@hyperframes/engine 0.6.4 → 0.6.6

package/dist/utils/assertSwiftShader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * assertSwiftShader — verify Chrome's WebGL is rendered by SwiftShader.
+ *
+ * Distributed renders pixel-lock on the GPU backend: hardware GL is bitwise
+ * unstable across worker machines (different drivers, driver versions, GL
+ * extension sets, even differing fp32 rounding on the same vendor). Chunk
+ * workers launch Chrome with `--use-gl=swiftshader --use-angle=swiftshader`
+ * so every worker uses the same pure-software GL implementation.
+ *
+ * Those Chrome flags are advisory: a misconfigured base image, a missing
+ * SwiftShader library, or a `chrome://gpu` blocklist override can silently
+ * downgrade to system GL. The distributed pipeline cannot detect the
+ * downgrade by sampling pixels (one machine = one render), so we read
+ * `chrome://gpu` directly after launch and refuse to render if the active
+ * GL renderer is anything other than SwiftShader.
+ */
+import type { Page } from "puppeteer-core";
+/**
+ * Error code classifying this failure as non-retryable for distributed
+ * workflow adapters — a downgraded GPU on a worker will not heal on retry.
+ */
+export declare const BROWSER_GPU_NOT_SOFTWARE = "BROWSER_GPU_NOT_SOFTWARE";
+/**
+ * Error thrown when chrome://gpu reports a non-SwiftShader WebGL backend.
+ *
+ * Carries a `code` property so the adapter can match on it without parsing
+ * the message string — Temporal/Step Functions retry policies key off the
+ * code, not the message.
+ */
+export declare class SwiftShaderAssertionError extends Error {
+    readonly code: typeof BROWSER_GPU_NOT_SOFTWARE;
+    readonly vendor: string;
+    readonly renderer: string;
+    constructor(message: string, vendor: string, renderer: string);
+}
+interface WebGlInfo {
+    vendor: string;
+    renderer: string;
+}
+/**
+ * Read the WebGL vendor/renderer strings from a live `chrome://gpu` page.
+ *
+ * Extracted from `assertSwiftShader` so tests can stub the navigation +
+ * extraction step. Returns the raw values; callers decide how to interpret
+ * them. Both fields are best-effort — Chrome returns empty strings if the
+ * GPU info table hasn't populated yet, which the caller treats as failure.
+ */
+export declare function readWebGlVendorInfo(page: Page): Promise<WebGlInfo>;
+/**
+ * Validate that the active WebGL renderer is SwiftShader. Throws
+ * `SwiftShaderAssertionError` otherwise.
+ *
+ * Pass an optional `readInfo` override for tests that don't have a real
+ * Puppeteer `Page`. The default implementation navigates to `chrome://gpu`
+ * and parses the GL_VENDOR / GL_RENDERER rows.
+ */
+export declare function assertSwiftShader(page: Page, readInfo?: (page: Page) => Promise<WebGlInfo>): Promise<void>;
+export {};
+//# sourceMappingURL=assertSwiftShader.d.ts.map

package/dist/utils/assertSwiftShader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertSwiftShader.d.ts","sourceRoot":"","sources":["../../src/utils/assertSwiftShader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAA4B;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAM9D;AAiBD,UAAU,SAAS;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAqBxE;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,QAAQ,GAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,SAAS,CAAuB,GACjE,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/utils/assertSwiftShader.js

