fix(studio): harden targeted agent writes

Author: miguel-heygen

docs/guides/webmcp.mdx

@@ -98,8 +98,9 @@ CSS selectors.
 | `studio_add_keyframe` | Adds a keyframe to an animation |
 | `studio_delete_animation` | Removes an animation |
 
-Element writes run through the same commit actors Studio uses. A successful durable write names the
-source file and content version that accepted it, and it enters the same undo history.
+Element writes run through the same commit actors Studio uses. When that actor forwards versioned
+durability evidence, the receipt names the source file and content version, and the edit enters the
+same undo history. Actors without that evidence stay at `dispatched`.
 
 ## Two rules worth knowing
 

packages/studio-server/src/routes/thumbnail.test.ts

@@ -388,10 +388,30 @@ describe("registerThumbnailRoutes", () => {
     expect(await (await app.request(url)).text()).toBe("shared");
 
     expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
-    expect(getProjectSignature).toHaveBeenCalledTimes(3);
+    expect(getProjectSignature).toHaveBeenCalledTimes(4);
     expect(getProjectSignature).toHaveBeenNthCalledWith(1, project.dir);
   });
 
+  it("does not cache generated pixels under a signature that changed in flight", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const signatures = ["old", "new", "old", "old"];
+    adapter.getProjectSignature = vi.fn(() => signatures.shift() ?? "old");
+    adapter.generateThumbnail = vi
+      .fn()
+      .mockResolvedValueOnce(Buffer.from("rendered-after-change"))
+      .mockResolvedValueOnce(Buffer.from("rendered-old"));
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+    const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
+
+    expect(await (await app.request(url)).text()).toBe("rendered-after-change");
+    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
+    expect(await (await app.request(url)).text()).toBe("rendered-old");
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
+  });
+
   it("keeps changed studio motion separated in the disk cache", async () => {
     const adapter = createAdapter();
     const project = await adapter.resolveProject("demo");

packages/studio-server/src/routes/thumbnail.ts

@@ -212,6 +212,17 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
             signal,
           });
           if (!generated) return null;
+          const afterGeneration = await resolveProjectAndSignature(adapter, project.id);
+          if (
+            !afterGeneration ||
+            afterGeneration.project.dir !== project.dir ||
+            afterGeneration.signature !== projectSignature
+          ) {
+            // The browser may have rendered content written after this request
+            // captured its cache identity. Return the pixels to this caller,
+            // but never file them under a signature they do not prove.
+            return generated;
+          }
           if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
           writeThumbnailAtomically(cachePath, generated);
           return generated;

packages/studio/src/components/editor/domEditingLayers.test.ts

@@ -126,6 +126,15 @@ describe("resolveDomEditSelection — data-hf-group capture", () => {
     expect(selection?.selector).toBe('[data-hf-group="Group 1"]');
   });
 
