docs(docs): U2 plan rev 3 with owner answers, implementation contract, BDR-123
This commit is contained in:
1 parent
838ae42a51
commit
56c75b12ef
4 files changed
+386
-27
No files matched your search
@@ -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).
|
||||
Reference in new issue
Block a user