@hyperframes/studio 0.8.113 → 0.8.115

package/src/hooks/useGestureCommit.test.tsx

@@ -1,12 +1,18 @@
 // @vitest-environment jsdom
-import { act } from "react";
+import { act, useLayoutEffect } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
 import { useGestureCommit } from "./useGestureCommit";
 
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
 const gestureRecording = vi.hoisted(() => ({
   startRecording: vi.fn(),
   stopRecording: vi.fn(() => [
@@ -84,44 +90,88 @@ function makeSelection(element: HTMLElement): DomEditSelection {
   };
 }
 
+function mountRecording(
+  writer: (
+    mutation: Record<string, unknown>,
+    options: CommitMutationOptions,
+    selection?: DomEditSelection,
+  ) => Promise<void>,
+  animations: GsapAnimation[] = [],
+  readOnlyPreview = false,
+) {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const element = document.createElement("div");
+  element.id = "card";
+  const session = {
+    current: {
+      domEditSelection: makeSelection(element),
+      selectedGsapAnimations: animations,
+      commitMutation: writer,
+    },
+  };
+  let hook: ReturnType<typeof useGestureCommit> | null = null;
+  function Probe() {
+    const editing = useGsapAwareEditing({
+      domEditSelection: session.current.domEditSelection,
+      selectedGsapAnimations: session.current.selectedGsapAnimations,
+      gsapCommitMutation: (selection, mutation, options) => writer(mutation, options, selection),
+      previewIframeRef: { current: iframe },
+      showToast: vi.fn(),
+      bumpGsapCache: vi.fn(),
+      makeFetchFallback: () => vi.fn(),
+      trackGsapInteractionFailure: vi.fn(),
+      stageElementPositionOffset: vi.fn(),
+      handleDomBoxSizeCommit: vi.fn(),
+      handleDomRotationCommit: vi.fn(),
+      commitPositionPatchToHtml: vi.fn(),
+      addGsapAnimation: vi.fn(),
+      convertToKeyframes: vi.fn(),
+      setArcPath: vi.fn(),
+      updateArcSegment: vi.fn(),
+    });
+    const currentHook = useGestureCommit({
+      domEditSessionRef: session,
+      previewIframeRef: { current: iframe },
+      showToast: vi.fn(),
+      isGestureRecordingRef: { current: false },
+      readOnlyPreview,
+    });
+    useLayoutEffect(() => {
+      session.current.commitMutation = editing.commitMutation;
+      hook = currentHook;
+    });
+    return null;
+  }
+  const root = mountReactHarness(<Probe />);
+  cleanup = () => act(() => root.unmount());
+  return Object.assign(
+    () => {
+      if (!hook) throw new Error("hook did not initialize");
+      return hook;
+    },
+    {
+      select: (selection: DomEditSelection, nextAnimations: GsapAnimation[]) => {
+        session.current.domEditSelection = selection;
+        session.current.selectedGsapAnimations = nextAnimations;
+        act(() => root.render(<Probe />));
+      },
+    },
+  );
+}
+
 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<
+    const writer = 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 },
-        readOnlyPreview: 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());
+    const hook = mountRecording(writer);
+    act(() => hook().handleToggleRecording());
+    act(() => hook().handleToggleRecording());
     await act(async () => {
-      await vi.waitFor(() => expect(commitMutation).toHaveBeenCalledTimes(2));
+      await vi.waitFor(() => expect(writer).toHaveBeenCalledTimes(2));
     });
-
-    const options = commitMutation.mock.calls.map((call) => call[1]);
+    const options = writer.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");
@@ -130,30 +180,150 @@ describe("useGestureCommit", () => {
   });
 
   it("does not start a recording while the preview is read-only", () => {
-    const element = document.createElement("div");
-    const commitMutation = vi.fn(async () => {});
-    const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
-    function Probe() {
-      captured.hook = useGestureCommit({
-        domEditSessionRef: {
-          current: {
-            domEditSelection: makeSelection(element),
-            selectedGsapAnimations: [],
-            commitMutation,
-          },
-        },
-        previewIframeRef: { current: document.createElement("iframe") },
-        showToast: vi.fn(),
-        isGestureRecordingRef: { current: false },
-        readOnlyPreview: true,
+    const writer = vi.fn(async () => {});
+    const hook = mountRecording(writer, [], true);
+    act(() => hook().handleToggleRecording());
+    expect(gestureRecording.startRecording).not.toHaveBeenCalled();
+    expect(writer).not.toHaveBeenCalled();
+  });
+});
+
+it.each([
+  ["new mixed-property recording", undefined, true, true, 1, "button"],
+  ["keyboard recording", undefined, true, true, 1, "keyboard"],
+  ["static hold replacement", "set", true, true, 1, "button"],
+  ["overlapping tween replacement", "to", true, true, 1, "button"],
+  ["unchanged recording", undefined, true, false, 0, "button"],
+  ["refused recording", undefined, false, true, 0, "button"],
+] as const)(
+  "counts writer receipts once for %s",
+  async (_name, method, ok, changed, count, inputMethod) => {
+    const animations = method
+      ? [
+          {
+            id: "card-position",
+            targetSelector: "#card",
+            propertyGroup: "position",
+            method,
+            properties: { x: 0, y: 0 },
+            resolvedStart: 0,
+            position: 0,
+            duration: method === "set" ? 0 : 2,
+            keyframes: {
+              keyframes: [
+                { percentage: 0, properties: { x: 0 } },
+                { percentage: 100, properties: { x: 100 } },
+              ],
+            },
+          } as unknown as GsapAnimation,
+        ]
+      : [];
+    const writer = vi.fn(
+      async (mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+        const result = { ok, changed };
+        trackKeyframeCommit([mutation], result, options);
+        options.onResult?.(result);
+      },
+    );
+    const hook = mountRecording(writer, animations);
+    act(() => hook().handleToggleRecording(inputMethod));
+    await act(async () => {
+      hook().handleToggleRecording();
+      await vi.waitFor(() => expect(writer).toHaveBeenCalled());
+    });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(count * 2);
+    if (count) {
+      expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+      expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+        feature: "gesture_recording",
+        surface: "preview",
+        method: inputMethod,
       });
-      return null;
     }
-    const root = mountReactHarness(<Probe />);
-    cleanup = () => act(() => root.unmount());
+  },
+);
 
-    act(() => captured.hook?.handleToggleRecording());
-    expect(gestureRecording.startRecording).not.toHaveBeenCalled();
-    expect(commitMutation).not.toHaveBeenCalled();
+it("keeps a pending recording isolated until its writer settles", async () => {
+  let release!: () => void;
+  const pending = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const writer = vi.fn(
+    async (_mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+      await pending;
+      options.onResult?.({ ok: true, changed: true });
+    },
+  );
+  const hook = mountRecording(writer);
+  act(() => hook().handleToggleRecording("keyboard"));
+  act(() => hook().handleToggleRecording());
+  await vi.waitFor(() => expect(writer).toHaveBeenCalledTimes(1));
+  act(() => hook().handleToggleRecording("button"));
+  expect(gestureRecording.startRecording).toHaveBeenCalledTimes(1);
+  await act(async () => {
+    release();
+    await vi.waitFor(() =>
+      expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+        feature: "gesture_recording",
+        surface: "preview",
+        method: "keyboard",
+      }),
+    );
+  });
+  expect(gestureRecording.clearSamples).toHaveBeenCalledTimes(1);
+  act(() => hook().handleToggleRecording("button"));
+  expect(gestureRecording.startRecording).toHaveBeenCalledTimes(2);
+});
+
+it("writes one recording to its original selection after selecting another source", async () => {
+  const original = {
+    id: "original-position",
+    targetSelector: "#card",
+    propertyGroup: "position",
+    method: "set",
+    properties: { x: 0, y: 0 },
+    resolvedStart: 0,
+    position: 0,
+    duration: 0,
+  } as GsapAnimation;
+  const writer = vi.fn(
+    async (
+      _mutation: Record<string, unknown>,
+      options: CommitMutationOptions,
+      _selection?: DomEditSelection,
+    ) => {
+      options.onResult?.({ ok: true, changed: true });
+    },
+  );
+  const hook = mountRecording(writer, [original]);
+  act(() => hook().handleToggleRecording("keyboard"));
+  const other = document.createElement("div");
+  other.id = "other";
+  hook.select(
+    { ...makeSelection(other), sourceFile: "other.html", compositionPath: "other.html" },
+    [],
+  );
+  await act(async () => {
+    hook().handleToggleRecording();
+    await vi.waitFor(() => expect(trackStudioEvent).toHaveBeenCalledTimes(2));
+  });
+  expect(writer).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      type: "replace-with-keyframes",
+      animationId: "original-position",
+      targetSelector: "#card",
+    }),
+    expect.objectContaining({ keyframeAction: "add" }),
+    expect.objectContaining({
+      id: "card",
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+    }),
+  );
+  expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+  expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+    feature: "gesture_recording",
+    surface: "preview",
+    method: "keyboard",
   });
 });

