@hyperframes/studio 0.8.90 → 0.8.91

package/src/hooks/useDomGeometryCommit.ts

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useRef } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
@@ -10,6 +10,11 @@ import { useGsapAwareEditing } from "./useGsapAwareEditing";
 import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
 import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import { useGsapCacheVersion } from "./useGsapTweenCache";
+import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
+import { useDomEditPersist } from "./useDomEditPersist";
+import { useDomEditPositionPatchCommit } from "./useDomEditPositionPatchCommit";
+import { useMountEffect } from "./useMountEffect";
+import { stageElementOffset } from "./elementOffsetStager";
 
 /**
  * Studio's `Player` must show the project, with `beginTimelineSession(projectId)` run before it
@@ -77,6 +82,41 @@ export function useDomGeometryCommit({
     showToast,
     writeProjectFile,
   });
+  const [queue] = useState(createDomEditSaveQueue);
+  useMountEffect(() => () => queue.destroy());
+  const persistDomEditOperations = useDomEditPersist({
+    activeCompPath,
+    previewIframeRef: iframeRef,
+    showToast,
+    queueDomEditSave: queue.enqueue,
+    writeProjectFile,
+    editHistory,
+    projectIdRef,
+    reloadPreview: noop,
+  });
+  const commitPositionPatchToHtml = useDomEditPositionPatchCommit({
+    activeCompPath,
+    persistDomEditOperations,
+    showToast,
+  });
+  // No paused-save banner in a host: each save is a retry, as in useDomStyleCommit.
+  const commitWithFreshQueue = useCallback<typeof commitPositionPatchToHtml>(
+    (...args) => {
+      queue.reset();
+      return commitPositionPatchToHtml(...args);
+    },
+    [commitPositionPatchToHtml, queue],
+  );
+  const stageElementPositionOffset = useCallback(
+    (selection: DomEditSelection, next: { x: number; y: number }, coalesceKey?: string) =>
+      stageElementOffset(
+        { commitPositionPatchToHtml: commitWithFreshQueue, showToast },
+        selection,
+        next,
+        coalesceKey,
+      ),
+    [commitWithFreshQueue, showToast],
+  );
   const makeFetchFallback = useGsapAnimationFetchFallback(projectId);
   const trackGsapInteractionFailure = useGsapInteractionFailureTelemetry(activeCompPath, showToast);
   const {
@@ -94,6 +134,7 @@ export function useDomGeometryCommit({
     bumpGsapCache,
     makeFetchFallback,
     trackGsapInteractionFailure,
+    stageElementPositionOffset,
     handleDomBoxSizeCommit: noDomBoxSizeRoute,
     addGsapAnimation: gsap.addGsapAnimation,
     convertToKeyframes: gsap.convertToKeyframes,

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -143,3 +143,30 @@ describe("useDomGeometryCommits read-only preview", () => {
     unmount();
   });
 });
+
+describe("useDomGeometryCommits element position offset", () => {
+  it("persists left/top on the element and no translate offset", async () => {
+    const element = document.createElement("span");
+    Object.defineProperties(element, {
+      offsetLeft: { get: () => 100 + (Number.parseFloat(element.style.left) || 0) },
+      offsetTop: { get: () => 200 + (Number.parseFloat(element.style.top) || 0) },
+    });
+    document.body.append(element);
+    const selection = { hfId: "w0", selector: ".w", element } as unknown as DomEditSelection;
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
+
+    await commits().stageElementPositionOffset(selection, { x: 40, y: 20 }).save();
+
+    const patches = commitPositionPatchToHtml.mock.calls[0]![1];
+    expect(patches).toEqual([
+      { type: "inline-style", property: "position", value: "relative" },
+      { type: "inline-style", property: "left", value: "40px" },
+      { type: "inline-style", property: "top", value: "20px" },
+    ]);
+    expect(element.style.getPropertyValue("translate")).toBe("");
+    unmount();
+  });
+});

package/src/hooks/useDomGeometryCommits.ts

@@ -14,6 +14,7 @@ import {
   clearStudioBoxSize,
   clearStudioRotation,
 } from "../components/editor/manualEdits";
+import { stageElementOffset } from "./elementOffsetStager";
 import {
   buildPathOffsetPatches,
   buildBoxSizePatches,
@@ -47,7 +48,7 @@ export interface UseDomGeometryCommitsParams {
   commitPositionPatchToHtml: (
     selection: DomEditSelection,
     patches: PatchOperation[],
-    options: { label: string; coalesceKey: string; skipRefresh?: boolean },
+    options: { label: string; coalesceKey: string; coalesceMs?: number; skipRefresh?: boolean },
   ) => Promise<void>;
   readOnlyPreview: boolean;
 }
@@ -58,6 +59,17 @@ export function useDomGeometryCommits({
   commitPositionPatchToHtml,
   readOnlyPreview,
 }: UseDomGeometryCommitsParams) {
+  const stageElementPositionOffset = useCallback(
+    (selection: DomEditSelection, next: { x: number; y: number }, coalesceKey?: string) =>
+      stageElementOffset(
+        { commitPositionPatchToHtml, showToast, readOnlyPreview },
+        selection,
+        next,
+        coalesceKey,
+      ),
+    [commitPositionPatchToHtml, readOnlyPreview, showToast],
+  );
+
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
       if (readOnlyPreview) return Promise.resolve();
@@ -163,6 +175,7 @@ export function useDomGeometryCommits({
   );
 
   return {
+    stageElementPositionOffset,
     handleDomPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -52,6 +52,9 @@ function mountResizeHandler(
   const element = document.createElement("div");
   const selection = { element, id: "clip", selector: "#clip" } as unknown as DomEditSelection;
   const fallback = vi.fn().mockResolvedValue(undefined);
+  const anchorSave = vi.fn().mockResolvedValue(undefined);
+  const anchorRollback = vi.fn();
+  const elementOffset = vi.fn(() => ({ save: anchorSave, rollback: anchorRollback }));
   const commitMutation = vi.fn().mockResolvedValue(undefined);
   let resize:
     | ((
@@ -71,6 +74,7 @@ function mountResizeHandler(
       bumpGsapCache: vi.fn(),
       makeFetchFallback: () => vi.fn().mockResolvedValue(targetAnimations),
       trackGsapInteractionFailure: vi.fn(),
+      stageElementPositionOffset: elementOffset,
       handleDomBoxSizeCommit: fallback,
       addGsapAnimation: vi.fn(),
       convertToKeyframes: vi.fn(),
@@ -80,7 +84,16 @@ function mountResizeHandler(
     return null;
   }
   const root = mountReactHarness(<Harness />);
-  return { selection, fallback, commitMutation, resize: resize!, root };
+  return {
+    selection,
+    fallback,
+    elementOffset,
+    anchorSave,
+    anchorRollback,
+    commitMutation,
+    resize: resize!,
+    root,
+  };
 }
 
 type AwareEditingParams = Parameters<typeof useGsapAwareEditing>[0];
@@ -89,11 +102,16 @@ function mountGroupHandler({
   gsapCommitMutation,
   makeFetchFallback,
   trackGsapInteractionFailure = vi.fn(),
+  stageElementPositionOffset = vi.fn(),
 }: Pick<AwareEditingParams, "gsapCommitMutation" | "makeFetchFallback"> &
-  Partial<Pick<AwareEditingParams, "trackGsapInteractionFailure">>) {
+  Partial<Pick<AwareEditingParams, "trackGsapInteractionFailure" | "stageElementPositionOffset">>) {
   let groupCommit!: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
+  let pathOffsetCommit!: (
+    selection: DomEditSelection,
+    next: { x: number; y: number },
+  ) => Promise<void>;
   function Harness() {
-    groupCommit = useGsapAwareEditing({
+    const editing = useGsapAwareEditing({
       domEditSelection: null,
       selectedGsapAnimations: [],
       gsapCommitMutation,
@@ -102,18 +120,75 @@ function mountGroupHandler({
       bumpGsapCache: vi.fn(),
       makeFetchFallback,
       trackGsapInteractionFailure,
+      stageElementPositionOffset,
       handleDomBoxSizeCommit: vi.fn(),
       addGsapAnimation: vi.fn(),
       convertToKeyframes: vi.fn(),
       setArcPath: vi.fn(),
       updateArcSegment: vi.fn(),
-    }).handleGsapAwareGroupPathOffsetCommit;
+    });
+    groupCommit = editing.handleGsapAwareGroupPathOffsetCommit;
+    pathOffsetCommit = editing.handleGsapAwarePathOffsetCommit;
     return null;
   }
   const root = mountReactHarness(<Harness />);
-  return { groupCommit: (updates: DomEditGroupPathOffsetCommit[]) => groupCommit(updates), root };
+  return {
+    groupCommit: (updates: DomEditGroupPathOffsetCommit[]) => groupCommit(updates),
+    pathOffsetCommit: (selection: DomEditSelection, next: { x: number; y: number }) =>
+      pathOffsetCommit(selection, next),
+    root,
+  };
 }
 
+describe("useGsapAwareEditing shared-tween moves", () => {
+  it("saves a single drag through the element's own offset", async () => {
+    mocks.drag.mockResolvedValue({ status: "element-offset" });
+    const save = vi.fn().mockResolvedValue(undefined);
+    const stageElementPositionOffset = vi.fn(() => ({ save, rollback: vi.fn() }));
+    const commitMutation = vi.fn();
+    const { pathOffsetCommit, root } = mountGroupHandler({
+      gsapCommitMutation: commitMutation,
+      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
+      stageElementPositionOffset,
+    });
+    const word = { element: document.createElement("span"), hfId: "w0", selector: ".w" };
+    await act(() => pathOffsetCommit(word as unknown as DomEditSelection, { x: 40, y: 20 }));
+    expect(stageElementPositionOffset).toHaveBeenCalledWith(word, { x: 40, y: 20 });
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(commitMutation).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  it("saves a group member that shares a tween through its own offset, under the group key", async () => {
+    mocks.drag.mockImplementation(async (selection, _next, _a, _i, commit, _f, options) => {
+      if (selection.hfId === "w0") return { status: "element-offset" };
+      if (!options?.preflightOnly) await commit(selection, { type: "move" }, { label: "Move" });
+      return { status: "persisted" };
+    });
+    const save = vi.fn().mockResolvedValue(undefined);
+    const stageElementPositionOffset = vi.fn(() => ({ save, rollback: vi.fn() }));
+    const { groupCommit, root } = mountGroupHandler({
+      gsapCommitMutation: vi.fn().mockResolvedValue(undefined),
+      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
+      stageElementPositionOffset,
+    });
+    const word = { element: document.createElement("span"), hfId: "w0", selector: ".w" };
+    const box = { element: document.createElement("div"), id: "box", selector: "#box" };
+    await act(() =>
+      groupCommit([
+        { selection: word, next: { x: 40, y: 20 } },
+        { selection: box, next: { x: 40, y: 20 } },
+      ] as unknown as DomEditGroupPathOffsetCommit[]),
+    );
+    expect(stageElementPositionOffset).toHaveBeenCalledWith(
+      word,
+      { x: 40, y: 20 },
+      expect.stringMatching(/^group-drag:\d+$/),
+    );
+    act(() => root.unmount());
+  });
+});
+
 describe("useGsapAwareEditing anchored resize", () => {
   it("uses the explicit target's animations instead of the human selection cache", async () => {
     const humanAnimation = { id: "human", propertyGroup: "scale" } as GsapAnimation;
@@ -161,6 +236,39 @@ describe("useGsapAwareEditing anchored resize", () => {
     act(() => h.root.unmount());
   });
 
+  function resizeWritesSize() {
+    mocks.resize.mockImplementation(async (selection, _next, _a, _i, commit) => {
+      await commit(selection, { type: "size" }, { label: "Resize", softReload: true });
+      return { status: "persisted" };
+    });
+    mocks.drag.mockResolvedValue({ status: "element-offset" });
+  }
+
+  it("saves a shared-tween word's anchor move after its size, under the resize's undo key", async () => {
+    resizeWritesSize();
+    const h = mountResizeHandler([]);
+    await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
+    const key = h.commitMutation.mock.calls[0]![2].coalesceKey;
+    expect(key).toMatch(/^tx:/);
+    expect(h.elementOffset).toHaveBeenCalledWith(h.selection, { x: -50, y: -25 }, key);
+    expect(h.anchorSave.mock.invocationCallOrder[0]).toBeGreaterThan(
+      h.commitMutation.mock.invocationCallOrder[0]!,
+    );
+    act(() => h.root.unmount());
+  });
+
+  it("does not keep the anchor move when the size save fails", async () => {
+    resizeWritesSize();
+    const h = mountResizeHandler([]);
+    h.commitMutation.mockRejectedValueOnce(new Error("size save failed"));
+    await expect(
+      act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 })),
+    ).rejects.toThrow("size save failed");
+    expect(h.anchorSave).not.toHaveBeenCalled();
+    expect(h.anchorRollback).toHaveBeenCalledTimes(1);
+    act(() => h.root.unmount());
+  });
+
   it("settles the live GSAP position before resize persistence reaches its first await", async () => {
     let resolveResize!: (outcome: { status: "persisted" }) => void;
     const pendingResize = new Promise<{ status: "persisted" }>((resolve) => {

package/src/hooks/useGsapAwareEditing.ts

@@ -34,9 +34,15 @@ import { logResize, logResizeSettle } from "../utils/resizeDebug";
 import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
 import { runGestureTransaction } from "./gestureTransaction";
 import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
-import { assertGsapEditPersisted } from "./gsapEditOutcome";
+import { assertGsapEditPersisted, type GsapEditOutcome } from "./gsapEditOutcome";
 import type { GsapAnimationFetchOptions } from "./useGsapAnimationFetchFallback";
 
+/** A move only a shared tween positions is saved on the element itself; a blocked one throws. */
+async function saveMove(outcome: GsapEditOutcome, saveOnElement: () => Promise<void>) {
+  if (outcome.status === "element-offset") return saveOnElement();
+  assertGsapEditPersisted(outcome);
+}
+
 // Distinct coalesceKey per group drag so consecutive group drags don't fold
 // into one another's undo entry (module-local counter, not Date.now()).
 let groupDragCommitCounter = 0;
