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
This commit is contained in:
Miguel Ángel
2026-11-08 06:03:31 +00:00
committed by GitHub
parent 0f5914dc44
commit 75fe18c621
5 changed files with 157 additions and 7 deletions
@@ -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<number, number> {
const { cards, timeline } = setBeforeFadeIn();
const structure = { owner: timeline, version: "1" };
const opacity = new Map<number, number>();
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)]);
}
}
}
});
}
});
+14 -3
View File
@@ -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<string, unknown>;
targets?: () => object[];
};
type PropertyWrite = { start: number; end: number; properties: Set<string> | null };
type PropertyWrite = {
start: number;
end: number;
properties: Set<string> | null;
order: number | undefined;
};
function propertiesWritten({ startAt, ...vars }: Record<string, unknown>): Set<string> | 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<object, PlacedMarks>();
const LANDING_MARK_REACH = 0.05;
type GsapPlaced = {
export type GsapPlaced = {
_start?: number;
_ts?: number;
_repeat?: number;
@@ -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<string, unknown> & { _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;
}
@@ -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);
});
+7 -3
View File
@@ -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);