chore(docs): U1 contract amended, owner precautions resolved

AC3, AC4, AC5, AC7, AC17 and changes 2.6-2.9 applied as approved
(BDR-105); per-operation sandbox go; precautions 2.8 (no silent loss
on a 1 024 px crossing or recovery decision) and AC7 (save time rights)
resolved from the code facts, AC21 and AC22 added. Plan unchanged.
This commit is contained in:
bchanot committed 2026-11-06 17:15:59 +01:00
1 parent 1ed5c96e1b
commit ed6fb0d313
1 file changed
+117 -12
@@ -180,6 +180,82 @@ Citations block of the selected finding's detail; no control inside the ARIA tre
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.
Q: U1 authorisation (brief « V1-2.6 UX — Ratification finale U1 et autorisation conditionnelle d'implémentation »,
2026-11-06) / A: [gated 2026-11-06] the 18 visible choices of the plan (checkpoint page section 1), approach A, the
amendments of AC3, AC4, AC5, AC7, AC17 (applied above, each tagged) and the changes 2.6 to 2.9 approved, with the two
precautions below. The plan at 2e46c14 stays the reference and is not redesigned. Implementation of U1 only, lots A to
I; per lot: scope and criteria respected, applicable checks run, existing functions kept, regressions fixed, validated
changes committed and pushed, no next lot while its preconditions are unmet. Kept in particular: global history and
Annuler/Rétablir, unsaved changes, the local recovery copy, rights and MFA checks, read-only behaviours, focus,
keyboard navigation and accessibility, document compatibility. U2 to U6 graphic operations excluded. Code starts
only after the targeted counter-check of the confirmation pass's three fixes and of the two precautions (verdict
reported, blocking gaps fixed and re-checked).
Q: Design criteria (checkpoint 2.7) / A: [gated 2026-11-06] no loss on a tab, section or panel change (Lots B2, D
tests); « Retour au dessin » focus and context; history tests on typed text, shortcuts and section transitions; save
shown only after the server answer, time only from the server; read-only below 1 024 px on every moved form and
shortcut; counts from the current document without network; no « Prévisualiser », no withdrawal, no removed function;
T17 entry without role logic; discard confirmation naming the stored copy; sections replaceable through one registry.
Q: Sandbox data deletion (checkpoint 2.9, made stricter by the authorisation brief §4) / A: [gated 2026-11-06] the
plan approval authorises no deletion of data, sandbox included, and no earlier go carries over. Before each
`pnpm db:sandbox down`, `pnpm db:sandbox up fresh` or any equivalent that may reset the sandbox (Lot B1, Lot I or any
other): stop before the destruction; take a read-only inventory of the containers, the accounts outside the seed, the
sheets, drafts and other resources concerned; present exactly what will be deleted; run it only on the owner's
explicit go for that operation. DEV is never a substitute for an unavailable sandbox. This prevails over plan :38-40,
:59 and :397.
Q: Unmounted forms (checkpoint 2.8, owner precaution) / A: [gated 2026-11-06] owner: « La traversée du seuil de
1 024 px ou une décision de récupération ne doit pas provoquer une perte silencieuse de saisie. Vérifier le
comportement réel des composants existants. Préserver les valeurs lorsqu'une solution sûre existe dans le périmètre
U1. Sinon, prévoir une confirmation explicite ou documenter précisément la limitation et les garanties de
récupération. Si la prévention de la perte exige une évolution hors périmètre U1, signaler le blocage avant
implémentation concernée. Ajouter les tests adaptés. » Facts (read 2026-11-06, `apps/app/src`): `readOnly = mode !==
'edit' || recovery !== 'none'` (route :132); the store accepts commits in narrow mode (`canEdit` true for edit and
narrow, `mode.ts:90-92`, `editorBase.ts:44-50`). Resolution, executor's, under the owner's rule:
- Recovery decision: no loss possible. An offer is pending only at opening (before any form exists,
`editorLoad.ts:65-88`, route :125-131) or when `canEdit` turns true from rights, inactive, historical or frozen
(`recoveryFlow.ts:76-95`), all read-only, so every edit-only part is absent while it is pending; « Restaurer » and
« Ignorer » mount empty forms. Pinned by a test (no edit-only control while an offer is pending, empty forms after).
- Width change to read-only, kept as today: `TextField` commits its typed text on unmount (`TextField.tsx:61-73`),
accepted in narrow mode (an unsaved change, recovery copy written); a value the field refuses keeps its message,
shown again when editing resumes.
- Width change to read-only, preserved (new): the edit-only parts without a native modal of their own stay mounted and
are hidden with `hidden` while read-only, instead of unmounting, so their values come back on widening: the
creation forms of categories, references, regions and detail views, the findings creation form, the submission
note, the crop group editor, and the annotation edit body (`EditableAnnotations`: tool, selection, pending creation
with its typed name, tracing, numeric geometry drafts) beside the read-only body. Hidden parts use the B2
`KeptPlace` visibility, so their canvases detach (one live composition per view). Three guards a width change needs
and a tab change does not: when the editor turns read-only, the route runs `commitFocusedField()` and blurs any
focus left inside a hidden part; the annotation edit body drops an in-flight drag without commit (its `moveTarget`
null while hidden, `EditableAnnotations.tsx:256-265`, `useMoveGesture.ts:54-57`); dialogs that confirm an edit
(`DeleteDialog`s, the discard confirmation) close without effect when the editor turns read-only, so no editing
entry stays usable below 1 024 px (precision 5; today they stay open and still write, level-1 behaviour).
- Width change to read-only, documented limit: the drawing actions of the views section (`ViewDrawing.tsx:47`:
upload phase, cleaning candidate, repair offer with typed geometries, parent drawing choice) own three native modals
(`CleaningDialog`, `RepairDialog`, `ParentDrawingDialog`); hiding an open native modal is not proven safe, so they
unmount as today. Guarantees: a running upload continues and lands (it checks the session only,
`drawingUpload.ts:198-209`); every committed change, the history and the recovery copy are kept; on widening, the
repair offer comes back from the drawing's hint (`ViewDrawing.tsx:77`) and the cleaning choice from a new upload of
the same file. Written in `docs/development/V1-2-6_OWNER_TRIAL.md` (Lot I) and the checkpoint report.
- Not changed: `ConflictDialog` (a save outcome). Lots: B2 (kept edit-only parts, guards, unit tests), H (Chromium:
type in each preserved part, cross 1 024 px, no edit control and no focus in a hidden part, widen, values back; a
drag across the crossing commits nothing; open delete and discard confirmations close). Plan §2 cites
`CategoriesSection.tsx:51` and `ReferencesTab.tsx:44`; the lines are 52 and 47.
Q: Save time rights (AC7, owner precaution) / A: [gated 2026-11-06] owner: « Vérifier les droits nécessaires pour
consulter l'heure de sauvegarde à partir de l'endpoint existant. Ne pas élargir les permissions. Si l'information
n'est pas accessible avec les droits normaux du praticien, afficher « Enregistré · révision n ». Ne jamais afficher
une sauvegarde réussie avant confirmation serveur, ni utiliser l'horloge du navigateur comme preuve de persistance. »
Facts (read 2026-11-06): the read (`packages/supabase/src/sheets.ts:475-483`, SQL
`supabase/migrations/20261103100000_sheet_draft_last_save.sql:14-94`) is `stable security definer`, needs
`require_catalog_actor` (active profile, confirmed e-mail, aal2) and `caller_can_see_official_sheet` (aal2 and an
active sheet_editor, reviewer or publisher grant on an official, non-deleted sheet); `save_sheet_draft` needs
`can_edit_sheet` (aal2 and an active editor grant), so every user who can save can read; no audit row, no write
budget, no sign-out or step-up in the wrapper; `saved_at` is the server's audit time, null when the revision was not
written by a save. Resolution: no permission change; `readSaveTime` calls the accessor directly with the store's
client and session, as `readConflict` does (`editorSave.ts:56-71`), never the route's query (a failed route refresh
unmounts the editor, `useAdminQuery.ts:45-48`); any refusal or failure leaves `savedAt` null, shown « Enregistré ·
révision n »; « Enregistré » appears only after the server's save answer (`applySaved`); the time is
`draft_last_save.saved_at` formatted, never `Date.now()` or `new Date()`. Tests in Lot E: refusal and network failure
→ « Enregistré · révision n », editor still mounted; no saved line while the request is in flight; no browser clock
read in `saveLine.ts` and `readSaveTime`.
## ACCEPTANCE CRITERIA
1. Four tabs from 1 024 px: Général, Annotations, Constats, Vérification, as an ARIA tablist (arrows, Home/End not
@@ -190,24 +266,39 @@ to it.
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 » /
3. [amended 2026-11-06, owner, checkpoint 2.1] References open in a non-modal side panel after board 11, anchored
below the tab row so that it never covers the draft header or the tab row, from a « Références » button in the
header and from the selected finding's detail (a « n référence(s) » button in its Citations block), filtered to
that finding's citations with « Tout afficher (N) », with search on citation, DOI and URL, the citation count per
reference, and the level-1 add / edit / delete; a scrim covers the tab panels, which are `inert` while the panel is
open; the header, the tab row, « Annuler », « Rétablir » and Ctrl+Z stay usable; Escape, ✕ or a click on the scrim
closes it, and focus returns to the opener, else to the header « Références » button; read-only (no edit control)
in every read-only mode; the panel is not a `ModalDialog`, and every dialog opened from it stays one (D13,
BDR-076).
4. [amended 2026-11-06, owner, checkpoint 2.2] 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;
pending); enabled while a save is in flight, as Ctrl+Z (a step taken during a save stays unsaved); 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).
5. [amended 2026-11-06, owner, checkpoint 2.3] Undo from any tab reverts the last accepted commit, whichever tab made
it; a field holding typed text is committed before the header undo (blur forced at pointerdown; keyboard users
reach the button with Tab, which blurs the field), and that commit is what the undo reverts, also when the history
was empty before it; when the field refuses the value (its error shown), no undo happens and focus returns to the
field (behaviours pinned by tests).
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.
7. [amended 2026-11-06, owner, checkpoint 2.4; precaution in CLARIFICATIONS « Save time rights »] The header save
line follows the boards, first matching form: a recovery copy issue (cap or quota), today's text;
« Enregistrement… » while saving; while unsaved, « n modification(s) non enregistrée(s) » (plural mechanism) when
n, the number of accepted changes between the shown and the saved document along the history, is a positive
number, else « Modifications non enregistrées »; after a save confirmed by the server in this page session,
« Enregistré à hh:mm · révision n » when one read of the existing admin endpoint returns that revision's save time,
else « Enregistré · révision n » (also after `draft.unchanged`), never the browser clock; « Révision n » when
nothing was saved in the session; state changes announced, not each count change; 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
@@ -238,7 +329,9 @@ to it.
« 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.
narrow read-only mode; a keyboard test of the order header → tab list → « Annuler » / « Rétablir » → references
panel when open → tab panel content in visual order (tools, canvas, side column) [last item amended 2026-11-06,
owner, checkpoint 2.5].
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.
@@ -251,6 +344,13 @@ to it.
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
21. [added 2026-11-06, owner precaution 2.8] No silent loss of typed input on a 1 024 px crossing or a recovery
decision, as resolved in CLARIFICATIONS « Unmounted forms »: the listed edit-only parts kept and hidden while
read-only with their values back on widening, the three guards, the drawing-actions limit documented with its
guarantees; unit tests (B2) and Chromium journeys (H).
22. [added 2026-11-06, owner precaution AC7] Save time read with the existing rights only, as resolved in
CLARIFICATIONS « Save time rights »: no permission change, refusal or failure → « Enregistré · révision n » with
the editor still mounted, nothing shown as saved before the server's answer, no browser clock; tests in Lot E.
## FILE SCOPE
- apps/app/src: editor tabs model (`editor/tabs.ts`, `editor/useViewport.ts`, `editor/verification.ts`,
@@ -258,6 +358,11 @@ to it.
(`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`
- [added 2026-11-06, owner, checkpoint 2.6] `apps/app/src/editor/{navigation,saveLine,useEditorNavigation,
sheetDocument}.ts`, `apps/app/src/editor/references/citations.ts`, `apps/app/src/editor/annotations/{overview,
useCanvasBuild}.ts` (overview new; the build hook detaches while hidden; the canvas reset uses the existing `view`
action of `uiState.ts`, unchanged), `apps/app/src/catalogue/useCatalogue.ts` (export `folded` only),
`apps/app/e2e/lan/trial-lan.spec.ts`; `editor/state/*` edits limited to `lastSave` and `readSaveTime`
- 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-