@frontmcp/ui 0.5.1 → 0.6.0

package/src/runtime/types.d.ts

@@ -1,414 +0,0 @@
-/**
- * Runtime Types for Tool UI Templates
- *
- * Types for the MCP Bridge runtime that adapts to different host environments
- * (OpenAI Apps SDK, ext-apps, Claude, etc.).
- *
- * Note: UI-related types are defined locally to avoid circular dependency with @frontmcp/sdk.
- * These are kept in sync with the SDK's tool-ui.metadata.ts definitions.
- */
-/**
- * Content Security Policy for UI templates rendered in sandboxed iframes.
- * Based on OpenAI Apps SDK and ext-apps (SEP-1865) specifications.
- */
-export interface UIContentSecurityPolicy {
-    /**
-     * Origins allowed for fetch/XHR/WebSocket connections.
-     * Maps to CSP `connect-src` directive.
-     */
-    connectDomains?: string[];
-    /**
-     * Origins allowed for images, scripts, fonts, and styles.
-     * Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives.
-     */
-    resourceDomains?: string[];
-}
-/**
- * Helper functions available in template context.
- */
-export interface TemplateHelpers {
-    /** Escape HTML special characters to prevent XSS. */
-    escapeHtml: (str: string) => string;
-    /** Format a date for display. */
-    formatDate: (date: Date | string, format?: string) => string;
-    /** Format a number as currency. */
-    formatCurrency: (amount: number, currency?: string) => string;
-    /** Generate a unique ID for DOM elements. */
-    uniqueId: (prefix?: string) => string;
-    /** Safely embed JSON data in HTML (escapes script-breaking characters). */
-    jsonEmbed: (data: unknown) => string;
-}
-/**
- * Context passed to template builder functions.
- */
-export interface TemplateContext<In, Out> {
-    /** The input arguments passed to the tool. */
-    input: In;
-    /** The raw output returned by the tool's execute method. */
-    output: Out;
-    /** The structured content parsed from the output (if outputSchema was provided). */
-    structuredContent?: unknown;
-    /** Helper functions for template rendering. */
-    helpers: TemplateHelpers;
-}
-/**
- * Template builder function type.
- */
-export type TemplateBuilderFn<In, Out> = (ctx: TemplateContext<In, Out>) => string;
-/**
- * Widget serving mode determines how the widget HTML is delivered to the client.
- */
-export type WidgetServingMode = 'inline' | 'static' | 'hybrid' | 'direct-url' | 'custom-url';
-/**
- * Template type - can be:
- * - HTML string
- * - Template builder function: (ctx) => string
- * - React component function (imported from .tsx file)
- * - JSX string (transpiled at runtime)
- * - MDX string (Markdown + JSX, transpiled at runtime)
- *
- * The renderer is auto-detected based on template type.
- */
-export type ToolUITemplate<In = unknown, Out = unknown> = TemplateBuilderFn<In, Out> | string | ((props: any) => any);
-/**
- * UI template configuration for tools.
- */
-export interface ToolUIConfig<In = unknown, Out = unknown> {
-    /**
-     * Template for rendering the tool UI.
-     *
-     * Supports multiple formats (auto-detected):
-     * - HTML string: `"<div>Hello</div>"`
-     * - Template builder: `(ctx) => \`<div>\${ctx.output.name}</div>\``
-     * - React component: `import { MyWidget } from './widget.tsx'`
-     * - JSX string: `"function Widget({ output }) { return <div>{output.name}</div>; }"`
-     * - MDX string: `"# Title\n<Card name={output.name} />"`
-     *
-     * @example HTML template builder
-     * ```typescript
-     * template: (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.name)}</div>`
-     * ```
-     *
-     * @example React component
-     * ```typescript
-     * import { MyWidget } from './my-widget.tsx';
-     * template: MyWidget
-     * ```
-     *
-     * @example MDX content
-     * ```typescript
-     * template: `
-     * # User Profile
-     * <UserCard name={output.name} />
-     * `
-     * ```
-     */
-    template: ToolUITemplate<In, Out>;
-    /** Content Security Policy for the sandboxed widget. */
-    csp?: UIContentSecurityPolicy;
-    /** Whether the widget can invoke tools via the MCP bridge. */
-    widgetAccessible?: boolean;
-    /** Preferred display mode for the widget. */
-    displayMode?: 'inline' | 'fullscreen' | 'pip';
-    /** Human-readable description shown to users about what the widget does. */
-    widgetDescription?: string;
-    /** Status messages shown during tool invocation. */
-    invocationStatus?: {
-        invoking?: string;
-        invoked?: string;
-    };
-    /** How the widget HTML should be served to the client. */
-    servingMode?: WidgetServingMode;
-    /** Custom URL for widget serving when `servingMode: 'custom-url'`. */
-    customWidgetUrl?: string;
-    /** Path for direct URL serving when `servingMode: 'direct-url'`. */
-    directPath?: string;
-    /**
-     * Enable client-side hydration for React/MDX components.
-     * When true, the rendered HTML includes hydration markers and
-     * the React runtime is included for client-side interactivity.
-     *
-     * @default false
-     */
-    hydrate?: boolean;
-    /**
-     * Custom React components to make available in MDX templates.
-     * These components can be used directly in MDX content.
-     *
-     * @example
-     * ```typescript
-     * import { Card, Badge } from './components';
-     *
-     * mdxComponents: { Card, Badge }
-     * // Now in MDX: # Title\n<Card><Badge>New</Badge></Card>
-     * ```
-     */
-    mdxComponents?: Record<string, any>;
-    /**
-     * Custom wrapper function for the rendered content.
-     * Allows per-tool customization of the HTML document structure.
-     *
-     * @example
-     * ```typescript
-     * wrapper: (content, ctx) => `
-     *   <div class="custom-wrapper">
-     *     ${content}
-     *   </div>
-     * `
-     * ```
-     */
-    wrapper?: (content: string, ctx: TemplateContext<In, Out>) => string;
-}
-type UICSPType = UIContentSecurityPolicy;
-/**
- * Provider identifier for the host environment
- */
-export type ProviderType = 'openai' | 'ext-apps' | 'claude' | 'unknown';
-/**
- * Display mode for the widget
- */
-export type DisplayMode = 'inline' | 'fullscreen' | 'pip' | 'carousel';
-/**
- * Theme mode
- */
-export type ThemeMode = 'light' | 'dark' | 'system';
-/**
- * Host context provided by the environment
- */
-export interface HostContext {
-    /** Current theme mode */
-    theme: ThemeMode;
-    /** Current display mode */
-    displayMode: DisplayMode;
-    /** Available display modes */
-    availableDisplayModes?: DisplayMode[];
-    /** Viewport dimensions */
-    viewport?: {
-        width: number;
-        height: number;
-        maxHeight?: number;
-        maxWidth?: number;
-    };
-    /** BCP 47 locale code */
-    locale?: string;
-    /** IANA timezone */
-    timeZone?: string;
-    /** User agent string */
-    userAgent?: string;
-    /** Platform type */
-    platform?: 'web' | 'desktop' | 'mobile';
-    /** Device capabilities */
-    deviceCapabilities?: {
-        touch?: boolean;
-        hover?: boolean;
-    };
-    /** Safe area insets (for mobile) */
-    safeAreaInsets?: {
-        top: number;
-        right: number;
-        bottom: number;
-        left: number;
-    };
-}
-/**
- * MCP Bridge interface available as window.mcpBridge
- */
-export interface MCPBridge {
-    /**
-     * Detected provider type
-     */
-    readonly provider: ProviderType;
-    /**
-     * Call a tool on the MCP server
-     */
-    callTool(name: string, params: Record<string, unknown>): Promise<unknown>;
-    /**
-     * Send a message to the chat interface
-     */
-    sendMessage(content: string): Promise<void>;
-    /**
-     * Open an external link
-     */
-    openLink(url: string): Promise<void>;
-    /**
-     * Get the tool input arguments
-     */
-    readonly toolInput: Record<string, unknown>;
-    /**
-     * Get the tool output/result
-     */
-    readonly toolOutput: unknown;
-    /**
-     * Get the structured content from the tool result
-     */
-    readonly structuredContent: unknown;
-    /**
-     * Get the current widget state
-     */
-    readonly widgetState: Record<string, unknown>;
-    /**
-     * Set the widget state (persisted)
-     */
-    setWidgetState(state: Record<string, unknown>): void;
-    /**
-     * Get the host context (theme, display mode, etc.)
-     */
-    readonly context: HostContext;
-    /**
-     * Subscribe to host context changes
-     */
-    onContextChange(callback: (context: Partial<HostContext>) => void): () => void;
-    /**
-     * Subscribe to tool result updates
-     */
-    onToolResult(callback: (result: unknown) => void): () => void;
-}
-/**
- * Options for wrapping tool UI templates
- */
-export interface WrapToolUIOptions {
-    /** HTML content of the template */
-    content: string;
-    /** Tool name */
-    toolName: string;
-    /** Tool input arguments */
-    input?: Record<string, unknown>;
-    /** Tool output */
-    output?: unknown;
-    /** Structured content from parsing */
-    structuredContent?: unknown;
-    /** Content Security Policy */
-    csp?: UICSPType;
-    /** Whether widget can call tools */
-    widgetAccessible?: boolean;
-    /** Title for the page */
-    title?: string;
-}
-declare global {
-    interface Window {
-        mcpBridge?: MCPBridge | MCPBridgeExtended;
-        openai?: OpenAIRuntime;
-        claude?: unknown;
-        __mcpPlatform?: string;
-        __mcpToolName?: string;
-        __mcpToolInput?: Record<string, unknown>;
-        __mcpToolOutput?: unknown;
-        __mcpStructuredContent?: unknown;
-        __mcpToolResponseMetadata?: Record<string, unknown>;
-        __mcpHostContext?: HostContext;
-        __mcpWidgetToken?: string;
-    }
-}
-/**
- * User agent information from OpenAI
- */
-export interface OpenAIUserAgent {
-    /** Device type */
-    type?: 'web' | 'mobile' | 'desktop';
-    /** Whether device supports hover interactions */
-    hover?: boolean;
-    /** Whether device supports touch interactions */
-    touch?: boolean;
-}
-/**
- * Safe area insets (for mobile devices with notches, etc.)
- */
-export interface SafeAreaInsets {
-    top: number;
-    bottom: number;
-    left: number;
-    right: number;
-}
-/**
- * Full OpenAI runtime interface matching window.openai API
- * @see https://developers.openai.com/apps-sdk/build/chatgpt-ui
- */
-export interface OpenAIRuntime {
-    /** Display theme */
-    theme?: 'light' | 'dark';
-    /** User agent information */
-    userAgent?: OpenAIUserAgent;
-    /** BCP 47 locale string */
-    locale?: string;
-    /** Maximum height available for widget (pixels) */
-    maxHeight?: number;
-    /** Current display mode */
-    displayMode?: DisplayMode;
-    /** Safe area insets for mobile devices */
-    safeArea?: SafeAreaInsets;
-    /** Tool input arguments passed to the tool */
-    toolInput?: Record<string, unknown>;
-    /** Structured tool output/result */
-    toolOutput?: unknown;
-    /** Additional metadata from tool response */
-    toolResponseMetadata?: Record<string, unknown>;
-    /** Persisted widget state */
-    widgetState?: Record<string, unknown>;
-    /**
-     * Invoke an MCP tool
-     * @param name - Tool name
-     * @param args - Tool arguments
-     * @returns Promise resolving to tool result
-     */
-    callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;
-    /**
-     * Request a display mode change
-     * @param options - Display mode options
-     */
-    requestDisplayMode?: (options: {
-        mode: DisplayMode;
-    }) => Promise<void>;
-    /**
-     * Request to close the widget
-     */
-    requestClose?: () => Promise<void>;
-    /**
-     * Open an external URL
-     * @param options - URL options
-     */
-    openExternal?: (options: {
-        href: string;
-    }) => Promise<void>;
-    /**
-     * Send a follow-up message to the chat
-     * @param options - Message options
-     */
-    sendFollowUpMessage?: (options: {
-        prompt: string;
-    }) => Promise<void>;
-    /**
-     * Set widget state (persisted across sessions)
-     * @param state - State object to persist
-     */
-    setWidgetState?: (state: Record<string, unknown>) => void;
-}
-/**
- * Extended MCP Bridge interface with full OpenAI API compatibility
- */
-export interface MCPBridgeExtended extends MCPBridge {
-    /** Display theme (proxied from window.openai or polyfilled) */
-    readonly theme: 'light' | 'dark';
-    /** User agent info */
-    readonly userAgent: OpenAIUserAgent;
-    /** BCP 47 locale */
-    readonly locale: string;
-    /** Max height for widget */
-    readonly maxHeight: number | undefined;
-    /** Current display mode */
-    readonly displayMode: DisplayMode;
-    /** Safe area insets */
-    readonly safeArea: SafeAreaInsets;
-    /** Tool response metadata */
-    readonly toolResponseMetadata: Record<string, unknown>;
-    /**
-     * Request display mode change
-     */
-    requestDisplayMode(options: {
-        mode: DisplayMode;
-    }): Promise<void>;
-    /**
-     * Request to close the widget
-     */
-    requestClose(): Promise<void>;
-}
-export {};

