@frontmcp/ui 0.5.0

package/src/adapters/platform-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-meta.js","sourceRoot":"","sources":["../../../src/adapters/platform-meta.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Platform Metadata Adapters\n *\n * Build platform-specific _meta fields for tool UI responses.\n * Adapts the UI configuration to the format expected by each\n * AI platform (OpenAI, Claude, Gemini, etc.).\n *\n * This module is SDK-independent and can be used by external systems\n * like AgentLink without requiring @frontmcp/sdk.\n *\n * @packageDocumentation\n */\n\nimport type { UITemplateConfig, UIContentSecurityPolicy } from '../types';\n\n// ============================================\n// Platform Types\n// ============================================\n\n/**\n * Supported AI platform types.\n * Used to determine which metadata format to generate.\n */\nexport type AIPlatformType =\n  | 'openai'\n  | 'claude'\n  | 'gemini'\n  | 'cursor'\n  | 'continue'\n  | 'cody'\n  | 'generic-mcp'\n  | 'ext-apps'\n  | 'unknown';\n\n// ============================================\n// UI Metadata\n// ============================================\n\n/**\n * UI metadata to include in tool response _meta field.\n * Contains both universal fields and platform-specific annotations.\n */\nexport interface UIMetadata {\n  // Universal fields\n  /** Inline rendered HTML (universal) */\n  'ui/html'?: string;\n  /** MIME type for the HTML content */\n  'ui/mimeType'?: string;\n  /** Widget token for authenticated operations */\n  'ui/widgetToken'?: string;\n  /** Direct URL to widget (for direct-url serving mode) */\n  'ui/directUrl'?: string;\n\n  // Widget manifest fields (new)\n  /** Renderer type for the widget (html, react, mdx, markdown, auto) */\n  'ui/type'?: string;\n  /** Manifest URI for accessing widget configuration */\n  'ui/manifestUri'?: string;\n  /** Hash of the widget content for cache validation */\n  'ui/contentHash'?: string;\n  /** Required renderer assets for lazy loading */\n  'ui/requiredRenderers'?: string[];\n\n  // OpenAI-specific fields\n  /** OpenAI: Resource URI for widget template */\n  'openai/outputTemplate'?: string;\n  /** OpenAI: Whether widget can invoke tools */\n  'openai/widgetAccessible'?: boolean;\n  /** OpenAI: Whether tool result can produce a widget (CRITICAL for ChatGPT) */\n  'openai/resultCanProduceWidget'?: boolean;\n  /** OpenAI: CSP configuration */\n  'openai/widgetCSP'?: {\n    connect_domains?: string[];\n    resource_domains?: string[];\n  };\n  /** OpenAI: Display mode preference */\n  'openai/displayMode'?: string;\n  /** OpenAI: Widget description */\n  'openai/widgetDescription'?: string;\n  /** OpenAI: Status text while tool is executing */\n  'openai/toolInvocation/invoking'?: string;\n  /** OpenAI: Status text after tool execution completes */\n  'openai/toolInvocation/invoked'?: string;\n\n  // Claude-specific fields\n  /** Claude: Widget description */\n  'claude/widgetDescription'?: string;\n\n  // Gemini-specific fields\n  /** Gemini: Widget description */\n  'gemini/widgetDescription'?: string;\n\n  // IDE-specific fields (Cursor, Continue, Cody)\n  /** IDE: Resource URI for widget template */\n  'ide/outputTemplate'?: string;\n  /** IDE: Widget description */\n  'ide/widgetDescription'?: string;\n\n  // MCP Apps (ext-apps) fields - per specification\n  /** MCP Apps: Resource URI for UI template */\n  'ui/resourceUri'?: string;\n  /** MCP Apps: CSP configuration */\n  'ui/csp'?: {\n    connectDomains?: string[];\n    resourceDomains?: string[];\n  };\n  /** MCP Apps: Dedicated sandbox domain */\n  'ui/domain'?: string;\n  /** MCP Apps: Whether to show border around UI */\n  'ui/prefersBorder'?: boolean;\n  /** MCP Apps: Display mode */\n  'ui/displayMode'?: 'inline' | 'fullscreen' | 'pip';\n\n  /** Allow additional platform-specific fields */\n  [key: string]: unknown;\n}\n\n// ============================================\n// Build Options\n// ============================================\n\n/**\n * Options for building UI metadata.\n */\nexport interface BuildUIMetaOptions<In = unknown, Out = unknown> {\n  /** Tool UI configuration */\n  uiConfig: UITemplateConfig<In, Out>;\n  /** Detected platform type */\n  platformType: AIPlatformType;\n  /** Rendered HTML content */\n  html: string;\n  /** Widget access token */\n  token?: string;\n  /** Direct URL for widget serving */\n  directUrl?: string;\n  /** Renderer type for the widget (html, react, mdx, markdown, auto) */\n  rendererType?: string;\n  /** Hash of the widget content for cache validation */\n  contentHash?: string;\n  /** Manifest URI for accessing widget configuration */\n  manifestUri?: string;\n}\n\n// ============================================\n// Main Builder Function\n// ============================================\n\n/**\n * Build platform-specific UI metadata for tool response.\n *\n * For inline serving mode (default), HTML is embedded directly in `_meta['ui/html']`.\n * For static mode, the static widget URI is provided in tools/list\n * and the tool response contains only structured data.\n *\n * @example\n * ```typescript\n * import { buildUIMeta } from '@frontmcp/ui/adapters';\n *\n * const meta = buildUIMeta({\n *   uiConfig: { template: (ctx) => `<div>${ctx.output.value}</div>` },\n *   platformType: 'openai',\n *   html: '<div>Hello World</div>',\n * });\n * ```\n */\nexport function buildUIMeta<In = unknown, Out = unknown>(options: BuildUIMetaOptions<In, Out>): UIMetadata {\n  const { uiConfig, platformType, html, token, directUrl, rendererType, contentHash, manifestUri } = options;\n\n  const meta: UIMetadata = {};\n\n  // Add manifest-related fields if provided\n  if (rendererType) {\n    meta['ui/type'] = rendererType;\n  }\n  if (contentHash) {\n    meta['ui/contentHash'] = contentHash;\n  }\n  if (manifestUri) {\n    meta['ui/manifestUri'] = manifestUri;\n  }\n\n  // For inline mode, embed HTML directly in response\n  // This is the only serving mode that uses buildUIMeta\n  // (static mode returns structured data only, no UI _meta)\n  meta['ui/html'] = html;\n\n  // Always include MIME type for platforms that need it\n  meta['ui/mimeType'] = getMimeType(platformType);\n\n  // Include token if provided\n  if (token) {\n    meta['ui/widgetToken'] = token;\n  }\n\n  // Include direct URL if provided\n  if (directUrl) {\n    meta['ui/directUrl'] = directUrl;\n  }\n\n  // Platform-specific fields\n  switch (platformType) {\n    case 'openai':\n      return buildOpenAIMeta(meta, uiConfig);\n\n    case 'claude':\n      return buildClaudeMeta(meta, uiConfig);\n\n    case 'gemini':\n      return buildGeminiMeta(meta, uiConfig);\n\n    case 'cursor':\n    case 'continue':\n    case 'cody':\n      return buildIDEMeta(meta, uiConfig);\n\n    case 'generic-mcp':\n      return buildGenericMeta(meta, uiConfig);\n\n    case 'ext-apps':\n      return buildExtAppsMeta(meta, uiConfig);\n\n    default:\n      // Unknown platform - just return universal fields\n      return meta;\n  }\n}\n\n// ============================================\n// Helper Functions\n// ============================================\n\n/**\n * Get MIME type based on platform.\n */\nfunction getMimeType(platformType: AIPlatformType): string {\n  switch (platformType) {\n    case 'openai':\n      return 'text/html+skybridge';\n    default:\n      return 'text/html+mcp';\n  }\n}\n\n/**\n * Build OpenAI-specific metadata for tool CALL response (inline mode).\n *\n * NOTE: Per OpenAI's pizzaz example, the call response should only include\n * invocation status in _meta. The outputTemplate, resultCanProduceWidget, etc.\n * are discovery-time fields that belong in tools/list _meta, NOT in call response.\n *\n * For static mode: OpenAI fetches the widget HTML from the outputTemplate URI\n * (set in tools/list) and injects structuredContent as window.openai.toolOutput.\n * For inline mode: HTML is embedded directly in _meta['ui/html'].\n */\nfunction buildOpenAIMeta<In, Out>(meta: UIMetadata, uiConfig: UITemplateConfig<In, Out>): UIMetadata {\n  // Only include invocation status in call response _meta\n  // (per pizzaz example - they don't include outputTemplate in call response)\n  if (uiConfig.invocationStatus?.invoking) {\n    meta['openai/toolInvocation/invoking'] = uiConfig.invocationStatus.invoking;\n  }\n  if (uiConfig.invocationStatus?.invoked) {\n    meta['openai/toolInvocation/invoked'] = uiConfig.invocationStatus.invoked;\n  }\n\n  return meta;\n}\n\n/**\n * Build OpenAI CSP format.\n */\nexport function buildOpenAICSP(csp: UIContentSecurityPolicy): {\n  connect_domains?: string[];\n  resource_domains?: string[];\n} {\n  const result: { connect_domains?: string[]; resource_domains?: string[] } = {};\n\n  if (csp.connectDomains?.length) {\n    result.connect_domains = csp.connectDomains;\n  }\n\n  if (csp.resourceDomains?.length) {\n    result.resource_domains = csp.resourceDomains;\n  }\n\n  return result;\n}\n\n/**\n * Build Claude-specific metadata.\n * Claude widgets are network-blocked, so we don't include URI references.\n */\nfunction buildClaudeMeta<In, Out>(meta: UIMetadata, uiConfig: UITemplateConfig<In, Out>): UIMetadata {\n  // Claude uses inline HTML only (network-blocked)\n  // Don't include resource URI since Claude can't fetch it\n\n  if (uiConfig.widgetDescription) {\n    meta['claude/widgetDescription'] = uiConfig.widgetDescription;\n  }\n\n  return meta;\n}\n\n/**\n * Build Gemini-specific metadata.\n */\nfunction buildGeminiMeta<In, Out>(meta: UIMetadata, uiConfig: UITemplateConfig<In, Out>): UIMetadata {\n  // Gemini support is limited - include inline HTML\n  // Future: Add Gemini-specific fields when they're defined\n\n  if (uiConfig.widgetDescription) {\n    meta['gemini/widgetDescription'] = uiConfig.widgetDescription;\n  }\n\n  return meta;\n}\n\n/**\n * Build IDE-specific metadata (Cursor, Continue, Cody).\n * For inline mode, HTML is embedded directly in _meta['ui/html'].\n */\nfunction buildIDEMeta<In, Out>(meta: UIMetadata, uiConfig: UITemplateConfig<In, Out>): UIMetadata {\n  if (uiConfig.widgetDescription) {\n    meta['ide/widgetDescription'] = uiConfig.widgetDescription;\n  }\n\n  return meta;\n}\n\n/**\n * Build generic MCP client metadata.\n * For inline mode, HTML is embedded directly in _meta['ui/html'].\n */\nfunction buildGenericMeta<In, Out>(meta: UIMetadata, uiConfig: UITemplateConfig<In, Out>): UIMetadata {\n  if (uiConfig.widgetAccessible) {\n    meta['openai/widgetAccessible'] = true;\n  }\n\n  if (uiConfig.csp) {\n    meta['openai/widgetCSP'] = buildOpenAICSP(uiConfig.csp);\n  }\n\n  return meta;\n}\n\n/**\n * Build MCP Apps (ext-apps) metadata per specification.\n * For inline mode, HTML is embedded directly in _meta['ui/html'].\n *\n * Per MCP Apps spec: https://github.com/modelcontextprotocol/ext-apps\n * - ui/csp: Content security policy for sandboxed iframe\n * - ui/displayMode: How the UI should be displayed\n * - ui/prefersBorder: Whether to show border around UI\n * - ui/domain: Optional dedicated sandbox domain\n */\nfunction buildExtAppsMeta<In, Out>(meta: UIMetadata, uiConfig: UITemplateConfig<In, Out>): UIMetadata {\n  // MCP Apps uses text/html+mcp MIME type\n  meta['ui/mimeType'] = 'text/html+mcp';\n\n  // CSP configuration (uses camelCase per MCP Apps spec)\n  if (uiConfig.csp) {\n    const csp: { connectDomains?: string[]; resourceDomains?: string[] } = {};\n\n    if (uiConfig.csp.connectDomains?.length) {\n      csp.connectDomains = uiConfig.csp.connectDomains;\n    }\n\n    if (uiConfig.csp.resourceDomains?.length) {\n      csp.resourceDomains = uiConfig.csp.resourceDomains;\n    }\n\n    if (Object.keys(csp).length > 0) {\n      meta['ui/csp'] = csp;\n    }\n  }\n\n  // Display mode preference\n  if (uiConfig.displayMode) {\n    // Map generic display modes to MCP Apps specific values\n    const displayModeMap: Record<string, 'inline' | 'fullscreen' | 'pip'> = {\n      inline: 'inline',\n      fullscreen: 'fullscreen',\n      pip: 'pip',\n      // Map OpenAI-style values\n      widget: 'inline',\n      panel: 'fullscreen',\n    };\n    const mappedMode = displayModeMap[uiConfig.displayMode];\n    if (mappedMode) {\n      meta['ui/displayMode'] = mappedMode;\n    }\n  }\n\n  // Border preference (default: true for visual clarity in sandbox)\n  if (uiConfig.prefersBorder !== undefined) {\n    meta['ui/prefersBorder'] = uiConfig.prefersBorder;\n  }\n\n  // Dedicated sandbox domain (optional)\n  if (uiConfig.sandboxDomain) {\n    meta['ui/domain'] = uiConfig.sandboxDomain;\n  }\n\n  return meta;\n}\n\n// ============================================\n// Tool Discovery Metadata\n// ============================================\n\n/**\n * Build metadata for tool discovery (tools/list response).\n * This includes fields that should be present at discovery time,\n * not in individual tool call responses.\n *\n * @example\n * ```typescript\n * import { buildToolDiscoveryMeta } from '@frontmcp/ui/adapters';\n *\n * const toolMeta = buildToolDiscoveryMeta({\n *   uiConfig: { template: MyWidget, widgetAccessible: true },\n *   platformType: 'openai',\n *   staticWidgetUri: 'ui://widget/my_tool.html',\n * });\n *\n * // Use in tools/list response\n * const tool = {\n *   name: 'my_tool',\n *   description: '...',\n *   inputSchema: {...},\n *   _meta: toolMeta,\n * };\n * ```\n */\nexport interface BuildToolDiscoveryMetaOptions<In = unknown, Out = unknown> {\n  /** Tool UI configuration */\n  uiConfig: UITemplateConfig<In, Out>;\n  /** Detected platform type */\n  platformType: AIPlatformType;\n  /** Static widget URI (e.g., ui://widget/my_tool.html) */\n  staticWidgetUri: string;\n}\n\n/**\n * Build tool discovery metadata (for tools/list response).\n */\nexport function buildToolDiscoveryMeta<In = unknown, Out = unknown>(\n  options: BuildToolDiscoveryMetaOptions<In, Out>,\n): UIMetadata {\n  const { uiConfig, platformType, staticWidgetUri } = options;\n\n  const meta: UIMetadata = {};\n\n  switch (platformType) {\n    case 'openai':\n      // OpenAI-specific discovery fields\n      meta['openai/outputTemplate'] = staticWidgetUri;\n      meta['openai/resultCanProduceWidget'] = true;\n\n      if (uiConfig.widgetAccessible) {\n        meta['openai/widgetAccessible'] = true;\n      }\n\n      if (uiConfig.csp) {\n        meta['openai/widgetCSP'] = buildOpenAICSP(uiConfig.csp);\n      }\n\n      if (uiConfig.displayMode) {\n        meta['openai/displayMode'] = uiConfig.displayMode;\n      }\n\n      if (uiConfig.widgetDescription) {\n        meta['openai/widgetDescription'] = uiConfig.widgetDescription;\n      }\n      break;\n\n    case 'generic-mcp':\n      // Generic MCP uses OpenAI-like format\n      meta['openai/outputTemplate'] = staticWidgetUri;\n      meta['openai/resultCanProduceWidget'] = true;\n\n      if (uiConfig.widgetAccessible) {\n        meta['openai/widgetAccessible'] = true;\n      }\n\n      if (uiConfig.csp) {\n        meta['openai/widgetCSP'] = buildOpenAICSP(uiConfig.csp);\n      }\n      break;\n\n    case 'ext-apps':\n      // MCP Apps discovery metadata per specification\n      meta['ui/resourceUri'] = staticWidgetUri;\n      meta['ui/mimeType'] = 'text/html+mcp';\n\n      if (uiConfig.csp) {\n        const csp: { connectDomains?: string[]; resourceDomains?: string[] } = {};\n        if (uiConfig.csp.connectDomains?.length) {\n          csp.connectDomains = uiConfig.csp.connectDomains;\n        }\n        if (uiConfig.csp.resourceDomains?.length) {\n          csp.resourceDomains = uiConfig.csp.resourceDomains;\n        }\n        if (Object.keys(csp).length > 0) {\n          meta['ui/csp'] = csp;\n        }\n      }\n\n      if (uiConfig.displayMode) {\n        const displayModeMap: Record<string, 'inline' | 'fullscreen' | 'pip'> = {\n          inline: 'inline',\n          fullscreen: 'fullscreen',\n          pip: 'pip',\n        };\n        const mappedMode = displayModeMap[uiConfig.displayMode];\n        if (mappedMode) {\n          meta['ui/displayMode'] = mappedMode;\n        }\n      }\n\n      if (uiConfig.prefersBorder !== undefined) {\n        meta['ui/prefersBorder'] = uiConfig.prefersBorder;\n      }\n\n      if (uiConfig.sandboxDomain) {\n        meta['ui/domain'] = uiConfig.sandboxDomain;\n      }\n      break;\n\n    // Claude, Gemini, IDEs don't need discovery metadata\n    // They use inline HTML at call time\n    default:\n      break;\n  }\n\n  return meta;\n}\n"]}

