@hyperframes/studio 0.8.16 → 0.8.17

package/src/webmcp/handles.test.ts

@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../player/store/timelineElement";
+import {
+  mintElementHandle,
+  parseElementHandle,
+  resolveElementHandle,
+  timelineElementAddress,
+} from "./handles";
+
+function timelineElement(overrides: Partial<TimelineElement>): TimelineElement {
+  return { id: "synthetic-id", tag: "div", start: 0, duration: 1, track: 0, ...overrides };
+}
+
+/** A separate document, standing in for the preview iframe's realm. */
+function previewDoc(html: string): Document {
+  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;
+  return doc;
+}
+
+describe("mintElementHandle", () => {
+  it("prefers data-hf-id, the stable patch target", () => {
+    const handle = mintElementHandle(
+      timelineElementAddress(
+        timelineElement({ hfId: "abc123", domId: "headline", selector: ".title" }),
+      ),
+    );
+    expect(handle).toBe("hf:abc123");
+  });
+
+  it("falls back to the DOM id when there is no hf id", () => {
+    expect(
+      mintElementHandle(
+        timelineElementAddress(timelineElement({ domId: "headline", selector: ".title" })),
+      ),
+    ).toBe("dom:headline");
+  });
+
+  it("falls back to a selector with its occurrence index", () => {
+    expect(
+      mintElementHandle(
+        timelineElementAddress(timelineElement({ selector: ".card", selectorIndex: 2 })),
+      ),
+    ).toBe("sel:.card#2");
+  });
+
+  it("defaults a missing occurrence index to the first match", () => {
+    expect(mintElementHandle(timelineElementAddress(timelineElement({ selector: ".card" })))).toBe(
+      "sel:.card#0",
+    );
+  });
+
+  it("returns null when the element carries no way to address it", () => {
+    // The synthesised `id` is deliberately NOT used: it cannot resolve.
+    expect(mintElementHandle(timelineElementAddress(timelineElement({})))).toBeNull();
+  });
+});
+
+describe("parseElementHandle", () => {
+  it("splits the index off the LAST hash, so id selectors survive", () => {
+    expect(parseElementHandle("sel:#card > .title#3")).toEqual({
+      scheme: "sel",
+      value: "#card > .title",
+      index: 3,
+    });
+  });
+
+  it("treats a selector with no index as the first match", () => {
+    expect(parseElementHandle("sel:.card")).toEqual({ scheme: "sel", value: ".card", index: 0 });
+  });
+
+  it("rejects an unknown scheme", () => {
+    expect(parseElementHandle("xpath://div")).toBeNull();
+  });
+
+  it("rejects a handle with no value", () => {
+    expect(parseElementHandle("dom:")).toBeNull();
+    expect(parseElementHandle("")).toBeNull();
+    expect(parseElementHandle(":headline")).toBeNull();
+  });
+});
+
+describe("resolveElementHandle", () => {
+  it("round-trips every handle scheme a read can mint", () => {
+    const doc = previewDoc(
+      `<div id="headline" data-hf-id="abc123">A</div>
+       <div class="card">first</div>
+       <div class="card">second</div>`,
+    );
+
+    expect(resolveElementHandle(doc, "hf:abc123")?.id).toBe("headline");
+    expect(resolveElementHandle(doc, "dom:headline")?.id).toBe("headline");
+    expect(resolveElementHandle(doc, "sel:.card#1")?.textContent).toBe("second");
+  });
+
+  it("resolves across realms, where a naive instanceof check fails", () => {
+    const doc = previewDoc('<div id="headline">A</div>');
+    const resolved = resolveElementHandle(doc, "dom:headline");
+
+    expect(resolved).not.toBeNull();
+    // The preview element is NOT an instance of Studio's own HTMLElement.
+    expect(resolved instanceof HTMLElement).toBe(false);
+  });
+
+  it("returns null for a handle that no longer matches", () => {
+    const doc = previewDoc('<div id="headline">A</div>');
+    expect(resolveElementHandle(doc, "dom:deleted")).toBeNull();
+    expect(resolveElementHandle(doc, "hf:missing")).toBeNull();
+    expect(resolveElementHandle(doc, "sel:.card#0")).toBeNull();
+  });
+
+  it("returns null for an out-of-range occurrence rather than the wrong element", () => {
+    const doc = previewDoc('<div class="card">only</div>');
+    expect(resolveElementHandle(doc, "sel:.card#4")).toBeNull();
+  });
+
+  it("returns null for a selector that is invalid in this document", () => {
+    const doc = previewDoc('<div class="card">only</div>');
+    expect(resolveElementHandle(doc, "sel:>>>broken#0")).toBeNull();
+  });
+
+  it("returns null for a malformed handle", () => {
+    const doc = previewDoc('<div id="headline">A</div>');
+    expect(resolveElementHandle(doc, "nonsense")).toBeNull();
+  });
+});

