@frontmcp/ui 0.5.0 → 0.6.0

package/src/types/ui-runtime.js

@@ -1,117 +0,0 @@
-"use strict";
-/**
- * Widget Runtime Types
- *
- * Core types for the Tool UI widget system. These types define:
- * - UI rendering modes (html, react, mdx, markdown, auto)
- * - Bundling strategies (static vs dynamic)
- * - Widget manifests for caching and discovery
- * - Runtime payloads for tool responses
- * - CSP directives for security
- *
- * This module is the canonical source for widget types.
- * Both `@frontmcp/sdk` and external consumers (like AgentLink)
- * should import types from here.
- *
- * @packageDocumentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RENDERER_ASSETS = exports.DEFAULT_CSP_BY_TYPE = void 0;
-exports.isUIType = isUIType;
-exports.isBundlingMode = isBundlingMode;
-exports.isResourceMode = isResourceMode;
-exports.isDisplayMode = isDisplayMode;
-exports.isOutputMode = isOutputMode;
-// ============================================
-// Type Guards
-// ============================================
-/**
- * Check if a value is a valid UIType.
- */
-function isUIType(value) {
-    return typeof value === 'string' && ['html', 'react', 'mdx', 'markdown', 'auto'].includes(value);
-}
-/**
- * Check if a value is a valid BundlingMode.
- */
-function isBundlingMode(value) {
-    return typeof value === 'string' && ['static', 'dynamic'].includes(value);
-}
-/**
- * Check if a value is a valid ResourceMode.
- */
-function isResourceMode(value) {
-    return typeof value === 'string' && ['cdn', 'inline'].includes(value);
-}
-/**
- * Check if a value is a valid DisplayMode.
- */
-function isDisplayMode(value) {
-    return typeof value === 'string' && ['inline', 'fullscreen', 'pip'].includes(value);
-}
-/**
- * Check if a value is a valid OutputMode.
- */
-function isOutputMode(value) {
-    return typeof value === 'string' && ['code-only', 'full-ssr'].includes(value);
-}
-// ============================================
-// Default Values
-// ============================================
-/**
- * Default CSP directives for different UI types.
- */
-exports.DEFAULT_CSP_BY_TYPE = {
-    html: {
-        scriptSrc: ["'self'", "'unsafe-inline'"],
-        styleSrc: ["'self'", "'unsafe-inline'"],
-        connectSrc: [],
-    },
-    react: {
-        scriptSrc: ["'self'", "'unsafe-inline'", 'https://unpkg.com'],
-        styleSrc: ["'self'", "'unsafe-inline'"],
-        connectSrc: [],
-    },
-    mdx: {
-        scriptSrc: ["'self'", "'unsafe-inline'", 'https://unpkg.com'],
-        styleSrc: ["'self'", "'unsafe-inline'"],
-        connectSrc: [],
-    },
-    markdown: {
-        scriptSrc: ["'self'", "'unsafe-inline'"],
-        styleSrc: ["'self'", "'unsafe-inline'"],
-        connectSrc: [],
-    },
-    auto: {
-        scriptSrc: ["'self'", "'unsafe-inline'", 'https://unpkg.com'],
-        styleSrc: ["'self'", "'unsafe-inline'"],
-        connectSrc: [],
-    },
-};
-/**
- * Default renderer assets for different UI types.
- */
-exports.DEFAULT_RENDERER_ASSETS = {
-    html: {
-        handlebarsRuntime: 'https://unpkg.com/handlebars@latest/dist/handlebars.runtime.min.js',
-    },
-    react: {
-        reactRuntime: 'https://unpkg.com/react@18/umd/react.production.min.js',
-        reactDomRuntime: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',
-    },
-    mdx: {
-        reactRuntime: 'https://unpkg.com/react@18/umd/react.production.min.js',
-        reactDomRuntime: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',
-        markdownEngine: 'https://unpkg.com/marked@latest/marked.min.js',
-    },
-    markdown: {
-        markdownEngine: 'https://unpkg.com/marked@latest/marked.min.js',
-    },
-    auto: {
-        reactRuntime: 'https://unpkg.com/react@18/umd/react.production.min.js',
-        reactDomRuntime: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',
-        markdownEngine: 'https://unpkg.com/marked@latest/marked.min.js',
-        handlebarsRuntime: 'https://unpkg.com/handlebars@latest/dist/handlebars.runtime.min.js',
-    },
-};
-//# sourceMappingURL=ui-runtime.js.map

