Files
faunosteo/docs/development/V1-2-6_U1_CORRECTIONS.md
T

20 KiB

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 »: the annotation's list row if it still exists, else the drawing, with no new selection and a polite announcement (A6 as ratified); 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. A cited reference shows no « Supprimer » (the core refuses it): a hint explains how to delete it once each citation is removed (« Aller à », then « Retirer » in the finding's or family's detail); an uncited reference keeps « Supprimer » (owner verdict, board 23). « 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; a cited tile has no « Supprimer » and shows the hint, an uncited tile keeps it; the panel from a finding: filtered, « Retirer de ce constat » removes only that citation (the reference stays in the document) and one undo restores it, « 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 a stack, which needs the owner's go for that operation. Ratified (A7): the dedicated checkpoint is V1-2-6_R3_SQL_CHECKPOINT.md; R3 ships in two steps, search and name sort with no date first, the date, the date sort and the « most recent » card only once the SQL change is authorised and applied.
  • 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 ships search and name sort first; its date part waits for the SQL checkpoint (A7 ratified). 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

Status as of the brief « R0 — Décisions propriétaire et dernière validation graphique » (2026-11-09, BDR-108) and the owner's graphic verdict « R0 — Verdict de revue graphique propriétaire » (2026-11-09, BDR-109): every arbitration is settled. The owner-facing table with consequences, in French: docs/design/v1-2-6-r0/ARBITRAGES.md.

# Question Recommendation Status
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. RATIFIED 2026-11-09 (BDR-109), exact recommendation
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. RATIFIED 2026-11-09 (BDR-109), exact recommendation
A3 Actions in the contextual panel « Modifier », « Retirer de ce constat », « Aller à »; no add, no reorder, no « Supprimer » (always refused by the core there). « Tout afficher » opens the tab with search and sort reset, focus on its heading. RATIFIED: « Retirer de ce constat » removes only the finding's citation of the reference, never the reference; undoable through the editor history
A4 Closed tile content Citation on two lines at most, type, « Citée N fois » or « Non citée » (the count includes families). RATIFIED 2026-11-09 (BDR-109), exact recommendation
A5 Escape priority Dialog, then open menu, then contextual panel, then tracing in progress, then selection. RATIFIED 2026-11-09 (BDR-109), exact recommendation
A5b « Toutes les annotations » already clears the selection Keep both (D6). RATIFIED 2026-11-09 (BDR-109), exact recommendation
A6 Focus after « Désélectionner » The annotation's row in the list. RATIFIED with precision: the row if it still exists, else the drawing; focus never selects again; an accessible announcement
A7 Source of the last-modification date SQL read change last_modified_at, own checkpoint. RATIFIED: dedicated SQL checkpoint V1-2-6_R3_SQL_CHECKPOINT.md; until then no creation date shown as a modification date and no misleading sort
A8 Date format Absolute, « 9 nov. 2026, 12:06 » (EN « 9 Nov 2026, 12:06 »). RATIFIED 2026-11-09 (BDR-109), exact recommendation; shown only after the SQL checkpoint
A9 Administration home card The five most recently modified sheets with species, status and date, then « Voir les N fiches ». RATIFIED 2026-11-09 (BDR-109), exact recommendation; final state after the SQL checkpoint
A10 Catalogue warning wording FR « Contrôle d'intégrité échoué : cette version ne peut pas être affichée. », a distinct line with « Réessayer » for a load that failed for another reason. R4 ACCEPTED; wording RATIFIED 2026-11-09 (BDR-109), exact recommendation
A11 Trial stack command pnpm db:trial, prefix faunosteo_trial_, ports 58xxx and 5194. RATIFIED 2026-11-09 (BDR-109), exact recommendation (name, prefix, ports)
A12 Old db:sandbox trial* commands Remove once the trial stack is validated. DECIDED otherwise: kept for now, neither removed nor silently redirected
A13 Trial accounts admin with catalogue rights, owner if needed. DECIDED 2026-11-09: two accounts; practitioner = technical admin + sheet_editor, no owner, reviewer or publisher; not a production practitioner profile; O1 unchanged
A14 Key lifetime and secret renewal One year, rotate-keys. DECIDED 2026-11-09: one-year keys on the dedicated local stack, documented rotation, no secret in Git or logs, security review of the renewal
A15 Backup before every migrate Automatic, kept, never pruned without the owner. RATIFIED 2026-11-09 (BDR-109), exact recommendation