@hyperframes/studio 0.7.58 → 0.7.60

package/src/hooks/usePersistentEditHistory.ts

@@ -30,6 +30,7 @@ interface RecordEditInput {
 interface ApplyCallbacks {
   readFile: (path: string) => Promise<string>;
   writeFile: (path: string, content: string) => Promise<void>;
+  serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
 }
 
 interface UsePersistentEditHistoryOptions {
@@ -167,31 +168,32 @@ async function applyHistoryStep(
   if (!entry) {
     return { state: currentState, result: { ok: false, reason: "empty" } };
   }
-  const { currentFiles, currentHashes } = await readCurrentFileHashes(
-    Object.keys(entry.files),
-    callbacks.readFile,
-  );
-  const result = transition(currentState, currentHashes, now());
-  if (!result.ok) {
+  const paths = Object.keys(entry.files);
+  const apply = async (): Promise<{ state: EditHistoryState; result: ApplyResult }> => {
+    const { currentFiles, currentHashes } = await readCurrentFileHashes(paths, callbacks.readFile);
+    const result = transition(currentState, currentHashes, now());
+    if (!result.ok) {
+      return {
+        state: currentState,
+        result: { ok: false, reason: result.reason },
+      };
+    }
+    await writeFilesWithRollback({
+      files: result.filesToWrite,
+      rollbackFiles: currentFiles,
+      writeFile: callbacks.writeFile,
+    });
     return {
-      state: currentState,
-      result: { ok: false, reason: result.reason },
+      state: result.state,
+      result: {
+        ok: true,
+        label: result.entry.label,
+        paths: Object.keys(result.entry.files),
+        files: restoredFilesMap(result.filesToWrite, currentFiles),
+      },
     };
-  }
-  await writeFilesWithRollback({
-    files: result.filesToWrite,
-    rollbackFiles: currentFiles,
-    writeFile: callbacks.writeFile,
-  });
-  return {
-    state: result.state,
-    result: {
-      ok: true,
-      label: result.entry.label,
-      paths: Object.keys(result.entry.files),
-      files: restoredFilesMap(result.filesToWrite, currentFiles),
-    },
   };
+  return callbacks.serialize ? callbacks.serialize(paths, apply) : apply();
 }
 
 export function createPersistentEditHistoryStore({
@@ -305,11 +307,15 @@ export function usePersistentEditHistory(options: UsePersistentEditHistoryOption
   const [loaded, setLoaded] = useState(false);
   const projectId = options.projectId;
   const storeRef = useRef<ReturnType<typeof createPersistentEditHistoryStore> | null>(null);
+  const storeProjectIdRef = useRef<string | null>(null);
+  const activeProjectIdRef = useRef(projectId);
+  activeProjectIdRef.current = projectId;
 
   useEffect(() => {
     let cancelled = false;
     const emptyState = createEmptyEditHistory();
     storeRef.current = null;
+    storeProjectIdRef.current = null;
     setState(emptyState);
     setLoaded(false);
     if (!projectId) {
@@ -327,6 +333,7 @@ export function usePersistentEditHistory(options: UsePersistentEditHistoryOption
           now,
           onChange: setState,
         });
+        storeProjectIdRef.current = projectId;
         setState(loadedState);
       })
       .catch(() => {
@@ -338,6 +345,7 @@ export function usePersistentEditHistory(options: UsePersistentEditHistoryOption
           now,
           onChange: setState,
         });
+        storeProjectIdRef.current = projectId;
         setState(emptyState);
       })
       .finally(() => {
@@ -349,17 +357,49 @@ export function usePersistentEditHistory(options: UsePersistentEditHistoryOption
     };
   }, [now, projectId, storage]);
 
-  const recordEdit = useCallback(async (input: RecordEditInput) => {
-    await storeRef.current?.recordEdit(input);
-  }, []);
+  const recordEdit = useCallback(
+    async (input: RecordEditInput) => {
+      if (!projectId) return;
+      if (activeProjectIdRef.current !== projectId) {
+        throw new Error(`Cannot record an edit for inactive project ${projectId}`);
+      }
+      const store = storeRef.current;
+      if (!store) return;
+      if (storeProjectIdRef.current !== projectId) {
+        throw new Error(`Edit history store does not belong to project ${projectId}`);
+      }
+      await store.recordEdit(input);
+    },
+    [projectId],
+  );
 
-  const undo = useCallback(async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
-    return storeRef.current?.undo(callbacks) ?? { ok: false, reason: "empty" };
-  }, []);
+  const undo = useCallback(
+    async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
+      if (
+        !projectId ||
+        activeProjectIdRef.current !== projectId ||
+        storeProjectIdRef.current !== projectId
+      ) {
+        return { ok: false, reason: "empty" };
+      }
+      return storeRef.current?.undo(callbacks) ?? { ok: false, reason: "empty" };
+    },
+    [projectId],
+  );
 
-  const redo = useCallback(async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
-    return storeRef.current?.redo(callbacks) ?? { ok: false, reason: "empty" };
-  }, []);
+  const redo = useCallback(
+    async (callbacks: ApplyCallbacks): Promise<ApplyResult> => {
+      if (
+        !projectId ||
+        activeProjectIdRef.current !== projectId ||
+        storeProjectIdRef.current !== projectId
+      ) {
+        return { ok: false, reason: "empty" };
+      }
+      return storeRef.current?.redo(callbacks) ?? { ok: false, reason: "empty" };
+    },
+    [projectId],
+  );
 
   return {
     loaded,

package/src/hooks/usePreviewPersistence.ts

@@ -133,7 +133,10 @@ export function usePreviewPersistence({
   if (!domEditSaveQueueRef.current) {
     domEditSaveQueueRef.current = createDomEditSaveQueue({
       onOpen: (event) => {
-        const message = "Auto-save is paused. Check your connection.";
+        const message =
+          event.statusCode === 409
+            ? "Save paused: this file changed elsewhere. Reload and review the latest version before reapplying your edit."
+            : "Auto-save is paused. Check your connection.";
         setDomEditSaveQueuePaused(message);
         showToastRef.current(message, "error");
         trackStudioEvent("save_queue_paused", {

package/src/hooks/useProjectCompositionVariables.ts

@@ -103,17 +103,16 @@ export function useEditVariablesInFile(deps: EditVariablesDeps) {
   return useCallback(
     async (path: string, label: string, mutate: (session: Composition) => void): Promise<void> => {
       const originalContent = await readProjectFile(path);
-      const comp = await openComposition(originalContent, { history: false });
-      let after: string;
-      try {
-        mutate(comp);
-        after = comp.serialize();
-      } finally {
-        comp.dispose();
-      }
-      if (after === originalContent) return;
       await persistSdkSerialize(
-        after,
+        async (onDiskBefore) => {
+          const comp = await openComposition(onDiskBefore, { history: false });
+          try {
+            mutate(comp);
+            return comp.serialize();
+          } finally {
+            comp.dispose();
+          }
+        },
         path,
         originalContent,
         {
@@ -122,6 +121,7 @@ export function useEditVariablesInFile(deps: EditVariablesDeps) {
           reloadPreview,
           domEditSaveTimestampRef,
           compositionPath: path,
+          readProjectFile,
         },
         { label },
       );

package/src/hooks/useProjectSignaturePoll.test.tsx

@@ -0,0 +1,135 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useProjectSignaturePoll } from "./useProjectSignaturePoll";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+function HookHost({
+  signature,
+  onChange,
+}: {
+  signature: string | undefined;
+  onChange: () => void;
+}) {
+  useProjectSignaturePoll("demo", signature, onChange);
+  return null;
+}
+
+let root: Root | null = null;
+let container: HTMLElement | null = null;
+
+function mount(signature: string | undefined, onChange: () => void): void {
+  act(() => {
+    if (!root) {
+      container = document.createElement("div");
+      document.body.appendChild(container);
+      root = createRoot(container);
+    }
+    root.render(<HookHost signature={signature} onChange={onChange} />);
+  });
+}
+
+function unmount(): void {
+  if (root) {
+    act(() => root?.unmount());
+    root = null;
+  }
+  container?.remove();
+  container = null;
+}
+
+function mockSignatureResponse(signature: string): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ signature }) }));
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("useProjectSignaturePoll", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    unmount();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("fires onChange when the polled signature moves past the loaded one", async () => {
+    const fetchMock = mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/demo/signature");
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("stays quiet while the polled signature matches", async () => {
+    mockSignatureResponse("sig-a");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("does not poll before a baseline signature exists", async () => {
+    const fetchMock = mockSignatureResponse("sig-a");
+    const onChange = vi.fn();
+    mount(undefined, onChange);
+
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("re-arms against the caller's refreshed signature without re-mounting", async () => {
+    mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    // The caller refetched and now holds the polled signature — no more firing.
+    mount("sig-b", onChange);
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips ticks while the tab is hidden and re-checks on visibility", async () => {
+    const fetchMock = mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    let hidden = true;
+    vi.spyOn(document, "hidden", "get").mockImplementation(() => hidden);
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    hidden = false;
+    await act(async () => {
+      document.dispatchEvent(new Event("visibilitychange"));
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops polling after unmount", async () => {
+    mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    unmount();
+    await vi.advanceTimersByTimeAsync(10_000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useProjectSignaturePoll.ts

@@ -0,0 +1,68 @@
+import { useEffect, useRef } from "react";
+import { buildProjectApiPath } from "../utils/projectRouting";
+
+const POLL_INTERVAL_MS = 2000;
+
+/** One poll: the current signature, or null on any failure (skip this tick). */
+async function fetchProjectSignature(projectId: string): Promise<string | null> {
+  try {
+    const res = await fetch(buildProjectApiPath(projectId, "/signature"));
+    if (!res.ok) return null;
+    const body = (await res.json()) as { signature?: string };
+    return typeof body.signature === "string" ? body.signature : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Poll the project's content signature and fire `onChange` when it no longer
+ * matches `currentSignature` — the storyboard board uses this to refresh itself
+ * while an agent writes sketch frames to disk.
+ *
+ * The comparison baseline is the signature the caller's data was loaded with,
+ * so a refetch triggered by `onChange` naturally re-arms the poll with the new
+ * value. Ticks are skipped while the tab is hidden (a visibility flip re-checks
+ * immediately) and while a previous request is still in flight; request
+ * failures are ignored — polling degrades to today's manual-reload behavior.
+ */
+export function useProjectSignaturePoll(
+  projectId: string | null,
+  currentSignature: string | undefined,
+  onChange: () => void,
+): void {
+  const signatureRef = useRef(currentSignature);
+  const onChangeRef = useRef(onChange);
+  signatureRef.current = currentSignature;
+  onChangeRef.current = onChange;
+
+  useEffect(() => {
+    if (!projectId) return;
+    let disposed = false;
+    let inFlight = false;
+
+    const tick = async () => {
+      if (disposed || inFlight || document.hidden) return;
+      // No baseline yet (initial storyboard fetch still loading, or an older
+      // server without the signature field) — nothing to compare against.
+      if (signatureRef.current === undefined) return;
+      inFlight = true;
+      const latest = await fetchProjectSignature(projectId);
+      inFlight = false;
+      if (disposed || latest === null) return;
+      if (latest !== signatureRef.current) onChangeRef.current();
+    };
+
+    const interval = window.setInterval(() => void tick(), POLL_INTERVAL_MS);
+    const onVisibilityChange = () => {
+      if (!document.hidden) void tick();
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    return () => {
+      disposed = true;
+      window.clearInterval(interval);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [projectId]);
+}

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

@@ -76,9 +76,10 @@ function mountRazorSplit(opts: { gsap?: boolean; previewStamp?: boolean } = {}):
         // Mirror the server: rewrites the GSAP script for the new id, writes to
         // disk, returns the final content.
         disk["index.html"] = SPLIT_GSAP;
-        return new Response(JSON.stringify({ ok: true, after: SPLIT_GSAP }), {
+        const version = `"test-gsap-${SPLIT_GSAP.length}"`;
+        return new Response(JSON.stringify({ ok: true, after: SPLIT_GSAP, version }), {
           status: 200,
-          headers: { "Content-Type": "application/json" },
+          headers: { "Content-Type": "application/json", ETag: version },
         });
       }
       // The fixture has no GSAP script — mirror the server's 400 response.
@@ -89,9 +90,16 @@ function mountRazorSplit(opts: { gsap?: boolean; previewStamp?: boolean } = {}):
     }
     if (u.includes("/file-mutations/split-element/")) {
       disk["index.html"] = SPLIT;
+      const version = `"test-split-${SPLIT.length}"`;
       return new Response(
-        JSON.stringify({ ok: true, changed: true, content: SPLIT, newId: "clip1-split" }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
+        JSON.stringify({
+          ok: true,
+          changed: true,
+          content: SPLIT,
+          newId: "clip1-split",
+          version,
+        }),
+        { status: 200, headers: { "Content-Type": "application/json", ETag: version } },
       );
     }
     if (u.includes("/files/")) {

package/src/hooks/useRazorSplit.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { useRazorSplit } from "./useRazorSplit";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("useRazorSplit mutation versions", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("observes each out-of-band mutation version before the OCC writer runs", async () => {
+    const original = '<div id="clip" data-start="0" data-duration="4">Clip</div>';
+    const htmlSplit =
+      '<div id="clip" data-start="0" data-duration="2">Clip</div><div id="clip-split" data-start="2" data-duration="2">Clip</div>';
+    const final = `${htmlSplit}<script>window.__timelines = {}</script>`;
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = String(input);
+      if (url.includes("/files/")) return jsonResponse({ content: original });
+      if (url.includes("/file-mutations/split-element/")) {
+        return jsonResponse({ ok: true, changed: true, content: htmlSplit, version: '"v-html"' });
+      }
+      if (url.includes("/gsap-mutations/")) {
+        return jsonResponse({ ok: true, changed: true, after: final, version: '"v-gsap"' });
+      }
+      throw new Error(`Unexpected request: ${url}`);
+    });
+
+    const order: string[] = [];
+    const observeProjectFileVersion = vi.fn((path: string, version: string | null) => {
+      order.push(`observe:${path}:${version}`);
+    });
+    const writeProjectFile = vi.fn(async () => {
+      order.push("write");
+    });
+    const recordEdit = vi.fn().mockResolvedValue(undefined);
+    let split: ((element: TimelineElement, splitTime: number) => Promise<void>) | undefined;
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+
+    function Harness() {
+      split = useRazorSplit({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        showToast: vi.fn(),
+        writeProjectFile,
+        observeProjectFileVersion,
+        recordEdit,
+        domEditSaveTimestampRef: { current: 0 },
+        reloadPreview: vi.fn(),
+      }).handleRazorSplit;
+      return null;
+    }
+
+    await act(async () => root.render(React.createElement(Harness)));
+    await act(async () => {
+      await split?.(
+        {
+          id: "clip",
+          domId: "clip",
+          hfId: "clip",
+          tag: "div",
+          start: 0,
+          duration: 4,
+          track: 0,
+          timingSource: "authored",
+        },
+        2,
+      );
+    });
+
+    expect(order).toEqual(['observe:index.html:"v-html"', 'observe:index.html:"v-gsap"', "write"]);
+    expect(writeProjectFile).toHaveBeenCalledWith("index.html", final, original);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+
+    act(() => root.unmount());
+    container.remove();
+  });
+});

package/src/hooks/useRazorSplit.testHelpers.ts

@@ -36,10 +36,11 @@ export function createSplitFetchMock(
       onSplit?.(path, JSON.parse(String(init?.body)) as SplitBody);
       // Return content that differs from the original so `changed` is true.
       const after = `${disk[path]}<!--split-->`;
+      const version = `"test-${path}-${after.length}"`;
       disk[path] = after; // server writes the split to disk
-      return new Response(JSON.stringify({ ok: true, changed: true, content: after }), {
+      return new Response(JSON.stringify({ ok: true, changed: true, content: after, version }), {
         status: 200,
-        headers: { "Content-Type": "application/json" },
+        headers: { "Content-Type": "application/json", ETag: version },
       });
     }
     if (u.includes("/files/")) {