The legacy seam program — modularize crates/grida for v2 promotion

[softmarshmallow]

Status — 2026-07-18

Umbrella for the legacy seam program: reorganizing crates/grida into modular, model-agnostic shape so the v2 engine promotion (#9) consumes modules, not forks. Migration by extraction, not reimplementation.

All work lands on main. The model-v2-anchor branch is locked — design reference only. Its WG spec overlay is landed on main by #26; those specs are what the seams build against.

Thesis

The legacy engine is already mostly IR-mediated. v1-model entanglement is confined to three choke points:

1. crates/grida/src/import/svg/pack.rs — walks the existing IRSVG IR but emits v1 node schema records directly.
2. crates/grida/src/import/html/mod.rs — walks Stylo ComputedValues and emits v1 records directly (no IR; duplicates the htmlcss cascade front-end verbatim).
3. The painter's model→display-list compilation (painter/layer.rs, geometry.rs, painter_debug_node.rs) — the draw loop itself has zero model references.

Already agnostic: the htmlcss/ renderer (own StyledElement→LayoutBox→Skia pipeline), the cg/ leaf vocabulary (one skia From impl from standalone), Skia-textlayout shaping, and the foundation crates (math2, csscascade, fonts).

Each seam gets: a name first, an architecture test locking the boundary, behavior-preserving refactors, and pixel/snapshot gates. The v2 engine is treated as a foreign consumer we cannot rewrite — contracts stay agnostic, never legacy-shaped or v2-shaped.

The deciding rule (standing doctrine for this program)

A module becomes a workspace crate when its second consumer appears in the workspace — and not before. Until then it stays an in-crate module whose boundary is locked by an architecture test enforcing the same import rules cargo would enforce after extraction, so extraction later is a git mv plus a Cargo.toml, not a design event.

Naming exercises are per-extraction gates (the name comes first), scheduled at extraction time — not now.

Milestones

Milestone	Contents	Status
M0 — bootstrap	WG spec overlay on main (#26); this issue + seam issues; gate baseline recorded (comment below)	done
M1/M2 — mechanical seams	cg decouple (#34); SVG sink inversion (#35); HTML gate + front-end share (#36, #41)	done
M3 — design tracks	resolved-text artifact (#40); paint/display-list vocabulary RFDs (#38); painter narrowing (#39)	done
M4 — extraction-readiness review	per candidate module: dependency closure verified, governing spec on main, naming exercise scheduled	done — see the M4 comment

Seam issues (each carries its exit criterion and gate commands): filed as follow-ups and linked in the checklist below.

• seam: cg/ skia decouple + architecture lock #28 — cg/ skia decouple + architecture lock
• seam: SVG sink inversion — the IR is the product, pack.rs is the v1 adapter #29 — SVG sink inversion (IR is the product; pack.rs is the v1 adapter)
• seam: HTML importer — snapshot gate + shared cascade front-end #30 — HTML importer: snapshot gate + shared cascade front-end
• seam: painter narrowing — one compiler module owns the model #31 — Painter narrowing (one compiler module owns the model)
• seam: resolved-text artifact conformant to the text-layout RFD #32 — Resolved-text artifact (conformant to the text-layout RFD)
• spec: paint / display-list vocabulary (feat-painting RFD + feat-2d study) #33 — Paint / display-list vocabulary (spec-first, docs/wg/feat-painting/)

Gate baseline

Recorded in a comment below after the baseline run. Every seam's exit criterion appends "…and the M0 baseline is unchanged."

• cargo test -p grida
• cargo run --release -p grida_dev -- reftest run --suite-dir fixtures/local/resvg-test-suite --renderer iosvg --threshold 0.1 (⚠️ iosvg, not the reftest-run.sh default htmlcss — the htmlcss renderer bypasses pack.rs entirely)
• grida_wpt fixtures/test-html/suites/L0.exact.json at 100% vs the Chromium oracle
• @grida/canvas-wasm builds (crates/grida-canvas-wasm && just build)

Non-goals (locked for the whole program)

• No format/grida.fbs changes (the SCHEMA_VERSION lockstep with gridaco/grida holds; see The engine migration — history & the consolidation guideline (residue from gridaco/grida) #1).
• No wasm-surface changes — @grida/canvas-wasm publishing is untouched throughout.
• No type reshaping of Paint/Stroke/Color/TextStyleRec — vocabulary convergence is spec-first work whose implementation belongs to the promotion program.
• No geometry-IR convergence (v2 PathArtifact vs legacy d: String) — no legacy-side choke point exists; doing it now would be v2 promotion in disguise.
• No tree-level HTML convergence (importer consuming collected StyledNode trees / LayoutBox) — baked positions and inline-merge semantics are intentional pixel changes, out of scope.
• No edits to model-v2/** — the branch is locked.

References

• The engine migration — history & the consolidation guideline (residue from gridaco/grida) #1 — the migration anchor & consolidation guideline (this program is main-side motion under its rules)
• anchor — the v2 node model #9 — the v2 node model these seams serve
• docs(wg): land the model-v2 spec overlay from model-v2-anchor #26 — the M0 spec overlay

[softmarshmallow]

M0 gate baseline — recorded 2026-07-18, main @ 90eb144

Gate	Result
cargo test -p grida	green — 828 lib tests + all integration suites (incl. svg_pack and the two htmlcss architecture/checkpoint suites) + 31 doctests; 0 failed
iosvg reftest, fixtures/local/resvg-test-suite	1679 fixtures rendered; avg similarity 71.45% (min 2.38 / max 100.00); oracle buckets: consensus n=1425 avg 0.744, passing@0.95 = 703 (49.33%); disputed n=193; ub n=61 excluded
grida_wpt L0.exact	65 fixture PNGs rendered from fixtures/test-html/suites/L0.exact.json
@grida/canvas-wasm	just build green (CJS + ESM bundles emitted)

How the seam gates use this: the full rendered PNG trees for both suites (plus report.json) are captured as the byte-diff reference. A seam PR passes its pixel gate when its re-render is byte-identical — a stronger bar than score-compare, and independent of oracle availability. (The Chromium-oracle scoring for L0.exact needs a Chrome bake, which is not present on this machine; byte-identity trivially preserves whatever similarity held at this baseline.)

Baseline artifacts are machine-local (per the fixtures doctrine, fixtures/local/** and render outputs are not tracked); any machine can reproduce the reference by running the commands in the issue body at 90eb144b.