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 <timeout>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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-11-05 07:41:04 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 7050b9b5bb
commit b98718fe93
6 changed files with 52 additions and 5 deletions
@@ -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",
+1
View File
@@ -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()}`;
}
@@ -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",
@@ -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,
@@ -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,
+13 -5
View File
@@ -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. ` +