24 KiB
Step 5 analysis: the application on the canonical sheet
Status: proposal, awaiting validation (2026-10-10). Nothing implemented.
Inputs: IMPLEMENTATION_PLAN.md Step 5, MIGRATION_STRATEGY.md §2 to §4,
FRONTEND_ARCHITECTURE.md §3, TEST_STRATEGY.md §2, ANATOMICAL_SHEET_MODEL.md
§2 and §6, CHARACTERIZATION_REPORT.md, memory decisions BDR-010/011/013/014/
015/019/031/034/036/037, and four read-only code analyses (core and store,
rendering and interactions, PDF, tests) run on the current apps/app.
Orientations given by the user for this step: keep the historical look and interactions of the markers but draw them from the document; use the curated equine draft as the reference content; show the review statuses in review interfaces only, never as badges on the drawings; render the head view as a crop of the main drawing while keeping independent views possible; check the framing before and after.
1. Facts that drive the design
- A Report v2 identifies a zone by
boneId= the legacydata-anno-id(point-mpbwtst0), plusdetailSourceId(head) for the head view. All 27 legacy ids differ from the canonical annotation ids (hip); the map islegacy-import/legacy-id-map.json. Findings are keyed by catalog zone key + node path, and that key already equals the canonical id (26/26). - Of the 612 legacy finding leaf paths, 170 do not exist in the curated
draft: 136 moved because every
<zone>-observationscategory became<zone>-consultation-reasons(CHG-004), 34 leaf ids were renamed or removed (CHG-005, 011, 012, 016, 017). These renames live incuration/changes.json, not in the legacy id map. - The app never draws markers today. They are elements of the SVG files
(
<g id="osteo-overlays">): each point is a transparent hitbox circle (r 34 joints, 30 junctions, 27 head) plus a visible twin (r 22 / 18 / 15, fill-opacity 0.65 main, 0.5 head, black 1.5 stroke) coloured by category; the five spine zones are magenta polygons (#e100ff, opacity 0.3); the head trigger is a dashed orange polygon at opacity 0.06 with no name. The document kept only the hitbox geometry andcategories[].coloris null. - The only state drawn is
data-state="current"on the zones of the active observation: accent#b85a3fat 0.85 on hitbox and twin, so a selected point shows as a disc of hitbox radius. Side, severity and other observations are not shown. A locale-aware tooltip follows the mouse. Horse_head.svgis the same drawing asHorse.svgwithviewBox="60 100 500 380", which is the draft's headview_box.- Every zone rule lives in
EditorRoute.tsx(552 lines): click dispatch, spine, bilateral and plain zone handlers, both picker confirmations, the three bone maps, highlight derivation, disclaimer, export. The store does whole-object replacement only. - Label text drives logic in two places:
zoneMatch.ts(fuzzy SVG label to catalog zone, used by ObservationCard) andspineZones.ts(region from label roots, used by the spine sync and the picker's initial tab). The draft renames 23 annotations and 13 zone names, so both would misbehave. - The PDF depends on markers for one thing: the highlight of the selected
zone before rasterising (
colorizedSvgString). Labels come from the SVG attributes and the catalog, finding text from the snapshots, vertebrae print as raw codes. The attachment is the full Report v2 JSON; import rejects any other version with a typed error. - The practitioner's archive is made of PDFs with v2 attachments produced by the deployed app. Their import must keep working in production.
- Tests: 41 files, 278 cases, happy-dom, rasterisation mocked everywhere.
Seven
char.*files (91 cases) pin the legacy assets: ids, attribute counts, click-chain outcomes in v2 shape, PDF strings, the head viewBox. 66 cases import the registry or readspecies/equine/*directly. - Two authoring tools read the legacy
data-anno-*format: the SVG editor route (1858 lines, vanilla DOM, no test) andpathology-editor.html(1700 lines, no test). Both are declared "not ported" by the frontend architecture; the merged sheet editor replaces them later (Step 17).
2. Target shape
2.1 Report document v3 (packages/domain)
Report v3
├─ version: 3
├─ id, createdAt, date, practitioner, animal, owner unchanged (snapshots)
├─ sheet: { sheetId, versionId, documentSha256 } exact sheet the report was built on
├─ observations[]: { id, zones[], findings[], freeTextFindings[], severity?, comment }
│ zone: { annotationId, viewId, side?, vertebrae?: { region: string, index }[] }
│ finding: { findingZoneId, path[], labelFrSnapshot, labelEnSnapshot,
│ requiresVetReferral?, side?, unresolved?: true }
├─ conclusion, recommendations, nextAppointment? unchanged
└─ localAnnotations: [] reserved (OPEN_QUESTIONS Q6), empty in Step 5
annotationId+viewIdreplaceboneId+detailSourceId. The pair is the zone identity everywhere (toggle, bilateral removal, spine sync).vertebrae[].regionbecomes a free string checked againstvertebral_config.regionsat runtime, not a closed enum (BDR-031).severitykeeps its three values as stable codesmild | moderate | severe; the French and English labels come from i18n. The persisted values stop being accented French words.unresolved: truemarks a finding whose(findingZoneId, path)does not exist in the referenced sheet. The snapshots still display it and the PDF still prints it. Nothing is dropped.sheetis required: a report always says which document it was built on. For the bundled draft,sheetIdandversionIdare the seed's deterministic ids anddocumentSha256the hash ofdraft/document.json.- Locale stays out of the report (BDR-014). The plan's "locale of last export" belongs to the PDF attachment envelope of Step 6, not to the report.
localAnnotationsis present and empty so that Step 14 does not need a version 4 to add report-only points once Q6 is decided.
2.2 v2 → v3 adapter and the migration map
The pipeline of Step 4c already records every rename and removal. It gains
one generated file, draft/report-migration-map.json:
{ annotations: { "<legacy data-anno-id>": "<annotation id>" }, from legacy-id-map
views: { "head": "head", "": "main" }, detailSourceId → viewId
findingPaths: { "<zone>/<legacy path>": "<zone>/<new path>" | null } } from the applier's records
The finding-path map is computed from the legacy baseline and the applier
records: a rename of a category or node rewrites the prefix of every path
under it; a removed subtree maps to null; a category removed and re-added
under another id (sphenoid, CHG-011) maps leaf by leaf when the same leaf id
exists at the same relative place under the new category, otherwise null.
The file is committed and golden-tested like the other artifacts, and the
CHANGELOG gains the counts: expected 442 identical paths, 136 remapped, at
most 34 unresolved.
migrateReportV2ToV3(report, map, sheetRef) is a pure function in
packages/domain: zones through annotations and views, findings through
findingPaths (null → unresolved: true, path kept as is), severity
through the code table, sheet filled from sheetRef. It never throws on
content: an unknown legacy id is kept verbatim and flagged, because losing a
practitioner's zone silently is worse than carrying an unresolved one.
Where v2 documents come from: sessionStorage['osteo:draft'] (migrated on
load, then saved back as v3) and the PDF attachments of the archive (migrated
at import). Both paths use the same function.
2.3 Sheet provider and bundling
SheetProvider
getReferenceSheet(): Promise<LoadedSheet>
LoadedSheet = { ref: { sheetId, versionId, documentSha256 }, document: AnatomicalSheetDocument,
assets: Record<svg_asset_id, string /* SVG text */> }
One implementation in Step 5, bundledSheetProvider, importing the generated
seed through a Vite alias (@sheets → supabase/seed/anatomical-sheets,
server.fs.allow widened to the repository root for dev). No copy of the
document into apps/app, no public/ fetch: the golden tests already
guarantee that the imported files are the pipeline's output, and the
Dockerfile copies the whole repository into the build context. The Supabase
implementation comes with Step 13 behind the same interface.
The provider returns the draft, as decided (BDR-037). The import of
legacy-import/document.json is not bundled: it is the migration baseline,
not a sheet the practitioner works on.
2.4 Separation: model, interaction service, store, UI
packages/domain canonical sheet (read-only in the app) + Report v3 + adapter
services/sheetIndex.ts pure lookups over a LoadedSheet: annotationsByView, annotation(id),
findingZone(id), regions(), nodeAt(zoneId, path) (replaces Bone maps,
zoneMatch, spineZones)
services/zoneInteraction.ts pure: decideZoneClick(annotation, observation, hasActive) →
open_detail | activate_fallback | open_vertebra_picker |
open_laterality_picker | remove_both_sides | toggle
+ pure reducers: toggleZone, addSides, syncVertebrae (BDR-019 semantics)
state/reportStore.ts holds Report v3; actions call the reducers; persistence behind
ReportPersistence with sessionStoragePersistence (migrates v2 on load)
UI EditorRoute wires events to the service and the pickers; AnatomyCanvas
and DetailModal render a view; ObservationCard reads sheetIndex
The store keeps activeObservationIndex client-side as today. The route
stops holding business rules and shrinks under the 300 lines the plan asks.
2.5 Rendering
renderAnnotationLayer(view, annotations, states, style) is a pure function
producing SVG elements for one view, appended after the drawing inside one
<svg viewBox=...>:
- the drawing is the cleaned asset text, parsed once and sanitised (no
<script>, no event attributes, LRN-025), its root attributes dropped; - the
viewBoxis the view'sview_boxwhen set, else the asset's own; the head view therefore renders the same drawing cropped to60 100 500 380, which is exactly whatHorse_head.svgdid; - each point annotation becomes the legacy pair: a transparent hitbox
(
rfrom the geometry) carryingdata-anno-id,data-anno-kind,data-anno-lateral,data-anno-region,data-anno-opens-view, and a visible twin whose radius, opacity and stroke follow a style table keyed by view kind (main: r × 22/34, opacity 0.65; detail: r × 15/27, opacity 0.5; black 1.5 stroke); - zone annotations (spine) become one polygon with the legacy magenta style;
detail triggers the dashed orange polygon;
pathgeometries a<path>; - colours come from
categories[].color, filled by a technical changeset with the legacy values (articulations#ff9500, os#a41e65, charnieres-vertebrales#ff0000, cadrans-du-crane#1baa08, zone-colonne#e100ff); the two per-view quirks of the head file (#ff8800joints,#d507c4hyoid) are dropped in favour of one colour per category; data-state="current"and the accent rule stay as they are, so the selected look is unchanged;- a
<title>child "FR / EN" and the mouse tooltip stay (names from the document, locale-aware).
The click delegation (closest('[data-anno-id]')) is unchanged. parseSvgBones
and the Bone type disappear: the layer is built from the document, so there
is nothing to parse back.
For the visual check asked by the user, the same function serialises the main
and head views with no state into draft/review/app-main.svg and
app-head.svg through the pipeline, rasterised by the operator with
ImageMagick like the 4c overlays. The before images are the current app's two
files; the after images are those renders. Framing and marker look are
compared side by side before the UI work starts.
2.6 PDF in Step 5 (shim)
observationPage takes the loaded sheet instead of refetching files: zone
titles from annotations[].name, finding headers from finding_zones[].name,
vertebrae still as codes, finding text from the snapshots (unresolved ones
printed as today, nothing special). The highlight is produced by rendering the
view through renderAnnotationLayer with data-state="current" on the
selected annotations, then rasterising as today. The picture keeps the same
drawing, the same accent and the same halo; only the moved points move.
The attachment carries the Report v3 as is. Import accepts v2 (migrated) and
v3. This touches pdf/import.ts and pdf/attachment.ts, which CLAUDE.md
gates behind an explicit confirmation: decision D3 below. The alternative,
converting v3 back to v2 for the attachment, would need a reverse id map and
would throw away the unresolved flags; it is not proposed.
3. Replace or refactor
| Current code | Fate | Why |
|---|---|---|
domain/species/** (registry, manifest, vertebrae, pathologies loader, bundled pathologies.json) |
delete | the sheet document carries species, views, assets, regions and the finding tree |
lib/zoneMatch.ts |
delete | finding_zone_id is explicit; its only consumer (ObservationCard) reads sheetIndex |
lib/spineZones.ts |
replace by syncVertebrae in the interaction service, keyed by vertebral_region_code |
region from data, no label roots; BDR-019 semantics kept and tested one-to-one |
anatomy/svgConvention.ts, anatomy/types.ts (Bone) |
delete | nothing to parse: the layer is generated |
anatomy/svgLoader.ts |
replace by a sanitising parser of the bundled asset text | one place, tested |
anatomy/labels.ts |
keep pickLocaleLabel, drop boneLabel |
labels are LocalizedText |
components/canvas/AnatomyCanvas.tsx, DetailModal.tsx |
rewrite thin: props = view + layer + states | same DOM contract for clicks and CSS |
app/routes/EditorRoute.tsx |
rewrite as wiring (< 300 lines) | rules move to the service |
state/reportStore.ts |
split: pure actions, persistence adapter, v3 | MIGRATION_STRATEGY §2 move A and B |
components/observation/VertebraPicker.tsx |
adapt: regions and counts from vertebral_config |
free codes, count_range |
components/observation/{ObservationCard,FindingsTreePicker}.tsx |
adapt: tree from sheetIndex, ids v3 |
no fuzzy match |
pdf/export.ts, pdf/render/observationPage.ts |
adapt (shim) | §2.6 |
pdf/attachment.ts, pdf/import.ts |
adapt: v2 migrated, v3 native | decision D3 |
app/routes/SvgEditorRoute.tsx, EditorsRoute.tsx, public/pathology-editor.html, styles/svg-editor.css |
delete in Step 5 (decision D4) or keep reading public/species/* untouched |
they edit a format the product no longer uses; the audit docs keep their functional reference for Step 17 |
public/species/equine/*.svg, pathologies.json |
keep until D4 is settled, then delete with the tools | the app itself stops reading them |
docs/ANATOMY-SVG-CONVENTION.md |
replace by "Annotation rendering contract" (attributes emitted by the layer, states, style table) | already out of sync with the code |
4. Regression risks and controls
| Area | Risk | Control |
|---|---|---|
| Zone selection | wrong identity after id change: a click on hip not matching a migrated zone |
identity = (annotationId, viewId) everywhere; click-chain tests migrated one-to-one with v3 expectations; adapter test on the golden v2 fixtures |
| Laterality | bilateral flag lost (legacy: absence of attribute = unpaired; canonical: explicit) | service reads annotation.laterality; test: each of the 10 bilateral annotations opens the side picker, the 18 others do not |
| Vertebrae | region inference gone; Cd range 15–21 vs picker cap 18; picker edits all regions at once | syncVertebrae keyed by vertebral_region_code; equivalence test against the legacy syncSpineZones outcomes on the same inputs; picker shows count by default and lets the practitioner extend to count_range.max (decision D6) |
| Findings | 170 legacy paths; snapshots must still print; tree picker must not crash on unresolved | migration map golden-tested; adapter test over all 612 legacy leaves; ObservationCard shows unresolved findings from snapshots with a neutral marker, no selection state |
| highlight picture changes; labels renamed; v2 archive import | golden PDFs produced by the current app before any change (full and minimal reports) become fixtures: import them with the new code and compare the migrated document to the expected v3 fixture; page-text assertions updated to the new labels, listed in the CHANGELOG of the step | |
| Draft persistence | a v2 draft in sessionStorage silently dropped |
readPersistedDraft migrates v2, rejects nothing silently (logs in DEV), test with the v2 fixture |
| Head view | framing differs from Horse_head.svg; detail title Détail — head |
same viewBox by construction; title from views[].name (decision D7); before/after renders compared by the user |
| Build | seed folder outside apps/app |
Vite alias + fs.allow; Docker build in CI already copies the repository; a build test imports the alias |
| Performance | layer re-rendered on each state change | memoised per view; states applied through attributes, not re-creation |
| Orphan findings | removing a zone leaves its findings (BDR-019 wart) | kept as is in Step 5, flagged unresolved only when the sheet lacks the path; cleaning is a separate decision (D5) |
5. Visible changes versus today
| Change | Cause | Needs validation |
|---|---|---|
| 10 points at new positions, one new point (carpus) | curated draft | already validated in 4c (to_confirm), nothing new |
| 23 annotation names and 13 zone names renamed (tooltips, badges, PDF) | curated draft | already validated in 4c |
| Findings tree: sphenoid restructured, new nodes, new descriptions, English descriptions | curated draft | already validated in 4c |
| Head detail title shows the view name ("Tête") instead of "Détail — head" | view names in the document | D7 |
| Head joints and hyoid colours aligned on the main view colours | one colour per category | D1 |
| Vertebra picker can go beyond the usual count up to the documented maximum | count_range |
D6 |
| Editor header mentions the sheet and its status ("brouillon de référence, non validé") | user rule on inherited data | D2 |
| Disclaimer text with the legal articles | curated draft | validated in 4c, question 3 still open |
/editors, /svg-editor and the pathology editor removed |
D4 | D4 |
Nothing else changes: layout, colours of the drawing, marker sizes, selection accent, tooltip, pickers, cards, PDF layout.
6. Tests
Before any code change: produce the golden artifacts of the current app and
freeze them: report-v2.full.pdf and report-v2.minimal.pdf exported by the
deployed version, plus the expected v3 documents after migration.
Migrated one-to-one (same assertion, new shape), with the replacing test named in the step's CHANGELOG:
| Characterisation today | Replacement |
|---|---|
char.clickChain (12) |
services/zoneInteraction branch tests on the draft annotations; outcomes in v3 shape |
char.svgCatalogLink, anatomy.horse |
sheetIndex tests: 28 annotations, 27 link a zone, one trigger opens head, 10 bilateral, 5 regions |
lib.spineZones (11) |
syncVertebrae equivalence table (same inputs, same outputs, codes instead of labels) |
lib.zoneMatch (23) |
deleted with the module; the importer kept the 26/26 proof in packages/anatomy |
char.pdfFull |
same report through the shim: drawn strings updated to the document labels; attachment v3; v2 golden PDF imported and deep-equal to the expected v3 |
state.reportStore*, state.draftMirror |
unchanged semantics on v3; plus v2 draft migration on load |
components.VertebraPicker |
regions from vertebral_config, count_range extension |
char.catalog, char.pathologyEditor |
deleted with the legacy copy and the editor (D4), their invariants live in packages/anatomy golden tests |
New: adapter over all 612 legacy leaves (counts pinned), layer renderer contract (attributes, radii, colours per category, state attribute), sanitiser, bundled provider (hash equals the seed's), PDF highlight rendering now unmocked on the layer function (the rasteriser stays mocked).
Visual check: draft/review/app-main.svg and app-head.svg rendered with
ImageMagick and compared with screenshots of the current app, before the UI
work starts and again at the end of the step.
7. Migration sequence
Each increment lands green (typecheck, lint, tests, build) on one feature branch, in this order:
- Freeze: golden v2 PDFs and expected v3 documents; CHARACTERIZATION_REPORT refreshed (41 files, 278 cases).
- Pipeline:
report-migration-map.json,app-main.svg/app-head.svg, category colours changeset; golden tests. packages/domain: Report v3, adapter, tests on fixtures and on the 612 leaves.- App foundation: sheet provider,
sheetIndex, layer renderer and sanitiser,AnatomyCanvasandDetailModalon views. Legacy flows still run on the registry until step 6. - Interaction service and store split, persistence adapter with v2
migration, pickers and cards on
sheetIndex, route rewired. - PDF shim and attachment v3, import of v2 (gate D3).
- Delete the legacy modules and tests, apply D4, replace the SVG convention doc, update CLAUDE.md, CHANGELOG, plan note, memory.
- Manual validation FR and EN of the full flow, visual before/after, gates (verifier, security).
Sizing: the largest increments are 4 and 5. The plan's "largest refactor of the app core" holds, but every increment is reversible on its own.
8. Decisions to validate
- D1. Marker colours. One colour per category stored in the document (legacy main-view values); the head file's two quirks disappear. Radii, opacities and strokes stay application style.
- D2. Review status in the app. Not shown per node in the practitioner's editor, no badge on drawings. The editor header shows the sheet name and status line "Brouillon de référence, non validé médicalement". Review interfaces (REVIEW-REPORT today, the editor of Step 17 later) carry the three statuses explicitly.
- D3. Attachment v3 and v2 import. Step 5 edits
pdf/attachment.tsandpdf/import.ts: v3 written, v2 read through the adapter, v1 still refused. Explicit confirmation requested here per CLAUDE.md. - D4. Legacy authoring tools. Recommended: delete
/editors,/svg-editor,pathology-editor.htmland thepublic/speciescopies in Step 5; the audit documents keep the functional reference for the merged editor (Step 17). Alternative: keep them untouched, readingpublic/species. - D5. Orphan findings. Keep the current behaviour (findings survive zone removal), add nothing in Step 5. Cleaning on zone removal would be a behaviour change to decide separately.
- D6. Vertebra picker and ranges. Show
countcolumns by default with a control to extend up tocount_range.max(Cd 21, T 19); belowminis not offered. Without this control the range stays data only. - D7. Detail view title. Use the view's localized name ("Tête" / "Head") instead of "Détail — head".
- D8. Severity codes. Persist
mild | moderate | severe, labels through i18n; the adapter maps the French values.
9. Left to later steps
- Q6 (report-only points):
localAnnotationsreserved, empty. - Locale of the last export: attachment envelope of Step 6.
- Sheet snapshot in the attachment, branding object: Step 6.
- Supabase
SheetProvider, Storage-served asset: Step 13. - Merged sheet editor replacing the deleted tools: Step 17.