Files
faunosteo/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md

1700 lines
106 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# U2 Direct Manipulation of Annotations Implementation Plan (V1-2.6), rev 3
> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development to implement this plan task-by-task.
> Steps use checkbox (`- [ ]`) syntax for tracking.
**Status:** VALIDATED by the owner, 2026-11-17 (brief « Je valide le plan technique U2 en révision 2 »). D1 validated.
D2 validated with a precision: a discreet hint tells the user to zoom to add a vertex (R-18). R-12 is corrected: a
move mode or a redraw with work started asks before Back or a tab drops it. A13, A14 and the board 33 adjustment
are validated as integrated. Implementation authorised. The owner tries the result on `pnpm db:trial` before U2
closes. DEV unchanged, no merge. Rev 3 = rev 2 + the owner's answers. Contract:
`.claude/tasks/contracts/2026-11-17-v1-2-6-u2-implementation.md`.
Rev 2 is rev 1 plus three fresh challenges of 2026-11-17: correctness FATAL(9), robustness FATAL(9), simplicity
CONCERNS(5). What became of each finding is recorded in « Challenge round », at the end.
**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:** page work around four pieces.
1. **The press machine.** One pure press machine (`press.ts`) decides every press on the drawing: click or drag,
which handle, which annotation, and what a second pointer cancels. It replaces the three deciders the editor runs
today (`clickHandler`, `useEmptyTap`, `swallowClick`, and `useMoveGesture`'s threshold).
2. **The work store.** A small work store holds what is uncommitted: the creation in progress with its form, the
move-mode or slider preview, and the chosen vertex. Each preview is stamped with the document text it was computed
on, so the leave guards, the undo paths and the tabs can see it, and a stale preview never commits.
3. **The dialogs.** `Dialog` gains an `anchor` prop that places it over the right column with a light veil. An
`annotation` history layer carries the properties dialog and the creation dialog. Both are mounted outside the
editable subtree with a `readOnly` prop, as the finding dialog is.
4. **The strip and the message line.** A fixed-height strip above the drawing and a fixed-height message line under
it replace `ToolNotes`, `SelectionTag` and `TracingBar`.
The core judges every end state on commit, through `geometryAccept`. One additive core value gives the smallest
radius a point may have in each view.
**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:**
- The boards `docs/design/v1-2-6-u2/` 02 to 06, 13, 31, 32 and 33, with `REVUE.md` and `ARBITRAGES.md`: A1 to A15,
and the « Validation du propriétaire » section with its three adjustments (BDR-122).
- `docs/development/V1-2-6_UX_PLAN.md` §U2, with « Orientation 2026-11-14 » and the validation note, plus §1.3,
§1.9, §1.10 and §2 G.
- `V1-2-6_UX_TESTS.md` §U2, realigned in Task 9.
- `V1-2-6_UX_DECISIONS.md`: T15, T16, T18.
- 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; checked by the three challenges)
### Gestures
- The click is `clickHandler` (`useCanvasGestures.ts:57-97`) behind `framing.swallowClick`, which uses a 4 px
cumulative path (`useFraming.ts:20,126-127,171-175`).
- An empty tap is `useEmptyTap`: 4 px cumulative (`catalogue/useEmptyTap.ts:5,90-97`), shared with
`CatalogueCanvas.tsx:73`.
- The block drag is `useMoveGesture`: 4 px displacement (`gesture.ts:5`). Its preview stays inside the canvas
(`useMoveGesture.ts:43-58`).
- `useFraming` is shared with `CatalogueCanvas.tsx:69` (no options). It decides the one-pointer pan at pointerdown
(`:113`). With two pointers it only zooms around the midpoint (`:128-137`), so there is NO two-finger pan. It pans
on arrows for every bubbled keydown (`:150-168`; the box receives the keys of its descendants,
`useCanvasGestures.ts:130-133`).
- The selection comes from the top element only: `annotationIdOf(event.target)` (`useCanvasGestures.ts:90`).
- Point hitboxes are painted under zones, and the visible element wins (`docs/ANNOTATION-RENDERING.md:30-38`).
- The trace closes within `CLOSE_SHARE 0.015 × span` (`usePlacement.ts:14,33-37`), about 8 px at 1 280 px.
### Overlay and layout
- `AnnotationOverlay.tsx` is `aria-hidden` and `pointer-events-none` (`:121`). Its vertices are decorative, span/200
units.
- These change height above the drawing: the tool line, the hint, `UnmeasuredHint` and `SelectionTag`
(`EditableAnnotations.tsx` `ToolNotes`). `TracingBar` sits under it (LRN-131). The header save line wraps
(`DraftHeader.tsx:68`) and changes text on the first commit.
- `styles/index.css:6` sets `html:has(dialog:modal) { overflow: hidden; }`: with classic scrollbars, an open dialog
removes the page scrollbar.
- Playwright headless Chromium hides scrollbars (`--hide-scrollbars`), so a box-only test cannot see that shift.
### Read-only and mounting
- `EditableAnnotations` lives under `EditOnly` → `KeptPlace` `hidden` (`tabs/AnnotationsTab.tsx:73-80`,
`KeptPlace.tsx:20`). A native modal must not live there (`editor/editingContext.ts:19-23`).
- The finding dialog is mounted outside `EditOnly` with `readOnly` (`FindingsTab.tsx:352-359`).
- Read-only comes from a crossing below 1 024 px, a refusal (frozen, rights) or a refresh (`editor/mode.ts:74-91`).
### Properties and creation
- `PropertiesPanel.tsx` is shared with the read-only twin (`AnnotationsTab.tsx:201-228`). `SelectionTag` is also
used by the twin (`:186-191`).
- `AnnotationFields.tsx` commits per field. `GeometryGroup.tsx` is imported by `PropertiesPanel.tsx:31`,
`CreationPanel.tsx:22` and `views/RepairDialog.tsx:5,203` (the « temporary form » of an attach refused for
annotations out of the new frame, owner decision 7; UX plan U5 lists it). It is the only repair path for an
out-of-frame point (`e2e/shell/editor-geometry.spec.ts:273-281`), because `geometryAccept` refuses a changed
annotation that is still invalid (`issues.ts` 158-170).
- `CreationFields.tsx:60-115` is a set of controlled inputs over a `CreationForm`.
- `creation.ts` `formProblem` and `creationAttempt.ts:49` produce the general line `fr.ts:1665`.
- `defaultRadius` (about 74 units on the main view) feeds `proposePoint`, `correctedCircle`, `centreCircle`
(`frame.ts:86-146`), `pendingForClick` and the keyboard path (`creation.ts:90,178`), and the test in
`correction.ts:34`.
### Navigation, leave, undo
- `LAYERS` is at `useEditorNavigation.ts:61-62`.
- `useTabSelect` (`:554-567`) and `openSection` (`:298-334`) ask no guard. `useAskLeaving` and `topDirtyLayer` walk
`LAYERS` only.
- `leaveGuardArmed` = unsaved or recovery (`editorBase.ts:62-64`). It is read by the route (`AdminSheetDraftRoute.tsx:93`)
and by `SignOutButton.tsx:20`.
- `ConfirmDialog.tsx` exists (title, body, two answers).
- Ctrl+Z is route-level (`useUndoShortcuts.ts:15-24`) and ignored only while a `dialog[open]` exists.
- `recordCommit` clears redo (`undo.ts:52-54`). Reload and recovery replace the text (`editorLoad.ts:136-153`,
`recoveryFlow.ts:167-186`).
- History cap: 8 MiB. The equine draft is 174 974 bytes as compact JSON, so the cap holds about 47 snapshots (UX
plan §2 G said about 20).
### Core
- `MIN_VISIBLE_PX = 4` (`frame.rs:67`). The scale is `preview_scale(main)` (`:104-112`); the twin is
`max(2, r − 12)` (`layer.rs:260`).
- The smallest radius is `12 + 2/scale` when `scale < 1`, else there is none. It depends on the view only, about
26.50 on the main view and 15.98 on the head (challenge, computed).
- `PreviewState` is ts-rs mirrored and not in the N-1 list.
- Wasm gate: 600 000 B gzip-9 by Node. The last figure is 580 522 B (`RUST.md:4523`).
### Equine data
- 28 annotations: 22 circles and 6 polygons, at most 17 vertices.
- Radii: 30 and 34 on the main view, 27 on the head view.
- Main view: 0.25 px per unit at 1 280 px, so the « Thoraciques » segments are 11 to 15 px.
- Hitboxes overlap (elbow and carpus 59 units apart with r 34 + 34). Junction points sit on the vertebral zones
(c7-t1 on « Thoraciques »).
## Migration inventory
| Today | U2 | Task |
|---|---|---|
| `clickHandler`, `useEmptyTap`, `swallowClick`, `useMoveGesture` threshold | `press.ts` machine, the editor's only decider; the catalogue keeps `useEmptyTap` and `useFraming` defaults | 2 |
| `ToolNotes`, `SelectionTag` (edit body), `TracingBar` | Fixed strip; `SelectionTag` stays for the read-only twin | 3 |
| Block drag of the selection | The press machine: point handle at any pointer, zone interior by mouse or pen | 2, 4, 5 |
| `GeometryGroup` in the properties panel and the creation panel | Removed from both (A8). The repair of an out-of-frame shape = move mode or redraw | 4, 5, 7 |
| `GeometryGroup` in `RepairDialog` (owner decision 7) | **D1** | none (D1) |
| `TraceReplacement` (path → polygon) | Strip command « Remplacer par un polygone » (T16, BDR-101) | 5 |
| `GeometryIssues` | Strip middle (first issue, `+n`) and an alert block in the dialog's read mode | 3, 6 |
| `AnnotationFields` per-field commits | Deleted. The edit form renders `CreationFields` (+ « Couleur ») on a `CreationForm` draft, one save | 6 |
| `StatusActions`, `Deletion` | Dialog read mode: direct review action (A10), « Supprimer » via `DeleteDialog` | 6 |
| `PropertiesPanel` (read-only twin) | Deleted. The twin renders `AnnotationReadBody` directly | 6 |
| `CreationPanel` (form, C26, « Créer », « Annuler ») | Creation dialog: first line, the C26 notice, `CreationFields`; « Créer », « Abandonner » | 7 |
| `KeyboardAdd` (centre + typed coordinates) | Same buttons: the shape at the centre at the A5 size, the dialog opens; then handles and move mode | 7 |
| Link tool (`detail_trigger`, `opens`) | Same dialogs with « Vue ouverte » | 6, 7 |
| « Aller à » an annotation (`data-properties-heading`) | Selects it on its view and focuses its row (R-5) | 6 |
| Busy « Aller à » targets (`data-creation-heading`, `tracing-bar`) | The creation dialog's heading, the strip's tracing commands | 3, 7 |
## Owner decisions
| # | Question | Recommendation | Alternative | Cost if wrong |
|---|---|---|---|---|
| D1 (VALIDATED) | `RepairDialog` (after attaching a drawing that leaves annotations out of the new frame, owner decision 7) still shows coordinate fields. A8 says « retirés partout ». | Keep them in that dialog only, until U5 rewrites it with `remap_view` (UX plan U5 already lists `RepairDialog.tsx`). It is a rare repair outside the annotation journey; its values are proposals in a frame not attached yet, so no drawing exists to drag on. `GeometryGroup.tsx` stays as the repair's own component. | Replace it in U2: list the out-of-frame annotations, attach the drawing first, then correct each one on the drawing with the move mode. That changes owner decision 7 (nothing is attached until it is valid), needs a new board, and adds a task. | Recommendation: coordinates remain in one rare dialog until U5. Alternative: a redesign of decision 7 inside U2. |
### D2: « + » on segments too short for the finger (VALIDATED, with R-18)
On the equine main view at fit zoom, the zone segments are 5 to 38 px long at 1 280 px and 6 to 49 px at 1 180 px.
Board 13 asks for 44 px touch targets, and board 05 draws a « + » on every segment.
Visible « + » per zone with R-9's rule (mouse needs a segment ≥ 20 px, finger ≥ 44 px), measured from
`document.json`:
| Zone | Mouse at 1 280 px | Mouse at 1 180 px | Finger at 1 180 px |
|---|---|---|---|
| cervical | 7/17 | 12/17 | 0/17 |
| thoracic | 5/9 | 5/9 | 0/9 |
| lumbar | 5/7 | 5/7 | 1/7 |
| sacral | 4/8 | 5/8 | 0/8 |
| caudal | 1/7 | 2/7 | 0/7 |
- **Recommendation (R-9 as written):** a « + » shows only when its segment is long enough on screen; otherwise
zoom in (two fingers, or « + » in the tool column) and it appears. A tap never inserts a vertex by accident, and
each target keeps 44 px. The owner demo says « zoomer d'abord » on a tablet.
- **Alternative:** every « + » always shown, as board 05 draws it, with its hit area shrunk to fit between its two
vertices (under 44 px when crowded, the spacing exception of WCAG 2.5.8). A mis-tap inserts a vertex; « Défaire »
removes it.
- **Cost if wrong:** the recommendation means one more gesture (zoom) before adding a vertex on a tablet. The
alternative means a wrong insert now and then, undone in one tap.
Conditional, Task 8: if neither loupe technique keeps the drag smooth on the editor itself, the owner chooses
between a loupe without the drawing (outline and handles only) and no loupe. No question before then.
## 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 ».
- Where: in the message line, neutral tone, no action, 4 s.
- Trigger: a one-finger drag on the drawing, past the touch slop, that moved nothing (`dragAction` `none` with
`futile`), shown only when the line is free.
- Once a two-finger pan or zoom has worked in this editor visit, it never shows again. No timer, no queue.
### R-2 Message line (adjustment A14)
- Layout: one fixed-height line under the drawing, single line, truncated with an ellipsis. The add buttons sit on
the left, the message on the right.
- No movement: showing or hiding a message changes no box. The canvas, the strip, the column and the header keep
their position and size, and the page keeps its scroll height.
- Scrollbar: `html:has([data-editor-workspace]) { scrollbar-gutter: stable; }`, scoped to the editor, so an open
dialog removes no scrollbar width there.
- Timing: 6 s (A14). It pauses while hovered with a mouse only; a touch never pauses it. Any commit, undo or redo
closes it.
- Undo: its « Défaire » calls the same `undo()` as the header (T15). It is hidden while a creation runs (A12).
- Announcements: 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, `role="alert"`, names only the missing fields with their labels in form order: FR « À compléter :
Latéralité. », EN « To complete: Laterality. » The focus goes to the first missing field.
- The general line `editor.annotations.required.fields` is removed. The creation dialog and the edit form share
`missingFields` and these keys.
### 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, or the drawing when a filter hides the row.
- No dialog opens (A1).
- A creation in progress keeps the request, as today.
### R-6 Veil
A click on the veil of an annotation dialog (properties or creation) does nothing. The dialog closes by ✕, Échap,
« Annuler » or « Abandonner », or Back (board 31 D). A tap that opens the dialog cannot close it with its own click,
and a stray tap never discards a creation.
### R-7 Handle cap (T18)
- `HANDLE_CAP = 40` vertices; the equine maximum is 17.
- 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 and double click
- 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.
- A second pointer during a press cancels it: no click, no commit.
- Two clicks within 400 ms and 8 px open the properties dialog of the annotation they hit. They never run a handle
action and never insert.
### R-9 Handles
- Device size, read once from `(any-pointer: coarse)`:
- Coarse: board 13 sizes. Vertex 18 px, « + » 24 px, « − » bubble 44 × 36 px, hit radius 22 px.
- Otherwise: board 05 sizes. Vertex 12 px, « + » 16 px, hit radius 10 px.
- Sizes are constant in CSS px under zoom.
- The handle nearest the press wins; at equal distance a vertex beats « − », which beats « + ».
- A « + » is hidden while its segment is shorter than two hit radii at the current zoom. Insert on the keyboard and
zooming still reach it.
### 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).
- This size feeds every new point: a click, the C26 candidate and its test, and the keyboard.
- The slider runs from half the smaller of (smallest stop, minimum) to twice the largest stop, or around the fallback
when there is no stop.
- 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 there is none.
### R-11 Move step and trace closing
- One arrow moves by 0.5 % of the frame's longer side, at least 0.01. Shift multiplies it by 10 (keys only).
- A trace closes on its first vertex within 12 CSS px for a mouse and 22 px for a finger or a pen.
### R-12 Confirmation during a creation (A12)
- During a creation that holds a shape or typed text, a confirmation (`ConfirmDialog`) is asked before: a tab, a
section, a view chip, a tool, Back, Escape, sign-out and leaving the editor.
- FR « Abandonner la création ? », « Continuer », « Abandonner »; EN « Discard the creation? », « Continue »,
« Discard ». Inside the creation dialog, the R2 `DiscardConfirm` takes this place.
- A move mode or a redraw (owner correction, 2026-11-17):
- With no work started, Back, a tab, a section, a view chip, a tool, sign-out or leaving the editor ends it at
once, without a question. The stored shape stays.
- Work is started once the move mode's position differs from the stored one, or the redraw has at least one
vertex. The same actions then ask first through `ConfirmDialog`: FR « Abandonner le déplacement ? » or
« Abandonner le nouveau tracé ? », with « Continuer » and « Abandonner »; EN « Discard the move? » or « Discard
the new tracing? », « Continue », « Discard ».
- « Annuler », « Annuler le tracé » and Escape are explicit cancels and act at once, as board 32 (row 4) draws.
- During a move mode, a click on another annotation or on the empty drawing selects nothing. The mode ends only
through « Valider la position », « Annuler », Escape or an action asked as above.
- Neither is a history entry (orientation): the question is the guard's, not a layer's.
- A keyboard series on a handle and the size slider commit on blur (BDR-050), as text fields do today (§1.9). A
click on a tab or on « Défaire » therefore commits the series first.
### R-13 Undo with something pending
- An undo (header, shortcut, message) while a move mode, a slider or a keyboard series is pending only cancels that
preview. The next undo undoes.
- During a creation, undo is inactive (A12).
- A document change made elsewhere (reload, recovery, a save refresh) drops every stale preview and the chosen
vertex. When the dropped work was a started move mode or redraw, the live region and the message line say so:
FR « Déplacement abandonné : la fiche a changé. » or « Nouveau tracé abandonné : la fiche a changé. », EN « Move
discarded: the sheet changed. » or « New tracing discarded: the sheet changed. » Nothing is dropped without being
said.
### R-14 Read-only flip
The editor turns read-only on a crossing below 1 024 px, a refusal or a refresh. Then:
- An open properties or creation dialog stays open in read-only form: a notice, inputs disabled, the draft kept, the
save disabled.
- A move mode or a redraw in progress is suspended, not dropped. It is kept (the body stays mounted, and the
preview stays in the work store) and resumes on the way back, unless the document changed meanwhile (R-13).
- Nothing commits while read-only, and the draft comes back editable on the way back.
- The anchor falls back to the visible column, or to the centre.
### R-15 Undo depth
The cap stays at 8 MiB: about 47 equine steps, written in UX_TESTS in place of « about 20 ».
### R-16 Read-only sheet at 1 024 px and wider (boards 31 F and 33 E)
- The read-only body (`ReadOnlyAnnotations`) gets the same strip, in its read-only form: « Point · fiche en lecture
seule », with « Propriétés » and « Désélectionner ».
- Its aside keeps the overview.
- The properties open in the same dialog, read-only, with values only and no action. The opening rules are A1's: a
second click, a double click, « Propriétés », Enter on the selected row.
- Below 1 024 px (phone, boards 14 and 16) the twin is unchanged: the read body sits inline in the stacked column.
### R-18 Zoom hint for short segments (D2 precision)
- When a zone is selected with its handles shown, and at least one of its « + » is hidden because its segment is too
short at the current zoom, the strip's middle shows a discreet line, info tone: FR « Zoomez pour ajouter un sommet
sur les segments courts. », EN « Zoom in to add a vertex on short segments. »
- It is not timed. It stays while the condition holds and goes when zooming reveals every « + ».
- It yields to a refusal or a geometry issue, which take the same place first. It is absent in a move mode, a
redraw and read-only.
- It changes no box: the strip's height is fixed.
- The keyboard path (Insert on the chosen vertex) stays available whatever the zoom.
### R-17 Rust by default (BDR-043)
These new modules stay in TypeScript. Each is listed in the review's Part II exception table:
- `press.ts` and `escape.ts`: pointer and keyboard event handling, which is DOM and UI (CLAUDE.md « kept as is »).
- `missingFields.ts`: a UI form rule over i18n keys (« kept as is »).
- `polygonEdit.ts` and `pointSize.ts`: interaction-rate preview arithmetic. UX plan §1.3 and §2 G, ratified at U0,
place it in the page. Each result goes through `sheet.edit` and the core's verdict, and no core rule is copied:
the minimum radius comes from the core (Task 1).
## Global Constraints
### Where and how
- 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 …`.
- `editor-equine.spec.ts` runs only through its sandbox alias.
### Core and Rust
- The core judges every geometry. The page proposes and commits through `geometryAccept` (`insertAnnotation`,
`updateGeometry`).
- A refusal restores the previous shape exactly.
- The minimum radius comes from Task 1; no TypeScript copy of a core rule.
- Rust by default: R-17.
### Undo and previews
- 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.
- Every preview, keyboard series and chosen vertex carries the `documentText` it was computed on (R-13). A commit
with a stale stamp is refused, and one store subscription drops stale work.
### Mounting and layout
- The dialogs are mounted outside `EditOnly` with `readOnly` (R-14).
- No silent loss: uncommitted work (a creation, a started move mode, a started redraw, a dialog draft) is asked
before any navigation drops it, or announced when a document change made elsewhere drops it (R-12, R-13).
- No layout shift: every state change of the tab keeps the canvas box, the strip, the aside and the header box
unchanged. This covers selection, strip content, message, dialog open and close, mode entry and exit, and the
first commit's save line. Task 3's helper asserts it, and every later task uses it.
### Code rules
- 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. « Abandonner » is reserved for leaving a form (T15).
- Rendering changes update `docs/ANNOTATION-RENDERING.md` « Editor overlay » FIRST.
- 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): read-only (O14 A), boards 14 and 16 unchanged.
## Review Focus
1. **A finger on a vertex, then a second finger.** The drag is cancelled, the shape restored, nothing committed, and
the pinch zooms. A pinch whose anchor finger barely moves never ends as a click. Tests: Task 2 table, Task 8 CDP
two-point touch.
2. **Ctrl+Z with focus on a handle after arrow moves, or on a move-mode arrow.** The undo only cancels the preview,
and a later Enter commits nothing stale. After undoing « + », « − » never removes the wrong vertex. Tests: Task 4
and Task 5 units.
3. **A typed properties or creation form when the width crosses 1 024 px, the device rotates, or a save is refused
as frozen.** The dialog stays, read-only, the draft is kept, nothing is committed; editable again on the way
back. Tests: Task 6 and Task 7 (width flip and mode flip).
4. **A message appears or expires while the user is about to tap a handle.** Nothing moves (boxes, header, scroll
height). Test: Task 3 helper at 1 024, 1 180 and 1 280 px.
5. **A tap or a double click that opens the dialog on the selected shape.** The dialog stays open; no vertex is
inserted; the veil ignores the synthesised click. Tests: Task 2 table, Task 6 e2e mouse and touch.
## File Structure
New:
- `apps/app/src/editor/annotations/press.ts`: slop per kind, hit choice, click and drag actions, double click, the
press machine.
- `apps/app/src/editor/annotations/polygonEdit.ts`: midpoint, removal, vertex move, no-op move, cap,
insert-visibility.
- `apps/app/src/editor/annotations/pointSize.ts`: stops, most used, snap, range.
- `apps/app/src/editor/annotations/escape.ts`: Escape action.
- `apps/app/src/editor/annotations/missingFields.ts`: replaces `formProblem`.
- `apps/app/src/editor/annotations/workStore.ts`: zustand: `creation`, `preview`, `chosen`, `stale()`.
- `apps/app/src/components/editor/annotations/EditStrip.tsx`, `GestureMessage.tsx`, `SizeSlider.tsx`,
`MoveModeBar.tsx`, `HandleLayer.tsx` (its own SVG, not aria-hidden), `Loupe.tsx`, `AnnotationDialog.tsx`,
`AnnotationReadBody.tsx`, `AnnotationEditForm.tsx`, `CreationDialog.tsx`.
- `apps/app/e2e/support/layout.ts` (`expectNoShift`).
Modified:
- Canvas and gestures: `AnnotationCanvas.tsx`, `AnnotationOverlay.tsx`, `EditableAnnotations.tsx`, `uiState.ts`,
`usePlacement.ts`, `useCanvasGestures.ts`, `gesture.ts`.
- Geometry and creation: `frame.ts` (radius passed in; `moveStep`), `creation.ts`, `creationAttempt.ts`,
`correction.ts`, `focusTarget.ts`, `CreationFields.tsx` (« Couleur » behind a prop, field order region then zone).
- Shared with the catalogue, opt-in only: `catalogue/useFraming.ts` (`twoPointerPan`; keys only on the box itself;
defaults unchanged).
- Dialogs: `components/ui/Dialog.tsx` (`anchor`), `ConfirmDialog.tsx` (`body` optional).
- Navigation and history: `navigation.ts`, `useEditorNavigation.ts` (layer, `useTabSelect`, `openSection`,
`useAskLeaving`), `history/{entry,useEditorHistory,useLeaveConfirm}.ts`, `leftDraft.ts`, `tabs.ts`,
`EditorWorkspace.tsx`, `tabs/AnnotationsTab.tsx` (dialog mounts, twin).
- Leave and undo: `AdminSheetDraftRoute.tsx` and `SignOutButton.tsx` (`leaveGuardArmed` or creation work),
`HistoryButtons.tsx` and `useUndoShortcuts.ts` (R-13).
- Page-wide: `styles/index.css` (R-2), `DraftHeader.tsx` (the save line holds its height, if Task 3 finds it
shifts), `i18n/{fr,en}.ts`.
Removed: `TracingBar.tsx`, `CreationPanel.tsx`, `PropertiesPanel.tsx`, `AnnotationFields.tsx`, `useMoveGesture.ts`,
the `ToolNotes` and `TagOf` parts of `EditableAnnotations`, and the field helpers of `geometryEdit.ts` used by
annotations only. `GeometryGroup.tsx` stays for `RepairDialog` (D1).
Core: `crates/core/src/anatomy/frame.rs`, `crates/core/src/domain/sheet/preview.rs`,
`crates/core/tests/sheet_preview.rs`, `packages/core-wasm/types/PreviewState.ts` (generated),
`packages/core-wasm/tests/contracts.types.test.ts`.
### Task 1: Core: the smallest radius a point may have in each view
**Files:** `frame.rs` (beside `annotation_placement`, l.208-227), `preview.rs` (`PreviewState` l.359-370, `state()`
l.272-292), `crates/core/tests/sheet_preview.rs`, the generated `PreviewState.ts`, `contracts.types.test.ts`,
`docs/development/RUST.md`.
**Interfaces:**
```rust
/// The smallest hitbox radius of a point (a circle that is not a trigger) that passes
/// `TooSmall` in a view with this frame, rounded up to 0.01; 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<f64>
```
`twin_radius(r) = max(2, r − 12)` must reach `MIN_VISIBLE_PX / 2 / scale`, with `scale = frame.preview_scale(main)`.
So the result is `Some(ceil_0.01(12 + MIN_VISIBLE_PX / 2 / scale))` when `MIN_VISIBLE_PX / 2 / scale > 2`, else
`None`. `PreviewState.min_point_radius: BTreeMap<String, f64>` maps a view id to its radius, for views with a usable
frame and a minimum. The app reads `previewState.min_point_radius[viewId] ?? null` inline.
- [ ] **Step 1: baseline.** `pnpm wasm:build`, then the gate's size test (`packages/core-wasm/tests/size.test.ts`);
record the printed figure.
- [ ] **Step 2: failing Rust tests** in `sheet_preview.rs`:
- The equine main and head views give the formula's value on their frames: about 26.50 and 15.98, asserted from
the frame read from the fixture.
- Width 100, an exact scale of 1 and an unusable frame give no entry.
- Property: for each entry, a circle with `r = value` passes `annotation_placement`, and `r = value − 0.01` gives
`TooSmall`.
- [ ] **Step 3:** `cargo test -p faunosteo-core --test sheet_preview` gives FAIL. Implement, then regenerate the types
(`cargo test` with features `ts`).
- [ ] **Step 4:** `pnpm rust:check`, `pnpm wasm:build`, and the size test. Record the figure and its delta in
`RUST.md`. `contracts.types.test.ts` asserts the field, and an app unit test checks the bundled draft's main-view
value.
- [ ] **Step 5:** commit `feat(domain): per-view minimum point radius in preview state`.
### Task 2: The press machine (one decider for the editor) and the stale stamp
**Files:**
- Create `press.ts` and `workStore.ts`.
- Modify `useCanvasGestures.ts`: the editor stops using `clickHandler`, `useEmptyTap`, `swallowClick` and
`useMoveGesture`; `canPan` becomes `dragAction(...).type === 'pan'`; the framing keys are passed only when
`event.target === event.currentTarget`.
- Modify `gesture.ts`: `DRAG_START_PX` and `pastDragThreshold` go.
- Delete `useMoveGesture.ts`.
- Tests: `tests/unit/annotations.press.test.ts` and `annotations.workStore.test.ts`. The existing suites stay green:
select, deselect on an empty tap, block drag of the selection, catalogue unchanged.
**Interfaces (produced, exact):**
```ts
// press.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<Record<PointerKind, number>> = { mouse: 4, pen: 6, touch: 10 }
export const DOUBLE_MS = 400
export const DOUBLE_PX = 8
export function pointerKindOf(pointerType: string): PointerKind {
return pointerType === 'touch' || pointerType === 'pen' ? pointerType : 'mouse'
}
const distance = (a: XY, b: XY) => Math.hypot(a.x - b.x, a.y - b.y)
export function pastSlop(kind: PointerKind, from: XY, to: XY): boolean {
return distance(from, to) > SLOP_PX[kind]
}
export type HandleRef =
| { kind: 'point' }
| { kind: 'vertex'; index: number }
| { kind: 'remove'; index: number }
| { kind: 'insert'; after: number }
/** One element under the press, top first (`elementsFromPoint`); handle centres in CSS px. */
export type Hit =
| { kind: 'handle'; handle: HandleRef; centre: XY }
| { kind: 'annotation'; id: string }
const RANK: Record<HandleRef['kind'], number> = { point: 0, vertex: 0, remove: 1, insert: 2 }
/** R-9: the nearest handle; at equal distance a vertex, then « − », then « + ». */
export function nearestHandle(hits: readonly Hit[], at: XY): HandleRef | null {
let best: { handle: HandleRef; d: number } | null = null
for (const hit of hits) {
if (hit.kind !== 'handle') continue
const d = distance(hit.centre, at)
const better =
!best || d < best.d || (d === best.d && RANK[hit.handle.kind] < RANK[best.handle.kind])
if (better) best = { handle: hit.handle, d }
}
return best?.handle ?? null
}
export interface Selection {
selectedId: string | null
chosenVertex: number | null
}
export type PressTarget =
| { kind: 'handle'; handle: HandleRef }
| { kind: 'other'; id: string }
| { kind: 'interior'; id: string }
| { kind: 'empty' }
/** Board 32: the selection's handles, then the TOPMOST annotation (the visible wins), else nothing. */
export function pressTarget(hits: readonly Hit[], at: XY, sel: Selection): PressTarget {
const handle = nearestHandle(hits, at)
if (handle) return { kind: 'handle', handle }
const top = hits.find((hit) => hit.kind === 'annotation')
if (top?.kind !== 'annotation') return { kind: 'empty' }
return top.id === sel.selectedId ? { kind: 'interior', id: top.id } : { kind: 'other', id: top.id }
}
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' }
}
/** R-8: the second of two clicks close in time and place opens; it never acts on a handle. */
export interface LastClick { at: XY; time: number }
export function isDoubleClick(last: LastClick | null, at: XY, time: number): boolean {
return last !== null && time - last.time <= DOUBLE_MS && distance(last.at, at) <= DOUBLE_PX
}
export interface DragContext {
kind: PointerKind
/** The selection can move now (editable, measured, circle or polygon, under the cap). */
movable: boolean
/** « Déplacer … » is on: a drag anywhere moves its target (board 06 B). */
moveMode: boolean
}
export type DragAction =
| { type: 'drag_mode' }
| { 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, ctx: DragContext): DragAction {
if (ctx.moveMode) return { type: 'drag_mode' }
if (target.kind === 'handle') {
if (!ctx.movable) return { type: 'none', futile: false }
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 (ctx.kind === 'touch') return { type: 'none', futile: true }
if (target.kind === 'interior' && ctx.movable) return { type: 'drag_shape', id: target.id }
return { type: 'pan' }
}
/** The press in flight: one pointer, or a multi-pointer gesture that never clicks nor commits. */
export type Press =
| { phase: 'idle' }
| { phase: 'down'; pointerId: number; kind: PointerKind; start: XY; target: PressTarget }
| { phase: 'drag'; pointerId: number; action: DragAction }
| { phase: 'multi' }
/** `pointers`: how many pointers are down after the event. */
export type PressEvent =
| { type: 'down'; pointerId: number; kind: PointerKind; at: XY; target: PressTarget; pointers: number }
| { type: 'move'; pointerId: number; at: XY }
| { type: 'up'; pointerId: number; pointers: number }
| { type: 'cancel' }
export type PressEffect =
| { type: 'click'; target: PressTarget }
| { type: 'drag_start'; action: DragAction }
| { type: 'drag_end' }
| { type: 'drag_cancel' }
| null
const IDLE: Press = { phase: 'idle' }
export function stepPress(
press: Press,
event: PressEvent,
ctx: Omit<DragContext, 'kind'>,
): { press: Press; effect: PressEffect } {
if (event.type === 'cancel') {
return { press: IDLE, effect: press.phase === 'drag' ? { type: 'drag_cancel' } : null }
}
if (event.type === 'down') {
if (press.phase === 'idle' && event.pointers === 1) {
const { pointerId, kind, at, target } = event
return { press: { phase: 'down', pointerId, kind, start: at, target }, effect: null }
}
return { press: { phase: 'multi' }, effect: press.phase === 'drag' ? { type: 'drag_cancel' } : null }
}
if (event.type === 'move') {
if (press.phase !== 'down' || event.pointerId !== press.pointerId) return { press, effect: null }
if (!pastSlop(press.kind, press.start, event.at)) return { press, effect: null }
const action = dragAction(press.target, { ...ctx, kind: press.kind })
return { press: { phase: 'drag', pointerId: press.pointerId, action }, effect: { type: 'drag_start', action } }
}
if (press.phase === 'multi') return { press: event.pointers === 0 ? IDLE : press, effect: null }
if (press.phase === 'down') return { press: IDLE, effect: { type: 'click', target: press.target } }
if (press.phase === 'drag') return { press: IDLE, effect: { type: 'drag_end' } }
return { press, effect: null }
}
```
```ts
// workStore.ts
import { create } from 'zustand'
import type { Geometry } from '@faunosteo/core-wasm/types'
import type { CreationForm, PendingElement } from './creation'
/** A geometry shown but not committed, stamped with the document text it was computed on. */
export interface Preview { annotationId: string; geometry: Geometry; base: string; source: 'move' | 'size' | 'keys' }
export interface Chosen { annotationId: string; vertex: number; base: string }
export interface Creation {
/** A new zone or link being traced lives here from its first vertex (`closed` false). */
pending: PendingElement
closed: boolean
form: CreationForm
/** The dialog is shown; false while the shape is replaced or the trace resumed. */
dialog: boolean
}
/** A move mode or a redraw; `started` once the position differs or a vertex is placed (R-12). */
export interface ModeWork { kind: 'move' | 'redraw'; annotationId: string; started: boolean }
interface Work {
creation: Creation | null
mode: ModeWork | null
preview: Preview | null
chosen: Chosen | null
}
export const useAnnotationWork = create<Work>(() => ({
creation: null,
mode: null,
preview: null,
chosen: null,
}))
export type GuardWork = 'creation' | 'move' | 'redraw' | null
/** R-12: what a navigation must ask about; an unstarted mode asks nothing and simply ends. */
export function guardWork(work: Work): GuardWork {
if (work.creation !== null) return 'creation'
return work.mode?.started ? work.mode.kind : null
}
/** The end of a mode without a question (unstarted, or « Abandonner » answered). */
export function endMode(): void {
useAnnotationWork.setState({ mode: null, preview: null })
}
/** R-13: drop what was computed on another document text; the caller passes the current text. */
export function dropStale(text: string): void {
useAnnotationWork.setState((work) => ({
preview: work.preview && work.preview.base !== text ? null : work.preview,
chosen: work.chosen && work.chosen.base !== text ? null : work.chosen,
}))
}
```
Notes on the code above:
- A creation always holds its shape, so `guardWork` reports any creation. The tool alone, before
the first click or the first vertex, holds nothing and creates no `creation`.
- The tracing of a NEW zone or link moves from `ui.tracing` to `creation` (Task 7). A redraw keeps its vertices in `ui.tracing`
(target `replace`) and sets `mode: { kind: 'redraw', started }` beside it (R-12): it is not a creation.
- The drag preview of a pointer drag stays canvas-local, as `useMoveGesture` keeps it today, for speed. It is
dropped by `drag_cancel`, by a second pointer and by a document change.
- `workStore` is reset when the sheet changes and when the editor unmounts. `editorStore` calls `dropStale` from
one subscription on `documentText`.
- [ ] **Step 1: failing table tests.**
- `nearestHandle`: the nearest of three overlapping hit circles wins (Thoraciques 11 px segment); at a tie,
vertex beats « − », which beats « + ».
- `pressTarget`: a selected zone hit first and a point hitbox under it gives `interior`; a point twin hit first
and the selected zone under it gives `other`; empty gives `empty`.
- `clickAction`: as in rev 1 (interior with a chosen vertex gives `unchoose`, without one `open`; a point handle
gives `open`).
- `isDoubleClick`: the edges at 400 ms and 8 px.
- `dragAction`: a move mode gives `drag_mode` whatever the target or pointer. A finger off a handle gives `none`
with `futile`. A mouse on the interior while not movable (read-only, unmeasured, path) gives `pan`. « + » and
« − » never drag.
- `stepPress`:
- A single press within the slop gives `click`.
- Past the slop gives `drag_start`, then `drag_end`.
- A second down while `down` gives `multi`, with no click on any up, and `idle` only at zero pointers (a pinch
never clicks).
- A second down while `drag` gives `drag_cancel`.
- `cancel` while `drag` gives `drag_cancel`.
- A move from another pointer id is ignored.
- `dropStale`: drops on a different text and keeps on the same one.
- [ ] **Step 2:** `pnpm --filter @faunosteo/app exec vitest run tests/unit/annotations.press tests/unit/annotations.workStore`
gives FAIL.
- [ ] **Step 3:** implement, then wire `useCanvasGestures`.
- `hitsAt(client)` uses `document.elementsFromPoint`. It maps handles by `data-handle` (JSON of `HandleRef`) with
their centre from `getBoundingClientRect`, and annotations by `annotationIdOf`.
- Pointer events feed `stepPress`. A `click` effect dispatches `clickAction` (or `open` when `isDoubleClick`). A
`drag_shape` reuses the block translation (`translatedGeometry`) and commits once on `drag_end` through
`updateGeometry`. `deselect` keeps today's focus rule (`useDeselect.byDrawing`).
- The box no longer handles `onClick`.
- Until the handle layer exists (Task 4), `hitsAt` reports a hit on the SELECTED point's own element as the
`point` handle (same `HandleRef`, centre from its box). The finger drag of a selected point therefore works from
this task on.
- `open` is a no-op until Task 6. `choose_vertex`, `insert` and `remove` are no-ops until Task 5.
- [ ] **Step 4:** `pnpm typecheck && pnpm test:run && pnpm lint`, plus the e2e of today's gestures on the sandbox:
`editor-annotations.spec.ts` « a click with jitter never moves; a drag moves by the pointer delta »,
`editor-deselect.spec.ts` mouse and touch, `editor-geometry.spec.ts` « a touch drag moves the selected marker »,
and `catalogue.spec.ts`.
- All stay green unchanged, with one exception: a finger drag on the interior of a selected ZONE no longer moves
it (A13). The move mode replaces it in Task 4.
- Any test asserting that finger drag is rewritten in this task to assert nothing moves, and its replacement is
named in the commit body.
- [ ] **Step 5:** commit `refactor(editor): one press machine for clicks, drags and taps on the drawing`.
### Task 3: The fixed strip, the message line, no layout shift
**Files:**
- Create `EditStrip.tsx`, `GestureMessage.tsx` and `apps/app/e2e/support/layout.ts`.
- Modify `EditableAnnotations.tsx`: remove `ToolNotes`, `TagOf` and `TracingBar`, and mount the strip over both
columns.
- Modify `uiState.ts` (`trace_pop`), `usePlacement.ts` (Backspace removes the last vertex), `focusTarget.ts` (busy
tracing target = the strip's tracing commands), `styles/index.css` (R-2) and i18n.
- Modify `DraftHeader.tsx` only if the helper shows the save line moving.
- Delete `TracingBar.tsx`.
**Interfaces:**
- `EditStrip` props: `{ lead: StripLead; notice: StripNotice | null; commands: ReactNode }`.
- `StripLead = { title: string; status?: ReviewStatus; detail: string; icon: IconName }`.
- `StripNotice = { tone: 'error' | 'info'; text: string; more?: number; link?: { label: string; onClick(): void } }`.
- `useGestureMessage()` returns `{ message, show(text, { undo, tone }), hint(text) }`.
- It clears on any change of `documentText` or of the history stacks.
- The 6 s timer is paused only by `pointerenter` with `pointerType === 'mouse'` and by focus inside.
- `hint` shows only when no message is shown.
- `expectNoShift(page, act)`:
1. Records the boxes of the canvas, the strip, the aside and the header, `scrollHeight`, the computed
`scrollbar-gutter` and `document.documentElement.clientWidth`.
2. Installs a `PerformanceObserver({ type: 'layout-shift' })`.
3. Runs `act`, then waits two animation frames.
4. Asserts equal boxes and widths, and a zero sum of every entry, `hadRecentInput` included.
- [ ] **Step 1: failing unit tests** (`editor-annotations-tab.test.tsx`, `describe('the strip')`).
- The labels per state come from REVUE's table: tool Point, a selected point, a selected zone (« Zone · 9 sommets »),
tracing (« Fermer le tracé », « Retirer le dernier sommet », « Annuler le tracé »), read-only, an unmeasured view
with its link, and geometry issues with `+n`.
- The strip has a fixed height and `overflow-hidden`; a long name truncates before the status.
- « Retirer le dernier sommet » and Backspace remove the last vertex.
- The message:
- A commit shows « Point déplacé · Défaire »; « Défaire » calls `undo`.
- A new commit replaces the message, and an undo from the header clears it.
- A refusal shows `role="alert"` with no « Défaire ».
- Mouse hover pauses the timer, a touch does not (fake timers).
- [ ] **Step 2:** FAIL. **Step 3:** implement and move the existing texts into the strip notice.
- [ ] **Step 4: e2e** `editor-annotations.spec.ts`, « the drawing never moves ».
- At 1 024, 1 180 and 1 280 px, `expectNoShift` around select, deselect, tool change, tracing start, add, pop and
close, the first commit (save line), a message showing, and its expiry (`page.clock`).
- At 1 280 px, the scoped `scrollbar-gutter` is `stable` on the editor page and absent on the dashboard.
- Existing selectors move to the strip; `editor-focus-request` busy cases are re-pointed.
- [ ] **Step 5:** gates, then commit `feat(editor): fixed edit strip and message line without layout shift`.
### Task 4: Point editing: handle, size slider, move mode, the repair without fields
**Files:**
- Create `HandleLayer.tsx`: its own `<svg>`, same `viewBox`, not `aria-hidden`, beside the overlay.
- Create `SizeSlider.tsx`, `MoveModeBar.tsx`, `pointSize.ts` and `escape.ts`.
- Modify `frame.ts`:
- `proposePoint(frame, click, radius)`, `correctedCircle(frame, at, radius)`, `centreCircle(frame, radius)`.
- `moveStep(frame, big)`.
- Modify the callers `creation.ts` (`pendingForClick`, `keyboardPending`) and `correction.ts` (the test against
the given radius, R-10).
- The move mode lives in `workStore.mode` (target in the preview: the shape, or a vertex), so the guard sites outside
the tab can read and end it. Modify `useCanvasGestures.ts` (`drag_point`, `drag_mode`) and `deselect.ts` (the
Escape listener calls `escapeAction`).
- The properties panel keeps its numeric group until Task 5, where polygons get their handles.
- The drawing guard and its sites (R-12): `workStore.ts` (`guardWork()`: what is started), `useEditorNavigation.ts`
(`useTabSelect`, the arrow-key tab move, `openSection`, the view chips and tools through the tab), `history/useEditorHistory.ts`
(`refusal` asks it on every POP), `history/useLeaveConfirm.ts`, `AdminSheetDraftRoute.tsx` and `SignOutButton.tsx`
(`leaveGuardArmed(state) || guardWork(work) !== null`), `ConfirmDialog.tsx` (`body` optional).
- Doc `docs/ANNOTATION-RENDERING.md` « Editor overlay » FIRST.
**Interfaces:**
```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<number, number>()
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) {
const closer = nearest === null || Math.abs(stop - value) < Math.abs(nearest - value)
if (Math.abs(stop - value) <= reach && closer) nearest = stop
}
return nearest ?? round2(value)
}
export interface SizeRange { low: number; high: number }
/** R-10: around the stops when there are some, around the fallback radius otherwise. */
export function sizeRange(stops: readonly number[], minimum: number | null, fallback: number): SizeRange {
const smallest = stops.length > 0 ? stops[0] : fallback
const largest = stops.length > 0 ? stops[stops.length - 1] : fallback
const base = minimum === null ? smallest : Math.min(smallest, minimum)
return { low: round2(Math.max(0.01, base / 2)), high: round2(2 * largest) }
}
```
```ts
// escape.ts
export interface EscapeInput {
/** A keyboard series or a slider not yet committed (outside a move mode). */
previewPending: boolean
creating: boolean
/** A redraw or a move mode. */
inMode: boolean
chosenVertex: number | null
selectedId: string | null
}
export type EscapeAction =
| 'drop_preview' | 'ask_creation' | 'drop_mode' | 'unchoose' | 'deselect' | null
/** Board 32 rows 3 to 6, one situation per press (rows 1 and 2, a dialog and a side panel, consume it first). */
export function escapeAction(s: EscapeInput): EscapeAction {
if (s.previewPending) return 'drop_preview'
if (s.creating) return 'ask_creation'
if (s.inMode) return 'drop_mode'
if (s.chosenVertex !== null) return 'unchoose'
return s.selectedId !== null ? 'deselect' : null
}
```
```ts
// frame.ts (added)
/** R-11: 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
}
```
How the pieces work:
- The strip shows `SizeSlider` for a selected point and for the Point tool before the click (A5).
- `MoveModeBar` replaces the commands during the mode. Its arrows write `useAnnotationWork.preview` with
`source: 'move'`. « Valider la position » commits once through `updateGeometry`, with the stamp checked.
- The overlay reads the preview through a zustand selector, so the tab does not re-render on each step.
- The point handle carries the accessible name « Point {nom} », with arrow keys as a series (`source: 'keys'`)
committed on Enter or blur.
- [ ] **Step 1: doc.** In « Editor overlay »: handles and their sizes (R-9), the chosen vertex (bigger, filled,
ringed), the old place (grey dashes), the refused place (red dashes), the move-mode target, and the handle layer
as its own SVG.
- [ ] **Step 2: failing tests.**
- Unit `pointSize`: on the bundled draft, the main view gives 30 and 34, the head 27; a tie goes to the smaller; a
view without a point gives null; the range on the main view runs from about 13.25 to 68; `snapSize` reach edges.
- Unit `escapeAction`: one situation per press, in the board's order.
- Unit `moveStep`: tiny and large frames.
- The slider:
- It shows the stops and the red mark at the core value.
- Arrows, Page Up and release commit once (history depth +1).
- A value under the mark is refused by the core and restored with a red message.
- The move mode:
- Its arrows commit nothing until « Valider la position », which commits once. « Annuler » and Escape restore.
- A click on another annotation selects nothing during the mode.
- Guard (R-12): THIS task builds the shared drawing guard and its sites (listed under Task 7, which adds the
creation to them), with the move mode as its first user. With no step taken, a tab
change ends the mode silently. After one step, it asks « Abandonner le déplacement ? »; « Continuer » keeps
the mode and the position.
- Ctrl+Z during the mode only cancels it (R-13), and a later Enter commits nothing (Review Focus 2).
- A document change during the mode drops it.
- The keyboard on the point handle: arrows pan nothing (the box keys only), Enter commits once.
- A5: a click, the C26 candidate and the keyboard point all use the most used size.
- E2E mouse:
- Drag the point, change its size by a track click (WCAG 2.5.7).
- Repair the inherited out-of-frame point with the move mode, replacing the numeric repair of
`editor-geometry.spec.ts:273-281` (a partial move is refused and restored).
- Re-point the C26 test (`:118`) to the dialog in Task 7 (until then, to the panel's state).
- All under `expectNoShift`.
- [ ] **Step 3:** implement. **Step 4:** gates and the touched e2e 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:**
- `polygonEdit.ts` (below).
- `HandleLayer.tsx`: vertices, « + » with its visibility rule, the « − » bubble.
- `useCanvasGestures.ts` and `usePlacement.ts`: redraw = tracing target `replace` on any polygon; the close radius
in CSS px (R-11).
- `EditStrip.tsx` commands, and i18n.
- The properties panel's numeric group (circle and polygon) is removed here. The panel keeps its fields until
Task 6. `CreationPanel` keeps its group until Task 7.
- `editor-annotations.spec.ts` « keyboard only »: its numeric edit of an existing annotation is rewritten to the
handle keys. Its creation part stays until Task 7.
**Interfaces:**
```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,
)
}
/** R-9: a « + » shows only when its segment is at least two hit radii long on screen. */
export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
return segmentPx >= 2 * hitRadiusPx
}
```
- [ ] **Step 1: failing tests.**
- Unit tables:
- `insertMidpoint`: the wrap, and an out-of-range index gives null.
- `removeVertex`: null at 3.
- `moveVertex`: non-finite gives null.
- `isNoOpMove`: the neighbours.
- `showsInsert`: the edges.
- Unit tab:
- A click on a vertex chooses it (« sommet 7 choisi »), stamped. A click on the interior unchooses it.
- A vertex drag commits once; a release on a neighbour commits nothing.
- « + » inserts and chooses the new vertex. Undo, then « − », removes nothing stale: the chosen vertex was
dropped (Review Focus 2).
- « − » is disabled at 3 with « Une zone garde au moins 3 sommets ». Insert and Delete keys.
- The interior drag by mouse moves the zone; « Déplacer la zone » and « Déplacer le sommet » use the Task 4 mode.
- 41 vertices show the outline and the cap message.
- 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 close commits once and keeps every property. A
refusal (`interior_too_small`) keeps the trace open with its message. Escape keeps the old shape.
- Redraw guard (R-12): before the first vertex, Back ends it at once. After one vertex, Back asks « Abandonner
le nouveau tracé ? ».
- R-18: « Thoraciques » selected at fit zoom shows the zoom line; zooming until every « + » shows removes it;
a refusal message takes its place while shown.
- E2E mouse on « Thoraciques »: vertex drag, « + », « − », zone drag, redraw accepted and refused, undo for each,
all under `expectNoShift`. Also a click inside « Thoraciques » on c7-t1 selects the point that is drawn on top
(topmost rule).
- [ ] **Step 2:** FAIL. **Step 3:** implement. Map each removed numeric-group assertion to its replacement in the
commit body.
- [ ] **Step 4:** gates. **Step 5:** commit `feat(editor): vertex handles, insert and remove, zone move, redraw`.
### Task 6: The properties dialog over the column (A1, A2, A3, A9, A10)
**Files:**
- `Dialog.tsx`: `anchor?: RefObject<HTMLElement | null>`. With an anchor box, the panel sits at the anchor's left
and width, at `top = max(12, rect.top)`, with `max-height = innerHeight − top − 12`, and the light veil (22 % ink).
- When the space left is under 320 px (tablet keyboard, through `visualViewport`), it sits at
`visualViewport.offsetTop + 12` with `height = visualViewport.height − 24`.
- Without an anchor box, the placement is centred.
- It is measured at open and on `resize` and `visualViewport` `resize`.
- The veil ignores clicks when anchored (R-6).
- Navigation and history:
- `navigation.ts`: `EditorView.annotation: { id: string } | null`, on tab `annotations` only. The creation
dialog is NOT a layer (Task 7).
- `useEditorNavigation.ts`: `LAYERS = ['annotation', 'finding', 'citations', 'reference']`, the
`useAnnotationLayer` moves `open`, `close` and `replace`, `useAskLeaving`.
- `history/{entry,useEditorHistory,useLeaveConfirm}.ts` and `leftDraft.ts` at each site of the audit
(exhaustiveness on `Record<LayerName, …>` finds them).
- `tabs.ts` and `EditorWorkspace.tsx`.
- Create `AnnotationDialog.tsx`, `AnnotationReadBody.tsx` and `AnnotationEditForm.tsx` (it renders `CreationFields`
with « Couleur » on a `CreationForm` draft, with `missingFields`; R-3).
- Create `missingFields.ts` (below). Add the « Couleur » prop to `CreationFields.tsx` and the field order: region,
then zone.
- `tabs/AnnotationsTab.tsx`:
- The dialog is mounted beside `EditOnly`, with `readOnly`.
- The read-only body (R-16): at 1 024 px and wider, the strip in its read-only form and the read-only dialog;
below, `AnnotationReadBody` inline with `SelectionTag` (boards 14 and 16 unchanged).
- Delete `PropertiesPanel.tsx` and `AnnotationFields.tsx`.
- `EditableAnnotations.tsx`: the aside always shows `OverviewPanel`, with the selected row `aria-current="true"`.
- `AnnotationList.tsx`: Enter on the selected row opens the dialog.
- `focusTarget.ts` (R-5), i18n.
**Interfaces:**
```ts
// missingFields.ts (creation dialog and edit form)
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
}
```
- Opening (A1): a press-machine `open`, from the selection's interior or point, or a double click (R-8); Enter on
the selected row; the strip's « Propriétés ». A drag never opens.
- Save:
1. Read the CURRENT annotation by id from `useEditorStore.getState().previewState.document`.
2. Merge the changed fields.
3. Run one `update` through `useEditCommand.run`.
4. If the id is gone, close with the vanished-element replace and an announcement.
- Read mode:
- The fields as text; « Couleur » only when set, « Région vertébrale » only when set, and « Vue ».
- The geometry issues as an alert.
- « Modifier » and « Modifier la forme »; « Marquer comme relu » or « Remettre à confirmer » (one `set_status`,
one undo); « Supprimer » (`DeleteDialog`).
- 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.
- Read-only (R-14): the dialog stays with a notice, disabled inputs and its draft, and Save is disabled. It becomes
editable again on the way back.
- History: Back closes the dialog and Forward reopens it.
- A layer whose id no longer exists is sanitised away, and the view lands on nothing selected, with an
announcement.
- A layer for an annotation of another view switches the view and selects it.
- [ ] **Step 1: failing tests.**
- `ui.Dialog.test.tsx`:
- The anchored geometry from a stubbed rect.
- The keyboard fallback from a stubbed `visualViewport` (height 350, `offsetTop` 0).
- The centred fallback.
- The veil ignores clicks when anchored; centred dialogs are unchanged.
- Layer suites (`editor-navigation`, `editor-history-entry`, `editor-history-guards`): open, close, Back, Forward,
vanished, other view.
- Unit `missingFields`: a chosen category is never listed (adjustment 3). A link with both names blank is fine,
with one blank names it. The fields come in form order.
- Unit read-only sheet at 1 280 px (R-16): strip « fiche en lecture seule », « Propriétés » opens the read-only
dialog, no handle, no slider.
- Unit tab:
- A first click and Enter on a row only select (A1). A second click on the interior opens; with a chosen vertex
it unchooses.
- Read mode per type.
- « Marquer comme relu » gives one undo.
- Edit category and both names, then save: ONE history entry.
- A blank name shows « Saisissez le nom en anglais. » and the summary.
- « Annuler » when dirty asks; « Abandonner » writes nothing.
- The issues block on the inherited out-of-frame point.
- The twin renders the read body.
- « Aller à » focuses the row (R-5).
- Unit read-only flip: open, type, `mode` flips to read-only. The dialog is still open, Save is disabled, the draft
is kept, nothing is committed; on the way back it is editable with the draft.
- Unit read-only flip during a started move mode: the mode is suspended and resumes with its position on the way
back (R-14).
- E2E:
- The dialog box lies inside the aside's x-range, starts at its top, and 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 double click on the selected zone leaves the dialog open with no vertex added.
- A touch tap on the selected shape opens the dialog, and it stays open.
- Width crossing below 1 024 px with a typed form, and back: the draft is intact (Review Focus 3).
- `expectNoShift` around open and close.
- [ ] **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`, `editor-no-loss`) in the commit body.
- [ ] **Step 4:** gates; the finding, history and leave suites green on the sandbox.
- [ ] **Step 5:** commit `feat(editor): annotation properties dialog over the column, transactional save`.
### Task 7: Creation by placing and tracing, then the creation dialog (A4, A5, A7, A12, A15)
**Files:**
- Create `CreationDialog.tsx`, mounted beside `EditOnly` with `readOnly`. Delete `CreationPanel.tsx`.
- `creation.ts` (`missingFields`, from Task 6, replaces `formProblem`), `creationAttempt.ts`, `usePlacement.ts`
and `KeyboardAdd.tsx`.
- `workStore.ts`: `creation` holds the pending shape and the form across « Replacer le point » and « Reprendre le
tracé ».
- The drawing guard (built in Task 4 for the move mode, extended in Task 5 to the redraw; this task adds the
creation and the undo rules; R-12):
- `useEditorNavigation.ts`: `useTabSelect`, the arrow-key tab move, `openSection` and the view chips ask, with
R-12 through `ConfirmDialog`.
- `history/useEditorHistory.ts`: `refusal` asks it on every POP. The creation dialog is a modal without a layer
(like `DeleteDialog`), so a Back while it is open is refused as `'modal'`, and `askAll` (which now includes
the drawing guard) shows its question inside the dialog.
- `history/useLeaveConfirm.ts`.
- `HistoryButtons.tsx` and `useUndoShortcuts.ts`: inactive during a creation.
- `GestureMessage`: « Défaire » hidden during a creation.
- The dimming: a host attribute `data-creating` and the CSS of the other annotations. Doc first.
- i18n.
Behaviour:
- **Placing.** The Point tool shows a preview under the mouse pointer at the strip size; touch has no hover.
- A click creates `creation` and opens « Nouveau point » (A2) with the ghost under the light veil.
- Changing the category recolours the ghost (A4). The laterality has no default.
- « Replacer le point » hides the dialog (`dialog: false`); the next click moves the ghost and shows it again.
- **Tracing.** The zone tool: closing on the first vertex (R-11), Enter or « Fermer le tracé » opens « Nouvelle
zone ». « Reprendre le tracé » keeps the vertices and shows « Revenir aux propriétés ».
- **Créer.** `insertAnnotation` under `accept`, one undo. Then the tool returns to « Sélectionner », the new annotation
is selected (A7), the message « Point créé · Défaire » or « Zone créée · Défaire » shows, and the focus goes to
its row (board 32).
- **Abandonner, ✕, Échap, Back.** The dialog's guard is ALWAYS armed, because the shape always exists (A12). Each
of them shows `DiscardConfirm` titled « Abandonner la création ? », even with nothing typed. « Abandonner » then
clears the creation, and the focus goes to the tool button.
- **During a creation.** Other annotations are dimmed and unselectable. The guard sites ask (R-12), and undo is
inactive.
- **Keyboard.** The add buttons place the shape at the centre at the A5 size and open the dialog.
- **Links.** A link shows « Vue ouverte ».
- **C26.** The notice shows in the dialog (R-4).
- **Read-only flip (R-14).** The dialog stays with its form and Créer is disabled.
- [ ] **Step 1: failing tests.**
- Unit tab: each behaviour above. ✕, Échap and Back on a creation dialog with nothing typed still ask, and the
shape is kept on « Continuer ». « Créer » without a laterality shows only « Choisissez une latéralité. » and
« À compléter : Latéralité. »
- Unit guards: a tab click, an arrow-key tab move, a section, a view chip, a tool, Back, Escape, sign-out and the
route leave each ask during a creation. « Continuer » keeps everything; « Abandonner » proceeds.
- The same sites, for a move mode and a redraw: they act at once before any work, and ask once work has started
(R-12). Escape and « Annuler » never ask for a mode.
- A started move mode, then a recovery replaces the document: the mode is dropped and announced (R-13).
- Unit: a creation open, then the width flips to read-only and back: the form and the ghost are intact.
- 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 »).
- The C26 test of `editor-geometry.spec.ts:118` re-pointed.
- axe on the creation states.
- `expectNoShift` when the dialog opens.
- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** gates.
- [ ] **Step 5:** commit `feat(editor): creation on the drawing then the creation dialog`.
### Task 8: Touch: two fingers, the hint, the loupe, the sizes
**Files:**
- `catalogue/useFraming.ts`: `twoPointerPan?: boolean`. The pinch branch also translates by the midpoint's
movement. The catalogue passes nothing and keeps today's behaviour.
- `useCanvasGestures.ts`: `twoPointerPan: true`; the hint on a `futile` drag.
- `Loupe.tsx`:
- Technique A: at a touch-drag start, clone the drawing's `<svg>` once (`aria-hidden`, `inert`) into a 120 px
disc 90 px above the finger, clamped inside the box, ×2 around the finger, with the preview outline on top.
- Technique B: the outline and handles only.
- `HandleLayer.tsx`: R-9 sizes from `(any-pointer: coarse)`.
- [ ] **Step 1: failing tests.**
- Unit `useFraming`: the defaults are unchanged (catalogue suites). With `twoPointerPan`, two pointers moving
together translate without scaling.
- Unit hint: a futile drag shows R-1 when the line is free, never while a message shows, and never again after a
two-finger gesture worked.
- 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 shown.
- 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: the drag is cancelled, the shape restored, nothing committed, and the
pinch zooms (Review Focus 1).
- The move mode by a finger.
- A tap on the selected zone opens the dialog; with a chosen vertex it unchooses.
- The trace closes from a finger within 22 px.
- Page scroll over the canvas without a selection keeps working.
- Every handle hit circle is at least 44 px.
- `expectNoShift` at the hint.
- Smoothness MEASURE, not a suite assertion (a timing check would flake on the shared sandbox): a script in
`apps/app/e2e/support/measure-drag.ts`, run by hand. Chromium touch at 1 180 px, CPU ×4 (CDP
`Emulation.setCPUThrottlingRate`), a 2 s vertex drag on the equine main view. It prints the median and p95
of pointermove to next frame, loupe included, and the figures go into the plan. Over 16 ms at p95 with
technique A, B is measured. If only B is acceptable, STOP for the conditional owner decision. The owner's
tablet trial is the real check.
- Measured 2026-11-18 (`MEASURE_DRAG=1 MEASURE_BUILD=preview`, production build under `vite preview`, Chromium
touch 1 180 × 800, CPU ×4, 2 s drag of a « Vertèbres thoraciques » vertex on a seeded draft, three runs each).
Frame work (first `pointermove` to the end of the next frame), p95: technique A 4.2 / 4.5 / 4.7 ms, B 4.0 /
4.4 / 4.3 ms, no loupe 4.0 / 4.2 / 3.6 ms; mouse control 3.1 to 3.9 ms. Technique A kept. From the event
timestamp the touch median is about 26 to 30 ms for all three (browser input queueing, the same without
loupe). The first run on the Vite dev server (React development build, StrictMode) gave about 30 ms for A and
25 ms with no loupe; it does not stand for the product.
- Measured again 2026-11-18 on the final code (15b23f8), same conditions, technique A only, three runs: frame
work median / p95 3.0 / 3.9, 3.2 / 4.5, 3.1 / 4.0 ms (53 of 55 samples with the loupe); touch from the event
timestamp 26.9 ms median in each run; mouse control p95 3.2 / 3.9 / 3.4 ms.
- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** gates.
- [ ] **Step 5:** commit `feat(editor): two-finger pan, touch hint, loupe, touch-sized handles`.
### Task 9: 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, about 47 undo steps.
- `docs/development/V1-2-6_UX_PLAN.md` §U2: the file list, the message, the status.
- `docs/ANNOTATION-RENDERING.md`: read again whole.
- `docs/development/RUST.md`: the size figures and the exception row.
- `RUST_ARCHITECTURE_REVIEW.md` Part II: the row.
- `docs/design/README.md`.
- `CLAUDE.md`: folder lines.
- [ ] **Step 1:** write. **Step 2:** grep the removed names (`TracingBar`, `CreationPanel`, `PropertiesPanel`,
`AnnotationFields`, `useMoveGesture`, `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 10: Gates and the owner checkpoint
- [ ] **Step 1:** `pnpm check:all`. Record the exact output lines.
- [ ] **Step 2:** sandbox `pnpm db:sandbox up fresh`, `test-db`, `e2e-shell` (whole shell suite), then `test`.
Record the counts.
- [ ] **Step 3:** commit latency under 500 ms for a vertex drag, an insert and a removal (`editor-equine.spec.ts`
through its sandbox alias).
- Ruling (T10): measured by the opt-in `shell/editor-measure-commit.spec.ts` (`support/measure-commit.ts`) on a
run-seeded equine-sized draft, never `editor-equine.spec.ts` nor the historical copy.
- Measured 2026-11-18 (`MEASURE_COMMIT=1 MEASURE_BUILD=preview`, production build under `vite preview`, Chromium
mouse 1 280 × 800, CPU ×4 during each gesture, « Vertèbres thoraciques » of the seeded draft, three runs per
gesture, each undone). From the `pointerup` time stamp to the end of the first frame, after paint, showing the
new `points`, no old-place outline and « Défaire la dernière modification » enabled (the undo entry). Median /
max: drag 176.9 / 209.2 ms, « + » 176.2 / 177.6 ms, « − » 168.2 / 170.3 ms; a second spec run gave 176.0 /
209.1, 176.1 / 186.1, 169.5 / 175.3 ms. All under the 500 ms bar. A dev-server smoke run (React development
build) gave medians 337.3, 329.1 and 272.2 ms, max 399.3 ms; it does not stand for the product.
- Measured again 2026-11-18 on the final code (15b23f8), same protocol: drag 202.1, 174.7, 171.0 ms (median
174.7, max 202.1); « + » 175.1, 178.3, 173.4 ms (175.1 / 178.3); « − » 169.7, 165.7, 182.2 ms (169.7 / 182.2).
All under the 500 ms bar.
- [ ] **Step 4:** fresh `verifier` against the U2 implementation contract (written at the start of execution with
the owner's approval brief verbatim), and fresh `security-auditor` on the U2 diff, once each.
- [ ] **Step 5:** owner trial section `docs/development/V1-2-6_OWNER_TRIAL.md` §4.17 « Démonstration U2 », on the
dedicated trial stack `pnpm db:trial` (owner's request, 2026-11-17).
- U2 adds no migration: `pnpm db:trial start`, then `pnpm db:trial app` serve this branch's code on the existing
data. The owner runs them; Claude writes nothing on the trial stack.
- If `db:trial status` shows a missing migration or drawing, the section says which existing command fixes it
(`migrate`, `assets`) and the owner runs it.
- 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, create a point and a zone, undo each step.
- Tablet in landscape: the same, plus the two-finger hint, the loupe, and a rotation with a dialog open.
- Watch for no jump when a message appears.
- Leave a started move mode and a started redraw by a tab and by Back: each asks; an unstarted one ends at once.
- Select « Thoraciques » at fit zoom: the zoom line shows; zoom until the « + » appear.
- [ ] **Step 6:** STOP for the owner's trial on `db:trial` (mouse and tablet). U2 closes only on the owner's
validation after that trial. Capitalize per the closing flow.
## Out of scope, tracked
- Curves: the curves lot (T16). A path only gets « Remplacer par un polygone ».
- The « Constats » part of the annotation dialog: U2b.
- The colour picker: U3 and U6 (A9 keeps the hex field).
- `RepairDialog`'s coordinate fields: U5 (D1 recommendation).
- Phone editing: O14 A.
- Firefox and WebKit: a follow-up, Chromium only until V1-5.
- BLK-015, RR-13, anomalies A and B: separate tracks.
## Challenge round (2026-11-17, three fresh `plan-challenger` agents, read-only, on rev 1)
### Correctness: FATAL(9)
| # | Finding | Rev 2 |
|---|---|---|
| 1 | `GeometryGroup` deleted while `RepairDialog`, `CreationPanel` and `PropertiesPanel` import it | Accepted: kept for `RepairDialog` (D1); removed from the panels in Tasks 4, 6 and 7 |
| 2 | A5 radius reaches only `proposePoint` | Accepted: radius passed through `correctedCircle`, `centreCircle`, `pendingForClick`, `keyboardPending`, `correction.ts` (R-10, Task 4) |
| 3 | Any other annotation in the stack beats the interior | Accepted: topmost annotation decides (`pressTarget`) |
| 4 | First handle in DOM order | Accepted: `nearestHandle`, ranked ties |
| 5 | Mouse pan during a handle or interior drag | Accepted: `canPan` = `dragAction(...).type === 'pan'` (Task 2) |
| 6 | A double click opens then closes, or inserts | Accepted: R-8 double click, R-6 veil ignores clicks |
| 7 | No site asks for a tab change | Accepted: `useTabSelect`, the arrow-key tab move, `openSection` and the view chips (Task 7) |
| 8 | Arrows on a handle also pan | Accepted: framing keys only on the box itself (Task 2) |
| 9 | Three slop measures | Accepted: the press machine is the editor's only decider (Task 2) |
| 10 | `trace_pop` and the file lists out of order | Accepted: `trace_pop` and `focusTarget.ts` in Task 3, `creationAttempt.ts` and `creation.ts` listed |
| 11 | Undo with a pending preview acts twice | Accepted: R-13, undo cancels only |
| 12 | Escape lacks a pending row; `dragAction` lacks inputs | Accepted: `drop_preview` row; `movable` and `moveMode` |
| 13 | Message « Défaire » live during a creation | Accepted (R-2, Task 7) |
| 14 | Focusable handles in an `aria-hidden` svg | Accepted: `HandleLayer` has its own svg |
| 15 | Range bound from `defaultRadius` | Accepted: `sizeRange` |
| 16 | Generic required key in the edit form | Accepted: shared `missingFields` (R-3) |
| 17 | Pointer preview and two focus returns missing | Accepted (Task 7) |
| 18 | `{ create }` reached by Forward without a shape | Resolved by dropping `{ create }`: the creation dialog is a modal without a layer, and the creation guard asks on every POP |
| 19 | Classic-scrollbar test vacuous in headless | Accepted: computed style and `clientWidth` asserted |
### Robustness: FATAL(9)
| # | Finding | Rev 2 |
|---|---|---|
| 1 | Dialogs inside the hidden editable subtree on a read-only flip | Accepted: mounted beside `EditOnly` with `readOnly` (R-14); Review Focus 3 rewritten |
| 2 | Drawing work invisible to leave, sign-out, tabs and undo | Accepted: `workStore`, read by every site (Task 7) |
| 3 | Stale previews and chosen vertex | Accepted: stamps, `dropStale`, R-13 |
| 4 | Press at pointer-up vs click; three deciders; pinch ends as a click | Accepted: press machine with `multi`; veil ignores clicks (R-6) |
| 5 | Paint order | Accepted (as correctness 3) |
| 6 | Overlapping handles, « + » on a plain click | Accepted: nearest handle, « + » hidden on short segments, double click guarded |
| 7 | Forward onto `{ create }` | Resolved (as correctness 18) |
| 8 | Tablet keyboard breaks the anchored height | Accepted: `visualViewport` fallback under 320 px, tested |
| 9 | Smoothness never measured on the page; per-move state at the tab root | Accepted: canvas-local drag, store selector for previews, p95 e2e on the editor (Task 8) |
| 10 | Hybrid devices | Accepted: `(any-pointer: coarse)` read once, no element re-creation |
| 11 | Scrollbar test vacuous | Accepted (as correctness 19) |
| 12 | `expectNoShift` false passes | Accepted: two frames, every entry, header box |
| 13 | Message sticks on touch | Accepted: mouse-only hover pause |
| 14 | Trace close under the finger slop | Accepted: R-11 in CSS px per kind |
| 15 | R-6 heap; Back in a mode | R-6 dropped (8 MiB kept, R-15); Back in a mode cancels it (R-12) |
### Simplicity: CONCERNS(5)
| # | Finding | Rev 2 |
|---|---|---|
| 1 | Three click deciders | Accepted (Task 2) |
| 2 | `preview.ts` no-op | Accepted: deleted; stamps in `workStore` |
| 3 | Two field components | Accepted: `AnnotationEditForm` renders `CreationFields`, one `missingFields`, `AnnotationFields` deleted |
| 4 | `drawing` guard too wide | Accepted: creations only (R-12) |
| 5 | Task split | Accepted: pure modules land with their first consumer; `trace_pop` in Task 3; loupe built and measured in Task 8; no Task 0 |
| 6 | `creation.phase` restates state | Accepted: `creation.dialog` boolean only, form lifted to the store |
| 7 | `canPan` rename churn | Accepted: name kept |
| 8 | `CreationConfirm` duplicates `ConfirmDialog` | Accepted |
| 9 | Dialog change too wide | Partly: one `anchor` prop implying the light veil. The `visualViewport` fallback is kept, because robustness 8 shows the plain `max-h` fails with the tablet keyboard |
| 10 | Page-wide gutter, page-wide shift sum | Gutter scoped to the editor. The page-wide sum is kept with the header box (robustness 12) |
| 11 | R-6 and Task 0 step 2 unasked | Accepted: dropped |
| 12 | Last-press switch | Accepted: `(any-pointer: coarse)` |
| 13 | Hint clock and queue | Accepted: no clock |
| 14 | One-liner modules; Escape wiring unnamed | Accepted: `moveStep` in `frame.ts`, the radius read inline, `escapeAction` wired into `useEscapeDeselect` |
| 15 | `SelectionTag` and `PropertiesPanel` for the twin | Accepted: `SelectionTag` kept, `PropertiesPanel` deleted |
| 16 | `sizeRange` | Accepted |
## Final pass on rev 2 (stronger reviewer, before the owner)
- Task 2 keeps today's tests green by reading the selected point as its own handle. The finger drag of a zone
interior stops there (A13), named.
- The numeric group leaves the properties panel in Task 5, after polygons have handles, not in Task 4.
- `missingFields` and the « Couleur » prop move to Task 6, their first consumer.
- The creation dialog's guard is always armed: a shape alone asks (A12).
- `{ create }` is dropped from history: the creation dialog is a modal without a layer.
- The read-only sheet at 1 024 px and wider gets the strip and the read-only dialog (R-16, boards 31 F and 33 E).
- Blur commits a keyboard series (R-12, BDR-050).
- The smoothness check becomes a measure, not a suite assertion.
- « + » visibility was measured on the equine zones and became D2.
- Rust by default became R-17.
## Owner answers (2026-11-17, rev 3)
- D1 validated: coordinates stay in the exceptional drawing-repair dialog until U5; A8 concerns the normal
annotation editing journey.
- D2 validated with a precision: « + » hidden on segments too short, revealed by zooming, and a discreet hint while
a selected zone has hidden « + » (R-18).
- R-12 corrected: a move mode or a redraw ends at once when nothing was started, and asks before being dropped
once work has started. The read-only flip suspends such a mode instead of dropping it (R-14), and a drop caused
by a document change elsewhere is announced (R-13), to keep « no silent loss » whole.
- Visible choices confirmed: the veil ignores clicks, a double click opens the properties, the strip and messages
never move the drawing, the read-only sheet keeps its properties readable, touch, loupe and gestures as planned.
A13, A14 and the board 33 adjustment validated as integrated.
- The owner tries the result on `pnpm db:trial` before U2 closes (Task 10).
## Owner corrections before the trial (2026-11-19, rev 4)
The owner read the Task 10 checkpoint and asked for six corrections before the db:trial run (verbatim in the
contract's addendum). Accepted as built, no change: Escape asks before dropping a creation; « Annuler le tracé » is an
explicit discard; a double click on « + » inserts one vertex; a message stays visible while it holds the focus. The
paging of the rights screen and the progressive loading of the catalogue go to the TODO. The ratified requirement on
made-up passwords in scripts stays: no real secret in clear in logs, process arguments, test or CI/CD artefacts before
production.
Findings that shape the tasks (controller, read-only, at 1f2485e):
- Point 5 is already the code's behaviour: the group is « Sommets de {nom} » with `annotationName()`, the annotation's
full name. The real equine zone is « Vertèbres thoraciques » (`measure-drag.ts:122` already expects « Sommet 1 de
Vertèbres thoraciques »); « Thoraciques » is the vertebral region's name, used only by a unit fixture and by
criterion 18's example. Task 12 pins it with an e2e assertion; the contract example is corrected.
- Point 1: the shell's top bar is `sticky top-0 z-30 h-14` (`ShellChrome.tsx:89`, plus the safe-area inset) on the
document's scroll; the edit strip is not sticky, so it scrolls under the bar (verifier-fix-report §3: bar bottom
56 px at 1 024, 1 180 and 1 280 px).
- Point 2: `commitFocusedSeries` (`drawingGuard.ts:7-13`) commits by `blur()`, so a touch press or a Safari tap sends
the focus to `body`. Its callers: `usePressGesture.ts:298`, `usePointEdit.ts:115`, `redraw.ts:18`,
`deselect.ts:57`, `drawingGuard.ts:34`.
- Point 3: `useZoneEdit`, `ZoneHandles` and the press machine take a stored `Annotation` (`currentPoints(id)`,
`onDrop` commit, `chosen` stamped with the document text). `resumeTrace` reopens the polyline (`closed: false`).
- Point 4: the canvas box maps `+`, `=`, `-`, `0` to the zoom (`useFraming.ts:243-252`) when it has the focus itself;
the tracing maps Backspace to « Retirer le dernier sommet » (`usePlacement.ts:116`).
- Point 6: `HistoryButtons` uses `aria-disabled` (focusable) and a `title`; neither tells a touch or keyboard user why
the button is held.
Rulings (rev 4):
- Ruling: point 3 generalises the existing zone editing to a target « points + drop »; a pending creation's drop
patches `creation.pending` and never touches the document or the history. No second handle path — two paths
would drift — cost if wrong: a later split.
- Ruling: undo stays inactive during a creation (A12, criterion 12); a change of the pending shape has no undo
entry, so its message line carries no « Défaire ». Arrow keys move a pending vertex at once (no keyboard series,
nothing held) — cost if wrong: one message variant.
- Ruling: the core's verdict on a zone stays at « Créer » (board 04: « Une zone trop étroite est refusée … »); the
handles enforce only the three-vertex floor, as on a stored zone — cost if wrong: a refusal arrives at « Créer »
instead of at the drop.
- Ruling: no interior drag of a pending zone (board 04 C draws vertices and « + » only); the 40-vertex cap applies
as on a stored zone. Both are listed for the trial.
- Ruling: point 4's Insert alternative is the « + » key (`event.key === '+'`, so AZERTY, QWERTY and the keypad
alike) on a focused vertex handle: it matches the drawn « + », needs no visible « + » (hidden on short segments),
and adds one key, not a chord. Backspace joins Delete through the same path. On the canvas box itself « + » still
zooms — cost if wrong: one key in a map.
- Ruling: point 1 makes the strip sticky under the top bar on the editable layout (≥ 1 024 px), the bar's height in
one CSS variable shared by both; below 1 024 px nothing changes (boards 14, 16). `ShellChrome.tsx` joins the FILE
SCOPE for that variable — cost if wrong: a strip that hides a band of the drawing while scrolled.
- Ruling: point 6 also covers « Défaire » during a creation (same mechanism, same question from the user); two
reasons only: a creation, or work pending. Extension of the owner's ask, reported after.
### Task 11: « Reprendre le tracé » edits the closed shape with its handles (board 04 C)
**Files:** `editor/annotations/{creationWork,workStore,useZoneEdit,zoneEdit,usePlacement,usePressGesture}.ts`,
`components/editor/annotations/{ZoneHandles,HandleLayer,AnnotationCanvas,EditableAnnotations,CreationCommands,
SceneStrip,stripLead}.tsx|ts` as needed, `i18n/{fr,en}.ts`, unit and e2e tests (new e2e in a creation spec, never
`editor-equine.spec.ts`).
**Behaviour (board 04 C):**
- « Reprendre le tracé » hides the dialog; the closed pending polygon stays drawn with its category fill, and the
zone handles show on it: vertices, « + » on segments long enough (R-9, the zoom hint as on a stored zone), « − »
on the chosen vertex. Same for a keyboard-added zone and for a link drawn as a polygon.
- A vertex drag (mouse, touch with the loupe), « + », « − », the vertex keys (arrows, Enter, Insert, Delete, and
Task 12's keys once added) change `creation.pending` only: the document, the history, « Défaire » and the unsaved
count are untouched. « − » at three vertices says `message.vertex_min`. The message line says what changed without
« Défaire ».
- The strip reads « Nouvelle zone » (« Nouvel accès ») · « Tracé repris, saisie gardée », with « Revenir aux
propriétés » and « Abandonner » only. « Retirer le dernier sommet » is gone from the resumed state (it stays in a
fresh tracing).
- A click or tap on the drawing off the handles adds no vertex and selects nothing. Escape asks « Abandonner la
création ? » as today. « Revenir aux propriétés » reopens the dialog with the form intact and the edited shape; the
focus goes where it goes today.
- Handle names: « Sommet {n} de {nom} » in « Sommets de {nom} », with the form's name in the current locale; while
that name is empty, « la nouvelle zone » / « le nouvel accès » (en: « the new zone » / « the new link »).
- The chosen vertex of a pending shape never outlives the creation (finish, drop, view change) and never leaks onto
a stored annotation.
- A point keeps « Replacer le point » as today.
**Deletions:** the `resumed` branch of `popVertex` and of `backToProperties` → `closeTrace`, the resumed
`tracedCount` path of `CreationCommands`, and every assertion of the polyline reopening; each removed assertion is
mapped in the commit body.
- [ ] **Step 1: failing tests.** Unit: resume keeps `closed` true and shows the handles; a drag, « + », « − », Insert,
Delete and arrows patch `creation.pending` and leave the document text and the history unchanged; « − » at three
vertices is refused with the message; « Créer » writes the edited shape in one insert; the chosen vertex clears on
finish and drop; the fallback names. E2E (1 280 px mouse and a touch run at 1 180 px): close a 5-vertex trace,
type a name, « Reprendre le tracé », drag a vertex, add one by « + », remove one by « − », « Revenir aux
propriétés », « Créer », then one undo removes the whole new zone; axe on the resumed state; `expectNoShift` at
resume and back.
- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** typecheck, lint, unit suite, the touched shell specs.
- [ ] **Step 5:** commit `feat(editor): resumed trace edits the closed shape with its handles`.
### Task 12: Vertex keys without Insert and Delete (Mac), the group name pinned
**Files:** `editor/annotations/useZoneEdit.ts`, `components/editor/annotations/ZoneHandles.tsx`
(`aria-keyshortcuts`), `i18n/{fr,en}.ts` if a key hint names the keys, unit and e2e tests.
- On a focused vertex handle (stored zone, and a pending one from Task 11): Backspace removes the chosen vertex
exactly as Delete (three-vertex floor and its message, move-mode inertness, pending arrow steps committed first);
« + » (`event.key === '+'`) inserts after the chosen vertex exactly as Insert, also when that segment's « + » is
hidden. Both `preventDefault`; neither reaches the canvas zoom nor the tracing's Backspace; no platform sniffing.
- The vertex handles' `aria-keyshortcuts` list the added keys.
- E2E on the sandbox copy: the handle group's accessible name is « Sommets de Vertèbres thoraciques » and a vertex
reads « Sommet 3 de Vertèbres thoraciques »; Backspace and « + » on a vertex, each undone.
- The unit fixture « Thoraciques » may stay (a unit name), but criterion 18's example is corrected in the contract.
- [ ] Steps: failing tests, FAIL, implement, gates, commit `feat(editor): Backspace and « + » on a vertex handle`.
### Task 13: The focus after a touch commit of pending settings
**Files:** `editor/annotations/{drawingGuard,usePressGesture,usePointEdit,redraw,deselect,focusTarget}.ts` and the
mode commands that call them, unit tests (the existing Safari block simulates a tap that does not focus).
- The pending keyboard series or slider change commits explicitly (the focused handle's or slider's own commit), not
by `blur()`; the focus never lands on `body` because of the commit.
- Then the focus goes where the same action sends it from the keyboard, with `preventScroll`:
- a press on a handle: that handle (the pressed vertex or point handle);
- a press elsewhere on the drawing that keeps the selection: the handle that held the series, if it still exists;
else the canvas box;
- « Déplacer … », « Redessiner », « Désélectionner » and the other selection commands: the focus their keyboard
activation gives today (the mode's own target, or the command);
- a handle removed by the action itself (a removed vertex, a redraw): the next vertex, else the strip's command.
- Unit tests per path with a tap that does not focus (Safari block); one e2e touch run. Real iPad Safari stays a
trial item, never reported as verified.
- [ ] Steps: failing tests, FAIL, implement, gates, commit `fix(editor): focus follows the action after a touch commit`.
### Task 14: The strip stays below the top bar while the page scrolls
**Files:** `components/shell/ShellChrome.tsx` (the bar's height as one CSS variable), `styles/index.css`,
`components/editor/annotations/SceneStrip.tsx` (or the strip's wrapper), e2e tests.
- On the editable layout (≥ 1 024 px), the strip is sticky right under the top bar: at every scroll position its top
is at or below the bar's bottom, and nothing of the strip is under the bar. Opaque background; above the drawing,
below the bar, the dialogs, the loupe and the menus.
- No ancestor `overflow` breaks the stickiness; the boxes of the canvas, the aside and the strip keep their place in
the flow (no layout shift); a programmatic focus or `scrollIntoView` never leaves a target under the bar or the
strip (`scroll-margin` or `scroll-padding`).
- Below 1 024 px nothing changes.
- E2E at 1 024 × 768, 1 180 × 820 and 1 280 × 800: scroll by steps to the bottom; at each step the strip's top ≥ the
bar's bottom and the strip is fully visible; `expectNoShift` on the canvas and the aside; a tap on a strip command
after a scroll hits it (no re-scroll by the hit check).
- [ ] Steps: failing tests, FAIL, implement, gates, commit `fix(editor): the strip stays below the top bar on scroll`.
### Task 15: Why « Refaire » (and « Défaire » during a creation) is unavailable
**Files:** `components/editor/HistoryButtons.tsx`, the annotations message line (a store signal or the existing
message API), `i18n/{fr,en}.ts`, unit and e2e tests.
- While held, the button keeps `aria-disabled` and gets `aria-describedby` to a short reason, read on focus:
- pending work (a started mode, a keyboard series, a slider change): « Refaire attend la fin de la modification en
cours : validez-la ou annulez-la. » (en: « Redo waits for the change in progress: confirm or cancel it. »);
- a creation: « Indisponible pendant une création : créez l'annotation ou abandonnez-la. » (en: « Unavailable
during a creation: create the annotation or discard it. »).
- A press (click, tap, Enter, Space) on a held button shows the same reason in the message line under the drawing,
without moving anything (A14), announced once; nothing else happens.
- The other disabled causes (nothing to redo, read-only) keep today's behaviour.
- The stale comment at `HistoryButtons.tsx:83` is fixed.
- [ ] Steps: failing tests, FAIL, implement, gates (axe on the held state), commit
`feat(editor): say why redo is unavailable during pending work`.
- Superseded at the final review (contract criterion 30, amendment of 2026-11-19): the pending-work text above was
false advice (a commit clears the redo stack); the texts, the « reason only when it helps » rule and « Défaire »
cancelling pending work are in the contract.
### Task 16: Documents, TODO, gates and the owner checkpoint (rev 4)
- `docs/development/V1-2-6_OWNER_TRIAL.md` §4.17: steps for Tasks 11 to 15 (mouse and tablet), the four accepted
behaviours moved out of « Choix visibles à juger », the new visible choices (the reason texts, the « + » key, the
sticky strip, the fallback handle names, no interior drag of a pending zone).
- `docs/development/V1-2-6_UX_TESTS.md` §U2, `docs/design/README.md:240` (« Reprendre le tracé » now draws the
handles as board 04 C), `docs/ANNOTATION-RENDERING.md` if the pending shape's handles change the overlay.
- `.claude/tasks/TODO.md`: the two follow-ups the owner approved (paging of the rights screen, progressive loading
of the catalogue) and the passwords requirement kept with the guardrails item.
- Gates on the final head: `pnpm check:all` exit 0; the shell suite without `editor-equine.spec.ts`; both opt-in
measures again; a fresh verifier on the contract with its addendum; a fresh security auditor on the U2 diff.
- [ ] STOP for the owner's trial on `db:trial`, the real equine sheet and the tablet. U2 closes only on the owner's
validation.
## Rev 5 (owner decisions at the checkpoint, 2026-11-19; contract addendum 2, criteria 32-35)
Order: Task 17 (the drawing, riskiest, moves the layout) → Task 18 (bubble, sits over that layout) → Task 19
(catalogue-integrity diagnosis, sandbox alone) → Task 20 (docs and gates). No `up fresh`, no reset (D4).
### Task 17: The drawing is never under the strip
**Files:** `styles/index.css`, `components/editor/annotations/EditableAnnotations.tsx` (`CanvasColumn` and the grid),
`AnnotationCanvas.tsx` if the box sizing changes, e2e `editor-geometry.spec.ts`, `editor-deselect.spec.ts`,
`editor-journey.spec.ts`, `docs/ANNOTATION-RENDERING.md`.
- Pin the canvas column (view chips, canvas, add row, message line) under the strip on the editable layout
(≥ 1 024 px) while the aside scrolls past: `sticky` at `top: bar + strip + gap`, so no part of it goes under the
strip or the bar. The aside may still pass under the strip: say so in the docs.
- The column must fit: if the viewport height cannot hold it, the add row and the message line must stay
reachable. If the canvas is capped by the viewport height, its size depends on the window, never on the scroll,
and is unchanged at 1 024 × 768, 1 180 × 820 and 1 280 × 800 (measure first; probe at least one shorter height,
e.g. 1 024 × 600 and 1 180 × 700).
- Pinned controls get no scroll margin (the Task 14 page jump: a focus on a stuck element scrolled 300 → 0):
exclude the pinned column from the drawing-place margin as the strip is excluded; extend « a focus never scrolls
onto the bar or the strip » to a chip, a handle, the add button and the line's « Défaire » while scrolled; probe
the keyboard insert/delete path that scrolls a vertex into view.
- Remove the rev 4 test workarounds (`scrollToTop` / `expectOnDrawing` from de418b29): the presses in
editor-deselect :287, :597 and editor-journey :313 pass where first written. The axe scan of the journey may stay
at the page top only if the aside still meets the strip there; say which.
- « Sans décalage intempestif »: find whether the 291 px scroll on a row click came from the product or from
Playwright's click; assert the canvas's on-screen position (getBoundingClientRect) around a row selection.
- No horizontal scroll at the three sizes and the shorter probe; touch: one-finger drag, pinch, page scroll over
the canvas without a selection, the loupe: editor-touch green.
- [ ] Steps: probes first (figures before), failing tests, implement, gates, commit `fix(editor): the drawing stays
clear of the strip while the page scrolls`.
### Task 18: The held reason in a bubble (D1)
**Files:** `components/editor/HistoryButtons.tsx`, a bubble component under `components/editor/`, remove the
`historyPress` route (`workStore`, `EditableAnnotations` effect, other-tab guard), i18n unchanged (same texts),
unit and e2e tests.
- A press (click, tap, Enter, Space) on a held « Défaire » or « Refaire » shows its reason in a small bubble right
under that button: absolutely placed (no layout shift), inside the viewport and below the top bar, clamped
horizontally (no horizontal scroll), on every tab. Reuse `anchoredPlace.ts` if it fits.
- Announced once per press (a status role or the existing describedby read; no double announcement), keeps
`aria-describedby`; axe passes while open.
- Closes when the hold ends, on a tab change, when the focus leaves the button (keyboard), on a press elsewhere
(touch, mouse) and on Escape. Escape order: with the bubble open, Escape closes the bubble first; the next Escape
does what it does today (creation asks, pending work drops). Test it.
- It does not cover the control its text names when that control is on screen (for « annulez-la avec Défaire » the
bubble is under « Refaire », not over « Défaire »).
- Unit: per press kind, the other-tab case flipped (the bubble shows on every tab), the closing rules, Escape order.
e2e at 1 024 × 768, 1 180 × 820, 1 280 × 800: bubble box in viewport and below the bar with the French text,
`expectNoShift`, `scrollWidth` unchanged, axe open.
- [ ] Steps: failing tests, implement, gates, commit `feat(editor): the held reason shows in a bubble by its button`.
### Task 19: Catalogue-integrity 4 → 6, non-destructive diagnosis (D5)
- Read-only SELECT counts of published sheets and versions now against the 426 versions recorded on 2026-11-18.
- One head run of `catalogue-integrity.spec.ts` alone, `--workers=1`.
- Only if that run fails all six: one baseline run at 56c75b1 the same way, straight after, in a git worktree
under `.superpowers/`, removed with `git worktree remove` (never by hand). No env file copied.
- Report « attributed » or « not attributed » with the figures; nothing deleted, nothing reset.
### Task 20: Documents and gates (rev 5)
- `V1-2-6_OWNER_TRIAL.md` §4.17: D1 to D5 recorded as decided; the bubble and the pinned drawing steps; the
« Choix visibles » list updated (bubble closing rules, Escape order, pinned column, aside under the strip).
- `V1-2-6_UX_TESTS.md`: the environment failures per D5 (named with their evidence, not resolved, not all formally
independent of U2), the Task 19 result; gate figures.
- Gates on the final code: check:all, the shell suite without editor-equine, both measures, a fresh verifier, a
fresh security auditor on the rev 5 delta. Then STOP for the owner's db:trial run.