Remote moved to git.bchanot.fr/bchanot/zoosteo.git; brand strings
and production URL updated to match new identity.
- package.json: name → zoosteo
- src/config/env.ts: AppConfig DEFAULTS → "Zoosteo"
- docker/entrypoint.sh: APP_*_NAME fallbacks → "Zoosteo"
- src/i18n/{fr,en}.ts: import error message + PDF title prefix
- src/pdf/attachment.ts: embedded description metadata "state v2"
- index.html: <title> fallback
- scripts/scaffold-species.mjs: console banner
- tests/unit/components.Brand.test.tsx: regex
- README.md, CLAUDE.md, CHANGELOG.md, docs/ADDING-A-SPECIES.md:
brand headings + intro lines
- DEPLOY.md: env defaults table + osteo.example.com → zoosteo.fr
(clone URL, paths, certbot, curl, container name references)
PDF attachment FILENAME 'osteo-report.json' and the startsWith
contract in src/pdf/attachment.ts:35,40 are preserved — changing
them would break PDF import for every PDF already exported by the
app. docs/superpowers/** and .claude/audits/** left unchanged as
historical records.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
230 lines
7.6 KiB
Markdown
230 lines
7.6 KiB
Markdown
# 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 `<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.
|