Skip to content

Write HTML. Render video. Built for agents.

30.3 KB
Raw Blame
// @vitest-environment happy-dom
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.
function steppedFilm() {
  const frames = [0, 1, 2].map(() => document.body.appendChild(document.createElement("div")));
  let calls = 0;
  const timeline = gsap.timeline({ paused: true });
  for (let k = 0; k < 30; k++) {
    timeline.set(frames, { visibility: "hidden" }, k * 0.1);
    timeline.set(frames[k % 3]!, { visibility: "visible" }, k * 0.1);
  }
  timeline.call(() => void calls++, [], 2.5);
  const adapter = createGsapAdapter({
    getTimeline: () => timeline as unknown as RuntimeTimelineLike,
  });
  const shown = () => frames.map((frame) => frame.style.visibility === "visible");
  return { timeline, adapter, shown, calls: () => calls };
}

describe("gsap adapter on a step", () => {
  it.each([0, 1, 2.7])("shows the step's frame when seeking onto it from %s s", (from) => {
    const film = steppedFilm();
    film.timeline.totalTime(from, true);
    film.adapter.seek({ time: 2.5 });
    expect(film.shown()).toEqual([false, true, false]);
  });

  it("fires a call on the step once when seeking onto it twice", () => {
    const film = steppedFilm();
    film.adapter.seek({ time: 2.5 });
    film.adapter.seek({ time: 2.5 });
    expect(film.calls()).toBe(1);
  });

  it("applies a set at 0 on a timeline that has not moved yet", () => {
    const intro = document.body.appendChild(document.createElement("div"));
    const timeline = gsap.timeline({ paused: true });
    timeline.set(intro, { display: "block" }, 0).to(intro, { opacity: 0, duration: 1 }, 1);
    intro.style.display = "none";
    createGsapAdapter({ getTimeline: () => timeline as unknown as RuntimeTimelineLike }).seek({
      time: 0,
    });
    expect(intro.style.display).toBe("block");
  });

  it("restores a value changed outside the timeline when seeking 0 again", () => {
    const box = document.body.appendChild(document.createElement("div"));
    const timeline = gsap.timeline({ paused: true });
    timeline.fromTo(box, { x: 10 }, { x: 100, duration: 1 }, 0);
    const adapter = createGsapAdapter({
      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
    });
    adapter.seek({ time: 0 });
    gsap.set(box, { x: 999 });
    adapter.seek({ time: 0 });
    expect(gsap.getProperty(box, "x")).toBe(10);
  });
});

