Every CV diffable. Every PDF reproducible.

jsPDF/PDFKit (manual layout primitives) or React-PDF (parallel layout engine, its own flexbox subset, no real CSS)

The browser is the layout engine I need for 12 templates × palettes anyway — flex, grid, OpenType, hyphenation, print CSS. A jsPDF route would have meant reimplementing CSS in JavaScript for every feature I already get for free. React-PDF can carry part of the load, but @page, break-inside, OKLCH colours, and variable fonts are browser features. The price is shipping Chromium in the deploy artefact (~300 MB), paid deliberately. Web editor and CLI render the same pixels because they ask the same rendering engine — no layout drift between preview and export.

JSON Resume (JSON, single-locale, runtime locale switching) or a DB row behind SaaS auth

YAML is greppable, diffable, comment-friendly, copy-paste- friendly — and the only format choice that produces a git-native artefact. JSON Resume has the same data graph but loses comments and turns multi-locale into a clumsy story. A DB behind SaaS auth is the anti-thesis: the user hands their CV to a vendor who raises prices or sunsets the product tomorrow. Zod as a contract between YAML and template means a missing required block is caught at build, not at export. Locale-from-filename is a free default — anyone who explicitly sets meta.locale overrides it.

one package with src/cli, src/web, src/templates — everything in a single package.json

The split isn't a day-2 tidy-up, it's the architecture: cvmake-templates can publish without the CLI, the schema can be imported by third-party templates, the web editor builds on the same renderCV() as the CLI — no layout drift possible because there is only one render function. Turbo caches per package; a template edit doesn't rebuild the whole workspace. The price is the bootstrap complexity (workspace protocol, pinned versions, build order). You pay that price once; layout drift between two render paths charges interest on every edit.

@page { margin: 28mm 0 18mm 0 } and let Chromium render the top spacer itself

@page margin reserves space on every page including page 1 — the hero header shifts, the full-bleed sidebar gradient breaks. What I actually need is top breathing space from page 2 onward, not from page 1. Chromium also paginates each CSS grid track independently: a spacer div inside <main> does not push the sidebar children down, because the sidebar lives in its own track container. Solution: the spacer-injection code measures getBoundingClientRect of each child per container, finds the first child that would cross the page boundary, and inserts a div.cv-page-spacer before it. MAX_PAGES=12 as a safety cap so a degenerate layout can't loop the renderer hot forever.

passing Puppeteer a base URL and authoring templates against relative photo paths

page.setContent() ships with no base URL by default, so relative photo paths would point nowhere. Setting a base URL means either spinning up a local dev server (the CLI becomes an HTTP server) or juggling file:// paths (CI-specific, permission-flaky). The data URL is render-context-free: the same HTML string renders in CLI, CI, and web preview without any of the three environments making a server assumption. Idempotency: anyone who hands in a photo as a data URL already (e.g., from the web editor that encodes directly) gets it back unchanged — no double base64 layering.

staying git-clone-only (fork-or-nothing), or deploying the editor to a serverless platform

"Fork the repo" is a great contributor story and a poor first-PDF story — clone + install + build is ~5 minutes, npx is ~30 seconds. The CLI's three workspace deps force the publish all-four-or-nothing — cvmake-cli alone wouldn't resolve — so the four packages release in lockstep at one shared version and the cross-dependency contract stays trivial. The editor can't go serverless: Puppeteer wants a real Node process and a ~300 MB Chromium, so it is a container on a box, not a function. And a public editor cannot be the local-first editor — it was built to read and write cv.*.yaml on disk, but every visitor would clobber the same files. NEXT_PUBLIC_DEMO_MODE retrofits a stateless posture — example CVs only, no autosave, photo crop done entirely client-side, "Download YAML" instead of disk. The non-obvious trap: NEXT_PUBLIC_* vars are inlined at build time, so setting the flag only at container runtime split-brained the server (demo) against the client (not-demo) — it has to be set before next build.