@frontmcp/ui 0.5.0

package/src/renderers/html.renderer.d.ts

@@ -0,0 +1,122 @@
+/**
+ * HTML Renderer
+ *
+ * Handles plain HTML templates:
+ * - Static HTML strings
+ * - Template builder functions: (ctx) => string
+ * - Handlebars-enhanced templates: HTML with {{variable}} syntax
+ *
+ * This is the default fallback renderer with the lowest priority.
+ */
+import type { TemplateContext } from '../runtime/types';
+import type { PlatformCapabilities } from '../theme';
+import type { UIRenderer, TranspileResult, TranspileOptions, RenderOptions, RuntimeScripts } from './types';
+/**
+ * Template builder function type.
+ */
+type TemplateBuilderFn<In, Out> = (ctx: TemplateContext<In, Out>) => string;
+/**
+ * Types this renderer can handle.
+ */
+type HtmlTemplate<In = unknown, Out = unknown> = string | TemplateBuilderFn<In, Out>;
+/**
+ * Check if a template contains Handlebars syntax.
+ * Non-async version for canHandle check.
+ */
+declare function containsHandlebars(template: string): boolean;
+/**
+ * HTML Renderer Implementation.
+ *
+ * Handles:
+ * - Static HTML strings (passed through directly)
+ * - Template builder functions that return HTML strings
+ * - Handlebars-enhanced templates (detected by {{...}} syntax)
+ *
+ * When Handlebars syntax is detected, the template is processed
+ * with the HandlebarsRenderer for variable interpolation, conditionals,
+ * and loops.
+ *
+ * @example Static HTML
+ * ```typescript
+ * const template = '<div class="card">Hello World</div>';
+ * await htmlRenderer.render(template, context);
+ * ```
+ *
+ * @example Template function
+ * ```typescript
+ * const template = (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.name)}</div>`;
+ * await htmlRenderer.render(template, context);
+ * ```
+ *
+ * @example Handlebars template
+ * ```typescript
+ * const template = `
+ *   <div class="card">
+ *     <h2>{{escapeHtml output.title}}</h2>
+ *     {{#if output.items}}
+ *       <ul>
+ *         {{#each output.items}}
+ *           <li>{{this.name}}</li>
+ *         {{/each}}
+ *       </ul>
+ *     {{/if}}
+ *   </div>
+ * `;
+ * await htmlRenderer.render(template, context);
+ * ```
+ */
+export declare class HtmlRenderer implements UIRenderer<HtmlTemplate> {
+    readonly type: "html";
+    readonly priority = 0;
+    /**
+     * Check if this renderer can handle the given template.
+     *
+     * Accepts:
+     * - Any string (assumed to be HTML, with or without Handlebars)
+     * - Functions that are template builders (not React components)
+     */
+    canHandle(template: unknown): template is HtmlTemplate;
+    /**
+     * Check if a template uses Handlebars syntax.
+     *
+     * @param template - Template string to check
+     * @returns true if template contains {{...}} syntax
+     */
+    usesHandlebars(template: string): boolean;
+    /**
+     * Transpile the template.
+     *
+     * For HTML templates, no transpilation is needed.
+     * This method returns a dummy result for consistency.
+     */
+    transpile(template: HtmlTemplate, _options?: TranspileOptions): Promise<TranspileResult>;
+    /**
+     * Render the template to HTML string.
+     *
+     * For static strings without Handlebars, returns the string directly.
+     * For strings with Handlebars syntax, processes with HandlebarsRenderer.
+     * For functions, calls the function with the context.
+     */
+    render<In, Out>(template: HtmlTemplate<In, Out>, context: TemplateContext<In, Out>, _options?: RenderOptions): Promise<string>;
+    /**
+     * Render Handlebars template with context.
+     */
+    private renderHandlebars;
+    /**
+     * Get runtime scripts for client-side functionality.
+     *
+     * HTML templates don't need additional runtime scripts.
+     */
+    getRuntimeScripts(_platform: PlatformCapabilities): RuntimeScripts;
+}
+/**
+ * Singleton instance of the HTML renderer.
+ */
+export declare const htmlRenderer: HtmlRenderer;
+/**
+ * Check if a template string contains Handlebars syntax.
+ *
+ * @param template - Template string
+ * @returns true if contains {{...}}
+ */
+export { containsHandlebars };

