diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index c2d2e8a7..179033e4 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -744,7 +744,7 @@ Order (BDR-071): P0 docs + decisions → V1-1 clients and animals → V1-2 sheet - [ ] Follow-up: seed owner row in `private.catalog_write_budgets` is R4's own (none before R4; its first run created it, later runs update that same row, 4 archives per run; 8 of 300 per hour after the final wave, outside the data guard); `catalogue.spec.ts` still leaves its published sheets listed, warm-up its sheet and `sheet_editor` grant per invocation (BLK-015, RR-13) - [ ] owner arbitrations A1-A15 (`V1-2-6_U1_CORRECTIONS.md` §6, `TRIAL_STACK.md` §6) - [x] V1-2.6 UX U2 design: boards 02-06, 13 redrawn + extras from 31 (owner brief 2026-11-17 « R4 est terminé … préparer U2 », orientation 2026-11-14 BDR-117; contract `.claude/tasks/contracts/2026-11-17-u2-design-boards.md`; docs only, no code, no DEV, no merge). [x] audit as built · [x] boards + REVUE + ARBITRAGES in `docs/design/v1-2-6-u2/` (bc19481, fixes 8bdb23a and pass 3) · [x] fresh design review (5 must-fix, 19 should, 19 observations; fixed) · [x] fresh conformity check (ECARTS(4), then re-check ECARTS(1) on 8bdb23a: two labels, fixed) · [x] owner validation 2026-11-17: nine boards + A1-A15 as recommended, adjustments A13 hint, A14 no shift, board 33 messages (ARBITRAGES « Validation du propriétaire ») - - [ ] V1-2.6 UX U2 technical plan (owner brief 2026-11-17 « conception graphique U2 validée … plan technique »): plan `.claude/tasks/plans/2026-11-17-v1-2-6-u2.md` · [ ] audit · [ ] plan rev 1 · [ ] three fresh plan-challengers · [ ] STOP owner approval of the plan and decisions before any U2 code + - [ ] V1-2.6 UX U2 technical plan (owner brief 2026-11-17 « conception graphique U2 validée … plan technique »): plan `.claude/tasks/plans/2026-11-17-v1-2-6-u2.md` · [x] audit · [x] plan rev 1 · [ ] three fresh plan-challengers · [ ] STOP owner approval of the plan and decisions before any U2 code - [ ] Test anomaly A (owner 2026-11-09, separate from U1/U2): fictitious fingerprints `'a'.repeat(64)` from worker stand-ins (`packages/supabase/tests/sandbox/sheet-fixtures.ts:115` openRound, `sheets-concurrency.sandbox.ts:168`, `sheets-perf.sandbox.ts:169`); 7 published/deprecated sandbox versions fail `check_published`. Fix: real fingerprint through the core (as e2e `fingerprintOf`, `apps/app/e2e/support/catalogue.ts:88`); never weaken the publish gate or the reader check. Needs its own go. Census 2026-11-17 (R4 Task 3, read-only): 4 of 164 catalogue entries fail, the four current « Cheval sandbox » versions (2 at v1, 2 at v2), all `fingerprint_mismatch`; R4 cards show them with the integrity line. - [ ] Test anomaly B (owner 2026-11-09, separate from U1/U2): `packages/supabase/tests/sandbox/sheets-admin.sandbox.ts:181-195` creates the historical working copy and never archives it; slot taken → `admin.spec.ts:717` fails x4. Fix test independence and cleanup; the existing copy `8c315a12-20d4-4432-9db3-7cb88b27a5b4` stays untouched until the owner authorises. Linked: RR-13, the admin.spec confirmation line above. - [x] Test anomaly C (owner 2026-11-09, separate from U1/U2): CLOSED 2026-11-17 with R4's owner validation. Integrity failure invisible in catalogue cards; implemented as lot R4; failure shown, never hidden or bypassed. Built 2026-11-17 (R4 Task 1-3 and final fix wave, `V1-2-6_U1_CORRECTIONS.md` §5 row C: built by R4, closes on the owner's validation); checked off with R4's owner validation. diff --git a/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md b/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md new file mode 100644 index 00000000..789ba0f2 --- /dev/null +++ b/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md @@ -0,0 +1,1006 @@ +# U2 Direct Manipulation of Annotations Implementation Plan (V1-2.6), rev 1 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development to implement this plan task-by-task. +> Steps use checkbox (`- [ ]`) syntax for tracking. + +**Status:** rev 1, NOT validated. Waits for three fresh `plan-challenger` reviews, then the owner's approval. No U2 +code before that approval. DEV unchanged, no merge. + +**Goal:** in the sheet editor's Annotations tab, points and polygon zones are created, moved, resized, reshaped and +redrawn directly on the drawing, by mouse, by touch and by keyboard. Properties are read and edited in a modal dialog +placed over the right-hand column. Each accepted change is one undo step. No data is lost, and the drawing never +moves when the interface around it changes. + +**Architecture:** mostly page work. Gestures are decided by small pure modules: pointer slop, press priority, +polygon edits, point sizes, Escape order, move steps, missing fields and the two-finger hint. They are table-tested, +and the React hooks only wire them to DOM events. The core still judges every end state on commit, through +`geometryAccept`. One additive core value tells the page the smallest radius a point may have in each view. +`Dialog` gains a "column" placement and a light backdrop. The navigation gains an `annotation` history layer plus a +`drawing` guard for creations, redraws and move modes in progress. A fixed-height strip above the drawing and a +fixed-height message line under it replace `ToolNotes`, `SelectionTag` and `TracingBar`. The per-field properties +panel and the coordinate fields leave the edit path. + +**Tech Stack:** React 19, TypeScript strict, Zustand 5, Tailwind 4, motion 11; Rust core (`crates/core`) through the +wasm facade and `packages/core-wasm`; vitest + happy-dom; Playwright Chromium + axe on `pnpm db:sandbox`. + +**Spec:** boards `docs/design/v1-2-6-u2/` 02 to 06, 13, 31, 32 and 33, with `REVUE.md` and `ARBITRAGES.md`. Those are +A1 to A15 and the three adjustments of 2026-11-17, all validated: BDR-122. Also `docs/development/V1-2-6_UX_PLAN.md` +§U2 with its « Orientation 2026-11-14 » and its owner validation note, §1.3, §1.9, §1.10 and §2 G. Then +`V1-2-6_UX_TESTS.md` §U2 (realigned in Task 10), `V1-2-6_UX_DECISIONS.md` (T15, T16, T18) and the design contract +`.claude/tasks/contracts/2026-11-17-u2-design-boards.md`. Boards 14 and 16 (phone, read-only) are unchanged. + +Plan form, as for R2 to R4: pure functions in full; React tasks give the files, the behaviour, the test cases and how +to verify. The executor writes the JSX under TDD against the boards. + +## Audit findings (2026-11-17, read-only, at 29073a9) + +- **Gestures today.** The selection is a click (`useCanvasGestures.ts`, `clickHandler`). A selected circle or + polygon moves as a block after 4 px (`useMoveGesture.ts`, `gesture.ts:5`). An empty tap deselects + (`catalogue/useEmptyTap.ts:5`, slop 4 px, shared with the catalogue). Zoom and pan come from + `catalogue/useFraming.ts`, which is also shared with `components/catalogue/CatalogueCanvas.tsx:69`. + - With one pointer, a press pans when `canPan` allows it, using a cumulative path above 4 px. + - With two pointers it only zooms around the midpoint (`useFraming.ts:126-136`). There is NO two-finger pan + today, so A13's "two fingers move the drawing" is new work. + - The arrows pan the focused box (`useFraming.ts:150-168`). + - `touch-action` is `none` while a tool, a drag, a zoom or a movable selection is active (`useCanvasGestures.ts`, + `touchStyle`). +- **Overlay.** `AnnotationOverlay.tsx` is `aria-hidden` and `pointer-events-none`. Its vertices are decorative, with a + radius of span/200 drawing units, so they scale with the zoom. No handle can be focused or hit. +- **Layout.** These elements sit above the drawing and change height: the tool line, the hint, `UnmeasuredHint` and + `SelectionTag` (`EditableAnnotations.tsx`, `ToolNotes`). `TracingBar` sits under it (LRN-131). The canvas box is + `aspect-[4/3] w-full` (`AnnotationCanvas.tsx`). `styles/index.css:6` sets `html:has(dialog:modal) { overflow: + hidden; }`: with classic scrollbars the page loses its scrollbar while a dialog is open, so the drawing shifts + sideways. +- **Properties.** `PropertiesPanel.tsx` is shared with the narrow read-only twin (`tabs/AnnotationsTab.tsx:201-228`). + - `AnnotationFields.tsx` commits each field on its own: one `update` and one undo entry per field, through + `useSend`. + - `GeometryGroup.tsx` applies the numeric group under `accept`. This is the only way to repair an inherited point + that sits out of its frame (`e2e/shell/editor-geometry.spec.ts`), because `geometryAccept` refuses a changed + annotation that is still invalid (`issues.ts` 158-170). + - The review status is an immediate `set_status`. Deletion goes through `DeleteDialog`. A path offers « Remplacer + par un polygone » (`TraceReplacement`). +- **Creation.** `CreationPanel.tsx` and `CreationFields.tsx`; `creation.ts`: `emptyForm` preselects the first + category and leaves the laterality blank. `formProblem` returns `'fields'` or `'names'`. `fr.ts:1665` + `editor.annotations.required.fields` is the general line that board 33 B shows: « Choisissez la catégorie et la + latéralité (et la vue ouverte pour un accès). » + - The correction flow C26 (`correction.ts`, `CorrectionNotice`) prints x and y in its text (`fr.ts:1638`). + - The keyboard path (`KeyboardAdd.tsx`) places a pending element at the centre, then expects typed coordinates. + - The link tool creates a `detail_trigger` with the field `opens`. + - `insertAnnotation` and `updateGeometry` (`annotationCommit.ts`) are the geometry commits under `accept`. +- **Dialogs (R2).** + - `ModalDialog.tsx` is a full-viewport transparent native ``, with focus in and out and the Escape and + close requests. + - `Dialog.tsx` hardcodes centred placement (79) and a `bg-black/40` backdrop that closes on click (82-89). Sizes run + from sm to xl, and the panel is capped at `max-h-[85vh]`. No anchoring support exists. + - `useFormDraft(initial, guards, same, layer)` already takes a layer name (`findings/useDirtyGuard.ts:60-76`). + `FormActions` and `DiscardConfirm` live in `findings/DiscardConfirm.tsx`. `useEditCommand` provides `run`, + `runNew` and `runBatch` (one batch, one undo). +- **History layers.** `LAYERS = ['finding','citations','reference']` (`useEditorNavigation.ts:61-62`). Adding a layer + touches these files: + - `navigation.ts`: `EditorView`, `DEFAULT_VIEW`, `viewOf`, `sameView`, `restoreView`, the reducer, and the resets + in `selectTab`, `goTo` and `showAllReferences`. + - `useEditorNavigation.ts`: `useAskLeaving` and the return object. + - `history/entry.ts`: `sanitizeView`, `layerCount` and `isRemoval`. + - `history/useEditorHistory.ts`: `sameLayers`, `leavingLayers`, `upTo` and `useViewOf`. + - `history/useLeaveConfirm.ts`: `clearerOf`. + - `leftDraft.ts`: `elementOf` and `LAYERS_TOP_DOWN`. + - `tabs.ts`: `EditorPlaceProps`. + - `EditorWorkspace.tsx`: `Places`. + + Guards are keyed by `LayerName`. A POP asks only the layers it removes (`refusal`). A non-layer modal makes every + layer be asked. +- **Undo.** `state/undo.ts` keeps full document texts, capped at 8 MiB (`HISTORY_LIMIT_BYTES`). The equine draft is + 174 974 bytes as compact JSON, so the cap holds about 47 snapshots; the "about 20" of UX plan §2 G assumed pretty + JSON. Each U2 gesture is one snapshot. `useUndoShortcuts` ignores Ctrl+Z while any `dialog[open]` exists. There is + NO toast component in the app. +- **Core.** `MIN_VISIBLE_PX = 4` (`crates/core/src/anatomy/frame.rs:67`). + - The scale is `Frame::preview_scale(main)`, the xMidYMid meet scale into the phone preview boxes: main 286 × 310, + detail 254 × 191. + - A point's visible size is `2 × max(2, r − 12)` (`layer.rs:260`). It is refused when `size × scale < 4`, so the + smallest radius is `12 + 2/scale` when `scale < 1`, and there is no minimum when `scale ≥ 1`. It depends on the + view, never on the position. + - `PreviewState` (`domain/sheet/preview.rs:359-370`) is mirrored by ts-rs (`packages/core-wasm/types/PreviewState.ts`). + It is not in the N-1 reader list (runtime state, never persisted). + - Wasm gate: 600 000 B gzip-9 by Node (`packages/core-wasm/tests/size.test.ts`). The last recorded figure is + 580 522 B (`RUST.md:4523`). LRN notes that a GNU gzip measure once overstated the margin, so Task 0 re-measures. +- **Equine data.** 28 annotations: 22 circles and 6 polygons, with at most 17 vertices. Point radii are 30 and 34 on + the main view and 27 on the head view (REVUE « Données vraies »). + +## Migration inventory (where each capability lands) + +| Today | U2 | Task | +|---|---|---| +| `ToolNotes` (tool line, unmeasured hint, no-category, no-child-view, refusal hint) | Fixed strip: left = status lines, middle = refusal or notice (2 lines max), right = commands | 3 | +| `SelectionTag` | Strip, line 1 (name, status) and line 2 (type, detail) | 3 | +| `TracingBar` (« Fermer le tracé », « Annuler le tracé », count) | Strip, plus « Retirer le dernier sommet » | 3 | +| Drag of the selected shape (`useMoveGesture`) | Kept for the mouse on the interior; the point handle drags at any pointer | 4, 5 | +| `GeometryGroup` numeric fields (A8) | Removed. Repair of an out-of-frame shape = move mode (preview free, one commit on « Valider la position ») or redraw | 4, 5 | +| `TraceReplacement` (path → polygon) | Strip command « Remplacer par un polygone » on a selected path (same label, T16, BDR-101) | 5 | +| `GeometryIssues` | Strip middle (first issue, `+n` when more) and an alert block in the dialog's read mode | 3, 7 | +| `AnnotationFields` per-field commits | Dialog edit mode, one transactional save | 7 | +| `StatusActions` | Dialog read mode, direct action, one undo (A10) | 7 | +| `Deletion` + `DeleteDialog` | Dialog read mode « Supprimer », same `DeleteDialog` | 7 | +| « Désélectionner », « Tout afficher » | Strip « Désélectionner »; the overview list is always shown (A3) | 3, 7 | +| `UnmeasuredHint` | Strip middle, with its link to the views section | 3 | +| `PropertiesPanel` in the narrow read-only twin (boards 14, 16) | Kept, reduced to the shared read body (`AnnotationReadBody`) | 7 | +| `CreationPanel` (form, C26 correction, « Créer », « Annuler ») | Creation dialog: first line (« Replacer le point » / « Reprendre le tracé »), the C26 notice, then the fields; « Créer », « Abandonner » | 8 | +| `KeyboardAdd` (centre + typed coordinates) | Same buttons: the shape at the centre, the creation dialog opens; after « Créer » the keyboard handles and the move mode correct it | 8 | +| Link tool (`detail_trigger`, field `opens`) | Same creation dialog with « Vue ouverte »; same properties dialog | 7, 8 | +| « Aller à » an annotation (focus on `data-properties-heading`) | Selects it on its view and focuses its row (A1: no dialog). The strip shows its first issue | 7 | +| Focus targets `data-creation-heading` and `tracing-bar` (busy « Aller à ») | The creation dialog's heading, the strip's tracing commands | 8 | + +## Owner decisions + +None blocks the plan. Every visible choice the boards leave open is listed below with the answer applied unless the +owner objects. One condition can bring a question back, at Task 0: if neither loupe technique holds a smooth drag on a +tablet, the owner chooses between a loupe without the drawing (outline and handles only) and no loupe. + +## Recorded unless the owner objects + +- **R-1 Two-finger hint (adjustment A13).** Text FR « Deux doigts pour déplacer ou zoomer le dessin », EN « Use two + fingers to move or zoom the drawing ». + - It appears in the message line under the drawing, neutral tone, no action, for 4 s. + - It is triggered only by a one-finger drag on the drawing, past the touch slop, that moved nothing: off every + handle, outside a move mode, while touch-action is `none` because a selection, a tool or a zoom is active. + - At most once a minute. Never again in this editor visit after a two-finger pan or zoom has worked. + - It never replaces a « Défaire » message still shown; it waits for it to go. +- **R-2 Message line (adjustment A14).** The line under the drawing has a fixed height, a single line that truncates + with an ellipsis, and fixed slots: the add buttons on the left, the message on the right. + - Showing or hiding a message changes no box: the canvas, the strip and the column keep the same position and size. + The page keeps the same scroll height. Chromium's Layout Instability API records no shift. + - The page gets `scrollbar-gutter: stable` on `html`, so an open dialog does not remove the scrollbar width either. + This applies to the whole application: a page with no scrolling keeps a 15 px gutter on classic-scrollbar systems. + - The message lasts 6 s (A14) and stays while it is hovered or focused. + - Any commit, undo or redo closes it. Its « Défaire » calls the same `undo()` as the header (T15 name « Défaire la + dernière modification »). + - It is a polite live region; a refusal is `role="alert"`, red, with no « Défaire ». +- **R-3 Validation messages (adjustment board 33).** Each missing field is named under that field, and only missing + fields are named. + - FR « Saisissez le nom en français. », « Saisissez le nom en anglais. », « Choisissez une catégorie. », « Choisissez + une latéralité. » (board 33 B), « Choisissez la vue ouverte. » + - EN « Enter the French name. », « Enter the English name. », « Choose a category. », « Choose a laterality. », + « Choose the view it opens. » + - One summary line names only the missing fields: FR « À compléter : Latéralité. », EN « To complete: Laterality. » + It uses the field labels in form order and is `role="alert"`. The focus goes to the first missing field. + - The general line `editor.annotations.required.fields` is removed. The edit form of the dialog follows the same + rule. +- **R-4 C26 correction in the creation dialog.** The notice keeps its two buttons. Its text loses the numbers (A8): + FR « Le point ne tient pas à l'endroit choisi : la position corrigée est proposée sur le dessin. », EN « The point + does not fit where you clicked: the corrected position is shown on the drawing. » +- **R-5 « Aller à » an annotation.** It selects the annotation on its view and focuses its row in the overview. If a + filter hides the row, it focuses the drawing. It opens no dialog (A1). A creation or a tracing in progress keeps + the request, as today. +- **R-6 Undo depth.** `HISTORY_LIMIT_BYTES` goes from 8 MiB to 16 MiB: about 95 equine steps instead of about 47, + measured in Task 0 on the stored text. U2 turns every vertex gesture into a snapshot. 16 MiB of strings in one tab + is negligible on the target tablets. +- **R-7 Handle cap (T18).** `HANDLE_CAP = 40` vertices: the equine maximum is 17, so 40 leaves a margin of more than + two. Above it the shape shows its outline and the board 33 D message, with no handles; the move mode and redraw + remain. +- **R-8 Slop.** A press becomes a drag beyond 4 CSS px for a mouse, 6 px for a pen and 10 px for a finger, measured + as displacement from the press. One module serves the editor. The catalogue keeps its own 4 px. +- **R-9 Move step.** One arrow (strip or key) moves by 0.5 % of the frame's longer side, rounded to 0.01 with a + floor of 0.01. Shift multiplies it by 10 (keys only). +- **R-10 Point sizes.** + - Stops are the distinct radii of the view's points; links are excluded. + - A new point takes the radius used most often in the view; a tie goes to the smaller one. A view with no point + falls back to `defaultRadius(frame)` (A5). + - The slider runs from half the smaller of (smallest stop, minimum) to twice the larger of (largest stop, default + radius). It snaps to a stop within 8 CSS px. Arrows step by 1 % of the range; Page Up and Page Down go to the + next stop. + - It commits on release, Enter or blur: one undo step (BDR-050). + - The red mark is the core's minimum (Task 1). It is absent when the core gives none. +- **R-11 Pen.** A pen counts as a mouse for dragging the interior of a selected zone, but uses the pen slop and the + touch-sized handles. +- **R-12 Confirmation during a creation (A12).** A tab, a view chip, a tool, Back or Escape during a creation that + holds a shape or typed text opens a confirmation: + - FR « Abandonner la création ? », « Continuer », « Abandonner »; EN « Discard the creation? », « Continue », + « Discard ». + - Leaving the editor (a link or a tab close) asks the same through the existing leave guard and `beforeunload`. + - Inside the creation dialog, the R2 `DiscardConfirm` takes this place (A2 dialog, T15 wording). + - A click on the creation dialog's veil asks; it never discards. +- **R-13 Touch-sized handles.** Used when the last press was a finger or a pen, or when `(pointer: coarse)` matches at + load. Board 13 sizes: vertex 18 px, « + » 24 px, « − » bubble 44 × 36 px, each with a 44 px hit circle. Mouse sizes + follow board 05: vertex 12 px, « + » 16 px. Sizes stay constant in CSS px under zoom. + +## Global Constraints + +- Work in `/home/bchanot/Documents/faunosteo-v1-2`, every shell command with that absolute path checked first + (LRN-110). Commit in place on `feature/v1-2-anatomical-sheets`, one commit per coherent change, pushed by the hooks. + No sub-branch, no merge, no `gitflow.sh finish`. +- Never DEV: the `supabase_*_faunosteo` containers are DEV. Database work happens only through `pnpm db:sandbox`, in + the order `test-db → e2e:shell → test` (LRN-113). Forbidden: `pnpm db:start`, `db:reset`, `db:test`, `db:types`, + `pnpm supabase …`. Never run `editor-equine.spec.ts` outside the sandbox alias. +- The core judges every geometry. The page proposes and commits through `geometryAccept` (`insertAnnotation`, + `updateGeometry`). A refusal restores the previous shape exactly. No TypeScript copy of a core rule: the minimum + radius comes from Task 1, frame tests stay in the core. +- Rust by default (BDR-043): the geometry arithmetic in Task 2 (midpoint, translation, vertex move, snapping) is + interaction-rate preview math. UX plan §1.3 and §2 G, ratified at U0, place it in the page. It writes nothing on its + own; each result goes through `sheet.edit` and the core's verdict. One row is added to the review's Part II + exception table, class C, as R3 did. +- One undo step per accepted change: per gesture, per slider release, per move-mode validation, per dialog save, per + review toggle, per creation. Previews never enter history. +- Pending previews are cancelled and restored before any undo, redo, document replacement, save reload, tab change, + view change, mode change or second pointer (§2 G). Index-based edits never apply to a document they were not + computed on. +- No layout shift: every state change of the tab keeps the canvas box's position and size. This covers selection, + strip content, message, dialog open and close, mode entry and exit. It is asserted in Task 3's helper and used by + every later task. +- Every string goes through `useT()`, with the same keys in `fr.ts` and `en.ts`. Labels come from REVUE.md's table + and from R-1 to R-12. « Défaire » and « Refaire » are as built (R0). « Abandonner » is reserved for leaving a form + (T15). +- Rendering changes update `docs/ANNOTATION-RENDERING.md` « Editor overlay » FIRST: handles, ghost, dimmed + annotations, old outline, loupe. +- Limits: 25 logic lines per function, 100 columns for TypeScript, 5 parameters, 5 locals. `shortcut:` comments are + harvested into TODO.md. +- Phone (< 1 024 px): the editor stays read-only (O14 A). Boards 14 and 16 do not change. + +## Review Focus + +1. **A finger lands on a vertex, then a second finger lands.** The drag is cancelled, the shape restored, nothing is + committed, and the pinch zooms. Test: Task 9, CDP two-point touch. +2. **An undo arrives while a drag, a move mode or a slider is pending** (header button, Ctrl+Z from a field, Back). + The preview is dropped first and the undo applies to the committed document. Test: Task 2 table + (`cancelPreview` reasons), Task 4 unit (undo during the move mode). +3. **An editor opens the properties dialog, types, then crosses 1 024 px or presses Back.** It asks, and nothing is + lost or silently committed. Test: Task 6 and Task 7 (`editor-no-loss`, `editor-leave-confirm` cases). +4. **A message appears or expires while the user is about to tap a handle.** Nothing moves. Test: Task 3 helper + with the Layout Instability observer, used at 1 024, 1 180 and 1 280 px. +5. **An inherited out-of-frame point is repaired without coordinate fields.** The move mode previews freely and + « Valider la position » commits once, accepted. A partial move is refused and restored. Test: Task 4 (replaces + the `editor-geometry.spec.ts` numeric repair). + +## File Structure + +Pure modules, new, under `apps/app/src/editor/annotations/`: + +- `pointer.ts`: slop per pointer kind. +- `press.ts`: hit list → target → click or drag action (board 32 priority). +- `polygonEdit.ts`: midpoint insert, vertex removal, vertex move, degenerate move, handle cap. +- `pointSize.ts`: stops, most used, snap, range. +- `escape.ts`: Escape situation (board 32 rows 3 to 6). +- `moveStep.ts`: arrow step. +- `missingFields.ts`: replaces `formProblem`. +- `twoFingerHint.ts`: when the hint may show. +- `preview.ts`: the pending preview and its cancel reasons. + +React, new: + +- `components/editor/annotations/EditStrip.tsx`: the fixed strip and its command sets. +- `GestureMessage.tsx` and `editor/annotations/useGestureMessage.ts`: the message line. +- `SizeSlider.tsx`. +- `MoveModeBar.tsx`: the four arrows, « Valider la position », « Annuler ». +- `HandleLayer.tsx`: the interactive handles inside the overlay. +- `Loupe.tsx`. +- `AnnotationDialog.tsx`: read and edit. +- `AnnotationReadBody.tsx`: shared with the narrow twin. +- `AnnotationEditForm.tsx`. +- `CreationDialog.tsx`: replaces `CreationPanel.tsx`. +- `CreationConfirm.tsx`: R-12. + +Modified: + +- Canvas and overlay: `AnnotationCanvas.tsx`, `AnnotationOverlay.tsx`, `EditableAnnotations.tsx`. +- Annotation state and gestures: `uiState.ts`, `usePlacement.ts`, `useMoveGesture.ts` (folded into the press + handler), `useCanvasGestures.ts`, `gesture.ts`, `frame.ts` (`proposePoint` takes a radius), `creation.ts`. +- Shared with the catalogue: `catalogue/useFraming.ts` (opt-in options, catalogue defaults unchanged). +- Dialogs: `components/ui/Dialog.tsx` (placement, backdrop). +- Navigation and history: `navigation.ts`, `useEditorNavigation.ts`, `history/{entry,useEditorHistory,useLeaveConfirm}.ts`, + `leftDraft.ts`, `tabs.ts`, `EditorWorkspace.tsx`. +- Undo: `HistoryButtons.tsx` and `useUndoShortcuts.ts` (inactive during a creation), `state/undo.ts` (R-6). +- Page-wide: `styles/index.css` (R-2), `i18n/{fr,en}.ts`. +- Read-only twin: `tabs/AnnotationsTab.tsx`. + +Removed: + +- `GeometryGroup.tsx`, `ToolNotes` (inside `EditableAnnotations`), `TracingBar.tsx`, `SelectionTag.tsx`, + `CreationPanel.tsx`. +- The edit paths of `PropertiesPanel.tsx`, and `AnnotationFields.tsx`'s per-field commits. +- `geometryEdit.ts`'s field helpers (`fieldsOf`, `parseFields`, `sameAsStored`, `changedFieldNames`, + `withVertexAfter`, `withoutVertex`); `isEditable` stays. + +Core: + +- `crates/core/src/anatomy/frame.rs` (`min_point_radius`). +- `crates/core/src/domain/sheet/preview.rs` (`PreviewState.min_point_radius`). +- `crates/core/tests/sheet_preview.rs`. +- `packages/core-wasm/types/PreviewState.ts` (generated). +- `packages/core-wasm/tests/contracts.types.test.ts`. + +### Task 0: Baselines and the loupe spike (nothing shipped) + +**Files:** a scratch harness page `apps/app/e2e/harness/loupe-spike.{html,tsx}` (dev server only, deleted at the end +of the task). Results go into this plan's « Task 0 results ». + +- [ ] **Step 1: wasm baseline.** Run `pnpm wasm:build` then `pnpm --filter @faunosteo/core-wasm exec vitest run + tests/size.test.ts`, and record the gate's printed gzip figure and the margin to 600 000 B. +- [ ] **Step 2: undo depth.** In a unit test against the bundled draft (`tests/helpers/sheet.ts`), print + `encoder.encode(state.documentText).length` after load. Compute 8 MiB and 16 MiB divided by it, and record both + depths. Confirm or correct R-6. +- [ ] **Step 3: loupe, technique A.** In the harness, use the composed equine main view. + - At touch-drag start, clone the drawing's `` once (`cloneNode(true)`, `aria-hidden`, `inert`) into a + 120 px circular box placed 90 px above the finger and clamped inside the canvas box. + - Scale it ×2 around the finger point, with the overlay's preview outline copied on top. + - Measure, in Chromium with touch emulation at 1 180 px and CPU throttling ×4 (CDP + `Emulation.setCPUThrottlingRate`), the median and 95th percentile of `pointermove` handling to next frame over + a 2 s drag. Pass: p95 under 16 ms. +- [ ] **Step 4: technique B, if A fails.** The loupe shows the overlay only (outline, handles, finger point) on a + white disc, without the drawing. If B is the only one to pass, STOP and ask the owner (Owner decisions). +- [ ] **Step 5:** delete the harness files, write the figures here and in `docs/development/RUST.md` (size). Commit + the plan and RUST.md: `docs(docs): U2 baselines, wasm size, undo depth, loupe spike`. + +### Task 1: Core: the smallest radius a point may have in each view + +**Files:** + +- Modify `crates/core/src/anatomy/frame.rs` (beside `annotation_placement`, l.208-227). +- Modify `crates/core/src/domain/sheet/preview.rs` (`PreviewState`, l.359-370; `state()`, l.272-292). +- Test `crates/core/tests/sheet_preview.rs`. +- Generated `packages/core-wasm/types/PreviewState.ts`. +- Test `packages/core-wasm/tests/contracts.types.test.ts`. +- App reader `apps/app/src/editor/annotations/minRadius.ts`. + +**Interfaces:** + +- Produces (Rust): + +```rust +/// The smallest hitbox radius of a point (a circle that is not a trigger) that passes +/// `TooSmall` in a view with this frame; None when every positive radius passes +/// (preview scale ≥ 1, the twin's 2-unit floor already shows 4 px). +pub fn min_point_radius(frame: &Frame, main_view: bool) -> Option +``` + + It is computed from the same constants as `annotation_placement`. With `scale = frame.preview_scale(main_view)`, + the twin must reach `MIN_VISIBLE_PX / 2 / scale`. Because `twin_radius(r) = max(2, r - 12)`, the result is + `Some(12 + MIN_VISIBLE_PX / 2 / scale)` when that twin exceeds 2, else `None`. The value is rounded UP to 0.01, so + the page never offers a refused value at the mark. +- Produces (state): `PreviewState.min_point_radius: BTreeMap`, view id → radius, with only views that + have a usable frame and a minimum. ts-rs gives `{ [key in string]?: number }`. +- Produces (app): `minPointRadius(state: PreviewState | null, viewId: string): number | null` in `minRadius.ts`. + +- [ ] **Step 1: failing Rust tests** in `sheet_preview.rs`: + - The equine main and head views give the values computed from their frames. Assert against the formula on the + frame read from the fixture, not a pasted number. + - A frame of width 100 (scale > 1) gives no entry. + - A frame exactly at scale 1 gives no entry. + - A view without a usable frame gives no entry. + - For each entry, a circle with `r = value` passes `annotation_placement` and `r = value − 0.01` gives `TooSmall`. + This consistency check is the property that matters. +- [ ] **Step 2:** `cargo test -p faunosteo-core --test sheet_preview`: FAIL (the field is missing). +- [ ] **Step 3:** implement `min_point_radius`, fill the map in `state()`, and run `cargo test` with features `ts` to + regenerate `PreviewState.ts`. +- [ ] **Step 4:** `pnpm rust:check` green. `pnpm wasm:build`, then the size test, then record the figure and its delta + against Task 0 in `RUST.md`. Then `contracts.types.test.ts` asserts the field's shape, and an app unit test checks + `minPointRadius` on the bundled draft equals the core's value. +- [ ] **Step 5:** commit Rust, the generated types and RUST.md: `feat(domain): per-view minimum point radius in + preview state`. + +### Task 2: Pure interaction modules + +**Files:** create the nine modules of the File Structure, each with `tests/unit/annotations..test.ts` table +tests. `gesture.ts` keeps `translatedGeometry` and `clientToDrawing`, and loses `DRAG_START_PX` and +`pastDragThreshold` for `pointer.ts`. + +**Interfaces (produced, exact):** + +```ts +// pointer.ts +import type { XY } from './frame' +export type PointerKind = 'mouse' | 'pen' | 'touch' +/** CSS px a press travels before it is a drag (R-8): a finger jitters more than a mouse. */ +export const SLOP_PX: Readonly> = { mouse: 4, pen: 6, touch: 10 } +export function pointerKindOf(pointerType: string): PointerKind { + return pointerType === 'touch' || pointerType === 'pen' ? pointerType : 'mouse' +} +export function pastSlop(kind: PointerKind, from: XY, to: XY): boolean { + return Math.hypot(to.x - from.x, to.y - from.y) > SLOP_PX[kind] +} +``` + +```ts +// press.ts +import type { PointerKind } from './pointer' +export type HandleRef = + | { kind: 'point' } + | { kind: 'vertex'; index: number } + | { kind: 'insert'; after: number } + | { kind: 'remove'; index: number } +/** One element under the pointer, top first (document.elementsFromPoint order). */ +export type Hit = { kind: 'handle'; handle: HandleRef } | { kind: 'annotation'; id: string } +export type PressTarget = + | { kind: 'handle'; handle: HandleRef } + | { kind: 'other'; id: string } + | { kind: 'interior'; id: string } + | { kind: 'empty' } +export interface Selection { + selectedId: string | null + chosenVertex: number | null +} +/** Board 32: the selection's handles, then another annotation, then its interior, then nothing. */ +export function pressTarget(hits: readonly Hit[], sel: Selection): PressTarget { + for (const hit of hits) if (hit.kind === 'handle') return hit + const other = hits.find((h) => h.kind === 'annotation' && h.id !== sel.selectedId) + if (other?.kind === 'annotation') return { kind: 'other', id: other.id } + const own = hits.some((h) => h.kind === 'annotation' && h.id === sel.selectedId) + return own && sel.selectedId !== null + ? { kind: 'interior', id: sel.selectedId } + : { kind: 'empty' } +} +export type ClickAction = + | { type: 'choose_vertex'; index: number } + | { type: 'insert'; after: number } + | { type: 'remove'; index: number } + | { type: 'select'; id: string } + | { type: 'unchoose' } + | { type: 'open'; id: string } + | { type: 'deselect' } +/** A press released within the slop (A1): select first, open on the selection itself. */ +export function clickAction(target: PressTarget, sel: Selection): ClickAction { + if (target.kind === 'other') return { type: 'select', id: target.id } + if (target.kind === 'empty') return { type: 'deselect' } + if (target.kind === 'interior') { + return sel.chosenVertex === null ? { type: 'open', id: target.id } : { type: 'unchoose' } + } + const { handle } = target + if (handle.kind === 'vertex') return { type: 'choose_vertex', index: handle.index } + if (handle.kind === 'insert') return { type: 'insert', after: handle.after } + if (handle.kind === 'remove') return { type: 'remove', index: handle.index } + return sel.selectedId ? { type: 'open', id: sel.selectedId } : { type: 'deselect' } +} +export type DragAction = + | { type: 'drag_point' } + | { type: 'drag_vertex'; index: number } + | { type: 'drag_shape'; id: string } + | { type: 'pan' } + | { type: 'none'; futile: boolean } +/** A press past the slop: a finger moves only what it holds (A13); a mouse or pen drags the interior. */ +export function dragAction(target: PressTarget, kind: PointerKind): DragAction { + if (target.kind === 'handle') { + if (target.handle.kind === 'point') return { type: 'drag_point' } + if (target.handle.kind === 'vertex') return { type: 'drag_vertex', index: target.handle.index } + return { type: 'none', futile: false } + } + if (kind === 'touch') return { type: 'none', futile: true } + if (target.kind === 'interior') return { type: 'drag_shape', id: target.id } + return { type: 'pan' } +} +``` + +Notes: + +- `pan` is the mouse or pen pan, only when zoomed; `useFraming` still decides through `canPan`. +- A mouse drag on another annotation pans. It never selects. +- `futile: true` feeds R-1. + +```ts +// polygonEdit.ts +import type { Point } from '@faunosteo/core-wasm/types' +import { round2, type XY } from './frame' +/** T18 (R-7): above this many vertices, outline and message, no handle. */ +export const HANDLE_CAP = 40 +export const MIN_VERTICES = 3 +const inRange = (points: readonly Point[], i: number) => + Number.isInteger(i) && i >= 0 && i < points.length +/** « + » on the segment from vertex `after` to the next (wrapping): its midpoint, 0.01 grid. */ +export function insertMidpoint(points: readonly Point[], after: number): Point[] | null { + if (!inRange(points, after)) return null + const [ax, ay] = points[after] + const [bx, by] = points[(after + 1) % points.length] + const middle: Point = [round2((ax + bx) / 2), round2((ay + by) / 2)] + return [...points.slice(0, after + 1), middle, ...points.slice(after + 1)] +} +/** « − »: null at 3 vertices (board 12 B reason shown by the caller). */ +export function removeVertex(points: readonly Point[], index: number): Point[] | null { + if (!inRange(points, index) || points.length <= MIN_VERTICES) return null + return points.filter((_, i) => i !== index) +} +export function moveVertex(points: readonly Point[], index: number, to: XY): Point[] | null { + if (!inRange(points, index) || !Number.isFinite(to.x) || !Number.isFinite(to.y)) return null + return points.map((p, i): Point => (i === index ? [round2(to.x), round2(to.y)] : p)) +} +/** A vertex released on itself or on a neighbour is no change (no commit). */ +export function isNoOpMove(points: readonly Point[], index: number, moved: readonly Point[]): boolean { + const n = points.length + const [x, y] = moved[index] + return [index, (index + 1) % n, (index + n - 1) % n].some( + (j) => points[j][0] === x && points[j][1] === y, + ) +} +``` + +```ts +// pointSize.ts +import type { Annotation } from '@faunosteo/core-wasm/types' +import { round2 } from './frame' +const pointRadii = (annotations: readonly Annotation[], viewId: string): number[] => + annotations.flatMap((a) => + a.kind === 'point' && a.view_id === viewId && a.geometry?.type === 'circle' ? [a.geometry.r] : [], + ) +/** The slider's stops: the distinct radii of the view's points, ascending (links excluded). */ +export function sizeStops(annotations: readonly Annotation[], viewId: string): number[] { + return [...new Set(pointRadii(annotations, viewId))].sort((a, b) => a - b) +} +/** A5: the radius used most in the view, the smaller on a tie; null without any point. */ +export function mostUsedSize(annotations: readonly Annotation[], viewId: string): number | null { + const counts = new Map() + for (const r of pointRadii(annotations, viewId)) counts.set(r, (counts.get(r) ?? 0) + 1) + let best: [number, number] | null = null + for (const [r, n] of counts) { + if (!best || n > best[1] || (n === best[1] && r < best[0])) best = [r, n] + } + return best?.[0] ?? null +} +/** The nearest stop within `reach` drawing units, else the value on the 0.01 grid. */ +export function snapSize(value: number, stops: readonly number[], reach: number): number { + let nearest: number | null = null + for (const stop of stops) { + if (Math.abs(stop - value) <= reach && (nearest === null || Math.abs(stop - value) < Math.abs(nearest - value))) + nearest = stop + } + return nearest ?? round2(value) +} +export interface SizeRange { low: number; high: number } +/** R-10: half the smaller of (smallest stop, minimum) to twice the larger of (largest stop, fallback). */ +export function sizeRange(stops: readonly number[], minimum: number | null, fallback: number): SizeRange { + const lows = [stops[0], minimum].filter((v): v is number => v !== null && v !== undefined) + const base = lows.length > 0 ? Math.min(...lows) : fallback + const low = round2(Math.max(0.01, base / 2)) + const high = round2(2 * Math.max(stops[stops.length - 1] ?? fallback, fallback)) + return { low, high } +} +``` + +```ts +// escape.ts +export interface EscapeInput { + creating: boolean + /** A shape placed or traced, or a typed field, in the creation. */ + holdsWork: boolean + redrawingOrMoving: boolean + chosenVertex: number | null + selectedId: string | null +} +export type EscapeAction = 'ask_creation' | 'drop_creation' | 'drop_mode' | 'unchoose' | 'deselect' | null +/** Board 32 rows 3 to 6 (rows 1 and 2, a dialog and the side panel, consume Escape first). */ +export function escapeAction(s: EscapeInput): EscapeAction { + if (s.creating) return s.holdsWork ? 'ask_creation' : 'drop_creation' + if (s.redrawingOrMoving) return 'drop_mode' + if (s.chosenVertex !== null) return 'unchoose' + return s.selectedId !== null ? 'deselect' : null +} +``` + +```ts +// moveStep.ts +import { round2, type Frame } from './frame' +/** R-9: one arrow = 0.5 % of the frame's longer side (0.01 at least); Shift ×10 on keys. */ +export function moveStep(frame: Frame, big: boolean): number { + const step = Math.max(0.01, round2(Math.max(frame.w, frame.h) * 0.005)) + return big ? round2(step * 10) : step +} +``` + +```ts +// missingFields.ts (replaces creation.ts formProblem) +import type { CreationForm, NewKind } from './creation' +export type MissingField = 'name_fr' | 'name_en' | 'category' | 'laterality' | 'opens' +const blank = (v: string) => v.trim() === '' +/** Board 33 adjustment: only what is really missing, in the form's order. */ +export function missingFields(kind: NewKind, form: CreationForm): MissingField[] { + const missing: MissingField[] = [] + const bothOrNone = kind === 'detail_trigger' && blank(form.fr) && blank(form.en) + if (!bothOrNone && blank(form.fr)) missing.push('name_fr') + if (!bothOrNone && blank(form.en)) missing.push('name_en') + if (form.categoryId === '') missing.push('category') + if (form.laterality === '') missing.push('laterality') + if (kind === 'detail_trigger' && form.opensViewId === '') missing.push('opens') + return missing +} +``` + +```ts +// twoFingerHint.ts +export const HINT_GAP_MS = 60_000 +export interface HintMemory { lastShown: number | null; twoFingerUsed: boolean } +/** R-1: after a futile one-finger drag, at most once a minute, never after two fingers worked. */ +export function mayHintTwoFingers(memory: HintMemory, now: number): boolean { + if (memory.twoFingerUsed) return false + return memory.lastShown === null || now - memory.lastShown >= HINT_GAP_MS +} +``` + +```ts +// preview.ts +import type { Geometry } from '@faunosteo/core-wasm/types' +/** A geometry shown but not committed: a drag, a move mode, a slider, a redraw. */ +export interface PendingPreview { annotationId: string; geometry: Geometry; source: 'drag' | 'move' | 'size' | 'redraw' } +export type CancelReason = + | 'undo' | 'redo' | 'replace_document' | 'save_reload' | 'tab' | 'view' | 'mode' | 'second_pointer' | 'escape' +/** §2 G: every reason drops the preview and restores the stored shape; none commits. */ +export function cancelPreview(_reason: CancelReason): null { + return null +} +``` + +`cancelPreview` exists so that every call site names its reason and the table test lists them all. Its only +behaviour is that no reason commits. + +- [ ] **Step 1: failing table tests**, one file per module. These are the cases that pin the boards. + - `pressTarget`: a handle beats everything. A point drawn inside the selected zone beats the zone (board 32 row 2). + Only the selected annotation hit gives `interior`. No hit gives `empty`. Another zone overlapping the interior + gives `other`. + - `clickAction`: interior with a chosen vertex gives `unchoose`, without one `open`. A point handle gives `open`. A + vertex gives `choose_vertex`. + - `dragAction`: a touch on the interior, on empty or on another annotation gives `none` with `futile: true`. A + mouse on the interior gives `drag_shape`. The `insert` and `remove` handles never drag. + - `insertMidpoint`: the wrap from the last vertex to the first, and an out-of-range index returns null. + - `removeVertex`: returns null at 3 vertices. + - `moveVertex`: returns null for a non-finite target. + - `isNoOpMove`: true on the neighbours. + - `sizeStops` and `mostUsedSize`: on the bundled draft's views, 30 and 34 on the main view and 27 on the head + (REVUE data). A tie goes to the smaller radius. A view with no point gives null. + - `snapSize`: the reach edges. + - `sizeRange`: with and without a minimum. + - `escapeAction`: the board 32 order. + - `moveStep`: tiny and large frames, Shift. + - `missingFields`: a category already chosen is never listed (adjustment 3). A link with both names blank is + fine, with one blank names it. The fields come in form order. + - `mayHintTwoFingers`: the gap edge, and `twoFingerUsed`. +- [ ] **Step 2:** `pnpm --filter @faunosteo/app exec vitest run tests/unit/annotations.` gives FAIL. +- [ ] **Step 3:** write the modules as above. Move `useCanvasGestures` and `useMoveGesture` to `pastSlop`; keep the + 4 px mouse behaviour (the existing tests stay green). +- [ ] **Step 4:** the same run gives PASS. Then `pnpm typecheck && pnpm lint`. +- [ ] **Step 5:** commit `feat(editor): pure U2 interaction rules (slop, priority, polygon, sizes, escape)`. + +### Task 3: The fixed strip, the message line, the stable gutter + +**Files:** + +- Create `EditStrip.tsx`, `GestureMessage.tsx` and `editor/annotations/useGestureMessage.ts`. +- Modify `EditableAnnotations.tsx`: remove `ToolNotes`, `TagOf` and `TracingBar`, and mount the strip over both + columns. +- Modify `styles/index.css` (`html { scrollbar-gutter: stable; }`) and i18n. +- E2E helper `apps/app/e2e/support/layout.ts`. + +**Interfaces:** + +- Produces `EditStrip` props: + - `{ lead: StripLead; notice: StripNotice | null; commands: ReactNode }` + - `StripLead = { title: string; status?: ReviewStatus; detail: string; icon: IconName }` + - `StripNotice = { tone: 'error' | 'info'; text: string; link?: { label: string; onClick(): void } }` +- Produces `useGestureMessage()`: + - Returns `{ message, show(text, { undo: boolean, tone }), hint(text) }`. + - It subscribes to the editor store and clears on any change of the history stacks or of `documentText`. + - The 6 s timer pauses while hovered or focused. +- Produces the e2e helper `expectNoShift(page, act: () => Promise, locators)`. It records the bounding boxes + of the canvas, the strip and the aside, plus `document.scrollingElement.scrollHeight`, and sums the + `layout-shift` entries of a `PerformanceObserver({ type: 'layout-shift', buffered: false })` installed before + `act`. It asserts equal boxes and a zero sum. + +- [ ] **Step 1: failing unit tests** (`editor-annotations-tab.test.tsx`, new `describe('the strip')`). + - The strip renders the board labels per state: tool Point (« Ajouter un point », « Cliquez dans le dessin pour + placer le point »), a selected point, a selected zone (« Zone · 9 sommets »), tracing (« Fermer le tracé », + « Retirer le dernier sommet », « Annuler le tracé »), read-only (« Point · fiche en lecture seule »), and an + unmeasured view with its link. + - The strip has a fixed height class and `overflow-hidden`. + - Long names truncate before the status. + - The message: a commit through `updateGeometry` shows « Point déplacé · Défaire ». « Défaire » calls the store's + `undo` and disappears. A second commit replaces the message. An undo from the header clears it. A refusal shows + in `role="alert"` with no « Défaire ». Hover keeps it past 6 s (fake timers). + - « Retirer le dernier sommet » and Backspace remove the last tracing vertex. +- [ ] **Step 2:** FAIL. **Step 3:** implement and move the existing hint, unmeasured, no-category and no-child-view + texts into the strip notice. +- [ ] **Step 4:** e2e `editor-annotations.spec.ts`, new test « the drawing never moves ». At 1 024, 1 180 and + 1 280 px, `expectNoShift` holds around select, deselect, tool change, tracing start and close, a commit message + showing, and its 6 s expiry (clock `page.clock`). Existing tests stay green after their selectors move from the + tool line to the strip. +- [ ] **Step 5:** `pnpm typecheck && pnpm test:run && pnpm lint`, then commit `feat(editor): fixed edit strip and + message line without layout shift`. + +### Task 4: Point editing: handle, size slider, move mode, repair + +**Files:** + +- Create `HandleLayer.tsx`, `SizeSlider.tsx` and `MoveModeBar.tsx`. +- Modify `AnnotationOverlay.tsx`: it hosts `HandleLayer`, and `pointer-events` is enabled on handles only. +- Modify `useCanvasGestures.ts`: one press handler built on `press.ts` replaces `useMoveGesture`. +- Modify `uiState.ts` (`chosenVertex`, `mode: { kind: 'move'; target; preview } | null`, `size: number | null`) and + `frame.ts` (`proposePoint(frame, click, radius)`). +- Doc `docs/ANNOTATION-RENDERING.md` « Editor overlay » FIRST. + +**Interfaces:** + +- Consumes Task 2 (`pressTarget`, `clickAction`, `dragAction`, `pastSlop`, `pointSize`, `moveStep`, `preview`) and + Task 3 (`EditStrip`, `useGestureMessage`). +- Produces the ui actions `{ type: 'mode_move'; target: 'shape' | { vertex: number } }`, `{ type: 'mode_preview'; + geometry }`, `{ type: 'mode_end' }`, `{ type: 'choose_vertex'; index: number | null }` and `{ type: 'size'; + radius: number }`. +- Produces the hit reading `hitsAt(client: XY): Hit[]`. It uses `document.elementsFromPoint`, maps handles by + `data-handle` (JSON of `HandleRef`) and annotations by `annotationIdOf`, and lives in `useCanvasGestures.ts`. +- Handles carry `role="button"`, `tabindex="0"` and `aria-label` « Point {nom} », « Sommet {i} de {nom} », « Ajouter un + sommet après le sommet {i} » or « Retirer le sommet {i} ». + +- [ ] **Step 1: doc.** Update « Editor overlay »: handles and their sizes (R-13), the chosen vertex (bigger, filled, + ringed), the old place (grey dashes), the refused place (red dashes) and the move-mode target. +- [ ] **Step 2: failing tests.** + - Unit: on a selected point the strip shows the slider with stops (main view 30 and 34) and the red mark at the + core value. Arrow, Page Up and release commit once (history depth +1). A value under the mark is refused by the + core, with the message in red and the size restored. + - « Déplacer le point » enters the mode. The strip arrows move by `moveStep`, nothing is committed until + « Valider la position », which commits once. « Annuler » and Escape restore it. Undo during the mode cancels + the preview first (Review Focus 2). + - Keyboard on the focused point handle: arrows move as a series, committed once on Enter or blur. + - E2E mouse: + - Drag a point. A click on the selected point opens nothing yet (the dialog comes in Task 7; the test asserts + the selection is kept). + - Change the size by a track click (WCAG 2.5.7). + - Repair the inherited out-of-frame point of `editor-geometry.spec.ts` with the move mode, replacing the + numeric repair (Review Focus 5). A partial move is refused and restored. + - Each with `expectNoShift`. +- [ ] **Step 3:** implement. + - The new point's size is the slider's value: A5 default, and the strip slider is shown with the Point tool + before the click. + - `proposePoint` uses that radius. +- [ ] **Step 4:** `pnpm typecheck && pnpm test:run && pnpm lint`, and the e2e files touched, on the sandbox. +- [ ] **Step 5:** commit `feat(editor): point handle, size slider with core minimum, move mode`. + +### Task 5: Zone editing: vertices, « + », « − », interior drag, redraw, paths, cap + +**Files:** `HandleLayer.tsx` (vertices, insert, remove bubble), `useCanvasGestures.ts`, `usePlacement.ts` (redraw = +tracing target `replace` on any polygon; « Retirer le dernier sommet »), `EditStrip.tsx` commands, removal of +`GeometryGroup.tsx` and the field helpers of `geometryEdit.ts`, i18n. + +**Interfaces:** Consumes `polygonEdit.ts`, `HANDLE_CAP`, and the Task 4 mode and handle layer. Produces +`{ type: 'trace_pop' }`. Redraw keeps the old outline as `overlay.old` until closing is accepted. + +- [ ] **Step 1: failing tests.** + - Unit: + - A click on a vertex chooses it (strip « sommet 7 choisi »). A click on the interior unchooses it. A drag of a + vertex commits one update. A release on a neighbour commits nothing. + - « + » inserts and chooses the new vertex. « − » removes it, and at 3 vertices it is disabled with « Une zone + garde au moins 3 sommets ». + - Insert and Delete on the keyboard. + - The interior drag by mouse moves the zone. « Déplacer la zone » and « Déplacer le sommet » use the Task 4 mode. + - A shape with 41 vertices shows the outline and the cap message, with no handles, and still allows the mode and + redraw. + - A path shows no handle, offers « Remplacer par un polygone », and its `d` is byte-identical after neighbour + gestures (UX_TESTS « Paths »). + - Redraw: the old outline stays during the trace. An accepted closing commits once, keeping name, category, + laterality, region, zone and status. A refusal (`interior_too_small`) keeps the trace open with its message. + Escape keeps the old shape. + - E2E mouse on the « Thoraciques » zone: drag a vertex, « + », « − », zone drag, redraw accepted and refused, and + undo for each (owner demo script), each with `expectNoShift`. +- [ ] **Step 2:** FAIL. **Step 3:** implement, then delete `GeometryGroup.tsx` and the unit cases of « a numeric + edit ». Map each removed assertion to its replacement in the commit body. +- [ ] **Step 4:** gates as in Task 4. **Step 5:** commit `feat(editor): vertex handles, insert and remove, zone move, + redraw; numeric group removed`. + +### Task 6: Dialog column placement and the annotation history layer + +**Files:** + +- `components/ui/Dialog.tsx`: + - `placement?: 'center' | { anchor: RefObject }`, default `'center'`. + - `backdrop?: 'default' | 'light'`: `bg-black/40` or `bg-[color-mix(in_srgb,var(--color-ink)_22%,transparent)]`. +- `styles/index.css`. +- Navigation and history: `navigation.ts`, `useEditorNavigation.ts`, `history/{entry,useEditorHistory,useLeaveConfirm}.ts`, + `leftDraft.ts`, `tabs.ts` and `EditorWorkspace.tsx`. + +**Interfaces:** + +- Produces `EditorView.annotation: AnnotationLayer | null`, with `type AnnotationLayer = { id: string } | { create: + NewKind }`. It is read only on tab `annotations`; `{ create }` is a form and is dropped when `forms` is false. +- Produces `LAYERS = ['annotation', 'finding', 'citations', 'reference']`. The annotation layer and the finding layer + never coexist: they belong to different tabs. +- Produces `GuardName = LayerName | 'drawing'`. + - `Guards.register` and `Guards.ask` accept `'drawing'`. + - `refusal` asks `'drawing'` on every POP while it is registered. + - `useLeaveConfirm` and `beforeunload` treat a registered `drawing` that holds work as dirty. +- Produces `EditorPlaceProps.annotationLayer`: + - `{ open(id: string): void; startCreation(kind: NewKind): void; close(forced?: boolean): boolean; replace(layer: + AnnotationLayer | null, text?: string): void }` + - These mirror `openFinding`, `startFinding`, `closeFinding` and `replaceFinding`. +- Column placement: + - The panel sits at `left = rect.left`, `width = rect.width` and `top = max(12, rect.top)` of the anchor (the aside). + - Its height is clamped to `visualViewport.height − top − 12`. It is recomputed on `resize` and on + `visualViewport` `resize` and `scroll` (the tablet keyboard). + - With no anchor box (below `lg`), the placement is centred. + - The motion origin is top. Reduced motion is kept. + +- [ ] **Step 1: failing tests.** + - `ui.Dialog.test.tsx`: the anchored geometry from a stubbed rect, the light backdrop class, the centred fallback, + and a backdrop click calling `onClose` (unchanged). + - `editor-navigation.test.ts`, `editor-history-entry.test.ts` and `editor-history-guards.test.tsx`: + - The annotation layer opens and closes with one entry. Back closes it, Forward reopens it. + - A layer for an id that no longer exists is sanitised away, and the view lands on the selection with an + announcement. + - A layer for an annotation of another view switches the view and selects it. + - `sanitizeView` keeps it only on the annotations tab. + - A `drawing` guard that refuses keeps the POP, re-pushes and shows R-12. + - E2E `expectNoShift` around a dialog open and close at 1 280 px on a classic-scrollbar page (`scrollbar-gutter`). +- [ ] **Step 2:** FAIL. **Step 3:** implement the layer at each site listed in the audit (TypeScript exhaustiveness + on `Record` finds them). **Step 4:** gates. The unit layer suites are green, and so are + `editor-history.spec.ts`, `editor-leave-confirm.spec.ts` and `editor-finding-dialog.spec.ts` on the sandbox + (findings unchanged). +- [ ] **Step 5:** commit `feat(editor): annotation history layer, drawing guard, dialog over the column`. + +### Task 7: The properties dialog (A1, A2, A3, A9, A10) + +**Files:** + +- Create `AnnotationDialog.tsx`, `AnnotationReadBody.tsx` and `AnnotationEditForm.tsx`. +- Modify `EditableAnnotations.tsx`: + - The aside always shows `OverviewPanel` with the selected row marked (`aria-current="true"`). + - The dialog is anchored to the aside. +- Modify `AnnotationList.tsx`: Enter on the selected row opens. +- Modify `tabs/AnnotationsTab.tsx`: the narrow twin uses `AnnotationReadBody`. +- Remove the edit paths of `PropertiesPanel.tsx` and the per-field commits of `AnnotationFields.tsx`; the fields + become plain controlled inputs. +- Modify `focusTarget.ts` (R-5) and i18n. + +**Interfaces:** + +- Consumes Task 6's layer and placement, `useFormDraft(initial, guards, same, 'annotation')`, `FormActions`, + `DiscardConfirm`, `useItemMode`, `useEditCommand` and `missingFields`'s edit-form twin (names only: + `editor.field.required`). +- Save: + 1. Read the CURRENT annotation from `useEditorStore.getState().previewState.document` by id. + 2. Merge the changed fields. + 3. Run one `update`. + 4. If the stored annotation changed underneath (an id gone), stop with the vanished-element replace. +- Opening (A1): `clickAction` gives `open`, from a click on the selected shape's interior or point. Also on a + double click on an annotation (`dblclick`, which selects it then opens), Enter on the selected row, and the strip's + « Propriétés ». A drag never opens. +- Focus return (board 32): + - Opened by « Propriétés »: the button. + - Opened from the drawing or the list: the row, or the drawing when the row is filtered out. + - « Modifier la forme »: the dialog closes, keeps the selection and focuses the first handle. + +- [ ] **Step 1: failing tests.** + - Unit: + - Reading mode on a point and a zone shows the fields as text. « Couleur » appears only when set, « Région + vertébrale » only when set, and « Vue » is shown. + - « Marquer comme relu » gives one undo and a message. « Remettre à confirmer » reverts it. + - « Supprimer » goes through `DeleteDialog`. + - « Modifier »: change the category and both names, save, and get ONE history entry. + - « Annuler » when dirty asks; « Abandonner » writes nothing. + - A blank name is refused on its field. + - The geometry issues block is shown in read mode for an inherited out-of-frame point. + - The narrow twin renders the same read body (ids prefixed, `editor-no-loss` case kept). + - Selection without a dialog: a first click or Enter on a row only selects (A1). + - « Aller à » focuses the row (R-5). + - E2E: + - The dialog sits over the aside: its box is inside the aside's x-range and starts at its top, and it never + overlaps the canvas box at 1 024, 1 180 and 1 280 px. + - axe in read and edit modes. + - A typed form, then Back, asks; then « Abandonner ». A typed form, then a 1 024 px crossing, keeps the left + draft as the finding dialog does (Review Focus 3). + - `expectNoShift` holds. +- [ ] **Step 2:** FAIL. **Step 3:** implement. Map every removed `PropertiesPanel` and `AnnotationFields` assertion + (`editor-annotations-tab`, `editor-deselect.spec`, `editor-annotations.spec`, `editor-focus-request`, + `editor-escape`) to its replacement in the commit body. +- [ ] **Step 4:** gates and the touched e2e suites on the sandbox. **Step 5:** commit `feat(editor): annotation + properties dialog over the column, transactional save`. + +### Task 8: Creation by placing and tracing, then the creation dialog (A4, A5, A7, A12, A15) + +**Files:** + +- Create `CreationDialog.tsx`, replacing `CreationPanel.tsx`, and `CreationConfirm.tsx`. +- Modify `CreationFields.tsx` (field order: vertebral region before findings zone, as the edit form), `creation.ts` + (`missingFields`), `usePlacement.ts`, `uiState.ts` (`creation: { phase: 'placing' | 'tracing' | 'dialog' | + 'resumed' }`), `KeyboardAdd.tsx`, `HistoryButtons.tsx` and `useUndoShortcuts.ts` (inactive during a creation), + `useCanvasBuild.ts` or the host class for dimming (doc first), and i18n. + +**Interfaces:** Consumes Task 6 (`startCreation`, `drawing` guard) and Task 2 (`missingFields`, `escapeAction`). +« Créer » = `insertAnnotation` under `accept`, one undo step. Then the tool returns to « Sélectionner », the new +annotation is selected (A7), and the message « Point créé · Défaire » or « Zone créée · Défaire » shows. + +- [ ] **Step 1: failing tests.** + - Unit: + - The Point tool: a click places the point at the strip size and the dialog opens by itself with the ghost under + the light veil. + - Changing the category recolours the ghost (A4). The laterality has no default (A4). + - « Créer » with a missing laterality shows only « Choisissez une latéralité. » and the summary « À compléter : + Latéralité. », never the category (adjustment 3). A missing English name names only it. + - « Replacer le point » closes the dialog with the form kept; the next click moves the ghost and reopens the + dialog. + - The zone tool: a trace, then a close on the first vertex, Enter or « Fermer le tracé », opens « Nouvelle zone ». + « Reprendre le tracé » keeps the vertices and shows « Revenir aux propriétés ». + - « Abandonner » with typed text asks (`DiscardConfirm`). A veil click asks (R-12). + - During a creation, other annotations are dimmed and unselectable. Tab, view chip, tool, Back and Escape ask + (R-12). « Défaire » is inactive. + - The keyboard add buttons place the shape at the centre and open the dialog. + - A link uses « Vue ouverte ». + - C26: a click at the edge shows the correction notice in the dialog (R-4). + - E2E: point, zone and link created by clicks, undone and redone, then saved (`editor-annotations.spec.ts` + rewritten). Keyboard only: create a zone, add and remove a vertex, move the zone, validate (UX_TESTS + « Keyboard »). axe on the creation states. `expectNoShift` when the dialog opens. +- [ ] **Step 2:** FAIL. **Step 3:** implement and delete `CreationPanel.tsx`. **Step 4:** gates. +- [ ] **Step 5:** commit `feat(editor): creation on the drawing then the creation dialog`. + +### Task 9: Touch: slop, one finger, two fingers, the hint, the loupe, 44 px + +**Files:** + +- `catalogue/useFraming.ts`: opt-in options, catalogue unchanged. + - `slopOf?: (event) => number` + - `onePointerPan?: (event) => boolean`, which replaces `canPan`; the old name stays as an alias until the last + caller moves. + - `twoPointerPan?: boolean`: the pinch also translates by the midpoint's movement. +- `useCanvasGestures.ts`, `Loupe.tsx` (technique from Task 0), `HandleLayer.tsx` (R-13 sizes), + `useGestureMessage.ts` (R-1). + +**Interfaces:** Consumes `dragAction(...).futile` and `mayHintTwoFingers`. The editor passes `onePointerPan: (e) => +pointerKindOf(e.pointerType) !== 'touch'` and `twoPointerPan: true`. + +- [ ] **Step 1: failing tests.** + - Unit `useFraming`: the defaults are unchanged (catalogue tests green). With `twoPointerPan`, two pointers moving + together translate without scaling. + - Unit hint: a futile drag shows R-1 once. A second within 60 s shows nothing. After a two-finger pan, it never + shows again. + - E2E touch (`hasTouch`, 1 024, 1 180 and 1 280 px, CDP `Input.dispatchTouchEvent`): + - One finger drags a vertex and a point, with the loupe visible during the drag. + - One finger off the handles moves nothing and shows the hint once. + - Two fingers zoom and pan. + - Finger 1 on a vertex then finger 2 elsewhere: the drag is cancelled, the shape restored, nothing committed, and + the pinch zooms (Review Focus 1). + - The explicit move mode by a finger. + - A tap on the selected zone opens the dialog; a tap with a chosen vertex unchooses it. + - Page scroll over the canvas without a selection keeps working (UX_TESTS). + - Every handle hit circle is ≥ 44 px (measured on boxes). + - `expectNoShift` at the hint's show and hide. +- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** gates. **Step 5:** commit `feat(editor): touch gestures, + two-finger pan, hint and loupe`. + +### Task 10: Documents realigned + +**Files:** + +- `docs/development/V1-2-6_UX_TESTS.md` §U2, rewritten to this plan: the dialog, A11, A12, the three adjustments, + « Défaire » in place of the toast's « Annuler », 6 s. +- `docs/development/V1-2-6_UX_PLAN.md` §U2: the file list, a 6 s message in place of « stays until closed », and + the status. +- `docs/ANNOTATION-RENDERING.md`: already updated in Tasks 4, 5 and 8; read again whole. +- `docs/development/RUST.md`: the size figures and the Part II exception row. +- `docs/development/RUST_ARCHITECTURE_REVIEW.md` Part II: the row. +- `docs/design/README.md`: the U2 status. +- `CLAUDE.md`: folder lines for the new components. + +- [ ] **Step 1:** write. **Step 2:** grep for the removed names (`GeometryGroup`, `TracingBar`, `CreationPanel`, + `required.fields`, `toast`) in `docs/`, `CLAUDE.md` and `.claude/rules/`, and fix every citer. **Step 3:** commit + `docs(docs): U2 tests, plan, rendering and Rust review aligned`. + +### Task 11: Gates and the owner checkpoint + +- [ ] **Step 1:** `pnpm check:all` (rust:check, types drift, wasm:build, check, app image, worker:test, + worker:image). Record the exact output lines. +- [ ] **Step 2:** sandbox `pnpm db:sandbox up fresh`, `test-db`, `e2e-shell` (the whole shell suite), then `test`. + Record the counts. +- [ ] **Step 3:** performance: commit latency under 500 ms for a vertex drag, an insert and a removal + (`editor-equine.spec.ts` budget, through its sandbox alias). +- [ ] **Step 4:** fresh `verifier` against the U2 implementation contract (written at the start of execution from + this plan, with the owner's approval brief verbatim), and fresh `security-auditor` on the U2 diff. Both run once. +- [ ] **Step 5:** owner demo script in `docs/development/V1-2-6_OWNER_TRIAL.md` U2, on the sandbox demo sheet. + - Mouse: move a point, change its size, drag a vertex of « Thoraciques », add and remove a vertex, move the zone, + redraw it and cancel, open and edit the properties, undo each step. + - The same on a tablet in landscape, with the two-finger hint and the loupe. + - Watch for no jump when a message appears. +- [ ] **Step 6:** STOP for the owner's checkpoint (mouse and tablet). Capitalize per the project's closing flow. + +## Out of scope, tracked + +- Curves (curve handles, path editing): the curves lot (T16). A path only gets « Remplacer par un polygone ». +- The « Constats » part of the annotation dialog: U2b (F1 to F22), where the dialog receives it. +- The category colour picker: U3 and U6 (A9 keeps the hex field). +- Phone editing: O14 A, read-only below 1 024 px. +- Firefox and WebKit runs: a follow-up as in R2; Chromium only until V1-5. +- BLK-015, RR-13 and anomalies A and B: separate tracks. + +## Task 0 results + +Empty until Task 0 runs. + +## Challenge round + +Empty until the three fresh challenges have run on rev 1.