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 commit9cf8a66. docs/PATHOLOGIES-FORMAT.md: - "PDF surface: snapshot label is prefixed ⚠" → "(!)" in two places (after WinAnsi hotfix143fdc3). 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.
7.6 KiB
Adding a New Species
Osteo Report ships with one species (equine). Adding a new one is
mostly authoring work — anatomy SVGs and a findings JSON — backed by a
small amount of boilerplate that the project can scaffold for you.
Throughout this document, replace
<id>with the new species' kebab-case id (e.g.canine,feline,bovine).
Quick start — pnpm scaffold:species
pnpm scaffold:species
The interactive prompt asks for:
- species id (kebab-case, e.g.
canine), - French and English display labels,
- the asset folder under
public/species/(defaults to the id), - the main SVG filename,
- zero or more detail-popup SVG paths (mapped by
data-anno-opens-detailkey), - the vertebral formula (C / T / L / S / Cd).
It then writes:
src/domain/species/<id>/
index.ts ← SpeciesManifest with `export default`
vertebrae.ts ← VertebralFormula constant
pathologies.ts ← parses pathologies.json via SpeciesFindingsSchema
pathologies.json ← minimal valid catalog skeleton
public/species/<assetFolder>/ (directory created, empty)
The script refuses to clobber existing files, so it is safe to rerun.
After scaffolding, drop the anatomy SVGs into the public/species/...
folder, fill in pathologies.json, and the species shows up
automatically in the species picker — see "How auto-discovery works"
below.
How auto-discovery works
src/domain/species/registry.ts no longer hard-codes species. It uses
Vite's import.meta.glob:
const modules = import.meta.glob<{ default: SpeciesManifest }>(
'./*/index.ts',
{ eager: true },
)
Every src/domain/species/<id>/index.ts that default-exports a
SpeciesManifest is picked up at build time and registered by its
manifest.id. Duplicates are warned about and the first one wins.
What this means in practice:
- No registry edit needed. Drop a properly-structured species
folder and it appears in
AnimalForm,getSpecies(id), the editor, and the PDF exporter. - The
idmust be unique. Two folders default-exporting manifests with the sameidtriggers a console warning and the later module is ignored. - A missing default export is silent. If you forget
export default, the species is invisible. The scaffold script emits the default export for you.
Manual setup (without the script)
The scaffold script just writes the files below. If you'd rather do it
by hand, the same workflow applies — make sure your index.ts
default-exports the manifest so auto-discovery sees it.
1. Author the anatomy SVGs
All SVG assets must conform to
docs/ANATOMY-SVG-CONVENTION.md. Every
clickable element must carry:
| Attribute | Required | Notes |
|---|---|---|
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 | Must be one of the 7 valid values defined in 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. |
Drop the SVGs into:
public/species/<assetFolder>/<Main>.svg
public/species/<assetFolder>/<Main>_<detail>.svg
The public/ prefix is implicit at runtime — the manifest references
files by absolute path starting with /species/....
2. Create the species manifest
src/domain/species/<id>/index.ts:
import type { SpeciesManifest } from '@/domain/species/types'
import { CANINE_VERTEBRAL_FORMULA } from './vertebrae'
export const canine: SpeciesManifest = {
id: 'canine',
labelFr: 'Chien',
mainSvg: '/species/canine/Dog.svg',
details: {
head: '/species/canine/Dog_head.svg',
},
vertebralFormula: CANINE_VERTEBRAL_FORMULA,
findings: () => import('./pathologies'),
}
export default canine // <- required for auto-discovery
details keys must match every distinct data-anno-opens-detail
attribute used in the main SVG. There is no filename convention — the
mapping is explicit through this object.
3. Provide the vertebral formula
src/domain/species/<id>/vertebrae.ts:
import type { VertebralFormula } from '@/domain/species/types'
export const CANINE_VERTEBRAL_FORMULA: VertebralFormula = {
C: 7,
T: 13,
L: 7,
S: 3,
Cd: 20,
}
Cap Cd at a sensible maximum (caudal counts vary heavily across
individuals).
4. Provide the findings catalog
Two files:
src/domain/species/<id>/pathologies.json — authored tree of zones,
categories, sub-categories and leaves. The shape is defined by
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. 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/<id>/pathologies.ts — loader:
import {
SpeciesFindingsSchema,
type SpeciesFindings,
} from '@/domain/schema/findings'
import data from './pathologies.json'
const FINDINGS: SpeciesFindings = SpeciesFindingsSchema.parse(data)
export default FINDINGS
The Zod parse runs on first import and fails fast if the JSON violates the schema (missing labels, malformed children, empty disclaimer, etc.). That is your validation gate — there is no separate lint step to run.
Updating the findings JSON
The JSON is bundled into the app at build time, so updates flow through normal dev/deploy paths:
- In dev (
pnpm dev): edit the JSON, Vite HMR reloads the module, the editor picks up the new tree on the next interaction. A bad edit fails loudly because the Zod parse runs at module load. - In prod: rebuild and redeploy. The findings tree is statically imported and there is no backend serving JSON at runtime.
Snapshots in already-exported PDFs are unaffected — observations carry
labelFrSnapshot / labelEnSnapshot copied at selection time, so
catalog edits cannot retroactively rewrite past reports.
How findings link back to clicked SVG zones
The catalog keys observations by stable JSON zone ids (e.g.
sphenoid). SVG hitboxes carry opaque generator ids
(e.g. point-mpbymcln). The bridge is the FR/EN label parsed from
data-anno-name-fr / data-anno-name-en, matched against the JSON's
zone.name_fr / zone.name_en via the fuzzy matcher in
src/lib/zoneMatch.ts.
In practice you do not need to make the SVG ids meaningful; you just need each zone's label to match its catalog entry under normalization (lowercase + strip accents + drop non-alphanumerics) or be close enough that Levenshtein finds it.
CI gate before merging
pnpm lint
pnpm typecheck
pnpm test:run
pnpm build
All four must be green before the new species lands.