@orkestrel/mcp 0.0.29 → 0.0.31

package/dist/src/browser/index.d.ts

@@ -1,12 +1,70 @@
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
 import type { HTTPClientTransportOptions } from '@orkestrel/mcp';
 import type { JSONRPCMessage } from '@orkestrel/mcp';
+import type { MCPClientInterface } from '@orkestrel/mcp';
+import type { MCPClientOptions } from '@orkestrel/mcp';
 import type { MCPMessageTransportEventMap } from '@orkestrel/mcp';
 import type { MCPMessageTransportInterface } from '@orkestrel/mcp';
 import type { MCPServerInterface } from '@orkestrel/mcp';
 import type { MCPTransportInterface } from '@orkestrel/mcp';
+import type { ToolAnnotations } from '@orkestrel/tool';
+import type { ToolDefinition } from '@orkestrel/tool';
+import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
 
+/**
+ * Builds the WebMCP projection of every tool a registry advertises, or refuses the batch.
+ *
+ * @remarks
+ * The WebMCP twin of `@orkestrel/mcp`'s `buildToolDescriptors`. Each tool is projected through
+ * `@orkestrel/tool`'s own `toolToDefinition` — the projection `definitions()` applies — so a
+ * tool advertises one description across the MCP wire and the WebMCP registry alike. The tool
+ * travels beside its descriptor because a registration records which tool it was made for, and
+ * a descriptor cannot report that.
+ *
+ * It refuses rather than skips. WebMCP requires `description`, and each alternative to
+ * refusing is worse: an empty string is an invented value a foreign agent reads as a real one,
+ * and silently dropping the tool publishes a registry missing a tool its author asked for.
+ * Refusing before any registration happens is also what keeps `publish` atomic — nothing is
+ * registered when one tool cannot be.
+ *
+ * @param manager - The tool registry to project
+ * @returns One projection per advertised tool, in registry order
+ * @throws Thrown as an `MCPError` carrying `-32602` when a tool advertises no description,
+ * naming the tool
+ *
+ * @example
+ * ```ts
+ * const tools = createToolManager()
+ * tools.add(createTool({ name: 'add', description: 'Adds two numbers', execute: () => 5 }))
+ * buildWebMCPProjections(tools).map((projection) => projection.descriptor.name) // ['add']
+ * ```
+ */
+export declare function buildWebMCPProjections(manager: ToolManagerInterface): readonly WebMCPProjection[];
+
+/**
+ * Collects the WebMCP projection of every tool a registry advertises that WebMCP can carry.
+ *
+ * @remarks
+ * The skipping sibling of {@link buildWebMCPProjections}, and the reading a followed change
+ * reconciles against: a followed change reaches no caller, so a tool advertising neither a
+ * `description` nor a `summary` is left out of the collection rather than refusing a batch
+ * nobody asked for.
+ *
+ * @param manager - The tool registry to project
+ * @returns One projection per advertised tool WebMCP can carry, in registry order
+ *
+ * @example
+ * ```ts
+ * const tools = createToolManager()
+ * tools.add(createTool({ name: 'bare', execute: () => 1 }))
+ * collectWebMCPProjections(tools) // []
+ * ```
+ */
+export declare function collectWebMCPProjections(manager: ToolManagerInterface): readonly WebMCPProjection[];
+
 /**
  * Creates the HTTP client transport for an
  * {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPMessageTransportInterface}
@@ -82,6 +140,91 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  */
 export declare function createMessagePortTransport(options: MessagePortTransportOptions): MCPTransportInterface;
 
