@modelcontextprotocol/ext-apps 0.4.0 → 0.4.2

package/dist/src/react/useApp.d.ts

@@ -2,49 +2,50 @@ import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 import { App, McpUiAppCapabilities } from "../app";
 export * from "../app";
 /**
- * Options for configuring the useApp hook.
+ * Options for configuring the {@link useApp `useApp`} hook.
  *
- * Note: This interface does NOT expose App options like `autoResize`.
- * The hook creates the App with default options (autoResize: true). If you need
- * custom App options, create the App manually instead of using this hook.
+ * Note: This interface does NOT expose {@link App `App`} options like `autoResize`.
+ * The hook creates the `App` with default options (`autoResize: true`). If you
+ * need custom `App` options, create the `App` manually instead of using this hook.
  *
- * @see {@link useApp} for the hook that uses these options
- * @see {@link useAutoResize} for manual auto-resize control with custom App options
+ * @see {@link useApp `useApp`} for the hook that uses these options
+ * @see {@link useAutoResize `useAutoResize`} for manual auto-resize control with custom `App` options
  */
 export interface UseAppOptions {
     /** App identification (name and version) */
     appInfo: Implementation;
-    /** Features and capabilities this app provides */
+    /**
+     * Declares what features this app supports.
+     */
     capabilities: McpUiAppCapabilities;
     /**
-     * Called after App is created but before connection.
+     * Called after {@link App `App`} is created but before connection.
      *
      * Use this to register request/notification handlers that need to be in place
      * before the initialization handshake completes.
      *
-     * @param app - The newly created App instance
+     * @param app - The newly created `App` instance
      *
-     * @example Register a notification handler
-     * ```typescript
-     * import { McpUiToolInputNotificationSchema } from '@modelcontextprotocol/ext-apps/react';
-     *
-     * onAppCreated: (app) => {
-     *   app.setNotificationHandler(
-     *     McpUiToolInputNotificationSchema,
-     *     (notification) => {
-     *       console.log("Tool input:", notification.params.arguments);
-     *     }
-     *   );
-     * }
+     * @example Register an event handler
+     * ```tsx source="./useApp.examples.tsx#useApp_registerHandler"
+     * useApp({
+     *   appInfo: { name: "MyApp", version: "1.0.0" },
+     *   capabilities: {},
+     *   onAppCreated: (app) => {
+     *     app.ontoolresult = (result) => {
+     *       console.log("Tool result:", result);
+     *     };
+     *   },
+     * });
      * ```
      */
     onAppCreated?: (app: App) => void;
 }
 /**
- * State returned by the useApp hook.
+ * State returned by the {@link useApp `useApp`} hook.
  */
 export interface AppState {
-    /** The connected App instance, null during initialization */
+    /** The connected {@link App `App`} instance, null during initialization */
     app: App | null;
     /** Whether initialization completed successfully */
     isConnected: boolean;
@@ -54,48 +55,61 @@ export interface AppState {
 /**
  * React hook to create and connect an MCP App.
  *
- * This hook manages the complete lifecycle of an {@link App}: creation, connection,
- * and cleanup. It automatically creates a {@link PostMessageTransport} to window.parent
- * and handles initialization.
+ * This hook manages {@link App `App`} creation and connection. It automatically
+ * creates a {@link PostMessageTransport `PostMessageTransport`} to window.parent and handles
+ * initialization.
+ *
+ * This hook is part of the optional React integration. The core SDK (`App`,
+ * `PostMessageTransport`) is framework-agnostic and can be used with any UI
+ * framework or vanilla JavaScript.
  *
  * **Important**: The hook intentionally does NOT re-run when options change
  * to avoid reconnection loops. Options are only used during the initial mount.
- *
- * **Note**: This is part of the optional React integration. The core SDK
- * (App, PostMessageTransport) is framework-agnostic and can be
- * used with any UI framework or vanilla JavaScript.
+ * Furthermore, the `App` instance is NOT closed on unmount. This avoids cleanup
+ * issues during React Strict Mode's double-mount cycle. If you need to
+ * explicitly close the `App`, call {@link App.close `App.close`} manually.
  *
  * @param options - Configuration for the app
  * @returns Current connection state and app instance. If connection fails during
  *   initialization, the `error` field will contain the error (typically connection
  *   timeouts, initialization handshake failures, or transport errors).
  *
- * @example Basic usage
- * ```typescript
- * import { useApp, McpUiToolInputNotificationSchema } from '@modelcontextprotocol/ext-apps/react';
- *
+ * @example Basic usage of useApp hook with common event handlers
+ * ```tsx source="./useApp.examples.tsx#useApp_basicUsage"
  * function MyApp() {
+ *   const [hostContext, setHostContext] = useState<
+ *     McpUiHostContext | undefined
+ *   >(undefined);
+ *
  *   const { app, isConnected, error } = useApp({
  *     appInfo: { name: "MyApp", version: "1.0.0" },
  *     capabilities: {},
  *     onAppCreated: (app) => {
- *       // Register handlers before connection
- *       app.setNotificationHandler(
- *         McpUiToolInputNotificationSchema,
- *         (notification) => {
- *           console.log("Tool input:", notification.params.arguments);
- *         }
- *       );
+ *       app.ontoolinput = (input) => {
+ *         console.log("Tool input:", input);
+ *       };
+ *       app.ontoolresult = (result) => {
+ *         console.log("Tool result:", result);
+ *       };
+ *       app.ontoolcancelled = (params) => {
+ *         console.log("Tool cancelled:", params.reason);
+ *       };
+ *       app.onerror = (error) => {
+ *         console.log("Error:", error);
+ *       };
+ *       app.onhostcontextchanged = (params) => {
+ *         setHostContext((prev) => ({ ...prev, ...params }));
+ *       };
  *     },
  *   });
  *
  *   if (error) return <div>Error: {error.message}</div>;
  *   if (!isConnected) return <div>Connecting...</div>;
- *   return <div>Connected!</div>;
+ *   return <div>Theme: {hostContext?.theme}</div>;
  * }
  * ```
  *
- * @see {@link App.connect} for the underlying connection method
- * @see {@link useAutoResize} for manual auto-resize control when using custom App options
+ * @see {@link App.connect `App.connect`} for the underlying connection method
+ * @see {@link useAutoResize `useAutoResize`} for manual auto-resize control when using custom App options
  */
 export declare function useApp({ appInfo, capabilities, onAppCreated, }: UseAppOptions): AppState;

package/dist/src/react/useApp.examples.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type-checked examples for the useApp hook.
+ *
+ * @module
+ */
+export {};

package/dist/src/react/useAutoResize.d.ts

@@ -3,21 +3,23 @@ import { App } from "../app";
 /**
  * React hook that automatically reports UI size changes to the host.
  *
- * Uses ResizeObserver to watch `document.body` and `document.documentElement` for
+ * Uses `ResizeObserver` to watch `document.body` and `document.documentElement` for
  * size changes and sends `ui/notifications/size-changed` notifications.
  *
- * **Note**: This hook is rarely needed since the {@link useApp} hook automatically enables
+ * The hook automatically cleans up the `ResizeObserver` when the component unmounts.
+ *
+ * **Note**: This hook is rarely needed since the {@link useApp `useApp`} hook automatically enables
  * auto-resize by default. This hook is provided for advanced cases where you
- * create the {@link App} manually with `autoResize: false` and want to add auto-resize
+ * create the {@link App `App`} manually with `autoResize: false` and want to add auto-resize
  * behavior later.
  *
- * @param app - The connected App instance, or null during initialization
+ * @param app - The connected {@link App `App`} instance, or null during initialization
  * @param elementRef - Currently unused. The hook always observes `document.body`
  *   and `document.documentElement` regardless of this value. Passing a ref will
  *   cause unnecessary effect re-runs; omit this parameter.
  *
  * @example Manual App creation with custom auto-resize control
- * ```tsx
+ * ```tsx source="./useAutoResize.examples.tsx#useAutoResize_manualApp"
  * function MyComponent() {
  *   // For custom App options, create App manually instead of using useApp
  *   const [app, setApp] = useState<App | null>(null);
@@ -27,11 +29,12 @@ import { App } from "../app";
  *     const myApp = new App(
  *       { name: "MyApp", version: "1.0.0" },
  *       {}, // capabilities
- *       { autoResize: false } // Disable default auto-resize
+ *       { autoResize: false }, // Disable default auto-resize
  *     );
  *
- *     const transport = new PostMessageTransport(window.parent);
- *     myApp.connect(transport)
+ *     const transport = new PostMessageTransport(window.parent, window.parent);
+ *     myApp
+ *       .connect(transport)
  *       .then(() => setApp(myApp))
  *       .catch((err) => setError(err));
  *   }, []);
@@ -44,8 +47,8 @@ import { App } from "../app";
  * }
  * ```
  *
- * @see {@link App.setupSizeChangedNotifications} for the underlying implementation
- * @see {@link useApp} which enables auto-resize by default
- * @see {@link App} constructor for configuring `autoResize` option
+ * @see {@link App.setupSizeChangedNotifications `App.setupSizeChangedNotifications`} for the underlying implementation
+ * @see {@link useApp `useApp`} which enables auto-resize by default
+ * @see {@link App `App`} constructor for configuring `autoResize` option
  */
 export declare function useAutoResize(app: App | null, elementRef?: RefObject<HTMLElement | null>): void;

package/dist/src/react/useAutoResize.examples.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type-checked examples for the useAutoResize hook.
+ *
+ * @module
+ */
+export {};

package/dist/src/react/useDocumentTheme.d.ts

@@ -2,45 +2,43 @@ import { McpUiTheme } from "../types";
 /**
  * React hook that provides the current document theme reactively.
  *
- * Uses a MutationObserver to watch for changes to the `data-theme` attribute
+ * Uses a `MutationObserver` to watch for changes to the `data-theme` attribute
  * or `class` on `document.documentElement`. When the theme changes (e.g., from
  * host context updates), the hook automatically re-renders your component with
  * the new theme value.
  *
+ * The `MutationObserver` is automatically disconnected when the component unmounts.
+ *
  * @returns The current theme ("light" or "dark")
  *
  * @example Conditionally render based on theme
- * ```tsx
- * import { useDocumentTheme } from '@modelcontextprotocol/ext-apps/react';
- *
+ * ```tsx source="./useDocumentTheme.examples.tsx#useDocumentTheme_conditionalRender"
  * function MyApp() {
  *   const theme = useDocumentTheme();
  *
- *   return (
- *     <div>
- *       {theme === 'dark' ? <DarkIcon /> : <LightIcon />}
- *     </div>
- *   );
+ *   return <div>{theme === "dark" ? <DarkIcon /> : <LightIcon />}</div>;
  * }
  * ```
  *
  * @example Use with theme-aware styling
- * ```tsx
+ * ```tsx source="./useDocumentTheme.examples.tsx#useDocumentTheme_themedButton"
  * function ThemedButton() {
  *   const theme = useDocumentTheme();
  *
  *   return (
- *     <button style={{
- *       background: theme === 'dark' ? '#333' : '#fff',
- *       color: theme === 'dark' ? '#fff' : '#333',
- *     }}>
+ *     <button
+ *       style={{
+ *         background: theme === "dark" ? "#333" : "#fff",
+ *         color: theme === "dark" ? "#fff" : "#333",
+ *       }}
+ *     >
  *       Click me
  *     </button>
  *   );
  * }
  * ```
  *
- * @see {@link getDocumentTheme} for the underlying function
- * @see {@link applyDocumentTheme} to set the theme
+ * @see {@link getDocumentTheme `getDocumentTheme`} for the underlying function
+ * @see {@link applyDocumentTheme `applyDocumentTheme`} to set the theme
  */
 export declare function useDocumentTheme(): McpUiTheme;

package/dist/src/react/useDocumentTheme.examples.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type-checked examples for the useDocumentTheme hook.
+ *
+ * @module
+ */
+export {};

package/dist/src/react/useHostStyles.d.ts

@@ -14,45 +14,33 @@ import { McpUiHostContext } from "../types";
  * this hook ensures they work correctly by setting the `color-scheme` property
  * based on the host's theme preference.
  *
- * @param app - The connected App instance, or null during initialization
+ * @param app - The connected {@link App `App`} instance, or null during initialization
  * @param initialContext - Initial host context from the connection (optional).
  *   If provided, styles and theme will be applied immediately on mount.
  *
- * @example Basic usage with useApp
- * ```tsx
- * import { useApp } from '@modelcontextprotocol/ext-apps/react';
- * import { useHostStyleVariables } from '@modelcontextprotocol/ext-apps/react';
- *
+ * @example
+ * ```tsx source="./useHostStyles.examples.tsx#useHostStyleVariables_basicUsage"
  * function MyApp() {
- *   const { app, isConnected } = useApp({
+ *   const { app } = useApp({
  *     appInfo: { name: "MyApp", version: "1.0.0" },
  *     capabilities: {},
  *   });
  *
- *   // Automatically apply host style variables and theme
- *   useHostStyleVariables(app);
+ *   // Apply host styles - pass initial context to apply styles from connect() immediately
+ *   useHostStyleVariables(app, app?.getHostContext());
  *
  *   return (
- *     <div style={{ background: 'var(--color-background-primary)' }}>
+ *     <div style={{ background: "var(--color-background-primary)" }}>
  *       Hello!
  *     </div>
  *   );
  * }
  * ```
  *
- * @example With initial context
- * ```tsx
- * const [hostContext, setHostContext] = useState<McpUiHostContext | null>(null);
- *
- * // ... get initial context from app.connect() result
- *
- * useHostStyleVariables(app, hostContext);
- * ```
- *
- * @see {@link applyHostStyleVariables} for the underlying styles function
- * @see {@link applyDocumentTheme} for the underlying theme function
- * @see {@link useHostFonts} for applying host fonts
- * @see {@link McpUiStyles} for available CSS variables
+ * @see {@link applyHostStyleVariables `applyHostStyleVariables`} for the underlying styles function
+ * @see {@link applyDocumentTheme `applyDocumentTheme`} for the underlying theme function
+ * @see {@link useHostFonts `useHostFonts`} for applying host fonts
+ * @see {@link McpUiStyles `McpUiStyles`} for available CSS variables
  */
 export declare function useHostStyleVariables(app: App | null, initialContext?: McpUiHostContext | null): void;
 /**
@@ -67,55 +55,59 @@ export declare function useHostStyleVariables(app: App | null, initialContext?:
  * The hook also applies fonts from the initial host context when
  * the app first connects.
  *
- * @param app - The connected App instance, or null during initialization
+ * @param app - The connected {@link App `App`} instance, or null during initialization
  * @param initialContext - Initial host context from the connection (optional).
  *   If provided, fonts will be applied immediately on mount.
  *
  * @example Basic usage with useApp
- * ```tsx
- * import { useApp } from '@modelcontextprotocol/ext-apps/react';
- * import { useHostFonts } from '@modelcontextprotocol/ext-apps/react';
- *
+ * ```tsx source="./useHostStyles.examples.tsx#useHostFonts_basicUsage"
  * function MyApp() {
- *   const { app, isConnected } = useApp({
+ *   const { app } = useApp({
  *     appInfo: { name: "MyApp", version: "1.0.0" },
  *     capabilities: {},
  *   });
  *
- *   // Automatically apply host fonts
- *   useHostFonts(app);
+ *   // Apply host fonts - pass initial context to apply fonts from connect() immediately
+ *   useHostFonts(app, app?.getHostContext());
  *
- *   return (
- *     <div style={{ fontFamily: 'var(--font-sans)' }}>
- *       Hello!
- *     </div>
- *   );
+ *   return <div style={{ fontFamily: "var(--font-sans)" }}>Hello!</div>;
  * }
  * ```
  *
- * @example With initial context
- * ```tsx
- * const [hostContext, setHostContext] = useState<McpUiHostContext | null>(null);
- *
- * // ... get initial context from app.connect() result
- *
- * useHostFonts(app, hostContext);
- * ```
- *
- * @see {@link applyHostFonts} for the underlying fonts function
- * @see {@link useHostStyleVariables} for applying style variables and theme
+ * @see {@link applyHostFonts `applyHostFonts`} for the underlying fonts function
+ * @see {@link useHostStyleVariables `useHostStyleVariables`} for applying style variables and theme
  */
 export declare function useHostFonts(app: App | null, initialContext?: McpUiHostContext | null): void;
 /**
- * React hook that applies host styles, fonts, and theme.
+ * Applies all host styling (CSS variables, theme, and fonts) to match the host application.
  *
- * This is a convenience hook that combines {@link useHostStyleVariables} and
- * {@link useHostFonts}. Use the individual hooks if you need more control.
+ * This is a convenience hook that combines {@link useHostStyleVariables `useHostStyleVariables`} and
+ * {@link useHostFonts `useHostFonts`}. Use the individual hooks if you need more control.
  *
- * @param app - The connected App instance, or null during initialization
+ * @param app - The connected {@link App `App`} instance, or null during initialization
  * @param initialContext - Initial host context from the connection (optional).
+ *   Pass `app?.getHostContext()` to apply styles immediately on mount.
+ *
+ * @example
+ * ```tsx source="./useHostStyles.examples.tsx#useHostStyles_basicUsage"
+ * function MyApp() {
+ *   const { app } = useApp({
+ *     appInfo: { name: "MyApp", version: "1.0.0" },
+ *     capabilities: {},
+ *   });
+ *
+ *   // Apply all host styles - pass initial context to apply styles from connect() immediately
+ *   useHostStyles(app, app?.getHostContext());
+ *
+ *   return (
+ *     <div style={{ background: "var(--color-background-primary)" }}>
+ *       Hello!
+ *     </div>
+ *   );
+ * }
+ * ```
  *
- * @see {@link useHostStyleVariables} for style variables and theme only
- * @see {@link useHostFonts} for fonts only
+ * @see {@link useHostStyleVariables `useHostStyleVariables`} for style variables and theme only
+ * @see {@link useHostFonts `useHostFonts`} for fonts only
  */
 export declare function useHostStyles(app: App | null, initialContext?: McpUiHostContext | null): void;

package/dist/src/react/useHostStyles.examples.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type-checked examples for the useHostStyles hooks.
+ *
+ * @module
+ */
+export {};