Render Environment Preflight

The failure

Document generation is one of the last places "works on my machine" survives, because the thing that differs isn't code. The invoice is perfect locally. On the server the typeface is wrong, the table wrapped to three pages, and the total moved onto its own page. Nothing threw.

• The font isn't installed. Headless containers ship almost none. The renderer substitutes,
• metrics change, the layout reflows — and substitution is the specified behaviour, so there is
• no error to catch.
• Emoji and CJK come from separate fonts. Fine in English on a full font stack, tofu boxes in
• a container.
• Page size defaults differ. A4 vs Letter is ~6mm of width, enough to overflow a tuned table.
• prefers-color-scheme resolves to dark in some headless setups — white on white, which
• reads as a blank page rather than a bug.
• Timezone and locale change the dates and separators inside the content.

  const problems = preflight(env, needs);
  renderable(problems); // false
  // [{ severity: "blocking", code: "font_missing",
  //    detail: "Inter is not installed. The renderer will SUBSTITUTE silently — metrics change,
  //             the layout reflows, and nothing errors, so the pipeline reports success on a
  //             wrong document" }]

A missing font is blocking, not a warning. Anything that reflows layout without erroring has to stop the run, or it isn't noticed until a customer reads the invoice.

A present family with a missing weight is blocking too: synthetic bolding has different metrics from a real bold face, so headings reflow even though the family "exists".

Explaining a render that already went wrong

  diffManifests(a, b);
  // [{ field: "fontsUsed", layoutAffecting: true,
  //    detail: "different fonts were actually used; only in B: liberation sans. This is a
  //             substitution, and it is the single most likely explanation for a layout that moved" }]

fontsUsed is the field most pipelines don't record, and it's the one that matters. Installed fonts tell you what was available; used fonts tell you what the engine picked. If your engine can report it, record it on every render — it turns a day of bisecting into one line of output. When it's absent on either side, this says substitution cannot be ruled out rather than quietly clearing it.

Differences are sorted layout-affecting first, and page count is labelled a **symptom, not a cause**.

What it does not do

| not included | why | |---|---| | Rendering anything | a rendering engine is exactly the dependency you don't want in a CI check | | Installing fonts | it tells you which are missing; provisioning is your Dockerfile's job | | Comparing output pixels | visual regression is a different tool and a heavier one | | PDF parsing | pdf-manual-parse, pdf-reading-order |

The font list is whatever your environment reports. If it lies — some containers report families they can't actually shape — this inherits that, and the manifest diff is your fallback.