feat(hdr): z-ordered multi-layer compositing with PQ support

[vanceingalls]

Summary

Phase 1 only handled HDR video on the bottom with DOM on top. Real compositions need arbitrary z-interleaving — HDR video between DOM layers, multiple HDR videos at different z-depths, SDR video as background below HDR. This PR adds per-frame z-order analysis and layer-by-layer compositing.

What it does

Per-frame algorithm:

1. Query stacking order — queryElementStacking() asks Chrome for every timed element's z-index, bounds, opacity, visibility, and whether it's an HDR video.
2. Group into layers — groupIntoLayers() walks the z-sorted list. Each time the content type switches (DOM ↔ HDR), a new layer starts. Adjacent DOM elements merge into a single layer (fewer Chrome screenshots).
3. Composite bottom-to-top — DOM layers get Chrome alpha screenshots (with non-layer elements hidden). HDR layers get native pixel blits from pre-extracted frames. Each layer composites onto the running canvas.

Example z-order:

z=0: SDR background     → DOM layer 0 (1 screenshot)
z=1: HDR video           → HDR layer 1 (native blit)  
z=2: text overlay        → DOM layer 2 (1 screenshot)
z=3: HDR circle video    → HDR layer 3 (native blit)
z=4: logo                → DOM layer 4 (1 screenshot)

This produces 3 screenshots + 2 native blits = 5 layer operations per frame.

Also adds PQ (HDR10) support:

• buildSrgbToHdrLut("pq") — PQ OETF (SMPTE 2084) maps SDR white to ~203 nits (~58% PQ signal)
• blitRgba8OverRgb48le() now accepts transfer: "hlg" | "pq" parameter
• blitRgb48leRegion() — positioned rectangular copy with bounds clipping and optional opacity

Files changed

File	What changed
packages/engine/src/utils/layerCompositor.ts	NEW — groupIntoLayers(), CompositeLayer type
packages/engine/src/services/videoFrameInjector.ts	queryElementStacking() with effective z-index walk, ElementStackingInfo type
packages/engine/src/utils/alphaBlit.ts	PQ LUT, blitRgb48leRegion(), transfer parameter
packages/producer/src/services/renderOrchestrator.ts	Layer-driven compositing loop replacing simple two-pass

How to test

Render a composition with SDR video below HDR video below text overlays. All three should be visible at their correct z-depths.

Stack position

4 of 6 — Stacked on #288 (two-pass compositing). Generalizes the fixed two-layer model to arbitrary N-layer compositing.

🤖 Generated with Claude Code

[vanceingalls]

• feat(hdr): HDR image support, HDR10 metadata, and regression test harness #314
• feat(hdr): layered HDR compositing, shader transitions, and HDR image support #268
• feat(hdr): GSAP transforms and border-radius masks on HDR video #290
• feat(hdr): z-ordered multi-layer compositing with PQ support #289 👈 (View in Graphite)
• feat(engine): add HDR two-pass compositing — DOM layer + native HLG video #288
• feat(engine): add HDR video output pipeline #265
• main

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

[miguel-heygen]

Automated review (Claude Code)

Reviewed against CLAUDE.md. Stack-level meta on #268.

Note: despite the PR title ("PQ support"), the PQ LUT/OETF code lives in alphaBlit.ts outside this PR's diff, so I couldn't verify the 203-nit SDR-white choice or its rationalization from this diff alone.

Critical

