137 lines
10 KiB
Markdown
137 lines
10 KiB
Markdown
# 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.
|