fix(engine): report a pending setup as a setup timeout, not zero duration - #7211

What

When a render gives up waiting for the page to finish setup, the error now says so: Composition setup did not finish within 45000ms. It used to say Composition has zero duration., even for compositions that declare a data-duration. The CLI reports a new code for it, COMPOSITION_SETUP_TIMEOUT.

Why

Before render-ready, the bridge reports __hf.duration as 0. So when pollHfReady timed out because a window.__hf.buildReady promise never settled, the timeout headline said the composition had zero duration. That sends authors looking at their timing attributes when the real problem is setup that never finished. We hit this on a Three.js path-tracing study: its setup waited on an animation frame, which the render clock holds until the first seek.

Related work

Refs the 3D path-tracing follow-up. EF's render-metrics classifier gets a matching row in heygen-com/experiment-framework#65311. We considered letting animation frames run before the first seek (#7213) and closed it, because it made frame-counting loops depend on load time. The render clock stays strict, and this message tells authors how to wait instead.

How

• buildZeroDurationDiagnostic takes the timeout and picks the headline from renderReady:
  • Not ready: "Composition setup did not finish within Nms."
  • Ready with zero duration: the old "Composition has zero duration."
• The pending-buildReady hint now also explains the render clock. Date and performance.now stay at 0, and requestAnimationFrame callbacks wait until the first frame, so setup that awaits either never finishes. The hint points authors at the library's own readiness promise (for Three.js, renderer.compileAsync), not a hand-written timer.
• Not covered here: a scheduler.yield() polling loop. In plain headless Chrome 152 (macOS Metal and Linux), a ten-line page that polls a setTimeout flag with await scheduler.yield() never finishes loading, because yield continuations outrank timers. That starves the page, so the readiness poll never returns and the render ends in a capture stall instead of this message. That guidance goes in the 3D docs and starter recipe.
• The "no GSAP timeline" hint now shows only once the runtime is ready. Before that, its advice about inferring duration doesn't apply yet.
• Retry behavior is unchanged: the new message is classified as transient, just like the old zero duration ... Runtime ready: false message.
• The CLI maps the new message to COMPOSITION_SETUP_TIMEOUT.

Other consumers that match on the old text:

• EF's render-metrics classifier: gets the follow-up PR mentioned above.
• HFI's studio-contracts stderrKind: maps Composition has zero duration to composition-empty. Setup timeouts will now land in other there, which is more accurate than "empty".

Test plan

• Unit tests added/updated:
  • frameCapture.test.ts: three cases. A pending setup gets the setup headline and the clock hint. The timeline hint is skipped while pending. A ready, zero-duration page keeps the old headline.
  • captureFailure.test.ts: the new message is classified as transient.
  • renderDiagnostic.test.ts: the new message maps to COMPOSITION_SETUP_TIMEOUT.
  • The three new frameCapture cases fail on main and pass here.
• Manual testing performed: rendered 1 s Three.js compositions whose setup waits for performance.now() to advance, or awaits one animation frame,, using the CLI built from this branch (software GL). It fails after 45 s with:

  [FrameCapture] Composition setup did not finish within 45000ms.
    Runtime ready: false, __player: true, __hf.seek: true, GSAP timeline: false, data-duration: 1s
    → window.__hf.buildReady never resolved for: scene. ... 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).
  @hf-diagnostic {"version":1,"operation":"render","code":"COMPOSITION_SETUP_TIMEOUT"}
  

• Documentation updated (if applicable): no doc names this message.
• Comments follow CONTRIBUTING.md "Comments".

🤖 Generated with Claude Code