feat(hdr): GSAP transforms and border-radius masks on HDR video

[vanceingalls]

Summary

HDR video elements with GSAP animations (position, scale, rotation, opacity) and CSS border-radius rendered without any transforms applied — the video just sat at (0,0) full-size. This PR adds affine transform support and rounded-corner masking for natively-composited HDR video.

What it does

Affine blit with bilinear interpolation:

• blitRgb48leAffine() — Takes a 4x4 DOMMatrix and maps each destination pixel back to source coordinates via the inverse transform. Bilinear interpolation between the 4 nearest source pixels produces smooth edges under rotation and non-integer scaling. Optional opacity and border-radius parameters.
• parseTransformMatrix() — Parses CSS matrix(a,b,c,d,e,f) strings into [a,b,c,d,e,f] tuples.

Accumulated viewport matrix:

• getViewportMatrix() — Walks the offsetParent chain from element to viewport, accumulating position offsets and CSS transforms at each level. Correctly handles transform-origin using the CSS sandwich: translate(origin) × M × translate(-origin). This is critical because GSAP animates transforms on wrapper divs, not directly on the video element.

Effective opacity:

• getEffectiveOpacity() — Multiplies opacity values walking up the ancestor chain. Uses Number.isNaN() (not || 1) so opacity:0 isn't incorrectly treated as 1.

Border-radius masks:

• roundedRectAlpha() — Per-pixel anti-aliased rounded-rectangle mask with support for independent corner radii.
• getEffectiveBorderRadius() — Walks ancestors for overflow:hidden + border-radius. Resolves percentage values (e.g., 50% for circles) via offsetWidth/offsetHeight.

Layout dimensions for extraction:

• Uses offsetWidth/offsetHeight (unaffected by CSS transforms) instead of getBoundingClientRect() (which returns the transformed bounding box and wobbles under rotation).

Files changed

File	What changed
packages/engine/src/utils/alphaBlit.ts	blitRgb48leAffine(), parseTransformMatrix(), roundedRectAlpha(), cornerAlpha()
packages/engine/src/services/videoFrameInjector.ts	getViewportMatrix(), getEffectiveOpacity(), getEffectiveBorderRadius(), layoutWidth/layoutHeight on ElementStackingInfo
packages/producer/src/services/renderOrchestrator.ts	Affine blit path, extraction at layout dimensions, border-radius parameter passing

How to test

Render a composition with an HDR video that has GSAP scale + rotation animation and a border-radius: 50% wrapper (circle mask). The video should rotate smoothly with round edges — no wobble, no sharp corners.

Stack position

5 of 6 — Stacked on #289 (z-ordered layers). Adds transform and masking support to the HDR blit that the layer compositor uses.

🤖 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 👈 (View in Graphite)
• feat(hdr): z-ordered multi-layer compositing with PQ support #289
• 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.

Critical

• Main HDR composite path ignores transform and borderRadius — packages/producer/src/services/renderOrchestrator.ts:~1012-1064 (verified against PR diff). The loop builds [scaleX, 0, 0, scaleY, el.x, el.y] from el.width/srcW, el.height/srcH, el.x, el.y only. el.transform and el.borderRadius — the fields this PR adds to ElementStackingInfo — are never read here. GSAP rotations and border-radius masking (the stated purpose of this PR) do not apply on this path. The bounding-rect comment says "getBoundingClientRect() already reflects all ancestor transforms" — but that gives the axis-aligned bounding box of a transformed element, destroying rotation information. Thread parseTransformMatrix(el.transform) and el.borderRadius through, or unify with the path at ~line 386 via a single helper.

Important

• Zero tests for DOM-walking math — getViewportMatrix, getEffectiveOpacity, getEffectiveBorderRadius (videoFrameInjector.ts:282-375). No unit coverage; not exercised by layerCompositor.test.ts. These run inside page.evaluate, so they need either jsdom/puppeteer tests or extraction into pure helpers taking DOM-like inputs. Transform-origin sandwich, percentage border-radius resolution, HDR-specific opacity-start-from-parent — all untested.
• transform-origin percentage resolution is suspect — videoFrameInjector.ts:370-373. parseFloat(origin[0] || "0") on "50% 50%" returns 50 (treated as px, not 50% of width). Chrome normalizes transformOrigin to px for rendered elements, but keyword origins (center) and unresolved percentages can leak through. Assert px or resolve % against offsetWidth/offsetHeight.
• offsetParent null for position:fixed silently truncates matrix walk — videoFrameInjector.ts:355-359. Fixed wrappers with GSAP transforms → dropped. Fall back to parentElement when offsetParent is null, or document the limitation.
• No NaN/singular-matrix guard on new DOMMatrix(cs.transform) — videoFrameInjector.ts:373. Malformed or 3D-matrix input throws; the whole queryElementStacking page.evaluate rejects → frame dropped. Wrap in try/catch, fall back to identity with a warning.
• offsetLeft/Top composition order — videoFrameInjector.ts:364-374. Translating by offsetLeft/Top before the transform-origin sandwich is fine for a single transform, but offsetParent semantics shift when an ancestor has a CSS transform (it becomes a containing block). Add a test with two stacked transformed wrappers.

