@frontmcp/ui 0.5.0

package/src/registry/render-template.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * Template Rendering
+ *
+ * Executes tool UI templates with proper context and helpers.
+ * Supports sync rendering for HTML strings/template functions,
+ * async rendering for React components via SSR, and MDX rendering.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containsMdxSyntax = containsMdxSyntax;
+exports.isReactComponent = isReactComponent;
+exports.renderToolTemplate = renderToolTemplate;
+exports.hasUIConfig = hasUIConfig;
+exports.renderToolTemplateAsync = renderToolTemplateAsync;
+const wrapper_1 = require("../runtime/wrapper");
+/**
+ * Check if a string contains MDX syntax (Markdown + JSX).
+ *
+ * Looks for:
+ * - JSX component tags (PascalCase): `<Component />`
+ * - JS expressions: `{variable}` or `{items.map(...)}`
+ * - Import/export statements
+ * - Frontmatter: `---\n...\n---`
+ */
+function containsMdxSyntax(source) {
+    // Has JSX component tags (PascalCase)
+    if (/<[A-Z][a-zA-Z0-9]*/.test(source)) {
+        return true;
+    }
+    // Has import/export statements (ESM)
+    if (/^(import|export)\s/m.test(source)) {
+        return true;
+    }
+    // Has JSX-specific attributes (className, onClick, etc.)
+    // These are only valid in JSX, not in regular HTML
+    if (/\s(className|onClick|onChange|onSubmit|htmlFor|dangerouslySetInnerHTML)=/.test(source)) {
+        return true;
+    }
+    // Has JS expressions in curly braces (not just HTML attributes)
+    if (/\{[^}"'\n]*\}/.test(source) && !/=\s*["'][^"']*\{/.test(source)) {
+        return true;
+    }
+    // Has frontmatter
+    if (/^---[\s\S]*?---/m.test(source)) {
+        return true;
+    }
+    // Has Markdown headers with JSX or expressions
+    if (/^#{1,6}\s.*\{.*\}/m.test(source)) {
+        return true;
+    }
+    // Has JSX fragments
+    if (/<>|<\/>/.test(source)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Render MDX content to HTML string.
+ *
+ * Uses the MDX renderer from @frontmcp/ui.
+ * Falls back to plain text if MDX rendering is not available.
+ */
+async function renderMdxContent(mdxContent, context, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+mdxComponents) {
+    try {
+        // Import the MDX renderer from renderers module
+        const { mdxRenderer } = await import('../renderers/index.js');
+        // Render MDX to HTML with custom components
+        const html = await mdxRenderer.render(mdxContent, context, { mdxComponents });
+        return html;
+    }
+    catch (error) {
+        // If MDX rendering fails, warn and return escaped content
+        console.error('[@frontmcp/ui] MDX rendering failed:', error instanceof Error ? error.stack || error.message : String(error));
+        // Return the raw MDX as escaped HTML (fallback)
+        const escaped = mdxContent.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        return `<pre class="mdx-fallback">${escaped}</pre>`;
+    }
+}
+/**
+ * Check if a template is a React component (not a template builder function).
+ *
+ * React components are distinguished from template builder functions by:
+ * - Having $$typeof symbol (React.memo, forwardRef, etc.)
+ * - Having prototype.isReactComponent (class components)
+ * - PascalCase naming convention (function components)
+ *
+ * Template builder functions take (ctx) and return a string, while
+ * React components take props and return JSX.Element.
+ */
+function isReactComponent(template) {
+    if (typeof template !== 'function')
+        return false;
+    // Template builder functions take (ctx) and return string
+    // React components have different signatures
+    // Check for React component markers
+    const fn = template;
+    // React.memo, forwardRef, etc. have $$typeof
+    if (fn.$$typeof)
+        return true;
+    // Class components have prototype.isReactComponent
+    if (fn.prototype?.isReactComponent)
+        return true;
+    // Function components: PascalCase name convention
+    // This is a heuristic - function names starting with uppercase are likely React components
+    if (fn.name && /^[A-Z]/.test(fn.name))
+        return true;
+    return false;
+}
+/**
+ * Render a tool UI template.
+ *
+ * @param options - Template and context data
+ * @returns Rendered HTML string
+ * @throws Error if template execution fails
+ */
+function renderToolTemplate(options) {
+    const { template, input, output, structuredContent } = options;
+    // If template is already a string, return it directly
+    if (typeof template === 'string') {
+        return template;
+    }
+    // Create template context with helpers
+    const ctx = {
+        input,
+        output,
+        structuredContent,
+        helpers: (0, wrapper_1.createTemplateHelpers)(),
+    };
+    // Execute the template function
+    try {
+        return template(ctx);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Template rendering failed: ${message}`);
+    }
+}
+/**
+ * Check if a tool has UI configuration.
+ * Uses loose typing to handle variance issues with generic tool metadata.
+ */
+function hasUIConfig(metadata) {
+    const ui = metadata.ui;
+    return ui !== undefined && ui.template !== undefined;
+}
+/**
+ * Render a tool UI template asynchronously.
+ *
+ * This version supports:
+ * - React components via SSR
+ * - MDX strings (Markdown + JSX) via @mdx-js/mdx
+ * - HTML strings and template builder functions
+ *
+ * For React components:
+ * - Dynamically imports react and react-dom/server
+ * - Uses renderToString for SSR
+ * - React components receive the template context as props
+ *
+ * For MDX templates:
+ * - Detects MDX syntax (Markdown headers, JSX components, expressions)
+ * - Compiles and renders via @frontmcp/ui's MDX renderer
+ *
+ * @param options - Template and context data
+ * @returns Promise resolving to rendered HTML string
+ * @throws Error if template execution or rendering fails
+ */
+async function renderToolTemplateAsync(options) {
+    const { template, input, output, structuredContent, mdxComponents } = options;
+    // Create template context with helpers
+    const ctx = {
+        input,
+        output,
+        structuredContent,
+        helpers: (0, wrapper_1.createTemplateHelpers)(),
+    };
+    // If template is already a string, check if it's MDX
+    if (typeof template === 'string') {
+        if (containsMdxSyntax(template)) {
+            return renderMdxContent(template, ctx, mdxComponents);
+        }
+        return template;
+    }
+    // Check if it's a React component
+    if (isReactComponent(template)) {
+        // Get component name for error reporting
+        const componentName = template.displayName || template.name || 'UnknownComponent';
+        try {
+            // Dynamically import React and ReactDOMServer
+            // This allows UI package to work without React as a hard dependency
+            const [React, ReactDOMServer] = await Promise.all([
+                import('react').catch(() => {
+                    throw new Error('React is required for React component templates. Install react as a dependency.');
+                }),
+                import('react-dom/server').catch(() => {
+                    throw new Error('react-dom/server is required for React component templates. Install react-dom as a dependency.');
+                }),
+            ]);
+            // React components receive props, which is our context
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const element = React.createElement(template, ctx);
+            return ReactDOMServer.renderToString(element);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            // Log detailed error for debugging
+            if (process.env['DEBUG'] || process.env['NODE_ENV'] === 'development') {
+                console.error('[FrontMCP] React SSR Error:', {
+                    component: componentName,
+                    error: errorMessage,
+                    stack: errorStack,
+                    propsKeys: Object.keys(ctx),
+                    hasInput: 'input' in ctx,
+                    hasOutput: 'output' in ctx,
+                    hasStructuredContent: 'structuredContent' in ctx,
+                });
+            }
+            throw new Error(`React template rendering failed for "${componentName}": ${errorMessage}`);
+        }
+    }
+    // Execute as regular template builder function
+    try {
+        const result = template(ctx);
+        // Check if the result is an MDX string (template function returned MDX)
+        if (typeof result === 'string' && containsMdxSyntax(result)) {
+            return renderMdxContent(result, ctx, mdxComponents);
+        }
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Template rendering failed: ${message}`);
+    }
+}
+//# sourceMappingURL=render-template.js.map

package/src/registry/render-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-template.js","sourceRoot":"","sources":["../../../src/registry/render-template.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAcH,8CAsCC;AA6CD,4CAyBC;AA2BD,gDAuBC;AAMD,kCAGC;AAuBD,0DA8EC;AAvRD,gDAA2D;AAE3D;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,MAAc;IAC9C,sCAAsC;IACtC,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qCAAqC;IACrC,IAAI,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,yDAAyD;IACzD,mDAAmD;IACnD,IAAI,0EAA0E,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gEAAgE;IAChE,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACrE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IAClB,IAAI,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+CAA+C;IAC/C,IAAI,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oBAAoB;IACpB,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,gBAAgB,CAC7B,UAAkB,EAClB,OAAiC;AACjC,8DAA8D;AAC9D,aAAmC;IAEnC,IAAI,CAAC;QACH,gDAAgD;QAChD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;QAE9D,4CAA4C;QAC5C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0DAA0D;QAC1D,OAAO,CAAC,KAAK,CACX,sCAAsC,EACtC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACtE,CAAC;QAEF,gDAAgD;QAChD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9F,OAAO,6BAA6B,OAAO,QAAQ,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAAC,QAAiB;IAChD,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAEjD,0DAA0D;IAC1D,6CAA6C;IAE7C,oCAAoC;IACpC,MAAM,EAAE,GAAG,QAKV,CAAC;IAEF,6CAA6C;IAC7C,IAAI,EAAE,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE7B,mDAAmD;IACnD,IAAI,EAAE,CAAC,SAAS,EAAE,gBAAgB;QAAE,OAAO,IAAI,CAAC;IAEhD,kDAAkD;IAClD,2FAA2F;IAC3F,IAAI,EAAE,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnD,OAAO,KAAK,CAAC;AACf,CAAC;AAoBD;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,OAA8B;IAC/D,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;IAE/D,sDAAsD;IACtD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,uCAAuC;IACvC,MAAM,GAAG,GAAsD;QAC7D,KAAK;QACL,MAAM;QACN,iBAAiB;QACjB,OAAO,EAAE,IAAA,+BAAqB,GAAE;KACjC,CAAC;IAEF,gCAAgC;IAChC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,QAA0B;IACpD,MAAM,EAAE,GAAG,QAAQ,CAAC,EAAoD,CAAC;IACzE,OAAO,EAAE,KAAK,SAAS,IAAI,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,KAAK,UAAU,uBAAuB,CAAC,OAA8B;IAC1E,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAE9E,uCAAuC;IACvC,MAAM,GAAG,GAAsD;QAC7D,KAAK;QACL,MAAM;QACN,iBAAiB;QACjB,OAAO,EAAE,IAAA,+BAAqB,GAAE;KACjC,CAAC;IAEF,qDAAqD;IACrD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChC,OAAO,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,kCAAkC;IAClC,IAAI,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/B,yCAAyC;QACzC,MAAM,aAAa,GAChB,QAAgC,CAAC,WAAW,IAAK,QAAgC,CAAC,IAAI,IAAI,kBAAkB,CAAC;QAEhH,IAAI,CAAC;YACH,8CAA8C;YAC9C,oEAAoE;YACpE,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBAChD,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;oBACzB,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAC;gBACrG,CAAC,CAAC;gBACF,MAAM,CAAC,kBAAkB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;oBACpC,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAC;gBACJ,CAAC,CAAC;aACH,CAAC,CAAC;YAEH,uDAAuD;YACvD,8DAA8D;YAC9D,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAAC,QAAoC,EAAE,GAAG,CAAC,CAAC;YAC/E,OAAO,cAAc,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5E,MAAM,UAAU,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YAEpE,mCAAmC;YACnC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,aAAa,EAAE,CAAC;gBACtE,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE;oBAC3C,SAAS,EAAE,aAAa;oBACxB,KAAK,EAAE,YAAY;oBACnB,KAAK,EAAE,UAAU;oBACjB,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;oBAC3B,QAAQ,EAAE,OAAO,IAAI,GAAG;oBACxB,SAAS,EAAE,QAAQ,IAAI,GAAG;oBAC1B,oBAAoB,EAAE,mBAAmB,IAAI,GAAG;iBACjD,CAAC,CAAC;YACL,CAAC;YAED,MAAM,IAAI,KAAK,CAAC,wCAAwC,aAAa,MAAM,YAAY,EAAE,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAI,QAAgD,CAAC,GAAG,CAAC,CAAC;QAEtE,wEAAwE;QACxE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5D,OAAO,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC","sourcesContent":["/**\n * Template Rendering\n *\n * Executes tool UI templates with proper context and helpers.\n * Supports sync rendering for HTML strings/template functions,\n * async rendering for React components via SSR, and MDX rendering.\n *\n * @packageDocumentation\n */\n\nimport type { UITemplateConfig, TemplateContext, TemplateBuilderFn } from '../types';\nimport { createTemplateHelpers } from '../runtime/wrapper';\n\n/**\n * Check if a string contains MDX syntax (Markdown + JSX).\n *\n * Looks for:\n * - JSX component tags (PascalCase): `<Component />`\n * - JS expressions: `{variable}` or `{items.map(...)}`\n * - Import/export statements\n * - Frontmatter: `---\\n...\\n---`\n */\nexport function containsMdxSyntax(source: string): boolean {\n  // Has JSX component tags (PascalCase)\n  if (/<[A-Z][a-zA-Z0-9]*/.test(source)) {\n    return true;\n  }\n\n  // Has import/export statements (ESM)\n  if (/^(import|export)\\s/m.test(source)) {\n    return true;\n  }\n\n  // Has JSX-specific attributes (className, onClick, etc.)\n  // These are only valid in JSX, not in regular HTML\n  if (/\\s(className|onClick|onChange|onSubmit|htmlFor|dangerouslySetInnerHTML)=/.test(source)) {\n    return true;\n  }\n\n  // Has JS expressions in curly braces (not just HTML attributes)\n  if (/\\{[^}\"'\\n]*\\}/.test(source) && !/=\\s*[\"'][^\"']*\\{/.test(source)) {\n    return true;\n  }\n\n  // Has frontmatter\n  if (/^---[\\s\\S]*?---/m.test(source)) {\n    return true;\n  }\n\n  // Has Markdown headers with JSX or expressions\n  if (/^#{1,6}\\s.*\\{.*\\}/m.test(source)) {\n    return true;\n  }\n\n  // Has JSX fragments\n  if (/<>|<\\/>/.test(source)) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Render MDX content to HTML string.\n *\n * Uses the MDX renderer from @frontmcp/ui.\n * Falls back to plain text if MDX rendering is not available.\n */\nasync function renderMdxContent<In, Out>(\n  mdxContent: string,\n  context: TemplateContext<In, Out>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  mdxComponents?: Record<string, any>,\n): Promise<string> {\n  try {\n    // Import the MDX renderer from renderers module\n    const { mdxRenderer } = await import('../renderers/index.js');\n\n    // Render MDX to HTML with custom components\n    const html = await mdxRenderer.render(mdxContent, context, { mdxComponents });\n    return html;\n  } catch (error) {\n    // If MDX rendering fails, warn and return escaped content\n    console.error(\n      '[@frontmcp/ui] MDX rendering failed:',\n      error instanceof Error ? error.stack || error.message : String(error),\n    );\n\n    // Return the raw MDX as escaped HTML (fallback)\n    const escaped = mdxContent.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');\n    return `<pre class=\"mdx-fallback\">${escaped}</pre>`;\n  }\n}\n\n/**\n * Check if a template is a React component (not a template builder function).\n *\n * React components are distinguished from template builder functions by:\n * - Having $$typeof symbol (React.memo, forwardRef, etc.)\n * - Having prototype.isReactComponent (class components)\n * - PascalCase naming convention (function components)\n *\n * Template builder functions take (ctx) and return a string, while\n * React components take props and return JSX.Element.\n */\nexport function isReactComponent(template: unknown): boolean {\n  if (typeof template !== 'function') return false;\n\n  // Template builder functions take (ctx) and return string\n  // React components have different signatures\n\n  // Check for React component markers\n  const fn = template as Function & {\n    $$typeof?: symbol;\n    displayName?: string;\n    render?: Function;\n    prototype?: { isReactComponent?: boolean };\n  };\n\n  // React.memo, forwardRef, etc. have $$typeof\n  if (fn.$$typeof) return true;\n\n  // Class components have prototype.isReactComponent\n  if (fn.prototype?.isReactComponent) return true;\n\n  // Function components: PascalCase name convention\n  // This is a heuristic - function names starting with uppercase are likely React components\n  if (fn.name && /^[A-Z]/.test(fn.name)) return true;\n\n  return false;\n}\n\n/**\n * Options for rendering a tool template.\n */\nexport interface RenderTemplateOptions {\n  /** The template configuration from the tool */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  template: TemplateBuilderFn<unknown, unknown> | string | ((props: any) => any);\n  /** Tool input arguments */\n  input: Record<string, unknown>;\n  /** Tool output (raw result from execute) */\n  output: unknown;\n  /** Structured content parsed from output */\n  structuredContent?: unknown;\n  /** Custom MDX components to use in MDX templates */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  mdxComponents?: Record<string, any>;\n}\n\n/**\n * Render a tool UI template.\n *\n * @param options - Template and context data\n * @returns Rendered HTML string\n * @throws Error if template execution fails\n */\nexport function renderToolTemplate(options: RenderTemplateOptions): string {\n  const { template, input, output, structuredContent } = options;\n\n  // If template is already a string, return it directly\n  if (typeof template === 'string') {\n    return template;\n  }\n\n  // Create template context with helpers\n  const ctx: TemplateContext<Record<string, unknown>, unknown> = {\n    input,\n    output,\n    structuredContent,\n    helpers: createTemplateHelpers(),\n  };\n\n  // Execute the template function\n  try {\n    return template(ctx);\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    throw new Error(`Template rendering failed: ${message}`);\n  }\n}\n\n/**\n * Check if a tool has UI configuration.\n * Uses loose typing to handle variance issues with generic tool metadata.\n */\nexport function hasUIConfig(metadata: { ui?: unknown }): metadata is { ui: UITemplateConfig<unknown, unknown> } {\n  const ui = metadata.ui as UITemplateConfig<unknown, unknown> | undefined;\n  return ui !== undefined && ui.template !== undefined;\n}\n\n/**\n * Render a tool UI template asynchronously.\n *\n * This version supports:\n * - React components via SSR\n * - MDX strings (Markdown + JSX) via @mdx-js/mdx\n * - HTML strings and template builder functions\n *\n * For React components:\n * - Dynamically imports react and react-dom/server\n * - Uses renderToString for SSR\n * - React components receive the template context as props\n *\n * For MDX templates:\n * - Detects MDX syntax (Markdown headers, JSX components, expressions)\n * - Compiles and renders via @frontmcp/ui's MDX renderer\n *\n * @param options - Template and context data\n * @returns Promise resolving to rendered HTML string\n * @throws Error if template execution or rendering fails\n */\nexport async function renderToolTemplateAsync(options: RenderTemplateOptions): Promise<string> {\n  const { template, input, output, structuredContent, mdxComponents } = options;\n\n  // Create template context with helpers\n  const ctx: TemplateContext<Record<string, unknown>, unknown> = {\n    input,\n    output,\n    structuredContent,\n    helpers: createTemplateHelpers(),\n  };\n\n  // If template is already a string, check if it's MDX\n  if (typeof template === 'string') {\n    if (containsMdxSyntax(template)) {\n      return renderMdxContent(template, ctx, mdxComponents);\n    }\n    return template;\n  }\n\n  // Check if it's a React component\n  if (isReactComponent(template)) {\n    // Get component name for error reporting\n    const componentName =\n      (template as React.ComponentType).displayName || (template as React.ComponentType).name || 'UnknownComponent';\n\n    try {\n      // Dynamically import React and ReactDOMServer\n      // This allows UI package to work without React as a hard dependency\n      const [React, ReactDOMServer] = await Promise.all([\n        import('react').catch(() => {\n          throw new Error('React is required for React component templates. Install react as a dependency.');\n        }),\n        import('react-dom/server').catch(() => {\n          throw new Error(\n            'react-dom/server is required for React component templates. Install react-dom as a dependency.',\n          );\n        }),\n      ]);\n\n      // React components receive props, which is our context\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const element = React.createElement(template as React.ComponentType<any>, ctx);\n      return ReactDOMServer.renderToString(element);\n    } catch (error) {\n      const errorMessage = error instanceof Error ? error.message : String(error);\n      const errorStack = error instanceof Error ? error.stack : undefined;\n\n      // Log detailed error for debugging\n      if (process.env['DEBUG'] || process.env['NODE_ENV'] === 'development') {\n        console.error('[FrontMCP] React SSR Error:', {\n          component: componentName,\n          error: errorMessage,\n          stack: errorStack,\n          propsKeys: Object.keys(ctx),\n          hasInput: 'input' in ctx,\n          hasOutput: 'output' in ctx,\n          hasStructuredContent: 'structuredContent' in ctx,\n        });\n      }\n\n      throw new Error(`React template rendering failed for \"${componentName}\": ${errorMessage}`);\n    }\n  }\n\n  // Execute as regular template builder function\n  try {\n    const result = (template as TemplateBuilderFn<unknown, unknown>)(ctx);\n\n    // Check if the result is an MDX string (template function returned MDX)\n    if (typeof result === 'string' && containsMdxSyntax(result)) {\n      return renderMdxContent(result, ctx, mdxComponents);\n    }\n\n    return result;\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    throw new Error(`Template rendering failed: ${message}`);\n  }\n}\n"]}

package/src/registry/tool-ui.registry.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Tool UI Registry
+ *
+ * Manages UI template rendering for tool responses.
+ * Provides platform-specific metadata generation for MCP clients.
+ *
+ * Three serving modes:
+ * - **inline**: HTML is rendered per-request and embedded in _meta['ui/html']
+ * - **static**: Static widget is pre-compiled at startup, client fetches via resources/read
+ * - **hybrid**: Shell (React + renderer) cached at startup, component + data in response
+ *
+ * @packageDocumentation
+ */
+import type { UITemplateConfig, WidgetManifest, BuildManifestResult } from '../types';
+import type { AIPlatformType, UIMetadata } from '../adapters';
+/**
+ * Options for renderAndRegisterAsync (inline mode).
+ */
+export interface RenderOptions {
+    /** Tool name */
+    toolName: string;
+    /** Unique request identifier */
+    requestId: string;
+    /** Tool input arguments */
+    input: Record<string, unknown>;
+    /** Raw tool output */
+    output: unknown;
+    /** Structured content (parsed from output) */
+    structuredContent?: unknown;
+    /** Tool UI configuration */
+    uiConfig: UITemplateConfig;
+    /** Detected platform type */
+    platformType: AIPlatformType;
+    /** Widget access token (optional) */
+    token?: string;
+    /** Direct URL for widget serving (optional) */
+    directUrl?: string;
+}
+/**
+ * Result of rendering UI for inline mode.
+ */
+export interface UIRenderResult {
+    /** Rendered HTML content */
+    html: string;
+    /** Platform-specific metadata for _meta field */
+    meta: UIMetadata;
+}
+/**
+ * ToolUIRegistry manages UI template rendering for tool responses.
+ *
+ * It provides:
+ * - Static widget compilation for static mode (pre-compiled at startup)
+ * - Per-request HTML rendering for inline mode (embedded in _meta)
+ * - Platform-specific _meta generation
+ * - Widget manifest management
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolUIRegistry();
+ *
+ * // For inline mode: render HTML per-request
+ * const result = await registry.renderAndRegisterAsync({
+ *   toolName: 'get_weather',
+ *   requestId: 'abc123',
+ *   input: { location: 'London' },
+ *   output: { temp: 72, conditions: 'Sunny' },
+ *   uiConfig: tool.metadata.ui,
+ *   platformType: 'openai',
+ * });
+ *
+ * // result.meta can be spread into tool result _meta
+ * return { content: [...], _meta: { ...result.meta } };
+ * ```
+ */
+/**
+ * Options for compiling a static widget.
+ */
+export interface CompileStaticWidgetOptions {
+    /** Tool name (used for cache key and URI) */
+    toolName: string;
+    /** The template to compile (React component, HTML string, or builder function) */
+    template: UITemplateConfig['template'];
+    /** Tool UI configuration */
+    uiConfig: UITemplateConfig;
+}
+/**
+ * Payload for hybrid mode component delivery.
+ * Sent in `_meta['ui/component']` at tool call time.
+ */
+export interface HybridComponentPayload {
+    /** Transpiled component JavaScript code (ES module format) */
+    code: string;
+    /** Renderer type for the component */
+    type: 'react' | 'mdx' | 'html';
+    /** Tool name for identification */
+    toolName: string;
+    /** Content hash for cache validation */
+    hash: string;
+}
+/**
+ * Options for building a hybrid component payload.
+ */
+export interface BuildHybridComponentPayloadOptions {
+    /** Tool name */
+    toolName: string;
+    /** The template to transpile */
+    template: UITemplateConfig['template'];
+    /** Tool UI configuration */
+    uiConfig: UITemplateConfig;
+}
+export declare class ToolUIRegistry {
+    /**
+     * Cache for static widgets (keyed by tool name).
+     * Static widgets are pre-compiled at server startup for tools with servingMode: 'static'.
+     * These widgets read data from the FrontMCP Bridge at runtime (window.openai.toolOutput).
+     */
+    private readonly staticWidgetCache;
+    /**
+     * Cache for widget manifests (keyed by tool name).
+     * Manifests describe the widget's renderer type, CSP, and other metadata.
+     */
+    private readonly manifestCache;
+    /**
+     * Cache for build results (keyed by tool name).
+     * Includes HTML, manifest, and hash for cache validation.
+     */
+    private readonly buildResultCache;
+    /**
+     * Compile a static widget template for a tool at server startup.
+     *
+     * For tools with `servingMode: 'static'`, the widget HTML is pre-compiled
+     * WITHOUT embedded data. The widget reads data from the FrontMCP Bridge at runtime
+     * (via window.openai.toolOutput or window.__frontmcp.toolOutput).
+     *
+     * This is called during tool registration, not during tool calls.
+     *
+     * @param options - Static widget compilation options
+     */
+    compileStaticWidgetAsync(options: CompileStaticWidgetOptions): Promise<void>;
+    /**
+     * Compile a lean widget shell for inline mode tools at server startup.
+     *
+     * For tools with `servingMode: 'inline'`, we create a minimal HTML shell that:
+     * - Contains only HTML structure, theme CSS, and fonts
+     * - NO React runtime, NO component code, NO bridge
+     * - OpenAI caches this at discovery time
+     * - The actual React widget comes in each tool response with embedded data
+     *
+     * @param options - Options for lean widget compilation
+     */
+    compileLeanWidgetAsync(options: {
+        toolName: string;
+        uiConfig: UITemplateConfig;
+    }): void;
+    /**
+     * Compile a hybrid widget shell at server startup.
+     *
+     * For tools with `servingMode: 'hybrid'`, we create a shell that:
+     * - Contains React 19 runtime from esm.sh CDN
+     * - Contains FrontMCP Bridge (universal)
+     * - Contains all FrontMCP hooks (useMcpBridgeContext, useToolOutput, etc.)
+     * - Contains all FrontMCP UI components (Card, Badge, Button)
+     * - Contains dynamic renderer script that imports components via blob URL
+     * - NO component code (comes at tool call time via `_meta['ui/component']`)
+     *
+     * The shell listens for `ui/component` in tool response metadata and dynamically
+     * imports the transpiled component code, then renders it with tool output data.
+     *
+     * @param options - Options for hybrid widget compilation
+     */
+    compileHybridWidgetAsync(options: {
+        toolName: string;
+        uiConfig: UITemplateConfig;
+    }): void;
+    /**
+     * Build a component payload for hybrid mode tool responses.
+     *
+     * For tools with `servingMode: 'hybrid'`, this method is called at tool call time
+     * to build the transpiled component code that gets delivered in `_meta['ui/component']`.
+     *
+     * The component code is in ES module format so it can be dynamically imported
+     * via blob URL in the hybrid shell's renderer.
+     *
+     * @param options - Options for building the component payload
+     * @returns The hybrid component payload, or undefined if template is not a function
+     */
+    buildHybridComponentPayload(options: BuildHybridComponentPayloadOptions): HybridComponentPayload | undefined;
+    /**
+     * Get the pre-compiled static widget HTML for a tool.
+     *
+     * @param toolName - The tool name to look up
+     * @returns Pre-compiled widget HTML, or undefined if not cached
+     */
+    getStaticWidget(toolName: string): string | undefined;
+    /**
+     * Check if a tool has a pre-compiled static widget.
+     *
+     * @param toolName - The tool name to check
+     * @returns true if the tool has a cached static widget
+     */
+    hasStaticWidget(toolName: string): boolean;
+    /**
+     * Get the widget manifest for a tool.
+     *
+     * @param toolName - The tool name to look up
+     * @returns Widget manifest, or undefined if not cached
+     */
+    getManifest(toolName: string): WidgetManifest | undefined;
+    /**
+     * Check if a tool has a cached manifest.
+     *
+     * @param toolName - The tool name to check
+     * @returns true if the tool has a cached manifest
+     */
+    hasManifest(toolName: string): boolean;
+    /**
+     * Get the full build result for a tool.
+     *
+     * @param toolName - The tool name to look up
+     * @returns Build result, or undefined if not cached
+     */
+    getBuildResult(toolName: string): BuildManifestResult | undefined;
+    /**
+     * Detect the UI type for a template.
+     *
+     * @param template - The template to analyze
+     * @returns Detected UI type
+     */
+    detectUIType(template: UITemplateConfig['template']): string;
+    /**
+     * Render a tool's UI template for inline mode.
+     *
+     * This version supports all template types including React components.
+     * The rendered HTML is embedded directly in _meta['ui/html'] for the client.
+     *
+     * For React/MDX components, the output is wrapped using wrapStaticWidgetUniversal
+     * which includes the React 19 CDN, client-side rendering script, and all the
+     * FrontMCP hooks/components. This provides the same rendering capability as
+     * static mode, but with data embedded in each response.
+     *
+     * @param options - Rendering options
+     * @returns Promise resolving to render result with HTML and metadata
+     */
+    renderAndRegisterAsync(options: RenderOptions): Promise<UIRenderResult>;
+    /**
+     * Build component code string for embedding in widget HTML.
+     *
+     * @param template - The React component
+     * @param toolName - Tool name for naming the component
+     * @returns JavaScript code string that defines and registers the component
+     */
+    private buildComponentCode;
+    /**
+     * Check if a template requires async rendering (e.g., React components).
+     *
+     * @param template - The template to check
+     * @returns true if the template requires async rendering
+     */
+    requiresAsyncRendering(template: UITemplateConfig['template']): boolean;
+}