@flighthq/tool-capture 0.3.0 → 0.3.1-next.1041.35b950c

package/src/captureBaselineSanity.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { isRejectedCaptureBaselineHash, isUniformCaptureFingerprint } from './captureBaselineSanity';
+
+describe('isRejectedCaptureBaselineHash', () => {
+  it('rejects the known blank frame a software WebGPU adapter produces', () => {
+    // Nearly committed as ground truth once; every write path must refuse it without anyone looking.
+    expect(isRejectedCaptureBaselineHash('a4f2105ecdefec94c5fe749c1dc5f2fb9dd74b9832cba0afcd3434f38c0380d0')).toBe(
+      true,
+    );
+  });
+
+  it('accepts an ordinary hash, including one differing only in its last character', () => {
+    expect(isRejectedCaptureBaselineHash('a4f2105ecdefec94c5fe749c1dc5f2fb9dd74b9832cba0afcd3434f38c0380d1')).toBe(
+      false,
+    );
+    expect(isRejectedCaptureBaselineHash('0b7af17177ffeb0f0f88c03546a86af9a9ef9274116cb05c0d82561b5c1a51be')).toBe(
+      false,
+    );
+  });
+});
+
+describe('isUniformCaptureFingerprint', () => {
+  it('rejects a fingerprint whose cells are all identical, the blank frame a stability check cannot catch', () => {
+    // The real shape that was blessed once: every cell the same colour.
+    expect(isUniformCaptureFingerprint('16:' + 'eeddcc'.repeat(256))).toBe(true);
+  });
+
+  it('accepts a frame that varies anywhere, including in only one cell', () => {
+    expect(isUniformCaptureFingerprint('16:' + 'eeddcc'.repeat(255) + '112233')).toBe(false);
+    expect(isUniformCaptureFingerprint('16:112233' + 'eeddcc'.repeat(255))).toBe(false);
+  });
+
+  it('treats a single-cell or empty payload as uniform, since it can distinguish nothing', () => {
+    expect(isUniformCaptureFingerprint('1:aabbcc')).toBe(true);
+    expect(isUniformCaptureFingerprint('16:')).toBe(true);
+  });
+});

package/src/captureBenchmark.e2e.test.ts

@@ -4,7 +4,7 @@ import { createServer } from 'node:http';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 
 import { getCaptureBenchmarkBaselinePath, runCaptureBenchmark } from './captureBenchmark';
 import { runCaptureValidation } from './captureValidation';
@@ -72,6 +72,34 @@ describe('benchmark and generalized parity browser workflow', () => {
     expect(gated.targets[1]?.baselineMetric).toBe('referenceRatio');
   }, 20_000);
 
