@hyperframes/studio 0.8.53 → 0.8.55

package/src/hooks/timelineElementFxAttribute.ts

@@ -7,7 +7,7 @@
  * shared core `setAudioGroupAttribute` also uses.
  */
 
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import type { TimelineElement } from "../player";
 import {
   buildPatchTarget,
@@ -32,6 +32,14 @@ function patchLiveElementAttribute(
   else target.setAttribute(attr, value);
 }
 
+function elementAttributeLiveKey(
+  element: TimelineElement,
+  activeCompPath: string | null,
+  attr: string,
+): string {
+  return `${element.sourceFile || activeCompPath || "index.html"}\0${element.key ?? element.domId ?? element.id}\0${attr}`;
+}
+
 interface SetElementAttributeInput {
   projectId: string;
   activeCompPath: string | null;
@@ -92,13 +100,35 @@ export function useSetElementAttribute({
     value: string | null,
     label: string,
   ) => Promise<void>;
+  revertLive: (element: TimelineElement, attr: string) => void;
 } {
+  const liveBeforeRef = useRef(new Map<string, string | null>());
   const setLive = useCallback(
     (element: TimelineElement, attr: string, value: string | null) => {
+      const key = elementAttributeLiveKey(element, activeCompPath, attr);
+      const target = findTimelineElementInIframe(previewIframeRef.current, element, activeCompPath);
+      if (!liveBeforeRef.current.has(key)) {
+        liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
+      }
       patchLiveElementAttribute(previewIframeRef.current, element, attr, value, activeCompPath);
     },
     [previewIframeRef, activeCompPath],
   );
+  const revertLive = useCallback(
+    (element: TimelineElement, attr: string) => {
+      const key = elementAttributeLiveKey(element, activeCompPath, attr);
+      if (!liveBeforeRef.current.has(key)) return;
+      patchLiveElementAttribute(
+        previewIframeRef.current,
+        element,
+        attr,
+        liveBeforeRef.current.get(key) ?? null,
+        activeCompPath,
+      );
+      liveBeforeRef.current.delete(key);
+    },
+    [previewIframeRef, activeCompPath],
+  );
   const setQuiet = useCallback(
     async (element: TimelineElement, attr: string, value: string | null, label: string) => {
       if (isRecordingRef?.current) {
@@ -120,10 +150,12 @@ export function useSetElementAttribute({
           recordEdit,
           pendingTimelineEditPathRef,
         });
+        liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
       } catch (error) {
         console.error("[Timeline] Failed to set element attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update effect";
         showToast(message);
+        liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
       }
     },
     [
@@ -137,5 +169,5 @@ export function useSetElementAttribute({
       projectIdRef,
     ],
   );
-  return { setLive, setQuiet };
+  return { setLive, setQuiet, revertLive };
 }

package/src/hooks/useFileManager.ts

@@ -1,18 +1,13 @@
-import { useState, useCallback, useMemo, useRef } from "react";
+import { useState, useCallback, useRef } from "react";
 import type { EditingFile } from "../utils/studioHelpers";
 import { FONT_EXT, isMediaFile } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { findTagByTarget, type PatchTarget } from "../utils/sourcePatcher";
-import {
-  createStudioSaveHttpError,
-  retryStudioSave,
-  StudioFileConflictError,
-  StudioSaveNetworkError,
-} from "../utils/studioSaveDiagnostics";
-import { studioExpectedFileVersion, studioWriteHeaders } from "../utils/studioFileVersion";
+import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
+import { useProjectFileWriter } from "./useProjectFileWriter";
 
 // ── Types ──
 
@@ -50,17 +45,13 @@ 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],
-  );
+  const {
+    fileVersions,
+    readProjectFile,
+    writeProjectFile: writeProjectFileRaw,
+    readOptionalProjectFile,
+    observeProjectFileVersion,
+  } = useProjectFileWriter({ projectId });
 
   // ── File tree ──
 
@@ -74,117 +65,24 @@ export function useFileManager({
     fontAssets,
   } = useFileTree({ projectId, projectIdRef });
 
-  // ── Core file I/O ──
-
-  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, 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`);
-        }
-      }
-      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.
-        let response: Response;
-        try {
-          response = await fetch(
-            `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
-            {
-              method: "PUT",
-              headers: {
-                "Content-Type": "text/plain",
-                ...studioWriteHeaders(),
-                ...(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) {
       setEditingFile({ path, 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 : "";
+  // Studio's own editor tab mirrors whatever it just wrote, on top of the
+  // shared writer — a host mounting useProjectFileWriter directly has no
+  // editor tab and does not need this.
+  const writeProjectFile = useCallback(
+    async (path: string, content: string, expectedContent?: string): Promise<void> => {
+      const writeProjectId = projectIdRef.current;
+      await writeProjectFileRaw(path, content, expectedContent);
+      if (projectIdRef.current === writeProjectId && editingPathRef.current === path) {
+        setEditingFile({ path, content });
+      }
     },
-    [fileVersions, projectId],
+    [writeProjectFileRaw],
   );
 
   // ── Editor save (debounced content change) ──

package/src/hooks/usePersistentEditHistory.ts

@@ -33,7 +33,7 @@ interface ApplyCallbacks {
   serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
 }
 
-interface UsePersistentEditHistoryOptions {
+export interface UsePersistentEditHistoryOptions {
   projectId: string | null;
   storage?: EditHistoryStorageAdapter;
   now?: () => number;

package/src/hooks/useProjectFileWriter.ts

@@ -0,0 +1,150 @@
+import { useCallback, useMemo } from "react";
+import {
+  createStudioSaveHttpError,
+  retryStudioSave,
+  StudioFileConflictError,
+  StudioSaveNetworkError,
+} from "../utils/studioSaveDiagnostics";
+import { studioExpectedFileVersion, studioWriteHeaders } from "../utils/studioFileVersion";
+
+export interface UseProjectFileWriterOptions {
+  projectId: string | null;
+}
+
+// The etag-guarded project-file read/write pair every Studio save path
+// shares. A host mounting hand editing outside Studio needs only this, not
+// the full file manager (file tree, editor tabs, uploads, font assets).
+export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions) {
+  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],
+  );
+
+  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 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],
+  );
+
+  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`);
+        }
+      }
+      // fallow-ignore-next-line complexity
+      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.
+        let response: Response;
+        try {
+          response = await fetch(
+            `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
+            {
+              method: "PUT",
+              headers: {
+                "Content-Type": "text/plain",
+                ...studioWriteHeaders(),
+                ...(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);
+      });
+    },
+    [fileVersions, projectId],
+  );
+
+  return useMemo(
+    () => ({
+      fileVersions,
+      readProjectFile,
+      writeProjectFile,
+      readOptionalProjectFile,
+      observeProjectFileVersion,
+    }),
+    [
+      fileVersions,
+      readProjectFile,
+      writeProjectFile,
+      readOptionalProjectFile,
+      observeProjectFileVersion,
+    ],
+  );
+}

package/src/hooks/useTimelineAssetDropOps.test.tsx

@@ -16,19 +16,29 @@ afterEach(() => {
 });
 
 type DropFn = ReturnType<typeof useTimelineAssetDropOps>["handleTimelineAssetDrop"];
+type FileDropFn = ReturnType<typeof useTimelineAssetDropOps>["handleTimelineFileDrop"];
+type CompositionDropFn = ReturnType<
+  typeof useTimelineAssetDropOps
+>["handleTimelineCompositionDrop"];
 
 function renderDropHook(
   sourceContent: string,
   writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
   timelineElements: TimelineElement[] = [],
+  checkEditable?: (targets: readonly TimelineElement[]) => boolean,
+  uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]> = vi
+    .fn()
+    .mockResolvedValue([]),
 ) {
   vi.stubGlobal(
     "fetch",
     vi.fn().mockResolvedValue({ ok: true, json: async () => ({ content: sourceContent }) }),
   );
   let drop: DropFn | null = null;
+  let fileDrop: FileDropFn | null = null;
+  let compositionDrop: CompositionDropFn | null = null;
   function Harness() {
-    const { handleTimelineAssetDrop } = useTimelineAssetDropOps({
+    const handlers = useTimelineAssetDropOps({
       projectIdRef: { current: "project" },
       activeCompPath: "index.html",
       timelineElements,
@@ -36,13 +46,19 @@ function renderDropHook(
       writeProjectFile,
       recordEdit: vi.fn().mockResolvedValue(undefined),
       reloadPreview: vi.fn(),
-      uploadProjectFiles: vi.fn().mockResolvedValue([]),
+      uploadProjectFiles,
+      checkEditable,
     });
-    drop = handleTimelineAssetDrop;
+    drop = handlers.handleTimelineAssetDrop;
+    fileDrop = handlers.handleTimelineFileDrop;
+    compositionDrop = handlers.handleTimelineCompositionDrop;
     return null;
   }
   mountReactHarness(<Harness />);
-  return () => drop!;
+  return Object.assign(() => drop!, {
+    file: () => fileDrop!,
+    composition: () => compositionDrop!,
+  });
 }
 
 describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
@@ -124,4 +140,46 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     expect(written).toContain('id="hidden" data-start="0" data-track-index="1"');
     expect(written).toMatch(/<video id="clip"[^>]*data-track-index="1"/);
   });
+
+  it("refuses an asset drop before reading or writing when editing is blocked", async () => {
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const checkEditable = vi.fn(() => false);
+    const getDrop = renderDropHook(
+      '<main data-composition-id="scene" data-duration="10"></main>',
+      writeProjectFile,
+      [],
+      checkEditable,
+    );
+
+    await act(async () => {
+      await getDrop()("clip.mp4", { start: 1, track: 0 }, 2);
+    });
+
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(checkEditable).toHaveBeenCalledWith([
+      expect.objectContaining({ sourceFile: "index.html", start: 1, track: 0 }),
+    ]);
+  });
+
+  it("refuses file and composition drops before their writes when editing is blocked", async () => {
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const uploadProjectFiles = vi.fn().mockResolvedValue(["clip.mp4"]);
+    const getDrop = renderDropHook(
+      '<main data-composition-id="scene" data-duration="10"></main>',
+      writeProjectFile,
+      [],
+      () => false,
+      uploadProjectFiles,
+    );
+    const fetchMock = vi.mocked(globalThis.fetch);
+
+    await act(async () => {
+      await getDrop.file()([new File(["clip"], "clip.mp4")], { start: 1, track: 0 });
+      await getDrop.composition()("scene.html", { start: 1, track: 0 });
+    });
+
+    expect(uploadProjectFiles).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(writeProjectFile).not.toHaveBeenCalled();
+  });
 });

package/src/hooks/useTimelineAssetDropOps.ts

@@ -38,6 +38,20 @@ function fileDropPlacement(
   return index === 0 ? { ...dropped, ...next } : { ...next, track: landedTrack ?? next.track };
 }
 
+function timelineDropTarget(
+  sourceFile: string,
+  placement: Pick<TimelineElement, "start" | "track">,
+): TimelineElement {
+  return {
+    id: "timeline-drop",
+    tag: "div",
+    start: placement.start,
+    duration: 0,
+    track: placement.track,
+    sourceFile,
+  };
+}
+
 interface UseTimelineAssetDropOpsOptions {
   projectIdRef: MutableRefObject<string | null>;
   activeCompPath: string | null;
@@ -50,6 +64,7 @@ interface UseTimelineAssetDropOpsOptions {
   isRecordingRef?: RefObject<boolean>;
   forceReloadSdkSession?: () => void;
   observeProjectFileVersion?: (path: string, version: string | null) => void;
+  checkEditable?: (targets: readonly TimelineElement[]) => boolean;
 }
 
 export function useTimelineAssetDropOps({
@@ -64,6 +79,7 @@ export function useTimelineAssetDropOps({
   isRecordingRef,
   forceReloadSdkSession,
   observeProjectFileVersion,
+  checkEditable,
 }: UseTimelineAssetDropOpsOptions) {
   // fallow-ignore-next-line complexity
   const dropAssetAt = useCallback(
@@ -77,6 +93,10 @@ export function useTimelineAssetDropOps({
         showToast("Cannot edit timeline while recording", "error");
         return undefined;
       }
+      const targetPath = activeCompPath || "index.html";
+      if (checkEditable && !checkEditable([timelineDropTarget(targetPath, placement)])) {
+        return undefined;
+      }
       const pid = projectIdRef.current;
       if (!pid) throw new Error("No active project");
 
@@ -86,7 +106,6 @@ export function useTimelineAssetDropOps({
         return undefined;
       }
 
-      const targetPath = activeCompPath || "index.html";
       try {
         const originalContent = await readFileContent(pid, targetPath);
 
@@ -172,6 +191,7 @@ export function useTimelineAssetDropOps({
       reloadPreview,
       isRecordingRef,
       forceReloadSdkSession,
+      checkEditable,
     ],
   );
 
@@ -190,6 +210,11 @@ export function useTimelineAssetDropOps({
         showToast("Cannot edit timeline while recording", "error");
         return;
       }
+      const targetPath = activeCompPath || "index.html";
+      const initialPlacement = placement ?? { start: 0, track: 0 };
+      if (checkEditable && !checkEditable([timelineDropTarget(targetPath, initialPlacement)])) {
+        return;
+      }
       const pid = projectIdRef.current;
       if (!pid) return;
       const uploaded = await uploadProjectFiles(files);
@@ -215,7 +240,15 @@ export function useTimelineAssetDropOps({
         if (index === 0) landedTrack = track;
       }
     },
-    [dropAssetAt, projectIdRef, uploadProjectFiles, isRecordingRef, showToast],
+    [
+      activeCompPath,
+      checkEditable,
+      dropAssetAt,
+      projectIdRef,
+      uploadProjectFiles,
+      isRecordingRef,
+      showToast,
+    ],
   );
 
   const handleTimelineCompositionDrop = useCallback(
@@ -224,9 +257,12 @@ export function useTimelineAssetDropOps({
         showToast("Cannot edit timeline while recording", "error");
         return;
       }
+      const targetPath = activeCompPath || "index.html";
+      if (checkEditable && !checkEditable([timelineDropTarget(targetPath, placement)])) {
+        return;
+      }
       const pid = projectIdRef.current;
       if (!pid) throw new Error("No active project");
-      const targetPath = activeCompPath || "index.html";
       try {
         await commitTimelineCompositionInsertion({
           projectId: pid,
@@ -251,6 +287,7 @@ export function useTimelineAssetDropOps({
     },
     [
       activeCompPath,
+      checkEditable,
       forceReloadSdkSession,
       isRecordingRef,
       observeProjectFileVersion,