@flighthq/tool-capture 0.2.0 → 0.2.1-next.423.3350e53

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// The tool-capture CLI. First (and currently only) command: `observe <url>` — the standalone eyes
+// primitive. Point it at any running page and it drives a deterministic headless render, grabs the
+// present frame (via the getContext intercept — zero page integration), and writes screenshot.png +
+// logs.jsonl + status.json (with the observe diagnostics block). No capture script or discovery needed
+// in the consumer; a repo just adds `"capture:observe": "tool-capture observe"` and points it at a URL.
+import { resolve } from 'node:path';
+import { captureUrl } from './captureEntry.js';
+const USAGE = 'usage: tool-capture observe <url> [--out <dir>] [--wait <ms>] [--frames <n>]';
+function flag(argv, key) {
+    const i = argv.indexOf(`--${key}`);
+    return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : undefined;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv[0] !== 'observe') {
+        console.error(USAGE);
+        process.exit(2);
+    }
+    const url = argv[1];
+    if (url === undefined || url.startsWith('--')) {
+        console.error(`observe requires a <url>\n${USAGE}`);
+        process.exit(2);
+    }
+    const outDir = resolve(flag(argv, 'out') ?? './capture');
+    const wait = Number.parseInt(flag(argv, 'wait') ?? '0', 10) || 0;
+    const captureFrames = Number.parseInt(flag(argv, 'frames') ?? '1', 10) || 1;
+    const diagnostics = await captureUrl(url, { outDir, wait, captureFrames });
+    console.log(`captured → ${resolve(outDir, 'screenshot.png')}`);
+    console.log(`observe   ${JSON.stringify(diagnostics)}`);
+    // Exit explicitly — the browser's live handles would otherwise keep the event loop alive after
+    // teardown and hang the process (the same trap the capture scripts hit).
+    process.exit(0);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,kGAAkG;AAClG,mGAAmG;AACnG,oGAAoG;AACpG,uGAAuG;AACvG,wGAAwG;AAExG,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,KAAK,GAAG,8EAA8E,CAAC;AAE7F,SAAS,IAAI,CAAC,IAAuB,EAAE,GAAW;IAChD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,OAAO,CAAC,KAAK,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,WAAW,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IACjE,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAE5E,MAAM,WAAW,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,GAAG,CAAC,cAAc,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxD,+FAA+F;IAC/F,yEAAyE;IACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/captureBrowser.d.ts

@@ -2,6 +2,7 @@ import type { Browser, BrowserContext } from '@playwright/test';
 export declare function launchBrowser(options?: {
     captureFrames?: number;
     verify?: boolean;
+    observe?: boolean;
 }): Promise<{
     browser: Browser;
     context: BrowserContext;

package/dist/captureBrowser.d.ts.map

@@ -1 +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"}
+{"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,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5E,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC,CAwLxD"}

package/dist/captureBrowser.js

@@ -34,9 +34,10 @@ export async function launchBrowser(options = {}) {
     // with no settle-timing race).
     const captureFrames = options.captureFrames ?? 0;
     const verify = options.verify ?? true;
+    const observe = options.observe ?? false;
     await context.addInitScript((args) => {
         const flags = window;
-        const { frames, verify } = args;
+        const { frames, verify, observe } = args;
         flags.__flightCapture = true;
         flags.__flightCaptureVerify = verify;
         // Inline mulberry32 — the exact algorithm of the SDK's createRandomSource (@flighthq/math). It is
@@ -54,15 +55,40 @@ export async function launchBrowser(options = {}) {
         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).
+        // Own the GL-context boundary. Forcing preserveDrawingBuffer keeps the halted frame in the buffer
+        // for the screenshot (the default clears it once composited, shooting blank once the loop stops).
+        // Recording each (canvas, gl) here is what lets the harness grab the present frame back post-hoc
+        // with ZERO integration: a scene just renders, and captureEntry reads these contexts' default
+        // framebuffers itself (see the intercepted-frame grab) — no client verifier registration needed.
+        flags.__ftGlContexts = [];
         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 });
+                const gl = realGetContext.call(this, type, { ...attrs, preserveDrawingBuffer: true });
+                if (gl !== null && !flags.__ftGlContexts.some((e) => e.gl === gl)) {
+                    flags.__ftGlContexts.push({ canvas: this, gl: gl });
+                }
+                return gl;
             }
             return realGetContext.call(this, type, attrs);
         };
