docs: record empirically verified Typst behaviour (0.15.1)

2026-08-27 09:06:23 +02:00
parent 5a76acdfbc
commit 2f7db0e4fd
1 changed files with 51 additions and 0 deletions
@@ -0,0 +1,51 @@
+# Typst behaviour — verified empirically
+
+Everything here was tested against the real binary (**typst 0.15.1**, `9dfd3a08`), not
+inferred from documentation. Re-run these checks if the pinned Typst version changes.
+
+## Confirmed
+
+| Claim | Result |
+|---|---|
+| `--format` / `--ppi` / `--input` / `--font-path` / `--ignore-system-fonts` / `--pdf-standard` / `--root` / `--pages` all exist | ✅ present in `typst compile --help` |
+| `#set page(bleed: 3mm)` emits a real PDF **TrimBox** | ✅ `/TrimBox [8.503937 8.503906 850.3937 1199.0552]` |
+| A3 trim geometry is exact | ✅ TrimBox = 841.89 pt = **297.0 mm**; MediaBox 858.9×1207.6 pt = **303×426 mm** |
+| `json(sys.inputs.specfile)` reads the spec as data | ✅ |
+| `context measure()` bisection auto-fit | ✅ compiles and fits |
+| `gradient.linear(...)` for scrims | ✅ |
+| Italian accents and `« »` | ✅ `à è é ì ò ù` render correctly |
+| Variable-font axes at render time | ✅ `text(variations: (wdth: 62, wght: 700))` with `Archivo[wdth,wght].ttf` |
+
+The variable-axis result matters: it means the auto-fit routine can **narrow** a long
+Italian title on the `wdth` axis before falling back to shrinking it, which preserves a
+poster's optical weight. That strategy is viable, not theoretical.
+
+## ⚠️ Corrections to earlier assumptions
+
+**1. PNG export renders the TRIM page, not the bleed page.**
+
+```
+typst compile poster.typ out.png --format png --ppi 300
+  -> 3508x4961 px   (A3 trim @300dpi)
+  NOT 3579x5032 px  (A3 + 3mm bleed @300dpi)
+```
+
+So: **PDF carries the bleed and the TrimBox; PNG comes out already trimmed.** This is
+convenient rather than a problem — screen/social output wants the trimmed image, and the
+print path uses the PDF anyway — but the renderer must not assume the two are the same
+size, and must not try to obtain a bleed area as PNG.
+
+**2. Output is byte-reproducible without `SOURCE_DATE_EPOCH`.**
+
+Two compiles a second apart produced byte-identical PDFs *with and without* the env var,
+because `#set document(date: none)` already removes the only nondeterministic field.
+Keep setting `SOURCE_DATE_EPOCH=0` anyway — it costs nothing and protects against any
+future field that does read the clock — but the load-bearing directive is
+`#set document(date: none)` in every template. Golden-file tests are therefore sound.
+
+## Reproducing
+
+```bash
+typst compile probe.typ probe.pdf --input specfile=spec.json --root .
+python3 -c "import re;d=open('probe.pdf','rb').read();print(re.search(rb'/TrimBox\s*\[([^\]]*)\]',d).group(1))"
+```