package/src/types/ui-runtime.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ui-runtime.js","sourceRoot":"","sources":["../../../src/types/ui-runtime.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AA8lCH,4BAEC;AAKD,wCAEC;AAKD,wCAEC;AAKD,sCAEC;AAKD,oCAEC;AArCD,+CAA+C;AAC/C,cAAc;AACd,+CAA+C;AAE/C;;GAEG;AACH,SAAgB,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnG,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5E,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACtF,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAChF,CAAC;AAED,+CAA+C;AAC/C,iBAAiB;AACjB,+CAA+C;AAE/C;;GAEG;AACU,QAAA,mBAAmB,GAAkC;IAChE,IAAI,EAAE;QACJ,SAAS,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACxC,QAAQ,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACvC,UAAU,EAAE,EAAE;KACf;IACD,KAAK,EAAE;QACL,SAAS,EAAE,CAAC,QAAQ,EAAE,iBAAiB,EAAE,mBAAmB,CAAC;QAC7D,QAAQ,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACvC,UAAU,EAAE,EAAE;KACf;IACD,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,QAAQ,EAAE,iBAAiB,EAAE,mBAAmB,CAAC;QAC7D,QAAQ,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACvC,UAAU,EAAE,EAAE;KACf;IACD,QAAQ,EAAE;QACR,SAAS,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACxC,QAAQ,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACvC,UAAU,EAAE,EAAE;KACf;IACD,IAAI,EAAE;QACJ,SAAS,EAAE,CAAC,QAAQ,EAAE,iBAAiB,EAAE,mBAAmB,CAAC;QAC7D,QAAQ,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;QACvC,UAAU,EAAE,EAAE;KACf;CACF,CAAC;AAEF;;GAEG;AACU,QAAA,uBAAuB,GAA4C;IAC9E,IAAI,EAAE;QACJ,iBAAiB,EAAE,oEAAoE;KACxF;IACD,KAAK,EAAE;QACL,YAAY,EAAE,wDAAwD;QACtE,eAAe,EAAE,gEAAgE;KAClF;IACD,GAAG,EAAE;QACH,YAAY,EAAE,wDAAwD;QACtE,eAAe,EAAE,gEAAgE;QACjF,cAAc,EAAE,+CAA+C;KAChE;IACD,QAAQ,EAAE;QACR,cAAc,EAAE,+CAA+C;KAChE;IACD,IAAI,EAAE;QACJ,YAAY,EAAE,wDAAwD;QACtE,eAAe,EAAE,gEAAgE;QACjF,cAAc,EAAE,+CAA+C;QAC/D,iBAAiB,EAAE,oEAAoE;KACxF;CACF,CAAC","sourcesContent":["/**\n * Widget Runtime Types\n *\n * Core types for the Tool UI widget system. These types define:\n * - UI rendering modes (html, react, mdx, markdown, auto)\n * - Bundling strategies (static vs dynamic)\n * - Widget manifests for caching and discovery\n * - Runtime payloads for tool responses\n * - CSP directives for security\n *\n * This module is the canonical source for widget types.\n * Both `@frontmcp/sdk` and external consumers (like AgentLink)\n * should import types from here.\n *\n * @packageDocumentation\n */\n\n// Import types from ui-config for use in this file\nimport type { WidgetServingMode as _WidgetServingMode } from './ui-config';\n\n// Re-export shared types from ui-config for backwards compatibility\nexport type {\n  TemplateHelpers,\n  TemplateContext,\n  TemplateBuilderFn,\n  UIContentSecurityPolicy,\n  WidgetDisplayMode,\n  WidgetServingMode,\n} from './ui-config';\n\n// Use the internal alias for WidgetServingMode within this file\ntype WidgetServingMode = _WidgetServingMode;\n\n// ============================================\n// UI Type (Renderer Selection)\n// ============================================\n\n/**\n * UI renderer type for widget templates.\n *\n * - `'html'`: Plain HTML template (with optional Handlebars enhancement)\n * - `'react'`: React component (SSR + optional hydration)\n * - `'mdx'`: MDX template (Markdown + JSX components)\n * - `'markdown'`: Pure Markdown (rendered via markdown engine)\n * - `'auto'`: Auto-detect from template; loads all renderers at runtime\n *\n * @example\n * ```typescript\n * // Explicit HTML mode\n * ui: {\n *   template: '<div>{{output.value}}</div>',\n *   uiType: 'html'\n * }\n *\n * // Auto-detect (loads all renderers)\n * ui: {\n *   template: MyReactComponent,\n *   uiType: 'auto'\n * }\n * ```\n */\nexport type UIType = 'html' | 'react' | 'mdx' | 'markdown' | 'auto';\n\n// ============================================\n// Bundling Mode\n// ============================================\n\n/**\n * Widget bundling strategy.\n *\n * - `'static'`: Widget shell is pre-compiled at startup and cached.\n *   Tool responses reference the cached widget via `ui://widget/{toolName}`.\n *   Data is injected at runtime via FrontMCP Bridge. **Default mode.**\n *\n * - `'dynamic'`: Fresh HTML is generated for each tool invocation.\n *   Use for debugging or when template logic depends on invocation context.\n *\n * @example\n * ```typescript\n * // Static mode (default, recommended)\n * ui: {\n *   template: WeatherWidget,\n *   bundlingMode: 'static'\n * }\n *\n * // Dynamic mode (debugging, fresh per call)\n * ui: {\n *   template: (ctx) => `<div>${ctx.output.debug}</div>`,\n *   bundlingMode: 'dynamic'\n * }\n * ```\n */\nexport type BundlingMode = 'static' | 'dynamic';\n\n// ============================================\n// Resource Mode (CDN vs Inline)\n// ============================================\n\n/**\n * Resource loading mode for widget dependencies.\n *\n * - `'cdn'`: Load React/MDX/Handlebars from CDN URLs (light, fast).\n *   Requires network access. Best for most platforms.\n *\n * - `'inline'`: Embed all scripts directly in the HTML (self-contained).\n *   Works in network-blocked environments (e.g., Claude Artifacts).\n *   Results in larger HTML payloads.\n *\n * @example\n * ```typescript\n * // CDN mode (default, lightweight)\n * ui: {\n *   template: WeatherWidget,\n *   resourceMode: 'cdn'\n * }\n *\n * // Inline mode (network-blocked environments)\n * ui: {\n *   template: WeatherWidget,\n *   resourceMode: 'inline'\n * }\n * ```\n */\nexport type ResourceMode = 'cdn' | 'inline';\n\n// ============================================\n// Output Mode (Client-Adaptive)\n// ============================================\n\n/**\n * Widget output mode - determines what is returned in tool responses.\n *\n * - `'code-only'`: Return just the transpiled/rendered content.\n *   The host platform (OpenAI, etc.) provides the runtime wrapper.\n *   Best for capable platforms that handle their own rendering.\n *\n * - `'full-ssr'`: Return complete SSR'd HTML with embedded data.\n *   Self-contained output for limited/unknown MCP clients.\n *   Includes FrontMCP Bridge, scripts, and all necessary runtime.\n *\n * @example\n * ```typescript\n * // For OpenAI - just return the rendered content\n * const result = await buildWidgetOutput({\n *   uiConfig,\n *   toolName: 'weather',\n *   outputMode: 'code-only',\n *   output: { temperature: 72 },\n * });\n * // result.content = '<div class=\"weather\">72°F</div>'\n *\n * // For unknown clients - return full HTML\n * const result = await buildWidgetOutput({\n *   uiConfig,\n *   toolName: 'weather',\n *   outputMode: 'full-ssr',\n *   output: { temperature: 72 },\n * });\n * // result.html = '<!DOCTYPE html>...'\n * ```\n */\nexport type OutputMode = 'code-only' | 'full-ssr';\n\n/**\n * Display mode for widget presentation.\n *\n * Note: This is an alias for `WidgetDisplayMode` from ui-config.ts.\n * Prefer using `WidgetDisplayMode` for new code.\n */\nexport type DisplayMode = 'inline' | 'fullscreen' | 'pip';\n\n// ============================================\n// CSP Directives (Granular)\n// ============================================\n\n/**\n * Content Security Policy directives for widget sandboxes.\n *\n * More granular than `UIContentSecurityPolicy`, this type\n * maps directly to CSP header directives.\n *\n * @example\n * ```typescript\n * const csp: CSPDirectives = {\n *   scriptSrc: [\"'self'\", \"'unsafe-inline'\", \"https://unpkg.com\"],\n *   styleSrc: [\"'self'\", \"'unsafe-inline'\"],\n *   connectSrc: [\"https://api.example.com\"],\n * };\n * ```\n */\nexport interface CSPDirectives {\n  /**\n   * Script source directives (CSP script-src).\n   * @example [\"'self'\", \"'unsafe-inline'\", \"https://unpkg.com\"]\n   */\n  scriptSrc: string[];\n\n  /**\n   * Style source directives (CSP style-src).\n   * @example [\"'self'\", \"'unsafe-inline'\"]\n   */\n  styleSrc: string[];\n\n  /**\n   * Connection source directives (CSP connect-src).\n   * Controls fetch/XHR/WebSocket destinations.\n   * @example [\"https://api.example.com\"]\n   */\n  connectSrc: string[];\n\n  /**\n   * Image source directives (CSP img-src).\n   * @example [\"'self'\", \"data:\", \"https://images.example.com\"]\n   */\n  imgSrc?: string[];\n\n  /**\n   * Font source directives (CSP font-src).\n   * @example [\"'self'\", \"https://fonts.gstatic.com\"]\n   */\n  fontSrc?: string[];\n\n  /**\n   * Default source directive (CSP default-src).\n   * @example [\"'self'\"]\n   */\n  defaultSrc?: string[];\n\n  /**\n   * Frame source directives (CSP frame-src).\n   * @example [\"'none'\"]\n   */\n  frameSrc?: string[];\n\n  /**\n   * Object source directives (CSP object-src).\n   * @example [\"'none'\"]\n   */\n  objectSrc?: string[];\n}\n\n// ============================================\n// CDN Resource\n// ============================================\n\n/**\n * CDN configuration for a single script resource.\n */\nexport interface CDNResource {\n  /**\n   * CDN URL for the script.\n   */\n  url: string;\n\n  /**\n   * Subresource integrity hash (SRI).\n   * @example \"sha384-...\"\n   */\n  integrity?: string;\n\n  /**\n   * Crossorigin attribute.\n   * @default \"anonymous\"\n   */\n  crossorigin?: 'anonymous' | 'use-credentials';\n}\n\n// ============================================\n// Renderer Assets\n// ============================================\n\n/**\n * External assets required by a renderer type.\n *\n * Supports two modes:\n * - CDN mode: Light payloads, scripts loaded from CDN URLs\n * - Inline mode: Self-contained, scripts embedded in HTML\n *\n * @example\n * ```typescript\n * // CDN mode (lightweight)\n * const assets: RendererAssets = {\n *   mode: 'cdn',\n *   react: { url: 'https://unpkg.com/react@18/umd/react.production.min.js' },\n *   reactDom: { url: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js' },\n * };\n *\n * // Inline mode (self-contained)\n * const assets: RendererAssets = {\n *   mode: 'inline',\n *   inlineReact: '/* minified react code *\\/',\n *   inlineReactDom: '/* minified react-dom code *\\/',\n * };\n * ```\n */\nexport interface RendererAssets {\n  /**\n   * Resource loading mode.\n   * - 'cdn': Load scripts from CDN URLs (light, requires network)\n   * - 'inline': Embed scripts in HTML (heavy, works offline)\n   * @default 'cdn'\n   */\n  mode: ResourceMode;\n\n  // ========== CDN Resources ==========\n\n  /**\n   * React UMD runtime CDN (for 'react' UI type).\n   */\n  react?: CDNResource;\n\n  /**\n   * ReactDOM UMD runtime CDN (for 'react' UI type with hydration).\n   */\n  reactDom?: CDNResource;\n\n  /**\n   * Markdown rendering engine CDN (for 'markdown' or 'mdx' types).\n   */\n  markdown?: CDNResource;\n\n  /**\n   * MDX runtime CDN (for 'mdx' type).\n   */\n  mdxRuntime?: CDNResource;\n\n  /**\n   * Handlebars runtime CDN (for enhanced HTML templates).\n   */\n  handlebars?: CDNResource;\n\n  /**\n   * Tailwind CSS CDN.\n   */\n  tailwind?: CDNResource;\n\n  // ========== Inline Resources ==========\n\n  /**\n   * Inline React runtime (for inline mode).\n   * Contains minified React UMD bundle.\n   */\n  inlineReact?: string;\n\n  /**\n   * Inline ReactDOM runtime (for inline mode).\n   * Contains minified ReactDOM UMD bundle.\n   */\n  inlineReactDom?: string;\n\n  /**\n   * Inline Handlebars runtime (for inline mode).\n   */\n  inlineHandlebars?: string;\n\n  /**\n   * Inline Markdown engine (for inline mode).\n   */\n  inlineMarkdown?: string;\n\n  /**\n   * Inline bundle content (compiled widget template).\n   * Contains the pre-bundled renderer + template code.\n   */\n  inlineBundle?: string;\n\n  // ========== Metadata ==========\n\n  /**\n   * Content hash of the bundled widget code.\n   * Used for cache invalidation.\n   */\n  bundleHash?: string;\n\n  // ========== Legacy (deprecated) ==========\n\n  /**\n   * @deprecated Use `react.url` instead\n   */\n  reactRuntime?: string;\n\n  /**\n   * @deprecated Use `reactDom.url` instead\n   */\n  reactDomRuntime?: string;\n\n  /**\n   * @deprecated Use `markdown.url` instead\n   */\n  markdownEngine?: string;\n\n  /**\n   * @deprecated Use `handlebars.url` instead\n   */\n  handlebarsRuntime?: string;\n}\n\n// ============================================\n// Widget Manifest\n// ============================================\n\n/**\n * Widget manifest describing a pre-compiled static widget.\n *\n * The manifest is embedded in the widget HTML and also cached\n * separately for quick lookups. It contains all metadata needed\n * for the runtime to render the widget correctly.\n *\n * @example\n * ```json\n * {\n *   \"tool\": \"weather.get\",\n *   \"uiType\": \"react\",\n *   \"bundlingMode\": \"static\",\n *   \"displayMode\": \"inline\",\n *   \"widgetAccessible\": true,\n *   \"schema\": { \"type\": \"object\", \"properties\": {...} },\n *   \"csp\": { \"scriptSrc\": [\"'self'\"], ... },\n *   \"rendererAssets\": { \"reactRuntime\": \"https://...\" },\n *   \"hash\": \"sha256-abc123...\"\n * }\n * ```\n */\nexport interface WidgetManifest {\n  /**\n   * Tool name (unique identifier).\n   * @example \"weather.get\"\n   */\n  tool: string;\n\n  /**\n   * UI renderer type.\n   */\n  uiType: UIType;\n\n  /**\n   * Bundling mode used to create this widget.\n   */\n  bundlingMode: BundlingMode;\n\n  /**\n   * Preferred display mode for the widget.\n   */\n  displayMode: DisplayMode;\n\n  /**\n   * Whether the widget can invoke tools via MCP bridge.\n   * When true, widget has access to `window.mcpBridge.callTool()`.\n   */\n  widgetAccessible: boolean;\n\n  /**\n   * JSON Schema describing the tool's output structure.\n   * Used for type hints and validation.\n   */\n  schema: object;\n\n  /**\n   * Content Security Policy directives.\n   */\n  csp: CSPDirectives;\n\n  /**\n   * External assets required by the renderer.\n   */\n  rendererAssets: RendererAssets;\n\n  /**\n   * SHA-256 hash of the manifest + HTML content.\n   * Used for cache validation and ETag generation.\n   */\n  hash: string;\n\n  /**\n   * Timestamp when the manifest was created (ISO 8601).\n   */\n  createdAt?: string;\n\n  /**\n   * Human-readable description of the widget.\n   */\n  description?: string;\n\n  /**\n   * Widget URI in the MCP resource format.\n   * @example \"ui://widget/weather.get.html\"\n   */\n  uri?: string;\n}\n\n// ============================================\n// Runtime Payload (_meta fields)\n// ============================================\n\n/**\n * UI metadata fields emitted in tool response `_meta`.\n *\n * All UI-related data goes in `_meta`, NOT in the `content` array.\n * The MCP client reads these fields to render the widget.\n *\n * @example\n * ```typescript\n * // Tool response structure\n * {\n *   content: [{ type: 'text', text: 'Weather data retrieved' }],\n *   _meta: {\n *     // UI type for renderer selection\n *     'ui/type': 'react',\n *\n *     // Transpiled widget code (for capable clients like OpenAI)\n *     'ui/content': '<div class=\"weather\">72°F Sunny</div>',\n *\n *     // OR full HTML (for limited clients)\n *     'ui/html': '<!DOCTYPE html>...',\n *\n *     // Content hash for caching\n *     'ui/hash': 'sha256-abc123...',\n *\n *     // Display mode hint\n *     'ui/displayMode': 'inline',\n *\n *     // Widget can call tools\n *     'ui/widgetAccessible': true,\n *\n *     // OpenAI-specific CSP\n *     'openai/widgetCSP': { connect_domains: ['api.weather.com'] },\n *   }\n * }\n * ```\n */\nexport interface UIMetaFields {\n  /**\n   * UI renderer type.\n   * Maps to `_meta['ui/type']`.\n   */\n  'ui/type': UIType;\n\n  /**\n   * Transpiled widget content (code-only mode).\n   * Just the rendered template without wrapper HTML.\n   * Use for capable clients (OpenAI) that provide their own runtime.\n   * Maps to `_meta['ui/content']`.\n   */\n  'ui/content'?: string;\n\n  /**\n   * Full HTML document (full-ssr mode).\n   * Complete self-contained HTML with scripts, bridge, etc.\n   * Use for limited/unknown MCP clients.\n   * Maps to `_meta['ui/html']`.\n   */\n  'ui/html'?: string;\n\n  /**\n   * Content hash for cache validation.\n   * Maps to `_meta['ui/hash']`.\n   */\n  'ui/hash': string;\n\n  /**\n   * Display mode hint.\n   * Maps to `_meta['ui/displayMode']`.\n   */\n  'ui/displayMode'?: DisplayMode;\n\n  /**\n   * Whether widget can invoke tools via MCP bridge.\n   * Maps to `_meta['ui/widgetAccessible']`.\n   */\n  'ui/widgetAccessible'?: boolean;\n\n  /**\n   * Widget description for accessibility.\n   * Maps to `_meta['ui/description']`.\n   */\n  'ui/description'?: string;\n\n  /**\n   * Resource mode used (cdn or inline).\n   * Maps to `_meta['ui/resourceMode']`.\n   */\n  'ui/resourceMode'?: ResourceMode;\n}\n\n/**\n * OpenAI-specific meta fields.\n * These are in addition to the standard UI fields.\n */\nexport interface OpenAIMetaFields {\n  /**\n   * OpenAI CSP configuration.\n   * Maps to `_meta['openai/widgetCSP']`.\n   */\n  'openai/widgetCSP'?: {\n    connect_domains?: string[];\n    resource_domains?: string[];\n  };\n\n  /**\n   * OpenAI widget accessible flag.\n   * Maps to `_meta['openai/widgetAccessible']`.\n   */\n  'openai/widgetAccessible'?: boolean;\n\n  /**\n   * OpenAI widget description.\n   * Maps to `_meta['openai/widgetDescription']`.\n   */\n  'openai/widgetDescription'?: string;\n\n  /**\n   * OpenAI display mode.\n   * Maps to `_meta['openai/displayMode']`.\n   */\n  'openai/displayMode'?: 'inline' | 'fullscreen' | 'pip';\n}\n\n/**\n * Combined meta fields for tool responses.\n * Includes both standard UI fields and platform-specific fields.\n */\nexport type ToolResponseMeta = Partial<UIMetaFields> & Partial<OpenAIMetaFields> & Record<string, unknown>;\n\n/**\n * @deprecated Use UIMetaFields instead. RuntimePayload is being replaced\n * with explicit _meta field types.\n */\nexport interface RuntimePayload {\n  /**\n   * Resolved UI type for this invocation.\n   * @deprecated Use UIMetaFields['ui/type']\n   */\n  type: UIType;\n\n  /**\n   * Rendered/compiled content.\n   * @deprecated Use UIMetaFields['ui/content']\n   */\n  content: string;\n\n  /**\n   * Content hash for cache validation.\n   * @deprecated Use UIMetaFields['ui/hash']\n   */\n  hash: string;\n\n  /**\n   * Hydration data for React components.\n   */\n  hydrationData?: unknown;\n\n  /**\n   * Structured tool output (JSON-serializable).\n   */\n  toolOutput?: unknown;\n\n  /**\n   * Additional metadata for the runtime.\n   */\n  metadata?: Record<string, unknown>;\n}\n\n// ============================================\n// Widget Configuration\n// ============================================\n\n/**\n * Widget template types supported by the system.\n *\n * - String: HTML/MDX/Markdown content\n * - Builder function: Receives context, returns HTML string\n * - React component: SSR'd with props from context\n */\nexport type WidgetTemplate =\n  | string\n  | ((ctx: WidgetTemplateContext) => string)\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  | React.ComponentType<WidgetTemplateContext>;\n\n/**\n * Context passed to widget templates.\n *\n * This is a more specific version of `TemplateContext` with\n * explicit typing for widget rendering.\n */\nexport interface WidgetTemplateContext<Input = Record<string, unknown>, Output = unknown> {\n  /**\n   * Tool input arguments.\n   */\n  input: Input;\n\n  /**\n   * Tool output/result.\n   */\n  output: Output;\n\n  /**\n   * Structured content parsed from output (if schema provided).\n   */\n  structuredContent?: unknown;\n\n  /**\n   * Template helper functions.\n   */\n  helpers: WidgetTemplateHelpers;\n}\n\n/**\n * Helper functions available in widget templates.\n */\nexport interface WidgetTemplateHelpers {\n  /**\n   * Escape HTML special characters to prevent XSS.\n   */\n  escapeHtml(str: string): string;\n\n  /**\n   * Format a date for display.\n   * @param date - Date object or ISO string\n   * @param format - Optional format string\n   */\n  formatDate(date: Date | string, format?: string): string;\n\n  /**\n   * Format a number as currency.\n   * @param amount - Numeric amount\n   * @param currency - ISO 4217 currency code (default: 'USD')\n   */\n  formatCurrency(amount: number, currency?: string): string;\n\n  /**\n   * Generate a unique ID for DOM elements.\n   * @param prefix - Optional prefix\n   */\n  uniqueId(prefix?: string): string;\n\n  /**\n   * Safely embed JSON data in HTML.\n   * Escapes script-breaking characters.\n   */\n  jsonEmbed(data: unknown): string;\n\n  /**\n   * Conditionally join class names.\n   * @param classes - Class names (falsy values are filtered)\n   */\n  classNames(...classes: (string | false | undefined | null)[]): string;\n\n  /**\n   * Format a number with locale-aware separators.\n   */\n  formatNumber(value: number, options?: Intl.NumberFormatOptions): string;\n}\n\n/**\n * Widget configuration for tool UI templates.\n *\n * This is the main configuration type used in tool decorators\n * and standalone widget compilation.\n *\n * @example\n * ```typescript\n * const config: WidgetConfig = {\n *   template: WeatherWidget,\n *   uiType: 'react',\n *   bundlingMode: 'static',\n *   displayMode: 'inline',\n *   widgetAccessible: true,\n *   csp: { connectSrc: ['https://api.weather.com'] },\n * };\n * ```\n */\nexport interface WidgetConfig<Input = Record<string, unknown>, Output = unknown> {\n  /**\n   * Widget template.\n   *\n   * Supports:\n   * - HTML string (with optional Handlebars syntax)\n   * - MDX string\n   * - Template builder function\n   * - React component\n   */\n  template: WidgetTemplate | ((ctx: WidgetTemplateContext<Input, Output>) => string);\n\n  /**\n   * UI renderer type.\n   *\n   * - `'html'`: HTML with optional Handlebars\n   * - `'react'`: React component (SSR)\n   * - `'mdx'`: MDX template\n   * - `'markdown'`: Pure Markdown\n   * - `'auto'`: Auto-detect from template (default)\n   *\n   * @default 'auto'\n   */\n  uiType?: UIType;\n\n  /**\n   * Bundling mode.\n   *\n   * - `'static'`: Pre-compile widget shell, inject data at runtime (default)\n   * - `'dynamic'`: Generate fresh HTML per tool invocation\n   *\n   * @default 'static'\n   */\n  bundlingMode?: BundlingMode;\n\n  /**\n   * Display mode preference.\n   *\n   * - `'inline'`: Render inline in conversation (default)\n   * - `'fullscreen'`: Request fullscreen display\n   * - `'pip'`: Picture-in-picture mode\n   *\n   * @default 'inline'\n   */\n  displayMode?: DisplayMode;\n\n  /**\n   * Resource loading mode.\n   *\n   * - `'cdn'`: Load React/MDX/Handlebars from CDN URLs (lightweight)\n   * - `'inline'`: Embed all scripts in HTML (self-contained)\n   *\n   * Use 'cdn' for most platforms (OpenAI, ChatGPT, Cursor).\n   * Use 'inline' for network-blocked environments (Claude Artifacts).\n   *\n   * @default 'cdn'\n   */\n  resourceMode?: ResourceMode;\n\n  /**\n   * Content Security Policy overrides.\n   *\n   * Merged with auto-generated CSP based on uiType.\n   */\n  csp?: Partial<CSPDirectives>;\n\n  /**\n   * Whether widget can invoke tools via MCP bridge.\n   *\n   * When true, widget gets access to `window.mcpBridge.callTool()`.\n   *\n   * @default false\n   */\n  widgetAccessible?: boolean;\n\n  /**\n   * Human-readable description shown to users.\n   * Maps to OpenAI's `openai/widgetDescription`.\n   */\n  widgetDescription?: string;\n\n  /**\n   * Runtime options for specific renderers.\n   */\n  runtimeOptions?: WidgetRuntimeOptions;\n\n  /**\n   * Custom MDX components available in templates.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  mdxComponents?: Record<string, any>;\n\n  /**\n   * Status messages during tool invocation (OpenAI-specific).\n   */\n  invocationStatus?: {\n    /** Status text while tool is executing */\n    invoking?: string;\n    /** Status text after execution completes */\n    invoked?: string;\n  };\n\n  // ============================================\n  // Serving Mode Options\n  // ============================================\n\n  /**\n   * How the widget HTML should be served to the client.\n   *\n   * - `'inline'`: HTML embedded directly in tool response `_meta['ui/html']`\n   * - `'static'`: Pre-compiled at startup, via `ui://` resource URI (MCP resources/read)\n   * - `'hybrid'`: Shell pre-compiled at startup, component in response\n   * - `'direct-url'`: HTTP endpoint on MCP server\n   * - `'custom-url'`: Custom URL (CDN or external hosting)\n   *\n   * @default 'inline'\n   */\n  servingMode?: WidgetServingMode;\n\n  /**\n   * Custom URL for widget serving when `servingMode: 'custom-url'`.\n   * The URL can include `{token}` placeholder which will be replaced\n   * with the widget access token.\n   *\n   * @example 'https://cdn.example.com/widgets/weather.html?token={token}'\n   */\n  customWidgetUrl?: string;\n\n  /**\n   * Path for direct URL serving when `servingMode: 'direct-url'`.\n   * This path is appended to the MCP server's base URL.\n   *\n   * @example '/widgets/weather'\n   */\n  directPath?: string;\n\n  // ============================================\n  // MCP Apps (ext-apps) Specific Options\n  // ============================================\n\n  /**\n   * Whether to show a border around the UI widget.\n   * MCP Apps spec: `_meta.ui.prefersBorder`\n   *\n   * @default undefined (host decides)\n   */\n  prefersBorder?: boolean;\n\n  /**\n   * Dedicated sandbox domain for the widget.\n   * MCP Apps spec: `_meta.ui.domain`\n   *\n   * @example 'sandbox.example.com'\n   */\n  sandboxDomain?: string;\n\n  // ============================================\n  // Hydration Options\n  // ============================================\n\n  /**\n   * Enable client-side React hydration after server-side rendering (SSR).\n   *\n   * **Default: `false`**\n   *\n   * When `false` (default):\n   * - SSR output is static HTML\n   * - No React runtime loaded on client\n   * - Interactivity via FrontMCP Bridge\n   *\n   * When `true`:\n   * - React/ReactDOM scripts included\n   * - Client attempts hydration\n   * - May cause hydration errors in MCP clients\n   *\n   * @default false\n   */\n  hydrate?: boolean;\n}\n\n/**\n * Runtime options for widget renderers.\n */\nexport interface WidgetRuntimeOptions {\n  /**\n   * Enable React hydration after SSR.\n   *\n   * **Default: false**\n   *\n   * When false (recommended):\n   * - SSR output is static HTML\n   * - No React runtime loaded on client\n   * - Interactivity via FrontMCP Bridge\n   *\n   * When true:\n   * - React/ReactDOM scripts included\n   * - Client attempts hydration\n   * - May cause hydration errors in MCP clients\n   */\n  hydrate?: boolean;\n\n  /**\n   * Markdown rendering options.\n   */\n  markdown?: {\n    /** Enable GitHub-flavored markdown */\n    gfm?: boolean;\n    /** Syntax highlighting theme */\n    highlightTheme?: string;\n    /** Custom renderer overrides */\n    rendererOverrides?: Record<string, unknown>;\n  };\n\n  /**\n   * Handlebars options (for HTML templates).\n   */\n  handlebars?: {\n    /** Custom helpers to register */\n    helpers?: Record<string, (...args: unknown[]) => string>;\n    /** Custom partials */\n    partials?: Record<string, string>;\n    /** Strict mode (error on missing variables) */\n    strict?: boolean;\n  };\n}\n\n// ============================================\n// Build Result Types\n// ============================================\n\n/**\n * Result of building a widget manifest.\n *\n * Returned by `buildToolWidgetManifest()` and used\n * by `ToolUIRegistry` for caching.\n *\n * The result contains both:\n * - `content`: Just the rendered template (for capable clients like OpenAI)\n * - `html`: Complete HTML document (for limited/unknown clients)\n *\n * Choose which to use based on the target client capabilities.\n */\nexport interface BuildManifestResult {\n  /**\n   * Rendered template content (transpiled code).\n   *\n   * This is just the template output WITHOUT the wrapper HTML.\n   * Use this for capable clients (OpenAI, etc.) that provide\n   * their own runtime environment.\n   *\n   * @example\n   * For a React component, this would be the SSR'd HTML:\n   * `<div class=\"weather-card\"><h1>72°F</h1><p>Sunny</p></div>`\n   */\n  content: string;\n\n  /**\n   * Complete HTML document string.\n   *\n   * Contains embedded manifest, FrontMCP Bridge, scripts, and template.\n   * Use this for limited/unknown MCP clients that need a\n   * self-contained HTML document.\n   *\n   * @example\n   * `<!DOCTYPE html><html>...<body>{{content}}</body></html>`\n   */\n  html: string;\n\n  /**\n   * Widget manifest (also embedded in HTML).\n   */\n  manifest: WidgetManifest;\n\n  /**\n   * Content hash for cache validation.\n   */\n  hash: string;\n\n  /**\n   * Resolved renderer type.\n   */\n  rendererType: UIType;\n\n  /**\n   * Transpiled component code for client-side rendering.\n   *\n   * For React/MDX templates, this contains the transpiled component\n   * that can be embedded in the widget HTML for client-side re-rendering\n   * when tool output becomes available.\n   *\n   * This is used by `wrapStaticWidgetUniversal` for static mode.\n   */\n  componentCode?: string;\n\n  /**\n   * Size of content in bytes.\n   */\n  contentSize: number;\n\n  /**\n   * Size of full HTML in bytes.\n   */\n  htmlSize: number;\n\n  /**\n   * Estimated gzipped size of full HTML.\n   */\n  gzipSize: number;\n\n  /**\n   * @deprecated Use `htmlSize` instead\n   */\n  size: number;\n}\n\n/**\n * Options for building a widget manifest.\n */\nexport interface BuildManifestOptions<Input = Record<string, unknown>, Output = unknown> {\n  /**\n   * Tool name (unique identifier).\n   */\n  toolName: string;\n\n  /**\n   * Widget configuration.\n   */\n  uiConfig: WidgetConfig<Input, Output>;\n\n  /**\n   * JSON Schema for tool output.\n   * Used for validation and type hints.\n   */\n  schema?: object;\n\n  /**\n   * Theme configuration override.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  theme?: any;\n\n  /**\n   * Sample input for SSR (static mode).\n   * Used during pre-compilation.\n   */\n  sampleInput?: Input;\n\n  /**\n   * Sample output for SSR (static mode).\n   * Used during pre-compilation.\n   */\n  sampleOutput?: Output;\n}\n\n// ============================================\n// Type Guards\n// ============================================\n\n/**\n * Check if a value is a valid UIType.\n */\nexport function isUIType(value: unknown): value is UIType {\n  return typeof value === 'string' && ['html', 'react', 'mdx', 'markdown', 'auto'].includes(value);\n}\n\n/**\n * Check if a value is a valid BundlingMode.\n */\nexport function isBundlingMode(value: unknown): value is BundlingMode {\n  return typeof value === 'string' && ['static', 'dynamic'].includes(value);\n}\n\n/**\n * Check if a value is a valid ResourceMode.\n */\nexport function isResourceMode(value: unknown): value is ResourceMode {\n  return typeof value === 'string' && ['cdn', 'inline'].includes(value);\n}\n\n/**\n * Check if a value is a valid DisplayMode.\n */\nexport function isDisplayMode(value: unknown): value is DisplayMode {\n  return typeof value === 'string' && ['inline', 'fullscreen', 'pip'].includes(value);\n}\n\n/**\n * Check if a value is a valid OutputMode.\n */\nexport function isOutputMode(value: unknown): value is OutputMode {\n  return typeof value === 'string' && ['code-only', 'full-ssr'].includes(value);\n}\n\n// ============================================\n// Default Values\n// ============================================\n\n/**\n * Default CSP directives for different UI types.\n */\nexport const DEFAULT_CSP_BY_TYPE: Record<UIType, CSPDirectives> = {\n  html: {\n    scriptSrc: [\"'self'\", \"'unsafe-inline'\"],\n    styleSrc: [\"'self'\", \"'unsafe-inline'\"],\n    connectSrc: [],\n  },\n  react: {\n    scriptSrc: [\"'self'\", \"'unsafe-inline'\", 'https://unpkg.com'],\n    styleSrc: [\"'self'\", \"'unsafe-inline'\"],\n    connectSrc: [],\n  },\n  mdx: {\n    scriptSrc: [\"'self'\", \"'unsafe-inline'\", 'https://unpkg.com'],\n    styleSrc: [\"'self'\", \"'unsafe-inline'\"],\n    connectSrc: [],\n  },\n  markdown: {\n    scriptSrc: [\"'self'\", \"'unsafe-inline'\"],\n    styleSrc: [\"'self'\", \"'unsafe-inline'\"],\n    connectSrc: [],\n  },\n  auto: {\n    scriptSrc: [\"'self'\", \"'unsafe-inline'\", 'https://unpkg.com'],\n    styleSrc: [\"'self'\", \"'unsafe-inline'\"],\n    connectSrc: [],\n  },\n};\n\n/**\n * Default renderer assets for different UI types.\n */\nexport const DEFAULT_RENDERER_ASSETS: Record<UIType, Partial<RendererAssets>> = {\n  html: {\n    handlebarsRuntime: 'https://unpkg.com/handlebars@latest/dist/handlebars.runtime.min.js',\n  },\n  react: {\n    reactRuntime: 'https://unpkg.com/react@18/umd/react.production.min.js',\n    reactDomRuntime: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',\n  },\n  mdx: {\n    reactRuntime: 'https://unpkg.com/react@18/umd/react.production.min.js',\n    reactDomRuntime: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',\n    markdownEngine: 'https://unpkg.com/marked@latest/marked.min.js',\n  },\n  markdown: {\n    markdownEngine: 'https://unpkg.com/marked@latest/marked.min.js',\n  },\n  auto: {\n    reactRuntime: 'https://unpkg.com/react@18/umd/react.production.min.js',\n    reactDomRuntime: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',\n    markdownEngine: 'https://unpkg.com/marked@latest/marked.min.js',\n    handlebarsRuntime: 'https://unpkg.com/handlebars@latest/dist/handlebars.runtime.min.js',\n  },\n};\n\n// ============================================\n// React Type Declaration (for JSX support)\n// ============================================\n\n/**\n * React namespace declaration for type safety.\n * This allows React.ComponentType to work without importing React.\n */\ndeclare namespace React {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  type ComponentType<P = any> = (props: P) => any;\n}\n"]}