package/src/webmcp/handles.ts

@@ -0,0 +1,129 @@
+/**
+ * Opaque element handles: the one thing reads mint and writes consume.
+ *
+ * `TimelineElement.id` cannot do this job. It is a SYNTHESISED identity built
+ * from label, index, selector and source file when the clip has no authored id
+ * (`timelineElementHelpers.buildTimelineElementIdentity`), so
+ * `getElementById(element.id)` misses most elements. The real addressing fields
+ * are separate: `hfId` (the `data-hf-id` the codebase calls the stable primary
+ * patch target), `domId`, and a `selector` plus occurrence index.
+ *
+ * Handles are strings so they survive a JSON round trip through the agent
+ * untouched. The agent never builds one; it passes back what a read gave it.
+ */
+
+import type { TimelineElement } from "../player/store/timelineElement";
+import type { PatchTarget } from "../utils/sourcePatcher";
+
+const SEPARATOR = ":";
+const INDEX_SEPARATOR = "#";
+
+/**
+ * How to find one element. `TimelineElement` calls the DOM id `domId` and
+ * `PatchTarget` calls it `id`, so both adapt into this rather than the minter
+ * knowing about either.
+ */
+export interface ElementAddress {
+  hfId?: string;
+  domId?: string | null;
+  selector?: string;
+  selectorIndex?: number;
+}
+
+/**
+ * Address an element the same way Studio's own patcher does, most stable first.
+ * `data-hf-id` survives edits that renumber or reorder; a bare selector does not.
+ */
+export function mintElementHandle(address: ElementAddress): string | null {
+  if (address.hfId) return `hf${SEPARATOR}${address.hfId}`;
+  if (address.domId) return `dom${SEPARATOR}${address.domId}`;
+  if (address.selector) {
+    const index = address.selectorIndex ?? 0;
+    return `sel${SEPARATOR}${address.selector}${INDEX_SEPARATOR}${index}`;
+  }
+  return null;
+}
+
+export function timelineElementAddress(element: TimelineElement): ElementAddress {
+  return {
+    hfId: element.hfId,
+    domId: element.domId,
+    selector: element.selector,
+    selectorIndex: element.selectorIndex,
+  };
+}
+
+export function patchTargetAddress(target: PatchTarget): ElementAddress {
+  return {
+    hfId: target.hfId,
+    domId: target.id,
+    selector: target.selector,
+    selectorIndex: target.selectorIndex,
+  };
+}
+
+interface ParsedHandle {
+  scheme: "hf" | "dom" | "sel";
+  value: string;
+  index: number;
+}
+
+export function parseElementHandle(handle: string): ParsedHandle | null {
+  const separatorAt = handle.indexOf(SEPARATOR);
+  if (separatorAt <= 0) return null;
+  const scheme = handle.slice(0, separatorAt);
+  const rest = handle.slice(separatorAt + 1);
+  if (!rest) return null;
+  if (scheme === "hf" || scheme === "dom") return { scheme, value: rest, index: 0 };
+  if (scheme !== "sel") return null;
+
+  // Only the LAST `#` splits the index off: CSS selectors contain `#` themselves.
+  const indexAt = rest.lastIndexOf(INDEX_SEPARATOR);
+  if (indexAt <= 0) return { scheme, value: rest, index: 0 };
+  const index = Number(rest.slice(indexAt + 1));
+  if (!Number.isInteger(index) || index < 0) return { scheme, value: rest, index: 0 };
+  return { scheme, value: rest.slice(0, indexAt), index };
+}
+
+/**
+ * Resolve a handle against the preview document.
+ *
+ * Always re-resolve per call rather than holding an element across calls: a
+ * preview reload replaces the document, and a node from the destroyed one is
+ * detached but still looks like an element.
+ */
+export function resolveElementHandle(doc: Document, handle: string): HTMLElement | null {
+  const parsed = parseElementHandle(handle);
+  if (!parsed) return null;
+
+  if (parsed.scheme === "dom") return asHtmlElement(doc, doc.getElementById(parsed.value));
+  if (parsed.scheme === "hf") {
+    return asHtmlElement(doc, doc.querySelector(`[data-hf-id="${cssEscape(parsed.value)}"]`));
+  }
+
+  let matches: NodeListOf<Element>;
+  try {
+    matches = doc.querySelectorAll(parsed.value);
+  } catch {
+    // A selector minted from a previous document can be invalid in this one.
+    return null;
+  }
+  return asHtmlElement(doc, matches.item(parsed.index));
+}
+
+function cssEscape(value: string): string {
+  // ponytail: happy-dom and jsdom don't always ship CSS.escape; quoting the two
+  // characters that can break out of an attribute selector covers this use.
+  return typeof CSS?.escape === "function" ? CSS.escape(value) : value.replace(/["\\]/g, "\\$&");
+}
+
+/**
+ * `instanceof HTMLElement` is checked against the OWNING document's realm.
+ * The preview lives in an iframe, so Studio's own `HTMLElement` is a different
+ * constructor and the naive check fails on every real preview element.
+ */
+function asHtmlElement(doc: Document, node: Element | null): HTMLElement | null {
+  if (!node) return null;
+  const ctor = doc.defaultView?.HTMLElement;
+  return ctor && node instanceof ctor ? node : null;
+}

package/src/webmcp/polyfill.test.ts

@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ModelContext } from "./types";
+
+// The real package defines `document.modelContext` as an import side effect.
+// A mock cannot do that, so tests stand the object up themselves to represent
+// the import having happened.
+const trackEvent = vi.hoisted(() => vi.fn());
+vi.mock("@mcp-b/global", () => ({}));
+vi.mock("../telemetry/client", () => ({ trackEvent }));
+
+let loadModelContextPolyfill: typeof import("./polyfill").loadModelContextPolyfill;
+
+function installModelContext(): ModelContext {
+  const modelContext: ModelContext = { registerTool: vi.fn().mockResolvedValue(undefined) };
+  Object.defineProperty(document, "modelContext", {
+    value: modelContext,
+    configurable: true,
+    writable: true,
+  });
+  return modelContext;
+}
+
+beforeEach(async () => {
+  vi.resetModules();
+  ({ loadModelContextPolyfill } = await import("./polyfill"));
+  trackEvent.mockReset();
+});
+
+afterEach(() => {
+  Reflect.deleteProperty(document, "modelContext");
+  vi.restoreAllMocks();
+});
+
+describe("loadModelContextPolyfill", () => {
+  it("returns the model context the package defines", async () => {
+    const modelContext = installModelContext();
+
+    await expect(loadModelContextPolyfill()).resolves.toBe(modelContext);
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.polyfill_loaded");
+  });
+
+  it("shares one load between callers that race", async () => {
+    installModelContext();
+
+    // Identity, not a call count: the guard being tested is the module-level
+    // promise, and the ESM registry would dedupe the import either way.
+    const first = loadModelContextPolyfill();
+    const second = loadModelContextPolyfill();
+
+    expect(first).toBe(second);
+    await expect(first).resolves.toBe(await second);
+  });
+
+  it("reuses the settled load rather than starting another", async () => {
+    installModelContext();
+
+    const first = loadModelContextPolyfill();
+    await first;
+
+    expect(loadModelContextPolyfill()).toBe(first);
+  });
+
+  it("returns null when the package loads but defines nothing", async () => {
+    // Studio must still boot. A missing agent surface is not a broken editor.
+    const first = loadModelContextPolyfill();
+    await expect(first).resolves.toBeNull();
+
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.polyfill_failed", {
+      error_name: "ModelContextMissingError",
+    });
+    const retry = loadModelContextPolyfill();
+    expect(retry).not.toBe(first);
+    await expect(retry).resolves.toBeNull();
+  });
+
+  it("reports a polyfill failure and lets a later mount retry", async () => {
+    const failure = new TypeError("blocked by policy");
+    Object.defineProperty(document, "modelContext", {
+      configurable: true,
+      get: () => {
+        throw failure;
+      },
+    });
+
+    const first = loadModelContextPolyfill();
+    await expect(first).resolves.toBeNull();
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.polyfill_failed", {
+      error_name: "TypeError",
+    });
+
+    Reflect.deleteProperty(document, "modelContext");
+    const modelContext = installModelContext();
+    const retry = loadModelContextPolyfill();
+    expect(retry).not.toBe(first);
+    await expect(retry).resolves.toBe(modelContext);
+  });
+});

