webmcpx 0.0.0-stage → 0.2.0

package/src/generated.js

@@ -0,0 +1,27 @@
+// @generated by `just gen` from crates/webmcpx-std. Do not edit.
+
+export const TOOLS = {
+  get_page_context: {"name":"get_page_context","title":"Get page context","description":"Describe the page the user is on: title, URL, language, meta description, heading outline and the text the user has selected. Use it for the page's structure or the user's selection; to find a fact on the page, call search_page instead.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"annotations":{"readOnlyHint":true,"untrustedContentHint":true}},
+  search_page: {"name":"search_page","title":"Search this page","description":"Find passages on the current page that match a query. Returns up to `limit` passages ranked by relevance, each with its section heading and a link to it. Prefer it to reading the whole page when looking for something specific.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Words to look for."},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5,"description":"Maximum passages to return."}},"required":["query"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"untrustedContentHint":true}},
+  fetch_as_markdown: {"name":"fetch_as_markdown","title":"Read page as Markdown","description":"Return the main content of the current page as Markdown. Long pages come in parts: when `truncated` is true, call again with `cursor` set to `next_cursor`.","inputSchema":{"type":"object","properties":{"cursor":{"type":"string","description":"The next_cursor value from a previous call."},"max_chars":{"type":"integer","minimum":100,"maximum":20000,"default":2000,"description":"Maximum characters to return."}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"untrustedContentHint":true}},
+  search_site: {"name":"search_site","title":"Search this website","description":"Search the whole website and return matching pages with title, URL and a short snippet. Use it to find pages other than the current one.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Words to look for."},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5,"description":"Maximum pages to return."}},"required":["query"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"untrustedContentHint":true}},
+};
+
+/** Error code -> retryable. */
+export const CODES = {
+  INVALID_INPUT: false,
+  NOT_FOUND: false,
+  RESULT_TOO_LARGE: false,
+  REFUSED: false,
+  RATE_LIMITED: true,
+  REQUIRES_USER: false,
+  UNAVAILABLE: true,
+};
+
+/** Authoring limits, in chars (webmcpx-core `limits`). */
+export const LIMITS = {
+  NAME_WARN: 30,
+  DESCRIPTION_WARN: 500,
+  TOOLS_WARN: 20,
+  OUTPUT_MAX: 20000,
+};

package/src/index.d.ts

