Files
faunosteo/.claude/tasks/contracts/2026-10-11-step-06-phase-3-engine.md

30 lines
8.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CONTRACT — step-06 phase 3 engine
- date: 2026-10-11 | flow: ship-feature (executor) | branch: feature/step-06-pdf-archives
- status: active (phases 1 and 2 landed)
- spec: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II §13 (packages/pdf block), §14 (Export, Label policy, View SVG, Read), §15 (caps, sanitiser, text), §17 (goldens the engine must reproduce), §3.3
## REQUEST (IMMUTABLE)
Create `packages/pdf` (`@faunosteo/pdf`): the browser-free PDF engine that exports a report archive from explicit inputs (report, sheet snapshot, branding, labels, locale, rasterizer, exportedAt) and reads an archive back (layered reading). Render code moves from `apps/app/src/pdf` with its behaviour frozen by the Phase 0 goldens. The app is NOT wired in this phase (Phase 4); `apps/app/src` is not modified.
## ACCEPTANCE CRITERIA
1. Package scaffold: `packages/pdf/{package.json,tsconfig.json,vitest.config.ts,eslint.config.js,src/,tests/}` following packages/domain conventions; dependencies `pdf-lib ^1.17.1`, `@pdf-lib/standard-fonts ^1.0.0` (for `Encodings.WinAnsi`), `@faunosteo/domain workspace:*`, `@faunosteo/anatomy workspace:*`, `@xmldom/xmldom ^0.9.8`; devDependencies as domain plus `@resvg/resvg-js` (latest 2.x) and `@pdf-lib/upng ^1.0.1` (PNG decode in tests); tsconfig `lib: ["ES2022"]`, `types: ["node","vitest/globals"]`; eslint on `src/**`: `no-restricted-globals` for fetch, window, document, Image, DOMParser, XMLSerializer, navigator, Buffer, process, require and `no-restricted-imports` for patterns `@/*`, `react*`, `node:*`; vitest `environment: 'node'`. Dockerfile copies `packages/pdf/package.json`; `packages/README.md` row updated.
CHECK: cd packages/pdf && corepack pnpm typecheck && corepack pnpm lint && echo ok
EXPECT: ok
2. Public API of `packages/pdf/src/index.ts` exactly spec §13: `exportReportArchive`, `exportFromEnvelope`, `readReportArchive`, `readAttachedDocument`, `ArchiveReadError` (kinds invalid_pdf | no_attachment | attachment_stripped | incompatible_version), `ArchiveExportError` (kinds snapshot_invalid | snapshot_too_large | sheet_mismatch | too_many_pages), `Rasterizer`, `ExportInput`, `ExportResult`, `ExportWarning`, `PdfLocale`, `defaultPdfLabels`, `PDF_KEYWORD`, `MAX_PDF_BYTES`, `MAX_ATTACHMENT_BYTES`, plus `composeHighlightedViewSvg(sheet: SheetSnapshot, viewId, observation): string` for tests and the app.
3. Export behaviour = spec §14 "Export" steps 1-10 and "Label policy"; branding images: `kind 'png'` → base64 decoded with `atob` → `embedPng`; `kind 'svg'` → sanitised + rasterised at width 1200 (height from its viewBox, same clamp) → `embedPng`; each slot fails alone (`logo_failed` warning); view raster failure → page without image + `view_raster_failed`; parallel rasterisation, sequential embedding in view order; `exportedAt` drives every date; `setKeywords([PDF_KEYWORD])`; envelope attached pretty-printed as `osteo-report.json`, description `Faunosteo report archive v1`.
4. Goldens (T3): `tests/goldens.test.ts` reproduces every Phase 0 golden under `apps/app/tests/fixtures/goldens/step6/` for the three reports (v2full migrated through the draft map, demo, v2unresolved rebuilt with the same recipe as Phase 0 — reuse the recipe by reading `apps/app/tests/helpers/legacyLeaves.ts` logic, copy what you need into `tests/helpers/`), two locales, two logo modes: text entries (page, text, x, y, size, font) identical; images identical; links identical (Phase 0 recorded images and links PER LOCALE: `images.<report>.<locale>.<logos>.json`, `links.<report>.<locale>.<logos>.json`, because the footer centres the powered-by block on the label width); views facts identical except `titles` and `dataAttributes` (hidden markers are absent in the engine and the layer `<g>` loses its `data-layer`/`data-view-id`: assert `titles` ≥ highlighted count and `dataAttributes === 0` instead of the golden's 2). Logo modes: `nologos` = Branding with every logo null and credits with fallback texts, fake rasterizer returning the 1×1 PNG; `logos` = Branding built from the real `apps/app/public` files (PNG base64, Paws SVG), fake rasterizer returning the 2×1 PNG for views AND for the partner SVG (same constants and the same single stub as Phase 0, see `apps/app/tests/helpers/goldens.ts`). Compose through `composeViewSvg` from `@faunosteo/anatomy/render` (generic `root: ComposeElement`, xmldom `Element` satisfies it) with `highlight: { annotationIds, halo: view.kind === 'main' }`. Any mismatch is a visible change: do not "fix" the golden; report it.
CHECK: cd packages/pdf && corepack pnpm vitest run tests/goldens.test.ts 2>&1 | tail -3
EXPECT: Tests .* passed
5. T1 no-sheet re-export (`tests/reexport.test.ts`): export demo from a snapshot built with `buildSheetSnapshot` on the draft loaded from `supabase/seed/anatomical-sheets/equine/draft/` → `readReportArchive` → `exportFromEnvelope` → identical text/images/views facts; envelope deep-equal minus `exportedAt`; the test file imports nothing that knows the draft after the first export (the second export receives only the envelope).
6. Read (`tests/read.test.ts`, T4 T5 T6): roundtrip envelope → `readReportArchive` → `archive` deep-equals the exported envelope, `origin 'envelope_v1'`; `apps/app/tests/fixtures/report-v2.full.pdf` and `report-v2.minimal.pdf` → `'v2'`, migrated, then re-export → import again equals; the 612-leaf v2 report (recipe from legacyLeaves) → 29 unresolved findings kept through export/import; `report-v3.bare.pdf` → `'bare_v3'`, `archive null`; envelope v2 wrapper → report kept + `snapshotRejected 'unsupported_envelope'`; envelope v1 with report v4 → `incompatible_version` foundVersion 4; bare `version: 7` → 7; a PDF with `Keywords` containing `faunosteo-archive` and no attachment → `attachment_stripped`; a foreign PDF → `no_attachment`; the Filespec named `osteo-report.json` is chosen over an earlier unrelated `EmbeddedFile` in a crafted PDF; > 50 MiB → `invalid_pdf`.
7. Security (`tests/security.test.ts`, T8): 5 assets, a 3 MiB asset, depth 9, 1,025 annotations, a view chain cycle, a dangling `svg_asset_id`, `sheet_mismatch` → report imported and `snapshotRejected` with the right reason; hostile SVG assets (`<script>`, `onload`, `javascript:` href, external `<image>`, `<!ENTITY>`, `<style>` with `url(http…)`, 257 `<use>`, root `viewBox="0 0 1 100000"`) → removed / refused / clamped as spec §15, the export still succeeds for the removable ones with the hostile parts gone, and `assertSnapshot` refuses the oversized ones at export with a typed error and no file; `__proto__` ids harmless; 24 MB inflate bomb → null (move the existing test); `horse.svg` and `Paws_in_harmony.svg` sanitise with `removed: []` and a serialisation byte-identical to the parsed input.
8. Text (`tests/text.test.ts`, T9): `safeText` keeps en dash, em dash, accented letters, `•`, `·`; replaces `⚠`, `→`, an emoji by `?`; strips `\t`, U+2028, ESC; `wrapLines` and every drawText go through it (a report with `⚠` in a comment exports without throwing); `formatDate` returns a non-ISO input unchanged.
9. Raster (`tests/raster.test.ts`, T10, resvg): a real `Rasterizer` built on `@resvg/resvg-js` (`fitTo width`) renders the demo report's main and head highlighted views: PNG width = 1200, height = requested ±1, pixels within ±24 of `#b85a3f` present, non-white ratio in [0.01, 0.9]; a rasterizer that throws yields a PDF whose page has no image and one `view_raster_failed` warning.
10. Size (T7): demo envelope attachment stored bytes (the EmbeddedFile stream `contents.length` found through `enumerateIndirectObjects`) < 250,000; the test prints stored and raw sizes for `nologos` and `logos` brandings.
11. Everything green: `corepack pnpm typecheck && corepack pnpm lint && corepack pnpm test:run` in packages/pdf, and `corepack pnpm -r typecheck` at the root; `apps/app/src` untouched.
CHECK: git -C $HOME/Documents/faunosteo status --short apps/app/src | wc -l
EXPECT: 0
## FILE SCOPE
packages/pdf/** (new), Dockerfile (one COPY line), packages/README.md (one row), pnpm-lock.yaml (install). Nothing under apps/app/src, packages/domain, packages/anatomy.