@hyperframes/studio 0.8.100 → 0.8.102

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

@@ -7,10 +7,15 @@ import type { DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player/store/playerStore";
 import { useAppHotkeys } from "./useAppHotkeys";
 import { mountReactHarness } from "./domSelectionTestHarness";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 const domDelete = vi.fn(async () => undefined);
+const historyUndo = vi.fn(async () => ({ ok: false }));
+const historyRedo = vi.fn(async () => ({ ok: false }));
 let root: Root | null = null;
 let sync: ((iframe: HTMLIFrameElement | null) => void) | null = null;
 
@@ -35,8 +40,8 @@ function Harness() {
     domEditSelectionRef: selectionRef,
     clearDomSelectionRef: useRef<() => void>(() => undefined),
     editHistory: {
-      undo: vi.fn(async () => ({ ok: false })),
-      redo: vi.fn(async () => ({ ok: false })),
+      undo: historyUndo,
+      redo: historyRedo,
       state: { undo: [], redo: [] },
     },
     readOptionalProjectFile: vi.fn(async () => ""),
@@ -62,6 +67,9 @@ afterEach(() => {
   document.body.innerHTML = "";
   usePlayerStore.getState().reset();
   domDelete.mockClear();
+  historyUndo.mockClear();
+  historyRedo.mockClear();
+  vi.mocked(trackStudioEvent).mockClear();
 });
 
 describe("preview iframe hotkey forwarding", () => {
@@ -87,4 +95,61 @@ describe("preview iframe hotkey forwarding", () => {
 
     expect(domDelete).toHaveBeenCalledTimes(1);
   });
+
+  function mountWithPreview(): Window & typeof globalThis {
+    root = mountReactHarness(<Harness />);
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    act(() => sync?.(iframe));
+    const inner = iframe.contentWindow as (Window & typeof globalThis) | null;
+    if (!inner) throw new Error("expected an iframe window");
+    return inner;
+  }
+
+  async function press(inner: Window & typeof globalThis, init: KeyboardEventInit) {
+    await act(async () => {
+      inner.document.body.dispatchEvent(
+        new inner.KeyboardEvent("keydown", { ...init, bubbles: true }),
+      );
+    });
+  }
+
+  it("takes one tracked undo step per Cmd+Z pressed inside the preview", async () => {
+    await press(mountWithPreview(), { key: "z", ctrlKey: true });
+
+    expect(historyUndo).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith("keyboard_shortcut", { action: "undo" });
+  });
+
+  it.each([
+    ["Shift+Cmd+Z", { key: "Z", metaKey: true, shiftKey: true }],
+    ["Ctrl+Y", { key: "y", ctrlKey: true }],
+  ])("takes one tracked redo step per %s pressed inside the preview", async (_, init) => {
+    await press(mountWithPreview(), init);
+
+    expect(historyRedo).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith("keyboard_shortcut", { action: "redo" });
+  });
+
+  it("stops handling preview keys once the app unmounts", async () => {
+    root = mountReactHarness(<Harness />);
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const inner = iframe.contentWindow as (Window & typeof globalThis) | null;
+    if (!inner) throw new Error("expected an iframe window");
+    const add = vi.spyOn(inner, "addEventListener");
+    const remove = vi.spyOn(inner, "removeEventListener");
+    act(() => sync?.(iframe));
+    act(() => root?.unmount());
+    root = null;
+
+    await press(inner, { key: "z", ctrlKey: true });
+
+    expect(historyUndo).not.toHaveBeenCalled();
+    // happy-dom removes a listener whatever its capture flag; a browser does not, so pin the flag.
+    expect(add).toHaveBeenCalled();
+    expect(remove.mock.calls).toEqual(add.mock.calls);
+  });
 });

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/useDomEditCommits.test.tsx

@@ -42,6 +42,7 @@ interface RenderDomEditCommitsOptions {
   onTrySdkPersist?: () => Promise<CutoverResult>;
   queueDomEditSave?: <T>(save: () => Promise<T>) => Promise<T>;
   projectIdRef?: MutableRefObject<string | null>;
+  readOnlyPreview?: boolean;
 }
 
 type FetchHandler = (
@@ -232,7 +233,7 @@ function renderDomEditCommits(
         target === selection.element ? selection : null,
       ),
       onTrySdkPersist: options.onTrySdkPersist,
-      readOnlyPreview: false,
+      readOnlyPreview: options.readOnlyPreview ?? false,
     });
     return null;
   }
@@ -266,97 +267,100 @@ describe("useDomEditCommits z-index reorder persistence", () => {
     document.body.replaceChildren();
   });
 
