Skip to content

Write HTML. Render video. Built for agents.

perf(engine): wait for a missing composition timeline once per render, not once per browser (#5227)

Miguel Ángele25394d38e0d
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 0ff6cbf4af..4fd3df11fa 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -42,6 +42,7 @@ export type {
CapturePerfSummary,
CaptureWarning,
CaptureWarningCode,
+ SubTimelineWaitMemo,
SubTimelineWaitOutcome,
} from "./types.js";
diff --git a/packages/engine/src/services/frameCapture-staticDedupVerificationPage.test.ts b/packages/engine/src/services/frameCapture-staticDedupVerificationPage.test.ts
index cafcfb93fa..be87ce55d4 100644
--- a/packages/engine/src/services/frameCapture-staticDedupVerificationPage.test.ts
+++ b/packages/engine/src/services/frameCapture-staticDedupVerificationPage.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
import { createStaticVerificationPage, type CaptureSession } from "./frameCapture.js";
describe("createStaticVerificationPage", () => {
@@ -14,6 +14,8 @@ describe("createStaticVerificationPage", () => {
browser: { newPage: vi.fn().mockResolvedValue(verificationPage) },
page: {},
serverUrl: "http://127.0.0.1:3000",
+ subTimelineWaitMemo: {},
+ scriptLoadFailures: [],
options: {
width: 1920,
height: 1080,
@@ -48,4 +50,56 @@ describe("createStaticVerificationPage", () => {
await expect(createStaticVerificationPage(session)).rejects.toThrow("viewport failed");
expect(verificationPage.close).toHaveBeenCalledOnce();
});
+ describe("timeline wait", () => {
+ afterEach(() => vi.useRealTimers());
+
+ // Hosts "main" (registered) and "badge" (never registers); every other page call is ready.
+ function makeVerificationSession(memo: { unregisteredIds?: string[] }, failures: string[]) {
+ const host = (id: string) => ({
+ hasAttribute: () => false,
+ getAttribute: (name: string) => (name === "data-composition-id" ? id : null),
+ });
+ const document = { querySelectorAll: () => [host("main"), host("badge")] };
+ const window = { __timelines: { main: {} } };
+ const verificationPage = {
+ evaluateOnNewDocument: vi.fn().mockResolvedValue(undefined),
+ setViewport: vi.fn().mockResolvedValue(undefined),
+ goto: vi.fn().mockResolvedValue(undefined),
+ evaluate: vi.fn(async (expr: unknown) =>
+ typeof expr === "string" && expr.includes("data-composition-id")
+ ? new Function("document", "window", `return ${expr}`)(document, window)
+ : true,
+ ),
+ close: vi.fn().mockResolvedValue(undefined),
+ };
+ const session = {
+ browser: { newPage: vi.fn().mockResolvedValue(verificationPage) },
+ serverUrl: "http://127.0.0.1:3000",
+ subTimelineWaitMemo: memo,
+ scriptLoadFailures: failures,
+ options: { width: 1920, height: 1080, format: "mp4", skipReadinessVideoIds: [] },
+ } as unknown as CaptureSession;
+ let settled = false;
+ const created = createStaticVerificationPage(session).finally(() => (settled = true));
+ return { created, settled: () => settled };
+ }
+
+ it("does not wait again for a host the render already timed out on", async () => {
+ vi.useFakeTimers();
+ const run = makeVerificationSession({ unregisteredIds: ["badge"] }, []);
+ await vi.advanceTimersByTimeAsync(0);
+ expect(run.settled()).toBe(true);
+ await run.created;
+ });
+
+ it("stops after the script-failure grace instead of the full timeout", async () => {
+ vi.useFakeTimers();
+ const run = makeVerificationSession({}, ["http://127.0.0.1:3000/scene.js"]);
+ await vi.advanceTimersByTimeAsync(1_999);
+ expect(run.settled()).toBe(false);
+ await vi.advanceTimersByTimeAsync(500);
+ expect(run.settled()).toBe(true);
+ await run.created;
+ });
+ });
});
diff --git a/packages/engine/src/services/frameCapture-subTimelineMemo.test.ts b/packages/engine/src/services/frameCapture-subTimelineMemo.test.ts
new file mode 100644
index 0000000000..340de9e56d
--- /dev/null
+++ b/packages/engine/src/services/frameCapture-subTimelineMemo.test.ts
@@ -0,0 +1,135 @@
+// A host that never registers a timeline costs the full wait once per render: later
+// sessions sharing the render's memo report the same timeout without waiting again.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Page } from "puppeteer-core";
+import {
+ type CaptureSession,
+ pollSubCompositionTimelines,
+ waitForSubCompositionTimelines,
+} from "./frameCapture.js";
+import type { SubTimelineWaitMemo } from "../types.js";
+
+const TIMEOUT_MS = 45_000;
+
+// Runs the page-side check scripts against a fake DOM with hosts "main" and "badge".
+function makeDomPage(timelines: Record<string, unknown>): Page {
+ const host = (id: string) => ({
+ hasAttribute: () => false,
+ getAttribute: (name: string) => (name === "data-composition-id" ? id : null),
+ });
+ const document = { querySelectorAll: () => [host("main"), host("badge")] };
+ const window = { __timelines: timelines, __hfForceTimelineRebind: vi.fn() };
+ return {
+ evaluate: vi.fn(async (expr: string) =>
+ new Function("document", "window", `return ${expr}`)(document, window),
+ ),
+ } as unknown as Page;
+}
+
+function makeSession(
+ memo: SubTimelineWaitMemo,
+ extra: Partial<Pick<CaptureSession, "pageErrors" | "scriptLoadFailures" | "vfxFailure">> = {},
+): CaptureSession {
+ return {
+ subTimelineWaitMemo: memo,
+ scriptLoadFailures: [],
+ pageErrors: [],
+ ...extra,
+ } as unknown as CaptureSession;
+}
+
+function track<T>(promise: Promise<T>): { settled: () => boolean; promise: Promise<T> } {
+ let done = false;
+ promise.then(
+ () => (done = true),
+ () => (done = true),
+ );
+ return { settled: () => done, promise };
+}
+
+describe("sub-composition timeline wait memo", () => {
+ beforeEach(() => vi.useFakeTimers());
+ afterEach(() => vi.useRealTimers());
+
+ it("a later session sharing the memo reports the timeout without waiting again", async () => {
+ const memo: SubTimelineWaitMemo = {};
+ const first = makeSession(memo);
+ const firstWait = track(
+ waitForSubCompositionTimelines(first, makeDomPage({ main: {} }), TIMEOUT_MS),
+ );
+ await vi.advanceTimersByTimeAsync(TIMEOUT_MS - 1);
+ expect(firstWait.settled()).toBe(false);
+ await vi.advanceTimersByTimeAsync(TIMEOUT_MS);
+ await firstWait.promise;
+ expect(first.subTimelineWaitOutcome).toBe("timeout");
+ expect(memo.unregisteredIds).toEqual(["badge"]);
+
+ const second = makeSession(memo);
+ const secondWait = track(
+ waitForSubCompositionTimelines(second, makeDomPage({ main: {} }), TIMEOUT_MS),
+ );
+ await vi.advanceTimersByTimeAsync(0);
+ expect(secondWait.settled()).toBe(true);
+ expect(second.subTimelineWaitOutcome).toBe("timeout");
+ expect(second.pendingTimelineIds).toEqual(["badge"]);
+ });
+
+ it("does not remember a timeout whose session saw a page error", async () => {
+ const memo: SubTimelineWaitMemo = {};
+ const session = makeSession(memo, { pageErrors: ["TypeError: d.items is undefined"] });
+ const wait = track(
+ waitForSubCompositionTimelines(session, makeDomPage({ main: {} }), TIMEOUT_MS),
+ );
+ await vi.advanceTimersByTimeAsync(TIMEOUT_MS * 2);
+ await wait.promise;
+ expect(session.subTimelineWaitOutcome).toBe("timeout");
+ expect(memo.unregisteredIds).toBeUndefined();
+ });
+
+ it("does not remember a wait a VFX failure stopped early", async () => {
+ const memo: SubTimelineWaitMemo = {};
+ const session = makeSession(memo, { vfxFailure: "chain failed" });
+ await waitForSubCompositionTimelines(session, makeDomPage({ main: {} }), TIMEOUT_MS);
+ expect(session.subTimelineWaitOutcome).toBe("timeout");
+ expect(memo.unregisteredIds).toBeUndefined();
+ });
+
+ it("a replaying session that sees a failed script load reports a script failure", async () => {
+ const session = makeSession(
+ { unregisteredIds: ["badge"] },
+ { scriptLoadFailures: ["http://127.0.0.1:3000/badge.js"] },
+ );
+ const wait = track(
+ waitForSubCompositionTimelines(session, makeDomPage({ main: {} }), TIMEOUT_MS),
+ );
+ await vi.advanceTimersByTimeAsync(0);
+ expect(wait.settled()).toBe(true);
+ expect(session.subTimelineWaitOutcome).toBe("script_failure");
+ });
+
+ it("still waits out the timeout for hosts the memo does not name", async () => {
+ const onPending = vi.fn();
+ const wait = track(
+ pollSubCompositionTimelines(makeDomPage({}), TIMEOUT_MS, {
+ onPending,
+ knownUnregisteredIds: ["badge"],
+ }),
+ );
+ await vi.advanceTimersByTimeAsync(TIMEOUT_MS - 1);
+ expect(wait.settled()).toBe(false);
+ await vi.advanceTimersByTimeAsync(TIMEOUT_MS);
+ expect(await wait.promise).toBe("timeout");
+ expect(onPending).toHaveBeenCalledWith(["main", "badge"]);
+ });
+
+ it("reports ready and rebinds when a memo host has registered since", async () => {
+ const page = makeDomPage({ main: {}, badge: {} });
+ const outcome = await pollSubCompositionTimelines(page, TIMEOUT_MS, {
+ knownUnregisteredIds: ["badge"],
+ });
+ expect(outcome).toBe("ready");
+ const exprs = (page.evaluate as ReturnType<typeof vi.fn>).mock.calls.map((c) => String(c[0]));
+ expect(exprs.some((e) => e.includes("__hfForceTimelineRebind"))).toBe(true);
+ });
+});
diff --git a/packages/engine/src/services/frameCapture-subTimelinePoll.test.ts b/packages/engine/src/services/frameCapture-subTimelinePoll.test.ts
index 4666832f5c..46acd8518b 100644
--- a/packages/engine/src/services/frameCapture-subTimelinePoll.test.ts
+++ b/packages/engine/src/services/frameCapture-subTimelinePoll.test.ts
@@ -19,7 +19,7 @@ function makeMockPage(evaluateResults: (expr: string) => unknown): Page {
describe("pollSubCompositionTimelines fail-fast", () => {
it("returns ready and forces a timeline rebind when timelines register", async () => {
const page = makeMockPage(() => true);
- const outcome = await pollSubCompositionTimelines(page, 1_000, 10);
+ const outcome = await pollSubCompositionTimelines(page, 1_000, { intervalMs: 10 });
expect(outcome).toBe("ready");
// Second evaluate is the __hfForceTimelineRebind call.
expect((page.evaluate as ReturnType<typeof vi.fn>).mock.calls.length).toBe(2);
@@ -33,9 +33,11 @@ describe("pollSubCompositionTimelines fail-fast", () => {
const outcome = await pollSubCompositionTimelines(
page,
60_000, // full timeout must NOT be waited
- 10,
- () => ["http://localhost/animations.js"],
- 50, // grace
+ {
+ intervalMs: 10,
+ getScriptLoadFailures: () => ["http://localhost/animations.js"],
+ scriptFailureGraceMs: 50,
+ },
);
expect(outcome).toBe("script_failure");
expect(Date.now() - started).toBeLessThan(5_000);
@@ -46,22 +48,21 @@ describe("pollSubCompositionTimelines fail-fast", () => {
expr.includes("__hfForceTimelineRebind") ? undefined : false,
);
const shouldStop = vi.fn(() => true);
- const outcome = await pollSubCompositionTimelines(
- page,
- 60_000,
- 10,
- () => [],
- undefined,
- undefined,
+ const outcome = await pollSubCompositionTimelines(page, 60_000, {
+ intervalMs: 10,
+ getScriptLoadFailures: () => [],
shouldStop,
- );
+ });
expect(outcome).toBe("timeout");
expect(shouldStop).toHaveBeenCalledTimes(1);
});
it("waits the full timeout when timelines are missing but no script failed", async () => {
const page = makeMockPage(() => false);
- const outcome = await pollSubCompositionTimelines(page, 120, 10, () => []);
+ const outcome = await pollSubCompositionTimelines(page, 120, {
+ intervalMs: 10,
+ getScriptLoadFailures: () => [],
+ });
expect(outcome).toBe("timeout");
});
@@ -72,13 +73,11 @@ describe("pollSubCompositionTimelines fail-fast", () => {
calls++;
return calls >= 3; // registers on the 3rd poll tick, inside the grace window
});
- const outcome = await pollSubCompositionTimelines(
- page,
- 60_000,
- 10,
- () => ["http://localhost/late.js"],
- 10_000, // generous grace — registration lands first
- );
+ const outcome = await pollSubCompositionTimelines(page, 60_000, {
+ intervalMs: 10,
+ getScriptLoadFailures: () => ["http://localhost/late.js"],
+ scriptFailureGraceMs: 10_000, // generous grace — registration lands first
+ });
expect(outcome).toBe("ready");
});
});
diff --git a/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts b/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts
index 8789f71a82..6c895bff46 100644
--- a/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts
+++ b/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts
@@ -167,14 +167,11 @@ describe("pollSubCompositionTimelines pending-id reporting", () => {
it("reports the still-unregistered ids to onPending", async () => {
const seen: string[][] = [];
const probe = pageReturning(["scene-2", "scene-5"]);
- const outcome = await pollSubCompositionTimelines(
- probe.page,
- 60,
- 10,
- () => [],
- undefined,
- (ids) => seen.push([...ids]),
- );
+ const outcome = await pollSubCompositionTimelines(probe.page, 60, {
+ intervalMs: 10,
+ getScriptLoadFailures: () => [],
+ onPending: (ids) => seen.push([...ids]),
+ });
expect(outcome).toBe("timeout");
expect(seen).toEqual([["scene-2", "scene-5"]]);
@@ -187,14 +184,11 @@ describe("pollSubCompositionTimelines pending-id reporting", () => {
it("degrades to no ids instead of throwing when the page returns a non-array", async () => {
const seen: string[][] = [];
const probe = pageReturning(false);
- const outcome = await pollSubCompositionTimelines(
- probe.page,
- 60,
- 10,
- () => [],
- undefined,
- (ids) => seen.push([...ids]),
- );
+ const outcome = await pollSubCompositionTimelines(probe.page, 60, {
+ intervalMs: 10,
+ getScriptLoadFailures: () => [],
+ onPending: (ids) => seen.push([...ids]),
+ });
expect(outcome).toBe("timeout");
expect(seen).toEqual([[]]);
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index fb12542a38..0a622eb256 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -88,6 +88,7 @@ import type {
CapturePerfSummary,
CaptureWarning,
HfSeekOptions,
+ SubTimelineWaitMemo,
SubTimelineWaitOutcome,
} from "../types.js";
import { cloneCaptureWarnings } from "./captureWarning.js";
@@ -190,6 +191,8 @@ export interface CaptureSession {
* our console output.
*/
pendingTimelineIds?: string[];
+ /** The render's shared memo when the caller passed one, else this session's own. */
+ subTimelineWaitMemo: SubTimelineWaitMemo;
/** Structured readiness warnings surfaced to the producer's render policy. */
warnings: CaptureWarning[];
initTelemetry?: {
@@ -1525,6 +1528,7 @@ async function constructCaptureSession(
browserConsoleBuffer: [],
scriptLoadFailures: [],
pageErrors: [],
+ subTimelineWaitMemo: sessionOptions.subTimelineWaitMemo ?? {},
warnings: [],
capturePerf: {
frames: 0,
@@ -1762,23 +1766,75 @@ async function pollHfReady(page: Page, timeoutMs: number, intervalMs: number = 1
);
}
-export async function pollSubCompositionTimelines(
+// Enumerated regardless of bail reason, so the warning names every composition still
+// waited on, not only a failed script URL.
+async function listUnregisteredTimelineIds(page: Page): Promise<string[]> {
+ const evaluated = await page.evaluate(`(function() {
+ var hosts = document.querySelectorAll("[data-composition-id]");
+ var timelines = window.__timelines || {};
+ var m = [];
+ for (var i = 0; i < hosts.length; i++) {
+ if (hosts[i].hasAttribute("data-no-timeline")) continue;
+ var id = hosts[i].getAttribute("data-composition-id");
+ if (id && !timelines[id]) m.push(id);
+ }
+ return m;
+ })()`);
+ // Builds a warning, so it must never throw: normalise a loosely typed result.
+ return Array.isArray(evaluated) ? evaluated.map((id) => String(id)) : [];
+}
+
+export async function waitForSubCompositionTimelines(
+ session: CaptureSession,
page: Page,
timeoutMs: number,
- intervalMs: number = 150,
- // Fail-fast hook: when a SCRIPT resource failed to load (404 / request
- // failure), the timeline registration it carried can never arrive — the
- // full-timeout wait buys nothing (measured: a 705-render spike at the 45s
- // setup bucket in 30 days of wild local renders, ~1% of renders, each also
- // shipping silently-broken animations). Once failures are present the poll
- // is cut to `scriptFailureGraceMs` from its start.
- getScriptLoadFailures?: () => readonly string[],
- scriptFailureGraceMs: number = 2_000,
- // Reports the composition ids still unregistered at bail time, so the caller
- // can put them in the structured warning as well as in stderr.
- onPending?: (ids: readonly string[]) => void,
+): Promise<void> {
+ const memo = session.subTimelineWaitMemo;
+ session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, timeoutMs, {
+ getScriptLoadFailures: () => session.scriptLoadFailures,
+ onPending: (ids) => {
+ session.pendingTimelineIds = [...ids];
+ },
+ shouldStop: () => session.vfxFailure !== undefined,
+ knownUnregisteredIds: memo.unregisteredIds,
+ });
+ // Only a clean full-length timeout is replayed: a VFX stop ends early, and page or script
+ // errors must reach each session so it can still classify the wait as a script failure.
+ const cleanTimeout =
+ session.subTimelineWaitOutcome === "timeout" &&
+ session.vfxFailure === undefined &&
+ session.pageErrors.length === 0 &&
+ session.scriptLoadFailures.length === 0;
+ if (cleanTimeout) {
+ memo.unregisteredIds = session.pendingTimelineIds ?? [];
+ }
+}
+
+export interface SubTimelinePollOptions {
+ intervalMs?: number;
+ // Fail-fast: a script resource that failed to load can never register its timeline,
+ // so once failures exist the poll ends `scriptFailureGraceMs` after it started.
+ getScriptLoadFailures?: () => readonly string[];
+ scriptFailureGraceMs?: number;
+ // Receives the ids still unregistered at bail time, for the structured warning.
+ onPending?: (ids: readonly string[]) => void;
// Ends the wait at once; the caller then fails the render for its own reason.
- shouldStop?: () => boolean,
+ shouldStop?: () => boolean;
+ // Ids an earlier session of this render already timed out on: not waited for again.
+ knownUnregisteredIds?: readonly string[];
+}
+
+export async function pollSubCompositionTimelines(
+ page: Page,
+ timeoutMs: number,
+ {
+ intervalMs = 150,
+ getScriptLoadFailures,
+ scriptFailureGraceMs = 2_000,
+ onPending,
+ shouldStop,
+ knownUnregisteredIds = [],
+ }: SubTimelinePollOptions = {},
): Promise<SubTimelineWaitOutcome> {
// Hosts may opt out of the timeline wait with `data-no-timeline` —
// compositions driven purely by CSS animations / rAF (the render-compat
@@ -1788,10 +1844,11 @@ export async function pollSubCompositionTimelines(
var hosts = document.querySelectorAll("[data-composition-id]");
if (hosts.length === 0) return true;
var timelines = window.__timelines || {};
+ var known = ${JSON.stringify(knownUnregisteredIds)};
for (var i = 0; i < hosts.length; i++) {
if (hosts[i].hasAttribute("data-no-timeline")) continue;
var id = hosts[i].getAttribute("data-composition-id");
- if (!id) continue;
+ if (!id || known.indexOf(id) !== -1) continue;
if (!timelines[id]) return false;
}
return true;
@@ -1818,6 +1875,12 @@ export async function pollSubCompositionTimelines(
}
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
+ // Skipped known ids still count: if one is still unregistered, report the timeout again.
+ const pendingIds =
+ ready && knownUnregisteredIds.length === 0 ? [] : await listUnregisteredTimelineIds(page);
+ if (ready && pendingIds.length > 0 && (getScriptLoadFailures?.() ?? []).length > 0) {
+ scriptFailureBail = true;
+ }
// Always force a timeline rebind once sub-composition timelines are
// confirmed present. The previous implementation only called rebind
// when the timeline count grew during the poll, which missed the case
@@ -1825,7 +1888,7 @@ export async function pollSubCompositionTimelines(
// started — leaving child timelines un-nested in the root and causing
// the earliest sub-composition (data-start near 0) to render without
// its GSAP animations.
- if (ready) {
+ if (ready && pendingIds.length === 0) {
await page.evaluate(`(function() {
if (typeof window.__hfForceTimelineRebind === "function") {
window.__hfForceTimelineRebind();
@@ -1833,26 +1896,6 @@ export async function pollSubCompositionTimelines(
})()`);
return "ready";
}
- // Enumerate the still-unregistered composition ids regardless of bail
- // reason — a script-failure bail used to skip this entirely, so a render
- // with multiple sub-compositions only named the failed script URL(s), not
- // which composition(s) it was still waiting on (review).
- const evaluated = await page.evaluate(`(function() {
- var hosts = document.querySelectorAll("[data-composition-id]");
- var timelines = window.__timelines || {};
- var m = [];
- for (var i = 0; i < hosts.length; i++) {
- if (hosts[i].hasAttribute("data-no-timeline")) continue;
- var id = hosts[i].getAttribute("data-composition-id");
- if (id && !timelines[id]) m.push(id);
- }
- return m;
- })()`);
- // This block exists to BUILD A WARNING, so it must never be the thing that
- // throws. `page.evaluate` is loosely typed, and a caller that stubs it (or a
- // runtime that returns nothing here) would turn a blind `as string[]` cast
- // into a TypeError on the diagnostic path. Normalise instead of asserting.
- const pendingIds = Array.isArray(evaluated) ? evaluated.map((id) => String(id)) : [];
onPending?.(pendingIds);
const missing = pendingIds.join(", ");
if (scriptFailureBail) {
@@ -2425,17 +2468,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
await pollHfReady(page, pageReadyTimeout);
logInitPhase("pollHfReady complete");
- session.subTimelineWaitOutcome = await pollSubCompositionTimelines(
- page,
- pageReadyTimeout,
- undefined,
- () => session.scriptLoadFailures,
- undefined,
- (ids) => {
- session.pendingTimelineIds = [...ids];
- },
- () => session.vfxFailure !== undefined,
- );
+ await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
assertVfxIntact(session);
recordSubTimelineWarning(session, pageReadyTimeout);
@@ -2591,17 +2624,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
await pollHfReady(page, pageReadyTimeout);
logInitPhase("pollHfReady complete");
- session.subTimelineWaitOutcome = await pollSubCompositionTimelines(
- page,
- pageReadyTimeout,
- undefined,
- () => session.scriptLoadFailures,
- undefined,
- (ids) => {
- session.pendingTimelineIds = [...ids];
- },
- () => session.vfxFailure !== undefined,
- );
+ await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
assertVfxIntact(session);
recordSubTimelineWarning(session, pageReadyTimeout);
@@ -3389,7 +3412,10 @@ export async function createStaticVerificationPage(session: CaptureSession): Pro
});
await page.evaluate(`window.__hfFlushSync?.()`);
await pollHfReady(page, pageReadyTimeout);
- await pollSubCompositionTimelines(page, pageReadyTimeout);
+ await pollSubCompositionTimelines(page, pageReadyTimeout, {
+ getScriptLoadFailures: () => session.scriptLoadFailures,
+ knownUnregisteredIds: session.subTimelineWaitMemo.unregisteredIds,
+ });
await applyVideoMetadataHints(page, session.options.videoMetadataHints);
const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts
index f09076407b..5b5815137a 100644
--- a/packages/engine/src/types.ts
+++ b/packages/engine/src/types.ts
@@ -15,6 +15,14 @@ import type { MotionBlurOptions } from "./services/motionBlur.js";
*/
export type SubTimelineWaitOutcome = "ready" | "timeout" | "script_failure";
+/**
+ * Shared by every capture session of one render: composition ids whose timeline
+ * wait already timed out, so later sessions report the timeout without waiting again.
+ */
+export interface SubTimelineWaitMemo {
+ unregisteredIds?: readonly string[];
+}
+
export type CaptureWarningCode =
| "media_readiness_timeout"
| "media_load_failed"
@@ -187,6 +195,8 @@ export interface CaptureOptions {
* intrinsic media dimensions.
*/
skipReadinessVideoIds?: readonly string[];
+ /** Pass one object to every session of a render; see `SubTimelineWaitMemo`. */
+ subTimelineWaitMemo?: SubTimelineWaitMemo;
/**
* Render-time variable overrides for the composition. The engine injects
* these as `window.__hfVariables` via `evaluateOnNewDocument` before any
diff --git a/packages/producer/src/services/distributed/plan.ts b/packages/producer/src/services/distributed/plan.ts
index fe7a6db4b8..c701ab3aa4 100644
--- a/packages/producer/src/services/distributed/plan.ts
+++ b/packages/producer/src/services/distributed/plan.ts
@@ -1058,6 +1058,7 @@ export async function buildLocalExecutionPlan(
height,
needsAlpha,
deviceScaleFactor,
+ subTimelineWaitMemo: {},
});
compiled = probeResult.compiled;
job.duration = probeResult.duration;
diff --git a/packages/producer/src/services/distributed/renderChunk.ts b/packages/producer/src/services/distributed/renderChunk.ts
index 0c20ee79ff..e4796427e2 100644
--- a/packages/producer/src/services/distributed/renderChunk.ts
+++ b/packages/producer/src/services/distributed/renderChunk.ts
@@ -827,6 +827,7 @@ export async function renderChunk(
// declare `data-composition-variables` leave this undefined and the
// engine skips the `evaluateOnNewDocument` injection.
variables: encoder.variables,
+ subTimelineWaitMemo: {},
...(videoCaptureBeyondViewport !== undefined
? { captureBeyondViewport: videoCaptureBeyondViewport }
: {}),
diff --git a/packages/producer/src/services/render/stages/probeStage.ts b/packages/producer/src/services/render/stages/probeStage.ts
index 9f6f354576..d382a50676 100644
--- a/packages/producer/src/services/render/stages/probeStage.ts
+++ b/packages/producer/src/services/render/stages/probeStage.ts
@@ -34,6 +34,7 @@ import {
type CaptureOptions,
type CaptureSession,
type EngineConfig,
+ type SubTimelineWaitMemo,
closeCaptureSession,
compositionRequiresWebGpu,
createCaptureSession,
@@ -94,6 +95,7 @@ export interface ProbeStageInput {
height: number;
needsAlpha: boolean;
deviceScaleFactor: number;
+ subTimelineWaitMemo: SubTimelineWaitMemo;
}
const FRAME_BOUNDARY_EPSILON = 1e-3;
@@ -279,6 +281,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageR
height,
needsAlpha,
deviceScaleFactor,
+ subTimelineWaitMemo,
} = input;
let { compiled } = input;
@@ -347,6 +350,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageR
deviceScaleFactor,
motionBlur,
requiresWebGpu: compositionRequiresWebGpu(compiled.html),
+ subTimelineWaitMemo,
};
const PROBE_MAX_ATTEMPTS = 2;
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index d7842e5176..ac6a2cfb67 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -69,6 +69,7 @@ import {
closeCaptureSession,
type CaptureOptions,
type CaptureVideoMetadataHint,
+ type SubTimelineWaitMemo,
type CaptureSession,
type BeforeCaptureHook,
createVideoFrameInjector,
@@ -3266,6 +3267,7 @@ async function executeRenderPipeline(input: {
updateCaptureObservability({ protocolTimeoutMs: scaledProtocolTimeout });
}
+ const subTimelineWaitMemo: SubTimelineWaitMemo = {};
const probeResult = await observeRenderStage(
observability,
"browser_probe",
@@ -3286,6 +3288,7 @@ async function executeRenderPipeline(input: {
height,
needsAlpha,
deviceScaleFactor,
+ subTimelineWaitMemo,
}),
// Browser probe is pre-capture; report `browser calibrating` so a
// slow probe (~64s SwiftShader warm-up on Windows was the reported
@@ -3589,6 +3592,7 @@ async function executeRenderPipeline(input: {
...captureOptions,
videoMetadataHints,
skipReadinessVideoIds: videoReadinessSkipIds,
+ subTimelineWaitMemo,
// Probe-resolved duration: drawElement self-verification derives its
// sample frame indices from this so they land inside the drained range.
compositionDurationSeconds: job.duration,