package/src/validation/error-box.d.ts

@@ -1,55 +0,0 @@
-/**
- * @file error-box.ts
- * @description Validation error box component for displaying input validation failures.
- *
- * Renders a styled error card when component options fail Zod validation.
- * Shows component name and invalid parameter without exposing internal details.
- *
- * @example
- * ```typescript
- * import { validationErrorBox } from '@frontmcp/ui';
- *
- * validationErrorBox({
- *   componentName: 'Button',
- *   invalidParam: 'variant',
- * });
- * ```
- *
- * @module @frontmcp/ui/validation/error-box
- */
-/**
- * Options for rendering a validation error box
- */
-export interface ValidationErrorBoxOptions {
-    /** Name of the component that failed validation */
-    componentName: string;
-    /** Name of the invalid parameter (path notation for nested, e.g., "htmx.get") */
-    invalidParam: string;
-}
-/**
- * Renders a validation error box for invalid component options
- *
- * This component is rendered in place of the actual component when
- * validation fails. It shows:
- * - The component name
- * - The invalid parameter name
- * - A styled error message
- *
- * It does NOT expose:
- * - The actual invalid value
- * - Internal Zod error messages
- * - Schema structure details
- *
- * @param options - Error box configuration
- * @returns HTML string for the error box
- *
- * @example
- * ```typescript
- * // Basic usage
- * validationErrorBox({ componentName: 'Button', invalidParam: 'variant' });
- *
- * // Nested param
- * validationErrorBox({ componentName: 'Button', invalidParam: 'htmx.get' });
- * ```
- */
-export declare function validationErrorBox(options: ValidationErrorBoxOptions): string;

