@tooluminati/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jitterbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/WebMcpContext.d.ts

@@ -0,0 +1,11 @@
+import type { PolicyContext, WebMcpRegistry } from '@tooluminati/core';
+import type { WebMcpPolicySet } from '@tooluminati/policies';
+export interface WebMcpReactContextValue {
+    registry: WebMcpRegistry;
+    enabled: boolean;
+    policies?: WebMcpPolicySet;
+    policyContext?: PolicyContext | undefined;
+    namespace?: string | undefined;
+}
+export declare const WebMcpContext: import("react").Context<WebMcpReactContextValue | null>;
+//# sourceMappingURL=WebMcpContext.d.ts.map

package/dist/WebMcpContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebMcpContext.d.ts","sourceRoot":"","sources":["../src/WebMcpContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,eAAO,MAAM,aAAa,yDAEzB,CAAC"}

package/dist/WebMcpContext.js

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const WebMcpContext = createContext(null);

package/dist/WebMcpProvider.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import { type PolicyContext, type WebMcpRegistryOptions, type WebMcpToolDescriptor } from '@tooluminati/core';
+import { type WebMcpPolicySet } from '@tooluminati/policies';
+export interface WebMcpProviderProps {
+    children: ReactNode;
+    tools?: WebMcpToolDescriptor[];
+    enabled?: boolean;
+    strict?: boolean;
+    namespace?: string;
+    policies?: WebMcpPolicySet;
+    policyContext?: PolicyContext;
+    modelContext?: WebMcpRegistryOptions['modelContext'];
+    getAppContext?: () => unknown;
+    onSecurityWarning?: WebMcpRegistryOptions['onSecurityWarning'];
+    onError?: WebMcpRegistryOptions['onError'];
+}
+export declare function WebMcpProvider({ children, tools, enabled, strict, namespace, policies, policyContext, modelContext, getAppContext, onSecurityWarning, onError, }: WebMcpProviderProps): import("react").JSX.Element;
+//# sourceMappingURL=WebMcpProvider.d.ts.map

package/dist/WebMcpProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebMcpProvider.d.ts","sourceRoot":"","sources":["../src/WebMcpProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,qBAAqB,CAAC,cAAc,CAAC,CAAC;IACrD,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;IAC/D,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,KAAU,EACV,OAAe,EACf,MAAc,EACd,SAAS,EACT,QAAyB,EACzB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,OAAO,GACR,EAAE,mBAAmB,+BA0ErB"}

package/dist/WebMcpProvider.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useEffect, useMemo, } from 'react';
+import { WebMcpRegistry, } from '@tooluminati/core';
+import { localDevPolicy, } from '@tooluminati/policies';
+import { WebMcpContext } from './WebMcpContext';
+export function WebMcpProvider({ children, tools = [], enabled = false, strict = false, namespace, policies = localDevPolicy, policyContext, modelContext, getAppContext, onSecurityWarning, onError, }) {
+    const parentContext = useContext(WebMcpContext);
+    useEffect(() => {
+        if (parentContext &&
+            namespace === undefined &&
+            typeof process !== 'undefined' &&
+            process.env.NODE_ENV !== 'production') {
+            console.warn('[tooluminati] Nested WebMcpProvider detected without a namespace. Provide namespace to avoid tool collisions.');
+        }
+    }, [namespace, parentContext]);
+    const registry = useMemo(() => new WebMcpRegistry({
+        enabled,
+        strict,
+        namespace,
+        policies,
+        policyContext,
+        modelContext,
+        getAppContext,
+        onSecurityWarning,
+        onError,
+    }), [
+        enabled,
+        getAppContext,
+        modelContext,
+        namespace,
+        onError,
+        onSecurityWarning,
+        policies,
+        policyContext,
+        strict,
+    ]);
+    useEffect(() => {
+        const registrations = tools.map((tool) => registry.registerTool(tool, { source: 'provider' }));
+        return () => {
+            for (const registration of registrations) {
+                registration.abort();
+            }
+        };
+    }, [registry, tools]);
+    useEffect(() => () => registry.unregisterAll(), [registry]);
+    const value = useMemo(() => {
+        const next = {
+            registry,
+            enabled,
+            policies,
+        };
+        if (policyContext !== undefined) {
+            next.policyContext = policyContext;
+        }
+        if (namespace !== undefined) {
+            next.namespace = namespace;
+        }
+        return next;
+    }, [enabled, namespace, policies, policyContext, registry]);
+    return (_jsx(WebMcpContext.Provider, { value: value, children: children }));
+}

