From b98718fe93b8798e29bc755049ef56729bdc1582 Mon Sep 17 00:00:00 2001 From: James Russo Date: Thu, 5 Nov 2026 07:41:04 +0000 Subject: [PATCH] fix(engine): report a pending setup as a setup timeout, not zero duration (#7211) * fix(engine): headline a pending setup as a setup timeout, not zero duration When the runtime never reaches render-ready, __hf.duration reads 0 because the bridge masks it, so pollHfReady's timeout reported "Composition has zero duration" even for compositions with a declared data-duration whose window.__hf.buildReady promise was still pending. Headline that case as "Composition setup did not finish within ms", skip the duration inference hint that cannot apply yet, and note that the render clock stays at 0 until the first frame. Keep its transient retry classification and give it its own CLI diagnostic code. Co-Authored-By: Claude Opus 5.5 (1M context) * fix(engine): name animation frames in the setup-timeout hint Setup that awaits requestAnimationFrame hits the same render-clock rule as setup that waits on Date or performance.now: frames only fire on a seek, and the first seek waits for setup. Say so, and point at the waits that work. Co-Authored-By: Claude Opus 5.5 (1M context) * fix(engine): stop suggesting scheduler.yield() for setup waits Chrome runs scheduler.yield() continuations ahead of ordinary tasks, so a setup loop that polls with it starves the setTimeout-driven work it waits on (Three's compileAsync polls with setTimeout(10)) and never finishes. Plain headless Chrome 152 hangs on a ten-line page that does exactly that. Point authors at setTimeout and say why yield-polling does not work. Co-Authored-By: Claude Opus 5.5 (1M context) * fix(engine): point setup waits at the library's readiness promise HyperFrames guidance is no system timers, so the hint should not tell authors to wait with setTimeout. Point them at the library's own readiness promise (Three.js renderer.compileAsync) and keep the warning about scheduler.yield() polling loops. Co-Authored-By: Claude Opus 5.5 (1M context) * fix(engine): keep the setup-timeout hint to what it can diagnose A scheduler.yield() polling loop starves the page, so the readiness poll never returns and the render reports a capture stall instead of this message. Drop that sentence; the hint covers animation-frame and clock waits only. Co-Authored-By: Claude Opus 5.5 (1M context) --------- Co-authored-by: Claude Opus 5.5 (1M context) --- packages/cli/src/ui/renderDiagnostic.test.ts | 7 +++++ packages/cli/src/ui/renderDiagnostic.ts | 1 + .../src/services/captureFailure.test.ts | 1 + .../engine/src/services/captureFailure.ts | 1 + .../engine/src/services/frameCapture.test.ts | 29 +++++++++++++++++++ packages/engine/src/services/frameCapture.ts | 18 ++++++++---- 6 files changed, 52 insertions(+), 5 deletions(-) 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. ` +