docs: add CHANGELOG.md — v1.0.0 entry (Keep a Changelog format)

First versioned changelog for the project. v1.0.0 entry covers the
shipped state on master at this commit: scaffold + B0..B3 (findings
schema, Report v2, FindingsTreePicker, i18n FR/EN), catalog v2.0
adoption, WinAnsi PDF hotfix, docs refresh, branch rename main →
master, push to https://git.bchanot.fr/bchanot/osteo-report.git.

Added / Changed / Fixed sections + Known limitations + a "Pre-1.0
milestones" appendix referencing git history for the un-tagged
scaffold / editor-polish / findings-tree-pivot / catalog-v2.0
sessions.

Note: package.json `version` field is still 0.1.0 — bump to 1.0.0
deliberately deferred until you're ready to tag the release on the
Gitea remote.
This commit is contained in:
Bastien Chanot committed 2026-05-21 04:13:37 +02:00
1 parent 98117b3b7f
commit fad3cb178a
1 file changed
+189
+189
View File
@@ -0,0 +1,189 @@
# Changelog
All notable changes to **Osteo Report** are documented here.
Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
Versions follow [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
- _(nothing yet)_
### Changed
- _(nothing yet)_
### Fixed
- _(nothing yet)_
---
## [1.0.0] — 2026-05-21
First public release. Single-praticien web app for veterinary
osteopathy bilans on animal anatomy SVGs. Static SPA, no backend, no
auth; the exported PDF is the long-term record, with the full report
JSON embedded as a native PDF attachment so re-importing the PDF
restores the session for a follow-up.
### Added
- **Anatomy canvas** — inline SVG with clickable zones, hitbox+visible
twin pattern, delegated click listener, async-mount safe.
- **Detail popups** — click a zone (e.g. head) to open a secondary SVG
with finer-grained zones. Independent bones map, fallback lookup
across main + detail.
- **Vertebra picker** — region tabs (C/T/L/S/Cd) with multi-select chip
grid; region tab preselected from the clicked zone label.
- **Hierarchical findings tree** — per-zone picker with breadcrumb
drill-down, leaf toggle, vet-referral badge, count badges on
intermediate nodes, scope-disclaimer modal shown once per session.
- **Bilingual UI (FR / EN)** — full i18n via flat dict + `useT()` hook,
language switcher in every header, locale persisted to
`localStorage`, default auto-detected from the browser.
- **PDF export** — A4 portrait with rasterized anatomy SVGs (canvg
@ 2×), structured per-zone observation sections (`CONSTATS — <ZONE>`
+ `CONSTATS LIBRES`), severity pill, conclusion page, locale-aware
static labels. Inter-item separator rendered as accent-coloured
bold bullet.
- **PDF import** — Zod-validated re-import of a previously exported PDF
restores the entire session. Typed `ImportError` (discriminant +
`foundVersion`) with i18n-resolved user-facing messages.
- **Practitioner cache** — last-used practitioner block prefilled via
`localStorage`.
- **Runtime identity** — `APP_SITE_NAME` / `APP_BRAND_NAME` /
`APP_FOOTER_NAME` / `APP_TAGLINE` injected into `env.js` at container
start; no rebuild required for brand changes.
- **Species auto-discovery** — drop a `src/domain/species/<id>/index.ts`
default-exporting a `SpeciesManifest` and the species appears in the
picker. `pnpm scaffold:species` writes a valid skeleton.
- **Findings catalog v2.0** — full equine catalog authored by the
domain expert: 26 zones (9 head + 17 body), 792 nodes, 612 leaves,
41 vet-referral leaves. Schema documented in
[`docs/PATHOLOGIES-FORMAT.md`](docs/PATHOLOGIES-FORMAT.md) with the
3 standardized categories per zone, 5 taxonomy patterns for
dysfunctions, structural authoring rules (depth ≤ 4, ≥ 2 children
per intermediate, sibling-scoped ID uniqueness), and the legal-scope
disclaimer.
- **Fuzzy zone matcher** — SVG `data-anno-name-fr` / `-en` ↔ JSON
`zone.name_fr` / `name_en` bridged via normalize + Levenshtein
(EN-first, FR fallback). Tolerant of case, accents, and minor typos.
- **Docker delivery** — multi-stage `Dockerfile` (node:20 → nginx:alpine),
`docker-compose.yml`, `entrypoint.sh` runtime env injection, nginx
SPA fallback + `env.js` no-cache rule. Production deploy guide in
[`DEPLOY.md`](DEPLOY.md).
- **Documentation** — `README.md`, `CLAUDE.md` (project conventions
for Claude), `docs/ANATOMY-SVG-CONVENTION.md` (SVG data-* contract),
`docs/ADDING-A-SPECIES.md` (recipe for a new species),
`docs/PATHOLOGIES-FORMAT.md` (findings JSON authoring contract),
`docs/PDF-FORMAT.md` (PDF layout placeholder), and project-state
notes under `.claude/{tasks,memory,audits}/`.
### Changed
- **Report schema v1 → v2**: `Observation` carries hierarchical
`findings: Finding[]` (zone + path + snapshotted FR/EN label + vet
flag) and `freeTextFindings: string[]`; old `pathologyIds` /
`freeTextPathologies` removed. `ReportSchema.version` bumped `1` → `2`.
v1 PDFs are not migrated — they hard-fail import with a
version-specific message (no install base to justify a migration
shim).
- **Catalog v1.2 → v2.0 contract**: `requires_vet_referral` boolean is
now the **sole source of truth** for the vet-orientation flag.
Generic "orienter vers vétérinaire" wording purged from
`description_fr` on 25 leaves where the boolean alone sufficed.
16 leaves carrying a clinical differential (cause neuro/sinusale/
ligamentaire/etc.) keep their `description_fr`. Consumers relying on
`description_fr.includes('vétérinaire')` must migrate — all in-tree
consumers already key off the boolean.
- **PDF locale = render preference**, not a schema field. Finding
snapshots already carry both FR and EN labels (`labelFrSnapshot` /
`labelEnSnapshot`), so `exportReportToPdf(report, { locale })`
picks the right snapshot at render time without a schema bump.
- **PDF date format** — locale-aware via `formatDate(iso, locale)`,
replacing the FR-only `formatDateFr` helper.
- **Default branch** — `main` → `master` (matches the Gitea remote at
`https://git.bchanot.fr/bchanot/osteo-report.git`).
### Fixed
- **PDF export crashed** `WinAnsi cannot encode "⚠" (0x26a0)` whenever
an observation carried a `requires_vet_referral` finding —
`pdf/fonts.ts` embeds `StandardFonts.Helvetica` which uses WinAnsi
(cp1252, Latin-1 only). PDF vet-referral marker swapped `⚠ ` →
`(!) `; picker DOM keeps `⚠` (browsers render U+26A0 natively).
Regression test added on `widthOfTextAtSize` + prefixed label.
Follow-up tracked: switch PDF body to embedded TTF
(Inter / Fraunces per `CLAUDE.md` spec) so future non-Latin-1 glyphs
work without ASCII surrogates.
- **PDF import error messages** localized via typed `ImportError`
discriminant — the prior FR-only messages leaked through to the EN
UI on import failure.
- **Detail-popup zone clicks** silently dropped — main-only bones map
did not know detail SVG ids; fallback lookup `bones.get(id) ??
detailBones.get(id)` added in the shared click handler.
- **PDF text overlap** — `drawText({ maxWidth })` wraps glyphs but not
the cursor; caller now measures with `widthOfTextAtSize` and
advances cursor per wrapped line.
- **PDF multi-SVG layout** — observation pages with N SVGs overflowed
page bounds. Now: pre-rasterize all, measure aspect, reserve
text-area height, derive cell budget per row; single-SVG layout
halved + centered.
- **PDF anatomy rasterization leaks** — interaction-only attributes
(`data-anno-*`, transparent hitboxes, faint default fills) stripped
before raster, non-selected zones hidden, selected zones recoloured.
- **Zone highlight scoping** — collapsed observations no longer leave
faint tints on the canvas; highlights re-painted after async SVG
mount so detail-popup zones colour correctly.
- **Hyoid label case** — SVG `data-anno-name-fr="hyoïde"` →
`"Hyoïde"` to match the JSON strict-equality rule across all 26
zones (fuzzy matcher still acts as safety net).
- **i18n key parity** — fr/en dicts validated by a parity test
(`Object.keys(fr).sort()` deep-equals `Object.keys(en).sort()`) so a
missing translation fails CI instead of falling back to the key
literal at runtime.
### Known limitations
- PDF body fonts are `StandardFonts.Helvetica` / `TimesRoman`
(WinAnsi / Latin-1) instead of the planned TTF Inter / Fraunces.
Any non-Latin-1 glyph in PDF text needs an ASCII surrogate until
the TTF migration lands.
- `description_fr` for sensitive vet-referral leaves and the
`scope_disclaimer` are FR-only; vet-expert authoring is needed for
the EN copy.
- Only the equine species ships. The infrastructure (manifest +
auto-discovery + scaffold script + schema) accepts any species —
domain expert authoring is the gating step.
- No backend, no accounts, no cloud sync. Each PDF is the long-term
record for the corresponding bilan.
---
## Pre-1.0 milestones (for reference)
These were never tagged but are reflected in git history on `master`.
- **Scaffold (2026-05-18)** — initial skeleton from approved design
spec: 80+ files (schemas, stubs, routes, stores, PDF modules, Docker
infra), real `Horse.svg` + `Horse_head.svg`, `pnpm`/`build`/
`typecheck`/`tests` all green.
- **Editor polish (2026-05-19)** — detail-popup click bridge,
VertebraPicker auto-region, PDF rendering fixes (header rule clear,
text-line wrapping, multi-SVG grid, halo glow), eyebrow + Times 22
title + accent severity pill.
- **Findings tree pivot (2026-05-20)** — B0 schema (`findings.ts`
Zod), B1 Report schema v2 (`Observation.findings`), B2 UI
(`FindingsTreePicker` replaces flat `PathologyPicker`), B3 i18n
FR/EN site + PDF, B5 stub cleanup. `requires_vet_referral` boolean
introduced alongside the textual fallback.
- **Catalog v2.0 + WinAnsi hotfix (2026-05-21)** — full 26-zone horse
catalog landed, `requires_vet_referral` becomes the sole source of
truth, PDF vet marker swapped to a WinAnsi-safe surrogate. Docs
refreshed, `DEPLOY.md` + `CHANGELOG.md` written, default branch
renamed `master`, repo pushed to `https://git.bchanot.fr/bchanot/osteo-report.git`.
[Unreleased]: https://git.bchanot.fr/bchanot/osteo-report/compare/v1.0.0...HEAD
[1.0.0]: https://git.bchanot.fr/bchanot/osteo-report/releases/tag/v1.0.0