docs(docs): U2 rev 4, owner corrections before the trial

This commit is contained in:
bchanot committed 2026-11-19 00:45:08 +01:00
1 parent 1f2485ecb8
commit 816d0f4f9a
3 files changed
+259 -2

No files matched your search

+174
View File
@@ -1450,3 +1450,177 @@ Behaviour:
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`.
### 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.