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]

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
• 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]

Review feedback follow-up

@jrusso1020's non-blocking suggestion is addressed: parseTransformMatrix now warns when a matrix3d arrives with Z-significant components.

packages/engine/src/utils/alphaBlit.ts:

function warnIfZSignificant(parts: number[]): void {
  if (warnedZSignificant) return;
  // For a flat 2D transform — the only thing this engine path can render
  // faithfully — we expect:
  //   a3 = b3 = c1 = c2 = 0   (no XZ/YZ rotation coupling)
  //   c3 = 1                  (no Z scaling)
  //   d1 = d2 = d3 = 0        (no perspective)
  //   d4 = 1                  (no homogeneous scaling)
  // Z translation (c4 = parts[14]) is explicitly dropped by the 2D affine
  // extraction below — that's the whole point of supporting GSAP's
  // `force3D: true` translate3d(x, y, 0) emission — so it is NOT flagged.
  // ...component checks against Z_EPSILON...
  if (...non-trivial 3D components detected...) {
    warnedZSignificant = true;
    console.warn(
      `[alphaBlit] parseTransformMatrix received a matrix3d with non-trivial 3D components ` +
        `(a3=${a3}, b3=${b3}, c1=${c1}, c2=${c2}, c3=${c3}, d1=${d1}, d2=${d2}, d3=${d3}, d4=${d4}). ` +
        `The engine projects 3D transforms to 2D (m11, m12, m21, m22, m41, m42) and silently ` +
        `discards perspective and out-of-plane rotation. ...`,
    );
  }
}

Key design points (addressing the staff-eng nod):

• force3D: true happy path is silent — translateZ (parts[14]) is intentionally not in the check, so GSAP's flat 2D output via matrix3d(...) doesn't trigger the warning.
• Once-per-process rate limit (warnedZSignificant module flag) so a 60fps render with a real 3D rotation doesn't flood logs.
• All 9 detector components are echoed back in the warn line (a3, b3, c1, c2, c3, d1, d2, d3, d4) so the author can identify which 3D feature they're using.

Test coverage in alphaBlit.test.ts:

• warns once when matrix3d has Z-significant components (rotateY 45deg) — pinned the rotateY case as the canonical 3D-significant emission.
• Existing force3D: true tests confirm translate3d, scale + translate3d, and rotateZ all stay quiet.

Stack-wide CI: ✅ green now (the Format and Render on windows-latest failures you flagged were resolved on subsequent commits in the stack).