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>
230 lines
7.6 KiB
Markdown
230 lines
7.6 KiB
Markdown
# 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`
|
|
|
|
```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/<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`:
|
|
|
|
```ts
|
|
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`](./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/<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`:
|
|
|
|
```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`:
|
|
|
|
```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`](./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:
|
|
|
|
```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.
|