@hyperframes/engine 0.6.118 → 0.6.120

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

@@ -1,183 +0,0 @@
-/**
- * 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-namePolyfill.test.ts

@@ -1,78 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-
-// Regression coverage for the `window.__name` no-op shim that
-// `frameCapture.ts` registers via `page.evaluateOnNewDocument`.
-//
-// Background: `@hyperframes/engine` ships raw TypeScript (see
-// `packages/engine/package.json` — main and exports both point at
-// `./src/index.ts`). Downstream transpilers like tsx run esbuild with
-// keepNames=true, which wraps named functions in `__name(fn, "name")`
-// calls. When Puppeteer serializes a `page.evaluate(callback)` argument
-// via `Function.prototype.toString()`, those wrappers travel into the
-// browser and throw `ReferenceError: __name is not defined` unless we
-// install a no-op shim first.
-//
-// These tests intentionally do NOT launch a browser — the rest of this
-// package follows the same pure-unit-test convention. Instead they:
-//   1. Assert the polyfill is wired up at the source level so it cannot
-//      be silently removed by a careless edit.
-//   2. Probe the current Vitest runtime so a future maintainer can see at
-//      a glance whether nested named functions still get `__name(...)`
-//      wrappers under the test transformer. This is advisory: both
-//      outcomes are acceptable — the reported observation is what makes
-//      the test useful when the upstream behavior shifts.
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const FRAME_CAPTURE_PATH = resolve(__dirname, "frameCapture.ts");
-
-describe("frameCapture __name polyfill", () => {
-  it("registers a window.__name shim via evaluateOnNewDocument", () => {
-    const source = readFileSync(FRAME_CAPTURE_PATH, "utf-8");
-
-    expect(source).toMatch(/page\.evaluateOnNewDocument\(/);
-    expect(source).toMatch(/typeof w\.__name !== "function"/);
-    expect(source).toMatch(/w\.__name\s*=\s*<T>/);
-  });
-
-  it("installs the shim before any awaited browser-version checks", () => {
-    const source = readFileSync(FRAME_CAPTURE_PATH, "utf-8");
-
-    const polyfillIndex = source.indexOf("page.evaluateOnNewDocument(");
-    const versionIndex = source.indexOf("await browser.version()");
-
-    expect(polyfillIndex).toBeGreaterThan(-1);
-    expect(versionIndex).toBeGreaterThan(-1);
-    expect(polyfillIndex).toBeLessThan(versionIndex);
-  });
-
-  it("documents the current transpiler behavior for nested named functions", () => {
-    function outer(): { wrapsNested: boolean; wrapsArrow: boolean } {
-      // The unused declarations are deliberate: we are inspecting whether the
-      // active transpiler rewrites `outer.toString()` to include
-      // `__name(nested, ...)` / `__name(arrowNested, ...)` wrappers.
-      // eslint-disable-next-line no-unused-vars
-      function nested() {
-        return 1;
-      }
-      // eslint-disable-next-line no-unused-vars
-      const arrowNested = () => 2;
-      const src = outer.toString();
-      return {
-        wrapsNested: /__name\(\s*nested\s*,/.test(src),
-        wrapsArrow: /__name\(\s*\(\)\s*=>\s*2\s*,/.test(src) || /__name\(\s*arrowNested/.test(src),
-      };
-    }
-
-    const { wrapsNested, wrapsArrow } = outer();
-
-    // Both outcomes are acceptable; the value of this test is in surfacing
-    // the runtime's behavior on the next failure (or first inspection).
-    // If both flags become false everywhere this engine is consumed, the
-    // polyfill above can probably be dropped. Until then it stays.
-    expect(typeof wrapsNested).toBe("boolean");
-    expect(typeof wrapsArrow).toBe("boolean");
-  });
-});

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

@@ -1,153 +0,0 @@
-/**
- * Tests for `pollImagesReady` — the image-side analog of `pollVideosReady`.
- *
- * Critical contract:
- *   - Successfully loaded image (complete=true, naturalWidth>0) → settled.
- *   - Broken / 404 image (complete=true, naturalWidth=0) → settled.
- *     This mirrors `pollVideosReady`'s `ve.error` early-exit. Without it,
- *     the htmlCompiler 404-fallback path (where a remote <img> URL failed
- *     to download and the original URL is preserved) would silently spin
- *     the full `pageReadyTimeout` budget waiting for an image that will
- *     never load — a 45 s regression vs the pre-PR behavior.
- *   - In-flight image (complete=false) → still waiting.
- *   - data: URI src → settled (no network fetch).
- *   - Empty src → settled (nothing to load).
- */
-
-import { describe, expect, it } from "vitest";
-import type { Page } from "puppeteer-core";
-import { pollImagesReady } from "./frameCapture.js";
-
-interface ImageSpec {
-  src: string;
-  complete: boolean;
-  naturalWidth: number;
-}
-
-// Mock `page` whose `evaluate(fn)` invokes `fn` with a Node-side `document`
-// mock that returns synthetic image objects matching the spec. Snapshots the
-// image state at evaluate-time, so callers can mutate `imgs` between polls
-// to simulate progressive load completion.
-function makeMockPage(imgs: () => ImageSpec[]): Page {
-  return {
-    evaluate: async (fn: () => unknown) => {
-      const snapshot = imgs();
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const prevDoc = (globalThis as any).document;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      (globalThis as any).document = {
-        querySelectorAll: () =>
-          snapshot.map((spec) => ({
-            getAttribute: (attr: string) => (attr === "src" ? spec.src : null),
-            complete: spec.complete,
-            naturalWidth: spec.naturalWidth,
-          })),
-      };
-      try {
-        return await fn();
-      } finally {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (globalThis as any).document = prevDoc;
-      }
-    },
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  } as any as Page;
-}
-
-describe("pollImagesReady", () => {
-  it("resolves immediately when there are no <img> elements", async () => {
-    const page = makeMockPage(() => []);
-    const result = await pollImagesReady(page, 1000, 10);
-    expect(result).toBe(true);
-  });
-
-  it("resolves immediately when every image has loaded successfully", async () => {
-    const page = makeMockPage(() => [
-      { src: "/a.png", complete: true, naturalWidth: 100 },
-      { src: "/b.png", complete: true, naturalWidth: 200 },
-    ]);
-    const result = await pollImagesReady(page, 1000, 10);
-    expect(result).toBe(true);
-  });
-
-  it("treats a broken image (complete=true, naturalWidth=0) as settled — does NOT wait for timeout", async () => {
-    // This is the bug Magi flagged. Without the broken-image escape, this
-    // test would block the full 1000ms timeout and return false.
-    const page = makeMockPage(() => [
-      { src: "/a.png", complete: true, naturalWidth: 100 },
-      { src: "https://broken.example.com/404.png", complete: true, naturalWidth: 0 },
-    ]);
-    const t0 = Date.now();
-    const result = await pollImagesReady(page, 1000, 10);
-    const elapsed = Date.now() - t0;
-    expect(result).toBe(true);
-    // Must resolve fast — well under the 1000ms timeout.
-    expect(elapsed).toBeLessThan(500);
-  });
-
-  it("treats a data: URI src as settled regardless of complete/naturalWidth", async () => {
-    const page = makeMockPage(() => [
-      { src: "data:image/svg+xml,%3Csvg/%3E", complete: false, naturalWidth: 0 },
-    ]);
-    const result = await pollImagesReady(page, 1000, 10);
-    expect(result).toBe(true);
-  });
-
-  it("treats an empty src as settled (nothing to load)", async () => {
-    const page = makeMockPage(() => [{ src: "", complete: false, naturalWidth: 0 }]);
-    const result = await pollImagesReady(page, 1000, 10);
-    expect(result).toBe(true);
-  });
-
-  it("waits for an in-flight image and resolves once it completes", async () => {
-    // Image starts in-flight, then completes after ~50ms.
-    let started = false;
-    const startTime = { value: 0 };
-    const page = makeMockPage(() => {
-      if (!started) {
-        started = true;
-        startTime.value = Date.now();
-      }
-      const elapsed = Date.now() - startTime.value;
-      const loaded = elapsed >= 50;
-      return [{ src: "/slow.png", complete: loaded, naturalWidth: loaded ? 100 : 0 }];
-    });
-    const result = await pollImagesReady(page, 1000, 10);
-    expect(result).toBe(true);
-  });
-
-  it("times out and returns false when an in-flight image never resolves", async () => {
-    // Image stays in-flight (complete=false) for the full timeout.
-    const page = makeMockPage(() => [
-      { src: "/never-loads.png", complete: false, naturalWidth: 0 },
-    ]);
-    const result = await pollImagesReady(page, 100, 10);
-    expect(result).toBe(false);
-  });
-
-  it("mixed batch: loaded + broken + data: + in-flight → waits only on the in-flight image", async () => {
-    let resolved = false;
-    const start = Date.now();
-    const page = makeMockPage(() => {
-      const elapsed = Date.now() - start;
-      if (elapsed >= 30) resolved = true;
-      return [
-        { src: "/loaded.png", complete: true, naturalWidth: 800 },
-        { src: "https://broken.example.com/404.jpg", complete: true, naturalWidth: 0 },
-        { src: "data:image/svg+xml,abc", complete: false, naturalWidth: 0 },
-        {
-          src: "/in-flight.png",
-          complete: resolved,
-          naturalWidth: resolved ? 200 : 0,
-        },
-      ];
-    });
-    const t0 = Date.now();
-    const result = await pollImagesReady(page, 1000, 10);
-    const elapsed = Date.now() - t0;
-    expect(result).toBe(true);
-    // Should wait roughly for the in-flight image to settle (~30ms) — not the
-    // full timeout. Allow generous slack for CI scheduler jitter.
-    expect(elapsed).toBeLessThan(500);
-  });
-});

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