+        // A scene whose first frames render blank while it warms up (async mesh/texture upload, an IBL
+        // bake, a float render target) needs more than `frames` frames before its first non-blank frame.
+        // Freezing hard on frame N would then shoot black. So for a GPU verifier the halt treats `frames`
+        // as a minimum: once past it, keep advancing until the verifier publishes a real (non-blank) frame,
+        // up to this ceiling. Scenes already non-blank by frame N halt at exactly N (unchanged), so stable
+        // baselines are unaffected; only warm-up-slow scenes render the extra frames. A scene that stays
+        // blank to the ceiling still stops, and the verifier guard in captureEntry then fails it — no false
+        // green, no unbounded loop (captureEntry's own 15s wait is the outer bound either way).
+        const warmupCeiling = frames + 600;
+        // Observe-only fallback: a page that registers no verify target takes the canvas-grab path with no
+        // warmup, so an app-loop-driven scene (whose first tick establishes time and hasn't drawn yet) is
+        // frozen blank at frame N. In observe mode, keep advancing such a page until its canvas actually
+        // draws — bounded by this much smaller ceiling (app-loop startup is a few frames, and a genuinely
+        // blank scene must not burn the GPU-warmup's ~10s here). The extra frames are recorded so the
+        // caller can warn that the capture took longer. Gate/baseline mode is untouched (deterministic
+        // freeze at frame N), so this changes no committed hash.
+        const observeWarmupCeiling = frames + 120;
         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
@@ -70,14 +96,73 @@ export async function launchBrowser(options = {}) {
         // 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
+            if (flags.__captureFramesReached)
+                return; // halted: scene holds its last frame
+            if (count >= frames) {
+                const targetKind = flags.__ftTarget?.kind;
+                const gpuVerifying = verify && (targetKind === 'webgl' || targetKind === 'webgpu');
+                let done;
+                if (observe) {
+                    // Eyes mode halts on MEASURED canvas pixels, not the verifier's publish signal — the latter
+                    // false-negatives for whole corpora (e.g. starling/functional render at >0.9 coverage yet
+                    // never publish, so a verifier-gated warmup burns all the way to the ceiling). Cheap inline
+                    // "did anything draw" test: downscale the canvas into a 32×32 2D context and look for any
+                    // pixel differing from the top-left (background). Inlined rather than a named helper on
+                    // purpose — a named function in an addInitScript body gets esbuild's __name() wrapper, which
+                    // is undefined in the injected page (same reason mulberry32 is inlined above). The ceiling
+                    // stays generous when a GPU target is present (a slow IBL bake / async upload can need dozens
+                    // of frames before first pixels), tighter otherwise (an app-loop 2D scene draws within a few).
+                    let drew = false;
+                    const canvas = document.querySelector('canvas');
+                    if (canvas !== null && canvas.width > 0 && canvas.height > 0) {
+                        const off = document.createElement('canvas');
+                        off.width = 32;
+                        off.height = 32;
+                        const ctx = off.getContext('2d');
+                        if (ctx === null) {
+                            drew = true; // can't sample — don't block the halt
+                        }
+                        else {
+                            try {
+                                ctx.drawImage(canvas, 0, 0, 32, 32);
+                                const data = ctx.getImageData(0, 0, 32, 32).data;
+                                const r = data[0];
+                                const g = data[1];
+                                const b = data[2];
+                                for (let i = 4; i < data.length; i += 4) {
+                                    if (Math.abs(data[i] - r) > 8 ||
+                                        Math.abs(data[i + 1] - g) > 8 ||
+                                        Math.abs(data[i + 2] - b) > 8) {
+                                        drew = true;
+                                        break;
+                                    }
+                                }
+                            }
+                            catch {
+                                drew = true; // tainted/unreadable — don't block the halt
+                            }
+                        }
+                    }
+                    done = drew || count >= (gpuVerifying ? warmupCeiling : observeWarmupCeiling);
+                }
+                else if (gpuVerifying) {
+                    const haveRealFrame = (flags.__ftVerification?.fingerprint ?? null) !== null || document.getElementById('ft-error') !== null;
+                    done = haveRealFrame || count >= warmupCeiling;
+                }
+                else {
+                    done = true; // gate/baseline: deterministic freeze at exactly frame N
+                }
+                if (done) {
+                    flags.__ftWarmupFrames = count - frames; // extra frames the warmup cost (0 = none)
+                    flags.__captureFramesReached = true;
+                    return; // halt: scene stops advancing
+                }
+                // else: still warming up — fall through to render another frame
+            }
             count++;
-            if (count >= frames)
-                flags.__captureFramesReached = true;
             callback(time);
         });
