diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 28f10b9a..53a23fd2 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -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-.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. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 6e63f40f..a811fa13 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -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. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 21b78bc8..ced0ccef 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -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 `` 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. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 5f83e6e6..70048192 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -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 --- diff --git a/CHANGELOG.md b/CHANGELOG.md index 6499fafd..926907a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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). diff --git a/CLAUDE.md b/CLAUDE.md index c381b6e4..830dc2f4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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`). diff --git a/DEPLOY.md b/DEPLOY.md index 1669b53e..c971bb34 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -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): diff --git a/README.md b/README.md index 9a196ae2..008359eb 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/ANNOTATION-RENDERING.md b/docs/ANNOTATION-RENDERING.md new file mode 100644 index 00000000..0a7f8f90 --- /dev/null +++ b/docs/ANNOTATION-RENDERING.md @@ -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. diff --git a/docs/PATHOLOGIES-FORMAT.md b/docs/PATHOLOGIES-FORMAT.md index cd8304ef..f9ffd3c9 100644 --- a/docs/PATHOLOGIES-FORMAT.md +++ b/docs/PATHOLOGIES-FORMAT.md @@ -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. diff --git a/docs/PDF-FORMAT.md b/docs/PDF-FORMAT.md index 67d06a42..02827d7d 100644 --- a/docs/PDF-FORMAT.md +++ b/docs/PDF-FORMAT.md @@ -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)`. diff --git a/docs/development/ANATOMICAL_SHEET_MODEL.md b/docs/development/ANATOMICAL_SHEET_MODEL.md index b6cb829d..cdf852b0 100644 --- a/docs/development/ANATOMICAL_SHEET_MODEL.md +++ b/docs/development/ANATOMICAL_SHEET_MODEL.md @@ -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 diff --git a/docs/development/CHARACTERIZATION_REPORT.md b/docs/development/CHARACTERIZATION_REPORT.md index a58353c9..18a3c030 100644 --- a/docs/development/CHARACTERIZATION_REPORT.md +++ b/docs/development/CHARACTERIZATION_REPORT.md @@ -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), diff --git a/docs/development/IMPLEMENTATION_PLAN.md b/docs/development/IMPLEMENTATION_PLAN.md index 13595b8d..99161a0f 100644 --- a/docs/development/IMPLEMENTATION_PLAN.md +++ b/docs/development/IMPLEMENTATION_PLAN.md @@ -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 diff --git a/docs/development/MIGRATION_STRATEGY.md b/docs/development/MIGRATION_STRATEGY.md index 6ed503ec..ce0ca10a 100644 --- a/docs/development/MIGRATION_STRATEGY.md +++ b/docs/development/MIGRATION_STRATEGY.md @@ -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. diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index e0073188..e78c3a6e 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -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) diff --git a/docs/development/WORKSPACE.md b/docs/development/WORKSPACE.md index 7a17f3f3..5ab8f70e 100644 --- a/docs/development/WORKSPACE.md +++ b/docs/development/WORKSPACE.md @@ -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 diff --git a/packages/README.md b/packages/README.md index 3a428b26..96f5fd0d 100644 --- a/packages/README.md +++ b/packages/README.md @@ -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 | diff --git a/packages/anatomy/tests/render.layer.test.ts b/packages/anatomy/tests/render.layer.test.ts index b3b91d73..1dfb4bf9 100644 --- a/packages/anatomy/tests/render.layer.test.ts +++ b/packages/anatomy/tests/render.layer.test.ts @@ -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)