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

+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()