chore(chore): R3 plan rev 1

This commit is contained in:
bchanot committed 2026-10-14 23:21:08 +02:00
1 parent aab61c2fe1
commit fbc9526e57
1 file changed
+134
@@ -0,0 +1,134 @@
# PLAN — Rust R3: anatomy core (SVG parse, tree, allowlist sanitiser, serialiser, layer, composition, highlight) and the editor canvas on it
- date: 2026-10-14 | rev 1 | branch: feature/rust-r3-anatomy-core (off develop after the R2 maintenance merge)
- 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 end criteria, VI.4 deletions; 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`), R5 (pipeline, review byte goldens `draft/review/app-*.svg`), any visible change, release 0.2.0, deployment
## 1. Outcome
The editor canvas (main view, detail modal) draws a string the Rust core composed from the sheet handle:
sanitised asset (allowlist) + annotation layer (markers from the document) + states. The app keeps
DOMParser, `importNode`, `replaceChildren`, the in-place `data-state` mutation, click and tooltip
delegation, the CSS. The denylist (`drawing.ts` `sanitizeSvg`), `parseDrawing` and the parse cache are
deleted. The core also carries the highlighted composition the PDF engine will use at R4
(`highlight`, halo filter), proven against trees frozen from the TS engine now, but not wired.
## 2. Decisions (no visible change; each listed as a declared choice)
- C1 Behaviour = the code, not the doc where they differ (trigger EN name = opened view's FR name when
the trigger has no name; shape by geometry type; twin radius `max(2, r-12)`; app viewBox fallback
`0 0 100 100`; states keyed by annotation id across views for the canvas, by (annotation, view) for the
highlight). `docs/ANNOTATION-RENDERING.md` rewritten FIRST to describe the code (D1–D9 of the facts),
no rendering change; the EN trigger name is listed as a follow-up question for the owner.
- C2 One sanitiser in Rust, TS-parity on the existing allowlist (28 elements, 74 attributes, value rules,
stdDeviation clamp 100, caps 20,000 elements / depth 64 / 256 `<use>`), strictly tighter where the TS
is lax (each a declared difference, none affects the runtime assets):
- namespace-aware: elements must be in the SVG namespace, attributes unqualified or `xlink:href`
(xlink namespace whatever its prefix), `xmlns`/`xmlns:xlink` declarations re-emitted by the
serialiser; a foreign-namespace element is removed like an unknown one;
- comments, processing instructions and CDATA are dropped (listed as removed `#comment`, `#pi`;
CDATA text kept as text); none in the runtime assets;
- `style`: parsed as declarations; property allowlist = the 27 presentation properties + `cursor`;
a declaration outside it, or a value with a function other than `url(#…)`, or a backslash → the
whole attribute removed (TS removes on `(` / backslash and keeps any property);
- internal references: `href`/`xlink:href`/`url(#id)` must name an existing element id; a dangling
one removes the attribute (listed); duplicate ids → document refused (`duplicate_id`);
- `<use>`: reference graph checked for cycles (`use_cycle`) and expansion budget (instances counted
through nested references, cap 10,000 → `use_budget`); refused whole;
- resource bounds in this order: (1) 2 MiB UTF-8 byte cap before anything (`too_large`);
(2) DOCTYPE/ENTITY refused by the TS rule (text contains `<!DOCTYPE` / `<!ENTITY`,
case-insensitive) before parsing, and again by roxmltree `allow_dtd: false`; (3) roxmltree with
`nodes_limit` 50,000 (elements + text + comments + PIs): its parser is iterative, no entity
expansion without a DTD, so parse time and memory are linear in the capped input and stop at the
node limit (`too_many_elements`); (4) depth > 64 and elements > 20,000 checked on the parsed tree
BEFORE any sanitising walk, every later walk iterative. roxmltree's tokenizer is private, so no
separate tokenizer pre-pass; no regex is used for structure. Hostile inputs measured (deep
nesting at the byte cap, node flood, attribute flood) with times recorded.
- Removal policy kept from the TS: an unknown element/attribute is dropped and its name returned in
`removed` (R4 needs the same output); the runtime assets are pinned at zero removal by tests (cargo
and app), so any future conflict is a test failure, never a silent drop at runtime. The app logs
nothing to the user: a non-empty `removed` on the bundled sheet cannot ship (test gate).
- C3 Tree = own arena (`Vec<Node>`, element: name + namespace + ordered attributes + children; text),
built from roxmltree; every walk iterative (explicit stack), depth already bounded.
- C4 Serialiser: XML 1.0, attribute values escape `& < > "`, text escapes `& < >`, empty element
self-closed, root carries `xmlns` and `xmlns:xlink` (when an xlink attribute exists), no XML
declaration. Output parsed back by the browser = the same tree (tested in happy-dom and Chromium).
- C5 Numbers: `js_number` for every coordinate the layer prints (ECMAScript `Number::toString`),
`Math.max(2, r-12)` computed in f64 then printed with `js_number`.
- C6 Facade, on the sheet handle (one call per build, never in a render path):
- `view.canvas { viewId, states: [annotationId] }` → `{ svg }`: the canvas composition (fresh root =
sanitised asset root attributes except width/height, viewBox = view_box ?? asset's ?? `0 0 100 100`,
asset children, layer with `data-state="current"` on the stated ids);
- `view.highlighted { viewId, annotationIds, halo }` → `{ svg, viewBox }` (engine semantics; R4);
- free `svg.sanitize { text }` → `{ svg, removed }` (branding at R4, tests).
The sheet load sanitises every asset once (eager, in `LoadedSheet`): a rejected asset makes the
sheet `invalid_sheet` (existing degraded state); the sanitised tree is kept and composed per call.
Closed failure kinds added: `unknown_view`, `no_asset`, `svg_rejected` (with `reason`:
doctype, malformed, not_svg, too_large, too_many_elements, too_deep, too_many_uses, duplicate_id,
use_cycle, use_budget).
- C7 App: `drawing.ts` becomes glue: `index.ops.canvasView(viewId, states)` → DOMParser
(`image/svg+xml`) → `parsererror` check → `document.importNode(root, true)`. A core failure leaves
the canvas empty with the existing `core.action_failed`-style notice (no throw in an effect).
`AnatomyCanvas` unchanged otherwise.
- C8 Budget: roxmltree 0.21 (MIT/Apache, deps memchr only) measured on the wasm before the
sanitiser lands; served module target ≤ 600 KB gzip; any jump > 60 KB gzip reported before keeping.
## 3. Oracles frozen with the TS code first (R3.0, before any Rust or app change)
O1 canvas trees: `buildViewSvg` (happy-dom) for main and head × state sets {none; each observation of
demo / v2full / v2unresolved as the active observation; every annotation} → normalised tree JSON
(namespace, local name, attributes as a sorted map with prefixed names, children incl. text nodes)
under `apps/app/tests/fixtures/goldens/r3/canvas.*.json`.
O2 layer trees: `renderAnnotationLayer` (main, head, with and without states; mini-sheet edge cases:
null geometry, null colour, r=3 twin floor, path geometry, circle trigger, polygon point) → JSON
with attribute ORDER kept, `crates/core/tests/oracles/r3/layer.*.json`.
O3 highlighted compositions: `renderHighlightedView` for every (report, observation, view) of the three
reports + an asset with an existing `<defs>` + a detail view with its own asset → normalised trees +
viewBox, `crates/core/tests/oracles/r3/highlight.*.json`.
O4 sanitiser verdict table: the 7 existing hostile cases + the new corpus (namespaces, comments/PI/CDATA,
style CSS, dangling refs, duplicate ids, use cycle, use budget, depth 65, 20,001 elements, 2 MiB + 1,
BOM, xml:space, data: href, animate/set, foreignObject, image, script in attribute values, entity
expansion) run through the TS sanitiser → `{ rejected | removed[] }` frozen; Rust must equal it on
every case the TS handles the same way, the tighter cases are listed with the Rust verdict.
O5 zero-removal set: horse.svg (draft), paws-in-harmony.svg, apps/app/public/*.svg: Rust `removed` = []
and the sanitised tree equals the parsed source tree (tree compare).
O6 visual references: real Chromium (playwright-core outside the repo, cached chromium) on `pnpm dev`
at the DEV origin: editor main canvas and head modal, desktop 1280×800 and phone 390×844, states
none / each demo observation / hover on a point → PNGs under
`apps/app/tests/fixtures/goldens/r3/visual/`; comparison script `scripts/visual-canvas.mjs`
(exact pixels first; a non-zero diff is classified: anti-aliasing = isolated pixels on edges with
delta ≤ a stated threshold, otherwise a regression).
## 4. Phases
R3.0 freeze O1–O6 with the TS code (commit before any change).
R3.1 Rust `crates/core/src/anatomy/`: `svg/{prescan,tree,parse,sanitize,serialize,refs}.rs`,
`layer.rs`, `compose.rs`; cargo tests: O2 exact, O3 tree-equal, O4, O5, caps, hostile, property
tests on serialise→parse round trip.
R3.2 facade ops + handle cache + ts-rs types; wasm tests (core-wasm vitest) on the real module;
size measured.
R3.3 app switch: `drawing.ts` glue, denylist deleted; app suites: AnatomyCanvas (O1 tree-equal for every
frozen case), EditorRoute click chain, DetailModal, pdf roundtrip untouched (engine still TS).
R3.4 visual comparison in Chromium vs O6; LAN run desktop + phone viewports; timings (compose call,
DOMParser, first canvas), memory after the editor path.
R3.5 docs: ANNOTATION-RENDERING.md (first, at R3.0), RUST.md §9 (R3), CLAUDE.md map, CHANGELOG,
PDF_IMPORT_HARDENING.md (the `<use>` budget item now exists in the core, engine switch at R4),
review VI.4 status.
R3.6 gates: `pnpm check:all`, fresh verifier (contract), security-auditor, plan stop for the owner's
LAN validation (TEST FONCTIONNEL / TEST GRAPHIQUE), no merge.
## 5. Deleted / kept
Deleted at R3: `apps/app/src/anatomy/drawing.ts` denylist + `parseDrawing` + parse cache, app imports of
`@faunosteo/anatomy/render` (the app no longer imports the TS renderer; ESLint rule added).
Kept (consumers named): `packages/anatomy/src/render/**` (TS engine until R4, pipeline until R5),
`packages/pdf/src/svg/**` (engine until R4), `browserRasterizer.ts` (DOM adapter, C).
## 6. Risks
- Tree equality with happy-dom differs from the browser (namespaces of attributes, whitespace): proven
again in Chromium by the visual run and a DOM dump compare.
- Whitespace text nodes: the asset has 702; the canvas imports them; the serialiser must keep them.
- roxmltree normalises attribute values (newline → space per XML spec) and line endings; the asset has
none (no CR, no tab) — pinned by O5.
- wasm size; compose cost per detail open (≈ 140 KB string + DOMParser): measured, cached sanitised tree.