describe("gsap adapter at a tween's start", () => {
  // Issue #5122: a render seeks every frame in order; only the from-vars set transformOrigin.
  it("keeps a fromTo's from-only values from the frame it starts on, with immediateRender off", () => {
    const box = document.body.appendChild(document.createElement("div"));
    const timeline = gsap.timeline({ paused: true });
    timeline.fromTo(
      box,
      { scale: 1.5, transformOrigin: "0% 0%" },
      { scale: 1, duration: 0.45, ease: "none", immediateRender: false },
      0.1,
    );
    timeline.set({}, {}, 1);
    const adapter = createGsapAdapter({
      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
    });
    const origins = [2, 3, 4, 5].map((frame) => {
      adapter.seek({ time: frame / 30 });
      return box.style.transformOrigin;
    });
    expect(origins).toEqual(["", "0% 0%", "0% 0%", "0% 0%"]);
    expect(gsap.getProperty(box, "scaleX")).toBeCloseTo(1.4259, 3);
  });

  it("keeps a keyframed fromTo's from-only values over an earlier tween's on the same element", () => {
    const box = document.body.appendChild(document.createElement("div"));
    const timeline = gsap.timeline({ paused: true });
    const fromTo = (origin: string, to: gsap.TweenVars, at: number) =>
      timeline.fromTo(
        box,
        { scale: 1.5, transformOrigin: origin },
        { scale: 1, immediateRender: false, ...to },
        at,
      );
    fromTo("0% 0%", { duration: 0.1 }, 0);
    fromTo("100% 100%", { duration: 0.1 }, 0.1);
    fromTo("0% 0%", { keyframes: { y: [0, 40] }, duration: 0.5 }, 0.2);
    timeline.set({}, {}, 1);
    const adapter = createGsapAdapter({
      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
    });
    const origins = [0, 2 / 30, 0.1, 4 / 30, 0.2, 7 / 30].map((time) => {
      adapter.seek({ time });
      return box.style.transformOrigin;
    });
    expect(origins.slice(1)).toEqual(["0% 0%", "100% 100%", "100% 100%", "0% 0%", "0% 0%"]);
  });

  it("keeps each staggered target's from-only values from the frame it starts on", () => {
    const film = () => {
      const boxes = [0, 1, 2].map(() => document.body.appendChild(document.createElement("div")));
      const timeline = gsap.timeline({ paused: true });
      timeline.fromTo(
        boxes,
        { scale: 1.5, transformOrigin: "0% 0%" },
        { scale: 1, duration: 0.3, stagger: 0.1, ease: "none", immediateRender: false },
        0.1,
      );
      timeline.set({}, {}, 1);
      return { boxes, timeline };
    };
    const played = film();
    const seeked = film();
    const adapter = createGsapAdapter({
      getTimeline: () => seeked.timeline as unknown as RuntimeTimelineLike,
    });
    for (let frame = 0; frame <= 12; frame++) {
      played.timeline.totalTime(frame / 30, false);
      adapter.seek({ time: frame / 30 });
      const origins = (film: { boxes: HTMLElement[] }) =>
        film.boxes.map((box) => box.style.transformOrigin);
      expect(origins(seeked), `frame ${frame}`).toEqual(origins(played));
    }
  });

  it("still lets a set authored later on the tween's start win over its from-values", () => {
    const box = document.body.appendChild(document.createElement("div"));
    const timeline = gsap.timeline({ paused: true });
    timeline.fromTo(
      box,
      { opacity: 0, transformOrigin: "0% 0%" },
      { opacity: 1, duration: 0.5, immediateRender: false },
      0.1,
    );
    timeline.set(box, { opacity: 0.3, transformOrigin: "100% 100%" }, 0.1);
    timeline.set({}, {}, 1);
    createGsapAdapter({ getTimeline: () => timeline as unknown as RuntimeTimelineLike }).seek({
      time: 0.1,
    });
    expect([box.style.opacity, box.style.transformOrigin]).toEqual(["0.3", "100% 100%"]);
  });

  // An edit at 2 s turns the later tween into keyframes; its first keyframe must win over the from() end.
  it.each([0, 1, 2, 2.5, 3])(
    "shows the tween that starts at the seek time, seeking from %s s",
    (from) => {
      const box = document.body.appendChild(document.createElement("div"));
      const timeline = gsap.timeline({ paused: true });
      timeline.from(box, { x: -60, duration: 2, ease: "none" }, 0);
      timeline.to(box, { keyframes: { "0%": { x: 5 }, "100%": { x: 60 } }, duration: 1 }, 2);
      timeline.totalTime(from, true);
      createGsapAdapter({ getTimeline: () => timeline as unknown as RuntimeTimelineLike }).seek({
        time: 2,
      });
      expect(gsap.getProperty(box, "x")).toBe(5);
    },
  );

  it("leaves a tween that starts later alone after a seek past the end", () => {
    const box = document.body.appendChild(document.createElement("div"));
    const timeline = gsap.timeline({ paused: true });
    timeline.to(box, { x: -400, duration: 0.4 }, 4.8);
    timeline.to(box, { x: 0, duration: 0.4 }, 16);
    const adapter = createGsapAdapter({
      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
    });
    for (const time of [20, 0, 4]) adapter.seek({ time });
    expect(gsap.getProperty(box, "x")).toBe(0);
  });

  it.each([
    { order: "keyframes, then a set", x: 42 },
    { order: "a set, then keyframes", x: 5 },
  ])("keeps the authored order of $order at the seek time", ({ order, x }) => {
    const box = document.body.appendChild(document.createElement("div"));
    const timeline = gsap.timeline({ paused: true });
    timeline.from(box, { x: -60, duration: 2, ease: "none" }, 0);
    const keyframes = () =>
      timeline.to(box, { keyframes: { "0%": { x: 5 }, "100%": { x: 60 } }, duration: 1 }, 2);
    const set = () => timeline.set(box, { x: 42 }, 2);
    if (order.startsWith("keyframes")) {
      keyframes();
      set();
    } else {
      set();
      keyframes();
    }
    const adapter = createGsapAdapter({
      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
    });
    for (const from of [0, 1, 2, 2.5, 3]) {
      timeline.totalTime(from, true);
      adapter.seek({ time: 2 });
      expect(gsap.getProperty(box, "x")).toBe(x);
    }
  });

  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("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);
  });

  it.each([
    {
      shape: "a stagger whose next target starts 0.1 us later with overwrite auto",
      build: (timeline: gsap.core.Timeline, o: { x: number }) => {
        timeline.to(o, { x: 100, duration: 10, ease: "none" }, 0);
        timeline.to([{ x: 0 }, o], { x: 200, duration: 1, stagger: 1e-7, overwrite: "auto" }, 2);
      },
      seeks: [2, 1],
      x: 10,
    },
    {
      shape: "a reversed keyframed tween",
      build: (timeline: gsap.core.Timeline, o: { x: number }) => {
        const tween = gsap.to(o, { keyframes: { "0%": { x: 5 }, "100%": { x: 60 } }, duration: 1 });
        timeline.add(tween, 1);
        tween.timeScale(-1);
      },
      seeks: [1],
      x: 60,
    },
    {
      shape: "a paused keyframed tween",
      build: (timeline: gsap.core.Timeline, o: { x: number }) => {
        const tween = gsap.to(o, {
          keyframes: { "0%": { x: 5 }, "100%": { x: 60 } },
          duration: 1,
          ease: "none",
        });
        timeline.add(tween, 1);
        tween.totalTime(0.5).pause();
      },
      seeks: [1, 1],
      x: 32.5,
    },
    {
      shape: "a 0.4 us repeatRefresh keyframed tween",
      build: (timeline: gsap.core.Timeline, o: { x: number }) => {
        const keyframes = [
          { x: "+=10", duration: 2e-7 },
          { x: "+=10", duration: 2e-7 },
        ];
        timeline.to(o, { keyframes, repeat: 2, repeatRefresh: true, ease: "none" }, 2);
      },
      seeks: [2, 2],
      x: 0,
    },
  ])("leaves $shape as GSAP renders it at its start", ({ build, seeks, x }) => {
    const o = { x: 0 };
    const timeline = gsap.timeline({ paused: true });
    build(timeline, o);
    const adapter = createGsapAdapter({
      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
    });
    for (const time of seeks) adapter.seek({ time });
    expect(o.x).toBeCloseTo(x, 6);
  });
});

