From 8385b49bbe654b117b951cd7de55a5d9385ff065 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Thu, 21 May 2026 04:13:13 +0200 Subject: [PATCH] docs: sync drift after catalog v2.0 + i18n + WinAnsi hotfix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit doc-syncer audit applied 10 AUTO patches and 1 HUMAN reword (#5) across the doc set. README.md: - Test count "7 tests pass on skeleton" / "88 tests across 23 files" → "155 tests" / "155 tests across 29 files". - Reword "Observation builder" bullet + add hierarchical findings tree + browser-detected locale bullets (HUMAN #5). - Status paragraph: pathology DB "intentionally empty" → full 26-zone v2.0 catalog (792 nodes, 612 leaves, 41 vet leaves). - Documentation section: add PATHOLOGIES-FORMAT.md link; tidy the DEPLOY.md mention (DEPLOY.md itself comes in the next commit). CLAUDE.md: - Architecture block: "embedFonts (Inter body + Fraunces heading)" → reality (Helvetica + TimesRoman / WinAnsi StandardFonts; TTF Inter/Fraunces planned). - PDF convention: "Fonts are TTF" → "Fonts are StandardFonts (Helvetica/TimesRoman, WinAnsi)" with the ASCII-surrogate caveat. - Folder map: add src/anatomy/labels.ts, include zoneMatch.ts in src/lib/{...}.ts. - i18n: locale default "fr" → "navigator-detected fr/en, or 'fr' if no match" to match commit 9cf8a66. docs/PATHOLOGIES-FORMAT.md: - "PDF surface: snapshot label is prefixed ⚠" → "(!)" in two places (after WinAnsi hotfix 143fdc3). Picker ⚠ statement kept — browser renders U+26A0 natively. docs/ADDING-A-SPECIES.md: - data-anno-category: "Free-form" → enum of 7 valid values per ANATOMY-SVG-CONVENTION.md; parser throws SvgConventionError on unknown values. - Section 4 (findings catalog): cross-link to docs/PATHOLOGIES-FORMAT.md so authors find the v2.0 contract. --- CLAUDE.md | 11 ++++++----- README.md | 31 ++++++++++++++++--------------- docs/ADDING-A-SPECIES.md | 11 +++++++---- docs/PATHOLOGIES-FORMAT.md | 10 ++++++---- 4 files changed, 35 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2d5e4840..745f88cf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -138,7 +138,8 @@ osteo/ │ ├─ anatomy/ │ │ ├─ types.ts ← Bone, BoneCategory, BoneState │ │ ├─ svgConvention.ts ← parseSvgBones() -│ │ └─ svgLoader.ts ← loadSvg(), svgToPngDataUrl() +│ │ ├─ svgLoader.ts ← loadSvg(), svgToPngDataUrl() +│ │ └─ labels.ts ← boneLabel(bone, locale, fallback) │ ├─ components/ │ │ ├─ ui/{Button,Card,Dialog,Input,Label,Select,Textarea,Badge,Chip}.tsx │ │ ├─ canvas/{AnatomyCanvas,DetailModal}.tsx @@ -151,7 +152,7 @@ osteo/ │ ├─ pdf/ │ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts │ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng}.ts -│ ├─ lib/{dates,id,assert}.ts +│ ├─ lib/{dates,id,assert,zoneMatch}.ts │ ├─ styles/{index,tokens}.css ← Tailwind v4 CSS-first │ └─ main.tsx ├─ tests/ @@ -200,7 +201,7 @@ SVG interaction PDF export → exportReportToPdf(report, { locale }) → pdf-lib PDFDocument - → embedFonts (Inter body + Fraunces heading) + → embedFonts (Helvetica body + TimesRoman heading — WinAnsi StandardFonts; TTF Inter/Fraunces planned) → for each observation: addObservationPage (rasterize SVG → PNG) → addConclusionPage → attachReportJson (native EmbeddedFiles) @@ -232,7 +233,7 @@ Runtime config - Key convention: `.` — e.g. `common.cancel`, `home.new_report.title`, `pdf.subject` - 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 `'fr'` +- `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 - PDF static labels (section headings, metadata) come from the dict via `getDict(locale)` in `exportReportToPdf` @@ -262,7 +263,7 @@ Runtime config - A4 portrait: 595.28 × 841.89 pt - No raw URLs in PDF output — abbreviated citations only - JSON attachment filename must start with osteo-report -- Fonts are TTF (pdf-lib limitation — no woff2) +- 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() diff --git a/README.md b/README.md index 63270db6..e84eeacd 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,13 @@ contract. ## Features - **Anatomy canvas** — inline SVG with clickable zones; hitbox+visible twin pattern; delegated click listener -- **Observation builder** — group zones into clinical observations with pathology selection, severity, and free-text notes +- **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 (canvg @ 2×), structured observations, and the full report JSON as a native PDF attachment - **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; locale persisted across sessions +- **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 @@ -75,7 +76,7 @@ docker compose up --build ```bash pnpm typecheck # TypeScript strict, no emit pnpm lint # ESLint 9 flat config, 0 warnings -pnpm test:run # vitest run (7 tests pass on skeleton) +pnpm test:run # vitest run (155 tests) pnpm build # tsc + vite build → dist/ ``` @@ -89,7 +90,7 @@ docker build -t osteo-report . # multi-stage Docker image docker compose up --build # run with env_file: .env ``` -For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, backups) — see [DEPLOY.md](DEPLOY.md) (to be written post-scaffold). +For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, backups, hardening) — see [DEPLOY.md](DEPLOY.md). --- @@ -98,7 +99,10 @@ For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy, - [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/PDF-FORMAT.md](docs/PDF-FORMAT.md) — PDF page layout and attachment contract +- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening) +- [CHANGELOG.md](CHANGELOG.md) — versioned release notes - [.claude/tasks/TODO.md](.claude/tasks/TODO.md) — implementation roadmap --- @@ -131,19 +135,16 @@ v1.0 MVP — implementation complete. - `pnpm typecheck` ✅ - `pnpm lint` ✅ -- `pnpm test:run` ✅ — 88 tests across 23 files -- `pnpm build` ✅ — 979 kB JS (349 kB gzip), 20 kB CSS +- `pnpm test:run` ✅ — 155 tests across 29 files +- `pnpm build` ✅ The first species data set ships with the real `Horse.svg` + `Horse_head.svg` -anatomy sources at `public/species/equine/`. Adding **dog, cat, goat, cow, -pig, rabbit, donkey, sheep** is the same procedure: convention-compliant SVG + -manifest + pathology file. See `docs/ADDING-A-SPECIES.md`. - -The pathology reference DB is intentionally empty in v1; the praticien adds -entries via the free-text input. Source-cited DB authoring is deferred to -v1.1 once the multi-praticien account architecture is decided (see -`docs/superpowers/specs/2026-05-18-osteo-report-mvp-design.md` -§Prerequisites/REMAINING). +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). Manual QA checklist: `.claude/audits/MVP-QA.md` — walk it through `pnpm dev` before delivery. diff --git a/docs/ADDING-A-SPECIES.md b/docs/ADDING-A-SPECIES.md index 86cc149d..4730f2c6 100644 --- a/docs/ADDING-A-SPECIES.md +++ b/docs/ADDING-A-SPECIES.md @@ -91,7 +91,7 @@ clickable element must carry: | `data-anno-id` | yes | Stable identifier, unique within the SVG. The renderer treats it as opaque. | | `data-anno-name-fr` | yes | French anatomical label. | | `data-anno-name-en` | yes | English anatomical label. | -| `data-anno-category` | yes | Free-form string used for grouping (e.g. `articulations`, `cadrans-du-cr-ne`). | +| `data-anno-category` | yes | Must be one of the 7 valid values defined in [`ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md) (`articulation`, `charniere`, `spine-zone`, `os`, `os-overlay`, `head`, `cadran-crane`). Parser throws `SvgConventionError` on unknown values. | | `data-anno-opens-detail` | no | Key of a detail popup SVG. Must match a key in the manifest's `details` map. | | `data-anno-special` | no | Behavior hint. `vertebral-precision` opens the VertebraPicker on click. | @@ -156,9 +156,12 @@ Two files: `src/domain/species//pathologies.json` — authored tree of zones, categories, sub-categories and leaves. The shape is defined by -`src/domain/schema/findings.ts`. The scaffold script ships a minimal -skeleton; populate the `zones` map by mirroring the equine reference at -`src/domain/species/equine/pathologies.json`. +`src/domain/schema/findings.ts`, and the full authoring contract +(structural rules, taxonomy patterns, v2.0 vet-referral policy, +changelog) lives in +[`docs/PATHOLOGIES-FORMAT.md`](./PATHOLOGIES-FORMAT.md). The scaffold +script ships a minimal skeleton; populate the `zones` map by mirroring +the equine reference at `src/domain/species/equine/pathologies.json`. `src/domain/species//pathologies.ts` — loader: diff --git a/docs/PATHOLOGIES-FORMAT.md b/docs/PATHOLOGIES-FORMAT.md index 8c0620d6..cd8304ef 100644 --- a/docs/PATHOLOGIES-FORMAT.md +++ b/docs/PATHOLOGIES-FORMAT.md @@ -217,9 +217,11 @@ v2.0 purge). All in-tree consumers (`FindingsTreePicker`, PDF `observationPage`) already key off the boolean. Picker surface: a ⚠ badge is shown next to vet-flagged leaves. PDF -surface: the snapshot label is prefixed `⚠` in the -`CONSTATS — ` section. If a `description_fr` is also present, -it is rendered as an additional context line below the children list. +surface: the snapshot label is prefixed `(!)` in the +`CONSTATS — ` section (the picker `⚠` cannot be rendered until +the PDF font path migrates from WinAnsi StandardFonts to TTF). If a +`description_fr` is also present, it is rendered as an additional +context line below the children list. --- @@ -346,7 +348,7 @@ required to re-render an existing report. In the PDF, findings are grouped by `zoneId` (one `CONSTATS — ` section per zone) followed by a single `CONSTATS LIBRES` section listing the free-text additions. Vet-referral -leaves are prefixed with ⚠ in the rendered list. +leaves are prefixed with `(!)` in the rendered list. ---