@flighthq/tool-capture 0.1.0

package/dist/baselineStore.d.ts

@@ -0,0 +1,5 @@
+export type BaselineField = 'fingerprint' | 'sha256';
+export declare function baselinePath(root: string, subject: string, name: string): string;
+export declare function getBaselineField(root: string, subject: string, name: string, column: string, field: BaselineField): string | null;
+export declare function setBaselineField(root: string, subject: string, name: string, column: string, field: BaselineField, value: string): void;
+//# sourceMappingURL=baselineStore.d.ts.map

package/dist/baselineStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baselineStore.d.ts","sourceRoot":"","sources":["../src/baselineStore.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,QAAQ,CAAC;AAWrD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,GACnB,MAAM,GAAG,IAAI,CAEf;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,GACZ,IAAI,CAKN"}

package/dist/baselineStore.js

@@ -0,0 +1,54 @@
+// Per-test committed baseline store: one JSON file per test at <subject-root>/baselines/<name>.json,
+// holding every column's values, e.g. { "canvas": { "fingerprint": "…", "sha256": "…" }, "flight:webgl": {…} }.
+// captureEntry writes each column's `sha256` (screenshot hash); compare-render writes its `fingerprint`
+// (coarse render fingerprint). Both read-merge-write so they preserve each other's fields and the other
+// columns. Output is prettier-compatible (sorted keys, 2-space, trailing newline) so it never churns the
+// format gate. Replaces the old tools/baselines/<subject>/<name>/<renderer>/{fingerprint.txt,baseline.sha256}.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// Per-subject baseline root: baselines colocate with their suite (functional/examples are
+// top-level). One JSON file per test under the root's baselines/ dir.
+const BASELINE_ROOTS = {
+    functional: 'functional',
+    examples: 'examples',
+};
+export function baselinePath(root, subject, name) {
+    const base = BASELINE_ROOTS[subject] ?? subject;
+    return join(root, base, 'baselines', `${name}.json`);
+}
+export function getBaselineField(root, subject, name, column, field) {
+    return readBaseline(baselinePath(root, subject, name))[column]?.[field] ?? null;
+}
+export function setBaselineField(root, subject, name, column, field, value) {
+    const path = baselinePath(root, subject, name);
+    const data = readBaseline(path);
+    (data[column] ??= {})[field] = value;
+    writeBaseline(path, data);
+}
+function readBaseline(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+// Stable, prettier-compatible serialisation: columns and fields in sorted order so a re-baseline of one
+// column produces a minimal diff and the format gate stays green.
+function writeBaseline(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    const sorted = {};
+    for (const column of Object.keys(data).sort()) {
+        const entry = data[column];
+        const out = {};
+        if (entry.fingerprint !== undefined)
+            out.fingerprint = entry.fingerprint;
+        if (entry.sha256 !== undefined)
+            out.sha256 = entry.sha256;
+        sorted[column] = out;
+    }
+    writeFileSync(path, JSON.stringify(sorted, null, 2) + '\n');
+}
+//# sourceMappingURL=baselineStore.js.map

package/dist/baselineStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baselineStore.js","sourceRoot":"","sources":["../src/baselineStore.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,gHAAgH;AAChH,wGAAwG;AACxG,wGAAwG;AACxG,yGAAyG;AACzG,+GAA+G;AAC/G,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAM1C,0FAA0F;AAC1F,sEAAsE;AACtE,MAAM,cAAc,GAA2B;IAC7C,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,UAAU;CACrB,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAe,EAAE,IAAY;IACtE,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC;IAChD,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAAe,EACf,IAAY,EACZ,MAAc,EACd,KAAoB;IAEpB,OAAO,YAAY,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAAe,EACf,IAAY,EACZ,MAAc,EACd,KAAoB,EACpB,KAAa;IAEb,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;IACrC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAiB,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,wGAAwG;AACxG,kEAAkE;AAClE,SAAS,aAAa,CAAC,IAAY,EAAE,IAAkB;IACrD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,GAAG,GAAmB,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;YAAE,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACzE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC1D,MAAM,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAC9D,CAAC"}

package/dist/captureBrowser.d.ts

@@ -0,0 +1,9 @@
+import type { Browser, BrowserContext } from '@playwright/test';
+export declare function launchBrowser(options?: {
+    captureFrames?: number;
+    verify?: boolean;
+}): Promise<{
+    browser: Browser;
+    context: BrowserContext;
+}>;
+//# sourceMappingURL=captureBrowser.d.ts.map

package/dist/captureBrowser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureBrowser.d.ts","sourceRoot":"","sources":["../src/captureBrowser.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEhE,wBAAsB,aAAa,CACjC,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACzD,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC,CA+FxD"}

package/dist/captureBrowser.js

@@ -0,0 +1,83 @@
+// Headless Chromium launch for a capture run, plus the pre-script init that makes every capture
+// deterministic: a fixed viewport, capture-mode flag, seeded Math.random, and the optional frame-halt.
+//
+// Playwright is imported lazily (a dynamic import inside launchBrowser) so that importing this package
+// has no top-level Playwright cost and pulls no browser driver into a consumer's module graph until a
+// capture is actually run. Only the `chromium` value is loaded this way; the Browser/BrowserContext
+// types are erased at compile time.
+export async function launchBrowser(options = {}) {
+    const { chromium } = await import('@playwright/test');
+    // Headless Chromium exposes navigator.gpu but withholds a Wgpu adapter on a software-only,
+    // "untrusted" config unless --enable-unsafe-webgpu is set; with it, Dawn falls back to the
+    // SwiftShader Vulkan ICD bundled inside Playwright's Chromium (no host GPU / driver needed).
+    // --use-webgpu-adapter=swiftshader pins that software adapter so output is identical on a dev
+    // machine with a real GPU and in CI — required for stable cross-backend baselines.
+    const browser = await chromium.launch({
+        args: ['--enable-unsafe-webgpu', '--use-webgpu-adapter=swiftshader'],
+    });
+    const context = await browser.newContext({ viewport: { width: 800, height: 600 } });
+    // Always signal capture mode before any page script runs. A page whose render advances over time
+    // holds a fixed, self-seeded frame in this mode (the landing backgrounds do), so its screenshot —
+    // and thus its baseline hash — is byte-identical run to run. Pages that ignore the flag animate.
+    //
+    // Also seed Math.random with a fixed value so a scene built with random positions/colours renders
+    // the same on every load and backend — what makes the render fingerprint stable run-to-run (Tier 5)
+    // and lets the cross-backend differential (Tier 3) compare like with like. It does not pin the clock,
+    // so time-based animation is not frozen here — the --frames halt handles that. (Pages with their own
+    // seeded RNG, like the landing, are unaffected.) The generator is mulberry32 — the same algorithm as
+    // the SDK's createRandomSource (@flighthq/math), inlined below; see the note there for why it cannot
+    // be imported into this pre-module, bare-page init script.
+    //
+    // Optionally also install a frame-halt (the --frames=N mode): count the page's animation frames,
+    // and on the Nth one stop invoking its callback so the scene halts on a fixed frame, then flag it
+    // for the screenshot. N=1 is the robust common case (frame 1 always completes before the screenshot,
+    // with no settle-timing race).
+    const captureFrames = options.captureFrames ?? 0;
+    const verify = options.verify ?? true;
+    await context.addInitScript((args) => {
+        const flags = window;
+        const { frames, verify } = args;
+        flags.__flightCapture = true;
+        flags.__flightCaptureVerify = verify;
+        // Inline mulberry32 — the exact algorithm of the SDK's createRandomSource (@flighthq/math). It is
+        // copied (not imported) on purpose: addInitScript is serialized and injected before any module
+        // loads, and the SDK function's *built* source references bundler helpers (e.g. __name) that do
+        // not exist in this bare page context, so injecting its source breaks. Keep this in sync with that
+        // one function — it is the only duplicate, and it is trivial and frozen.
+        let seed = 0x9e3779b9 >>> 0;
+        Math.random = () => {
+            seed = (seed + 0x6d2b79f5) | 0;
+            let r = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+            r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+            return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+        };
+        if (frames < 1)
+            return;
+        flags.__captureFramesReached = false;
+        // Force preserveDrawingBuffer so the halted Gl frame survives in the buffer for the screenshot
+        // (the default clears it once composited, which would shoot blank once the loop stops).
+        const realGetContext = HTMLCanvasElement.prototype.getContext;
+        HTMLCanvasElement.prototype.getContext = function (type, attrs) {
+            if (type === 'webgl' || type === 'webgl2' || type === 'experimental-webgl') {
+                return realGetContext.call(this, type, { ...attrs, preserveDrawingBuffer: true });
+            }
+            return realGetContext.call(this, type, attrs);
+        };
+        let count = 0;
+        const realRequestAnimationFrame = window.requestAnimationFrame.bind(window);
+        // Expose the un-hijacked rAF so the render verifier can await a genuine presented frame before it
+        // reads the canvas back. The override below stops invoking callbacks past the halt frame, so a
+        // verifier awaiting window.requestAnimationFrame could hang; it uses this stashed one instead.
+        flags.__ftRealRequestAnimationFrame = realRequestAnimationFrame;
+        window.requestAnimationFrame = (callback) => realRequestAnimationFrame((time) => {
+            if (count >= frames)
+                return; // halt: scene stops advancing on frame N
+            count++;
+            if (count >= frames)
+                flags.__captureFramesReached = true;
+            callback(time);
+        });
+    }, { frames: captureFrames, verify });
+    return { browser, context };
+}
+//# sourceMappingURL=captureBrowser.js.map

package/dist/captureBrowser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureBrowser.js","sourceRoot":"","sources":["../src/captureBrowser.ts"],"names":[],"mappings":"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"}

package/dist/captureEntries.d.ts

@@ -0,0 +1,11 @@
+export declare const RENDERERS: readonly ["dom", "canvas", "webgl", "webgpu"];
+export type Tool = 'examples' | 'functional';
+export interface Entry {
+    name: string;
+    renderers: string[];
+}
+export declare const BACKEND_UNAVAILABLE: RegExp;
+export declare function discoverEntries(tool: Tool, root: string): Entry[];
+export declare function rendererMatchesFilter(renderer: string, filter: readonly string[]): boolean;
+export declare function routeSegment(renderer: string): string;
+//# sourceMappingURL=captureEntries.d.ts.map

package/dist/captureEntries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureEntries.d.ts","sourceRoot":"","sources":["../src/captureEntries.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,SAAS,+CAAgD,CAAC;AACvE,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG,YAAY,CAAC;AAE7C,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AASD,eAAO,MAAM,mBAAmB,QACgJ,CAAC;AAEjL,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,EAAE,CAkBjE;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI1F;AAID,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/captureEntries.js

@@ -0,0 +1,44 @@
+// Capture-subject vocabulary and discovery: the tool set, the renderer id helpers, and the per-tool
+// enumeration of (entry, renderers) pairs the capture pipeline drives.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { discoverFunctionalScenes } from './functionalScenes.js';
+export const RENDERERS = ['dom', 'canvas', 'webgl', 'webgpu'];
+// A backend the environment cannot provide or sustain: WebGPU with no adapter/device, or a software
+// adapter that loses its device mid-run under sustained per-frame GPU load. These are the only
+// null-fingerprint / page-error outcomes that may be skipped rather than failed — the gate verifies
+// backends where they exist and stays green on machines without them. A real render bug still fails:
+// a validation error (bad writeBuffer/copy) is logged before the device dies, and is matched first.
+// Shared with compare-render.ts so the smoke gate and the parity/regression gate agree on what counts
+// as "unavailable".
+export const BACKEND_UNAVAILABLE = /WebGPU adapter|WebGPU device|requestAdapter|requestDevice|GPUAdapter|WebGPU is not supported|external Instance reference no longer exists|device (was )?lost|device is lost/i;
+export function discoverEntries(tool, root) {
+    // Functional scenes are flat files under functional/scenes/; the shared discovery is the single
+    // source of truth (also used by tools/functional/vite.config.ts).
+    if (tool === 'functional')
+        return discoverFunctionalScenes(join(root, 'functional', 'scenes'));
+    const dir = join(root, 'examples', 'packages');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, 'package.json')))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map(({ name }) => {
+        const testDir = join(dir, name);
+        const customRenderers = RENDERERS.filter((r) => existsSync(join(testDir, `src/render.${r}.ts`)));
+        return { name, renderers: customRenderers };
+    })
+        .filter((e) => e.renderers.length > 0);
+}
+export function rendererMatchesFilter(renderer, filter) {
+    if (filter.length === 0)
+        return true;
+    const backend = renderer.includes(':') ? renderer.slice(renderer.indexOf(':') + 1) : renderer;
+    return filter.includes(renderer) || filter.includes(backend);
+}
+// A column id may carry a `<library>:<renderer>` colon; map it to a URL/dir-safe
+// segment. Colon-free ids (canvas, webgl, …) pass through unchanged.
+export function routeSegment(renderer) {
+    return renderer.replace(':', '-');
+}
+//# sourceMappingURL=captureEntries.js.map

