@frontmcp/ui 0.5.0

package/src/react/hooks/tools.js

@@ -0,0 +1,465 @@
+"use strict";
+/**
+ * @file tools.tsx
+ * @description React hooks for MCP tool interactions.
+ *
+ * Provides hooks for calling tools, accessing tool input/output,
+ * and managing tool execution state.
+ *
+ * @example
+ * ```tsx
+ * import { useCallTool, useToolInput, useToolOutput } from '@frontmcp/ui/react';
+ *
+ * function WeatherWidget() {
+ *   const input = useToolInput<{ location: string }>();
+ *   const output = useToolOutput<WeatherData>();
+ *   const [callWeather, { data, loading, error }] = useCallTool<WeatherData>('get_weather');
+ *
+ *   return (
+ *     <div>
+ *       <p>Location: {input?.location}</p>
+ *       <button onClick={() => callWeather({ location: 'NYC' })}>
+ *         Get Weather
+ *       </button>
+ *       {loading && <p>Loading...</p>}
+ *       {data && <p>Temperature: {data.temperature}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @module @frontmcp/ui/react/hooks
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useToolInput = useToolInput;
+exports.useToolOutput = useToolOutput;
+exports.useStructuredContent = useStructuredContent;
+exports.useCallTool = useCallTool;
+exports.useToolCalls = useToolCalls;
+exports.useSendMessage = useSendMessage;
+exports.useOpenLink = useOpenLink;
+const react_1 = require("react");
+const context_1 = require("./context");
+// ============================================
+// Tool Input/Output Hooks
+// ============================================
+/**
+ * Hook to get the current tool input arguments.
+ * Returns the arguments passed to the tool when it was invoked.
+ *
+ * @typeParam T - Expected shape of the tool input
+ *
+ * @example
+ * ```tsx
+ * interface WeatherInput {
+ *   location: string;
+ *   units?: 'celsius' | 'fahrenheit';
+ * }
+ *
+ * function WeatherWidget() {
+ *   const input = useToolInput<WeatherInput>();
+ *
+ *   return (
+ *     <div>
+ *       <h1>Weather for {input?.location}</h1>
+ *       <p>Units: {input?.units ?? 'celsius'}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useToolInput() {
+    const { bridge, ready } = (0, context_1.useMcpBridgeContext)();
+    if (!ready || !bridge) {
+        return null;
+    }
+    try {
+        return bridge.getToolInput();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hook to get the current tool output/result.
+ * Returns the result data from the tool execution.
+ *
+ * @typeParam T - Expected shape of the tool output
+ *
+ * @example
+ * ```tsx
+ * interface WeatherOutput {
+ *   temperature: number;
+ *   condition: string;
+ *   humidity: number;
+ * }
+ *
+ * function WeatherDisplay() {
+ *   const output = useToolOutput<WeatherOutput>();
+ *
+ *   if (!output) return <div>No data</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Temperature: {output.temperature}°</p>
+ *       <p>Condition: {output.condition}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useToolOutput() {
+    const { bridge, ready } = (0, context_1.useMcpBridgeContext)();
+    const [output, setOutput] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!ready || !bridge)
+            return;
+        // Get initial output
+        try {
+            const initialOutput = bridge.getToolOutput();
+            if (initialOutput !== undefined) {
+                setOutput(initialOutput);
+            }
+        }
+        catch {
+            // Ignore
+        }
+        // Subscribe to tool result updates
+        const unsubscribe = bridge.onToolResult((result) => {
+            setOutput(result);
+        });
+        return unsubscribe;
+    }, [bridge, ready]);
+    return output;
+}
+/**
+ * Hook to get the structured content from the tool output.
+ * This is the parsed/structured version of the tool result.
+ *
+ * @typeParam T - Expected shape of the structured content
+ *
+ * @example
+ * ```tsx
+ * interface WeatherData {
+ *   forecast: Array<{ day: string; temp: number }>;
+ * }
+ *
+ * function ForecastDisplay() {
+ *   const content = useStructuredContent<WeatherData>();
+ *
+ *   return (
+ *     <ul>
+ *       {content?.forecast.map(day => (
+ *         <li key={day.day}>{day.day}: {day.temp}°</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+function useStructuredContent() {
+    const { bridge, ready } = (0, context_1.useMcpBridgeContext)();
+    if (!ready || !bridge) {
+        return null;
+    }
+    try {
+        const adapter = bridge.getAdapter?.();
+        if (adapter) {
+            return adapter.getStructuredContent();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================
+// Tool Execution Hooks
+// ============================================
+/**
+ * Hook to call an MCP tool with loading and error state management.
+ *
+ * Returns a tuple with:
+ * 1. The call function
+ * 2. State object (data, loading, error, called)
+ * 3. Reset function
+ *
+ * @typeParam TInput - Shape of the tool input arguments
+ * @typeParam TOutput - Expected shape of the tool output
+ *
+ * @example Basic usage
+ * ```tsx
+ * function WeatherButton() {
+ *   const [getWeather, { data, loading, error }] = useCallTool<
+ *     { location: string },
+ *     { temperature: number; condition: string }
+ *   >('get_weather');
+ *
+ *   return (
+ *     <div>
+ *       <button
+ *         onClick={() => getWeather({ location: 'San Francisco' })}
+ *         disabled={loading}
+ *       >
+ *         {loading ? 'Loading...' : 'Get Weather'}
+ *       </button>
+ *       {error && <p className="error">{error.message}</p>}
+ *       {data && <p>{data.temperature}° - {data.condition}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With callbacks
+ * ```tsx
+ * function WeatherWidget() {
+ *   const [getWeather, state, reset] = useCallTool('get_weather', {
+ *     onSuccess: (data) => console.log('Got weather:', data),
+ *     onError: (err) => console.error('Failed:', err),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => getWeather({ location: 'NYC' })}>
+ *         Get Weather
+ *       </button>
+ *       <button onClick={reset}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useCallTool(toolName, options = {}) {
+    const { bridge, ready } = (0, context_1.useMcpBridgeContext)();
+    const { onSuccess, onError, resetOnToolChange = true } = options;
+    console.log('useCallTool', toolName, bridge);
+    const [state, setState] = (0, react_1.useState)({
+        data: null,
+        loading: false,
+        error: null,
+        called: false,
+    });
+    // Reset state when tool name changes
+    (0, react_1.useEffect)(() => {
+        if (resetOnToolChange) {
+            setState({
+                data: null,
+                loading: false,
+                error: null,
+                called: false,
+            });
+        }
+    }, [toolName, resetOnToolChange]);
+    const reset = (0, react_1.useCallback)(() => {
+        setState({
+            data: null,
+            loading: false,
+            error: null,
+            called: false,
+        });
+    }, []);
+    const callTool = (0, react_1.useCallback)(async (args) => {
+        if (!ready || !bridge) {
+            const error = new Error('Bridge not initialized');
+            setState((prev) => ({ ...prev, error, called: true }));
+            onError?.(error);
+            return null;
+        }
+        setState((prev) => ({
+            ...prev,
+            loading: true,
+            error: null,
+            called: true,
+        }));
+        try {
+            const result = await bridge.callTool(toolName, args);
+            const data = result;
+            setState({
+                data,
+                loading: false,
+                error: null,
+                called: true,
+            });
+            onSuccess?.(data);
+            return data;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setState({
+                data: null,
+                loading: false,
+                error,
+                called: true,
+            });
+            onError?.(error);
+            return null;
+        }
+    }, [bridge, ready, toolName, onSuccess, onError]);
+    return [callTool, state, reset];
+}
+/**
+ * Hook to manage multiple tool calls.
+ * Useful when you need to track state for multiple tools.
+ *
+ * @example
+ * ```tsx
+ * function MultiToolWidget() {
+ *   const tools = useToolCalls({
+ *     weather: 'get_weather',
+ *     news: 'get_news',
+ *     stocks: 'get_stocks',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => tools.weather.call({ location: 'NYC' })}>
+ *         Get Weather
+ *       </button>
+ *       <button onClick={() => tools.news.call({ topic: 'tech' })}>
+ *         Get News
+ *       </button>
+ *       {tools.weather.loading && <p>Loading weather...</p>}
+ *       {tools.news.data && <p>News: {tools.news.data.headline}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useToolCalls(toolMap) {
+    const bridge = (0, context_1.useMcpBridge)();
+    const [states, setStates] = (0, react_1.useState)(() => {
+        const initial = {};
+        for (const key of Object.keys(toolMap)) {
+            initial[key] = { data: null, loading: false, error: null, called: false };
+        }
+        return initial;
+    });
+    const createCallFn = (0, react_1.useCallback)((key, toolName) => async (args) => {
+        if (!bridge) {
+            setStates((prev) => ({
+                ...prev,
+                [key]: {
+                    ...prev[key],
+                    error: new Error('Bridge not initialized'),
+                    called: true,
+                },
+            }));
+            return null;
+        }
+        setStates((prev) => ({
+            ...prev,
+            [key]: { ...prev[key], loading: true, error: null, called: true },
+        }));
+        try {
+            const result = await bridge.callTool(toolName, args);
+            setStates((prev) => ({
+                ...prev,
+                [key]: { data: result, loading: false, error: null, called: true },
+            }));
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setStates((prev) => ({
+                ...prev,
+                [key]: { data: null, loading: false, error, called: true },
+            }));
+            return null;
+        }
+    }, [bridge]);
+    const createResetFn = (0, react_1.useCallback)((key) => () => {
+        setStates((prev) => ({
+            ...prev,
+            [key]: { data: null, loading: false, error: null, called: false },
+        }));
+    }, []);
+    // Build result object
+    const result = {};
+    for (const [key, toolName] of Object.entries(toolMap)) {
+        const state = states[key] || {
+            data: null,
+            loading: false,
+            error: null,
+            called: false,
+        };
+        result[key] = {
+            call: createCallFn(key, toolName),
+            data: state.data,
+            loading: state.loading,
+            error: state.error,
+            reset: createResetFn(key),
+        };
+    }
+    return result;
+}
+/**
+ * Hook to send a message to the conversation.
+ * Returns a function and state for sending messages.
+ *
+ * @example
+ * ```tsx
+ * function ChatWidget() {
+ *   const [sendMessage, { loading, error, sent }] = useSendMessage();
+ *
+ *   return (
+ *     <button
+ *       onClick={() => sendMessage('Here is the weather update!')}
+ *       disabled={loading}
+ *     >
+ *       {loading ? 'Sending...' : 'Send Update'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+function useSendMessage() {
+    const bridge = (0, context_1.useMcpBridge)();
+    const [state, setState] = (0, react_1.useState)({
+        loading: false,
+        error: null,
+        sent: false,
+    });
+    const sendMessage = (0, react_1.useCallback)(async (content) => {
+        if (!bridge) {
+            setState({ loading: false, error: new Error('Bridge not initialized'), sent: false });
+            return;
+        }
+        setState({ loading: true, error: null, sent: false });
+        try {
+            await bridge.sendMessage(content);
+            setState({ loading: false, error: null, sent: true });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setState({ loading: false, error, sent: false });
+        }
+    }, [bridge]);
+    return [sendMessage, state];
+}
+/**
+ * Hook to open external links via the bridge.
+ *
+ * @example
+ * ```tsx
+ * function LinkButton() {
+ *   const openLink = useOpenLink();
+ *
+ *   return (
+ *     <button onClick={() => openLink('https://example.com')}>
+ *       Open Website
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+function useOpenLink() {
+    const bridge = (0, context_1.useMcpBridge)();
+    return (0, react_1.useCallback)(async (url) => {
+        if (!bridge) {
+            console.warn('Bridge not initialized, cannot open link');
+            return;
+        }
+        await bridge.openLink(url);
+    }, [bridge]);
+}
+//# sourceMappingURL=tools.js.map

package/src/react/hooks/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../src/react/hooks/tools.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * @file tools.tsx\n * @description React hooks for MCP tool interactions.\n *\n * Provides hooks for calling tools, accessing tool input/output,\n * and managing tool execution state.\n *\n * @example\n * ```tsx\n * import { useCallTool, useToolInput, useToolOutput } from '@frontmcp/ui/react';\n *\n * function WeatherWidget() {\n *   const input = useToolInput<{ location: string }>();\n *   const output = useToolOutput<WeatherData>();\n *   const [callWeather, { data, loading, error }] = useCallTool<WeatherData>('get_weather');\n *\n *   return (\n *     <div>\n *       <p>Location: {input?.location}</p>\n *       <button onClick={() => callWeather({ location: 'NYC' })}>\n *         Get Weather\n *       </button>\n *       {loading && <p>Loading...</p>}\n *       {data && <p>Temperature: {data.temperature}</p>}\n *     </div>\n *   );\n * }\n * ```\n *\n * @module @frontmcp/ui/react/hooks\n */\n\nimport { useState, useCallback, useEffect } from 'react';\nimport { useMcpBridgeContext, useMcpBridge } from './context';\n\n// ============================================\n// Types\n// ============================================\n\n/**\n * State for tool execution.\n */\nexport interface ToolState<T = unknown> {\n  /** Tool result data */\n  data: T | null;\n  /** Whether the tool is currently executing */\n  loading: boolean;\n  /** Execution error, if any */\n  error: Error | null;\n  /** Whether the tool has been called at least once */\n  called: boolean;\n}\n\n/**\n * Options for useCallTool hook.\n */\nexport interface UseCallToolOptions {\n  /** Automatically reset state when tool name changes */\n  resetOnToolChange?: boolean;\n  /** Callback when tool execution succeeds */\n  onSuccess?: (data: unknown) => void;\n  /** Callback when tool execution fails */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Return type for useCallTool hook.\n */\nexport type UseCallToolReturn<TInput extends object, TOutput> = [\n  /** Function to call the tool */\n  (args: TInput) => Promise<TOutput | null>,\n  /** Current tool state */\n  ToolState<TOutput>,\n  /** Reset state to initial values */\n  () => void,\n];\n\n// ============================================\n// Tool Input/Output Hooks\n// ============================================\n\n/**\n * Hook to get the current tool input arguments.\n * Returns the arguments passed to the tool when it was invoked.\n *\n * @typeParam T - Expected shape of the tool input\n *\n * @example\n * ```tsx\n * interface WeatherInput {\n *   location: string;\n *   units?: 'celsius' | 'fahrenheit';\n * }\n *\n * function WeatherWidget() {\n *   const input = useToolInput<WeatherInput>();\n *\n *   return (\n *     <div>\n *       <h1>Weather for {input?.location}</h1>\n *       <p>Units: {input?.units ?? 'celsius'}</p>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useToolInput<T extends object = Record<string, unknown>>(): T | null {\n  const { bridge, ready } = useMcpBridgeContext();\n\n  if (!ready || !bridge) {\n    return null;\n  }\n\n  try {\n    return bridge.getToolInput() as T;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Hook to get the current tool output/result.\n * Returns the result data from the tool execution.\n *\n * @typeParam T - Expected shape of the tool output\n *\n * @example\n * ```tsx\n * interface WeatherOutput {\n *   temperature: number;\n *   condition: string;\n *   humidity: number;\n * }\n *\n * function WeatherDisplay() {\n *   const output = useToolOutput<WeatherOutput>();\n *\n *   if (!output) return <div>No data</div>;\n *\n *   return (\n *     <div>\n *       <p>Temperature: {output.temperature}°</p>\n *       <p>Condition: {output.condition}</p>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useToolOutput<T = unknown>(): T | null {\n  const { bridge, ready } = useMcpBridgeContext();\n  const [output, setOutput] = useState<T | null>(null);\n\n  useEffect(() => {\n    if (!ready || !bridge) return;\n\n    // Get initial output\n    try {\n      const initialOutput = bridge.getToolOutput();\n      if (initialOutput !== undefined) {\n        setOutput(initialOutput as T);\n      }\n    } catch {\n      // Ignore\n    }\n\n    // Subscribe to tool result updates\n    const unsubscribe = bridge.onToolResult((result) => {\n      setOutput(result as T);\n    });\n\n    return unsubscribe;\n  }, [bridge, ready]);\n\n  return output;\n}\n\n/**\n * Hook to get the structured content from the tool output.\n * This is the parsed/structured version of the tool result.\n *\n * @typeParam T - Expected shape of the structured content\n *\n * @example\n * ```tsx\n * interface WeatherData {\n *   forecast: Array<{ day: string; temp: number }>;\n * }\n *\n * function ForecastDisplay() {\n *   const content = useStructuredContent<WeatherData>();\n *\n *   return (\n *     <ul>\n *       {content?.forecast.map(day => (\n *         <li key={day.day}>{day.day}: {day.temp}°</li>\n *       ))}\n *     </ul>\n *   );\n * }\n * ```\n */\nexport function useStructuredContent<T = unknown>(): T | null {\n  const { bridge, ready } = useMcpBridgeContext();\n\n  if (!ready || !bridge) {\n    return null;\n  }\n\n  try {\n    const adapter = bridge.getAdapter?.();\n    if (adapter) {\n      return adapter.getStructuredContent() as T;\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\n// ============================================\n// Tool Execution Hooks\n// ============================================\n\n/**\n * Hook to call an MCP tool with loading and error state management.\n *\n * Returns a tuple with:\n * 1. The call function\n * 2. State object (data, loading, error, called)\n * 3. Reset function\n *\n * @typeParam TInput - Shape of the tool input arguments\n * @typeParam TOutput - Expected shape of the tool output\n *\n * @example Basic usage\n * ```tsx\n * function WeatherButton() {\n *   const [getWeather, { data, loading, error }] = useCallTool<\n *     { location: string },\n *     { temperature: number; condition: string }\n *   >('get_weather');\n *\n *   return (\n *     <div>\n *       <button\n *         onClick={() => getWeather({ location: 'San Francisco' })}\n *         disabled={loading}\n *       >\n *         {loading ? 'Loading...' : 'Get Weather'}\n *       </button>\n *       {error && <p className=\"error\">{error.message}</p>}\n *       {data && <p>{data.temperature}° - {data.condition}</p>}\n *     </div>\n *   );\n * }\n * ```\n *\n * @example With callbacks\n * ```tsx\n * function WeatherWidget() {\n *   const [getWeather, state, reset] = useCallTool('get_weather', {\n *     onSuccess: (data) => console.log('Got weather:', data),\n *     onError: (err) => console.error('Failed:', err),\n *   });\n *\n *   return (\n *     <div>\n *       <button onClick={() => getWeather({ location: 'NYC' })}>\n *         Get Weather\n *       </button>\n *       <button onClick={reset}>Reset</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useCallTool<TInput extends object = Record<string, unknown>, TOutput = unknown>(\n  toolName: string,\n  options: UseCallToolOptions = {},\n): UseCallToolReturn<TInput, TOutput> {\n  const { bridge, ready } = useMcpBridgeContext();\n  const { onSuccess, onError, resetOnToolChange = true } = options;\n\n  console.log('useCallTool', toolName, bridge);\n  const [state, setState] = useState<ToolState<TOutput>>({\n    data: null,\n    loading: false,\n    error: null,\n    called: false,\n  });\n\n  // Reset state when tool name changes\n  useEffect(() => {\n    if (resetOnToolChange) {\n      setState({\n        data: null,\n        loading: false,\n        error: null,\n        called: false,\n      });\n    }\n  }, [toolName, resetOnToolChange]);\n\n  const reset = useCallback(() => {\n    setState({\n      data: null,\n      loading: false,\n      error: null,\n      called: false,\n    });\n  }, []);\n\n  const callTool = useCallback(\n    async (args: TInput): Promise<TOutput | null> => {\n      if (!ready || !bridge) {\n        const error = new Error('Bridge not initialized');\n        setState((prev) => ({ ...prev, error, called: true }));\n        onError?.(error);\n        return null;\n      }\n\n      setState((prev) => ({\n        ...prev,\n        loading: true,\n        error: null,\n        called: true,\n      }));\n\n      try {\n        const result = await bridge.callTool(toolName, args as Record<string, unknown>);\n        const data = result as TOutput;\n\n        setState({\n          data,\n          loading: false,\n          error: null,\n          called: true,\n        });\n\n        onSuccess?.(data);\n        return data;\n      } catch (err) {\n        const error = err instanceof Error ? err : new Error(String(err));\n\n        setState({\n          data: null,\n          loading: false,\n          error,\n          called: true,\n        });\n\n        onError?.(error);\n        return null;\n      }\n    },\n    [bridge, ready, toolName, onSuccess, onError],\n  );\n\n  return [callTool, state, reset];\n}\n\n/**\n * Hook to manage multiple tool calls.\n * Useful when you need to track state for multiple tools.\n *\n * @example\n * ```tsx\n * function MultiToolWidget() {\n *   const tools = useToolCalls({\n *     weather: 'get_weather',\n *     news: 'get_news',\n *     stocks: 'get_stocks',\n *   });\n *\n *   return (\n *     <div>\n *       <button onClick={() => tools.weather.call({ location: 'NYC' })}>\n *         Get Weather\n *       </button>\n *       <button onClick={() => tools.news.call({ topic: 'tech' })}>\n *         Get News\n *       </button>\n *       {tools.weather.loading && <p>Loading weather...</p>}\n *       {tools.news.data && <p>News: {tools.news.data.headline}</p>}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useToolCalls<T extends Record<string, string>>(\n  toolMap: T,\n): {\n  [K in keyof T]: {\n    call: (args: Record<string, unknown>) => Promise<unknown>;\n    data: unknown;\n    loading: boolean;\n    error: Error | null;\n    reset: () => void;\n  };\n} {\n  const bridge = useMcpBridge();\n  const [states, setStates] = useState<Record<string, ToolState<unknown>>>(() => {\n    const initial: Record<string, ToolState<unknown>> = {};\n    for (const key of Object.keys(toolMap)) {\n      initial[key] = { data: null, loading: false, error: null, called: false };\n    }\n    return initial;\n  });\n\n  const createCallFn = useCallback(\n    (key: string, toolName: string) =>\n      async (args: Record<string, unknown>): Promise<unknown> => {\n        if (!bridge) {\n          setStates((prev) => ({\n            ...prev,\n            [key]: {\n              ...prev[key],\n              error: new Error('Bridge not initialized'),\n              called: true,\n            },\n          }));\n          return null;\n        }\n\n        setStates((prev) => ({\n          ...prev,\n          [key]: { ...prev[key], loading: true, error: null, called: true },\n        }));\n\n        try {\n          const result = await bridge.callTool(toolName, args);\n          setStates((prev) => ({\n            ...prev,\n            [key]: { data: result, loading: false, error: null, called: true },\n          }));\n          return result;\n        } catch (err) {\n          const error = err instanceof Error ? err : new Error(String(err));\n          setStates((prev) => ({\n            ...prev,\n            [key]: { data: null, loading: false, error, called: true },\n          }));\n          return null;\n        }\n      },\n    [bridge],\n  );\n\n  const createResetFn = useCallback(\n    (key: string) => () => {\n      setStates((prev) => ({\n        ...prev,\n        [key]: { data: null, loading: false, error: null, called: false },\n      }));\n    },\n    [],\n  );\n\n  // Build result object\n  const result = {} as {\n    [K in keyof T]: {\n      call: (args: Record<string, unknown>) => Promise<unknown>;\n      data: unknown;\n      loading: boolean;\n      error: Error | null;\n      reset: () => void;\n    };\n  };\n\n  for (const [key, toolName] of Object.entries(toolMap)) {\n    const state = states[key] || {\n      data: null,\n      loading: false,\n      error: null,\n      called: false,\n    };\n    result[key as keyof T] = {\n      call: createCallFn(key, toolName),\n      data: state.data,\n      loading: state.loading,\n      error: state.error,\n      reset: createResetFn(key),\n    };\n  }\n\n  return result;\n}\n\n/**\n * Hook to send a message to the conversation.\n * Returns a function and state for sending messages.\n *\n * @example\n * ```tsx\n * function ChatWidget() {\n *   const [sendMessage, { loading, error, sent }] = useSendMessage();\n *\n *   return (\n *     <button\n *       onClick={() => sendMessage('Here is the weather update!')}\n *       disabled={loading}\n *     >\n *       {loading ? 'Sending...' : 'Send Update'}\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useSendMessage(): [\n  (content: string) => Promise<void>,\n  { loading: boolean; error: Error | null; sent: boolean },\n] {\n  const bridge = useMcpBridge();\n  const [state, setState] = useState({\n    loading: false,\n    error: null as Error | null,\n    sent: false,\n  });\n\n  const sendMessage = useCallback(\n    async (content: string): Promise<void> => {\n      if (!bridge) {\n        setState({ loading: false, error: new Error('Bridge not initialized'), sent: false });\n        return;\n      }\n\n      setState({ loading: true, error: null, sent: false });\n\n      try {\n        await bridge.sendMessage(content);\n        setState({ loading: false, error: null, sent: true });\n      } catch (err) {\n        const error = err instanceof Error ? err : new Error(String(err));\n        setState({ loading: false, error, sent: false });\n      }\n    },\n    [bridge],\n  );\n\n  return [sendMessage, state];\n}\n\n/**\n * Hook to open external links via the bridge.\n *\n * @example\n * ```tsx\n * function LinkButton() {\n *   const openLink = useOpenLink();\n *\n *   return (\n *     <button onClick={() => openLink('https://example.com')}>\n *       Open Website\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useOpenLink(): (url: string) => Promise<void> {\n  const bridge = useMcpBridge();\n\n  return useCallback(\n    async (url: string): Promise<void> => {\n      if (!bridge) {\n        console.warn('Bridge not initialized, cannot open link');\n        return;\n      }\n\n      await bridge.openLink(url);\n    },\n    [bridge],\n  );\n}\n"]}