package/src/validation/error-box.js

@@ -1,75 +0,0 @@
-"use strict";
-/**
- * @file error-box.ts
- * @description Validation error box component for displaying input validation failures.
- *
- * Renders a styled error card when component options fail Zod validation.
- * Shows component name and invalid parameter without exposing internal details.
- *
- * @example
- * ```typescript
- * import { validationErrorBox } from '@frontmcp/ui';
- *
- * validationErrorBox({
- *   componentName: 'Button',
- *   invalidParam: 'variant',
- * });
- * ```
- *
- * @module @frontmcp/ui/validation/error-box
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validationErrorBox = validationErrorBox;
-const base_1 = require("../layouts/base");
-// ============================================
-// Error Box Component
-// ============================================
-/**
- * Error icon SVG
- */
-const errorIcon = `<svg class="w-5 h-5 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
-  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
-</svg>`;
-/**
- * Renders a validation error box for invalid component options
- *
- * This component is rendered in place of the actual component when
- * validation fails. It shows:
- * - The component name
- * - The invalid parameter name
- * - A styled error message
- *
- * It does NOT expose:
- * - The actual invalid value
- * - Internal Zod error messages
- * - Schema structure details
- *
- * @param options - Error box configuration
- * @returns HTML string for the error box
- *
- * @example
- * ```typescript
- * // Basic usage
- * validationErrorBox({ componentName: 'Button', invalidParam: 'variant' });
- *
- * // Nested param
- * validationErrorBox({ componentName: 'Button', invalidParam: 'htmx.get' });
- * ```
- */
-function validationErrorBox(options) {
-    const { componentName, invalidParam } = options;
-    return `<div
-  class="validation-error flex items-start gap-3 p-4 bg-red-50 border border-red-200 text-red-800 rounded-lg"
-  role="alert"
-  data-testid="validation-error"
-  data-component="${(0, base_1.escapeHtml)(componentName)}"
-  data-param="${(0, base_1.escapeHtml)(invalidParam)}"
->
-  ${errorIcon}
-  <div class="min-w-0">
-    <p class="font-semibold text-sm">${(0, base_1.escapeHtml)(componentName)}: Invalid Configuration</p>
-    <p class="text-sm opacity-90 mt-0.5">The "${(0, base_1.escapeHtml)(invalidParam)}" parameter is invalid.</p>
-  </div>
-</div>`;
-}
-//# sourceMappingURL=error-box.js.map

