Card content
-
+ Input: {JSON.stringify(input)}
-Output: {JSON.stringify(output)}
- -
- ${
- client.icon
- ? `})
`
- : `
- `;
-
- // User info section
- const userSection = user
- ? `
-
- ${escapeHtml(client.name.charAt(0).toUpperCase())}
-
`
- }
- - ${ - client.verified - ? ` - ${escapeHtml(client.name)} - - ` - : escapeHtml(client.name) - } -
-wants to access your account
-
- ${
- user.avatar
- ? `})
`
- : `
- `
- : '';
-
- // Permissions section
- const permissionsSection = `
-
- ${escapeHtml((user.name || user.email || 'U').charAt(0).toUpperCase())}
-
`
- }
-
- ${user.name ? `
-
- Switch account
-
- ${escapeHtml(user.name)}
` : ''}
- ${user.email ? `${escapeHtml(user.email)}
` : ''}
-
-
- `;
-
- // Hidden form fields
- const hiddenFields = [
- csrfToken ? csrfInput(csrfToken) : '',
- state ? hiddenInput('state', state) : '',
- redirectUri ? hiddenInput('redirect_uri', redirectUri) : '',
- responseType ? hiddenInput('response_type', responseType) : '',
- nonce ? hiddenInput('nonce', nonce) : '',
- codeChallenge ? hiddenInput('code_challenge', codeChallenge) : '',
- codeChallengeMethod ? hiddenInput('code_challenge_method', codeChallengeMethod) : '',
- hiddenInput('client_id', client.clientId),
- // Include all scopes if not selectable
- !allowScopeSelection ? permissions.map((p) => hiddenInput('scope[]', p.scope)).join('\n') : '',
- ]
- .filter(Boolean)
- .join('\n');
-
- // Action buttons
- const actionsHtml = `
- This will allow ${escapeHtml(client.name)} to:
- ${permissionList(permissions, { - checkable: allowScopeSelection, - inputName: 'scope', - })} -
-
-
-
- `;
-
- // Privacy/Terms links
- const linksHtml =
- client.privacyUrl || client.termsUrl || client.websiteUrl
- ? `
-
- ${
- client.websiteUrl
- ? `Website`
- : ''
- }
- ${
- client.privacyUrl
- ? `Privacy Policy`
- : ''
- }
- ${
- client.termsUrl
- ? `Terms of Service`
- : ''
- }
-
- `
- : '';
-
- // Combine all content
- const content = `
- ${errorAlert}
- ${unverifiedWarning}
- ${clientHeader}
- ${userSection}
- ${permissionsSection}
- ${actionsHtml}
- ${linksHtml}
- `;
-
- return consentLayout(content, {
- title: `Authorize ${client.name}`,
- clientName: client.name,
- clientIcon: client.icon,
- userInfo: user,
- ...layout,
- });
-}
-
-// ============================================
-// Consent Success Page
-// ============================================
-
-/**
- * Consent success page options
- */
-export interface ConsentSuccessOptions {
- /** Client info */
- client: ClientInfo;
- /** Redirect URL */
- redirectUrl?: string;
- /** Auto redirect delay (ms) */
- autoRedirectDelay?: number;
- /** Layout options */
- layout?: Partial
-
- ${redirectScript}
- `;
-
- return consentLayout(content, {
- title: 'Authorization Successful',
- clientName: client.name,
- clientIcon: client.icon,
- ...layout,
- });
-}
-
-// ============================================
-// Consent Denied Page
-// ============================================
-
-/**
- * Consent denied page options
- */
-export interface ConsentDeniedOptions {
- /** Client info */
- client: ClientInfo;
- /** Redirect URL */
- redirectUrl?: string;
- /** Layout options */
- layout?: Partial
-
-
- Authorization Successful
-- You have authorized ${escapeHtml(client.name)} to access your account. -
- ${ - redirectUrl - ? `Redirecting you back to ${escapeHtml(client.name)}...
` - : '' - } -
-
- `;
-
- return consentLayout(content, {
- title: 'Authorization Denied',
- clientName: client.name,
- clientIcon: client.icon,
- ...layout,
- });
-}
diff --git a/libs/ui/src/pages/error.ts b/libs/ui/src/pages/error.ts
deleted file mode 100644
index 01e25a22..00000000
--- a/libs/ui/src/pages/error.ts
+++ /dev/null
@@ -1,358 +0,0 @@
-/**
- * Error Page Templates
- *
- * Various error page templates (404, 500, etc.)
- */
-
-import { errorLayout, type ErrorLayoutOptions } from '../layouts';
-import { escapeHtml } from '../layouts/base';
-
-// ============================================
-// Error Page Types
-// ============================================
-
-/**
- * Error page options
- */
-export interface ErrorPageOptions {
- /** Error code (404, 500, etc.) */
- code?: string | number;
- /** Error title */
- title?: string;
- /** Error message */
- message?: string;
- /** Detailed error (for development) */
- details?: string;
- /** Show stack trace (development only) */
- showStack?: boolean;
- /** Stack trace */
- stack?: string;
- /** Show retry button */
- showRetry?: boolean;
- /** Retry URL */
- retryUrl?: string;
- /** Show home button */
- showHome?: boolean;
- /** Home URL */
- homeUrl?: string;
- /** Custom actions HTML */
- actions?: string;
- /** Layout options */
- layout?: Partial
-
-
- Authorization Denied
-- You denied ${escapeHtml(client.name)} access to your account. -
- ${ - redirectUrl - ? ` - - Return to ${escapeHtml(client.name)} - - ` - : '' - } -
- ${
- details
- ? `
-
- `
- : '';
-
- // Request ID for support
- const requestIdHtml = requestId
- ? `
-
- Details:
-
- `
- : ''
- }
- ${
- showStack && stack
- ? `
- ${escapeHtml(details)}
-
-
- `
- : ''
- }
- Stack Trace
-${escapeHtml(stack)}
-
- Request ID: ${escapeHtml(requestId)}
-
-
- Sign In
-
-
- `,
- ...rest,
- });
-}
-
-/**
- * 500 Internal Server Error page
- */
-export function serverErrorPage(options: Partial${redirectAction}
` : undefined,
- ...rest,
- });
-}
diff --git a/libs/ui/src/pages/index.ts b/libs/ui/src/pages/index.ts
deleted file mode 100644
index 089c3e5d..00000000
--- a/libs/ui/src/pages/index.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-/**
- * Page Templates Module
- *
- * Minimal page templates that complement SDK auth flows.
- * Login/Register flows are handled by @frontmcp/sdk auth system.
- */
-
-// Consent pages (OAuth/OpenID consent flows)
-export {
- type ClientInfo,
- type UserInfo,
- type ConsentPageOptions,
- type ConsentSuccessOptions,
- type ConsentDeniedOptions,
- consentPage,
- consentSuccessPage,
- consentDeniedPage,
-} from './consent';
-
-// Error pages (generic error display)
-export {
- type ErrorPageOptions,
- type OAuthErrorPageOptions,
- errorPage,
- notFoundPage,
- forbiddenPage,
- unauthorizedPage,
- serverErrorPage,
- maintenancePage,
- rateLimitPage,
- offlinePage,
- sessionExpiredPage,
- oauthErrorPage,
-} from './error';
diff --git a/libs/ui/src/react/index.ts b/libs/ui/src/react/index.ts
index da41fd38..f87504c7 100644
--- a/libs/ui/src/react/index.ts
+++ b/libs/ui/src/react/index.ts
@@ -111,6 +111,3 @@ export type { AlertProps, AlertRenderProps } from './Alert';
// Legacy web component types (for ref typing)
export type { FmcpCard, FmcpBadge, FmcpButton, FmcpAlert, FmcpInput, FmcpSelect } from './types';
-
-// Utilities (deprecated, use render/prerender instead)
-export { renderChildrenToString, isBrowser, isServer } from './utils';
diff --git a/libs/ui/src/react/utils.ts b/libs/ui/src/react/utils.ts
deleted file mode 100644
index b22d5185..00000000
--- a/libs/ui/src/react/utils.ts
+++ /dev/null
@@ -1,101 +0,0 @@
-/**
- * @file utils.ts
- * @description Utility functions for React wrapper components.
- *
- * Provides helpers for converting React children to HTML strings
- * for SSR compatibility with FrontMCP web components.
- *
- * @module @frontmcp/ui/react/utils
- */
-
-import type { ReactNode } from 'react';
-import { escapeHtml } from '@frontmcp/uipack/utils';
-
-// Lazy-load ReactDOMServer to avoid import errors in non-React environments
-let cachedReactDOMServer: typeof import('react-dom/server') | null = null;
-
-/**
- * Get ReactDOMServer lazily (only when needed)
- */
-function getReactDOMServer(): typeof import('react-dom/server') | null {
- if (!cachedReactDOMServer) {
- try {
- cachedReactDOMServer = require('react-dom/server');
- } catch {
- return null;
- }
- }
- return cachedReactDOMServer;
-}
-
-/**
- * Convert React children to an HTML string for SSR.
- *
- * - Strings are escaped via escapeHtml()
- * - Numbers are converted to strings
- * - ReactNode is rendered via ReactDOMServer.renderToStaticMarkup()
- * - null/undefined return empty string
- *
- * @param children - React children to convert
- * @returns HTML string representation
- *
- * @example
- * ```tsx
- * // String children
- * renderChildrenToString('Hello') // 'Hello' (escaped)
- *
- * // React element children
- * renderChildrenToString(Test
) // 'Test
'
- *
- * // Mixed children
- * renderChildrenToString(['Hello', World])
- * ```
- */
-export function renderChildrenToString(children: ReactNode): string {
- // Handle null/undefined
- if (children == null) {
- return '';
- }
-
- // Handle string - escape HTML
- if (typeof children === 'string') {
- return escapeHtml(children);
- }
-
- // Handle number - convert to string
- if (typeof children === 'number') {
- return String(children);
- }
-
- // Handle boolean - React doesn't render true/false
- if (typeof children === 'boolean') {
- return '';
- }
-
- // Handle React elements and arrays - use ReactDOMServer
- try {
- const server = getReactDOMServer();
- if (server) {
- return server.renderToStaticMarkup(children as React.ReactElement);
- }
- // Fallback for non-React environments
- return String(children);
- } catch {
- // Fallback for non-React environments
- return String(children);
- }
-}
-
-/**
- * Check if we're running in a browser environment
- */
-export function isBrowser(): boolean {
- return typeof window !== 'undefined';
-}
-
-/**
- * Check if we're running in a Node.js environment
- */
-export function isServer(): boolean {
- return typeof window === 'undefined';
-}
diff --git a/libs/ui/src/renderers/index.ts b/libs/ui/src/renderers/index.ts
index cc8f54d4..e811a400 100644
--- a/libs/ui/src/renderers/index.ts
+++ b/libs/ui/src/renderers/index.ts
@@ -38,14 +38,14 @@ export type {
} from '@frontmcp/uipack/renderers';
// React Renderer (only available in @frontmcp/ui)
-export { ReactRenderer, reactRenderer, buildHydrationScript } from './react.renderer';
+export { ReactRenderer, reactRenderer } from './react.renderer';
// React Renderer Adapter (client-side rendering)
export { ReactRendererAdapter, createReactAdapter, loadReactAdapter } from './react.adapter';
// MDX Server Renderer (requires React, uses react-dom/server for SSR)
// For client-side CDN-based MDX rendering, use MdxClientRenderer from @frontmcp/uipack
-export { MdxRenderer, mdxRenderer, buildMdxHydrationScript } from './mdx.renderer';
+export { MdxRenderer, mdxRenderer } from './mdx.renderer';
// JSX Execution (requires React)
// For transpilation only (without React), use transpileJsx from @frontmcp/uipack
diff --git a/libs/ui/src/renderers/react.renderer.ts b/libs/ui/src/renderers/react.renderer.ts
index fbdd4f17..e4b6529c 100644
--- a/libs/ui/src/renderers/react.renderer.ts
+++ b/libs/ui/src/renderers/react.renderer.ts
@@ -5,7 +5,15 @@
* - Imported React components (already transpiled)
* - JSX string templates (transpiled at runtime with SWC)
*
- * Uses react-dom/server for SSR to HTML.
+ * Generates HTML for CLIENT-SIDE rendering (no SSR).
+ * React components are rendered in the browser, not on the server.
+ *
+ * @example
+ * ```typescript
+ * // The generated HTML includes React CDN scripts and a render script
+ * // The component is rendered client-side when the page loads
+ * const html = await reactRenderer.render(MyWidget, context);
+ * ```
*/
import type { TemplateContext } from '@frontmcp/uipack/runtime';
@@ -18,14 +26,48 @@ import type {
RuntimeScripts,
ToolUIProps,
} from '@frontmcp/uipack/renderers';
-import {
- isReactComponent,
- containsJsx,
- hashString,
- transpileJsx,
- executeTranspiledCode,
- transpileCache,
-} from '@frontmcp/uipack/renderers';
+import { isReactComponent, containsJsx, hashString, transpileJsx } from '@frontmcp/uipack/renderers';
+
+// ============================================
+// Component Name Validation
+// ============================================
+
+/**
+ * Valid JavaScript identifier pattern.
+ * Matches only alphanumeric characters, underscores, and dollar signs,
+ * and must not start with a digit.
+ */
+const VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+/**
+ * Validate that a component name is a safe JavaScript identifier.
+ *
+ * Prevents code injection attacks where a malicious function name
+ * could break out of the identifier context.
+ *
+ * @param name - Component name to validate
+ * @returns True if the name is a valid JavaScript identifier
+ */
+function isValidComponentName(name: string): boolean {
+ return VALID_JS_IDENTIFIER.test(name);
+}
+
+/**
+ * Sanitize a component name for safe use in generated JavaScript code.
+ *
+ * If the name is not a valid identifier, returns a safe fallback.
+ *
+ * @param name - Component name to sanitize
+ * @returns Safe component name
+ */
+function sanitizeComponentName(name: string): string {
+ if (isValidComponentName(name)) {
+ return name;
+ }
+ // Replace invalid characters with underscores, ensure it starts correctly
+ const sanitized = name.replace(/[^a-zA-Z0-9_$]/g, '_').replace(/^[0-9]/, '_$&');
+ return sanitized || 'Component';
+}
/**
* Types this renderer can handle.
@@ -60,7 +102,8 @@ console.warn('[FrontMCP] React hydration not available on this platform.');
* - Imported React components (FC or class)
* - JSX string templates (transpiled with SWC at runtime)
*
- * Renders to HTML using react-dom/server's renderToString.
+ * Generates HTML for CLIENT-SIDE rendering. The component is rendered
+ * in the browser using React from CDN, not server-side rendered.
*
* @example Imported component
* ```typescript
@@ -88,14 +131,6 @@ export class ReactRenderer implements UIRenderer
+
+
+`;
- return html;
+ return html.trim();
}
/**
@@ -240,22 +336,6 @@ export class ReactRenderer implements UIRenderer
+
+ Loading...
+
+
- ${label ? escapeHtml(label) : 'Progress'}
- ${Math.round(clampedValue)}%
-
`
- : '';
-
- return `
- ${
- animated
- ? ``
- : ''
- }`;
-}
-
-// ============================================
-// Multi-Step Progress
-// ============================================
-
-/**
- * Step definition
- */
-export interface Step {
- /** Step label */
- label: string;
- /** Step description */
- description?: string;
- /** Step status */
- status: 'completed' | 'current' | 'upcoming';
- /** Icon (optional) */
- icon?: string;
- /** URL for clickable steps */
- href?: string;
-}
-
-/**
- * Multi-step progress options
- */
-export interface StepProgressOptions {
- /** Steps */
- steps: Step[];
- /** Orientation */
- orientation?: 'horizontal' | 'vertical';
- /** Connector style */
- connector?: 'line' | 'dashed' | 'none';
- /** Additional CSS classes */
- className?: string;
-}
-
-/**
- * Build a multi-step progress indicator
- */
-export function stepProgress(options: StepProgressOptions): string {
- const { steps, orientation = 'horizontal', connector = 'line', className = '' } = options;
-
- const getStepIcon = (step: Step, index: number): string => {
- if (step.icon) return step.icon;
-
- if (step.status === 'completed') {
- return ``;
- }
-
- return `${index + 1}`;
- };
-
- const getStepClasses = (status: Step['status']): { circle: string; text: string } => {
- switch (status) {
- case 'completed':
- return {
- circle: 'bg-success text-white',
- text: 'text-text-primary',
- };
- case 'current':
- return {
- circle: 'bg-primary text-white ring-4 ring-primary/20',
- text: 'text-primary font-medium',
- };
- case 'upcoming':
- default:
- return {
- circle: 'bg-gray-200 text-gray-500',
- text: 'text-text-secondary',
- };
- }
- };
-
- if (orientation === 'vertical') {
- const stepsHtml = steps
- .map((step, index) => {
- const classes = getStepClasses(step.status);
- const isLast = index === steps.length - 1;
-
- const connectorHtml =
- !isLast && connector !== 'none'
- ? ``
- : '';
-
- const stepContent = `
-
-
- ${connectorHtml}
- `;
-
- return step.href && step.status === 'completed'
- ? `${stepContent}`
- : `
- ${getStepIcon(step, index)}
-
-
-
- ${escapeHtml(step.label)}
- ${
- step.description
- ? `${escapeHtml(step.description)}
` - : '' - } -${stepContent}
`;
- })
- .join('\n');
-
- return `${stepsHtml}
`;
- }
-
- // Horizontal orientation
- const stepsHtml = steps
- .map((step, index) => {
- const classes = getStepClasses(step.status);
- const isLast = index === steps.length - 1;
-
- const connectorHtml =
- !isLast && connector !== 'none'
- ? ``
- : '';
-
- const stepHtml = `
-
-
- `;
-
- const clickableStep =
- step.href && step.status === 'completed'
- ? `${stepHtml}`
- : stepHtml;
-
- return `${clickableStep}${connectorHtml}`;
- })
- .join('\n');
-
- return `
- ${getStepIcon(step, index)}
-
-
-
- ${escapeHtml(step.label)}
- ${
- step.description
- ? `${escapeHtml(step.description)}
` - : '' - } -${stepsHtml}
`;
-}
-
-// ============================================
-// Circular Progress
-// ============================================
-
-/**
- * Circular progress options
- */
-export interface CircularProgressOptions {
- /** Progress value (0-100) */
- value: number;
- /** Size in pixels */
- size?: number;
- /** Stroke width */
- strokeWidth?: number;
- /** Color variant */
- variant?: 'primary' | 'success' | 'warning' | 'danger';
- /** Show percentage */
- showLabel?: boolean;
- /** Custom label */
- label?: string;
- /** Additional CSS classes */
- className?: string;
-}
-
-/**
- * Build a circular progress indicator
- */
-export function circularProgress(options: CircularProgressOptions): string {
- const { value, size = 80, strokeWidth = 8, variant = 'primary', showLabel = true, label, className = '' } = options;
-
- const clampedValue = Math.min(100, Math.max(0, value));
- const radius = (size - strokeWidth) / 2;
- const circumference = radius * 2 * Math.PI;
- const offset = circumference - (clampedValue / 100) * circumference;
-
- const variantColors: Record
-
- ${
- showLabel
- ? `${escapeHtml(displayLabel)}`
- : ''
- }
-
`;
-}
-
-// ============================================
-// Status Indicator
-// ============================================
-
-/**
- * Status indicator options
- */
-export interface StatusIndicatorOptions {
- /** Status state */
- status: 'online' | 'offline' | 'busy' | 'away' | 'loading' | 'error' | 'success';
- /** Status label */
- label?: string;
- /** Size */
- size?: 'sm' | 'md' | 'lg';
- /** Show pulse animation */
- pulse?: boolean;
- /** Additional CSS classes */
- className?: string;
-}
-
-/**
- * Build a status indicator
- */
-export function statusIndicator(options: StatusIndicatorOptions): string {
- const { status, label, size = 'md', pulse = false, className = '' } = options;
-
- const sizeClasses: Record
-
- ${pulseHtml}
-
-
- ${displayLabel ? `${escapeHtml(displayLabel)}` : ''}
-
`;
-}
-
-// ============================================
-// Skeleton Loader
-// ============================================
-
-/**
- * Skeleton loader options
- */
-export interface SkeletonOptions {
- /** Skeleton type */
- type?: 'text' | 'circle' | 'rect' | 'card';
- /** Width (CSS value) */
- width?: string;
- /** Height (CSS value) */
- height?: string;
- /** Number of text lines */
- lines?: number;
- /** Animated */
- animated?: boolean;
- /** Additional CSS classes */
- className?: string;
-}
-
-/**
- * Build a skeleton loader
- */
-export function skeleton(options: SkeletonOptions = {}): string {
- const { type = 'text', width, height, lines = 3, animated = true, className = '' } = options;
-
- const animateClass = animated ? 'animate-pulse' : '';
- const baseClass = `bg-gray-200 ${animateClass}`;
-
- switch (type) {
- case 'circle':
- return ``;
-
- case 'rect':
- return ``;
-
- case 'card':
- return `
-
-
`;
-
- case 'text':
- default: {
- const linesHtml = Array(lines)
- .fill(0)
- .map((_, i) => {
- const lineWidth = i === lines - 1 ? '60%' : i === 0 ? '90%' : '80%';
- return ``;
- })
- .join('\n');
-
- return `
-
-
-
-
- ${linesHtml}
-
`;
- }
- }
-}
-
-/**
- * Build a content skeleton with avatar and text
- */
-export function contentSkeleton(options: { animated?: boolean; className?: string } = {}): string {
- const { animated = true, className = '' } = options;
- const animateClass = animated ? 'animate-pulse' : '';
-
- return `
-
-
`;
-}
diff --git a/libs/ui/src/widgets/resource.ts b/libs/ui/src/widgets/resource.ts
deleted file mode 100644
index 30ff96ae..00000000
--- a/libs/ui/src/widgets/resource.ts
+++ /dev/null
@@ -1,572 +0,0 @@
-/**
- * OpenAI App SDK Resource Widgets
- *
- * Components for displaying resources in OpenAI's App SDK format.
- * These widgets are designed to work with OpenAI Canvas and similar interfaces.
- */
-
-import { escapeHtml } from '../layouts/base';
-import { card, type CardOptions } from '../components/card';
-import { badge, type BadgeVariant } from '../components/badge';
-import { button } from '../components/button';
-
-// ============================================
-// Resource Types
-// ============================================
-
-/**
- * Resource type identifiers
- */
-export type ResourceType =
- | 'document'
- | 'image'
- | 'code'
- | 'data'
- | 'file'
- | 'link'
- | 'user'
- | 'event'
- | 'message'
- | 'task'
- | 'custom';
-
-/**
- * Resource metadata
- */
-export interface ResourceMeta {
- /** Creation timestamp */
- createdAt?: string | Date;
- /** Last modified timestamp */
- updatedAt?: string | Date;
- /** Author/creator */
- author?: string;
- /** File size (bytes) */
- size?: number;
- /** MIME type */
- mimeType?: string;
- /** Tags */
- tags?: string[];
- /** Custom metadata */
- [key: string]: unknown;
-}
-
-/**
- * Resource action
- */
-export interface ResourceAction {
- /** Action label */
- label: string;
- /** Action icon */
- icon?: string;
- /** Action URL */
- href?: string;
- /** HTMX attributes */
- htmx?: {
- get?: string;
- post?: string;
- delete?: string;
- target?: string;
- swap?: string;
- confirm?: string;
- };
- /** Variant */
- variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
- /** Disabled */
- disabled?: boolean;
-}
-
-/**
- * Base resource options
- */
-export interface ResourceOptions {
- /** Resource type */
- type: ResourceType;
- /** Resource title */
- title: string;
- /** Resource description */
- description?: string;
- /** Resource icon */
- icon?: string;
- /** Resource thumbnail URL */
- thumbnail?: string;
- /** Resource URL */
- url?: string;
- /** Resource metadata */
- meta?: ResourceMeta;
- /** Resource status */
- status?: {
- label: string;
- variant: BadgeVariant;
- };
- /** Available actions */
- actions?: ResourceAction[];
- /** Additional CSS classes */
- className?: string;
- /** Card options */
- cardOptions?: Partial
-
-
-
-
- })
-
`
- : `
- ${icon || resourceIcons[type]}
-
`;
-
- // Status badge
- const statusHtml = status ? badge(status.label, { variant: status.variant, size: 'sm' }) : '';
-
- // Metadata
- const metaItems: string[] = [];
- if (meta?.size) {
- metaItems.push(formatFileSize(meta.size));
- }
- if (meta?.mimeType) {
- metaItems.push(meta.mimeType);
- }
- if (meta?.updatedAt) {
- metaItems.push(`Updated ${formatDate(meta.updatedAt)}`);
- } else if (meta?.createdAt) {
- metaItems.push(`Created ${formatDate(meta.createdAt)}`);
- }
- if (meta?.author) {
- metaItems.push(`by ${meta.author}`);
- }
-
- const metaHtml =
- metaItems.length > 0 ? `${metaItems.join(' • ')}
` : '';
-
- // Tags
- const tagsHtml =
- meta?.tags && meta.tags.length > 0
- ? `
- ${meta.tags.map((tag) => badge(tag, { variant: 'default', size: 'sm' })).join('')}
-
`
- : '';
-
- // Actions
- const actionsHtml =
- actions.length > 0
- ? `
- ${actions
- .map((action) => {
- const variantMap: Record = {
- primary: 'primary',
- secondary: 'secondary',
- danger: 'danger',
- ghost: 'ghost',
- };
- const variant = action.variant ? variantMap[action.variant] : 'ghost';
-
- const htmxAttrs: string[] = [];
- if (action.htmx) {
- if (action.htmx.get) htmxAttrs.push(`hx-get="${escapeHtml(action.htmx.get)}"`);
- if (action.htmx.post) htmxAttrs.push(`hx-post="${escapeHtml(action.htmx.post)}"`);
- if (action.htmx.delete) htmxAttrs.push(`hx-delete="${escapeHtml(action.htmx.delete)}"`);
- if (action.htmx.target) htmxAttrs.push(`hx-target="${escapeHtml(action.htmx.target)}"`);
- if (action.htmx.swap) htmxAttrs.push(`hx-swap="${escapeHtml(action.htmx.swap)}"`);
- if (action.htmx.confirm) htmxAttrs.push(`hx-confirm="${escapeHtml(action.htmx.confirm)}"`);
- }
-
- return button(action.label, {
- variant: variant as 'primary' | 'secondary' | 'danger' | 'ghost',
- size: 'sm',
- href: action.href,
- disabled: action.disabled,
- iconBefore: action.icon,
- });
- })
- .join('')}
-
`
- : '';
-
- // Content
- const content = `
-
- ${iconHtml}
-
- `;
-
- return card(content, {
- variant: 'default',
- size: 'md',
- className: `resource-widget resource-${type} ${className}`,
- ...cardOptions,
- });
-}
-
-// ============================================
-// Resource List Widget
-// ============================================
-
-/**
- * Resource list options
- */
-export interface ResourceListOptions {
- /** Resources to display */
- resources: ResourceOptions[];
- /** List title */
- title?: string;
- /** Empty state message */
- emptyMessage?: string;
- /** Grid or list layout */
- layout?: 'list' | 'grid';
- /** Grid columns */
- columns?: 1 | 2 | 3 | 4;
- /** Additional CSS classes */
- className?: string;
- /** Show load more button */
- showLoadMore?: boolean;
- /** Load more URL */
- loadMoreUrl?: string;
-}
-
-/**
- * Build a resource list widget
- */
-export function resourceList(options: ResourceListOptions): string {
- const {
- resources,
- title,
- emptyMessage = 'No resources found',
- layout = 'list',
- columns = 2,
- className = '',
- showLoadMore = false,
- loadMoreUrl,
- } = options;
-
- // Title
- const titleHtml = title ? `
-
-
-
- ${actionsHtml}
-
- ${
- url
- ? `${escapeHtml(
- title,
- )}`
- : `
- ${statusHtml}
- ${escapeHtml(title)}
` - } - ${ - description - ? `${escapeHtml(description)}
` - : '' - } - ${metaHtml} - ${tagsHtml} -${escapeHtml(title)}
` : ''; - - // Empty state - if (resources.length === 0) { - return `
- ${titleHtml}
-
`;
- }
-
- // Layout classes
- const layoutClasses = layout === 'grid' ? `grid grid-cols-1 md:grid-cols-${columns} gap-4` : 'space-y-4';
-
- // Resources
- const resourcesHtml = resources.map((r) => resourceWidget(r)).join('\n');
-
- // Load more button
- const loadMoreHtml =
- showLoadMore && loadMoreUrl
- ? `
-
-
- ${escapeHtml(emptyMessage)}
-
- ${button('Load More', {
- variant: 'outline',
- href: loadMoreUrl,
- })}
-
`
- : '';
-
- return `
- ${titleHtml}
-
`;
-}
-
-// ============================================
-// Compact Resource Item
-// ============================================
-
-/**
- * Build a compact resource item (for inline display)
- */
-export function resourceItem(options: Omit
- ${resourcesHtml}
-
- ${loadMoreHtml}
-
- ${icon || resourceIcons[type]}
-
`;
-
- const statusHtml = status ? badge(status.label, { variant: status.variant, size: 'sm' }) : '';
-
- const metaText = meta?.size ? formatFileSize(meta.size) : '';
-
- const titleElement = url
- ? `${escapeHtml(title)}`
- : `${escapeHtml(title)}`;
-
- return `
- ${iconHtml}
-
`;
-}
-
-// ============================================
-// Preview Widget
-// ============================================
-
-/**
- * Code preview options
- */
-export interface CodePreviewOptions {
- /** Code content */
- code: string;
- /** Language */
- language?: string;
- /** Filename */
- filename?: string;
- /** Show line numbers */
- lineNumbers?: boolean;
- /** Max height */
- maxHeight?: string;
- /** Copy button */
- showCopy?: boolean;
- /** Additional CSS classes */
- className?: string;
-}
-
-/**
- * Build a code preview widget
- */
-export function codePreview(options: CodePreviewOptions): string {
- const {
- code,
- language = 'text',
- filename,
- lineNumbers = true,
- maxHeight = '400px',
- showCopy = true,
- className = '',
- } = options;
-
- const lines = code.split('\n');
-
- const lineNumbersHtml = lineNumbers
- ? `
-
-
- ${titleElement}
- ${statusHtml}
-
- ${
- description || metaText
- ? `${escapeHtml(description || metaText)}
` - : '' - } -
- ${lines.map((_, i) => `
`
- : '';
-
- const copyScript = showCopy
- ? ``
- : '';
-
- const copyButton = showCopy
- ? ``
- : '';
-
- return `${i + 1}
`).join('')}
-
- ${
- filename || showCopy
- ? `
-
`;
-}
-
-/**
- * Image preview options
- */
-export interface ImagePreviewOptions {
- /** Image URL */
- src: string;
- /** Alt text */
- alt: string;
- /** Caption */
- caption?: string;
- /** Max height */
- maxHeight?: string;
- /** Clickable (opens in new tab) */
- clickable?: boolean;
- /** Additional CSS classes */
- className?: string;
-}
-
-/**
- * Build an image preview widget
- */
-export function imagePreview(options: ImagePreviewOptions): string {
- const { src, alt, caption, maxHeight = '400px', clickable = true, className = '' } = options;
-
- const imageHtml = `
- ${filename ? `${escapeHtml(filename)}` : ''}
-
- `
- : ''
- }
-
- ${language ? `${escapeHtml(language)}` : ''}
- ${copyButton}
-
-
-
- ${copyScript}
-
- ${lineNumbersHtml}
-
- ${escapeHtml(code)}${escapeHtml(caption)}
` - : ''; - - const content = clickable - ? `${imageHtml}` - : imageHtml; - - return `
- ${content}
- ${captionHtml}
-
`;
-}
diff --git a/libs/uipack/CLAUDE.md b/libs/uipack/CLAUDE.md
index c799450e..f90c1e17 100644
--- a/libs/uipack/CLAUDE.md
+++ b/libs/uipack/CLAUDE.md
@@ -2,17 +2,17 @@
## Overview
-`@frontmcp/uipack` provides **bundling, build tools, HTML components, and platform adapters** for MCP UI development - all without requiring React.
+`@frontmcp/uipack` provides **bundling, build tools, platform adapters, and theming** for MCP UI development - all without requiring React.
This is the React-free core package. For React components and hooks, use `@frontmcp/ui`.
**Key Principles:**
- Zero React dependency
-- Pure HTML string generation
-- Zod schema validation for all component inputs
- Platform-aware theming and CDN configuration
-- HTMX support for dynamic interactions
+- Build tools for Tool UI generation
+- esbuild/SWC bundling utilities
+- Zod schema validation
## Architecture
@@ -20,17 +20,15 @@ This is the React-free core package. For React components and hooks, use `@front
libs/uipack/src/
├── adapters/ # Platform adapters (OpenAI, Claude, etc.)
├── base-template/ # Default HTML wrappers with polyfills
-├── bridge/ # Multi-platform MCP bridge
+├── bridge-runtime/ # MCP bridge runtime generation
├── build/ # Build-time API (buildToolUI, etc.)
-├── bundler/ # esbuild/SWC bundling
-├── components/ # HTML string components (button, card, etc.)
+├── bundler/ # esbuild/SWC bundling, caching, sandbox
├── dependency/ # CDN resolution and import maps
├── handlebars/ # Handlebars template engine
-├── layouts/ # Page layout templates
-├── pages/ # Pre-built pages (consent, error)
+├── preview/ # Preview server utilities
├── registry/ # Tool UI registry
-├── renderers/ # HTML/MDX renderers
-├── runtime/ # Runtime utilities (template helpers)
+├── renderers/ # HTML/MDX client renderers
+├── runtime/ # Runtime utilities (wrapper, sanitizer, CSP)
├── styles/ # Style variant definitions
├── theme/ # Theme system and CDN config
├── tool-template/ # Tool template utilities
@@ -38,103 +36,52 @@ libs/uipack/src/
├── typings/ # .d.ts type fetching
├── utils/ # Utilities (escapeHtml, safeStringify)
├── validation/ # Zod validation utilities
-├── web-components/ # Custom HTML elements
-├── widgets/ # OpenAI widget utilities
└── index.ts # Main barrel exports
```
## Package Split
-| Package | Purpose | React Required |
-| ------------------ | --------------------------------------------------------- | -------------- |
-| `@frontmcp/uipack` | Bundling, build tools, HTML components, platform adapters | No |
-| `@frontmcp/ui` | React components, hooks, SSR rendering | Yes |
+| Package | Purpose | React Required |
+| ------------------ | ------------------------------------------------------- | -------------- |
+| `@frontmcp/uipack` | Bundling, build tools, platform adapters, theme | No |
+| `@frontmcp/ui` | React components, hooks, SSR rendering, HTML components | Yes |
## Entry Points
-| Path | Purpose |
-| --------------------------------- | ------------------------------------- |
-| `@frontmcp/uipack` | Main exports |
-| `@frontmcp/uipack/adapters` | Platform adapters and meta builders |
-| `@frontmcp/uipack/base-template` | Default HTML templates with polyfills |
-| `@frontmcp/uipack/bridge` | MCP bridge for multiple platforms |
-| `@frontmcp/uipack/build` | Build-time API |
-| `@frontmcp/uipack/bundler` | esbuild/SWC bundling |
-| `@frontmcp/uipack/components` | HTML string components |
-| `@frontmcp/uipack/dependency` | CDN resolution |
-| `@frontmcp/uipack/handlebars` | Handlebars integration |
-| `@frontmcp/uipack/layouts` | Page layouts |
-| `@frontmcp/uipack/pages` | Pre-built pages |
-| `@frontmcp/uipack/registry` | Tool UI registry |
-| `@frontmcp/uipack/renderers` | HTML/MDX renderers |
-| `@frontmcp/uipack/runtime` | Runtime utilities |
-| `@frontmcp/uipack/styles` | Style variants |
-| `@frontmcp/uipack/theme` | Theme system |
-| `@frontmcp/uipack/types` | Type definitions |
-| `@frontmcp/uipack/utils` | Utilities |
-| `@frontmcp/uipack/validation` | Zod validation |
-| `@frontmcp/uipack/web-components` | Custom elements |
-| `@frontmcp/uipack/widgets` | OpenAI widgets |
-
-## Component Development
-
-### 1. Create Schema First
-
-Every component must have a Zod schema with `.strict()` mode:
+| Path | Purpose |
+| -------------------------------- | ------------------------------------- |
+| `@frontmcp/uipack` | Main exports |
+| `@frontmcp/uipack/adapters` | Platform adapters and meta builders |
+| `@frontmcp/uipack/base-template` | Default HTML templates with polyfills |
+| `@frontmcp/uipack/build` | Build-time API (buildToolUI) |
+| `@frontmcp/uipack/bundler` | esbuild/SWC bundling, cache, sandbox |
+| `@frontmcp/uipack/dependency` | CDN resolution and import maps |
+| `@frontmcp/uipack/handlebars` | Handlebars integration |
+| `@frontmcp/uipack/preview` | Preview server utilities |
+| `@frontmcp/uipack/registry` | Tool UI registry |
+| `@frontmcp/uipack/renderers` | HTML/MDX client renderers |
+| `@frontmcp/uipack/runtime` | Runtime utilities (wrapper, CSP) |
+| `@frontmcp/uipack/styles` | Style variants |
+| `@frontmcp/uipack/theme` | Theme system and platform config |
+| `@frontmcp/uipack/types` | Type definitions |
+| `@frontmcp/uipack/typings` | TypeScript definition fetching |
+| `@frontmcp/uipack/utils` | Utilities |
+| `@frontmcp/uipack/validation` | Zod validation |
-```typescript
-// component.schema.ts
-import { z } from 'zod';
-
-export const ComponentOptionsSchema = z
- .object({
- variant: z.enum(['primary', 'secondary']).optional(),
- size: z.enum(['sm', 'md', 'lg']).optional(),
- disabled: z.boolean().optional(),
- className: z.string().optional(),
- htmx: z
- .object({
- get: z.string().optional(),
- post: z.string().optional(),
- target: z.string().optional(),
- swap: z.string().optional(),
- })
- .strict()
- .optional(),
- })
- .strict(); // IMPORTANT: Reject unknown properties
-
-export type ComponentOptions = z.infer${escapeHtml(content)}
`;
-}
-```
-
-### 3. Always Escape User Content
+import { buildToolUI, getOutputModeForClient } from '@frontmcp/uipack/build';
-```typescript
-import { escapeHtml } from '../utils';
+// Build tool UI HTML
+const html = await buildToolUI({
+ template: '{{output.data}}
',
+ context: { input: {}, output: { data: 'Hello' } },
+ platform: 'openai',
+});
-const html = `${escapeHtml(content)}
`;
+// Get output mode for client
+const mode = getOutputModeForClient('openai');
```
## Theme System
@@ -190,20 +137,56 @@ const scripts = buildCdnScriptsFromTheme(DEFAULT_THEME, { inline: false });
const inlineScripts = buildCdnScriptsFromTheme(DEFAULT_THEME, { inline: true });
```
-## Build API
+## Renderers
+
+### HTML Renderer
```typescript
-import { buildToolUI, getOutputModeForClient } from '@frontmcp/uipack/build';
+import { htmlRenderer, HtmlRenderer } from '@frontmcp/uipack/renderers';
-// Build tool UI HTML
-const html = await buildToolUI({
- template: '{{output.data}}
',
- context: { input: {}, output: { data: 'Hello' } },
- platform: 'openai',
+// Render HTML template
+const html = await htmlRenderer.render(template, context);
+```
+
+### MDX Client Renderer (CDN-based)
+
+```typescript
+import { mdxClientRenderer, MdxClientRenderer } from '@frontmcp/uipack/renderers';
+
+// Render MDX using CDN-based React (no bundled React)
+const html = await mdxClientRenderer.render(mdxContent, context);
+```
+
+> **Note:** For server-side MDX rendering with bundled React, use `@frontmcp/ui/renderers`.
+
+## Bundler Utilities
+
+```typescript
+import { BundlerCache, hashContent, createCacheKey, validateSource, executeCode } from '@frontmcp/uipack/bundler';
+
+// Create cache for bundled results
+const cache = new BundlerCache({ maxSize: 100, ttl: 60000 });
+
+// Hash content for cache keys
+const hash = hashContent(sourceCode);
+
+// Validate source code security
+const violations = validateSource(code, policy);
+```
+
+## Validation
+
+```typescript
+import { validateOptions, createErrorBox } from '@frontmcp/uipack/validation';
+
+const result = validateOptions(options, {
+ schema: MySchema,
+ componentName: 'MyComponent',
});
-// Get output mode for client
-const mode = getOutputModeForClient('openai');
+if (!result.success) {
+ return result.error; // HTML error box
+}
```
## Testing Requirements
@@ -241,6 +224,6 @@ Note: No React dependency!
## Related Packages
-- **@frontmcp/ui** - React components, hooks, SSR rendering
+- **@frontmcp/ui** - React components, hooks, SSR rendering, HTML components
- **@frontmcp/sdk** - Core FrontMCP SDK
- **@frontmcp/testing** - E2E testing utilities
diff --git a/libs/uipack/src/build/builders/base-builder.ts b/libs/uipack/src/build/builders/base-builder.ts
new file mode 100644
index 00000000..cad367b5
--- /dev/null
+++ b/libs/uipack/src/build/builders/base-builder.ts
@@ -0,0 +1,393 @@
+/**
+ * Base Builder
+ *
+ * Abstract base class for Static, Hybrid, and Inline builders.
+ * Provides common functionality for template detection, transpilation,
+ * and HTML generation.
+ *
+ * @packageDocumentation
+ */
+
+import { transform } from 'esbuild';
+import type {
+ BuilderOptions,
+ CdnMode,
+ TemplateDetection,
+ TranspileOptions,
+ TranspileResult,
+} from './types';
+import type { UITemplateConfig, TemplateContext, TemplateBuilderFn } from '../../types';
+import type { ThemeConfig } from '../../theme';
+import { DEFAULT_THEME, mergeThemes, buildThemeCss, buildFontPreconnect, buildFontStylesheets } from '../../theme';
+import { createTransformConfig, createExternalizedConfig, DEFAULT_EXTERNALS } from './esbuild-config';
+import { BRIDGE_SCRIPT_TAGS } from '../../bridge-runtime';
+import { HYBRID_DATA_PLACEHOLDER, HYBRID_INPUT_PLACEHOLDER } from '../hybrid-data';
+import { escapeHtml } from '../../utils';
+
+// ============================================
+// Base Builder Class
+// ============================================
+
+/**
+ * Abstract base builder class.
+ *
+ * Provides common functionality:
+ * - Template type detection
+ * - Component transpilation via esbuild
+ * - Theme CSS generation
+ * - HTML document scaffolding
+ */
+export abstract class BaseBuilder {
+ /**
+ * CDN loading mode.
+ */
+ protected readonly cdnMode: CdnMode;
+
+ /**
+ * Whether to minify output.
+ */
+ protected readonly minify: boolean;
+
+ /**
+ * Theme configuration.
+ */
+ protected readonly theme: ThemeConfig;
+
+ /**
+ * Whether to include source maps.
+ */
+ protected readonly sourceMaps: boolean;
+
+ constructor(options: BuilderOptions = {}) {
+ this.cdnMode = options.cdnMode ?? 'cdn';
+ this.minify = options.minify ?? false;
+ this.theme = options.theme ? mergeThemes(DEFAULT_THEME, options.theme) : DEFAULT_THEME;
+ this.sourceMaps = options.sourceMaps ?? false;
+ }
+
+ // ============================================
+ // Template Detection
+ // ============================================
+
+ /**
+ * Detect the type of a template.
+ *
+ * @param template - Template to detect
+ * @returns Detection result with type and renderer info
+ */
+ protected detectTemplate
+
+
+
+
+ `;
+
+ const html = this.wrapInHtmlDocument({
+ head,
+ body,
+ bodyClass: 'antialiased',
+ });
+
+ // Cache the shell
+ this.vendorShellCache = html;
+
+ return html;
+ }
+
+ /**
+ * Build a component chunk for a specific template.
+ *
+ * The component chunk is transpiled with externalized dependencies
+ * (React, etc.) that are provided by the vendor shell.
+ *
+ * @param template - Component template
+ * @returns Transpiled component code
+ */
+ async buildComponentChunk
+
+
+
+
+
+
+
+ Loading component...
+