@hyperframes/studio 0.7.54 → 0.7.56

package/src/hooks/useElementLifecycleOps.ts

@@ -1,42 +1,26 @@
 import { useCallback } from "react";
 import { usePlayerStore } from "../player";
-import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import {
+  readProjectFileContent,
+  saveProjectFilesWithHistory,
+  type DomEditCommitBaseParams,
+} from "../utils/studioFileHistory";
 import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
 import {
   buildDomEditPatchTarget,
   readHfId,
   type DomEditSelection,
 } from "../components/editor/domEditing";
-import type { PatchOperation } from "../utils/sourcePatcher";
-import type { EditHistoryKind } from "../utils/editHistory";
-
-interface RecordEditInput {
-  label: string;
-  kind: EditHistoryKind;
-  coalesceKey?: string;
-  files: Record<string, { before: string; after: string }>;
-}
+import type { CommitDomEditPatchBatches, DomEditPatchBatch } from "./domEditCommitTypes";
 
-interface UseElementLifecycleOpsParams {
-  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 UseElementLifecycleOpsParams extends DomEditCommitBaseParams {
   /** Route delete through SDK when session resolves the hf-id; returns true if handled. */
   onTrySdkDelete?: (hfId: string, originalContent: string, targetPath: string) => Promise<boolean>;
   /** Resolver-shadow tripwire for the reordered targets (telemetry-only, decoupled from cutover). */
   onReorderShadow?: (targets: string[]) => void;
   /** Resync the SDK session after a server-fallback delete. */
   forceReloadSdkSession?: () => void;
-  commitPositionPatchToHtml: (
-    selection: DomEditSelection,
-    patches: PatchOperation[],
-    options: { label: string; coalesceKey: string; skipRefresh?: boolean },
-  ) => Promise<void>;
+  commitDomEditPatchBatches: CommitDomEditPatchBatches;
   /** Stage 7 Step 3b: called after a successful server-side element delete (shadow). */
   onElementDeleted?: (selection: DomEditSelection) => void;
 }
@@ -53,7 +37,7 @@ export function useElementLifecycleOps({
   onTrySdkDelete,
   onReorderShadow,
   forceReloadSdkSession,
-  commitPositionPatchToHtml,
+  commitDomEditPatchBatches,
   onElementDeleted,
 }: UseElementLifecycleOpsParams) {
   // fallow-ignore-next-line complexity
@@ -66,17 +50,7 @@ export function useElementLifecycleOps({
 
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
       try {
-        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);
 
         const patchTarget = buildDomEditPatchTarget(selection);
         if (!patchTarget.id && !patchTarget.selector && !patchTarget.hfId) {
@@ -156,8 +130,8 @@ export function useElementLifecycleOps({
     ],
   );
 
-  // ponytail: z-index reorder writes inline-style patches via commitPositionPatchToHtml →
-  // persistDomEditOperations → onTrySdkPersist, so it is already SDK-cut-over as setStyle.
+  // ponytail: z-index reorder folds every element patch for a source file in memory and sends
+  // one patch-elements-batch request, so each file is persisted with one atomic disk write.
   // No SDK reorder/reparent op exists; DOM sibling order stays server-authoritative if ever needed.
   const handleDomZIndexReorderCommit = useCallback(
     // fallow-ignore-next-line complexity
@@ -171,6 +145,7 @@ export function useElementLifecycleOps({
         sourceFile: string;
         key?: string;
       }>,
+      gestureCoalesceKey?: string,
     ) => {
       if (entries.length === 0) return Promise.resolve();
       // Resolver shadow (telemetry-only, decoupled from cutover): record whether
@@ -178,11 +153,12 @@ export function useElementLifecycleOps({
       onReorderShadow?.(
         entries.map((e) => readHfId(e.element)).filter((id): id is string => id != null),
       );
-      const coalesceKey = `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
-      const saves: Array<Promise<void>> = [];
+      const coalesceKey =
+        gestureCoalesceKey ??
+        `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
+      const patchesBySourceFile = new Map<string, DomEditPatchBatch["patches"]>();
       const rollbacks: Array<() => void> = [];
-      for (let i = 0; i < entries.length; i++) {
-        const entry = entries[i];
+      for (const entry of entries) {
         const priorZIndex = entry.element.style.zIndex;
         const priorPosition = entry.element.style.position;
         const priorStoreEntry = entry.key
@@ -218,39 +194,32 @@ export function useElementLifecycleOps({
             });
           }
         });
-        saves.push(
-          commitPositionPatchToHtml(
-            {
-              element: entry.element,
-              id: entry.id ?? null,
-              hfId: readHfId(entry.element),
-              selector: entry.selector,
-              selectorIndex: entry.selectorIndex,
-              sourceFile: entry.sourceFile,
-            } as unknown as DomEditSelection,
-            patches,
-            {
-              label: "Reorder layers",
-              coalesceKey,
-              skipRefresh: i < entries.length - 1,
-            },
-          ),
-        );
+        const filePatches = patchesBySourceFile.get(entry.sourceFile) ?? [];
+        filePatches.push({
+          target: buildDomEditPatchTarget({
+            id: entry.id,
+            hfId: readHfId(entry.element),
+            selector: entry.selector,
+            selectorIndex: entry.selectorIndex,
+          }),
+          operations: patches,
+        });
+        patchesBySourceFile.set(entry.sourceFile, filePatches);
       }
-      // Resolves once every z-index patch is persisted so a same-file timing write
+      const batches = [...patchesBySourceFile].map(([sourceFile, patches]) => ({
+        sourceFile,
+        patches,
+      }));
+      // Resolves once every source-file batch is persisted so a same-file timing write
       // can be ordered after it (see applyTimelineStackingReorder callers).
-      return Promise.allSettled(saves).then((settled) => {
-        const rejected = settled.find(
-          (result): result is PromiseRejectedResult => result.status === "rejected",
-        );
-        if (rejected) {
+      return commitDomEditPatchBatches(batches, { label: "Reorder layers", coalesceKey }).catch(
+        (error) => {
           for (const rollback of rollbacks) rollback();
-          return Promise.reject(rejected.reason);
-        }
-        return undefined;
-      });
+          throw error;
+        },
+      );
     },
-    [commitPositionPatchToHtml, onReorderShadow],
+    [commitDomEditPatchBatches, onReorderShadow],
   );
 
   return {

package/src/hooks/useEnableKeyframes.test.ts

@@ -1,4 +1,7 @@
-import { describe, expect, it } from "vitest";
+// @vitest-environment happy-dom
+import { act, createElement, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
@@ -7,8 +10,20 @@ import {
   isPlayheadWithinTween,
   promoteSetToKeyframes,
   resolveNewTweenRange,
+  useEnableKeyframes,
   type EnableKeyframesSession,
 } from "./useEnableKeyframes";
+import { usePlayerStore } from "../player/store/playerStore";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let cleanup: (() => void) | null = null;
+afterEach(() => {
+  cleanup?.();
+  cleanup = null;
+  vi.unstubAllGlobals();
+  window.location.hash = "";
+});
 
 function anim(overrides: Partial<GsapAnimation>): GsapAnimation {
   return {
@@ -203,3 +218,129 @@ describe("promoteSetToKeyframes — auto endpoint", () => {
     expect(kfs[0].percentage).toBe(0);
   });
 });
+
+function renderEnableKeyframes(session: EnableKeyframesSession): () => Promise<void> {
+  let enable: (() => Promise<void>) | null = null;
+  function Probe() {
+    const sessionRef = useRef<EnableKeyframesSession | undefined>(session);
+    enable = useEnableKeyframes(sessionRef);
+    return null;
+  }
+  const container = document.createElement("div");
+  const root = createRoot(container);
+  act(() => root.render(createElement(Probe)));
+  cleanup = () => act(() => root.unmount());
+  if (!enable) throw new Error("hook did not initialize");
+  return enable;
+}
+
+function flatTweenResponses(flat: GsapAnimation, converted: GsapAnimation) {
+  const responses = [{ animations: [flat] }, { animations: [converted] }];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => ({
+      ok: true,
+      json: async () => responses.shift() ?? { animations: [] },
+    })),
+  );
+}
+
+function makeElementSelection(): DomEditSelection {
+  const element = document.body.appendChild(document.createElement("div"));
+  element.id = "el";
+  return {
+    id: "el",
+    selector: "#el",
+    sourceFile: "index.html",
+    element,
+  } as DomEditSelection;
+}
+
+function stubFlatTweenConversion(id: string): {
+  flat: GsapAnimation;
+  converted: GsapAnimation;
+} {
+  const flat = anim({ id, position: 1, duration: 1, properties: { x: 10 } });
+  const converted = anim({
+    id,
+    position: 1,
+    duration: 1,
+    keyframes: {
+      format: "object-array",
+      keyframes: [
+        { percentage: 0, properties: { x: 0 } },
+        { percentage: 100, properties: { x: 10 } },
+      ],
+    },
+  });
+  flatTweenResponses(flat, converted);
+  return { flat, converted };
+}
+
+describe("useEnableKeyframes — flat tween transaction", () => {
+  it("skips the convert reload and coalesces an outside-range terminal soft reload", async () => {
+    window.location.hash = "#/project/test-project";
+    usePlayerStore.setState({ currentTime: 3 });
+    const selection = makeElementSelection();
+    const { flat } = stubFlatTweenConversion("flat-1");
+    const handleConvert = vi.fn(async () => undefined);
+    const commitMutation = vi.fn(async () => undefined);
+    const enable = renderEnableKeyframes({
+      domEditSelection: selection,
+      selectedGsapAnimations: [flat],
+      previewIframeRef: {
+        current: {
+          contentWindow: { gsap: { getProperty: () => 10 } },
+        } as unknown as HTMLIFrameElement,
+      },
+      handleGsapAddAnimation: vi.fn(),
+      handleGsapConvertToKeyframes: handleConvert,
+      handleGsapRemoveKeyframe: vi.fn(),
+      commitMutation,
+    });
+
+    await act(async () => enable());
+
+    const convertOptions = handleConvert.mock.calls[0]?.[3];
+    const terminalOptions = commitMutation.mock.calls[0]?.[1];
+    expect(convertOptions).toMatchObject({ skipReload: true, coalesceMs: Infinity });
+    expect(terminalOptions).toMatchObject({
+      softReload: true,
+      coalesceKey: convertOptions?.coalesceKey,
+    });
+    expect(convertOptions?.coalesceKey).toEqual(expect.any(String));
+  });
+
+  it("passes the convert coalesce key to an inside-range batch edit", async () => {
+    window.location.hash = "#/project/test-project";
+    usePlayerStore.setState({ currentTime: 1.5 });
+    const selection = makeElementSelection();
+    const { flat } = stubFlatTweenConversion("flat-2");
+    const handleConvert = vi.fn(async () => undefined);
+    const addKeyframeBatch = vi.fn(async () => undefined);
+    const enable = renderEnableKeyframes({
+      domEditSelection: selection,
+      selectedGsapAnimations: [flat],
+      previewIframeRef: {
+        current: {
+          contentWindow: { gsap: { getProperty: () => 5 } },
+        } as unknown as HTMLIFrameElement,
+      },
+      handleGsapAddAnimation: vi.fn(),
+      handleGsapConvertToKeyframes: handleConvert,
+      handleGsapRemoveKeyframe: vi.fn(),
+      handleGsapAddKeyframeBatch: addKeyframeBatch,
+    });
+
+    await act(async () => enable());
+
+    const convertOptions = handleConvert.mock.calls[0]?.[3];
+    expect(addKeyframeBatch.mock.calls[0]?.[3]).toEqual({
+      softReload: true,
+      coalesceKey: convertOptions?.coalesceKey,
+      // Must carry the convert phase's infinite window so the inside-range
+      // apply folds into one undo entry regardless of round-trip latency.
+      coalesceMs: Infinity,
+    });
+  });
+});

package/src/hooks/useEnableKeyframes.ts

@@ -12,7 +12,7 @@ import type { GsapAnimation, GsapPercentageKeyframe } from "@hyperframes/core/gs
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
-import { selectorFromSelection, computeElementPercentage } from "./gsapShared";
+import { selectorFromSelection, computeElementPercentage, isInstantHold } from "./gsapShared";
 import {
   resolveTweenStart,
   resolveTweenDuration,
@@ -21,6 +21,9 @@ import {
 import { POSITION_PROPS } from "./gsapRuntimeReaders";
 import { roundTo3 } from "../utils/rounding";
 import { nearestPointOnPath } from "../components/editor/motionPathGeometry";
+import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+
+let enableKeyframesTransactionCounter = 0;
 
 export interface EnableKeyframesSession {
   domEditSelection: DomEditSelection | null;
@@ -30,16 +33,19 @@ export interface EnableKeyframesSession {
   handleGsapConvertToKeyframes: (
     animId: string,
     resolvedFromValues?: Record<string, number | string>,
+    duration?: number,
+    commitOverrides?: Partial<CommitMutationOptions>,
   ) => void | Promise<void>;
   handleGsapRemoveKeyframe: (animId: string, pct: number) => void;
   handleGsapAddKeyframeBatch?: (
     animId: string,
     pct: number,
     properties: Record<string, number | string>,
+    commitOverrides?: Partial<CommitMutationOptions>,
   ) => Promise<void>;
   commitMutation?: (
     mutation: Record<string, unknown>,
-    options: { label: string; softReload?: boolean },
+    options: CommitMutationOptions,
   ) => Promise<void>;
 }
 
@@ -107,6 +113,36 @@ export function buildExtendedKeyframes(
   return { position: roundTo3(newStart), duration: newDuration, keyframes };
 }
 
+async function replaceSetWithSingleKeyframe(
+  session: EnableKeyframesSession,
+  sel: DomEditSelection,
+  setAnim: GsapAnimation,
+  t: number,
+  iframe: HTMLIFrameElement | null,
+  selector: string,
+): Promise<void> {
+  const position = readElementPosition(iframe, sel, setAnim);
+  if (Object.keys(position).length === 0) {
+    for (const [key, held] of Object.entries(setAnim.properties ?? {})) {
+      if (typeof held === "number") position[key] = held;
+    }
+  }
+  if (Object.keys(position).length === 0 || !session.commitMutation) return;
+  const range = resolveNewTweenRange(sel.dataAttributes?.start, sel.dataAttributes?.duration, t);
+  await session.commitMutation(
+    {
+      type: "replace-with-keyframes",
+      animationId: setAnim.id,
+      targetSelector: selector,
+      position: roundTo3(range.start),
+      duration: roundTo3(range.duration),
+      keyframes: [{ percentage: 0, properties: position }],
+      ease: setAnim.ease,
+    },
+    { label: "Enable keyframes", softReload: true },
+  );
+}
+
 // fallow-ignore-next-line complexity
 function readElementPosition(
   iframe: HTMLIFrameElement | null,
@@ -199,6 +235,7 @@ async function applyKeyframeAtPlayhead(
   kfAnim: GsapAnimation,
   t: number,
   iframe: HTMLIFrameElement | null,
+  commitOverrides?: Partial<CommitMutationOptions>,
 ): Promise<void> {
   if (!isPlayheadWithinTween(kfAnim, t)) {
     const position = readElementPosition(iframe, sel, kfAnim);
@@ -215,7 +252,11 @@ async function applyKeyframeAtPlayhead(
           keyframes: extended.keyframes,
           ease: kfAnim.ease,
         },
-        { label: "Add keyframe", softReload: true },
+        {
+          label: "Add keyframe",
+          softReload: true,
+          ...commitOverrides,
+        },
       );
     }
     return;
@@ -229,7 +270,7 @@ async function applyKeyframeAtPlayhead(
   if (session.handleGsapAddKeyframeBatch) {
     const position = readElementPosition(iframe, sel, kfAnim);
     if (Object.keys(position).length > 0) {
-      await session.handleGsapAddKeyframeBatch(kfAnim.id, pct, position);
+      await session.handleGsapAddKeyframeBatch(kfAnim.id, pct, position, commitOverrides);
     }
   }
 }
@@ -259,27 +300,7 @@ export async function promoteSetToKeyframes(
   // the set with a single keyframe at the playhead holding its value, matching the
   // no-animation branch: one diamond the user can build motion from.
   if (t <= setStart) {
-    const position = readElementPosition(iframe, sel, setAnim);
-    if (Object.keys(position).length === 0) {
-      for (const key of Object.keys(setAnim.properties ?? {})) {
-        const held = setAnim.properties?.[key];
-        if (typeof held === "number") position[key] = held;
-      }
-    }
-    if (Object.keys(position).length === 0) return;
-    const range = resolveNewTweenRange(sel.dataAttributes?.start, sel.dataAttributes?.duration, t);
-    await session.commitMutation(
-      {
-        type: "replace-with-keyframes",
-        animationId: setAnim.id,
-        targetSelector: selector,
-        position: roundTo3(range.start),
-        duration: roundTo3(range.duration),
-        keyframes: [{ percentage: 0, properties: position }],
-        ease: setAnim.ease,
-      },
-      { label: "Enable keyframes", softReload: true },
-    );
+    await replaceSetWithSingleKeyframe(session, sel, setAnim, t, iframe, selector);
     return;
   }
   const endPosition = readElementPosition(iframe, sel, setAnim);
@@ -395,8 +416,8 @@ export function useEnableKeyframes(
     // the curve.
     const arcAnim = anims.find((a) => a.arcPath);
     const kfAnim = anims.find((a) => a.keyframes && !a.arcPath);
-    const setAnim = anims.find((a) => a.method === "set" && !a.keyframes && !a.arcPath);
-    const flatAnim = anims.find((a) => !a.keyframes && !a.arcPath && a.method !== "set");
+    const setAnim = anims.find((a) => isInstantHold(a) && !a.keyframes && !a.arcPath);
+    const flatAnim = anims.find((a) => !a.keyframes && !a.arcPath && !isInstantHold(a));
 
     if (arcAnim) {
       await applyArcWaypointAtPlayhead(session, sel, arcAnim, t, iframe);
@@ -409,9 +430,32 @@ export function useEnableKeyframes(
       // resolvedFromValues, so the 0%/100% stops keep the real start→end motion
       // (passing the playhead value would flatten it). Then apply uniformly so an
       // out-of-range playhead extends the range just like a keyframe tween.
-      await session.handleGsapConvertToKeyframes(flatAnim.id);
+      enableKeyframesTransactionCounter += 1;
+      const coalesceKey = `enable-keyframes:${flatAnim.id}:${enableKeyframesTransactionCounter}`;
+      const convertCommitOverrides: Partial<CommitMutationOptions> = {
+        skipReload: true,
+        coalesceKey,
+        coalesceMs: Number.POSITIVE_INFINITY,
+      };
+      await session.handleGsapConvertToKeyframes(
+        flatAnim.id,
+        undefined,
+        undefined,
+        convertCommitOverrides,
+      );
       const converted = (await fetchAnimationsForElement(sel)).find((a) => a.keyframes);
-      if (converted) await applyKeyframeAtPlayhead(session, sel, converted, t, iframe);
+      if (converted) {
+        const applyCommitOverrides: Partial<CommitMutationOptions> = {
+          softReload: true,
+          coalesceKey,
+          // Must match the convert phase's window: editHistory keys coalescing
+          // off the incoming entry, so without Infinity here the apply (landing
+          // after two POSTs + a fetch) falls back to the 300ms default and the
+          // conversion splits into two undo entries under real latency.
+          coalesceMs: Number.POSITIVE_INFINITY,
+        };
+        await applyKeyframeAtPlayhead(session, sel, converted, t, iframe, applyCommitOverrides);
+      }
     } else {
       const position = readElementPosition(iframe, sel, null);
       const { start: elStart, duration: elDuration } = resolveNewTweenRange(

package/src/hooks/useGestureCommit.test.tsx

@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { usePlayerStore } from "../player";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+import { useGestureCommit } from "./useGestureCommit";
+
+const gestureRecording = vi.hoisted(() => ({
+  startRecording: vi.fn(),
+  stopRecording: vi.fn(() => [
+    { time: 0, properties: { x: 0, y: 0, opacity: 1 } },
+    { time: 0.5, properties: { x: 50, y: 25, opacity: 0.5 } },
+    { time: 1, properties: { x: 100, y: 50, opacity: 0 } },
+  ]),
+  clearSamples: vi.fn(),
+  cancelRecording: vi.fn(),
+  isRecording: false,
+  recordingDuration: 0,
+  samplesRef: { current: [] },
+  trailRef: { current: [] },
+}));
+
+vi.mock("./useGestureRecording", () => ({
+  useGestureRecording: () => gestureRecording,
+}));
+
+vi.mock("../utils/rdpSimplify", () => ({
+  simplifyGestureSamples: () =>
+    new Map([
+      [0, { x: 0, y: 0, opacity: 1 }],
+      [50, { x: 50, y: 25, opacity: 0.5 }],
+      [100, { x: 100, y: 50, opacity: 0 }],
+    ]),
+}));
+
+vi.mock("../utils/gestureSmoother", () => ({
+  smoothGestureKeyframes: (keyframes: unknown) => keyframes,
+}));
+
+vi.mock("../utils/velocityEaseFitter", () => ({
+  fitEasesFromVelocity: (keyframes: unknown) => keyframes,
+}));
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+let cleanup: (() => void) | null = null;
+
+afterEach(() => {
+  cleanup?.();
+  cleanup = null;
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+  vi.clearAllMocks();
+});
+
+function makeSelection(element: HTMLElement): DomEditSelection {
+  return {
+    id: element.id,
+    element,
+    label: "Card",
+    tagName: "div",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 100, height: 100 },
+    textContent: null,
+    dataAttributes: { start: "0", duration: "2" },
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+}
+
+describe("useGestureCommit", () => {
+  it("coalesces property-group commits and reloads only the terminal group", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const element = document.createElement("div");
+    element.id = "card";
+    const commitMutation = vi.fn<
+      (mutation: Record<string, unknown>, options: CommitMutationOptions) => Promise<void>
+    >(async () => {});
+    const sessionRef = {
+      current: {
+        domEditSelection: makeSelection(element),
+        selectedGsapAnimations: [],
+        commitMutation,
+      },
+    };
+    const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
+    function Probe() {
+      captured.hook = useGestureCommit({
+        domEditSessionRef: sessionRef,
+        previewIframeRef: { current: iframe },
+        showToast: vi.fn(),
+        isGestureRecordingRef: { current: false },
+      });
+      return null;
+    }
+    const root = mountReactHarness(<Probe />);
+    cleanup = () => act(() => root.unmount());
+    if (!captured.hook) throw new Error("hook did not initialize");
+
+    act(() => captured.hook?.handleToggleRecording());
+    act(() => captured.hook?.handleToggleRecording());
+    await act(async () => {
+      await vi.waitFor(() => expect(commitMutation).toHaveBeenCalledTimes(2));
+    });
+
+    const options = commitMutation.mock.calls.map((call) => call[1]);
+    expect(new Set(options.map((entry) => entry.coalesceKey)).size).toBe(1);
+    expect(options[0]).toEqual(expect.objectContaining({ coalesceMs: Infinity, skipReload: true }));
+    expect(options[0]).not.toHaveProperty("softReload");
+    expect(options[1]).toEqual(expect.objectContaining({ coalesceMs: Infinity, softReload: true }));
+    expect(options[1]).not.toHaveProperty("skipReload");
+  });
+});