chore(memory): /close — BDR-012/013 + LRN-013..016 + journal 2026-05-20 (session 2)

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 <noreply@anthropic.com>
This commit is contained in:
Bastien ChanotandClaude committed 2026-05-20 06:21:39 +02:00
1 parent 70f21ccf37
commit bffa6fba26
3 files changed
+67

No files matched your search

+29
View File
@@ -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<path, module>`. 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.