tests: fix root-relative spec path; document ink-surface blocker

2026-08-27 09:25:34 +02:00
parent cf7f0aa386
commit 5fabf5345f
12 changed files with 6270 additions and 1 deletions
@@ -0,0 +1,51 @@
+# Open defects found by the fixture harness
+
+## 1. BLOCKER — ink colour ignores what is actually behind the text
+
+**Symptom.** In `framed` and on the flat panel of `split`, body text renders white on the
+cream `palette.bg` (`#f4efe6`) and is essentially illegible. Reproduce with:
+
+```bash
+tests/render-fixtures.sh /path/to/typst
+# then look at tests/out/framed__accents.png and split__landscape.png
+```
+
+**Cause.** `templates/lib.typ:61`, in `palette-of()`:
+
+```typst
+let ink = hex(_get(spec, "ink_resolved", _get(p, "ink", none)), fallback: rgb("#111111"))
+```
+
+`ink_resolved` **always** wins over `palette.ink`. But `ink_resolved` is measured by
+`render/contrast.ts` against the **artwork**. That is correct only for text sitting over
+the artwork. Templates that place text on flat colour — `framed` entirely, `split` on its
+colour half — inherit an ink chosen for a completely different surface. `split.typ:7`
+already carries a comment noticing the tension.
+
+**Fix.** Contrast must be resolved per *surface*, not once per poster:
+
+- Extend `ResolvedSpec` with `ink_on_art` (measured, today's `ink_resolved`) and
+  `ink_on_bg` (checked against `palette.bg`; `design/palettes.ts` already guarantees every
+  palette meets 4.5:1, so this is normally just `palette.ink`).
+- Add `ink-for(spec, surface)` to `lib.typ`, where surface is `"art"` or `"bg"`, and have
+  each template ask for the surface its text actually sits on.
+- Keep `ink_resolved` as a deprecated alias so nothing breaks mid-migration.
+- `resolveSpec()` in `render/typst.ts` must populate both.
+
+Add a fixture whose artwork is dark and whose `palette.bg` is light — the case where a
+single ink cannot possibly satisfy both surfaces — so this cannot regress silently.
+
+## 2. Gotcha (fixed in the harness, must hold in `render/typst.ts`)
+
+Typst resolves a leading `/` against `--root`, **not** the filesystem. Passing an absolute
+path to `--input specfile=...` yields `<root>/home/you/...` → "file not found". The spec
+path must be **root-relative**. Same rule applies to `art_file` and every `font_files`
+entry.
+
+## Confirmed working
+
+- A3 trim geometry exact: TrimBox 297.0 × 420.0 mm inside a 303 × 426 mm MediaBox.
+- Italian typography: `PERCHÉ`, `È COSÌ`, `CITTÀ`, `SANT'ANNA`, `FORLÌ`, `«PIAZZA GRANDE»`.
+- Auto-fit: a 92-character title shrinks and wraps rather than overflowing.
+- `split` genuinely adapts to landscape (art left / text right) rather than assuming portrait.
+- 18/18 template × fixture combinations compile.