package/dist/WebMcpScope.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+import type { WebMcpToolDescriptor, WebMcpToolSource } from '@tooluminati/core';
+export interface WebMcpScopeProps {
+    children: ReactNode;
+    tools: WebMcpToolDescriptor[];
+    source?: WebMcpToolSource;
+    namespaceSegment?: string | undefined;
+}
+export declare function WebMcpScope({ children, tools, source, namespaceSegment, }: WebMcpScopeProps): import("react").JSX.Element;
+//# sourceMappingURL=WebMcpScope.d.ts.map

package/dist/WebMcpScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebMcpScope.d.ts","sourceRoot":"","sources":["../src/WebMcpScope.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,KAAK,EACL,MAAgB,EAChB,gBAAgB,GACjB,EAAE,gBAAgB,+BAkBlB"}

package/dist/WebMcpScope.js

@@ -0,0 +1,16 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { useWebMcpContextValue } from './useWebMcpRegistry';
+import { useWebMcpTools } from './useWebMcpTools';
+export function WebMcpScope({ children, tools, source = 'scope', namespaceSegment, }) {
+    const { namespace } = useWebMcpContextValue();
+    const scopedTools = useMemo(() => namespaceSegment
+        ? tools.map((tool) => ({
+            ...tool,
+            name: `${namespaceSegment}.${tool.name}`,
+        }))
+        : tools, [namespaceSegment, tools]);
+    void namespace;
+    useWebMcpTools(scopedTools, [scopedTools], { source });
+    return _jsx(_Fragment, { children: children });
+}

package/dist/WebMcpSecurityBanner.d.ts

@@ -0,0 +1,2 @@
+export declare function WebMcpSecurityBanner(): import("react").JSX.Element | null;
+//# sourceMappingURL=WebMcpSecurityBanner.d.ts.map

package/dist/WebMcpSecurityBanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebMcpSecurityBanner.d.ts","sourceRoot":"","sources":["../src/WebMcpSecurityBanner.tsx"],"names":[],"mappings":"AAEA,wBAAgB,oBAAoB,uCAsBnC"}

package/dist/WebMcpSecurityBanner.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useWebMcpSecurityBanner } from './useWebMcpSecurityBanner';
+export function WebMcpSecurityBanner() {
+    const banner = useWebMcpSecurityBanner();
+    if (!banner.enabled) {
+        return null;
+    }
+    return (_jsxs("aside", { "aria-live": "polite", style: {
+            background: '#fff3cd',
+            border: '1px solid #ffeeba',
+            color: '#856404',
+            padding: '0.75rem 1rem',
+            marginBottom: '1rem',
+        }, children: [_jsx("strong", { children: "Tooluminati diagnostics enabled." }), " ", banner.message, " Registered tools: ", banner.registeredTools.join(', ') || 'none', "."] }));
+}

package/dist/index.cjs

