Skip to content

Write HTML. Render video. Built for agents.

15.8 KB
Raw Blame
// @vitest-environment happy-dom
import { gsap } from "gsap";
import { parseGsapScriptAcorn } from "@hyperframes/parsers/gsap-parser-acorn";
import {
  replaceTweenWithKeyframesInScript,
  syncPositionHoldsBeforeKeyframes,
  updateKeyframeInScript,
} from "@hyperframes/parsers/gsap-writer-acorn";
import { afterEach, expect, it, vi } from "vitest";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { usePlayerStore } from "../player/store/playerStore";
import { findParsedTween, parsedImplicitEndValue, parsedTweenEase } from "./gsapParsedTween";
import { readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
import { GsapEditBlockedError } from "./gsapEditOutcome";
import { toClipKeyframes } from "./gsapShared";
import { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
import { applyKeyframeAtPlayhead, type EnableKeyframesSession } from "./useEnableKeyframes";

/** Runs a composition script as the preview does: a paused timeline, bound, then seeked to `at`. */
function play(script: string, at: number) {
  const win = { __timelines: {} as Record<string, gsap.core.Timeline> };
  new Function("gsap", "window", script)(gsap, win);
  const timeline = win.__timelines.t!;
  timeline.progress(0.0001, true).seek(at);
  return { timeline, iframe: { contentWindow: { ...win, gsap } } as unknown as HTMLIFrameElement };
}

/** Drags `#x` to `x` at `at`, writes the plan into the script, and replays the written file there. */
function dragAndReplay(
  script: string,
  x: number,
  at: number,
  selectedPct: number | null = null,
  { y, backfill }: { y?: number; backfill?: Record<string, number> } = {},
) {
  const box = document.body.appendChild(document.createElement("div"));
  box.id = "x";
  const { timeline, iframe } = play(script, at);
  usePlayerStore.setState({ currentTime: at, activeKeyframePct: selectedPct });
  const anim = parseGsapScriptAcorn(script).animations[0]!;
  const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;
  const plan = planValueEdit(selection, anim, { x, ...(y != null && { y }) }, iframe, { backfill });
  timeline.kill();
  if (!plan.ok) return { plan };
  const written = replaceTweenWithKeyframesInScript(script, anim.id, plan.mutation)!;
  const replay = play(written, at);
  const shown = gsap.getProperty(box, "x");
  replay.timeline.kill();
  return { plan, written, shown };
}

const script = (vars: string) =>
  `var tl = gsap.timeline({ paused: true });\ntl.to("#x", { ${vars} }, 0);\nwindow.__timelines["t"] = tl;`;

afterEach(() => {
  document.body.replaceChildren();
  usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null });
});

it("edits a delayed tween with no authored ease, landing the value at the playhead", () => {
  const { plan, shown } = dragAndReplay(script("duration: 1, delay: 0.5, x: 100"), 200, 2);
  expect(plan.ok).toBe(true);
  expect(shown).toBe(200);
});

it("writes a delayed linear tween so GSAP shows the new value at the playhead, not later", () => {
  const { shown } = dragAndReplay(script("duration: 1, delay: 0.5, x: 100, ease: 'none'"), 200, 2);
  expect(shown).toBe(200);
});

it("reads plain array nodes where the lane puts them, though GSAP fills in step durations", () => {
  const source = script("keyframes: [{ x: 60 }, { x: 120 }, { x: 180 }], duration: 3");
  document.body.appendChild(document.createElement("div")).id = "x";
  const { timeline, iframe } = play(source, 0);
  const frame = { ...iframe, contentDocument: document } as HTMLIFrameElement;
  const read = readRuntimeKeyframes(frame, "#x");
  timeline.kill();
  const parsed = parseGsapScriptAcorn(source).animations[0]!.keyframes!.keyframes;
  expect(read?.keyframes.map((kf) => kf.percentage)).toEqual(parsed.map((kf) => kf.percentage));
});

// Three default 0.5 s steps stretched over 3 s: GSAP reaches the middle one at 2 s, where the parse
// places it at 66.7%.
it.each([
  ["at the playhead, timing array steps on their own timeline", undefined],
  ["selected in the lane, in place", 66.7],
])("changes the middle array keyframe %s", (_, selectedPct) => {
  const { plan, shown } = dragAndReplay(
    script("keyframes: [{ x: 60 }, { x: 120 }, { x: 180 }], duration: 3"),
    130,
    2,
    selectedPct,
  );
  expect(plan.ok && plan.mutation.keyframes.map((kf) => kf.properties.x)).toEqual([60, 130, 180]);
  expect(shown).toBeCloseTo(130, 2);
});

