# PDF format and report archive A Faunosteo PDF is both a document for the reader and an archive of the bilan. The engine lives in `packages/pdf` (`@faunosteo/pdf`) and renders from explicit inputs only: no network, no browser DOM, no access to the current catalog. The attachment carries everything a future reader needs to re-render the bilan when the anatomical sheet, the catalog, the labels or the branding have changed since the export. Design record: `docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md`. ## Pages - A4 portrait, 595.28 × 841.89 pt, 36 pt side margins. - One page per observation, then one conclusion page. Every page carries the header (logo, practitioner, animal, owner, date) and the footer (site logo, "powered by" credit, partner credit, page `n / N`). - Observation page: eyebrow + title, the views of the observation drawn with its zones highlighted (main view first, head view as a crop of the same asset), then zones, findings grouped by finding zone, free findings, severity, comment. - Conclusion page: conclusion, recommendations, next appointment. - Fonts: pdf-lib StandardFonts Helvetica, Helvetica-Bold (body) and Times-Roman (headings), WinAnsi encoding. Every printed string goes through `safeText`: control characters are stripped and any glyph WinAnsi cannot encode becomes `?` (en and em dashes, accented letters, `•`, `·` are fine; `⚠` is not, hence the `(!)` vet-referral marker). - Drawings: the sheet SVG asset is parsed with xmldom, sanitised (allowlist below), framed on the view box, the marker layer is generated from the document and the observation's zones are filled `#b85a3f` at 0.85 opacity with a blur halo on the main view; every other marker is dropped. The SVG is rasterised at 1200 px wide (aspect clamped to [0.2, 2.0]) by the rasterizer the caller provides: `Image` + canvas in the browser, resvg in Node tests. A failed raster leaves the page without that image and reports a warning; the export never fails for a drawing. - Document information: title, author, subject, dates = `exportedAt`, and `Keywords: faunosteo-archive/1` so a PDF whose attachment was stripped by a viewer is still recognised. ## Attachment: the report archive envelope (v1) One native embedded file (`EmbeddedFiles`, `AFRelationship /Data`) named `osteo-report.json`, MIME `application/json`, description `Faunosteo report archive v1`, Flate-compressed by pdf-lib. Pretty-printed JSON, camelCase keys (the sheet document inside keeps its own snake_case schema): ```json { "format": "faunosteo-report-archive", "envelopeVersion": 1, "exportedAt": "2026-10-11T09:00:00.000Z", "locale": "fr", "report": { "version": 3, "...": "Report v3 exactly as exported" }, "sheetSnapshot": { "status": "draft", "ref": { "sheetId": "…", "versionId": null, "documentSha256": "…", "schemaVersion": 2, "speciesId": "equine" }, "document": { "schema_version": 2, "...": "lean, valid anatomical sheet document" }, "assets": [ { "svgAssetId": "…", "sha256": "…", "svg": "" } ] }, "branding": { "siteUrl": "https://…", "headerLogo": { "kind": "png", "base64": "…" }, "footerLogo": { "kind": "png", "base64": "…" }, "poweredBy": { "logo": { "kind": "png", "base64": "…" }, "url": "https://…", "fallbackText": "…" }, "partner": { "logo": { "kind": "svg", "svg": "" }, "url": "https://…", "fallbackText": "…" } }, "labels": { "fr": { "pdf.section.zones": "ZONES", "...": "25 keys" }, "en": { "...": "" } } } ``` ### What the snapshot holds The snapshot is the sheet the bilan was built on, reduced to what the bilan needs, as a **valid** anatomical sheet document (schema v2, same integrity rules as the catalog): | Part | Content | |---|---| | `ref` | sheet id, version id, sha256 of the full catalog document (provenance pointer), schema version, species | | `document.views`, `annotations`, `categories`, `vertebral_config` | all of them: geometry, colours, names, anatomical relations (`finding_zone_id`, `vertebral_region_code`, `opens_view_id`, laterality) | | `document.finding_zones` | every zone with its name; for the zones the report's findings use (resolved or `unresolved`), the categories pruned to the referenced paths with the name and vet flag of every node on the path; other zones keep `categories: []` | | `document.references` | emptied (bibliography) | | `document.name`, `description`, `scope_disclaimer`, `attribution` | kept | | `assets` | the SVG text of every asset a view reaches, with the catalog's content hash when known | `branding` is the exact set of images, URLs and credit texts used at export; `labels` is the engine dictionary in both languages. A re-export of the archive uses these three blocks and nothing from the current application, so a new logo, a reworded heading or a curated sheet never changes how an old bilan is reproduced. Invariant: `report.sheet.documentSha256 === sheetSnapshot.ref.documentSha256` (and the sheet ids match). The export refuses to write a file that breaks it. ### Sizes Measured on the demo report (6 observations, both views, equine draft): | Branding | Stored in the PDF (Flate) | Raw JSON | |---|---|---| | no logos | 55 KB | 189 KB | | full branding (3 PNG logos + partner SVG) | 136 KB | 306 KB | The drawing is the largest part (47 KB stored); the archived PNG logos add about 80 KB stored. The 250 KB target applies to the stored size. ## Reading an archive `readReportArchive(pdfBytes, migrationMap)` reads in layers so the report is never lost because of its wrapper: 1. The PDF must load (`invalid_pdf`, also above 50 MiB). 2. The attachment named `osteo-report*` is taken first, else the first embedded file; Flate streams are inflated under a 16 MiB cap. No attachment: `attachment_stripped` when the PDF carries the Faunosteo keyword, else `no_attachment`. 3. The report is located (`data.report` inside an envelope, `data` for a bare attachment) and read with the report reader: v3 as is, v2 migrated through the sheet's `report-migration-map.json` (items the map cannot place are kept with their labels and flagged `unresolved: true`), any other version → `incompatible_version` with the version found. 4. Envelope metadata is read tolerantly (unknown keys ignored within v1). An unknown `envelopeVersion` keeps the report and drops the snapshot (`snapshotRejected: 'unsupported_envelope'`). The snapshot, branding and labels are validated strictly; any failure drops the snapshot with a closed reason (`schema`, `caps`, `integrity`, `sheet_mismatch`) and keeps the report. | Archive | Produced by | Read as | |---|---|---| | bare Report v2 | application before Step 5 | `origin 'v2'`, migrated, unresolved counts | | bare Report v3 | Step 5 | `origin 'bare_v3'`, no archive | | envelope v1 | Step 6 | `origin 'envelope_v1'`, archive kept or `snapshotRejected` | | envelope v≥2 | future | report kept when its version is known, snapshot dropped | Readers never drop a schema version: sheet document schema v2 stays readable as long as envelope v1 archives exist, as Report v2 does today. A rollback to a pre-Step-6 application reads an envelope as "no attachment". ### In the application Two operations are distinct: - **Re-read or re-export an archive**: `exportFromEnvelope(envelope, { locale, rasterizer, exportedAt })` uses the archived snapshot, branding and labels. The imported archive is kept in the session (`osteo:archive`), immutable. - **Resume a bilan for editing**: the editor works on the loaded sheet. When the archive's sheet differs from the loaded one, the report is **rebased** on a working copy: zones and findings the loaded sheet cannot place are flagged `unresolved: true`, their labels are filled from the archived snapshot, and `report.sheet` becomes the loaded sheet. The import message states the number of items not found; a degraded import is never shown as a perfect restoration. ## Limits and sanitising | Item | Cap | |---|---| | PDF file | 50 MiB | | attachment, raw and inflated | 16 MiB | | snapshot assets | ≤ 4, ≤ 2 MiB each, ≤ 6 MiB total | | snapshot document | ≤ 64 views, ≤ 1,024 annotations, ≤ 8,192 finding nodes, depth ≤ 8, names ≤ 512 chars | | branding | PNG base64 ≤ 512 KiB, SVG ≤ 256 KiB, http(s) URLs ≤ 2,048 chars | | branding URL | `http(s)://` then printable ASCII only, without `"` `'` `(` `)` `<` `>` `\`, no space or control character | | branding PNG | valid signature and IHDR, each side ≤ 8,192 px, ≤ 16,777,216 px (4096²) | | report at export | ≤ 500 observations, ≤ 8 views per observation | | SVG sanitiser | ≤ 20,000 elements, nesting ≤ 64, ≤ 256 ``, blur `stdDeviation` ≤ 100 | Every SVG that reaches the engine (sheet asset or branding) is untrusted: a text containing `` expansion is bounded by the rasterizer (resvg refuses an oversized tree), not by the sanitiser, which only counts the `` elements (≤ 256). - Report v3 collections are not capped on read; the export refuses above 500 observations and 8 views per observation. ## Checking an archive against its migration `pnpm report:compare ...` reads the attachment of one or more PDFs and prints it next to its v3 reading on the bundled reference sheet. It writes no output file: - an envelope prints a header line `archive v1 (snapshot kept)` or `archive v1 (snapshot rejected: )`; - a v2 archive PDF: every legacy zone (`data-anno-id`, side, vertebrae) and every legacy finding path is shown with its canonical target and the current label of that target (`same` when the path did not change); - a v3 report: every zone and finding is checked against the sheet, and the header says whether the report was written on the bundled sheet document; - anything the sheet cannot place is printed as `!! UNRESOLVED` with the reason: unknown legacy zone id, finding removed from the sheet by the curation, finding that never belonged to the legacy catalog, or a v3 finding flagged `unresolved` in the report itself. Options: `--summary` (one line per file, counts and unresolved counts), `--full` (add the practitioner, animal and owner names and the real free texts; by default only identifiers, catalog labels, snapshots of unresolved items, counts and placeholders such as `comment (present)` are printed), `--locale fr|en` (labels), `--diff a.pdf b.pdf` (compare the v3 content of two PDFs: an archive and the PDF exported after importing it should print `identical v3 content`; by default the texts are compared as placeholders, so an edited text shows only when it appears or disappears; `--full` compares the real texts and prints the differing lines). Every untrusted string is printed with control characters escaped as `\uXXXX`. The tool exits 2 when a file could not be read (no attachment, unknown version, oversized) and prints the reason.