@frontmcp/ui 0.5.0 → 0.6.0

package/src/types/ui-config.d.ts

@@ -1,357 +0,0 @@
-/**
- * Standalone UI Configuration Types
- *
- * SDK-independent types for configuring UI templates.
- * These types can be used by external consumers (like AgentLink)
- * without requiring @frontmcp/sdk as a dependency.
- *
- * @packageDocumentation
- */
-/**
- * Content Security Policy for UI templates rendered in sandboxed iframes.
- * Based on OpenAI Apps SDK and MCP Apps (SEP-1865) specifications.
- */
-export interface UIContentSecurityPolicy {
-    /**
-     * Origins allowed for fetch/XHR/WebSocket connections.
-     * Maps to CSP `connect-src` directive.
-     * @example ['https://api.example.com', 'https://*.myservice.com']
-     */
-    connectDomains?: string[];
-    /**
-     * Origins allowed for images, scripts, fonts, and styles.
-     * Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives.
-     * @example ['https://cdn.example.com']
-     */
-    resourceDomains?: string[];
-}
-/**
- * Helper functions available in template context.
- */
-export interface TemplateHelpers {
-    /**
-     * Escape HTML special characters to prevent XSS.
-     */
-    escapeHtml: (str: string) => string;
-    /**
-     * Format a date for display.
-     * @param date - Date object or ISO string
-     * @param format - Optional format (default: localized date)
-     */
-    formatDate: (date: Date | string, format?: string) => string;
-    /**
-     * Format a number as currency.
-     * @param amount - The numeric amount
-     * @param currency - ISO 4217 currency code (default: 'USD')
-     */
-    formatCurrency: (amount: number, currency?: string) => string;
-    /**
-     * Generate a unique ID for DOM elements.
-     * @param prefix - Optional prefix for the ID
-     */
-    uniqueId: (prefix?: string) => string;
-    /**
-     * Safely embed JSON data in HTML (escapes script-breaking characters).
-     */
-    jsonEmbed: (data: unknown) => string;
-}
-/**
- * Context passed to template builder functions.
- * Contains all data needed to render a tool's UI template.
- */
-export interface TemplateContext<In = unknown, Out = unknown> {
-    /**
-     * The input arguments passed to the tool.
-     */
-    input: In;
-    /**
-     * The raw output returned by the tool's execute method.
-     */
-    output: Out;
-    /**
-     * The structured content parsed from the output (if outputSchema was provided).
-     * This is the JSON-serializable form suitable for widget consumption.
-     */
-    structuredContent?: unknown;
-    /**
-     * Helper functions for template rendering.
-     */
-    helpers: TemplateHelpers;
-}
-/**
- * Template builder function type.
- * Receives context with input/output and returns HTML string.
- */
-export type TemplateBuilderFn<In = unknown, Out = unknown> = (ctx: TemplateContext<In, Out>) => string;
-/**
- * Widget serving mode determines how the widget HTML is delivered to the client.
- */
-export type WidgetServingMode = 'inline' | 'static' | 'hybrid' | 'direct-url' | 'custom-url';
-/**
- * @deprecated Use 'static' instead of 'mcp-resource'. Will be removed in v2.0.
- * Alias maintained for backwards compatibility.
- */
-export type WidgetServingModeLegacy = 'mcp-resource';
-/**
- * Widget display mode preference.
- */
-export type WidgetDisplayMode = 'inline' | 'fullscreen' | 'pip';
-/**
- * UI template configuration for tools.
- * Enables rendering interactive widgets for tool responses in supported hosts
- * (OpenAI Apps SDK, Claude/MCP-UI, etc.).
- *
- * This is a standalone type that doesn't depend on @frontmcp/sdk.
- * Use this type in external systems (like AgentLink) that consume @frontmcp/ui.
- *
- * @example
- * ```typescript
- * const uiConfig: UITemplateConfig = {
- *   template: (ctx) => `
- *     <div class="p-4">
- *       <h2>${ctx.helpers.escapeHtml(ctx.input.location)}</h2>
- *       <p>${ctx.output.temperature}°F</p>
- *     </div>
- *   `,
- *   csp: { connectDomains: ['https://api.weather.com'] },
- *   widgetAccessible: true,
- *   widgetDescription: 'Displays current weather conditions',
- * };
- * ```
- */
-export interface UITemplateConfig<In = unknown, Out = unknown> {
-    /**
-     * Template for rendering tool UI.
-     *
-     * Supports multiple formats (auto-detected by renderer):
-     * - Template builder function: `(ctx) => string` - receives input/output/helpers, returns HTML
-     * - Static HTML/MDX string: `"<div>...</div>"` or `"# Title\n<Card />"`
-     * - React component: `MyWidget` - receives props with input/output/helpers
-     */
-    template: TemplateBuilderFn<In, Out> | string | ((props: any) => any);
-    /**
-     * Content Security Policy for the sandboxed widget.
-     * Controls which external resources the widget can access.
-     */
-    csp?: UIContentSecurityPolicy;
-    /**
-     * Whether the widget can invoke tools via the MCP bridge.
-     * When true, the widget gains access to `window.mcpBridge.callTool()`.
-     * Maps to OpenAI's `openai/widgetAccessible` annotation.
-     *
-     * Default: false
-     */
-    widgetAccessible?: boolean;
-    /**
-     * Preferred display mode for the widget.
-     * - 'inline': Rendered inline in the conversation (default)
-     * - 'fullscreen': Request fullscreen display
-     * - 'pip': Picture-in-picture mode
-     *
-     * Note: Host may not support all modes; this is a preference hint.
-     */
-    displayMode?: WidgetDisplayMode;
-    /**
-     * Human-readable description shown to users about what the widget does.
-     * Maps to OpenAI's `openai/widgetDescription` annotation.
-     */
-    widgetDescription?: string;
-    /**
-     * Status messages shown during tool invocation (OpenAI ChatGPT specific).
-     * Maps to OpenAI's `openai/toolInvocation/invoking` and `openai/toolInvocation/invoked`.
-     *
-     * @example
-     * ```typescript
-     * invocationStatus: {
-     *   invoking: 'Fetching weather data...',
-     *   invoked: 'Weather data loaded'
-     * }
-     * ```
-     */
-    invocationStatus?: {
-        /** Status text shown while tool is executing */
-        invoking?: string;
-        /** Status text shown after tool execution completes */
-        invoked?: string;
-    };
-    /**
-     * How the widget HTML should be served to the client.
-     *
-     * - `'inline'`: HTML embedded directly in tool response `_meta['ui/html']`
-     *   Best for small widgets, works on all platforms including network-blocked ones.
-     *
-     * - `'static'`: Widget pre-compiled at server startup, registered as MCP resource with `ui://` URI.
-     *   Client fetches via `resources/read`. Good for OpenAI's template system.
-     *   Widget is resolved during `tools/list`, not dependent on tool call.
-     *
-     * - `'hybrid'`: Shell (React runtime + bridge) pre-compiled at startup.
-     *   Component code transpiled per-request and delivered in `_meta['ui/component']`.
-     *
-     * - `'direct-url'`: Served from MCP server's HTTP endpoint.
-     *   Avoids third-party cookie issues since widget loads from same domain.
-     *
-     * - `'custom-url'`: Served from a custom URL (CDN, external hosting).
-     *   Requires `customWidgetUrl` to be set.
-     *
-     * Default: `'inline'`
-     */
-    servingMode?: WidgetServingMode;
-    /**
-     * Custom URL for widget serving when `servingMode: 'custom-url'`.
-     * The URL can include `{token}` placeholder which will be replaced with
-     * the widget access token.
-     *
-     * @example
-     * ```typescript
-     * customWidgetUrl: 'https://cdn.example.com/widgets/weather.html?token={token}'
-     * ```
-     */
-    customWidgetUrl?: string;
-    /**
-     * Path for direct URL serving when `servingMode: 'direct-url'`.
-     * This path is appended to the MCP server's base URL.
-     *
-     * @example
-     * ```typescript
-     * directPath: '/widgets/weather'
-     * // Results in: https://mcp-server.example.com/widgets/weather?token=...
-     * ```
-     */
-    directPath?: string;
-    /**
-     * Custom React components available in MDX templates.
-     * These components can be used directly in MDX content without importing.
-     *
-     * @example
-     * ```typescript
-     * ui: {
-     *   template: `# Weather\n<Alert type="info">Data loaded</Alert>`,
-     *   mdxComponents: {
-     *     Alert: ({ type, children }) => <div className={type}>{children}</div>,
-     *     Card: MyCardComponent,
-     *   }
-     * }
-     * ```
-     */
-    mdxComponents?: Record<string, any>;
-    /**
-     * Whether to show a border around the UI widget.
-     * MCP Apps spec: `_meta.ui.prefersBorder`
-     *
-     * When true, hosts should render a visible border around the sandbox iframe.
-     * Useful for visual clarity when the widget content doesn't have its own borders.
-     *
-     * Default: undefined (host decides)
-     */
-    prefersBorder?: boolean;
-    /**
-     * Dedicated sandbox domain for the widget.
-     * MCP Apps spec: `_meta.ui.domain`
-     *
-     * When specified, the host should load the widget in an iframe with this
-     * domain as the origin, providing additional isolation.
-     *
-     * @example 'sandbox.example.com'
-     */
-    sandboxDomain?: string;
-    /**
-     * Enable client-side React hydration after server-side rendering (SSR).
-     *
-     * **Default: `false`**
-     *
-     * When `false` (default):
-     * - SSR output is static HTML
-     * - No React runtime is loaded on the client
-     * - All interactivity is handled by the FrontMCP Bridge IIFE
-     * - This prevents React Hydration Error #418 in MCP clients
-     *
-     * When `true`:
-     * - React/ReactDOM CDN scripts are included
-     * - Client attempts to hydrate React components
-     * - May cause hydration mismatch errors in some MCP clients (Claude, ChatGPT)
-     *
-     * **Why disabled by default?**
-     * MCP clients like Claude and ChatGPT render HTML in sandboxed iframes.
-     * React hydration expects the client-rendered HTML to exactly match the
-     * server-rendered HTML. Due to timing differences, random data, and
-     * different execution contexts, mismatches frequently occur causing
-     * React Error #418 ("Hydration failed...").
-     *
-     * The FrontMCP Bridge IIFE already provides all necessary interactivity
-     * (tool calls via `data-tool-call`, state updates, loading states) without
-     * requiring React hydration.
-     *
-     * **Only enable if:**
-     * - You need React state management on the client
-     * - You're sure your template produces deterministic HTML
-     * - You've tested hydration works in your target MCP client
-     *
-     * @example
-     * ```typescript
-     * // Disable hydration (default behavior - recommended)
-     * ui: {
-     *   template: MyReactComponent,
-     *   hydrate: false
-     * }
-     *
-     * // Enable hydration (use with caution)
-     * ui: {
-     *   template: MyStatefulComponent,
-     *   hydrate: true
-     * }
-     * ```
-     */
-    hydrate?: boolean;
-    /**
-     * UI renderer type.
-     *
-     * - `'html'`: HTML with optional Handlebars
-     * - `'react'`: React component (SSR)
-     * - `'mdx'`: MDX template
-     * - `'markdown'`: Pure Markdown
-     * - `'auto'`: Auto-detect from template (default)
-     *
-     * @default 'auto'
-     */
-    uiType?: 'html' | 'react' | 'mdx' | 'markdown' | 'auto';
-    /**
-     * Bundling mode.
-     *
-     * - `'static'`: Pre-compile widget shell, inject data at runtime (default)
-     * - `'dynamic'`: Generate fresh HTML per tool invocation
-     *
-     * @default 'static'
-     */
-    bundlingMode?: 'static' | 'dynamic';
-    /**
-     * Resource loading mode.
-     *
-     * - `'cdn'`: Load React/MDX/Handlebars from CDN URLs (lightweight)
-     * - `'inline'`: Embed all scripts in HTML (self-contained)
-     *
-     * Use 'cdn' for most platforms (OpenAI, ChatGPT, Cursor).
-     * Use 'inline' for network-blocked environments (Claude Artifacts).
-     *
-     * @default 'cdn'
-     */
-    resourceMode?: 'cdn' | 'inline';
-    /**
-     * Runtime options for specific renderers.
-     */
-    runtimeOptions?: {
-        /** Enable React hydration after SSR */
-        hydrate?: boolean;
-        /** Markdown rendering options */
-        markdown?: {
-            /** Enable GitHub-flavored markdown */
-            gfm?: boolean;
-            /** Syntax highlighting theme */
-            highlightTheme?: string;
-        };
-    };
-}
-/**
- * Type alias for backwards compatibility.
- * Prefer using UITemplateConfig directly.
- */
-export type UITemplate<In = unknown, Out = unknown> = UITemplateConfig<In, Out>;

