diff --git a/packages/core/src/runtime/editing/gsapSnapshot.test.ts b/packages/core/src/runtime/editing/gsapSnapshot.test.ts
new file mode 100644
index 0000000000..d6d643844d
--- /dev/null
+++ b/packages/core/src/runtime/editing/gsapSnapshot.test.ts
@@ -0,0 +1,153 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { gsap as realGsap } from "gsap";
+import { handleFor } from "../editingHandles";
+import { gsapSnapshot } from "./gsapSnapshot";
+import { MAX_SNAPSHOT_TEXT, MAX_SNAPSHOT_TWEENS } from "./gsapSnapshotLimits";
+
+afterEach(() => {
+ document.body.innerHTML = "";
+ for (const name of ["gsap", "__timelines", "__player"]) Reflect.deleteProperty(window, name);
+});
+
+function frame(tweens: unknown[], getProperty = (_el: Element, prop: string) => prop.length) {
+ Object.assign(window, {
+ gsap: { getProperty, defaults: () => ({ ease: "power1.out" }) },
+ __timelines: {
+ main: { getChildren: () => tweens, time: () => 2, vars: { defaults: { ease: "none" } } },
+ marker: true,
+ },
+ __player: { getTime: () => 2 },
+ });
+}
+
+describe("gsapSnapshot", () => {
+ it("copies each tween as plain data, with GSAP's parse and its targets' values now", async () => {
+ document.body.innerHTML = `
`;
+ const box = document.getElementById("box")!;
+ const pt = { p: "x", s: 0, c: 200, _next: { d: { _pt: { p: "scaleX", s: 1, c: 1 } } } };
+ frame([
+ {
+ targets: () => [box, { notAnElement: true }],
+ vars: { x: 200, scale: 2, ease: "expo.out", onComplete: () => {}, data: "hold" },
+ startTime: () => 1,
+ duration: () => 3,
+ _initted: true,
+ _pt: pt,
+ },
+ ]);
+
+ const snapshot = await gsapSnapshot();
+
+ expect(snapshot.time).toBe(2);
+ expect(snapshot.defaultEase).toBe("power1.out");
+ expect(snapshot.timelines).toEqual([
+ {
+ id: "main",
+ time: 2,
+ defaultEase: "none",
+ tweens: [
+ {
+ targets: [handleFor(box)],
+ vars: { x: 200, scale: 2, ease: "expo.out", data: "hold" },
+ start: 1,
+ duration: 3,
+ from: false,
+ initted: true,
+ parsed: [
+ { p: "x", s: 0, c: 200 },
+ { p: "scaleX", s: 1, c: 1 },
+ ],
+ parts: [],
+ },
+ ],
+ },
+ ]);
+ const [target] = snapshot.targets;
+ expect(target).toMatchObject({ handle: handleFor(box), id: "box", className: "card big" });
+ expect(Object.keys(target!.values).sort()).toEqual(["scale", "scaleX", "x", "y"]);
+ expect(() => structuredClone(snapshot)).not.toThrow();
+ });
+
+ it("refuses rather than cuts a timeline past the bound", async () => {
+ const tween = { targets: () => [], vars: {}, startTime: () => 0, duration: () => 1 };
+ frame(Array.from({ length: MAX_SNAPSHOT_TWEENS + 1 }, () => tween));
+ await expect(gsapSnapshot()).rejects.toThrow(/bound on tweens/);
+ });
+
+ it("refuses a tween value past the text bound", async () => {
+ const vars = { text: "a".repeat(MAX_SNAPSHOT_TEXT + 1) };
+ frame([{ targets: () => [], vars, startTime: () => 0, duration: () => 1 }]);
+ await expect(gsapSnapshot()).rejects.toThrow(/bound on text length/);
+ });
+
+ // fails without the fix: only values were held to the text bound, not keys, ids, eases or channel names.
+ it.each([
+ [
+ "a vars key",
+ () => frame([{ targets: () => [], vars: { ["k".repeat(MAX_SNAPSHOT_TEXT + 1)]: 1 } }]),
+ ],
+ [
+ "an element id",
+ () => {
+ document.body.innerHTML = ``;
+ frame([{ targets: () => [document.body.firstElementChild], vars: {} }]);
+ },
+ ],
+ [
+ "a timeline id",
+ () => {
+ frame([]);
+ Object.assign(window, {
+ __timelines: { ["t".repeat(MAX_SNAPSHOT_TEXT + 1)]: { getChildren: () => [] } },
+ });
+ },
+ ],
+ [
+ "the default ease",
+ () => {
+ frame([]);
+ Object.assign(window, {
+ gsap: { defaults: () => ({ ease: "e".repeat(MAX_SNAPSHOT_TEXT + 1) }) },
+ });
+ },
+ ],
+ [
+ "a parsed channel name",
+ () =>
+ frame([{ targets: () => [], _pt: { p: "p".repeat(MAX_SNAPSHOT_TEXT + 1), s: 0, c: 1 } }]),
+ ],
+ ])("refuses %s past the text bound", async (_name, set) => {
+ set();
+ await expect(gsapSnapshot()).rejects.toThrow(/bound on text length/);
+ });
+
+ // fails without the fix: a property-tween chain that loops back on itself was walked forever.
+ it("stops at a property-tween chain that loops back on itself", async () => {
+ const first: Record = {};
+ first._next = { _next: first };
+ frame([{ targets: () => [], vars: {}, _pt: first }]);
+
+ const snapshot = await gsapSnapshot();
+
+ expect(snapshot.timelines[0]!.tweens[0]!.parsed).toEqual([]);
+ });
+
+ // fails without the fix: GSAP's own state on a keyframes tween's vars tripped the nesting bound, so a sealed preview
+ // read no GSAP values and Add keyframe at playhead added nothing.
+ it("reads a real GSAP keyframes tween", async () => {
+ document.body.innerHTML = ``;
+ const tl = realGsap.timeline({ paused: true });
+ tl.to(
+ "#box",
+ { keyframes: { "0%": { x: 0, y: 0 }, "100%": { x: 1200, y: 240 } }, duration: 2 },
+ 0,
+ );
+ tl.seek(1);
+ Object.assign(window, { gsap: realGsap, __timelines: { main: tl } });
+
+ const snapshot = await gsapSnapshot();
+
+ expect(snapshot.timelines[0]!.tweens).toHaveLength(1);
+ expect(snapshot.targets[0]!.values.x).toBeCloseTo(600);
+ });
+});
diff --git a/packages/core/src/runtime/editing/gsapSnapshot.ts b/packages/core/src/runtime/editing/gsapSnapshot.ts
new file mode 100644
index 0000000000..84b5a8d929
--- /dev/null
+++ b/packages/core/src/runtime/editing/gsapSnapshot.ts
@@ -0,0 +1,266 @@
+// The frame's GSAP tweens as plain data, for a parent that cannot reach the frame's window.
+import type { EditingElementHandle } from "../editingElement";
+import { handleFor } from "../editingHandles";
+import { isPlainRecord } from "../editingPort";
+import { isElementNode } from "../domRealm";
+import {
+ MAX_SNAPSHOT_CHANNELS,
+ MAX_SNAPSHOT_FIELDS,
+ MAX_SNAPSHOT_TARGETS,
+ MAX_SNAPSHOT_TEXT,
+ MAX_SNAPSHOT_TWEENS,
+ MAX_VARS_DEPTH,
+} from "./gsapSnapshotLimits";
+
+export type SnapshotValue =
+ | number
+ | string
+ | boolean
+ | null
+ | SnapshotValue[]
+ | { [key: string]: SnapshotValue };
+
+export interface GsapSnapshotTween {
+ targets: EditingElementHandle[];
+ /** The tween's vars; functions, elements and other live objects are left out. */
+ vars: Record;
+ start: number;
+ duration: number;
+ from: boolean;
+ initted: boolean;
+ /** GSAP's parse of each channel: start `s` and change `c`. */
+ parsed: Array<{ p: string; s: number; c: number }>;
+ /** A keyframed tween's steps, timed within the tween. */
+ parts: GsapSnapshotTween[];
+}
+
+export interface GsapSnapshotTimeline {
+ id: string;
+ time: number | null;
+ defaultEase: string | null;
+ tweens: GsapSnapshotTween[];
+}
+
+export interface GsapSnapshotTarget {
+ handle: EditingElementHandle;
+ id: string;
+ className: string;
+ /** GSAP's current value of each channel a tween animates, and of x and y. */
+ values: Record;
+}
+
+export interface GsapSnapshot {
+ /** The player's time when read; null without a player. */
+ time: number | null;
+ defaultEase: string | null;
+ timelines: GsapSnapshotTimeline[];
+ targets: GsapSnapshotTarget[];
+}
+
+interface LiveTween {
+ targets?: () => unknown[];
+ vars?: unknown;
+ startTime?: () => number;
+ duration?: () => number;
+ _from?: unknown;
+ _initted?: unknown;
+ _pt?: LivePropTween;
+ timeline?: { getChildren?: () => LiveTween[] };
+}
+interface LivePropTween {
+ p?: unknown;
+ s?: unknown;
+ c?: unknown;
+ d?: { _pt?: LivePropTween };
+ _next?: LivePropTween;
+}
+interface LiveGsap {
+ getProperty?: (target: Element, prop: string) => unknown;
+ defaults?: () => { ease?: unknown };
+}
+interface LiveTimeline {
+ getChildren?: (nested: boolean) => LiveTween[];
+ time?: () => number;
+ vars?: { defaults?: { ease?: unknown } };
+}
+/** The frame globals this reads; typed here so the file also compiles where the runtime's are not. */
+interface FrameGlobals {
+ gsap?: LiveGsap;
+ __timelines?: Record;
+ __player?: { getTime?: () => number };
+ __hfWaitForSeekCompletion?: () => Promise;
+}
+
+const VARS_SKIP = new Set([
+ "ease",
+ "easeEach",
+ "duration",
+ "delay",
+ "stagger",
+ "overwrite",
+ "data",
+ "id",
+]);
+
+class SnapshotBound extends Error {
+ constructor(what: string) {
+ super(`the preview's GSAP state is past the snapshot bound on ${what}`);
+ }
+}
+
+/** Every text the snapshot carries, keys and ids included, is held to the text bound. */
+function capped(value: string): string {
+ if (value.length > MAX_SNAPSHOT_TEXT) throw new SnapshotBound("text length");
+ return value;
+}
+const text = (value: unknown) => (typeof value === "string" ? capped(value) : null);
+const finite = (value: unknown) =>
+ typeof value === "number" && Number.isFinite(value) ? value : 0;
+
+/** Every tween on the frame's timelines, after any seek in flight has painted. Throws past a bound. */
+export async function gsapSnapshot(): Promise {
+ const frame = window as unknown as FrameGlobals;
+ await frame.__hfWaitForSeekCompletion?.();
+ const gsap = frame.gsap;
+ const reader = new SnapshotReader();
+ const timelines: GsapSnapshotTimeline[] = [];
+ for (const [id, live] of Object.entries(frame.__timelines ?? {})) {
+ if (typeof live?.getChildren !== "function") continue;
+ const tweens = live.getChildren(true).filter((child) => typeof child.targets === "function");
+ if (timelines.length >= MAX_SNAPSHOT_TWEENS) throw new SnapshotBound("timelines");
+ timelines.push({
+ id: capped(id),
+ time: typeof live.time === "function" ? finite(live.time()) : null,
+ defaultEase: text(live.vars?.defaults?.ease),
+ tweens: tweens.map((tween) => reader.tween(tween)),
+ });
+ }
+ const time = frame.__player?.getTime?.();
+ return {
+ time: typeof time === "number" && Number.isFinite(time) ? time : null,
+ defaultEase: text(gsap?.defaults?.().ease),
+ timelines,
+ targets: reader.targets(gsap),
+ };
+}
+
+class SnapshotReader {
+ private tweens = 0;
+ private fields = 0;
+ private channels = new Map>();
+
+ tween(live: LiveTween): GsapSnapshotTween {
+ if (++this.tweens > MAX_SNAPSHOT_TWEENS) throw new SnapshotBound("tweens");
+ const elements = (live.targets?.() ?? []).filter(isElementNode);
+ const vars = this.plain(live.vars, 0);
+ const parsed = parsedChannels(live._pt);
+ const parts = (live.timeline?.getChildren?.() ?? []).map((part) => this.tween(part));
+ for (const element of elements) this.note(element, vars, parsed, parts);
+ const record = isPlainRecord(vars) ? (vars as Record) : {};
+ return { targets: elements.map(handleFor), vars: record, ...timing(live), parsed, parts };
+ }
+
+ targets(gsap: LiveGsap | undefined): GsapSnapshotTarget[] {
+ if (this.channels.size > MAX_SNAPSHOT_TARGETS) throw new SnapshotBound("targets");
+ return [...this.channels].map(([element, channels]) => {
+ if (channels.size > MAX_SNAPSHOT_CHANNELS) throw new SnapshotBound("channels");
+ const values: Record = {};
+ for (const channel of channels) {
+ const value = Number(gsap?.getProperty?.(element, channel));
+ if (Number.isFinite(value)) values[channel] = value;
+ }
+ const className = element.getAttribute("class") ?? "";
+ if (className.length > MAX_SNAPSHOT_TEXT) throw new SnapshotBound("class names");
+ return { handle: handleFor(element), id: capped(element.id), className, values };
+ });
+ }
+
+ private note(
+ element: Element,
+ vars: SnapshotValue | undefined,
+ parsed: GsapSnapshotTween["parsed"],
+ parts: GsapSnapshotTween[],
+ ) {
+ const channels = this.channels.get(element) ?? new Set(["x", "y"]);
+ this.channels.set(element, channels);
+ const steps = isPlainRecord(vars) ? [vars, ...stepsOf(vars.keyframes)] : [];
+ for (const step of steps)
+ for (const [key, value] of Object.entries(step))
+ if (!VARS_SKIP.has(key) && isChannelValue(value)) channels.add(key);
+ for (const { p } of [...parsed, ...parts.flatMap((part) => part.parsed)]) channels.add(p);
+ }
+
+ private plain(value: unknown, depth: number): SnapshotValue | undefined {
+ if (++this.fields > MAX_SNAPSHOT_FIELDS) throw new SnapshotBound("tween fields");
+ if (Array.isArray(value)) return this.list(value, depth);
+ if (isLiteralRecord(value)) return this.record(value, depth);
+ return scalar(value);
+ }
+
+ private list(value: unknown[], depth: number): SnapshotValue[] {
+ nested(depth);
+ return value.map((item) => this.plain(item, depth + 1) ?? null);
+ }
+
+ private record(value: Record, depth: number): Record {
+ nested(depth);
+ const out: Record = {};
+ for (const [key, item] of Object.entries(value)) {
+ const kept = this.plain(item, depth + 1);
+ if (kept !== undefined) out[capped(key)] = kept;
+ }
+ return out;
+ }
+}
+
+function timing(live: LiveTween) {
+ return {
+ start: finite(live.startTime?.()),
+ duration: finite(live.duration?.()),
+ from: Boolean(live._from),
+ initted: Boolean(live._initted),
+ };
+}
+
+// GSAP puts live objects on a tween's vars (`parent` is its timeline), and they reach the whole graph.
+const isLiteralRecord = (value: unknown): value is Record =>
+ isPlainRecord(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+function nested(depth: number) {
+ if (depth >= MAX_VARS_DEPTH) throw new SnapshotBound("nesting");
+}
+
+/** A value kept as is; functions, elements and other live objects are left out. */
+function scalar(value: unknown): SnapshotValue | undefined {
+ if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+ if (typeof value !== "string")
+ return typeof value === "boolean" || value === null ? value : undefined;
+ return capped(value);
+}
+
+/** A step's value, or an object-of-arrays keyframe's list of them. */
+const isChannelValue = (value: SnapshotValue): boolean =>
+ typeof value === "number" || typeof value === "string" || Array.isArray(value);
+
+/** Keyframe steps in any of GSAP's forms; an object of arrays is its own one step. */
+function stepsOf(keyframes: SnapshotValue | undefined): Record[] {
+ if (Array.isArray(keyframes)) return keyframes.filter(isPlainRecord) as never;
+ if (!isPlainRecord(keyframes)) return [];
+ return [keyframes, ...Object.values(keyframes).filter(isPlainRecord)] as never;
+}
+
+/** The tween's property tweens, CSSPlugin's nested ones included, in chain order; a node seen before ends a chain. */
+function parsedChannels(
+ first: LivePropTween | undefined,
+ seen = new Set(),
+): GsapSnapshotTween["parsed"] {
+ const out: GsapSnapshotTween["parsed"] = [];
+ for (let node = first; node && !seen.has(node); node = node._next) {
+ seen.add(node);
+ if (typeof node.p === "string" && typeof node.s === "number" && typeof node.c === "number")
+ out.push({ p: capped(node.p), s: node.s, c: node.c });
+ out.push(...parsedChannels(node.d?._pt, seen));
+ if (out.length > MAX_SNAPSHOT_CHANNELS) throw new SnapshotBound("parsed channels");
+ }
+ return out;
+}
diff --git a/packages/core/src/runtime/editing/gsapSnapshotLimits.ts b/packages/core/src/runtime/editing/gsapSnapshotLimits.ts
new file mode 100644
index 0000000000..fc673e295e
--- /dev/null
+++ b/packages/core/src/runtime/editing/gsapSnapshotLimits.ts
@@ -0,0 +1,6 @@
+export const MAX_SNAPSHOT_TWEENS = 2_048;
+export const MAX_SNAPSHOT_TARGETS = 512;
+export const MAX_SNAPSHOT_CHANNELS = 64;
+export const MAX_SNAPSHOT_FIELDS = 100_000;
+export const MAX_SNAPSHOT_TEXT = 4_096;
+export const MAX_VARS_DEPTH = 6;
diff --git a/packages/core/src/runtime/editingAgent.test.ts b/packages/core/src/runtime/editingAgent.test.ts
index 0487164a5e..272ab4bd8d 100644
--- a/packages/core/src/runtime/editingAgent.test.ts
+++ b/packages/core/src/runtime/editingAgent.test.ts
@@ -195,6 +195,7 @@ describe("installEditingAgent", () => {
"document-markup",
"set-audio-group-attribute",
"assign-audio-group",
+ "gsap-snapshot",
],
},
});
diff --git a/packages/core/src/runtime/editingAgent.ts b/packages/core/src/runtime/editingAgent.ts
index f6855237c3..1d7a946ad6 100644
--- a/packages/core/src/runtime/editingAgent.ts
+++ b/packages/core/src/runtime/editingAgent.ts
@@ -35,6 +35,7 @@ import { drawDrafts } from "./editingDraft";
import { restoreAttributes } from "./editing/restoreAttributes";
import { stopWatchingGeometry, watchGeometry } from "./editing/watchGeometry";
import { gestureStart } from "./editingGestureStart";
+import { gsapSnapshot } from "./editing/gsapSnapshot";
import {
getLogicalOpacity,
markedForStudio,
@@ -210,6 +211,7 @@ const HANDLERS: Handlers = {
"document-markup": documentMarkup,
"set-audio-group-attribute": setAudioGroupAttribute,
"assign-audio-group": (params) => assignAudioGroup(params, elementForHandle),
+ "gsap-snapshot": () => gsapSnapshot(),
};
function serve(port: MessagePort): void {
diff --git a/packages/core/src/runtime/editingPort.test.ts b/packages/core/src/runtime/editingPort.test.ts
index 727bc39210..9f5198bde7 100644
--- a/packages/core/src/runtime/editingPort.test.ts
+++ b/packages/core/src/runtime/editingPort.test.ts
@@ -88,6 +88,7 @@ describe("createEditingPortClient", () => {
"document-markup",
"set-audio-group-attribute",
"assign-audio-group",
+ "gsap-snapshot",
],
});
} finally {
diff --git a/packages/core/src/runtime/editingPort.ts b/packages/core/src/runtime/editingPort.ts
index 554422b978..a12b8e27e5 100644
--- a/packages/core/src/runtime/editingPort.ts
+++ b/packages/core/src/runtime/editingPort.ts
@@ -26,6 +26,7 @@ import {
} from "./editingElement";
import type { EditingElementBox, EditingElementGeometry } from "./editingGeometry";
import type { EditingGestureStart } from "./editingGestureStart";
+import type { GsapSnapshot } from "./editing/gsapSnapshot";
import type { EditingLayer } from "./editingLayers";
import type { RuntimeTimelineMessage } from "./types";
import { wallClearTimeout, wallSetTimeout } from "./wallClock";
@@ -96,6 +97,14 @@ export {
} from "./editingGeometry";
export type { EditingGestureStart } from "./editingGestureStart";
export { MAX_CAPTION_TRANSFORM } from "./editing/captionTransform";
+export {
+ MAX_SNAPSHOT_CHANNELS,
+ MAX_SNAPSHOT_FIELDS,
+ MAX_SNAPSHOT_TARGETS,
+ MAX_SNAPSHOT_TEXT,
+ MAX_SNAPSHOT_TWEENS,
+ MAX_VARS_DEPTH,
+} from "./editing/gsapSnapshotLimits";
export {
compositionPoint,
coversComposition,
@@ -156,6 +165,7 @@ export const EDITING_REQUEST_KINDS = [
"document-markup",
"set-audio-group-attribute",
"assign-audio-group",
+ "gsap-snapshot",
] as const;
export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number];
@@ -282,6 +292,7 @@ export interface EditingRequests {
params: AssignAudioGroupParams;
result: { previous: Array; changed: boolean };
};
+ "gsap-snapshot": { params: NoParams; result: GsapSnapshot };
}
export type EditingParams = EditingRequests[K]["params"];
export type EditingResult = EditingRequests[K]["result"];
@@ -479,6 +490,7 @@ const PARAM_PARSERS: {
"document-markup": noParams,
"set-audio-group-attribute": parseSetAudioGroupAttribute,
"assign-audio-group": parseAssignAudioGroup,
+ "gsap-snapshot": noParams,
};
/** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */
diff --git a/packages/studio/src/components/editor/previewDrafts.ts b/packages/studio/src/components/editor/previewDrafts.ts
index 3a67e74048..410cd89401 100644
--- a/packages/studio/src/components/editor/previewDrafts.ts
+++ b/packages/studio/src/components/editor/previewDrafts.ts
@@ -20,6 +20,8 @@ interface Queue {
const standIns = new WeakMap();
const queues = new WeakMap();
+export const previewStandInHandle = (standIn: Element) => standIns.get(standIn)?.handle;
+
export function registerPreviewStandIn(
standIn: Element,
iframe: HTMLIFrameElement,
diff --git a/packages/studio/src/hooks/gsapFrameSnapshot.test.ts b/packages/studio/src/hooks/gsapFrameSnapshot.test.ts
new file mode 100644
index 0000000000..b490eed105
--- /dev/null
+++ b/packages/studio/src/hooks/gsapFrameSnapshot.test.ts
@@ -0,0 +1,93 @@
+// @vitest-environment happy-dom
+
+import { afterEach, expect, it, vi } from "vitest";
+
+const request = vi.hoisted(() => vi.fn());
+vi.mock("../player/lib/previewChannel", () => {
+ const clients = new WeakMap();
+ return {
+ previewEditingClient: (iframe: HTMLIFrameElement) => {
+ if (!clients.has(iframe)) clients.set(iframe, {});
+ return clients.get(iframe);
+ },
+ previewFrameOpaque: () => true,
+ previewRequest: request,
+ };
+});
+
+import { usePlayerStore } from "../player/store/playerStore";
+import { frameDocument, frameTimelines, settleGsapSnapshot } from "./gsapFrameSnapshot";
+
+const HANDLE = "0123456789abcdef:1";
+const tween = {
+ targets: [HANDLE],
+ vars: { x: 200 },
+ start: 0,
+ duration: 1,
+ from: false,
+ initted: true,
+ parsed: [{ p: "x", s: 0, c: 200 }],
+ parts: [],
+};
+const target = { handle: HANDLE, id: "box", className: "", values: { x: 120 } };
+const snapshot = (over: Record = {}) => ({
+ time: 0.5,
+ defaultEase: null,
+ timelines: [{ id: "main", time: 0.5, defaultEase: null, tweens: [tween] }],
+ targets: [target],
+ ...over,
+});
+
+afterEach(() => {
+ request.mockReset();
+ usePlayerStore.setState({ currentTime: 0, isPlaying: false });
+});
+
+async function readReply(reply: unknown) {
+ usePlayerStore.setState({ currentTime: 0.5, isPlaying: false });
+ request.mockResolvedValue(reply);
+ const iframe = document.createElement("iframe");
+ await expect(settleGsapSnapshot(iframe)).resolves.toBeUndefined();
+ return iframe;
+}
+
+it("holds a well-formed reply", async () => {
+ const iframe = await readReply(snapshot());
+
+ expect(Object.keys(frameTimelines(iframe) ?? {})).toEqual(["main"]);
+ expect(frameDocument(iframe)?.getElementById("box")).not.toBeNull();
+});
+
+// fails without the fix: the frame's reply was used unchecked, so a malformed one threw or was held as is.
+it.each([
+ ["targets that are not a list", snapshot({ targets: null })],
+ [
+ "more targets than the frame may send",
+ snapshot({ targets: Array.from({ length: 513 }, () => target) }),
+ ],
+ ["a value that is not a number", snapshot({ targets: [{ ...target, values: { x: "7" } }] })],
+ [
+ "a tween start that is not finite",
+ snapshot({
+ timelines: [
+ { id: "main", time: 0.5, defaultEase: null, tweens: [{ ...tween, start: Number.NaN }] },
+ ],
+ }),
+ ],
+ ["a target that is not a handle", snapshot({ targets: [{ ...target, handle: "#box" }] })],
+ ["an id past the text bound", snapshot({ targets: [{ ...target, id: "b".repeat(4_097) }] })],
+ ["a reply that is not a record", "gsap"],
+])("refuses %s and holds nothing", async (_name, reply) => {
+ const iframe = await readReply(reply);
+
+ expect(frameTimelines(iframe)).toBeNull();
+ expect(frameDocument(iframe)).toBeNull();
+});
+
+it("keeps a timeline named __proto__ as a timeline, not the record's prototype", async () => {
+ const iframe = await readReply(
+ snapshot({ timelines: [{ id: "__proto__", time: 0.5, defaultEase: null, tweens: [tween] }] }),
+ );
+
+ expect(Object.keys(frameTimelines(iframe) ?? {})).toEqual(["__proto__"]);
+});
diff --git a/packages/studio/src/hooks/gsapFrameSnapshot.ts b/packages/studio/src/hooks/gsapFrameSnapshot.ts
new file mode 100644
index 0000000000..80298db6d2
--- /dev/null
+++ b/packages/studio/src/hooks/gsapFrameSnapshot.ts
@@ -0,0 +1,241 @@
+// A sealed preview's GSAP tweens, read over the editing port and shaped like the live objects the
+// readers walk. Tween data answers at any time; values and timeline times only at the playhead read.
+import { useSyncExternalStore } from "react";
+import type { EditingPortClient, EditingResult } from "@hyperframes/core/runtime/editing-port";
+import {
+ previewEditingClient,
+ previewFrameOpaque,
+ previewRequest,
+} from "../player/lib/previewChannel";
+import { onPreviewContentReplaced } from "../player/sceneSwap";
+import { usePlayerStore } from "../player/store/playerStore";
+import { usePreviewIframeStore } from "../player/store/previewIframeStore";
+import { previewStandInHandle } from "../components/editor/previewDrafts";
+import type { RuntimeTimeline } from "./gsapRuntimeKeyframes";
+import { readGsapSnapshot } from "./gsapSnapshotReply";
+
+type Snapshot = EditingResult<"gsap-snapshot">;
+type SnapshotTween = Snapshot["timelines"][number]["tweens"][number];
+
+interface HeldSnapshot {
+ /** The paused playhead the frame was read at. */
+ readAt: number | null;
+ json: string;
+ timelines: Record;
+ document: Document;
+ byHandle: Map;
+ values: WeakMap>;
+ defaultEase: string | null;
+}
+
+const held = new WeakMap();
+const asking = new WeakMap>();
+const watched = new WeakSet();
+const listeners = new Set<() => void>();
+let version = 0;
+
+const pausedPlayhead = (): number | null => {
+ const { isPlaying, currentTime } = usePlayerStore.getState();
+ return isPlaying ? null : currentTime;
+};
+
+function fresh(snapshot: HeldSnapshot): boolean {
+ const playhead = pausedPlayhead();
+ return playhead !== null && snapshot.readAt === playhead;
+}
+
+/** Half a frame at 60 fps: the frame may hold a seek to its own frame grid. */
+const SEEK_TOLERANCE_S = 1 / 120;
+const seekLanded = (frameTime: number | null, readAt: number | null) =>
+ frameTime !== null && readAt !== null && Math.abs(frameTime - readAt) <= SEEK_TOLERANCE_S;
+
+let watchingPlayhead = false;
+
+/** After a seek, the previewed frame is read again where the playhead stopped. */
+function watchPlayhead() {
+ if (watchingPlayhead) return;
+ watchingPlayhead = true;
+ usePlayerStore.subscribe((state, before) => {
+ if (state.isPlaying || state.currentTime === before.currentTime) return;
+ const { iframe } = usePreviewIframeStore.getState();
+ if (iframe && held.has(previewEditingClient(iframe))) void refreshGsapSnapshot(iframe);
+ });
+}
+
+function announce() {
+ version += 1;
+ for (const listener of listeners) listener();
+}
+
+/** Re-reads the frame's tweens; readers answer from the last read meanwhile. */
+function refreshGsapSnapshot(iframe: HTMLIFrameElement): Promise {
+ const client = previewEditingClient(iframe);
+ const pending = asking.get(client) ?? read(iframe, client);
+ asking.set(client, pending);
+ return pending;
+}
+
+/** Reads the frame again unless the held read is at the paused playhead, for async callers. */
+export async function settleGsapSnapshot(iframe: HTMLIFrameElement | null): Promise {
+ if (!iframe || !previewFrameOpaque(iframe)) return;
+ const snapshot = held.get(previewEditingClient(iframe));
+ if (!snapshot || !fresh(snapshot)) await refreshGsapSnapshot(iframe);
+}
+
+async function read(iframe: HTMLIFrameElement, client: EditingPortClient): Promise {
+ watchPlayhead();
+ if (!watched.has(client)) {
+ watched.add(client);
+ const stop = onPreviewContentReplaced(iframe, () => {
+ stop();
+ held.delete(client);
+ watched.delete(client);
+ void refreshGsapSnapshot(iframe);
+ });
+ }
+ const readAt = pausedPlayhead();
+ try {
+ const snapshot = readGsapSnapshot(await previewRequest(iframe, "gsap-snapshot", {}));
+ const before = held.get(client);
+ if (!snapshot) {
+ if (before) held.delete(client);
+ return;
+ }
+ const json = JSON.stringify(snapshot);
+ const stamp = pausedPlayhead() === readAt && seekLanded(snapshot.time, readAt) ? readAt : null;
+ if (before?.json === json && before.readAt === stamp) return;
+ held.set(client, hold(snapshot, json, stamp));
+ announce();
+ } finally {
+ asking.delete(client);
+ }
+}
+
+/** The last read of an opaque frame, asking again when there is none or the playhead moved. */
+function heldSnapshot(iframe: HTMLIFrameElement | null): HeldSnapshot | null {
+ if (!iframe || !previewFrameOpaque(iframe)) return null;
+ const snapshot = held.get(previewEditingClient(iframe)) ?? null;
+ if (!snapshot || (!fresh(snapshot) && pausedPlayhead() !== null))
+ void refreshGsapSnapshot(iframe);
+ return snapshot;
+}
+
+/** An opaque frame's timelines; null for a same-origin frame or before the first read lands. */
+export function frameTimelines(iframe: HTMLIFrameElement | null) {
+ return heldSnapshot(iframe)?.timelines ?? null;
+}
+
+/** An opaque frame's tween targets, as elements of a detached document a selector can query. */
+export function frameDocument(iframe: HTMLIFrameElement | null): Document | null {
+ return heldSnapshot(iframe)?.document ?? null;
+}
+
+export function frameQuery(iframe: HTMLIFrameElement | null, selector: string): Element | null {
+ try {
+ return frameDocument(iframe)?.querySelector(selector) ?? null;
+ } catch {
+ return null;
+ }
+}
+
+/** The snapshot's element for Studio's stand-in of a frame element, matched by handle, else id. */
+export function frameTarget(iframe: HTMLIFrameElement | null, element: Element): Element | null {
+ const snapshot = heldSnapshot(iframe);
+ if (!snapshot) return null;
+ const handle = previewStandInHandle(element);
+ const byHandle = handle ? snapshot.byHandle.get(handle) : undefined;
+ if (byHandle) return byHandle;
+ return element.id ? snapshot.document.getElementById(element.id) : null;
+}
+
+/** The ease GSAP falls back to; time-independent. */
+export function frameDefaultEase(iframe: HTMLIFrameElement | null): string | null {
+ return heldSnapshot(iframe)?.defaultEase ?? null;
+}
+
+/** GSAP's values as read at the paused playhead; null once it moved, until the next read lands. */
+export function frameGsap(iframe: HTMLIFrameElement | null) {
+ const snapshot = heldSnapshot(iframe);
+ if (!iframe || !snapshot || !fresh(snapshot)) return null;
+ return {
+ getProperty(element: Element, prop: string): number {
+ const target = snapshot.values.has(element) ? element : frameTarget(iframe, element);
+ return (target && snapshot.values.get(target)?.[prop]) ?? Number.NaN;
+ },
+ };
+}
+
+function subscribe(listener: () => void) {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+}
+
+/** Changes when a sealed frame's read lands, so memos over the readers recompute. */
+export function useGsapSnapshotVersion(): number {
+ return useSyncExternalStore(
+ subscribe,
+ () => version,
+ () => version,
+ );
+}
+
+function hold(snapshot: Snapshot, json: string, readAt: number | null): HeldSnapshot {
+ const document = window.document.implementation.createHTMLDocument("");
+ const byHandle = new Map();
+ const values = new WeakMap>();
+ for (const target of snapshot.targets) {
+ const element = document.createElement("div");
+ if (target.id) element.id = target.id;
+ if (target.className) element.setAttribute("class", target.className);
+ document.body.append(element);
+ byHandle.set(target.handle, element);
+ values.set(element, target.values);
+ }
+ const held: HeldSnapshot = {
+ readAt,
+ json,
+ // Ids are the frame's: a timeline named __proto__ must stay a timeline.
+ timelines: Object.create(null) as Record,
+ document,
+ byHandle,
+ values,
+ defaultEase: snapshot.defaultEase,
+ };
+ for (const line of snapshot.timelines) {
+ const timeline = {
+ vars: { defaults: { ease: line.defaultEase ?? undefined } },
+ time: () => (fresh(held) ? line.time : null),
+ getChildren: () => tweens,
+ } as unknown as RuntimeTimeline;
+ const tweens = line.tweens.map((tween) => liveShaped(tween, byHandle, timeline));
+ held.timelines[line.id] = timeline;
+ }
+ return held;
+}
+
+/** The fields of a GSAP tween the readers use, from the snapshot's copy. */
+function liveShaped(
+ tween: SnapshotTween,
+ byHandle: Map,
+ parent?: unknown,
+): Record {
+ const targets = tween.targets.flatMap((handle) => byHandle.get(handle) ?? []);
+ const _pt = tween.parsed.reduceRight