From 70b7f20f6f3daba71470d21c00b41aa71f5fc594 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Wed, 20 May 2026 05:46:33 +0200 Subject: [PATCH] feat(species): auto-discover species manifests + scaffold script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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//index.ts (with `export default`) src/domain/species//vertebrae.ts src/domain/species//pathologies.ts (Zod-parses the JSON) src/domain/species//pathologies.json (minimal valid skeleton) public/species// (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 --- docs/ADDING-A-SPECIES.md | 313 ++++++++++++++--------------- package.json | 3 +- scripts/scaffold-species.mjs | 235 ++++++++++++++++++++++ src/domain/species/equine/index.ts | 5 + src/domain/species/registry.ts | 46 ++++- 5 files changed, 432 insertions(+), 170 deletions(-) create mode 100755 scripts/scaffold-species.mjs diff --git a/docs/ADDING-A-SPECIES.md b/docs/ADDING-A-SPECIES.md index b2885229..86cc149d 100644 --- a/docs/ADDING-A-SPECIES.md +++ b/docs/ADDING-A-SPECIES.md @@ -1,61 +1,113 @@ # Adding a New Species -This guide walks through every step required to add a new species (e.g. dog, -cat, bovine) to Osteo Report. The reference implementation is `equine` — -mirror its structure when 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 `` with the new species' kebab-case id -(e.g. `canine`, `feline`, `bovine`). +> Throughout this document, replace `` with the new species' +> kebab-case id (e.g. `canine`, `feline`, `bovine`). --- -## 1. Author the anatomy SVGs +## Quick start — `pnpm scaffold:species` -All SVG assets must conform to the conventions in -[`docs/ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md). The parser -in `src/anatomy/svgConvention.ts` reads the same attributes, so any drift -breaks the editor canvas. - -Every clickable zone element must carry these data attributes: - -| Attribute | Required | Notes | -|----------------------|----------|-----------------------------------------------------------------| -| `data-anno-id` | yes | Stable kebab-case id, unique within the SVG. | -| `data-anno-name-fr` | yes | French anatomical label (used in tooltips and PDF text). | -| `data-anno-name-en` | yes | English anatomical label (used as fallback and a11y hint). | -| `data-anno-category` | yes | One of: `articulation`, `charniere`, `spine-zone`, `os`, `os-overlay`, `head`, `cadran-crane`. | -| `data-anno-opens-detail` | no | Id of a detail popup SVG to open when the zone is clicked. The id must match a key in the species manifest's `details` map. | - -Reuse the equine SVG patterns: - -- **Hitbox + visible twin** — used for `articulation`, `charniere`, `os-overlay`, `head`. -- **Single visible element** — used for `spine-zone`, `os`, `cadran-crane`. - -See `public/species/equine/Horse.svg` and `public/species/equine/Horse_head.svg` -for fully worked examples. - -## 2. Drop the SVGs into `public/` - -Put the assets at: - -``` -public/species//
.svg # main side-view body schema -public/species//
_.svg # one detail SVG per opens-detail key +```bash +pnpm scaffold:species ``` -For example, for a dog with a single head detail popup: +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: ``` -public/species/canine/Dog.svg -public/species/canine/Dog_head.svg +src/domain/species// + 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// (directory created, empty) ``` -The `public/` prefix is implicit at runtime — the manifest references files -by absolute path starting with `/species/...`. +The script refuses to clobber existing files, so it is safe to rerun. -## 3. Create the species manifest +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. -Create `src/domain/species//index.ts` exporting a `SpeciesManifest`: +--- + +## 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//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 | 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//
.svg +public/species//
_.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//index.ts`: ```ts import type { SpeciesManifest } from '@/domain/species/types' @@ -69,50 +121,23 @@ export const canine: SpeciesManifest = { head: '/species/canine/Dog_head.svg', }, vertebralFormula: CANINE_VERTEBRAL_FORMULA, - pathologies: () => import('./pathologies'), + findings: () => import('./pathologies'), } + +export default canine // <- required for auto-discovery ``` -Required fields (see `src/domain/species/types.ts`): +`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. -- `id` — must match the folder name and the registry key. -- `labelFr` — French display name shown in the species picker. -- `mainSvg` — absolute path to the main anatomy SVG. -- `details` — map of detail id → SVG path. Keys must match every distinct - `data-anno-opens-detail` attribute used in the main SVG. -- `vertebralFormula` — segment counts for the VertebraPicker (see step 5). -- `pathologies` — lazy import returning `{ default: Pathology[] }` (step 6). +### 3. Provide the vertebral formula -## 4. Register the manifest - -Edit `src/domain/species/registry.ts` to add the new manifest: - -```ts -import type { SpeciesManifest } from './types' -import { equine } from './equine' -import { canine } from './canine' - -const SPECIES_REGISTRY: Record = { - [equine.id]: equine, - [canine.id]: canine, -} -``` - -The species will now appear in the species `