package/src/base-template/bridge.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Platform Bridge - Reactive Data Store for Tool UI
+ *
+ * Provides a reactive interface for tool output data that works across:
+ * - React (via useSyncExternalStore)
+ * - HTMX (via custom events)
+ * - Vanilla JS (via subscribe callbacks)
+ *
+ * Uses Object.defineProperty to intercept when platforms inject data,
+ * automatically detecting and notifying subscribers when data changes.
+ *
+ * @example React integration
+ * ```tsx
+ * import { useSyncExternalStore } from 'react';
+ *
+ * function useToolOutput() {
+ *   return useSyncExternalStore(
+ *     window.__frontmcp.bridge.subscribe,
+ *     window.__frontmcp.bridge.getSnapshot,
+ *     window.__frontmcp.bridge.getServerSnapshot
+ *   );
+ * }
+ * ```
+ *
+ * @example Vanilla JS
+ * ```javascript
+ * const unsubscribe = window.__frontmcp.bridge.subscribe(() => {
+ *   const state = window.__frontmcp.bridge.getState();
+ *   if (!state.loading) {
+ *     renderWidget(state.data);
+ *   }
+ * });
+ * ```
+ *
+ * @example HTMX
+ * ```html
+ * <div hx-trigger="frontmcp:change from:document" hx-get="/render">
+ *   Loading...
+ * </div>
+ * ```
+ */
+/**
+ * Bridge state containing data, loading status, and error information.
+ */
+export interface BridgeState<T = unknown> {
+    /** Current data (null when loading or no data) */
+    data: T | null;
+    /** Whether the bridge is waiting for data */
+    loading: boolean;
+    /** Error message if data loading failed */
+    error: string | null;
+}
+/**
+ * Platform Bridge interface for reactive data access.
+ */
+export interface PlatformBridge<T = unknown> {
+    /** Get current state snapshot */
+    getState(): BridgeState<T>;
+    /** Subscribe to state changes */
+    subscribe(callback: () => void): () => void;
+    /** React useSyncExternalStore compatible getSnapshot */
+    getSnapshot(): BridgeState<T>;
+    /** React SSR compatible getServerSnapshot */
+    getServerSnapshot(): BridgeState<T>;
+    /** Check if bridge has received data */
+    hasData(): boolean;
+    /** Manually set data (for testing or custom injection) */
+    setData(data: T): void;
+    /** Manually set error */
+    setError(error: string): void;
+    /** Reset to loading state */
+    reset(): void;
+}
+/**
+ * Render the Platform Bridge inline script.
+ *
+ * This script creates a reactive data store that:
+ * 1. Installs interceptors on window.openai to detect data injection
+ * 2. Provides subscribe/getState API for React/HTMX/vanilla integration
+ * 3. Dispatches custom events for HTMX compatibility
+ * 4. Handles the race condition between iframe load and data injection
+ *
+ * @returns Script tag with bridge implementation
+ */
+export declare function renderBridgeScript(): string;
+/**
+ * Generate TypeScript types for the bridge (for documentation/IDE support).
+ */
+export declare const BRIDGE_TYPES = "\ninterface BridgeState<T = unknown> {\n  data: T | null;\n  loading: boolean;\n  error: string | null;\n}\n\ninterface PlatformBridge<T = unknown> {\n  getState(): BridgeState<T>;\n  subscribe(callback: () => void): () => void;\n  getSnapshot(): BridgeState<T>;\n  getServerSnapshot(): BridgeState<T>;\n  hasData(): boolean;\n  setData(data: T): void;\n  setError(error: string): void;\n  reset(): void;\n}\n\ndeclare global {\n  interface Window {\n    __frontmcp: {\n      bridge: PlatformBridge;\n      // ... other __frontmcp methods\n    };\n  }\n}\n";

