docs(docs): V1-2.6 UX redesign technical plan, compatibility, tests, risks, decisions

This commit is contained in:
bchanot committed 2026-11-05 17:32:52 +01:00
1 parent f58cf2308f
commit 14fb527552
5 files changed
+1083

No files matched your search

+157
View File
@@ -0,0 +1,157 @@
# V1-2.6 UX redesign: technical decisions still needed
Status: PROPOSAL, 2026-11-05, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md`; this is the
single table of what blocks what. The 11 UX choices and the direct SVG interactions validated by the owner on
2026-11-05 are not reopened. Each item is a technical question they leave open, with a recommendation.
## Owner decisions
| Id | Question | Blocks | Recommendation |
|---|---|---|---|
| T1 | Fallback if the wasm budget is exceeded | U5 and U6 only if the measure exceeds 600 000 B; U9 certainly | `wasm-opt -Oz` as a pinned build tool, then a small D-R13 raise; the PDF split stays a separate track |
| T2 | Doctrine for optional category keys, and the owner's agreement to widen the snapshot reader | U6 | route A, no version bump, `v1` convention kept, rules amended |
| T3 | Opacity semantics | U6 | integer percent 10-100, point twins and zone fills, constants when absent |
| T4 | Tier of the fixed-category rules; residual gap on a first version | U6 | `edit.rs` refusals + `sheet_report` issues (existing verdict code), round-withdrawal migration; residual gap accepted and covered by review |
| T5 | Fixed categories of a new sheet: ids, names, default colours | U6 | `cat-bone`, `cat-joint`, `cat-vertebra`; Os / Bones, Articulations / Joints, Vertèbres / Vertebrae; equine colours |
| T6 | Equine working copy conversion | V1-2.8 | proposal below, decided at V1-2.8 |
| T9 | Replacing a crop by its own drawing | U5 | explicit choice when the `viewBox` differs, positions kept when equal |
| T10 | Category of an automatic access; sheet without category | U5 | the Joints category after U6; before U6 the first category; none → box unchecked |
| T11 | Fate of the level-1 owner trial | U1 | skip it; trial the redesign at U2 and U8 |
| T12 | Common text: source, versions, wording, responsibility | U7 | versioned module; wording supplied and validated by the owner |
| T14 | Multi-tab notice | none (follow-up) | not in V1-2.6; track as a follow-up |
| T15 | Header « Annuler » next to form « Annuler » | none | keep the label; accessible name « Annuler la dernière modification » |
| T16 | Curve handle editing in V1-2.6 | U9 | defer to the lot that first lets a path enter a document |
| T17 | Vertebral regions entry when no category has the vertebra role | U6 | keep a « Régions vertébrales » entry in the Annotations panel in that case only |
## Implementer decisions (recorded at U0, no owner question)
| Id | Decision | Reason |
|---|---|---|
| T7 | Strip `role` and `fill_opacity` from every envelope snapshot, at `lean_document` and at the export gate | the PDF needs neither; the only alternative breaks N-1 reading of new PDFs |
| T8 | Path ops (U9) compute on the written decimal digits; output precision = max(input precision, 2 decimals for a user move) | keeps « no other point moves » and exact round trips |
| T13 | No sub-branches: commit in place on `feature/v1-2-anatomical-sheets`, rollback by reverting a sub-step's commits | the gitflow lib branches only from develop and `finish` merges into develop |
| T18 | Handle cap per shape (constant fixed at U2 from the equine maxima with margin); above it, outline and a message | bounded DOM for oversized shapes saved directly |
| T19 | Sliders and arrow moves commit on release, Enter or blur | BDR-050; the 8 MiB history holds about 20 equine documents |
## T1 · Wasm budget fallback
- Facts: the gate measures Node `gzipSync` level 9 (`packages/core-wasm/tests/size.test.ts:12-25`): 592 143 B of
600 000 B, margin 7 857 B (measured 2026-11-05). Without curves the new core code is estimated at 4.5 to 13.5 KB.
The plan builds `annotations_in_rect` first and measures, then `remap_view`, then the U6 changes.
- Options if a measure exceeds the budget:
- (a) `wasm-opt -Oz`: gain unknown; `wasm-opt` is not installed (`RUST.md:4054`), so it becomes a pinned tool in
`scripts/wasm-build.sh`, the builder image and the release workflow.
- (b) raise the budget (D-R13) by the measured excess plus a margin: no work; a slightly slower first load.
- (c) lighter URL check (about 23 KB): must keep `new URL()` equivalence.
- (d) PDF code in a lazily loaded second module (about 55-60 KB): touches R4, the import worker, the CSP proof,
trap recovery and the readers of user data; its own track with its own owner checkpoint, never a prerequisite.
- Recommendation: (a), then (b) if still short. (d) only as a separate decision.
## T2 · Doctrine for optional category keys
- Facts: `.claude/rules/schemas.md:9-11` (« additive optional fields keep it ») against `.claude/rules/sheet-model.md`
(« Document schema change → bump … No bump during V1-2 (BLK-008) ») and BDR-068 (`v1` freezes construction and
validation). Route B (v3) is excluded by contract §12.3 (`V1-2_ANATOMICAL_SHEETS.md:1779-1781`) and needs a data
migration and a `save_sheet_draft` change. The snapshot reader (`assert_snapshot`, used by `archive/read.rs`) is a
reader of user data: CLAUDE.md requires the owner's agreement before widening it.
- Recommendation: route A as specified in `V1-2-6_UX_COMPATIBILITY.md` §1: an additive optional change of the v2
document, no version bump, the `sha256-rfc8785-validated-v1` construction unchanged (existing values proven equal
by tests); `sheet-model.md` amended to say that an optional key omitted when absent is not a version change, with
the proof list. Route C (reserved ids, no opacity) contradicts choice 5.
## T3 · Opacity semantics
- Recommendation: integer percent from 10 to 100 (below 10 a marker becomes invisible on the drawing while the 4 px
rules assume it visible). When present it drives the fill of point twins and of zones alike; when absent the
current constants stay (0.65 main and 0.5 detail for twins, 0.3 for zones), so existing renders are identical.
Detail triggers keep 0.06. The selected state keeps its accent at 0.85 (`apps/app/src/styles/index.css:14`).
Written first in `docs/ANNOTATION-RENDERING.md`. The layer writes it as `fill-opacity`, which the PDF highlight
overwrites: no PDF effect.
## T4 · Tier of the fixed-category rules
- Facts: edit refusals act only in the editor (`edit.rs:1-4`); a direct save is checked structurally only. A
`validate.rs` error would invalidate existing documents (fingerprint, snapshot gate). Issues added in
`sheet_report` (the `GEOMETRY_MISSING` pattern, `report.rs:17-19`) map to the existing
`verification.validation.rules` (`verdict.rs:277-296`), so no SQL code change. The contract requires a migration
withdrawing rounds in `verifying`, `open` or `approved` when the integrity rules change
(`V1-2_ANATOMICAL_SHEETS.md:945-949`).
- Options: (a) `edit.rs` refusals only; (b) (a) + report issues relative to the base (a role of the base must remain;
a role appears once) + the withdrawal migration.
- Residual in both: a first version has no base; a direct save, or « Garder ma version » from a tab running an older
bundle, can strip the roles before the first publication. It shows in the review of the `general` group.
- Recommendation: (b), consistent with O22, and the residual accepted.
## T5 · Fixed categories of a new sheet
- Recommendation: `sheet.empty` creates `cat-bone`, `cat-joint`, `cat-vertebra` (core-chosen, unlike the page's
`cat-<10 base32>` ids, `apps/app/src/editor/ids.ts:1-21`, so no collision); names FR « Os », « Articulations »,
« Vertèbres », EN « Bones », « Joints », « Vertebrae »; roles `bone`, `joint`, `vertebra`; default colours, shown
as « Couleur d'origine » (board 07 A), taken from the equine categories: `#a41e65`, `#ff9500`, `#e100ff`. Names stay
stored (old readers show them) and the edit rules refuse changing them.
## T6 · Equine working copy conversion (V1-2.8)
- Facts: five categories (`articulations` 12 annotations, `os` 2, `charnieres-vertebrales` 4, `zone-colonne` 5,
`cadrans-du-crane` 5). `os` and `articulations` already carry the fixed names; `zone-colonne` is « Segments
vertébraux / Vertebral segments ». Three own colours: atm and ssb `#ff8800`, hyoid `#d507c4`.
- Proposal: roles on `os`, `articulations`, `zone-colonne`; `zone-colonne` renamed « Vertèbres / Vertebrae » in the
working copy only (id unchanged); the two other categories stay free; own colours kept (choice 11) unless the
business review decides otherwise. The historical sheet and the Git seed never change.
## T9 · Replacing a crop by its own drawing
- Facts: the seed head drawing has exactly the crop's `viewBox` and the full drawing's path data: keeping positions
is right for it. A remap is right only for a drawing re-based on another `viewBox`.
- Recommendation: V equal to R → positions kept, no question. V different → the dialog asks « Même repère : garder
les positions » or « Dessin recadré : transposer les annotations », no default selected; transposition is uniform
(`meet`), centred, annotations to confirm. Labels to confirm by the owner.
## T10 · Category of an automatic access
- Recommendation: after U6, the Joints category (the equine access to « Tête » belongs to Articulations); before U6,
the first category of the sheet; a sheet without any category → the box is unchecked with the reason, the access
is placed later. Changeable in the properties.
## T11 · Fate of the level-1 owner trial
- Facts: level 1 is built and served for the trial (`V1-2-6_OWNER_TRIAL.md`); not tried yet. U1 and U2 replace its
tab structure and numeric journeys.
- Recommendation: skip the level-1 trial; keep its infrastructure (store, save, recovery, conflicts, upload, modes)
as the base; trial the redesign at U2 and U8. Level-1 criteria the redesign does not touch (C13 recovery, C14 undo
bound, C16 narrow read-only, C34, C41) stay in force and are re-tested.
## T12 · Common text
- Recommendation: a versioned module in the application (id, version, FR, EN), changed only by a reviewed commit;
wording supplied and validated by the owner or a person the owner names; the editor shows « texte commun,
version n » and never presents it as veterinary or legal advice approved by the platform. U7 starts only when the
wording exists. Contract §7.4 amended at U0.
## T14 · Multi-tab notice
- Facts: no multi-tab detection exists; the server revision check and the conflict dialog prevent silent loss; the
boards show no such notice.
- Recommendation: out of V1-2.6, tracked as a follow-up. If kept later: heartbeat-based (a crashed tab never says
goodbye), wording consistent with « Garder ma version ».
## T15 · « Annuler » wording
- Recommendation: keep the validated label; give the header button the accessible name and tooltip « Annuler la
dernière modification » / « Undo the last change ».
## T16 · Curve handle editing
- Facts: no document of the project holds a path; no product path creates one; the validated guarantee « aucune
courbe convertie » is held by display-only paths and the C45 refusal; board 05 shows curves as « exemple d'une
autre fiche ». The three path ops are the plan's heaviest work (610 to 1 020 lines, 10 to 21 KB) and need a
certain size lever and a round-withdrawal migration.
- Recommendation: defer U9 to the lot that first lets a path into a document (package import, zones from drawing
shapes, or a curve drawing tool), keep its specification (`V1-2-6_UX_PLAN.md` §2 D) and keep C45 and the closed
`remap.path` refusal meanwhile.
## T17 · Vertebral regions entry without a vertebra role
- Facts: board 09 opens the regions from the Vertèbres category; the equine working copy has no role before V1-2.8.
- Recommendation: when no category carries the vertebra role, the Annotations panel keeps a « Régions
vertébrales » entry; when one does, the entry sits under it as on board 09.