diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 799dfa5a..fe6efe86 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -345,3 +345,10 @@ Apply: any future CLI/log over report content (Step 6 server import, worker). Te Context: findings picker text blurry on screen, crisp in PDF (Step 5 validation). `motion.ul` kept inline `will-change: transform, opacity` after its 220 ms slide (computed transform `none`); list sat at fractional offset inside height-animated card (left 561.1875 px desktop, top 735.77 px mobile) → element stayed on own compositor layer, text resampled at non-integer position → blur. Fix = drop the prop; motion promotes the element itself while animating (1f0b710). Pattern: never set permanent `will-change` on text containers; let the animation lib promote for the duration. Diagnose with headless Chromium: computed `willChange`, bounding rect fractional offsets, edge-sharpness ratio before/after (headless has no LCD antialiasing → desktop delta flat, user confirms in real browser). Regression test = rendered element has no inline `will-change`. Apply: any `motion.*`/CSS transition on lists, cards, modals holding text; design-review audits. + +--- + +## LRN-046 | 2026-10-11 | Refactor a render pipeline behind goldens frozen in two fixture modes; lean-document snapshot beats a new schema + +Step 6 moved the PDF pipeline into `packages/pdf` with zero visible change. What made it provable: Phase 0 froze drawn text (page, x, y, size, font), image placements, link annotations and per-view structural facts with the OLD code, in two harness modes (logos absent / present via a fetch stub serving the real public/ bytes) and per locale (footer geometry depends on label width). Golden JSON = oracle; the port had 0 mismatch; the two intentional differences (hidden markers absent, data-* gone) were declared as relaxed fields, never by editing goldens. Snapshot shaped as a valid lean `AnatomicalSheetDocument` reused the index, the renderer and 21 integrity rules (3 challengers killed the dedicated-schema idea). Node-side xmldom composer already existed in curation (`app-review.ts`): promote, don't rewrite. resvg 0.40 panics on gradient fills culled by a cropped root viewBox (head view) → test adapter renders the full box and crops pixels; Chrome is fine. Executors denied `rm`/`git rm`: orchestrator deletes on literal relative paths after checking importers. +Apply: any pipeline extraction (Step 13 Supabase provider, Step 14 worker); any "snapshot" design: reuse the live schema minus content before inventing one. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 7db0e309..a812b2b9 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -105,9 +105,9 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [x] 6.1 Phase 0 freeze (8b86b92: 39 goldens, demo fixture, bare v3 PDF, T12/T13; 206 app tests) with current code: demo report fixture, migrated-v2-with-unresolved builder, G3 bare v3 PDF, G1 text goldens (logos absent + present), G2 structural facts/placements/links, T12 HomeRoute + T13 EditorRoute characterisation - [x] 6.2 Phase 1 domain (cdc0943: 154 domain tests, snapshot 171 KB raw on the fixture): sheet-index moved, archive/snapshot (buildSheetSnapshot, assertSnapshot, caps), archive/envelope (schema v1, layered readArchiveDocument, SnapshotRejection), report/rebase (rebaseReportOnSheet), bundle carries asset sha + status/name, tests - [x] 6.3 Phase 2 anatomy (6940926: composeViewSvg + highlightLayer, 130 anatomy tests): render/compose.ts promoted from curation/app-review.ts, highlight on the layer tree, review drawing golden unchanged - - [ ] 6.4 Phase 3 packages/pdf: scaffold (no DOM lib, restricted globals, vitest node, Dockerfile, CI, README), svg/sanitize allowlist + horse.svg zero-removal, render moved, Branding/Rasterizer/exportedAt/safeText/dict, exportReportArchive (T3 both logo modes), readReportArchive (filename-first, layered, attachment_stripped; T4-T6, T8), T1/T7/T9/T10 resvg/T11, xmldom bundle size ≤ 50 KB gz - - [ ] 6.5 Phase 4 app: browserRasterizer, branding.ts, export/import on the engine, rebase on import + draft restore, 2 new messages, old render/attachment/highlight code + pdf.* keys removed, report:compare on engine API, T2/T14/T15, suite migrated 1:1 - - [ ] 6.6 Phase 5 docs + gates: PDF-FORMAT.md real, CLAUDE.md map, WORKSPACE.md rule, DEPLOY.md rollback note, CHANGELOG, BDR-014 note; pnpm check, docker build, verifier + security gates, EVAL; manual validation list + - [x] 6.4 Phase 3 packages/pdf (c179560: 53 engine tests, 36 goldens exact, resvg raster, demo envelope 55 KB / 136 KB stored): scaffold (no DOM lib, restricted globals, vitest node, Dockerfile, CI, README), svg/sanitize allowlist + horse.svg zero-removal, render moved, Branding/Rasterizer/exportedAt/safeText/dict, exportReportArchive (T3 both logo modes), readReportArchive (filename-first, layered, attachment_stripped; T4-T6, T8), T1/T7/T9/T10 resvg/T11, xmldom bundle size ≤ 50 KB gz + - [x] 6.5 Phase 4 app (9bd5173: 222 app tests, archive kept in session, rebase + alerts, legacy PDF modules removed, xmldom ≈ 31 KB gz in the main chunk): browserRasterizer, branding.ts, export/import on the engine, rebase on import + draft restore, 2 new messages, old render/attachment/highlight code + pdf.* keys removed, report:compare on engine API, T2/T14/T15, suite migrated 1:1 + - [ ] 6.6 Phase 5 docs + gates (docs synced: PDF-FORMAT, CLAUDE, README, WORKSPACE, DEPLOY, CHANGELOG; root check 580 tests + build + docker build green; verifier + security gates running): PDF-FORMAT.md real, CLAUDE.md map, WORKSPACE.md rule, DEPLOY.md rollback note, CHANGELOG, BDR-014 note; pnpm check, docker build, verifier + security gates, EVAL; manual validation list - [ ] 6.7 follow-ups recorded for Step 13: catalog asset cap aligned with the archive cap (2 MiB), allowlist sanitiser at upload, app canvas sanitiser (EVAL-011) - [ ] 5 follow-up: allowlist SVG sanitiser before Storage-served assets (Step 13); orphan findings UX (D5) at the report UX step; report:compare residuals (ZodError reason genericised, v3 lines computed once, long template lines); 16 MiB attachment cap without direct test diff --git a/CLAUDE.md b/CLAUDE.md index 005d85b6..b0cea08c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,12 @@ audit log exist; Step 4 added the canonical anatomical sheet model (`packages/do tables `species`, `anatomical_sheets` / `_versions` / `_assets`). Step 5 moved the application onto that model: the editor renders the bundled reference sheet (the curated equine DRAFT, `SHEET_BUNDLE=draft`), writes Report v3 and imports v2 PDFs -through a generated migration map. The Supabase client is still unused by the UI. +through a generated migration map. Step 6 made the PDF an autonomous archive: the +`packages/pdf` engine renders from explicit inputs (report, sheet snapshot, branding, +labels, rasterizer) with no network and no DOM, and the attachment is an envelope v1 +carrying the report, a lean sheet snapshot, the branding and the labels used, so an old +bilan is reproduced identically after any catalog, wording or logo change +(`docs/PDF-FORMAT.md`). The Supabase client is still unused by the UI. MVP species: equine only. Open-source MIT. --- @@ -201,10 +206,11 @@ faunosteo/ ├─ eslint.config.js, index.html, package.json (@faunosteo/app) ├─ tsconfig*.json, vite.config.ts, vitest.config.ts │ (end of apps/app) -├─ packages/domain/ ← @faunosteo/domain (pure, no DOM, zod only) +├─ packages/domain/ ← @faunosteo/domain (pure, no DOM, zod only): anatomical-sheet (document, integrity rules, sheet-index), report (v3, v2 migration, rebase), archive (sheet snapshot, envelope v1, branding, labels, layered reader) │ ├─ src/anatomical-sheet/{schema,validate,create}.ts ← canonical sheet document + integrity rules │ └─ tests/{fixtures/horse-slice.ts,*.test.ts} -├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, pure annotation-layer renderer (`./render`) +├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, pure annotation-layer renderer + view composer (`./render`) +├─ packages/pdf/ ← @faunosteo/pdf: browser-free PDF engine — src/{export,read,text,branding}.ts, attachment/, svg/{parse,sanitize,view}.ts, render/, i18n/; tests reproduce the Step 6 goldens │ ├─ src/legacy/{svg,catalog,regions,ids,report,importer}.ts, src/cli/import-equine.ts │ ├─ src/curation/{schema,targets,fields,ops,rename,apply,types,assets,labels,stats,changelog,review-report,overlay,seed,sources,pipeline}.ts ← changeset → draft │ └─ tests/ ← counts preserved, special cases, determinism, curation ops, golden artifacts @@ -250,19 +256,22 @@ SVG interaction → open_vertebra_picker / open_laterality_picker → pickers → reducers (ensureZone, addSides, syncVertebrae) → toggle / remove_both_sides → updateObservation() in store -PDF export - → exportReportToPdf(report, sheet, { locale }) - → pdf-lib PDFDocument - → embedFonts (Helvetica body + TimesRoman heading — WinAnsi StandardFonts; TTF Inter/Fraunces planned) - → for each observation: addObservationPage (rasterize SVG → PNG) - → addConclusionPage - → attachReportJson (native EmbeddedFiles) - → Uint8Array → browser download +PDF export (app side: apps/app/src/pdf, engine: packages/pdf) + → exportReportToPdf(report, index, { locale }) + → buildSheetSnapshot(index.sheet, report) + loadBranding() (4 public/ files, each may fail alone) + defaultPdfLabels + → exportReportArchive({ report, sheet, branding, labels, locale, rasterizer: browserRasterizer, exportedAt }) + assertSnapshot (caps, integrity, sheet invariant) → fonts (WinAnsi StandardFonts, safeText guard) + → per observation: composeHighlightedViewSvg (xmldom: sanitise allowlist → composeViewSvg highlight) → rasterizer → page + → conclusion page, footer, envelope v1 attached as osteo-report.json, Keywords faunosteo-archive/1 + → { pdf, envelope, warnings } → browser download + → exportFromEnvelope(envelope, …) re-exports an archive from its own snapshot, branding and labels (no sheet) PDF import - → importReportFromPdf(bytes, migrationMap) - → extractReportJson → readReportDocument (v3 as is, v2 migrated, else incompatible_version) - → hydrateReport() → navigate /editor (unresolved zones/findings kept and flagged) + → importReportFromPdf(bytes, migrationMap) → readReportArchive (engine) + → attachment osteo-report* first → layered reading: report (v3 as is, v2 migrated, else incompatible_version), + envelope metadata tolerant, snapshot/branding/labels strict → archive kept or snapshotRejected (closed reason) + → rebaseReportOnSheet(report, index, archivedSnapshot) when the loaded sheet differs (unresolved flags, labels kept) + → hydrateImport({ report, archive }) → one alert (archive_ok / snapshot_rejected / rebased / migrated) → navigate /editor Runtime config → Docker entrypoint writes env.js (window.__APP_CONFIG__) @@ -295,7 +304,7 @@ Database (Supabase) - Get the translate function in any component: `const t = useT()` then `t('common.cancel')` - `src/state/localeStore.ts` holds current `Locale` (`'fr' | 'en'`), persisted to `localStorage` key `osteo:locale`; default: navigator-detected `fr`/`en`, or `'fr'` if no match - Zone and finding names shown in the editor and the PDF come from the sheet document (`{ fr, en }` labels) and from the report's snapshots, not from the dict -- PDF static labels (section headings, metadata) come from the dict via `getDict(locale)` in `exportReportToPdf` +- PDF static labels (section headings, metadata) live in the engine (`packages/pdf/src/i18n`, `defaultPdfLabels`, 25 keys) and are archived in the envelope; the app dicts hold no `pdf.*` key ### Identity strings - NEVER hardcode APP_SITE_NAME, APP_BRAND_NAME, APP_FOOTER_NAME, APP_TAGLINE @@ -322,13 +331,15 @@ Database (Supabase) ### Stores - No direct store mutation outside Zustand actions - No business logic in components — delegate to store actions -- sessionStorage key: osteo:draft (auto-saved on every change, v3; a v2 draft is migrated on restore once the sheet is loaded) +- sessionStorage keys: osteo:draft (auto-saved on every change, v3; a v2 draft is migrated and a stale draft rebased on restore once the sheet is loaded) and osteo:archive (the imported archive envelope, written only on import / new report / reset, never on edits) - localStorage key: osteo:lastPractitioner (practitioner prefill cache) ### PDF - A4 portrait: 595.28 × 841.89 pt - No raw URLs in PDF output — abbreviated citations only -- JSON attachment filename must start with osteo-report; content = Report v3; import accepts v2 (migrated) and v3 +- JSON attachment filename must start with osteo-report; content = report archive envelope v1 (report v3 + sheet snapshot + branding + labels); import accepts bare v2 (migrated), bare v3 and envelope v1; a bad snapshot never loses the report +- The engine (`packages/pdf`) has no DOM lib, no fetch, no Node-only global (lint-enforced); rasterisation is an injected adapter; every SVG it receives is sanitised by allowlist with caps +- Page layout is frozen by the Step 6 goldens: any visible change needs a user decision and a golden regeneration - Fonts are StandardFonts (Helvetica/TimesRoman, WinAnsi encoding) — TTF Inter/Fraunces planned but not yet embedded. Any non-Latin-1 glyph in PDF text must use an ASCII surrogate until the TTF migration lands (e.g. `(!)` instead of `⚠`). ### Anatomical sheet content @@ -417,8 +428,8 @@ Database (Supabase) - Annotation rendering changes require updating docs/ANNOTATION-RENDERING.md first. - Never modify the legacy sources under `supabase/seed/anatomical-sheets/equine/legacy-sources/` — they are the importer's input (the user's historical files). -- Ask before any change to importReportFromPdf, extractReportJson or readAttachedDocument — these handle user data. -- After PDF roundtrip tests fail: check attachment bytes, then Zod validation (v3, or v2 through the migration map), then DecompressionStream inflation. +- Ask before any change to `readReportArchive`, `readArchiveDocument`, `readAttachedDocument` or `rebaseReportOnSheet` — they handle user data; archive readers never drop a schema version (envelope v1, Report v2/v3, sheet document v2). +- After PDF roundtrip tests fail: check attachment bytes, then the layered reader (report first, envelope metadata, snapshot/branding/labels), then DecompressionStream inflation. Goldens under `apps/app/tests/fixtures/goldens/step6` are never regenerated without a user decision. - Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install. - SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test` on the real stack when Docker is available; regenerate types (`pnpm db:types`).