# Adding a New Species Zoosteo 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`). --- ## Quick start — `pnpm scaffold:species` ```bash pnpm scaffold:species ``` 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: ``` 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 script refuses to clobber existing files, so it is safe to rerun. 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. --- ## 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 | Must be one of the 7 valid values defined in [`ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md) (`articulation`, `charniere`, `spine-zone`, `os`, `os-overlay`, `head`, `cadran-crane`). Parser throws `SvgConventionError` on unknown values. | | `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' 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, findings: () => import('./pathologies'), } export default canine // <- required for auto-discovery ``` `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. ### 3. Provide the vertebral formula `src/domain/species//vertebrae.ts`: ```ts import type { VertebralFormula } from '@/domain/species/types' export const CANINE_VERTEBRAL_FORMULA: VertebralFormula = { C: 7, T: 13, L: 7, S: 3, Cd: 20, } ``` Cap `Cd` at a sensible maximum (caudal counts vary heavily across individuals). ### 4. Provide the findings catalog Two files: `src/domain/species//pathologies.json` — authored tree of zones, categories, sub-categories and leaves. The shape is defined by `src/domain/schema/findings.ts`, and the full authoring contract (structural rules, taxonomy patterns, v2.0 vet-referral policy, changelog) lives in [`docs/PATHOLOGIES-FORMAT.md`](./PATHOLOGIES-FORMAT.md). The scaffold script ships a minimal skeleton; populate the `zones` map by mirroring the equine reference at `src/domain/species/equine/pathologies.json`. `src/domain/species//pathologies.ts` — loader: ```ts import { SpeciesFindingsSchema, type SpeciesFindings, } from '@/domain/schema/findings' import data from './pathologies.json' const FINDINGS: SpeciesFindings = SpeciesFindingsSchema.parse(data) export default FINDINGS ``` The Zod parse runs on first import and **fails fast** if the JSON violates the schema (missing labels, malformed children, empty disclaimer, etc.). That is your validation gate — there is no separate lint step to run. --- ## Updating the findings JSON The JSON is bundled into the app at build time, so updates flow through normal dev/deploy paths: - **In dev (`pnpm dev`)**: edit the JSON, Vite HMR reloads the module, the editor picks up the new tree on the next interaction. A bad edit fails loudly because the Zod parse runs at module load. - **In prod**: rebuild and redeploy. The findings tree is statically imported and there is no backend serving JSON at runtime. Snapshots in already-exported PDFs are unaffected — observations carry `labelFrSnapshot` / `labelEnSnapshot` copied at selection time, so catalog edits cannot retroactively rewrite past reports. --- ## How findings link back to clicked SVG zones The catalog keys observations by stable JSON zone ids (e.g. `sphenoid`). SVG hitboxes carry opaque generator ids (e.g. `point-mpbymcln`). The bridge is the **FR/EN label** parsed from `data-anno-name-fr` / `data-anno-name-en`, matched against the JSON's `zone.name_fr` / `zone.name_en` via the fuzzy matcher in `src/lib/zoneMatch.ts`. In practice you do not need to make the SVG ids meaningful; you just need each zone's label to match its catalog entry under normalization (lowercase + strip accents + drop non-alphanumerics) or be close enough that Levenshtein finds it. --- ## CI gate before merging ```bash pnpm lint pnpm typecheck pnpm test:run pnpm build ``` All four must be green before the new species lands.