perf(producer): cache transfer-converted hdr image buffers per render job

[vanceingalls]

Summary

Add HdrImageTransferCache — a per-render-job bounded LRU keyed by (imageId, targetTransfer) — so static HDR image layers whose source transfer differs from the render's effective transfer (PQ↔HLG) are converted once per job instead of once per composited frame.

Why

Chunk 8B of plans/hdr-followups.md. blitHdrImageLayer was running Buffer.from + convertTransfer on every composited frame, even though the converted buffer is identical for the entire job. For a multi-second comp at 30 fps this is hundreds of redundant transfer conversions on the hot path.

What changed

• New packages/producer/src/services/hdrImageTransferCache.ts — bounded LRU keyed by (imageId, targetTransfer) that owns the converted HDR rgb48 buffer for static HDR image layers:
  • Same-transfer requests return the source buffer untouched (zero copy).
  • Cross-transfer requests pay one Buffer.from + convertTransfer on first miss, reuse the cached copy on every subsequent frame.
• Wired into renderOrchestrator.ts via HdrCompositeContext.hdrImageTransferCache, instantiated once per render job, and consumed by blitHdrImageLayer on both the main composite path and the transition path.

Test plan

• packages/producer/src/services/hdrImageTransferCache.test.ts — 12 tests:
  • hit/miss semantics
  • distinct keys per image and per target transfer
  • LRU eviction + promotion
  • maxEntries=0 passthrough
  • source-buffer immutability for cached entries
  • invalid options
• Re-ran the Chunk 8A HDR benchmark — for the hdr-regression fixture (which has cross-transfer image layers) the cache hits 100% after the first frame; for HDR fixtures without cross-transfer images the same-transfer passthrough is a no-op.

Stack

Chunk 8B of plans/hdr-followups.md. Sits on top of Chunk 8C (logger gating) and Chunk 8A (benchmark harness) so the win is measurable.

[vanceingalls]

• docs(engine): document __name polyfill and add regression test #385
• perf(producer): cache transfer-converted hdr image buffers per render job #384 👈 (View in Graphite)
• 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
• 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.