fix(core): re-cross only the tweens that start at the seek time

The step up past the target (d5c5d79) initialised tweens starting within
the next millisecond, so an overwrite: "auto" tween killed the one before
it, and it crossed a repeatRefresh boundary sitting on the target. The
re-render is back to #4911's step from just below. That step skips a
keyframes or stagger tween already at its start (GSAP passes no start
crossing into the tween's own timeline), so after it each such tween that
starts exactly at the target, at any nesting depth, re-crosses its own
start alone. No other child moves.

Author: miguel-heygen

packages/core/scripts/test-hyperframe-runtime-seek.ts

@@ -102,7 +102,6 @@ function testGsapAdapterPreservesTotalTime(): void {
       { method: "pause" },
       { method: "totalTime", time: seekTime, suppressEvents: false },
       // Silent re-render arriving from below, so same-time steps apply in authored order
-      { method: "totalTime", time: seekTime + 0.001, suppressEvents: true },
       { method: "totalTime", time: seekTime - 0.001, suppressEvents: true },
       { method: "totalTime", time: seekTime, suppressEvents: true },
     ],

packages/core/src/runtime/adapters/gsap.steps.test.ts

@@ -89,4 +89,57 @@ describe("gsap adapter at a tween's start", () => {
     for (const time of [20, 0, 4]) adapter.seek({ time });
     expect(gsap.getProperty(box, "x")).toBe(0);
   });
+
+  it("shows a keyframed tween's start inside a nested timeline, seeking onto it twice", () => {
+    const box = document.body.appendChild(document.createElement("div"));
+    const timeline = gsap.timeline({ paused: true });
+    const scene = gsap.timeline();
+    scene.from(box, { x: -60, duration: 2, ease: "none" }, 0);
+    scene.to(box, { keyframes: { "0%": { x: 5 }, "100%": { x: 60 } }, duration: 1 }, 2);
+    timeline.add(scene, 0.5);
+    const adapter = createGsapAdapter({
+      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
+    });
+    adapter.seek({ time: 2.5 });
+    adapter.seek({ time: 2.5 });
+    expect(gsap.getProperty(box, "x")).toBe(5);
+  });
+
+  it("shows a staggered tween's start over an earlier tween's end", () => {
+    const boxes = [0, 1].map(() => document.body.appendChild(document.createElement("div")));
+    const timeline = gsap.timeline({ paused: true });
+    timeline.from(boxes, { x: -60, duration: 2, ease: "none" }, 0);
+    timeline.fromTo(boxes, { x: 5 }, { x: 60, duration: 1, stagger: 0.1 }, 2);
+    const adapter = createGsapAdapter({
+      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
+    });
+    adapter.seek({ time: 2 });
+    adapter.seek({ time: 2 });
+    expect(gsap.getProperty(boxes[0]!, "x")).toBe(5);
+  });
+
+  it("does not start a tween that begins just after the seek time", () => {
+    const box = document.body.appendChild(document.createElement("div"));
+    const timeline = gsap.timeline({ paused: true });
+    timeline.to(box, { x: 100, duration: 10, ease: "none" }, 0);
+    timeline.to(box, { x: 200, duration: 1, ease: "none", overwrite: "auto" }, 2.0005);
+    const adapter = createGsapAdapter({
+      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
+    });
+    adapter.seek({ time: 2 });
+    adapter.seek({ time: 1 });
+    expect(gsap.getProperty(box, "x")).toBe(10);
+  });
+
+  it("keeps a relative repeatRefresh tween on its iteration at a repeat boundary", () => {
+    const box = document.body.appendChild(document.createElement("div"));
+    const timeline = gsap.timeline({ paused: true });
+    timeline.to(box, { x: "+=10", duration: 1, repeat: 1, repeatRefresh: true, ease: "none" }, 0);
+    const adapter = createGsapAdapter({
+      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
+    });
+    adapter.seek({ time: 1 });
+    adapter.seek({ time: 1 });
+    expect(gsap.getProperty(box, "x")).toBe(10);
+  });
 });

packages/core/src/runtime/adapters/gsap.ts