describe("re-rendering onto a call at the playhead", () => {
  type Film = {
    build: (timeline: gsap.core.Timeline, fire: () => void) => void;
    at: number;
    to: number;
  };
  const nestedAt = (callAt: number, repeat = 0, speed = 1): Film["build"] => {
    return (timeline, fire) => {
      const scene = gsap.timeline({ repeat }).to({ y: 0 }, { y: 1, duration: 4 });
      scene.call(fire, [], callAt).timeScale(speed);
      timeline.add(scene, 1);
    };
  };
  const films: Record<string, Film> = {
    "a call on the playhead": { build: (tl, fire) => void tl.call(fire, [], 2), at: 2, to: 3 },
    "a call at 0 on a fresh timeline": {
      build: (tl, fire) => void tl.call(fire, [], 0),
      at: 0,
      to: 1,
    },
    "a reversed call": {
      build: (tl, fire) => void tl.call(fire, [], 2).getChildren().at(-1)!.reversed(true),
      at: 2,
      to: 3,
    },
    "a call in a nested timeline": { build: nestedAt(1), at: 2, to: 3 },
    "a call in a repeating nested timeline": { build: nestedAt(2, 1), at: 7, to: 8 },
    "a call in a nested timeline at double speed": { build: nestedAt(1, 0, 2), at: 1.5, to: 2 },
    "a call in an otherwise empty nested timeline": {
      build: (tl, fire) => void tl.add(gsap.timeline().call(fire), 2),
      at: 2,
      to: 3,
    },
  };

  it.each(Object.keys(films).flatMap((film) => [false, true].map((silent) => ({ film, silent }))))(
    "fires $film as often as without the redraw (arrived silently: $silent)",
    ({ film, silent }) => {
      const { build, at, to } = films[film]!;
      const fires = (redraw: boolean, arriveSilently = silent) => {
        let fired = 0;
        const timeline = gsap.timeline({ paused: true }).to({ x: 0 }, { x: 1, duration: 10 });
        build(timeline, () => void fired++);
        timeline.totalTime(at, arriveSilently);
        if (redraw) rerenderGsapTimelineAt(timeline, at);
        timeline.totalTime(to, false);
        return fired;
      };
      // GSAP itself never fires a call in an otherwise empty nested timeline arrived at silently.
      expect(fires(false, false)).toBeGreaterThan(0);
      expect(fires(true)).toBe(fires(false));
    },
  );
});

