Files
faunosteo/docs/ADDING-A-SPECIES.md
T
Bastien Chanot 8385b49bbe docs: sync drift after catalog v2.0 + i18n + WinAnsi hotfix
doc-syncer audit applied 10 AUTO patches and 1 HUMAN reword (#5)
across the doc set.

README.md:
- Test count "7 tests pass on skeleton" / "88 tests across 23 files"
  → "155 tests" / "155 tests across 29 files".
- Reword "Observation builder" bullet + add hierarchical findings
  tree + browser-detected locale bullets (HUMAN #5).
- Status paragraph: pathology DB "intentionally empty" → full
  26-zone v2.0 catalog (792 nodes, 612 leaves, 41 vet leaves).
- Documentation section: add PATHOLOGIES-FORMAT.md link; tidy the
  DEPLOY.md mention (DEPLOY.md itself comes in the next commit).

CLAUDE.md:
- Architecture block: "embedFonts (Inter body + Fraunces heading)"
  → reality (Helvetica + TimesRoman / WinAnsi StandardFonts; TTF
  Inter/Fraunces planned).
- PDF convention: "Fonts are TTF" → "Fonts are StandardFonts
  (Helvetica/TimesRoman, WinAnsi)" with the ASCII-surrogate caveat.
- Folder map: add src/anatomy/labels.ts, include zoneMatch.ts in
  src/lib/{...}.ts.
- i18n: locale default "fr" → "navigator-detected fr/en, or 'fr'
  if no match" to match commit 9cf8a66.

docs/PATHOLOGIES-FORMAT.md:
- "PDF surface: snapshot label is prefixed ⚠" → "(!)" in two
  places (after WinAnsi hotfix 143fdc3). Picker ⚠ statement
  kept — browser renders U+26A0 natively.

docs/ADDING-A-SPECIES.md:
- data-anno-category: "Free-form" → enum of 7 valid values per
  ANATOMY-SVG-CONVENTION.md; parser throws SvgConventionError on
  unknown values.
- Section 4 (findings catalog): cross-link to
  docs/PATHOLOGIES-FORMAT.md so authors find the v2.0 contract.
2026-05-21 04:13:13 +02:00

7.6 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 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.


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.