package/src/react/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file index.ts
+ * @description React components and hooks for FrontMCP UI.
+ *
+ * These are pure React components that can be used:
+ * 1. As regular React components in your app
+ * 2. To generate static HTML via render functions
+ * 3. With hooks to access the MCP bridge
+ *
+ * @example React usage
+ * ```tsx
+ * import { Card, Badge, Button, Alert } from '@frontmcp/ui/react';
+ *
+ * function App() {
+ *   return (
+ *     <Card title="Welcome" variant="elevated">
+ *       <Badge variant="success">New</Badge>
+ *       <p>Card content here</p>
+ *       <Button variant="primary">Click Me</Button>
+ *     </Card>
+ *   );
+ * }
+ * ```
+ *
+ * @example Static HTML generation
+ * ```typescript
+ * import { renderCard, renderBadge } from '@frontmcp/ui/react';
+ *
+ * const cardHtml = await renderCard({
+ *   title: 'Welcome',
+ *   variant: 'elevated',
+ *   children: '<p>Content</p>',
+ * });
+ * ```
+ *
+ * @example Using hooks with the MCP bridge
+ * ```tsx
+ * import {
+ *   McpBridgeProvider,
+ *   useMcpBridge,
+ *   useToolInput,
+ *   useCallTool,
+ *   useTheme,
+ * } from '@frontmcp/ui/react';
+ *
+ * function App() {
+ *   return (
+ *     <McpBridgeProvider>
+ *       <WeatherWidget />
+ *     </McpBridgeProvider>
+ *   );
+ * }
+ *
+ * function WeatherWidget() {
+ *   const input = useToolInput<{ location: string }>();
+ *   const theme = useTheme();
+ *   const [getWeather, { data, loading }] = useCallTool('get_weather');
+ *
+ *   return (
+ *     <Card title={`Weather for ${input?.location}`} variant={theme === 'dark' ? 'elevated' : 'default'}>
+ *       {loading ? 'Loading...' : data?.temperature}
+ *     </Card>
+ *   );
+ * }
+ * ```
+ *
+ * @module @frontmcp/ui/react
+ */
+export { Card, renderCard, renderCardSync } from './Card';
+export { Badge, renderBadge, renderBadgeSync } from './Badge';
+export { Button, renderButton, renderButtonSync } from './Button';
+export { Alert, renderAlert, renderAlertSync } from './Alert';
+export { McpBridgeProvider, useMcpBridgeContext, useMcpBridge, useTheme, useDisplayMode, useHostContext, useCapability, useToolInput, useToolOutput, useStructuredContent, useCallTool, useToolCalls, useSendMessage, useOpenLink, type McpBridgeContextValue, type McpBridgeProviderProps, type ToolState, type UseCallToolOptions, type UseCallToolReturn, } from './hooks';
+export type { CardProps, CardRenderProps, CardVariant, CardSize } from './Card';
+export type { BadgeProps, BadgeRenderProps, BadgeVariant, BadgeSize } from './Badge';
+export type { ButtonProps, ButtonRenderProps, ButtonVariant, ButtonSize } from './Button';
+export type { AlertProps, AlertRenderProps, AlertVariant } from './Alert';
+export type { FmcpCard, FmcpBadge, FmcpButton, FmcpAlert } from './types';
+export type { CardOptions, BadgeOptions, ButtonOptions, AlertOptions } from './types';
+export { renderChildrenToString, isBrowser, isServer } from './utils';