@hyperframes/engine 0.6.4 → 0.6.5

package/src/services/frameCapture.ts

@@ -78,6 +78,81 @@ export interface CaptureSession {
 const BROWSER_CONSOLE_BUFFER_SIZE = 200;
 const CAPTURE_SESSION_CLOSE_TIMEOUT_MS = 5_000;
 
+/**
+ * Fixed warmup-loop iteration count used when `CaptureOptions.lockWarmupTicks`
+ * is `true`. Picked to roughly match the median tick count observed by the
+ * unlocked wall-clock loop during a typical 2s page load at 30fps — so
+ * `beginFrameTimeTicks` lands in a similar range regardless of host speed.
+ */
+export const LOCKED_WARMUP_TICKS = 60;
+
+/**
+ * Internal driver for the BeginFrame warmup loop.
+ *
+ *   - Unlocked: exits as soon as `state.running` flips to `false`. Tick count
+ *     varies with wall-clock page-load time.
+ *   - Locked: ignores `state.running` entirely and exits once it has driven
+ *     exactly `LOCKED_WARMUP_TICKS` iterations. Caller awaits this promise
+ *     after page-readiness so `session.beginFrameTimeTicks` is identical
+ *     across hosts.
+ *   - `tick` errors are swallowed (Chrome's `beginFrame` is best-effort
+ *     during page load — the page hasn't installed CDP listeners yet). When
+ *     `tick` throws, the iteration count does NOT advance.
+ *
+ * `intervalMs` is the BeginFrame interval (≈33ms at 30fps).
+ *
+ * `frameTimeTicks` is derived as `ticks * intervalMs` and exposed via
+ * {@link warmupFrameTimeTicks} — not stored on the state, to keep `ticks`
+ * the single source of truth.
+ */
+export interface WarmupTickState {
+  running: boolean;
+  ticks: number;
+}
+
+export interface WarmupTickOptions {
+  intervalMs: number;
+  lockWarmupTicks: boolean;
+  tick: (frameTimeTicks: number, intervalMs: number) => Promise<void>;
+  /** Injectable so tests can advance "time" without real setTimeout. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const realSleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Derive the current simulated frame time from a warmup state. Single source
+ * of truth so tests and callers stay in sync.
+ */
+export function warmupFrameTimeTicks(state: WarmupTickState, intervalMs: number): number {
+  return state.ticks * intervalMs;
+}
+
+export async function driveWarmupTicks(
+  options: WarmupTickOptions,
+  state: WarmupTickState,
+): Promise<void> {
+  const sleep = options.sleep ?? realSleep;
+  while (true) {
+    if (options.lockWarmupTicks) {
+      // Locked mode exits on the iteration count, ignoring `state.running` —
+      // the caller flips `running=false` after page-readiness but we keep
+      // ticking until LOCKED_WARMUP_TICKS so the count is host-independent.
+      if (state.ticks >= LOCKED_WARMUP_TICKS) return;
+    } else {
+      // Unlocked mode is wall-clock-bounded.
+      if (!state.running) return;
+    }
+    try {
+      await options.tick(state.ticks * options.intervalMs, options.intervalMs);
+      state.ticks += 1;
+    } catch {
+      // Page not ready yet; keep spinning.
+    }
+    await sleep(options.intervalMs);
+  }
+}
+
 async function waitForCloseWithTimeout(promise: Promise<unknown>): Promise<boolean> {
   let timedOut = false;
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -447,38 +522,53 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
   // In BeginFrame mode, Chrome's event loop is paused until we issue frames.
   // Start a warmup loop to drive rAF/setTimeout callbacks during page load.
-  let warmupRunning = true;
-  let warmupTicks = 0;
-  let warmupFrameTime = 0;
+  //
+  // The unlocked path runs while `warmupState.running` stays true — wall-
+  // clock-bounded. The locked path (`options.lockWarmupTicks`) additionally
+  // exits at exactly `LOCKED_WARMUP_TICKS` iterations so `beginFrameTimeTicks`
+  // is deterministic across hosts with different page-load latencies.
   const warmupIntervalMs = 33; // ~30fps
+  const warmupState: WarmupTickState = {
+    running: true,
+    ticks: 0,
+  };
+  const lockWarmupTicks = session.options.lockWarmupTicks === true;
   let warmupClient: import("puppeteer-core").CDPSession | null = null;
 
-  const warmupLoop = async () => {
+  const acquireWarmupClient = async (): Promise<void> => {
     try {
       warmupClient = await getCdpSession(page);
       await warmupClient.send("HeadlessExperimental.enable");
     } catch {
       /* page not ready yet */
     }
+  };
 
-    while (warmupRunning) {
-      if (warmupClient) {
-        try {
+  const warmupLoopPromise = (async () => {
+    await acquireWarmupClient();
+    await driveWarmupTicks(
+      {
+        intervalMs: warmupIntervalMs,
+        lockWarmupTicks,
+        tick: async (frameTimeTicks, interval) => {
+          if (!warmupClient) {
+            // No CDP yet — let driveWarmupTicks count the tick anyway so the
+            // locked iteration count is reached deterministically. Throwing
+            // would skip the ticks++ increment, leaking host-load variance
+            // back into the count.
+            return;
+          }
           await warmupClient.send("HeadlessExperimental.beginFrame", {
-            frameTimeTicks: warmupFrameTime,
-            interval: warmupIntervalMs,
+            frameTimeTicks,
+            interval,
             noDisplayUpdates: true,
           });
-          warmupFrameTime += warmupIntervalMs;
-          warmupTicks++;
-        } catch {
-          /* ignore warmup errors */
-        }
-      }
-      await new Promise((r) => setTimeout(r, warmupIntervalMs));
-    }
-  };
-  warmupLoop().catch(() => {});
+        },
+      },
+      warmupState,
+    );
+  })();
+  warmupLoopPromise.catch(() => {});
 
   await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60000 });
 
@@ -497,7 +587,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     `!!(window.__hf && typeof window.__hf.seek === "function" && window.__hf.duration > 0)`,
   );
   if (!pageReady) {
-    warmupRunning = false;
+    warmupState.running = false;
     throw new Error(
       `[FrameCapture] window.__hf not ready after ${pageReadyTimeout}ms. Page must expose window.__hf = { duration, seek }.`,
     );
@@ -521,11 +611,18 @@ export async function initializeSession(session: CaptureSession): Promise<void>
   await page.evaluate(`document.fonts?.ready`);
   await waitForOptionalTailwindReady(page, pageReadyTimeout);
 
-  // Stop warmup
-  warmupRunning = false;
+  // Stop warmup. Unlocked mode exits on this flag; locked mode keeps ticking
+  // until LOCKED_WARMUP_TICKS, so we await its promise to ensure the count is
+  // exact before deriving the baseline.
+  warmupState.running = false;
+  if (lockWarmupTicks) {
+    await warmupLoopPromise.catch(() => {});
+  }
 
-  // Set base frame time ticks past warmup range
-  session.beginFrameTimeTicks = (warmupTicks + 10) * session.beginFrameIntervalMs;
+  // Set base frame time ticks past warmup range. Locked mode pins to the
+  // constant so chunk workers on different hosts compute the same baseline.
+  const baseTickCount = lockWarmupTicks ? LOCKED_WARMUP_TICKS : warmupState.ticks;
+  session.beginFrameTimeTicks = (baseTickCount + 10) * session.beginFrameIntervalMs;
 
   // For PNG captures, inject the transparent-background override + stylesheet
   // (see the screenshot-mode branch above for the rationale). BeginFrame mode
@@ -712,6 +809,69 @@ export async function captureFrameToBuffer(
   return { buffer, captureTimeMs };
 }
 
+/**
+ * Type of the "inner capture" function consumed by
+ * {@link discardWarmupCapture}. Matches the real `captureFrameCore` signature
+ * with the buffer-bearing result trimmed to what the caller actually uses
+ * (the wrapper never inspects the buffer). Exposed so unit tests can inject
+ * a stub instead of driving Chrome end-to-end.
+ */
+export type DiscardWarmupInnerCapture = (
+  session: CaptureSession,
+  frameIndex: number,
+  time: number,
+) => Promise<{ buffer: Buffer; quantizedTime: number; captureTimeMs: number }>;
+
+/**
+ * Perform one capture, throw away the buffer, and restore any session
+ * side-effects (perf counters, BeginFrame damage tallies) so downstream
+ * captures see state identical to a fresh session.
+ *
+ * Distributed chunk workers need this because Chrome's BeginFrame screenshot
+ * pipeline maintains a per-process `lastFrameCache`: when a captured frame's
+ * `hasDamage` reports `false`, the screenshot path returns the previously
+ * captured buffer. For chunk N (N > 0) the worker has no prior frame in its
+ * cache, so the very first capture's `hasDamage` reporting diverges from
+ * what an in-process render at the same absolute frame index would see (the
+ * in-process renderer always has frame N-1 cached). One discard capture
+ * before the first real capture primes the cache.
+ *
+ * The function intentionally restores perf state so the warmup capture does
+ * NOT bias `getCapturePerfSummary()`'s per-frame averages.
+ *
+ * No file is written; the buffer is discarded.
+ *
+ * @param session — initialized capture session
+ * @param frameIndex — frame index to warm up with (default 0). Chunk
+ *   workers typically pass their chunk's first absolute frame index.
+ * @param time — time in seconds (default 0). Chunk workers typically pass
+ *   the corresponding `frameIndex / fps`.
+ * @param innerCapture — injectable for tests; defaults to the real
+ *   `captureFrameCore`.
+ */
+export async function discardWarmupCapture(
+  session: CaptureSession,
+  frameIndex: number = 0,
+  time: number = 0,
+  innerCapture: DiscardWarmupInnerCapture = captureFrameCore,
+): Promise<void> {
+  // Snapshot the side-effect counters captureFrameCore mutates. We use a
+  // shallow `{...}` for capturePerf because all five fields are primitive
+  // numbers — no nested state to deep-copy.
+  const perfBefore = { ...session.capturePerf };
+  const hasDamageBefore = session.beginFrameHasDamageCount;
+  const noDamageBefore = session.beginFrameNoDamageCount;
+  try {
+    await innerCapture(session, frameIndex, time);
+  } finally {
+    // Always restore — even on error. A failed warmup capture should not
+    // leak inflated perf counters into the real capture summary.
+    session.capturePerf = perfBefore;
+    session.beginFrameHasDamageCount = hasDamageBefore;
+    session.beginFrameNoDamageCount = noDamageBefore;
+  }
+}
+
 export async function closeCaptureSession(session: CaptureSession): Promise<void> {
   // INVARIANT: closeCaptureSession is idempotent. The renderOrchestrator HDR
   // cleanup path tracks a `domSessionClosed` flag and may still re-call this

package/src/types.ts

@@ -120,6 +120,20 @@ export interface CaptureOptions {
    * `--variables-file <path>`. Must be a JSON-serializable plain object.
    */
   variables?: Record<string, unknown>;
+  /**
+   * When `true`, the BeginFrame warmup loop driven during page navigation
+   * runs exactly `LOCKED_WARMUP_TICKS` (60) iterations regardless of how
+   * long the page load takes, making `session.beginFrameTimeTicks`
+   * deterministic across machines with different page-load latencies.
+   *
+   * Default `false`: wall-clock-bounded driver — ticks until page-readiness
+   * completes, accumulating whatever count the host CPU manages. Preserves
+   * the in-process renderer's BeginFrame timing baselines.
+   *
+   * Has no effect outside BeginFrame mode (screenshot capture never runs a
+   * warmup loop).
+   */
+  lockWarmupTicks?: boolean;
 }
 
 export interface CaptureVideoMetadataHint {

package/src/utils/assertSwiftShader.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for assertSwiftShader and its companion readWebGlVendorInfo helper.
+ *
+ * We don't spin up a real Chrome here — the assertion's contract is "given a
+ * WebGL info pair, accept SwiftShader and reject anything else." Tests inject
+ * the info pair through the optional `readInfo` override that the
+ * production code path leaves as a default.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { Page } from "puppeteer-core";
+import {
+  BROWSER_GPU_NOT_SOFTWARE,
+  SwiftShaderAssertionError,
+  assertSwiftShader,
+} from "./assertSwiftShader.js";
+
+// Minimal Page stub. Only assertSwiftShader's default `readInfo` ever touches
+// `page.goto` / `page.evaluate`; when we inject a custom `readInfo` the page
+// object is never used, so an empty cast is safe.
+const stubPage = {} as unknown as Page;
+
+describe("assertSwiftShader", () => {
+  it("accepts the canonical SwiftShader vendor + renderer pair", async () => {
+    await assertSwiftShader(stubPage, async () => ({
+      vendor: "Google Inc. (Google)",
+      renderer:
+        "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)",
+    }));
+  });
+
+  it("accepts SwiftShader regardless of trailing whitespace on vendor", async () => {
+    await assertSwiftShader(stubPage, async () => ({
+      vendor: "  Google Inc. (Google)  ",
+      renderer: "SwiftShader",
+    }));
+  });
+
+  it("accepts case-insensitive renderer token", async () => {
+    await assertSwiftShader(stubPage, async () => ({
+      vendor: "Google Inc. (Google)",
+      renderer: "ANGLE (Google, swiftshader Device, swiftshader driver)",
+    }));
+  });
+
+  it("throws SwiftShaderAssertionError when vendor is hardware-accelerated", async () => {
+    let caught: unknown;
+    try {
+      await assertSwiftShader(stubPage, async () => ({
+        vendor: "Google Inc. (NVIDIA Corporation)",
+        renderer: "ANGLE (NVIDIA, NVIDIA GeForce RTX 4090, OpenGL 4.6)",
+      }));
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(SwiftShaderAssertionError);
+    expect((caught as SwiftShaderAssertionError).code).toBe(BROWSER_GPU_NOT_SOFTWARE);
+    expect((caught as Error).message).toContain("non-SwiftShader");
+    expect((caught as Error).message).toContain("--use-gl=swiftshader");
+    expect((caught as SwiftShaderAssertionError).vendor).toBe("Google Inc. (NVIDIA Corporation)");
+  });
+
+  it("throws when the renderer string lacks SwiftShader even if vendor matches", async () => {
+    // Google Inc. is the umbrella vendor for many ANGLE backends — vendor
+    // alone is not enough; the renderer must actually mention SwiftShader.
+    let caught: unknown;
+    try {
+      await assertSwiftShader(stubPage, async () => ({
+        vendor: "Google Inc. (Google)",
+        renderer: "ANGLE (Google, Vulkan 1.3.0 (Intel(R) UHD Graphics 630), OpenGL ES 3.0)",
+      }));
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(SwiftShaderAssertionError);
+    expect((caught as SwiftShaderAssertionError).code).toBe(BROWSER_GPU_NOT_SOFTWARE);
+  });
+
+  it("throws when both vendor and renderer are empty", async () => {
+    // Some chrome:// pages return empty strings before the GPU info table
+    // populates. We treat that as failure rather than silently passing.
+    let caught: unknown;
+    try {
+      await assertSwiftShader(stubPage, async () => ({ vendor: "", renderer: "" }));
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(SwiftShaderAssertionError);
+    expect((caught as SwiftShaderAssertionError).code).toBe(BROWSER_GPU_NOT_SOFTWARE);
+  });
+
+  it("propagates errors from the info reader without wrapping", async () => {
+    const upstream = new Error("simulated CDP failure");
+    let caught: unknown;
+    try {
+      await assertSwiftShader(stubPage, async () => {
+        throw upstream;
+      });
+    } catch (err) {
+      caught = err;
+    }
+    // Reader errors should not be masked by SwiftShaderAssertionError —
+    // they are a separate failure class (probably retryable).
+    expect(caught).toBe(upstream);
+  });
+
+  it("rejects an unrelated vendor that happens to contain the SwiftShader token in the renderer", async () => {
+    // Defensive: if some future ANGLE build uses a non-Google vendor string
+    // but still mentions SwiftShader in the renderer for some reason, we
+    // still want to require the exact Google vendor signature.
+    let caught: unknown;
+    try {
+      await assertSwiftShader(stubPage, async () => ({
+        vendor: "Mesa/X.org",
+        renderer: "llvmpipe (SwiftShader compatible)",
+      }));
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(SwiftShaderAssertionError);
+  });
+});
+
+describe("SwiftShaderAssertionError", () => {
+  it("exposes the BROWSER_GPU_NOT_SOFTWARE typed-failure code", () => {
+    const err = new SwiftShaderAssertionError("test", "v", "r");
+    expect(err.code).toBe(BROWSER_GPU_NOT_SOFTWARE);
+    expect(err.code).toBe("BROWSER_GPU_NOT_SOFTWARE");
+  });
+});

package/src/utils/assertSwiftShader.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 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 {
+  readonly code: typeof BROWSER_GPU_NOT_SOFTWARE = BROWSER_GPU_NOT_SOFTWARE;
+  readonly vendor: string;
+  readonly renderer: string;
+
+  constructor(message: string, vendor: string, renderer: string) {
+    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";
+
+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 async function readWebGlVendorInfo(page: Page): Promise<WebGlInfo> {
+  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((): WebGlInfo => {
+    type Row = { description?: string; value?: string };
+    type InfoLog = { graphics_info?: { basic_info?: Row[] } };
+    const w = window as unknown as { browserBridge?: { gpuInfo_?: InfoLog } };
+    const rows: Row[] = 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: Page,
+  readInfo: (page: Page) => Promise<WebGlInfo> = readWebGlVendorInfo,
+): Promise<void> {
+  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,
+  );
+}