Files
faunosteo/.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md

10 KiB
Raw Permalink Blame History

PLAN — Rust R3: anatomy core (SVG prescan, parse, tree, allowlist sanitiser, serialiser, layer, composition, highlight) and the editor canvas on it

  • date: 2026-10-14 | rev 2 (after 3 plan challenges: correctness FATAL(3), robustness FATAL(6), simplicity CONCERNS(4); 32 findings folded) | branch: feature/rust-r3-anatomy-core
  • spec: owner brief 2026-10-14 §2–§12; docs/development/RUST_ARCHITECTURE_REVIEW.md II.2 rows "anatomy render" + "pdf svg / drawing.ts denylist", VI.2 R3, VI.4; CLAUDE.md "Rust by default", "Annotation rendering"; facts: scratchpad r3-render-facts.md, r3-sanitiser-facts.md
  • not in scope: R4 (the TS PDF engine keeps its TS sanitiser and composeViewSvg; no facade op for the highlight), R5 (pipeline, review byte goldens), any visible change, release 0.2.0, deployment

1. Outcome

The editor canvas (main view, detail modal) draws a string the core composed from the loaded sheet: the sanitised asset + the annotation layer, no state. The app keeps DOMParser, importNode, replaceChildren, the in-place data-state restyle (it runs right after every build already), click and tooltip delegation, the CSS. Deleted: the denylist sanitizeSvg, parseDrawing, the parse cache, statesRef, the app's dependency on @faunosteo/anatomy. The highlighted composition the engine needs at R4 exists in the core as a function over (document, sanitised tree, view, highlight), proven against the TS freeze in cargo, not exposed through the facade (R4 designs its own snapshot-based call, review II.2 row "pdf writer").

