Registry
--------
src/domain/species/registry.ts previously hard-coded the species list,
which meant adding a new animal forced an edit in two places. The
registry now uses Vite's `import.meta.glob('./*/index.ts', { eager: true })`
and registers every manifest that default-exports a SpeciesManifest.
Duplicate ids log a warn and the first wins. Existing named imports
keep working — equine/index.ts adds `export default equine` next to the
named export.
The species dropdown is also now sorted alphabetically by labelFr (FR
locale) instead of insertion order, so two species don't shuffle
position based on glob ordering.
Scaffold script
---------------
`pnpm scaffold:species` (scripts/scaffold-species.mjs) is an
interactive Node ESM prompt that asks for the id, FR/EN labels, asset
folder, main SVG filename, detail SVG mappings, and the vertebral
formula, then writes:
src/domain/species/<id>/index.ts (with `export default`)
src/domain/species/<id>/vertebrae.ts
src/domain/species/<id>/pathologies.ts (Zod-parses the JSON)
src/domain/species/<id>/pathologies.json (minimal valid skeleton)
public/species/<assetFolder>/ (directory placeholder)
The script refuses to overwrite existing files, so it's safe to rerun
after typos. SVG assets are not generated — drop them in the public
folder yourself.
Findings JSON updates
---------------------
No runtime hot-reload mechanism is needed in dev: `pathologies.ts`
imports `pathologies.json` and runs `SpeciesFindingsSchema.parse(data)`
at module load, so a JSON edit triggers Vite HMR + an immediate Zod
validation pass. In prod, rebuild and redeploy.
Docs
----
docs/ADDING-A-SPECIES.md rewritten around the new flow: quick start via
the scaffold script first, manual instructions second, and removed the
stale references to the flat `Pathology[]` model and the no-longer-
required registry edit step.
Co-Authored-By: Claude <noreply@anthropic.com>
7.2 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 | Free-form string used for grouping (e.g. articulations, cadrans-du-cr-ne). |
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. 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.