@hyperframes/studio 0.8.50 → 0.8.53-desktop.0

package/src/hooks/useAppHotkeys.textEditing.test.tsx

@@ -5,7 +5,6 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { TextAreaField } from "../components/editor/propertyPanelSections";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
 import { usePlayerStore } from "../player/store/playerStore";
 import { useAppHotkeys } from "./useAppHotkeys";
 
@@ -70,7 +69,6 @@ function Harness() {
   const [selectionRefreshed, setSelectionRefreshed] = useState(false);
   const selectionRef = useRef<DomEditSelection | null>(parentWithTextChild());
   const clearSelectionRef = useRef<() => void>(() => undefined);
-  const leftSidebarRef = useRef<LeftSidebarHandle | null>(null);
 
   useAppHotkeys({
     handleTimelineElementsDelete: timelineDeleteMany,
@@ -89,7 +87,6 @@ function Harness() {
     showToast: vi.fn(),
     syncHistoryPreviewAfterApply: vi.fn(async () => undefined),
     waitForPendingDomEditSaves: vi.fn(async () => undefined),
-    leftSidebarRef,
     handleCopy: vi.fn(() => false),
     handlePaste: vi.fn(async () => undefined),
     handleCut: vi.fn(async () => false),

package/src/hooks/useAppHotkeys.ts

@@ -2,8 +2,6 @@ import { useCallback, useEffect, useRef } from "react";
 import { usePlayerStore } from "../player";
 import type { TimelineElement } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
-import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import { isTypingTarget } from "../utils/typingTarget";
 import { useCaptionStore } from "../captions/store";
 import {
@@ -11,13 +9,17 @@ import {
   isCaptionPreviewVisible,
 } from "../captions/components/CaptionOverlayUtils";
 import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
-import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
 import {
   type HotkeyCallbacks,
   dispatchModifierKey,
   dispatchPlainKey,
   handleUndoRedoKey,
 } from "./appHotkeysDispatch";
+import {
+  useEditHistoryActions,
+  type EditHistoryHandle,
+  type UseEditHistoryActionsOptions,
+} from "./useEditHistoryActions";
 
 function iframeContentWindow(iframe: HTMLIFrameElement | null): Window | null {
   try {
@@ -69,28 +71,6 @@ function tryApplyBeatHistory(
 
 // ── Types ──
 
-interface HistoryResult {
-  ok: boolean;
-  reason?: string;
-  label?: string;
-  paths?: string[];
-  /** Per-file restored/previous content, used to soft-apply the preview. */
-  files?: Record<string, { previous: string; restored: string }>;
-}
-interface HistoryFileCallbacks {
-  readFile: (path: string) => Promise<string>;
-  writeFile: (path: string, content: string) => Promise<void>;
-  serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
-}
-interface EditHistoryHandle {
-  undo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
-  redo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
-  state: {
-    undo: ReadonlyArray<{ createdAt: number }>;
-    redo: ReadonlyArray<{ createdAt: number }>;
-  };
-}
-
 interface UseAppHotkeysParams {
   handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;
@@ -105,12 +85,8 @@ interface UseAppHotkeysParams {
   readProjectFile: (path: string) => Promise<string>;
   writeProjectFile: (path: string, content: string) => Promise<void>;
   showToast: (message: string, tone?: "error" | "info") => void;
-  syncHistoryPreviewAfterApply: (restore: {
-    paths?: string[];
-    files?: Record<string, { previous: string; restored: string }>;
-  }) => Promise<void>;
+  syncHistoryPreviewAfterApply: UseEditHistoryActionsOptions["syncHistoryPreviewAfterApply"];
   waitForPendingDomEditSaves: () => Promise<void>;
-  leftSidebarRef: React.RefObject<LeftSidebarHandle | null>;
   handleCopy: () => boolean;
   handlePaste: () => Promise<void>;
   handleCut: () => Promise<boolean>;
@@ -147,7 +123,6 @@ export function useAppHotkeys({
   showToast,
   syncHistoryPreviewAfterApply,
   waitForPendingDomEditSaves,
-  leftSidebarRef,
   handleCopy,
   handlePaste,
   handleCut,
@@ -165,22 +140,18 @@ export function useAppHotkeys({
 
   // ── Undo / Redo ──
 
-  const readHistoryFile = useCallback(
-    (path: string): Promise<string> =>
-      path === STUDIO_MOTION_PATH ? readOptionalProjectFile(path) : readProjectFile(path),
-    [readOptionalProjectFile, readProjectFile],
-  );
-  const writeHistoryFile = useCallback(
-    async (path: string, content: string): Promise<void> => {
-      await writeProjectFile(path, content);
-    },
-    [writeProjectFile],
-  );
-  const serializeHistoryFiles = useCallback(
-    <T>(paths: readonly string[], task: () => Promise<T>) =>
-      serializeStudioFileMutations(writeProjectFile, paths, task),
-    [writeProjectFile],
-  );
+  const fileHistory = useEditHistoryActions({
+    editHistory,
+    readOptionalProjectFile,
+    readProjectFile,
+    writeProjectFile,
+    showToast,
+    syncHistoryPreviewAfterApply,
+    waitForPendingDomEditSaves,
+    onAfterUndoRedo,
+    activeCompPath,
+    forceReloadSdkSession,
+  });
 
   const applyHistory = useCallback(
     async (direction: "undo" | "redo") => {
@@ -189,7 +160,7 @@ export function useAppHotkeys({
       // earlier file edit (which would ALSO leave the caption change intact).
       const captionState = useCaptionStore.getState();
       // Only when the caption preview is actually visible: isEditMode stays
-      // true while the preview is hidden (storyboard view), and eating ⌘Z
+      // true while the preview is hidden, and eating ⌘Z
       // there would pop invisible caption edits instead of file history.
       if (captionState.isEditMode && isCaptionPreviewVisible()) {
         const restored = direction === "undo" ? captionState.undo() : captionState.redo();
@@ -204,42 +175,9 @@ export function useAppHotkeys({
       // Beat edits interleave with file history by timestamp; handle them first.
       if (tryApplyBeatHistory(direction, editHistory.state, showToast)) return;
 
-      await waitForPendingDomEditSaves();
-      const result = await editHistory[direction]({
-        readFile: readHistoryFile,
-        writeFile: writeHistoryFile,
-        serialize: serializeHistoryFiles,
-      });
-      if (!result.ok && result.reason === "content-mismatch") {
-        showToast(
-          `File changed outside Studio. ${direction === "undo" ? "Undo" : "Redo"} history was not applied.`,
-          "info",
-        );
-        return;
-      }
-      if (result.ok && result.label) {
-        onAfterUndoRedo?.();
-        // If the active composition was among the written files, force-reload
-        // the SDK session so its in-memory doc matches the reverted content.
-        if (activeCompPath && result.paths?.includes(activeCompPath)) {
-          forceReloadSdkSession?.();
-        }
-        await syncHistoryPreviewAfterApply({ paths: result.paths, files: result.files });
-        showToast(`${direction === "undo" ? "Undid" : "Redid"} ${result.label}`, "info");
-      }
+      await fileHistory[direction]();
     },
-    [
-      editHistory,
-      readHistoryFile,
-      showToast,
-      syncHistoryPreviewAfterApply,
-      waitForPendingDomEditSaves,
-      writeHistoryFile,
-      serializeHistoryFiles,
-      onAfterUndoRedo,
-      activeCompPath,
-      forceReloadSdkSession,
-    ],
+    [editHistory.state, fileHistory, showToast],
   );
 
   const handleUndo = useCallback(() => applyHistory("undo"), [applyHistory]);
@@ -263,7 +201,6 @@ export function useAppHotkeys({
     onToggleRecording,
     onGroupSelection,
     onUngroupSelection,
-    leftSidebarRef,
     domEditSelectionRef,
     showToast,
   };

package/src/hooks/useCaptionDetection.sender.test.tsx

@@ -3,6 +3,7 @@ import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { expect, it, vi } from "vitest";
 import { useCaptionDetection } from "./useCaptionDetection";
+import { usePreviewIframeStore } from "../player/store/previewIframeStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
@@ -52,3 +53,48 @@ it("does not let a foreign window trigger caption activation", () => {
     vi.unstubAllGlobals();
   }
 });
+
+it("re-runs caption activation on the promoted iframe's document", () => {
+  const host = document.createElement("div");
+  const a = document.createElement("iframe");
+  const b = document.createElement("iframe");
+  document.body.append(host, a, b);
+  const ref = { current: a };
+  const root = createRoot(host);
+  const fetchMock = vi.fn(() => new Promise<Response>(() => {}));
+  vi.stubGlobal("fetch", fetchMock);
+  const params = {
+    projectId: "demo",
+    activeCompPath: "captions.html",
+    compIdToSrc: new Map<string, string>(),
+    captionEditMode: false,
+    captionHasSelection: false,
+    previewIframeRef: ref,
+    captionSync: { save: vi.fn(), loadOverrides: vi.fn(async () => {}) },
+    setRightCollapsed: vi.fn(),
+  };
+  function Harness() {
+    useCaptionDetection(params);
+    return null;
+  }
+  try {
+    act(() => usePreviewIframeStore.getState().setIframe(a));
+    act(() => root.render(<Harness />));
+    const group = b.contentDocument!.createElement("div");
+    group.className = "caption-group";
+    b.contentDocument!.body.append(group);
+    expect(fetchMock).not.toHaveBeenCalled();
+    act(() => {
+      ref.current = b;
+      usePreviewIframeStore.getState().setIframe(b);
+    });
+    expect(fetchMock).toHaveBeenCalledOnce();
+  } finally {
+    act(() => root.unmount());
+    usePreviewIframeStore.setState({ iframe: null });
+    host.remove();
+    a.remove();
+    b.remove();
+    vi.unstubAllGlobals();
+  }
+});

package/src/hooks/useCaptionDetection.ts

@@ -1,3 +1,4 @@
+import { useLivePreviewIframe } from "../player/store/previewIframeStore";
 import { buildProjectApiPath } from "../utils/projectRouting";
 import { useEffect, useRef } from "react";
 import { useCaptionStore } from "../captions/store";
@@ -26,6 +27,7 @@ export function useCaptionDetection({
   captionSync,
   setRightCollapsed,
 }: UseCaptionDetectionParams) {
+  const livePreviewIframe = useLivePreviewIframe();
   // Switching compositions must drop the previous comp's caption state — a
   // stale model + full-canvas overlay otherwise blocks normal element editing
   // on the new composition (and edit mode could never be exited).
@@ -145,7 +147,7 @@ export function useCaptionDetection({
     return () => {
       window.removeEventListener("message", handleMessage);
     };
-  }, [activeCompPath, projectId, compIdToSrc, captionSync, previewIframeRef]);
+  }, [activeCompPath, projectId, compIdToSrc, captionSync, previewIframeRef, livePreviewIframe]);
 
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {

package/src/hooks/useDomEditPreviewSync.ts

@@ -6,7 +6,7 @@
 import { useEffect, useRef } from "react";
 import { findElementForSelection, type DomEditSelection } from "../components/editor/domEditing";
 import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits";
-import type { SidebarTab } from "../components/sidebar/LeftSidebar";
+import { useDockLayoutStore } from "../components/dock/dockLayoutStore";
 import type { PatchTarget } from "../utils/sourcePatcher";
 import { logSelect } from "../utils/selectDebug";
 
@@ -30,7 +30,6 @@ interface UseDomEditPreviewSyncParams {
     (iframe: HTMLIFrameElement) => Promise<void>
   >;
   openSourceForSelection?: (sourceFile: string, target: PatchTarget) => void;
-  getSidebarTab?: () => SidebarTab;
   gsapCacheVersion?: number;
 }
 
@@ -48,7 +47,6 @@ export function useDomEditPreviewSync({
   syncPreviewHotkeys,
   applyStudioManualEditsToPreviewRef,
   openSourceForSelection,
-  getSidebarTab,
   gsapCacheVersion,
 }: UseDomEditPreviewSyncParams): void {
   // Sync selection from preview document on load / refresh
@@ -142,15 +140,15 @@ export function useDomEditPreviewSync({
   useEffect(
     // fallow-ignore-next-line complexity
     () => {
-      if (!domEditSelection || !openSourceRef.current || !getSidebarTab) return;
+      if (!domEditSelection || !openSourceRef.current) return;
       if (!domEditSelection.sourceFile) return;
-      if (getSidebarTab() !== "code") return;
+      if (!useDockLayoutStore.getState().visiblePanels.has("code")) return;
       openSourceRef.current(domEditSelection.sourceFile, {
         id: domEditSelection.id,
         selector: domEditSelection.selector,
         selectorIndex: domEditSelection.selectorIndex,
       });
     },
-    [domEditSelection, getSidebarTab],
+    [domEditSelection],
   );
 }

package/src/hooks/useDomEditSession.ts

@@ -5,7 +5,6 @@ import type { TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { RightPanelTab } from "../utils/studioHelpers";
 import type { PatchTarget } from "../utils/sourcePatcher";
-import type { SidebarTab } from "../components/sidebar/LeftSidebar";
 import type { Composition } from "@hyperframes/sdk";
 import { sdkCutoverPersist, sdkDeletePersist, type PublishSdkSession } from "../utils/sdkCutover";
 import { runResolverShadow, recordResolverParity } from "../utils/sdkResolverShadow";
@@ -53,8 +52,6 @@ export interface UseDomEditSessionParams extends DomEditTimelineParams {
   reloadPreview: () => void;
   setRefreshKey: React.Dispatch<React.SetStateAction<number>>;
   openSourceForSelection?: (sourceFile: string, target: PatchTarget) => void;
-  selectSidebarTab?: (tab: SidebarTab) => void;
-  getSidebarTab?: () => SidebarTab;
   sdkSession?: Composition | null;
   publishSdkSession?: PublishSdkSession;
   forceReloadSdkSession?: () => void;
@@ -97,8 +94,6 @@ export function useDomEditSession({
   reloadPreview,
   setRefreshKey: _setRefreshKey,
   openSourceForSelection,
-  selectSidebarTab,
-  getSidebarTab,
   sdkSession,
   publishSdkSession,
   forceReloadSdkSession,
@@ -430,8 +425,6 @@ export function useDomEditSession({
     applyDomSelection,
     buildDomSelectionFromTarget,
     openSourceForSelection,
-    selectSidebarTab,
-    getSidebarTab,
     updateGsapProperty,
     updateGsapMeta,
     deleteGsapAnimation,

package/src/hooks/useDomEditWiring.ts

@@ -16,7 +16,7 @@ import { useGsapAnimationFetchFallback } from "./useGsapAnimationFetchFallback";
 import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
 import { useGsapSelectionHandlers } from "./useGsapSelectionHandlers";
 import type { PatchTarget } from "../utils/sourcePatcher";
-import type { SidebarTab } from "../components/sidebar/LeftSidebar";
+import { useDockLayoutStore } from "../components/dock/dockLayoutStore";
 
 export interface UseDomEditWiringParams {
   projectId: string | null;
@@ -43,8 +43,6 @@ export interface UseDomEditWiringParams {
   ) => void;
   buildDomSelectionFromTarget: (element: HTMLElement) => Promise<DomEditSelection | null>;
   openSourceForSelection?: (sourceFile: string, target: PatchTarget) => void;
-  selectSidebarTab?: (tab: SidebarTab) => void;
-  getSidebarTab?: () => SidebarTab;
   // GSAP script commit ops (from useGsapScriptCommits)
   updateGsapProperty: (
     sel: DomEditSelection,
@@ -132,8 +130,6 @@ export function useDomEditWiring({
   applyDomSelection,
   buildDomSelectionFromTarget,
   openSourceForSelection,
-  selectSidebarTab,
-  getSidebarTab,
   updateGsapProperty,
   updateGsapMeta,
   deleteGsapAnimation,
@@ -157,16 +153,16 @@ export function useDomEditWiring({
 
   const onClickToSource = useCallback(
     (selection: DomEditSelection) => {
-      if (!openSourceForSelection || !selectSidebarTab) return;
+      if (!openSourceForSelection) return;
       if (!selection.sourceFile) return;
-      selectSidebarTab("code");
+      useDockLayoutStore.getState().activatePanel("code");
       openSourceForSelection(selection.sourceFile, {
         id: selection.id,
         selector: selection.selector,
         selectorIndex: selection.selectorIndex,
       });
     },
-    [openSourceForSelection, selectSidebarTab],
+    [openSourceForSelection],
   );
 
   // ── DOM selection -> timeline element sync ──
@@ -267,7 +263,6 @@ export function useDomEditWiring({
     syncPreviewHotkeys,
     applyStudioManualEditsToPreviewRef,
     openSourceForSelection,
-    getSidebarTab,
     gsapCacheVersion,
   });
 

package/src/hooks/useEditHistoryActions.test.tsx

@@ -0,0 +1,90 @@
+// @vitest-environment happy-dom
+
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
+import { useEditHistoryActions, type EditHistoryHandle } from "./useEditHistoryActions";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+afterEach(() => act(() => root?.unmount()));
+
+function mount(result: { ok: boolean; reason?: string; label?: string; paths?: string[] }) {
+  const editHistory = {
+    undo: vi.fn<EditHistoryHandle["undo"]>(async (cb) => {
+      if (result.ok) await cb.writeFile("index.html", "before");
+      return result;
+    }),
+    redo: vi.fn<EditHistoryHandle["redo"]>(async () => result),
+  };
+  const deps = {
+    editHistory,
+    readOptionalProjectFile: vi.fn(async () => ""),
+    readProjectFile: vi.fn(async () => ""),
+    writeProjectFile: vi.fn(async () => undefined),
+    showToast: vi.fn(),
+    syncHistoryPreviewAfterApply: vi.fn(async () => undefined),
+    waitForPendingDomEditSaves: vi.fn(async () => undefined),
+    onAfterUndoRedo: vi.fn(),
+    activeCompPath: "index.html",
+    forceReloadSdkSession: vi.fn(),
+  };
+  let actions!: ReturnType<typeof useEditHistoryActions>;
+  function Probe() {
+    actions = useEditHistoryActions(deps);
+    return null;
+  }
+  root = createRoot(document.createElement("div"));
+  act(() => root!.render(createElement(Probe)));
+  return { deps, actions };
+}
+
+describe("useEditHistoryActions", () => {
+  it("undo writes through the host writer, resyncs the preview and toasts the label", async () => {
+    const { deps, actions } = mount({ ok: true, label: "Move clip", paths: ["index.html"] });
+    await act(() => actions.undo());
+    expect(deps.waitForPendingDomEditSaves).toHaveBeenCalled();
+    expect(deps.writeProjectFile).toHaveBeenCalledWith("index.html", "before");
+    expect(deps.onAfterUndoRedo).toHaveBeenCalled();
+    expect(deps.forceReloadSdkSession).toHaveBeenCalled();
+    expect(deps.syncHistoryPreviewAfterApply).toHaveBeenCalled();
+    expect(deps.showToast).toHaveBeenCalledWith("Undid Move clip", "info");
+  });
+
+  it("redo reports the redone label and skips the SDK reload for other files", async () => {
+    const { deps, actions } = mount({ ok: true, label: "Split clip", paths: ["other.html"] });
+    await act(() => actions.redo());
+    expect(deps.forceReloadSdkSession).not.toHaveBeenCalled();
+    expect(deps.showToast).toHaveBeenCalledWith("Redid Split clip", "info");
+  });
+
+  it("explains a refused undo when the file changed on disk", async () => {
+    const { deps, actions } = mount({ ok: false, reason: "content-mismatch" });
+    await act(() => actions.undo());
+    expect(deps.showToast).toHaveBeenCalledWith(
+      "File changed outside Studio. Undo history was not applied.",
+      "info",
+    );
+    expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();
+  });
+
+  it("waits for pending saves first and reads the motion file through the optional reader", async () => {
+    const { deps, actions } = mount({ ok: true, label: "Move clip", paths: ["index.html"] });
+    const order: string[] = [];
+    deps.waitForPendingDomEditSaves.mockImplementation(async () => void order.push("wait"));
+    deps.editHistory.undo.mockImplementation(async (cb) => {
+      order.push("undo");
+      await cb.readFile(STUDIO_MOTION_PATH);
+      await cb.readFile("index.html");
+      await cb.serialize?.(["index.html"], async () => order.push("serialized"));
+      return { ok: true };
+    });
+    await act(() => actions.undo());
+    expect(order).toEqual(["wait", "undo", "serialized"]);
+    expect(deps.readOptionalProjectFile).toHaveBeenCalledWith(STUDIO_MOTION_PATH);
+    expect(deps.readProjectFile).toHaveBeenCalledWith("index.html");
+    expect(deps.readProjectFile).not.toHaveBeenCalledWith(STUDIO_MOTION_PATH);
+  });
+});

package/src/hooks/useEditHistoryActions.ts

@@ -0,0 +1,106 @@
+// fallow-ignore-file complexity
+import { useCallback, useMemo } from "react";
+import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+
+interface HistoryResult {
+  ok: boolean;
+  reason?: string;
+  label?: string;
+  paths?: string[];
+  /** Per-file restored/previous content, used to soft-apply the preview. */
+  files?: Record<string, { previous: string; restored: string }>;
+}
+interface HistoryFileCallbacks {
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+  serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
+}
+export interface EditHistoryHandle {
+  undo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
+  redo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
+  state: {
+    undo: ReadonlyArray<{ createdAt: number }>;
+    redo: ReadonlyArray<{ createdAt: number }>;
+  };
+}
+
+export interface UseEditHistoryActionsOptions {
+  editHistory: Pick<EditHistoryHandle, "undo" | "redo">;
+  readOptionalProjectFile: (path: string) => Promise<string>;
+  readProjectFile: (path: string) => Promise<string>;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  syncHistoryPreviewAfterApply: (restore: Pick<HistoryResult, "paths" | "files">) => Promise<void>;
+  waitForPendingDomEditSaves: () => Promise<void>;
+  onAfterUndoRedo?: () => void;
+  /** Active composition path — decides whether undo/redo must resync the SDK session. */
+  activeCompPath?: string | null;
+  /** Reloads the SDK session after a revert of the active comp, past the self-write suppress window. */
+  forceReloadSdkSession?: () => void;
+}
+
+/** Applies one persisted file-history step: the single owner of undo/redo over project files. */
+export function useEditHistoryActions({
+  editHistory,
+  readOptionalProjectFile,
+  readProjectFile,
+  writeProjectFile,
+  showToast,
+  syncHistoryPreviewAfterApply,
+  waitForPendingDomEditSaves,
+  onAfterUndoRedo,
+  activeCompPath,
+  forceReloadSdkSession,
+}: UseEditHistoryActionsOptions) {
+  const readHistoryFile = useCallback(
+    (path: string): Promise<string> =>
+      path === STUDIO_MOTION_PATH ? readOptionalProjectFile(path) : readProjectFile(path),
+    [readOptionalProjectFile, readProjectFile],
+  );
+  const serializeHistoryFiles = useCallback(
+    <T>(paths: readonly string[], task: () => Promise<T>) =>
+      serializeStudioFileMutations(writeProjectFile, paths, task),
+    [writeProjectFile],
+  );
+
+  const apply = useCallback(
+    async (direction: "undo" | "redo") => {
+      const [noun, verb] = direction === "undo" ? ["Undo", "Undid"] : ["Redo", "Redid"];
+      await waitForPendingDomEditSaves();
+      const result = await editHistory[direction]({
+        readFile: readHistoryFile,
+        writeFile: writeProjectFile,
+        serialize: serializeHistoryFiles,
+      });
+      if (!result.ok && result.reason === "content-mismatch") {
+        showToast(`File changed outside Studio. ${noun} history was not applied.`, "info");
+        return;
+      }
+      if (result.ok && result.label) {
+        onAfterUndoRedo?.();
+        if (activeCompPath && result.paths?.includes(activeCompPath)) {
+          forceReloadSdkSession?.();
+        }
+        await syncHistoryPreviewAfterApply({ paths: result.paths, files: result.files });
+        showToast(`${verb} ${result.label}`, "info");
+      }
+    },
+    [
+      editHistory,
+      readHistoryFile,
+      showToast,
+      syncHistoryPreviewAfterApply,
+      waitForPendingDomEditSaves,
+      writeProjectFile,
+      serializeHistoryFiles,
+      onAfterUndoRedo,
+      activeCompPath,
+      forceReloadSdkSession,
+    ],
+  );
+
+  const undo = useCallback(() => apply("undo"), [apply]);
+  const redo = useCallback(() => apply("redo"), [apply]);
+  return useMemo(() => ({ undo, redo }), [undo, redo]);
+}