@frontmcp/ui 0.5.0

package/src/renderers/mdx.renderer.js

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mdxRenderer = exports.MdxRenderer = void 0;
+exports.buildMdxHydrationScript = buildMdxHydrationScript;
+const detect_1 = require("./utils/detect");
+const hash_1 = require("./utils/hash");
+const cache_1 = require("./cache");
+/**
+ * Runtime CDN URLs (same as React since MDX compiles to React).
+ */
+const REACT_CDN = {
+    react: 'https://unpkg.com/react@18/umd/react.production.min.js',
+    reactDom: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',
+};
+/**
+ * Placeholder for blocked-network platforms.
+ */
+const INLINE_MDX_PLACEHOLDER = `
+// MDX runtime not available inline yet.
+// For blocked-network platforms, use pre-rendered HTML templates.
+console.warn('[FrontMCP] MDX hydration not available on this platform.');
+`;
+/**
+ * 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} />
+ *     `
+ *   }
+ * })
+ * ```
+ */
+class MdxRenderer {
+    type = 'mdx';
+    priority = 10; // Between HTML (0) and React (20)
+    /**
+     * Lazy-loaded modules.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    React = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ReactDOMServer = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    jsxRuntime = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mdxEvaluate = null;
+    /**
+     * Check if this renderer can handle the given template.
+     *
+     * Accepts strings containing MDX syntax (Markdown + JSX).
+     */
+    canHandle(template) {
+        if (typeof template !== 'string') {
+            return false;
+        }
+        return (0, detect_1.containsMdxSyntax)(template);
+    }
+    /**
+     * 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.
+     */
+    async transpile(template, _options) {
+        const hash = (0, hash_1.hashString)(template);
+        // Check cache - for MDX, the "code" is just the original source
+        // since we use evaluate() which handles compilation internally
+        const cached = cache_1.transpileCache.getByKey(hash);
+        if (cached) {
+            return { ...cached, cached: true };
+        }
+        const transpileResult = {
+            code: template, // Store original MDX for evaluate()
+            hash,
+            cached: false,
+        };
+        // Cache the result
+        cache_1.transpileCache.setByKey(hash, transpileResult);
+        return 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.
+     */
+    async render(template, context, options) {
+        // Ensure dependencies are loaded
+        await this.loadReact();
+        await this.loadMdx();
+        if (!this.mdxEvaluate) {
+            throw new Error('MDX compilation requires @mdx-js/mdx. Install it: npm install @mdx-js/mdx');
+        }
+        // Create a cache key based on the template hash
+        const templateHash = (0, hash_1.hashString)(template);
+        const cacheKey = `mdx-component:${templateHash}`;
+        // Check component cache
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let Content = cache_1.componentCache.get(cacheKey);
+        if (!Content) {
+            // Evaluate MDX source to get the component
+            // evaluate() combines compile + run in one step
+            const result = await this.mdxEvaluate(template, {
+                ...this.jsxRuntime,
+                Fragment: this.React.Fragment,
+                development: false,
+            });
+            Content = result.default;
+            // Cache the compiled component
+            cache_1.componentCache.set(cacheKey, Content);
+        }
+        // Build component map with custom MDX components
+        const mdxComponents = {
+            // User-provided components from tool config
+            ...options?.mdxComponents,
+            // Wrapper that provides context to the content
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            wrapper: ({ children }) => {
+                return this.React.createElement('div', { className: 'mdx-content' }, children);
+            },
+        };
+        // Create props that MDX can access
+        // These become available in MDX as {props.input}, {props.output}, etc.
+        const props = {
+            input: context.input,
+            output: context.output,
+            structuredContent: context.structuredContent,
+            helpers: context.helpers,
+        };
+        // Also spread output properties at top level for convenience
+        // This allows accessing {output.name} or just {name} in MDX
+        const spreadProps = {
+            ...props,
+            ...(typeof context.output === 'object' && context.output !== null ? context.output : {}),
+        };
+        // Create the element with components and props
+        const element = this.React.createElement(Content, {
+            components: mdxComponents,
+            ...spreadProps,
+        });
+        // Render to HTML
+        const html = this.ReactDOMServer.renderToString(element);
+        // If hydration is enabled, wrap with markers
+        if (options?.hydrate) {
+            // Full HTML attribute escaping to prevent XSS
+            const escapedProps = JSON.stringify(props)
+                .replace(/&/g, '&amp;')
+                .replace(/'/g, '&#39;')
+                .replace(/</g, '&lt;')
+                .replace(/>/g, '&gt;');
+            return `<div data-mdx-hydrate="true" data-props='${escapedProps}'>${html}</div>`;
+        }
+        return html;
+    }
+    /**
+     * Get runtime scripts for client-side functionality.
+     */
+    getRuntimeScripts(platform) {
+        // For blocked-network platforms (Claude), scripts must be inline
+        if (platform.networkMode === 'blocked') {
+            return {
+                headScripts: '',
+                inlineScripts: INLINE_MDX_PLACEHOLDER,
+                isInline: true,
+            };
+        }
+        // For platforms with network access, use CDN (React required for MDX)
+        return {
+            headScripts: `
+        <script crossorigin src="${REACT_CDN.react}"></script>
+        <script crossorigin src="${REACT_CDN.reactDom}"></script>
+      `,
+            isInline: false,
+        };
+    }
+    /**
+     * Load React and ReactDOMServer modules.
+     */
+    async loadReact() {
+        if (this.React && this.ReactDOMServer && this.jsxRuntime) {
+            return;
+        }
+        try {
+            const [react, reactDomServer, jsxRuntime] = await Promise.all([
+                import('react'),
+                import('react-dom/server'),
+                import('react/jsx-runtime'),
+            ]);
+            this.React = react;
+            this.ReactDOMServer = reactDomServer;
+            this.jsxRuntime = jsxRuntime;
+        }
+        catch {
+            throw new Error('React is required for MdxRenderer. Install react and react-dom: npm install react react-dom');
+        }
+    }
+    /**
+     * 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.
+     */
+    async loadMdx() {
+        if (this.mdxEvaluate) {
+            return;
+        }
+        try {
+            const mdx = await import('@mdx-js/mdx');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            this.mdxEvaluate = mdx.evaluate;
+        }
+        catch {
+            console.warn('[@frontmcp/ui] @mdx-js/mdx not available. MDX rendering disabled. ' +
+                'Install @mdx-js/mdx to enable: npm install @mdx-js/mdx');
+        }
+    }
+}
+exports.MdxRenderer = MdxRenderer;
+/**
+ * Singleton instance of the MDX renderer.
+ */
+exports.mdxRenderer = new 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.
+ */
+function buildMdxHydrationScript() {
+    return `
+<script>
+(function() {
+  // MDX hydration requires React and component definitions
+  if (typeof React === 'undefined' || typeof ReactDOM === 'undefined') {
+    console.warn('[FrontMCP] React not available for MDX hydration');
+    return;
+  }
+
+  // Find all elements marked for MDX hydration
+  document.querySelectorAll('[data-mdx-hydrate]').forEach(function(root) {
+    var propsJson = root.getAttribute('data-props');
+    var props = propsJson ? JSON.parse(propsJson) : {};
+
+    // MDX content is pre-rendered, hydration mainly attaches event handlers
+    // For full interactivity, components need to be available client-side
+    if (window.__frontmcp_mdx_content) {
+      try {
+        ReactDOM.hydrateRoot(root, React.createElement(
+          window.__frontmcp_mdx_content,
+          props
+        ));
+      } catch (e) {
+        console.error('[FrontMCP] MDX hydration failed', e);
+      }
+    }
+  });
+})();
+</script>
+`;
+}
+//# sourceMappingURL=mdx.renderer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mdx.renderer.js","sourceRoot":"","sources":["../../../src/renderers/mdx.renderer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MDX Renderer\n *\n * Handles MDX templates - Markdown with embedded JSX components.\n * Uses @mdx-js/mdx for compilation and react-dom/server for SSR.\n *\n * MDX allows mixing Markdown with React components:\n * - Markdown headings, lists, code blocks\n * - JSX component tags: `<Card />`\n * - JS expressions: `{output.items.map(...)}`\n * - Frontmatter for metadata\n */\n\nimport type { TemplateContext } from '../runtime/types';\nimport type { PlatformCapabilities } from '../theme';\nimport type {\n  UIRenderer,\n  TranspileResult,\n  TranspileOptions,\n  RenderOptions,\n  RuntimeScripts,\n  ToolUIProps,\n} from './types';\nimport { containsMdxSyntax } from './utils/detect';\nimport { hashString } from './utils/hash';\nimport { transpileCache, componentCache } from './cache';\n\n/**\n * Types this renderer can handle - MDX strings.\n */\ntype MdxTemplate = string;\n\n/**\n * Runtime CDN URLs (same as React since MDX compiles to React).\n */\nconst REACT_CDN = {\n  react: 'https://unpkg.com/react@18/umd/react.production.min.js',\n  reactDom: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',\n};\n\n/**\n * Placeholder for blocked-network platforms.\n */\nconst INLINE_MDX_PLACEHOLDER = `\n// MDX runtime not available inline yet.\n// For blocked-network platforms, use pre-rendered HTML templates.\nconsole.warn('[FrontMCP] MDX hydration not available on this platform.');\n`;\n\n/**\n * MDX Renderer Implementation.\n *\n * Compiles MDX (Markdown + JSX) to React components using @mdx-js/mdx,\n * then renders to HTML using react-dom/server.\n *\n * @example Basic MDX template\n * ```typescript\n * @Tool({\n *   ui: {\n *     template: `\n * # User Profile\n *\n * <UserCard name={output.name} email={output.email} />\n *\n * ## Recent Activity\n * {output.items.map(item => <ActivityItem key={item.id} {...item} />)}\n *     `,\n *     mdxComponents: { UserCard, ActivityItem }\n *   }\n * })\n * ```\n *\n * @example MDX with frontmatter\n * ```typescript\n * @Tool({\n *   ui: {\n *     template: `\n * ---\n * title: Dashboard\n * ---\n *\n * # {frontmatter.title}\n *\n * <Dashboard data={output} />\n *     `\n *   }\n * })\n * ```\n */\nexport class MdxRenderer implements UIRenderer<MdxTemplate> {\n  readonly type = 'mdx' as const;\n  readonly priority = 10; // Between HTML (0) and React (20)\n\n  /**\n   * Lazy-loaded modules.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  private React: any = null;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  private ReactDOMServer: any = null;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  private jsxRuntime: any = null;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  private mdxEvaluate: ((source: string, options: object) => Promise<{ default: any }>) | null = null;\n\n  /**\n   * Check if this renderer can handle the given template.\n   *\n   * Accepts strings containing MDX syntax (Markdown + JSX).\n   */\n  canHandle(template: unknown): template is MdxTemplate {\n    if (typeof template !== 'string') {\n      return false;\n    }\n\n    return containsMdxSyntax(template);\n  }\n\n  /**\n   * Transpile MDX to executable JavaScript.\n   *\n   * Uses @mdx-js/mdx to compile MDX source to a module.\n   * Note: For MDX, we use evaluate() which combines compile + run,\n   * so this method just returns the source hash for caching purposes.\n   */\n  async transpile(template: MdxTemplate, _options?: TranspileOptions): Promise<TranspileResult> {\n    const hash = hashString(template);\n\n    // Check cache - for MDX, the \"code\" is just the original source\n    // since we use evaluate() which handles compilation internally\n    const cached = transpileCache.getByKey(hash);\n    if (cached) {\n      return { ...cached, cached: true };\n    }\n\n    const transpileResult: TranspileResult = {\n      code: template, // Store original MDX for evaluate()\n      hash,\n      cached: false,\n    };\n\n    // Cache the result\n    transpileCache.setByKey(hash, transpileResult);\n\n    return transpileResult;\n  }\n\n  /**\n   * Render MDX template to HTML string.\n   *\n   * Uses @mdx-js/mdx's evaluate() for clean compilation + execution,\n   * then renders the resulting React component to HTML via SSR.\n   */\n  async render<In, Out>(\n    template: MdxTemplate,\n    context: TemplateContext<In, Out>,\n    options?: RenderOptions,\n  ): Promise<string> {\n    // Ensure dependencies are loaded\n    await this.loadReact();\n    await this.loadMdx();\n\n    if (!this.mdxEvaluate) {\n      throw new Error('MDX compilation requires @mdx-js/mdx. Install it: npm install @mdx-js/mdx');\n    }\n\n    // Create a cache key based on the template hash\n    const templateHash = hashString(template);\n    const cacheKey = `mdx-component:${templateHash}`;\n\n    // Check component cache\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let Content: any = componentCache.get(cacheKey);\n\n    if (!Content) {\n      // Evaluate MDX source to get the component\n      // evaluate() combines compile + run in one step\n      const result = await this.mdxEvaluate(template, {\n        ...this.jsxRuntime,\n        Fragment: this.React.Fragment,\n        development: false,\n      });\n\n      Content = result.default;\n\n      // Cache the compiled component\n      componentCache.set(cacheKey, Content);\n    }\n\n    // Build component map with custom MDX components\n    const mdxComponents = {\n      // User-provided components from tool config\n      ...options?.mdxComponents,\n      // Wrapper that provides context to the content\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      wrapper: ({ children }: { children: any }) => {\n        return this.React.createElement('div', { className: 'mdx-content' }, children);\n      },\n    };\n\n    // Create props that MDX can access\n    // These become available in MDX as {props.input}, {props.output}, etc.\n    const props: ToolUIProps<In, Out> = {\n      input: context.input,\n      output: context.output,\n      structuredContent: context.structuredContent,\n      helpers: context.helpers,\n    };\n\n    // Also spread output properties at top level for convenience\n    // This allows accessing {output.name} or just {name} in MDX\n    const spreadProps = {\n      ...props,\n      ...(typeof context.output === 'object' && context.output !== null ? context.output : {}),\n    };\n\n    // Create the element with components and props\n    const element = this.React.createElement(Content, {\n      components: mdxComponents,\n      ...spreadProps,\n    });\n\n    // Render to HTML\n    const html = this.ReactDOMServer.renderToString(element);\n\n    // If hydration is enabled, wrap with markers\n    if (options?.hydrate) {\n      // Full HTML attribute escaping to prevent XSS\n      const escapedProps = JSON.stringify(props)\n        .replace(/&/g, '&amp;')\n        .replace(/'/g, '&#39;')\n        .replace(/</g, '&lt;')\n        .replace(/>/g, '&gt;');\n      return `<div data-mdx-hydrate=\"true\" data-props='${escapedProps}'>${html}</div>`;\n    }\n\n    return html;\n  }\n\n  /**\n   * Get runtime scripts for client-side functionality.\n   */\n  getRuntimeScripts(platform: PlatformCapabilities): RuntimeScripts {\n    // For blocked-network platforms (Claude), scripts must be inline\n    if (platform.networkMode === 'blocked') {\n      return {\n        headScripts: '',\n        inlineScripts: INLINE_MDX_PLACEHOLDER,\n        isInline: true,\n      };\n    }\n\n    // For platforms with network access, use CDN (React required for MDX)\n    return {\n      headScripts: `\n        <script crossorigin src=\"${REACT_CDN.react}\"></script>\n        <script crossorigin src=\"${REACT_CDN.reactDom}\"></script>\n      `,\n      isInline: false,\n    };\n  }\n\n  /**\n   * Load React and ReactDOMServer modules.\n   */\n  private async loadReact(): Promise<void> {\n    if (this.React && this.ReactDOMServer && this.jsxRuntime) {\n      return;\n    }\n\n    try {\n      const [react, reactDomServer, jsxRuntime] = await Promise.all([\n        import('react'),\n        import('react-dom/server'),\n        import('react/jsx-runtime'),\n      ]);\n\n      this.React = react;\n      this.ReactDOMServer = reactDomServer;\n      this.jsxRuntime = jsxRuntime;\n    } catch {\n      throw new Error('React is required for MdxRenderer. Install react and react-dom: npm install react react-dom');\n    }\n  }\n\n  /**\n   * Load @mdx-js/mdx evaluate function.\n   *\n   * evaluate() is the cleanest way to run MDX - it combines\n   * compile and run in a single step, handling all the runtime\n   * injection automatically.\n   */\n  private async loadMdx(): Promise<void> {\n    if (this.mdxEvaluate) {\n      return;\n    }\n\n    try {\n      const mdx = await import('@mdx-js/mdx');\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      this.mdxEvaluate = mdx.evaluate as any;\n    } catch {\n      console.warn(\n        '[@frontmcp/ui] @mdx-js/mdx not available. MDX rendering disabled. ' +\n          'Install @mdx-js/mdx to enable: npm install @mdx-js/mdx',\n      );\n    }\n  }\n}\n\n/**\n * Singleton instance of the MDX renderer.\n */\nexport const mdxRenderer = new MdxRenderer();\n\n/**\n * Build MDX hydration script for client-side interactivity.\n *\n * Note: MDX hydration is more complex than React hydration\n * because it needs the MDX runtime and component definitions.\n */\nexport function buildMdxHydrationScript(): string {\n  return `\n<script>\n(function() {\n  // MDX hydration requires React and component definitions\n  if (typeof React === 'undefined' || typeof ReactDOM === 'undefined') {\n    console.warn('[FrontMCP] React not available for MDX hydration');\n    return;\n  }\n\n  // Find all elements marked for MDX hydration\n  document.querySelectorAll('[data-mdx-hydrate]').forEach(function(root) {\n    var propsJson = root.getAttribute('data-props');\n    var props = propsJson ? JSON.parse(propsJson) : {};\n\n    // MDX content is pre-rendered, hydration mainly attaches event handlers\n    // For full interactivity, components need to be available client-side\n    if (window.__frontmcp_mdx_content) {\n      try {\n        ReactDOM.hydrateRoot(root, React.createElement(\n          window.__frontmcp_mdx_content,\n          props\n        ));\n      } catch (e) {\n        console.error('[FrontMCP] MDX hydration failed', e);\n      }\n    }\n  });\n})();\n</script>\n`;\n}\n"]}

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

@@ -0,0 +1,95 @@
+/**
+ * React Renderer
+ *
+ * Handles React component templates:
+ * - Imported React components (already transpiled)
+ * - JSX string templates (transpiled at runtime with SWC)
+ *
+ * Uses react-dom/server for SSR to HTML.
+ */
+import type { TemplateContext } from '../runtime/types';
+import type { PlatformCapabilities } from '../theme';
+import type { UIRenderer, TranspileResult, TranspileOptions, RenderOptions, RuntimeScripts, ToolUIProps } from './types';
+/**
+ * Types this renderer can handle.
+ */
+type ReactTemplate<In = unknown, Out = unknown> = ((props: ToolUIProps<In, Out>) => unknown) | string;
+/**
+ * React Renderer Implementation.
+ *
+ * Handles:
+ * - Imported React components (FC or class)
+ * - JSX string templates (transpiled with SWC at runtime)
+ *
+ * Renders to HTML using react-dom/server's renderToString.
+ *
+ * @example Imported component
+ * ```typescript
+ * import { MyWidget } from './my-widget.tsx';
+ *
+ * @Tool({
+ *   ui: { template: MyWidget }
+ * })
+ * ```
+ *
+ * @example JSX string (runtime transpilation)
+ * ```typescript
+ * @Tool({
+ *   ui: {
+ *     template: `
+ *       function Widget({ output }) {
+ *         return <div>{output.name}</div>;
+ *       }
+ *     `
+ *   }
+ * })
+ * ```
+ */
+export declare class ReactRenderer implements UIRenderer<ReactTemplate> {
+    readonly type: "react";
+    readonly priority = 20;
+    /**
+     * Lazy-loaded React modules.
+     */
+    private React;
+    private ReactDOMServer;
+    /**
+     * Check if this renderer can handle the given template.
+     *
+     * Accepts:
+     * - React component functions (imported, already transpiled)
+     * - Strings containing JSX syntax
+     */
+    canHandle(template: unknown): template is ReactTemplate;
+    /**
+     * Transpile the template if needed.
+     *
+     * For imported React components, no transpilation is needed.
+     * For JSX strings, SWC transpilation is performed.
+     */
+    transpile(template: ReactTemplate, options?: TranspileOptions): Promise<TranspileResult>;
+    /**
+     * Render the template to HTML string using react-dom/server.
+     */
+    render<In, Out>(template: ReactTemplate<In, Out>, 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;
+}
+/**
+ * Singleton instance of the React renderer.
+ */
+export declare const reactRenderer: ReactRenderer;
+/**
+ * Build React hydration script for client-side interactivity.
+ *
+ * This script finds elements with data-hydrate attributes and
+ * hydrates them with the corresponding React component.
+ */
+export declare function buildHydrationScript(): string;
+export {};

package/src/renderers/react.renderer.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * React Renderer
+ *
+ * Handles React component templates:
+ * - Imported React components (already transpiled)
+ * - JSX string templates (transpiled at runtime with SWC)
+ *
+ * Uses react-dom/server for SSR to HTML.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reactRenderer = exports.ReactRenderer = void 0;
+exports.buildHydrationScript = buildHydrationScript;
+const detect_1 = require("./utils/detect");
+const hash_1 = require("./utils/hash");
+const transpiler_1 = require("./utils/transpiler");
+const cache_1 = require("./cache");
+/**
+ * React runtime CDN URLs.
+ * Using esm.sh for React 19 (ES modules).
+ */
+const REACT_CDN = {
+    react: 'https://esm.sh/react@19',
+    reactDom: 'https://esm.sh/react-dom@19/client',
+};
+/**
+ * Minimal inline React runtime for blocked-network platforms (Claude).
+ * This is a placeholder - in production, we'd bundle a minified React.
+ */
+const INLINE_REACT_PLACEHOLDER = `
+// React runtime not available inline yet.
+// For blocked-network platforms, use pre-rendered HTML templates.
+console.warn('[FrontMCP] React hydration not available on this platform.');
+`;
+/**
+ * React Renderer Implementation.
+ *
+ * Handles:
+ * - Imported React components (FC or class)
+ * - JSX string templates (transpiled with SWC at runtime)
+ *
+ * Renders to HTML using react-dom/server's renderToString.
+ *
+ * @example Imported component
+ * ```typescript
+ * import { MyWidget } from './my-widget.tsx';
+ *
+ * @Tool({
+ *   ui: { template: MyWidget }
+ * })
+ * ```
+ *
+ * @example JSX string (runtime transpilation)
+ * ```typescript
+ * @Tool({
+ *   ui: {
+ *     template: `
+ *       function Widget({ output }) {
+ *         return <div>{output.name}</div>;
+ *       }
+ *     `
+ *   }
+ * })
+ * ```
+ */
+class ReactRenderer {
+    type = 'react';
+    priority = 20; // Higher priority than HTML
+    /**
+     * Lazy-loaded React modules.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    React = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ReactDOMServer = null;
+    /**
+     * Check if this renderer can handle the given template.
+     *
+     * Accepts:
+     * - React component functions (imported, already transpiled)
+     * - Strings containing JSX syntax
+     */
+    canHandle(template) {
+        // React component function
+        if (typeof template === 'function' && (0, detect_1.isReactComponent)(template)) {
+            return true;
+        }
+        // JSX string
+        if (typeof template === 'string' && (0, detect_1.containsJsx)(template)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Transpile the template if needed.
+     *
+     * For imported React components, no transpilation is needed.
+     * For JSX strings, SWC transpilation is performed.
+     */
+    async transpile(template, options) {
+        // Imported component - no transpilation needed
+        if (typeof template === 'function') {
+            const hash = (0, hash_1.hashString)(template.toString());
+            return {
+                code: '', // No transpiled code for already-compiled components
+                hash,
+                cached: true,
+            };
+        }
+        // JSX string - transpile with SWC
+        if (typeof template === 'string') {
+            return (0, transpiler_1.transpileJsx)(template, {
+                development: options?.sourceMaps ?? false,
+            });
+        }
+        throw new Error('Invalid template type for ReactRenderer');
+    }
+    /**
+     * Render the template to HTML string using react-dom/server.
+     */
+    async render(template, context, options) {
+        // Ensure React is loaded
+        await this.loadReact();
+        // Get the component function
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let Component;
+        if (typeof template === 'function') {
+            // Already a component function
+            Component = template;
+        }
+        else if (typeof template === 'string') {
+            // Transpile and execute the JSX string
+            const transpiled = await this.transpile(template);
+            // Check cache for the executed component
+            const cached = cache_1.transpileCache.getByKey(`exec:${transpiled.hash}`);
+            if (cached) {
+                Component = cached.code;
+            }
+            else {
+                // Execute the transpiled code to get the component
+                Component = await (0, transpiler_1.executeTranspiledCode)(transpiled.code, {
+                    // Provide any additional MDX components if specified
+                    ...options?.mdxComponents,
+                });
+                // Cache the component function
+                cache_1.transpileCache.setByKey(`exec:${transpiled.hash}`, {
+                    code: Component,
+                    hash: transpiled.hash,
+                    cached: false,
+                });
+            }
+        }
+        else {
+            throw new Error('Invalid template type for ReactRenderer');
+        }
+        // Build props from context
+        const props = {
+            input: context.input,
+            output: context.output,
+            structuredContent: context.structuredContent,
+            helpers: context.helpers,
+        };
+        // Create React element
+        const element = this.React.createElement(Component, props);
+        // Render to HTML string
+        const html = this.ReactDOMServer.renderToString(element);
+        // If hydration is enabled, wrap with hydration markers
+        if (options?.hydrate) {
+            const componentName = Component.name || 'Component';
+            // Full HTML attribute escaping to prevent XSS
+            const escapedProps = JSON.stringify(props)
+                .replace(/&/g, '&amp;')
+                .replace(/'/g, '&#39;')
+                .replace(/</g, '&lt;')
+                .replace(/>/g, '&gt;');
+            return `<div data-hydrate="${componentName}" data-props='${escapedProps}'>${html}</div>`;
+        }
+        return html;
+    }
+    /**
+     * Get runtime scripts for client-side functionality.
+     */
+    getRuntimeScripts(platform) {
+        // For blocked-network platforms (Claude), scripts must be inline
+        if (platform.networkMode === 'blocked') {
+            return {
+                headScripts: '',
+                inlineScripts: INLINE_REACT_PLACEHOLDER,
+                isInline: true,
+            };
+        }
+        // For platforms with network access, use CDN
+        return {
+            headScripts: `
+        <script crossorigin src="${REACT_CDN.react}"></script>
+        <script crossorigin src="${REACT_CDN.reactDom}"></script>
+      `,
+            isInline: false,
+        };
+    }
+    /**
+     * Load React and ReactDOMServer modules.
+     */
+    async loadReact() {
+        if (this.React && this.ReactDOMServer) {
+            return;
+        }
+        try {
+            this.React = await import('react');
+            this.ReactDOMServer = await import('react-dom/server');
+        }
+        catch {
+            throw new Error('React is required for ReactRenderer. Install react and react-dom: npm install react react-dom');
+        }
+    }
+}
+exports.ReactRenderer = ReactRenderer;
+/**
+ * Singleton instance of the React renderer.
+ */
+exports.reactRenderer = new ReactRenderer();
+/**
+ * Build React hydration script for client-side interactivity.
+ *
+ * This script finds elements with data-hydrate attributes and
+ * hydrates them with the corresponding React component.
+ */
+function buildHydrationScript() {
+    return `
+<script>
+(function() {
+  // Wait for React to be available
+  if (typeof React === 'undefined' || typeof ReactDOM === 'undefined') {
+    console.warn('[FrontMCP] React not available for hydration');
+    return;
+  }
+
+  // Find all elements marked for hydration
+  document.querySelectorAll('[data-hydrate]').forEach(function(root) {
+    var componentName = root.getAttribute('data-hydrate');
+    var propsJson = root.getAttribute('data-props');
+    var props = propsJson ? JSON.parse(propsJson) : {};
+
+    // Look for the component in the global scope
+    if (window.__frontmcp_components && window.__frontmcp_components[componentName]) {
+      try {
+        ReactDOM.hydrateRoot(root, React.createElement(
+          window.__frontmcp_components[componentName],
+          props
+        ));
+      } catch (e) {
+        console.error('[FrontMCP] Hydration failed for', componentName, e);
+      }
+    }
+  });
+})();
+</script>
+`;
+}
+//# sourceMappingURL=react.renderer.js.map