@hyperframes/studio 0.7.90 → 0.7.93

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -0,0 +1,429 @@
+import { useCallback, useEffect, useRef, useState, type MutableRefObject } from "react";
+import { readStudioFileChangePath } from "../components/editor/manualEdits";
+import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
+import type { ExternalConflictSnapshot } from "../utils/externalConflictStorage";
+import { isSelfWriteEcho } from "./sdkSelfWriteRegistry";
+import { consumeStudioWriteToken } from "../utils/studioFileVersion";
+
+type ExternalChangeDrainResult =
+  | { status: "clean" }
+  | { status: "conflict"; error: StudioFileConflictError }
+  | { status: "failed"; error: unknown };
+
+export type ExternalFileChangeBlockedState =
+  | {
+      status: "conflict";
+      generation: number;
+      error: StudioFileConflictError;
+      payload: unknown;
+    }
+  | {
+      status: "failed";
+      generation: number;
+      path: string;
+      error: unknown;
+      payload: unknown;
+      studioContent: string | null;
+      recovered: boolean;
+    };
+
+interface ExternalFileChangeCoordinatorOptions {
+  projectId: string | null;
+  activeCompPath: string | null;
+  recoveryFilePath?: string | null;
+  pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
+  drainPendingChanges: () => Promise<ExternalChangeDrainResult>;
+  getPendingCandidate?: () => { path: string; content: string } | null;
+  discardPendingChanges: () => void;
+  reloadPreview: () => void;
+  reloadSdkSession: (path: string) => void;
+  persistConflictSnapshot: (projectId: string, conflict: StudioFileConflictError) => Promise<void>;
+  persistFailureSnapshot?: (
+    projectId: string,
+    filePath: string,
+    studioContent: string,
+    externalVersion: string | null,
+    externalContent: string | null,
+    error: unknown,
+  ) => Promise<void>;
+  loadConflictSnapshot?: (
+    projectId: string,
+    filePath: string,
+  ) => Promise<ExternalConflictSnapshot | null>;
+  deleteConflictSnapshot?: (projectId: string, filePath: string) => Promise<void>;
+  overwriteConflict: (conflict: StudioFileConflictError) => Promise<void>;
+  readProjectFile: (path: string) => Promise<string>;
+  onUseExternalFile?: (path: string, content: string) => void;
+  resetSaveQueues?: () => void;
+}
+
+export interface ExternalFileChangeCoordinatorHandle {
+  blocked: ExternalFileChangeBlockedState | null;
+  retry: () => Promise<void>;
+  useExternalFile: () => Promise<void>;
+  keepStudioFile: () => Promise<void>;
+}
+
+interface HotTestAdapter {
+  on(event: string, handler: (payload?: unknown) => void): void;
+  off(event: string, handler: (payload?: unknown) => void): void;
+}
+
+function testHotAdapter(): HotTestAdapter | null {
+  const value = (globalThis as { __HF_STUDIO_HOT_TEST_ADAPTER__?: unknown })
+    .__HF_STUDIO_HOT_TEST_ADAPTER__;
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as Partial<HotTestAdapter>;
+  return typeof candidate.on === "function" && typeof candidate.off === "function"
+    ? (candidate as HotTestAdapter)
+    : null;
+}
+
+function readFileChangeContent(payload: unknown): string | null {
+  if (!payload || typeof payload !== "object") return null;
+  const record = payload as Record<string, unknown>;
+  if (typeof record.content === "string") return record.content;
+  return "data" in record ? readFileChangeContent(record.data) : null;
+}
+
+function readFileChangeVersion(payload: unknown): string | null {
+  if (!payload || typeof payload !== "object") return null;
+  const record = payload as Record<string, unknown>;
+  if (typeof record.version === "string") return record.version;
+  return "data" in record ? readFileChangeVersion(record.data) : null;
+}
+
+function readFileChangeWriteToken(payload: unknown): string | null {
+  if (!payload || typeof payload !== "object") return null;
+  const record = payload as Record<string, unknown>;
+  if (typeof record.writeToken === "string") return record.writeToken;
+  return "data" in record ? readFileChangeWriteToken(record.data) : null;
+}
+
+function eventIdentity(path: string, payload: unknown): string | null {
+  const version = readFileChangeVersion(payload);
+  if (version) return `${path}\0${version}`;
+  const content = readFileChangeContent(payload);
+  return content == null ? null : `${path}\0${content.length}\0${content}`;
+}
+
+export function useExternalFileChangeCoordinator({
+  projectId,
+  activeCompPath,
+  recoveryFilePath = activeCompPath,
+  pendingTimelineEditPathRef,
+  drainPendingChanges,
+  getPendingCandidate,
+  discardPendingChanges,
+  reloadPreview,
+  reloadSdkSession,
+  persistConflictSnapshot,
+  persistFailureSnapshot,
+  loadConflictSnapshot,
+  deleteConflictSnapshot,
+  overwriteConflict,
+  readProjectFile,
+  onUseExternalFile,
+  resetSaveQueues,
+}: ExternalFileChangeCoordinatorOptions): ExternalFileChangeCoordinatorHandle {
+  const [blocked, setBlocked] = useState<ExternalFileChangeBlockedState | null>(null);
+  const generationRef = useRef(0);
+  const mountedRef = useRef(true);
+  const lastEventIdentityRef = useRef<string | null>(null);
+  const blockedRef = useRef(blocked);
+  const snapshotWriteTailRef = useRef<Promise<void>>(Promise.resolve());
+  blockedRef.current = blocked;
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      generationRef.current += 1;
+    };
+  }, []);
+
+  useEffect(() => {
+    generationRef.current += 1;
+    setBlocked(null);
+    lastEventIdentityRef.current = null;
+  }, [projectId, activeCompPath]);
+
+  useEffect(() => {
+    if (!projectId || !recoveryFilePath || !loadConflictSnapshot) return;
+    const generation = ++generationRef.current;
+    let cancelled = false;
+    void loadConflictSnapshot(projectId, recoveryFilePath)
+      .then((snapshot) => {
+        if (cancelled || !snapshot || !mountedRef.current || generation !== generationRef.current) {
+          return;
+        }
+        const payload = {
+          path: snapshot.filePath,
+          version: snapshot.externalVersion,
+          content: snapshot.externalContent,
+        };
+        if (snapshot.kind === "failed") {
+          setBlocked({
+            status: "failed",
+            generation,
+            path: snapshot.filePath,
+            error: new Error(snapshot.failureMessage),
+            payload,
+            studioContent: snapshot.studioContent,
+            recovered: true,
+          });
+        } else {
+          const error = new StudioFileConflictError({
+            filePath: snapshot.filePath,
+            currentVersion: snapshot.externalVersion,
+            currentContent: snapshot.externalContent,
+            attemptedContent: snapshot.studioContent,
+          });
+          setBlocked({ status: "conflict", generation, error, payload });
+        }
+      })
+      .catch(() => {
+        // Storage may be unavailable in restricted browser contexts. A failed
+        // best-effort restore must not create an unhandled rejection or block
+        // a project that has no known recovery record.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [loadConflictSnapshot, projectId, recoveryFilePath]);
+
+  const reloadAcceptedGeneration = useCallback(
+    (path: string) => {
+      reloadPreview();
+      reloadSdkSession(path);
+    },
+    [reloadPreview, reloadSdkSession],
+  );
+
+  const persistSnapshotInOrder = useCallback(async (write: () => Promise<void>) => {
+    const next = snapshotWriteTailRef.current.catch(() => undefined).then(write);
+    snapshotWriteTailRef.current = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    await next;
+  }, []);
+
+  const processChange = useCallback(
+    // fallow-ignore-next-line complexity
+    async (payload: unknown, allowDuplicate = false) => {
+      const path = readStudioFileChangePath(payload);
+      if (!path || !projectId) return;
+      const pendingTimelinePaths = pendingTimelineEditPathRef.current;
+      // The old path-only suppression could drop a real agent/user write that
+      // raced ahead of the timeline write receipt. Clear the legacy marker but
+      // decide ownership only from the exact write token/content below.
+      pendingTimelinePaths.delete(path);
+
+      const content = readFileChangeContent(payload);
+      if (consumeStudioWriteToken(readFileChangeWriteToken(payload))) return;
+      if (content != null && isSelfWriteEcho(path, content)) return;
+
+      const identity = eventIdentity(path, payload);
+      if (!allowDuplicate && identity != null && identity === lastEventIdentityRef.current) return;
+      lastEventIdentityRef.current = identity;
+      const generation = ++generationRef.current;
+      const result = await drainPendingChanges();
+      if (!mountedRef.current || generation !== generationRef.current) return;
+
+      if (result.status === "clean") {
+        const previousBlocked = blockedRef.current;
+        if (previousBlocked?.status === "failed" && deleteConflictSnapshot) {
+          try {
+            await deleteConflictSnapshot(projectId, path);
+          } catch (error) {
+            if (mountedRef.current && generation === generationRef.current) {
+              setBlocked({ ...previousBlocked, generation, error });
+            }
+            return;
+          }
+        }
+        if (!mountedRef.current || generation !== generationRef.current) return;
+        setBlocked(null);
+        reloadAcceptedGeneration(path);
+        return;
+      }
+      if (result.status === "failed") {
+        const candidate = getPendingCandidate?.();
+        const studioContent = candidate?.path === path ? candidate.content : null;
+        let error = result.error;
+        if (studioContent != null && persistFailureSnapshot) {
+          try {
+            await persistSnapshotInOrder(() =>
+              persistFailureSnapshot(
+                projectId,
+                path,
+                studioContent,
+                readFileChangeVersion(payload),
+                content,
+                result.error,
+              ),
+            );
+          } catch (snapshotError) {
+            error = new Error(
+              `Studio could not save the edit or its recovery snapshot: ${
+                snapshotError instanceof Error ? snapshotError.message : String(snapshotError)
+              }`,
+              { cause: result.error },
+            );
+          }
+        }
+        if (!mountedRef.current || generation !== generationRef.current) return;
+        setBlocked({
+          status: "failed",
+          generation,
+          path,
+          error,
+          payload,
+          studioContent,
+          recovered: false,
+        });
+        return;
+      }
+      try {
+        await persistSnapshotInOrder(() => persistConflictSnapshot(projectId, result.error));
+      } catch (error) {
+        if (!mountedRef.current || generation !== generationRef.current) return;
+        setBlocked({
+          status: "failed",
+          generation,
+          path,
+          error,
+          payload,
+          studioContent: result.error.attemptedContent,
+          recovered: false,
+        });
+        return;
+      }
+      if (!mountedRef.current || generation !== generationRef.current) return;
+      setBlocked({ status: "conflict", generation, error: result.error, payload });
+    },
+    [
+      projectId,
+      pendingTimelineEditPathRef,
+      drainPendingChanges,
+      deleteConflictSnapshot,
+      getPendingCandidate,
+      persistConflictSnapshot,
+      persistFailureSnapshot,
+      persistSnapshotInOrder,
+      reloadAcceptedGeneration,
+    ],
+  );
+
+  useEffect(() => {
+    const handler = (payload?: unknown) => processChange(payload);
+    const adapter = testHotAdapter();
+    if (adapter) {
+      adapter.on("hf:file-change", handler);
+      return () => adapter.off("hf:file-change", handler);
+    }
+    if (import.meta.hot) {
+      import.meta.hot.on("hf:file-change", handler);
+      return () => import.meta.hot?.off?.("hf:file-change", handler);
+    }
+    const eventSource = new EventSource("/api/events");
+    eventSource.addEventListener("file-change", handler);
+    return () => eventSource.close();
+  }, [processChange]);
+
+  const retry = useCallback(async () => {
+    const current = blockedRef.current;
+    if (!current || current.status === "conflict" || current.recovered) return;
+    resetSaveQueues?.();
+    lastEventIdentityRef.current = null;
+    await processChange(current.payload, true);
+  }, [processChange, resetSaveQueues]);
+
+  const useExternalFile = useCallback(
+    // fallow-ignore-next-line complexity
+    async () => {
+      const current = blockedRef.current;
+      if (!current || !projectId || current.generation !== generationRef.current) return;
+      const path = current.status === "conflict" ? current.error.filePath : current.path;
+      const external =
+        current.status === "conflict" && current.error.currentContent != null
+          ? current.error.currentContent
+          : await readProjectFile(path);
+      if (current.generation !== generationRef.current) return;
+      discardPendingChanges();
+      resetSaveQueues?.();
+      onUseExternalFile?.(path, external);
+      await deleteConflictSnapshot?.(projectId, path);
+      setBlocked(null);
+      reloadAcceptedGeneration(path);
+    },
+    [
+      deleteConflictSnapshot,
+      discardPendingChanges,
+      onUseExternalFile,
+      projectId,
+      readProjectFile,
+      reloadAcceptedGeneration,
+      resetSaveQueues,
+    ],
+  );
+
+  // fallow-ignore-next-line complexity
+  const keepStudioFile = useCallback(async () => {
+    const current = blockedRef.current;
+    if (!current || !projectId) return;
+    if (current.generation !== generationRef.current) return;
+    let conflict: StudioFileConflictError;
+    if (current.status === "conflict") {
+      conflict = current.error;
+    } else {
+      if (!current.recovered || current.studioContent == null) return;
+      try {
+        const currentContent =
+          readFileChangeContent(current.payload) ?? (await readProjectFile(current.path));
+        conflict = new StudioFileConflictError({
+          filePath: current.path,
+          currentVersion: readFileChangeVersion(current.payload),
+          currentContent,
+          attemptedContent: current.studioContent,
+        });
+      } catch (error) {
+        if (current.generation === generationRef.current) setBlocked({ ...current, error });
+        return;
+      }
+    }
+    try {
+      await overwriteConflict(conflict);
+    } catch (error) {
+      if (current.generation === generationRef.current) {
+        setBlocked({
+          status: "failed",
+          generation: current.generation,
+          path: conflict.filePath,
+          error,
+          payload: current.payload,
+          studioContent: conflict.attemptedContent,
+          recovered: current.status === "failed" && current.recovered,
+        });
+      }
+      return;
+    }
+    if (current.generation !== generationRef.current) return;
+    discardPendingChanges();
+    resetSaveQueues?.();
+    await deleteConflictSnapshot?.(projectId, conflict.filePath);
+    setBlocked(null);
+    reloadAcceptedGeneration(conflict.filePath);
+  }, [
+    deleteConflictSnapshot,
+    discardPendingChanges,
+    overwriteConflict,
+    projectId,
+    readProjectFile,
+    reloadAcceptedGeneration,
+    resetSaveQueues,
+  ]);
+
+  return { blocked, retry, useExternalFile, keepStudioFile };
+}

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

@@ -20,15 +20,65 @@ vi.mock("./useEditorSave", () => ({
   useEditorSave: () => ({
     saveRafRef: { current: null },
     handleContentChange: vi.fn(),
+    getPendingCandidate: vi.fn(() => null),
+    flushPendingSave: vi.fn(async () => ({ status: "clean" as const })),
+    discardPendingSave: vi.fn(),
   }),
 }));
 
 import { useFileManager } from "./useFileManager";
+import { resetStudioWriteTokens, studioFileContentVersion } from "../utils/studioFileVersion";
+import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+function useTestFileManager(projectId: string) {
+  return useFileManager({
+    projectId,
+    showToast: vi.fn(),
+    recordEdit: vi.fn(async () => {}),
+    domEditSaveTimestampRef: { current: 0 },
+    setRefreshKey: vi.fn(),
+  });
+}
+
+async function mountTestFileManager(projectId = "project-a") {
+  const captured: { manager: ReturnType<typeof useFileManager> | null } = { manager: null };
+  function Probe() {
+    captured.manager = useTestFileManager(projectId);
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  await act(async () => root.render(<Probe />));
+  const manager = captured.manager;
+  if (!manager) throw new Error("file manager did not render");
+  return { manager, root };
+}
+
+async function mountOverwriteRequest(response: Response) {
+  const fetchMock = vi.fn((_url: string, init?: RequestInit) => {
+    if (init?.method !== "PUT") {
+      throw new Error("overwrite unexpectedly performed a preflight read");
+    }
+    return Promise.resolve(response);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return { ...(await mountTestFileManager()), fetchMock };
+}
+
+function createOverwriteConflict(currentVersion: string | null, currentContent: string | null) {
+  return new StudioFileConflictError({
+    filePath: "index.html",
+    currentVersion,
+    currentContent,
+    attemptedContent: "STUDIO",
+  });
+}
+
 describe("useFileManager project ownership", () => {
   afterEach(() => {
+    resetStudioWriteTokens();
+    vi.useRealTimers();
     vi.unstubAllGlobals();
   });
 
@@ -54,13 +104,7 @@ describe("useFileManager project ownership", () => {
 
     const captured: { manager: ReturnType<typeof useFileManager> | null } = { manager: null };
     function Probe({ projectId }: { projectId: string }) {
-      captured.manager = useFileManager({
-        projectId,
-        showToast: vi.fn(),
-        recordEdit: vi.fn(async () => {}),
-        domEditSaveTimestampRef: { current: 0 },
-        setRefreshKey: vi.fn(),
-      });
+      captured.manager = useTestFileManager(projectId);
       return null;
     }
 
@@ -106,4 +150,92 @@ describe("useFileManager project ownership", () => {
 
     await act(async () => root.unmount());
   });
+
+  it("uses a fresh write token when a lost response retries a committed save", async () => {
+    vi.useFakeTimers();
+    let putAttempt = 0;
+    const fetchMock = vi.fn((_url: string, init?: RequestInit) => {
+      if (!init?.method) {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({ content: "BEFORE", version: "v1" }),
+        } as Response);
+      }
+      putAttempt += 1;
+      if (putAttempt === 1) return Promise.reject(new TypeError("response lost"));
+      return Promise.resolve({ ok: true, json: async () => ({ version: "v2" }) } as Response);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { manager, root } = await mountTestFileManager();
+    await manager.readProjectFile("index.html");
+
+    const write = manager.writeProjectFile("index.html", "AFTER");
+    await vi.runAllTimersAsync();
+    await write;
+
+    const writeTokens = fetchMock.mock.calls
+      .filter(([, init]) => init?.method === "PUT")
+      .map(([, init]) => new Headers(init?.headers).get("X-Hyperframes-Write-Token"));
+    expect(writeTokens).toHaveLength(2);
+    expect(writeTokens[0]).toBeTruthy();
+    expect(writeTokens[1]).not.toBe(writeTokens[0]);
+
+    await act(async () => root.unmount());
+  });
+
+  it("overwrites the exact external content version with an If-Match precondition", async () => {
+    const { manager, root, fetchMock } = await mountOverwriteRequest({
+      ok: true,
+      json: async () => ({ version: "v3" }),
+    } as Response);
+    const conflict = createOverwriteConflict("v2", "EXTERNAL");
+
+    await manager.overwriteExternalConflict(conflict);
+
+    const [, init] = fetchMock.mock.calls[0] ?? [];
+    const headers = new Headers(init?.headers);
+    expect(init).toMatchObject({ method: "PUT", body: "STUDIO" });
+    expect(headers.get("If-Match")).toBe(await studioFileContentVersion("EXTERNAL"));
+    expect(headers.get("If-None-Match")).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("preserves a newer third-party edit when a content-less conflict version is stale", async () => {
+    const { manager, root, fetchMock } = await mountOverwriteRequest({
+      ok: false,
+      status: 409,
+      json: async () => ({ currentVersion: "v3", currentContent: "THIRD PARTY" }),
+    } as Response);
+    const conflict = createOverwriteConflict("v2", null);
+
+    await expect(manager.overwriteExternalConflict(conflict)).rejects.toMatchObject({
+      name: "StudioFileConflictError",
+      currentVersion: "v3",
+      currentContent: "THIRD PARTY",
+      attemptedContent: "STUDIO",
+    });
+
+    const [, init] = fetchMock.mock.calls[0] ?? [];
+    const headers = new Headers(init?.headers);
+    expect(headers.get("If-Match")).toBe("v2");
+    expect(headers.get("If-None-Match")).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("uses create-only semantics when the conflicted file was deleted", async () => {
+    const { manager, root, fetchMock } = await mountOverwriteRequest({
+      ok: true,
+      json: async () => ({ version: "v1" }),
+    } as Response);
+    const conflict = createOverwriteConflict(null, null);
+
+    await manager.overwriteExternalConflict(conflict);
+
+    const [, init] = fetchMock.mock.calls[0] ?? [];
+    const headers = new Headers(init?.headers);
+    expect(headers.get("If-Match")).toBeNull();
+    expect(headers.get("If-None-Match")).toBe("*");
+    await act(async () => root.unmount());
+  });
 });

package/src/hooks/useFileManager.ts

@@ -10,7 +10,11 @@ import {
   StudioFileConflictError,
   StudioSaveNetworkError,
 } from "../utils/studioSaveDiagnostics";
-import { createStudioWriteToken, studioExpectedFileVersion } from "../utils/studioFileVersion";
+import {
+  createStudioWriteToken,
+  markStudioWriteToken,
+  studioExpectedFileVersion,
+} from "../utils/studioFileVersion";
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 
@@ -117,8 +121,11 @@ export function useFileManager({
           throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`);
         }
       }
-      const writeToken = createStudioWriteToken();
       await retryStudioSave(async () => {
+        // Each request gets its own receipt identity. If a committed request loses its response,
+        // the retry can produce a second filesystem receipt that must be suppressed independently.
+        const writeToken = createStudioWriteToken();
+        markStudioWriteToken(writeToken);
         let response: Response;
         try {
           response = await fetch(
@@ -191,7 +198,7 @@ export function useFileManager({
 
   // ── Editor save (debounced content change) ──
 
-  const { saveRafRef, handleContentChange } = useEditorSave({
+  const editorSave = useEditorSave({
     editingPathRef,
     projectIdRef,
     readProjectFile,
@@ -201,6 +208,24 @@ export function useFileManager({
     setRefreshKey,
     showToast,
   });
+  const { saveRafRef, handleContentChange } = editorSave;
+
+  const overwriteExternalConflict = useCallback(
+    async (conflict: StudioFileConflictError) => {
+      if (conflict.currentContent != null) {
+        await writeProjectFile(
+          conflict.filePath,
+          conflict.attemptedContent,
+          conflict.currentContent,
+        );
+      } else {
+        fileVersions.set(conflict.filePath, conflict.currentVersion);
+        await writeProjectFile(conflict.filePath, conflict.attemptedContent);
+      }
+      updateEditingFileContent(conflict.filePath, conflict.attemptedContent);
+    },
+    [fileVersions, updateEditingFileContent, writeProjectFile],
+  );
 
   // ── File select ──
 
@@ -491,11 +516,15 @@ export function useFileManager({
     editingPathRef,
     projectIdRef,
     saveRafRef,
+    flushPendingSourceSave: editorSave.flushPendingSave,
+    discardPendingSourceSave: editorSave.discardPendingSave,
+    getPendingSourceCandidate: editorSave.getPendingCandidate,
     importedFontAssetsRef,
 
     // Core I/O
     readProjectFile,
     writeProjectFile,
+    overwriteExternalConflict,
     readOptionalProjectFile,
     observeProjectFileVersion,
     updateEditingFileContent,