describe("re-rendering leaves the rest as the seek left it", () => {
  const shapes: Record<string, (timeline: gsap.core.Timeline, o: { x: number }) => void> = {
    "a reversed set": (tl, o) => void tl.set(o, { x: 100 }, 2).getChildren().at(-1)!.reversed(true),
    "an immediateRender set": (tl, o) => void tl.set(o, { x: 100, immediateRender: true }, 2),
    "a reversed set in a nested timeline playing over the playhead": (tl, o) => {
      const scene = gsap.timeline().to({ y: 0 }, { y: 1, duration: 4 });
      scene.set(o, { x: 100 }, 1.5).getChildren().at(-1)!.reversed(true);
      tl.add(scene, 0.5);
    },
    "a reversed nested timeline": (tl, o) => {
      const scene = gsap.timeline().to(o, { x: 100, duration: 1 });
      tl.add(scene, 2);
      scene.reversed(true);
    },
  };

  it.each(
    Object.keys(shapes).flatMap((shape) => [false, true].map((silent) => ({ shape, silent }))),
  )("draws $shape as without the redraw (arrived silently: $silent)", ({ shape, silent }) => {
    const draws = (redraw: boolean) => {
      const o = { x: 0 };
      const timeline = gsap.timeline({ paused: true }).to({ y: 0 }, { y: 1, duration: 10 });
      shapes[shape]!(timeline, o);
      timeline.totalTime(1, silent);
      if (redraw) rerenderGsapTimelineAt(timeline, 1);
      const atPlayhead = o.x;
      timeline.totalTime(1.01, false);
      return [atPlayhead, o.x];
    };
    expect(draws(true)).toEqual(draws(false));
  });

  it("keeps two sets on the playhead in authored order on the next seek", () => {
    const o = { x: 0 };
    const timeline = gsap.timeline({ paused: true }).to({ y: 0 }, { y: 1, duration: 10 });
    // Only the second set has a callback, so restoring callback tweens alone breaks the order.
    timeline.set(o, { x: 50 }, 2).set(o, { x: 100, onComplete: () => {} }, 2);
    timeline.totalTime(2, false);
    rerenderGsapTimelineAt(timeline, 2);
    timeline.totalTime(2.01, false);
    expect(o.x).toBe(100);
  });

  it("undraws a scene's opening set when stepping back off the scene's start", () => {
    const draws = (redraw: boolean) => {
      const o = { x: 0 };
      const timeline = gsap.timeline({ paused: true }).to({ y: 0 }, { y: 1, duration: 10 });
      timeline.add(gsap.timeline().set(o, { x: 100 }, 0).to({ z: 0 }, { z: 1, duration: 2 }), 2);
      timeline.totalTime(3, false);
      timeline.totalTime(2, false);
      if (redraw) rerenderGsapTimelineAt(timeline, 2);
      timeline.totalTime(1.99, false);
      return o.x;
    };
    expect(draws(true)).toBe(draws(false));
  });

  it("fires a pause in a reversed repeating scene as often as without the redraw", () => {
    const fires = (redraw: boolean) => {
      let fired = 0;
      const timeline = gsap.timeline({ paused: true }).to({ y: 0 }, { y: 1, duration: 10 });
      const scene = gsap.timeline({ repeat: 2, yoyo: true }).to({ z: 0 }, { z: 1, duration: 1 });
      scene.addPause(0, () => void fired++).timeScale(3);
      timeline.add(scene, 1);
      scene.reversed(true);
      timeline.progress(0.0001, true).totalTime(0, false);
      timeline.totalTime(3, true);
      if (redraw) rerenderGsapTimelineAt(timeline, 3);
      timeline.totalTime(2.99, false);
      return fired;
    };
    expect(fires(true)).toBe(fires(false));
  });

  it("renders every frame of style-5-prod's paused typed intro as without the redraw", () => {
    const frames = (redraw: boolean) => {
      const timeline = gsap.timeline({ paused: true }).to({ y: 0 }, { y: 1, duration: 10 });
      const scene = gsap.timeline({ paused: true });
      const typeLine = (text: string, start: number) => {
        const chars = text.split("").map(() => ({ opacity: 0 }));
        const cursor = { opacity: 0 };
        scene.set(cursor, { opacity: 1 }, start);
        chars.forEach((char, i) =>
          scene.to(char, { opacity: 1, duration: 0.01 }, start + i * 0.05),
        );
        const end = start + chars.length * 0.05;
        scene
          .to(cursor, { opacity: 0.25, duration: 0.1 }, end)
          .to(cursor, { opacity: 1, duration: 0.1 }, end + 0.1);
        scene.set(cursor, { opacity: 0 }, end + 0.2);
        return { chars, cursor, end: end + 0.5 };
      };
      const line1 = typeLine("SYSTEM BOOTING...", 0.2);
      const line2 = typeLine("EDITOR AGENT v1.0", line1.end);
      const container = { opacity: 0 };
      scene.fromTo(container, { opacity: 0.92 }, { opacity: 1, duration: 0.6 }, 0);
      timeline.add(scene, 0);
      const drawn: number[][] = [];
      for (let frame = 0; frame < 90; frame++) {
        scene.paused(false);
        timeline.totalTime(frame / 30, false);
        if (redraw) rerenderGsapTimelineAt(timeline, frame / 30);
        scene.paused(true);
        drawn.push(
          [...line1.chars, line1.cursor, ...line2.chars, line2.cursor, container].map(
            (o) => o.opacity,
          ),
        );
      }
      return drawn;
    };
    expect(frames(true)).toEqual(frames(false));
  });

  it("keeps the length of a timeline that grew after its last render", () => {
    const timeline = gsap.timeline({ paused: true }).to({ y: 0 }, { y: 1, duration: 10 });
    timeline.totalTime(1, true);
    timeline.set({ x: 0 }, { x: 100 }, 20);
    rerenderGsapTimelineAt(timeline, 1);
    expect(timeline.duration()).toBe(20);
  });
});

