open-mcp-app 0.0.2

package/dist/core/index.d.ts

@@ -0,0 +1,1095 @@
+export { applyDocumentTheme, applyHostFonts, applyHostStyleVariables, getDocumentTheme } from '@modelcontextprotocol/ext-apps';
+
+/**
+ * Core SDK Types
+ *
+ * Unified type definitions for the MCP Apps SDK.
+ * Provides a single, consistent API across all host environments.
+ */
+/**
+ * Environment types for host detection.
+ * The SDK automatically detects which environment it's running in.
+ */
+type Environment = "chatgpt" | "mcp-apps" | "standalone";
+/**
+ * Display modes for UI resources.
+ * - "inline": Embedded within the conversation flow
+ * - "pip": Picture-in-picture floating panel
+ * - "fullscreen": Full-screen overlay
+ */
+type DisplayMode = "inline" | "pip" | "fullscreen";
+/**
+ * Log severity levels matching MCP protocol LoggingLevel.
+ * Logs are displayed in the host's DevConsole with appropriate colors.
+ */
+type LogLevel = "debug" | "info" | "notice" | "warning" | "error";
+/**
+ * Structured widget state format (ChatGPT-compatible).
+ * Allows separating model-visible content from private UI state.
+ */
+interface StructuredWidgetState {
+    /** Content visible to the AI model on follow-up turns */
+    modelContent?: string | Record<string, unknown> | null;
+    /** UI-only state, hidden from model */
+    privateContent?: Record<string, unknown> | null;
+    /** File IDs for images the model can see */
+    imageIds?: string[];
+}
+/**
+ * Widget state can be structured (with modelContent/privateContent)
+ * or a simple key-value object.
+ */
+type WidgetState = StructuredWidgetState | Record<string, unknown>;
+/**
+ * Tool call result structure.
+ */
+interface ToolResult<T = Record<string, unknown>> {
+    content?: Array<{
+        type: string;
+        text: string;
+    }>;
+    structuredContent?: T;
+    isError?: boolean;
+    source?: "agent" | "ui";
+    /** Tool name that produced this result (for view routing) */
+    toolName?: string;
+}
+/**
+ * Context about how the view was opened.
+ * SDK uses this to determine initialization behavior.
+ */
+interface OpenContext {
+    /**
+     * How the view was opened:
+     * - "tool": Opened by an agent tool call (expect tool-input/tool-result)
+     * - "user": Opened directly by user (no tool notifications coming)
+     * - "restore": Restoring previous state (popout, pop-back-in, refresh).
+     *              Uses widgetState.modelContent.view for initial view.
+     */
+    triggeredBy: "tool" | "user" | "restore";
+}
+/**
+ * Host context sent from MCP Apps host.
+ * Follows MCP Apps spec with extensions via [key: string]: unknown.
+ */
+interface HostContext {
+    theme?: "light" | "dark";
+    styles?: {
+        variables?: Record<string, string>;
+        css?: {
+            fonts?: string;
+        };
+    };
+    displayMode?: DisplayMode;
+    availableDisplayModes?: DisplayMode[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    platform?: string;
+    /**
+     * Host application identifier per MCP Apps spec.
+     * Format: "<host>/<version>" (e.g. "creature/1.0.0", "chatgpt/2.0.0").
+     */
+    userAgent?: string;
+    /**
+     * Widget state restored from previous widget instance.
+     */
+    widgetState?: WidgetState;
+    /**
+     * Context about how the view was opened.
+     * Per MCP Apps spec extensibility, sent in hostContext.
+     */
+    openContext?: OpenContext;
+    /**
+     * Experimental (non-standard) extensions.
+     * Follows the SDK's `experimental` namespace paradigm.
+     */
+    experimental?: {
+        /**
+         * Additional CSS variables beyond the MCP Apps spec.
+         * Apps should apply these alongside spec styles for enhanced theming.
+         */
+        styles?: {
+            variables?: Record<string, string | undefined>;
+        };
+    };
+    /**
+     * Allow additional host-specific properties.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Content block types for model context updates.
+ */
+interface TextContentBlock {
+    type: "text";
+    text: string;
+}
+interface ImageContentBlock {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+type ContentBlock = TextContentBlock | ImageContentBlock;
+/**
+ * Configuration for creating a host client.
+ */
+interface HostClientConfig {
+    /** Name of the client (for protocol handshake) */
+    name: string;
+    /** Version of the client */
+    version: string;
+}
+/**
+ * State managed by the host client.
+ */
+interface HostClientState {
+    /** Whether the host connection is ready */
+    isReady: boolean;
+    /** The detected environment */
+    environment: Environment;
+    /** Current widget state */
+    widgetState: WidgetState | null;
+}
+/**
+ * Listener for state changes.
+ */
+type StateListener = (state: HostClientState, prevState: HostClientState) => void;
+/**
+ * All events supported by the unified host client.
+ * Events that aren't supported by a host are no-op subscriptions.
+ */
+interface HostClientEvents {
+    /** Called when tool input is received (before execution) */
+    "tool-input": (args: Record<string, unknown>) => void;
+    /** Called when tool result is received */
+    "tool-result": (result: ToolResult) => void;
+    /** Called when widget state changes (restored or updated) */
+    "widget-state-change": (widgetState: WidgetState | null) => void;
+    /** Called when theme changes (MCP Apps only, no-op on ChatGPT) */
+    "theme-change": (theme: "light" | "dark") => void;
+    /** Called when host requests teardown (MCP Apps only, no-op on ChatGPT) */
+    "teardown": () => Promise<void> | void;
+}
+/**
+ * Experimental host APIs that are not part of the MCP Apps spec.
+ *
+ * These APIs provide access to host-specific features that may not be
+ * supported by all hosts. Methods gracefully degrade (no-op or return null)
+ * when called on unsupported hosts.
+ */
+interface ExpHostApi {
+    /**
+     * Set widget state and notify the host.
+     *
+     * Widget state is synchronized with the host for persistence across
+     * sessions and visibility to the AI model.
+     *
+     * - ChatGPT: Native support via `window.openai.setWidgetState`
+     * - Creature: Extension via `ui/notifications/widget-state-changed`
+     * - Generic MCP Apps hosts: May not support (state stored locally)
+     * - Standalone: Stores locally
+     */
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Set the pip/widget title displayed in the host UI.
+     *
+     * Creature only - no-op on ChatGPT and generic MCP Apps hosts.
+     */
+    setTitle(title: string): void;
+    /**
+     * Update the model context for future turns.
+     *
+     * In MCP Apps spec as `ui/update-model-context`. Context is available
+     * to the model in future turns without triggering immediate response.
+     * Each call overwrites previous context.
+     *
+     * - MCP Apps hosts: Supported (if host declares capability)
+     * - ChatGPT: No-op
+     */
+    updateModelContext(content: ContentBlock[]): Promise<void>;
+    /**
+     * Send a raw notification to the host.
+     *
+     * Low-level API for power users. Most apps should use higher-level methods.
+     * MCP Apps only - no-op on ChatGPT.
+     */
+    sendNotification(method: string, params: unknown): void;
+    /**
+     * Get the instance ID for this widget.
+     *
+     * Multi-instance support is a Creature extension.
+     * - Creature: Full support for multiple instances with independent state
+     * - ChatGPT: May return session ID, singleton behavior
+     * - Generic MCP Apps hosts: Returns null
+     */
+    getInstanceId(): string | null;
+    /**
+     * Check if the host supports multi-instance resources.
+     *
+     * - Creature: true
+     * - ChatGPT: false (singleton only)
+     * - Generic MCP Apps hosts: false
+     */
+    supportsMultiInstance(): boolean;
+    /**
+     * Get the initial tool result if view was opened by an agent tool call.
+     *
+     * Returns the first tool result received, or null if:
+     * - View was opened directly by user (no tool call)
+     * - Tool result hasn't arrived yet (shouldn't happen after isReady=true)
+     *
+     * This enables clean initialization:
+     * ```typescript
+     * const { isReady, getInitialToolResult } = useHost();
+     * useEffect(() => {
+     *   if (!isReady) return;
+     *   const initial = getInitialToolResult();
+     *   if (initial) {
+     *     // View opened by agent - use the tool result data
+     *     processData(initial.structuredContent);
+     *   } else {
+     *     // View opened by user - fetch initial data
+     *     fetchData();
+     *   }
+     * }, [isReady]);
+     * ```
+     */
+    getInitialToolResult(): ToolResult | null;
+    /**
+     * Send a follow-up message to the conversation.
+     *
+     * ChatGPT only. Triggers a new model turn with the given prompt.
+     * No-op on MCP Apps hosts.
+     */
+    sendFollowUpMessage(prompt: string): Promise<void>;
+    /**
+     * Open a modal dialog from the host.
+     *
+     * ChatGPT only. Returns null on MCP Apps hosts.
+     */
+    requestModal(options: {
+        title?: string;
+        params?: Record<string, unknown>;
+    }): Promise<unknown | null>;
+    /**
+     * Request the host to close this widget.
+     *
+     * ChatGPT only. No-op on MCP Apps hosts.
+     */
+    requestClose(): Promise<void>;
+}
+/**
+ * Unified host client interface.
+ *
+ * This is the primary interface returned by `createHost()`.
+ * Provides a consistent API across all host environments (ChatGPT, MCP Apps, Standalone).
+ */
+interface UnifiedHostClient {
+    /**
+     * The detected environment.
+     */
+    readonly environment: Environment;
+    /**
+     * Get current client state.
+     */
+    getState(): HostClientState;
+    /**
+     * Subscribe to state changes. Returns unsubscribe function.
+     */
+    subscribe(listener: StateListener): () => void;
+    /**
+     * Get the host context received from the host.
+     * Contains theme, styles, userAgent, and host-specific properties.
+     * Returns null before connection is established or on ChatGPT.
+     */
+    getHostContext(): HostContext | null;
+    /**
+     * Call a tool on the MCP server.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Request a display mode change from the host.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Send a log message to host DevConsole.
+     * Falls back to browser console on ChatGPT.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Register an event handler. Returns unsubscribe function.
+     */
+    on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
+    /**
+     * Start listening for host messages.
+     */
+    connect(): void;
+    /**
+     * Stop listening for host messages.
+     */
+    disconnect(): void;
+    /**
+     * Experimental APIs for non-standard features.
+     *
+     * These APIs provide access to host-specific features that may not be
+     * supported by all hosts. Methods gracefully degrade when unsupported.
+     */
+    readonly exp: ExpHostApi;
+}
+/**
+ * WebSocket connection status.
+ */
+type WebSocketStatus = "disconnected" | "connecting" | "connected" | "error";
+/**
+ * Configuration for creating a WebSocket client.
+ */
+interface WebSocketClientConfig<TReceive = unknown> {
+    /** Called when a message is received */
+    onMessage?: (message: TReceive) => void;
+    /** Called when connection status changes */
+    onStatusChange?: (status: WebSocketStatus, error?: string) => void;
+    /** Whether to auto-reconnect on disconnect (default: true) */
+    reconnect?: boolean;
+    /** Base interval for reconnection attempts in ms (default: 1000) */
+    reconnectInterval?: number;
+}
+/**
+ * WebSocket client interface.
+ */
+interface WebSocketClient<TSend = unknown, TReceive = unknown> {
+    /** Current connection status */
+    readonly status: WebSocketStatus;
+    /** Error message if status is "error" */
+    readonly error: string | undefined;
+    /** Connect to the WebSocket server */
+    connect(): void;
+    /** Disconnect from the WebSocket server */
+    disconnect(): void;
+    /** Send a message to the server */
+    send(message: TSend): void;
+}
+
+/**
+ * Subscribable Base Class
+ *
+ * Provides event emitter pattern for state changes and host events.
+ * Used as a base class for all host client implementations.
+ */
+
+/**
+ * Base class for subscribable host clients.
+ * Provides unified event handling for state changes and host events.
+ */
+declare abstract class Subscribable {
+    private stateListeners;
+    private eventHandlers;
+    private mcpEventHandlers;
+    /**
+     * Subscribe to state changes.
+     *
+     * @param listener - Callback invoked when state changes
+     * @returns Unsubscribe function
+     */
+    protected subscribeToState(listener: StateListener): () => void;
+    /**
+     * Register a handler for base events.
+     *
+     * @param event - The event name
+     * @param handler - The event handler
+     * @returns Unsubscribe function
+     */
+    protected onEvent<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
+    /**
+     * Get the number of subscribers for an event.
+     *
+     * @param event - The event name
+     * @returns Number of subscribers
+     */
+    protected getSubscriberCount(event: keyof HostClientEvents): number;
+    /**
+     * Register a handler for MCP-specific events (theme-change, teardown).
+     *
+     * @param event - The event name
+     * @param handler - The event handler
+     * @returns Unsubscribe function
+     */
+    protected onMcpEvent<K extends "theme-change" | "teardown">(event: K, handler: K extends "theme-change" ? (theme: "light" | "dark") => void : () => Promise<void> | void): () => void;
+    /**
+     * Notify all state listeners of a state change.
+     */
+    protected notifyStateChange(state: HostClientState, prevState: HostClientState): void;
+    /**
+     * Emit a base event to all registered handlers.
+     */
+    protected emit<K extends keyof HostClientEvents>(event: K, ...args: Parameters<HostClientEvents[K]>): void;
+    /**
+     * Emit an MCP-specific event to all registered handlers.
+     */
+    protected emitMcpEvent<K extends "theme-change" | "teardown">(event: K, ...args: K extends "theme-change" ? ["light" | "dark"] : []): void | Promise<void>;
+}
+
+/**
+ * Creature Desktop Host Client
+ *
+ * Host client for the Creature Desktop environment.
+ * Handles iframe postMessage communication with the Creature host application.
+ */
+
+/**
+ * Creature Desktop host client implementation.
+ *
+ * Provides full MCP Apps support with Creature-specific extensions:
+ * - Multi-instance support
+ * - Dynamic title changes
+ * - Views-based routing
+ *
+ * Event Buffering:
+ * Tool-input and tool-result events may arrive before React components
+ * have subscribed (due to useEffect timing). We buffer these events and
+ * replay them when the first subscriber is added, ensuring no data is lost.
+ */
+declare class CreatureDesktopHostClient extends Subscribable implements UnifiedHostClient {
+    readonly environment: "mcp-apps";
+    private state;
+    private config;
+    private app;
+    private connected;
+    private hostContext;
+    private instanceId;
+    /**
+     * Whether this view was triggered by a tool call.
+     * Determined from openContext.triggeredBy in hostContext.
+     */
+    private triggeredByTool;
+    /**
+     * Whether we've received the initial tool-result notification.
+     * Used to gate isReady when triggeredByTool is true.
+     */
+    private hasReceivedToolResult;
+    /**
+     * The initial tool result received when view was opened by agent.
+     * Stored for getInitialToolResult() access.
+     */
+    private initialToolResult;
+    /**
+     * Buffered events for replay when subscribers are added.
+     *
+     * Events may arrive before React's useEffect sets up subscriptions.
+     * We buffer them here and replay when the first subscriber is added.
+     */
+    private bufferedToolInput;
+    private bufferedToolResult;
+    constructor(config: HostClientConfig);
+    /**
+     * Create a Creature Desktop host client instance.
+     */
+    static create(config: HostClientConfig): CreatureDesktopHostClient;
+    getState(): HostClientState;
+    getHostContext(): HostContext | null;
+    subscribe(listener: StateListener): () => void;
+    /**
+     * Connect to the Creature Desktop host.
+     *
+     * Creates the App instance, registers notification handlers, and initiates
+     * the protocol handshake. The host responds with hostContext including
+     * theme, styles, and widgetState.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the host.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool on the MCP server via the host.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Request a display mode change from the host.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Send a log message to the host's DevConsole.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
+    /**
+     * Experimental APIs (shared across all hosts).
+     * Behavior varies by host - see ExpHostApi for details.
+     */
+    get exp(): ExpHostApi;
+    /**
+     * Send a notification to the host.
+     */
+    private sendNotification;
+    /**
+     * Update internal state and notify listeners.
+     */
+    private setState;
+    /**
+     * Check if there are any subscribers for an event type.
+     */
+    private hasSubscribers;
+    /**
+     * Set up notification handlers on the App instance.
+     *
+     * Events are buffered if no subscribers exist yet. When a subscriber
+     * is added via on(), buffered events are replayed immediately.
+     *
+     * For tool-triggered views, isReady is set after tool-result is received.
+     * This ensures getInitialToolResult() has data when the app initializes.
+     */
+    private setupHandlers;
+    /**
+     * Initiate connection using PostMessageTransport.
+     *
+     * For user-triggered views: Sets isReady immediately after connection.
+     * For tool-triggered views: Waits for tool-result before setting isReady.
+     * This ensures getInitialToolResult() has data when the app initializes.
+     *
+     * Events that arrive before React subscribes are buffered and replayed.
+     */
+    private initiateConnection;
+    /**
+     * Apply theme, styles, and fonts from host context.
+     */
+    private applyHostContext;
+    /**
+     * Apply experimental CSS variables to the document root.
+     * These are non-standard extensions that enhance the spec styles.
+     */
+    private applyExperimentalStyles;
+    /**
+     * Extract text content from SDK result content array.
+     */
+    private extractTextContent;
+}
+
+/**
+ * Claude Desktop Host Client
+ *
+ * Host client for the Claude Desktop environment.
+ * Handles iframe postMessage communication with the Claude Desktop host application.
+ */
+
+/**
+ * Claude Desktop host client implementation.
+ *
+ * Provides MCP Apps support for Claude Desktop:
+ * - Single-instance only (no multi-instance support)
+ * - No dynamic title changes
+ * - Inline display mode only
+ *
+ * Event Buffering:
+ * Tool-input and tool-result events may arrive before React components
+ * have subscribed (due to useEffect timing). We buffer these events and
+ * replay them when the first subscriber is added, ensuring no data is lost.
+ */
+declare class ClaudeDesktopHostClient extends Subscribable implements UnifiedHostClient {
+    readonly environment: "mcp-apps";
+    private state;
+    private config;
+    private app;
+    private connected;
+    private hostContext;
+    /**
+     * Whether this view was triggered by a tool call.
+     * Determined from openContext.triggeredBy in hostContext.
+     */
+    private triggeredByTool;
+    /**
+     * Whether we've received the initial tool-result notification.
+     * Used to gate isReady when triggeredByTool is true.
+     */
+    private hasReceivedToolResult;
+    /**
+     * The initial tool result received when view was opened by agent.
+     * Stored for getInitialToolResult() access.
+     */
+    private initialToolResult;
+    /**
+     * Buffered events for replay when subscribers are added.
+     *
+     * Events may arrive before React's useEffect sets up subscriptions.
+     * We buffer them here and replay when the first subscriber is added.
+     */
+    private bufferedToolInput;
+    private bufferedToolResult;
+    constructor(config: HostClientConfig);
+    /**
+     * Create a Claude Desktop host client instance.
+     */
+    static create(config: HostClientConfig): ClaudeDesktopHostClient;
+    getState(): HostClientState;
+    getHostContext(): HostContext | null;
+    subscribe(listener: StateListener): () => void;
+    /**
+     * Connect to the Claude Desktop host.
+     *
+     * Creates the App instance, registers notification handlers, and initiates
+     * the protocol handshake. The host responds with hostContext including
+     * theme, styles, and widgetState.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the host.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool on the MCP server via the host.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Request a display mode change from the host.
+     * Claude Desktop only supports inline mode.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Send a log message to the host's DevConsole.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
+    /**
+     * Experimental APIs (shared across all hosts).
+     * Behavior varies by host - see ExpHostApi for details.
+     */
+    get exp(): ExpHostApi;
+    /**
+     * Send a notification to the host.
+     */
+    private sendNotification;
+    /**
+     * Update internal state and notify listeners.
+     */
+    private setState;
+    /**
+     * Check if there are any subscribers for an event type.
+     */
+    private hasSubscribers;
+    /**
+     * Set up notification handlers on the App instance.
+     *
+     * Events are buffered if no subscribers exist yet. When a subscriber
+     * is added via on(), buffered events are replayed immediately.
+     *
+     * For tool-triggered views, isReady is set after tool-result is received.
+     * This ensures getInitialToolResult() has data when the app initializes.
+     */
+    private setupHandlers;
+    /**
+     * Initiate connection using PostMessageTransport.
+     *
+     * For user-triggered views: Sets isReady immediately after connection.
+     * For tool-triggered views: Waits for tool-result before setting isReady.
+     * This ensures getInitialToolResult() has data when the app initializes.
+     *
+     * Events that arrive before React subscribes are buffered and replayed.
+     */
+    private initiateConnection;
+    /**
+     * Apply theme, styles, and fonts from host context.
+     */
+    private applyHostContext;
+    /**
+     * Apply experimental CSS variables to the document root.
+     * These are non-standard extensions that enhance the spec styles.
+     */
+    private applyExperimentalStyles;
+    /**
+     * Extract text content from SDK result content array.
+     */
+    private extractTextContent;
+}
+
+/**
+ * ChatGPT Web Host Client
+ *
+ * Host client for the ChatGPT web environment.
+ * Bridges the ChatGPT Apps SDK (`window.openai`) to the unified interface.
+ */
+
+/**
+ * OpenAI bridge interface exposed by ChatGPT Apps SDK.
+ * Available on `window.openai` when running inside ChatGPT.
+ */
+interface OpenAIBridge {
+    toolOutput?: Record<string, unknown>;
+    widgetState?: WidgetState;
+    setWidgetState?: (state: WidgetState) => void;
+    callTool?: (name: string, args: Record<string, unknown>) => Promise<{
+        structuredContent?: Record<string, unknown>;
+        content?: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+    requestDisplayMode?: (args: {
+        mode: string;
+    }) => Promise<{
+        mode: string;
+    }>;
+    sendFollowUpMessage?: (prompt: string) => Promise<void>;
+    requestModal?: (options: {
+        title?: string;
+        params?: Record<string, unknown>;
+    }) => Promise<unknown>;
+    requestClose?: () => Promise<void>;
+}
+declare global {
+    interface Window {
+        openai?: OpenAIBridge;
+    }
+}
+/**
+ * ChatGPT Web host client implementation.
+ *
+ * Bridges the ChatGPT Apps SDK to provide a unified interface.
+ * MCP-specific features are no-ops.
+ */
+declare class ChatGptWebHostClient extends Subscribable implements UnifiedHostClient {
+    readonly environment: "chatgpt";
+    private state;
+    private config;
+    private connected;
+    private hasProcessedInitialData;
+    private globalsHandler;
+    private lastToolOutputJson;
+    private lastWidgetStateJson;
+    constructor(config: HostClientConfig);
+    /**
+     * Create a ChatGPT Web host client instance.
+     */
+    static create(config: HostClientConfig): ChatGptWebHostClient;
+    /**
+     * Check if the current environment is ChatGPT.
+     */
+    static detect(): boolean;
+    getState(): HostClientState;
+    /**
+     * Get host context - returns null for ChatGPT as it doesn't use MCP Apps protocol.
+     */
+    getHostContext(): HostContext | null;
+    subscribe(listener: StateListener): () => void;
+    /**
+     * Connect to the ChatGPT host.
+     *
+     * Processes initial data from `window.openai` and sets up a listener
+     * for subsequent `openai:set_globals` events.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the host.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool on the MCP server via the ChatGPT bridge.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Request a display mode change from the ChatGPT host.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Log a message to the console.
+     * ChatGPT doesn't have a DevConsole, so logs go to browser console only.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
+    /**
+     * Experimental APIs (shared across all hosts).
+     * Behavior varies by host - see ExpHostApi for details.
+     */
+    get exp(): ExpHostApi;
+    /**
+     * Update internal state and notify listeners.
+     */
+    private setState;
+    /**
+     * Process initial data from `window.openai`.
+     */
+    private processInitialData;
+    /**
+     * Set up listener for `openai:set_globals` events.
+     */
+    private setupGlobalsListener;
+}
+
+/**
+ * Standalone Host Client
+ *
+ * A minimal fallback for when running outside any host environment.
+ * Useful for development and testing scenarios.
+ */
+
+/**
+ * Standalone host client implementation.
+ *
+ * A minimal fallback for development and testing scenarios.
+ * Host-specific features are no-ops or console-logged.
+ */
+declare class StandaloneHostClient extends Subscribable implements UnifiedHostClient {
+    readonly environment: "standalone";
+    private state;
+    private config;
+    private connected;
+    constructor(config: HostClientConfig);
+    /**
+     * Create a Standalone host client instance.
+     */
+    static create(config: HostClientConfig): StandaloneHostClient;
+    /**
+     * Check if the current environment is standalone.
+     * Returns true when not in ChatGPT or MCP Apps.
+     */
+    static detect(): boolean;
+    getState(): HostClientState;
+    /**
+     * Get host context - returns null for standalone mode.
+     */
+    getHostContext(): HostContext | null;
+    subscribe(listener: StateListener): () => void;
+    /**
+     * Connect in standalone mode.
+     * Simply marks the client as ready since there's no host to connect to.
+     */
+    connect(): void;
+    /**
+     * Disconnect in standalone mode.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool - not available in standalone mode.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, _args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Request a display mode - returns the requested mode since there's no host.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Log a message to the console.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof HostClientEvents>(event: K, handler: HostClientEvents[K]): () => void;
+    /**
+     * Experimental APIs for non-standard features.
+     * All methods are logged for development/debugging purposes.
+     */
+    get exp(): ExpHostApi;
+    /**
+     * Update internal state and notify listeners.
+     */
+    private setState;
+}
+
+/**
+ * Environment-Aware Default Styles
+ *
+ * This module provides default CSS variable values for MCP Apps and ChatGPT Apps.
+ * Import `initDefaultStyles` early in your app entry point to prevent flash of unstyled content.
+ *
+ * The MCP Apps spec defines CSS variable names (e.g., --color-background-primary).
+ * This module provides environment-specific VALUES for those variables as sensible
+ * defaults until the host injects its own values.
+ *
+ * Flow:
+ * 1. Detect environment (ChatGPT, MCP Apps, or Standalone)
+ * 2. Detect theme (light or dark)
+ * 3. Inject defaults immediately on document.documentElement
+ * 4. When host connects, host variables override these defaults
+ *
+ * IMPORTANT: MCP Apps defaults match Creature's actual values exactly.
+ * The observer only runs for ChatGPT (MCP Apps hosts handle theme changes themselves).
+ */
+
+/**
+ * Theme mode for styling.
+ */
+type Theme = "light" | "dark";
+/**
+ * Options for initializing styles.
+ */
+interface InitStylesOptions {
+    /** Whether to set up a MutationObserver for dynamic theme changes. Default: true for ChatGPT only */
+    observeThemeChanges?: boolean;
+}
+/**
+ * MCP Apps / Creature default values - DARK mode.
+ * These values are extracted directly from Creature's globals.css.
+ * They MUST match exactly what Creature sends via hostContext.styles.variables.
+ */
+declare const MCP_APPS_DARK_DEFAULTS: Record<string, string>;
+/**
+ * MCP Apps / Creature default values - LIGHT mode.
+ * These values are extracted directly from Creature's globals.css.
+ */
+declare const MCP_APPS_LIGHT_DEFAULTS: Record<string, string>;
+/**
+ * Shared MCP Apps / Creature typography and layout tokens (same for light/dark).
+ * These values are extracted directly from Creature's globals.css.
+ */
+declare const MCP_APPS_SHARED_DEFAULTS: Record<string, string>;
+/**
+ * ChatGPT Apps default values - LIGHT mode.
+ * Ported from @openai/apps-sdk-ui design tokens.
+ */
+declare const CHATGPT_LIGHT_DEFAULTS: Record<string, string>;
+/**
+ * ChatGPT Apps default values - DARK mode.
+ */
+declare const CHATGPT_DARK_DEFAULTS: Record<string, string>;
+/**
+ * Shared ChatGPT typography and layout tokens (same for light/dark).
+ */
+declare const CHATGPT_SHARED_DEFAULTS: Record<string, string>;
+/**
+ * Get MCP Apps default styles for the specified theme.
+ * Returns CSS variable names with their default values.
+ * These values match exactly what Creature sends via hostContext.styles.variables.
+ *
+ * @param theme - The theme to get defaults for
+ * @returns Record of CSS variable names to their values
+ */
+declare const getMcpAppDefaultStyles: ({ theme }: {
+    theme: Theme;
+}) => Record<string, string>;
+/**
+ * Get ChatGPT Apps default styles for the specified theme.
+ * Returns CSS variable names with their values matching the @openai/apps-sdk-ui design tokens.
+ *
+ * @param theme - The theme to get defaults for
+ * @returns Record of CSS variable names to their values
+ */
+declare const getChatGptDefaultStyles: ({ theme }: {
+    theme: Theme;
+}) => Record<string, string>;
+/**
+ * Detect the current theme from the document.
+ * Checks data-theme attribute, dark class (Tailwind), and prefers-color-scheme.
+ *
+ * @returns The detected theme
+ */
+declare const detectTheme: () => Theme;
+/**
+ * Apply CSS variables to the document root.
+ *
+ * @param styles - Record of CSS variable names to their values
+ */
+declare const applyStyles: ({ styles }: {
+    styles: Record<string, string>;
+}) => void;
+/**
+ * Initialize default styles based on detected environment and theme.
+ * This should be called early in your app entry point to prevent FOUC.
+ *
+ * For MCP Apps (Creature): Applies defaults once. The host handles theme changes
+ * and sends new styles via hostContext, which override these defaults.
+ *
+ * For ChatGPT: Applies defaults and sets up an observer to handle theme changes,
+ * since ChatGPT may change theme before sending new hostContext.
+ *
+ * @param environment - The detected environment (from detectEnvironment)
+ * @param options - Configuration options
+ */
+declare const initDefaultStyles: ({ environment, options, }: {
+    environment: Environment;
+    options?: InitStylesOptions;
+}) => void;
+
+/**
+ * Create a WebSocket client with automatic reconnection.
+ *
+ * @param url - WebSocket server URL
+ * @param config - Client configuration
+ * @returns WebSocket client instance
+ */
+declare function createWebSocket<TSend = unknown, TReceive = unknown>(url: string, config?: WebSocketClientConfig<TReceive>): WebSocketClient<TSend, TReceive>;
+
+/**
+ * Core Host Client Module
+ *
+ * Provides the unified host client factory and all related types.
+ * This is the main entry point for client-side SDK usage.
+ */
+
+/**
+ * Detect the current host environment.
+ *
+ * Used to auto-select the appropriate host client implementation:
+ * - "chatgpt": Running inside ChatGPT's widget system
+ * - "mcp-apps": Running inside an MCP Apps host (iframe with parent)
+ * - "standalone": Running outside any host environment
+ *
+ * @returns The detected environment
+ */
+declare const detectEnvironment: () => Environment;
+/**
+ * Create a host client for the detected environment.
+ *
+ * Automatically selects the appropriate client based on runtime detection:
+ * - ChatGPT Web: Uses ChatGptWebHostClient (detects window.openai)
+ * - MCP Apps: Uses CreatureDesktopHostClient (detects iframe with parent)
+ * - Standalone: Uses StandaloneHostClient for development/testing
+ *
+ * Note: For MCP Apps environments, this returns CreatureDesktopHostClient by default.
+ * Use createHostAsync() for proper host detection via userAgent after connection.
+ *
+ * @param config - Configuration for the host client
+ * @returns The appropriate host client for the environment
+ *
+ * @example
+ * ```typescript
+ * const host = createHost({ name: "my-app", version: "1.0.0" });
+ * host.connect();
+ *
+ * // Call tools
+ * const result = await host.callTool("get_todos", {});
+ *
+ * // Use experimental features (graceful degradation)
+ * host.exp.setTitle("My Widget");
+ * ```
+ */
+declare const createHost: (config: HostClientConfig) => UnifiedHostClient;
+/**
+ * Create a host client asynchronously with proper host detection.
+ *
+ * Unlike createHost(), this function:
+ * 1. Connects to the host
+ * 2. Detects the specific host type via userAgent
+ * 3. Returns the appropriate client (CreatureDesktop, ClaudeDesktop, etc.)
+ *
+ * For MCP Apps environments, this performs deferred detection by connecting
+ * first, then checking the userAgent to select the correct client.
+ *
+ * @param config - Configuration for the host client
+ * @returns Promise that resolves to the configured host client after connection
+ *
+ * @example
+ * ```typescript
+ * const host = await createHostAsync({ name: "my-app", version: "1.0.0" });
+ * // host is now ready to use with correct host-specific behavior
+ * ```
+ */
+declare const createHostAsync: (config: HostClientConfig) => Promise<UnifiedHostClient>;
+
+export { CHATGPT_DARK_DEFAULTS, CHATGPT_LIGHT_DEFAULTS, CHATGPT_SHARED_DEFAULTS, ChatGptWebHostClient, ClaudeDesktopHostClient, type ContentBlock, CreatureDesktopHostClient, type DisplayMode, type Environment, type ExpHostApi, type HostClientConfig, type HostClientEvents, type HostClientState, type HostContext, type ImageContentBlock, type InitStylesOptions, type LogLevel, MCP_APPS_DARK_DEFAULTS, MCP_APPS_LIGHT_DEFAULTS, MCP_APPS_SHARED_DEFAULTS, type OpenContext, StandaloneHostClient, type StateListener, type StructuredWidgetState, type TextContentBlock, type Theme, type ToolResult, type UnifiedHostClient, type WebSocketClient, type WebSocketClientConfig, type WebSocketStatus, type WidgetState, applyStyles, createHost, createHostAsync, createWebSocket, detectEnvironment, detectTheme, getChatGptDefaultStyles, getMcpAppDefaultStyles, initDefaultStyles };