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:
1 parent
ce2ec26112
commit
0476276a8f
19 files changed
+276
-112
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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)`.
|
||||
@@ -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),
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user