Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 complexityexport 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