Files
faunosteo/docs/development/V1-2-6_UX_PLAN.md
T

48 KiB
Raw Blame History

V1-2.6 UX redesign: technical implementation plan

Status: PROPOSAL for the owner, 2026-11-05. Nothing in this file authorises code. No application, Rust, SQL or worker change is made before the owner approves this plan and the blocking decisions of V1-2-6_UX_DECISIONS.md. Branch feature/v1-2-anatomical-sheets, worktree /home/bchanot/Documents/faunosteo-v1-2, audited at f58cf23.

Companion files:

File Content
V1-2-6_UX_PLAN.md This plan: inventory, sensitive points A to I, sub-steps U0 to U9
V1-2-6_UX_COMPATIBILITY.md Old / new schema matrix: core, SQL, worker, PDF, snapshots, N-1, oracles, rollback
V1-2-6_UX_TESTS.md Test matrix per sub-step
V1-2-6_UX_RISKS.md Risks, dependencies, blocking points
V1-2-6_UX_DECISIONS.md Technical decisions still needed (the validated UX choices are not reopened)

Inputs: the owner brief « V1-2.6 — Validation UX définitive et préparation technique » (16 boards of docs/design/v1-2-6/, archive V2, and the 11 choices of ARBITRAGES.md, all validated); five static audits run on f58cf23 (core model, rendering and archives, geometry and wasm, SQL and worker, editor and tests). Every claim of the earlier study (docs/design/v1-2-6/ETUDE-TECHNIQUE.md, .claude/audits/2026-11-05-v1-2-6-ux-feasibility.md) was re-checked against the code; §1.7 lists where it was wrong.

Paths below are relative to the repository root. core/ stands for crates/core/src/, app/ for apps/app/src/.


1. Technical audit

1.1 What the core already offers (re-verified)

  • Edit primitives. sheet.edit (insert, update, remove, move, set_status, mark_reviewed) is a free op, document in, document out (core/ops.rs:106-119, core/domain/sheet/edit.rs:96-125). update replaces an element whole (edit.rs:459-509); an annotation whose content changes turns to_confirm (edit.rs:495-509). Every gesture on a point or a polygon ends in one such update (or insert).
  • Removal guard. remove refuses with has_dependents while anything names the element (edit.rs:570-577, 903-908).
  • Redrawn views. After every command, the annotations of a view whose drawing or view_box changed turn to_confirm; geometry is never touched (edit.rs:792-857).
  • Preview handle. PreviewSheet holds the drawings and the document, preview.state and view.canvas (core/ops.rs:514-530, crates/wasm/src/lib.rs:79-154). Practitioner canvas and editor canvas share one composition (ops.rs:472-507).
  • Crop composition is vector. The whole sanitised drawing is cloned, its root becomes a <g>, only the new root's viewBox frames it (core/anatomy/compose.rs:94-160). A crop view needs no derived file.
  • Placement rules. view_frame, geometry_bounds, placement, out_of_frame, too_small, marker_too_small (core/anatomy/frame.rs:60-254) and interior_too_small (core/anatomy/interior.rs:33-43, 207-222).
  • Path reader. Strict browser grammar, every command, implicit repeats, numbers bounded at 2^20, f64 pen, bounds measured on the shape (core/anatomy/path.rs, 1 090 lines). Its Cursor, Pen, Arc and Ellipse are private and the number spans are computed then dropped (path.rs:136-139, 203, 226, 303-311).
  • Number writing. json::js_number prints ECMAScript Number::toString (core/json.rs:18-82), valid in path data. anatomy/svg/number.rs is a JavaScript Number() reader and is not a path writer.
  • Names. PreviewState.index.names already ships every annotation's name to the page (core/domain/sheet/preview.rs:332-356).

1.2 What the application already offers (re-verified)

Capability Code Use in the redesign
Editor route, modes, permission states app/app/routes/app/admin/AdminSheetDraftRoute.tsx:73-156, app/editor/mode.ts:12-92 REUSE
Store, commit, undo (one entry per accepted commit, 8 MiB) app/editor/state/editorEdit.ts:45-82, undo.ts:7-54 REUSE, header buttons ADD
Undo shortcuts (global, ignored in fields and dialogs) app/editor/useUndoShortcuts.ts:4-24 REUSE
Explicit save, unsaved state, conflict dialog with M8 editorSave.ts:43-149, DraftHeader.tsx:27-153, ConflictDialog.tsx:105-231 REUSE
Local recovery (sessionStorage, key user + version, revision in the record) recovery.ts:10-155, recoveryFlow.ts:56-187 REUSE
Pan, pinch, wheel, keyboard zoom app/catalogue/useFraming.ts:85-168 REUSE, keys ADAPT
Point and polygon move after 4 CSS px, one update on pointer-up useMoveGesture.ts:78-116, gesture.ts:5-33 ADAPT (pointerId)
Point, zone and link creation by clicks creation.ts:93-178, usePlacement.ts:13-85 ADAPT
Geometry accept after commit app/editor/issues.ts:123-175 REUSE
Upload, cleaning, attach, repair drawingUpload.ts:86-192, repair.ts:60-309 REUSE, attach ADAPT (remap)
Crop preview of the parent CropCanvas.tsx:30-77, viewBox.ts:31-46 REUSE as the rectangle's base
Verification tab, submission components/editor/tabs/VerificationTab.tsx, verification.ts:64-131 REUSE, targets ADAPT

1.3 Interactions possible without a core change

Page-only, each ending in sheet.edit and judged by the core on commit (issues.ts:123-175): the four-tab shell; header undo and redo; the references side panel; sidebar collapse; point move; point size slider (the page reads the radii present in the view, the core still refuses marker_too_small); polygon vertex drag; « + » on a segment; « − » on a vertex; zone move (mouse direct, touch mode); zone redraw keeping the old shape until validation; the rectangle gesture that sets a detail view's view_box; « replace by a specific SVG » without remap; per-annotation colour shown only when set, with « back to the category colour » (an update with color: null); keyboard alternatives; 44 px touch handles; the pointerId guard; a multi-tab notice if the owner wants one (T14).