package/src/renderers/html.renderer.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * HTML Renderer
+ *
+ * Handles plain HTML templates:
+ * - Static HTML strings
+ * - Template builder functions: (ctx) => string
+ * - Handlebars-enhanced templates: HTML with {{variable}} syntax
+ *
+ * This is the default fallback renderer with the lowest priority.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.htmlRenderer = exports.HtmlRenderer = void 0;
+exports.containsHandlebars = containsHandlebars;
+const detect_1 = require("./utils/detect");
+const hash_1 = require("./utils/hash");
+/**
+ * Lazy-loaded HandlebarsRenderer for Handlebars template support.
+ */
+let handlebarsRenderer = null;
+/**
+ * Load HandlebarsRenderer if available.
+ */
+async function loadHandlebarsRenderer() {
+    if (handlebarsRenderer !== null) {
+        return handlebarsRenderer;
+    }
+    try {
+        // Dynamic import with explicit .js extension for ESM compatibility
+        const handlebarsModule = await import(/* webpackIgnore: true */ '../handlebars/index.js');
+        const { HandlebarsRenderer } = handlebarsModule;
+        const renderer = new HandlebarsRenderer();
+        handlebarsRenderer = {
+            render: (template, context) => renderer.render(template, {
+                input: (context.input ?? {}),
+                output: context.output,
+                structuredContent: context.structuredContent,
+            }),
+            containsHandlebars: (template) => HandlebarsRenderer.containsHandlebars(template),
+        };
+        return handlebarsRenderer;
+    }
+    catch {
+        // Handlebars not available, return null
+        return null;
+    }
+}
+/**
+ * Check if a template contains Handlebars syntax.
+ * Non-async version for canHandle check.
+ */
+function containsHandlebars(template) {
+    // Match {{...}} but not {{! comments }}
+    return /\{\{(?!!)[\s\S]*?\}\}/.test(template);
+}
+/**
+ * HTML Renderer Implementation.
+ *
+ * Handles:
+ * - Static HTML strings (passed through directly)
+ * - Template builder functions that return HTML strings
+ * - Handlebars-enhanced templates (detected by {{...}} syntax)
+ *
+ * When Handlebars syntax is detected, the template is processed
+ * with the HandlebarsRenderer for variable interpolation, conditionals,
+ * and loops.
+ *
+ * @example Static HTML
+ * ```typescript
+ * const template = '<div class="card">Hello World</div>';
+ * await htmlRenderer.render(template, context);
+ * ```
+ *
+ * @example Template function
+ * ```typescript
+ * const template = (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.name)}</div>`;
+ * await htmlRenderer.render(template, context);
+ * ```
+ *
+ * @example Handlebars template
+ * ```typescript
+ * const template = `
+ *   <div class="card">
+ *     <h2>{{escapeHtml output.title}}</h2>
+ *     {{#if output.items}}
+ *       <ul>
+ *         {{#each output.items}}
+ *           <li>{{this.name}}</li>
+ *         {{/each}}
+ *       </ul>
+ *     {{/if}}
+ *   </div>
+ * `;
+ * await htmlRenderer.render(template, context);
+ * ```
+ */
+class HtmlRenderer {
+    type = 'html';
+    priority = 0; // Lowest priority - fallback renderer
+    /**
+     * Check if this renderer can handle the given template.
+     *
+     * Accepts:
+     * - Any string (assumed to be HTML, with or without Handlebars)
+     * - Functions that are template builders (not React components)
+     */
+    canHandle(template) {
+        // String templates
+        if (typeof template === 'string') {
+            return true;
+        }
+        // Template builder functions
+        if (typeof template === 'function') {
+            return (0, detect_1.isTemplateBuilderFunction)(template);
+        }
+        return false;
+    }
+    /**
+     * Check if a template uses Handlebars syntax.
+     *
+     * @param template - Template string to check
+     * @returns true if template contains {{...}} syntax
+     */
+    usesHandlebars(template) {
+        return containsHandlebars(template);
+    }
+    /**
+     * Transpile the template.
+     *
+     * For HTML templates, no transpilation is needed.
+     * This method returns a dummy result for consistency.
+     */
+    async transpile(template, _options) {
+        const source = typeof template === 'string' ? template : template.toString();
+        const hash = (0, hash_1.hashString)(source);
+        return {
+            code: '', // No transpiled code needed
+            hash,
+            cached: true, // Always "cached" since no work is done
+        };
+    }
+    /**
+     * Render the template to HTML string.
+     *
+     * For static strings without Handlebars, returns the string directly.
+     * For strings with Handlebars syntax, processes with HandlebarsRenderer.
+     * For functions, calls the function with the context.
+     */
+    async render(template, context, _options) {
+        // Static HTML string
+        if (typeof template === 'string') {
+            // Check for Handlebars syntax
+            if (containsHandlebars(template)) {
+                return this.renderHandlebars(template, context);
+            }
+            return template;
+        }
+        // Template builder function
+        if (typeof template === 'function') {
+            const result = template(context);
+            // Check if the function result contains Handlebars
+            if (typeof result === 'string' && containsHandlebars(result)) {
+                return this.renderHandlebars(result, context);
+            }
+            return result;
+        }
+        // Fallback (should never reach here due to canHandle check)
+        return String(template);
+    }
+    /**
+     * Render Handlebars template with context.
+     */
+    async renderHandlebars(template, context) {
+        const renderer = await loadHandlebarsRenderer();
+        if (!renderer) {
+            // Handlebars not available, return template as-is with a warning comment
+            console.warn('[@frontmcp/ui] Template contains Handlebars syntax but handlebars is not installed. ' +
+                'Install it for template interpolation: npm install handlebars');
+            return template;
+        }
+        return renderer.render(template, {
+            input: context.input,
+            output: context.output,
+            structuredContent: context.structuredContent,
+        });
+    }
+    /**
+     * Get runtime scripts for client-side functionality.
+     *
+     * HTML templates don't need additional runtime scripts.
+     */
+    getRuntimeScripts(_platform) {
+        return {
+            headScripts: '',
+            isInline: false,
+        };
+    }
+}
+exports.HtmlRenderer = HtmlRenderer;
+/**
+ * Singleton instance of the HTML renderer.
+ */
+exports.htmlRenderer = new HtmlRenderer();
+//# sourceMappingURL=html.renderer.js.map

