docs(docs): U2 plan rev 3 with owner answers, implementation contract, BDR-123

This commit is contained in:
bchanot committed 2026-11-17 16:24:26 +01:00
1 parent 838ae42a51
commit 56c75b12ef
4 files changed
+386 -27

No files matched your search

+109 -26
View File
@@ -1,10 +1,14 @@
# U2 Direct Manipulation of Annotations Implementation Plan (V1-2.6), rev 2
# 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:** 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.
**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.
@@ -153,9 +157,9 @@ to verify. The executor writes the JSX under TDD against the boards.
| # | Question | Recommendation | Alternative | Cost if wrong |
|---|---|---|---|---|
| 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. |
| 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
### 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.
@@ -283,8 +287,17 @@ 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 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 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.
@@ -293,8 +306,11 @@ and a stray tap never discards a creation.
- 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 (redo, reload, recovery, a save refresh) drops every stale preview and the chosen
vertex.
- 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
@@ -302,7 +318,8 @@ The editor turns read-only on a crossing below 1 024 px, a refusal or a refresh.
- An open properties or creation dialog stays open in read-only form: a notice, inputs disabled, the draft kept, the
save disabled.
- Move modes and previews are dropped.
- 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.
@@ -319,6 +336,17 @@ The cap stays at 8 MiB: about 47 equine steps, written in UX_TESTS in place of
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:
@@ -359,6 +387,8 @@ These new modules stay in TypeScript. Each is listed in the review's Part II exc
### 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.
@@ -673,16 +703,30 @@ export interface Creation {
/** 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, preview: null, chosen: null }))
export const useAnnotationWork = create<Work>(() => ({
creation: null,
mode: null,
preview: null,
chosen: null,
}))
/** R-12: a creation holds work once a shape exists or a field is typed. */
export function holdsCreationWork(work: Work): boolean {
return work.creation !== 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. */
@@ -696,10 +740,10 @@ export function dropStale(text: string): void {
Notes on the code above:
- A creation always holds its shape, so `holdsCreationWork` is the existence of the creation. The tool alone, before
- 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 stays in `ui.tracing`
(target `replace`): it is not a creation (R-12).
- 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
@@ -806,9 +850,14 @@ Notes on the code above:
- `moveStep(frame, big)`.
- Modify the callers `creation.ts` (`pendingForClick`, `keyboardPending`) and `correction.ts` (the test against
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`).
- 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:**
@@ -909,6 +958,11 @@ How the pieces work:
- 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.
@@ -997,6 +1051,10 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
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).
@@ -1015,7 +1073,6 @@ export function showsInsert(segmentPx: number, hitRadiusPx: number): boolean {
- 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).
- `ConfirmDialog.tsx`: `body` optional.
- Navigation and history:
- `navigation.ts`: `EditorView.annotation: { id: string } | null`, on tab `annotations` only. The creation
dialog is NOT a layer (Task 7).
@@ -1105,6 +1162,8 @@ export function missingFields(kind: NewKind, form: CreationForm): MissingField[]
- « 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.
@@ -1129,14 +1188,14 @@ export function missingFields(kind: NewKind, form: CreationForm): MissingField[]
and `KeyboardAdd.tsx`.
- `workStore.ts`: `creation` holds the pending shape and the form across « Replacer le point » and « Reprendre le
tracé ».
- The drawing guard:
- 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`.
- `AdminSheetDraftRoute.tsx` and `SignOutButton.tsx`: `leaveGuardArmed(state) || holdsCreationWork(work)`.
- `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.
@@ -1169,8 +1228,10 @@ Behaviour:
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
redraw are cancelled silently by a tab change and by Back (R-12).
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`
@@ -1248,12 +1309,20 @@ Behaviour:
through its sandbox alias).
- [ ] **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 demo script in `docs/development/V1-2-6_OWNER_TRIAL.md` U2, on the sandbox demo sheet.
- [ ] **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.
- [ ] **Step 6:** STOP for the owner's checkpoint (mouse and tablet). Capitalize per the closing flow.
- 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
@@ -1345,3 +1414,17 @@ Behaviour:
- 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).