pi-imgen/docs/OPEN-DEFECTS.md

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:

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():

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.