package/src/validation/error-box.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"error-box.js","sourceRoot":"","sources":["../../../src/validation/error-box.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AAuDH,gDAgBC;AArED,0CAA6C;AAgB7C,+CAA+C;AAC/C,sBAAsB;AACtB,+CAA+C;AAE/C;;GAEG;AACH,MAAM,SAAS,GAAG;;OAEX,CAAC;AAER;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,kBAAkB,CAAC,OAAkC;IACnE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAEhD,OAAO;;;;oBAIW,IAAA,iBAAU,EAAC,aAAa,CAAC;gBAC7B,IAAA,iBAAU,EAAC,YAAY,CAAC;;IAEpC,SAAS;;uCAE0B,IAAA,iBAAU,EAAC,aAAa,CAAC;gDAChB,IAAA,iBAAU,EAAC,YAAY,CAAC;;OAEjE,CAAC;AACR,CAAC","sourcesContent":["/**\n * @file error-box.ts\n * @description Validation error box component for displaying input validation failures.\n *\n * Renders a styled error card when component options fail Zod validation.\n * Shows component name and invalid parameter without exposing internal details.\n *\n * @example\n * ```typescript\n * import { validationErrorBox } from '@frontmcp/ui';\n *\n * validationErrorBox({\n *   componentName: 'Button',\n *   invalidParam: 'variant',\n * });\n * ```\n *\n * @module @frontmcp/ui/validation/error-box\n */\n\nimport { escapeHtml } from '../layouts/base';\n\n// ============================================\n// Types\n// ============================================\n\n/**\n * Options for rendering a validation error box\n */\nexport interface ValidationErrorBoxOptions {\n  /** Name of the component that failed validation */\n  componentName: string;\n  /** Name of the invalid parameter (path notation for nested, e.g., \"htmx.get\") */\n  invalidParam: string;\n}\n\n// ============================================\n// Error Box Component\n// ============================================\n\n/**\n * Error icon SVG\n */\nconst errorIcon = `<svg class=\"w-5 h-5 flex-shrink-0\" fill=\"none\" stroke=\"currentColor\" viewBox=\"0 0 24 24\" aria-hidden=\"true\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z\"/>\n</svg>`;\n\n/**\n * Renders a validation error box for invalid component options\n *\n * This component is rendered in place of the actual component when\n * validation fails. It shows:\n * - The component name\n * - The invalid parameter name\n * - A styled error message\n *\n * It does NOT expose:\n * - The actual invalid value\n * - Internal Zod error messages\n * - Schema structure details\n *\n * @param options - Error box configuration\n * @returns HTML string for the error box\n *\n * @example\n * ```typescript\n * // Basic usage\n * validationErrorBox({ componentName: 'Button', invalidParam: 'variant' });\n *\n * // Nested param\n * validationErrorBox({ componentName: 'Button', invalidParam: 'htmx.get' });\n * ```\n */\nexport function validationErrorBox(options: ValidationErrorBoxOptions): string {\n  const { componentName, invalidParam } = options;\n\n  return `<div\n  class=\"validation-error flex items-start gap-3 p-4 bg-red-50 border border-red-200 text-red-800 rounded-lg\"\n  role=\"alert\"\n  data-testid=\"validation-error\"\n  data-component=\"${escapeHtml(componentName)}\"\n  data-param=\"${escapeHtml(invalidParam)}\"\n>\n  ${errorIcon}\n  <div class=\"min-w-0\">\n    <p class=\"font-semibold text-sm\">${escapeHtml(componentName)}: Invalid Configuration</p>\n    <p class=\"text-sm opacity-90 mt-0.5\">The \"${escapeHtml(invalidParam)}\" parameter is invalid.</p>\n  </div>\n</div>`;\n}\n"]}

