@hyperframes/studio 0.7.58 → 0.7.60

package/src/utils/sdkResolverShadow.ts

@@ -15,11 +15,12 @@
  * Telemetry-only — never writes to disk, never affects the user-visible edit.
  */
 
+import { openComposition } from "@hyperframes/sdk";
 import type { Composition, JsonPatchOp } from "@hyperframes/sdk";
 import type { PatchOperation } from "./sourcePatcher";
 import { STUDIO_SDK_RESOLVER_SHADOW_ENABLED } from "../components/editor/manualEditingAvailability";
 import { patchOpsToSdkEditOps } from "./sdkOpMapping";
-import { trackStudioEvent, flushViaBeacon } from "./studioTelemetry";
+import { trackStudioEvent } from "./studioTelemetry";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -234,95 +235,14 @@ export function sdkResolverShadowCheck(
   }
 }
 
-// ─── Attempt counter (denominator for the soak gate) ──────────────────────────
-//
-// The three emit functions below only fire a PostHog event on divergence —
-// parity is silent, by design, to avoid firing on every edit. That leaves no
-// way to compute a rate (divergences / attempts): we can count failures but
-// never attempts. This counter tracks attempts in memory and rolls them up
-// into ONE low-frequency event instead of firing per-attempt, which would
-// recreate the exact chattiness problem the divergence-only design avoids.
-
-const attemptCounts: Record<string, number> = {};
-
-/**
- * Record that the resolver-shadow tripwire ran for `opLabel`, regardless of
- * outcome (parity or divergence). No flag check of its own — only ever called
- * from inside the three emit functions below, after their own
- * STUDIO_SDK_RESOLVER_SHADOW_ENABLED guard, so it's already flag-gated.
- */
-export function recordAttempt(opLabel: string): void {
-  attemptCounts[opLabel] = (attemptCounts[opLabel] ?? 0) + 1;
-  ensureAttemptFlushScheduled();
-}
-
-/**
- * Return the accumulated attempt counts since the last flush (or `null` if
- * nothing has been recorded — no point emitting an empty rollup), and reset
- * the counter to empty.
- */
-export function flushAttemptCounts(): Record<string, number> | null {
-  const keys = Object.keys(attemptCounts);
-  if (keys.length === 0) return null;
-  const snapshot: Record<string, number> = {};
-  for (const key of keys) {
-    snapshot[key] = attemptCounts[key];
-    delete attemptCounts[key];
-  }
-  return snapshot;
-}
-
-const ATTEMPT_FLUSH_INTERVAL_MS = 5 * 60_000;
-let attemptFlushTimer: ReturnType<typeof setInterval> | null = null;
-let attemptVisibilityHandler: (() => void) | null = null;
-
-function flushAndEmitAttempts(): void {
-  const counts = flushAttemptCounts();
-  if (counts === null) return;
-  trackStudioEvent("sdk_resolver_shadow_attempt", { counts: JSON.stringify(counts) });
-}
-
-// Lazily starts the rollup timer + visibilitychange listener on the FIRST
-// attempt in a session — mirrors studioTelemetry.ts's own lazy flushTimer
-// start, so a session that never exercises the tripwire never runs a
-// background timer.
-function ensureAttemptFlushScheduled(): void {
-  if (!attemptFlushTimer) {
-    attemptFlushTimer = setInterval(flushAndEmitAttempts, ATTEMPT_FLUSH_INTERVAL_MS);
-  }
-  if (!attemptVisibilityHandler && typeof document !== "undefined") {
-    attemptVisibilityHandler = () => {
-      if (document.visibilityState !== "hidden") return;
-      flushAndEmitAttempts();
-      // studioTelemetry.ts registers its own visibilitychange listener (on
-      // window, at module load) that drains its queue via sendBeacon. Listener
-      // execution order between that handler and this one (on document,
-      // registered lazily) is not something to rely on — whichever runs
-      // first could otherwise beacon-flush before or after this rollup lands
-      // in the queue. Forcing a beacon flush here makes delivery of this
-      // rollup event correct regardless of that order.
-      flushViaBeacon();
-    };
-    document.addEventListener("visibilitychange", attemptVisibilityHandler);
-  }
-}
-
-/**
- * Test-only: clears the lazy timer/listener singleton state so tests can
- * verify the "starts on first attempt" behavior in isolation, without an
- * earlier test's real-timer interval (or visibilitychange listener) silently
- * surviving into a later test. Does NOT touch attemptCounts — only the
- * scheduling state. Not part of the public module contract; only imported
- * from sdkResolverShadow.test.ts.
- */
-export function __resetAttemptSchedulingForTests(): void {
-  if (attemptFlushTimer) clearInterval(attemptFlushTimer);
-  attemptFlushTimer = null;
-  if (attemptVisibilityHandler && typeof document !== "undefined") {
-    document.removeEventListener("visibilitychange", attemptVisibilityHandler);
-  }
-  attemptVisibilityHandler = null;
-}
+// Attempt counting (the soak-gate denominator) lives in sdkResolverAttempts.ts;
+// re-exported here so existing consumers/tests keep one import surface.
+export {
+  recordAttempt,
+  flushAttemptCounts,
+  __resetAttemptSchedulingForTests,
+} from "./sdkResolverAttempts";
+import { recordAttempt } from "./sdkResolverAttempts";
 
 // ─── Telemetry ────────────────────────────────────────────────────────────────
 
