Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsxindex 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.tsindex 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.tsindex 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 = selectordiff --git a/packages/studio/src/index.ts b/packages/studio/src/index.tsindex 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,