it("keeps an array step that leaves a channel out holding it, as GSAP played it", () => {
  const hold = "keyframes: [{ x: 60, duration: 1 }, { duration: 1 }, { x: 180, duration: 1 }]";
  const { written } = dragAndReplay(script(hold), 97, 1);
  const replay = play(written!, 2);
  expect(gsap.getProperty("#x", "x")).toBe(97);
  replay.timeline.kill();
});

it("holds a newly animated channel at rest through a step list's opening pause", () => {
  const pauseFirst =
    "keyframes: [{ duration: 1 }, { x: 60, duration: 1 }, { x: 180, duration: 1 }]";
  const { written } = dragAndReplay(script(pauseFirst), 37, 2, null, { y: 11, backfill: { y: 0 } });
  for (const [t, y] of [
    [0.5, 0],
    [2, 11],
  ]) {
    gsap.set("#x", { clearProps: "all" }); // a reloaded preview starts the tween from rest
    const replay = play(written!, t!);
    expect(gsap.getProperty("#x", "y")).toBeCloseTo(y!, 2);
    replay.timeline.kill();
  }
});

it("holds a channel at its start until the array step that first animates it", () => {
  const late = "keyframes: [{ x: 60 }, { x: 120, y: 50 }], duration: 2";
  const { written } = dragAndReplay(script(late), 200, 2);
  const replay = play(written!, 1);
  expect(gsap.getProperty("#x", "y")).toBe(0);
  replay.timeline.kill();
});

it("keeps GSAP's default ease, by name, for a tween that authors none", () => {
  const { plan } = dragAndReplay(script("duration: 1, x: 100"), 60, 0.5);
  expect(plan.ok && plan.mutation.easeEach).toBe("power1.out");
});

it("reads a tween the playhead has not reached without redrawing a sibling's live value", () => {
  const [x, y] = ["x", "y"].map((id) =>
    Object.assign(document.body.appendChild(document.createElement("div")), { id }),
  );
  const src = `var tl = gsap.timeline({ paused: true });
tl.to("#y", { x: 100, duration: 1, ease: "none" }, 0);
tl.to("#x", { x: 300, duration: 1 }, 2);
window.__timelines["t"] = tl;`;
  const { timeline, iframe } = play(src, 0.5);
  gsap.set(y!, { x: 77 });

  const tween = findParsedTween(iframe, x!, parseGsapScriptAcorn(src).animations[1]!);

  expect(parsedImplicitEndValue(tween)("x", "start")).toBe(0);
  expect(gsap.getProperty(y!, "x")).toBe(77);
  expect(timeline.time()).toBe(0.5);
  timeline.kill();
});

it("keeps a sibling's live attribute while reading an unplayed tween beside the runtime's filler", () => {
  const [x, y] = ["x", "y"].map((id) =>
    Object.assign(document.body.appendChild(document.createElement("div")), { id }),
  );
  y!.setAttribute("data-value", "0");
  const src = `var tl = gsap.timeline({ paused: true });
tl.to({}, { duration: 4, data: "hf-runtime-filler" }, 0);
tl.to("#y", { attr: { "data-value": 100 }, duration: 1, ease: "none" }, 0);
tl.to("#x", { x: 300, duration: 1 }, 2);
window.__timelines["t"] = tl;`;
  const { timeline, iframe } = play(src, 0.5);
  y!.setAttribute("data-value", "77");

  const tween = findParsedTween(iframe, x!, parseGsapScriptAcorn(src).animations.at(-1)!);

  expect(parsedImplicitEndValue(tween)("x", "start")).toBe(0);
  expect(y!.getAttribute("data-value")).toBe("77");
  timeline.kill();
});

it("reads a later tween's start from the earlier tween on the same layer, as playback does", () => {
  const x = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
  const src = `var tl = gsap.timeline({ paused: true });
tl.to("#x", { x: 50, duration: 4, ease: "none" }, 0);
tl.to("#x", { x: 100, duration: 1, ease: "none", overwrite: "auto" }, 2);
window.__timelines["t"] = tl;`;
  const { timeline, iframe } = play(src, 0.5);

  const tween = findParsedTween(iframe, x, parseGsapScriptAcorn(src).animations[1]!);

  expect(parsedImplicitEndValue(tween)("x", "start")).toBe(25);
  timeline.seek(2.5);
  expect(gsap.getProperty(x, "x")).toBe(62.5);
  timeline.kill();
});