package/src/validation/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * @file index.ts
- * @description Validation module exports for @frontmcp/ui.
- *
- * Provides Zod-based input validation utilities for UI components.
- * All components use these utilities to validate options at runtime
- * and display user-friendly error boxes on invalid input.
- *
- * @module @frontmcp/ui/validation
- */
-export { validationErrorBox, type ValidationErrorBoxOptions } from './error-box';
-export { validateOptions, withValidation, type ValidationConfig, type ValidationResult } from './wrapper';

package/src/validation/index.js

@@ -1,21 +0,0 @@
-"use strict";
-/**
- * @file index.ts
- * @description Validation module exports for @frontmcp/ui.
- *
- * Provides Zod-based input validation utilities for UI components.
- * All components use these utilities to validate options at runtime
- * and display user-friendly error boxes on invalid input.
- *
- * @module @frontmcp/ui/validation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withValidation = exports.validateOptions = exports.validationErrorBox = void 0;
-// Error box component
-var error_box_1 = require("./error-box");
-Object.defineProperty(exports, "validationErrorBox", { enumerable: true, get: function () { return error_box_1.validationErrorBox; } });
-// Validation wrapper utilities
-var wrapper_1 = require("./wrapper");
-Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return wrapper_1.validateOptions; } });
-Object.defineProperty(exports, "withValidation", { enumerable: true, get: function () { return wrapper_1.withValidation; } });
-//# sourceMappingURL=index.js.map

package/src/validation/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,sBAAsB;AACtB,yCAAiF;AAAxE,+GAAA,kBAAkB,OAAA;AAE3B,+BAA+B;AAC/B,qCAA0G;AAAjG,0GAAA,eAAe,OAAA;AAAE,yGAAA,cAAc,OAAA","sourcesContent":["/**\n * @file index.ts\n * @description Validation module exports for @frontmcp/ui.\n *\n * Provides Zod-based input validation utilities for UI components.\n * All components use these utilities to validate options at runtime\n * and display user-friendly error boxes on invalid input.\n *\n * @module @frontmcp/ui/validation\n */\n\n// Error box component\nexport { validationErrorBox, type ValidationErrorBoxOptions } from './error-box';\n\n// Validation wrapper utilities\nexport { validateOptions, withValidation, type ValidationConfig, type ValidationResult } from './wrapper';\n"]}