@@ -0,0 +1,314 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  WebMcpContext: () => WebMcpContext,
+  WebMcpProvider: () => WebMcpProvider,
+  WebMcpScope: () => WebMcpScope,
+  WebMcpSecurityBanner: () => WebMcpSecurityBanner,
+  useLatestRef: () => useLatestRef,
+  useStableTool: () => useStableTool,
+  useWebMcpContextValue: () => useWebMcpContextValue,
+  useWebMcpRegistry: () => useWebMcpRegistry,
+  useWebMcpSecurityBanner: () => useWebMcpSecurityBanner,
+  useWebMcpTool: () => useWebMcpTool,
+  useWebMcpTools: () => useWebMcpTools
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/WebMcpContext.tsx
+var import_react = require("react");
+var WebMcpContext = (0, import_react.createContext)(
+  null
+);
+
+// src/WebMcpProvider.tsx
+var import_react2 = require("react");
+var import_core = require("@tooluminati/core");
+var import_policies = require("@tooluminati/policies");
+var import_jsx_runtime = require("react/jsx-runtime");
+function WebMcpProvider({
+  children,
+  tools = [],
+  enabled = false,
+  strict = false,
+  namespace,
+  policies = import_policies.localDevPolicy,
+  policyContext,
+  modelContext,
+  getAppContext,
+  onSecurityWarning,
+  onError
+}) {
+  const parentContext = (0, import_react2.useContext)(WebMcpContext);
+  (0, import_react2.useEffect)(() => {
+    if (parentContext && namespace === void 0 && typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[tooluminati] Nested WebMcpProvider detected without a namespace. Provide namespace to avoid tool collisions."
+      );
+    }
+  }, [namespace, parentContext]);
+  const registry = (0, import_react2.useMemo)(
+    () => new import_core.WebMcpRegistry({
+      enabled,
+      strict,
+      namespace,
+      policies,
+      policyContext,
+      modelContext,
+      getAppContext,
+      onSecurityWarning,
+      onError
+    }),
+    [
+      enabled,
+      getAppContext,
+      modelContext,
+      namespace,
+      onError,
+      onSecurityWarning,
+      policies,
+      policyContext,
+      strict
+    ]
+  );
+  (0, import_react2.useEffect)(() => {
+    const registrations = tools.map(
+      (tool) => registry.registerTool(tool, { source: "provider" })
+    );
+    return () => {
+      for (const registration of registrations) {
+        registration.abort();
+      }
+    };
+  }, [registry, tools]);
+  (0, import_react2.useEffect)(() => () => registry.unregisterAll(), [registry]);
+  const value = (0, import_react2.useMemo)(() => {
+    const next = {
+      registry,
+      enabled,
+      policies
+    };
+    if (policyContext !== void 0) {
+      next.policyContext = policyContext;
+    }
+    if (namespace !== void 0) {
+      next.namespace = namespace;
+    }
+    return next;
+  }, [enabled, namespace, policies, policyContext, registry]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(WebMcpContext.Provider, { value, children });
+}
+
+// src/WebMcpScope.tsx
+var import_react5 = require("react");
+
+// src/useWebMcpRegistry.ts
+var import_react3 = require("react");
+function useWebMcpRegistry() {
+  const context = (0, import_react3.useContext)(WebMcpContext);
+  if (!context) {
+    throw new Error("useWebMcpRegistry must be used within WebMcpProvider.");
+  }
+  return context.registry;
+}
+function useWebMcpContextValue(fallbackRegistry) {
+  const context = (0, import_react3.useContext)(WebMcpContext);
+  if (!context && !fallbackRegistry) {
+    throw new Error("WebMCP hooks must be used within WebMcpProvider.");
+  }
+  if (context) {
+    return context;
+  }
+  return {
+    registry: fallbackRegistry,
+    enabled: false
+  };
+}
+
+// src/useWebMcpTools.ts
+var import_react4 = require("react");
+function useWebMcpTools(tools, deps = [], options = {}) {
+  const { registry } = useWebMcpContextValue();
+  const exposedTo = options.exposedTo;
+  const source = options.source ?? "scope";
+  (0, import_react4.useEffect)(() => {
+    const registrations = tools.map(
+      (tool) => registry.registerTool(tool, {
+        ...options,
+        source
+      })
+    );
+    return () => {
+      for (const registration of registrations) {
+        registration.abort();
+      }
+    };
+  }, [registry, tools, exposedTo, source, ...deps]);
+}
+
+// src/WebMcpScope.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function WebMcpScope({
+  children,
+  tools,
+  source = "scope",
+  namespaceSegment
+}) {
+  const { namespace } = useWebMcpContextValue();
+  const scopedTools = (0, import_react5.useMemo)(
+    () => namespaceSegment ? tools.map((tool) => ({
+      ...tool,
+      name: `${namespaceSegment}.${tool.name}`
+    })) : tools,
+    [namespaceSegment, tools]
+  );
+  void namespace;
+  useWebMcpTools(scopedTools, [scopedTools], { source });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children });
+}
+
+// src/useLatestRef.ts
+var import_react6 = require("react");
+function useLatestRef(value) {
+  const ref = (0, import_react6.useRef)(value);
+  (0, import_react6.useLayoutEffect)(() => {
+    ref.current = value;
+  });
+  return ref;
+}
+
+// src/useStableTool.ts
+var import_react7 = require("react");
+function useStableTool(factory, deps) {
+  return (0, import_react7.useMemo)(factory, deps);
+}
+
+// src/useWebMcpSecurityBanner.ts
+var import_react8 = require("react");
+var import_core2 = require("@tooluminati/core");
+function useWebMcpSecurityBanner() {
+  const { enabled, registry } = useWebMcpContextValue();
+  return (0, import_react8.useMemo)(
+    () => ({
+      enabled,
+      supported: (0, import_core2.isWebMcpSupported)(),
+      registeredTools: registry.getRegisteredToolNames(),
+      message: enabled ? "Tooluminati diagnostics are enabled for this page." : "Tooluminati diagnostics are disabled."
+    }),
+    [enabled, registry]
+  );
+}
+
+// src/WebMcpSecurityBanner.tsx
+var import_jsx_runtime3 = require("react/jsx-runtime");
+function WebMcpSecurityBanner() {
+  const banner = useWebMcpSecurityBanner();
+  if (!banner.enabled) {
+    return null;
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+    "aside",
+    {
+      "aria-live": "polite",
+      style: {
+        background: "#fff3cd",
+        border: "1px solid #ffeeba",
+        color: "#856404",
+        padding: "0.75rem 1rem",
+        marginBottom: "1rem"
+      },
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("strong", { children: "Tooluminati diagnostics enabled." }),
+        " ",
+        banner.message,
+        " Registered tools: ",
+        banner.registeredTools.join(", ") || "none",
+        "."
+      ]
+    }
+  );
+}
+
+// src/useWebMcpTool.ts
+var import_react9 = require("react");
+function stableSerialize(value) {
+  return JSON.stringify(
+    value,
+    (_key, current) => current && typeof current === "object" && !Array.isArray(current) ? Object.keys(current).sort().reduce((accumulator, key) => {
+      accumulator[key] = current[key];
+      return accumulator;
+    }, {}) : current
+  );
+}
+function useWebMcpTool(tool, deps = [], options = {}) {
+  const context = useWebMcpContextValue(options.fallbackRegistry);
+  const registry = options.fallbackRegistry ?? context.registry;
+  const toolRef = useLatestRef(tool);
+  const definitionKey = (0, import_react9.useMemo)(
+    () => stableSerialize({
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
+      exposedTo: options.exposedTo,
+      source: options.source
+    }),
+    [
+      tool.name,
+      tool.title,
+      tool.description,
+      tool.inputSchema,
+      tool.annotations,
+      options.exposedTo,
+      options.source
+    ]
+  );
+  (0, import_react9.useEffect)(() => {
+    const latest = toolRef.current;
+    const registration = registry.registerTool(
+      {
+        ...latest,
+        execute: (args, executionContext) => toolRef.current.execute(args, executionContext)
+      },
+      {
+        ...options,
+        source: options.source ?? "hook"
+      }
+    );
+    return () => registration.abort();
+  }, [definitionKey, registry, toolRef, options.exposedTo, options.source, ...deps]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WebMcpContext,
+  WebMcpProvider,
+  WebMcpScope,
+  WebMcpSecurityBanner,
+  useLatestRef,
+  useStableTool,
+  useWebMcpContextValue,
+  useWebMcpRegistry,
+  useWebMcpSecurityBanner,
+  useWebMcpTool,
+  useWebMcpTools
+});

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @experimental Tooluminati React bindings — public APIs may change.
+ */
+export * from './WebMcpContext';
+export * from './WebMcpProvider';
+export * from './WebMcpScope';
+export * from './useLatestRef';
+export * from './useStableTool';
+export * from './useWebMcpRegistry';
+export * from './WebMcpSecurityBanner';
+export * from './useWebMcpSecurityBanner';
+export * from './useWebMcpTool';
+export * from './useWebMcpTools';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,285 @@
+// src/WebMcpContext.tsx
+import { createContext } from "react";
+var WebMcpContext = createContext(
+  null
+);
+
+// src/WebMcpProvider.tsx
+import {
+  useContext,
+  useEffect,
+  useMemo
+} from "react";
+import {
+  WebMcpRegistry
+} from "@tooluminati/core";
+import {
+  localDevPolicy
+} from "@tooluminati/policies";
+import { jsx } from "react/jsx-runtime";
+function WebMcpProvider({
+  children,
+  tools = [],
+  enabled = false,
+  strict = false,
+  namespace,
+  policies = localDevPolicy,
+  policyContext,
+  modelContext,
+  getAppContext,
+  onSecurityWarning,
+  onError
+}) {
+  const parentContext = useContext(WebMcpContext);
+  useEffect(() => {
+    if (parentContext && namespace === void 0 && typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[tooluminati] Nested WebMcpProvider detected without a namespace. Provide namespace to avoid tool collisions."
+      );
+    }
+  }, [namespace, parentContext]);
+  const registry = useMemo(
+    () => new WebMcpRegistry({
+      enabled,
+      strict,
+      namespace,
+      policies,
+      policyContext,
+      modelContext,
+      getAppContext,
+      onSecurityWarning,
+      onError
+    }),
+    [
+      enabled,
+      getAppContext,
+      modelContext,
+      namespace,
+      onError,
+      onSecurityWarning,
+      policies,
+      policyContext,
+      strict
+    ]
+  );
+  useEffect(() => {
+    const registrations = tools.map(
+      (tool) => registry.registerTool(tool, { source: "provider" })
+    );
+    return () => {
+      for (const registration of registrations) {
+        registration.abort();
+      }
+    };
+  }, [registry, tools]);
+  useEffect(() => () => registry.unregisterAll(), [registry]);
+  const value = useMemo(() => {
+    const next = {
+      registry,
+      enabled,
+      policies
+    };
+    if (policyContext !== void 0) {
+      next.policyContext = policyContext;
+    }
+    if (namespace !== void 0) {
+      next.namespace = namespace;
+    }
+    return next;
+  }, [enabled, namespace, policies, policyContext, registry]);
+  return /* @__PURE__ */ jsx(WebMcpContext.Provider, { value, children });
+}
+
+// src/WebMcpScope.tsx
+import { useMemo as useMemo2 } from "react";
+
+// src/useWebMcpRegistry.ts
+import { useContext as useContext2 } from "react";
+function useWebMcpRegistry() {
+  const context = useContext2(WebMcpContext);
+  if (!context) {
+    throw new Error("useWebMcpRegistry must be used within WebMcpProvider.");
+  }
+  return context.registry;
+}
+function useWebMcpContextValue(fallbackRegistry) {
+  const context = useContext2(WebMcpContext);
+  if (!context && !fallbackRegistry) {
+    throw new Error("WebMCP hooks must be used within WebMcpProvider.");
+  }
+  if (context) {
+    return context;
+  }
+  return {
+    registry: fallbackRegistry,
+    enabled: false
+  };
+}
+
+// src/useWebMcpTools.ts
+import { useEffect as useEffect2 } from "react";
+function useWebMcpTools(tools, deps = [], options = {}) {
+  const { registry } = useWebMcpContextValue();
+  const exposedTo = options.exposedTo;
+  const source = options.source ?? "scope";
+  useEffect2(() => {
+    const registrations = tools.map(
+      (tool) => registry.registerTool(tool, {
+        ...options,
+        source
+      })
+    );
+    return () => {
+      for (const registration of registrations) {
+        registration.abort();
+      }
+    };
+  }, [registry, tools, exposedTo, source, ...deps]);
+}
+
+// src/WebMcpScope.tsx
+import { Fragment, jsx as jsx2 } from "react/jsx-runtime";
+function WebMcpScope({
+  children,
+  tools,
+  source = "scope",
+  namespaceSegment
+}) {
+  const { namespace } = useWebMcpContextValue();
+  const scopedTools = useMemo2(
+    () => namespaceSegment ? tools.map((tool) => ({
+      ...tool,
+      name: `${namespaceSegment}.${tool.name}`
+    })) : tools,
+    [namespaceSegment, tools]
+  );
+  void namespace;
+  useWebMcpTools(scopedTools, [scopedTools], { source });
+  return /* @__PURE__ */ jsx2(Fragment, { children });
+}
+
+// src/useLatestRef.ts
+import { useLayoutEffect, useRef } from "react";
+function useLatestRef(value) {
+  const ref = useRef(value);
+  useLayoutEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+}
+
+// src/useStableTool.ts
+import { useMemo as useMemo3 } from "react";
+function useStableTool(factory, deps) {
+  return useMemo3(factory, deps);
+}
+
+// src/useWebMcpSecurityBanner.ts
+import { useMemo as useMemo4 } from "react";
+import { isWebMcpSupported } from "@tooluminati/core";
+function useWebMcpSecurityBanner() {
+  const { enabled, registry } = useWebMcpContextValue();
+  return useMemo4(
+    () => ({
+      enabled,
+      supported: isWebMcpSupported(),
+      registeredTools: registry.getRegisteredToolNames(),
+      message: enabled ? "Tooluminati diagnostics are enabled for this page." : "Tooluminati diagnostics are disabled."
+    }),
+    [enabled, registry]
+  );
+}
+
+// src/WebMcpSecurityBanner.tsx
+import { jsx as jsx3, jsxs } from "react/jsx-runtime";
+function WebMcpSecurityBanner() {
+  const banner = useWebMcpSecurityBanner();
+  if (!banner.enabled) {
+    return null;
+  }
+  return /* @__PURE__ */ jsxs(
+    "aside",
+    {
+      "aria-live": "polite",
+      style: {
+        background: "#fff3cd",
+        border: "1px solid #ffeeba",
+        color: "#856404",
+        padding: "0.75rem 1rem",
+        marginBottom: "1rem"
+      },
+      children: [
+        /* @__PURE__ */ jsx3("strong", { children: "Tooluminati diagnostics enabled." }),
+        " ",
+        banner.message,
+        " Registered tools: ",
+        banner.registeredTools.join(", ") || "none",
+        "."
+      ]
+    }
+  );
+}
+
+// src/useWebMcpTool.ts
+import { useEffect as useEffect3, useMemo as useMemo5 } from "react";
+function stableSerialize(value) {
+  return JSON.stringify(
+    value,
+    (_key, current) => current && typeof current === "object" && !Array.isArray(current) ? Object.keys(current).sort().reduce((accumulator, key) => {
+      accumulator[key] = current[key];
+      return accumulator;
+    }, {}) : current
+  );
+}
+function useWebMcpTool(tool, deps = [], options = {}) {
+  const context = useWebMcpContextValue(options.fallbackRegistry);
+  const registry = options.fallbackRegistry ?? context.registry;
+  const toolRef = useLatestRef(tool);
+  const definitionKey = useMemo5(
+    () => stableSerialize({
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
+      exposedTo: options.exposedTo,
+      source: options.source
+    }),
+    [
+      tool.name,
+      tool.title,
+      tool.description,
+      tool.inputSchema,
+      tool.annotations,
+      options.exposedTo,
+      options.source
+    ]
+  );
+  useEffect3(() => {
+    const latest = toolRef.current;
+    const registration = registry.registerTool(
+      {
+        ...latest,
+        execute: (args, executionContext) => toolRef.current.execute(args, executionContext)
+      },
+      {
+        ...options,
+        source: options.source ?? "hook"
+      }
+    );
+    return () => registration.abort();
+  }, [definitionKey, registry, toolRef, options.exposedTo, options.source, ...deps]);
+}
+export {
+  WebMcpContext,
+  WebMcpProvider,
+  WebMcpScope,
+  WebMcpSecurityBanner,
+  useLatestRef,
+  useStableTool,
+  useWebMcpContextValue,
+  useWebMcpRegistry,
+  useWebMcpSecurityBanner,
+  useWebMcpTool,
+  useWebMcpTools
+};

