@frontmcp/ui 0.6.0 → 0.6.2

package/esm/renderers/index.mjs

@@ -0,0 +1,611 @@
+// libs/ui/src/renderers/react.renderer.ts
+import { isReactComponent, containsJsx, hashString, transpileJsx } from "@frontmcp/uipack/renderers";
+var VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function isValidComponentName(name) {
+  return VALID_JS_IDENTIFIER.test(name);
+}
+function sanitizeComponentName(name) {
+  if (isValidComponentName(name)) {
+    return name;
+  }
+  const sanitized = name.replace(/[^a-zA-Z0-9_$]/g, "_").replace(/^[0-9]/, "_$&");
+  return sanitized || "Component";
+}
+var REACT_CDN = {
+  react: "https://esm.sh/react@19",
+  reactDom: "https://esm.sh/react-dom@19/client"
+};
+var 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.');
+`;
+var ReactRenderer = class {
+  type = "react";
+  priority = 20;
+  // Higher priority than HTML
+  /**
+   * Check if this renderer can handle the given template.
+   *
+   * Accepts:
+   * - React component functions (imported, already transpiled)
+   * - Strings containing JSX syntax
+   */
+  canHandle(template) {
+    if (typeof template === "function" && isReactComponent(template)) {
+      return true;
+    }
+    if (typeof template === "string" && 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) {
+    if (typeof template === "function") {
+      const hash = hashString(template.toString());
+      return {
+        code: "",
+        // No transpiled code for already-compiled components
+        hash,
+        cached: true
+      };
+    }
+    if (typeof template === "string") {
+      return transpileJsx(template, {
+        development: options?.sourceMaps ?? false
+      });
+    }
+    throw new Error("Invalid template type for ReactRenderer");
+  }
+  /**
+   * Render the template to HTML for client-side rendering.
+   *
+   * Unlike SSR, this method generates HTML that will be rendered
+   * client-side by React in the browser. No server-side React required.
+   *
+   * The generated HTML includes:
+   * - A container div for the React root
+   * - The component code (transpiled if needed)
+   * - Props embedded as a data attribute
+   * - A render script that initializes the component
+   */
+  async render(template, context, _options) {
+    const props = {
+      input: context.input,
+      output: context.output,
+      structuredContent: context.structuredContent,
+      helpers: context.helpers
+    };
+    const escapedProps = JSON.stringify(props).replace(/&/g, "&amp;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const rootId = `frontmcp-react-${hashString(Date.now().toString()).slice(0, 8)}`;
+    let componentCode;
+    let componentName;
+    if (typeof template === "function") {
+      const rawName = template.name || "Component";
+      componentName = sanitizeComponentName(rawName);
+      componentCode = `
+        // Component should be registered via window.__frontmcp_components['${componentName}']
+        (function() {
+          if (!window.__frontmcp_components || !window.__frontmcp_components['${componentName}']) {
+            console.error('[FrontMCP] Component "${componentName}" not registered. Use buildHydrationScript() to register components.');
+          }
+        })();
+      `;
+    } else if (typeof template === "string") {
+      const transpiled = await this.transpile(template);
+      const match = transpiled.code.match(/function\s+(\w+)/);
+      const rawName = match?.[1] || "Widget";
+      componentName = sanitizeComponentName(rawName);
+      componentCode = transpiled.code;
+    } else {
+      throw new Error("Invalid template type for ReactRenderer");
+    }
+    const html = `
+<div id="${rootId}" data-frontmcp-react data-component="${componentName}" data-props='${escapedProps}'>
+  <div class="flex items-center justify-center p-4 text-gray-500">
+    <svg class="animate-spin h-5 w-5 mr-2" viewBox="0 0 24 24">
+      <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" fill="none"></circle>
+      <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+    </svg>
+    Loading...
+  </div>
+</div>
+<script type="module">
+(function() {
+  ${componentCode}
+
+  // Wait for React to be available
+  function waitForReact(callback, maxAttempts) {
+    var attempts = 0;
+    var check = function() {
+      if (typeof React !== 'undefined' && typeof ReactDOM !== 'undefined') {
+        callback();
+      } else if (attempts < maxAttempts) {
+        attempts++;
+        setTimeout(check, 50);
+      } else {
+        console.error('[FrontMCP] React not loaded after ' + maxAttempts + ' attempts');
+      }
+    };
+    check();
+  }
+
+  waitForReact(function() {
+    try {
+      var root = document.getElementById('${rootId}');
+      if (!root) return;
+
+      var propsJson = root.getAttribute('data-props');
+      var props = propsJson ? JSON.parse(propsJson.replace(/&amp;/g, '&').replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>')) : {};
+
+      // Get the component
+      var Component = ${componentName};
+
+      // Check if it's registered globally
+      if (typeof Component === 'undefined' && window.__frontmcp_components) {
+        Component = window.__frontmcp_components['${componentName}'];
+      }
+
+      if (typeof Component === 'function') {
+        var element = React.createElement(Component, props);
+        var reactRoot = ReactDOM.createRoot(root);
+        reactRoot.render(element);
+      } else {
+        console.error('[FrontMCP] Component "${componentName}" not found');
+      }
+    } catch (err) {
+      console.error('[FrontMCP] React render error:', err);
+    }
+  }, 100);
+})();
+</script>
+`;
+    return html.trim();
+  }
+  /**
+   * Get runtime scripts for client-side functionality.
+   */
+  getRuntimeScripts(platform) {
+    if (platform.networkMode === "blocked") {
+      return {
+        headScripts: "",
+        inlineScripts: INLINE_REACT_PLACEHOLDER,
+        isInline: true
+      };
+    }
+    return {
+      headScripts: `
+        <script crossorigin src="${REACT_CDN.react}"></script>
+        <script crossorigin src="${REACT_CDN.reactDom}"></script>
+      `,
+      isInline: false
+    };
+  }
+};
+var reactRenderer = new ReactRenderer();
+
+// libs/ui/src/renderers/react.adapter.ts
+var mountedRoots = /* @__PURE__ */ new WeakMap();
+var ReactRendererAdapter = class {
+  type = "react";
+  // Lazy-loaded React runtime
+  react = null;
+  reactDOM = null;
+  loadPromise = null;
+  /**
+   * Check if this adapter can handle the given content.
+   */
+  canHandle(content) {
+    if (typeof content === "function") {
+      return true;
+    }
+    if (typeof content === "string") {
+      return content.includes("React.createElement") || content.includes("jsx(") || content.includes("jsxs(") || /function\s+\w+\s*\([^)]*\)\s*\{[\s\S]*return\s*[\s\S]*</.test(content);
+    }
+    return false;
+  }
+  /**
+   * Render React component to a string.
+   * This is a client-side fallback - SSR should be done at build time.
+   */
+  async render(content, context, _options) {
+    return `<div data-frontmcp-react data-tool="${context.toolName}">${content}</div>`;
+  }
+  /**
+   * Render React component directly to the DOM.
+   */
+  async renderToDOM(content, target, context, options) {
+    try {
+      await this.ensureReactLoaded();
+      if (!this.react || !this.reactDOM) {
+        throw new Error("React runtime not available");
+      }
+      const componentName = target.getAttribute("data-component");
+      const component = this.getComponent(componentName, content);
+      if (!component) {
+        target.innerHTML = content;
+        return { success: true };
+      }
+      const element = this.react.createElement(component, {
+        input: context.input,
+        output: context.output,
+        structuredContent: context.structuredContent,
+        toolName: context.toolName
+      });
+      if (options?.hydrate && this.reactDOM.hydrateRoot) {
+        const root = this.reactDOM.hydrateRoot(target, element);
+        mountedRoots.set(target, root);
+      } else if (this.reactDOM.createRoot) {
+        const root = this.reactDOM.createRoot(target);
+        root.render(element);
+        mountedRoots.set(target, root);
+      } else if (this.reactDOM.render) {
+        this.reactDOM.render(element, target);
+        mountedRoots.set(target, {
+          unmount: () => this.reactDOM?.unmountComponentAtNode?.(target)
+        });
+      } else {
+        throw new Error("No suitable React render method available");
+      }
+      target.dispatchEvent(
+        new CustomEvent("frontmcp:rendered", {
+          bubbles: true,
+          detail: { type: "react", toolName: context.toolName }
+        })
+      );
+      return { success: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error("[FrontMCP] React render failed:", message);
+      return { success: false, error: message };
+    }
+  }
+  /**
+   * Hydrate existing SSR content with React.
+   */
+  async hydrate(target, context, options) {
+    return this.renderToDOM("", target, context, { ...options, hydrate: true });
+  }
+  /**
+   * Update rendered React component with new data.
+   */
+  async update(target, context) {
+    try {
+      await this.ensureReactLoaded();
+      if (!this.react) {
+        throw new Error("React runtime not available");
+      }
+      const existingRoot = mountedRoots.get(target);
+      const componentName = target.getAttribute("data-component");
+      const component = this.getComponent(componentName, "");
+      if (!component) {
+        return { success: false, error: "No component found for update" };
+      }
+      const element = this.react.createElement(component, {
+        input: context.input,
+        output: context.output,
+        structuredContent: context.structuredContent,
+        toolName: context.toolName
+      });
+      if (existingRoot && "render" in existingRoot) {
+        existingRoot.render(element);
+        return { success: true };
+      }
+      return this.renderToDOM("", target, context);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error("[FrontMCP] React update failed:", message);
+      return { success: false, error: message };
+    }
+  }
+  /**
+   * Clean up React root.
+   */
+  destroy(target) {
+    const root = mountedRoots.get(target);
+    if (root) {
+      root.unmount();
+      mountedRoots.delete(target);
+    }
+  }
+  /**
+   * Ensure React is loaded.
+   */
+  async ensureReactLoaded() {
+    if (this.react && this.reactDOM) {
+      return;
+    }
+    if (this.loadPromise) {
+      return this.loadPromise;
+    }
+    this.loadPromise = this.loadReact();
+    return this.loadPromise;
+  }
+  /**
+   * Load React runtime.
+   */
+  async loadReact() {
+    const win = typeof window !== "undefined" ? window : globalThis;
+    if (win.React) {
+      this.react = win.React;
+    }
+    if (win.ReactDOM) {
+      this.reactDOM = win.ReactDOM;
+    }
+    if (this.react && this.reactDOM) {
+      return;
+    }
+    try {
+      if (!this.react) {
+        const reactModule = await import(
+          /* webpackIgnore: true */
+          "react"
+        );
+        this.react = reactModule.default || reactModule;
+      }
+      if (!this.reactDOM) {
+        const reactDOMModule = await import(
+          /* webpackIgnore: true */
+          "react-dom/client"
+        );
+        this.reactDOM = reactDOMModule.default || reactDOMModule;
+      }
+    } catch {
+      if (!this.react || !this.reactDOM) {
+        console.warn("[FrontMCP] React runtime not available. Ensure React is loaded via CDN or bundled.");
+      }
+    }
+  }
+  /**
+   * Get a React component by name or from content.
+   */
+  getComponent(componentName, content) {
+    const win = typeof window !== "undefined" ? window : globalThis;
+    if (componentName && win.__frontmcp_components) {
+      const registered = win.__frontmcp_components?.[componentName];
+      if (registered) {
+        return registered;
+      }
+    }
+    if (content && typeof content === "function") {
+      return content;
+    }
+    return null;
+  }
+};
+function createReactAdapter() {
+  return new ReactRendererAdapter();
+}
+async function loadReactAdapter() {
+  return createReactAdapter();
+}
+
+// libs/ui/src/renderers/mdx.renderer.ts
+import { containsMdxSyntax, hashString as hashString2, transpileCache, componentCache } from "@frontmcp/uipack/renderers";
+function buildReactCdnUrls(version = "19") {
+  return {
+    react: `https://esm.sh/react@${version}`,
+    reactDom: `https://esm.sh/react-dom@${version}/client`
+  };
+}
+var REACT_CDN2 = buildReactCdnUrls("19");
+var 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.');
+`;
+var MdxRenderer = class {
+  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 containsMdxSyntax(template);
+  }
+  /**
+   * Prepare MDX template for rendering.
+   * Caches the template hash for deduplication. Actual MDX compilation
+   * happens during render() via @mdx-js/mdx evaluate().
+   */
+  async transpile(template, _options) {
+    const hash = hashString2(template);
+    const cached = transpileCache.getByKey(hash);
+    if (cached) {
+      return { ...cached, cached: true };
+    }
+    const transpileResult = {
+      code: template,
+      hash,
+      cached: false
+    };
+    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) {
+    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");
+    }
+    const templateHash = hashString2(template);
+    const cacheKey = `mdx-component:${templateHash}`;
+    let Content = componentCache.get(cacheKey);
+    if (!Content) {
+      const result = await this.mdxEvaluate(template, {
+        ...this.jsxRuntime,
+        Fragment: this.React.Fragment,
+        development: false
+      });
+      Content = result.default;
+      componentCache.set(cacheKey, Content);
+    }
+    const mdxComponents = {
+      ...options?.mdxComponents,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      wrapper: ({ children }) => {
+        return this.React.createElement("div", { className: "mdx-content" }, children);
+      }
+    };
+    const props = {
+      input: context.input,
+      output: context.output,
+      structuredContent: context.structuredContent,
+      helpers: context.helpers
+    };
+    const reservedProps = /* @__PURE__ */ new Set(["input", "output", "structuredContent", "helpers", "components"]);
+    const outputProps = typeof context.output === "object" && context.output !== null ? Object.fromEntries(Object.entries(context.output).filter(([key]) => !reservedProps.has(key))) : {};
+    const spreadProps = {
+      ...outputProps,
+      ...props
+    };
+    const element = this.React.createElement(Content, {
+      components: mdxComponents,
+      ...spreadProps
+    });
+    const html = this.ReactDOMServer.renderToString(element);
+    if (options?.hydrate) {
+      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) {
+    if (platform.networkMode === "blocked") {
+      return {
+        headScripts: "",
+        inlineScripts: INLINE_MDX_PLACEHOLDER,
+        isInline: true
+      };
+    }
+    return {
+      headScripts: `
+        <script crossorigin src="${REACT_CDN2.react}"></script>
+        <script crossorigin src="${REACT_CDN2.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.
+   */
+  async loadMdx() {
+    if (this.mdxEvaluate) {
+      return;
+    }
+    try {
+      const mdx = await import("@mdx-js/mdx");
+      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"
+      );
+    }
+  }
+};
+var mdxRenderer = new MdxRenderer();
+
+// libs/ui/src/renderers/transpiler.ts
+import { transpileJsx as transpileJsx2 } from "@frontmcp/uipack/renderers";
+async function executeTranspiledCode(code, context = {}) {
+  let React;
+  let jsxRuntime;
+  try {
+    React = await import("react");
+    jsxRuntime = await import("react/jsx-runtime");
+  } catch {
+    throw new Error("React is required for JSX templates. Install react: npm install react react-dom");
+  }
+  const exports = {};
+  const module = { exports };
+  const require2 = (id) => {
+    switch (id) {
+      case "react":
+        return React;
+      case "react/jsx-runtime":
+        return jsxRuntime;
+      case "react/jsx-dev-runtime":
+        return jsxRuntime;
+      default:
+        if (context[id]) {
+          return context[id];
+        }
+        throw new Error(`Module '${id}' not available in JSX template context`);
+    }
+  };
+  try {
+    const fn = new Function("exports", "require", "module", "__filename", "__dirname", "React", "context", code);
+    fn(exports, require2, module, "template.js", "/", React, context);
+    const exportKeys = Object.keys(module.exports);
+    return module.exports["default"] || (exportKeys.length > 0 ? module.exports[exportKeys[0]] : null) || module.exports;
+  } catch (error) {
+    throw new Error(`Failed to execute transpiled JSX: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function transpileAndExecute(source, context = {}) {
+  const result = await transpileJsx2(source);
+  return executeTranspiledCode(result.code, context);
+}
+export {
+  MdxRenderer,
+  ReactRenderer,
+  ReactRendererAdapter,
+  createReactAdapter,
+  executeTranspiledCode,
+  loadReactAdapter,
+  mdxRenderer,
+  reactRenderer,
+  transpileAndExecute
+};