@frontmcp/ui 0.5.1 → 0.6.1

package/bridge/core/bridge-factory.d.ts

@@ -0,0 +1,199 @@
+/**
+ * FrontMcpBridge Factory
+ *
+ * Main entry point for the unified multi-platform adapter system.
+ * Provides automatic platform detection and a consistent API across
+ * OpenAI, Claude, ext-apps, Gemini, and custom adapters.
+ *
+ * @packageDocumentation
+ */
+import type { PlatformAdapter, AdapterCapabilities, BridgeConfig, DisplayMode, HostContext, FrontMcpBridgeInterface } from '../types';
+import { AdapterRegistry } from './adapter-registry';
+/**
+ * FrontMcpBridge - Unified multi-platform bridge for MCP tool widgets.
+ *
+ * @example Basic usage with auto-detection
+ * ```typescript
+ * const bridge = new FrontMcpBridge();
+ * await bridge.initialize();
+ *
+ * const theme = bridge.getTheme();
+ * const toolInput = bridge.getToolInput();
+ * ```
+ *
+ * @example Force specific adapter
+ * ```typescript
+ * const bridge = new FrontMcpBridge({
+ *   forceAdapter: 'openai',
+ *   debug: true,
+ * });
+ * await bridge.initialize();
+ * ```
+ *
+ * @example With custom registry
+ * ```typescript
+ * const registry = new AdapterRegistry();
+ * registry.register('custom', createCustomAdapter);
+ *
+ * const bridge = new FrontMcpBridge({ forceAdapter: 'custom' }, registry);
+ * await bridge.initialize();
+ * ```
+ */
+export declare class FrontMcpBridge implements FrontMcpBridgeInterface {
+    private _config;
+    private _registry;
+    private _adapter;
+    private _initialized;
+    private _initPromise;
+    /**
+     * Create a new FrontMcpBridge instance.
+     * @param config - Bridge configuration
+     * @param registry - Optional custom adapter registry (uses default if not provided)
+     */
+    constructor(config?: BridgeConfig, registry?: AdapterRegistry);
+    /**
+     * Whether the bridge has been initialized.
+     */
+    get initialized(): boolean;
+    /**
+     * Current adapter ID, or undefined if not initialized.
+     */
+    get adapterId(): string | undefined;
+    /**
+     * Current adapter capabilities, or undefined if not initialized.
+     */
+    get capabilities(): AdapterCapabilities | undefined;
+    /**
+     * Initialize the bridge.
+     * Auto-detects the best adapter for the current platform unless
+     * `forceAdapter` is specified in the config.
+     *
+     * @throws Error if no suitable adapter is found
+     */
+    initialize(): Promise<void>;
+    /**
+     * Internal initialization logic.
+     */
+    private _doInitialize;
+    /**
+     * Dispose the bridge and release resources.
+     */
+    dispose(): void;
+    /**
+     * Get the active adapter instance.
+     */
+    getAdapter(): PlatformAdapter | undefined;
+    /**
+     * Check if a specific capability is available.
+     * @param cap - Capability key to check
+     */
+    hasCapability(cap: keyof AdapterCapabilities): boolean;
+    /**
+     * Get current theme.
+     */
+    getTheme(): 'light' | 'dark';
+    /**
+     * Get current display mode.
+     */
+    getDisplayMode(): DisplayMode;
+    /**
+     * Get tool input arguments.
+     */
+    getToolInput(): Record<string, unknown>;
+    /**
+     * Get tool output/result.
+     */
+    getToolOutput(): unknown;
+    /**
+     * Get structured content (parsed output).
+     */
+    getStructuredContent(): unknown;
+    /**
+     * Get persisted widget state.
+     */
+    getWidgetState(): Record<string, unknown>;
+    /**
+     * Get full host context.
+     */
+    getHostContext(): HostContext;
+    /**
+     * Call a tool on the MCP server.
+     * @param name - Tool name
+     * @param args - Tool arguments
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Send a follow-up message to the conversation.
+     * @param content - Message content
+     */
+    sendMessage(content: string): Promise<void>;
+    /**
+     * Open an external link.
+     * @param url - URL to open
+     */
+    openLink(url: string): Promise<void>;
+    /**
+     * Request a display mode change.
+     * @param mode - Desired display mode
+     */
+    requestDisplayMode(mode: DisplayMode): Promise<void>;
+    /**
+     * Request widget close.
+     */
+    requestClose(): Promise<void>;
+    /**
+     * Set widget state (persisted across sessions).
+     * @param state - State object to persist
+     */
+    setWidgetState(state: Record<string, unknown>): void;
+    /**
+     * Subscribe to host context changes.
+     * @param callback - Called when context changes
+     * @returns Unsubscribe function
+     */
+    onContextChange(callback: (changes: Partial<HostContext>) => void): () => void;
+    /**
+     * Subscribe to tool result updates.
+     * @param callback - Called when tool result is received
+     * @returns Unsubscribe function
+     */
+    onToolResult(callback: (result: unknown) => void): () => void;
+    /**
+     * Ensure the bridge is initialized before operations.
+     */
+    private _ensureInitialized;
+    /**
+     * Wrap a promise with a timeout.
+     */
+    private _withTimeout;
+    /**
+     * Emit a bridge event via CustomEvent.
+     */
+    private _emitEvent;
+    /**
+     * Log debug message if debugging is enabled.
+     */
+    private _log;
+}
+/**
+ * Create and initialize a bridge instance.
+ * Convenience function for one-liner initialization.
+ *
+ * @example
+ * ```typescript
+ * const bridge = await createBridge({ debug: true });
+ * const theme = bridge.getTheme();
+ * ```
+ */
+export declare function createBridge(config?: BridgeConfig, registry?: AdapterRegistry): Promise<FrontMcpBridge>;
+/**
+ * Get or create the global bridge instance.
+ * Initializes automatically on first call.
+ */
+export declare function getGlobalBridge(config?: BridgeConfig): Promise<FrontMcpBridge>;
+/**
+ * Reset the global bridge instance.
+ * Useful for testing or when switching configurations.
+ */
+export declare function resetGlobalBridge(): void;
+//# sourceMappingURL=bridge-factory.d.ts.map

