From fbc9526e57a6aea65b00800b88418d8fb1684485 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 14 Oct 2026 23:21:08 +0200 Subject: [PATCH] chore(chore): R3 plan rev 1 --- .../plans/2026-10-14-rust-r3-anatomy-core.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 .claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md diff --git a/.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md b/.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md new file mode 100644 index 00000000..944e0a6c --- /dev/null +++ b/.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md @@ -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 ``), 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`); + - ``: 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 ` 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`, 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 `` + 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 `` 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.