@@ -0,0 +1,82 @@
+export type ToolName = "get_page_context" | "search_page" | "fetch_as_markdown" | "search_site";
+
+export interface SiteSearchResult {
+  title: string;
+  url: string;
+  snippet?: string;
+}
+
+export interface Options {
+  /** Tools to register. Default: get_page_context, search_page, fetch_as_markdown (+ search_site when `searchSite` is set). */
+  tools?: ToolName[];
+  /** Element (or selector) holding the main content. Default: `main`, `[role=main]`, `article`, else `body`. */
+  root?: Element | string;
+  /** Backend search for `search_site`. Return results best first. */
+  searchSite?: (query: string, options: { limit: number; signal?: AbortSignal }) => Promise<SiteSearchResult[]>;
+  /** Where to load the WebAssembly module from (URL, Response or bytes). Default: next to the loader. */
+  wasm?: string | URL | Response | BufferSource | WebAssembly.Module;
+}
+
+export interface Registration {
+  registered: ToolName[];
+  failed: { name: string; error: string }[];
+  /** Unregisters every tool registered by this call. */
+  dispose(): void;
+}
+
+/** Registers webmcpx standard tools. A no-op (empty `registered`) where WebMCP is unavailable. */
+export function register(options?: Options): Promise<Registration>;
+
+/** The tool contracts (name, title, description, inputSchema, annotations). */
+export const TOOLS: Record<ToolName, {
+  name: ToolName;
+  title: string;
+  description: string;
+  inputSchema: object;
+  annotations: Record<string, boolean>;
+}>;
+
+/** What every tool resolves with (as a JSON string). */
+export type Envelope<T = unknown> =
+  | { ok: true; data: T; truncated?: true; next_cursor?: string; hint?: string }
+  | { ok: false; error: { code: string; message: string; retryable: boolean }; hint?: string };
+
+/** An input field: a JSON type ("string", "number?" for optional), a list of choices, or a property schema. */
+export type InputField = string | readonly (string | number)[] | Record<string, unknown>;
+
+export interface ToolDefinition<I = any, O = unknown> {
+  /** 1–128 of A-Z a-z 0-9 _ . - (keep it under 30). */
+  name: string;
+  /** What it does and when to use it (under 500 chars). */
+  description: string;
+  /** Shorthand: `{ sku: "string", "qty?": "number", size: ["S", "M"] }`. */
+  input?: Record<string, InputField>;
+  /** A full JSON Schema instead of `input` (checked: type, enum, required, properties, bounds, pattern...). */
+  inputSchema?: { type: "object"; [key: string]: unknown };
+  /** Returns the data for `{ ok: true, data }`. Throw for errors; an error with a webmcpx `code` keeps it. */
+  run(input: I, client?: unknown): O | Promise<O>;
+  /** Only reads (readOnlyHint). */
+  readOnly?: boolean;
+  /** Changes something for the user: cart, booking, message (consequentialHint). */
+  acts?: boolean;
+  /** Returns third-party content, like reviews or comments (untrustedContentHint). */
+  untrusted?: boolean;
+  /** Abort to unregister. */
+  signal?: AbortSignal;
+}
+
+export interface ToolHandle {
+  /** Resolves true once registered, false where WebMCP is missing or the host refused it. */
+  ready: Promise<boolean>;
+  /** Unregisters the tool. */
+  dispose(): void;
+}
+
+/** Registers one of your own tools with the webmcpx contract. A no-op where WebMCP is missing. */
+export function tool<I = any, O = unknown>(definition: ToolDefinition<I, O>): ToolHandle;
+
+/** Exposes every `<form toolname>` as a tool (WebMCP declarative API), following DOM changes. */
+export function forms(): { dispose(): void };
+
+/** The JSON Schema an input shorthand stands for. */
+export function schema(input?: Record<string, InputField>): object;

package/src/index.js

@@ -0,0 +1,3 @@
+// webmcpx: the standard WebMCP tools, your own tools and <form toolname>, in one package.
+export { readPage, register, TOOLS } from "./loader.js";
+export { forms, schema, tool } from "./tool.js";

package/src/loader.js