@@ -1,76 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { captureFrameToBuffer, type CaptureSession } from "./frameCapture.js";
-
-/**
- * Regression lock for the static-dedup reuse index.
- *
- * `captureFrameCore` must key the static-frame reuse set on the ABSOLUTE
- * composition frame — derived from `time` (`round(time * fps)`) — NOT the
- * `frameIndex` argument. Distributed / per-worker-range / parallel callers pass
- * a chunk-RELATIVE `frameIndex` (captureStage passes the loop `i`,
- * parallelCoordinator passes `i - outputFrameOffset`) while `staticFrames` is
- * keyed in absolute frames. A prior bug used `frameIndex`, so a chunk with
- * `startFrame > 0` reused the wrong frames (and the right frames missed).
- *
- * The reuse branch returns BEFORE any page interaction, so we can exercise the
- * decision with a stub session whose `page` throws if touched: a dedup HIT
- * returns the cached buffer (page untouched); a MISS proceeds to the page and
- * rejects. Both assertions below FAIL on the pre-fix (relative-index) code.
- */
-
-const SENTINEL = Buffer.from("cached-anchor-frame");
-
-// ponytail: minimal stub of the 40-field CaptureSession — only the fields the
-// reuse decision reads are real; `page` is a trap that throws on any access so
-// a dedup MISS (which falls through to prepareFrameForCapture) rejects loudly.
-function makeSession(staticFrames: Set<number>, fps: { num: number; den: number }): CaptureSession {
-  const pageTrap = new Proxy(
-    {},
-    {
-      get() {
-        throw new Error("PAGE_TOUCHED");
-      },
-    },
-  );
-  return {
-    page: pageTrap,
-    options: { fps, format: "jpg" },
-    captureMode: "screenshot",
-    isInitialized: false,
-    staticFrames,
-    lastFrameBuffer: SENTINEL,
-    staticDedupCount: 0,
-  } as unknown as CaptureSession;
-}
-
-describe("static-dedup reuse keys on absolute frame index (time), not relative frameIndex", () => {
-  const fps30 = { num: 30, den: 1 };
-
-  it("HIT: relative frameIndex=0 but absolute time=90/30 reuses the anchor", async () => {
-    const session = makeSession(new Set([90]), fps30);
-    // Pre-fix used frameIndex (0) ∉ {90} → would miss → page trap throws.
-    const result = await captureFrameToBuffer(session, 0, 90 / 30);
-    expect(result.buffer).toBe(SENTINEL);
-    expect(session.staticDedupCount).toBe(1);
-  });
-
-  it("MISS: relative frameIndex=90 but absolute time=0 does NOT reuse", async () => {
-    const session = makeSession(new Set([90]), fps30);
-    // Pre-fix used frameIndex (90) ∈ {90} → would wrongly reuse the anchor.
-    await expect(captureFrameToBuffer(session, 90, 0)).rejects.toThrow();
-    expect(session.staticDedupCount).toBe(0);
-  });
-
-  it("non-integer fps (29.97) recovers the absolute index exactly", async () => {
-    const fps2997 = { num: 30000, den: 1001 };
-    const session = makeSession(new Set([100]), fps2997);
-    const time = (100 * fps2997.den) / fps2997.num; // absolute frame 100 → time
-    const result = await captureFrameToBuffer(session, 7, time);
-    expect(result.buffer).toBe(SENTINEL);
-  });
-
-  it("no reuse when the absolute frame is not in the static set", async () => {
-    const session = makeSession(new Set([10, 11, 12]), fps30);
-    await expect(captureFrameToBuffer(session, 0, 50 / 30)).rejects.toThrow();
-  });
-});

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

@@ -1,174 +0,0 @@
-/**
- * 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);
-  });
-});