package/dist/useLatestRef.d.ts

@@ -0,0 +1,2 @@
+export declare function useLatestRef<T>(value: T): import("react").RefObject<T>;
+//# sourceMappingURL=useLatestRef.d.ts.map

package/dist/useLatestRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLatestRef.d.ts","sourceRoot":"","sources":["../src/useLatestRef.ts"],"names":[],"mappings":"AAEA,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,gCAQvC"}

package/dist/useLatestRef.js

@@ -0,0 +1,8 @@
+import { useLayoutEffect, useRef } from 'react';
+export function useLatestRef(value) {
+    const ref = useRef(value);
+    useLayoutEffect(() => {
+        ref.current = value;
+    });
+    return ref;
+}

package/dist/useStableTool.d.ts

@@ -0,0 +1,4 @@
+import { type DependencyList } from 'react';
+import type { WebMcpToolDescriptor } from '@tooluminati/core';
+export declare function useStableTool<TArgs, TResult>(factory: () => WebMcpToolDescriptor<TArgs, TResult>, deps: DependencyList): WebMcpToolDescriptor<TArgs, TResult>;
+//# sourceMappingURL=useStableTool.d.ts.map

package/dist/useStableTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStableTool.d.ts","sourceRoot":"","sources":["../src/useStableTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAC1C,OAAO,EAAE,MAAM,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,EACnD,IAAI,EAAE,cAAc,GACnB,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAEtC"}

