Initial hypothesis ("pnpm@latest pulled a newer 11.4+ with new Node
floor") was wrong. Investigation after the second VPS crash showed
the whole pnpm 11.0+ line imports node:sqlite from its store-index
module. Local dev was misleading because pnpm install never re-ran
on the Node 20 host (lockfile already resolved, child scripts don't
load the store module).
Updates:
- BLK-005: replace single-fix line with iteration log
(@latest → @11.1.3 → @10.13.1, last one resolved).
- LRN-022: rewrite headline + body to reflect pnpm 11 ↔ Node 22.13
coupling, not just pnpm 11.4. Add pnpm/Node compat matrix.
- journal 2026-05-21: append v2 fix entry referencing commit 990c8e7.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
16 KiB
Learnings Registry
Format: LRN-XXX | Date | Pattern | Context | Future application
LRN-001 | 2026-05-18 | Zod discriminatedUnion for nextAppointment
Report.nextAppointment uses discriminatedUnion('kind', [...]). Gives precise TS narrowing on .kind; avoids optional union type ambiguity. Apply: any polymorphic field with a literal discriminant.
LRN-002 | 2026-05-18 | SVG hitbox+visible twin pattern
Two SVG elements share same data-anno-id: hitbox (pointer-events:all, fill:transparent) + visible (pointer-events:none, colored). Parser groups by data-anno-id → Bone.hitboxEls[], Bone.visibleEls[]. Apply: any SVG-based interactive map needing precise click areas.
LRN-003 | 2026-05-18 | pnpm via corepack shim breaks on older Node 20
corepack shim on Node 20.20.0 throws ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. Fix: install pnpm directly via get.pnpm.io/install.sh. Binary lands at ~/.local/share/pnpm/bin/pnpm. Apply: CI/dev envs without system pnpm.
LRN-004 | 2026-05-19 | SVG behavior hints via free-form data-anno-special
Branch click handling on data-anno-special (free-form string), not on data-anno-category.
Why: category is free-form metadata (LRN follow-up to refactor BDR/cad94a4 chain); coupling logic to category re-introduces a closed enum and silently breaks when SVG author renames a slug. Hints stay opaque to parser, consumed only at use site.
Apply: any SVG-driven UI where authors add new annotation types regularly — use data-anno-special for behavior triggers, keep category for grouping/filters only.
LRN-005 | 2026-05-19 | Detail-popup needs its own bones map
When a popup loads a separate SVG, its annotation ids are not in the parent's bones map.
Parse detail SVG on popup open and keep a detailBones map; fall back lookup bones.get(id) ?? detailBones.get(id) in shared click handler.
Apply: any nested/zoom-popup pattern where the child SVG has independent ids.
LRN-006 | 2026-05-19 | Strip authoring annotations before rasterizing for print
Source SVGs carry interaction-only artifacts (data-anno-, transparent hitboxes, faint default fills) that are invisible in-app via CSS but leak into PDF rasterization.
Before raster: walk [data-anno-id], hide non-selected via display="none", strip data-anno- attributes, recolor selected.
Apply: any "screen → print" pipeline where the screen SVG has interaction layers.
LRN-007 | 2026-05-19 | pdf-lib maxWidth wraps glyphs, not your cursor
pdf-lib's drawText({ maxWidth }) wraps the visible glyph run but the returned y is unchanged — caller must measure with widthOfTextAtSize and advance the cursor per wrapped line. Otherwise subsequent text blocks overlap the wrapped tail. Apply: any pdf-lib layout with variable-length user text. Always wrap explicitly + advance per line.
LRN-008 | 2026-05-19 | pdf-lib eyebrow + title vertical spacing
Times-22 ascender ≈ 17pt. Eyebrow size-9 baseline above title baseline needs ≥22pt gap to clear the ascender + leave ≥6pt visual breathing. Header rule needs ≥30pt cushion below for a size-22 title (title baseline at height-120ish on A4). Apply: any pdf-lib heading stack (eyebrow + title or chained headings). Compute from font.heightAtSize/widthOfTextAtSize, never eyeball pixel offsets.
LRN-009 | 2026-05-19 | pdf-lib variable-count image layout — pre-rasterize, reserve text, then grid
Variable-count image blocks (N SVGs per observation) overflow page when stacked top-down because each item's height depends on its rasterized aspect ratio, unknown until after embedPng. Order: (1) pre-rasterize every image in parallel via Promise.all, capture aspect = img.height/img.width; (2) build text sections + estimate their height with wrapLines on real font metrics; (3) reserve bottom area = MARGIN_BOTTOM + textHeight + gap, derive availH for images; (4) pick cols (1 if single image, else 2), rows = ceil(n/cols); (5) rowBudget = (availH - rows*labelGap - (rows-1)rowGap)/rows with a min-cell floor; (6) cellH per item = min(cellWaspect, rowBudget) — preserves aspect, capped by budget. Apply: any pdf-lib page where image count is data-driven and text must remain visible. Never lay out images before measuring text; never embed-then-skip — embed all, then place. Min-cell floor prevents zero-height when content is dense.
LRN-010 | 2026-05-19 | React effect that mutates async-appended DOM needs a "loaded" gate
Symptom: highlight effect (querySelectorAll + setAttribute) silently no-ops when sibling effect appends DOM async via loadSvg().then(append). First render: mutate-effect runs against empty container, then DOM arrives, then nothing re-paints because deps didn't change. Symptom is intermittent ("sometimes highlighted, sometimes not") — actually depends on which effect resolves first on a given mount.
Fix pattern: hold a loadedSrc state, set it to null at src-change, set it to src right after appendChild, and depend the mutate-effect on [data, loadedSrc, src] with guard if (loadedSrc !== src) return. Now the mutate-effect re-runs both on data change AND when DOM finishes mounting.
Apply: any React component that mounts external DOM async and applies attribute/style mutations in a separate effect. Includes inline SVG injection, MapLibre overlays, Lottie players. Never rely on effect ordering across an async boundary.
LRN-011 | 2026-05-20 | Zod recursive schema via z.lazy + explicit ZodType
Recursive shapes (FindingNode with optional children: FindingNode[]) need TS interface declared first, then const FindingNodeSchema: z.ZodType<FindingNode> = z.lazy(() => z.object({...})). Without the explicit ZodType annotation, TS infers any for the recursive arm and the entire downstream type chain collapses. Without z.lazy, the schema references itself before initialization → runtime ReferenceError.
Apply: any tree/AST-style schema in Zod 3.x. Declare interface first, type the schema explicitly, wrap recursive shape in z.lazy. Same trick works for ZodType<U[]> when the recursion is via children: U[].
LRN-012 | 2026-05-20 | Once-per-session UX modal via sessionStorage flag
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.
LRN-017 | 2026-05-20 | i18n dict parity via Object.keys.sort equality
Cheapest drift guard between fr/en dicts: one test asserts Object.keys(fr).sort() deep-equals Object.keys(en).sort() + every value non-empty. Catches any forgotten translation at CI time without enumerating keys. Pairs with a flat <area>.<key> convention so adding a key in fr.ts forces matching update in en.ts at the next test run.
Apply: any project with N parallel translation dicts (i18n, locale strings, error-code maps). Beats type-level enforcement (TS can't easily require Record<K, ...> shapes to match across two as const literals without ceremony).
LRN-018 | 2026-05-20 | useT hook: selector subscribe + closure-per-render
export function useT() {
const locale = useLocaleStore((s) => s.locale)
const dict = getDict(locale)
return (key) => dict[key] ?? (warn(key), key)
}
Selector subscribe re-renders consumer only on locale change. Dict resolved once per render, the returned closure does a single hash lookup per call. No prop drilling, no context provider, no React useMemo needed. Missing-key path warns in DEV (import.meta.env?.DEV) and falls back to the key literal so the UI never crashes on a typo.
Apply: any Zustand-state-driven derived computation that needs to re-render N components without prop chains. Same pattern works for theme tokens, feature flags, current user.
LRN-019 | 2026-05-20 | exhaustive-deps trap with closures over store values
Defining a helper like const nameOf = (z) => locale === 'en' ? z.name_en : z.name_fr inside a component and using it inside useMemo([deps]) triggers react-hooks/exhaustive-deps: nameOf is a fresh function each render, listing it in deps invalidates the memo every render; omitting it makes the linter complain. Two fixes:
- Inline the locale-conditional inside the memo body (no closure).
- Wrap the helper in
useCallback([locale])so it's referentially stable. Inline is simpler when the helper is one expression. Apply: any closure that bridges a memoized computation to an outer hook value (store selector, prop, context). Same trap withuseEffectdeps.
LRN-021 | 2026-05-21 | pdf-lib StandardFonts use WinAnsi — Latin-1 only, throws on any non-WinAnsi char
PDFDocument.embedFont(StandardFonts.Helvetica) (and the 13 other Adobe built-ins) returns a font whose encoding is WinAnsi (cp1252). Any text op (widthOfTextAtSize, drawText) on a string carrying a non-WinAnsi codepoint throws synchronously: WinAnsi cannot encode "<glyph>" (0x<hex>). Common offenders: ⚠ U+26A0, → U+2192, ✓ U+2713, ★, em-dash variants outside cp1252, all CJK. The error surfaces at the FIRST measurement pass (text-height estimator) — well before any draw call — so even a try/catch around drawing won't save you.
Fix paths:
- Quick: replace the offending glyph with a WinAnsi-safe ASCII surrogate (
(!)instead of⚠,->instead of→). - Right: embed a TTF (Inter, NotoSans, Fraunces…) via
pdfDoc.embedFont(ttfBytes). pdf-lib then subsets the actually-used glyphs into the PDF; arbitrary Unicode works. Per CLAUDE.md spec our PDF should already use TTFs — current StandardFonts shipment is a drift. Why: Slipped past CI because the existing PDF roundtrip tests exercised observations without vet-referral findings; the WinAnsi error only fires when the offending glyph is present in a measured string. How to apply: When a new visual cue (icon, badge, arrow) is added to PDF output, either restrict to ASCII or audit the font path. Add a regression test that exercises the measurement path with a representative string. The cheap canary:font.widthOfTextAtSize(candidateGlyph, 10)in a test.
LRN-020 | 2026-05-21 | Forward-compat Zod schema absorbs catalog version bump zero-code
Catalog JSON went v1.2→v2.0 (semantic breaking change per author doc), but findings.ts Zod schema declared requires_vet_referral boolean + description_fr optional from B0 day-one. Result: v2.0 file dropped in, parses clean, 154/154 tests stay green, no schema edit, no consumer rewrite. Picker + PDF already keyed on boolean (no textual description_fr.includes('vétérinaire') fallback ever existed in our code), so the v2.0 "removed redundant text" change is a no-op at consumption site. Lesson: when authoring a Zod schema for external content, mark anything that "might or might not" appear as .optional() + make booleans authoritative early. The schema then forms a stable contract that absorbs author-side simplifications without code churn.
Apply: any data contract sourced from non-engineering authors (clinical, legal, marketing). Decouple presence-of-field from semantic-of-field; let the boolean drive logic, let text be display-only ornamentation.
LRN-022 | 2026-05-21 | pnpm 11.x requires Node 22.13 — pin pnpm to ≤10.x when staying on Node 20, never use @latest
pnpm 11.x imports node:sqlite for its store-index module — loaded at pnpm startup for any command that touches the store (install, fetch, add, prune). node:sqlite is a Node 22.13+ built-in. Result: ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite on every fresh Docker build using node:20-alpine + pnpm 11.x. The crash is deterministic for cold installs and invisible for warm dev hosts that already have node_modules resolved (pnpm 11 on Node 20 can still spawn child scripts because the store module isn't required for pnpm run).
Initial hypothesis ("pnpm@latest pulls a newer 11.x with a new Node floor") was wrong — the whole pnpm 11.0+ line carries the sqlite dependency.
Fix paths:
- Stay on Node 20 → pin Dockerfile to
pnpm@10.x(e.g.corepack prepare pnpm@10.13.1 --activate). pnpm 10 reads lockfile v9 unchanged. - Move to Node 22 → bump
FROM node:22-alpine,.nvmrc, and CLAUDE.md stack table together. Required if pnpm 11+ features needed. - Mirror exact version in
package.json:"packageManager": "pnpm@X.Y.Z"so host + Docker stay synced via corepack. - Never
corepack prepare pnpm@latest— re-resolves at every cold build, silently bumps toolchain across deploys with no commit. Why: Floating tag = drift bomb between cached dev + fresh prod resolve. Same risk for unpinnednode:lts,:alpine, GitHub Actionsuses: foo@v1(prefer SHA). Lockfile pins app deps; Dockerfile must pin toolchain. How to apply: Before first prod deploy, audit every Dockerfile, docker-compose, and CI workflow for floating upstream refs. For pnpm specifically, check Node version against pnpm minimum (pnpm 11 ↔ Node 22.13, pnpm 10 ↔ Node 18+, pnpm 9 ↔ Node 18+).