webmcpx 0.2.0 → 0.2.1

package/README.md

@@ -1,14 +1,17 @@
 # webmcpx
 
-**Make your site agent-ready with one script tag.** webmcpx registers standard
+**Make your site agent-ready in two steps.** webmcpx registers standard
 [WebMCP](https://webmachinelearning.github.io/webmcp/) tools on any page, so AI agents in the browser
 call a function instead of reading and clicking through the page.
 
+**Step 1, on your site.** Paste this before `</body>`:
+
 ```html
 <script type="module" src="https://cdn.jsdelivr.net/npm/webmcpx@0.2/src/auto.js"></script>
 ```
 
-**See it work in any agent, today.** Give your coding agent the WebMCP tools of every page it opens:
+**Step 2, in your agent.** Give your agent the WebMCP tools of every page it opens (the ChatGPT desktop
+app and the Codex app skip this step: they call WebMCP tools natively):
 
 ```sh
 claude mcp add webmcpx -- npx -y webmcpx mcp     # Codex: codex mcp add webmcpx -- npx -y webmcpx mcp
@@ -49,10 +52,10 @@ the script tag adds where the browser doesn't have it yet. With `toolautosubmit`
 `event.agentInvoked` and can answer with `event.respondWith(...)`.
 
 ```html
-<form toolname="search_flights" tooldescription="Search flights by route and date." action="/search">
-  <input name="from" required toolparamdescription="Departure airport, e.g. GRU">
-  <input name="to" required toolparamdescription="Arrival airport, e.g. LIS">
-  <input name="date" type="date" required>
+<form toolname="add_to_cart" tooldescription="Add a product to the cart by SKU." action="/cart" method="post" toolautosubmit>
+  <input name="sku" required toolparamdescription="Product SKU, e.g. MUG-01">
+  <input name="qty" type="number" min="1" toolparamdescription="How many (default 1)">
+  <button>Add to cart</button>
 </form>
 ```
 

package/agent/browser.js

@@ -51,6 +51,8 @@ export class Cdp {
   #id = 0;
   #pending = new Map();
   #listeners = new Set();
+  #closed = false;
+  #onClose = new Set();
 
   static async connect(url) {
     const ws = new WebSocket(url);
@@ -74,17 +76,39 @@ export class Cdp {
       if (msg.error) pending?.reject(new Error(msg.error.message));
       else pending?.resolve(msg.result);
     });
-    ws.addEventListener("close", () => {
-      for (const { reject } of this.#pending.values()) reject(new Error("the browser connection closed"));
-      this.#pending.clear();
-    });
+    ws.addEventListener("close", () => this.#shut());
+    ws.addEventListener("error", () => this.#shut());
+  }
+
+  /** Once closed (the browser quit or crashed), every pending and later call fails at once. */
+  #shut() {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const { reject } of this.#pending.values()) reject(new Error("the browser connection closed"));
+    this.#pending.clear();
+    for (const listener of this.#onClose) listener();
+  }
+
+  get closed() {
+    return this.#closed;
+  }
+
+  /** Calls `listener` once the connection closes. */
+  onClose(listener) {
+    this.#onClose.add(listener);
   }
 
   send(method, params = {}, sessionId) {
+    if (this.#closed) return Promise.reject(new Error("the browser connection closed"));
     const id = ++this.#id;
     return new Promise((resolve, reject) => {
       this.#pending.set(id, { resolve, reject });
-      this.#ws.send(JSON.stringify({ id, method, params, ...(sessionId && { sessionId }) }));
+      try {
+        this.#ws.send(JSON.stringify({ id, method, params, ...(sessionId && { sessionId }) }));
+      } catch (e) {
+        this.#pending.delete(id);
+        reject(e);
+      }
     });
   }
 
@@ -96,6 +120,7 @@ export class Cdp {
 
   close() {
     this.#ws.close();
+    this.#shut();
   }
 }
 
@@ -122,10 +147,24 @@ export async function launch({ headed = false, executable = findBrowser() } = {}
   ];
   const child = spawn(executable, args, { stdio: ["ignore", "ignore", "pipe"] });
   const cleanup = () => rmSync(profile, { recursive: true, force: true });
-  const kill = () => child.kill();
+  // Also runs on process exit (signals included, see bin/webmcpx.js): never leave a browser or its profile.
+  const kill = () => {
+    child.kill();
+    try {
+      cleanup();
+    } catch {
+      // still in use: removed when the browser exits
+    }
+  };
   process.once("exit", kill);
   child.once("exit", cleanup);
 
+  // A browser that fails to start (no DevTools line, no connection) must not be left running.
+  const fail = (e) => {
+    process.removeListener("exit", kill);
+    kill();
+    throw e;
+  };
   const endpoint = await new Promise((resolve, reject) => {
     let log = "";
     const timer = setTimeout(() => reject(new Error(`${executable} did not start within 30 s`)), 30_000);
@@ -146,8 +185,13 @@ export async function launch({ headed = false, executable = findBrowser() } = {}
       clearTimeout(timer);
       reject(new Error(`${executable} exited (${code}) before it was ready: ${log.trim().slice(-500)}`));
     });
+  }).catch(fail);
+  const cdp = await Cdp.connect(endpoint).catch(fail);
+  // The connection dropped but Chrome may still run: it is ours, so it goes too.
+  cdp.onClose(() => {
+    process.removeListener("exit", kill);
+    kill();
   });
-  const cdp = await Cdp.connect(endpoint);
   return {
     cdp,
     close() {

package/agent/mcp.js

@@ -43,22 +43,58 @@ const CALL = {
   annotations: { openWorldHint: true },
 };
 
+/** Who a tool is across refreshes: standard, or the page's (origin, owning frame and name). */
+const keyOf = (t) => (t.standard ? `standard ${t.name}` : `${t.origin ?? ""} ${t.owner ?? "0"} ${t.name}`);
+
 /**
- * Gives each tool a unique MCP name, in list order: MCP allows [A-Za-z0-9_-] and 64 characters, WebMCP
- * also "." and 128, and two frames can register the same name. Clashes get "_2", "_3"...
- * @returns {{name: string, tool: import("./session.js").Tool}[]}
+ * Gives each tool a unique MCP name: MCP allows [A-Za-z0-9_-] and 64 characters, WebMCP also "." and
+ * 128, and two frames can register the same name. Clashes get "_2", "_3"...
+ * `previous` (key -> names, in list order) carries names over when as many tools share that key as
+ * before. When that count changes, same-named tools in different frames can't be told apart, so their old
+ * names are retired for the session (`retired`, updated here). `reserved` (name -> key, every name handed out this session; updated here) lets a
+ * name come back only to the same key: a name a client already has never runs a different tool.
+ * @returns {{name: string, id: string, tool: import("./session.js").Tool}[]}
  */
-export function named(tools) {
+export function named(tools, previous = new Map(), reserved = new Map(), retired = new Set()) {
+  const ids = tools.map(keyOf);
+  const count = (id) => ids.filter((x) => x === id).length;
+  // Same-named tools whose number changed can't be matched to their old names: retire those names for
+  // good. A lone tool that leaves and comes back is the same tool (same origin and name): it keeps its name.
+  for (const [id, names] of previous) {
+    if (names.length !== count(id) && Math.max(names.length, count(id)) > 1) for (const n of names) retired.add(n);
+  }
   const used = new Set([OPEN.name, CALL.name]);
-  return tools.map((tool) => {
-    const base = tool.name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "tool";
-    let name = base;
-    for (let n = 2; used.has(name); n++) name = `${base.slice(0, 64 - String(n).length - 1)}_${n}`;
+  const free = (name, id) => !used.has(name) && !retired.has(name) && (reserved.get(name) ?? id) === id;
+  const rank = new Map();
+  const kept = ids.map((id) => {
+    const i = rank.get(id) ?? 0;
+    rank.set(id, i + 1);
+    const name = previous.get(id)?.[i];
+    if (!name || !free(name, id)) return undefined;
     used.add(name);
-    return { name, tool };
+    return name;
+  });
+  const entries = tools.map((tool, i) => {
+    let name = kept[i];
+    if (!name) {
+      const base = tool.name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "tool";
+      name = base;
+      for (let n = 2; !free(name, ids[i]); n++) name = `${base.slice(0, 64 - String(n).length - 1)}_${n}`;
+      used.add(name);
+    }
+    return { name, id: ids[i], tool };
   });
+  for (const e of entries) reserved.set(e.name, e.id);
+  return entries;
 }
 
+/** What `named` needs from the last list: each key's names, in order. */
+export const carry = (entries) => {
+  const map = new Map();
+  for (const e of entries) map.set(e.id, [...(map.get(e.id) ?? []), e.name]);
+  return map;
+};
+
 /** MCP wants an object schema at the root; WebMCP schemas may leave `type` out. */
 export function objectSchema(schema) {
   if (schema && typeof schema === "object" && !Array.isArray(schema)) {
@@ -93,11 +129,10 @@ function asMcp({ name, tool }) {
 }
 
 /** A short, readable summary of an opened page for the model. */
-export function describe({ url, title, tools }) {
+export function describe({ url, title, tools }, entries = tools && named(tools)) {
   if (tools === null) {
     return `Opened ${url}, but it is not a secure context, so it has no WebMCP. Use https:// or localhost.`;
   }