package/dist/useStableTool.js

@@ -0,0 +1,4 @@
+import { useMemo } from 'react';
+export function useStableTool(factory, deps) {
+    return useMemo(factory, deps);
+}

package/dist/useWebMcpRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { WebMcpRegistry } from '@tooluminati/core';
+export declare function useWebMcpRegistry(): WebMcpRegistry;
+export declare function useWebMcpContextValue(fallbackRegistry?: WebMcpRegistry): import("./WebMcpContext").WebMcpReactContextValue;
+//# sourceMappingURL=useWebMcpRegistry.d.ts.map

package/dist/useWebMcpRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWebMcpRegistry.d.ts","sourceRoot":"","sources":["../src/useWebMcpRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,wBAAgB,iBAAiB,mBAQhC;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,CAAC,EAAE,cAAc,qDAetE"}

package/dist/useWebMcpRegistry.js

@@ -0,0 +1,22 @@
+import { useContext } from 'react';
+import { WebMcpContext } from './WebMcpContext';
+export function useWebMcpRegistry() {
+    const context = useContext(WebMcpContext);
+    if (!context) {
+        throw new Error('useWebMcpRegistry must be used within WebMcpProvider.');
+    }
+    return context.registry;
+}
+export function useWebMcpContextValue(fallbackRegistry) {
+    const context = useContext(WebMcpContext);
+    if (!context && !fallbackRegistry) {
+        throw new Error('WebMCP hooks must be used within WebMcpProvider.');
+    }
+    if (context) {
+        return context;
+    }
+    return {
+        registry: fallbackRegistry,
+        enabled: false,
+    };
+}