package/src/validation/wrapper.d.ts

@@ -1,96 +0,0 @@
-/**
- * @file wrapper.ts
- * @description Validation wrapper utilities for component input validation.
- *
- * Provides functions to validate component options against Zod schemas
- * and return either the validated data or an error box HTML string.
- *
- * @example
- * ```typescript
- * import { validateOptions } from '@frontmcp/ui';
- * import { z } from 'zod';
- *
- * const schema = z.object({ variant: z.enum(['primary', 'secondary']) });
- *
- * const result = validateOptions(options, {
- *   componentName: 'Button',
- *   schema,
- * });
- *
- * if (!result.success) return result.error; // Returns error box HTML
- *
- * // Use result.data safely
- * ```
- *
- * @module @frontmcp/ui/validation/wrapper
- */
-import { type ZodSchema } from 'zod';
-/**
- * Configuration for validation
- */
-export interface ValidationConfig {
-    /** Name of the component being validated */
-    componentName: string;
-    /** Zod schema to validate against */
-    schema: ZodSchema;
-}
-/**
- * Result of validation - either success with data or failure with error HTML
- */
-export type ValidationResult<T> = {
-    success: true;
-    data: T;
-} | {
-    success: false;
-    error: string;
-};
-/**
- * Validates input against a Zod schema
- *
- * Returns either:
- * - `{ success: true, data: T }` with validated/parsed data
- * - `{ success: false, error: string }` with error box HTML
- *
- * @param options - The options object to validate
- * @param config - Validation configuration (component name and schema)
- * @returns ValidationResult with either data or error HTML
- *
- * @example
- * ```typescript
- * const result = validateOptions({ variant: 'invalid' }, {
- *   componentName: 'Button',
- *   schema: ButtonOptionsSchema,
- * });
- *
- * if (!result.success) {
- *   return result.error; // Error box HTML
- * }
- *
- * // result.data is typed and validated
- * ```
- */
-export declare function validateOptions<T>(options: unknown, config: ValidationConfig): ValidationResult<T>;
-/**
- * Higher-order function to wrap a component function with validation
- *
- * Creates a new function that validates the options before calling the
- * original component. If validation fails, returns the error box HTML
- * instead of calling the component.
- *
- * @param componentFn - The original component function
- * @param config - Validation configuration
- * @returns Wrapped function that validates before calling
- *
- * @example
- * ```typescript
- * const buttonImpl = (text: string, opts: ButtonOptions) => `<button>...</button>`;
- *
- * const button = withValidation(buttonImpl, {
- *   componentName: 'Button',
- *   schema: ButtonOptionsSchema,
- * });
- *
- * // button() now validates options before rendering
- * ```
- */
-export declare function withValidation<TInput, TOptions>(componentFn: (input: TInput, options: TOptions) => string, config: ValidationConfig): (input: TInput, options: unknown) => string;

package/src/validation/wrapper.js

