diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 41d80830..ed2bcd52 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -188,7 +188,14 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [x] B session texts never overwritten after a failed set-aside (owner UI choice: resolution panel + save-failure banner) (e34b7f2, a37c50b, c97b0e7): occupied slot refused, pair set-aside with rollback, `held` restore result, mirror on report change only, guarded new/import, discard + open-adapted behind confirmation, banner (draft or archive write refused); 27 new tests (app 346) - [x] gates: verifier 11/11 (floor false positive on `cli-latest`, clarified) + residual fixed; security PASS, 4 LOW fixed (archive refusal banner, download URL kept 30 s, header wording, comment); check:all green 1 min 29 s - [ ] follow-ups: UI for set-aside (quarantined) texts (owner: later); PDF export revokes its object URL at once (WebKit may cancel the download); "New report" replaces a readable draft without asking (unchanged, owner to decide if wanted); `writeCachedPractitioner` throws on a full localStorage before the report is created (no data loss) - - [ ] R3 anatomy core: tree, one sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas switched; composed views frozen as trees first + - [ ] R3 anatomy core (owner go 2026-10-14; branch feature/rust-r3-anatomy-core; plan `.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md` rev 2 after 3 challenges, 32 findings): prescan + tree + allowlist sanitiser + reference budget + serialiser + layer + canvas/highlight composition in `crates/core`; app canvas on `view.canvas`; denylist deleted + - [x] R3.0 freeze O1 canvas (47c5f49), O2 layer (969b872), O3 highlight (d1aa35e), O4/O5 sanitiser corpus (b440a2f, e316821), O6 Chromium references (scratchpad, 30/30 stable); roxmltree recursion measured (overflow < 3,000 levels on 1 MiB) → prescan (5f53aaa) + - [ ] R3.0b ANNOTATION-RENDERING.md to the code + - [ ] R3.1 svg prescan caps + tree + sanitiser + refs + number + serialiser (cargo O4/O5) + - [ ] R3.2 layer + compose + op view.canvas + per-asset outcome + wasm tests/thresholds + - [ ] R3.3 app switch + tests + - [ ] R3.4 Chromium visual + DOM dump + timings + memory + LAN + - [ ] R3.5 docs - [ ] R3.6 gates, stop for owner validation (no merge) - [ ] R4 pdf core: reader (Web Worker, BLK-009 browser measurements) + writer (`pdf-writer`, Std14 AFM, draw log; lines/rects/colours golden frozen with the TS engine first, D-R2) + `report-compare` tool; `packages/pdf` deleted; N-1 scanner reads R4 PDFs - [ ] R5 curation pipeline + importer + upload tool: seed golden regenerated once (new `documentSha256`, D-R5), `packages/anatomy` + `packages/domain` deleted, docs map; all before Step 13 - [ ] separate chore (D-R7): form constraints module + PGlite `pg_constraint`/config.toml parity test 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 index 944e0a6c..44f5459b 100644 --- a/.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md +++ b/.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md @@ -1,134 +1,136 @@ -# PLAN — Rust R3: anatomy core (SVG parse, tree, allowlist sanitiser, serialiser, layer, composition, highlight) and the editor canvas on it +# 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 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 +- 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 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. +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 (no visible change; each listed as a declared choice) +## 2. Decisions -- 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. +- 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. `` + 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 `` 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 `` 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 (R3.0, before any Rust or app change) +## 3. Oracles frozen with the TS code first (done before any change unless noted) -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). +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 + `` 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 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. +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. Deleted / kept +## 5. End criteria (review VI.2 R3, amended) -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). +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. Risks +## 6. Kept / deleted (consumers named) -- 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. +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.