10 KiB
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.mdII.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 fallback0 0 100 100; highlight per (annotation, view)).docs/ANNOTATION-RENDERING.mdrewritten 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):
- 2 MiB UTF-8 (
too_large); a leading BOM →malformed(xmldom parity). <!DOCTYPE/<!ENTITYanywhere, case-insensitive →doctype(engine rule); roxmltreeallow_dtd: falseas well.- 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,xmlnsdeclarations ≤ 16, raw<≤ 100,000 and=≤ 200,000 (roxmltree pre-allocates on those counts) →too_complex. - roxmltree
nodes_limit200,000 (never reached once 3 holds;too_complexif it is). - Serialised output ≤ 8 MiB (
too_large).
- 2 MiB UTF-8 (
- C3 Sanitiser = the TS allowlist, matched like the TS on qualified names (raw names from roxmltree
positions:
s:pathandx:hrefremoved, prefixed rootnot_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:
classandstyleremoved (inline SVG under page CSS: UI-redress risk, robustness 5);idvalues must match^[A-Za-z_][\w.:-]*$everywhere, else removed; stdDeviation: JSNumber()reproduced by hand (hex,Infinity,''→0, noinf/nan/_), JS printing of the clamped list;- reference graph (owner: internal references and
<use>complexity): edges fromhref/xlink:hrefand everyurl(#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-emptyremovedis refused at sheet load for the views on that asset (LRN-055: refuse, never repair).
- an element must also be in the SVG namespace (or none, xmldom's default):
- 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 \ras 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 refusesinvalid_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 onSheetIndex(constant string). Failure kinds:unknown_view,no_asset,svg_rejected(with the reason indetail),invalid_character. The sheet load sanitises each asset once into a per-asset outcome (tree or rejection);LoadedSheet.assetsstays the RAW text (snapshots archive it; r2 envelopes re-checked). - C7 App:
drawing.tsglue:index.ops.canvasView(viewId)→ DOMParserimage/svg+xml→parsererrorcheck →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:SheetSessiontreats only a closedinvalid_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)
- Step 6 view facts unchanged (engine untouched); O2 exact, O3 and O1 tree-equal on the core.
- O4 every row equal or declared; O5 zero removal and tree-equal on the 4 product SVGs.
- One sanitiser for the canvas: no
sanitizeSvg/parseDrawing/@faunosteo/anatomyinapps/app/src(grep) and no@faunosteo/anatomyinapps/app/package.json; the engine keeps its own until R4 (VI.2 item amended). - 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.canvasmain ≤ 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. - Visual: 0-diff on the 30 captures (any non-zero diff analysed and reported, never waved through).
- Served module ≤ 600 KB gzip; app, core-wasm, cargo, pgTAP suites green;
pnpm check:allgreen.
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.