@frontmcp/ui 0.5.0

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

@@ -0,0 +1,91 @@
+/**
+ * Default Base Template for Tool UI
+ *
+ * Provides a generic HTML wrapper for tool output widgets that:
+ * 1. Includes theming (Tailwind CSS with @theme)
+ * 2. Includes platform polyfills (callTool, detectMcpSession)
+ * 3. Polls for toolOutput from window.openai or window.__frontmcp
+ * 4. Renders content via window.__frontmcp.renderContent or default JSON renderer
+ *
+ * This template is platform-agnostic and works with:
+ * - OpenAI Apps SDK (window.openai.toolOutput)
+ * - Claude Artifacts
+ * - Custom hosts using MCP protocol
+ * - ngrok/iframe scenarios
+ */
+import { type ThemeConfig } from '../theme';
+import { type McpSession } from './polyfills';
+/**
+ * Options for creating a default base template.
+ */
+export interface BaseTemplateOptions {
+    /** Tool name for identification */
+    toolName: string;
+    /** Theme configuration */
+    theme?: ThemeConfig;
+    /** MCP session info for callTool polyfill fallback */
+    mcpSession?: McpSession;
+    /** Include HTMX (default: false) */
+    htmx?: boolean;
+    /** Include Alpine.js (default: false) */
+    alpine?: boolean;
+    /** Include fonts (default: true) */
+    fonts?: boolean;
+    /** Use inline scripts (for blocked network platforms) */
+    inline?: boolean;
+    /**
+     * Additional head content (scripts, meta tags).
+     * @warning This content is injected WITHOUT escaping. Only use with trusted content.
+     */
+    headContent?: string;
+    /** Custom body classes */
+    bodyClass?: string;
+    /** Custom widget container classes */
+    containerClass?: string;
+}
+/**
+ * Create a default base template for tool UI widgets.
+ *
+ * This generates a complete HTML document that:
+ * 1. Loads Tailwind CSS with theme configuration
+ * 2. Injects platform polyfills (callTool, detectMcpSession, getToolOutput)
+ * 3. Waits for toolOutput to be injected
+ * 4. Renders content using window.__frontmcp.renderContent or default JSON renderer
+ *
+ * @param options - Base template configuration
+ * @returns Complete HTML document string
+ *
+ * @example Basic usage
+ * ```typescript
+ * const html = createDefaultBaseTemplate({ toolName: 'get_weather' });
+ * ```
+ *
+ * @example With custom theme and MCP session
+ * ```typescript
+ * const html = createDefaultBaseTemplate({
+ *   toolName: 'get_weather',
+ *   theme: customTheme,
+ *   mcpSession: { mcpUrl: 'https://mcp.example.com', sessionId: 'abc123' },
+ * });
+ * ```
+ *
+ * @example For Claude Artifacts (inline scripts)
+ * ```typescript
+ * await fetchAndCacheScriptsFromTheme(theme);
+ * const html = createDefaultBaseTemplate({
+ *   toolName: 'get_weather',
+ *   inline: true,
+ * });
+ * ```
+ */
+export declare function createDefaultBaseTemplate(options: BaseTemplateOptions): string;
+/**
+ * Create a minimal base template without fonts.
+ *
+ * Use this for lightweight widgets or when fonts are loaded elsewhere.
+ *
+ * @param toolName - Tool name for identification
+ * @param mcpSession - Optional MCP session info
+ * @returns Complete HTML document string
+ */
+export declare function createMinimalBaseTemplate(toolName: string, mcpSession?: McpSession): string;

package/src/base-template/default-base-template.js

