chore(tasks): R1 and D6b contract and plan (rev 3, challenged)

This commit is contained in:
bchanot committed 2026-11-12 12:19:34 +01:00
1 parent 541706cba9
commit 4923edefc0
2 files changed
+463

No files matched your search

@@ -0,0 +1,156 @@
# CONTRACT — r1-history-deselect
- date: 2026-11-12 | flow: ship-feature | branch: feature/v1-2-anatomical-sheets
- status: active
## REQUEST (verbatim — IMMUTABLE)
# FAUNOSTEO V1-2.6 — GO R1 COMPLET + D6b
Le propriétaire approuve l'implémentation complète de R1, incluant le critère D6b ajouté après les tests manuels U1.
La cause identifiée dans useCanvasGestures.ts est acceptée. Le périmètre proposé est validé, sous les décisions suivantes.
## 1. Arbitrages
A. Focus après clic :
- Le focus reste dans le schéma après une désélection par clic ou toucher.
- Utiliser un élément graphique approprié et focusable ; ne pas tenter de focaliser arbitrairement un os ou un path SVG.
- Déclencher l'annonce accessible prévue.
- Conserver la règle A6 propre au bouton Désélectionner : ligne correspondante si disponible, sinon repli sur le schéma.
B. Zones et liens :
- Un clic sur une annotation interactive (point, zone ou lien) conserve le comportement de sélection.
- Un clic sur un élément non interactif du dessin, y compris un os ou un tracé SVG interne, désélectionne.
- Ne pas confondre les éléments SVG ordinaires et ceux porteurs d'une annotation.
C. Livraison :
- Implémenter R1 complet, conformément aux maquettes R0 validées et à V1-2-6_U1_CORRECTIONS.md.
- Isoler D6b dans un commit distinct pour faciliter sa revue et sa traçabilité.
- Ne pas commencer R2, R3, R4, U2 ou U2b.
D. Valeurs invalides :
- Conserver pour R1 le comportement actuel d'une valeur explicitement refusée et non appliquée : fermeture du panneau sans modification du document.
- Vérifier qu'aucune modification valide en attente d'enregistrement n'est perdue silencieusement.
- Ne pas introduire une nouvelle gestion globale des formulaires ou une modale de confirmation dans ce lot.
- Documenter le comportement et ses limites.
## 2. Implémentation D6b
Traiter les deux parcours :
- useCanvasGestures.ts / EditableAnnotations.tsx pour l'éditeur modifiable.
- CatalogueCanvas.tsx / AnnotationsTab.tsx pour la consultation en lecture seule.
Mutualiser le chemin de désélection existant lorsque c'est pertinent, sans altérer le catalogue du lecteur.
Une désélection ne doit pas :
- Modifier le document ;
- Déclencher une sauvegarde ;
- Ajouter une opération Défaire/Refaire ;
- Annuler une création en cours lorsqu'aucune annotation n'était sélectionnée ;
- Interférer avec le déplacement d'un repère, le pan, le zoom ou le pincement.
Le seuil de mouvement de 4 px et la protection des gestes multidoigts doivent être vérifiés sur les séquences réelles d'événements, et pas uniquement sur des clics synthétiques isolés.
## 3. Tests
Exécuter les tests unitaires et navigateur prévus pour R1 et D6b.
Couvrir :
- Clic sur un point, une zone et un lien interactif ;
- Clic sur rect/path/circle non interactifs, racine SVG et marge ;
- Absence de sélection initiale ;
- Pan, zoom, déplacement d'annotation et gestes à plusieurs doigts ;
- Utilisation tactile ;
- Annonce accessible et gestion du focus ;
- Lecture seule ;
- Absence de régression du catalogue du lecteur ;
- Défaire/Refaire après désélection ;
- Persistance du document et absence d'écriture inattendue ;
- Gestion des valeurs refusées et des modifications valides en attente.
Exécuter les suites automatisées uniquement sur leur environnement prévu. Ne jamais utiliser db:trial comme sandbox E2E jetable.
Si un test équin nécessite des fixtures, les préparer dans un environnement automatisé isolé, sans toucher à la fiche historique ni aux données de la pile d'essai.
iOS Safari reste une vérification manuelle ultérieure, non une preuve de compatibilité acquise.
## 4. Livraison et contrôles
Respecter les conventions de branche, commit et push du projet.
Réaliser :
- Les vérifications statiques ;
- Les tests unitaires ;
- Les tests navigateur ;
- Une revue fonctionnelle indépendante ;
- Une revue de code indépendante ;
- Une vérification de sécurité ciblée sur les interactions et l'isolation des environnements.
Documenter les écarts et limites réels, sans déclarer validé un test non exécuté.
## 5. Restrictions
Aucune intervention sur DEV.
Aucune migration SQL ni modification du moteur Rust ou du worker.
Ne pas modifier la fiche équine historique.
Ne pas supprimer ni réinitialiser la copie de travail d'essai.
Aucune modification des rôles, du MFA ou des secrets.
Ne pas modifier l'exposition réseau de la pile d'essai.
Préserver le fichier de revue ChatGPT non suivi.
Aucune fusion ni aucun déploiement.
## 6. Checkpoint
Fournir :
- Le détail des modifications R1 et D6b ;
- Les commits et leur état de push ;
- Les résultats des tests et contre-revues ;
- Les éventuelles régressions ou limitations ;
- Les points à vérifier manuellement dans l'éditeur sur db:trial.
S'arrêter à la fin de R1.
Ne pas démarrer R2 sans nouveau feu vert.
## CLARIFICATIONS
Q: spec of R1? / A: docs/development/V1-2-6_U1_CORRECTIONS.md §1 D5, D6, D6b, §3 R1, §6 A5, A5b, A6; board 26 (docs/design/v1-2-6-r0/26-historique-deselection.png, maquettes.html:380-391, :611-667, REVUE.md:57-60, :72, :108-111, :129-135) is normative (BDR-110).
Q: tooltip with the shortcut and Meta in aria-keyshortcuts? / A: yes, board 26 and REVUE.md:59, :108-110 (title = name + « (Ctrl+Z ou ⌘Z) » / « (Ctrl+Maj+Z ou ⇧⌘Z) », EN « (Ctrl+Z or ⌘Z) » / « (Ctrl+Shift+Z or ⇧⌘Z) »; aria-label = name only; aria-keyshortcuts adds Meta+Z / Meta+Shift+Z).
Q: suites environment? / A: unit + e2e:ui local; e2e:shell only on `pnpm db:sandbox` (already up); never db:trial, never DEV; no sandbox reset/down; exact shell count reported against the known baseline (4 failures admin.spec.ts:717, anomaly B).
## ACCEPTANCE CRITERIA
1. FR history labels read « Défaire » / « Refaire » with names « Défaire la dernière modification » / « Refaire la dernière modification défaite »; EN undo/redo strings unchanged; fr and en key sets identical.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && grep -q "'editor.history.undo': 'Défaire'" src/i18n/fr.ts && grep -q "'editor.history.redo': 'Refaire'" src/i18n/fr.ts && grep -q "'editor.history.undo_title': 'Défaire la dernière modification'" src/i18n/fr.ts && grep -q "'editor.history.redo_title': 'Refaire la dernière modification défaite'" src/i18n/fr.ts && grep -q "'editor.history.undo': 'Undo'" src/i18n/en.ts && grep -q "'editor.history.redo_title': 'Redo the last undone change'" src/i18n/en.ts && ! grep -qE "'editor\.history\.(undo|redo)(_title)?': '(Annuler|Rétablir)" src/i18n/fr.ts && echo LABELS_OK
EXPECT: LABELS_OK
EVIDENCE: pending
2. History buttons: aria-label = the name, title = name + the shortcut text of board 26, aria-keyshortcuts lists Control and Meta forms; shortcuts themselves unchanged (useUndoShortcuts.ts untouched); dialog « Annuler » buttons untouched; the FR prose naming the history command (editor.views.drawing.use_parent_body, editor.views.repair.body_one/_other) says « Défaire ».
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && git diff --quiet 541706c -- apps/app/src/editor/useUndoShortcuts.ts && grep -q "Meta+Z" apps/app/src/components/editor/HistoryButtons.tsx && grep -q "Meta+Shift+Z" apps/app/src/components/editor/HistoryButtons.tsx && ! grep -q "un seul Annuler" apps/app/src/i18n/fr.ts && ! grep -q "ce changement (Annuler)" apps/app/src/i18n/fr.ts && echo HISTORY_OK
EXPECT: HISTORY_OK
EVIDENCE: pending
3. « Désélectionner » (secondary, deselect glyph) sits to the left of « Supprimer » in the properties panel, in edit and read-only modes (read-only: no « Supprimer »); after it: the annotation's list row if visible, else the drawing box; focus never reselects; polite announcement « Aucune annotation sélectionnée. » / « No annotation selected. ».
4. Escape in the editor workspace, first applicable wins: open dialog (native, untouched) > « Plus » menu open (closes, focus on « Plus ») > references panel open (closes, focus on its opener) > tracing in progress (cancels, as today) > selection (deselects, focus per the [gated] rule, same announcement); Escape inside a text field / select never deselects; nothing applicable → nothing; acts on the shown body only (kept hidden edit body or hidden tab never changes).
5. D6b, edit canvas: with the select tool, a click/tap whose target has no [data-anno-id] ancestor deselects when an annotation is selected (bone or any drawing shape, the composed root, the box margin); a click on a point, zone or link still selects it; nothing selected → no dispatch (pending keyboard creation, typed fields, « Filtrer par nom » kept); drawing tools and tracing unchanged; a press that moved > 4 px (pan, marker drag, pinch) or during which a second pointer came down never deselects; focus ends on the canvas box (role=group, tabIndex 0), never on an SVG shape; same announcement.
6. D6b, read-only twin: CatalogueCanvas gets an optional onEmpty with the same rules, passed only by the editor's read-only twin; the catalogue reader (SheetRoute) passes none and behaves exactly as before; useFraming.ts unchanged.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && git diff --quiet 541706c -- apps/app/src/catalogue/useFraming.ts apps/app/src/app/routes/app/anatomy/SheetRoute.tsx && grep -q "onEmpty" apps/app/src/components/catalogue/CatalogueCanvas.tsx && grep -q "onEmpty" apps/app/src/components/editor/tabs/AnnotationsTab.tsx && echo READER_UNCHANGED_OK
EXPECT: READER_UNCHANGED_OK
EVIDENCE: pending
7. Every deselect path (button, Escape, click/tap): document text, handle version, history length, unsaved count and save state unchanged by the deselect itself; no save request; a valid typed value not yet blurred is committed (its own edit, undoable), never dropped silently; a refused « non appliqué » value: panel closes, document unchanged (current behaviour, documented); undo after a deselect undoes the previous edit.
8. Unit tests (vitest) cover items 1-7 including clicks on inner SVG elements (rect/circle/path), the root svg and the margin, pointer sequences (down/move/up then click) under and over 4 px, a second pointer, read-only twin, reader unchanged; `pnpm typecheck`, `pnpm lint`, `pnpm test:run`, `pnpm build` pass.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm -s typecheck >/dev/null 2>&1 && pnpm -s lint >/dev/null 2>&1 && pnpm -s test:run >/tmp/claude-1000/-home-bchanot-Documents-faunosteo/463d8810-0112-4b67-92e4-aa3c30af6089/scratchpad/r1-unit.txt 2>&1 && echo STATIC_UNIT_OK
EXPECT: STATIC_UNIT_OK
EVIDENCE: pending
9. Browser tests: `pnpm e2e:ui` passes; a new shell spec (Chromium, `pnpm db:sandbox` only) covers button, Escape matrix, D6b mouse clicks on inner shapes/root/margin/annotations, pan/zoom/marker drag, touch tap, touch drag, two-finger tap and pinch through CDP, read-only twin, persistence after reload and no save request; `editor-equine.spec.ts` clicks a bone path of the horse drawing on its own sandbox copy; the full shell suite run is reported with its exact counts against the baseline.
10. D6b lands in its own commit; commits pushed on feature/v1-2-anatomical-sheets; no change under supabase/, crates/, scripts/db-trial*.sh, docker/; the untracked review file kept.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && [ -z "$(git diff --name-only 541706c -- supabase crates scripts/db-trial.sh scripts/db-trial-check.sh docker)" ] && [ -f faunosteo-v1-2-6-revue-ux-chatgpt.md ] && git log --format=%s 541706c..HEAD | grep -q "D6b" && [ "$(git rev-parse HEAD)" = "$(git rev-parse @{u})" ] && echo SCOPE_PUSH_OK
EXPECT: SCOPE_PUSH_OK
EVIDENCE: pending
11. Docs: V1-2-6_U1_CORRECTIONS.md R1 status + the deselect limits (refused value, focus rules, iOS manual), BROWSER_TESTS.md (new spec, keyboard order « Défaire », « Refaire »), V1-2-6_OWNER_TRIAL.md labels, a D5 note on T15 in V1-2-6_UX_DECISIONS.md and V1-2_ANATOMICAL_SHEETS.md, ANNOTATION-RENDERING.md click paragraph (D6b); historical records (U1 checkpoint, v1-2-6 board records) untouched.
## FILE SCOPE
apps/app/src/i18n/{fr,en}.ts; apps/app/src/components/editor/{HistoryButtons,EditorTabs,EditorWorkspace,EditorGlyph}.tsx; apps/app/src/components/editor/annotations/{PropertiesPanel,EditableAnnotations,AnnotationCanvas}.tsx; apps/app/src/components/editor/references/ReferencesPanel.tsx; apps/app/src/components/editor/tabs/AnnotationsTab.tsx; apps/app/src/components/catalogue/CatalogueCanvas.tsx; apps/app/src/editor/annotations/{useCanvasGestures,usePlacement}.ts; apps/app/src/editor/{focusRequest,useEditorNavigation}.ts; new apps/app/src/editor/{deselect,escape}.ts(x) helpers; apps/app/tests/unit/*.test.tsx (editor-history-buttons, editor-annotations-tab, editor-overview, editor-sections, editor-keep-alive, routes.catalogue, new editor-deselect / editor-escape); apps/app/e2e/shell/editor-*.spec.ts (titles/comments), new e2e/shell/editor-deselect.spec.ts, e2e/support/editor.ts, editor-equine.spec.ts; docs listed in criterion 11; .claude/tasks/*.
@@ -0,0 +1,307 @@
# R1 (history labels, deselection, Escape) + D6b Implementation Plan — rev 3 (3-lens challenge + re-challenge)
> For agentic workers: executed task by task by fresh implementers (subagent-driven-development), each task
> reviewed before the next. Steps use checkbox syntax.
**Goal:** V1-2.6 lot R1 complete: « Défaire » / « Refaire », « Désélectionner », the Escape priority, and D6b
(a click or tap on the drawing outside any annotation deselects), in the editable editor and its read-only twin.
**Architecture:** one deselect hook (commit the focused field, clear the selection, move or keep focus, announce)
used by the button, Escape and the drawing. Escape needs no registry: only the SHOWN annotation body
(`usePlaceVisible()`) listens for Escape on `document` (bubbling, so React-level consumers that stop or mark the key
go first), and only while it has a resolved selection and no tracing; the « Plus » disclosure closes itself first
through a capture listener while open; the workspace root closes the references panel for an Escape from the header
or tab row. D6b decides on the PRESS, not the click target: a tap tracker (pointerdown target, accumulated
movement, primary/non-primary pointers anywhere in the page, contextmenu) gives an empty-tap verdict at `pointerup`.
Mouse and pen apply it at pointerup (survives the pointer capture of the move gesture, whose click targets the box,
and the canvas rebuild a blur commit triggers at mousedown) and swallow the click that follows. Touch applies it in
the tap's own click, and only if that click's target carries no `[data-anno-id]` (Chromium builds the touch click
after touchend, hit-tests the post-deselect layout and adjusts toward nearby markers: applying at pointerup would
let the click land on what moved under the finger). `useFraming` is not touched.
**Tech stack:** React 19, TypeScript strict, Zustand editor store, Vitest + happy-dom + Testing Library,
Playwright Chromium (`pnpm e2e:shell` on `pnpm db:sandbox`).
**Spec:** `docs/development/V1-2-6_U1_CORRECTIONS.md` §1 (D5, D6, D6b), §3 R1, §6 (A5, A5b, A6); board
`docs/design/v1-2-6-r0/26-historique-deselection.png` (normative, BDR-110), `maquettes.html:380-391, :611-667`,
`REVUE.md:57-60, :72, :108-111, :129-135`. Contract: `.claude/tasks/contracts/2026-11-12-r1-history-deselect-1141.md`.
## Global constraints
- Worktree `/home/bchanot/Documents/faunosteo-v1-2`, branch `feature/v1-2-anatomical-sheets`, commit in place
(auto-push); never run anything in `/home/bchanot/Documents/faunosteo`.
- No change under `supabase/`, `crates/`, `scripts/`, `docker/`; `apps/app/src/catalogue/useFraming.ts`,
`apps/app/src/editor/useUndoShortcuts.ts`, `apps/app/src/app/routes/app/anatomy/SheetRoute.tsx` unchanged;
`src/catalogue` and `src/components/catalogue` import nothing from `@/editor`.
- Every UI string through `useT()`; fr and en get the same keys; `t` never in effect or callback deps (LRN-088).
- Our code: ≤ 25 logic lines per function, ≤ 5 params, ≤ 5 locals, 100 chars per TS line; comments say why.
- Kept places: act only on what is shown; no one-shot focus in mount effects (LRN-119); twin ids keep `ro-`.
- Unit pointer events in happy-dom carry `isPrimary: true, button: 0, pointerType: 'mouse'` explicitly (happy-dom's
default `isPrimary` is false).
- Browser suites: `pnpm e2e:shell` against `pnpm db:sandbox` only (up); never db:trial, never DEV; no sandbox
reset or `down`; never edit `src` while a browser suite runs (LRN-120).
- Commits: Conventional Commits, allowed scopes (`app`, `tests`, `docs`); every rewritten or removed assertion
mapped to its replacement in the commit body (R-24). D6b code and its tests only in the D6b commit.
## Fixed wording (board 26, REVUE.md table)
| Key | FR | EN |
|---|---|---|
| `editor.history.undo` | Défaire | Undo (unchanged) |
| `editor.history.undo_title` | Défaire la dernière modification | Undo the last change (unchanged) |
| `editor.history.redo` | Refaire | Redo (unchanged) |
| `editor.history.redo_title` | Refaire la dernière modification défaite | Redo the last undone change (unchanged) |
| `editor.history.undo_shortcut` (new) | Ctrl+Z ou ⌘Z | Ctrl+Z or ⌘Z |
| `editor.history.redo_shortcut` (new) | Ctrl+Maj+Z ou ⇧⌘Z | Ctrl+Shift+Z or ⇧⌘Z |
| `editor.annotations.deselect` (new) | Désélectionner | Deselect |
| `editor.annotations.deselected` (new) | Aucune annotation sélectionnée. | No annotation selected. |
FR prose: `editor.views.drawing.use_parent_body` « … et vous pouvez défaire ce changement (Défaire). … »;
`editor.views.repair.body_one` / `_other` « … et un seul Défaire les restaure ensemble. ». EN prose unchanged.
`fr.ts:1479` « Annulez, … » and every dialog « Annuler » stay.
## Gate outcomes (filled at the validation gate before dispatch)
- G1 Escape focus: [pending owner] recommended = focus inside the properties panel → A6 (row if visible, else the
drawing box); focus elsewhere (canvas box, view chips, tool column, add buttons) → stays where it is.
- G2 « Supprimer »: [pending owner] recommended = unchanged (filled danger button, no icon), per the board caption
« qui garde son style de danger »; only placed to the right of « Désélectionner » in the bordered row.
## Reviewer checklist (each has its test below)
Shown body only (Task 3 test 9); replace tracing (Task 2 test 8, Task 3 test 6, Task 4 test 10); pending valid value
then a drawing click in a real browser (Task 5 step 7); two-finger tap (Task 4 test 8, Task 5 step 5 with the event
count); filtered-out row (Task 2 test 2); selected marker click and jitter (Task 4 test 4, Task 5 step 3).
---
### Task 1: history reads « Défaire » / « Refaire » (D5) — commit `feat(app): history reads Défaire / Refaire (R1, D5)`
**Files:** `apps/app/src/i18n/fr.ts` (:1284-1287, :1444, :1473-1474), `apps/app/src/i18n/en.ts` (new shortcut keys
only), `apps/app/src/components/editor/HistoryButtons.tsx`, `EditorTabs.tsx:147` (comment only); tests
`tests/unit/editor-history-buttons.test.tsx`, `tests/unit/editor-annotations-tab.test.tsx:514`; e2e titles/comments
`e2e/shell/editor-shell-layout.spec.ts:271, :293`, `editor-shell-journeys.spec.ts:152, :160`, `editor-shell.spec.ts:149`,
`e2e/support/editor.ts:440`.
- [ ] Dictionaries per the wording table.
- [ ] `HistoryButtons.tsx`: `SHORTCUT = { undo: 'Control+Z Meta+Z', redo: 'Control+Shift+Z Meta+Shift+Z' }`;
`aria-label={name}`, `title={`${name} (${t(`editor.history.${direction}_shortcut`)})`}`; comments :41, :53, :121
and `EditorTabs.tsx:147` say « Défaire » / « Refaire ».
- [ ] Unit: constants and assertions to the new FR names; title = name + « (Ctrl+Z ou ⌘Z) » / « (Ctrl+Maj+Z ou
⇧⌘Z) »; `aria-keyshortcuts` the two-form lists; visible labels `['Défaire','Refaire']`; the absence checks (:205,
`editor-annotations-tab.test.tsx:514`) become `/Défaire|Refaire/`; one EN test (names unchanged, title with
« (Ctrl+Z or ⌘Z) »); FR prose keys contain « Défaire » while `use_parent_cancel` still reads « Annuler ».
- [ ] Run `pnpm --filter @faunosteo/app exec vitest run tests/unit/editor-history-buttons.test.tsx tests/unit/i18n.dicts.test.ts tests/unit/editor-annotations-tab.test.tsx`, `pnpm typecheck`, `pnpm lint`. Commit with the R-24 map.
### Task 2: « Désélectionner » (D6, A6) — part of commit `feat(app): Désélectionner and the Escape priority (R1, D6, A5, A6)`
**Files:** new `apps/app/src/editor/annotations/deselect.ts`; `src/editor/useEditorNavigation.ts` (export
`CANVAS_BOX` only); `src/editor/focusRequest.ts` (export `isTextField(target)`; `commitFocusedField` uses it);
`EditorGlyph.tsx` (glyph `deselect`: `M4 8V5a1 1 0 0 1 1-1h3M16 4h3a1 1 0 0 1 1 1v3M20 16v3a1 1 0 0 1-1 1h-3M8 20H5a1 1 0 0 1-1-1v-3M9 9l6 6M15 9l-6 6`);
`annotations/PropertiesPanel.tsx`; `annotations/EditableAnnotations.tsx` (pass `busy`); i18n keys.
- [ ] `deselect.ts`:
- `focusDrawing(): boolean` — `visibleElement(CANVAS_BOX)` focused with `{ preventScroll: true }`.
- `focusRowOrDrawing(id)` — `focusRow({ kind: 'annotation', id }) || focusDrawing()`.
- `useDeselect(id: string | null, clear: () => void)` → `{ byButton(), byKey(fromPanel: boolean) }`. `id` is the
RESOLVED selection (`selected?.id ?? null`, never the raw `selectedId`, which can name a removed annotation).
Each: `id === null` → return false; else `commitFocusedField()`, `flushSync(clear)`, focus (byButton →
`focusRowOrDrawing(id)`; byKey → `focusRowOrDrawing(id)` if `fromPanel`, else per G1), `announce(t(…deselected))`
(`AnnounceContext`), return true. `t` via a ref.
- [ ] `PropertiesPanel`: new optional prop `busy?: boolean` (a tracing runs). After the status actions, one row
`<div className="flex flex-wrap gap-2 border-t border-[var(--color-border)] pt-2.5">`: « Désélectionner »
(`<Button variant="secondary" size="sm">`, `<EditorGlyph name="deselect" size={16} />`, `t('editor.annotations.deselect')`),
not rendered while `busy`; its handler `useDeselect(annotation.id, props.onShowAll).byButton` (the same clear
as « Toutes les annotations », no new callback prop); `onMouseDown={(e) => e.preventDefault()}` keeps the focus in
a field being typed during the press, so its blur commit (which can change the panel height above the button and
lose the click) happens inside byButton's `commitFocusedField()`; then `Deletion` unchanged (G2). Rendered in read-only too
(`Deletion` already renders null there). `ShowAll` untouched.
- [ ] Edit body passes `busy={ui.tracing !== null}`.
- [ ] Unit tests appended to `tests/unit/editor-annotations-tab.test.tsx` (`describe('« Désélectionner » (R1, A6)')`,
mount wrapped in an `AnnounceContext` spy, as `editor-sections.test.tsx:172`):
1. overview back, focus on the row, announcement, `documentText`, `handleVersion`, undo stack length, `unsaved`
unchanged; 2. filter term hiding the row → focus on `[data-testid=annotation-canvas]`, nothing selected;
3. undo after it undoes the earlier edit; 4. read-only: « Désélectionner » present, no « Supprimer », it deselects
and focuses the `ro-` row; 5. valid typed « Centre x » not blurred → committed once (one undo step);
6. refused value not blurred → panel closes, `documentText` unchanged; 7. EN: « Deselect », « No annotation
selected. »; 8. replace tracing started → no « Désélectionner » rendered.
### Task 3: the Escape priority (A5) — rest of the same commit
**Files:** `annotations/EditableAnnotations.tsx`, `tabs/AnnotationsTab.tsx` (body handlers), `EditorTabs.tsx`
(MoreTabs Escape), `EditorWorkspace.tsx` (panel close from outside it), `editor/annotations/usePlacement.ts:79-83`
(`event.preventDefault()` when Escape cancels a tracing). `ReferencesPanel.tsx` unchanged (it already stops its Escape).
- [ ] Every Escape handler below returns early on `event.nativeEvent.isComposing` (or `event.isComposing`).
- [ ] `MoreTabs`: local state kept (unmount still resets it); while `open`, an effect adds a `document` keydown
listener in the CAPTURE phase: Escape, no `dialog[open]`, not composing → `preventDefault()`, close, focus
`#${MORE_BUTTON_ID}`; removed on close or unmount.
- [ ] `EditorWorkspace` root `onKeyDown` (bubbling): Escape, not `defaultPrevented`, not composing,
`state.references.open` → `nav.closeReferences()` (existing focus return), `preventDefault()`.
- [ ] New hook `useEscapeDeselect(active: boolean, onEscape: (event: KeyboardEvent) => boolean)` in
`editor/annotations/deselect.ts`: while `active`, a `document` keydown listener (bubbling phase; the latest
`onEscape` read through a ref): Escape, not `defaultPrevented`, not composing, `!isTextField(event.target)`, the
target is `document.body` or inside `[data-editor-workspace]` (attribute added on the EditorWorkspace root) →
`if (onEscape(event)) event.preventDefault()`. React handlers that stop propagation (dialogs, references panel)
never reach `document`; the « Plus » capture listener and the workspace panel handler mark the key first.
- [ ] Each body calls it with `active = usePlaceVisible() && selected !== undefined && (edit: ui.tracing === null)`
and `onEscape = (e) => deselect.byKey(asideRef.current?.contains(e.target as Node) ?? false)`; `asideRef` on
the panel column. A hidden body (kept edit body, hidden tab or section) is never active.
- [ ] Limit, documented: Escape from outside the editor workspace (sidebar, app header) does nothing.
- [ ] Unit tests, new `tests/unit/editor-escape.test.tsx` rendering `EditorWorkspace` with the existing harness
(`tests/helpers/editorHarness.ts`, as `editor-keep-alive.test.tsx`): 1. canvas box focused → deselected, focus
per G1, announcement; 2. « Marquer comme relu » focused → deselected, focus on the row; 3. select A, then B, then
Escape from the panel → focus on B's row; 4. « Nom (FR) » focused → nothing; 5. references panel open, Escape
from the tab row → panel closes, selection kept; 6. replace tracing with the canvas box focused → tracing
cancelled, selection kept; 7. tracing, focus on the TracingBar → nothing; 8. small tier, « Plus » open, focus in
the twin's canvas → « Plus » closes, focus on it, twin selection kept; 9. read-only width with the hidden edit
body holding its own selection → only the twin deselects, the hidden body's selection unchanged; 10. delete
dialog open → only the dialog's own handling (wiring proof, LRN-082); 11. focus on `body` → deselected; focus on
« Défaire » in the tab row → deselected (focus stays there); a target outside the workspace → nothing;
12. nothing selected (or the selected annotation deleted) → no announcement, no change.
- [ ] Run the new file + `editor-keep-alive`, `editor-annotations-tab`, `editor-overview`; typecheck, lint. Commit
tasks 2 + 3 together (R-24 map).
### Task 4: D6b, an empty tap on the drawing — commit `feat(app): a click on the drawing deselects (R1, D6b)`
**Files:** new `apps/app/src/catalogue/useEmptyTap.ts`; `src/editor/annotations/useCanvasGestures.ts`;
`components/editor/annotations/AnnotationCanvas.tsx` (prop pass-through); `EditableAnnotations.tsx` (CanvasStage);
`components/catalogue/CatalogueCanvas.tsx`; `components/editor/tabs/AnnotationsTab.tsx`; `editor/annotations/deselect.ts`
(add `byDrawing`).
- [ ] `useEmptyTap()` (refs, one document listener, cleaned on unmount): `onPointerDown(e)`: primary → reset
`{ armed: e.button === 0, onAnnotation: target.closest('[data-anno-id]') !== null, moved: 0, multi: false,
last: point, touchPending: false, swallowClick: false }` and, while armed, a `document` capture `pointerdown`
listener that sets `multi` for any other pointerId (a second finger outside the box counts); non-primary →
`multi = true`. `onPointerMove(e)`: primary and armed → `moved += distance(last, point)`, `last = point`.
`onPointerCancel` and `onContextMenu` → disarm. `verdict(e)` (called on EVERY pointerup, before any tool test, so
every press disarms and removes the document listener): `'none'` unless primary, armed, `!multi`,
`moved <= TAP_SLOP_PX` (4, the same 4 px as `useFraming`'s drag threshold), `!onAnnotation`; else `'now'` for
mouse and pen (sets `swallowClick`), `'on_click'` for touch (sets `touchPending`). `takeClick(target)` (called
first by the click handler): `swallowClick` → clear it, answer `'swallow'`; `touchPending` → clear it, answer
`'deselect'` when the target has no `[data-anno-id]` ancestor, else `'normal'`; otherwise `'normal'`.
Both flags are cleared by the next pointerdown.
- [ ] `useCanvasGestures`: `GestureInput.onDeselect: () => void`; `composedPointer` also calls the tracker's
down/move/cancel; box `onContextMenu` → tracker. `onPointerUp` runs framing and move first, then
`const v = tap.verdict(event); if (input.tool === 'select' && v === 'now') input.onDeselect()`.
`clickHandler`: `swallowClick()` (framing) first as today, then `tap.takeClick(event.target)`: `'swallow'` →
return; `'deselect'` → `if (input.tool === 'select') input.onDeselect()`, return; `'normal'` → today's code
unchanged (select on an id, place with a tool).
- [ ] Documented behaviour: the vertex handles of a selected polygon are drawn by the overlay with
`pointer-events: none` and have no function; a press on a handle's part outside the zone's own fill deselects
(pinned by a unit case). A touch tap whose click Chromium drops (rare: the blur commit of a field rebuilds the
drawing between the synthesized mousedown and the click) does not deselect; a second tap does (reported from e2e).
- [ ] `deselect.ts`: `byDrawing()` — like byButton but focus: `focusDrawing()` unless the visible box already holds
the focus; same announcement; returns false when nothing is selected (no dispatch).
- [ ] `CanvasStage`: `onDeselect={deselect.byDrawing}` with the resolved selection.
- [ ] `CatalogueCanvas`: `onEmpty?: () => void`; viewport handlers compose `handlers.onPointerDown/Move/Up/Cancel`
(and `onContextMenu`) with the tracker; on pointerup `if (verdict(e) === 'now' && onEmpty) onEmpty()`; the host
click listener calls `takeClick` first only when `onEmpty` is set (`'swallow'` → return, `'deselect'` →
`onEmpty()`, `'normal'` → today's code). Without `onEmpty` the listener is byte-for-byte today's path and nothing
new is observable (the reader keeps its behaviour, BDR-099 item 5).
- [ ] Twin: `onEmpty={deselect.byDrawing}`.
- [ ] Unit tests appended to `tests/unit/editor-annotations-tab.test.tsx` (`describe('a tap on the drawing (D6b)')`;
helper `tap(el, { dx, upOn, type })`: pointerdown on `el`, optional pointermove, pointerup on `upOn`, then
`click` on `upOn`; primary, button 0, `pointerType` mouse by default; extra cases: touch tap on `<rect>` →
deselected only at the click; touch tap whose click target is a marker (touch adjustment) → that marker selected,
no deselect announcement; mouse tap → deselected at pointerup and the following click on a marker is swallowed;
`contextmenu` during the press → kept; a document-level pointerdown with another pointerId during the press →
kept; a press on a selected polygon's vertex handle outside its fill → deselected (documented behaviour):
1. inner `<rect>` → deselected, focus on the canvas box, announcement, store unchanged (text, version, undo
length, unsaved); 2. composed root `<svg>` → deselected; 3. the box itself (margin) → deselected;
4. pointerdown on the SELECTED marker, pointerup and click on the box (capture retarget) → kept; same with a 2 px
move → kept; 5. another marker → selected (existing click path); a zone polygon interior → selected; a link →
selected; 6. nothing selected, pending keyboard creation with a typed name → tap on `<rect>` keeps it;
7. 3 px accumulated move → deselects; 6 px → kept; out 5 px and back (net 0) → kept; 8. non-primary pointerdown
during the press → kept; the next single tap → deselects; 9. `button: 2` press → kept; 10. replace tracing
(tool zone) tap → a vertex added, selection kept; 11. marker drag of the selected point 8 px → moved, still
selected (re-query the marker after the rebuild); 12. read-only twin: tap on `<rect>` → deselected, focus on
`[data-testid=catalogue-canvas]`; 13. undo after a tap deselect undoes the earlier edit, redo works;
14. typed valid « Centre x », focus moved to the box at pointerdown (as mousedown does, triggering the blur
commit and the rebuild), pointerup on the new `<rect>` → committed once AND deselected; 15. same with a refused
value → panel closes, document unchanged.
- [ ] `tests/unit/routes.catalogue.test.tsx`: zone picked, tap on a drawing `<rect>` → zone panel unchanged.
- [ ] Run the touched files, typecheck, lint. Commit (D6b only).
### Task 5: browser tests, gates, docs — commits `test(app): browser checks for R1 and D6b`, `docs(app): R1 delivered`
**Files:** new `apps/app/e2e/shell/editor-deselect.spec.ts`; `e2e/support/editor.ts` (only helpers it needs);
`e2e/shell/editor-equine.spec.ts` (one new test, last); docs per contract criterion 11; `.claude/tasks/TODO.md`.
- [ ] Fixture: `seedDraft({ shape: shapeWith(point, zone, link) })` with the detail view of
`support/editor.ts:235-275` and `DRAWING_SVG`, so revision 1 is the reference (no recovery offer at reload).
Coordinates recomputed before every press (LRN-104); presses away from discs (LRN-108); after each negative
("kept") check wait two animation frames.
- [ ] `editor-deselect.spec.ts` (`chromium-desktop`; the twin test on `chromium-375`):
1. button: live region text, focus on the row; reload → `documentText` equal to revision 1;
2. Escape: canvas focused → deselected; field focused → nothing; delete dialog → only it closes (wait for it
gone, LRN-111); references panel → closes; tracing → cancelled only;
3. mouse: click inner circle, inner rect, root (inside viewBox, outside rect), box margin → each deselects;
point, zone interior, link → select; click and dblclick and a 2 px jitter on the SELECTED point and zone →
still selected (and `editor-annotations.spec.ts:179-186` stays green);
4. zoom in, drag-pan 20 px on empty, marker drag, Ctrl+wheel → kept; 2 px jitter on empty → deselects;
5. touch (`hasTouch` context, 1280×800, CDP `Input.dispatchTouchEvent` as `editor-geometry.spec.ts:457-465`): tap
→ deselected; a tap on empty drawing with an annotation about 40 px below it, and a tap within 36 px of the
canvas bottom (above the add buttons) → deselected, nothing else selected, no pending creation; a tap about
6 px outside a marker's hitbox → either that marker selected or deselected, never both (no deselect
announcement when the marker ends selected); one-finger drag, two-finger tap, pinch → kept; a capture-phase
recorder on the document logs pointerdown (primary / non-primary), pointercancel, pointerup and click with the
click target's `data-anno-id`, attached as test annotations; the report states which guard each step reached;
6. no draft-save request recorded by `page.on('request')` during steps 1-5;
7. valid typed « Centre x » (no blur) then ONE click on the drawing → value applied (unsaved +1) AND the overview
shown; « Défaire » reverts the value; « Désélectionner » pressed with an unblurred refused value → panel closed
in one click, document unchanged; with an unblurred valid value → committed and closed in one click;
8. `chromium-375` (twin, `touch-action: pan-x pan-y`): tap a marker, tap the rect → deselected, focus on the
catalogue box; one-finger drag and two-finger tap on the twin → kept (recorder shows pointercancel or multi).
- [ ] `editor-equine.spec.ts`: a new test placed right AFTER the copy-creation test in the serial group, reusing
`copyId`: select an annotation from the list, click a horse path found by `page.evaluate` (bbox centre whose
`elementFromPoint` is that path, no `[data-anno-id]` ancestor) → deselected. Setup and teardown unchanged; the
gate report names it executed or skipped.
- [ ] Gates in the U1 order (CORRECTIONS:44-48): `pnpm typecheck`, `pnpm lint`, `pnpm test:run`, `pnpm build`,
`pnpm e2e:ui`; then `impeccable detect` on the changed components and a fresh design review against board 26
(fixes, if any, land now); then `pnpm e2e:shell` (whole suite) on the sandbox on the final src commit (named in
the report), exact counts against the baseline; any later src change reruns the suite.
- [ ] Docs (criterion 11) incl. limits: Escape from outside the editor workspace does nothing; a refused value is lost when
the panel closes (as « Toutes les annotations »); « Toutes les annotations » keeps today's focus (falls to the page
when its row is filtered out, noted in TODO); iOS Safari unverified; the two-finger guard proven where the event
counts show it. TODO R1 line.
## Disposition
- honors BDR-107/108/109/110 (D5, D6, A5, A5b, A6, board 26 normative) by the wording table, the Escape order and
the row-else-drawing focus; D6b supersedes BDR-107's « left to U2 » (owner 2026-11-12, BDR at capitalize).
- honors BDR-099 item 5: `SheetRoute` and the reader's zone panel unchanged (`onEmpty` optional).
- honors BDR-101: only the history labels change (« Abandonner » and dialog « Annuler » unchanged).
- honors BDR-104/105/106, LRN-121: shell suite on the sandbox as it stands, never reset, exact counts against the
baseline (4 failures `admin.spec.ts:717`).
- applies LRN-082, LRN-088, LRN-103, LRN-104, LRN-108, LRN-111, LRN-119, LRN-120, LRN-017, EVAL-042 as cited.
## Challenge record (rev 1 → rev 2)
- BLOCKER (correctness 1, robustness 1): click on the selected movable marker retargeted to the box by pointer
capture → D6b decides on the press at pointerup (`useEmptyTap`), click path unchanged; tests 4.4 and e2e 3.
- MAJOR (correctness 2, robustness 2): blur commit at mousedown rebuilds the drawing, the click can be dropped →
pointerup decision; unit 4.14 moves focus at pointerdown; e2e 7 asserts the overview after one click.
- MAJOR (simplicity 1): Escape registry replaced by per-body bubbling handlers (structural « shown body only »).
- Folded minors: resolved selection (c4), « Plus » state kept local with a capture listener (c3, r5), isComposing
(c9), byDrawing in the D6b commit (c10, s6), EditorTabs comment (c11), isPrimary-based multi-pointer (s4, c8, r3),
hook in `src/catalogue` (s5), button built from `onShowAll` (s2), ShowAll untouched (s3), tests in existing files
(s7), one `isTextField` (s8), no ReferencesPanel edit (s9), gate outcomes section (s10), checklist reworded
(s11), drag test re-queries the marker (c6), event counts in touch e2e (c7, r4), equine step as its own last test
(r6), focus-on-body limit (r7), no « Désélectionner » during a tracing (r8), server-seeded fixture (r9).
## Re-challenge record (rev 2 → rev 3; correctness CONCERNS(2), robustness FATAL(2))
- BLOCKER (robustness 1) + MAJOR (correctness 1): a touch deselect at pointerup moves the layout (SelectionTag,
hint) before Chromium builds the tap's click, which lands on what moved under the finger → touch applies the
verdict in its own click and only on a target without `[data-anno-id]`; mouse/pen apply at pointerup and swallow
the next click (`takeClick`); e2e 5 taps near annotations and the canvas bottom with a recorder.
- MAJOR (robustness 2): touch adjustment of a near-miss → deselect then reselect → same click-time rule; e2e 5.
- MAJOR (correctness 2) + minor (robustness 9): Escape from the header or tab row did not deselect → the shown body
listens on `document` while active (target body or inside the workspace); tests 11.
- Minors: « Désélectionner » keeps the field focused during the press (c3) with e2e 7; second finger outside the box
via a document capture listener (c4, r4); `verdict` on every pointerup (r4); contextmenu disarms (r3); vertex
handles documented and pinned (r5); equine test right after the copy creation (r6); recorder with pointercancel,
click targets, twin drag and two-finger at 375 (r7); impeccable and design review before the shell suite on the
final commit (r8). Rev 3 is not re-challenged (one re-challenge per run); the verifier, the security gate and the
code review judge the result.