@hyperframes/studio 0.8.114 → 0.8.116

package/src/hooks/useExternalFileChangeCoordinator.test.tsx

@@ -83,6 +83,25 @@ describe("external file change coordinator", () => {
     expect(captured.handle?.blocked).toBeNull();
   });
 
+  it("keeps one file-change subscription across re-renders and delivers to the latest callbacks", async () => {
+    const on = vi.fn((_event: string, next: HotHandler) => void (handler = next));
+    vi.stubGlobal("__HF_STUDIO_HOT_TEST_ADAPTER__", { on, off: vi.fn() });
+    const { options } = await mountCoordinator();
+    on.mockClear();
+    const root = createRoot(document.createElement("div"));
+    roots.push(root);
+    function Probe({ onAccepted }: { onAccepted: () => void }) {
+      useExternalFileChangeCoordinator({ ...options, onAcceptedPersistedFileChange: onAccepted });
+      return null;
+    }
+    const latest = vi.fn();
+    await act(async () => root.render(<Probe onAccepted={vi.fn()} />));
+    await act(async () => root.render(<Probe onAccepted={latest} />));
+    await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
+    expect(on).toHaveBeenCalledOnce();
+    expect(latest).toHaveBeenCalledOnce();
+  });
+
   // The file tree (useFileTree) is only ever refreshed from Studio's own file
   // operations (create/delete/rename/upload) — never on an external change.
   // Without this call, an agent removing or replacing a composition updates
@@ -143,6 +162,85 @@ describe("external file change coordinator", () => {
     expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("scene.html", ["scene.html"]);
   });
 