-  it("persists an N-element reorder with one batch POST, one undo entry, and NO iframe reload", async () => {
-    const original =
-      '<div id="a" style="z-index: 1"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 3"></div>';
-    const after =
-      '<div id="a" style="z-index: 3"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 1"></div>';
-    const fetchMock = vi.fn(
-      async (
-        input: Parameters<typeof fetch>[0],
-        _init?: Parameters<typeof fetch>[1],
-      ): Promise<Response> => {
-        const url = requestUrl(input);
-        if (url.endsWith("/file-mutations/patch-element-batches")) {
-          return jsonResponse({
-            durable: true,
-            files: [
-              {
-                sourceFile: "index.html",
-                changed: true,
-                matched: [true, true, true],
-                before: original,
-                after,
-              },
-            ],
-          });
-        }
-        throw new Error(`Unexpected fetch: ${url}`);
-      },
-    );
-    vi.stubGlobal("fetch", fetchMock);
-    const { iframe, element } = createPreviewElement(
-      '<div data-hf-id="hf-card"></div><div id="b"></div><div id="c"></div>',
-    );
-    element.id = "a";
-    const elements = [
-      element,
-      iframe.contentDocument!.getElementById("b")!,
-      iframe.contentDocument!.getElementById("c")!,
-    ];
-    const rendered = renderDomEditCommits(createSelection(element), iframe);
-
-    try {
-      await act(async () => {
-        await rendered.hook.handleDomZIndexReorderCommit(
-          elements.map((item, index) => ({
-            element: item,
-            zIndex: 3 - index,
-            id: item.id,
-            sourceFile: "index.html",
-          })),
-          "z-reorder:test",
-        );
-      });
-
-      const batchPosts = fetchMock.mock.calls.filter(([input]) =>
-        requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
+  it.each([false, true])(
+    "persists an N-element reorder with one batch POST, one undo entry, and NO iframe reload (read-only preview %s: the timeline's z sync stays editable)",
+    async (readOnlyPreview) => {
+      const original =
+        '<div id="a" style="z-index: 1"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 3"></div>';
+      const after =
+        '<div id="a" style="z-index: 3"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 1"></div>';
+      const fetchMock = vi.fn(
+        async (
+          input: Parameters<typeof fetch>[0],
+          _init?: Parameters<typeof fetch>[1],
+        ): Promise<Response> => {
+          const url = requestUrl(input);
+          if (url.endsWith("/file-mutations/patch-element-batches")) {
+            return jsonResponse({
+              durable: true,
+              files: [
+                {
+                  sourceFile: "index.html",
+                  changed: true,
+                  matched: [true, true, true],
+                  before: original,
+                  after,
+                },
+              ],
+            });
+          }
+          throw new Error(`Unexpected fetch: ${url}`);
+        },
       );
-      const singlePosts = fetchMock.mock.calls.filter(([input]) =>
-        requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+      vi.stubGlobal("fetch", fetchMock);
+      const { iframe, element } = createPreviewElement(
+        '<div data-hf-id="hf-card"></div><div id="b"></div><div id="c"></div>',
       );
-      expect(batchPosts).toHaveLength(1);
-      expect(singlePosts).toHaveLength(0);
-      expect(JSON.parse(String(batchPosts[0]?.[1]?.body))).toEqual({
-        batches: [
-          {
-            sourceFile: "index.html",
-            patches: expect.arrayContaining([
-              expect.objectContaining({ target: expect.objectContaining({ id: "a" }) }),
-              expect.objectContaining({ target: expect.objectContaining({ id: "b" }) }),
-              expect.objectContaining({ target: expect.objectContaining({ id: "c" }) }),
-            ]),
-          },
-        ],
-      });
-      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
-      expect(rendered.recordEdit).toHaveBeenCalledWith({
-        label: "Reorder layers",
-        coalesceKey: "z-reorder:test",
-        // Unbounded per-gesture fold window (keys are unique per gesture):
-        // the z entry and its mirror/lane counterpart fold across the server
-        // round-trip that separates them.
-        coalesceMs: Number.POSITIVE_INFINITY,
-        files: { "index.html": { before: original, after } },
-      });
-      // FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
-      // The live DOM + store already hold the final state and the server matched
-      // every style-only patch, so the reload is provably redundant.
-      expect(rendered.reloadPreview).not.toHaveBeenCalled();
-    } finally {
-      rendered.cleanup();
-    }
-  });
+      element.id = "a";
+      const elements = [
+        element,
+        iframe.contentDocument!.getElementById("b")!,
+        iframe.contentDocument!.getElementById("c")!,
+      ];
+      const rendered = renderDomEditCommits(createSelection(element), iframe, { readOnlyPreview });
+
+      try {
+        await act(async () => {
+          await rendered.hook.handleDomZIndexReorderCommit(
+            elements.map((item, index) => ({
+              element: item,
+              zIndex: 3 - index,
+              id: item.id,
+              sourceFile: "index.html",
+            })),
+            "z-reorder:test",
+          );
+        });
+
+        const batchPosts = fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
+        );
+        const singlePosts = fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+        );
+        expect(batchPosts).toHaveLength(1);
+        expect(singlePosts).toHaveLength(0);
+        expect(JSON.parse(String(batchPosts[0]?.[1]?.body))).toEqual({
+          batches: [
+            {
+              sourceFile: "index.html",
+              patches: expect.arrayContaining([
+                expect.objectContaining({ target: expect.objectContaining({ id: "a" }) }),
+                expect.objectContaining({ target: expect.objectContaining({ id: "b" }) }),
+                expect.objectContaining({ target: expect.objectContaining({ id: "c" }) }),
+              ]),
+            },
+          ],
+        });
+        expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+        expect(rendered.recordEdit).toHaveBeenCalledWith({
+          label: "Reorder layers",
+          coalesceKey: "z-reorder:test",
+          // Unbounded per-gesture fold window (keys are unique per gesture):
+          // the z entry and its mirror/lane counterpart fold across the server
+          // round-trip that separates them.
+          coalesceMs: Number.POSITIVE_INFINITY,
+          files: { "index.html": { before: original, after } },
+        });
+        // FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
+        // The live DOM + store already hold the final state and the server matched
+        // every style-only patch, so the reload is provably redundant.
+        expect(rendered.reloadPreview).not.toHaveBeenCalled();
+      } finally {
+        rendered.cleanup();
+      }
+    },
+  );
 
   it("falls back to reloading when the server response omits matched[]", async () => {
     // Without a matched[] confirmation the persist can't be proven in sync with

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");
+});