mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
fix(studio): a value or keyframe edit shows in place in a sealed preview (#8151)
* fix(studio): a value or keyframe edit shows in place in a sealed preview * fix(studio): a sealed group edit reloads once at its end, and a batch renders its last tween * refactor(studio): the sealed tween patch path lives in its own module Keeps useGsapScriptCommits under Studio's 600-line limit, and records the authoredOpacity helpers' move into core as an intended deletion. * refactor(studio): the sealed tween patch code passes the quality audit without suppressions Splits the frame-side change parser per kind, the tween lookup and keyframe rebuild into small checks, and the reachable-preview patch out of applyPreviewSync; drops an unused type re-export.
This commit is contained in:
@@ -464,6 +464,12 @@
|
||||
"types": "./dist/runtime/editingPort.d.ts",
|
||||
"environments": ["browser", "bun", "node"]
|
||||
},
|
||||
"./runtime/patch-tween": {
|
||||
"source": "./src/runtime/editing/patchTween.ts",
|
||||
"runtime": "./dist/runtime/editing/patchTween.js",
|
||||
"types": "./dist/runtime/editing/patchTween.d.ts",
|
||||
"environments": ["browser", "bun", "node"]
|
||||
},
|
||||
"./runtime/clip-window": {
|
||||
"source": "./src/runtime/clipWindow.ts",
|
||||
"runtime": "./dist/runtime/clipWindow.js",
|
||||
|
||||
@@ -471,6 +471,12 @@
|
||||
"import": "./src/runtime/editingPort.ts",
|
||||
"types": "./src/runtime/editingPort.ts"
|
||||
},
|
||||
"./runtime/patch-tween": {
|
||||
"bun": "./src/runtime/editing/patchTween.ts",
|
||||
"node": "./dist/runtime/editing/patchTween.js",
|
||||
"import": "./src/runtime/editing/patchTween.ts",
|
||||
"types": "./src/runtime/editing/patchTween.ts"
|
||||
},
|
||||
"./runtime/clip-window": {
|
||||
"bun": "./src/runtime/clipWindow.ts",
|
||||
"node": "./dist/runtime/clipWindow.js",
|
||||
@@ -983,6 +989,10 @@
|
||||
"import": "./dist/runtime/editingPort.js",
|
||||
"types": "./dist/runtime/editingPort.d.ts"
|
||||
},
|
||||
"./runtime/patch-tween": {
|
||||
"import": "./dist/runtime/editing/patchTween.js",
|
||||
"types": "./dist/runtime/editing/patchTween.d.ts"
|
||||
},
|
||||
"./runtime/clip-window": {
|
||||
"import": "./dist/runtime/clipWindow.js",
|
||||
"types": "./dist/runtime/clipWindow.d.ts"
|
||||
|
||||
@@ -39,6 +39,17 @@ export const COLOR_GRADING_SOURCE_HIDDEN_ATTR = "data-hf-color-grading-source-hi
|
||||
*/
|
||||
export const COLOR_GRADING_AUTHORED_OPACITY_ATTR = "data-hf-authored-opacity";
|
||||
|
||||
export function readStampedAuthoredOpacity(element: {
|
||||
getAttribute(name: string): string | null;
|
||||
}): string | null {
|
||||
return element.getAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR);
|
||||
}
|
||||
|
||||
export function applyAuthoredInlineOpacity(style: CSSStyleDeclaration, authored: string): void {
|
||||
if (authored === "") style.removeProperty("opacity");
|
||||
else style.setProperty("opacity", authored);
|
||||
}
|
||||
|
||||
export const HF_COLOR_GRADING_CANVAS_ID_PREFIX = "__hf_color_grading_";
|
||||
|
||||
export const HF_COLOR_GRADING_COLOR_SPACE = COLOR_GRADING_COLOR_SPACE;
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import { parsePatchTweens, patchTweens } from "./patchTween";
|
||||
|
||||
afterEach(() => {
|
||||
document.body.innerHTML = "";
|
||||
for (const key of ["__timelines", "__player", "gsap"]) Reflect.deleteProperty(window, key);
|
||||
});
|
||||
|
||||
function frameWithSets(...tweenVars: Array<Record<string, unknown>>) {
|
||||
document.body.innerHTML = `<div id="a"></div><div id="b"></div>`;
|
||||
const el = (id: string) => document.getElementById(id)!;
|
||||
const tweens = tweenVars.map((vars) => ({
|
||||
vars,
|
||||
targets: () => [el(String(vars.target))],
|
||||
duration: () => 0,
|
||||
startTime: () => 0,
|
||||
invalidate: vi.fn(),
|
||||
}));
|
||||
const seek = vi.fn();
|
||||
Object.assign(window, {
|
||||
__timelines: { main: { getChildren: () => tweens, time: () => 2 } },
|
||||
__player: { getTime: () => 2, seek },
|
||||
});
|
||||
return { tweens, seek };
|
||||
}
|
||||
|
||||
describe("patch-tweens in the frame", () => {
|
||||
it("patches each element's own set and renders once, after the last", () => {
|
||||
const { tweens, seek } = frameWithSets({ target: "a", x: 0 }, { target: "b", x: 0 });
|
||||
|
||||
const reply = patchTweens({
|
||||
patches: [
|
||||
{ selector: "#a", change: { kind: "set", props: { x: 10 } } },
|
||||
{ selector: "#b", change: { kind: "set", props: { x: 20 } } },
|
||||
],
|
||||
seek: true,
|
||||
});
|
||||
|
||||
expect(reply).toEqual({ patched: true });
|
||||
expect(tweens.map((t) => t.vars.x)).toEqual([10, 20]);
|
||||
expect(seek).toHaveBeenCalledExactlyOnceWith(2);
|
||||
});
|
||||
|
||||
it("leaves the render to a later write of the same group", () => {
|
||||
const { seek } = frameWithSets({ target: "a", x: 0 });
|
||||
|
||||
patchTweens({
|
||||
patches: [{ selector: "#a", change: { kind: "set", props: { x: 5 } } }],
|
||||
seek: false,
|
||||
});
|
||||
|
||||
expect(seek).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("stops at the first patch it cannot place, so the caller reloads", () => {
|
||||
const { tweens } = frameWithSets({ target: "a", x: "+=100" }, { target: "b", x: 0 });
|
||||
|
||||
const reply = patchTweens({
|
||||
patches: [
|
||||
{ selector: "#a", change: { kind: "set", props: { x: 10 } } },
|
||||
{ selector: "#b", change: { kind: "set", props: { x: 20 } } },
|
||||
],
|
||||
seek: true,
|
||||
});
|
||||
|
||||
expect(reply).toEqual({ patched: false });
|
||||
expect(tweens[1]!.vars.x).toBe(0);
|
||||
});
|
||||
|
||||
it("renders a patched set even when the batch ends in a base value", () => {
|
||||
const { tweens, seek } = frameWithSets({ target: "a", x: 0 });
|
||||
Object.assign(window, { gsap: { set: vi.fn() } });
|
||||
|
||||
const reply = patchTweens({
|
||||
patches: [
|
||||
{ selector: "#a", change: { kind: "set", props: { x: 10 } } },
|
||||
{ selector: "#b", change: { kind: "global-set", props: { rotation: 45 } } },
|
||||
],
|
||||
seek: true,
|
||||
});
|
||||
|
||||
expect(reply).toEqual({ patched: true });
|
||||
expect(tweens[0]!.vars.x).toBe(10);
|
||||
expect(seek).toHaveBeenCalledExactlyOnceWith(2);
|
||||
});
|
||||
|
||||
it("applies a base value with the frame's own GSAP", () => {
|
||||
frameWithSets();
|
||||
const set = vi.fn();
|
||||
Object.assign(window, { gsap: { set } });
|
||||
|
||||
const reply = patchTweens({
|
||||
patches: [{ selector: "#b", change: { kind: "global-set", props: { rotation: 45 } } }],
|
||||
seek: true,
|
||||
});
|
||||
|
||||
expect(reply).toEqual({ patched: true });
|
||||
expect(set).toHaveBeenCalledExactlyOnceWith(document.getElementById("b"), { rotation: 45 });
|
||||
});
|
||||
});
|
||||
|
||||
describe("patch-tweens parser", () => {
|
||||
const ok = (change: unknown) =>
|
||||
parsePatchTweens({ patches: [{ selector: "#a", change }], seek: true });
|
||||
|
||||
it("takes every change kind Studio sends, with finite values on known channels", () => {
|
||||
expect(ok({ kind: "set", props: { x: 1, opacity: 0.5 } })).not.toBeNull();
|
||||
expect(ok({ kind: "global-set", props: { width: 120 } })).not.toBeNull();
|
||||
expect(ok({ kind: "keyframes", keyframes: [{ x: 0 }, { x: 10 }] })).not.toBeNull();
|
||||
expect(ok({ kind: "keyframe-rebuild", pct: 50, props: { y: 3 } })).not.toBeNull();
|
||||
});
|
||||
|
||||
it("refuses unknown channels, non-finite values, bad steps and extra fields", () => {
|
||||
for (const change of [
|
||||
{ kind: "set", props: { onUpdate: 1 } },
|
||||
{ kind: "set", props: { x: Number.POSITIVE_INFINITY } },
|
||||
{ kind: "set", props: {} },
|
||||
{ kind: "keyframes", keyframes: [] },
|
||||
{ kind: "keyframes", keyframes: [{ x: "1" }] },
|
||||
{ kind: "keyframe-rebuild", pct: 140, props: { y: 3 } },
|
||||
{ kind: "set", props: { x: 1 }, extra: true },
|
||||
{ kind: "run", props: { x: 1 } },
|
||||
{ kind: "toString", props: { x: 1 } },
|
||||
{ kind: "__proto__", props: { x: 1 } },
|
||||
{ kind: "constructor", props: { x: 1 } },
|
||||
])
|
||||
expect(ok(change)).toBeNull();
|
||||
expect(parsePatchTweens({ patches: [], seek: true })).toBeNull();
|
||||
expect(
|
||||
parsePatchTweens({
|
||||
patches: [{ selector: "", change: { kind: "set", props: { x: 1 } } }],
|
||||
seek: true,
|
||||
}),
|
||||
).toBeNull();
|
||||
const many = Array.from({ length: 65 }, () => ({
|
||||
selector: "#a",
|
||||
change: { kind: "set", props: { x: 1 } },
|
||||
}));
|
||||
expect(parsePatchTweens({ patches: many, seek: true })).toBeNull();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,458 @@
|
||||
// A value-only edit patches its one live GSAP tween in place; anything it cannot place
|
||||
// confidently returns false and the caller reloads. Studio runs it on a frame it can reach,
|
||||
// a sealed frame on itself through the editing port.
|
||||
import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "../../colorGrading";
|
||||
|
||||
export interface SetPatchProps {
|
||||
x?: number;
|
||||
y?: number;
|
||||
rotation?: number;
|
||||
rotationX?: number;
|
||||
rotationY?: number;
|
||||
rotationZ?: number;
|
||||
z?: number;
|
||||
transformPerspective?: number;
|
||||
scaleX?: number;
|
||||
scaleY?: number;
|
||||
scale?: number;
|
||||
opacity?: number;
|
||||
width?: number;
|
||||
height?: number;
|
||||
}
|
||||
|
||||
/** A single keyframe step's numeric channels (the GSAP array-keyframe form). */
|
||||
export type KeyframeStep = Record<string, number>;
|
||||
|
||||
export type RuntimeTweenChange =
|
||||
| { kind: "set"; props: SetPatchProps }
|
||||
| { kind: "keyframes"; keyframes: KeyframeStep[] }
|
||||
// GSAP compiles object-form keyframes into sub-tweens at creation and ignores later
|
||||
// `vars.keyframes` mutations, so one step's edit rebuilds the tween at its position.
|
||||
| { kind: "keyframe-rebuild"; pct: number; props: KeyframeStep }
|
||||
// A base `gsap.set` lives off the timeline: the element is static on these channels.
|
||||
| { kind: "global-set"; props: SetPatchProps };
|
||||
|
||||
const SET_CHANNELS: Array<keyof SetPatchProps> = [
|
||||
"x",
|
||||
"y",
|
||||
"rotation",
|
||||
"rotationX",
|
||||
"rotationY",
|
||||
"rotationZ",
|
||||
"z",
|
||||
"transformPerspective",
|
||||
"scaleX",
|
||||
"scaleY",
|
||||
"scale",
|
||||
"opacity",
|
||||
];
|
||||
const PATCH_CHANNELS = new Set<string>([...SET_CHANNELS, "width", "height"]);
|
||||
|
||||
export interface PatchableTween {
|
||||
targets?: () => Element[];
|
||||
vars?: Record<string, unknown>;
|
||||
duration?: () => number;
|
||||
startTime?: () => number;
|
||||
invalidate?: () => unknown;
|
||||
kill?: () => void;
|
||||
parent?: PatchableTimeline;
|
||||
}
|
||||
|
||||
export interface PatchableTimeline {
|
||||
getChildren?: (deep: boolean) => PatchableTween[];
|
||||
time?: () => number;
|
||||
to?: (targets: Element[], vars: Record<string, unknown>, position?: number) => unknown;
|
||||
}
|
||||
|
||||
export interface PatchTarget {
|
||||
timelines: Record<string, PatchableTimeline> | null | undefined;
|
||||
document: Document | null | undefined;
|
||||
gsap: { set?: (target: Element, vars: Record<string, number>) => void } | null | undefined;
|
||||
player: { getTime?: () => number; seek?: (t: number) => void } | null | undefined;
|
||||
}
|
||||
|
||||
export function matchesElement(tween: PatchableTween, el: Element): boolean {
|
||||
if (!tween.targets) return false;
|
||||
for (const t of tween.targets()) {
|
||||
if (t === el || (el.id && (t as Element).id === el.id)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function varsCarryChannel(vars: Record<string, unknown> | undefined, channels: string[]): boolean {
|
||||
if (!vars) return false;
|
||||
return channels.some((ch) => Object.prototype.hasOwnProperty.call(vars, ch));
|
||||
}
|
||||
|
||||
/** Whether a keyframe tween's steps carry one of `channels`, in the object, array or object-of-arrays form. */
|
||||
export function keyframeVarsCarryChannel(
|
||||
vars: Record<string, unknown> | undefined,
|
||||
channels: string[],
|
||||
): boolean {
|
||||
const kf = vars?.keyframes;
|
||||
if (!kf || typeof kf !== "object") return false;
|
||||
if (!Array.isArray(kf) && channels.some((ch) => Object.prototype.hasOwnProperty.call(kf, ch)))
|
||||
return true;
|
||||
const steps = Array.isArray(kf) ? kf : Object.values(kf);
|
||||
return steps.some(
|
||||
(step) =>
|
||||
step != null &&
|
||||
typeof step === "object" &&
|
||||
channels.some((ch) => Object.prototype.hasOwnProperty.call(step, ch)),
|
||||
);
|
||||
}
|
||||
|
||||
export interface ResolvedTween {
|
||||
tween: PatchableTween;
|
||||
timeline: PatchableTimeline;
|
||||
}
|
||||
|
||||
const tweenDuration = (tween: PatchableTween) =>
|
||||
typeof tween.duration === "function" ? tween.duration() : 0;
|
||||
|
||||
const isKind = (tween: PatchableTween, kind: "keyframe" | "set") =>
|
||||
tweenDuration(tween) > 0 === (kind === "keyframe");
|
||||
|
||||
function playsNow(tween: PatchableTween, timeline: PatchableTimeline): boolean {
|
||||
if (typeof timeline.time !== "function") return false;
|
||||
const now = timeline.time();
|
||||
const start = typeof tween.startTime === "function" ? tween.startTime() : 0;
|
||||
return now >= start - 1e-3 && now <= start + tweenDuration(tween) + 1e-3;
|
||||
}
|
||||
|
||||
const carriesChannels = (
|
||||
vars: Record<string, unknown>,
|
||||
kind: "keyframe" | "set",
|
||||
channels: string[],
|
||||
) => (kind === "set" ? varsCarryChannel(vars, channels) : keyframeVarsCarryChannel(vars, channels));
|
||||
|
||||
type WalkableTimeline = PatchableTimeline & { getChildren: (deep: boolean) => PatchableTween[] };
|
||||
|
||||
function liveTimelines(
|
||||
timelines: Record<string, PatchableTimeline>,
|
||||
compositionId?: string,
|
||||
): WalkableTimeline[] {
|
||||
const ids = compositionId ? [compositionId] : Object.keys(timelines);
|
||||
return ids
|
||||
.map((id) => timelines[id])
|
||||
.filter((tl): tl is WalkableTimeline => typeof tl?.getChildren === "function");
|
||||
}
|
||||
|
||||
type Candidate = {
|
||||
tween: PatchableTween & { vars: Record<string, unknown> };
|
||||
timeline: WalkableTimeline;
|
||||
};
|
||||
|
||||
function candidatesFor(
|
||||
target: PatchTarget,
|
||||
selector: string,
|
||||
kind: "keyframe" | "set",
|
||||
compositionId?: string,
|
||||
): Candidate[] {
|
||||
const targetEl = target.timelines ? target.document?.querySelector(selector) : null;
|
||||
if (!target.timelines || !targetEl) return [];
|
||||
const found: Candidate[] = [];
|
||||
for (const timeline of liveTimelines(target.timelines, compositionId))
|
||||
for (const tween of timeline.getChildren(true))
|
||||
if (tween.vars && matchesElement(tween, targetEl) && isKind(tween, kind))
|
||||
found.push({ tween: tween as Candidate["tween"], timeline });
|
||||
return found;
|
||||
}
|
||||
|
||||
/** The live tween on `selector`; `channels` keeps an {x,y} patch off a co-located rotation-only set. */
|
||||
export function resolveTween(
|
||||
target: PatchTarget,
|
||||
selector: string,
|
||||
kind: "keyframe" | "set",
|
||||
compositionId?: string,
|
||||
channels?: string[],
|
||||
): ResolvedTween | null {
|
||||
const found = candidatesFor(target, selector, kind, compositionId);
|
||||
const preferred =
|
||||
channels && channels.length > 0
|
||||
? found.find(({ tween }) => carriesChannels(tween.vars, kind, channels))
|
||||
: kind === "keyframe"
|
||||
? found.find(({ tween, timeline }) => playsNow(tween, timeline))
|
||||
: undefined;
|
||||
return preferred ?? found[0] ?? null;
|
||||
}
|
||||
|
||||
function finiteNumericProps(props: SetPatchProps): Record<string, number> | null {
|
||||
const numeric: Record<string, number> = {};
|
||||
for (const [k, v] of Object.entries(props)) {
|
||||
if (typeof v !== "number" || !Number.isFinite(v)) return null;
|
||||
numeric[k] = v;
|
||||
}
|
||||
return Object.keys(numeric).length > 0 ? numeric : null;
|
||||
}
|
||||
|
||||
/** The element a base `gsap.set` was applied to, or null when it could not be applied. */
|
||||
export function applyGlobalSet(
|
||||
target: PatchTarget,
|
||||
selector: string,
|
||||
props: SetPatchProps,
|
||||
): Element | null {
|
||||
const el = target.document?.querySelector(selector) ?? null;
|
||||
const numeric = finiteNumericProps(props);
|
||||
if (typeof target.gsap?.set !== "function" || !el || !numeric) return null;
|
||||
target.gsap.set(el, numeric);
|
||||
return el;
|
||||
}
|
||||
|
||||
function keyframesAreStatic(keyframes: KeyframeStep[]): boolean {
|
||||
if (keyframes.length === 0) return false;
|
||||
return keyframes.every(
|
||||
(step) =>
|
||||
!!step &&
|
||||
typeof step === "object" &&
|
||||
Object.values(step).every((v) => typeof v === "number" && Number.isFinite(v)),
|
||||
);
|
||||
}
|
||||
|
||||
function patchSet(tween: PatchableTween, props: SetPatchProps): boolean {
|
||||
const vars = tween.vars;
|
||||
if (!vars || "motionPath" in vars) return false;
|
||||
let touched = false;
|
||||
for (const ch of SET_CHANNELS) {
|
||||
const next = props[ch];
|
||||
if (next === undefined) continue;
|
||||
if (typeof next !== "number" || !Number.isFinite(next)) return false;
|
||||
// A string here is a computed GSAP expression ("+=100"); a number would drop it.
|
||||
if (typeof vars[ch] === "string") return false;
|
||||
vars[ch] = next;
|
||||
touched = true;
|
||||
}
|
||||
return touched;
|
||||
}
|
||||
|
||||
function patchKeyframes(tween: PatchableTween, keyframes: KeyframeStep[]): boolean {
|
||||
const vars = tween.vars;
|
||||
if (!vars || "motionPath" in vars) return false;
|
||||
if (!Array.isArray(vars.keyframes) || !keyframesAreStatic(keyframes)) return false;
|
||||
vars.keyframes = keyframes.map((step) => ({ ...step }));
|
||||
return true;
|
||||
}
|
||||
|
||||
function mergeKeyframeStep(
|
||||
map: Record<string, Record<string, number>>,
|
||||
pct: number,
|
||||
props: KeyframeStep,
|
||||
): Record<string, Record<string, number>> {
|
||||
const next: Record<string, Record<string, number>> = {};
|
||||
for (const [k, step] of Object.entries(map)) next[k] = { ...step };
|
||||
let key: string | null = null;
|
||||
for (const k of Object.keys(next)) {
|
||||
const n = parseFloat(k);
|
||||
if (Number.isFinite(n) && Math.abs(n - pct) < 0.05) {
|
||||
key = k;
|
||||
break;
|
||||
}
|
||||
}
|
||||
key ??= `${pct}%`;
|
||||
next[key] = { ...(next[key] ?? {}), ...props };
|
||||
return next;
|
||||
}
|
||||
|
||||
type ReplaceableTween = PatchableTween & {
|
||||
vars: Record<string, unknown>;
|
||||
startTime: () => number;
|
||||
kill: () => void;
|
||||
parent: PatchableTimeline & { to: NonNullable<PatchableTimeline["to"]> };
|
||||
};
|
||||
|
||||
const replaceable = (tween: PatchableTween): tween is ReplaceableTween =>
|
||||
!!tween.vars &&
|
||||
typeof tween.startTime === "function" &&
|
||||
typeof tween.kill === "function" &&
|
||||
typeof tween.parent?.to === "function";
|
||||
|
||||
function keyframeObject(
|
||||
vars: Record<string, unknown>,
|
||||
): Record<string, Record<string, number>> | null {
|
||||
const kf = vars.keyframes;
|
||||
if ("motionPath" in vars || !kf || typeof kf !== "object" || Array.isArray(kf)) return null;
|
||||
return kf as Record<string, Record<string, number>>;
|
||||
}
|
||||
|
||||
const finiteStep = (props: KeyframeStep) =>
|
||||
Object.values(props).every((v) => typeof v === "number" && Number.isFinite(v));
|
||||
|
||||
function rebuildKeyframeTween(tween: PatchableTween, pct: number, props: KeyframeStep): boolean {
|
||||
if (!replaceable(tween) || !finiteStep(props)) return false;
|
||||
const kf = keyframeObject(tween.vars);
|
||||
const targets = tween.targets?.();
|
||||
if (!kf || !targets || targets.length === 0) return false;
|
||||
const next = mergeKeyframeStep(kf, pct, props);
|
||||
const position = tween.startTime();
|
||||
tween.kill();
|
||||
tween.parent.to(targets, { ...tween.vars, keyframes: next }, position);
|
||||
return true;
|
||||
}
|
||||
|
||||
function changeChannels(change: RuntimeTweenChange): string[] | undefined {
|
||||
if (change.kind === "set")
|
||||
return Object.keys(change.props).filter(
|
||||
(k) => change.props[k as keyof SetPatchProps] !== undefined,
|
||||
);
|
||||
if (change.kind === "keyframe-rebuild") return Object.keys(change.props);
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function changeTouchesOpacity(change: RuntimeTweenChange): boolean {
|
||||
if (change.kind === "set" || change.kind === "global-set")
|
||||
return change.props.opacity !== undefined;
|
||||
if (change.kind === "keyframes") return change.keyframes.some((step) => "opacity" in step);
|
||||
return "opacity" in change.props;
|
||||
}
|
||||
|
||||
/** A re-init captures the current inline opacity, which mid-grade is the engine's 0 hide. */
|
||||
function restoreAuthoredOpacityForCapture(tween: PatchableTween): void {
|
||||
for (const target of tween.targets?.() ?? []) {
|
||||
const el = target as HTMLElement | null;
|
||||
if (!el?.style || typeof el.getAttribute !== "function") continue;
|
||||
const authored = readStampedAuthoredOpacity(el);
|
||||
if (authored !== null) applyAuthoredInlineOpacity(el.style, authored);
|
||||
}
|
||||
}
|
||||
|
||||
function applyChange(tween: PatchableTween, change: RuntimeTweenChange): boolean {
|
||||
if (change.kind === "set") return patchSet(tween, change.props);
|
||||
if (change.kind === "keyframes") return patchKeyframes(tween, change.keyframes);
|
||||
if (change.kind === "keyframe-rebuild")
|
||||
return rebuildKeyframeTween(tween, change.pct, change.props);
|
||||
return false;
|
||||
}
|
||||
|
||||
function seekToCurrent(target: PatchTarget, timeline: PatchableTimeline): void {
|
||||
const player = target.player;
|
||||
const currentTime =
|
||||
typeof player?.getTime === "function"
|
||||
? player.getTime()
|
||||
: typeof timeline.time === "function"
|
||||
? timeline.time()
|
||||
: 0;
|
||||
player?.seek?.(Number.isFinite(currentTime) ? currentTime : 0);
|
||||
}
|
||||
|
||||
/** `deferSeek`: a group commit renders once after its last patch, or queued members repaint stale. */
|
||||
export function patchTween(
|
||||
target: PatchTarget,
|
||||
selector: string,
|
||||
change: Exclude<RuntimeTweenChange, { kind: "global-set" }>,
|
||||
compositionId?: string,
|
||||
deferSeek = false,
|
||||
): boolean {
|
||||
try {
|
||||
const kind = change.kind === "set" ? "set" : "keyframe";
|
||||
const resolved = resolveTween(target, selector, kind, compositionId, changeChannels(change));
|
||||
if (!resolved) return false;
|
||||
const { tween, timeline } = resolved;
|
||||
if (changeTouchesOpacity(change)) restoreAuthoredOpacityForCapture(tween);
|
||||
if (!applyChange(tween, change)) return false;
|
||||
// Only the edited tween: a timeline-wide invalidate re-captures every from() against
|
||||
// the grading engine's opacity-0 hide, and graded elements vanish.
|
||||
if (change.kind !== "keyframe-rebuild") tween.invalidate?.();
|
||||
if (!deferSeek) seekToCurrent(target, timeline);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
const MAX_PATCHES = 64;
|
||||
const MAX_KEYFRAME_STEPS = 64;
|
||||
const MAX_SELECTOR_LENGTH = 2_000;
|
||||
|
||||
/** A base value never renders, so a batch renders on its last tween patch, whatever follows it. */
|
||||
export function lastTweenPatch(patches: ReadonlyArray<{ change: RuntimeTweenChange }>): number {
|
||||
for (let i = patches.length - 1; i >= 0; i--)
|
||||
if (patches[i]!.change.kind !== "global-set") return i;
|
||||
return -1;
|
||||
}
|
||||
|
||||
export type PatchTweensParams = {
|
||||
patches: Array<{ selector: string; change: RuntimeTweenChange }>;
|
||||
seek: boolean;
|
||||
};
|
||||
|
||||
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
||||
Object.prototype.toString.call(value) === "[object Object]";
|
||||
|
||||
function numericChannels(value: unknown): Record<string, number> | null {
|
||||
if (!isRecord(value)) return null;
|
||||
const entries = Object.entries(value);
|
||||
const ok = entries.every(
|
||||
([k, v]) => PATCH_CHANNELS.has(k) && typeof v === "number" && Number.isFinite(v),
|
||||
);
|
||||
return ok && entries.length > 0 ? (value as Record<string, number>) : null;
|
||||
}
|
||||
|
||||
const CHANGE_KEYS: Record<RuntimeTweenChange["kind"], string> = {
|
||||
set: "kind,props",
|
||||
"global-set": "kind,props",
|
||||
"keyframe-rebuild": "kind,pct,props",
|
||||
keyframes: "keyframes,kind",
|
||||
};
|
||||
|
||||
function parseKeyframes(steps: unknown): RuntimeTweenChange | null {
|
||||
if (!Array.isArray(steps) || steps.length === 0 || steps.length > MAX_KEYFRAME_STEPS) return null;
|
||||
const parsed = steps.map(numericChannels);
|
||||
return parsed.every(Boolean) ? { kind: "keyframes", keyframes: parsed as KeyframeStep[] } : null;
|
||||
}
|
||||
|
||||
function parseRebuild(pct: unknown, value: unknown): RuntimeTweenChange | null {
|
||||
const props = numericChannels(value);
|
||||
const okPct = typeof pct === "number" && pct >= 0 && pct <= 100;
|
||||
return props && okPct ? { kind: "keyframe-rebuild", pct, props } : null;
|
||||
}
|
||||
|
||||
function parseChange(value: unknown): RuntimeTweenChange | null {
|
||||
if (!isRecord(value) || typeof value.kind !== "string") return null;
|
||||
const kind = value.kind as RuntimeTweenChange["kind"];
|
||||
// An unknown kind, prototype names included, has no key list here, so it fails this match.
|
||||
if (Object.keys(value).sort().join() !== CHANGE_KEYS[kind]) return null;
|
||||
if (kind === "keyframes") return parseKeyframes(value.keyframes);
|
||||
if (kind === "keyframe-rebuild") return parseRebuild(value.pct, value.props);
|
||||
const props = numericChannels(value.props);
|
||||
return props ? { kind, props } : null;
|
||||
}
|
||||
|
||||
export function parsePatchTweens(params: unknown): PatchTweensParams | null {
|
||||
if (!isRecord(params) || Object.keys(params).sort().join() !== "patches,seek") return null;
|
||||
const { patches, seek } = params;
|
||||
if (typeof seek !== "boolean" || !Array.isArray(patches)) return null;
|
||||
if (patches.length === 0 || patches.length > MAX_PATCHES) return null;
|
||||
const parsed: PatchTweensParams["patches"] = [];
|
||||
for (const patch of patches) {
|
||||
if (!isRecord(patch) || Object.keys(patch).sort().join() !== "change,selector") return null;
|
||||
const { selector } = patch;
|
||||
const change = parseChange(patch.change);
|
||||
const okSelector =
|
||||
typeof selector === "string" && selector.length > 0 && selector.length <= MAX_SELECTOR_LENGTH;
|
||||
if (!okSelector || !change) return null;
|
||||
parsed.push({ selector, change });
|
||||
}
|
||||
return { patches: parsed, seek };
|
||||
}
|
||||
|
||||
/** The frame patching its own timelines: every patch must land, and it renders once at the end. */
|
||||
export function patchTweens({ patches, seek }: PatchTweensParams): { patched: boolean } {
|
||||
const win = window as unknown as {
|
||||
__timelines?: Record<string, PatchableTimeline>;
|
||||
gsap?: PatchTarget["gsap"];
|
||||
__player?: PatchTarget["player"];
|
||||
};
|
||||
const target: PatchTarget = {
|
||||
timelines: win.__timelines,
|
||||
document,
|
||||
gsap: win.gsap,
|
||||
player: win.__player,
|
||||
};
|
||||
const renderAt = lastTweenPatch(patches);
|
||||
const missed = patches.find(({ selector, change }, index) => {
|
||||
if (change.kind === "global-set")
|
||||
return applyGlobalSet(target, selector, change.props) === null;
|
||||
return !patchTween(target, selector, change, undefined, !(seek && index === renderAt));
|
||||
});
|
||||
return { patched: missed === undefined };
|
||||
}
|
||||
@@ -201,6 +201,7 @@ describe("installEditingAgent", () => {
|
||||
"crop-lift",
|
||||
"edit-element",
|
||||
"gsap-set",
|
||||
"patch-tweens",
|
||||
],
|
||||
},
|
||||
});
|
||||
@@ -562,6 +563,36 @@ describe("installEditingAgent", () => {
|
||||
);
|
||||
});
|
||||
|
||||
it("patches a set tween through the port, and refuses a patch with an unknown field", async () => {
|
||||
document.body.innerHTML = `<div id="box"></div>`;
|
||||
const set = {
|
||||
vars: { x: 0 },
|
||||
targets: () => [document.getElementById("box")],
|
||||
duration: () => 0,
|
||||
};
|
||||
Object.assign(window, { __timelines: { main: { getChildren: () => [set], time: () => 0 } } });
|
||||
const port = connectedPort();
|
||||
const patch = { selector: "#box", change: { kind: "set", props: { x: 12 } } };
|
||||
|
||||
const applied = await ask(port, {
|
||||
v: 1,
|
||||
id: 1,
|
||||
kind: "patch-tweens",
|
||||
params: { patches: [patch], seek: true },
|
||||
});
|
||||
const refused = await ask(port, {
|
||||
v: 1,
|
||||
id: 2,
|
||||
kind: "patch-tweens",
|
||||
params: { patches: [{ ...patch, script: "x" }], seek: true },
|
||||
});
|
||||
|
||||
expect(applied).toMatchObject({ id: 1, ok: true, result: { patched: true } });
|
||||
expect(set.vars.x).toBe(12);
|
||||
expect(refused).toMatchObject({ id: 2, ok: false, error: { code: "invalid-params" } });
|
||||
Reflect.deleteProperty(window, "__timelines");
|
||||
});
|
||||
|
||||
it("replies failed when a handler rejects or its result cannot be cloned", async () => {
|
||||
window.__hfWaitForSeekCompletion = () => Promise.reject(new Error("seek lost"));
|
||||
const port = connectedPort();
|
||||
|
||||
@@ -40,6 +40,7 @@ import { gsapSnapshot } from "./editing/gsapSnapshot";
|
||||
import { motionPathHome } from "./editing/motionPathHome";
|
||||
import { cropLift } from "./editing/cropLift";
|
||||
import { gsapSet } from "./editing/gsapSet";
|
||||
import { patchTweens } from "./editing/patchTween";
|
||||
import {
|
||||
getLogicalOpacity,
|
||||
markedForStudio,
|
||||
@@ -222,6 +223,7 @@ const HANDLERS: Handlers = {
|
||||
"crop-lift": cropLift,
|
||||
"edit-element": editElement,
|
||||
"gsap-set": gsapSet,
|
||||
"patch-tweens": patchTweens,
|
||||
};
|
||||
|
||||
function serve(port: MessagePort): void {
|
||||
|
||||
@@ -104,6 +104,7 @@ describe("createEditingPortClient", () => {
|
||||
"crop-lift",
|
||||
"edit-element",
|
||||
"gsap-set",
|
||||
"patch-tweens",
|
||||
],
|
||||
});
|
||||
} finally {
|
||||
|
||||
@@ -29,6 +29,7 @@ import type { EditingGestureStart } from "./editingGestureStart";
|
||||
import type { GsapSnapshot } from "./editing/gsapSnapshot";
|
||||
import type { MotionPathFrameHome } from "./editing/motionPathHome";
|
||||
import { parseGsapSet, type GsapSetParams } from "./editing/gsapSet";
|
||||
import { parsePatchTweens, type PatchTweensParams } from "./editing/patchTween";
|
||||
import type { EditingLayer } from "./editingLayers";
|
||||
import type { RuntimeTimelineMessage } from "./types";
|
||||
import { wallClearTimeout, wallSetTimeout } from "./wallClock";
|
||||
@@ -178,6 +179,7 @@ export const EDITING_REQUEST_KINDS = [
|
||||
"crop-lift",
|
||||
"edit-element",
|
||||
"gsap-set",
|
||||
"patch-tweens",
|
||||
] as const;
|
||||
export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number];
|
||||
|
||||
@@ -313,6 +315,7 @@ export interface EditingRequests {
|
||||
};
|
||||
"edit-element": { params: EditElementParams; result: EditElementResult };
|
||||
"gsap-set": { params: GsapSetParams; result: { applied: boolean } };
|
||||
"patch-tweens": { params: PatchTweensParams; result: { patched: boolean } };
|
||||
}
|
||||
export type EditingParams<K extends EditingRequestKind> = EditingRequests[K]["params"];
|
||||
export type EditingResult<K extends EditingRequestKind> = EditingRequests[K]["result"];
|
||||
@@ -522,6 +525,7 @@ const PARAM_PARSERS: {
|
||||
: null,
|
||||
"edit-element": parseEditElement,
|
||||
"gsap-set": parseGsapSet,
|
||||
"patch-tweens": parsePatchTweens,
|
||||
};
|
||||
|
||||
/** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */
|
||||
|
||||
@@ -14,6 +14,7 @@ import { timeAtProgress } from "../utils/gsapKeyframeEases";
|
||||
import { readMotionPathTween } from "./gsapRuntimeMotionPath";
|
||||
import { roundTo3 } from "../utils/rounding";
|
||||
import { matchesElement, tweensTargeting } from "./gsapRuntimeTweenIndex";
|
||||
import { keyframeVarsCarryChannel } from "@hyperframes/core/runtime/patch-tween";
|
||||
import { withParsedStart } from "./gsapParsedTween";
|
||||
import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
|
||||
import { gsapRendersTransform } from "../components/editor/gsapAnimatesProperty";
|
||||
@@ -98,7 +99,7 @@ function timelinesOf(iframe: HTMLIFrameElement | null): Record<string, RuntimeTi
|
||||
}
|
||||
}
|
||||
|
||||
/** A sealed frame reads from its snapshot; resolveRuntimeTween patches, so it takes live tweens only. */
|
||||
/** A sealed frame reads from its snapshot. */
|
||||
function readableTimelines(iframe: HTMLIFrameElement | null) {
|
||||
return iframe && previewFrameOpaque(iframe) ? frameTimelines(iframe) : timelinesOf(iframe);
|
||||
}
|
||||
@@ -162,129 +163,6 @@ function tweenTiming(tween: RuntimeTween): { start: number; duration: number } {
|
||||
};
|
||||
}
|
||||
|
||||
export interface ResolvedRuntimeTween {
|
||||
/** The live GSAP tween targeting the selector. */
|
||||
tween: RuntimeTween;
|
||||
/** The composition timeline that owns it. */
|
||||
timeline: RuntimeTimeline;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a tween's `vars` carry at least one of `channels` as an OWN property.
|
||||
* Used to disambiguate co-located `set`s: an element can have separate
|
||||
* `tl.set("#el",{x,y})` and `tl.set("#el",{rotation})` tweens, and a position
|
||||
* patch must land on the {x,y} set — never the rotation-only one.
|
||||
*/
|
||||
function varsCarryChannel(vars: Record<string, unknown> | undefined, channels: string[]): boolean {
|
||||
if (!vars) return false;
|
||||
for (const ch of channels) {
|
||||
if (Object.prototype.hasOwnProperty.call(vars, ch)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Like `varsCarryChannel` but for a keyframe tween: the channels live inside the
|
||||
* keyframe steps (`vars.keyframes`), not as own props of `vars`. Handles the object
|
||||
* form (`{ "0%": {...} }`), the array form (`[{...}, ...]`) and the object-of-arrays form.
|
||||
*/
|
||||
function keyframeVarsCarryChannel(
|
||||
vars: Record<string, unknown> | undefined,
|
||||
channels: string[],
|
||||
): boolean {
|
||||
const kf = vars?.keyframes;
|
||||
if (!kf || typeof kf !== "object") return false;
|
||||
if (!Array.isArray(kf) && channels.some((ch) => Object.prototype.hasOwnProperty.call(kf, ch)))
|
||||
return true;
|
||||
const steps = Array.isArray(kf) ? kf : Object.values(kf);
|
||||
return steps.some(
|
||||
(step) =>
|
||||
step != null &&
|
||||
typeof step === "object" &&
|
||||
channels.some((ch) => Object.prototype.hasOwnProperty.call(step, ch)),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the live tween targeting `selector` using the SAME all-timelines scan
|
||||
* `readRuntimeKeyframes` uses, so read and write agree on "which tween". With
|
||||
* `kind: "keyframe"` it skips zero-duration `set`s and prefers the tween whose
|
||||
* range contains the playhead (matching the reader). With `kind: "set"` it picks
|
||||
* the zero-duration `set`/hold instead. Returns null when none matches.
|
||||
*
|
||||
* `channels` disambiguates co-located `set`s (CHANNEL-BLIND otherwise): when
|
||||
* provided with `kind: "set"`, a set carrying ONE of those channels wins, and a
|
||||
* set carrying ONLY disjoint channels is skipped (so patching {x,y} never lands
|
||||
* on a rotation-only set). With no channel-matching set, it falls back to the
|
||||
* first matching set (back-compat). `channels` is ignored for `kind: "keyframe"`.
|
||||
*/
|
||||
// fallow-ignore-next-line complexity
|
||||
export function resolveRuntimeTween(
|
||||
iframe: HTMLIFrameElement | null,
|
||||
selector: string,
|
||||
kind: "keyframe" | "set",
|
||||
compositionId?: string,
|
||||
channels?: string[],
|
||||
// fallow-ignore-next-line code-duplication
|
||||
): ResolvedRuntimeTween | null {
|
||||
const timelines = timelinesOf(iframe);
|
||||
if (!timelines) return null;
|
||||
|
||||
let targetEl: Element | null = null;
|
||||
try {
|
||||
targetEl = iframe?.contentDocument?.querySelector(selector) ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!targetEl) return null;
|
||||
|
||||
const tlIds = compositionId
|
||||
? [compositionId]
|
||||
: Object.keys(timelines).filter((k) => typeof timelines[k]?.getChildren === "function");
|
||||
|
||||
// Channels disambiguate co-located tweens for BOTH kinds: a `set` carries them as
|
||||
// own vars props, a keyframe tween carries them inside its keyframe steps. An
|
||||
// element can have a rotation keyframe tween AND a position keyframe tween; a
|
||||
// rotation edit must land on the former. The reader passes no channels, so its
|
||||
// playhead-containment path below is unchanged.
|
||||
const wantChannels = channels && channels.length > 0 ? channels : null;
|
||||
|
||||
let first: ResolvedRuntimeTween | null = null;
|
||||
// fallow-ignore-next-line code-duplication
|
||||
let channelMatch: ResolvedRuntimeTween | null = null;
|
||||
for (const tlId of tlIds) {
|
||||
const timeline = timelines[tlId];
|
||||
if (!timeline?.getChildren) continue;
|
||||
const now = typeof timeline.time === "function" ? timeline.time() : null;
|
||||
for (const tween of timeline.getChildren(true)) {
|
||||
if (!tween.vars || !matchesElement(tween, targetEl)) continue;
|
||||
const dur = typeof tween.duration === "function" ? tween.duration() : 0;
|
||||
const isSet = !(dur > 0);
|
||||
if (kind === "set" ? !isSet : isSet) continue;
|
||||
if (wantChannels) {
|
||||
const carries =
|
||||
kind === "set"
|
||||
? varsCarryChannel(tween.vars, wantChannels)
|
||||
: keyframeVarsCarryChannel(tween.vars, wantChannels);
|
||||
if (carries) {
|
||||
if (channelMatch === null) channelMatch = { tween, timeline };
|
||||
} else if (first === null) {
|
||||
// A tween carrying only disjoint channels: remember as last-resort
|
||||
// fallback, but never prefer it over a channel-matching one.
|
||||
first = { tween, timeline };
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (first === null) first = { tween, timeline };
|
||||
if (kind === "keyframe" && now != null) {
|
||||
const start = typeof tween.startTime === "function" ? tween.startTime() : 0;
|
||||
if (now >= start - 1e-3 && now <= start + dur + 1e-3) return { tween, timeline };
|
||||
}
|
||||
}
|
||||
}
|
||||
return channelMatch ?? first;
|
||||
}
|
||||
|
||||
/** Whether a read carries at least one of `channels` as a keyframe property. */
|
||||
function readCarriesChannel(read: ReadTween, channels: string[]): boolean {
|
||||
return read.keyframes.some((kf) => channels.some((c) => kf.properties[c] != null));
|
||||
|
||||
@@ -1,288 +1,38 @@
|
||||
/**
|
||||
* Patch ONE tween's values in the preview iframe's runtime timeline in place, so a
|
||||
* value-only manual edit (a `tl.set` position/rotation/scale, or a keyframe
|
||||
* value/position change) is reflected INSTANTLY — without re-running the whole
|
||||
* composition.
|
||||
*
|
||||
* Defensive by default: the caller (`runCommit`) falls back to the existing soft
|
||||
* reload whenever this returns `false`. It returns `false` (never silently
|
||||
* mis-patches) when the tween can't be confidently located or the requested change
|
||||
* can't be safely expressed (dynamic/computed values, motionPath arcs, shape
|
||||
* mismatch), and never throws.
|
||||
*
|
||||
* "Which tween" is resolved by the same all-timelines scan `readRuntimeKeyframes`
|
||||
* uses (`resolveRuntimeTween`), so read and write agree on the target.
|
||||
* Patch ONE tween's values in a reachable preview's runtime timeline in place, so a
|
||||
* value-only manual edit shows instantly. The caller (`runCommit`) soft-reloads
|
||||
* whenever this returns `false`. A sealed preview patches itself through the
|
||||
* editing port instead (`patch-tweens`).
|
||||
*/
|
||||
import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "../utils/authoredOpacity";
|
||||
import {
|
||||
resolveRuntimeTween,
|
||||
type RuntimeTween,
|
||||
type RuntimeTimeline,
|
||||
} from "./gsapRuntimeKeyframes";
|
||||
applyGlobalSet,
|
||||
patchTween,
|
||||
type PatchTarget,
|
||||
type RuntimeTweenChange,
|
||||
} from "@hyperframes/core/runtime/patch-tween";
|
||||
import { recordLiveSet } from "../utils/softReloadTargets";
|
||||
|
||||
/** Value-only channels a `tl.set(...)` patch may touch. */
|
||||
export interface SetPatchProps {
|
||||
x?: number;
|
||||
y?: number;
|
||||
rotation?: number;
|
||||
rotationX?: number;
|
||||
rotationY?: number;
|
||||
rotationZ?: number;
|
||||
z?: number;
|
||||
transformPerspective?: number;
|
||||
scaleX?: number;
|
||||
scaleY?: number;
|
||||
scale?: number;
|
||||
opacity?: number;
|
||||
width?: number;
|
||||
height?: number;
|
||||
}
|
||||
export type { RuntimeTweenChange, SetPatchProps } from "@hyperframes/core/runtime/patch-tween";
|
||||
|
||||
/** A single keyframe step's numeric channels (the GSAP array-keyframe form). */
|
||||
export type KeyframeStep = Record<string, number>;
|
||||
|
||||
export type RuntimeTweenChange =
|
||||
| { kind: "set"; props: SetPatchProps }
|
||||
| { kind: "keyframes"; keyframes: KeyframeStep[] }
|
||||
// Edit ONE step (at `pct`) of an object-form keyframe tween — the form the studio
|
||||
// writes (`keyframes: { "0%": {...} }`). GSAP pre-compiles those into sub-tweens
|
||||
// and won't re-read `vars.keyframes` on `invalidate()`, so this REBUILDS the tween
|
||||
// (kill + recreate at the same position) instead of mutating it. Lets a design-panel
|
||||
// keyframe edit show instantly rather than soft-reloading the iframe (a flash).
|
||||
| { kind: "keyframe-rebuild"; pct: number; props: KeyframeStep }
|
||||
// Apply a base `gsap.set` value to the element directly (`gsap.set(el, props)`).
|
||||
// A base set lives OFF the timeline, so there's no runtime tween to patch — but
|
||||
// the element is static on these channels, so setting them immediately reflects
|
||||
// the edit with no soft reload (no flash) and leaves no keyframe marker.
|
||||
| { kind: "global-set"; props: SetPatchProps };
|
||||
|
||||
const SET_CHANNELS: Array<keyof SetPatchProps> = [
|
||||
"x",
|
||||
"y",
|
||||
"rotation",
|
||||
"rotationX",
|
||||
"rotationY",
|
||||
"rotationZ",
|
||||
"z",
|
||||
"transformPerspective",
|
||||
"scaleX",
|
||||
"scaleY",
|
||||
"scale",
|
||||
"opacity",
|
||||
];
|
||||
|
||||
type IframeWindow = Window & {
|
||||
__player?: { getTime?: () => number; seek?: (t: number) => void };
|
||||
gsap?: { set?: (target: Element, vars: Record<string, number>) => void };
|
||||
};
|
||||
|
||||
/**
|
||||
* Apply a base `gsap.set` value to the element in the live runtime. Returns `true`
|
||||
* if applied. Used for off-timeline static holds (position / 3D transform) — there's
|
||||
* no tween to patch, so we set the channels directly. Safe because the element is
|
||||
* static on these channels (the caller only uses this for non-animated values).
|
||||
*/
|
||||
/** The props as finite numbers, or null if any value is non-finite / none present. */
|
||||
function finiteNumericProps(props: SetPatchProps): Record<string, number> | null {
|
||||
const numeric: Record<string, number> = {};
|
||||
for (const [k, v] of Object.entries(props)) {
|
||||
if (typeof v !== "number" || !Number.isFinite(v)) return null;
|
||||
numeric[k] = v;
|
||||
}
|
||||
return Object.keys(numeric).length > 0 ? numeric : null;
|
||||
}
|
||||
|
||||
function applyGlobalSet(
|
||||
iframe: HTMLIFrameElement,
|
||||
selector: string,
|
||||
props: SetPatchProps,
|
||||
): boolean {
|
||||
try {
|
||||
const gsapLib = (iframe.contentWindow as IframeWindow | null)?.gsap;
|
||||
const el = iframe.contentDocument?.querySelector(selector) ?? null;
|
||||
const numeric = finiteNumericProps(props);
|
||||
if (!gsapLib?.set || !el || !numeric) return false;
|
||||
gsapLib.set(el, numeric);
|
||||
recordLiveSet(el, numeric);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function playerOf(iframe: HTMLIFrameElement): IframeWindow["__player"] | null {
|
||||
try {
|
||||
return (iframe.contentWindow as IframeWindow | null)?.__player ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** Every step value must be a finite number — string/computed values can't round-trip. */
|
||||
function keyframesAreStatic(keyframes: KeyframeStep[]): boolean {
|
||||
if (keyframes.length === 0) return false;
|
||||
for (const step of keyframes) {
|
||||
if (!step || typeof step !== "object") return false;
|
||||
for (const v of Object.values(step)) {
|
||||
if (typeof v !== "number" || !Number.isFinite(v)) return false;
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function patchSet(tween: RuntimeTween, props: SetPatchProps): boolean {
|
||||
const vars = tween.vars;
|
||||
if (!vars) return false;
|
||||
// A `set` carrying a motionPath isn't a plain value set — defer.
|
||||
if ("motionPath" in vars) return false;
|
||||
let touched = false;
|
||||
for (const ch of SET_CHANNELS) {
|
||||
const next = props[ch];
|
||||
if (next === undefined) continue;
|
||||
if (typeof next !== "number" || !Number.isFinite(next)) return false;
|
||||
// A string value here is a dynamic/computed GSAP expression (e.g. "+=100",
|
||||
// "random(...)"). Overwriting it with a plain number would silently drop the
|
||||
// dynamic intent — decline so the caller soft-reloads from the (edited) source.
|
||||
if (typeof vars[ch] === "string") return false;
|
||||
vars[ch] = next;
|
||||
touched = true;
|
||||
}
|
||||
return touched;
|
||||
}
|
||||
|
||||
function patchKeyframes(tween: RuntimeTween, keyframes: KeyframeStep[]): boolean {
|
||||
const vars = tween.vars;
|
||||
if (!vars) return false;
|
||||
// motionPath arc tweens express motion as a path, not channel keyframes — defer.
|
||||
if ("motionPath" in vars) return false;
|
||||
// Only the array-keyframe form is patched in place; the existing tween must
|
||||
// already carry array keyframes (shape match), or this is a structural change.
|
||||
if (!Array.isArray(vars.keyframes)) return false;
|
||||
if (!keyframesAreStatic(keyframes)) return false;
|
||||
vars.keyframes = keyframes.map((step) => ({ ...step }));
|
||||
return true;
|
||||
}
|
||||
|
||||
/** The object-form keyframes map with `props` merged into the step at `pct`. */
|
||||
function mergeKeyframeStep(
|
||||
map: Record<string, Record<string, number>>,
|
||||
pct: number,
|
||||
props: KeyframeStep,
|
||||
): Record<string, Record<string, number>> {
|
||||
const next: Record<string, Record<string, number>> = {};
|
||||
for (const [k, step] of Object.entries(map)) next[k] = { ...step };
|
||||
// Match the existing percentage key numerically ("50%" ≡ pct 50), else add one.
|
||||
let key: string | null = null;
|
||||
for (const k of Object.keys(next)) {
|
||||
const n = parseFloat(k);
|
||||
if (Number.isFinite(n) && Math.abs(n - pct) < 0.05) {
|
||||
key = k;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (key === null) key = `${pct}%`;
|
||||
next[key] = { ...(next[key] ?? {}), ...props };
|
||||
return next;
|
||||
function reachablePreview(iframe: HTMLIFrameElement): PatchTarget {
|
||||
const win = iframe.contentWindow as
|
||||
| (Window & {
|
||||
__timelines?: PatchTarget["timelines"];
|
||||
gsap?: PatchTarget["gsap"];
|
||||
__player?: PatchTarget["player"];
|
||||
})
|
||||
| null;
|
||||
return {
|
||||
timelines: win?.__timelines,
|
||||
document: iframe.contentDocument,
|
||||
gsap: win?.gsap,
|
||||
player: win?.__player,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Rebuild an object-form keyframe tween with `props` merged into the step at `pct`,
|
||||
* in place: kill the old tween and recreate it on the SAME parent timeline at the
|
||||
* SAME position, with all other vars (duration, ease, repeat, …) preserved. This
|
||||
* is the only way to reflect an object-form keyframe edit live — GSAP compiles
|
||||
* those keyframes into sub-tweens at creation and ignores later `vars.keyframes`
|
||||
* mutations. Declines (→ caller soft-reloads) for array-form, motionPath arcs,
|
||||
* non-finite/dynamic values, or a tween whose parent/targets can't be resolved.
|
||||
*/
|
||||
// fallow-ignore-next-line complexity
|
||||
function rebuildKeyframeTween(tween: RuntimeTween, pct: number, props: KeyframeStep): boolean {
|
||||
const vars = tween.vars;
|
||||
if (!vars || "motionPath" in vars) return false;
|
||||
const kf = vars.keyframes;
|
||||
if (!kf || typeof kf !== "object" || Array.isArray(kf)) return false;
|
||||
for (const v of Object.values(props)) {
|
||||
if (typeof v !== "number" || !Number.isFinite(v)) return false;
|
||||
}
|
||||
const parent = tween.parent;
|
||||
const targets = tween.targets?.();
|
||||
if (!parent?.to || !targets || targets.length === 0) return false;
|
||||
if (typeof tween.startTime !== "function" || typeof tween.kill !== "function") return false;
|
||||
|
||||
const next = mergeKeyframeStep(kf as Record<string, Record<string, number>>, pct, props);
|
||||
const newVars = { ...vars, keyframes: next };
|
||||
const position = tween.startTime();
|
||||
tween.kill();
|
||||
parent.to(targets, newVars, position);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** The channels a change writes, for the resolver to disambiguate co-located tweens. */
|
||||
function changeChannels(change: RuntimeTweenChange): string[] | undefined {
|
||||
if (change.kind === "set") {
|
||||
return Object.keys(change.props).filter(
|
||||
(k) => change.props[k as keyof SetPatchProps] !== undefined,
|
||||
);
|
||||
}
|
||||
if (change.kind === "keyframe-rebuild") return Object.keys(change.props);
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/** Re-render the timeline at the current playhead after an in-place edit. */
|
||||
function seekToCurrent(iframe: HTMLIFrameElement, timeline: RuntimeTimeline): void {
|
||||
const player = playerOf(iframe);
|
||||
const currentTime =
|
||||
typeof player?.getTime === "function"
|
||||
? player.getTime()
|
||||
: typeof timeline.time === "function"
|
||||
? timeline.time()
|
||||
: 0;
|
||||
player?.seek?.(Number.isFinite(currentTime) ? currentTime : 0);
|
||||
}
|
||||
|
||||
/** Does this change touch the opacity channel (whose re-init reads inline style)? */
|
||||
function changeTouchesOpacity(change: RuntimeTweenChange): boolean {
|
||||
if (change.kind === "set" || change.kind === "global-set")
|
||||
return change.props.opacity !== undefined;
|
||||
if (change.kind === "keyframes") return change.keyframes.some((step) => "opacity" in step);
|
||||
return "opacity" in change.props;
|
||||
}
|
||||
|
||||
/**
|
||||
* A tween re-initialization (invalidate, or kill+recreate for keyframe-rebuild)
|
||||
* captures opacity from the element's CURRENT inline style — for a mid-flight
|
||||
* tween that's a runtime transient, not the authored value, and the capture makes it permanent.
|
||||
* Restore the runtime's parse-time authored capture (data-hf-authored-opacity)
|
||||
* first; the re-seek after the patch re-renders the animated value anyway.
|
||||
* Duck-typed (no instanceof): the targets live in the preview iframe's realm.
|
||||
*/
|
||||
function restoreAuthoredOpacityForCapture(tween: RuntimeTween): void {
|
||||
const targets = typeof tween.targets === "function" ? tween.targets() : [];
|
||||
for (const target of targets ?? []) {
|
||||
const el = target as HTMLElement | null;
|
||||
if (!el?.style || typeof el.getAttribute !== "function") continue;
|
||||
const authored = readStampedAuthoredOpacity(el);
|
||||
if (authored === null) continue;
|
||||
applyAuthoredInlineOpacity(el.style, authored);
|
||||
}
|
||||
}
|
||||
|
||||
/** Apply `change` to the resolved tween. `true` if applied, `false` to soft-reload.
|
||||
* `global-set` is handled before this (no tween) and never reaches here. */
|
||||
function applyChange(tween: RuntimeTween, change: RuntimeTweenChange): boolean {
|
||||
if (change.kind === "set") return patchSet(tween, change.props);
|
||||
if (change.kind === "keyframes") return patchKeyframes(tween, change.keyframes);
|
||||
if (change.kind === "keyframe-rebuild")
|
||||
return rebuildKeyframeTween(tween, change.pct, change.props);
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Edit one tween in `window.__timelines` in place + re-seek to the current playhead.
|
||||
* Returns `true` on a confident patch, `false` otherwise (caller soft-reloads).
|
||||
*
|
||||
* `deferSeek` skips the re-render, for a caller patching several tweens in a row
|
||||
* that will render once after the last one.
|
||||
* `true` on a confident patch, `false` otherwise. `deferSeek` skips the re-render
|
||||
* for a caller patching several tweens in a row that renders once after the last.
|
||||
*/
|
||||
export function patchRuntimeTweenInPlace(
|
||||
iframe: HTMLIFrameElement | null,
|
||||
@@ -292,41 +42,13 @@ export function patchRuntimeTweenInPlace(
|
||||
deferSeek = false,
|
||||
): boolean {
|
||||
if (!iframe) return false;
|
||||
// A base `gsap.set` has no timeline tween to resolve — apply the value straight
|
||||
// to the element so the edit shows instantly (no soft reload, no flash).
|
||||
if (change.kind === "global-set") return applyGlobalSet(iframe, selector, change.props);
|
||||
try {
|
||||
const resolved = resolveRuntimeTween(
|
||||
iframe,
|
||||
selector,
|
||||
change.kind === "set" ? "set" : "keyframe",
|
||||
compositionId,
|
||||
changeChannels(change),
|
||||
);
|
||||
if (!resolved) return false;
|
||||
const { tween, timeline } = resolved;
|
||||
|
||||
if (changeTouchesOpacity(change)) restoreAuthoredOpacityForCapture(tween);
|
||||
if (!applyChange(tween, change)) return false;
|
||||
|
||||
// A rebuild already recreated the tween; set/keyframes mutate vars in place, so
|
||||
// invalidate to make GSAP re-read them on the next render. Either way, re-seek.
|
||||
// Invalidate ONLY the edited tween — never the whole timeline. A timeline-wide
|
||||
// invalidate re-initializes every from() tween against the CURRENT inline
|
||||
// styles, and the color-grading engine hides its source elements with
|
||||
// `opacity: 0 !important` — so every graded element's from(opacity) re-captures
|
||||
// 0 as its end value and animates 0→0 forever (all graded elements vanish).
|
||||
if (change.kind !== "keyframe-rebuild") {
|
||||
tween.invalidate?.();
|
||||
}
|
||||
// A seek re-renders the WHOLE timeline, not just the tween we patched. Under a
|
||||
// multi-element commit that is a visible jump: the members still queued behind
|
||||
// this one get repainted from their un-patched tweens, back to where they were
|
||||
// before the gesture, and stay there until their own patch lands. Deferring
|
||||
// leaves them showing the gesture's own transform, and the caller's last patch
|
||||
// seeks once for the whole group.
|
||||
if (!deferSeek) seekToCurrent(iframe, timeline);
|
||||
return true;
|
||||
const target = reachablePreview(iframe);
|
||||
if (change.kind !== "global-set")
|
||||
return patchTween(target, selector, change, compositionId, deferSeek);
|
||||
const el = applyGlobalSet(target, selector, change.props);
|
||||
if (el) recordLiveSet(el, { ...change.props });
|
||||
return el !== null;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
|
||||
@@ -1,12 +1,8 @@
|
||||
import type { RuntimeTimeline, RuntimeTween } from "./gsapRuntimeKeyframes";
|
||||
|
||||
export function matchesElement(tween: RuntimeTween, el: Element): boolean {
|
||||
if (!tween.targets) return false;
|
||||
for (const t of tween.targets()) {
|
||||
if (t === el || (el.id && (t as Element).id === el.id)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
import { matchesElement } from "@hyperframes/core/runtime/patch-tween";
|
||||
|
||||
export { matchesElement };
|
||||
|
||||
type TweenIndex = { byElement: Map<unknown, RuntimeTween[]>; byId: Map<string, RuntimeTween[]> };
|
||||
let tweenIndexes: WeakMap<RuntimeTimeline, TweenIndex> | null = null;
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
import type { RuntimeTweenChange } from "./gsapRuntimePatch";
|
||||
import { previewRequest } from "../player/lib/previewChannel";
|
||||
|
||||
const definedChannels = <T extends object>(props: T): T =>
|
||||
Object.fromEntries(Object.entries(props).filter(([, v]) => v !== undefined)) as T;
|
||||
|
||||
function wireChange(change: RuntimeTweenChange): RuntimeTweenChange {
|
||||
switch (change.kind) {
|
||||
case "keyframes":
|
||||
return { ...change, keyframes: change.keyframes.map(definedChannels) };
|
||||
case "keyframe-rebuild":
|
||||
return { ...change, props: definedChannels(change.props) };
|
||||
default:
|
||||
return { ...change, props: definedChannels(change.props) };
|
||||
}
|
||||
}
|
||||
|
||||
const wirePatch = ({ selector, change }: { selector: string; change: RuntimeTweenChange }) => ({
|
||||
selector,
|
||||
change: wireChange(change),
|
||||
});
|
||||
|
||||
const sealedGroupPatched = new WeakMap<HTMLIFrameElement, Promise<boolean>>();
|
||||
|
||||
/** A sealed preview patches its own tweens; a refusal, or no answer, reloads it once after the group's last write. */
|
||||
export function patchSealedPreview(
|
||||
iframe: HTMLIFrameElement,
|
||||
patches: ReadonlyArray<{ selector: string; change: RuntimeTweenChange }>,
|
||||
lastWrite: boolean,
|
||||
reloadPreview: () => void,
|
||||
): void {
|
||||
const request = { patches: patches.map(wirePatch), seek: lastWrite };
|
||||
const patched = previewRequest(iframe, "patch-tweens", request).then((r) => r?.patched === true);
|
||||
const earlier = sealedGroupPatched.get(iframe) ?? Promise.resolve(true);
|
||||
const group = Promise.all([earlier, patched]).then(([a, b]) => a && b);
|
||||
if (!lastWrite) {
|
||||
sealedGroupPatched.set(iframe, group);
|
||||
return;
|
||||
}
|
||||
sealedGroupPatched.delete(iframe);
|
||||
void group.then((all) => {
|
||||
if (!all) reloadPreview();
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
// @vitest-environment happy-dom
|
||||
import { beforeEach, expect, it, vi } from "vitest";
|
||||
|
||||
const { previewRequest, patchRuntimeTweenInPlace } = vi.hoisted(() => ({
|
||||
previewRequest: vi.fn(),
|
||||
patchRuntimeTweenInPlace: vi.fn(),
|
||||
}));
|
||||
vi.mock("../player/lib/previewChannel", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("../player/lib/previewChannel")>()),
|
||||
previewFrameOpaque: () => true,
|
||||
previewRequest,
|
||||
}));
|
||||
vi.mock("./gsapRuntimePatch", () => ({ patchRuntimeTweenInPlace }));
|
||||
|
||||
import { applyPreviewSync } from "./useGsapScriptCommits";
|
||||
|
||||
const iframe = document.createElement("iframe");
|
||||
const result = { ok: true, scriptText: "tl.set('#a',{})" };
|
||||
|
||||
beforeEach(() => {
|
||||
previewRequest.mockReset();
|
||||
patchRuntimeTweenInPlace.mockReset();
|
||||
});
|
||||
|
||||
it("sends a sealed preview's value edits to the frame in one request, without empty channels", () => {
|
||||
previewRequest.mockResolvedValue({ patched: true });
|
||||
|
||||
applyPreviewSync(
|
||||
iframe,
|
||||
result,
|
||||
{
|
||||
label: "drag",
|
||||
softReload: true,
|
||||
instantPatches: [
|
||||
{ selector: "#a", change: { kind: "set", props: { x: 10, y: undefined } } },
|
||||
{ selector: "#b", change: { kind: "global-set", props: { rotation: 45 } } },
|
||||
],
|
||||
},
|
||||
vi.fn(),
|
||||
);
|
||||
|
||||
expect(previewRequest).toHaveBeenCalledExactlyOnceWith(iframe, "patch-tweens", {
|
||||
patches: [
|
||||
{ selector: "#a", change: { kind: "set", props: { x: 10 } } },
|
||||
{ selector: "#b", change: { kind: "global-set", props: { rotation: 45 } } },
|
||||
],
|
||||
seek: true,
|
||||
});
|
||||
const sent = previewRequest.mock.calls[0]?.[2] as {
|
||||
patches: Array<{ change: { props: object } }>;
|
||||
};
|
||||
expect(Object.keys(sent.patches[0]!.change.props)).toEqual(["x"]);
|
||||
expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("keeps the preview when the frame patched every tween, and reloads it when it could not", async () => {
|
||||
const instantPatch = { selector: "#a", change: { kind: "set" as const, props: { x: 10 } } };
|
||||
const kept = vi.fn();
|
||||
previewRequest.mockResolvedValueOnce({ patched: true });
|
||||
applyPreviewSync(iframe, result, { label: "drag", instantPatch }, kept);
|
||||
|
||||
const reloaded = vi.fn();
|
||||
previewRequest.mockResolvedValueOnce({ patched: false });
|
||||
applyPreviewSync(iframe, result, { label: "drag", instantPatch }, reloaded);
|
||||
|
||||
await vi.waitFor(() => expect(reloaded).toHaveBeenCalledOnce());
|
||||
expect(kept).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("reloads a group once, after its last write, when the frame refused an earlier member", async () => {
|
||||
const member = (selector: string) => ({
|
||||
selector,
|
||||
change: { kind: "set" as const, props: { x: 1 } },
|
||||
});
|
||||
const reloadPreview = vi.fn();
|
||||
previewRequest.mockResolvedValueOnce({ patched: false }).mockResolvedValueOnce({ patched: true });
|
||||
|
||||
applyPreviewSync(
|
||||
iframe,
|
||||
result,
|
||||
{ label: "move", deferPreviewSync: true, instantPatch: member("#a") },
|
||||
reloadPreview,
|
||||
);
|
||||
await new Promise((resolve) => setTimeout(resolve, 0));
|
||||
expect(reloadPreview).not.toHaveBeenCalled();
|
||||
|
||||
applyPreviewSync(iframe, result, { label: "move", instantPatch: member("#b") }, reloadPreview);
|
||||
|
||||
await vi.waitFor(() => expect(reloadPreview).toHaveBeenCalledOnce());
|
||||
});
|
||||
|
||||
it("leaves the render to the group's last write", () => {
|
||||
previewRequest.mockResolvedValue({ patched: true });
|
||||
|
||||
applyPreviewSync(
|
||||
iframe,
|
||||
result,
|
||||
{
|
||||
label: "drag",
|
||||
deferPreviewSync: true,
|
||||
instantPatch: { selector: "#a", change: { kind: "set", props: { x: 1 } } },
|
||||
},
|
||||
vi.fn(),
|
||||
);
|
||||
|
||||
expect(previewRequest.mock.calls[0]?.[2]).toMatchObject({ seek: false });
|
||||
});
|
||||
@@ -131,6 +131,29 @@ describe("applyPreviewSync", () => {
|
||||
expect(reloadPreview).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("renders on the last tween patch when the batch ends in a base value, which never renders", () => {
|
||||
patchRuntimeTweenInPlace.mockReturnValue(true);
|
||||
|
||||
applyPreviewSync(
|
||||
FAKE_IFRAME,
|
||||
result(),
|
||||
{
|
||||
label: "Move layers",
|
||||
softReload: true,
|
||||
instantPatches: [
|
||||
{ selector: "#a", change: { kind: "set" as const, props: { x: 1 } } },
|
||||
{ selector: "#b", change: { kind: "global-set" as const, props: { x: 2 } } },
|
||||
],
|
||||
},
|
||||
vi.fn(),
|
||||
);
|
||||
|
||||
expect(patchRuntimeTweenInPlace.mock.calls.map((call) => [call[1], call[4]])).toEqual([
|
||||
["#a", false],
|
||||
["#b", true],
|
||||
]);
|
||||
});
|
||||
|
||||
it("applies both plural and singular patches when a caller supplies both", () => {
|
||||
patchRuntimeTweenInPlace.mockReturnValue(true);
|
||||
|
||||
|
||||
@@ -25,6 +25,9 @@ import {
|
||||
import type { CutoverDeps } from "../utils/sdkCutover";
|
||||
import { updateKeyframeCacheFromParsed } from "./gsapKeyframeCacheHelpers";
|
||||
import { patchRuntimeTweenInPlace } from "./gsapRuntimePatch";
|
||||
import { lastTweenPatch } from "@hyperframes/core/runtime/patch-tween";
|
||||
import { previewFrameOpaque } from "../player/lib/previewChannel";
|
||||
import { patchSealedPreview } from "./sealedTweenPatch";
|
||||
import { createKeyedSerializer } from "./serializeByKey";
|
||||
import {
|
||||
GsapMutationHttpError,
|
||||
@@ -258,25 +261,8 @@ export function applyPreviewSync(
|
||||
const writtenWithoutPatch = patches.length === 0;
|
||||
let needsFallback = options.previewFallbackLatch?.pending === true || writtenWithoutPatch;
|
||||
if (patches.length > 0) {
|
||||
const deferSeek = options.deferPreviewSync === true;
|
||||
const missed = patches.find(
|
||||
(patch, index) =>
|
||||
!patchRuntimeTweenInPlace(
|
||||
iframe,
|
||||
patch.selector,
|
||||
patch.change,
|
||||
undefined,
|
||||
deferSeek || index < patches.length - 1,
|
||||
),
|
||||
);
|
||||
if (missed) {
|
||||
// The instant path couldn't patch in place — record the fallback so we can
|
||||
// track how often the fast path misses before the soft/full reload below.
|
||||
trackStudioEvent("gsap_instant_patch_fallback", { selector: missed.selector });
|
||||
needsFallback = true;
|
||||
}
|
||||
// Patched in place — elements are already correct on screen; no reload needed
|
||||
// unless an earlier deferred batch left one member unpatched.
|
||||
if (!patchInstantly(iframe, patches, options, reloadPreview)) needsFallback = true;
|
||||
// Patched in place: no reload unless an earlier deferred batch left one member unpatched.
|
||||
if (!needsFallback) return;
|
||||
}
|
||||
// Written, but the caller has more writes to make and will render after the last.
|
||||
@@ -306,6 +292,40 @@ export function applyPreviewSync(
|
||||
}
|
||||
}
|
||||
|
||||
/** A sealed preview patches itself (and reloads on its own if it must); a reachable one is patched here. */
|
||||
function patchInstantly(
|
||||
iframe: HTMLIFrameElement | null,
|
||||
patches: NonNullable<CommitMutationOptions["instantPatches"]>,
|
||||
options: CommitMutationOptions,
|
||||
reloadPreview: () => void,
|
||||
): boolean {
|
||||
if (!iframe || !previewFrameOpaque(iframe))
|
||||
return patchReachablePreview(iframe, patches, options.deferPreviewSync === true);
|
||||
patchSealedPreview(iframe, patches, !options.deferPreviewSync, reloadPreview);
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Patches a reachable preview's tweens in place, rendering once; `false` when one could not land. */
|
||||
function patchReachablePreview(
|
||||
iframe: HTMLIFrameElement | null,
|
||||
patches: NonNullable<CommitMutationOptions["instantPatches"]>,
|
||||
deferSeek: boolean,
|
||||
): boolean {
|
||||
const renderAt = lastTweenPatch(patches);
|
||||
const missed = patches.find(
|
||||
(patch, index) =>
|
||||
!patchRuntimeTweenInPlace(
|
||||
iframe,
|
||||
patch.selector,
|
||||
patch.change,
|
||||
undefined,
|
||||
deferSeek || index !== renderAt,
|
||||
),
|
||||
);
|
||||
if (missed) trackStudioEvent("gsap_instant_patch_fallback", { selector: missed.selector });
|
||||
return missed === undefined;
|
||||
}
|
||||
|
||||
function instantPatchesFor(
|
||||
options: CommitMutationOptions,
|
||||
): NonNullable<CommitMutationOptions["instantPatches"]> {
|
||||
|
||||
@@ -1,35 +0,0 @@
|
||||
/**
|
||||
* Authored-opacity contract, studio side. The runtime stamps every graded
|
||||
* element's authored inline opacity at document parse time (see
|
||||
* installAuthoredOpacityCapture in @hyperframes/core); studio code that makes
|
||||
* GSAP re-initialize tweens (soft reload, in-place patches) restores it so
|
||||
* re-captures never bake a runtime transient in as a tween bound.
|
||||
*/
|
||||
import { COLOR_GRADING_AUTHORED_OPACITY_ATTR } from "@hyperframes/core/color-grading";
|
||||
|
||||
interface AttributeReader {
|
||||
getAttribute(name: string): string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The stamped authored inline opacity. Three-state:
|
||||
* "0.98" — the authored value; "" — captured, authored none;
|
||||
* null — never captured (unknown).
|
||||
* Duck-typed so iframe-realm elements (no shared HTMLElement) work.
|
||||
*/
|
||||
export function readStampedAuthoredOpacity(element: AttributeReader): string | null {
|
||||
return element.getAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR);
|
||||
}
|
||||
|
||||
/**
|
||||
* Write an authored inline opacity back: "" removes the property, a value sets
|
||||
* it. Priority-lossy by design: the capture reads `style.opacity` (value only)
|
||||
* and the write sets no priority, so an authored `opacity: X !important`
|
||||
* round-trips as `opacity: X`. The only `!important` opacity in the pipeline
|
||||
* is the color-grading runtime hide — a transient this contract exists to
|
||||
* discard — and authored compositions don't `!important` their opacity.
|
||||
*/
|
||||
export function applyAuthoredInlineOpacity(style: CSSStyleDeclaration, authored: string): void {
|
||||
if (authored === "") style.removeProperty("opacity");
|
||||
else style.setProperty("opacity", authored);
|
||||
}
|
||||
@@ -1,7 +1,10 @@
|
||||
import { parseGsapScript } from "@hyperframes/parsers/gsap-parser";
|
||||
import { GSAP_BASE_URL_META, motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
|
||||
import { findAuthoredElement } from "./authoredSource";
|
||||
import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "./authoredOpacity";
|
||||
import {
|
||||
applyAuthoredInlineOpacity,
|
||||
readStampedAuthoredOpacity,
|
||||
} from "@hyperframes/core/color-grading";
|
||||
import {
|
||||
authoringFile,
|
||||
collectResetTargets,
|
||||
|
||||
@@ -2147,6 +2147,10 @@ export const ALLOWED_DELETIONS = new Map([
|
||||
"packages/engine/src/services/frameCapture-pageNetwork.test.ts",
|
||||
"pinned the removed per-page filter; browserManager.test.ts pins when a render browser goes behind the proxy",
|
||||
],
|
||||
[
|
||||
"packages/studio/src/utils/authoredOpacity.ts",
|
||||
"its two authored-opacity helpers moved into core's colorGrading, which the frame's own tween patch now calls; Studio imports them from there",
|
||||
],
|
||||
]);
|
||||
|
||||
export function parseBase(argv, fallback = "origin/main") {
|
||||
|
||||
Reference in New Issue
Block a user