From 4355055a42f8b00633a198e78f10349fd47f4d94 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Mon, 18 May 2026 22:02:29 +0200 Subject: [PATCH] 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//, 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) --- docs/ADDING-A-SPECIES.md | 243 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 236 insertions(+), 7 deletions(-) diff --git a/docs/ADDING-A-SPECIES.md b/docs/ADDING-A-SPECIES.md index 2c49f7bf..faca1818 100644 --- a/docs/ADDING-A-SPECIES.md +++ b/docs/ADDING-A-SPECIES.md @@ -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//` 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 `` 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//
.svg # main side-view body schema +public/species//
_.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//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 = { + [equine.id]: equine, + [canine.id]: canine, +} +``` + +The species will now appear in the species `