@orkestrel/mcp 0.0.30 → 0.0.31

package/dist/src/browser/index.js

@@ -1,11 +1,527 @@
-import { isString } from "@orkestrel/contract";
-import { HTTPClientTransport, MCP_WEBSOCKET_SUBPROTOCOL, bindServer, createMCPServer, deliverMessage } from "../core/index.js";
+import { attempt, canonicalStringify, isFunction, isString, objectOf } from "@orkestrel/contract";
+import { HTTPClientTransport, JSONRPC_INVALID_PARAMS, MCPError, MCP_WEBSOCKET_SUBPROTOCOL, bindClient, bindServer, createDuplexClientTransport, createMCPClient, createMCPServer, deliverMessage } from "../core/index.js";
+import { createTool, toolToDefinition } from "@orkestrel/tool";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/browser/constants.ts
 /** Supplies the default server name `createScopeServer` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. */
 var DEFAULT_MCP_SERVER_NAME = "@orkestrel/mcp";
 /** Supplies the default server version `createScopeServer` reports (`initialize`'s `serverInfo.version`) when `options.version` is omitted. */
 var DEFAULT_MCP_SERVER_VERSION = "1.0.0";
+/** Names the WebMCP registry event the bridge republishes as its own `change`. */
+var WEBMCP_CHANGE_EVENT = "toolchange";
+//#endregion
+//#region src/browser/validators.ts
+/**
+* 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
+* ```
+*/
+function isWebMCPRegistry(value) {
+	return objectOf({
+		registerTool: isFunction,
+		getTools: isFunction,
+		executeTool: isFunction,
+		addEventListener: isFunction,
+		removeEventListener: isFunction
+	})(value);
+}
+/**
+* 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
+* ```
+*/
+function isWebMCPDocument(value) {
+	return objectOf({ modelContext: isWebMCPRegistry })(value);
+}
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* 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 }
+* ```
+*/
+function toolAnnotationsToWebMCP(annotations) {
+	return {
+		...annotations.pure === void 0 ? {} : { readOnlyHint: annotations.pure },
+		...annotations.untrusted === void 0 ? {} : { untrustedContentHint: annotations.untrusted },
+		...annotations.consequential === void 0 ? {} : { consequentialHint: annotations.consequential }
+	};
+}
+/**
+* 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 }
+* ```
+*/
+function webMCPAnnotationsToTool(annotations) {
+	return {
+		...annotations.readOnlyHint === void 0 ? {} : { pure: annotations.readOnlyHint },
+		...annotations.untrustedContentHint === void 0 ? {} : { untrusted: annotations.untrustedContentHint },
+		...annotations.consequentialHint === void 0 ? {} : { consequential: annotations.consequentialHint }
+	};
+}
+/**
+* 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'
+* ```
+*/
+function toolToWebMCP(definition) {
+	if (definition.description === void 0) return void 0;
+	const annotations = definition.annotations === void 0 ? {} : toolAnnotationsToWebMCP(definition.annotations);
+	return {
+		name: definition.name,
+		description: definition.description,
+		...definition.title === void 0 ? {} : { title: definition.title },
+		...definition.parameters === void 0 ? {} : { inputSchema: definition.parameters },
+		...Object.keys(annotations).length === 0 ? {} : { annotations }
+	};
+}
+/**
+* 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'
+* ```
+*/
+function webMCPToTool(registered) {
+	const annotations = registered.annotations === void 0 ? {} : webMCPAnnotationsToTool(registered.annotations);
+	return {
+		name: registered.name,
+		description: registered.description,
+		...registered.title === void 0 ? {} : { title: registered.title },
+		...registered.inputSchema === void 0 ? {} : { parameters: registered.inputSchema },
+		...Object.keys(annotations).length === 0 ? {} : { annotations }
+	};
+}
+/**
+* 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
+* ```
+*/
+function matchesDescriptor(held, projected) {
+	const left = attempt(() => canonicalStringify(held));
+	const right = attempt(() => canonicalStringify(projected));
+	if (!left.success || !right.success) return false;
+	return left.value !== void 0 && left.value === right.value;
+}
+/**
+* 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'
+* ```
+*/
+function describeWebMCPTool(manager, name) {
+	for (const definition of manager.definitions()) if (definition.name === name) return toolToWebMCP(definition);
+}
+/**
+* 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']
+* ```
+*/
+function buildWebMCPProjections(manager) {
+	const projections = [];
+	for (const tool of manager.tools()) {
+		const descriptor = toolToWebMCP(toolToDefinition(tool));
+		if (descriptor === void 0) throw new MCPError(`WebMCP requires a description for tool '${tool.name}'`, JSONRPC_INVALID_PARAMS);
+		projections.push({
+			tool,
+			descriptor
+		});
+	}
+	return projections;
+}
+/**
+* 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) // []
+* ```
+*/
+function collectWebMCPProjections(manager) {
+	const projections = [];
+	for (const tool of manager.tools()) {
+		const descriptor = toolToWebMCP(toolToDefinition(tool));
+		if (descriptor !== void 0) projections.push({
+			tool,
+			descriptor
+		});
+	}
+	return projections;
+}
+//#endregion
+//#region src/browser/ModelContext.ts
+/**
+* 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)
+* }
+* ```
+*/
+var ModelContext = class {
+	#registry;
+	#emitter;
+	#registrations = /* @__PURE__ */ new Map();
+	#listener;
+	#followed = void 0;
+	#pendingManager = void 0;
+	#queue = Promise.resolve();
+	#destroyed = false;
+	/**
+	* 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, options) {
+		this.#registry = document.modelContext;
+		this.#emitter = new Emitter({
+			...options?.on === void 0 ? {} : { on: options.on },
+			...options?.error === void 0 ? {} : { error: options.error }
+		});
+		this.#listener = this.#republish.bind(this);
+		this.#registry.addEventListener(WEBMCP_CHANGE_EVENT, this.#listener);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	publish(tools, options) {
+		const snapshot = attempt(() => buildWebMCPProjections(tools));
+		if (!snapshot.success) return Promise.reject(snapshot.error);
+		if (!this.#destroyed) this.#follow(tools, options);
+		this.#pendingManager = void 0;
+		const settled = this.#queue.then(() => this.#publish(tools, snapshot.value, options));
+		this.#queue = settled.catch(() => void 0);
+		return settled;
+	}
+	async adopt(options) {
+		return (await this.#registry.getTools(options?.origins === void 0 ? {} : { fromOrigins: options.origins })).map((tool) => createTool({
+			...webMCPToTool(tool),
+			execute: this.#execute.bind(this, tool)
+		}));
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#unfollow();
+		this.#pendingManager = void 0;
+		this.#registry.removeEventListener(WEBMCP_CHANGE_EVENT, this.#listener);
+		for (const held of this.#registrations.values()) held.controller.abort();
+		this.#registrations.clear();
+		this.#emitter.destroy();
+	}
+	#republish() {
+		this.#emitter.emit("change");
+	}
+	#follow(tools, options) {
+		this.#unfollow();
+		const changed = this.#changed.bind(this, tools, options);
+		tools.emitter.on("add", changed);
+		tools.emitter.on("remove", changed);
+		tools.emitter.on("clear", changed);
+		this.#followed = {
+			tools,
+			changed
+		};
+	}
+	#unfollow() {
+		const followed = this.#followed;
+		if (followed === void 0) return;
+		this.#followed = void 0;
+		followed.tools.emitter.off("add", followed.changed);
+		followed.tools.emitter.off("remove", followed.changed);
+		followed.tools.emitter.off("clear", followed.changed);
+	}
+	#follows(tools) {
+		return this.#followed?.tools === tools;
+	}
+	#changed(tools, options) {
+		if (!this.#follows(tools)) return;
+		if (this.#pendingManager === tools) return;
+		this.#pendingManager = tools;
+		this.#queue = this.#queue.then(this.#sync.bind(this, tools, options)).catch(() => void 0);
+	}
+	async #sync(tools, options) {
+		if (this.#pendingManager === tools) this.#pendingManager = void 0;
+		if (this.#destroyed) return;
+		const projections = collectWebMCPProjections(tools);
+		try {
+			for (const projection of projections) await this.#reconcile(tools, projection, options);
+		} finally {
+			this.#prune(projections, tools);
+		}
+	}
+	async #publish(tools, projections, options) {
+		if (this.#destroyed) return;
+		try {
+			for (const projection of projections) await this.#reconcile(tools, projection, options);
+		} finally {
+			this.#prune(projections);
+		}
+	}
+	async #reconcile(tools, projection, options) {
+		if (this.#destroyed) return;
+		const { descriptor, tool } = projection;
+		const held = this.#registrations.get(descriptor.name);
+		if (held !== void 0 && held.tools === tools) {
+			if (held.tool === tool) return;
+			if (matchesDescriptor(held.descriptor, descriptor)) {
+				this.#registrations.set(descriptor.name, {
+					...held,
+					tool
+				});
+				return;
+			}
+		}
+		if (held !== void 0) {
+			this.#registrations.delete(descriptor.name);
+			held.controller.abort();
+			if (this.#destroyed) return;
+		}
+		await this.#register(tools, projection, options);
+	}
+	async #register(tools, projection, options) {
+		const { descriptor, tool } = projection;
+		const controller = new AbortController();
+		this.#registrations.set(descriptor.name, {
+			controller,
+			descriptor,
+			tool,
+			tools
+		});
+		try {
+			await this.#registry.registerTool({
+				...descriptor,
+				execute: this.#run.bind(this, tools, descriptor.name)
+			}, {
+				...options?.origins === void 0 ? {} : { exposedTo: options.origins },
+				signal: controller.signal
+			});
+		} catch (error) {
+			this.#registrations.delete(descriptor.name);
+			controller.abort();
+			throw error;
+		}
+	}
+	#prune(projections, tools) {
+		if (this.#destroyed) return;
+		const kept = new Set(projections.map((projection) => projection.descriptor.name));
+		for (const [name, held] of this.#registrations) {
+			if (kept.has(name) || tools !== void 0 && held.tools !== tools) continue;
+			this.#registrations.delete(name);
+			held.controller.abort();
+			if (this.#destroyed) return;
+		}
+	}
+	async #run(tools, name, input, options) {
+		const result = await tools.execute({
+			id: crypto.randomUUID(),
+			name,
+			arguments: input
+		}, { signal: options.signal });
+		if (!result.success) throw new Error(result.error);
+		return result.value;
+	}
+	#execute(registered, args, context) {
+		return this.#registry.executeTool(registered, args, { signal: context.signal });
+	}
+};
 //#endregion
 //#region src/browser/transports/MessagePortTransport.ts
 /**
@@ -174,7 +690,7 @@ var WebSocketClientTransport = class {
 		this.#emitter = new Emitter();
 		this.#url = options.url;
 		const protocols = options.protocols;
-		this.#protocols = typeof protocols === "string" ? protocols : protocols === void 0 ? MCP_WEBSOCKET_SUBPROTOCOL : protocols.length === 0 ? void 0 : [...protocols];
+		this.#protocols = isString(protocols) ? protocols : protocols === void 0 ? MCP_WEBSOCKET_SUBPROTOCOL : protocols.length === 0 ? void 0 : [...protocols];
 	}
 	get emitter() {
 		return this.#emitter;
@@ -549,7 +1065,123 @@ function createScopeTransport(scope) {
 		}
 	};
 }
+/**
+* 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()
+* ```
+*/
+function createPageServer(options) {
+	const { port1, port2 } = new MessageChannel();
+	const server = createMCPServer({
+		tools: options.tools,
+		identity: {
+			name: options.name ?? "@orkestrel/mcp",
+			version: options.version ?? "1.0.0"
+		}
+	});
+	const hosted = new MessagePortTransport({ port: port1 });
+	const unbindServer = bindServer(server, hosted);
+	const driven = new MessagePortTransport({ port: port2 });
+	const client = createMCPClient({
+		...options.client,
+		transport: createDuplexClientTransport(driven)
+	});
+	const unbindClient = bindClient(client, driven);
+	let stopped = false;
+	return {
+		client,
+		stop() {
+			if (stopped) return;
+			stopped = true;
+			driven.close();
+			unbindClient();
+			unbindServer();
+			hosted.close();
+		}
+	};
+}
+/**
+* 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()
+* }
+* ```
+*/
+function createModelContext(options) {
+	const host = options?.document ?? globalThis.document;
+	if (!isWebMCPDocument(host)) return void 0;
+	return new ModelContext(host, options);
+}
 //#endregion
-export { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, MessagePortTransport, WebSocketClientTransport, createHTTPClientTransport, createMessagePortTransport, createScopeMessageListener, createScopeServer, createScopeTransport, createWebSocketClientTransport };
+export { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, MessagePortTransport, ModelContext, WEBMCP_CHANGE_EVENT, WebSocketClientTransport, buildWebMCPProjections, collectWebMCPProjections, createHTTPClientTransport, createMessagePortTransport, createModelContext, createPageServer, createScopeMessageListener, createScopeServer, createScopeTransport, createWebSocketClientTransport, describeWebMCPTool, isWebMCPDocument, isWebMCPRegistry, matchesDescriptor, toolAnnotationsToWebMCP, toolToWebMCP, webMCPAnnotationsToTool, webMCPToTool };
 
 //# sourceMappingURL=index.js.map