Files
faunosteo/docs/ADDING-A-SPECIES.md
T
Bastien ChanotandClaude Opus 4.7 4355055a42 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>
2026-05-18 22:02:29 +02:00

7.5 KiB
Raw Blame History

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-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:

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:

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:

  • 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:

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.