package/src/base-template/bridge.js

@@ -0,0 +1,452 @@
+"use strict";
+/**
+ * Platform Bridge - Reactive Data Store for Tool UI
+ *
+ * Provides a reactive interface for tool output data that works across:
+ * - React (via useSyncExternalStore)
+ * - HTMX (via custom events)
+ * - Vanilla JS (via subscribe callbacks)
+ *
+ * Uses Object.defineProperty to intercept when platforms inject data,
+ * automatically detecting and notifying subscribers when data changes.
+ *
+ * @example React integration
+ * ```tsx
+ * import { useSyncExternalStore } from 'react';
+ *
+ * function useToolOutput() {
+ *   return useSyncExternalStore(
+ *     window.__frontmcp.bridge.subscribe,
+ *     window.__frontmcp.bridge.getSnapshot,
+ *     window.__frontmcp.bridge.getServerSnapshot
+ *   );
+ * }
+ * ```
+ *
+ * @example Vanilla JS
+ * ```javascript
+ * const unsubscribe = window.__frontmcp.bridge.subscribe(() => {
+ *   const state = window.__frontmcp.bridge.getState();
+ *   if (!state.loading) {
+ *     renderWidget(state.data);
+ *   }
+ * });
+ * ```
+ *
+ * @example HTMX
+ * ```html
+ * <div hx-trigger="frontmcp:change from:document" hx-get="/render">
+ *   Loading...
+ * </div>
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BRIDGE_TYPES = void 0;
+exports.renderBridgeScript = renderBridgeScript;
+/**
+ * Render the Platform Bridge inline script.
+ *
+ * This script creates a reactive data store that:
+ * 1. Installs interceptors on window.openai to detect data injection
+ * 2. Provides subscribe/getState API for React/HTMX/vanilla integration
+ * 3. Dispatches custom events for HTMX compatibility
+ * 4. Handles the race condition between iframe load and data injection
+ *
+ * @returns Script tag with bridge implementation
+ */
+function renderBridgeScript() {
+    return `<script>
+(function() {
+  'use strict';
+
+  // ============================================
+  // Debug Mode
+  // ============================================
+
+  var DEBUG = window.location.search.indexOf('frontmcp_debug=1') > -1 ||
+              window.localStorage.getItem('frontmcp_debug') === '1';
+  var debugLog = [];
+
+  function log(level, message, data) {
+    var entry = {
+      ts: new Date().toISOString(),
+      level: level,
+      message: message,
+      data: data
+    };
+    debugLog.push(entry);
+    if (DEBUG) {
+      console[level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log'](
+        '[frontmcp] ' + message,
+        data || ''
+      );
+    }
+  }
+
+  // ============================================
+  // Bridge State Management
+  // ============================================
+
+  var state = { data: null, loading: true, error: null };
+  var subscribers = [];
+  var stateVersion = 0;  // For React useSyncExternalStore stability
+
+  function notify() {
+    stateVersion++;
+    for (var i = 0; i < subscribers.length; i++) {
+      try { subscribers[i](); } catch(e) {
+        log('error', 'Subscriber error:', { error: e.message, stack: e.stack });
+      }
+    }
+    // Dispatch custom event for HTMX
+    if (typeof CustomEvent !== 'undefined') {
+      document.dispatchEvent(new CustomEvent('frontmcp:change', { detail: state }));
+    }
+  }
+
+  function setData(data) {
+    // Skip if data hasn't actually changed (prevents unnecessary re-renders)
+    if (!state.loading && state.data === data) return;
+    log('info', 'setData called', {
+      dataType: typeof data,
+      dataLength: typeof data === 'string' ? data.length : 'N/A',
+      isNull: data === null,
+      isUndefined: data === undefined
+    });
+    state = { data: data, loading: false, error: null };
+    notify();
+  }
+
+  function setError(error) {
+    log('error', 'setError called', { error: error });
+    state = { data: null, loading: false, error: error };
+    notify();
+  }
+
+  function reset() {
+    log('info', 'reset called');
+    state = { data: null, loading: true, error: null };
+    notify();
+  }
+
+  // ============================================
+  // Data Validation
+  // ============================================
+
+  function validateToolOutput(data, source) {
+    var errors = [];
+
+    if (data === undefined) {
+      errors.push('toolOutput is undefined');
+    } else if (data === null) {
+      // null is valid initial state from OpenAI
+      log('info', 'toolOutput is null (OpenAI initial state)', { source: source });
+      return { valid: false, errors: ['initial_state'], isInitial: true };
+    }
+
+    if (typeof data === 'object' && data !== null) {
+      if (data.isError === true) {
+        errors.push('Tool returned error: ' + JSON.stringify(data));
+      }
+      // Check for MCP error structure
+      if (data.error && data.error.code) {
+        errors.push('MCP error: code=' + data.error.code + ', message=' + (data.error.message || 'unknown'));
+      }
+    }
+
+    if (errors.length > 0) {
+      log('warn', 'Validation issues', { source: source, errors: errors });
+    }
+
+    return { valid: errors.length === 0, errors: errors, isInitial: false };
+  }
+
+  function validateMetadata(meta, source) {
+    var errors = [];
+
+    if (!meta) {
+      errors.push('toolResponseMetadata is null/undefined');
+      return { valid: false, errors: errors };
+    }
+
+    if (typeof meta !== 'object') {
+      errors.push('toolResponseMetadata is not an object: ' + typeof meta);
+      return { valid: false, errors: errors };
+    }
+
+    var html = meta['ui/html'];
+    if (html !== undefined) {
+      if (typeof html !== 'string') {
+        errors.push('ui/html is not a string: ' + typeof html);
+      } else if (html.length === 0) {
+        errors.push('ui/html is empty string');
+      } else if (html.indexOf('validation-error') > -1) {
+        errors.push('ui/html contains validation error');
+        log('warn', 'HTML contains validation error', { htmlPreview: html.substring(0, 500) });
+      }
+    }
+
+    if (errors.length > 0) {
+      log('warn', 'Metadata validation issues', { source: source, errors: errors, keys: Object.keys(meta) });
+    }
+
+    return { valid: errors.length === 0, errors: errors };
+  }
+
+  // ============================================
+  // OpenAI Platform Interceptors
+  // ============================================
+
+  var openaiIntercepted = false;
+
+  function checkOpenAIData(openai) {
+    if (!openai) {
+      log('warn', 'checkOpenAIData: openai object is null');
+      return false;
+    }
+
+    log('info', 'checkOpenAIData called', {
+      hasToolOutput: openai.toolOutput !== undefined,
+      hasToolResponseMetadata: openai.toolResponseMetadata !== undefined,
+      toolOutputType: typeof openai.toolOutput,
+      metadataKeys: openai.toolResponseMetadata ? Object.keys(openai.toolResponseMetadata) : []
+    });
+
+    // Priority 1: Pre-rendered HTML from toolResponseMetadata
+    if (openai.toolResponseMetadata) {
+      var metaValidation = validateMetadata(openai.toolResponseMetadata, 'openai.toolResponseMetadata');
+      var html = openai.toolResponseMetadata['ui/html'];
+      if (html && typeof html === 'string') {
+        log('info', 'Using ui/html from metadata', { htmlLength: html.length });
+        setData(html);
+        return true;
+      }
+    }
+
+    // Priority 2: Tool output (skip null - that's OpenAI's initial state)
+    if (openai.toolOutput !== undefined && openai.toolOutput !== null) {
+      var outputValidation = validateToolOutput(openai.toolOutput, 'openai.toolOutput');
+      if (!outputValidation.isInitial) {
+        log('info', 'Using toolOutput', {
+          valid: outputValidation.valid,
+          errors: outputValidation.errors
+        });
+        setData(openai.toolOutput);
+        return true;
+      }
+    }
+
+    log('info', 'checkOpenAIData: no data found yet');
+    return false;
+  }
+
+  function installPropertyInterceptor(obj, prop, onSet) {
+    var current = obj[prop];
+    var descriptor = Object.getOwnPropertyDescriptor(obj, prop);
+
+    // Don't re-intercept
+    if (descriptor && descriptor.get && descriptor.set) return;
+
+    Object.defineProperty(obj, prop, {
+      get: function() { return current; },
+      set: function(val) {
+        current = val;
+        onSet(val);
+      },
+      enumerable: true,
+      configurable: true
+    });
+  }
+
+  function installOpenAIInterceptors(openai) {
+    if (!openai || openaiIntercepted) return;
+    openaiIntercepted = true;
+
+    // Check existing data first
+    if (checkOpenAIData(openai)) return;
+
+    // Intercept toolOutput
+    installPropertyInterceptor(openai, 'toolOutput', function(val) {
+      checkOpenAIData(openai);
+    });
+
+    // Intercept toolResponseMetadata
+    installPropertyInterceptor(openai, 'toolResponseMetadata', function(val) {
+      checkOpenAIData(openai);
+    });
+  }
+
+  // Install interceptor on window.openai
+  if (typeof window.openai !== 'undefined') {
+    installOpenAIInterceptors(window.openai);
+  } else {
+    // OpenAI object doesn't exist yet - wait for it
+    var pendingOpenai = undefined;
+    Object.defineProperty(window, 'openai', {
+      get: function() { return pendingOpenai; },
+      set: function(val) {
+        pendingOpenai = val;
+        if (val) installOpenAIInterceptors(val);
+      },
+      enumerable: true,
+      configurable: true
+    });
+  }
+
+  // ============================================
+  // MCP/Generic Platform Support
+  // ============================================
+
+  // Check for existing __frontmcp.toolOutput
+  if (window.__frontmcp && window.__frontmcp.toolOutput !== undefined) {
+    setData(window.__frontmcp.toolOutput);
+  }
+
+  // Check for __mcpToolOutput
+  if (window.__mcpToolOutput !== undefined && window.__mcpToolOutput !== null) {
+    setData(window.__mcpToolOutput);
+  }
+
+  // Check for __mcpResponseMeta
+  if (window.__mcpResponseMeta && window.__mcpResponseMeta['ui/html']) {
+    setData(window.__mcpResponseMeta['ui/html']);
+  }
+
+  // ============================================
+  // Bridge API
+  // ============================================
+
+  window.__frontmcp = window.__frontmcp || {};
+
+  window.__frontmcp.bridge = {
+    getState: function() { return state; },
+
+    // React useSyncExternalStore compatible
+    getSnapshot: function() { return state; },
+    getServerSnapshot: function() { return { data: null, loading: true, error: null }; },
+
+    subscribe: function(callback) {
+      subscribers.push(callback);
+      return function() {
+        var idx = subscribers.indexOf(callback);
+        if (idx > -1) subscribers.splice(idx, 1);
+      };
+    },
+
+    hasData: function() { return !state.loading && state.data !== null; },
+
+    // Manual control (for testing/custom injection)
+    setData: setData,
+    setError: setError,
+    reset: reset,
+
+    // Debug API
+    debug: {
+      getLogs: function() { return debugLog.slice(); },
+      getLastErrors: function() {
+        return debugLog.filter(function(e) { return e.level === 'error' || e.level === 'warn'; });
+      },
+      enableDebug: function() {
+        DEBUG = true;
+        window.localStorage.setItem('frontmcp_debug', '1');
+        console.log('[frontmcp] Debug mode enabled. Reload page to see all logs.');
+      },
+      disableDebug: function() {
+        DEBUG = false;
+        window.localStorage.removeItem('frontmcp_debug');
+      },
+      isDebugEnabled: function() { return DEBUG; },
+      getStateHistory: function() {
+        return {
+          current: state,
+          version: stateVersion,
+          subscriberCount: subscribers.length,
+          openaiIntercepted: openaiIntercepted,
+          pollCount: pollCount
+        };
+      },
+      dumpAll: function() {
+        console.group('[frontmcp] Debug Dump');
+        console.log('State:', state);
+        console.log('Version:', stateVersion);
+        console.log('Subscribers:', subscribers.length);
+        console.log('OpenAI Intercepted:', openaiIntercepted);
+        console.log('Poll Count:', pollCount);
+        console.log('Debug Logs:', debugLog);
+        console.groupEnd();
+        return {
+          state: state,
+          logs: debugLog,
+          version: stateVersion,
+          openaiIntercepted: openaiIntercepted
+        };
+      }
+    }
+  };
+
+  // ============================================
+  // Fallback Polling (for platforms that don't trigger setters)
+  // ============================================
+
+  var pollCount = 0;
+  var maxPolls = 30;  // ~3 seconds with exponential backoff
+
+  function pollForData() {
+    if (state.data !== null || pollCount >= maxPolls) return;
+    pollCount++;
+
+    // Check all sources
+    if (window.openai) {
+      if (checkOpenAIData(window.openai)) return;
+    }
+
+    // Use getToolOutput if available
+    if (window.__frontmcp.getToolOutput) {
+      var data = window.__frontmcp.getToolOutput();
+      if (data !== undefined && data !== null) {
+        setData(data);
+        return;
+      }
+    }
+
+    // Exponential backoff: 50ms, 75ms, 112ms, ...
+    var delay = Math.min(50 * Math.pow(1.5, Math.min(pollCount, 10)), 500);
+    setTimeout(pollForData, delay);
+  }
+
+  // Start polling after a brief delay (give interceptors time to fire)
+  setTimeout(pollForData, 50);
+})();
+</script>`;
+}
+/**
+ * Generate TypeScript types for the bridge (for documentation/IDE support).
+ */
+exports.BRIDGE_TYPES = `
+interface BridgeState<T = unknown> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+}
+
+interface PlatformBridge<T = unknown> {
+  getState(): BridgeState<T>;
+  subscribe(callback: () => void): () => void;
+  getSnapshot(): BridgeState<T>;
+  getServerSnapshot(): BridgeState<T>;
+  hasData(): boolean;
+  setData(data: T): void;
+  setError(error: string): void;
+  reset(): void;
+}
+
+declare global {
+  interface Window {
+    __frontmcp: {
+      bridge: PlatformBridge;
+      // ... other __frontmcp methods
+    };
+  }
+}
+`;
+//# sourceMappingURL=bridge.js.map

