36 KiB
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: thegetAttachmentsbranch never runs on pdf-lib 1.17.1, so the filename is never checked and the firstEmbeddedFilewins) →readReportDocument(v3 parsed, v2 migrated with the bundled map, elseincompatible_version). Any other failure becomesno_attachment("not generated by Faunosteo"). - Nothing compares
report.sheetwith the loaded sheet, on import or on export. Everypnpm import:equinerun changes the draft'sdocumentSha256.
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;
unresolvedis 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/xmldom0.9.x as a runtime dependency ofpackages/pdfandpackages/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 ofpackages/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 anonErrorthat throws onerrorandfatalErrorand never logs raw input. Watched bypnpm audit --prod.@resvg/resvg-jsas a devDependency ofpackages/pdf(D6): real rasterisation in Node for one end-to-end test. Native prebuilt binaries (lockfile must carrylinux-x64-muslfor 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
- Compile-time:
packages/pdfhas noDOMlib, sodocument,Image,DOMParserdo not type-check. - Lint-time: restricted globals and imports on
src/**(tests may read fixtures withnode:fs). - Test-time: the engine suite runs under vitest
environment: nodewith no Vite sheet plugin, so nothing can reach the bundled sheet. - 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 awarningsentry, 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
annotationIdis absent from the loaded sheet, or whoseviewIdis unknown, getsunresolved: 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 getsunresolved: true(same semantics as the v2 migration); report.sheetbecomes the loaded ref; counts are returned and the existing partial-import alert pattern shows them (new keyhome.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:
- Locate the report:
data.reportwhendata.envelope_versionis numeric, elsedataitself (bare). - Parse the report with
readReportDocument(v3 parsed, v2 migrated with the bundled map, any otherversion→incompatible_versionwith the report version found).foundVersionalways names a report version, so the existing UI message stays true. - Parse the envelope metadata tolerantly (unknown keys ignored within v1).
envelope_versionother than 1 →snapshotRejected: 'unsupported_envelope', report kept. Then parsesheet_snapshotstrictly (document schema v2, caps, integrity, assets reachable,sheet_mismatch); any failure →snapshotRejectedwith 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
<!DOCTYPEor<!ENTITY; - element allowlist, enumerated from the real inventory of
horse.svgplus 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; nostyle,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-*; noon*;href/xlink:hrefandurl(…)values must be#fragment;styleattributes may not containurl(other than#,expression(or@import; - returns the list of removals; the engine logs nothing from it and the test
on
horse.svgasserts 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 withfill/fill-opacity/filter, hidden marker count, halo filter on the main view only, nodata-*left; plus image placements(page, x, y, w, h)and link annotations(page, Rect, URI). - G3
report-v3.bare.pdfexported by Step 5 code (import fixture only). - T12
HomeRouteimport: v2 alert with count, error kinds to messages, navigation. T13EditorRouteexport: 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 →
exportReportArchivefrom the envelope alone → same G1 text, same G2 facts, same envelope minusexported_at(the written snapshot isassertSnapshot'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 →
toEqualreport 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 withsnapshot: null. - T6 versions: envelope v2 with report v3 → report imported,
snapshotRejected: 'unsupported_envelope'; envelope v1 with report v4 →incompatible_version4; bare v7 →incompatible_version7. - 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 andsnapshotRejectednames the reason; hostile SVG (<script>,onload,javascript:href, external<image>,<!ENTITY>,<style>withurl(http…), 257<use>, a rootviewBoxof0 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 typecheckandpnpm lintofpackages/pdfpass 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
documentSha256differs → unresolved flags, labels filled from the archived snapshot,report.sheetupdated, 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, G3report-v3.bare.pdf - 0.2 goldens G1 (both logo modes), G2 (structural facts, placements, links);
one-shot
MAKE_GOLDEN=1run, 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.tsmoved from the app (re-export kept) - 1.2
archive/snapshot.ts:buildSheetSnapshot,assertSnapshot, caps - 1.3
archive/envelope.ts: schema v1,readArchiveDocumentlayered 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),
validateSheetDocumentclean on the lean document, caps, dispatch table of §4, rebase cases
Phase 2 — Anatomy: composer
- 2.1
render/compose.tspromoted fromcuration/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.svgzero-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.tsandimport.tsrewritten on the engine; rebase on import and on draft restore; two new messages - 4.2 old
src/pdf/render,attachment.ts,anatomy/drawing.tshighlight code andpdf.*app keys removed;report:compareon 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.mdwritten for real (pages, envelope v1, snapshot content, caps, read order, compatibility table, rebase rule, CLI); CLAUDE.md folder map and conventions;WORKSPACE.mdpackage rule corrected (tests undertests/); 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.