@hyperframes/studio 0.8.81 → 0.8.82

package/src/hooks/useDomEditCommits.ts

@@ -5,11 +5,7 @@ import { FONT_EXT } from "../utils/mediaTypes";
 
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { primaryFontFamilyValue } from "../utils/studioFontHelpers";
-import {
-  createStudioSaveHttpError,
-  StudioSaveHttpError,
-  trackStudioSaveFailure,
-} from "../utils/studioSaveDiagnostics";
+import { StudioSaveHttpError, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
 import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { CommitDomEditPatchBatches, PersistDomEditOperations } from "./domEditCommitTypes";
@@ -26,15 +22,15 @@ import { useElementLifecycleOps } from "./useElementLifecycleOps";
 import {
   AtomicElementPatchConvergenceError,
   batchesAreInlineStyleOnly,
-  formatPatchRejectionMessage,
   formatUnsafeFieldList,
-  getErrorDetail,
   patchElementBatches,
-  readErrorResponseBody,
+  postPatchElement,
+  writePreparedContent,
 } from "./useDomEditCommitsHelpers";
 import type { CutoverResult } from "../utils/sdkCutover";
-import { studioWriteHeaders } from "../utils/studioFileVersion";
 import { reseekPreviewRuntime } from "./timelineTrackVisibility";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+import { readProjectFileContent } from "../utils/studioFileHistory";
 interface RecordEditInput {
   label: string;
   coalesceKey?: string;
@@ -159,23 +155,13 @@ export function useDomEditCommits({
         return result;
       };
 
-      const readResponse = await fetch(
-        buildProjectApiPath(pid, `/files/${encodeURIComponent(targetPath)}`),
-      );
-      if (!readResponse.ok) {
-        throw await createStudioSaveHttpError(readResponse, `Failed to read ${targetPath}`);
-      }
-      const readData = (await readResponse.json()) as { content?: string };
-      const originalContent = readData.content;
-      if (typeof originalContent !== "string") {
-        throw new Error(`Missing file contents for ${targetPath}`);
-      }
-
-      if (projectIdRef.current !== expectedProjectId) {
-        throw new Error("Active project changed before the edit could be saved");
-      }
-
-      if (options?.shouldSave && !options.shouldSave()) return;
+      const readTarget = async (): Promise<string | null> => {
+        const content = await readProjectFileContent(pid, targetPath);
+        if (projectIdRef.current !== expectedProjectId) {
+          throw new Error("Active project changed before the edit could be saved");
+        }
+        return options?.shouldSave && !options.shouldSave() ? null : content;
+      };
 
       // Validate layout values BEFORE any persist path runs. The SDK cutover
       // path (onTrySdkPersist) returns early on success, so leaving this check
@@ -195,7 +181,10 @@ export function useDomEditCommits({
       // Skip the SDK path when prepareContent is set (e.g. @font-face injection
       // for a custom font): sdkCutoverPersist serializes only the patched DOM
       // and would drop the injected content. Let the server path run prepareContent.
+      // The SDK joins the file queue itself and re-reads there; this read is only its fallback.
       if (onTrySdkPersist && !options?.prepareContent) {
+        const originalContent = await readTarget();
+        if (originalContent === null) return;
         const cutover = await onTrySdkPersist(selection, operations, originalContent, targetPath, {
           label: options?.label,
           coalesceKey: options?.coalesceKey,
@@ -212,31 +201,41 @@ export function useDomEditCommits({
         }
       }
 
-      const patchResponse = await fetch(
-        buildProjectApiPath(pid, `/file-mutations/patch-element/${encodeURIComponent(targetPath)}`),
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
-          body: JSON.stringify(patchBody),
-        },
-      );
-      if (!patchResponse.ok) {
-        showToast(formatPatchRejectionMessage(await readErrorResponseBody(patchResponse)), "error");
-        throw await createStudioSaveHttpError(patchResponse, `Failed to patch ${targetPath}`, {
-          alreadyToasted: true,
-        });
-      }
-
-      const patchData = (await patchResponse.json()) as {
-        ok?: boolean;
-        changed?: boolean;
-        matched?: boolean;
-        content?: string;
-        path?: string;
-        version?: string;
+      const history = {
+        label: options?.label ?? "Edit layer",
+        coalesceKey: options?.coalesceKey,
+        coalesceMs: options?.coalesceMs,
       };
+      const prepare = options?.prepareContent;
+      // Read, server patch, follow-up write and history hold the file's queue, so no save lands between them.
+      const saved = await serializeStudioFileMutations(writeProjectFile, [targetPath], async () => {
+        const originalContent = await readTarget();
+        if (originalContent === null) return null;
+        const patchData = await postPatchElement(pid, targetPath, patchBody, showToast);
+        if (!patchData.changed) return { patchData, patchedContent: null, finalContent: null };
+
+        const patchedContent =
+          typeof patchData.content === "string" ? patchData.content : originalContent;
+        const finalContent = prepare
+          ? await writePreparedContent(
+              targetPath,
+              patchedContent,
+              prepare,
+              writeProjectFile,
+              showToast,
+            )
+          : patchedContent;
+
+        await editHistory.recordEdit({
+          ...history,
+          files: { [targetPath]: { before: originalContent, after: finalContent } },
+        });
+        return { patchData, patchedContent, finalContent };
+      });
+      if (saved === null) return;
+      const { patchData, patchedContent, finalContent } = saved;
 
-      if (!patchData.changed) {
+      if (finalContent === null) {
         if (patchData.matched === false) {
           const targetKey = selection.selector ?? selection.id ?? "selection";
           if (!reportedUnresolvableRef.current.has(targetKey)) {
@@ -258,36 +257,6 @@ export function useDomEditCommits({
           false,
         );
       }
-
-      const patchedContent =
-        typeof patchData.content === "string" ? patchData.content : originalContent;
-
-      let finalContent = patchedContent;
-      if (options?.prepareContent) {
-        const preparedContent = options.prepareContent(patchedContent, targetPath);
-        if (preparedContent !== patchedContent) {
-          try {
-            await writeProjectFile(targetPath, preparedContent, patchedContent);
-            finalContent = preparedContent;
-          } catch (error) {
-            // The patch above already landed on disk — only the prepareContent
-            // embellishment (e.g. an injected @font-face) failed to write. Keep
-            // the already-persisted patchedContent instead of throwing, which
-            // would otherwise revert a change the server already committed.
-            showToast(
-              `Saved, but couldn't finish updating ${targetPath}: ${getErrorDetail(error)}`,
-              "error",
-            );
-          }
-        }
-      }
-
-      await editHistory.recordEdit({
-        label: options?.label ?? "Edit layer",
-        coalesceKey: options?.coalesceKey,
-        coalesceMs: options?.coalesceMs,
-        files: { [targetPath]: { before: originalContent, after: finalContent } },
-      });
       forceReloadSdkSession?.();
 
       if (!options?.skipRefresh) {
@@ -350,24 +319,38 @@ export function useDomEditCommits({
             );
           }
 
-          const atomicResult = await patchElementBatches(pid, batches);
-          const allMatched =
-            atomicResult.durable && atomicResult.files.every((result) => result.allMatched);
-          const files = Object.fromEntries(
-            atomicResult.files
-              .filter((result) => result.changed)
-              .map((result) => [result.sourceFile, { before: result.before, after: result.after }]),
+          const sourceFiles = batches.map((batch) => batch.sourceFile);
+          // The server patch and its history entry hold every touched file's queue.
+          const { allMatched, changed } = await serializeStudioFileMutations(
+            writeProjectFile,
+            sourceFiles,
+            async () => {
+              const atomicResult = await patchElementBatches(pid, batches);
+              const files = Object.fromEntries(
+                atomicResult.files
+                  .filter((result) => result.changed)
+                  .map((result) => [
+                    result.sourceFile,
+                    { before: result.before, after: result.after },
+                  ]),
+              );
+              const anyChanged = Object.keys(files).length > 0;
+              if (anyChanged) {
+                await editHistory.recordEdit({
+                  label: options.label,
+                  coalesceKey: options.coalesceKey,
+                  coalesceMs: options.coalesceMs,
+                  files,
+                });
+              }
+              return {
+                allMatched:
+                  atomicResult.durable && atomicResult.files.every((result) => result.allMatched),
+                changed: anyChanged,
+              };
+            },
           );
-          const changed = Object.keys(files).length > 0;
-          if (changed) {
-            await editHistory.recordEdit({
-              label: options.label,
-              coalesceKey: options.coalesceKey,
-              coalesceMs: options.coalesceMs,
-              files,
-            });
-            forceReloadSdkSession?.();
-          }
+          if (changed) forceReloadSdkSession?.();
           const durable = allMatched;
           // A z-only reorder already applied its inline styles to the live iframe
           // DOM (and the store) synchronously, so remounting the iframe here only
@@ -399,7 +382,15 @@ export function useDomEditCommits({
         throw error;
       });
     },
-    [editHistory, forceReloadSdkSession, projectIdRef, queueDomEditSave, reloadPreview, showToast],
+    [
+      editHistory,
+      forceReloadSdkSession,
+      projectIdRef,
+      queueDomEditSave,
+      reloadPreview,
+      showToast,
+      writeProjectFile,
+    ],
   );
 
   // ── Text & style commits (delegated to useDomEditTextCommits) ──

package/src/hooks/useDomEditCommitsHelpers.ts

@@ -1,4 +1,9 @@
-import { StudioSaveHttpError, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
+import {
+  createStudioSaveHttpError,
+  StudioSaveHttpError,
+  trackStudioSaveFailure,
+} from "../utils/studioSaveDiagnostics";
+import { buildProjectApiPath } from "../utils/projectRouting";
 import type { DomEditPatchBatch } from "./domEditCommitTypes";
 import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
@@ -7,11 +12,11 @@ export function formatUnsafeFieldList(fields: Array<{ path: string }>): string {
   return fields.map((field) => field.path).join(", ");
 }
 
-export function getErrorDetail(error: unknown): string {
+function getErrorDetail(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-export async function readErrorResponseBody(
+async function readErrorResponseBody(
   response: Response,
 ): Promise<{ error?: string; fields?: string[] } | null> {
   const contentType = response.headers.get("content-type") ?? "";
@@ -19,9 +24,7 @@ export async function readErrorResponseBody(
   return (await response.json().catch(() => null)) as { error?: string; fields?: string[] } | null;
 }
 
-export function formatPatchRejectionMessage(
-  body: { error?: string; fields?: string[] } | null,
-): string {
+function formatPatchRejectionMessage(body: { error?: string; fields?: string[] } | null): string {
   if (!body?.error) return "Couldn't save edit";
   return `Couldn't save edit: ${body.error}${formatFieldsSuffix(body.fields)}`;
 }
@@ -157,3 +160,63 @@ export function batchesAreInlineStyleOnly(batches: DomEditPatchBatch[]): boolean
     batch.patches.every((patch) => patch.operations.every((op) => op.type === "inline-style")),
   );
 }
+
+export interface PatchElementResponse {
+  ok?: boolean;
+  changed?: boolean;
+  matched?: boolean;
+  content?: string;
+  path?: string;
+  version?: string;
+}
+
+type ShowToast = (message: string, tone?: "error" | "info") => void;
+
+export async function postPatchElement(
+  projectId: string,
+  targetPath: string,
+  body: unknown,
+  showToast: ShowToast,
+): Promise<PatchElementResponse> {
+  const response = await fetch(
+    buildProjectApiPath(
+      projectId,
+      `/file-mutations/patch-element/${encodeURIComponent(targetPath)}`,
+    ),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
+      body: JSON.stringify(body),
+    },
+  );
+  if (!response.ok) {
+    showToast(formatPatchRejectionMessage(await readErrorResponseBody(response)), "error");
+    throw await createStudioSaveHttpError(response, `Failed to patch ${targetPath}`, {
+      alreadyToasted: true,
+    });
+  }
+  return (await response.json()) as PatchElementResponse;
+}
+
+/** Writes `prepare`'s embellishment over the server's patch; returns what the file ends up holding. */
+export async function writePreparedContent(
+  targetPath: string,
+  patchedContent: string,
+  prepare: (html: string, sourceFile: string) => string,
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
+  showToast: ShowToast,
+): Promise<string> {
+  const preparedContent = prepare(patchedContent, targetPath);
+  if (preparedContent === patchedContent) return patchedContent;
+  try {
+    await writeProjectFile(targetPath, preparedContent, patchedContent);
+    return preparedContent;
+  } catch (error) {
+    // The patch already landed on disk; keep it rather than revert a committed change.
+    showToast(
+      `Saved, but couldn't finish updating ${targetPath}: ${getErrorDetail(error)}`,
+      "error",
+    );
+    return patchedContent;
+  }
+}

package/src/hooks/useEditorSave.ts

@@ -107,7 +107,7 @@ export function useEditorSave({
         projectId: candidate.projectId,
         label: "Edit source",
         coalesceKey: `source:${candidate.path}`,
-        files: { [candidate.path]: candidate.content },
+        files: { [candidate.path]: () => candidate.content },
         readFile: readProjectFile,
         writeFile: writeProjectFile,
         recordEdit,

package/src/hooks/useElementLifecycleOps.ts

@@ -3,7 +3,7 @@ import { useCallback } from "react";
 import { usePlayerStore } from "../player";
 import {
   readProjectFileContent,
-  saveProjectFilesWithHistory,
+  saveServerRewriteWithHistory,
   type DomEditCommitBaseParams,
 } from "../utils/studioFileHistory";
 import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
@@ -111,8 +111,6 @@ export function useElementLifecycleOps({
         (candidate) => (candidate.sourceFile || activeCompPath || "index.html") === targetPath,
       );
       try {
-        const originalContent = await readProjectFileContent(pid, targetPath);
-
         const patchTargets = sameFile.map((member) => buildDomEditPatchTarget(member));
         if (patchTargets.some((t) => !t.id && !t.selector && !t.hfId)) {
           throw new Error("Selected element has no patchable target");
@@ -125,6 +123,7 @@ export function useElementLifecycleOps({
           .map((member) => member.hfId)
           .filter((hfId): hfId is string => Boolean(hfId));
         if (onTrySdkDelete && hfIds.length === sameFile.length) {
+          const originalContent = await readProjectFileContent(pid, targetPath);
           let allHandled = true;
           for (const hfId of hfIds) {
             // The SDK owns the document it edits, so every member is removed
@@ -150,28 +149,41 @@ export function useElementLifecycleOps({
         // cost a round trip and a rewrite of the file EACH, and a canvas
         // selection runs to hundreds of members — the file ended up correct, but
         // only after long enough that Delete looked like it had done nothing.
-        const removeResponse = await fetch(
-          buildProjectApiPath(
-            pid,
-            `/file-mutations/remove-elements/${encodeURIComponent(targetPath)}`,
-          ),
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
-            body: JSON.stringify({ targets: patchTargets }),
+        const deleted = await saveServerRewriteWithHistory({
+          projectId: pid,
+          path: targetPath,
+          label: "Delete element",
+          writeFile: writeProjectFile,
+          recordEdit: editHistory.recordEdit,
+          rewrite: async (originalContent) => {
+            const removeResponse = await fetch(
+              buildProjectApiPath(
+                pid,
+                `/file-mutations/remove-elements/${encodeURIComponent(targetPath)}`,
+              ),
+              {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
+                body: JSON.stringify({ targets: patchTargets }),
+              },
+            );
+            if (!removeResponse.ok) {
+              throw await createStudioSaveHttpError(
+                removeResponse,
+                `Failed to delete element from ${targetPath}`,
+              );
+            }
+            const removeData = (await removeResponse.json()) as {
+              changed?: boolean;
+              content?: string;
+            };
+            if (!removeData.changed) return null;
+            return {
+              disk: typeof removeData.content === "string" ? removeData.content : originalContent,
+            };
           },
-        );
-        if (!removeResponse.ok) {
-          throw await createStudioSaveHttpError(
-            removeResponse,
-            `Failed to delete element from ${targetPath}`,
-          );
-        }
-        const removeData = (await removeResponse.json()) as {
-          changed?: boolean;
-          content?: string;
-        };
-        if (!removeData.changed) {
+        });
+        if (!deleted) {
           // A member the file no longer holds simply does not match, which is
           // normal for one nested inside another member already removed. Nothing
           // matching at all means the preview is describing a document the file
@@ -180,19 +192,6 @@ export function useElementLifecycleOps({
           showToast("Nothing to delete, the preview was out of date. Try again.");
           return domEditCommitDeclined("preview-stale");
         }
-        const patchedContent =
-          typeof removeData.content === "string" ? removeData.content : originalContent;
-        await saveProjectFilesWithHistory({
-          projectId: pid,
-          label: "Delete element",
-          files: { [targetPath]: patchedContent },
-          readFile: async () => originalContent,
-          // remove-element already wrote the removal, so disk holds THAT — not
-          // the content read at the top. Undo still goes back to the original.
-          diskContent: { [targetPath]: patchedContent },
-          writeFile: writeProjectFile,
-          recordEdit: editHistory.recordEdit,
-        });
 
         clearDomSelection();
         usePlayerStore.getState().setSelectedElementId(null);

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

@@ -31,19 +31,19 @@ import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-function useTestFileManager(projectId: string) {
+function useTestFileManager(projectId: string, showToast = vi.fn()) {
   return useFileManager({
     projectId,
-    showToast: vi.fn(),
+    showToast,
     recordEdit: vi.fn(async () => {}),
     setRefreshKey: vi.fn(),
   });
 }
 
-async function mountTestFileManager(projectId = "project-a") {
+async function mountTestFileManager(projectId = "project-a", showToast = vi.fn()) {
   const captured: { manager: ReturnType<typeof useFileManager> | null } = { manager: null };
   function Probe() {
-    captured.manager = useTestFileManager(projectId);
+    captured.manager = useTestFileManager(projectId, showToast);
     return null;
   }
   const root = createRoot(document.createElement("div"));
@@ -237,3 +237,50 @@ describe("useFileManager project ownership", () => {
     await act(async () => root.unmount());
   });
 });
+
+describe("useFileManager uploads", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  async function uploadClip(response: Record<string, unknown>) {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        Response.json(
+          { ok: true, files: [], skipped: [], invalid: [], ...response },
+          { status: 201 },
+        ),
+      ),
+    );
+    const showToast = vi.fn();
+    const { manager, root } = await mountTestFileManager("project-a", showToast);
+    const added = await act(() => manager.uploadProjectFiles([new File(["x"], "clip.mp4")]));
+    await act(async () => root.unmount());
+    return { added, showToast };
+  }
+
+  it("says which uploads were added without a media check, and why", async () => {
+    const reason =
+      "not checked: ffprobe was not found. Install FFmpeg or set HYPERFRAMES_FFPROBE_PATH.";
+    const { added, showToast } = await uploadClip({
+      files: ["clip.mp4"],
+      unchecked: [{ name: "clip.mp4", reason }],
+    });
+
+    expect(added).toEqual(["clip.mp4"]);
+    expect(showToast).toHaveBeenCalledWith(`Added clip.mp4, ${reason}`, "info");
+  });
+
+  it("says why each upload was not added", async () => {
+    const { added, showToast } = await uploadClip({
+      invalid: [
+        { name: "clip.mp4", reason: "no supported video stream found" },
+        { name: "song.mp3", reason: "no supported audio stream found" },
+      ],
+    });
+
+    expect(added).toEqual([]);
+    expect(showToast).toHaveBeenCalledWith(
+      "Not added: clip.mp4 (no supported video stream found), song.mp3 (no supported audio stream found)",
+    );
+  });
+});

package/src/hooks/useFileManager.ts

@@ -4,6 +4,7 @@ import { FONT_EXT, isMediaFile } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import { findTagByTarget, type PatchTarget } from "../utils/sourcePatcher";
 import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
+import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordinator";
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 import { useProjectFileWriter } from "./useProjectFileWriter";
@@ -98,16 +99,18 @@ export function useFileManager({
 
   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);
-      }
+      await serializeStudioFileMutation(writeProjectFile, conflict.filePath, async () => {
+        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],
@@ -207,8 +210,14 @@ export function useFileManager({
             showToast(`Skipped (too large): ${data.skipped.join(", ")}`);
           }
           if (data.invalid?.length) {
-            const names = data.invalid.map((entry: { name: string }) => entry.name).join(", ");
-            showToast(`Unsupported media skipped: ${names}`);
+            const why = data.invalid
+              .map((entry: { name: string; reason: string }) => `${entry.name} (${entry.reason})`)
+              .join(", ");
+            showToast(`Not added: ${why}`);
+          }
+          if (data.unchecked?.length) {
+            const names = data.unchecked.map((entry: { name: string }) => entry.name).join(", ");
+            showToast(`Added ${names}, ${data.unchecked[0].reason}`, "info");
           }
           await refreshFileTree();
           setRefreshKey((k) => k + 1);

package/src/hooks/useGroupCommits.ts

@@ -1,8 +1,7 @@
 import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback } from "react";
 import {
-  readProjectFileContent,
-  saveProjectFilesWithHistory,
+  saveServerRewriteWithHistory,
   type DomEditCommitBaseParams,
 } from "../utils/studioFileHistory";
 import {
@@ -125,36 +124,36 @@ async function commitStructuralMutation(
     | "reloadPreview"
   >,
 ): Promise<{ content?: string; groupId?: string }> {
-  const originalContent = await readProjectFileContent(pid, targetPath);
-
-  const mutateResponse = await fetch(
-    buildProjectApiPath(pid, `/file-mutations/${route}/${encodeURIComponent(targetPath)}`),
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
-      body: JSON.stringify(body),
-    },
-  );
-  if (!mutateResponse.ok) {
-    const errBody = (await mutateResponse.json().catch(() => null)) as { error?: string } | null;
-    throw new Error(errBody?.error ?? `Failed to ${label.toLowerCase()} in ${targetPath}`);
-  }
-  const mutateData = (await mutateResponse.json()) as { content?: string; groupId?: string };
-  const patchedContent =
-    typeof mutateData.content === "string" ? mutateData.content : originalContent;
-
-  await saveProjectFilesWithHistory({
+  let result: { content?: string; groupId?: string } = {};
+  await saveServerRewriteWithHistory({
     projectId: pid,
+    path: targetPath,
     label,
-    files: { [targetPath]: patchedContent },
-    readFile: async () => originalContent,
     writeFile: deps.writeProjectFile,
     recordEdit: deps.editHistory.recordEdit,
+    rewrite: async (originalContent) => {
+      const mutateResponse = await fetch(
+        buildProjectApiPath(pid, `/file-mutations/${route}/${encodeURIComponent(targetPath)}`),
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
+          body: JSON.stringify(body),
+        },
+      );
+      if (!mutateResponse.ok) {
+        const errBody = (await mutateResponse.json().catch(() => null)) as {
+          error?: string;
+        } | null;
+        throw new Error(errBody?.error ?? `Failed to ${label.toLowerCase()} in ${targetPath}`);
+      }
+      result = (await mutateResponse.json()) as { content?: string; groupId?: string };
+      return { disk: typeof result.content === "string" ? result.content : originalContent };
+    },
   });
   deps.clearDomSelection();
   deps.forceReloadSdkSession?.();
   deps.reloadPreview();
-  return mutateData;
+  return result;
 }
 
 export function useGroupCommits(params: UseGroupCommitsParams) {