@hyperframes/studio 0.8.23 → 0.8.25

package/src/hooks/useDomEditTextCommits.test.tsx

@@ -124,6 +124,44 @@ afterEach(() => {
 });
 
 describe("useDomEditTextCommits", () => {
+  it("keeps concurrent text commit ownership isolated by target", async () => {
+    const { iframe, element: firstElement } = previewElement(
+      "<div id='first'>First</div><div id='second'>Second</div>",
+      "first",
+    );
+    const secondElement = iframe.contentDocument?.getElementById("second") as HTMLElement;
+    const firstSelection = selectionFor(firstElement);
+    const secondSelection = selectionFor(secondElement);
+    const firstPersist = createDeferred<void>();
+    const persistDomEditOperations = vi
+      .fn()
+      .mockImplementationOnce(() => firstPersist.promise)
+      .mockResolvedValueOnce(undefined);
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const hook = renderTextCommitHook(
+      commitParams({
+        previewIframeRef: { current: iframe },
+        domEditSelection: firstSelection,
+        persistDomEditOperations,
+      }),
+    );
+
+    let firstCommit: Promise<unknown> | undefined;
+    act(() => {
+      firstCommit = hook.handleDomTextCommitForSelection(firstSelection, "Pending first", "self");
+    });
+    await act(async () => {
+      await hook.handleDomTextCommitForSelection(secondSelection, "Saved second", "self");
+    });
+    firstPersist.reject(new Error("first target failed"));
+    await act(async () => {
+      await firstCommit;
+    });
+
+    expect(firstElement.textContent).toBe("First");
+    expect(secondElement.textContent).toBe("Saved second");
+  });
+
   it("does not let a stale failed fields commit revert newer text", async () => {
     const { iframe, element } = previewElement("<div id='card'>Original</div>", "card");
     vi.spyOn(console, "warn").mockImplementation(() => {});
@@ -183,8 +221,17 @@ describe("useDomEditTextCommits", () => {
   it("reports a successful style commit", async () => {
     const { iframe, element } = previewElement("<div id='card'>Original</div>", "card");
     const selection = selectionFor(element);
+    const persistence = {
+      sourceFile: "index.html",
+      version: '"sha256:after"',
+      changed: true,
+    } as const;
     const hook = renderTextCommitHook(
-      commitParams({ previewIframeRef: { current: iframe }, domEditSelection: selection }),
+      commitParams({
+        previewIframeRef: { current: iframe },
+        domEditSelection: selection,
+        persistDomEditOperations: vi.fn().mockResolvedValue(persistence),
+      }),
     );
 
     let outcome: unknown;
@@ -192,7 +239,7 @@ describe("useDomEditTextCommits", () => {
       outcome = await hook.handleDomStyleCommit("color", "red");
     });
 
-    expect(outcome).toEqual({ ok: true });
+    expect(outcome).toEqual({ ok: true, persistence });
   });
 
   it("declines a style commit with no selection, without reaching the writer", async () => {
@@ -286,4 +333,41 @@ describe("useDomEditTextCommits", () => {
     expect(outcome).toEqual({ ok: false, reason: "no-selection" });
     expect(persistDomEditOperations).not.toHaveBeenCalled();
   });
+
+  it("preserves text persistence evidence for an explicit selection", async () => {
+    const { iframe, element: ambientElement } = previewElement(
+      "<div id='ambient'>Ambient</div><div id='agent'>Agent</div>",
+      "ambient",
+    );
+    const agentElement = iframe.contentDocument?.getElementById("agent") as HTMLElement;
+    const ambientSelection = selectionFor(ambientElement);
+    const agentSelection = selectionFor(agentElement);
+    const persistence = {
+      sourceFile: "index.html",
+      version: '"sha256:text"',
+      changed: true,
+    } as const;
+    const persistDomEditOperations = vi.fn().mockResolvedValue(persistence);
+    const hook = renderTextCommitHook(
+      commitParams({
+        previewIframeRef: { current: iframe },
+        domEditSelection: ambientSelection,
+        persistDomEditOperations,
+      }),
+    );
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await hook.handleDomTextCommitForSelection(agentSelection, "Edited", "self");
+    });
+
+    expect(outcome).toEqual({ ok: true, persistence });
+    expect(persistDomEditOperations).toHaveBeenCalledWith(
+      agentSelection,
+      expect.any(Array),
+      expect.any(Object),
+    );
+    expect(ambientElement.textContent).toBe("Ambient");
+    expect(agentElement.textContent).toBe("Edited");
+  });
 });

package/src/hooks/useDomEditTextCommits.ts

@@ -13,11 +13,9 @@ import {
 import {
   buildDomEditRichTextPatchOperation,
   buildDomEditStylePatchOperation,
-  buildDomEditTextPatchOperation,
   findElementForSelection,
   getDomEditTargetKey,
   isTextEditableSelection,
-  serializeDomEditTextFields,
   buildDefaultDomEditTextField,
   type DomEditTextField,
   type DomEditSelection,
@@ -25,11 +23,10 @@ import {
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { PersistDomEditOperations } from "./domEditCommitTypes";
 import { canEditElementTextInline } from "../components/editor/domEditInlineText";
-import { buildTextFieldChildOperations } from "./domEditTextFieldCommitOps";
+import { buildNextDomTextFields, planDomTextCommit } from "./domEditTextCommitPlan";
 import { reportDomEditPersistFailure } from "./domEditPersistFailure";
 import {
   bumpDomEditCommitMapVersion,
-  bumpDomEditCommitVersion,
   domEditCommitDeclined,
   runDomEditCommit,
   runReportedDomEditCommit,
@@ -58,13 +55,6 @@ export interface UseDomEditTextCommitsParams {
   resolveImportedFontAsset: (fontFamilyValue: string) => ImportedFontAsset | null;
 }
 
-interface DomTextCommitPlan {
-  usesSerializedTextFields: boolean;
-  nextContent: string;
-  childOperations: PatchOperation[] | null;
-  operations: PatchOperation[];
-}
-
 function canCommitInlineTextSelection(selection: DomEditSelection, element: HTMLElement): boolean {
   if (selection.isCompositionHost || selection.isInsideLockedComposition) return false;
   return canEditElementTextInline(element);
@@ -97,51 +87,6 @@ function buildDomStyleCommitOperations(
   return operations;
 }
 
-function buildNextDomTextFields(
-  textFields: DomEditTextField[],
-  value: string,
-  fieldKey?: string,
-): DomEditTextField[] {
-  if (textFields.length === 0) return [];
-  return textFields.map((field) => (field.key === fieldKey ? { ...field, value } : field));
-}
-
-function planDomTextCommit(
-  originalTextFields: DomEditTextField[],
-  nextTextFields: DomEditTextField[],
-  plainTextContent: string,
-): DomTextCommitPlan {
-  const usesSerializedTextFields =
-    nextTextFields.length > 1 || nextTextFields.some((field) => field.source === "child");
-  const nextContent = usesSerializedTextFields
-    ? serializeDomEditTextFields(nextTextFields)
-    : plainTextContent;
-  const childOperations = usesSerializedTextFields
-    ? buildTextFieldChildOperations(originalTextFields, nextTextFields)
-    : null;
-  // Per-child operations when the layers still line up one-for-one, and the
-  // element's whole markup when they do not.
-  //
-  // `buildTextFieldChildOperations` can only address children that already
-  // exist, so it returns null for any change in how many there are — which is
-  // every delete and every add. That used to end here with "Couldn't save this
-  // text structure change": the panel offered a remove button and an Add text
-  // field row, and neither could ever save. A structure change has one honest
-  // operation, which is to write the structure.
-  const operations =
-    childOperations ??
-    (usesSerializedTextFields
-      ? [buildDomEditRichTextPatchOperation(nextContent)]
-      : [buildDomEditTextPatchOperation(nextContent)]);
-
-  return {
-    usesSerializedTextFields,
-    nextContent,
-    childOperations,
-    operations,
-  };
-}
-
 async function resyncDomTextSelectionFromPreview(
   doc: Document | null | undefined,
   selection: DomEditSelection,
@@ -170,8 +115,8 @@ export function useDomEditTextCommits({
   persistDomEditOperations,
   resolveImportedFontAsset,
 }: UseDomEditTextCommitsParams) {
-  const domTextCommitVersionRef = useRef(0);
-  const domStyleCommitVersionRef = useRef(new Map<string, number>());
+  const domTextCommitVersionRef = useRef(new Map<string, symbol>());
+  const domStyleCommitVersionRef = useRef(new Map<string, symbol>());
 
   const {
     handleDomAttributeCommit,
@@ -188,15 +133,18 @@ export function useDomEditTextCommits({
     persistDomEditOperations,
   });
 
-  const handleDomStyleCommit = useCallback(
-    async (property: string, value: string): Promise<DomEditCommitOutcome> => {
-      if (!domEditSelection) return domEditCommitDeclined("no-selection");
+  const handleDomStyleCommitForSelection = useCallback(
+    async (
+      selection: DomEditSelection,
+      property: string,
+      value: string,
+    ): Promise<DomEditCommitOutcome> => {
       if (isManualGeometryStyleProperty(property))
         return domEditCommitDeclined("geometry-property");
-      if (!domEditSelection.capabilities.canEditStyles) {
+      if (!selection.capabilities.canEditStyles) {
         return domEditCommitDeclined("styles-not-editable");
       }
-      const styleCommitKey = `${getDomEditTargetKey(domEditSelection)}:${property}`;
+      const styleCommitKey = `${getDomEditTargetKey(selection)}:${property}`;
       const isLatestStyleCommit = bumpDomEditCommitMapVersion(
         domStyleCommitVersionRef.current,
         styleCommitKey,
@@ -219,7 +167,7 @@ export function useDomEditTextCommits({
       return runReportedDomEditCommit({
         capture: () => {
           if (!doc) return;
-          const el = findElementForSelection(doc, domEditSelection, activeCompPath);
+          const el = findElementForSelection(doc, selection, activeCompPath);
           if (!el) return;
           editedElement = el;
           previousInlineValue = el.style.getPropertyValue(property);
@@ -238,7 +186,7 @@ export function useDomEditTextCommits({
           }
         },
         persist: () =>
-          persistDomEditOperations(domEditSelection, operations, {
+          persistDomEditOperations(selection, operations, {
             label: "Edit layer style",
             skipRefresh,
             prepareContent: importedFont
@@ -255,15 +203,14 @@ export function useDomEditTextCommits({
             editedElement.style.setProperty(property, previousInlineValue);
           }
         },
-        onError: (error) =>
-          reportDomEditPersistFailure(domEditSelection, operations, error, showToast),
+        onError: (error) => reportDomEditPersistFailure(selection, operations, error, showToast),
         shouldResync: isLatestStyleCommit,
-        resync: () => refreshDomEditSelectionFromPreview(domEditSelection),
+        resync: () => refreshDomEditSelectionFromPreview(selection),
+        onFinally: isLatestStyleCommit.release,
       });
     },
     [
       activeCompPath,
-      domEditSelection,
       persistDomEditOperations,
       refreshDomEditSelectionFromPreview,
       resolveImportedFontAsset,
@@ -272,15 +219,29 @@ export function useDomEditTextCommits({
     ],
   );
 
-  const handleDomTextCommit = useCallback(
-    async (value: string, fieldKey?: string): Promise<DomEditCommitOutcome> => {
-      if (!domEditSelection) return domEditCommitDeclined("no-selection");
-      if (!isTextEditableSelection(domEditSelection)) {
+  const handleDomStyleCommit = useCallback(
+    (property: string, value: string): Promise<DomEditCommitOutcome> =>
+      domEditSelection
+        ? handleDomStyleCommitForSelection(domEditSelection, property, value)
+        : Promise.resolve(domEditCommitDeclined("no-selection")),
+    [domEditSelection, handleDomStyleCommitForSelection],
+  );
+
+  const handleDomTextCommitForSelection = useCallback(
+    async (
+      selection: DomEditSelection,
+      value: string,
+      fieldKey?: string,
+    ): Promise<DomEditCommitOutcome> => {
+      if (!isTextEditableSelection(selection)) {
         return domEditCommitDeclined("not-text-editable");
       }
-      const isLatestTextCommit = bumpDomEditCommitVersion(domTextCommitVersionRef);
-      const nextTextFields = buildNextDomTextFields(domEditSelection.textFields, value, fieldKey);
-      const textCommit = planDomTextCommit(domEditSelection.textFields, nextTextFields, value);
+      const isLatestTextCommit = bumpDomEditCommitMapVersion(
+        domTextCommitVersionRef.current,
+        getDomEditTargetKey(selection),
+      );
+      const nextTextFields = buildNextDomTextFields(selection.textFields, value, fieldKey);
+      const textCommit = planDomTextCommit(selection.textFields, nextTextFields, value);
       const iframe = previewIframeRef.current;
       const doc = iframe?.contentDocument;
       let editedElement: HTMLElement | null = null;
@@ -289,7 +250,7 @@ export function useDomEditTextCommits({
       return runReportedDomEditCommit({
         capture: () => {
           if (!doc) return;
-          const el = findElementForSelection(doc, domEditSelection, activeCompPath);
+          const el = findElementForSelection(doc, selection, activeCompPath);
           if (!el) return;
           editedElement = el;
           previousInnerHtml = el.innerHTML;
@@ -302,42 +263,49 @@ export function useDomEditTextCommits({
             editedElement.textContent = value;
           }
         },
-        persist: async () => {
-          await persistDomEditOperations(domEditSelection, textCommit.operations, {
+        persist: () =>
+          persistDomEditOperations(selection, textCommit.operations, {
             label: "Edit text",
             skipRefresh: true,
             shouldSave: isLatestTextCommit,
-          });
-        },
+          }),
         shouldRevert: () => isLatestTextCommit(),
         revert: () => {
           if (!editedElement || previousInnerHtml === null) return;
           editedElement.innerHTML = previousInnerHtml;
         },
         onError: (error) =>
-          reportDomEditPersistFailure(domEditSelection, textCommit.operations, error, showToast),
+          reportDomEditPersistFailure(selection, textCommit.operations, error, showToast),
         shouldResync: isLatestTextCommit,
         resync: () =>
           resyncDomTextSelectionFromPreview(
             doc,
-            domEditSelection,
+            selection,
             activeCompPath,
             buildDomSelectionFromTarget,
             applyDomSelection,
           ),
+        onFinally: isLatestTextCommit.release,
       });
     },
     [
       activeCompPath,
       applyDomSelection,
       buildDomSelectionFromTarget,
-      domEditSelection,
       persistDomEditOperations,
       previewIframeRef,
       showToast,
     ],
   );
 
+  const handleDomTextCommit = useCallback(
+    (value: string, fieldKey?: string): Promise<DomEditCommitOutcome> =>
+      domEditSelection
+        ? handleDomTextCommitForSelection(domEditSelection, value, fieldKey)
+        : Promise.resolve(domEditCommitDeclined("no-selection")),
+    [domEditSelection, handleDomTextCommitForSelection],
+  );
+
   /**
    * Persist an element's own markup, for a text edit that styled part of it.
    *
@@ -366,7 +334,10 @@ export function useDomEditTextCommits({
       // A preview reload replaces the document. Never resolve this commit onto
       // the replacement node: it did not own the edit or its rollback snapshot.
       if (!ownsCurrentPreviewElement(domEditSelection, element, doc)) return;
-      const isLatestTextCommit = bumpDomEditCommitVersion(domTextCommitVersionRef);
+      const isLatestTextCommit = bumpDomEditCommitMapVersion(
+        domTextCommitVersionRef.current,
+        getDomEditTargetKey(domEditSelection),
+      );
       const operations = [buildDomEditRichTextPatchOperation(html)];
       let appliedHtml = "";
 
@@ -404,6 +375,7 @@ export function useDomEditTextCommits({
             buildDomSelectionFromTarget,
             applyDomSelection,
           ),
+        onFinally: isLatestTextCommit.release,
       });
     },
     [
@@ -423,7 +395,10 @@ export function useDomEditTextCommits({
       nextTextFields: DomEditTextField[],
       options?: { importedFont?: ImportedFontAsset | null },
     ) => {
-      const isLatestTextCommit = bumpDomEditCommitVersion(domTextCommitVersionRef);
+      const isLatestTextCommit = bumpDomEditCommitMapVersion(
+        domTextCommitVersionRef.current,
+        getDomEditTargetKey(selection),
+      );
       const textCommit = planDomTextCommit(
         selection.textFields,
         nextTextFields,
@@ -476,6 +451,7 @@ export function useDomEditTextCommits({
             buildDomSelectionFromTarget,
             applyDomSelection,
           ),
+        onFinally: isLatestTextCommit.release,
       });
     },
     [
@@ -579,12 +555,14 @@ export function useDomEditTextCommits({
 
   return {
     handleDomStyleCommit,
+    handleDomStyleCommitForSelection,
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomAttributeQuietCommit,
     handleDomHtmlAttributeCommit,
     handleDomAttributesCommit,
     handleDomTextCommit,
+    handleDomTextCommitForSelection,
     handleDomRichTextCommit,
     commitDomTextFields,
     handleDomTextFieldStyleCommit,

package/src/hooks/useDomEditWiring.ts

@@ -223,7 +223,7 @@ export function useDomEditWiring({
   // ── Telemetry & fallback ──
 
   const trackGsapInteractionFailure = useGsapInteractionFailureTelemetry(activeCompPath, showToast);
-  const makeFetchFallback = useGsapAnimationFetchFallback(projectId, gsapSourceFile);
+  const makeFetchFallback = useGsapAnimationFetchFallback(projectId);
 
   // ── GSAP selection handlers ──
 

package/src/hooks/useDomSelection.ts

@@ -210,6 +210,7 @@ export function useDomSelection({
       options?: {
         preferClipAncestor?: boolean;
         skipSourceProbe?: boolean;
+        exactTarget?: boolean;
         // Override the drill-in scope (used by canvas double-click to resolve the
         // child inside a group before the activeGroupElement state has re-rendered).
         activeGroupElement?: HTMLElement | null;
@@ -220,6 +221,7 @@ export function useDomSelection({
         isMasterView,
         preferClipAncestor: options?.preferClipAncestor,
         skipSourceProbe: options?.skipSourceProbe,
+        exactTarget: options?.exactTarget,
         activeGroupElement:
           options && "activeGroupElement" in options
             ? options.activeGroupElement

package/src/hooks/useDomSelectionTypes.ts

@@ -16,6 +16,8 @@ export interface ResolveDomSelectionOptions {
   preferClipAncestor?: boolean;
   skipSourceProbe?: boolean;
   activeGroupElement?: HTMLElement | null;
+  /** Resolve this node itself instead of applying human group-capture behavior. */
+  exactTarget?: boolean;
 }
 
 export interface UseDomSelectionParams {

package/src/hooks/useExternalFileChangeCoordinator.test.tsx

@@ -4,6 +4,7 @@ import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
 import { markStudioWriteToken, resetStudioWriteTokens } from "../utils/studioFileVersion";
+import { markSelfWrite, resetSelfWriteRegistry } from "./sdkSelfWriteRegistry";
 import {
   useExternalFileChangeCoordinator,
   type ExternalFileChangeCoordinatorHandle,
@@ -29,6 +30,7 @@ async function mountCoordinator(overrides: Partial<CoordinatorOptions> = {}) {
     discardPendingChanges: vi.fn(),
     overwriteConflict: vi.fn(async () => undefined),
     readProjectFile: vi.fn(async () => "external"),
+    onAcceptedPersistedFileChange: vi.fn(),
   };
   const options = { ...defaults, ...overrides };
   const root = createRoot(document.createElement("div"));
@@ -45,6 +47,7 @@ describe("external file change coordinator", () => {
   beforeEach(() => {
     handler = null;
     resetStudioWriteTokens();
+    resetSelfWriteRegistry();
     vi.stubGlobal("__HF_STUDIO_HOT_TEST_ADAPTER__", {
       on: (_event: string, next: HotHandler) => {
         handler = next;
@@ -67,23 +70,61 @@ describe("external file change coordinator", () => {
         order.push("drain");
         return { status: "clean" };
       },
+      onAcceptedPersistedFileChange: () => order.push("thumbnail"),
       reloadPreview: () => order.push("preview"),
       reloadSdkSession: () => order.push("sdk"),
     });
     await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
-    expect(order).toEqual(["drain", "preview", "sdk"]);
+    expect(order).toEqual(["drain", "thumbnail", "preview", "sdk"]);
     expect(captured.handle?.blocked).toBeNull();
   });
 
-  it("suppresses an exact Studio write receipt", async () => {
+  it("refreshes thumbnails once but suppresses Preview reload for an exact Studio write", async () => {
     const drainPendingChanges = vi.fn(async () => ({ status: "clean" as const }));
     const reloadPreview = vi.fn();
     const reloadSdkSession = vi.fn();
-    await mountCoordinator({ drainPendingChanges, reloadPreview, reloadSdkSession });
+    const onAcceptedPersistedFileChange = vi.fn();
+    await mountCoordinator({
+      drainPendingChanges,
+      reloadPreview,
+      reloadSdkSession,
+      onAcceptedPersistedFileChange,
+    });
     markStudioWriteToken("studio-write-1");
+    const payload = {
+      path: "index.html",
+      content: "studio",
+      version: "v2",
+      writeToken: "studio-write-1",
+    };
+    await act(async () => handler?.(payload));
+    await act(async () => handler?.(payload));
+    expect(drainPendingChanges).not.toHaveBeenCalled();
+    expect(reloadPreview).not.toHaveBeenCalled();
+    expect(reloadSdkSession).not.toHaveBeenCalled();
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html");
+  });
+
+  it("accepts a matching content echo without a write token and suppresses every reload", async () => {
+    const drainPendingChanges = vi.fn(async () => ({ status: "clean" as const }));
+    const reloadPreview = vi.fn();
+    const reloadSdkSession = vi.fn();
+    const onAcceptedPersistedFileChange = vi.fn();
+    await mountCoordinator({
+      drainPendingChanges,
+      reloadPreview,
+      reloadSdkSession,
+      onAcceptedPersistedFileChange,
+    });
+    markSelfWrite("index.html", "studio content");
+
     await act(async () =>
-      handler?.({ path: "index.html", content: "studio", writeToken: "studio-write-1" }),
+      handler?.({ path: "index.html", content: "studio content", version: "v2" }),
     );
+
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledWith("index.html");
     expect(drainPendingChanges).not.toHaveBeenCalled();
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(reloadSdkSession).not.toHaveBeenCalled();
@@ -115,15 +156,23 @@ describe("external file change coordinator", () => {
       attemptedContent: "studio",
     });
     const persistConflictSnapshot = vi.fn(async () => undefined);
+    const onAcceptedPersistedFileChange = vi.fn();
     const { captured, options } = await mountCoordinator({
       drainPendingChanges: async () => ({ status: "conflict", error: conflict }),
       persistConflictSnapshot,
+      onAcceptedPersistedFileChange,
     });
     await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
     expect(persistConflictSnapshot).toHaveBeenCalledWith("project-a", conflict);
     expect(captured.handle?.blocked).toMatchObject({ status: "conflict", error: conflict });
     expect(options.reloadPreview).not.toHaveBeenCalled();
     expect(options.reloadSdkSession).not.toHaveBeenCalled();
+    expect(onAcceptedPersistedFileChange).not.toHaveBeenCalled();
+
+    await act(async () => captured.handle?.useExternalFile());
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
+    expect(options.reloadPreview).toHaveBeenCalledOnce();
+    expect(options.reloadSdkSession).toHaveBeenCalledOnce();
   });
 
   it("ignores stale drain completion after a newer generation", async () => {
@@ -165,6 +214,7 @@ describe("external file change coordinator", () => {
     const failure = new Error("network unavailable");
     const persistFailureSnapshot = vi.fn(async () => undefined);
     const deleteConflictSnapshot = vi.fn(async () => undefined);
+    const onAcceptedPersistedFileChange = vi.fn();
     const { captured } = await mountCoordinator({
       drainPendingChanges: vi
         .fn()
@@ -173,6 +223,7 @@ describe("external file change coordinator", () => {
       getPendingCandidate: () => ({ path: "index.html", content: "final local candidate" }),
       persistFailureSnapshot,
       deleteConflictSnapshot,
+      onAcceptedPersistedFileChange,
     });
     await act(async () => handler?.({ path: "index.html" }));
     expect(captured.handle?.blocked).toMatchObject({
@@ -188,15 +239,19 @@ describe("external file change coordinator", () => {
       null,
       failure,
     );
+    expect(onAcceptedPersistedFileChange).not.toHaveBeenCalled();
     await act(async () => captured.handle?.retry());
     expect(deleteConflictSnapshot).toHaveBeenCalledWith("project-a", "index.html");
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
   });
 
   it("restores and overwrites from a durable failed draft", async () => {
     const overwriteConflict = vi.fn(async () => undefined);
+    const onAcceptedPersistedFileChange = vi.fn();
     const { captured } = await mountCoordinator({
       recoveryFilePath: "index.html",
       overwriteConflict,
+      onAcceptedPersistedFileChange,
       loadConflictSnapshot: vi.fn(async () => ({
         kind: "failed" as const,
         projectId: "project-a",
@@ -217,5 +272,17 @@ describe("external file change coordinator", () => {
     expect(overwriteConflict).toHaveBeenCalledWith(
       expect.objectContaining({ attemptedContent: "recover me", currentVersion: "v2" }),
     );
+    expect(onAcceptedPersistedFileChange).not.toHaveBeenCalled();
+
+    markStudioWriteToken("keep-studio-write");
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "recover me",
+        version: "v3",
+        writeToken: "keep-studio-write",
+      }),
+    );
+    expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
   });
 });