docs(docs): R3 in RUST.md §9, CLAUDE.md, CHANGELOG, PDF import gate note, packages README
This commit is contained in:
1 parent
967c71c31e
commit
d6b5edb626
5 files changed
+177
-12
No files matched your search
@@ -109,6 +109,9 @@ hides its `/Keywords`, so a stripped attachment on such a file reads as
|
||||
observation) so a hostile report cannot freeze the editor before the
|
||||
export's own caps refuse it.
|
||||
- The remaining low findings of the Step 6 audits: `<use>` nesting budget in
|
||||
the sanitiser (today bounded by the rasterizer), the decoder memory
|
||||
the sanitiser (today bounded by the rasterizer on the PDF path; since R3 the
|
||||
Rust reader refuses reference cycles and expansions over 50,000 elements,
|
||||
`docs/development/RUST.md` §9.2, and the engine gets it when R4 switches it to
|
||||
that reader: still open for the PDF path), the decoder memory
|
||||
envelope of PNG logos (bounded by the 4096² cap, about 430 MB worst case
|
||||
for four logos).
|
||||
@@ -684,3 +684,151 @@ application itself builds.
|
||||
is the Step 27 follow-up of R0).
|
||||
- The documented CSP refuses the footer's external credit logo
|
||||
(`img-src`), an older matter seen by the proof.
|
||||
|
||||
## 9. R3: the anatomy core in Rust, drawn by the editor canvas (2026-10-15)
|
||||
|
||||
Plan and contract: `.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md`
|
||||
(revision 2 after three plan challenges, 32 findings folded). Status: delivered
|
||||
on `feature/rust-r3-anatomy-core`, awaiting the owner's validation; not merged.
|
||||
|
||||
### 9.1 What runs in Rust, and who calls it
|
||||
|
||||
| Former TypeScript | Rust (`crates/core/src/anatomy`) | Consumer |
|
||||
|---|---|---|
|
||||
| `apps/app/src/anatomy/drawing.ts` denylist + `DOMParser` parse of the asset (deleted) | `svg/{prescan,tree,sanitize,refs,number,serialize}.rs`, `svg::read_svg` | the sheet load (`LoadedSheet`, each drawing read once) |
|
||||
| `packages/anatomy/src/render/layer.ts` (`renderAnnotationLayer`, `viewBoxOf`) | `layer.rs` | `view.canvas`; the highlight |
|
||||
| the canvas composition of `drawing.ts` (fresh root, viewBox rules, layer last) | `compose.rs` `compose_canvas` | `view.canvas` → `SheetIndex.canvasSvg` → `AnatomyCanvas` |
|
||||
| `packages/anatomy/src/render/compose.ts` (`composeViewSvg`, `highlightLayer`, halo) | `compose.rs` `compose_highlight` | none yet: proven against the engine (O3), wired at R4 in R4's snapshot-based call |
|
||||
| `packages/pdf/src/svg/sanitize.ts` allowlist and value rules | `svg/sanitize.rs` (same lists, same rules, declared additions 9.4) | the canvas now; the engine keeps its TypeScript copy until R4 |
|
||||
|
||||
One facade operation on the sheet handle: `view.canvas { viewId } → { svg }`,
|
||||
failures `unknown_view`, `no_asset`, `svg_rejected` (reason in `detail`:
|
||||
`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`,
|
||||
`too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`, or
|
||||
`removed <names>` when the allowlist would take something out of a product
|
||||
drawing), `invalid_character`. The result is constant for a loaded sheet:
|
||||
`SheetIndex` memoises it per view; `AnatomyCanvas` parses it with `DOMParser`,
|
||||
imports it and restyles `data-state` in place as before.
|
||||
|
||||
### 9.2 The SVG reader (`read_svg`)
|
||||
|
||||
1. Bounds before any parser (`prescan.rs`, a markup state machine: comments,
|
||||
CDATA, PIs and quoted values skipped by the grammar, no regex): 2 MiB, a
|
||||
leading BOM refused, `<!DOCTYPE`/`<!ENTITY` anywhere, depth 64, 20,000
|
||||
elements, 256 attributes per element and 100,000 in all, 16 namespace
|
||||
declarations, 100,000 raw `<` and 200,000 raw `=`. Reason: roxmltree 0.21.1
|
||||
builds its tree recursively (measured: a 1 MiB stack overflows between
|
||||
1,000 and 3,000 nesting levels; the iterative fix is unreleased), and it
|
||||
pre-allocates on the raw `<`/`=` counts, checks duplicate attributes
|
||||
quadratically and copies inherited namespaces per declaring element.
|
||||
2. roxmltree 0.21.1 (DTD refused, node limit 200,000 as a backstop) into the
|
||||
core's own tree, names as written (the allowlist matches qualified names
|
||||
like the engine).
|
||||
3. The allowlist (`sanitize.rs`): the engine's 28 elements, 74 attributes, 27
|
||||
presentation attributes and value rules (no backslash, every `url(` local,
|
||||
`href` to `#id` only, `style` without forbidden tokens or functions, the
|
||||
`stdDeviation` clamp with JavaScript `Number()` reproduced by hand), and the
|
||||
`<use>` count cap 256.
|
||||
4. The reference graph (`refs.rs`): tree edges plus every `href`/`xlink:href`
|
||||
and `url(#id)` to the first element of that id; a cycle is refused, and so
|
||||
is an expanded size over 50,000 elements (each reference adds its target's
|
||||
expanded subtree, saturating, iterative, early exit).
|
||||
5. The serialiser (`serialize.rs`): XML 1.0, `& < > "` and `\t \n \r` as
|
||||
references in attributes, `& < >` and `\r` in text; a re-read gives the
|
||||
same tree. A composed view over 4 MiB is refused.
|
||||
|
||||
### 9.3 Proofs and tests (oracles frozen with the TypeScript first)
|
||||
|
||||
- O1 (`apps/app/tests/fixtures/goldens/r3/canvas.*.json`, 47c5f49): the canvas
|
||||
tree of each view and the layer of 14 state sets per view (the three
|
||||
reference reports). Green on the Rust composition in cargo
|
||||
(`tests/anatomy_compose.rs`), in the app suite on the mounted canvas
|
||||
(`canvas.trees.test.tsx`) and in Chromium 156 on the live page
|
||||
(`scripts/visual-canvas.mjs dom`): equal for both views.
|
||||
- O2 (`oracles/r3/layer.json`): 8 layer trees with attribute order (draft +
|
||||
an edge document: twin radius floor, `1e+21`, path geometry, circle trigger
|
||||
without a name, colour fallback, laterality): exact, order included.
|
||||
- O3 (`oracles/r3/highlight.json`): 36 highlighted compositions (every
|
||||
observation and view of the three reports, an existing nested `<defs>`, a
|
||||
detail view with its own asset and no viewBox): tree-equal.
|
||||
- O4/O5 (`oracles/r3/sanitiser.json`): 36 hostile files
|
||||
(`tests/fixtures/svg/hostile`) and 10 generated cases: equal to the
|
||||
TypeScript verdict or a declared one (9.4); the 4 product SVGs (horse
|
||||
drawing, partner logo, 2 public logos) untouched, tree-equal. Mutation
|
||||
checks run on the oracle tests (a cap, the namespace rule, the twin floor,
|
||||
the halo placement): each mutant failed the suite.
|
||||
- Shipped wasm (`packages/core-wasm/tests/anatomy.test.ts`): the corpus plus
|
||||
floods (99,000 nesting levels, 20,001 nodes, 150,000 `<` in a comment, 257
|
||||
attributes, 2 MiB + 1, a 12 × 20 `<use>` chain, 1.9 MiB of `>`), each in a
|
||||
fresh instance: a closed outcome, no trap, slowest 24.9 ms, largest linear
|
||||
memory growth 10.1 MiB.
|
||||
- Runtime: the `SheetHandle` constructor's closed refusal (`<kind>: <detail>`
|
||||
from a plain `Error`) is `invalid_sheet`; any other throw (RangeError,
|
||||
InternalError, a trap) poisons the instance (`runtime.test.ts`).
|
||||
- Visual, Chromium 156 (`scripts/visual-canvas.mjs`): 30 captures before
|
||||
(TypeScript canvas) and after (Rust), desktop 1280 × 800 and phone
|
||||
390 × 844, no selection, each demo observation active, hover, main and
|
||||
head: 30/30 pixel-identical. The method's own noise floor: two captures of
|
||||
the same build 30/30 identical; its classifier flags a 10 × 10 change as a
|
||||
regression and a one-pixel edge nudge as anti-aliasing.
|
||||
- The Step 6 goldens (39) and the seed and review-drawing goldens are
|
||||
untouched: the engine and the pipeline still run the TypeScript renderer.
|
||||
|
||||
### 9.4 Behaviour differences (declared; none touches a product SVG)
|
||||
|
||||
1. An element outside the SVG namespace is removed (`<path xmlns="…">`), and
|
||||
`xlink:href` must be in the xlink namespace whatever its prefix.
|
||||
2. Comments and processing instructions are dropped; non-whitespace text is
|
||||
kept only in `title`/`desc`, each at most 4 KiB (longer: refused whole).
|
||||
3. The root loses `class` and `style` (an inline SVG lives under the page's
|
||||
CSS: `class="fixed inset-0 …"` would cover the application); an `id`
|
||||
outside `[A-Za-z_][\w.:-]*` is removed.
|
||||
4. A reference cycle, an expansion over 50,000 elements, and the floods of
|
||||
9.2 step 1 are refused; the TypeScript accepted them (size counted on the
|
||||
raw text, refused subtrees included).
|
||||
5. A product drawing the allowlist would alter is refused at sheet load for
|
||||
the views on that asset (`svg_rejected`, `removed …`); the TypeScript canvas
|
||||
dropped such parts silently.
|
||||
6. A label or path the document holds with a code point XML 1.0 cannot carry
|
||||
is refused (`invalid_character`); the DOM path drew it.
|
||||
7. When the canvas cannot be composed, it shows the existing degraded notice
|
||||
(`sheet.core_unavailable`) with "Réessayer" inside the canvas; before R3 a
|
||||
failure there left it blank (an uncaught error).
|
||||
|
||||
### 9.5 Measurements
|
||||
|
||||
| Measure | Value |
|
||||
|---|---|
|
||||
| shipped module | 1,188,740 B raw, **395,771 B gzip -9** (+55.8 KB over R2; budget 600 KB) |
|
||||
| sheet handle with the drawing read (Node) | 8 to 10 ms |
|
||||
| `view.canvas` main, first (Node) | 1.2 to 1.4 ms; head warm median 0.85 ms; 143 KiB of SVG |
|
||||
| Chromium, preview build, CPU × 4, medians of 3 | editor to canvas 503 ms (476 ms before R3); detail open 143 ms (125 ms before R3, runs 109 to 157); browser parse + import of the canvas text 21 ms (22 ms) |
|
||||
| 50 detail open/close cycles, CPU × 4 | JS heap +0.72 MiB (+0.89 MiB before R3), DOM nodes +0 (+0) |
|
||||
|
||||
### 9.6 TypeScript deleted, kept
|
||||
|
||||
- Deleted: the canvas denylist `sanitizeSvg`, `parseDrawing`, the parse
|
||||
cache, `assetOfView`, the states input of the canvas build, the
|
||||
`assets` field of `SheetIndex`, the app's dependency on
|
||||
`@faunosteo/anatomy`.
|
||||
- Kept, with their consumers: `packages/anatomy/src/render/**` (PDF engine
|
||||
until R4, curation pipeline until R5), `packages/pdf/src/svg/**` (engine
|
||||
until R4), the R3 oracle generators (`packages/anatomy/tests/
|
||||
r3.layer-oracles.test.ts`, `packages/pdf/tests/r3.{highlight,sanitiser}-
|
||||
oracles.test.ts`: they still pass on the TypeScript and keep the freeze
|
||||
honest until R4/R5).
|
||||
|
||||
### 9.7 Residual risks
|
||||
|
||||
- The engine (PDF) still sanitises with the TypeScript allowlist and has no
|
||||
reference budget: the `<use>` expansion gate of `PDF_IMPORT_HARDENING.md`
|
||||
§5 is met in the core, closed for the PDF path only when R4 switches it.
|
||||
- roxmltree's recursion: safe behind the prescan depth cap; pin the release
|
||||
with the iterative parser when it ships.
|
||||
- Firefox and WebKit: not run here (no browser build); the owner's LAN run on
|
||||
the phone covers WebKit.
|
||||
- The degraded notice inside the canvas (9.4 item 7) and its wording ("le
|
||||
moteur … n'a pas pu être chargé") are not tailored to a rejected drawing,
|
||||
which no shipped sheet can produce today.
|
||||
- A trigger without a name carries the opened view's French name in both
|
||||
name attributes (unchanged since Step 5; owner question).
|
||||
Reference in new issue
Block a user