Files
hyperframes/packages/cli/src/capture/captureCompositionFrame.test.ts
T
James Russo 3a6b7f0612 fix: align local WebGPU capture behavior (#2907)
* fix: align local WebGPU capture behavior

* fix: address WebGPU capture review feedback

* fix: retain overlapping GPU seek work

* fix: satisfy runtime seek completion types

* fix: drain concurrent GPU seek work

* fix: prevent WebGPU capture barrier starvation

* fix: keep WebGPU presentation active during render seeks
2026-07-30 21:52:30 -07:00

422 lines
15 KiB
TypeScript

import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
AUDIT_SEEK_OPTIONS,
DENSE_GEOMETRY_SEEK_OPTIONS,
captureRegionCrop,
clampCropRegion,
installPageFunctionGuard,
padCropRegion,
parseZoomTarget,
resolveCliChromeGpuMode,
resolveCropRegion,
runFfmpegOnce,
seekCompositionTimeline,
type CompositionSeekPage,
} from "./captureCompositionFrame.js";
function tempDir(): string {
return mkdtempSync(join(tmpdir(), "hf-capture-frame-test-"));
}
function fakeSeekPage() {
const evaluate = vi.fn(
async (
_pageFunction: Parameters<CompositionSeekPage["evaluate"]>[0],
_value?: number,
_fallbackToBridgeAndTimelines?: boolean,
): Promise<unknown> => undefined,
);
const waitForFunction = vi.fn(
async (_pageFunction: () => boolean, _options: { timeout: number }): Promise<unknown> =>
undefined,
);
const page: CompositionSeekPage = { evaluate, waitForFunction };
return { page, evaluate, waitForFunction };
}
function runBrowserSeek(evaluate: ReturnType<typeof fakeSeekPage>["evaluate"]): void {
const seekInBrowser = evaluate.mock.calls[0]?.[0];
if (typeof seekInBrowser !== "function") throw new Error("Expected a browser seek function");
Reflect.apply(seekInBrowser, undefined, evaluate.mock.calls[0]?.slice(1) ?? []);
}
afterEach(() => {
vi.useRealTimers();
vi.unstubAllGlobals();
});
describe("seekCompositionTimeline", () => {
it("keeps the raced double-frame settle and adds a bounded font wait by default", async () => {
const { page, evaluate, waitForFunction } = fakeSeekPage();
await seekCompositionTimeline(page, 1.25);
expect(waitForFunction).not.toHaveBeenCalled();
expect(evaluate).toHaveBeenCalledTimes(4);
expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 1.25, false);
expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function));
expect(evaluate.mock.calls[2]?.[0]).toContain("window.setTimeout(finish, 100)");
// Post-seek font settle: a seek can reveal glyphs whose unicode-range
// subsets only start loading after the next layout (CJK snapshot reports).
expect(evaluate).toHaveBeenNthCalledWith(4, expect.any(Function), 500);
});
it("waitForFontsMs: 0 disables the post-seek font wait", async () => {
const { page, evaluate } = fakeSeekPage();
await seekCompositionTimeline(page, 1.25, { waitForFontsMs: 0 });
expect(evaluate).toHaveBeenCalledTimes(3);
});
it("prefers renderSeek so the runtime synchronizes clip visibility", async () => {
const { page, evaluate } = fakeSeekPage();
const renderSeek = vi.fn();
const bridgeSeek = vi.fn();
const playerSeek = vi.fn();
const timelineSeek = vi.fn();
vi.stubGlobal("window", {
__player: { renderSeek, seek: playerSeek },
__hf: { seek: bridgeSeek },
__timelines: { main: { seek: timelineSeek } },
});
await seekCompositionTimeline(page, 2.25);
runBrowserSeek(evaluate);
expect(renderSeek).toHaveBeenCalledWith(2.25);
expect(bridgeSeek).not.toHaveBeenCalled();
expect(playerSeek).not.toHaveBeenCalled();
expect(timelineSeek).not.toHaveBeenCalled();
});
function fakeBridgeOnlySeekPage() {
const { page, evaluate } = fakeSeekPage();
const bridgeSeek = vi.fn();
const tickerTick = vi.fn();
vi.stubGlobal("window", { __hf: { seek: bridgeSeek }, gsap: { ticker: { tick: tickerTick } } });
return { page, evaluate, bridgeSeek, tickerTick };
}
it("keeps bridge and raw fallbacks disabled for default capture callers", async () => {
const { page, evaluate, bridgeSeek, tickerTick } = fakeBridgeOnlySeekPage();
await seekCompositionTimeline(page, 2.5);
runBrowserSeek(evaluate);
expect(bridgeSeek).not.toHaveBeenCalled();
expect(tickerTick).not.toHaveBeenCalled();
});
it("opts into the bridge before player and raw timeline fallbacks", async () => {
const { page, evaluate, bridgeSeek, tickerTick } = fakeBridgeOnlySeekPage();
await seekCompositionTimeline(page, 2.5, { fallbackToBridgeAndTimelines: true });
runBrowserSeek(evaluate);
expect(bridgeSeek).toHaveBeenCalledWith(2.5);
expect(tickerTick).toHaveBeenCalledOnce();
});
it("opts into pausing and seeking raw timelines when no preferred target exists", async () => {
const { page, evaluate } = fakeSeekPage();
const pause = vi.fn();
const seek = vi.fn();
vi.stubGlobal("window", { __timelines: { main: { pause, seek } } });
await seekCompositionTimeline(page, 1.75, { fallbackToBridgeAndTimelines: true });
runBrowserSeek(evaluate);
expect(pause).toHaveBeenCalledOnce();
expect(seek).toHaveBeenCalledWith(1.75);
});
it("supports validate settling without adding an animation-frame or font wait", async () => {
vi.useFakeTimers();
const { page, evaluate, waitForFunction } = fakeSeekPage();
const pending = seekCompositionTimeline(page, 3, {
fallbackToBridgeAndTimelines: true,
waitForPreferredSeekTargetMs: 500,
animationFrameSettle: "none",
waitForFontsMs: 0,
settleMs: 150,
});
await vi.advanceTimersByTimeAsync(150);
await pending;
expect(waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 500 });
expect(evaluate).toHaveBeenCalledTimes(2);
expect(evaluate).toHaveBeenCalledWith(expect.any(Function), 3, true);
});
it("supports layout's ordered double-frame, bounded font, and sleep settles", async () => {
vi.useFakeTimers();
const { page, evaluate } = fakeSeekPage();
const pending = seekCompositionTimeline(page, 4, {
fallbackToBridgeAndTimelines: true,
animationFrameSettle: "double",
waitForFontsMs: 500,
settleMs: 120,
});
await vi.advanceTimersByTimeAsync(120);
await pending;
expect(evaluate).toHaveBeenCalledTimes(4);
expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 4, true);
expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function));
expect(evaluate).toHaveBeenNthCalledWith(3, expect.any(Function));
expect(evaluate).toHaveBeenNthCalledWith(4, expect.any(Function), 500);
});
it("awaits GPU completion registered by the seek event before settling", async () => {
let completeGpu: (() => void) | undefined;
const gpuWork = new Promise<void>((resolve) => {
completeGpu = resolve;
});
let evaluateCall = 0;
vi.stubGlobal("window", {
__player: { renderSeek: vi.fn() },
__hfWaitForSeekCompletion: () => gpuWork,
});
const page: CompositionSeekPage = {
evaluate: vi.fn(async (pageFunction, value, fallback) => {
evaluateCall += 1;
if (typeof pageFunction === "function") {
return Reflect.apply(pageFunction, undefined, [value, fallback]);
}
}),
};
let settled = false;
const pending = seekCompositionTimeline(page, 1, {
animationFrameSettle: "none",
waitForFontsMs: 0,
}).then(() => {
settled = true;
});
await Promise.resolve();
expect(evaluateCall).toBe(2);
expect(settled).toBe(false);
completeGpu?.();
await pending;
expect(settled).toBe(true);
});
});
describe("resolveCliChromeGpuMode", () => {
it("preserves auto/hardware/software env mapping", () => {
expect(resolveCliChromeGpuMode("software")).toBe("software");
expect(resolveCliChromeGpuMode("hardware")).toBe("hardware");
expect(resolveCliChromeGpuMode("auto")).toBe("auto");
expect(resolveCliChromeGpuMode("")).toBe("auto");
});
});
describe("screenshot Chrome arguments", () => {
it("resolves auto once and launches shared captures with the concrete mode", () => {
const captureSource = readFileSync(
new URL("./captureCompositionFrame.ts", import.meta.url),
"utf8",
);
const layoutSource = readFileSync(new URL("../commands/layout.ts", import.meta.url), "utf8");
expect(captureSource).toContain("resolveCaptureBrowserGpuMode(");
expect(captureSource).toContain("{ browserGpuMode: resolvedGpuMode }");
expect(layoutSource).toContain("resolveCaptureBrowserGpuMode(");
expect(layoutSource).toContain("{ browserGpuMode: resolvedGpuMode }");
});
});
describe("parseZoomTarget", () => {
it("parses four comma-separated numbers as an exact region", () => {
expect(parseZoomTarget("100,50,400,300")).toEqual({
kind: "region",
region: { x: 100, y: 50, width: 400, height: 300 },
});
});
it("treats anything else as a CSS selector", () => {
expect(parseZoomTarget("#headline")).toEqual({ kind: "selector", selector: "#headline" });
expect(parseZoomTarget(".card:nth-of-type(2)")).toEqual({
kind: "selector",
selector: ".card:nth-of-type(2)",
});
});
});
describe("clampCropRegion / padCropRegion", () => {
it("clamps a region to the canvas bounds", () => {
expect(
clampCropRegion({ x: -10, y: -10, width: 50, height: 50 }, { width: 30, height: 30 }),
).toEqual({
x: 0,
y: 0,
width: 30,
height: 30,
});
});
it("pads a region on every side when it fits within the canvas", () => {
expect(
padCropRegion({ x: 500, y: 500, width: 100, height: 40 }, { width: 1920, height: 1080 }, 24),
).toEqual({ x: 476, y: 476, width: 148, height: 88 });
});
it("pads then clamps when padding would spill outside the canvas", () => {
expect(
padCropRegion({ x: 10, y: 10, width: 20, height: 20 }, { width: 200, height: 200 }, 24),
).toEqual({ x: 0, y: 0, width: 54, height: 54 });
});
});
describe("resolveCropRegion", () => {
it("resolves a selector to its bbox, padded 24px and clamped", async () => {
const page = { evaluate: vi.fn(async () => ({ x: 500, y: 500, width: 100, height: 40 })) };
const region = await resolveCropRegion(
page,
{ kind: "selector", selector: "#headline" },
{ width: 1920, height: 1080 },
);
expect(region).toEqual({ x: 476, y: 476, width: 148, height: 88 });
});
it("crops a region exactly, without padding, when it already fits the canvas", async () => {
const page = { evaluate: vi.fn() };
const region = await resolveCropRegion(
page,
{ kind: "region", region: { x: 100, y: 50, width: 400, height: 300 } },
{ width: 1920, height: 1080 },
);
expect(region).toEqual({ x: 100, y: 50, width: 400, height: 300 });
expect(page.evaluate).not.toHaveBeenCalled();
});
it("throws a clear, loud error when the selector matches nothing", async () => {
const page = { evaluate: vi.fn(async () => null) };
await expect(
resolveCropRegion(
page,
{ kind: "selector", selector: "#missing" },
{ width: 640, height: 360 },
),
).rejects.toThrow("--zoom selector matched no element: #missing");
});
it("returns null when the clamped region is a sliver (element animated off-canvas)", async () => {
// Element slid past the right edge: raw bbox is large, but clamping the
// padded region to the canvas leaves ~1px — a useless crop.
const page = { evaluate: vi.fn(async () => ({ x: 2500, y: 400, width: 600, height: 250 })) };
const region = await resolveCropRegion(
page,
{ kind: "selector", selector: "#gone-by-now" },
{ width: 1920, height: 1080 },
);
expect(region).toBeNull();
});
});
describe("captureRegionCrop", () => {
it("raises deviceScaleFactor for the clip shot, then restores the original viewport", async () => {
const original = { width: 1920, height: 1080, deviceScaleFactor: 1 };
const setViewport = vi.fn(async () => undefined);
const screenshot = vi.fn(async () => new Uint8Array([1, 2, 3]));
const page = { viewport: () => original, setViewport, screenshot };
const region = { x: 10, y: 20, width: 100, height: 50 };
const buffer = await captureRegionCrop(page, region, 3);
expect(setViewport).toHaveBeenNthCalledWith(1, { ...original, deviceScaleFactor: 3 });
expect(screenshot).toHaveBeenCalledWith({
clip: region,
type: "png",
omitBackground: true,
});
expect(setViewport).toHaveBeenNthCalledWith(2, original);
expect(buffer).toBeInstanceOf(Buffer);
expect(Array.from(buffer)).toEqual([1, 2, 3]);
});
it("honors an explicit scale other than the default", async () => {
const original = { width: 800, height: 600 };
const setViewport = vi.fn(async () => undefined);
const screenshot = vi.fn(async () => new Uint8Array());
const page = { viewport: () => original, setViewport, screenshot };
await captureRegionCrop(page, { x: 0, y: 0, width: 10, height: 10 }, 2);
expect(setViewport).toHaveBeenNthCalledWith(1, { ...original, deviceScaleFactor: 2 });
});
});
describe("runFfmpegOnce", () => {
it("returns the process exit code and collected stderr", async () => {
const dir = tempDir();
try {
const script = join(dir, "fail.cjs");
writeFileSync(script, 'process.stderr.write("ffmpeg failed"); process.exit(3);\n');
const result = await runFfmpegOnce(process.execPath, [script], 1000);
expect(result).toEqual({ code: 3, stderr: "ffmpeg failed", timedOut: false });
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("terminates the process when the timeout elapses", async () => {
const dir = tempDir();
try {
const script = join(dir, "hang.cjs");
writeFileSync(script, "setTimeout(() => {}, 10000);\n");
const result = await runFfmpegOnce(process.execPath, [script], 50);
expect(result.timedOut).toBe(true);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
describe("installPageFunctionGuard", () => {
it("defines the keepNames __name shim in the page before any script runs", async () => {
const evaluateOnNewDocument = vi.fn(async (_source: string) => undefined);
await installPageFunctionGuard({ evaluateOnNewDocument });
expect(evaluateOnNewDocument).toHaveBeenCalledOnce();
const source = evaluateOnNewDocument.mock.calls[0]?.[0] ?? "";
expect(source).toContain("self.__name");
// The shim must be a no-op passthrough so wrapped functions stay callable.
const shim = new Function(`const self = {}; ${source}; return self.__name;`)() as (
fn: unknown,
) => unknown;
const marker = () => 42;
expect(shim(marker)).toBe(marker);
});
});
describe("DENSE_GEOMETRY_SEEK_OPTIONS", () => {
it("is genuinely geometry-only — no post-seek settle waits at the 600-sample cap", () => {
// Dense pass must not inherit AUDIT's post-seek waits — geometry is valid synchronously after setTime, and waits multiply by sample count.
expect(DENSE_GEOMETRY_SEEK_OPTIONS.animationFrameSettle).toBe("none");
expect(DENSE_GEOMETRY_SEEK_OPTIONS.waitForFontsMs).toBe(0);
expect(DENSE_GEOMETRY_SEEK_OPTIONS.settleMs).toBe(0);
// AUDIT (the full-settle path used by the base grid) must still carry the waits.
expect(AUDIT_SEEK_OPTIONS.animationFrameSettle).toBe("double");
expect(AUDIT_SEEK_OPTIONS.settleMs).toBeGreaterThan(0);
});
});