@hyperframes/studio 0.8.114 → 0.8.116

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,6 +11,8 @@ 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";
@@ -72,6 +74,7 @@ interface GestureSessionRef {
   commitMutation?: (
     mutation: Record<string, unknown>,
     options: CommitMutationOptions,
+    selection?: DomEditSelection,
   ) => Promise<void>;
 }
 
@@ -81,6 +84,12 @@ 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 {
@@ -95,7 +104,7 @@ interface UseGestureCommitParams {
 export interface UseGestureCommitResult {
   gestureState: "idle" | "recording";
   gestureRecording: ReturnType<typeof useGestureRecording>;
-  handleToggleRecording: () => void;
+  handleToggleRecording: (method?: "button" | "keyboard") => void;
 }
 
 // fallow-ignore-next-line complexity
@@ -111,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), []);
@@ -206,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,
@@ -216,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) =>
@@ -228,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,
@@ -237,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;
@@ -274,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,
@@ -286,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.
@@ -294,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,
@@ -320,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,
@@ -338,6 +355,7 @@ export function useGestureCommit({
             );
           }
         }
+        trackPreviewEditResult("gesture_recording", recordingMethodRef.current, outcome.finish());
       }
       showToast(`Recorded ${sortedPcts.length} keyframes`, "info");
     } catch (err) {
@@ -351,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 useStableHandlers({ gestureState, gestureRecording, handleToggleRecording }, projectId);
 }

package/src/hooks/useGroupCommits.ts

@@ -16,6 +16,7 @@ import {
   type ElementMatchSelection,
 } from "../utils/studioHelpers";
 import type { TimelineElement } from "../player";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseGroupCommitsParams extends DomEditCommitBaseParams {
   /** Resync the SDK session after a server-side write (the wrapper/unwrap changes
@@ -132,7 +133,7 @@ async function commitStructuralMutation(
     writeFile: deps.writeProjectFile,
     recordEdit: deps.editHistory.recordEdit,
     rewrite: async (originalContent) => {
-      const mutateResponse = await fetch(
+      const mutateResponse = await studioApiFetch(
         buildProjectApiPath(pid, `/file-mutations/${route}/${encodeURIComponent(targetPath)}`),
         {
           method: "POST",