1.4 New Rust operations required

Op Needed for Kind Estimate
sheet.annotations_in_rect name proposal of a detail view (choice 6), automatic access only without overlap PreviewSheet op 80-150 lines, 1.5-4 KB gzip
sheet.remap_view a crop view receiving a re-based drawing (point E) PreviewSheet op returning sheet.edit commands 120-250 lines, 2-5 KB
per-view minimum visible radius the red « minimum touchable » mark of the size slider (choice 3) value in PreviewState 20-40 lines, < 0.5 KB
sheet.path_points curve handles (point D, U9, deferral proposed) free op 250-400 lines, 4-8 KB
sheet.path_move_points move anchors and controls without simplifying free op 300-500 lines, 5-10 KB
sheet.path_translate move a curved zone whole free op 60-120 lines, 1-3 KB
fixed-category rules + opacity in the layer choices 4 and 5 schema + edit.rs + sheet_report issues + layer.rs 1-3 KB

Estimates come from the recorded size history: the frame rule with curve and arc measure cost +12 616 B, the interior rule +6 195 B, sheet.empty about +2 698 B, reserved ids +655 B (docs/development/RUST.md:4101, 4203, 4452). They are ranges, not measures.

1.5 Schema change, serialisation, fingerprints, versioning

Only choices 4 and 5 touch the document schema (two optional keys on AnnotationCategory, route A of the earlier study). Facts that govern it:

  • AnnotationCategory is {id, name, color} with deny_unknown_fields; color is a required key that may be null (core/domain/sheet/schema.rs:219-228). Every strict reader refuses an unknown key: sheet.check and sheet.edit answer invalid_shape, PreviewSheet invalid_document, the verdict verification.integrity.document, the snapshot gate SnapshotRejection::Schema.
  • The fingerprint hashes the JCS text of the typed document re-serialised (core/domain/sheet/fingerprint.rs:4-11, 246-273). A new Option field keeps every existing fingerprint only if it is omitted when absent (skip_serializing_if), as LocalizedOptionalText already does (schema.rs:162-180). The nearest precedents (count_range, annotation color) write null; following them would change every fingerprint, the equine sheet-ref, the alias pair of BDR-070, every review digest and every R4 app-path digest.
  • The fingerprint and the snapshot gate also require no validation error (fingerprint.rs:262-265, snapshot_rules.rs:334-340). A new unconditional validate.rs error (for example « three roles required ») would strip the fingerprint of every existing document and reject old PDF snapshots. Fixed-category rules must live in edit.rs (editor refusals) and in a verdict-only tier relative to the base (precedent GEOMETRY_MISSING, core/domain/sheet/report.rs:17-19, 54-55), never as an unconditional validate.rs error.
  • Doctrine conflict to settle (decision T2): .claude/rules/schemas.md:9-11 says additive optional fields keep the contract; .claude/rules/sheet-model.md says a document schema change bumps SHEET_DOCUMENT_SCHEMA_VERSION, with no bump during V1-2 (BLK-008); BDR-068 says v1 freezes the construction and the validation. Route B (schema v3) is excluded by the contract during V1-2 (docs/development/V1-2_ANATOMICAL_SHEETS.md:1779-1781) and would need a data migration (BLK-008) plus a change to save_sheet_draft, which never updates document_schema_version (supabase/migrations/20261028110000_sheet_review_workflow.sql:621-623 against the CHECK of 20261008110000_anatomical_sheets.sql:120-121).

1.6 Wasm module size

Measured on the shipped build (packages/core-wasm/pkg/faunosteo_wasm_bg.wasm, built 2026-11-04 after the last core change of 2026-11-02): 1 569 864 B raw, 592 143 B with Node gzipSync level 9, which is what the gate measures (packages/core-wasm/tests/size.test.ts:12-25). Budget 600 000 B (D-R13), margin 7 857 B. GNU gzip -9 gives 583 126 B; the earlier study's « about 17 KB left » used that figure. Without the curve operations (U9, deferral proposed) the new core code is estimated at about 4.5 to 13.5 KB: it may fit or exceed the margin, so the plan measures after each op and holds a fallback ready (decision T1). With U9 the total reaches 14 to 31 KB and a lever is certain. Documented levers, none applied: wasm-opt -Oz (never measured; wasm-opt is not installed, RUST.md:4054, so it is a new pinned build tool), a lighter URL check (about 23 KB), the PDF writer, reader and inflater in a lazily loaded second module (about 55-60 KB, RUST.md:4050-4054; touches the R4 paths, the import worker, the CSP proof and trap recovery, and the readers of user data that need an explicit owner ask). Raising the budget is an owner decision (D-R13).

1.7 Corrections to the earlier study

