@hyperframes/studio 0.7.55 → 0.7.57

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],
   );

package/src/hooks/useMusicBeatAnalysis.ts

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useRef } from "react";
 import { usePlayerStore } from "../player/store/playerStore";
-import { isMusicTrack } from "../utils/timelineInspector";
+import { resolveBeatSourceTrack } from "../utils/timelineInspector";
 import { analyzeMusicFromUrl } from "@hyperframes/core/beats";
 import { useFileManagerContextOptional } from "../contexts/FileManagerContext";
 import { mergeUserBeats } from "../utils/beatEditing";
@@ -52,6 +52,44 @@ async function resolveBeats(
   return { ...detected, hasFile: false };
 }
 
+/** True when the beats file for a track exists and holds at least one beat. */
+async function readHasSavedBeats(io: ProjectIo, beatPath: string): Promise<boolean> {
+  try {
+    const content = await io.readOptionalProjectFile(beatPath);
+    const parsed = content ? parseBeats(content) : null;
+    return !!(parsed && parsed.times.length > 0);
+  } catch {
+    return false;
+  }
+}
+
+type MusicAnalysis = Awaited<ReturnType<typeof analyzeMusicFromUrl>>;
+
+/**
+ * Analyze a track (memoized per URL) and fold in any saved beat edits. Null on
+ * decode/analysis failure — the caller then clears state and drops the cache
+ * entry (only when the effect is still live).
+ */
+async function loadBeatAnalysis(
+  musicSrc: string,
+  beatPath: string,
+  io: ProjectIo,
+): Promise<{ analysis: MusicAnalysis; times: number[]; strengths: number[] } | null> {
+  let promise = analysisCache.get(musicSrc);
+  if (!promise) {
+    promise = analyzeMusicFromUrl(musicSrc);
+    cacheAnalysis(musicSrc, promise);
+  }
+  try {
+    const analysis = await promise;
+    const detected = { times: analysis.beatTimes, strengths: analysis.beatStrengths };
+    const { times, strengths } = await resolveBeats(beatPath, detected, io);
+    return { analysis, times, strengths };
+  } catch {
+    return null;
+  }
+}
+
 export function useMusicBeatAnalysis(): void {
   const elements = usePlayerStore((s) => s.elements);
   const setBeatAnalysis = usePlayerStore((s) => s.setBeatAnalysis);
@@ -71,9 +109,12 @@ export function useMusicBeatAnalysis(): void {
       ? { readOptionalProjectFile, writeProjectFile }
       : null;
 
-  const musicSrc = useMemo(() => {
-    const el = elements.find((e) => isMusicTrack(e));
-    return el?.src ?? null;
+  const { musicSrc, isFallbackTrack } = useMemo(() => {
+    const resolved = resolveBeatSourceTrack(elements);
+    return {
+      musicSrc: resolved?.element.src ?? null,
+      isFallbackTrack: resolved?.isFallback ?? false,
+    };
   }, [elements]);
 
   // ── Load: decode for strength data, then use the saved beat file if present,
@@ -95,50 +136,45 @@ export function useMusicBeatAnalysis(): void {
     const beatPath = beatFilePathForSrc(musicSrc);
     const io = ioRef.current;
 
-    // Only run expensive audio decode + beat analysis when the user has an
-    // explicit beats file saved. Without one, skip entirely — no surprise
-    // green lines on the timeline after dragging unrelated assets.
+    // For explicitly tagged/named music tracks: only run expensive audio decode
+    // + beat analysis when the user has an explicit beats file saved. Without
+    // one, skip entirely — no surprise green lines on the timeline after
+    // dragging unrelated assets.
+    //
+    // For fallback tracks (audio dropped from Finder with no role/music-id):
+    // always run analysis so the Beat tool becomes usable immediately.
     (async () => {
       if (!beatPath || !io) return;
-      let hasSavedBeats = false;
-      try {
-        const content = await io.readOptionalProjectFile(beatPath);
-        const parsed = content ? parseBeats(content) : null;
-        hasSavedBeats = !!(parsed && parsed.times.length > 0);
-      } catch {
-        /* no file */
+      if (!isFallbackTrack) {
+        const hasSavedBeats = await readHasSavedBeats(io, beatPath);
+        if (cancelled) return;
+        if (!hasSavedBeats) {
+          setBeatAnalysis(null);
+          return;
+        }
       }
       if (cancelled) return;
-      if (!hasSavedBeats) {
+
+      const result = await loadBeatAnalysis(musicSrc, beatPath, io);
+      if (cancelled) return;
+      if (!result) {
         setBeatAnalysis(null);
+        analysisCache.delete(musicSrc);
         return;
       }
-
-      let promise = analysisCache.get(musicSrc);
-      if (!promise) {
-        promise = analyzeMusicFromUrl(musicSrc);
-        cacheAnalysis(musicSrc, promise);
-      }
-      try {
-        const analysis = await promise;
-        const detected = { times: analysis.beatTimes, strengths: analysis.beatStrengths };
-        const { times, strengths } = await resolveBeats(beatPath, detected, io);
-        if (cancelled) return;
-        setBeatEdits(null);
-        resetBeatHistory();
-        setBeatAnalysis({ ...analysis, beatTimes: times, beatStrengths: strengths });
-      } catch {
-        if (!cancelled) {
-          setBeatAnalysis(null);
-          analysisCache.delete(musicSrc);
-        }
-      }
+      setBeatEdits(null);
+      resetBeatHistory();
+      setBeatAnalysis({
+        ...result.analysis,
+        beatTimes: result.times,
+        beatStrengths: result.strengths,
+      });
     })();
 
     return () => {
       cancelled = true;
     };
-  }, [musicSrc, setBeatAnalysis, setBeatEdits, resetBeatHistory]);
+  }, [musicSrc, isFallbackTrack, setBeatAnalysis, setBeatEdits, resetBeatHistory]);
 
   // ── Persist: register a debounced writer fired by every beat edit/undo/redo.
   //    Flushes any pending write on cleanup so the last edit is never lost. ──

package/src/hooks/usePersistentEditHistory.test.ts

@@ -213,6 +213,39 @@ describe("createPersistentEditHistoryController", () => {
     expect(store.snapshot().canRedo).toBe(true);
   });
 
+  it("returns per-file restored/previous content so the preview can soft-apply", async () => {
+    const storage = createMemoryEditHistoryStorage();
+    const store = createPersistentEditHistoryStore({
+      projectId: "project-1",
+      storage,
+      initialState: createEmptyEditHistory(),
+      now: () => 100,
+      onChange: () => {},
+    });
+    await store.recordEdit({
+      label: "Move layer",
+      kind: "manual",
+      files: { "index.html": { before: "OLD", after: "NEW" } },
+    });
+    const disk: Record<string, string> = { "index.html": "NEW" };
+    const undo = await store.undo({
+      readFile: async (p) => disk[p],
+      writeFile: async (p, c) => {
+        disk[p] = c;
+      },
+    });
+    // `restored` = bytes written (the undo target), `previous` = the current live bytes.
+    expect(undo.files).toEqual({ "index.html": { previous: "NEW", restored: "OLD" } });
+
+    const redo = await store.redo({
+      readFile: async (p) => disk[p],
+      writeFile: async (p, c) => {
+        disk[p] = c;
+      },
+    });
+    expect(redo.files).toEqual({ "index.html": { previous: "OLD", restored: "NEW" } });
+  });
+
   it("rolls back files when an undo write fails partway through", async () => {
     const storage = createMemoryEditHistoryStorage();
     const store = createPersistentEditHistoryStore({