-    }, { frames: captureFrames, verify });
+    }, { frames: captureFrames, verify, observe });
     return { browser, context };
 }
 //# sourceMappingURL=captureBrowser.js.map

package/dist/captureBrowser.js.map

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

package/dist/captureEntries.d.ts

@@ -1,8 +1,9 @@
 export declare const RENDERERS: readonly ["dom", "canvas", "webgl", "webgpu"];
-export type Tool = 'examples' | 'functional';
+export type Tool = 'examples' | 'functional' | 'reference';
 export interface Entry {
     name: string;
     renderers: string[];
+    route?: (renderer: string) => string;
 }
 export declare const BACKEND_UNAVAILABLE: RegExp;
 export declare function discoverEntries(tool: Tool, root: string): Entry[];

package/dist/captureEntries.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"captureEntries.d.ts","sourceRoot":"","sources":["../src/captureEntries.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,SAAS,+CAAgD,CAAC;AAIvE,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IAIpB,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC;AASD,eAAO,MAAM,mBAAmB,QACgJ,CAAC;AAEjL,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,EAAE,CAqBjE;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

@@ -13,6 +13,10 @@ export const RENDERERS = ['dom', 'canvas', 'webgl', 'webgpu'];
 // 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) {
+    // 'reference' entries come from the external flight-reference harness (the reference runner supplies
+    // them with routes), not from a directory walk here.
+    if (tool === 'reference')
+        return [];
     // 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')

package/dist/captureEntries.js.map

@@ -1 +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"}
+{"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;AAevE,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,qGAAqG;IACrG,qDAAqD;IACrD,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,EAAE,CAAC;IACpC,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

@@ -9,6 +9,36 @@ export interface CaptureStatus {
     baselineHash: string | null;
     /** null = no baseline exists yet; false = hash matches baseline; true = hash differs from baseline */
     changed: boolean | null;
+    /**
+     * Present only for an observe-mode capture: what the eyes actually saw. Observe never gates or
+     * touches baselines — it always emits a screenshot plus this block so a reviewing agent can tell
+     * "geometry drew but wrong" (blank:false, coverage>0) from "nothing drew" (blank:true, coverage 0)
+     * from "the page crashed" (pageErrorCount>0), instead of dead-ending on "cannot capture".
+     */
+    observe?: CaptureObserveDiagnostics;
+}
+/** What an observe-mode capture saw: the trustworthiness metadata beside the emitted screenshot. */
+export interface CaptureObserveDiagnostics {
+    /** No verified/non-blank frame was produced — the emitted screenshot is a fallback, likely blank/black. */
+    blank: boolean;
+    /** Render backend: canvas | dom | webgl | webgpu. */
+    backend: string;
+    /** The functional verify-target kind the page registered, or null when it registered none. */
+    verifyTargetKind: string | null;
+    /** True when the in-page verifier published a non-blank frame (window.__ftRenderImage). */
+    verifyPublished: boolean;
+    /** Verifier-reported non-background coverage in 0..1, or null when the page exposed none. */
+    coverage: number | null;
+    /** Uncaught page exceptions the page threw (a non-zero count means broken code, not a backend limit). */
+    pageErrorCount: number;
+    /** Console/network error logs (a failed asset, a console.error), excluding page exceptions. */
+    errorCount: number;
+    /**
+     * Extra animation frames the observe warmup rendered past the requested count to coax a first draw out
+     * of an app-loop-driven page (see launchBrowser). 0 = drew immediately. A large value that still ended
+     * blank means the warmup gave up at its ceiling — the scene never drew, not that it merely started late.
+     */
+    warmupFrames: number;
 }
 export interface CaptureEntryOptions {
     context: BrowserContext;
@@ -36,6 +66,14 @@ export interface CaptureEntryOptions {
      * error on every backend.
      */
     failOnError?: boolean;
+    /**
+     * Eyes mode. When true the capture never fails closed: a blank/failed verifier readback that would
+     * otherwise throw ("cannot capture") instead emits a best-available screenshot and records a
+     * `CaptureObserveDiagnostics` block in status.json. Observe does not gate and does not compare or
+     * write baselines — it is for an agent (or human) to SEE a scene, not to pass/fail it. Overrides
+     * failOnError/updateBaseline behavior for the run.
+     */
+    observe?: 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.
@@ -46,6 +84,12 @@ export interface CaptureEntryOptions {
      * identifies its entry: `entry.name/renderer` rather than just `renderer`.
      */
     displayLabel?: string;
+    /**
+     * Forces (true) or disables (false) the in-page render-verification wait + surface readback. Defaults
+     * to `tool === 'functional'`. An external subject (reference) sets it true once its pages register a
+     * functional target, so its WebGL captures read the fingerprinted surface instead of a black canvas.
+     */
+    verify?: boolean;
 }
 export interface ParallelCaptureOptions {
     context: BrowserContext;
@@ -59,7 +103,9 @@ export interface ParallelCaptureOptions {
     extraWait?: number;
     captureFrames?: number;
     failOnError?: boolean;
+    observe?: boolean;
     isAborted?: () => boolean;
+    verify?: boolean;
     /** Number of Playwright pages to run concurrently. Default: 6. */
     workerCount?: number;
 }
@@ -77,7 +123,25 @@ export interface CaptureOutputPaths {
     finalLogs: string;
     statusPath: string;
 }
+export declare function buildCaptureObserveDiagnostics(args: {
+    backend: string;
+    blank: boolean;
+    coverage: number | null;
+    logs: readonly unknown[];
+    verifyPublished: boolean;
+    verifyTargetKind: string | null;
+    warmupFrames: number;
+}): CaptureObserveDiagnostics;
 export declare function captureEntry(opts: CaptureEntryOptions): Promise<'ok' | 'changed' | 'error'>;
 export declare function captureParallel(opts: ParallelCaptureOptions): Promise<ParallelCaptureResult>;
+export declare function captureUrl(url: string, options: Readonly<CaptureUrlOptions>): Promise<CaptureObserveDiagnostics>;
+export interface CaptureUrlOptions {
+    /** Directory to write screenshot.png / logs.jsonl / status.json into (flat, one page). */
+    outDir: string;
+    /** Extra settle time after the frame halt, in ms. */
+    wait?: number;
+    /** Frame-halt minimum (see launchBrowser); 1 is the robust default. */
+    captureFrames?: number;
+}
 export declare function getCaptureOutputPaths(outBase: string, tool: Tool, name: string, renderer: string): CaptureOutputPaths;
 //# sourceMappingURL=captureEntry.d.ts.map

package/dist/captureEntry.d.ts.map

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