From 75fe18c621be5297d7b09a788fabc75a3cd6c734 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Sun, 8 Nov 2026 06:03:31 +0000 Subject: [PATCH] fix(core): a set written before its tween no longer erases the tween's end (#7397) * fix(core): a set written before its tween no longer erases the tween's end * fix(core): shorten two comment lines to the limit * fix(core): the stamp takes any GSAP the runtime types, so the runtime typecheck passes --- .../src/runtime/adapters/gsap.order.test.ts | 81 ++++++++++++++++++- packages/core/src/runtime/adapters/gsap.ts | 17 +++- .../src/runtime/adapters/gsapAuthoredOrder.ts | 40 +++++++++ .../src/runtime/init.authoredOrder.test.ts | 16 ++++ packages/core/src/runtime/init.ts | 10 ++- 5 files changed, 157 insertions(+), 7 deletions(-) create mode 100644 packages/core/src/runtime/adapters/gsapAuthoredOrder.ts create mode 100644 packages/core/src/runtime/init.authoredOrder.test.ts diff --git a/packages/core/src/runtime/adapters/gsap.order.test.ts b/packages/core/src/runtime/adapters/gsap.order.test.ts index 7b9c550fd8..c4565e008e 100644 --- a/packages/core/src/runtime/adapters/gsap.order.test.ts +++ b/packages/core/src/runtime/adapters/gsap.order.test.ts @@ -1,9 +1,13 @@ import gsap from "gsap"; -import { describe, expect, it } from "vitest"; +import { beforeAll, describe, expect, it } from "vitest"; import { rerenderGsapTimelineAt, seekGsapTimeline } from "./gsap"; +import { stampAuthoredOrder } from "./gsapAuthoredOrder"; import { producerStandIn } from "./gsapStandIn.test-helpers"; import type { RuntimeTimelineLike } from "../types"; +// The runtime stamps the order a film writes its tweens in as GSAP loads, before any composition script runs. +beforeAll(() => stampAuthoredOrder(gsap)); + const FPS = 60; const FRAMES = 150; @@ -228,3 +232,78 @@ describe("a fromTo beside a set on another property of the same element", () => expect(tile.x).toBeCloseTo(100 + 100 * (59 / 30 - 1), 5); }); }); + +// An init written as a set before the tween that fades in from it: the set sits inside the tween's span, but the +// author wrote the tween last, so the tween's end is what the film shows. +function setBeforeFadeIn() { + const cards = [0, 1, 2, 3].map(() => ({ opacity: 0, scale: 1 })); + const timeline = gsap.timeline({ paused: true }); + timeline.to({ x: 0 }, { x: 1, duration: 0.8 }, 5.5); + timeline.set(cards, { opacity: 0, scale: 0.95 }); + timeline.fromTo( + cards, + { opacity: 0, scale: 0.95 }, + { opacity: 1, scale: 1, duration: 0.8, stagger: 0.15 }, + 6.0, + ); + timeline.to(cards, { opacity: 0, scale: 0.8, duration: 1 }, 8.5); + return { cards, timeline: timeline as unknown as RuntimeTimelineLike }; +} + +const CARD_FRAMES = range(0, 300); +// Inside the overlap GSAP's own in-order stepping shows the set's value for one frame (190) that the runtime's +// re-render does not; this test is about what the film shows once the last card has faded in. +const FADED_IN = Math.ceil((6.0 + 3 * 0.15 + 0.8) * SET_FPS); + +/** Card 0's opacity at each frame, through the render's seek, or through the runtime's seek and re-render. */ +function cardsAt(frames: number[], through: "render" | "runtime"): Map { + const { cards, timeline } = setBeforeFadeIn(); + const structure = { owner: timeline, version: "1" }; + const opacity = new Map(); + for (const frame of frames) { + const t = frame / SET_FPS; + if (through === "render") seekGsapTimeline(timeline, t, true, structure, SET_FPS); + else if (!seekGsapTimeline(timeline, t, false, undefined, SET_FPS)) { + rerenderGsapTimelineAt( + { + totalTime: timeline.totalTime!.bind(timeline), + totalDuration: timeline.totalDuration?.bind(timeline), + getChildren: timeline.getChildren?.bind(timeline), + }, + t, + ); + } + opacity.set(frame, cards[0]!.opacity); + } + return opacity; +} + +describe("a set written before the tween it sits inside", () => { + // What GSAP itself shows playing the film in order, frame by frame. + const inOrder = (() => { + const { cards, timeline } = setBeforeFadeIn(); + return new Map( + CARD_FRAMES.map((frame) => { + timeline.totalTime!(frame / SET_FPS, true); + return [frame, cards[0]!.opacity] as const; + }), + ); + })(); + + it("starts from a film where the fade-in ends fully visible", () => { + expect(inOrder.get(Math.round(7.5 * SET_FPS))).toBe(1); + }); + + for (const through of ["render", "runtime"] as const) { + it(`shows the tween's end after the fade-in through the ${through} seek, however frames are shared out`, () => { + for (const workers of [1, 2, 3, 4, 6]) { + for (let worker = 0; worker < workers; worker++) { + for (const [frame, opacity] of cardsAt(range(worker, 300, workers), through)) { + if (through === "runtime" && frame < FADED_IN) continue; + expect([workers, frame, opacity]).toEqual([workers, frame, inOrder.get(frame)]); + } + } + } + }); + } +}); diff --git a/packages/core/src/runtime/adapters/gsap.ts b/packages/core/src/runtime/adapters/gsap.ts index b9fac96791..c79682a409 100644 --- a/packages/core/src/runtime/adapters/gsap.ts +++ b/packages/core/src/runtime/adapters/gsap.ts @@ -1,4 +1,5 @@ import type { RuntimeDeterministicAdapter, RuntimeTimelineLike } from "../types"; +import { authoredOrderOf } from "./gsapAuthoredOrder"; type GsapAdapterDeps = { getTimeline: () => RuntimeTimelineLike | null; @@ -140,7 +141,12 @@ type PlacedTween = GsapPlaced & { vars?: Record; targets?: () => object[]; }; -type PropertyWrite = { start: number; end: number; properties: Set | null }; +type PropertyWrite = { + start: number; + end: number; + properties: Set | null; + order: number | undefined; +}; function propertiesWritten({ startAt, ...vars }: Record): Set | null { const to = ownPropertiesWritten(vars); @@ -190,6 +196,7 @@ function writeOf(tween: PlacedTween, timeline: RuntimeTimelineLike): PropertyWri start: span[0], end: span[0] + span[1], properties: propertiesWritten(tween.vars ?? {}), + order: authoredOrderOf(tween, owner), } ); } @@ -210,6 +217,10 @@ function sharesAProperty(a: PropertyWrite, b: PropertyWrite): boolean { return !a.properties || !b.properties || [...a.properties].some((p) => b.properties!.has(p)); } +function writtenBefore(a: PropertyWrite, b: PropertyWrite): boolean { + return a.order !== undefined && b.order !== undefined && a.order < b.order; +} + function overlapsOnOneTarget(writes: PropertyWrite[]): OverlapSpan[] { const spans: OverlapSpan[] = []; writes.sort((x, y) => x.start - y.start); @@ -221,7 +232,7 @@ function overlapsOnOneTarget(writes: PropertyWrite[]): OverlapSpan[] { laterStart: second.start, sharedEnd: Math.min(first.end, second.end), earlierEnd: first.end, - laterIsSet: second.end === second.start, + laterIsSet: second.end === second.start && !writtenBefore(second, first), }); } }); @@ -377,7 +388,7 @@ const landingMarksCache = new WeakMap(); const LANDING_MARK_REACH = 0.05; -type GsapPlaced = { +export type GsapPlaced = { _start?: number; _ts?: number; _repeat?: number; diff --git a/packages/core/src/runtime/adapters/gsapAuthoredOrder.ts b/packages/core/src/runtime/adapters/gsapAuthoredOrder.ts new file mode 100644 index 0000000000..0a5d62a61c --- /dev/null +++ b/packages/core/src/runtime/adapters/gsapAuthoredOrder.ts @@ -0,0 +1,40 @@ +import type { GsapPlaced } from "./gsap"; + +// GSAP sorts a timeline's children by start time and keeps no record of the order a film wrote them in. A set written +// before the tween it sits inside is that tween's initial state; one written after it is an override of that tween. +type Stamped = { _hfAuthored?: number }; +type Adder = (this: { _recent?: Stamped }, ...args: unknown[]) => unknown; +type TimelineProto = Record & { _hfStamped?: true }; + +const ADDERS = ["to", "from", "fromTo", "set"] as const; +let written = 0; + +/** Numbers every child a timeline adds with `to`, `from`, `fromTo` and `set` by when the film wrote it. */ +export function stampAuthoredOrder(gsap: object | undefined): void { + const core = (gsap as { core?: { Timeline?: { prototype: object } } } | undefined)?.core; + const proto = core?.Timeline?.prototype as TimelineProto | undefined; + if (!proto || proto._hfStamped) return; + proto._hfStamped = true; + for (const name of ADDERS) { + const add = proto[name] as Adder; + proto[name] = function (this: { _recent?: Stamped }, ...args: unknown[]) { + const result = add.apply(this, args); + if (this._recent && this._recent._hfAuthored === undefined) + this._recent._hfAuthored = ++written; + return result; + }; + } +} + +/** When the film wrote the child of `owner` holding `tween`; undefined for a film built before the runtime loaded. */ +export function authoredOrderOf(tween: GsapPlaced, owner: object): number | undefined { + let order: number | undefined; + for ( + let node: GsapPlaced | null | undefined = tween; + node && node !== owner; + node = node.parent + ) { + order = (node as Stamped)._hfAuthored ?? order; + } + return order; +} diff --git a/packages/core/src/runtime/init.authoredOrder.test.ts b/packages/core/src/runtime/init.authoredOrder.test.ts new file mode 100644 index 0000000000..c32c600232 --- /dev/null +++ b/packages/core/src/runtime/init.authoredOrder.test.ts @@ -0,0 +1,16 @@ +import gsap from "gsap"; +import { expect, it } from "vitest"; +import { installFlatGsapTransforms } from "./init"; + +// Its own file: the stamp patches GSAP's Timeline once for the whole process. +it("numbers the order a film writes its tweens in when GSAP loads after the runtime", () => { + installFlatGsapTransforms(); + window.gsap = gsap as unknown as typeof window.gsap; + const timeline = gsap.timeline({ paused: true }); + timeline.set({ a: 0 }, { a: 1 }).to({ b: 0 }, { b: 1, duration: 1 }); + const [first, second] = timeline.getChildren(false, true, true) as unknown as { + _hfAuthored?: number; + }[]; + expect(first?._hfAuthored).toBeDefined(); + expect(second?._hfAuthored).toBeGreaterThan(first?._hfAuthored ?? Infinity); +}); diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts index 35d28eb7ab..8cb82321a7 100644 --- a/packages/core/src/runtime/init.ts +++ b/packages/core/src/runtime/init.ts @@ -71,6 +71,7 @@ import { seekGsapTimeline, type GsapStructureKey, } from "./adapters/gsap"; +import { stampAuthoredOrder } from "./adapters/gsapAuthoredOrder"; import { createAnimeJsAdapter } from "./adapters/animejs"; import { createLottieAdapter } from "./adapters/lottie"; import { createThreeAdapter } from "./adapters/three"; @@ -459,10 +460,13 @@ export function installAuthoredMediaCapture(): void { } // Mid-tween, GSAP's default force3D writes translate3d, and Chrome snaps a crop edge on it to whole pixels. -// Runs at script evaluation: GSAP is configured as its bundle assigns window.gsap, before a composition's -// set() or from() parses an element. Chains to an accessor already there (the producer's early stub). +// Runs at script evaluation, as GSAP's bundle assigns window.gsap and before a composition's set() or from() parses +// an element: force3D off, and tweens numbered by write order. Chains to an accessor already there (the early stub). export function installFlatGsapTransforms(): void { - const flatten = (g: Window["gsap"]) => g?.config?.({ force3D: false }); + const flatten = (g: Window["gsap"]) => { + g?.config?.({ force3D: false }); + stampAuthoredOrder(g); + }; const prior = Object.getOwnPropertyDescriptor(window, "gsap"); let loaded = window.gsap; flatten(loaded);