refactor(producer): extract HDR compositing helpers and rename media metadata

[vanceingalls]

Summary

Four behavior-preserving refactors that reduce complexity in renderOrchestrator.ts and clarify the engine ffprobe utility surface. Lands after the correctness fixes (Chunks 1–5) so the refactored code is already correct.

Why

Chunk 7 of plans/hdr-followups.md. The HDR composite block had grown a ~200 LOC inline closure with 14 captured deps, a repeated capture-options spread, a extractVideoMetadata name that now also handles still images, and per-frame re-creation of debug helpers.

What changed

7A — Hoist compositeToBuffer into a module-scoped helper. Extract the inline HDR closure into a top-level compositeHdrFrame() that takes an HdrCompositeContext struct. Construct the context once at the top of the HDR render block and pass it through. Removes a deeply-nested closure from the middle of the orchestrator.

7B — buildHdrCaptureOptions() helper. Factor the repeated { ...captureOptions, skipReadinessVideoIds: ... } spread into a named helper at the call site.

7C — Rename extractVideoMetadata → extractMediaMetadata. Reflects that the helper handles still images (PNG/JPEG/WebP) in addition to video. Update all callers in engine + producer (videoFrameExtractor, htmlCompiler, regression-harness, producer ffprobe re-export, tests). Re-export the old name as a deprecated alias from @hyperframes/engine for backward compatibility, plus the producer re-export shim.

7D — Hoist debug counters to module scope. countNonZeroAlpha and countNonZeroRgb48 are now module-scoped so they aren't re-created per frame and so the closure has fewer captures.

Also touches the hdr-regression and hdr-hlg-regression README + meta.json files reviewed during this refactor.

Test plan

• bunx tsc --noEmit -p packages/producer && bunx tsc --noEmit -p packages/engine clean.
• Engine tests: 313 pass, 0 fail (1218 expect calls).
• bunx oxlint + bunx oxfmt --check clean on 8 changed source files.
• Diff is structural only — no behavioral changes.

Stack

Chunk 7 of plans/hdr-followups.md. Lands after the correctness fixes (Chunks 1–5) per the suggested merge order.

[vanceingalls]

• docs(engine): document __name polyfill and add regression test #385
• perf(producer): cache transfer-converted hdr image buffers per render job #384
• perf(producer): gate per-frame debug meta via optional isLevelEnabled #383
• perf(producer): hdr benchmark harness — --tags filter, peak heap/RSS tracking, bench:hdr script #382
• test(producer): extract frameDirMaxIndexCache to its own module and pin cross-job isolation #381
• test(engine): cover spawnStreamingEncoder lifecycle and cleanup paths #380
• test(engine): add ffprobe-unavailable fallback regression tests #379
• test(shader-transitions): add midpoint (p=0.5) regression invariants for all shaders #378
• test(engine): lock down sRGB→BT.2020 LUT with byte-exact reference values #377
• build(lfs): track tests/*/src/*.png via Git LFS #376
• test(hdr-regression): tighten Window F maxFrameFailures budget after Chunk 4 fix #375
• fix(engine,shader): handle matrix3d transforms and hide non-first scenes #374
• refactor(producer): extract HDR compositing helpers and rename media metadata #373 👈 (View in Graphite)
• fix(producer): wire --crf and --video-bitrate CLI overrides into encoders #372
• fix(producer): tighten resource lifecycle and harden file server #371
• feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer #370
• test(hdr-regression): tighten Window C maxFrameFailures budget after Chunk 1 fix #369
• fix(engine): stop clobbering native <video> opacity in HDR pipeline #368
• refactor(shader-transitions): extract DEFAULT_DURATION and DEFAULT_EASE constants #367
• refactor(types): tighten type safety, dedupe HfTransitionMeta, prune dead LUT export #366
• test(producer): add hdr-regression and hdr-hlg-regression test suites #365
• main

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

[graphite-app]

Merge activity

• Apr 23, 5:15 AM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.
• Apr 23, 5:41 AM UTC: @vanceingalls merged this pull request with Graphite.