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>
240 lines
7.6 KiB
Markdown
240 lines
7.6 KiB
Markdown
# 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`](./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`:
|
||
|
||
```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-anno-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-anno-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.
|