describe("gsap adapter just after a tween's start", () => {
  // Starts 0.5 ms before a frame, so the redraw's step down to 1 ms below that frame crosses its start.
  it("keeps a fromTo's from-only opacity on every frame of a sweep that a later set hides", () => {
    const bar = document.body.appendChild(document.createElement("div"));
    bar.style.opacity = "0";
    const timeline = gsap.timeline({ paused: true });
    timeline.fromTo(
      bar,
      { x: 1920, opacity: 1 },
      { x: -320, duration: 0.34, ease: "power2.inOut", immediateRender: false },
      0.4995,
    );
    timeline.set(bar, { opacity: 0 }, 0.85);
    timeline.set({}, {}, 2);
    const adapter = createGsapAdapter({
      getTimeline: () => timeline as unknown as RuntimeTimelineLike,
    });
    const shown: string[] = [];
    for (let frame = 0; frame <= 60; frame++) {
      adapter.seek({ time: frame / 30 });
      if (frame / 30 > 0.49 && frame / 30 < 0.84) shown.push(bar.style.opacity);
    }
    expect(new Set(shown)).toEqual(new Set(["1"]));
    expect(bar.style.opacity).toBe("0");
  });

  // A slow drift with a short move on the same property inside it: the drift resumes after the move, as in playback.
  it("renders overlapping tweens on one property as playback does", () => {
    const film = () => {
      const box = { y: 0 };
      const timeline = gsap.timeline({ paused: true });
      timeline.to(box, { y: 100, duration: 4, ease: "none" }, 0);
      timeline.to(box, { y: 300, duration: 0.5, ease: "none" }, 1);
      timeline.set({}, {}, 5);
      return { box, timeline };
    };
    const played = film();
    const seeked = film();
    const adapter = createGsapAdapter({
      getTimeline: () => seeked.timeline as unknown as RuntimeTimelineLike,
    });
    for (let frame = 0; frame <= 150; frame++) {
      played.timeline.totalTime(frame / 30);
      adapter.seek({ time: frame / 30 });
      expect(seeked.box.y, `frame ${frame}`).toBeCloseTo(played.box.y, 6);
    }
  });
});

