fix(engine,shader): handle matrix3d transforms and hide non-first scenes

[vanceingalls]

Summary

Two correctness fixes in the HDR transform & clipping pipeline: parseTransformMatrix now handles matrix3d(...) (GSAP's default force3D: true), and shader-transitions sets every non-first scene to opacity: 0 at t=0 so the engine doesn't over-composite at the start.

Why

Chunk 4 of plans/hdr-followups.md. Transform extraction and border-radius computation existed but were dead — an HDR video with rotation: 45 rendered un-rotated, and 3-scene compositions ghosted at t=0 because every scene defaulted to CSS opacity: 1 and contributed to the first frame.

What changed

Matrix3d support in parseTransformMatrix. DOMMatrix.toString() emits matrix3d whenever any ancestor in the chain has used a 3D transform — most importantly GSAP's default force3D: true, which converts translate(...) into translate3d(..., 0). Without this, every GSAP-driven transform was silently dropped during HDR compositing because videoFrameInjector.getViewportMatrix() would return matrix3d(...) and the blit path would parse it as null and fall back to identity. The 16-value column-major form is converted to its 2D affine projection (indices 0, 1, 4, 5, 12, 13 → m11, m12, m21, m22, m41, m42); Z, perspective, and out-of-plane rotation components are dropped.

Initial-state opacity in initEngineMode. The browser preview branch uses a GL canvas overlay during transitions, so scene opacity at t=0 doesn't matter visually. The engine branch reads scene opacity directly via queryElementStacking() to decide which layers to composite. Without an explicit initial-state tween, every scene defaulted to CSS opacity: 1 and contributed to the very first frame, causing ghosting/overlap until the first transition fired. tl.set() at position 0 anchors the initial state in the timeline graph so reverse seeks from inside a later transition restore it correctly.

These two fixes together make el.transform and el.borderRadius (already wired in Chunk 7A's compositeHdrFrame) actually flow through the GSAP-animated case, and keep the engine's per-frame compositing aligned with what the user sees in browser preview.

Test plan

• 6 new alphaBlit.test.ts cases (identity matrix3d, translate3d, scale + translate3d, rotateZ, malformed arg count, non-finite values).
• Existing hdr-regression Window H already CSS-sets #scene-b { opacity: 0 } as a fallback; the new tl.set is redundant for that case but harmless and removes the need for compositions to remember the CSS workaround.
• Manual: rotated HDR video (rotation: 45) appears rotated; border-radius: 50% clips to circle; 3-scene composition has no overlap at t=0.

Stack

Chunk 4 of plans/hdr-followups.md. Window F of the regression suite documents the bug; the next PR in the stack tightens the maxFrameFailures budget to 0.

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

[jrusso1020]

Two real fixes, both structural:

matrix3d in parseTransformMatrix — previously returned null for any 3D matrix, which meant every GSAP composition with force3D: true (GSAP's default for transform tweens) fell off the deterministic engine path and rendered with identity transforms on the HDR compositor. The spec-correct approach is: parse the 16-element column-major matrix, extract the 2D affine components (a=m[0], b=m[1], c=m[4], d=m[5], tx=m[12], ty=m[13]), drop Z-translation, and validate all six extracted components are finite. Tests pin the three common GSAP emission shapes (identity, translate3d, scale + translate3d, rotateZ) plus malformed rejection (wrong arg count, NaN values). Exactly the right coverage.

Worth documenting in code (or the plans doc) that this is a 2D projection of the 3D transform — any composition that actually uses Z-depth (perspective, 3D rotation around X/Y axes) will silently lose those components in the engine path. For force3D: true with a flat Z this is invisible; for a genuine 3D scene the engine just doesn't support it, which was already the case before this PR but is now hidden behind a "parses successfully" result instead of a null. If a Z-significant transform ever shows up in a regression test, the engine will render it flat without flagging that it threw away the Z info. Non-blocking, but worth a log warning when m[8..11] are non-identity.

Non-first scenes start at opacity: 0 in hyper-shader.ts — the fix for the Window F corruption in #365. Without this, non-first scenes were visible during scene-A capture and bled into the HDR compositor's first frame. Cleaner than the alternative (hiding scenes via DOM manipulation) because it stays inside the shader-transitions package's opacity contract.

CI failures here are the stack-wide Format and Render on windows-latest — not specific to this change. The Windows failure across the whole upper stack is worth running down separately (could be LFS-check issue after #376, or could be unrelated).

Approved.

— Rames Jusso

[vanceingalls]

Merge activity

• Apr 23, 6:55 AM UTC: @vanceingalls merged this pull request with Graphite.