diff --git a/docs/ADDING-A-SPECIES.md b/docs/ADDING-A-SPECIES.md index b2885229..86cc149d 100644 --- a/docs/ADDING-A-SPECIES.md +++ b/docs/ADDING-A-SPECIES.md @@ -1,61 +1,113 @@ # 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. +Osteo Report ships with one species (`equine`). Adding a new one is +mostly authoring work — anatomy SVGs and a findings JSON — backed by a +small amount of boilerplate that the project can scaffold for you. -Throughout this document, replace `` with the new species' kebab-case id -(e.g. `canine`, `feline`, `bovine`). +> Throughout this document, replace `` with the new species' +> kebab-case id (e.g. `canine`, `feline`, `bovine`). --- -## 1. Author the anatomy SVGs +## Quick start — `pnpm scaffold:species` -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//
.svg # main side-view body schema -public/species//
_.svg # one detail SVG per opens-detail key +```bash +pnpm scaffold:species ``` -For example, for a dog with a single head detail popup: +The interactive prompt asks for: + +- species id (kebab-case, e.g. `canine`), +- French and English display labels, +- the asset folder under `public/species/` (defaults to the id), +- the main SVG filename, +- zero or more detail-popup SVG paths (mapped by `data-anno-opens-detail` key), +- the vertebral formula (C / T / L / S / Cd). + +It then writes: ``` -public/species/canine/Dog.svg -public/species/canine/Dog_head.svg +src/domain/species// + index.ts ← SpeciesManifest with `export default` + vertebrae.ts ← VertebralFormula constant + pathologies.ts ← parses pathologies.json via SpeciesFindingsSchema + pathologies.json ← minimal valid catalog skeleton +public/species// (directory created, empty) ``` -The `public/` prefix is implicit at runtime — the manifest references files -by absolute path starting with `/species/...`. +The script refuses to clobber existing files, so it is safe to rerun. -## 3. Create the species manifest +After scaffolding, drop the anatomy SVGs into the `public/species/...` +folder, fill in `pathologies.json`, and the species shows up +automatically in the species picker — see "How auto-discovery works" +below. -Create `src/domain/species//index.ts` exporting a `SpeciesManifest`: +--- + +## How auto-discovery works + +`src/domain/species/registry.ts` no longer hard-codes species. It uses +Vite's `import.meta.glob`: + +```ts +const modules = import.meta.glob<{ default: SpeciesManifest }>( + './*/index.ts', + { eager: true }, +) +``` + +Every `src/domain/species//index.ts` that **default-exports** a +`SpeciesManifest` is picked up at build time and registered by its +`manifest.id`. Duplicates are warned about and the first one wins. + +What this means in practice: + +- **No registry edit needed.** Drop a properly-structured species + folder and it appears in `AnimalForm`, `getSpecies(id)`, the editor, + and the PDF exporter. +- **The `id` must be unique.** Two folders default-exporting manifests + with the same `id` triggers a console warning and the later module + is ignored. +- **A missing default export is silent.** If you forget + `export default`, the species is invisible. The scaffold script + emits the default export for you. + +--- + +## Manual setup (without the script) + +The scaffold script just writes the files below. If you'd rather do it +by hand, the same workflow applies — make sure your `index.ts` +default-exports the manifest so auto-discovery sees it. + +### 1. Author the anatomy SVGs + +All SVG assets must conform to +[`docs/ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md). Every +clickable element must carry: + +| Attribute | Required | Notes | +| -------------------------- | -------- | -------------------------------------------------------------------------------------- | +| `data-anno-id` | yes | Stable identifier, unique within the SVG. The renderer treats it as opaque. | +| `data-anno-name-fr` | yes | French anatomical label. | +| `data-anno-name-en` | yes | English anatomical label. | +| `data-anno-category` | yes | Free-form string used for grouping (e.g. `articulations`, `cadrans-du-cr-ne`). | +| `data-anno-opens-detail` | no | Key of a detail popup SVG. Must match a key in the manifest's `details` map. | +| `data-anno-special` | no | Behavior hint. `vertebral-precision` opens the VertebraPicker on click. | + +Drop the SVGs into: + +``` +public/species//
.svg +public/species//
_.svg +``` + +The `public/` prefix is implicit at runtime — the manifest references +files by absolute path starting with `/species/...`. + +### 2. Create the species manifest + +`src/domain/species//index.ts`: ```ts import type { SpeciesManifest } from '@/domain/species/types' @@ -69,50 +121,23 @@ export const canine: SpeciesManifest = { head: '/species/canine/Dog_head.svg', }, vertebralFormula: CANINE_VERTEBRAL_FORMULA, - pathologies: () => import('./pathologies'), + findings: () => import('./pathologies'), } + +export default canine // <- required for auto-discovery ``` -Required fields (see `src/domain/species/types.ts`): +`details` keys must match every distinct `data-anno-opens-detail` +attribute used in the main SVG. There is no filename convention — the +mapping is explicit through this object. -- `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). +### 3. Provide the vertebral formula -## 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 `