Brand strings, config defaults, i18n dicts, PDF attachment metadata, HTML titles, Docker container name, package name, repo URLs, deploy paths, and all documentation updated. Git remote switched to faunosteo.git. Domain URLs (zoosteo.fr) preserved — DNS update is separate. 155/155 tests green. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
7.6 KiB
Adding a New Species
Faunosteo 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-detailkey), - 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
idmust be unique. Two folders default-exporting manifests with the sameidtriggers 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 | Must be one of the 7 valid values defined in 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/<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, and the full authoring contract
(structural rules, taxonomy patterns, v2.0 vet-referral policy,
changelog) lives in
docs/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/<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.
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
pnpm lint
pnpm typecheck
pnpm test:run
pnpm build
All four must be green before the new species lands.