describe("seekGsapTimeline", () => {
  function hiddenAtZero() {
    const word = document.body.appendChild(document.createElement("span"));
    let calls = 0;
    const timeline = gsap.timeline({ paused: true });
    timeline.set(word, { visibility: "hidden" }, 0);
    timeline.call(() => void calls++, [], 0);
    timeline.set(word, { visibility: "visible" }, 0.5);
    return { word, timeline: timeline as unknown as RuntimeTimelineLike, calls: () => calls };
  }

  it("renders a never-rendered timeline seeked to the time it sits at", () => {
    const film = hiddenAtZero();
    seekGsapTimeline(film.timeline, 0, false);
    expect(film.word.style.visibility).toBe("hidden");
  });

  it("redraws a timeline parked at one time once, not on every seek", () => {
    const film = hiddenAtZero();
    const real = film.timeline;
    let moves = 0;
    const counted = {
      ...real,
      time: () => real.time(),
      totalTime: (time?: number, suppressEvents?: boolean) => {
        if (time === undefined) return real.totalTime!();
        moves++;
        return real.totalTime!(time, suppressEvents);
      },
      getChildren: real.getChildren!.bind(real),
    } as RuntimeTimelineLike;
    seekGsapTimeline(counted, 0, false);
    const firstSeekMoves = moves;
    seekGsapTimeline(counted, 0, false);
    seekGsapTimeline(counted, 0, false);
    expect(firstSeekMoves).toBeGreaterThan(1);
    expect(moves - firstSeekMoves).toBe(2);
  });

  it("fires a call at that time once across the next seeks", () => {
    const film = hiddenAtZero();
    seekGsapTimeline(film.timeline, 0, false);
    seekGsapTimeline(film.timeline, 0, false);
    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", () => {
  // Steps at the root and inside a nested part that starts at 1 s, the shape of a caption track.
  function film() {
    const frames = [0, 1, 2].map(() => document.body.appendChild(document.createElement("div")));
    let calls = 0;
    const timeline = gsap.timeline({ paused: true });
    for (let k = 0; k < 20; k++) timeline.set(frames[k % 3]!, { opacity: k % 2 }, k * 0.1);
    const part = gsap.timeline();
    for (let k = 0; k < 20; k++) part.set(frames[(k + 1) % 3]!, { x: k }, k * 0.05);
    part.call(() => void calls++, [], 0.5);
    timeline.add(part, 1);
    const state = () => ({
      dom: frames.map((frame) => frame.getAttribute("style")),
      calls,
      marks: (timeline.getChildren(true, true, true) as unknown as GsapMarks[]).map((child) => [
        child.ratio,
        child._zTime,
        child._act,
      ]),
    });
    return { timeline, state };
  }
  type GsapMarks = { ratio: number; _zTime?: number; _act?: number };

  it("leaves the film exactly as a re-render that walks every child", () => {
    const plain = film();
    const keyed = film();
    const key = { owner: keyed.timeline, version: "1" };
    for (let frame = 0; frame <= 150; frame++) {
      const t = frame / 60;
      for (const [one, structure] of [
        [plain, undefined],
        [keyed, key],
      ] as const) {
        one.timeline.totalTime(t, false);
        rerenderGsapTimelineAt(
          {
            totalTime: one.timeline.totalTime.bind(one.timeline),
            totalDuration: one.timeline.totalDuration.bind(one.timeline),
            getChildren: one.timeline.getChildren.bind(
              one.timeline,
            ) as RuntimeTimelineLike["getChildren"],
          },
          t,
          structure,
        );
      }
      expect(keyed.state()).toEqual(plain.state());
    }
  });
});