package/src/webmcp/polyfill.ts

@@ -0,0 +1,60 @@
+/**
+ * The fallback for browsers that have not shipped WebMCP.
+ *
+ * `@mcp-b/global` does two things: it defines `document.modelContext`, and it
+ * stands up an in-page MCP server for a bridge extension to attach to. The
+ * second is the reason this is the chosen package over the bare
+ * `@mcp-b/webmcp-polyfill`: without the server there is nothing for an
+ * out-of-browser agent to connect to, which is the only case the fallback
+ * exists to serve.
+ *
+ * It is a DYNAMIC import so a browser with native support never downloads it,
+ * and so it lands in its own chunk rather than the entry bundle.
+ */
+
+import { makeStudioDebugLogger } from "../utils/studioDebug";
+import { trackEvent } from "../telemetry/client";
+import { getModelContext, type ModelContext } from "./types";
+
+const log = makeStudioDebugLogger("webmcp");
+
+/**
+ * Module-level, so two mounts racing (React StrictMode, or a remount during
+ * the import) share one load instead of pulling the package twice.
+ */
+let pending: Promise<ModelContext | null> | null = null;
+
+async function importPolyfill(): Promise<ModelContext | null> {
+  try {
+    await import("@mcp-b/global");
+    const modelContext = getModelContext();
+    if (!modelContext) {
+      // The package loaded but did not define what it promises to define.
+      log("polyfill", { loaded: true, modelContext: false });
+      trackEvent("webmcp.polyfill_failed", { error_name: "ModelContextMissingError" });
+    } else {
+      trackEvent("webmcp.polyfill_loaded");
+    }
+    return modelContext;
+  } catch (error) {
+    // A missing agent surface must never break Studio's boot.
+    log("polyfill", { failed: error instanceof Error ? error.message : String(error) });
+    trackEvent("webmcp.polyfill_failed", {
+      error_name: error instanceof Error ? error.name : "NonError",
+    });
+    return null;
+  }
+}
+
+export function loadModelContextPolyfill(): Promise<ModelContext | null> {
+  if (pending) return pending;
+
+  const attempt = importPolyfill();
+  pending = attempt;
+  // A transient chunk/CSP failure must not disable WebMCP for the rest of the
+  // tab. Concurrent callers still share this attempt; a later mount may retry.
+  void attempt.then((modelContext) => {
+    if (modelContext === null && pending === attempt) pending = null;
+  });
+  return pending;
+}

