@frontmcp/ui 0.5.1 → 0.6.0

package/src/renderers/mdx.renderer.js

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

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

@@ -1,95 +0,0 @@
-/**
- * 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

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