From 8c5a8871e5bdb06a4534528235592402cfa66ff5 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 17 Nov 2026 16:16:07 +0100 Subject: [PATCH] docs(docs): U2 plan rev 2 final pass, D2 added --- .claude/tasks/plans/2026-11-17-v1-2-6-u2.md | 177 ++++++++++++++------ 1 file changed, 129 insertions(+), 48 deletions(-) diff --git a/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md b/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md index 9751dbaa..9246bd54 100644 --- a/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md +++ b/.claude/tasks/plans/2026-11-17-v1-2-6-u2.md @@ -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.