Skip to content

Write HTML. Render video. Built for agents.

feat(studio): a host can save canvas moves, resizes and rotations with the handles (#4709)

Miguel Ángel001d001c589f
diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
index 2913ed3a2b..f3691152b1 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.tsx
+++ b/packages/studio/src/components/editor/DomEditOverlay.tsx
@@ -81,15 +81,18 @@ export interface DomEditOverlayProps {
selection: DomEditSelection,
next: { x: number; y: number },
modifiers?: { altKey?: boolean },
- ) => Promise<void> | void;
- onGroupPathOffsetCommit: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void;
+ ) => Promise<unknown> | void;
+ onGroupPathOffsetCommit: (updates: DomEditGroupPathOffsetCommit[]) => Promise<unknown> | void;
onBoxSizeCommit: (
selection: DomEditSelection,
next: { width: number; height: number },
offset?: { x: number; y: number },
restore?: () => void,
- ) => Promise<void> | void;
- onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
+ ) => Promise<unknown> | void;
+ onRotationCommit: (
+ selection: DomEditSelection,
+ next: { angle: number },
+ ) => Promise<unknown> | void;
onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
recordingState?: GestureRecordingState;
onToggleRecording?: () => void;
diff --git a/packages/studio/src/components/editor/domEditOverlayGestures.ts b/packages/studio/src/components/editor/domEditOverlayGestures.ts
index adc280fd16..270e38a7c4 100644
--- a/packages/studio/src/components/editor/domEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/domEditOverlayGestures.ts
@@ -247,10 +247,10 @@ export type UseDomEditOverlayGesturesOptions = {
s: DomEditSelection,
n: { x: number; y: number },
m?: { altKey?: boolean },
- ) => Promise<void> | void
+ ) => Promise<unknown> | void
>;
onGroupPathOffsetCommitRef: RefObject<
- (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void
+ (updates: DomEditGroupPathOffsetCommit[]) => Promise<unknown> | void
>;
onBoxSizeCommitRef: RefObject<
(
@@ -258,10 +258,10 @@ export type UseDomEditOverlayGesturesOptions = {
n: { width: number; height: number },
offset?: { x: number; y: number },
restore?: () => void,
- ) => Promise<void> | void
+ ) => Promise<unknown> | void
>;
onRotationCommitRef: RefObject<
- (s: DomEditSelection, n: { angle: number }) => Promise<void> | void
+ (s: DomEditSelection, n: { angle: number }) => Promise<unknown> | void
>;
onCanvasPointerMoveRef: RefObject<
(
diff --git a/packages/studio/src/components/editor/useDomEditNudge.ts b/packages/studio/src/components/editor/useDomEditNudge.ts
index 55d757783e..fa76d816bd 100644
--- a/packages/studio/src/components/editor/useDomEditNudge.ts
+++ b/packages/studio/src/components/editor/useDomEditNudge.ts
@@ -60,10 +60,10 @@ export interface UseDomEditNudgeParams {
s: DomEditSelection,
n: { x: number; y: number },
m?: { altKey?: boolean },
- ) => Promise<void> | void
+ ) => Promise<unknown> | void
>;
onGroupPathOffsetCommitRef: RefObject<
- (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void
+ (updates: DomEditGroupPathOffsetCommit[]) => Promise<unknown> | void
>;
}
diff --git a/packages/studio/src/hooks/useDomGeometryCommit.test.tsx b/packages/studio/src/hooks/useDomGeometryCommit.test.tsx
new file mode 100644
index 0000000000..c966b7075c
--- /dev/null
+++ b/packages/studio/src/hooks/useDomGeometryCommit.test.tsx
@@ -0,0 +1,226 @@
+// @vitest-environment happy-dom
+import { act, createElement, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ useDomGeometryCommit,
+ usePlayerStore,
+ type DomEditOverlayProps,
+ type UseDomGeometryCommitOptions,
+} from "../index";
+import { makeSelection } from "./domSelectionTestHarness";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const SOURCE = '<div id="card">Card</div><div id="other">Other</div>';
+
+/** A warm parse where only another element animates, and a GSAP writer answering `status`. */
+function stubServer(status = 200, parseStatus = 200) {
+ const mutations: unknown[] = [];
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+ const url = String(input instanceof Request ? input.url : input);
+ const json = (body: unknown, code = 200) =>
+ new Response(JSON.stringify(body), {
+ status: code,
+ headers: { "content-type": "application/json" },
+ });
+ if (url.includes("/api/projects/p1/gsap-animations/")) {
+ if (parseStatus !== 200) return json({ error: "down" }, parseStatus);
+ return json({
+ animations: [
+ {
+ id: "other-fade",
+ targetSelector: "#other",
+ method: "to",
+ position: 0,
+ duration: 1,
+ properties: { opacity: 1 },
+ propertyGroup: "opacity",
+ },
+ ],
+ });
+ }
+ if (url.includes("/api/projects/p1/gsap-mutations/")) {
+ mutations.push(JSON.parse(String(init?.body)));
+ if (status !== 200) return json({ error: "refused" }, status);
+ return json({ ok: true, changed: true, before: "BEFORE", after: "AFTER" });
+ }
+ throw new Error(`Unexpected fetch: ${url}`);
+ }),
+ );
+ return mutations;
+}
+
+function renderHost(options: Partial<UseDomGeometryCommitOptions> = {}) {
+ const iframe = document.createElement("iframe");
+ document.body.append(iframe);
+ const doc = iframe.contentDocument;
+ if (!doc) throw new Error("Expected iframe document");
+ doc.body.innerHTML = SOURCE;
+ const element = doc.getElementById("card") as HTMLElement;
+ const recordEdit = vi.fn(async () => {});
+ const writeProjectFile = vi.fn(async () => {});
+ const reloadPreview = vi.fn();
+ const api: { current: ReturnType<typeof useDomGeometryCommit> | null } = { current: null };
+ function Host() {
+ const iframeRef = useRef<HTMLIFrameElement | null>(iframe);
+ api.current = useDomGeometryCommit({
+ projectId: "p1",
+ iframeRef,
+ writeProjectFile,
+ recordEdit,
+ reloadPreview,
+ ...options,
+ });
+ return null;
+ }
+ const root = createRoot(document.createElement("div"));
+ act(() => root.render(createElement(Host)));
+ const hook = () => {
+ if (!api.current) throw new Error("Expected the hook to render");
+ return api.current;
+ };
+ return {
+ element,
+ recordEdit,
+ hook,
+ rerender: () => act(() => root.render(createElement(Host))),
+ unmount: () => act(() => root.unmount()),
+ };
+}
+
+beforeEach(() => {
+ usePlayerStore.setState({ previewBooted: true, timelineProjectId: "p1" });
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ document.body.innerHTML = "";
+});
+
+describe("useDomGeometryCommit, from the package entry", () => {
+ it("plugs into DomEditOverlay and saves a move as one GSAP write and one undo step", async () => {
+ const mutations = stubServer();
+ const { element, recordEdit, hook, unmount } = renderHost();
+ const overlayCommits: Pick<
+ DomEditOverlayProps,
+ "onPathOffsetCommit" | "onGroupPathOffsetCommit" | "onBoxSizeCommit" | "onRotationCommit"
+ > = {
+ onPathOffsetCommit: hook().commitPathOffset,
+ onGroupPathOffsetCommit: hook().commitGroupPathOffset,
+ onBoxSizeCommit: hook().commitBoxSize,
+ onRotationCommit: hook().commitRotation,
+ };
+
+ const outcome = await overlayCommits.onPathOffsetCommit(makeSelection("card", element), {
+ x: 40,
+ y: 20,
+ });
+
+ expect(outcome).toEqual({ ok: true });
+ expect(mutations).toEqual([
+ expect.objectContaining({ type: "add", targetSelector: "#card", method: "set" }),
+ ]);
+ expect(recordEdit).toHaveBeenCalledTimes(1);
+ expect(recordEdit).toHaveBeenCalledWith(
+ expect.objectContaining({ files: { "index.html": { before: "BEFORE", after: "AFTER" } } }),
+ );
+ unmount();
+ });
+
+ it("keeps the same commits across renders, so the overlay's handlers stay put", () => {
+ stubServer();
+ const { hook, rerender, unmount } = renderHost();
+ const first = hook();
+ rerender();
+ expect(hook().commitPathOffset).toBe(first.commitPathOffset);
+ expect(hook().commitRotation).toBe(first.commitRotation);
+ unmount();
+ });
+
+ it("rejects a move the server refuses, so the overlay undoes it", async () => {
+ stubServer(500);
+ const showToast = vi.fn();
+ const { element, recordEdit, hook, unmount } = renderHost({ showToast });
+
+ await expect(
+ hook().commitPathOffset(makeSelection("card", element), { x: 40, y: 20 }),
+ ).rejects.toThrow();
+ expect(recordEdit).not.toHaveBeenCalled();
+ expect(showToast).toHaveBeenCalledWith(expect.any(String), "error");
+ unmount();
+ });
+
+ it("undoes a resize whose animations cannot be read, and saves nothing", async () => {
+ const mutations = stubServer(200, 500);
+ const showToast = vi.fn();
+ const restore = vi.fn();
+ const { element, recordEdit, hook, unmount } = renderHost({ showToast });
+
+ await expect(
+ hook().commitBoxSize(
+ makeSelection("card", element),
+ { width: 300, height: 90 },
+ undefined,
+ restore,
+ ),
+ ).rejects.toThrow();
+ expect(restore).toHaveBeenCalledTimes(1);
+ expect(showToast).toHaveBeenCalledWith(expect.any(String), "error");
+ expect(mutations).toHaveLength(0);
+ expect(recordEdit).not.toHaveBeenCalled();
+ unmount();
+ });
+
+ it.each([
+ ["the player shows another project", { timelineProjectId: "another-project" }],
+ ["the preview has not booted", { previewBooted: false }],
+ ])("refuses at once when %s", async (_state, store) => {
+ const mutations = stubServer();
+ usePlayerStore.setState(store);
+ const restore = vi.fn();
+ const showToast = vi.fn();
+ const { element, hook, unmount } = renderHost({ showToast });
+
+ await expect(
+ hook().commitBoxSize(
+ makeSelection("card", element),
+ { width: 300, height: 90 },
+ undefined,
+ restore,
+ ),
+ ).rejects.toThrow("has not loaded yet");
+ expect(restore).toHaveBeenCalledTimes(1);
+ expect(showToast).toHaveBeenCalledWith(expect.stringContaining("not loaded"), "error");
+ expect(mutations).toHaveLength(0);
+ unmount();
+ });
+
+ it("waits for a move still being saved", async () => {
+ const mutations = stubServer();
+ const { element, recordEdit, hook, unmount } = renderHost();
+
+ const move = hook().commitPathOffset(makeSelection("card", element), { x: 40, y: 20 });
+ await hook().waitForPendingSaves();
+
+ expect(mutations).toHaveLength(1);
+ expect(recordEdit).toHaveBeenCalledTimes(1);
+ await move;
+ unmount();
+ });
+
+ it("rejects without a project and writes nothing", async () => {
+ const mutations = stubServer();
+ const { element, hook, unmount } = renderHost({ projectId: null });
+
+ await expect(
+ hook().commitRotation(makeSelection("card", element), { angle: 15 }),
+ ).rejects.toThrow("No project is open");
+ expect(mutations).toHaveLength(0);
+ unmount();
+ });
+});
diff --git a/packages/studio/src/hooks/useDomGeometryCommit.ts b/packages/studio/src/hooks/useDomGeometryCommit.ts
new file mode 100644
index 0000000000..862a1d47a7
--- /dev/null
+++ b/packages/studio/src/hooks/useDomGeometryCommit.ts
@@ -0,0 +1,147 @@
+import { useCallback, useMemo, useRef } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import { isPreviewBooted } from "../player/store/playerStore";
+import type { DomEditCommitOutcome } from "./domEditCommitRunner";
+import type { UseDomStyleCommitOptions } from "./useDomStyleCommit";
+import { useGsapAnimationFetchFallback } from "./useGsapAnimationFetchFallback";
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
+import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
+import { useGsapScriptCommits } from "./useGsapScriptCommits";
+import { useGsapCacheVersion } from "./useGsapTweenCache";
+
+/**
+ * Studio's `Player` must show the project, with `beginTimelineSession(projectId)` run before it
+ * mounts; drain `waitForPendingSaves` before switching projects.
+ */
+export interface UseDomGeometryCommitOptions extends UseDomStyleCommitOptions {
+ /** Called when a save cannot patch the preview in place; defaults to reloading the iframe. */
+ reloadPreview?: () => void;
+}
+
+export interface DomGeometryCommits {
+ commitPathOffset: (
+ selection: DomEditSelection,
+ next: { x: number; y: number },
+ modifiers?: { altKey?: boolean },
+ ) => Promise<DomEditCommitOutcome>;
+ commitGroupPathOffset: (updates: DomEditGroupPathOffsetCommit[]) => Promise<DomEditCommitOutcome>;
+ commitBoxSize: (
+ selection: DomEditSelection,
+ next: { width: number; height: number },
+ offset?: { x: number; y: number },
+ restore?: () => void,
+ ) => Promise<DomEditCommitOutcome>;
+ commitRotation: (
+ selection: DomEditSelection,
+ next: { angle: number },
+ ) => Promise<DomEditCommitOutcome>;
+ waitForPendingSaves: () => Promise<void>;
+}
+
+const noop = () => {};
+const NO_SELECTED_ANIMATIONS: GsapAnimation[] = [];
+// ponytail: unreachable, the GSAP writer always exists so a resize never takes the DOM route.
+const noDomBoxSizeRoute = () => Promise.reject(new Error("Resize has no DOM route here"));
+
+/**
+ * Saves canvas moves, resizes and rotations through Studio's own GSAP-aware commits, for a host
+ * without the editor. A failed save rejects, so DomEditOverlay undoes the live gesture.
+ */
+export function useDomGeometryCommit({
+ projectId,
+ iframeRef,
+ writeProjectFile,
+ recordEdit,
+ activeCompPath = null,
+ showToast = noop,
+ reloadPreview,
+}: UseDomGeometryCommitOptions): DomGeometryCommits {
+ const projectIdRef = useRef(projectId);
+ projectIdRef.current = projectId;
+ const pending = useRef(new Set<Promise<void>>()).current;
+ const editHistory = useMemo(() => ({ recordEdit }), [recordEdit]);
+ const reload = useCallback(
+ () => (reloadPreview ? reloadPreview() : iframeRef.current?.contentWindow?.location.reload()),
+ [reloadPreview, iframeRef],
+ );
+ const { bump: bumpGsapCache } = useGsapCacheVersion();
+ const gsap = useGsapScriptCommits({
+ projectIdRef,
+ activeCompPath,
+ previewIframeRef: iframeRef,
+ editHistory,
+ reloadPreview: reload,
+ onCacheInvalidate: bumpGsapCache,
+ showToast,
+ writeProjectFile,
+ });
+ const makeFetchFallback = useGsapAnimationFetchFallback(projectId);
+ const trackGsapInteractionFailure = useGsapInteractionFailureTelemetry(activeCompPath, showToast);
+ const {
+ handleGsapAwarePathOffsetCommit,
+ handleGsapAwareGroupPathOffsetCommit,
+ handleGsapAwareBoxSizeCommit,
+ handleGsapAwareRotationCommit,
+ } = useGsapAwareEditing({
+ // The host owns selection, so every gesture reads its element's animations from the server.
+ domEditSelection: null,
+ selectedGsapAnimations: NO_SELECTED_ANIMATIONS,
+ gsapCommitMutation: gsap.commitMutation,
+ previewIframeRef: iframeRef,
+ showToast,
+ bumpGsapCache,
+ makeFetchFallback,
+ trackGsapInteractionFailure,
+ handleDomBoxSizeCommit: noDomBoxSizeRoute,
+ addGsapAnimation: gsap.addGsapAnimation,
+ convertToKeyframes: gsap.convertToKeyframes,
+ setArcPath: gsap.setArcPath,
+ updateArcSegment: gsap.updateArcSegment,
+ });
+ const saved = useCallback(
+ async (commit: () => Promise<void>, restore = noop): Promise<DomEditCommitOutcome> => {
+ const refusal = !projectIdRef.current
+ ? "No project is open"
+ : !isPreviewBooted(projectIdRef.current)
+ ? "The preview for this project has not loaded yet"
+ : null;
+ if (refusal) {
+ restore();
+ showToast(refusal, "error");
+ throw new Error(refusal);
+ }
+ const run = commit();
+ pending.add(run);
+ try {
+ await run;
+ } finally {
+ pending.delete(run);
+ }
+ return { ok: true };
+ },
+ [pending, showToast],
+ );
+ return useMemo(
+ () => ({
+ commitPathOffset: (selection, next, modifiers) =>
+ saved(() => handleGsapAwarePathOffsetCommit(selection, next, modifiers)),
+ commitGroupPathOffset: (updates) =>
+ saved(() => handleGsapAwareGroupPathOffsetCommit(updates)),
+ commitBoxSize: (selection, next, offset, restore) =>
+ saved(() => handleGsapAwareBoxSizeCommit(selection, next, offset, restore), restore),
+ commitRotation: (selection, next) =>
+ saved(() => handleGsapAwareRotationCommit(selection, next)),
+ waitForPendingSaves: () => Promise.allSettled([...pending]).then(noop),
+ }),
+ [
+ saved,
+ pending,
+ handleGsapAwarePathOffsetCommit,
+ handleGsapAwareGroupPathOffsetCommit,
+ handleGsapAwareBoxSizeCommit,
+ handleGsapAwareRotationCommit,
+ ],
+ );
+}
diff --git a/packages/studio/src/hooks/useGsapAwareEditing.ts b/packages/studio/src/hooks/useGsapAwareEditing.ts
index b92889dd0f..0d505a78b9 100644
--- a/packages/studio/src/hooks/useGsapAwareEditing.ts
+++ b/packages/studio/src/hooks/useGsapAwareEditing.ts
@@ -298,10 +298,15 @@ export function useGsapAwareEditing({
offset?: { x: number; y: number },
restore: () => void = () => undefined,
) => {
- const ownedAnimations = getGsapAnimationsForSelection(selection);
- const targetAnimations = Array.isArray(ownedAnimations)
- ? ownedAnimations
- : await ownedAnimations;
+ let targetAnimations: GsapAnimation[];
+ try {
+ const ownedAnimations = getGsapAnimationsForSelection(selection);
+ targetAnimations = Array.isArray(ownedAnimations) ? ownedAnimations : await ownedAnimations;
+ } catch (error) {
+ restore();
+ trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");
+ throw error;
+ }
const scaleRoute = targetAnimations.some((anim) => anim.propertyGroup === "scale");
const selector = selectorFromSelection(selection);
const hasLivePositionTween = selector
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index f7c22c0ebd..aa6e012607 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -167,7 +167,7 @@ export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
export { useClipboard } from "./hooks/useClipboard";
export type { UseClipboardOptions } from "./hooks/useClipboard";
-// DOM editing for a host outside EditorShell; useDomStyleCommit saves styles without the session.
+// DOM editing for a host outside EditorShell; the Commit hooks save without useDomEditSession.
export { useDomEditSession } from "./hooks/useDomEditSession";
export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
@@ -181,6 +181,8 @@ export { useDomStyleCommit } from "./hooks/useDomStyleCommit";
export type { UseDomStyleCommitOptions } from "./hooks/useDomStyleCommit";
export type { DomEditCommitDeclineReason, DomEditCommitOutcome } from "./hooks/domEditCommitRunner";
export { resolveDomEditSelection } from "./components/editor/domEditingLayers";
+export { useDomGeometryCommit } from "./hooks/useDomGeometryCommit";
+export type { DomGeometryCommits, UseDomGeometryCommitOptions } from "./hooks/useDomGeometryCommit";
export { DomEditOverlay } from "./components/editor/DomEditOverlay";
export type {
DomEditGroupPathOffsetCommit,