Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 anydiff --git a/packages/producer/src/services/distributed/plan.ts b/packages/producer/src/services/distributed/plan.tsindex 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.tsindex 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.tsindex 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<ProbeStageRheight,needsAlpha,deviceScaleFactor,+ subTimelineWaitMemo,} = input;let { compiled } = input;@@ -347,6 +350,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageRdeviceScaleFactor,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.tsindex 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,