refactor(producer): extract encodeStage and assembleStage

[jrusso1020]

Stacked on #725 → #726 → #730 → #731 → #733 → this. Rebase once ancestors merge.

What

Phase 1 PR 1.9 of the distributed-render refactor. Two small extractions for the final two stages:

• encodeStage.ts (Stage 5): handles both branches of the post-capture encode step:
  • png-sequence: rename captured PNGs to frame_NNNNNN.png, copy to outputPath, write audio.aac sidecar if audio is present.
  • encoded output: invokes encodeFramesFromDir or (when enableChunkedEncode is on) encodeFramesChunkedConcat.
• assembleStage.ts (Stage 6): mux video + audio (muxVideoWithAudio) when hasAudio, otherwise applyFaststart. Skipped entirely for png-sequence (the sequencer gates the call).

Why

These are the final two capture-adjacent stages. After this PR, the only work left in executeRenderJob is the in-sequencer setup (worker calibration, preset selection, etc.) and the eight stage calls. PR 1.10 reduces the sequencer to a thin composition.

How

• encodeStage.ts exports runEncodeStage(input) → { encodeMs }. Body covers both branches (png copy vs. ffmpeg encode). Sequencer calls it with the same condition gating (isPngSequence ? png-path : encoded-path is inside the stage now).
• assembleStage.ts exports runAssembleStage(input) → { assembleMs }. Body is the if (hasAudio) ... else ... mux/faststart pair.
• Sequencer replaces both inline blocks with the stage calls and assigns perfStages.encodeMs / perfStages.assembleMs from the results.
• Drops the now-orphaned imports from the orchestrator: encodeFramesFromDir, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart.

Preserved invariants

• The updateJobStatus payloads fire from inside the stages at the same code points: "Writing PNG sequence" / "Encoding video" at 75%, "Assembling final video" at 90%.
• The "png-sequence output requested but no PNGs were captured to ..." error throws verbatim.
• The png-sequence audio sidecar is only written when hasAudio && existsSync(audioOutputPath).
• The chunked-concat vs. direct encode selection is identical (enableChunkedEncode flag, same args).
• "Audio muxing failed: " / "Faststart failed: " throw verbatim on the respective success: false results.

Test plan

• bunx oxlint + bunx oxfmt --check — clean.
• bun run --filter @hyperframes/producer typecheck + build — clean.
• bun test packages/producer/src/services/ — 176 pass, same pre-existing failure.
• Docker fixtures (5/5 PASS): font-variant-numeric (1.000), many-cuts (0.994), sub-composition-video (0.947), gsap-letters-render-compat (1.000), hdr-regression (1.000). Between them they exercise the encoded mp4 path (encode + assemble both run), the streaming-fusion path (encode is skipped by the sequencer when streaming succeeded), and the HDR path (encode is also skipped because the HDR stage produces videoOnlyPath directly).
• Full regression matrix on CI via the regression workflow.

🤖 Generated with Claude Code

[jrusso1020]

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

• refactor(producer): move updateJobStatus to render/shared.ts #737
• refactor(producer): document executeRenderJob as a thin sequencer #735
• refactor(producer): extract encodeStage and assembleStage #734 👈 (View in Graphite)
• refactor(producer): extract captureHdrStage (HDR / shader-transition path) #733
• refactor(producer): extract captureStreamingStage (single-machine fusion) #731
• refactor(producer): extract captureStage (SDR disk path) #730
• refactor(producer): extract audioStage from executeRenderJob #726
• refactor(producer): extract extractVideosStage + add materializeSymlinks param #725
• main

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

[vanceingalls]

Verdict: approve.

Bundles two stages (encodeStage, assembleStage) into one PR. Both are byte-clean extractions, each independent.

encodeStage (Stage 5):

• Two branches — png-sequence (copy + rename + audio sidecar) and encoded (mp4 / webm / mov via encodeFramesFromDir or encodeFramesChunkedConcat). Both lifted verbatim.
• The "png-sequence output requested but no PNGs were captured" throw preserved; the enableChunkedEncode branch selector preserved; the Encoding failed: <err> throw preserved.
• updateJobStatus(... "encoding", "Writing PNG sequence" / "Encoding video", 75, ...) payload fires at the same point — inside the stage, at 75%.
• Skip when streamingHandled === true — gated correctly on the sequencer side.

assembleStage (Stage 6):

• hasAudio ? muxVideoWithAudio : applyFaststart branch preserved verbatim with the same throw messages (Audio muxing failed: <err> / Faststart failed: <err>).
• Stage is correctly skipped for png-sequence in the sequencer — same if (!isPngSequence) guard as pre-extraction.
• updateJobStatus(... "assembling", "Assembling final video", 90, ...) payload preserved at 90% from inside the stage.

The bundling is justified. Both stages are post-capture, both are skip-aware (encodeStage skipped by streaming fusion; assembleStage skipped by png-sequence), neither has internal state worth a third file. Splitting them across two PRs would be churn for no review benefit. The stage interfaces are independent — assembleStage doesn't depend on anything encodeStage returns beyond what was already in the sequencer's scope.

Nits:

• encodeStage.ts:53,69,103 — fps: Fps and useGpu: boolean | undefined are passed in, but #735 immediately drops them in favor of reading job.config.fps and job.config.useGpu directly. Worth folding into this PR instead of a separate cleanup.
• Same runtime cycle pattern as the other stages (imports updateJobStatus from the orchestrator). #737 resolves it.

Praise: assembleStage is the shortest stage in the stack — 70 lines including the JSDoc — and reads end-to-end. The pattern of preserving every updateJobStatus call site inside the stage at the same progress percentage keeps perfStages and the on-screen progress bar in lock-step across the migration. Easy to verify.

— Vai

[miguel-heygen]

Clean mechanical extraction — no behavior changes, no introduced bugs. Verified imports, error handling, and cleanup invariants are preserved. LGTM. — Magi