@@ -0,0 +1,106 @@
+/**
+ * assertSwiftShader — verify Chrome's WebGL is rendered by SwiftShader.
+ *
+ * Distributed renders pixel-lock on the GPU backend: hardware GL is bitwise
+ * unstable across worker machines (different drivers, driver versions, GL
+ * extension sets, even differing fp32 rounding on the same vendor). Chunk
+ * workers launch Chrome with `--use-gl=swiftshader --use-angle=swiftshader`
+ * so every worker uses the same pure-software GL implementation.
+ *
+ * Those Chrome flags are advisory: a misconfigured base image, a missing
+ * SwiftShader library, or a `chrome://gpu` blocklist override can silently
+ * downgrade to system GL. The distributed pipeline cannot detect the
+ * downgrade by sampling pixels (one machine = one render), so we read
+ * `chrome://gpu` directly after launch and refuse to render if the active
+ * GL renderer is anything other than SwiftShader.
+ */
+/**
+ * Error code classifying this failure as non-retryable for distributed
+ * workflow adapters — a downgraded GPU on a worker will not heal on retry.
+ */
+export const BROWSER_GPU_NOT_SOFTWARE = "BROWSER_GPU_NOT_SOFTWARE";
+/**
+ * Error thrown when chrome://gpu reports a non-SwiftShader WebGL backend.
+ *
+ * Carries a `code` property so the adapter can match on it without parsing
+ * the message string — Temporal/Step Functions retry policies key off the
+ * code, not the message.
+ */
+export class SwiftShaderAssertionError extends Error {
+    code = BROWSER_GPU_NOT_SOFTWARE;
+    vendor;
+    renderer;
+    constructor(message, vendor, renderer) {
+        super(message);
+        this.name = "SwiftShaderAssertionError";
+        this.vendor = vendor;
+        this.renderer = renderer;
+    }
+}
+/**
+ * SwiftShader identifies itself on `chrome://gpu` and in
+ * `WEBGL_debug_renderer_info` with this exact vendor string. Locking to
+ * Google's own GL string (rather than a substring match on "swiftshader")
+ * avoids false-positives from third-party ANGLE backends that incidentally
+ * mention SwiftShader in unrelated diagnostic text.
+ */
+const SWIFTSHADER_VENDOR_SIGNATURE = "Google Inc. (Google)";
+/**
+ * Renderer string contains the literal "SwiftShader" token. We match
+ * case-insensitively and only require the substring; Chrome occasionally
+ * appends a build suffix (e.g. " Vulkan 1.3").
+ */
+const SWIFTSHADER_RENDERER_TOKEN = "swiftshader";
+/**
+ * Read the WebGL vendor/renderer strings from a live `chrome://gpu` page.
+ *
+ * Extracted from `assertSwiftShader` so tests can stub the navigation +
+ * extraction step. Returns the raw values; callers decide how to interpret
+ * them. Both fields are best-effort — Chrome returns empty strings if the
+ * GPU info table hasn't populated yet, which the caller treats as failure.
+ */
+export async function readWebGlVendorInfo(page) {
+    await page.goto("chrome://gpu", { waitUntil: "domcontentloaded", timeout: 30_000 });
+    // The "GL_VENDOR" / "GL_RENDERER" rows live inside <info-view> shadow DOM
+    // in modern Chrome. We pull the structured `info_log_` payload off the
+    // page-level globals instead of querying the DOM, since the DOM layout has
+    // drifted across versions.
+    const info = await page.evaluate(() => {
+        const w = window;
+        const rows = w.browserBridge?.gpuInfo_?.graphics_info?.basic_info ?? [];
+        let vendor = "";
+        let renderer = "";
+        for (const row of rows) {
+            if (typeof row.description !== "string" || typeof row.value !== "string")
+                continue;
+            if (row.description === "GL_VENDOR")
+                vendor = row.value;
+            else if (row.description === "GL_RENDERER")
+                renderer = row.value;
+        }
+        return { vendor, renderer };
+    });
+    return info;
+}
+/**
+ * Validate that the active WebGL renderer is SwiftShader. Throws
+ * `SwiftShaderAssertionError` otherwise.
+ *
+ * Pass an optional `readInfo` override for tests that don't have a real
+ * Puppeteer `Page`. The default implementation navigates to `chrome://gpu`
+ * and parses the GL_VENDOR / GL_RENDERER rows.
+ */
+export async function assertSwiftShader(page, readInfo = readWebGlVendorInfo) {
+    const { vendor, renderer } = await readInfo(page);
+    const vendorMatches = vendor.trim() === SWIFTSHADER_VENDOR_SIGNATURE;
+    const rendererMatches = renderer.toLowerCase().includes(SWIFTSHADER_RENDERER_TOKEN);
+    if (vendorMatches && rendererMatches)
+        return;
+    throw new SwiftShaderAssertionError(`[assertSwiftShader] Chrome reported a non-SwiftShader WebGL backend. ` +
+        `Distributed renders require pure-software GL for pixel-identical retries. ` +
+        `Got vendor=${JSON.stringify(vendor)} renderer=${JSON.stringify(renderer)}; ` +
+        `expected vendor=${JSON.stringify(SWIFTSHADER_VENDOR_SIGNATURE)} renderer to contain "SwiftShader". ` +
+        `Ensure Chrome was launched with --use-gl=swiftshader --use-angle=swiftshader and that the ` +
+        `SwiftShader libraries are present in the runtime image.`, vendor, renderer);
+}
+//# sourceMappingURL=assertSwiftShader.js.map

