User updated the clickable-zone convention in the source SVGs:
data-bone-id → data-anno-id
data-bone-fr → data-anno-name-fr
data-bone-en → data-anno-name-en
data-category → data-anno-category
data-opens-detail → data-anno-opens-detail
Bulk-renamed across:
- public/species/equine/Horse.svg + Horse_head.svg (86 anno-attrs each)
- src/anatomy/svgConvention.ts (parser + getBoneIdFromEvent)
- src/anatomy/types.ts (doc strings)
- src/components/canvas/AnatomyCanvas.tsx (querySelector + delegated click)
- src/styles/index.css (`[data-bone-id]` selectors → `[data-anno-id]`)
- src/domain/species/types.ts + schema/observation.ts (doc strings)
- docs/{ANATOMY-SVG-CONVENTION,ADDING-A-SPECIES,superpowers/specs,plans}.md
- CLAUDE.md + .claude/{memory/learnings,tasks/TODO}.md
- tests/unit/{anatomy.svgConvention,anatomy.svgLoader,components.AnatomyCanvas}.test.tsx
Internal TS type names and field names (Bone, boneId, parseSvgBones,
getBoneIdFromEvent) are kept intentionally — they're the application's
logical shape and the persisted JSON contract. ObservationZone.boneId is
the identifier seen in already-exported PDFs; renaming it would break
re-import of those PDFs. Only the SVG-side attribute names change.
90/90 tests pass, lint clean, build clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
7.6 KiB
Adding a New Species
This guide walks through every step required to add a new species (e.g. dog,
cat, bovine) to Osteo Report. The reference implementation is equine —
mirror its structure when adding a new species.
Throughout this document, replace <id> with the new species' kebab-case id
(e.g. canine, feline, bovine).
1. Author the anatomy SVGs
All SVG assets must conform to the conventions in
docs/ANATOMY-SVG-CONVENTION.md. The parser
in src/anatomy/svgConvention.ts reads the same attributes, so any drift
breaks the editor canvas.
Every clickable zone element must carry these data attributes:
| Attribute | Required | Notes |
|---|---|---|
data-anno-id |
yes | Stable kebab-case id, unique within the SVG. |
data-anno-name-fr |
yes | French anatomical label (used in tooltips and PDF text). |
data-anno-name-en |
yes | English anatomical label (used as fallback and a11y hint). |
data-anno-category |
yes | One of: articulation, charniere, spine-zone, os, os-overlay, head, cadran-crane. |
data-anno-opens-detail |
no | Id of a detail popup SVG to open when the zone is clicked. The id must match a key in the species manifest's details map. |
Reuse the equine SVG patterns:
- Hitbox + visible twin — used for
articulation,charniere,os-overlay,head. - Single visible element — used for
spine-zone,os,cadran-crane.
See public/species/equine/Horse.svg and public/species/equine/Horse_head.svg
for fully worked examples.
2. Drop the SVGs into public/
Put the assets at:
public/species/<id>/<Main>.svg # main side-view body schema
public/species/<id>/<Main>_<detail>.svg # one detail SVG per opens-detail key
For example, for a dog with a single head detail popup:
public/species/canine/Dog.svg
public/species/canine/Dog_head.svg
The public/ prefix is implicit at runtime — the manifest references files
by absolute path starting with /species/....
3. Create the species manifest
Create src/domain/species/<id>/index.ts exporting a SpeciesManifest:
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,
pathologies: () => import('./pathologies'),
}
Required fields (see src/domain/species/types.ts):
id— must match the folder name and the registry key.labelFr— French display name shown in the species picker.mainSvg— absolute path to the main anatomy SVG.details— map of detail id → SVG path. Keys must match every distinctdata-anno-opens-detailattribute used in the main SVG.vertebralFormula— segment counts for the VertebraPicker (see step 5).pathologies— lazy import returning{ default: Pathology[] }(step 6).
4. Register the manifest
Edit src/domain/species/registry.ts to add the new manifest:
import type { SpeciesManifest } from './types'
import { equine } from './equine'
import { canine } from './canine'
const SPECIES_REGISTRY: Record<string, SpeciesManifest> = {
[equine.id]: equine,
[canine.id]: canine,
}
The species will now appear in the species <Select> of AnimalForm,
and getSpecies(id) will resolve it everywhere it is consumed (editor,
PDF export, anatomy canvas).
5. Provide a vertebral formula
Create src/domain/species/<id>/vertebrae.ts:
import type { VertebralFormula } from '@/domain/species/types'
/**
* Vertebral formula for the dog (Canis lupus familiaris).
* Cd count capped at 20 for the picker — actual count varies 6–23.
*/
export const CANINE_VERTEBRAL_FORMULA: VertebralFormula = {
C: 7,
T: 13,
L: 7,
S: 3,
Cd: 20,
}
The keys map to the cervical, thoracic, lumbar, sacral, and caudal counts
the VertebraPicker will offer when the practitioner clicks a spine-zone
on the main SVG. Cap Cd at a reasonable maximum for picker usability
when the real count varies between individuals.
Look up the reference counts in a veterinary anatomy textbook (König & Liebich for dogs/cats, Dyce/Sack/Wensing for general comparative anatomy).
6. Provide a pathologies seed file
Create src/domain/species/<id>/pathologies.ts:
import type { Pathology } from '@/domain/schema/pathology'
/**
* Canine pathology database.
* Per v1 contract, an empty array is acceptable — the practitioner can
* fall back to free-text pathology input until this is populated.
*/
const CANINE_PATHOLOGIES: Pathology[] = []
export default CANINE_PATHOLOGIES
Each entry, when populated, must pass PathologySchema.parse() and have
at least one sources entry citing a peer-reviewed reference. See
src/domain/schema/pathology.ts for the full schema.
Empty arrays are allowed for v1 — the editor will simply show the free-text pathology input only, exactly like equine ships today.
7. Add the two tests
Mirror the equine reference tests:
7a. Registry test
Add to tests/unit/species.registry.test.ts (or create
tests/unit/species.<id>Registry.test.ts if you prefer one file per
species). Pattern:
it('returns the canine manifest', () => {
const c = getSpecies('canine')
expect(c).toBeDefined()
expect(c?.labelFr).toBe('Chien')
expect(c?.mainSvg).toBe('/species/canine/Dog.svg')
expect(c?.details.head).toBe('/species/canine/Dog_head.svg')
expect(c?.vertebralFormula).toEqual({ C: 7, T: 13, L: 7, S: 3, Cd: 20 })
})
7b. Real-SVG parse test
Mirror tests/unit/anatomy.horse.test.ts. Create
tests/unit/anatomy.<id>.test.ts that loads the real SVG from
public/species/<id>/ and asserts:
parseSvgBonesdoes not throw and returns a non-empty map.- Every required
data-anno-categoryyou used is present at least once (especially thespine-zonecount, theheadzone withopensDetail, and anycharnierehinges). - Detail SVGs (one test per detail id) parse cleanly and contain the
expected
cadran-cranezones.
Pattern:
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { dirname, resolve } from 'node:path'
import { parseSvgBones } from '@/anatomy/svgConvention'
const HERE = dirname(fileURLToPath(import.meta.url))
const DOG_PATH = resolve(HERE, '../../public/species/canine/Dog.svg')
function loadSvg(path: string): SVGSVGElement {
const raw = readFileSync(path, 'utf8')
return new DOMParser()
.parseFromString(raw, 'image/svg+xml')
.documentElement as unknown as SVGSVGElement
}
describe('real Dog.svg', () => {
const map = parseSvgBones(loadSvg(DOG_PATH))
it('parses without throwing', () => {
expect(map.size).toBeGreaterThan(10)
})
it('contains all 5 spine-zone bones', () => {
const spine = [...map.values()].filter((b) => b.category === 'spine-zone')
expect(spine.length).toBe(5)
})
})
Also add a tests/unit/species.<id>Pathologies.test.ts that mirrors
tests/unit/species.equinePathologies.test.ts — even if the array is empty,
the schema parse loop and the speciesIds.includes('<id>') assertion become
guardrails for future contributors.
CI gate before merging
pnpm lint
pnpm typecheck
pnpm test:run
pnpm build
All four must be green before the new species lands.