# 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.