@hyperframes/studio 0.8.16 → 0.8.17

package/src/webmcp/useStudioAgentTools.test.tsx

@@ -0,0 +1,221 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mountReactHarness } from "../hooks/domSelectionTestHarness";
+import { writeStudioUiPreferences } from "../utils/studioUiPreferences";
+import { useStudioAgentTools, type StudioAgentToolsDeps } from "./useStudioAgentTools";
+import type { ModelContext, ModelContextRegisterToolOptions, ModelContextTool } from "./types";
+import type { StudioLookSnapshot } from "./tools/lookTools";
+
+const trackEvent = vi.hoisted(() => vi.fn());
+vi.mock("../telemetry/client", () => ({ trackEvent }));
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+let cleanup: (() => void) | null = null;
+
+function snapshot(overrides: Partial<StudioLookSnapshot> = {}): StudioLookSnapshot {
+  return {
+    projectId: "demo",
+    compositionPath: "index.html",
+    currentTime: 0,
+    duration: 10,
+    isPlaying: false,
+    elements: [],
+    selection: null,
+    selectionAnimationCount: 0,
+    history: { canUndo: false, canRedo: false, undoLabel: null, redoLabel: null },
+    ...overrides,
+  };
+}
+
+/** Install a fake `document.modelContext` and report what got registered. */
+function installModelContext() {
+  const registered: ModelContextTool[] = [];
+  const registerTool = vi.fn(
+    async (tool: ModelContextTool, _options?: ModelContextRegisterToolOptions) => {
+      registered.push(tool);
+    },
+  );
+  const modelContext: ModelContext = { registerTool };
+  Object.defineProperty(document, "modelContext", {
+    value: modelContext,
+    configurable: true,
+    writable: true,
+  });
+  return { registered, registerTool };
+}
+
+function removeModelContext() {
+  Reflect.deleteProperty(document, "modelContext");
+}
+
+function mountTools(deps: StudioAgentToolsDeps) {
+  function Probe({ current }: { current: StudioAgentToolsDeps }) {
+    useStudioAgentTools(current);
+    return null;
+  }
+  const root = mountReactHarness(<Probe current={deps} />);
+  cleanup = () => act(() => root.unmount());
+  return {
+    rerenderWith(next: StudioAgentToolsDeps) {
+      act(() => root.render(<Probe current={next} />));
+    },
+  };
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  trackEvent.mockReset();
+});
+
+afterEach(() => {
+  cleanup?.();
+  cleanup = null;
+  removeModelContext();
+  window.localStorage.clear();
+  vi.restoreAllMocks();
+});
+
+describe("useStudioAgentTools", () => {
+  it("registers the tool set once on mount", async () => {
+    const { registered } = installModelContext();
+
+    await act(async () => {
+      mountTools({ getSnapshot: () => snapshot() });
+    });
+
+    expect(registered.map((tool) => tool.name)).toEqual(["studio_look"]);
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.native_present");
+  });
+
+  it("does not re-register when the deps object changes identity", async () => {
+    // The regression test for the whole design. The DomEdit actions object
+    // changes identity on nearly every interaction; if registration depended on
+    // it, the signal would abort and unregister the tools each time.
+    const { registerTool } = installModelContext();
+
+    let harness: ReturnType<typeof mountTools> | null = null;
+    await act(async () => {
+      harness = mountTools({ getSnapshot: () => snapshot() });
+    });
+    expect(registerTool).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      harness?.rerenderWith({ getSnapshot: () => snapshot({ currentTime: 5 }) });
+      harness?.rerenderWith({ getSnapshot: () => snapshot({ currentTime: 6 }) });
+    });
+
+    expect(registerTool).toHaveBeenCalledTimes(1);
+  });
+
+  it("executes against the LATEST deps, not the ones present at registration", async () => {
+    // The other half of the ref: registering once must not freeze the state the
+    // tools read, or every answer after the first render would be stale.
+    const { registered } = installModelContext();
+
+    let harness: ReturnType<typeof mountTools> | null = null;
+    await act(async () => {
+      harness = mountTools({ getSnapshot: () => snapshot({ currentTime: 1 }) });
+    });
+
+    await act(async () => {
+      harness?.rerenderWith({ getSnapshot: () => snapshot({ currentTime: 42 }) });
+    });
+
+    const look = registered[0];
+    if (!look) throw new Error("expected studio_look to be registered");
+    const result = (await look.execute({}, { signal: new AbortController().signal })) as {
+      ok: boolean;
+      playhead: number;
+    };
+
+    expect(result.ok).toBe(true);
+    expect(result.playhead).toBe(42);
+  });
+
+  it("unregisters on unmount by aborting the registration signal", async () => {
+    const { registerTool } = installModelContext();
+
+    await act(async () => {
+      mountTools({ getSnapshot: () => snapshot() });
+    });
+    const signal = registerTool.mock.calls[0]?.[1]?.signal;
+    expect(signal?.aborted).toBe(false);
+
+    cleanup?.();
+    cleanup = null;
+
+    expect(signal?.aborted).toBe(true);
+  });
+
+  it("registers nothing when the browser has no WebMCP", async () => {
+    removeModelContext();
+
+    await act(async () => {
+      mountTools({ getSnapshot: () => snapshot() });
+    });
+
+    // The assertion is that mounting did not throw; a browser without the API
+    // must still boot Studio.
+    expect(document).not.toHaveProperty("modelContext");
+  });
+
+  it("registers nothing when the preference is turned off", async () => {
+    writeStudioUiPreferences({ agentToolsEnabled: false });
+    const { registerTool } = installModelContext();
+
+    await act(async () => {
+      mountTools({ getSnapshot: () => snapshot() });
+    });
+
+    expect(registerTool).not.toHaveBeenCalled();
+  });
+
+  it("registers when the preference is absent, because on is the default", async () => {
+    const { registerTool } = installModelContext();
+
+    await act(async () => {
+      mountTools({ getSnapshot: () => snapshot() });
+    });
+
+    expect(registerTool).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports a non-abort registration failure through production telemetry", async () => {
+    const { registerTool } = installModelContext();
+    registerTool.mockRejectedValue(new DOMException("blocked", "NotAllowedError"));
+
+    await act(async () => {
+      mountTools({ getSnapshot: () => snapshot() });
+    });
+
+    expect(trackEvent).toHaveBeenCalledWith("webmcp_registration_failed", {
+      error_name: "NotAllowedError",
+      tool_name: "studio_look",
+    });
+  });
+
+  it("reports a tool that throws as an internal failure instead of rejecting", async () => {
+    const { registered } = installModelContext();
+
+    await act(async () => {
+      mountTools({
+        getSnapshot: () => {
+          throw new TypeError("handler signature moved");
+        },
+      });
+    });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const look = registered[0];
+    if (!look) throw new Error("expected studio_look to be registered");
+    const result = (await look.execute({}, { signal: new AbortController().signal })) as {
+      ok: boolean;
+      kind: string;
+    };
+
+    expect(result.ok).toBe(false);
+    expect(result.kind).toBe("internal");
+  });
+});