Earlier claim Code
About 17 KB of wasm margin 7 857 B by the gate's measure (§1.6)
PDF highlight is a fixed colour, category settings change no PDF Fill and fill-opacity are overwritten (compose.rs:259-267); zone and trigger strokes keep the category colour in the PDF. Category opacity has no PDF effect only if written as fill-opacity
Old documents re-written identically under route A Only with skip_serializing_if; the precedents write null. And any sheet.edit output re-serialises the stored text (seed key order, omitted color); « byte for byte » holds for untouched stored texts and for the canonical fingerprint
An integer avoids losing Eq JsInt wraps an f64 without Eq (core/domain/js.rs:94); nothing needs Eq on the category
Snapshot can strip the fields « as it strips references » lean_document copies categories whole (snapshot_rules.rs:160); stripping is new code, and the export gate re-serialises caller snapshots (pdf/write/input.rs:174-181, export.rs:27-37)
N-1 and 0.2.0 refuse an unknown key Only the snapshot is dropped (snapshotRejected 'schema'); the report is still imported with a degraded alert (packages/core-wasm/tests/n-1/domain/archive/envelope.ts:110-117, core/domain/archive/read.rs:86-89)
SQL checks arrays and category ids Category ids are not checked since M5 (20261028110000:139-144); the conclusion (optional keys pass SQL) holds
Worker image before the app, as for any core change Not written anywhere. When verdict codes, group kinds or verdict format change, the SQL migration comes first (20261101100000_sheet_verification_jobs.sql:57-69, 153-160, 321), then the worker, then the app. A new document rule needs no new code: every error issue outside five excluded codes maps to the existing verification.validation.rules (core/domain/sheet/verdict.rs:277-296)
Replacing a crop by its own drawing displaces annotations Not for the project's own data: the seed head drawing has viewBox="60 100 500 380" (supabase/seed/anatomical-sheets/equine/legacy-sources/Horse_head.svg), exactly the head crop (draft/document.json:477-482), and the same path data as the full drawing. Keeping positions is right for a drawing cut from the same master; a remap is right only for a re-based drawing
Adding a role to os, articulations, zone-colonne suffices os (Os / Bones) and articulations (Articulations / Joints) already carry the fixed names; only zone-colonne (Segments vertébraux / Vertebral segments) differs. Three equine annotations carry an own colour that overrides any category setting
Not covered A detail view without an access is a view.unreachable error (core/domain/sheet/validate.rs:199-220): it blocks the fingerprint, the snapshot and publication. Under choice 6 an access not created automatically must be placed before submission
Recovery keyed by version and revision (contract C13) Key = user + version; the revision is a field of the record (recovery.ts:47-49). Code and contract text differ
useMoveGesture has a weak pointerId check It has none (useMoveGesture.ts:87): a second finger feeds the drag while the pinch zooms

1.8 SQL, RLS and worker

  • No SQL reads the members of a top-level category. Optional keys pass check_document_structure (20261028110000:411-441), the CHECKs and the RLS unchanged. schema_version 3 is refused (20261028110000:424-426, 20261010100000:10-12).
  • The worker reads the document strictly through the core (crates/worker/src/verify.rs:93-97, core/domain/sheet/verdict.rs:169-185, 264-274). An older worker answers a definitive verification.integrity.document on a draft carrying the new keys, never retried; a newer worker adding a verdict code before SQL knows it closes the rounds whose verdict carries it verdict_refused (20261101100000:57-69, 87-90). The plan adds no verdict code (fixed-category rules are issues mapped to verification.validation.rules).
  • App and worker images are built from one GIT_SHA by .gitea/workflows/release-images.yml:103-120 (prepared, never run). The sandbox reuses faunosteo_worker:dev without checking it matches the checkout (scripts/db-sandbox.sh:335-347): every model step rebuilds it explicitly.
  • The only SQL the redesign needs is the round-withdrawal migration the contract requires when the integrity rules or the SVG reader change (V1-2_ANATOMICAL_SHEETS.md:945-949): U6 (verdict-tier rules, decision T4) and U9 (path reader). References are in the document; own drawings use the existing upload path, capped at 4 drawings per sheet, 2 MiB each, 6 MiB in all (core/domain/archive/snapshot.rs:21-28).

1.9 Concurrency, multi-tab, recovery

  • One draft per sheet (unique partial index, 20261008110000:131-133); save_sheet_draft locks and checks the revision (20261028110000:593-608); a stale save answers draft_conflict, nothing is overwritten.
  • No multi-tab detection in the app (no storage event, BroadcastChannel or navigator.locks). Each tab keeps its own sessionStorage copy. Two tabs edit freely; the first save wins; « Garder ma version » in the second tab overwrites the first tab's save with a whole document after confirmation (editorSave.ts:140-149).
  • Undo crosses a save (history kept, editorSave.ts:84-93); addDrawing is outside history (editorEdit.ts:85-104).
  • Clicking a header button while a text field holds typed text blurs it first, which commits; the undo then reverts that typing (TextField.tsx:75-88, GeometryGroup.tsx:188).

1.10 Keyboard, mouse, touch

  • Markers are not focusable; keyboard selection goes through the annotation list (AnnotationList.tsx:55-72).
  • Arrows already pan the focused canvas box (useFraming.ts:150-168): they collide with « arrows move the chosen handle » unless focus decides (handle focused → move; box focused → pan).
  • touch-action: none while a tool is active, a drag is armed, the view is zoomed or a movable selection exists (useCanvasGestures.ts:76-84).
  • Overlay vertices are decorative, pointer-events-none, radius span/200 drawing units (AnnotationOverlay.tsx:48-66, 116, 125). No multi-touch test exists; the touch test is a single CDP touch at 1 280 px (apps/app/e2e/shell/editor-geometry.spec.ts:416-470).

2. Sensitive points A to I

