fix(studio): GSAP keyframe and value reads work in a sealed preview (#8003)

* test(studio): adding a keyframe at the playhead reads a sealed preview's GSAP values

* fix(studio): GSAP keyframe and value reads work in a sealed preview

* test(studio): run the sealed keyframe test's agent on a marked Studio preview page

* test(studio): a sealed preview's GSAP reply is checked before Studio holds it

* fix(studio): hold a sealed preview's GSAP reply only when it is in shape and within bounds

* style(core): keep the snapshot limits module within the comment share

* refactor(studio): check a GSAP reply's tween in small parts

* build: raise the core packed-size budget for the sealed preview's GSAP reader

* test(core): a sealed preview's GSAP read takes a real keyframes tween

* fix(core): a sealed preview's GSAP read leaves GSAP's live objects out of a tween's vars
This commit is contained in:
Miguel Ángel
2026-11-17 19:11:15 +00:00
committed by GitHub
parent 183bf2a416
commit 133965e4f5
18 changed files with 1046 additions and 30 deletions
@@ -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 = `<div id="box" class="card big"></div>`;
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 = `<div id="${"b".repeat(MAX_SNAPSHOT_TEXT + 1)}"></div>`;
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<string, unknown> = {};
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 = `<div id="box"></div>`;
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);
});
});
@@ -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<string, SnapshotValue>;
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<string, number>;
}
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<string, LiveTimeline | undefined>;
__player?: { getTime?: () => number };
__hfWaitForSeekCompletion?: () => Promise<unknown>;
}
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<GsapSnapshot> {
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<Element, Set<string>>();
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<string, SnapshotValue>) : {};
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<string, number> = {};
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<string, unknown>, depth: number): Record<string, SnapshotValue> {
nested(depth);
const out: Record<string, SnapshotValue> = {};
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<string, unknown> =>
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<string, SnapshotValue>[] {
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<LivePropTween>(),
): 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;
}
@@ -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;
@@ -195,6 +195,7 @@ describe("installEditingAgent", () => {
"document-markup",
"set-audio-group-attribute",
"assign-audio-group",
"gsap-snapshot",
],
},
});
@@ -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 {
@@ -88,6 +88,7 @@ describe("createEditingPortClient", () => {
"document-markup",
"set-audio-group-attribute",
"assign-audio-group",
"gsap-snapshot",
],
});
} finally {
+12
View File
@@ -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<string | null>; changed: boolean };
};
"gsap-snapshot": { params: NoParams; result: GsapSnapshot };
}
export type EditingParams<K extends EditingRequestKind> = EditingRequests[K]["params"];
export type EditingResult<K extends EditingRequestKind> = 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. */
@@ -20,6 +20,8 @@ interface Queue {
const standIns = new WeakMap<Element, { iframe: HTMLIFrameElement; handle: string }>();
const queues = new WeakMap<HTMLIFrameElement, Queue>();
export const previewStandInHandle = (standIn: Element) => standIns.get(standIn)?.handle;
export function registerPreviewStandIn(
standIn: Element,
iframe: HTMLIFrameElement,
@@ -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<HTMLIFrameElement, object>();
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<string, unknown> = {}) => ({
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__"]);
});
@@ -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<string, RuntimeTimeline>;
document: Document;
byHandle: Map<string, Element>;
values: WeakMap<Element, Record<string, number>>;
defaultEase: string | null;
}
const held = new WeakMap<EditingPortClient, HeldSnapshot>();
const asking = new WeakMap<EditingPortClient, Promise<void>>();
const watched = new WeakSet<EditingPortClient>();
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<void> {
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<void> {
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<void> {
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<string, Element>();
const values = new WeakMap<Element, Record<string, number>>();
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<string, RuntimeTimeline>,
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<string, Element>,
parent?: unknown,
): Record<string, unknown> {
const targets = tween.targets.flatMap((handle) => byHandle.get(handle) ?? []);
const _pt = tween.parsed.reduceRight<object | undefined>(
(next, { p, s, c }) => ({ p, s, c, _next: next }),
undefined,
);
const parts: Array<Record<string, unknown>> = tween.parts.map((part) =>
liveShaped(part, byHandle),
);
return {
vars: tween.vars,
_from: tween.from,
_initted: tween.initted,
_pt,
parent,
targets: () => targets,
startTime: () => tween.start,
duration: () => tween.duration,
...(parts.length > 0 && { timeline: { getChildren: () => parts } }),
};
}
+16 -9
View File
@@ -3,6 +3,7 @@ import { elementTargets } from "../utils/elementGsap";
import { resolveTweenStart } from "../utils/globalTimeCompiler";
import { KEYFRAME_PCT_MATCH } from "./gsapShared";
import { previewFrameOpaque } from "../player/lib/previewChannel";
import { frameDefaultEase, frameTarget, frameTimelines } from "./gsapFrameSnapshot";
import type { ImplicitEndValue } from "./gsapValueAtPlayhead";
import type { ReadTween } from "./gsapRuntimeKeyframes";
@@ -82,23 +83,28 @@ export function findParsedTween(
element: Element,
anim: GsapAnimation,
): ParsedTween | null {
if (!iframe || previewFrameOpaque(iframe)) return null;
const win = iframe.contentWindow as GsapWindow | null;
if (!iframe) return null;
const sealed = previewFrameOpaque(iframe);
const win = sealed ? null : (iframe.contentWindow as GsapWindow | null);
const timelines = sealed
? (frameTimelines(iframe) as GsapWindow["__timelines"])
: win?.__timelines;
const target = sealed ? frameTarget(iframe, element) : element;
const start = resolveTweenStart(anim);
if (!win?.__timelines || start == null) return null;
if (!timelines || !target || start == null) return null;
const steps = anim.keyframes?.keyframes.map((kf) => kf.properties) ?? [anim.properties];
const props = [...new Set(steps.flatMap((step) => Object.keys(step)))];
const keyframed = Boolean(anim.keyframes);
for (const timeline of Object.values(win.__timelines)) {
for (const timeline of Object.values(timelines)) {
for (const tween of timeline?.getChildren?.(true) ?? []) {
const targets = (tween.targets?.() ?? []) as Array<{ id?: unknown }>;
if (!targets.includes(element) && !targets.some((t) => element.id && t.id === element.id))
if (!targets.includes(target) && !targets.some((t) => target.id && t.id === target.id))
continue;
if (!startsAt(tween, start)) continue;
const vars = tween.vars ?? {};
const carries = keyframed ? "keyframes" in vars : props.some((p) => p in vars);
if (!carries || !((tween.duration?.() ?? 0) > 0)) continue;
parseUnplayed(win, element, tween, props);
if (win) parseUnplayed(win, element, tween, props);
return tween;
}
}
@@ -220,9 +226,10 @@ function partsFrom(tween: ParsedTween, end: "start" | "end"): ParsedTween[] {
/** The ease GSAP resolved for a flat tween that authors none: its timeline's default, else GSAP's. */
export function parsedTweenEase(iframe: HTMLIFrameElement | null, tween: ParsedTween | null) {
if (!tween) return null;
const win = iframe?.contentWindow as GsapWindow | null;
const ease =
tween.vars?.ease ?? tween.parent?.vars?.defaults?.ease ?? win?.gsap?.defaults?.().ease;
const sealed = iframe ? previewFrameOpaque(iframe) : false;
const win = sealed ? null : (iframe?.contentWindow as GsapWindow | null);
const fallback = sealed ? frameDefaultEase(iframe) : win?.gsap?.defaults?.().ease;
const ease = tween.vars?.ease ?? tween.parent?.vars?.defaults?.ease ?? fallback;
if (typeof ease === "string") return ease;
const named = (name: string) => win?.gsap?.parseEase?.(name) === ease;
return typeof ease === "function" ? (BUILT_IN_EASES.find(named) ?? null) : null;
@@ -17,6 +17,8 @@ import { matchesElement, tweensTargeting } from "./gsapRuntimeTweenIndex";
import { withParsedStart } from "./gsapParsedTween";
import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
import { gsapRendersTransform } from "../components/editor/gsapAnimatesProperty";
import { previewFrameOpaque } from "../player/lib/previewChannel";
import { frameQuery, frameTimelines } from "./gsapFrameSnapshot";
/**
* A GSAP tween's `vars` object — intentionally open: it mixes channel values
@@ -96,6 +98,20 @@ function timelinesOf(iframe: HTMLIFrameElement | null): Record<string, RuntimeTi
}
}
/** A sealed frame reads from its snapshot; resolveRuntimeTween patches, so it takes live tweens only. */
function readableTimelines(iframe: HTMLIFrameElement | null) {
return iframe && previewFrameOpaque(iframe) ? frameTimelines(iframe) : timelinesOf(iframe);
}
function readableTarget(iframe: HTMLIFrameElement | null, selector: string): Element | null {
if (iframe && previewFrameOpaque(iframe)) return frameQuery(iframe, selector);
try {
return iframe?.contentDocument?.querySelector(selector) ?? null;
} catch {
return null;
}
}
/**
* A tween we must skip when reading keyframes: a zero-duration `set`/hold (incl.
* the studio pre-keyframe position hold, tagged `data: STUDIO_HOLD_MARKER`).
@@ -292,15 +308,10 @@ export function readRuntimeKeyframes(
requireChannels?: string[],
// fallow-ignore-next-line code-duplication
): ReadTween | null {
const timelines = timelinesOf(iframe);
const timelines = readableTimelines(iframe);
if (!timelines) return null;
let targetEl: Element | null = null;
try {
targetEl = iframe?.contentDocument?.querySelector(selector) ?? null;
} catch {
return null;
}
const targetEl = readableTarget(iframe, selector);
if (!targetEl) return null;
// Search the element's OWN composition timeline. With inlined subcompositions the
@@ -366,13 +377,10 @@ export function hasNonHoldTweenForElement(
compositionId?: string,
channels?: string[],
): boolean {
let targetEl: Element | null = null;
try {
targetEl = iframe?.contentDocument?.querySelector(selector) ?? null;
} catch {
return false;
}
return !!targetEl && hasNonHoldTween(timelinesOf(iframe), targetEl, channels, compositionId);
const targetEl = readableTarget(iframe, selector);
return (
!!targetEl && hasNonHoldTween(readableTimelines(iframe), targetEl, channels, compositionId)
);
}
// A sibling rotation/scale tween must never push a static position hold into the keyframe branch.
@@ -545,7 +553,7 @@ export function scanAllRuntimeKeyframes(
clipById?: ClipDims,
): Map<string, RuntimeKeyframeEntry> {
const result = new Map<string, RuntimeKeyframeEntry>();
const timelines = timelinesOf(iframe);
const timelines = readableTimelines(iframe);
if (!timelines) return result;
for (const timeline of Object.values(timelines)) {
if (!timeline?.getChildren) continue;
+4
View File
@@ -14,6 +14,8 @@ import {
resolveTweenDuration,
} from "../utils/globalTimeCompiler";
import { toCompositionTime } from "../player/store/timelineElement";
import { previewFrameOpaque } from "../player/lib/previewChannel";
import { frameGsap, frameQuery } from "./gsapFrameSnapshot";
// ── Types ─────────────────────────────────────────────────────────────────────
@@ -361,6 +363,7 @@ export function computeElementPercentage(
/** Safely retrieve the GSAP runtime from the preview iframe. */
export function getIframeGsap(iframe: HTMLIFrameElement | null): IframeGsap | null {
if (iframe && previewFrameOpaque(iframe)) return frameGsap(iframe);
if (!iframe?.contentWindow) return null;
try {
const gsap = (iframe.contentWindow as unknown as { gsap?: IframeGsap }).gsap;
@@ -375,6 +378,7 @@ export function queryIframeElement(
iframe: HTMLIFrameElement | null,
selector: string,
): Element | null {
if (iframe && previewFrameOpaque(iframe)) return frameQuery(iframe, selector);
try {
return iframe?.contentDocument?.querySelector(selector) ?? null;
} catch {
@@ -0,0 +1,110 @@
// A gsap-snapshot reply is frame data: Studio holds one only in the shape and within the
// bounds the frame keeps to.
import {
EDITING_ELEMENT_HANDLE,
MAX_SNAPSHOT_CHANNELS,
MAX_SNAPSHOT_FIELDS,
MAX_SNAPSHOT_TARGETS,
MAX_SNAPSHOT_TEXT,
MAX_SNAPSHOT_TWEENS,
MAX_VARS_DEPTH,
type EditingResult,
} from "@hyperframes/core/runtime/editing-port";
type Snapshot = EditingResult<"gsap-snapshot">;
type Fields = Record<string, unknown>;
/** What the whole reply may still spend, shared by every tween and vars field in it. */
type Budget = { tweens: number; fields: number };
const isFields = (value: unknown): value is Fields =>
typeof value === "object" && value !== null && !Array.isArray(value);
const isText = (value: unknown): value is string =>
typeof value === "string" && value.length <= MAX_SNAPSHOT_TEXT;
const isTextOrNull = (value: unknown) => value === null || isText(value);
const isNumber = (value: unknown): value is number =>
typeof value === "number" && Number.isFinite(value);
const isNumberOrNull = (value: unknown) => value === null || isNumber(value);
const isHandle = (value: unknown) =>
typeof value === "string" && EDITING_ELEMENT_HANDLE.test(value);
const isList = (value: unknown, max: number): value is unknown[] =>
Array.isArray(value) && value.length <= max;
/** The reply as a snapshot, or null when any part of it is off its shape or past a bound. */
export function readGsapSnapshot(value: unknown): Snapshot | null {
if (!isFields(value) || !isNumberOrNull(value.time) || !isTextOrNull(value.defaultEase))
return null;
const budget: Budget = { tweens: MAX_SNAPSHOT_TWEENS, fields: MAX_SNAPSHOT_FIELDS };
const { timelines, targets } = value;
const ok =
isList(timelines, MAX_SNAPSHOT_TWEENS) &&
timelines.every((line) => isTimeline(line, budget)) &&
isList(targets, MAX_SNAPSHOT_TARGETS) &&
targets.every(isTarget);
return ok ? (value as unknown as Snapshot) : null;
}
function isTimeline(value: unknown, budget: Budget): boolean {
return (
isFields(value) &&
isText(value.id) &&
isNumberOrNull(value.time) &&
isTextOrNull(value.defaultEase) &&
isList(value.tweens, MAX_SNAPSHOT_TWEENS) &&
value.tweens.every((tween) => isTween(tween, budget))
);
}
function isTween(value: unknown, budget: Budget): boolean {
if ((budget.tweens -= 1) < 0 || !isFields(value)) return false;
return (
isTargetHandles(value.targets) &&
isFields(value.vars) &&
isVars(value.vars, budget, 0) &&
isTiming(value) &&
isParsed(value.parsed) &&
areParts(value.parts, budget)
);
}
const isTargetHandles = (value: unknown) =>
isList(value, MAX_SNAPSHOT_TARGETS) && value.every(isHandle);
const isTiming = (tween: Fields) =>
isNumber(tween.start) &&
isNumber(tween.duration) &&
typeof tween.from === "boolean" &&
typeof tween.initted === "boolean";
const isChannel = (value: unknown) =>
isFields(value) && isText(value.p) && isNumber(value.s) && isNumber(value.c);
const isParsed = (value: unknown) => isList(value, MAX_SNAPSHOT_CHANNELS) && value.every(isChannel);
function areParts(value: unknown, budget: Budget): boolean {
return isList(value, MAX_SNAPSHOT_TWEENS) && value.every((part) => isTween(part, budget));
}
/** A plain vars value: finite numbers, bounded text, booleans, null, and lists and records
* no deeper than the frame's. */
function isVars(value: unknown, budget: Budget, depth: number): boolean {
if ((budget.fields -= 1) < 0) return false;
if (value === null || typeof value === "boolean" || isNumber(value) || isText(value)) return true;
if (depth >= MAX_VARS_DEPTH) return false;
if (Array.isArray(value)) return value.every((item) => isVars(item, budget, depth + 1));
return (
isFields(value) &&
Object.entries(value).every(([key, item]) => isText(key) && isVars(item, budget, depth + 1))
);
}
function isTarget(value: unknown): boolean {
if (!isFields(value) || !isFields(value.values)) return false;
const values = Object.entries(value.values);
return (
isHandle(value.handle) &&
isText(value.id) &&
isText(value.className) &&
values.length <= MAX_SNAPSHOT_CHANNELS &&
values.every(([key, number]) => isText(key) && isNumber(number))
);
}
@@ -0,0 +1,97 @@
// @vitest-environment happy-dom
import { afterEach, expect, it, vi } from "vitest";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
// The frame's real runtime agent, serving the opaque frame from this document as Studio's marked preview page.
import { installMarkedEditingAgent } from "../../../core/src/runtime/editingAgent.test-helpers";
import { detachedFakeIframe } from "../player/hooks/timelinePlayerTestHarness";
import { describePreviewElements, queryPreviewElements } from "../player/lib/previewElements";
import { usePlayerStore } from "../player/store/playerStore";
import { standInFor } from "../components/editor/previewSelection";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { applyKeyframeAtPlayhead, type EnableKeyframesSession } from "./useEnableKeyframes";
const closers: Array<() => void> = [];
afterEach(() => {
closers.splice(0).forEach((close) => close());
usePlayerStore.setState({ currentTime: 0, isPlaying: false });
document.body.innerHTML = "";
for (const name of ["gsap", "__timelines", "__player"]) Reflect.deleteProperty(window, name);
});
/** A frame Studio cannot read, whose runtime is the real editing agent over this document. */
function opaqueFrame() {
const frame: Record<string, unknown> = {};
const iframe = detachedFakeIframe(frame);
Object.defineProperty(iframe, "contentDocument", { value: null });
Object.defineProperty(frame, "document", {
get: () => {
throw new DOMException("blocked", "SecurityError");
},
});
const parent = {
postMessage: (data: unknown, _origin: string, ports: MessagePort[]) =>
window.dispatchEvent(
new MessageEvent("message", { source: frame as unknown as Window, data, ports }),
),
} as unknown as Window;
const agent = installMarkedEditingAgent(parent);
frame.postMessage = (data: unknown) =>
window.dispatchEvent(new MessageEvent("message", { source: parent, data }));
closers.push(() => agent.dispose());
return iframe;
}
/** The frame's GSAP: one keyframed tween moving #box, paused half way where GSAP has it at 120, 40. */
function frameGsapAt(seconds: number) {
const box = document.getElementById("box")!;
const live = { x: 120, y: 40 } as Record<string, number>;
const tween = {
targets: () => [box],
vars: { keyframes: { "0%": { x: 0, y: 0 }, "100%": { x: 200, y: 80 } }, duration: 1 },
startTime: () => 0,
duration: () => 1,
_initted: true,
};
Object.assign(window, {
gsap: { getProperty: (el: Element, prop: string) => (el === box ? live[prop] : 0) },
__timelines: { main: { getChildren: () => [tween], time: () => seconds } },
__player: { getTime: () => seconds },
});
}
const keyframed: GsapAnimation = {
id: "#box-to-0-position",
targetSelector: "#box",
method: "to",
position: 0,
duration: 1,
properties: {},
keyframes: {
format: "percentage",
keyframes: [
{ percentage: 0, properties: { x: 0, y: 0 } },
{ percentage: 100, properties: { x: 200, y: 80 } },
],
},
};
// fails without the fix: a sealed preview's GSAP values were out of reach, so the add did nothing.
it("adds a keyframe at the playhead with the sealed preview's GSAP values there", async () => {
document.body.innerHTML = `<main data-composition-id="main"><div id="box"></div></main>`;
frameGsapAt(0.5);
usePlayerStore.setState({ currentTime: 0.5, isPlaying: false });
const iframe = opaqueFrame();
const [match] = (await queryPreviewElements(iframe, "#box"))!.matches;
const [described] = (await describePreviewElements(iframe, [match!.handle]))!;
const sel = { id: "box", selector: "#box", element: standInFor(iframe, described!) };
const addKeyframes = vi.fn(async () => undefined);
const session = {
handleGsapAddKeyframeBatch: addKeyframes,
handleGsapRemoveKeyframe: vi.fn(),
} as unknown as EnableKeyframesSession;
await applyKeyframeAtPlayhead(session, sel as DomEditSelection, keyframed, 0.5, iframe);
expect(addKeyframes).toHaveBeenCalledWith(keyframed.id, 50, { x: 120, y: 40 }, undefined);
});
@@ -33,6 +33,8 @@ import { findParsedTween, withLiveTiming } from "./gsapParsedTween";
import { roundTo3 } from "../utils/rounding";
import { readTranslatePxLeavingPercent } from "../components/editor/plainTranslate";
import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
import { previewFrameOpaque } from "../player/lib/previewChannel";
import { frameGsap, settleGsapSnapshot } from "./gsapFrameSnapshot";
import {
buildExtendedKeyframes,
buildTemporalArcKeyframes,
@@ -133,15 +135,19 @@ function readElementPosition(
const result: Record<string, number> = {};
if (!iframe?.contentWindow) return result;
const sealed = previewFrameOpaque(iframe);
let gsap: { getProperty?: (el: Element, prop: string) => number } | undefined;
try {
gsap = (iframe.contentWindow as Window & { gsap?: typeof gsap }).gsap;
gsap = sealed
? (frameGsap(iframe) ?? undefined)
: (iframe.contentWindow as Window & { gsap?: typeof gsap }).gsap;
} catch {
return result;
}
// A sealed selection is Studio's stand-in, which the snapshot matches by handle.
const element = sel.element;
if (!element?.isConnected || !gsap?.getProperty) return result;
if (!element || (!sealed && !element.isConnected) || !gsap?.getProperty) return result;
// ponytail: a brand-new tween captures position only — bundling opacity made it
// a mixed group that the position-only drag intercept couldn't resolve.
@@ -280,6 +286,7 @@ export async function applyKeyframeAtPlayhead(
commitOverrides?: Partial<CommitMutationOptions>,
liveTween?: ReturnType<typeof findParsedTween>,
): Promise<void> {
await settleGsapSnapshot(iframe);
const keepAuthoredDuration = kfAnim.durationUnresolved === true;
if (keepAuthoredDuration) {
kfAnim = withLiveTiming(kfAnim, liveTween ?? findParsedTween(iframe, sel.element, kfAnim));
@@ -20,12 +20,17 @@ import {
} from "./gsapTweenSynth";
import { fetchParsedAnimations, populateKeyframeCacheFromAst } from "./keyframeCacheAstLoad";
import { getAnimationsForElement } from "./gsapElementMatch";
import { frameDocument, useGsapSnapshotVersion } from "./gsapFrameSnapshot";
// Re-exported so callers keep importing the GSAP cache surface from one module.
export { resolveClipTimingBasis } from "./gsapShared";
export { fetchParsedAnimations, resolveSelectorElementIds } from "./keyframeCacheAstLoad";
export { getAnimationsForElement } from "./gsapElementMatch";
/** The frame's document, or a sealed frame's tween targets as one a selector can query. */
const previewDocument = (iframe: HTMLIFrameElement | null | undefined) =>
iframe?.contentDocument ?? frameDocument(iframe ?? null);
export function useGsapAnimationsForElement(
projectId: string | null,
sourceFile: string,
@@ -83,20 +88,21 @@ export function useGsapAnimationsForElement(
const targetId = target?.id ?? null;
const targetSelector = target?.selector ?? null;
const snapshotVersion = useGsapSnapshotVersion();
const rawAnimations = useMemo(() => {
if (!targetId && !targetSelector) return [];
// Resolve the live element so class / descendant tweens (e.g.
// gsap.from(".dot", {stagger})) attribute to every matching element, not
// just the one whose exact selector equals the tween's. `version` re-runs
// this after composition reloads.
const element = target ? findPreviewNode(iframeRef?.current?.contentDocument, target) : null;
const element = target ? findPreviewNode(previewDocument(iframeRef?.current), target) : null;
return getAnimationsForElement(
allAnimations,
{ id: targetId, selector: targetSelector },
element,
);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [allAnimations, target, version, iframeRef]);
}, [allAnimations, target, version, iframeRef, snapshotVersion]);
// fallow-ignore-next-line complexity
const animations = useMemo(() => {
@@ -301,7 +307,7 @@ export function usePopulateKeyframeCacheForFile(
if (!sameData) pruneKeyframeCacheToFiles(files);
if (stale.length === 0) return;
runtimeScanDoneRef.current = "";
const doc = iframeRef?.current?.contentDocument;
const doc = previewDocument(iframeRef?.current);
for (const sf of stale) {
void populateKeyframeCacheFromAst(projectId, sf, doc).then((loaded) => {
if (!loaded && loadedRef.current.dataKey === dataKey) loadedRef.current.files.delete(sf);
+1 -1
View File
@@ -8,7 +8,7 @@
"unpacked": 25500000
},
"@hyperframes/core": {
"packed": 1800000,
"packed": 1820000,
"unpacked": 4639000
},
"@hyperframes/engine": {