Skip to content

Write HTML. Render video. Built for agents.

23.4 KB
Raw Blame
import gsap from "gsap";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { initSandboxRuntimeModular } from "./init";
import type { RuntimeTimelineLike } from "./types";
import { STUDIO_MANUAL_EDIT_GESTURE_ATTR } from "../editing/draftMarkers";
import { sourceTimeAt } from "../speedRamp";
import { readElementRateSpec } from "./playbackRate";
import {
  createMockTimeline,
  resetRuntimeFixtureDom,
  stubDuration,
} from "./runtimeSeekFixture.test-helpers";

// Pins where a running runtime places a sub-composition's timeline, against what a fresh load does.
describe("runtime sub-composition placement", () => {
  beforeEach(() => {
    resetRuntimeFixtureDom();
    window.gsap = gsap as unknown as typeof window.gsap;
  });

  afterEach(() => {
    window.__hfRuntimeTeardown?.();
    vi.restoreAllMocks();
    vi.unstubAllGlobals();
    delete window.__player;
    delete window.__playerReady;
    delete window.__hf;
  });

  /** A root with one scene clip at `hostStart`, whose timeline slides `#s` from 0 to 100 over 2 s. */
  function load(hostStart: number | string) {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true" data-duration="10">` +
      `<div id="host" class="clip" data-composition-id="scene" data-start="${hostStart}" data-duration="3">` +
      `<div id="s"></div></div></div>`;
    const scene = gsap
      .timeline({ paused: true })
      .to("#s", { x: 100, duration: 2, ease: "none" }, 0);
    const root = gsap.timeline({ paused: true }).to({}, { duration: 1 }, 0);
    window.__timelines = { main: root, scene } as unknown as Record<string, RuntimeTimelineLike>;
    initSandboxRuntimeModular();
    return { scene, root };
  }

  const shownX = () => Number(gsap.getProperty("#s", "x"));

  it("places the scene at its host's new start when a rebind follows a host move, as a fresh load does", () => {
    const { scene } = load(1);
    window.__player?.seek(5);
    expect(shownX()).toBe(100);

    document.getElementById("host")!.setAttribute("data-start", "4");
    window.__hfForceTimelineRebind?.();

    expect(scene.startTime()).toBe(4);
    expect(shownX()).toBe(50);
    window.__player?.seek(4.5);
    expect(shownX()).toBe(25);
  });

  it("leaves a scene where the root script places it after a re-run, as a fresh load does", () => {
    const { scene } = load(1);
    const root = gsap.timeline({ paused: true }).to({}, { duration: 1 }, 0).add(scene, 2);
    window.__timelines = { main: root, scene } as unknown as Record<string, RuntimeTimelineLike>;
    window.__hfForceTimelineRebind?.();
    expect(scene.startTime()).toBe(2);

    document.getElementById("host")!.setAttribute("data-start", "4");
    window.__hfForceTimelineRebind?.();

    expect(scene.startTime()).toBe(2);
  });

  it("leaves a scene that a script moved into another timeline where that timeline put it", () => {
    const { root, scene } = load(1);
    const holder = gsap.timeline({ paused: true });
    root.add(holder, 0);
    holder.add(scene, 2);

    document.getElementById("host")!.setAttribute("data-start", "4");
    window.__hfForceTimelineRebind?.();

    expect(scene.parent).toBe(holder);
    expect(scene.startTime()).toBe(2);
  });

  it("still moves a runtime-placed scene when the root script placed another one itself", () => {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true" data-duration="10">` +
      // Listed first, so a throw on the script-placed intro would stop the loop before the scene.
      `<div class="clip" data-composition-id="intro" data-start="2.5" data-duration="2"></div>` +
      `<div id="host" class="clip" data-composition-id="scene" data-start="1" data-duration="3"></div></div>`;
    const intro = gsap.timeline({ paused: true }).to({}, { duration: 2 }, 0);
    const scene = gsap.timeline({ paused: true }).to({}, { duration: 3 }, 0);
    const root = gsap.timeline({ paused: true }).to({}, { duration: 1 }, 0).add(intro, 2);
    window.__timelines = { main: root, intro, scene } as unknown as Record<
      string,
      RuntimeTimelineLike
    >;
    initSandboxRuntimeModular();

    document.getElementById("host")!.setAttribute("data-start", "4");
    window.__hfForceTimelineRebind?.();

    expect(scene.startTime()).toBe(4);
    expect(intro.startTime()).toBe(2);
  });

  /** Transport frames on demand; the clock moves a second per frame, past the change-service rate limit. */
  function stubFrames() {
    const frames = new Map<number, FrameRequestCallback>();
    let next = 0;
    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
      frames.set(++next, cb);
      return next;
    });
    vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
    let now = Date.now();
    vi.spyOn(Date, "now").mockImplementation(() => now);
    return async (count: number) => {
      for (let frame = 1; frame <= count; frame++) {
        now += 1000;
        await Promise.resolve();
        const due = [...frames.values()];
        frames.clear();
        for (const run of due) run(frame * 16);
      }
    };
  }

  /** A root with no timeline of its own around one scene clip, whose timeline slides `#s` from 0 to 100 over 4 s. */
  function loadWithoutRootTimeline(rootMarkup = "", rootLength = ` data-duration="10"`) {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true"${rootLength}>${rootMarkup}` +
      `<div id="host" class="clip" data-composition-id="scene" data-start="1" data-duration="4">` +
      `<div id="s"></div></div></div>`;
    const scene = gsap
      .timeline({ paused: true })
      .to("#s", { x: 100, duration: 4, ease: "none" }, 0);
    window.__timelines = { scene } as unknown as Record<string, RuntimeTimelineLike>;
    initSandboxRuntimeModular();
    return scene;
  }

  it("keeps a nested scene where the playhead left it during a drag when the root has no timeline", async () => {
    const runFrames = stubFrames();
    loadWithoutRootTimeline();
    window.__player?.seek(4);
    expect(shownX()).toBe(75);

    // Every transform GSAP writes while the drag is held, including ones a later write in the same tick hides.
    const shown: string[] = [];
    const writes = new MutationObserver((records) =>
      shown.push(...records.map((r) => r.oldValue ?? "")),
    );
    writes.observe(document.getElementById("s")!, {
      attributes: true,
      attributeFilter: ["style"],
      attributeOldValue: true,
    });
    // A Studio press marks the element; a timing edit then wakes the transport's rebind mid-drag.
    document.getElementById("s")!.setAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR, "gesture-1:move");
    document.getElementById("host")!.setAttribute("data-duration", "4");
    await runFrames(30);

    shown.push(
      ...writes.takeRecords().map((r) => r.oldValue ?? ""),
      document.getElementById("s")!.getAttribute("style") ?? "",
    );
    writes.disconnect();
    const xs = shown.map((style) => /translate(?:3d)?\(([-\d.]+)/.exec(style)?.[1]).filter(Boolean);
    expect(xs.length).toBeGreaterThan(0);
    expect(new Set(xs)).toEqual(new Set(["75"]));
  });

  it("keeps a dragged scene where the playhead left it when another scene registers mid-drag", async () => {
    const runFrames = stubFrames();
    loadWithoutRootTimeline(
      `<div id="later" class="clip" data-composition-id="later" data-start="0" data-duration="2"><div id="l"></div></div>`,
    );
    window.__player?.seek(4);
    document.getElementById("s")!.setAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR, "gesture-1:move");
    (window.__timelines as Record<string, unknown>).later = gsap
      .timeline({ paused: true })
      .to("#l", { x: 100, duration: 2, ease: "none" }, 0);
    await runFrames(30);

    expect(shownX()).toBe(75);
  });

  it("reports a scene's new length after a script extends it, when the root declares none", async () => {
    const runFrames = stubFrames();
    const scene = loadWithoutRootTimeline("", "");
    await runFrames(3);
    window.__player?.seek(2);
    scene.to({}, { duration: 8 }, 0);
    await runFrames(5);

    expect(window.__player?.getDuration()).toBe(9);
  });

  it("rests a scene's longer animation at its clip's end, where the clip hides", () => {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true" data-duration="10">` +
      `<div id="host" class="clip" data-composition-id="scene" data-start="1" data-duration="2">` +
      `<div id="s"></div></div></div>`;
    let renders = 0;
    const scene = gsap
      .timeline({ paused: true })
      .to("#s", { x: 100, duration: 8, ease: "none", onUpdate: () => renders++ }, 0);
    const root = gsap.timeline({ paused: true }).to({}, { duration: 10 }, 0);
    window.__timelines = { main: root, scene } as unknown as Record<string, RuntimeTimelineLike>;
    initSandboxRuntimeModular();

    window.__player?.seek(2);
    expect(shownX()).toBe(12.5);
    window.__player?.seek(5);
    expect(shownX()).toBe(25);
    expect(getComputedStyle(document.getElementById("host")!).visibility).toBe("hidden");
    renders = 0;
    window.__player?.seek(6);
    expect(renders).toBe(0);
  });

  it("keeps a slow scene with no clip window animating while it shows", () => {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true" data-duration="20">` +
      `<div id="host" data-composition-id="scene" data-playback-rate="0.5">` +
      `<div id="s"></div></div></div>`;
    const scene = gsap
      .timeline({ paused: true })
      .to("#s", { x: 100, duration: 8, ease: "none" }, 0);
    const root = gsap.timeline({ paused: true }).to({}, { duration: 20 }, 0);
    window.__timelines = { main: root, scene } as unknown as Record<string, RuntimeTimelineLike>;
    initSandboxRuntimeModular();

    window.__player?.seek(6);
    window.__player?.seek(12);
    expect(shownX()).toBe(75);
  });

  it("keeps a slow scene Studio stamped animating past its stamp, once the root has grown", () => {
    const parent = window.parent;
    Object.defineProperty(window, "parent", { configurable: true, value: {} });
    try {
      // What Studio leaves after a root extension: the host's discovery stamp still ends at 10 s.
      document.body.innerHTML =
        `<div data-composition-id="main" data-root="true" data-duration="20">` +
        `<div id="host" style="position: absolute" data-composition-id="scene" data-playback-rate="0.5"` +
        ` data-start="0" data-duration="10" data-hf-autostamped="1"><div id="s"></div></div></div>`;
      const scene = gsap
        .timeline({ paused: true })
        .to("#s", { x: 100, duration: 8, ease: "none" }, 0);
      const root = gsap.timeline({ paused: true }).to({}, { duration: 20 }, 0);
      window.__timelines = { main: root, scene } as unknown as Record<string, RuntimeTimelineLike>;
      initSandboxRuntimeModular();

      window.__player?.seek(6);
      window.__player?.seek(12);
      expect(shownX()).toBe(75);
      expect(getComputedStyle(document.getElementById("host")!).visibility).not.toBe("hidden");
    } finally {
      Object.defineProperty(window, "parent", { configurable: true, value: parent });
    }
  });

  it("renders a scene past its clip's end where root propagation leaves it, replaying no callbacks", () => {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true" data-duration="10">` +
      `<div id="host" class="clip" data-composition-id="scene" data-start="1" data-duration="2">` +
      `<div id="s"></div></div></div>`;
    let callbacks = 0;
    const scene = gsap.timeline({ paused: true }).to(
      "#s",
      {
        x: 100,
        duration: 8,
        ease: "none",
        onUpdate: () => callbacks++,
        onComplete: () => callbacks++,
      },
      0,
    );
    const root = gsap.timeline({ paused: true }).to({}, { duration: 10 }, 0);
    window.__timelines = { main: root, scene } as unknown as Record<string, RuntimeTimelineLike>;
    initSandboxRuntimeModular();

    window.__player?.renderSeek(9.1);
    expect(shownX()).toBe(100);
    callbacks = 0;
    window.__player?.renderSeek(9.2);
    window.__player?.renderSeek(9.3, { suppressEvents: true });
    expect(callbacks).toBe(0);
  });

  it("keeps the scene in one root after a tween first renders, when the root's own timeline is empty", async () => {
    const runFrames = stubFrames();
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true" data-duration="10">` +
      `<div id="host" class="clip" data-composition-id="scene" data-start="1" data-duration="9">` +
      `<div id="s"></div></div></div>`;
    const scene = gsap
      .timeline({ paused: true })
      .fromTo("#s", { x: -100 }, { x: 0, duration: 0.5, ease: "none" }, 0.5)
      .to({}, { duration: 9 }, 0);
    const root = gsap.timeline({ paused: true });
    window.__timelines = { main: root, scene } as unknown as Record<string, RuntimeTimelineLike>;
    initSandboxRuntimeModular();
    window.__player?.seek(1.2);
    const bound = scene.parent;

    window.__player?.seek(3);
    await runFrames(6);

    expect(scene.parent).toBe(bound);
    expect(shownX()).toBe(0);
  });

  it("binds a root timeline that registers after the runtime started on its children", async () => {
    const runFrames = stubFrames();
    loadWithoutRootTimeline(`<div id="r"></div>`);
    const root = gsap
      .timeline({ paused: true })
      .to("#r", { x: 100, duration: 10, ease: "none" }, 0);
    (window.__timelines as Record<string, unknown>).main = root;
    await runFrames(30);

    window.__player?.seek(5);
    expect(Number(gsap.getProperty("#r", "x"))).toBe(50);
    expect(shownX()).toBe(100);
  });

  it("places a scene at its host's new start on a rebind when the root has no timeline", () => {
    const scene = loadWithoutRootTimeline();
    document.getElementById("host")!.setAttribute("data-start", "4");
    window.__hfForceTimelineRebind?.();

    expect(scene.startTime()).toBe(4);
    window.__player?.seek(5);
    expect(shownX()).toBe(25);
  });

  it("leaves an unmoved scene in place on a rebind, whatever its start rounds to", () => {
    const { root, scene } = load("0.33333333");
    const remove = vi.spyOn(root, "remove");

    window.__hfForceTimelineRebind?.();

    expect(remove).not.toHaveBeenCalledWith(scene);
  });

  /** What Studio's split writes for a 12 s scene cut at 5 s and 9 s, each half mounting its own copy. */
  function loadSplitScene() {
    const videos = [
      ["v1", 0, 1],
      ["v2", 4, 5],
      ["v3", 8, 2],
    ]
      .map(
        ([name, start, mediaStart]) =>
          `<video class="${name}" data-start="${start}" data-duration="4" data-media-start="${mediaStart}"></video>`,
      )
      .join("");
    const hosts = [
      ["scene", 0, 5, 0],
      ["scene-split", 5, 4, 5],
      ["scene-split-split", 9, 3, 9],
    ]
      .map(
        ([id, start, duration, inPoint]) =>
          `<div id="${id}" class="clip" data-composition-id="${id}" data-composition-file="compositions/scene.html" ` +
          `data-start="${start}" data-duration="${duration}" data-playback-start="${inPoint}"><div>${videos}</div></div>`,
      )
      .join("");
    mountInRoot(hosts);
  }

  /** A 12 s root around `markup`; every video's source runs `sourceSeconds` and has not been seeked (-1). */
  function mountInRoot(markup: string, sourceSeconds = 30) {
    document.body.innerHTML = `<div data-composition-id="main" data-root="true" data-duration="12">${markup}</div>`;
    for (const video of document.querySelectorAll("video")) {
      stubDuration(video, sourceSeconds);
      Object.defineProperty(video, "currentTime", {
        value: -1,
        writable: true,
        configurable: true,
      });
      video.play = vi.fn(() => Promise.resolve());
      video.pause = vi.fn();
    }
    window.__timelines = { main: createMockTimeline(12) };
    initSandboxRuntimeModular();
  }

  /** The half after a split at 5 s: it starts at 5 with in-point 5, so scene time t plays at t. */
  function loadSecondHalf(inner: string, sourceSeconds?: number) {
    mountInRoot(
      `<div class="clip" data-composition-id="half" data-composition-file="compositions/scene.html" ` +
        `data-start="5" data-duration="7" data-playback-start="5"><div>${inner}</div></div>`,
      sourceSeconds,
    );
  }

  const video = (id: string) => document.getElementById(id) as HTMLVideoElement;

  const sourceTimeOf = (host: string, video: string) =>
    document.querySelector<HTMLVideoElement>(`#${host} .${video}`)!.currentTime;

  it("shifts a split scene's videos by each half's in-point and cuts them to that half", () => {
    loadSplitScene();
    window.__player?.renderSeek(4.5);
    expect(sourceTimeOf("scene", "v2")).toBe(5.5);
    // The second half's v2 lands at 4-8 but is cut until that half starts at 5.
    expect(sourceTimeOf("scene-split", "v2")).toBe(-1);

    window.__player?.renderSeek(5);
    expect(sourceTimeOf("scene-split", "v2")).toBe(6);
    window.__player?.renderSeek(8.5);
    expect(sourceTimeOf("scene-split", "v3")).toBe(2.5);
    window.__player?.renderSeek(10);
    expect(sourceTimeOf("scene-split-split", "v3")).toBe(4);
  });

  it("lets a scene's video play past a shorter root animation when the root authors no length", () => {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true">` +
      `<div class="clip" data-composition-id="scene" data-composition-file="compositions/scene.html" data-start="0" data-duration="10">` +
      `<video id="long" data-start="0" data-duration="10"></video></div></div>`;
    stubDuration(video("long"), 10);
    Object.defineProperty(video("long"), "currentTime", { value: -1, writable: true });
    video("long").play = vi.fn(() => Promise.resolve());
    video("long").pause = vi.fn();
    // The root's own timeline is a 2 s title fade.
    window.__timelines = { main: createMockTimeline(2) };
    initSandboxRuntimeModular();

    const at = (t: number) => (window.__player?.renderSeek(t), video("long").currentTime);
    expect([at(1), at(5), at(8)]).toEqual([1, 5, 8]);
  });

  it("keeps a scene trimmed to 3 s driving its 6 s file past the trim, as before in-points", () => {
    mountInRoot(
      `<div id="scene" class="clip" data-composition-id="scene" data-composition-file="compositions/scene.html" ` +
        `data-start="2" data-duration="3" data-playback-start="0">` +
        `<div data-composition-id="scene" data-duration="6"><video id="body" data-start="0"></video></div></div>`,
    );
    window.__player?.renderSeek(6);
    expect(video("body").currentTime).toBe(4);
  });

  it("cuts a split half that has no id at its own end, not its file's", () => {
    // Studio's split of a host without an id: the half is found by its composition attributes.
    mountInRoot(
      `<div class="clip" data-composition-file="compositions/scene.html" data-start="5" data-duration="4" ` +
        `data-playback-start="5"><div data-composition-id="scene" data-duration="12">` +
        `<video id="late" data-start="8" data-duration="4"></video></div></div>`,
    );
    window.__player?.renderSeek(8.5);
    expect(video("late").currentTime).toBe(0.5);
    window.__player?.renderSeek(10);
    expect(video("late").currentTime).toBe(0.5);
  });

  it("keeps a video in a composition nested inside the half silent until the half starts", () => {
    loadSecondHalf(
      `<div data-composition-id="inner" data-composition-file="compositions/inner.html" data-start="0" data-duration="12">` +
        `<video id="deep" data-start="0" data-duration="12"></video></div>`,
    );
    window.__player?.renderSeek(1);
    expect(video("deep").currentTime).toBe(-1);
    window.__player?.renderSeek(6);
    expect(video("deep").currentTime).toBe(6);
  });

  it("loops a straddling clip over its whole file, not from the cut", () => {
    loadSecondHalf(
      `<video id="loop" loop data-start="2" data-duration="10" data-media-start="0"></video>`,
      4,
    );
    const at = (t: number) => (window.__player?.renderSeek(t), video("loop").currentTime);
    expect([at(5), at(6), at(7.5)]).toEqual([3, 0, 1.5]);
  });

  it("follows a straddling clip's speed ramp from the clip's own start", () => {
    const ramp = JSON.stringify({
      version: 1,
      lanes: [
        {
          target: "rate",
          points: [
            { t: 0, v: 1 },
            { t: 8, v: 2 },
          ],
        },
      ],
    });
    loadSecondHalf(
      `<video id="ramp" data-start="2" data-duration="8" data-automation='${ramp}'></video>`,
    );
    window.__player?.renderSeek(7);
    expect(video("ramp").currentTime).toBeCloseTo(
      sourceTimeAt(readElementRateSpec(video("ramp")), 5),
      6,
    );
  });

  it("times a straddling clip's fade-out from the clip's own end", () => {
    loadSecondHalf(`<video id="fade" data-start="4" data-duration="4" data-fade-out="2"></video>`);
    window.__player?.renderSeek(7);
    expect(video("fade").volume).toBeCloseTo(0.5, 6);
  });

  it("times a straddling clip's fade-in from the clip's own start", () => {
    loadSecondHalf(`<video id="fade" data-start="4" data-duration="4" data-fade-in="2"></video>`);
    window.__player?.renderSeek(5);
    expect(video("fade").volume).toBeCloseTo(0.5, 6);
  });
});

