@frontmcp/ui 0.5.0 → 0.6.0

package/src/registry/render-template.js

@@ -1,239 +0,0 @@
-"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

@@ -1 +0,0 @@
-{"version":3,"file":"render-template.js","sourceRoot":"","sources":["../../../src/registry/render-template.ts"],"names":[],"mappings":"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","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

@@ -1,260 +0,0 @@
-/**
- * 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;
-}