@hyperframes/studio 0.7.58 → 0.7.60

package/src/hooks/useFileManager.ts

@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef } from "react";
+import { useState, useCallback, useMemo, useRef } from "react";
 import type { EditingFile } from "../utils/studioHelpers";
 import { FONT_EXT, isMediaFile } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
@@ -7,8 +7,10 @@ import { findTagByTarget, type PatchTarget } from "../utils/sourcePatcher";
 import {
   createStudioSaveHttpError,
   retryStudioSave,
+  StudioFileConflictError,
   StudioSaveNetworkError,
 } from "../utils/studioSaveDiagnostics";
+import { createStudioWriteToken, studioExpectedFileVersion } from "../utils/studioFileVersion";
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 
@@ -50,6 +52,17 @@ export function useFileManager({
   projectIdRef.current = projectId;
 
   const importedFontAssetsRef = useRef<ImportedFontAsset[]>([]);
+  const fileVersionScope = useMemo(
+    () => ({ projectId, versions: new Map<string, string | null>() }),
+    [projectId],
+  );
+  const fileVersions = fileVersionScope.versions;
+  const observeProjectFileVersion = useCallback(
+    (path: string, version: string | null) => {
+      fileVersions.set(path, version);
+    },
+    [fileVersions],
+  );
 
   // ── File tree ──
 
@@ -66,38 +79,95 @@ export function useFileManager({
 
   // ── Core file I/O ──
 
-  const readProjectFile = useCallback(async (path: string): Promise<string> => {
-    const pid = projectIdRef.current;
-    if (!pid) throw new Error("No active project");
-    const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
-    if (!response.ok) throw new Error(`Failed to read ${path}`);
-    const data = (await response.json()) as { content?: string };
-    if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
-    return data.content;
-  }, []);
+  const readProjectFile = useCallback(
+    async (path: string): Promise<string> => {
+      if (!projectId) throw new Error("No active project");
+      const response = await fetch(
+        `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}`,
+      );
+      if (!response.ok) throw new Error(`Failed to read ${path}`);
+      const data = (await response.json()) as { content?: string; version?: string };
+      if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
+      fileVersions.set(path, data.version ?? response.headers.get("etag"));
+      return data.content;
+    },
+    [fileVersions, projectId],
+  );
 
-  const writeProjectFile = useCallback(async (path: string, content: string): Promise<void> => {
-    const pid = projectIdRef.current;
-    if (!pid) throw new Error("No active project");
-    await retryStudioSave(async () => {
-      let response: Response;
-      try {
-        response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`, {
-          method: "PUT",
-          headers: { "Content-Type": "text/plain" },
-          body: content,
-        });
-      } catch (error) {
-        throw new StudioSaveNetworkError(`Failed to save ${path}: network error`, {
-          cause: error,
-        });
+  const writeProjectFile = useCallback(
+    async (path: string, content: string, expectedContent?: string): Promise<void> => {
+      if (!projectId) throw new Error("No active project");
+      const writeProjectId = projectId;
+      let expectedVersion = await studioExpectedFileVersion(fileVersions, path, expectedContent);
+      if (expectedVersion === undefined) {
+        const preflight = await fetch(
+          `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
+        );
+        if (preflight.ok) {
+          const data = (await preflight.json()) as { content?: string; version?: string };
+          throw new StudioFileConflictError({
+            filePath: path,
+            currentVersion: data.version ?? preflight.headers.get("etag"),
+            currentContent: data.content ?? null,
+            attemptedContent: content,
+          });
+        } else if (preflight.status === 404) {
+          expectedVersion = null;
+        } else {
+          throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`);
+        }
       }
-      if (!response.ok) throw await createStudioSaveHttpError(response, `Failed to save ${path}`);
-    });
-    if (editingPathRef.current === path) {
-      setEditingFile({ path, content });
-    }
-  }, []);
+      const writeToken = createStudioWriteToken();
+      await retryStudioSave(async () => {
+        let response: Response;
+        try {
+          response = await fetch(
+            `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
+            {
+              method: "PUT",
+              headers: {
+                "Content-Type": "text/plain",
+                "X-Hyperframes-Write-Token": writeToken,
+                ...(expectedVersion ? { "If-Match": expectedVersion } : { "If-None-Match": "*" }),
+              },
+              body: content,
+            },
+          );
+        } catch (error) {
+          throw new StudioSaveNetworkError(`Failed to save ${path}: network error`, {
+            cause: error,
+          });
+        }
+        if (response.status === 409) {
+          const conflict = (await response.json().catch(() => null)) as {
+            currentVersion?: string | null;
+            currentContent?: string | null;
+          } | null;
+          const currentVersion = conflict?.currentVersion ?? null;
+          if (currentVersion && conflict?.currentContent === content) {
+            fileVersions.set(path, currentVersion);
+            return;
+          }
+          throw new StudioFileConflictError({
+            filePath: path,
+            currentVersion,
+            currentContent: conflict?.currentContent ?? null,
+            attemptedContent: content,
+          });
+        }
+        if (!response.ok) throw await createStudioSaveHttpError(response, `Failed to save ${path}`);
+        const result = (await response.json()) as { version?: string };
+        const version = result.version ?? response.headers.get("etag");
+        if (!version)
+          throw new Error(`Save response for ${path} did not include a content version`);
+        fileVersions.set(path, version);
+      });
+      if (projectIdRef.current === writeProjectId && editingPathRef.current === path) {
+        setEditingFile({ path, content });
+      }
+    },
+    [fileVersions, projectId],
+  );
 
   const updateEditingFileContent = useCallback((path: string, content: string) => {
     if (editingPathRef.current === path) {
@@ -105,16 +175,19 @@ export function useFileManager({
     }
   }, []);
 
-  const readOptionalProjectFile = useCallback(async (path: string): Promise<string> => {
-    const pid = projectIdRef.current;
-    if (!pid) throw new Error("No active project");
-    const response = await fetch(
-      `/api/projects/${pid}/files/${encodeURIComponent(path)}?optional=1`,
-    );
-    if (!response.ok) throw new Error(`Failed to read ${path}`);
-    const data = (await response.json()) as { content?: string };
-    return typeof data.content === "string" ? data.content : "";
-  }, []);
+  const readOptionalProjectFile = useCallback(
+    async (path: string): Promise<string> => {
+      if (!projectId) throw new Error("No active project");
+      const response = await fetch(
+        `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
+      );
+      if (!response.ok) throw new Error(`Failed to read ${path}`);
+      const data = (await response.json()) as { content?: string; version?: string };
+      fileVersions.set(path, data.version ?? response.headers.get("etag"));
+      return typeof data.content === "string" ? data.content : "";
+    },
+    [fileVersions, projectId],
+  );
 
   // ── Editor save (debounced content change) ──
 
@@ -146,13 +219,14 @@ export function useFileManager({
         setEditingFile({ path, content: null });
         return;
       }
-      fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`)
+      fetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`)
         .then((r) => {
           if (!r.ok) throw new Error(`Failed to load ${path} (${r.status})`);
           return r.json();
         })
-        .then((data: { content?: string }) => {
+        .then((data: { content?: string; version?: string }) => {
           if (data.content != null) {
+            fileVersions.set(path, data.version ?? null);
             setEditingFile({ path, content: data.content });
           }
         })
@@ -160,7 +234,7 @@ export function useFileManager({
           showToast(err instanceof Error ? err.message : `Failed to load ${path}`, "error");
         });
     },
-    [showToast],
+    [fileVersions, showToast],
   );
 
   // ── Click-to-source ──
@@ -179,13 +253,14 @@ export function useFileManager({
       const requestId = ++revealRequestIdRef.current;
       const controller = new AbortController();
       revealAbortRef.current = controller;
-      fetch(`/api/projects/${pid}/files/${encodeURIComponent(sourceFile)}`, {
+      fetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(sourceFile)}`, {
         signal: controller.signal,
       })
         .then((r) => r.json())
-        .then((data: { content?: string }) => {
+        .then((data: { content?: string; version?: string }) => {
           if (requestId !== revealRequestIdRef.current) return;
           if (data.content != null) {
+            fileVersions.set(sourceFile, data.version ?? null);
             setEditingFile({ path: sourceFile, content: data.content });
             const match = findTagByTarget(data.content, target);
             setRevealSourceOffset(match ? match.start : null);
@@ -193,7 +268,7 @@ export function useFileManager({
         })
         .catch(() => {});
     },
-    [editingFile?.content],
+    [editingFile?.content, fileVersions],
   );
 
   // ── Upload ──
@@ -211,7 +286,7 @@ export function useFileManager({
 
       const qs = dir ? `?dir=${encodeURIComponent(dir)}` : "";
       try {
-        const res = await fetch(`/api/projects/${pid}/upload${qs}`, {
+        const res = await fetch(`/api/projects/${encodeURIComponent(pid)}/upload${qs}`, {
           method: "POST",
           body: formData,
         });
@@ -251,11 +326,14 @@ 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(`/api/projects/${pid}/files/${encodeURIComponent(path)}`, {
-        method: "POST",
-        headers: { "Content-Type": "text/plain" },
-        body: content,
-      });
+      const res = await fetch(
+        `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "text/plain" },
+          body: content,
+        },
+      );
       if (res.ok) {
         await refreshFileTree();
         handleFileSelect(path);
@@ -273,7 +351,7 @@ export function useFileManager({
       const pid = projectIdRef.current;
       if (!pid) return;
       const res = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent(path + "/.gitkeep")}`,
+        `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path + "/.gitkeep")}`,
         {
           method: "POST",
           headers: { "Content-Type": "text/plain" },
@@ -295,9 +373,12 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`, {
-        method: "DELETE",
-      });
+      const res = await fetch(
+        `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`,
+        {
+          method: "DELETE",
+        },
+      );
       if (res.ok) {
         if (editingPathRef.current === path) setEditingFile(null);
         await refreshFileTree();
@@ -314,11 +395,14 @@ export function useFileManager({
     async (oldPath: string, newPath: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(oldPath)}`, {
-        method: "PATCH",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ newPath }),
-      });
+      const res = await fetch(
+        `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(oldPath)}`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ newPath }),
+        },
+      );
       if (res.ok) {
         if (editingPathRef.current === oldPath) {
           handleFileSelect(newPath);
@@ -338,7 +422,7 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(`/api/projects/${pid}/duplicate-file`, {
+      const res = await fetch(`/api/projects/${encodeURIComponent(pid)}/duplicate-file`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ path }),
@@ -367,17 +451,18 @@ export function useFileManager({
 
   const handleImportFonts = useCallback(
     async (files: FileList | File[]): Promise<ImportedFontAsset[]> => {
+      const pid = projectIdRef.current;
+      if (!pid) return [];
       const uploaded = await uploadProjectFiles(
         Array.from(files).filter((file) => FONT_EXT.test(file.name)),
         "assets/fonts",
       );
-      const pid = projectIdRef.current;
       const imported = uploaded
         .filter((asset) => FONT_EXT.test(asset))
         .map((asset) => ({
           family: fontFamilyFromAssetPath(asset),
           path: asset,
-          url: `/api/projects/${pid}/preview/${asset}`,
+          url: `/api/projects/${encodeURIComponent(pid)}/preview/${asset}`,
         }));
       importedFontAssetsRef.current = [
         ...imported,
@@ -412,6 +497,7 @@ export function useFileManager({
     readProjectFile,
     writeProjectFile,
     readOptionalProjectFile,
+    observeProjectFileVersion,
     updateEditingFileContent,
 
     // Click-to-source

package/src/hooks/useGsapAnimationOps.ts

@@ -7,6 +7,7 @@ import {
   sdkGsapDeleteAllForSelectorPersist,
   sdkAddWithKeyframesPersist,
   sdkReplaceWithKeyframesPersist,
+  cutoverCommittedOrThrow,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import {
@@ -52,7 +53,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,
@@ -74,7 +75,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: "Delete GSAP animation" },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,
@@ -96,7 +97,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: "Delete all animations for element" },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       void commitMutation(
         selection,
@@ -162,7 +163,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: `Add GSAP ${method} animation` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
 
       await commitMutation(
@@ -213,7 +214,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       void commitMutation(
         selection,
@@ -256,7 +257,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       void commitMutation(
         selection,

package/src/hooks/useGsapKeyframeOps.ts

@@ -8,6 +8,7 @@ import {
   sdkGsapRemoveKeyframePersist,
   sdkGsapRemoveAllKeyframesPersist,
   sdkGsapConvertToKeyframesPersist,
+  cutoverCommittedOrThrow,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import type { KeyframeCacheEntry } from "../player/store/playerStore";
@@ -136,7 +137,7 @@ export function useGsapKeyframeOps({
                 coalesceKey: `gsap:${animationId}:kf:${percentage}`,
               },
             );
-            if (handled) return;
+            if (cutoverCommittedOrThrow(handled)) return;
           }
           await commitMutation(selection, mutation, {
             label: `Add keyframe at ${percentage}%`,
@@ -169,7 +170,7 @@ export function useGsapKeyframeOps({
           sdkDeps,
           toSdkPersistOptions(`Add keyframe at ${percentage}%`, commitOverrides),
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       return commitMutation(
         selection,
@@ -218,7 +219,7 @@ export function useGsapKeyframeOps({
               sdkDeps,
               toSdkPersistOptions(label, commitOverrides),
             );
-            if (handled) return;
+            if (cutoverCommittedOrThrow(handled)) return;
           }
           const commitOptions = commitOverrides?.skipReload
             ? { label, ...commitOverrides }
@@ -300,7 +301,7 @@ export function useGsapKeyframeOps({
           sdkDeps,
           toSdkPersistOptions("Convert to keyframes", commitOverrides),
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       return commitMutation(
         selection,
@@ -329,7 +330,7 @@ export function useGsapKeyframeOps({
           sdkDeps,
           { label: "Remove all keyframes" },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,

package/src/hooks/useGsapPropertyDebounce.ts

@@ -5,6 +5,7 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
   sdkGsapTweenPersist,
   sdkGsapRemovePropertyPersist,
+  cutoverCommittedOrThrow,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import { extractGsapScriptText } from "../utils/gsapSoftReload";
@@ -45,6 +46,12 @@ interface SdkPropertyDeps {
   sdkSession?: Composition | null;
   sdkDeps?: CutoverDeps | null;
   activeCompPath?: string | null;
+  onFlushError?: (
+    error: unknown,
+    selection: DomEditSelection,
+    mutation: Record<string, unknown>,
+    label: string,
+  ) => void;
 }
 
 export function useGsapPropertyDebounce(
@@ -68,38 +75,46 @@ export function useGsapPropertyDebounce(
   const sdkRef = useRef(sdk);
   sdkRef.current = sdk;
 
+  // fallow-ignore-next-line complexity
   const flushPendingPropertyEdit = useCallback(async () => {
     const pending = pendingPropertyEditRef.current;
     if (!pending) return;
     pendingPropertyEditRef.current = null;
     const { selection, animationId, property, value } = pending;
-    const { sdkSession, sdkDeps, activeCompPath } = sdkRef.current ?? {};
-    if (sdkSession && sdkDeps) {
-      const targetPath = selection.sourceFile || activeCompPath || "index.html";
-      const handled = await sdkGsapTweenPersist(
-        targetPath,
-        {
-          kind: "set",
-          animationId,
-          properties: {
-            properties: mergeTweenProperties(sdkSession, animationId, { [property]: value }, "to"),
+    const mutation = { type: "update-property", animationId, property, value };
+    const label = `Edit GSAP ${property}`;
+    try {
+      const { sdkSession, sdkDeps, activeCompPath } = sdkRef.current ?? {};
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkGsapTweenPersist(
+          targetPath,
+          {
+            kind: "set",
+            animationId,
+            properties: {
+              properties: mergeTweenProperties(
+                sdkSession,
+                animationId,
+                { [property]: value },
+                "to",
+              ),
+            },
           },
-        },
-        sdkSession,
-        sdkDeps,
-        { label: `Edit GSAP ${property}`, coalesceKey: `gsap:${animationId}:${property}` },
-      );
-      if (handled) return;
-    }
-    commitMutationSafely(
-      selection,
-      { type: "update-property", animationId, property, value },
-      {
-        label: `Edit GSAP ${property}`,
+          sdkSession,
+          sdkDeps,
+          { label, coalesceKey: `gsap:${animationId}:${property}` },
+        );
+        if (cutoverCommittedOrThrow(handled)) return;
+      }
+      await commitMutationSafely(selection, mutation, {
+        label,
         coalesceKey: `gsap:${animationId}:${property}`,
         softReload: true,
-      },
-    );
+      });
+    } catch (error) {
+      sdkRef.current?.onFlushError?.(error, selection, mutation, label);
+    }
   }, [commitMutationSafely]);
 
   const updateGsapProperty = useCallback(
@@ -162,7 +177,7 @@ export function useGsapPropertyDebounce(
           sdkDeps,
           { label: `Add GSAP ${property}` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,
@@ -187,7 +202,7 @@ export function useGsapPropertyDebounce(
           sdkDeps,
           { label: `Remove GSAP ${from ? `from-${property}` : property}` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       if (from) {
         commitMutationSafely(
@@ -247,7 +262,7 @@ export function useGsapPropertyDebounce(
             coalesceKey: `gsap:${animationId}:from:${property}`,
           },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,
@@ -285,7 +300,7 @@ export function useGsapPropertyDebounce(
           sdkDeps,
           { label: `Add GSAP from-${property}` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,

package/src/hooks/useGsapPropertyDebounceFlush.test.ts

@@ -82,4 +82,39 @@ describe("useGsapPropertyDebounce flush stability (finding #7)", () => {
       root.unmount();
     });
   });
+
+  it("reports a rejected debounced flush instead of leaking an unhandled rejection", async () => {
+    const error = new Error("save failed");
+    const commitMutationSafely = vi.fn().mockRejectedValue(error);
+    const onFlushError = vi.fn();
+    let queueEdit: (() => void) | null = null;
+
+    function Harness() {
+      const ops = useGsapPropertyDebounce(commitMutationSafely, {
+        sdkSession: null,
+        sdkDeps: null,
+        activeCompPath: "index.html",
+        onFlushError,
+      });
+      queueEdit = () => ops.updateGsapProperty(selection, "tw-1", "x", 42);
+      return null;
+    }
+
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(React.createElement(Harness));
+    });
+    act(() => queueEdit?.());
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+
+    expect(onFlushError).toHaveBeenCalledWith(
+      error,
+      selection,
+      { type: "update-property", animationId: "tw-1", property: "x", value: 42 },
+      "Edit GSAP x",
+    );
+    act(() => root.unmount());
+  });
 });