@@ -380,15 +300,41 @@ function reportEmptySession(session: Composition, opLabel: string): boolean {
   return true;
 }
 
+/** Shape shared by every resolver-shadow entry point's optional path pair. */
+export interface ResolverShadowPaths {
+  targetPath?: string;
+  compositionPath?: string | null;
+}
+
+/**
+ * Cross-file edit: the session models ONLY the active composition, so a
+ * target living in another file is structurally unresolvable — the cutover
+ * gates decline it (wrongCompositionFile) and it can never cut over. Every
+ * tripwire entry point skips entirely (no event, no attempt): the op belongs
+ * in neither the divergence count nor the attempt denominator of the soak
+ * rate. PostHog 0.7.41: one cross-file editing session emitted 479 false
+ * element_not_found events before this rule existed. Callers that pass no
+ * paths (isolated consumers/tests) run as before.
+ */
+function isCrossFileEdit(paths?: ResolverShadowPaths): boolean {
+  return (
+    paths?.targetPath !== undefined &&
+    paths.compositionPath != null &&
+    paths.targetPath !== paths.compositionPath
+  );
+}
+
 export function runResolverShadow(
   session: Composition,
   hfId: string | null | undefined,
   ops: PatchOperation[],
   sourceContent?: string,
+  paths?: ResolverShadowPaths,
 ): void {
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!hfId) return;
   try {
+    if (isCrossFileEdit(paths)) return;
     if (reportEmptySession(session, "dom-edit")) return;
     recordAttempt("dom-edit");
     const mismatches = sdkResolverShadowCheck(session, hfId, ops, sourceContent);
@@ -434,15 +380,41 @@ export function runResolverShadow(
  *
  * No-op when the shadow flag is off; never throws; never mutates the session.
  */
+/**
+ * Source-truth check for a missed hf-id: read the target file and decide
+ * whether the miss is a runtime-generated node (id absent from source —
+ * suppress, the SDK cannot model it by design) or a reportable divergence
+ * (id present → strict attribute count for the event; read failure → fail
+ * open, tagged). Mirrors checkAnimationIdOnDisk's error discipline.
+ */
+async function checkHfIdInSource(
+  hfId: string,
+  readSource?: () => Promise<string | undefined>,
+): Promise<{ suppress: boolean; strictCount?: number; sourceReadFailed: boolean }> {
+  if (!readSource) return { suppress: false, sourceReadFailed: false };
+  let source: string | undefined;
+  try {
+    source = await readSource();
+  } catch {
+    return { suppress: false, sourceReadFailed: true }; // fail-open
+  }
+  if (source === undefined) return { suppress: false, sourceReadFailed: false };
+  // Loose substring match — biased toward keeping signal (see sourceLooseMatchOnly).
+  if (!source.includes(hfId)) return { suppress: true, sourceReadFailed: false };
+  return { suppress: false, strictCount: countHfIdInSource(source, hfId), sourceReadFailed: false };
+}
+
 export async function recordResolverParity(
   session: Composition | null | undefined,
   hfId: string | null | undefined,
   opLabel: string,
   readSource?: () => Promise<string | undefined>,
+  paths?: ResolverShadowPaths,
 ): Promise<void> {
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !hfId) return;
   try {
+    if (isCrossFileEdit(paths)) return;
     if (reportEmptySession(session, opLabel)) return;
     recordAttempt(opLabel);
     if (resolveSnapshot(session, hfId)) return; // resolves — parity, nothing to record
@@ -453,19 +425,10 @@ export async function recordResolverParity(
     // state this field exists to diagnose.
     const sessionElementCount = session.getElements().length;
     // Cheap check passed above, so the source read only runs on a real divergence.
-    let source: string | undefined;
-    let sourceReadFailed = false;
-    if (readSource) {
-      try {
-        source = await readSource();
-      } catch {
-        source = undefined; // fail-open: a read error must not drop a real divergence
-        sourceReadFailed = true;
-      }
-    }
-    // Runtime-generated node the static parse can't model — suppress (mirrors the dom-edit path).
-    if (source !== undefined && !source.includes(hfId)) return;
-    const strictCount = source !== undefined ? countHfIdInSource(source, hfId) : undefined;
+    // Runtime-generated node the static parse can't model → suppressed inside.
+    const verdict = await checkHfIdInSource(hfId, readSource);
+    if (verdict.suppress) return;
+    const { strictCount, sourceReadFailed } = verdict;
     trackStudioEvent("sdk_resolver_shadow", {
       hfId,
       opLabel,
@@ -505,24 +468,94 @@ export async function recordResolverParity(
  *
  * No-op when the shadow flag is off; never throws; never mutates the session.
  */
-export function recordAnimationResolverParity(
+/**
+ * Disk-truth disambiguation for a missed animationId: the GSAP panel computes
+ * animationIds from the CURRENT on-disk script (the server read path re-reads
+ * per render), while the session's parsed id space reflects the last session
+ * reload. An edit that shifts tween positions shifts every
+ * `selector-method-position` id, so a panel op landing before the reload
+ * targets an id the session has never seen — a sync gap, not a resolver bug
+ * (the 0.7.48 keyframe-op class). `staleSession` = a fresh parse of the file
+ * resolves the id (suppress); `diskChecked` = the fresh parse ran and ALSO
+ * missed (a trustworthy real divergence); read errors fail open.
+ */
+async function checkAnimationIdOnDisk(
+  animationId: string,
+  sourcePromise: Promise<string | undefined>,
+): Promise<{ staleSession: boolean; diskChecked: boolean; sourceReadFailed: boolean }> {
+  let source: string | undefined;
+  try {
+    source = await sourcePromise;
+  } catch {
+    return { staleSession: false, diskChecked: false, sourceReadFailed: true };
+  }
+  if (source === undefined) {
+    return { staleSession: false, diskChecked: false, sourceReadFailed: false };
+  }
+  // A parse failure (malformed script the user just introduced) means the
+  // source can't serve as ground truth — treat it exactly like a read failure
+  // (fail open, tagged) instead of letting the outer never-propagate catch
+  // swallow the whole divergence event.
+  let disk: Composition;
+  try {
+    disk = await openComposition(source, { history: false });
+  } catch {
+    return { staleSession: false, diskChecked: false, sourceReadFailed: true };
+  }
+  try {
+    return {
+      staleSession: disk.getAllAnimationIds().has(animationId),
+      diskChecked: true,
+      sourceReadFailed: false,
+    };
+  } finally {
+    disk.dispose();
+  }
+}
+
+export async function recordAnimationResolverParity(
   session: Composition | null | undefined,
   animationId: string,
   opLabel: string,
-): void {
+  readSource?: () => Promise<string | undefined>,
+  paths?: ResolverShadowPaths,
+): Promise<void> {
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !animationId) return;
   try {
+    if (isCrossFileEdit(paths)) return;
     recordAttempt(opLabel);
     const elements = session.getElements();
     const resolves =
       elements.some((el) => el.animationIds.includes(animationId)) ||
       session.getAllAnimationIds().has(animationId);
     if (resolves) return; // SDK locates the animation — parity
+    // Capture BEFORE any await (fire-and-forget caller mutates right after).
+    const sessionElementCount = elements.length;
+    let diskChecked = false;
+    let sourceReadFailed = false;
+    if (readSource) {
+      // Start the read SYNCHRONOUSLY, before returning control to the caller:
+      // the caller's cutover persist writes the new content to this same file
+      // moments later, and a read dispatched after that write would check the
+      // POST-edit disk (e.g. a remove op's target legitimately gone → false
+      // "genuine divergence"). Dispatching the request here, in the same sync
+      // prologue as the miss check, orders it ahead of the caller's write.
+      const sourcePromise = (async () => readSource())();
+      const verdict = await checkAnimationIdOnDisk(animationId, sourcePromise);
+      if (verdict.staleSession) return; // sync gap, not a resolver bug — suppress
+      diskChecked = verdict.diskChecked;
+      sourceReadFailed = verdict.sourceReadFailed;
+    }
     trackStudioEvent("sdk_resolver_shadow", {
       animationId,
       opLabel,
-      sessionElementCount: elements.length,
+      sessionElementCount,
+      // The id missed a fresh parse of the on-disk file too — this is a real
+      // resolver divergence, not session staleness. Absent when no reader was
+      // wired or the read failed (see sourceReadFailed).
+      ...(diskChecked ? { diskChecked: true } : {}),
+      ...(sourceReadFailed ? { sourceReadFailed: true } : {}),
       mismatchCount: 1,
       mismatches: JSON.stringify([
         { kind: "animation_not_found", animationId } satisfies SdkResolverMismatch,

package/src/utils/setSlideshowManifest.test.ts

@@ -74,11 +74,8 @@ describe("persistSlideshowManifest — op construction", () => {
     const deps = makeDeps(writeProjectFile);
     const recordEdit = deps.editHistory.recordEdit as ReturnType<typeof vi.fn>;
 
-    const mockSession = { serialize: vi.fn().mockReturnValue(originalHtml) };
-
     await persistSlideshowManifest({
       manifest: { slides: [{ sceneId: "scene-2" }] },
-      sdkSession: mockSession as never,
       originalContent: originalHtml,
       targetPath: "/proj/comp.html",
       deps,
@@ -96,11 +93,8 @@ describe("persistSlideshowManifest — op construction", () => {
     const baseHtml = "<html><head></head><body></body></html>";
     const writeProjectFile = vi.fn().mockResolvedValue(undefined);
     const deps = makeDeps(writeProjectFile);
-    const mockSession = { serialize: vi.fn().mockReturnValue(baseHtml) };
-
     await persistSlideshowManifest({
       manifest: { slides: [{ sceneId: "new-scene" }] },
-      sdkSession: mockSession as never,
       originalContent: baseHtml,
       targetPath: "/proj/comp.html",
       deps,
@@ -122,11 +116,8 @@ describe("persistSlideshowManifest — op construction", () => {
 
     const writeProjectFile = vi.fn().mockResolvedValue(undefined);
     const deps = makeDeps(writeProjectFile);
-    const mockSession = { serialize: vi.fn().mockReturnValue(twoIslandHtml) };
-
     await persistSlideshowManifest({
       manifest: { slides: [{ sceneId: "fresh" }] },
-      sdkSession: mockSession as never,
       originalContent: twoIslandHtml,
       targetPath: "/proj/comp.html",
       deps,

package/src/utils/setSlideshowManifest.ts

@@ -5,7 +5,7 @@
  * embedded in the composition HTML.  Because <script> nodes are not tracked by
  * the SDK element tree (they have no hf-id), we cannot use a `setText` dispatch
  * op.  Instead we:
- *   1. Call `sdkSession.serialize()` to get the current HTML.
+ *   1. Acquire the per-file transaction and read the current on-disk HTML.
  *   2. Replace or insert the island with the new manifest JSON.
  *   3. Write via `persistSdkSerialize` — the same low-level writer used by the
  *      other SDK-cutover paths (sdkDeletePersist, sdkTimingPersist, etc.).
@@ -23,7 +23,6 @@ import {
   parseSlideshowManifest,
   slideshowIslandRegex,
 } from "@hyperframes/core/slideshow";
-import type { Composition } from "@hyperframes/sdk";
 import type { CutoverDeps } from "./sdkCutover";
 import { persistSdkSerialize } from "./sdkCutover";
 
@@ -46,8 +45,6 @@ export function buildSlideshowIslandHtml(manifest: SlideshowManifest): string {
 
 export interface PersistSlideshowArgs {
   manifest: SlideshowManifest;
-  /** Live SDK Composition session — used only to read the current serialized HTML. */
-  sdkSession: Pick<Composition, "serialize">;
   /** Exact on-disk bytes for the undo-history `before` baseline. */
   originalContent: string;
   targetPath: string;
@@ -62,7 +59,7 @@ export interface PersistSlideshowArgs {
 }
 
 export async function persistSlideshowManifest(args: PersistSlideshowArgs): Promise<void> {
-  const { manifest, sdkSession, originalContent, targetPath, deps, label, coalesceKey } = args;
+  const { manifest, originalContent, targetPath, deps, label, coalesceKey } = args;
 
   const islandHtml = buildSlideshowIslandHtml(manifest);
 
@@ -77,26 +74,22 @@ export async function persistSlideshowManifest(args: PersistSlideshowArgs): Prom
     throw new Error(`refusing to persist invalid slideshow manifest: ${(err as Error).message}`);
   }
 
-  const current = sdkSession.serialize();
-
-  // Strip ALL existing islands (handles the case where two stale islands
-  // accumulated) then insert exactly one fresh island.
-  const stripped = current.replace(ISLAND_RE, "");
-
-  let after: string;
-  const bodyClose = stripped.lastIndexOf("</body>");
-  if (bodyClose !== -1) {
-    after = stripped.slice(0, bodyClose) + islandHtml + "\n" + stripped.slice(bodyClose);
-  } else {
-    after = stripped + "\n" + islandHtml;
-  }
-
-  // No-op gate: if the rewritten HTML is byte-identical to the current serialized
-  // HTML, skip the write — avoids a spurious disk write and a no-op undo entry.
-  if (after === current) return;
-
-  await persistSdkSerialize(after, targetPath, originalContent, deps, {
-    label: label ?? "Edit slideshow",
-    ...(coalesceKey ? { coalesceKey } : {}),
-  });
+  await persistSdkSerialize(
+    (current) => {
+      // Strip ALL existing islands (handles the case where two stale islands
+      // accumulated) then insert exactly one fresh island.
+      const stripped = current.replace(ISLAND_RE, "");
+      const bodyClose = stripped.lastIndexOf("</body>");
+      return bodyClose !== -1
+        ? stripped.slice(0, bodyClose) + islandHtml + "\n" + stripped.slice(bodyClose)
+        : stripped + "\n" + islandHtml;
+    },
+    targetPath,
+    originalContent,
+    deps,
+    {
+      label: label ?? "Edit slideshow",
+      ...(coalesceKey ? { coalesceKey } : {}),
+    },
+  );
 }

package/src/utils/studioFileHistory.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
+import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
 
 describe("saveProjectFilesWithHistory", () => {
   it("reads before content, writes after content, and records a history entry", async () => {
@@ -153,4 +154,44 @@ describe("saveProjectFilesWithHistory", () => {
       ["index.html", "index-before"],
     ]);
   });
+
+  it("reads and writes after an earlier same-file mutation completes", async () => {
+    let disk = "before";
+    let release!: () => void;
+    const blocked = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const writeFile = vi.fn(async (_path: string, content: string) => {
+      disk = content;
+    });
+    const priorMutation = serializeStudioFileMutation(writeFile, "index.html", async () => {
+      await blocked;
+      disk = "sdk-after";
+    });
+    const readFile = vi.fn(async () => disk);
+    const recordEdit = vi.fn();
+
+    const save = saveProjectFilesWithHistory({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      files: { "index.html": "editor-after" },
+      readFile,
+      writeFile,
+      recordEdit,
+    });
+
+    await Promise.resolve();
+    expect(readFile).not.toHaveBeenCalled();
+    release();
+    await priorMutation;
+    await save;
+
+    expect(disk).toBe("editor-after");
+    expect(recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        files: { "index.html": { before: "sdk-after", after: "editor-after" } },
+      }),
+    );
+  });
 });

package/src/utils/studioFileHistory.ts

@@ -1,5 +1,6 @@
 import type { MutableRefObject } from "react";
 import type { EditHistoryKind } from "./editHistory";
+import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
 import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
 
 export interface RecordEditInput {
@@ -13,7 +14,7 @@ export interface RecordEditInput {
 export interface DomEditCommitBaseParams {
   activeCompPath: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: ProjectFileWriter;
   domEditSaveTimestampRef: MutableRefObject<number>;
   editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
   projectIdRef: MutableRefObject<string | null>;
@@ -21,6 +22,8 @@ export interface DomEditCommitBaseParams {
   clearDomSelection: () => void;
 }
 
+type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
+
 interface SaveProjectFilesWithHistoryInput {
   projectId: string;
   label: string;
@@ -29,7 +32,7 @@ interface SaveProjectFilesWithHistoryInput {
   coalesceMs?: number;
   files: Record<string, string>;
   readFile: (path: string) => Promise<string>;
-  writeFile: (path: string, content: string) => Promise<void>;
+  writeFile: ProjectFileWriter;
   recordEdit: (entry: RecordEditInput) => Promise<void>;
 }
 
@@ -55,37 +58,39 @@ export async function saveProjectFilesWithHistory({
   writeFile,
   recordEdit,
 }: SaveProjectFilesWithHistoryInput): Promise<string[]> {
-  const snapshots: Record<string, { before: string; after: string }> = {};
-  for (const [path, after] of Object.entries(files)) {
-    const before = await readFile(path);
-    if (before !== after) {
-      snapshots[path] = { before, after };
+  return serializeStudioFileMutations(writeFile, Object.keys(files), async () => {
+    const snapshots: Record<string, { before: string; after: string }> = {};
+    for (const [path, after] of Object.entries(files)) {
+      const before = await readFile(path);
+      if (before !== after) {
+        snapshots[path] = { before, after };
+      }
     }
-  }
-
-  const changedPaths = Object.keys(snapshots);
-  if (changedPaths.length === 0) return [];
 
-  const writtenPaths: string[] = [];
-  try {
-    for (const path of changedPaths) {
-      await writeFile(path, snapshots[path].after);
-      writtenPaths.push(path);
-    }
+    const changedPaths = Object.keys(snapshots);
+    if (changedPaths.length === 0) return [];
 
-    await recordEdit({ label, kind, coalesceKey, coalesceMs, files: snapshots });
-  } catch (error) {
+    const writtenPaths: string[] = [];
     try {
-      for (const path of writtenPaths.reverse()) {
-        await writeFile(path, snapshots[path].before);
+      for (const path of changedPaths) {
+        await writeFile(path, snapshots[path].after, snapshots[path].before);
+        writtenPaths.push(path);
+      }
+
+      await recordEdit({ label, kind, coalesceKey, coalesceMs, files: snapshots });
+    } catch (error) {
+      try {
+        for (const path of writtenPaths.reverse()) {
+          await writeFile(path, snapshots[path].before, snapshots[path].after);
+        }
+      } catch (rollbackError) {
+        throw new AggregateError(
+          [error, rollbackError],
+          "Failed to save project files and rollback did not complete",
+        );
       }
-    } catch (rollbackError) {
-      throw new AggregateError(
-        [error, rollbackError],
-        "Failed to save project files and rollback did not complete",
-      );
+      throw error;
     }
-    throw error;
-  }
-  return changedPaths;
+    return changedPaths;
+  });
 }

package/src/utils/studioFileMutationCoordinator.ts

@@ -0,0 +1,45 @@
+export type StudioProjectFileWriter = (path: string, content: string) => Promise<void>;
+
+// A writer is bound to one project (see useFileManager), so writer identity plus
+// path is the complete durable-file identity. Sharing this queue across SDK and
+// legacy mutation paths prevents independent read-modify-write transactions from
+// cloning the same stale bytes and overwriting one another.
+const mutationQueues = new WeakMap<StudioProjectFileWriter, Map<string, Promise<unknown>>>();
+
+export function serializeStudioFileMutation<T>(
+  writer: StudioProjectFileWriter,
+  targetPath: string,
+  task: () => Promise<T>,
+): Promise<T> {
+  let queues = mutationQueues.get(writer);
+  if (!queues) {
+    queues = new Map();
+    mutationQueues.set(writer, queues);
+  }
+  const prior = queues.get(targetPath) ?? Promise.resolve();
+  const next = prior.then(task, task);
+  queues.set(targetPath, next);
+  void next.then(
+    () => {
+      if (queues?.get(targetPath) === next) queues.delete(targetPath);
+    },
+    () => {
+      if (queues?.get(targetPath) === next) queues.delete(targetPath);
+    },
+  );
+  return next;
+}
+
+export function serializeStudioFileMutations<T>(
+  writer: StudioProjectFileWriter,
+  targetPaths: readonly string[],
+  task: () => Promise<T>,
+): Promise<T> {
+  const paths = [...new Set(targetPaths)].sort();
+  const acquire = (index: number): Promise<T> => {
+    const path = paths[index];
+    if (path === undefined) return task();
+    return serializeStudioFileMutation(writer, path, () => acquire(index + 1));
+  };
+  return acquire(0);
+}

package/src/utils/studioFileVersion.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { studioExpectedFileVersion, studioFileContentVersion } from "./studioFileVersion";
+
+describe("studioFileContentVersion", () => {
+  it("matches the strong SHA-256 ETag format used by studio-server", async () => {
+    await expect(studioFileContentVersion("abc")).resolves.toBe(
+      '"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"',
+    );
+  });
+
+  it("keeps an explicit content precondition authoritative over cached state", async () => {
+    const versions = new Map<string, string | null>([
+      ["stale.html", await studioFileContentVersion("stale")],
+      ["newer.html", await studioFileContentVersion("newer")],
+      ["missing.html", null],
+    ]);
+    const expectedVersion = await studioFileContentVersion("expected");
+
+    expect(await studioExpectedFileVersion(versions, "stale.html", "expected")).toBe(
+      expectedVersion,
+    );
+    expect(await studioExpectedFileVersion(versions, "newer.html", "expected")).toBe(
+      expectedVersion,
+    );
+    expect(await studioExpectedFileVersion(versions, "missing.html", "expected")).toBe(
+      expectedVersion,
+    );
+  });
+
+  it("keeps known-missing and untracked files distinct without explicit content", async () => {
+    const versions = new Map<string, string | null>([["missing.html", null]]);
+
+    expect(await studioExpectedFileVersion(versions, "missing.html")).toBeNull();
+    expect(await studioExpectedFileVersion(versions, "untracked.html")).toBeUndefined();
+  });
+});