# 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 1. A Report v2 identifies a zone by `boneId` = the legacy `data-anno-id` (`point-mpbwtst0`), plus `detailSourceId` (`head`) for the head view. All 27 legacy ids differ from the canonical annotation ids (`hip`); the map is `legacy-import/legacy-id-map.json`. Findings are keyed by catalog zone key + node path, and that key already equals the canonical id (26/26). 2. Of the 612 legacy finding leaf paths, 170 do not exist in the curated draft: 136 moved because every `-observations` category became `-consultation-reasons` (CHG-004), 34 leaf ids were renamed or removed (CHG-005, 011, 012, 016, 017). These renames live in `curation/changes.json`, not in the legacy id map. 3. The app never draws markers today. They are elements of the SVG files (``): 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 and `categories[].color` is null. 4. The only state drawn is `data-state="current"` on the zones of the active observation: accent `#b85a3f` at 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. 5. `Horse_head.svg` is the same drawing as `Horse.svg` with `viewBox="60 100 500 380"`, which is the draft's head `view_box`. 6. 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. 7. Label text drives logic in two places: `zoneMatch.ts` (fuzzy SVG label to catalog zone, used by ObservationCard) and `spineZones.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. 8. 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. 9. The practitioner's archive is made of PDFs with v2 attachments produced by the deployed app. Their import must keep working in production. 10. 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 read `species/equine/*` directly. 11. Two authoring tools read the legacy `data-anno-*` format: the SVG editor route (1858 lines, vanilla DOM, no test) and `pathology-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`) ```text 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` + `viewId` replace `boneId` + `detailSourceId`. The pair is the zone identity everywhere (toggle, bilateral removal, spine sync). - `vertebrae[].region` becomes a free string checked against `vertebral_config.regions` at runtime, not a closed enum (BDR-031). - `severity` keeps its three values as stable codes `mild | moderate | severe`; the French and English labels come from i18n. The persisted values stop being accented French words. - `unresolved: true` marks 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. - `sheet` is required: a report always says which document it was built on. For the bundled draft, `sheetId` and `versionId` are the seed's deterministic ids and `documentSha256` the hash of `draft/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. - `localAnnotations` is 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`: ```text { annotations: { "": "" }, from legacy-id-map views: { "head": "head", "": "main" }, detailSourceId → viewId findingPaths: { "/": "/" | 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 ```text SheetProvider getReferenceSheet(): Promise LoadedSheet = { ref: { sheetId, versionId, documentSha256 }, document: AnatomicalSheetDocument, assets: Record } ``` 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 ```text 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 ``: - the drawing is the cleaned asset text, parsed once and sanitised (no `