feat(producer,studio): wire capture motion blur into renders and Studio

packages/cli/src/capture/captureCompositionFrame.test.ts

@@ -16,6 +16,8 @@ import {
   resolveCropRegion,
   runFfmpegOnce,
   seekCompositionTimeline,
+  seekCompositionTimelineOnly,
+  settleCompositionSeek,
   waitForRuntimeReady,
   type CompositionSeekPage,
 } from "./captureCompositionFrame.js";
@@ -116,6 +118,18 @@ describe("seekCompositionTimeline", () => {
     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();
 
@@ -285,7 +299,7 @@ describe("seekCompositionTimeline", () => {
     }).then(() => {
       settled = true;
     });
-    await Promise.resolve();
+    await new Promise((resolve) => setTimeout(resolve, 0));
     expect(evaluateCall).toBe(2);
     expect(settled).toBe(false);
     completeGpu?.();

packages/cli/src/capture/captureCompositionFrame.ts

@@ -510,6 +510,16 @@ export async function seekCompositionTimeline(
   page: CompositionSeekPage,
   timeSeconds: number,
   options: SeekCompositionTimelineOptions = {},
+): Promise<void> {
+  await seekCompositionTimelineOnly(page, timeSeconds, options);
+  await settleCompositionSeek(page, options);
+}
+
+/** The seek alone; `settleCompositionSeek` must follow, which is what finishes a blurred frame. */
+export async function seekCompositionTimelineOnly(
+  page: CompositionSeekPage,
+  timeSeconds: number,
+  options: SeekCompositionTimelineOptions = {},
 ): Promise<void> {
   if (options.waitForPreferredSeekTargetMs !== undefined) {
     await waitForPreferredSeekTarget(page, options.waitForPreferredSeekTargetMs);
@@ -522,7 +532,12 @@ export async function seekCompositionTimeline(
     options.exactTime === true,
     options.skipWebglDraws === true,
   );
+}
 
+export async function settleCompositionSeek(
+  page: CompositionSeekPage,
+  options: SeekCompositionTimelineOptions = {},
+): Promise<void> {
   await page.evaluate(
     async (barrier: SeekBarrierOptions) => {
       const waitForCompletion = Reflect.get(window, "__hfWaitForSeekCompletion");

packages/cli/src/commands/snapshot-contactSheet.test.ts

@@ -31,6 +31,8 @@ vi.mock("../capture/captureCompositionFrame.js", async (importOriginal) => ({
     renderReadyTimedOut: false,
   })),
   seekCompositionTimeline: capture.seek,
+  seekCompositionTimelineOnly: capture.seek,
+  settleCompositionSeek: vi.fn(async () => undefined),
 }));
 
 vi.mock("../utils/staticProjectServer.js", () => ({

packages/cli/src/commands/snapshot.test.ts

@@ -14,13 +14,15 @@ const snapshotState = vi.hoisted(() => ({
   seek: vi.fn(async (_page: unknown, _time: number, _options?: unknown): Promise<void> => {
     throw new Error("seek reached");
   }),
+  settle: vi.fn(async (_page: unknown, _options?: unknown): Promise<void> => undefined),
   closeServer: vi.fn(async () => undefined),
 }));
 
 vi.mock("../capture/captureCompositionFrame.js", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../capture/captureCompositionFrame.js")>()),
   openSettledCompositionPage: snapshotState.openSettledPage,
-  seekCompositionTimeline: snapshotState.seek,
+  seekCompositionTimelineOnly: snapshotState.seek,
+  settleCompositionSeek: snapshotState.settle,
 }));
 
 vi.mock("../utils/staticProjectServer.js", () => ({
@@ -192,6 +194,57 @@ describe("snapshot --at seeks", () => {
   });
 });
 
+describe("snapshot video overlays and the blurred frame", () => {
+  // The runtime draws a blurred frame when the seek settles, so the video <img> overlays must
+  // be in by then (the engine injects before it waits, too).
+  it("settles the seek only after the video overlays were read and injected", async () => {
+    const project = mkdtempSync(join(tmpdir(), "hf-snapshot-blur-order-"));
+    writeFileSync(
+      join(project, "index.html"),
+      `<html><body><div data-composition-id="main" data-width="640" data-height="360" data-start="0" data-duration="3" data-motion-blur="on"><div class="clip" data-start="0" data-duration="3">Visible</div></div></body></html>`,
+    );
+    const log: string[] = [];
+    let calls = 0;
+    const evaluate = vi.fn(async () => {
+      calls += 1;
+      if (calls === 1) return { loaded: [], errored: [], unused: [] };
+      if (calls === 2) return 3;
+      if (calls === 3) return true;
+      if (calls === 4) {
+        log.push("read videos");
+        return [];
+      }
+      return undefined;
+    });
+    snapshotState.openSettledPage.mockResolvedValueOnce({
+      browser: { close: vi.fn(async () => undefined) },
+      page: { evaluate },
+      renderReadyTimedOut: false,
+    });
+    snapshotState.seek.mockReset();
+    snapshotState.seek.mockImplementation(async () => {
+      log.push("seek");
+    });
+    snapshotState.settle.mockClear();
+    snapshotState.settle.mockImplementation(async () => {
+      log.push("settle");
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    try {
+      await expect(
+        snapshotCommand.run?.({
+          args: { dir: project, at: "1", end: false, output: join(project, "out") },
+        } as never),
+      ).rejects.toBeDefined();
+      expect(log).toEqual(["seek", "read videos", "settle"]);
+    } finally {
+      logSpy.mockRestore();
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("resolveSnapshotVideoFrameTime", () => {
   it("holds a clip ending with the composition on its last decodable frame", () => {
     expect(

packages/cli/src/commands/snapshot.ts

@@ -31,7 +31,8 @@ import {
   parseZoomTarget,
   resolveCropRegion,
   runFfmpegOnce,
-  seekCompositionTimeline,
+  seekCompositionTimelineOnly,
+  settleCompositionSeek,
   type ZoomTarget,
 } from "../capture/captureCompositionFrame.js";
 import {
@@ -748,7 +749,8 @@ async function captureSnapshots(
       for (let i = 0; i < positions.length; i++) {
         const time = positions[i]!;
 
-        await seekCompositionTimeline(page, time, { exactTime: true });
+        const seekOptions = { exactTime: true };
+        await seekCompositionTimelineOnly(page, time, seekOptions);
 
         if (cameraExpr) await page.evaluate(cameraExpr);
 
@@ -892,6 +894,7 @@ async function captureSnapshots(
           }
         }
 
+        await settleCompositionSeek(page, seekOptions);
         await recaptureSnapshotComposite(page);
 
         const timeLabel = formatSnapshotTimestamp(time);

packages/cli/src/server/studioServer.renderBrowser.test.ts

@@ -103,3 +103,37 @@ describe("Studio render GPU encoding", () => {
     expect(mocks.createRenderJob).toHaveBeenCalledWith(expect.objectContaining({ useGpu: true }));
   });
 });
+
+describe("Studio render motion blur", () => {
+  it("hands the route's pageMotionBlur to the job", async () => {
+    mocks.resolveRenderBrowser.mockResolvedValue({
+      executablePath: "/opt/chrome",
+      source: "cache",
+    });
+
+    startStudioRender({ pageMotionBlur: "off" });
+    await vi.waitFor(() => expect(mocks.createRenderJob).toHaveBeenCalledTimes(1), {
+      timeout: 10_000,
+    });
+
+    expect(mocks.createRenderJob).toHaveBeenCalledWith(
+      expect.objectContaining({ pageMotionBlur: "off" }),
+    );
+  });
+
+  it("sends none when the route sent none", async () => {
+    mocks.resolveRenderBrowser.mockResolvedValue({
+      executablePath: "/opt/chrome",
+      source: "cache",
+    });
+
+    startStudioRender();
+    await vi.waitFor(() => expect(mocks.createRenderJob).toHaveBeenCalledTimes(1), {
+      timeout: 10_000,
+    });
+
+    expect(mocks.createRenderJob).not.toHaveBeenCalledWith(
+      expect.objectContaining({ pageMotionBlur: expect.anything() }),
+    );
+  });
+});

packages/cli/src/server/studioServer.ts

@@ -642,6 +642,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
             ...(opts.videoFrameFormat ? { videoFrameFormat: opts.videoFrameFormat } : {}),
             ...(opts.hdrMode ? { hdrMode: opts.hdrMode } : {}),
             ...(opts.useGpu ? { useGpu: true } : {}),
+            ...(opts.pageMotionBlur ? { pageMotionBlur: opts.pageMotionBlur } : {}),
           });
           renderJob = job;
           const onProgress = (j: { progress: number; currentStage?: string }) => {