@hyperframes/studio 0.8.107 → 0.8.109

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

@@ -206,7 +206,9 @@ it("an undo pressed while a nudge waits for more keys never shows the move befor
   const s = await studio();
   await s.edit();
   resetNudgeKeys();
+  let finish!: () => void;
   const save = vi.fn(async () => {
+    await new Promise<void>((resolve) => (finish = resolve));
     writeFileSync(s.path, NUDGED);
     await s.history().recordEdit({
       label: "Move layer",
@@ -218,12 +220,51 @@ it("an undo pressed while a nudge waits for more keys never shows the move befor
     window.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", cancelable: true }));
   });
 
+  const nudge = () => s.element("box").style.getPropertyValue("translate");
+  expect(nudge()).not.toBe("");
+
   const undone = s.actions().undo();
   expect(s.box()).toBe("50px");
+  expect(nudge()).toBe("");
+  await vi.waitFor(() => expect(save).toHaveBeenCalledTimes(1));
+  expect(nudge()).toBe("");
+  finish();
   await act(() => undone);
   expect(save).toHaveBeenCalledTimes(1);
   expect(s.file()).toBe(AFTER);
   expect(s.box()).toBe("50px");
+  expect(nudge()).toBe("");
+});
+
+it("an undo pressed while a nudge's save is queued shows the nudge undone in the key's own task", async () => {
+  const s = await studio();
+  await s.edit();
+  resetNudgeKeys();
+  let finish!: () => void;
+  const save = vi.fn(async () => {
+    await new Promise<void>((resolve) => (finish = resolve));
+    writeFileSync(s.path, NUDGED);
+    await s.history().recordEdit({
+      label: "Move layer",
+      files: { "index.html": { before: AFTER, after: NUDGED } },
+    });
+  });
+  s.mount(createElement(Nudge, { target: s.element("box"), save }));
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", cancelable: true }));
+  });
+  await vi.waitFor(() => expect(save).toHaveBeenCalledTimes(1));
+  const nudge = () => s.element("box").style.getPropertyValue("translate");
+  expect(nudge()).not.toBe("");
+
+  const undone = s.actions().undo();
+  expect(nudge()).toBe("");
+  expect(s.box()).toBe("50px");
+  finish();
+  await act(() => undone);
+  expect(s.file()).toBe(AFTER);
+  expect(nudge()).toBe("");
+  expect(s.box()).toBe("50px");
 });
 
 it("an undo pressed while a queued save fails undoes the edit before it, file and box alike", async () => {

package/src/hooks/useEditHistoryActions.ts

@@ -3,6 +3,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";
+import { revertNewestStudioPendingEdit } from "../utils/studioPendingEdits";
 
 interface HistoryResult {
   ok: boolean;
@@ -74,7 +75,10 @@ export function useEditHistoryActions({
       const noun = direction === "undo" ? "Undo" : "Redo";
       // 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;
+      const predictedShown = predicted ? (showHistoryRestoreNow?.(predicted.files) ?? null) : null;
+      const pendingEditShown =
+        !predictedShown && direction === "undo" ? revertNewestStudioPendingEdit() : null;
+      const putBack = predictedShown ?? pendingEditShown;
       let result: HistoryResult = { ok: false, reason: "failed" };
       let serverSteppedShown = false;
       try {
@@ -83,8 +87,10 @@ export function useEditHistoryActions({
           readFile: readHistoryFile,
           serialize: serializeHistoryFiles,
         });
-        serverSteppedShown =
-          Boolean(putBack && result.ok && result.label) && result.undoes === predicted?.id;
+        const stepped = Boolean(result.ok && result.label);
+        serverSteppedShown = predictedShown
+          ? stepped && result.undoes === predicted?.id
+          : stepped && Boolean(pendingEditShown);
       } finally {
         if (putBack && !serverSteppedShown) putBack();
       }
@@ -100,7 +106,10 @@ export function useEditHistoryActions({
         return;
       }
       if (result.ok && result.label) {
-        const files = serverSteppedShown ? fromShown(result.files, predicted!.files) : result.files;
+        const files =
+          serverSteppedShown && predictedShown
+            ? fromShown(result.files, predicted!.files)
+            : result.files;
         const restore = { paths: result.paths, files };
         onAfterUndoRedo?.(restore);
         if (activeCompPath && result.paths?.includes(activeCompPath)) {

package/src/hooks/useElementPicker.test.ts

@@ -19,6 +19,22 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
+// The runtime's element-picked message, posted by `from`.
+const picked = (from: Window | null, selector: string) =>
+  act(() => {
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        source: from,
+        data: {
+          source: "hf-preview",
+          type: "element-picked",
+          elementInfo: { selector, tagName: "h1" },
+          ...runtimeProtocolMetadata(30),
+        },
+      }),
+    );
+  });
+
 // The preview page: the saved markup plus what the runtime adds to it.
 function mountPreview(mounted = ""): HTMLIFrameElement {
   const iframe = document.createElement("iframe");
@@ -61,19 +77,7 @@ function mountPicker(
   }
   root = createRoot(document.createElement("div"));
   act(() => root?.render(React.createElement(Harness)));
-  act(() => {
-    window.dispatchEvent(
-      new MessageEvent("message", {
-        source: iframe.contentWindow,
-        data: {
-          source: "hf-preview",
-          type: "element-picked",
-          elementInfo: { selector, tagName: "h1" },
-          ...runtimeProtocolMetadata(30),
-        },
-      }),
-    );
-  });
+  picked(iframe.contentWindow, selector);
   const picker = () => api as ReturnType<typeof useElementPicker>;
   return {
     picker,
@@ -170,3 +174,48 @@ describe("an edit to a picked element without an id", () => {
     expect(synced).toEqual([]);
   });
 });
+
+describe("a pick across a reload that swaps the preview frame", () => {
+  function mountSwapping() {
+    const live = mountPreview();
+    const ref: { current: HTMLIFrameElement | null } = { current: live };
+    let api: ReturnType<typeof useElementPicker> | null = null;
+    function Harness() {
+      api = useElementPicker(ref);
+      return null;
+    }
+    root = createRoot(document.createElement("div"));
+    act(() => root?.render(React.createElement(Harness)));
+    return { live, ref, picker: () => api as ReturnType<typeof useElementPicker> };
+  }
+
+  it("keeps a pick posted by the frame it was made in after a new frame took its place", () => {
+    const { live, ref, picker } = mountSwapping();
+    picked(live.contentWindow, "h1");
+    act(() => picker().clearPick());
+    // The reload promotes its frame before the old frame's pick message is handled.
+    const old = live.contentWindow;
+    ref.current = mountPreview();
+    live.remove();
+    picked(old, "h1.next");
+    expect(picker().pickedElement?.selector).toBe("h1.next");
+  });
+
+  it("does not keep trusting a zoomed frame once the zoom is gone", () => {
+    const { picker } = mountSwapping();
+    const zoom = mountPreview();
+    act(() => picker().setActiveIframe(zoom));
+    picked(zoom.contentWindow, "h1");
+    expect(picker().pickedElement?.selector).toBe("h1");
+    act(() => picker().setActiveIframe(null));
+    picked(zoom.contentWindow, "h1.late");
+    expect(picker().pickedElement?.selector).toBe("h1");
+  });
+
+  it("still ignores a frame it never showed", () => {
+    const { picker } = mountSwapping();
+    const stranger = mountPreview();
+    picked(stranger.contentWindow, "h1");
+    expect(picker().pickedElement).toBeNull();
+  });
+});

package/src/hooks/useElementPicker.ts

@@ -97,6 +97,8 @@ export function useElementPicker(
     setPickedElement(null);
   }, []);
 
+  const windowsThatWerePrimary = useRef(new WeakSet<MessageEventSource>());
+
   // Listen for picker messages from the iframe
   useMountEffect(() => {
     // One guard per message field, then one branch per message type.
@@ -105,10 +107,16 @@ export function useElementPicker(
       const data = e.data;
       if (data?.source !== "hf-preview") return;
       if (!acceptStudioRuntimeMessage(data)) return;
-      // Accept events from either the primary iframe or the active override
+      // The primary frame, the active override, or a primary frame a reload just swapped out.
       const activeIframe = getActiveIframe();
       if (!activeIframe) return;
-      if (e.source !== activeIframe.contentWindow && e.source !== iframeRef.current?.contentWindow)
+      if (!e.source) return;
+      if (e.source === iframeRef.current?.contentWindow)
+        windowsThatWerePrimary.current.add(e.source);
+      else if (
+        e.source !== activeIframe.contentWindow &&
+        !windowsThatWerePrimary.current.has(e.source)
+      )
         return;
 
       if (data.type === "element-picked" && data.elementInfo) {

package/src/hooks/useFreezeFrame.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { requestFreezeFrame } from "./useFreezeFrame";
+
+afterEach(() => vi.unstubAllGlobals());
+
+const element: TimelineElement = {
+  id: "talk",
+  domId: "talk",
+  tag: "video",
+  start: 5,
+  duration: 6,
+  track: 0,
+  parentCompositionStart: 4,
+};
+
+function stubFetch(freezeResponse: { status: number; body: unknown }) {
+  const calls: Array<{ url: string; body: unknown }> = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init?: { body?: string }) => {
+      calls.push({ url, body: init?.body ? JSON.parse(init.body) : null });
+      if (url.includes("/files/")) return new Response(JSON.stringify({ version: "v1" }));
+      return new Response(JSON.stringify(freezeResponse.body), { status: freezeResponse.status });
+    }),
+  );
+  return calls;
+}
+
+describe("requestFreezeFrame", () => {
+  it("posts the clip target, file version and an authored-time playhead", async () => {
+    const calls = stubFetch({ status: 200, body: { before: "a", after: "b", version: "v2" } });
+    const result = await requestFreezeFrame({
+      projectId: "p",
+      path: "scene.html",
+      element,
+      playhead: 7.5,
+    });
+    expect(result).toEqual({ before: "a", after: "b", version: "v2" });
+    const post = calls[1];
+    expect(post?.url).toContain("/file-mutations/freeze-frame");
+    expect(post?.body).toMatchObject({
+      path: "scene.html",
+      expectedVersion: "v1",
+      target: { id: "talk" },
+      playhead: 3.5,
+    });
+  });
+
+  it("surfaces the server's error", async () => {
+    stubFetch({ status: 400, body: { error: "Move the playhead inside a video clip to freeze" } });
+    await expect(
+      requestFreezeFrame({ projectId: "p", path: "index.html", element, playhead: 7 }),
+    ).rejects.toThrow("Move the playhead inside a video clip to freeze");
+  });
+});

package/src/hooks/useFreezeFrame.ts

@@ -0,0 +1,121 @@
+import { useCallback, useRef } from "react";
+import type { TimelineElement } from "../player";
+import { toAuthoredStart } from "../player/store/timelineElement";
+import { buildPatchTarget } from "../utils/timelineElementSplit";
+import { buildProjectApiPath } from "../utils/projectRouting";
+import { markStudioWriteToken } from "../utils/studioFileVersion";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+import type { RecordEditInput } from "../utils/studioFileHistory";
+
+type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
+
+interface FreezeFrameResponse {
+  before: string;
+  after: string;
+  version: string;
+}
+
+function isFreezeFrameResponse(value: unknown): value is FreezeFrameResponse {
+  if (typeof value !== "object" || value === null) return false;
+  const body: Partial<Record<keyof FreezeFrameResponse, unknown>> = value;
+  return (
+    typeof body.before === "string" &&
+    typeof body.after === "string" &&
+    typeof body.version === "string"
+  );
+}
+
+function errorOf(value: unknown): string | null {
+  if (typeof value !== "object" || value === null || !("error" in value)) return null;
+  return typeof value.error === "string" ? value.error : null;
+}
+
+async function readVersion(projectId: string, path: string): Promise<string> {
+  const response = await fetch(
+    buildProjectApiPath(projectId, `/files/${encodeURIComponent(path)}`),
+  );
+  const body: unknown = await response.json().catch(() => null);
+  const version =
+    typeof body === "object" && body !== null && "version" in body ? body.version : null;
+  if (!response.ok || typeof version !== "string") throw new Error(`Could not read ${path}`);
+  return version;
+}
+
+/** POST the freeze to studio-server, which extracts the still and writes the whole edit at once. */
+export async function requestFreezeFrame(input: {
+  projectId: string;
+  path: string;
+  element: TimelineElement;
+  playhead: number;
+}): Promise<FreezeFrameResponse> {
+  const target = buildPatchTarget(input.element);
+  if (!target) throw new Error("This clip has no id to freeze it by");
+  const expectedVersion = await readVersion(input.projectId, input.path);
+  const transactionToken = `freeze:${crypto.randomUUID()}`;
+  markStudioWriteToken(transactionToken);
+  const response = await fetch(
+    buildProjectApiPath(input.projectId, "/file-mutations/freeze-frame"),
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Hyperframes-Write-Token": transactionToken,
+      },
+      body: JSON.stringify({
+        path: input.path,
+        expectedVersion,
+        target,
+        playhead: toAuthoredStart(input.element, input.playhead),
+        transactionToken,
+      }),
+    },
+  );
+  const body: unknown = await response.json().catch(() => null);
+  if (!response.ok || !isFreezeFrameResponse(body)) {
+    throw new Error(errorOf(body) ?? `Freeze frame failed (${response.status})`);
+  }
+  return body;
+}
+
+interface UseFreezeFrameOptions {
+  projectId: string | null;
+  activeCompPath: string | null;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: ProjectFileWriter;
+  observeProjectFileVersion?: (path: string, version: string | null) => void;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  reloadPreview: () => void;
+  forceReloadSdkSession?: () => void;
+  isRecordingRef?: React.RefObject<boolean>;
+}
+
+export function useFreezeFrame(options: UseFreezeFrameOptions) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  return useCallback(async (element: TimelineElement, playhead: number) => {
+    const opts = optionsRef.current;
+    if (opts.isRecordingRef?.current) {
+      opts.showToast("Cannot edit timeline while recording", "error");
+      return;
+    }
+    const projectId = opts.projectId;
+    if (!projectId) return;
+    const path = element.sourceFile || opts.activeCompPath || "index.html";
+    try {
+      await serializeStudioFileMutations(opts.writeProjectFile, [path], async () => {
+        const result = await requestFreezeFrame({ projectId, path, element, playhead });
+        await opts.recordEdit({
+          label: "Freeze frame",
+          files: { [path]: { before: result.before, after: result.after } },
+        });
+        opts.observeProjectFileVersion?.(path, result.version);
+      });
+      opts.forceReloadSdkSession?.();
+      opts.reloadPreview();
+      opts.showToast(`Froze a 2 s still at ${playhead.toFixed(2)}s`, "info");
+    } catch (error) {
+      opts.showToast(error instanceof Error ? error.message : "Freeze frame failed", "error");
+    }
+  }, []);
+}

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -10,13 +10,16 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 const patchRuntimeTweenInPlace = vi.fn<(...args: unknown[]) => boolean>();
 const applySoftReload = vi.fn<(...args: unknown[]) => string>();
 const trackStudioEvent = vi.fn();
+const readNestedFiles = vi.fn<(...args: unknown[]) => unknown>(() => null);
 
 vi.mock("./gsapRuntimePatch", () => ({
   patchRuntimeTweenInPlace: (...args: unknown[]) => patchRuntimeTweenInPlace(...args),
 }));
-vi.mock("../utils/gsapSoftReload", () => ({
+vi.mock("../utils/gsapSoftReload", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../utils/gsapSoftReload")>()),
   applySoftReload: (...args: unknown[]) => applySoftReload(...args),
   extractGsapScriptText: () => "",
+  readNestedFiles: (...args: unknown[]) => readNestedFiles(...args),
 }));
 vi.mock("../utils/studioTelemetry", () => ({
   trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
@@ -364,6 +367,7 @@ let cleanup: (() => void) | null = null;
 function renderCommitHook(
   options: {
     writeProjectFile?: (path: string, content: string) => Promise<void>;
+    iframe?: HTMLIFrameElement;
   } = {},
 ) {
   const reloadPreview = vi.fn();
@@ -378,7 +382,7 @@ function renderCommitHook(
     captured.api = useGsapScriptCommits({
       projectIdRef: { current: "proj-1" },
       activeCompPath: "index.html",
-      previewIframeRef: { current: FAKE_IFRAME },
+      previewIframeRef: { current: options.iframe ?? FAKE_IFRAME },
       editHistory: { recordEdit },
       reloadPreview,
       onCacheInvalidate,
@@ -578,6 +582,7 @@ describe("runCommit — instantPatch wiring", () => {
     patchRuntimeTweenInPlace.mockReset();
     applySoftReload.mockReset();
     trackStudioEvent.mockReset();
+    readNestedFiles.mockReset().mockReturnValue(null);
   });
   afterEach(() => {
     cleanup?.();
@@ -585,6 +590,83 @@ describe("runCommit — instantPatch wiring", () => {
     vi.unstubAllGlobals();
   });
 
+  const NESTED_SCRIPT = 'window.__timelines["root"] = tl;';
+  const SUB = `<template><div data-composition-id="sub"><div id="nwid" style="left: 40px"></div></div></template>`;
+
+  // A preview whose top-level timeline tweens an element written in a nested composition file.
+  function nestedPreview(): HTMLIFrameElement {
+    const doc = document.implementation.createHTMLDocument("");
+    doc.body.innerHTML = `<div data-composition-id="root"><div data-composition-file="compositions/sub.html"><div id="nwid"></div></div></div>`;
+    const nwid = doc.getElementById("nwid")!;
+    const tween = { targets: () => [nwid], vars: { width: 400 } };
+    return {
+      contentDocument: doc,
+      contentWindow: { __timelines: { root: { getChildren: () => [tween] } } },
+    } as unknown as HTMLIFrameElement;
+  }
+
+  // The mutation endpoint answers the commit; the files endpoint serves the nested file, or fails.
+  function mockServer(fileOk: boolean): ReturnType<typeof vi.fn> {
+    const body = {
+      ok: true,
+      changed: true,
+      before: "BEFORE",
+      after: "AFTER",
+      scriptText: NESTED_SCRIPT,
+    };
+    const fetch = vi.fn(async (url: string) =>
+      url.includes("/files/")
+        ? ({ ok: fileOk, json: async () => ({ content: SUB }) } as unknown as Response)
+        : ({ ok: true, json: async () => body } as unknown as Response),
+    );
+    vi.stubGlobal("fetch", fetch);
+    return fetch;
+  }
+
+  async function useRealNestedRead() {
+    const actual =
+      await vi.importActual<typeof import("../utils/gsapSoftReload")>("../utils/gsapSoftReload");
+    readNestedFiles.mockImplementation((...args) =>
+      actual.readNestedFiles(...(args as Parameters<typeof actual.readNestedFiles>)),
+    );
+  }
+
+  it("hands the soft reload the nested composition file it read for a reset element", async () => {
+    await useRealNestedRead();
+    applySoftReload.mockReturnValue("applied");
+    const fetch = mockServer(true);
+    const deps = renderCommitHook({ iframe: nestedPreview() });
+
+    await act(async () => {
+      await deps.api.commitMutation(selection, { x: 10 }, { label: "drag", softReload: true });
+    });
+
+    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"));
+    expect(applySoftReload).toHaveBeenCalledWith(
+      expect.anything(),
+      NESTED_SCRIPT,
+      expect.objectContaining({ nestedFiles: new Map([["compositions/sub.html", SUB]]) }),
+    );
+  });
+
+  it("reloads the preview in full when that nested file cannot be read", async () => {
+    await useRealNestedRead();
+    applySoftReload.mockReturnValue("cannot-soft-reload");
+    mockServer(false);
+    const deps = renderCommitHook({ iframe: nestedPreview() });
+
+    await act(async () => {
+      await deps.api.commitMutation(selection, { x: 10 }, { label: "drag", softReload: true });
+    });
+
+    expect(applySoftReload).toHaveBeenCalledWith(
+      expect.anything(),
+      NESTED_SCRIPT,
+      expect.objectContaining({ nestedFiles: null }),
+    );
+    expect(deps.reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
   it("instantPatch succeeds: persists, invalidates cache, NO reload", async () => {
     patchRuntimeTweenInPlace.mockReturnValue(true);
     mockFetchResult();

package/src/hooks/useGsapScriptCommits.ts

@@ -3,7 +3,12 @@ import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mu
 import { readProjectFileContent as readSharedProjectFileContent } from "../utils/studioFileHistory";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { applySoftReload, extractGsapScriptText } from "../utils/gsapSoftReload";
+import {
+  applySoftReload,
+  extractGsapScriptText,
+  readNestedFiles,
+  settleNestedReads,
+} from "../utils/gsapSoftReload";
 import type { SoftReloadResult } from "../utils/gsapSoftReload";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordinator";
@@ -142,9 +147,10 @@ function refreshMutationPreview(
   options: CommitMutationOptions,
   reloadPreview: () => void,
   onCacheInvalidate: () => void,
+  nestedFiles?: Map<string, string> | null,
 ): void {
   options.beforeReload?.();
-  applyPreviewSync(iframe, result, options, reloadPreview);
+  applyPreviewSync(iframe, result, options, reloadPreview, nestedFiles);
   onCacheInvalidate();
 }
 
@@ -168,6 +174,7 @@ function syncCommittedGsapMutation({
   forceReloadSdkSession,
   reloadPreview,
   onCacheInvalidate,
+  nestedFiles,
 }: {
   iframe: HTMLIFrameElement | null;
   selection: DomEditSelection;
@@ -179,6 +186,7 @@ function syncCommittedGsapMutation({
   forceReloadSdkSession?: () => void;
   reloadPreview: () => void;
   onCacheInvalidate: () => void;
+  nestedFiles?: Map<string, string> | null;
 }): void {
   if (result.after != null) onFileContentChanged?.(targetPath, result.after);
   // Server wrote the file; the in-memory SDK doc is now stale. Resync it so a
@@ -196,7 +204,7 @@ function syncCommittedGsapMutation({
       iframe?.contentDocument,
     );
   }
-  refreshMutationPreview(iframe, result, options, reloadPreview, onCacheInvalidate);
+  refreshMutationPreview(iframe, result, options, reloadPreview, onCacheInvalidate, nestedFiles);
 }
 
 /**
@@ -219,6 +227,7 @@ function softReloadOrEscalate(
   reloadPreview: () => void,
   origin: "preview_sync" | "sdk_refresh",
   authoredHtml?: string,
+  nestedFiles?: Map<string, string> | null,
 ): void {
   // Seek the rebuilt timeline to the studio's own authoritative scrub position,
   // not the iframe's raw `__player.getTime()` — see the comment in
@@ -228,6 +237,7 @@ function softReloadOrEscalate(
     onAsyncFailure: reloadPreview,
     currentTimeOverride: currentTime,
     authoredHtml,
+    nestedFiles,
   });
   if (result === "applied") return;
   trackStudioEvent("gsap_soft_reload_outcome", {
@@ -252,6 +262,7 @@ export function applyPreviewSync(
   result: MutationResult,
   options: CommitMutationOptions,
   reloadPreview: () => void,
+  nestedFiles?: Map<string, string> | null,
 ): void {
   const patches = instantPatchesFor(options);
   let needsFallback = options.previewFallbackLatch?.pending === true;
@@ -297,6 +308,7 @@ export function applyPreviewSync(
       reloadPreview,
       "preview_sync",
       result.after ?? undefined,
+      nestedFiles,
     );
   } else {
     reloadPreview();
@@ -349,6 +361,13 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       return;
     }
     await recordMutationEdit(targetPath, result, options);
+    const nestedFiles = await settleNestedReads(
+      result.scriptText
+        ? readNestedFiles(previewIframeRef.current, result.scriptText, (path) =>
+            readSharedProjectFileContent(projectId, path),
+          )
+        : null,
+    );
     // The durable mutation belongs to the project captured when it was queued.
     // A later project must never receive its file state or preview refresh.
     if (!isActiveCommitTarget(projectIdRef, activeCompPathRef, projectId, compositionPath)) return;
@@ -363,6 +382,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       forceReloadSdkSession,
       reloadPreview,
       onCacheInvalidate,
+      nestedFiles,
     });
   }, [projectIdRef, previewIframeRef, reloadPreview, onCacheInvalidate, onFileContentChanged, forceReloadSdkSession, recordMutationEdit]);
 

package/src/hooks/usePersistentEditHistory.test.ts

@@ -243,8 +243,14 @@ it("a step that cannot reach the server says so", async () => {
   });
 });
 
-it("predicts a step from what this tab wrote, and not while a claim or step may have moved the history", async () => {
+it("predicts a step from what this tab wrote as soon as its save ends, and not while a claim or step may have moved the history", async () => {
   const { hook, save, readFile } = await studio();
+  const real = globalThis.fetch;
+  const slowView = (url: string, init?: RequestInit) =>
+    url.endsWith("/history")
+      ? new Promise((r) => setTimeout(r, 50)).then(() => real(url, init))
+      : real(url, init);
+  vi.stubGlobal("fetch", slowView);
   save("B");
   const claim = hook().recordEdit({
     label: "Moved Title",
@@ -252,11 +258,8 @@ it("predicts a step from what this tab wrote, and not while a claim or step may
   });
   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!;
-  });
+  const predicted = hook().predict("undo")!;
+  expect(predicted?.files).toEqual({ "index.html": { previous: "B", restored: "A" } });
 
   hook().noteOutsideChange();
   expect(hook().predict("undo")).toBeNull();

package/src/hooks/usePersistentEditHistory.ts

@@ -223,7 +223,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
       const claimed = claimHeld(reply, label);
       if (claimed) own.remember(claimed, files);
       heldClaimRef.current = claimed && coalesceKey ? { paths, at: Date.now() } : null;
-      void refresh();
+      await refresh();
     },
     [projectId, refresh, own],
   );