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

137 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.