@@ -1,20 +1,43 @@
-import type { RuntimeDeterministicAdapter, RuntimeTimelineLike } from "../types";
+import type {
+  RuntimeDeterministicAdapter,
+  RuntimeTimelineChildLike,
+  RuntimeTimelineLike,
+} from "../types";
 
 type GsapAdapterDeps = {
   getTimeline: () => RuntimeTimelineLike | null;
 };
 
 /**
- * Re-renders a timeline already at `t`, silently: just above, just below (not below 0), then `t`. The last move
- * is forward so same-time steps apply in authored order, and a child starting exactly at `t` crosses its start.
+ * Re-renders a timeline already at `t`, silently, from just below (above at 0) so same-time steps apply in authored
+ * order. That step skips a keyframes or stagger tween already at its start, so each one re-crosses its start alone.
  */
 export function rerenderGsapTimelineAt(
-  timeline: { totalTime: (time: number, suppressEvents?: boolean) => unknown },
+  timeline: {
+    totalTime: (time: number, suppressEvents?: boolean) => unknown;
+    getChildren?: RuntimeTimelineLike["getChildren"];
+  },
   t: number,
 ): void {
-  timeline.totalTime(t + 0.001, true);
-  if (t >= 0.001) timeline.totalTime(t - 0.001, true);
+  timeline.totalTime(t >= 0.001 ? t - 0.001 : t + 0.001, true);
   timeline.totalTime(t, true);
+  recrossTweensStartingAt(timeline, t);
+}
+
+function recrossTweensStartingAt(
+  timeline: Pick<RuntimeTimelineChildLike, "getChildren">,
+  time: number,
+): void {
+  for (const child of timeline.getChildren?.(false, true, true) ?? []) {
+    const local = (time - (child.startTime?.() ?? 0)) * (child.timeScale?.() ?? 1);
+    if (Math.abs(local) < 1e-9 && child.timeline && child.render) {
+      child.render(0.001, true);
+      child.render(-0.001, true);
+      child.render(0, true);
+    } else if (child.getChildren && local > 0 && local <= (child.totalDuration?.() ?? 0)) {
+      recrossTweensStartingAt(child, local);
+    }
+  }
 }
 
 export function createGsapAdapter(deps: GsapAdapterDeps): RuntimeDeterministicAdapter {
@@ -29,7 +52,13 @@ export function createGsapAdapter(deps: GsapAdapterDeps): RuntimeDeterministicAd
       const suppressEvents = ctx.suppressEvents === true;
       if (typeof timeline.totalTime === "function") {
         timeline.totalTime(safeTime, suppressEvents);
-        rerenderGsapTimelineAt({ totalTime: timeline.totalTime.bind(timeline) }, safeTime);
+        rerenderGsapTimelineAt(
+          {
+            totalTime: timeline.totalTime.bind(timeline),
+            getChildren: timeline.getChildren?.bind(timeline),
+          },
+          safeTime,
+        );
       } else {
         timeline.seek(safeTime, suppressEvents);
       }

packages/core/src/runtime/init.test.ts

@@ -2851,7 +2851,6 @@ describe("initSandboxRuntimeModular", () => {
 
     expect(seekCalls).toEqual([
       { time: 2, suppressEvents: false },
-      { time: 2.001, suppressEvents: true },
       { time: 1.999, suppressEvents: true },
       { time: 2, suppressEvents: true },
     ]);

packages/core/src/runtime/init.ts

@@ -4361,7 +4361,10 @@ export function initSandboxRuntimeModular(): void {
           tl.totalTime(tlSeekTime, suppressEvents);
           if (!suppressEvents && !hasZeroDurationCallbackTween(tl)) {
             // The first seek is the only eventful one; the re-render only refreshes styles.
-            rerenderGsapTimelineAt({ totalTime: tl.totalTime.bind(tl) }, tlSeekTime);
+            rerenderGsapTimelineAt(
+              { totalTime: tl.totalTime.bind(tl), getChildren: tl.getChildren?.bind(tl) },
+              tlSeekTime,
+            );
           }
         } else {
           tl.seek(tlSeekTime, suppressEvents);

packages/core/src/runtime/types.ts

@@ -294,9 +294,13 @@ export type RuntimeTimelineChildLike = {
   vars?: unknown;
   startTime?: () => number;
   duration?: () => number;
+  totalDuration?: () => number;
+  timeScale?: () => number;
   data?: unknown;
   parent?: RuntimeTimelineChildLike;
   getChildren?: RuntimeTimelineLike["getChildren"];
+  timeline?: unknown;
+  render?: (totalTime: number, suppressEvents?: boolean) => unknown;
 };
 
 /** A timeline or tween a composition script started, as a scene swap stops it. */