@r0hitsharma/webmcp 0.12.0-rohit-fork-ci.1

package/README.md

@@ -0,0 +1,83 @@
+# @r0hitsharma/webmcp
+
+A stable React wrapper over [WebMCP](https://github.com/webmcp-org) (`@mcp-b/global`) for registering UI tools that a connected agent harness can call. It exposes a fixed interface so the fast-moving `@mcp-b/*` packages can churn behind a single seam.
+
+Tools are registered into `document.modelContext`. A tool registered here runs in the consumer's own authenticated browser session, so it reuses the app's existing auth and APIs rather than requiring separate server credentials.
+
+## Installation
+
+```bash
+npm install @r0hitsharma/webmcp react
+```
+
+`react` is a peer dependency (>= 19).
+
+## Features
+
+- Schema-first tool definitions (`defineTool`)
+- StrictMode-safe registration that mounts/unmounts cleanly
+- A React provider that initializes the WebMCP polyfill and a tool registry
+- Hooks to register tools, observe the registry, and contribute view state
+- Wire-protocol types shared with the relay back-channel
+
+## Usage
+
+### Wrap your app
+
+```tsx
+import { WebMCPProvider } from '@r0hitsharma/webmcp';
+
+export function App() {
+  return (
+    <WebMCPProvider>
+      <YourApp />
+    </WebMCPProvider>
+  );
+}
+```
+
+### Define and register a tool
+
+The handler lives on the spec. Build the spec inside the component (or with a
+ref) when it needs to close over component state — `useRegisterTool` reads the
+latest spec through a ref, so it re-registers only when the tool *name* changes,
+never on every render.
+
+```tsx
+import { defineTool, useRegisterTool } from '@r0hitsharma/webmcp';
+
+function IdentityView({ onSelect }: { onSelect: (id: string) => void }) {
+  const selectIdentityTool = defineTool<{ identityId: string }, { selected: string }>({
+    name: 'explorer.selectIdentity',
+    description: 'Select and focus an identity node in the Explorer.',
+    schema: {
+      type: 'object',
+      properties: { identityId: { type: 'string' } },
+      required: ['identityId'],
+    },
+    handler: async ({ identityId }) => {
+      onSelect(identityId);
+      return { selected: identityId };
+    },
+  });
+
+  useRegisterTool(selectIdentityTool);
+  return null;
+}
+```
+
+## Public surface
+
+- `defineTool` — schema-first tool factory
+- `WebMCPProvider` — provider that initializes the polyfill and registry
+- `useRegisterTool` — register a tool while a component is mounted
+- `useTool` — observe a single tool's spec by name
+- `useToolRegistry` / `useToolRegistryRef` — read the full registry
+- `useContributeViewState` — contribute a partial view-state slice
+- `listTools` / `getViewState` — imperative helpers for non-React callers
+- `useRelaySession` — drive the relay back-channel from the registry: mint/reuse a session, advertise the registered tools, run incoming `invoke`s, and gate any `mutation: true` tool behind a local confirmation
+- Tool types (`ToolSpec`, `ToolHandler`, `PendingCallPrompt`, `ViewState`, ...) and the wire-protocol types re-exported from [`@r0hitsharma/mcp-relay`](../mcp-relay/README.md), the single source of truth shared with the Python relay
+
+## Related
+
+- [`@r0hitsharma/mcp-connect`](../mcp-connect/README.md) — the connection UI (chat icon, status indicator, connect modal) that pairs the browser with a harness over the relay.

package/dist/hooks.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Public hooks for @r0hitsharma/webmcp.
+ *
+ * All hooks require <WebMCPProvider> in the component tree.
+ * None of them import @mcp-b/* directly, that coupling lives in provider.tsx.
+ */
+import { type DependencyList } from 'react';
+import type { ToolSpec, ViewState } from './types.js';
+/**
+ * Register a tool while the calling component is mounted.
+ *
+ * Registers the tool into `document.modelContext` (via the @mcp-b/global
+ * polyfill) so it is exposed to any connected harness, AND registers the spec
+ * in the local ToolRegistry so `listTools()` / `getViewState()` see it.
+ *
+ * @example
+ * ```tsx
+ * import { defineTool, useRegisterTool } from '@r0hitsharma/webmcp';
+ *
+ * const selectIdentityTool = defineTool({
+ *   name: 'explorer.selectIdentity',
+ *   description: 'Select and focus an identity node in the Explorer.',
+ *   schema: {
+ *     type: 'object',
+ *     properties: { identityId: { type: 'string' } },
+ *     required: ['identityId'],
+ *   },
+ *   handler: async ({ identityId }) => {
+ *     // drive explorer state here
+ *     return { selected: identityId };
+ *   },
+ * });
+ *
+ * function IdentityGraph() {
+ *   useRegisterTool(selectIdentityTool);
+ *   return <Graph />;
+ * }
+ * ```
+ *
+ * @param spec - The tool definition created via `defineTool(...)`.
+ * @param deps - Optional dependency array.  When values change the tool is
+ *   re-registered.  Pass the same deps you would pass to `useEffect`.
+ */
+export declare function useRegisterTool<TArgs = Record<string, unknown>, TResult = unknown>(spec: ToolSpec<TArgs, TResult>, deps?: DependencyList): void;
+/**
+ * Access the execution state of a previously-registered tool by name.
+ *
+ * Returns `null` if no tool with that name is registered.
+ *
+ * Useful for components that want to observe tool activity (e.g., showing a
+ * loading spinner while `explorer.switchBranch` is executing) without owning
+ * the registration themselves.
+ */
+export declare function useTool(toolName: string): ToolSpec | null;
+/**
+ * Read-only view of the whole tool registry.
+ *
+ * @returns
+ *   - `tools` - live snapshot of all currently-registered tool specs
+ *   - `listTools()` - stable function returning the same snapshot
+ *   - `getViewState()` - aggregated view state from all contributors
+ *
+ * @example
+ * ```tsx
+ * function ConnectHarnessPanel() {
+ *   const { tools, getViewState } = useToolRegistry();
+ *   return <pre>{JSON.stringify({ count: tools.length, state: getViewState() }, null, 2)}</pre>;
+ * }
+ * ```
+ */
+export declare function useToolRegistry(): {
+    tools: ToolSpec<Record<string, unknown>, unknown>[];
+    listTools: () => ToolSpec[];
+    getViewState: () => ViewState;
+};
+/**
+ * Contribute a partial view-state slice while the calling component is mounted.
+ *
+ * The slice is merged into the object returned by `getViewState()`.
+ * On unmount the contribution is removed.
+ *
+ * @example
+ * ```tsx
+ * function BranchSelector({ selectedBranch }: { selectedBranch: string }) {
+ *   useContributeViewState({ selectedBranch });
+ *   return <select>...</select>;
+ * }
+ * ```
+ */
+export declare function useContributeViewState(partial: ViewState, deps?: DependencyList): void;
+/**
+ * Imperative accessor for the list of currently-registered tools.
+ *
+ * For use outside React components (e.g., WebSocket relay handlers that need
+ * to push a fresh `tools/list` message to the server).  Requires a registry
+ * instance obtained from `useToolRegistry()` or direct context access.
+ *
+ * @example
+ * ```ts
+ * const registry = getRegistryFromContext(ctx);
+ * const tools = listTools(registry);
+ * ws.send(JSON.stringify({ type: 'tools/list', tools: toWireFormat(tools) }));
+ * ```
+ */
+export declare function listTools(registry: {
+    listTools: () => ToolSpec[];
+}): ToolSpec[];
+/**
+ * Imperative accessor for the aggregated view state.
+ */
+export declare function getViewState(registry: {
+    getViewState: () => ViewState;
+}): ViewState;
+export type ToolRegistryRef = {
+    listTools: () => ToolSpec[];
+    getViewState: () => ViewState;
+};
+/**
+ * Returns a stable ref-shaped object pointing at the registry's imperative
+ * methods.  Useful to pass to non-React code (e.g., the WebSocket session
+ * handler) without causing re-renders.
+ */
+export declare function useToolRegistryRef(): ToolRegistryRef;

package/dist/hooks.js

@@ -0,0 +1,217 @@
+/* eslint-disable no-underscore-dangle -- the registry exposes internal-by-convention methods (_addSpec, _contributeViewState) that these public hooks wrap. */
+/**
+ * Public hooks for @r0hitsharma/webmcp.
+ *
+ * All hooks require <WebMCPProvider> in the component tree.
+ * None of them import @mcp-b/* directly, that coupling lives in provider.tsx.
+ */
+import { useEffect, useMemo, useRef } from 'react';
+import { useToolRegistryContext } from './provider.js';
+import { acquireToolRegistration } from './registration.js';
+// ---------------------------------------------------------------------------
+// useRegisterTool
+// ---------------------------------------------------------------------------
+/**
+ * Register a tool while the calling component is mounted.
+ *
+ * Registers the tool into `document.modelContext` (via the @mcp-b/global
+ * polyfill) so it is exposed to any connected harness, AND registers the spec
+ * in the local ToolRegistry so `listTools()` / `getViewState()` see it.
+ *
+ * @example
+ * ```tsx
+ * import { defineTool, useRegisterTool } from '@r0hitsharma/webmcp';
+ *
+ * const selectIdentityTool = defineTool({
+ *   name: 'explorer.selectIdentity',
+ *   description: 'Select and focus an identity node in the Explorer.',
+ *   schema: {
+ *     type: 'object',
+ *     properties: { identityId: { type: 'string' } },
+ *     required: ['identityId'],
+ *   },
+ *   handler: async ({ identityId }) => {
+ *     // drive explorer state here
+ *     return { selected: identityId };
+ *   },
+ * });
+ *
+ * function IdentityGraph() {
+ *   useRegisterTool(selectIdentityTool);
+ *   return <Graph />;
+ * }
+ * ```
+ *
+ * @param spec - The tool definition created via `defineTool(...)`.
+ * @param deps - Optional dependency array.  When values change the tool is
+ *   re-registered.  Pass the same deps you would pass to `useEffect`.
+ */
+export function useRegisterTool(spec, deps) {
+    const registry = useToolRegistryContext();
+    // `deps` is accepted for API familiarity, but registration intentionally does
+    // NOT re-run when deps change. Callers (e.g. the Explorer) build specs from
+    // unstable values (inline callbacks, freshly-derived maps) every render; if
+    // the registration effects depended on those, they would re-run each render,
+    // and the registry's bump()/setState would loop ("Maximum update depth").
+    // Instead we register once per tool name and read the latest handler/spec
+    // through a ref, so handlers always see current state without re-registering.
+    void deps;
+    const specRef = useRef(spec);
+    // Synced in an effect, not during render: refs are read-only during
+    // render. Safe here because `stableSpec`'s getters below are read lazily
+    // (only when something actually accesses `.name`/`.handler`/etc, always
+    // after this effect has run, whether that's this hook's own registration
+    // effects or a harness invoking the tool later) — no cross-component
+    // ordering to worry about, unlike a ref read by a child's own effects.
+    useEffect(() => {
+        specRef.current = spec;
+    });
+    // A stable spec object (per tool name) whose fields delegate to the latest
+    // spec via specRef. Re-renders update specRef.current; this object identity
+    // stays constant so the effects below only run on mount / name change.
+    const stableSpec = useMemo(() => ({
+        get name() {
+            return specRef.current.name;
+        },
+        get description() {
+            return specRef.current.description;
+        },
+        get schema() {
+            return specRef.current.schema;
+        },
+        get mutation() {
+            return specRef.current.mutation;
+        },
+        get confirmationSummary() {
+            return specRef.current.confirmationSummary;
+        },
+        handler: (args) => specRef.current.handler(args),
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [spec.name]);
+    // Register in the local ToolRegistry so listTools() sees it.
+    useEffect(() => {
+        return registry._addSpec(stableSpec);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [spec.name]);
+    // Register with document.modelContext through our StrictMode-safe manager
+    // (see registration.ts). We deliberately do not use @mcp-b's useWebMCP here:
+    // its effect re-runs under StrictMode in a way that races the polyfill's
+    // microtask-synced McpServer and throws "Tool <name> is already registered".
+    // The manager registers each name once, refcounted, with AbortSignal-based
+    // unregister.
+    useEffect(() => {
+        return acquireToolRegistration(stableSpec);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [spec.name]);
+}
+// ---------------------------------------------------------------------------
+// useTool
+// ---------------------------------------------------------------------------
+/**
+ * Access the execution state of a previously-registered tool by name.
+ *
+ * Returns `null` if no tool with that name is registered.
+ *
+ * Useful for components that want to observe tool activity (e.g., showing a
+ * loading spinner while `explorer.switchBranch` is executing) without owning
+ * the registration themselves.
+ */
+export function useTool(toolName) {
+    const registry = useToolRegistryContext();
+    return registry.tools.find((t) => t.name === toolName) ?? null;
+}
+// ---------------------------------------------------------------------------
+// useToolRegistry
+// ---------------------------------------------------------------------------
+/**
+ * Read-only view of the whole tool registry.
+ *
+ * @returns
+ *   - `tools` - live snapshot of all currently-registered tool specs
+ *   - `listTools()` - stable function returning the same snapshot
+ *   - `getViewState()` - aggregated view state from all contributors
+ *
+ * @example
+ * ```tsx
+ * function ConnectHarnessPanel() {
+ *   const { tools, getViewState } = useToolRegistry();
+ *   return <pre>{JSON.stringify({ count: tools.length, state: getViewState() }, null, 2)}</pre>;
+ * }
+ * ```
+ */
+export function useToolRegistry() {
+    const registry = useToolRegistryContext();
+    return {
+        tools: registry.tools,
+        listTools: registry.listTools,
+        getViewState: registry.getViewState,
+    };
+}
+// ---------------------------------------------------------------------------
+// useContributeViewState
+// ---------------------------------------------------------------------------
+/**
+ * Contribute a partial view-state slice while the calling component is mounted.
+ *
+ * The slice is merged into the object returned by `getViewState()`.
+ * On unmount the contribution is removed.
+ *
+ * @example
+ * ```tsx
+ * function BranchSelector({ selectedBranch }: { selectedBranch: string }) {
+ *   useContributeViewState({ selectedBranch });
+ *   return <select>...</select>;
+ * }
+ * ```
+ */
+export function useContributeViewState(partial, deps) {
+    const registry = useToolRegistryContext();
+    const contribute = registry._contributeViewState;
+    useEffect(() => {
+        return contribute(partial);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    deps ?? Object.values(partial));
+}
+// ---------------------------------------------------------------------------
+// Convenience re-export: listTools / getViewState as standalone functions
+// ---------------------------------------------------------------------------
+/**
+ * Imperative accessor for the list of currently-registered tools.
+ *
+ * For use outside React components (e.g., WebSocket relay handlers that need
+ * to push a fresh `tools/list` message to the server).  Requires a registry
+ * instance obtained from `useToolRegistry()` or direct context access.
+ *
+ * @example
+ * ```ts
+ * const registry = getRegistryFromContext(ctx);
+ * const tools = listTools(registry);
+ * ws.send(JSON.stringify({ type: 'tools/list', tools: toWireFormat(tools) }));
+ * ```
+ */
+export function listTools(registry) {
+    return registry.listTools();
+}
+/**
+ * Imperative accessor for the aggregated view state.
+ */
+export function getViewState(registry) {
+    return registry.getViewState();
+}
+/**
+ * Returns a stable ref-shaped object pointing at the registry's imperative
+ * methods.  Useful to pass to non-React code (e.g., the WebSocket session
+ * handler) without causing re-renders.
+ */
+export function useToolRegistryRef() {
+    const registry = useToolRegistryContext();
+    // useMemo (not useCallback-then-invoke) so the returned object keeps a stable
+    // identity across renders. Non-React consumers (e.g. a WebSocket session
+    // handler) can hold this reference without it churning every render.
+    return useMemo(() => ({
+        listTools: registry.listTools,
+        getViewState: registry.getViewState,
+    }), [registry.listTools, registry.getViewState]);
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @r0hitsharma/webmcp
+ *
+ * Stable wrapper over the @mcp-b/global polyfill, exposing a fixed interface
+ * that the rest of the codebase depends on. All @mcp-b/* churn is absorbed here.
+ *
+ * Public surface (stable contract):
+ *   - defineTool                   schema-first tool factory
+ *   - WebMCPProvider               React provider (initializes polyfill + registry)
+ *   - useRegisterTool              register a tool while mounted
+ *   - useTool                      observe a single tool's spec by name
+ *   - useToolRegistry              read the full registry (listTools / getViewState)
+ *   - useContributeViewState       contribute a partial view-state slice
+ *   - useRelaySession              drive a relay back-channel from the registry
+ *   - listTools / getViewState     imperative helpers for non-React callers
+ *   - ToolSpec / ViewState / etc.  shared types
+ *   - wire-protocol types          re-exported from @r0hitsharma/mcp-relay
+ */
+export { defineTool } from './types.js';
+export type { PendingCallPrompt, ToolHandler, ToolRegistry, ToolSpec, ViewState, } from './types.js';
+export { WebMCPProvider } from './provider.js';
+export type { WebMCPProviderProps, ToolRegistryContextValue, } from './provider.js';
+export { useRegisterTool, useTool, useToolRegistry, useContributeViewState, listTools, getViewState, useToolRegistryRef, } from './hooks.js';
+export type { ToolRegistryRef } from './hooks.js';
+export { useRelaySession } from './useRelaySession.js';
+export type { RelaySessionStatus, UseRelaySessionOptions, UseRelaySessionResult, } from './useRelaySession.js';
+export type { BrowserToServerMessage, ConnectionTokenClaims, CreateSessionResponse, HarnessStatusMessage, HelloAcceptedMessage, HelloMessage, HelloRejectedMessage, InvokeMessage, PingMessage, PongMessage, ResultMessage, ServerToBrowserMessage, ToolActivityMessage, ToolDefinition, ToolInputSchema, ToolsChangedMessage, ToolsListMessage, } from './protocol.js';

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @r0hitsharma/webmcp
+ *
+ * Stable wrapper over the @mcp-b/global polyfill, exposing a fixed interface
+ * that the rest of the codebase depends on. All @mcp-b/* churn is absorbed here.
+ *
+ * Public surface (stable contract):
+ *   - defineTool                   schema-first tool factory
+ *   - WebMCPProvider               React provider (initializes polyfill + registry)
+ *   - useRegisterTool              register a tool while mounted
+ *   - useTool                      observe a single tool's spec by name
+ *   - useToolRegistry              read the full registry (listTools / getViewState)
+ *   - useContributeViewState       contribute a partial view-state slice
+ *   - useRelaySession              drive a relay back-channel from the registry
+ *   - listTools / getViewState     imperative helpers for non-React callers
+ *   - ToolSpec / ViewState / etc.  shared types
+ *   - wire-protocol types          re-exported from @r0hitsharma/mcp-relay
+ */
+// Tool-definition contract
+export { defineTool } from './types.js';
+// Provider
+export { WebMCPProvider } from './provider.js';
+// Hooks
+export { useRegisterTool, useTool, useToolRegistry, useContributeViewState, listTools, getViewState, useToolRegistryRef, } from './hooks.js';
+// Relay session: connects the registry to a relay back-channel.
+export { useRelaySession } from './useRelaySession.js';

package/dist/protocol.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Relay wire-protocol types for the browser side.
+ *
+ * Single source of truth lives in the browser-free core
+ * `@r0hitsharma/mcp-relay`; we re-export it here so the browser widget and
+ * the relay host can never drift. (Previously these were re-declared in full;
+ * the duplicate has been collapsed.)
+ *
+ * Mutation confirmation is handled browser-side (the session hook gates a
+ * mutation invoke behind a local dialog, then returns a normal `result`), so
+ * the relay's MVP wire subset is all the browser needs — there are no
+ * confirmation_request/response frames on the wire.
+ */
+export type { BrowserToServerMessage, ConnectionTokenClaims, CreateSessionResponse, HarnessStatusMessage, HelloAcceptedMessage, HelloMessage, HelloRejectedMessage, InvokeMessage, PingMessage, PongMessage, ResultMessage, ServerToBrowserMessage, ToolActivityMessage, ToolDefinition, ToolInputSchema, ToolsChangedMessage, ToolsListMessage, } from '@r0hitsharma/mcp-relay';

package/dist/protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/provider.d.ts

@@ -0,0 +1,71 @@
+/**
+ * WebMCPProvider
+ *
+ * Wraps @mcp-b/global initialization (installs the document.modelContext
+ * polyfill) and exposes a ToolRegistryContext so that useRegisterTool /
+ * useToolRegistry hooks can work together without redundant polyfill calls.
+ *
+ * Absorbs @mcp-b churn: callers never import @mcp-b/* directly.
+ */
+import { type ReactNode } from 'react';
+import type { ToolSpec, ViewState } from './types.js';
+/**
+ * Internal registry kept by the provider so `listTools` and `getViewState`
+ * have something to read synchronously.
+ *
+ * Registration is additive: each `useRegisterTool` call pushes its spec into
+ * the registry while mounted and removes it on unmount.
+ */
+export interface ToolRegistryContextValue {
+    /**
+     * Snapshot of all currently-registered tool specs.
+     * Re-computed whenever any tool mounts or unmounts.
+     */
+    tools: ToolSpec[];
+    /**
+     * Returns a snapshot of every registered tool spec at call time.
+     */
+    listTools: () => ToolSpec[];
+    /**
+     * Returns the current view state aggregated from all registered context
+     * contributions.  Starts empty; components hydrate it via setViewState.
+     */
+    getViewState: () => ViewState;
+    /**
+     * Called by hooks to add a spec to the registry.
+     * Returns a cleanup function that removes it.
+     */
+    _addSpec: (spec: ToolSpec) => () => void;
+    /**
+     * Called by view-state contributor hooks to merge partial state.
+     * Returns a cleanup function that removes the contribution.
+     */
+    _contributeViewState: (partial: ViewState) => () => void;
+}
+export interface WebMCPProviderProps {
+    children: ReactNode;
+    /**
+     * Pass `false` to skip polyfill initialization (useful in tests or SSR).
+     * @default true
+     */
+    initPolyfill?: boolean;
+}
+/**
+ * Mount this provider once near the root of your React tree before using
+ * any hooks from @r0hitsharma/webmcp.
+ *
+ * @example
+ * ```tsx
+ * import { WebMCPProvider } from '@r0hitsharma/webmcp';
+ *
+ * function App() {
+ *   return (
+ *     <WebMCPProvider>
+ *       <Explorer />
+ *     </WebMCPProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function WebMCPProvider({ children, initPolyfill, }: WebMCPProviderProps): import("react").JSX.Element;
+export declare function useToolRegistryContext(): ToolRegistryContextValue;

package/dist/provider.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* eslint-disable no-underscore-dangle -- the registry exposes internal-by-convention methods (_addSpec, _contributeViewState) that the public hooks wrap. */
+import { cleanupWebModelContext, initializeWebModelContext, } from '@mcp-b/global';
+/**
+ * WebMCPProvider
+ *
+ * Wraps @mcp-b/global initialization (installs the document.modelContext
+ * polyfill) and exposes a ToolRegistryContext so that useRegisterTool /
+ * useToolRegistry hooks can work together without redundant polyfill calls.
+ *
+ * Absorbs @mcp-b churn: callers never import @mcp-b/* directly.
+ */
+import { createContext, useCallback, useContext, useEffect, useRef, useSyncExternalStore, } from 'react';
+const ToolRegistryContext = createContext(null);
+/**
+ * Mount this provider once near the root of your React tree before using
+ * any hooks from @r0hitsharma/webmcp.
+ *
+ * @example
+ * ```tsx
+ * import { WebMCPProvider } from '@r0hitsharma/webmcp';
+ *
+ * function App() {
+ *   return (
+ *     <WebMCPProvider>
+ *       <Explorer />
+ *     </WebMCPProvider>
+ *   );
+ * }
+ * ```
+ */
+export function WebMCPProvider({ children, initPolyfill = true, }) {
+    // Stable refs so the context value object is referentially stable.
+    const toolMapRef = useRef(new Map());
+    const viewStateRef = useRef(new Map());
+    // `tools` is exposed to render via `useSyncExternalStore` — refs aren't
+    // safe to read during render, so `toolMapRef` itself never is; `bump`
+    // recomputes a snapshot array and notifies subscribers instead.
+    const toolsSnapshotRef = useRef([]);
+    const listenersRef = useRef(new Set());
+    const subscribeTools = useCallback((listener) => {
+        listenersRef.current.add(listener);
+        return () => {
+            listenersRef.current.delete(listener);
+        };
+    }, []);
+    const getToolsSnapshot = useCallback(() => toolsSnapshotRef.current, []);
+    const bump = useCallback(() => {
+        toolsSnapshotRef.current = Array.from(toolMapRef.current.values());
+        for (const listener of listenersRef.current)
+            listener();
+    }, []);
+    // Initialize the document.modelContext polyfill on mount.
+    useEffect(() => {
+        if (!initPolyfill)
+            return;
+        initializeWebModelContext({ autoInitialize: true });
+        return () => {
+            cleanupWebModelContext();
+        };
+    }, [initPolyfill]);
+    const _addSpec = useCallback((spec) => {
+        toolMapRef.current.set(spec.name, spec);
+        bump();
+        return () => {
+            toolMapRef.current.delete(spec.name);
+            bump();
+        };
+    }, [bump]);
+    const _contributeViewState = useCallback((partial) => {
+        // Use object identity as key.
+        const key = Math.random().toString(36).slice(2);
+        viewStateRef.current.set(key, partial);
+        return () => {
+            viewStateRef.current.delete(key);
+        };
+    }, []);
+    const listTools = useCallback(() => {
+        return Array.from(toolMapRef.current.values());
+    }, []);
+    const getViewState = useCallback(() => {
+        const merged = {};
+        for (const partial of viewStateRef.current.values()) {
+            Object.assign(merged, partial);
+        }
+        return merged;
+    }, []);
+    // No effect ever runs during server rendering, so `toolsSnapshotRef` is
+    // still at its initial (empty) value then — safe to reuse `getToolsSnapshot`
+    // as the server snapshot too.
+    const tools = useSyncExternalStore(subscribeTools, getToolsSnapshot, getToolsSnapshot);
+    const value = {
+        tools,
+        listTools,
+        getViewState,
+        _addSpec,
+        _contributeViewState,
+    };
+    return (_jsx(ToolRegistryContext.Provider, { value: value, children: children }));
+}
+// ---------------------------------------------------------------------------
+// Internal hook to access the registry context (throws if not mounted)
+// ---------------------------------------------------------------------------
+export function useToolRegistryContext() {
+    const ctx = useContext(ToolRegistryContext);
+    if (!ctx) {
+        throw new Error('[web-mcp] useToolRegistryContext called outside <WebMCPProvider>. ' +
+            'Wrap your app (or at least the component tree that uses @r0hitsharma/webmcp hooks) ' +
+            'with <WebMCPProvider>.');
+    }
+    return ctx;
+}