package/dist/utils/assertSwiftShader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertSwiftShader.js","sourceRoot":"","sources":["../../src/utils/assertSwiftShader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,IAAI,GAAoC,wBAAwB,CAAC;IACjE,MAAM,CAAS;IACf,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,MAAc,EAAE,QAAgB;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,4BAA4B,GAAG,sBAAsB,CAAC;AAC5D;;;;GAIG;AACH,MAAM,0BAA0B,GAAG,aAAa,CAAC;AAOjD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAU;IAClD,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACpF,0EAA0E;IAC1E,uEAAuE;IACvE,2EAA2E;IAC3E,2BAA2B;IAC3B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAc,EAAE;QAG/C,MAAM,CAAC,GAAG,MAA+D,CAAC;QAC1E,MAAM,IAAI,GAAU,CAAC,CAAC,aAAa,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,IAAI,EAAE,CAAC;QAC/E,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,QAAQ,GAAG,EAAE,CAAC;QAClB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;gBAAE,SAAS;YACnF,IAAI,GAAG,CAAC,WAAW,KAAK,WAAW;gBAAE,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC;iBACnD,IAAI,GAAG,CAAC,WAAW,KAAK,aAAa;gBAAE,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC;QACnE,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC9B,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAU,EACV,WAA+C,mBAAmB;IAElE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAElD,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,4BAA4B,CAAC;IACrE,MAAM,eAAe,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC,CAAC;IAEpF,IAAI,aAAa,IAAI,eAAe;QAAE,OAAO;IAE7C,MAAM,IAAI,yBAAyB,CACjC,uEAAuE;QACrE,4EAA4E;QAC5E,cAAc,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,aAAa,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI;QAC7E,mBAAmB,IAAI,CAAC,SAAS,CAAC,4BAA4B,CAAC,sCAAsC;QACrG,4FAA4F;QAC5F,yDAAyD,EAC3D,MAAM,EACN,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -11,7 +11,9 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./alpha-blit": "./src/utils/alphaBlit.ts",
+    "./shader-transitions": "./src/utils/shaderTransitions.ts"
   },
   "dependencies": {
     "@hono/node-server": "^1.13.0",
@@ -19,7 +21,7 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^24.0.0",
     "puppeteer-core": "^24.39.1",
-    "@hyperframes/core": "^0.6.4"
+    "@hyperframes/core": "^0.6.6"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

package/src/index.ts

@@ -65,11 +65,13 @@ export {
   closeCaptureSession,
   captureFrame,
   captureFrameToBuffer,
+  discardWarmupCapture,
   getCompositionDuration,
   getCapturePerfSummary,
   prepareCaptureSessionForReuse,
   type CaptureSession,
   type BeforeCaptureHook,
+  type DiscardWarmupInnerCapture,
 } from "./services/frameCapture.js";
 
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
@@ -155,6 +157,13 @@ export {
 // ── Utilities ──────────────────────────────────────────────────────────────────
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 
+export {
+  assertSwiftShader,
+  readWebGlVendorInfo,
+  SwiftShaderAssertionError,
+  BROWSER_GPU_NOT_SOFTWARE,
+} from "./utils/assertSwiftShader.js";
+
 export {
   extractMediaMetadata,
   extractVideoMetadata,
@@ -166,7 +175,12 @@ export {
 } from "./utils/ffprobe.js";
 
 export { downloadToTemp, isHttpUrl } from "./utils/urlDownloader.js";
-export { runFfmpeg, type RunFfmpegOptions, type RunFfmpegResult } from "./utils/runFfmpeg.js";
+export {
+  runFfmpeg,
+  formatFfmpegError,
+  type RunFfmpegOptions,
+  type RunFfmpegResult,
+} from "./utils/runFfmpeg.js";
 
 export {
   decodePng,

package/src/services/frameCapture-discardWarmup.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Tests for `discardWarmupCapture` — the helper distributed chunk workers
+ * run before their first real capture to prime `lastFrameCache`.
+ *
+ * The helper is a thin wrapper around the inner `captureFrameCore`
+ * machinery, so its testable contract is post-conditional rather than
+ * pixel-level:
+ *
+ *   1. The wrapper invokes the inner capture exactly once with the supplied
+ *      `(frameIndex, time)`.
+ *   2. After the wrapper returns, the session's perf and BeginFrame damage
+ *      counters look exactly as they did before — even though the inner
+ *      capture mutated them.
+ *   3. The wrapper writes no file to disk (no path is plumbed through;
+ *      asserted indirectly by observing that `outputDir` is never read).
+ *   4. State is restored even if the inner capture throws.
+ *
+ * The inner capture is stubbed (the helper accepts an injectable
+ * `innerCapture` for exactly this reason). We don't need a real Chrome.
+ */
+
+import { describe, expect, it } from "vitest";
+import { existsSync, readdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { discardWarmupCapture, type CaptureSession } from "./frameCapture.js";
+
+function makeFakeSession(): CaptureSession {
+  // The discardWarmupCapture wrapper only reads `capturePerf`,
+  // `beginFrameHasDamageCount`, `beginFrameNoDamageCount`. Everything else
+  // is unused — leave it as bare-minimum stubs cast through `unknown`.
+  return {
+    browser: {} as unknown,
+    page: {} as unknown,
+    options: { width: 1, height: 1, fps: { num: 30, den: 1 } },
+    serverUrl: "",
+    outputDir: mkdtempSync(join(tmpdir(), "discard-warmup-")),
+    onBeforeCapture: null,
+    isInitialized: true,
+    browserConsoleBuffer: [],
+    capturePerf: {
+      frames: 7,
+      seekMs: 100,
+      beforeCaptureMs: 50,
+      screenshotMs: 200,
+      totalMs: 350,
+    },
+    captureMode: "beginframe",
+    beginFrameTimeTicks: 0,
+    beginFrameIntervalMs: 33,
+    beginFrameHasDamageCount: 4,
+    beginFrameNoDamageCount: 3,
+  } as unknown as CaptureSession;
+}
+
+describe("discardWarmupCapture", () => {
+  it("calls the inner capture exactly once with (frameIndex=0, time=0) by default", async () => {
+    const session = makeFakeSession();
+    try {
+      let calls = 0;
+      let receivedFrameIndex = -1;
+      let receivedTime = -1;
+      await discardWarmupCapture(session, undefined, undefined, async (_s, fi, t) => {
+        calls++;
+        receivedFrameIndex = fi;
+        receivedTime = t;
+        return { buffer: Buffer.alloc(0), quantizedTime: t, captureTimeMs: 0 };
+      });
+      expect(calls).toBe(1);
+      expect(receivedFrameIndex).toBe(0);
+      expect(receivedTime).toBe(0);
+    } finally {
+      rmSync(session.outputDir, { recursive: true, force: true });
+    }
+  });
+
+  it("passes through caller-supplied (frameIndex, time)", async () => {
+    const session = makeFakeSession();
+    try {
+      let received: { fi: number; t: number } | null = null;
+      await discardWarmupCapture(session, 240, 8, async (_s, fi, t) => {
+        received = { fi, t };
+        return { buffer: Buffer.alloc(0), quantizedTime: t, captureTimeMs: 0 };
+      });
+      expect(received).toEqual({ fi: 240, t: 8 });
+    } finally {
+      rmSync(session.outputDir, { recursive: true, force: true });
+    }
+  });
+
+  it("restores perf counters after the inner capture mutates them", async () => {
+    const session = makeFakeSession();
+    const before = { ...session.capturePerf };
+    try {
+      await discardWarmupCapture(session, 0, 0, async (s) => {
+        s.capturePerf.frames += 1;
+        s.capturePerf.seekMs += 12;
+        s.capturePerf.beforeCaptureMs += 5;
+        s.capturePerf.screenshotMs += 33;
+        s.capturePerf.totalMs += 50;
+        return { buffer: Buffer.alloc(0), quantizedTime: 0, captureTimeMs: 50 };
+      });
+      expect(session.capturePerf).toEqual(before);
+    } finally {
+      rmSync(session.outputDir, { recursive: true, force: true });
+    }
+  });
+
+  it("restores BeginFrame damage counters after the inner capture mutates them", async () => {
+    const session = makeFakeSession();
+    const hasBefore = session.beginFrameHasDamageCount;
+    const noBefore = session.beginFrameNoDamageCount;
+    try {
+      await discardWarmupCapture(session, 0, 0, async (s) => {
+        s.beginFrameHasDamageCount += 10;
+        s.beginFrameNoDamageCount += 1;
+        return { buffer: Buffer.alloc(0), quantizedTime: 0, captureTimeMs: 0 };
+      });
+      expect(session.beginFrameHasDamageCount).toBe(hasBefore);
+      expect(session.beginFrameNoDamageCount).toBe(noBefore);
+    } finally {
+      rmSync(session.outputDir, { recursive: true, force: true });
+    }
+  });
+
+  it("restores state even when the inner capture throws", async () => {
+    const session = makeFakeSession();
+    const perfBefore = { ...session.capturePerf };
+    const hasBefore = session.beginFrameHasDamageCount;
+    const noBefore = session.beginFrameNoDamageCount;
+    try {
+      let thrown: unknown;
+      try {
+        await discardWarmupCapture(session, 0, 0, async (s) => {
+          s.capturePerf.frames += 5;
+          s.beginFrameNoDamageCount += 2;
+          throw new Error("simulated capture failure");
+        });
+      } catch (err) {
+        thrown = err;
+      }
+      expect((thrown as Error).message).toBe("simulated capture failure");
+      // The whole point of `finally { restore }`: failure must not leak
+      // inflated counters into the real capture summary.
+      expect(session.capturePerf).toEqual(perfBefore);
+      expect(session.beginFrameHasDamageCount).toBe(hasBefore);
+      expect(session.beginFrameNoDamageCount).toBe(noBefore);
+    } finally {
+      rmSync(session.outputDir, { recursive: true, force: true });
+    }
+  });
+
+  it("writes no output file to the session's outputDir", async () => {
+    const session = makeFakeSession();
+    try {
+      expect(existsSync(session.outputDir)).toBe(true);
+      const before = readdirSync(session.outputDir);
+      await discardWarmupCapture(session, 0, 0, async () => ({
+        buffer: Buffer.from([0xff, 0xff, 0xff]),
+        quantizedTime: 0,
+        captureTimeMs: 0,
+      }));
+      const after = readdirSync(session.outputDir);
+      expect(after).toEqual(before);
+    } finally {
+      rmSync(session.outputDir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns undefined (no result type, so the buffer can't escape)", async () => {
+    const session = makeFakeSession();
+    try {
+      const result = await discardWarmupCapture(session, 0, 0, async () => ({
+        buffer: Buffer.from([0x01]),
+        quantizedTime: 0,
+        captureTimeMs: 1,
+      }));
+      expect(result).toBeUndefined();
+    } finally {
+      rmSync(session.outputDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/services/frameCapture-warmupTicks.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Tests for the `driveWarmupTicks` BeginFrame warmup driver.
+ *
+ * The wall-clock warmup loop in `initializeSession` accumulates a different
+ * number of ticks per host CPU speed, which shifts `beginFrameTimeTicks`
+ * and breaks byte-identical captures across distributed workers.
+ *
+ * `lockWarmupTicks=true` clamps the loop to a fixed iteration count
+ * (`LOCKED_WARMUP_TICKS = 60`) so the baseline becomes host-independent.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  LOCKED_WARMUP_TICKS,
+  driveWarmupTicks,
+  warmupFrameTimeTicks,
+  type WarmupTickState,
+} from "./frameCapture.js";
+
+function makeState(): WarmupTickState {
+  return { running: true, ticks: 0 };
+}
+
+// Run the warmup driver "concurrently" with a simulated page-load that
+// flips `state.running` to false after `pageLoadIterations` of the
+// `tick` callback. Returns the final state.
+async function runWithSimulatedPageLoad(
+  lockWarmupTicks: boolean,
+  pageLoadIterations: number,
+  tickDelay: () => Promise<void> = () => Promise.resolve(),
+): Promise<WarmupTickState> {
+  const state = makeState();
+  const intervalMs = 33;
+
+  const tick = async (): Promise<void> => {
+    if (state.ticks + 1 === pageLoadIterations) {
+      state.running = false;
+    }
+    await tickDelay();
+  };
+
+  await driveWarmupTicks(
+    {
+      intervalMs,
+      lockWarmupTicks,
+      tick,
+      sleep: () => Promise.resolve(),
+    },
+    state,
+  );
+  return state;
+}
+
+describe("driveWarmupTicks — unlocked", () => {
+  it("stops when state.running flips false", async () => {
+    const state = await runWithSimulatedPageLoad(false, 10);
+    expect(state.ticks).toBe(10);
+  });
+
+  it("yields different tick counts for different simulated page-load lengths", async () => {
+    const fast = await runWithSimulatedPageLoad(false, 5);
+    const slow = await runWithSimulatedPageLoad(false, 50);
+    expect(fast.ticks).toBe(5);
+    expect(slow.ticks).toBe(50);
+    expect(fast.ticks).not.toBe(slow.ticks);
+  });
+
+  it("frame time derived as ticks * intervalMs", async () => {
+    const state = await runWithSimulatedPageLoad(false, 7);
+    expect(warmupFrameTimeTicks(state, 33)).toBe(7 * 33);
+  });
+
+  it("does not iterate when state.running starts false", async () => {
+    const state: WarmupTickState = { running: false, ticks: 0 };
+    await driveWarmupTicks(
+      {
+        intervalMs: 33,
+        lockWarmupTicks: false,
+        tick: async () => {},
+        sleep: () => Promise.resolve(),
+      },
+      state,
+    );
+    expect(state.ticks).toBe(0);
+  });
+
+  it("counts ticks even when tick callback throws (page not ready yet)", async () => {
+    // Pre-acquisition errors are swallowed — the loop must keep spinning so
+    // it can drive the page once CDP comes up.
+    let stopAt = 5;
+    const state = makeState();
+    await driveWarmupTicks(
+      {
+        intervalMs: 33,
+        lockWarmupTicks: false,
+        tick: async () => {
+          if (--stopAt <= 0) state.running = false;
+          throw new Error("CDP not ready");
+        },
+        sleep: () => Promise.resolve(),
+      },
+      state,
+    );
+    // We don't count ticks on throw, but the loop kept running until
+    // state.running flipped — so it exited cleanly.
+    expect(state.running).toBe(false);
+    expect(state.ticks).toBe(0);
+  });
+});
+
+describe("driveWarmupTicks — locked", () => {
+  it("runs exactly LOCKED_WARMUP_TICKS iterations regardless of state.running", async () => {
+    // Simulate a fast page load: state.running flips false after just 5 ticks.
+    // The locked loop must still run to LOCKED_WARMUP_TICKS.
+    const state = await runWithSimulatedPageLoad(true, 5);
+    expect(state.ticks).toBe(LOCKED_WARMUP_TICKS);
+  });
+
+  it("runs exactly LOCKED_WARMUP_TICKS iterations on slow simulated load", async () => {
+    // state.running stays true past the locked count — loop still stops at
+    // LOCKED_WARMUP_TICKS.
+    const state = await runWithSimulatedPageLoad(true, 9999);
+    expect(state.ticks).toBe(LOCKED_WARMUP_TICKS);
+  });
+
+  it("yields IDENTICAL tick counts across simulated fast and slow loads", async () => {
+    // THE determinism property the locked mode exists for.
+    const fast = await runWithSimulatedPageLoad(true, 5);
+    const slow = await runWithSimulatedPageLoad(true, 200);
+    expect(fast.ticks).toBe(slow.ticks);
+    expect(fast.ticks).toBe(LOCKED_WARMUP_TICKS);
+    expect(warmupFrameTimeTicks(fast, 33)).toBe(warmupFrameTimeTicks(slow, 33));
+  });
+
+  it("yields LOCKED_WARMUP_TICKS even when state.running starts false", async () => {
+    // Guards the locked contract independently of the caller's running flag.
+    const state: WarmupTickState = { running: false, ticks: 0 };
+    await driveWarmupTicks(
+      {
+        intervalMs: 33,
+        lockWarmupTicks: true,
+        tick: async () => {},
+        sleep: () => Promise.resolve(),
+      },
+      state,
+    );
+    expect(state.ticks).toBe(LOCKED_WARMUP_TICKS);
+  });
+
+  it("does not exceed LOCKED_WARMUP_TICKS even if the caller never stops it", async () => {
+    const state = makeState();
+    let observedMax = 0;
+    await driveWarmupTicks(
+      {
+        intervalMs: 33,
+        lockWarmupTicks: true,
+        tick: async () => {
+          observedMax = Math.max(observedMax, state.ticks + 1);
+        },
+        sleep: () => Promise.resolve(),
+      },
+      state,
+    );
+    expect(observedMax).toBe(LOCKED_WARMUP_TICKS);
+    expect(state.ticks).toBe(LOCKED_WARMUP_TICKS);
+  });
+
+  it("baseline frame time matches (LOCKED_WARMUP_TICKS * intervalMs)", async () => {
+    // initializeSession derives session.beginFrameTimeTicks from the final
+    // tick count — locked mode pins this to a host-independent value.
+    const state = await runWithSimulatedPageLoad(true, 5);
+    expect(warmupFrameTimeTicks(state, 33)).toBe(LOCKED_WARMUP_TICKS * 33);
+  });
+});