chore(chore): R3 plan rev 1
This commit is contained in:
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.
|
||||
Reference in new issue
Block a user