package/src/renderers/html.renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.renderer.js","sourceRoot":"","sources":["../../../src/renderers/html.renderer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTML Renderer\n *\n * Handles plain HTML templates:\n * - Static HTML strings\n * - Template builder functions: (ctx) => string\n * - Handlebars-enhanced templates: HTML with {{variable}} syntax\n *\n * This is the default fallback renderer with the lowest priority.\n */\n\nimport type { TemplateContext } from '../runtime/types';\nimport type { PlatformCapabilities } from '../theme';\nimport type { UIRenderer, TranspileResult, TranspileOptions, RenderOptions, RuntimeScripts } from './types';\nimport { isTemplateBuilderFunction } from './utils/detect';\nimport { hashString } from './utils/hash';\n\n/**\n * Template builder function type.\n */\ntype TemplateBuilderFn<In, Out> = (ctx: TemplateContext<In, Out>) => string;\n\n/**\n * Types this renderer can handle.\n */\ntype HtmlTemplate<In = unknown, Out = unknown> = string | TemplateBuilderFn<In, Out>;\n\n/**\n * Lazy-loaded HandlebarsRenderer for Handlebars template support.\n */\nlet handlebarsRenderer: {\n  render: (\n    template: string,\n    context: { input: unknown; output: unknown; structuredContent?: unknown },\n  ) => Promise<string>;\n  containsHandlebars: (template: string) => boolean;\n} | null = null;\n\n/**\n * Load HandlebarsRenderer if available.\n */\nasync function loadHandlebarsRenderer(): Promise<typeof handlebarsRenderer> {\n  if (handlebarsRenderer !== null) {\n    return handlebarsRenderer;\n  }\n\n  try {\n    // Dynamic import with explicit .js extension for ESM compatibility\n    const handlebarsModule = await import(/* webpackIgnore: true */ '../handlebars/index.js');\n    const { HandlebarsRenderer } = handlebarsModule;\n    const renderer = new HandlebarsRenderer();\n    handlebarsRenderer = {\n      render: (template: string, context: { input: unknown; output: unknown; structuredContent?: unknown }) =>\n        renderer.render(template, {\n          input: (context.input ?? {}) as Record<string, unknown>,\n          output: context.output,\n          structuredContent: context.structuredContent,\n        }),\n      containsHandlebars: (template: string) => HandlebarsRenderer.containsHandlebars(template),\n    };\n    return handlebarsRenderer;\n  } catch {\n    // Handlebars not available, return null\n    return null;\n  }\n}\n\n/**\n * Check if a template contains Handlebars syntax.\n * Non-async version for canHandle check.\n */\nfunction containsHandlebars(template: string): boolean {\n  // Match {{...}} but not {{! comments }}\n  return /\\{\\{(?!!)[\\s\\S]*?\\}\\}/.test(template);\n}\n\n/**\n * HTML Renderer Implementation.\n *\n * Handles:\n * - Static HTML strings (passed through directly)\n * - Template builder functions that return HTML strings\n * - Handlebars-enhanced templates (detected by {{...}} syntax)\n *\n * When Handlebars syntax is detected, the template is processed\n * with the HandlebarsRenderer for variable interpolation, conditionals,\n * and loops.\n *\n * @example Static HTML\n * ```typescript\n * const template = '<div class=\"card\">Hello World</div>';\n * await htmlRenderer.render(template, context);\n * ```\n *\n * @example Template function\n * ```typescript\n * const template = (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.name)}</div>`;\n * await htmlRenderer.render(template, context);\n * ```\n *\n * @example Handlebars template\n * ```typescript\n * const template = `\n *   <div class=\"card\">\n *     <h2>{{escapeHtml output.title}}</h2>\n *     {{#if output.items}}\n *       <ul>\n *         {{#each output.items}}\n *           <li>{{this.name}}</li>\n *         {{/each}}\n *       </ul>\n *     {{/if}}\n *   </div>\n * `;\n * await htmlRenderer.render(template, context);\n * ```\n */\nexport class HtmlRenderer implements UIRenderer<HtmlTemplate> {\n  readonly type = 'html' as const;\n  readonly priority = 0; // Lowest priority - fallback renderer\n\n  /**\n   * Check if this renderer can handle the given template.\n   *\n   * Accepts:\n   * - Any string (assumed to be HTML, with or without Handlebars)\n   * - Functions that are template builders (not React components)\n   */\n  canHandle(template: unknown): template is HtmlTemplate {\n    // String templates\n    if (typeof template === 'string') {\n      return true;\n    }\n\n    // Template builder functions\n    if (typeof template === 'function') {\n      return isTemplateBuilderFunction(template as Function);\n    }\n\n    return false;\n  }\n\n  /**\n   * Check if a template uses Handlebars syntax.\n   *\n   * @param template - Template string to check\n   * @returns true if template contains {{...}} syntax\n   */\n  usesHandlebars(template: string): boolean {\n    return containsHandlebars(template);\n  }\n\n  /**\n   * Transpile the template.\n   *\n   * For HTML templates, no transpilation is needed.\n   * This method returns a dummy result for consistency.\n   */\n  async transpile(template: HtmlTemplate, _options?: TranspileOptions): Promise<TranspileResult> {\n    const source = typeof template === 'string' ? template : template.toString();\n    const hash = hashString(source);\n\n    return {\n      code: '', // No transpiled code needed\n      hash,\n      cached: true, // Always \"cached\" since no work is done\n    };\n  }\n\n  /**\n   * Render the template to HTML string.\n   *\n   * For static strings without Handlebars, returns the string directly.\n   * For strings with Handlebars syntax, processes with HandlebarsRenderer.\n   * For functions, calls the function with the context.\n   */\n  async render<In, Out>(\n    template: HtmlTemplate<In, Out>,\n    context: TemplateContext<In, Out>,\n    _options?: RenderOptions,\n  ): Promise<string> {\n    // Static HTML string\n    if (typeof template === 'string') {\n      // Check for Handlebars syntax\n      if (containsHandlebars(template)) {\n        return this.renderHandlebars(template, context);\n      }\n      return template;\n    }\n\n    // Template builder function\n    if (typeof template === 'function') {\n      const result = template(context);\n      // Check if the function result contains Handlebars\n      if (typeof result === 'string' && containsHandlebars(result)) {\n        return this.renderHandlebars(result, context);\n      }\n      return result;\n    }\n\n    // Fallback (should never reach here due to canHandle check)\n    return String(template);\n  }\n\n  /**\n   * Render Handlebars template with context.\n   */\n  private async renderHandlebars<In, Out>(template: string, context: TemplateContext<In, Out>): Promise<string> {\n    const renderer = await loadHandlebarsRenderer();\n\n    if (!renderer) {\n      // Handlebars not available, return template as-is with a warning comment\n      console.warn(\n        '[@frontmcp/ui] Template contains Handlebars syntax but handlebars is not installed. ' +\n          'Install it for template interpolation: npm install handlebars',\n      );\n      return template;\n    }\n\n    return renderer.render(template, {\n      input: context.input as Record<string, unknown>,\n      output: context.output,\n      structuredContent: context.structuredContent,\n    });\n  }\n\n  /**\n   * Get runtime scripts for client-side functionality.\n   *\n   * HTML templates don't need additional runtime scripts.\n   */\n  getRuntimeScripts(_platform: PlatformCapabilities): RuntimeScripts {\n    return {\n      headScripts: '',\n      isInline: false,\n    };\n  }\n}\n\n/**\n * Singleton instance of the HTML renderer.\n */\nexport const htmlRenderer = new HtmlRenderer();\n\n/**\n * Check if a template string contains Handlebars syntax.\n *\n * @param template - Template string\n * @returns true if contains {{...}}\n */\nexport { containsHandlebars };\n"]}

package/src/renderers/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Renderer Module
+ *
+ * Multi-framework rendering system for Tool UI templates.
+ * Supports HTML, React, and MDX templates with auto-detection.
+ *
+ * @module @frontmcp/ui
+ *
+ * @example Basic usage with auto-detection
+ * ```typescript
+ * import { rendererRegistry } from '@frontmcp/ui';
+ *
+ * // HTML template
+ * const htmlTemplate = (ctx) => `<div>${ctx.output.name}</div>`;
+ * const result = await rendererRegistry.render(htmlTemplate, context);
+ * ```
+ *
+ * @example Register React renderer
+ * ```typescript
+ * import { rendererRegistry, reactRenderer } from '@frontmcp/ui';
+ *
+ * rendererRegistry.register(reactRenderer);
+ *
+ * // Now React components are auto-detected
+ * const MyComponent = ({ output }) => <div>{output.name}</div>;
+ * const result = await rendererRegistry.render(MyComponent, context);
+ * ```
+ */
+export type { RendererType, UIRenderer, ToolUIProps, HydratedToolUIProps, TranspileResult, TranspileOptions, RenderOptions, RuntimeScripts, RenderResult, RendererRegistryOptions, DetectionResult, ReactComponentType, WrapperContext, ExtendedToolUIConfig, } from './types';
+export { TranspileCache, transpileCache, renderCache, type TranspileCacheOptions } from './cache';
+export { RendererRegistry, rendererRegistry } from './registry';
+export { HtmlRenderer, htmlRenderer } from './html.renderer';
+export { ReactRenderer, reactRenderer, buildHydrationScript } from './react.renderer';
+export { MdxRenderer, mdxRenderer, buildMdxHydrationScript } from './mdx.renderer';
+export { isReactComponent, isTemplateBuilderFunction, containsJsx, containsMdxSyntax, isPlainHtml, detectTemplateType, hashString, hashCombined, isHash, transpileJsx, isSwcAvailable, executeTranspiledCode, transpileAndExecute, } from './utils';

package/src/renderers/index.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Renderer Module
+ *
+ * Multi-framework rendering system for Tool UI templates.
+ * Supports HTML, React, and MDX templates with auto-detection.
+ *
+ * @module @frontmcp/ui
+ *
+ * @example Basic usage with auto-detection
+ * ```typescript
+ * import { rendererRegistry } from '@frontmcp/ui';
+ *
+ * // HTML template
+ * const htmlTemplate = (ctx) => `<div>${ctx.output.name}</div>`;
+ * const result = await rendererRegistry.render(htmlTemplate, context);
+ * ```
+ *
+ * @example Register React renderer
+ * ```typescript
+ * import { rendererRegistry, reactRenderer } from '@frontmcp/ui';
+ *
+ * rendererRegistry.register(reactRenderer);
+ *
+ * // Now React components are auto-detected
+ * const MyComponent = ({ output }) => <div>{output.name}</div>;
+ * const result = await rendererRegistry.render(MyComponent, context);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transpileAndExecute = exports.executeTranspiledCode = exports.isSwcAvailable = exports.transpileJsx = exports.isHash = exports.hashCombined = exports.hashString = exports.detectTemplateType = exports.isPlainHtml = exports.containsMdxSyntax = exports.containsJsx = exports.isTemplateBuilderFunction = exports.isReactComponent = exports.buildMdxHydrationScript = exports.mdxRenderer = exports.MdxRenderer = exports.buildHydrationScript = exports.reactRenderer = exports.ReactRenderer = exports.htmlRenderer = exports.HtmlRenderer = exports.rendererRegistry = exports.RendererRegistry = exports.renderCache = exports.transpileCache = exports.TranspileCache = void 0;
+// Cache
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "TranspileCache", { enumerable: true, get: function () { return cache_1.TranspileCache; } });
+Object.defineProperty(exports, "transpileCache", { enumerable: true, get: function () { return cache_1.transpileCache; } });
+Object.defineProperty(exports, "renderCache", { enumerable: true, get: function () { return cache_1.renderCache; } });
+// Registry
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "RendererRegistry", { enumerable: true, get: function () { return registry_1.RendererRegistry; } });
+Object.defineProperty(exports, "rendererRegistry", { enumerable: true, get: function () { return registry_1.rendererRegistry; } });
+// HTML Renderer (built-in)
+var html_renderer_1 = require("./html.renderer");
+Object.defineProperty(exports, "HtmlRenderer", { enumerable: true, get: function () { return html_renderer_1.HtmlRenderer; } });
+Object.defineProperty(exports, "htmlRenderer", { enumerable: true, get: function () { return html_renderer_1.htmlRenderer; } });
+// React Renderer
+var react_renderer_1 = require("./react.renderer");
+Object.defineProperty(exports, "ReactRenderer", { enumerable: true, get: function () { return react_renderer_1.ReactRenderer; } });
+Object.defineProperty(exports, "reactRenderer", { enumerable: true, get: function () { return react_renderer_1.reactRenderer; } });
+Object.defineProperty(exports, "buildHydrationScript", { enumerable: true, get: function () { return react_renderer_1.buildHydrationScript; } });
+// MDX Renderer
+var mdx_renderer_1 = require("./mdx.renderer");
+Object.defineProperty(exports, "MdxRenderer", { enumerable: true, get: function () { return mdx_renderer_1.MdxRenderer; } });
+Object.defineProperty(exports, "mdxRenderer", { enumerable: true, get: function () { return mdx_renderer_1.mdxRenderer; } });
+Object.defineProperty(exports, "buildMdxHydrationScript", { enumerable: true, get: function () { return mdx_renderer_1.buildMdxHydrationScript; } });
+// Utilities
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "isReactComponent", { enumerable: true, get: function () { return utils_1.isReactComponent; } });
+Object.defineProperty(exports, "isTemplateBuilderFunction", { enumerable: true, get: function () { return utils_1.isTemplateBuilderFunction; } });
+Object.defineProperty(exports, "containsJsx", { enumerable: true, get: function () { return utils_1.containsJsx; } });
+Object.defineProperty(exports, "containsMdxSyntax", { enumerable: true, get: function () { return utils_1.containsMdxSyntax; } });
+Object.defineProperty(exports, "isPlainHtml", { enumerable: true, get: function () { return utils_1.isPlainHtml; } });
+Object.defineProperty(exports, "detectTemplateType", { enumerable: true, get: function () { return utils_1.detectTemplateType; } });
+Object.defineProperty(exports, "hashString", { enumerable: true, get: function () { return utils_1.hashString; } });
+Object.defineProperty(exports, "hashCombined", { enumerable: true, get: function () { return utils_1.hashCombined; } });
+Object.defineProperty(exports, "isHash", { enumerable: true, get: function () { return utils_1.isHash; } });
+Object.defineProperty(exports, "transpileJsx", { enumerable: true, get: function () { return utils_1.transpileJsx; } });
+Object.defineProperty(exports, "isSwcAvailable", { enumerable: true, get: function () { return utils_1.isSwcAvailable; } });
+Object.defineProperty(exports, "executeTranspiledCode", { enumerable: true, get: function () { return utils_1.executeTranspiledCode; } });
+Object.defineProperty(exports, "transpileAndExecute", { enumerable: true, get: function () { return utils_1.transpileAndExecute; } });
+//# sourceMappingURL=index.js.map

package/src/renderers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/renderers/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;AAsBH,QAAQ;AACR,iCAAkG;AAAzF,uGAAA,cAAc,OAAA;AAAE,uGAAA,cAAc,OAAA;AAAE,oGAAA,WAAW,OAAA;AAEpD,WAAW;AACX,uCAAgE;AAAvD,4GAAA,gBAAgB,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAE3C,2BAA2B;AAC3B,iDAA6D;AAApD,6GAAA,YAAY,OAAA;AAAE,6GAAA,YAAY,OAAA;AAEnC,iBAAiB;AACjB,mDAAsF;AAA7E,+GAAA,aAAa,OAAA;AAAE,+GAAA,aAAa,OAAA;AAAE,sHAAA,oBAAoB,OAAA;AAE3D,eAAe;AACf,+CAAmF;AAA1E,2GAAA,WAAW,OAAA;AAAE,2GAAA,WAAW,OAAA;AAAE,uHAAA,uBAAuB,OAAA;AAE1D,YAAY;AACZ,iCAciB;AAbf,yGAAA,gBAAgB,OAAA;AAChB,kHAAA,yBAAyB,OAAA;AACzB,oGAAA,WAAW,OAAA;AACX,0GAAA,iBAAiB,OAAA;AACjB,oGAAA,WAAW,OAAA;AACX,2GAAA,kBAAkB,OAAA;AAClB,mGAAA,UAAU,OAAA;AACV,qGAAA,YAAY,OAAA;AACZ,+FAAA,MAAM,OAAA;AACN,qGAAA,YAAY,OAAA;AACZ,uGAAA,cAAc,OAAA;AACd,8GAAA,qBAAqB,OAAA;AACrB,4GAAA,mBAAmB,OAAA","sourcesContent":["/**\n * Renderer Module\n *\n * Multi-framework rendering system for Tool UI templates.\n * Supports HTML, React, and MDX templates with auto-detection.\n *\n * @module @frontmcp/ui\n *\n * @example Basic usage with auto-detection\n * ```typescript\n * import { rendererRegistry } from '@frontmcp/ui';\n *\n * // HTML template\n * const htmlTemplate = (ctx) => `<div>${ctx.output.name}</div>`;\n * const result = await rendererRegistry.render(htmlTemplate, context);\n * ```\n *\n * @example Register React renderer\n * ```typescript\n * import { rendererRegistry, reactRenderer } from '@frontmcp/ui';\n *\n * rendererRegistry.register(reactRenderer);\n *\n * // Now React components are auto-detected\n * const MyComponent = ({ output }) => <div>{output.name}</div>;\n * const result = await rendererRegistry.render(MyComponent, context);\n * ```\n */\n\n// Types\n// Note: TemplateBuilderFn and ToolUITemplate are exported from ../runtime/types\n// to avoid duplication with the main runtime exports\nexport type {\n  RendererType,\n  UIRenderer,\n  ToolUIProps,\n  HydratedToolUIProps,\n  TranspileResult,\n  TranspileOptions,\n  RenderOptions,\n  RuntimeScripts,\n  RenderResult,\n  RendererRegistryOptions,\n  DetectionResult,\n  ReactComponentType,\n  WrapperContext,\n  ExtendedToolUIConfig,\n} from './types';\n\n// Cache\nexport { TranspileCache, transpileCache, renderCache, type TranspileCacheOptions } from './cache';\n\n// Registry\nexport { RendererRegistry, rendererRegistry } from './registry';\n\n// HTML Renderer (built-in)\nexport { HtmlRenderer, htmlRenderer } from './html.renderer';\n\n// React Renderer\nexport { ReactRenderer, reactRenderer, buildHydrationScript } from './react.renderer';\n\n// MDX Renderer\nexport { MdxRenderer, mdxRenderer, buildMdxHydrationScript } from './mdx.renderer';\n\n// Utilities\nexport {\n  isReactComponent,\n  isTemplateBuilderFunction,\n  containsJsx,\n  containsMdxSyntax,\n  isPlainHtml,\n  detectTemplateType,\n  hashString,\n  hashCombined,\n  isHash,\n  transpileJsx,\n  isSwcAvailable,\n  executeTranspiledCode,\n  transpileAndExecute,\n} from './utils';\n"]}

package/src/renderers/mdx.renderer.d.ts

@@ -0,0 +1,119 @@
+/**
+ * MDX Renderer
+ *
+ * Handles MDX templates - Markdown with embedded JSX components.
+ * Uses @mdx-js/mdx for compilation and react-dom/server for SSR.
+ *
+ * MDX allows mixing Markdown with React components:
+ * - Markdown headings, lists, code blocks
+ * - JSX component tags: `<Card />`
+ * - JS expressions: `{output.items.map(...)}`
+ * - Frontmatter for metadata
+ */
+import type { TemplateContext } from '../runtime/types';
+import type { PlatformCapabilities } from '../theme';
+import type { UIRenderer, TranspileResult, TranspileOptions, RenderOptions, RuntimeScripts } from './types';
+/**
+ * Types this renderer can handle - MDX strings.
+ */
+type MdxTemplate = string;
+/**
+ * MDX Renderer Implementation.
+ *
+ * Compiles MDX (Markdown + JSX) to React components using @mdx-js/mdx,
+ * then renders to HTML using react-dom/server.
+ *
+ * @example Basic MDX template
+ * ```typescript
+ * @Tool({
+ *   ui: {
+ *     template: `
+ * # User Profile
+ *
+ * <UserCard name={output.name} email={output.email} />
+ *
+ * ## Recent Activity
+ * {output.items.map(item => <ActivityItem key={item.id} {...item} />)}
+ *     `,
+ *     mdxComponents: { UserCard, ActivityItem }
+ *   }
+ * })
+ * ```
+ *
+ * @example MDX with frontmatter
+ * ```typescript
+ * @Tool({
+ *   ui: {
+ *     template: `
+ * ---
+ * title: Dashboard
+ * ---
+ *
+ * # {frontmatter.title}
+ *
+ * <Dashboard data={output} />
+ *     `
+ *   }
+ * })
+ * ```
+ */
+export declare class MdxRenderer implements UIRenderer<MdxTemplate> {
+    readonly type: "mdx";
+    readonly priority = 10;
+    /**
+     * Lazy-loaded modules.
+     */
+    private React;
+    private ReactDOMServer;
+    private jsxRuntime;
+    private mdxEvaluate;
+    /**
+     * Check if this renderer can handle the given template.
+     *
+     * Accepts strings containing MDX syntax (Markdown + JSX).
+     */
+    canHandle(template: unknown): template is MdxTemplate;
+    /**
+     * Transpile MDX to executable JavaScript.
+     *
+     * Uses @mdx-js/mdx to compile MDX source to a module.
+     * Note: For MDX, we use evaluate() which combines compile + run,
+     * so this method just returns the source hash for caching purposes.
+     */
+    transpile(template: MdxTemplate, _options?: TranspileOptions): Promise<TranspileResult>;
+    /**
+     * Render MDX template to HTML string.
+     *
+     * Uses @mdx-js/mdx's evaluate() for clean compilation + execution,
+     * then renders the resulting React component to HTML via SSR.
+     */
+    render<In, Out>(template: MdxTemplate, context: TemplateContext<In, Out>, options?: RenderOptions): Promise<string>;
+    /**
+     * Get runtime scripts for client-side functionality.
+     */
+    getRuntimeScripts(platform: PlatformCapabilities): RuntimeScripts;
+    /**
+     * Load React and ReactDOMServer modules.
+     */
+    private loadReact;
+    /**
+     * Load @mdx-js/mdx evaluate function.
+     *
+     * evaluate() is the cleanest way to run MDX - it combines
+     * compile and run in a single step, handling all the runtime
+     * injection automatically.
+     */
+    private loadMdx;
+}
+/**
+ * Singleton instance of the MDX renderer.
+ */
+export declare const mdxRenderer: MdxRenderer;
+/**
+ * Build MDX hydration script for client-side interactivity.
+ *
+ * Note: MDX hydration is more complex than React hydration
+ * because it needs the MDX runtime and component definitions.
+ */
+export declare function buildMdxHydrationScript(): string;
+export {};