docs(docs): V1-2.6 UX redesign technical plan, compatibility, tests, risks, decisions

This commit is contained in:
bchanot committed 2026-11-05 17:32:52 +01:00
1 parent f58cf2308f
commit 14fb527552
5 files changed
+1083

No files matched your search

+122
View File
@@ -0,0 +1,122 @@
# V1-2.6 UX redesign: old / new schema compatibility matrix
Status: PROPOSAL, 2026-11-05, audited at `f58cf23`, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md`. Each cell states the outcome
the code gives today (VERIFIED, file:line) or the outcome the plan requires and must prove by a test (REQUIRED,
test in `V1-2-6_UX_TESTS.md`). Nothing here is proven by assertion alone.
Only sub-step U6 changes the document model. Every other sub-step writes plain v2 documents through `sheet.edit`
and leaves every row of this matrix unchanged.
## 1. The change under study (route A, decision T2)
Two optional keys on `AnnotationCategory` (`crates/core/src/domain/sheet/schema.rs:219-228`):
```text
role?: "bone" | "joint" | "vertebra"
fill_opacity?: integer percent (range: decision T3)
```
Serde form required: `#[serde(default, deserialize_with = "js::present", skip_serializing_if = "Option::is_none")]`
and `ts(optional)`, the `LocalizedOptionalText` pattern (`schema.rs:162-180`). Absent = omitted on output; an
explicit `null` refused. No `SHEET_DOCUMENT_SCHEMA_VERSION` bump. If the keys were written as `null` when absent
(the `count_range` and annotation `color` precedent, `schema.rs:215-216`, `429-430`), every fingerprint, review
digest and R4 app-path digest would change: that serialisation is forbidden by this plan and pinned by tests.
Document kinds used below:
- **Old**: any document saved or published before U6 (equine historical, equine working copy, sandbox sheets, seed,
oracles, PDF snapshots).
- **New-absent**: a document handled by the new core that carries neither key (every old document re-saved, any
sheet whose editor never set them).
- **New-present**: a document carrying `role` and/or `fill_opacity` (every new sheet after U6, through `sheet.empty`;
any edited category).
## 2. Core readers and writers
| Artefact | Old | New-absent | New-present | Evidence |
|---|---|---|---|---|
| Strict reading, current core (before U6) | read | read | `invalid_shape` / `invalid_document` / `invalid_sheet` | VERIFIED `schema.rs:4-6`, `219-228`; `ops.rs:121-124`, `175-190`; `preview.rs:150-151`; `facade.rs:52-58` |
| Strict reading, new core | read | read | read | REQUIRED U6: parse every fixture, the seed, the oracles |
| Canonical writing, new core | as today | as today (keys omitted) | keys written | REQUIRED U6: re-serialise the seed, no `role`/`fill_opacity` text |
| Fingerprint `sha256-rfc8785-validated-v1` | unchanged | unchanged | new value, same construction | VERIFIED construction `fingerprint.rs:246-273`; REQUIRED: equine `12d78872…` and alias `27c7383c…` recomputed equal |
| Convention constant | unchanged | unchanged | unchanged (no bump under T2) | VERIFIED `check_declared` accepts v1 only, `fingerprint.rs:109-111` |
| Review digests (`general` holds categories) | unchanged | unchanged | `general` changes, change list reports `Category{id}` | VERIFIED `review.rs:96-124`, `210-216`, `375-378`; REQUIRED: seed digests unchanged |
| Size measure (2 MiB) | unchanged | unchanged | + about 16-20 B per key | VERIFIED `size.rs:21-42` |
| Validation (`validate.rs`) | unchanged | unchanged | unchanged (no new error; T4) | REQUIRED: same issues on every fixture before and after |
| Report issues (`sheet_report`, verdict only) | none new | none new | role disappeared vs base, duplicate role → `verification.validation.rules` | VERIFIED mapping `verdict.rs:277-296`; REQUIRED U6 |
| Edit refusals (role-bearing category) | n/a | n/a | refused remove / role change / duplicate / name change | REQUIRED U6, new kinds |
| `sheet.empty` | n/a | n/a | three role-bearing categories | REQUIRED U6 |
## 3. Rendering
| Artefact | Old | New-absent | New-present | Evidence |
|---|---|---|---|---|
| Layer (practitioner and editor canvas) | identical | identical (constants 0.65 / 0.5 / 0.3 / 0.06) | point twin and zone fill use `fill_opacity`; strokes and triggers unchanged | VERIFIED constants `layer.rs:94`, `242`, `297-315`; REQUIRED: R3 trees equal |
| R3 oracles `crates/core/tests/oracles/r3/{layer,highlight}.json` | pass | pass | not used (frozen inputs) | VERIFIED tree comparison `tests/common/svg_tree.rs:12-37`; `anatomy_layer.rs:54-85`; `anatomy_compose.rs:60-103` |
| Canvas goldens `apps/app/tests/fixtures/goldens/r3/canvas.*` | pass | pass | pass while the seed carries no key | VERIFIED `anatomy_compose.rs:119-140`; `anatomy_canvas_op.rs:27` reads the seed |
| Selected state (CSS) | accent at 0.85 | same | same: overrides any category opacity | VERIFIED `apps/app/src/styles/index.css:14` |
| Marker isolation vectors | closed | closed | closed: the layer writes only `fill-opacity` on its own elements | VERIFIED `svg_marker_isolation.rs:30-53`, `228-257`; REQUIRED: suite green |
## 4. PDF and archives
| Artefact | Old | New-absent | New-present, snapshot stripped (T7) | New-present, snapshot carrying keys (rejected option) | Evidence |
|---|---|---|---|---|---|
| PDF highlight raster | unchanged | unchanged | fill unchanged (overwritten); stroke = category colour as today | same | VERIFIED `compose.rs:41-42`, `259-267` |
| Envelope snapshot categories | `{id,name,color}` | same | same (stripped) | carries keys | VERIFIED `lean_document` copies whole, `snapshot_rules.rs:160`; REQUIRED: strip in `lean_document` and at the export gate `pdf/write/input.rs:174-181`, `export.rs:27-37` |
| Snapshot gate, new core | accepts | accepts | accepts | accepts | REQUIRED U6 |
| Archive reader at `f58cf23` (rollback build) | archive kept | archive kept | archive kept | `snapshot_rejected: Schema`, report kept | VERIFIED `read.rs:86-89`, `snapshot_rules.rs:225` |
| Frozen N-1 reader | read | read | read | `snapshotRejected 'schema'`, report kept, degraded alert | VERIFIED `n-1/domain/anatomical-sheet/schema.ts:65-72`, `n-1/domain/archive/envelope.ts:104-121`; REQUIRED: a New-present sheet fixture and harness whose PDFs pass the assertions of `n-1.reader.test.ts:178-196` (that test runs on the seed only) |
| ts-rs ↔ N-1 type test (assignability, `toMatchTypeOf`) | green | green | green with `ts(optional)` on both keys | green with `ts(optional)` (a type test cannot see runtime stripping) | VERIFIED `contracts.types.test.ts:53-61`; the runtime proof is the N-1 fixture row above |
| `release/0.2.0` (never released, TypeScript reader identical to N-1) | read | read | read | snapshot rejected, report kept | VERIFIED branch tip `f8d9425`, `CHANGELOG.md:9-14` |
| 0.1.0 (production faunosteo.com) | NOT VERIFIED | NOT VERIFIED | NOT VERIFIED | NOT VERIFIED | to read before any production release |
| R4 digests, cargo and wasm paths (frozen R3 envelopes) | unchanged | unchanged | unchanged | unchanged | VERIFIED `pdf_serialize.rs:67`, `124-140`; `pdf-export.test.ts:163-184` |
| R4 digests, app path, and step6 goldens (built from the bundled seed) | unchanged | unchanged | unchanged while the seed carries no key | changed | VERIFIED `pdf.goldens.test.ts:184-229`; `helpers/sheet.ts:19-20` |
| Old bilan PDFs (envelope v1, Report v2/v3) | read and reproduced | same | same | same | rule kept: an archive reader never drops a version |
## 5. Server
| Artefact | Old | New-absent | New-present | Evidence |
|---|---|---|---|---|
| `check_document_structure` | pass | pass | pass (category members never read) | VERIFIED `20261028110000_sheet_review_workflow.sql:411-441` |
| CHECKs `schema_known`, `schema_matches` | pass | pass | pass | VERIFIED `20261010100000:10-12`, `20261008110000:120-121` |
| Status walk, disclaimer, group keys | unchanged | unchanged | unchanged | VERIFIED `20261028110000:150-215`, `20261101100000:107-181` |
| `sheet_verdict_codes` | unchanged | unchanged | unchanged: report issues map to the existing `verification.validation.rules`; SQL checks only top-level failure codes | VERIFIED `20261101100000:57-69`, `360-368`; `verdict.rs:277-296` |
| Rounds in flight when the rules change | n/a | n/a | withdrawn by the U6 migration (T4) | REQUIRED U6 pgTAP; contract `V1-2_ANATOMICAL_SHEETS.md:945-949` |
| Worker at `f58cf23` (old image) | verdict as today | verdict as today | definitive `verification.integrity.document` (draft) or `.base` (base) | VERIFIED `verify.rs:93-97`, `verdict.rs:169-185`, `264-274`; `20261101100000:355-378` |
| Worker of U6 | verdict as today | same | reads; applies the report issues | REQUIRED `verify-e2e` with an image checked against `HEAD` |
| App at `f58cf23` after rollback | reads | reads | `invalid_document`: the draft cannot open | VERIFIED `preview.rs:150-151` |
| Published versions | immutable | immutable | immutable: cannot be edited back | VERIFIED `20261028110000:274-292` |
## 6. Old drafts and local copies
| Case | Outcome | Evidence |
|---|---|---|
| Draft saved before U6, opened after | read as New-absent | REQUIRED U6 |
| Recovery copy (sessionStorage) taken before U6, restored after | document text read by the same strict reader | VERIFIED storage `recovery.ts:10-57`; REQUIRED U6 |
| Recovery copy taken after U6, restored by a rolled-back app | refused like any `invalid_document`; the copy is kept, not deleted | REQUIRED: test that a refused copy is not purged |
| Undo history across the U6 release | history is per page session, never persisted | VERIFIED `undo.ts`, `editorLoad.ts:136-152` |
## 7. Deploy order and rollback
This section is the single statement of the order; the plan and the risk register point here.
Order for any environment, for U6 and U9 (and any later change of the reader, the rules, the caps or the
fingerprint):
1. SQL: the round-withdrawal migration (contract `V1-2_ANATOMICAL_SHEETS.md:945-949`). No verdict code is added, so
no change to `sheet_verdict_codes`.
2. Worker image, built from the same commit as the app (`.gitea/workflows/release-images.yml:103-120`).
3. Application.
Rollback:
| From → to | Possible | Limit |
|---|---|---|
| Any frontend-only sub-step (U1, U3, U4, U7) | yes | none: no document changes form |
| U2, U5 (additive read-only core value and queries) | yes | documents written are plain v2 |
| U6 → before U6, no New-present document exists | yes | none |
| U6 → before U6, a New-present document exists (any sheet created after U6) | **no** | drafts unreadable by the old app (`invalid_document`) and the old worker (`integrity.document`); published rows immutable; migrations forward-only (`docs/development/SUPABASE.md:595-603`). Same class as RR-2; recorded as a release-readiness item (id reconciled with develop) |
| U9 → before U9 | yes | paths go back to display only; documents stay plain v2 |
Before any production release carrying U6: read the 0.1.0 reader and record its behaviour on New-present snapshots
(NOT VERIFIED today), and run the release replay of published versions (contract §15).
+157
View File
@@ -0,0 +1,157 @@
# V1-2.6 UX redesign: technical decisions still needed
Status: PROPOSAL, 2026-11-05, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md`; this is the
single table of what blocks what. The 11 UX choices and the direct SVG interactions validated by the owner on
2026-11-05 are not reopened. Each item is a technical question they leave open, with a recommendation.
## Owner decisions
| Id | Question | Blocks | Recommendation |
|---|---|---|---|
| T1 | Fallback if the wasm budget is exceeded | U5 and U6 only if the measure exceeds 600 000 B; U9 certainly | `wasm-opt -Oz` as a pinned build tool, then a small D-R13 raise; the PDF split stays a separate track |
| T2 | Doctrine for optional category keys, and the owner's agreement to widen the snapshot reader | U6 | route A, no version bump, `v1` convention kept, rules amended |
| T3 | Opacity semantics | U6 | integer percent 10-100, point twins and zone fills, constants when absent |
| T4 | Tier of the fixed-category rules; residual gap on a first version | U6 | `edit.rs` refusals + `sheet_report` issues (existing verdict code), round-withdrawal migration; residual gap accepted and covered by review |
| T5 | Fixed categories of a new sheet: ids, names, default colours | U6 | `cat-bone`, `cat-joint`, `cat-vertebra`; Os / Bones, Articulations / Joints, Vertèbres / Vertebrae; equine colours |
| T6 | Equine working copy conversion | V1-2.8 | proposal below, decided at V1-2.8 |
| T9 | Replacing a crop by its own drawing | U5 | explicit choice when the `viewBox` differs, positions kept when equal |
| T10 | Category of an automatic access; sheet without category | U5 | the Joints category after U6; before U6 the first category; none → box unchecked |
| T11 | Fate of the level-1 owner trial | U1 | skip it; trial the redesign at U2 and U8 |
| T12 | Common text: source, versions, wording, responsibility | U7 | versioned module; wording supplied and validated by the owner |
| T14 | Multi-tab notice | none (follow-up) | not in V1-2.6; track as a follow-up |
| T15 | Header « Annuler » next to form « Annuler » | none | keep the label; accessible name « Annuler la dernière modification » |
| T16 | Curve handle editing in V1-2.6 | U9 | defer to the lot that first lets a path enter a document |
| T17 | Vertebral regions entry when no category has the vertebra role | U6 | keep a « Régions vertébrales » entry in the Annotations panel in that case only |
## Implementer decisions (recorded at U0, no owner question)
| Id | Decision | Reason |
|---|---|---|
| T7 | Strip `role` and `fill_opacity` from every envelope snapshot, at `lean_document` and at the export gate | the PDF needs neither; the only alternative breaks N-1 reading of new PDFs |
| T8 | Path ops (U9) compute on the written decimal digits; output precision = max(input precision, 2 decimals for a user move) | keeps « no other point moves » and exact round trips |
| T13 | No sub-branches: commit in place on `feature/v1-2-anatomical-sheets`, rollback by reverting a sub-step's commits | the gitflow lib branches only from develop and `finish` merges into develop |
| T18 | Handle cap per shape (constant fixed at U2 from the equine maxima with margin); above it, outline and a message | bounded DOM for oversized shapes saved directly |
| T19 | Sliders and arrow moves commit on release, Enter or blur | BDR-050; the 8 MiB history holds about 20 equine documents |
## T1 · Wasm budget fallback
- Facts: the gate measures Node `gzipSync` level 9 (`packages/core-wasm/tests/size.test.ts:12-25`): 592 143 B of
600 000 B, margin 7 857 B (measured 2026-11-05). Without curves the new core code is estimated at 4.5 to 13.5 KB.
The plan builds `annotations_in_rect` first and measures, then `remap_view`, then the U6 changes.
- Options if a measure exceeds the budget:
- (a) `wasm-opt -Oz`: gain unknown; `wasm-opt` is not installed (`RUST.md:4054`), so it becomes a pinned tool in
`scripts/wasm-build.sh`, the builder image and the release workflow.
- (b) raise the budget (D-R13) by the measured excess plus a margin: no work; a slightly slower first load.
- (c) lighter URL check (about 23 KB): must keep `new URL()` equivalence.
- (d) PDF code in a lazily loaded second module (about 55-60 KB): touches R4, the import worker, the CSP proof,
trap recovery and the readers of user data; its own track with its own owner checkpoint, never a prerequisite.
- Recommendation: (a), then (b) if still short. (d) only as a separate decision.
## T2 · Doctrine for optional category keys
- Facts: `.claude/rules/schemas.md:9-11` (« additive optional fields keep it ») against `.claude/rules/sheet-model.md`
(« Document schema change → bump … No bump during V1-2 (BLK-008) ») and BDR-068 (`v1` freezes construction and
validation). Route B (v3) is excluded by contract §12.3 (`V1-2_ANATOMICAL_SHEETS.md:1779-1781`) and needs a data
migration and a `save_sheet_draft` change. The snapshot reader (`assert_snapshot`, used by `archive/read.rs`) is a
reader of user data: CLAUDE.md requires the owner's agreement before widening it.
- Recommendation: route A as specified in `V1-2-6_UX_COMPATIBILITY.md` §1: an additive optional change of the v2
document, no version bump, the `sha256-rfc8785-validated-v1` construction unchanged (existing values proven equal
by tests); `sheet-model.md` amended to say that an optional key omitted when absent is not a version change, with
the proof list. Route C (reserved ids, no opacity) contradicts choice 5.
## T3 · Opacity semantics
- Recommendation: integer percent from 10 to 100 (below 10 a marker becomes invisible on the drawing while the 4 px
rules assume it visible). When present it drives the fill of point twins and of zones alike; when absent the
current constants stay (0.65 main and 0.5 detail for twins, 0.3 for zones), so existing renders are identical.
Detail triggers keep 0.06. The selected state keeps its accent at 0.85 (`apps/app/src/styles/index.css:14`).
Written first in `docs/ANNOTATION-RENDERING.md`. The layer writes it as `fill-opacity`, which the PDF highlight
overwrites: no PDF effect.
## T4 · Tier of the fixed-category rules
- Facts: edit refusals act only in the editor (`edit.rs:1-4`); a direct save is checked structurally only. A
`validate.rs` error would invalidate existing documents (fingerprint, snapshot gate). Issues added in
`sheet_report` (the `GEOMETRY_MISSING` pattern, `report.rs:17-19`) map to the existing
`verification.validation.rules` (`verdict.rs:277-296`), so no SQL code change. The contract requires a migration
withdrawing rounds in `verifying`, `open` or `approved` when the integrity rules change
(`V1-2_ANATOMICAL_SHEETS.md:945-949`).
- Options: (a) `edit.rs` refusals only; (b) (a) + report issues relative to the base (a role of the base must remain;
a role appears once) + the withdrawal migration.
- Residual in both: a first version has no base; a direct save, or « Garder ma version » from a tab running an older
bundle, can strip the roles before the first publication. It shows in the review of the `general` group.
- Recommendation: (b), consistent with O22, and the residual accepted.
## T5 · Fixed categories of a new sheet
- Recommendation: `sheet.empty` creates `cat-bone`, `cat-joint`, `cat-vertebra` (core-chosen, unlike the page's
`cat-<10 base32>` ids, `apps/app/src/editor/ids.ts:1-21`, so no collision); names FR « Os », « Articulations »,
« Vertèbres », EN « Bones », « Joints », « Vertebrae »; roles `bone`, `joint`, `vertebra`; default colours, shown
as « Couleur d'origine » (board 07 A), taken from the equine categories: `#a41e65`, `#ff9500`, `#e100ff`. Names stay
stored (old readers show them) and the edit rules refuse changing them.
## T6 · Equine working copy conversion (V1-2.8)
- Facts: five categories (`articulations` 12 annotations, `os` 2, `charnieres-vertebrales` 4, `zone-colonne` 5,
`cadrans-du-crane` 5). `os` and `articulations` already carry the fixed names; `zone-colonne` is « Segments
vertébraux / Vertebral segments ». Three own colours: atm and ssb `#ff8800`, hyoid `#d507c4`.
- Proposal: roles on `os`, `articulations`, `zone-colonne`; `zone-colonne` renamed « Vertèbres / Vertebrae » in the
working copy only (id unchanged); the two other categories stay free; own colours kept (choice 11) unless the
business review decides otherwise. The historical sheet and the Git seed never change.
## T9 · Replacing a crop by its own drawing
- Facts: the seed head drawing has exactly the crop's `viewBox` and the full drawing's path data: keeping positions
is right for it. A remap is right only for a drawing re-based on another `viewBox`.
- Recommendation: V equal to R → positions kept, no question. V different → the dialog asks « Même repère : garder
les positions » or « Dessin recadré : transposer les annotations », no default selected; transposition is uniform
(`meet`), centred, annotations to confirm. Labels to confirm by the owner.
## T10 · Category of an automatic access
- Recommendation: after U6, the Joints category (the equine access to « Tête » belongs to Articulations); before U6,
the first category of the sheet; a sheet without any category → the box is unchecked with the reason, the access
is placed later. Changeable in the properties.
## T11 · Fate of the level-1 owner trial
- Facts: level 1 is built and served for the trial (`V1-2-6_OWNER_TRIAL.md`); not tried yet. U1 and U2 replace its
tab structure and numeric journeys.
- Recommendation: skip the level-1 trial; keep its infrastructure (store, save, recovery, conflicts, upload, modes)
as the base; trial the redesign at U2 and U8. Level-1 criteria the redesign does not touch (C13 recovery, C14 undo
bound, C16 narrow read-only, C34, C41) stay in force and are re-tested.
## T12 · Common text
- Recommendation: a versioned module in the application (id, version, FR, EN), changed only by a reviewed commit;
wording supplied and validated by the owner or a person the owner names; the editor shows « texte commun,
version n » and never presents it as veterinary or legal advice approved by the platform. U7 starts only when the
wording exists. Contract §7.4 amended at U0.
## T14 · Multi-tab notice
- Facts: no multi-tab detection exists; the server revision check and the conflict dialog prevent silent loss; the
boards show no such notice.
- Recommendation: out of V1-2.6, tracked as a follow-up. If kept later: heartbeat-based (a crashed tab never says
goodbye), wording consistent with « Garder ma version ».
## T15 · « Annuler » wording
- Recommendation: keep the validated label; give the header button the accessible name and tooltip « Annuler la
dernière modification » / « Undo the last change ».
## T16 · Curve handle editing
- Facts: no document of the project holds a path; no product path creates one; the validated guarantee « aucune
courbe convertie » is held by display-only paths and the C45 refusal; board 05 shows curves as « exemple d'une
autre fiche ». The three path ops are the plan's heaviest work (610 to 1 020 lines, 10 to 21 KB) and need a
certain size lever and a round-withdrawal migration.
- Recommendation: defer U9 to the lot that first lets a path into a document (package import, zones from drawing
shapes, or a curve drawing tool), keep its specification (`V1-2-6_UX_PLAN.md` §2 D) and keep C45 and the closed
`remap.path` refusal meanwhile.
## T17 · Vertebral regions entry without a vertebra role
- Facts: board 09 opens the regions from the Vertèbres category; the equine working copy has no role before V1-2.8.
- Recommendation: when no category carries the vertebra role, the Annotations panel keeps a « Régions
vertébrales » entry; when one does, the entry sits under it as on board 09.
+623
View File
@@ -0,0 +1,623 @@
# V1-2.6 UX redesign: technical implementation plan
Status: PROPOSAL for the owner, 2026-11-05. Nothing in this file authorises code. No application, Rust, SQL or
worker change is made before the owner approves this plan and the blocking decisions of
`V1-2-6_UX_DECISIONS.md`. Branch `feature/v1-2-anatomical-sheets`, worktree `/home/bchanot/Documents/faunosteo-v1-2`,
audited at `f58cf23`.
Companion files:
| File | Content |
|---|---|
| `V1-2-6_UX_PLAN.md` | This plan: inventory, sensitive points A to I, sub-steps U0 to U9 |
| `V1-2-6_UX_COMPATIBILITY.md` | Old / new schema matrix: core, SQL, worker, PDF, snapshots, N-1, oracles, rollback |
| `V1-2-6_UX_TESTS.md` | Test matrix per sub-step |
| `V1-2-6_UX_RISKS.md` | Risks, dependencies, blocking points |
| `V1-2-6_UX_DECISIONS.md` | Technical decisions still needed (the validated UX choices are not reopened) |
Inputs: the owner brief « V1-2.6 — Validation UX définitive et préparation technique » (16 boards of
`docs/design/v1-2-6/`, archive V2, and the 11 choices of `ARBITRAGES.md`, all validated); five static audits run on
`f58cf23` (core model, rendering and archives, geometry and wasm, SQL and worker, editor and tests). Every claim of
the earlier study (`docs/design/v1-2-6/ETUDE-TECHNIQUE.md`, `.claude/audits/2026-11-05-v1-2-6-ux-feasibility.md`)
was re-checked against the code; §1.7 lists where it was wrong.
Paths below are relative to the repository root. `core/` stands for `crates/core/src/`, `app/` for `apps/app/src/`.
---
## 1. Technical audit
### 1.1 What the core already offers (re-verified)
- **Edit primitives.** `sheet.edit` (insert, update, remove, move, set_status, mark_reviewed) is a free op, document
in, document out (`core/ops.rs:106-119`, `core/domain/sheet/edit.rs:96-125`). `update` replaces an element whole
(`edit.rs:459-509`); an annotation whose content changes turns `to_confirm` (`edit.rs:495-509`). Every gesture on a
point or a polygon ends in one such `update` (or `insert`).
- **Removal guard.** `remove` refuses with `has_dependents` while anything names the element (`edit.rs:570-577`,
`903-908`).
- **Redrawn views.** After every command, the annotations of a view whose drawing or `view_box` changed turn
`to_confirm`; geometry is never touched (`edit.rs:792-857`).
- **Preview handle.** `PreviewSheet` holds the drawings and the document, `preview.state` and `view.canvas`
(`core/ops.rs:514-530`, `crates/wasm/src/lib.rs:79-154`). Practitioner canvas and editor canvas share one
composition (`ops.rs:472-507`).
- **Crop composition is vector.** The whole sanitised drawing is cloned, its root becomes a `<g>`, only the new
root's `viewBox` frames it (`core/anatomy/compose.rs:94-160`). A crop view needs no derived file.
- **Placement rules.** `view_frame`, `geometry_bounds`, `placement`, `out_of_frame`, `too_small`, `marker_too_small`
(`core/anatomy/frame.rs:60-254`) and `interior_too_small` (`core/anatomy/interior.rs:33-43`, `207-222`).
- **Path reader.** Strict browser grammar, every command, implicit repeats, numbers bounded at 2^20, f64 pen,
bounds measured on the shape (`core/anatomy/path.rs`, 1 090 lines). Its `Cursor`, `Pen`, `Arc` and `Ellipse` are
private and the number spans are computed then dropped (`path.rs:136-139`, `203`, `226`, `303-311`).
- **Number writing.** `json::js_number` prints ECMAScript `Number::toString` (`core/json.rs:18-82`), valid in path
data. `anatomy/svg/number.rs` is a JavaScript `Number()` reader and is not a path writer.
- **Names.** `PreviewState.index.names` already ships every annotation's name to the page (`core/domain/sheet/preview.rs:332-356`).
### 1.2 What the application already offers (re-verified)
| Capability | Code | Use in the redesign |
|---|---|---|
| Editor route, modes, permission states | `app/app/routes/app/admin/AdminSheetDraftRoute.tsx:73-156`, `app/editor/mode.ts:12-92` | REUSE |
| Store, commit, undo (one entry per accepted commit, 8 MiB) | `app/editor/state/editorEdit.ts:45-82`, `undo.ts:7-54` | REUSE, header buttons ADD |
| Undo shortcuts (global, ignored in fields and dialogs) | `app/editor/useUndoShortcuts.ts:4-24` | REUSE |
| Explicit save, unsaved state, conflict dialog with M8 | `editorSave.ts:43-149`, `DraftHeader.tsx:27-153`, `ConflictDialog.tsx:105-231` | REUSE |
| Local recovery (sessionStorage, key user + version, revision in the record) | `recovery.ts:10-155`, `recoveryFlow.ts:56-187` | REUSE |
| Pan, pinch, wheel, keyboard zoom | `app/catalogue/useFraming.ts:85-168` | REUSE, keys ADAPT |
| Point and polygon move after 4 CSS px, one update on pointer-up | `useMoveGesture.ts:78-116`, `gesture.ts:5-33` | ADAPT (pointerId) |
| Point, zone and link creation by clicks | `creation.ts:93-178`, `usePlacement.ts:13-85` | ADAPT |
| Geometry accept after commit | `app/editor/issues.ts:123-175` | REUSE |
| Upload, cleaning, attach, repair | `drawingUpload.ts:86-192`, `repair.ts:60-309` | REUSE, attach ADAPT (remap) |
| Crop preview of the parent | `CropCanvas.tsx:30-77`, `viewBox.ts:31-46` | REUSE as the rectangle's base |
| Verification tab, submission | `components/editor/tabs/VerificationTab.tsx`, `verification.ts:64-131` | REUSE, targets ADAPT |
### 1.3 Interactions possible without a core change
Page-only, each ending in `sheet.edit` and judged by the core on commit (`issues.ts:123-175`): the four-tab shell;
header undo and redo; the references side panel; sidebar collapse; point move; point size slider (the page reads
the radii present in the view, the core still refuses `marker_too_small`); polygon vertex drag; « + » on a segment;
« − » on a vertex; zone move (mouse direct, touch mode); zone redraw keeping the old shape until validation; the
rectangle gesture that sets a detail view's `view_box`; « replace by a specific SVG » without remap; per-annotation
colour shown only when set, with « back to the category colour » (an `update` with `color: null`); keyboard
alternatives; 44 px touch handles; the `pointerId` guard; a multi-tab notice if the owner wants one (T14).
### 1.4 New Rust operations required
| Op | Needed for | Kind | Estimate |
|---|---|---|---|
| `sheet.annotations_in_rect` | name proposal of a detail view (choice 6), automatic access only without overlap | `PreviewSheet` op | 80-150 lines, 1.5-4 KB gzip |
| `sheet.remap_view` | a crop view receiving a re-based drawing (point E) | `PreviewSheet` op returning `sheet.edit` commands | 120-250 lines, 2-5 KB |
| per-view minimum visible radius | the red « minimum touchable » mark of the size slider (choice 3) | value in `PreviewState` | 20-40 lines, < 0.5 KB |
| `sheet.path_points` | curve handles (point D, U9, deferral proposed) | free op | 250-400 lines, 4-8 KB |
| `sheet.path_move_points` | move anchors and controls without simplifying | free op | 300-500 lines, 5-10 KB |
| `sheet.path_translate` | move a curved zone whole | free op | 60-120 lines, 1-3 KB |
| fixed-category rules + opacity in the layer | choices 4 and 5 | schema + `edit.rs` + `sheet_report` issues + `layer.rs` | 1-3 KB |
Estimates come from the recorded size history: the frame rule with curve and arc measure cost +12 616 B, the
interior rule +6 195 B, `sheet.empty` about +2 698 B, reserved ids +655 B (`docs/development/RUST.md:4101`, `4203`,
`4452`). They are ranges, not measures.
### 1.5 Schema change, serialisation, fingerprints, versioning
Only choices 4 and 5 touch the document schema (two optional keys on `AnnotationCategory`, route A of the earlier
study). Facts that govern it:
- `AnnotationCategory` is `{id, name, color}` with `deny_unknown_fields`; `color` is a required key that may be
`null` (`core/domain/sheet/schema.rs:219-228`). Every strict reader refuses an unknown key: `sheet.check` and
`sheet.edit` answer `invalid_shape`, PreviewSheet `invalid_document`, the verdict
`verification.integrity.document`, the snapshot gate `SnapshotRejection::Schema`.
- The fingerprint hashes the JCS text of the typed document re-serialised (`core/domain/sheet/fingerprint.rs:4-11`,
`246-273`). A new `Option` field keeps every existing fingerprint only if it is **omitted** when absent
(`skip_serializing_if`), as `LocalizedOptionalText` already does (`schema.rs:162-180`). The nearest precedents
(`count_range`, annotation `color`) write `null`; following them would change every fingerprint, the equine
sheet-ref, the alias pair of BDR-070, every review digest and every R4 app-path digest.
- The fingerprint and the snapshot gate also require no validation **error** (`fingerprint.rs:262-265`,
`snapshot_rules.rs:334-340`). A new unconditional `validate.rs` error (for example « three roles required ») would
strip the fingerprint of every existing document and reject old PDF snapshots. Fixed-category rules must live in
`edit.rs` (editor refusals) and in a verdict-only tier relative to the base (precedent `GEOMETRY_MISSING`,
`core/domain/sheet/report.rs:17-19`, `54-55`), never as an unconditional `validate.rs` error.
- Doctrine conflict to settle (decision T2): `.claude/rules/schemas.md:9-11` says additive optional fields keep the
contract; `.claude/rules/sheet-model.md` says a document schema change bumps `SHEET_DOCUMENT_SCHEMA_VERSION`, with
no bump during V1-2 (BLK-008); BDR-068 says `v1` freezes the construction and the validation. Route B (schema v3)
is excluded by the contract during V1-2 (`docs/development/V1-2_ANATOMICAL_SHEETS.md:1779-1781`) and would need a
data migration (BLK-008) plus a change to `save_sheet_draft`, which never updates `document_schema_version`
(`supabase/migrations/20261028110000_sheet_review_workflow.sql:621-623` against the CHECK of
`20261008110000_anatomical_sheets.sql:120-121`).
### 1.6 Wasm module size
Measured on the shipped build (`packages/core-wasm/pkg/faunosteo_wasm_bg.wasm`, built 2026-11-04 after the last
core change of 2026-11-02): 1 569 864 B raw, **592 143 B** with Node `gzipSync` level 9, which is what the gate
measures (`packages/core-wasm/tests/size.test.ts:12-25`). Budget 600 000 B (D-R13), **margin 7 857 B**. GNU `gzip -9`
gives 583 126 B; the earlier study's « about 17 KB left » used that figure. Without the curve operations (U9,
deferral proposed) the new core code is estimated at about 4.5 to 13.5 KB: it may fit or exceed the margin, so the
plan measures after each op and holds a fallback ready (decision T1). With U9 the total reaches 14 to 31 KB and a
lever is certain. Documented levers, none applied: `wasm-opt -Oz` (never measured; `wasm-opt` is not installed,
`RUST.md:4054`, so it is a new pinned build tool), a lighter URL check (about 23 KB), the PDF writer, reader and
inflater in a lazily loaded second module (about 55-60 KB, `RUST.md:4050-4054`; touches the R4 paths, the import
worker, the CSP proof and trap recovery, and the readers of user data that need an explicit owner ask). Raising the
budget is an owner decision (D-R13).
### 1.7 Corrections to the earlier study
| Earlier claim | Code |
|---|---|
| About 17 KB of wasm margin | 7 857 B by the gate's measure (§1.6) |
| PDF highlight is a fixed colour, category settings change no PDF | Fill and fill-opacity are overwritten (`compose.rs:259-267`); zone and trigger **strokes keep the category colour** in the PDF. Category opacity has no PDF effect only if written as `fill-opacity` |
| Old documents re-written identically under route A | Only with `skip_serializing_if`; the precedents write `null`. And any `sheet.edit` output re-serialises the stored text (seed key order, omitted `color`); « byte for byte » holds for untouched stored texts and for the canonical fingerprint |
| An integer avoids losing `Eq` | `JsInt` wraps an f64 without `Eq` (`core/domain/js.rs:94`); nothing needs `Eq` on the category |
| Snapshot can strip the fields « as it strips references » | `lean_document` copies categories whole (`snapshot_rules.rs:160`); stripping is new code, and the export gate re-serialises caller snapshots (`pdf/write/input.rs:174-181`, `export.rs:27-37`) |
| N-1 and 0.2.0 refuse an unknown key | Only the snapshot is dropped (`snapshotRejected 'schema'`); the report is still imported with a degraded alert (`packages/core-wasm/tests/n-1/domain/archive/envelope.ts:110-117`, `core/domain/archive/read.rs:86-89`) |
| SQL checks arrays and category ids | Category ids are not checked since M5 (`20261028110000:139-144`); the conclusion (optional keys pass SQL) holds |
| Worker image before the app, as for any core change | Not written anywhere. When verdict codes, group kinds or verdict format change, the **SQL migration** comes first (`20261101100000_sheet_verification_jobs.sql:57-69`, `153-160`, `321`), then the worker, then the app. A new document rule needs no new code: every error issue outside five excluded codes maps to the existing `verification.validation.rules` (`core/domain/sheet/verdict.rs:277-296`) |
| Replacing a crop by its own drawing displaces annotations | Not for the project's own data: the seed head drawing has `viewBox="60 100 500 380"` (`supabase/seed/anatomical-sheets/equine/legacy-sources/Horse_head.svg`), exactly the `head` crop (`draft/document.json:477-482`), and the same path data as the full drawing. Keeping positions is right for a drawing cut from the same master; a remap is right only for a re-based drawing |
| Adding a role to `os`, `articulations`, `zone-colonne` suffices | `os` (Os / Bones) and `articulations` (Articulations / Joints) already carry the fixed names; only `zone-colonne` (Segments vertébraux / Vertebral segments) differs. Three equine annotations carry an own colour that overrides any category setting |
| Not covered | A detail view without an access is a `view.unreachable` **error** (`core/domain/sheet/validate.rs:199-220`): it blocks the fingerprint, the snapshot and publication. Under choice 6 an access not created automatically must be placed before submission |
| Recovery keyed by version and revision (contract C13) | Key = user + version; the revision is a field of the record (`recovery.ts:47-49`). Code and contract text differ |
| `useMoveGesture` has a weak pointerId check | It has none (`useMoveGesture.ts:87`): a second finger feeds the drag while the pinch zooms |
### 1.8 SQL, RLS and worker
- No SQL reads the members of a top-level category. Optional keys pass `check_document_structure`
(`20261028110000:411-441`), the CHECKs and the RLS unchanged. `schema_version` 3 is refused
(`20261028110000:424-426`, `20261010100000:10-12`).
- The worker reads the document strictly through the core (`crates/worker/src/verify.rs:93-97`,
`core/domain/sheet/verdict.rs:169-185`, `264-274`). An older worker answers a definitive
`verification.integrity.document` on a draft carrying the new keys, never retried; a newer worker adding a verdict
code before SQL knows it closes the rounds whose verdict carries it `verdict_refused` (`20261101100000:57-69`,
`87-90`). The plan adds no verdict code (fixed-category rules are issues mapped to `verification.validation.rules`).
- App and worker images are built from one `GIT_SHA` by `.gitea/workflows/release-images.yml:103-120` (prepared,
never run). The sandbox reuses `faunosteo_worker:dev` without checking it matches the checkout
(`scripts/db-sandbox.sh:335-347`): every model step rebuilds it explicitly.
- The only SQL the redesign needs is the round-withdrawal migration the contract requires when the integrity rules
or the SVG reader change (`V1-2_ANATOMICAL_SHEETS.md:945-949`): U6 (verdict-tier rules, decision T4) and U9 (path
reader). References are in the document; own drawings use the existing upload path, capped at
4 drawings per sheet, 2 MiB each, 6 MiB in all (`core/domain/archive/snapshot.rs:21-28`).
### 1.9 Concurrency, multi-tab, recovery
- One draft per sheet (unique partial index, `20261008110000:131-133`); `save_sheet_draft` locks and checks the
revision (`20261028110000:593-608`); a stale save answers `draft_conflict`, nothing is overwritten.
- No multi-tab detection in the app (no `storage` event, `BroadcastChannel` or `navigator.locks`). Each tab keeps its
own sessionStorage copy. Two tabs edit freely; the first save wins; « Garder ma version » in the second tab
overwrites the first tab's save with a whole document after confirmation (`editorSave.ts:140-149`).
- Undo crosses a save (history kept, `editorSave.ts:84-93`); `addDrawing` is outside history (`editorEdit.ts:85-104`).
- Clicking a header button while a text field holds typed text blurs it first, which commits; the undo then reverts
that typing (`TextField.tsx:75-88`, `GeometryGroup.tsx:188`).
### 1.10 Keyboard, mouse, touch
- Markers are not focusable; keyboard selection goes through the annotation list (`AnnotationList.tsx:55-72`).
- Arrows already pan the focused canvas box (`useFraming.ts:150-168`): they collide with « arrows move the chosen
handle » unless focus decides (handle focused → move; box focused → pan).
- `touch-action: none` while a tool is active, a drag is armed, the view is zoomed or a movable selection exists
(`useCanvasGestures.ts:76-84`).
- Overlay vertices are decorative, `pointer-events-none`, radius span/200 drawing units (`AnnotationOverlay.tsx:48-66`,
`116`, `125`). No multi-touch test exists; the touch test is a single CDP touch at 1 280 px
(`apps/app/e2e/shell/editor-geometry.spec.ts:416-470`).
---
## 2. Sensitive points A to I
### A. Non-destructive migration for fixed categories and opacity
- Route A: `role` (`bone` | `joint` | `vertebra`) and `fill_opacity` (integer percent, decision T3) on
`AnnotationCategory`, both `Option` + `#[serde(default)]` + `js::present` (an explicit `null` refused, one canonical
form) + `skip_serializing_if = "Option::is_none"` + `ts(optional)`, the `LocalizedOptionalText` pattern. No
`SHEET_DOCUMENT_SCHEMA_VERSION` bump, no SQL schema change, no data migration (decision T2).
- Existing documents carry neither key: they read, write and fingerprint as today. Proven by tests, never assumed:
equine fingerprint `12d78872…` and alias `27c7383c…` recomputed equal, every seed review digest pinned and equal,
R4 app-path digests unchanged (`V1-2-6_UX_TESTS.md` U6).
- New sheets: `sheet.empty` creates the three fixed categories with roles, core-chosen ids (precedent `view-main`,
`core/domain/sheet/create.rs:9`, `28`), fixed names and default colours (decision T5).
- Rules in two tiers, never as an unconditional `validate.rs` error (that would strip fingerprints and reject old
snapshots): `edit.rs` refuses removing a role-bearing category, changing or clearing its role, a duplicate role,
and renaming a role-bearing category; `sheet_report` issues, relative to the base when there is one, report a role
of the base that disappeared and any duplicate role. They map to the existing `verification.validation.rules`
(`verdict.rs:277-296`): no new verdict code (decision T4).
- Residual gap, stated: a sheet's first version has no base, so a direct `save_sheet_draft` (or « Garder ma
version » from a tab still running an older bundle) can strip the three roles before the first publication; the
edit refusals do not see it. It shows in the review of the `general` group, where every group of a first version
must be covered. Decision T4 records whether this residual is accepted.
- No expand-then-write split: every environment where U6 runs is a throwaway sandbox, and `sheet.empty` writes the
keys from the first new sheet, so a split would not protect anything. The rollback limit is stated instead
(`V1-2-6_UX_COMPATIBILITY.md` §7) and recorded as a release-readiness item.
### B. Historical equine sheet and published documents
- The historical sheet `503dc301…` stays read-only on the server (`sheet.historical_read_only`) and in Git: no file
of `supabase/seed/anatomical-sheets/equine/` changes; `pnpm r5:import-equine --check` stays clean at every
sub-step; `anatomy_canvas_op.rs:27` keeps reading the seed unchanged.
- Published versions are immutable (`20261028110000:274-292`) and keep their bytes.
- Category ids never change (`id_changed`, `edit.rs:486-489`). Converting the equine working copy (roles on
`os`, `articulations`, `zone-colonne`, the renaming of `zone-colonne`, the three own colours) is V1-2.8 content
work, a reviewed edit of its draft, after decision T6. Nothing in V1-2.6 converts it.
### C. Proof of compatibility: N-1, PDF snapshots, worker, old drafts
- Snapshot: `lean_document` strips `role` and `fill_opacity`, and the export gate strips them on caller-built
snapshots and in `export_from_envelope`, so no path writes them into an envelope. The PDF needs neither (fill and
fill-opacity are overwritten in the highlight, `compose.rs:259-267`).
- N-1: a dedicated New-present sheet fixture and harness export PDFs that must pass the assertions of
`apps/app/tests/unit/n-1.reader.test.ts:178-196` (envelope success, archive kept, no `snapshotRejected`); the seed
path stays as it is. `contracts.types.test.ts:53-61` checks assignability: `ts(optional)` on both keys is
necessary and sufficient; it says nothing about runtime stripping, which the fixture test proves.
- Worker: the image is rebuilt from the same commit, checked against `git rev-parse HEAD` before the run (U1 adds
that guard), and `verify-e2e` runs a New-absent and a New-present draft.
- Old drafts and recovery copies are plain document texts read by the same strict reader.
- The readers of user data widen (`assert_snapshot`, used by `archive/read.rs`, accepts the keys): CLAUDE.md asks for
the owner's agreement before such a change; it is part of decision T2.
### D. Editing and translating curves without geometric degradation
Validated guarantee already held: a curve is never converted or simplified. Paths are displayed by the core; the
editor never reshapes them (level-1 C45) and offers « Remplacer par un polygone ». No document of the project holds
a path (the seed has 22 circles, 6 polygons, 0 paths), and no product path can create one: creation makes points
and polygons only (`creation.ts:93-97`), package import and zones from the drawing's shapes stay deferred
(`V1-2_ANATOMICAL_SHEETS.md:1330-1338`). Board 05 labels its curve card « exemple d'une autre fiche ».
Handle editing of curves (anchors, controls, translation) is therefore U9, proposed for deferral to the lot that
first lets a path enter a document (decision T16). Its specification is kept so it can start without a new study:
- Built on the existing reader (`path.rs`), extended to keep each number's byte span and a segment model (command,
absolute or relative, origin, anchor, explicit controls).
- `path_move_points` rewrites only the moved numbers and those that depend on them; every other byte stays.
Relative commands after a moved anchor are compensated so later absolute positions do not move; H or V moved off
their axis convert to L (splitting implicit runs); an S or T whose implicit control would change converts to C or
Q; arcs move their endpoint only (radii, rotation and flags untouched; a λ rescale is reported). Separators are
re-inserted where a sign or a dot would merge two numbers.
- `path_translate` changes only absolute coordinates and the leading `m`.
- Numbers: exact decimal arithmetic on the written digits, output precision = max(input precision of the number,
2 decimals for a user move), so compensation never moves another point and a translation round-trips exactly.
- Preview during a drag: page-side transform of the drawn path element (an SVG `transform` on the preview only), one
core call on pointer-up (BDR-050), never a core call per move.
- Implicit S/T controls are listed as non-editable; a control outside the frame is never judged on its own.
- Remap of a crop view holding a path is refused with a closed code until U9.
### E. Annotations when a crop view receives its own SVG
- Today the attach keeps the old `view_box` and changes only `svg_asset_id` (`drawingUpload.ts:185-192`): the frame
stays the crop rectangle R, read in the new drawing's space. For a drawing cut from the same master (the seed
head drawing has exactly the crop's `viewBox`), this is already right and annotations stay on their anatomy.
- For a re-based drawing (another export with a different `viewBox`), positions must be transposed. The editor
therefore offers an explicit choice when the new drawing's `viewBox` V differs from R: « Même repère : garder les
positions » or « Dessin recadré : transposer les annotations ». V equal to R: no question, positions kept
(decision T9 on wording and default).
- `sheet.remap_view {view_id, asset_id}` on the preview handle returns a batch of `sheet.edit` commands (the view
update and one `update` per remapped annotation), committed by the existing `commitBatch` as one undo entry under
the geometry accept (`editorEdit.ts:45-61`). The core reads R and V itself; the page supplies no number. Mapping:
one uniform scale and translation (`xMidYMid meet`, the composer's default); circles move their centre and scale
`r`; polygons every point; numbers on the 0.01 grid of the page; every remapped annotation `to_confirm` (by the
`update` rule, `edit.rs:495-509`).
- Scope: the view's own annotations, including the detail triggers drawn in it. Descendant views with their own
drawing are untouched. Refused as a whole, with closed codes: a descendant crop view without its own drawing
(`remap.descendant_crop`; no sheet has one), a path in the view (`remap.path`, until U9), `unknown_view`,
`no_frame`, `out_of_range`. A refusal or a remap whose end state fails the geometry accept leaves the document
unchanged and the uploaded drawing held, with a message; the editor can then attach with « garder les positions »
or abandon.
- Fixed user-unit sizes (twin offset 12, floor 2, strokes) do not scale, so `too_small` can change after a downscale;
the geometry accept and the repair dialog judge the end state.
### F. `annotations_in_rect`, name proposal, access placement
- Input `{view_id, rect}` on the preview handle; `rect` passes the frame range rule (`Frame::from_numbers`, made
`pub(crate)`). Output `[{id, relation}]` in document order, `relation` = `inside` | `partial`; names come from
`index.names`, already on the page.
- Geometry tested by bounds: circle by its hit-box disc (cx ± r, the box of the frame rule, `frame.rs:167-185`),
polygon and path by their bounds (`path_bounds` is tight on the shape). `inside` = bounds within the rect;
`partial` = bounds intersect. Over-reporting for concave shapes is conservative: it can only prevent an automatic
access, never place one over an annotation.
- Name proposal (page, display formatting from the core's list): FR and EN names of the `inside` annotations, in
document order, joined by the locale's list format, the first three then « … »; none inside → « Vue détaillée n »
/ « Detail view n », n = number of detail views + 1. Both fields stay editable.
- Access: the view and its access are inserted in one batch. The access is created automatically, with the drawn
rectangle as its polygon in the parent view, only when the overlap list is empty and the sheet has a category for
it (decision T10). Otherwise the box is unchecked with the reason stated, and the access is placed explicitly from
the view's menu (« Ajouter un accès »), which replaces the « Accès à une vue détaillée » toolbar tool (choice 6).
Until an access exists the view is `view.unreachable`, an error in the validation panel that blocks submission,
not saving; the creation flow says so and links to the placement.
### G. Polygon operations, undo and redo, invalid shapes
- Page operations, each one `sheet.edit update` of the whole annotation: vertex drag (preview on move, commit on
pointer-up), « + » inserts the segment midpoint after the segment's start vertex, « − » removes the chosen vertex,
zone drag translates every point, redraw replaces the points after the new trace is accepted.
- Protections before the core: « − » not offered at 3 vertices; no non-finite value committed; a vertex released on
its neighbour is a no-op; above a handle cap (implementation constant, recorded at U0) the shape shows its outline
and a message instead of one handle per vertex. The core judges the end state on commit (`invalid_shape` below 3
points; `out_of_frame`, `too_small`, `interior_too_small` through `issues.ts:123-175`). A refusal restores the
previous shape.
- Pending previews (a drag, arrow moves before Enter, a staged form) are cancelled and restored before any undo,
redo, document replacement, save reload, tab change or second pointer: index-based operations never apply to a
document they were not computed on.
- A second `pointerdown` during an armed drag cancels the drag and restores the shape (a pinch never moves a
handle). `touch-action: none` sits on the handle hit targets and in the explicit move mode; the canvas box keeps
panning (the browser reads `touch-action` at touchstart, `useCanvasGestures.ts:73-83`).
- Redraw: the old shape stays drawn and committed until the new trace closes and is accepted; Escape or a refusal
keeps the old one. One undo entry.
- Undo and redo: one entry per accepted commit, whatever the tab; header buttons, shortcuts and the toast call the
same `undo()`. The toast is dismissed by any commit, undo or redo, stays until then or until closed, is reachable
by keyboard, and its message is in a live region. Sliders (point size, opacity) and arrow moves commit on release,
Enter or blur only (BDR-050), so a keyboard walk never floods the 8 MiB history (about 20 entries of the equine
document).
- Keyboard: roving focus inside a shape (Tab enters the shape, arrows between handles when the handle list is
focused, then move the chosen handle in « move » state), Shift ×10, Insert or the visible « + » button, Delete or
Backspace or the visible « − » button, Enter commits, Escape restores. Arrows pan only when the canvas box itself
has focus.
- Self-intersection stays allowed (nonzero rule decides, `interior.rs:33-34`); no new polygon rule.
### H. Tests
Detail per sub-step in `V1-2-6_UX_TESTS.md`: core unit and conformance, seeded property tests in Rust (no new
dependency), table tests in TypeScript, hostile inputs at the op level, N-1 on a New-present fixture, oracles and
seed untouched, axe, keyboard and touch journeys, sandbox and worker runs.
### I. Decisions that block before any code
Each sub-step lists the decisions it consumes; the single table is in `V1-2-6_UX_DECISIONS.md`. Before U1: T11.
Before U5: T9, T10 (and T1 if the measure exceeds the budget). Before U6: T2, T3, T4, T5, T17. Before U7: T12.
Before U9: T16.
---
## 3. Sub-steps
Order: U0, U1, then U2 to U4 (frontend), U5 (first core queries, consumer-driven), U6 (model), U7 (common text,
when its wording exists), U8 (closure). U9 (curves) is proposed for deferral. Each sub-step ends at an owner
checkpoint; the next starts after the owner accepts it.
Common rules for every sub-step that touches code:
- Work in `/home/bchanot/Documents/faunosteo-v1-2`, every shell command with that absolute path verified first
(LRN-110). Commit in place on `feature/v1-2-anatomical-sheets`, one commit per coherent change; rollback = revert
of the sub-step's contiguous commits. No sub-branch (the gitflow lib only branches from develop), no merge, no
`gitflow.sh finish`.
- Gates: `pnpm typecheck`, `pnpm test:run`, `pnpm lint`, `pnpm build`; after any change under `crates/core` or
`crates/wasm`, `pnpm rust:check` and `pnpm wasm:build` first and the size figure recorded; `pnpm check:all` before
the checkpoint; fresh verifier and security review.
- Database: `pnpm db:sandbox` only (`up fresh`, `up upgrade`, `test-db`, `types --check`, `e2e-shell`, `test`,
`verify-e2e`), in the order `test-db → e2e:shell → test` (LRN-113). Forbidden: `pnpm db:start`, `db:reset`,
`db:test`, `db:types`, `pnpm supabase …`, `e2e:avatar` and `e2e:sheet-assets` outside their sandbox aliases, any
command reaching DEV. The CLAUDE.md line « SQL change: db:reset && db:test » does not apply to this plan.
- The sandbox and the worker image tag are shared with the other checkouts of this machine
(`scripts/db-sandbox.sh:47-60`): no other checkout runs them during V1-2.6; the owner-trial stack is rebuilt only
after telling the owner (it wipes trial accounts and data).
- Owner demos run on a sandbox demo sheet provisioned by the same upload path as `editor-equine.spec.ts:81-104`
(the equine drawing uploaded through the application), not on the historical working copy, which the missing
sandbox drawings block (separate track).
### U0 · Contract, decisions and amendments (docs only)
- Objective: record the owner's answers to `V1-2-6_UX_DECISIONS.md` and amend the ratified texts the validated UX
replaces.
- Files: `docs/development/V1-2_ANATOMICAL_SHEETS.md` §7.4 (common text), §8.2 (no coordinate fields, fixed
categories, colour shown when set, access created with the view), §8.3 (vertex drag and the crop rectangle leave
level 2; curves per T16), §8.4 (O14 A kept, tablet rule), §16.7 (new state); the level-1 contract
`.claude/tasks/contracts/2026-11-03-v1-2-6-editor-1509.md` (C3, C4, C6, C7, C8, C13 wording to match the code key,
C32, C33, C40); `docs/design/README.md` (v1-2-6 boards replace V1-2.4 boards 04 and 05 for the editor, BDR-096);
`.claude/rules/sheet-model.md` (optional keys under T2; rules may also live in `edit.rs` and `sheet_report`) and
`schemas.md`; the implementer decisions (T7, T8, handle cap, branch policy); `.claude/memory/decisions.md` via
`memory.sh`.
- Dependencies: owner answers.
- Rust ops: none. Tests: a fresh verifier checks the amendments against the answers.
- Acceptance: each decision recorded once and cited where it applies; no contradiction left between the contract,
the level-1 criteria and the boards.
- Owner demo: read the amended sections. Rollback: revert.
- Checkpoint: owner approves the amended contract.
### U1 · Shell: four tabs, header undo, references panel, tablet layout, sandbox guard
- Objective: General, Annotations, Findings, Verification; views, drawings, vertebral regions and categories in
Annotations; References as a side panel from the header or a finding; Undo and Redo in the header on every tab;
sidebar hidden in the editor below 1 280 px with the menu one tap away; « Aller à » retargeted. Tooling: the
sandbox `verify-e2e` refuses an image whose commit label differs from `HEAD`; the trial command provisions the
demo sheet.
- Files: `app/editor/tabs.ts`, `EditorTabs.tsx`, `EditorTabBody.tsx`, `DraftHeader.tsx`, `components/editor/tabs/*`,
`app/editor/verification.ts:64-131`, `PropertiesPanel.tsx:169`, `components/shell/AppLayout.tsx:72-123`,
`ToolColumn.tsx`, i18n; `scripts/db-sandbox.sh` (image check, demo sheet), `crates/worker/Dockerfile` (commit
label).
- Dependencies: U0, T11.
- Rust ops: none.
- Tests: `V1-2-6_UX_TESTS.md` U1.
- Acceptance: four tabs at 1 024 px and wider; every existing editor journey green on the new shell; narrow-width
read-only unchanged; undo from any tab reverts the last accepted change; a stale worker image is refused.
- Owner demo: on the demo sheet, switch tabs, undo a General change from Annotations, open References from a
finding, resize to 1 180 px.
- Risk: broad test rewrite (each removed assertion mapped to its replacement). Rollback: revert, no data change.
- Checkpoint: owner validates the shell.
### U2 · Direct manipulation of points and polygons
- Objective: boards 02 to 06 and 13 for points and polygons (curve handles excluded, U9): point move and size
slider snapping to the radii of the view with the red minimum mark; vertex drag; « + » per segment; « − » on the
chosen vertex; zone drag directly with the mouse once selected, explicit « Déplacer la zone » mode by touch; redraw
keeping the old shape until accepted; 44 px touch handles; pointer rules and keyboard of §2 G; the toast;
coordinate fields leave the normal journey.
- Files: `AnnotationOverlay.tsx` (interactive handle layer), `EditableAnnotations.tsx`, `GeometryGroup.tsx`,
`PropertiesPanel.tsx`, `TracingBar.tsx`, `ToolColumn.tsx`, `KeyboardAdd.tsx`, `useMoveGesture.ts`, `gesture.ts`,
`geometryEdit.ts`, `usePlacement.ts`, `useCanvasGestures.ts`, `app/catalogue/useFraming.ts`, a toast in
`components/ui`; core: `anatomy/frame.rs` and `domain/sheet/preview.rs` (per-view minimum visible radius in
`PreviewState`), types and wrapper.
- Dependencies: U1.
- Rust ops: one read-only value (minimum visible radius per view, from the `marker_too_small` threshold,
`frame.rs:67`, `220`), so the page draws the mark without a TypeScript size rule (BDR-043, C32).
- Tests: `V1-2-6_UX_TESTS.md` U2.
- Acceptance: every listed gesture works with mouse, touch (1 024, 1 180 and 1 280 px) and keyboard; a refused shape
is restored exactly; no coordinate field in the normal journey; latency under the 500 ms budget.
- Owner demo: on the demo sheet, move a point, change its size, drag a vertex of « Thoraciques », add and remove a
vertex, move the zone, redraw it and cancel, undo each step; same on a tablet in landscape.
- Risk: touch and keyboard conflicts (§2 G). Rollback: revert (the core value is additive and unused once reverted).
- Checkpoint: owner tries mouse and tablet.
### U3 · Category panel and own colour
- Objective: board 07 states A to D without the fixed-role locks (they come at U6): foldable panel in Annotations,
swatch with the name next to it, 16-colour palette plus hex, staged form with « Appliquer » (the drawing previews
the candidate document on the preview handle, the store commits one batch on Apply, Cancel restores), delete when
unused, « Réaffecter à… » when a delete is refused (one batch of annotation updates, one undo entry); own colour of
an annotation shown only when set, with « Revenir à la couleur de la catégorie »; new annotations inherit.
- Files: `components/editor/general/CategoriesSection.tsx` (moved), `AnnotationFields.tsx:96-104`,
`AnnotationList.tsx:53-73`, `editorEdit.ts` (preview without commit), i18n.
- Dependencies: U1.
- Rust ops: none.
- Tests: `V1-2-6_UX_TESTS.md` U3.
- Acceptance: board 07 A to D minus the locks; board 03 colour behaviour; equine own colours shown and revertible.
- Owner demo: recolour a category with preview, cancel, apply; reassign and delete a category; revert an own colour.
- Risk: preview without commit must never leak into history. Rollback: revert.
- Checkpoint: owner.
### U4 · Detail view by rectangle (manual)
- Objective: « Créer une vue détaillée » draws a rectangle on the parent drawing (handles, keyboard resize) and sets
the new view's `view_box`; names typed; the access placed from the view's menu (« Ajouter un accès »); the toolbar
tool « Accès à une vue détaillée » and the numeric crop editor leave the normal journey.
- Files: `CropCanvas.tsx`, `DetailViewForm.tsx`, `CropEditor.tsx`, `DetailViewRow.tsx`, `ToolColumn.tsx`,
`app/editor/viewBox.ts`, `viewUpdate.ts`, i18n.
- Dependencies: U2.
- Rust ops: none (the core refuses an unusable frame: `view.frame.unknown`).
- Tests: `V1-2-6_UX_TESTS.md` U4.
- Acceptance: a detail view created and opened without typing a number; `view.unreachable` shown until its access
exists.
- Owner demo: create « Coude » on the main view, place its access, open it in the preview.
- Rollback: revert.
- Checkpoint: owner.
### U5 · Detail view assisted: `annotations_in_rect`, `remap_view`, name, access, specific SVG
- Objective: the two core queries, consumed in the same sub-step: proposed FR/EN name, automatic access only
without overlap, explicit placement otherwise; « Remplacer par un SVG spécifique » with the explicit choice of §2 E.
- Files: core `anatomy/frame.rs` (`from_numbers`, `holds` to `pub(crate)`), new `domain/sheet/rect.rs` and
`domain/sheet/remap.rs`, `ops.rs` (`call_with_preview`), types, `packages/core-wasm/src`, `app/core/*`,
`DetailViewForm.tsx`, `CropCanvas.tsx`, `drawingUpload.ts:184-192`, `ViewDrawing.tsx`, `RepairDialog.tsx`, i18n,
`RUST.md` §12.
- Dependencies: U4; T9, T10; T1 if the measure exceeds the budget.
- Rust ops: `sheet.annotations_in_rect`, `sheet.remap_view` (§2 E, F). Order: `annotations_in_rect` first, size
measured; then `remap_view`, size measured; a budget excess stops the sub-step for T1.
- Tests: `V1-2-6_UX_TESTS.md` U5.
- Acceptance: board 08; no access ever created over an annotation; « garder les positions » and « transposer » both
proven on fixtures; one undo entry per remap; size within budget or T1 applied.
- Owner demo: board 08 on the demo sheet; attach the seed head drawing to a crop (positions kept, no question);
attach a re-based fixture drawing (transposition offered).
- Risk: size; bounds over-report. Rollback: revert (documents written are plain v2).
- Checkpoint: owner.
### U6 · Category model: fixed categories, fill opacity, vertebral regions from the category
- Objective: route A (§2 A); `sheet.empty` creates the three categories; edit refusals and report issues; the layer
applies `fill_opacity` (decision T3); snapshot and export gate strip both keys; the panel locks the fixed
categories (no delete, name read-only, role badge, « Couleur d'origine » from T5) and gains the opacity slider and
field; board 09: regions open from the vertebra-role category, the region picker of a zone filtered to the
vertebra-role category's annotations (page filter, no rule), staged « Appliquer » with the error count; fallback
per T17 when no category has the role (the equine copy before V1-2.8). `docs/ANNOTATION-RENDERING.md` amended
first; round-withdrawal migration (contract `945-949`) if T4 adds report issues.
- Files: core `domain/sheet/schema.rs`, `create.rs`, `edit.rs`, `report.rs`, `anatomy/layer.rs` (`layer()` 85-102,
`Context::point` 242, `zone_visual` 297-304), `domain/archive/snapshot_rules.rs:141-165`,
`pdf/write/input.rs:174-181`, `export.rs:27-37`, types; app `refusal.ts`, the category panel, the regions dialog
(`components/editor/vertebrae/*`), i18n; SQL `supabase/migrations/<timestamp>_sheet_rounds_withdraw_v1_2_6.sql`
(name provisional); docs `ANNOTATION-RENDERING.md`, `ANATOMICAL_SHEET_MODEL.md` (spec table), `RUST.md`,
`DEPLOY.md` (order).
- Dependencies: U3, U5; T2, T3, T4, T5, T17.
- Rust ops: schema fields, edit refusal kinds, report issues, layer reading, snapshot stripping.
- Tests: `V1-2-6_UX_TESTS.md` U6; each row of `V1-2-6_UX_COMPATIBILITY.md` is an acceptance line.
- Acceptance: compatibility matrix proven row by row; oracles, goldens and seed unchanged; N-1 reads New-present
PDFs; worker verdict on both kinds of draft; the contract §16.7 journey on a non-equine sheet with the new UX
reaches `open` after the worker verdict.
- Owner demo: new species sheet with its three categories, custom opacity, regions from Vertèbres, PDF exported and
reopened.
- Deploy order and rollback: `V1-2-6_UX_COMPATIBILITY.md` §7. Rolling back below U6 is impossible once a document
with the keys exists (sandbox only until the owner decides otherwise).
- Checkpoint: owner.
### U7 · Scope and limits: one-time copy of a versioned common text
- Starts only when the owner has supplied the validated wording (T12); no text is written by the implementer.
- Objective: when both disclaimer fields are empty, « Insérer le texte commun (version n) » copies FR and EN once;
afterwards the fields are free text; a read-only comparison shows the current version; no automatic change ever
reaches a draft or a published version.
- Files: a versioned template module in `apps/app/src`, `components/editor/general/TextsSection.tsx`, i18n; the
change note records the template id and version.
- Rust ops: none (one `update` of the sheet texts).
- Tests: `V1-2-6_UX_TESTS.md` U7.
- Acceptance: board 10; contract §7.4 as amended at U0.
- Owner demo: insert, edit, compare. Rollback: revert.
- Checkpoint: owner and the person responsible for the wording.
### U8 · Closure
- Objective: recovery and conflict journeys re-run on the new UX; the contract §16.7 acceptance on the sandbox;
documents and TODO closed; `V1-2-6_OWNER_TRIAL.md` updated.
- Dependencies: U1 to U6 (U7 when its wording exists; U9 per T16).
- Tests: `V1-2-6_UX_TESTS.md` U8.
- Checkpoint: owner trial of the redesigned editor; V1-2.7 stays closed until the owner opens it.
### U9 · Curves (deferral proposed, decision T16)
- Objective, if the owner keeps it in V1-2.6: board 05 curve handles (§2 D), curved zone move, remap of paths, the
C45 refusal replaced by real correction.
- Files: core `anatomy/path.rs`, `ops.rs`, types, wrappers; app `AnnotationOverlay.tsx`, `useMoveGesture.ts`,
`repair.ts:60-100`; SQL round-withdrawal migration (the path reader feeds the frame and interior verdict rules,
`frame.rs:25`, `interior.rs:23`); `RUST.md`.
- Dependencies: U2, U5; T16, T1 (a lever is certain).
- Rust ops: `sheet.path_points`, `sheet.path_move_points`, `sheet.path_translate`.
- Tests: `V1-2-6_UX_TESTS.md` U9, including a frozen pre-U9 oracle of `number_list`, `path_bounds` and
`path_outline` on a corpus, compared byte for byte after the change.
- Acceptance: a path of a fixture sheet (never the seed) edited point by point, saved, reloaded with every untouched
number byte-identical.
- Rollback: revert; paths go back to display only.
- Checkpoint: owner.
---
## 4. Frontend-only versus model and core
| Sub-step | App | Rust core | Schema | SQL | Worker image |
|---|---|---|---|---|---|
| U0 | no | no | no | no | no |
| U1 | yes | no | no | no | label only |
| U2 | yes | one read-only value | no | no | no |
| U3, U4 | yes | no | no | no | no |
| U5 | yes | two queries | no | no | no (the worker calls neither) |
| U6 | yes | yes | optional keys | round withdrawal (T4) | rebuilt, deployed before the app |
| U7 | yes | no | no | no | no |
| U8 | no | no | no | no | rebuilt for the final run |
| U9 | yes | path ops | no | round withdrawal | rebuilt, deployed before the app |
## 5. Out of scope, tracked separately
- TOTP asked at sign-in for accounts with a factor.
- The historical equine drawings missing on the sandbox, which block the working copy.
- Full touch editing on the phone (boards 14 to 16 kept as the reference of that future lot); O14 A stays.
- A multi-tab notice (not in the validated boards; the server revision check and the conflict dialog already guard
against lost writes): proposed as a follow-up, decision T14.
The first three are in `.claude/tasks/TODO.md` (V1-2 section); T14 is added there if the owner keeps it.
## 6. Independent review record (2026-11-05)
Three fresh plan challengers, one lens each, on the first version of the five files: correctness CONCERNS(5),
robustness CONCERNS(9), simplicity CONCERNS(6); no BLOCKER. Integrated:
- The U7a/U7b expand-then-write split did not hold (`sheet.empty` writes the keys from the first new sheet) and
protected no environment: one model sub-step (U6) with the rollback limit stated.
- M9 dropped: report issues map to the existing `verification.validation.rules` (`verdict.rs:277-296`); the
round-withdrawal migration of contract `945-949` added to U6 and U9, with a frozen pre-U9 reader oracle.
- Sub-branches dropped (the gitflow lib branches only from develop): commit in place, rollback by revert.
- Curves: no document holds a path; U9 proposed for deferral (T16); the size lever becomes a fallback measured op by
op (T1), the PDF split a separate track.
- Remap: the seed head drawing has the crop's exact `viewBox`, so the remap is an explicit choice, never automatic;
returned as a command batch through `commitBatch`; descendant crops and paths refused with closed codes.
- Pointer and keyboard: second pointer cancels the drag; pending previews cancelled before undo, redo, replacement
or tab change; toast dismissed on any commit; sliders commit on release; `touch-action` on handle targets; roving
focus, Backspace, live region; touch tests at 1 024, 1 180 and 1 280 px; handle cap.
- Sandbox safety: forbidden DEV-reaching SQL commands listed; image checked against `HEAD`; shared sandbox and
owner-trial stack rules; owner demos on a provisioned demo sheet.
- Missing UX elements added: board 09 (regions from the vertebra-role category), board 07 « Réaffecter à… »,
« Couleur d'origine » and staged Apply, the red minimum mark (one core value), removal of the access tool.
- Corrections of fact: equine names (only `zone-colonne` differs), the ts-rs/N-1 test is an assignability test, the
N-1 runtime proof needs a New-present fixture, C32 and C33 added to the U0 amendments, the reader-of-user-data
agreement added to T2.
- Duplication reduced: one decision table (DECISIONS), one deploy-order statement (COMPATIBILITY §7); T7, T8, T13
turned into implementer decisions; the multi-tab notice moved to a follow-up (T14); U7 (common text) starts only
when the wording exists.
Not adopted: the simplicity lens recommended `edit.rs` refusals only (T4 option a). The plan keeps report issues
because they cost no SQL code once mapped to the existing verdict code and keep the core as the authority (O22);
the owner decides under T4. No second review was run on the corrected version.
+47
View File
@@ -0,0 +1,47 @@
# V1-2.6 UX redesign: risk register
Status: PROPOSAL, 2026-11-05, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md`. Blocking
decisions live in `V1-2-6_UX_DECISIONS.md` (single table); sub-step dependencies in the plan (§3, each sub-step's
« Dependencies »); deploy order and rollback in `V1-2-6_UX_COMPATIBILITY.md` §7. Probability and impact: H high,
M medium, L low.
| Id | Risk | P | I | Mitigation | Where checked |
|---|---|---|---|---|---|
| R-1 | New category keys written as `null` when absent: every fingerprint, review digest, equine sheet-ref, alias and R4 app-path digest changes | H without a pin | H | `skip_serializing_if` + `js::present`; tests pin fingerprint `12d78872…`, alias `27c7383c…`, seed digests | U6 |
| R-2 | An unconditional `validate.rs` rule on roles strips fingerprints of existing documents and rejects old PDF snapshots | H if done | H | rules only in `edit.rs` and `sheet_report` | U6 review |
| R-3 | Direct save, or « Garder ma version » from an older bundle, strips roles of a never-published sheet | M | M | report issues against the base; residual accepted under T4, visible in the `general` review | U6 |
| R-4 | Worker older than the app reads a New-present draft: definitive `integrity.document` | H on skew | M | one commit for both images; worker before app; `verify-e2e` refuses a stale image | U1 guard, U6 |
| R-5 | Rounds in flight across a rule or reader change keep a verdict of the old core | M | M | round-withdrawal migration in U6 (T4) and U9, tested with `up upgrade` and live rounds | U6, U9 |
| R-6 | A caller-built snapshot or `export_from_envelope` carries the keys: N-1 and older apps drop the snapshot | M | M | strip at both points (T7); N-1 test on a New-present fixture | U6 |
| R-7 | Opacity written as anything but `fill-opacity` would reach the PDF (category colour already reaches strokes) | L | M | layer writes `fill-opacity` only | U6 |
| R-8 | Budget exceeded mid-sub-step | M | M | measure after each op; T1 fallback; PDF split never on the critical path | U5, U6 |
| R-9 | Rollback below U6 impossible once a New-present document exists (drafts unreadable by the old app and worker, published rows immutable, migrations forward-only) | certain after U6 | H | sandbox only until the owner decides; release-readiness item (new RR id, reconciled with develop where RR-11 is taken) | U6 |
| R-10 | An executor follows the CLAUDE.md SQL line (`db:reset`, `db:test`, `db:types`) and reaches DEV | M | H | plan forbids them and lists the sandbox commands; LRN-110 absolute-path rule in every brief | every SQL sub-step |
| R-11 | Shared sandbox and worker tag: another checkout replaces the stack or image between rebuild and test | M | M | no other checkout runs them during V1-2.6; image label checked against `HEAD` | U1 guard |
| R-12 | Rebuilding the sandbox wipes the owner-trial stack | M | L | tell the owner before any `down` or `up fresh` | every sub-step |
| R-13 | Automatic remap moves correct annotations of a drawing cut from the same master | H if automatic | M | explicit choice; positions kept when `viewBox` equals the crop (T9) | U5 |
| R-14 | Remap of a subtree with descendant crops or paths | L | M | closed refusals `remap.descendant_crop`, `remap.path` | U5 |
| R-15 | A pinch with finger 1 on a handle moves the handle | H on touch | M | a second pointerdown cancels the armed drag; two-touch test starting on a handle | U2 |
| R-16 | Undo, redo or a document replacement during a pending preview resurrects a change or moves the wrong vertex | M | H | pending previews cancelled before any of them | U2, U3 |
| R-17 | Toast undoes a different action than it names | M | L | dismissed on any commit, undo or redo | U2 |
| R-18 | Arrow keys pan and move handles | H | M | focus decides | U2 |
| R-19 | Sliders flood the history | M | M | commit on release or blur (T19); history depth test | U2, U6 |
| R-20 | `touch-action` read at touchstart: a late change breaks one-finger handle drags | M | M | `touch-action: none` on handle hit targets and in move mode, box keeps pan | U2 |
| R-21 | Oversized shapes render thousands of handles | L | M | handle cap (T18) | U2 |
| R-22 | Keyboard gaps: no Insert or Delete on compact keyboards, Tab through every vertex, toast timing | M | M | Backspace and visible buttons, roving focus, persistent toast, live region | U2 |
| R-23 | Header undo after typing reverts the typing, not the previous action | M | L | flush the field first, pinned by a test | U1 |
| R-24 | Large test rewrite hides lost coverage | M | M | each removed assertion mapped to its replacement; verifier checks the mapping | U1, U2 |
| R-25 | Touch only tested in Chromium; WebKit and real tablets differ (LRN-108) | M | M | owner trial on a real tablet at U2 and U8 | owner |
| R-26 | Owner demos depend on the equine working copy blocked on the sandbox | certain | M | demo sheet provisioned through the application upload path | U1 |
| R-27 | Preview of a staged category form leaks into history | M | M | preview on the handle only, commit on Apply, restore on Cancel | U3 |
| R-28 | Two tabs on one draft: the second learns at its save; « Garder ma version » overwrites the first | H if used | M | unchanged from level 1; follow-up T14 | n/a |
| R-29 | Undo crosses a save; `addDrawing` outside history | L | L | kept as built; stated in the trial guide | U8 |
| R-30 | 0.1.0 production reader behaviour on new PDFs unknown | unknown | M | read before any production release carrying U6 | release track |
| R-31 | Bounds-based overlap over-reports for concave shapes | M | L | conservative by design | U5 |
## Separate tracks (kept out, tracked in TODO.md)
- TOTP asked at sign-in for accounts with a factor.
- Historical equine drawings missing on the sandbox, which block the working copy.
- Full phone editing, a future lot after V1-2 (boards 14 to 16 kept as its reference).
- RR-12, the AAL2 token after factor removal (production prerequisite, unchanged by this plan).
+134
View File
@@ -0,0 +1,134 @@
# V1-2.6 UX redesign: test matrix per sub-step
Status: PROPOSAL, 2026-11-05, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md` (the common
rules of §3 apply: absolute paths, sandbox-only database commands, forbidden commands). No test is written before
the owner approves the plan.
## Common gates
| Gate | Command | When |
|---|---|---|
| Core | `pnpm rust:check` then `pnpm wasm:build` | any change under `crates/` |
| App and packages | `pnpm typecheck`, `pnpm test:run`, `pnpm lint`, `pnpm build` | always |
| Size | `packages/core-wasm/tests/size.test.ts` (Node gzip ≤ 600 000 B), figure recorded in RUST.md | any change under `crates/core` or `crates/wasm` |
| Seed and pipeline | `pnpm r5:import-equine --check` with no difference | always |
| Frozen references | no change under `crates/core/tests/oracles/`, `apps/app/tests/fixtures/goldens/`, `supabase/seed/` (`git diff --stat` on those paths is empty) | always |
| Browser, no backend | `pnpm e2e:ui` | always |
| Sandbox | `pnpm db:sandbox up fresh`, then `test-db → e2e-shell → test` (LRN-113) | always |
| Worker | `pnpm worker:image`, then `pnpm db:sandbox verify-e2e` (refuses an image not built from `HEAD` after U1) | U1, U6, U8, U9 |
| Pre-checkpoint | `pnpm check:all` | every code sub-step |
| Reviews | fresh verifier on the sub-step contract; fresh security review on the diff | every sub-step |
Property tests: seeded generators inside Rust tests (fixed-seed linear congruential sequence, a few thousand cases
per property, a failing seed kept as a regression case); no new dependency. TypeScript arithmetic is covered by
table tests.
Accessibility: axe with zero serious or critical violations per state (`docs/development/BROWSER_TESTS.md:73-91`),
keyboard-only journeys, a text next to every colour, visible focus on every handle. Chromium only until V1-5; WebKit
and real tablets are owner trials.
## U0 · Contract and decisions
| Kind | Test |
|---|---|
| Review | fresh verifier: each answer recorded once and cited where it applies; no contradiction between contract §7.4, §8.2-8.4, §16.7, the level-1 criteria (C3, C4, C6, C7, C8, C13, C32, C33, C40) and the boards |
## U1 · Shell
| Kind | Tests |
|---|---|
| Unit | four-tab model, initial tab, width tiers (replaces `editor-route.test.tsx:66`, `128-170`, `editor-mode.test.ts:99-110`); header undo and redo states; undo from each tab reverts the last commit made on another tab; a typed field is flushed before the header undo (behaviour pinned); references panel open, close, return focus; « Aller à » target for every issue kind (`verification.ts:64-131`) |
| E2E shell | helpers rewritten (`e2e/support/editor.ts:326-330`, `warm-up.ts:43-45`, `editor-access.spec.ts:34-42`); every existing editor journey green on the new shell; sidebar hidden in the editor at 1 024, 1 180, 1 279 px, shown at 1 280 px, menu reachable in one tap; narrow-width read-only unchanged |
| Tooling | `verify-e2e` refuses an image whose commit label differs from `HEAD`; the trial command provisions the demo sheet through the application upload path |
| Accessibility | axe on the four tabs and on the open references panel; Tab order header → tabs → panel → canvas |
| Regression | recovery and conflict specs unchanged; each removed assertion mapped to its replacement in the commit message |
## U2 · Points and polygons
| Kind | Tests |
|---|---|
| Unit (tables) | slider stops = distinct radii of the view; snapping; red mark from the core value; midpoint insert after the segment start; « − » hidden at 3 vertices; zone translation; nearest-handle priority; keyboard map (arrows, Shift ×10, Insert or Backspace or Delete, Enter, Escape, roving focus); arrows pan only when the box is focused; handle cap fallback |
| Unit (state) | pending preview cancelled and restored on undo, redo, document replacement, tab change, second pointer; toast dismissed on any commit, undo or redo; slider commits once on release (history depth after a keyboard walk) |
| Core | the per-view minimum visible radius equals the `marker_too_small` threshold on the equine views and on edge frames |
| E2E mouse | drag a vertex, « + », « − », zone drag on a selected zone, redraw accepted, redraw refused by `interior_too_small` restores the old shape, undo and redo of each, toast « Annuler » undoes the same entry as the header |
| E2E touch (`hasTouch`, 1 024, 1 180, 1 280 px) | one-finger handle drag; explicit « Déplacer la zone » mode; finger 1 on a vertex handle then finger 2 elsewhere: the pinch zooms, the drag is cancelled, no commit (CDP `Input.dispatchTouchEvent` with two points); page scroll over the canvas with a selection and outside it |
| Keyboard | create a zone, add and remove a vertex, move the zone, validate, without a pointer; Ctrl+Z on a focused handle after arrow moves restores the pre-move shape |
| Accessibility | axe on selection, tracing and move states; handle names (« sommet 3 de Thoraciques »); live-region message after a move |
| Performance | commit latency under the 500 ms budget (`editor-equine.spec.ts:25-34`) for drag, insert, remove |
## U3 · Category panel and own colour
| Kind | Tests |
|---|---|
| Unit | own colour hidden when null; « Revenir à la couleur de la catégorie » sends one `update` with `color: null`; new annotations carry no colour; staged form: preview leaves history untouched, Apply commits one batch, Cancel restores the handle; « Réaffecter à… » commits one batch and one undo entry |
| E2E | demo sheet with the equine own colours: atm shows `#ff8800`, revert, undo; recolour with preview, cancel, apply; reassign then delete a category |
| Accessibility | every swatch has its name next to it; palette keyboard-operable; axe on states A to D |
## U4 · Detail view by rectangle (manual)
| Kind | Tests |
|---|---|
| Unit | rectangle normalised from any drag direction and clamped to the parent frame; keyboard resize of its handles; toolbar without the access tool; view menu « Ajouter un accès » |
| E2E | create a detail view by mouse and by keyboard, `view.unreachable` until its access exists, place the access, open the view in the practitioner preview |
| Core regression | `compose.rs` tests and canvas goldens unchanged |
| Accessibility | axe on creation and placement states |
## U5 · Detail view assisted
| Kind | Tests |
|---|---|
| Rust `annotations_in_rect` | circle, polygon, path, trigger; inside, partial, none; rect on an edge; empty view; unknown view; invalid rect |
| Rust `remap_view` | same aspect, different aspect (uniform, centred); triggers drawn in the view remapped; descendant view with its own drawing untouched; descendant crop refused (`remap.descendant_crop`); path refused (`remap.path`); no frame refused; output = command batch; numbers on the 0.01 grid |
| Properties (seeded) | identity mapping returns the geometry exactly; mapping then inverse within 0.01 per number; `inside` ⇒ bounds within the rect; a rect equal to the frame ⇒ every annotation of the view `inside` |
| Hostile (op level) | non-finite and out-of-range rect, unknown ids, oversized command output bounded; no panic |
| Wasm | core-wasm proofs through the preview handle; size gate after each op, figure printed |
| Unit app | name formatting FR and EN (one, two, three, more with « … », none → « Vue détaillée n »); access box checked only with an empty overlap list and a category available; view and access inserted in one batch |
| E2E | board 08: rectangle over the elbow, proposed name, access unchecked with its reason, explicit placement, preview; rectangle over an empty area: access created, no annotation under it; attach the seed head drawing to a crop with the same `viewBox`: no question, positions kept; attach a re-based fixture drawing: choice offered, transposition, all remapped annotations `to_confirm`, one undo entry; a remap failing the geometry accept leaves the document unchanged and the drawing held |
| Accessibility | axe on the dialogs; the reason of the unchecked box is announced |
## U6 · Category model
| Kind | Tests |
|---|---|
| Rust serialisation | both keys round-trip; absent keys not written (no `role` or `fill_opacity` text in the re-serialised seed); explicit `null` refused; out-of-range opacity and unknown role refused |
| Rust identity pins | equine fingerprint `12d78872…` and alias `27c7383c…` recomputed equal; every seed review digest equal to its value pinned before the change; `characterisation_serde_tolerance.rs`, `sheet_fingerprint.rs`, `r5_6_switch.rs` green unchanged |
| Rust rules | edit refusals (remove, role change, duplicate role, rename of a role-bearing category); report issues against a base (role disappears, duplicate role) mapped to `verification.validation.rules`; none fires on the seed, the oracles or any fixture; `validate.rs` issue lists identical before and after on every fixture |
| Rust empty sheet | `sheet.empty` creates the three categories with the T5 ids, names, roles and colours and passes `sheet.check` |
| Rust layer | absent keys → R3 trees identical; present `fill_opacity` changes only the twin and zone fill attributes; triggers unchanged; `svg_marker_isolation.rs` green |
| Rust snapshot | `lean_document` and the export gate strip both keys; a snapshot from a New-present document passes the gate and the N-1 shape |
| App and N-1 | New-present sheet fixture and harness: exported PDFs pass the assertions of `n-1.reader.test.ts:178-196`; `contracts.types.test.ts` green with `ts(optional)`; `measure.test.ts` green; PDF goldens unchanged |
| SQL | the round-withdrawal migration: pgTAP with rounds in `verifying`, `open`, `approved` before it and withdrawn after with the reason; `pnpm db:sandbox up upgrade` from the current migration set; `types --check` |
| Worker | image rebuilt from `HEAD`; `verify-e2e` with a New-absent and a New-present draft; verdict passes for both |
| Unit and E2E app | board 07 locks (no delete, name read-only, role badge, « Couleur d'origine »); opacity slider and field synchronised, commit on release; board 09: regions from the vertebra-role category, picker filtered, staged « Appliquer (n erreurs) »; fallback entry when no category has the role (T17) |
| Acceptance journey | a new non-equine sheet with the new UX (drawing, rectangle view, points, zones, access, findings, custom opacity), saved, submitted, worker verdict passes, round `open`; its PDF exported, reopened by the app and read by N-1 (archive kept) |
| Recovery | a copy taken before an opacity edit restored after reload; conflict journey on a role-bearing category; « Garder ma version » with a keyless document shows the report issue |
| Security | fresh review: no path writes the keys into an envelope; no new SQL business rule |
| Accessibility | axe on board 07 and 09 states; the opacity value is exposed to assistive technology |
## U7 · Common text
| Kind | Tests |
|---|---|
| Unit | insertion only into empty FR and EN fields; never overwrites; template id and version in the change note; comparison read-only |
| E2E | insert, edit, undo, save, reload |
| Accessibility | axe on General with the comparison open |
## U8 · Closure
| Kind | Tests |
|---|---|
| Full run | common gates, `check:all`, sandbox order, `verify-e2e`, N-1 suite, frozen references unchanged, axe on every tab and state, keyboard-only journey, tablet touch journey |
| Acceptance | contract §16.7 journey re-run on the redesigned editor |
| Owner trial | `V1-2-6_OWNER_TRIAL.md` updated; WebKit iPad and a real tablet by the owner |
## U9 · Curves (if kept, T16)
| Kind | Tests |
|---|---|
| Frozen reader oracle | before any change: `number_list`, `path_bounds`, `path_outline` on a corpus (fixtures, hostile paths, owner exports) recorded; compared byte for byte after the change |
| Rust conformance | every command absolute and relative; implicit repeats; M followed by pairs; H and V along and off axis; S and T kept or converted; arcs (endpoint move, λ rescale reported); Z then relative; numbers at ±2^20, exponent forms, `.5.5`, `1-2` separator merges |
| Properties (seeded) | untouched numbers keep their bytes; moving point i never changes the absolute position of point j ≠ i (exact decimal arithmetic); translate then inverse translate restores the path byte for byte; bounds after translate = bounds shifted |
| Hostile | unreadable `d`, 2 MiB `d`, unknown index, non-finite or out-of-range move; no panic |
| SQL | round-withdrawal migration, as U6 |
| E2E | fixture sheet with paths (never the seed): drag an anchor, a control, move the zone, save, reload, untouched bytes identical; remap of a crop view holding a path; preview transform during the drag, one core call on release |
| Size | gate with the figure printed |