1700 lines
106 KiB
Markdown
1700 lines
106 KiB
Markdown
# 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.
|