@blade-hq/agent-react 2612.0.0-beta.67 → 2612.0.0-beta.69

package/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useApp.d.ts

@@ -0,0 +1,115 @@
+import type { Implementation } from "@modelcontextprotocol/client";
+import { App, AppOptions, McpUiAppCapabilities } from "../app.js";
+export * from "../app.js";
+/**
+ * Options for configuring the {@link useApp `useApp`} hook.
+ *
+ * The `autoResize` and `strict` options are forwarded to the underlying
+ * {@link App `App`} instance. For other {@link AppOptions `AppOptions`},
+ * create the `App` manually instead of using this hook.
+ *
+ * @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 extends Pick<AppOptions, "autoResize" | "strict"> {
+    /** App identification (name and version) */
+    appInfo: Implementation;
+    /**
+     * Declares what features this app supports.
+     */
+    capabilities: McpUiAppCapabilities;
+    /**
+     * 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
+     *
+     * @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 {@link useApp `useApp`} hook.
+ */
+export interface AppState {
+    /** The connected {@link App `App`} instance, null during initialization */
+    app: App | null;
+    /** Whether initialization completed successfully */
+    isConnected: boolean;
+    /** Connection error if initialization failed, null otherwise */
+    error: Error | null;
+}
+/**
+ * React hook to create and connect an MCP App.
+ *
+ * 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.
+ * 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 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) => {
+ *       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 = (ctx) => {
+ *         setHostContext((prev) => ({ ...prev, ...ctx }));
+ *       };
+ *     },
+ *   });
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!isConnected) return <div>Connecting...</div>;
+ *   return <div>Theme: {hostContext?.theme}</div>;
+ * }
+ * ```
+ *
+ * @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, autoResize, strict, }: UseAppOptions): AppState;

package/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useApp.examples.d.ts

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

package/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useAutoResize.d.ts

@@ -0,0 +1,54 @@
+import { RefObject } from "react";
+import { App } from "../app.js";
+/**
+ * React hook that automatically reports UI size changes to the host.
+ *
+ * Uses `ResizeObserver` to watch `document.body` and `document.documentElement` for
+ * size changes and sends `ui/notifications/size-changed` notifications.
+ *
+ * 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 `App`} manually with `autoResize: false` and want to add auto-resize
+ * behavior later.
+ *
+ * @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 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);
+ *   const [error, setError] = useState<Error | null>(null);
+ *
+ *   useEffect(() => {
+ *     const myApp = new App(
+ *       { name: "MyApp", version: "1.0.0" },
+ *       {}, // capabilities
+ *       { autoResize: false }, // Disable default auto-resize
+ *     );
+ *
+ *     const transport = new PostMessageTransport(window.parent, window.parent);
+ *     myApp
+ *       .connect(transport)
+ *       .then(() => setApp(myApp))
+ *       .catch((err) => setError(err));
+ *   }, []);
+ *
+ *   // Add manual auto-resize control
+ *   useAutoResize(app);
+ *
+ *   if (error) return <div>Connection failed: {error.message}</div>;
+ *   return <div>My content</div>;
+ * }
+ * ```
+ *
+ * @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/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useAutoResize.examples.d.ts

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

package/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useDocumentTheme.d.ts

@@ -0,0 +1,44 @@
+import { McpUiTheme } from "../types.js";
+/**
+ * React hook that provides the current document theme reactively.
+ *
+ * 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 source="./useDocumentTheme.examples.tsx#useDocumentTheme_conditionalRender"
+ * function MyApp() {
+ *   const theme = useDocumentTheme();
+ *
+ *   return <div>{theme === "dark" ? <DarkIcon /> : <LightIcon />}</div>;
+ * }
+ * ```
+ *
+ * @example Use with theme-aware styling
+ * ```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",
+ *       }}
+ *     >
+ *       Click me
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link getDocumentTheme `getDocumentTheme`} for the underlying function
+ * @see {@link applyDocumentTheme `applyDocumentTheme`} to set the theme
+ */
+export declare function useDocumentTheme(): McpUiTheme;

package/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useDocumentTheme.examples.d.ts

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

package/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useHostStyles.d.ts

@@ -0,0 +1,113 @@
+import { App } from "../app.js";
+import { McpUiHostContext } from "../types.js";
+/**
+ * React hook that applies host style variables and theme as CSS custom properties.
+ *
+ * This hook listens to host context changes and automatically applies:
+ * - `styles.variables` CSS variables to `document.documentElement` (e.g., `--color-background-primary`)
+ * - `theme` via `color-scheme` CSS property, enabling `light-dark()` CSS function support
+ *
+ * The hook also applies styles and theme from the initial host context when
+ * the app first connects.
+ *
+ * **Note:** If the host provides style values using CSS `light-dark()` function,
+ * this hook ensures they work correctly by setting the `color-scheme` property
+ * based on the host's theme preference.
+ *
+ * @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
+ * ```tsx source="./useHostStyles.examples.tsx#useHostStyleVariables_basicUsage"
+ * function MyApp() {
+ *   const { app } = useApp({
+ *     appInfo: { name: "MyApp", version: "1.0.0" },
+ *     capabilities: {},
+ *   });
+ *
+ *   // Apply host styles - pass initial context to apply styles from connect() immediately
+ *   useHostStyleVariables(app, app?.getHostContext());
+ *
+ *   return (
+ *     <div style={{ background: "var(--color-background-primary)" }}>
+ *       Hello!
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @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;
+/**
+ * React hook that applies host fonts from CSS.
+ *
+ * This hook listens to host context changes and automatically applies:
+ * - `styles.css.fonts` as a `<style>` tag for custom fonts
+ *
+ * The CSS can contain `@font-face` rules for self-hosted fonts,
+ * `@import` statements for Google Fonts or other font services, or both.
+ *
+ * The hook also applies fonts from the initial host context when
+ * the app first connects.
+ *
+ * @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 source="./useHostStyles.examples.tsx#useHostFonts_basicUsage"
+ * function MyApp() {
+ *   const { app } = useApp({
+ *     appInfo: { name: "MyApp", version: "1.0.0" },
+ *     capabilities: {},
+ *   });
+ *
+ *   // 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>;
+ * }
+ * ```
+ *
+ * @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;
+/**
+ * Applies all host styling (CSS variables, theme, and fonts) to match the host application.
+ *
+ * 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 {@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 `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/node_modules/@modelcontextprotocol/ext-apps/dist/src/react/useHostStyles.examples.d.ts

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