it("saves a dragged keyframe tween with its authored start, not the drag's live value", () => {
  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
  const src = script(
    "keyframes: { '0%': { opacity: 0 }, '100%': { opacity: 1, x: 300 } }, duration: 1, ease: 'none'",
  ).replace("}, 0);", "}, 2);");
  const { timeline, iframe } = play(src, 0.5);
  usePlayerStore.setState({ currentTime: 0.5, activeKeyframePct: null });
  gsap.set(box, { x: 77 });
  const anim = parseGsapScriptAcorn(src).animations[0]!;
  const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;

  const plan = planValueEdit(selection, anim, { x: 77 }, iframe);
  timeline.kill();

  expect(plan.ok).toBe(true);
  if (!plan.ok) return;
  const written = replaceTweenWithKeyframesInScript(src, anim.id, plan.mutation)!;
  const at = (time: number) => {
    const replay = play(written, time);
    const x = gsap.getProperty(box, "x");
    replay.timeline.kill();
    return x;
  };
  expect(at(0.5)).toBe(77);
  expect(at(2)).toBe(0);
  expect(at(3)).toBe(300);
});

it("keeps a layer's other transform values while reading an unplayed tween", () => {
  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
  const src = script(
    "keyframes: { '0%': { opacity: 0 }, '100%': { opacity: 1, x: 300 } }, duration: 1",
  ).replace("}, 0);", "}, 2);");
  const { timeline, iframe } = play(src, 0.5);
  gsap.set(box, {
    x: 77,
    skewX: 23,
    rotationX: 19,
    xPercent: 12,
    transformOrigin: "20px 30px 40px",
  });

  const tween = findParsedTween(iframe, box, parseGsapScriptAcorn(src).animations[0]!);
  timeline.kill();

  expect(parsedImplicitEndValue(tween)("x", "start")).toBe(0);
  const values = ["x", "skewX", "rotationX", "xPercent", "transformOrigin"];
  expect(values.map((p) => gsap.getProperty(box, p))).toEqual([77, 23, 19, 12, "20px 30px 40px"]);
});

it("names only an ease GSAP built in, and refuses a custom function rather than guess", () => {
  const custom = { vars: { ease: (p: number) => p * p } };
  const iframe = { contentWindow: { gsap } } as unknown as HTMLIFrameElement;
  expect(parsedTweenEase(iframe, { vars: { ease: gsap.parseEase("expo.in") } })).toBe("expo.in");
  expect(parsedTweenEase(iframe, custom)).toBeNull();
});

it("writes an edit into a looping tween and keeps its repeat and yoyo, as main did", () => {
  const vars = "duration: 2, x: 100, ease: 'none', repeat: 1, yoyo: true";
  const { plan, written } = dragAndReplay(script(vars), 40, 1);
  expect(plan.ok).toBe(true);
  expect(written).toMatch(/repeat: 1[\s\S]*yoyo: true/);
});

it("keeps a delayed step list where GSAP plays it, before and after a keyframe edit", () => {
  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
  const stepList = `var tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: [{ x: 60 }, { x: 120 }], ease: "none" }, 1);\nwindow.__timelines["t"] = tl;`;
  const id = parseGsapScriptAcorn(stepList).animations[0]!.id;
  const edited = syncPositionHoldsBeforeKeyframes(
    updateKeyframeInScript(stepList, id, 100, { x: 130 }),
  );
  const xAt = (file: string, at: number) => {
    const { timeline } = play(file, at);
    const x = gsap.getProperty(box, "x");
    timeline.kill();
    gsap.set(box, { clearProps: "all" });
    return x;
  };
  for (const file of [stepList, edited]) {
    expect([xAt(file, 0.5), xAt(file, 1.25)]).toEqual([0, 30]);
    const tween = parseGsapScriptAcorn(file).animations.find((a) => a.keyframes)!;
    for (const { percentage, properties } of tween.keyframes!.keyframes) {
      expect(xAt(file, 1 + percentage / 100)).toBeCloseTo(Number(properties.x), 3);
    }
  }
});

