@frontmcp/ui 0.5.0

package/src/build/widget-manifest.js

@@ -0,0 +1,652 @@
+"use strict";
+/**
+ * Widget Manifest Builder
+ *
+ * Builds static widget wrappers with embedded manifests for tool UIs.
+ * Produces complete HTML documents with FrontMCP Bridge runtime.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectUIType = detectUIType;
+exports.buildCSPForType = buildCSPForType;
+exports.buildCSPMetaContent = buildCSPMetaContent;
+exports.getRendererAssets = getRendererAssets;
+exports.buildToolWidgetManifest = buildToolWidgetManifest;
+exports.batchBuildWidgets = batchBuildWidgets;
+exports.buildToolResponseMeta = buildToolResponseMeta;
+exports.getOutputModeForClient = getOutputModeForClient;
+const ui_runtime_1 = require("../types/ui-runtime");
+const cdn_resources_1 = require("./cdn-resources");
+const wrapper_1 = require("../runtime/wrapper");
+const registry_1 = require("../renderers/registry");
+const renderers_1 = require("../renderers");
+// ============================================
+// UI Type Detection
+// ============================================
+/**
+ * Detect the UI type from a template.
+ *
+ * @param template - Widget template
+ * @returns Detected UI type
+ */
+function detectUIType(template) {
+    const detection = (0, renderers_1.detectTemplateType)(template);
+    switch (detection.type) {
+        case 'react':
+            return 'react';
+        case 'mdx':
+            return 'mdx';
+        case 'jsx-string':
+            return 'react'; // JSX strings are rendered as React
+        case 'html-string':
+        case 'html-function':
+            return 'html';
+        default:
+            return 'auto';
+    }
+}
+// ============================================
+// CSP Building
+// ============================================
+/**
+ * Build CSP directives for a UI type.
+ *
+ * @param uiType - UI renderer type
+ * @param userCsp - User-provided CSP overrides
+ * @returns Complete CSP directives
+ */
+function buildCSPForType(uiType, userCsp) {
+    const baseCsp = ui_runtime_1.DEFAULT_CSP_BY_TYPE[uiType] ?? ui_runtime_1.DEFAULT_CSP_BY_TYPE['auto'];
+    if (!userCsp) {
+        return { ...baseCsp };
+    }
+    // Merge user CSP with base CSP
+    return {
+        scriptSrc: mergeCspArray(baseCsp.scriptSrc, userCsp.scriptSrc),
+        styleSrc: mergeCspArray(baseCsp.styleSrc, userCsp.styleSrc),
+        connectSrc: mergeCspArray(baseCsp.connectSrc, userCsp.connectSrc),
+        imgSrc: userCsp.imgSrc ?? baseCsp.imgSrc,
+        fontSrc: userCsp.fontSrc ?? baseCsp.fontSrc,
+        defaultSrc: userCsp.defaultSrc ?? baseCsp.defaultSrc,
+        frameSrc: userCsp.frameSrc ?? baseCsp.frameSrc,
+        objectSrc: userCsp.objectSrc ?? baseCsp.objectSrc,
+    };
+}
+/**
+ * Merge CSP arrays, preserving uniqueness.
+ */
+function mergeCspArray(base, override) {
+    if (!override)
+        return [...base];
+    const merged = new Set([...base, ...override]);
+    return Array.from(merged);
+}
+/**
+ * Build CSP meta tag content.
+ */
+function buildCSPMetaContent(csp) {
+    const directives = [];
+    if (csp.defaultSrc?.length) {
+        directives.push(`default-src ${csp.defaultSrc.join(' ')}`);
+    }
+    if (csp.scriptSrc.length) {
+        directives.push(`script-src ${csp.scriptSrc.join(' ')}`);
+    }
+    if (csp.styleSrc.length) {
+        directives.push(`style-src ${csp.styleSrc.join(' ')}`);
+    }
+    if (csp.connectSrc.length) {
+        directives.push(`connect-src ${csp.connectSrc.join(' ')}`);
+    }
+    if (csp.imgSrc?.length) {
+        directives.push(`img-src ${csp.imgSrc.join(' ')}`);
+    }
+    if (csp.fontSrc?.length) {
+        directives.push(`font-src ${csp.fontSrc.join(' ')}`);
+    }
+    if (csp.frameSrc?.length) {
+        directives.push(`frame-src ${csp.frameSrc.join(' ')}`);
+    }
+    if (csp.objectSrc?.length) {
+        directives.push(`object-src ${csp.objectSrc.join(' ')}`);
+    }
+    return directives.join('; ');
+}
+// ============================================
+// Renderer Assets
+// ============================================
+/**
+ * Get renderer assets for a UI type.
+ *
+ * @param uiType - UI renderer type
+ * @param resourceMode - Resource loading mode (cdn or inline)
+ * @returns Required renderer assets with CDN URLs or inline placeholders
+ *
+ * @example
+ * ```typescript
+ * // Get CDN-based assets for React
+ * const assets = getRendererAssets('react', 'cdn');
+ * console.log(assets.react?.url);
+ * // "https://unpkg.com/react@18/umd/react.production.min.js"
+ *
+ * // Get inline-mode assets
+ * const inlineAssets = getRendererAssets('react', 'inline');
+ * // inlineAssets.mode === 'inline'
+ * ```
+ */
+function getRendererAssets(uiType, resourceMode = 'cdn') {
+    // Use the CDN resources helper which provides proper CDN URLs
+    return (0, cdn_resources_1.getDefaultAssets)(uiType, resourceMode);
+}
+// ============================================
+// Hash Generation
+// ============================================
+/**
+ * Generate a hash for content.
+ */
+async function generateHash(content) {
+    // Use Web Crypto API if available
+    if (typeof crypto !== 'undefined' && crypto.subtle) {
+        const encoder = new TextEncoder();
+        const data = encoder.encode(content);
+        const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    // Fallback: simple hash
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const char = content.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash;
+    }
+    return Math.abs(hash).toString(16).padStart(8, '0');
+}
+// ============================================
+// Main Builder
+// ============================================
+/**
+ * Build a widget manifest for a tool.
+ *
+ * Creates a static widget wrapper with embedded manifest.
+ * The widget can be cached and reused across tool invocations.
+ *
+ * @param options - Build options
+ * @returns Build result with HTML, manifest, and metadata
+ *
+ * @example
+ * ```typescript
+ * import { buildToolWidgetManifest } from '@frontmcp/ui/build';
+ *
+ * const result = await buildToolWidgetManifest({
+ *   toolName: 'weather.get',
+ *   uiConfig: {
+ *     template: WeatherWidget,
+ *     uiType: 'react',
+ *     displayMode: 'inline',
+ *     widgetAccessible: true,
+ *   },
+ *   schema: { type: 'object', properties: { ... } },
+ * });
+ *
+ * // Cache the HTML
+ * cache.set(`ui://widget/${result.manifest.tool}.html`, result.html);
+ * ```
+ */
+async function buildToolWidgetManifest(options) {
+    const { toolName, uiConfig, schema, theme, sampleInput, sampleOutput } = options;
+    // Resolve UI type
+    // Use type assertion to handle complex generic template types
+    const uiType = (0, ui_runtime_1.isUIType)(uiConfig.uiType)
+        ? uiConfig.uiType
+        : detectUIType(uiConfig.template);
+    // Resolve display mode
+    const displayMode = uiConfig.displayMode ?? 'inline';
+    // Resolve bundling mode
+    const bundlingMode = uiConfig.bundlingMode ?? 'static';
+    // Resolve resource mode (cdn or inline)
+    const resourceMode = (0, ui_runtime_1.isResourceMode)(uiConfig.resourceMode)
+        ? uiConfig.resourceMode
+        : 'cdn';
+    // Build CSP
+    const csp = buildCSPForType(uiType, uiConfig.csp);
+    // Get renderer assets based on resource mode
+    const rendererAssets = getRendererAssets(uiType, resourceMode);
+    // Render the template to get initial content
+    // Cast to generic type to avoid complex type inference issues
+    const templateConfig = uiConfig;
+    const content = await renderTemplate(templateConfig, {
+        input: (sampleInput ?? {}),
+        output: (sampleOutput ?? {}),
+        uiType,
+    });
+    // Generate component code for client-side rendering (React/MDX only)
+    const componentCode = (uiType === 'react' || uiType === 'mdx')
+        ? buildComponentCode(uiConfig.template, toolName)
+        : undefined;
+    // Build manifest
+    // Note: We intentionally omit 'uri' since we're not using resource-based serving.
+    // The content/html is returned directly in the tool response.
+    const manifestBase = {
+        tool: toolName,
+        uiType,
+        bundlingMode,
+        displayMode,
+        widgetAccessible: uiConfig.widgetAccessible ?? false,
+        schema: schema ?? {},
+        csp,
+        rendererAssets,
+        createdAt: new Date().toISOString(),
+        description: uiConfig.widgetDescription,
+    };
+    // Convert CSPDirectives to UIContentSecurityPolicy for wrapper
+    const wrapperCsp = uiConfig.csp ? {
+        connectDomains: uiConfig.csp.connectSrc,
+        resourceDomains: [
+            ...(uiConfig.csp.scriptSrc ?? []),
+            ...(uiConfig.csp.styleSrc ?? []),
+            ...(uiConfig.csp.imgSrc ?? []),
+        ].filter((d) => d !== "'self'" && d !== "'unsafe-inline'"),
+    } : undefined;
+    // Build manifest script to embed in the page
+    const manifestScript = buildManifestScript(manifestBase);
+    // Prepend manifest script to content so it's available before the UI renders
+    const contentWithManifest = manifestScript + '\n' + content;
+    // Build the complete HTML with manifest embedded
+    // Use inlineScripts when resourceMode is 'inline' (for blocked-network environments)
+    const html = (0, wrapper_1.wrapToolUIUniversal)({
+        content: contentWithManifest,
+        toolName,
+        input: (sampleInput ?? {}),
+        output: sampleOutput,
+        csp: wrapperCsp,
+        widgetAccessible: uiConfig.widgetAccessible,
+        includeBridge: true,
+        rendererType: uiType,
+        inlineScripts: resourceMode === 'inline',
+        resourceMode, // Pass resource mode for CDN script generation
+    });
+    // Generate hash based on tool name + content (for cache invalidation)
+    // Including toolName ensures different tools have different hashes even if content is similar
+    const hash = await generateHash(`${toolName}:${content}`);
+    // Complete manifest with hash
+    const manifest = {
+        ...manifestBase,
+        hash: `sha256-${hash}`,
+    };
+    // Calculate sizes
+    const contentSize = new TextEncoder().encode(content).length;
+    const htmlSize = new TextEncoder().encode(html).length;
+    const gzipSize = Math.round(htmlSize * 0.25); // Rough estimate
+    return {
+        // Transpiled content only (for capable clients like OpenAI)
+        content,
+        // Full HTML document (for limited/unknown MCP clients)
+        html,
+        manifest,
+        hash,
+        rendererType: uiType,
+        // Component code for client-side rendering (React/MDX only)
+        componentCode,
+        contentSize,
+        htmlSize,
+        gzipSize,
+        // Deprecated, kept for backwards compatibility
+        size: htmlSize,
+    };
+}
+/**
+ * Build the manifest script tag for embedding in HTML.
+ */
+function buildManifestScript(manifest) {
+    // Escape for embedding in script tag
+    const json = JSON.stringify(manifest)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026');
+    return `
+<script type="application/json" id="frontmcp-widget-manifest">
+${json}
+</script>
+<script>
+(function() {
+  try {
+    var manifest = JSON.parse(document.getElementById('frontmcp-widget-manifest').textContent);
+    window.__frontmcp = window.__frontmcp || {};
+    window.__frontmcp.widget = window.__frontmcp.widget || {};
+    window.__frontmcp.widget.manifest = manifest;
+  } catch (e) {
+    console.error('[FrontMCP] Failed to parse widget manifest:', e);
+  }
+})();
+</script>
+  `.trim();
+}
+// ============================================
+// Component Code Builder (for Client-Side Rendering)
+// ============================================
+/**
+ * Build client-side component code for React templates.
+ *
+ * This converts the server-side React component into a string that can be
+ * embedded in the widget HTML for client-side rendering when tool output
+ * becomes available.
+ *
+ * @param template - The React component or template
+ * @param toolName - Tool name for naming the component
+ * @returns JavaScript code string that defines the component
+ */
+function buildComponentCode(template, toolName) {
+    if (typeof template !== 'function') {
+        return undefined;
+    }
+    // Get the component function as a string
+    const componentSource = template.toString();
+    // Sanitize tool name for JavaScript variable name
+    const safeName = toolName.replace(/[^a-zA-Z0-9_]/g, '_');
+    // Build the component code that will be embedded in the HTML
+    // The component is registered on window.__frontmcp_component for the render script
+    return `
+// FrontMCP Widget Component: ${toolName}
+(function() {
+  // The component function
+  var ${safeName} = ${componentSource};
+
+  // Register component globally for client-side rendering
+  window.__frontmcp_component = ${safeName};
+
+  // Also register in __frontmcp_components for multiple components
+  window.__frontmcp_components = window.__frontmcp_components || {};
+  window.__frontmcp_components['${toolName}'] = ${safeName};
+})();
+`.trim();
+}
+/**
+ * Ensure renderers are registered before use.
+ * This is called once and ensures React/MDX renderers are available.
+ */
+let renderersInitialized = false;
+function ensureRenderersRegistered() {
+    if (renderersInitialized) {
+        return;
+    }
+    // Register React renderer if not already registered
+    if (!registry_1.rendererRegistry.has('react')) {
+        registry_1.rendererRegistry.register(renderers_1.reactRenderer);
+    }
+    // Register MDX renderer if not already registered
+    if (!registry_1.rendererRegistry.has('mdx')) {
+        registry_1.rendererRegistry.register(renderers_1.mdxRenderer);
+    }
+    renderersInitialized = true;
+}
+/**
+ * Render template content.
+ */
+async function renderTemplate(uiConfig, options) {
+    const { input, output, uiType } = options;
+    const template = uiConfig.template;
+    // Ensure renderers are available
+    ensureRenderersRegistered();
+    // Build context for template
+    const context = {
+        input: input,
+        output,
+        structuredContent: undefined,
+        helpers: {
+            escapeHtml: (str) => str.replace(/[&<>"']/g, (c) => ({
+                '&': '&amp;',
+                '<': '&lt;',
+                '>': '&gt;',
+                '"': '&quot;',
+                "'": '&#39;',
+            })[c] ?? c),
+            formatDate: (date) => new Date(date).toLocaleDateString(),
+            formatCurrency: (amount, currency = 'USD') => new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amount),
+            uniqueId: (prefix = 'id') => `${prefix}-${Math.random().toString(36).slice(2, 9)}`,
+            jsonEmbed: (data) => JSON.stringify(data).replace(/</g, '\\u003c').replace(/>/g, '\\u003e'),
+        },
+    };
+    // Try to render using the registry
+    try {
+        // Use the detected uiType to render with the correct renderer
+        if (uiType === 'react' && registry_1.rendererRegistry.has('react')) {
+            const result = await registry_1.rendererRegistry.renderWith('react', template, context, {
+                mdxComponents: uiConfig.mdxComponents,
+            });
+            return result.html;
+        }
+        if (uiType === 'mdx' && registry_1.rendererRegistry.has('mdx')) {
+            const result = await registry_1.rendererRegistry.renderWith('mdx', template, context, {
+                mdxComponents: uiConfig.mdxComponents,
+            });
+            return result.html;
+        }
+        // Auto-detect and render
+        const result = await registry_1.rendererRegistry.render(template, context, {
+            mdxComponents: uiConfig.mdxComponents,
+        });
+        return result.html;
+    }
+    catch (error) {
+        // Fallback: simple rendering
+        if (typeof template === 'string') {
+            return template;
+        }
+        if (typeof template === 'function') {
+            // Check if it's a React component (has prototype or is class)
+            const isReact = template.prototype?.isReactComponent ||
+                template.$$typeof !== undefined;
+            if (!isReact) {
+                // It's a template builder function
+                return template(context);
+            }
+        }
+        // Log the error for debugging
+        console.warn('[FrontMCP] Template rendering failed:', error);
+        return `<div class="error">Template rendering failed</div>`;
+    }
+}
+/**
+ * Build multiple widget manifests in batch.
+ *
+ * @param options - Batch build options
+ * @returns Batch build results
+ *
+ * @example
+ * ```typescript
+ * const { results, errors } = await batchBuildWidgets({
+ *   tools: [
+ *     { toolName: 'weather.get', uiConfig: weatherConfig },
+ *     { toolName: 'stock.quote', uiConfig: stockConfig },
+ *   ],
+ * });
+ *
+ * for (const [name, result] of results) {
+ *   cache.set(result.manifest.uri, result.html);
+ * }
+ * ```
+ */
+async function batchBuildWidgets(options) {
+    const startTime = performance.now();
+    const results = new Map();
+    const errors = new Map();
+    const { tools, theme, parallel = true } = options;
+    if (parallel) {
+        // Build in parallel
+        const promises = tools.map(async (tool) => {
+            try {
+                const result = await buildToolWidgetManifest({
+                    toolName: tool.toolName,
+                    uiConfig: tool.uiConfig,
+                    schema: tool.schema,
+                    theme,
+                });
+                return { toolName: tool.toolName, result, error: null };
+            }
+            catch (error) {
+                return {
+                    toolName: tool.toolName,
+                    result: null,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                };
+            }
+        });
+        const outcomes = await Promise.all(promises);
+        for (const outcome of outcomes) {
+            if (outcome.result) {
+                results.set(outcome.toolName, outcome.result);
+            }
+            else if (outcome.error) {
+                errors.set(outcome.toolName, outcome.error);
+            }
+        }
+    }
+    else {
+        // Build sequentially
+        for (const tool of tools) {
+            try {
+                const result = await buildToolWidgetManifest({
+                    toolName: tool.toolName,
+                    uiConfig: tool.uiConfig,
+                    schema: tool.schema,
+                    theme,
+                });
+                results.set(tool.toolName, result);
+            }
+            catch (error) {
+                errors.set(tool.toolName, error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    }
+    return {
+        results,
+        totalTime: performance.now() - startTime,
+        successCount: results.size,
+        errors,
+    };
+}
+/**
+ * Build _meta fields for a tool response.
+ *
+ * This function generates the proper _meta structure for UI widgets.
+ * All UI-related data goes in _meta, NOT in the content array.
+ *
+ * @param options - Build options
+ * @returns _meta fields object to spread into tool response
+ *
+ * @example
+ * ```typescript
+ * const buildResult = await buildToolWidgetManifest({...});
+ *
+ * // For OpenAI (code-only mode)
+ * const meta = buildToolResponseMeta({
+ *   buildResult,
+ *   outputMode: 'code-only',
+ * });
+ *
+ * return {
+ *   content: [{ type: 'text', text: 'Weather retrieved' }],
+ *   _meta: meta,
+ * };
+ *
+ * // For unknown clients (full-ssr mode)
+ * const meta = buildToolResponseMeta({
+ *   buildResult,
+ *   outputMode: 'full-ssr',
+ * });
+ * ```
+ */
+function buildToolResponseMeta(options) {
+    const { buildResult, outputMode = 'code-only', includeOpenAI = true } = options;
+    const { manifest, content, html, hash, rendererType } = buildResult;
+    // Base UI meta fields
+    const meta = {
+        'ui/type': rendererType,
+        'ui/hash': hash,
+    };
+    // Add content based on output mode
+    if (outputMode === 'code-only') {
+        meta['ui/content'] = content;
+    }
+    else {
+        meta['ui/html'] = html;
+    }
+    // Add optional fields from manifest
+    if (manifest.displayMode && manifest.displayMode !== 'inline') {
+        meta['ui/displayMode'] = manifest.displayMode;
+    }
+    if (manifest.widgetAccessible) {
+        meta['ui/widgetAccessible'] = true;
+    }
+    if (manifest.description) {
+        meta['ui/description'] = manifest.description;
+    }
+    // Add resource mode if not default
+    if (manifest.rendererAssets?.mode && manifest.rendererAssets.mode !== 'cdn') {
+        meta['ui/resourceMode'] = manifest.rendererAssets.mode;
+    }
+    // Add OpenAI-specific fields
+    if (includeOpenAI) {
+        if (manifest.widgetAccessible) {
+            meta['openai/widgetAccessible'] = true;
+        }
+        if (manifest.description) {
+            meta['openai/widgetDescription'] = manifest.description;
+        }
+        if (manifest.displayMode && manifest.displayMode !== 'inline') {
+            meta['openai/displayMode'] = manifest.displayMode;
+        }
+        // Build OpenAI CSP from manifest CSP
+        const csp = manifest.csp;
+        if (csp) {
+            const openaiCsp = {};
+            if (csp.connectSrc && csp.connectSrc.length > 0) {
+                openaiCsp.connect_domains = csp.connectSrc.filter((d) => d !== "'self'" && d !== "'none'");
+            }
+            const resourceDomains = [
+                ...(csp.scriptSrc || []),
+                ...(csp.styleSrc || []),
+                ...(csp.imgSrc || []),
+            ].filter((d) => d !== "'self'" && d !== "'unsafe-inline'" && d !== "'none'");
+            if (resourceDomains.length > 0) {
+                openaiCsp.resource_domains = [...new Set(resourceDomains)];
+            }
+            if (openaiCsp.connect_domains?.length || openaiCsp.resource_domains?.length) {
+                meta['openai/widgetCSP'] = openaiCsp;
+            }
+        }
+    }
+    return meta;
+}
+/**
+ * Determine the appropriate output mode based on client info.
+ *
+ * @param clientInfo - MCP client information
+ * @returns Recommended output mode
+ *
+ * @example
+ * ```typescript
+ * const outputMode = getOutputModeForClient(request.clientInfo);
+ * const meta = buildToolResponseMeta({ buildResult, outputMode });
+ * ```
+ */
+function getOutputModeForClient(clientInfo) {
+    if (!clientInfo?.name) {
+        // Unknown client - use full SSR for safety
+        return 'full-ssr';
+    }
+    const name = clientInfo.name.toLowerCase();
+    // Capable clients that provide their own runtime
+    if (name.includes('openai') ||
+        name.includes('chatgpt') ||
+        name.includes('cursor') ||
+        name.includes('claude') // Claude Desktop might support code-only in future
+    ) {
+        return 'code-only';
+    }
+    // Default to full SSR for unknown clients
+    return 'full-ssr';
+}
+//# sourceMappingURL=widget-manifest.js.map