docs(chore): step 5 — annotation rendering contract, CLAUDE.md map and conventions, README, DEPLOY SHEET_BUNDLE, PDF format v3, spec §6 migration map, plan/changelog/strategy notes; BDR-038, LRN-043, TODO

This commit is contained in:
bchanot committed 2026-10-10 11:41:55 +02:00
1 parent ce2ec26112
commit 0476276a8f
19 files changed
+276 -112

No files matched your search

+70
View File
@@ -0,0 +1,70 @@
# Annotation rendering contract
**Status**: source of truth since Step 5. Replaces `ANATOMY-SVG-CONVENTION.md`
(the legacy `data-anno-*` attributes authored inside the SVG files).
The drawing of a sheet is a plain SVG asset with no annotation element. The
application draws the markers itself from the canonical document
(`docs/development/ANATOMICAL_SHEET_MODEL.md`): `renderAnnotationLayer` in
`packages/anatomy/src/render/layer.ts` turns the annotations of one view into
a pure element tree, materialised in the browser (`apps/app/src/anatomy/drawing.ts`)
or serialised by the pipeline (`draft/review/app-<view>.svg`).
## Elements emitted per annotation
| Kind | Geometry | Elements |
|---|---|---|
| `point` | circle | transparent hitbox (`r` of the geometry, `pointer-events: all`) + visible twin (`r − 12`, category or annotation colour, `fill-opacity` 0.65 on the main view / 0.5 on a detail view, black 1.5 stroke, `pointer-events: none`) |
| `zone` | polygon or path | one filled shape (`fill-opacity` 0.3, stroke 2) |
| `detail_trigger` | polygon or path | one dashed outline (`fill-opacity` 0.06, stroke 2, dash `8,4`, class `detail-zone`) |
Annotations without geometry draw nothing. Each element carries a `<title>`
"FR / EN" (native tooltip) and the attributes below.
## Attributes (the application's read contract)
| Attribute | Value |
|---|---|
| `data-anno-id` | annotation id (stable, the report's `annotationId`) |
| `data-anno-kind` | `point`, `zone` or `detail_trigger` |
| `data-anno-name-fr`, `data-anno-name-en` | annotation name; for a trigger, the opened view's name |
| `data-anno-lateral` | `unpaired`, `bilateral`, `left` or `right` |
| `data-anno-zone` | `finding_zone_id` when the annotation links a finding zone |
| `data-anno-region` | `vertebral_region_code` when the annotation opens the vertebra picker |
| `data-anno-opens-view` | `opens_view_id` of a trigger |
| `data-state` | `current` when the annotation belongs to the active observation |
Click handling walks up to the nearest `[data-anno-id]` and hands
`(annotationId, viewId)` to the interaction service
(`apps/app/src/services/zoneInteraction.ts`). Behaviour never depends on a
label, an element id or a class.
## Colours
`categories[].color` gives the colour of every annotation of a category;
`annotations[].color` overrides it (the head view keeps the shades the legacy
file used for the TMJ, the SBS and the hyoid). Both are document data, written
by the curation changeset, never by the renderer. Without either, the renderer
falls back to `#888888`.
## Views
A view renders on its `view_box` when set (the head view is the crop
`60 100 500 380` of the main drawing), else on the asset's own `viewBox`. A
detail view with its own `svg_asset_id` renders that asset: independent
drawings per view stay possible.
## Styling and states
The application stylesheet keeps the legacy rules: `.svg-canvas [data-state='current']`
fills the selected markers with the accent colour at 0.85, every `[data-anno-id]`
shows a pointer cursor and brightens on hover. The PDF export reuses the same
layer, then recolours the selected markers and hides the others before
rasterising (`apps/app/src/pdf/render/observationPage.ts`).
## Checking the look
`pnpm import:equine` writes `draft/review/app-main.svg` and `app-head.svg`.
Rasterise them with ImageMagick next to the legacy files (strip the `<title>`
elements first, ImageMagick's own SVG renderer drops shapes that carry one) to
compare markers and framing before and after a change.
+4
View File
@@ -1,3 +1,7 @@
**Status (2026-10-10)**: legacy format. `pathologies.json` is now an input of the
importer only (`supabase/seed/anatomical-sheets/equine/legacy-sources/`); the
application reads the canonical sheet document (`docs/development/ANATOMICAL_SHEET_MODEL.md`).
# Pathologies / Findings JSON Format
Each species ships a `pathologies.json` next to its `index.ts` manifest.
+17
View File
@@ -10,3 +10,20 @@ Will cover:
- JSON attachment spec (EmbeddedFiles, afRelationship:Data)
- Font handling (pdf-lib StandardFonts Helvetica/Times-Roman, WinAnsi; TTF Inter/Fraunces planned, not shipped)
- Import/re-import roundtrip contract
## Attachment versions (Step 5)
The attachment `osteo-report.json` carries the Report **v3** document
(`packages/domain/src/report/v3.ts`): zones by `(annotationId, viewId)`,
findings by `(findingZoneId, path)` with label snapshots, severity codes,
the `sheet` reference (sheet id, version id, sha256 of the document) and the
reserved `localAnnotations`.
Import (`importReportFromPdf(bytes, migrationMap)`) accepts:
- v3: read as is;
- v2 (PDFs produced by the application before Step 5, the practitioner's
archive): migrated through the sheet's `report-migration-map.json`; a zone
or finding the map cannot place is kept with its snapshots and flagged
`unresolved: true`; the outcome reports `migrated` and the unresolved counts;
- any other version: `ImportError('incompatible_version', foundVersion)`.
+17 -2
View File
@@ -304,7 +304,9 @@ the decision lands; only the naming one is implemented in this document.
## 6. Official equine sheet: import (Step 4b) and curation (Step 4c)
`packages/anatomy` holds a deterministic pipeline (`pnpm import:equine`)
that reads `Horse.svg`, `Horse_head.svg` and `pathologies.json`, then the
that reads the historical files kept under
`supabase/seed/anatomical-sheets/equine/legacy-sources/` (`Horse.svg`,
`Horse_head.svg`, `pathologies.json`, `vertebrae.ts`, never edited), then the
authored curation files, and writes under
`supabase/seed/anatomical-sheets/equine/`:
@@ -312,7 +314,7 @@ authored curation files, and writes under
| ---------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy-import/` | generated baseline | canonical `document.json`, `legacy-id-map.json` (every legacy `data-anno-id`, category slug and view key → new id), `assets.json` + byte-identical SVG copies, `IMPORT-REPORT.md` (French, for the osteopath: volumes, mappings, anomalies). No SQL. |
| `curation/` | authored, committed | `references.json` (the references registry) and `changes.json` (the changeset) |
| `draft/` | generated working revision | curated `document.json`, `assets.json` + `assets/horse.svg`, `CHANGELOG.md`, `REVIEW-REPORT.md`, `review/annotations-<view>.svg` (before/after drawing per view), `equine_draft.sql` |
| `draft/` | generated working revision | curated `document.json`, `assets.json` + `assets/horse.svg`, `sheet-ref.json` (sheet id, null version id, sha256 of the document), `report-migration-map.json` (legacy ids and finding paths → the draft, for Report v2 imports), `CHANGELOG.md`, `REVIEW-REPORT.md`, `review/annotations-<view>.svg` (before/after drawing per view), `review/app-<view>.svg` (the application's own rendering), `equine_draft.sql` |
Changeset (`packages/anatomy/src/curation/schema.ts`): each change has an
id `CHG-nnn`, a level (A demonstrated error, B supported improvement, C
@@ -388,6 +390,19 @@ database that still holds a schema 1 draft (a dev database seeded before Step
data migration that lifts stored documents to the current schema, then
tightens the CHECK (BLK-008). Future schema bumps follow that order.
Report migration map (Step 5): `draft/report-migration-map.json` replays the
applier's rename, move and removal records over every node of the legacy
baseline (792 nodes: 571 identical, 180 renamed or moved, 7 re-homed under
another category when the match is unique, 34 removed = `null`), maps the 27
legacy `data-anno-id` to annotation ids with the legacy names, and the `head`
detail key to the view. `migrateReportV2ToV3` (packages/domain) reads it; a
report keeps what the map cannot place, flagged `unresolved`.
Annotation colour (Step 5, additive, schema_version stays 2): `annotations[].color`
overrides `categories[].color` for the marker drawn by the application
(docs/ANNOTATION-RENDERING.md); the curation changeset CHG-045 carries the
legacy colours.
Seed: `equine_draft.sql` is idempotent and converging. On a fresh database
it inserts the sheet, the cleaned asset row and the draft through
`private.insert_sheet_draft`; when the sheet's only version is a draft
@@ -1,6 +1,11 @@
# Characterisation report (plan Step 1)
Status: done 2026-10-08, branch `feature/step-01-characterisation-tests`.
Note 2026-10-10 (Step 5): the legacy suites this report lists were replaced one-to-one
by suites on the canonical sheet (`services.zoneInteraction`, `sheets.provider`,
`state.reportStore`, `pdf.roundtrip`, `components.*`, `routes.EditorRoute`); the
frozen v2 fixtures (`report-v2.*.json`, `report-v2.*.pdf`) remain the oracle of the
v2 → v3 migration.
Scope: a tested photograph of the current application before any SaaS
transformation. No file under `src/`, `public/`, `scripts/`, `docker/` was
changed. Commands run on this host: Node 24.21.0, pnpm 10.13.1 (corepack),
+6
View File
@@ -161,6 +161,12 @@ Risks: subtle divergences between parser and importer on the detail trigger (no
attachment v3, replace-or-refactor table, risks, tests, 8 decisions D1–D8). Awaiting validation;
the orientations below supersede "annotation_finding_map" (inline finding_zone_id, BDR-031) and
"locale of last export" (locale stays out of the report, BDR-014).
Step 5 done 2026-10-10 (branch feature/step-05-app-on-canonical-sheet, awaiting user validation):
Report v3 + v2 migration (packages/domain/report), report-migration-map + sheet-ref + app review
drawings from the pipeline, annotation layer renderer (@faunosteo/anatomy/render), bundled
SheetProvider (SHEET_BUNDLE), zoneInteraction service, store on v3 with persistence adapter, PDF v3
with v2 archive import, legacy registry / matchers / editors / public species assets removed
(legacy sources moved under the seed). Visible changes limited to the validated 4c content and D6/D7.
```
```text
+11
View File
@@ -22,6 +22,9 @@ evolves without a big-bang rewrite. The step-by-step schedule is in
## 2. `reportStore`
Status 2026-10-10: moves A and B done in Step 5 (`state/persistence.ts`,
Report v3 in `packages/domain/report`); move C pending (Cloud reports).
Today: Zustand store holding `Report | null`, 14 actions, a `subscribe` that
mirrors every change to `sessionStorage['osteo:draft']`, restore on boot via
`ReportSchema.safeParse` (`reportStore.ts:42-56`, `159-167`).
@@ -39,6 +42,10 @@ UI state stay client-only.
## 3. Anatomy domain
Status 2026-10-10: points 1, 2, 4, 5 and 6 done (Steps 4, 4b, 5). Point 3 differs:
ids are stable slugs, not UUIDs (BDR-031/034). The renderer emits elements from
the document's geometry, not attributes on legacy elements (docs/ANNOTATION-RENDERING.md).
Today: four sources with no common object (manifest TS, two SVG files
fetched from `public/`, catalog JSON bundled), link by fuzzy label at render
time (audit 02 §1, 06 §1).
@@ -82,6 +89,10 @@ Evolution:
## 4. PDF
Status 2026-10-10: Step 5 took the sheet as export input and attached v3 with
v2 import; points 2 (sheet snapshot in the attachment), 3 (server import) and 5
(branding object) stay for Step 6.
Today: `exportReportToPdf(report, { locale })` re-fetches SVGs from
`public/`, re-parses them for labels, reloads the catalog through the
registry, rasterises in the browser, attaches the raw `Report` JSON.
+2 -1
View File
@@ -19,9 +19,10 @@ supabase/
│ └─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks
├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
├─ seed/anatomical-sheets/equine/ official equine sheet as a DRAFT, generated by `pnpm import:equine`
│ ├─ legacy-sources/ the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input)
│ ├─ legacy-import/ baseline import (document, id map, SVG copies, IMPORT-REPORT.md), no SQL
│ ├─ curation/ authored changes.json + references.json
│ └─ draft/ curated working revision (document, horse.svg, CHANGELOG, REVIEW-REPORT, review/*.svg) + equine_draft.sql: idempotent, converging seed (sheet, 1 asset row, working draft), applied by db reset and by PGlite
│ └─ draft/ curated working revision (document, horse.svg, sheet-ref.json, report-migration-map.json, CHANGELOG, REVIEW-REPORT, review/*.svg; bundled into the app with SHEET_BUNDLE=draft) + equine_draft.sql: idempotent, converging seed (sheet, 1 asset row, working draft), applied by db reset and by PGlite
└─ tests/ pgTAP, one file per concern, allowed AND denied paths
packages/supabase/
├─ src/client.ts createBrowserClient() (anon key, PKCE)
+6 -7
View File
@@ -85,7 +85,6 @@ works as `corepack pnpm <cmd>`.
| `pnpm build` | typecheck + Vite build in every package |
| `pnpm check` | typecheck, test:run, lint, build in sequence (what CI runs) |
| `pnpm format` | Prettier on the whole repository |
| `pnpm scaffold:species` | legacy species scaffold (slated for removal) |
Package-scoped: `pnpm --filter @faunosteo/app <script>`.
@@ -105,13 +104,13 @@ Package-scoped: `pnpm --filter @faunosteo/app <script>`.
"Ignored build scripts" warning.
2. `pnpm typecheck`, `pnpm test:run` (271 tests), `pnpm lint`, `pnpm build`
all exit 0; `apps/app/dist/` contains `index.html`, `env.js`,
`pathology-editor.html`, `species/equine/{Horse.svg,Horse_head.svg,pathologies.json}`.
`favicon`, logos (anatomy assets are bundled from the sheet seed, Step 5).
3. `pnpm dev`, then in the browser: `/` (home), `/new` (form, species defaults
to Cheval), `/editor` (SVG loads, click a hinge, a hip, a spine zone, the
head trigger; pickers open; findings picker lists the zone), export the
PDF, go back to `/` and import it; `/svg-editor` loads a project SVG;
`/pathology-editor.html` loads the pre-wired horse. Behaviour must match
`CHARACTERIZATION_REPORT.md`.
to Cheval), `/editor` (the bundled sheet renders, click a hinge, a hip, a
spine zone, the head trigger; pickers open; findings picker lists the
zone), export the PDF, go back to `/` and import it, then import an older
v2 PDF. Behaviour must match the suites listed in
`CHARACTERIZATION_REPORT.md` (note of 2026-10-10).
4. `grep -rn "/home/\|/Users/" apps/app/tests` returns nothing (no
machine-specific path; fixtures resolve from `import.meta.url`).
5. `docker build -t faunosteo .` then `docker compose up` and