+  it('fails a gating run with no committed benchmark baselines', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      const result = await runCaptureBenchmark({
+        subject: 'unconfigured',
+        entries: [{ name: 'work', renderers: ['dom'], routes: { dom: 'dom' } }],
+        server: { url: baseUrl, kill() {} },
+        root,
+        iterations: 1,
+        samples: 3,
+        sampleDurationMs: 1,
+        warmupIterations: 0,
+        reportPath: false,
+      });
+
+      expect(result).toMatchObject({
+        failed: 0,
+        passed: 0,
+        skipped: 1,
+        shouldFail: true,
+        targets: [{ status: 'skipped', error: 'no benchmark baseline' }],
+      });
+      expect(log).toHaveBeenCalledWith(expect.stringContaining('benchmark gate unconfigured'));
+    } finally {
+      log.mockRestore();
+    }
+  }, 20_000);
+
   it('compares DOM and arbitrary WASM-labelled targets through an explicit visual group', async () => {
     const result = await runCaptureValidation({
       subject: 'fixture',

package/src/captureDomReadback.test.ts

@@ -0,0 +1,35 @@
+import { Buffer } from 'node:buffer';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { provideCaptureDomRenderPixels } from './captureDomReadback';
+
+describe('provideCaptureDomRenderPixels', () => {
+  it('screenshots the registered DOM target and supplies its encoded image to the page bridge', async () => {
+    const dispose = vi.fn();
+    const screenshot = vi.fn().mockResolvedValue(Buffer.from('pixels'));
+    const evaluate = vi.fn().mockResolvedValue(true);
+    const page = {
+      evaluate,
+      evaluateHandle: vi.fn().mockResolvedValue({
+        asElement: () => ({ screenshot }),
+        dispose,
+      }),
+    };
+
+    await expect(provideCaptureDomRenderPixels(page as never)).resolves.toBe(true);
+    expect(screenshot).toHaveBeenCalledWith({ animations: 'disabled' });
+    expect(evaluate.mock.calls[0]?.[1]).toBe(`data:image/png;base64,${Buffer.from('pixels').toString('base64')}`);
+    expect(dispose).toHaveBeenCalledOnce();
+  });
+
+  it('reports that no readback was supplied when the page has no DOM target', async () => {
+    const dispose = vi.fn();
+    const page = {
+      evaluateHandle: vi.fn().mockResolvedValue({ asElement: () => null, dispose }),
+    };
+
+    await expect(provideCaptureDomRenderPixels(page as never)).resolves.toBe(false);
+    expect(dispose).toHaveBeenCalledOnce();
+  });
+});

package/src/captureEntry.e2e.test.ts

@@ -0,0 +1,108 @@
+// The entry-side half of the oracle-invocation record. functionalVerify owns SETTING it (two-armed
+// there: invoked vs absent); this file owns CARRYING it into status.json, and specifically on the
+// path where the oracle threw. That path is the whole point of the field — an oracle that ran and
+// rejected the frame is the case an agent most needs to distinguish from one that never ran — and it
+// is the path that discarded the record, so the failing arm below fails against the previous shape.
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { launchBrowser } from './captureBrowser';
+import { captureEntry } from './captureEntry';
+import { CAPTURE_PROTOCOL_VERSION } from './captureProtocol';
+
+// Both pages publish a terminal FAILED verification, exactly as runRenderVerification leaves the page
+// when it throws. They differ only in how far the verifier got: past the assert step with the scene's
+// oracle called, or short of it. Publishing the record directly (rather than bundling the real
+// verifier) keeps this test about the entry's carry-through; functionalVerify.test.ts covers the
+// branch that produces the value.
+const verificationPage = (stage: string, oracle: string | null, error: string): string =>
+  `<!doctype html><canvas width="320" height="180"></canvas><script>
+    const ctx = document.querySelector('canvas').getContext('2d');
+    ctx.fillStyle = '#123'; ctx.fillRect(0, 0, 320, 180);
+    window.__ftVerification = {
+      protocolVersion: ${CAPTURE_PROTOCOL_VERSION},
+      render: 'canvas',
+      coverage: 0.5,
+      fingerprint: null,
+      state: 'failed',
+      stage: ${JSON.stringify(stage)},
+      error: ${JSON.stringify(error)},
+      ${oracle === null ? '' : `oracle: ${JSON.stringify(oracle)},`}
+    };
+  </script>`;
+
+const ORACLE_ERROR = '[scene/canvas] no wide continuous ink run found — the stroke does not appear to be drawn';
+const READBACK_ERROR = '[verify:canvas] blank render: no readable render bitmap';
+
+const pages: Record<string, string> = {
+  '/oracle-rejected': verificationPage('asserting', 'invoked', ORACLE_ERROR),
+  '/failed-before-asserting': verificationPage('readingBack', null, READBACK_ERROR),
+};
+
+interface CaptureEntryStatus {
+  error: string | null;
+  oracle: 'absent' | 'invoked' | null;
+  state: string;
+}
+
+describe('captureEntry browser contract', () => {
+  const artifactRoot = mkdtempSync(join(tmpdir(), 'tool-capture-entry-'));
+  const server = createServer((request, response) => {
+    response.setHeader('content-type', 'text/html');
+    response.end(pages[(request.url ?? '').split('?')[0]] ?? 'not found');
+  });
+  let baseUrl = '';
+
+  const captureStatus = async (name: string): Promise<CaptureEntryStatus> => {
+    const session = await launchBrowser({ verify: true });
+    try {
+      await captureEntry({
+        baseUrl,
+        context: session.context,
+        entry: { name, renderers: ['canvas'], route: () => name },
+        outBase: artifactRoot,
+        renderers: ['canvas'],
+        root: artifactRoot,
+        tool: 'functional',
+        verify: true,
+      });
+    } finally {
+      await session.browser.close();
+    }
+    const path = join(artifactRoot, 'functional', name, 'canvas', 'status.json');
+    return JSON.parse(readFileSync(path, 'utf8')) as CaptureEntryStatus;
+  };
+
+  beforeAll(async () => {
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (address === null || typeof address === 'string') throw new Error('fixture server did not bind');
+    baseUrl = `http://127.0.0.1:${address.port}`;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+    rmSync(artifactRoot, { recursive: true, force: true });
+  });
+
+  it('records the oracle as invoked when the oracle itself rejected the frame', async () => {
+    const status = await captureStatus('oracle-rejected');
+    expect(status.state).toBe('error');
+    expect(status.error).toContain('no wide continuous ink run');
+    // The defect this pins: the error status used to hardcode null here, so a target whose oracle ran
+    // and threw was indistinguishable in the artifact from one that never called an oracle at all —
+    // and the artifact then said "never invoked" while carrying an error only the oracle can produce.
+    expect(status.oracle).toBe('invoked');
+  }, 30_000);
+
+  it('leaves the oracle unrecorded when the run failed before reaching the assert step', async () => {
+    const status = await captureStatus('failed-before-asserting');
+    expect(status.state).toBe('error');
+    expect(status.error).toContain('blank render');
+    expect(status.oracle).toBeNull();
+  }, 30_000);
+});

package/src/captureEntryFilter.test.ts

@@ -0,0 +1,45 @@
+import { selectCaptureEntriesByName } from './captureEntryFilter';
+
+const entries = [
+  { name: 'material-depth' },
+  { name: 'material-depth-orthographic' },
+  { name: 'material-vertex-color' },
+  { name: 'material-vertex-color-interpolated' },
+];
+
+describe('selectCaptureEntriesByName', () => {
+  it('returns every entry when neither selector is given', () => {
+    expect(selectCaptureEntriesByName(entries, undefined, undefined)).toHaveLength(4);
+  });
+
+  // The defect this exists to fix: a name contained in a longer name cannot be selected alone by
+  // substring, so a WRITING run under `--filter` rewrites ground truth for an entry nobody named.
+  it('substring selection silently takes the longer neighbours too', () => {
+    expect(selectCaptureEntriesByName(entries, 'material-depth', undefined).map((e) => e.name)).toEqual([
+      'material-depth',
+      'material-depth-orthographic',
+    ]);
+  });
+
+  it('exact selection takes ONLY the name given', () => {
+    expect(selectCaptureEntriesByName(entries, undefined, 'material-depth').map((e) => e.name)).toEqual([
+      'material-depth',
+    ]);
+  });
+
+  it('exact selection of a name that is a prefix of another still takes only that one', () => {
+    expect(selectCaptureEntriesByName(entries, undefined, 'material-vertex-color').map((e) => e.name)).toEqual([
+      'material-vertex-color',
+    ]);
+  });
+
+  it('selects nothing for an exact name no entry carries, rather than falling back to substring', () => {
+    expect(selectCaptureEntriesByName(entries, undefined, 'material-dep')).toEqual([]);
+  });
+
+  // Two different selections cannot both be meant; silently preferring one would be the same class of
+  // quiet widening this module exists to remove.
+  it('refuses both selectors at once', () => {
+    expect(() => selectCaptureEntriesByName(entries, 'material', 'material-depth')).toThrow(/not both/);
+  });
+});

package/src/captureEyes.e2e.test.ts

@@ -28,6 +28,9 @@ const pages: Record<string, string> = {
   '/flaky': `<!doctype html><canvas width="320" height="180"></canvas><script>
     const ctx=document.querySelector('canvas').getContext('2d'); ctx.fillStyle='#123'; ctx.fillRect(0,0,320,180); ctx.fillStyle='#0cf'; ctx.fillRect(40,30,240,120);
   </script>`,
+  '/failed-resources': `<!doctype html><script src="/missing-resource.js"></script><script src="/server-error-resource.js"></script><script src="/transport-failure-resource.js"></script><canvas width="320" height="180"></canvas><script>
+    const ctx=document.querySelector('canvas').getContext('2d'); ctx.fillStyle='#123'; ctx.fillRect(0,0,320,180); ctx.fillStyle='#0cf'; ctx.fillRect(40,30,240,120);
+  </script>`,
   '/loop': `<!doctype html><canvas width="320" height="180"></canvas><script>
     const canvas=document.querySelector('canvas'); const ctx=canvas.getContext('2d'); let frame=0;
     function draw() { frame++; ctx.fillStyle='#123'; ctx.fillRect(0,0,320,180); ctx.fillStyle='#0cf'; ctx.fillRect(frame,30,240,120); requestAnimationFrame(draw); }
@@ -42,6 +45,20 @@ describe('capture eyes browser contract', () => {
   const artifactRoot = mkdtempSync(join(tmpdir(), 'tool-capture-eyes-'));
   let flakyRequests = 0;
   const server = createServer((request, response) => {
+    if (request.url === '/missing-resource.js') {
+      response.statusCode = 404;
+      response.end('missing');
+      return;
+    }
+    if (request.url === '/server-error-resource.js') {
+      response.statusCode = 503;
+      response.end('unavailable');
+      return;
+    }
+    if (request.url === '/transport-failure-resource.js') {
+      request.socket.destroy();
+      return;
+    }
     if (request.url === '/flaky' && flakyRequests++ === 0) {
       request.socket.destroy();
       return;
@@ -123,4 +140,30 @@ describe('capture eyes browser contract', () => {
       await session.browser.close();
     }
   }, 20_000);
+
+  it('names every failed resource URL across HTTP and transport failures', async () => {
+    const outDir = join(artifactRoot, 'failed-resources');
+    const diagnostics = await captureUrl(`${baseUrl}/failed-resources`, { outDir, maxRetries: 0 });
+    expect(diagnostics).toMatchObject({ blank: false, usable: true });
+
+    const logs = readFileSync(join(outDir, 'logs.jsonl'), 'utf8')
+      .split('\n')
+      .filter((line) => line !== '')
+      .map((line) => JSON.parse(line) as { channel?: string; data?: { msg?: string } });
+    const networkMessages = logs.filter((entry) => entry.channel === 'network').map((entry) => entry.data?.msg ?? '');
+    expect(networkMessages).toHaveLength(3);
+    expect(networkMessages).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(new RegExp(`${baseUrl}/missing-resource\\.js \\(HTTP 404`)),
+        expect.stringMatching(new RegExp(`${baseUrl}/server-error-resource\\.js \\(HTTP 503`)),
+        expect.stringMatching(new RegExp(`${baseUrl}/transport-failure-resource\\.js \\(net::ERR_`)),
+      ]),
+    );
+
+    const browserResourceMessages = logs
+      .map((entry) => entry.data?.msg ?? '')
+      .filter((message) => message.startsWith('Failed to load resource:'));
+    expect(browserResourceMessages.length).toBeGreaterThan(0);
+    expect(browserResourceMessages.every((message) => message.includes(`${baseUrl}/`))).toBe(true);
+  }, 15_000);
 });

package/src/captureFlightPreset.test.ts

@@ -26,4 +26,14 @@ describe('getFlightCaptureValidationPreset', () => {
     expect(getFlightCaptureValidationPreset('examples').fingerprintSkip).toEqual(['playingsound']);
     expect(getFlightCaptureValidationPreset('custom').fingerprintSkip).toEqual([]);
   });
+
+  it('keeps only the parity exceptions backed by current renderer behavior', () => {
+    expect(getFlightCaptureValidationPreset('functional').paritySkip).toEqual({
+      'effect-lens-distortion': ['canvas'],
+      'effect-lens-flare': ['canvas'],
+      'effect-posterize': ['canvas'],
+      'effect-vignette': ['canvas'],
+      'effect-god-rays': 'all',
+    });
+  });
 });

package/src/capturePage.test.ts

@@ -19,12 +19,26 @@ function resetCapturePageWindow(): void {
     __ftTarget?: unknown;
     __ftVerification?: unknown;
     __ftBenchmarkTarget?: unknown;
+    __ftProvideDomRenderPixels?: (readback: { data: Uint8ClampedArray; height: number; width: number } | null) => void;
   };
   flags.__flightCapture = undefined;
   flags.__flightCaptureVerify = undefined;
   flags.__ftTarget = undefined;
   flags.__ftVerification = undefined;
   flags.__ftBenchmarkTarget = undefined;
+  flags.__ftProvideDomRenderPixels = undefined;
+}
+
+async function provideDomRenderPixels(): Promise<void> {
+  const flags = window as unknown as {
+    __ftProvideDomRenderPixels?: (readback: { data: Uint8ClampedArray; height: number; width: number } | null) => void;
+  };
+  await vi.waitFor(() => expect(flags.__ftProvideDomRenderPixels).toBeTypeOf('function'));
+  flags.__ftProvideDomRenderPixels?.({
+    data: new Uint8ClampedArray([0, 0, 0, 255, 255, 255, 255, 255]),
+    height: 1,
+    width: 2,
+  });
 }
 
 beforeEach(resetCapturePageWindow);
@@ -49,7 +63,9 @@ describe('installCaptureElementTarget', () => {
   it('adapts a renderer-owned DOM element without requiring a Flight render state', async () => {
     const element = document.createElement('div');
     element.textContent = 'reference renderer';
-    await expect(installCaptureElementTarget({ renderer: 'dom', element, verify: true })).resolves.toMatchObject({
+    const verification = installCaptureElementTarget({ renderer: 'dom', element, verify: true });
+    await provideDomRenderPixels();
+    await expect(verification).resolves.toMatchObject({
       render: 'dom',
       state: 'passed',
     });
@@ -67,7 +83,7 @@ describe('installCaptureTarget', () => {
     const render = vi.fn(() => {
       element.textContent = 'ready';
     });
-    const result = await installCaptureTarget({
+    const verification = installCaptureTarget({
       renderer: 'dom',
       state: { element } as unknown as DomRenderState,
       width: 800,
@@ -75,6 +91,8 @@ describe('installCaptureTarget', () => {
       render,
       verify: true,
     });
+    await provideDomRenderPixels();
+    const result = await verification;
 
     expect(render).toHaveBeenCalledOnce();
     expect(result).toMatchObject({
@@ -116,6 +134,8 @@ describe('verifyCaptureTarget', () => {
       width: 1,
       height: 1,
     });
-    await expect(verifyCaptureTarget({}, 'dom')).resolves.toMatchObject({ state: 'passed' });
+    const verification = verifyCaptureTarget({}, 'dom');
+    await provideDomRenderPixels();
+    await expect(verification).resolves.toMatchObject({ state: 'passed' });
   });
 });

package/src/captureResourceFailure.test.ts

@@ -0,0 +1,60 @@
+import type { ConsoleMessage, Page, Request, Response } from '@playwright/test';
+import { describe, expect, it, vi } from 'vitest';
+
+import { formatCaptureConsoleMessage, listenForCaptureResourceFailures } from './captureResourceFailure';
+
+describe('formatCaptureConsoleMessage', () => {
+  it('adds the source URL when Chromium omits it from a resource error', () => {
+    const message = {
+      location: () => ({ url: 'https://flight.test/missing.png' }),
+      text: () => 'Failed to load resource: the server responded with a status of 404',
+    } as ConsoleMessage;
+
+    expect(formatCaptureConsoleMessage(message)).toBe(
+      'Failed to load resource: the server responded with a status of 404 (https://flight.test/missing.png)',
+    );
+  });
+
+  it('does not repeat a URL already present in the message', () => {
+    const message = {
+      location: () => ({ url: 'https://flight.test/missing.png' }),
+      text: () => 'resource failed: https://flight.test/missing.png',
+    } as ConsoleMessage;
+
+    expect(formatCaptureConsoleMessage(message)).toBe('resource failed: https://flight.test/missing.png');
+  });
+});
+
+describe('listenForCaptureResourceFailures', () => {
+  it('names HTTP and transport failures without duplicating one failed response', () => {
+    const listeners = new Map<string, (event: unknown) => void>();
+    const page = {
+      on: vi.fn((event: string, listener: (event: unknown) => void) => {
+        listeners.set(event, listener);
+        return page;
+      }),
+    } as unknown as Page;
+    const failures: string[] = [];
+    listenForCaptureResourceFailures(page, (message) => failures.push(message));
+
+    const missingRequest = {} as Request;
+    listeners.get('response')?.({
+      request: () => missingRequest,
+      status: () => 404,
+      statusText: () => 'Not Found',
+      url: () => 'https://flight.test/missing.png',
+    } as Response);
+    listeners.get('requestfailed')?.(missingRequest);
+
+    const transportRequest = {
+      failure: () => ({ errorText: 'net::ERR_CONNECTION_RESET' }),
+      url: () => 'https://flight.test/dropped.png',
+    } as Request;
+    listeners.get('requestfailed')?.(transportRequest);
+
+    expect(failures).toEqual([
+      'resource load failed: https://flight.test/missing.png (HTTP 404 Not Found)',
+      'resource load failed: https://flight.test/dropped.png (net::ERR_CONNECTION_RESET)',
+    ]);
+  });
+});

package/src/captureScreenshotHash.test.ts

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+
+import type { CaptureScreenshotHashPage } from './captureScreenshotHash';
+import { hashCaptureScreenshotPixels, hashCaptureScreenshotPixelsOrNull } from './captureScreenshotHash';
+
+// WHAT THESE TESTS COVER, AND WHAT THEY DO NOT.
+//
+// The decode itself runs in a real browser and is exercised by the functional capture suite, not here —
+// there is no PNG decoder in Node, which is the whole reason the decode was put in the page. So these
+// pin the CONTRACT around the decode: the screenshot reaches the page, the page's digest is what comes
+// back, and a page that cannot decode fails loudly instead of degrading to something that looks like a
+// hash. A test double supplies the digest, so none of this asserts that a PNG decodes correctly.
+//
+// ★ THE SAME LIMIT APPLIES TO THE BLANK GUARD, and it is measured rather than assumed: deleting the
+// in-page blank CHECK leaves every test here passing, because the double returns the 'blank' sentinel
+// directly. What is covered is the Node-side handling — that a blank result throws instead of being
+// hashed, and that the caller's threshold is what reaches the page. The coverage computation itself is
+// only exercised by a real capture against a real browser.
+
+describe('hashCaptureScreenshotPixels', () => {
+  it('sends the screenshot to the page as base64 and returns the digest the page computed', () => {
+    const digest = 'a'.repeat(64);
+    let received: string | null = null;
+    const page: CaptureScreenshotHashPage = {
+      evaluate: async (_fn, argument) => {
+        received = (argument as { base64: string }).base64;
+        return digest as never;
+      },
+    };
+
+    return hashCaptureScreenshotPixels(page, new Uint8Array([137, 80, 78, 71]), 0.001).then((hash) => {
+      expect(received).toBe(Buffer.from([137, 80, 78, 71]).toString('base64'));
+      expect(hash).toBe(digest);
+    });
+  });
+
+  it('forwards a null blank threshold, so a verified scene keeps its own definition of blank', () => {
+    // The scene's verifier has already applied that scene's declared minCoverage. Null is how the caller
+    // says "already ruled on"; if it were coerced to a number here, a deliberately-uniform frame would be
+    // refused by a threshold the scene explicitly opted out of. Asserted at this seam because the blank
+    // comparison itself runs in the page, which these doubles do not execute.
+    const thresholds: Array<number | null> = [];
+    const page: CaptureScreenshotHashPage = {
+      evaluate: async (_fn, argument) => {
+        thresholds.push((argument as { blankCoverage: number | null }).blankCoverage);
+        return 'c'.repeat(64) as never;
+      },
+    };
+    const screenshot = new Uint8Array([137, 80, 78, 71]);
+
+    return hashCaptureScreenshotPixels(page, screenshot, null)
+      .then(() => hashCaptureScreenshotPixels(page, screenshot, 0.001))
+      .then(() => {
+        expect(thresholds).toEqual([null, 0.001]);
+      });
+  });
+
+  it('does NOT hash the encoded bytes — the defect this replaces', () => {
+    // The regression lock. If someone reverts this to sha256 over the PNG buffer, the returned hash
+    // becomes the encoded-bytes digest and this fails. Stated as a value rather than a shape so the
+    // comparison is against the exact thing that used to be written into baselines.
+    const screenshot = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+    const encodedBytesDigest = createHash('sha256').update(screenshot).digest('hex');
+    const pageDigest = 'b'.repeat(64);
+    const page: CaptureScreenshotHashPage = { evaluate: async () => pageDigest as never };
+
+    return hashCaptureScreenshotPixels(page, screenshot, 0.001).then((hash) => {
+      expect(hash).toBe(pageDigest);
+      expect(hash).not.toBe(encodedBytesDigest);
+    });
+  });
+
+  it('THROWS when the page cannot produce a digest, rather than degrading to a different quantity', () => {
+    // A fallback to the encoded-bytes hash would write a value into the column that means something
+    // different from every other value in it, and nothing downstream could tell them apart. A failed
+    // capture is recoverable; a silently different quantity is not.
+    const page: CaptureScreenshotHashPage = { evaluate: async () => null as never };
+
+    return expect(hashCaptureScreenshotPixels(page, new Uint8Array([1]), 0.001)).rejects.toThrow(
+      /rather than a sha256 hex digest/,
+    );
+  });
+
+  it('rejects a page result that is string-shaped but not a digest', () => {
+    // `page.evaluate` returning an error string, or a truncated result, must not be written as a hash.
+    const page: CaptureScreenshotHashPage = { evaluate: async () => 'not-a-digest' as never };
+
+    return expect(hashCaptureScreenshotPixels(page, new Uint8Array([1]), 0.001)).rejects.toThrow(/not-a-digest/);
+  });
+});
+
+describe('hashCaptureScreenshotPixels blank guard', () => {
+  it('THROWS when the page reports the decoded frame is blank, rather than hashing nothing', () => {
+    // The failure shape a digest-shape check cannot see: a decode that succeeds with correct dimensions
+    // and byte count and contains no render. A re-read of a WebGPU swapchain does exactly this, and the
+    // resulting hash is stable, identical across scenes, and meaningless. Content has to be checked,
+    // because the shape is already right.
+    const page: CaptureScreenshotHashPage = { evaluate: async () => 'blank' as never };
+
+    return expect(hashCaptureScreenshotPixels(page, new Uint8Array([1]), 0.001)).rejects.toThrow(
+      /decoded screenshot is blank/,
+    );
+  });
+
+  it('passes the caller-supplied blank threshold into the page rather than holding its own', () => {
+    // One definition of "blank" for the whole capture path: the caller hands over the same
+    // OBSERVE_BLANK_COVERAGE the rest of captureEntry compares against. Two thresholds in adjacent code
+    // is how the next reader concludes they must mean different things.
+    let received: number | null = null;
+    const page: CaptureScreenshotHashPage = {
+      evaluate: async (_fn, argument) => {
+        received = (argument as { blankCoverage: number }).blankCoverage;
+        return 'd'.repeat(64) as never;
+      },
+    };
+
+    return hashCaptureScreenshotPixels(page, new Uint8Array([1]), 0.001).then(() => {
+      expect(received).toBe(0.001);
+    });
+  });
+});
+
+describe('hashCaptureScreenshotPixelsOrNull', () => {
+  it('returns null instead of throwing, so a failed capture still records its error', () => {
+    // The error path may be reached BECAUSE the page crashed. Throwing there would lose the error
+    // report on its way out — an unrecorded failure in place of a recorded one.
+    const page: CaptureScreenshotHashPage = {
+      evaluate: async () => {
+        throw new Error('Target page, context or browser has been closed');
+      },
+    };
+
+    return expect(hashCaptureScreenshotPixelsOrNull(page, new Uint8Array([1]), 0.001)).resolves.toBeNull();
+  });
+
+  it('returns the digest when the page CAN produce one, so the error path is not degraded by default', () => {
+    const digest = 'c'.repeat(64);
+    const page: CaptureScreenshotHashPage = { evaluate: async () => digest as never };
+
+    return expect(hashCaptureScreenshotPixelsOrNull(page, new Uint8Array([1]), 0.001)).resolves.toBe(digest);
+  });
+});