package/bridge/core/bridge-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-factory.d.ts","sourceRoot":"","sources":["../../../src/bridge/core/bridge-factory.ts"],"names":[],"mappings":"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"}

package/bridge/core/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bridge Core Module
+ *
+ * Core infrastructure for the FrontMcpBridge system.
+ *
+ * @packageDocumentation
+ */
+export { AdapterRegistry, defaultRegistry, registerAdapter, getAdapter, detectAdapter } from './adapter-registry';
+export { FrontMcpBridge, createBridge, getGlobalBridge, resetGlobalBridge } from './bridge-factory';
+//# sourceMappingURL=index.d.ts.map

package/bridge/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/bridge/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAElH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/bridge/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * FrontMcpBridge - Unified Multi-Platform Adapter System
+ *
+ * Provides a consistent API for MCP tool widgets across AI platforms:
+ * - OpenAI ChatGPT (Apps SDK)
+ * - Anthropic Claude
+ * - ext-apps (SEP-1865 protocol)
+ * - Google Gemini
+ * - Generic fallback
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createBridge } from '@frontmcp/ui/bridge';
+ *
+ * const bridge = await createBridge();
+ * const theme = bridge.getTheme();
+ * const input = bridge.getToolInput();
+ * ```
+ *
+ * @example Custom adapter registration
+ * ```typescript
+ * import { AdapterRegistry, FrontMcpBridge, BaseAdapter } from '@frontmcp/ui/bridge';
+ *
+ * class MyAdapter extends BaseAdapter {
+ *   readonly id = 'my-adapter';
+ *   readonly name = 'My Custom Adapter';
+ *   readonly priority = 50;
+ *   canHandle() { return true; }
+ * }
+ *
+ * const registry = new AdapterRegistry();
+ * registry.register('my-adapter', () => new MyAdapter());
+ *
+ * const bridge = new FrontMcpBridge({ forceAdapter: 'my-adapter' }, registry);
+ * await bridge.initialize();
+ * ```
+ *
+ * @example Runtime script injection
+ * ```typescript
+ * import { generateBridgeIIFE, BRIDGE_SCRIPT_TAGS } from '@frontmcp/ui/bridge';
+ *
+ * // Use pre-generated universal script
+ * const html = `<!DOCTYPE html><html>${BRIDGE_SCRIPT_TAGS.universal}...</html>`;
+ *
+ * // Or generate custom
+ * const script = generateBridgeIIFE({ adapters: ['openai', 'generic'], debug: true });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { DisplayMode, UserAgentInfo, SafeAreaInsets, ViewportInfo, HostContext, AdapterCapabilities, PlatformAdapter, AdapterConfig, AdapterFactory, AdapterRegistration, BridgeConfig, FrontMcpBridgeInterface, BridgeEventType, BridgeEventPayloads, JsonRpcMessage, JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, JsonRpcError, ExtAppsInitializeParams, ExtAppsInitializeResult, ExtAppsToolInputParams, ExtAppsToolResultParams, ExtAppsHostContextChangeParams, } from './types';
+export { AdapterRegistry, defaultRegistry, registerAdapter, getAdapter, detectAdapter } from './core/adapter-registry';
+export { FrontMcpBridge, createBridge, getGlobalBridge, resetGlobalBridge } from './core/bridge-factory';
+export { BaseAdapter, DEFAULT_CAPABILITIES, DEFAULT_SAFE_AREA } from './adapters/base-adapter';
+export { OpenAIAdapter, createOpenAIAdapter } from './adapters/openai.adapter';
+export { ExtAppsAdapter, createExtAppsAdapter, type ExtAppsAdapterConfig } from './adapters/ext-apps.adapter';
+export { ClaudeAdapter, createClaudeAdapter } from './adapters/claude.adapter';
+export { GeminiAdapter, createGeminiAdapter } from './adapters/gemini.adapter';
+export { GenericAdapter, createGenericAdapter } from './adapters/generic.adapter';
+export { registerBuiltInAdapters } from './adapters';
+export { generateBridgeIIFE, generatePlatformBundle, UNIVERSAL_BRIDGE_SCRIPT, BRIDGE_SCRIPT_TAGS, type IIFEGeneratorOptions, } from './runtime/iife-generator';
+//# sourceMappingURL=index.d.ts.map

package/bridge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAGH,YAAY,EAEV,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EAEX,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,cAAc,EACd,mBAAmB,EAEnB,YAAY,EACZ,uBAAuB,EAEvB,eAAe,EACf,mBAAmB,EAEnB,cAAc,EACd,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAEvH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGzG,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE/F,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAE/E,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAE9G,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAE/E,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAE/E,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElF,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,oBAAoB,GAC1B,MAAM,0BAA0B,CAAC"}