+/**
+ * Creates the bridge between a tool registry and a document's WebMCP registry, or reports that
+ * the document exposes none.
+ *
+ * @remarks
+ * Feature detection is the return value: `undefined` means this document has no
+ * `document.modelContext`, which is the reading every browser gives today — the specification
+ * is incubating in a Community Group, and the chromestatus record, read 2026-09-15 and last
+ * updated 2026-08-12, reports `Proposed` with `"flag": false` and `"origintrial": false`. There
+ * is no `supported` flag to read and no polyfill behind the factory, because a local
+ * implementation of an absent platform feature is one a caller mistakes for the platform.
+ *
+ * The bridge borrows the registry. It aborts only the registrations it made, so a name it
+ * never registered is left exactly as it found it. WebMCP keys a registration by tool name per
+ * document, so releasing a name releases whatever now stands under it — a same-name
+ * registration the page or another bridge made later goes with it.
+ *
+ * @param options - The document to bridge and the emitter's initial wiring; see
+ *   {@link ModelContextOptions}
+ * @returns A {@link ModelContextInterface}, or `undefined` when the document exposes no
+ *   WebMCP registry
+ *
+ * @example
+ * ```ts
+ * import { createModelContext } from '@orkestrel/mcp/browser'
+ * import { createToolManager } from '@orkestrel/tool'
+ *
+ * const bridge = createModelContext()
+ * if (bridge !== undefined) {
+ * 	await bridge.publish(createToolManager())
+ * 	const foreign = await bridge.adopt()
+ * 	bridge.destroy()
+ * }
+ * ```
+ */
+export declare function createModelContext(options?: ModelContextOptions): ModelContextInterface | undefined;
+
+/**
+ * Creates an `MCPServer` hosted inside the calling page and hands back the client bound to it
+ * — the page twin of {@link createScopeServer}, and the in-page MCP pair as one call.
+ *
+ * @remarks
+ * The pair is a native `MessageChannel`: the server binds `port1`, the client drives `port2`,
+ * and no byte leaves the page. That is the point of the factory — a consumer assembling it by
+ * hand writes the channel, two transports, `bindServer`, `createDuplexClientTransport`,
+ * `createMCPClient`, and `bindClient`, in an order {@link MessagePortTransport}'s own doc warns
+ * about: a `MessagePort` starts dispatching at construction, so an `await` interleaved between
+ * a transport and its binder drops whatever arrived in the gap. This factory never suspends
+ * between the two.
+ *
+ * The returned client is bound but not connected. Connection is a protocol round trip, so it
+ * stays the consumer's `await client.connect()` rather than a promise this call hides — and a
+ * factory that returned a promise could not return the terminal beside it.
+ *
+ * `stop` closes the client's port first, so the client observes the close and reports
+ * `connected` as `false` with its pending requests rejected, then unbinds both sides and
+ * closes the server's port. It is idempotent, and it takes the twin's verb because it is the
+ * twin's action: {@link createScopeServer} publishes `stop` for ending a hosted server's
+ * bindings, and a consumer who learned one factory reads the other without checking.
+ *
+ * The published `client` outlives the pair and is inert after `stop`: every session-bound
+ * request issued on it — `call`, `tools`, each `tasks/*` method, and a `listen` stream on its
+ * first `next()` — rejects at once with an `MCPError` carrying `-32600`, rather than waiting
+ * out its request deadline against a channel nothing is listening on.
+ *
+ * @param options - The tools, the optional server identity, and the optional client settings;
+ *   see {@link PageServerOptions}
+ * @returns A {@link PageServerInterface} holding the bound client and the pair's `stop`
+ *
+ * @example
+ * ```ts
+ * import { createPageServer } from '@orkestrel/mcp/browser'
+ * import { createTool, createToolManager } from '@orkestrel/tool'
+ *
+ * const tools = createToolManager()
+ * tools.add(createTool({ name: 'add', execute: () => 5 }))
+ *
+ * const page = createPageServer({ tools })
+ * await page.client.connect()
+ * const value = await page.client.call('add', {}) // { resultType: 'complete', value: 5 }
+ * page.stop()
+ * ```
+ */
+export declare function createPageServer(options: PageServerOptions): PageServerInterface;
+
 /**
  * Builds {@link createScopeServer}'s `message`-event listener — the unified dispatcher that
  * routes every inbound event on a hostable scope, portless or port-bearing, to the right
@@ -226,6 +369,96 @@ export declare const DEFAULT_MCP_SERVER_NAME = "@orkestrel/mcp";
 /** Supplies the default server version `createScopeServer` reports (`initialize`'s `serverInfo.version`) when `options.version` is omitted. */
 export declare const DEFAULT_MCP_SERVER_VERSION = "1.0.0";
 
