@frontmcp/ui 0.5.0

package/src/build/widget-manifest.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Widget Manifest Builder
+ *
+ * Builds static widget wrappers with embedded manifests for tool UIs.
+ * Produces complete HTML documents with FrontMCP Bridge runtime.
+ *
+ * @packageDocumentation
+ */
+import type { UIType, ResourceMode, OutputMode, CSPDirectives, RendererAssets, WidgetConfig, BuildManifestResult, BuildManifestOptions, ToolResponseMeta } from '../types/ui-runtime';
+import type { ThemeConfig } from '../theme';
+/**
+ * Detect the UI type from a template.
+ *
+ * @param template - Widget template
+ * @returns Detected UI type
+ */
+export declare function detectUIType(template: WidgetConfig['template']): UIType;
+/**
+ * Build CSP directives for a UI type.
+ *
+ * @param uiType - UI renderer type
+ * @param userCsp - User-provided CSP overrides
+ * @returns Complete CSP directives
+ */
+export declare function buildCSPForType(uiType: UIType, userCsp?: Partial<CSPDirectives>): CSPDirectives;
+/**
+ * Build CSP meta tag content.
+ */
+export declare function buildCSPMetaContent(csp: CSPDirectives): string;
+/**
+ * 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'
+ * ```
+ */
+export declare function getRendererAssets(uiType: UIType, resourceMode?: ResourceMode): RendererAssets;
+/**
+ * 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);
+ * ```
+ */
+export declare function buildToolWidgetManifest<Input = Record<string, unknown>, Output = unknown>(options: BuildManifestOptions<Input, Output>): Promise<BuildManifestResult>;
+/**
+ * Options for batch building multiple widgets.
+ */
+export interface BatchBuildOptions {
+    /**
+     * Array of tool configurations to build.
+     */
+    tools: Array<{
+        toolName: string;
+        uiConfig: WidgetConfig;
+        schema?: object;
+    }>;
+    /**
+     * Theme configuration to apply to all widgets.
+     */
+    theme?: ThemeConfig;
+    /**
+     * Enable parallel building.
+     * @default true
+     */
+    parallel?: boolean;
+}
+/**
+ * Result of batch building.
+ */
+export interface BatchBuildResult {
+    /**
+     * Individual build results keyed by tool name.
+     */
+    results: Map<string, BuildManifestResult>;
+    /**
+     * Total build time in ms.
+     */
+    totalTime: number;
+    /**
+     * Number of successful builds.
+     */
+    successCount: number;
+    /**
+     * Errors encountered (keyed by tool name).
+     */
+    errors: Map<string, Error>;
+}
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare function batchBuildWidgets(options: BatchBuildOptions): Promise<BatchBuildResult>;
+/**
+ * Options for building tool response _meta fields.
+ */
+export interface BuildMetaOptions {
+    /**
+     * Build result from buildToolWidgetManifest.
+     */
+    buildResult: BuildManifestResult;
+    /**
+     * Output mode - determines which content to include.
+     * - 'code-only': Include ui/content (transpiled code only)
+     * - 'full-ssr': Include ui/html (complete HTML document)
+     *
+     * @default 'code-only'
+     */
+    outputMode?: OutputMode;
+    /**
+     * Include OpenAI-specific meta fields.
+     * @default true
+     */
+    includeOpenAI?: boolean;
+}
+/**
+ * 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',
+ * });
+ * ```
+ */
+export declare function buildToolResponseMeta(options: BuildMetaOptions): ToolResponseMeta;
+/**
+ * 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 });
+ * ```
+ */
+export declare function getOutputModeForClient(clientInfo?: {
+    name?: string;
+    version?: string;
+}): OutputMode;