@hyperframes/studio 0.7.54 → 0.7.56

package/src/hooks/useGsapKeyframeOps.ts

@@ -19,6 +19,7 @@ import {
 } from "./gsapKeyframeCacheHelpers";
 import type {
   CommitMutation,
+  CommitMutationOptions,
   SafeGsapCommitMutation,
   TrackGsapSaveFailure,
 } from "./gsapScriptCommitTypes";
@@ -54,6 +55,21 @@ interface GsapKeyframeOpsParams extends SdkKeyframeDeps {
   trackGsapSaveFailure: TrackGsapSaveFailure;
 }
 
+/**
+ * Translate a gesture's commit overrides into the SDK persist options. The
+ * server path's `softReload`/`skipReload` maps to the SDK's `skipRefresh`, and
+ * `coalesceKey`/`coalesceMs` must ride along so an SDK-routed edit folds into
+ * one undo entry the same way the server path does.
+ */
+function toSdkPersistOptions(label: string, overrides?: Partial<CommitMutationOptions>) {
+  return {
+    label,
+    coalesceKey: overrides?.coalesceKey,
+    coalesceMs: overrides?.coalesceMs,
+    skipRefresh: overrides?.skipReload,
+  };
+}
+
 export function useGsapKeyframeOps({
   activeCompPath,
   commitMutation,
@@ -140,6 +156,7 @@ export function useGsapKeyframeOps({
       animationId: string,
       percentage: number,
       properties: Record<string, number | string>,
+      commitOverrides?: Partial<CommitMutationOptions>,
     ) => {
       if (sdkSession && sdkDeps) {
         const sourceFile = selection.sourceFile || activeCompPath || "index.html";
@@ -150,21 +167,30 @@ export function useGsapKeyframeOps({
           properties,
           sdkSession,
           sdkDeps,
-          { label: `Add keyframe at ${percentage}%` },
+          toSdkPersistOptions(`Add keyframe at ${percentage}%`, commitOverrides),
         );
         if (handled) return;
       }
       return commitMutation(
         selection,
         { type: "add-keyframe", animationId, percentage, properties },
-        { label: `Add keyframe at ${percentage}%`, softReload: true },
+        {
+          label: `Add keyframe at ${percentage}%`,
+          softReload: true,
+          ...commitOverrides,
+        },
       );
     },
     [commitMutation, activeCompPath, sdkSession, sdkDeps],
   );
 
   const removeKeyframe = useCallback(
-    (selection: DomEditSelection, animationId: string, percentage: number) => {
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      percentage: number,
+      commitOverrides?: Partial<CommitMutationOptions>,
+    ) => {
       const sourceFile = selection.sourceFile || activeCompPath || "index.html";
       const mutation = { type: "remove-keyframe", animationId, percentage };
       void executeOptimisticKeyframeCacheUpdate({
@@ -182,6 +208,7 @@ export function useGsapKeyframeOps({
           ),
         }),
         persist: async () => {
+          const label = `Remove keyframe at ${percentage}%`;
           if (sdkSession && sdkDeps) {
             const handled = await sdkGsapRemoveKeyframePersist(
               sourceFile,
@@ -189,14 +216,14 @@ export function useGsapKeyframeOps({
               percentage,
               sdkSession,
               sdkDeps,
-              { label: `Remove keyframe at ${percentage}%` },
+              toSdkPersistOptions(label, commitOverrides),
             );
             if (handled) return;
           }
-          await commitMutation(selection, mutation, {
-            label: `Remove keyframe at ${percentage}%`,
-            softReload: true,
-          });
+          const commitOptions = commitOverrides?.skipReload
+            ? { label, ...commitOverrides }
+            : { label, softReload: true, ...commitOverrides };
+          await commitMutation(selection, mutation, commitOptions);
         },
       }).catch((error) => {
         trackGsapSaveFailure(error, selection, mutation, `Remove keyframe at ${percentage}%`);
@@ -261,6 +288,7 @@ export function useGsapKeyframeOps({
       animationId: string,
       resolvedFromValues?: Record<string, number | string>,
       duration?: number,
+      commitOverrides: Partial<CommitMutationOptions> = { softReload: true },
     ) => {
       if (sdkSession && sdkDeps) {
         const targetPath = selection.sourceFile || activeCompPath || "index.html";
@@ -270,7 +298,7 @@ export function useGsapKeyframeOps({
           resolvedFromValues,
           sdkSession,
           sdkDeps,
-          { label: "Convert to keyframes" },
+          toSdkPersistOptions("Convert to keyframes", commitOverrides),
         );
         if (handled) return;
       }
@@ -279,7 +307,7 @@ export function useGsapKeyframeOps({
         // `duration` only applies when the target is a static `set` (which has
         // none) — it spans the converted keyframes across the element's clip.
         { type: "convert-to-keyframes", animationId, resolvedFromValues, duration },
-        { label: "Convert to keyframes" },
+        { label: "Convert to keyframes", ...commitOverrides },
       );
     },
     [commitMutation, activeCompPath, sdkSession, sdkDeps],

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -217,6 +217,7 @@ let cleanup: (() => void) | null = null;
 function renderCommitHook() {
   const reloadPreview = vi.fn();
   const onCacheInvalidate = vi.fn();
+  const onFileContentChanged = vi.fn();
   const forceReloadSdkSession = vi.fn();
   const recordEdit = vi.fn(async () => {});
   const showToast = vi.fn();
@@ -231,7 +232,7 @@ function renderCommitHook() {
       domEditSaveTimestampRef: { current: 0 },
       reloadPreview,
       onCacheInvalidate,
-      onFileContentChanged: undefined,
+      onFileContentChanged,
       showToast,
       sdkSession: null,
       writeProjectFile: undefined,
@@ -252,6 +253,7 @@ function renderCommitHook() {
     api: hookApi,
     reloadPreview,
     onCacheInvalidate,
+    onFileContentChanged,
     forceReloadSdkSession,
     recordEdit,
     showToast,
@@ -383,4 +385,41 @@ describe("runCommit — instantPatch wiring", () => {
     expectSoftReloadedWith(deps.reloadPreview, "AFTER");
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
+
+  it("batch capability posts ordered mutations and finalizes the result once", async () => {
+    applySoftReload.mockReturnValue("applied");
+    mockFetchResult();
+    const deps = renderCommitHook();
+    const firstMutation = { type: "add", value: 1 };
+    const lastMutation = { type: "delete", value: 2 };
+    const batch = deps.api.commitMutation.batch;
+    if (!batch) throw new Error("batch capability missing");
+
+    await act(async () => {
+      await batch(
+        [
+          { selection, mutation: firstMutation, options: { label: "Resize", skipReload: true } },
+          { selection, mutation: lastMutation, options: { label: "Resize", softReload: true } },
+        ],
+        { label: "Resize", coalesceKey: "tx:resize:1", coalesceMs: Infinity, softReload: true },
+      );
+    });
+
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(fetch).toHaveBeenCalledWith(
+      "/api/projects/proj-1/gsap-mutations-batch/index.html",
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({ mutations: [firstMutation, lastMutation] }),
+      }),
+    );
+    expect(deps.recordEdit).toHaveBeenCalledTimes(1);
+    expect(deps.recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ label: "Resize", coalesceKey: "tx:resize:1" }),
+    );
+    expect(deps.onFileContentChanged).toHaveBeenCalledTimes(1);
+    expect(deps.forceReloadSdkSession).toHaveBeenCalledTimes(1);
+    expect(applySoftReload).toHaveBeenCalledTimes(1);
+    expect(deps.onCacheInvalidate).toHaveBeenCalledTimes(1);
+  });
 });

package/src/hooks/useGsapScriptCommits.ts

@@ -1,5 +1,6 @@
 import { useCallback, useMemo, useRef } from "react";
 import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mutation";
+import { readProjectFileContent as readSharedProjectFileContent } from "../utils/studioFileHistory";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { applySoftReload, extractGsapScriptText } from "../utils/gsapSoftReload";
@@ -15,6 +16,8 @@ import {
   readJsonResponseBody,
 } from "./gsapScriptCommitHelpers";
 import type {
+  CommitMutation,
+  CommitMutationCall,
   CommitMutationOptions,
   GsapScriptCommitsParams,
   MutationResult,
@@ -47,6 +50,76 @@ async function mutateGsapScript(
   return result;
 }
 
+async function mutateGsapScriptBatch(
+  projectId: string,
+  sourceFile: string,
+  mutations: Record<string, unknown>[],
+): Promise<MutationResult> {
+  const res = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations-batch/${encodeURIComponent(sourceFile)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ mutations }),
+    },
+  );
+  if (!res.ok) throw new GsapMutationHttpError(res.status, await readJsonResponseBody(res));
+  const result = (await res.json()) as MutationResult;
+  if (!result.ok) throw new Error(`Failed to update GSAP in ${sourceFile}`);
+  return result;
+}
+
+type ShowToast = (message: string, tone?: "error" | "info") => void;
+
+async function runMutationRequest(
+  mutations: Record<string, unknown>[],
+  options: CommitMutationOptions,
+  showToast: ShowToast | undefined,
+  request: () => Promise<MutationResult>,
+): Promise<MutationResult | undefined> {
+  const unsafeFields = mutations.flatMap((mutation) => findUnsafeMutationValues(mutation));
+  if (unsafeFields.length > 0) {
+    showToast?.("Couldn't read element layout — try again at a different playhead time", "error");
+    if (options.skipReload) return;
+    throw new Error(
+      `Mutation contains unsafe values: ${unsafeFields.map((field) => field.path).join(", ")}`,
+    );
+  }
+  try {
+    return await request();
+  } catch (error) {
+    if (error instanceof GsapMutationHttpError)
+      showToast?.(formatGsapMutationRejectionToast(error), "error");
+    if (options.skipReload) return;
+    throw error;
+  }
+}
+
+function finishUnchangedMutation(
+  iframe: HTMLIFrameElement | null,
+  result: MutationResult,
+  options: CommitMutationOptions,
+  reloadPreview: () => void,
+): boolean {
+  if (result.changed !== false) return false;
+  if (!options.skipReload && options.instantPatch) {
+    applyPreviewSync(iframe, result, options, reloadPreview);
+  }
+  return true;
+}
+
+function refreshMutationPreview(
+  iframe: HTMLIFrameElement | null,
+  result: MutationResult,
+  options: CommitMutationOptions,
+  reloadPreview: () => void,
+  onCacheInvalidate: () => void,
+): void {
+  options.beforeReload?.();
+  applyPreviewSync(iframe, result, options, reloadPreview);
+  onCacheInvalidate();
+}
+
 /**
  * Apply a soft reload and enforce the U4 invariant via the richer
  * `SoftReloadResult`, with telemetry on every non-success path so the invariant
@@ -141,63 +214,78 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
   // the same animationId so their POSTs can't interleave. Held in a ref so the
   // chain survives re-renders.
   const serializerRef = useRef(createKeyedSerializer());
-  // fallow-ignore-next-line complexity
-  const runCommit = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
-    const pid = projectIdRef.current;
-    if (!pid) return;
-    const unsafeFields = findUnsafeMutationValues(mutation);
-    if (unsafeFields.length > 0) {
-      showToast?.("Couldn't read element layout — try again at a different playhead time", "error");
-      if (options.skipReload) return;
-      throw new Error(`Mutation contains unsafe values: ${unsafeFields.map((field) => field.path).join(", ")}`);
-    }
-    const targetPath = selection.sourceFile || activeCompPath || "index.html";
-    let result: MutationResult;
-    try {
-      result = await mutateGsapScript(pid, targetPath, mutation);
-    } catch (error) {
-      if (error instanceof GsapMutationHttpError) showToast?.(formatGsapMutationRejectionToast(error), "error");
-      if (options.skipReload) return;
-      throw error;
-    }
-    if (result.changed === false) {
-      // The FILE already matched, but a deferred instant patch may still be
-      // owed to the RUNTIME: paired commits (x with skipReload, then y carrying
-      // the patch for both) rely on the SECOND commit to sync the preview — if
-      // that half happens to be a no-op (a purely-horizontal drag or resize
-      // compensation), returning here would leave the runtime showing the old
-      // value while the file holds the new one. Patching in place is idempotent
-      // when the values truly match everywhere.
-      if (!options.skipReload && options.instantPatch) {
-        applyPreviewSync(previewIframeRef.current, result, options, reloadPreview);
-      }
-      return;
-    }
+  const recordMutationEdit = useCallback(async (targetPath: string, result: MutationResult, options: CommitMutationOptions) => {
+    if (result.before == null || result.after == null) return;
+    await editHistory.recordEdit({
+      label: options.label,
+      kind: "manual",
+      coalesceKey: options.coalesceKey,
+      coalesceMs: options.coalesceMs,
+      files: { [targetPath]: { before: result.before, after: result.after } },
+    });
+  }, [editHistory]);
+
+  const finalizeSuccessfulMutation = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, targetPath: string, result: MutationResult, options: CommitMutationOptions) => {
+    // A no-op file write may still owe the runtime a deferred instant patch.
+    if (finishUnchangedMutation(previewIframeRef.current, result, options, reloadPreview)) return;
     domEditSaveTimestampRef.current = Date.now();
-    if (result.before != null && result.after != null) {
-      await editHistory.recordEdit({ label: options.label, kind: "manual", coalesceKey: options.coalesceKey, files: { [targetPath]: { before: result.before, after: result.after } } });
-    }
+    await recordMutationEdit(targetPath, result, options);
     if (result.after != null) onFileContentChanged?.(targetPath, result.after);
     // Server wrote the file; the in-memory SDK doc is now stale. Resync it so a
     // later SDK-routed edit doesn't serialize the pre-write doc and revert this.
     forceReloadSdkSession?.();
     if (options.skipReload) return;
     if (result.parsed?.animations) updateKeyframeCacheFromParsed(result.parsed.animations, targetPath, selection.id ?? undefined, mutation);
-    options.beforeReload?.();
-    applyPreviewSync(previewIframeRef.current, result, options, reloadPreview);
-    onCacheInvalidate();
-  }, [projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, forceReloadSdkSession]);
+    refreshMutationPreview(
+      previewIframeRef.current,
+      result,
+      options,
+      reloadPreview,
+      onCacheInvalidate,
+    );
+  }, [previewIframeRef, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, forceReloadSdkSession, recordMutationEdit]);
+
+  const runCommit = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+    const pid = projectIdRef.current;
+    if (!pid) return;
+    const targetPath = selection.sourceFile || activeCompPath || "index.html";
+    const result = await runMutationRequest([mutation], options, showToast, () =>
+      mutateGsapScript(pid, targetPath, mutation),
+    );
+    if (!result) return;
+    await finalizeSuccessfulMutation(selection, mutation, targetPath, result, options);
+  }, [projectIdRef, activeCompPath, showToast, finalizeSuccessfulMutation]);
+
+  const runBatchCommit = useCallback(async (calls: CommitMutationCall[], options: CommitMutationOptions) => {
+    const pid = projectIdRef.current;
+    const first = calls[0];
+    const last = calls.at(-1);
+    if (!pid || !first || !last) return;
+    const targetPath = first.selection.sourceFile || activeCompPath || "index.html";
+    const mutations = calls.map(({ mutation }) => mutation);
+    const result = await runMutationRequest(mutations, options, showToast, () =>
+      mutateGsapScriptBatch(pid, targetPath, mutations),
+    );
+    if (!result) return;
+    await finalizeSuccessfulMutation(last.selection, last.mutation, targetPath, result, options);
+  }, [projectIdRef, activeCompPath, showToast, finalizeSuccessfulMutation]);
+
   // Every GSAP-script commit is a read-modify-write of one file. Overlapping
   // commits to the SAME file (any op type, any animation) interleave server-side,
   // so serialize per target file by default; an explicit serializeKey overrides.
-  const commitMutation = useCallback(
-    (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+  const commitMutation = useMemo<CommitMutation>(() => {
+    const commit: CommitMutation = (selection, mutation, options) => {
       const file = selection.sourceFile || activeCompPath || "index.html";
       const key = options.serializeKey ?? `gsap-file:${file}`;
       return serializerRef.current(key, () => runCommit(selection, mutation, options));
-    },
-    [runCommit, activeCompPath],
-  );
+    };
+    commit.batch = (calls, options) => {
+      const file = calls[0]?.selection.sourceFile || activeCompPath || "index.html";
+      const key = options.serializeKey ?? `gsap-file:${file}`;
+      return serializerRef.current(key, () => runBatchCommit(calls, options));
+    };
+    return commit;
+  }, [runCommit, runBatchCommit, activeCompPath]);
   const trackGsapSaveFailure = useGsapSaveFailureTelemetry(activeCompPath);
   const commitMutationSafely = useSafeGsapCommitMutation(commitMutation, trackGsapSaveFailure, showToast);
 
@@ -238,14 +326,10 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
   // exact prior content as its undo `before` (matching the style/delete paths),
   // instead of a normalized full-DOM re-emit that would reformat the whole file.
   const readProjectFileContent = useCallback(
-    async (path: string): Promise<string> => {
+    (path: string): Promise<string> => {
       const pid = projectIdRef.current;
       if (!pid) throw new Error("No active project");
-      const res = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
-      if (!res.ok) throw new Error(`Failed to read ${path}`);
-      const data = (await res.json()) as { content?: string };
-      if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
-      return data.content;
+      return readSharedProjectFileContent(pid, path);
     },
     [projectIdRef],
   );

package/src/hooks/useGsapSelectionHandlers.ts

@@ -5,6 +5,7 @@ import { usePlayerStore } from "../player";
 import { computeCurrentPercentage } from "./gsapDragCommit";
 import { trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
 
 /**
  * Thin useCallback wrappers that guard on `domEditSelection` before
@@ -75,8 +76,14 @@ export function useGsapSelectionHandlers({
     animId: string,
     percentage: number,
     properties: Record<string, number | string>,
+    commitOverrides?: Partial<CommitMutationOptions>,
   ) => Promise<void>;
-  removeKeyframe: (sel: DomEditSelection, animId: string, percentage: number) => void;
+  removeKeyframe: (
+    sel: DomEditSelection,
+    animId: string,
+    percentage: number,
+    commitOverrides?: Partial<CommitMutationOptions>,
+  ) => void;
   moveKeyframe: (
     sel: DomEditSelection,
     animId: string,
@@ -95,6 +102,7 @@ export function useGsapSelectionHandlers({
     animId: string,
     resolvedFromValues?: Record<string, number | string>,
     duration?: number,
+    commitOverrides?: Partial<CommitMutationOptions>,
   ) => Promise<void>;
   removeAllKeyframes: (sel: DomEditSelection, animId: string) => void;
 
@@ -232,20 +240,36 @@ export function useGsapSelectionHandlers({
   );
 
   const handleGsapAddKeyframeBatch = useCallback(
-    (animId: string, percentage: number, properties: Record<string, number | string>) => {
+    (
+      animId: string,
+      percentage: number,
+      properties: Record<string, number | string>,
+      commitOverrides?: Partial<CommitMutationOptions>,
+    ) => {
       if (!domEditSelection) return Promise.resolve();
-      return addKeyframeBatch(domEditSelection, animId, percentage, properties).catch((error) => {
+      return addKeyframeBatch(
+        domEditSelection,
+        animId,
+        percentage,
+        properties,
+        commitOverrides,
+      ).catch((error) => {
         trackGsapHandlerFailure(error, domEditSelection, "add-keyframe", "Add keyframe");
       });
     },
     [domEditSelection, addKeyframeBatch, trackGsapHandlerFailure],
   );
   const handleGsapRemoveKeyframe = useCallback(
-    (animId: string, percentage: number, selectionOverride?: DomEditSelection | null) => {
+    (
+      animId: string,
+      percentage: number,
+      commitOverrides?: Partial<CommitMutationOptions>,
+      selectionOverride?: DomEditSelection | null,
+    ) => {
       const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
       if (!sel) return;
       trackStudioEvent("keyframe", { action: "remove" });
-      removeKeyframe(sel, animId, percentage);
+      removeKeyframe(sel, animId, percentage, commitOverrides);
     },
     [domEditSelection, removeKeyframe],
   );
@@ -302,18 +326,27 @@ export function useGsapSelectionHandlers({
   );
 
   const handleGsapConvertToKeyframes = useCallback(
-    (animId: string, resolvedFromValues?: Record<string, number | string>, duration?: number) => {
+    (
+      animId: string,
+      resolvedFromValues?: Record<string, number | string>,
+      duration?: number,
+      commitOverrides?: Partial<CommitMutationOptions>,
+    ) => {
       if (!domEditSelection) return Promise.resolve();
-      return convertToKeyframes(domEditSelection, animId, resolvedFromValues, duration).catch(
-        (error) => {
-          trackGsapHandlerFailure(
-            error,
-            domEditSelection,
-            "convert-to-keyframes",
-            "Convert to keyframes",
-          );
-        },
-      );
+      return convertToKeyframes(
+        domEditSelection,
+        animId,
+        resolvedFromValues,
+        duration,
+        commitOverrides,
+      ).catch((error) => {
+        trackGsapHandlerFailure(
+          error,
+          domEditSelection,
+          "convert-to-keyframes",
+          "Convert to keyframes",
+        );
+      });
     },
     [domEditSelection, convertToKeyframes, trackGsapHandlerFailure],
   );