diff --git a/.claude/tasks/plans/2026-11-22-detail-views-graphic-crop.md b/.claude/tasks/plans/2026-11-22-detail-views-graphic-crop.md index 88472010..566a58b1 100644 --- a/.claude/tasks/plans/2026-11-22-detail-views-graphic-crop.md +++ b/.claude/tasks/plans/2026-11-22-detail-views-graphic-crop.md @@ -1,9 +1,11 @@ -# U2/U4 Detail Views Drawn on the Drawing: Implementation Plan (V1-2.6), rev 1 +# U2/U4 Detail Views Drawn on the Drawing: Implementation Plan (V1-2.6), rev 2 > **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development to implement this plan task-by-task. > Steps use checkbox (`- [ ]`) syntax for tracking. -**Status:** DRAFT for the owner's technical validation (owner, 2026-11-22: « Cette validation concerne le design. Elle +**Status:** rev 2 = rev 1 plus the three challenges of 2026-11-22 (correctness FATAL 5, robustness CONCERNS 7, +simplicity CONCERNS 1; what became of each finding is in « Challenge round », at the end). DRAFT for the owner's +technical validation (owner, 2026-11-22: « Cette validation concerne le design. Elle n'autorise pas encore l'implémentation. Je validerai le plan technique avant le début du code. »). No product code before that validation. Contract: `.claude/tasks/contracts/2026-11-22-detail-views-graphic-crop-0134.md`. @@ -57,6 +59,23 @@ each task. | R5 | Keep: no change to pre-existing sandbox data, never `editor-equine` on the persistent sandbox, never DEV, no `db:trial` without an authorised checkpoint, no merge, no deploy. | Global Constraints, 29, 30 | | R6 | The plan separates: Rust core; document compatibility and the N-1 reader; frame creation and editing; accesses and their shapes; annotation priority on the three surfaces; label placement and accessibility; parent/child navigation; PDF engine fixes; automated tests and manual trials on db:trial. | Parts 1 to 9 | +## Correction to the owner (found by the correctness challenge, verified) + +Board revisions 3 and 4 said the uniqueness of the category id is « contrôlée par le cœur (`validate.rs:397`) et par +SQL (`20261010100000…:45`) ; un test pgTAP le prouvera ». The SQL half is wrong. +- Migration `20261028110000_sheet_review_workflow.sql:139-144` dropped that SQL check, together with the whole + business mirror (« drop the business mirror, keep the structural guards », V1-2 M5, decision O22). A draft save now + checks only the document's structure and size (`private.check_document_structure`, `:411-441`). +- Uniqueness is held by the core at every write path: + - an editor insert of an id already present is refused (`DuplicateKey`), in this version and in N-1 ones; + - the core alone creates `cat-access`, once (Task 2); + - a document that still held two would carry the error `category.id.duplicate`, refused by the server verdict before + submission and publication. +- The plan therefore proves uniqueness in the core and the verdict (Tasks 1 and 2), and keeps a pgTAP test for what SQL + really does (Task 4): a draft carrying `cat-access` saves. +- Adding the SQL check back would be a migration and a business rule in SQL, against your « sans migration SQL » and + against O22. Not proposed. + ## Arbitrations for the owner (visible choices this plan settles; recommendation first) These are the choices that neither the board nor the five owner messages settle. Each is applied as recommended @@ -82,14 +101,20 @@ unless the owner says otherwise. A changed answer is listed with the task it cha - Recommended: « Ouvrir la vue », « Recadrer la vue », « Déplacer l'accès », « Propriétés ». - « Supprimer » stays in the properties dialog, as for every annotation (`AnnotationDialog.tsx:181`). - The strip keeps four buttons, so its width budget does not move. - - Alternative: panel 05 exactly, with no non-drag move of a whole access. + - Alternative: panel 05 exactly. An access then has no move without dragging, and an access entirely covered by + points could not be moved at all (the point under the pointer wins, D11). - **A3. PDF continuation pages.** - Today a note that is long enough runs over the footer and, beyond that, off the page. There is one page per observation and no overflow check (`layout/observation.rs:633-657`). - - Recommended: the images shrink in proportion down to the 60 pt floor. If the text still does not fit, the images - keep their size and the text continues on a following page. That page carries the same header and the same - observation title (number and severity), with no new wording and no new label key; a new key would break the N-1 - reading of archived labels. + - Recommended: + - as today, each row gets its share of the room the text leaves, never under 60 pt; + - an image taller than its share is reduced as a whole and centred in its cell, never squashed; + - a shorter neighbour keeps its size. + - If the text cannot fit even with the rows at 60 pt, the images take the page above the first section and the text + continues on a following page. + - That page carries the same header and the same observation title (number and severity), with no new wording and + no new label key; a new key would break the N-1 reading of archived labels. + - The 60 pt floor yields only when the views alone exceed the page (eight full-width views). - « One page per observation » then holds except for those cases. - **A4. Order of full-width views on the page.** - Recommended: the first view keeps the top of the page, so a 3:1 or wider main view comes first, alone on its row. @@ -97,20 +122,25 @@ unless the owner says otherwise. A changed answer is listed with the task it cha per row. - Alternative: strict view order, which leaves half-empty rows between full-width ones. - **A5. Raster tolerance.** - - Beyond today's clamps (taller than 1:2, wider than 5:1), the new size rule gives the raster the frame's ratio to - within half a pixel. At most 0.25 px of drawing beyond the frame can show at an edge, which antialiasing makes - invisible. - - Frames between 1:2 and 5:1 keep today's size (« rien ne change », validated). Their rounding can show up to about + - Beyond today's clamps (taller than 1:2, wider than 5:1), a view's raster gets the frame's ratio to within half a + pixel. At most 0.25 px of drawing beyond the frame can show at an edge, which antialiasing makes invisible. + - Views between 1:2 and 5:1 keep today's size (« rien ne change », validated). Their rounding can show up to about 1.25 px beyond the frame at the sides of a 5:1 frame. That is pre-existing and was never seen. + - The branding logos keep today's rule, so the footer does not move. The 57 frozen raster-size cases do not change. - Recommended: keep the validated « rien ne change ». - - Alternative: the exact rule everywhere. This changes, by one pixel, some frozen raster-size expectations of - `crates/core/tests/oracles/r4/text.json`, and no existing PDF or reference. + - Alternative: the exact rule for every view. That changes no existing PDF, but some views' raster sizes by one + pixel. - **A6. Where the internal category is created** (wording, no behaviour change). The core creates `cat-access` when the first access enters it, inside the same undo step as the view when « Créer la vue » makes the access. This also covers « Je le tracerai ensuite » and a new access to an existing view. The README's « seul le lot vue, catégorie et accès la crée » becomes « seul le cœur la crée, quand un accès y entre ». - **A7. Bands on detail views only.** The neutral bands and the clip apply to detail views. The main view keeps today's look on the three surfaces. +- **A8. « Autres vues (N) » on the catalogue.** The catalogue already has its zoom buttons (−, +, « Ajuster ») in the + top-right corner of the drawing (`CatalogueCanvas.tsx:163-185`). + - Recommended: there, the button sits in the same corner, just under them. On the editor and the bilan it is in the + corner itself, as on the board. + - Alternative: move the zoom buttons. ## Audit findings (2026-11-22, read-only, at 84ce1955) @@ -118,7 +148,7 @@ unless the owner says otherwise. A changed answer is listed with the task it cha - Edit commands are one generic enum, `crates/core/src/domain/sheet/edit.rs:96`: insert, update, remove, move, set_status, mark_reviewed over element keys. There is no batch in Rust: `commitBatch` - (`apps/app/src/editor/state/editorEdit.ts:275-291`) applies a command list on a scratch text and records one undo + (`apps/app/src/editor/state/editorEdit.ts:46-62`) applies a command list on a scratch text and records one undo entry. - Ids come from the page (`apps/app/src/editor/ids.ts`, `-<10 chars a-z2-7>`). The equine draft's category ids are words (`articulations`, `os`, `charnieres-vertebrales`, `zone-colonne`, `cadrans-du-crane`). `cat-access` is @@ -148,8 +178,9 @@ unless the owner says otherwise. A changed answer is listed with the task it cha - Fingerprints: equine canonical `12d78872…`, alias `27c7383c…` (`fingerprint.rs:44`, tests in `sheet_fingerprint.rs`). - Review digests: `general` covers `categories` (`review.rs:~215`). A first access therefore changes the `general` digest of a document. That is expected, and it is listed in the README. -- SQL refuses duplicate category ids (`20261010100000_sheet_document_schema_v2.sql:32-62`, - `category.id.duplicate`). +- SQL no longer checks duplicate category ids. `20261028110000_sheet_review_workflow.sql:139-144` dropped the business + mirror, and the save checks structure and size only (`private.check_document_structure`, `:411-441`). Uniqueness is + the core's: `DuplicateKey` on insert, and `category.id.duplicate` (an Error) in the verdict. ### PDF @@ -254,7 +285,8 @@ named. - Expected: the access is grown (A1), the commit is accepted, and nothing is lost. - Tests: Task 3 (core value proven against `annotation_placement`) and Task 10 (dialog). 3. **The text of a long observation note reaching the footer or the page bottom.** - - Covers a note of 5 000 characters with 0, 1, 4 and 8 views, wide and tall ones mixed. + - Covers a note of 5 000 characters with 0, 2, 4 and 8 views, wide and tall ones mixed, a 1:6, 1:10 and 1:100 + view beside the main view, and a long segmented section (zones) crossing a page. - Expected: no op under the footer region, no image overlapping anything, no squashed image, continuation pages in order. - Tests: Task 27. @@ -277,10 +309,10 @@ named. | `crates/core/src/domain/sheet/edit.rs` | `EditError::ReservedCategory`, guards in `insert_top`, `update`, `update_annotation`, `remove`; category appended when an access enters it | 2 | | `crates/core/tests/sheet_access_category.rs` | NEW. Guards, creation, fixture equality, R1 (`view.unreachable`), census of `cat-access` in the repo | 2, 4 | | `crates/core/src/anatomy/frame.rs`, `domain/sheet/preview.rs` | `min_access_span`, `min_access_spans`, `PreviewState.min_access_span` | 3 | -| `supabase/tests/024_sheet_access_category.sql` | NEW. pgTAP: one `cat-access` saves, two are refused | 4 | +| `supabase/tests/024_sheet_access_category.sql` | NEW. pgTAP: a draft carrying `cat-access` and its access saves (SQL checks structure only) | 4 | | `packages/core-wasm/tests/n-1.access-category.test.ts` | NEW. Frozen N-1 Zod reader on the fixture; N-1 scanner and readers on a PDF of that sheet | 4 | -| `crates/core/src/pdf/write/views.rs` | `raster_size_of` exact beyond the clamps | 25 | -| `crates/core/src/pdf/write/layout/observation.rs` | Rows (grid + full width), proportional scale, text flow onto continuation pages, text floor | 26, 27 | +| `crates/core/src/pdf/write/views.rs` | `view_raster_size`, exact beyond the clamps for views; logos unchanged | 25 | +| `crates/core/src/pdf/write/layout/observation.rs` | Rows (grid + full width), each image fitted in its row's budget, text flow onto continuation pages, text floor | 26, 27 | | `crates/core/tests/common/page_boxes.rs` | NEW. Boxes of a draw log page, the footer region, the overlap census | 24 | | `crates/core/tests/pdf_proportions.rs` | NEW. Raster sizes, layout modes, flow and stress cases, new references | 25 to 28 | | `crates/core/tests/oracles/proportions/*.json` | NEW, frozen after the owner's checkpoint. Draw logs of the new reference cases | 28 | @@ -299,13 +331,14 @@ named. | `apps/app/e2e/shell/editor-detail-views.spec.ts`, `e2e/ui/access-labels.spec.ts` (+ harness page) | NEW. Browser proofs | 29 | | Docs | `ANNOTATION-RENDERING.md` (first), `PDF-FORMAT.md`, `RUST.md` §10 and §12, `ANATOMICAL_SHEET_MODEL.md`, `V1-2-6_UX_COMPATIBILITY.md` §1, `V1-2-6_UX_TESTS.md` U4, `V1-2-6_UX_PLAN.md` U4, `V1-2-6_OWNER_TRIAL.md` §4.18, board README | 5, 17, 28, 30 | -Execution order: -- 0, 1, 2, 3, 4, 5; -- the PDF: 24, 25, 26, 27, 28 (its freeze waits for the owner; the rest goes on meanwhile); -- 13, 17, 18, 19, then 6, 7, 8, 9, 10, 11, 12, 21, 14, 15, 16, 22, 23, 20; +Execution order (each task runs after everything it consumes): +- 0, 1, 2, 4, 5; +- the PDF: 24, 25, 26, 27, 28. Its freeze waits for the owner; the rest goes on meanwhile. +- 3, measured only after the PDF tasks: it is the optional user of the wasm margin (A1); +- 13, 17, 18, 19, 22, 6, 7, 8, 9, 14, 15, 10, 11, 16, 21, 12, 23, 20; - 29, 30, 31. -Each task's own interfaces block names what it needs from earlier ones. +Each task's interfaces block names what it needs from earlier ones. --- @@ -543,6 +576,13 @@ mod baseline_edits { assert_eq!(done.unwrap_err(), EditError::HasDependents); } + /// Uniqueness at N-1 too: a second category of that id is a duplicate key. + #[test] + fn an_n1_application_cannot_insert_a_second_one() { + let done = apply_edit(&fixture(), insert("category", access_category())); + assert_eq!(done.unwrap_err(), EditError::DuplicateKey); + } + #[test] fn an_n1_application_removes_it_once_empty() { let done = apply_all(&fixture(), vec![ @@ -556,7 +596,7 @@ mod baseline_edits { - [ ] **Step 3: Run it on the unchanged core.** - Run `cargo test -p faunosteo-core --test n1_access_category`. - - Expected: 8 passed. A failure means the fixture is not what the N-1 core writes. Fix the fixture's construction, + - Expected: 9 passed. A failure means the fixture is not what the N-1 core writes. Fix the fixture's construction, never the assertions, and rerun. - [ ] **Step 4: Commit.** - `git add crates/core/tests/fixtures/n1/access-category.json crates/core/tests/n1_access_category.rs` @@ -595,8 +635,10 @@ mod baseline_edits { mod common; use faunosteo_core::domain::js::parse_json; -use faunosteo_core::domain::sheet::AnatomicalSheetDocument; use faunosteo_core::domain::sheet::access::ACCESS_CATEGORY_ID; +use faunosteo_core::domain::sheet::{ + AnatomicalSheetDocument, is_publishable, validate_sheet_document, +}; use faunosteo_core::domain::sheet::edit::{EditCommand, EditError, apply_edit}; use faunosteo_core::facade::call; use serde_json::{Value, json}; @@ -751,6 +793,18 @@ fn an_access_in_it_is_reshaped_and_an_n1_point_in_it_stays_editable() { assert!(apply_edit(&with_point, update("annotation", "anno-n1pointaa", ordinary)).is_ok()); } +/// Uniqueness where it is held (correction to the owner, SQL keeps the structure only): a +/// document that held two would fail the verdict before submission and publication. +#[test] +fn two_access_categories_never_pass_the_verdict() { + let mut value = fixture_value(); + let category = element("categories", ACCESS_CATEGORY_ID); + value["categories"].as_array_mut().unwrap().push(category); + let issues = validate_sheet_document(&doc_of(value)); + assert!(issues.iter().any(|i| i.code == "category.id.duplicate")); + assert!(!is_publishable(&issues)); +} + #[test] fn the_facade_names_the_refusal() { let input = json!({ "document": value_of(SLICE)["input"], @@ -862,16 +916,12 @@ fn insert_annotation( } ``` -- [ ] **Step 5: Flip `baseline_edits` in `n1_access_category.rs`.** - - Keep the module name and its tests' names. Above the module, add the doc comment: « At the N-1 baseline (`N1_BASE`, - ledger) these edits were accepted; Task 5 replays them there. The current core refuses them. » - - Change the bodies as follows: - - `the_fixture_is_the_slice_plus_three_inserts`: the category insert is now refused with `ReservedCategory`. The - assertion becomes: inserting `access_category()` into the slice gives `Err(EditError::ReservedCategory)`. - - `an_n1_application_renames_and_recolours_it`: `Err(EditError::ReservedCategory)`. - - `an_n1_application_puts_a_point_in_it`: `Err(EditError::ReservedCategory)`. - - `an_n1_application_cannot_remove_it_while_an_access_uses_it`: `Err(EditError::ReservedCategory)`. - - `an_n1_application_removes_it_once_empty`: the second command is refused with `ReservedCategory`. +- [ ] **Step 5: Retire `baseline_edits` from `n1_access_category.rs`.** + - Delete the module, and the helpers only it used. Keep `permanent`. + - Add to the file's head comment: « The N-1 edits (rename, recolour, a point in the category, removal once empty, a + second category refused as a duplicate) are recorded at `N1_BASE` (ledger), where they ran green. The current core + refuses the first four: `sheet_access_category.rs`. » + - Duplicating them here as refusals would only repeat `sheet_access_category.rs`. - [ ] **Step 6: The page phrases the refusal.** - Append `'reserved_category'` to the kinds list of `apps/app/src/editor/refusal.ts:12`. - Add the key `editor.refusal.core.reserved_category`: @@ -891,12 +941,14 @@ fn insert_annotation( ### Task 3: The smallest side of an access in each view (arbitration A1) -Dropped if the owner picks A1's alternative. Task 10 then takes its « A1 alternative » bullet. +Runs after Task 27 (execution order): the PDF work the owner required uses the wasm margin first. Dropped if the owner +picks A1's alternative, or if the margin left after Task 27 is smaller than the 3 188 B the `min_point_radius` +precedent cost. Task 10 then takes its « A1 alternative » bullet. **Files:** - Modify: `crates/core/src/anatomy/frame.rs` (after `min_point_radii`, `:242-255`) - Modify: `crates/core/src/domain/sheet/preview.rs` (`PreviewState`, `:362-378`; `state()` `:280-293`) -- Modify: `crates/core/tests/sheet_frame.rs`, `crates/core/tests/sheet_preview.rs` +- Modify: `crates/core/tests/sheet_preview.rs` - Regenerate: `packages/core-wasm/types/PreviewState.ts` **Interfaces:** @@ -905,8 +957,9 @@ Dropped if the owner picks A1's alternative. Task 10 then takes its « A1 altern - `PreviewState.min_access_span: BTreeMap` (TS `min_access_span: { [key in string]?: number }`), with one entry for every view that has a usable frame and drawing. -- [ ] **Step 1: Failing tests** in `sheet_frame.rs`. Build the slice's frames the way the file already builds them for - `frame_faults`, then: +- [ ] **Step 1: Failing tests** in `sheet_preview.rs`, whose bundle helpers (`:10-21`: `BundledSheetData`, + `LoadedSheet`, the frame imports) already load a sheet with its drawing. Build the frames of the main and head views + from that drawing (`view_frame`), then: ```rust /// A rectangle access of side `min_access_span` passes on the main view and on the head view; @@ -924,12 +977,11 @@ fn an_access_of_the_minimum_side_passes_and_a_smaller_one_does_not() { } ``` - `frame_faults_of_access(view_id, frame, side)` is a local helper. It adds to the slice a `detail_trigger` drawn in - `view_id`: a square of `side` centred on the frame, opening a new child view of `view_id`. It returns the faults of - that annotation only. Write it from the file's existing doc-building helpers. In `sheet_preview.rs`, assert that - `PreviewState.min_access_span` holds `view-main` and `view-head`, and that each value equals `min_access_span` of its - frame. -- [ ] **Step 2: Run, expect failure** (unknown function): `cargo test -p faunosteo-core --test sheet_frame --test sheet_preview`. + `frame_faults_of_access(view_id, frame, side)` is a local helper. It adds a `detail_trigger` drawn in `view_id`: a + square of `side` centred on the frame, opening a new child view of `view_id`. It returns the `frame_faults` of that + annotation only. Also assert that `PreviewState.min_access_span` holds the main and head views, and that each value + equals `min_access_span` of its frame. +- [ ] **Step 2: Run, expect failure** (unknown function): `cargo test -p faunosteo-core --test sheet_preview`. - [ ] **Step 3: Implement.** ```rust @@ -962,7 +1014,7 @@ pub fn min_access_spans<'a>( drawn in each view, by view id (`min_access_span`): the page grows a generated access to it. Absent for a view without a usable frame or drawing. » Fill it in `state()` exactly like `min_point_radius`. - [ ] **Step 4: Run.** - - `cargo test -p faunosteo-core --test sheet_frame --test sheet_preview`: pass. + - `cargo test -p faunosteo-core --test sheet_preview`: pass. - Then `pnpm rust:check`, which exports the type, and `pnpm wasm:build`. - Then `pnpm --filter @faunosteo/core-wasm exec vitest run`. Fix any TS fixture that builds a `PreviewState` by adding `min_access_span: {}`. @@ -988,15 +1040,20 @@ pub fn min_access_spans<'a>( - For every `.json`, `.sql`, `.svg` and `.md` file, it asserts the bytes do not contain `cat-access`. The only exception is `crates/core/tests/fixtures/n1/access-category.json`. - For every `.pdf` under `apps/app/tests/fixtures`, it locates the attachment with - `faunosteo_core::pdf::read::read_attached_document(&bytes, ProbeLimits::UNBOUNDED)` (the call - `pdf_layout.rs:39-52` uses), and asserts the attachment text does not contain `cat-access`. + `faunosteo_core::pdf::read::probe::read_attached_document` (imported as `pdf_layout.rs:16` does), under the + production limits, never `UNBOUNDED`: the tree holds hostile files (`pdf/r4/read`). A refused read or a missing + attachment counts as « no `cat-access` ». When there is an attachment, the test asserts its text does not contain + `cat-access`. - Expected: green. -- [ ] **Step 2: pgTAP (R3 « unicité »).** In `supabase/tests/024_sheet_access_category.sql`: - - Follow `016_sheet_review_workflow.sql:40-60` for the setup: an editor account, a draft sheet, a version content - built with `jsonb_build_object`. - - Assert a draft whose `content.categories` holds one `cat-access` category saves (`lives_ok`). - - Assert one holding two is refused with the `category.id.duplicate` issue (`throws_ok`, the message the existing - duplicate tests expect). +- [ ] **Step 2: pgTAP, what SQL really does (correction to the owner).** In + `supabase/tests/024_sheet_access_category.sql`: + - Follow `016_sheet_review_workflow.sql:40-60` for the setup: an editor account, a draft sheet, and a version + content built with `jsonb_build_object`. + - Assert that `save_sheet_draft` accepts a draft carrying a `cat-access` category and an access in it (`lives_ok`): + no SQL change is needed for this feature. + - Write the file's head comment with the facts: SQL checks the structure and the size only + (`20261028110000…:139-144, 411-441`). Uniqueness is the core's: `DuplicateKey` on insert, and + `category.id.duplicate` in the verdict (`sheet_access_category.rs`). - Run `pnpm --filter @faunosteo/supabase test:run`: green. - [ ] **Step 3: Frozen N-1 readers (R3 « lecture par l'application N-1 »).** - In `packages/core-wasm/tests/n-1.access-category.test.ts`, read the fixture JSON by path. Then: @@ -1008,7 +1065,9 @@ pub fn min_access_spans<'a>( - apply to the bundled reference document, through the core's `sheet.edit`, the insert of a detail view (`view_box` 625, 969, 220 × 660 on the main view) and of its access in `cat-access`; - build the archive snapshot and the PDF attachment of a report touching that sheet, the way the neighbouring case - does; + does. The edited document has a new fingerprint: load it as a new bundle whose `sheet-ref` carries the + fingerprint the core computes (`document_fingerprint`), without the historical alias. Loading it under the + bundled `sheet-ref` would be refused (`loaded.rs:191-210`); - assert the frozen N-1 scanner and `readArchiveDocument` and `assertSnapshot` accept it; - record in the test whether the lean snapshot carries `cat-access` (assert the observed fact, either way, with a comment). @@ -1028,19 +1087,16 @@ pub fn min_access_spans<'a>( - Modify: `docs/development/ANATOMICAL_SHEET_MODEL.md` (categories and editor refusals) - Modify: `docs/development/RUST.md` (§12, the editor commands; the wasm figure row) -- [ ] **Step 1: Replay the N-1 characterisation at its baseline (R3).** One command block, run from the repo root. The - worktree path is a fresh `mktemp -d`, written in the same command. `N1_BASE` is the sha recorded at Task 1. - -```bash -cd /home/bchanot/Documents/faunosteo-v1-2 && WT=$(mktemp -d) && \ -git worktree add --detach "$WT/core" "$N1_BASE" && \ -cp crates/core/tests/fixtures/n1/access-category.json "$WT/core/crates/core/tests/fixtures/n1/access-category.json" && \ -(cd "$WT/core" && cargo test -p faunosteo-core --test n1_access_category) ; \ -git worktree remove --force "$WT/core" -``` - - Expected: `test result: ok. 8 passed`. This is the baseline core reading, editing and rewriting the current fixture. - Record the output in the ledger. +- [ ] **Step 1: The N-1 characterisation still applies (R3).** The N-1 core read, edited and rewrote the fixture at + `N1_BASE` (Task 1, 9 passed). It holds for what the current core writes as long as the fixture is unchanged since + then; `the_fixture_is_the_slice_plus_the_view_and_its_access` proves the current core writes that fixture. + - Check: `git diff --quiet "$N1_BASE"..HEAD -- crates/core/tests/fixtures/n1/access-category.json && echo FIXTURE-UNCHANGED`. + - Expected: `FIXTURE-UNCHANGED`, recorded in the ledger. + - Only if it changed, replay the N-1 file at `N1_BASE` on the new fixture: + - in a `git worktree add --detach` made in a fresh `mktemp -d` path, copy the fixture and run + `cargo test -p faunosteo-core --test n1_access_category` there; + - print the worktree path and hand its removal (`git worktree remove `, then `git worktree prune`) to the + user. No recursive delete through a variable. - [ ] **Step 2: Existing sheets unchanged (R3 « fiches existantes »).** - `git diff --stat "$PLAN_BASE"..HEAD -- supabase/seed crates/core/tests/oracles apps/app/tests/fixtures/goldens packages/core-wasm/tests/n-1` prints nothing. @@ -1074,10 +1130,10 @@ git worktree remove --force "$WT/core" - Create: `apps/app/tests/unit/annotations.frameBox.test.ts` **Interfaces:** -- Consumes: `Frame` `{x, y, w, h}` from `editor/annotations/frame.ts`, and `round2` from `editor/annotations/gesture.ts` - (export it there if it is file-local). +- Consumes: `Frame` `{x, y, w, h}`, `XY` and `round2` from `editor/annotations/frame.ts`. Export that file's + file-local `floor2` and `ceil2` (`frame.ts:35-37`): Tasks 6, 10 and 14 round inward with them. - Produces, used by Tasks 8, 10, 11, 14: - - the types `XY`, `FrameHandle`, `FramePart`; + - the types `FrameHandle`, `FramePart`; - the constants `FRAME_HANDLES`, `MIN_FRAME_PX`, `SIDE_HANDLES_MIN_PX`; - the functions `boxFromCorners`, `intersection`, `clampInto`, `defaultBox`, `drawnBox`, `moveBox`, `resizeBox`, `ratioLabel`, `shownHandles`, `toViewBox`. @@ -1100,21 +1156,15 @@ git worktree remove --force "$WT/core" - `(2.718,1,'fr')` « 8:3 » (within 2 %); - `(2.45,1,'fr')` « 2,5:1 », and in English `'en'` « 2.5:1 ». - `shownHandles(40, 200)` hides `n` and `s` and keeps `e`, `w` and the four corners. - - `toViewBox` rounds to 0.01. + - `toViewBox` rounds inward to 0.01: the left and top edges up, the right and bottom edges down. - [ ] **Step 2: Run, expect failure:** `pnpm --filter @faunosteo/app exec vitest run tests/unit/annotations.frameBox.test.ts`. - [ ] **Step 3: Implement.** ```ts import type { ViewBox } from '@faunosteo/core-wasm/types' -import type { Frame } from './frame' -import { round2 } from './gesture' - -/** A point in drawing units. */ -export interface XY { - x: number - y: number -} +import type { Frame, XY } from './frame' +import { ceil2, floor2, round2 } from './frame' /** The eight handles of a frame (D8), clockwise from the top-left corner: their tab order. */ export type FrameHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' @@ -1267,8 +1317,14 @@ export function shownHandles(widthPx: number, heightPx: number): FrameHandle[] { }) } +/** The frame as a `view_box`, rounded inward to 0.01, so a frame held against the parent's edge never leaves it + * (the core's edge slack is 1e-9 of the span, `frame.rs:115-121`). */ export function toViewBox(box: Frame): ViewBox { - return { min_x: round2(box.x), min_y: round2(box.y), width: round2(box.w), height: round2(box.h) } + const l = ceil2(box.x) + const t = ceil2(box.y) + const width = round2(floor2(box.x + box.w) - l) + const height = round2(floor2(box.y + box.h) - t) + return { min_x: l, min_y: t, width, height } } ``` @@ -1439,11 +1495,18 @@ Board panels 01, 03, 09, 18, 19. Decisions D3, D6, D15, D16. - Modify: `apps/app/src/i18n/fr.ts`, `en.ts` - Test: new `apps/app/tests/unit/editor-view-commands.test.tsx` +**Interfaces:** +- Produces `ViewCommands` with props `{ onNew: (button: HTMLElement) => void; onParent?: (button: HTMLElement) => + void; onRecrop?: (button: HTMLElement) => void }`. A button whose handler is absent is not rendered: + - Task 11 passes `onRecrop`; + - Task 21 passes `onParent`. + So each task leaves a working strip. + Behaviour: 1. **Idle** (tool `select`, nothing selected, no creation, no frame): - on the main view, the strip shows « Nouvelle vue de détail »; - - on a detail view, it shows « Vue parente » (Task 21 wires it), « Recadrer la vue » (crop views only, i.e. + - on a detail view, it shows « Vue parente » (Task 21 wires it), « Recadrer la vue » (Task 11 wires it; crop views only, i.e. `svg_asset_id` null) and « Nouvelle vue de détail ». - The commands box keeps its fixed height (A6). `commandsKey` remounts the box instead of resizing it (LRN-131). 2. **« Nouvelle vue de détail »** calls `startFrame({ purpose: 'create', viewId: scene.viewId, drawnOn: scene.viewId, @@ -1513,12 +1576,13 @@ Board panels 04, 05, 11. Decisions D7, D13, D14, D18, D19. Arbitration A1. Owner - Tests: new `apps/app/tests/unit/annotations.viewCreation.test.ts`, new `apps/app/tests/unit/editor-view-creation.test.tsx` **Interfaces:** -- Consumes: - - `ACCESS_CATEGORY_ID` (Task 13: write that file first if Task 13 has not run; the execution order puts Task 13 - first); +- Consumes, all from tasks run before it: + - `ACCESS_CATEGORY_ID` (Task 13); - `toViewBox` and `clampInto` (Task 6); - - `PreviewState.min_access_span` (Task 3); - - `commitBatch` (`editorEdit.ts:275-291`), `geometryAccept` (`issues.ts:169`), `newElementId`. + - `bandInsets` and `bandClip` (Task 22), for « Fenêtre du bilan »; + - `uiState.accessTarget` (Task 14), the preset for « Je le tracerai ensuite »; + - `PreviewState.min_access_span` (Task 3), or the A1 alternative below; + - `commitBatch` (`editorEdit.ts:46-62`), `geometryAccept` (`issues.ts:169`), `newElementId`. - Produces: ```ts export type AccessChoice = 'frame' | 'later' | 'none' @@ -1543,7 +1607,7 @@ Board panels 04, 05, 11. Decisions D7, D13, D14, D18, D19. Arbitration A1. Owner - With `'later'` and `'none'`, only the view insert. - `accessBox` grows a 10 × 10 frame to a 29 × 29 square around the same centre when `minSpan` is 29, keeps it inside the bounds near an edge, reports `grown`, and leaves a large frame unchanged (`grown: false`). - - `rectanglePolygon` returns four vertices clockwise from the top-left, rounded to 0.01. + - `rectanglePolygon` returns four vertices clockwise from the top-left, rounded inward to 0.01. - `frameKnown` refuses a state whose report holds `view.frame.unknown` at the new view's path, and accepts otherwise. - [ ] **Step 2: Implement `viewCreation.ts` and the two `accessShape.ts` functions.** @@ -1552,16 +1616,17 @@ Board panels 04, 05, 11. Decisions D7, D13, D14, D18, D19. Arbitration A1. Owner import type { Polygon } from '@faunosteo/core-wasm/types' import type { Frame } from './frame' +import { ceil2, floor2, round2 } from './frame' import { clampInto } from './frameBox' -import { round2 } from './gesture' /** D5, D9: a rectangle access, stored as a polygon of four vertices clockwise from the - * top-left, so it reshapes by its vertices like a zone. */ + * top-left, so it reshapes by its vertices like a zone; rounded inward to 0.01, so an access + * held against the parent's edge stays inside it. */ export function rectanglePolygon(box: Frame): Polygon { - const l = round2(box.x) - const t = round2(box.y) - const r = round2(box.x + box.w) - const b = round2(box.y + box.h) + const l = ceil2(box.x) + const t = ceil2(box.y) + const r = floor2(box.x + box.w) + const b = floor2(box.y + box.h) return { type: 'polygon', points: [[l, t], [r, t], [r, b], [l, b]] } } @@ -1686,7 +1751,8 @@ export function frameKnown(viewId: string): (state: PreviewState) => boolean { `DiscardConfirm`, as `CreationDialog` does. « Ajuster le cadre » closes the dialog and keeps the box. - **Previews.** « Fenêtre du bilan » is a 4:3 box showing the parent drawing cropped to the box between neutral bands (Task 22's `bandInsets`). « Page du PDF » is a page sketch with the image at the box's ratio, half width, or - full width when `w ≥ 3h`. The constant is `PDF_FULL_WIDTH_RATIO = 3`. + full width when `box.w ≥ 3 × box.h`. The constant is `PDF_FULL_WIDTH_RATIO = 3`. The PDF decides on the same + numbers: the view's frame (Task 26), not its rounded raster. - [ ] **Step 4: Implement until they pass.** - Ids come from `newElementId('view')` and `newElementId('anno')`, built again once on `duplicate_key` (the `runBatch` pattern). @@ -1698,8 +1764,8 @@ export function frameKnown(viewId: string): (state: PreviewState) => boolean { choisissez « Je le tracerai ensuite » ou « Aucun pour l'instant », ou agrandissez le cadre. » - Focus goes to the access group. - [ ] **Step 5: The PDF constant stays in step with the core.** Add a test that reads - `crates/core/src/pdf/write/layout/observation.rs` and asserts it declares `const FULL_WIDTH_MIN_RATIO: u32 = 3;` - (Task 26 adds that constant). Before Task 26 runs, mark the test `it.todo`; Task 26 turns it into a real test. + `crates/core/src/pdf/write/layout/observation.rs` and asserts it declares `const FULL_WIDTH_MIN_RATIO: f64 = 3.0;` + (added by Task 26, which runs before this task) and that `PDF_FULL_WIDTH_RATIO` equals 3. | Key | fr | en | |---|---|---| @@ -1741,7 +1807,10 @@ Board panel 10. Decision D16. export function recropCommands(view: DetailView, box: Frame, follower: DetailTriggerAnnotation | null): EditCommand[] ``` `accessFollows` returns the one access on the parent opening the view whose polygon equals - `rectanglePolygon(oldBox)`, within 0.01 per coordinate. Otherwise it returns null. + `rectanglePolygon(accessBox(oldBox, minSpan, parentBounds).box)`, within 0.01 per coordinate: the shape the view's + creation gave it, grown or not (A1). Otherwise it returns null. `recropCommands` writes the follower as + `rectanglePolygon(accessBox(newBox, minSpan, parentBounds).box)`, so a smaller recrop keeps a readable access. + `minSpan` is `previewState.min_access_span[parentId] ?? null`; it is null under A1's alternative. Behaviour: @@ -1772,14 +1841,16 @@ Behaviour: - [ ] **Step 1: Failing tests.** - Pure: - - `recropCommands` gives one view update, plus one access update to `rectanglePolygon(newBox)` when a follower is - given; - - `accessFollows` finds the frame-shaped access and ignores a reshaped one. + - `recropCommands` gives one view update, plus one access update to the grown rectangle of the new box when a + follower is given; + - `accessFollows` finds the frame-shaped access, finds a grown one, and ignores a reshaped one. - Component: - recrop shows ghosts and no labels; - the checkbox is disabled for a reshaped access; - « Appliquer » makes one undo entry; - - a box that leaves an annotation outside is refused, the message shows, and the box stays. + - a box that leaves an annotation outside is refused, the message shows, and the box stays; + - a recrop of a view whose access was grown keeps the checkbox enabled; + - a recrop to a frame under the minimum, with the checkbox on, is accepted, because the follower is grown. - [ ] **Step 2: Implement until they pass.** - [ ] **Step 3: Run** both test files, `editor-repair.test.tsx` and `editor-tabs-views.test.tsx`, then `pnpm typecheck`. - [ ] **Step 4: Commit.** Message: `feat(editor): recrop a detail view on its parent drawing`. @@ -1856,10 +1927,11 @@ Focus 1. - `EditableAnnotations.tsx:307,415,485` (`noCategory` and the blocked flags use the ordinary categories; the access tool and « Nouvelle vue de détail » no longer need any category); - `SceneStrip.tsx:240`; - - `editor/annotations/missingFields.ts:118` (no category check for a new access); + - `editor/annotations/missingFields.ts:23` (no category check for a new access); - `editor/annotations/overview.ts:54-61`: the `cat-access` group is labelled `editor.annotations.access_group` and placed last, whatever name the document stores; - - `AnnotationReadBody.tsx:29` and `editor/sheetDocument.ts:110` (fixed label). + - `AnnotationReadBody.tsx:29`, `editor/sheetDocument.ts:110` and the catalogue's `ZonePanel.tsx:43-48` + (`zoneLine`): the fixed label, whatever name the document stores. - Test: new `apps/app/tests/unit/editor-access-category.test.tsx` **Interfaces:** @@ -1911,7 +1983,9 @@ Board panel 07. Decisions D5, D23. - Modify: - `apps/app/src/editor/annotations/uiState.ts`: `accessShape: 'rectangle' | 'polygon' | 'circle'`, default `'rectangle'`, kept when the `'view'` action resets the rest (the last choice lasts the session); also - `accessTarget: string | null`, the preset « Vue ouverte » of Tasks 10 and 12; + `accessTarget: string | null`, the preset « Vue ouverte » of Tasks 10 and 12. It is cleared on a view change, an + undo or a redo, an access commit, and when the access tool is disarmed. When it is used, it must still name a direct + child of the view (`model.children`), else it is ignored; - `usePlacement.ts` (`keyboardPending` and `placeAtCentre` by shape), `creation.ts` (`keyboardPending`); - `press.ts`: `ctx.drawing` for the link tool with rectangle or circle; - `usePressGesture.ts`: on release, the pending element goes through `placePending`, and the creation dialog opens @@ -1926,7 +2000,7 @@ Board panel 07. Decisions D5, D23. ```ts // accessShape.ts, added by this task import type { Circle } from '@faunosteo/core-wasm/types' -import type { XY } from './frameBox' +import type { XY } from './frame' /** D5: a circle dragged from its centre to its edge, kept inside `bounds`; a radius under * `minR` counts as a click: `fallback()`. */ @@ -1941,12 +2015,14 @@ export function defaultCircle(at: XY, visible: Frame, bounds: Frame): Circle { return circleInside({ type: 'circle', cx: at.x, cy: at.y, r: visible.w / 12 }, bounds) } -/** The circle moved (and shrunk only if larger) so it lies inside `bounds`, rounded to 0.01. */ +/** The circle moved (and shrunk only if larger) so it lies inside `bounds`, rounded inward to + * 0.01 so it stays inside them. */ export function circleInside(circle: Circle, bounds: Frame): Circle { - const r = Math.min(circle.r, bounds.w / 2, bounds.h / 2) - const cx = Math.min(Math.max(circle.cx, bounds.x + r), bounds.x + bounds.w - r) - const cy = Math.min(Math.max(circle.cy, bounds.y + r), bounds.y + bounds.h - r) - return { type: 'circle', cx: round2(cx), cy: round2(cy), r: round2(r) } + const r = floor2(Math.min(circle.r, bounds.w / 2, bounds.h / 2)) + const inside = (v: number, lo: number, hi: number) => Math.min(Math.max(round2(v), ceil2(lo)), floor2(hi)) + const cx = inside(circle.cx, bounds.x + r, bounds.x + bounds.w - r) + const cy = inside(circle.cy, bounds.y + r, bounds.y + bounds.h - r) + return { type: 'circle', cx, cy, r } } ``` @@ -1981,6 +2057,7 @@ Behaviour: - a rectangle drag opens the access dialog with a four-vertex polygon pending; - a circle drag opens it with a circle pending; - « Placer au centre » places each shape; + - `accessTarget` is cleared by an undo of the view it names, and an access is never preset to a removed view; - the dialog has no category field; - the committed access lands in `cat-access`. - [ ] **Step 2: Implement until they pass.** Run `annotations.accessShape.test.ts`, `editor-add-buttons.test.tsx`, @@ -2107,9 +2184,11 @@ export function pickAnnotation(elements: readonly Element[], within: Element): E return access } -/** The same pick at a client point. */ -export function annotationAt(x: number, y: number, within: Element): Element | null { - return pickAnnotation(document.elementsFromPoint(x, y), within) +/** The same pick for a pointer event: its target first (the top element; a synthetic click + * with no coordinates still resolves), then every element under its point. */ +export function annotationAt(event: { target: EventTarget | null; clientX: number; clientY: number }, within: Element): Element | null { + const top = event.target instanceof Element ? [event.target] : [] + return pickAnnotation([...top, ...document.elementsFromPoint(event.clientX, event.clientY)], within) } ``` @@ -2128,15 +2207,17 @@ export function annotationAt(x: number, y: number, within: Element): Element | n - a trigger over a point's hitbox returns the point; - a trigger alone returns the trigger; - an element outside `within` is skipped; - - a twin with no `data-anno-id` of its own resolves to its annotation. + - a twin with no `data-anno-id` of its own resolves to its annotation; + - `annotationAt` with an empty `elementsFromPoint` (a synthetic click) resolves through the target, so the + existing `clickZone` tests of `routes.EditorRoute.test.tsx`, `components.AnatomyCanvas.test.tsx` and + `routes.catalogue.test.tsx` keep passing unchanged. - `pressTarget` with hits `[access a, annotation p]` gives `other p`. - The catalogue: with `document.elementsFromPoint` stubbed to `[trigger, point ring]`, a click selects the point. - The bilan: the same stub makes `onZoneClick` receive the point's id. The tooltip shows the point's name, not nothing. - [ ] **Step 2: Implement.** - The catalogue and bilan handlers keep their current guards: `swallowClick` and the empty-tap verdicts. - - `useEmptyTap` uses `annotationAt(e.clientX, e.clientY, viewport)` at the press, so a press over a ring decides - « marker », as today. + - `useEmptyTap` uses `annotationAt(e, viewport)` at the press, so a press over a ring decides « marker », as today. - [ ] **Step 3: Run** the four test files, `editor-deselect.test.tsx` and `catalogue.useFraming.test.ts`, then `pnpm typecheck`. - [ ] **Step 4: Commit.** @@ -2219,6 +2300,8 @@ The `w` values are the board's measured tab widths, and the points are discs of - **Cut by the edge (panel 17):** access {-20,-10,80,60}, w 90 → box {4,4,90,20} with leader {30,24 → 30,25}. - **Off screen:** access {500,100,60,40} → neither placed nor in overflow. - **Long name:** request w 260 → box width 180. + - **Reserved corner (A8):** reserved {252,8,140,44} (the catalogue's zoom buttons), the « no place » access plus an + access {300,30,60,40} w 50 → both in `overflow`, `button` {284,58,110,28}. - **Panel 15:** the fixture's inputs, button 110 × 28 → `placed` equal to `expected.placed` within 0.002 px, `overflow` equal, `button` {227,6,110,28}. - **Property test,** 2 000 seeded random layouts: area 200 to 1 100 × 150 to 750, 1 to 8 accesses partly outside, 0 @@ -2226,6 +2309,7 @@ The `w` values are the board's measured tab widths, and the points are discs of - lies 4 px inside the area; - overlaps no other box and no disc, nor the button when there is one; - has no leader crossing another leader or another box. + The port with `reserved` was rerun on 2026-11-22: the panel 15 fixture and the 2 000 layouts still pass. - [ ] **Step 2: Run, expect failure.** - [ ] **Step 3: Implement.** @@ -2252,6 +2336,8 @@ export interface LabelLayoutInput { area: Box labels: readonly LabelRequest[] obstacles: readonly Disc[] + /** Boxes already used over the canvas, such as the catalogue's zoom buttons (A8). */ + reserved?: readonly Box[] /** The measured size of the « Autres vues (N) » button. */ button: { w: number; h: number } } @@ -2425,7 +2511,8 @@ function dropCrossings(items: Item[], overflow: Wanted[], wanted: readonly Wante } function layout(input: LabelLayoutInput, reserved: Box | null): { placed: PlacedLabel[]; overflow: string[] } { - const room: Room = { area: input.area, obstacles: input.obstacles, taken: reserved ? [reserved] : [] } + const taken = [...(input.reserved ?? []), ...(reserved ? [reserved] : [])] + const room: Room = { area: input.area, obstacles: input.obstacles, taken } const wanted = wantedOf(input.labels, input.area) const items: Item[] = [] const needy: Wanted[] = [] @@ -2448,17 +2535,26 @@ function layout(input: LabelLayoutInput, reserved: Box | null): { placed: Placed return { placed: items.map(({ id, box, leader }) => ({ id, box, leader })), overflow: overflow.map((w) => w.id) } } -/** D25: every label placed or listed, never lost. When some must go to the list, the corner - * of « Autres vues (N) » is reserved and the placement runs once more around it. */ -export function placeAccessLabels(input: LabelLayoutInput): LabelLayout { - const first = layout(input, null) - if (first.overflow.length === 0) return { ...first, button: null } - const button = { +/** « Autres vues (N) » in the top-right corner, under any reserved box already there (A8). */ +function buttonBox(input: LabelLayoutInput): Box { + const box: Box = { x: input.area.x + input.area.w - BUTTON_INSET - input.button.w, y: input.area.y + BUTTON_INSET, w: input.button.w, h: input.button.h, } + for (const r of [...(input.reserved ?? [])].sort((p, q) => p.y - q.y)) { + if (overlaps(box, r)) box.y = r.y + r.h + BUTTON_INSET + } + return box +} + +/** D25: every label placed or listed, never lost. When some must go to the list, the corner + * of « Autres vues (N) » is reserved and the placement runs once more around it. */ +export function placeAccessLabels(input: LabelLayoutInput): LabelLayout { + const first = layout(input, null) + if (first.overflow.length === 0) return { ...first, button: null } + const button = buttonBox(input) const second = layout(input, button) return { ...second, button: second.overflow.length > 0 ? button : null } } @@ -2487,8 +2583,11 @@ export interface AccessLabelsProps { box: RefObject /** The drawing host holding the core's layer. */ drawing: RefObject - /** Recompute triggers: view, framing transform, selection (handles), locale. */ + /** Recompute triggers: view, the surface's build counter (bumped after each svg rebuild), + * framing transform, selection (handles), locale. */ layoutKey: string + /** Boxes over the canvas the labels must leave free (the catalogue's zoom buttons, A8). */ + reserved?: RefObject[] hidden: boolean onActivate: (accessId: string, opensViewId: string) => void } @@ -2496,13 +2595,14 @@ export interface AccessLabelsProps { Behaviour: -1. **`useAccessLabels`, after layout** (`useLayoutEffect`, and again on `layoutKey` changes, `ResizeObserver` on - `box`, and an rAF throttle). It measures, relative to `box`'s client rect: +1. **`useAccessLabels`, after layout** (`useLayoutEffect` on `layoutKey`, which includes the surface's build counter, + so a rebuilt drawing is measured once it exists, and a resize observed with `HandleLayer`'s `useBoxSize`, exported + for this, with an rAF throttle). It measures, relative to `box`'s client rect: - each `[data-anno-kind="detail_trigger"]` element's client rect, in document order (the layer keeps it); - each point marker's disc: the hitbox circle's client rect centre, radius max(rect.w / 2, 11) + 4; - each `[data-handle]`'s centre and hit radius; - the label widths from a hidden measuring row of the same buttons; - - the « Autres vues » button's size. + - the « Autres vues » button's size, and the `reserved` elements' rects. It then calls `placeAccessLabels`. Nothing reaches the core (BDR-050). 2. **Each placed label** is a `