diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json index 6b3077e9ca..0213ad312a 100644 --- a/packages/core/package-subpaths.json +++ b/packages/core/package-subpaths.json @@ -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", diff --git a/packages/core/package.json b/packages/core/package.json index 4961066258..c902150aef 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -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" diff --git a/packages/core/src/colorGrading.ts b/packages/core/src/colorGrading.ts index cd53746841..d3a08bc3bc 100644 --- a/packages/core/src/colorGrading.ts +++ b/packages/core/src/colorGrading.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; diff --git a/packages/core/src/runtime/editing/patchTween.test.ts b/packages/core/src/runtime/editing/patchTween.test.ts new file mode 100644 index 0000000000..d19a89539e --- /dev/null +++ b/packages/core/src/runtime/editing/patchTween.test.ts @@ -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>) { + document.body.innerHTML = `
`; + 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(); + }); +}); diff --git a/packages/core/src/runtime/editing/patchTween.ts b/packages/core/src/runtime/editing/patchTween.ts new file mode 100644 index 0000000000..bfec4f0263 --- /dev/null +++ b/packages/core/src/runtime/editing/patchTween.ts @@ -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; + +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 = [ + "x", + "y", + "rotation", + "rotationX", + "rotationY", + "rotationZ", + "z", + "transformPerspective", + "scaleX", + "scaleY", + "scale", + "opacity", +]; +const PATCH_CHANNELS = new Set([...SET_CHANNELS, "width", "height"]); + +export interface PatchableTween { + targets?: () => Element[]; + vars?: Record; + duration?: () => number; + startTime?: () => number; + invalidate?: () => unknown; + kill?: () => void; + parent?: PatchableTimeline; +} + +export interface PatchableTimeline { + getChildren?: (deep: boolean) => PatchableTween[]; + time?: () => number; + to?: (targets: Element[], vars: Record, position?: number) => unknown; +} + +export interface PatchTarget { + timelines: Record | null | undefined; + document: Document | null | undefined; + gsap: { set?: (target: Element, vars: Record) => 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 | 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 | 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, + kind: "keyframe" | "set", + channels: string[], +) => (kind === "set" ? varsCarryChannel(vars, channels) : keyframeVarsCarryChannel(vars, channels)); + +type WalkableTimeline = PatchableTimeline & { getChildren: (deep: boolean) => PatchableTween[] }; + +function liveTimelines( + timelines: Record, + 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 }; + 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 | null { + const numeric: Record = {}; + 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>, + pct: number, + props: KeyframeStep, +): Record> { + const next: Record> = {}; + 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; + startTime: () => number; + kill: () => void; + parent: PatchableTimeline & { to: NonNullable }; +}; + +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, +): Record> | null { + const kf = vars.keyframes; + if ("motionPath" in vars || !kf || typeof kf !== "object" || Array.isArray(kf)) return null; + return kf as Record>; +} + +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, + 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 => + Object.prototype.toString.call(value) === "[object Object]"; + +function numericChannels(value: unknown): Record | 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) : null; +} + +const CHANGE_KEYS: Record = { + 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; + 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 }; +} diff --git a/packages/core/src/runtime/editingAgent.test.ts b/packages/core/src/runtime/editingAgent.test.ts index 3158eb8cf3..cbe8f89358 100644 --- a/packages/core/src/runtime/editingAgent.test.ts +++ b/packages/core/src/runtime/editingAgent.test.ts @@ -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 = `
`; + 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(); diff --git a/packages/core/src/runtime/editingAgent.ts b/packages/core/src/runtime/editingAgent.ts index 07a8e47916..2dd0135009 100644 --- a/packages/core/src/runtime/editingAgent.ts +++ b/packages/core/src/runtime/editingAgent.ts @@ -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 { diff --git a/packages/core/src/runtime/editingPort.test.ts b/packages/core/src/runtime/editingPort.test.ts index b23f51f946..c4fd50b17c 100644 --- a/packages/core/src/runtime/editingPort.test.ts +++ b/packages/core/src/runtime/editingPort.test.ts @@ -104,6 +104,7 @@ describe("createEditingPortClient", () => { "crop-lift", "edit-element", "gsap-set", + "patch-tweens", ], }); } finally { diff --git a/packages/core/src/runtime/editingPort.ts b/packages/core/src/runtime/editingPort.ts index 058972dd2b..4fadd4c62a 100644 --- a/packages/core/src/runtime/editingPort.ts +++ b/packages/core/src/runtime/editingPort.ts @@ -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 = EditingRequests[K]["params"]; export type EditingResult = 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. */ diff --git a/packages/studio/src/hooks/gsapRuntimeKeyframes.ts b/packages/studio/src/hooks/gsapRuntimeKeyframes.ts index 2dedbe7ac0..514b1f0c4e 100644 --- a/packages/studio/src/hooks/gsapRuntimeKeyframes.ts +++ b/packages/studio/src/hooks/gsapRuntimeKeyframes.ts @@ -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 | 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 | 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)); diff --git a/packages/studio/src/hooks/gsapRuntimePatch.ts b/packages/studio/src/hooks/gsapRuntimePatch.ts index 454b29fcaf..ceef342aee 100644 --- a/packages/studio/src/hooks/gsapRuntimePatch.ts +++ b/packages/studio/src/hooks/gsapRuntimePatch.ts @@ -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; - -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 = [ - "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) => 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 | null { - const numeric: Record = {}; - 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>, - pct: number, - props: KeyframeStep, -): Record> { - const next: Record> = {}; - 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>, 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; } diff --git a/packages/studio/src/hooks/gsapRuntimeTweenIndex.ts b/packages/studio/src/hooks/gsapRuntimeTweenIndex.ts index 12aeae2e71..136600b45b 100644 --- a/packages/studio/src/hooks/gsapRuntimeTweenIndex.ts +++ b/packages/studio/src/hooks/gsapRuntimeTweenIndex.ts @@ -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; byId: Map }; let tweenIndexes: WeakMap | null = null; diff --git a/packages/studio/src/hooks/sealedTweenPatch.ts b/packages/studio/src/hooks/sealedTweenPatch.ts new file mode 100644 index 0000000000..a813240cac --- /dev/null +++ b/packages/studio/src/hooks/sealedTweenPatch.ts @@ -0,0 +1,44 @@ +import type { RuntimeTweenChange } from "./gsapRuntimePatch"; +import { previewRequest } from "../player/lib/previewChannel"; + +const definedChannels = (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>(); + +/** 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(); + }); +} diff --git a/packages/studio/src/hooks/useGsapScriptCommits.sealed.test.ts b/packages/studio/src/hooks/useGsapScriptCommits.sealed.test.ts new file mode 100644 index 0000000000..eabc8f1dcd --- /dev/null +++ b/packages/studio/src/hooks/useGsapScriptCommits.sealed.test.ts @@ -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()), + 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 }); +}); diff --git a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx index dac765effb..4b0cc0124a 100644 --- a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx +++ b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx @@ -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); diff --git a/packages/studio/src/hooks/useGsapScriptCommits.ts b/packages/studio/src/hooks/useGsapScriptCommits.ts index 34de9fd468..2204747757 100644 --- a/packages/studio/src/hooks/useGsapScriptCommits.ts +++ b/packages/studio/src/hooks/useGsapScriptCommits.ts @@ -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, + 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, + 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 { diff --git a/packages/studio/src/utils/authoredOpacity.ts b/packages/studio/src/utils/authoredOpacity.ts deleted file mode 100644 index 53b3ede308..0000000000 --- a/packages/studio/src/utils/authoredOpacity.ts +++ /dev/null @@ -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); -} diff --git a/packages/studio/src/utils/gsapSoftReload.ts b/packages/studio/src/utils/gsapSoftReload.ts index 5049b47170..af7f715808 100644 --- a/packages/studio/src/utils/gsapSoftReload.ts +++ b/packages/studio/src/utils/gsapSoftReload.ts @@ -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, diff --git a/scripts/check-no-main-deletions.mjs b/scripts/check-no-main-deletions.mjs index 3039b109d7..8d2c391ae1 100644 --- a/scripts/check-no-main-deletions.mjs +++ b/scripts/check-no-main-deletions.mjs @@ -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") {