@hyperframes/studio 0.8.16 → 0.8.17

package/src/hooks/useDomEditTextCommits.test.tsx

@@ -66,6 +66,42 @@ function selectionFor(element: HTMLElement): DomEditSelection {
   };
 }
 
+/** A preview element inside a real iframe, which is where Studio's chrome expects to find it. */
+function previewElement(
+  html: string,
+  id: string,
+): { iframe: HTMLIFrameElement; element: HTMLElement } {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("expected iframe document");
+  doc.body.innerHTML = html;
+  const element = doc.getElementById(id);
+  const HTMLElementCtor = doc.defaultView?.HTMLElement;
+  if (!HTMLElementCtor || !(element instanceof HTMLElementCtor)) {
+    throw new Error("expected preview element");
+  }
+  return { iframe, element };
+}
+
+/** Hook params with nothing selected and a writer that succeeds; override what the test is about. */
+function commitParams(
+  overrides: Partial<UseDomEditTextCommitsParams> = {},
+): UseDomEditTextCommitsParams {
+  return {
+    activeCompPath: "index.html",
+    previewIframeRef: { current: null },
+    showToast: vi.fn(),
+    domEditSelection: null,
+    applyDomSelection: vi.fn(),
+    refreshDomEditSelectionFromPreview: vi.fn(),
+    buildDomSelectionFromTarget: vi.fn(async () => null),
+    persistDomEditOperations: vi.fn().mockResolvedValue(undefined),
+    resolveImportedFontAsset: () => null,
+    ...overrides,
+  };
+}
+
 let cleanup: (() => void) | null = null;
 
 function renderTextCommitHook(params: UseDomEditTextCommitsParams) {
@@ -89,16 +125,7 @@ afterEach(() => {
 
 describe("useDomEditTextCommits", () => {
   it("does not let a stale failed fields commit revert newer text", async () => {
-    const iframe = document.createElement("iframe");
-    document.body.append(iframe);
-    const doc = iframe.contentDocument;
-    if (!doc) throw new Error("expected iframe document");
-    doc.body.innerHTML = '<div id="card">Original</div>';
-    const element = doc.getElementById("card");
-    const HTMLElementCtor = doc.defaultView?.HTMLElement;
-    if (!HTMLElementCtor || !(element instanceof HTMLElementCtor)) {
-      throw new Error("expected preview element");
-    }
+    const { iframe, element } = previewElement("<div id='card'>Original</div>", "card");
     vi.spyOn(console, "warn").mockImplementation(() => {});
     const selection = selectionFor(element);
     const stalePersist = createDeferred<void>();
@@ -106,17 +133,13 @@ describe("useDomEditTextCommits", () => {
       .fn()
       .mockImplementationOnce(() => stalePersist.promise)
       .mockResolvedValueOnce(undefined);
-    const hook = renderTextCommitHook({
-      activeCompPath: "index.html",
-      previewIframeRef: { current: iframe },
-      showToast: vi.fn(),
-      domEditSelection: selection,
-      applyDomSelection: vi.fn(),
-      refreshDomEditSelectionFromPreview: vi.fn(),
-      buildDomSelectionFromTarget: vi.fn(async () => null),
-      persistDomEditOperations,
-      resolveImportedFontAsset: () => null,
-    });
+    const hook = renderTextCommitHook(
+      commitParams({
+        previewIframeRef: { current: iframe },
+        domEditSelection: selection,
+        persistDomEditOperations,
+      }),
+    );
 
     let staleCommit: Promise<void> | undefined;
     act(() => {
@@ -132,4 +155,135 @@ describe("useDomEditTextCommits", () => {
 
     expect(element.innerHTML).toBe("Newest");
   });
+
+  it("reports persist failure from a style commit instead of resolving silently", async () => {
+    const { iframe, element } = previewElement("<div id='card'>Original</div>", "card");
+    const selection = selectionFor(element);
+    const showToast = vi.fn();
+    const hook = renderTextCommitHook(
+      commitParams({
+        previewIframeRef: { current: iframe },
+        showToast,
+        domEditSelection: selection,
+        persistDomEditOperations: vi.fn().mockRejectedValue(new Error("server said no")),
+      }),
+    );
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await hook.handleDomStyleCommit("color", "red");
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "persist-failed" });
+    // The human-facing behaviour must be unchanged: still toasts, still reverts.
+    expect(showToast).toHaveBeenCalled();
+    expect(element.style.getPropertyValue("color")).toBe("");
+  });
+
+  it("reports a successful style commit", async () => {
+    const { iframe, element } = previewElement("<div id='card'>Original</div>", "card");
+    const selection = selectionFor(element);
+    const hook = renderTextCommitHook(
+      commitParams({ previewIframeRef: { current: iframe }, domEditSelection: selection }),
+    );
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await hook.handleDomStyleCommit("color", "red");
+    });
+
+    expect(outcome).toEqual({ ok: true });
+  });
+
+  it("declines a style commit with no selection, without reaching the writer", async () => {
+    const persistDomEditOperations = vi.fn().mockResolvedValue(undefined);
+    const hook = renderTextCommitHook(
+      commitParams({
+        domEditSelection: null,
+        persistDomEditOperations,
+      }),
+    );
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await hook.handleDomStyleCommit("color", "red");
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "no-selection" });
+    expect(persistDomEditOperations).not.toHaveBeenCalled();
+  });
+
+  it("declines a style commit for a manual-geometry property", async () => {
+    const persistDomEditOperations = vi.fn().mockResolvedValue(undefined);
+    const { element } = previewElement("<div id='card'>Original</div>", "card");
+    const hook = renderTextCommitHook(
+      commitParams({
+        domEditSelection: selectionFor(element),
+        persistDomEditOperations,
+      }),
+    );
+
+    let outcome: unknown;
+    await act(async () => {
+      // `left` is a manual-geometry property the style path deliberately refuses.
+      outcome = await hook.handleDomStyleCommit("left", "10px");
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "geometry-property" });
+    expect(persistDomEditOperations).not.toHaveBeenCalled();
+  });
+
+  it("declines a style commit when the selection cannot edit styles", async () => {
+    const persistDomEditOperations = vi.fn().mockResolvedValue(undefined);
+    const { element } = previewElement("<div id='card'>Original</div>", "card");
+    const locked = selectionFor(element);
+    locked.capabilities = { ...locked.capabilities, canEditStyles: false };
+    const hook = renderTextCommitHook(
+      commitParams({
+        domEditSelection: locked,
+        persistDomEditOperations,
+      }),
+    );
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await hook.handleDomStyleCommit("color", "red");
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "styles-not-editable" });
+    expect(persistDomEditOperations).not.toHaveBeenCalled();
+  });
+
+  it("reports persist failure from a text commit instead of resolving silently", async () => {
+    const { iframe, element } = previewElement("<div id='card'>Original</div>", "card");
+    const selection = selectionFor(element);
+    const hook = renderTextCommitHook(
+      commitParams({
+        previewIframeRef: { current: iframe },
+        domEditSelection: selection,
+        persistDomEditOperations: vi.fn().mockRejectedValue(new Error("server said no")),
+      }),
+    );
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await hook.handleDomTextCommit("Updated");
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "persist-failed" });
+    expect(element.innerHTML).toBe("Original");
+  });
+
+  it("reports a text commit declined for an unselected target", async () => {
+    const persistDomEditOperations = vi.fn().mockResolvedValue(undefined);
+    const hook = renderTextCommitHook(commitParams({ persistDomEditOperations }));
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await hook.handleDomTextCommit("Updated");
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: "no-selection" });
+    expect(persistDomEditOperations).not.toHaveBeenCalled();
+  });
 });