+  it("resolves an explicit agent target without promoting it to the group", async () => {
+    const { parent, child } = buildNestedGroups();
+    const selection = await resolveDomEditSelection(child, { ...opts, exactTarget: true });
+    document.body.removeChild(parent);
+
+    expect(selection?.element).toBe(child);
+    expect(selection?.id).toBe("child");
+  });
+
   it("selects the next nested group when drilled into the outer group", async () => {
     const { parent, outer, inner, child } = buildNestedGroups();
     const selection = await resolveDomEditSelection(child, { ...opts, activeGroupElement: outer });

packages/studio/src/components/editor/domEditingLayers.ts

@@ -281,10 +281,6 @@ export function resolveDomEditCapabilities(args: {
   ).capabilities;
 }
 
-// ─── Element label ────────────────────────────────────────────────────────────
-
-// ─── Source probe ────────────────────────────────────────────────────────────
-
 async function probeSourceElement(
   projectId: string,
   sourceFile: string,
@@ -310,17 +306,21 @@ async function probeSourceElement(
   }
 }
 
-// ─── Selection resolution ────────────────────────────────────────────────────
-
 // fallow-ignore-next-line complexity
 export async function resolveDomEditSelection(
   startEl: HTMLElement | null,
-  options: DomEditContextOptions & { projectId?: string | null; skipSourceProbe?: boolean },
+  options: DomEditContextOptions & {
+    projectId?: string | null;
+    skipSourceProbe?: boolean;
+    exactTarget?: boolean;
+  },
 ): Promise<DomEditSelection | null> {
   if (!startEl) return null;
   const doc = startEl.ownerDocument;
 
-  let capture = resolveGroupCapture(startEl, options.activeGroupElement ?? null);
+  let capture = options.exactTarget
+    ? ({ kind: "unit", element: startEl } as const)
+    : resolveGroupCapture(startEl, options.activeGroupElement ?? null);
   if (capture.kind === "out-of-scope") {
     // Drill-in is non-sticky: clicking/hovering OUTSIDE the drilled-into group
     // exits it and resolves the target normally, rather than selecting nothing

packages/studio/src/contexts/DomEditContext.tsx

@@ -32,6 +32,7 @@ export interface DomEditActionsValue extends Pick<
   | "handleDomTextFieldStyleCommit"
   | "handleDomAddTextField"
   | "handleDomRemoveTextField"
+  | "getGsapAnimationsForSelection"
   | "handleAskAgent"
   | "handleAgentModalSubmit"
   | "handleBlockedDomMove"
@@ -174,6 +175,7 @@ export function DomEditProvider({
     handleDomTextFieldStyleCommit,
     handleDomAddTextField,
     handleDomRemoveTextField,
+    getGsapAnimationsForSelection,
     handleAskAgent,
     handleAgentModalSubmit,
     handleBlockedDomMove,
@@ -265,6 +267,7 @@ export function DomEditProvider({
       handleDomTextFieldStyleCommit,
       handleDomAddTextField,
       handleDomRemoveTextField,
+      getGsapAnimationsForSelection,
       handleAskAgent,
       handleAgentModalSubmit,
       handleBlockedDomMove,
@@ -338,6 +341,7 @@ export function DomEditProvider({
       handleDomTextFieldStyleCommit,
       handleDomAddTextField,
       handleDomRemoveTextField,
+      getGsapAnimationsForSelection,
       handleAskAgent,
       handleAgentModalSubmit,
       handleBlockedDomMove,

packages/studio/src/hooks/useDomEditCommits.test.tsx

@@ -8,6 +8,7 @@ import type { DomEditSelection, DomEditTextField } from "../components/editor/do
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import { usePlayerStore } from "../player";
 import { StudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import type { CutoverResult } from "../utils/sdkCutover";
 import { useDomEditCommits } from "./useDomEditCommits";
@@ -39,6 +40,7 @@ interface RenderDomEditCommitsOptions {
   importedFontAssets?: ImportedFontAsset[];
   writeProjectFile?: (path: string, content: string, expectedContent?: string) => Promise<void>;
   onTrySdkPersist?: () => Promise<CutoverResult>;
+  queueDomEditSave?: <T>(save: () => Promise<T>) => Promise<T>;
 }
 
 type FetchHandler = (
@@ -214,7 +216,7 @@ function renderDomEditCommits(
       activeCompPath: "index.html",
       previewIframeRef,
       showToast,
-      queueDomEditSave: async (save) => save(),
+      queueDomEditSave: options.queueDomEditSave ?? (async (save) => save()),
       writeProjectFile: options.writeProjectFile ?? (async () => {}),
       domEditSaveTimestampRef,
       editHistory: { recordEdit },
@@ -1019,6 +1021,96 @@ describe("useDomEditCommits style persist handling", () => {
     }
   });
 
+  it("serializes the full read, write, and history transaction across overlapping commits", async () => {
+    const firstPatch = createDeferred<Response>();
+    let readCount = 0;
+    let patchCount = 0;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: Parameters<typeof fetch>[0]) => {
+        const url = requestUrl(input);
+        if (url.includes("/api/projects/p1/files/")) {
+          readCount += 1;
+          return jsonResponse({
+            content:
+              readCount === 1
+                ? '<div data-hf-id="hf-card" style="color: red">Card</div>'
+                : '<div data-hf-id="hf-card" style="color: blue">Card</div>',
+          });
+        }
+        if (url.includes("/api/projects/p1/file-mutations/patch-element/")) {
+          patchCount += 1;
+          if (patchCount === 1) return firstPatch.promise;
+          return jsonResponse({
+            ok: true,
+            changed: true,
+            matched: true,
+            content: '<div data-hf-id="hf-card" style="color: green">Card</div>',
+            path: "index.html",
+            version: '"sha256:green"',
+          });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      }),
+    );
+    const queue = createDomEditSaveQueue();
+    const { iframe, element } = createPreviewElement();
+    const rendered = renderDomEditCommits(createSelection(element), iframe, {
+      queueDomEditSave: queue.enqueue,
+    });
+
+    try {
+      const first = rendered.hook.handleDomStyleCommit("color", "blue");
+      await flushAsyncWork();
+      const second = rendered.hook.handleDomStyleCommit("color", "green");
+      await flushAsyncWork();
+
+      expect(readCount).toBe(1);
+      expect(patchCount).toBe(1);
+
+      firstPatch.resolve(
+        jsonResponse({
+          ok: true,
+          changed: true,
+          matched: true,
+          content: '<div data-hf-id="hf-card" style="color: blue">Card</div>',
+          path: "index.html",
+          version: '"sha256:blue"',
+        }),
+      );
+      await first;
+      await second;
+
+      expect(readCount).toBe(2);
+      expect(patchCount).toBe(2);
+      expect(rendered.recordEdit).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          files: {
+            "index.html": expect.objectContaining({
+              before: expect.stringContaining("color: red"),
+              after: expect.stringContaining("color: blue"),
+            }),
+          },
+        }),
+      );
+      expect(rendered.recordEdit).toHaveBeenNthCalledWith(
+        2,
+        expect.objectContaining({
+          files: {
+            "index.html": expect.objectContaining({
+              before: expect.stringContaining("color: blue"),
+              after: expect.stringContaining("color: green"),
+            }),
+          },
+        }),
+      );
+    } finally {
+      queue.destroy();
+      rendered.cleanup();
+    }
+  });
+
   it("preserves the SDK cutover version as the style commit's durable evidence", async () => {
     const fetchMock = stubPatchFetch({ ok: true, changed: true, matched: true });
     const { iframe, element } = createPreviewElement();
@@ -1520,9 +1612,7 @@ describe("useDomEditCommits attribute persist handling", () => {
       // optimistic apply) and succeeds before the older one rejects. Without the
       // per-key version guard, the stale rejection would revert to the older
       // commit's own previousValue (null) and stomp the newer commit's value.
-      const firstCommit = act(async () => {
-        await rendered.hook.handleDomHtmlAttributeCommit("muted", "first-value");
-      });
+      const firstCommit = rendered.hook.handleDomHtmlAttributeCommit("muted", "first-value");
       await act(async () => {
         await rendered.hook.handleDomHtmlAttributeCommit("muted", "second-value");
       });

packages/studio/src/hooks/useDomEditCommits.ts

@@ -139,7 +139,7 @@ export function useDomEditCommits({
   const reportedUnresolvableRef = useRef(new Set<string>());
 
   // fallow-ignore-next-line complexity
-  const persistDomEditOperations: PersistDomEditOperations = useCallback(
+  const performPersistDomEditOperations: PersistDomEditOperations = useCallback(
     // fallow-ignore-next-line complexity
     async (selection, operations, options) => {
       const pid = projectIdRef.current;
@@ -297,6 +297,12 @@ export function useDomEditCommits({
     ],
   );
 
+  const persistDomEditOperations: PersistDomEditOperations = useCallback(
+    (selection, operations, options) =>
+      queueDomEditSave(() => performPersistDomEditOperations(selection, operations, options)),
+    [performPersistDomEditOperations, queueDomEditSave],
+  );
+
   const commitDomEditPatchBatches: CommitDomEditPatchBatches = useCallback(
     (batches, options) =>
       queueDomEditSave(
@@ -413,7 +419,6 @@ export function useDomEditCommits({
   const commitPositionPatchToHtml = useDomEditPositionPatchCommit({
     activeCompPath,
     persistDomEditOperations,
-    queueDomEditSave,
     showToast,
   });
 

packages/studio/src/hooks/useDomEditPositionPatchCommit.test.tsx

@@ -55,14 +55,13 @@ function renderCommit(params: Parameters<typeof useDomEditPositionPatchCommit>[0
   return captured.commit;
 }
 
-function paramsWith(queueDomEditSave: (save: () => Promise<void>) => Promise<void>) {
+function paramsWith(persistDomEditOperations: () => Promise<undefined>) {
   const showToast = vi.fn();
   return {
     showToast,
     params: {
       activeCompPath: "index.html",
-      persistDomEditOperations: vi.fn().mockResolvedValue(undefined),
-      queueDomEditSave,
+      persistDomEditOperations,
       showToast,
     },
   };
@@ -104,7 +103,7 @@ describe("useDomEditPositionPatchCommit", () => {
   });
 
   it("resolves when the write lands", async () => {
-    const { showToast, params } = paramsWith((save) => save());
+    const { showToast, params } = paramsWith(() => Promise.resolve(undefined));
     const commit = renderCommit(params);
 
     await act(async () => {