package/src/hooks/useGestureCommit.ts

@@ -11,9 +11,12 @@ 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 { trackPreviewEditResult } from "../utils/previewFeatureUsage";
+import { observeGsapGesture } from "./gsapGestureOutcome";
 import { roundTo3 } from "../utils/rounding";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
 import { isInstantHold, idSelector, writeTargetSelector, tweenTargetsElement } from "./gsapShared";
+import { useStableHandlers } from "./useStableHandlers";
 
 type RecordedKeyframe = {
   percentage: number;
@@ -71,6 +74,7 @@ interface GestureSessionRef {
   commitMutation?: (
     mutation: Record<string, unknown>,
     options: CommitMutationOptions,
+    selection?: DomEditSelection,
   ) => Promise<void>;
 }
 
@@ -80,9 +84,16 @@ function reloadOnlyLast(index: number, count: number): Partial<CommitMutationOpt
   return index === count - 1 ? { softReload: true } : { skipReload: true };
 }
 
+function recordingEnd(selection: DomEditSelection): number | undefined {
+  const start = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
+  const duration = Number.parseFloat(selection.dataAttributes?.duration ?? "0") || 0;
+  return duration > 0 ? start + duration : undefined;
+}
+
 let gestureRecordingCommitCounter = 0;
 
 interface UseGestureCommitParams {
+  projectId?: string | null;
   domEditSessionRef: React.MutableRefObject<GestureSessionRef>;
   previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
@@ -93,11 +104,12 @@ interface UseGestureCommitParams {
 export interface UseGestureCommitResult {
   gestureState: "idle" | "recording";
   gestureRecording: ReturnType<typeof useGestureRecording>;
-  handleToggleRecording: () => void;
+  handleToggleRecording: (method?: "button" | "keyboard") => void;
 }
 
 // fallow-ignore-next-line complexity
 export function useGestureCommit({
+  projectId,
   domEditSessionRef,
   previewIframeRef,
   showToast,
@@ -108,11 +120,13 @@ export function useGestureCommit({
   const [gestureState, setGestureState] = useState<"idle" | "recording">("idle");
   const gestureStateRef = useRef<"idle" | "recording">("idle");
   const recordingAutoStopRef = useRef<ReturnType<typeof setInterval>>(undefined);
+  const recordingMethodRef = useRef<"button" | "keyboard">("button");
   const recordingStartTimeRef = useRef(0);
   const commitInFlightRef = useRef(false);
   // Capture selection at recording start so commit always targets the recorded element,
   // even if the user's selection changes mid-recording.
   const capturedSelectionRef = useRef<DomEditSelection | null>(null);
+  const capturedAnimationsRef = useRef<GsapAnimation[]>([]);
 
   // Unmount: clear auto-stop interval
   useEffect(() => () => clearInterval(recordingAutoStopRef.current), []);
@@ -203,6 +217,12 @@ export function useGestureCommit({
         return;
       }
       if (liveSession.commitMutation) {
+        const writer = liveSession.commitMutation;
+        const outcome = observeGsapGesture((_selection, mutation, options) =>
+          writer(mutation, options, sel),
+        );
+        const commit = (mutation: Record<string, unknown>, options: CommitMutationOptions) =>
+          outcome.commit!(sel, mutation, options);
         const recStart = recordingStartTimeRef.current;
         const rawKeyframes = sortedPcts.map((pct) => ({
           percentage: pct,
@@ -213,7 +233,7 @@ export function useGestureCommit({
         const hasPositionProps = keyframes.some((kf) =>
           Object.keys(kf.properties).some((k) => classifyPropertyGroup(k) === "position"),
         );
-        const allAnims = liveSession.selectedGsapAnimations ?? [];
+        const allAnims = capturedAnimationsRef.current;
         const existingPositionTween = hasPositionProps
           ? allAnims.find(
               (a) =>
@@ -225,7 +245,7 @@ export function useGestureCommit({
           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(
+            await commit(
               {
                 type: "replace-with-keyframes",
                 animationId: existingPositionTween.id,
@@ -234,7 +254,7 @@ export function useGestureCommit({
                 duration: roundTo3(duration),
                 keyframes,
               },
-              { label: "Gesture recording (replace set)", softReload: true },
+              { label: "Gesture recording (replace set)", softReload: true, keyframeAction: "add" },
             );
           } else {
             const tweenStart = existingPositionTween.resolvedStart ?? 0;
@@ -271,7 +291,7 @@ export function useGestureCommit({
 
               const merged = [...preserved, ...mapped].sort((a, b) => a.percentage - b.percentage);
 
-              await liveSession.commitMutation(
+              await commit(
                 {
                   type: "replace-with-keyframes",
                   animationId: existingPositionTween.id,
@@ -283,7 +303,7 @@ export function useGestureCommit({
                   duration: tweenDur,
                   keyframes: merged,
                 },
-                { label: "Gesture recording (merge)", softReload: true },
+                { label: "Gesture recording (merge)", softReload: true, keyframeAction: "add" },
               );
             } else {
               // Emit one tween per property group so a mixed-prop gesture (e.g.
@@ -291,7 +311,7 @@ export function useGestureCommit({
               // tween that the position-only drag intercept can't edit.
               const keyframeGroups = partitionKeyframesByGroup(keyframes);
               for (const [index, groupKfs] of keyframeGroups.entries()) {
-                await liveSession.commitMutation(
+                await commit(
                   {
                     type: "add-with-keyframes",
                     targetSelector: writeSelector,
@@ -317,7 +337,7 @@ export function useGestureCommit({
           // No existing tween — same per-group split as the new-range branch above.
           const keyframeGroups = partitionKeyframesByGroup(keyframes);
           for (const [index, groupKfs] of keyframeGroups.entries()) {
-            await liveSession.commitMutation(
+            await commit(
               {
                 type: "add-with-keyframes",
                 targetSelector: writeSelector,
@@ -335,6 +355,7 @@ export function useGestureCommit({
             );
           }
         }
+        trackPreviewEditResult("gesture_recording", recordingMethodRef.current, outcome.finish());
       }
       showToast(`Recorded ${sortedPcts.length} keyframes`, "info");
     } catch (err) {
@@ -348,58 +369,71 @@ export function useGestureCommit({
     }
   }, [gestureRecording, showToast, isGestureRecordingRef, domEditSessionRef]);
 
-  // fallow-ignore-next-line complexity
-  const handleToggleRecording = useCallback(() => {
-    if (gestureStateRef.current === "recording") {
-      if (readOnlyPreview) {
-        cancelRecording();
+  const armAutoStop = useCallback(
+    (elementEnd: number | undefined) => {
+      clearInterval(recordingAutoStopRef.current);
+      const autoStopAt = elementEnd ?? Infinity;
+      recordingAutoStopRef.current = setInterval(() => {
+        const { currentTime: t, duration: d } = usePlayerStore.getState();
+        const limit = Math.min(autoStopAt, d);
+        if (limit > 0 && t >= limit - 0.05) {
+          void stopAndCommitRecording();
+        }
+      }, 100);
+    },
+    [stopAndCommitRecording],
+  );
+
+  const startRecording = useCallback(
+    (method: "button" | "keyboard") => {
+      if (readOnlyPreview) return;
+      const sel = domEditSessionRef.current.domEditSelection;
+      if (!sel) {
+        showToast("Select an element first", "error");
+        return;
+      }
+      const iframe = previewIframeRef.current;
+      if (!iframe) {
+        showToast("Preview not ready — try again", "error");
         return;
       }
-      void stopAndCommitRecording();
-      return;
-    }
-    if (readOnlyPreview) return;
-    const sel = domEditSessionRef.current.domEditSelection;
-    if (!sel) {
-      showToast("Select an element first", "error");
-      return;
-    }
-    const iframe = previewIframeRef.current;
-    if (!iframe) {
-      showToast("Preview not ready — try again", "error");
-      return;
-    }
 
-    const store = usePlayerStore.getState();
-    recordingStartTimeRef.current = store.currentTime;
-    const elStart = Number.parseFloat(sel.dataAttributes?.start ?? "0") || 0;
-    const elDur = Number.parseFloat(sel.dataAttributes?.duration ?? "0") || 0;
-    const elementEnd = elDur > 0 ? elStart + elDur : undefined;
-    capturedSelectionRef.current = sel;
-    gestureRecording.startRecording(sel.element, iframe, elementEnd);
-    gestureStateRef.current = "recording";
-    isGestureRecordingRef.current = true;
-    setGestureState("recording");
+      const store = usePlayerStore.getState();
+      recordingMethodRef.current = method;
+      recordingStartTimeRef.current = store.currentTime;
+      const elementEnd = recordingEnd(sel);
+      capturedSelectionRef.current = sel;
+      capturedAnimationsRef.current = domEditSessionRef.current.selectedGsapAnimations ?? [];
+      gestureRecording.startRecording(sel.element, iframe, elementEnd);
+      gestureStateRef.current = "recording";
+      isGestureRecordingRef.current = true;
+      setGestureState("recording");
 
-    clearInterval(recordingAutoStopRef.current);
-    const autoStopAt = elementEnd ?? Infinity;
-    recordingAutoStopRef.current = setInterval(() => {
-      const { currentTime: t, duration: d } = usePlayerStore.getState();
-      const limit = Math.min(autoStopAt, d);
-      if (limit > 0 && t >= limit - 0.05) {
-        void stopAndCommitRecording();
+      armAutoStop(elementEnd);
+    },
+    [
+      gestureRecording,
+      showToast,
+      previewIframeRef,
+      domEditSessionRef,
+      isGestureRecordingRef,
+      readOnlyPreview,
+      armAutoStop,
+    ],
+  );
+
+  const handleToggleRecording = useCallback(
+    (method: "button" | "keyboard" = "button") => {
+      if (commitInFlightRef.current) return;
+      if (gestureStateRef.current === "recording") {
+        if (readOnlyPreview) cancelRecording();
+        else void stopAndCommitRecording();
+        return;
       }
-    }, 100);
-  }, [
-    gestureRecording,
-    showToast,
-    stopAndCommitRecording,
-    cancelRecording,
-    previewIframeRef,
-    domEditSessionRef,
-    isGestureRecordingRef,
-    readOnlyPreview,
-  ]);
+      startRecording(method);
+    },
+    [cancelRecording, readOnlyPreview, startRecording, stopAndCommitRecording],
+  );
 
-  return { gestureState, gestureRecording, handleToggleRecording };
+  return useStableHandlers({ gestureState, gestureRecording, handleToggleRecording }, projectId);
 }

package/src/hooks/useGestureTrailOverlay.tsx

@@ -0,0 +1,33 @@
+import { useLayoutEffect, useRef } from "react";
+import { GestureTrailOverlay } from "../components/editor/GestureTrailOverlay";
+import type { UseGestureCommitResult } from "./useGestureCommit";
+
+/** The live gesture trail drawn over the preview while a gesture is recording, or nothing. */
+export function useGestureTrailOverlay(
+  {
+    gestureState,
+    gestureRecording,
+  }: Pick<UseGestureCommitResult, "gestureState" | "gestureRecording">,
+  previewIframe: HTMLIFrameElement | null,
+  compositionSize: { width: number; height: number } | null,
+) {
+  const canvasRectRef = useRef<DOMRect | null>(null);
+  useLayoutEffect(() => {
+    if (gestureState !== "recording" || !previewIframe) {
+      canvasRectRef.current = null;
+      return;
+    }
+    canvasRectRef.current = previewIframe.getBoundingClientRect();
+  }, [gestureState, previewIframe]);
+  if (gestureState !== "recording" || !previewIframe) return undefined;
+  return (
+    <GestureTrailOverlay
+      samples={gestureRecording.samplesRef.current}
+      sampleCount={gestureRecording.samplesRef.current.length}
+      trail={gestureRecording.trailRef.current}
+      canvasRect={canvasRectRef.current!}
+      compositionSize={compositionSize ?? undefined}
+      mode="recording"
+    />
+  );
+}

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -74,7 +74,7 @@ function mountResizeHandler(
         size: { width: number; height: number },
         offset?: { x: number; y: number },
         restore?: () => void,
-      ) => Promise<void>)
+      ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>)
     | null = null;
   let property: ReturnType<typeof useGsapAwareEditing>["commitAnimatedProperty"] | null = null;
   function Harness() {
@@ -131,13 +131,18 @@ function mountGroupHandler({
       "trackGsapInteractionFailure" | "stageElementPositionOffset" | "handleDomRotationCommit"
     >
   >) {
-  let groupCommit!: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
+  let groupCommit!: (
+    updates: DomEditGroupPathOffsetCommit[],
+  ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
   let pathOffsetCommit!: (
     selection: DomEditSelection,
     next: { x: number; y: number },
     route?: { plainTranslate?: boolean },
-  ) => Promise<void>;
-  let rotationCommit!: (selection: DomEditSelection, next: RotationCommit) => Promise<void>;
+  ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
+  let rotationCommit!: (
+    selection: DomEditSelection,
+    next: RotationCommit,
+  ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
   function Harness() {
     const editing = useGsapAwareEditing({
       domEditSelection: null,
@@ -589,7 +594,7 @@ describe("useGsapAwareEditing anchored resize", () => {
     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>;
+    let commit!: Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
     act(() => {
       commit = h.resize(h.selection, { width: 300, height: 200 }, { x: -50.2, y: -25.6 });
     });
@@ -636,7 +641,7 @@ describe("useGsapAwareEditing anchored resize", () => {
           s: DomEditSelection,
           m: unknown,
           o: { coalesceKey?: string; label?: string; softReload?: boolean },
-        ) => Promise<void>,
+        ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>,
         _fetch: unknown,
         options?: { preflightOnly?: boolean },
       ) => {