+/**
+ * Projects the descriptor a registry advertises for one tool name, or reports that it has none.
+ *
+ * @remarks
+ * Reads the manager's own `definitions()` rather than a tool instance, so the description here
+ * is the one the registry advertises — an authored `summary` in place of the full
+ * `description` — and one tool reaches the WebMCP registry and the MCP wire describing itself
+ * the same way.
+ *
+ * `undefined` covers both answers a caller must not conflate with a descriptor: the manager
+ * advertises no tool under that name, and the tool it advertises carries no description, which
+ * is the member WebMCP requires.
+ *
+ * @param manager - The tool registry to read
+ * @param name - The tool name to describe
+ * @returns The WebMCP descriptor, or `undefined` when the registry advertises none
+ *
+ * @example
+ * ```ts
+ * const tools = createToolManager()
+ * tools.add(createTool({ name: 'add', description: 'Adds two numbers', execute: () => 5 }))
+ * describeWebMCPTool(tools, 'add')?.description // 'Adds two numbers'
+ * ```
+ */
+export declare function describeWebMCPTool(manager: ToolManagerInterface, name: string): WebMCPDescriptor | undefined;
+
+/**
+ * Determines whether an unknown value is a document exposing the WebMCP tool registry.
+ *
+ * @remarks
+ * This is the feature detection {@link import('./factories.js').createModelContext} performs,
+ * published so a consumer can run it before deciding to build a bridge at all. It reads
+ * `modelContext` and checks it with {@link isWebMCPRegistry}; it asserts nothing about the rest
+ * of a `Document`, because that member is the whole of what the bridge needs.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if the value carries a WebMCP registry; false otherwise
+ *
+ * @example
+ * ```ts
+ * isWebMCPDocument(globalThis.document) // false in a browser that ships no WebMCP
+ * ```
+ */
+export declare function isWebMCPDocument(value: unknown): value is WebMCPDocument;
+
+/**
+ * Determines whether an unknown value is a WebMCP tool registry.
+ *
+ * @remarks
+ * Reads the members the bridge dereferences — the IDL's `registerTool`, `getTools`, and
+ * `executeTool` operations, plus the `EventTarget` pair the `toolchange` subscription needs —
+ * and nothing else. A registry carrying extra members is still a registry, and a user agent's
+ * own implementation reaches every one of these through its prototype.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if the value exposes every WebMCP registry operation; false otherwise
+ *
+ * @example
+ * ```ts
+ * isWebMCPRegistry({}) // false
+ * ```
+ */
+export declare function isWebMCPRegistry(value: unknown): value is WebMCPRegistryInterface;
+
+/**
+ * Determines whether two WebMCP descriptors advertise the same tool to the registry.
+ *
+ * @remarks
+ * The reading `ModelContextInterface.publish` reconciles a name against once the manager's
+ * tool has changed under it: equal descriptors leave the live registration standing, because
+ * execution routes through the manager by name, and anything else releases it and registers
+ * the new one.
+ *
+ * Equality is structural and key-order-independent, through `@orkestrel/contract`'s
+ * `canonicalStringify`: `inputSchema` is the author's own JSON Schema record, and two
+ * authorings of the same schema that differ only in key order describe the same tool. A
+ * descriptor JSON cannot encode — a cyclic or unreadable `inputSchema` — is reported as
+ * unequal, which re-registers rather than serving a descriptor nothing could compare.
+ *
+ * @param held - The descriptor the live registration carries
+ * @param projected - The descriptor this publication projected
+ * @returns True when both describe the same tool; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesDescriptor({ name: 'add', description: 'Adds' }, { description: 'Adds', name: 'add' }) // true
+ * ```
+ */
+export declare function matchesDescriptor(held: WebMCPDescriptor, projected: WebMCPDescriptor): boolean;
+
 /**
  * Carries the Model Context Protocol over a native `MessagePort` from the browser face — a
  * {@link MCPTransportInterface}, the genuinely new capability this face adds: MCP over
@@ -312,6 +545,308 @@ export declare interface MessagePortTransportOptions {
     readonly port: MessagePort;
 }
 
+/**
+ * Bridges a `ToolManagerInterface` and a document's WebMCP tool registry — the
+ * {@link ModelContextInterface} {@link import('./factories.js').createModelContext} returns.
+ *
+ * @remarks
+ * - **It borrows the registry, it does not own it.** The handle registers tools, retains one
+ *   `AbortController` per registration, and aborts exactly those on `destroy`. WebMCP's own
+ *   unregistration path is that abort. Registration identity is the tool name, per document,
+ *   so releasing a name releases whatever now stands under it — including a same-name
+ *   registration another handle made later.
+ * - **`publish` snapshots at the call, then follows the manager.** The manager is projected
+ *   when `publish` is called, before the work queues behind an earlier publication, so a
+ *   registry mutated while this call waits its turn does not decide what this call registers.
+ *   The same call subscribes to the manager's own `emitter`, so a later `add`, `remove`, or
+ *   `clear` reaches the document registry without a second `publish`.
+ * - **One manager is followed at a time.** A `publish` naming another manager releases the
+ *   subscription and takes up the new one, and `destroy` releases it outright. An event from a
+ *   manager this handle no longer follows is ignored, which is what a listener republishing
+ *   another manager from inside a dispatch produces. A followed change has no caller to refuse
+ *   to, so a tool advertising neither a `description` nor a `summary` is left unregistered
+ *   rather than refusing anything; `publish` still refuses such a batch whole. Under a name
+ *   this handle never registered that skip emits no `change`, because nothing reached the
+ *   document registry. A synchronisation registers only what it can carry, so such a tool
+ *   standing under a name this handle already registered releases that registration rather
+ *   than leaving it advertising a descriptor the manager no longer stands behind, and that
+ *   release emits the registry's `change` like any other.
+ * - **A followed change is a trigger, not a fact.** Each `add`, `remove`, or `clear` queues one
+ *   synchronisation of this handle's registrations for that manager against what the manager
+ *   holds when that queued work runs. The event cannot decide the outcome: `remove` and
+ *   `clear` name tools the manager no longer holds, an earlier listener in the same dispatch
+ *   may already have put another tool under one of those names, and the manager's `destroy`
+ *   empties its map after the `clear` it publishes. Reading the manager converges on its state
+ *   however the change was reached, so a synchronisation queued and not yet started already
+ *   covers every change that arrives before it runs and a second one is not queued. A
+ *   publication queued behind that synchronisation ends its cover, because the publication
+ *   prunes what the synchronisation registered: a change arriving after that call queues a
+ *   synchronisation of its own, which runs after the publication.
+ * - **A later `publish` reconciles, and so does every synchronisation.** Each name is compared
+ *   with what this handle already registered for it: the same manager holding the same tool
+ *   leaves the registration alone, another tool of that same manager advertising an equal
+ *   descriptor leaves it registered and records the tool it now stands for, and anything else
+ *   releases it and registers the new descriptor bound to the new manager. A name the snapshot
+ *   dropped, or a name the manager no longer holds, is released — after the batch has
+ *   reconciled, never before, so no name is withdrawn while the tools replacing it are still
+ *   being registered. A failed batch releases them too, and still withdraws nothing it
+ *   carries. Nothing has to be removed from the manager to make the registry agree with it.
+ * - **Work serializes.** Registration is asynchronous and `destroy` is not, so overlapping
+ *   calls would interleave registrations with the aborts meant to end them. Each publication
+ *   and each synchronisation queues behind the previous one, and every step re-reads the
+ *   destroyed flag, so a `destroy` issued mid-publish stops the registrations that have not
+ *   happened yet instead of racing them.
+ * - **Nothing is polyfilled.** A document exposing no registry never reaches this class:
+ *   {@link import('./factories.js').createModelContext} returns `undefined` instead, so feature
+ *   absence stays absence rather than becoming a local implementation a caller mistakes for
+ *   the platform.
+ * - **The result shape is the registry's.** An adopted tool resolves whatever `executeTool`
+ *   resolved, unchanged. WebMCP's IDL types that `Promise<DOMString>` while the
+ *   specification's README sample returns `{ content: [...] }`; the primary source disagrees
+ *   with itself, and normalizing either way would encode a guess as a contract.
+ *
+ * @example
+ * ```ts
+ * import { isWebMCPDocument, ModelContext } from '@orkestrel/mcp/browser'
+ *
+ * if (isWebMCPDocument(document)) {
+ * 	const bridge = new ModelContext(document)
+ * 	await bridge.publish(tools)
+ * }
+ * ```
+ */
+export declare class ModelContext implements ModelContextInterface {
+    #private;
+    /**
+     * Binds a narrowed document's registry and arms the `toolchange` subscription.
+     *
+     * @param document - The document whose `modelContext` this handle bridges
+     * @param options - The emitter's initial hooks and listener-error handler; see
+     *   {@link ModelContextOptions}
+     */
+    constructor(document: WebMCPDocument, options?: ModelContextOptions);
+    get emitter(): EmitterInterface<ModelContextEventMap>;
+    publish(tools: ToolManagerInterface, options?: ModelContextPublishOptions): Promise<void>;
+    adopt(options?: ModelContextAdoptOptions): Promise<readonly ToolInterface[]>;
+    destroy(): void;
+}
+
+/**
+ * Options for {@link ModelContextInterface.adopt} — the origins whose tools are read.
+ *
+ * @remarks
+ * `origins` is this package's one-word name for WebMCP's `fromOrigins`, forwarded unchanged.
+ * Omitting it reads this document's own registrations.
+ */
+export declare interface ModelContextAdoptOptions {
+    readonly origins?: readonly string[];
+}
+
+/**
+ * Reports the moments a WebMCP registry's contents changed.
+ *
+ * @remarks
+ * Declared as a `type` alias rather than an interface, so the type-literal satisfies
+ * `EventMap` structurally. One event, because the registry publishes one: WebMCP's
+ * `toolchange` names no tool and carries no payload, so the bridge republishes it as a bare
+ * signal and a listener re-reads {@link ModelContextInterface.adopt} to learn what changed.
+ */
+export declare type ModelContextEventMap = {
+    /** Reports that the document's registry changed — re-read it to learn how. */
+    readonly change: readonly [];
+};
+
+/**
+ * Represents the bridge between a {@link ToolManagerInterface} and a document's WebMCP
+ * registry — what {@link import('./factories.js').createModelContext} returns.
+ *
+ * @remarks
+ * Bidirectional and symmetric: `publish` sends this page's tools out to the registry, `adopt`
+ * brings the registry's tools back in as `@orkestrel/tool` `Tool` instances. Both directions
+ * run the same annotation projection in opposite directions.
+ *
+ * The handle aborts exactly the registrations it made. WebMCP registration identity is the
+ * tool name, per document, so a later registration of a name replaces the earlier one whichever
+ * handle made it, and this handle's release takes whatever now stands under the names it
+ * registered — including a same-name registration another handle made later. Names this handle
+ * never registered are untouched.
+ */
+export declare interface ModelContextInterface {
+    /** Holds the emitter republishing the registry's `toolchange` as `change`. */
+    readonly emitter: EmitterInterface<ModelContextEventMap>;
+    /**
+     * Registers every tool the manager holds at this moment, then follows it.
+     *
+     * @remarks
+     * The snapshot is taken when the call is made, before the work queues behind an earlier
+     * `publish`, so a registry mutated while this call waits registers what it held at the call
+     * rather than what it holds when the queue reaches it.
+     *
+     * The same call subscribes to the manager's own `emitter`. Each `add`, `remove`, and
+     * `clear` it publishes queues one synchronisation of this handle's registrations against
+     * what the manager holds when that queued work runs, so the document registry converges on
+     * the tool registry after every change it follows, without a second call. Changes that
+     * arrive before that queued work runs are covered by it; a change that arrives after a
+     * later `publish` call takes a synchronisation of its own, which runs after that
+     * publication rather than before it. The event is the trigger and the manager is the fact:
+     * `remove` and `clear` carry tools the manager no longer holds, a listener that ran earlier
+     * in the same dispatch may already have put another tool under one of those names, and the
+     * manager's own `destroy` empties its map after publishing the `clear` that reports it. One
+     * manager is followed at a time: a `publish` naming another manager releases the
+     * subscription and takes up the new one, and `destroy` releases it outright. An event from
+     * a manager this handle no longer follows is ignored, which is what a listener republishing
+     * another manager from inside a dispatch produces. A followed change reaches no caller, so
+     * a tool advertising neither a `description` nor a `summary` is left unregistered rather
+     * than refusing anything, and a registration the document registry refuses is dropped, so
+     * the next call or the next synchronisation registers that name again. That batch still
+     * releases the names it dropped, because the prune runs whether or not every registration
+     * it asked for was made. A synchronisation registers only what it can carry, so such a tool
+     * standing under a name this handle already registered releases that registration instead
+     * of leaving it advertising a descriptor the manager no longer stands behind. Under a name
+     * this handle never registered the skip emits no `change`, because nothing reached the
+     * document registry; releasing a name this handle did register emits the registry's
+     * `change` like any other release. Compare the manager's own `definitions()` with what
+     * `adopt()` returns to read the mismatch, and
+     * {@link import('./helpers.js').describeWebMCPTool} answers `undefined` for a name
+     * `definitions()` still lists, which is that mismatch read from the manager's own side.
+     *
+     * Every name reconciles against what this handle registered for it, whether it arrives in a
+     * snapshot or through a synchronisation. The same manager still holding the same tool
+     * leaves the registration untouched, so a repeat publishes nothing and fires no
+     * `toolchange`. Another tool of that manager advertising an equal descriptor leaves the
+     * registration standing too, because execution routes through the manager by name and the
+     * replacement's handler is already what a foreign agent reaches. A changed projection, or
+     * the same name arriving from a different manager, releases the registration this handle
+     * holds and registers the new descriptor bound to the new manager. A name the snapshot
+     * dropped, and a name the followed manager no longer holds, is released after everything
+     * the batch carries has reconciled, so no name is withdrawn while the tools replacing it
+     * are still being registered.
+     *
+     * Every tool is projected before anything is registered, so a manager holding a tool with
+     * neither `description` nor `summary` is refused whole rather than half-registered.
+     *
+     * @param tools - The registry whose current tools are registered and whose later changes
+     *   are followed
+     * @param options - The optional exposure list; see {@link ModelContextPublishOptions}
+     * @returns Resolves after the registry has accepted each added registration
+     * @throws Thrown when a tool carries neither a `description` nor a `summary`, because
+     * WebMCP requires the member and an empty string would be an invented one
+     */
+    publish(tools: ToolManagerInterface, options?: ModelContextPublishOptions): Promise<void>;
+    /**
+     * Reads the document's registered tools as locally executable tools.
+     *
+     * @remarks
+     * Each returned tool's `execute` runs the registry's `executeTool` and forwards its
+     * `ToolContext.signal` as WebMCP's `signal`, so an agent-side abort reaches the foreign
+     * tool. The value resolves unchanged: WebMCP's own sources disagree about whether a tool
+     * answers with a string or an MCP content record, so the bridge normalizes neither.
+     *
+     * An adopted tool advertises the foreign `inputSchema` as its `parameters` and validates
+     * nothing against it. Compiling that schema into a contract would let one page's
+     * unreadable or hostile schema refuse the whole `adopt` call, and the arguments reach a
+     * handler in another document that has to validate them anyway.
+     *
+     * @param options - The optional origin filter; see {@link ModelContextAdoptOptions}
+     * @returns The registry's tools, in registry order
+     */
+    adopt(options?: ModelContextAdoptOptions): Promise<readonly ToolInterface[]>;
+    /**
+     * Aborts every registration this handle made, stops following the tool registry, and
+     * releases the emitter — idempotent.
+     *
+     * @remarks
+     * The subscription is released before anything is aborted, and a synchronisation already
+     * queued reads the destroyed handle and stops, so no registration is made after this call
+     * and none is left behind for a later change to release.
+     *
+     * @returns Nothing
+     */
+    destroy(): void;
+}
+
+/**
+ * Options for {@link import('./factories.js').createModelContext} — the document to bridge
+ * and the emitter's initial wiring.
+ *
+ * @remarks
+ * - `document` — the document whose registry to bridge, defaulting to `globalThis.document`.
+ *   A document exposing no `modelContext` makes the factory return `undefined`.
+ * - `on` — the reserved initial {@link import('@orkestrel/emitter').EmitterHooks} for
+ *   {@link ModelContextEventMap}.
+ * - `error` — the emitter's listener-error handler; a listener throw routes here rather than
+ *   to a domain event.
+ */
+export declare interface ModelContextOptions {
+    readonly document?: Document;
+    readonly on?: EmitterHooks<ModelContextEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/**
+ * Options for {@link ModelContextInterface.publish} — the origins each registration is
+ * exposed to.
+ *
+ * @remarks
+ * `origins` is this package's one-word name for WebMCP's `exposedTo`, forwarded unchanged.
+ * Omitting it registers with no exposure list, which is the registry's own default.
+ */
+export declare interface ModelContextPublishOptions {
+    readonly origins?: readonly string[];
+}
+
+/**
+ * Represents one MCP server hosted inside the calling page — what
+ * {@link import('./factories.js').createPageServer} returns.
+ *
+ * @remarks
+ * The page twin of {@link ScopeServerInterface}, and it publishes the client beside the
+ * terminal because the pair's whole value is holding both ends. The returned `client` is
+ * bound but NOT connected: connection is a protocol round trip over the channel, so it stays
+ * the consumer's `await client.connect()` rather than a promise the factory hides.
+ *
+ * `stop` closes the client's port first, so the client observes the close and reports
+ * `connected` as `false`, then unbinds both sides and closes the server's port. It is
+ * idempotent, and it ends this handle's lifetime permanently — the same verb, with the same
+ * meaning, that {@link ScopeServerInterface} publishes for the same action.
+ *
+ * The published `client` stays reachable after `stop` and is inert: `call` and `tools` reject
+ * at once with an `MCPError` carrying `-32600`, because the pair's channel is closed and no
+ * `connect` can reopen it.
+ */
+export declare interface PageServerInterface {
+    /** Holds the client bound to the server this page hosts, awaiting its own `connect`. */
+    readonly client: MCPClientInterface;
+    /** Closes both ports, unbinds both sides, and disconnects the client — idempotent. */
+    stop(): void;
+}
+
+/**
+ * Options for {@link import('./factories.js').createPageServer} — the live
+ * {@link ToolManagerInterface} to expose, the optional server identity, and the optional
+ * settings for the client half the pair owns.
+ *
+ * @remarks
+ * - `tools` — the registry the hosted `MCPServer` dispatches `tools/call` against. Required.
+ * - `name` / `version` — the hosted server's identity, defaulting to
+ *   {@link import('./constants.js').DEFAULT_MCP_SERVER_NAME} /
+ *   {@link import('./constants.js').DEFAULT_MCP_SERVER_VERSION} exactly as
+ *   {@link ScopeServerOptions} does.
+ * - `client` — the client half's own settings, grouped because there is more than one, and
+ *   declared as `MCPClientOptions` (`@orkestrel/mcp`) minus its one omission rather than as a
+ *   restatement of its members: every member the client accepts reaches this factory, and a
+ *   member added to that interface later reaches it without an edit here. `transport` is the
+ *   omission, and the only one: the pair mints the `MessageChannel` and owns both ends of it,
+ *   which is the whole point of the factory, so a caller-supplied carrier would be a second
+ *   transport with nothing on the other side of it.
+ */
+export declare interface PageServerOptions {
+    readonly tools: ToolManagerInterface;
+    readonly name?: string;
+    readonly version?: string;
+    readonly client?: Omit<MCPClientOptions, 'transport'>;
+}
+
 /**
  * Describes the structural shape {@link import('./factories.js').createScopeServer} needs
  * from a
@@ -327,8 +862,11 @@ export declare interface MessagePortTransportOptions {
  * structurally (it exposes far more, which this narrower shape ignores).
  */
 export declare interface ScopeInterface {
+    /** Posts one reply onto the scope's implicit channel. */
     postMessage(message: unknown): void;
+    /** Subscribes to the scope's `message` events, portless and port-bearing alike. */
     addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    /** Drops a `message` subscription. */
     removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
 }
 
@@ -389,6 +927,254 @@ export declare interface ScopeTransportInterface extends MCPTransportInterface {
     deliver(message: string): void;
 }
 
+/**
+ * Projects domain tool annotations onto WebMCP registry hints without inventing defaults.
+ *
+ * @param annotations - The authored domain annotations
+ * @returns The mapped hints; an omitted annotation stays omitted
+ *
+ * @example
+ * ```ts
+ * toolAnnotationsToWebMCP({ pure: true, untrusted: true }) // { readOnlyHint: true, untrustedContentHint: true }
+ * ```
+ */
+export declare function toolAnnotationsToWebMCP(annotations: ToolAnnotations): WebMCPAnnotations;
+
+/**
+ * Projects one advertised tool definition onto the WebMCP descriptor a registration carries.
+ *
+ * @remarks
+ * Takes the definition a `ToolManagerInterface` advertises rather than the tool itself, so the
+ * description here is the one the MCP wire advertises too — the registry substitutes an
+ * authored `summary` for the full `description`, and reading the same projection keeps one
+ * advertised description across both surfaces.
+ *
+ * WebMCP requires `description`, so a definition carrying none cannot be registered at all.
+ * Returning `undefined` is what lets the caller refuse the whole batch before registering any
+ * of it; registering an empty string instead would be an invented value a foreign agent reads
+ * as a real one.
+ *
+ * @param definition - The advertised definition to project
+ * @returns The WebMCP descriptor, or `undefined` when the definition advertises no description
+ *
+ * @example
+ * ```ts
+ * toolToWebMCP({ name: 'add', description: 'Adds two numbers' })?.description // 'Adds two numbers'
+ * ```
+ */
+export declare function toolToWebMCP(definition: ToolDefinition): WebMCPDescriptor | undefined;
+
+/** Names the WebMCP registry event the bridge republishes as its own `change`. */
+export declare const WEBMCP_CHANGE_EVENT = "toolchange";
+
+/**
+ * Describes a tool's observable effects as the WebMCP registry declares them.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ToolAnnotations` dictionary. The IDL defaults each member to
+ * `false`; this declaration keeps every member optional instead, because the bridge projects
+ * from `@orkestrel/tool`'s `ToolAnnotations` and never invents a hint the author omitted. The
+ * mapping is `pure` to `readOnlyHint`, `untrusted` to `untrustedContentHint`, and
+ * `consequential` to `consequentialHint` — a fuller correspondence than the MCP wire's, which
+ * has no counterpart for `untrusted` and spells the consequence `destructiveHint`.
+ */
+export declare interface WebMCPAnnotations {
+    readonly readOnlyHint?: boolean;
+    readonly untrustedContentHint?: boolean;
+    readonly consequentialHint?: boolean;
+}
+
+/**
+ * Projects WebMCP registry hints onto domain tool annotations without inventing defaults.
+ *
+ * @param annotations - The registry's hints, as the WebMCP dictionary declares them
+ * @returns The mapped annotations; an omitted hint stays omitted
+ *
+ * @example
+ * ```ts
+ * webMCPAnnotationsToTool({ readOnlyHint: false, consequentialHint: true }) // { pure: false, consequential: true }
+ * ```
+ */
+export declare function webMCPAnnotationsToTool(annotations: WebMCPAnnotations): ToolAnnotations;
+
+/**
+ * Describes the members a WebMCP tool carries into the registry and back out of it.
+ *
+ * @remarks
+ * The WebMCP `ModelContextTool` and `RegisteredTool` dictionaries declare the same members —
+ * `name`, `title`, `description`, `inputSchema`, `annotations` — and differ only in what each
+ * adds, so this is the shared body {@link WebMCPTool} and {@link WebMCPRegisteredTool} extend.
+ * `description` is required in the IDL and stays required here, which is why `publish` refuses
+ * a tool that authors neither a description nor a summary rather than registering an empty one.
+ */
+export declare interface WebMCPDescriptor {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    readonly annotations?: WebMCPAnnotations;
+}
+
+/**
+ * Describes a document that exposes the WebMCP tool registry.
+ *
+ * @remarks
+ * The narrowed shape {@link import('./validators.js').isWebMCPDocument} produces, and the one
+ * value {@link import('./ModelContext.js').ModelContext} needs. It declares the `modelContext`
+ * member alone rather than extending `Document`, because that member is the whole of what the
+ * bridge dereferences — a real `Document` carrying the registry satisfies it structurally, and
+ * so does any other host object that exposes one.
+ */
+export declare interface WebMCPDocument {
+    readonly modelContext: WebMCPRegistryInterface;
+}
+
+/**
+ * Runs one registered WebMCP tool with the caller's input and the registry's signal.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ToolExecuteCallback` callback. The IDL types its return
+ * `Promise<any>` and this declaration narrows that to `Promise<unknown>`, because a caller
+ * must narrow what a foreign tool returned before reading it.
+ */
+export declare type WebMCPExecuteHandler = (input: Readonly<Record<string, unknown>>, options: WebMCPHandlerOptions) => Promise<unknown>;
+
+/**
+ * Options for the WebMCP registry's `executeTool` — the caller's cancellation signal.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ModelContextExecuteToolOptions` dictionary. The registry
+ * forwards this signal onto the {@link WebMCPHandlerOptions} it hands the tool's callback.
+ */
+export declare interface WebMCPExecuteOptions {
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * Carries the execution signal the WebMCP registry hands a registered tool's callback.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ToolExecuteCallbackOptions` dictionary, whose `signal` is
+ * required: the registry always mints one, and an `executeTool` caller's own signal is
+ * forwarded onto it.
+ */
+export declare interface WebMCPHandlerOptions {
+    readonly signal: AbortSignal;
+}
+
+/**
+ * Pairs one tool with the WebMCP descriptor a registry advertises for it.
+ *
+ * @remarks
+ * The bridge's own pairing rather than a WebMCP dictionary. A registration has to answer later
+ * whether the manager still holds the tool it was made for, and a descriptor alone cannot
+ * answer that: two tools can advertise identical descriptors, and a descriptor JSON cannot
+ * encode — a cyclic `inputSchema` — compares equal to none, its own included.
+ */
+export declare interface WebMCPProjection {
+    readonly tool: ToolInterface;
+    readonly descriptor: WebMCPDescriptor;
+}
+
+/**
+ * Describes one tool as the WebMCP registry reports it back.
+ *
+ * @remarks
+ * Transliterates the WebMCP `RegisteredTool` dictionary: {@link WebMCPDescriptor}'s members
+ * plus the `window` that registered the tool and the `origin` it was registered from. The
+ * bridge carries both unread — `executeTool` takes the whole record back — and reads the
+ * descriptor members alone.
+ */
+export declare interface WebMCPRegisteredTool extends WebMCPDescriptor {
+    readonly window: Window;
+    readonly origin: string;
+}
+
+/**
+ * Options for the WebMCP registry's `registerTool` — the exposure list and the
+ * unregistration signal.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ModelContextRegisterToolOptions` dictionary. `exposedTo` lists
+ * the origins the registration is visible to; `signal` is WebMCP's unregistration path —
+ * aborting it removes the tool, which is why the bridge retains one controller per
+ * registration.
+ */
+export declare interface WebMCPRegisterOptions {
+    readonly exposedTo?: readonly string[];
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * Represents the WebMCP tool registry a document exposes as `document.modelContext`.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ModelContext` interface, which extends `EventTarget`: the
+ * operations plus the `toolchange` subscription the bridge republishes as
+ * {@link ModelContextEventMap}'s `change`. Only the members the bridge touches are declared,
+ * exactly as {@link ScopeInterface} declares only what `createScopeServer` touches, so a real
+ * `ModelContext` satisfies this structurally and an IDL-faithful double satisfies it without
+ * implementing the whole of `EventTarget`.
+ *
+ * `executeTool` resolves `unknown` because the primary source disagrees with itself: the IDL
+ * types it `Promise<DOMString>` while the specification's own README sample returns the MCP
+ * content shape `{ content: [...] }` from a tool's callback. The bridge records that
+ * disagreement rather than resolving it, so it neither parses the answer as text nor projects
+ * it into content blocks.
+ */
+export declare interface WebMCPRegistryInterface {
+    /** Registers one tool, resolving when the registry has accepted it. */
+    registerTool(tool: WebMCPTool, options?: WebMCPRegisterOptions): Promise<void>;
+    /** Reads the registered tools this document may see. */
+    getTools(options?: WebMCPToolsOptions): Promise<readonly WebMCPRegisteredTool[]>;
+    /** Runs one registered tool and resolves whatever its callback returned. */
+    executeTool(tool: WebMCPRegisteredTool, input?: Readonly<Record<string, unknown>>, options?: WebMCPExecuteOptions): Promise<unknown>;
+    /** Subscribes to the registry's `toolchange` event. */
+    addEventListener(type: 'toolchange', listener: () => void): void;
+    /** Drops a `toolchange` subscription. */
+    removeEventListener(type: 'toolchange', listener: () => void): void;
+}
+
+/**
+ * Describes one tool as handed to the WebMCP registry for registration.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ModelContextTool` dictionary: {@link WebMCPDescriptor}'s members
+ * plus the required `execute` callback the registry invokes.
+ */
+export declare interface WebMCPTool extends WebMCPDescriptor {
+    readonly execute: WebMCPExecuteHandler;
+}
+
+/**
+ * Options for the WebMCP registry's `getTools` — the origins whose tools are read.
+ *
+ * @remarks
+ * Transliterates the WebMCP `ModelContextGetToolOptions` dictionary. Omitting `fromOrigins`
+ * reads this document's own registrations.
+ */
+export declare interface WebMCPToolsOptions {
+    readonly fromOrigins?: readonly string[];
+}
+
+/**
+ * Projects one registered WebMCP tool onto the tool definition an adopted tool advertises.
+ *
+ * @remarks
+ * The inverse of {@link toolToWebMCP}, and deliberately lossy in the other direction: the
+ * registry's `window` and `origin` describe where the tool lives rather than what it does, and
+ * the bridge hands the whole registered record back to `executeTool` instead of rebuilding it.
+ *
+ * @param registered - The registered tool the registry reported
+ * @returns The definition an adopted tool advertises
+ *
+ * @example
+ * ```ts
+ * webMCPToTool({ name: 'add', description: 'Adds', window, origin: 'https://a.example' }).name // 'add'
+ * ```
+ */
+export declare function webMCPToTool(registered: WebMCPRegisteredTool): ToolDefinition;
+
 /**
  * Drives a remote MCP server over the native `WebSocket` global from the browser face, as a
  * client {@link MCPMessageTransportInterface}. This class is the browser sibling of the Node