@@ -0,0 +1,132 @@
+// webmcpx standard tools: registers them on the page. Owns the DOM and registerTool();
+// all text processing runs in a WebAssembly module loaded on the first tool call.
+import { CODES, TOOLS } from "./generated.js";
+
+const DEFAULT_TOOLS = ["get_page_context", "search_page", "fetch_as_markdown"];
+
+const envelope = (body) => JSON.stringify(body);
+const ok = (data) => envelope({ ok: true, data });
+const err = (code, message, hint) =>
+  envelope({ ok: false, error: { code, message, retryable: CODES[code] }, ...(hint && { hint }) });
+
+let wasm;
+const engine = (source) =>
+  (wasm ??= import("../wasm/webmcpx_wasm.js")
+    .then(async (m) => (await m.default(source ? { module_or_path: source } : undefined), m))
+    .catch((e) => {
+      wasm = undefined;
+      throw e;
+    }));
+
+// "blocks": main content as a webmcpx-std block stream; "context": the page. Self-contained:
+// agent/ runs its source in pages. Internal, not public API.
+export function readPage(what, root) {
+  const RECORD = "\x1e";
+  const FIELD = "\x1f";
+  const KINDS = {
+    H1: "h1", H2: "h2", H3: "h3", H4: "h4", H5: "h5", H6: "h6",
+    P: "p", LI: "li", PRE: "pre", BLOCKQUOTE: "quote",
+    DT: "p", DD: "p", FIGCAPTION: "p", SUMMARY: "p",
+  };
+  const SKIP = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "SVG", "NAV", "FOOTER", "ASIDE"]);
+  const base = location.href.split("#")[0];
+  const text = (s) => (s ?? "").replace(/\s+/g, " ").trim();
+  if (what === "context") {
+    return {
+      title: document.title,
+      url: location.href,
+      lang: document.documentElement.lang || undefined,
+      description: document.querySelector('meta[name="description"]')?.getAttribute("content") || undefined,
+      headings: [...document.querySelectorAll("h1, h2, h3")].slice(0, 30).map((h) => ({
+        level: Number(h.tagName[1]),
+        text: text(h.textContent).slice(0, 120),
+        url: h.id ? `${base}#${h.id}` : undefined,
+      })),
+      selection: text(globalThis.getSelection?.()?.toString()).slice(0, 1000) || undefined,
+    };
+  }
+  const skipped = (el) => SKIP.has(el.tagName) || el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true";
+  let out = "";
+  let anchor = "";
+  const visit = (el) => {
+    for (const child of el.children) {
+      if (skipped(child)) continue;
+      if (child.id) anchor = `${base}#${child.id}`;
+      // A table row is one block ("Monday | Closed"), so search keeps a value next to its label.
+      const row = child.tagName === "TR" && [...child.children].filter((c) => !skipped(c)).map((c) => text(c.textContent)).join(" | ");
+      const kind = row ? "p" : KINDS[child.tagName] ?? (child.children.length === 0 && "p");
+      if (kind) out += kind + FIELD + (row || child.textContent) + FIELD + anchor + RECORD;
+      else visit(child);
+    }
+  };
+  visit(root ?? document.querySelector("main, [role=main], article") ?? document.body);
+  return out;
+}
+
+const contentRoot = (root) => (typeof root === "string" ? document.querySelector(root) ?? document.body : root);
+
+function executors(options) {
+  const withEngine = (run) => async (input) => {
+    let m;
+    try {
+      m = await engine(options.wasm);
+    } catch (e) {
+      return err("UNAVAILABLE", `WebAssembly could not load: ${e?.message ?? e}`,
+        "If the page sets a Content-Security-Policy, add 'wasm-unsafe-eval' to script-src.");
+    }
+    return run(m, readPage("blocks", contentRoot(options.root)), input);
+  };
+  return {
+    get_page_context: async () => ok(readPage("context")),
+    search_page: withEngine((m, page, { query, limit }) =>
+      typeof query === "string" ? m.search(page, query, limit ?? 0) : err("INVALID_INPUT", "`query` must be a string")),
+    fetch_as_markdown: withEngine((m, page, { cursor, max_chars }) => m.markdown(page, String(cursor ?? ""), max_chars ?? 0)),
+    search_site: async ({ query, limit = 5 }, { signal } = {}) => {
+      if (typeof query !== "string" || !query.trim()) return err("INVALID_INPUT", "`query` must be a non-empty string");
+      const found = await options.searchSite(query, { limit, signal });
+      if (!found?.length) return err("NOT_FOUND", "no page matches the query", "Try fewer or different words.");
+      return ok({ results: found.slice(0, limit).map(({ title, url, snippet }) => ({ title, url, snippet })) });
+    },
+  };
+}
+
+/** Tools resolve with an envelope and never reject: hosts drop rejection reasons (webmcp#282). */
+const guard = (run) => async (input, client) => {
+  try {
+    return await run(typeof input === "string" ? JSON.parse(input || "{}") : input ?? {}, client);
+  } catch (e) {
+    return err("UNAVAILABLE", String(e?.message ?? e));
+  }
+};
+
+/**
+ * Registers webmcpx standard tools on the current document.
+ * @param {import("./index").Options} [options]
+ * @returns {Promise<import("./index").Registration>}
+ */
+export async function register(options = {}) {
+  const mc = globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
+  const controller = new AbortController();
+  const result = { registered: [], failed: [], dispose: () => controller.abort() };
+  if (typeof mc?.registerTool !== "function") return result;
+
+  const run = executors(options);
+  const names = options.tools ?? [...DEFAULT_TOOLS, ...(options.searchSite ? ["search_site"] : [])];
+  await Promise.all(names.map(async (name) => {
+    if (!TOOLS[name]) return result.failed.push({ name, error: "unknown tool" });
+    if (name === "search_site" && !options.searchSite) {
+      return result.failed.push({ name, error: "search_site needs options.searchSite" });
+    }
+    try {
+      // Never assign onto `mc`: some agent browsers expose a frozen object (webmcp#293).
+      await mc.registerTool({ ...TOOLS[name], execute: guard(run[name]) }, { signal: controller.signal });
+      result.registered.push(name);
+    } catch (e) {
+      result.failed.push({ name, error: String(e?.message ?? e) });
+    }
+  }));
+  result.registered.sort();
+  return result;
+}
+
+export { TOOLS };

