chore(docs): V1-2.6 UX U1 contract and challenged plan

Owner approach A and four choices recorded as gated clarifications.
Plan lots A to I after three blind challengers and one confirmation
pass; no application code, no DEV.
This commit is contained in:
bchanot committed 2026-11-06 12:37:04 +01:00
1 parent 846994b4ab
commit 2e46c14697
3 files changed
+954 -1

No files matched your search

@@ -0,0 +1,267 @@
# CONTRACT — v1-2-6-ux-u1
- date: 2026-11-06 | flow: ship-feature | branch: feature/v1-2-anatomical-sheets
- status: active
- worktree: /home/bchanot/Documents/faunosteo-v1-2 (every command runs from this absolute path; never from
/home/bchanot/Documents/faunosteo; never against DEV: the `supabase_*_faunosteo` containers are DEV; the throwaway
sandbox is `faunosteo_dbsandbox_*`, reached only through `pnpm db:sandbox …`)
- base: 846994b (T17 recorded, BDR-102). Commit in place, push each commit; no merge, no `gitflow.sh finish`
(T13), no sub-branch.
- spec: `docs/development/V1-2-6_UX_PLAN.md` §3 U1 and §2 G (undo rules), `docs/development/V1-2-6_UX_TESTS.md` U1,
`docs/development/V1-2_ANATOMICAL_SHEETS.md` §8.2-§8.4 and §17.12 as amended, the level-1 contract
`.claude/tasks/contracts/2026-11-03-v1-2-6-editor-1509.md` with its U0 notes and header precedence rule,
`docs/development/V1-2-6_UX_DECISIONS.md` (T15, T17, « Points from the boards for U1 and later »), boards
`docs/design/v1-2-6` (`maquettes.html` is their source).
## REQUEST (verbatim — IMMUTABLE)
# FAUNOSTEO — V1-2.6 UX — Autorisation de U1 uniquement
Le propriétaire approuve définitivement le checkpoint U0.
U0 est terminé, vérifié CONFORME 12/12, commité et poussé au HEAD 452a346.
J'autorise maintenant l'implémentation de U1 uniquement, conformément à V1-2-6_UX_PLAN.md, aux contrats amendés et aux 16 maquettes V2 validées.
## 1. Périmètre U1
Implémenter la nouvelle structure générale de l'éditeur anatomique.
Navigation principale à quatre onglets :
- Général
- Annotations
- Constats
- Vérification
Les références doivent rester accessibles depuis un panneau secondaire, sans imposer un onglet principal supplémentaire.
Les vues détaillées et les régions vertébrales seront intégrées progressivement à Annotations dans les étapes prévues. U1 ne doit pas anticiper les opérations U2 à U6.
## 2. Annuler / Rétablir
Déplacer les commandes globales dans l'en-tête conformément aux maquettes corrigées.
Contraintes :
- Historique global de la fiche.
- Conservation du comportement existant et de la pile d'historique.
- États activé/désactivé correctement synchronisés.
- Raccourcis clavier appropriés.
- Noms accessibles explicites, notamment « Annuler la dernière modification ».
- Aucun bouton flottant redondant sur le dessin.
Ne pas confondre Annuler/Rétablir avec l'abandon d'un formulaire.
## 3. Navigation et compatibilité
Préserver toutes les fonctions métier de l'ancien éditeur pendant leur réorganisation.
En particulier :
- Aucune perte de brouillon lors d'un changement d'onglet.
- Aucun changement non prévu du mécanisme de sauvegarde explicite.
- Préservation de la récupération locale.
- Préservation des contrôles d'autorisation et du MFA.
- Aucune modification des règles de soumission et de publication.
- Aucun changement du format des documents anatomiques.
- Conservation des chemins et des états nécessaires aux étapes suivantes.
Ne pas implémenter prématurément des fonctions de V1-2.7 simplement parce qu'elles figurent dans certaines maquettes.
## 4. Responsive et accessibilité
Appliquer les règles UX validées :
- Barre latérale repliée sous 1 280 px dans l'éditeur.
- Navigation accessible au clavier.
- Focus visible et cohérent après changement d'onglet.
- Annonces et libellés accessibles.
- Préservation de la règle O14 A : téléphone en lecture seule sous 1 024 px.
- Ne pas supprimer les capacités tactiles déjà présentes sur les largeurs autorisées.
La manipulation avancée des points et des polygones relève de U2, pas de U1.
## 5. Décision T17
Le propriétaire valide la solution suivante pour U6 :
Lorsqu'aucune catégorie ne porte le rôle `vertebra`, proposer une entrée de secours « Régions vertébrales » depuis Annotations.
Lorsqu'une catégorie Vertèbres existe, sa configuration doit se faire depuis cette catégorie, sans doublon.
Enregistrer cette décision selon la convention du registre et actualiser ses dépendances. Ne pas implémenter maintenant le nouveau modèle de catégories.
## 6. Vérifications
Avant toute exécution de tests :
- Vérifier le répertoire et la branche.
- Examiner le statut Git.
- Préserver le fichier de revue non suivi.
- Inspecter les commandes pour confirmer qu'elles ne visent pas DEV.
Exécuter les vérifications applicables à U1 :
- TypeScript et lint.
- Tests unitaires de navigation et d'historique.
- Tests de non-régression.
- Tests clavier/accessibilité pertinents.
- Tests d'intégration et E2E en sandbox jetable strictement isolée, si nécessaires.
Ne jamais exécuter une commande susceptible de joindre ou modifier Supabase DEV.
Faire une revue indépendante de la conformité U1 et corriger les écarts justifiés.
## 7. Git et traçabilité
Travailler dans :
`/home/bchanot/Documents/faunosteo-v1-2`
Sur :
`feature/v1-2-anatomical-sheets`
Utiliser les conventions Git du projet, avec commits réguliers et push.
Ne pas ajouter les fichiers non suivis préexistants sans nécessité et autorisation.
Ne pas modifier le checkout V1-1.
## 8. Interdictions
Aucune modification Rust, SQL, worker ou schéma documentaire.
Aucune migration, aucune opération sur DEV et aucun déploiement.
Aucune fusion.
Ne pas commencer U2, U3, U4, U5, U6, U7, U8 ou V1-2.7.
## 9. Checkpoint U1
Fournir :
- Liste des modifications réalisées.
- Correspondance entre l'interface et les maquettes V2.
- Tests réellement exécutés et leurs résultats.
- Revue indépendante et verdict exact.
- Éventuelles limitations restantes.
- Démonstration testable dans la sandbox.
- Commits et état Git.
- Critères de sortie U1.
S'arrêter au checkpoint U1.
Ne pas commencer U2 sans nouvelle autorisation explicite.
## CLARIFICATIONS
Q: The plan's U1 tooling (worker image commit label in `crates/worker/Dockerfile`, `verify-e2e` image check against
HEAD, demo sheet provisioned by the trial command in `scripts/db-sandbox.sh`) — the brief forbids worker changes /
A: [gated 2026-11-06] defer all of it to U6 (owner). No change under `crates/` or `scripts/` in U1. The U1 demo runs
on the existing trial stack: the owner creates a non-equine sheet in the UI as in `docs/development/V1-2-6_OWNER_TRIAL.md`.
The PLAN U1 acceptance line « a stale worker image is refused » and the TESTS U1 « Tooling » row move to U6.
Q: Where does « Abandonner les modifications » (C11, return to the last saved revision) sit, since the boards show no
discard control / A: [gated 2026-11-06] in the header, a secondary button beside the save state and « Enregistrer »,
edit mode only, disabled when nothing is unsaved; same confirmation and behaviour as today (owner).
Q: Internal design (brief « U1 — Validation de la conception interne », 2026-11-06) / A: [gated 2026-11-06] approach
A: the Annotations panel keeps board 01's cards; « Gérer les vues », « Modifier les catégories » and « Régions
vertébrales » open the existing level-1 editors in full-width sections with « Retour au dessin », until U3, U4 and U6
replace them; four tabs, references in a side panel, history in the header, sidebar hidden below 1 280 px, keyboard
navigation, focus management, read-only below 1 024 px. Ten mandatory precisions: no silent loss of changes, history
or editing state on a section, tab or panel change; « Retour au dessin » restores a coherent context and an
accessible focus; history tests on typed text, shortcuts and section transitions; a save shown only after effective
confirmation, never the browser clock as proof of persistence; read-only below 1 024 px on every editing entry,
moved forms and shortcuts included; reference counters from the current document, no network, no costly recount per
render; no « Prévisualiser » nor withdrawal, no existing function removed; the regions entry respects T17 without
anticipating U6; « Abandonner les modifications » only for unsaved changes, confirmed when data can be lost, never
removing the local copy silently; no provisional code hard to remove, sections replaceable without rebuilding the
navigation. Plan: `.claude/tasks/plans/2026-11-06-v1-2-6-ux-u1.md`.
Q: Save time source / A: [gated 2026-11-06] server time: after a confirmed save, one read of the existing admin
endpoint; « Enregistré à hh:mm · révision n » only when `draft_last_save` names the same revision, else « Enregistré ·
révision n »; never the browser clock.
Q: References panel behaviour / A: [gated 2026-11-06] non-modal: scrim over the content below the tabs (board 11),
content inert, header, tabs and Annuler/Rétablir usable, Escape or scrim click closes, content kept across closes.
Q: Control opening the filtered panel from a finding / A: [gated 2026-11-06] a « n référence(s) » button in the
Citations block of the selected finding's detail; no control inside the ARIA tree.
Q: Annotation list layout / A: [gated 2026-11-06] board 01 card « Annotations de la vue » (grouped by category,
« Filtrer par nom »), shown when nothing is selected; the properties panel gains « Toutes les annotations » to return
to it.
## ACCEPTANCE CRITERIA
1. Four tabs from 1 024 px: Général, Annotations, Constats, Vérification, as an ARIA tablist (arrows, Home/End not
required beyond today's pattern); no « Vues et illustrations », « Références » or « Vertèbres » tab remains; the
initial-tab rule of C40 as amended holds (Général for a sheet without a measurable view, else Annotations).
2. Annotations holds, with their level-1 operations unchanged: the views and their drawings (main view, detail views,
upload, cleaning, attach, the numeric crop editor kept until U4), the annotation categories (level-1 editor kept
until U3) and the « Régions vertébrales » fallback entry with the level-1 regions editor (T17, BDR-102; no role
exists before U6), laid out after board 01's overview panel; no U2-U6 operation is added (no handle, slider,
rectangle, remap, role, opacity).
3. References open in a side panel after board 11, from a « Références » button in the header and from a finding
(its citation badge), filtered to that finding's citations with « Tout afficher », with search, the citation count
per reference, and the level-1 add / edit / delete; read-only (no edit control) in every read-only mode; a modal
panel uses `ModalDialog` (D13, BDR-076); closing returns focus to the opener.
4. Undo and redo sit at the right of the tab row on every tab (board `hist()`): icon and visible « Annuler » /
« Rétablir »; « Annuler » has the accessible name and tooltip « Annuler la dernière modification » (T15); redo's
long name is a label proposal; enabled exactly when the store can undo or redo AND the editor is in edit mode with
no recovery pending; disabled in every read-only mode (narrow, frozen, rights, inactive, historical, recovery
pending, saving); the same `undo()`/`redo()` store actions as today, history and its 8 MiB bound unchanged;
Ctrl+Z and Ctrl+Shift+Z unchanged; the undo and redo buttons of the tool column are removed (no pair on the
drawing).
5. Undo from any tab reverts the last accepted commit, whichever tab made it; a field holding typed text is committed
before the header undo, and that commit is what the undo reverts (behaviour pinned by a test).
6. « Abandonner les modifications » replaces « Annuler les modifications » in the header beside « Enregistrer »
(clarification), with the same confirmation and `discardChanges` behaviour; C28's list names it.
7. The header save line follows the boards: « n modification(s) non enregistrée(s) » while unsaved (count through the
existing plural mechanism), « Enregistrement… » while saving, « Enregistré à hh:mm · révision n » after a save in
this page session; « Révision n » when nothing was saved yet in the session; the save mechanism itself unchanged.
8. The Vérification tab shows the boards' text badge « n erreur(s) » (plural mechanism) when the in-page check has
errors.
9. In the editor, the application sidebar is hidden below 1 280 px and shown from 1 280 px; below 1 280 px the top bar
shows the menu button, which opens the existing drawer (D11, BDR-079) one tap away; the drawer does not close by
itself while the sidebar stays hidden; every menu link stays under the leave guard (BDR-078); other pages keep
today's 1 024 px rule.
10. From 1 024 to 1 279 px the editor follows board 13: properties beside the canvas (C25 as amended), header actions
in reach; no horizontal scroll at 1 024, 1 180, 1 279 and 1 280 px on any tab and with the references panel open.
11. Below 1 024 px (O14 A, C16 as amended): read-only as today, notice title alone, badges, tabs, whole drawing, zoom
and pan, properties summary, no editing action and no enabled undo or redo; unsaved work survives a width change;
no horizontal scroll at 320, 375 and 768 px; touch abilities already present from 1 024 px kept.
12. Focus and announcements: clicking or arrowing a tab keeps focus on that tab; a tab change started from inside a
panel (a hint link, « Aller à ») moves focus to its target element, or to the new tab when there is none, never to
`body`; a polite live region (distinct from the save status) announces a tab or section reached that way; focus
is visible on every new control.
13. « Aller à » reaches every issue kind in its new place: views, categories and regions in Annotations (the section
shown and its row focused), references in the side panel (opened, the reference focused), annotations, findings
and general fields as today.
14. Unchanged: the explicit save, the local recovery (C13, C27, C28), conflicts, rights and MFA checks, the mode
precedence (C38), submission and publication rules, the document format, Rust, SQL, the worker, the core and its
wasm build; level-1 criteria C13, C14, C16, C34 and C41 re-run green.
15. No V1-2.7 control: no « Prévisualiser », no withdrawal (DECISIONS « Points from the boards »).
16. i18n: every string through `useT`, FR/EN parity; prose that names an old tab is reworded to the new place; the new
labels are listed as proposals in `.claude/audits/2026-11-06-v1-2-6-u1-label-proposals.md` for the owner's label
review (C19, C44).
17. Tests: unit tests for the tab model and tiers, header undo/redo states (edit and every read-only mode), cross-tab
undo, the typed-field flush, the references panel (open from header and finding, filter, close, focus return),
« Aller à » targets, the sidebar rule, the save line; e2e helpers (`e2e/support/editor.ts`, `warm-up.ts`) and
specs rewritten for the new shell; every removed or rewritten assertion mapped to its replacement in the commit
message (R-24); axe with no serious or critical violation on the four tabs, the open references panel and the
narrow read-only mode; a keyboard test of the order header → tabs → panel → canvas.
18. Gates, in this order, all green: `pnpm typecheck`, `pnpm lint`, `pnpm test:run`, `pnpm build`, `pnpm e2e:ui`,
a fresh sandbox `pnpm db:sandbox up fresh` then `test-db → e2e-shell → test` (LRN-113), `pnpm check:all`,
`pnpm r5:import-equine --check`; a fresh verifier and a fresh security review.
19. Scope: no change under `crates/`, `supabase/`, `scripts/`, `packages/core-wasm/src/`, `packages/supabase/src/`,
`docs/design/v1-2-6/`; nothing staged from the untracked review file.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && git diff --quiet 846994b..HEAD -- crates supabase scripts packages/core-wasm/src packages/supabase/src docs/design/v1-2-6 && git diff --quiet -- crates supabase scripts packages/core-wasm/src packages/supabase/src docs/design/v1-2-6 && ! git ls-files --error-unmatch faunosteo-v1-2-6-revue-ux-chatgpt.md >/dev/null 2>&1 && echo U1_SCOPE_OK
EXPECT: U1_SCOPE_OK
EVIDENCE: pending
20. FR/EN dictionaries hold the same keys.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && node -e "const fs=require('fs');const k=f=>new Set([...fs.readFileSync(f,'utf8').matchAll(/^\s*'([a-z0-9_.]+)':/gm)].map(m=>m[1]));const a=k('apps/app/src/i18n/fr.ts'),b=k('apps/app/src/i18n/en.ts');const d=[...a].filter(x=>!b.has(x)).concat([...b].filter(x=>!a.has(x)));if(d.length||a.size<100){console.error(d);process.exit(1)}console.log('I18N_PARITY_OK',a.size)"
EXPECT: I18N_PARITY_OK
EVIDENCE: pending
## FILE SCOPE
- apps/app/src: editor tabs model (`editor/tabs.ts`, `editor/useViewport.ts`, `editor/verification.ts`,
`editor/focusRequest.ts`, `editor/annotations/focusTarget.ts`), editor state selectors needed for the header
(`editor/state/*`, read-only additions only: save count, save time), `components/editor/**` (EditorTabs,
EditorTabBody, DraftHeader, tab bodies, annotations panels, references panel, verification), `components/shell/
{AppLayout,MobileDrawer,SidebarNav}.tsx`, `app/routes/app/admin/AdminSheetDraftRoute.tsx`, `i18n/{fr,en}.ts`
- apps/app/tests/unit/**, apps/app/tests/helpers/**, apps/app/e2e/** (support helpers, shell and ui specs)
- docs: `docs/development/V1-2-6_OWNER_TRIAL.md` (U1 demo steps), `docs/development/BROWSER_TESTS.md` if a suite
changes, `docs/development/V1-2-6_UX_{PLAN,TESTS}.md` (tooling moved to U6), `.claude/audits/2026-11-06-v1-2-6-u1-
label-proposals.md`
- .claude/tasks (this contract, plan, TODO), .claude/memory (through memory.sh)
- NOT in scope: crates/**, supabase/**, scripts/**, packages/core-wasm/src/**, packages/supabase/src/**,
docs/design/v1-2-6/**, the V1-1 checkout