package/dist/captureEntries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureEntries.js","sourceRoot":"","sources":["../src/captureEntries.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,uEAAuE;AAEvE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAQvE,oGAAoG;AACpG,+FAA+F;AAC/F,oGAAoG;AACpG,qGAAqG;AACrG,oGAAoG;AACpG,sGAAsG;AACtG,oBAAoB;AACpB,MAAM,CAAC,MAAM,mBAAmB,GAC9B,8KAA8K,CAAC;AAEjL,MAAM,UAAU,eAAe,CAAC,IAAU,EAAE,IAAY;IACtD,gGAAgG;IAChG,kEAAkE;IAClE,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,wBAAwB,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE/F,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;SAC/E,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE;QAChB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAChC,MAAM,eAAe,GAAI,SAA+B,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACpE,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAChD,CAAC;QACF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;IAC9C,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,MAAyB;IAC/E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC9F,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,iFAAiF;AACjF,qEAAqE;AACrE,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC"}

package/dist/captureEntry.d.ts

@@ -0,0 +1,83 @@
+import type { BrowserContext } from '@playwright/test';
+import type { Entry, Tool } from './captureEntries.js';
+export interface CaptureStatus {
+    state: 'ready' | 'error';
+    capturedAt: number;
+    error: string | null;
+    hash: string | null;
+    /** The committed baseline sha256, or null when no baseline exists yet. */
+    baselineHash: string | null;
+    /** null = no baseline exists yet; false = hash matches baseline; true = hash differs from baseline */
+    changed: boolean | null;
+}
+export interface CaptureEntryOptions {
+    context: BrowserContext;
+    entry: Entry;
+    renderers: string[];
+    baseUrl: string;
+    tool: Tool;
+    outBase: string;
+    /** Repo root — committed baselines live at tests/<tool>/baselines/<name>.json. */
+    root: string;
+    /** When true, writes the current screenshot hash as the new baseline instead of comparing. */
+    updateBaseline?: boolean;
+    extraWait?: number;
+    /**
+     * When set (≥1), run the page's animation loop exactly this many frames, halt it on that frame,
+     * and screenshot it — a deterministic "capture the Nth frame" mode. Omit for the default behavior
+     * (render two frames and shoot, letting self-freezing pages like the landing hold their frame).
+     * Must match the value passed to launchBrowser, which installs the frame-halt in the page.
+     */
+    captureFrames?: number;
+    /**
+     * When true, an entry whose page logged an error or page error (a thrown exception, a failed
+     * request, or a render-verification failure from the functional harness) counts as a failure. This
+     * is the render smoke/not-blank gate: "CI green" then means every entry loaded and drew without
+     * error on every backend.
+     */
+    failOnError?: boolean;
+    /**
+     * Polled before each renderer: when it returns true the run is being interrupted (Ctrl+C), so the
+     * renderer loop stops and a torn-down page is not reported as a failure. See installAbortHandler.
+     */
+    isAborted?: () => boolean;
+    /**
+     * When set, replaces the renderer name in status lines. Used by captureParallel so each line
+     * identifies its entry: `entry.name/renderer` rather than just `renderer`.
+     */
+    displayLabel?: string;
+}
+export interface ParallelCaptureOptions {
+    context: BrowserContext;
+    entries: Entry[];
+    rendererFilter: string[];
+    baseUrl: string;
+    tool: Tool;
+    outBase: string;
+    root: string;
+    updateBaseline?: boolean;
+    extraWait?: number;
+    captureFrames?: number;
+    failOnError?: boolean;
+    isAborted?: () => boolean;
+    /** Number of Playwright pages to run concurrently. Default: 6. */
+    workerCount?: number;
+}
+export interface ParallelCaptureResult {
+    captured: number;
+    changed: number;
+    failed: number;
+}
+/** The artifact file paths for one (tool, entry, renderer) capture, under the output base directory. */
+export interface CaptureOutputPaths {
+    outDir: string;
+    tmpScreenshot: string;
+    finalScreenshot: string;
+    tmpLogs: string;
+    finalLogs: string;
+    statusPath: string;
+}
+export declare function captureEntry(opts: CaptureEntryOptions): Promise<'ok' | 'changed' | 'error'>;
+export declare function captureParallel(opts: ParallelCaptureOptions): Promise<ParallelCaptureResult>;
+export declare function getCaptureOutputPaths(outBase: string, tool: Tool, name: string, renderer: string): CaptureOutputPaths;
+//# sourceMappingURL=captureEntry.d.ts.map

package/dist/captureEntry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureEntry.d.ts","sourceRoot":"","sources":["../src/captureEntry.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAQ,MAAM,kBAAkB,CAAC;AAI7D,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAMvD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sGAAsG;IACtG,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wGAAwG;AACxG,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,CA+PjG;AA2CD,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA8ClG;AAKD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAUrH"}