Skip to content

Write HTML. Render video. Built for agents.

perf(studio): move the live tweens in place after a timeline drop (#5042)

Miguel Ángel8661e8c96565
diff --git a/packages/core/src/runtime/init.compositionLength.test.ts b/packages/core/src/runtime/init.compositionLength.test.ts
index a74b8922b5..88bf690b6f 100644
--- a/packages/core/src/runtime/init.compositionLength.test.ts
+++ b/packages/core/src/runtime/init.compositionLength.test.ts
@@ -1,5 +1,7 @@
+import gsap from "gsap";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { initSandboxRuntimeModular } from "./init";
+import { RUNTIME_FILLER } from "./protocol";
import type { RuntimeTimelineLike } from "./types";
import {
createMockTimeline,
@@ -47,6 +49,28 @@ describe("runtime composition length and size", () => {
expect(lengthOf(html, { main: createMockTimeline(10) })).toBe(4);
});
+ it("re-pads a timeline that survives a rebind to the root's new length, as a fresh load does", () => {
+ // GSAP's ticker re-enters an animation frame that runs at once.
+ window.requestAnimationFrame = originalRequestAnimationFrame;
+ document.body.innerHTML = `<div data-composition-id="main" data-root="true" data-duration="6"><div id="a"></div></div>`;
+ const timeline = gsap.timeline({ paused: true });
+ timeline.to("#a", { x: 1, duration: 1 }, 0);
+ window.__timelines = { main: timeline as unknown as RuntimeTimelineLike };
+ initSandboxRuntimeModular();
+ const fillers = () =>
+ timeline
+ .getChildren(false, true, false)
+ .filter((child) => child.data === RUNTIME_FILLER)
+ .map((child) => child.startTime());
+ expect(fillers()).toEqual([6]);
+
+ document.getElementById("a")!.parentElement!.setAttribute("data-duration", "9");
+ window.__hfForceTimelineRebind?.();
+
+ expect(fillers()).toEqual([9]);
+ expect(window.__player?.getDuration()).toBe(9);
+ });
+
it("takes the timeline's length when the root declares none", () => {
const html = `<div data-composition-id="main" data-root="true"></div>`;
expect(lengthOf(html, { main: createMockTimeline(6) })).toBe(6);
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 88e8760fc3..46158b4eae 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -1,4 +1,5 @@
// fallow-ignore-file code-duplication complexity
+import { RUNTIME_FILLER } from "./protocol";
import { preloadMedia, releaseMedia, lengthIsAuthored, stopMediaDownload } from "./preloadMedia";
import { installRuntimeControlBridge, postRuntimeMessage, setRuntimeProtocolFps } from "./bridge";
import { instantTolerance } from "../clipFacts";
@@ -169,6 +170,15 @@ function pauseTimelineIfPossible(tl: RuntimeTimelineLike | null | undefined): vo
}
}
+/** A timeline the runtime already padded is padded again from scratch, as a fresh load pads it. */
+function dropRuntimeFillers(timeline: RuntimeTimelineLike): void {
+ const removable = timeline as RuntimeTimelineLike & { remove?: (child: unknown) => unknown };
+ if (typeof removable.remove !== "function") return;
+ for (const child of timeline.getChildren?.(false, true, false) ?? []) {
+ if (child.data === RUNTIME_FILLER) removable.remove(child);
+ }
+}
+
type ExportRenderFpsResolution = {
fps: number | null;
source: "render-options" | "default" | "unknown";
@@ -351,8 +361,6 @@ const MEDIA_URL_ATTRS = new Map([
]);
const SLOW_IDLE_HEARTBEAT_MS = 1000;
-// GSAP `data` on the tweens the runtime adds to stretch a timeline; never animation.
-const RUNTIME_FILLER = "hf-runtime-filler";
// One document.getAnimations() per seek and the pause after it, read on first use, shared by all adapters.
function pageAnimationsForOnePass(): () => Animation[] {
@@ -1600,6 +1608,7 @@ export function initSandboxRuntimeModular(): void {
/* ignore */
}
}
+ dropRuntimeFillers(rootTimeline);
const rootDurationSeconds = getTimelineDurationSeconds(rootTimeline);
if (!isUsableTimelineDuration(rootDurationSeconds) && rootChildCandidates.length > 0) {
const selectedTimelineIds = rootChildCandidates.map((candidate) => candidate.compositionId);
@@ -2035,6 +2044,12 @@ export function initSandboxRuntimeModular(): void {
if (state.capturedTimeline !== resolution.timeline) {
childrenBound = false;
bindRootTimelineIfAvailable();
+ } else {
+ const length = getSafeTimelineDurationSeconds(state.capturedTimeline, 0);
+ if (length > 0 && length !== clock.getDuration()) {
+ clock.setDuration(length);
+ postTimeline();
+ }
}
syncTimedElementVisibility(state.currentTime);
};
diff --git a/packages/core/src/runtime/protocol.ts b/packages/core/src/runtime/protocol.ts
index f6a4eccbc2..894f9590bb 100644
--- a/packages/core/src/runtime/protocol.ts
+++ b/packages/core/src/runtime/protocol.ts
@@ -1,5 +1,7 @@
export const RUNTIME_PROTOCOL_VERSION = 1 as const;
+export const RUNTIME_FILLER = "hf-runtime-filler";
+
export const RUNTIME_PROTOCOL_CAPABILITIES = [
"seconds-time",
"rational-fps",
diff --git a/packages/studio/src/hooks/timelineTimingSync.ts b/packages/studio/src/hooks/timelineTimingSync.ts
index 05419d7c31..2a32f4714d 100644
--- a/packages/studio/src/hooks/timelineTimingSync.ts
+++ b/packages/studio/src/hooks/timelineTimingSync.ts
@@ -30,6 +30,7 @@ import {
type StudioProjectFileWriter,
} from "../utils/studioFileMutationCoordinator";
import { studioApiFetch } from "../utils/studioApiFetch";
+import { moveLiveTweens } from "../utils/gsapLiveRetime";
export async function readFileContent(projectId: string, targetPath: string): Promise<string> {
if (targetPath.includes("\0") || targetPath.includes("..")) {
@@ -83,8 +84,8 @@ function rebindPreviewTiming(iframe: HTMLIFrameElement | null, currentTime: numb
}
/**
- * Sync the live preview after a TIMING-ONLY edit (move / resize), preferring a
- * soft reload over the full iframe reload that flashes every clip.
+ * Sync the live preview after a timing-only edit (move / resize): move the live tweens when only
+ * their timing changed, else a soft reload rather than the full reload that flashes every clip.
*
* Why this is safe WITHOUT re-deriving timeline elements: a move/resize commit has
* already (a) patched the live DOM timing attributes, (b) updated the store's
@@ -116,25 +117,32 @@ function rebindPreviewTiming(iframe: HTMLIFrameElement | null, currentTime: numb
* script is now stale, so a rebind against it would show wrong positions →
* full-reload.
*/
-function syncTimingEditPreview(
+async function syncTimingEditPreview(
iframe: HTMLIFrameElement | null,
outcome: GsapMutationStatus,
- currentTime: number,
+ projectId: string | null,
reloadPreview: () => void,
rebindWhenUnmutated: boolean,
- nestedFiles: Map<string, string> | null | undefined,
-): void {
+): Promise<void> {
+ const currentTime = () => usePlayerStore.getState().currentTime;
if (!outcome.mutated && rebindWhenUnmutated) {
- if (!rebindPreviewTiming(iframe, currentTime)) reloadPreview();
+ if (!rebindPreviewTiming(iframe, currentTime())) reloadPreview();
return;
}
- if (!iframe || !outcome.scriptText) {
+ const { scriptText } = outcome;
+ if (!iframe || !scriptText) {
reloadPreview();
return;
}
- const result = applySoftReload(iframe, outcome.scriptText, {
+ if (moveLiveTweens(iframe, scriptText, currentTime(), reloadPreview)) return;
+ const nestedFiles = await settleNestedReads(
+ projectId
+ ? readNestedFiles(iframe, scriptText, (path) => readFileContent(projectId, path))
+ : null,
+ );
+ const result = applySoftReload(iframe, scriptText, {
onAsyncFailure: reloadPreview,
- currentTimeOverride: currentTime,
+ currentTimeOverride: currentTime(),
authoredHtml: outcome.after,
nestedFiles,
});
@@ -170,21 +178,12 @@ export async function finishTimelineTimingFallback(input: {
return;
}
}
- const { projectId } = input;
- const nestedFiles = await settleNestedReads(
- projectId && outcome.scriptText
- ? readNestedFiles(input.iframe, outcome.scriptText, (path) =>
- readFileContent(projectId, path),
- )
- : null,
- );
- syncTimingEditPreview(
+ await syncTimingEditPreview(
input.iframe,
outcome,
- usePlayerStore.getState().currentTime,
+ input.projectId,
input.reloadPreview,
input.rebindWhenUnmutated,
- nestedFiles,
);
}
diff --git a/packages/studio/src/utils/gsapLiveRetime.realGsap.test.ts b/packages/studio/src/utils/gsapLiveRetime.realGsap.test.ts
new file mode 100644
index 0000000000..06001a3921
--- /dev/null
+++ b/packages/studio/src/utils/gsapLiveRetime.realGsap.test.ts
@@ -0,0 +1,544 @@
+// @vitest-environment happy-dom
+import { gsap } from "gsap";
+import { retimeClipTweensInScript } from "@hyperframes/parsers/gsap-writer-acorn";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { finishTimelineTimingFallback } from "../hooks/timelineTimingSync";
+import { applyLiveRetime, planLiveRetime, planLiveRetimeFromPreview } from "./gsapLiveRetime";
+
+const BEFORE = [
+ "var tl = gsap.timeline({ paused: true });",
+ 'tl.set("#b", { y: 3 }, 0.2);',
+ 'tl.to("#a", { x: 100, duration: 1 }, 0.5);',
+ 'tl.from("#b", { opacity: 0, duration: 2 }, 1);',
+ 'tl.to("#c", { keyframes: { "0%": { x: 0 }, "50%": { x: 80 }, "100%": { x: 50 } }, duration: 1.5 }, 2);',
+ 'window.__timelines["t"] = tl;',
+].join("\n");
+
+const SAMPLES = Array.from({ length: 25 }, (_, i) => i * 0.25);
+
+/** Runs a composition script and binds its timeline at `at`, as the preview's runtime does. */
+function play(script: string, at = 0, nested = "") {
+ const win = { __timelines: {} as Record<string, gsap.core.Timeline> };
+ new Function("gsap", "window", script)(gsap, win);
+ const timeline = win.__timelines.t!;
+ // The runtime nests each sub-composition's timeline into its host's; the script does not know them...
+ const sub = gsap.timeline().to({}, { duration: 6.7 });
+ new Function("gsap", "sub", nested)(gsap, sub);
+ timeline.add(sub, 0);
+ // ...and pads the timeline to the composition's length with a filler tween.
+ timeline.to({}, { duration: 0, data: "hf-runtime-filler" }, 8);
+ timeline.progress(0.0001, true).totalTime(at, false);
+ return { win, timeline };
+}
+
+/** Each tween's start and length, and what every element shows across the timeline. */
+function observe(timeline: gsap.core.Timeline) {
+ const tweens = timeline
+ .getChildren(false, true, false)
+ .map((t) => [round(t.startTime()), round(t.duration())]);
+ const shown = SAMPLES.map((at) => {
+ timeline.seek(at);
+ return shownNow();
+ });
+ return { tweens, length: round(timeline.duration()), shown };
+}
+
+const round = (n: number) => Math.round(n * 1000) / 1000;
+
+/** What every element shows now. */
+const shownNow = () =>
+ ["#a", "#b", "#c"].map((id) =>
+ ["x", "y", "opacity"].map((p) => round(Number(gsap.getProperty(id, p)))),
+ );
+
+/** A preview iframe whose live script is `script`, built and bound. */
+function preview(script: string, nested = "") {
+ const tag = document.createElement("script");
+ tag.type = "text/plain"; // the runtime already ran it; happy-dom must not run it again
+ tag.textContent = script;
+ document.body.appendChild(tag);
+ const { win, timeline } = play(script, 0, nested);
+ const rebind = vi.fn();
+ // The runtime hooks a rebind needs; a soft reload would also need `gsap`, which this preview lacks.
+ Object.assign(win, { __hfForceTimelineRebind: rebind, __player: { seek: vi.fn() } });
+ const iframe = { contentWindow: win, contentDocument: document } as unknown as HTMLIFrameElement;
+ return { iframe, timeline, tag, rebind };
+}
+
+beforeEach(() => {
+ for (const id of ["a", "b", "c"]) {
+ const element = document.body.appendChild(document.createElement("div"));
+ element.id = id;
+ element.className = "item";
+ }
+});
+
+afterEach(() => {
+ document.body.replaceChildren();
+ vi.restoreAllMocks();
+});
+
+const moveA = () =>
+ retimeClipTweensInScript(BEFORE, [{ kind: "shift", targetSelector: "#a", delta: 0.75 }], document)
+ .script;
+
+async function dropInto(iframe: HTMLIFrameElement, after: string) {
+ const reloadPreview = vi.fn();
+ await finishTimelineTimingFallback({
+ iframe,
+ projectId: null,
+ reloadPreview,
+ gsapMutation: async () => ({ mutated: true, scriptText: after }),
+ onGsapError: () => {},
+ rebindWhenUnmutated: true,
+ });
+ return reloadPreview;
+}
+
+/** Wraps `element` in a composition host with id `id`, and returns the host. */
+function inComposition(id: string, element: Element) {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-id", id);
+ element.replaceWith(host);
+ host.appendChild(element);
+ return host;
+}
+
+/** `code` as the preview serves it: indented inside the page, with the blank lines around it. */
+const reformatted = (code: string) => `\n${code.replace(/^/gm, " ")}\n`;
+
+const script = (...lines: string[]) =>
+ ["var tl = gsap.timeline({ paused: true });", ...lines, 'window.__timelines["t"] = tl;'].join(
+ "\n",
+ );
+
+it.each([
+ {
+ name: "a tween with no written length",
+ path: "rerun",
+ before: script('tl.to("#a", { x: 100 }, 0);', 'tl.to("#b", { x: 50, duration: 1 }, 1);'),
+ after: script('tl.to("#a", { x: 100 }, 0);', 'tl.to("#b", { x: 50, duration: 1 }, 2);'),
+ },
+ {
+ name: "a step list with no lengths",
+ path: "retime",
+ before: script(
+ 'tl.to("#a", { keyframes: [{ x: 10 }, { x: 20 }] }, 0);',
+ 'tl.to("#b", { x: 5, duration: 1 }, 1);',
+ ),
+ after: script(
+ 'tl.to("#a", { keyframes: [{ x: 10 }, { x: 20 }] }, 0);',
+ 'tl.to("#b", { x: 5, duration: 1 }, 2);',
+ ),
+ },
+ {
+ name: "a stagger beside the moved tween",
+ path: "rerun",
+ before: script(
+ 'tl.to(".item", { x: 100, duration: 1, stagger: 0.2 }, 0);',
+ 'tl.to("#a", { y: 5, duration: 1 }, 2);',
+ ),
+ after: script(
+ 'tl.to(".item", { x: 100, duration: 1, stagger: 0.2 }, 0);',
+ 'tl.to("#a", { y: 5, duration: 1 }, 3);',
+ ),
+ },
+ {
+ name: "a repeat before an implicit position",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 1, duration: 1, repeat: 1 }, 0);',
+ 'tl.to("#b", { x: 1, duration: 1 });',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 1, duration: 1, repeat: 1 }, 0.5);',
+ 'tl.to("#b", { x: 1, duration: 1 });',
+ ),
+ },
+ {
+ name: "a delay before a '<' position",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 1, duration: 1, delay: 0.5 }, 0);',
+ 'tl.to("#b", { x: 1, duration: 1 }, "<");',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 1, duration: 1, delay: 0.5 }, 1);',
+ 'tl.to("#b", { x: 1, duration: 1 }, "<");',
+ ),
+ },
+ {
+ name: "two tweens on one element whose live order differs from the script's",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 100, duration: 1, delay: 1 }, 0);',
+ 'tl.to("#a", { y: 50, duration: 1 }, 0.5);',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 100, duration: 1, delay: 1 }, 0);',
+ 'tl.to("#a", { y: 50, duration: 1 }, 1.5);',
+ ),
+ },
+ {
+ name: "two tweens on one element that swap order",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 100, duration: 1 }, 0);',
+ 'tl.to("#a", { x: 200, duration: 1 }, 2);',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 100, duration: 1 }, 3);',
+ 'tl.to("#a", { x: 200, duration: 1 }, 2);',
+ ),
+ },
+ {
+ name: "a call in the timeline",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 1, duration: 1 }, 0);',
+ "tl.call(() => {}, [], 1);",
+ 'tl.to("#b", { x: 1, duration: 1 }, 2);',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 1, duration: 1 }, 0);',
+ "tl.call(() => {}, [], 1);",
+ 'tl.to("#b", { x: 1, duration: 1 }, 3);',
+ ),
+ },
+ {
+ name: "a counter tween on a plain object",
+ path: "rerun",
+ before: script(
+ "var counter = { n: 0 };",
+ "tl.to(counter, { n: 10, duration: 1 }, 0);",
+ 'tl.to("#b", { x: 1, duration: 1 }, 1);',
+ ),
+ after: script(
+ "var counter = { n: 0 };",
+ "tl.to(counter, { n: 10, duration: 1 }, 0);",
+ 'tl.to("#b", { x: 1, duration: 1 }, 2);',
+ ),
+ },
+ {
+ name: "a paused playhead past the moved tween",
+ path: "retime",
+ before: script('tl.to("#a", { x: 100, duration: 1 }, 0.5);'),
+ after: script('tl.to("#a", { x: 100, duration: 1 }, 1.5);'),
+ at: 2,
+ },
+ {
+ name: "an unmoved tween on the same element that overlaps the moved one",
+ path: "rerun",
+ before: script(
+ 'tl.to(".item", { x: 100, duration: 2 }, 0);',
+ 'tl.to("#a", { x: 0, duration: 1 }, 4);',
+ ),
+ after: script(
+ 'tl.to(".item", { x: 100, duration: 2 }, 0);',
+ 'tl.to("#a", { x: 0, duration: 1 }, 1);',
+ ),
+ },
+ {
+ name: "a sub-composition tween on the moved tween's element",
+ path: "rerun",
+ before: script('tl.to("#a", { x: 100, duration: 1 }, 0);'),
+ after: script('tl.to("#a", { x: 100, duration: 1 }, 3);'),
+ nested: 'sub.to("#a", { x: 50, duration: 1 }, 2);',
+ },
+ {
+ name: "a delayed tween that GSAP orders after the moved one",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { opacity: 0.5, duration: 1, delay: 2 }, 0);',
+ 'tl.to("#a", { x: 100, duration: 1 }, 0);',
+ ),
+ after: script(
+ 'tl.to("#a", { opacity: 0.5, duration: 1, delay: 2 }, 0);',
+ 'tl.to("#a", { x: 100, duration: 1 }, 3);',
+ ),
+ },
+ {
+ name: "a set moved onto a playhead at 0",
+ path: "retime",
+ before: script('tl.set("#a", { x: 30 }, 2);', 'tl.to("#b", { x: 1, duration: 1 }, 3);'),
+ after: script('tl.set("#a", { x: 30 }, 0);', 'tl.to("#b", { x: 1, duration: 1 }, 3);'),
+ },
+ {
+ name: "a tween whose callback draws another element",
+ path: "retime",
+ before: script(
+ 'tl.to("#a", { x: 100, duration: 2, onUpdate: function () { gsap.set("#c", { y: Math.round(this.progress() * 100) }); } }, 1);',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 100, duration: 2, onUpdate: function () { gsap.set("#c", { y: Math.round(this.progress() * 100) }); } }, 1.5);',
+ ),
+ at: 2,
+ },
+ {
+ name: "a trim of an element with an entrance and an exit, rounded as the writer writes it",
+ path: "retime",
+ before: script(
+ 'tl.to("#a", { y: 40, duration: 1 }, 0);',
+ 'tl.to("#a", { x: 50, duration: 1 }, 2);',
+ ),
+ after: script(
+ 'tl.to("#a", { y: 40, duration: 0.833 }, 0);',
+ 'tl.to("#a", { x: 50, duration: 0.833 }, 1.667);',
+ ),
+ },
+ {
+ name: "a trim of an element whose tween has a delay",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 100, duration: 1, delay: 1 }, 0);',
+ 'tl.to("#a", { x: 200, duration: 1 }, 2);',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 100, duration: 0.5, delay: 1 }, 0);',
+ 'tl.to("#a", { x: 200, duration: 0.5 }, 1);',
+ ),
+ },
+ {
+ name: "a move of a sub-composition's host",
+ path: "rerun",
+ before: script('tl.to("#a", { y: 40, duration: 1 }, 0);'),
+ after: script('tl.to("#a", { y: 40, duration: 1 }, 2);'),
+ setup: () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-id", "scene");
+ document.getElementById("a")!.appendChild(host);
+ },
+ },
+ {
+ name: "a tween on an element inside a sub-composition's host",
+ path: "rerun",
+ before: script('tl.to("#a", { y: 40, duration: 1 }, 0);'),
+ after: script('tl.to("#a", { y: 40, duration: 1 }, 2);'),
+ setup: () => inComposition("t", inComposition("scene", document.getElementById("a")!)),
+ },
+ {
+ name: "a tween on an element of the timeline's own composition",
+ path: "retime",
+ before: script('tl.to("#a", { y: 40, duration: 1 }, 0);'),
+ after: script('tl.to("#a", { y: 40, duration: 1 }, 2);'),
+ setup: () => inComposition("t", document.getElementById("a")!),
+ },
+ {
+ name: "a set and a tween on one element that round to the same start",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 50, duration: 1 }, 0);',
+ 'tl.set("#a", { x: 0 }, 2.0004);',
+ 'tl.to("#a", { x: 100, duration: 1 }, 2);',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 50, duration: 1 }, 1);',
+ 'tl.set("#a", { x: 0 }, 3);',
+ 'tl.to("#a", { x: 100, duration: 1 }, 3);',
+ ),
+ },
+ {
+ name: "a slight trim of an element whose tween has a delay",
+ path: "rerun",
+ before: script(
+ 'tl.to("#a", { x: 100, duration: 1, delay: 1 }, 0);',
+ 'tl.to("#a", { x: 200, duration: 1 }, 2);',
+ ),
+ after: script(
+ 'tl.to("#a", { x: 100, duration: 0.999, delay: 1 }, 0);',
+ 'tl.to("#a", { x: 200, duration: 0.999 }, 1.998);',
+ ),
+ },
+ {
+ name: "a set that never played moved onto a playhead at 0",
+ path: "retime",
+ before: script('tl.set("#a", { x: 30 }, 2);', 'tl.to("#b", { x: 1, duration: 1 }, 3);'),
+ after: script('tl.set("#a", { x: 30 }, 0);', 'tl.to("#b", { x: 1, duration: 1 }, 3);'),
+ unplayed: true,
+ },
+])(
+ "after a drop over $name, the live preview equals a fresh load or the script re-runs",
+ async ({ before, after, nested = "", at = 0, path, setup, unplayed }) => {
+ setup?.();
+ const error = vi.spyOn(console, "error");
+ const live = preview(before, nested);
+ // Played through once, then parked: every tween has recorded its start values.
+ if (!unplayed) live.timeline.totalTime(live.timeline.duration(), false);
+ live.timeline.totalTime(at, false);
+ const reloadPreview = await dropInto(live.iframe, after);
+ expect(error).not.toHaveBeenCalled();
+ if (reloadPreview.mock.calls.length === 0) {
+ const shown = shownNow();
+ const got = observe(live.timeline);
+ live.timeline.revert();
+ const fresh = play(after, at, nested).timeline;
+ expect(shown).toEqual(shownNow());
+ expect(got).toEqual(observe(fresh));
+ }
+ expect(reloadPreview.mock.calls.length > 0 ? "rerun" : "retime").toBe(path);
+ },
+);
+
+it("leaves the live preview equal to a fresh load of the saved script after a move and a resize", () => {
+ const { script: after } = retimeClipTweensInScript(
+ BEFORE,
+ [
+ { kind: "shift", targetSelector: "#a", delta: 0.75 },
+ {
+ kind: "scale",
+ targetSelector: "#c",
+ oldStart: 2,
+ oldDuration: 1.5,
+ newStart: 2.5,
+ newDuration: 3,
+ },
+ ],
+ document,
+ );
+ const fresh = play(after);
+ const want = observe(fresh.timeline);
+ fresh.timeline.revert();
+
+ const live = preview(BEFORE);
+ const plan = planLiveRetimeFromPreview(live.iframe, after);
+ expect(plan.kind).toBe("retime");
+ if (plan.kind !== "retime") return;
+ expect(plan.tweens.filter((t) => t.moved).map((t) => t.selector)).toEqual(["#a", "#c"]);
+ expect(applyLiveRetime(live.iframe, plan)).toBe(true);
+
+ expect(observe(live.timeline)).toEqual(want);
+ expect(live.tag.textContent).toBe(after);
+});
+
+it("re-runs the script for an edit that changes more than timing", () => {
+ const after = BEFORE.replace("x: 100", "x: 140").replace(", 0.5);", ", 0.9);");
+ expect(planLiveRetime(BEFORE, after).kind).toBe("rerun");
+});
+
+it("re-runs the script when the edit also changes code the parser does not read", () => {
+ const before = script('tl.to("#a", { x: 1, duration: 1 }, 0);', 'document.title = "one";');
+ const after = script('tl.to("#a", { x: 1, duration: 1 }, 1);', 'document.title = "two";');
+ expect(planLiveRetime(before, after).kind).toBe("rerun");
+});
+
+it("reloads the preview, and says so, when moving the live tweens throws", async () => {
+ const before = script('tl.to("#a", { x: () => { throw new Error("boom"); }, duration: 1 }, 5);');
+ const live = preview(before);
+ live.timeline.totalTime(3, false);
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+ const reloadPreview = await dropInto(live.iframe, before.replace("}, 5);", "}, 1);"));
+
+ expect(reloadPreview).toHaveBeenCalledTimes(1);
+ expect(error).toHaveBeenCalledTimes(1);
+});
+
+it("re-runs the script when the edit also joins two words of code", () => {
+ const before = script('tl.to("#a", { x: 1, duration: 1 }, 0);', "var b = typeof a;");
+ const after = script('tl.to("#a", { x: 1, duration: 1 }, 1);', "var b = typeofa;");
+ expect(planLiveRetime(before, after).kind).toBe("rerun");
+});
+
+it("moves the live tweens beside a helper-built tween in a reformatted copy of the script", async () => {
+ const lines = [
+ "function pop(sel, at) { tl.to(sel, { x: 5, duration: 1 }, at); }",
+ 'pop("#b", 2);',
+ ];
+ const before = script('tl.to("#a", { x: 1, duration: 1 }, 0);', ...lines);
+ const live = preview(before);
+ live.tag.textContent = reformatted(before);
+
+ const reloadPreview = await dropInto(
+ live.iframe,
+ script('tl.to("#a", { x: 1, duration: 1 }, 0.5);', ...lines),
+ );
+
+ expect(reloadPreview).not.toHaveBeenCalled();
+});
+
+it("moves the live tweens beside a multi-line value in a reformatted copy of the script", async () => {
+ const raw = 'tl.to("#b", { x: [\n 1,\n 2,\n].length, duration: 1 }, 2);';
+ const before = script('tl.to("#a", { y: 1, duration: 1 }, 0);', raw);
+ const live = preview(before);
+ live.tag.textContent = reformatted(before);
+
+ const reloadPreview = await dropInto(
+ live.iframe,
+ script('tl.to("#a", { y: 1, duration: 1 }, 0.5);', raw),
+ );
+
+ expect(reloadPreview).not.toHaveBeenCalled();
+});
+
+it("re-runs the script when the edit adds a tween", () => {
+ const after = BEFORE.replace(
+ "window.__timelines",
+ 'tl.to("#a", { y: 9, duration: 1 }, 4);\nwindow.__timelines',
+ );
+ expect(planLiveRetime(BEFORE, after).kind).toBe("rerun");
+});
+
+it("leaves a live timeline that does not pair with its script untouched", () => {
+ // The preview runs a script with one more tween than the text it claims to be running.
+ const ran = BEFORE.replace(
+ "window.__timelines",
+ 'tl.to("#b", { x: 5, duration: 1 }, 0);\nwindow.__timelines',
+ );
+ const live = preview(ran);
+ live.tag.textContent = BEFORE;
+ const { script: after } = retimeClipTweensInScript(
+ BEFORE,
+ [{ kind: "shift", targetSelector: "#a", delta: 0.75 }],
+ document,
+ );
+ const plan = planLiveRetimeFromPreview(live.iframe, after);
+ expect(plan.kind).toBe("retime");
+ if (plan.kind !== "retime") return;
+ const starts = live.timeline.getChildren(false, true, false).map((t) => t.startTime());
+
+ expect(applyLiveRetime(live.iframe, plan)).toBe(false);
+ expect(live.timeline.getChildren(false, true, false).map((t) => t.startTime())).toEqual(starts);
+ expect(live.tag.textContent).toBe(BEFORE);
+});
+
+it("syncs a timeline move by moving the live tweens and rebinding, without re-running the script", async () => {
+ const live = preview(BEFORE);
+ const after = moveA();
+ const reloadPreview = await dropInto(live.iframe, after);
+
+ expect(reloadPreview).not.toHaveBeenCalled();
+ expect(live.rebind).toHaveBeenCalledTimes(1);
+ const got = observe(live.timeline);
+ live.timeline.revert();
+ expect(got).toEqual(observe(play(after).timeline));
+ expect(document.querySelectorAll("script")).toHaveLength(1);
+});
+
+it("moves the live tweens when the preview runs a reformatted copy of the saved script", async () => {
+ const live = preview(BEFORE);
+ live.tag.textContent = reformatted(BEFORE);
+
+ const reloadPreview = await dropInto(live.iframe, moveA());
+
+ expect(reloadPreview).not.toHaveBeenCalled();
+});
+
+it("pairs by start time, so a second move after a reorder still lands on the right tweens", async () => {
+ const live = preview(BEFORE);
+ const first = moveA(); // #a now starts after #b, so the live children re-sort
+ await dropInto(live.iframe, first);
+ const { script: second } = retimeClipTweensInScript(
+ first,
+ [{ kind: "shift", targetSelector: "#b", delta: 1 }],
+ document,
+ );
+ const error = vi.spyOn(console, "error");
+
+ const reloadPreview = await dropInto(live.iframe, second);
+
+ expect(error).not.toHaveBeenCalled();
+ expect(reloadPreview).not.toHaveBeenCalled();
+ const got = observe(live.timeline);
+ live.timeline.revert();
+ expect(got).toEqual(observe(play(second).timeline));
+});
diff --git a/packages/studio/src/utils/gsapLiveRetime.ts b/packages/studio/src/utils/gsapLiveRetime.ts
new file mode 100644
index 0000000000..0075211edf
--- /dev/null
+++ b/packages/studio/src/utils/gsapLiveRetime.ts
@@ -0,0 +1,286 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { parseGsapScriptAcorn } from "@hyperframes/core/gsap-parser-acorn";
+import { hasExplicitTime } from "@hyperframes/parsers/gsap-writer-acorn";
+import { RUNTIME_FILLER } from "@hyperframes/core/runtime/protocol";
+import {
+ applySoftReloadFinalization,
+ findGsapScriptElements,
+ scriptsRegistering,
+ timelineKeys,
+} from "./gsapSoftReload";
+
+interface TweenTiming {
+ selector: string;
+ start: number;
+ duration: number;
+ wasStart: number;
+ wasDuration: number;
+ moved: boolean;
+ /** Its place in the script, which is the order a fresh run adds it to the timeline. */
+ source: number;
+}
+
+/**
+ * How a saved script differs from the live one: `retime` when only tween starts and lengths moved
+ * (`tweens` in the live timeline's child order), `rerun` for anything only a re-run reproduces.
+ */
+export type LiveRetimePlan =
+ | { kind: "retime"; key: string; after: string; tweens: TweenTiming[] }
+ | { kind: "rerun" };
+
+const RERUN = { kind: "rerun" } as const;
+
+/** The preview runs a reformatted copy of the script: compare code, not its layout. */
+const withoutLayout = (code: string) =>
+ code
+ .replace(/\s+/g, " ")
+ .replace(/ ?([^\w$ ]) ?/g, "$1")
+ .trim();
+
+function untimedShape(animation: GsapAnimation): string {
+ const { id: _id, position: _p, resolvedStart: _s, duration: _d, ...rest } = animation;
+ // An offset into the text, which moves when the preview reformats its copy of the script.
+ const provenance = rest.provenance && { ...rest.provenance, sourceRange: undefined };
+ return JSON.stringify({ ...rest, provenance }, (_key, value) =>
+ typeof value === "string" && value.startsWith("__raw:") ? withoutLayout(value) : value,
+ );
+}
+
+const onTimeline = (animation: GsapAnimation) => !animation.global;
+
+const placedAlone = (animation: GsapAnimation) =>
+ hasExplicitTime(animation) && typeof animation.resolvedStart === "number";
+
+/** Undefined when only GSAP knows it: an unwritten length takes `gsap.defaults`, which a script may change. */
+const lengthOf = (animation: GsapAnimation) =>
+ animation.method === "set" ? 0 : animation.durationUnresolved ? undefined : animation.duration;
+
+/** A timing edit rewrites numbers only; anything else may be code the parser does not read. */
+const withoutNumbers = (script: string) =>
+ withoutLayout(script.replace(/(?<![\w$#.])\d*\.?\d+/g, "0"));
+
+/** Decides, from the two scripts alone, whether a saved edit moved tweens and nothing else. */
+export function planLiveRetime(before: string, after: string): LiveRetimePlan {
+ if (withoutNumbers(before) !== withoutNumbers(after)) return RERUN;
+ const keys = timelineKeys(after);
+ if (keys.length !== 1 || timelineKeys(before).join() !== keys.join()) return RERUN;
+ const was = parseGsapScriptAcorn(before).animations.filter(onTimeline);
+ const now = parseGsapScriptAcorn(after).animations.filter(onTimeline);
+ if (was.length !== now.length) return RERUN;
+ const tweens: TweenTiming[] = [];
+ for (const [index, next] of now.entries()) {
+ const prev = was[index]!;
+ if (untimedShape(prev) !== untimedShape(next)) return RERUN;
+ // A relative position follows the parser's playhead, which is not GSAP's; only numbers place a tween alone.
+ if (!placedAlone(next) || !placedAlone(prev)) return RERUN;
+ const duration = lengthOf(next);
+ const wasDuration = lengthOf(prev);
+ if (duration === undefined || wasDuration === undefined) return RERUN;
+ tweens.push({
+ selector: next.targetSelector,
+ start: next.resolvedStart!,
+ duration,
+ wasStart: prev.resolvedStart!,
+ wasDuration,
+ moved: next.resolvedStart !== prev.resolvedStart || duration !== wasDuration,
+ source: index,
+ });
+ }
+ // A GSAP timeline keeps its children sorted by start, an equal start after the earlier one: pair in that order.
+ tweens.sort((x, y) => x.wasStart - y.wasStart || x.source - y.source);
+ return { kind: "retime", key: keys[0]!, after, tweens };
+}
+
+export type LiveRetime = Extract<LiveRetimePlan, { kind: "retime" }> & {
+ script: HTMLScriptElement;
+};
+
+/** Plans against the script the preview is running now; `rerun` when no single live script owns the timeline. */
+export function planLiveRetimeFromPreview(
+ iframe: HTMLIFrameElement | null,
+ after: string,
+): LiveRetime | typeof RERUN {
+ const doc = iframe?.contentDocument;
+ const [key] = timelineKeys(after);
+ if (!doc || !key) return RERUN;
+ const [script, ...extra] = scriptsRegistering(findGsapScriptElements(doc), [key]);
+ if (!script || extra.length > 0) return RERUN;
+ const plan = planLiveRetime(script.textContent ?? "", after);
+ return plan.kind === "retime" ? { ...plan, script } : RERUN;
+}
+
+interface LiveTween {
+ duration: (value?: number) => number;
+ startTime: () => number;
+ delay: () => number;
+ repeatDelay?: () => number;
+ data?: unknown;
+ targets?: () => unknown[];
+}
+interface LiveTimeline {
+ getChildren(nested: boolean, tweens: true, timelines: false): LiveTween[];
+ getChildren(nested: false, tweens: false, timelines: true): LiveTimeline[];
+ remove: (child: LiveTween) => unknown;
+ add: (child: LiveTween, position: number) => unknown;
+ time: () => number;
+ progress: (value: number, suppressEvents: boolean) => unknown;
+ totalTime: (time: number, suppressEvents: boolean) => unknown;
+}
+
+const same = (a: number, b: number) => Math.abs(a - b) < 1e-6;
+
+const targetsMatch = (tween: LiveTween, selector: string) => {
+ const targets = tween.targets?.() ?? [];
+ try {
+ return targets.length > 0 && targets.every((t) => (t as Element).matches?.(selector) === true);
+ } catch {
+ return false;
+ }
+};
+
+/** The live tweens, one per planned tween, when each sits exactly where the parser says it did. */
+function pairedLiveTweens(timeline: LiveTimeline, plan: LiveRetime): LiveTween[] | null {
+ // The script's tweens only: the runtime also nests sub-composition timelines and adds filler tweens here.
+ const children = timeline
+ .getChildren(false, true, false)
+ .filter((tween) => tween.data !== RUNTIME_FILLER);
+ if (children.length !== plan.tweens.length) return null;
+ const paired = plan.tweens.every((t, i) => {
+ const live = children[i]!;
+ return (
+ targetsMatch(live, t.selector) &&
+ same(live.startTime() - live.delay(), t.wasStart) &&
+ same(live.duration(), t.wasDuration)
+ );
+ });
+ return paired ? children : null;
+}
+
+/** The writer rounds every time it writes to 3 decimals. */
+const near = (a: number, b: number) => Math.abs(a - b) <= 2e-3;
+
+/** One stretch for every tween (start = shift + stretch × old start, length = stretch × old length), in old order. */
+function sharesOneStretch(tweens: TweenTiming[]): boolean {
+ const first = tweens[0]!;
+ const last = tweens.at(-1)!;
+ const longest = tweens.reduce((x, y) => (y.wasDuration > x.wasDuration ? y : x));
+ const spread = last.wasStart - first.wasStart;
+ // Taken over the widest span, so the writer's rounding cannot push it past `near`.
+ const stretch =
+ spread > longest.wasDuration
+ ? (last.start - first.start) / spread
+ : longest.wasDuration > 0
+ ? longest.duration / longest.wasDuration
+ : 1;
+ const fits = tweens.every(
+ (t) =>
+ near(t.start, first.start + stretch * (t.wasStart - first.wasStart)) &&
+ near(t.duration, stretch * t.wasDuration),
+ );
+ return stretch > 0 && fits;
+}
+
+/** The runtime places a sub-composition's timeline at its host's start once; moving the host leaves it there. */
+function inOrHostsSubComposition(target: unknown, ownId: string): boolean {
+ const element = target as Element;
+ const owner = element.closest?.("[data-composition-id]");
+ return (
+ (owner != null && owner.getAttribute("data-composition-id") !== ownId) ||
+ element.querySelector?.("[data-composition-id]") != null
+ );
+}
+
+/** Tweens on one element still start in the order they did, an equal start in script order. */
+const keepsOrder = (tweens: TweenTiming[]) =>
+ tweens.every(
+ (t, k) => k === 0 || (tweens[k - 1]!.start - t.start || tweens[k - 1]!.source - t.source) < 0,
+ );
+
+/**
+ * A tween keeps the start values it recorded when it first played, so every element a move touches
+ * must keep its tweens' spacing, and no timeline the script does not own may animate it.
+ */
+function movesKeepEachElementsHistory(
+ timeline: LiveTimeline,
+ plan: LiveRetime,
+ children: LiveTween[],
+): boolean {
+ const byElement = new Map<unknown, number[]>();
+ children.forEach((child, i) => {
+ for (const target of child.targets?.() ?? []) {
+ const indexes = byElement.get(target);
+ if (indexes) indexes.push(i);
+ else byElement.set(target, [i]);
+ }
+ });
+ const moved = new Set<unknown>();
+ for (const [target, indexes] of byElement) {
+ if (!indexes.some((i) => plan.tweens[i]!.moved)) continue;
+ if (inOrHostsSubComposition(target, plan.key)) return false;
+ const tweens = indexes.map((i) => plan.tweens[i]!);
+ // GSAP adds delays to the schedule unstretched; a shift keeps every length.
+ const shifted = tweens.every((t) => t.duration === t.wasDuration);
+ const undelayed = indexes.every((i) => !children[i]!.delay() && !children[i]!.repeatDelay?.());
+ if (!keepsOrder(tweens) || !sharesOneStretch(tweens) || !(shifted || undelayed)) return false;
+ moved.add(target);
+ }
+ return !timeline
+ .getChildren(false, false, true)
+ .some((sub) =>
+ sub
+ .getChildren(true, true, false)
+ .some((tween) => tween.targets?.().some((t) => moved.has(t))),
+ );
+}
+
+/**
+ * Moves the live tweens a `retime` plan names and records the saved script as the live one.
+ * False, with nothing changed, when the live timeline is not exactly what the parser read.
+ */
+export function applyLiveRetime(iframe: HTMLIFrameElement | null, plan: LiveRetime): boolean {
+ const win = iframe?.contentWindow as { __timelines?: Record<string, unknown> } | null;
+ const timeline = win?.__timelines?.[plan.key] as LiveTimeline | undefined;
+ if (typeof timeline?.getChildren !== "function") return false;
+ // Paired before anything moves: moving a tween re-sorts the timeline's children.
+ const children = pairedLiveTweens(timeline, plan);
+ if (!children) return false;
+ if (plan.tweens.some((t) => t.moved)) {
+ if (!movesKeepEachElementsHistory(timeline, plan, children)) return false;
+ // Re-added in script order: GSAP orders equal starts by when they were added, as a fresh run does.
+ const bySource = plan.tweens
+ .map((t, i) => ({ ...t, tween: children[i]! }))
+ .sort((a, b) => a.source - b.source);
+ for (const { tween } of bySource) timeline.remove(tween);
+ for (const { tween, start, duration } of bySource) {
+ if (tween.duration() !== duration) tween.duration(duration);
+ timeline.add(tween, start);
+ }
+ // Replayed to the playhead as the runtime binds a fresh load, callbacks included.
+ const at = timeline.time();
+ timeline.progress(0.0001, true);
+ timeline.totalTime(at, false);
+ }
+ // A script element runs once, so this only keeps the next comparison honest; nothing re-executes.
+ plan.script.textContent = plan.after;
+ return true;
+}
+
+/** Syncs a saved timing edit by moving the live tweens; false when only re-running the script can. */
+export function moveLiveTweens(
+ iframe: HTMLIFrameElement,
+ scriptText: string,
+ currentTime: number,
+ reloadPreview: () => void,
+): boolean {
+ const plan = planLiveRetimeFromPreview(iframe, scriptText);
+ if (plan.kind !== "retime") return false;
+ try {
+ if (!applyLiveRetime(iframe, plan)) return false;
+ } catch (error) {
+ console.error("[Studio] Moving the live tweens threw; reloading the preview", error);
+ reloadPreview();
+ return true;
+ }
+ if (!applySoftReloadFinalization(iframe, currentTime)) reloadPreview();
+ return true;
+}
diff --git a/packages/studio/src/utils/gsapSoftReload.ts b/packages/studio/src/utils/gsapSoftReload.ts
index c5855b731d..806029fe41 100644
--- a/packages/studio/src/utils/gsapSoftReload.ts
+++ b/packages/studio/src/utils/gsapSoftReload.ts
@@ -277,12 +277,26 @@ export function applySoftReloadFinalization(
}
}
-function timelineKeys(scriptText: string): string[] {
+export function timelineKeys(scriptText: string): string[] {
return [...scriptText.matchAll(/__timelines\s*\[\s*["'`]([^"'`]+)["'`]\s*\]/g)]
.map((m) => m[1]!)
.filter((key) => key !== "__proxied");
}
+/** The live script elements that register one of `keys` on `window.__timelines`. */
+export function scriptsRegistering(
+ scripts: readonly HTMLScriptElement[],
+ keys: readonly string[],
+): HTMLScriptElement[] {
+ return scripts.filter((script) => {
+ const text = script.textContent || "";
+ return keys.some(
+ (key) => text.includes(`__timelines["${key}"]`) || text.includes(`__timelines['${key}']`),
+ );
+ });
+}
+
+// fallow-ignore-next-line complexity
export function applySoftReload(
iframe: HTMLIFrameElement | null,
scriptText: string,
@@ -311,12 +325,7 @@ export function applySoftReload(
if (gsapScripts.length === 0) return "cannot-soft-reload";
// Remove only the stale script element(s) that registered a target key; one we
// can't match in the doc is left alone (re-running appends a fresh element).
- const staleScripts = gsapScripts.filter((script) =>
- targetKeys.some((key) => {
- const text = script.textContent || "";
- return text.includes(`__timelines["${key}"]`) || text.includes(`__timelines['${key}']`);
- }),
- );
+ const staleScripts = scriptsRegistering(gsapScripts, targetKeys);
// Multiple GSAP scripts exist but none registers a key this script owns — we
// can't identify which element to replace (ambiguous, matching
// extractGsapScriptText's single-script requirement). Escalate to a full reload