docs: step 6 implementation contract (types, envelope v1, read, rebase, session, messages, goldens) + BDR-039

This commit is contained in:
bchanot committed 2026-10-11 11:59:08 +02:00
1 parent 72f19521d3
commit 4c6c5151f8
3 files changed
+408

No files matched your search

+8
View File
@@ -327,3 +327,11 @@ Status: closed.
Sheet source: `SheetProvider` interface; Step 5 implementation = Vite virtual module `virtual:faunosteo-sheet` built from the seed draft (`vite/sheet-bundle.ts`), mode `SHEET_BUNDLE=draft|none`, default draft for dev server, none for builds/CI/Docker (`--build-arg SHEET_BUNDLE=draft` = explicit preview) → unvalidated draft never ships by accident (D2). Markers: pure renderer `@faunosteo/anatomy/render` (element tree, no DOM) reproduces legacy look (hitbox r + twin r−12, opacities 0.65/0.5, spine 0.3, trigger 0.06 dashed); colours = document data (`categories[].color`, additive `annotations[].color` for the head shades, schema_version stays 2 for additive optional fields); same renderer feeds `draft/review/app-<view>.svg` for visual checks. Report v3 in packages/domain: `(annotationId, viewId)` zones with label snapshots, `(findingZoneId, path)` findings, severity codes, `sheet {sheetId, versionId|null, documentSha256}`, `unresolved: true` for what migration cannot place, `localAnnotations: []` reserved. Migration map generated by the pipeline from applier records (replay renames/moves/removals + unique re-homing): 792 nodes → 571/180/7/34. Interaction = pure service + reducers (BDR-019 kept); store = v3 + persistence adapter (v2 draft migrated on restore). D4 applied: registry, matchers, SVG parser, editors, pathology-editor, public species assets deleted; legacy sources moved to `supabase/seed/.../legacy-sources/` (importer input).
Alt rejected: copying the draft into apps/app (duplication, drift); runtime fetch of `/sheets/*.json` (still public, no gain); UUID annotation ids (BDR-031); converting v3→v2 for attachments (lossy); per-view colour table in the app (horse knowledge in generic code).
Status: closed; awaiting user validation of Step 5.
---
## BDR-039 | 2026-10-11 | Step 6: autonomous PDF archives — lean-document snapshot, envelope v1, archived branding + labels, explicit rebase
User-validated design (docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II). Attachment = envelope v1 `{format, envelopeVersion, exportedAt, locale, report v3, sheetSnapshot, branding, labels}` in one `osteo-report.json`, SVG inline as text. Snapshot = `{status, ref, document, assets}` where document = valid lean `AnatomicalSheetDocument` (all views/annotations/categories/regions, finding zones kept by id, trees pruned to used paths with ancestor labels, references emptied) → reuses sheet index, layer renderer, 21 integrity rules; no dedicated schema. Branding (logos base64/svg, credits, URLs) + label dict (fr+en) archived so future logo/wording changes never alter a re-render (user D7 adjustment). Engine `packages/pdf`: explicit inputs `{report, sheet, branding, labels, locale, rasterizer, exportedAt}`, no DOM lib, xmldom composition promoted from curation app-review, Rasterizer adapter (browser Image/canvas; resvg devDep for tests), per-view/per-logo degradation, export-side validation (caps, integrity, sheet invariant). Read = layered: report first (v3/v2 existing dispatch), envelope metadata tolerant, snapshot strict → `snapshotRejected` enum, report never lost; `attachment_stripped` via Info.Keywords stamp. Session: imported archive kept immutable (`osteo:archive`), working copy rebased explicitly on the loaded sheet (`rebaseReportOnSheet`, unresolved flags + labels from archived snapshot) (user D8 adjustment); re-export of the kept archive = technical support only, UX submitted after step. No CLI, no page change, no original v2 JSON re-embedded.
Alt rejected: dedicated SheetSnapshotSchema (rewrites lookups, loses integrity rules); separate embedded files per asset (first-EmbeddedFile reader, stripping risk); pruning views/annotations (saves ~0 KB, breaks trigger titles); snapshot discarded on import (user: keep for faithful re-read); crypto hash check of assets (self-referential; sha copied from catalog manifest as provenance pointer instead).
Status: open (implementation in progress on feature/step-06-pdf-archives).
@@ -0,0 +1,27 @@
# CONTRACT — step-06 phase 0 freeze
- date: 2026-10-11 | flow: ship-feature (executor) | branch: feature/step-06-pdf-archives
- status: active
- spec: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II (§17 goldens, §13 types for naming only)
## REQUEST (IMMUTABLE)
Freeze the current PDF pipeline behaviour before any refactor: new fixtures, goldens generated once with the current code, characterisation tests of the two routes. Production code under apps/app/src is NOT modified in this phase.
## ACCEPTANCE CRITERIA
1. Fixture `apps/app/tests/fixtures/report-v3.demo.json`: valid Report v3 on the bundled draft (ids taken from draft/document.json), 6 observations covering: main view zones, head view zone, a spine zone with vertebrae, a bilateral zone with left and right sides, a vet-referral leaf (`requiresVetReferral: true`), a leaf whose label holds an en dash (U+2013), free-text findings, severities, comment, conclusion, recommendations, nextAppointment; `sheet` = the draft ref.
CHECK: cd apps/app && corepack pnpm vitest run tests/unit/pdf.goldens.test.ts 2>&1 | tail -3
EXPECT: Tests .* passed
2. Goldens under `apps/app/tests/fixtures/goldens/step6/` exactly as spec §17 (text/images/links per report × locale × logo mode, views per report), generated by `MAKE_GOLDEN=1 corepack pnpm vitest run tests/unit/pdf.goldens.test.ts`, then asserted by the same file without the flag. Reports: v2full, demo, v2unresolved. Logo modes: nologos, logos.
CHECK: ls apps/app/tests/fixtures/goldens/step6 | wc -l
EXPECT: >= 20
3. Fixture `apps/app/tests/fixtures/report-v3.bare.pdf`: the demo report exported by the current code (rasteriser stubbed 1×1, no logos), produced by the same MAKE_GOLDEN run; `tests/fixtures/README.md` documents the new files and the rule "never regenerate without a user decision".
CHECK: test -s apps/app/tests/fixtures/report-v3.bare.pdf && echo ok
EXPECT: ok
4. Characterisation tests `tests/unit/routes.HomeRoute.import.test.tsx` and `tests/unit/routes.EditorRoute.export.test.tsx` as spec §17 (import mocked at module level; alert text with count; the three current error kinds + generic; navigation to /editor; export call shape; download name; failure alert).
CHECK: cd apps/app && corepack pnpm vitest run tests/unit/routes.HomeRoute.import.test.tsx tests/unit/routes.EditorRoute.export.test.tsx 2>&1 | tail -3
EXPECT: Tests .* passed
5. Whole app suite, typecheck and lint green; no file under apps/app/src changed.
CHECK: cd apps/app && corepack pnpm typecheck && corepack pnpm lint && corepack pnpm test:run 2>&1 | tail -4; git -C /home/bchanot/Documents/faunosteo status --short apps/app/src | wc -l
EXPECT: Tests .* passed ; 0
## FILE SCOPE
apps/app/tests/** only (new test files, fixtures, goldens, helpers, README). No change under apps/app/src, packages/**, docs/**.
@@ -617,3 +617,376 @@ 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 |