docs(pdf): PDF-FORMAT.md written for real — pages, archive envelope v1, snapshot, layered reading, rebase, limits, compare tool

This commit is contained in:
bchanot committed 2026-10-11 13:11:04 +02:00
1 parent c17956031d
commit ad48758f8c
1 file changed
+179 -31
+179 -31
View File
@@ -1,33 +1,178 @@
# PDF Format
# PDF format and report archive
Placeholder — to be written when implementing src/pdf/.
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`.
Will cover:
## Pages
- A4 portrait dimensions (595.28 × 841.89 pt)
- Page layout: header / body / footer zones
- Observation page structure
- Conclusion page structure
- JSON attachment spec (EmbeddedFiles, afRelationship:Data)
- Font handling (pdf-lib StandardFonts Helvetica/Times-Roman, WinAnsi; TTF Inter/Fraunces planned, not shipped)
- Import/re-import roundtrip contract
- 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 versions (Step 5)
## Attachment: the report archive envelope (v1)
The attachment `osteo-report.json` carries the Report **v3** document
(`packages/domain/src/report/v3.ts`): zones by `(annotationId, viewId)`,
findings by `(findingZoneId, path)` with label snapshots, severity codes,
the `sheet` reference (sheet id, version id, sha256 of the document) and the
reserved `localAnnotations`.
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):
Import (`importReportFromPdf(bytes, migrationMap)`) accepts:
```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": "<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": "<svg …>" }, "url": "https://…", "fallbackText": "…" }
},
"labels": { "fr": { "pdf.section.zones": "ZONES", "...": "25 keys" }, "en": { "...": "" } }
}
```
- v3: read as is;
- v2 (PDFs produced by the application before Step 5, the practitioner's
archive): migrated through the sheet's `report-migration-map.json`; a zone
or finding the map cannot place is kept with its snapshots and flagged
`unresolved: true`; the outcome reports `migrated` and the unresolved counts;
- any other version: `ImportError('incompatible_version', foundVersion)`.
### 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 |
| report at export | ≤ 500 observations, ≤ 8 views per observation |
| SVG sanitiser | ≤ 20,000 elements, nesting ≤ 64, ≤ 256 `<use>`, blur `stdDeviation` ≤ 100 |
Every SVG that reaches the engine (sheet asset or branding) is untrusted: a
text containing `<!DOCTYPE` or `<!ENTITY` is refused; the parsed tree is
sanitised by allowlist (shapes, groups, gradients, the filter primitives the
drawings use, `clipPath`, `mask`, `switch`, `use`, `title`, `desc`; geometry,
presentation, gradient and filter attributes; `href` and `url()` only to a
`#fragment`; no `style` element, no `script`, `image`, `a`, `foreignObject`,
`text`, no event handler). The reference drawings pass unchanged (tested).
The same caps are checked at export, so an export can never write a file its
own reader refuses.
## Checking an archive against its migration
@@ -35,10 +180,12 @@ Import (`importReportFromPdf(bytes, migrationMap)`) accepts:
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: <reason>)`;
- 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 PDF: every zone and finding is checked against the sheet, and the
- 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
@@ -49,10 +196,11 @@ 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.
`--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.