diff --git a/packages/cli/src/ui/renderDiagnostic.test.ts b/packages/cli/src/ui/renderDiagnostic.test.ts index 0fdaacf411..f20b24df91 100644 --- a/packages/cli/src/ui/renderDiagnostic.test.ts +++ b/packages/cli/src/ui/renderDiagnostic.test.ts @@ -126,6 +126,13 @@ describe("render diagnostic wire", () => { }), "COMPOSITION_ZERO_DURATION", ], + [ + new CaptureFailure({ + kind: "transient_browser", + message: `[Parallel] Capture failed: Worker 0: [FrameCapture] Composition setup did not finish within 45000ms. ${PRIVATE}`, + }), + "COMPOSITION_SETUP_TIMEOUT", + ], [ new CaptureFailure({ kind: "authoring", message: PRIVATE, pageErrorLines: [PRIVATE] }), "PAGE_ERROR", diff --git a/packages/cli/src/ui/renderDiagnostic.ts b/packages/cli/src/ui/renderDiagnostic.ts index 409e667152..27947589dc 100644 --- a/packages/cli/src/ui/renderDiagnostic.ts +++ b/packages/cli/src/ui/renderDiagnostic.ts @@ -41,6 +41,7 @@ function producerCodeOf(error: unknown): string | undefined { function captureCodeOf(error: unknown, message: string): string | undefined { if (/Composition has zero duration/.test(message)) return "COMPOSITION_ZERO_DURATION"; + if (/Composition setup did not finish/.test(message)) return "COMPOSITION_SETUP_TIMEOUT"; if (!(error instanceof CaptureFailure)) return undefined; return error.pageErrorLines.length > 0 ? "PAGE_ERROR" : `CAPTURE_${error.kind.toUpperCase()}`; } diff --git a/packages/engine/src/services/captureFailure.test.ts b/packages/engine/src/services/captureFailure.test.ts index 4b1dc81f08..3ffa9ad87d 100644 --- a/packages/engine/src/services/captureFailure.test.ts +++ b/packages/engine/src/services/captureFailure.test.ts @@ -17,6 +17,7 @@ describe("classifyCaptureFailure", () => { ["JavaScript heap out of memory", "memory_exhaustion"], ["drawElement self-verify failed", "verification"], ["Composition has zero duration. Runtime ready: true", "authoring"], + ["[FrameCapture] Composition setup did not finish within 45000ms.", "transient_browser"], ["Protocol error (Page.captureScreenshot): Unable to capture screenshot", "transient_browser"], [ "[Parallel] Capture failed: Worker 0: Protocol error (Page.captureScreenshot): Unable to capture screenshot", diff --git a/packages/engine/src/services/captureFailure.ts b/packages/engine/src/services/captureFailure.ts index be67b98c45..5c19250b2d 100644 --- a/packages/engine/src/services/captureFailure.ts +++ b/packages/engine/src/services/captureFailure.ts @@ -55,6 +55,7 @@ const TRANSIENT_BROWSER_ERROR_PATTERNS = [ /ECONNREFUSED/i, /net::ERR_NETWORK_CHANGED/i, /Composition has zero duration[\s\S]*Runtime ready: false/, + /Composition setup did not finish/, // CDP can refuse a capture call outright with this exact wording; timed-out // variants of the same call hit PROTOCOL_TIMEOUT_PATTERNS, checked first. // Anchored to this literal reason (not just the CDP method) so an unrelated, diff --git a/packages/engine/src/services/frameCapture.test.ts b/packages/engine/src/services/frameCapture.test.ts index 6550e951dc..2c3cf0405a 100644 --- a/packages/engine/src/services/frameCapture.test.ts +++ b/packages/engine/src/services/frameCapture.test.ts @@ -673,6 +673,35 @@ describe("buildZeroDurationDiagnostic", () => { expect(message).not.toContain("buildReady"); }); + it("headlines a pending setup as a setup timeout, not a zero duration", () => { + const message = buildZeroDurationDiagnostic( + { ...baseDiag, pendingBuildReadyKeys: ["clockwork"] }, + 45000, + ); + expect(message).toMatch( + /^\[FrameCapture\] Composition setup did not finish within 45000ms\.\n/, + ); + expect(message).not.toContain("zero duration"); + expect(message).toContain("data-duration: 6s"); + expect(message).toContain("requestAnimationFrame callbacks wait until the first frame"); + expect(message).toContain("Await the library's own readiness promise instead"); + }); + + it("does not guess at duration inference while setup is still pending", () => { + const message = buildZeroDurationDiagnostic({ ...baseDiag, hasTimeline: false }); + expect(message).toContain("Composition setup did not finish."); + expect(message).not.toContain("No GSAP timeline registered"); + }); + + it("keeps the zero-duration headline once the runtime is ready", () => { + const message = buildZeroDurationDiagnostic( + { ...baseDiag, renderReady: true, hasTimeline: false, declaredDuration: -1 }, + 45000, + ); + expect(message).toMatch(/^\[FrameCapture\] Composition has zero duration\.\n/); + expect(message).toContain("No GSAP timeline registered"); + }); + it("names a rejected buildReady key separately from a pending one", () => { const message = buildZeroDurationDiagnostic({ ...baseDiag, diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index 6e1b812130..8a92e1c868 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -1889,13 +1889,17 @@ export interface HfDiagnostic { } // fallow-ignore-next-line complexity -export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string { +export function buildZeroDurationDiagnostic(diag: HfDiagnostic, timeoutMs?: number): string { const hints: string[] = []; if (diag.pendingBuildReadyKeys.length > 0) { hints.push( `window.__hf.buildReady never resolved for: ${diag.pendingBuildReadyKeys.join(", ")}. ` + "The runtime holds render-ready until every registered buildReady promise settles. " + - "Find where the composition registers that key and confirm it actually resolves.", + "Find where the composition registers that key and confirm it actually resolves. " + + "During a render, Date and performance.now stay at 0 and requestAnimationFrame " + + "callbacks wait until the first frame, so setup that awaits an animation frame or " + + "the clock never finishes. Await the library's own readiness promise instead (for " + + "Three.js, renderer.compileAsync).", ); } if (diag.rejectedBuildReadyKeys.length > 0) { @@ -1907,7 +1911,7 @@ export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string { if (!diag.hasPlayer) { hints.push("window.__player was never set: the HyperFrames runtime did not initialize."); } - if (!diag.hasTimeline) { + if (diag.renderReady && !diag.hasTimeline) { hints.push( "No GSAP timeline registered (window.__timelines is empty). " + "CSS/WAAPI/Lottie animations are usually auto-detected (the runtime infers " + @@ -1925,8 +1929,12 @@ export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string { if (diag.hasSeek && diag.duration === 0 && diag.renderReady) { hints.push("The runtime finished initializing but reported zero duration. This is permanent."); } + const within = timeoutMs === undefined ? "" : ` within ${timeoutMs}ms`; + const headline = diag.renderReady + ? "Composition has zero duration." + : `Composition setup did not finish${within}.`; return ( - `[FrameCapture] Composition has zero duration.\n` + + `[FrameCapture] ${headline}\n` + ` Runtime ready: ${diag.renderReady}, __player: ${diag.hasPlayer}, ` + `__hf.seek: ${diag.hasSeek}, GSAP timeline: ${diag.hasTimeline}, ` + `data-duration: ${diag.declaredDuration > 0 ? diag.declaredDuration + "s" : "not set"}\n` + @@ -1995,7 +2003,7 @@ export async function pollHfReady( const diag = await evaluateHfDiagnostic(page); if (diag.hasSeek && diag.duration === 0) { - throw new Error(buildZeroDurationDiagnostic(diag)); + throw new Error(buildZeroDurationDiagnostic(diag, timeoutMs)); } throw new Error( `[FrameCapture] window.__hf not ready after ${timeoutMs}ms. ` +