package/src/hooks/useDomEditTextCommits.ts

@@ -30,7 +30,10 @@ import { reportDomEditPersistFailure } from "./domEditPersistFailure";
 import {
   bumpDomEditCommitMapVersion,
   bumpDomEditCommitVersion,
+  domEditCommitDeclined,
   runDomEditCommit,
+  runReportedDomEditCommit,
+  type DomEditCommitOutcome,
 } from "./domEditCommitRunner";
 import { useDomEditAttributeCommits } from "./useDomEditAttributeCommits";
 import type { InlineTextEditCommit } from "./useInlineTextEdit";
@@ -186,10 +189,13 @@ export function useDomEditTextCommits({
   });
 
   const handleDomStyleCommit = useCallback(
-    async (property: string, value: string) => {
-      if (!domEditSelection) return;
-      if (isManualGeometryStyleProperty(property)) return;
-      if (!domEditSelection.capabilities.canEditStyles) return;
+    async (property: string, value: string): Promise<DomEditCommitOutcome> => {
+      if (!domEditSelection) return domEditCommitDeclined("no-selection");
+      if (isManualGeometryStyleProperty(property))
+        return domEditCommitDeclined("geometry-property");
+      if (!domEditSelection.capabilities.canEditStyles) {
+        return domEditCommitDeclined("styles-not-editable");
+      }
       const styleCommitKey = `${getDomEditTargetKey(domEditSelection)}:${property}`;
       const isLatestStyleCommit = bumpDomEditCommitMapVersion(
         domStyleCommitVersionRef.current,
@@ -210,7 +216,7 @@ export function useDomEditTextCommits({
       // element in-browser immediately, so a reload would only cost a black blink.
       const skipRefresh = true;
 
-      await runDomEditCommit({
+      return runReportedDomEditCommit({
         capture: () => {
           if (!doc) return;
           const el = findElementForSelection(doc, domEditSelection, activeCompPath);
@@ -267,9 +273,11 @@ export function useDomEditTextCommits({
   );
 
   const handleDomTextCommit = useCallback(
-    async (value: string, fieldKey?: string) => {
-      if (!domEditSelection) return;
-      if (!isTextEditableSelection(domEditSelection)) return;
+    async (value: string, fieldKey?: string): Promise<DomEditCommitOutcome> => {
+      if (!domEditSelection) return domEditCommitDeclined("no-selection");
+      if (!isTextEditableSelection(domEditSelection)) {
+        return domEditCommitDeclined("not-text-editable");
+      }
       const isLatestTextCommit = bumpDomEditCommitVersion(domTextCommitVersionRef);
       const nextTextFields = buildNextDomTextFields(domEditSelection.textFields, value, fieldKey);
       const textCommit = planDomTextCommit(domEditSelection.textFields, nextTextFields, value);
@@ -278,7 +286,7 @@ export function useDomEditTextCommits({
       let editedElement: HTMLElement | null = null;
       let previousInnerHtml: string | null = null;
 
-      await runDomEditCommit({
+      return runReportedDomEditCommit({
         capture: () => {
           if (!doc) return;
           const el = findElementForSelection(doc, domEditSelection, activeCompPath);

package/src/hooks/useDomEditWiring.ts

@@ -107,7 +107,7 @@ export interface UseDomEditWiringParams {
     resolvedFromValues?: Record<string, number | string>,
   ) => Promise<void>;
   removeAllKeyframes: (sel: DomEditSelection, animId: string) => Promise<void>;
-  handleDomManualEditsReset: (sel: DomEditSelection) => void;
+  handleDomManualEditsReset: (sel: DomEditSelection) => Promise<void>;
 }
 
 // fallow-ignore-next-line complexity

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -52,6 +52,7 @@ describe("useDomGeometryCommits rollback", () => {
       commits!.handleDomBoxSizeCommit(selection, { width: 200, height: 160 }, { x: 30, y: 40 }),
     ).rejects.toBe(failure);
     await expect(commits!.handleDomRotationCommit(selection, { angle: 45 })).rejects.toBe(failure);
+    await expect(commits!.handleDomManualEditsReset(selection)).rejects.toBe(failure);
 
     expect(readStudioPathOffset(element)).toEqual({ x: 10, y: 20 });
     expect(readStudioBoxSize(element)).toEqual({ width: 100, height: 80 });

package/src/hooks/useDomGeometryCommits.ts

@@ -130,6 +130,9 @@ export function useDomGeometryCommits({
   const handleDomManualEditsReset = useCallback(
     (selection: DomEditSelection) => {
       const element = selection.element;
+      const beforeOffset = captureStudioPathOffset(element);
+      const beforeSize = captureStudioBoxSize(element);
+      const beforeRotation = captureStudioRotation(element);
       const clearPatches = [
         ...buildClearPathOffsetPatches(element),
         ...buildClearBoxSizePatches(element),
@@ -139,11 +142,16 @@ export function useDomGeometryCommits({
       clearStudioBoxSize(element);
       clearStudioRotation(element);
       // skipRefresh:false triggers reloadPreview() which re-syncs selection on load
-      void commitPositionPatchToHtml(selection, clearPatches, {
+      return commitPositionPatchToHtml(selection, clearPatches, {
         label: "Reset layer edits",
         coalesceKey: `manual-reset:${getDomEditTargetKey(selection)}`,
         skipRefresh: false,
-      }).catch(() => undefined);
+      }).catch((error) => {
+        restoreStudioPathOffset(element, beforeOffset);
+        restoreStudioBoxSize(element, beforeSize);
+        restoreStudioRotation(element, beforeRotation);
+        throw error;
+      });
     },
     [commitPositionPatchToHtml],
   );

package/src/hooks/useElementLifecycleOps.multiDelete.test.tsx

@@ -6,6 +6,8 @@ import { useElementLifecycleOps } from "./useElementLifecycleOps";
 import { makeLifecycleOpsParams } from "./elementLifecycleOpsTestUtils";
 import { mountReactHarness, makeSelection } from "./domSelectionTestHarness";
 
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
 function selectionFor(id: string) {
   const el = document.createElement("div");
   el.id = id;
@@ -13,28 +15,51 @@ function selectionFor(id: string) {
   return { ...makeSelection(id, el), sourceFile: "index.html" };
 }
 
+function mountDeleteOps(overrides: Partial<Parameters<typeof useElementLifecycleOps>[0]> = {}) {
+  const captured: { ops: ReturnType<typeof useElementLifecycleOps> | null } = { ops: null };
+  function Probe() {
+    captured.ops = useElementLifecycleOps(
+      makeLifecycleOpsParams({
+        commitDomEditPatchBatches: vi.fn(async () => ({ ok: true }) as never),
+        ...overrides,
+      }),
+    );
+    return null;
+  }
+  mountReactHarness(<Probe />);
+  if (!captured.ops) throw new Error("hook did not initialize");
+  return captured.ops;
+}
+
 describe("useElementLifecycleOps — deleting a canvas multi-selection", () => {
   const removed: string[] = [];
   const requests: string[] = [];
   let changes = true;
+  let removeOk = true;
 
   beforeEach(() => {
     removed.length = 0;
     requests.length = 0;
     changes = true;
+    removeOk = true;
     vi.stubGlobal(
       "fetch",
       vi.fn(async (url: string, init?: RequestInit) => {
-        requests.push(String(url));
+        const requestUrl = String(url);
+        requests.push(requestUrl);
         const body = JSON.parse(String(init?.body ?? "{}")) as {
           targets?: { id?: string; selector?: string }[];
         };
-        for (const target of body.targets ?? []) {
-          const key = target.id ?? target.selector;
-          if (key) removed.push(key);
-        }
+        const keys = (body.targets ?? [])
+          .map((target) => target.id ?? target.selector)
+          .filter((key): key is string => key !== undefined);
+        removed.push(...keys);
+        const isRemove = requestUrl.includes("/file-mutations/remove-elements/");
+        const status = isRemove && !removeOk ? 500 : 200;
         return {
-          ok: true,
+          ok: status === 200,
+          status,
+          text: async () => (status === 200 ? "" : "server said no"),
           json: async () => ({ changed: changes, content: "<html></html>" }),
         } as unknown as Response;
       }),
@@ -48,21 +73,12 @@ describe("useElementLifecycleOps — deleting a canvas multi-selection", () => {
   it("removes every selected element, not just the first", async () => {
     // The reported bug: select several elements on the canvas, press Delete, and
     // one disappears while the rest stay — still drawn as selected.
-    let ops: ReturnType<typeof useElementLifecycleOps> | null = null;
-    function Probe() {
-      ops = useElementLifecycleOps(
-        makeLifecycleOpsParams({
-          commitDomEditPatchBatches: vi.fn(async () => ({ ok: true }) as never),
-          projectIdRef: { current: "p1" },
-        }),
-      );
-      return null;
-    }
-    mountReactHarness(<Probe />);
+    const ops = mountDeleteOps({ projectIdRef: { current: "p1" } });
 
     const selections = ["a", "b", "c"].map(selectionFor);
+    let outcome: unknown;
     await act(async () => {
-      await ops!.handleDomEditElementsDelete(selections);
+      outcome = await ops.handleDomEditElementsDelete(selections);
     });
 
     // The defect: only the first was ever removed.
@@ -70,6 +86,49 @@ describe("useElementLifecycleOps — deleting a canvas multi-selection", () => {
     // And one request for the selection, not one per member: a canvas selection
     // runs to hundreds, and a round trip each made Delete look like a no-op.
     expect(requests.filter((url) => url.includes("remove-elements"))).toHaveLength(1);
+    expect(outcome).toEqual({ ok: true });
+  });
+
+  it("reports a successful SDK delete as landed", async () => {
+    const ops = mountDeleteOps({
+      projectIdRef: { current: "p1" },
+      onTrySdkDelete: vi.fn(async () => ({ status: "committed", version: "v1" }) as const),
+    });
+
+    const target = { ...selectionFor("a"), hfId: "hf-a" };
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await ops.handleDomEditElementsDelete([target]);
+    });
+
+    expect(outcome).toEqual({ ok: true });
+    expect(requests.some((url) => url.includes("remove-elements"))).toBe(false);
+  });
+
+  it("reports missing project and selection without starting a request", async () => {
+    const projectIdRef = { current: null as string | null };
+    const ops = mountDeleteOps({ projectIdRef });
+
+    await expect(ops.handleDomEditElementsDelete([selectionFor("a")])).resolves.toEqual({
+      ok: false,
+      reason: "no-project",
+    });
+    projectIdRef.current = "p1";
+    await expect(ops.handleDomEditElementsDelete([])).resolves.toEqual({
+      ok: false,
+      reason: "no-selection",
+    });
+    expect(requests).toEqual([]);
+  });
+
+  it("reports an HTTP write failure instead of only toasting", async () => {
+    removeOk = false;
+    const ops = mountDeleteOps({ projectIdRef: { current: "p1" } });
+
+    await expect(ops.handleDomEditElementsDelete([selectionFor("a")])).resolves.toEqual({
+      ok: false,
+      reason: "persist-failed",
+    });
   });
 
   it("says so when the preview is stale instead of claiming a delete", async () => {
@@ -78,23 +137,14 @@ describe("useElementLifecycleOps — deleting a canvas multi-selection", () => {
     // nothing at all, with nothing on screen to explain it.
     changes = false;
     const showToast = vi.fn();
-    let ops: ReturnType<typeof useElementLifecycleOps> | null = null;
-    function Probe() {
-      ops = useElementLifecycleOps(
-        makeLifecycleOpsParams({
-          commitDomEditPatchBatches: vi.fn(async () => ({ ok: true }) as never),
-          projectIdRef: { current: "p1" },
-          showToast,
-        }),
-      );
-      return null;
-    }
-    mountReactHarness(<Probe />);
+    const ops = mountDeleteOps({ projectIdRef: { current: "p1" }, showToast });
 
+    let outcome: unknown;
     await act(async () => {
-      await ops!.handleDomEditElementsDelete([selectionFor("a")]);
+      outcome = await ops.handleDomEditElementsDelete([selectionFor("a")]);
     });
 
     expect(showToast.mock.calls.flat().join(" ")).toContain("out of date");
+    expect(outcome).toEqual({ ok: false, reason: "preview-stale" });
   });
 });

package/src/hooks/useElementLifecycleOps.ts

@@ -20,6 +20,7 @@ import {
   type LayerRevealCommitOwnership,
 } from "../components/editor/useLayerRevealOverride";
 import type { CommitDomEditPatchBatches, DomEditPatchBatch } from "./domEditCommitTypes";
+import { domEditCommitDeclined, type DomEditCommitOutcome } from "./domEditCommitRunner";
 import { cutoverCommittedOrThrow, type CutoverResult } from "../utils/sdkCutover";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
 
@@ -87,11 +88,11 @@ export function useElementLifecycleOps({
   // fallow-ignore-next-line complexity
   const handleDomEditElementsDelete = useCallback(
     // fallow-ignore-next-line complexity
-    async (selections: DomEditSelection[]) => {
+    async (selections: DomEditSelection[]): Promise<DomEditCommitOutcome> => {
       const pid = projectIdRef.current;
-      if (!pid) return;
+      if (!pid) return domEditCommitDeclined("no-project");
       const [selection] = selections;
-      if (!selection) return;
+      if (!selection) return domEditCommitDeclined("no-selection");
       const label =
         selections.length === 1
           ? selection.label || selection.id || selection.selector || selection.tagName
@@ -141,7 +142,7 @@ export function useElementLifecycleOps({
               `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
               "info",
             );
-            return;
+            return { ok: true } as const;
           }
         }
 
@@ -174,7 +175,8 @@ export function useElementLifecycleOps({
           // matching at all means the preview is describing a document the file
           // does not have — say so rather than reporting a delete that happened.
           reloadPreview();
-          throw new Error("Nothing to delete — the preview was out of date. Try again.");
+          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;
@@ -208,9 +210,13 @@ export function useElementLifecycleOps({
           `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
           "info",
         );
+        return { ok: true } as const;
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to delete element";
         showToast(message);
+        // The toast is what tells the human. The returned outcome is what tells
+        // a caller that has no screen to read.
+        return domEditCommitDeclined("persist-failed");
       }
     },
     [

package/src/hooks/useGsapSelectionHandlers.ts

@@ -111,7 +111,7 @@ export function useGsapSelectionHandlers({
   ) => Promise<void>;
   removeAllKeyframes: (sel: DomEditSelection, animId: string) => Promise<void>;
 
-  handleDomManualEditsReset: (sel: DomEditSelection) => void;
+  handleDomManualEditsReset: (sel: DomEditSelection) => Promise<void>;
   selectedGsapAnimations: GsapAnimation[];
   showToast: (message: string, tone?: "error" | "info") => void;
 }) {
@@ -230,7 +230,9 @@ export function useGsapSelectionHandlers({
         },
       );
       if (domEditSelection.element.hasAttribute("data-hf-studio-path-offset")) {
-        handleDomManualEditsReset(domEditSelection);
+        // The reset owns rollback and the position commit already owns user and
+        // telemetry reporting. This is only the fire-and-forget UI boundary.
+        void handleDomManualEditsReset(domEditSelection).catch(() => undefined);
       }
     },
     [domEditSelection, addGsapAnimation, handleDomManualEditsReset, trackGsapHandlerFailure],

package/src/utils/studioUiPreferences.ts

@@ -34,6 +34,14 @@ export interface StudioUiPreferences {
   timelineZoomMode?: "fit" | "manual";
   /** Manual timeline zoom percent, paired with `timelineZoomMode: "manual"`. */
   timelineManualZoomPercent?: number;
+  /**
+   * Expose Studio's editing capabilities to an agentic browser as WebMCP tools.
+   * Absent means on: the browser still gates every actual call behind its own
+   * permission prompt, so "registered" is not "reachable without consent".
+   * Changes take effect on the next Studio reload because registration is
+   * intentionally scoped to one mount.
+   */
+  agentToolsEnabled?: boolean;
 }
 
 const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";
@@ -140,6 +148,9 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     ) {
       preferences.timelineManualZoomPercent = parsed.timelineManualZoomPercent;
     }
+    if (typeof parsed.agentToolsEnabled === "boolean") {
+      preferences.agentToolsEnabled = parsed.agentToolsEnabled;
+    }
     return preferences;
   } catch {
     return {};

package/src/webmcp/StudioAgentTools.tsx

@@ -0,0 +1,46 @@
+import { useCallback } from "react";
+import { useDomEditSelectionContext } from "../contexts/DomEditContext";
+import { useStudioShellContext } from "../contexts/StudioContext";
+import { usePlayerStore } from "../player";
+import { useStudioAgentTools } from "./useStudioAgentTools";
+import type { StudioLookSnapshot } from "./tools/lookTools";
+
+/**
+ * Mounts Studio's WebMCP tool surface. Renders nothing.
+ *
+ * Lives inside `EditorShell` rather than `App` for two reasons: the DomEdit
+ * contexts are only readable below `DomEditProvider`, which `App` renders, and
+ * `App.tsx` sits three lines under the 600-line cap.
+ *
+ * The player store is read IMPERATIVELY through `getState()` inside the
+ * snapshot callback rather than subscribed to. Subscribing to `currentTime`
+ * would re-render this component on every animation frame during playback for
+ * a value nothing here displays.
+ */
+export function StudioAgentTools() {
+  const { projectId, activeCompPath, editHistory } = useStudioShellContext();
+  const { domEditSelection, selectedGsapAnimations } = useDomEditSelectionContext();
+
+  const getSnapshot = useCallback((): StudioLookSnapshot => {
+    const player = usePlayerStore.getState();
+    return {
+      projectId,
+      compositionPath: activeCompPath,
+      currentTime: player.currentTime,
+      duration: player.duration,
+      isPlaying: player.isPlaying,
+      elements: player.elements,
+      selection: domEditSelection,
+      selectionAnimationCount: selectedGsapAnimations.length,
+      history: {
+        canUndo: editHistory.canUndo,
+        canRedo: editHistory.canRedo,
+        undoLabel: editHistory.undoLabel ?? null,
+        redoLabel: editHistory.redoLabel ?? null,
+      },
+    };
+  }, [projectId, activeCompPath, domEditSelection, selectedGsapAnimations, editHistory]);
+
+  useStudioAgentTools({ getSnapshot });
+  return null;
+}