Files
faunosteo/docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md

60 KiB
Raw Permalink Blame History

Step 6 — Autonomous PDF archives: analysis and plan

Status 2026-10-10: analysis and plan, challenged on three lenses (correctness, robustness, simplicity: GO WITH FIXES each, fixes folded in below), awaiting user validation. No implementation.

Scope authorised by the user on 2026-10-10: the PDF import system, the attachment and the modules around them may change (this lifts the CLAUDE.md "ask before" gate for this step). Goal: a Faunosteo PDF must stay readable and re-renderable when the anatomical sheet it was built on no longer exists in the catalog. Business behaviour of the PDF is preserved; no graphic redesign.

Sources: three read-only analyses of the current code (PDF pipeline, data model, app wiring and tests), size measurements on the equine draft, three plan challenges. Facts carry a path:line reference; measurements were taken on develop @ 072d761.


1. What the current pipeline depends on

1.1 Inputs read at export time

exportReportToPdf(report, sheet: SheetIndex, { locale }) (apps/app/src/pdf/export.ts:27) reads two sources.

From the live sheet, through the SheetIndex built from the bundled draft:

Data Used for Where
annotation.name {fr,en} (trigger: the opened view's name) zone text render/observationPage.ts:355-356, services/sheetIndex.ts:108-111
finding_zones[].name, looked up by id whatever the unresolved flag finding group heading observationPage.ts:383-390
view.kind, view.name "general" label, halo, upper-cased detail caption :329-340
view.view_box, view.svg_asset_id, parent chain crop and asset choice anatomy/drawing.ts:61-85
asset SVG text the drawing drawing.ts:52
document.views (names title the nameless triggers), categories[].color, every annotation of the view marker layer, then highlight packages/anatomy/src/render/layer.ts:114-255

From the report: identities, dates, zones (annotationId, viewId, side, vertebrae), finding leaf snapshots (always the text source, BDR-010) and the vet flag (!) (observationPage.ts:413-414), free text, severity, conclusion. Zone snapshots are a fallback only (:357-361).

From the i18n dict: pdf.*, severity.*, lateral.*, footer.powered_by, footer.in_partnership.

Never read: the finding tree nodes (nodeAt), vertebral_config, report.sheet, finding.path.

1.2 Browser and network dependencies

Dependency Where Behind an interface
fetch of 4 logos on root-relative URLs render/logo.ts:6, export.ts:63 no
DOMParser, document.createElementNS/importNode drawing.ts:37,78,88,95 no
querySelectorAll, el.remove(), XMLSerializer observationPage.ts:159-229 no
DOMParser, Blob, URL.createObjectURL, Image, canvas, toBlob/toDataURL, atob svgToPng.ts:17-101 no
DecompressionStream (read side, guarded) attachment.ts:127 no
new Date() (non-deterministic bytes) export.ts:38, attachment.ts:35 no

Hard-coded branding: 4 logo paths under public/, link URLs at header.ts:63 and footer.ts:53,92,107,116, attachment description, highlight colour #b85a3f. No useConfig/appConfig on the PDF path. Logos degrade one by one (own try/catch, export.ts:47-68); a single view raster failure sinks the whole export (Promise.all, observationPage.ts:334).

Node 24 provides CompressionStream, DecompressionStream, TextEncoder, crypto.subtle, Blob, structuredClone; it has no DOMParser, XMLSerializer, Image or document. pdf-lib 1.17.1 is DOM-free and already runs in Node for pnpm report:compare. @faunosteo/anatomy/render is DOM-free (LayerElement tree + serializeLayer), and the curation pipeline already composes a view drawing with @xmldom/xmldom in Node (renderAppReviewDrawing, packages/anatomy/src/curation/app-review.ts:20-36: parse asset, set viewBox, drop width/height, append the layer, serialise).

1.3 The attachment today

  • One embedded file osteo-report.json, the bare Report v3 (pretty JSON), Flate-compressed by pdf-lib itself (FileEmbedder → context.flateStream, pako). Full fixture: 3,947 B raw, 1,177 B stored.
  • Carries sheet {sheetId, versionId|null, documentSha256} and nothing else of the sheet. No locale, no labels beyond the zone and leaf snapshots.
  • Read path: importReportFromPdf (50 MiB cap) → readAttachedDocument (16 MiB cap, raw object traversal: the getAttachments branch never runs on pdf-lib 1.17.1, so the filename is never checked and the first EmbeddedFile wins) → readReportDocument (v3 parsed, v2 migrated with the bundled map, else incompatible_version). Any other failure becomes no_attachment ("not generated by Faunosteo").
  • Nothing compares report.sheet with the loaded sheet, on import or on export. Every pnpm import:equine run changes the draft's documentSha256.

1.4 What the report already preserves

Report v3 (packages/domain/src/report/v3.ts) embeds: zone names FR/EN (optional), leaf finding names FR/EN (required), the vet flag, vertebra codes and indexes, the side, unresolved: true on items the v2 migration could not place (their legacy ids are kept; the 29 unresolved legacy leaves all sit in zones that still exist: frontal, sphenoid, ssb). It does not embed finding-zone names, ancestor and category names, region names, view names, colours, geometry, view boxes or assets.


2. Snapshot: exact content

2.1 Requirement

Re-read and re-render an old bilan (FR and EN, text and drawings) without the current catalog, and keep every historical datum including unresolved items. A sheet id or a dependency on the current catalog is not enough.

2.2 Shape: a lean sheet document, not a new schema

The snapshot has the shape the renderer and the sheet index already consume (LoadedSheet minus the migration map): { status, ref, document, assets }. document is a valid AnatomicalSheetDocument (schema v2, strict, unchanged) with the bibliography emptied and the finding trees pruned to what the report uses. So renderAnnotationLayer, buildSheetIndex, pickLabel and validateSheetDocument apply to it with no change, and the full set of sheet integrity rules (unique ids, acyclic view chain, one main view, categories and regions present) protects it.

Part Content Why
ref sheet_id, version_id, document_sha256, schema_version, species_id, name {fr,en}, status provenance (document_sha256 is the full catalog document's hash, kept as a pointer, not as a hash of the snapshot)
document.views all views captions, crops, trigger titles (a nameless trigger is titled from the view it opens, layer.ts:240-248)
document.annotations all annotations, review_status kept (schema default) geometry, colours, zone names, anatomical relations (finding_zone_id, vertebral_region_code, opens_view_id, laterality)
document.categories, vertebral_config all marker colours, region names and counts
document.finding_zones every zone {id, name}; for a zone referenced by any finding of the report, resolved or unresolved, its categories pruned to the referenced paths ({id, kind, name} and every node on the path {id, name, requires_vet_referral}, description: {}, reference_ids: []); other zones keep categories: [] group headings by id; the labels of every ancestor on a used path are preserved (+4 KB raw, +0.4 KB stored over empty trees)
document.references [] bibliography is not bilan data (15 KB)
document.name, description, scope_disclaimer, attribution kept as is (1.4 KB) sheet identity and legal scope of the historical sheet
assets [{ svg_asset_id, sha256, svg }] for every asset reachable from a view the drawing; sha256 is the catalog's content address copied from the seed manifest (assets.json), carried by the bundle from now on, a provenance pointer and not a tamper check

The SVG text goes inline as a JSON string (SVG is UTF-8 text: no base64 penalty, one attachment, one size cap, one parse). Separate embedded files were rejected: the raw-object reader takes the first EmbeddedFile, and several attachments multiply the stripping risk.

Rejected alternative: a dedicated SheetSnapshotSchema. It would force a rewrite of every sheet lookup in the render path, leave renderAnnotationLayer without a valid input, and lose the sheet integrity rules.

2.3 Envelope (attachment v1)

{
  "format": "faunosteo-report-archive",
  "envelope_version": 1,
  "exported_at": "2026-10-10T18:00:00.000Z",
  "locale": "fr",
  "report": { "version": 3, "...": "Report v3 unchanged" },
  "sheet_snapshot": {
    "status": "draft",
    "ref": { "sheet_id": "…", "version_id": null, "document_sha256": "…", "schema_version": 2, "species_id": "equine", "name": { "fr": "…", "en": "…" } },
    "document": { "schema_version": 2, "...": "lean AnatomicalSheetDocument" },
    "assets": [ { "svg_asset_id": "…", "sha256": "…", "svg": "<svg …>" } ]
  }
}

Report v3 is wrapped, not changed: no report version bump. Invariant written and checked: report.sheet.documentSha256 === sheet_snapshot.ref.document_sha256 (see §3.5 for how the app keeps it true). Filename stays osteo-report.json (CLAUDE.md); description becomes Faunosteo report archive v1; the PDF Info dictionary gains Keywords: faunosteo-archive/1 so a PDF whose attachment was stripped by a viewer can still be recognised. Pretty-printed as today (an extracted archive stays human-readable). locale and exported_at make the attachment differ between locale variants: BDR-014's "byte-identical JSON" note is superseded on that point, the report inside stays identical.

2.4 Measured sizes (equine draft, pretty JSON, deflate 6 ≈ pdf-lib Flate)

Envelope Raw Stored
3-observation fixture, lean document + SVG 172 KB 51 KB
Worst case 27 zones × 3 findings, both views 228 KB 54 KB
Lean document alone, 3 observations 29 KB 4 KB
Full document (bibliography included) + SVG, alternative 464 KB 79 KB
SVG alone, as a JSON string 138 KB 47 KB

The drawing is 90% of the stored size. The 250 KB target holds on the raw size (worst case 228 KB) and with a 4× margin on the stored size. Data conservation wins over size: nothing in §2.2 is dropped to fit.


3. Target architecture

3.1 One sheet input for the engine: the snapshot

app export       : LoadedSheet + Report ──buildSheetSnapshot()──▶ SheetSnapshot ─┐
archive re-export: envelope.sheet_snapshot ─────────────────────────────────────┤
                                                                                ▼
exportReportArchive({ report, sheet, branding, locale, rasterizer, exportedAt }) ─▶ { pdf, warnings }

The engine builds its SheetIndex from the snapshot and never sees a live sheet. The app builds the snapshot from the loaded sheet at export; an archive re-export passes envelope.sheet_snapshot as is. The attachment embeds exactly what the engine consumed.

Label policy, identical to today's output:

  • zone name = snapshot annotation name by id (trigger: the opened view's name), else the report's zone snapshot in the requested locale, else the id; unresolved is never consulted;
  • finding group heading = snapshot finding-zone name by id, else the id upper-cased (as today);
  • finding text and the (!) marker always come from the report (BDR-010);
  • views: unique view ids of the observation present in the snapshot, main first; an unknown view prints no image, as today.

3.2 Packages and moved code

Package Content
packages/domain archive/envelope.ts: ReportArchiveEnvelopeSchema (v1, metadata tolerant to unknown keys, report and sheet_snapshot at fixed keys), snapshot caps, readArchiveDocument(data, map) with layered reading (§4), ArchiveReadError; archive/snapshot.ts: buildSheetSnapshot(loadedSheet, report) (pure: prune trees, empty references, pick assets), assertSnapshot(snapshot) (schema, caps, validateSheetDocument with no error, every view reaches an asset present in assets); anatomical-sheet/sheet-index.ts: buildSheetIndex, pickLabel, isObservable moved from apps/app/src/services/sheetIndex.ts (the app re-exports them); report/rebase.ts: rebaseReportOnSheet(report, index, archivedSnapshot?) (§3.5)
packages/anatomy render/compose.ts: composeViewSvg({ assetRoot, document, viewId, highlight }) promoted from curation/app-review.ts (xmldom), highlight applied on the LayerElement tree before it becomes DOM (fill #b85a3f, opacity 0.85, osteo-halo filter on the main view, unselected markers dropped, no data-*, <title> kept); the curation review drawing calls it with no highlight
packages/pdf (new, @faunosteo/pdf) the engine: exportReportArchive, readReportArchive; render/* moved as is (metadata, fonts, pages, header, footer, text, link annotations, constants); svg/sanitize.ts (allowlist, xmldom, §6); svg/view.ts (parse → sanitise → compose → serialise, raster size from the view box); attachment/{write,read,inflate}.ts; text.ts (safeText, §6); dates.ts (formatDate copy, never throws on a free string); i18n/{fr,en}.ts (verbatim copies of today's pdf.*, severity.*, lateral.*, footer.powered_by, footer.in_partnership); types Branding, Rasterizer, ExportInput, ExportResult. tsconfig: lib: ["ES2022"], types: ["node"]; ESLint on src/**: no-restricted-globals (fetch, window, document, Image, DOMParser, XMLSerializer, navigator, Buffer, process, require) and no-restricted-imports (@/*, react, node:*); vitest environment: node
apps/app/src/pdf (shrinks) export.ts (snapshot + branding + browser rasterizer → engine; download unchanged), import.ts (engine read → ImportError kinds, BDR-015), browserRasterizer.ts (today's svgToPng), branding.ts
apps/app/scripts report:compare moved onto the engine read API (unchanged options)

Dependencies added:

  • @xmldom/xmldom 0.9.x as a runtime dependency of packages/pdf and packages/anatomy (compose.ts), pinned: parse, sanitise, compose and serialise without a browser, in the browser too (one code path). Already in the workspace as a devDependency of packages/anatomy (0.9.12). Unminified 276 KB / 71 KB gzipped, 43 KB of which is the HTML entity table; expected 35–45 KB gzipped in the app bundle, measured in Phase 3 with a stated ceiling of 50 KB, else the browser keeps the native DOM for composition. Parsed with an onError that throws on error and fatalError and never logs raw input. Watched by pnpm audit --prod.
  • @resvg/resvg-js as a devDependency of packages/pdf (D6): real rasterisation in Node for one end-to-end test. Native prebuilt binaries (lockfile must carry linux-x64-musl for the Docker builder stage, where the unfiltered install pulls it; the runtime image is nginx and unaffected).

No text-extraction dependency: drawn-text goldens reuse the PDFPage.prototype.drawText spy pattern (LRN-033).

3.3 Browser-free guarantees

  1. Compile-time: packages/pdf has no DOM lib, so document, Image, DOMParser do not type-check.
  2. Lint-time: restricted globals and imports on src/** (tests may read fixtures with node:fs).
  3. Test-time: the engine suite runs under vitest environment: node with no Vite sheet plugin, so nothing can reach the bundled sheet.
  4. Rasterisation is an adapter: type Rasterizer = (svg: string, size: { widthPx: number; heightPx: number }) => Promise<Uint8Array>. The engine computes the size (width 1200 px, height from the view box, aspect clamped to [0.2, 2.0]) and degrades per view: a failed raster gives a page without that image and a warnings entry, never a failed export. Logos degrade one by one as today.

3.4 Branding as explicit input

interface Credit { logoPng: Uint8Array | null; url: string; fallbackText: string }
interface Branding {
  siteUrl: string;
  headerLogoPng: Uint8Array | null;
  footerLogoPng: Uint8Array | null;
  poweredBy: Credit | null;   // today: ZenQuality, 70×16 pt
  partner: Credit | null;     // today: Paws in Harmony, aspect-derived width
}

The app assembles it once per export in branding.ts: PNG bytes from bundled assets (?url import + fetch inside the app, allowed there), the Paws SVG rasterised with the browser rasterizer before the engine runs, URLs and fallback handles as app constants (none of them is an identity string of ConfigProvider; the PDF prints no site name). Branding is not embedded in the archive: brand assets are the publisher's, not bilan data, and a re-export uses the branding it is given.

3.5 Import flow and the sheet invariant

readReportArchive(pdfBytes, migrationMap) returns { report, snapshot | null, origin: 'envelope_v1' | 'bare_v3' | 'v2', migrated, unresolvedZones, unresolvedFindings, snapshotRejected?: SnapshotRejection } with SnapshotRejection = 'unsupported_envelope' | 'schema' | 'caps' | 'integrity' | 'sheet_mismatch' (a closed enum: no received value is echoed). Attachment selection: the Filespec whose /F starts with osteo-report first, then the first EmbeddedFile (today's behaviour as fallback); the dead getAttachments branch is removed. A PDF stamped faunosteo-archive/1 with no attachment gives the new ImportError kind attachment_stripped (message: the viewer or optimiser removed the data; re-export from the original).

Invariant and rebase. The editor always works on the loaded sheet. When a report arrives whose report.sheet.documentSha256 differs from the loaded ref (import of any archive, or a session draft restored after the bundle changed), the app calls rebaseReportOnSheet(report, index, archivedSnapshot?):

  • a zone whose annotationId is absent from the loaded sheet, or whose viewId is unknown, gets unresolved: true; its label snapshots are filled from the archived snapshot when present (labels survive the rebase);
  • a finding whose (findingZoneId, path) has no node in the loaded sheet gets unresolved: true (same semantics as the v2 migration);
  • report.sheet becomes the loaded ref; counts are returned and the existing partial-import alert pattern shows them (new key home.import.rebased, wording to validate: "Bilan établi sur une autre version de la fiche. Éléments non retrouvés : {count} (conservés avec leurs libellés).").

Export then refuses when the invariant does not hold (ArchiveExportError 'sheet_mismatch'), which cannot happen through the app once rebase runs on every entry path. An envelope whose two references disagree is imported with snapshotRejected: 'sheet_mismatch'.

The imported snapshot is not kept in the session (D8): once rebased, the report lives on the current sheet, the original PDF remains the historical rendering, and autonomy is exercised by the engine API and the tests.


4. v2 / v3 archive compatibility

Layered reading, so the report is never lost because of its wrapper:

  1. Locate the report: data.report when data.envelope_version is numeric, else data itself (bare).
  2. Parse the report with readReportDocument (v3 parsed, v2 migrated with the bundled map, any other version → incompatible_version with the report version found). foundVersion always names a report version, so the existing UI message stays true.
  3. Parse the envelope metadata tolerantly (unknown keys ignored within v1). envelope_version other than 1 → snapshotRejected: 'unsupported_envelope', report kept. Then parse sheet_snapshot strictly (document schema v2, caps, integrity, assets reachable, sheet_mismatch); any failure → snapshotRejected with its reason, report kept.
Archive Produced by Import Re-export
v2 bare report app before Step 5 migrated with the map; unresolved items flagged, snapshots and legacy ids kept; then rebased (no-op when the map's sheet is the loaded one) envelope v1 on the current sheet snapshot; unresolved items print from their snapshots
v3 bare report Step 5 develop parsed, snapshot: null, rebased if the draft changed since as above
envelope v1 Step 6 report parsed first, snapshot validated or rejected with a reason, rebased if the sheet changed from the embedded snapshot, no sheet needed
envelope v≥2 future report imported if its version is known, snapshotRejected: 'unsupported_envelope' —
report v≠2,3 future incompatible_version with that version —

Durability rule: archive readers never drop a schema version. Sheet document schema v2 stays readable in packages/domain for as long as envelope v1 archives exist, exactly as Report v2 stays readable today. Forward rule: additive optional fields keep envelope_version: 1 (readers ignore unknown metadata keys); a breaking change bumps it and the reader keeps every older version. A rollback to a pre-Step-6 app reads an envelope as no_attachment; DEPLOY.md records that limit.

A v2 archive has no legacy sheet snapshot. Its own pages are the historical rendering; the attachment serves data recovery. Building a "legacy snapshot" from legacy-import/ for a faithful re-render of v2 bilans is possible (the baseline document and the two legacy SVGs are in the repo) but not proposed: no external users, BDR-038 rejected v3→v2 work, and the printed PDF already holds the picture. D4 covers keeping the original v2 JSON.

Fixtures: the two frozen v2 PDFs stay; Phase 0 freezes, with the current code (LRN-043): a v3 bare golden PDF, a demo report report-v3.demo.json (6 observations: main and head views, vertebrae, bilateral sides, a vet-referral leaf, a leaf label with an en dash, free text, next appointment) and a migrated v2 report with unresolved items (sphenoid / ssb leaves reached only through unresolved paths).


5. Re-export without current resources

exportReportArchive({ report: envelope.report, sheet: envelope.sheet_snapshot, branding, locale, rasterizer, exportedAt }) is the whole answer: no sheet provider, no Vite, no browser, no network. The labels, drawings, colours, crops and relations come from the snapshot; the finding texts from the report; the only external inputs are the branding and the locale. Test T1 (§7) performs exactly this call in a Node environment where no sheet exists. A future server worker runs the same call.

An operator CLI (report:reexport) is not planned in this step (D12): the test proves the property, and a CLI is a public command name plus a file writer over untrusted content (output names must derive from the input file name, wx open, LRN-044 escaping, resvg under memory and time limits).


6. Size and security limits

Write side (new): buildSheetSnapshot output goes through assertSnapshot (schema, caps, integrity, assets present, sanitiser acceptance of every asset, sheet invariant) and the serialised envelope must stay under the 16 MiB attachment cap; otherwise the export fails with a typed ArchiveExportError (snapshot_invalid | snapshot_too_large | sheet_mismatch | too_many_pages) and an alert, never a file that cannot be read back. The equine draft is 60× under every cap. Step 13 must align the catalog's asset cap with the archive cap (BDR-032 allows 20 MiB assets today).

Caps (checked on both sides, Zod and counters):

Item Cap
PDF file 50 MiB (existing)
attachment, raw and inflated 16 MiB (existing, bomb guard)
assets ≤ 4 per snapshot, ≤ 2 MiB each, ≤ 6 MiB total
document ≤ 64 views, ≤ 1,024 annotations, ≤ 8,192 finding nodes, depth ≤ 8 (pre-checked before the recursive schema), labels ≤ 512 chars
report at export ≤ 500 observations, ≤ 8 views per observation (too_many_pages)
sanitiser ≤ 20,000 elements, nesting ≤ 64, ≤ 256 <use>, filter stdDeviation ≤ 50
raster width 1200 px, aspect clamped to [0.2, 2.0] (an untrusted root viewBox cannot request a 120-million-pixel canvas)

SVG sanitiser (packages/pdf/src/svg/sanitize.ts, xmldom, used at export on the bundled asset and at re-export on the archived one; the app canvas is out of scope, EVAL-011 keeps it for Step 13):

  • the text is refused if it contains <!DOCTYPE or <!ENTITY;
  • element allowlist, enumerated from the real inventory of horse.svg plus structural needs: svg g path circle ellipse rect line polyline polygon defs linearGradient radialGradient stop filter feGaussianBlur feMerge feMergeNode feOffset feFlood feComposite feBlend feColorMatrix clipPath mask title desc switch use; no style, script, image, a, foreignObject, text, feImage, feTurbulence, feConvolveMatrix;
  • attribute allowlist from the same inventory: id, geometry, presentation (fill stroke* opacity fill-opacity fill-rule transform style), gradient and filter attributes (gradientUnits gradientTransform offset stop-color stop-opacity in in2 result stdDeviation color-interpolation-filters x y width height), viewBox, xmlns*, systemLanguage (the <switch>), font-*; no on*; href/xlink:href and url(…) values must be #fragment; style attributes may not contain url( other than #, expression( or @import;
  • returns the list of removals; the engine logs nothing from it and the test on horse.svg asserts an empty list and a byte-identical serialisation.

Other guards: strict document schema, Object.hasOwn on records, depth pre-check, no new PII in the envelope (export date, locale). WinAnsi: one text ingress safeText() used by measurement and drawing, testing each code point with Encodings.WinAnsi.canEncodeUnicodeCodePoint (en and em dashes are encodable and must survive), replacing the rest by ? and stripping control characters; a canary test covers ⚠, →, an emoji, \t, U+2028 (restores the lost EVAL-003 test). formatDate never throws: a non YYYY-MM-DD string is printed as is.


7. Tests that prove autonomy

Phase 0 goldens and characterisation tests, frozen with the current code before any change:

  • G1 drawn-text sequence per page, FR and EN, for: the v2 full fixture, the demo report, the migrated v2 report with unresolved items. Two harness modes: logos absent (fetch 404, as today) and logos present (fetch stub returning the real PNG bytes from public/, Paws raster stubbed).
  • G2 per view, structural: viewBox, highlighted ids with fill/fill-opacity/filter, hidden marker count, halo filter on the main view only, no data-* left; plus image placements (page, x, y, w, h) and link annotations (page, Rect, URI).
  • G3 report-v3.bare.pdf exported by Step 5 code (import fixture only).
  • T12 HomeRoute import: v2 alert with count, error kinds to messages, navigation. T13 EditorRoute export: call arguments, download name. Both written now on the current routes and kept green unchanged.

Engine (packages/pdf, node environment):

  • T1 No-sheet re-export: export the demo report through the app path → read the envelope → exportReportArchive from the envelope alone → same G1 text, same G2 facts, same envelope minus exported_at (the written snapshot is assertSnapshot's parsed output, so key order is stable).
  • T3 G1/G2 equality between the new engine and the Phase 0 goldens in both logo modes: proof of "no visible change".
  • T4 roundtrip envelope → import → toEqual report and snapshot.
  • T5 v2 fixtures import (29 unresolved on the 612-leaf report, zones [] everywhere, so an empty-views observation must export) → re-export → import again equals; G3 imports with snapshot: null.
  • T6 versions: envelope v2 with report v3 → report imported, snapshotRejected: 'unsupported_envelope'; envelope v1 with report v4 → incompatible_version 4; bare v7 → incompatible_version 7.
  • T7 size: demo envelope stored < 250 KB, raw size printed.
  • T8 security: 5 assets, a 3 MiB asset, depth 9, 1,025 annotations, a view chain cycle, a dangling svg_asset_id, sheet_mismatch → the report imports and snapshotRejected names the reason; hostile SVG (<script>, onload, javascript: href, external <image>, <!ENTITY>, <style> with url(http…), 257 <use>, a root viewBox of 0 0 1 100000) stripped, refused or clamped; __proto__ ids; 24 MB inflate bomb (existing); export-side: a snapshot over caps fails the export with a typed error and no file.
  • T9 WinAnsi canary (§6) on labels, user text, branding fallback text.
  • T10 real raster (resvg) on the demo report: PNG dimensions follow the 1200 px rule and the clamp, highlight colour present, non-white ratio in range for main and head views; a raster failure yields a page without image and one warning.
  • T11 (CI, not a test): pnpm typecheck and pnpm lint of packages/pdf pass with no DOM lib and the restricted globals.

App:

  • T2 Catalog changed: mutate the loaded sheet's labels and one geometry, re-export the frozen envelope through the app's engine call → G1/G2 of the envelope, not of the mutated sheet.
  • T12, T13 kept green; T15 rebase: import a v3 archive whose documentSha256 differs → unresolved flags, labels filled from the archived snapshot, report.sheet updated, alert shown; draft restore path covered too.
  • T14 i18n parity: the engine dict FR/EN share one key set; app dicts stay in parity after losing pdf.*.

Manual validation: export the demo report in FR and EN, open in two viewers, check pages and the attachment panel (osteo-report.json), import on a fresh tab, import a pre-Step-5 v2 PDF, re-import the exported file after pnpm import:equine changed the draft and read the rebase alert.


8. Visible changes

In the PDF pages: none by default; T3 enforces it. Proposed, not planned:

  • V1 provenance line in the footer or on the conclusion page: sheet name, version and status ("Fiche équine, brouillon v1") and export date. Useful on paper, honest about the draft status. Needs validation.
  • V2 marker on items printed from snapshots because the sheet no longer holds them, for example (?) before the label, mirroring the (!) vet marker. Needs validation.

Outside the pages: attachment description "Faunosteo report archive v1" and the Keywords stamp in the PDF properties; in the app, two new messages (home.import.rebased, home.import.error_attachment_stripped), wording to validate.


9. Decisions to validate

# Decision Recommendation Alternative
D1 Finding trees in the snapshot pruned to the paths the report uses, ancestor labels kept (+4 KB raw) empty trees (ids and leaf labels only, in the report)
D4 v2 provenance do not embed the original v2 JSON in re-exports (the original PDF remains the record; the migration is reversible through the committed map) optional origin block with the verbatim v2 document
D6 Node rasterizer @resvg/resvg-js devDependency for T10 no real raster in Node (structure tests only)
D7 Branding explicit input, not archived archive the branding bytes (+90 KB per PDF)
D8 Imported snapshot in the app not kept; report rebased onto the loaded sheet with the alert of §3.5 keep it in the session and offer "re-export the archive as is" (new UI)
D10 Visible changes V1, V2 none in this step V1 and/or V2
D12 report:reexport CLI not in this step add it, envelope v1 only, with the file-writing rules of §5
D13 New app messages home.import.rebased and error_attachment_stripped as worded in §3.5 and §8 other wording

Settled in this plan (no observable effect): inline SVG text, lean-document snapshot shape, xmldom composition everywhere, engine-owned dictionary, demo report as the DoD reference, exportedAt as an input (no clock abstraction).


10. Risks

Risk Mitigation
xmldom serialisation differs from XMLSerializer G2 compares structural facts, not strings; T10 covers pixels; the browser rasterizer re-parses anyway
xmldom bundle cost above 50 KB gzipped measured in Phase 3; fallback: native DOM composition in the browser behind the same composeViewSvg signature
resvg renders the 81 Gaussian-blur filters or <switch> differently from Chromium T10 asserts structure, not pixels; the browser stays the production rasterizer
Moving render code touches 8 modules and 6 test files one-to-one test migration with the replacing test named (Step 1 rule)
Rebase marks items unresolved that only moved on the drawing by design: ids that survive stay resolved; the alert reports counts only
A future sheet with several large assets per-asset and total caps with an export-time typed error; Step 13 aligns the catalog cap
Allowlist strips legitimate content of a future asset silently the sanitiser returns its removals; Step 13 runs it at upload and fails there (TODO recorded as a shortcut:)

11. Plan

Executors as in Step 5: one executor per phase with a closed contract, TDD, fresh verifier and security gates at the end, no publication, no graphic redesign. Branch feature/step-06-pdf-archives.

Phase 0 — Freeze (current code, nothing else changes)

  • 0.1 fixtures: report-v3.demo.json, migrated-v2-with-unresolved report builder, G3 report-v3.bare.pdf
  • 0.2 goldens G1 (both logo modes), G2 (structural facts, placements, links); one-shot MAKE_GOLDEN=1 run, generator deleted (LRN-043)
  • 0.3 characterisation tests T12 (HomeRoute import) and T13 (EditorRoute export)

Phase 1 — Domain: snapshot, envelope, rebase

  • 1.1 anatomical-sheet/sheet-index.ts moved from the app (re-export kept)
  • 1.2 archive/snapshot.ts: buildSheetSnapshot, assertSnapshot, caps
  • 1.3 archive/envelope.ts: schema v1, readArchiveDocument layered reading, ArchiveReadError, SnapshotRejection
  • 1.4 report/rebase.ts: rebaseReportOnSheet
  • 1.5 bundle carries the asset manifest sha and the sheet status/name (vite/sheet-bundle.ts, sheets/provider.ts, LoadedSheet)
  • 1.6 tests: pruning on the draft (counts, bytes), validateSheetDocument clean on the lean document, caps, dispatch table of §4, rebase cases

Phase 2 — Anatomy: composer

  • 2.1 render/compose.ts promoted from curation/app-review.ts, highlight on the layer tree; review drawing unchanged (golden test proves it)

Phase 3 — Engine packages/pdf

  • 3.1 scaffold: manifest, tsconfig, lint rules, vitest node, Dockerfile manifest copy, CI, packages/README.md (fix its two wrong lines while there)
  • 3.2 svg/sanitize.ts + svg/view.ts; horse.svg zero-removal test; hostile cases
  • 3.3 render modules moved; Branding, Rasterizer, exportedAt, safeText, dict; parallel rasterisation then sequential embedding
  • 3.4 exportReportArchive (snapshot-based index, label policy §3.1, per-view degradation, caps, envelope write, Keywords stamp) → T3 in both logo modes
  • 3.5 readReportArchive (filename-first selection, inflate cap, layered reading, attachment_stripped) → T4, T5, T6, T8
  • 3.6 T1, T7, T9, T10 (resvg), T11; bundle-size measurement of xmldom

Phase 4 — App integration

  • 4.1 browserRasterizer.ts, branding.ts, export.ts and import.ts rewritten on the engine; rebase on import and on draft restore; two new messages
  • 4.2 old src/pdf/render, attachment.ts, anatomy/drawing.ts highlight code and pdf.* app keys removed; report:compare on the engine read API
  • 4.3 T2, T14, T15; T12/T13 green unchanged; app suite migrated one-to-one

Phase 5 — Docs and gates

  • 5.1 docs/PDF-FORMAT.md written for real (pages, envelope v1, snapshot content, caps, read order, compatibility table, rebase rule, CLI); CLAUDE.md folder map and conventions; WORKSPACE.md package rule corrected (tests under tests/); DEPLOY.md rollback note; CHANGELOG; BDR-014 note
  • 5.2 pnpm check, docker build, verifier and security gates, EVAL
  • 5.3 manual validation list (§7) for the user

Definition of Done: no fetch and no DOM in packages/pdf (compile, lint, tests); T1–T15 green; Phase 0 goldens reproduced in both logo modes; demo envelope < 250 KB stored and raw; docs/PDF-FORMAT.md complete; v2 fixtures import and re-export; rebase alert shown when the draft changed.


Part II — Implementation contract (validated 2026-10-11)

The user validated Part I on 2026-10-11 with three adjustments, recorded here as the binding contract for the executors. Where Part I and Part II differ, Part II wins.

12. Validated adjustments

  • D7 (branding). The engine receives its branding explicitly and never fetches. The archive also stores the branding used at export (logos, partner credits, URLs, fallback texts) and the label dictionary (both locales), so a future logo, wording or configuration change cannot alter the reproduction of an old archive. Compact and safe representation, no duplicated resource inside the envelope. Cost measured and reported.
  • D8 (imported snapshot). The archive carried by an imported PDF is kept in the session, immutable. Two operations are distinct in the architecture: (1) re-read or re-export an archive from its own snapshot, branding and labels, no rebase; (2) resume a bilan for editing on the current sheet: an explicit rebase on a working copy, historical labels of unresolvable items preserved. No new significant UI in this step: the technical support (store, persistence, engine API) ships and the UX choice for operation (1) is submitted to the user after the step.
  • D10, D12. No change to the pages. No report:reexport CLI.
  • D13 (messages). Explicit FR/EN messages for: an archive imported with its snapshot; a snapshot rejected while the report was recovered; a rebase with its count; a stripped attachment. A partial or degraded import is never presented as a perfect restoration.
  • D1, D4, D6 as recommended in §9.

13. Types (TypeScript, authoritative)

All JSON contracts below are camelCase, like Report v3 and SheetRef; the AnatomicalSheetDocument inside keeps its own snake_case schema.

// packages/domain/src/archive/snapshot.ts
export interface SheetSnapshotRef {            // sheet-ref.json, camelCase
  sheetId: string; versionId: string | null; documentSha256: string /^[0-9a-f]{64}$/;
  schemaVersion: number; speciesId: string;
}
export interface SheetSnapshotAsset { svgAssetId: string; sha256: string | null; svg: string }
export interface SheetSnapshot {
  status: 'draft' | 'published';
  ref: SheetSnapshotRef;
  document: AnatomicalSheetDocument;           // lean, valid (schema v2, strict)
  assets: SheetSnapshotAsset[];
}
export const SheetSnapshotSchema: z.ZodType<SheetSnapshot>   // strict + caps (§15)
export function buildSheetSnapshot(sheet: SnapshotSource, report: Report): SheetSnapshot
export interface SnapshotSource {              // what LoadedSheet provides
  status: 'draft' | 'published'; ref: SheetSnapshotRef; document: AnatomicalSheetDocument;
  assets: Readonly<Record<string, string>>;    // svg text by svgAssetId
  assetHashes?: Readonly<Record<string, string>>; // sha256 by svgAssetId (seed manifest)
}
export function assertSnapshot(snapshot: SheetSnapshot): SheetSnapshot
  // SheetSnapshotSchema.parse, validateSheetDocument(document) has no 'error' issue,
  // every view resolves (own asset or parent chain) to an asset present in `assets`,
  // document depth pre-check; throws SnapshotError(reason: SnapshotRejection)
export type SnapshotRejection = 'unsupported_envelope' | 'schema' | 'caps' | 'integrity' | 'sheet_mismatch'

// packages/domain/src/archive/envelope.ts
export const ENVELOPE_FORMAT = 'faunosteo-report-archive'
export const ENVELOPE_VERSION = 1
export interface ReportArchiveEnvelope {
  format: typeof ENVELOPE_FORMAT; envelopeVersion: 1;
  exportedAt: string;                          // ISO timestamp
  locale: 'fr' | 'en';
  report: Report;                              // v3, as exported (never rebased)
  sheetSnapshot: SheetSnapshot;
  branding: Branding;
  labels: PdfLabelSet;
}
export const ReportArchiveEnvelopeSchema: z.ZodType<ReportArchiveEnvelope>
  // metadata object is NOT strict (unknown keys ignored within v1); report, sheetSnapshot,
  // branding, labels are parsed by their own schemas
export type ArchiveOrigin = 'envelope_v1' | 'bare_v3' | 'v2'
export interface ArchiveReadOutcome {
  report: Report; origin: ArchiveOrigin; migrated: boolean;
  unresolvedZones: number; unresolvedFindings: number;   // from the v2 migration
  archive: ReportArchiveEnvelope | null;      // the validated envelope, when accepted
  snapshotRejected?: SnapshotRejection;       // envelope present but snapshot dropped
}
export function readArchiveDocument(data: unknown, map: ReportMigrationMap): ArchiveReadOutcome
  // throws UnsupportedReportVersionError (existing) when the REPORT version is unknown

// packages/domain/src/archive/branding.ts
export type ImageAsset = { kind: 'png'; base64: string } | { kind: 'svg'; svg: string }
export interface Credit { logo: ImageAsset | null; url: string; fallbackText: string }
export interface Branding {
  siteUrl: string;
  headerLogo: ImageAsset | null;               // today /assets/faunosteo_logo_horizontal-512.png
  footerLogo: ImageAsset | null;               // today /assets/faunosteo-horizontal-com-512.png
  poweredBy: Credit | null;                    // today ZenQuality PNG, https://zenquality.fr, 'zenquality.fr'
  partner: Credit | null;                      // today Paws SVG, instagram URL, '@paws.iin.harmony'
}
export const BrandingSchema: z.ZodType<Branding>   // strict; base64 ≤ 512 KiB, svg ≤ 256 KiB,
                                                   // url http(s) only ≤ 2048, fallbackText ≤ 128

// packages/domain/src/archive/labels.ts
export const PDF_LABEL_KEYS = [ /* exactly the keys read by apps/app/src/pdf at HEAD: */
  'pdf.empty','pdf.eyebrow.observation','pdf.eyebrow.synthesis','pdf.owner_prefix',
  'pdf.section.comment','pdf.section.conclusion','pdf.section.findings_prefix',
  'pdf.section.free_findings','pdf.section.next_appointment','pdf.section.recommendations',
  'pdf.section.severity','pdf.section.zones','pdf.siret_prefix','pdf.subject',
  'pdf.title.conclusion','pdf.title.suffix.bilan','pdf.view.detail_prefix','pdf.view.general',
  'severity.mild','severity.moderate','severity.severe','lateral.left','lateral.right',
  'footer.powered_by','footer.in_partnership' ] as const
export type PdfLabels = Record<(typeof PDF_LABEL_KEYS)[number], string>
export interface PdfLabelSet { fr: PdfLabels; en: PdfLabels }
export const PdfLabelSetSchema   // strict, every key required, values ≤ 256 chars

// packages/domain/src/report/rebase.ts
export interface RebaseOutcome { report: Report; unresolvedZones: number; unresolvedFindings: number; rebased: boolean }
export function rebaseReportOnSheet(report: Report, index: SheetIndex, archived: SheetSnapshot | null): RebaseOutcome
  // rebased=false and report returned as is when report.sheet.documentSha256 === index.sheet.ref.documentSha256
  // else: zone with unknown annotationId or unknown viewId → unresolved: true, label snapshots
  //   filled from `archived` annotation names when absent; finding with no nodeAt(zoneId, path)
  //   → unresolved: true; items already unresolved stay; report.sheet = index.sheet.ref

// packages/domain/src/anatomical-sheet/sheet-index.ts  (moved from apps/app/src/services/sheetIndex.ts)
export interface SheetIndexSource { ref: SheetSnapshotRef-compatible { documentSha256 }; document: AnatomicalSheetDocument; assets: Readonly<Record<string,string>> }
export { buildSheetIndex, pickLabel, isObservable, type SheetIndex, type ObservableAnnotation }
  // SheetIndex.sheet is typed as the source given; LoadedSheet satisfies it; SheetSnapshot does
  // through a one-line adapter (assets array → record). `pickLabel` takes 'fr' | 'en'.

// packages/pdf/src/index.ts
export type PdfLocale = 'fr' | 'en'
export type Rasterizer = (svg: string, size: { widthPx: number; heightPx: number }) => Promise<Uint8Array>
export interface ExportInput {
  report: Report; sheet: SheetSnapshot; branding: Branding; labels: PdfLabelSet;
  locale: PdfLocale; rasterizer: Rasterizer; exportedAt: Date;
}
export type ExportWarning =
  | { kind: 'view_raster_failed'; observationId: string; viewId: string }
  | { kind: 'logo_failed'; slot: 'headerLogo' | 'footerLogo' | 'poweredBy' | 'partner' }
export interface ExportResult { pdf: Uint8Array; envelope: ReportArchiveEnvelope; warnings: ExportWarning[] }
export function exportReportArchive(input: ExportInput): Promise<ExportResult>
  // throws ArchiveExportError(kind: 'snapshot_invalid' | 'snapshot_too_large' | 'sheet_mismatch' | 'too_many_pages')
export function exportFromEnvelope(env: ReportArchiveEnvelope, opts: { locale: PdfLocale; rasterizer: Rasterizer; exportedAt: Date }): Promise<ExportResult>
  // = exportReportArchive({ report: env.report, sheet: env.sheetSnapshot, branding: env.branding, labels: env.labels, ...opts })
export type ArchiveReadErrorKind = 'invalid_pdf' | 'no_attachment' | 'attachment_stripped' | 'incompatible_version'
export class ArchiveReadError extends Error { kind: ArchiveReadErrorKind; foundVersion?: number | null }
export function readReportArchive(pdfBytes: Uint8Array, map: ReportMigrationMap): Promise<ArchiveReadOutcome>
export function readAttachedDocument(pdfDoc: PDFDocument): Promise<unknown>   // raw JSON, for the compare CLI
export const MAX_PDF_BYTES, MAX_ATTACHMENT_BYTES
export const defaultPdfLabels: PdfLabelSet       // verbatim copy of today's FR/EN strings
export const PDF_KEYWORD = 'faunosteo-archive/1' // Info.Keywords stamp

14. Behaviour

Export (exportReportArchive): (1) assertSnapshot(sheet); (2) refuse when report.sheet.documentSha256 !== sheet.ref.documentSha256 (sheet_mismatch); (3) refuse report.observations.length > 500 or any observation with more than 8 distinct view ids (too_many_pages); (4) build the envelope { format, envelopeVersion: 1, exportedAt, locale, report, sheetSnapshot: sheet, branding, labels }, serialise pretty (indent 2), refuse above MAX_ATTACHMENT_BYTES (snapshot_too_large); (5) metadata: title, author, subject (labels), creation and modification dates = exportedAt, setKeywords([PDF_KEYWORD]); (6) fonts; (7) branding images: PNG → embedPng (base64 decoded with atob), SVG → sanitise + rasterise at width 1200 px (today's rule) → embedPng; each slot fails alone with a logo_failed warning; (8) observation pages: rasterise every view of an observation in parallel, then embed in view order (main first); a raster failure gives a page without that image and a view_raster_failed warning; (9) conclusion page, footer on every page, attach the envelope bytes as osteo-report.json (application/json, description Faunosteo report archive v1, dates exportedAt, AFRelationship.Data); (10) save().

Label policy (§3.1, unchanged wording): zone name = snapshot annotation name by id (trigger: opened view's name), else report zone snapshot in the locale (other locale as fallback), else the id; finding group heading = snapshot finding-zone name by id, else the id upper-cased; finding text and (!) from the report; views = unique view ids of the observation present in the snapshot, main first; unresolved never consulted; every printed string goes through safeText (§15).

View SVG (packages/pdf/src/svg/view.ts): asset text refused if it contains <!DOCTYPE or <!ENTITY; parsed with xmldom (onError throws on error and fatalError); sanitizeSvgRoot (§15); composeViewSvg from @faunosteo/anatomy/render with highlight: { annotationIds, halo: view.kind === 'main' }; serialised; size = width 1200, height = round(1200 × vbH / vbW) with the ratio clamped to [0.2, 2.0], view box = view.view_box ?? root viewBox ?? 0.6 ratio (today's fallback).

composeViewSvg (packages/anatomy/src/render/compose.ts, promoted from curation/app-review.ts, which now calls it with no highlight): ({ root: Element, document, viewId, highlight?: { annotationIds: ReadonlySet<string>; halo: boolean } }) => Element: set viewBox from viewBoxOf(view) when present, remove width/height, render the layer tree; with highlight: keep only layer elements whose annotation id is selected, set fill="#b85a3f", fill-opacity="0.85", and filter="url(#osteo-halo)" when halo, emit no data-* attribute, keep <title>; when halo, ensure <defs> (created as first child when absent) holds the osteo-halo filter exactly as observationPage.ts:157-197 (x/y −100%, width/height 300%, filterUnits="userSpaceOnUse", blurs 18 and 8, merge wide×3 + tight×2 + SourceGraphic); append the layer <g> last.

Read (readReportArchive): size cap → PDFDocument.load (invalid_pdf on failure) → attachment: the Filespec whose /F starts with osteo-report, else the first EmbeddedFile, inflating FlateDecode streams under the cap (inflateFlate, kept) → none: attachment_stripped when getKeywords() contains faunosteo-archive, else no_attachment → cap → JSON.parse → readArchiveDocument(data, map):

  1. locate the report: data.report when typeof data.envelopeVersion === 'number', else data;
  2. readReportDocument(report, map) (existing: v3 parsed, v2 migrated, other → UnsupportedReportVersionError(found) → incompatible_version);
  3. bare → { origin: 'bare_v3' | 'v2', archive: null }; envelope with envelopeVersion !== 1 → archive: null, snapshotRejected: 'unsupported_envelope'; envelope v1 → parse metadata + sheetSnapshot + branding + labels; BrandingSchema/PdfLabelSetSchema failure → 'schema'; assertSnapshot failure → its reason; snapshot ref ≠ report.sheet → 'sheet_mismatch'; success → archive = the validated envelope. Every other JSON failure → no_attachment as today.

App session (reportStore.ts, persistence.ts):

  • state { report: Report | null; archive: ReportArchiveEnvelope | null; activeObservationIndex };
  • hydrateReport(report) kept (archive → null); new hydrateImport({ report, archive }); initReport and reset clear archive;
  • persistence: osteo:draft as today; osteo:archive written on hydrateImport/reset/initReport only (not on every edit), restored with the draft; ArchivePersistence beside ReportPersistence;
  • restoreDraft(index: SheetIndex) loads the draft then rebases it on the index when its sha differs (counts returned to the caller).
  • HomeRoute: readReportArchive through apps/app/src/pdf/import.ts (maps ArchiveReadError kinds to ImportError kinds, four kinds now) → rebaseReportOnSheet(outcome.report, index, outcome.archive?.sheetSnapshot ?? null) → hydrateImport({ report: rebased, archive: outcome.archive }) → one window.alert composed of the applicable lines (see §16) → /editor.
  • EditorRoute export: exportReportArchive({ report, sheet: buildSheetSnapshot(index.sheet, report), branding: await loadBranding(), labels: defaultPdfLabels, locale, rasterizer: browserRasterizer, exportedAt: new Date() }); download name unchanged; warnings logged with console.warn.
  • The kept archive is exposed by the store for operation (1); no UI uses it in this step (UX choice submitted after).

Branding in the app (apps/app/src/pdf/branding.ts): loadBranding(): Promise<Branding> fetches the four public/ files by their current URLs (each failure → slot null + console.warn, as today), PNG → base64, Paws SVG kept as { kind: 'svg', svg }; constants: siteUrl 'https://faunosteo.com', poweredBy { url: 'https://zenquality.fr', fallbackText: 'zenquality.fr' }, partner { url: 'https://www.instagram.com/paws.iin.harmony', fallbackText: '@paws.iin.harmony' }. // shortcut: the site URL and partner constants live here until the config carries them.

Bundle (vite/sheet-bundle.ts, sheets/provider.ts): the payload gains assetHashes: Record<svg_asset_id, sha256> from assets.json; LoadedSheet gains assetHashes; ref gains schemaVersion and speciesId so it is a SheetSnapshotRef (SheetRef of the report stays the 3-field subset).

15. Caps, sanitiser, text

Item Cap
PDF file 50 MiB (existing)
attachment, raw and inflated 16 MiB (existing)
snapshot assets ≤ 4, each ≤ 2 MiB, total ≤ 6 MiB
snapshot document ≤ 64 views, ≤ 1,024 annotations, ≤ 8,192 finding nodes, depth ≤ 8, labels ≤ 512 chars
branding PNG base64 ≤ 512 KiB each, SVG ≤ 256 KiB, URLs http(s) ≤ 2,048 chars
report at export ≤ 500 observations, ≤ 8 views per observation
sanitiser ≤ 20,000 elements, nesting ≤ 64, ≤ 256 <use>, stdDeviation ≤ 100
raster width 1200 px, aspect clamped to [0.2, 2.0]

Sanitiser (packages/pdf/src/svg/sanitize.ts, sanitizeSvgRoot(root: Element): { removed: string[] }, DOM Level 2 only: childNodes, attributes, removeAttribute, removeChild, tagName):

  • elements kept: svg g path circle ellipse rect line polyline polygon defs linearGradient radialGradient stop filter feGaussianBlur feMerge feMergeNode feOffset feFlood feComposite feBlend feColorMatrix clipPath mask title desc switch use; anything else is removed with its subtree (incl. style, script, image, a, foreignObject, text, feImage, feTurbulence, feConvolveMatrix, animate*, set);
  • attributes kept: id class d cx cy r rx ry x y x1 y1 x2 y2 dx dy width height points transform viewBox version preserveAspectRatio fill fill-opacity fill-rule stroke stroke-width stroke-linecap stroke-linejoin stroke-opacity stroke-dasharray stroke-dashoffset stroke-miterlimit opacity filter clip-path clip-rule mask display visibility color gradientUnits gradientTransform spreadMethod offset stop-color stop-opacity stdDeviation in in2 result mode operator k1 k2 k3 k4 flood-color flood-opacity type values color-interpolation-filters filterUnits primitiveUnits systemLanguage font-family font-size font-weight xmlns xmlns:xlink xlink:href href style; any other attribute (incl. every on*) is removed;
  • href/xlink:href must match ^#[A-Za-z_][\w.:-]*$; every url( in any attribute value must be url(#…); a style attribute containing url( not followed by #, expression(, @import, javascript: or behavior: is removed; stdDeviation above the cap is clamped;
  • counters: elements, depth, <use>; over a cap → throws SvgRejectedError.
  • horse.svg and Paws_in_harmony.svg must pass with removed: [] and a serialisation byte-identical to the parsed input (test).

Text: safeText(s: string): string strips \p{Cc}\p{Cf}

 except none, then replaces every code point that Encodings.WinAnsi.canEncodeUnicodeCodePoint (from @pdf-lib/standard-fonts) refuses by ?; used by wrapLines, every drawText and widthOfTextAtSize in the engine; en and em dashes survive. formatDate in the engine returns the input unchanged when it is not YYYY-MM-DD.

16. Messages (FR / EN keys, app dicts)

Key FR EN
home.import.archive_ok Archive Faunosteo importée : bilan et instantané de la fiche d'origine conservés. Faunosteo archive imported: report and the original sheet snapshot kept.
home.import.snapshot_rejected Bilan récupéré, mais l'instantané de la fiche d'origine a été rejeté ({reason}) : cette archive ne pourra pas être reproduite telle quelle. Report recovered, but the original sheet snapshot was rejected ({reason}): this archive cannot be reproduced as is.
home.import.snapshot_reason.unsupported_envelope archive d'une version plus récente archive from a newer version
home.import.snapshot_reason.schema contenu invalide invalid content
home.import.snapshot_reason.caps taille ou complexité excessive size or complexity over the limits
home.import.snapshot_reason.integrity fiche incohérente inconsistent sheet
home.import.snapshot_reason.sheet_mismatch fiche différente de celle du bilan sheet differs from the report's
home.import.rebased Bilan ouvert sur la fiche actuelle, différente de celle de l'archive. Éléments non retrouvés : {count} (conservés avec leurs libellés). Report opened on the current sheet, which differs from the archive's. Items not found: {count} (kept with their labels).
home.import.error_attachment_stripped Ce PDF Faunosteo a perdu ses données embarquées (pièce jointe supprimée par un lecteur ou un optimiseur). Utilisez le fichier d'origine. This Faunosteo PDF lost its embedded data (attachment removed by a viewer or an optimiser). Use the original file.

Alert composition after a successful import, lines joined by a blank line: migrated (existing v2 message, when origin === 'v2' and counts > 0) · archive_ok (when archive kept) · snapshot_rejected (when snapshotRejected) · rebased (whenever the rebase ran, count may be 0). No alert when nothing applies (bare v3 on the same sheet, as today).

17. Goldens (Phase 0, frozen with the current code)

Files under apps/app/tests/fixtures/goldens/step6/, JSON, numbers rounded to 2 decimals, generated once by a MAKE_GOLDEN=1 run of the golden test file itself (pdf.goldens.test.ts: in generation mode it writes, otherwise it asserts), and never regenerated without a user decision.

  • text.<report>.<locale>.<logos>.json: ordered { page, text, x, y, size, font } from a PDFPage.prototype.drawText spy (page = index of this in pdfDoc.getPages() after save; font = options.font.name).
  • images.<report>.<logos>.json: ordered { page, x, y, width, height } from a drawImage spy.
  • links.<report>.<logos>.json: { page, rect, uri } of every /Annot /Link read back from the saved PDF.
  • views.<report>.json: per (observationId, viewId): { viewBox, halo, highlighted: [{ tag, cx, cy, r, points, d, fill, fillOpacity, filter }], nonHighlightedVisible: 0, dataAttributes: 0, titles } from highlightedViewSvg parsed with DOMParser (hidden markers are display="none" today and absent in the engine: both count as not visible).
  • Reports: v2full (migrated report-v2.full.json), demo (report-v3.demo.json, new fixture: 6 observations covering main and head views, vertebrae, bilateral sides, a vet-referral leaf, a leaf whose label holds an en dash, free text, severity, next appointment), v2unresolved (built with tests/helpers/legacyLeaves.ts: one observation per unresolved leaf family, sphenoid and ssb, plus one resolved leaf).
  • Logo modes: nologos (fetch 404) and logos (fetch stub serving the real bytes of the four public/ files; rasterizeSvg mocked to a fixed 2×1 PNG so the partner logo width is deterministic).
  • report-v3.bare.pdf: the demo report exported by the current code (nologos), import fixture only.

Characterisation tests written in Phase 0 and kept green unchanged: routes.HomeRoute.import.test.tsx (v2 alert with count, four error kinds to messages, navigation; importReportFromPdf mocked) and routes.EditorRoute.export.test.tsx (export called with report, index and locale; download name bilan-<animal>-<date>.pdf; failure alert). Phase 4 adapts only the mocked module path and the call-shape assertion of T13 to the engine API, nothing else.

18. Executors and phases

One executor per phase, closed contract in .claude/tasks/contracts/, TDD, no commit (the orchestrator commits), report with test counts. Phases 1 and 2 run in parallel. Verifier and security gates after Phase 5 and on request.

Phase Owner Exit
0 freeze executor goldens + fixtures + T12/T13 committed, app suite green
1 domain executor archive/{snapshot,envelope,branding,labels}, sheet-index moved, rebase, bundle hashes; domain + app suites green
2 anatomy executor compose.ts, review drawing golden unchanged; anatomy suite green
3 engine executor packages/pdf complete, T1 T3–T11 green, xmldom bundle size measured
4 app executor routes, store, persistence, branding, messages; T2 T12–T15 green; old code removed
5 docs + gates orchestrator + verifier + security docs, check, docker, EVAL