package/src/react.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "./index.js";
+
+/** Registers the tool while the component is mounted. */
+export function useTool(definition: ToolDefinition): void;

package/src/react.js

@@ -0,0 +1,17 @@
+// React 16.8+ (and Preact via preact/compat): `useTool({ name, description, input, run })` registers the tool while the component is
+// mounted. `run` always sees the latest props and state; the tool re-registers when what the agent
+// sees changes: name, description, input or annotations.
+import { useEffect, useRef } from "react";
+import { tool } from "./tool.js";
+
+export function useTool(definition) {
+  const latest = useRef(definition);
+  latest.current = definition;
+  const { name, description, input, inputSchema, readOnly, acts, untrusted, signal } = definition;
+  // What the agent sees (and is told about safety) re-registers the tool; `run` is always the latest.
+  const shape = JSON.stringify([input ?? {}, inputSchema ?? null]);
+  useEffect(
+    () => tool({ ...latest.current, run: (args, client) => latest.current.run(args, client) }).dispose,
+    [name, description, shape, Boolean(readOnly), Boolean(acts), Boolean(untrusted), signal],
+  );
+}

package/src/svelte.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "./index.js";
+
+/** Registers the tool while the component is mounted. */
+export function useTool(definition: ToolDefinition): void;

package/src/svelte.js

@@ -0,0 +1,8 @@
+// Svelte 3, 4 and 5: `useTool(definition)` in a component's script registers the tool while it is
+// mounted. (In Svelte 5 you can also write `$effect(() => tool(definition).dispose)`.)
+import { onMount } from "svelte";
+import { tool } from "./tool.js";
+
+export function useTool(definition) {
+  onMount(() => tool(definition).dispose);
+}

package/src/tool.js

