Skip to content

Write HTML. Render video. Built for agents.

fix(core): scrubbing back across a scene no longer leaves its content hidden (#5766)

Miguel Ángel4cf0e3a0e599
diff --git a/packages/core/src/runtime/adapters/gsap.steps.test.ts b/packages/core/src/runtime/adapters/gsap.steps.test.ts
index 93b148d2ca..1e2788e690 100644
--- a/packages/core/src/runtime/adapters/gsap.steps.test.ts
+++ b/packages/core/src/runtime/adapters/gsap.steps.test.ts
@@ -2,6 +2,7 @@
import gsap from "gsap";
import { describe, expect, it } from "vitest";
import { createGsapAdapter, rerenderGsapTimelineAt, seekGsapTimeline } from "./gsap";
+import type { GsapStructureKey } from "./gsap";
import type { RuntimeTimelineLike } from "../types";
// Every 0.1 s: hide all three frames, then show one, as frame-by-frame films do.
@@ -578,6 +579,135 @@ describe("seekGsapTimeline", () => {
seekGsapTimeline(film.timeline, 0.1, false);
expect(film.calls()).toBe(1);
});
+
+ const structures = new WeakMap<object, GsapStructureKey>();
+ const structureOf = (timeline: object) => {
+ if (!structures.has(timeline)) structures.set(timeline, { owner: timeline, version: "1" });
+ return structures.get(timeline)!;
+ };
+ // What init's root seek does: the shared seek, then its own redraw unless the seek already redrew.
+ const rootSeek = (timeline: RuntimeTimelineLike, t: number) => {
+ if (!seekGsapTimeline(timeline, t, false, structureOf(timeline)))
+ rerenderGsapTimelineAt(timeline as never, t, structureOf(timeline));
+ };
+ const sceneSeek = (timeline: RuntimeTimelineLike, t: number) =>
+ seekGsapTimeline(timeline, t, false, structureOf(timeline));
+
+ // A scene that reveals its content with steps at 0, as scenes built from template clones do.
+ function revealedAtZero() {
+ const field = document.body.appendChild(document.createElement("div"));
+ const timeline = gsap.timeline({ paused: true });
+ timeline.set(field, { visibility: "hidden" }, 0);
+ timeline.set(field, { visibility: "visible" }, 0);
+ timeline.to(field, { x: 100, duration: 2 }, 0);
+ timeline.set(field, { visibility: "hidden" }, 1.5);
+ return { field, timeline: timeline as unknown as RuntimeTimelineLike };
+ }
+
+ it("shows a scene's steps at 0 after the playhead comes back to 0 from later", () => {
+ const scene = revealedAtZero();
+ sceneSeek(scene.timeline, 1);
+ sceneSeek(scene.timeline, 0);
+ expect(scene.field.style.visibility).toBe("visible");
+ sceneSeek(scene.timeline, 0.5);
+ expect(scene.field.style.visibility).toBe("visible");
+ });
+
+ it("shows a nested scene's steps at 0 after its parent parks it there from later", () => {
+ const scene = revealedAtZero();
+ const root = gsap
+ .timeline({ paused: true })
+ .add(scene.timeline as unknown as gsap.core.Timeline, 6);
+ root.set({}, {}, 12);
+ // What a runtime seek does: the root, then the scene at its own time, held at 0 before it starts.
+ const seekBoth = (t: number) => {
+ root.totalTime(t);
+ sceneSeek(scene.timeline, Math.max(0, t - 6));
+ };
+ seekBoth(8);
+ seekBoth(5.9);
+ seekBoth(6.5);
+ expect(scene.field.style.visibility).toBe("visible");
+ });
+
+ it("shows two steps on one later time in authored order after the playhead comes back onto it", () => {
+ const word = document.body.appendChild(document.createElement("span"));
+ const timeline = gsap.timeline({ paused: true });
+ timeline.set(word, { visibility: "hidden" }, 1).set(word, { visibility: "visible" }, 1);
+ timeline.to({}, { duration: 3 }, 0);
+ const scene = timeline as unknown as RuntimeTimelineLike;
+ sceneSeek(scene, 2);
+ sceneSeek(scene, 1);
+ expect(word.style.visibility).toBe("visible");
+ sceneSeek(scene, 1.2);
+ expect(word.style.visibility).toBe("visible");
+ });
+
+ it("keeps a scene's steps at 0 through the root's redraw at 0 on every seek", () => {
+ const scene = revealedAtZero();
+ rootSeek(scene.timeline, 1);
+ rootSeek(scene.timeline, 0);
+ rootSeek(scene.timeline, 0);
+ expect(scene.field.style.visibility).toBe("visible");
+ });
+
+ const keyframeForms: Record<string, gsap.TweenVars> = {
+ "a keyframes array": { keyframes: [{ x: 10 }, { x: 100 }] },
+ "percent keyframes": { keyframes: { "0%": { x: 5 }, "100%": { x: 60 } } },
+ };
+ const keyframedAtZero = (form: string) => {
+ const o = { x: 0 };
+ const timeline = gsap.timeline({ paused: true });
+ timeline.to(o, { ...keyframeForms[form], duration: 1 }, 0).to({}, { duration: 3 }, 0);
+ return { o, timeline: timeline as unknown as RuntimeTimelineLike };
+ };
+ const landings: [string, number[]][] = [
+ ["root", [2, 0]],
+ ["root", [0.5, 0]],
+ ["root", [0.5, 0, 0, 0]],
+ ["scene", [0.5, 0, 0, 1 / 30]],
+ ["scene", [1, 0]],
+ ];
+
+ it.each(
+ Object.keys(keyframeForms).flatMap((form) =>
+ landings.map(([path, times]) => ({ form, path, times })),
+ ),
+ )("draws $form starting at 0 as plain GSAP does when the $path seeks $times", (landing) => {
+ const ours = keyframedAtZero(landing.form);
+ const plain = keyframedAtZero(landing.form);
+ for (const t of landing.times) {
+ (landing.path === "root" ? rootSeek : sceneSeek)(ours.timeline, t);
+ plain.timeline.totalTime!(t, false);
+ expect(ours.o.x).toBeCloseTo(plain.o.x, 6);
+ }
+ });
+
+ it("fires a call on the landing time as often as plain GSAP across back-and-forth seeks", () => {
+ const fires = (ours: boolean) => {
+ let calls = 0;
+ const word = document.body.appendChild(document.createElement("span"));
+ const timeline = gsap.timeline({ paused: true }).to({}, { duration: 3 }, 0);
+ timeline.set(word, { visibility: "hidden" }, 1).call(() => void calls++, [], 1);
+ timeline.set(word, { visibility: "visible" }, 1);
+ const scene = timeline as unknown as RuntimeTimelineLike;
+ for (const t of [2, 1, 1.5, 1, 0.5, 1, 2, 1, 1]) {
+ if (ours) sceneSeek(scene, t);
+ else timeline.totalTime(t, false);
+ }
+ return calls;
+ };
+ expect(fires(true)).toBe(fires(false));
+ });
+
+ it("never redraws a whole scene for a backward landing, on steps or between them", () => {
+ const scene = revealedAtZero();
+ sceneSeek(scene.timeline, 2);
+ expect(sceneSeek(scene.timeline, 1.5)).toBe(false);
+ expect(scene.field.style.visibility).toBe("hidden");
+ sceneSeek(scene.timeline, 2);
+ expect(sceneSeek(scene.timeline, 0.37)).toBe(false);
+ });
});
describe("rerenderGsapTimelineAt with a structure key", () => {
diff --git a/packages/core/src/runtime/adapters/gsap.ts b/packages/core/src/runtime/adapters/gsap.ts
index 6b4e9114b7..e89591f578 100644
--- a/packages/core/src/runtime/adapters/gsap.ts
+++ b/packages/core/src/runtime/adapters/gsap.ts
@@ -33,10 +33,7 @@ export function rerenderGsapTimelineAt(
);
for (const [child] of skipped) child._ts = 0;
try {
- const below = t >= REDRAW_STEP;
- timeline.totalTime(below ? t - REDRAW_STEP : t + REDRAW_STEP, true);
- primeTweensStartingAt(children, t, below ? REDRAW_STEP : 0);
- timeline.totalTime(t, true);
+ renderOntoInAuthoredOrder(timeline, children, t, structure);
} finally {
for (const [child, timeScale] of skipped) child._ts = timeScale;
for (const [parent, dur, tDur, end, dirty] of lengths) {
@@ -50,6 +47,31 @@ export function rerenderGsapTimelineAt(
}
}
+function renderOntoInAuthoredOrder(
+ timeline: Parameters<typeof rerenderGsapTimelineAt>[0],
+ children: unknown[],
+ t: number,
+ structure: GsapStructureKey | undefined,
+): void {
+ const below = t >= REDRAW_STEP;
+ timeline.totalTime(below ? t - REDRAW_STEP : t + REDRAW_STEP, true);
+ primeTweensStartingAt(children, t, below ? REDRAW_STEP : 0);
+ timeline.totalTime(t, true);
+ if (!below && structure) reapplyStepsInAuthoredOrder(timeline, structure, t);
+}
+
+function reapplyStepsInAuthoredOrder(
+ timeline: { getChildren?: RuntimeTimelineLike["getChildren"] },
+ structure: GsapStructureKey,
+ t: number,
+): void {
+ for (const step of stepsAt(timeline, structure, t)) {
+ const { ratio, _zTime, _act } = step;
+ step.render(0, true, true);
+ Object.assign(step, { ratio, _zTime, _act });
+ }
+}
+
type GsapRenderState = { _initted?: number };
function gsapNeverRendered(timeline: RuntimeTimelineLike): boolean {
@@ -68,14 +90,16 @@ export function seekGsapTimeline(
timeline: RuntimeTimelineLike,
t: number,
suppressEvents: boolean,
+ structure?: GsapStructureKey,
): boolean {
if (typeof timeline.totalTime !== "function") {
timeline.seek(t, suppressEvents);
return false;
}
- const gsapSkipsRenderInPlace = Number(timeline.totalTime()) === t;
+ const from = Number(timeline.totalTime());
timeline.totalTime(t, suppressEvents);
- if (!gsapSkipsRenderInPlace || !gsapNeverRendered(timeline)) return false;
+ if (t < from && structure) reapplyStepsInAuthoredOrder(timeline, structure, t);
+ if (from !== t || !gsapNeverRendered(timeline)) return false;
rerenderGsapTimelineAt(
{
totalTime: timeline.totalTime.bind(timeline),
@@ -83,6 +107,7 @@ export function seekGsapTimeline(
getChildren: timeline.getChildren?.bind(timeline),
},
t,
+ structure,
);
return true;
}
@@ -119,6 +144,10 @@ function childrenStartingAfter(
type GsapLandingMarks = { ratio: number; _zTime?: number; _act?: number };
+type GsapStep = GsapLandingMarks & {
+ render: (totalTime: number, suppressEvents: boolean, force: boolean) => unknown;
+};
+
function childrenWithLandingMarksIn(timeline: {
getChildren?: RuntimeTimelineLike["getChildren"];
}): GsapLandingMarks[] {
@@ -184,17 +213,39 @@ function firstPointFrom(points: PlacedMarks["points"], time: number): number {
return lo;
}
-function landingMarksOf(
+function placedLandingMarks(
timeline: { getChildren?: RuntimeTimelineLike["getChildren"] },
- structure: GsapStructureKey | undefined,
- t: number,
-): GsapLandingMarks[] {
- if (!structure) return childrenWithLandingMarksIn(timeline);
+ structure: GsapStructureKey,
+): PlacedMarks {
let placed = landingMarksCache.get(structure.owner);
if (placed?.version !== structure.version) {
placed = placeLandingMarks(timeline, structure);
landingMarksCache.set(structure.owner, placed);
}
+ return placed;
+}
+
+function stepsAt(
+ timeline: { getChildren?: RuntimeTimelineLike["getChildren"] },
+ structure: GsapStructureKey,
+ t: number,
+): GsapStep[] {
+ const { points } = placedLandingMarks(timeline, structure);
+ const steps: GsapStep[] = [];
+ for (let i = firstPointFrom(points, t - PLAYHEAD_FLOAT_NOISE); i < points.length; i++) {
+ if (points[i]!.at > t + PLAYHEAD_FLOAT_NOISE) break;
+ steps.push(points[i]!.mark as GsapStep);
+ }
+ return steps;
+}
+
+function landingMarksOf(
+ timeline: { getChildren?: RuntimeTimelineLike["getChildren"] },
+ structure: GsapStructureKey | undefined,
+ t: number,
+): GsapLandingMarks[] {
+ if (!structure) return childrenWithLandingMarksIn(timeline);
+ const placed = placedLandingMarks(timeline, structure);
const { points } = placed;
const near = [...placed.always];
const last = t + LANDING_MARK_REACH;
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 63be3b3fe5..c0de159a74 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -4388,6 +4388,14 @@ export function initSandboxRuntimeModular(): void {
let playingPollWitness = "";
let lastTickPlaying = false;
+ const gsapStructureOf = (timeline: RuntimeTimelineLike): GsapStructureKey | undefined =>
+ renderCaptureSeekStarted
+ ? undefined
+ : {
+ owner: timeline,
+ version: `${compositionTimingRevision}:${timeline.getChildren?.(false, true, true).length ?? 0}`,
+ };
+
const seekRuntimeTimeline = (
timeline: RuntimeTimelineLike,
timeSeconds: number,
@@ -4398,7 +4406,7 @@ export function initSandboxRuntimeModular(): void {
const suppressEvents = options?.suppressEvents === true;
// Guarded: a partial timeline without pause() must still get its seek.
pauseTimelineIfPossible(timeline);
- seekGsapTimeline(timeline, timeSeconds, suppressEvents);
+ seekGsapTimeline(timeline, timeSeconds, suppressEvents, gsapStructureOf(timeline));
} catch (err) {
swallow(swallowLabel, err);
}
@@ -4584,13 +4592,8 @@ export function initSandboxRuntimeModular(): void {
}
try {
if (typeof tl.totalTime === "function") {
- const redrawn = seekGsapTimeline(tl, tlSeekTime, suppressEvents);
- const structure = renderCaptureSeekStarted
- ? undefined
- : {
- owner: tl,
- version: `${compositionTimingRevision}:${tl.getChildren?.(false, true, true).length ?? 0}`,
- };
+ const structure = gsapStructureOf(tl);
+ const redrawn = seekGsapTimeline(tl, tlSeekTime, suppressEvents, structure);
if (!redrawn && !suppressEvents && !hasZeroDurationCallbackTween(tl, structure)) {
// The first seek is the only eventful one; the re-render only refreshes styles.
rerenderGsapTimelineAt(