A. Non-destructive migration for fixed categories and opacity

  • Route A: role (bone | joint | vertebra) and fill_opacity (integer percent, decision T3) on AnnotationCategory, both Option + #[serde(default)] + js::present (an explicit null refused, one canonical form) + skip_serializing_if = "Option::is_none" + ts(optional), the LocalizedOptionalText pattern. No SHEET_DOCUMENT_SCHEMA_VERSION bump, no SQL schema change, no data migration (decision T2).
  • Existing documents carry neither key: they read, write and fingerprint as today. Proven by tests, never assumed: equine fingerprint 12d78872… and alias 27c7383c… recomputed equal, every seed review digest pinned and equal, R4 app-path digests unchanged (V1-2-6_UX_TESTS.md U6).
  • New sheets: sheet.empty creates the three fixed categories with roles, core-chosen ids (precedent view-main, core/domain/sheet/create.rs:9, 28), fixed names and default colours (decision T5).
  • Rules in two tiers, never as an unconditional validate.rs error (that would strip fingerprints and reject old snapshots): edit.rs refuses removing a role-bearing category, changing or clearing its role, a duplicate role, and renaming a role-bearing category; sheet_report issues, relative to the base when there is one, report a role of the base that disappeared and any duplicate role. They map to the existing verification.validation.rules (verdict.rs:277-296): no new verdict code (decision T4).
  • Residual gap, stated: a sheet's first version has no base, so a direct save_sheet_draft (or « Garder ma version » from a tab still running an older bundle) can strip the three roles before the first publication; the edit refusals do not see it. It shows in the review of the general group, where every group of a first version must be covered. Decision T4 records whether this residual is accepted.
  • No expand-then-write split: every environment where U6 runs is a throwaway sandbox, and sheet.empty writes the keys from the first new sheet, so a split would not protect anything. The rollback limit is stated instead (V1-2-6_UX_COMPATIBILITY.md §7) and recorded as a release-readiness item.

B. Historical equine sheet and published documents

  • The historical sheet 503dc301… stays read-only on the server (sheet.historical_read_only) and in Git: no file of supabase/seed/anatomical-sheets/equine/ changes; pnpm r5:import-equine --check stays clean at every sub-step; anatomy_canvas_op.rs:27 keeps reading the seed unchanged.
  • Published versions are immutable (20261028110000:274-292) and keep their bytes.
  • Category ids never change (id_changed, edit.rs:486-489). Converting the equine working copy (roles on os, articulations, zone-colonne, the renaming of zone-colonne, the three own colours) is V1-2.8 content work, a reviewed edit of its draft, after decision T6. Nothing in V1-2.6 converts it.

C. Proof of compatibility: N-1, PDF snapshots, worker, old drafts

  • Snapshot: lean_document strips role and fill_opacity, and the export gate strips them on caller-built snapshots and in export_from_envelope, so no path writes them into an envelope. The PDF needs neither (fill and fill-opacity are overwritten in the highlight, compose.rs:259-267).
  • N-1: a dedicated New-present sheet fixture and harness export PDFs that must pass the assertions of apps/app/tests/unit/n-1.reader.test.ts:178-196 (envelope success, archive kept, no snapshotRejected); the seed path stays as it is. contracts.types.test.ts:53-61 checks assignability: ts(optional) on both keys is necessary and sufficient; it says nothing about runtime stripping, which the fixture test proves.
  • Worker: the image is rebuilt from the same commit, checked against git rev-parse HEAD before the run (U1 adds that guard), and verify-e2e runs a New-absent and a New-present draft.
  • Old drafts and recovery copies are plain document texts read by the same strict reader.
  • The readers of user data widen (assert_snapshot, used by archive/read.rs, accepts the keys): CLAUDE.md asks for the owner's agreement before such a change; it is part of decision T2.

D. Editing and translating curves without geometric degradation

Validated guarantee already held: a curve is never converted or simplified. Paths are displayed by the core; the editor never reshapes them (level-1 C45) and offers « Remplacer par un polygone ». No document of the project holds a path (the seed has 22 circles, 6 polygons, 0 paths), and no product path can create one: creation makes points and polygons only (creation.ts:93-97), package import and zones from the drawing's shapes stay deferred (V1-2_ANATOMICAL_SHEETS.md:1330-1338). Board 05 labels its curve card « exemple d'une autre fiche ».

Handle editing of curves (anchors, controls, translation) is therefore U9, proposed for deferral to the lot that first lets a path enter a document (decision T16). Its specification is kept so it can start without a new study:

  • Built on the existing reader (path.rs), extended to keep each number's byte span and a segment model (command, absolute or relative, origin, anchor, explicit controls).
  • path_move_points rewrites only the moved numbers and those that depend on them; every other byte stays. Relative commands after a moved anchor are compensated so later absolute positions do not move; H or V moved off their axis convert to L (splitting implicit runs); an S or T whose implicit control would change converts to C or Q; arcs move their endpoint only (radii, rotation and flags untouched; a λ rescale is reported). Separators are re-inserted where a sign or a dot would merge two numbers.
  • path_translate changes only absolute coordinates and the leading m.
  • Numbers: exact decimal arithmetic on the written digits, output precision = max(input precision of the number, 2 decimals for a user move), so compensation never moves another point and a translation round-trips exactly.
  • Preview during a drag: page-side transform of the drawn path element (an SVG transform on the preview only), one core call on pointer-up (BDR-050), never a core call per move.
  • Implicit S/T controls are listed as non-editable; a control outside the frame is never judged on its own.
  • Remap of a crop view holding a path is refused with a closed code until U9.

