@hyperframes/studio 0.8.100 → 0.8.101

package/src/hooks/useAppHotkeys.ts

@@ -8,13 +8,7 @@ import {
   applyCaptionModelToIframe,
   isCaptionPreviewVisible,
 } from "../captions/components/CaptionOverlayUtils";
-import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
-import {
-  type HotkeyCallbacks,
-  dispatchModifierKey,
-  dispatchPlainKey,
-  handleUndoRedoKey,
-} from "./appHotkeysDispatch";
+import { type HotkeyCallbacks, dispatchModifierKey, dispatchPlainKey } from "./appHotkeysDispatch";
 import {
   useEditHistoryActions,
   type EditHistoryHandle,
@@ -36,9 +30,14 @@ function safeAddListener(t: EventTarget | null, type: string, h: EventListener,
     /* cross-origin */
   }
 }
-function safeRemoveListener(t: EventTarget | null, type: string, h: EventListener) {
+function safeRemoveListener(
+  t: EventTarget | null,
+  type: string,
+  h: EventListener,
+  capture = false,
+) {
   try {
-    t?.removeEventListener(type, h);
+    t?.removeEventListener(type, h, capture);
   } catch {
     /* cross-origin */
   }
@@ -86,6 +85,7 @@ interface UseAppHotkeysParams {
   writeProjectFile: (path: string, content: string) => Promise<void>;
   showToast: (message: string, tone?: "error" | "info") => void;
   syncHistoryPreviewAfterApply: UseEditHistoryActionsOptions["syncHistoryPreviewAfterApply"];
+  showHistoryRestoreNow?: UseEditHistoryActionsOptions["showHistoryRestoreNow"];
   waitForPendingDomEditSaves: () => Promise<void>;
   handleCopy: () => boolean;
   handlePaste: () => Promise<void>;
@@ -124,6 +124,7 @@ export function useAppHotkeys({
   writeProjectFile,
   showToast,
   syncHistoryPreviewAfterApply,
+  showHistoryRestoreNow,
   waitForPendingDomEditSaves,
   handleCopy,
   handlePaste,
@@ -150,6 +151,7 @@ export function useAppHotkeys({
     writeProjectFile,
     showToast,
     syncHistoryPreviewAfterApply,
+    showHistoryRestoreNow,
     waitForPendingDomEditSaves,
     onAfterUndoRedo,
     activeCompPath,
@@ -229,52 +231,23 @@ export function useAppHotkeys({
 
   // ── Preview iframe forwarding ──
 
-  const handleHistoryHotkey = useCallback((event: KeyboardEvent) => {
-    if (!(event.metaKey || event.ctrlKey) || shouldIgnoreHistoryShortcut(event.target)) return;
-    handleUndoRedoKey(
-      event,
-      () => void cbRef.current.handleUndo(),
-      () => void cbRef.current.handleRedo(),
-    );
-  }, []);
-
   /**
-   * Give the preview iframe the app's hotkeys, because a keypress lands in
-   * whichever document has focus and clicking the canvas puts focus in there.
-   *
-   * Must run on every iframe LOAD, not once when the element mounts: a reload
-   * keeps the same element (so no ref callback) and the same WindowProxy (so an
-   * identity check sees no change) while replacing the inner window that holds
-   * the listeners. Attaching once left Delete dead in the canvas after the first
-   * reload — press it with a selection and nothing happened, no toast, nothing
-   * to explain it — while undo/redo kept working because they re-attached here.
+   * Give the preview iframe the app's hotkeys: clicking the canvas puts focus in there.
+   * Runs on every iframe LOAD: a reload keeps the element and WindowProxy but replaces the
+   * inner window holding the listeners, which once left Delete dead after the first reload.
    */
   const syncPreviewHotkeys = useCallback(
     (iframe: HTMLIFrameElement | null) => {
       previewHistoryCleanupRef.current?.();
       previewHistoryCleanupRef.current = null;
       const win = iframeContentWindow(iframe);
-      let doc: Document | null = null;
-      try {
-        doc = iframe?.contentDocument ?? null;
-      } catch {
-        doc = null;
-      }
-      if (!win && !doc) return;
-      const handler = handleHistoryHotkey as EventListener;
+      if (!win) return;
       const appHandler = handleAppKeyDown as EventListener;
-      safeAddListener(win, "keydown", handler, true);
-      // Window only: the history pair also listens on the document, and a
-      // capture listener on both would run the app handler twice per press.
+      // Window only: a capture listener on the document too would run it twice per press.
       safeAddListener(win, "keydown", appHandler, true);
-      doc?.addEventListener("keydown", handleHistoryHotkey, true);
-      previewHistoryCleanupRef.current = () => {
-        safeRemoveListener(win, "keydown", handler);
-        safeRemoveListener(win, "keydown", appHandler);
-        doc?.removeEventListener("keydown", handleHistoryHotkey, true);
-      };
+      previewHistoryCleanupRef.current = () => safeRemoveListener(win, "keydown", appHandler, true);
     },
-    [handleAppKeyDown, handleHistoryHotkey],
+    [handleAppKeyDown],
   );
 
   useEffect(

package/src/hooks/useEditHistoryActions.paint.test.tsx

@@ -0,0 +1,166 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import {
+  createStudioApi,
+  openProjectHistory,
+  type StudioApiAdapter,
+} from "@hyperframes/studio-server";
+import { useEditHistoryActions } from "./useEditHistoryActions";
+import { usePersistentEditHistory } from "./usePersistentEditHistory";
+import { usePreviewPersistence } from "./usePreviewPersistence";
+
+const page = (left: string, top = "0px") =>
+  `<!doctype html><html><head></head><body><div id="root" data-composition-id="main"><div id="box" style="position: absolute; left: ${left}"></div><div id="other" style="position: absolute; top: ${top}"></div></div></body></html>`;
+const BEFORE = page("10px");
+const AFTER = page("50px");
+const OUTSIDE = page("50px", "99px");
+
+const cleanup: Array<() => unknown> = [];
+let scratch = "";
+beforeEach(() => {
+  scratch = mkdtempSync(join(tmpdir(), "hf-undo-paint-"));
+});
+afterEach(async () => {
+  for (const step of cleanup.splice(0).reverse()) await step();
+  rmSync(scratch, { recursive: true, force: true });
+  vi.unstubAllGlobals();
+});
+
+/** Studio's undo wired as App.tsx wires it, over the real history engine, with a live preview document. */
+async function studio() {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  const dir = join(scratch, "project");
+  mkdirSync(dir);
+  const path = join(dir, "index.html");
+  writeFileSync(path, BEFORE);
+  const engine = await openProjectHistory({
+    projectDir: dir,
+    historyRoot: join(scratch, "history"),
+  });
+  cleanup.push(() => engine.close());
+  const api = createStudioApi({
+    listProjects: () => [],
+    resolveProject: (id: string) => (id === "demo" ? { id, dir } : null),
+    history: () => engine,
+  } as unknown as StudioApiAdapter);
+  vi.stubGlobal("fetch", (url: string, init?: RequestInit) =>
+    api.request(url.replace(/^\/api/, ""), init),
+  );
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  cleanup.push(() => iframe.remove());
+  const reloads = vi.fn();
+  const readFile = async (p: string) => readFileSync(join(dir, p), "utf8");
+  let history!: ReturnType<typeof usePersistentEditHistory>;
+  let persistence!: ReturnType<typeof usePreviewPersistence>;
+  let actions!: ReturnType<typeof useEditHistoryActions>;
+  function Harness() {
+    history = usePersistentEditHistory({ projectId: "demo" });
+    persistence = usePreviewPersistence({
+      showToast: () => {},
+      readOptionalProjectFile: async () => "",
+      writeProjectFile: async () => {},
+      recordEdit: async () => {},
+      previewIframeRef: { current: iframe },
+      activeCompPathRef: { current: "index.html" },
+      reloadPreview: reloads,
+    });
+    actions = useEditHistoryActions({
+      editHistory: history,
+      readOptionalProjectFile: async () => "",
+      readProjectFile: readFile,
+      writeProjectFile: async (p, content) => writeFileSync(join(dir, p), content),
+      showToast: () => {},
+      syncHistoryPreviewAfterApply: persistence.syncHistoryPreviewAfterApply,
+      showHistoryRestoreNow: persistence.showHistoryRestoreNow,
+      waitForPendingDomEditSaves: persistence.waitForPendingDomEditSaves,
+    });
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  await act(async () => root.render(createElement(Harness)));
+  cleanup.push(() => act(() => root.unmount()));
+  const box = () => iframe.contentDocument!.getElementById("box")!.style.left;
+  const other = () => iframe.contentDocument!.getElementById("other")!.style.top;
+  const show = (html: string) => {
+    iframe.contentDocument!.documentElement.innerHTML = new DOMParser().parseFromString(
+      html,
+      "text/html",
+    ).documentElement.innerHTML;
+  };
+  /** A move Studio saved: the live preview already shows it, then the file and the history claim land. */
+  const edit = async () => {
+    show(AFTER);
+    writeFileSync(path, AFTER);
+    await act(() =>
+      history.recordEdit({
+        label: "Move layer",
+        files: { "index.html": { before: BEFORE, after: AFTER } },
+      }),
+    );
+    await vi.waitFor(() => expect(history.undoLabel).toBe("Move layer"));
+  };
+  return {
+    history: () => history,
+    persistence: () => persistence,
+    actions: () => actions,
+    box,
+    other,
+    show,
+    path,
+    edit,
+    file: () => readFileSync(path, "utf8"),
+    reloads,
+  };
+}
+
+it("undo and redo of a style edit paint in the key's own task, before the server answers", async () => {
+  const s = await studio();
+  await s.edit();
+
+  const undone = s.actions().undo();
+  expect(s.box()).toBe("10px");
+  await act(() => undone);
+  expect(s.file()).toBe(BEFORE);
+  expect(s.box()).toBe("10px");
+
+  await vi.waitFor(() => expect(s.history().redoLabel).toBeTruthy());
+  const redone = s.actions().redo();
+  expect(s.box()).toBe("50px");
+  await act(() => redone);
+  expect(s.file()).toBe(AFTER);
+  expect(s.box()).toBe("50px");
+  expect(s.reloads).not.toHaveBeenCalled();
+});
+
+it("an undo pressed while a save is still running waits for the server instead of guessing", async () => {
+  const s = await studio();
+  await s.edit();
+  let finish!: () => void;
+  const saving = new Promise<void>((resolve) => (finish = resolve));
+  void s.persistence().queueDomEditSave(() => saving);
+
+  const undone = s.actions().undo();
+  expect(s.box()).toBe("50px");
+  finish();
+  await act(() => undone);
+  expect(s.file()).toBe(BEFORE);
+  expect(s.box()).toBe("10px");
+});
+
+it("an undo after an outside write ends with the preview showing the file the server restored", async () => {
+  const s = await studio();
+  await s.edit();
+  writeFileSync(s.path, OUTSIDE);
+  s.show(OUTSIDE);
+
+  await act(() => s.actions().undo());
+  expect(s.file()).toBe(AFTER);
+  expect(s.other()).toBe("0px");
+  expect(s.box()).toBe("50px");
+});

package/src/hooks/useEditHistoryActions.test.tsx

@@ -11,24 +11,36 @@ import { useEditHistoryActions, type EditHistoryHandle } from "./useEditHistoryA
 let root: Root | null = null;
 afterEach(() => act(() => root?.unmount()));
 
-function mount(result: {
-  ok: boolean;
-  reason?: string;
-  message?: string;
-  label?: string;
-  paths?: string[];
-}) {
+type RestoreFiles = Record<string, { previous: string; restored: string }>;
+type Prediction = { id: string; files: RestoreFiles };
+
+function mount(
+  result: {
+    ok: boolean;
+    reason?: string;
+    message?: string;
+    label?: string;
+    paths?: string[];
+    undoes?: string;
+    files?: RestoreFiles;
+  },
+  predicted?: Prediction,
+) {
   const editHistory = {
     undo: vi.fn<EditHistoryHandle["undo"]>(async () => result),
     redo: vi.fn<EditHistoryHandle["redo"]>(async () => result),
+    predict: () => predicted ?? null,
   };
+  const putBack = vi.fn();
   const deps = {
     editHistory,
     readOptionalProjectFile: vi.fn(async () => ""),
     readProjectFile: vi.fn(async () => ""),
     writeProjectFile: vi.fn(async () => undefined),
     showToast: vi.fn(),
-    syncHistoryPreviewAfterApply: vi.fn(async () => undefined),
+    syncHistoryPreviewAfterApply: vi.fn(async (_restore: unknown) => undefined),
+    putBack,
+    showHistoryRestoreNow: vi.fn((_files: RestoreFiles) => putBack),
     waitForPendingDomEditSaves: vi.fn(async () => undefined),
     onAfterUndoRedo: vi.fn(),
     activeCompPath: "index.html",
@@ -44,7 +56,53 @@ function mount(result: {
   return { deps, actions };
 }
 
+const PREDICTED = { id: "e1", files: { "index.html": { previous: "B", restored: "A" } } };
+const SERVER_FILES = { "index.html": { previous: "B", restored: "A2" } };
+
 describe("useEditHistoryActions", () => {
+  it("corrects a shown step from the server's restore, diffed from what the preview shows", async () => {
+    const { deps, actions } = mount(
+      { ok: true, label: "Undid: Move", paths: ["index.html"], undoes: "e1", files: SERVER_FILES },
+      PREDICTED,
+    );
+    await act(() => actions.undo());
+    expect(deps.showHistoryRestoreNow).toHaveBeenCalledWith(PREDICTED.files);
+    expect(deps.putBack).not.toHaveBeenCalled();
+    expect(deps.syncHistoryPreviewAfterApply).toHaveBeenCalledWith({
+      paths: ["index.html"],
+      files: { "index.html": { previous: "A", restored: "A2" } },
+    });
+  });
+
+  it("puts a shown step back and applies the server's own restore when it stepped another entry", async () => {
+    const { deps, actions } = mount(
+      {
+        ok: true,
+        label: "Undid: Outside",
+        paths: ["index.html"],
+        undoes: "e0",
+        files: SERVER_FILES,
+      },
+      PREDICTED,
+    );
+    await act(() => actions.undo());
+    expect(deps.putBack).toHaveBeenCalledTimes(1);
+    expect(deps.syncHistoryPreviewAfterApply).toHaveBeenCalledWith({
+      paths: ["index.html"],
+      files: SERVER_FILES,
+    });
+  });
+
+  it("puts a shown step back when the server refuses it", async () => {
+    const { deps, actions } = mount(
+      { ok: false, reason: "failed", message: "disk full" },
+      PREDICTED,
+    );
+    await act(() => actions.undo());
+    expect(deps.putBack).toHaveBeenCalledTimes(1);
+    expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();
+  });
+
   it("undo resyncs the preview and toasts the step as the history names it", async () => {
     const { deps, actions } = mount({ ok: true, label: "Undid: Move clip", paths: ["index.html"] });
     await act(() => actions.undo());
@@ -80,7 +138,7 @@ describe("useEditHistoryActions", () => {
     expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();
   });
 
-  it("says why when the history could not take the step", async () => {
+  it("says why when the history could not take the step, with nothing shown to take back", async () => {
     const { deps, actions } = mount({ ok: false, reason: "failed", message: "disk full" });
     await act(() => actions.undo());
     expect(deps.showToast).toHaveBeenCalledWith("Undo failed: disk full", "error");

package/src/hooks/useEditHistoryActions.ts

@@ -2,6 +2,7 @@
 import { useCallback, useMemo } from "react";
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+import type { RestoreFiles } from "../utils/gsapUndoRestore";
 
 interface HistoryResult {
   ok: boolean;
@@ -9,8 +10,9 @@ interface HistoryResult {
   message?: string;
   label?: string;
   paths?: string[];
+  undoes?: string;
   /** Per-file restored/previous content, used to soft-apply the preview. */
-  files?: Record<string, { previous: string; restored: string }>;
+  files?: RestoreFiles;
 }
 interface HistoryFileCallbacks {
   readFile: (path: string) => Promise<string>;
@@ -19,6 +21,7 @@ interface HistoryFileCallbacks {
 export interface EditHistoryHandle {
   undo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
   redo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
+  predict?: (direction: "undo" | "redo") => { id: string; files: RestoreFiles } | null;
   state: {
     undo: ReadonlyArray<{ createdAt: number }>;
     redo: ReadonlyArray<{ createdAt: number }>;
@@ -26,12 +29,13 @@ export interface EditHistoryHandle {
 }
 
 export interface UseEditHistoryActionsOptions {
-  editHistory: Pick<EditHistoryHandle, "undo" | "redo">;
+  editHistory: Pick<EditHistoryHandle, "undo" | "redo" | "predict">;
   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>;
+  showHistoryRestoreNow?: (files: RestoreFiles) => (() => void) | null;
   waitForPendingDomEditSaves: () => Promise<void>;
   onAfterUndoRedo?: (restore: Pick<HistoryResult, "paths" | "files">) => void;
   /** Active composition path — decides whether undo/redo must resync the SDK session. */
@@ -48,6 +52,7 @@ export function useEditHistoryActions({
   writeProjectFile,
   showToast,
   syncHistoryPreviewAfterApply,
+  showHistoryRestoreNow,
   waitForPendingDomEditSaves,
   onAfterUndoRedo,
   activeCompPath,
@@ -67,11 +72,22 @@ export function useEditHistoryActions({
   const apply = useCallback(
     async (direction: "undo" | "redo") => {
       const noun = direction === "undo" ? "Undo" : "Redo";
-      await waitForPendingDomEditSaves();
-      const result = await editHistory[direction]({
-        readFile: readHistoryFile,
-        serialize: serializeHistoryFiles,
-      });
+      // Paint the step in the key's own task when this tab knows it; the server's answer then confirms or corrects.
+      const predicted = editHistory.predict?.(direction) ?? null;
+      const putBack = predicted ? (showHistoryRestoreNow?.(predicted.files) ?? null) : null;
+      let result: HistoryResult = { ok: false, reason: "failed" };
+      let serverSteppedShown = false;
+      try {
+        await waitForPendingDomEditSaves();
+        result = await editHistory[direction]({
+          readFile: readHistoryFile,
+          serialize: serializeHistoryFiles,
+        });
+        serverSteppedShown =
+          Boolean(putBack && result.ok && result.label) && result.undoes === predicted?.id;
+      } finally {
+        if (putBack && !serverSteppedShown) putBack();
+      }
       if (!result.ok && result.reason === "content-mismatch") {
         showToast(
           `Can't ${direction}: ${result.paths?.join(", ")} changed since that edit.`,
@@ -84,7 +100,8 @@ export function useEditHistoryActions({
         return;
       }
       if (result.ok && result.label) {
-        const restore = { paths: result.paths, files: result.files };
+        const files = serverSteppedShown ? fromShown(result.files, predicted!.files) : result.files;
+        const restore = { paths: result.paths, files };
         onAfterUndoRedo?.(restore);
         if (activeCompPath && result.paths?.includes(activeCompPath)) {
           forceReloadSdkSession?.();
@@ -98,6 +115,7 @@ export function useEditHistoryActions({
       readHistoryFile,
       showToast,
       syncHistoryPreviewAfterApply,
+      showHistoryRestoreNow,
       waitForPendingDomEditSaves,
       serializeHistoryFiles,
       onAfterUndoRedo,
@@ -110,3 +128,13 @@ export function useEditHistoryActions({
   const redo = useCallback(() => apply("redo"), [apply]);
   return useMemo(() => ({ undo, redo }), [undo, redo]);
 }
+
+function fromShown(files: RestoreFiles | undefined, shown: RestoreFiles) {
+  if (!files) return files;
+  return Object.fromEntries(
+    Object.entries(files).map(([path, f]) => [
+      path,
+      { previous: shown[path]?.restored ?? f.previous, restored: f.restored },
+    ]),
+  );
+}

package/src/hooks/usePersistentEditHistory.test.ts

@@ -76,6 +76,7 @@ it("an edit Studio saved is undone and redone by the project's history, with the
   expect(undone).toEqual({
     ok: true,
     label: "Undid: Moved Title",
+    undoes: expect.any(String),
     paths: ["index.html"],
     files: { "index.html": { previous: "B", restored: "A" } },
   });
@@ -241,3 +242,48 @@ it("a step that cannot reach the server says so", async () => {
     message: "Studio could not reach its server.",
   });
 });
+
+it("predicts a step from what this tab wrote, and not while a claim or step may have moved the history", async () => {
+  const { hook, save, readFile } = await studio();
+  save("B");
+  const claim = hook().recordEdit({
+    label: "Moved Title",
+    files: { "index.html": { before: "A", after: "B" } },
+  });
+  expect(hook().predict("undo")).toBeNull();
+  await act(() => claim);
+  const predicted = await vi.waitFor(() => {
+    const next = hook().predict("undo");
+    expect(next?.files).toEqual({ "index.html": { previous: "B", restored: "A" } });
+    return next!;
+  });
+
+  hook().noteOutsideChange();
+  expect(hook().predict("undo")).toBeNull();
+  await vi.waitFor(() => expect(hook().predict("undo")?.id).toBe(predicted.id));
+
+  const undone = hook().undo({ readFile });
+  expect(hook().predict("undo")).toBeNull();
+  expect((await act(() => undone)).undoes).toBe(predicted.id);
+  await vi.waitFor(() =>
+    expect(hook().predict("redo")?.files).toEqual({
+      "index.html": { previous: "A", restored: "B" },
+    }),
+  );
+});
+
+it("an undo taken before the view caught up with the edit still reports the preview's before and after", async () => {
+  const { hook, save, readFile } = await studio();
+  save("B");
+  const record = hook().recordEdit({
+    label: "Moved Title",
+    files: { "index.html": { before: "A", after: "B" } },
+  });
+  const undo = hook().undo;
+  await act(() => record);
+  const undone = await act(() => undo({ readFile }));
+  expect(undone).toMatchObject({
+    ok: true,
+    files: { "index.html": { previous: "B", restored: "A" } },
+  });
+});