From bffa6fba267708af92af311842054797154e795f Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Wed, 20 May 2026 06:21:39 +0200 Subject: [PATCH] =?UTF-8?q?chore(memory):=20/close=20=E2=80=94=20BDR-012/0?= =?UTF-8?q?13=20+=20LRN-013..016=20+=20journal=202026-05-20=20(session=202?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Capture the second-session findings-tree iteration learnings before they fade: Decisions - BDR-012 species auto-discovery via Vite import.meta.glob default-export contract (alternatives: hardcoded registry, runtime registerSpecies()). - BDR-013 SVG↔JSON zone bridge via fuzzy FR/EN label match (alternatives: rename SVG ids, add new data-anno-finding-zone attribute). Learnings - LRN-013 import.meta.glob + default-export as a plugin-discovery pattern. - LRN-014 normalize + Levenshtein recipe for human-string cross-walk. - LRN-015 per-source try/catch beats wrapping a loop with one outer catch. - LRN-016 pdf-lib subset-font output: latin1/utf-8 bytes-grep won't find user-visible text — extract the JSON attachment or test through a refactored helper instead. Journal - Logs the 11 commits between b7b0945 and 70f21cc with one-line summaries + cross-refs to the new registry entries. Co-Authored-By: Claude --- .claude/memory/decisions.md | 18 ++++++++++++++++++ .claude/memory/journal.md | 20 ++++++++++++++++++++ .claude/memory/learnings.md | 29 +++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+) diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 4d749b60..6119f398 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -89,3 +89,21 @@ importReportFromPdf detects `data.version !== 2` BEFORE strict Zod parse, throws Alt: silent generic ImportError — rejected (user can't tell why import failed). Alt: v1→v2 migration adapter — rejected (no install base to justify cost). Status: closed. + +--- + +## BDR-012 | 2026-05-20 | Species auto-discovery via Vite import.meta.glob + +`src/domain/species/registry.ts` uses `import.meta.glob('./*/index.ts', { eager: true })` and registers every module that default-exports a SpeciesManifest. Drop-folder onboarding: scaffold writes index.ts with `export default `, no registry edit needed. Duplicate id → warn + first wins. Missing default export → silently skipped. +Alt rejected: hardcoded SPECIES_REGISTRY map — forced edits in two places, broke "single source of truth" per species folder. +Alt rejected: explicit registerSpecies() runtime helper — extra import boilerplate per species, no compile-time check that registration runs. +Status: closed. + +--- + +## BDR-013 | 2026-05-20 | SVG↔JSON zone bridge via fuzzy FR/EN label match + +SVG data-anno-id values stay opaque generator strings (point-mpb..., zone-...). JSON catalog keys are stable human zone names (sphenoid, atm). Bridge runs at observation render: matchZoneFindings normalizes both sides (lowercase + NFD-strip accents + alphanum-only) and scores EN-exact → FR-exact → substring → Levenshtein within max(2, floor(maxLen*0.25)) tolerance. EN first because no accent normalization edge cases. +Alt rejected: rename SVG data-anno-id to JSON keys — couples opaque SVG generator output to human-meaningful catalog, brittle across SVG re-exports. +Alt rejected: add new `data-anno-finding-zone` attribute on every hitbox — forces SVG edit per species, double-source for the same info already in name_fr/en. +Status: closed. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 66cd9c62..0951d694 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -47,3 +47,23 @@ Bundled B0+B1+B2 shipped on feat/findings-tree-v2. 3 atomic commits. - 107/107 tests green, lint 0 warn, typecheck clean, vite build OK (882KB main + 15KB lazy pathologies chunk). - BDR-009 (snake_case JSON fields preserved in TS), LRN-011 (Zod recursive via z.lazy + explicit ZodType), LRN-012 (sessionStorage flag pattern for once-per-session UX modals) to capitalize. - NEXT: push branch + PR. After merge: B3 (i18n FR/EN) + B4 (PDF observationPage polish for vet-referral) + C (full horse.json + QA + deploy). + +--- + +## 2026-05-20 (session 2) + +Iterated on the findings-tree branch — 11 more commits on top of B0+B1+B2. +- 1731adf fix(editor): match findings tree to SVG zones via FR label (strict equality, dropped raw-boneId lookup). +- 95d746b feat(editor): fuzzy zone matcher (src/lib/zoneMatch.ts) — normalize + Levenshtein, EN-first + FR fallback. 23 new tests. +- 34acb0c feat(editor): count badges on intermediate FindingsTreePicker nodes (pathStartsWith + countSelectedUnder). +- 93294a4 fix(pdf): buildZoneLabels per-source try/catch + parallel + warn + exported for tests. Fixes raw-boneId fallback when detail SVG fetch fails. +- 1e12f22 fix(editor): EditorRoute eagerly preloads every species.details SVG so re-imported PDFs render their pickers immediately. +- de40c5f feat(editor+pdf): per-zone PDF sections "CONSTATS — " + dedicated "CONSTATS LIBRES"; ObservationCard accordion (one zone picker open at a time). +- add408e feat(pdf): single-SVG observations halved + centered; first halo glow on main-view selections. +- 4f8ea9e fix(pdf): bumped halo with stacked feGaussianBlur (stdDeviation 18 + 8) to survive the SVG→canvas→PNG→pdf-lib alpha attenuation. +- 700567f feat(pdf): inter-item separator rendered as accent-coloured bold "•" @14pt with per-segment layout instead of plain join (height-estimator updated). +- 70b7f20 feat(species): auto-discover species via import.meta.glob default-export contract + `pnpm scaffold:species` Node script + docs refresh. +- 70f21cc docs: PATHOLOGIES-FORMAT.md — canonical findings-JSON spec mirroring src/domain/schema/findings.ts. +- BDR-012 (auto-discovery import.meta.glob), BDR-013 (fuzzy FR/EN label bridge), LRN-013 (glob+default plugin pattern), LRN-014 (normalize+Levenshtein cross-walk), LRN-015 (per-source try/catch), LRN-016 (pdf-lib subset-font bytes-grep caveat) captured. +- Tests 139/139 green, lint 0, typecheck clean, vite build OK throughout. Branch feat/findings-tree-v2 = 15 commits ahead of main, no remote configured (push + PR still pending). +- NEXT: push branch + PR; then B3 (i18n FR/EN), B4 (PDF observationPage vet-referral polish), C (full horse.json + QA + Scaleway deploy). diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index a182dc46..a3841d62 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -94,3 +94,32 @@ Apply: any tree/AST-style schema in Zod 3.x. Declare interface first, type the s Pattern: state `disclaimer: string | null`, useEffect on the data dep that reads `sessionStorage.getItem(FLAG)`; if absent, set state to the message. Acknowledge handler writes the flag and clears state. Survives reloads within tab, resets on new tab. Cheaper than persisting per-user (no backend) and respects practitioner intent — they see the legal scope reminder once per work session. Apply: any single-praticien tool needing one-shot acknowledgment per session (legal disclaimers, version-change notices, GDPR banners scoped to a session). Use a stable string key prefixed with `osteo:` to avoid collision. + +--- + +## LRN-013 | 2026-05-20 | Vite import.meta.glob + default-export = plugin discovery + +`import.meta.glob<{ default: T }>('./*/index.ts', { eager: true })` scans the folder at build time and returns a `Record`. Combined with a "each module must default-export a T" convention, you get drop-folder plugin discovery: drop a conforming folder → it shows up in `Object.values(modules).map(m => m.default)`. Eager mode resolves synchronously so the registry is a plain object literal in the bundled output. +Pitfalls: a missing default export silently disappears (warn explicitly on `!mod.default`), and duplicate ids need a tie-break policy (first-wins + warn). Glob ordering is filesystem-dependent — sort the output by a stable key (e.g. labelFr) before exposing it to UI. +Apply: any registry-style module set where you want zero-touch onboarding — species, integrations, plugins, theme packs. + +--- + +## LRN-014 | 2026-05-20 | Cross-walk human strings via normalize + Levenshtein + +When bridging two sources of the same human label (SVG `data-anno-name-fr` ↔ JSON `zone.name_fr`), strict equality is too brittle (casse, accents, "(ATM)" abbreviations, typos). Robust strategy: aggressive normalize (lowercase + NFD-strip combining marks + drop non-alphanumerics), then score by `0=exact`, `1=substring`, `2+d=Levenshtein within max(2, floor(maxLen*0.25))`, `∞=no match`. EN-first if both languages available — no accent normalization edge cases. +Apply: any cross-system label match where one side is authored, the other generated or hand-typed. The 25% character tolerance is a sweet spot — catches single typos on labels 8+ chars, refuses cross-zone collisions (Sphenoid ↛ Spheno-Basilar Synchondrosis even though both share "spheno"). + +--- + +## LRN-015 | 2026-05-20 | Per-source try/catch beats loop-wrapping try/catch + +Original `buildZoneLabels` wrapped main + every detail SVG fetch in one outer try/catch. First failing source (e.g. 404 on a detail asset) aborted the whole loop, leaving callers a partially-filled map with no signal — the rest of the labels never made it in. Lesson: when each iteration is independent, the try/catch belongs INSIDE the iteration (or inside the `Promise.all` callback). Outer catch only makes sense when iterations are sequentially dependent and the work is moot after a failure. +Apply: any fan-out fetch / parse / transform over heterogeneous sources — config loaders, plugin enumerators, asset preloaders. Bonus: log on failure (console.warn) so the silent skip is observable in dev. + +--- + +## LRN-016 | 2026-05-20 | PDF custom-font text is glyph-subset — bytes-grep won't find it + +pdf-lib with embedded TTF fonts (Inter, Fraunces) subsets glyphs and stores text streams as glyph indices, not codepoints. A latin1 / utf-8 grep over the raw PDF bytes will not match user-visible strings ("Temporo" never appears literally in the dump). Standard PDF text show ops (`Tj`, `TJ`) carry the glyph IDs inside content streams that are typically Flate-encoded too. +Testing implication: don't assert PDF text via byte grep — either re-extract the embedded JSON attachment (already plain text) or refactor the offending logic into an exported helper and unit-test that. Same pattern when smoke-testing PDF output in CI.