package/src/webmcp/registrar.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import { findToolDefinitionError, registerStudioTools } from "./registrar";
+import type { ModelContext, ModelContextTool } from "./types";
+
+function tool(overrides: Partial<ModelContextTool> = {}): ModelContextTool {
+  return {
+    name: "studio_look",
+    description: "Read Studio's live state.",
+    execute: async () => ({ ok: true }),
+    ...overrides,
+  };
+}
+
+function fakeModelContext(
+  registerTool: ModelContext["registerTool"] = vi.fn().mockResolvedValue(undefined),
+): ModelContext {
+  return { registerTool };
+}
+
+function domException(name: string, message = name): DOMException {
+  return new DOMException(message, name);
+}
+
+describe("findToolDefinitionError", () => {
+  it("accepts the names Studio actually uses", () => {
+    expect(findToolDefinitionError(tool({ name: "studio_look" }))).toBeNull();
+    expect(findToolDefinitionError(tool({ name: "studio.look-2" }))).toBeNull();
+  });
+
+  it("rejects a name the browser would reject, naming the tool", () => {
+    expect(findToolDefinitionError(tool({ name: "studio look" }))).toMatch(/name must be/);
+    expect(findToolDefinitionError(tool({ name: "a".repeat(129) }))).toMatch(/name must be/);
+    expect(findToolDefinitionError(tool({ name: "" }))).toMatch(/name must be/);
+  });
+
+  it("rejects an empty description", () => {
+    expect(findToolDefinitionError(tool({ description: "   " }))).toBe(
+      "description must not be empty",
+    );
+  });
+});
+
+describe("registerStudioTools", () => {
+  it("registers every tool with the shared abort signal", async () => {
+    const registerTool = vi.fn().mockResolvedValue(undefined);
+    const controller = new AbortController();
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_frame" })],
+      controller.signal,
+    );
+
+    expect(report.registered).toEqual(["studio_look", "studio_frame"]);
+    expect(report.failed).toEqual([]);
+    expect(registerTool).toHaveBeenCalledTimes(2);
+    expect(registerTool.mock.calls[0]?.[1]).toEqual({ signal: controller.signal });
+  });
+
+  it("stops silently when the signal aborts mid-registration", async () => {
+    // A StrictMode mount-cleanup-mount rejects the in-flight registrations with
+    // AbortError. That is teardown working; it must not surface as a failure or
+    // escape as an unhandled rejection.
+    const registerTool = vi
+      .fn()
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(domException("AbortError"));
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_frame" })],
+      new AbortController().signal,
+    );
+
+    expect(report.registered).toEqual(["studio_look"]);
+    expect(report.failed).toEqual([]);
+  });
+
+  it("keeps the DOMException name, which is the only thing that tells the gates apart", async () => {
+    const registerTool = vi
+      .fn()
+      .mockRejectedValue(domException("SecurityError", "not origin-keyed"));
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool()],
+      new AbortController().signal,
+    );
+
+    expect(report.failed).toHaveLength(1);
+    expect(report.failed[0]?.tool).toBe("studio_look");
+    expect(report.failed[0]?.name).toBe("SecurityError");
+    // Substring, not equality: jsdom prefixes DOMException.message with the
+    // name and real browsers do not.
+    expect(report.failed[0]?.message).toContain("not origin-keyed");
+    expect(report.registered).toEqual([]);
+  });
+
+  it("keeps going after one tool fails", async () => {
+    const registerTool = vi
+      .fn()
+      .mockRejectedValueOnce(domException("NotAllowedError", "tools policy"))
+      .mockResolvedValueOnce(undefined);
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_frame" })],
+      new AbortController().signal,
+    );
+
+    expect(report.registered).toEqual(["studio_frame"]);
+    expect(report.failed.map((f) => f.tool)).toEqual(["studio_look"]);
+  });
+
+  it("catches a duplicate name before the browser does, so the report names it", async () => {
+    const registerTool = vi.fn().mockResolvedValue(undefined);
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_look" })],
+      new AbortController().signal,
+    );
+
+    expect(report.registered).toEqual(["studio_look"]);
+    expect(report.failed).toEqual([
+      {
+        tool: "studio_look",
+        name: "InvalidStateError",
+        message: "duplicate tool name in this registration set",
+      },
+    ]);
+    // Registering the same name twice REJECTS rather than replacing, so the
+    // second one must never reach the browser.
+    expect(registerTool).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not send a tool the browser would reject", async () => {
+    const registerTool = vi.fn().mockResolvedValue(undefined);
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio look" })],
+      new AbortController().signal,
+    );
+
+    expect(registerTool).not.toHaveBeenCalled();
+    expect(report.failed[0]?.name).toBe("InvalidStateError");
+  });
+});

