docs(docs): R0 boards, U1 corrections plan and trial stack plan

Owner brief of 2026-11-09 after the first U1 trial. Boards 23-30 (proposal), lots R0-R4 with arbitrations A1-A15, persistent trial stack plan. No code.
This commit is contained in:
bchanot committed 2026-11-09 16:13:04 +01:00
1 parent 8cb681e2fa
commit 3d64146164
17 files changed
+1403

No files matched your search

+171
View File
@@ -0,0 +1,171 @@
# V1-2.6 U1 corrections after the owner's first trial
Status: PROPOSAL, 2026-11-09. Owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire » (2026-11-09),
answering the trial diagnosis of the same day. Design, documentation and plan only: nothing here authorises code.
Lot R0 (boards) is delivered in `docs/design/v1-2-6-r0/` and awaits the owner's graphic validation; R1 to R4 start
only on their own explicit authorisation. Contract: `.claude/tasks/contracts/2026-11-09-v1-2-6-trial-arbitrations.md`.
Companion: `TRIAL_STACK.md` (the dedicated manual trial stack, request §5).
## 1. Owner decisions (2026-11-09)
| # | Decision |
|---|---|
| D1 | A fifth main tab « Références » between Constats and Vérification becomes the main access to the reference library. The header « Références » button is removed. |
| D2 | A contextual panel stays, opened from a finding's detail, filtered on its citations, with « Tout afficher » leading to the tab. About 34 rem wide within the available space, a lateral slide of 150 to 200 ms, `prefers-reduced-motion` honoured. |
| D3 | The tab shows collapsible tiles: closed = short citation, type, citation count; open = full information, DOI, URL, actions. Instant search with a clear button. Sort by document order (default), A to Z, citation count or type. Sorting never changes the document; reorder commands only while document order is shown. |
| D4 | Kept: unsaved changes, focus, « Aller à », permissions, read-only mode, accessibility tests. Below 640 px, Références goes in the « Plus » menu. Boards validated before any UI code. |
| D5 | History reads « Défaire » / « Refaire » instead of « Annuler » / « Rétablir », with explicit accessible names, the keyboard shortcuts kept and the distinction from dialog « Annuler » buttons kept. |
| D6 | A « Désélectionner » button near « Supprimer ». Escape deselects when no dialog, priority panel, menu or tracing in progress consumes it. Deselecting is interface state: no document change, no history entry. A click on an empty part of the drawing is left to U2. |
| D7 | Sheet list: instant search with clear, sort by last modification (default) or name, the last-modification date visible, better Administration home cards. No section built on UUIDs, names, slugs or test conventions; generic for every species; no artificial test filter. |
| D8 | A dedicated, persistent manual trial stack, separate from the automated sandbox: technical plan only, nothing created, reset or deleted now (`TRIAL_STACK.md`). |
| D9 | Three separate test anomalies tracked apart from U1 and U2: A fictitious fingerprints, B working copy never archived by `sheets-admin.sandbox.ts`, C integrity failure invisible in catalogue cards (section 5). |
| D10 | Lots R0 (boards), R1 (history labels, deselect), R2 (References tab), R3 (sheet list), R4 (catalogue integrity warning, independent fix). Any SQL schema or Rust core change needs its own checkpoint. |
## 2. What these decisions supersede
| Earlier validated item | Where | New state |
|---|---|---|
| U1 AC1: « no … « Références » … tab remains » | U1 contract `.claude/tasks/contracts/2026-11-06-v1-2-6-ux-u1-1123.md:373-375` | Five tabs (D1). |
| U1 AC3: panel opened from the header button and from a finding; focus back to the opener, else the header button | same contract :381-389 | Opened from a finding only; focus back to the finding's « n référence(s) » button. Scrim, `inert` tab panels, Escape / ✕ / scrim close and read-only behaviour unchanged. |
| U1 AC4 and T15 (history part): visible « Annuler » / « Rétablir », name « Annuler la dernière modification » | contract :390-397, `V1-2-6_UX_DECISIONS.md:309-322` | « Défaire » / « Refaire » (D5). T15's form wording (« Abandonner », « Abandonner les modifications ») unchanged. |
| U1 AC10: no horizontal scroll with the references panel open | contract :420-421 | Kept, re-checked with the 34 rem panel. |
| U1 AC12, AC13: « Aller à » a reference opens the side panel | contract :425-431 | « Aller à » a reference opens the Références tab, the tile open and focused. |
| U1 AC17: panel tests « open from header and finding »; keyboard order with the panel | contract :439-446 | Tests rewritten for the tab and the finding-only panel; the panel keeps its place in the keyboard order when open. |
| Checkpoint choice 5: Général and Constats under « Plus » below 640 px | `V1-2-6_UX_U1_CHECKPOINT.md:24` | Général, Constats and Références under « Plus ». |
| Checkpoint choice 10: search on citation, DOI and URL; ↑/↓ only on the unfiltered list | same file :29 | Carried to the tab: same search fields; reorder only in document order and without an active search. |
| Checkpoint choice 15: « Références » announced as a panel | same file :34 | Announced as a tab, like the four others. |
| Board 11 (references side panel as the main access) | `docs/design/v1-2-6/11-constats-references-desktop.png` | Replaced by boards 23 to 27 once validated. |
| BDR-099 item 5 (collapsible references rejected) | memory | Not contradicted: it concerned the catalogue page on a phone (`docs/design/README.md`, accepted deviation 2), not the editor. |
| U2b F5 (filter panel in the references panel's slot) | `V1-2-6_UX_FINDINGS_NAV.md:104-126` | Unaffected: the panel slot stays, used by the contextual references panel now and by the filter panel in U2b. |
## 3. Lots
Every lot: one commit or more per coherent change, pushed; gates in this order: `pnpm typecheck`, `pnpm lint`,
`pnpm test:run`, `pnpm build`, `pnpm e2e:ui`, then the shell suite on the sandbox as it stands, with its exact result
(the suite is not green today: four `admin.spec.ts:717` failures from the taken working-copy slot, anomaly B). Every
removed or rewritten assertion is mapped to its replacement in the commit message (R-24). Design gates: the boards of
R0 as validated, `impeccable detect` on the changed components, a fresh design review before the lot closes.
### R0 — Boards and owner validation (this delivery)
Boards 23 to 30 in `docs/design/v1-2-6-r0/` (sources, data generated from the equine draft, `REVUE.md`). Exit: the
owner validates each board, or asks for corrections; the validated boards then join `docs/design/README.md` as the
reference of R1 to R4.
### R1 — History labels and deselection (D5, D6)
- Labels: `editor.history.*` keys in `apps/app/src/i18n/fr.ts` and `en.ts` (FR « Défaire » / « Refaire », names
« Défaire la dernière modification » and « Refaire la dernière modification défaite »; EN « Undo » / « Redo »
unchanged); `HistoryButtons.tsx` keeps its structure. Shortcuts unchanged: Ctrl/⌘+Z undo, Ctrl/⌘+Maj+Z redo
(`apps/app/src/editor/useUndoShortcuts.ts:19-23`). Every prose string that names the history « Annuler » is
reworded; dialog « Annuler » buttons untouched.
- « Désélectionner »: a secondary button beside « Supprimer » (`PropertiesPanel.tsx:257-284`), shown while an
annotation is selected, in read-only modes too (selection is interface state); it dispatches the existing
« no selection » path that « Toutes les annotations » uses (`PropertiesPanel.tsx:93-108`).
- Escape: today a tracing consumes it when the canvas box has focus (`usePlacement.ts:82`), the references panel
when not already handled (`ReferencesPanel.tsx:234`), dialogs natively (`ModalDialog.tsx:111`). One handler on the
workspace, at the bubbling phase, deselects only when `event.defaultPrevented` is false, no dialog is open, no menu
is open and no tracing runs; each consumer marks the key handled. The « Plus » menu's own Escape path is checked
first (it has no explicit handler today).
- Unit tests: deselect leaves the document text and the history length unchanged; undo after a deselect undoes the
previous edit; the Escape matrix (dialog, menu, panel, tracing, nothing open) with one consumer each time; focus
after « Désélectionner » on the annotation's list row (arbitration A6); accessible names of both history buttons in FR and EN; read-only modes
show « Désélectionner » and no « Supprimer ».
- E2E: the journeys that name « Annuler » / « Rétablir » rewritten one for one; a new desktop spec for the button and
Escape; axe on Annotations with a selection.
### R2 — The Références tab (D1 to D4)
- Tab model: `EDITOR_TABS` gains `references` between `findings` and `verification` (`apps/app/src/editor/tabs.ts:6-11`),
`SHOWN.small` keeps it under « Plus » (:18). The id collides with the panel's `data-place` name `references`: the
panel place is renamed first (internal name, no visible effect). Touched with it: `navigation.ts` `targetOfKey`
(:65-81, reference keys go to the tab), `focusRequest.ts:19-22`, `useEditorNavigation.ts`, `EditorTabBody.tsx:16-23`,
`EditorWorkspace.tsx:85-131`, `verification.ts`, i18n keys.
- Tab content: tiles built from `ReferenceRow` / `ReferenceForm` (`components/editor/references/`), a disclosure
button per tile (`aria-expanded`, `aria-controls`), the toolbar with a search field and its explicit clear button
(focus back to the field), a native `<select>` with its external « Trier par » label. Tile count reads « Citée N
fois » (citations from families and findings, as `citations.ts` counts them); the open tile names a family as a family.
« Ajouter une référence » appends in document order, resets search and sort, opens the new tile in edit with focus
on its citation field. Sorting is a pure function over the reference ids that never
touches the document: document order; citation A to Z with `Intl.Collator` of the current language; citation count
descending, ties in document order; type in the order of the type list, ties in document order. Search keeps
`filter.ts` (citation, DOI, URL, `folded`).
- Panel: opened only from a finding (`EditorWorkspace.tsx:94` width becomes `min(34rem, 100%)`), slide from the right
in 150 to 200 ms with a shorter exit, no slide under `prefers-reduced-motion` (Tailwind `motion-reduce:`); the panel
stays mounted during its exit and the page stays `inert` until the exit ends (LRN-085); no permanent `will-change`
(LRN-045). The header button and its focus fallback are removed (`HeaderActions.tsx`, `REFERENCES_BUTTON_ID` in
`tabs.ts:57`).
- Unit tests (about 15 files today assert the four-tab structure or the panel): five tabs and the « Plus » tier at
500 px; each sort, stable, document untouched (text compared before and after); reorder commands present only in
document order without search; clear button; tile disclosure and focus; « Aller à » from Vérification opens the
tab, the tile open and focused; « Aller à » from a tile reaches the finding; the panel from a finding: filtered,
« Tout afficher » opens the tab with search and sort reset and focus on its heading, close returns focus to the
finding's button; unsaved edits in a tile form survive a tab change (kept-mounted places); no edit control in any
read-only mode or without the editor right; the reduced-motion class.
- E2E: `TABS` helper (`e2e/support/editor.ts:327`) to five; `editor-shell-journeys.spec.ts:116-125` count 4 to 5;
layout specs with the panel open at 1 024, 1 180, 1 279, 1 280 px (no horizontal scroll); 375 px « Plus »;
axe on the tab (tiles closed and open) and on the panel; keyboard walk of the new order; about 28 panel open/close
calls rewritten.
### R3 — Sheet list and Administration home (D7)
- `AdminSheetsRoute.tsx`: search on the sheet name in both languages (`folded`, accents ignored) with a clear
button, a « Trier par » select (last modification descending by default, name A to Z by `Intl.Collator`), the
result count, the date on each row; the four filters unchanged (`apps/app/src/admin/filters.ts`).
- `AdminHomeRoute.tsx` « Fiches officielles » card (`CARD_SHEETS = 5`, :25): the five most recently modified sheets
with species, status and date, and « Voir les N fiches ».
- Date source (arbitration A7): the list payload carries `anatomical_sheets.updated_at`
(`supabase/migrations/20261102100000_sheet_admin_reads.sql:54`), which a draft save does not move:
`save_sheet_draft` writes `anatomical_sheet_versions` only (`20261028110000_sheet_review_workflow.sql:569-630`). On
the sandbox, 28 of 219 official sheets have a version newer than the sheet row. A true « dernière modification »
needs one read change in SQL (a `last_modified_at` field, greatest of the sheet's and its versions' `updated_at`,
in `private.official_sheet_admin_summary`; no table, policy or privilege change), hence an SQL checkpoint, pgTAP,
regenerated types, and its application to the sandbox, which needs the owner's go for that operation.
- Search and sort run in the browser on the full list: `shortcut:` until RR-13 pages the list on the server, where
search and sort move with it.
- Tests: unit for search (accents, both languages, empty, clear), sort (date ties by name, collation), date format
FR/EN, the home card (at most five, sorted); e2e admin list search and sort at desktop and 375 px with axe; the four
filters unchanged.
### R4 — Integrity warning in catalogue cards (D9 C, independent fix)
- The card already runs the integrity check: `useCardDetails` calls `loadVersion` and drops a failed load in
silence (`apps/app/src/catalogue/useCardDetails.ts`, `if (!load.ok) return`). R4 keeps the failure kind in the
card's state and shows a warning inside the card; the sheet page's `CatalogueFailureNotice` is unchanged. No SQL,
no Rust: the check stays the core's `check_published`, never bypassed.
- Tests: unit for a card whose load fails with `fingerprint_mismatch` (warning shown, link kept) and with a transport
failure (its own line and « Réessayer », arbitration A10); e2e on a catalogue entry whose stored fingerprint differs, built by
the test itself (never by editing an existing sheet); axe on the list.
- Its own commit and verification, kept out of the U1 shell lots.
## 4. Order and dependencies
R0 first (validation). R1 is independent of R2 and can ship first. R2 depends on the validated boards 23 to 27. R3
depends on arbitration A7; with the SQL option, its migration goes through its own checkpoint before the UI part.
R4 is independent and may run any time after its board (30) is validated. Anomaly B (section 5) should land before
the gates of R2 and R3 are read, since its taken slot fails four admin specs on every run.
## 5. Test anomalies tracked apart (D9)
| Item | Cause | Constraint |
|---|---|---|
| A. Fictitious fingerprints | Worker stand-ins publish with `'a'.repeat(64)`: `packages/supabase/tests/sandbox/sheet-fixtures.ts:115` (`openRound`), `sheets-concurrency.sandbox.ts:168`, `sheets-perf.sandbox.ts:169`. Seven published or deprecated versions on the sandbox fail `check_published`; the owner opened three of them on 2026-11-09. | Compute the real fingerprint through the core as the catalogue e2e does (`fingerprintOf`), never weaken the publish gate or the reader's check. |
| B. Working copy never archived | `packages/supabase/tests/sandbox/sheets-admin.sandbox.ts:181-195` creates the historical sheet's working copy (`8c315a12-…`, 2026-11-08 21:00:30) and never archives it; the single slot then disables « Créer une copie de travail » (`WorkingCopyAction.tsx:88`) and fails `admin.spec.ts:717` four times. | Make the suite independent (its own cleanup, or a precondition it creates and removes); the existing copy is not touched before the owner authorises it. |
| C. Silent card failure | Section 3, R4. | Show the failure, never hide or route around it. |
## 6. Arbitrations for the owner
| # | Question | Recommendation |
|---|---|---|
| A1 | Reorder commands with a search active in document order | Hidden, as checkpoint choice 10 already rules (moving among a hidden subset is ambiguous); one hint line. |
| A2 | Tiles open at once; how long open state, search and sort last | Several open at once; kept while the editor stays open (kept-mounted tab), reset when it reopens. |
| A3 | Actions in the contextual panel | Modifier, « Aller à »; no add, no reorder. Every reference in the panel is cited by the finding, so « Supprimer » would always be refused by the core (no dangling reference): offer « Retirer de ce constat » (removes the id from the finding's citations, an ordinary undoable edit) instead, or nothing. « Tout afficher » opens the tab with search and sort reset, focus on its heading. |
| A4 | Closed tile content | Citation on two lines at most, type, « Citée par N constats » or « Non citée ». |
| A5 | Escape priority | Dialog, then open menu, then contextual panel, then tracing in progress, then selection. |
| A5b | « Toutes les annotations » (top of the properties panel) already clears the selection | Keep both: « Désélectionner » sits where the eye is after acting on an annotation, as decided (D6); the top entry keeps its role of returning to the list. Alternative: rename the top entry. |
| A6 | Focus after « Désélectionner » (the button leaves with the selection) | The annotation's row in the list, as « Toutes les annotations » already does (`PropertiesPanel.tsx:92-102`, `focusRow`). |
| A7 | Source of the last-modification date | SQL read change `last_modified_at` with its own checkpoint (recommended). Without it, label the row « Fiche modifiée le » and accept that draft saves do not move it. |
| A8 | Date format | Absolute, « 9 nov. 2026, 12:06 » (EN « 9 Nov 2026, 12:06 »). |
| A9 | Administration home card | The five most recently modified sheets with species, status and date, then « Voir les N fiches ». |
| A10 | Catalogue warning wording | FR « Contrôle d'intégrité échoué : cette version ne peut pas être affichée. », a distinct line for a load that failed for another reason. |
| A11 to A15 | Trial stack: names, ports, old trial commands, account roles, key lifetime, backups | `TRIAL_STACK.md` section 6. |