@hyperframes/studio 0.7.54 → 0.7.56

package/src/hooks/useGestureCommit.ts

@@ -10,8 +10,10 @@ import { smoothGestureKeyframes } from "../utils/gestureSmoother";
 import { usePlayerStore } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
 import { roundTo3 } from "../utils/rounding";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
+import { isInstantHold } from "./gsapShared";
 
 type RecordedKeyframe = {
   percentage: number;
@@ -68,10 +70,18 @@ interface GestureSessionRef {
   selectedGsapAnimations?: GsapAnimation[];
   commitMutation?: (
     mutation: Record<string, unknown>,
-    options: { label: string; softReload?: boolean },
+    options: CommitMutationOptions,
   ) => Promise<void>;
 }
 
+/** Only the LAST group in a per-group commit loop reloads the preview; the
+ *  earlier ones skip it, so a multi-group gesture recording is one reload. */
+function reloadOnlyLast(index: number, count: number): Partial<CommitMutationOptions> {
+  return index === count - 1 ? { softReload: true } : { skipReload: true };
+}
+
+let gestureRecordingCommitCounter = 0;
+
 interface UseGestureCommitParams {
   domEditSessionRef: React.MutableRefObject<GestureSessionRef>;
   previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
@@ -112,6 +122,10 @@ export function useGestureCommit({
       return;
     }
     commitInFlightRef.current = true;
+    const coalesceOptions = {
+      coalesceKey: `gesture-recording:${++gestureRecordingCommitCounter}`,
+      coalesceMs: Number.POSITIVE_INFINITY,
+    };
     gestureStateRef.current = "idle";
     isGestureRecordingRef.current = false;
     const frozenSamples = gestureRecording.stopRecording();
@@ -175,9 +189,9 @@ export function useGestureCommit({
           ? allAnims.find((a) => a.propertyGroup === "position" && a.targetSelector === selector)
           : undefined;
         if (existingPositionTween) {
-          if (existingPositionTween.method === "set") {
-            // A `set` is a static hold, not a tween to merge into — replace it with
-            // the recorded motion (which already starts from the set's position).
+          if (isInstantHold(existingPositionTween)) {
+            // An instant hold is not a tween to merge into — replace it with the
+            // recorded motion (which already starts from the held position).
             await liveSession.commitMutation(
               {
                 type: "replace-with-keyframes",
@@ -242,7 +256,8 @@ export function useGestureCommit({
               // Emit one tween per property group so a mixed-prop gesture (e.g.
               // x/y + opacity) doesn't collapse into an untagged legacy mixed
               // tween that the position-only drag intercept can't edit.
-              for (const groupKfs of partitionKeyframesByGroup(keyframes)) {
+              const keyframeGroups = partitionKeyframesByGroup(keyframes);
+              for (const [index, groupKfs] of keyframeGroups.entries()) {
                 await liveSession.commitMutation(
                   {
                     type: "add-with-keyframes",
@@ -256,14 +271,19 @@ export function useGestureCommit({
                     // not inherit a sigmoid.
                     easeEach: "none",
                   },
-                  { label: "Gesture recording (new range)", softReload: true },
+                  {
+                    label: "Gesture recording (new range)",
+                    ...coalesceOptions,
+                    ...reloadOnlyLast(index, keyframeGroups.length),
+                  },
                 );
               }
             }
           }
         } else {
           // No existing tween — same per-group split as the new-range branch above.
-          for (const groupKfs of partitionKeyframesByGroup(keyframes)) {
+          const keyframeGroups = partitionKeyframesByGroup(keyframes);
+          for (const [index, groupKfs] of keyframeGroups.entries()) {
             await liveSession.commitMutation(
               {
                 type: "add-with-keyframes",
@@ -274,7 +294,11 @@ export function useGestureCommit({
                 // Linear fallback (see above) — constant-speed segments stay linear.
                 easeEach: "none",
               },
-              { label: "Gesture recording", softReload: true },
+              {
+                label: "Gesture recording",
+                ...coalesceOptions,
+                ...reloadOnlyLast(index, keyframeGroups.length),
+              },
             );
           }
         }

package/src/hooks/useGroupCommits.ts

@@ -1,25 +1,12 @@
 import { useCallback } from "react";
-import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
-import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import {
+  readProjectFileContent,
+  saveProjectFilesWithHistory,
+  type DomEditCommitBaseParams,
+} from "../utils/studioFileHistory";
 import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
-import type { EditHistoryKind } from "../utils/editHistory";
 
-interface RecordEditInput {
-  label: string;
-  kind: EditHistoryKind;
-  coalesceKey?: string;
-  files: Record<string, { before: string; after: string }>;
-}
-
-interface UseGroupCommitsParams {
-  activeCompPath: string | null;
-  showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
-  domEditSaveTimestampRef: React.MutableRefObject<number>;
-  editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
-  projectIdRef: React.MutableRefObject<string | null>;
-  reloadPreview: () => void;
-  clearDomSelection: () => void;
+interface UseGroupCommitsParams extends DomEditCommitBaseParams {
   /** Resync the SDK session after a server-side write (the wrapper/unwrap changes
    * structure the in-memory doc doesn't know about). */
   forceReloadSdkSession?: () => void;
@@ -81,15 +68,7 @@ async function commitStructuralMutation(
     | "reloadPreview"
   >,
 ): Promise<{ content?: string; groupId?: string }> {
-  const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`);
-  if (!response.ok) {
-    throw await createStudioSaveHttpError(response, `Failed to read ${targetPath}`);
-  }
-  const data = (await response.json()) as { content?: string };
-  const originalContent = data.content;
-  if (typeof originalContent !== "string") {
-    throw new Error(`Missing file contents for ${targetPath}`);
-  }
+  const originalContent = await readProjectFileContent(pid, targetPath);
 
   deps.domEditSaveTimestampRef.current = Date.now();
   const mutateResponse = await fetch(

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,
+    });
+  });
+});