Files
faunosteo/docs/ADDING-A-SPECIES.md
T
Bastien ChanotandClaude Opus 4.7 1109e33383 refactor(anatomy): rename SVG data attrs (bone → anno) per new convention
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>
2026-05-19 03:10:06 +02:00

240 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.