Render progress bar sits at 77% when 95% of a long streaming render is done #7713

Context: I've been using HyperFrames every day for the past two weeks to make Korean Shorts and long-form videos, and it's been great to work with. This is one of a batch of things I ran into along the way (most came as small PRs from me today) — sorry for the pile-up, and thanks for your patience.

What happens

On a long render the percentage in hyperframes render's bar (and pct in the @hf-progress machine lines) runs well behind the work. An 8:44 long-form render (15,723 frames, streaming drawElement, 3 workers, 11m17s total) printed

  ███████████████████░░░░░░  77%  Streaming frame 14912/15723 (3 workers)

and finished about 40 s later. 95% of the frames were done and about 6% of the wall-clock time was left, but the bar said 23% was left.

Reproduction (main, affa03b6, CLI 0.9.43)

A 100 s, 30 fps busy 1920x1080 GSAP composition (3,000 frames; 80 rotating boxes), hyperframes render, defaults (looks, auto workers, which the DE router pins to 3 drawElement workers on this Mac). Timestamps from a piped log:

   0.81 s   25%  Starting frame capture
   4.59 s   26%  Streaming frame 40/3000 (3 workers)
  65.39 s   77%  Streaming frame 2856/3000 (3 workers)
  68.45 s   80%  Streaming frame 3000/3000 (3 workers)
  68.75 s   90%  Encoding frame 2946/3000
  69.22 s   90%  Encoding frame 3000/3000
  69.24 s   90%  Assembling final video
  69.64 s   99%  Assembling final video
  69.69 s  100%  Render complete

The first 25 points are spent in 0.8 s and the last 20 in 1.2 s; capture, which is 97% of the wall-clock time, gets 55 points. A 900-frame version behaves the same (856/900 frames → 77%; capture 29.7 s of 34.4 s).

Why, in the code

The percentage is a fixed band per stage, not a share of the work:

• compile 5, extract 10–20 (reportExtractProgress), audio 20, start of capture 25 (renderOrchestrator.ts);
• streaming capture Math.round(25 + (done / total) * 55) → 25–80 (packages/producer/src/services/render/stages/captureStreamingStage.ts lines 619, 648, 981, 1193; the same 55 in captureSegmentedStage.ts 237/256 and the HDR loops). The disk path uses 25–70 (captureStage.ts 403/623);
• encode "from where capture left the bar up to 90%" (reportEncodeProgress, render/shared.ts ~354). On the streaming path encoding runs during capture, so this band only covers ffmpeg's drain after the last frame (0.8 s above);
• assemble 90–99 (reportAssembleProgress), 100 when the file is complete.

The bands came in with #5137 and look deliberate, so this is a question rather than a bug report: is the percentage meant to track the work? On the streaming path the 80–90 encode band is nearly empty by construction, since encode is fused into capture.

Possible directions

1. Streaming capture spans 25→90 (it already includes encoding), leaving 90–99 to assemble. Smallest change: 2856/3000 would print 87% instead of 77%.
2. Weight the bands by the expected time of each stage (capture dominates any render longer than a few seconds), keeping pct monotonic.
3. Leave the percentage alone and add an ETA from the frame rate seen so far, since done/total is already on the line.

Option 1 changes only the producer's numbers. The @hf-progress shape that HyperFrames Desktop reads (code/done/total/pct, never going back) stays the same.

Environment

macOS 27.0 (arm64, Apple M4 Pro, 12 cores, 24 GB), Node 22.16, CLI 0.9.43 (main affa03b6). Originally seen on 0.8.2xx in early November.