chore(memory): R2 plan rev 3 and contract

This commit is contained in:
bchanot committed 2026-11-12 18:21:31 +01:00
1 parent f078b1eb96
commit 49867bad19
2 files changed
+397

No files matched your search

@@ -0,0 +1,245 @@
# PLAN — R2 « Références » tab (V1-2.6) — rev 2
Contract: `.claude/tasks/contracts/2026-11-12-r2-references-tab-1730.md`. Sources: `docs/development/V1-2-6_U1_CORRECTIONS.md`
§R2 (D1-D4), `docs/design/v1-2-6-r0/{ARBITRAGES.md A1-A5, REVUE.md, maquettes.html boards 23-27}`, TODO R2 block
(a1d4084), BDR-114, BDR-107..110, BDR-113. Read-before digest: analyzer 2026-11-12.
Rev 2 = rev 1 + challenge round 1 (correctness FATAL(5), robustness FATAL(7), simplicity CONCERNS(1)); changes tagged
[Cn] / [Rn] / [Sn] with the finding number.
Plan form (deviation from writing-plans « full code », stated): ~30 files; each task gives files, behaviour, test cases
and verification; executors write the code under TDD. Design = owner-validated boards (BDR-110), no brainstorm.
## Global rules
- Limits: 25 logic lines / function, 100 chars, 5 params, 5 locals, no global state; i18n through `useT()` with fr / en
parity; edits only through `useEditCommand` → store.commit (one history entry per action).
- Never touch supabase/, crates/, scripts/db-trial*, docker/, packages/supabase/src, components/catalogue/ (reader
unchanged) [C9]. No db:trial, no DEV.
- Shell runs: `pnpm db:sandbox e2e-shell <explicit spec list>`; NEVER `editor-equine.spec.ts` (owner §3).
- Data guard [R6]: before and after each shell session, per-id snapshot of pre-existing rows of `anatomical_sheets`
(id, status, archived_at, updated_at) AND `anatomical_sheet_versions` (id, status, the revision / updated_at columns,
md5(content::text)); compared per id (changed or missing = stop); new rows counted and their sheet ids listed per run
(owner §3 fixture tracking). Select-only through `pnpm db:sandbox sql`.
- Key removal [R10]: before removing any i18n key or helper, grep src, tests and e2e INCLUDING editor-equine; equine is
reported « updated, not run ».
- R-24: every removed or rewritten assertion mapped in the sub-lot commit body.
- Design floor: `impeccable detect <changed .tsx>` on R2.1-R2.4.
## Decisions (owner answers marked [owner])
- P1 [S1] The panel is no navigation place: no `EditorTarget` variant. It opens only through the action
`open_citations(citedBy, opener)` (renamed `open_references`, `citedBy` required). Its DOM place name is `citations`
(`data-place`, PlaceName member only for its heading and focus scope). R2.1 removes the panel target from
`EditorTarget`, `placeOf`, `placeKey`, `moveText` and the panel's own focus-request handler.
- P2 « Type » sort = REFERENCE_TYPES order, ties in sheet order.
- P3 « Aller à » a reference hidden by the tab search: clear the search only, open the tile, focus it (P8); other open
tiles stay open (A2).
- P4 [C6] « Tout afficher dans l'onglet Références » = its own action `show_all_references`: closes the panel, then
(after exit, P9) selects the tab with a reset signal (search and sort reset, open tiles and a tile in edit kept),
focus on the tab heading. Vérification's unresolved reference path selects the tab WITHOUT reset.
- P5 [owner] family trigger → same panel, family words.
- P6 [C2][R2] focus fallbacks, in order: the trigger (re-found by `data-citations-trigger=<element key>`) if shown →
else the active tab button via `focusActiveTab()` (« Plus » button below 640 px). Never a missing heading.
- P7 panel: no search, add, delete, reorder (board 25).
- P8 [C8] focus target of a reference = the tile's disclosure button, carrying only `data-focus-key` (natural tab
stop, no `tabIndex=-1`); the tile is opened first.
- P9 [C1][R1][R8] Panel closing is uniform: every close (✕, Escape, scrim, « Tout afficher », « Aller à » from a panel
tile, element vanished, tab switch) records ONE pending move (target + focus) in the workspace; the panel animates out
(`motion/react` AnimatePresence, enter 180 ms decelerate, exit 140 ms accelerate, translateX only, scrim opacity same
timings; `useReducedMotion` → no transition); `onExitComplete` lifts the page `inert`, keeps
`ReferencesOpenContext` true until then, and applies the pending move. The panel is `inert` during exit and
unmounted after. Focus helpers report « found » only when `document.activeElement` is the target. Page inert through
exit is kept (approved CORRECTIONS §R2 text, owner « y compris pendant son animation de sortie »).
- P10 editor-equine: helper calls updated, never run.
- P11 [owner] 640-1 023 px: five tabs, row may wrap, no horizontal scroll.
- P12 [R11] tab search: explicit Escape handler: non-empty query → clear + `preventDefault`; empty → let it bubble (A5).
- P13 trigger gains `aria-expanded` + `aria-controls="editor-citations-panel"`.
- P14 tile ids prefixed by host (`tab-` / `panel-`).
- P15 [owner] « Retirer … » marks the element « À confirmer » (core rule); documented; one « Défaire » restores both.
- P16 [C4][C5][R5] Geometry: the Places container gets `overflow-x: clip` (never `hidden`: sticky must keep working)
and NO open-state `min-h` toggle; the panel wrapper is `absolute inset-y-0 right-0 w-[min(34rem,100%)]`, the panel
inner `sticky top-14 h-full max-h-[calc(100dvh-3.5rem)]` with its own scrolling list, so it never exceeds the
container: document height and width never change on open / close / during motion. Heading focus on open uses
`preventScroll` and happens after enter completes.
- P17 labels table file: `docs/development/V1-2-6_R2_LABELS.md`.
- P18 [S4] count wording: reword `editor.references.cited_*` in place to « Citée {n} fois » (capital) and add
`editor.references.uncited` « Non citée »; no parallel keys.
- P19 [S3] one memoised `citersOf(doc): Map<refId, CiterItem[]>` (families and nodes at any depth); tile count =
list length; `citationCounts` derived from it (or removed with its last consumer).
- P20 [C3][R2] After « Retirer … »: focus the next tile's disclosure button, else the previous, else the panel heading;
zero citations left → the panel stays open with the line « Ce constat ne cite plus aucune référence. » / « Cette
famille ne cite plus aucune référence. » (new provisional labels) + « Tout afficher »; close then follows P6 (the
trigger is gone when its count is 0).
- P21 [C2][R2] Selecting a tab while the panel is open closes it (pending move = the tab; focus on the new tab button).
Défaire / Refaire stay usable with the panel open; an undo that removes the element triggers P6.
- P22 [R3] Leaving edit is guarded: « Terminer », switching `editingId`, « Ajouter » while another tile is in edit,
and closing the panel with a tile in edit first commit the pending field; on refusal the tile stays in edit, the
refused field shows its message and takes focus, and the leave is cancelled.
- P23 [R4] Pinning: while `editingId` (or the add draft) is set, that tile stays in the shown set at its current index
whatever the sort or search, until it leaves edit.
- P24 [C12] Add: « Ajouter une référence » resets search and sort, appends a draft tile in edit (Type « Choisir… »,
Citation focused); « Ajouter la référence » creates it in one modification; on success the tile stays open, leaves
edit, focus on its disclosure button.
- P25 [S2] `ReferenceLibrary` (R2.1 extraction) is folded into `ReferencesTab` at R2.4; only `ReferenceTile` is shared.
- P26 [C9] links: `editor/references/safeLink.ts` (http / https only; DOI → `https://doi.org/<encoded doi>`);
`target="_blank" rel="noopener noreferrer"`; the catalogue's `safeHref` is not touched.
## R2.0 — rename the panel's DOM place (no visible change) — `refactor(editor): …`
Scope [S1][C10]: the `data-place` / KeptPlace `name="references"` literal, the PlaceName member, `headingOf`,
`ownedBy` uses, DOM ids `editor-references-panel` / `editor-references-title` → `editor-citations-*`;
`editor/annotations/deselect.ts` only if it names the place; tests and e2e literals. Not renamed (deleted in R2.1): the
EditorTarget variant, MoveKinds.
E2E [S7]: library assertions routed through one helper (`libraryRoot(page)`) in `e2e/support/editor.ts`, so R2.1
changes one line; `place(page,'citations')` only at the true panel sites.
Proof [R9][C10]: `grep -rnE "['\"]references['\"]" apps/app/src apps/app/tests apps/app/e2e` reviewed hit by hit (each
remaining hit justified in the commit body), plus `name="references"` absent.
Gate: typecheck, lint, test:run, build; e2e:shell crossing, journeys, shell, structures, deselect, access,
shell-layout + data guard. Commit + push.
## R2.1 — five tabs, navigation, library in the tab — `feat(editor): …`
- `tabs.ts` five tabs; `SHOWN.small` unchanged (« Plus » = general, findings, references); `REFERENCES_BUTTON_ID`
removed. `EditorTabs.tsx` row may wrap (P11).
- `components/editor/tabs/ReferencesTab.tsx` in `EditorTabBody` BODIES; h2 « Références » with `data-place-heading`;
hosts `ReferenceLibrary` (list of the current cards, form, DeleteDialog, search), ids `tab-` (P14).
- `navigation.ts`: reference keys → `{place:'tab', tab:'references', key}`; panel EditorTarget removed (P1);
`open_citations(citedBy, opener)`; `show_all_references` (P4); `select_tab` closes the panel (P21); pending move
plumbing (P9) introduced here with the current (non-animated) panel so focus rules hold from R2.1.
- `verification.ts` reference issues → tab; `useEditorNavigation.ts` landing on the tab heading; fallbacks P6.
- Header button, separator and props removed (HeaderActions, DraftHeader, EditorWorkspace).
- Trigger (FindingContent): `open_citations`, `data-citations-trigger`, `aria-expanded`, `aria-controls` (P13).
- i18n: `editor.tab.references`; removals per [R10].
- E2E [C7][R7]: tier-aware `openTab(page, dict, tab)` (opens « Plus » below 640 px); `TABS` five; each existing
`openReferences` call mapped explicitly (R-24 table in the commit body) to `openTab(…,'references')` (library) or
`openCitations(page, dict, element)` (panel), keeping today's narrow-width panel axe and overflow checks through
`openCitations` at 320 / 375 / 768 / 800 px; `warm-up.ts` uses the tab (same commit).
- Unit tests rewritten with R-24 mapping (editor-mode, editor-route, editor-references-panel → finding path only [S2],
editor-tabs-lists, editor-navigation, editor-focus-request, editor-keep-alive, editor-escape (A5 panel layer through the
trigger), editor-no-loss(-decisions), editor-route-recovery, editor-verification); new: select_tab closes panel,
P6 fallbacks, Vérification « Aller à » reference → tab + focused row.
Gate: typecheck, lint, test:run, build, e2e:ui, e2e:shell (editor-* except equine, admin, shell, journeys) + data
guard; impeccable detect. Commit + push.
## R2.2 — collapsible tiles — `feat(editor): …`
- `ReferenceTile.tsx` (board 23 / 24 C / D / 27): header `<button aria-expanded aria-controls>` (≥ 44 px, P8), 2-line
clamp, meta column (type badge, « Citée {n} fois » / « Non citée »), phone meta row; open body `dl` Type / DOI / URL
via `safeLink` (P26) else « Aucun » / « Aucune »; « Citée {n} fois, par : » list from `citersOf` (P19) with
« famille » badge and « Aller à » (44 px) or the empty line; actions « Modifier »; « Supprimer » only uncited (existing
DeleteDialog) else the hint; « Monter » / « Descendre » (R2.3 decides visibility).
- Edit mode (24 D): title « Modifier la référence », Type | DOI, Citation textarea focused, « Adresse web (URL) »,
cited rows, only « Terminer » with the P22 guard; pinning P23.
- Tab state kept mounted (A2): `openIds`, `editingId`; reset on editor reopen.
- Read-only (24 C): no edit control; DOI, URL, « Aller à » kept.
- Unit: disclosure keyboard, several open, cited hint vs uncited Supprimer, edit hides actions, P22 refusals (schemeless
URL, blank citation) keep edit and focus the field, edit survives a tab change, read-only, `javascript:` never a
link, counts = list length including families, several findings citing one reference.
- E2E: start `e2e/shell/editor-references.spec.ts` (tiles closed / open / edit, read-only twin at 375 via « Plus »,
axe on closed / open / edit, keyboard walk through tile headers).
Gate: as R2.1 + the new spec. Commit + push.
## R2.3 — search, sort, count, add, reorder — `feat(editor): …`
- `editor/references/sort.ts` `sortReferenceIds` pure (sheet / citation with `Intl.Collator(locale,
{sensitivity:'base', numeric:true})` / count desc / type P2; ties in sheet order); new array, inputs untouched.
- Toolbar (23 / 24 / 27 B): search + « Effacer la recherche » (focus back) + P12 Escape; « Trier par » external label +
native select; count « {n} références » / « {n} références sur {total} »; « Ajouter une référence » (edit modes).
- No result (24 B): notice + « Effacer la recherche » button.
- A1 move buttons only in sheet order without search, else the hint line.
- Add P24; pinning P23; « Aller à » P3 / P8.
- Unit: each sort stable on a fixture (equal citations, accents, numbers, mixed types); document text + history length
identical before / after every sort and search; clear button; no-result notice; A1 matrix; add flow; P23 (edit under
citation sort and under search keeps the tile in place); Vérification « Aller à » hidden tile.
- E2E (editor-references.spec): four sorts visible order, search / clear / no result, A1, add, delete uncited, server
document and revision unchanged after sorts / searches.
Gate: as R2.2. Commit + push.
## R2.4 — contextual panel — `feat(editor): …`
- `CitationsPanel.tsx` (board 25): overlay geometry P16; header book icon + « Références citées » + ✕ 44×44 « Fermer
les références »; path line; count line « {n} références citées par ce constat / cette famille » + « Tout afficher dans
l'onglet Références » (P4); tiles (meta 132 px) with « Modifier », « Retirer de ce constat / cette famille » (P15,
P20), « Aller à »; « ce constat / cette famille » badge; P7; zero state P20.
- Motion and focus P9, P6, P21, P22 (close with a tile in edit); `ReferenceLibrary` folded into `ReferencesTab` (P25).
- Unit: open only through the trigger; filtered; family words; Retirer removes only that id, reference stays, one undo
restores (and the review status); P20 focus chain and zero state; P4 reset + heading focus; every close path applies
its pending move after exit and the focused element is the expected one (activeElement); P21; P6 after undo; reduced
motion (no transition) vs normal; inert page and panel during exit; `ReferencesOpenContext` until exit; read-only: no
Modifier / Retirer.
- E2E [C11][R7]: `e2e/shell/editor-citations.spec.ts` in THIS sub-lot: desktop + 375 px (full-width panel via
« Plus » → Constats): open, filtered, Retirer + Défaire, Tout afficher, each close path with `document.activeElement`
checked after exit, Escape (A5), inert during exit (keyboard cannot reach the page), reduced motion
(`emulateMedia`), axe open (edit and read-only). Widths / shift only in `editor-shell-layout.spec.ts` [S6]: 1 024,
1 180, 1 279, 1 280 + 375, panel ≤ 34 rem and ≤ viewport, `documentElement.scrollWidth` / `scrollHeight` sampled
before, during (motion on) and after open and close [R5].
Gate: as R2.3 + citations spec + layout spec. Commit + push.
## R2.5 — non-regression sweep — `test(tests): …` (only if changes are needed)
- Full gates on the final state: typecheck, lint, test:run, build, e2e:ui, e2e:shell ALL specs except
`editor-equine.spec.ts` (explicit list), the two new specs run twice; data guard; R-24 audit of the whole R2 diff
(no assertion lost without a mapped replacement); gaps found here are fixed in this sub-lot.
## R2.6 — docs, labels, closure — `docs(…): …`
- `docs/development/V1-2-6_R2_LABELS.md`: every new / changed / removed key (key, FR, EN provisional, where, family
variants, ambiguity notes).
- `RUST_ARCHITECTURE_REVIEW.md` Part II §II.2 rows (class C, phase n/a) for `editor/references/{filter,citations,sort,
safeLink}.ts` + §II.3 bullet (BDR-114 A).
- `V1-2-6_U1_CORRECTIONS.md` §R2 status (incl. P15 « À confirmer », P20, P21); `BROWSER_TESTS.md` (new specs, equine
excluded); `V1-2-6_OWNER_TRIAL.md` R2 db:trial protocol; `CLAUDE.md` tree.
- Then STEP 5 (fresh verifier on the enriched contract, security), STEP 6 code review (opus), doc sync, capitalize;
stop at the checkpoint.
## Verification per sub-lot
SDD per task (implementer sonnet + spec review + quality review) → sub-lot gate → commit + push; a red gate blocks the
commit. Fresh verifier + security + code review on the whole of R2 at the end.
## Risks kept
- Larger R-24 mapping load (13 unit files, 8 specs, warm-up) → per-commit tables.
- happy-dom cannot show layout, motion or inert focus loss → each is proven in Chromium in the same sub-lot.
- editor-equine updated but unverified until its separate fix.
## Rev 3 — challenge round 2 (robustness FATAL(5), correctness CONCERNS(2)); these override rev 2 where they differ
- G1 [R2-1 BLOCKER] Shell commands use full paths only (`e2e/shell/<name>.spec.ts`), never a bare token (`shell`,
`editor-` match every file: Playwright args are regexes on the absolute path). Mandatory preflight before every run:
`pnpm db:sandbox e2e-shell --list <same args> | grep -q editor-equine && abort`. Each gate below lists its exact files.
- G2 Data guard queries run inside `begin transaction read only; … rollback;` [R2-12].
- P22' [R2-2][C2-1] Leave guard covers EVERY edit field of the tile: fields expose their draft through a tile-level
registry; leaving re-commits each field whose draft ≠ document value; any refusal blocks the leave and focuses that
field. Unit: « A refused, then B committed OK, then Terminer » keeps edit.
- P22'' [R2-3][C2-2] The panel registers `canLeave(): boolean` with the workspace; every USER close (✕, Escape, scrim,
Tout afficher, Aller à, tab click) calls it before recording the pending move; refusal cancels the whole close (tab not
switched). FORCED closes (element vanished, read-only flip, conflict reload) proceed; a refused draft is dropped and
announced in the live region (new provisional label « Saisie non appliquée : … »).
- P23' [R2-4][R2-14] Pin only when sort ≠ sheet order or a search is active; in read-only the pin is suspended and the
tile renders read view; the add draft is kept in an EditOnly-style hidden container and resumes when editable;
`openIds` / `editingId` pruned of ids absent from the document on each render.
- P27 [R2-5] Panel and workspace Escape handlers ignore `isTextField(target)` and `isComposing` (A5: a field keeps
Escape); unit + e2e: Escape in a panel tile textarea neither closes nor commits.
- P28 [R2-6][R2-7] During exit: a second close is a no-op; a tab select replaces the pending move; the pending focus is
skipped if the user moved focus off `body`; a one-shot fallback timer (exit duration + 100 ms) lifts inert and applies
the move if `onExitComplete` has not fired.
- P9' [C2-3] `onExitComplete` only sets state (exiting=false + pending move); focus is applied by the existing
`useMoveFocus` effect after that commit (never inside the callback).
- P16' [R2-8][C2-4][C2-5] `overflow-x: clip` on the panel's absolute wrapper only (translateX on the inner panel); tab
content keeps its focus rings. Places gets a PERMANENT (never toggled) `min-h-[calc(100dvh-3.5rem)]` so the panel and
scrim reach the bottom as on board 25 and the document height never changes on open / close (shown at the gate).
- P29 [C2-6] Reduced motion keeps the same AnimatePresence with zero-duration transitions (callbacks fire); focus on
open after enter completes in both modes. Deviation from the CORRECTIONS text (« Tailwind motion-reduce: » + « class »
test): `motion/react` `useReducedMotion` (MobileDrawer precedent), shown at the gate.
- P30 [R2-9] Dangling citation ids: the panel lists them as « Référence introuvable » rows with « Retirer » (new
provisional label); trigger count, panel count and zero state use the same list.
- P31 [R2-10][C2-8] Tile UI state, DOM ids and focus keys use position + id (duplicates stay visible and distinct);
sort works over positions.
- P26' [R2-13][C2-9] DOI link: strip a leading `doi:` / `https://doi.org/` / `http://dx.doi.org/`, link only
`^10\.\d{4,9}/\S+$`, encode per segment keeping `/`; test with the seed DOI `10.1892/0891-6640(2002)016<0697:toih>2.3.co;2`.
- P6' [R2-11] Trigger re-found by comparing `dataset` values, never a raw attribute selector.
- E1 [C2-7] e2e seeded shape gains one reference cited by one finding (counts in other specs checked); the two layout
tests that opened the panel over the drawing are remapped: drawing box measured before open and after a P21 switch to
Annotations (the panel no longer exists on Annotations).
- E2 [R2-15] Timing checks sampled in-page with a rAF loop started before the click (or `page.clock`), asserting the
`inert` attribute, not a racing key press.
- E3 [C2-10] R2.1 interim panel: its add form and search are dropped; `gone` wired to the P6 close path; `onShowAll`
only for « Tout afficher ».
### Exact shell gate file lists (G1)
- R2.0: e2e/shell/editor-shell-crossing.spec.ts e2e/shell/editor-shell-journeys.spec.ts e2e/shell/editor-shell.spec.ts
e2e/shell/editor-structures.spec.ts e2e/shell/editor-deselect.spec.ts e2e/shell/editor-access.spec.ts
e2e/shell/editor-shell-layout.spec.ts
- R2.1-R2.4: the R2.0 list + e2e/shell/editor-annotations.spec.ts e2e/shell/editor-geometry.spec.ts
e2e/shell/editor-journey.spec.ts e2e/shell/editor-recovery.spec.ts e2e/shell/editor-drawings.spec.ts
e2e/shell/editor-signout.spec.ts e2e/shell/admin.spec.ts e2e/shell/shell.spec.ts + the new R2 specs as they land
- R2.5: every file of `ls e2e/shell/*.spec.ts` except editor-equine.spec.ts, written out in full in the command.