package/dist/useWebMcpSecurityBanner.d.ts

@@ -0,0 +1,7 @@
+export declare function useWebMcpSecurityBanner(): {
+    enabled: boolean;
+    supported: boolean;
+    registeredTools: string[];
+    message: string;
+};
+//# sourceMappingURL=useWebMcpSecurityBanner.d.ts.map

package/dist/useWebMcpSecurityBanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWebMcpSecurityBanner.d.ts","sourceRoot":"","sources":["../src/useWebMcpSecurityBanner.ts"],"names":[],"mappings":"AAIA,wBAAgB,uBAAuB;;;;;EActC"}

package/dist/useWebMcpSecurityBanner.js

@@ -0,0 +1,14 @@
+import { useMemo } from 'react';
+import { isWebMcpSupported } from '@tooluminati/core';
+import { useWebMcpContextValue } from './useWebMcpRegistry';
+export function useWebMcpSecurityBanner() {
+    const { enabled, registry } = useWebMcpContextValue();
+    return useMemo(() => ({
+        enabled,
+        supported: isWebMcpSupported(),
+        registeredTools: registry.getRegisteredToolNames(),
+        message: enabled
+            ? 'Tooluminati diagnostics are enabled for this page.'
+            : 'Tooluminati diagnostics are disabled.',
+    }), [enabled, registry]);
+}

