Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): capture snapshot --at at the exact requested instant (#4827)
HEOJUNFO8aefd91bf82c
diff --git a/packages/cli/src/capture/captureCompositionFrame.test.ts b/packages/cli/src/capture/captureCompositionFrame.test.tsindex 1fd125fbcc..7c3c0699cb 100644--- a/packages/cli/src/capture/captureCompositionFrame.test.ts+++ b/packages/cli/src/capture/captureCompositionFrame.test.ts@@ -56,7 +56,7 @@ describe("seekCompositionTimeline", () => {expect(waitForFunction).not.toHaveBeenCalled();expect(evaluate).toHaveBeenCalledTimes(4);- expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 1.25, false);+ expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 1.25, false, 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@@ -93,6 +93,17 @@ describe("seekCompositionTimeline", () => {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();@@ -150,7 +161,7 @@ describe("seekCompositionTimeline", () => {expect(waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 500 });expect(evaluate).toHaveBeenCalledTimes(2);- expect(evaluate).toHaveBeenCalledWith(expect.any(Function), 3, true);+ expect(evaluate).toHaveBeenCalledWith(expect.any(Function), 3, true, false);});it("supports layout's ordered double-frame, bounded font, and sleep settles", async () => {@@ -167,7 +178,7 @@ describe("seekCompositionTimeline", () => {await pending;expect(evaluate).toHaveBeenCalledTimes(4);- expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 4, true);+ expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 4, true, false);expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function));expect(evaluate).toHaveBeenNthCalledWith(3, expect.any(Function));expect(evaluate).toHaveBeenNthCalledWith(4, expect.any(Function), 500);diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.tsindex df0b49b4eb..4b0aa39211 100644--- a/packages/cli/src/capture/captureCompositionFrame.ts+++ b/packages/cli/src/capture/captureCompositionFrame.ts@@ -37,6 +37,7 @@ export const DENSE_GEOMETRY_SEEK_OPTIONS = {export interface SeekCompositionTimelineOptions {fallbackToBridgeAndTimelines?: boolean;+ exactTime?: boolean;waitForPreferredSeekTargetMs?: number;animationFrameSettle?: "race" | "double" | "none";waitForFontsMs?: number;@@ -47,13 +48,14 @@ type CompositionPageFunction =| string| (() => unknown)| ((value: number) => unknown)- | ((value: number, fallbackToBridgeAndTimelines: boolean) => unknown);+ | ((value: number, fallbackToBridgeAndTimelines: boolean, exactTime: boolean) => unknown);export interface CompositionEvaluationPage {evaluate(pageFunction: CompositionPageFunction,value?: number,fallbackToBridgeAndTimelines?: boolean,+ exactTime?: boolean,): Promise<unknown>;}@@ -247,7 +249,7 @@ export async function seekCompositionTimeline(await page.evaluate(// Serialized into the page; the seek-target cascade must stay one function.// fallow-ignore-next-line complexity- (t: number, fallbackToBridgeAndTimelines: boolean) => {+ (t: number, fallbackToBridgeAndTimelines: boolean, exactTime: boolean) => {const getProperty = (target: unknown, key: string): unknown => {if ((typeof target !== "object" || target === null) && typeof target !== "function") {return undefined;@@ -271,7 +273,7 @@ export async function seekCompositionTimeline(// Prefer renderSeek because it also runs the runtime's data-start/data-duration// visibility sync; raw timeline seeks leave off-window clips visible to audits.- if (call(renderSeek, player, [safe])) {+ if (call(renderSeek, player, exactTime ? [safe, { exact: true }] : [safe])) {// Preferred runtime target handled the seek.} else if (fallbackToBridgeAndTimelines && call(bridgeSeek, hf, [safe])) {// Producer bridge handled the seek.@@ -294,6 +296,7 @@ export async function seekCompositionTimeline(},timeSeconds,options.fallbackToBridgeAndTimelines === true,+ options.exactTime === true,);await page.evaluate(async () => {diff --git a/packages/cli/src/commands/snapshot.test.ts b/packages/cli/src/commands/snapshot.test.tsindex 7fd4db398c..992de2bbc9 100644--- a/packages/cli/src/commands/snapshot.test.ts+++ b/packages/cli/src/commands/snapshot.test.ts@@ -8,15 +8,19 @@ import { findFFmpeg } from "../browser/ffmpeg.js";import { sourceTimeAt } from "@hyperframes/core";const snapshotState = vi.hoisted(() => ({- openSettledPage: vi.fn(async () => {+ openSettledPage: vi.fn(async (): Promise<unknown> => {throw new Error("browser capture reached");}),+ seek: vi.fn(async (_page: unknown, _time: number, _options?: unknown): Promise<void> => {+ throw new Error("seek reached");+ }),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,}));vi.mock("../utils/staticProjectServer.js", () => ({@@ -150,6 +154,44 @@ describe("snapshot lint preflight", () => {});});+describe("snapshot --at seeks", () => {+ it("asks the runtime for the exact requested instant, not its 30fps grid", async () => {+ const project = mkdtempSync(join(tmpdir(), "hf-snapshot-exact-at-"));+ writeFileSync(+ join(project, "index.html"),+ `<html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="20" data-fps="29.97"><div class="clip" data-start="0" data-duration="20">Visible</div></div></body></html>`,+ );+ const evaluate = vi+ .fn()+ .mockResolvedValueOnce({ loaded: [], errored: [], unused: [] })+ .mockResolvedValueOnce(20)+ .mockResolvedValueOnce(true);+ const close = vi.fn(async () => undefined);+ snapshotState.openSettledPage.mockResolvedValueOnce({+ browser: { close },+ page: { evaluate },+ renderReadyTimedOut: false,+ });+ snapshotState.seek.mockClear();+ const log = vi.spyOn(console, "log").mockImplementation(() => undefined);++ try {+ await expect(+ snapshotCommand.run?.({+ args: { dir: project, at: "19.019018", end: false, output: join(project, "out") },+ } as never),+ ).rejects.toBeDefined();+ expect(snapshotState.seek).toHaveBeenCalledWith(expect.anything(), 19.019018, {+ exactTime: true,+ });+ expect(close).toHaveBeenCalled();+ } finally {+ log.mockRestore();+ rmSync(project, { recursive: true, force: true });+ }+ });+});+describe("resolveSnapshotVideoFrameTime", () => {it("holds a clip ending with the composition on its last decodable frame", () => {expect(diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.tsindex b091b3c6c1..f086ae6b3c 100644--- a/packages/cli/src/commands/snapshot.ts+++ b/packages/cli/src/commands/snapshot.ts@@ -453,7 +453,7 @@ async function captureSnapshots(for (let i = 0; i < positions.length; i++) {const time = positions[i]!;- await seekCompositionTimeline(page, time);+ await seekCompositionTimeline(page, time, { exactTime: true });if (cameraExpr) await page.evaluate(cameraExpr);@@ -684,7 +684,8 @@ export default defineCommand({},at: {type: "string",- description: "Comma-separated timestamps in seconds (e.g., --at 3.0,10.5,18.0)",+ description:+ "Comma-separated timestamps in seconds (e.g., --at 3.0,10.5,18.0). Each is captured at that exact instant, not snapped to a frame.",},timeout: {type: "string",diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.tsindex 76a95cbb2d..dcdf597591 100644--- a/packages/core/src/runtime/init.test.ts+++ b/packages/core/src/runtime/init.test.ts@@ -1023,6 +1023,42 @@ describe("initSandboxRuntimeModular", () => {expect(timeline.time()).toBe(0);});+ describe("issue #4430 sweep on a 29.97fps project", () => {+ // `snapshot --at` times from the issue, with where the 30fps grid floors each one.+ const sweep = [+ { at: 19.019018, grid: 19 },+ { at: 19.05, grid: 571 / 30 },+ ];++ function seekOnNtscProject(at: number, options?: { exact?: boolean }): number {+ const root = document.createElement("div");+ root.setAttribute("data-composition-id", "main");+ root.setAttribute("data-root", "true");+ root.setAttribute("data-start", "0");+ root.setAttribute("data-duration", "20");+ root.setAttribute("data-fps", "29.97");+ root.setAttribute("data-width", "1920");+ root.setAttribute("data-height", "1080");+ document.body.appendChild(root);++ const timeline = createMockTimeline(20);+ window.__timelines = { main: timeline };++ initSandboxRuntimeModular();+ window.__player?.renderSeek(at, options);+ return timeline.time();+ }++ it.each(sweep)("an exact renderSeek to $at lands on $at", ({ at }) => {+ expect(seekOnNtscProject(at, { exact: true })).toBe(at);+ });++ // Frame export never passes `exact`, so its seeks keep flooring onto the frame grid.+ it.each(sweep)("a default renderSeek to $at still floors to $grid", ({ at, grid }) => {+ expect(seekOnNtscProject(at)).toBeCloseTo(grid, 9);+ });+ });+it("uses live child timeline duration when a composition host has no authored duration", () => {const root = document.createElement("div");root.setAttribute("data-composition-id", "main");diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.tsindex e5b60f33d5..8e10b5b0eb 100644--- a/packages/core/src/runtime/init.ts+++ b/packages/core/src/runtime/init.ts@@ -44,7 +44,7 @@ import {import { handleErrorForProxy, handleMetadataForProxy, maybeProxyProactively } from "./mediaProxy";import { probeAndCacheElementVolume, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";import { createPickerModule } from "./picker";-import { createRuntimePlayer, type RuntimePlayerTransport } from "./player";+import { createRuntimePlayer, resolveRenderSeekTime, type RuntimePlayerTransport } from "./player";import { createRuntimeState } from "./state";import {collectRuntimeTimelinePayload,@@ -97,7 +97,7 @@ import {isMemberGroupHidden,} from "../audioGroups";import { clampNativeMediaVolume } from "../audioGain";-import { quantizeSeekTime, quantizeTimeToFrame } from "../inline-scripts/parityContract";+import { quantizeTimeToFrame } from "../inline-scripts/parityContract";import { createManualEditGestureWatch } from "./manualEditGestureWatch";import type {HeldSeek,@@ -3905,15 +3905,15 @@ export function initSandboxRuntimeModular(): void {renderSeek: (timeSeconds, options) => {heldSeek = null;renderCaptureSeekStarted = true;- const quantized = quantizeSeekTime(+ const seekTime = resolveRenderSeekTime(Math.max(0, Number(timeSeconds) || 0),state.canonicalFps,- options?.subFrameDivisions,+ options,);webAudio.stopAll();clock.detachAudioSource();if (clock.isPlaying()) clock.pause();- clock.seek(quantized);+ clock.seek(seekTime);state.currentTime = clock.now();state.isPlaying = false;state.mediaForceSyncNextTick = true;diff --git a/packages/core/src/runtime/player.test.ts b/packages/core/src/runtime/player.test.tsindex fde3b30e61..0a29309172 100644--- a/packages/core/src/runtime/player.test.ts+++ b/packages/core/src/runtime/player.test.ts@@ -709,6 +709,15 @@ describe("renderSeek sub-frame grid (issue #4010 motion blur)", () => {expect(timeline.time()).toBe(10 / 30);});+ it("lands on the requested instant, off every frame grid, for an exact seek", () => {+ const timeline = createMockTimeline();+ const player = createRuntimePlayer(createMockDeps(timeline));++ player.renderSeek(10 / 30 + 0.017, { exact: true });++ expect(timeline.time()).toBe(10 / 30 + 0.017);+ });+it("suppresses timeline events on a sub-frame sample seek", () => {const timeline = createMockTimeline();const player = createRuntimePlayer(createMockDeps(timeline));diff --git a/packages/core/src/runtime/player.ts b/packages/core/src/runtime/player.tsindex 7217dcea47..89a13e665d 100644--- a/packages/core/src/runtime/player.ts+++ b/packages/core/src/runtime/player.ts@@ -83,13 +83,24 @@ function forEachSiblingTimeline(}}+export function resolveRenderSeekTime(+ timeSeconds: number,+ canonicalFps: number,+ options?: RuntimeSeekOptions,+): number {+ if (options?.exact === true) {+ return Number.isFinite(timeSeconds) && timeSeconds > 0 ? timeSeconds : 0;+ }+ return quantizeSeekTime(timeSeconds, canonicalFps, options?.subFrameDivisions);+}+function seekTimelineDeterministically(timeline: RuntimeTimelineLike,timeSeconds: number,canonicalFps: number,options?: RuntimeSeekOptions,): number {- const quantized = quantizeSeekTime(timeSeconds, canonicalFps, options?.subFrameDivisions);+ const quantized = resolveRenderSeekTime(timeSeconds, canonicalFps, options);const suppressEvents = options?.suppressEvents === true;safeVoid(timeline, "pause");if (typeof timeline.totalTime === "function") {@@ -248,11 +259,7 @@ export function createRuntimePlayer(deps: PlayerDeps): RuntimePlayer {activateSiblingTimelines(deps.getTimelineRegistry?.(), timeline);return seekTimelineDeterministically(timeline, timeSeconds, canonicalFps, options);})()- : quantizeSeekTime(- Math.max(0, Number(timeSeconds) || 0),- canonicalFps,- options?.subFrameDivisions,- );+ : resolveRenderSeekTime(Math.max(0, Number(timeSeconds) || 0), canonicalFps, options);deps.onDeterministicSeek(quantized, options);deps.setIsPlaying(false);deps.onSyncMedia(quantized, false);diff --git a/packages/core/src/runtime/types.ts b/packages/core/src/runtime/types.tsindex eecdda6ce4..1c38578372 100644--- a/packages/core/src/runtime/types.ts+++ b/packages/core/src/runtime/types.ts@@ -286,6 +286,7 @@ export type RuntimeSeekOptions = {* engine's sub-frame tick count so a fractional sample time survives quantization.*/subFrameDivisions?: number;+ exact?: boolean;};export type RuntimeTimelineChildLike = {diff --git a/packages/engine/src/services/frameCapture-motionBlur.test.ts b/packages/engine/src/services/frameCapture-motionBlur.test.tsindex 15c7db60bd..320d6c3204 100644--- a/packages/engine/src/services/frameCapture-motionBlur.test.ts+++ b/packages/engine/src/services/frameCapture-motionBlur.test.ts@@ -28,13 +28,14 @@ interface RecordedSeek {time: number;suppressEvents?: boolean;subFrameDivisions?: number;+ exact?: boolean;}function installPageGlobals(seeks: RecordedSeek[]): void {const root = globalThis as Record<string, unknown>;root.window = {__hf: {- seek: (time: number, options?: { suppressEvents?: boolean; subFrameDivisions?: number }) => {+ seek: (time: number, options?: Omit<RecordedSeek, "time">) => {seeks.push({ time, ...options });},},@@ -175,6 +176,23 @@ describe("sub-frame accumulation reaches the page with distinct sample times", (});});+describe("frame export keeps its frame grid (issue #4430)", () => {+ // `exact` is the snapshot-only opt-out of the runtime's seek quantization. Export must+ // never send it, or frames would land between grid points instead of on them.+ it("never asks for an exact seek with motion blur off", async () => {+ await captureFrameToBuffer(makeSession({ motionBlur: undefined }), 10, 10 / 30);++ expect(seeks).toEqual([{ time: 10 / 30 }]);+ });++ it("never asks for an exact seek on any motion-blur sample", async () => {+ await captureFrameToBuffer(makeSession(), 10, 10 / 30);++ expect(seeks.length).toBeGreaterThan(1);+ expect(seeks.every((s) => !("exact" in s))).toBe(true);+ });+});+describe("accumulation composes with static-frame dedup", () => {// 720 degrees is the widest shutter After Effects offers, and the AD5 reference export// uses it, so it is the case a reader is most likely to check the frame ranges against.diff --git a/packages/parsers/src/types.ts b/packages/parsers/src/types.tsindex d6588ae977..9f964a7ff6 100644--- a/packages/parsers/src/types.ts+++ b/packages/parsers/src/types.ts@@ -439,7 +439,7 @@ export interface PlayerAPI {disableRenderMode(): void;renderSeek(time: number,- options?: { suppressEvents?: boolean; subFrameDivisions?: number },+ options?: { suppressEvents?: boolean; subFrameDivisions?: number; exact?: boolean },): void;getElementVisibility(elementId: string): { visible: boolean; opacity?: number };getVisibleElements(): Array<{ id: string; tagName: string; start: number; end: number }>;