fix(core): a cropped element's edge stays exact while GSAP tweens it

[miguel-heygen]

What this fixes

A crop on an element that GSAP scales or moves shimmered in renders: while a tween ran, the crop edge jumped by up to 1 px from frame to frame, then settled when the tween stopped. The Studio preview geometry was exact, so the export disagreed with what the author set. Six edit accuracy cases failed on this (crop-scale-px-*-mid, render 0.99 px and 0.77 px).

Cause

Mid-tween, GSAP's default force3D: "auto" writes translate3d(...) instead of translate(...) (CSSPlugin _renderCSSTransforms). A 3D transform gives the element its own compositing layer, and Chrome paints a clip-path edge on such a layer hard, snapped to whole pixels. At a tween boundary GSAP writes the 2D form again, so the edge snaps back to the exact position. The same static page shows it without any HyperFrames code:

Transform on a box with clip-path: inset(0 35.55px 0 0)	Exact right edge	Painted right edge
scale(1.125)	815.006	815.0
translate3d(0,0,0) scale(1.125)	815.006	816.0
scale(1.225)	823.451	823.448
translate3d(0,0,0) scale(1.225)	823.451	824.0

Change

The runtime sets GSAP's force3D to false through the public gsap.config, the moment GSAP loads. installFlatGsapTransforms runs while the runtime script evaluates (beside installAuthoredMediaCapture in entry.ts), configures a GSAP that is already there, and wraps the window.gsap assignment so a GSAP bundle that loads later is configured on arrival. Either way the setting is in place before a composition's own script runs set(), from() or fromTo(), which is when GSAP stores it on each element. The wrapper chains to an accessor already on window.gsap (the producer's early stub traps the same property) and installs once.

• Flat transforms stay 2D. Real 3D (z, rotationX, rotationY, transformPerspective) is still written as 3D by GSAP.
• A composition that calls gsap.config({ force3D: true }) itself keeps its own setting.
• A page that made window.gsap non-configurable before the runtime (a global var gsap ahead of it) is not trapped: a GSAP already there is configured, one that loads after it is not and keeps 3D tweens.

Evidence

Per-frame crop edge in a producer render of a bench case (crop on a scale tween, 30 fps, t = 1.8 to 3.2 s, 43 frames, JPEG as the bench renders, Chrome headless shell 152):

	Max error	Mean error	Frames off by more than 0.3 px
main	0.99 px	0.39 px	24 of 43
this branch	0.12 px	0.011 px	0

The same case, with and without a gsap.set() on the element before its timeline (crop edge error at frames 30 to 66, producer render):

Runtime	Timeline only	gsap.set() first
main	up to 0.99 px, 3D	up to 0.99 px, 3D
first commit of this PR (setting applied at DOMContentLoaded)	0.01 px	up to 0.99 px, 3D
this branch	0.01 px	0.01 px

• Edit accuracy (CI, full grid): accurate 1562, base branch 1556; the six crop-scale-px-*-mid cases are newly passing and no case lost its pass. baseline.json is the gate artifact's, committed as the gate asks. The render error itself moves both ways; see the trade below.
• Studio preview playback on two heavy repo films (registry product-promo, kinetic-type), 5 alternating rounds against main: no separable difference in per-frame main-thread work (medians 3.02 vs 3.21 ms and 3.30 vs 3.08 ms) or dropped frames. Measured with an earlier build that applied the same setting at timeline bind.
• Producer regression set, every renderable fixture rendered on main and on this branch, compared frame by frame: 61 fixtures; 22 identical; 26 differ only on edges or text antialiasing. The other 13 also differ away from hard edges, so each was re-rendered from one checkout, twice with main's runtime and once with this branch's. Main's own run-to-run noise accounts for one of them entirely (heygen-promo-preview-assets) and most of style-17-prod. In the rest, the change is fine texture and outline sharpness inside layers that move (video included), because they are now painted in the page rather than resampled as a 3D layer. Their worst frames are visually the same. Nothing moves, appears or disappears. One fixture (hf2550-video-subcomposition-ghost) has no renderable media in that environment and was not compared.
• Tests (init.test.ts, real GSAP, in page order: runtime script, GSAP bundle, composition script, DOMContentLoaded): to(), from(), fromTo() and set()-then-to() draw in 2D mid-tween; a set() then moved element draws in 2D when GSAP loaded before the runtime; a composition's own force3D: true is kept; an opacity-only tween writes no transform; a second install configures GSAP once; an accessor already on window.gsap still receives GSAP; a non-configurable window.gsap is configured without the runtime throwing (init.flatGsap.test.ts, its own file because the property cannot be removed). Seven single-line mutations of installFlatGsapTransforms each turn at least one test red. 3 green runs; the runtime folder (69 files, 1815 tests) passes.

Render change: transformed layers stay crisp mid-motion

Every element GSAP moves, scales or rotates in 2D now paints in the page instead of on its own compositor layer while the tween runs. On main such an element is drawn as a resampled texture mid-tween and snaps back to a sharp paint when the tween ends; on this branch it is painted sharp throughout.

Two producer goldens are byte-strict (maxFrameFailures: 0) over a GSAP-rotated icon and are regenerated here with docker:test:update from Dockerfile.test (Chrome 148):

• png-sequence: 59 of 60 frames change, every changed pixel inside the 44 x 44 px icon, only on the ring and dot edges.
• mov-prores: on main this fixture already scored 30.04 to 30.06 dB against its June golden, just over the 30 dB bar, because its text renders about 1 px differently today; the icon change took it to 29.88. The regenerated golden matches today's render.
• Their compiled.html snapshots are left as they were: the update also rewrites them, but only for drift unrelated to this change (they do not contain the runtime), and the compile check passes either way.

Render accuracy trade

Chrome snaps a box's painted background to whole pixels when its layout position is fractional, in both modes. On a 3D layer the crop moves with that snap, but the crop edge itself snaps (the 1 px pop above). In 2D the crop clips at its exact position on top of the snapped background, so a cropped box at a half-pixel position paints up to 0.5 px short on an uncropped edge. Static page, Chrome 152, box at top: 100.5px, height: 160px, cropped: 2D paints 101.0 to 260.5, 3D paints 101.0 to 261.0.

Render error across the 1562 edit accuracy cases, this branch's banked baseline.json vs main's (the same counts on two CI runs at different heads of this branch):

	Count
better by more than 0.015 px	53
worse by more than 0.015 px	71
worse by more than 0.1 px	6 (crop-tween-px-r0-*, 0.02 to 0.26 px)
over 0.3 px	12 (main 15)
over 0.5 px, the limit	0 (main 6)

The largest render error is now 0.37 px (crop-spin-px-r0-nested-*-mid, 0.32 on main); on main it was 0.99 px.

Known limits

The setting reaches only elements GSAP first touches after the runtime script has run. Three paths load the runtime after a composition's own script, and there an element set() before its timeline still tweens in 3D:

• Studio preview's fallback when its bundler throws, which adds the runtime at the end of <body> (reported separately; it also affects the other script-time installs in entry.ts).
• The player loading a composition by URL that has no runtime, which appends it once the page has loaded (composition-probe.ts).
• A timeline script inline in <head> before the runtime.

Before

After

[github-actions]

Edit accuracy: accurate 1562 (base branch 1556), smooth 1333 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Newly passing (6)

• crop-scale-px-r0-nested-z100-mid
• crop-scale-px-r0-root-z50-mid
• crop-scale-px-r30-nested-z100-mid
• crop-scale-px-r0-nested-z50-mid
• crop-scale-px-r0-root-z100-mid
• crop-scale-px-r30-root-z100-mid

Quarantined, measured but not gated (0)

[jrusso1020]

Approving. Setting force3D: false through the public gsap.config is the fix at the cause. The install order is what makes it work for elements that are set() before their timeline.

Install and chaining

• installFlatGsapTransforms runs at script evaluation, next to the other evaluation-time installs in entry.ts. It configures a GSAP that is already loaded and traps window.gsap for one that loads later, so the setting is in place before a composition's set() / from() stores it on an element.
• It chains to the producer's early stub (hf-early-stub-inline.ts), which defines a configurable getter and setter on window.gsap. Assignments still reach the stub's setter, so the timeline proxy wrapping is kept, and reads go through the stub's getter.
• An author's own gsap.config({ force3D: true }), or a tween-level force3D, still wins, because it runs later or is per tween.
• parseTransformMatrix in the engine already handles the 2D matrix(...) form that computed styles now report, so nothing downstream relies on matrix3d.

Goldens and baseline: these are intended baselines, not stray render output.

• The png-sequence and mov-prores outputs are LFS files already tracked on main.
• png-sequence is a byte-strict gate (maxFrameFailures: 0), and its meta.json names docker:test:update as the way to regenerate it.
• baseline.json is re-banked per PR, as on #4935 / #4934 / #4889.

Reuse: the only other window.gsap trap is the producer's stub. It only exists in renders, and this fix has to reach Studio preview too, so the runtime is the right owner, and it chains to the stub rather than duplicating it. Nothing in core configures GSAP globally today.

Simplicity: 25 lines, and I don't see a smaller version that still covers the set()-first case. Applying the setting at DOMContentLoaded or at timeline bind is the simpler-looking alternative, and the body's second table shows it misses that case. The hfFlat install-once marker and the non-configurable guard are each pinned by a test.

Tests and mutations (core, 221 tests, green): each of seven single-line mutations of installFlatGsapTransforms turns at least one test red:

• dropping the config of an already-loaded GSAP (2 red)
• dropping the config on assignment (6)
• the setter skipping the stub's setter (1)
• the getter ignoring the stub's getter (1)
• removing the non-configurable guard (1)
• removing the install-once marker (1)
• force3D: "auto" (7)

The entry.ts call itself has no unit test. The producer and edit-accuracy CI results cover it.

CI at this head: no red and nothing pending, including the Perf jobs (fps, scrub, load, drift, parity), player-perf and all ten regression shards.

Not blocking:

• The render change reaches every 2D GSAP transform, not only cropped ones. The body measures preview main-thread work but not producer render wall time, and repainting in-page instead of compositing could cost more on heavy scenes. The Perf jobs passing is some evidence. One timed render of a heavy fixture, before and after, would settle it.
• The known limits (runtime added after the composition script: the bundler-error fallback, a composition loaded by URL, an inline head timeline) are stated in the body. Worth tracking alongside the existing note on the other evaluation-time installs.

— Rames