package/dist/useWebMcpTool.d.ts

@@ -0,0 +1,7 @@
+import { type DependencyList } from 'react';
+import type { RegisterToolOptions, WebMcpRegistry, WebMcpToolDescriptor } from '@tooluminati/core';
+export interface UseWebMcpToolOptions extends RegisterToolOptions {
+    fallbackRegistry?: WebMcpRegistry;
+}
+export declare function useWebMcpTool<TArgs, TResult>(tool: WebMcpToolDescriptor<TArgs, TResult>, deps?: DependencyList, options?: UseWebMcpToolOptions): void;
+//# sourceMappingURL=useWebMcpTool.d.ts.map

package/dist/useWebMcpTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWebMcpTool.d.ts","sourceRoot":"","sources":["../src/useWebMcpTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAChE,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,gBAAgB,CAAC,EAAE,cAAc,CAAC;CACnC;AAeD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAC1C,IAAI,EAAE,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,EAC1C,IAAI,GAAE,cAAmB,EACzB,OAAO,GAAE,oBAAyB,GACjC,IAAI,CA2CN"}

package/dist/useWebMcpTool.js

@@ -0,0 +1,46 @@
+import { useEffect, useMemo } from 'react';
+import { useLatestRef } from './useLatestRef';
+import { useWebMcpContextValue } from './useWebMcpRegistry';
+function stableSerialize(value) {
+    return JSON.stringify(value, (_key, current) => current && typeof current === 'object' && !Array.isArray(current)
+        ? Object.keys(current)
+            .sort()
+            .reduce((accumulator, key) => {
+            accumulator[key] = current[key];
+            return accumulator;
+        }, {})
+        : current);
+}
+export function useWebMcpTool(tool, deps = [], options = {}) {
+    const context = useWebMcpContextValue(options.fallbackRegistry);
+    const registry = options.fallbackRegistry ?? context.registry;
+    const toolRef = useLatestRef(tool);
+    const definitionKey = useMemo(() => stableSerialize({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: tool.annotations,
+        exposedTo: options.exposedTo,
+        source: options.source,
+    }), [
+        tool.name,
+        tool.title,
+        tool.description,
+        tool.inputSchema,
+        tool.annotations,
+        options.exposedTo,
+        options.source,
+    ]);
+    useEffect(() => {
+        const latest = toolRef.current;
+        const registration = registry.registerTool({
+            ...latest,
+            execute: (args, executionContext) => toolRef.current.execute(args, executionContext),
+        }, {
+            ...options,
+            source: options.source ?? 'hook',
+        });
+        return () => registration.abort();
+    }, [definitionKey, registry, toolRef, options.exposedTo, options.source, ...deps]);
+}

