docs(docs): U2 plan rev 2 final pass, D2 added

This commit is contained in:
bchanot committed 2026-11-17 16:16:07 +01:00
1 parent 31d0c415ec
commit 8c5a8871e5
1 file changed
+129 -48
+129 -48
View File
@@ -3,7 +3,7 @@
> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development to implement this plan task-by-task.
> Steps use checkbox (`- [ ]`) syntax for tracking.
**Status:** rev 2, NOT validated. Waits for the owner's approval and the answer to D1. No U2 code before both. DEV
**Status:** rev 2, NOT validated. Waits for the owner's approval and the answers to D1 and D2. No U2 code before both. DEV
unchanged, no merge.
Rev 2 is rev 1 plus three fresh challenges of 2026-11-17: correctness FATAL(9), robustness FATAL(9), simplicity
@@ -137,7 +137,7 @@ to verify. The executor writes the JSX under TDD against the boards.
| `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** | — |
| `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 |
@@ -155,8 +155,33 @@ to verify. The executor writes the JSX under TDD against the boards.
|---|---|---|---|---|
| D1 | `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. |
Conditional, Task 8: if neither loupe technique keeps a smooth drag on the editor itself, the owner chooses between a
loupe without the drawing (outline and handles only) and no loupe. No question before then.
### D2: « + » on segments too short for the finger
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
@@ -258,8 +283,10 @@ and a stray tap never discards a creation.
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, a redraw or a pending keyboard series is NOT a creation: Back, a tab or a view change cancels it
silently, the stored shape staying. These are not history entries (orientation).
- A move mode or a redraw is NOT a creation: Back, a tab or a view change cancels it silently, and the stored shape
stays. These are not history entries (orientation).
- 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
@@ -283,6 +310,25 @@ The editor turns read-only on a crossing below 1 024 px, a refusal or a refresh.
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-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
@@ -301,9 +347,7 @@ The cap stays at 8 MiB: about 47 equine steps, written in UX_TESTS in place of
`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 (BDR-043): the geometry arithmetic of `polygonEdit.ts` and `pointSize.ts` is interaction-rate
preview math. UX plan §1.3 and §2 G, ratified at U0, place it in the page, and each result goes through
`sheet.edit` and the core's verdict. One row is added to the review's Part II exception table, class C.
- Rust by default: R-17.
### Undo and previews
@@ -690,9 +734,18 @@ Notes on the code above:
`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, `catalogue.spec.ts`. All green unchanged.
`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
@@ -755,7 +808,7 @@ Notes on the code above:
the given radius, R-10).
- Modify `uiState.ts` (`mode: { kind: 'move'; target: 'shape' | { vertex: number } } | null`),
`useCanvasGestures.ts` (`drag_point`, `drag_mode`) and `deselect.ts` (the Escape listener calls `escapeAction`).
- Modify the properties panel: its numeric group goes, and the panel keeps its fields until Task 6.
- The properties panel keeps its numeric group until Task 5, where polygons get their handles.
- Doc `docs/ANNOTATION-RENDERING.md` « Editor overlay » FIRST.
**Interfaces:**
@@ -878,6 +931,10 @@ How the pieces work:
- `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:**
@@ -960,8 +1017,8 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
- The veil ignores clicks when anchored (R-6).
- `ConfirmDialog.tsx`: `body` optional.
- Navigation and history:
- `navigation.ts`: `EditorView.annotation: { id: string } | { create: NewKind } | null`, on tab `annotations`
only.
- `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
@@ -969,9 +1026,12 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
- `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 twin renders `AnnotationReadBody` and keeps `SelectionTag`.
- 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.
@@ -979,6 +1039,24 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
**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:
@@ -1001,8 +1079,6 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
- 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.
- `{ create }` is a form: dropped on reload, and treated as vanished on any restore without a pending creation in
the work store.
- [ ] **Step 1: failing tests.**
- `ui.Dialog.test.tsx`:
@@ -1011,7 +1087,11 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
- 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, `{ create }` without a creation.
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.
@@ -1045,14 +1125,16 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
**Files:**
- Create `CreationDialog.tsx`, mounted beside `EditOnly` with `readOnly`. Delete `CreationPanel.tsx`.
- `creation.ts` (`missingFields` replaces `formProblem`), `creationAttempt.ts`, `missingFields.ts` (below),
`CreationFields.tsx` (field order: region, then zone), `usePlacement.ts`, and `KeyboardAdd.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:
- `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.
- `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`.
- `AdminSheetDraftRoute.tsx` and `SignOutButton.tsx`: `leaveGuardArmed(state) || holdsCreationWork(work)`.
- `HistoryButtons.tsx` and `useUndoShortcuts.ts`: inactive during a creation.
@@ -1060,23 +1142,6 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
- The dimming: a host attribute `data-creating` and the CSS of the other annotations. Doc first.
- i18n.
```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
}
```
Behaviour:
@@ -1089,8 +1154,9 @@ Behaviour:
- **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.** It asks with typed text (`DiscardConfirm`), then clears the creation. The focus goes to the tool
button.
- **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.
@@ -1099,9 +1165,8 @@ Behaviour:
- **Read-only flip (R-14).** The dialog stays with its form and Créer is disabled.
- [ ] **Step 1: failing tests.**
- 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 tab: each behaviour above. « Créer » without a laterality shows only « Choisissez une latéralité. » and
- 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. Move mode and
@@ -1147,10 +1212,12 @@ Behaviour:
- Page scroll over the canvas without a selection keeps working.
- Every handle hit circle is at least 44 px.
- `expectNoShift` at the hint.
- E2E smoothness on the editor itself: Chromium touch at 1 180 px, CPU ×4 (CDP
`Emulation.setCPUThrottlingRate`), a 2 s vertex drag on the equine main view. The p95 of pointermove to next
frame is under 16 ms, loupe included. If technique A fails and B passes, STOP for the conditional owner
decision.
- 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.
- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** gates.
- [ ] **Step 5:** commit `feat(editor): two-finger pan, touch hint, loupe, touch-sized handles`.
@@ -1221,7 +1288,7 @@ Behaviour:
| 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 | Accepted: treated as vanished (Task 6) |
| 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)
@@ -1234,7 +1301,7 @@ Behaviour:
| 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 }` | Accepted (as correctness 18) |
| 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 |
@@ -1264,3 +1331,17 @@ Behaviour:
| 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.