mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
* 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
422 lines
15 KiB
TypeScript
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);
|
|
});
|
|
});
|