Files
faunosteo/docs/PDF-FORMAT.md
T

235 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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": "<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": { "...": "" } }
}
```
### 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 `<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). An attribute value with a backslash is removed (a
CSS escape such as `u\72l(` would hide a reference), and a `style` or
presentation attribute may call no function other than `url(#…)`: `rgb(`,
`image-set(`, `expression(` and the like are removed with the attribute. 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.
The branding URL rule exists because a URL is written into every page's
link action: pdf-lib does not escape a literal string, so the engine writes
the URI as a hex string and the schema refuses the characters that could
close a literal. The export re-validates the branding and the labels it
receives (`ArchiveExportError('branding_invalid')` before any page is
drawn), even from an archive that passed the reader. A PNG logo whose header
is missing, wrong or over the pixel budget is never decoded: that slot alone
prints its fallback text and the export reports `logo_failed`.
### Known limits
- pdf-lib inflates PDF object streams without a cap when loading: a crafted
PDF of a few hundred KB can expand to hundreds of MB in the tab before the
attachment is even looked at. The 50 MiB file cap bounds the input, not
the expansion. Mitigation planned: parse in a Worker, or locate the
attachment without a full load.
- `<use>` expansion is bounded by the rasterizer (resvg refuses an
oversized tree), not by the sanitiser, which only counts the `<use>`
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 <file.pdf | folder>...` 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: <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 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.