package/dist/useWebMcpTools.d.ts

@@ -0,0 +1,4 @@
+import { type DependencyList } from 'react';
+import type { RegisterToolOptions, WebMcpToolDescriptor } from '@tooluminati/core';
+export declare function useWebMcpTools(tools: WebMcpToolDescriptor[], deps?: DependencyList, options?: RegisterToolOptions): void;
+//# sourceMappingURL=useWebMcpTools.d.ts.map

package/dist/useWebMcpTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWebMcpTools.d.ts","sourceRoot":"","sources":["../src/useWebMcpTools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAG3B,wBAAgB,cAAc,CAC5B,KAAK,EAAE,oBAAoB,EAAE,EAC7B,IAAI,GAAE,cAAmB,EACzB,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAmBN"}

package/dist/useWebMcpTools.js

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+import { useWebMcpContextValue } from './useWebMcpRegistry';
+export function useWebMcpTools(tools, deps = [], options = {}) {
+    const { registry } = useWebMcpContextValue();
+    const exposedTo = options.exposedTo;
+    const source = options.source ?? 'scope';
+    useEffect(() => {
+        const registrations = tools.map((tool) => registry.registerTool(tool, {
+            ...options,
+            source,
+        }));
+        return () => {
+            for (const registration of registrations) {
+                registration.abort();
+            }
+        };
+    }, [registry, tools, exposedTo, source, ...deps]);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@tooluminati/react",
+  "version": "0.1.0",
+  "description": "React provider, hooks, and scopes for Tooluminati.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@tooluminati/core": "0.1.0",
+    "@tooluminati/policies": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jitterbox/Tooluminati.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/jitterbox/Tooluminati/issues"
+  },
+  "homepage": "https://github.com/jitterbox/Tooluminati#readme",
+  "keywords": [
+    "tooluminati",
+    "webmcp",
+    "react",
+    "hooks",
+    "agents"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs && tsc -p tsconfig.json --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit"
+  }
+}