Improve auto worker handling and guidance for WebGL-heavy compositions

[miguel-heygen]

Problem

HyperFrames can push much further than "template motion graphics" for high-fidelity compositions, but the render ergonomics start to break down once a scene gets WebGL-heavy.

I spent the weekend trying to find the edges of HyperFrames by building a 22-second intro for a fictional crypto card. The composition used:

• a fully procedural Canvas 2D card face (radial gradients, EMV chip, holographic foil, concentric circles)
• Three.js + PMREM lighting for the photoreal look without raytracing
• bloom for the specular sweep / camera-found-the-light moment
• one GSAP timeline to orchestrate text staggers, burst rings, and camera orbits

The creative side worked well. The runtime side was the surprise:

• render time: 3m32s
• --workers auto chose 6 and kept timing out
• forcing --workers 2 ran cleanly

Right now that means users can hit a ceiling where the composition itself is valid, but the default render worker strategy makes it feel unstable. It is also hard to tell whether the fix is "optimize the scene" or just "stop auto from oversubscribing this kind of workload."

Proposed solution

1. Make --workers auto more conservative for WebGL-heavy scenes.
   • Detect likely heavy GPU/Three.js workloads and choose a lower worker count.
   • Or, if a render times out under auto, retry with a smaller worker count before failing.
2. Document the current guidance explicitly.
   • Add troubleshooting guidance that WebGL-heavy / bloom-heavy scenes may need fewer workers.
   • Call out a recommended starting point such as --workers 2 when GPU pressure is high.
3. Add an advanced showcase/example that demonstrates the ceiling.
   • Procedural Canvas 2D textures instead of imported assets
   • Three.js + PMREM + bloom for product-photography lighting
   • GSAP as the single orchestration timeline

That would do two things at once: make rendering more reliable, and show that HyperFrames can produce polished, non-template motion when pushed hard.

Alternatives considered

• Manually tune --workers per project.
  • Works today, but it is trial-and-error and easy to misread as a scene bug.
• Flatten more visuals into image assets.
  • Reduces runtime pressure, but loses the zero-asset / infinite-resolution upside of procedural graphics.
• Treat this as docs only.
  • Helpful, but it still leaves --workers auto picking an unsafe default for some advanced scenes.

Additional context

A few things that stood out from the experiment:

• Procedural Canvas 2D was a big win: no image files, no load-time asset dependency, infinite resolution.
• Three.js + PMREM was enough to get convincing product-lighting behavior without raytracing.
• GSAP being the single timeline made the scene much easier to reason about than splitting motion across multiple tools.
• Small details mattered a lot for escaping the "prototype" look: plastic grain bump maps, hairline inner frames, double burst rings at the hero moment, and a white flash on wordmark reveal.

Next iteration is to layer in a HeyGen presenter, but the main OSS-facing issue here is render reliability + guidance for GPU-heavy scenes.