Suggestions

• Percentage border-radius uses clipping-ancestor dims — videoFrameInjector.ts:289-295. Correct per CSS spec, but the resulting radii are then applied to the video at its own dimensions in the consumer. If the clipping ancestor is larger than the video → wrong mask size. Verify the consumer converts to video coordinate system (or uses layoutWidth/Height consistently).
• layoutWidth: htmlEl.offsetWidth || Math.round(rect.width) — videoFrameInjector.ts:404-405. offsetWidth=0 triggers the fallback to rect.width, which is the very transformed-bounding-box value the field exists to avoid. Prefer htmlEl instanceof HTMLElement ? htmlEl.offsetWidth : Math.round(rect.width).
• hdrExtractionDims gates on el.width > 0 — renderOrchestrator.ts extraction-dim block. HDR elements that start invisible (GSAP autoAlpha: 0 at t=0, common pattern) have el.width = 0 → fall back to composition dims → original bug reintroduced. Use layoutWidth/layoutHeight.

Strengths

• Number.isNaN(val) ? 1 : val correctly implemented (videoFrameInjector.ts:325); opacity:0 trap explicitly noted in-comment — matches PR description.
• Freeze-on-last-frame fallback (renderOrchestrator.ts:1024-1033) is good UX parity with Chrome video.
• Extraction at display dimensions → eliminates stride/scale mismatch.
• DOMMatrix.toString() + parseTransformMatrix as the IPC boundary between browser and Node is a clean design.
• Debug stderr from #289 was correctly removed here.

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

[vanceingalls]

Thanks. Fixes landed.

Addressed:

• Main HDR composite path ignores transform / borderRadius — the feat(hdr): layered HDR compositing, shader transitions, and HDR image support #268 refactor collapsed both composite paths into a single blitHdrVideoLayer helper that reads el.transform via parseTransformMatrix and el.borderRadius directly, so this is already resolved by the later PR landing together.
• offsetParent null for position:fixed — getViewportMatrix now falls back to parentElement when offsetParent is null. Fixed wrappers with GSAP transforms still contribute to the accumulated matrix.
• transform-origin percentage resolution — extracted a resolveLength() helper that handles both px and % (resolving % against offsetWidth/offsetHeight).
• NaN/singular-matrix guard — new DOMMatrix(cs.transform) is now wrapped in try/catch, and all 6 matrix fields are validated with Number.isFinite before being applied. Malformed ancestor transforms fall back to identity without rejecting the whole frame.
• hdrExtractionDims gates on el.width > 0 (autoAlpha:0 trap) — already using layoutWidth/layoutHeight (from offsetWidth/offsetHeight), which are non-zero even when a GSAP autoAlpha: 0 wrapper sets display:none isn't involved.
• layoutWidth fallback style — replaced el as HTMLElement cast with el instanceof HTMLElement ? el : null type guard. offsetWidth/offsetHeight are now only accessed on actual HTMLElement instances; SVGElement/MathMLElement/etc. fall through to the bounding-rect fallback cleanly instead of relying on the cast silently producing 0.

Not addressed:

• Zero tests for DOM-walking math (getViewportMatrix, getEffectiveOpacity, getEffectiveBorderRadius) — these run inside page.evaluate so they need either a jsdom/puppeteer setup or extraction into pure helpers. Agreed it's a gap; worth a dedicated test-infra PR so we don't half-test them.
• Two stacked transformed wrappers test — same reasoning; belongs with the DOM-walk tests above.
• Percentage border-radius clipping-ancestor dims vs. consumer coordinate system — the consumer (blitRgb48le*) applies radii to the element at its own dimensions, so clipping-ancestor resolution is what we want for the mask size. Worth explicit verification in a dedicated test.

[graphite-app]

Merge activity

• Apr 19, 11:32 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.
• Apr 20, 12:03 AM UTC: @vanceingalls merged this pull request with Graphite.