@hyperframes/studio 0.7.54 → 0.7.56

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({

package/src/hooks/usePersistentEditHistory.ts

@@ -7,8 +7,10 @@ import {
   redoEditHistory,
   undoEditHistory,
   type BuildEditHistoryEntryInput,
+  type EditHistoryEntry,
   type EditHistoryKind,
   type EditHistoryState,
+  type EditHistoryTransitionResult,
 } from "../utils/editHistory";
 import {
   createIndexedDbEditHistoryStorage,
@@ -21,6 +23,7 @@ interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
   coalesceKey?: string;
+  coalesceMs?: number;
   files: BuildEditHistoryEntryInput["files"];
 }
 
@@ -35,11 +38,24 @@ interface UsePersistentEditHistoryOptions {
   now?: () => number;
 }
 
+/**
+ * Per-file content the restore just applied. `restored` is the bytes written to
+ * disk (the undo/redo target); `previous` is what was on disk immediately before
+ * (the current live preview state). The undo preview-sync diffs these to decide
+ * whether the restore is soft-reloadable (attributes/style/GSAP-script only) or
+ * needs a full iframe reload.
+ */
+interface ApplyRestoredFile {
+  previous: string;
+  restored: string;
+}
+
 interface ApplyResult {
   ok: boolean;
   reason?: "empty" | "content-mismatch";
   label?: string;
   paths?: string[];
+  files?: Record<string, ApplyRestoredFile>;
 }
 
 interface PersistentEditHistoryStoreOptions {
@@ -55,6 +71,18 @@ type EditHistoryMutation<T> = (state: EditHistoryState) => Promise<{
   result: T;
 }>;
 
+/** Pair the just-written (`restored`) bytes with the pre-write (`previous`) bytes per path. */
+function restoredFilesMap(
+  filesToWrite: Record<string, string>,
+  currentFiles: Record<string, string>,
+): Record<string, ApplyRestoredFile> {
+  const out: Record<string, ApplyRestoredFile> = {};
+  for (const [path, restored] of Object.entries(filesToWrite)) {
+    out[path] = { previous: currentFiles[path] ?? "", restored };
+  }
+  return out;
+}
+
 function createEntryId(now: number): string {
   return `edit-${now.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -120,6 +148,52 @@ async function writeFilesWithRollback({
   }
 }
 
+/**
+ * Apply one undo/redo step: read current on-disk hashes, run the direction's
+ * transition, write the restored files with rollback, and shape the ApplyResult.
+ * `entry` is the stack top used to know which paths to hash before applying.
+ */
+async function applyHistoryStep(
+  currentState: EditHistoryState,
+  entry: EditHistoryEntry | undefined,
+  transition: (
+    state: EditHistoryState,
+    currentHashes: Record<string, string>,
+    now: number,
+  ) => EditHistoryTransitionResult,
+  now: () => number,
+  callbacks: ApplyCallbacks,
+): Promise<{ state: EditHistoryState; result: ApplyResult }> {
+  if (!entry) {
+    return { state: currentState, result: { ok: false, reason: "empty" } };
+  }
+  const { currentFiles, currentHashes } = await readCurrentFileHashes(
+    Object.keys(entry.files),
+    callbacks.readFile,
+  );
+  const result = transition(currentState, currentHashes, now());
+  if (!result.ok) {
+    return {
+      state: currentState,
+      result: { ok: false, reason: result.reason },
+    };
+  }
+  await writeFilesWithRollback({
+    files: result.filesToWrite,
+    rollbackFiles: currentFiles,
+    writeFile: callbacks.writeFile,
+  });
+  return {
+    state: result.state,
+    result: {
+      ok: true,
+      label: result.entry.label,
+      paths: Object.keys(result.entry.files),
+      files: restoredFilesMap(result.filesToWrite, currentFiles),
+    },
+  };
+}
+
 export function createPersistentEditHistoryStore({
   projectId,
   storage,
@@ -171,66 +245,26 @@ export function createPersistentEditHistoryStore({
       });
     },
     async undo(callbacks: ApplyCallbacks): Promise<ApplyResult> {
-      return mutate<ApplyResult>(async (currentState) => {
-        const entry = currentState.undo[currentState.undo.length - 1];
-        if (!entry) {
-          return {
-            state: currentState,
-            result: { ok: false, reason: "empty" },
-          };
-        }
-        const { currentFiles, currentHashes } = await readCurrentFileHashes(
-          Object.keys(entry.files),
-          callbacks.readFile,
-        );
-        const result = undoEditHistory(currentState, currentHashes, now());
-        if (!result.ok) {
-          return {
-            state: currentState,
-            result: { ok: false, reason: result.reason },
-          };
-        }
-        await writeFilesWithRollback({
-          files: result.filesToWrite,
-          rollbackFiles: currentFiles,
-          writeFile: callbacks.writeFile,
-        });
-        return {
-          state: result.state,
-          result: { ok: true, label: result.entry.label, paths: Object.keys(result.entry.files) },
-        };
-      });
+      return mutate<ApplyResult>((currentState) =>
+        applyHistoryStep(
+          currentState,
+          currentState.undo[currentState.undo.length - 1],
+          undoEditHistory,
+          now,
+          callbacks,
+        ),
+      );
     },
     async redo(callbacks: ApplyCallbacks): Promise<ApplyResult> {
-      return mutate<ApplyResult>(async (currentState) => {
-        const entry = currentState.redo[currentState.redo.length - 1];
-        if (!entry) {
-          return {
-            state: currentState,
-            result: { ok: false, reason: "empty" },
-          };
-        }
-        const { currentFiles, currentHashes } = await readCurrentFileHashes(
-          Object.keys(entry.files),
-          callbacks.readFile,
-        );
-        const result = redoEditHistory(currentState, currentHashes, now());
-        if (!result.ok) {
-          return {
-            state: currentState,
-            result: { ok: false, reason: result.reason },
-          };
-        }
-        await writeFilesWithRollback({
-          files: result.filesToWrite,
-          rollbackFiles: currentFiles,
-          writeFile: callbacks.writeFile,
-        });
-        return {
-          state: result.state,
-          result: { ok: true, label: result.entry.label, paths: Object.keys(result.entry.files) },
-        };
-      });
+      return mutate<ApplyResult>((currentState) =>
+        applyHistoryStep(
+          currentState,
+          currentState.redo[currentState.redo.length - 1],
+          redoEditHistory,
+          now,
+          callbacks,
+        ),
+      );
     },
   };
 }

package/src/hooks/usePreviewPersistence.ts

@@ -10,6 +10,14 @@ import type { EditHistoryKind } from "../utils/editHistory";
 import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
 import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { applyUndoRestoreToPreview, type UndoRestoreFile } from "../utils/gsapSoftReload";
+import { usePlayerStore } from "../player";
+
+/** The restore payload the undo/redo preview-sync consumes (from the history store). */
+interface HistoryPreviewRestore {
+  paths?: string[];
+  files?: Record<string, UndoRestoreFile>;
+}
 
 // ── Types ──
 
@@ -105,13 +113,12 @@ export function usePreviewPersistence({
   writeProjectFile: _writeProjectFile,
   recordEdit: _recordEdit,
   previewIframeRef,
-  activeCompPathRef: _activeCompPathRef,
+  activeCompPathRef,
   domEditSaveTimestampRef,
   reloadPreview,
   pendingTimelineEditPathRef,
 }: UsePreviewPersistenceParams) {
   void _recordEdit;
-  void _activeCompPathRef;
 
   const [domEditSaveQueuePaused, setDomEditSaveQueuePaused] = useState<string | null>(null);
 
@@ -190,12 +197,23 @@ export function usePreviewPersistence({
   // ── Sync preview after undo/redo ──
 
   const syncHistoryPreviewAfterApply = useCallback(
-    async (_paths: string[] | undefined) => {
-      // Motion data is now stored in HTML attributes — any undo/redo that touches HTML
-      // files triggers a full reload which picks up the changes automatically.
-      reloadPreview();
+    async (restore: HistoryPreviewRestore) => {
+      // Prefer an in-place soft reload for a soft-reloadable restore (the change
+      // is confined to the active comp's element attributes / inline-style and/or
+      // its GSAP script) — a full iframe remount blanks the frame black and
+      // re-flashes the WebGL context. applyUndoRestoreToPreview syncs the reverted
+      // attributes onto the live DOM and re-runs the timeline at the SAME playhead,
+      // falling back to reloadPreview for anything structural (split/delete undo),
+      // multi-file, sub-comp, or a permanent soft-reload failure.
+      applyUndoRestoreToPreview(
+        previewIframeRef.current,
+        activeCompPathRef.current,
+        restore.files,
+        usePlayerStore.getState().currentTime,
+        reloadPreview,
+      );
     },
-    [reloadPreview],
+    [previewIframeRef, activeCompPathRef, reloadPreview],
   );
 
   // ── Migrate legacy studio-motion.json ──