chore(memory): journal — ship-feature U2 trial adjustments, plan + contract

This commit is contained in:
bchanot committed 2026-11-20 16:39:08 +01:00
1 parent 007d9d419e
commit fef5f126b3
4 files changed
+503

No files matched your search

@@ -0,0 +1,395 @@
# U2 trial adjustments — implementation plan (rev 2, after the three-lens challenge)
> For agentic workers: executed by subagent-driven-development, one fresh implementer per task, tasks strictly in order (the shell suite owns one sandbox and port 5192). Steps use `- [ ]`.
**Goal:** the « Ajouter … » buttons arm their tool on a pointer press (keyboard keeps the centre path), and the coarse-pointer handles get lighter marks with a « − » bubble whose hit area never meets a shown « + » hit area.
**Architecture:** item 1 adds `armedFrom` to the editor UI state and a pointer/keyboard split in `KeyboardAdd`; item 2 adds one pure TS placement function (`removeBubble.ts`) called by `ZoneHandles`, bounded by the visible part of the drawing, plus new coarse mark sizes. TS, not Rust: placement runs in the render path, where the core is never called (CLAUDE.md « no call in a render path »); it sits beside `polygonEdit.ts`/`showsInsert`, already TS.
**Tech stack:** React 19, TypeScript strict, Tailwind v4, Zustand, vitest + happy-dom + @testing-library/user-event 14.6.1, Playwright 1.64.1 (Chromium) against `pnpm db:sandbox`.
**Spec:** contract `/home/bchanot/Documents/faunosteo-v1-2/.claude/tasks/contracts/2026-11-20-u2-trial-adjustments-1259.md` (REQUEST, CLARIFICATIONS `[gated 2026-11-20]`, criteria 1-10).
## Global constraints
- Repo root: `/home/bchanot/Documents/faunosteo-v1-2` (ABSOLUTE; the session cwd is another checkout). Branch `feature/v1-2-anatomical-sheets`; commit in place; never merge, never `gitflow finish`, no `gitflow.sh start`.
- Review and gate range: `70d4addc..HEAD` (never `develop..HEAD`: the whole V1-2 branch).
- Commits: Conventional Commits, subject ≤ 72 chars, scopes `editor`, `tests`, `docs`; no attribution lines. Every commit leaves `pnpm test:run` green (commits auto-push).
- TS line limit 100 (project exception). Neighbouring code style: small functions (≤ 25 logic lines), JSDoc on exports, comments say why.
- i18n: three new screen-reader strings `editor.annotations.armed.{point,zone,detail_trigger}` (Task 6 Step 3b), in `fr.ts` and `en.ts`, plus a dictionary test for the template keys (LRN-137).
- Coarse sizes (owner 2026-11-20): vertex 14 px (chosen vertex 18 px: `vertex/2 + 2` radius, unchanged rule), « + » 18 px, « − » mark 32 × 26 px drawn centred in an unchanged 44 × 36 px hit rectangle; hit radius 22 px unchanged (criterion 18, D2 threshold `2·hit`, R-18 hint unchanged). Fine sizes unchanged: vertex 12, « + » 16, hit 10, bubble 28 × 22 (mark = hit).
- Bubble search (owner-gated, 30° steps): turns 0, ±30°, … ±180° around the open direction, then 8, 16, 24, 32 px farther out. Measured before this plan on the six equine main polygons, widths 621/679/694, zoom 1 to 6 by 0.01: 0 overlaps with shown « + » hit areas, 24 px extra at most.
- Bubble precedence (stated in the doc): on screen first. Inside the part shown, the hit rect keeps clear of every shown « + » hit circle when such a place exists; when the shown part leaves none, the bubble stays on screen and stays UNAMBIGUOUS: no shown « + » centre inside its hit rect, its own centre inside no « + » hit circle (owner precision). When the chosen vertex itself is off screen, the screen bound is dropped (bounds = frame).
- Stored geometry never depends on the pointer type (`pointSize.ts`, inserted midpoints untouched).
- Tests: `pnpm --filter @faunosteo/app exec vitest run <files>`; e2e only `pnpm db:sandbox e2e-shell e2e/shell/<name>.spec.ts [--grep …] --workers=2` — every spec by its FULL path, never a directory or a pattern (docs/development/BROWSER_TESTS.md:157-159) on the running sandbox (never `up fresh`, never a reset, never DEV, never `db:trial`, never `editor-equine.spec.ts`). Check the sandbox first (`docker ps --format '{{.Names}}' | grep dbsandbox`); down → STOP, BLOCKED.
- The full shell run (≈ 28 min) is the main loop's, in the background, after Task 7; implementers run single specs only.
- Never loosen or delete an existing assertion; a test that changes its press keeps its intent.
- Owner trial pickup: `pnpm db:trial app` is the Vite dev server on this working tree; a page reload picks up the commits (restart `pnpm db:trial app` if it is stopped).
## Review focus
1. A vertex near the edge of the visible part of the drawing (zoomed): the bubble stays on screen, never clipped by the canvas box (Task 3 « window » test, Task 7 e2e).
2. A zero-length neighbour (duplicate points): the direction comes from the nearest distinct neighbour; the centre is finite and criterion (a) holds (Task 3 « degenerate » test).
3. The disarming press while a creation is started (tracing, or dialog hidden by « Replacer le point »): « Abandonner la création ? » comes first, nothing dropped silently (Task 6 test 5).
4. A double-click on an add button: the tool stays armed (Task 6 test 7).
5. A redraw in progress lends the zone tool: « Ajouter une zone » must not show armed, and a press arms a new zone behind the guard (Task 6 test 8). Residual, not testable here: assistive technologies that activate with `detail ≥ 1` arm instead of placing at the centre (Task 8 records it).
---
### Task 1: documents before the rendering change (U2 criterion 21)
**Files:**
- Modify: `docs/ANNOTATION-RENDERING.md` (« Editor overlay », about :170-199)
- Modify: `.claude/tasks/contracts/2026-11-17-v1-2-6-u2-implementation.md` (append « Owner decisions 2026-11-20 (addendum 3) »)
- Modify: `docs/design/v1-2-6-u2/REVUE.md` (append « Amendement propriétaire 2026-11-20 », French like the file)
- [ ] **Step 1: size table** (replace the table and add the note below it):
```markdown
| Device | Vertex (chosen) | « + » | « − » bubble (drawn / hit) | Hit radius |
|---|---|---|---|---|
| Coarse (finger) | 14 px (18 px) | 18 px | 32 × 26 / 44 × 36 px | 22 px |
| Fine (mouse, pen) | 12 px (16 px) | 16 px | 28 × 22 / 28 × 22 px | 10 px |
The coarse marks were lightened after the owner's tablet trial (2026-11-20); every
hit area kept its size, so the touch targets, the « + » threshold and the zoom hint
are unchanged.
```
- [ ] **Step 2: bubble paragraph.** Replace « a rounded rectangle drawn just above that vertex » with the guarantees (not the search constants):
```markdown
the « − » bubble of the chosen vertex, a rounded rectangle placed away from the
vertex's two segments, on the side of the larger angle they make, so the « + »
of those segments are never in its way. Its hit rectangle never meets the
vertex's own hit circle nor the hit circle of a shown « + »; when room allows
it also keeps clear of the other vertices' hit circles. It always lies inside
the drawing and, while its vertex is on screen, inside the part shown; when
that part leaves no place clear of the « + », it stays on screen with no
« + » centre under it and its own centre under no « + ». Its place is computed
at each render (zoom, pan, drag preview), never stored.
```
And amend « No handle covers the polygon's interior » to « No handle covers the polygon's interior, except the « − » bubble of a vertex whose larger angle is inside (a re-entrant corner) ».
- [ ] **Step 3: U2 contract addendum 3.** Append:
```markdown
### Owner decisions 2026-11-20 (addendum 3)
- Criterion 32: validated by the owner on the trial build; REOPENED by the owner (2026-11-20) until re-verified on the final code (the 44 px add buttons move the pinned thresholds): short windows and several rows of view chips (plan Task 7 Step 4b).
- Criterion 12 reworded: « The add buttons: a pointer press (click or tap) arms their tool, the
shape is placed or traced on the drawing and the dialog opens itself; a keyboard press (Enter,
Space) places the shape at the centre and opens the dialog; a second single pointer press on an
armed button disarms it, behind the R-12 guard; a double-click leaves it armed. »
- Coarse marks lightened (vertex 14, « + » 18, « − » 32 × 26 drawn in a 44 × 36 hit); criterion 18
unchanged; the « − » bubble placed on the open side of its vertex, clear of shown « + » hit
areas, on screen. Add buttons 44 px tall below 1 280 px; the pinned column budget follows.
- Contract of the change: `.claude/tasks/contracts/2026-11-20-u2-trial-adjustments-1259.md`.
```
- [ ] **Step 4: REVUE amendment** (French):
```markdown
## Amendement propriétaire 2026-11-20 (essai tablette)
- Tablette : sommets 14 px (18 px choisi), « + » 18 px, bulle « − » dessinée 32 × 26 px ; les
zones tactiles restent 44 px (cercles) et 44 × 36 px (bulle). Remplace les tailles visibles de
la planche 13.
- La bulle « − » n'est plus toujours au-dessus du sommet (planche 05) : elle se place du côté
libre du sommet, à l'écart de ses segments et des « + » affichés, toujours visible à l'écran.
- « Ajouter un point / une zone / un accès » : un clic ou un toucher arme l'outil (bouton
enfoncé, un second appui le désarme) ; Entrée ou Espace pose au centre. 44 px de haut sous
1 280 px.
```
- [ ] **Step 5: commit** `docs(docs): U2 trial amendments before the handle change`.
### Task 2: coarse mark sizes and the drawn bubble inside its hit rectangle
**Files:**
- Modify: `apps/app/src/editor/annotations/handleSize.ts`
- Modify: `apps/app/src/components/editor/annotations/ZoneHandles.tsx:186-247` (`Remove`)
- Modify: `.claude/tasks/TODO.md` (the line citing the `handleSize.ts` `shortcut:` — check it off: « settled by the owner trial 2026-11-20 »)
- Test: `apps/app/tests/unit/annotations.handleSize.test.ts` (new)
**Interfaces — Produces:** `HandleSizes` gains `bubbleMark: { w: number; h: number }` (drawn size); `bubble` stays the hit rectangle. `deviceSizes` exported.
- [ ] **Step 1: failing test**
```ts
import { afterEach, describe, expect, it, vi } from 'vitest'
import { deviceSizes } from '@/editor/annotations/handleSize'
const coarse = (matches: boolean) =>
vi.spyOn(window, 'matchMedia').mockReturnValue({ matches } as MediaQueryList)
afterEach(() => vi.restoreAllMocks())
describe('handle sizes (owner trial 2026-11-20)', () => {
it('a finger gets lighter marks and unchanged hit areas', () => {
coarse(true)
expect(deviceSizes()).toEqual({
vertex: 14,
insert: 18,
hit: 22,
bubble: { w: 44, h: 36 },
bubbleMark: { w: 32, h: 26 },
})
})
it('a mouse keeps its sizes, the mark filling its hit rectangle', () => {
coarse(false)
expect(deviceSizes()).toEqual({
vertex: 12,
insert: 16,
hit: 10,
bubble: { w: 28, h: 22 },
bubbleMark: { w: 28, h: 22 },
})
})
})
```
- [ ] **Step 2:** run `pnpm --filter @faunosteo/app exec vitest run tests/unit/annotations.handleSize.test.ts` → FAIL.
- [ ] **Step 3: implement** `handleSize.ts`: `bubbleMark` in the interface (JSDoc « The « − » bubble as drawn, centred in its hit rectangle »), `FINE.bubbleMark = { w: 28, h: 22 }`, `COARSE = { vertex: 14, insert: 18, hit: 22, bubble: { w: 44, h: 36 }, bubbleMark: { w: 32, h: 26 } }`, export `deviceSizes`, delete the `shortcut:` comment.
- [ ] **Step 4:** `Remove` draws, at one centre, the hit rect (`sizes.bubble`, `fill="transparent"`, `data-handle`, `pointer-events-auto`, cursor classes; LRN-103) and the visible mark (`sizes.bubbleMark`, `rx={6 * unit}`, the fill), the « − » path across the mark (`0.3·w` to `0.7·w` of the mark), the focus ring around the mark (+3 units, `rx 8·unit`). In this task the centre stays where the hit rect's centre is today: `cx = at[0]`, `cy = at[1] - (sizes.vertex / 2 + 6) * unit - (sizes.bubble.h * unit) / 2` (Task 4 replaces it). `role`, `aria-*`, `data-focus-target`, `onKeyDown` unchanged.
- [ ] **Step 5:** run the new test + `tests/unit/editor-zone-edit.test.tsx tests/unit/annotations.press.test.ts` → PASS; `pnpm typecheck`.
- [ ] **Step 6: commit** `feat(editor): lighter coarse handle marks, hit areas unchanged`.
### Task 3: pure placement of the « − » bubble
**Files:**
- Create: `apps/app/src/editor/annotations/removeBubble.ts`
- Test: `apps/app/tests/unit/annotations.removeBubble.test.ts` (new)
**Interfaces — Produces:**
```ts
export interface BubbleScene {
points: readonly Point[]
/** Segment i (vertex i to the next) shows its « + » (ZoneHandles.shownInserts). */
inserts: readonly boolean[]
/** Drawing units per CSS px. */
unit: number
sizes: HandleSizes
/** Where the bubble may lie, in drawing units: the frame ∩ the part on screen; null: no bound. */
bounds: Frame | null
/** The whole frame: the bound used when the chosen vertex is off screen; null: none. */
frame: Frame | null
}
/** The centre of the « − » bubble of vertex `chosen`, in drawing units. */
export function removeBubbleCentre(scene: BubbleScene, chosen: number): Point
/** Signed px gap between the bubble's hit rect centred at `centre` and a hit circle at `other` (both px). */
export function bubbleClearance(centre: XY, other: XY, sizes: HandleSizes): number
/** The part of the frame on screen (drawing units), from the framing; null when the box is 0 × 0. */
export function visibleBounds(frame: Frame, box: { w: number; h: number }, framing: { x: number; y: number; scale: number }): Frame | null
```
- [ ] **Step 1: failing tests.** Read the draft like `tests/unit/annotations.pointSize.test.ts:26-31` (`readFileSync` of `supabase/seed/anatomical-sheets/equine/draft/document.json`). The main view's `view_box` is null: read the frame from the `viewBox` of `supabase/seed/anatomical-sheets/equine/draft/assets/horse.svg` with a regex (today `0 0 2073.4 1629.4`). Coarse sizes from `deviceSizes()` with `matchMedia` mocked `matches: true`. `inserts = points.map((p, s) => showsInsert(segPx(p, points[(s + 1) % n]), sizes.hit))` with `showsInsert` from `polygonEdit.ts`. For every polygon annotation of view `main` (six: caudal, sacral, lumbar, thoracic, cervical, head-trigger), widths W 621, 679, 694 and zoom from 1 to 6 by 0.05 (`unit = 1 / (Math.min(W / frame.w, (W * 0.75) / frame.h) * zoom)`, `bounds = frame`), for every vertex v chosen, `c = removeBubbleCentre(...)` and, in px (drawing units / unit):
- (a) THE criterion (owner precision: real hit areas): `bubbleClearance(c, mid(s), sizes) >= 0` for every segment s with `inserts[s]`;
- (c) `bubbleClearance(c, vertex v, sizes) >= 0` (its own vertex);
- (d) the hit rect inside `bounds`;
- one line of sanity: `c` differs from every shown « + » centre.
Focused tests:
- **control (red-first evidence):** the pre-change centre `[vx, vy - (9 + 6 + 18) * unit]` (old coarse vertex 18, offset `vertex/2 + 6`, half the 36 px height) fails (a) for vertex 2 of `thoracic` at zoom 2.25, W 679 (measured: −22 px);
- **window:** a square `[[0,0],[100,0],[100,100],[0,100]]`, unit 1, fine sizes, `bounds = { x: 0, y: 0, w: 60, h: 60 }`, `frame` 0 0 100 100 (as if zoomed on the top-left part): the bubble of vertex 0 lies inside those bounds; the bubble of vertex 2 (off screen) is not forced into them;
- **panned sweep (the owner's zoomed case):** on the six equine polygons, W 679, zooms 2.25, 3.375 and 5.0625, for every vertex v and every pan that puts v at screen x ∈ {0, 20, 60, W/2, W−60, W−20, W} × y ∈ {0, 20, 60, H/2, H−60, H−20, H} (H = 0.75·W; 9 261 placements; `bounds = visibleBounds(frame, {w: W, h: H}, framing)` — write `visibleBounds` in this task, Task 4 only wires it): the hit rect is inside `bounds` whenever an inside candidate exists, and the choice is unambiguous (no shown « + » centre inside it, its centre farther than `hit` from every shown « + » centre) except in at most 3 placements — measured on the prototype 2026-11-20: 3 of 9 261 have no place both on screen and unambiguous, all with the vertex at a window corner; print each exception (polygon, vertex, zoom, screen position) and the count meeting (a) (prototype: 8 525);
- **vertex rung:** a vertex whose open direction points straight at another vertex 40 px away (build a 5-point polygon so that the base candidate's hit rect overlaps that vertex's hit circle while a 30° turn does not): the chosen centre keeps `bubbleClearance >= 0` to that vertex;
- **degenerate:** points `[[10,10],[10,10],[60,10],[60,60]]`, unit 1, fine sizes, bounds `{0,0,100,100}`: every centre is finite and (a) holds.
- [ ] **Step 2:** run → FAIL (module missing).
- [ ] **Step 3: implement** `removeBubble.ts` (each function ≤ 25 logic lines):
```ts
import type { Point } from '@faunosteo/core-wasm/types'
import type { Frame, XY } from './frame'
import type { HandleSizes } from './handleSize'
/** CSS px kept between the bubble's hit rect and its own vertex's hit circle. */
const GAP_PX = 2
/** Turns tried around the open direction (owner: 30° steps): 0, +30, −30, … ±180. */
const TURNS = [0, ...[1, 2, 3, 4, 5].flatMap((i) => [i, -i]), 6].map((i) => (i * Math.PI) / 6)
/** CSS px tried farther out when no turn is clear (measured: 24 px suffice on the equine sheet). */
const FARTHER_PX = [0, 8, 16, 24, 32]
export function bubbleClearance(centre: XY, other: XY, sizes: HandleSizes): number {
const dx = Math.max(Math.abs(other.x - centre.x) - sizes.bubble.w / 2, 0)
const dy = Math.max(Math.abs(other.y - centre.y) - sizes.bubble.h / 2, 0)
return Math.hypot(dx, dy) - sizes.hit
}
```
- `neighbour(points, chosen, step)`: walk `step` (−1 or +1) from `chosen` to the first point distinct from it; none → null.
- `openDirection`: with both neighbours, `ta`, `tb` their `atan2` from the vertex, `gap = ((tb − ta) mod 2π + 2π) mod 2π`, `bisector = ta + gap/2`, return `gap > π ? bisector : bisector + π`; one neighbour → its angle + π; none → `−π/2`.
- Candidates in px, `extra` of `FARTHER_PX` outer × `turn` of `TURNS` inner: `θ = open + turn`, `d = hit + (w/2)|cosθ| + (h/2)|sinθ| + GAP_PX + extra` (keeps the rect off the vertex's own hit circle), `centre = vertexPx + d·(cosθ, sinθ)`. Score: `inside` (hit rect within `bounds`, back in drawing units; true when null), `insertGap` (min `bubbleClearance` to shown « + » midpoints; `Infinity` if none), `vertexGap` (min to other distinct vertices; `Infinity` if none). `unambiguous` = no shown « + » centre inside the hit rect AND the bubble centre farther than `hit` from every shown « + » centre. When the chosen vertex lies outside `bounds`, use the frame (the scene's `frame`, see Interfaces) as bounds. Choose: first with `inside && insertGap >= 0 && vertexGap >= 0`; else first with `inside && insertGap >= 0`; else the `inside && unambiguous` one with the largest `insertGap`; else the `inside` one with the largest `insertGap`; else the first candidate. Return in drawing units.
- [ ] **Step 4:** run → PASS. If (a) fails anywhere, report polygon, vertex, W and zoom; do not relax it.
- [ ] **Step 5: commit** `feat(editor): place the « − » bubble on the open side of its vertex`.
### Task 4: wire the placement, bounded by the part on screen
**Files:**
- Modify: `apps/app/src/components/editor/annotations/ZoneHandles.tsx` (`Scale` gains `bounds: Frame | null` and `frame: Frame | null`; `shownInserts` takes `Pick<Scale, 'unit' | 'sizes'>`; `Remove` takes `centre: Point`; `ZoneHandles` computes `removeBubbleCentre({ points, inserts, unit, sizes, bounds, frame }, chosen)` with the `inserts` it already has)
- Modify: `apps/app/src/components/editor/annotations/HandleLayer.tsx` (new prop `pan: { x: number; y: number }`; build ONE `scale = { unit, sizes, bounds, frame }` used by `ZoneHandles` and `useReportHidden`; `bounds` = the frame ∩ the visible window, null before layout)
- Modify: `apps/app/src/components/editor/annotations/AnnotationCanvas.tsx:114-118` (pass `pan: { x: framing.x, y: framing.y }` beside `scale`)
- Test: `apps/app/tests/unit/editor-zone-edit.test.tsx` (one test), `apps/app/tests/unit/annotations.removeBubble.test.ts` (one test for `visibleBounds`)
The visible window: the layer is the canvas box, transformed by `translate(x px, y px) scale(s)` from its top-left (`origin-top-left`, `transformOf` in `catalogue/framing.ts`); the box clips (`overflow-hidden`). A layer px `p` shows at `x + s·p`, so the visible layer px span `[−x/s, (W − x)/s] × [−y/s, (H − y)/s]`. Layer px → drawing units through the `meet` fit of the viewBox: `base = min(W / frame.w, H / frame.h)`, offsets `ox = (W − frame.w·base)/2`, `oy = (H − frame.h·base)/2` (xMidYMid, the core's default ratio; extend the existing `shortcut:` above `unitsPerPx` to name this function too), drawing = `frame.x + (p − o)/base`. `visibleBounds` (written in Task 3, exported from `removeBubble.ts`) implements this, intersected with the frame. Known limit, recorded in Task 8: the canvas box is `overflow-hidden`, so a script or a focus could scroll it; the framing does not see such a scroll (pre-existing; pointer choices use `preventScroll`).
- [ ] **Step 1: failing tests:** (1) in `annotations.removeBubble.test.ts`: `visibleBounds({x:0,y:0,w:100,h:100}, {w:100,h:100}, {x:-50,y:-50,scale:2})` → `{ x: 25, y: 25, w: 50, h: 50 }`; at fit → the frame (move this test to Task 3 if Task 3 already wrote it). (2) in `editor-zone-edit.test.tsx`, a triangle `[[20,20],[80,20],[50,60]]` (unit 1 in the harness, fine sizes, frame 0 0 100 100): choose its lowest vertex (index 2) and assert the remove `[data-handle]` rect's `y` is BELOW the vertex (`y > 60`) — impossible with the always-above placement. Reuse the file's render/select helpers.
- [ ] **Step 2:** run → FAIL.
- [ ] **Step 3:** implement the wiring; `Remove` positions both rects from `centre`.
- [ ] **Step 4:** run `tests/unit/editor-zone-edit.test.tsx tests/unit/annotations.removeBubble.test.ts tests/unit/annotations.press.test.ts` → PASS; `pnpm typecheck && pnpm lint`.
- [ ] **Step 5: commit** `feat(editor): the « − » bubble follows the open side, on screen`.
### Task 5: migrate the unit tests that used a pointer press for the centre path (before the change)
**Files (keep every assertion):**
- `apps/app/tests/unit/editor-annotations-tab.test.tsx` :235, :271, :299, :684, :867, :1353
- `apps/app/tests/unit/editor-creation-dialog.test.tsx` :170, :226, :524, :761
- `apps/app/tests/unit/editor-keep-alive.test.tsx` :559
- `apps/app/tests/unit/editor-no-loss.test.tsx` :226
- `apps/app/tests/unit/editor-point-edit.test.tsx` :508
- `apps/app/tests/unit/editor-sections.test.tsx` helper `addPoint` :192-199
- Create (unless a shared editor helper module fits, e.g. `tests/helpers/editorHarness.ts`): `apps/app/tests/helpers/addByKeyboard.ts`
- [ ] **Step 1:** Enter on these buttons already gives the centre path today, so this migration is green before AND after Task 6. Run the files → green (baseline).
- [ ] **Step 2:** the helper:
```ts
import type { UserEvent } from '@testing-library/user-event'
/** C7: « Ajouter … » by keyboard (Enter), the shape at the centre with its dialog at once. */
export async function addByKeyboard(user: UserEvent, button: HTMLElement) {
button.focus()
await user.keyboard('{Enter}')
}
```
- [ ] **Step 3:** each `user.click(<add button>)` that needs the centre placement becomes `await addByKeyboard(user, <add button>)`. `editor-point-edit.test.tsx:553` (`fireEvent.click`, detail 0) stays. `editor-zone-edit` I-3 is Task 6's. Do NOT touch the Findings tab presses (`editor.findings.add_zone`: editor-findings :258, :579; editor-finding-dialog :354, :375, :384; editor-no-loss :165).
- [ ] **Step 4:** `pnpm test:run` → green.
- [ ] **Step 5: commit** `test(tests): centre-path add presses go through the keyboard (C7)`.
### Task 6: « Ajouter … » arms its tool on a pointer press
**Files:**
- Modify: `apps/app/src/editor/annotations/uiState.ts` (export `TOOL_OF: Record<NewKind, ToolId>` = `{ point: 'point', zone: 'zone', detail_trigger: 'link' }` beside `ToolId`; `UiState.armedFrom: Creation['origin']`, initial `'tool'`; action `{ type: 'tool'; tool: ToolId; from?: 'add' }`; reducer `tool`: `armedFrom: action.from ?? 'tool'`; export `armedTool(state: Pick<UiState, 'tool' | 'tracing'>): ToolId` = `'select'` while `tracing?.target === 'replace'` (a redraw lends the zone tool), else `tool`)
- Modify: `apps/app/src/editor/annotations/workStore.ts:33` (`origin: 'tool' | 'add'`; the former `'keyboard'` is `'add'`: both mean « an add button started it »)
- Modify: `apps/app/src/editor/annotations/creationWork.ts:41-56` (`placePending` keeps `kept.origin` for a same-kind creation, as it keeps `form` and `resumed`)
- Modify: `apps/app/src/editor/annotations/usePlacement.ts` (both `creationStart(input, 'tool')` → `creationStart(input, input.ui.armedFrom)`; `TOOL_TARGET` stays)
- Modify: `apps/app/src/editor/annotations/creationAsk.ts` (import `TOOL_OF` from uiState, drop its own; `creationOpener`: origin `'add'` → `[data-add-kind="…"]`, else `[data-tool="…"]`)
- Modify: `apps/app/src/editor/annotations/useCreationFollow.ts:11` (import `TOOL_OF` from uiState, drop its own)
- Modify: `apps/app/src/components/editor/annotations/KeyboardAdd.tsx`
- Modify: `apps/app/src/components/editor/annotations/EditableAnnotations.tsx` (KeyboardAdd props; `addAtCentre` uses origin `'add'`; new `armFromAdd`)
- Modify: `apps/app/src/styles/index.css:63-104` (the pinned column budget, see Step 4)
- Modify: `apps/app/src/i18n/{fr,en}.ts` (three `editor.annotations.armed.*` keys, Step 3b)
- Modify: `apps/app/tests/unit/editor-zone-edit.test.tsx` I-3 :828-890
- Test: `apps/app/tests/unit/editor-add-buttons.test.tsx` (new)
Grep first: `grep -rn "'keyboard'" apps/app/src apps/app/tests` — every `'keyboard'` origin becomes `'add'` (test fixtures included).
- [ ] **Step 1: failing tests** in `editor-add-buttons.test.tsx` (render the annotations tab as `editor-annotations-tab.test.tsx` does; reuse its helpers and its way of clicking the drawing, see its « the Point tool » test at :1660):
1. `user.click(« Ajouter un point »)` → no creation dialog; the tool column's « Point » `aria-pressed="true"`; the button has `data-armed`; the strip reads « Ajouter un point » / « Cliquez dans le dessin pour placer le point ».
2. Then a click inside the drawing → « Nouveau point » dialog, ghost at the clicked place (not the frame centre).
3. Then « Abandonner » (and its confirmation if any) → focus on « Ajouter un point ».
3b. Armed by pointer, point placed, « Replacer le point » (dialog hidden), a second drawing click re-places it, then the strip's « Abandonner » and its confirmation → focus on « Ajouter un point ».
4. Armed, a second `user.click` on « Ajouter un point » → « Sélectionner » pressed, no `data-armed`.
5. `user.click(« Ajouter une zone »)`, one vertex traced, `user.click(« Ajouter une zone »)` again → « Abandonner la création ? » shows, the creation still exists; « Continuer » keeps it and the tool; again then « Abandonner » drops it and disarms.
6. Criterion 3, discriminating: `user.click(« Ajouter un accès »)` → no dialog and `data-armed` (fails on today's code); then « Sélectionner »; then focus « Ajouter un point » and `user.keyboard('{Enter}')` → dialog at once, ghost at the frame centre; « Abandonner » → focus back on « Ajouter un point »; focus « Ajouter un accès », `user.keyboard(' ')` → its dialog at once.
7. `user.dblClick(« Ajouter un point »)` → the tool stays armed (`data-armed`, « Point » pressed).
9. Screen-reader path (owner precision 2026-11-20): `user.click(« Ajouter un point »)` → the always-mounted `role="status"` region of the add row reads « Outil Point actif : … Entrée dans le dessin … »; then focus the drawing (`annotation-canvas`) and `user.keyboard('{Enter}')` → the « Nouveau point » dialog at once, ghost at the frame centre; « Abandonner » → focus back on « Ajouter un point ». Same for « Ajouter une zone » (centre triangle, its dialog). With the « Sélectionner » tool, Enter on the drawing creates nothing.
10. Dictionary: the three `editor.annotations.armed.*` keys exist in both dicts (template keys, LRN-137).
8. A stored zone selected, « Redessiner » started → « Ajouter une zone » has no `data-armed`; `user.click` on it → the redraw's guard (or its silent end when nothing is traced yet, as today for any tool press) and then the zone tool armed for a NEW zone (`data-armed`, no redraw tracing).
I-3 (`editor-zone-edit.test.tsx:828-890`): the landed click models a tap-synthesised click, `detail ≥ 1`: pass `detail: 1` to its `fireEvent.click` calls; the « goes through » cases assert `data-armed` on the button and `aria-pressed="true"` on « Point » instead of a creation; the « absorbed » cases assert no `data-armed` and `aria-pressed="false"` on « Point ».
- [ ] **Step 2:** run → FAIL.
- [ ] **Step 3: implement** `KeyboardAdd`:
```tsx
import type { MouseEvent } from 'react'
import Button from '@/components/ui/Button'
import type { NewKind } from '@/editor/annotations/creation'
import { TOOL_OF, type ToolId } from '@/editor/annotations/uiState'
import { useT } from '@/i18n/useT'
const KINDS: readonly NewKind[] = ['point', 'zone', 'detail_trigger']
/** The armed look of the tool column's pressed tool, border kept so nothing moves (A14). */
const ARMED =
'data-armed:border-[var(--color-ink)] data-armed:bg-[var(--color-ink)] data-armed:text-white'
/**
* The add row (owner trial 2026-11-20): one mouse click or tap (`detail` 1) arms the kind's
* tool, or disarms it when armed, so the shape is placed where the drawing is pressed and its
* dialog opens itself; the second click of a double-click (`detail` 2) changes nothing; Enter
* or Space (`detail` 0) keeps the C7 keyboard path: the shape at the centre of the frame at
* the A5 size, its dialog at once.
*/
export default function KeyboardAdd({ disabled, linkDisabled, armed, onAdd, onArm }: {
/** No measured frame, or no category: nothing can be placed. */
disabled: boolean
/** No detail view directly under this view: no link can be placed. */
linkDisabled: boolean
/** The armed tool (`armedTool`): its button shows pressed. */
armed: ToolId
onAdd: (kind: NewKind) => void
onArm: (kind: NewKind, button: HTMLElement) => void
}) {
const t = useT()
const press = (kind: NewKind) => (event: MouseEvent<HTMLButtonElement>) => {
if (event.detail === 0) onAdd(kind)
else if (event.detail === 1) onArm(kind, event.currentTarget)
}
return (
<div className="flex flex-wrap gap-2">
{KINDS.map((kind) => (
<Button
key={kind}
type="button"
variant="secondary"
size="sm"
className={`min-h-11 xl:min-h-9 ${ARMED}`}
data-add-kind={kind}
data-armed={armed === TOOL_OF[kind] ? '' : undefined}
disabled={disabled || (kind === 'detail_trigger' && linkDisabled)}
onClick={press(kind)}
>
{t(`editor.annotations.add.${kind}`)}
</Button>
))}
</div>
)
}
```
No `aria-pressed` on these buttons (delegated choice, contract): Enter does not toggle them; the tool column keeps `aria-pressed`. In `EditableAnnotations.tsx`: `armed={armedTool(scene.ui)}`, `onArm={(kind, button) => armFromAdd(kind, button, scene)}`, `addAtCentre`'s `creationStart(scene, 'add')`, and:
```tsx
/**
* « Ajouter … » pressed once by pointer: arms the kind's tool, or disarms it when armed
* (owner 2026-11-20). Behind the drawing guard (R-12): a started creation or redraw is asked
* about first, never dropped silently.
*/
function armFromAdd(kind: NewKind, button: HTMLElement, { ui, dispatch }: Scene) {
const tool = TOOL_OF[kind]
const next = armedTool(ui) === tool ? 'select' : tool
guardedPress(button, () => dispatch({ type: 'tool', tool: next, from: 'add' }))
}
```
Check in the browser build that `data-armed:` generates `[data-armed]` rules (Tailwind v4 boolean data variant): `grep -o 'data-armed' ` in the built CSS of Task 7's run, or a unit assertion is not possible (happy-dom has no CSS); Task 7 Step 1 asserts the armed button's computed background.
- [ ] **Step 3b: the screen-reader path.** (i) `usePlacement.ts` `onTraceKey`: when there is no tracing, no creation, the tool is `point`, `zone` or `link` and the key is Enter, `preventDefault` and place the kind's shape at the centre: `placePending(creationStart(input, input.ui.armedFrom), keyboardPending(kind, frame, newPointSize(doc.annotations, viewId, frame, ui.size)))` with `kind = TOOL_TARGET[tool]` (the same shape and dialog as the C7 path; no frame → nothing). (ii) `KeyboardAdd` gets `announce: boolean` (true when `armedFrom === 'add'` and an add tool is armed) and renders, after its buttons, an always-mounted `<p role="status" className="sr-only">` holding `t(`editor.annotations.armed.${kind}`)` for the armed kind, empty otherwise (M-3 pattern: the region exists before its text). (iii) Strings:
- fr `editor.annotations.armed.point`: « Outil Point actif : touchez ou cliquez le dessin à l'endroit voulu, ou appuyez sur Entrée dans le dessin pour placer le point au centre. »
- fr `editor.annotations.armed.zone`: « Outil Zone actif : posez les sommets sur le dessin, ou appuyez sur Entrée dans le dessin pour placer une zone au centre. »
- fr `editor.annotations.armed.detail_trigger`: « Outil Accès actif : posez les sommets sur le dessin, ou appuyez sur Entrée dans le dessin pour placer un accès au centre. »
- en: « Point tool on: tap or click the drawing where you want it, or press Enter on the drawing to place the point at the centre. » / « Zone tool on: place the vertices on the drawing, or press Enter on the drawing to place a zone at the centre. » / « Link tool on: place the vertices on the drawing, or press Enter on the drawing to place a link at the centre. »
- [ ] **Step 4: pinned column budget** — FIRST, in the same commit, `docs/ANNOTATION-RENDERING.md:245-270` (the pinned column paragraph: 40.25 rem / 644 px, 9.25 rem, « capped below 672, 789 and 672 px ») and the comments of `apps/app/e2e/shell/editor-geometry.spec.ts:683` and `:1213` get the new figures; then `index.css`: the 9.25rem part budget counts the add row at 36 px (comment :79-80: chips 30 + gaps 36 + add row 36 + line 44 + border 2 = 148 px). Below 1 280 px the row is now 44 px: use 9.75rem there, and move the pin threshold from 40.25rem to 40.75rem below 1 280 px (the 365 px tool column beside the capped canvas must still fit). Keep 9.25rem / 40.25rem at ≥ 1 280 px. Update both comments' figures (the window heights under which the box is capped: recompute them, do not copy). Structure: the WHOLE block of `index.css:71-104` (sticky, cap and pinned scroll-margin rules) moves under one media-query list `@media (min-width: 1024px) and (max-width: 1279.98px) and (min-height: 40.75rem), (min-width: 1280px) and (min-height: 40.25rem)`, the cap reading a custom property `--edit-column-parts` (9.75rem, overridden to 9.25rem at `min-width: 1280px`); no band where the column is pinned without room.
- [ ] **Step 5:** run the new file, I-3, `pnpm test:run`, `pnpm typecheck && pnpm lint` → green.
- [ ] **Step 6: commit** `feat(editor): « Ajouter … » arms its tool on a click or a tap`.
### Task 7: browser suites
**Files:**
- Modify: `apps/app/e2e/shell/editor-shell-crossing.spec.ts:262-270` (« Ajouter un point » `.click()` → `focus()` + `keyboard.press('Enter')`; intent R-14 unchanged)
- Modify: `apps/app/e2e/shell/editor-annotations.spec.ts` (new tests, mouse)
- Modify: `apps/app/e2e/shell/editor-touch.spec.ts` (new tests in the 1 180 px `hasTouch` describe)
- [ ] **Step 1: owner journey by mouse** (editor-annotations.spec.ts): at 1 024, 1 180 and 1 280 px, inside `expectNoShift`: `click` « Ajouter un point » → no dialog, `[data-add-kind="point"][data-armed]`, `await expect(add).toHaveCSS('background-color', <the pressed « Point » tool's colour>)` (retrying: Button has a `transition`), and the three add buttons keep their width and height (measure before/after). At 1 280 px: click the drawing at 30 % / 40 % of the canvas box → « Nouveau point » visible, the ghost circle's screen centre within 3 px of the click; « Abandonner », confirm → focus on « Ajouter un point ». Then `dblclick()` on « Ajouter une zone » → it stays armed.
- [ ] **Step 2: owner journey by finger** (editor-touch.spec.ts, 1 180 px): `tap` « Ajouter un point », `tap` the drawing → dialog visible; the add button's height ≥ 43.5 px.
- [ ] **Step 3: handles on « Vertèbres thoraciques » by finger** (editor-touch.spec.ts, 1 180 px): seed the run's own equine draft as `editor-zones.spec.ts:30-34` does (`seedDraft(actor, { drawing: equineDrawing(), shape: equineShape })`; never the historical copy), `select(page, 'Vertèbres thoraciques')`, zoom in twice with the zoom-in button (×2.25). For every vertex handle `[data-vertex="i"]` whose centre lies inside the canvas box: choose it by focus without scrolling (`locator.evaluate((el) => (el as SVGElement).focus({ preventScroll: true }))`, which chooses through `onVertexFocus`) and assert the canvas box's `scrollLeft`/`scrollTop` stay 0, then read every `[data-testid="handle-layer"] [data-handle]` box and assert: the remove rect vs each insert circle (radius = half its box width) gap ≥ −1.5 px (LRN-105); the remove rect lies inside the canvas box (±1.5 px); the visible fill circle of an unchosen vertex is 14 ± 1.5 px wide and the chosen one's 18 ± 1.5 px; the visible « − » mark is 32 × 26 ± 1.5 px; `expectFingerSizedHandles(page)` passes. Then, for one vertex whose adjacent « + » is on screen, choose it by a real tap and tap that « + » centre → the zone's vertex count (count of `[data-vertex]`) grows by one; « Défaire » restores it.
- [ ] **Step 4:** run each touched or exposed spec alone, by full path, `--workers=2`: `pnpm db:sandbox e2e-shell e2e/shell/editor-shell-crossing.spec.ts --workers=2`, then `e2e/shell/editor-annotations.spec.ts`, `e2e/shell/editor-touch.spec.ts`, `e2e/shell/editor-zones.spec.ts` (presses « − » at its box centre), `e2e/shell/editor-geometry.spec.ts` (pinned column, short windows incl. 1 180 × 700) → green; a failure that is one of the 13 known on 3d6aacad is reported as such, by name.
- [ ] **Step 4b: criterion 32 on the final code (owner 2026-11-20).** In `editor-geometry.spec.ts`, a new describe seeding the run's own draft with eight extra detail views (long names, e.g. « Détail de la région thoracique 1 » … 8) so the view chips wrap; for each window 1 024 × 768, 1 180 × 820, 1 180 × 700 and 1 280 × 800, assert the chips take at least two rows, then run the same scroll walk as the existing Task 17 tests (column top below the strip; stuck with the strip, the column bottom ≤ the window bottom + 0.5; canvas size constant; no sideways scroll). Then rerun the whole `e2e/shell/editor-geometry.spec.ts` (short windows included). If the multi-row case fails, do NOT change the layout to make it pass: report BLOCKED with the measured overflow per window (the budget counts one row of chips; the owner decides).
- [ ] **Step 5: commit** `test(tests): browser journeys for the add buttons and the open-side bubble`.
### Task 8: gates and records
- [ ] **Step 1:** `pnpm typecheck && pnpm lint && pnpm test:run` → green.
- [ ] **Step 2:** `pnpm e2e:ui` → green.
- [ ] **Step 3 (main loop, background):** full shell run with the baseline's explicit list (33 specs by full path, NEVER `editor-equine.spec.ts`) and `--workers=2`: `pnpm db:sandbox e2e-shell e2e/shell/admin-sheets-list.spec.ts e2e/shell/admin.spec.ts e2e/shell/animals.spec.ts e2e/shell/catalogue-integrity.spec.ts e2e/shell/catalogue.spec.ts e2e/shell/clients.spec.ts e2e/shell/editor-access.spec.ts e2e/shell/editor-annotations.spec.ts e2e/shell/editor-citations.spec.ts e2e/shell/editor-deselect.spec.ts e2e/shell/editor-drawings.spec.ts e2e/shell/editor-finding-dialog.spec.ts e2e/shell/editor-geometry.spec.ts e2e/shell/editor-history.spec.ts e2e/shell/editor-journey.spec.ts e2e/shell/editor-leave-confirm.spec.ts e2e/shell/editor-measure-commit.spec.ts e2e/shell/editor-measure-drag.spec.ts e2e/shell/editor-more-menu.spec.ts e2e/shell/editor-properties.spec.ts e2e/shell/editor-recovery.spec.ts e2e/shell/editor-reference-journey.spec.ts e2e/shell/editor-references.spec.ts e2e/shell/editor-shell-crossing.spec.ts e2e/shell/editor-shell-journeys.spec.ts e2e/shell/editor-shell-layout.spec.ts e2e/shell/editor-shell.spec.ts e2e/shell/editor-signout.spec.ts e2e/shell/editor-structures.spec.ts e2e/shell/editor-touch.spec.ts e2e/shell/editor-zones.spec.ts e2e/shell/responsive.spec.ts e2e/shell/shell.spec.ts --workers=2 2>&1 | tee <scratchpad>/shell-u2-trial.log`; compare failing test names to `/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-faunosteo/0090b8ae-ef81-4b47-9d52-c8450e9a8d62/scratchpad/shell-3d6aacad-w2.log`; any new name is a regression.
- [ ] **Step 4:** `docs/development/V1-2-6_UX_TESTS.md`: rows for the add buttons (pointer, keyboard, double-click, redraw, the screen-reader path: announcement + Enter on the drawing), criterion 32 re-verified on the final code (short windows, chips on several rows: the result, pass or measured overflow), the open-side bubble (unit proof on the six equine polygons over zoom 1-6, e2e on « Vertèbres thoraciques »), criterion 8 (the device-independent geometry: `annotations.pointSize.test.ts` and the `insertMidpoint` tests of `annotations.polygonEdit.test.ts`; handle sizes read only by `HandleLayer` and `ZoneHandles`), and the residual risks: « assistive technologies activating with `detail ≥ 1` arm the tool instead of placing at the centre »; « a fast double tap on the tablet browser: counted as a double-click (stays armed) or as two taps (arms then disarms), not verified on the device »; « the canvas box can be scrolled by a focus (overflow-hidden), the bubble's screen bound then lags; pre-existing, pointer choices use preventScroll ».
- [ ] **Step 5: commit** `docs(docs): U2 trial adjustments test notes`.