mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
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:
@@ -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 {
|
||||
|
||||
@@ -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 } }),
|
||||
};
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
"unpacked": 25500000
|
||||
},
|
||||
"@hyperframes/core": {
|
||||
"packed": 1800000,
|
||||
"packed": 1820000,
|
||||
"unpacked": 4639000
|
||||
},
|
||||
"@hyperframes/engine": {
|
||||
|
||||
Reference in New Issue
Block a user