perf(producer): gate per-frame debug meta via optional isLevelEnabled

[vanceingalls]

Summary

Add an optional isLevelEnabled(level) method to ProducerLogger and use it to short-circuit per-frame HDR composite metadata construction in renderOrchestrator when the log level is above debug.

Closes Chunks 8C and 8D from plans/hdr-followups.md.

Why

Chunk 8C of plans/hdr-followups.md. The per-frame HDR composite snapshot (every 30 frames) was building an Array.find + toFixed + struct allocation unconditionally and handing it to a debug logger that immediately discarded it at level="info". On long renders, this is allocation pressure and CPU time wasted on log meta nobody reads.

Chunk 8D was investigated in the same pass and found to already be guarded — see below.

What changed

• New optional isLevelEnabled(level: ProducerLogLevel): boolean on ProducerLogger.
• createConsoleLogger implements it.
• renderOrchestrator.ts per-frame HDR composite snapshot is now gated on i % 30 === 0 && (log.isLevelEnabled?.("debug") ?? true) — production runs at level="info" skip the meta-object construction entirely; custom loggers without the new method keep their existing behavior thanks to the ?? true fallback.
• New packages/producer/src/logger.test.ts (17 tests) covering level filtering, meta formatting, the isLevelEnabled path, a hot-loop call-site simulation that asserts zero builder invocations at info level, and the ?? true fallback for loggers that omit the method.
• docs/packages/producer.mdx gains a new "Logging" section documenting ProducerLogger, createConsoleLogger, defaultLogger, and the isLevelEnabled gating pattern.

8D resolution (no code change). countNonZeroAlpha / countNonZeroRgb48 calls live behind shouldLog = debugDumpEnabled && debugFrameIndex >= 0, where debugDumpEnabled is itself driven by KEEP_TEMP=1. The pixel iteration is fully skipped on production runs already, so 8D needed no fix — verified during the 8C work.

Test plan

• bun test in producer — 17/17 logger tests pass; existing service tests unchanged.
• Hot-loop call-site simulation asserts the meta builder is invoked zero times at level="info".
• ?? true fallback preserves prior behavior for custom logger implementations that don't define the method.
• Re-ran the HDR benchmark from Chunk 8A — no regression on wall-clock, peak heap unchanged at info level.

Stack

Chunks 8C + 8D of plans/hdr-followups.md. Sits on top of the benchmark harness PR (Chunk 8A) so the optimization is measurable.

[vanceingalls]

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

• 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 👈 (View in Graphite)
• 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.