993 lines
60 KiB
Markdown
993 lines
60 KiB
Markdown
# Step 6 — Autonomous PDF archives: analysis and plan
|
||
|
||
Status 2026-10-10: analysis and plan, challenged on three lenses (correctness,
|
||
robustness, simplicity: GO WITH FIXES each, fixes folded in below), awaiting
|
||
user validation. No implementation.
|
||
|
||
Scope authorised by the user on 2026-10-10: the PDF import system, the
|
||
attachment and the modules around them may change (this lifts the CLAUDE.md
|
||
"ask before" gate for this step). Goal: a Faunosteo PDF must stay readable and
|
||
re-renderable when the anatomical sheet it was built on no longer exists in
|
||
the catalog. Business behaviour of the PDF is preserved; no graphic redesign.
|
||
|
||
Sources: three read-only analyses of the current code (PDF pipeline, data
|
||
model, app wiring and tests), size measurements on the equine draft, three
|
||
plan challenges. Facts carry a `path:line` reference; measurements were taken
|
||
on `develop @ 072d761`.
|
||
|
||
---
|
||
|
||
## 1. What the current pipeline depends on
|
||
|
||
### 1.1 Inputs read at export time
|
||
|
||
`exportReportToPdf(report, sheet: SheetIndex, { locale })`
|
||
(`apps/app/src/pdf/export.ts:27`) reads two sources.
|
||
|
||
From the **live sheet**, through the `SheetIndex` built from the bundled draft:
|
||
|
||
| Data | Used for | Where |
|
||
|---|---|---|
|
||
| `annotation.name {fr,en}` (trigger: the opened view's name) | zone text | `render/observationPage.ts:355-356`, `services/sheetIndex.ts:108-111` |
|
||
| `finding_zones[].name`, looked up by id whatever the `unresolved` flag | finding group heading | `observationPage.ts:383-390` |
|
||
| `view.kind`, `view.name` | "general" label, halo, upper-cased detail caption | `:329-340` |
|
||
| `view.view_box`, `view.svg_asset_id`, parent chain | crop and asset choice | `anatomy/drawing.ts:61-85` |
|
||
| asset SVG text | the drawing | `drawing.ts:52` |
|
||
| `document.views` (names title the nameless triggers), `categories[].color`, every annotation of the view | marker layer, then highlight | `packages/anatomy/src/render/layer.ts:114-255` |
|
||
|
||
From the **report**: identities, dates, zones `(annotationId, viewId, side,
|
||
vertebrae)`, finding leaf snapshots (always the text source, BDR-010) and the
|
||
vet flag `(!)` (`observationPage.ts:413-414`), free text, severity,
|
||
conclusion. Zone snapshots are a fallback only (`:357-361`).
|
||
|
||
From the **i18n dict**: `pdf.*`, `severity.*`, `lateral.*`,
|
||
`footer.powered_by`, `footer.in_partnership`.
|
||
|
||
Never read: the finding tree nodes (`nodeAt`), `vertebral_config`,
|
||
`report.sheet`, `finding.path`.
|
||
|
||
### 1.2 Browser and network dependencies
|
||
|
||
| Dependency | Where | Behind an interface |
|
||
|---|---|---|
|
||
| `fetch` of 4 logos on root-relative URLs | `render/logo.ts:6`, `export.ts:63` | no |
|
||
| `DOMParser`, `document.createElementNS/importNode` | `drawing.ts:37,78,88,95` | no |
|
||
| `querySelectorAll`, `el.remove()`, `XMLSerializer` | `observationPage.ts:159-229` | no |
|
||
| `DOMParser`, `Blob`, `URL.createObjectURL`, `Image`, canvas, `toBlob`/`toDataURL`, `atob` | `svgToPng.ts:17-101` | no |
|
||
| `DecompressionStream` (read side, guarded) | `attachment.ts:127` | no |
|
||
| `new Date()` (non-deterministic bytes) | `export.ts:38`, `attachment.ts:35` | no |
|
||
|
||
Hard-coded branding: 4 logo paths under `public/`, link URLs at
|
||
`header.ts:63` and `footer.ts:53,92,107,116`, attachment description,
|
||
highlight colour `#b85a3f`. No `useConfig`/`appConfig` on the PDF path.
|
||
Logos degrade one by one (own try/catch, `export.ts:47-68`); a single view
|
||
raster failure sinks the whole export (`Promise.all`, `observationPage.ts:334`).
|
||
|
||
Node 24 provides `CompressionStream`, `DecompressionStream`, `TextEncoder`,
|
||
`crypto.subtle`, `Blob`, `structuredClone`; it has no `DOMParser`,
|
||
`XMLSerializer`, `Image` or `document`. pdf-lib 1.17.1 is DOM-free and already
|
||
runs in Node for `pnpm report:compare`. `@faunosteo/anatomy/render` is DOM-free
|
||
(`LayerElement` tree + `serializeLayer`), and the curation pipeline already
|
||
composes a view drawing with `@xmldom/xmldom` in Node
|
||
(`renderAppReviewDrawing`, `packages/anatomy/src/curation/app-review.ts:20-36`:
|
||
parse asset, set `viewBox`, drop width/height, append the layer, serialise).
|
||
|
||
### 1.3 The attachment today
|
||
|
||
- One embedded file `osteo-report.json`, the bare Report v3 (pretty JSON),
|
||
Flate-compressed by pdf-lib itself (`FileEmbedder` → `context.flateStream`,
|
||
pako). Full fixture: 3,947 B raw, 1,177 B stored.
|
||
- Carries `sheet {sheetId, versionId|null, documentSha256}` and nothing else of
|
||
the sheet. No locale, no labels beyond the zone and leaf snapshots.
|
||
- Read path: `importReportFromPdf` (50 MiB cap) → `readAttachedDocument`
|
||
(16 MiB cap, raw object traversal: the `getAttachments` branch never runs on
|
||
pdf-lib 1.17.1, so the filename is never checked and the first
|
||
`EmbeddedFile` wins) → `readReportDocument` (v3 parsed, v2 migrated with the
|
||
bundled map, else `incompatible_version`). Any other failure becomes
|
||
`no_attachment` ("not generated by Faunosteo").
|
||
- Nothing compares `report.sheet` with the loaded sheet, on import or on
|
||
export. Every `pnpm import:equine` run changes the draft's `documentSha256`.
|
||
|
||
### 1.4 What the report already preserves
|
||
|
||
Report v3 (`packages/domain/src/report/v3.ts`) embeds: zone names FR/EN
|
||
(optional), leaf finding names FR/EN (required), the vet flag, vertebra codes
|
||
and indexes, the side, `unresolved: true` on items the v2 migration could not
|
||
place (their legacy ids are kept; the 29 unresolved legacy leaves all sit in
|
||
zones that still exist: frontal, sphenoid, ssb). It does **not** embed
|
||
finding-zone names, ancestor and category names, region names, view names,
|
||
colours, geometry, view boxes or assets.
|
||
|
||
---
|
||
|
||
## 2. Snapshot: exact content
|
||
|
||
### 2.1 Requirement
|
||
|
||
Re-read and re-render an old bilan (FR and EN, text and drawings) without the
|
||
current catalog, and keep every historical datum including unresolved items.
|
||
A sheet id or a dependency on the current catalog is not enough.
|
||
|
||
### 2.2 Shape: a lean sheet document, not a new schema
|
||
|
||
The snapshot has the shape the renderer and the sheet index already consume
|
||
(`LoadedSheet` minus the migration map): `{ status, ref, document, assets }`.
|
||
`document` is a valid `AnatomicalSheetDocument` (schema v2, strict, unchanged)
|
||
with the bibliography emptied and the finding trees pruned to what the report
|
||
uses. So `renderAnnotationLayer`, `buildSheetIndex`, `pickLabel` and
|
||
`validateSheetDocument` apply to it with no change, and the full set of sheet
|
||
integrity rules (unique ids, acyclic view chain, one main view, categories and
|
||
regions present) protects it.
|
||
|
||
| Part | Content | Why |
|
||
|---|---|---|
|
||
| `ref` | `sheet_id`, `version_id`, `document_sha256`, `schema_version`, `species_id`, `name {fr,en}`, `status` | provenance (`document_sha256` is the full catalog document's hash, kept as a pointer, not as a hash of the snapshot) |
|
||
| `document.views` | all views | captions, crops, trigger titles (a nameless trigger is titled from the view it opens, `layer.ts:240-248`) |
|
||
| `document.annotations` | all annotations, `review_status` kept (schema default) | geometry, colours, zone names, anatomical relations (`finding_zone_id`, `vertebral_region_code`, `opens_view_id`, `laterality`) |
|
||
| `document.categories`, `vertebral_config` | all | marker colours, region names and counts |
|
||
| `document.finding_zones` | every zone `{id, name}`; for a zone referenced by any finding of the report, resolved or `unresolved`, its categories pruned to the referenced paths (`{id, kind, name}` and every node on the path `{id, name, requires_vet_referral}`, `description: {}`, `reference_ids: []`); other zones keep `categories: []` | group headings by id; the labels of every ancestor on a used path are preserved (+4 KB raw, +0.4 KB stored over empty trees) |
|
||
| `document.references` | `[]` | bibliography is not bilan data (15 KB) |
|
||
| `document.name`, `description`, `scope_disclaimer`, `attribution` | kept as is (1.4 KB) | sheet identity and legal scope of the historical sheet |
|
||
| `assets` | `[{ svg_asset_id, sha256, svg }]` for every asset reachable from a view | the drawing; `sha256` is the catalog's content address copied from the seed manifest (`assets.json`), carried by the bundle from now on, a provenance pointer and not a tamper check |
|
||
|
||
The SVG text goes **inline as a JSON string** (SVG is UTF-8 text: no base64
|
||
penalty, one attachment, one size cap, one parse). Separate embedded files
|
||
were rejected: the raw-object reader takes the first `EmbeddedFile`, and
|
||
several attachments multiply the stripping risk.
|
||
|
||
Rejected alternative: a dedicated `SheetSnapshotSchema`. It would force a
|
||
rewrite of every sheet lookup in the render path, leave `renderAnnotationLayer`
|
||
without a valid input, and lose the sheet integrity rules.
|
||
|
||
### 2.3 Envelope (attachment v1)
|
||
|
||
```json
|
||
{
|
||
"format": "faunosteo-report-archive",
|
||
"envelope_version": 1,
|
||
"exported_at": "2026-10-10T18:00:00.000Z",
|
||
"locale": "fr",
|
||
"report": { "version": 3, "...": "Report v3 unchanged" },
|
||
"sheet_snapshot": {
|
||
"status": "draft",
|
||
"ref": { "sheet_id": "…", "version_id": null, "document_sha256": "…", "schema_version": 2, "species_id": "equine", "name": { "fr": "…", "en": "…" } },
|
||
"document": { "schema_version": 2, "...": "lean AnatomicalSheetDocument" },
|
||
"assets": [ { "svg_asset_id": "…", "sha256": "…", "svg": "<svg …>" } ]
|
||
}
|
||
}
|
||
```
|
||
|
||
Report v3 is wrapped, not changed: no report version bump. Invariant written
|
||
and checked: `report.sheet.documentSha256 === sheet_snapshot.ref.document_sha256`
|
||
(see §3.5 for how the app keeps it true). Filename stays `osteo-report.json`
|
||
(CLAUDE.md); description becomes `Faunosteo report archive v1`; the PDF Info
|
||
dictionary gains `Keywords: faunosteo-archive/1` so a PDF whose attachment was
|
||
stripped by a viewer can still be recognised. Pretty-printed as today (an
|
||
extracted archive stays human-readable). `locale` and `exported_at` make the
|
||
attachment differ between locale variants: BDR-014's "byte-identical JSON"
|
||
note is superseded on that point, the report inside stays identical.
|
||
|
||
### 2.4 Measured sizes (equine draft, pretty JSON, deflate 6 ≈ pdf-lib Flate)
|
||
|
||
| Envelope | Raw | Stored |
|
||
|---|---|---|
|
||
| 3-observation fixture, lean document + SVG | 172 KB | 51 KB |
|
||
| Worst case 27 zones × 3 findings, both views | 228 KB | 54 KB |
|
||
| Lean document alone, 3 observations | 29 KB | 4 KB |
|
||
| Full document (bibliography included) + SVG, alternative | 464 KB | 79 KB |
|
||
| SVG alone, as a JSON string | 138 KB | 47 KB |
|
||
|
||
The drawing is 90% of the stored size. The 250 KB target holds on the raw
|
||
size (worst case 228 KB) and with a 4× margin on the stored size. Data
|
||
conservation wins over size: nothing in §2.2 is dropped to fit.
|
||
|
||
---
|
||
|
||
## 3. Target architecture
|
||
|
||
### 3.1 One sheet input for the engine: the snapshot
|
||
|
||
```
|
||
app export : LoadedSheet + Report ──buildSheetSnapshot()──▶ SheetSnapshot ─┐
|
||
archive re-export: envelope.sheet_snapshot ─────────────────────────────────────┤
|
||
▼
|
||
exportReportArchive({ report, sheet, branding, locale, rasterizer, exportedAt }) ─▶ { pdf, warnings }
|
||
```
|
||
|
||
The engine builds its `SheetIndex` from the snapshot and never sees a live
|
||
sheet. The app builds the snapshot from the loaded sheet at export; an archive
|
||
re-export passes `envelope.sheet_snapshot` as is. The attachment embeds exactly
|
||
what the engine consumed.
|
||
|
||
Label policy, identical to today's output:
|
||
|
||
- zone name = snapshot annotation name by id (trigger: the opened view's
|
||
name), else the report's zone snapshot in the requested locale, else the id;
|
||
`unresolved` is never consulted;
|
||
- finding group heading = snapshot finding-zone name by id, else the id
|
||
upper-cased (as today);
|
||
- finding text and the `(!)` marker always come from the report (BDR-010);
|
||
- views: unique view ids of the observation present in the snapshot, main
|
||
first; an unknown view prints no image, as today.
|
||
|
||
### 3.2 Packages and moved code
|
||
|
||
| Package | Content |
|
||
|---|---|
|
||
| `packages/domain` | `archive/envelope.ts`: `ReportArchiveEnvelopeSchema` (v1, metadata tolerant to unknown keys, `report` and `sheet_snapshot` at fixed keys), snapshot caps, `readArchiveDocument(data, map)` with layered reading (§4), `ArchiveReadError`; `archive/snapshot.ts`: `buildSheetSnapshot(loadedSheet, report)` (pure: prune trees, empty references, pick assets), `assertSnapshot(snapshot)` (schema, caps, `validateSheetDocument` with no error, every view reaches an asset present in `assets`); `anatomical-sheet/sheet-index.ts`: `buildSheetIndex`, `pickLabel`, `isObservable` moved from `apps/app/src/services/sheetIndex.ts` (the app re-exports them); `report/rebase.ts`: `rebaseReportOnSheet(report, index, archivedSnapshot?)` (§3.5) |
|
||
| `packages/anatomy` | `render/compose.ts`: `composeViewSvg({ assetRoot, document, viewId, highlight })` promoted from `curation/app-review.ts` (xmldom), highlight applied on the `LayerElement` tree before it becomes DOM (fill `#b85a3f`, opacity 0.85, `osteo-halo` filter on the main view, unselected markers dropped, no `data-*`, `<title>` kept); the curation review drawing calls it with no highlight |
|
||
| `packages/pdf` (new, `@faunosteo/pdf`) | the engine: `exportReportArchive`, `readReportArchive`; `render/*` moved as is (metadata, fonts, pages, header, footer, text, link annotations, constants); `svg/sanitize.ts` (allowlist, xmldom, §6); `svg/view.ts` (parse → sanitise → compose → serialise, raster size from the view box); `attachment/{write,read,inflate}.ts`; `text.ts` (`safeText`, §6); `dates.ts` (`formatDate` copy, never throws on a free string); `i18n/{fr,en}.ts` (verbatim copies of today's `pdf.*`, `severity.*`, `lateral.*`, `footer.powered_by`, `footer.in_partnership`); types `Branding`, `Rasterizer`, `ExportInput`, `ExportResult`. `tsconfig`: `lib: ["ES2022"]`, `types: ["node"]`; ESLint on `src/**`: `no-restricted-globals` (`fetch`, `window`, `document`, `Image`, `DOMParser`, `XMLSerializer`, `navigator`, `Buffer`, `process`, `require`) and `no-restricted-imports` (`@/*`, `react`, `node:*`); vitest `environment: node` |
|
||
| `apps/app/src/pdf` (shrinks) | `export.ts` (snapshot + branding + browser rasterizer → engine; download unchanged), `import.ts` (engine read → `ImportError` kinds, BDR-015), `browserRasterizer.ts` (today's `svgToPng`), `branding.ts` |
|
||
| `apps/app/scripts` | `report:compare` moved onto the engine read API (unchanged options) |
|
||
|
||
Dependencies added:
|
||
|
||
- `@xmldom/xmldom` 0.9.x as a runtime dependency of `packages/pdf` and
|
||
`packages/anatomy` (`compose.ts`), pinned: parse, sanitise, compose and
|
||
serialise without a browser, in the browser too (one code path). Already in
|
||
the workspace as a devDependency of `packages/anatomy` (0.9.12). Unminified
|
||
276 KB / 71 KB gzipped, 43 KB of which is the HTML entity table; expected
|
||
35–45 KB gzipped in the app bundle, measured in Phase 3 with a stated
|
||
ceiling of 50 KB, else the browser keeps the native DOM for composition.
|
||
Parsed with an `onError` that throws on `error` and `fatalError` and never
|
||
logs raw input. Watched by `pnpm audit --prod`.
|
||
- `@resvg/resvg-js` as a **devDependency** of `packages/pdf` (D6): real
|
||
rasterisation in Node for one end-to-end test. Native prebuilt binaries
|
||
(lockfile must carry `linux-x64-musl` for the Docker builder stage, where
|
||
the unfiltered install pulls it; the runtime image is nginx and unaffected).
|
||
|
||
No text-extraction dependency: drawn-text goldens reuse the
|
||
`PDFPage.prototype.drawText` spy pattern (LRN-033).
|
||
|
||
### 3.3 Browser-free guarantees
|
||
|
||
1. Compile-time: `packages/pdf` has no `DOM` lib, so `document`, `Image`,
|
||
`DOMParser` do not type-check.
|
||
2. Lint-time: restricted globals and imports on `src/**` (tests may read
|
||
fixtures with `node:fs`).
|
||
3. Test-time: the engine suite runs under vitest `environment: node` with no
|
||
Vite sheet plugin, so nothing can reach the bundled sheet.
|
||
4. Rasterisation is an adapter:
|
||
`type Rasterizer = (svg: string, size: { widthPx: number; heightPx: number }) => Promise<Uint8Array>`.
|
||
The engine computes the size (width 1200 px, height from the view box,
|
||
aspect clamped to [0.2, 2.0]) and degrades per view: a failed raster gives
|
||
a page without that image and a `warnings` entry, never a failed export.
|
||
Logos degrade one by one as today.
|
||
|
||
### 3.4 Branding as explicit input
|
||
|
||
```ts
|
||
interface Credit { logoPng: Uint8Array | null; url: string; fallbackText: string }
|
||
interface Branding {
|
||
siteUrl: string;
|
||
headerLogoPng: Uint8Array | null;
|
||
footerLogoPng: Uint8Array | null;
|
||
poweredBy: Credit | null; // today: ZenQuality, 70×16 pt
|
||
partner: Credit | null; // today: Paws in Harmony, aspect-derived width
|
||
}
|
||
```
|
||
|
||
The app assembles it once per export in `branding.ts`: PNG bytes from
|
||
bundled assets (`?url` import + fetch inside the app, allowed there), the Paws
|
||
SVG rasterised with the browser rasterizer before the engine runs, URLs and
|
||
fallback handles as app constants (none of them is an identity string of
|
||
`ConfigProvider`; the PDF prints no site name). Branding is **not** embedded in
|
||
the archive: brand assets are the publisher's, not bilan data, and a re-export
|
||
uses the branding it is given.
|
||
|
||
### 3.5 Import flow and the sheet invariant
|
||
|
||
`readReportArchive(pdfBytes, migrationMap)` returns
|
||
`{ report, snapshot | null, origin: 'envelope_v1' | 'bare_v3' | 'v2', migrated, unresolvedZones, unresolvedFindings, snapshotRejected?: SnapshotRejection }`
|
||
with `SnapshotRejection = 'unsupported_envelope' | 'schema' | 'caps' | 'integrity' | 'sheet_mismatch'`
|
||
(a closed enum: no received value is echoed). Attachment selection: the
|
||
Filespec whose `/F` starts with `osteo-report` first, then the first
|
||
`EmbeddedFile` (today's behaviour as fallback); the dead `getAttachments`
|
||
branch is removed. A PDF stamped `faunosteo-archive/1` with no attachment
|
||
gives the new `ImportError` kind `attachment_stripped` (message: the viewer or
|
||
optimiser removed the data; re-export from the original).
|
||
|
||
**Invariant and rebase.** The editor always works on the loaded sheet. When a
|
||
report arrives whose `report.sheet.documentSha256` differs from the loaded
|
||
ref (import of any archive, or a session draft restored after the bundle
|
||
changed), the app calls `rebaseReportOnSheet(report, index, archivedSnapshot?)`:
|
||
|
||
- a zone whose `annotationId` is absent from the loaded sheet, or whose
|
||
`viewId` is unknown, gets `unresolved: true`; its label snapshots are filled
|
||
from the archived snapshot when present (labels survive the rebase);
|
||
- a finding whose `(findingZoneId, path)` has no node in the loaded sheet gets
|
||
`unresolved: true` (same semantics as the v2 migration);
|
||
- `report.sheet` becomes the loaded ref; counts are returned and the existing
|
||
partial-import alert pattern shows them (new key `home.import.rebased`,
|
||
wording to validate: "Bilan établi sur une autre version de la fiche.
|
||
Éléments non retrouvés : {count} (conservés avec leurs libellés).").
|
||
|
||
Export then refuses when the invariant does not hold (`ArchiveExportError
|
||
'sheet_mismatch'`), which cannot happen through the app once rebase runs on
|
||
every entry path. An envelope whose two references disagree is imported with
|
||
`snapshotRejected: 'sheet_mismatch'`.
|
||
|
||
The imported snapshot is not kept in the session (D8): once rebased, the
|
||
report lives on the current sheet, the original PDF remains the historical
|
||
rendering, and autonomy is exercised by the engine API and the tests.
|
||
|
||
---
|
||
|
||
## 4. v2 / v3 archive compatibility
|
||
|
||
Layered reading, so the report is never lost because of its wrapper:
|
||
|
||
1. Locate the report: `data.report` when `data.envelope_version` is numeric,
|
||
else `data` itself (bare).
|
||
2. Parse the report with `readReportDocument` (v3 parsed, v2 migrated with the
|
||
bundled map, any other `version` → `incompatible_version` with the report
|
||
version found). `foundVersion` always names a **report** version, so the
|
||
existing UI message stays true.
|
||
3. Parse the envelope metadata tolerantly (unknown keys ignored within v1).
|
||
`envelope_version` other than 1 → `snapshotRejected: 'unsupported_envelope'`,
|
||
report kept. Then parse `sheet_snapshot` strictly (document schema v2,
|
||
caps, integrity, assets reachable, `sheet_mismatch`); any failure →
|
||
`snapshotRejected` with its reason, report kept.
|
||
|
||
| Archive | Produced by | Import | Re-export |
|
||
|---|---|---|---|
|
||
| v2 bare report | app before Step 5 | migrated with the map; unresolved items flagged, snapshots and legacy ids kept; then rebased (no-op when the map's sheet is the loaded one) | envelope v1 on the current sheet snapshot; unresolved items print from their snapshots |
|
||
| v3 bare report | Step 5 develop | parsed, `snapshot: null`, rebased if the draft changed since | as above |
|
||
| envelope v1 | Step 6 | report parsed first, snapshot validated or rejected with a reason, rebased if the sheet changed | from the embedded snapshot, no sheet needed |
|
||
| envelope v≥2 | future | report imported if its version is known, `snapshotRejected: 'unsupported_envelope'` | — |
|
||
| report v≠2,3 | future | `incompatible_version` with that version | — |
|
||
|
||
Durability rule: archive readers never drop a schema version. Sheet document
|
||
schema v2 stays readable in `packages/domain` for as long as envelope v1
|
||
archives exist, exactly as Report v2 stays readable today. Forward rule:
|
||
additive optional fields keep `envelope_version: 1` (readers ignore unknown
|
||
metadata keys); a breaking change bumps it and the reader keeps every older
|
||
version. A rollback to a pre-Step-6 app reads an envelope as `no_attachment`;
|
||
DEPLOY.md records that limit.
|
||
|
||
A v2 archive has no legacy sheet snapshot. Its own pages are the historical
|
||
rendering; the attachment serves data recovery. Building a "legacy snapshot"
|
||
from `legacy-import/` for a faithful re-render of v2 bilans is possible (the
|
||
baseline document and the two legacy SVGs are in the repo) but not proposed:
|
||
no external users, BDR-038 rejected v3→v2 work, and the printed PDF already
|
||
holds the picture. D4 covers keeping the original v2 JSON.
|
||
|
||
Fixtures: the two frozen v2 PDFs stay; Phase 0 freezes, with the current code
|
||
(LRN-043): a **v3 bare golden** PDF, a **demo report** `report-v3.demo.json`
|
||
(6 observations: main and head views, vertebrae, bilateral sides, a
|
||
vet-referral leaf, a leaf label with an en dash, free text, next appointment)
|
||
and a **migrated v2 report with unresolved items** (sphenoid / ssb leaves
|
||
reached only through unresolved paths).
|
||
|
||
---
|
||
|
||
## 5. Re-export without current resources
|
||
|
||
`exportReportArchive({ report: envelope.report, sheet: envelope.sheet_snapshot, branding, locale, rasterizer, exportedAt })`
|
||
is the whole answer: no sheet provider, no Vite, no browser, no network. The
|
||
labels, drawings, colours, crops and relations come from the snapshot; the
|
||
finding texts from the report; the only external inputs are the branding and
|
||
the locale. Test T1 (§7) performs exactly this call in a Node environment
|
||
where no sheet exists. A future server worker runs the same call.
|
||
|
||
An operator CLI (`report:reexport`) is **not** planned in this step (D12): the
|
||
test proves the property, and a CLI is a public command name plus a file
|
||
writer over untrusted content (output names must derive from the input file
|
||
name, `wx` open, LRN-044 escaping, resvg under memory and time limits).
|
||
|
||
---
|
||
|
||
## 6. Size and security limits
|
||
|
||
Write side (new): `buildSheetSnapshot` output goes through `assertSnapshot`
|
||
(schema, caps, integrity, assets present, sanitiser acceptance of every asset,
|
||
sheet invariant) and the serialised envelope must stay under the 16 MiB
|
||
attachment cap; otherwise the export fails with a typed `ArchiveExportError`
|
||
(`snapshot_invalid | snapshot_too_large | sheet_mismatch | too_many_pages`)
|
||
and an alert, never a file that cannot be read back. The equine draft is 60×
|
||
under every cap. Step 13 must align the catalog's asset cap with the archive
|
||
cap (BDR-032 allows 20 MiB assets today).
|
||
|
||
Caps (checked on both sides, Zod and counters):
|
||
|
||
| Item | Cap |
|
||
|---|---|
|
||
| PDF file | 50 MiB (existing) |
|
||
| attachment, raw and inflated | 16 MiB (existing, bomb guard) |
|
||
| assets | ≤ 4 per snapshot, ≤ 2 MiB each, ≤ 6 MiB total |
|
||
| document | ≤ 64 views, ≤ 1,024 annotations, ≤ 8,192 finding nodes, depth ≤ 8 (pre-checked before the recursive schema), labels ≤ 512 chars |
|
||
| report at export | ≤ 500 observations, ≤ 8 views per observation (`too_many_pages`) |
|
||
| sanitiser | ≤ 20,000 elements, nesting ≤ 64, ≤ 256 `<use>`, filter `stdDeviation` ≤ 50 |
|
||
| raster | width 1200 px, aspect clamped to [0.2, 2.0] (an untrusted root `viewBox` cannot request a 120-million-pixel canvas) |
|
||
|
||
SVG sanitiser (`packages/pdf/src/svg/sanitize.ts`, xmldom, used at export on
|
||
the bundled asset and at re-export on the archived one; the app canvas is out
|
||
of scope, EVAL-011 keeps it for Step 13):
|
||
|
||
- the text is refused if it contains `<!DOCTYPE` or `<!ENTITY`;
|
||
- element allowlist, enumerated from the real inventory of `horse.svg` plus
|
||
structural needs: `svg g path circle ellipse rect line polyline polygon defs
|
||
linearGradient radialGradient stop filter feGaussianBlur feMerge feMergeNode
|
||
feOffset feFlood feComposite feBlend feColorMatrix clipPath mask title desc
|
||
switch use`; no `style`, `script`, `image`, `a`, `foreignObject`, `text`,
|
||
`feImage`, `feTurbulence`, `feConvolveMatrix`;
|
||
- attribute allowlist from the same inventory: `id`, geometry, presentation
|
||
(`fill stroke* opacity fill-opacity fill-rule transform style`), gradient
|
||
and filter attributes (`gradientUnits gradientTransform offset stop-color
|
||
stop-opacity in in2 result stdDeviation color-interpolation-filters x y
|
||
width height`), `viewBox`, `xmlns*`, `systemLanguage` (the `<switch>`),
|
||
`font-*`; no `on*`; `href`/`xlink:href` and `url(…)` values must be
|
||
`#fragment`; `style` attributes may not contain `url(` other than `#`,
|
||
`expression(` or `@import`;
|
||
- returns the list of removals; the engine logs nothing from it and the test
|
||
on `horse.svg` asserts an empty list and a byte-identical serialisation.
|
||
|
||
Other guards: strict document schema, `Object.hasOwn` on records, depth
|
||
pre-check, no new PII in the envelope (export date, locale). WinAnsi: one text
|
||
ingress `safeText()` used by measurement and drawing, testing each code point
|
||
with `Encodings.WinAnsi.canEncodeUnicodeCodePoint` (en and em dashes are
|
||
encodable and must survive), replacing the rest by `?` and stripping control
|
||
characters; a canary test covers `⚠`, `→`, an emoji, `\t`, U+2028 (restores
|
||
the lost EVAL-003 test). `formatDate` never throws: a non `YYYY-MM-DD` string
|
||
is printed as is.
|
||
|
||
---
|
||
|
||
## 7. Tests that prove autonomy
|
||
|
||
Phase 0 goldens and characterisation tests, frozen with the current code
|
||
before any change:
|
||
|
||
- G1 drawn-text sequence per page, FR and EN, for: the v2 full fixture, the
|
||
demo report, the migrated v2 report with unresolved items. Two harness
|
||
modes: logos absent (fetch 404, as today) and logos present (fetch stub
|
||
returning the real PNG bytes from `public/`, Paws raster stubbed).
|
||
- G2 per view, structural: `viewBox`, highlighted ids with
|
||
`fill`/`fill-opacity`/`filter`, hidden marker count, halo filter on the main
|
||
view only, no `data-*` left; plus image placements `(page, x, y, w, h)` and
|
||
link annotations `(page, Rect, URI)`.
|
||
- G3 `report-v3.bare.pdf` exported by Step 5 code (import fixture only).
|
||
- T12 `HomeRoute` import: v2 alert with count, error kinds to messages,
|
||
navigation. T13 `EditorRoute` export: call arguments, download name.
|
||
Both written now on the current routes and kept green unchanged.
|
||
|
||
Engine (`packages/pdf`, node environment):
|
||
|
||
- T1 **No-sheet re-export**: export the demo report through the app path →
|
||
read the envelope → `exportReportArchive` from the envelope alone → same G1
|
||
text, same G2 facts, same envelope minus `exported_at` (the written snapshot
|
||
is `assertSnapshot`'s parsed output, so key order is stable).
|
||
- T3 G1/G2 equality between the new engine and the Phase 0 goldens in both
|
||
logo modes: proof of "no visible change".
|
||
- T4 roundtrip envelope → import → `toEqual` report and snapshot.
|
||
- T5 v2 fixtures import (29 unresolved on the 612-leaf report, zones `[]`
|
||
everywhere, so an empty-views observation must export) → re-export →
|
||
import again equals; G3 imports with `snapshot: null`.
|
||
- T6 versions: envelope v2 with report v3 → report imported,
|
||
`snapshotRejected: 'unsupported_envelope'`; envelope v1 with report v4 →
|
||
`incompatible_version` 4; bare v7 → `incompatible_version` 7.
|
||
- T7 size: demo envelope stored < 250 KB, raw size printed.
|
||
- T8 security: 5 assets, a 3 MiB asset, depth 9, 1,025 annotations, a
|
||
view chain cycle, a dangling `svg_asset_id`, `sheet_mismatch` → the report
|
||
imports and `snapshotRejected` names the reason; hostile SVG (`<script>`,
|
||
`onload`, `javascript:` href, external `<image>`, `<!ENTITY>`, `<style>`
|
||
with `url(http…)`, 257 `<use>`, a root `viewBox` of `0 0 1 100000`)
|
||
stripped, refused or clamped; `__proto__` ids; 24 MB inflate bomb
|
||
(existing); export-side: a snapshot over caps fails the export with a typed
|
||
error and no file.
|
||
- T9 WinAnsi canary (§6) on labels, user text, branding fallback text.
|
||
- T10 real raster (resvg) on the demo report: PNG dimensions follow the
|
||
1200 px rule and the clamp, highlight colour present, non-white ratio in
|
||
range for main and head views; a raster failure yields a page without image
|
||
and one warning.
|
||
- T11 (CI, not a test): `pnpm typecheck` and `pnpm lint` of `packages/pdf`
|
||
pass with no DOM lib and the restricted globals.
|
||
|
||
App:
|
||
|
||
- T2 **Catalog changed**: mutate the loaded sheet's labels and one geometry,
|
||
re-export the frozen envelope through the app's engine call → G1/G2 of the
|
||
envelope, not of the mutated sheet.
|
||
- T12, T13 kept green; T15 rebase: import a v3 archive whose `documentSha256`
|
||
differs → unresolved flags, labels filled from the archived snapshot,
|
||
`report.sheet` updated, alert shown; draft restore path covered too.
|
||
- T14 i18n parity: the engine dict FR/EN share one key set; app dicts stay in
|
||
parity after losing `pdf.*`.
|
||
|
||
Manual validation: export the demo report in FR and EN, open in two viewers,
|
||
check pages and the attachment panel (`osteo-report.json`), import on a fresh
|
||
tab, import a pre-Step-5 v2 PDF, re-import the exported file after
|
||
`pnpm import:equine` changed the draft and read the rebase alert.
|
||
|
||
---
|
||
|
||
## 8. Visible changes
|
||
|
||
In the PDF pages: **none** by default; T3 enforces it. Proposed, not planned:
|
||
|
||
- V1 provenance line in the footer or on the conclusion page: sheet name,
|
||
version and status ("Fiche équine, brouillon v1") and export date. Useful
|
||
on paper, honest about the draft status. Needs validation.
|
||
- V2 marker on items printed from snapshots because the sheet no longer holds
|
||
them, for example `(?)` before the label, mirroring the `(!)` vet marker.
|
||
Needs validation.
|
||
|
||
Outside the pages: attachment description "Faunosteo report archive v1" and
|
||
the `Keywords` stamp in the PDF properties; in the app, two new messages
|
||
(`home.import.rebased`, `home.import.error_attachment_stripped`), wording to
|
||
validate.
|
||
|
||
---
|
||
|
||
## 9. Decisions to validate
|
||
|
||
| # | Decision | Recommendation | Alternative |
|
||
|---|---|---|---|
|
||
| D1 | Finding trees in the snapshot | pruned to the paths the report uses, ancestor labels kept (+4 KB raw) | empty trees (ids and leaf labels only, in the report) |
|
||
| D4 | v2 provenance | do not embed the original v2 JSON in re-exports (the original PDF remains the record; the migration is reversible through the committed map) | optional `origin` block with the verbatim v2 document |
|
||
| D6 | Node rasterizer | `@resvg/resvg-js` devDependency for T10 | no real raster in Node (structure tests only) |
|
||
| D7 | Branding | explicit input, not archived | archive the branding bytes (+90 KB per PDF) |
|
||
| D8 | Imported snapshot in the app | not kept; report rebased onto the loaded sheet with the alert of §3.5 | keep it in the session and offer "re-export the archive as is" (new UI) |
|
||
| D10 | Visible changes V1, V2 | none in this step | V1 and/or V2 |
|
||
| D12 | `report:reexport` CLI | not in this step | add it, envelope v1 only, with the file-writing rules of §5 |
|
||
| D13 | New app messages | `home.import.rebased` and `error_attachment_stripped` as worded in §3.5 and §8 | other wording |
|
||
|
||
Settled in this plan (no observable effect): inline SVG text, lean-document
|
||
snapshot shape, xmldom composition everywhere, engine-owned dictionary,
|
||
demo report as the DoD reference, `exportedAt` as an input (no clock
|
||
abstraction).
|
||
|
||
---
|
||
|
||
## 10. Risks
|
||
|
||
| Risk | Mitigation |
|
||
|---|---|
|
||
| xmldom serialisation differs from `XMLSerializer` | G2 compares structural facts, not strings; T10 covers pixels; the browser rasterizer re-parses anyway |
|
||
| xmldom bundle cost above 50 KB gzipped | measured in Phase 3; fallback: native DOM composition in the browser behind the same `composeViewSvg` signature |
|
||
| resvg renders the 81 Gaussian-blur filters or `<switch>` differently from Chromium | T10 asserts structure, not pixels; the browser stays the production rasterizer |
|
||
| Moving render code touches 8 modules and 6 test files | one-to-one test migration with the replacing test named (Step 1 rule) |
|
||
| Rebase marks items unresolved that only moved on the drawing | by design: ids that survive stay resolved; the alert reports counts only |
|
||
| A future sheet with several large assets | per-asset and total caps with an export-time typed error; Step 13 aligns the catalog cap |
|
||
| Allowlist strips legitimate content of a future asset silently | the sanitiser returns its removals; Step 13 runs it at upload and fails there (TODO recorded as a `shortcut:`) |
|
||
|
||
---
|
||
|
||
## 11. Plan
|
||
|
||
Executors as in Step 5: one executor per phase with a closed contract, TDD,
|
||
fresh verifier and security gates at the end, no publication, no graphic
|
||
redesign. Branch `feature/step-06-pdf-archives`.
|
||
|
||
**Phase 0 — Freeze (current code, nothing else changes)**
|
||
- 0.1 fixtures: `report-v3.demo.json`, migrated-v2-with-unresolved report
|
||
builder, G3 `report-v3.bare.pdf`
|
||
- 0.2 goldens G1 (both logo modes), G2 (structural facts, placements, links);
|
||
one-shot `MAKE_GOLDEN=1` run, generator deleted (LRN-043)
|
||
- 0.3 characterisation tests T12 (HomeRoute import) and T13 (EditorRoute
|
||
export)
|
||
|
||
**Phase 1 — Domain: snapshot, envelope, rebase**
|
||
- 1.1 `anatomical-sheet/sheet-index.ts` moved from the app (re-export kept)
|
||
- 1.2 `archive/snapshot.ts`: `buildSheetSnapshot`, `assertSnapshot`, caps
|
||
- 1.3 `archive/envelope.ts`: schema v1, `readArchiveDocument` layered
|
||
reading, `ArchiveReadError`, `SnapshotRejection`
|
||
- 1.4 `report/rebase.ts`: `rebaseReportOnSheet`
|
||
- 1.5 bundle carries the asset manifest sha and the sheet `status`/`name`
|
||
(`vite/sheet-bundle.ts`, `sheets/provider.ts`, `LoadedSheet`)
|
||
- 1.6 tests: pruning on the draft (counts, bytes), `validateSheetDocument`
|
||
clean on the lean document, caps, dispatch table of §4, rebase cases
|
||
|
||
**Phase 2 — Anatomy: composer**
|
||
- 2.1 `render/compose.ts` promoted from `curation/app-review.ts`, highlight
|
||
on the layer tree; review drawing unchanged (golden test proves it)
|
||
|
||
**Phase 3 — Engine `packages/pdf`**
|
||
- 3.1 scaffold: manifest, tsconfig, lint rules, vitest node, Dockerfile
|
||
manifest copy, CI, `packages/README.md` (fix its two wrong lines while
|
||
there)
|
||
- 3.2 `svg/sanitize.ts` + `svg/view.ts`; `horse.svg` zero-removal test;
|
||
hostile cases
|
||
- 3.3 render modules moved; `Branding`, `Rasterizer`, `exportedAt`,
|
||
`safeText`, dict; parallel rasterisation then sequential embedding
|
||
- 3.4 `exportReportArchive` (snapshot-based index, label policy §3.1,
|
||
per-view degradation, caps, envelope write, Keywords stamp) → T3 in both
|
||
logo modes
|
||
- 3.5 `readReportArchive` (filename-first selection, inflate cap, layered
|
||
reading, `attachment_stripped`) → T4, T5, T6, T8
|
||
- 3.6 T1, T7, T9, T10 (resvg), T11; bundle-size measurement of xmldom
|
||
|
||
**Phase 4 — App integration**
|
||
- 4.1 `browserRasterizer.ts`, `branding.ts`, `export.ts` and `import.ts`
|
||
rewritten on the engine; rebase on import and on draft restore; two new
|
||
messages
|
||
- 4.2 old `src/pdf/render`, `attachment.ts`, `anatomy/drawing.ts` highlight
|
||
code and `pdf.*` app keys removed; `report:compare` on the engine read API
|
||
- 4.3 T2, T14, T15; T12/T13 green unchanged; app suite migrated one-to-one
|
||
|
||
**Phase 5 — Docs and gates**
|
||
- 5.1 `docs/PDF-FORMAT.md` written for real (pages, envelope v1, snapshot
|
||
content, caps, read order, compatibility table, rebase rule, CLI);
|
||
CLAUDE.md folder map and conventions; `WORKSPACE.md` package rule corrected
|
||
(tests under `tests/`); DEPLOY.md rollback note; CHANGELOG; BDR-014 note
|
||
- 5.2 `pnpm check`, docker build, verifier and security gates, EVAL
|
||
- 5.3 manual validation list (§7) for the user
|
||
|
||
Definition of Done: no fetch and no DOM in `packages/pdf` (compile, lint,
|
||
tests); T1–T15 green; Phase 0 goldens reproduced in both logo modes; demo
|
||
envelope < 250 KB stored and raw; `docs/PDF-FORMAT.md` complete; v2 fixtures
|
||
import and re-export; rebase alert shown when the draft changed.
|
||
|
||
---
|
||
|
||
# Part II — Implementation contract (validated 2026-10-11)
|
||
|
||
The user validated Part I on 2026-10-11 with three adjustments, recorded here
|
||
as the binding contract for the executors. Where Part I and Part II differ,
|
||
Part II wins.
|
||
|
||
## 12. Validated adjustments
|
||
|
||
- **D7 (branding).** The engine receives its branding explicitly and never
|
||
fetches. The archive **also stores the branding used at export** (logos,
|
||
partner credits, URLs, fallback texts) and the **label dictionary** (both
|
||
locales), so a future logo, wording or configuration change cannot alter
|
||
the reproduction of an old archive. Compact and safe representation, no
|
||
duplicated resource inside the envelope. Cost measured and reported.
|
||
- **D8 (imported snapshot).** The archive carried by an imported PDF is
|
||
**kept in the session**, immutable. Two operations are distinct in the
|
||
architecture: (1) re-read or re-export an archive from its own snapshot,
|
||
branding and labels, no rebase; (2) resume a bilan for editing on the
|
||
current sheet: an explicit rebase on a **working copy**, historical labels
|
||
of unresolvable items preserved. No new significant UI in this step: the
|
||
technical support (store, persistence, engine API) ships and the UX choice
|
||
for operation (1) is submitted to the user after the step.
|
||
- **D10, D12.** No change to the pages. No `report:reexport` CLI.
|
||
- **D13 (messages).** Explicit FR/EN messages for: an archive imported with
|
||
its snapshot; a snapshot rejected while the report was recovered; a rebase
|
||
with its count; a stripped attachment. A partial or degraded import is
|
||
never presented as a perfect restoration.
|
||
- **D1, D4, D6** as recommended in §9.
|
||
|
||
## 13. Types (TypeScript, authoritative)
|
||
|
||
All JSON contracts below are **camelCase**, like Report v3 and `SheetRef`;
|
||
the `AnatomicalSheetDocument` inside keeps its own snake_case schema.
|
||
|
||
```ts
|
||
// packages/domain/src/archive/snapshot.ts
|
||
export interface SheetSnapshotRef { // sheet-ref.json, camelCase
|
||
sheetId: string; versionId: string | null; documentSha256: string /^[0-9a-f]{64}$/;
|
||
schemaVersion: number; speciesId: string;
|
||
}
|
||
export interface SheetSnapshotAsset { svgAssetId: string; sha256: string | null; svg: string }
|
||
export interface SheetSnapshot {
|
||
status: 'draft' | 'published';
|
||
ref: SheetSnapshotRef;
|
||
document: AnatomicalSheetDocument; // lean, valid (schema v2, strict)
|
||
assets: SheetSnapshotAsset[];
|
||
}
|
||
export const SheetSnapshotSchema: z.ZodType<SheetSnapshot> // strict + caps (§15)
|
||
export function buildSheetSnapshot(sheet: SnapshotSource, report: Report): SheetSnapshot
|
||
export interface SnapshotSource { // what LoadedSheet provides
|
||
status: 'draft' | 'published'; ref: SheetSnapshotRef; document: AnatomicalSheetDocument;
|
||
assets: Readonly<Record<string, string>>; // svg text by svgAssetId
|
||
assetHashes?: Readonly<Record<string, string>>; // sha256 by svgAssetId (seed manifest)
|
||
}
|
||
export function assertSnapshot(snapshot: SheetSnapshot): SheetSnapshot
|
||
// SheetSnapshotSchema.parse, validateSheetDocument(document) has no 'error' issue,
|
||
// every view resolves (own asset or parent chain) to an asset present in `assets`,
|
||
// document depth pre-check; throws SnapshotError(reason: SnapshotRejection)
|
||
export type SnapshotRejection = 'unsupported_envelope' | 'schema' | 'caps' | 'integrity' | 'sheet_mismatch'
|
||
|
||
// packages/domain/src/archive/envelope.ts
|
||
export const ENVELOPE_FORMAT = 'faunosteo-report-archive'
|
||
export const ENVELOPE_VERSION = 1
|
||
export interface ReportArchiveEnvelope {
|
||
format: typeof ENVELOPE_FORMAT; envelopeVersion: 1;
|
||
exportedAt: string; // ISO timestamp
|
||
locale: 'fr' | 'en';
|
||
report: Report; // v3, as exported (never rebased)
|
||
sheetSnapshot: SheetSnapshot;
|
||
branding: Branding;
|
||
labels: PdfLabelSet;
|
||
}
|
||
export const ReportArchiveEnvelopeSchema: z.ZodType<ReportArchiveEnvelope>
|
||
// metadata object is NOT strict (unknown keys ignored within v1); report, sheetSnapshot,
|
||
// branding, labels are parsed by their own schemas
|
||
export type ArchiveOrigin = 'envelope_v1' | 'bare_v3' | 'v2'
|
||
export interface ArchiveReadOutcome {
|
||
report: Report; origin: ArchiveOrigin; migrated: boolean;
|
||
unresolvedZones: number; unresolvedFindings: number; // from the v2 migration
|
||
archive: ReportArchiveEnvelope | null; // the validated envelope, when accepted
|
||
snapshotRejected?: SnapshotRejection; // envelope present but snapshot dropped
|
||
}
|
||
export function readArchiveDocument(data: unknown, map: ReportMigrationMap): ArchiveReadOutcome
|
||
// throws UnsupportedReportVersionError (existing) when the REPORT version is unknown
|
||
|
||
// packages/domain/src/archive/branding.ts
|
||
export type ImageAsset = { kind: 'png'; base64: string } | { kind: 'svg'; svg: string }
|
||
export interface Credit { logo: ImageAsset | null; url: string; fallbackText: string }
|
||
export interface Branding {
|
||
siteUrl: string;
|
||
headerLogo: ImageAsset | null; // today /assets/faunosteo_logo_horizontal-512.png
|
||
footerLogo: ImageAsset | null; // today /assets/faunosteo-horizontal-com-512.png
|
||
poweredBy: Credit | null; // today ZenQuality PNG, https://zenquality.fr, 'zenquality.fr'
|
||
partner: Credit | null; // today Paws SVG, instagram URL, '@paws.iin.harmony'
|
||
}
|
||
export const BrandingSchema: z.ZodType<Branding> // strict; base64 ≤ 512 KiB, svg ≤ 256 KiB,
|
||
// url http(s) only ≤ 2048, fallbackText ≤ 128
|
||
|
||
// packages/domain/src/archive/labels.ts
|
||
export const PDF_LABEL_KEYS = [ /* exactly the keys read by apps/app/src/pdf at HEAD: */
|
||
'pdf.empty','pdf.eyebrow.observation','pdf.eyebrow.synthesis','pdf.owner_prefix',
|
||
'pdf.section.comment','pdf.section.conclusion','pdf.section.findings_prefix',
|
||
'pdf.section.free_findings','pdf.section.next_appointment','pdf.section.recommendations',
|
||
'pdf.section.severity','pdf.section.zones','pdf.siret_prefix','pdf.subject',
|
||
'pdf.title.conclusion','pdf.title.suffix.bilan','pdf.view.detail_prefix','pdf.view.general',
|
||
'severity.mild','severity.moderate','severity.severe','lateral.left','lateral.right',
|
||
'footer.powered_by','footer.in_partnership' ] as const
|
||
export type PdfLabels = Record<(typeof PDF_LABEL_KEYS)[number], string>
|
||
export interface PdfLabelSet { fr: PdfLabels; en: PdfLabels }
|
||
export const PdfLabelSetSchema // strict, every key required, values ≤ 256 chars
|
||
|
||
// packages/domain/src/report/rebase.ts
|
||
export interface RebaseOutcome { report: Report; unresolvedZones: number; unresolvedFindings: number; rebased: boolean }
|
||
export function rebaseReportOnSheet(report: Report, index: SheetIndex, archived: SheetSnapshot | null): RebaseOutcome
|
||
// rebased=false and report returned as is when report.sheet.documentSha256 === index.sheet.ref.documentSha256
|
||
// else: zone with unknown annotationId or unknown viewId → unresolved: true, label snapshots
|
||
// filled from `archived` annotation names when absent; finding with no nodeAt(zoneId, path)
|
||
// → unresolved: true; items already unresolved stay; report.sheet = index.sheet.ref
|
||
|
||
// packages/domain/src/anatomical-sheet/sheet-index.ts (moved from apps/app/src/services/sheetIndex.ts)
|
||
export interface SheetIndexSource { ref: SheetSnapshotRef-compatible { documentSha256 }; document: AnatomicalSheetDocument; assets: Readonly<Record<string,string>> }
|
||
export { buildSheetIndex, pickLabel, isObservable, type SheetIndex, type ObservableAnnotation }
|
||
// SheetIndex.sheet is typed as the source given; LoadedSheet satisfies it; SheetSnapshot does
|
||
// through a one-line adapter (assets array → record). `pickLabel` takes 'fr' | 'en'.
|
||
|
||
// packages/pdf/src/index.ts
|
||
export type PdfLocale = 'fr' | 'en'
|
||
export type Rasterizer = (svg: string, size: { widthPx: number; heightPx: number }) => Promise<Uint8Array>
|
||
export interface ExportInput {
|
||
report: Report; sheet: SheetSnapshot; branding: Branding; labels: PdfLabelSet;
|
||
locale: PdfLocale; rasterizer: Rasterizer; exportedAt: Date;
|
||
}
|
||
export type ExportWarning =
|
||
| { kind: 'view_raster_failed'; observationId: string; viewId: string }
|
||
| { kind: 'logo_failed'; slot: 'headerLogo' | 'footerLogo' | 'poweredBy' | 'partner' }
|
||
export interface ExportResult { pdf: Uint8Array; envelope: ReportArchiveEnvelope; warnings: ExportWarning[] }
|
||
export function exportReportArchive(input: ExportInput): Promise<ExportResult>
|
||
// throws ArchiveExportError(kind: 'snapshot_invalid' | 'snapshot_too_large' | 'sheet_mismatch' | 'too_many_pages')
|
||
export function exportFromEnvelope(env: ReportArchiveEnvelope, opts: { locale: PdfLocale; rasterizer: Rasterizer; exportedAt: Date }): Promise<ExportResult>
|
||
// = exportReportArchive({ report: env.report, sheet: env.sheetSnapshot, branding: env.branding, labels: env.labels, ...opts })
|
||
export type ArchiveReadErrorKind = 'invalid_pdf' | 'no_attachment' | 'attachment_stripped' | 'incompatible_version'
|
||
export class ArchiveReadError extends Error { kind: ArchiveReadErrorKind; foundVersion?: number | null }
|
||
export function readReportArchive(pdfBytes: Uint8Array, map: ReportMigrationMap): Promise<ArchiveReadOutcome>
|
||
export function readAttachedDocument(pdfDoc: PDFDocument): Promise<unknown> // raw JSON, for the compare CLI
|
||
export const MAX_PDF_BYTES, MAX_ATTACHMENT_BYTES
|
||
export const defaultPdfLabels: PdfLabelSet // verbatim copy of today's FR/EN strings
|
||
export const PDF_KEYWORD = 'faunosteo-archive/1' // Info.Keywords stamp
|
||
```
|
||
|
||
## 14. Behaviour
|
||
|
||
**Export** (`exportReportArchive`): (1) `assertSnapshot(sheet)`; (2) refuse
|
||
when `report.sheet.documentSha256 !== sheet.ref.documentSha256`
|
||
(`sheet_mismatch`); (3) refuse `report.observations.length > 500` or any
|
||
observation with more than 8 distinct view ids (`too_many_pages`); (4) build
|
||
the envelope `{ format, envelopeVersion: 1, exportedAt, locale, report,
|
||
sheetSnapshot: sheet, branding, labels }`, serialise pretty (indent 2), refuse
|
||
above `MAX_ATTACHMENT_BYTES` (`snapshot_too_large`); (5) metadata: title,
|
||
author, subject (labels), creation and modification dates = `exportedAt`,
|
||
`setKeywords([PDF_KEYWORD])`; (6) fonts; (7) branding images: PNG → `embedPng`
|
||
(base64 decoded with `atob`), SVG → sanitise + rasterise at width 1200 px
|
||
(today's rule) → `embedPng`; each slot fails alone with a `logo_failed`
|
||
warning; (8) observation pages: rasterise every view of an observation in
|
||
parallel, then embed in view order (main first); a raster failure gives a
|
||
page without that image and a `view_raster_failed` warning; (9) conclusion
|
||
page, footer on every page, attach the envelope bytes as `osteo-report.json`
|
||
(`application/json`, description `Faunosteo report archive v1`, dates
|
||
`exportedAt`, `AFRelationship.Data`); (10) `save()`.
|
||
|
||
**Label policy** (§3.1, unchanged wording): zone name = snapshot annotation
|
||
name by id (trigger: opened view's name), else report zone snapshot in the
|
||
locale (other locale as fallback), else the id; finding group heading =
|
||
snapshot finding-zone name by id, else the id upper-cased; finding text and
|
||
`(!)` from the report; views = unique view ids of the observation present in
|
||
the snapshot, main first; `unresolved` never consulted; every printed string
|
||
goes through `safeText` (§15).
|
||
|
||
**View SVG** (`packages/pdf/src/svg/view.ts`): asset text refused if it
|
||
contains `<!DOCTYPE` or `<!ENTITY`; parsed with xmldom (`onError` throws on
|
||
`error` and `fatalError`); `sanitizeSvgRoot` (§15); `composeViewSvg` from
|
||
`@faunosteo/anatomy/render` with `highlight: { annotationIds, halo:
|
||
view.kind === 'main' }`; serialised; size = width 1200, height = round(1200 ×
|
||
vbH / vbW) with the ratio clamped to [0.2, 2.0], view box = `view.view_box`
|
||
?? root `viewBox` ?? 0.6 ratio (today's fallback).
|
||
|
||
**composeViewSvg** (`packages/anatomy/src/render/compose.ts`, promoted from
|
||
`curation/app-review.ts`, which now calls it with no highlight):
|
||
`({ root: Element, document, viewId, highlight?: { annotationIds: ReadonlySet<string>; halo: boolean } }) => Element`:
|
||
set `viewBox` from `viewBoxOf(view)` when present, remove `width`/`height`,
|
||
render the layer tree; with `highlight`: keep only layer elements whose
|
||
annotation id is selected, set `fill="#b85a3f"`, `fill-opacity="0.85"`, and
|
||
`filter="url(#osteo-halo)"` when `halo`, emit no `data-*` attribute, keep
|
||
`<title>`; when `halo`, ensure `<defs>` (created as first child when absent)
|
||
holds the `osteo-halo` filter exactly as `observationPage.ts:157-197`
|
||
(x/y −100%, width/height 300%, `filterUnits="userSpaceOnUse"`, blurs 18 and 8,
|
||
merge wide×3 + tight×2 + SourceGraphic); append the layer `<g>` last.
|
||
|
||
**Read** (`readReportArchive`): size cap → `PDFDocument.load` (`invalid_pdf`
|
||
on failure) → attachment: the Filespec whose `/F` starts with `osteo-report`,
|
||
else the first `EmbeddedFile`, inflating `FlateDecode` streams under the cap
|
||
(`inflateFlate`, kept) → none: `attachment_stripped` when
|
||
`getKeywords()` contains `faunosteo-archive`, else `no_attachment` → cap →
|
||
`JSON.parse` → `readArchiveDocument(data, map)`:
|
||
1. locate the report: `data.report` when `typeof data.envelopeVersion === 'number'`, else `data`;
|
||
2. `readReportDocument(report, map)` (existing: v3 parsed, v2 migrated, other
|
||
→ `UnsupportedReportVersionError(found)` → `incompatible_version`);
|
||
3. bare → `{ origin: 'bare_v3' | 'v2', archive: null }`; envelope with
|
||
`envelopeVersion !== 1` → `archive: null, snapshotRejected: 'unsupported_envelope'`;
|
||
envelope v1 → parse metadata + `sheetSnapshot` + `branding` + `labels`;
|
||
`BrandingSchema`/`PdfLabelSetSchema` failure → `'schema'`;
|
||
`assertSnapshot` failure → its reason; snapshot ref ≠ `report.sheet` →
|
||
`'sheet_mismatch'`; success → `archive` = the validated envelope.
|
||
Every other JSON failure → `no_attachment` as today.
|
||
|
||
**App session** (`reportStore.ts`, `persistence.ts`):
|
||
- state `{ report: Report | null; archive: ReportArchiveEnvelope | null; activeObservationIndex }`;
|
||
- `hydrateReport(report)` kept (archive → null); new
|
||
`hydrateImport({ report, archive })`; `initReport` and `reset` clear `archive`;
|
||
- persistence: `osteo:draft` as today; `osteo:archive` written on
|
||
`hydrateImport`/`reset`/`initReport` only (not on every edit), restored with
|
||
the draft; `ArchivePersistence` beside `ReportPersistence`;
|
||
- `restoreDraft(index: SheetIndex)` loads the draft then rebases it on the
|
||
index when its sha differs (counts returned to the caller).
|
||
- `HomeRoute`: `readReportArchive` through `apps/app/src/pdf/import.ts`
|
||
(maps `ArchiveReadError` kinds to `ImportError` kinds, four kinds now) →
|
||
`rebaseReportOnSheet(outcome.report, index, outcome.archive?.sheetSnapshot ?? null)`
|
||
→ `hydrateImport({ report: rebased, archive: outcome.archive })` → one
|
||
`window.alert` composed of the applicable lines (see §16) → `/editor`.
|
||
- `EditorRoute` export: `exportReportArchive({ report, sheet: buildSheetSnapshot(index.sheet, report), branding: await loadBranding(), labels: defaultPdfLabels, locale, rasterizer: browserRasterizer, exportedAt: new Date() })`;
|
||
download name unchanged; `warnings` logged with `console.warn`.
|
||
- The kept `archive` is exposed by the store for operation (1); no UI uses it
|
||
in this step (UX choice submitted after).
|
||
|
||
**Branding in the app** (`apps/app/src/pdf/branding.ts`): `loadBranding():
|
||
Promise<Branding>` fetches the four `public/` files by their current URLs
|
||
(each failure → slot `null` + `console.warn`, as today), PNG → base64,
|
||
Paws SVG kept as `{ kind: 'svg', svg }`; constants: `siteUrl
|
||
'https://faunosteo.com'`, poweredBy `{ url: 'https://zenquality.fr',
|
||
fallbackText: 'zenquality.fr' }`, partner `{ url:
|
||
'https://www.instagram.com/paws.iin.harmony', fallbackText: '@paws.iin.harmony' }`.
|
||
`// shortcut:` the site URL and partner constants live here until the config
|
||
carries them.
|
||
|
||
**Bundle** (`vite/sheet-bundle.ts`, `sheets/provider.ts`): the payload gains
|
||
`assetHashes: Record<svg_asset_id, sha256>` from `assets.json`; `LoadedSheet`
|
||
gains `assetHashes`; `ref` gains `schemaVersion` and `speciesId` so it is a
|
||
`SheetSnapshotRef` (`SheetRef` of the report stays the 3-field subset).
|
||
|
||
## 15. Caps, sanitiser, text
|
||
|
||
| Item | Cap |
|
||
|---|---|
|
||
| PDF file | 50 MiB (existing) |
|
||
| attachment, raw and inflated | 16 MiB (existing) |
|
||
| snapshot assets | ≤ 4, each ≤ 2 MiB, total ≤ 6 MiB |
|
||
| snapshot document | ≤ 64 views, ≤ 1,024 annotations, ≤ 8,192 finding nodes, depth ≤ 8, labels ≤ 512 chars |
|
||
| branding | PNG base64 ≤ 512 KiB each, SVG ≤ 256 KiB, URLs http(s) ≤ 2,048 chars |
|
||
| report at export | ≤ 500 observations, ≤ 8 views per observation |
|
||
| sanitiser | ≤ 20,000 elements, nesting ≤ 64, ≤ 256 `<use>`, `stdDeviation` ≤ 100 |
|
||
| raster | width 1200 px, aspect clamped to [0.2, 2.0] |
|
||
|
||
Sanitiser (`packages/pdf/src/svg/sanitize.ts`, `sanitizeSvgRoot(root:
|
||
Element): { removed: string[] }`, DOM Level 2 only: `childNodes`,
|
||
`attributes`, `removeAttribute`, `removeChild`, `tagName`):
|
||
|
||
- elements kept: `svg g path circle ellipse rect line polyline polygon defs
|
||
linearGradient radialGradient stop filter feGaussianBlur feMerge feMergeNode
|
||
feOffset feFlood feComposite feBlend feColorMatrix clipPath mask title desc
|
||
switch use`; anything else is removed with its subtree (incl. `style`,
|
||
`script`, `image`, `a`, `foreignObject`, `text`, `feImage`, `feTurbulence`,
|
||
`feConvolveMatrix`, `animate*`, `set`);
|
||
- attributes kept: `id class d cx cy r rx ry x y x1 y1 x2 y2 dx dy width height
|
||
points transform viewBox version preserveAspectRatio fill fill-opacity
|
||
fill-rule stroke stroke-width stroke-linecap stroke-linejoin stroke-opacity
|
||
stroke-dasharray stroke-dashoffset stroke-miterlimit opacity filter
|
||
clip-path clip-rule mask display visibility color gradientUnits
|
||
gradientTransform spreadMethod offset stop-color stop-opacity stdDeviation
|
||
in in2 result mode operator k1 k2 k3 k4 flood-color flood-opacity type
|
||
values color-interpolation-filters filterUnits primitiveUnits
|
||
systemLanguage font-family font-size font-weight xmlns xmlns:xlink
|
||
xlink:href href style`; any other attribute (incl. every `on*`) is removed;
|
||
- `href`/`xlink:href` must match `^#[A-Za-z_][\w.:-]*$`; every `url(` in any
|
||
attribute value must be `url(#…)`; a `style` attribute containing `url(`
|
||
not followed by `#`, `expression(`, `@import`, `javascript:` or `behavior:`
|
||
is removed; `stdDeviation` above the cap is clamped;
|
||
- counters: elements, depth, `<use>`; over a cap → throws `SvgRejectedError`.
|
||
- `horse.svg` and `Paws_in_harmony.svg` must pass with `removed: []` and a
|
||
serialisation byte-identical to the parsed input (test).
|
||
|
||
Text: `safeText(s: string): string` strips `\p{Cc}\p{Cf}
` except
|
||
none, then replaces every code point that
|
||
`Encodings.WinAnsi.canEncodeUnicodeCodePoint` (from
|
||
`@pdf-lib/standard-fonts`) refuses by `?`; used by `wrapLines`, every
|
||
`drawText` and `widthOfTextAtSize` in the engine; en and em dashes survive.
|
||
`formatDate` in the engine returns the input unchanged when it is not
|
||
`YYYY-MM-DD`.
|
||
|
||
## 16. Messages (FR / EN keys, app dicts)
|
||
|
||
| Key | FR | EN |
|
||
|---|---|---|
|
||
| `home.import.archive_ok` | Archive Faunosteo importée : bilan et instantané de la fiche d'origine conservés. | Faunosteo archive imported: report and the original sheet snapshot kept. |
|
||
| `home.import.snapshot_rejected` | Bilan récupéré, mais l'instantané de la fiche d'origine a été rejeté ({reason}) : cette archive ne pourra pas être reproduite telle quelle. | Report recovered, but the original sheet snapshot was rejected ({reason}): this archive cannot be reproduced as is. |
|
||
| `home.import.snapshot_reason.unsupported_envelope` | archive d'une version plus récente | archive from a newer version |
|
||
| `home.import.snapshot_reason.schema` | contenu invalide | invalid content |
|
||
| `home.import.snapshot_reason.caps` | taille ou complexité excessive | size or complexity over the limits |
|
||
| `home.import.snapshot_reason.integrity` | fiche incohérente | inconsistent sheet |
|
||
| `home.import.snapshot_reason.sheet_mismatch` | fiche différente de celle du bilan | sheet differs from the report's |
|
||
| `home.import.rebased` | Bilan ouvert sur la fiche actuelle, différente de celle de l'archive. Éléments non retrouvés : {count} (conservés avec leurs libellés). | Report opened on the current sheet, which differs from the archive's. Items not found: {count} (kept with their labels). |
|
||
| `home.import.error_attachment_stripped` | Ce PDF Faunosteo a perdu ses données embarquées (pièce jointe supprimée par un lecteur ou un optimiseur). Utilisez le fichier d'origine. | This Faunosteo PDF lost its embedded data (attachment removed by a viewer or an optimiser). Use the original file. |
|
||
|
||
Alert composition after a successful import, lines joined by a blank line:
|
||
`migrated` (existing v2 message, when `origin === 'v2'` and counts > 0) ·
|
||
`archive_ok` (when `archive` kept) · `snapshot_rejected` (when
|
||
`snapshotRejected`) · `rebased` (whenever the rebase ran, count may be 0).
|
||
No alert when nothing applies (bare v3 on the same sheet, as today).
|
||
|
||
## 17. Goldens (Phase 0, frozen with the current code)
|
||
|
||
Files under `apps/app/tests/fixtures/goldens/step6/`, JSON, numbers rounded
|
||
to 2 decimals, generated once by a `MAKE_GOLDEN=1` run of the golden test
|
||
file itself (`pdf.goldens.test.ts`: in generation mode it writes, otherwise it
|
||
asserts), and never regenerated without a user decision.
|
||
|
||
- `text.<report>.<locale>.<logos>.json`: ordered `{ page, text, x, y, size, font }`
|
||
from a `PDFPage.prototype.drawText` spy (page = index of `this` in
|
||
`pdfDoc.getPages()` after save; font = `options.font.name`).
|
||
- `images.<report>.<logos>.json`: ordered `{ page, x, y, width, height }` from
|
||
a `drawImage` spy.
|
||
- `links.<report>.<logos>.json`: `{ page, rect, uri }` of every `/Annot /Link`
|
||
read back from the saved PDF.
|
||
- `views.<report>.json`: per `(observationId, viewId)`: `{ viewBox, halo,
|
||
highlighted: [{ tag, cx, cy, r, points, d, fill, fillOpacity, filter }],
|
||
nonHighlightedVisible: 0, dataAttributes: 0, titles }` from
|
||
`highlightedViewSvg` parsed with `DOMParser` (hidden markers are
|
||
`display="none"` today and absent in the engine: both count as not visible).
|
||
- Reports: `v2full` (migrated `report-v2.full.json`), `demo`
|
||
(`report-v3.demo.json`, new fixture: 6 observations covering main and head
|
||
views, vertebrae, bilateral sides, a vet-referral leaf, a leaf whose label
|
||
holds an en dash, free text, severity, next appointment), `v2unresolved`
|
||
(built with `tests/helpers/legacyLeaves.ts`: one observation per unresolved
|
||
leaf family, sphenoid and ssb, plus one resolved leaf).
|
||
- Logo modes: `nologos` (fetch 404) and `logos` (fetch stub serving the real
|
||
bytes of the four `public/` files; `rasterizeSvg` mocked to a fixed 2×1 PNG
|
||
so the partner logo width is deterministic).
|
||
- `report-v3.bare.pdf`: the demo report exported by the current code
|
||
(`nologos`), import fixture only.
|
||
|
||
Characterisation tests written in Phase 0 and kept green unchanged:
|
||
`routes.HomeRoute.import.test.tsx` (v2 alert with count, four error kinds to
|
||
messages, navigation; `importReportFromPdf` mocked) and
|
||
`routes.EditorRoute.export.test.tsx` (export called with report, index and
|
||
locale; download name `bilan-<animal>-<date>.pdf`; failure alert). Phase 4
|
||
adapts only the mocked module path and the call-shape assertion of T13 to the
|
||
engine API, nothing else.
|
||
|
||
## 18. Executors and phases
|
||
|
||
One executor per phase, closed contract in `.claude/tasks/contracts/`, TDD,
|
||
no commit (the orchestrator commits), report with test counts. Phases 1 and 2
|
||
run in parallel. Verifier and security gates after Phase 5 and on request.
|
||
|
||
| Phase | Owner | Exit |
|
||
|---|---|---|
|
||
| 0 freeze | executor | goldens + fixtures + T12/T13 committed, app suite green |
|
||
| 1 domain | executor | archive/{snapshot,envelope,branding,labels}, sheet-index moved, rebase, bundle hashes; domain + app suites green |
|
||
| 2 anatomy | executor | compose.ts, review drawing golden unchanged; anatomy suite green |
|
||
| 3 engine | executor | packages/pdf complete, T1 T3–T11 green, xmldom bundle size measured |
|
||
| 4 app | executor | routes, store, persistence, branding, messages; T2 T12–T15 green; old code removed |
|
||
| 5 docs + gates | orchestrator + verifier + security | docs, check, docker, EVAL |
|