BDR-020 (pathology editor standalone), BDR-021 (zoneMatch inline port), LRN-025 (importNode XSS), LRN-026 (inline port pattern). Journal updated for 2026-05-22 sessions. Co-Authored-By: Claude <noreply@anthropic.com>
9.5 KiB
Decisions Registry
Format: BDR-XXX | Date | Title | Rationale | Alternatives | Status
BDR-001 | 2026-05-18 | React SPA exception for tool app
Tool is practitioner-only, no public indexing needed → SPA valid per CLAUDE.md rule. Alt: Next.js SSR rejected — no server, static deploy only. Status: closed.
BDR-002 | 2026-05-18 | SVG inline via DOMParser, not img/object
Inline SVG = full CSS control, pointer-events, data-* access. img/object = sandboxed, no DOM access, no click delegation. Status: closed.
BDR-003 | 2026-05-18 | PDF attachment via native pdf-lib attach()
Native EmbeddedFiles (afRelationship:Data) = proper PDF spec, survives re-save in Acrobat. Alt: custom metadata → rejected (non-standard, stripped by some viewers). Status: closed.
BDR-004 | 2026-05-18 | Runtime identity via window.APP_CONFIG
Build-time VITE_APP_* → baked into bundle; runtime injection via entrypoint.sh → no rebuild needed for brand changes. Order: runtime > build-time > defaults. Status: closed.
BDR-005 | 2026-05-18 | Vertebra picker: region tabs + chip grid
≥40px touch targets, multi-select, per-region toggle. Alt: flat list → too long for 54 total vertebrae. Status: closed.
BDR-006 | 2026-05-18 | Drag-reorder: up/down buttons, not DnD
DnD on mobile unreliable; ↑/↓ buttons accessible + simple. Status: closed.
BDR-007 | 2026-05-18 | pnpm 11 used instead of pnpm 9
pnpm@9 not available on host; corepack resolved 11.1.3. Package.json engine constraint set to >=9 for Docker (Docker uses corepack latest). Status: closed — deviation accepted.
BDR-008 | 2026-05-19 | PDF page layout — branded heading pattern
Each PDF page leads with bold-uppercase accent eyebrow (size 9), Times 22 title, 2pt × 48pt accent rule under title. Section labels follow same eyebrow style (uppercase bold accent) above their values. Observation severity rendered as filled color-coded pill (sage / amber / red) next to the obs number. Alts: plain text titles only — rejected (overlapped header rule + read unstyled). Status: closed.
BDR-009 | 2026-05-20 | Findings JSON keeps snake_case in TS, observation snapshot uses camelCase
JSON catalog fields (name_fr/name_en/description_fr/requires_vet_referral/...) stay snake_case in TS types/Zod schema — no transform layer. Domain-expert authored, reads natural in JSON, zero remap cost. Observation Finding snapshot uses camelCase (labelFrSnapshot/labelEnSnapshot/requiresVetReferral) per app convention. Alt: Zod transform to camelCase everywhere — rejected (extra layer, hides JSON shape, no real upside for a static catalog). Status: closed.
BDR-010 | 2026-05-20 | Observation findings snapshot labels at selection time
Finding stores labelFrSnapshot + labelEnSnapshot copied from leaf at click time. Exported reports remain readable years later even if catalog renames/restructures leaves. Path[] still carried for future re-link/migration. Alt: lookup labels on render via path — rejected (breaks already-exported PDFs if catalog edits). Status: closed.
BDR-011 | 2026-05-20 | v1 PDF import — hard-fail with version-specific FR message
importReportFromPdf detects data.version !== 2 BEFORE strict Zod parse, throws IncompatibleReportVersionError, wrapped into ImportError with explicit "v{n}, incompatible avec v2, réexportez..." message. No retro-compat shim (no prod PDFs in the wild).
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 <id>, 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.
BDR-014 | 2026-05-20 | PDF locale = render preference, not Report schema field
exportReportToPdf takes explicit { locale } option read from localeStore at call site. Locale lives outside Report — never persisted in schema. Rationale: Finding snapshots already carry labelFrSnapshot+labelEnSnapshot (per BDR-010), so render-time locale picks the correct snapshot; no schema bump needed; re-imported PDF can be re-exported in either locale without data migration; embedded JSON byte-identical between locale variants of the same Report.
Alt rejected: store locale field on Report schema — would force v3 bump, complicate re-export ergonomics, duplicate state already in store.
Alt rejected: default locale to 'fr' in export — caller is route layer, has store, easy to pass; explicit arg makes tests + API surface clean.
Status: closed.
BDR-015 | 2026-05-20 | Typed ImportError discriminant (kind + foundVersion) over localized messages
ImportError carries kind: 'invalid_pdf' | 'incompatible_version' | 'no_attachment' + optional foundVersion. Message field collapses to internal sentinel. UI layer (HomeRoute) resolves user-facing string via i18n dict using err.kind, with {version} template substitution. Rationale: review caught hardcoded FR in pdf/import.ts + pdf/attachment.ts leaking to EN UI; original "throw with localized message" coupled domain layer to one locale; typed discriminant moves message authoring to the UI layer where i18n lives.
Alt rejected: keep FR messages, translate via err.message string match — brittle (any rewording breaks the lookup), spreads i18n knowledge into the catch site.
Alt rejected: pass t() into domain layer — wrong direction; domain should not know about React hooks or current locale.
Status: closed.
BDR-016 | 2026-05-21 | pathologies.json v2.0 — boolean source of truth, generic vet description_fr purged
Catalog bumped v1.2→v2.0. requires_vet_referral: true boolean = sole source of truth for vet flag. Generic "orienter vers vétérinaire" descriptions purged on 25 leaves where boolean alone sufficed. description_fr kept on 16 leaves carrying differential cue (cause neuro/sinusale/ligamentaire/rotulienne/etc.). Horse coverage extended placeholder 3 zones → full 26 zones (9 head + 17 body), 792 nodes, 612 leaves, 41 vet-referral leaves. Schema_version "2.0".
Why: v1.2 had textual fallback (description_fr.includes('vétérinaire')) + boolean coexisting → redundant + ambiguous. v2.0 collapses to one signal.
How to apply: Any new species JSON authored at v2.0 — boolean on vet leaves only, description_fr only when it adds clinical differential beyond "see vet". Consumers MUST use boolean check, never textual scan.
Alt rejected: keep dual signal — wastes maintainer attention, drift risk between text and boolean.
Status: closed.
BDR-017 | 2026-05-22 | SVG editor: vanilla JS wrap over React rewrite
editor.html = ~1630-line standalone SVG annotation tool (DOM manipulation, drag/drop, polygon editing, zoom, categories, export). Integrated into React app via useRef + useEffect mounting all vanilla JS logic into container refs. Only CSS restyled to Zoosteo tokens.
Alt rejected: full React rewrite (convert all state to Zustand/useState, all DOM ops to React) — massive effort ~10x, high risk of subtle behavior differences in drag/polygon/zoom interactions.
Status: closed.
BDR-020 | 2026-05-22 | Pathology editor: standalone HTML, not React route
pathology-editor.html = standalone tool at project root, same pattern as SVG editor integration. Vanilla JS/CSS, no build step, no deps. Decoupled from React app entirely — zero imports from src/. Why: tool for domain experts editing JSON, not practitioners using main app. No shared state needed. Standalone = deployable anywhere, no Vite required. Alt rejected: React route with Zustand store — unnecessary coupling, heavier DX for a JSON editing tool. Status: closed.
BDR-021 | 2026-05-22 | Port zoneMatch.ts inline into pathology editor
Fuzzy matching logic (normalizeLabel, levenshtein, scorePair, matchZone) duplicated inline in pathology-editor.html rather than imported from src/lib/zoneMatch.ts. Why: standalone HTML cannot import TS modules. Keeping identical algorithm ensures matching consistency between main app and editor. Alt rejected: extract to shared .js file — adds dependency management for a tool that should be zero-dep. Status: closed.