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

+8
View File
@@ -319,3 +319,11 @@ Status: closed; content awaits professional review (REVIEW-REPORT §10, 9 questi
User decisions: curated equine draft = reference draft of the app until published (no publication without professional review); technical integrity ≠ medical validation (`inherited` / `reviewed` / `to_confirm` stay visible, REVIEW-REPORT the hand-off doc for the osteopath, 11 open questions → next changeset); future schema changes = incremental non-destructive migrations (BLK-008); legal scope text re-read on consolidated Légifrance texts before publication; head view preserved as crop, per-view assets still possible. Docker `faunosteo_` rule permanent; `.env.example` change documented in DEPLOY.md (file denied to Claude). SaaS development continues without waiting for medical validation.
Status: closed.
---
## BDR-038 | 2026-10-10 | Step 5: app on the canonical sheet — bundled sheet, layer renderer, Report v3, migration map
Sheet source: `SheetProvider` interface; Step 5 implementation = Vite virtual module `virtual:faunosteo-sheet` built from the seed draft (`vite/sheet-bundle.ts`), mode `SHEET_BUNDLE=draft|none`, default draft for dev server, none for builds/CI/Docker (`--build-arg SHEET_BUNDLE=draft` = explicit preview) → unvalidated draft never ships by accident (D2). Markers: pure renderer `@faunosteo/anatomy/render` (element tree, no DOM) reproduces legacy look (hitbox r + twin r−12, opacities 0.65/0.5, spine 0.3, trigger 0.06 dashed); colours = document data (`categories[].color`, additive `annotations[].color` for the head shades, schema_version stays 2 for additive optional fields); same renderer feeds `draft/review/app-<view>.svg` for visual checks. Report v3 in packages/domain: `(annotationId, viewId)` zones with label snapshots, `(findingZoneId, path)` findings, severity codes, `sheet {sheetId, versionId|null, documentSha256}`, `unresolved: true` for what migration cannot place, `localAnnotations: []` reserved. Migration map generated by the pipeline from applier records (replay renames/moves/removals + unique re-homing): 792 nodes → 571/180/7/34. Interaction = pure service + reducers (BDR-019 kept); store = v3 + persistence adapter (v2 draft migrated on restore). D4 applied: registry, matchers, SVG parser, editors, pathology-editor, public species assets deleted; legacy sources moved to `supabase/seed/.../legacy-sources/` (importer input).
Alt rejected: copying the draft into apps/app (duplication, drift); runtime fetch of `/sheets/*.json` (still public, no gain); UUID annotation ids (BDR-031); converting v3→v2 for attachments (lossy); per-view colour table in the app (horse knowledge in generic code).
Status: closed; awaiting user validation of Step 5.
+1
View File
@@ -190,3 +190,4 @@ Step 4 validated + finished into develop. User decisions on the 7 open points
- Gates 4c: verifier ×3 (4→2→1 écarts, last 3 doc lines fixed by hand at cap), executor closed the applier rule + typed tests; security PASS (LOW url scheme → SQL rule `reference.url.scheme`). Real stack 267/267, Storage e2e OK. EVAL-010. Awaiting user validation; `.env.example` COMPOSE_PROJECT_NAME left to the user (file denied).
- Step 4c VALIDATED by user 2026-10-10 → tracking: head view check documented (spec §6), BLK-008 migration limit, BDR-037, DEPLOY.md `.env.example` note. Finished into develop. Next: Step 5 (app on the canonical sheet), design points flagged before any UI work.
- Step 5 preparation (2026-10-10): 4 analyzer agents (core/store, rendering, PDF, tests) + plan/spec reading → docs/development/STEP5_MIGRATION_ANALYSIS.md on chore/step-05-migration-analysis. Key facts: all 27 legacy data-anno-ids differ from canonical ids; 170/612 legacy finding paths moved/removed by curation → generated report-migration-map; markers never drawn by the app (in the SVG); PDF depends on markers only for the highlight; 66 tests import the registry. 8 decisions D1–D8 await the user. No implementation.
- Step 5 implemented (2026-10-10, feature/step-05-app-on-canonical-sheet): domain report v3 + migration (80 tests), pipeline migration map/sheet-ref/app review drawings + layer renderer (110), app rewritten on the sheet (99 tests: service, store, provider, canvas, pickers, PDF v2/v3, route), legacy code removed, docs rewritten (ANNOTATION-RENDERING.md replaces the SVG convention). Root check green, docker build OK, real stack 267/267, default build carries no sheet. BDR-038, LRN-043. Gates next; awaiting user validation.
+7
View File
@@ -323,3 +323,10 @@ Apply: every pgTAP touching storage.*; every workspace CLI.
Authoring 44 changes / 679 ops by hand is error-prone → scratch python modules (one per research theme, shared helpers `set_op/cite_op/add_change`, auto-numbered ids, targets derived from the baseline by walking it) built into changes.json; the pipeline's Zod + integrity rules catch any bad target at once. Order of modules = order of ops: a later module must address ids renamed by an earlier one (consultation-reason category ids). Stylised drawing: render with `magick` + 50-unit grid crops; sample first non-white row per column to prove "point floats above the silhouette" (t18-l1, l6-s1 were 30-70 units above the back). ImageMagick's internal SVG renderer drops shapes with `fill="none"` and shapes containing a `<title>` child → overlay uses fill-opacity and puts `<title>` on the `<g>`. Research agents: one theme each, every citation tagged VERIFIED-fetched/snippet/UNVERIFIED; only fetched or bibliographically confirmed entries enter the registry, unread books say "non consulté" in the citation.
Apply: next species/sheet curation; any overlay/diagnostic SVG rasterised with ImageMagick.
---
## LRN-043 | 2026-10-10 | Migrating an app onto a new data model: freeze goldens first, make ids + maps data, read fresh state in DOM handlers
Freeze golden artifacts with the OLD code before touching it (v2 PDFs via a one-shot vitest, MAKE_GOLDEN=1, deleted after): the new importer is then tested against real archive-like bytes. Generate id/path maps from the pipeline's own records (renames/removals), never hand-written, and commit them as golden-tested data. In React routes, click handlers bound through `useEffect` capture stale closures when two DOM clicks land before a re-render (tests dispatch synchronously): read `store.getState()` inside the handler. A sheet needed to restore a draft but only known from the draft → load the default species' sheet when no report is open. Vitest has its own config: a Vite plugin providing a virtual module must be registered there too. ImageMagick cannot verify marker look with `<title>` children or `fill="none"`: strip titles for the raster only.
Apply: Step 6 (PDF v3 snapshot), Step 13 (Supabase SheetProvider), any future schema bump.
+9 -9
View File
@@ -86,15 +86,15 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo
- [x] 4c.5 reports: REVIEW-REPORT.md for the osteopath (10 sections, questions ranked), CHANGELOG table, before/after review SVGs (draft/review/, PNG renders by operator), quantitative before/after.
- [ ] 4c follow-up (open, not blocking Step 5): 11 questions for the osteopath (draft/REVIEW-REPORT.md §10) → next changeset; legal scope text to re-read on consolidated Légifrance articles before publication; BLK-008 data migration v1→v2 before real data; user action `.env.example` COMPOSE_PROJECT_NAME=faunosteo (DEPLOY.md)
- [x] 4c.6 verify (root check 68+21+100+278, PGlite + real stack 267/267, types, docker build, Storage e2e; verifier ×3 → fixes, security PASS; EVAL-010): pnpm check, PGlite + real stack pgTAP, types, docker build, golden tests; gates verifier + security; docs (spec §6/§7, SUPABASE.md, CLAUDE.md, plan Step 4c, CHANGELOG); memory (BDR/LRN/EVAL/journal). Stop for user validation.
- [ ] Step 5 — application on the canonical sheet (analysis 2026-10-10, branch chore/step-05-migration-analysis, AWAITING user validation of docs/development/STEP5_MIGRATION_ANALYSIS.md and decisions D1–D8; no implementation before)
- [ ] 5.0 freeze: golden v2 PDFs + expected v3 docs; CHARACTERIZATION_REPORT refreshed
- [ ] 5.1 pipeline: report-migration-map.json (annotations, views, findingPaths 442/136/≤34), app-main.svg + app-head.svg review renders, category colours changeset (D1)
- [ ] 5.2 packages/domain: Report v3 (annotationId+viewId, free region codes, severity codes D8, sheet ref, unresolved findings, localAnnotations []), migrateReportV2ToV3, tests on fixtures + 612 leaves
- [ ] 5.3 app foundation: bundledSheetProvider (Vite alias @sheets), sheetIndex, sanitiser, renderAnnotationLayer (legacy look), AnatomyCanvas/DetailModal on views (head = crop)
- [ ] 5.4 zoneInteraction service + reducers, store split + sessionStoragePersistence (v2 migration on load), pickers/cards on sheetIndex (D6 ranges, D7 title), EditorRoute < 300 lines
- [ ] 5.5 PDF shim + attachment v3 + v2 import (gate D3)
- [ ] 5.6 delete legacy (registry, species/*, zoneMatch, spineZones, svgConvention, D4 tools), SVG convention doc replaced, CLAUDE.md map, CHANGELOG, plan note, memory
- [ ] 5.7 manual FR/EN flow, visual before/after, gates verifier + security
- [ ] Step 5 — application on the canonical sheet (analysis validated 2026-10-10; implemented on feature/step-05-app-on-canonical-sheet, AWAITING user validation; D5 orphan findings documented as UX follow-up)
- [x] 5.0 freeze: golden v2 PDFs + expected v3 docs; CHARACTERIZATION_REPORT refreshed
- [x] 5.1 pipeline: report-migration-map.json (annotations, views, findingPaths 442/136/≤34), app-main.svg + app-head.svg review renders, category colours changeset (D1)
- [x] 5.2 packages/domain: Report v3 (annotationId+viewId, free region codes, severity codes D8, sheet ref, unresolved findings, localAnnotations []), migrateReportV2ToV3, tests on fixtures + 612 leaves
- [x] 5.3 app foundation: bundledSheetProvider (Vite alias @sheets), sheetIndex, sanitiser, renderAnnotationLayer (legacy look), AnatomyCanvas/DetailModal on views (head = crop)
- [x] 5.4 zoneInteraction service + reducers, store split + sessionStoragePersistence (v2 migration on load), pickers/cards on sheetIndex (D6 ranges, D7 title), EditorRoute < 300 lines
- [x] 5.5 PDF shim + attachment v3 + v2 import (gate D3)
- [x] 5.6 delete legacy (registry, species/*, zoneMatch, spineZones, svgConvention, D4 tools), SVG convention doc replaced, CLAUDE.md map, CHANGELOG, plan note, memory
- [~] 5.7 visual before/after done (cmp renders), root check + docker + real stack green; gates verifier + security pending; manual FR/EN flow = user validation
---
+1
View File
@@ -11,6 +11,7 @@ Versions follow [Semantic Versioning](https://semver.org/).
- **Supabase foundation** — local stack (`supabase/config.toml`), migrations (schemas `private` / `audit`, `profiles`, platform roles with audited RPCs), pgTAP suite run on PGlite (`pnpm test:run`) and on the real stack (`pnpm db:test`), `@faunosteo/supabase` typed client + generated types. No UI change.
- **Anatomical sheet model** — `@faunosteo/domain`: canonical sheet document (views tree, annotations with stable ids and explicit laterality, ordered vertebral regions, typed finding categories, explicit annotation → finding zone links, FR/EN labels) with integrity validation; tables `species`, `anatomical_sheets`, `anatomical_sheet_versions` (published rows immutable, one draft per sheet, deletion preconditions), `anatomical_sheet_assets`; lifecycle RPCs (create, draft, publish, deprecate, delete, fork with provenance, archive, assets) audited and under RLS. Spec: `docs/development/ANATOMICAL_SHEET_MODEL.md`.
- **Application on the canonical sheet (Step 5)** — the editor renders the bundled reference sheet (curated equine draft, `SHEET_BUNDLE=draft`; a default build carries no sheet): markers drawn from the document with the legacy look (`@faunosteo/anatomy/render`), head view as a crop of the same drawing, zone interaction service, pickers on the sheet's regions (usual count, extension to the documented range) and finding zones. Report document **v3** (`packages/domain/report`): zones by annotation and view ids, findings by zone and path, severity codes, exact sheet reference; v2 PDFs and drafts migrate through the generated `report-migration-map.json`, unresolved items kept with their labels. Removed: species registry, label matchers, SVG convention parser, `/editors`, `/svg-editor`, `pathology-editor.html`, `scaffold:species`; the legacy sources now live under `supabase/seed/anatomical-sheets/equine/legacy-sources/`.
- **Equine sheet curation (Step 4c)** — document schema v2 (references registry, `review_status` on findings and annotations, configurable vertebral `count_range`; migration `20261010100000`, pgTAP 008); `@faunosteo/anatomy` curation pipeline: authored changeset (`curation/changes.json`, levels A/B/C, before/after records) applied to the legacy baseline → working draft with `CHANGELOG.md`, `REVIEW-REPORT.md` (10 sections for the osteopath) and before/after review drawings; one cleaned SVG asset, head view as a crop. Content: research-backed audit of the horse sheet (44 changes, 48 verifiable references): sphenoid zone restructured, NAV terminology, FR/EN translations, vertebral ranges, ten SVG points relocated, carpus zone added, veterinary red flags, legal disclaimer anchored on R. 243-6 / R. 243-8, osteopathic-model status on unvalidated concepts, 11 questions for the professional. Still a private DRAFT, not published. Docker resources prefixed `faunosteo_` (Compose project and container).
- **Equine import (Step 4b)** — `@faunosteo/anatomy` deterministic importer: `Horse.svg` + `Horse_head.svg` + `pathologies.json` → canonical document, legacy id map, French import report, idempotent seed creating the official sheet `faunosteo-cheval` as a private DRAFT (never published by code). Storage bucket `anatomical-sheet-assets` (content-addressed SVGs, read through the sheet, operator upload script).
+64 -57
View File
@@ -14,8 +14,10 @@ attachment so importing it restores the session for a follow-up.
SPA deployed via Docker + nginx on Scaleway VPS. Backend foundation on Supabase
(PostgreSQL + Auth + RLS) since Step 3 of the SaaS plan: profiles, platform roles and
audit log exist; Step 4 added the canonical anatomical sheet model (`packages/domain`,
tables `species`, `anatomical_sheets` / `_versions` / `_assets`). The UI does not use
the client yet (local-only flows unchanged).
tables `species`, `anatomical_sheets` / `_versions` / `_assets`). Step 5 moved the
application onto that model: the editor renders the bundled reference sheet (the
curated equine DRAFT, `SHEET_BUNDLE=draft`), writes Report v3 and imports v2 PDFs
through a generated migration map. The Supabase client is still unused by the UI.
MVP species: equine only. Open-source MIT.
---
@@ -81,6 +83,11 @@ pnpm db:reset # replay from zero
pnpm db:test # pgTAP on the real stack
pnpm db:types # regenerate packages/supabase/src/database.types.ts
pnpm db:types:check # CI diff
# Reference sheet in the app: the dev server bundles the curated draft; a build does not
pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments)
pnpm preview:draft # same, then serves it
pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings)
```
## Docker commands
@@ -89,6 +96,9 @@ pnpm db:types:check # CI diff
# Build image
docker build -t faunosteo .
# Build an image that embeds the reference DRAFT sheet (preview only, never the default)
docker build --build-arg SHEET_BUNDLE=draft -t faunosteo .
# Run with compose (reads .env for APP_* vars)
docker compose up --build
@@ -136,40 +146,28 @@ pnpm format # Prettier write
```
faunosteo/
├─ apps/app/ ← @faunosteo/app (everything below until packages/)
├─ public/
│ ├─ species/equine/{Horse,Horse_head}.svg ← real anatomy SVGs
│ └─ pathology-editor.html ← standalone JSON editor (served as static file)
├─ public/ ← logos only (no anatomy asset: the sheet is bundled)
├─ vite/sheet-bundle.ts ← Vite plugin: `virtual:faunosteo-sheet` (SHEET_BUNDLE=draft|none)
├─ src/
│ ├─ app/
│ │ ├─ App.tsx ← root router
│ │ ├─ routes/{Home,NewReport,Editor,Editors,SvgEditor,NotFound}Route.tsx
│ │ ├─ routes/{Home,NewReport,Editor,NotFound}Route.tsx
│ │ └─ providers/ConfigProvider.tsx ← AppConfig context
│ ├─ config/env.ts ← runtime config resolution
│ ├─ domain/
│ │ ├─ schema/ ← Zod schemas (source of truth)
│ │ │ ├─ report.ts
│ │ │ ├─ observation.ts
│ │ │ ├─ practitioner.ts
│ │ │ ├─ animal.ts
│ │ │ └─ findings.ts
│ │ └─ species/
│ │ ├─ types.ts ← SpeciesManifest interface
│ │ ├─ registry.ts ← getSpecies(), getAllSpecies()
│ │ └─ equine/{index,vertebrae,pathologies}.{ts,json}
│ ├─ sheets/{provider,useSheet}.ts ← SheetProvider interface, bundled implementation, per-species hook
│ ├─ services/
│ │ ├─ sheetIndex.ts ← read-only lookups over the loaded sheet (ids, never labels)
│ │ └─ zoneInteraction.ts ← pure click decision + observation reducers (zones, sides, vertebrae)
│ ├─ i18n/
│ │ ├─ types.ts ← Locale type + Dict type
│ │ ├─ fr.ts + en.ts ← translation dicts (flat key → string)
│ │ ├─ index.ts ← getDict(locale)
│ │ └─ useT.ts ← useT() hook (reads localeStore)
│ ├─ state/
│ │ ├─ reportStore.ts ← Zustand store
│ │ ├─ reportStore.ts ← Zustand store (Report v3) + persistence.ts (sessionStorage adapter, v2 draft migration)
│ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage)
│ │ └─ practitionerCache.ts ← localStorage prefill
│ ├─ anatomy/
│ │ ├─ types.ts ← Bone, BoneCategory, BoneState
│ │ ├─ svgConvention.ts ← parseSvgBones()
│ │ ├─ svgLoader.ts ← loadSvg()
│ │ └─ labels.ts ← boneLabel(bone, locale, fallback)
│ ├─ anatomy/drawing.ts ← sanitised asset + generated annotation layer → inline <svg> per view
│ ├─ components/
│ │ ├─ ui/{Button,Card,Dialog,Input,Label,Select,Textarea,Badge,Chip}.tsx
│ │ ├─ canvas/{AnatomyCanvas,DetailModal}.tsx
@@ -182,8 +180,8 @@ faunosteo/
│ ├─ pdf/
│ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts
│ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng,text,logo,linkAnnotation}.ts
│ ├─ lib/{dates,id,assert,zoneMatch,spineZones,supabase}.ts ← supabase.ts: getSupabaseClient() | null
│ ├─ styles/{index,tokens,svg-editor}.css ← Tailwind v4 CSS-first + SVG editor styles
│ ├─ lib/{dates,id,assert,supabase}.ts ← supabase.ts: getSupabaseClient() | null
│ ├─ styles/{index,tokens}.css ← Tailwind v4 CSS-first
│ └─ main.tsx
├─ tests/
│ ├─ setup.ts
@@ -192,8 +190,7 @@ faunosteo/
│ ├─ entrypoint.sh ← injects env.js at container start
│ └─ nginx.conf ← SPA fallback + PORT envsubst
├─ docs/
│ ├─ ANATOMY-SVG-CONVENTION.md ← SVG data-* contract
│ ├─ ADDING-A-SPECIES.md
│ ├─ ANNOTATION-RENDERING.md ← annotation layer contract (attributes, styles, colours)
│ ├─ PDF-FORMAT.md
│ ├─ faunosteo-audit/ ← audit of the current system (frozen at 83e40af)
│ ├─ development/ ← SaaS implementation plan, WORKSPACE.md
@@ -204,7 +201,7 @@ faunosteo/
├─ packages/domain/ ← @faunosteo/domain (pure, no DOM, zod only)
│ ├─ src/anatomical-sheet/{schema,validate,create}.ts ← canonical sheet document + integrity rules
│ └─ tests/{fixtures/horse-slice.ts,*.test.ts}
├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer (SVG + catalog → canonical document) + curation
├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, pure annotation-layer renderer (`./render`)
│ ├─ src/legacy/{svg,catalog,regions,ids,report,importer}.ts, src/cli/import-equine.ts
│ ├─ src/curation/{schema,targets,fields,ops,rename,apply,types,assets,labels,stats,changelog,review-report,overlay,seed,sources,pipeline}.ts ← changeset → draft
│ └─ tests/ ← counts preserved, special cases, determinism, curation ops, golden artifacts
@@ -215,9 +212,10 @@ faunosteo/
│ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts
│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets, storage, sheet_document_schema_v2
│ ├─ seed/anatomical-sheets/equine/
│ │ ├─ legacy-sources/ ← the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input, never edited)
│ │ ├─ legacy-import/ ← GENERATED baseline: document, id map, IMPORT-REPORT, SVG copies (no SQL)
│ │ ├─ curation/{changes,references}.json ← AUTHORED changeset + references registry (never generated)
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
├─ packages/README.md ← shared packages index
├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker
@@ -238,13 +236,16 @@ User interaction
→ Zustand store (reportStore)
→ Components read store via selectors (no prop drilling)
Sheet loading
→ useSheet(speciesId) → SheetProvider (bundled: virtual:faunosteo-sheet, SHEET_BUNDLE=draft)
→ Zod-validated document + assets + migration map → buildSheetIndex()
SVG interaction
→ AnatomyCanvas fetches SVG text via loadSvg()
→ parseSvgBones() walks DOM → Bone map
→ delegated click listener → getBoneIdFromEvent()
→ if spine-zone → VertebraPicker modal
→ if data-anno-opens-detail → DetailModal (loads detail SVG)
→ else → updateObservation() in store
→ AnatomyCanvas builds the view: sanitised asset + renderAnnotationLayer() (markers from the document)
→ delegated click on [data-anno-id] → decideZoneClick() (services/zoneInteraction, pure)
→ open_view → DetailModal (same drawing, view_box crop, or the view's own asset)
→ open_vertebra_picker / open_laterality_picker → pickers → reducers (ensureZone, addSides, syncVertebrae)
→ toggle / remove_both_sides → updateObservation() in store
PDF export
→ exportReportToPdf(report, { locale })
@@ -256,9 +257,9 @@ PDF export
→ Uint8Array → browser download
PDF import
→ importReportFromPdf(bytes)
→ extractReportJson → Zod validate
→ hydrateReport() → navigate /editor
→ importReportFromPdf(bytes, migrationMap)
→ extractReportJson → readReportDocument (v3 as is, v2 migrated, else incompatible_version)
→ hydrateReport() → navigate /editor (unresolved zones/findings kept and flagged)
Runtime config
→ Docker entrypoint writes env.js (window.__APP_CONFIG__)
@@ -290,7 +291,7 @@ Database (Supabase)
- Both dicts must share the exact same key set; a key missing in one dict logs a warning in DEV
- Get the translate function in any component: `const t = useT()` then `t('common.cancel')`
- `src/state/localeStore.ts` holds current `Locale` (`'fr' | 'en'`), persisted to `localStorage` key `osteo:locale`; default: navigator-detected `fr`/`en`, or `'fr'` if no match
- Finding leaf labels (zone names shown in PDF) are resolved at export time via SVG `data-anno-name-fr` / `data-anno-name-en` attributes — not from the dict
- Zone and finding names shown in the editor and the PDF come from the sheet document (`{ fr, en }` labels) and from the report's snapshots, not from the dict
- PDF static labels (section headings, metadata) come from the dict via `getDict(locale)` in `exportReportToPdf`
### Identity strings
@@ -298,34 +299,40 @@ Database (Supabase)
- Always read from ConfigProvider via useConfig()
- src/config/env.ts is the only place with defaults
### SVG convention
- docs/ANATOMY-SVG-CONVENTION.md is the source of truth
- Every clickable element must have: data-anno-id, data-anno-name-fr, data-anno-name-en, data-anno-category
- SvgConventionError thrown on any missing required attribute
- Never rely on element id or className for click targeting — always data-anno-id
### Annotation rendering
- docs/ANNOTATION-RENDERING.md is the source of truth: the drawing carries no annotation element, the app draws
the markers from the document (`@faunosteo/anatomy/render`), with the attributes listed there
- Never rely on element id, className or a label for click targeting or behaviour — always `data-anno-id`
and the annotation's fields (`laterality`, `vertebral_region_code`, `opens_view_id`)
- Marker look (radii, opacities, strokes) is renderer style; colours are document data (`color` on categories
and annotations); no graphic redesign without prior validation
### Schemas
- domain/schema/*.ts are the data contracts — never change without bumping version
- `packages/domain/src/report/*.ts` are the report data contracts (v3 current, v2 input only); never change
without bumping the version on a breaking change (additive optional fields keep it)
- All user-provided data goes through Zod parse before hitting the store
- ReportSchema.version = 2 (v1 attachments rejected at import with a typed error); future breaking changes → version 3
- Report version 3: zones by `(annotationId, viewId)`, findings by `(findingZoneId, path)`, severities
`mild|moderate|severe`, `sheet` reference; v2 is migrated through `report-migration-map.json`
(`migrateReportV2ToV3`, never throws on content, `unresolved: true` marks what the sheet no longer holds);
v1 and unknown versions are refused with a typed error
### Stores
- No direct store mutation outside Zustand actions
- No business logic in components — delegate to store actions
- sessionStorage key: osteo:draft (auto-saved on every observation change)
- sessionStorage key: osteo:draft (auto-saved on every change, v3; a v2 draft is migrated on restore once the sheet is loaded)
- localStorage key: osteo:lastPractitioner (practitioner prefill cache)
### PDF
- A4 portrait: 595.28 × 841.89 pt
- No raw URLs in PDF output — abbreviated citations only
- JSON attachment filename must start with osteo-report
- JSON attachment filename must start with osteo-report; content = Report v3; import accepts v2 (migrated) and v3
- Fonts are StandardFonts (Helvetica/TimesRoman, WinAnsi encoding) — TTF Inter/Fraunces planned but not yet embedded. Any non-Latin-1 glyph in PDF text must use an ASCII surrogate until the TTF migration lands (e.g. `(!)` instead of `⚠`).
### Pathology DB
- All entries must pass PathologySchema.parse()
- Each entry needs ≥1 source with citation
- boneIds: [] = all zones; speciesIds: [] = all species
- Source types: manual | journal | database | web
### Anatomical sheet content
- The findings catalog, the vertebral regions and the markers are the canonical sheet document; every content
change goes through `supabase/seed/anatomical-sheets/equine/curation/changes.json` (see the sheet model section)
- The curated draft is the reference content in development (`SHEET_BUNDLE=draft`); it is not medically
validated and a production build carries no sheet unless that flag is set on purpose
### Database (Supabase)
- Platform roles (`platform_role`: owner/admin/moderator/support) are NOT professional
@@ -404,11 +411,11 @@ Database (Supabase)
- Run `pnpm typecheck && pnpm test:run` before every commit.
- Domain schema changes (domain/schema/*.ts) require updating all callers + bumping version if breaking.
- SVG convention changes require updating docs/ANATOMY-SVG-CONVENTION.md first.
- Never modify anatomy SVGs in public/species/ — they are source assets from the user.
- Pathology DB entries must be source-cited before commit; client review required for MVP batch.
- Annotation rendering changes require updating docs/ANNOTATION-RENDERING.md first.
- Never modify the legacy sources under `supabase/seed/anatomical-sheets/equine/legacy-sources/` — they are the
importer's input (the user's historical files).
- Ask before any change to importReportFromPdf or extractReportJson — these handle user data.
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation, then DecompressionStream inflation.
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation (v3, or v2 through the migration map), then DecompressionStream inflation.
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
- SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test`
on the real stack when Docker is available; regenerate types (`pnpm db:types`).
+13
View File
@@ -21,6 +21,19 @@ The host should publish only ports `22`, `80`, `443` to the internet. The
container port (`8080` by default) should stay loopback-only — the host
reverse proxy reads from it on `127.0.0.1:8080`.
### Reference sheet in the image (SHEET_BUNDLE)
The application needs an anatomical sheet to work. Until sheets are served by
Supabase (plan Step 13) the only source is the sheet bundled at build time:
| Build | Sheet in the bundle |
|---|---|
| `docker build .` / `pnpm build` (default, CI) | none: the app shows "no anatomical sheet" and refuses to create or import a report |
| `docker build --build-arg SHEET_BUNDLE=draft .` / `pnpm build:preview` | the curated equine DRAFT, medically unvalidated |
Bundling the draft is a deliberate preview decision, never the default: the
draft content is readable by anyone who can load the application (BDR-037).
### Docker resource naming
Expected change in `.env.example` (file not editable by the assistant):
+30 -31
View File
@@ -5,10 +5,11 @@ SVGs — click zones, build observations, export a self-contained PDF with the
full report JSON embedded as a native PDF attachment. Re-importing that PDF
restores the state for a follow-up.
Multi-species by design. MVP data set covers the **horse** (équin). Additional
species — dog, cat, goat, cow, pig, rabbit, donkey, sheep — drop in by adding
their SVG schematic + manifest + pathology file under `src/domain/species/`.
See [`docs/ADDING-A-SPECIES.md`](docs/ADDING-A-SPECIES.md) for the recipe.
Multi-species by design. The MVP ships the **horse** sheet: a canonical anatomical
sheet document (drawing + annotations + findings catalog, `packages/domain`)
generated and curated under `supabase/seed/anatomical-sheets/equine/`. Another
species is another sheet document, no code change.
See `docs/development/ANATOMICAL_SHEET_MODEL.md` §6 for how a sheet is produced.
Open to every praticien who wants to use it. No authentication, no backend,
no central server in v1 — the PDF is the long-term record. Phase 2 will add
@@ -19,20 +20,17 @@ contract.
## Features
- **Anatomy canvas** — inline SVG with clickable zones; hitbox+visible twin pattern; delegated click listener
- **Anatomy canvas** — inline SVG drawing with markers rendered from the sheet document (hitbox + visible twin, delegated click listener)
- **Observation builder** — group zones into clinical observations with severity and free-text notes
- **Hierarchical findings tree** — per-zone picker with breadcrumb drill-down through the expert-authored catalog (26 zones for the horse), vet-referral badges on sensitive leaves, scope-disclaimer modal once per session
- **Vertebra picker** — region tabs (C/T/L/S/Cd) with multi-select chip grid for precise vertebral notation
- **Detail popups** — click a zone (e.g. head) to open a secondary SVG with finer-grained zones
- **PDF export** — A4 portrait with rasterized anatomy SVGs (native browser `Image`/`canvas` pipeline), structured observations, and the full report JSON as a native PDF attachment
- **Detail views** — click the head trigger to open the head view (a crop of the same drawing, or a view's own asset)
- **PDF export** — A4 portrait with rasterized views, structured observations, and the full Report v3 JSON as a native PDF attachment; older v2 PDFs import through a generated migration map
- **PDF re-import** — open a previously exported PDF to restore the session for a follow-up
- **Bilingual UI** — full FR/EN interface with a one-click language switcher; default locale auto-detected from the browser, then persisted
- **Configurable identity** — site name, brand, footer, tagline all come from env vars; nothing hardcoded
- **Practitioner cache** — last-used practitioner block prefilled via localStorage
- **Pathology editor** — standalone `pathology-editor.html` tool (no build step) for visually editing the species findings JSON via SVG zone selection; exports a downloadable JSON file
- **Laterality** — left/right side selection on bilateral zones, reflected in badges and the PDF
- **SVG anatomy editor** — in-app `/svg-editor` tool to annotate anatomy SVGs
- **Welcome screen + editors page** — tabbed entry with a project SVG picker and an `/editors` listing
- **Footer branding** — global footer (copyright, "Powered by ZenQuality", partner logo), on site + PDF
---
@@ -101,9 +99,9 @@ For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy,
## Documentation
- [CLAUDE.md](CLAUDE.md) — project conventions, stack reference, architecture overview
- [docs/ANATOMY-SVG-CONVENTION.md](docs/ANATOMY-SVG-CONVENTION.md) — SVG data-* contract (source of truth)
- [docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) — guide for adding a second species post-MVP
- [docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md) — findings catalog format + authoring guide
- [docs/ANNOTATION-RENDERING.md](docs/ANNOTATION-RENDERING.md) — annotation layer contract (markers drawn from the sheet document)
- [docs/development/ANATOMICAL_SHEET_MODEL.md](docs/development/ANATOMICAL_SHEET_MODEL.md) — canonical anatomical sheet document, curation pipeline, report migration map
- [docs/development/STEP5_MIGRATION_ANALYSIS.md](docs/development/STEP5_MIGRATION_ANALYSIS.md) — how the application moved onto the canonical sheet (Report v3)
- [docs/PDF-FORMAT.md](docs/PDF-FORMAT.md) — PDF page layout and attachment contract
- [docs/development/SUPABASE.md](docs/development/SUPABASE.md) — local Supabase stack, migrations, RLS tests, generated types
- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening)
@@ -117,25 +115,26 @@ For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy,
```
faunosteo/ pnpm workspace (see docs/development/WORKSPACE.md)
├─ apps/app/ the private application (@faunosteo/app):
├─ public/species/equine/ anatomy SVGs (Horse.svg, Horse_head.svg)
├─ vite/sheet-bundle.ts Vite plugin bundling the reference sheet (SHEET_BUNDLE=draft|none)
├─ src/app/ routes + ConfigProvider
├─ src/config/ runtime env config resolution
├─ src/domain/ Zod schemas + species registry + equine data
├─ src/sheets/ SheetProvider (bundled implementation) + useSheet hook
├─ src/services/ sheet index (lookups by id) + zone interaction service (pure)
├─ src/i18n/ translation dicts (fr/en) + useT() hook
├─ src/state/ Zustand store + locale store + localStorage cache
├─ src/anatomy/ SVG parser + loader
├─ src/state/ Zustand store (Report v3) + persistence adapter + locale store
├─ src/anatomy/ drawing: sanitised asset + annotation layer → inline SVG per view
├─ src/components/ UI primitives, canvas, observation, report
├─ src/pdf/ export/import/attachment/fonts + renderers
├─ src/lib/ id, dates, assert utilities
├─ src/styles/ Tailwind v4 CSS + design tokens
├─ tests/unit/ vitest tests (apps/app/tests, incl. characterisation suite)
├─ packages/domain/ @faunosteo/domain: canonical anatomical sheet document (Zod) + integrity rules
├─ tests/unit/ vitest tests on the bundled sheet (+ frozen v2 fixtures)
├─ packages/domain/ @faunosteo/domain: canonical sheet document + report document (v3, v2 migration)
├─ packages/anatomy/ @faunosteo/anatomy: legacy importer, curation pipeline, annotation-layer renderer
├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL test harness
├─ supabase/ CLI config, SQL migrations, local seed, pgTAP tests
├─ supabase/ CLI config, SQL migrations, local seed (incl. the equine sheet), pgTAP tests
├─ docker/ entrypoint.sh + nginx.conf
├─ docs/ conventions + species guide + PDF spec
├─ index.html SPA entry point
└─ public/pathology-editor.html standalone pathology JSON editor (served as static file)
├─ docs/ conventions, sheet model, PDF spec, development plan
└─ index.html SPA entry point
```
---
@@ -146,16 +145,16 @@ v0.1.0 MVP — implementation complete.
- `pnpm typecheck` ✅
- `pnpm lint` ✅
- `pnpm test:run` ✅ — 271 tests across 39 files
- `pnpm test:run` ✅ — 310 tests across the workspace (domain, anatomy, supabase, app)
- `pnpm build` ✅
The first species data set ships with the real `Horse.svg` + `Horse_head.svg`
anatomy sources at `public/species/equine/` and a full v2.0 findings catalog
(26 zones, 792 nodes, 612 leaves, 41 vet-referral leaves) authored by the
domain expert. Adding **dog, cat, goat, cow, pig, rabbit, donkey, sheep** is
the same procedure: convention-compliant SVG + manifest + findings JSON. See
[docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) and
[docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md).
The first species ships as the equine anatomical sheet: the historical
`Horse.svg`, `Horse_head.svg` and findings catalog (26 zones, 792 nodes)
imported, then audited and curated (`supabase/seed/anatomical-sheets/equine/`,
44 traced changes, 48 references). The application bundles that curated
draft in development (`SHEET_BUNDLE=draft`); it is not medically validated and
a production build carries no sheet unless asked. Another species is another
sheet document produced the same way.
Manual QA checklist: `.claude/audits/MVP-QA.md` — walk it through `pnpm dev`
before delivery.
+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
+1 -1
View File
@@ -9,7 +9,7 @@ Planned packages and the step that creates each one:
| Package | Content | Created at |
|---|---|---|
| `@faunosteo/domain` | Zod schemas: anatomical sheet document + integrity rules (**created**, Step 4); report document, entitlement capabilities later | Step 4 (sheet model) |
| `@faunosteo/anatomy` | legacy importer (**created**, Step 4b), curation pipeline: changeset → working draft (**created**, Step 4c); renderer helpers, spine logic later | Step 4b (importer) |
| `@faunosteo/anatomy` | legacy importer (**created**, Step 4b), curation pipeline: changeset → working draft + report migration map (**created**, Steps 4c/5), pure annotation-layer renderer `@faunosteo/anatomy/render` shared with the app (**created**, Step 5) | Step 4b (importer) |
| `@faunosteo/pdf` | export / import / attachment, render helpers | Step 6 (PDF v3) |
| `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) |
| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite, sheet publish gate | **created**, Step 3 |
+4 -4
View File
@@ -127,10 +127,10 @@ describe('annotation layer on the real draft', () => {
'<svg xmlns="http://www.w3.org/2000/svg"/>',
'image/svg+xml',
)
const element = createLayerElement(
doc as never,
layer,
) as unknown as Element
const element = createLayerElement(doc as never, layer) as unknown as {
getAttribute(name: string): string | null
getElementsByTagName(tag: string): { length: number }
}
expect(element.getAttribute('data-layer')).toBe('annotations')
expect(element.getElementsByTagName('circle')).toHaveLength(18)
const text = serializeLayer(layer)