@hyperframes/studio 0.8.53 → 0.8.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.53",
+  "version": "0.8.54",
   "description": "",
   "repository": {
     "type": "git",
@@ -51,11 +51,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.53",
-    "@hyperframes/sdk": "0.8.53",
-    "@hyperframes/player": "0.8.53",
-    "@hyperframes/parsers": "0.8.53",
-    "@hyperframes/studio-server": "0.8.53"
+    "@hyperframes/core": "0.8.54",
+    "@hyperframes/parsers": "0.8.54",
+    "@hyperframes/player": "0.8.54",
+    "@hyperframes/studio-server": "0.8.54",
+    "@hyperframes/sdk": "0.8.54"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +71,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.53"
+    "@hyperframes/producer": "0.8.54"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/nle/TimelinePane.tsx

@@ -1,6 +1,6 @@
 import { useCallback, type ReactNode } from "react";
 import { Timeline } from "../../player";
-import type { TimelineElement } from "../../player";
+import type { TimelineElement, TimelineTimeRange } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
 import { trackStudioExpandedClipEdit } from "../../telemetry/events";
@@ -77,6 +77,9 @@ export interface TimelinePaneProps {
   timelineToolbar?: ReactNode;
   /** Slot rendered below the timeline tracks */
   timelineFooter?: ReactNode;
+  /** Slot for a host's own overlay spanning the whole timeline area (e.g. a draft/ghost
+   *  clip), positioned absolutely the same way PreviewPane's previewOverlay is. */
+  timelineOverlay?: ReactNode;
   /** Custom clip content renderer for timeline (thumbnails, waveforms, etc.) */
   renderClipContent?: (
     element: TimelineElement,
@@ -101,6 +104,7 @@ export interface TimelinePaneProps {
   ) => Promise<void> | void;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSelectTimelineElement?: (element: TimelineElement | null) => void;
+  onRangeSelect?: (range: TimelineTimeRange | null) => void;
   /** Copy/paste/duplicate act on the store's own selection, not a passed
    *  element, so unlike onDeleteElement they need no composition-basis wrapper. */
   onCopyClip?: () => boolean;
@@ -113,6 +117,7 @@ export interface TimelinePaneProps {
 export function TimelinePane({
   timelineToolbar,
   timelineFooter,
+  timelineOverlay,
   renderClipContent,
   onFileDrop,
   onDeleteElement,
@@ -121,6 +126,7 @@ export function TimelinePane({
   onCompositionDrop,
   onBlockedEditAttempt,
   onSelectTimelineElement,
+  onRangeSelect,
   onCopyClip,
   onPasteClip,
   onDuplicateClip,
@@ -278,6 +284,7 @@ export function TimelinePane({
           onBlockedEditAttempt={onBlockedEditAttempt}
           onSplitElement={handleSplitElement}
           onSelectElement={onSelectTimelineElement}
+          onRangeSelect={onRangeSelect}
           onCopyClip={onCopyClip}
           onPasteClip={onPasteClip}
           onDuplicateClip={onDuplicateClip}
@@ -285,6 +292,9 @@ export function TimelinePane({
         />
       </div>
       {timelineFooter && <div className="shrink-0">{timelineFooter}</div>}
+      {timelineOverlay && (
+        <div className="pointer-events-none absolute inset-0 z-20">{timelineOverlay}</div>
+      )}
       {timelineDisabled && (
         <div
           className="absolute inset-0 z-30 cursor-not-allowed bg-black/18 flex items-center justify-center"

package/src/hooks/timelineAudioGroupCreate.ts

@@ -28,6 +28,19 @@ import {
   type UseTimelineElementVisibilityEditingInput,
 } from "./timelineTrackVisibility";
 
+interface AudioGroupCarveInput extends UseTimelineElementVisibilityEditingInput {
+  checkEditable?: (elements: readonly TimelineElement[]) => boolean;
+}
+
+function assertAudioGroupEditable(
+  checkEditable: AudioGroupCarveInput["checkEditable"],
+  elements: readonly TimelineElement[],
+): void {
+  if (checkEditable && !checkEditable(elements)) {
+    throw new Error("Timeline edit blocked");
+  }
+}
+
 /**
  * Assign (or restore) `data-audio-group` across a set of members.
  *
@@ -267,7 +280,8 @@ export function useAudioGroupCarveAssignment({
   previewIframeRef,
   pendingTimelineEditPathRef,
   isRecordingRef,
-}: UseTimelineElementVisibilityEditingInput): (
+  checkEditable,
+}: AudioGroupCarveInput): (
   clipIds: readonly string[],
   groupId: string,
   groupLabel?: string,
@@ -289,6 +303,7 @@ export function useAudioGroupCarveAssignment({
         const domId = runtimeAudioId(item);
         return domId !== null && wanted.has(domId);
       });
+      if (elements.length === wanted.size) assertAudioGroupEditable(checkEditable, elements);
       try {
         // Loud, not silent: an unresolved id used to leave `elements` short,
         // `createAudioGroupAndAssignMembers` returning early with no write, and
@@ -333,6 +348,7 @@ export function useAudioGroupCarveAssignment({
       isRecordingRef,
       showToast,
       projectIdRef,
+      checkEditable,
     ],
   );
 }

package/src/hooks/timelineAudioGroupVolume.ts

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { usePlayerStore } from "../player";
@@ -29,6 +29,10 @@ function patchLiveGroupAttribute(
   invalidateGroupInfoCache(iframe?.contentDocument);
 }
 
+function audioGroupAttributeLiveKey(groupId: string, attr: string): string {
+  return `${groupId}\0${attr}`;
+}
+
 /**
  * `data-volume` exactly as core reads it (`readAudioGroupVolume`): an absent or
  * empty attribute is UNITY, not zero.
@@ -210,9 +214,16 @@ export function useSetAudioGroupAttribute({
 }: UseTimelineElementVisibilityEditingInput): {
   setLive: (groupId: string, attr: string, value: string | null) => void;
   setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
+  revertLive: (groupId: string, attr: string) => void;
 } {
+  const liveBeforeRef = useRef(new Map<string, string | null>());
   const setLive = useCallback(
     (groupId: string, attr: string, value: string | null) => {
+      const key = audioGroupAttributeLiveKey(groupId, attr);
+      const target = previewIframeRef.current?.contentDocument?.getElementById(groupId);
+      if (!liveBeforeRef.current.has(key)) {
+        liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
+      }
       patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value);
       // Live too, not just on commit: a fader drag is `setLive` per frame and
       // `setQuiet` once on release, so without this the strip's own readout
@@ -221,6 +232,26 @@ export function useSetAudioGroupAttribute({
     },
     [previewIframeRef],
   );
+  const revertLive = useCallback(
+    (groupId: string, attr: string) => {
+      const key = audioGroupAttributeLiveKey(groupId, attr);
+      if (!liveBeforeRef.current.has(key)) return;
+      patchLiveGroupAttribute(
+        previewIframeRef.current,
+        groupId,
+        attr,
+        liveBeforeRef.current.get(key) ?? null,
+      );
+      syncStoredGroupAttribute(
+        groupId,
+        attr,
+        previewIframeRef.current?.contentDocument?.getElementById(groupId)?.getAttribute(attr) ??
+          null,
+      );
+      liveBeforeRef.current.delete(key);
+    },
+    [previewIframeRef],
+  );
   const setQuiet = useCallback(
     async (groupId: string, attr: string, value: string | null, label: string) => {
       if (isRecordingRef?.current) {
@@ -242,6 +273,7 @@ export function useSetAudioGroupAttribute({
           recordEdit,
           pendingTimelineEditPathRef,
         });
+        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
         syncStoredGroupAttribute(groupId, attr, value);
       } catch (error) {
         // `persistElementAttribute` leaves the live DOM at the previous value
@@ -257,6 +289,7 @@ export function useSetAudioGroupAttribute({
         console.error("[Timeline] Failed to set group attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update group";
         showToast(message);
+        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
       }
     },
     [
@@ -270,5 +303,5 @@ export function useSetAudioGroupAttribute({
       projectIdRef,
     ],
   );
-  return { setLive, setQuiet };
+  return { setLive, setQuiet, revertLive };
 }

package/src/hooks/timelineEditPermission.ts

@@ -0,0 +1,31 @@
+import { useCallback } from "react";
+import type { TimelineElement } from "../player";
+
+/** A host's verdict on one element: editable, or blocked with a reason to show. */
+export type TimelineEditPermission = true | { blocked: true; reason: string };
+
+export type CanEditTimelineElement = (element: TimelineElement) => TimelineEditPermission;
+
+/**
+ * Refuses a write when any target element is blocked, toasting the host's
+ * reason. Absent `canEdit` never refuses, so Studio itself is unchanged.
+ */
+export function useTimelineEditGate(
+  canEdit: CanEditTimelineElement | undefined,
+  showToast: (message: string, tone?: "error" | "info") => void,
+) {
+  return useCallback(
+    (targets: readonly TimelineElement[]): boolean => {
+      if (!canEdit) return true;
+      for (const element of targets) {
+        const verdict = canEdit(element);
+        if (verdict !== true) {
+          showToast(verdict.reason, "error");
+          return false;
+        }
+      }
+      return true;
+    },
+    [canEdit, showToast],
+  );
+}

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,
+    ],
+  );
+}