E. Annotations when a crop view receives its own SVG

  • Today the attach keeps the old view_box and changes only svg_asset_id (drawingUpload.ts:185-192): the frame stays the crop rectangle R, read in the new drawing's space. For a drawing cut from the same master (the seed head drawing has exactly the crop's viewBox), this is already right and annotations stay on their anatomy.
  • For a re-based drawing (another export with a different viewBox), positions must be transposed. The editor therefore offers an explicit choice when the new drawing's viewBox V differs from R: « Même repère : garder les positions » or « Dessin recadré : transposer les annotations ». V equal to R: no question, positions kept (decision T9 on wording and default).
  • sheet.remap_view {view_id, asset_id} on the preview handle returns a batch of sheet.edit commands (the view update and one update per remapped annotation), committed by the existing commitBatch as one undo entry under the geometry accept (editorEdit.ts:45-61). The core reads R and V itself; the page supplies no number. Mapping: one uniform scale and translation (xMidYMid meet, the composer's default); circles move their centre and scale r; polygons every point; numbers on the 0.01 grid of the page; every remapped annotation to_confirm (by the update rule, edit.rs:495-509).
  • Scope: the view's own annotations, including the detail triggers drawn in it. Descendant views with their own drawing are untouched. Refused as a whole, with closed codes: a descendant crop view without its own drawing (remap.descendant_crop; no sheet has one), a path in the view (remap.path, until U9), unknown_view, no_frame, out_of_range. A refusal or a remap whose end state fails the geometry accept leaves the document unchanged and the uploaded drawing held, with a message; the editor can then attach with « garder les positions » or abandon.
  • Fixed user-unit sizes (twin offset 12, floor 2, strokes) do not scale, so too_small can change after a downscale; the geometry accept and the repair dialog judge the end state.

F. annotations_in_rect, name proposal, access placement

  • Input {view_id, rect} on the preview handle; rect passes the frame range rule (Frame::from_numbers, made pub(crate)). Output [{id, relation}] in document order, relation = inside | partial; names come from index.names, already on the page.
  • Geometry tested by bounds: circle by its hit-box disc (cx ± r, the box of the frame rule, frame.rs:167-185), polygon and path by their bounds (path_bounds is tight on the shape). inside = bounds within the rect; partial = bounds intersect. Over-reporting for concave shapes is conservative: it can only prevent an automatic access, never place one over an annotation.
  • Name proposal (page, display formatting from the core's list): FR and EN names of the inside annotations, in document order, joined by the locale's list format, the first three then « … »; none inside → « Vue détaillée n » / « Detail view n », n = number of detail views + 1. Both fields stay editable.
  • Access: the view and its access are inserted in one batch. The access is created automatically, with the drawn rectangle as its polygon in the parent view, only when the overlap list is empty and the sheet has a category for it (decision T10). Otherwise the box is unchecked with the reason stated, and the access is placed explicitly from the view's menu (« Ajouter un accès »), which replaces the « Accès à une vue détaillée » toolbar tool (choice 6). Until an access exists the view is view.unreachable, an error in the validation panel that blocks submission, not saving; the creation flow says so and links to the placement.

G. Polygon operations, undo and redo, invalid shapes

  • Page operations, each one sheet.edit update of the whole annotation: vertex drag (preview on move, commit on pointer-up), « + » inserts the segment midpoint after the segment's start vertex, « − » removes the chosen vertex, zone drag translates every point, redraw replaces the points after the new trace is accepted.
  • Protections before the core: « − » not offered at 3 vertices; no non-finite value committed; a vertex released on its neighbour is a no-op; above a handle cap (implementation constant, recorded at U0) the shape shows its outline and a message instead of one handle per vertex. The core judges the end state on commit (invalid_shape below 3 points; out_of_frame, too_small, interior_too_small through issues.ts:123-175). A refusal restores the previous shape.
  • Pending previews (a drag, arrow moves before Enter, a staged form) are cancelled and restored before any undo, redo, document replacement, save reload, tab change or second pointer: index-based operations never apply to a document they were not computed on.
  • A second pointerdown during an armed drag cancels the drag and restores the shape (a pinch never moves a handle). touch-action: none sits on the handle hit targets and in the explicit move mode; the canvas box keeps panning (the browser reads touch-action at touchstart, useCanvasGestures.ts:73-83).
  • Redraw: the old shape stays drawn and committed until the new trace closes and is accepted; Escape or a refusal keeps the old one. One undo entry.
  • Undo and redo: one entry per accepted commit, whatever the tab; header buttons, shortcuts and the toast call the same undo(). The toast is dismissed by any commit, undo or redo, stays until then or until closed, is reachable by keyboard, and its message is in a live region. Sliders (point size, opacity) and arrow moves commit on release, Enter or blur only (BDR-050), so a keyboard walk never floods the 8 MiB history (about 20 entries of the equine document).
  • Keyboard: roving focus inside a shape (Tab enters the shape, arrows between handles when the handle list is focused, then move the chosen handle in « move » state), Shift ×10, Insert or the visible « + » button, Delete or Backspace or the visible « − » button, Enter commits, Escape restores. Arrows pan only when the canvas box itself has focus.
  • Self-intersection stays allowed (nonzero rule decides, interior.rs:33-34); no new polygon rule.

H. Tests

Detail per sub-step in V1-2-6_UX_TESTS.md: core unit and conformance, seeded property tests in Rust (no new dependency), table tests in TypeScript, hostile inputs at the op level, N-1 on a New-present fixture, oracles and seed untouched, axe, keyboard and touch journeys, sandbox and worker runs.

I. Decisions that block before any code

Each sub-step lists the decisions it consumes; the single table is in V1-2-6_UX_DECISIONS.md. Before U1: T11. Before U5: T9, T10 (and T1 if the measure exceeds the budget). Before U6: T2, T3, T4, T5, T17. Before U7: T12. Before U9: T16.


3. Sub-steps

Order: U0, U1, then U2 to U4 (frontend), U5 (first core queries, consumer-driven), U6 (model), U7 (common text, when its wording exists), U8 (closure). U9 (curves) is proposed for deferral. Each sub-step ends at an owner checkpoint; the next starts after the owner accepts it.

Common rules for every sub-step that touches code:

  • Work in /home/bchanot/Documents/faunosteo-v1-2, every shell command with that absolute path verified first (LRN-110). Commit in place on feature/v1-2-anatomical-sheets, one commit per coherent change; rollback = revert of the sub-step's contiguous commits. No sub-branch (the gitflow lib only branches from develop), no merge, no gitflow.sh finish.
  • Gates: pnpm typecheck, pnpm test:run, pnpm lint, pnpm build; after any change under crates/core or crates/wasm, pnpm rust:check and pnpm wasm:build first and the size figure recorded; pnpm check:all before the checkpoint; fresh verifier and security review.
  • Database: pnpm db:sandbox only (up fresh, up upgrade, test-db, types --check, e2e-shell, test, verify-e2e), in the order test-db → e2e:shell → test (LRN-113). Forbidden: pnpm db:start, db:reset, db:test, db:types, pnpm supabase …, e2e:avatar and e2e:sheet-assets outside their sandbox aliases, any command reaching DEV. The CLAUDE.md line « SQL change: db:reset && db:test » does not apply to this plan.
  • The sandbox and the worker image tag are shared with the other checkouts of this machine (scripts/db-sandbox.sh:47-60): no other checkout runs them during V1-2.6; the owner-trial stack is rebuilt only after telling the owner (it wipes trial accounts and data).
  • Owner demos run on a sandbox demo sheet provisioned by the same upload path as editor-equine.spec.ts:81-104 (the equine drawing uploaded through the application), not on the historical working copy, which the missing sandbox drawings block (separate track).

U0 · Contract, decisions and amendments (docs only)

  • Objective: record the owner's answers to V1-2-6_UX_DECISIONS.md and amend the ratified texts the validated UX replaces.
  • Files: docs/development/V1-2_ANATOMICAL_SHEETS.md §7.4 (common text), §8.2 (no coordinate fields, fixed categories, colour shown when set, access created with the view), §8.3 (vertex drag and the crop rectangle leave level 2; curves per T16), §8.4 (O14 A kept, tablet rule), §16.7 (new state); the level-1 contract .claude/tasks/contracts/2026-11-03-v1-2-6-editor-1509.md (C3, C4, C6, C7, C8, C13 wording to match the code key, C32, C33, C40); docs/design/README.md (v1-2-6 boards replace V1-2.4 boards 04 and 05 for the editor, BDR-096); .claude/rules/sheet-model.md (optional keys under T2; rules may also live in edit.rs and sheet_report) and schemas.md; the implementer decisions (T7, T8, handle cap, branch policy); .claude/memory/decisions.md via memory.sh.
  • Dependencies: owner answers.
  • Rust ops: none. Tests: a fresh verifier checks the amendments against the answers.
  • Acceptance: each decision recorded once and cited where it applies; no contradiction left between the contract, the level-1 criteria and the boards.
  • Owner demo: read the amended sections. Rollback: revert.
  • Checkpoint: owner approves the amended contract.

U1 · Shell: four tabs, header undo, references panel, tablet layout, sandbox guard

  • Objective: General, Annotations, Findings, Verification; views, drawings, vertebral regions and categories in Annotations; References as a side panel from the header or a finding; Undo and Redo in the header on every tab; sidebar hidden in the editor below 1 280 px with the menu one tap away; « Aller à » retargeted. Tooling: the sandbox verify-e2e refuses an image whose commit label differs from HEAD; the trial command provisions the demo sheet.
  • Files: app/editor/tabs.ts, EditorTabs.tsx, EditorTabBody.tsx, DraftHeader.tsx, components/editor/tabs/*, app/editor/verification.ts:64-131, PropertiesPanel.tsx:169, components/shell/AppLayout.tsx:72-123, ToolColumn.tsx, i18n; scripts/db-sandbox.sh (image check, demo sheet), crates/worker/Dockerfile (commit label).
  • Dependencies: U0, T11.
  • Rust ops: none.
  • Tests: V1-2-6_UX_TESTS.md U1.
  • Acceptance: four tabs at 1 024 px and wider; every existing editor journey green on the new shell; narrow-width read-only unchanged; undo from any tab reverts the last accepted change; a stale worker image is refused.
  • Owner demo: on the demo sheet, switch tabs, undo a General change from Annotations, open References from a finding, resize to 1 180 px.
  • Risk: broad test rewrite (each removed assertion mapped to its replacement). Rollback: revert, no data change.
  • Checkpoint: owner validates the shell.

U2 · Direct manipulation of points and polygons

  • Objective: boards 02 to 06 and 13 for points and polygons (curve handles excluded, U9): point move and size slider snapping to the radii of the view with the red minimum mark; vertex drag; « + » per segment; « − » on the chosen vertex; zone drag directly with the mouse once selected, explicit « Déplacer la zone » mode by touch; redraw keeping the old shape until accepted; 44 px touch handles; pointer rules and keyboard of §2 G; the toast; coordinate fields leave the normal journey.
  • Files: AnnotationOverlay.tsx (interactive handle layer), EditableAnnotations.tsx, GeometryGroup.tsx, PropertiesPanel.tsx, TracingBar.tsx, ToolColumn.tsx, KeyboardAdd.tsx, useMoveGesture.ts, gesture.ts, geometryEdit.ts, usePlacement.ts, useCanvasGestures.ts, app/catalogue/useFraming.ts, a toast in components/ui; core: anatomy/frame.rs and domain/sheet/preview.rs (per-view minimum visible radius in PreviewState), types and wrapper.
  • Dependencies: U1.
  • Rust ops: one read-only value (minimum visible radius per view, from the marker_too_small threshold, frame.rs:67, 220), so the page draws the mark without a TypeScript size rule (BDR-043, C32).
  • Tests: V1-2-6_UX_TESTS.md U2.
  • Acceptance: every listed gesture works with mouse, touch (1 024, 1 180 and 1 280 px) and keyboard; a refused shape is restored exactly; no coordinate field in the normal journey; latency under the 500 ms budget.
  • Owner demo: on the demo sheet, move a point, change its size, drag a vertex of « Thoraciques », add and remove a vertex, move the zone, redraw it and cancel, undo each step; same on a tablet in landscape.
  • Risk: touch and keyboard conflicts (§2 G). Rollback: revert (the core value is additive and unused once reverted).
  • Checkpoint: owner tries mouse and tablet.

U3 · Category panel and own colour

  • Objective: board 07 states A to D without the fixed-role locks (they come at U6): foldable panel in Annotations, swatch with the name next to it, 16-colour palette plus hex, staged form with « Appliquer » (the drawing previews the candidate document on the preview handle, the store commits one batch on Apply, Cancel restores), delete when unused, « Réaffecter à… » when a delete is refused (one batch of annotation updates, one undo entry); own colour of an annotation shown only when set, with « Revenir à la couleur de la catégorie »; new annotations inherit.
  • Files: components/editor/general/CategoriesSection.tsx (moved), AnnotationFields.tsx:96-104, AnnotationList.tsx:53-73, editorEdit.ts (preview without commit), i18n.
  • Dependencies: U1.
  • Rust ops: none.
  • Tests: V1-2-6_UX_TESTS.md U3.
  • Acceptance: board 07 A to D minus the locks; board 03 colour behaviour; equine own colours shown and revertible.
  • Owner demo: recolour a category with preview, cancel, apply; reassign and delete a category; revert an own colour.
  • Risk: preview without commit must never leak into history. Rollback: revert.
  • Checkpoint: owner.

U4 · Detail view by rectangle (manual)

  • Objective: « Créer une vue détaillée » draws a rectangle on the parent drawing (handles, keyboard resize) and sets the new view's view_box; names typed; the access placed from the view's menu (« Ajouter un accès »); the toolbar tool « Accès à une vue détaillée » and the numeric crop editor leave the normal journey.
  • Files: CropCanvas.tsx, DetailViewForm.tsx, CropEditor.tsx, DetailViewRow.tsx, ToolColumn.tsx, app/editor/viewBox.ts, viewUpdate.ts, i18n.
  • Dependencies: U2.
  • Rust ops: none (the core refuses an unusable frame: view.frame.unknown).
  • Tests: V1-2-6_UX_TESTS.md U4.
  • Acceptance: a detail view created and opened without typing a number; view.unreachable shown until its access exists.
  • Owner demo: create « Coude » on the main view, place its access, open it in the preview.
  • Rollback: revert.
  • Checkpoint: owner.

U5 · Detail view assisted: annotations_in_rect, remap_view, name, access, specific SVG

  • Objective: the two core queries, consumed in the same sub-step: proposed FR/EN name, automatic access only without overlap, explicit placement otherwise; « Remplacer par un SVG spécifique » with the explicit choice of §2 E.
  • Files: core anatomy/frame.rs (from_numbers, holds to pub(crate)), new domain/sheet/rect.rs and domain/sheet/remap.rs, ops.rs (call_with_preview), types, packages/core-wasm/src, app/core/*, DetailViewForm.tsx, CropCanvas.tsx, drawingUpload.ts:184-192, ViewDrawing.tsx, RepairDialog.tsx, i18n, RUST.md §12.
  • Dependencies: U4; T9, T10; T1 if the measure exceeds the budget.
  • Rust ops: sheet.annotations_in_rect, sheet.remap_view (§2 E, F). Order: annotations_in_rect first, size measured; then remap_view, size measured; a budget excess stops the sub-step for T1.
  • Tests: V1-2-6_UX_TESTS.md U5.
  • Acceptance: board 08; no access ever created over an annotation; « garder les positions » and « transposer » both proven on fixtures; one undo entry per remap; size within budget or T1 applied.
  • Owner demo: board 08 on the demo sheet; attach the seed head drawing to a crop (positions kept, no question); attach a re-based fixture drawing (transposition offered).
  • Risk: size; bounds over-report. Rollback: revert (documents written are plain v2).
  • Checkpoint: owner.

U6 · Category model: fixed categories, fill opacity, vertebral regions from the category

  • Objective: route A (§2 A); sheet.empty creates the three categories; edit refusals and report issues; the layer applies fill_opacity (decision T3); snapshot and export gate strip both keys; the panel locks the fixed categories (no delete, name read-only, role badge, « Couleur d'origine » from T5) and gains the opacity slider and field; board 09: regions open from the vertebra-role category, the region picker of a zone filtered to the vertebra-role category's annotations (page filter, no rule), staged « Appliquer » with the error count; fallback per T17 when no category has the role (the equine copy before V1-2.8). docs/ANNOTATION-RENDERING.md amended first; round-withdrawal migration (contract 945-949) if T4 adds report issues.
  • Files: core domain/sheet/schema.rs, create.rs, edit.rs, report.rs, anatomy/layer.rs (layer() 85-102, Context::point 242, zone_visual 297-304), domain/archive/snapshot_rules.rs:141-165, pdf/write/input.rs:174-181, export.rs:27-37, types; app refusal.ts, the category panel, the regions dialog (components/editor/vertebrae/*), i18n; SQL supabase/migrations/<timestamp>_sheet_rounds_withdraw_v1_2_6.sql (name provisional); docs ANNOTATION-RENDERING.md, ANATOMICAL_SHEET_MODEL.md (spec table), RUST.md, DEPLOY.md (order).
  • Dependencies: U3, U5; T2, T3, T4, T5, T17.
  • Rust ops: schema fields, edit refusal kinds, report issues, layer reading, snapshot stripping.
  • Tests: V1-2-6_UX_TESTS.md U6; each row of V1-2-6_UX_COMPATIBILITY.md is an acceptance line.
  • Acceptance: compatibility matrix proven row by row; oracles, goldens and seed unchanged; N-1 reads New-present PDFs; worker verdict on both kinds of draft; the contract §16.7 journey on a non-equine sheet with the new UX reaches open after the worker verdict.
  • Owner demo: new species sheet with its three categories, custom opacity, regions from Vertèbres, PDF exported and reopened.
  • Deploy order and rollback: V1-2-6_UX_COMPATIBILITY.md §7. Rolling back below U6 is impossible once a document with the keys exists (sandbox only until the owner decides otherwise).
  • Checkpoint: owner.

U7 · Scope and limits: one-time copy of a versioned common text

  • Starts only when the owner has supplied the validated wording (T12); no text is written by the implementer.
  • Objective: when both disclaimer fields are empty, « Insérer le texte commun (version n) » copies FR and EN once; afterwards the fields are free text; a read-only comparison shows the current version; no automatic change ever reaches a draft or a published version.
  • Files: a versioned template module in apps/app/src, components/editor/general/TextsSection.tsx, i18n; the change note records the template id and version.
  • Rust ops: none (one update of the sheet texts).
  • Tests: V1-2-6_UX_TESTS.md U7.
  • Acceptance: board 10; contract §7.4 as amended at U0.
  • Owner demo: insert, edit, compare. Rollback: revert.
  • Checkpoint: owner and the person responsible for the wording.

U8 · Closure

  • Objective: recovery and conflict journeys re-run on the new UX; the contract §16.7 acceptance on the sandbox; documents and TODO closed; V1-2-6_OWNER_TRIAL.md updated.
  • Dependencies: U1 to U6 (U7 when its wording exists; U9 per T16).
  • Tests: V1-2-6_UX_TESTS.md U8.
  • Checkpoint: owner trial of the redesigned editor; V1-2.7 stays closed until the owner opens it.

U9 · Curves (deferral proposed, decision T16)

  • Objective, if the owner keeps it in V1-2.6: board 05 curve handles (§2 D), curved zone move, remap of paths, the C45 refusal replaced by real correction.
  • Files: core anatomy/path.rs, ops.rs, types, wrappers; app AnnotationOverlay.tsx, useMoveGesture.ts, repair.ts:60-100; SQL round-withdrawal migration (the path reader feeds the frame and interior verdict rules, frame.rs:25, interior.rs:23); RUST.md.
  • Dependencies: U2, U5; T16, T1 (a lever is certain).
  • Rust ops: sheet.path_points, sheet.path_move_points, sheet.path_translate.
  • Tests: V1-2-6_UX_TESTS.md U9, including a frozen pre-U9 oracle of number_list, path_bounds and path_outline on a corpus, compared byte for byte after the change.
  • Acceptance: a path of a fixture sheet (never the seed) edited point by point, saved, reloaded with every untouched number byte-identical.
  • Rollback: revert; paths go back to display only.
  • Checkpoint: owner.

4. Frontend-only versus model and core

Sub-step App Rust core Schema SQL Worker image
U0 no no no no no
U1 yes no no no label only
U2 yes one read-only value no no no
U3, U4 yes no no no no
U5 yes two queries no no no (the worker calls neither)
U6 yes yes optional keys round withdrawal (T4) rebuilt, deployed before the app
U7 yes no no no no
U8 no no no no rebuilt for the final run
U9 yes path ops no round withdrawal rebuilt, deployed before the app

5. Out of scope, tracked separately

  • TOTP asked at sign-in for accounts with a factor.
  • The historical equine drawings missing on the sandbox, which block the working copy.
  • Full touch editing on the phone (boards 14 to 16 kept as the reference of that future lot); O14 A stays.
  • A multi-tab notice (not in the validated boards; the server revision check and the conflict dialog already guard against lost writes): proposed as a follow-up, decision T14.

The first three are in .claude/tasks/TODO.md (V1-2 section); T14 is added there if the owner keeps it.

6. Independent review record (2026-11-05)

Three fresh plan challengers, one lens each, on the first version of the five files: correctness CONCERNS(5), robustness CONCERNS(9), simplicity CONCERNS(6); no BLOCKER. Integrated:

  • The U7a/U7b expand-then-write split did not hold (sheet.empty writes the keys from the first new sheet) and protected no environment: one model sub-step (U6) with the rollback limit stated.
  • M9 dropped: report issues map to the existing verification.validation.rules (verdict.rs:277-296); the round-withdrawal migration of contract 945-949 added to U6 and U9, with a frozen pre-U9 reader oracle.
  • Sub-branches dropped (the gitflow lib branches only from develop): commit in place, rollback by revert.
  • Curves: no document holds a path; U9 proposed for deferral (T16); the size lever becomes a fallback measured op by op (T1), the PDF split a separate track.
  • Remap: the seed head drawing has the crop's exact viewBox, so the remap is an explicit choice, never automatic; returned as a command batch through commitBatch; descendant crops and paths refused with closed codes.
  • Pointer and keyboard: second pointer cancels the drag; pending previews cancelled before undo, redo, replacement or tab change; toast dismissed on any commit; sliders commit on release; touch-action on handle targets; roving focus, Backspace, live region; touch tests at 1 024, 1 180 and 1 280 px; handle cap.
  • Sandbox safety: forbidden DEV-reaching SQL commands listed; image checked against HEAD; shared sandbox and owner-trial stack rules; owner demos on a provisioned demo sheet.
  • Missing UX elements added: board 09 (regions from the vertebra-role category), board 07 « Réaffecter à… », « Couleur d'origine » and staged Apply, the red minimum mark (one core value), removal of the access tool.
  • Corrections of fact: equine names (only zone-colonne differs), the ts-rs/N-1 test is an assignability test, the N-1 runtime proof needs a New-present fixture, C32 and C33 added to the U0 amendments, the reader-of-user-data agreement added to T2.
  • Duplication reduced: one decision table (DECISIONS), one deploy-order statement (COMPATIBILITY §7); T7, T8, T13 turned into implementer decisions; the multi-tab notice moved to a follow-up (T14); U7 (common text) starts only when the wording exists.

Not adopted: the simplicity lens recommended edit.rs refusals only (T4 option a). The plan keeps report issues because they cost no SQL code once mapped to the existing verdict code and keep the core as the authority (O22); the owner decides under T4. No second review was run on the corrected version.