2. Decisions

  • C1 Behaviour = the code where the doc differs (trigger without a name: both name attributes = the opened view's FR name; shape by geometry type; twin radius max(2, r-12); canvas viewBox fallback 0 0 100 100; highlight per (annotation, view)). docs/ANNOTATION-RENDERING.md rewritten FIRST to describe the code (no rendering change). Follow-up for the owner: EN name of an unnamed trigger.
  • C2 Resource bounds, in order, before any parser (robustness 1/2, correctness 1; roxmltree 0.21.1 recurses per nesting level: measured overflow of a 1 MiB stack between 1,000 and 3,000 levels; fixed only in unreleased git):
    1. 2 MiB UTF-8 (too_large); a leading BOM → malformed (xmldom parity).
    2. <!DOCTYPE/<!ENTITY anywhere, case-insensitive → doctype (engine rule); roxmltree allow_dtd: false as well.
    3. Markup prescan (hand-written state machine, no regex: comments, CDATA, PIs, quoted values skipped): depth ≤ 64 (too_deep), elements ≤ 20,000 counted on the raw text (removed subtrees included: declared tighter), attributes per element ≤ 256 and in total ≤ 100,000, xmlns declarations ≤ 16, raw < ≤ 100,000 and = ≤ 200,000 (roxmltree pre-allocates on those counts) → too_complex.
    4. roxmltree nodes_limit 200,000 (never reached once 3 holds; too_complex if it is).
    5. Serialised output ≤ 8 MiB (too_large).
  • C3 Sanitiser = the TS allowlist, matched like the TS on qualified names (raw names from roxmltree positions: s:path and x:href removed, prefixed root not_svg, a root without namespace accepted as SVG), with these declared differences (each an O4 row with both verdicts; none touches a product SVG):
    • an element must also be in the SVG namespace (or none, xmldom's default): <path xmlns="evil"> removed (TS keeps it);
    • comments and PIs dropped (TS keeps them), not listed as removals; non-whitespace text kept only inside title/desc (never rendered elsewhere; robustness 11);
    • root element: class and style removed (inline SVG under page CSS: UI-redress risk, robustness 5); id values must match ^[A-Za-z_][\w.:-]*$ everywhere, else removed;
    • stdDeviation: JS Number() reproduced by hand (hex, Infinity, ''→0, no inf/nan/_), JS printing of the clamped list;
    • reference graph (owner: internal references and <use> complexity): edges from href/ xlink:href and every url(#id) (fill, stroke, clip-path, mask, filter, style) to the first element holding that id (document order, like browsers); a cycle → reference_cycle; the expanded element count (each edge adds its target's expanded subtree, saturating, iterative, early exit) ≤ 50,000 → too_complex. Dangling references are left alone (no rendering change; simplicity 3a). The TS <use> count cap 256 is kept.
    • removal policy unchanged (dropped + named in removed); a product asset with a non-empty removed is refused at sheet load for the views on that asset (LRN-055: refuse, never repair).
  • C4 Tree: own arena (roxmltree borrows its input), elements (local name, namespace, qualified name, attributes in source order, children), text; recursion allowed after the depth cap (64). Serialiser: XML 1.0, attributes escape & < > " and \t \n \r as character references, text escapes & < > and \r; namespace declarations re-emitted where the source declared them; no XML declaration. A code point XML 1.0 forbids in a layer input (label, d) → compose refuses invalid_character (never replaced; today's DOM path would draw it, the string path cannot).
  • C5 Numbers printed with js_number; Math.max(2, r-12) in f64.
  • C6 Facade: one op on the sheet handle, view.canvas { viewId } → { svg }, called once per (sheet, view) and memoised on SheetIndex (constant string). Failure kinds: unknown_view, no_asset, svg_rejected (with the reason in detail), invalid_character. The sheet load sanitises each asset once into a per-asset outcome (tree or rejection); LoadedSheet.assets stays the RAW text (snapshots archive it; r2 envelopes re-checked).
  • C7 App: drawing.ts glue: index.ops.canvasView(viewId) → DOMParser image/svg+xml → parsererror check → document.importNode(root, true). On failure the canvas retries once (the runtime recovers a trapped instance on the next call), then shows the existing degraded notice (sheet.core_unavailable + sheet.core_retry, existing component) inside the canvas; the retry rebuilds. Runtime hardening: SheetSession treats only a closed invalid_sheet: refusal as such and poisons the instance on any other throw (robustness 9).
  • C8 Budget: served module ≤ 600 KB gzip; a jump > 60 KB gzip reported before keeping it.

3. Oracles frozen with the TS code first (done before any change unless noted)

O1 canvas: buildViewSvg (happy-dom) full tree with no state per view + the layer for every state set of the three reports (done, 47c5f49). After the switch: AnatomyCanvas mounted with each state set, its DOM compared to the frozen trees. O2 layer trees with attribute order: draft + edge document (done, 969b872). O3 highlighted compositions as trees (text nodes included): 36 cases incl. an existing nested <defs> and an own-asset detail view without viewBox (done, d1aa35e). O4 sanitiser verdicts and sanitised trees on the hostile corpus (32 files + 10 generated specs) (done, b440a2f, e316821); Rust rows: equal, or declared (C2/C3) with the Rust verdict asserted; a Rust verdict looser than the TS fails unless declared. O5 product SVGs (horse, paws, public logos): Rust output serialised, re-parsed, compared with the TS sanitised tree (namespace declarations kept as declared) (frozen in O4's legitimate). O6 Chromium: screenshots before/after on the same Chromium, uncommitted, 0-diff expected, the method's own noise floor measured (before/before: 30/30 identical, done); the classifier only reports, a non-zero diff is analysed. Plus one live-DOM dump of the canvas in Chromium compared with O1.

4. Phases

R3.0 freeze (done) + ANNOTATION-RENDERING.md rewritten to the code. R3.1 core anatomy/svg/{prescan,tree,sanitize,refs,number,serialize}.rs; cargo: prescan caps, hostile corpus (O4), product SVGs (O5), deep/flood/namespace/attribute cases. R3.2 core anatomy/{layer,compose}.rs: O2 exact (order), O3 tree-equal, canvas composition equal to O1's frozen base; LoadedSheet per-asset outcome; op view.canvas; ts-rs types; core-wasm tests on the shipped module: the corpus through wasm with no trap, thresholds below. R3.3 app switch (C7), denylist and dependency deleted, AnatomyCanvas/EditorRoute/DetailModal suites, O1 on the mounted canvas, hostile bundled sheet through the real core (correctness 9). R3.4 Chromium: O6 after, DOM dump, timings on pnpm preview:draft (4× CPU throttle), 50 detail open/close cycles memory, one forced trap; LAN desktop + phone check. R3.5 docs: RUST.md §9, CLAUDE.md, CHANGELOG, PDF_IMPORT_HARDENING.md (reference budget exists in the core, engine switch at R4), review VI.4 status. R3.6 gates: pnpm check:all, fresh verifier, security-auditor; stop for the owner's validation.

5. End criteria (review VI.2 R3, amended)

  1. Step 6 view facts unchanged (engine untouched); O2 exact, O3 and O1 tree-equal on the core.
  2. O4 every row equal or declared; O5 zero removal and tree-equal on the 4 product SVGs.
  3. One sanitiser for the canvas: no sanitizeSvg/parseDrawing/@faunosteo/anatomy in apps/app/src (grep) and no @faunosteo/anatomy in apps/app/package.json; the engine keeps its own until R4 (VI.2 item amended).
  4. Thresholds (shipped wasm, Node): every hostile case answers a closed outcome with no trap, ≤ 150 ms each, wasm memory growth over the whole corpus ≤ 32 MiB; view.canvas main ≤ 15 ms warm. Chromium preview build, 4× CPU: first canvas paint after the core is ready ≤ 300 ms, detail open ≤ 150 ms; 50 open/close cycles: wasm memory flat after the first, JS heap growth ≤ 5 MB.
  5. Visual: 0-diff on the 30 captures (any non-zero diff analysed and reported, never waved through).
  6. Served module ≤ 600 KB gzip; app, core-wasm, cargo, pgTAP suites green; pnpm check:all green.

6. Kept / deleted (consumers named)

Deleted: drawing.ts denylist + parseDrawing + cache, apps/app → @faunosteo/anatomy dependency, statesRef. Kept: packages/anatomy/src/render/** (engine R4, pipeline R5), packages/pdf/src/svg/** (engine R4), browserRasterizer.ts (DOM adapter), the TS oracle generators (R4/R5 need them).

7. Risks

  • happy-dom vs Chromium tree differences: covered by the Chromium DOM dump.
  • New degraded state inside the canvas (C7) reuses an existing notice; reported to the owner.
  • Declared stricter rules could refuse a future Step 13 upload: each is a closed reason, logged in the review for Step 13.