@@ -71,6 +77,11 @@ export interface UseGsapAwareEditingParams {
     label: string,
   ) => void;
   // DOM fallbacks (from useDomEditCommits)
+  stageElementPositionOffset: (
+    selection: DomEditSelection,
+    next: { x: number; y: number },
+    coalesceKey?: string,
+  ) => { save: () => Promise<void>; rollback: () => void };
   handleDomBoxSizeCommit: (
     selection: DomEditSelection,
     next: { width: number; height: number },
@@ -117,6 +128,7 @@ export function useGsapAwareEditing({
   bumpGsapCache,
   makeFetchFallback,
   trackGsapInteractionFailure,
+  stageElementPositionOffset,
   handleDomBoxSizeCommit,
   addGsapAnimation,
   convertToKeyframes,
@@ -154,7 +166,7 @@ export function useGsapAwareEditing({
             makeFetchFallback(selection),
             modifiers,
           );
-          assertGsapEditPersisted(outcome);
+          await saveMove(outcome, () => stageElementPositionOffset(selection, next).save());
         } catch (error) {
           trackGsapInteractionFailure(error, selection, "drag", "Move animated layer");
           throw error;
@@ -167,6 +179,7 @@ export function useGsapAwareEditing({
       makeFetchFallback,
       trackGsapInteractionFailure,
       getGsapAnimationsForSelection,
+      stageElementPositionOffset,
     ],
   );
 
@@ -222,6 +235,7 @@ export function useGsapAwareEditing({
         return Promise.resolve();
       };
       const preflightAnimations = new Map<DomEditSelection, GsapAnimation[]>();
+      const offsetMembers = new Set<DomEditSelection>();
       // Editability is user-atomic: prove every member can be written before
       // the first source mutation. Network failures after this point retain the
       // existing multi-request semantics, but a blocked member can never leave
@@ -242,6 +256,7 @@ export function useGsapAwareEditing({
             undefined,
             { preflightOnly: true, group: true },
           );
+          if (outcome.status === "element-offset") offsetMembers.add(selection);
           assertGsapEditPersisted(outcome);
         }),
       );
@@ -255,8 +270,15 @@ export function useGsapAwareEditing({
         );
         throw preflightFailure.error;
       }
+      const lastScriptWrite = updates.findLastIndex(
+        ({ selection }) => !offsetMembers.has(selection),
+      );
       for (const [index, { selection, next }] of updates.entries()) {
-        renderOnCommit = index === updates.length - 1;
+        renderOnCommit = index === lastScriptWrite;
+        if (offsetMembers.has(selection)) {
+          await stageElementPositionOffset(selection, next, coalesceKey).save();
+          continue;
+        }
         try {
           const outcome = await tryGsapDragIntercept(
             selection,
@@ -288,7 +310,13 @@ export function useGsapAwareEditing({
         throw error;
       }
     },
-    [gsapCommitMutation, previewIframeRef, makeFetchFallback, trackGsapInteractionFailure],
+    [
+      gsapCommitMutation,
+      previewIframeRef,
+      makeFetchFallback,
+      trackGsapInteractionFailure,
+      stageElementPositionOffset,
+    ],
   );
 
   const handleGsapAwareBoxSizeCommit = useCallback(
@@ -324,6 +352,7 @@ export function useGsapAwareEditing({
         animCount: targetAnimations.length,
         animGroups: targetAnimations.map((a) => `${a.propertyGroup}:${a.method}`),
       });
+      let anchorMove: ReturnType<typeof stageElementPositionOffset> | null = null;
       return runGestureTransaction({
         element: selection.element,
         label: "Resize layer",
@@ -339,7 +368,7 @@ export function useGsapAwareEditing({
           logResize("sync-settle", { gsapPos, offset, newX, newY });
           setElementGsapPosition(selection.element, newX, newY);
         },
-        persist: async (commit) => {
+        persist: async (commit, coalesceKey) => {
           if (gsapCommitMutation) {
             const commitMutation = commit(gsapCommitMutation);
             try {
@@ -375,7 +404,10 @@ export function useGsapAwareEditing({
                   commitMutation,
                   makeFetchFallback(selection),
                 );
-                assertGsapEditPersisted(dragOutcome);
+                // Saved after the size, under its undo key, so the two are one step.
+                await saveMove(dragOutcome, async () => {
+                  anchorMove = stageElementPositionOffset(selection, offset, coalesceKey);
+                });
               }
               logResizeSettle(selection.element, ownsDragOffset ? "gsap-scale" : "gsap-size");
               return;
@@ -392,12 +424,17 @@ export function useGsapAwareEditing({
           logResizeSettle(selection.element, "dom-route");
           await handleDomBoxSizeCommit(selection, next, offset);
         },
-        restore,
+        afterBufferedCommitsSaved: () => anchorMove?.save() ?? Promise.resolve(),
+        restore: () => {
+          anchorMove?.rollback();
+          restore();
+        },
         skipPixelAssert: hasLivePositionTween,
       });
     },
     [
       handleDomBoxSizeCommit,
+      stageElementPositionOffset,
       gsapCommitMutation,
       previewIframeRef,
       makeFetchFallback,

package/src/hooks/useGsapInteractionFailureTelemetry.test.tsx

@@ -12,7 +12,8 @@ const { trackStudioEditBlocked, trackStudioSaveFailure } = vi.hoisted(() => ({
   trackStudioEditBlocked: vi.fn(),
   trackStudioSaveFailure: vi.fn(),
 }));
-vi.mock("../utils/studioSaveDiagnostics", () => ({
+vi.mock("../utils/studioSaveDiagnostics", async (importOriginal) => ({
+  ...(await importOriginal<object>()),
   trackStudioEditBlocked,
   trackStudioSaveFailure,
 }));

package/src/hooks/useGsapInteractionFailureTelemetry.ts

@@ -2,6 +2,12 @@ import { useCallback } from "react";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { trackStudioEditBlocked, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
 import { isGsapEditBlockedError } from "./gsapEditOutcome";
+import { wasAlreadyToasted } from "./domEditPersistFailure";
+
+function failureToast(error: unknown): string | null {
+  if (wasAlreadyToasted(error)) return null;
+  return isGsapEditBlockedError(error) ? error.message : "Failed to save animated edit.";
+}
 
 export function useGsapInteractionFailureTelemetry(
   activeCompPath: string | null,
@@ -22,10 +28,8 @@ export function useGsapInteractionFailureTelemetry(
         targetSelector: selection?.selector,
         targetSourceFile: selection?.sourceFile,
       });
-      showToast(
-        isGsapEditBlockedError(error) ? error.message : "Failed to save animated edit.",
-        "error",
-      );
+      const message = failureToast(error);
+      if (message) showToast(message, "error");
     },
     [activeCompPath, showToast],
   );

package/src/hooks/useRazorSplit.test.ts

@@ -25,7 +25,7 @@ const rootElement: TimelineElement = {
 };
 
 // An expanded sub-comp child: `start` is in MASTER coordinates (offset by the
-// host's master start), `sourceFile` is the sub-comp, and `expandedParentStart`
+// host's master start), `sourceFile` is the sub-comp, and `parentCompositionStart`
 // is that host master start. Its authored time in the file is start - basis.
 const expandedChild: TimelineElement = {
   id: "child-clip",
@@ -35,7 +35,7 @@ const expandedChild: TimelineElement = {
   track: 1,
   domId: "child-clip",
   sourceFile: SUBCOMP_FILE,
-  expandedParentStart: 2,
+  parentCompositionStart: 2,
 };
 
 interface SplitRequest {
@@ -119,13 +119,13 @@ describe("useRazorSplit — sub-comp coordinate rebasing", () => {
     expect(harness.splitRequests).toHaveLength(1);
     const req = harness.splitRequests[0];
     expect(req.path).toBe(SUBCOMP_FILE);
-    expect(req.splitTime).toBe(3); // 5 - expandedParentStart(2), NOT 5
+    expect(req.splitTime).toBe(3); // 5 - parentCompositionStart(2), NOT 5
     expect(req.elementStart).toBe(0); // 2 - 2, NOT the master start 2
     expect(req.elementDuration).toBe(6);
   });
 
   it("leaves a root-level clip's coordinates unchanged", async () => {
-    // Master split time T = 4; no expandedParentStart, so nothing is rebased.
+    // Master split time T = 4; no parentCompositionStart, so nothing is rebased.
     await act(async () => {
       await harness.singleRef.current!(rootElement, 4);
     });
@@ -154,7 +154,7 @@ describe("useRazorSplit — sub-comp coordinate rebasing", () => {
     expect(rootReq.splitTime).toBe(3);
     expect(rootReq.elementStart).toBe(0);
 
-    // Expanded child: rebased by its OWN expandedParentStart, not the root's.
+    // Expanded child: rebased by its OWN parentCompositionStart, not the root's.
     expect(childReq.splitTime).toBe(1); // 3 - 2
     expect(childReq.elementStart).toBe(0); // 2 - 2
   });