@hyperframes/studio 0.8.114 → 0.8.116

package/src/hooks/usePersistentEditHistory.test.ts

@@ -88,6 +88,234 @@ it("an edit Studio saved is undone and redone by the project's history, with the
   expect(file()).toBe("B");
 });
 
+it("undoes the edit claimed since the key, not a later edit the server took in first", async () => {
+  const { dir, hook, file, save, readFile } = await studio();
+  const atKey = hook().claims();
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  writeFileSync(join(dir, "card.html"), "Y");
+  const later = hook().recordEdit({
+    label: "Added Card",
+    files: { "card.html": { before: "", after: "Y" } },
+  });
+  const afterLater = async <T>(_paths: readonly string[], task: () => Promise<T>) => {
+    await later;
+    return task();
+  };
+
+  const undone = await act(() =>
+    hook().undo({ readFile, serialize: afterLater, claimedAfter: atKey }),
+  );
+  expect(undone).toMatchObject({ ok: true, label: "Undid: Moved Title" });
+  expect(file()).toBe("A");
+  expect(readFileSync(join(dir, "card.html"), "utf8")).toBe("Y");
+});
+
+it("a second undo pressed while the same edit saves undoes the edit before it", async () => {
+  const { hook, file, save, readFile } = await studio();
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  await vi.waitFor(() => expect(hook().undoLabel).toBe("Moved Title"));
+  const atKey = hook().claims();
+  save("C");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Card",
+      files: { "index.html": { before: "B", after: "C" } },
+    }),
+  );
+
+  let queue: Promise<unknown> = Promise.resolve();
+  const serialize = <T>(_paths: readonly string[], task: () => Promise<T>) => {
+    const run = queue.then(task);
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const press = () => hook().undo({ readFile, claimedAfter: atKey, serialize });
+
+  const [first, second] = await act(() => Promise.all([press(), press()]));
+
+  expect([first, second]).toMatchObject([
+    { ok: true, label: "Undid: Moved Card" },
+    { ok: true, label: "Undid: Moved Title" },
+  ]);
+  expect(file()).toBe("A");
+});
+
+it("keeps the claim when its undo fails, so the next press targets that edit again", async () => {
+  const { hook, save, readFile } = await studio();
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  await vi.waitFor(() => expect(hook().undoLabel).toBe("Moved Title"));
+  const atKey = hook().claims();
+  save("C");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Card",
+      files: { "index.html": { before: "B", after: "C" } },
+    }),
+  );
+  const posted: string[] = [];
+  const fetch = globalThis.fetch;
+  vi.stubGlobal("fetch", (url: string, init?: RequestInit) => {
+    if (init?.method === "POST") posted.push(url.slice(url.lastIndexOf("/") + 1));
+    return fetch(url, init);
+  });
+
+  save("edited elsewhere");
+  const failed = await act(() => hook().undo({ readFile, claimedAfter: atKey }));
+  save("C");
+  const retried = await act(() => hook().undo({ readFile, claimedAfter: atKey }));
+
+  expect(failed.ok).toBe(false);
+  expect(retried).toMatchObject({ ok: true, label: "Undid: Moved Card" });
+  expect(posted.filter((p) => p === "undo" || p === "step")).toEqual(["undo", "undo"]);
+});
+
+it("does not undo again an edit another press already undid", async () => {
+  const { hook, file, save, readFile } = await studio();
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  await vi.waitFor(() => expect(hook().undoLabel).toBe("Moved Title"));
+  const atKey = hook().claims();
+  save("C");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Card",
+      files: { "index.html": { before: "B", after: "C" } },
+    }),
+  );
+  let calls = 0;
+  let queue: Promise<unknown> = Promise.resolve();
+  const serialize = <T>(_paths: readonly string[], task: () => Promise<T>) => {
+    calls += 1;
+    if (calls === 1) return Promise.reject(new Error("save failed"));
+    const run = queue.then(task);
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const press = () => hook().undo({ readFile, claimedAfter: atKey, serialize });
+
+  const [first, second] = await act(() => Promise.allSettled([press(), press()]));
+  const third = await act(() => press());
+
+  expect(first.status).toBe("rejected");
+  expect(second).toMatchObject({
+    status: "fulfilled",
+    value: { ok: true, label: "Undid: Moved Card" },
+  });
+  expect(third).toMatchObject({ ok: true, label: "Undid: Moved Title" });
+  expect(file()).toBe("A");
+});
+
+it("does not undo again an edit a later press undid first", async () => {
+  const { hook, file, save, readFile } = await studio();
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  await vi.waitFor(() => expect(hook().undoLabel).toBe("Moved Title"));
+  const atKey = hook().claims();
+  save("C");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Card",
+      files: { "index.html": { before: "B", after: "C" } },
+    }),
+  );
+  let fail!: (error: Error) => void;
+  const held = <T>(_paths: readonly string[], _task: () => Promise<T>) =>
+    new Promise<T>((_resolve, reject) => {
+      fail = reject;
+    });
+  const failed = hook()
+    .undo({ readFile, claimedAfter: atKey, serialize: held })
+    .catch(() => undefined);
+
+  const second = await act(() => hook().undo({ readFile, claimedAfter: atKey }));
+  fail(new Error("save failed"));
+  await failed;
+  const third = await act(() => hook().undo({ readFile, claimedAfter: atKey }));
+
+  expect(second).toMatchObject({ ok: true, label: "Undid: Moved Card" });
+  expect(third).toMatchObject({ ok: true, label: "Undid: Moved Title" });
+  expect(file()).toBe("A");
+});
+
+it("refuses a second press whose edit is undone once an edit was made after the press", async () => {
+  const { dir, hook, file, save, readFile } = await studio();
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  await vi.waitFor(() => expect(hook().undoLabel).toBe("Moved Title"));
+  const atKey = hook().claims();
+  save("C");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Card",
+      files: { "index.html": { before: "B", after: "C" } },
+    }),
+  );
+  let open!: () => void;
+  const opened = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+  let queue: Promise<unknown> = Promise.resolve();
+  let queued = 0;
+  const serialize = <T>(_paths: readonly string[], task: () => Promise<T>) => {
+    queued += 1;
+    const wait = queued === 2 ? opened : Promise.resolve();
+    const run = queue.then(() => wait).then(task);
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const press = () => hook().undo({ readFile, claimedAfter: atKey, serialize });
+  const presses = Promise.all([press(), press()]);
+  await vi.waitFor(() => expect(file()).toBe("B"));
+  writeFileSync(join(dir, "card.html"), "Y");
+  await act(() =>
+    hook().recordEdit({
+      label: "Added Card",
+      files: { "card.html": { before: "", after: "Y" } },
+    }),
+  );
+
+  open();
+  const [first, second] = await act(() => presses);
+
+  expect(first).toMatchObject({ ok: true, label: "Undid: Moved Card" });
+  expect(second).toMatchObject({ ok: false, reason: "content-mismatch" });
+  expect(readFileSync(join(dir, "card.html"), "utf8")).toBe("Y");
+  expect(file()).toBe("B");
+});
+
 it("a drag's edits under one key undo as one step, even before the drag goes idle", async () => {
   const { hook, file, save, readFile } = await studio();
   const writes: Array<[before: string, after: string]> = [
@@ -115,6 +343,32 @@ it("a drag's edits under one key undo as one step, even before the drag goes idl
   expect(file()).toBe("A");
 });
 
+it("an undo before the history view shows a drag's held claim still waits on the files it wrote", async () => {
+  const { hook, save, readFile } = await studio();
+  const server = globalThis.fetch;
+  vi.stubGlobal("fetch", (url: string, init?: RequestInit) =>
+    init?.method === "POST"
+      ? server(url, init)
+      : Promise.resolve(new Response(null, { status: 503 })),
+  );
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Dragged Title",
+      coalesceKey: "drag",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  let waitedOn: readonly string[] = [];
+  const serialize = <T>(paths: readonly string[], task: () => Promise<T>) => {
+    waitedOn = paths;
+    return task();
+  };
+
+  await act(() => hook().undo({ readFile, serialize }));
+  expect(waitedOn).toEqual(["index.html"]);
+});
+
 it("an agent's edit made seconds before Studio's stays the agent's: Cmd+Z undoes only Studio's", async () => {
   const { hook, file, save, readFile } = await studio();
   save("B");
@@ -159,7 +413,11 @@ it("without a history on the server an edit still saves, and there is nothing to
 });
 
 /** Answers requests to `route` with `reply` instead of the engine, every other request as before; returns the undo. */
-function answer(route: "/history/step" | "/history/claim", status: number, reply: object | string) {
+function answer(
+  route: "/history" | "/history/step" | "/history/claim",
+  status: number,
+  reply: object | string,
+) {
   const real = globalThis.fetch;
   vi.stubGlobal("fetch", (url: string, init?: RequestInit) =>
     url.endsWith(route)
@@ -230,6 +488,24 @@ it("a step whose reply cannot be read says so, instead of throwing", async () =>
   });
 });
 
+it("an edit whose history reply cannot be read is still saved, and the reply is its own error", async () => {
+  const { hook, file, save } = await studio();
+  const logged = vi.spyOn(console, "error").mockImplementation(() => {});
+  cleanup.push(() => logged.mockRestore());
+  answer("/history", 200, "<html>");
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Moved Title",
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+  await vi.waitFor(() =>
+    expect(logged).toHaveBeenCalledWith("The history's reply was unreadable."),
+  );
+  expect(file()).toBe("B");
+});
+
 it("a step that cannot reach the server says so", async () => {
   const { hook, readFile } = await studio();
   const real = globalThis.fetch;

package/src/hooks/usePersistentEditHistory.ts

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { HistoryListItem, HistoryResult } from "@hyperframes/studio-server";
 import { studioFileContentVersion, studioWriteHeaders } from "../utils/studioFileVersion";
 import type { RestoreFiles } from "../utils/gsapUndoRestore";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface RecordEditInput {
   label: string;
@@ -13,6 +14,7 @@ interface RecordEditInput {
 interface ApplyCallbacks {
   readFile: (path: string) => Promise<string>;
   serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
+  claimedAfter?: number;
 }
 
 export interface UsePersistentEditHistoryOptions {
@@ -53,6 +55,8 @@ function createOwnHistory() {
   const own = new Map<string, OwnFiles>();
   let next: Record<"undo" | "redo", NextStep | null> | null = null;
   let changes = 0;
+  let claimed = { count: 0, id: "" };
+  const undoneIds = new Set<string>();
   const remember = (id: string, files: OwnFiles) => {
     const known = own.get(id) ?? {};
     for (const [path, { before, after }] of Object.entries(files)) {
@@ -73,7 +77,16 @@ function createOwnHistory() {
       if (seen === changes) next = { undo: view.back, redo: view.forward };
     },
     changes: () => changes,
+    claimCount: () => claimed.count,
+    claimedAfter: (count: number) => (claimed.count > count && claimed.id ? claimed.id : null),
+    targetFor: (id: string | null, pressedAt: number) =>
+      !id || !undoneIds.has(id) ? id : claimed.count > pressedAt ? false : null,
+    noteClaim: (id: string) => {
+      claimed = { count: claimed.count + 1, id };
+    },
     stepped: (entry: { id: string; undoes?: string }) => {
+      if (entry.undoes) undoneIds.add(entry.undoes);
+      if (undoneIds.size > OWN_ENTRIES_KEPT) undoneIds.delete(undoneIds.values().next().value!);
       const undone = entry.undoes ? own.get(entry.undoes) : undefined;
       if (!undone) return;
       const swapped = Object.entries(undone).map(([path, f]) => [
@@ -102,6 +115,7 @@ function createOwnHistory() {
     },
     clear: () => {
       own.clear();
+      undoneIds.clear();
       next = null;
       changes += 1;
     },
@@ -113,12 +127,20 @@ function historyUrl(projectId: string, path = ""): string {
   return `/api/projects/${encodeURIComponent(projectId)}/history${path}`;
 }
 
+async function cantUndo(paths: string[] | undefined): Promise<ApplyResult> {
+  return { ok: false, reason: "content-mismatch", paths: paths ?? [] };
+}
+
+function unionPaths(...lists: Array<readonly string[] | undefined>): string[] {
+  return [...new Set(lists.flatMap((list) => list ?? []))];
+}
+
 async function post(
   url: string,
   body: object,
   headers: Record<string, string> = {},
 ): Promise<{ ok: true; body: unknown } | { ok: false; status: number; error: string }> {
-  const response = await fetch(url, {
+  const response = await studioApiFetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json", ...headers },
     body: JSON.stringify(body),
@@ -194,9 +216,12 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   const refresh = useCallback(async () => {
     if (!projectId) return;
     const seen = own.changes();
-    const response = await fetch(historyUrl(projectId)).catch(() => null);
-    const next = response?.ok ? ((await response.json()) as HistoryView) : EMPTY;
+    const response = await studioApiFetch(historyUrl(projectId)).catch(() => null);
+    const next = response?.ok
+      ? ((await response.json().catch(() => null)) as HistoryView | null)
+      : EMPTY;
     if (projectIdRef.current !== projectId) return;
+    if (!next) return console.error("The history's reply was unreadable.");
     setView(next);
     own.offered(seen, next);
   }, [projectId, own]);
@@ -221,7 +246,10 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
         ...(coalesceKey && { coalesceKey, idleMs: coalesceMs ?? DEFAULT_COALESCE_MS }),
       });
       const claimed = claimHeld(reply, label);
-      if (claimed) own.remember(claimed, files);
+      if (claimed) {
+        own.remember(claimed, files);
+        own.noteClaim(claimed);
+      }
       heldClaimRef.current = claimed && coalesceKey ? { paths, at: Date.now() } : null;
       await refresh();
     },
@@ -231,14 +259,20 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   const step = useCallback(
     async (direction: "undo" | "redo", callbacks: ApplyCallbacks): Promise<ApplyResult> => {
       if (!projectId) return { ok: false, reason: "empty" };
+      const candidate =
+        direction === "undo" && callbacks.claimedAfter !== undefined
+          ? own.claimedAfter(callbacks.claimedAfter)
+          : null;
       const next = direction === "undo" ? view.back : view.forward;
-      const paths = [...new Set([...(next?.paths ?? []), ...(heldClaimRef.current?.paths ?? [])])];
+      const stepPaths = candidate ? Object.keys(own.afterOf(candidate)) : next?.paths;
+      const paths = unionPaths(stepPaths, heldClaimRef.current?.paths);
+      const pressedAt = own.claimCount();
       own.overtake();
-      const run = async (): Promise<ApplyResult> => {
+      const attempt = async (target: string | null): Promise<ApplyResult> => {
         const previous = await readAll(paths, callbacks.readFile);
         const posted = await post(
-          historyUrl(projectId, "/step"),
-          { direction: direction === "undo" ? "back" : "forward" },
+          historyUrl(projectId, target ? "/undo" : "/step"),
+          target ? { entryId: target } : { direction: direction === "undo" ? "back" : "forward" },
           studioWriteHeaders(),
         );
         heldClaimRef.current = null;
@@ -266,6 +300,10 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
           ),
         };
       };
+      const run = () => {
+        const target = own.targetFor(candidate, pressedAt);
+        return target === false ? cantUndo(stepPaths) : attempt(target);
+      };
       return callbacks.serialize ? callbacks.serialize(paths, run) : run();
     },
     [projectId, view, refresh, own],
@@ -301,6 +339,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
     undo,
     redo,
     predict: own.predict,
+    claims: own.claimCount,
     noteOutsideChange,
   };
 }

package/src/hooks/usePopulateKeyframeCacheForFile.test.tsx

@@ -8,8 +8,8 @@ import { usePlayerStore } from "../player/store/playerStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
-function HookHost() {
-  usePopulateKeyframeCacheForFile("demo", "index.html", 1);
+function HookHost({ sourceFile = "index.html", version = 1 }) {
+  usePopulateKeyframeCacheForFile("demo", sourceFile, version);
   return null;
 }
 
@@ -67,4 +67,78 @@ describe("usePopulateKeyframeCacheForFile", () => {
     expect(urls.some((u) => u.endsWith("/index.html"))).toBe(true);
     expect(urls.some((u) => u.includes("keyframe-lab.html"))).toBe(true);
   });
+
+  it("keeps every covered file when the selection switches between them, and refetches all on new data", async () => {
+    // Every click on a clip from another file flips `sourceFile`; a flip must not
+    // re-read every composition file, or a multi-select pays files x clicks fetches.
+    const urls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((input: RequestInfo | URL) => {
+        urls.push(String(input));
+        return Promise.resolve({ ok: true, json: () => Promise.resolve({ animations: [] }) });
+      }),
+    );
+    const render = async (props: { sourceFile: string; version: number }) => {
+      await act(async () => {
+        if (!root) {
+          container = document.createElement("div");
+          document.body.appendChild(container);
+          root = createRoot(container);
+        }
+        root.render(<HookHost {...props} />);
+      });
+      await act(async () => {
+        await Promise.resolve();
+      });
+    };
+
+    await render({ sourceFile: "index.html", version: 1 });
+    const loaded = urls.length;
+    await render({ sourceFile: "compositions/keyframe-lab.html", version: 1 });
+    expect(urls.length).toBe(loaded);
+    await render({ sourceFile: "index.html", version: 1 });
+    expect(urls.length).toBe(loaded);
+
+    await render({ sourceFile: "index.html", version: 2 });
+    expect(urls.length).toBe(loaded * 2);
+  });
+
+  it("asks again for a covered file whose first read failed", async () => {
+    const urls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((input: RequestInfo | URL) => {
+        const url = String(input);
+        urls.push(url);
+        const failed =
+          url.includes("keyframe-lab.html") && urls.filter((u) => u === url).length === 1;
+        return Promise.resolve({
+          ok: !failed,
+          json: () => Promise.resolve({ animations: [] }),
+        });
+      }),
+    );
+    const render = async (sourceFile: string) => {
+      await act(async () => {
+        if (!root) {
+          container = document.createElement("div");
+          document.body.appendChild(container);
+          root = createRoot(container);
+        }
+        root.render(<HookHost sourceFile={sourceFile} />);
+      });
+      await act(async () => {
+        await Promise.resolve();
+      });
+    };
+
+    await render("index.html");
+    const labReads = () => urls.filter((u) => u.includes("keyframe-lab.html")).length;
+    expect(labReads()).toBe(1);
+    await render("compositions/keyframe-lab.html");
+    expect(labReads()).toBe(2);
+    await render("index.html");
+    expect(labReads()).toBe(2);
+  });
 });

package/src/hooks/usePreviewInteraction.test.ts

@@ -299,3 +299,24 @@ describe("a refused move's toast", () => {
     ]);
   });
 });
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../utils/studioTelemetry";
+it("counts additive preview selection only after resolving a hit", async () => {
+  vi.mocked(trackStudioEvent).mockClear();
+  const selection = makeSelection("Card", document.createElement("div"));
+  const applyDomSelection = vi.fn();
+  const { canvas, cleanup } = renderHarness({
+    previewIframe: createPreviewIframe(vi.fn()),
+    resolveDomSelectionFromPreviewPoint: vi.fn(async () => selection),
+    applyDomSelection,
+  });
+  await dispatchMouseDown(canvas, { shiftKey: true });
+  expect(applyDomSelection).toHaveBeenCalledWith(selection, { additive: true });
+  expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+    feature: "multi_select",
+    surface: "preview",
+    method: "button",
+  });
+  cleanup();
+});

package/src/hooks/usePreviewInteraction.ts

@@ -1,3 +1,4 @@
+import { trackPreviewFeatureUsed } from "../utils/previewFeatureUsage";
 import { useCallback, useRef } from "react";
 import { liveTime, usePlayerStore } from "../player";
 import { pauseStudioPreviewPlayback } from "../utils/studioPreviewHelpers";
@@ -169,6 +170,7 @@ export function usePreviewInteraction({
         e.preventDefault();
         e.stopPropagation();
         applyDomSelection(nextSelection, { additive: true });
+        trackPreviewFeatureUsed("multi_select", "button");
         return;
       }
 

package/src/hooks/usePreviewPersistence.history.test.tsx

@@ -79,12 +79,13 @@ describe("undo that re-runs the top-level script over an element of a nested com
     };
   }
 
-  async function undo(fileOk: boolean) {
+  async function undo(fileOk: boolean, projectId: string | null = "p1") {
     const { iframe, nwid } = nestedPreview();
     const reloadPreview = vi.fn();
     const fetch = vi.fn(async () => ({ ok: fileOk, json: async () => ({ content: SUB }) }));
     vi.stubGlobal("fetch", fetch);
-    usePlayerStore.getState().beginTimelineSession("p1");
+    if (projectId) usePlayerStore.getState().beginTimelineSession(projectId);
+    else usePlayerStore.setState({ timelineProjectId: null });
     let sync: ReturnType<typeof usePreviewPersistence>["syncHistoryPreviewAfterApply"] | null =
       null;
     function Harness() {
@@ -109,7 +110,9 @@ describe("undo that re-runs the top-level script over an element of a nested com
   it("restores the element from its own composition file", async () => {
     const { nwid, reloadPreview, fetch } = await undo(true);
 
-    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"));
+    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"), {
+      credentials: "omit",
+    });
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(nwid.getAttribute("style")).toBe("left: 40px;");
   });
@@ -120,4 +123,12 @@ describe("undo that re-runs the top-level script over an element of a nested com
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(nwid.getAttribute("style")).toBe("left: 40px; width: 337px");
   });
+
+  it("reloads the preview in full when no project is open to read that file from", async () => {
+    const { nwid, reloadPreview, fetch } = await undo(true, null);
+
+    expect(fetch).not.toHaveBeenCalled();
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(nwid.getAttribute("style")).toBe("left: 40px; width: 337px");
+  });
 });

package/src/hooks/usePreviewPersistence.ts

@@ -163,8 +163,9 @@ export function usePreviewPersistence({
   }, [drainPendingDomEditSaves]);
 
   const settlePendingEdits = useCallback(async (): Promise<void> => {
-    await flushStudioPendingEdits();
-    await domEditSaveQueueRef.current?.waitForIdle();
+    const queued = domEditSaveQueueRef.current?.waitForIdle();
+    await flushStudioPendingEdits({ onlyCurrent: true });
+    await queued;
   }, []);
 
   const resetDomEditSaveQueueBreaker = useCallback(() => {
@@ -209,14 +210,15 @@ export function usePreviewPersistence({
       // multi-file, sub-comp, or a permanent soft-reload failure.
       const projectId = usePlayerStore.getState().timelineProjectId;
       const nestedFiles = await settleNestedReads(
-        projectId
-          ? readUndoNestedFiles(
-              previewIframeRef.current,
-              activeCompPathRef.current,
-              restore.files,
-              (path) => readProjectFileContent(projectId, path),
-            )
-          : null,
+        readUndoNestedFiles(
+          previewIframeRef.current,
+          activeCompPathRef.current,
+          restore.files,
+          (path) =>
+            projectId
+              ? readProjectFileContent(projectId, path)
+              : Promise.reject(new Error("No project is open to read nested files from.")),
+        ),
       );
       const strategy = applyUndoRestoreToPreview(
         previewIframeRef.current,
@@ -258,7 +260,7 @@ export function usePreviewPersistence({
 
   // ── Migrate legacy studio-motion.json ──
   // Projects that used the old JSON-file approach may still have a populated
-  // `.hyperframes/studio-motion.json`. The studio no longer reads from it, but
+  // studio-motion.json in the project's .hyperframes folder. The studio no longer reads it, but
   // the legacy render-script injection in `preview.ts` / `vite.studioMotion.ts`
   // could still fire alongside the new seek-reapply runtime. Empty the file so
   // the legacy codepath no-ops.