@frontmcp/ui 0.5.1 → 0.6.0

package/esm/base-template/index.js

@@ -0,0 +1,1364 @@
+// libs/ui/src/theme/cdn.ts
+var CDN = {
+  /**
+   * Tailwind CSS v4 Browser CDN
+   * Generates styles on-the-fly with @theme support
+   * @see https://tailwindcss.com/docs/installation/play-cdn
+   */
+  tailwind: "https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4",
+  /**
+   * HTMX 2.x - High power tools for HTML
+   * Enables AJAX, WebSockets, Server Sent Events directly in HTML
+   * @see https://htmx.org
+   */
+  htmx: {
+    url: "https://cdnjs.cloudflare.com/ajax/libs/htmx/2.0.7/htmx.min.js",
+    integrity: "sha512-T6VLg/MJYMbLTmQ8VLvonbWg8VOvmDhXcOvHzCwo6ShdGuUU5SEcp1IAPXL4k9lVoMi8gRXl5K/S/zh43Y9rJA=="
+  },
+  /**
+   * Alpine.js - Lightweight reactive framework
+   * Used for more complex client-side interactions
+   * @see https://alpinejs.dev
+   */
+  alpine: {
+    url: "https://cdn.jsdelivr.net/npm/alpinejs@3.14.3/dist/cdn.min.js",
+    integrity: "sha384-6zY8MFQJ/EqS1r4RJl+7j8rvZPuBWpT0RzWf+IFcKhxqUzQNmJzA1X1VEVZhYaEz"
+  },
+  /**
+   * Google Fonts - Inter for modern UI typography
+   */
+  fonts: {
+    preconnect: ["https://fonts.googleapis.com", "https://fonts.gstatic.com"],
+    inter: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
+    mono: "https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&display=swap"
+  },
+  /**
+   * Lucide Icons - Beautiful & consistent icons
+   * @see https://lucide.dev
+   */
+  icons: {
+    url: "https://cdn.jsdelivr.net/npm/lucide@0.294.0/dist/umd/lucide.min.js",
+    integrity: "sha384-wpLmHb7v7V1LsEuTmPQ9tXqWZvTtRWWVqJuE+Yz6X0I6O2T6bHJVeXH1lVWqF4qE"
+  }
+};
+var scriptCache = /* @__PURE__ */ new Map();
+function getCachedScript(url) {
+  return scriptCache.get(url);
+}
+function isScriptCached(url) {
+  return scriptCache.has(url);
+}
+function buildScriptTag(url, integrity, options = {}) {
+  const attrs = [`src="${url}"`];
+  if (integrity) {
+    attrs.push(`integrity="${integrity}"`);
+    attrs.push('crossorigin="anonymous"');
+  }
+  if (options.defer) attrs.push("defer");
+  if (options.async) attrs.push("async");
+  return `<script ${attrs.join(" ")}></script>`;
+}
+function buildInlineScriptTag(content) {
+  return `<script>${content}</script>`;
+}
+function buildFontPreconnectFromTheme(theme) {
+  const preconnect = theme.cdn?.fonts?.preconnect ?? CDN.fonts.preconnect;
+  return preconnect.map((url, i) => `<link rel="preconnect" href="${url}"${i > 0 ? " crossorigin" : ""}>`).join("\n  ");
+}
+function buildFontStylesheetsFromTheme(theme) {
+  const stylesheets = theme.cdn?.fonts?.stylesheets ?? [CDN.fonts.inter];
+  return stylesheets.map((url) => `<link href="${url}" rel="stylesheet">`).join("\n  ");
+}
+function buildCdnScriptsFromTheme(theme, options = {}) {
+  const { tailwind = true, htmx = true, alpine = false, icons = false, inline = false } = options;
+  const scripts = [];
+  const tailwindUrl = theme.cdn?.scripts?.tailwind ?? CDN.tailwind;
+  const htmxConfig = theme.cdn?.scripts?.htmx ?? CDN.htmx;
+  const alpineConfig = theme.cdn?.scripts?.alpine ?? CDN.alpine;
+  const iconsConfig = theme.cdn?.icons?.script ?? CDN.icons;
+  if (inline) {
+    if (tailwind) {
+      if (isScriptCached(tailwindUrl)) {
+        scripts.push(buildInlineScriptTag(getCachedScript(tailwindUrl)));
+      } else {
+        console.warn(
+          "[frontmcp/ui] Inline mode requested but Tailwind script not cached. Call fetchAndCacheScriptsFromTheme() first."
+        );
+      }
+    }
+    if (htmx) {
+      if (isScriptCached(htmxConfig.url)) {
+        scripts.push(buildInlineScriptTag(getCachedScript(htmxConfig.url)));
+      } else {
+        console.warn(
+          "[frontmcp/ui] Inline mode requested but HTMX script not cached. Call fetchAndCacheScriptsFromTheme() first."
+        );
+      }
+    }
+    if (alpine) {
+      if (isScriptCached(alpineConfig.url)) {
+        scripts.push(buildInlineScriptTag(getCachedScript(alpineConfig.url)));
+      } else {
+        console.warn(
+          "[frontmcp/ui] Inline mode requested but Alpine.js script not cached. Call fetchAndCacheScriptsFromTheme() first."
+        );
+      }
+    }
+    if (icons) {
+      if (isScriptCached(iconsConfig.url)) {
+        scripts.push(buildInlineScriptTag(getCachedScript(iconsConfig.url)));
+      } else {
+        console.warn(
+          "[frontmcp/ui] Inline mode requested but icons script not cached. Call fetchAndCacheScriptsFromTheme() first."
+        );
+      }
+    }
+  } else {
+    if (tailwind) {
+      scripts.push(buildScriptTag(tailwindUrl));
+    }
+    if (htmx) {
+      scripts.push(buildScriptTag(htmxConfig.url, htmxConfig.integrity));
+    }
+    if (alpine) {
+      scripts.push(buildScriptTag(alpineConfig.url, alpineConfig.integrity, { defer: true }));
+    }
+    if (icons) {
+      scripts.push(buildScriptTag(iconsConfig.url, iconsConfig.integrity));
+    }
+  }
+  return scripts.join("\n  ");
+}
+
+// libs/ui/src/theme/platforms.ts
+var CLAUDE_PLATFORM = {
+  id: "claude",
+  name: "Claude (Artifacts)",
+  supportsWidgets: true,
+  supportsTailwind: true,
+  supportsHtmx: false,
+  // Network blocked, HTMX won't work for API calls
+  networkMode: "blocked",
+  scriptStrategy: "inline",
+  maxInlineSize: 100 * 1024,
+  // 100KB limit for artifacts
+  cspRestrictions: ["script-src 'unsafe-inline'", "connect-src 'none'"],
+  options: {
+    mode: "artifacts",
+    framework: "react"
+    // Claude artifacts prefer React
+  }
+};
+
+// libs/ui/src/theme/presets/github-openai.ts
+var GITHUB_OPENAI_THEME = {
+  name: "github-openai",
+  colors: {
+    semantic: {
+      // Primary: Near-black for main actions and branding
+      primary: "#24292f",
+      // Secondary: Medium gray for secondary elements
+      secondary: "#57606a",
+      // Accent: Blue for links, focus states, and highlights
+      accent: "#0969da",
+      // Status colors
+      success: "#1a7f37",
+      // GitHub green
+      warning: "#9a6700",
+      // Amber warning
+      danger: "#cf222e",
+      // GitHub red
+      info: "#0969da"
+      // Blue info
+    },
+    surface: {
+      // Pure white background
+      background: "#ffffff",
+      // Light gray surface (GitHub code background style)
+      surface: "#f6f8fa",
+      // White elevated surfaces (modals, cards)
+      elevated: "#ffffff",
+      // Dark semi-transparent overlay
+      overlay: "rgba(27, 31, 36, 0.5)"
+    },
+    text: {
+      // Near-black for primary text
+      primary: "#24292f",
+      // Gray for secondary/muted text
+      secondary: "#57606a",
+      // Light gray for disabled text
+      disabled: "#8c959f",
+      // White for text on dark backgrounds
+      inverse: "#ffffff",
+      // Blue for links
+      link: "#0969da"
+    },
+    border: {
+      // Light gray border (GitHub style)
+      default: "#d0d7de",
+      // Medium gray on hover
+      hover: "#8c959f",
+      // Blue focus ring
+      focus: "#0969da",
+      // Subtle divider
+      divider: "#d8dee4"
+    }
+  },
+  typography: {
+    families: {
+      // System UI font stack (GitHub/Apple style)
+      sans: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"',
+      // Monospace stack
+      mono: 'ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, "Liberation Mono", monospace'
+    },
+    sizes: {
+      xs: "0.75rem",
+      // 12px
+      sm: "0.875rem",
+      // 14px
+      base: "1rem",
+      // 16px
+      lg: "1.125rem",
+      // 18px
+      xl: "1.25rem",
+      // 20px
+      "2xl": "1.5rem",
+      // 24px
+      "3xl": "1.875rem",
+      // 30px
+      "4xl": "2.25rem"
+      // 36px
+    },
+    weights: {
+      normal: "400",
+      medium: "500",
+      semibold: "600",
+      bold: "700"
+    }
+  },
+  radius: {
+    none: "0",
+    sm: "3px",
+    // GitHub uses smaller radii
+    md: "6px",
+    lg: "8px",
+    xl: "12px",
+    "2xl": "16px",
+    full: "9999px"
+  },
+  shadows: {
+    // Subtle shadows with gray tones
+    sm: "0 1px 0 rgba(27, 31, 36, 0.04)",
+    md: "0 3px 6px rgba(140, 149, 159, 0.15)",
+    lg: "0 8px 24px rgba(140, 149, 159, 0.2)",
+    xl: "0 12px 28px rgba(140, 149, 159, 0.3)"
+  },
+  components: {
+    button: {
+      radius: "6px",
+      paddingX: "16px",
+      paddingY: "5px",
+      fontSize: "14px",
+      fontWeight: "500"
+    },
+    card: {
+      radius: "6px",
+      padding: "16px",
+      shadow: "0 1px 0 rgba(27, 31, 36, 0.04)",
+      borderWidth: "1px"
+    },
+    input: {
+      radius: "6px",
+      paddingX: "12px",
+      paddingY: "5px",
+      borderWidth: "1px",
+      focusRingWidth: "3px"
+    }
+  },
+  cdn: {
+    fonts: {
+      preconnect: ["https://fonts.googleapis.com", "https://fonts.gstatic.com"],
+      stylesheets: [
+        // System UI fonts don't need external stylesheets, but we include
+        // Inter as an optional enhancement for consistent cross-platform rendering
+        "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+      ]
+    },
+    icons: {
+      script: {
+        url: "https://cdn.jsdelivr.net/npm/lucide@0.294.0/dist/umd/lucide.min.js"
+      }
+    },
+    scripts: {
+      tailwind: "https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4",
+      htmx: {
+        url: "https://cdnjs.cloudflare.com/ajax/libs/htmx/2.0.7/htmx.min.js",
+        integrity: "sha512-T6VLg/MJYMbLTmQ8VLvonbWg8VOvmDhXcOvHzCwo6ShdGuUU5SEcp1IAPXL4k9lVoMi8gRXl5K/S/zh43Y9rJA=="
+      },
+      alpine: {
+        url: "https://cdn.jsdelivr.net/npm/alpinejs@3.14.3/dist/cdn.min.js",
+        integrity: "sha384-6zY8MFQJ/EqS1r4RJl+7j8rvZPuBWpT0RzWf+IFcKhxqUzQNmJzA1X1VEVZhYaEz"
+      }
+    }
+  }
+};
+var DEFAULT_THEME = GITHUB_OPENAI_THEME;
+
+// libs/ui/src/theme/theme.ts
+function emitColorScale(lines, name, scale) {
+  for (const [shade, value] of Object.entries(scale)) {
+    if (value) lines.push(`--color-${name}-${shade}: ${value};`);
+  }
+}
+function buildThemeCss(theme) {
+  const lines = [];
+  const semantic = theme.colors.semantic;
+  if (typeof semantic.primary === "string") {
+    lines.push(`--color-primary: ${semantic.primary};`);
+  } else if (semantic.primary) {
+    emitColorScale(lines, "primary", semantic.primary);
+  }
+  if (semantic.secondary) {
+    if (typeof semantic.secondary === "string") {
+      lines.push(`--color-secondary: ${semantic.secondary};`);
+    } else {
+      emitColorScale(lines, "secondary", semantic.secondary);
+    }
+  }
+  if (semantic.accent) {
+    if (typeof semantic.accent === "string") {
+      lines.push(`--color-accent: ${semantic.accent};`);
+    } else {
+      emitColorScale(lines, "accent", semantic.accent);
+    }
+  }
+  if (semantic.neutral) {
+    if (typeof semantic.neutral === "string") {
+      lines.push(`--color-neutral: ${semantic.neutral};`);
+    } else {
+      emitColorScale(lines, "neutral", semantic.neutral);
+    }
+  }
+  if (semantic.success) lines.push(`--color-success: ${semantic.success};`);
+  if (semantic.warning) lines.push(`--color-warning: ${semantic.warning};`);
+  if (semantic.danger) lines.push(`--color-danger: ${semantic.danger};`);
+  if (semantic.info) lines.push(`--color-info: ${semantic.info};`);
+  const surface = theme.colors.surface;
+  if (surface?.background) lines.push(`--color-background: ${surface.background};`);
+  if (surface?.surface) lines.push(`--color-surface: ${surface.surface};`);
+  if (surface?.elevated) lines.push(`--color-elevated: ${surface.elevated};`);
+  if (surface?.overlay) lines.push(`--color-overlay: ${surface.overlay};`);
+  const text = theme.colors.text;
+  if (text?.primary) lines.push(`--color-text-primary: ${text.primary};`);
+  if (text?.secondary) lines.push(`--color-text-secondary: ${text.secondary};`);
+  if (text?.disabled) lines.push(`--color-text-disabled: ${text.disabled};`);
+  if (text?.inverse) lines.push(`--color-text-inverse: ${text.inverse};`);
+  if (text?.link) lines.push(`--color-text-link: ${text.link};`);
+  const border = theme.colors.border;
+  if (border?.default) lines.push(`--color-border: ${border.default};`);
+  if (border?.hover) lines.push(`--color-border-hover: ${border.hover};`);
+  if (border?.focus) lines.push(`--color-border-focus: ${border.focus};`);
+  if (border?.divider) lines.push(`--color-divider: ${border.divider};`);
+  if (theme.colors.custom) {
+    for (const [key, value] of Object.entries(theme.colors.custom)) {
+      lines.push(`--color-${key}: ${value};`);
+    }
+  }
+  const typography = theme.typography;
+  if (typography?.families?.sans) lines.push(`--font-sans: ${typography.families.sans};`);
+  if (typography?.families?.serif) lines.push(`--font-serif: ${typography.families.serif};`);
+  if (typography?.families?.mono) lines.push(`--font-mono: ${typography.families.mono};`);
+  if (typography?.families?.display) lines.push(`--font-display: ${typography.families.display};`);
+  const radius = theme.radius;
+  if (radius?.none) lines.push(`--radius-none: ${radius.none};`);
+  if (radius?.sm) lines.push(`--radius-sm: ${radius.sm};`);
+  if (radius?.md) lines.push(`--radius-md: ${radius.md};`);
+  if (radius?.lg) lines.push(`--radius-lg: ${radius.lg};`);
+  if (radius?.xl) lines.push(`--radius-xl: ${radius.xl};`);
+  if (radius?.["2xl"]) lines.push(`--radius-2xl: ${radius["2xl"]};`);
+  if (radius?.full) lines.push(`--radius-full: ${radius.full};`);
+  if (theme.customVars) {
+    for (const [key, value] of Object.entries(theme.customVars)) {
+      lines.push(`${key}: ${value};`);
+    }
+  }
+  return lines.join("\n      ");
+}
+function buildStyleBlock(theme) {
+  const themeCss = buildThemeCss(theme);
+  const customCss = theme.customCss || "";
+  return `<style type="text/tailwindcss">
+    @theme {
+      ${themeCss}
+    }
+    ${customCss}
+  </style>`;
+}
+
+// libs/ui/src/base-template/theme-styles.ts
+function renderThemeStyles(options = {}) {
+  const {
+    theme = DEFAULT_THEME,
+    tailwind = true,
+    htmx = false,
+    alpine = false,
+    fonts = true,
+    inline = false
+  } = options;
+  const parts = [];
+  if (fonts && !inline) {
+    parts.push(buildFontPreconnectFromTheme(theme));
+  }
+  if (fonts && !inline) {
+    parts.push(buildFontStylesheetsFromTheme(theme));
+  }
+  const scriptOptions = {
+    tailwind,
+    htmx,
+    alpine,
+    inline
+  };
+  parts.push(buildCdnScriptsFromTheme(theme, scriptOptions));
+  parts.push(buildStyleBlock(theme));
+  return parts.filter(Boolean).join("\n  ");
+}
+function renderMinimalThemeStyles(theme = DEFAULT_THEME) {
+  return renderThemeStyles({
+    theme,
+    tailwind: true,
+    htmx: false,
+    alpine: false,
+    fonts: false,
+    inline: false
+  });
+}
+function renderThemeCssOnly(theme = DEFAULT_THEME) {
+  return buildStyleBlock(theme);
+}
+
+// libs/ui/src/base-template/polyfills.ts
+function renderMcpSessionPolyfill(mcpSession) {
+  const fallbackCode = mcpSession ? `
+      return {
+        mcpUrl: '${escapeJs(mcpSession.mcpUrl)}',
+        sessionId: '${escapeJs(mcpSession.sessionId)}'
+      };` : `
+      return null;`;
+  return `<script>
+(function() {
+  'use strict';
+
+  window.__frontmcp = window.__frontmcp || {};
+
+  /**
+   * Auto-detect MCP session from page context.
+   * Tries multiple sources in order of priority.
+   */
+  window.__frontmcp.detectMcpSession = function() {
+    // 1. Check if explicitly set by developer
+    if (window.__frontmcp.mcpSession) {
+      return window.__frontmcp.mcpSession;
+    }
+
+    // 2. Check meta tags
+    var mcpUrlMeta = document.querySelector('meta[name="mcp-url"]');
+    var sessionIdMeta = document.querySelector('meta[name="mcp-session-id"]');
+    if (mcpUrlMeta && sessionIdMeta) {
+      return {
+        mcpUrl: mcpUrlMeta.getAttribute('content'),
+        sessionId: sessionIdMeta.getAttribute('content')
+      };
+    }
+
+    // 3. Check URL query parameters (for ngrok/iframe scenarios)
+    try {
+      var params = new URLSearchParams(window.location.search);
+      var mcpUrl = params.get('mcpUrl');
+      var sessionId = params.get('sessionId');
+      if (mcpUrl && sessionId) {
+        return { mcpUrl: mcpUrl, sessionId: sessionId };
+      }
+    } catch (e) {
+      // URLSearchParams may not be available in all environments
+    }
+
+    // 4. Use explicit fallback if provided at render time
+    ${fallbackCode}
+  };
+
+  /**
+   * Enhanced callTool that uses HTTP fallback when MCP bridge is unavailable.
+   * This wraps window.mcpBridge.callTool with HTTP fallback support.
+   */
+  window.__frontmcp.callTool = async function(toolName, args) {
+    // Priority 1: Direct OpenAI SDK call (most reliable in OpenAI iframe)
+    if (typeof window !== 'undefined' && window.openai && typeof window.openai.callTool === 'function') {
+      return window.openai.callTool(toolName, args);
+    }
+
+    // Priority 2: If MCP bridge has callTool, use it
+    if (window.mcpBridge && typeof window.mcpBridge.callTool === 'function') {
+      try {
+        return await window.mcpBridge.callTool(toolName, args);
+      } catch (e) {
+        // If MCP bridge fails, fall through to HTTP fallback
+        console.warn('MCP bridge callTool failed, trying HTTP fallback:', e.message);
+      }
+    }
+
+    // Priority 3: HTTP fallback using detected session
+    var session = window.__frontmcp.detectMcpSession();
+    if (!session) {
+      throw new Error(
+        'MCP session not available. Set window.__frontmcp.mcpSession, ' +
+        'add meta tags, or provide URL parameters.'
+      );
+    }
+
+    var response = await fetch(session.mcpUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Session-Id': session.sessionId
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: { name: toolName, arguments: args || {} },
+        id: Date.now()
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error('HTTP ' + response.status + ': ' + response.statusText);
+    }
+
+    var result = await response.json();
+    if (result.error) {
+      throw new Error(result.error.message || 'Tool call failed');
+    }
+    return result.result;
+  };
+
+  /**
+   * Get tool output from all possible sources.
+   * Priority: pre-rendered HTML from metadata > structured data > raw output
+   *
+   * Note: Returns undefined for null values from OpenAI (which is its initial state)
+   * to allow proper loading state handling in the bridge.
+   */
+  window.__frontmcp.getToolOutput = function() {
+    // 1. Check for pre-rendered HTML in OpenAI toolResponseMetadata (highest priority)
+    // This is set when the tool has a UI template (React, HTML, etc.)
+    if (window.openai && window.openai.toolResponseMetadata) {
+      var html = window.openai.toolResponseMetadata['ui/html'];
+      if (html && typeof html === 'string') {
+        return html;  // Return HTML string directly
+      }
+    }
+
+    // 2. Check for pre-rendered HTML in MCP response metadata (for MCP Inspector, etc.)
+    if (window.__mcpResponseMeta) {
+      var mcpHtml = window.__mcpResponseMeta['ui/html'];
+      if (mcpHtml && typeof mcpHtml === 'string') {
+        return mcpHtml;  // Return HTML string directly
+      }
+    }
+
+    // 3. OpenAI injects structured data into window.openai.toolOutput
+    // Skip null - that's OpenAI's initial state before real data is injected
+    if (window.openai && window.openai.toolOutput !== undefined && window.openai.toolOutput !== null) {
+      return window.openai.toolOutput;
+    }
+
+    // 4. MCP Bridge stores in window.__mcpToolOutput (skip null)
+    if (window.__mcpToolOutput !== undefined && window.__mcpToolOutput !== null) {
+      return window.__mcpToolOutput;
+    }
+
+    // 5. Explicit injection
+    if (window.__frontmcp.toolOutput !== undefined) {
+      return window.__frontmcp.toolOutput;
+    }
+
+    return undefined;
+  };
+})();
+</script>`;
+}
+function escapeJs(str) {
+  return str.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/"/g, '\\"').replace(/`/g, "\\`").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/<\/script/gi, "<\\/script").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+
+// libs/ui/src/base-template/bridge.ts
+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>`;
+}
+var 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
+    };
+  }
+}
+`;
+
+// libs/ui/src/base-template/default-base-template.ts
+function escapeAttr(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function createDefaultBaseTemplate(options) {
+  const {
+    toolName,
+    theme = DEFAULT_THEME,
+    mcpSession,
+    htmx = false,
+    alpine = false,
+    fonts = true,
+    inline = false,
+    headContent = "",
+    bodyClass = "bg-transparent font-sans antialiased",
+    containerClass = "p-4"
+  } = options;
+  const themeStylesOptions = {
+    theme,
+    tailwind: true,
+    htmx,
+    alpine,
+    fonts,
+    inline
+  };
+  const themeStyles = renderThemeStyles(themeStylesOptions);
+  const polyfills = renderMcpSessionPolyfill(mcpSession);
+  const bridge = renderBridgeScript();
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light dark">
+  <title>${escapeAttr(toolName)} Widget</title>
+  ${themeStyles}
+  ${polyfills}
+  ${bridge}
+  ${headContent}
+</head>
+<body class="${escapeAttr(bodyClass)}">
+  <div id="widget-root" class="${escapeAttr(containerClass)}"></div>
+
+  <script>
+  (function() {
+    'use strict';
+
+    var root = document.getElementById('widget-root');
+
+    /**
+     * Render the widget based on bridge state.
+     * Uses the reactive bridge to automatically re-render when data changes.
+     */
+    function render() {
+      var state = window.__frontmcp.bridge.getState();
+
+      // Loading state
+      if (state.loading) {
+        root.innerHTML = renderLoading();
+        return;
+      }
+
+      // Error state
+      if (state.error) {
+        root.innerHTML = renderError(state.error);
+        return;
+      }
+
+      // No data state
+      if (state.data === null) {
+        root.innerHTML = renderEmpty();
+        return;
+      }
+
+      // Render data
+      try {
+        // Check for custom renderer provided by developer
+        if (window.__frontmcp && typeof window.__frontmcp.renderContent === 'function') {
+          root.innerHTML = window.__frontmcp.renderContent(state.data);
+          return;
+        }
+
+        // Fall back to default renderer
+        root.innerHTML = defaultRenderer(state.data);
+      } catch (e) {
+        console.error('[frontmcp] Error rendering widget:', e);
+        root.innerHTML = renderError(e.message || 'Render error');
+      }
+    }
+
+    /**
+     * Default renderer for tool output.
+     * Handles both pre-rendered HTML strings and raw JSON data.
+     */
+    function defaultRenderer(data) {
+      // Check if data is pre-rendered HTML (server-side rendered widget)
+      if (typeof data === 'string' && data.trim().startsWith('<')) {
+        // Direct HTML injection - content was already rendered/sanitized server-side
+        return data;
+      }
+
+      // Check for special wrapper with HTML content
+      if (data && typeof data === 'object' && data.__html) {
+        return data.__html;
+      }
+
+      // Fallback: JSON renderer for raw data
+      var json = JSON.stringify(data, null, 2);
+      return '<pre class="p-4 bg-surface rounded-md overflow-auto text-sm font-mono text-text-primary border border-border">' +
+        escapeHtml(json) +
+        '</pre>';
+    }
+
+    /**
+     * Render loading state with animated spinner.
+     */
+    function renderLoading() {
+      return '<div class="flex items-center justify-center p-8">' +
+        '<div class="flex flex-col items-center gap-3">' +
+        '<svg class="animate-spin h-8 w-8 text-blue-500" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">' +
+        '<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>' +
+        '<path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>' +
+        '</svg>' +
+        '<p class="text-text-secondary text-sm">Loading...</p>' +
+        '</div>' +
+        '</div>';
+    }
+
+    /**
+     * Render error message.
+     */
+    function renderError(message) {
+      return '<div class="p-4 bg-red-50 border border-red-200 rounded-md">' +
+        '<p class="text-red-600 text-sm">Error: ' + escapeHtml(message) + '</p>' +
+        '</div>';
+    }
+
+    /**
+     * Render empty state (no data available).
+     */
+    function renderEmpty() {
+      return '<div class="p-4 text-text-secondary text-sm text-center">' +
+        'No data available' +
+        '</div>';
+    }
+
+    /**
+     * Escape HTML special characters.
+     */
+    function escapeHtml(str) {
+      if (typeof str !== 'string') return str;
+      return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+    }
+
+    /**
+     * Create debug overlay panel.
+     * Shows bridge state, logs, and OpenAI data status.
+     */
+    function createDebugOverlay() {
+      var overlay = document.createElement('div');
+      overlay.id = 'frontmcp-debug-overlay';
+      overlay.style.cssText = 'position:fixed;bottom:10px;right:10px;width:400px;max-height:60vh;' +
+        'background:rgba(0,0,0,0.9);color:#0f0;font-family:monospace;font-size:11px;' +
+        'padding:10px;border-radius:4px;z-index:99999;overflow:auto;display:none;';
+
+      var toggle = document.createElement('button');
+      toggle.id = 'frontmcp-debug-toggle';
+      toggle.textContent = 'Debug';
+      toggle.style.cssText = 'position:fixed;bottom:10px;right:10px;padding:4px 8px;' +
+        'background:#333;color:#0f0;font-family:monospace;font-size:10px;border:1px solid #0f0;' +
+        'border-radius:4px;z-index:100000;cursor:pointer;';
+
+      toggle.onclick = function() {
+        var o = document.getElementById('frontmcp-debug-overlay');
+        if (o.style.display === 'none') {
+          o.style.display = 'block';
+          toggle.style.right = '420px';
+          updateDebugOverlay();
+        } else {
+          o.style.display = 'none';
+          toggle.style.right = '10px';
+        }
+      };
+
+      document.body.appendChild(overlay);
+      document.body.appendChild(toggle);
+
+      // Auto-update every second
+      setInterval(updateDebugOverlay, 1000);
+    }
+
+    function updateDebugOverlay() {
+      var overlay = document.getElementById('frontmcp-debug-overlay');
+      if (!overlay || overlay.style.display === 'none') return;
+
+      var state = window.__frontmcp.bridge.getState();
+      var debug = window.__frontmcp.bridge.debug;
+      var logs = debug.getLogs();
+      var errors = debug.getLastErrors();
+      var stateHistory = debug.getStateHistory();
+
+      var html = '<div style="margin-bottom:10px;border-bottom:1px solid #333;padding-bottom:5px;">' +
+        '<strong>FrontMCP Debug Panel</strong>' +
+        '<span style="float:right;color:#666;">v' + stateHistory.version + '</span>' +
+        '</div>';
+
+      // Bridge State
+      html += '<div style="margin-bottom:10px;">' +
+        '<div style="color:#ff0;">Bridge State:</div>' +
+        '<div>Loading: ' + state.loading + '</div>' +
+        '<div>Has Data: ' + (state.data !== null) + '</div>' +
+        '<div>Data Type: ' + (state.data === null ? 'null' : typeof state.data) + '</div>' +
+        (typeof state.data === 'string' ? '<div>Data Length: ' + state.data.length + '</div>' : '') +
+        '<div>Error: ' + (state.error || 'none') + '</div>' +
+        '</div>';
+
+      // OpenAI Status
+      html += '<div style="margin-bottom:10px;">' +
+        '<div style="color:#ff0;">OpenAI Status:</div>' +
+        '<div>Intercepted: ' + stateHistory.openaiIntercepted + '</div>' +
+        '<div>Poll Count: ' + stateHistory.pollCount + '</div>';
+
+      if (window.openai) {
+        html += '<div>window.openai: exists</div>' +
+          '<div>toolOutput: ' + (window.openai.toolOutput !== undefined ? 'present' : 'undefined') + '</div>' +
+          '<div>toolResponseMetadata: ' + (window.openai.toolResponseMetadata !== undefined ? 'present' : 'undefined') + '</div>';
+        if (window.openai.toolResponseMetadata) {
+          html += '<div>meta keys: ' + Object.keys(window.openai.toolResponseMetadata).join(', ') + '</div>';
+        }
+      } else {
+        html += '<div>window.openai: undefined</div>';
+      }
+      html += '</div>';
+
+      // Errors
+      if (errors.length > 0) {
+        html += '<div style="margin-bottom:10px;">' +
+          '<div style="color:#f00;">Errors (' + errors.length + '):</div>';
+        errors.slice(-5).forEach(function(e) {
+          html += '<div style="color:#f88;font-size:10px;">[' + e.level + '] ' + escapeHtml(e.message) + '</div>';
+        });
+        html += '</div>';
+      }
+
+      // Recent Logs
+      html += '<div>' +
+        '<div style="color:#ff0;">Recent Logs (' + logs.length + '):</div>' +
+        '<div style="max-height:150px;overflow:auto;">';
+      logs.slice(-10).forEach(function(e) {
+        var color = e.level === 'error' ? '#f00' : e.level === 'warn' ? '#ff0' : '#0f0';
+        html += '<div style="color:' + color + ';font-size:10px;">' +
+          '[' + e.ts.split('T')[1].split('.')[0] + '] ' + escapeHtml(e.message) +
+          '</div>';
+      });
+      html += '</div></div>';
+
+      // Actions
+      html += '<div style="margin-top:10px;border-top:1px solid #333;padding-top:5px;">' +
+        '<button onclick="console.log(window.__frontmcp.bridge.debug.dumpAll())" ' +
+        'style="font-size:10px;padding:2px 6px;margin-right:5px;">Dump to Console</button>' +
+        '<button onclick="window.__frontmcp.bridge.reset()" ' +
+        'style="font-size:10px;padding:2px 6px;">Reset Bridge</button>' +
+        '</div>';
+
+      overlay.innerHTML = html;
+    }
+
+    /**
+     * Initialize the widget with reactive rendering.
+     */
+    function init() {
+      // Subscribe to bridge state changes for reactive re-rendering
+      window.__frontmcp.bridge.subscribe(render);
+
+      // Initial render
+      render();
+
+      // Global click handler for SSR-compatible tool calls
+      // Handles buttons/elements with data-tool-call attribute
+      document.addEventListener('click', function(e) {
+        var target = e.target;
+        // Walk up the DOM to find element with data-tool-call (handles clicks on child elements)
+        while (target && target !== document.body) {
+          if (target.hasAttribute && target.hasAttribute('data-tool-call')) {
+            var toolName = target.getAttribute('data-tool-call');
+            var argsStr = target.getAttribute('data-tool-args');
+            var args = {};
+
+            if (argsStr) {
+              try {
+                args = JSON.parse(argsStr);
+              } catch (parseErr) {
+                console.error('[frontmcp] Failed to parse data-tool-args:', parseErr);
+              }
+            }
+
+            // Prevent default behavior and stop propagation
+            e.preventDefault();
+            e.stopPropagation();
+
+            // Show loading state on the button
+            var originalContent = target.innerHTML;
+            var loadingContent = '<span style="display:inline-flex;align-items:center;">' +
+              '<span style="animation:spin 1s linear infinite;margin-right:4px;">\u23F3</span>' +
+              'Loading...' +
+              '</span>';
+            target.innerHTML = loadingContent;
+            target.disabled = true;
+
+            // Call the tool
+            if (window.__frontmcp && typeof window.__frontmcp.callTool === 'function') {
+              window.__frontmcp.callTool(toolName, args)
+                .then(function(result) {
+                  console.log('[frontmcp] Tool call success:', toolName, result);
+                  // Restore button state on success
+                  target.innerHTML = originalContent;
+                  target.disabled = false;
+                })
+                .catch(function(err) {
+                  console.error('[frontmcp] Tool call failed:', toolName, err);
+                  // Restore button state on error
+                  target.innerHTML = originalContent;
+                  target.disabled = false;
+                });
+            } else {
+              console.error('[frontmcp] callTool not available');
+              target.innerHTML = originalContent;
+              target.disabled = false;
+            }
+
+            return;
+          }
+          target = target.parentElement;
+        }
+      });
+
+      // Create debug overlay if debug mode is enabled
+      var DEBUG = window.location.search.indexOf('frontmcp_debug=1') > -1 ||
+                  window.localStorage.getItem('frontmcp_debug') === '1';
+      if (DEBUG) {
+        createDebugOverlay();
+      }
+    }
+
+    // Initialize when DOM is ready
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', init);
+    } else {
+      init();
+    }
+  })();
+  </script>
+</body>
+</html>`;
+}
+function createMinimalBaseTemplate(toolName, mcpSession) {
+  return createDefaultBaseTemplate({
+    toolName,
+    mcpSession,
+    fonts: false,
+    htmx: false,
+    alpine: false
+  });
+}
+export {
+  BRIDGE_TYPES,
+  createDefaultBaseTemplate,
+  createMinimalBaseTemplate,
+  renderBridgeScript,
+  renderMcpSessionPolyfill,
+  renderMinimalThemeStyles,
+  renderThemeCssOnly,
+  renderThemeStyles
+};