Files
faunosteo/.claude/tasks/contracts/2026-10-11-step-06-phase-4-app.md

5.9 KiB

CONTRACT — step-06 phase 4 app

  • date: 2026-10-11 | flow: ship-feature (executor) | branch: feature/step-06-pdf-archives
  • status: draft (dispatched after phase 3 lands)
  • spec: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II §14 "App session", "Branding in the app", §16 messages, §17 (T12/T13 kept green), Part I §7 T2/T14/T15

REQUEST (IMMUTABLE)

Wire the application onto @faunosteo/pdf: export through the engine with a snapshot, branding and the browser rasterizer; import through the engine with layered reading, kept archive and explicit rebase; new import messages; old PDF code removed; report:compare on the engine read API. No visual change to pages or app layout; alerts follow the existing window.alert pattern.

ACCEPTANCE CRITERIA

  1. apps/app/src/pdf/ contains only: export.ts (exportReportToPdf(report, index, { locale }): Promise<Uint8Array> kept as the route-facing signature, implemented as exportReportArchive({ report, sheet: buildSheetSnapshot(index.sheet, report), branding: await loadBranding(), labels: defaultPdfLabels, locale, rasterizer: browserRasterizer, exportedAt: new Date() }), warnings → console.warn), import.ts (importReportFromPdf(bytes, map) returning the engine's ArchiveReadOutcome; ImportError kinds invalid_pdf | incompatible_version | no_attachment | attachment_stripped mapped 1:1 from ArchiveReadError), browserRasterizer.ts (today's svgToPng.ts adapted to (svg, { widthPx, heightPx }) => Promise<Uint8Array>: the engine computes the size, the adapter sets width/height on the root and draws), branding.ts (loadBranding(): Promise<Branding> per spec §14). render/, attachment.ts, fonts.ts, src/anatomy/drawing.ts's highlight code are deleted; drawing.ts keeps buildViewSvg/parseDrawing/sanitizeSvg for the canvas (unchanged behaviour). CHECK: ls apps/app/src/pdf EXPECT: branding.ts browserRasterizer.ts export.ts import.ts
  2. Store/persistence per spec §14 "App session": archive: ReportArchiveEnvelope | null in ReportStore, hydrateImport({ report, archive }), initReport/reset/hydrateReport clear it, osteo:archive key written only on those actions, restoreDraft(index) rebases a stale draft and restores the archive; ArchivePersistence beside ReportPersistence; tests in state.reportStore.test.ts extended (archive kept across a draft restore, cleared on new report, not rewritten on edits: spy on setItem).
  3. HomeRoute: importReportFromPdf → rebaseReportOnSheet(outcome.report, sheet.index, outcome.archive?.sheetSnapshot ?? null) → hydrateImport → one alert composed per spec §16 (lines: migrated / archive_ok / snapshot_rejected with reason label / rebased with count) → /editor; error mapping adds attachment_stripped. EditorRoute export path unchanged for the user (download name, failure alert). The Phase 0 characterisation tests routes.HomeRoute.import.test.tsx and routes.EditorRoute.export.test.tsx stay green with at most these edits: the mocked outcome objects gain origin/archive fields, and the export call-shape assertion stays (report, index, { locale }).
  4. i18n: keys of spec §16 added to fr.ts and en.ts with the given wording; pdf.* keys removed from both app dicts (the engine owns them; severity.*, lateral.*, footer.* stay, the UI uses them); i18n.keys.test.ts parity green.
  5. scripts/compare-reports.ts + scripts/compare/report.ts: read through readAttachedDocument from @faunosteo/pdf and readArchiveDocument from @faunosteo/domain/archive; an envelope prints one extra header line archive v1 (snapshot kept | snapshot rejected: <reason>) under the same escaping rules; scripts.compare.test.ts green.
  6. New tests: pdf.export.app.test.ts (T2: export the demo fixture through exportReportToPdf with the real bundled sheet, then mutate a cloned LoadedSheet's labels and one geometry, re-export the ENVELOPE through exportFromEnvelope and assert the engine output facts equal the first export, not the mutated sheet; T13 call shape covered by Phase 0), pdf.goldens.test.ts adapted so the app export path reproduces the Phase 0 goldens through the engine (same spies; the rasterizeSvg mock becomes a mock of @/pdf/browserRasterizer), routes.HomeRoute.archive.test.tsx (T15: envelope import with same sha → archive kept in store, archive_ok alert; envelope whose sha differs → rebased alert with count, unresolved flags, labels filled, report.sheet updated; snapshot rejected outcome → snapshot_rejected alert with the reason label; attachment_stripped → its error message), migration.leaves.test.ts kept green (612 leaves through the new path).
  7. Bundle cost: SHEET_BUNDLE=draft corepack pnpm build in apps/app succeeds; report the gzip size of the main JS chunk before (from git stash-free method: build develop in a worktree is NOT allowed; instead read the size printed by vite for the chunk containing xmldom and report the total gz of dist/assets/*.js) and the size of the xmldom portion if vite's output isolates it; ceiling 50 KB gz for xmldom's share, else report.
  8. Green: from the repo root corepack pnpm typecheck && corepack pnpm lint && corepack pnpm test:run && corepack pnpm build; grep -rn "fetch(" apps/app/src/pdf shows only branding.ts. CHECK: cd $HOME/Documents/faunosteo && corepack pnpm test:run 2>&1 | grep -E "Test Files|Tests " | tail -8 EXPECT: all passed

FILE SCOPE

apps/app/src/pdf/, apps/app/src/anatomy/drawing.ts (removal of highlight-only code if any), apps/app/src/app/routes/{HomeRoute,EditorRoute,NewReportRoute}.tsx (minimal), apps/app/src/state/{reportStore,persistence}.ts, apps/app/src/i18n/{fr,en}.ts, apps/app/scripts/, apps/app/package.json (dependency @faunosteo/pdf: workspace:*, drop pdf-lib only if no app code imports it anymore), apps/app/tests/** (adaptations named above; goldens JSON files never edited), CLAUDE.md folder map lines for apps/app/src/pdf (keep docs minimal; Phase 5 owns the docs). Nothing under packages/**.