From ad48758f8cc4deb550b30a4072eaa7296f1d2aa8 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 11 Oct 2026 13:11:04 +0200 Subject: [PATCH] =?UTF-8?q?docs(pdf):=20PDF-FORMAT.md=20written=20for=20re?= =?UTF-8?q?al=20=E2=80=94=20pages,=20archive=20envelope=20v1,=20snapshot,?= =?UTF-8?q?=20layered=20reading,=20rebase,=20limits,=20compare=20tool?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/PDF-FORMAT.md | 210 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 179 insertions(+), 31 deletions(-) diff --git a/docs/PDF-FORMAT.md b/docs/PDF-FORMAT.md index 0a70de92..12496b9e 100644 --- a/docs/PDF-FORMAT.md +++ b/docs/PDF-FORMAT.md @@ -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": "" } ] + }, + "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": { "...": "" } } +} +``` -- 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 ``, blur `stdDeviation` ≤ 100 | + +Every SVG that reaches the engine (sheet asset or branding) is untrusted: a +text containing `)`; - 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.