@frontmcp/ui 0.5.0 → 0.6.0

package/renderers/cache.d.ts

@@ -0,0 +1,145 @@
+/**
+ * LRU Cache for Renderer Transpilation Results
+ *
+ * Provides fast, memory-bounded caching for transpiled templates.
+ * Uses content-addressable keys (hash of source) for deduplication.
+ */
+import type { TranspileResult } from './types';
+/**
+ * Options for the transpile cache.
+ */
+export interface TranspileCacheOptions {
+    /** Maximum number of entries (default: 500) */
+    maxSize?: number;
+    /** TTL in milliseconds, 0 = infinite (default: 0 for transpile cache) */
+    ttl?: number;
+}
+/**
+ * LRU Cache for transpiled template results.
+ *
+ * Features:
+ * - Content-addressable keys via hash
+ * - LRU eviction when max size reached
+ * - Optional TTL for time-based expiration
+ * - Access statistics
+ *
+ * @example
+ * ```typescript
+ * const cache = new TranspileCache({ maxSize: 500 });
+ *
+ * // Store a transpiled result
+ * const hash = cache.set(sourceCode, transpileResult);
+ *
+ * // Retrieve it later
+ * const result = cache.get(sourceCode);
+ * if (result) {
+ *   console.log('Cache hit!', result.code);
+ * }
+ * ```
+ */
+export declare class TranspileCache {
+    private cache;
+    private readonly maxSize;
+    private readonly ttl;
+    /** Cache statistics */
+    private stats;
+    constructor(options?: TranspileCacheOptions);
+    /**
+     * Get a cached transpile result by source content.
+     *
+     * @param source - Source code to look up
+     * @returns Cached result or undefined if not found/expired
+     */
+    get(source: string): TranspileResult | undefined;
+    /**
+     * Get a cached transpile result by hash key.
+     *
+     * @param key - Hash key
+     * @returns Cached result or undefined if not found/expired
+     */
+    getByKey(key: string): TranspileResult | undefined;
+    /**
+     * Store a transpile result.
+     *
+     * @param source - Source code (used to generate key)
+     * @param value - Transpile result to cache
+     * @returns The hash key used for storage
+     */
+    set(source: string, value: TranspileResult): string;
+    /**
+     * Store a transpile result by hash key.
+     *
+     * @param key - Hash key
+     * @param value - Transpile result to cache
+     */
+    setByKey(key: string, value: TranspileResult): void;
+    /**
+     * Check if a source is cached.
+     *
+     * @param source - Source code to check
+     * @returns True if cached and not expired
+     */
+    has(source: string): boolean;
+    /**
+     * Check if a key is cached.
+     *
+     * @param key - Hash key to check
+     * @returns True if cached and not expired
+     */
+    hasByKey(key: string): boolean;
+    /**
+     * Delete a cached entry by source.
+     *
+     * @param source - Source code to delete
+     * @returns True if entry was deleted
+     */
+    delete(source: string): boolean;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Get current cache size.
+     */
+    get size(): number;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): {
+        hits: number;
+        misses: number;
+        evictions: number;
+        size: number;
+        hitRate: number;
+    };
+}
+/**
+ * Global transpile cache instance.
+ * Shared across all renderers for deduplication.
+ */
+export declare const transpileCache: TranspileCache;
+/**
+ * Render cache for full HTML output.
+ * Uses shorter TTL since outputs depend on input/output data.
+ */
+export declare const renderCache: TranspileCache;
+/**
+ * Simple LRU cache for storing any type of values.
+ * Used for caching compiled components (React/MDX).
+ */
+export declare class ComponentCache<T = unknown> {
+    private cache;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Global component cache for storing compiled React/MDX components.
+ */
+export declare const componentCache: ComponentCache<unknown>;
+//# sourceMappingURL=cache.d.ts.map

package/renderers/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/renderers/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAc/C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAkD;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,uBAAuB;IACvB,OAAO,CAAC,KAAK,CAIX;gBAEU,OAAO,GAAE,qBAA0B;IAK/C;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAKhD;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAwBlD;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM;IAMnD;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAkBnD;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAK5B;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAa9B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAK/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAQ/F;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,gBAAuC,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,WAAW,gBAGtB,CAAC;AAEH;;;GAGG;AACH,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO;IACrC,OAAO,CAAC,KAAK,CAAsD;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,SAAM;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAU/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAYhC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,yBAAuB,CAAC"}

package/renderers/html.renderer.d.ts

@@ -0,0 +1,123 @@
+/**
+ * HTML Renderer
+ *
+ * Handles plain HTML templates:
+ * - Static HTML strings
+ * - Template builder functions: (ctx) => string
+ * - Handlebars-enhanced templates: HTML with {{variable}} syntax
+ *
+ * This is the default fallback renderer with the lowest priority.
+ */
+import type { TemplateContext } from '../runtime/types';
+import type { PlatformCapabilities } from '../theme';
+import type { UIRenderer, TranspileResult, TranspileOptions, RenderOptions, RuntimeScripts } from './types';
+/**
+ * Template builder function type.
+ */
+type TemplateBuilderFn<In, Out> = (ctx: TemplateContext<In, Out>) => string;
+/**
+ * Types this renderer can handle.
+ */
+type HtmlTemplate<In = unknown, Out = unknown> = string | TemplateBuilderFn<In, Out>;
+/**
+ * Check if a template contains Handlebars syntax.
+ * Non-async version for canHandle check.
+ */
+declare function containsHandlebars(template: string): boolean;
+/**
+ * HTML Renderer Implementation.
+ *
+ * Handles:
+ * - Static HTML strings (passed through directly)
+ * - Template builder functions that return HTML strings
+ * - Handlebars-enhanced templates (detected by {{...}} syntax)
+ *
+ * When Handlebars syntax is detected, the template is processed
+ * with the HandlebarsRenderer for variable interpolation, conditionals,
+ * and loops.
+ *
+ * @example Static HTML
+ * ```typescript
+ * const template = '<div class="card">Hello World</div>';
+ * await htmlRenderer.render(template, context);
+ * ```
+ *
+ * @example Template function
+ * ```typescript
+ * const template = (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.name)}</div>`;
+ * await htmlRenderer.render(template, context);
+ * ```
+ *
+ * @example Handlebars template
+ * ```typescript
+ * const template = `
+ *   <div class="card">
+ *     <h2>{{escapeHtml output.title}}</h2>
+ *     {{#if output.items}}
+ *       <ul>
+ *         {{#each output.items}}
+ *           <li>{{this.name}}</li>
+ *         {{/each}}
+ *       </ul>
+ *     {{/if}}
+ *   </div>
+ * `;
+ * await htmlRenderer.render(template, context);
+ * ```
+ */
+export declare class HtmlRenderer implements UIRenderer<HtmlTemplate> {
+    readonly type: "html";
+    readonly priority = 0;
+    /**
+     * Check if this renderer can handle the given template.
+     *
+     * Accepts:
+     * - Any string (assumed to be HTML, with or without Handlebars)
+     * - Functions that are template builders (not React components)
+     */
+    canHandle(template: unknown): template is HtmlTemplate;
+    /**
+     * Check if a template uses Handlebars syntax.
+     *
+     * @param template - Template string to check
+     * @returns true if template contains {{...}} syntax
+     */
+    usesHandlebars(template: string): boolean;
+    /**
+     * Transpile the template.
+     *
+     * For HTML templates, no transpilation is needed.
+     * This method returns a dummy result for consistency.
+     */
+    transpile(template: HtmlTemplate, _options?: TranspileOptions): Promise<TranspileResult>;
+    /**
+     * Render the template to HTML string.
+     *
+     * For static strings without Handlebars, returns the string directly.
+     * For strings with Handlebars syntax, processes with HandlebarsRenderer.
+     * For functions, calls the function with the context.
+     */
+    render<In, Out>(template: HtmlTemplate<In, Out>, context: TemplateContext<In, Out>, _options?: RenderOptions): Promise<string>;
+    /**
+     * Render Handlebars template with context.
+     */
+    private renderHandlebars;
+    /**
+     * Get runtime scripts for client-side functionality.
+     *
+     * HTML templates don't need additional runtime scripts.
+     */
+    getRuntimeScripts(_platform: PlatformCapabilities): RuntimeScripts;
+}
+/**
+ * Singleton instance of the HTML renderer.
+ */
+export declare const htmlRenderer: HtmlRenderer;
+/**
+ * Check if a template string contains Handlebars syntax.
+ *
+ * @param template - Template string
+ * @returns true if contains {{...}}
+ */
+export { containsHandlebars };
+//# sourceMappingURL=html.renderer.d.ts.map

package/renderers/html.renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.renderer.d.ts","sourceRoot":"","sources":["../../src/renderers/html.renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI5G;;GAEG;AACH,KAAK,iBAAiB,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC;AAE5E;;GAEG;AACH,KAAK,YAAY,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,MAAM,GAAG,iBAAiB,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AA0CrF;;;GAGG;AACH,iBAAS,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,YAAa,YAAW,UAAU,CAAC,YAAY,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,QAAQ,CAAC,QAAQ,KAAK;IAEtB;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,YAAY;IActD;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIzC;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAW9F;;;;;;OAMG;IACG,MAAM,CAAC,EAAE,EAAE,GAAG,EAClB,QAAQ,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,CAAC,EAC/B,OAAO,EAAE,eAAe,CAAC,EAAE,EAAE,GAAG,CAAC,EACjC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,MAAM,CAAC;IAwBlB;;OAEG;YACW,gBAAgB;IAmB9B;;;;OAIG;IACH,iBAAiB,CAAC,SAAS,EAAE,oBAAoB,GAAG,cAAc;CAMnE;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,cAAqB,CAAC;AAE/C;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/renderers/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Renderer Module
+ *
+ * Multi-framework rendering system for Tool UI templates.
+ * Supports HTML, React, and MDX templates with auto-detection.
+ *
+ * @module @frontmcp/ui
+ *
+ * @example Basic usage with auto-detection
+ * ```typescript
+ * import { rendererRegistry } from '@frontmcp/ui';
+ *
+ * // HTML template
+ * const htmlTemplate = (ctx) => `<div>${ctx.output.name}</div>`;
+ * const result = await rendererRegistry.render(htmlTemplate, context);
+ * ```
+ *
+ * @example Register React renderer
+ * ```typescript
+ * import { rendererRegistry, reactRenderer } from '@frontmcp/ui';
+ *
+ * rendererRegistry.register(reactRenderer);
+ *
+ * // Now React components are auto-detected
+ * const MyComponent = ({ output }) => <div>{output.name}</div>;
+ * const result = await rendererRegistry.render(MyComponent, context);
+ * ```
+ */
+export type { RendererType, UIRenderer, ToolUIProps, HydratedToolUIProps, TranspileResult, TranspileOptions, RenderOptions, RuntimeScripts, RenderResult, RendererRegistryOptions, DetectionResult, ReactComponentType, WrapperContext, ExtendedToolUIConfig, } from './types';
+export { TranspileCache, transpileCache, renderCache, type TranspileCacheOptions } from './cache';
+export { RendererRegistry, rendererRegistry } from './registry';
+export { HtmlRenderer, htmlRenderer } from './html.renderer';
+export { ReactRenderer, reactRenderer, buildHydrationScript } from './react.renderer';
+export { MdxRenderer, mdxRenderer, buildMdxHydrationScript } from './mdx.renderer';
+export { isReactComponent, isTemplateBuilderFunction, containsJsx, containsMdxSyntax, isPlainHtml, detectTemplateType, hashString, hashCombined, isHash, transpileJsx, isSwcAvailable, executeTranspiledCode, transpileAndExecute, } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/renderers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renderers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,YAAY,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGhE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG7D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGtF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAGnF,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,SAAS,CAAC"}