open-mcp-app 0.1.2 → 0.1.4

package/dist/react/index.d.ts

@@ -1,6 +1,7 @@
-import { ToolResult, WidgetState, Environment, DisplayMode, AdapterKind, HostContext, WebSocketStatus } from '../core/index.js';
-export { BaseHostClient, BaseHostClientEvents, ChatGptAdapter, CreatureAdapter, HostAdapter, HostClientConfig, HostClientState, HostIdentity, KNOWN_HOSTS, LogLevel, McpAppsAdapter, StandaloneAdapter, StructuredWidgetState, UnifiedHostClient, UnifiedHostClientEvents, UpgradingMcpAppsClient, WebSocketClient, WebSocketClientConfig, createHost, createHostAsync, createWebSocket, detectEnvironment, getHostIdentity, isHost, parseHostUserAgent } from '../core/index.js';
+import { ToolResult, WidgetState, Environment, DisplayMode, AdapterKind, HostContext, ExperimentalHostApi, WebSocketStatus, UnifiedHostClient } from '../core/index.js';
+export { BaseHostClient, BaseHostClientEvents, ChatGptAdapter, CreatureAdapter, HostAdapter, HostClientConfig, HostClientState, HostIdentity, KNOWN_HOSTS, LogLevel, McpAppsAdapter, StandaloneAdapter, StructuredWidgetState, UnifiedHostClientEvents, UpgradingMcpAppsClient, WebSocketClient, WebSocketClientConfig, createHost, createHostAsync, createWebSocket, detectEnvironment, getHostIdentity, isHost, parseHostUserAgent } from '../core/index.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 export { applyDocumentTheme, applyHostFonts, applyHostStyleVariables, getDocumentTheme } from '@modelcontextprotocol/ext-apps';
 
 interface UseHostConfig {
@@ -13,6 +14,45 @@ interface UseHostConfig {
     /** Called when widget state changes (restored from host or updated) */
     onWidgetStateChange?: (widgetState: WidgetState | null) => void;
 }
+/**
+ * Status of a tool call.
+ */
+type ToolCallStatus = "idle" | "loading" | "success" | "error";
+/**
+ * State returned from a tool call.
+ * Contains the status, data, and metadata from the tool result.
+ */
+interface ToolCallState<T = Record<string, unknown>> {
+    /** Current status of the tool call */
+    status: ToolCallStatus;
+    /** Structured data from tool result (from structuredContent) */
+    data: T | null;
+    /** Full tool result object */
+    result: ToolResult<T> | null;
+    /** Error if the tool call failed */
+    error: unknown | null;
+    /** Whether the result is an error (from isError flag or thrown exception) */
+    isError: boolean;
+    /** Text content for AI context (from content[0].text) */
+    text: string | null;
+    /** Title for PIP tab (from structuredContent.title) */
+    title: string | null;
+    /** Instance ID for this widget (from structuredContent.instanceId) */
+    instanceId: string | null;
+}
+/**
+ * Function to call a tool with optional arguments.
+ * Returns a promise that resolves to the tool result.
+ */
+type ToolCallFunction<T = Record<string, unknown>> = (args?: Record<string, unknown>) => Promise<ToolResult<T>>;
+/**
+ * Tuple returned from callTool().
+ * First element is the function to call the tool, second is the current state.
+ */
+type ToolCallTuple<T = Record<string, unknown>> = [
+    ToolCallFunction<T>,
+    ToolCallState<T>
+];
 /**
  * Logger interface with convenience methods for each log level.
  *
@@ -49,22 +89,36 @@ interface Logger {
 }
 interface UseHostReturn {
     isReady: boolean;
-    callTool: <T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>) => Promise<ToolResult<T>>;
-    sendNotification: (method: string, params: unknown) => void;
-    environment: Environment;
-    widgetState: WidgetState | null;
-    setWidgetState: (state: WidgetState | null) => void;
     /**
-     * Set the pip/widget title displayed in the host UI.
+     * Get a tool caller for the given tool name.
+     * Returns a tuple of [callFn, state] where:
+     * - callFn: Function to call the tool with optional args (defaults to {})
+     * - state: Current state of the tool call (status, data, error, etc.)
      *
-     * Useful for updating the title based on user actions (e.g., switching tabs)
-     * without making a tool call.
+     * @example
+     * ```tsx
+     * const { callTool, isReady } = useHost({ name: "my-app", version: "1.0.0" });
+     * const [listTodos, listTodosState] = callTool<TodoData>("todos_list");
+     * const [addTodo, addTodoState] = callTool<TodoData>("todos_add");
      *
-     * Note: Creature-specific extension, no-op on ChatGPT Apps.
+     * useEffect(() => {
+     *   if (isReady) {
+     *     listTodos(); // Call with no args
+     *   }
+     * }, [isReady, listTodos]);
      *
-     * @param title - The new title to display
+     * // Use the state
+     * if (listTodosState.status === "loading") return <Spinner />;
+     * if (listTodosState.data) return <TodoList todos={listTodosState.data.todos} />;
+     *
+     * // Call with args
+     * <button onClick={() => addTodo({ text: "New todo" })}>Add</button>
+     * ```
      */
-    setTitle: (title: string) => void;
+    callTool: <T = Record<string, unknown>>(toolName: string) => ToolCallTuple<T>;
+    environment: Environment;
+    /** Current widget state (read-only). Use experimental_widgetState() for read/write access. */
+    widgetState: WidgetState | null;
     requestDisplayMode: (params: {
         mode: DisplayMode;
     }) => Promise<{
@@ -109,6 +163,52 @@ interface UseHostReturn {
      * ```
      */
     log: Logger;
+    /**
+     * Experimental APIs that are not part of the MCP Apps spec.
+     *
+     * These APIs provide access to Creature-specific features and other
+     * non-standard extensions. They may change or be removed in future versions.
+     *
+     * @example
+     * ```tsx
+     * const { experimental, isCreature } = useHost({ name: "my-app", version: "1.0.0" });
+     *
+     * // Set widget state (non-spec extension)
+     * experimental.setWidgetState({ count: 42 });
+     *
+     * // Set title (Creature-only)
+     * if (isCreature) {
+     *   experimental.setTitle("My Widget");
+     * }
+     *
+     * // Get Creature-specific styles
+     * const styles = experimental.getCreatureStyles();
+     * ```
+     */
+    experimental: ExperimentalHostApi;
+    /**
+     * Get widget state as a useState-like tuple.
+     * Returns [state, setState] for reading and updating widget state.
+     *
+     * Widget state is persisted by the host across sessions and restored
+     * when the widget is re-opened.
+     *
+     * @example
+     * ```tsx
+     * const { experimental_widgetState } = useHost({ name: "my-app", version: "1.0.0" });
+     * const [widgetState, setWidgetState] = experimental_widgetState<MyState>();
+     *
+     * return (
+     *   <button onClick={() => setWidgetState({ count: (widgetState?.count ?? 0) + 1 })}>
+     *     Count: {widgetState?.count ?? 0}
+     *   </button>
+     * );
+     * ```
+     */
+    experimental_widgetState: <T extends WidgetState = WidgetState>() => [
+        T | null,
+        (state: T | null) => void
+    ];
 }
 interface UseToolResultReturn<T> {
     /** Structured data from tool result */
@@ -153,28 +253,52 @@ interface CreatureIconProps {
 /**
  * React hook for connecting to an MCP Apps host.
  *
- * Creates a host client instance and manages its lifecycle. Automatically
- * connects on mount and disconnects on unmount. Uses refs for callbacks
- * to prevent reconnection loops when consumers pass inline functions.
+ * Can be used in two ways:
+ *
+ * 1. **With HostProvider** (recommended): Call `useHost()` with no arguments
+ *    inside a component wrapped by `<HostProvider>`. The client is shared
+ *    via context, and connection is managed by the provider.
+ *
+ * 2. **Standalone**: Pass config to create and manage your own client.
+ *    The hook handles connection/disconnection automatically.
  *
- * @param config - Configuration including app info and event handlers
+ * @param config - Optional configuration. If omitted, uses HostProvider context.
  * @returns Current state and methods for interacting with the host
  *
- * @example
+ * @example With HostProvider (recommended)
  * ```tsx
- * const { isReady, callTool, log } = useHost({
- *   name: "my-app",
- *   version: "1.0.0",
- *   onToolResult: (result) => setData(result.structuredContent),
- * });
- *
- * // Logging
- * log("User action"); // default info level
- * log.debug("Verbose info");
- * log.error("Something failed", { error: err.message });
+ * // App.tsx
+ * function App() {
+ *   return (
+ *     <HostProvider name="my-app" version="1.0.0">
+ *       <MyWidget />
+ *     </HostProvider>
+ *   );
+ * }
+ *
+ * // MyWidget.tsx
+ * function MyWidget() {
+ *   const { callTool, isReady, log, experimental_widgetState } = useHost();
+ *   const [widgetState, setWidgetState] = experimental_widgetState();
+ *   const [listTodos, listTodosData] = callTool("todos_list");
+ *
+ *   useEffect(() => {
+ *     if (isReady) listTodos();
+ *   }, [isReady, listTodos]);
+ * }
+ * ```
+ *
+ * @example Standalone (creates own client)
+ * ```tsx
+ * function MyApp() {
+ *   const { isReady, callTool, log } = useHost({
+ *     name: "my-app",
+ *     version: "1.0.0",
+ *   });
+ * }
  * ```
  */
-declare function useHost(config: UseHostConfig): UseHostReturn;
+declare function useHost(config?: UseHostConfig): UseHostReturn;
 
 /**
  * Hook to access tool result data.
@@ -193,4 +317,157 @@ declare function useWebSocket<TSend = unknown, TReceive = unknown>(url: string |
  */
 declare function CreatureIcon({ isDarkMode, showEyes, enableBlink, width, height, className, }: CreatureIconProps): react_jsx_runtime.JSX.Element;
 
-export { AdapterKind, CreatureIcon, type CreatureIconProps, DisplayMode, Environment, HostContext, type Logger, ToolResult, type UseHostConfig, type UseHostReturn, type UseToolResultReturn, type UseWebSocketConfig, type UseWebSocketReturn, WebSocketStatus, WidgetState, useHost, useToolResult, useWebSocket };
+/**
+ * Get the host client from context.
+ *
+ * @throws Error if used outside of HostProvider
+ */
+declare function useHostClient(): UnifiedHostClient;
+/**
+ * Get the host client from context, or null if not in a provider.
+ * Useful for optional host features.
+ */
+declare function useHostClientOptional(): UnifiedHostClient | null;
+interface HostProviderProps {
+    /** App name for the host client */
+    name: string;
+    /** App version for the host client */
+    version: string;
+    /** Child components */
+    children: ReactNode;
+    /**
+     * Called when tool input is received.
+     * Note: For tool results, use onToolResult in individual components.
+     */
+    onToolInput?: (args: Record<string, unknown>) => void;
+    /** Called when theme changes (MCP Apps only) */
+    onThemeChange?: (theme: "light" | "dark") => void;
+    /** Called when host requests teardown (MCP Apps only) */
+    onTeardown?: () => Promise<void> | void;
+}
+/**
+ * Provides the host client to child components.
+ *
+ * Creates a single host client instance that is shared across all children.
+ * The client connects on mount and disconnects on unmount.
+ *
+ * @example
+ * ```tsx
+ * import { HostProvider } from 'open-mcp-app/react';
+ *
+ * function App() {
+ *   return (
+ *     <HostProvider name="my-app" version="1.0.0">
+ *       <MyWidget />
+ *     </HostProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function HostProvider({ name, version, children, onToolInput, onThemeChange, onTeardown, }: HostProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Experimental React Hooks
+ *
+ * These hooks provide React-idiomatic APIs for non-spec host features.
+ * They follow the Vercel AI SDK naming convention with `experimental_` prefix.
+ *
+ * Usage:
+ * ```tsx
+ * import {
+ *   experimental_useWidgetState as useWidgetState,
+ *   experimental_useTitle as useTitle,
+ * } from 'open-mcp-app/react';
+ * ```
+ */
+
+/**
+ * React hook for managing widget state with host synchronization.
+ *
+ * Returns a tuple similar to `useState`, but the state is:
+ * - Persisted by the host across sessions
+ * - Restored when the widget is re-opened
+ * - Optionally visible to the AI model (via `modelContent`)
+ *
+ * **Experimental:** This uses the `ui/notifications/widget-state-changed`
+ * notification which is not part of the MCP Apps specification.
+ *
+ * @returns Tuple of [state, setState] like useState
+ *
+ * @example
+ * ```tsx
+ * import { experimental_useWidgetState as useWidgetState } from 'open-mcp-app/react';
+ *
+ * function Counter() {
+ *   const [state, setState] = useWidgetState<{ count: number }>();
+ *
+ *   return (
+ *     <button onClick={() => setState({ count: (state?.count ?? 0) + 1 })}>
+ *       Count: {state?.count ?? 0}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function experimental_useWidgetState<T extends WidgetState = WidgetState>(): [
+    T | null,
+    (state: T | null) => void
+];
+/**
+ * React hook for setting the widget/PiP title.
+ *
+ * Returns a setter function to update the title displayed in the host UI.
+ * This is useful for dynamic titles that change based on widget state.
+ *
+ * **Experimental:** This uses the `ui/notifications/title-changed`
+ * notification which is a Creature-specific extension, not part of
+ * the MCP Apps specification. No-op on other hosts.
+ *
+ * @returns Function to set the title
+ *
+ * @example
+ * ```tsx
+ * import { experimental_useTitle as useTitle } from 'open-mcp-app/react';
+ *
+ * function DocumentEditor() {
+ *   const setTitle = useTitle();
+ *   const [docName, setDocName] = useState("Untitled");
+ *
+ *   useEffect(() => {
+ *     setTitle(`Editing: ${docName}`);
+ *   }, [docName, setTitle]);
+ *
+ *   return <input value={docName} onChange={(e) => setDocName(e.target.value)} />;
+ * }
+ * ```
+ */
+declare function experimental_useTitle(): (title: string) => void;
+/**
+ * React hook for accessing Creature-specific CSS style variables.
+ *
+ * Returns the custom CSS variables provided by the Creature host,
+ * or null if not running in Creature.
+ *
+ * **Experimental:** This is a Creature-specific extension, not part of
+ * the MCP Apps specification.
+ *
+ * @returns Creature styles object or null
+ *
+ * @example
+ * ```tsx
+ * import { experimental_useCreatureStyles as useCreatureStyles } from 'open-mcp-app/react';
+ *
+ * function ThemedComponent() {
+ *   const styles = useCreatureStyles();
+ *
+ *   return (
+ *     <div style={{ color: styles?.['--creature-accent-color'] }}>
+ *       Themed content
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function experimental_useCreatureStyles(): Record<string, string | undefined> | null;
+
+export { AdapterKind, CreatureIcon, type CreatureIconProps, DisplayMode, Environment, ExperimentalHostApi, HostContext, HostProvider, type HostProviderProps, type Logger, type ToolCallFunction, type ToolCallState, type ToolCallStatus, type ToolCallTuple, ToolResult, UnifiedHostClient, type UseHostConfig, type UseHostReturn, type UseToolResultReturn, type UseWebSocketConfig, type UseWebSocketReturn, WebSocketStatus, WidgetState, experimental_useCreatureStyles, experimental_useTitle, experimental_useWidgetState, useHost, useHostClient, useHostClientOptional, useToolResult, useWebSocket };