From 14fb527552c1b603920c47014655ffc6bc6e688e Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 5 Nov 2026 17:32:52 +0100 Subject: [PATCH] docs(docs): V1-2.6 UX redesign technical plan, compatibility, tests, risks, decisions --- docs/development/V1-2-6_UX_COMPATIBILITY.md | 122 ++++ docs/development/V1-2-6_UX_DECISIONS.md | 157 +++++ docs/development/V1-2-6_UX_PLAN.md | 623 ++++++++++++++++++++ docs/development/V1-2-6_UX_RISKS.md | 47 ++ docs/development/V1-2-6_UX_TESTS.md | 134 +++++ 5 files changed, 1083 insertions(+) create mode 100644 docs/development/V1-2-6_UX_COMPATIBILITY.md create mode 100644 docs/development/V1-2-6_UX_DECISIONS.md create mode 100644 docs/development/V1-2-6_UX_PLAN.md create mode 100644 docs/development/V1-2-6_UX_RISKS.md create mode 100644 docs/development/V1-2-6_UX_TESTS.md diff --git a/docs/development/V1-2-6_UX_COMPATIBILITY.md b/docs/development/V1-2-6_UX_COMPATIBILITY.md new file mode 100644 index 00000000..2f0b6df4 --- /dev/null +++ b/docs/development/V1-2-6_UX_COMPATIBILITY.md @@ -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). diff --git a/docs/development/V1-2-6_UX_DECISIONS.md b/docs/development/V1-2-6_UX_DECISIONS.md new file mode 100644 index 00000000..2249e26d --- /dev/null +++ b/docs/development/V1-2-6_UX_DECISIONS.md @@ -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. diff --git a/docs/development/V1-2-6_UX_PLAN.md b/docs/development/V1-2-6_UX_PLAN.md new file mode 100644 index 00000000..86c1863d --- /dev/null +++ b/docs/development/V1-2-6_UX_PLAN.md @@ -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 ``, 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/_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. diff --git a/docs/development/V1-2-6_UX_RISKS.md b/docs/development/V1-2-6_UX_RISKS.md new file mode 100644 index 00000000..7f732de4 --- /dev/null +++ b/docs/development/V1-2-6_UX_RISKS.md @@ -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). diff --git a/docs/development/V1-2-6_UX_TESTS.md b/docs/development/V1-2-6_UX_TESTS.md new file mode 100644 index 00000000..12b31cab --- /dev/null +++ b/docs/development/V1-2-6_UX_TESTS.md @@ -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 |