@hyperframes/studio 0.8.114 → 0.8.115

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/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 },
       ) => {