test(engine): lock down sRGB→BT.2020 LUT with byte-exact reference values

[vanceingalls]

Summary

Add a 12-row reference table covering the full sRGB range with byte-exact 16-bit HLG and PQ signal values, plus three guard tests, locking down the buildSrgbToHdrLut() math.

Why

Chunk 9F of plans/hdr-followups.md. The matrix-free fast path through blitRgba8OverRgb48le runs every DOM pixel through buildSrgbToHdrLut() (sRGB EOTF → linear → HDR OETF → 16-bit). Any drift in the EOTF/OETF math — constant changes, branch swaps, rounding-mode regressions — would silently corrupt every text / UI / overlay pixel composited onto an HDR frame.

Existing tests covered structural invariants (transparent passthrough, opaque overwrite, alpha blending, channel symmetry, HLG ≠ PQ) but no byte-exact reference values, so a uniform scale or constant tweak could pass everything.

What changed

• 12-row reference table in alphaBlit.test.ts covering black, shadow, mid-grays, highlight, near-white, and white with exact 16-bit HLG and PQ signal values.
• Three guard tests:
  • Asymmetric R/G/B (HLG): each channel hits the LUT independently.
  • Asymmetric R/G/B (PQ): same, on the PQ path.
  • BT.2408 SDR-white invariant: PQ caps sRGB 255 at 38055 (~203 nits), well below HLG's 65535. This is the load-bearing detail that makes PQ headroom work — locking the exact value prevents a future "fix" that would re-scale PQ to peak-at-SDR-white and clip every real HDR pixel.

Reference values mirror buildSrgbToHdrLut() exactly and were verified against the existing HLG mid-gray comment in the file.

Test plan

• All new tests pass against the current LUT.
• Existing alphaBlit.test.ts invariants unchanged.

Stack

Chunk 9F of plans/hdr-followups.md. Test-only change, independent of all other chunks.

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

[qodo-ai-reviewer]

Hi, generate-lut-reference.py uses PEP585 built-in generics (e.g., list[int], tuple[int, ...]) which fail to parse on Python <3.9, but the repo does not pin a minimum Python version for engine scripts, so the regeneration workflow can break for some developers/CI environments.

Severity: remediation recommended | Category: reliability

How to fix: Pin Python or avoid generics

Agent prompt to fix - you can give this to your LLM of choice:

Issue description

packages/engine/scripts/generate-lut-reference.py uses PEP585 built-in generics (list[int], tuple[int, ...]) which require Python 3.9+. The repo doesn't pin a Python version for engine scripts, so running this script on Python 3.8 will fail at parse time.

Issue Context

Other scripts either avoid these annotations or explicitly state a Python 3.9+ requirement, so this new script should either declare its Python requirement or be compatible with older versions.

Fix Focus Areas

• packages/engine/scripts/generate-lut-reference.py[106-119]

Suggested fixes

Choose one:

1. Make the script compatible with Python 3.8 by replacing list[int] / tuple[int, ...] with List[int] / Tuple[int, ...] from typing, or by removing those annotations.
2. Explicitly document/enforce Python 3.9+ for this script (e.g., in the docstring header and/or a repo-level Python version pin file if the project uses one).

---

Found by Qodo code review