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
apps/app/src/pdf/contains only:export.ts(exportReportToPdf(report, index, { locale }): Promise<Uint8Array>kept as the route-facing signature, implemented asexportReportArchive({ 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'sArchiveReadOutcome;ImportErrorkindsinvalid_pdf | incompatible_version | no_attachment | attachment_strippedmapped 1:1 fromArchiveReadError),browserRasterizer.ts(today'ssvgToPng.tsadapted 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.tskeepsbuildViewSvg/parseDrawing/sanitizeSvgfor the canvas (unchanged behaviour). CHECK: ls apps/app/src/pdf EXPECT: branding.ts browserRasterizer.ts export.ts import.ts- Store/persistence per spec §14 "App session":
archive: ReportArchiveEnvelope | nullinReportStore,hydrateImport({ report, archive }),initReport/reset/hydrateReportclear it,osteo:archivekey written only on those actions,restoreDraft(index)rebases a stale draft and restores the archive;ArchivePersistencebesideReportPersistence; tests instate.reportStore.test.tsextended (archive kept across a draft restore, cleared on new report, not rewritten on edits: spy on setItem). 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 addsattachment_stripped.EditorRouteexport path unchanged for the user (download name, failure alert). The Phase 0 characterisation testsroutes.HomeRoute.import.test.tsxandroutes.EditorRoute.export.test.tsxstay green with at most these edits: the mocked outcome objects gainorigin/archivefields, and the export call-shape assertion stays(report, index, { locale }).- 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.tsparity green. scripts/compare-reports.ts+scripts/compare/report.ts: read throughreadAttachedDocumentfrom@faunosteo/pdfandreadArchiveDocumentfrom@faunosteo/domain/archive; an envelope prints one extra header linearchive v1 (snapshot kept | snapshot rejected: <reason>)under the same escaping rules;scripts.compare.test.tsgreen.- New tests:
pdf.export.app.test.ts(T2: export the demo fixture throughexportReportToPdfwith the real bundled sheet, then mutate a cloned LoadedSheet's labels and one geometry, re-export the ENVELOPE throughexportFromEnvelopeand assert the engine output facts equal the first export, not the mutated sheet; T13 call shape covered by Phase 0),pdf.goldens.test.tsadapted so the app export path reproduces the Phase 0 goldens through the engine (same spies; therasterizeSvgmock 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.sheetupdated; snapshot rejected outcome → snapshot_rejected alert with the reason label;attachment_stripped→ its error message),migration.leaves.test.tskept green (612 leaves through the new path). - Bundle cost:
SHEET_BUNDLE=draft corepack pnpm buildin apps/app succeeds; report the gzip size of the main JS chunk before (fromgit 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. - Green: from the repo root
corepack pnpm typecheck && corepack pnpm lint && corepack pnpm test:run && corepack pnpm build;grep -rn "fetch(" apps/app/src/pdfshows onlybranding.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/**.