@@ -1,117 +0,0 @@
-"use strict";
-/**
- * @file wrapper.ts
- * @description Validation wrapper utilities for component input validation.
- *
- * Provides functions to validate component options against Zod schemas
- * and return either the validated data or an error box HTML string.
- *
- * @example
- * ```typescript
- * import { validateOptions } from '@frontmcp/ui';
- * import { z } from 'zod';
- *
- * const schema = z.object({ variant: z.enum(['primary', 'secondary']) });
- *
- * const result = validateOptions(options, {
- *   componentName: 'Button',
- *   schema,
- * });
- *
- * if (!result.success) return result.error; // Returns error box HTML
- *
- * // Use result.data safely
- * ```
- *
- * @module @frontmcp/ui/validation/wrapper
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateOptions = validateOptions;
-exports.withValidation = withValidation;
-const error_box_1 = require("./error-box");
-// ============================================
-// Validation Functions
-// ============================================
-/**
- * Extract the path of the first invalid field from a Zod error
- */
-function getFirstInvalidPath(error) {
-    const firstError = error.issues[0];
-    if (!firstError || firstError.path.length === 0) {
-        return 'options';
-    }
-    return firstError.path.map(String).join('.');
-}
-/**
- * Validates input against a Zod schema
- *
- * Returns either:
- * - `{ success: true, data: T }` with validated/parsed data
- * - `{ success: false, error: string }` with error box HTML
- *
- * @param options - The options object to validate
- * @param config - Validation configuration (component name and schema)
- * @returns ValidationResult with either data or error HTML
- *
- * @example
- * ```typescript
- * const result = validateOptions({ variant: 'invalid' }, {
- *   componentName: 'Button',
- *   schema: ButtonOptionsSchema,
- * });
- *
- * if (!result.success) {
- *   return result.error; // Error box HTML
- * }
- *
- * // result.data is typed and validated
- * ```
- */
-function validateOptions(options, config) {
-    const result = config.schema.safeParse(options);
-    if (result.success) {
-        return { success: true, data: result.data };
-    }
-    // Extract first invalid field path (safe to expose)
-    const invalidParam = getFirstInvalidPath(result.error);
-    return {
-        success: false,
-        error: (0, error_box_1.validationErrorBox)({
-            componentName: config.componentName,
-            invalidParam,
-        }),
-    };
-}
-/**
- * Higher-order function to wrap a component function with validation
- *
- * Creates a new function that validates the options before calling the
- * original component. If validation fails, returns the error box HTML
- * instead of calling the component.
- *
- * @param componentFn - The original component function
- * @param config - Validation configuration
- * @returns Wrapped function that validates before calling
- *
- * @example
- * ```typescript
- * const buttonImpl = (text: string, opts: ButtonOptions) => `<button>...</button>`;
- *
- * const button = withValidation(buttonImpl, {
- *   componentName: 'Button',
- *   schema: ButtonOptionsSchema,
- * });
- *
- * // button() now validates options before rendering
- * ```
- */
-function withValidation(componentFn, config) {
-    return (input, options) => {
-        const result = validateOptions(options, config);
-        if (!result.success) {
-            return result.error;
-        }
-        return componentFn(input, result.data);
-    };
-}
-//# sourceMappingURL=wrapper.js.map

package/src/validation/wrapper.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"wrapper.js","sourceRoot":"","sources":["../../../src/validation/wrapper.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;AAgEH,0CAiBC;AAyBD,wCAaC;AApHD,2CAAiD;AAqBjD,+CAA+C;AAC/C,uBAAuB;AACvB,+CAA+C;AAE/C;;GAEG;AACH,SAAS,mBAAmB,CAAC,KAAiD;IAC5E,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,eAAe,CAAI,OAAgB,EAAE,MAAwB;IAC3E,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAS,EAAE,CAAC;IACnD,CAAC;IAED,oDAAoD;IACpD,MAAM,YAAY,GAAG,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEvD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,IAAA,8BAAkB,EAAC;YACxB,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,YAAY;SACb,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,cAAc,CAC5B,WAAyD,EACzD,MAAwB;IAExB,OAAO,CAAC,KAAa,EAAE,OAAgB,EAAE,EAAE;QACzC,MAAM,MAAM,GAAG,eAAe,CAAW,OAAO,EAAE,MAAM,CAAC,CAAC;QAE1D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,MAAM,CAAC,KAAK,CAAC;QACtB,CAAC;QAED,OAAO,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * @file wrapper.ts\n * @description Validation wrapper utilities for component input validation.\n *\n * Provides functions to validate component options against Zod schemas\n * and return either the validated data or an error box HTML string.\n *\n * @example\n * ```typescript\n * import { validateOptions } from '@frontmcp/ui';\n * import { z } from 'zod';\n *\n * const schema = z.object({ variant: z.enum(['primary', 'secondary']) });\n *\n * const result = validateOptions(options, {\n *   componentName: 'Button',\n *   schema,\n * });\n *\n * if (!result.success) return result.error; // Returns error box HTML\n *\n * // Use result.data safely\n * ```\n *\n * @module @frontmcp/ui/validation/wrapper\n */\n\nimport { type ZodSchema } from 'zod';\nimport { validationErrorBox } from './error-box';\n\n// ============================================\n// Types\n// ============================================\n\n/**\n * Configuration for validation\n */\nexport interface ValidationConfig {\n  /** Name of the component being validated */\n  componentName: string;\n  /** Zod schema to validate against */\n  schema: ZodSchema;\n}\n\n/**\n * Result of validation - either success with data or failure with error HTML\n */\nexport type ValidationResult<T> = { success: true; data: T } | { success: false; error: string };\n\n// ============================================\n// Validation Functions\n// ============================================\n\n/**\n * Extract the path of the first invalid field from a Zod error\n */\nfunction getFirstInvalidPath(error: { issues: Array<{ path: PropertyKey[] }> }): string {\n  const firstError = error.issues[0];\n  if (!firstError || firstError.path.length === 0) {\n    return 'options';\n  }\n  return firstError.path.map(String).join('.');\n}\n\n/**\n * Validates input against a Zod schema\n *\n * Returns either:\n * - `{ success: true, data: T }` with validated/parsed data\n * - `{ success: false, error: string }` with error box HTML\n *\n * @param options - The options object to validate\n * @param config - Validation configuration (component name and schema)\n * @returns ValidationResult with either data or error HTML\n *\n * @example\n * ```typescript\n * const result = validateOptions({ variant: 'invalid' }, {\n *   componentName: 'Button',\n *   schema: ButtonOptionsSchema,\n * });\n *\n * if (!result.success) {\n *   return result.error; // Error box HTML\n * }\n *\n * // result.data is typed and validated\n * ```\n */\nexport function validateOptions<T>(options: unknown, config: ValidationConfig): ValidationResult<T> {\n  const result = config.schema.safeParse(options);\n\n  if (result.success) {\n    return { success: true, data: result.data as T };\n  }\n\n  // Extract first invalid field path (safe to expose)\n  const invalidParam = getFirstInvalidPath(result.error);\n\n  return {\n    success: false,\n    error: validationErrorBox({\n      componentName: config.componentName,\n      invalidParam,\n    }),\n  };\n}\n\n/**\n * Higher-order function to wrap a component function with validation\n *\n * Creates a new function that validates the options before calling the\n * original component. If validation fails, returns the error box HTML\n * instead of calling the component.\n *\n * @param componentFn - The original component function\n * @param config - Validation configuration\n * @returns Wrapped function that validates before calling\n *\n * @example\n * ```typescript\n * const buttonImpl = (text: string, opts: ButtonOptions) => `<button>...</button>`;\n *\n * const button = withValidation(buttonImpl, {\n *   componentName: 'Button',\n *   schema: ButtonOptionsSchema,\n * });\n *\n * // button() now validates options before rendering\n * ```\n */\nexport function withValidation<TInput, TOptions>(\n  componentFn: (input: TInput, options: TOptions) => string,\n  config: ValidationConfig,\n): (input: TInput, options: unknown) => string {\n  return (input: TInput, options: unknown) => {\n    const result = validateOptions<TOptions>(options, config);\n\n    if (!result.success) {\n      return result.error;\n    }\n\n    return componentFn(input, result.data);\n  };\n}\n"]}