package/src/types/ui-config.js

@@ -1,12 +0,0 @@
-"use strict";
-/**
- * Standalone UI Configuration Types
- *
- * SDK-independent types for configuring UI templates.
- * These types can be used by external consumers (like AgentLink)
- * without requiring @frontmcp/sdk as a dependency.
- *
- * @packageDocumentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=ui-config.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"ui-config.js","sourceRoot":"","sources":["../../../src/types/ui-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * Standalone UI Configuration Types\n *\n * SDK-independent types for configuring UI templates.\n * These types can be used by external consumers (like AgentLink)\n * without requiring @frontmcp/sdk as a dependency.\n *\n * @packageDocumentation\n */\n\n// ============================================\n// Content Security Policy\n// ============================================\n\n/**\n * Content Security Policy for UI templates rendered in sandboxed iframes.\n * Based on OpenAI Apps SDK and MCP Apps (SEP-1865) specifications.\n */\nexport interface UIContentSecurityPolicy {\n  /**\n   * Origins allowed for fetch/XHR/WebSocket connections.\n   * Maps to CSP `connect-src` directive.\n   * @example ['https://api.example.com', 'https://*.myservice.com']\n   */\n  connectDomains?: string[];\n\n  /**\n   * Origins allowed for images, scripts, fonts, and styles.\n   * Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives.\n   * @example ['https://cdn.example.com']\n   */\n  resourceDomains?: string[];\n}\n\n// ============================================\n// Template Context & Helpers\n// ============================================\n\n/**\n * Helper functions available in template context.\n */\nexport interface TemplateHelpers {\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 (default: localized date)\n   */\n  formatDate: (date: Date | string, format?: string) => string;\n\n  /**\n   * Format a number as currency.\n   * @param amount - The 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 for the ID\n   */\n  uniqueId: (prefix?: string) => string;\n\n  /**\n   * Safely embed JSON data in HTML (escapes script-breaking characters).\n   */\n  jsonEmbed: (data: unknown) => string;\n}\n\n/**\n * Context passed to template builder functions.\n * Contains all data needed to render a tool's UI template.\n */\nexport interface TemplateContext<In = unknown, Out = unknown> {\n  /**\n   * The input arguments passed to the tool.\n   */\n  input: In;\n\n  /**\n   * The raw output returned by the tool's execute method.\n   */\n  output: Out;\n\n  /**\n   * The structured content parsed from the output (if outputSchema was provided).\n   * This is the JSON-serializable form suitable for widget consumption.\n   */\n  structuredContent?: unknown;\n\n  /**\n   * Helper functions for template rendering.\n   */\n  helpers: TemplateHelpers;\n}\n\n/**\n * Template builder function type.\n * Receives context with input/output and returns HTML string.\n */\nexport type TemplateBuilderFn<In = unknown, Out = unknown> = (ctx: TemplateContext<In, Out>) => string;\n\n// ============================================\n// Widget Serving Mode\n// ============================================\n\n/**\n * Widget serving mode determines how the widget HTML is delivered to the client.\n */\nexport type WidgetServingMode =\n  | 'inline' // HTML embedded directly in tool response _meta\n  | 'static' // Pre-compiled at startup, resolved via tools/list (ui:// resource URI)\n  | 'hybrid' // Shell (React + renderer) cached, component + data in response\n  | 'direct-url' // HTTP endpoint on MCP server\n  | 'custom-url'; // Custom URL (CDN or external hosting)\n\n/**\n * @deprecated Use 'static' instead of 'mcp-resource'. Will be removed in v2.0.\n * Alias maintained for backwards compatibility.\n */\nexport type WidgetServingModeLegacy = 'mcp-resource';\n\n// ============================================\n// Display Mode\n// ============================================\n\n/**\n * Widget display mode preference.\n */\nexport type WidgetDisplayMode = 'inline' | 'fullscreen' | 'pip';\n\n// ============================================\n// UI Template Configuration\n// ============================================\n/**\n * UI template configuration for tools.\n * Enables rendering interactive widgets for tool responses in supported hosts\n * (OpenAI Apps SDK, Claude/MCP-UI, etc.).\n *\n * This is a standalone type that doesn't depend on @frontmcp/sdk.\n * Use this type in external systems (like AgentLink) that consume @frontmcp/ui.\n *\n * @example\n * ```typescript\n * const uiConfig: UITemplateConfig = {\n *   template: (ctx) => `\n *     <div class=\"p-4\">\n *       <h2>${ctx.helpers.escapeHtml(ctx.input.location)}</h2>\n *       <p>${ctx.output.temperature}°F</p>\n *     </div>\n *   `,\n *   csp: { connectDomains: ['https://api.weather.com'] },\n *   widgetAccessible: true,\n *   widgetDescription: 'Displays current weather conditions',\n * };\n * ```\n */\nexport interface UITemplateConfig<In = unknown, Out = unknown> {\n  /**\n   * Template for rendering tool UI.\n   *\n   * Supports multiple formats (auto-detected by renderer):\n   * - Template builder function: `(ctx) => string` - receives input/output/helpers, returns HTML\n   * - Static HTML/MDX string: `\"<div>...</div>\"` or `\"# Title\\n<Card />\"`\n   * - React component: `MyWidget` - receives props with input/output/helpers\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  template: TemplateBuilderFn<In, Out> | string | ((props: any) => any);\n\n  /**\n   * Content Security Policy for the sandboxed widget.\n   * Controls which external resources the widget can access.\n   */\n  csp?: UIContentSecurityPolicy;\n\n  /**\n   * Whether the widget can invoke tools via the MCP bridge.\n   * When true, the widget gains access to `window.mcpBridge.callTool()`.\n   * Maps to OpenAI's `openai/widgetAccessible` annotation.\n   *\n   * Default: false\n   */\n  widgetAccessible?: boolean;\n\n  /**\n   * Preferred display mode for the widget.\n   * - 'inline': Rendered inline in the conversation (default)\n   * - 'fullscreen': Request fullscreen display\n   * - 'pip': Picture-in-picture mode\n   *\n   * Note: Host may not support all modes; this is a preference hint.\n   */\n  displayMode?: WidgetDisplayMode;\n\n  /**\n   * Human-readable description shown to users about what the widget does.\n   * Maps to OpenAI's `openai/widgetDescription` annotation.\n   */\n  widgetDescription?: string;\n\n  /**\n   * Status messages shown during tool invocation (OpenAI ChatGPT specific).\n   * Maps to OpenAI's `openai/toolInvocation/invoking` and `openai/toolInvocation/invoked`.\n   *\n   * @example\n   * ```typescript\n   * invocationStatus: {\n   *   invoking: 'Fetching weather data...',\n   *   invoked: 'Weather data loaded'\n   * }\n   * ```\n   */\n  invocationStatus?: {\n    /** Status text shown while tool is executing */\n    invoking?: string;\n    /** Status text shown after tool execution completes */\n    invoked?: string;\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   *   Best for small widgets, works on all platforms including network-blocked ones.\n   *\n   * - `'static'`: Widget pre-compiled at server startup, registered as MCP resource with `ui://` URI.\n   *   Client fetches via `resources/read`. Good for OpenAI's template system.\n   *   Widget is resolved during `tools/list`, not dependent on tool call.\n   *\n   * - `'hybrid'`: Shell (React runtime + bridge) pre-compiled at startup.\n   *   Component code transpiled per-request and delivered in `_meta['ui/component']`.\n   *\n   * - `'direct-url'`: Served from MCP server's HTTP endpoint.\n   *   Avoids third-party cookie issues since widget loads from same domain.\n   *\n   * - `'custom-url'`: Served from a custom URL (CDN, external hosting).\n   *   Requires `customWidgetUrl` to be set.\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 with\n   * the widget access token.\n   *\n   * @example\n   * ```typescript\n   * customWidgetUrl: 'https://cdn.example.com/widgets/weather.html?token={token}'\n   * ```\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\n   * ```typescript\n   * directPath: '/widgets/weather'\n   * // Results in: https://mcp-server.example.com/widgets/weather?token=...\n   * ```\n   */\n  directPath?: string;\n\n  /**\n   * Custom React components available in MDX templates.\n   * These components can be used directly in MDX content without importing.\n   *\n   * @example\n   * ```typescript\n   * ui: {\n   *   template: `# Weather\\n<Alert type=\"info\">Data loaded</Alert>`,\n   *   mdxComponents: {\n   *     Alert: ({ type, children }) => <div className={type}>{children}</div>,\n   *     Card: MyCardComponent,\n   *   }\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  mdxComponents?: Record<string, any>;\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   * When true, hosts should render a visible border around the sandbox iframe.\n   * Useful for visual clarity when the widget content doesn't have its own borders.\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   * When specified, the host should load the widget in an iframe with this\n   * domain as the origin, providing additional isolation.\n   *\n   * @example 'sandbox.example.com'\n   */\n  sandboxDomain?: string;\n\n  // ============================================\n  // Rendering 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 is loaded on the client\n   * - All interactivity is handled by the FrontMCP Bridge IIFE\n   * - This prevents React Hydration Error #418 in MCP clients\n   *\n   * When `true`:\n   * - React/ReactDOM CDN scripts are included\n   * - Client attempts to hydrate React components\n   * - May cause hydration mismatch errors in some MCP clients (Claude, ChatGPT)\n   *\n   * **Why disabled by default?**\n   * MCP clients like Claude and ChatGPT render HTML in sandboxed iframes.\n   * React hydration expects the client-rendered HTML to exactly match the\n   * server-rendered HTML. Due to timing differences, random data, and\n   * different execution contexts, mismatches frequently occur causing\n   * React Error #418 (\"Hydration failed...\").\n   *\n   * The FrontMCP Bridge IIFE already provides all necessary interactivity\n   * (tool calls via `data-tool-call`, state updates, loading states) without\n   * requiring React hydration.\n   *\n   * **Only enable if:**\n   * - You need React state management on the client\n   * - You're sure your template produces deterministic HTML\n   * - You've tested hydration works in your target MCP client\n   *\n   * @example\n   * ```typescript\n   * // Disable hydration (default behavior - recommended)\n   * ui: {\n   *   template: MyReactComponent,\n   *   hydrate: false\n   * }\n   *\n   * // Enable hydration (use with caution)\n   * ui: {\n   *   template: MyStatefulComponent,\n   *   hydrate: true\n   * }\n   * ```\n   */\n  hydrate?: boolean;\n\n  // ============================================\n  // Runtime/Build Configuration (from ui-runtime.ts)\n  // ============================================\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?: 'html' | 'react' | 'mdx' | 'markdown' | 'auto';\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?: 'static' | 'dynamic';\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?: 'cdn' | 'inline';\n\n  /**\n   * Runtime options for specific renderers.\n   */\n  runtimeOptions?: {\n    /** Enable React hydration after SSR */\n    hydrate?: boolean;\n    /** Markdown rendering options */\n    markdown?: {\n      /** Enable GitHub-flavored markdown */\n      gfm?: boolean;\n      /** Syntax highlighting theme */\n      highlightTheme?: string;\n    };\n  };\n}\n\n/**\n * Type alias for backwards compatibility.\n * Prefer using UITemplateConfig directly.\n */\nexport type UITemplate<In = unknown, Out = unknown> = UITemplateConfig<In, Out>;\n"]}