package/src/base-template/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../../src/base-template/bridge.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;;;AA+CH,gDA4WC;AAvXD;;;;;;;;;;GAUG;AACH,SAAgB,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA0WC,CAAC;AACX,CAAC;AAED;;GAEG;AACU,QAAA,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B3B,CAAC","sourcesContent":["/**\n * Platform Bridge - Reactive Data Store for Tool UI\n *\n * Provides a reactive interface for tool output data that works across:\n * - React (via useSyncExternalStore)\n * - HTMX (via custom events)\n * - Vanilla JS (via subscribe callbacks)\n *\n * Uses Object.defineProperty to intercept when platforms inject data,\n * automatically detecting and notifying subscribers when data changes.\n *\n * @example React integration\n * ```tsx\n * import { useSyncExternalStore } from 'react';\n *\n * function useToolOutput() {\n *   return useSyncExternalStore(\n *     window.__frontmcp.bridge.subscribe,\n *     window.__frontmcp.bridge.getSnapshot,\n *     window.__frontmcp.bridge.getServerSnapshot\n *   );\n * }\n * ```\n *\n * @example Vanilla JS\n * ```javascript\n * const unsubscribe = window.__frontmcp.bridge.subscribe(() => {\n *   const state = window.__frontmcp.bridge.getState();\n *   if (!state.loading) {\n *     renderWidget(state.data);\n *   }\n * });\n * ```\n *\n * @example HTMX\n * ```html\n * <div hx-trigger=\"frontmcp:change from:document\" hx-get=\"/render\">\n *   Loading...\n * </div>\n * ```\n */\n\n/**\n * Bridge state containing data, loading status, and error information.\n */\nexport interface BridgeState<T = unknown> {\n  /** Current data (null when loading or no data) */\n  data: T | null;\n  /** Whether the bridge is waiting for data */\n  loading: boolean;\n  /** Error message if data loading failed */\n  error: string | null;\n}\n\n/**\n * Platform Bridge interface for reactive data access.\n */\nexport interface PlatformBridge<T = unknown> {\n  /** Get current state snapshot */\n  getState(): BridgeState<T>;\n  /** Subscribe to state changes */\n  subscribe(callback: () => void): () => void;\n  /** React useSyncExternalStore compatible getSnapshot */\n  getSnapshot(): BridgeState<T>;\n  /** React SSR compatible getServerSnapshot */\n  getServerSnapshot(): BridgeState<T>;\n  /** Check if bridge has received data */\n  hasData(): boolean;\n  /** Manually set data (for testing or custom injection) */\n  setData(data: T): void;\n  /** Manually set error */\n  setError(error: string): void;\n  /** Reset to loading state */\n  reset(): void;\n}\n\n/**\n * Render the Platform Bridge inline script.\n *\n * This script creates a reactive data store that:\n * 1. Installs interceptors on window.openai to detect data injection\n * 2. Provides subscribe/getState API for React/HTMX/vanilla integration\n * 3. Dispatches custom events for HTMX compatibility\n * 4. Handles the race condition between iframe load and data injection\n *\n * @returns Script tag with bridge implementation\n */\nexport function renderBridgeScript(): string {\n  return `<script>\n(function() {\n  'use strict';\n\n  // ============================================\n  // Debug Mode\n  // ============================================\n\n  var DEBUG = window.location.search.indexOf('frontmcp_debug=1') > -1 ||\n              window.localStorage.getItem('frontmcp_debug') === '1';\n  var debugLog = [];\n\n  function log(level, message, data) {\n    var entry = {\n      ts: new Date().toISOString(),\n      level: level,\n      message: message,\n      data: data\n    };\n    debugLog.push(entry);\n    if (DEBUG) {\n      console[level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log'](\n        '[frontmcp] ' + message,\n        data || ''\n      );\n    }\n  }\n\n  // ============================================\n  // Bridge State Management\n  // ============================================\n\n  var state = { data: null, loading: true, error: null };\n  var subscribers = [];\n  var stateVersion = 0;  // For React useSyncExternalStore stability\n\n  function notify() {\n    stateVersion++;\n    for (var i = 0; i < subscribers.length; i++) {\n      try { subscribers[i](); } catch(e) {\n        log('error', 'Subscriber error:', { error: e.message, stack: e.stack });\n      }\n    }\n    // Dispatch custom event for HTMX\n    if (typeof CustomEvent !== 'undefined') {\n      document.dispatchEvent(new CustomEvent('frontmcp:change', { detail: state }));\n    }\n  }\n\n  function setData(data) {\n    // Skip if data hasn't actually changed (prevents unnecessary re-renders)\n    if (!state.loading && state.data === data) return;\n    log('info', 'setData called', {\n      dataType: typeof data,\n      dataLength: typeof data === 'string' ? data.length : 'N/A',\n      isNull: data === null,\n      isUndefined: data === undefined\n    });\n    state = { data: data, loading: false, error: null };\n    notify();\n  }\n\n  function setError(error) {\n    log('error', 'setError called', { error: error });\n    state = { data: null, loading: false, error: error };\n    notify();\n  }\n\n  function reset() {\n    log('info', 'reset called');\n    state = { data: null, loading: true, error: null };\n    notify();\n  }\n\n  // ============================================\n  // Data Validation\n  // ============================================\n\n  function validateToolOutput(data, source) {\n    var errors = [];\n\n    if (data === undefined) {\n      errors.push('toolOutput is undefined');\n    } else if (data === null) {\n      // null is valid initial state from OpenAI\n      log('info', 'toolOutput is null (OpenAI initial state)', { source: source });\n      return { valid: false, errors: ['initial_state'], isInitial: true };\n    }\n\n    if (typeof data === 'object' && data !== null) {\n      if (data.isError === true) {\n        errors.push('Tool returned error: ' + JSON.stringify(data));\n      }\n      // Check for MCP error structure\n      if (data.error && data.error.code) {\n        errors.push('MCP error: code=' + data.error.code + ', message=' + (data.error.message || 'unknown'));\n      }\n    }\n\n    if (errors.length > 0) {\n      log('warn', 'Validation issues', { source: source, errors: errors });\n    }\n\n    return { valid: errors.length === 0, errors: errors, isInitial: false };\n  }\n\n  function validateMetadata(meta, source) {\n    var errors = [];\n\n    if (!meta) {\n      errors.push('toolResponseMetadata is null/undefined');\n      return { valid: false, errors: errors };\n    }\n\n    if (typeof meta !== 'object') {\n      errors.push('toolResponseMetadata is not an object: ' + typeof meta);\n      return { valid: false, errors: errors };\n    }\n\n    var html = meta['ui/html'];\n    if (html !== undefined) {\n      if (typeof html !== 'string') {\n        errors.push('ui/html is not a string: ' + typeof html);\n      } else if (html.length === 0) {\n        errors.push('ui/html is empty string');\n      } else if (html.indexOf('validation-error') > -1) {\n        errors.push('ui/html contains validation error');\n        log('warn', 'HTML contains validation error', { htmlPreview: html.substring(0, 500) });\n      }\n    }\n\n    if (errors.length > 0) {\n      log('warn', 'Metadata validation issues', { source: source, errors: errors, keys: Object.keys(meta) });\n    }\n\n    return { valid: errors.length === 0, errors: errors };\n  }\n\n  // ============================================\n  // OpenAI Platform Interceptors\n  // ============================================\n\n  var openaiIntercepted = false;\n\n  function checkOpenAIData(openai) {\n    if (!openai) {\n      log('warn', 'checkOpenAIData: openai object is null');\n      return false;\n    }\n\n    log('info', 'checkOpenAIData called', {\n      hasToolOutput: openai.toolOutput !== undefined,\n      hasToolResponseMetadata: openai.toolResponseMetadata !== undefined,\n      toolOutputType: typeof openai.toolOutput,\n      metadataKeys: openai.toolResponseMetadata ? Object.keys(openai.toolResponseMetadata) : []\n    });\n\n    // Priority 1: Pre-rendered HTML from toolResponseMetadata\n    if (openai.toolResponseMetadata) {\n      var metaValidation = validateMetadata(openai.toolResponseMetadata, 'openai.toolResponseMetadata');\n      var html = openai.toolResponseMetadata['ui/html'];\n      if (html && typeof html === 'string') {\n        log('info', 'Using ui/html from metadata', { htmlLength: html.length });\n        setData(html);\n        return true;\n      }\n    }\n\n    // Priority 2: Tool output (skip null - that's OpenAI's initial state)\n    if (openai.toolOutput !== undefined && openai.toolOutput !== null) {\n      var outputValidation = validateToolOutput(openai.toolOutput, 'openai.toolOutput');\n      if (!outputValidation.isInitial) {\n        log('info', 'Using toolOutput', {\n          valid: outputValidation.valid,\n          errors: outputValidation.errors\n        });\n        setData(openai.toolOutput);\n        return true;\n      }\n    }\n\n    log('info', 'checkOpenAIData: no data found yet');\n    return false;\n  }\n\n  function installPropertyInterceptor(obj, prop, onSet) {\n    var current = obj[prop];\n    var descriptor = Object.getOwnPropertyDescriptor(obj, prop);\n\n    // Don't re-intercept\n    if (descriptor && descriptor.get && descriptor.set) return;\n\n    Object.defineProperty(obj, prop, {\n      get: function() { return current; },\n      set: function(val) {\n        current = val;\n        onSet(val);\n      },\n      enumerable: true,\n      configurable: true\n    });\n  }\n\n  function installOpenAIInterceptors(openai) {\n    if (!openai || openaiIntercepted) return;\n    openaiIntercepted = true;\n\n    // Check existing data first\n    if (checkOpenAIData(openai)) return;\n\n    // Intercept toolOutput\n    installPropertyInterceptor(openai, 'toolOutput', function(val) {\n      checkOpenAIData(openai);\n    });\n\n    // Intercept toolResponseMetadata\n    installPropertyInterceptor(openai, 'toolResponseMetadata', function(val) {\n      checkOpenAIData(openai);\n    });\n  }\n\n  // Install interceptor on window.openai\n  if (typeof window.openai !== 'undefined') {\n    installOpenAIInterceptors(window.openai);\n  } else {\n    // OpenAI object doesn't exist yet - wait for it\n    var pendingOpenai = undefined;\n    Object.defineProperty(window, 'openai', {\n      get: function() { return pendingOpenai; },\n      set: function(val) {\n        pendingOpenai = val;\n        if (val) installOpenAIInterceptors(val);\n      },\n      enumerable: true,\n      configurable: true\n    });\n  }\n\n  // ============================================\n  // MCP/Generic Platform Support\n  // ============================================\n\n  // Check for existing __frontmcp.toolOutput\n  if (window.__frontmcp && window.__frontmcp.toolOutput !== undefined) {\n    setData(window.__frontmcp.toolOutput);\n  }\n\n  // Check for __mcpToolOutput\n  if (window.__mcpToolOutput !== undefined && window.__mcpToolOutput !== null) {\n    setData(window.__mcpToolOutput);\n  }\n\n  // Check for __mcpResponseMeta\n  if (window.__mcpResponseMeta && window.__mcpResponseMeta['ui/html']) {\n    setData(window.__mcpResponseMeta['ui/html']);\n  }\n\n  // ============================================\n  // Bridge API\n  // ============================================\n\n  window.__frontmcp = window.__frontmcp || {};\n\n  window.__frontmcp.bridge = {\n    getState: function() { return state; },\n\n    // React useSyncExternalStore compatible\n    getSnapshot: function() { return state; },\n    getServerSnapshot: function() { return { data: null, loading: true, error: null }; },\n\n    subscribe: function(callback) {\n      subscribers.push(callback);\n      return function() {\n        var idx = subscribers.indexOf(callback);\n        if (idx > -1) subscribers.splice(idx, 1);\n      };\n    },\n\n    hasData: function() { return !state.loading && state.data !== null; },\n\n    // Manual control (for testing/custom injection)\n    setData: setData,\n    setError: setError,\n    reset: reset,\n\n    // Debug API\n    debug: {\n      getLogs: function() { return debugLog.slice(); },\n      getLastErrors: function() {\n        return debugLog.filter(function(e) { return e.level === 'error' || e.level === 'warn'; });\n      },\n      enableDebug: function() {\n        DEBUG = true;\n        window.localStorage.setItem('frontmcp_debug', '1');\n        console.log('[frontmcp] Debug mode enabled. Reload page to see all logs.');\n      },\n      disableDebug: function() {\n        DEBUG = false;\n        window.localStorage.removeItem('frontmcp_debug');\n      },\n      isDebugEnabled: function() { return DEBUG; },\n      getStateHistory: function() {\n        return {\n          current: state,\n          version: stateVersion,\n          subscriberCount: subscribers.length,\n          openaiIntercepted: openaiIntercepted,\n          pollCount: pollCount\n        };\n      },\n      dumpAll: function() {\n        console.group('[frontmcp] Debug Dump');\n        console.log('State:', state);\n        console.log('Version:', stateVersion);\n        console.log('Subscribers:', subscribers.length);\n        console.log('OpenAI Intercepted:', openaiIntercepted);\n        console.log('Poll Count:', pollCount);\n        console.log('Debug Logs:', debugLog);\n        console.groupEnd();\n        return {\n          state: state,\n          logs: debugLog,\n          version: stateVersion,\n          openaiIntercepted: openaiIntercepted\n        };\n      }\n    }\n  };\n\n  // ============================================\n  // Fallback Polling (for platforms that don't trigger setters)\n  // ============================================\n\n  var pollCount = 0;\n  var maxPolls = 30;  // ~3 seconds with exponential backoff\n\n  function pollForData() {\n    if (state.data !== null || pollCount >= maxPolls) return;\n    pollCount++;\n\n    // Check all sources\n    if (window.openai) {\n      if (checkOpenAIData(window.openai)) return;\n    }\n\n    // Use getToolOutput if available\n    if (window.__frontmcp.getToolOutput) {\n      var data = window.__frontmcp.getToolOutput();\n      if (data !== undefined && data !== null) {\n        setData(data);\n        return;\n      }\n    }\n\n    // Exponential backoff: 50ms, 75ms, 112ms, ...\n    var delay = Math.min(50 * Math.pow(1.5, Math.min(pollCount, 10)), 500);\n    setTimeout(pollForData, delay);\n  }\n\n  // Start polling after a brief delay (give interceptors time to fire)\n  setTimeout(pollForData, 50);\n})();\n</script>`;\n}\n\n/**\n * Generate TypeScript types for the bridge (for documentation/IDE support).\n */\nexport const BRIDGE_TYPES = `\ninterface BridgeState<T = unknown> {\n  data: T | null;\n  loading: boolean;\n  error: string | null;\n}\n\ninterface PlatformBridge<T = unknown> {\n  getState(): BridgeState<T>;\n  subscribe(callback: () => void): () => void;\n  getSnapshot(): BridgeState<T>;\n  getServerSnapshot(): BridgeState<T>;\n  hasData(): boolean;\n  setData(data: T): void;\n  setError(error: string): void;\n  reset(): void;\n}\n\ndeclare global {\n  interface Window {\n    __frontmcp: {\n      bridge: PlatformBridge;\n      // ... other __frontmcp methods\n    };\n  }\n}\n`;\n"]}