+  it("keeps a waiting head edit's thumbnail refresh when a later write replaces it", async () => {
+    let release = () => {};
+    const inFlight = new Promise<void>((resolve) => (release = resolve));
+    const onAcceptedPersistedFileChange = vi.fn();
+    let drains = 0;
+    await mountCoordinator({
+      onAcceptedPersistedFileChange,
+      drainPendingChanges: async () => {
+        if (drains++ === 0) await inFlight;
+        return { status: "clean" as const };
+      },
+    });
+    await act(async () => handler?.({ path: "other.html", content: "a", version: "v1" }));
+    await act(async () => handler?.({ path: "index.html", content: "b", version: "v2" }));
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "c",
+        version: "v3",
+        affectedCompositions: ["index.html"],
+      }),
+    );
+    await act(async () => release());
+    expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("index.html", null);
+  });
+
+  it("keeps a head edit's thumbnail refresh through a conflict that a later write replaces", async () => {
+    const onAcceptedPersistedFileChange = vi.fn();
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v1",
+      currentContent: "theirs",
+      attemptedContent: "mine",
+    });
+    const { captured } = await mountCoordinator({
+      onAcceptedPersistedFileChange,
+      drainPendingChanges: async () => ({ status: "conflict" as const, error: conflict }),
+    });
+    await act(async () => handler?.({ path: "index.html", content: "head", version: "v1" }));
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "body",
+        version: "v2",
+        affectedCompositions: ["index.html"],
+      }),
+    );
+    await act(async () => captured.handle?.useExternalFile());
+    expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("index.html", null);
+  });
+
+  it("keeps a held head edit's thumbnail refresh when a later write saves cleanly", async () => {
+    const onAcceptedPersistedFileChange = vi.fn();
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v1",
+      currentContent: "theirs",
+      attemptedContent: "mine",
+    });
+    let drains = 0;
+    await mountCoordinator({
+      onAcceptedPersistedFileChange,
+      drainPendingChanges: async () =>
+        drains++ === 0
+          ? { status: "conflict" as const, error: conflict }
+          : { status: "clean" as const },
+    });
+    await act(async () => handler?.({ path: "index.html", content: "head", version: "v1" }));
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "body",
+        version: "v2",
+        affectedCompositions: ["index.html"],
+      }),
+    );
+    expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("index.html", null);
+  });
+
   it("does not refresh the tree for a suppressed self-write echo", async () => {
     const refreshFileTree = vi.fn();
     await mountCoordinator({ refreshFileTree });
@@ -333,6 +431,29 @@ describe("external file change coordinator", () => {
     expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
   });
 
+  it("keeps the failed file's payload when a snapshot delete fails for another file", async () => {
+    const { captured } = await mountCoordinator({
+      drainPendingChanges: vi
+        .fn()
+        .mockResolvedValueOnce({ status: "failed" as const, error: new Error("offline") })
+        .mockResolvedValueOnce({ status: "clean" as const }),
+      getPendingCandidate: () => ({ path: "scene.html", content: "studio" }),
+      deleteConflictSnapshot: vi.fn(async () => {
+        throw new Error("delete failed");
+      }),
+    });
+    await act(async () =>
+      handler?.({ path: "scene.html", content: "scene-external", version: "s1" }),
+    );
+    await act(async () =>
+      handler?.({ path: "index.html", content: "index-external", version: "i1" }),
+    );
+    expect(captured.handle?.blocked).toMatchObject({
+      status: "failed",
+      payload: { path: "scene.html", content: "scene-external", version: "s1" },
+    });
+  });
+
   it("restores and overwrites from a durable failed draft", async () => {
     const overwriteConflict = vi.fn(async () => undefined);
     const onAcceptedPersistedFileChange = vi.fn();

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState, type MutableRefObject } from "react";
 import {
+  mergeFileChangeAffectedCompositions,
   readFileChangeAffectedCompositions,
   readFileChangeAffectsPreview,
   readFileChangeField,
@@ -163,7 +164,7 @@ export function useExternalFileChangeCoordinator({
   onAcceptedPersistedFileChange,
   refreshFileTree,
 }: ExternalFileChangeCoordinatorOptions): ExternalFileChangeCoordinatorHandle {
-  const [blocked, setBlocked] = useState<ExternalFileChangeBlockedState | null>(null);
+  const [blocked, setBlockedState] = useState<ExternalFileChangeBlockedState | null>(null);
   const generationRef = useRef(0);
   const mountedRef = useRef(true);
   const lastEventIdentityRef = useRef<string | null>(null);
@@ -172,6 +173,14 @@ export function useExternalFileChangeCoordinator({
   const drainingRef = useRef(false);
   const pendingPayloadRef = useRef<{ payload: unknown } | null>(null);
   blockedRef.current = blocked;
+  // A newer blocked change replaces the held one, so it inherits the thumbnails the held one owed.
+  const setBlocked = useCallback((next: ExternalFileChangeBlockedState | null) => {
+    setBlockedState((held) =>
+      next && held
+        ? { ...next, payload: mergeFileChangeAffectedCompositions(held.payload, next.payload) }
+        : next,
+    );
+  }, []);
 
   useEffect(() => {
     mountedRef.current = true;
@@ -185,7 +194,7 @@ export function useExternalFileChangeCoordinator({
     generationRef.current += 1;
     setBlocked(null);
     lastEventIdentityRef.current = null;
-  }, [projectId, activeCompPath]);
+  }, [projectId, activeCompPath, setBlocked]);
 
   useEffect(() => {
     if (!projectId || !recoveryFilePath || !loadConflictSnapshot) return;
@@ -229,7 +238,7 @@ export function useExternalFileChangeCoordinator({
     return () => {
       cancelled = true;
     };
-  }, [loadConflictSnapshot, projectId, recoveryFilePath]);
+  }, [loadConflictSnapshot, projectId, recoveryFilePath, setBlocked]);
 
   const reloadAcceptedGeneration = useCallback(
     (path: string, affectsPreview = true) => {
@@ -275,14 +284,22 @@ export function useExternalFileChangeCoordinator({
             await deleteConflictSnapshot(projectId!, path);
           } catch (error) {
             if (mountedRef.current && generation === generationRef.current) {
-              setBlocked({ ...previousBlocked, generation, error });
+              setBlocked({
+                ...previousBlocked,
+                generation,
+                error,
+                payload: mergeFileChangeAffectedCompositions(payload, previousBlocked.payload),
+              });
             }
             return;
           }
         }
         if (!mountedRef.current || generation !== generationRef.current) return;
         setBlocked(null);
-        onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(payload));
+        const owed = previousBlocked
+          ? mergeFileChangeAffectedCompositions(previousBlocked.payload, payload)
+          : payload;
+        onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(owed));
         reloadAcceptedGeneration(path, readFileChangeAffectsPreview(payload));
         return;
       }
@@ -344,6 +361,7 @@ export function useExternalFileChangeCoordinator({
     },
     [
       drainPendingChanges,
+      setBlocked,
       projectId,
       deleteConflictSnapshot,
       getPendingCandidate,
@@ -419,15 +437,22 @@ export function useExternalFileChangeCoordinator({
         waiting != null &&
         readFileChangeAffectsPreview(waiting) &&
         !readFileChangeAffectsPreview(payload);
-      if (!waitingChangeOutranksThis) pendingPayloadRef.current = { payload };
+      if (!waitingChangeOutranksThis) {
+        pendingPayloadRef.current = {
+          payload:
+            waiting == null ? payload : mergeFileChangeAffectedCompositions(waiting, payload),
+        };
+      }
       void startDrainLoop();
     },
     [projectId, pendingTimelineEditPathRef, startDrainLoop, onAcceptedPersistedFileChange],
   );
 
+  const processChangeRef = useRef(processChange);
+  processChangeRef.current = processChange;
   useEffect(() => {
     // One decoder for all three transports; the rungs only choose the channel.
-    const handler = (delivery?: unknown) => processChange(decodeFileChange(delivery));
+    const handler = (delivery?: unknown) => processChangeRef.current(decodeFileChange(delivery));
     const adapter = testHotAdapter();
     if (adapter) {
       adapter.on("hf:file-change", handler);
@@ -438,7 +463,7 @@ export function useExternalFileChangeCoordinator({
       return () => import.meta.hot?.off?.("hf:file-change", handler);
     }
     return sseFileChangeChannel(handler);
-  }, [processChange]);
+  }, []);
 
   const retry = useCallback(async () => {
     const current = blockedRef.current;
@@ -469,6 +494,7 @@ export function useExternalFileChangeCoordinator({
     },
     [
       deleteConflictSnapshot,
+      setBlocked,
       discardPendingChanges,
       onUseExternalFile,
       onAcceptedPersistedFileChange,
@@ -527,6 +553,7 @@ export function useExternalFileChangeCoordinator({
     reloadAcceptedGeneration(conflict.filePath);
   }, [
     deleteConflictSnapshot,
+    setBlocked,
     discardPendingChanges,
     overwriteConflict,
     projectId,

package/src/hooks/useFileManager.projectOwnership.test.tsx

@@ -129,6 +129,7 @@ describe("useFileManager project ownership", () => {
 
     expect(fetchMock).toHaveBeenCalledWith(
       "/api/projects/project-a%2F..%2Fother%3Fx%3D1/files/index.html",
+      { credentials: "omit" },
     );
     expect(fetchMock).toHaveBeenCalledWith(
       "/api/projects/project-a%2F..%2Fother%3Fx%3D1/files/index.html",
@@ -136,14 +137,18 @@ describe("useFileManager project ownership", () => {
     );
     expect(fetchMock).toHaveBeenCalledWith(
       "/api/projects/project-a%2F..%2Fother%3Fx%3D1/files/missing.html",
+      { credentials: "omit" },
     );
     expect(fetchMock).toHaveBeenCalledWith(
       "/api/projects/project-a%2F..%2Fother%3Fx%3D1/files/missing.html",
       expect.objectContaining({ method: "PUT", body: "A_NEW" }),
     );
-    expect(fetchMock).toHaveBeenCalledWith("/api/projects/project-b%23fragment/files/index.html");
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/project-b%23fragment/files/index.html", {
+      credentials: "omit",
+    });
     expect(fetchMock).toHaveBeenCalledWith(
       "/api/projects/project-b%23fragment/files/index.html?optional=1",
+      { credentials: "omit" },
     );
 
     await act(async () => root.unmount());

package/src/hooks/useFileManager.ts

@@ -8,6 +8,7 @@ import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordina
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 import { useProjectFileWriter } from "./useProjectFileWriter";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 // ── Types ──
 
@@ -133,7 +134,7 @@ export function useFileManager({
         setEditingFile({ path, content: null });
         return;
       }
-      fetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`)
+      studioApiFetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`)
         .then((r) => {
           if (!r.ok) throw new Error(`Failed to load ${path} (${r.status})`);
           return r.json();
@@ -167,9 +168,12 @@ export function useFileManager({
       const requestId = ++revealRequestIdRef.current;
       const controller = new AbortController();
       revealAbortRef.current = controller;
-      fetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(sourceFile)}`, {
-        signal: controller.signal,
-      })
+      studioApiFetch(
+        `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(sourceFile)}`,
+        {
+          signal: controller.signal,
+        },
+      )
         .then((r) => r.json())
         .then((data: { content?: string; version?: string }) => {
           if (requestId !== revealRequestIdRef.current) return;
@@ -200,7 +204,7 @@ export function useFileManager({
 
       const qs = dir ? `?dir=${encodeURIComponent(dir)}` : "";
       try {
-        const res = await fetch(`/api/projects/${encodeURIComponent(pid)}/upload${qs}`, {
+        const res = await studioApiFetch(`/api/projects/${encodeURIComponent(pid)}/upload${qs}`, {
           method: "POST",
           body: formData,
         });
@@ -246,7 +250,7 @@ export function useFileManager({
         content =
           '<!DOCTYPE html>\n<html>\n<head>\n  <meta charset="UTF-8">\n</head>\n<body>\n\n</body>\n</html>\n';
       }
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`,
         {
           method: "POST",
@@ -270,7 +274,7 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path + "/.gitkeep")}`,
         {
           method: "POST",
@@ -293,7 +297,7 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`,
         {
           method: "DELETE",
@@ -315,7 +319,7 @@ export function useFileManager({
     async (oldPath: string, newPath: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(oldPath)}`,
         {
           method: "PATCH",
@@ -342,7 +346,7 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(`/api/projects/${encodeURIComponent(pid)}/duplicate-file`, {
+      const res = await studioApiFetch(`/api/projects/${encodeURIComponent(pid)}/duplicate-file`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ path }),

package/src/hooks/useFileTree.ts

@@ -3,6 +3,7 @@ import { useState, useCallback, useEffect, useMemo, useRef } from "react";
 import { FONT_EXT } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import { captureProjectProvenance } from "../components/feedback/projectProvenance";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseFileTreeOptions {
   projectId: string | null;
@@ -38,7 +39,7 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
     if (!projectId) return;
     let cancelled = false;
     setFetched({ projectId, loaded: false, fileTree: [], compositionPaths: [], projectDir: null });
-    fetch(buildProjectApiPath(projectId))
+    studioApiFetch(buildProjectApiPath(projectId))
       // An unresolvable project answers 404 with a JSON body, so without this
       // the error path parsed cleanly and the success branch below recorded an
       // empty tree — and an empty provenance snapshot — for a project that was
@@ -84,7 +85,7 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
     refreshAbortRef.current = controller;
     let data: { files?: string[]; compositions?: string[] };
     try {
-      const res = await fetch(buildProjectApiPath(pid), { signal: controller.signal });
+      const res = await studioApiFetch(buildProjectApiPath(pid), { signal: controller.signal });
       data = await res.json();
     } catch (err) {
       if (err instanceof DOMException && err.name === "AbortError") return;

package/src/hooks/useFrameCapture.ts

@@ -2,6 +2,7 @@ import { useMemo, useState, useCallback, useRef, type MouseEvent } from "react";
 import { useMountEffect } from "./useMountEffect";
 import { liveTime, usePlayerStore } from "../player";
 import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "../utils/frameCapture";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseFrameCaptureParams {
   projectId: string | null;
@@ -67,7 +68,10 @@ export function useFrameCapture({
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 30000);
         try {
-          const response = await fetch(href, { cache: "no-store", signal: controller.signal });
+          const response = await studioApiFetch(href, {
+            cache: "no-store",
+            signal: controller.signal,
+          });
           clearTimeout(timeout);
           if (!response.ok) {
             let msg = `Capture failed (${response.status})`;

package/src/hooks/useFreezeFrame.ts

@@ -6,6 +6,7 @@ import { buildProjectApiPath } from "../utils/projectRouting";
 import { markStudioWriteToken } from "../utils/studioFileVersion";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
 import type { RecordEditInput } from "../utils/studioFileHistory";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
 
@@ -31,7 +32,7 @@ function errorOf(value: unknown): string | null {
 }
 
 async function readVersion(projectId: string, path: string): Promise<string> {
-  const response = await fetch(
+  const response = await studioApiFetch(
     buildProjectApiPath(projectId, `/files/${encodeURIComponent(path)}`),
   );
   const body: unknown = await response.json().catch(() => null);
@@ -53,7 +54,7 @@ export async function requestFreezeFrame(input: {
   const expectedVersion = await readVersion(input.projectId, input.path);
   const transactionToken = `freeze:${crypto.randomUUID()}`;
   markStudioWriteToken(transactionToken);
-  const response = await fetch(
+  const response = await studioApiFetch(
     buildProjectApiPath(input.projectId, "/file-mutations/freeze-frame"),
     {
       method: "POST",