• Debug stderr in hot path — packages/producer/src/services/renderOrchestrator.ts:983-990. process.stderr.write([DBG] f${i} …) every 30th frame on every render. Not behind log.debug. (Removed in #290 — ensure the stack lands together or squash carries this out.)
• Per-DOM-layer captureAlphaPng cycle is the primary perf regression — renderOrchestrator.ts:1024-1029. Each DOM layer triggers its own hideVideoElements + captureAlphaPng + showVideoElements + seek() cycle. A DOM→HDR→DOM→HDR→DOM composition does ~3× Chrome work vs. a single screenshot. Consider caching layer groupings when DOM is static, or a single screenshot + CSS-visibility layering when no HDR is interleaved.

Important

• getEffectiveZIndex misses CSS stacking-context semantics — videoFrameInjector.ts:259-268 respects position !== "static" + explicit z-index, but CSS creates stacking contexts without explicit z-index via opacity<1, transform, filter, will-change, isolation. An HDR video inside a transform: translate(...) wrapper with no z-index returns the parent's parent's z-index, potentially sorting incorrectly. GSAP routinely sets transform on wrappers — this will bite. Document the supported subset at minimum.
• Tie-break non-determinism documented-by-absence — layerCompositor.ts:31. Sort-by-z with many 0 defaults falls through to V8 stable sort → querySelectorAll DOM order. Probably fine; add a comment.
• Silent swallow of HDR decode failures — renderOrchestrator.ts:1005-1008. try { decodePngToRgb48le(...) } catch {}. Log at debug min with frame + path.
• effectiveHdr! non-null assertion — renderOrchestrator.ts:1037. Inside the HDR branch but under a swallowed try/catch: if effectiveHdr is undefined (HDR video present but probe failed) → throws → caught → silent black DOM layer. Restore explicit default or assert early.

Suggestions

• Tests for groupIntoLayers coverage gaps: empty input (should return []), negative z-index (valid CSS back layers), stable tie-break at equal z-index (input-order preservation).
• ElementStackingInfo invariants undocumented — mixes layout, stacking, visibility. visible:false + width>0 is impossible by construction but the type allows it. Brief JSDoc per field.
• Merge rule correctness comment — "adjacent DOM elements merge" is sound only because DOM layers are rendered via a full-page screenshot with non-layer elements hidden (so within-layer z-order is Chrome's). Worth a comment inside groupIntoLayers explaining why the merge doesn't lose information.

Strengths

• layerCompositor.ts is small, pure, well-tested (8 table-driven cases) — excellent module boundary.
• blitRgb48leRegion bounds clipping via Math.max/min, empty-region short-circuit, full-opacity fast path via Buffer.copy — correct.
• Re-seeking GSAP after showVideoElements (1031-1033) is a thoughtful fix for the removeProperty clobber.
• CompositeLayer discriminated union → clean pattern match in the compositor loop.

🤖 Automated review. See stack meta-comment on #268.

[vanceingalls]

Thanks. Fixes landed.

Addressed:

• Debug stderr in hot path — already removed in feat(hdr): GSAP transforms and border-radius masks on HDR video #290's diff; confirmed still absent.
• Silent HDR-decode swallow — now log.warn with element id + time.
• effectiveHdr! non-null assertion — removed in a prior revision; current code uses effectiveHdr?.transfer or narrows once at the top of the HDR branch with an early throw on the invariant.
• Tie-break non-determinism — documented in the groupIntoLayers docstring (V8 stable sort → querySelectorAll DOM order, which matches what Chrome does for equal-z elements in a stacking context). Added a test that exercises it explicitly.
• getEffectiveZIndex stacking-context limitations — now documented: does NOT detect implicit stacking contexts created by opacity<1, transform, filter, will-change, isolation, mix-blend-mode. Recommends explicit z-index on wrappers that should be compositing roots.
• groupIntoLayers coverage gaps — added tests for empty input, negative z-index (valid CSS back layers), and stable tie-break at equal z-index.
• ElementStackingInfo invariants JSDoc — expanded the interface with per-field invariants and a preamble describing assumptions the producer makes.
• Merge rule correctness — groupIntoLayers docstring now explains why merging adjacent DOM elements doesn't lose information (DOM layers render via full-page screenshot with non-layer elements hidden, so within-layer z-order is Chrome's).

Not addressed:

• Per-DOM-layer captureAlphaPng cycle as perf regression — architectural (each DOM layer does its own hide/capture/show cycle). Worth a dedicated perf PR with benchmarks before/after; keeping it scoped.