package/src/webmcp/useStudioAgentTools.ts

@@ -0,0 +1,119 @@
+import { useEffect, useRef } from "react";
+import { trackEvent } from "../telemetry/client";
+import { readStudioUiPreferences } from "../utils/studioUiPreferences";
+import { makeStudioDebugLogger } from "../utils/studioDebug";
+import { loadModelContextPolyfill } from "./polyfill";
+import { registerStudioTools, type ToolRegistrationReport } from "./registrar";
+import { runToolBody, type ToolResult } from "./toolResult";
+import { getModelContext, type ModelContext, type ModelContextTool } from "./types";
+import {
+  buildStudioLook,
+  STUDIO_LOOK_DESCRIPTION,
+  STUDIO_LOOK_INPUT_SCHEMA,
+  type StudioLook,
+  type StudioLookInput,
+  type StudioLookSnapshot,
+} from "./tools/lookTools";
+
+const log = makeStudioDebugLogger("webmcp");
+
+function reportRegistration(report: ToolRegistrationReport, native: boolean): void {
+  log("registered", { native, ...report });
+  for (const failure of report.failed) {
+    trackEvent("webmcp_registration_failed", {
+      error_name: failure.name,
+      tool_name: failure.tool,
+    });
+  }
+}
+
+export interface StudioAgentToolsDeps {
+  /** Read Studio's current state. Called per tool invocation, never cached. */
+  getSnapshot: () => StudioLookSnapshot;
+}
+
+/**
+ * Build the tool list once.
+ *
+ * Every `execute` reads `depsRef.current` at CALL time rather than closing over
+ * a snapshot, which is what lets the list be built once and still see live
+ * state. That is the whole point of the ref: see the registration note below.
+ */
+function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }): ModelContextTool[] {
+  return [
+    {
+      name: "studio_look",
+      title: "Look at the composition",
+      description: STUDIO_LOOK_DESCRIPTION,
+      inputSchema: STUDIO_LOOK_INPUT_SCHEMA,
+      annotations: {
+        readOnlyHint: true,
+        // The labels, text and ids come from the user's composition, which can
+        // contain anything. This is a hint to the agent, not a sanitiser.
+        untrustedContentHint: true,
+      },
+      execute: (input): Promise<ToolResult<StudioLook>> =>
+        runToolBody("studio_look", async () =>
+          buildStudioLook(depsRef.current.getSnapshot(), input as StudioLookInput),
+        ),
+    },
+  ];
+}
+
+/**
+ * Register Studio's tools with the browser, exactly once per mount.
+ *
+ * The effect has an EMPTY dependency array on purpose, and the deps live in a
+ * ref that every render refreshes. The obvious alternative — depend on the
+ * handlers — re-runs on nearly every interaction, because the DomEdit actions
+ * object changes identity whenever the selection or the element list does.
+ * Re-running means the registration signal aborts and unregisters everything,
+ * `toolchange` fires constantly so a connected agent watches the tool list
+ * churn, and the spec warns that a quick unregister-then-reregister can apply
+ * an old call's arguments against the new schema.
+ *
+ * `useStudioTestHooks` carries a comment about the same class of bug already hit
+ * in this codebase, where effect teardown revoked a lease moments after it was
+ * taken because writing state changed the effect's dependency identities.
+ *
+ * Any fallback must be awaited inside this effect before registration and then
+ * re-read here. Installing one from a sibling effect would race this mount-only
+ * lookup. Hot-module replacement can still create a brief unregister/register
+ * window in development; production has one document-scoped registration.
+ */
+export function useStudioAgentTools(deps: StudioAgentToolsDeps): void {
+  const depsRef = useRef(deps);
+  depsRef.current = deps;
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (readStudioUiPreferences().agentToolsEnabled === false) {
+      log("skipped", { why: "disabled by preference" });
+      return;
+    }
+
+    const controller = new AbortController();
+
+    void (async () => {
+      const native: ModelContext | null = getModelContext();
+      if (native) trackEvent("webmcp.native_present");
+      // Native browsers never download the polyfill.
+      const modelContext = native ?? (await loadModelContextPolyfill());
+      if (!modelContext) {
+        log("skipped", { why: "no model context, native or polyfilled" });
+        return;
+      }
+      // The import is async, so the component may already be gone.
+      if (controller.signal.aborted) return;
+
+      const report = await registerStudioTools(
+        modelContext,
+        buildStudioTools(depsRef),
+        controller.signal,
+      );
+      reportRegistration(report, native !== null);
+    })();
+
+    return () => controller.abort();
+  }, []);
+}