it.each([
  [
    "an outer power2.in",
    `keyframes: { "0%": { x: 0 }, "50%": { x: 60 }, "100%": { x: 120 } }, duration: 1, ease: "power2.in"`,
  ],
  ["no duration", `keyframes: [{ x: 60 }, { x: 120 }], ease: "none"`],
])("draws each diamond of a keyframed tween with %s where GSAP shows its value", (_, vars) => {
  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
  const file = `var tl = gsap.timeline({ paused: true });\ntl.to("#x", { ${vars} }, 1);\nwindow.__timelines["t"] = tl;`;
  const tween = parseGsapScriptAcornAnimation(file);
  for (const row of toClipKeyframes(tween.keyframes!.keyframes, tween, 0, 4)) {
    const { timeline } = play(file, (row.percentage / 100) * 4);
    expect(gsap.getProperty(box, "x")).toBeCloseTo(Number(row.properties.x), 1);
    timeline.kill();
    gsap.set(box, { clearProps: "all" });
  }
});

function parseGsapScriptAcornAnimation(file: string) {
  return parseGsapScriptAcorn(file).animations.find((a) => a.keyframes)!;
}

it("keeps a step list's steps where GSAP plays them when an outer duration stretches it", () => {
  const { plan, written } = dragAndReplay(
    script(`keyframes: [{ x: 100 }, { x: 200 }], duration: 2, ease: "none"`),
    70,
    0.5,
  );
  expect(plan.ok).toBe(true);
  const box = document.getElementById("x")!;
  const xAt = (at: number) => {
    const { timeline } = play(written!, at);
    const x = gsap.getProperty(box, "x");
    timeline.kill();
    return x;
  };
  expect([xAt(0.5), xAt(1), xAt(2)]).toEqual([70, 100, 200]);
});

it("adds a keyframe where GSAP plays a tween whose duration is an expression, and never rewrites the expression", async () => {
  const src = `var dur = () => 2;\nvar tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: { "0%": { x: 0 }, "100%": { x: 300 } }, duration: dur() }, 1);\nwindow.__timelines["t"] = tl;`;
  const box = document.body.appendChild(document.createElement("div"));
  box.id = "x";
  const { timeline, iframe } = play(src, 2);
  const anim = parseGsapScriptAcorn(src).animations[0]!;
  const writes: Array<[string, unknown]> = [];
  const session = {
    commitMutation: async (mutation: unknown) => void writes.push(["replace", mutation]),
    handleGsapRemoveKeyframe: () => void writes.push(["remove", null]),
    handleGsapAddKeyframeBatch: async (_id: string, pct: number) => void writes.push(["add", pct]),
  } as unknown as EnableKeyframesSession;
  const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;

  await applyKeyframeAtPlayhead(session, selection, anim, 2, iframe);
  await applyKeyframeAtPlayhead(session, selection, anim, 3.5, iframe);
  timeline.kill();

  expect(anim.durationUnresolved).toBe(true);
  expect(writes).toEqual([["add", 50]]);
});

it("leaves a step list with a runBackwards step to the runtime: a rewrite would play it differently", async () => {
  const flagged = script(
    "keyframes: [{ x: 60, duration: 1, runBackwards: true }, { x: 180, duration: 1 }], ease: 'none'",
  );
  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
  const xAt = (src: string, t: number) => {
    gsap.set(box, { clearProps: "all" });
    const replay = play(src, t);
    const x = gsap.getProperty(box, "x");
    replay.timeline.kill();
    return x;
  };
  // The flag plays the first step from 60 back to the start, so a list without it is another animation.
  expect(xAt(flagged, 0.25)).not.toBe(xAt(flagged.replace(", runBackwards: true", ""), 0.25));
  const { timeline, iframe } = play(flagged, 1.5);
  usePlayerStore.setState({ currentTime: 1.5, activeKeyframePct: null });
  const anim = parseGsapScriptAcorn(flagged).animations[0]!;
  const commitMutation = vi.fn(async () => {});
  const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;

  const edit = commitValueAtPlayhead(
    selection,
    anim,
    { x: 90 },
    iframe,
    { commitMutation },
    {
      label: "Move",
    },
  );

  await expect(edit).rejects.toBeInstanceOf(GsapEditBlockedError);
  timeline.kill();
  expect(commitMutation).not.toHaveBeenCalled();
});