package/src/runtime/types.js

@@ -1,12 +0,0 @@
-"use strict";
-/**
- * Runtime Types for Tool UI Templates
- *
- * Types for the MCP Bridge runtime that adapts to different host environments
- * (OpenAI Apps SDK, ext-apps, Claude, etc.).
- *
- * Note: UI-related types are defined locally to avoid circular dependency with @frontmcp/sdk.
- * These are kept in sync with the SDK's tool-ui.metadata.ts definitions.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/src/runtime/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/runtime/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * Runtime Types for Tool UI Templates\n *\n * Types for the MCP Bridge runtime that adapts to different host environments\n * (OpenAI Apps SDK, ext-apps, Claude, etc.).\n *\n * Note: UI-related types are defined locally to avoid circular dependency with @frontmcp/sdk.\n * These are kept in sync with the SDK's tool-ui.metadata.ts definitions.\n */\n\n// ============================================\n// Content Security Policy (mirrors SDK types)\n// ============================================\n\n/**\n * Content Security Policy for UI templates rendered in sandboxed iframes.\n * Based on OpenAI Apps SDK and ext-apps (SEP-1865) specifications.\n */\nexport interface UIContentSecurityPolicy {\n  /**\n   * Origins allowed for fetch/XHR/WebSocket connections.\n   * Maps to CSP `connect-src` directive.\n   */\n  connectDomains?: string[];\n\n  /**\n   * Origins allowed for images, scripts, fonts, and styles.\n   * Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives.\n   */\n  resourceDomains?: string[];\n}\n\n// ============================================\n// Template Context & Helpers (mirrors SDK types)\n// ============================================\n\n/**\n * Helper functions available in template context.\n */\nexport interface TemplateHelpers {\n  /** Escape HTML special characters to prevent XSS. */\n  escapeHtml: (str: string) => string;\n\n  /** Format a date for display. */\n  formatDate: (date: Date | string, format?: string) => string;\n\n  /** Format a number as currency. */\n  formatCurrency: (amount: number, currency?: string) => string;\n\n  /** Generate a unique ID for DOM elements. */\n  uniqueId: (prefix?: string) => string;\n\n  /** Safely embed JSON data in HTML (escapes script-breaking characters). */\n  jsonEmbed: (data: unknown) => string;\n}\n\n/**\n * Context passed to template builder functions.\n */\nexport interface TemplateContext<In, Out> {\n  /** The input arguments passed to the tool. */\n  input: In;\n\n  /** The raw output returned by the tool's execute method. */\n  output: Out;\n\n  /** The structured content parsed from the output (if outputSchema was provided). */\n  structuredContent?: unknown;\n\n  /** Helper functions for template rendering. */\n  helpers: TemplateHelpers;\n}\n\n/**\n * Template builder function type.\n */\nexport type TemplateBuilderFn<In, Out> = (ctx: TemplateContext<In, Out>) => string;\n\n/**\n * Widget serving mode determines how the widget HTML is delivered to the client.\n */\nexport type WidgetServingMode =\n  | 'inline' // HTML embedded directly in tool response _meta\n  | 'static' // Pre-compiled at startup, via ui:// resource URI (MCP resources/read)\n  | 'hybrid' // Shell (React + renderer) cached, component + data in response\n  | 'direct-url' // HTTP endpoint on MCP server\n  | 'custom-url'; // Custom URL (CDN or external hosting)\n\n/**\n * Template type - can be:\n * - HTML string\n * - Template builder function: (ctx) => string\n * - React component function (imported from .tsx file)\n * - JSX string (transpiled at runtime)\n * - MDX string (Markdown + JSX, transpiled at runtime)\n *\n * The renderer is auto-detected based on template type.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type ToolUITemplate<In = unknown, Out = unknown> = TemplateBuilderFn<In, Out> | string | ((props: any) => any);\n\n/**\n * UI template configuration for tools.\n */\nexport interface ToolUIConfig<In = unknown, Out = unknown> {\n  /**\n   * Template for rendering the tool UI.\n   *\n   * Supports multiple formats (auto-detected):\n   * - HTML string: `\"<div>Hello</div>\"`\n   * - Template builder: `(ctx) => \\`<div>\\${ctx.output.name}</div>\\``\n   * - React component: `import { MyWidget } from './widget.tsx'`\n   * - JSX string: `\"function Widget({ output }) { return <div>{output.name}</div>; }\"`\n   * - MDX string: `\"# Title\\n<Card name={output.name} />\"`\n   *\n   * @example HTML template builder\n   * ```typescript\n   * template: (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.name)}</div>`\n   * ```\n   *\n   * @example React component\n   * ```typescript\n   * import { MyWidget } from './my-widget.tsx';\n   * template: MyWidget\n   * ```\n   *\n   * @example MDX content\n   * ```typescript\n   * template: `\n   * # User Profile\n   * <UserCard name={output.name} />\n   * `\n   * ```\n   */\n  template: ToolUITemplate<In, Out>;\n\n  /** Content Security Policy for the sandboxed widget. */\n  csp?: UIContentSecurityPolicy;\n\n  /** Whether the widget can invoke tools via the MCP bridge. */\n  widgetAccessible?: boolean;\n\n  /** Preferred display mode for the widget. */\n  displayMode?: 'inline' | 'fullscreen' | 'pip';\n\n  /** Human-readable description shown to users about what the widget does. */\n  widgetDescription?: string;\n\n  /** Status messages shown during tool invocation. */\n  invocationStatus?: {\n    invoking?: string;\n    invoked?: string;\n  };\n\n  /** How the widget HTML should be served to the client. */\n  servingMode?: WidgetServingMode;\n\n  /** Custom URL for widget serving when `servingMode: 'custom-url'`. */\n  customWidgetUrl?: string;\n\n  /** Path for direct URL serving when `servingMode: 'direct-url'`. */\n  directPath?: string;\n\n  /**\n   * Enable client-side hydration for React/MDX components.\n   * When true, the rendered HTML includes hydration markers and\n   * the React runtime is included for client-side interactivity.\n   *\n   * @default false\n   */\n  hydrate?: boolean;\n\n  /**\n   * Custom React components to make available in MDX templates.\n   * These components can be used directly in MDX content.\n   *\n   * @example\n   * ```typescript\n   * import { Card, Badge } from './components';\n   *\n   * mdxComponents: { Card, Badge }\n   * // Now in MDX: # Title\\n<Card><Badge>New</Badge></Card>\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  mdxComponents?: Record<string, any>;\n\n  /**\n   * Custom wrapper function for the rendered content.\n   * Allows per-tool customization of the HTML document structure.\n   *\n   * @example\n   * ```typescript\n   * wrapper: (content, ctx) => `\n   *   <div class=\"custom-wrapper\">\n   *     ${content}\n   *   </div>\n   * `\n   * ```\n   */\n  wrapper?: (content: string, ctx: TemplateContext<In, Out>) => string;\n}\n\n// Local alias for use within this file\ntype UICSPType = UIContentSecurityPolicy;\n\n/**\n * Provider identifier for the host environment\n */\nexport type ProviderType = 'openai' | 'ext-apps' | 'claude' | 'unknown';\n\n/**\n * Display mode for the widget\n */\nexport type DisplayMode = 'inline' | 'fullscreen' | 'pip' | 'carousel';\n\n/**\n * Theme mode\n */\nexport type ThemeMode = 'light' | 'dark' | 'system';\n\n/**\n * Host context provided by the environment\n */\nexport interface HostContext {\n  /** Current theme mode */\n  theme: ThemeMode;\n\n  /** Current display mode */\n  displayMode: DisplayMode;\n\n  /** Available display modes */\n  availableDisplayModes?: DisplayMode[];\n\n  /** Viewport dimensions */\n  viewport?: {\n    width: number;\n    height: number;\n    maxHeight?: number;\n    maxWidth?: number;\n  };\n\n  /** BCP 47 locale code */\n  locale?: string;\n\n  /** IANA timezone */\n  timeZone?: string;\n\n  /** User agent string */\n  userAgent?: string;\n\n  /** Platform type */\n  platform?: 'web' | 'desktop' | 'mobile';\n\n  /** Device capabilities */\n  deviceCapabilities?: {\n    touch?: boolean;\n    hover?: boolean;\n  };\n\n  /** Safe area insets (for mobile) */\n  safeAreaInsets?: {\n    top: number;\n    right: number;\n    bottom: number;\n    left: number;\n  };\n}\n\n/**\n * MCP Bridge interface available as window.mcpBridge\n */\nexport interface MCPBridge {\n  /**\n   * Detected provider type\n   */\n  readonly provider: ProviderType;\n\n  /**\n   * Call a tool on the MCP server\n   */\n  callTool(name: string, params: Record<string, unknown>): Promise<unknown>;\n\n  /**\n   * Send a message to the chat interface\n   */\n  sendMessage(content: string): Promise<void>;\n\n  /**\n   * Open an external link\n   */\n  openLink(url: string): Promise<void>;\n\n  /**\n   * Get the tool input arguments\n   */\n  readonly toolInput: Record<string, unknown>;\n\n  /**\n   * Get the tool output/result\n   */\n  readonly toolOutput: unknown;\n\n  /**\n   * Get the structured content from the tool result\n   */\n  readonly structuredContent: unknown;\n\n  /**\n   * Get the current widget state\n   */\n  readonly widgetState: Record<string, unknown>;\n\n  /**\n   * Set the widget state (persisted)\n   */\n  setWidgetState(state: Record<string, unknown>): void;\n\n  /**\n   * Get the host context (theme, display mode, etc.)\n   */\n  readonly context: HostContext;\n\n  /**\n   * Subscribe to host context changes\n   */\n  onContextChange(callback: (context: Partial<HostContext>) => void): () => void;\n\n  /**\n   * Subscribe to tool result updates\n   */\n  onToolResult(callback: (result: unknown) => void): () => void;\n}\n\n/**\n * Options for wrapping tool UI templates\n */\nexport interface WrapToolUIOptions {\n  /** HTML content of the template */\n  content: string;\n\n  /** Tool name */\n  toolName: string;\n\n  /** Tool input arguments */\n  input?: Record<string, unknown>;\n\n  /** Tool output */\n  output?: unknown;\n\n  /** Structured content from parsing */\n  structuredContent?: unknown;\n\n  /** Content Security Policy */\n  csp?: UICSPType;\n\n  /** Whether widget can call tools */\n  widgetAccessible?: boolean;\n\n  /** Title for the page */\n  title?: string;\n}\n\n// Extend Window interface\ndeclare global {\n  interface Window {\n    mcpBridge?: MCPBridge | MCPBridgeExtended;\n    openai?: OpenAIRuntime;\n    claude?: unknown; // Claude's runtime interface (if any)\n    __mcpPlatform?: string; // Platform identifier injected by server\n    __mcpToolName?: string;\n    __mcpToolInput?: Record<string, unknown>;\n    __mcpToolOutput?: unknown;\n    __mcpStructuredContent?: unknown;\n    __mcpToolResponseMetadata?: Record<string, unknown>;\n    __mcpHostContext?: HostContext;\n    __mcpWidgetToken?: string; // Widget access token\n  }\n}\n\n/**\n * User agent information from OpenAI\n */\nexport interface OpenAIUserAgent {\n  /** Device type */\n  type?: 'web' | 'mobile' | 'desktop';\n  /** Whether device supports hover interactions */\n  hover?: boolean;\n  /** Whether device supports touch interactions */\n  touch?: boolean;\n}\n\n/**\n * Safe area insets (for mobile devices with notches, etc.)\n */\nexport interface SafeAreaInsets {\n  top: number;\n  bottom: number;\n  left: number;\n  right: number;\n}\n\n/**\n * Full OpenAI runtime interface matching window.openai API\n * @see https://developers.openai.com/apps-sdk/build/chatgpt-ui\n */\nexport interface OpenAIRuntime {\n  // ==================== Properties ====================\n\n  /** Display theme */\n  theme?: 'light' | 'dark';\n\n  /** User agent information */\n  userAgent?: OpenAIUserAgent;\n\n  /** BCP 47 locale string */\n  locale?: string;\n\n  /** Maximum height available for widget (pixels) */\n  maxHeight?: number;\n\n  /** Current display mode */\n  displayMode?: DisplayMode;\n\n  /** Safe area insets for mobile devices */\n  safeArea?: SafeAreaInsets;\n\n  /** Tool input arguments passed to the tool */\n  toolInput?: Record<string, unknown>;\n\n  /** Structured tool output/result */\n  toolOutput?: unknown;\n\n  /** Additional metadata from tool response */\n  toolResponseMetadata?: Record<string, unknown>;\n\n  /** Persisted widget state */\n  widgetState?: Record<string, unknown>;\n\n  // ==================== Methods ====================\n\n  /**\n   * Invoke an MCP tool\n   * @param name - Tool name\n   * @param args - Tool arguments\n   * @returns Promise resolving to tool result\n   */\n  callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;\n\n  /**\n   * Request a display mode change\n   * @param options - Display mode options\n   */\n  requestDisplayMode?: (options: { mode: DisplayMode }) => Promise<void>;\n\n  /**\n   * Request to close the widget\n   */\n  requestClose?: () => Promise<void>;\n\n  /**\n   * Open an external URL\n   * @param options - URL options\n   */\n  openExternal?: (options: { href: string }) => Promise<void>;\n\n  /**\n   * Send a follow-up message to the chat\n   * @param options - Message options\n   */\n  sendFollowUpMessage?: (options: { prompt: string }) => Promise<void>;\n\n  /**\n   * Set widget state (persisted across sessions)\n   * @param state - State object to persist\n   */\n  setWidgetState?: (state: Record<string, unknown>) => void;\n}\n\n/**\n * Extended MCP Bridge interface with full OpenAI API compatibility\n */\nexport interface MCPBridgeExtended extends MCPBridge {\n  // ==================== OpenAI-Compatible Properties ====================\n\n  /** Display theme (proxied from window.openai or polyfilled) */\n  readonly theme: 'light' | 'dark';\n\n  /** User agent info */\n  readonly userAgent: OpenAIUserAgent;\n\n  /** BCP 47 locale */\n  readonly locale: string;\n\n  /** Max height for widget */\n  readonly maxHeight: number | undefined;\n\n  /** Current display mode */\n  readonly displayMode: DisplayMode;\n\n  /** Safe area insets */\n  readonly safeArea: SafeAreaInsets;\n\n  /** Tool response metadata */\n  readonly toolResponseMetadata: Record<string, unknown>;\n\n  // ==================== OpenAI-Compatible Methods ====================\n\n  /**\n   * Request display mode change\n   */\n  requestDisplayMode(options: { mode: DisplayMode }): Promise<void>;\n\n  /**\n   * Request to close the widget\n   */\n  requestClose(): Promise<void>;\n}\n"]}