docs(species): document how to add a new species end-to-end

Replace the placeholder with a full 7-step walkthrough: SVG convention,
file placement under public/, species manifest at src/domain/species/<id>/,
registry wiring, vertebral formula, pathology seed (empty allowed in v1),
and the two mirror tests (registry + real-SVG parse + pathologies schema).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bastien ChanotandClaude Opus 4.7 committed 2026-05-18 22:02:29 +02:00
1 parent 0aa8f46f5c
commit 4355055a42
1 file changed
+236 -7
+236 -7
View File
@@ -1,10 +1,239 @@
# Adding a New Species
Placeholder — to be written when adding the second species post-MVP.
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.
Steps will cover:
1. Preparing anatomy SVGs per docs/ANATOMY-SVG-CONVENTION.md
2. Creating `src/domain/species/<id>/` folder
3. Defining vertebralFormula + pathology DB
4. Registering in `src/domain/species/registry.ts`
5. Testing with convention parser + pathology integrity tests
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`](./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-bone-id` | yes | Stable kebab-case id, unique within the SVG. |
| `data-bone-fr` | yes | French anatomical label (used in tooltips and PDF text). |
| `data-bone-en` | yes | English anatomical label (used as fallback and a11y hint). |
| `data-category` | yes | One of: `articulation`, `charniere`, `spine-zone`, `os`, `os-overlay`, `head`, `cadran-crane`. |
| `data-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`:
```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,
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 distinct
`data-opens-detail` attribute 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:
```ts
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`:
```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`:
```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:
```ts
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:
- `parseSvgBones` does not throw and returns a non-empty map.
- Every required `data-category` you used is present at least once
(especially the `spine-zone` count, the `head` zone with `opensDetail`,
and any `charniere` hinges).
- Detail SVGs (one test per detail id) parse cleanly and contain the
expected `cadran-crane` zones.
Pattern:
```ts
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.