Skip to content

Commit e353a6d

Browse files
jrusso1020claude
andcommitted
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) <[email protected]>
1 parent 9820703 commit e353a6d

6 files changed

Lines changed: 49 additions & 5 deletions

File tree

‎packages/cli/src/ui/renderDiagnostic.test.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,13 @@ describe("render diagnostic wire", () => {
126126
}),
127127
"COMPOSITION_ZERO_DURATION",
128128
],
129+
[
130+
new CaptureFailure({
131+
kind: "transient_browser",
132+
message: `[Parallel] Capture failed: Worker 0: [FrameCapture] Composition setup did not finish within 45000ms. ${PRIVATE}`,
133+
}),
134+
"COMPOSITION_SETUP_TIMEOUT",
135+
],
129136
[
130137
new CaptureFailure({ kind: "authoring", message: PRIVATE, pageErrorLines: [PRIVATE] }),
131138
"PAGE_ERROR",

‎packages/cli/src/ui/renderDiagnostic.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ function producerCodeOf(error: unknown): string | undefined {
4141

4242
function captureCodeOf(error: unknown, message: string): string | undefined {
4343
if (/Composition has zero duration/.test(message)) return "COMPOSITION_ZERO_DURATION";
44+
if (/Composition setup did not finish/.test(message)) return "COMPOSITION_SETUP_TIMEOUT";
4445
if (!(error instanceof CaptureFailure)) return undefined;
4546
return error.pageErrorLines.length > 0 ? "PAGE_ERROR" : `CAPTURE_${error.kind.toUpperCase()}`;
4647
}

‎packages/engine/src/services/captureFailure.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ describe("classifyCaptureFailure", () => {
1717
["JavaScript heap out of memory", "memory_exhaustion"],
1818
["drawElement self-verify failed", "verification"],
1919
["Composition has zero duration. Runtime ready: true", "authoring"],
20+
["[FrameCapture] Composition setup did not finish within 45000ms.", "transient_browser"],
2021
["Protocol error (Page.captureScreenshot): Unable to capture screenshot", "transient_browser"],
2122
[
2223
"[Parallel] Capture failed: Worker 0: Protocol error (Page.captureScreenshot): Unable to capture screenshot",

‎packages/engine/src/services/captureFailure.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ const TRANSIENT_BROWSER_ERROR_PATTERNS = [
5555
/ECONNREFUSED/i,
5656
/net::ERR_NETWORK_CHANGED/i,
5757
/Composition has zero duration[\s\S]*Runtime ready: false/,
58+
/Composition setup did not finish/,
5859
// CDP can refuse a capture call outright with this exact wording; timed-out
5960
// variants of the same call hit PROTOCOL_TIMEOUT_PATTERNS, checked first.
6061
// Anchored to this literal reason (not just the CDP method) so an unrelated,

‎packages/engine/src/services/frameCapture.test.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -673,6 +673,34 @@ describe("buildZeroDurationDiagnostic", () => {
673673
expect(message).not.toContain("buildReady");
674674
});
675675

676+
it("headlines a pending setup as a setup timeout, not a zero duration", () => {
677+
const message = buildZeroDurationDiagnostic(
678+
{ ...baseDiag, pendingBuildReadyKeys: ["clockwork"] },
679+
45000,
680+
);
681+
expect(message).toMatch(
682+
/^\[FrameCapture\] Composition setup did not finish within 45000ms\.\n/,
683+
);
684+
expect(message).not.toContain("zero duration");
685+
expect(message).toContain("data-duration: 6s");
686+
expect(message).toContain("Date and performance.now stay at 0 until the first frame");
687+
});
688+
689+
it("does not guess at duration inference while setup is still pending", () => {
690+
const message = buildZeroDurationDiagnostic({ ...baseDiag, hasTimeline: false });
691+
expect(message).toContain("Composition setup did not finish.");
692+
expect(message).not.toContain("No GSAP timeline registered");
693+
});
694+
695+
it("keeps the zero-duration headline once the runtime is ready", () => {
696+
const message = buildZeroDurationDiagnostic(
697+
{ ...baseDiag, renderReady: true, hasTimeline: false, declaredDuration: -1 },
698+
45000,
699+
);
700+
expect(message).toMatch(/^\[FrameCapture\] Composition has zero duration\.\n/);
701+
expect(message).toContain("No GSAP timeline registered");
702+
});
703+
676704
it("names a rejected buildReady key separately from a pending one", () => {
677705
const message = buildZeroDurationDiagnostic({
678706
...baseDiag,

‎packages/engine/src/services/frameCapture.ts‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1889,13 +1889,15 @@ export interface HfDiagnostic {
18891889
}
18901890

18911891
// fallow-ignore-next-line complexity
1892-
export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string {
1892+
export function buildZeroDurationDiagnostic(diag: HfDiagnostic, timeoutMs?: number): string {
18931893
const hints: string[] = [];
18941894
if (diag.pendingBuildReadyKeys.length > 0) {
18951895
hints.push(
18961896
`window.__hf.buildReady never resolved for: ${diag.pendingBuildReadyKeys.join(", ")}. ` +
18971897
"The runtime holds render-ready until every registered buildReady promise settles. " +
1898-
"Find where the composition registers that key and confirm it actually resolves.",
1898+
"Find where the composition registers that key and confirm it actually resolves. " +
1899+
"During a render, Date and performance.now stay at 0 until the first frame, so setup " +
1900+
"that waits for the clock to advance never finishes.",
18991901
);
19001902
}
19011903
if (diag.rejectedBuildReadyKeys.length > 0) {
@@ -1907,7 +1909,7 @@ export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string {
19071909
if (!diag.hasPlayer) {
19081910
hints.push("window.__player was never set: the HyperFrames runtime did not initialize.");
19091911
}
1910-
if (!diag.hasTimeline) {
1912+
if (diag.renderReady && !diag.hasTimeline) {
19111913
hints.push(
19121914
"No GSAP timeline registered (window.__timelines is empty). " +
19131915
"CSS/WAAPI/Lottie animations are usually auto-detected (the runtime infers " +
@@ -1925,8 +1927,12 @@ export function buildZeroDurationDiagnostic(diag: HfDiagnostic): string {
19251927
if (diag.hasSeek && diag.duration === 0 && diag.renderReady) {
19261928
hints.push("The runtime finished initializing but reported zero duration. This is permanent.");
19271929
}
1930+
const within = timeoutMs === undefined ? "" : ` within ${timeoutMs}ms`;
1931+
const headline = diag.renderReady
1932+
? "Composition has zero duration."
1933+
: `Composition setup did not finish${within}.`;
19281934
return (
1929-
`[FrameCapture] Composition has zero duration.\n` +
1935+
`[FrameCapture] ${headline}\n` +
19301936
` Runtime ready: ${diag.renderReady}, __player: ${diag.hasPlayer}, ` +
19311937
`__hf.seek: ${diag.hasSeek}, GSAP timeline: ${diag.hasTimeline}, ` +
19321938
`data-duration: ${diag.declaredDuration > 0 ? diag.declaredDuration + "s" : "not set"}\n` +
@@ -1995,7 +2001,7 @@ export async function pollHfReady(
19952001

19962002
const diag = await evaluateHfDiagnostic(page);
19972003
if (diag.hasSeek && diag.duration === 0) {
1998-
throw new Error(buildZeroDurationDiagnostic(diag));
2004+
throw new Error(buildZeroDurationDiagnostic(diag, timeoutMs));
19992005
}
20002006
throw new Error(
20012007
`[FrameCapture] window.__hf not ready after ${timeoutMs}ms. ` +

0 commit comments

Comments
 (0)