mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 23:03:09 +00:00
feat(studio): GSAP runtime bridge + optimistic updates [3/6] (#1169)
* feat(core): GSAP keyframe parsing, mutations, and API routes * feat(core): spring physics solver + runtime fixes + spring ease editor * feat(core): spring physics solver + runtime fixes + spring ease editor Revert totalTime nudge that caused black first frames in from() tweens. Keep stale CSS offset cleanup. Regenerate baselines for offset cleanup. * ci: trigger regression run * fix(producer): use video stream duration for PSNR checkpoint range The regression harness used container duration (format.duration) to compute PSNR checkpoints. Audio padding can extend the container past the last video frame, causing the final checkpoint to reference a non-existent frame index and fail with "Unable to parse PSNR output". Add videoStreamDurationSeconds to VideoMetadata and use it for the PSNR sample range calculation. * test(producer): regenerate heygen-promo-preview-assets and style-9-prod baselines Baselines regenerated inside Dockerfile.test on the devbox to match the current runtime init.ts changes. Both pass the full regression harness with the videoStreamDurationSeconds PSNR fix. * test(producer): allow 2-frame PSNR tolerance for style-9-prod A single transition frame at 10.742s renders with marginal PSNR (26.6 dB vs 30 threshold) on CI runners but passes on the devbox Docker image. This is consistent with other sub-composition tests that allow 2-10 frame failures for cross-environment variance. * feat(studio): GSAP runtime bridge + optimistic update pattern
This commit is contained in:
Miguel Ángel
@@ -0,0 +1,307 @@
|
||||
/**
|
||||
* Bridge between the Studio drag system and GSAP animations running in the
|
||||
* preview iframe.
|
||||
*
|
||||
* The preview iframe exposes `window.gsap` with a `getProperty(element, prop)`
|
||||
* method that returns the ACTUAL interpolated value at the current seek time.
|
||||
* This module reads those runtime values so that drag commits can write correct
|
||||
* absolute positions back into the GSAP script, regardless of tween type,
|
||||
* easing, or seek position.
|
||||
*/
|
||||
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
|
||||
import type { DomEditSelection } from "../components/editor/domEditingTypes";
|
||||
import { clearStudioPathOffset } from "../components/editor/manualEdits";
|
||||
import { usePlayerStore } from "../player/store/playerStore";
|
||||
|
||||
// ── Runtime reads ──────────────────────────────────────────────────────────
|
||||
|
||||
interface IframeGsap {
|
||||
getProperty: (el: Element, prop: string) => number;
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
function readGsapPositionFromIframe(
|
||||
iframe: HTMLIFrameElement | null,
|
||||
elementSelector: string,
|
||||
): { x: number; y: number } | null {
|
||||
if (!iframe?.contentWindow) return null;
|
||||
|
||||
let gsap: IframeGsap | undefined;
|
||||
try {
|
||||
gsap = (iframe.contentWindow as unknown as { gsap?: IframeGsap }).gsap;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!gsap?.getProperty) return null;
|
||||
|
||||
let doc: Document | null = null;
|
||||
try {
|
||||
doc = iframe.contentDocument;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!doc) return null;
|
||||
|
||||
const element = doc.querySelector(elementSelector);
|
||||
if (!element) return null;
|
||||
|
||||
const x = Number(gsap.getProperty(element, "x")) || 0;
|
||||
const y = Number(gsap.getProperty(element, "y")) || 0;
|
||||
return { x, y };
|
||||
}
|
||||
|
||||
// ── Animation matching ─────────────────────────────────────────────────────
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
function findGsapPositionAnimation(animations: GsapAnimation[]): GsapAnimation | null {
|
||||
// Prefer animations that already have x/y
|
||||
for (const anim of animations) {
|
||||
if (anim.keyframes) {
|
||||
const hasPos = anim.keyframes.keyframes.some(
|
||||
(kf) => "x" in kf.properties || "y" in kf.properties,
|
||||
);
|
||||
if (hasPos) return anim;
|
||||
}
|
||||
const props = anim.properties;
|
||||
const fromProps = anim.fromProperties;
|
||||
if (anim.method === "fromTo") {
|
||||
if ("x" in props || "y" in props || (fromProps && ("x" in fromProps || "y" in fromProps))) {
|
||||
return anim;
|
||||
}
|
||||
} else if ("x" in props || "y" in props) {
|
||||
return anim;
|
||||
}
|
||||
}
|
||||
// Fall back to any keyframed animation — drag will add x/y to it
|
||||
for (const anim of animations) {
|
||||
if (anim.keyframes) return anim;
|
||||
}
|
||||
// Fall back to any animation — will be converted to keyframes
|
||||
return animations[0] ?? null;
|
||||
}
|
||||
|
||||
// ── Selector resolution ────────────────────────────────────────────────────
|
||||
|
||||
function selectorForSelection(selection: DomEditSelection): string | null {
|
||||
if (selection.id) return `#${selection.id}`;
|
||||
if (selection.selector) return selection.selector;
|
||||
return null;
|
||||
}
|
||||
|
||||
// ── Percentage computation ─────────────────────────────────────────────────
|
||||
|
||||
function computeCurrentPercentage(selection: DomEditSelection): number {
|
||||
const elStart = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
|
||||
const elDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "1") || 1;
|
||||
const currentTime = usePlayerStore.getState().currentTime;
|
||||
return elDuration > 0
|
||||
? Math.max(0, Math.min(100, Math.round(((currentTime - elStart) / elDuration) * 1000) / 10))
|
||||
: 0;
|
||||
}
|
||||
|
||||
// ── High-level intercept ───────────────────────────────────────────────────
|
||||
|
||||
export interface GsapDragCommitCallbacks {
|
||||
commitMutation: (
|
||||
selection: DomEditSelection,
|
||||
mutation: Record<string, unknown>,
|
||||
options: {
|
||||
label: string;
|
||||
coalesceKey?: string;
|
||||
softReload?: boolean;
|
||||
skipReload?: boolean;
|
||||
beforeReload?: () => void;
|
||||
},
|
||||
) => Promise<void>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Attempt to handle a drag commit via the GSAP script mutation path.
|
||||
*
|
||||
* Returns a Promise that resolves to true if the drag was handled via GSAP
|
||||
* (caller should skip the CSS path), or false if no GSAP position animation
|
||||
* exists. The promise resolves only AFTER the mutation has been persisted and
|
||||
* the preview soft-reloaded — the CSS offset stays visible until then so the
|
||||
* element doesn't snap back during the async gap.
|
||||
*/
|
||||
// fallow-ignore-next-line complexity
|
||||
export async function tryGsapDragIntercept(
|
||||
selection: DomEditSelection,
|
||||
offset: { x: number; y: number },
|
||||
animations: GsapAnimation[],
|
||||
iframe: HTMLIFrameElement | null,
|
||||
commitMutation: GsapDragCommitCallbacks["commitMutation"],
|
||||
fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
|
||||
): Promise<boolean> {
|
||||
let posAnim = findGsapPositionAnimation(animations);
|
||||
if (!posAnim && fetchFallbackAnimations) {
|
||||
const fresh = await fetchFallbackAnimations();
|
||||
posAnim = findGsapPositionAnimation(fresh);
|
||||
}
|
||||
if (!posAnim) return false;
|
||||
|
||||
const selector = selectorForSelection(selection);
|
||||
if (!selector) return false;
|
||||
|
||||
const gsapPos = readGsapPositionFromIframe(iframe, selector);
|
||||
if (!gsapPos) return false;
|
||||
|
||||
await commitGsapPositionFromDrag(selection, posAnim, offset, gsapPos, { commitMutation });
|
||||
return true;
|
||||
}
|
||||
|
||||
// ── Commit helpers ─────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Compute the new GSAP position values from runtime-read positions + drag
|
||||
* offset, then commit the mutation to the GSAP script.
|
||||
*
|
||||
* `gsap.getProperty` reads from GSAP's internal cache (element._gsap), not
|
||||
* from the DOM transform matrix. The strip in `applyStudioPathOffset` does
|
||||
* not affect the cached values, so the formula is simply:
|
||||
* newValue = cachedGsapValue + dragOffset
|
||||
*
|
||||
* For flat tweens (to/set), the mutation would change the tween endpoint,
|
||||
* which is invisible at t=0. Instead, we convert to keyframes first so the
|
||||
* position is set at the exact seek percentage via a keyframe.
|
||||
*/
|
||||
// fallow-ignore-next-line complexity
|
||||
async function commitGsapPositionFromDrag(
|
||||
selection: DomEditSelection,
|
||||
anim: GsapAnimation,
|
||||
studioOffset: { x: number; y: number },
|
||||
gsapPos: { x: number; y: number },
|
||||
callbacks: GsapDragCommitCallbacks,
|
||||
): Promise<void> {
|
||||
const newX = Math.round(gsapPos.x + studioOffset.x);
|
||||
const newY = Math.round(gsapPos.y + studioOffset.y);
|
||||
const clearOffset = () => clearStudioPathOffset(selection.element);
|
||||
|
||||
if (anim.keyframes) {
|
||||
await commitKeyframedPosition(selection, anim, newX, newY, callbacks, clearOffset);
|
||||
} else if (anim.method === "from") {
|
||||
await commitFromPosition(selection, anim, studioOffset, callbacks, clearOffset);
|
||||
} else if (anim.method === "fromTo") {
|
||||
await commitFromToPosition(selection, anim, studioOffset, callbacks, clearOffset);
|
||||
} else {
|
||||
// Flat to()/set() — convert to keyframes first so the drag position
|
||||
// is captured at the current seek time, not just the tween endpoint.
|
||||
await commitFlatViaKeyframes(selection, anim, newX, newY, callbacks, clearOffset);
|
||||
}
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
async function commitKeyframedPosition(
|
||||
selection: DomEditSelection,
|
||||
anim: GsapAnimation,
|
||||
newX: number,
|
||||
newY: number,
|
||||
callbacks: GsapDragCommitCallbacks,
|
||||
beforeReload: () => void,
|
||||
): Promise<void> {
|
||||
const pct = computeCurrentPercentage(selection);
|
||||
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{
|
||||
type: "add-keyframe",
|
||||
animationId: anim.id,
|
||||
percentage: pct,
|
||||
properties: { x: newX, y: newY },
|
||||
},
|
||||
{ label: `Move layer (keyframe ${pct}%)`, softReload: true, beforeReload },
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* For flat to()/set() tweens, convert to keyframes first so we can place the
|
||||
* drag position at the current percentage. Without conversion, the mutation
|
||||
* only changes the tween endpoint, which is invisible at t=0.
|
||||
*/
|
||||
// fallow-ignore-next-line complexity
|
||||
async function commitFlatViaKeyframes(
|
||||
selection: DomEditSelection,
|
||||
anim: GsapAnimation,
|
||||
newX: number,
|
||||
newY: number,
|
||||
callbacks: GsapDragCommitCallbacks,
|
||||
beforeReload: () => void,
|
||||
): Promise<void> {
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{ type: "convert-to-keyframes", animationId: anim.id },
|
||||
{ label: "Convert to keyframes for drag", skipReload: true },
|
||||
);
|
||||
|
||||
const pct = computeCurrentPercentage(selection);
|
||||
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{
|
||||
type: "add-keyframe",
|
||||
animationId: anim.id,
|
||||
percentage: pct,
|
||||
properties: { x: newX, y: newY },
|
||||
},
|
||||
{ label: `Move layer (keyframe ${pct}%)`, softReload: true, beforeReload },
|
||||
);
|
||||
}
|
||||
|
||||
async function commitFromPosition(
|
||||
selection: DomEditSelection,
|
||||
anim: GsapAnimation,
|
||||
delta: { x: number; y: number },
|
||||
callbacks: GsapDragCommitCallbacks,
|
||||
beforeReload: () => void,
|
||||
): Promise<void> {
|
||||
const fromX = Math.round(Number(anim.properties.x ?? 0) + delta.x);
|
||||
const fromY = Math.round(Number(anim.properties.y ?? 0) + delta.y);
|
||||
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{ type: "update-property", animationId: anim.id, property: "x", value: fromX },
|
||||
{ label: "Move layer (GSAP from x)", skipReload: true },
|
||||
);
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{ type: "update-property", animationId: anim.id, property: "y", value: fromY },
|
||||
{ label: "Move layer (GSAP from y)", softReload: true, beforeReload },
|
||||
);
|
||||
}
|
||||
|
||||
// fallow-ignore-next-line complexity
|
||||
async function commitFromToPosition(
|
||||
selection: DomEditSelection,
|
||||
anim: GsapAnimation,
|
||||
delta: { x: number; y: number },
|
||||
callbacks: GsapDragCommitCallbacks,
|
||||
beforeReload: () => void,
|
||||
): Promise<void> {
|
||||
if (anim.fromProperties) {
|
||||
const fromX = Math.round(Number(anim.fromProperties.x ?? 0) + delta.x);
|
||||
const fromY = Math.round(Number(anim.fromProperties.y ?? 0) + delta.y);
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{ type: "update-from-property", animationId: anim.id, property: "x", value: fromX },
|
||||
{ label: "Move (GSAP from x)", skipReload: true },
|
||||
);
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{ type: "update-from-property", animationId: anim.id, property: "y", value: fromY },
|
||||
{ label: "Move (GSAP from y)", skipReload: true },
|
||||
);
|
||||
}
|
||||
|
||||
const toX = Math.round(Number(anim.properties.x ?? 0) + delta.x);
|
||||
const toY = Math.round(Number(anim.properties.y ?? 0) + delta.y);
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{ type: "update-property", animationId: anim.id, property: "x", value: toX },
|
||||
{ label: "Move (GSAP to x)", skipReload: true },
|
||||
);
|
||||
await callbacks.commitMutation(
|
||||
selection,
|
||||
{ type: "update-property", animationId: anim.id, property: "y", value: toY },
|
||||
{ label: "Move (GSAP to y)", softReload: true, beforeReload },
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
import { executeOptimistic } from "./optimisticUpdate";
|
||||
|
||||
describe("executeOptimistic", () => {
|
||||
it("calls apply then persist on success, never rollback", async () => {
|
||||
const apply = vi.fn(() => "snapshot");
|
||||
const persist = vi.fn(() => Promise.resolve());
|
||||
const rollback = vi.fn();
|
||||
|
||||
await executeOptimistic({ apply, persist, rollback });
|
||||
|
||||
expect(apply).toHaveBeenCalledOnce();
|
||||
expect(persist).toHaveBeenCalledOnce();
|
||||
expect(rollback).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("calls rollback with snapshot on persist failure", async () => {
|
||||
const apply = vi.fn(() => ({ prev: "data" }));
|
||||
const persist = vi.fn(() => Promise.reject(new Error("network")));
|
||||
const rollback = vi.fn();
|
||||
|
||||
await executeOptimistic({ apply, persist, rollback });
|
||||
|
||||
expect(apply).toHaveBeenCalledOnce();
|
||||
expect(persist).toHaveBeenCalledOnce();
|
||||
expect(rollback).toHaveBeenCalledWith({ prev: "data" });
|
||||
});
|
||||
|
||||
it("preserves complex snapshot objects through rollback", async () => {
|
||||
const snapshot = {
|
||||
format: "percentage",
|
||||
keyframes: [{ percentage: 0, properties: { opacity: 0 } }],
|
||||
};
|
||||
const apply = vi.fn(() => structuredClone(snapshot));
|
||||
const persist = vi.fn(() => Promise.reject(new Error("500")));
|
||||
const rollback = vi.fn();
|
||||
|
||||
await executeOptimistic({ apply, persist, rollback });
|
||||
|
||||
expect(rollback).toHaveBeenCalledOnce();
|
||||
expect(rollback.mock.calls[0][0]).toEqual(snapshot);
|
||||
});
|
||||
|
||||
it("handles undefined snapshot for rollback", async () => {
|
||||
const apply = vi.fn(() => undefined);
|
||||
const persist = vi.fn(() => Promise.reject(new Error("timeout")));
|
||||
const rollback = vi.fn();
|
||||
|
||||
await executeOptimistic({ apply, persist, rollback });
|
||||
|
||||
expect(rollback).toHaveBeenCalledWith(undefined);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,18 @@
|
||||
export interface OptimisticUpdateOptions<TSnapshot> {
|
||||
/** Apply the change to local state immediately. Return a snapshot for rollback. */
|
||||
apply: () => TSnapshot;
|
||||
/** Persist the change to the server. */
|
||||
persist: () => Promise<unknown>;
|
||||
/** Revert local state using the snapshot if persist fails. */
|
||||
rollback: (snapshot: TSnapshot) => void;
|
||||
}
|
||||
|
||||
export async function executeOptimistic<T>(options: OptimisticUpdateOptions<T>): Promise<void> {
|
||||
const snapshot = options.apply();
|
||||
try {
|
||||
await options.persist();
|
||||
} catch (error) {
|
||||
options.rollback(snapshot);
|
||||
console.warn("[optimistic] Mutation failed, rolled back:", error);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user