docs(docs): R4.6 J2 recette (procedure, results grid, kit script), export harness phases and dist override, export series script, ledger targets of the app PDF suites, CLAUDE.md export flow; export driver publishes its User Timing split

This commit is contained in:
bchanot committed 2026-10-19 01:41:57 +02:00
1 parent 9cb3cb75d4
commit cdcdda8e1c
12 files changed
+679 -39

No files matched your search

+19 -16
View File
@@ -234,8 +234,8 @@ faunosteo/
│ │ ├─ shell/{AppLayout,SidebarNav,MobileDrawer,UserBadge,SignOutButton}.tsx
│ │ └─ account/{SectionCard,SaveRow,AvatarSection,PersonalInfoForm,ProfessionalInfoForm,PreferencesForm,SecurityPanel,RoleBadges}.tsx
│ ├─ account/avatarTransport.ts ← magic-byte sniff (never SVG), createImageBitmap → canvas ≤ 1024 px → JPEG transport blob
│ ├─ pdf/ ← app side of @faunosteo/pdf (engine in packages/pdf)
│ │ ├─ export.ts + import.ts ← exportReportToPdf (sheet snapshot + branding + browser rasterizer → engine), importReportFromPdf (ArchiveReadOutcome, ImportError kinds)
│ ├─ pdf/ ← the app side of the PDF (export on the core's session since R4.6; the TS reader of packages/pdf until R4.8)
│ │ ├─ export.ts + labels.ts + import.ts ← exportReportToPdf (snapshot + branding + labels → ExportSession, rasters one by one, Blob of the parts, abort on unmount), defaultPdfLabels (25 keys), importReportFromPdf (tests; the app imports through the worker)
│ │ └─ branding.ts + browserRasterizer.ts ← bundled src/assets/brand logos (?inline / ?raw) → Branding; Image/canvas Rasterizer adapter
│ ├─ lib/{dates,id,assert,supabase}.ts ← supabase.ts: getSupabaseClient() | null
│ ├─ styles/{index,tokens}.css ← Tailwind v4 CSS-first
@@ -260,7 +260,7 @@ faunosteo/
│ ├─ src/anatomical-sheet/{schema,validate,create}.ts ← canonical sheet document + integrity rules
│ └─ tests/{fixtures/horse-slice.ts,*.test.ts}
├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, frozen TS annotation-layer renderer + view composer (`./render`: PDF engine until R4, pipeline until R5; the app no longer depends on it)
├─ packages/pdf/ ← @faunosteo/pdf: browser-free PDF engine — src/{export,read,text,branding}.ts, attachment/, svg/{parse,sanitize,view}.ts, render/, i18n/; tests reproduce the Step 6 goldens
├─ packages/pdf/ ← @faunosteo/pdf: the frozen TypeScript PDF engine (R3 reference until R4.8; no app consumer since R4.6 but the kept reader) — src/{export,read,text,branding}.ts, attachment/, svg/{parse,sanitize,view}.ts, render/, i18n/; tests reproduce the Step 6 goldens
│ ├─ src/legacy/{svg,catalog,regions,ids,report,importer}.ts, src/cli/import-equine.ts
│ ├─ src/curation/{schema,targets,fields,ops,rename,apply,types,assets,labels,stats,changelog,review-report,overlay,seed,sources,pipeline}.ts ← changeset → draft
│ └─ tests/ ← counts preserved, special cases, determinism, curation ops, golden artifacts
@@ -278,7 +278,7 @@ faunosteo/
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
├─ packages/README.md ← shared packages index
├─ packages/core-wasm/ ← @faunosteo/core-wasm: CoreRuntime (lazy, poison, recovery) + Node source, pkg/ shipped and pkg-proofs/ (built, git-ignored, BUILD_STAMP), ts-rs types (committed), frozen N-1 reader (tests/n-1), tests
├─ packages/core-wasm/ ← @faunosteo/core-wasm: CoreRuntime (lazy, poison, recovery) + CoreExportSession (R4.6) + Node source, pkg/ shipped and pkg-proofs/ (built, git-ignored, BUILD_STAMP), ts-rs types (committed), frozen N-1 reader (tests/n-1), tests
├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root)
│ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing); tests/{oracles,conformance,fixtures} frozen from the TypeScript (oracles/r3, fixtures/svg/hostile); no I/O, no clock (lint-enforced)
│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, SheetHandle; trap exports in the proofs build only)
@@ -321,15 +321,18 @@ SVG interaction
→ vertebra.select per tap, vertebra.sync / zone.add_sides on confirm → updateObservation() in store
→ toggle / remove_both_sides → the core's observation → updateObservation(); findings picker → finding.toggle
PDF export (app side: apps/app/src/pdf, engine: packages/pdf)
→ exportReportToPdf(report, index, { locale })
→ index.ops.snapshot(report) (core: archive.snapshot) + loadBranding() (4 logos bundled at build time, no network) + defaultPdfLabels
→ exportReportArchive({ report, sheet, branding, labels, locale, rasterizer: browserRasterizer, exportedAt })
assertSnapshot (caps, integrity, sheet invariant) → fonts (WinAnsi StandardFonts, safeText guard)
→ per observation: composeHighlightedViewSvg (xmldom: sanitise allowlist → composeViewSvg highlight) → rasterizer → page
→ conclusion page, footer, envelope v1 attached as osteo-report.json, Keywords faunosteo-archive/1
→ { pdf, envelope, warnings } → { pdf, warnings } to EditorRoute → browser download, alert naming failed logo slots / views
→ exportFromEnvelope(envelope, …) re-exports an archive from its own snapshot, branding and labels (no sheet)
PDF export (app side: apps/app/src/pdf; writer: crates/core/src/pdf/write, RUST.md §10.4 to §10.8)
→ exportReportToPdf(report, index, { locale, signal })
→ index.ops.snapshot(report) (core: archive.snapshot) + loadBranding() (4 logos bundled at build time, no network) + defaultPdfLabels (labels.ts)
→ openExportSession(runtime, ExportInput JSON): the core checks the input (branding and labels schemas, snapshot gate through the SVG reader,
sheet match, page caps), builds the envelope under 16 MiB, opens the file (Info, fonts)
→ loop session.next(): the SVG logos, then each observation's views (main first), composed by the core (R3 compose_highlight, 1200 px wide)
→ browserRasterizer under Promise.all → rasterFailed in rejection order, addRaster in request order (a view is decoded and its
XObject written on arrival, PNG and planes dropped; a PNG the decoder refuses is the view's warning)
→ session.finish(): conclusion page, footers, pages, attachment (osteo-report.json, Keywords faunosteo-archive/1), self-check by the R4
reader → the file in parts → new Blob(parts) to EditorRoute → browser download, alert naming failed logo slots / views; free() in finally
→ a trap poisons the runtime as any core call; a session of a dropped instance answers core_unavailable; leaving the editor aborts and frees
→ export_from_envelope (cargo only) re-exports an archive from its own snapshot, branding and labels (no sheet)
PDF import
→ readAttachment(bytes) → engine byte scan for the EmbeddedFile stream (TS until R4; no pdf-lib parse on untrusted
@@ -387,7 +390,7 @@ Database (Supabase)
- `src/state/localeStore.ts` holds current `Locale` (`'fr' | 'en'`), persisted to `localStorage` key `osteo:locale`; default: navigator-detected `fr`/`en`, or `'fr'` if no match; while signed in, `services/localeSync.ts` writes it to `profiles.locale` and applies the account locale on sign-in
- Form validation messages are i18n keys returned by the Zod schemas (`src/auth/validation.ts`, `src/account/validation.ts`), translated next to the field; GoTrue messages never reach the screen (`auth.failure.*`)
- Zone and finding names shown in the editor and the PDF come from the sheet document (`{ fr, en }` labels) and from the report's snapshots, not from the dict
- PDF static labels (section headings, metadata) live in the engine (`packages/pdf/src/i18n`, `defaultPdfLabels`, 25 keys) and are archived in the envelope; the app dicts hold no `pdf.*` key
- PDF static labels (section headings, metadata) live in `apps/app/src/pdf/labels.ts` (`defaultPdfLabels`, 25 keys, moved verbatim from the engine at R4.6) and are archived in the envelope; the app dicts hold no `pdf.*` key
### Identity strings
- NEVER hardcode APP_SITE_NAME, APP_BRAND_NAME, APP_FOOTER_NAME, APP_TAGLINE
@@ -432,8 +435,8 @@ Database (Supabase)
- A4 portrait: 595.28 × 841.89 pt
- No raw URLs in PDF output — abbreviated citations only
- JSON attachment filename must start with osteo-report; content = report archive envelope v1 (report v3 + sheet snapshot + branding + labels); import accepts bare v2 (migrated), bare v3 and envelope v1; a bad snapshot never loses the report
- The engine (`packages/pdf`) has no DOM lib, no fetch, no Node-only global (lint-enforced); rasterisation is an injected adapter; every SVG it receives is sanitised by allowlist with caps
- Page layout is frozen by the Step 6 goldens: any visible change needs a user decision and a golden regeneration
- The writer (`crates/core/src/pdf/write`, since R4.6; the frozen TS engine `packages/pdf` until R4.8) takes no clock and no I/O; rasterisation is the browser's, one raster per core request; every SVG it composes went through the core's one reader. The export is an incremental session (OD-2): the file is written as the rasters arrive, held once, handed out in parts; never accumulate rasters or build the file twice
- Page layout is frozen by the Step 6 goldens and the R4 oracles (O1 draw logs, O2 PDFs): any visible change needs a user decision and a golden regeneration; the R4 digests (`goldens/r4/pdf.*.sha256`) pin the writer's own bytes and are rewritten only for a declared structural change, with the O2 comparisons re-run
- Fonts are StandardFonts (Helvetica/TimesRoman, WinAnsi encoding) — TTF Inter/Fraunces planned but not yet embedded. Any non-Latin-1 glyph in PDF text must use an ASCII surrogate until the TTF migration lands (e.g. `(!)` instead of `⚠`).
### Anatomical sheet content
+64 -10
View File
@@ -49,6 +49,47 @@ function assertNotAborted(signal: AbortSignal | undefined): void {
if (signal?.aborted) throw new DOMException('export aborted', 'AbortError')
}
/** Where the time went, for the DEV console and the browser harness (User Timing). */
interface ExportTiming {
startedAt: number
coreMs: number
rasterMs: number
requests: number
}
/** Runs a core call and charges its time. */
function timed<T>(timing: ExportTiming, call: () => T): T {
const started = performance.now()
try {
return call()
} finally {
timing.coreMs += performance.now() - started
}
}
/**
* One `performance.measure('faunosteo:export')` entry with the split in its detail:
* nothing the page shows, what the harness reads. Absent where User Timing lacks the
* options form.
*/
function publishTiming(timing: ExportTiming, parts: number, bytes: number): void {
try {
performance.measure('faunosteo:export', {
start: timing.startedAt,
end: performance.now(),
detail: {
coreMs: timing.coreMs,
rasterMs: timing.rasterMs,
requests: timing.requests,
parts,
bytes,
},
})
} catch {
// An older engine: no measure, nothing else changes.
}
}
/**
* One batch of the session's requests rasterised under `Promise.all`, as the engine did:
* a raster that fails is reported as it rejects (the warning order the engine recorded),
@@ -60,7 +101,10 @@ async function answerBatch(
session: CoreExportSession,
requests: RasterRequest[],
signal: AbortSignal | undefined,
timing: ExportTiming,
): Promise<void> {
timing.requests += requests.length
const rasterStarted = performance.now()
const settled = await Promise.all(
requests.map(async (request) => {
try {
@@ -71,15 +115,16 @@ async function answerBatch(
return { key: request.key, png }
} catch {
assertNotAborted(signal)
unwrap(session.rasterFailed(request.key))
unwrap(timed(timing, () => session.rasterFailed(request.key)))
return { key: request.key, png: null }
}
}),
)
timing.rasterMs += performance.now() - rasterStarted
for (const { key, png } of settled) {
if (!png) continue
assertNotAborted(signal)
unwrap(session.addRaster(key, png))
unwrap(timed(timing, () => session.addRaster(key, png)))
}
}
@@ -109,23 +154,32 @@ export async function exportReportToPdf(
exportedAt: new Date().toISOString(),
}
assertNotAborted(opts.signal)
const session = unwrap(openExportSession(coreRuntime(), JSON.stringify(input)))
const timing: ExportTiming = {
startedAt: performance.now(),
coreMs: 0,
rasterMs: 0,
requests: 0,
}
const text = JSON.stringify(input)
const session = unwrap(
timed(timing, () => openExportSession(coreRuntime(), text)),
)
try {
for (;;) {
assertNotAborted(opts.signal)
const step = unwrap(session.next())
const step = unwrap(timed(timing, () => session.next()))
if (step.step === 'done') break
await answerBatch(session, step.requests, opts.signal)
await answerBatch(session, step.requests, opts.signal, timing)
}
const parts = unwrap(session.finish())
const parts = unwrap(timed(timing, () => session.finish()))
const warnings = unwrap(session.warnings())
for (const warning of warnings) {
console.warn('PDF export warning', warning)
}
return {
pdf: new Blob(parts as BlobPart[], { type: 'application/pdf' }),
warnings,
}
const pdf = new Blob(parts as BlobPart[], { type: 'application/pdf' })
publishTiming(timing, parts.length, pdf.size)
if (import.meta.env.DEV) console.info('PDF export', timing)
return { pdf, warnings }
} finally {
session.free()
}
+1
View File
@@ -49,6 +49,7 @@ without the flag the same tests assert equality with the committed files.
| `r4/reports/{L,CAP}.json` | Synthetic Report v3 on the draft: 60 observations / 120 views (L) and 500 / 1,000 (CAP), the export memory inputs of plan §B.4 (O13). |
| `goldens/r4/draw.*.json` | Every drawing call of the export (text, image, line, rectangle, link) at full precision, per page and in call order, for the 12 Step 6 report × locale × logo combinations (O1). |
| `pdf/r3/` | The 12 PDFs the R3-era engine produced for those combinations, the store-path export with its `report.json`, and `real/v2full-obs1.fr.logos.pdf` with its two browser PNGs and manifest: the byte references of the writer port (O2). |
| `goldens/r4/pdf.*.sha256` | Digests of the Rust writer's own output on the 14 O2 runs (not an oracle of the TypeScript: the proof that the wasm module and the application path write the native bytes). Frozen at R4.5; rewritten once at R4.6 when the writer became incremental (catalog and page tree written last, upper-case hex strings as pdf-lib), every O2 comparison and the poppler render unchanged. `MAKE_R4_ORACLES=1 cargo test --test pdf_serialize r4_output_digests_are_frozen` rewrites them, never to hide a difference with O2. |
| `pdf/step6/envelope.*.pdf` | Three envelope PDFs from before R2 (O3). |
| `pdf/r4/tolerance/` | 51 PDFs, valid and hostile, with today's import outcome and message in `crates/core/tests/oracles/r4/tolerance.json` (O8). |
| `pdf/r4/read/`, `pdf/r4/inflate/` | 155 reader inputs and 24 zlib framing inputs, the bytes behind `read.json` and `inflate.json`; a `<slug>.gen.json` describes a large input by concatenation (O7, O9). |
+71
View File
@@ -0,0 +1,71 @@
# R4 J2: device acceptance of the Rust export
Plan `.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md` §B.7 (R4.6 "your
phone check of L") and the owner's R4.6 brief. The export of the application
runs on the core's session since R4.6 (`docs/development/RUST.md` §10.8):
the browser draws each view the core asks for, the core writes the file as
the rasters arrive. Headless runs in Chromium, Firefox and WebKit are
recorded in RUST.md §10.8; nothing below is validated until it has run on
the owner's devices. The J1 recette (import, `R4_J1.md`) stays due on Safari
iOS before any R4 merge; J2 can run in the same session.
## 1. Serve the build on the LAN (owner's machine)
As for J1, on the DEV origin (`scripts/dev-env.sh`, `FAUNOSTEO_DEV_HOST`):
1. `pnpm dev:offline` (the local tool), `http://<FAUNOSTEO_DEV_HOST>:5173`.
2. The production build behind the DEPLOY CSP: `pnpm build:preview` then
`node scripts/browser/serve.mjs --host "$FAUNOSTEO_DEV_HOST" --port 4173`,
`http://<FAUNOSTEO_DEV_HOST>:4173`. Surface 2 is the one that matters for
the memory items and the CSP.
## 2. The kit
`node scripts/r4-j2-kit.mjs [dir]` writes a folder (about 3 MB, synthetic
data only) with `ATTENDU.md`:
- `1-reference/`: the R3 exports of the TypeScript engine (demo FR and EN
with logos, demo FR without, v2full, v2unresolved, the store path, the
real-raster export). Import one, export it again: the two files show the
same bilan.
- `2-large/`: `L.fr.logos.pdf` (60 observations, 120 views, 377 KB) and
`CAP.fr.logos.pdf` (500 observations, 1,000 views, 1.5 MB), archives the
Rust session wrote with 2 × 1 stub rasters: the device draws the real
views when it exports them.
Copy the folder to the devices (AirDrop, a share, a USB key); on iPhone pick
from Files. To compare two PDFs on a phone, open them side by side in the
viewer; on a computer, `pdftoppm -r 72` on both and flip between the pages,
or any viewer with two tabs.
## 3. Checks per device (computer, iPhone, low-end Android: the OD-6 list)
Record the device, the browser and its version, the surface (1 or 2), and
for J2.6 the time from the tap to the download sheet and whether the tab
survived.
| # | Check | Expected |
|---|---|---|
| J2.1 | FR export: import `1-reference/r3-demo.fr.logos.pdf`, tap « Exporter en PDF » | a download named `bilan-<animal>-<date>.pdf`; opened, 7 pages identical to the imported file: the same texts, the four logos (header, footer, ZenQuality, the partner drawing), the anatomy views with the observation's zones highlighted in the accent colour, the severity pill, the conclusion page, the pagination « n / 7 » |
| J2.2 | EN export: switch the language to English in the editor, export again | the same pages in English (« GENERAL VIEW », « FINDINGS — », « Powered by »); the animal and practitioner names unchanged |
| J2.3 | Without logos: import `r3-demo.fr.nologos.pdf`, export | the header shows the site name as text, the footer the credit texts (« zenquality.fr », « @paws.iin.harmony ») in place of the logos; no alert |
| J2.4 | Links: in the exported file of J2.1, tap the header logo and the two footer credits | they open `faunosteo.com`, `zenquality.fr` and the partner's Instagram page |
| J2.5 | Real rasters: import `r3-real.v2full-obs1.fr.logos.pdf`, export, zoom at 400 % on the main view of the first observation | the drawing is crisp (1200 px wide raster), the highlighted zones and the halo as in the imported file |
| J2.6 | Large export on the phone (E4): import `2-large/L.fr.logos.pdf`, export | the download arrives (note the time; the development machine takes 7 s in Chromium); the tab survives, no reload, no memory warning; the file opens with 61 pages |
| J2.7 | Repetition: export the demo 6 times in a row on the same page | 6 downloads, no slowdown worth noting, the tab alive |
| J2.8 | Round trip: import the file exported at J2.1 (from the Files app) | the editor opens with the same bilan, « Restauration complète… »; export it again: identical pages |
| J2.9 | Interrupted export: on `2-large/L.fr.logos.pdf`, tap « Exporter en PDF » then leave the editor at once (« Accueil ») | no download, no alert, Home usable; a later export works |
| J2.10 | Engine unavailable: surface 2 with `--csp without`, open the editor | the degraded notice (the export button is not offered); back with the keyword, the export works |
| J2.11 | CAP on the computer only: import `2-large/CAP.fr.logos.pdf`, export | the download arrives (the development machine: Chromium about 1 min); 501 pages; the tab survives |
J2.1 to J2.5 are the visual parity items: any difference between the
imported and the exported file (a shifted block, a missing glyph, a wrong
colour, a missing link) is a finding, with a screenshot of both. J2.6 and
J2.7 are the memory items of OD-2 on a device (the headless numbers are in
RUST.md §10.8).
## 4. Results
Fill `docs/development/R4_J2_RESULTS.md` (PASS / FAIL / NON TESTÉ per
device and check; device, browser, version, surface, times as read). The
headless runs never count as a device result.
+31
View File
@@ -0,0 +1,31 @@
# R4 J2: results (to fill during the device acceptance of the export)
Procedure: `R4_J2.md`. One column per device actually run; `PASS`, `FAIL` or
`NON TESTÉ` per cell, with a note under the table for every FAIL, incident,
timing and memory event. A device or browser not run stays `NON TESTÉ`; the
headless runs of RUST.md §10.8 never fill a cell.
| Device, browser, version | Surface (1 dev / 2 prod CSP) | Date |
|---|---|---|
| (to be given by the owner) | | |
| Check | Computer | iPhone, Safari iOS | Android |
|---|---|---|---|
| J2.1 FR export identical to the imported demo | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.2 EN export | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.3 export without logos | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.4 links open the three sites | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.5 real rasters crisp at 400 % | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.6 L export on the phone (E4), time, tab alive | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.7 six demo exports in a row | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.8 round trip of an exported file | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.9 interrupted export | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.10 engine unavailable then recovered | NON TESTÉ | NON TESTÉ | NON TESTÉ |
| J2.11 CAP export (computer only) | NON TESTÉ | not applicable | not applicable |
Notes (FAIL, incidents, timings, memory warnings, reloads):
-
Recommendation (filled after the run): accept R4.6 as is / accept with
follow-ups / do not accept, and why.
+24
View File
@@ -145,6 +145,29 @@ function rastersOf(probe) {
}
}
/**
* Where the export's time went, from the page clock: before the first raster (checks,
* branding), the raster phase (first `toBlob` start to the last `toBlob` end, layout and
* image writing interleaved), the tail (last raster to the PDF blob: the remaining
* pages, the attachment, the save or `finish()`), plus the Rust driver's own split when
* the build publishes it (`faunosteo:export` User Timing: core calls, rasteriser awaits).
*/
function phasesOf(probe) {
const starts = probe.png.map((p) => p.startedAt).filter((t) => t != null)
const ends = probe.png.map((p) => p.at).filter((t) => t != null)
const first = starts.length ? Math.min(...starts) : null
const last = ends.length ? Math.max(...ends) : null
return {
headMs: elapsed(probe.clickAt, first),
rasterPhaseMs: elapsed(first, last),
tailMs: elapsed(last, probe.pdfBlobAt),
rasterSumMs: sum(
probe.png.map((p) => (p.at != null && p.startedAt != null ? p.at - p.startedAt : 0)),
),
driver: probe.exportTiming,
}
}
const elapsed = (from, to) => (from === null || to === null ? null : to - from)
function peakOf(snapshot) {
@@ -173,6 +196,7 @@ async function afterDownload(session, tab, end) {
suggestedFilename: end.value.suggestedFilename(),
exportMs: elapsed(probe.clickAt, probe.pdfBlobAt),
rasters: rastersOf(probe),
phases: phasesOf(probe),
cspViolations: probe.csp,
...peak,
after,
+1 -1
View File
@@ -48,7 +48,7 @@ export function checkBuild() {
throw new Error(`the build carries no sheet: run ${BUILD_COMMAND}`)
}
return {
distDir: 'apps/app/dist',
distDir: DIST_DIR,
builtAt: statSync(index).mtime.toISOString(),
sheetChunk: sheet,
entryChunk: assetSize(/^index-.*\.js$/),
+22 -3
View File
@@ -21,6 +21,8 @@ export function installProbes() {
dataUrls: 0,
clickAt: null,
pdfBlobAt: null,
/** R4.6: the `faunosteo:export` User Timing entry's detail (the Rust driver's split). */
exportTiming: null,
changeAt: null,
navAt: null,
alertAt: null,
@@ -37,8 +39,14 @@ export function installProbes() {
const toBlob = proto.toBlob
proto.toBlob = function (callback, ...rest) {
const size = { width: this.width, height: this.height }
const startedAt = now()
const record = (blob) => {
probe.png.push({ ...size, bytes: blob ? blob.size : null })
probe.png.push({
...size,
bytes: blob ? blob.size : null,
startedAt,
at: now(),
})
callback(blob)
}
return toBlob.call(this, record, ...rest)
@@ -132,8 +140,19 @@ export function countErrorLines() {
}).observe(document.body, { childList: true, subtree: true })
}
/** Reads the probe back (a structured-clone copy). */
export const readProbe = () => window.__harness
/** Reads the probe back (a structured-clone copy), with the export timing entry if any. */
export const readProbe = () => {
const probe = window.__harness
const entry = performance.getEntriesByName('faunosteo:export').at(-1)
if (entry) {
probe.exportTiming = {
startTime: entry.startTime,
duration: entry.duration,
...(entry.detail ?? {}),
}
}
return probe
}
/**
* A page of a fresh context with the probes and the tab seed, dialogs
+4 -1
View File
@@ -2,7 +2,10 @@ import { resolve } from 'node:path'
export const HARNESS_DIR = resolve(import.meta.dirname, '..')
export const REPO_ROOT = resolve(HARNESS_DIR, '../..')
export const DIST_DIR = resolve(REPO_ROOT, 'apps/app/dist')
/** The build measured; `FAUNOSTEO_DIST` points a run at another build (R4.6: TS vs Rust). */
export const DIST_DIR = process.env.FAUNOSTEO_DIST
? resolve(process.env.FAUNOSTEO_DIST)
: resolve(REPO_ROOT, 'apps/app/dist')
export const FIXTURES_DIR = resolve(REPO_ROOT, 'apps/app/tests/fixtures')
export const ORACLES_R4_DIR = resolve(REPO_ROOT, 'crates/core/tests/oracles/r4')
export const RESULTS_DIR = resolve(HARNESS_DIR, 'results')
+273
View File
@@ -0,0 +1,273 @@
// Export series of the application (R4.6, OD-2 release proof): ONE editor
// tab per engine and report, the start level, then one export (the init
// cost: module, fonts, first decode, counted apart) and `--exports` more by
// the same « Exporter en PDF » button, each awaited through the download;
// 2 s idle after each, 5 s at the end, the content RSS read after each
// (Chromium: forced GC + 1 s before each reading; Firefox and WebKit: idle
// only, indicative). Recurring growth = L7 − L2 for 6 exports, the import
// series' 10 MiB tolerance (BDR-058). The session is freed by the driver
// after every export, so the module's memory is reused, not grown; the
// `faunosteo:export` User Timing entry of each export is kept (core and
// raster split). A fresh browser per repetition (`--reps`).
//
// PLAYWRIGHT_NODE_MODULES=... node scripts/browser/r4-export-series.mjs \
// [--engines chromium,firefox,webkit] [--reports demo,L] \
// [--reps 1] [--exports 6] [--out <file>]
import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
import { dirname, join } from 'node:path'
import { parseArgs } from 'node:util'
import { checkBuild } from './lib/app-build.mjs'
import { delay, firstLine, tagged, timeoutAfter } from './lib/async.mjs'
import { hostFacts } from './lib/host.mjs'
import { probedPage, readProbe } from './lib/page-probes.mjs'
import { FIXTURES_DIR, RESULTS_DIR } from './lib/paths.mjs'
import {
ENGINES,
closeEngine,
launchEngine,
loadPlaywright,
} from './lib/playwright.mjs'
import {
IDLE_SETTLE_MS,
forcedGc,
levelNow,
listOf,
log,
today,
} from './lib/r4-runs.mjs'
import { watchdogFacts } from './lib/watchdog.mjs'
import { deltasOf } from './r4-leak-series.mjs'
import { startServer } from './serve.mjs'
const MINUTE = 60_000
const EXPORT_LABEL = 'Exporter en PDF' // fr.ts editor.export
const CANVAS = '.svg-canvas [data-anno-id]'
const LOAD_TIMEOUT_MS = 2 * MINUTE
const BETWEEN_MS = 2000
const FINAL_IDLE_MS = 5000
const TEN_MIB = 10 * 1024 * 1024
const REPORTS = {
demo: { file: 'report-v3.demo.json', timeoutMs: 5 * MINUTE },
L: { file: 'r4/reports/L.json', timeoutMs: 30 * MINUTE },
}
const READINGS =
'Readings: content RSS of the browser tree after each export (download ' +
'received, export button enabled again), 2 s idle; Chromium adds a forced ' +
'GC (CDP HeapProfiler.collectGarbage) + 1 s before each reading, Firefox ' +
'and WebKit are read after idle only (no forced GC: indicative). Start = ' +
'editor loaded, before any export. Init = first export (module, fonts, ' +
'first decode). Recurring = L[last] − L[2]: the last 5 exports for 6.'
function options() {
const { values } = parseArgs({
options: {
engines: { type: 'string', default: ENGINES.join(',') },
reports: { type: 'string', default: 'demo,L' },
reps: { type: 'string', default: '1' },
exports: { type: 'string', default: '6' },
out: {
type: 'string',
default: join(RESULTS_DIR, `${today()}-r4-export-series.json`),
},
},
})
const engines = listOf(values.engines)
const reports = listOf(values.reports)
for (const r of reports) {
if (!REPORTS[r]) throw new Error(`unknown report ${r}`)
}
return {
engines,
reports,
reps: Number(values.reps),
exports: Number(values.exports),
out: values.out,
}
}
/** The draft exactly as persistence.ts writes it: JSON.stringify(report). */
function draftOf(name) {
const text = readFileSync(join(FIXTURES_DIR, REPORTS[name].file), 'utf8')
return JSON.stringify(JSON.parse(text))
}
async function openEditor(session, baseUrl, name) {
const context = await session.browser.newContext({
acceptDownloads: true,
locale: 'fr-FR',
})
const seed = { draft: draftOf(name), locale: 'fr', skipDisclaimer: true }
const { page, events } = await probedPage(context, seed)
const cdp =
session.engine === 'chromium' ? await context.newCDPSession(page) : null
await page.goto(`${baseUrl}/editor`)
await page.waitForSelector(CANVAS, { timeout: LOAD_TIMEOUT_MS })
const button = page.getByRole('button', { name: EXPORT_LABEL })
await button.and(page.locator(':enabled')).waitFor()
return { context, page, events, cdp, button }
}
async function reading(session, tab) {
if (tab.cdp) await forcedGc(tab)
return levelNow(session)
}
/** One export: click, the download, the button enabled again; its timing entry. */
async function exportOnce(tab, timeoutMs) {
const download = tab.page.waitForEvent('download', { timeout: 0 })
download.catch(() => undefined)
const started = performance.now()
const end = await Promise.race([
tagged('downloaded', tab.button.click().then(() => download)),
timeoutAfter(timeoutMs),
])
if (end.kind !== 'downloaded') {
return { outcome: end.kind, error: end.error ?? null }
}
await tab.button.and(tab.page.locator(':enabled')).waitFor()
const probe = await tab.page.evaluate(readProbe)
// The probe keeps every raster of the tab: only the last export's count grows it.
const result = {
outcome: 'downloaded',
clickToEndMs: Math.round(performance.now() - started),
exportMs:
probe.clickAt !== null && probe.pdfBlobAt !== null
? probe.pdfBlobAt - probe.clickAt
: null,
rastersSoFar: probe.png.length,
driver: probe.exportTiming,
dialogs: tab.events.dialogs.length,
pageErrors: tab.events.pageErrors.length,
}
// The next export's clock starts afresh.
await tab.page.evaluate(() => {
window.__harness.clickAt = null
window.__harness.pdfBlobAt = null
})
return result
}
/** ONE tab: start level, the init export, `count` more, final. */
async function measureSeries(session, tab, name, count) {
if (!tab.cdp) await delay(IDLE_SETTLE_MS)
const levels = [await reading(session, tab)]
await session.watchdog.resetPeak()
const exports = []
for (let i = 0; i <= count; i += 1) {
const row = await exportOnce(tab, REPORTS[name].timeoutMs)
exports.push(row)
if (row.outcome !== 'downloaded') {
return { outcome: row.outcome, error: row.error, exports }
}
await delay(BETWEEN_MS)
levels.push(await reading(session, tab))
}
await delay(FINAL_IDLE_MS)
levels.push(await reading(session, tab))
const peak = session.watchdog.snapshot()
const content = levels.map((l) => l.rssContentBytes)
const summed = levels.map((l) => l.rssBytes)
return {
outcome: 'series',
exports,
levels: { content, summed },
deltas: {
content: deltasOf(content, count),
summed: deltasOf(summed, count),
},
peakBytes: peak.peakBytes,
peakContentBytes: peak.peakContentBytes,
withinTolerance: deltasOf(content, count).last5 <= TEN_MIB,
pageErrors: tab.events.pageErrors,
consoleErrors: tab.events.consoleErrors.slice(0, 20),
}
}
async function seriesRun(pw, { engine, baseUrl, report, rep, count }) {
const session = await launchEngine(pw, engine)
const head = { engine, engineVersion: session.version, report, rep }
try {
const tab = await openEditor(session, baseUrl, report)
const measured = await measureSeries(session, tab, report, count)
return { ...head, ...measured }
} catch (error) {
const stopped = session.watchdog.snapshot().stopped
const outcome = stopped ? 'stopped_by_ceiling' : 'error'
return { ...head, outcome, error: firstLine(error) }
} finally {
await closeEngine(session)
}
}
const mib = (bytes) => (bytes / 1024 / 1024).toFixed(1)
function table(runs) {
const lines = [
'| Engine | Report | Rep | Outcome | Init MiB | Per export MiB | Recurring (last 5) MiB | Final idle MiB | Peak content MiB | Export ms (median after init) | Core ms (median) |',
'|---|---|---|---|---|---|---|---|---|---|---|',
]
for (const run of runs) {
if (run.outcome !== 'series') {
lines.push(
`| ${run.engine} | ${run.report} | ${run.rep} | ${run.outcome} | | | | | | | |`,
)
continue
}
const d = run.deltas.content
const after = run.exports.slice(1)
const median = (values) => {
const sorted = values.filter((v) => v != null).sort((a, b) => a - b)
return sorted.length ? sorted[Math.floor(sorted.length / 2)] : null
}
const exportMs = median(after.map((e) => e.exportMs))
const coreMs = median(after.map((e) => e.driver?.coreMs ?? null))
lines.push(
`| ${run.engine} | ${run.report} | ${run.rep} | series | ${mib(d.init)} | ${d.perImport.map(mib).join(' / ')} | ${mib(d.last5)}${run.withinTolerance ? '' : ' (over)'} | ${mib(d.finalIdle)} | ${mib(run.peakContentBytes)} | ${exportMs === null ? '' : Math.round(exportMs)} | ${coreMs === null ? '' : Math.round(coreMs)} |`,
)
}
return lines.join('\n')
}
async function main() {
const opts = options()
const build = checkBuild()
const pw = loadPlaywright()
const server = await startServer({ csp: 'with' })
const runs = []
try {
for (const engine of opts.engines) {
for (const report of opts.reports) {
for (let rep = 1; rep <= opts.reps; rep += 1) {
const run = await seriesRun(pw, {
engine,
baseUrl: server.url,
report,
rep,
count: opts.exports,
})
log(`series ${engine} ${report} #${rep}: ${run.outcome}`)
runs.push(run)
}
}
}
} finally {
await server.close()
}
const result = {
harness: 'scripts/browser/r4-export-series.mjs',
startedAt: new Date().toISOString(),
readings: READINGS,
toleranceBytes: TEN_MIB,
watchdog: watchdogFacts(),
host: hostFacts(),
build,
options: opts,
runs,
}
mkdirSync(dirname(opts.out), { recursive: true })
writeFileSync(opts.out, `${JSON.stringify(result, null, 2)}\n`)
log(`results written to ${opts.out}`)
console.log(table(runs))
}
await main()
+152
View File
@@ -0,0 +1,152 @@
// R4 J2 device acceptance kit (R4.6, the Rust export): gathers in one folder
// the archive PDFs the owner imports from a phone or a computer and then
// exports again with the Rust writer, so that the exported file can be
// compared with the reference of the same bilan (docs/development/R4_J2.md).
// 1-reference/ the R3 exports of the TypeScript engine (FR / EN, with and
// without logos, the real-raster export, the store path):
// import one, export it, compare the two files side by side.
// 2-large/ the L (60 observations, 120 views) and CAP (500 / 1,000)
// synthetic reports as archive PDFs written by the Rust
// session with 2 × 1 stub rasters (small files: the phone
// draws the real rasters when it exports them).
// Synthetic data only. Usage: node scripts/r4-j2-kit.mjs [out-dir]
// (default: a `faunosteo-j2-kit` folder next to the repository; the core
// module built: pnpm wasm:build).
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { join, resolve } from 'node:path'
import { fileURLToPath, pathToFileURL } from 'node:url'
const ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)))
const FIXTURES = join(ROOT, 'apps/app/tests/fixtures')
const SEED = join(ROOT, 'supabase/seed/anatomical-sheets/equine/draft')
const PKG = join(ROOT, 'packages/core-wasm/pkg')
const OUT = resolve(process.argv[2] ?? join(ROOT, '..', 'faunosteo-j2-kit'))
const TWO_BY_ONE_PNG = Buffer.from(
'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAAD0lEQVR4nGPYEWX///9/AA0PBE/1T7nxAAAAAElFTkSuQmCC',
'base64',
)
const REFERENCE = [
'demo.fr.logos',
'demo.en.logos',
'demo.fr.nologos',
'v2full.fr.logos',
'v2unresolved.fr.logos',
'store-path.fr.nologos',
]
const read = (path) => readFileSync(path, 'utf8')
/** The bundled draft exactly as `apps/app/vite/sheet-bundle.ts` embeds it. */
function draftBundle() {
const manifest = JSON.parse(read(join(SEED, 'assets.json')))
const assets = {}
const assetHashes = {}
for (const asset of manifest) {
assets[asset.svg_asset_id] = read(join(SEED, 'assets', asset.file))
assetHashes[asset.svg_asset_id] = asset.sha256
}
return JSON.stringify({
status: 'draft',
ref: JSON.parse(read(join(SEED, 'sheet-ref.json'))),
document: JSON.parse(read(join(SEED, 'document.json'))),
migrationMap: JSON.parse(read(join(SEED, 'report-migration-map.json'))),
assets,
assetHashes,
})
}
/** The shipped module, instantiated once. */
async function loadGlue() {
const glue = await import(pathToFileURL(join(PKG, 'faunosteo_wasm.js')).href)
const module = await WebAssembly.compile(
readFileSync(join(PKG, 'faunosteo_wasm_bg.wasm')),
)
await glue.default({ module_or_path: module })
return glue
}
function unwrap(text, what) {
const outcome = JSON.parse(text)
if (!outcome.ok) throw new Error(`${what}: ${outcome.kind} ${outcome.detail ?? ''}`)
return outcome.value
}
function copy(from, toDir, name) {
mkdirSync(toDir, { recursive: true })
writeFileSync(join(toDir, name), readFileSync(from))
}
/** The synthetic report in the demo export's envelope, exported by the session. */
function largeArchive(glue, demo, name) {
const report = JSON.parse(read(join(FIXTURES, `r4/reports/${name}.json`)))
report.sheet = demo.report.sheet
const input = JSON.stringify({
report,
sheetSnapshot: demo.sheetSnapshot,
branding: demo.branding,
labels: demo.labels,
locale: 'fr',
exportedAt: new Date().toISOString(),
})
const session = new glue.ExportSession(input)
try {
for (;;) {
const step = unwrap(session.next_step(), 'next')
if (step.step === 'done') break
for (const request of step.requests) {
unwrap(session.add_raster(request.key, TWO_BY_ONE_PNG), request.key)
}
}
const count = session.finish()
const parts = []
for (let i = 0; i < count; i += 1) parts.push(session.take_part())
return Buffer.concat(parts)
} finally {
session.free()
}
}
const lines = [
'# Kit J2 (R4.6) — fichiers de la recette de l’export Rust',
'',
'## 1-reference/ (exports du moteur TypeScript, R3)',
'',
'Importer le fichier depuis l’accueil, puis « Exporter en PDF » dans l’éditeur :',
'le fichier exporté se compare au fichier importé (mêmes pages, mêmes textes,',
'mêmes images, mêmes liens ; seule la date d’export change).',
'',
]
for (const name of REFERENCE) {
copy(join(FIXTURES, `pdf/r3/${name}.pdf`), join(OUT, '1-reference'), `r3-${name}.pdf`)
lines.push(`- \`r3-${name}.pdf\``)
}
copy(
join(FIXTURES, 'pdf/r3/real/v2full-obs1.fr.logos.pdf'),
join(OUT, '1-reference'),
'r3-real.v2full-obs1.fr.logos.pdf',
)
lines.push('- `r3-real.v2full-obs1.fr.logos.pdf` (rasters réels du navigateur)', '')
lines.push(
'## 2-large/ (rapports synthétiques, écrits par la session Rust)',
'',
'Importer, puis exporter : le téléphone dessine lui-même les 120 (L) ou 1 000 (CAP)',
'vues. L doit aboutir sur le téléphone (E4) ; CAP est réservé à l’ordinateur.',
'',
)
const glue = await loadGlue()
const sheet = new glue.SheetHandle(draftBundle())
const demo = unwrap(
sheet.import_pdf(new Uint8Array(readFileSync(join(FIXTURES, 'pdf/r3/demo.fr.logos.pdf')))),
'demo',
).read.archive
for (const name of ['L', 'CAP']) {
const pdf = largeArchive(glue, demo, name)
mkdirSync(join(OUT, '2-large'), { recursive: true })
writeFileSync(join(OUT, '2-large', `${name}.fr.logos.pdf`), pdf)
lines.push(`- \`${name}.fr.logos.pdf\` (${(pdf.byteLength / 1024).toFixed(0)} Ko)`)
}
lines.push('')
writeFileSync(join(OUT, 'ATTENDU.md'), `${lines.join('\n')}\n`)
console.log(`kit written to ${OUT}`)
+17 -8
View File
@@ -88,13 +88,26 @@ const SAFE_TEXT =
const WRAP = 'cargo pdf_text::wrap_lines_reproduces_every_case'
const DATES =
'cargo pdf_text::format_date_reproduces_the_intl_grid_and_the_others'
const CARGO_GOLDENS = 'R4.4/R4.5 cargo goldens (pending)'
/** R4.6: the Step 6 goldens hold on the app path, read back from the file's content
* streams (tests/helpers/pdfRead.ts), and in cargo from the draw log and the O2 runs. */
const CARGO_GOLDENS =
'vitest (same case, read from the file); cargo pdf_layout::step6_text_and_image_goldens_derive_from_the_log, pdf_serialize::o2_streams_images_links_info_and_attachment_match_the_r3_build'
const RASTER_CHECK =
'vitest (same case); cargo pdf_png::every_o6_decode_matches_pdf_lib'
const SAME = 'vitest (same case)'
const NONE = '-'
const GENERATOR = 'generator; oracle files kept (R4.8)'
const N1_SWITCH = 'reader switched to the frozen O11 scanner at R4.8'
const PDF_LIB_LEAVES =
'pdf-lib leaves the app; read-back moves to cargo/lopdf or the wasm reader'
/** R4.6: the export side of these cases runs on the core; the reader is the kept TS one
* until R4.8, the kinds and round trips are cargo's. */
const IMPORT_R46 =
'vitest (same case, export on the core); cargo pdf_import (kinds), pdf_serialize::restoration_round_trip_loses_nothing'
/** R4.6: the roundtrip suite reads the Rust export's content streams and metadata through
* pdf-lib (kept in the tests until R4.8); the read-back is cargo's from R4.8. */
const ROUNDTRIP_R46 =
'vitest (same case, read from the file); cargo pdf_serialize::restoration_round_trip_loses_nothing from R4.8'
const ported = (target, oracle, note = NONE) => ({
disposition: 'ported',
@@ -222,11 +235,7 @@ const RULES = [
{
file: GOLDENS,
title: 'golden inputs > the 2×1 PNG decodes',
...replaced(
CARGO_GOLDENS,
'O6',
'pdf-lib embedPng check of the golden rasters',
),
...replaced(RASTER_CHECK, 'O6', 'pdf-lib embedPng check of the golden rasters'),
},
{
file: GOLDENS,
@@ -250,11 +259,11 @@ const RULES = [
},
{
file: `${APP}pdf.import.test.ts`,
...replaced('R4.3/R4.5 (pending)', NONE, PDF_LIB_LEAVES),
...replaced(IMPORT_R46, NONE, PDF_LIB_LEAVES),
},
{
file: `${APP}pdf.roundtrip.test.ts`,
...replaced('R4.3/R4.5 (pending)', NONE, PDF_LIB_LEAVES),
...replaced(ROUNDTRIP_R46, NONE, PDF_LIB_LEAVES),
},
{ file: `${APP}archive.envelopes.test.ts`, ...kept(NONE, N1_SWITCH) },
{ file: `${APP}n-1.reader.test.ts`, ...kept(NONE, N1_SWITCH) },