package/src/webmcp/registrar.ts

@@ -0,0 +1,115 @@
+/**
+ * Registers Studio's tools with the browser, once.
+ *
+ * The only file besides `types.ts` that touches the WebMCP API, so a spec
+ * change lands here. Tool names are document-scoped, so Studio relies on its
+ * single live `EditorShell` mounting one `StudioAgentTools`. A second live
+ * shell would register the same names and receive `InvalidStateError`; the
+ * duplicate check below only owns duplicates within one registration set.
+ */
+
+import type { ModelContext, ModelContextTool } from "./types";
+
+export interface ToolRegistrationFailure {
+  tool: string;
+  /** The DOMException name where there is one. It is the only thing that tells
+   *  a duplicate name (InvalidStateError) apart from a document that is not
+   *  origin-keyed (SecurityError) or not permitted to use `tools`
+   *  (NotAllowedError), and all three look identical without it. */
+  name: string;
+  message: string;
+}
+
+export interface ToolRegistrationReport {
+  registered: string[];
+  failed: ToolRegistrationFailure[];
+}
+
+/** Max 128 chars, ASCII alphanumeric plus `_`, `-`, `.` (`index.bs`). */
+const VALID_TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+
+/**
+ * A tool whose name or description the browser would reject anyway. Caught here
+ * so the failure names the offending tool instead of arriving as one of N
+ * identical InvalidStateErrors.
+ */
+export function findToolDefinitionError(tool: ModelContextTool): string | null {
+  if (!VALID_TOOL_NAME.test(tool.name)) {
+    return `name must be 1-128 chars of A-Z a-z 0-9 _ - . (got ${JSON.stringify(tool.name)})`;
+  }
+  if (!tool.description.trim()) return "description must not be empty";
+  return null;
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function invalidState(tool: string, message: string): ToolRegistrationFailure {
+  return { tool, name: "InvalidStateError", message };
+}
+
+/**
+ * `"aborted"` is a third outcome, not a failure: teardown got there first and
+ * the caller should stop rather than record anything.
+ */
+type RegisterOneOutcome =
+  | { status: "registered" }
+  | { status: "failed"; failure: ToolRegistrationFailure }
+  | { status: "aborted" };
+
+async function registerOne(
+  modelContext: ModelContext,
+  tool: ModelContextTool,
+  signal: AbortSignal,
+): Promise<RegisterOneOutcome> {
+  const definitionError = findToolDefinitionError(tool);
+  if (definitionError) {
+    return { status: "failed", failure: invalidState(tool.name, definitionError) };
+  }
+
+  try {
+    await modelContext.registerTool(tool, { signal });
+    return { status: "registered" };
+  } catch (error) {
+    // A mount-cleanup-mount cycle (React StrictMode in dev) aborts the signal in
+    // the same task the registration promise is queued in, which rejects every
+    // registerTool with AbortError. That is teardown working, not a failure, and
+    // letting it escape fills the dev console with unhandled rejections.
+    if (isAbortError(error)) return { status: "aborted" };
+    return {
+      status: "failed",
+      failure: {
+        tool: tool.name,
+        name: error instanceof DOMException ? error.name : "Error",
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+export async function registerStudioTools(
+  modelContext: ModelContext,
+  tools: readonly ModelContextTool[],
+  signal: AbortSignal,
+): Promise<ToolRegistrationReport> {
+  const report: ToolRegistrationReport = { registered: [], failed: [] };
+  const seen = new Set<string>();
+
+  for (const tool of tools) {
+    // Registering a name twice REJECTS rather than replacing, so a duplicate
+    // must never reach the browser.
+    if (seen.has(tool.name)) {
+      report.failed.push(invalidState(tool.name, "duplicate tool name in this registration set"));
+      continue;
+    }
+    seen.add(tool.name);
+
+    const outcome = await registerOne(modelContext, tool, signal);
+    if (outcome.status === "aborted") return report;
+    if (outcome.status === "failed") report.failed.push(outcome.failure);
+    else report.registered.push(tool.name);
+  }
+
+  return report;
+}