@mcp-b/global 1.1.0 → 1.1.2

package/dist/index.js

@@ -101,47 +101,511 @@ function validateWithZod(data, validator) {
 //#endregion
 //#region src/global.ts
 /**
-* Custom ToolCallEvent implementation
+* Detect if the native Chromium Web Model Context API is available.
+* Checks for both navigator.modelContext and navigator.modelContextTesting,
+* and verifies they are native implementations (not polyfills) by examining
+* the constructor name.
+*
+* @returns Detection result with flags for native context and testing API availability
+*/
+function detectNativeAPI() {
+	if (typeof window === "undefined" || typeof navigator === "undefined") return {
+		hasNativeContext: false,
+		hasNativeTesting: false
+	};
+	const modelContext = navigator.modelContext;
+	const modelContextTesting = navigator.modelContextTesting;
+	if (!modelContext || !modelContextTesting) return {
+		hasNativeContext: false,
+		hasNativeTesting: false
+	};
+	if ((modelContextTesting.constructor?.name || "").includes("WebModelContext")) return {
+		hasNativeContext: false,
+		hasNativeTesting: false
+	};
+	return {
+		hasNativeContext: true,
+		hasNativeTesting: true
+	};
+}
+/**
+* Adapter that wraps the native Chromium Web Model Context API.
+* Synchronizes tool changes from the native API to the MCP bridge,
+* enabling MCP clients to stay in sync with the native tool registry.
+*
+* Key features:
+* - Listens to native tool changes via registerToolsChangedCallback()
+* - Syncs native tools to MCP bridge automatically
+* - Delegates tool execution to native API
+* - Converts native results to MCP ToolResponse format
+*
+* @class NativeModelContextAdapter
+* @implements {InternalModelContext}
+*/
+var NativeModelContextAdapter = class {
+	nativeContext;
+	nativeTesting;
+	bridge;
+	syncInProgress = false;
+	/**
+	* Creates a new NativeModelContextAdapter.
+	*
+	* @param {MCPBridge} bridge - The MCP bridge instance
+	* @param {ModelContext} nativeContext - The native navigator.modelContext
+	* @param {ModelContextTesting} nativeTesting - The native navigator.modelContextTesting
+	*/
+	constructor(bridge, nativeContext, nativeTesting) {
+		this.bridge = bridge;
+		this.nativeContext = nativeContext;
+		this.nativeTesting = nativeTesting;
+		this.nativeTesting.registerToolsChangedCallback(() => {
+			console.log("[Native Adapter] Tool change detected from native API");
+			this.syncToolsFromNative();
+		});
+		this.syncToolsFromNative();
+	}
+	/**
+	* Synchronizes tools from the native API to the MCP bridge.
+	* Fetches all tools from navigator.modelContextTesting.listTools()
+	* and updates the bridge's tool registry.
+	*
+	* @private
+	*/
+	syncToolsFromNative() {
+		if (this.syncInProgress) return;
+		this.syncInProgress = true;
+		try {
+			const nativeTools = this.nativeTesting.listTools();
+			console.log(`[Native Adapter] Syncing ${nativeTools.length} tools from native API`);
+			this.bridge.tools.clear();
+			for (const toolInfo of nativeTools) try {
+				const inputSchema = JSON.parse(toolInfo.inputSchema);
+				const validatedTool = {
+					name: toolInfo.name,
+					description: toolInfo.description,
+					inputSchema,
+					execute: async (args) => {
+						const result = await this.nativeTesting.executeTool(toolInfo.name, JSON.stringify(args));
+						return this.convertToToolResponse(result);
+					},
+					inputValidator: jsonSchemaToZod$1(inputSchema)
+				};
+				this.bridge.tools.set(toolInfo.name, validatedTool);
+			} catch (error) {
+				console.error(`[Native Adapter] Failed to sync tool "${toolInfo.name}":`, error);
+			}
+			this.notifyMCPServers();
+		} finally {
+			this.syncInProgress = false;
+		}
+	}
+	/**
+	* Converts native API result to MCP ToolResponse format.
+	* Native API returns simplified values (string, number, object, etc.)
+	* which need to be wrapped in the MCP CallToolResult format.
+	*
+	* @param {unknown} result - The result from native executeTool()
+	* @returns {ToolResponse} Formatted MCP ToolResponse
+	* @private
+	*/
+	convertToToolResponse(result) {
+		if (typeof result === "string") return { content: [{
+			type: "text",
+			text: result
+		}] };
+		if (result === void 0 || result === null) return { content: [{
+			type: "text",
+			text: ""
+		}] };
+		if (typeof result === "object") return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(result, null, 2)
+			}],
+			structuredContent: result
+		};
+		return { content: [{
+			type: "text",
+			text: String(result)
+		}] };
+	}
+	/**
+	* Notifies all connected MCP servers that the tools list has changed.
+	*
+	* @private
+	*/
+	notifyMCPServers() {
+		if (this.bridge.tabServer?.notification) this.bridge.tabServer.notification({
+			method: "notifications/tools/list_changed",
+			params: {}
+		});
+		if (this.bridge.iframeServer?.notification) this.bridge.iframeServer.notification({
+			method: "notifications/tools/list_changed",
+			params: {}
+		});
+	}
+	/**
+	* Provides context (tools) to AI models via the native API.
+	* Delegates to navigator.modelContext.provideContext().
+	* Tool change callback will fire and trigger sync automatically.
+	*
+	* @param {ModelContextInput} context - Context containing tools to register
+	*/
+	provideContext(context) {
+		console.log("[Native Adapter] Delegating provideContext to native API");
+		this.nativeContext.provideContext(context);
+	}
+	/**
+	* Registers a single tool dynamically via the native API.
+	* Delegates to navigator.modelContext.registerTool().
+	* Tool change callback will fire and trigger sync automatically.
+	*
+	* @param {ToolDescriptor} tool - The tool descriptor to register
+	* @returns {{unregister: () => void}} Object with unregister function
+	*/
+	registerTool(tool) {
+		console.log(`[Native Adapter] Delegating registerTool("${tool.name}") to native API`);
+		return this.nativeContext.registerTool(tool);
+	}
+	/**
+	* Unregisters a tool by name via the native API.
+	* Delegates to navigator.modelContext.unregisterTool().
+	*
+	* @param {string} name - Name of the tool to unregister
+	*/
+	unregisterTool(name) {
+		console.log(`[Native Adapter] Delegating unregisterTool("${name}") to native API`);
+		this.nativeContext.unregisterTool(name);
+	}
+	/**
+	* Clears all registered tools via the native API.
+	* Delegates to navigator.modelContext.clearContext().
+	*/
+	clearContext() {
+		console.log("[Native Adapter] Delegating clearContext to native API");
+		this.nativeContext.clearContext();
+	}
+	/**
+	* Executes a tool via the native API.
+	* Delegates to navigator.modelContextTesting.executeTool() with JSON string args.
+	*
+	* @param {string} toolName - Name of the tool to execute
+	* @param {Record<string, unknown>} args - Arguments to pass to the tool
+	* @returns {Promise<ToolResponse>} The tool's response in MCP format
+	* @internal
+	*/
+	async executeTool(toolName, args) {
+		console.log(`[Native Adapter] Executing tool "${toolName}" via native API`);
+		try {
+			const result = await this.nativeTesting.executeTool(toolName, JSON.stringify(args));
+			return this.convertToToolResponse(result);
+		} catch (error) {
+			console.error(`[Native Adapter] Error executing tool "${toolName}":`, error);
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${error instanceof Error ? error.message : String(error)}`
+				}],
+				isError: true
+			};
+		}
+	}
+	/**
+	* Lists all registered tools from the MCP bridge.
+	* Returns tools synced from the native API.
+	*
+	* @returns {Array<{name: string, description: string, inputSchema: InputSchema}>} Array of tool descriptors
+	*/
+	listTools() {
+		return Array.from(this.bridge.tools.values()).map((tool) => ({
+			name: tool.name,
+			description: tool.description,
+			inputSchema: tool.inputSchema,
+			...tool.outputSchema && { outputSchema: tool.outputSchema },
+			...tool.annotations && { annotations: tool.annotations }
+		}));
+	}
+	/**
+	* Adds an event listener for tool call events.
+	* Delegates to the native API's addEventListener.
+	*
+	* @param {'toolcall'} type - Event type
+	* @param {(event: ToolCallEvent) => void | Promise<void>} listener - Event handler
+	* @param {boolean | AddEventListenerOptions} [options] - Event listener options
+	*/
+	addEventListener(type, listener, options) {
+		this.nativeContext.addEventListener(type, listener, options);
+	}
+	/**
+	* Removes an event listener for tool call events.
+	* Delegates to the native API's removeEventListener.
+	*
+	* @param {'toolcall'} type - Event type
+	* @param {(event: ToolCallEvent) => void | Promise<void>} listener - Event handler
+	* @param {boolean | EventListenerOptions} [options] - Event listener options
+	*/
+	removeEventListener(type, listener, options) {
+		this.nativeContext.removeEventListener(type, listener, options);
+	}
+	/**
+	* Dispatches a tool call event.
+	* Delegates to the native API's dispatchEvent.
+	*
+	* @param {Event} event - The event to dispatch
+	* @returns {boolean} False if event was cancelled, true otherwise
+	*/
+	dispatchEvent(event) {
+		return this.nativeContext.dispatchEvent(event);
+	}
+};
+/**
+* ToolCallEvent implementation for the Web Model Context API.
+* Represents an event fired when a tool is called, allowing event listeners
+* to intercept and provide custom responses.
+*
+* @class WebToolCallEvent
+* @extends {Event}
+* @implements {ToolCallEvent}
 */
 var WebToolCallEvent = class extends Event {
 	name;
 	arguments;
 	_response = null;
 	_responded = false;
+	/**
+	* Creates a new ToolCallEvent.
+	*
+	* @param {string} toolName - Name of the tool being called
+	* @param {Record<string, unknown>} args - Validated arguments for the tool
+	*/
 	constructor(toolName, args) {
 		super("toolcall", { cancelable: true });
 		this.name = toolName;
 		this.arguments = args;
 	}
+	/**
+	* Provides a response for this tool call, preventing the default tool execution.
+	*
+	* @param {ToolResponse} response - The response to use instead of executing the tool
+	* @throws {Error} If a response has already been provided
+	*/
 	respondWith(response) {
 		if (this._responded) throw new Error("Response already provided for this tool call");
 		this._response = response;
 		this._responded = true;
 	}
+	/**
+	* Gets the response provided via respondWith().
+	*
+	* @returns {ToolResponse | null} The response, or null if none provided
+	*/
 	getResponse() {
 		return this._response;
 	}
+	/**
+	* Checks whether a response has been provided for this tool call.
+	*
+	* @returns {boolean} True if respondWith() was called
+	*/
 	hasResponse() {
 		return this._responded;
 	}
 };
 /**
-* Time window (in ms) to detect rapid duplicate registrations
-* Registrations within this window are likely due to React Strict Mode
+* Time window in milliseconds to detect rapid duplicate tool registrations.
+* Used to filter out double-registrations caused by React Strict Mode.
 */
 const RAPID_DUPLICATE_WINDOW_MS = 50;
 /**
-* ModelContext implementation that bridges to MCP SDK
-* Implements the W3C Web Model Context API proposal with two-bucket tool management
+* Testing API implementation for the Model Context Protocol.
+* Provides debugging, mocking, and testing capabilities for tool execution.
+* Implements both Chromium native methods and polyfill-specific extensions.
+*
+* @class WebModelContextTesting
+* @implements {ModelContextTesting}
+*/
+var WebModelContextTesting = class {
+	toolCallHistory = [];
+	mockResponses = /* @__PURE__ */ new Map();
+	toolsChangedCallbacks = /* @__PURE__ */ new Set();
+	bridge;
+	/**
+	* Creates a new WebModelContextTesting instance.
+	*
+	* @param {MCPBridge} bridge - The MCP bridge instance to test
+	*/
+	constructor(bridge) {
+		this.bridge = bridge;
+	}
+	/**
+	* Records a tool call in the history.
+	* Called internally by WebModelContext when tools are executed.
+	*
+	* @param {string} toolName - Name of the tool that was called
+	* @param {Record<string, unknown>} args - Arguments passed to the tool
+	* @internal
+	*/
+	recordToolCall(toolName, args) {
+		this.toolCallHistory.push({
+			toolName,
+			arguments: args,
+			timestamp: Date.now()
+		});
+	}
+	/**
+	* Checks if a mock response is registered for a specific tool.
+	*
+	* @param {string} toolName - Name of the tool to check
+	* @returns {boolean} True if a mock response exists
+	* @internal
+	*/
+	hasMockResponse(toolName) {
+		return this.mockResponses.has(toolName);
+	}
+	/**
+	* Retrieves the mock response for a specific tool.
+	*
+	* @param {string} toolName - Name of the tool
+	* @returns {ToolResponse | undefined} The mock response, or undefined if none exists
+	* @internal
+	*/
+	getMockResponse(toolName) {
+		return this.mockResponses.get(toolName);
+	}
+	/**
+	* Notifies all registered callbacks that the tools list has changed.
+	* Called internally when tools are registered, unregistered, or cleared.
+	*
+	* @internal
+	*/
+	notifyToolsChanged() {
+		for (const callback of this.toolsChangedCallbacks) try {
+			callback();
+		} catch (error) {
+			console.error("[Model Context Testing] Error in tools changed callback:", error);
+		}
+	}
+	/**
+	* Executes a tool directly with JSON string input (Chromium native API).
+	* Parses the JSON input, validates it, and executes the tool.
+	*
+	* @param {string} toolName - Name of the tool to execute
+	* @param {string} inputArgsJson - JSON string of input arguments
+	* @returns {Promise<unknown>} The tool's result, or undefined on error
+	* @throws {SyntaxError} If the input JSON is invalid
+	* @throws {Error} If the tool does not exist
+	*/
+	async executeTool(toolName, inputArgsJson) {
+		console.log(`[Model Context Testing] Executing tool: ${toolName}`);
+		let args;
+		try {
+			args = JSON.parse(inputArgsJson);
+		} catch (error) {
+			throw new SyntaxError(`Invalid JSON input: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (!this.bridge.tools.get(toolName)) throw new Error(`Tool not found: ${toolName}`);
+		const result = await this.bridge.modelContext.executeTool(toolName, args);
+		if (result.isError) return;
+		if (result.structuredContent) return result.structuredContent;
+		if (result.content && result.content.length > 0) {
+			const firstContent = result.content[0];
+			if (firstContent && firstContent.type === "text") return firstContent.text;
+		}
+	}
+	/**
+	* Lists all registered tools with inputSchema as JSON string (Chromium native API).
+	* Returns an array of ToolInfo objects where inputSchema is stringified.
+	*
+	* @returns {Array<{name: string, description: string, inputSchema: string}>} Array of tool information
+	*/
+	listTools() {
+		return this.bridge.modelContext.listTools().map((tool) => ({
+			name: tool.name,
+			description: tool.description,
+			inputSchema: JSON.stringify(tool.inputSchema)
+		}));
+	}
+	/**
+	* Registers a callback that fires when the tools list changes (Chromium native API).
+	* The callback will be invoked on registerTool, unregisterTool, provideContext, and clearContext.
+	*
+	* @param {() => void} callback - Function to call when tools change
+	*/
+	registerToolsChangedCallback(callback) {
+		this.toolsChangedCallbacks.add(callback);
+		console.log("[Model Context Testing] Tools changed callback registered");
+	}
+	/**
+	* Gets all tool calls that have been recorded (polyfill extension).
+	*
+	* @returns {Array<{toolName: string, arguments: Record<string, unknown>, timestamp: number}>} Tool call history
+	*/
+	getToolCalls() {
+		return [...this.toolCallHistory];
+	}
+	/**
+	* Clears the tool call history (polyfill extension).
+	*/
+	clearToolCalls() {
+		this.toolCallHistory = [];
+		console.log("[Model Context Testing] Tool call history cleared");
+	}
+	/**
+	* Sets a mock response for a specific tool (polyfill extension).
+	* When set, the tool's execute function will be bypassed.
+	*
+	* @param {string} toolName - Name of the tool to mock
+	* @param {ToolResponse} response - The mock response to return
+	*/
+	setMockToolResponse(toolName, response) {
+		this.mockResponses.set(toolName, response);
+		console.log(`[Model Context Testing] Mock response set for tool: ${toolName}`);
+	}
+	/**
+	* Clears the mock response for a specific tool (polyfill extension).
+	*
+	* @param {string} toolName - Name of the tool
+	*/
+	clearMockToolResponse(toolName) {
+		this.mockResponses.delete(toolName);
+		console.log(`[Model Context Testing] Mock response cleared for tool: ${toolName}`);
+	}
+	/**
+	* Clears all mock tool responses (polyfill extension).
+	*/
+	clearAllMockToolResponses() {
+		this.mockResponses.clear();
+		console.log("[Model Context Testing] All mock responses cleared");
+	}
+	/**
+	* Gets the current tools registered in the system (polyfill extension).
+	*
+	* @returns {ReturnType<InternalModelContext['listTools']>} Array of registered tools
+	*/
+	getRegisteredTools() {
+		return this.bridge.modelContext.listTools();
+	}
+	/**
+	* Resets the entire testing state (polyfill extension).
+	* Clears both tool call history and all mock responses.
+	*/
+	reset() {
+		this.clearToolCalls();
+		this.clearAllMockToolResponses();
+		console.log("[Model Context Testing] Testing state reset");
+	}
+};
+/**
+* ModelContext implementation that bridges to the Model Context Protocol SDK.
+* Implements the W3C Web Model Context API proposal with two-bucket tool management:
+* - Bucket A (provideContextTools): Tools registered via provideContext()
+* - Bucket B (dynamicTools): Tools registered via registerTool()
 *
-* Two-Bucket System:
-* - Bucket A (provideContextTools): Tools registered via provideContext() - base/app-level tools
-* - Bucket B (dynamicTools): Tools registered via registerTool() - component-scoped tools
+* This separation ensures that component-scoped dynamic tools persist across
+* app-level provideContext() calls.
 *
-* Benefits:
-* - provideContext() only clears Bucket A, leaving Bucket B intact
-* - Components can manage their own tool lifecycle independently
-* - Final tool list = Bucket A + Bucket B (merged, with collision detection)
+* @class WebModelContext
+* @implements {InternalModelContext}
 */
 var WebModelContext = class {
 	bridge;
@@ -150,6 +614,12 @@ var WebModelContext = class {
 	dynamicTools;
 	registrationTimestamps;
 	unregisterFunctions;
+	testingAPI;
+	/**
+	* Creates a new WebModelContext instance.
+	*
+	* @param {MCPBridge} bridge - The MCP bridge to use for communication
+	*/
 	constructor(bridge) {
 		this.bridge = bridge;
 		this.eventTarget = new EventTarget();
@@ -159,26 +629,51 @@ var WebModelContext = class {
 		this.unregisterFunctions = /* @__PURE__ */ new Map();
 	}
 	/**
-	* Add event listener (compatible with ModelContext interface)
+	* Sets the testing API instance.
+	* Called during initialization to enable testing features.
+	*
+	* @param {WebModelContextTesting} testingAPI - The testing API instance
+	* @internal
+	*/
+	setTestingAPI(testingAPI) {
+		this.testingAPI = testingAPI;
+	}
+	/**
+	* Adds an event listener for tool call events.
+	*
+	* @param {'toolcall'} type - Event type (only 'toolcall' is supported)
+	* @param {(event: ToolCallEvent) => void | Promise<void>} listener - Event handler function
+	* @param {boolean | AddEventListenerOptions} [options] - Event listener options
 	*/
 	addEventListener(type, listener, options) {
 		this.eventTarget.addEventListener(type, listener, options);
 	}
 	/**
-	* Remove event listener
+	* Removes an event listener for tool call events.
+	*
+	* @param {'toolcall'} type - Event type (only 'toolcall' is supported)
+	* @param {(event: ToolCallEvent) => void | Promise<void>} listener - Event handler function
+	* @param {boolean | EventListenerOptions} [options] - Event listener options
 	*/
 	removeEventListener(type, listener, options) {
 		this.eventTarget.removeEventListener(type, listener, options);
 	}
 	/**
-	* Dispatch event
+	* Dispatches a tool call event to all registered listeners.
+	*
+	* @param {Event} event - The event to dispatch
+	* @returns {boolean} False if event was cancelled, true otherwise
 	*/
 	dispatchEvent(event) {
 		return this.eventTarget.dispatchEvent(event);
 	}
 	/**
-	* Provide context (tools) to AI models
-	* Clears and replaces Bucket A (provideContext tools), leaving Bucket B (dynamic tools) intact
+	* Provides context (tools) to AI models by registering base tools (Bucket A).
+	* Clears and replaces all previously registered base tools while preserving
+	* dynamic tools registered via registerTool().
+	*
+	* @param {ModelContextInput} context - Context containing tools to register
+	* @throws {Error} If a tool name collides with an existing dynamic tool
 	*/
 	provideContext(context) {
 		console.log(`[Web Model Context] Registering ${context.tools.length} tools via provideContext`);
@@ -203,9 +698,12 @@ var WebModelContext = class {
 		this.notifyToolsListChanged();
 	}
 	/**
-	* Register a single tool dynamically (Bucket B)
-	* Returns an object with an unregister function to remove the tool
-	* Tools registered via this method persist across provideContext() calls
+	* Registers a single tool dynamically (Bucket B).
+	* Dynamic tools persist across provideContext() calls and can be independently managed.
+	*
+	* @param {ToolDescriptor} tool - The tool descriptor to register
+	* @returns {{unregister: () => void}} Object with unregister function
+	* @throws {Error} If tool name collides with existing tools
 	*/
 	registerTool(tool) {
 		console.log(`[Web Model Context] Registering tool dynamically: ${tool.name}`);
@@ -251,8 +749,46 @@ var WebModelContext = class {
 		return { unregister: unregisterFn };
 	}
 	/**
-	* Update the bridge tools map with merged tools from both buckets
-	* Final tool list = Bucket A (provideContext) + Bucket B (dynamic)
+	* Unregisters a tool by name (Chromium native API).
+	* Can unregister tools from either Bucket A (provideContext) or Bucket B (registerTool).
+	*
+	* @param {string} name - Name of the tool to unregister
+	*/
+	unregisterTool(name) {
+		console.log(`[Web Model Context] Unregistering tool: ${name}`);
+		const inProvideContext = this.provideContextTools.has(name);
+		const inDynamic = this.dynamicTools.has(name);
+		if (!inProvideContext && !inDynamic) {
+			console.warn(`[Web Model Context] Tool "${name}" is not registered, ignoring unregister call`);
+			return;
+		}
+		if (inProvideContext) this.provideContextTools.delete(name);
+		if (inDynamic) {
+			this.dynamicTools.delete(name);
+			this.registrationTimestamps.delete(name);
+			this.unregisterFunctions.delete(name);
+		}
+		this.updateBridgeTools();
+		this.notifyToolsListChanged();
+	}
+	/**
+	* Clears all registered tools from both buckets (Chromium native API).
+	* Removes all tools registered via provideContext() and registerTool().
+	*/
+	clearContext() {
+		console.log("[Web Model Context] Clearing all tools");
+		this.provideContextTools.clear();
+		this.dynamicTools.clear();
+		this.registrationTimestamps.clear();
+		this.unregisterFunctions.clear();
+		this.updateBridgeTools();
+		this.notifyToolsListChanged();
+	}
+	/**
+	* Updates the bridge tools map with merged tools from both buckets.
+	* The final tool list is the union of Bucket A (provideContext) and Bucket B (dynamic).
+	*
+	* @private
 	*/
 	updateBridgeTools() {
 		this.bridge.tools.clear();
@@ -261,7 +797,10 @@ var WebModelContext = class {
 		console.log(`[Web Model Context] Updated bridge with ${this.provideContextTools.size} base tools + ${this.dynamicTools.size} dynamic tools = ${this.bridge.tools.size} total`);
 	}
 	/**
-	* Notify all servers that the tools list has changed
+	* Notifies all servers and testing callbacks that the tools list has changed.
+	* Sends MCP notifications to connected servers and invokes registered testing callbacks.
+	*
+	* @private
 	*/
 	notifyToolsListChanged() {
 		if (this.bridge.tabServer.notification) this.bridge.tabServer.notification({
@@ -272,13 +811,23 @@ var WebModelContext = class {
 			method: "notifications/tools/list_changed",
 			params: {}
 		});
+		if (this.testingAPI && "notifyToolsChanged" in this.testingAPI) this.testingAPI.notifyToolsChanged();
 	}
 	/**
-	* Execute a tool with hybrid approach:
-	* 1. Validate input arguments
-	* 2. Dispatch toolcall event first
-	* 3. If not prevented, call tool's execute function
-	* 4. Validate output (permissive mode - warn only)
+	* Executes a tool with validation and event dispatch.
+	* Follows this sequence:
+	* 1. Validates input arguments against schema
+	* 2. Records tool call in testing API (if available)
+	* 3. Checks for mock response (if testing)
+	* 4. Dispatches 'toolcall' event to listeners
+	* 5. Executes tool function if not prevented
+	* 6. Validates output (permissive mode - warns only)
+	*
+	* @param {string} toolName - Name of the tool to execute
+	* @param {Record<string, unknown>} args - Arguments to pass to the tool
+	* @returns {Promise<ToolResponse>} The tool's response
+	* @throws {Error} If tool is not found
+	* @internal
 	*/
 	async executeTool(toolName, args) {
 		const tool = this.bridge.tools.get(toolName);
@@ -296,6 +845,14 @@ var WebModelContext = class {
 			};
 		}
 		const validatedArgs = validation.data;
+		if (this.testingAPI) this.testingAPI.recordToolCall(toolName, validatedArgs);
+		if (this.testingAPI?.hasMockResponse(toolName)) {
+			const mockResponse = this.testingAPI.getMockResponse(toolName);
+			if (mockResponse) {
+				console.log(`[Web Model Context] Returning mock response for tool: ${toolName}`);
+				return mockResponse;
+			}
+		}
 		const event = new WebToolCallEvent(toolName, validatedArgs);
 		this.dispatchEvent(event);
 		if (event.defaultPrevented && event.hasResponse()) {
@@ -325,8 +882,11 @@ var WebModelContext = class {
 		}
 	}
 	/**
-	* Get list of registered tools in MCP format
-	* Includes full MCP spec: annotations, outputSchema, etc.
+	* Lists all registered tools in MCP format.
+	* Returns tools from both buckets with full MCP specification including
+	* annotations and output schemas.
+	*
+	* @returns {Array<{name: string, description: string, inputSchema: InputSchema, outputSchema?: InputSchema, annotations?: ToolAnnotations}>} Array of tool descriptors
 	*/
 	listTools() {
 		return Array.from(this.bridge.tools.values()).map((tool) => ({
@@ -339,8 +899,12 @@ var WebModelContext = class {
 	}
 };
 /**
-* Initialize the MCP bridge with dual-server support
-* Creates both TabServer (same-window) and IframeChildServer (parent-child) by default
+* Initializes the MCP bridge with dual-server support.
+* Creates TabServer for same-window communication and optionally IframeChildServer
+* for parent-child iframe communication.
+*
+* @param {WebModelContextInitOptions} [options] - Configuration options
+* @returns {MCPBridge} The initialized MCP bridge
 */
 function initializeMCPBridge(options) {
 	console.log("[Web Model Context] Initializing MCP bridge");
@@ -430,7 +994,24 @@ function initializeMCPBridge(options) {
 	return bridge;
 }
 /**
-* Initialize the Web Model Context API (window.navigator.modelContext)
+* Initializes the Web Model Context API on window.navigator.
+* Creates and exposes navigator.modelContext and navigator.modelContextTesting.
+* Automatically detects and uses native Chromium implementation if available.
+*
+* @param {WebModelContextInitOptions} [options] - Configuration options
+* @throws {Error} If initialization fails
+* @example
+* ```typescript
+* import { initializeWebModelContext } from '@mcp-b/global';
+*
+* initializeWebModelContext({
+*   transport: {
+*     tabServer: {
+*       allowedOrigins: ['https://example.com']
+*     }
+*   }
+* });
+* ```
 */
 function initializeWebModelContext(options) {
 	if (typeof window === "undefined") {
@@ -438,10 +1019,49 @@ function initializeWebModelContext(options) {
 		return;
 	}
 	const effectiveOptions = options ?? window.__webModelContextOptions;
+	const native = detectNativeAPI();
+	if (native.hasNativeContext && native.hasNativeTesting) {
+		const nativeContext = window.navigator.modelContext;
+		const nativeTesting = window.navigator.modelContextTesting;
+		if (!nativeContext || !nativeTesting) {
+			console.error("[Web Model Context] Native API detection mismatch");
+			return;
+		}
+		console.log("✅ [Web Model Context] Native Chromium API detected");
+		console.log("   Using native implementation with MCP bridge synchronization");
+		console.log("   Native API will automatically collect tools from embedded iframes");
+		try {
+			const bridge = initializeMCPBridge(effectiveOptions);
+			bridge.modelContext = new NativeModelContextAdapter(bridge, nativeContext, nativeTesting);
+			bridge.modelContextTesting = nativeTesting;
+			Object.defineProperty(window, "__mcpBridge", {
+				value: bridge,
+				writable: false,
+				configurable: true
+			});
+			console.log("✅ [Web Model Context] MCP bridge synced with native API");
+			console.log("   MCP clients will receive automatic tool updates from native registry");
+		} catch (error) {
+			console.error("[Web Model Context] Failed to initialize native adapter:", error);
+			throw error;
+		}
+		return;
+	}
+	if (native.hasNativeContext && !native.hasNativeTesting) {
+		console.warn("[Web Model Context] Partial native API detected");
+		console.warn("   navigator.modelContext exists but navigator.modelContextTesting is missing");
+		console.warn("   Cannot sync with native API. Please enable experimental features:");
+		console.warn("      - Navigate to chrome://flags");
+		console.warn("      - Enable \"Experimental Web Platform Features\"");
+		console.warn("      - Or launch with: --enable-experimental-web-platform-features");
+		console.warn("   Skipping initialization to avoid conflicts");
+		return;
+	}
 	if (window.navigator.modelContext) {
 		console.warn("[Web Model Context] window.navigator.modelContext already exists, skipping initialization");
 		return;
 	}
+	console.log("[Web Model Context] Native API not detected, installing polyfill");
 	try {
 		const bridge = initializeMCPBridge(effectiveOptions);
 		Object.defineProperty(window.navigator, "modelContext", {
@@ -455,13 +1075,36 @@ function initializeWebModelContext(options) {
 			configurable: true
 		});
 		console.log("✅ [Web Model Context] window.navigator.modelContext initialized successfully");
+		console.log("[Model Context Testing] Installing polyfill");
+		console.log("   💡 To use the native implementation in Chromium:");
+		console.log("      - Navigate to chrome://flags");
+		console.log("      - Enable \"Experimental Web Platform Features\"");
+		console.log("      - Or launch with: --enable-experimental-web-platform-features");
+		const testingAPI = new WebModelContextTesting(bridge);
+		bridge.modelContextTesting = testingAPI;
+		bridge.modelContext.setTestingAPI(testingAPI);
+		Object.defineProperty(window.navigator, "modelContextTesting", {
+			value: testingAPI,
+			writable: false,
+			configurable: true
+		});
+		console.log("✅ [Model Context Testing] Polyfill installed at window.navigator.modelContextTesting");
 	} catch (error) {
 		console.error("[Web Model Context] Failed to initialize:", error);
 		throw error;
 	}
 }
 /**
-* Cleanup function (for testing/development)
+* Cleans up the Web Model Context API.
+* Closes all MCP servers and removes API from window.navigator.
+* Useful for testing and hot module replacement.
+*
+* @example
+* ```typescript
+* import { cleanupWebModelContext } from '@mcp-b/global';
+*
+* cleanupWebModelContext();
+* ```
 */
 function cleanupWebModelContext() {
 	if (typeof window === "undefined") return;
@@ -472,6 +1115,7 @@ function cleanupWebModelContext() {
 		console.warn("[Web Model Context] Error closing MCP servers:", error);
 	}
 	delete window.navigator.modelContext;
+	delete window.navigator.modelContextTesting;
 	delete window.__mcpBridge;
 	console.log("[Web Model Context] Cleaned up");
 }