fix(cli): improve error message for zero-duration composition renders

[miguel-heygen]

PR Stack

#	PR	Status
1	#122 — fix: info width/height swap	← base
2	#123 — fix: include all 9 templates in build
3	#124 — fix: suppress ANSI in non-TTY
4	#125 — fix: lint --json error paths
5	#126 — fix: separate info/warning counts
6	#127 — fix: lint severity display
7	#128 — fix: render output path error
8	#129 — fix: zero-duration error message	← top

---

Summary

• When a composition had zero duration (empty GSAP timeline, no data-duration), Docker render hung for 45s then showed the misleading hint "Check Docker is running" even though Docker was fine
• Now detects the __hf not ready timeout error and provides a context-aware hint about zero duration instead

Reproducer

# Create a composition with an empty GSAP timeline and no data-duration
cat > index.html << 'HTML'
<div data-composition-id="test" data-width="1920" data-height="1080" data-start="0">
  <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
  <script>
    window.__timelines = window.__timelines || {};
    window.__timelines["test"] = gsap.timeline({ paused: true });
    // No tweens — timeline has zero duration
  </script>
</div>
HTML
npx hyperframes render --docker --output out.mp4
# Was: "Check Docker is running: docker info"
# Now: "Composition may have zero duration. Add data-duration to the root element or ensure the GSAP timeline has tweens."

Stack

8/8 — Depends on #128. Last PR in the stack.

🤖 Generated with Claude Code

[miguel-heygen]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(engine,cli): download headless-shell instead of using system Chrome for local renders #131
• fix(cli): improve error message for zero-duration composition renders #129 👈 (View in Graphite)
• fix(cli): catch output directory creation errors in render #130
• fix(cli): distinguish info vs warning severity in lint output #127
• fix(core): separate info count from warning count in linter results #126
• fix(cli): respect --json flag on lint error paths #125
• fix(cli): suppress ANSI escape codes in non-TTY progress output #124
• fix(cli): include all 9 templates in build output #123
• fix(cli): read actual data-width/data-height in info command #122
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

Two issues:

1. message.includes("duration") is too broad

The "__hf not ready" check alone covers the zero-duration failure path (the engine error at frameCapture.ts:251 already contains that substring). The || message.includes("duration") branch will false-positive on unrelated errors — e.g. FFmpeg failures containing "Invalid duration", ffprobe output parsing, audio mixer issues — all of which would incorrectly get the "Composition may have zero duration" hint instead of the Docker hint.

Recommend removing the || message.includes("duration") branch entirely, or narrowing to something very specific like message.includes("duration > 0").

2. Same error can occur in renderLocal path

The renderLocal catch block (line ~298) still shows a generic hint. The same __hf not ready error originates from frameCapture.ts which is used by both render paths. Consider extracting the hint-selection into a helper and applying it to both paths:

function renderHintForError(error: unknown, fallback: string): string {
  const message = error instanceof Error ? error.message : String(error);
  if (message.includes("__hf not ready")) {
    return "Composition may have zero duration. Add data-duration to the root element or ensure the GSAP timeline has tweens.";
  }
  return fallback;
}

[miguel-heygen]

Addressed both points: (1) removed broad includes("duration"), now only matches "__hf not ready". (2) Extracted renderHintForError() helper and applied to both renderDocker and renderLocal catch blocks.

[miguel-heygen]

Consolidated into fix/render-improvements.