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:
1 parent
0aa8f46f5c
commit
4355055a42
1 file changed
+236
-7
+236
-7
@@ -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.
|
||||
Reference in new issue
Block a user