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

8.0 KiB
Raw Permalink Blame History

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.