-  const entries = named(tools);
   const own = entries.filter((e) => !e.tool.standard);
   const lines = [`Opened "${title}" (${url}).`, ""];
   lines.push(own.length ? `The site's own WebMCP tools (${own.length}):` : "The site registers no WebMCP tools of its own.");
@@ -113,12 +148,14 @@ export function describe({ url, title, tools }) {
 /** Runs the server on stdin/stdout until stdin closes. Logs go to stderr only. */
 export async function serve(options = {}, { input = process.stdin, output = process.stdout } = {}) {
   let entries = [];
+  const reserved = new Map();
+  const retired = new Set();
   let initialized = false;
   const write = (msg) => output.write(`${JSON.stringify({ jsonrpc: "2.0", ...msg })}\n`);
   // Replaces the tool list and tells the client when what it would see changed.
   const update = (tools) => {
     const before = JSON.stringify(entries.map(asMcp));
-    entries = named(tools);
+    entries = named(tools, carry(entries), reserved, retired);
     if (initialized && JSON.stringify(entries.map(asMcp)) !== before) write({ method: "notifications/tools/list_changed" });
   };
   const session = new Session({
@@ -132,11 +169,17 @@ export async function serve(options = {}, { input = process.stdin, output = proc
     if (name === OPEN.name) {
       const page = await session.goto(args.url);
       update(page.tools ?? []);
-      return text(describe(page));
+      return text(describe(page, entries));
     }
     const wanted = name === CALL.name ? String(args.name ?? "") : name;
+    // call_page_tool also takes the page's own name, but only when it is unambiguous and is not a name we
+    // gave (or retired) for another tool.
+    const byPageName = entries.filter((e) => e.tool.name === wanted);
     const entry =
-      entries.find((e) => e.name === wanted) ?? (name === CALL.name ? entries.find((e) => e.tool.name === wanted) : undefined);
+      entries.find((e) => e.name === wanted) ??
+      (name === CALL.name && byPageName.length === 1 && !retired.has(wanted) && (reserved.get(wanted) ?? byPageName[0].id) === byPageName[0].id
+        ? byPageName[0]
+        : undefined);
     if (!entry) return text(`Unknown tool "${wanted}". Call open_page first, then use the tools it lists.`, true);
     const out = await session.call(entry.tool, name === CALL.name ? args.input : args);
     return mcpResult(out) ?? text(out, failed(out));
@@ -186,5 +229,5 @@ export async function serve(options = {}, { input = process.stdin, output = proc
       (e) => msg.id !== undefined && write({ id: msg.id, error: { code: e.code ?? -32603, message: e.message } }),
     );
   }
-  session.close();
+  await session.close();
 }

package/agent/page.js

@@ -51,6 +51,20 @@ function summarize() {
       return undefined;
     }
   };
+  // The frame that owns each tool (the spec's RegisteredTool.window), as a number that stays the same
+  // while the page is open: same-named tools in two frames are two tools.
+  // Frame ids are scoped to this document: after a navigation, a frame is never mistaken for an older
+  // one. The page itself is 0, so a site's own tools keep their names from visit to visit.
+  const owners = (globalThis.__webmcpxOwners ??= { ids: new WeakMap(), next: 1, doc: Math.random().toString(36).slice(2) });
+  const owner = (w) => {
+    if (!w || w === window) return "0";
+    try {
+      if (!owners.ids.has(w)) owners.ids.set(w, `${owners.doc}.${owners.next++}`);
+      return owners.ids.get(w);
+    } catch {
+      return "?";
+    }
+  };
   return this.map((t, index) => ({
     index,
     name: t.name,
@@ -58,13 +72,22 @@ function summarize() {
     inputSchema: parse(t.inputSchema),
     annotations: { ...(t.annotations ?? {}) },
     origin: t.origin,
+    owner: owner(t.window),
   }));
 }
 
-// Called on the same array: runs one descriptor. executeTool() returns the result JSON-serialized; a tool
-// that returned a string (like the webmcpx envelope) comes back as a JSON string literal: unwrap it once.
-async function execute(index, input) {
-  const out = await document.modelContext.executeTool(this[index], input);
+// Called on the same array: runs one descriptor, cancellable through `cancel` below. executeTool() returns
+// the result JSON-serialized; a tool that returned a string (like the webmcpx envelope) comes back as a
+// JSON string literal: unwrap it once.
+async function execute(index, input, call) {
+  const controller = new AbortController();
+  (this.__webmcpxCalls ??= new Map()).set(call, controller);
+  let out;
+  try {
+    out = await document.modelContext.executeTool(this[index], input, { signal: controller.signal });
+  } finally {
+    this.__webmcpxCalls.delete(call);
+  }
   let value = out;
   try {
     value = typeof out === "string" ? JSON.parse(out) : out;
@@ -74,9 +97,15 @@ async function execute(index, input) {
   return typeof value === "string" ? value : JSON.stringify(value ?? null);
 }
 
+function cancel(call) {
+  this.__webmcpxCalls?.get(call)?.abort();
+}
+
 const GROUP = "webmcpx-tools";
 const LOAD_TIMEOUT = 30_000;
 const CALL_TIMEOUT = 60_000;
+/** How long a cancellation may take before the tab counts as frozen. */
+const CANCEL_WAIT = 2_000;
 const SETTLE = { min: 400, max: 3_000, every: 200 };
 // Unref'd: a pending timeout must never keep the CLI alive after its work is done.
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref());
@@ -85,32 +114,49 @@ const timeout = (ms, what) =>
     setTimeout(() => reject(new Error(`${what} took longer than ${ms / 1000} s`)), ms).unref();
   });
 
-/** Whether an error means the page navigated or the tool list was replaced since it was read. */
-export const stale = (e) =>
-  /Could not find object|Cannot find context|context was destroyed|Inspected target navigated/i.test(e?.message);
+/** The tool's list is gone (the page navigated since it was read): the call never started. */
+export const stale = (e) => /Could not find object|Cannot find context/i.test(e?.message);
+/** The page navigated while the tool ran: it may have done its work. */
+const interrupted = (e) => /context was destroyed|Inspected target navigated|Execution context/i.test(e?.message);
 
 export class Page {
   #cdp;
   #session;
+  #target;
+  #unsubscribe;
   #onChange;
+  #calls = 0;
+  /** Set when the page stopped answering: the session must not use this tab again. */
+  broken = false;
+  #callTimeout = CALL_TIMEOUT;
   #loads = new Set();
   #handles = [];
   #debounce;
 
   /** Opens a new tab. `onChange()` fires when the page's tools may have changed on their own. */
-  static async create(cdp, { onChange = () => {} } = {}) {
+  /** `callTimeout` (ms) bounds one tool call; tests shorten it. */
+  static async create(cdp, { onChange = () => {}, callTimeout = CALL_TIMEOUT } = {}) {
     const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
     const { sessionId } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
-    const page = new Page(cdp, sessionId, onChange);
+    const page = new Page(cdp, sessionId, targetId, onChange);
+    page.#callTimeout = callTimeout;
     await page.#init();
     return page;
   }
 
-  constructor(cdp, session, onChange) {
+  constructor(cdp, session, target, onChange) {
     this.#cdp = cdp;
     this.#session = session;
+    this.#target = target;
     this.#onChange = onChange;
-    cdp.on((msg) => msg.sessionId === session && this.#event(msg));
+    this.#unsubscribe = cdp.on((msg) => msg.sessionId === session && this.#event(msg));
+  }
+
+  /** Closes this tab (in a browser we attached to, it is the only thing we opened there). */
+  async close() {
+    clearTimeout(this.#debounce);
+    this.#unsubscribe();
+    await this.#cdp.send("Target.closeTarget", { targetId: this.#target }).catch(() => {});
   }
 
   #send(method, params) {
@@ -202,26 +248,47 @@ export class Page {
     if (this.#handles.length > 50) {
       this.#send("Runtime.releaseObject", { objectId: this.#handles.shift() }).catch(() => {});
     }
-    const count = new Map();
-    for (const t of list.value) count.set(`${t.origin} ${t.name}`, (count.get(`${t.origin} ${t.name}`) ?? 0) + 1);
-    return list.value.map((tool) => ({
-      ...tool,
-      list: result.objectId,
-      unique: count.get(`${tool.origin} ${tool.name}`) === 1,
-    }));
+    return list.value.map((tool) => ({ ...tool, list: result.objectId }));
   }
 
-  /** Runs a tool on the list it came from; resolves with its result text. */
+  /**
+   * Runs a tool on the list it came from; resolves with its result text. A tool past the time limit is
+   * cancelled (its AbortSignal fires); a page that navigates mid-call reports that the tool may have run.
+   */
   async call(tool, input) {
+    const call = ++this.#calls;
     const run = this.#send("Runtime.callFunctionOn", {
       objectId: tool.list,
       functionDeclaration: execute.toString(),
-      arguments: [{ value: tool.index }, { value: input ?? {} }],
+      arguments: [{ value: tool.index }, { value: input ?? {} }, { value: call }],
       awaitPromise: true,
       returnByValue: true,
       userGesture: true,
     });
-    const { result, exceptionDetails } = await Promise.race([run, timeout(CALL_TIMEOUT, "the tool")]);
+    let reply;
+    try {
+      reply = await Promise.race([run, timeout(this.#callTimeout, "the tool")]);
+    } catch (e) {
+      if (stale(e)) throw e;
+      if (interrupted(e)) {
+        throw new Error(`the page navigated while "${tool.name}" ran: it may have done its work, so check before calling it again`);
+      }
+      if (!/took longer than/.test(e?.message)) throw e;
+      // Ask the tool to stop. A page whose script is stuck can't even take that: then the tab is broken,
+      // and the session replaces it (see Session.call).
+      const cancelled = this.#send("Runtime.callFunctionOn", {
+        objectId: tool.list,
+        functionDeclaration: cancel.toString(),
+        arguments: [{ value: call }],
+      });
+      const answered = await Promise.race([cancelled.then(() => true, () => true), wait(CANCEL_WAIT).then(() => false)]);
+      if (!answered) {
+        this.broken = true;
+        throw new Error(`"${tool.name}" took longer than ${this.#callTimeout / 1000} s and froze the page; it may have partly run`);
+      }
+      throw new Error(`"${tool.name}" took longer than ${this.#callTimeout / 1000} s and was cancelled; it may have partly run`);
+    }
+    const { result, exceptionDetails } = reply;
     if (exceptionDetails) throw new Error(describeException(exceptionDetails));
     return result.value;
   }
@@ -234,4 +301,4 @@ export class Page {
 
 const describeException = (d) => d.exception?.description?.split("\n")[0] ?? d.text;
 
-/** @typedef {{index: number, list: string, unique: boolean, name: string, description: string, inputSchema?: object, annotations: Record<string, boolean>, origin?: string}} PageTool */
+/** @typedef {{index: number, list: string, name: string, description: string, inputSchema?: object, annotations: Record<string, boolean>, origin?: string, owner?: string}} PageTool */

package/agent/session.js

@@ -9,18 +9,30 @@ export class Session {
   #browser;
   #page;
   #ready;
+  #closed = false;
   #queue = Promise.resolve();
 
-  /** @param {{headed?: boolean, browser?: string, cdp?: string, onChange?: () => void}} options */
+  /** @param {{headed?: boolean, browser?: string, cdp?: string, onChange?: () => void, callTimeout?: number}} options */
   constructor(options = {}) {
     this.#options = options;
   }
 
   #start() {
+    if (this.#closed) return Promise.reject(new Error("the session is closed"));
     this.#ready ??= (async () => {
-      const { cdp, headed, browser, onChange } = this.#options;
-      this.#browser = cdp ? await attach(cdp) : await launch({ headed, executable: browser });
-      return Page.create(this.#browser.cdp, { onChange });
+      const { cdp, headed, browser, onChange, callTimeout } = this.#options;
+      const opened = cdp ? await attach(cdp) : await launch({ headed, executable: browser });
+      // Closed while the browser was starting: shut it instead of leaving it running.
+      if (this.#closed) {
+        opened.close();
+        throw new Error("the session is closed");
+      }
+      this.#browser = opened;
+      // A browser that quits or crashes is started again on the next page.
+      opened.cdp.onClose(() => {
+        if (this.#browser === opened) [this.#browser, this.#ready, this.#page] = [];
+      });
+      return Page.create(opened.cdp, { onChange, callTimeout });
     })().catch((e) => {
       this.#ready = undefined;
       throw e;
@@ -49,7 +61,7 @@ export class Session {
     return this.#serial(async () => (this.#page ? withStandard((await this.#page.tools()) ?? []) : []));
   }
 
-  /** Calls a tool from the latest list; a page tool whose list went stale is found again by name and origin. */
+  /** Calls a tool from a list the page gave; one from a page that has since navigated is refused. */
   call(tool, input) {
     return this.#serial(async () => {
       if (!this.#page) throw new Error("no page is open yet: call open_page first");
@@ -58,18 +70,29 @@ export class Session {
       try {
         return await page.call(tool, input);
       } catch (e) {
-        if (!stale(e)) throw e;
-        // The document the tool was listed in is gone: run the same tool in the new one only when no
-        // other tool shares its name and origin there or then; otherwise refuse rather than guess.
-        const now = ((await page.tools()) ?? []).filter((t) => t.name === tool.name && t.origin === tool.origin);
-        const again = tool.unique && now.length === 1 ? now[0] : undefined;
-        if (!again) throw new Error(`the page changed and no longer has the tool "${tool.name}": call open_page again`);
-        return page.call(again, input);
+        // A frozen page can't be used again: drop the browser (or, attached, our tab); the next page
+        // starts fresh instead of waiting on it forever.
+        if (page.broken) await this.#reset();
+        // The tool's list is gone only when the page navigated: never guess which new tool is "the same".
+        if (stale(e)) throw new Error(`the page changed since "${tool.name}" was listed: open it again or use the new tools`);
+        throw e;
       }
     });
   }
 
-  close() {
+  async #reset() {
+    const [browser, ready] = [this.#browser, this.#ready];
+    [this.#browser, this.#ready, this.#page] = [];
+    const page = await ready?.catch(() => undefined);
+    await Promise.race([page?.close(), new Promise((resolve) => setTimeout(resolve, 2_000).unref())]);
+    browser?.close();
+  }
+
+  /** Closes our tab and the browser (or only our tab's connection, in a browser we attached to). */
+  async close() {
+    this.#closed = true;
+    const page = await this.#ready?.catch(() => undefined);
+    await page?.close();
     this.#browser?.close();
   }
 }

package/bin/webmcpx.js

@@ -91,6 +91,12 @@ function printTools(page) {
   console.log(dim(`\nTry one: npx webmcpx call ${page.url} search_page '{"query": "..."}'`));
 }
 
+// An MCP client stops its server with a signal: exit through process.exit, so the browser we started
+// is killed by its exit hook instead of being orphaned.
+for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) {
+  process.once(signal, () => process.exit(code));
+}
+
 async function main() {
   const { values, positionals } = parse(process.argv.slice(2));
   const [command, ...rest] = positionals;
@@ -142,7 +148,7 @@ async function main() {
     console.log(pretty);
     if (failed(out)) process.exitCode = 1;
   } finally {
-    session.close();
+    await session.close();
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webmcpx",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Standard WebMCP tools for any website, and an MCP server that gives any agent the WebMCP tools of the pages it opens.",
   "type": "module",
   "license": "MIT",

package/src/auto.js

@@ -1,6 +1,5 @@
 // Drop-in: <script type="module" src="https://cdn.jsdelivr.net/npm/webmcpx@0.2/src/auto.js"></script>
-// Registers the standard tools, and turns every <form toolname> into a tool (that code loads only
-// on pages that have one).
+// Standard tools, plus <form toolname> as tools (that code loads only where such a form exists).
 import { register } from "./loader.js";
 
 register();

package/src/loader.js

@@ -1,5 +1,4 @@
-// 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.
+// The standard tools: DOM and registerTool() here, text work in WebAssembly (loaded on first call).
 import { CODES, TOOLS } from "./generated.js";
 
 const DEFAULT_TOOLS = ["get_page_context", "search_page", "fetch_as_markdown"];
@@ -46,16 +45,22 @@ export function readPage(what, root) {
     };
   }
   const skipped = (el) => SKIP.has(el.tagName) || el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true";
+  // Text without hidden parts; an element with no block inside is one block ("Free <b>delivery</b>").
+  const textOf = (el) =>
+    [...el.childNodes].map((n) => (n.nodeType === 3 ? n.data : n.nodeType === 1 && !skipped(n) ? textOf(n) : "")).join("");
+  const BLOCKS = Object.keys(KINDS) + ",div,section,article,main,ul,ol,dl,table,tr,form,header,figure,details";
   let out = "";
   let anchor = "";
+  const add = (kind, s) => text(s) && (out += kind + FIELD + s + FIELD + anchor + RECORD);
   const visit = (el) => {
-    for (const child of el.children) {
-      if (skipped(child)) continue;
+    for (const child of el.childNodes) {
+      if (child.nodeType === 3) add("p", child.data);
+      if (child.nodeType !== 1 || 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;
+      const row = child.tagName === "TR" && [...child.children].filter((c) => !skipped(c)).map((c) => text(textOf(c))).join(" | ");
+      const kind = row ? "p" : KINDS[child.tagName] ?? (!child.querySelector(BLOCKS) && "p");
+      if (kind) add(kind, row || textOf(child));
       else visit(child);
     }
   };
@@ -99,11 +104,7 @@ const guard = (run) => async (input, client) => {
   }
 };
 
-/**
- * Registers webmcpx standard tools on the current document.
- * @param {import("./index").Options} [options]
- * @returns {Promise<import("./index").Registration>}
- */
+/** Registers the standard tools (types: index.d.ts). */
 export async function register(options = {}) {
   const mc = globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
   const controller = new AbortController();

package/src/tool.js

@@ -1,6 +1,5 @@
-// 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.
+// Your own tools, with the standard tools' contract, and <form toolname> (webmcp's
+// declarative-api-explainer.md) where the browser lacks it.
 import { CODES, LIMITS } from "./generated.js";
 
 const context = () => globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
@@ -70,7 +69,7 @@ function check(s, value, at = "input") {
   return "";
 }
 
-/** Wraps `run` in the standard contract: parsed and checked input, `{ok, data}` or `{ok: false, error}`. */
+/** `run` in the standard contract: checked input, `{ok, data}` or `{ok: false, error}`. */
 const contract = (inputSchema, run) => async (raw, client) => {
   let args;
   try {
@@ -110,12 +109,7 @@ function register(definition, signal) {
   );
 }
 
-/**
- * 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}}
- */
+/** Registers one of your own tools (types and docs: index.d.ts). */
 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() {} };
@@ -139,7 +133,7 @@ export function tool({ name, description, input, inputSchema = schema(input), ru
 
 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 CONTROL_ATTRIBUTES = ["name", "type", "required", "disabled", "readonly", "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)$/;
 
@@ -149,9 +143,12 @@ export function formSchema(form) {
   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;
+    if (!fillable(el)) continue;
     let p;
-    if (type === "checkbox") p = { type: "boolean" };
+    // Several checkboxes with one name: a set of choices.
+    if (type === "checkbox" && [...form.elements].filter((e) => e.name === name && fillable(e)).length > 1) {
+      (p = properties[name] ?? { type: "array", items: { enum: [] } }).items.enum.push(el.value);
+    } else 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) };
@@ -160,22 +157,31 @@ export function formSchema(form) {
       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");
+      el.getAttribute("toolparamdescription") || (!p.items && (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 }) };
+  // Only fields it shows: never hidden, password or disabled ones.
+  return { type: "object", properties, ...(required.length && { required }), additionalProperties: false };
 }
 
+/** A control a user could edit: named, enabled (fieldsets too), not readonly, hidden, password or a file. */
+const fillable = (el) =>
+  el.name && !el.matches(":disabled, [readonly]") && !SKIPPED.test(el.type) && "value" in el && el.tagName !== "BUTTON";
+
 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);
+    for (const el of (field instanceof Element ? [field] : [...(field ?? [])]).filter(fillable)) {
+      // Click / native setter: frameworks (React) ignore plain property writes.
+      const on = el.type === "checkbox" ? ([].concat(value).includes(el.value) || value === true) : el.value === String(value);
+      if (el.type === "checkbox" || el.type === "radio") {
+        if (el.checked !== on) el.click();
+        continue;
+      }
+      if (el.multiple) for (const o of el.options) o.selected = [].concat(value).includes(o.value);
+      else Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), "value").set.call(el, String(value));
       // Frameworks listen for these, not for property writes.
       el.dispatchEvent(new Event("input", { bubbles: true }));
       el.dispatchEvent(new Event("change", { bubbles: true }));
@@ -212,11 +218,7 @@ function runForm(form) {
   };
 }
 
-/**
- * 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}}
- */
+/** Every `<form toolname>` as a tool, following DOM changes; not where the browser does it itself. */
 export function forms() {
   const doc = globalThis.document;
   if (!doc || typeof context()?.registerTool !== "function" || "toolName" in HTMLFormElement.prototype) {