Skip to content

Write HTML. Render video. Built for agents.

21.0 KB
Raw Blame
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
  AUDIT_SEEK_OPTIONS,
  DENSE_GEOMETRY_SEEK_OPTIONS,
  SCREENSHOT_SEEK_OPTIONS,
  captureRegionCrop,
  clampCropRegion,
  installPageFunctionGuard,
  padCropRegion,
  parseZoomTarget,
  resolveCliChromeGpuMode,
  resolveCropRegion,
  runFfmpegOnce,
  seekCompositionTimeline,
  seekCompositionTimelineOnly,
  settleCompositionSeek,
  waitForRuntimeReady,
  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?: Parameters<CompositionSeekPage["evaluate"]>[1],
      _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("waitForRuntimeReady", () => {
  it("waits for the runtime's render-ready flag and reports a timeout as not ready", async () => {
    const { waitForFunction, evaluate } = fakeSeekPage();

    await expect(waitForRuntimeReady({ waitForFunction, evaluate }, 123)).resolves.toBe(true);
    expect(waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 123 });
    const ready = waitForFunction.mock.calls[0]![0];
    vi.stubGlobal("window", { __timelines: {} });
    expect(ready()).toBe(false);
    vi.stubGlobal("window", { __timelines: {}, __renderReady: true });
    expect(ready()).toBe(true);

    waitForFunction.mockRejectedValueOnce(new Error("Waiting failed: 1ms exceeded"));
    await expect(waitForRuntimeReady({ waitForFunction, evaluate }, 1)).resolves.toBe(false);
  });

  it("fails with the runtime's start-up error instead of reporting the page ready", async () => {
    const { waitForFunction, evaluate } = fakeSeekPage();
    const startupError = "HyperFrames runtime failed: TypeError: boom";
    evaluate.mockResolvedValue(startupError);

    const ready = waitForFunction.mock.calls.length;
    await expect(waitForRuntimeReady({ waitForFunction, evaluate }, 123)).rejects.toThrow(
      startupError,
    );
    const predicate = waitForFunction.mock.calls[ready]![0];
    vi.stubGlobal("window", { __hfStartupError: startupError });
    expect(predicate()).toBe(true);
    vi.stubGlobal("window", { __hfStartupError: { message: "not a string" } });
    expect(predicate()).toBe(false);
  });

  it("is what layout, motion-shot and validate wait on before they sample the page", () => {
    const commands = join(dirname(fileURLToPath(import.meta.url)), "../commands");
    const firstSample = {
      layout: "getCompositionDuration(page)",
      motionShot: "installSeekHelper(page)",
      validate: "auditClipDurations(page,",
    };
    for (const [name, sample] of Object.entries(firstSample)) {
      const source = readFileSync(join(commands, `${name}.ts`), "utf8");
      const wait = source.indexOf("await waitForRuntimeReady(page, ");
      expect(wait, name).toBeGreaterThan(-1);
      expect(source.indexOf(sample), name).toBeGreaterThan(wait);
      expect(source, name).not.toContain("__timelines?: unknown }).__timelines");
    }
  });
});

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, false, false);
    expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function), { videoFrames: true });
    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), { ms: 500, frames: 1 });
  });

  it("can seek without finishing the frame, so overlays land before a blurred frame is drawn", async () => {
    const { page, evaluate } = fakeSeekPage();

    await seekCompositionTimelineOnly(page, 1.25);
    expect(evaluate).toHaveBeenCalledTimes(1);
    expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 1.25, false, false, false);

    await settleCompositionSeek(page);
    expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function), { videoFrames: true });
    expect(evaluate).toHaveBeenCalledTimes(4);
  });

  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();
  });

  it("asks renderSeek for the exact instant when exactTime is set", async () => {
    const { page, evaluate } = fakeSeekPage();
    const renderSeek = vi.fn();
    vi.stubGlobal("window", { __player: { renderSeek } });

    await seekCompositionTimeline(page, 19.019018, { exactTime: true });
    runBrowserSeek(evaluate);

    expect(renderSeek).toHaveBeenCalledWith(19.019018, { exact: true });
  });

  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, false, false);
  });

  it("checks fonts on the double settle's second frame instead of waiting a third", 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(3);
    expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 4, true, false, false);
    expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function), { videoFrames: true });
    expect(evaluate).toHaveBeenNthCalledWith(3, expect.any(Function), { ms: 500, frames: 2 });

    const frames: (() => void)[] = [];
    const statusReadAt: number[] = [];
    let frame = 0;
    vi.stubGlobal("requestAnimationFrame", (callback: () => void) => frames.push(callback));
    vi.stubGlobal("document", {
      body: { offsetHeight: 0 },
      fonts: {
        get status() {
          statusReadAt.push(frame);
          return "loaded";
        },
        ready: Promise.resolve(),
      },
    });
    const fontWait = evaluate.mock.calls[2]?.[0];
    if (typeof fontWait !== "function") throw new Error("Expected the font wait page function");
    const waited = Reflect.apply(fontWait, undefined, [{ ms: 500, frames: 2 }]);
    while (frames.length > 0) {
      frame += 1;
      frames.shift()?.();
    }
    await waited;
    expect(statusReadAt).toEqual([2]);
  });

  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 new Promise((resolve) => setTimeout(resolve, 0));
    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("resolveManagedGpuMode(");
    expect(captureSource).toContain("resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu)");
    expect(layoutSource).toContain("resolveManagedGpuMode(");
    expect(layoutSource).toContain("resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu)");
  });
});

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("SCREENSHOT_SEEK_OPTIONS", () => {
  it("waits for image decodes before a screenshot, not for a fixed sleep", async () => {
    vi.useFakeTimers();
    const { page, evaluate } = fakeSeekPage();
    let done = false;
    void seekCompositionTimeline(page, 2, SCREENSHOT_SEEK_OPTIONS).then(() => {
      done = true;
    });
    await vi.advanceTimersByTimeAsync(0);

    expect(done).toBe(true);
    expect(evaluate).toHaveBeenLastCalledWith(
      expect.any(Function),
      SCREENSHOT_SEEK_OPTIONS.waitForImagesMs,
    );
  });
});

