docs(pdf): PDF-FORMAT.md written for real — pages, archive envelope v1, snapshot, layered reading, rebase, limits, compare tool
This commit is contained in:
1 parent
c17956031d
commit
ad48758f8c
1 file changed
+179
-31
+179
-31
@@ -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.
|
||||
Reference in new issue
Block a user