@hyperframes/studio 0.7.55 → 0.7.57

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -0,0 +1,239 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import { mountReactHarness } from "./domSelectionTestHarness";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({
+  resize: vi.fn(),
+  drag: vi.fn(),
+  readPosition: vi.fn(),
+  setPosition: vi.fn(),
+}));
+
+vi.mock("./gsapResizeIntercept", () => ({ tryGsapResizeIntercept: mocks.resize }));
+vi.mock("./gsapRuntimeBridge", () => ({
+  POSITION_CHANNELS: ["x", "y"],
+  tryGsapDragIntercept: mocks.drag,
+  tryGsapRotationIntercept: vi.fn(),
+}));
+vi.mock("./gsapPositionDetection", () => ({
+  readGsapPositionFromIframe: mocks.readPosition,
+}));
+vi.mock("../utils/elementGsap", () => ({ setElementGsapPosition: mocks.setPosition }));
+vi.mock("./useAnimatedPropertyCommit", () => ({
+  useAnimatedPropertyCommit: () => ({
+    commitAnimatedProperty: vi.fn(),
+    commitAnimatedProperties: vi.fn(),
+  }),
+}));
+vi.mock("./useSafeGsapCommitMutation", () => ({
+  useGsapSaveFailureTelemetry: () => vi.fn(),
+  useSafeGsapCommitMutation: (commit: unknown) => commit,
+}));
+
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+function mountResizeHandler(animations: GsapAnimation[]) {
+  const element = document.createElement("div");
+  const selection = { element, id: "clip", selector: "#clip" } as unknown as DomEditSelection;
+  const fallback = vi.fn().mockResolvedValue(undefined);
+  const commitMutation = vi.fn().mockResolvedValue(undefined);
+  let resize:
+    | ((
+        selection: DomEditSelection,
+        size: { width: number; height: number },
+        offset?: { x: number; y: number },
+        restore?: () => void,
+      ) => Promise<void>)
+    | null = null;
+  function Harness() {
+    resize = useGsapAwareEditing({
+      domEditSelection: selection,
+      selectedGsapAnimations: animations,
+      gsapCommitMutation: commitMutation,
+      previewIframeRef: { current: null },
+      showToast: vi.fn(),
+      bumpGsapCache: vi.fn(),
+      makeFetchFallback: () => vi.fn().mockResolvedValue(animations),
+      trackGsapInteractionFailure: vi.fn(),
+      handleDomBoxSizeCommit: fallback,
+      addGsapAnimation: vi.fn(),
+      convertToKeyframes: vi.fn(),
+      setArcPath: vi.fn(),
+      updateArcSegment: vi.fn(),
+    }).handleGsapAwareBoxSizeCommit;
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  return { selection, fallback, commitMutation, resize: resize!, root };
+}
+
+describe("useGsapAwareEditing anchored resize", () => {
+  it("forwards the anchor offset to the DOM fallback when GSAP does not handle resize", async () => {
+    mocks.resize.mockResolvedValue(false);
+    const h = mountResizeHandler([]);
+    await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
+    expect(h.fallback).toHaveBeenCalledWith(
+      h.selection,
+      { width: 300, height: 200 },
+      { x: -50, y: -25 },
+    );
+    act(() => h.root.unmount());
+  });
+
+  it("persists the anchor exactly once through GSAP position when size route handles resize", async () => {
+    mocks.resize.mockResolvedValue(true);
+    mocks.drag.mockResolvedValue(true);
+    const h = mountResizeHandler([]);
+    await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
+    expect(h.fallback).not.toHaveBeenCalled();
+    expect(mocks.drag).toHaveBeenCalledTimes(1);
+    expect(mocks.drag.mock.calls[0]![1]).toEqual({ x: -50, y: -25 });
+    act(() => h.root.unmount());
+  });
+
+  it("settles the live GSAP position before resize persistence reaches its first await", async () => {
+    let resolveResize!: (handled: boolean) => void;
+    const pendingResize = new Promise<boolean>((resolve) => {
+      resolveResize = resolve;
+    });
+    mocks.resize.mockReturnValue(pendingResize);
+    mocks.drag.mockResolvedValue(true);
+    mocks.readPosition.mockReturnValue({ x: 120.4, y: 80.2 });
+    const h = mountResizeHandler([]);
+    h.selection.element.setAttribute("data-hf-drag-gsap-base-x", "120.4");
+    h.selection.element.setAttribute("data-hf-drag-gsap-base-y", "80.2");
+    h.selection.element.setAttribute("data-hf-drag-initial-offset-x", "0");
+    h.selection.element.setAttribute("data-hf-drag-initial-offset-y", "0");
+
+    let commit!: Promise<void>;
+    act(() => {
+      commit = h.resize(h.selection, { width: 300, height: 200 }, { x: -50.2, y: -25.6 });
+    });
+
+    expect(mocks.setPosition).toHaveBeenCalledWith(h.selection.element, 70, 55);
+    expect(mocks.setPosition.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.resize.mock.invocationCallOrder[0]!,
+    );
+
+    resolveResize(true);
+    await act(() => commit);
+    act(() => h.root.unmount());
+  });
+
+  it("passes a transaction-scoped commit wrapper into the resize path", async () => {
+    mocks.resize.mockImplementation(async (selection, _size, _animations, _iframe, commit) => {
+      await commit(selection, { type: "resize" }, { label: "Resize", softReload: true });
+      return true;
+    });
+    const h = mountResizeHandler([]);
+
+    await act(() => h.resize(h.selection, { width: 300, height: 200 }));
+
+    expect(h.commitMutation).toHaveBeenCalledWith(
+      h.selection,
+      { type: "resize" },
+      expect.objectContaining({
+        coalesceKey: expect.stringMatching(/^tx:Resize layer:\d+$/),
+        softReload: true,
+      }),
+    );
+    act(() => h.root.unmount());
+  });
+
+  it("folds a group drag's member writes into one undo entry via a shared coalesceKey", async () => {
+    const capturedKeys: Array<string | undefined> = [];
+    mocks.drag.mockImplementation(
+      async (
+        selection: DomEditSelection,
+        _next: unknown,
+        _anims: unknown,
+        _iframe: unknown,
+        commit: (
+          s: DomEditSelection,
+          m: unknown,
+          o: { coalesceKey?: string; label?: string; softReload?: boolean },
+        ) => Promise<void>,
+      ) => {
+        await commit(selection, { type: "move" }, { label: "Move", softReload: true });
+        return true;
+      },
+    );
+    const commitMutation = vi.fn(
+      (_s: DomEditSelection, _m: unknown, o: { coalesceKey?: string }) => {
+        capturedKeys.push(o.coalesceKey);
+        return Promise.resolve();
+      },
+    );
+    let groupCommit!: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
+    function Harness() {
+      groupCommit = useGsapAwareEditing({
+        domEditSelection: null,
+        selectedGsapAnimations: [],
+        gsapCommitMutation: commitMutation,
+        previewIframeRef: { current: null },
+        showToast: vi.fn(),
+        bumpGsapCache: vi.fn(),
+        makeFetchFallback: () => vi.fn().mockResolvedValue([]),
+        trackGsapInteractionFailure: vi.fn(),
+        handleDomBoxSizeCommit: vi.fn(),
+        addGsapAnimation: vi.fn(),
+        convertToKeyframes: vi.fn(),
+        setArcPath: vi.fn(),
+        updateArcSegment: vi.fn(),
+      }).handleGsapAwareGroupPathOffsetCommit;
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+    const updates = [
+      {
+        selection: { element: document.createElement("div"), id: "a", selector: "#a" },
+        next: { x: 10, y: 10 },
+      },
+      {
+        selection: { element: document.createElement("div"), id: "b", selector: "#b" },
+        next: { x: 10, y: 10 },
+      },
+    ] as unknown as DomEditGroupPathOffsetCommit[];
+
+    await act(() => groupCommit(updates));
+
+    expect(capturedKeys).toHaveLength(2);
+    expect(capturedKeys[0]).toMatch(/^group-drag:\d+$/);
+    // Both members share ONE coalesceKey → they fold into a single undo entry.
+    expect(capturedKeys[0]).toBe(capturedKeys[1]);
+    act(() => root.unmount());
+  });
+
+  it("restores once when resize persistence fails", async () => {
+    const error = new Error("resize failed");
+    const restore = vi.fn();
+    mocks.resize.mockRejectedValue(error);
+    const h = mountResizeHandler([]);
+
+    const commit = h.resize(h.selection, { width: 300, height: 200 }, undefined, restore);
+    await expect(commit).rejects.toBe(error);
+    expect(restore).toHaveBeenCalledTimes(1);
+    act(() => h.root.unmount());
+  });
+
+  it("does not apply the anchor twice when scale route already settles the drop point", async () => {
+    mocks.resize.mockResolvedValue(true);
+    const scale = { propertyGroup: "scale" } as GsapAnimation;
+    const h = mountResizeHandler([scale]);
+    await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
+    expect(mocks.drag).not.toHaveBeenCalled();
+    expect(h.fallback).not.toHaveBeenCalled();
+    act(() => h.root.unmount());
+  });
+});

package/src/hooks/useGsapAwareEditing.ts

@@ -10,15 +10,30 @@
 import { useCallback } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-import { tryGsapDragIntercept, tryGsapRotationIntercept } from "./gsapRuntimeBridge";
+import {
+  POSITION_CHANNELS,
+  tryGsapDragIntercept,
+  tryGsapRotationIntercept,
+} from "./gsapRuntimeBridge";
 import { tryGsapResizeIntercept } from "./gsapResizeIntercept";
+import { computeDraggedGsapPosition } from "./draggedGsapPosition";
+import { readGsapPositionFromIframe } from "./gsapPositionDetection";
+import { selectorFromSelection } from "./gsapShared";
 import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
 import {
   useGsapSaveFailureTelemetry,
   useSafeGsapCommitMutation,
 } from "./useSafeGsapCommitMutation";
 import type { CommitMutation } from "./gsapScriptCommitTypes";
+import { setElementGsapPosition } from "../utils/elementGsap";
+import { logResize, logResizeSettle } from "../utils/resizeDebug";
 import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import { runGestureTransaction } from "./gestureTransaction";
+import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
+
+// 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;
 
 export interface UseGsapAwareEditingParams {
   domEditSelection: DomEditSelection | null;
@@ -38,6 +53,7 @@ export interface UseGsapAwareEditingParams {
   handleDomBoxSizeCommit: (
     selection: DomEditSelection,
     next: { width: number; height: number },
+    offset?: { x: number; y: number },
   ) => Promise<void>;
   // GSAP script commit ops (from useGsapScriptCommits)
   addGsapAnimation: (
@@ -127,7 +143,18 @@ export function useGsapAwareEditing({
   // composition there's nothing to write (a no-op, exactly like the single-drag path).
   const handleGsapAwareGroupPathOffsetCommit = useCallback(
     async (updates: DomEditGroupPathOffsetCommit[]) => {
-      if (!gsapCommitMutation) return;
+      if (!gsapCommitMutation || updates.length === 0) return;
+      // A group drag is ONE user action: fold every member's position write into
+      // a single undo entry by forcing a shared coalesceKey (infinite window, so
+      // it survives the N sequential server round-trips) onto each commit —
+      // otherwise each member records its own entry and it takes N presses to undo.
+      const coalesceKey = `group-drag:${++groupDragCommitCounter}`;
+      const coalescedCommit: typeof gsapCommitMutation = (selection, mutation, options) =>
+        gsapCommitMutation(selection, mutation, {
+          ...options,
+          coalesceKey,
+          coalesceMs: Number.POSITIVE_INFINITY,
+        });
       for (const { selection, next } of updates) {
         try {
           await tryGsapDragIntercept(
@@ -135,7 +162,7 @@ export function useGsapAwareEditing({
             next,
             [],
             previewIframeRef.current,
-            gsapCommitMutation,
+            coalescedCommit,
             makeFetchFallback(selection),
           );
         } catch (error) {
@@ -148,24 +175,92 @@ export function useGsapAwareEditing({
   );
 
   const handleGsapAwareBoxSizeCommit = useCallback(
-    async (selection: DomEditSelection, next: { width: number; height: number }) => {
-      if (gsapCommitMutation) {
-        try {
-          const handled = await tryGsapResizeIntercept(
-            selection,
-            next,
-            selectedGsapAnimations,
+    async (
+      selection: DomEditSelection,
+      next: { width: number; height: number },
+      offset?: { x: number; y: number },
+      restore: () => void = () => undefined,
+    ) => {
+      const scaleRoute = selectedGsapAnimations.some((anim) => anim.propertyGroup === "scale");
+      const selector = selectorFromSelection(selection);
+      const hasLivePositionTween = selector
+        ? hasNonHoldTweenForElement(
             previewIframeRef.current,
-            gsapCommitMutation,
-            makeFetchFallback(selection),
-          );
-          if (handled) return;
-        } catch (error) {
-          trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");
-          throw error;
-        }
-      }
-      return handleDomBoxSizeCommit(selection, next);
+            selector,
+            undefined,
+            POSITION_CHANNELS,
+          )
+        : false;
+      logResize("commit-route", {
+        next,
+        offset: offset ?? null,
+        scaleRoute,
+        animCount: selectedGsapAnimations.length,
+        animGroups: selectedGsapAnimations.map((a) => `${a.propertyGroup}:${a.method}`),
+      });
+      return runGestureTransaction({
+        element: selection.element,
+        label: "Resize layer",
+        settle: () => {
+          // Scale resize settles its center-scale residual after the scale commit
+          // renders. Width/height can settle its anchored position immediately.
+          if (!offset || scaleRoute || !selector) return;
+          const gsapPos = readGsapPositionFromIframe(previewIframeRef.current, selector) ?? {
+            x: 0,
+            y: 0,
+          };
+          const { newX, newY } = computeDraggedGsapPosition(selection.element, offset, gsapPos);
+          logResize("sync-settle", { gsapPos, offset, newX, newY });
+          setElementGsapPosition(selection.element, newX, newY);
+        },
+        persist: async (commit) => {
+          if (gsapCommitMutation) {
+            const commitMutation = commit(gsapCommitMutation);
+            try {
+              const handled = await tryGsapResizeIntercept(
+                selection,
+                next,
+                selectedGsapAnimations,
+                previewIframeRef.current,
+                commitMutation,
+                makeFetchFallback(selection),
+              );
+              if (handled) {
+                logResize("intercept-handled", {
+                  scaleRoute,
+                  willForwardOffset: !!(offset && !scaleRoute),
+                });
+                // Scale-route resize persists its residual position internally.
+                // Width/height persists the already-settled anchor through drag.
+                if (offset && !scaleRoute) {
+                  await tryGsapDragIntercept(
+                    selection,
+                    offset,
+                    selectedGsapAnimations,
+                    previewIframeRef.current,
+                    commitMutation,
+                    makeFetchFallback(selection),
+                  );
+                }
+                logResizeSettle(selection.element, scaleRoute ? "gsap-scale" : "gsap-size");
+                return;
+              }
+            } catch (error) {
+              trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");
+              throw error;
+            }
+          }
+          logResize("dom-route", {
+            next,
+            offset: offset ?? null,
+            hadGsapMutation: !!gsapCommitMutation,
+          });
+          logResizeSettle(selection.element, "dom-route");
+          await handleDomBoxSizeCommit(selection, next, offset);
+        },
+        restore,
+        skipPixelAssert: hasLivePositionTween,
+      });
     },
     [
       handleDomBoxSizeCommit,

package/src/hooks/useGsapKeyframeOps.test.tsx

@@ -99,3 +99,62 @@ describe("useGsapKeyframeOps — resizeKeyframedTween", () => {
     expect(labelArg).toBe("Retime keyframe (resize tween)");
   });
 });
+
+describe("useGsapKeyframeOps — keyframe transaction options", () => {
+  it("soft-reloads a standalone convert when the SDK path is unavailable", async () => {
+    const commitMutation = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => ({
+      ok: true,
+    }));
+    const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure: vi.fn() });
+
+    await act(async () => {
+      await api.convertToKeyframes(selection, "box-to-0-opacity");
+    });
+
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      expect.objectContaining({
+        type: "convert-to-keyframes",
+        animationId: "box-to-0-opacity",
+      }),
+      { label: "Convert to keyframes", softReload: true },
+    );
+  });
+
+  it("threads one coalesce key through skipped convert reload and terminal batch edit", async () => {
+    const commitMutation = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => ({
+      ok: true,
+    }));
+    const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure: vi.fn() });
+    const coalesceKey = "enable-keyframes:box-to-0-opacity:1";
+
+    await act(async () => {
+      await api.convertToKeyframes(selection, "box-to-0-opacity", undefined, undefined, {
+        skipReload: true,
+        coalesceKey,
+        coalesceMs: Infinity,
+      });
+      await api.addKeyframeBatch(
+        selection,
+        "box-to-0-opacity",
+        50,
+        { opacity: 0.5 },
+        {
+          coalesceKey,
+        },
+      );
+    });
+
+    expect(commitMutation.mock.calls[0]?.[2]).toEqual({
+      label: "Convert to keyframes",
+      skipReload: true,
+      coalesceKey,
+      coalesceMs: Infinity,
+    });
+    expect(commitMutation.mock.calls[1]?.[2]).toEqual({
+      label: "Add keyframe at 50%",
+      softReload: true,
+      coalesceKey,
+    });
+  });
+});

package/src/hooks/useGsapKeyframeOps.ts

@@ -19,6 +19,7 @@ import {
 } from "./gsapKeyframeCacheHelpers";
 import type {
   CommitMutation,
+  CommitMutationOptions,
   SafeGsapCommitMutation,
   TrackGsapSaveFailure,
 } from "./gsapScriptCommitTypes";
@@ -54,6 +55,21 @@ interface GsapKeyframeOpsParams extends SdkKeyframeDeps {
   trackGsapSaveFailure: TrackGsapSaveFailure;
 }
 
+/**
+ * Translate a gesture's commit overrides into the SDK persist options. The
+ * server path's `softReload`/`skipReload` maps to the SDK's `skipRefresh`, and
+ * `coalesceKey`/`coalesceMs` must ride along so an SDK-routed edit folds into
+ * one undo entry the same way the server path does.
+ */
+function toSdkPersistOptions(label: string, overrides?: Partial<CommitMutationOptions>) {
+  return {
+    label,
+    coalesceKey: overrides?.coalesceKey,
+    coalesceMs: overrides?.coalesceMs,
+    skipRefresh: overrides?.skipReload,
+  };
+}
+
 export function useGsapKeyframeOps({
   activeCompPath,
   commitMutation,
@@ -140,6 +156,7 @@ export function useGsapKeyframeOps({
       animationId: string,
       percentage: number,
       properties: Record<string, number | string>,
+      commitOverrides?: Partial<CommitMutationOptions>,
     ) => {
       if (sdkSession && sdkDeps) {
         const sourceFile = selection.sourceFile || activeCompPath || "index.html";
@@ -150,21 +167,30 @@ export function useGsapKeyframeOps({
           properties,
           sdkSession,
           sdkDeps,
-          { label: `Add keyframe at ${percentage}%` },
+          toSdkPersistOptions(`Add keyframe at ${percentage}%`, commitOverrides),
         );
         if (handled) return;
       }
       return commitMutation(
         selection,
         { type: "add-keyframe", animationId, percentage, properties },
-        { label: `Add keyframe at ${percentage}%`, softReload: true },
+        {
+          label: `Add keyframe at ${percentage}%`,
+          softReload: true,
+          ...commitOverrides,
+        },
       );
     },
     [commitMutation, activeCompPath, sdkSession, sdkDeps],
   );
 
   const removeKeyframe = useCallback(
-    (selection: DomEditSelection, animationId: string, percentage: number) => {
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      percentage: number,
+      commitOverrides?: Partial<CommitMutationOptions>,
+    ) => {
       const sourceFile = selection.sourceFile || activeCompPath || "index.html";
       const mutation = { type: "remove-keyframe", animationId, percentage };
       void executeOptimisticKeyframeCacheUpdate({
@@ -182,6 +208,7 @@ export function useGsapKeyframeOps({
           ),
         }),
         persist: async () => {
+          const label = `Remove keyframe at ${percentage}%`;
           if (sdkSession && sdkDeps) {
             const handled = await sdkGsapRemoveKeyframePersist(
               sourceFile,
@@ -189,14 +216,14 @@ export function useGsapKeyframeOps({
               percentage,
               sdkSession,
               sdkDeps,
-              { label: `Remove keyframe at ${percentage}%` },
+              toSdkPersistOptions(label, commitOverrides),
             );
             if (handled) return;
           }
-          await commitMutation(selection, mutation, {
-            label: `Remove keyframe at ${percentage}%`,
-            softReload: true,
-          });
+          const commitOptions = commitOverrides?.skipReload
+            ? { label, ...commitOverrides }
+            : { label, softReload: true, ...commitOverrides };
+          await commitMutation(selection, mutation, commitOptions);
         },
       }).catch((error) => {
         trackGsapSaveFailure(error, selection, mutation, `Remove keyframe at ${percentage}%`);
@@ -261,6 +288,7 @@ export function useGsapKeyframeOps({
       animationId: string,
       resolvedFromValues?: Record<string, number | string>,
       duration?: number,
+      commitOverrides: Partial<CommitMutationOptions> = { softReload: true },
     ) => {
       if (sdkSession && sdkDeps) {
         const targetPath = selection.sourceFile || activeCompPath || "index.html";
@@ -270,7 +298,7 @@ export function useGsapKeyframeOps({
           resolvedFromValues,
           sdkSession,
           sdkDeps,
-          { label: "Convert to keyframes" },
+          toSdkPersistOptions("Convert to keyframes", commitOverrides),
         );
         if (handled) return;
       }
@@ -279,7 +307,7 @@ export function useGsapKeyframeOps({
         // `duration` only applies when the target is a static `set` (which has
         // none) — it spans the converted keyframes across the element's clip.
         { type: "convert-to-keyframes", animationId, resolvedFromValues, duration },
-        { label: "Convert to keyframes" },
+        { label: "Convert to keyframes", ...commitOverrides },
       );
     },
     [commitMutation, activeCompPath, sdkSession, sdkDeps],

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -217,6 +217,7 @@ let cleanup: (() => void) | null = null;
 function renderCommitHook() {
   const reloadPreview = vi.fn();
   const onCacheInvalidate = vi.fn();
+  const onFileContentChanged = vi.fn();
   const forceReloadSdkSession = vi.fn();
   const recordEdit = vi.fn(async () => {});
   const showToast = vi.fn();
@@ -231,7 +232,7 @@ function renderCommitHook() {
       domEditSaveTimestampRef: { current: 0 },
       reloadPreview,
       onCacheInvalidate,
-      onFileContentChanged: undefined,
+      onFileContentChanged,
       showToast,
       sdkSession: null,
       writeProjectFile: undefined,
@@ -252,6 +253,7 @@ function renderCommitHook() {
     api: hookApi,
     reloadPreview,
     onCacheInvalidate,
+    onFileContentChanged,
     forceReloadSdkSession,
     recordEdit,
     showToast,
@@ -383,4 +385,41 @@ describe("runCommit — instantPatch wiring", () => {
     expectSoftReloadedWith(deps.reloadPreview, "AFTER");
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
+
+  it("batch capability posts ordered mutations and finalizes the result once", async () => {
+    applySoftReload.mockReturnValue("applied");
+    mockFetchResult();
+    const deps = renderCommitHook();
+    const firstMutation = { type: "add", value: 1 };
+    const lastMutation = { type: "delete", value: 2 };
+    const batch = deps.api.commitMutation.batch;
+    if (!batch) throw new Error("batch capability missing");
+
+    await act(async () => {
+      await batch(
+        [
+          { selection, mutation: firstMutation, options: { label: "Resize", skipReload: true } },
+          { selection, mutation: lastMutation, options: { label: "Resize", softReload: true } },
+        ],
+        { label: "Resize", coalesceKey: "tx:resize:1", coalesceMs: Infinity, softReload: true },
+      );
+    });
+
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(fetch).toHaveBeenCalledWith(
+      "/api/projects/proj-1/gsap-mutations-batch/index.html",
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({ mutations: [firstMutation, lastMutation] }),
+      }),
+    );
+    expect(deps.recordEdit).toHaveBeenCalledTimes(1);
+    expect(deps.recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ label: "Resize", coalesceKey: "tx:resize:1" }),
+    );
+    expect(deps.onFileContentChanged).toHaveBeenCalledTimes(1);
+    expect(deps.forceReloadSdkSession).toHaveBeenCalledTimes(1);
+    expect(applySoftReload).toHaveBeenCalledTimes(1);
+    expect(deps.onCacheInvalidate).toHaveBeenCalledTimes(1);
+  });
 });