describe("DENSE_GEOMETRY_SEEK_OPTIONS", () => {
  // A 79 s project of 1080p H.264 clips: each of the 600 dense seeks waited ~185 ms for a video frame it never reads,
  // so `check` ran past its deadline. Frame sources and hf-seek work can move the DOM, so those still hold it.
  it("skips only the seek barrier's video-frame holds, while the audit seek waits for all", async () => {
    const barrierCalls = async (options: Parameters<typeof seekCompositionTimeline>[2]) => {
      const { page, evaluate } = fakeSeekPage();
      const barrier = vi.fn(async (_options?: { videoFrames?: boolean }) => {});
      vi.stubGlobal("window", { __hfWaitForSeekCompletion: barrier });
      evaluate.mockImplementation(async (pageFunction, value) =>
        typeof pageFunction === "function" && typeof value === "object"
          ? Reflect.apply(pageFunction, undefined, [value])
          : undefined,
      );
      await seekCompositionTimeline(page, 3, options);
      return barrier.mock.calls;
    };

    expect(await barrierCalls(DENSE_GEOMETRY_SEEK_OPTIONS)).toEqual([[{ videoFrames: false }]]);
    expect(await barrierCalls(AUDIT_SEEK_OPTIONS)).toEqual([[{ videoFrames: true }]]);
  });

  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 base grid) keeps the frame and font waits; only a screenshot seek adds the paint sleep.
    expect(AUDIT_SEEK_OPTIONS.animationFrameSettle).toBe("double");
    expect("settleMs" in AUDIT_SEEK_OPTIONS).toBe(false);
    expect(SCREENSHOT_SEEK_OPTIONS.waitForImagesMs).toBeGreaterThan(0);
    expect("settleMs" in SCREENSHOT_SEEK_OPTIONS).toBe(false);
  });
});