Files
faunosteo/docs/ADDING-A-SPECIES.md
T
Bastien ChanotandClaude 70b7f20f6f feat(species): auto-discover species manifests + scaffold script
Registry
--------
src/domain/species/registry.ts previously hard-coded the species list,
which meant adding a new animal forced an edit in two places. The
registry now uses Vite's `import.meta.glob('./*/index.ts', { eager: true })`
and registers every manifest that default-exports a SpeciesManifest.
Duplicate ids log a warn and the first wins. Existing named imports
keep working — equine/index.ts adds `export default equine` next to the
named export.

The species dropdown is also now sorted alphabetically by labelFr (FR
locale) instead of insertion order, so two species don't shuffle
position based on glob ordering.

Scaffold script
---------------
`pnpm scaffold:species` (scripts/scaffold-species.mjs) is an
interactive Node ESM prompt that asks for the id, FR/EN labels, asset
folder, main SVG filename, detail SVG mappings, and the vertebral
formula, then writes:

  src/domain/species/<id>/index.ts        (with `export default`)
  src/domain/species/<id>/vertebrae.ts
  src/domain/species/<id>/pathologies.ts  (Zod-parses the JSON)
  src/domain/species/<id>/pathologies.json (minimal valid skeleton)
  public/species/<assetFolder>/           (directory placeholder)

The script refuses to overwrite existing files, so it's safe to rerun
after typos. SVG assets are not generated — drop them in the public
folder yourself.

Findings JSON updates
---------------------
No runtime hot-reload mechanism is needed in dev: `pathologies.ts`
imports `pathologies.json` and runs `SpeciesFindingsSchema.parse(data)`
at module load, so a JSON edit triggers Vite HMR + an immediate Zod
validation pass. In prod, rebuild and redeploy.

Docs
----
docs/ADDING-A-SPECIES.md rewritten around the new flow: quick start via
the scaffold script first, manual instructions second, and removed the
stale references to the flat `Pathology[]` model and the no-longer-
required registry edit step.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-05-20 05:46:33 +02:00

7.2 KiB

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 <id> with the new species' kebab-case id (e.g. canine, feline, bovine).


Quick start — pnpm scaffold:species

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/<id>/
  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/<assetFolder>/   (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:

const modules = import.meta.glob<{ default: SpeciesManifest }>(
  './*/index.ts',
  { eager: true },
)

Every src/domain/species/<id>/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. 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/<assetFolder>/<Main>.svg
public/species/<assetFolder>/<Main>_<detail>.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/<id>/index.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/<id>/vertebrae.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/<id>/pathologies.json — authored tree of zones, categories, sub-categories and leaves. The shape is defined by src/domain/schema/findings.ts. 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/<id>/pathologies.ts — loader:

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.


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

pnpm lint
pnpm typecheck
pnpm test:run
pnpm build

All four must be green before the new species lands.