docs: CLAUDE.md on the Step 6 pipeline (architecture, conventions, folder map); TODO 6.4-6.5; LRN-046
This commit is contained in:
1 parent
9bd5173a9c
commit
83115b484d
3 files changed
+40
-22
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`).
|
||||
|
||||
Reference in new issue
Block a user