// The producer's tween-batching stub registers stand-ins: the same methods on another object, the timeline behind it.
function standIn(real: gsap.core.Timeline): RuntimeTimelineLike {
  const proxy: Record<string, unknown> = { __hfIsProxy: true, __hfReal: real };
  const unwrap = (arg: unknown) => (arg as { __hfReal?: unknown } | null)?.__hfReal ?? arg;
  for (let o: object | null = real; o && o !== Object.prototype; o = Object.getPrototypeOf(o)) {
    for (const key of Object.getOwnPropertyNames(o)) {
      const method = (real as unknown as Record<string, unknown>)[key];
      if (key === "constructor" || key in proxy || typeof method !== "function") continue;
      proxy[key] = (...args: unknown[]) => {
        const out = (method as (...a: unknown[]) => unknown).apply(real, args.map(unwrap));
        return out === real ? proxy : out;
      };
    }
  }
  return proxy as unknown as RuntimeTimelineLike;
}

describe("runtime placement of timelines registered as stand-ins", () => {
  beforeEach(() => {
    resetRuntimeFixtureDom();
    window.gsap = gsap as unknown as typeof window.gsap;
  });

  afterEach(() => {
    window.__hfRuntimeTeardown?.();
    vi.restoreAllMocks();
    delete window.__player;
    delete window.__playerReady;
    delete window.__hf;
  });

  // A card flies in at 0.5 s, its from-vars showing it, hidden from 0 by a fromTo authored after it.
  function cardScene(card: Element | object) {
    const scene = gsap.timeline({ paused: true });
    scene.fromTo(card, { x: -600, opacity: 1 }, { x: 0, duration: 0.34 }, 0.5);
    scene.fromTo([card], { opacity: 0 }, { opacity: 0, duration: 0.01 }, 0);
    return scene;
  }

  it("keeps a scene's fly-in on every rendered frame under an empty root, as playback does", () => {
    document.body.innerHTML =
      `<div data-composition-id="main" data-root="true" data-duration="2">` +
      `<div class="clip" data-composition-id="scene" data-start="0" data-duration="2">` +
      `<div id="card"></div></div></div>`;
    const card = document.getElementById("card")!;
    const scene = cardScene(card);
    window.__timelines = {
      main: standIn(gsap.timeline({ paused: true })),
      scene: standIn(scene),
    };
    initSandboxRuntimeModular();
    const played = { x: 0, opacity: 0 };
    const playedScene = cardScene(played);
    for (let frame = 0; frame <= 30; frame++) {
      playedScene.totalTime(frame / 30);
      window.__player?.renderSeek(frame / 30, { suppressEvents: true });
      expect(card.style.opacity, `frame ${frame}`).toBe(String(played.opacity));
    }
  });
});