@@ -0,0 +1,269 @@
+// Your own tools with the standard tools' contract (one result shape, validated input, never a
+// rejection), and the WebMCP declarative API (<form toolname>, webmcp's declarative-api-explainer.md)
+// in browsers that expose WebMCP without it.
+import { CODES, LIMITS } from "./generated.js";
+
+const context = () => globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
+const envelope = (body) => JSON.stringify(body);
+const fail = (code, message, hint) =>
+  envelope({ ok: false, error: { code, message, retryable: CODES[code] }, ...(hint && { hint }) });
+const NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+let count = 0;
+
+/** Input shorthand to JSON Schema: `{ sku: "string", qty: "number?", size: ["S", "M"] }` (see index.d.ts). */
+export function schema(input = {}) {
+  const properties = {};
+  const required = [];
+  for (const [rawKey, spec] of Object.entries(input)) {
+    const key = rawKey.replace(/\?$/, "");
+    const optional = rawKey !== key || (typeof spec === "string" && spec.endsWith("?"));
+    properties[key] =
+      typeof spec === "string" ? { type: spec.replace(/\?$/, "") } : Array.isArray(spec) ? { enum: spec } : spec;
+    if (!optional) required.push(key);
+  }
+  return { type: "object", properties, ...(required.length && { required }) };
+}
+
+const TYPES = {
+  string: (v) => typeof v === "string",
+  number: (v) => typeof v === "number" && Number.isFinite(v),
+  integer: Number.isInteger,
+  boolean: (v) => typeof v === "boolean",
+  array: Array.isArray,
+  null: (v) => v === null,
+  object: (v) => v !== null && typeof v === "object" && !Array.isArray(v),
+};
+
+/** The first problem with `value` against JSON Schema `s` (the keywords tool inputs use), or "". */
+function check(s, value, at = "input") {
+  if (!s || typeof s !== "object") return "";
+  const types = s.type === undefined ? [] : [].concat(s.type);
+  if (types.length && !types.some((t) => TYPES[t]?.(value))) return `${at} must be of type ${types.join(" or ")}`;
+  if (s.enum && !s.enum.includes(value)) return `${at} must be one of ${s.enum.join(", ")}`;
+  if (typeof value === "number") {
+    if (value < s.minimum) return `${at} must be at least ${s.minimum}`;
+    if (value > s.maximum) return `${at} must be at most ${s.maximum}`;
+  }
+  if (typeof value === "string") {
+    if (value.length < s.minLength) return `${at} must have at least ${s.minLength} chars`;
+    if (value.length > s.maxLength) return `${at} must have at most ${s.maxLength} chars`;
+    if (s.pattern && !new RegExp(s.pattern, "u").test(value)) return `${at} must match ${s.pattern}`;
+  }
+  if (Array.isArray(value)) {
+    if (value.length < s.minItems) return `${at} must have at least ${s.minItems} items`;
+    if (value.length > s.maxItems) return `${at} must have at most ${s.maxItems} items`;
+    for (let i = 0; i < value.length; i++) {
+      const problem = check(s.items, value[i], `${at}[${i}]`);
+      if (problem) return problem;
+    }
+  }
+  if (TYPES.object(value)) {
+    // Own properties only ("__proto__" is not a declared input).
+    for (const key of s.required ?? []) if (!Object.hasOwn(value, key) || value[key] === undefined) return `\`${key}\` is required`;
+    for (const [key, v] of Object.entries(value)) {
+      const p = s.properties && Object.hasOwn(s.properties, key) ? s.properties[key] : undefined;
+      if (!p && s.additionalProperties === false) return `\`${key}\` is not an input of this tool`;
+      const problem = p && v !== undefined ? check(p, v, `\`${key}\``) : "";
+      if (problem) return problem;
+    }
+  }
+  return "";
+}
+
+/** Wraps `run` in the standard contract: parsed and checked input, `{ok, data}` or `{ok: false, error}`. */
+const contract = (inputSchema, run) => async (raw, client) => {
+  let args;
+  try {
+    // Omitted input is {} (as in the spec); anything that is not an object is refused below.
+    args = typeof raw === "string" ? JSON.parse(raw || "{}") : raw === undefined ? {} : raw;
+  } catch {
+    return fail("INVALID_INPUT", "the input is not JSON");
+  }
+  try {
+    const problem = TYPES.object(args) ? check(inputSchema, args) : "the input must be an object";
+    if (problem) return fail("INVALID_INPUT", problem);
+    const out = envelope({ ok: true, data: (await run(args, client)) ?? null });
+    return out.length > LIMITS.OUTPUT_MAX
+      ? fail("RESULT_TOO_LARGE", `the result has ${out.length} chars`, `Return at most ${LIMITS.OUTPUT_MAX}: page it.`)
+      : out;
+  } catch (e) {
+    return fail(e?.code in CODES ? e.code : "UNAVAILABLE", String(e?.message ?? e));
+  }
+};
+
+const warn = (name, message) => console.warn(`webmcpx: tool "${name}": ${message}`);
+
+function register(definition, signal) {
+  const mc = context();
+  const { name, description } = definition;
+  if (!NAME.test(name ?? "")) warn(name, "names are 1-128 of A-Z a-z 0-9 _ . -");
+  else if (name.length > LIMITS.NAME_WARN) warn(name, `keep names under ${LIMITS.NAME_WARN} chars`);
+  if (!description) warn(name, "say what it does and when to use it in `description`");
+  else if (description.length > LIMITS.DESCRIPTION_WARN) warn(name, `keep the description under ${LIMITS.DESCRIPTION_WARN} chars`);
+  if (++count === LIMITS.TOOLS_WARN + 1) console.warn(`webmcpx: more than ${LIMITS.TOOLS_WARN} tools on one page`);
+  if (typeof mc?.registerTool !== "function") return Promise.resolve(false);
+  signal.addEventListener("abort", () => count--, { once: true });
+  // Never assign onto `mc`: some agent browsers expose a frozen object (webmcp#293).
+  return mc.registerTool(definition, { signal }).then(
+    () => true,
+    (e) => (warn(name, e?.message ?? e), false),
+  );
+}
+
+/**
+ * Registers one of your own tools. `run(input)` returns the data (or throws; an error with a webmcpx
+ * `code` keeps it). A no-op where WebMCP is missing.
+ * @param {import("./index").ToolDefinition} definition
+ * @returns {{ready: Promise<boolean>, dispose(): void}}
+ */
+export function tool({ name, description, input, inputSchema = schema(input), run, readOnly, acts, untrusted, signal } = {}) {
+  const controller = new AbortController();
+  if (signal?.aborted) return { ready: Promise.resolve(false), dispose() {} };
+  signal?.addEventListener("abort", () => controller.abort(), { once: true });
+  const ready = register(
+    {
+      name,
+      description,
+      inputSchema,
+      annotations: {
+        ...(readOnly && { readOnlyHint: true }),
+        ...(acts && { consequentialHint: true }),
+        ...(untrusted && { untrustedContentHint: true }),
+      },
+      execute: contract(inputSchema, run),
+    },
+    controller.signal,
+  );
+  return { ready, dispose: () => controller.abort() };
+}
+
+const TOOL_ATTRIBUTES = ["toolname", "tooldescription", "toolautosubmit"];
+// What a control contributes to the schema (option values included).
+const CONTROL_ATTRIBUTES = ["name", "type", "required", "disabled", "min", "max", "multiple", "value", "toolparamdescription", "method"];
+const FORMATS = { email: "email", url: "uri", date: "date", "datetime-local": "date-time", time: "time" };
+const SKIPPED = /^(submit|button|reset|image|file|password|hidden)$/;
+
+/** A form's input schema, per the declarative explainer: control `name`s, `toolparamdescription`s. */
+export function formSchema(form) {
+  const properties = {};
+  const required = [];
+  for (const el of form.elements) {
+    const { name, type } = el;
+    if (!name || el.disabled || SKIPPED.test(type) || !("value" in el) || el.tagName === "BUTTON") continue;
+    let p;
+    if (type === "checkbox") p = { type: "boolean" };
+    else if (type === "radio") (p = properties[name] ?? { type: "string", enum: [] }).enum.push(el.value);
+    else if (el.tagName === "SELECT") {
+      p = { type: "string", enum: [...el.options].map((o) => o.value) };
+      if (el.multiple) p = { type: "array", items: p };
+    } else if (type === "number" || type === "range") {
+      p = { type: "number", ...(el.min && { minimum: +el.min }), ...(el.max && { maximum: +el.max }) };
+    } else p = { type: "string", ...(FORMATS[type] && { format: FORMATS[type] }) };
+    const description =
+      el.getAttribute("toolparamdescription") || el.labels?.[0]?.textContent.trim() || el.getAttribute("placeholder");
+    if (description) p.description = description;
+    properties[name] = p;
+    if (el.required && !required.includes(name)) required.push(name);
+  }
+  return { type: "object", properties, ...(required.length && { required }) };
+}
+
+function fill(form, args) {
+  for (const [name, value] of Object.entries(args)) {
+    const field = form.elements.namedItem(name);
+    for (const el of field instanceof Element ? [field] : [...(field ?? [])]) {
+      if (el.type === "checkbox") el.checked = Boolean(value);
+      else if (el.type === "radio") el.checked = el.value === String(value);
+      else if (el.multiple) for (const o of el.options) o.selected = [].concat(value).includes(o.value);
+      else el.value = String(value);
+      // Frameworks listen for these, not for property writes.
+      el.dispatchEvent(new Event("input", { bubbles: true }));
+      el.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+  }
+}
+
+/** Fills the form; with `toolautosubmit`, submits it and returns what `respondWith()` gave. */
+function runForm(form) {
+  return async (args) => {
+    fill(form, args);
+    const invalid = [...form.elements].find((el) => el.willValidate && !el.checkValidity());
+    if (invalid) throw Object.assign(new Error(`\`${invalid.name}\`: ${invalid.validationMessage}`), { code: "INVALID_INPUT" });
+    if (!form.hasAttribute("toolautosubmit")) {
+      form.querySelector("[type=submit], button:not([type])")?.focus();
+      return { submitted: false, next: "Ask the user to review the form and submit it." };
+    }
+    let response;
+    // The explainer's SubmitEvent#agentInvoked and #respondWith(), for the page's submit handlers.
+    const mark = (event) => {
+      if (event.target !== form) return;
+      Object.defineProperties(event, {
+        agentInvoked: { value: true },
+        respondWith: { value: (promise) => void (response = promise) },
+      });
+    };
+    addEventListener("submit", mark, true);
+    try {
+      form.requestSubmit();
+    } finally {
+      removeEventListener("submit", mark, true);
+    }
+    return response ? await response : { submitted: true, next: "The page may navigate: read it for the result." };
+  };
+}
+
+/**
+ * Exposes every `<form toolname>` of the page as a tool, and follows them as the page changes. Does
+ * nothing where WebMCP is missing or where the browser runs the declarative API itself.
+ * @returns {{dispose(): void}}
+ */
+export function forms() {
+  const doc = globalThis.document;
+  if (!doc || typeof context()?.registerTool !== "function" || "toolName" in HTMLFormElement.prototype) {
+    return { dispose() {} };
+  }
+  const live = new Map();
+  // A form's tool is its attributes plus the schema of its controls: re-registered when either changes.
+  const key = (form) =>
+    JSON.stringify([...TOOL_ATTRIBUTES.map((a) => form.getAttribute(a)), form.method, formSchema(form)]);
+  const sync = () => {
+    for (const [form, entry] of live) {
+      if (!form.isConnected || !form.hasAttribute("toolname") || entry.key !== key(form)) {
+        entry.controller.abort();
+        live.delete(form);
+      }
+    }
+    for (const form of doc.querySelectorAll("form[toolname]")) {
+      if (live.has(form)) continue;
+      const controller = new AbortController();
+      const inputSchema = formSchema(form);
+      live.set(form, { key: key(form), controller });
+      register(
+        {
+          // Names allow [A-Za-z0-9_.-]: "Search flights" becomes "Search_flights".
+          name: form.getAttribute("toolname").trim().replace(/[^A-Za-z0-9_.-]+/g, "_"),
+          description: form.getAttribute("tooldescription") ?? "",
+          inputSchema,
+          annotations: form.method === "get" ? { readOnlyHint: true } : { consequentialHint: true },
+          execute: contract(inputSchema, runForm(form)),
+        },
+        controller.signal,
+      );
+    }
+  };
+  sync();
+  const observer = new MutationObserver(sync);
+  observer.observe(doc.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: [...TOOL_ATTRIBUTES, ...CONTROL_ATTRIBUTES],
+  });
+  return {
+    dispose() {
+      observer.disconnect();
+      for (const { controller } of live.values()) controller.abort();
+      live.clear();
+    },
+  };
+}

package/src/vue.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "./index.js";
+
+/** Registers the tool while the component is mounted. */
+export function useTool(definition: ToolDefinition | (() => ToolDefinition) | { value: ToolDefinition }): void;

package/src/vue.js

@@ -0,0 +1,11 @@
+// Vue 2.7 and 3: `useTool(definition)` registers the tool for the component's life. Pass a getter or a
+// ref to re-register when the definition changes.
+import { unref, watchEffect } from "vue";
+import { tool } from "./tool.js";
+
+export function useTool(definition) {
+  watchEffect((onCleanup) => {
+    const current = typeof definition === "function" ? definition() : unref(definition);
+    onCleanup(tool(current).dispose);
+  });
+}