@@ -0,0 +1,435 @@
+"use strict";
+/**
+ * Default Base Template for Tool UI
+ *
+ * Provides a generic HTML wrapper for tool output widgets that:
+ * 1. Includes theming (Tailwind CSS with @theme)
+ * 2. Includes platform polyfills (callTool, detectMcpSession)
+ * 3. Polls for toolOutput from window.openai or window.__frontmcp
+ * 4. Renders content via window.__frontmcp.renderContent or default JSON renderer
+ *
+ * This template is platform-agnostic and works with:
+ * - OpenAI Apps SDK (window.openai.toolOutput)
+ * - Claude Artifacts
+ * - Custom hosts using MCP protocol
+ * - ngrok/iframe scenarios
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultBaseTemplate = createDefaultBaseTemplate;
+exports.createMinimalBaseTemplate = createMinimalBaseTemplate;
+const theme_1 = require("../theme");
+const theme_styles_1 = require("./theme-styles");
+const polyfills_1 = require("./polyfills");
+const bridge_1 = require("./bridge");
+/**
+ * Escape string for use in HTML attributes.
+ */
+function escapeAttr(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/'/g, ''')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/**
+ * Create a default base template for tool UI widgets.
+ *
+ * This generates a complete HTML document that:
+ * 1. Loads Tailwind CSS with theme configuration
+ * 2. Injects platform polyfills (callTool, detectMcpSession, getToolOutput)
+ * 3. Waits for toolOutput to be injected
+ * 4. Renders content using window.__frontmcp.renderContent or default JSON renderer
+ *
+ * @param options - Base template configuration
+ * @returns Complete HTML document string
+ *
+ * @example Basic usage
+ * ```typescript
+ * const html = createDefaultBaseTemplate({ toolName: 'get_weather' });
+ * ```
+ *
+ * @example With custom theme and MCP session
+ * ```typescript
+ * const html = createDefaultBaseTemplate({
+ *   toolName: 'get_weather',
+ *   theme: customTheme,
+ *   mcpSession: { mcpUrl: 'https://mcp.example.com', sessionId: 'abc123' },
+ * });
+ * ```
+ *
+ * @example For Claude Artifacts (inline scripts)
+ * ```typescript
+ * await fetchAndCacheScriptsFromTheme(theme);
+ * const html = createDefaultBaseTemplate({
+ *   toolName: 'get_weather',
+ *   inline: true,
+ * });
+ * ```
+ */
+function createDefaultBaseTemplate(options) {
+    const { toolName, theme = theme_1.DEFAULT_THEME, mcpSession, htmx = false, alpine = false, fonts = true, inline = false, headContent = '', bodyClass = 'bg-transparent font-sans antialiased', containerClass = 'p-4', } = options;
+    // Build theme styles (fonts, scripts, @theme CSS)
+    const themeStylesOptions = {
+        theme,
+        tailwind: true,
+        htmx,
+        alpine,
+        fonts,
+        inline,
+    };
+    const themeStyles = (0, theme_styles_1.renderThemeStyles)(themeStylesOptions);
+    // Build MCP session polyfill (detectMcpSession, callTool, getToolOutput)
+    const polyfills = (0, polyfills_1.renderMcpSessionPolyfill)(mcpSession);
+    // Build reactive bridge (handles data injection and re-rendering)
+    const bridge = (0, bridge_1.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;">⏳</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>`;
+}
+/**
+ * Create a minimal base template without fonts.
+ *
+ * Use this for lightweight widgets or when fonts are loaded elsewhere.
+ *
+ * @param toolName - Tool name for identification
+ * @param mcpSession - Optional MCP session info
+ * @returns Complete HTML document string
+ */
+function createMinimalBaseTemplate(toolName, mcpSession) {
+    return createDefaultBaseTemplate({
+        toolName,
+        mcpSession,
+        fonts: false,
+        htmx: false,
+        alpine: false,
+    });
+}
+//# sourceMappingURL=default-base-template.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default-base-template.js","sourceRoot":"","sources":["../../../src/base-template/default-base-template.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAmFH,8DAyWC;AAWD,8DAQC;AA7cD,oCAA2D;AAC3D,iDAA4E;AAC5E,2CAAwE;AACxE,qCAA8C;AA+B9C;;GAEG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,GAAG;SACP,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,SAAgB,yBAAyB,CAAC,OAA4B;IACpE,MAAM,EACJ,QAAQ,EACR,KAAK,GAAG,qBAAa,EACrB,UAAU,EACV,IAAI,GAAG,KAAK,EACZ,MAAM,GAAG,KAAK,EACd,KAAK,GAAG,IAAI,EACZ,MAAM,GAAG,KAAK,EACd,WAAW,GAAG,EAAE,EAChB,SAAS,GAAG,sCAAsC,EAClD,cAAc,GAAG,KAAK,GACvB,GAAG,OAAO,CAAC;IAEZ,kDAAkD;IAClD,MAAM,kBAAkB,GAAuB;QAC7C,KAAK;QACL,QAAQ,EAAE,IAAI;QACd,IAAI;QACJ,MAAM;QACN,KAAK;QACL,MAAM;KACP,CAAC;IACF,MAAM,WAAW,GAAG,IAAA,gCAAiB,EAAC,kBAAkB,CAAC,CAAC;IAE1D,yEAAyE;IACzE,MAAM,SAAS,GAAG,IAAA,oCAAwB,EAAC,UAAU,CAAC,CAAC;IAEvD,kEAAkE;IAClE,MAAM,MAAM,GAAG,IAAA,2BAAkB,GAAE,CAAC;IAEpC,OAAO;;;;;;WAME,UAAU,CAAC,QAAQ,CAAC;IAC3B,WAAW;IACX,SAAS;IACT,MAAM;IACN,WAAW;;eAEA,UAAU,CAAC,SAAS,CAAC;iCACH,UAAU,CAAC,cAAc,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA4TnD,CAAC;AACT,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,yBAAyB,CAAC,QAAgB,EAAE,UAAuB;IACjF,OAAO,yBAAyB,CAAC;QAC/B,QAAQ;QACR,UAAU;QACV,KAAK,EAAE,KAAK;QACZ,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Default Base Template for Tool UI\n *\n * Provides a generic HTML wrapper for tool output widgets that:\n * 1. Includes theming (Tailwind CSS with @theme)\n * 2. Includes platform polyfills (callTool, detectMcpSession)\n * 3. Polls for toolOutput from window.openai or window.__frontmcp\n * 4. Renders content via window.__frontmcp.renderContent or default JSON renderer\n *\n * This template is platform-agnostic and works with:\n * - OpenAI Apps SDK (window.openai.toolOutput)\n * - Claude Artifacts\n * - Custom hosts using MCP protocol\n * - ngrok/iframe scenarios\n */\n\nimport { DEFAULT_THEME, type ThemeConfig } from '../theme';\nimport { renderThemeStyles, type ThemeStylesOptions } from './theme-styles';\nimport { renderMcpSessionPolyfill, type McpSession } from './polyfills';\nimport { renderBridgeScript } from './bridge';\n\n/**\n * Options for creating a default base template.\n */\nexport interface BaseTemplateOptions {\n  /** Tool name for identification */\n  toolName: string;\n  /** Theme configuration */\n  theme?: ThemeConfig;\n  /** MCP session info for callTool polyfill fallback */\n  mcpSession?: McpSession;\n  /** Include HTMX (default: false) */\n  htmx?: boolean;\n  /** Include Alpine.js (default: false) */\n  alpine?: boolean;\n  /** Include fonts (default: true) */\n  fonts?: boolean;\n  /** Use inline scripts (for blocked network platforms) */\n  inline?: boolean;\n  /**\n   * Additional head content (scripts, meta tags).\n   * @warning This content is injected WITHOUT escaping. Only use with trusted content.\n   */\n  headContent?: string;\n  /** Custom body classes */\n  bodyClass?: string;\n  /** Custom widget container classes */\n  containerClass?: string;\n}\n\n/**\n * Escape string for use in HTML attributes.\n */\nfunction escapeAttr(str: string): string {\n  return str\n    .replace(/&/g, '&amp;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&#39;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;');\n}\n\n/**\n * Create a default base template for tool UI widgets.\n *\n * This generates a complete HTML document that:\n * 1. Loads Tailwind CSS with theme configuration\n * 2. Injects platform polyfills (callTool, detectMcpSession, getToolOutput)\n * 3. Waits for toolOutput to be injected\n * 4. Renders content using window.__frontmcp.renderContent or default JSON renderer\n *\n * @param options - Base template configuration\n * @returns Complete HTML document string\n *\n * @example Basic usage\n * ```typescript\n * const html = createDefaultBaseTemplate({ toolName: 'get_weather' });\n * ```\n *\n * @example With custom theme and MCP session\n * ```typescript\n * const html = createDefaultBaseTemplate({\n *   toolName: 'get_weather',\n *   theme: customTheme,\n *   mcpSession: { mcpUrl: 'https://mcp.example.com', sessionId: 'abc123' },\n * });\n * ```\n *\n * @example For Claude Artifacts (inline scripts)\n * ```typescript\n * await fetchAndCacheScriptsFromTheme(theme);\n * const html = createDefaultBaseTemplate({\n *   toolName: 'get_weather',\n *   inline: true,\n * });\n * ```\n */\nexport function createDefaultBaseTemplate(options: BaseTemplateOptions): string {\n  const {\n    toolName,\n    theme = DEFAULT_THEME,\n    mcpSession,\n    htmx = false,\n    alpine = false,\n    fonts = true,\n    inline = false,\n    headContent = '',\n    bodyClass = 'bg-transparent font-sans antialiased',\n    containerClass = 'p-4',\n  } = options;\n\n  // Build theme styles (fonts, scripts, @theme CSS)\n  const themeStylesOptions: ThemeStylesOptions = {\n    theme,\n    tailwind: true,\n    htmx,\n    alpine,\n    fonts,\n    inline,\n  };\n  const themeStyles = renderThemeStyles(themeStylesOptions);\n\n  // Build MCP session polyfill (detectMcpSession, callTool, getToolOutput)\n  const polyfills = renderMcpSessionPolyfill(mcpSession);\n\n  // Build reactive bridge (handles data injection and re-rendering)\n  const bridge = renderBridgeScript();\n\n  return `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <meta name=\"color-scheme\" content=\"light dark\">\n  <title>${escapeAttr(toolName)} Widget</title>\n  ${themeStyles}\n  ${polyfills}\n  ${bridge}\n  ${headContent}\n</head>\n<body class=\"${escapeAttr(bodyClass)}\">\n  <div id=\"widget-root\" class=\"${escapeAttr(containerClass)}\"></div>\n\n  <script>\n  (function() {\n    'use strict';\n\n    var root = document.getElementById('widget-root');\n\n    /**\n     * Render the widget based on bridge state.\n     * Uses the reactive bridge to automatically re-render when data changes.\n     */\n    function render() {\n      var state = window.__frontmcp.bridge.getState();\n\n      // Loading state\n      if (state.loading) {\n        root.innerHTML = renderLoading();\n        return;\n      }\n\n      // Error state\n      if (state.error) {\n        root.innerHTML = renderError(state.error);\n        return;\n      }\n\n      // No data state\n      if (state.data === null) {\n        root.innerHTML = renderEmpty();\n        return;\n      }\n\n      // Render data\n      try {\n        // Check for custom renderer provided by developer\n        if (window.__frontmcp && typeof window.__frontmcp.renderContent === 'function') {\n          root.innerHTML = window.__frontmcp.renderContent(state.data);\n          return;\n        }\n\n        // Fall back to default renderer\n        root.innerHTML = defaultRenderer(state.data);\n      } catch (e) {\n        console.error('[frontmcp] Error rendering widget:', e);\n        root.innerHTML = renderError(e.message || 'Render error');\n      }\n    }\n\n    /**\n     * Default renderer for tool output.\n     * Handles both pre-rendered HTML strings and raw JSON data.\n     */\n    function defaultRenderer(data) {\n      // Check if data is pre-rendered HTML (server-side rendered widget)\n      if (typeof data === 'string' && data.trim().startsWith('<')) {\n        // Direct HTML injection - content was already rendered/sanitized server-side\n        return data;\n      }\n\n      // Check for special wrapper with HTML content\n      if (data && typeof data === 'object' && data.__html) {\n        return data.__html;\n      }\n\n      // Fallback: JSON renderer for raw data\n      var json = JSON.stringify(data, null, 2);\n      return '<pre class=\"p-4 bg-surface rounded-md overflow-auto text-sm font-mono text-text-primary border border-border\">' +\n        escapeHtml(json) +\n        '</pre>';\n    }\n\n    /**\n     * Render loading state with animated spinner.\n     */\n    function renderLoading() {\n      return '<div class=\"flex items-center justify-center p-8\">' +\n        '<div class=\"flex flex-col items-center gap-3\">' +\n        '<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\">' +\n        '<circle class=\"opacity-25\" cx=\"12\" cy=\"12\" r=\"10\" stroke=\"currentColor\" stroke-width=\"4\"></circle>' +\n        '<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>' +\n        '</svg>' +\n        '<p class=\"text-text-secondary text-sm\">Loading...</p>' +\n        '</div>' +\n        '</div>';\n    }\n\n    /**\n     * Render error message.\n     */\n    function renderError(message) {\n      return '<div class=\"p-4 bg-red-50 border border-red-200 rounded-md\">' +\n        '<p class=\"text-red-600 text-sm\">Error: ' + escapeHtml(message) + '</p>' +\n        '</div>';\n    }\n\n    /**\n     * Render empty state (no data available).\n     */\n    function renderEmpty() {\n      return '<div class=\"p-4 text-text-secondary text-sm text-center\">' +\n        'No data available' +\n        '</div>';\n    }\n\n    /**\n     * Escape HTML special characters.\n     */\n    function escapeHtml(str) {\n      if (typeof str !== 'string') return str;\n      return str\n        .replace(/&/g, '&amp;')\n        .replace(/</g, '&lt;')\n        .replace(/>/g, '&gt;')\n        .replace(/\"/g, '&quot;');\n    }\n\n    /**\n     * Create debug overlay panel.\n     * Shows bridge state, logs, and OpenAI data status.\n     */\n    function createDebugOverlay() {\n      var overlay = document.createElement('div');\n      overlay.id = 'frontmcp-debug-overlay';\n      overlay.style.cssText = 'position:fixed;bottom:10px;right:10px;width:400px;max-height:60vh;' +\n        'background:rgba(0,0,0,0.9);color:#0f0;font-family:monospace;font-size:11px;' +\n        'padding:10px;border-radius:4px;z-index:99999;overflow:auto;display:none;';\n\n      var toggle = document.createElement('button');\n      toggle.id = 'frontmcp-debug-toggle';\n      toggle.textContent = 'Debug';\n      toggle.style.cssText = 'position:fixed;bottom:10px;right:10px;padding:4px 8px;' +\n        'background:#333;color:#0f0;font-family:monospace;font-size:10px;border:1px solid #0f0;' +\n        'border-radius:4px;z-index:100000;cursor:pointer;';\n\n      toggle.onclick = function() {\n        var o = document.getElementById('frontmcp-debug-overlay');\n        if (o.style.display === 'none') {\n          o.style.display = 'block';\n          toggle.style.right = '420px';\n          updateDebugOverlay();\n        } else {\n          o.style.display = 'none';\n          toggle.style.right = '10px';\n        }\n      };\n\n      document.body.appendChild(overlay);\n      document.body.appendChild(toggle);\n\n      // Auto-update every second\n      setInterval(updateDebugOverlay, 1000);\n    }\n\n    function updateDebugOverlay() {\n      var overlay = document.getElementById('frontmcp-debug-overlay');\n      if (!overlay || overlay.style.display === 'none') return;\n\n      var state = window.__frontmcp.bridge.getState();\n      var debug = window.__frontmcp.bridge.debug;\n      var logs = debug.getLogs();\n      var errors = debug.getLastErrors();\n      var stateHistory = debug.getStateHistory();\n\n      var html = '<div style=\"margin-bottom:10px;border-bottom:1px solid #333;padding-bottom:5px;\">' +\n        '<strong>FrontMCP Debug Panel</strong>' +\n        '<span style=\"float:right;color:#666;\">v' + stateHistory.version + '</span>' +\n        '</div>';\n\n      // Bridge State\n      html += '<div style=\"margin-bottom:10px;\">' +\n        '<div style=\"color:#ff0;\">Bridge State:</div>' +\n        '<div>Loading: ' + state.loading + '</div>' +\n        '<div>Has Data: ' + (state.data !== null) + '</div>' +\n        '<div>Data Type: ' + (state.data === null ? 'null' : typeof state.data) + '</div>' +\n        (typeof state.data === 'string' ? '<div>Data Length: ' + state.data.length + '</div>' : '') +\n        '<div>Error: ' + (state.error || 'none') + '</div>' +\n        '</div>';\n\n      // OpenAI Status\n      html += '<div style=\"margin-bottom:10px;\">' +\n        '<div style=\"color:#ff0;\">OpenAI Status:</div>' +\n        '<div>Intercepted: ' + stateHistory.openaiIntercepted + '</div>' +\n        '<div>Poll Count: ' + stateHistory.pollCount + '</div>';\n\n      if (window.openai) {\n        html += '<div>window.openai: exists</div>' +\n          '<div>toolOutput: ' + (window.openai.toolOutput !== undefined ? 'present' : 'undefined') + '</div>' +\n          '<div>toolResponseMetadata: ' + (window.openai.toolResponseMetadata !== undefined ? 'present' : 'undefined') + '</div>';\n        if (window.openai.toolResponseMetadata) {\n          html += '<div>meta keys: ' + Object.keys(window.openai.toolResponseMetadata).join(', ') + '</div>';\n        }\n      } else {\n        html += '<div>window.openai: undefined</div>';\n      }\n      html += '</div>';\n\n      // Errors\n      if (errors.length > 0) {\n        html += '<div style=\"margin-bottom:10px;\">' +\n          '<div style=\"color:#f00;\">Errors (' + errors.length + '):</div>';\n        errors.slice(-5).forEach(function(e) {\n          html += '<div style=\"color:#f88;font-size:10px;\">[' + e.level + '] ' + escapeHtml(e.message) + '</div>';\n        });\n        html += '</div>';\n      }\n\n      // Recent Logs\n      html += '<div>' +\n        '<div style=\"color:#ff0;\">Recent Logs (' + logs.length + '):</div>' +\n        '<div style=\"max-height:150px;overflow:auto;\">';\n      logs.slice(-10).forEach(function(e) {\n        var color = e.level === 'error' ? '#f00' : e.level === 'warn' ? '#ff0' : '#0f0';\n        html += '<div style=\"color:' + color + ';font-size:10px;\">' +\n          '[' + e.ts.split('T')[1].split('.')[0] + '] ' + escapeHtml(e.message) +\n          '</div>';\n      });\n      html += '</div></div>';\n\n      // Actions\n      html += '<div style=\"margin-top:10px;border-top:1px solid #333;padding-top:5px;\">' +\n        '<button onclick=\"console.log(window.__frontmcp.bridge.debug.dumpAll())\" ' +\n        'style=\"font-size:10px;padding:2px 6px;margin-right:5px;\">Dump to Console</button>' +\n        '<button onclick=\"window.__frontmcp.bridge.reset()\" ' +\n        'style=\"font-size:10px;padding:2px 6px;\">Reset Bridge</button>' +\n        '</div>';\n\n      overlay.innerHTML = html;\n    }\n\n    /**\n     * Initialize the widget with reactive rendering.\n     */\n    function init() {\n      // Subscribe to bridge state changes for reactive re-rendering\n      window.__frontmcp.bridge.subscribe(render);\n\n      // Initial render\n      render();\n\n      // Global click handler for SSR-compatible tool calls\n      // Handles buttons/elements with data-tool-call attribute\n      document.addEventListener('click', function(e) {\n        var target = e.target;\n        // Walk up the DOM to find element with data-tool-call (handles clicks on child elements)\n        while (target && target !== document.body) {\n          if (target.hasAttribute && target.hasAttribute('data-tool-call')) {\n            var toolName = target.getAttribute('data-tool-call');\n            var argsStr = target.getAttribute('data-tool-args');\n            var args = {};\n\n            if (argsStr) {\n              try {\n                args = JSON.parse(argsStr);\n              } catch (parseErr) {\n                console.error('[frontmcp] Failed to parse data-tool-args:', parseErr);\n              }\n            }\n\n            // Prevent default behavior and stop propagation\n            e.preventDefault();\n            e.stopPropagation();\n\n            // Show loading state on the button\n            var originalContent = target.innerHTML;\n            var loadingContent = '<span style=\"display:inline-flex;align-items:center;\">' +\n              '<span style=\"animation:spin 1s linear infinite;margin-right:4px;\">⏳</span>' +\n              'Loading...' +\n              '</span>';\n            target.innerHTML = loadingContent;\n            target.disabled = true;\n\n            // Call the tool\n            if (window.__frontmcp && typeof window.__frontmcp.callTool === 'function') {\n              window.__frontmcp.callTool(toolName, args)\n                .then(function(result) {\n                  console.log('[frontmcp] Tool call success:', toolName, result);\n                  // Restore button state on success\n                  target.innerHTML = originalContent;\n                  target.disabled = false;\n                })\n                .catch(function(err) {\n                  console.error('[frontmcp] Tool call failed:', toolName, err);\n                  // Restore button state on error\n                  target.innerHTML = originalContent;\n                  target.disabled = false;\n                });\n            } else {\n              console.error('[frontmcp] callTool not available');\n              target.innerHTML = originalContent;\n              target.disabled = false;\n            }\n\n            return;\n          }\n          target = target.parentElement;\n        }\n      });\n\n      // Create debug overlay if debug mode is enabled\n      var DEBUG = window.location.search.indexOf('frontmcp_debug=1') > -1 ||\n                  window.localStorage.getItem('frontmcp_debug') === '1';\n      if (DEBUG) {\n        createDebugOverlay();\n      }\n    }\n\n    // Initialize when DOM is ready\n    if (document.readyState === 'loading') {\n      document.addEventListener('DOMContentLoaded', init);\n    } else {\n      init();\n    }\n  })();\n  </script>\n</body>\n</html>`;\n}\n\n/**\n * Create a minimal base template without fonts.\n *\n * Use this for lightweight widgets or when fonts are loaded elsewhere.\n *\n * @param toolName - Tool name for identification\n * @param mcpSession - Optional MCP session info\n * @returns Complete HTML document string\n */\nexport function createMinimalBaseTemplate(toolName: string, mcpSession?: McpSession): string {\n  return createDefaultBaseTemplate({\n    toolName,\n    mcpSession,\n    fonts: false,\n    htmx: false,\n    alpine: false,\n  });\n}\n"]}

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

@@ -0,0 +1,14 @@
+/**
+ * Base Template Module
+ *
+ * Provides default HTML wrappers for Tool UI widgets with:
+ * - Theming (Tailwind CSS + @theme)
+ * - Platform polyfills (callTool, detectMcpSession, getToolOutput)
+ * - Cross-platform compatibility (OpenAI, Claude, custom hosts)
+ *
+ * @module @frontmcp/ui/base-template
+ */
+export { createDefaultBaseTemplate, createMinimalBaseTemplate, type BaseTemplateOptions, } from './default-base-template';
+export { renderThemeStyles, renderMinimalThemeStyles, renderThemeCssOnly, type ThemeStylesOptions, } from './theme-styles';
+export { renderMcpSessionPolyfill, type McpSession } from './polyfills';
+export { renderBridgeScript, type BridgeState, type PlatformBridge, BRIDGE_TYPES } from './bridge';

package/src/base-template/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Base Template Module
+ *
+ * Provides default HTML wrappers for Tool UI widgets with:
+ * - Theming (Tailwind CSS + @theme)
+ * - Platform polyfills (callTool, detectMcpSession, getToolOutput)
+ * - Cross-platform compatibility (OpenAI, Claude, custom hosts)
+ *
+ * @module @frontmcp/ui/base-template
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BRIDGE_TYPES = exports.renderBridgeScript = exports.renderMcpSessionPolyfill = exports.renderThemeCssOnly = exports.renderMinimalThemeStyles = exports.renderThemeStyles = exports.createMinimalBaseTemplate = exports.createDefaultBaseTemplate = void 0;
+// Default base template
+var default_base_template_1 = require("./default-base-template");
+Object.defineProperty(exports, "createDefaultBaseTemplate", { enumerable: true, get: function () { return default_base_template_1.createDefaultBaseTemplate; } });
+Object.defineProperty(exports, "createMinimalBaseTemplate", { enumerable: true, get: function () { return default_base_template_1.createMinimalBaseTemplate; } });
+// Theme styles renderer
+var theme_styles_1 = require("./theme-styles");
+Object.defineProperty(exports, "renderThemeStyles", { enumerable: true, get: function () { return theme_styles_1.renderThemeStyles; } });
+Object.defineProperty(exports, "renderMinimalThemeStyles", { enumerable: true, get: function () { return theme_styles_1.renderMinimalThemeStyles; } });
+Object.defineProperty(exports, "renderThemeCssOnly", { enumerable: true, get: function () { return theme_styles_1.renderThemeCssOnly; } });
+// Platform polyfills
+var polyfills_1 = require("./polyfills");
+Object.defineProperty(exports, "renderMcpSessionPolyfill", { enumerable: true, get: function () { return polyfills_1.renderMcpSessionPolyfill; } });
+// Platform bridge (reactive data store)
+var bridge_1 = require("./bridge");
+Object.defineProperty(exports, "renderBridgeScript", { enumerable: true, get: function () { return bridge_1.renderBridgeScript; } });
+Object.defineProperty(exports, "BRIDGE_TYPES", { enumerable: true, get: function () { return bridge_1.BRIDGE_TYPES; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base-template/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,wBAAwB;AACxB,iEAIiC;AAH/B,kIAAA,yBAAyB,OAAA;AACzB,kIAAA,yBAAyB,OAAA;AAI3B,wBAAwB;AACxB,+CAKwB;AAJtB,iHAAA,iBAAiB,OAAA;AACjB,wHAAA,wBAAwB,OAAA;AACxB,kHAAA,kBAAkB,OAAA;AAIpB,qBAAqB;AACrB,yCAAwE;AAA/D,qHAAA,wBAAwB,OAAA;AAEjC,wCAAwC;AACxC,mCAAmG;AAA1F,4GAAA,kBAAkB,OAAA;AAAyC,sGAAA,YAAY,OAAA","sourcesContent":["/**\n * Base Template Module\n *\n * Provides default HTML wrappers for Tool UI widgets with:\n * - Theming (Tailwind CSS + @theme)\n * - Platform polyfills (callTool, detectMcpSession, getToolOutput)\n * - Cross-platform compatibility (OpenAI, Claude, custom hosts)\n *\n * @module @frontmcp/ui/base-template\n */\n\n// Default base template\nexport {\n  createDefaultBaseTemplate,\n  createMinimalBaseTemplate,\n  type BaseTemplateOptions,\n} from './default-base-template';\n\n// Theme styles renderer\nexport {\n  renderThemeStyles,\n  renderMinimalThemeStyles,\n  renderThemeCssOnly,\n  type ThemeStylesOptions,\n} from './theme-styles';\n\n// Platform polyfills\nexport { renderMcpSessionPolyfill, type McpSession } from './polyfills';\n\n// Platform bridge (reactive data store)\nexport { renderBridgeScript, type BridgeState, type PlatformBridge, BRIDGE_TYPES } from './bridge';\n"]}

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

@@ -0,0 +1,30 @@
+/**
+ * Platform Polyfills for Base Template
+ *
+ * Provides additional polyfills for MCP session detection and
+ * direct HTTP fallback when not in an OpenAI or ext-apps environment.
+ *
+ * These polyfills complement the existing MCP_BRIDGE_RUNTIME.
+ */
+/**
+ * MCP Session information for HTTP fallback
+ */
+export interface McpSession {
+    /** MCP server URL */
+    mcpUrl: string;
+    /** Session ID for authentication */
+    sessionId: string;
+}
+/**
+ * Render the MCP session detection polyfill script.
+ *
+ * This provides auto-detection of MCP session info from:
+ * 1. Explicit window.__frontmcp.mcpSession
+ * 2. Meta tags (mcp-url, mcp-session-id)
+ * 3. URL query parameters (mcpUrl, sessionId)
+ * 4. Fallback values provided at render time
+ *
+ * @param mcpSession - Optional explicit session to bake into the template
+ * @returns Script tag with polyfill code
+ */
+export declare function renderMcpSessionPolyfill(mcpSession?: McpSession): string;