@frontmcp/uipack 0.12.2 → 1.0.0-beta.1

package/CLAUDE.md

@@ -2,214 +2,116 @@
 
 ## Overview
 
-`@frontmcp/uipack` provides **bundling, build tools, platform adapters, and theming** for MCP UI development - all without requiring React.
+`@frontmcp/uipack` provides **HTML shell builder, pluggable import resolver, and NPM component loader** 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
-- Platform-aware theming and CDN configuration
-- Build tools for Tool UI generation
-- esbuild/SWC bundling utilities
-- Zod schema validation
+- HTML shell generation with CSP, data injection, bridge runtime
+- Pluggable import resolution (esm.sh default, custom resolvers)
+- NPM component loading (npm, file, URL, or inline function)
+- TypeScript type fetching from esm.sh
 
 ## Architecture
 
 ```text
 libs/uipack/src/
-├── adapters/           # Platform adapters (OpenAI, Claude, etc.)
-├── base-template/      # Default HTML wrappers with polyfills
-├── bridge-runtime/     # MCP bridge runtime generation
-├── build/              # Build-time API (buildToolUI, etc.)
-├── bundler/            # esbuild/SWC bundling, caching, sandbox
-├── dependency/         # CDN resolution and import maps
-├── handlebars/         # Handlebars template engine
-├── preview/            # Preview server utilities
-├── registry/           # Tool UI registry
-├── 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
-├── types/              # TypeScript type definitions
-├── typings/            # .d.ts type fetching
-├── utils/              # Utilities (escapeHtml, safeStringify)
-├── validation/         # Zod validation utilities
-└── index.ts            # Main barrel exports
+├── bridge-runtime/   # Platform-aware IIFE generator
+├── component/        # NPM component loader (4 source modes)
+├── resolver/         # Pluggable import resolution (esm.sh default)
+├── shell/            # HTML shell builder with CSP, data injection, bridge
+├── types/            # Standalone UI config types
+├── typings/          # TypeScript type fetching engine
+├── utils/            # XSS-safe escaping functions
+└── index.ts          # Main barrel exports
 ```
 
 ## Package Split
 
-| Package            | Purpose                                                 | React Required |
-| ------------------ | ------------------------------------------------------- | -------------- |
-| `@frontmcp/uipack` | Bundling, build tools, platform adapters, theme         | No             |
-| `@frontmcp/ui`     | React components, hooks, SSR rendering, HTML components | Yes            |
+| Package            | Purpose                                                   | React Required |
+| ------------------ | --------------------------------------------------------- | -------------- |
+| `@frontmcp/uipack` | HTML shell builder, import resolver, NPM component loader | No             |
+| `@frontmcp/ui`     | React components, hooks, SSR rendering                    | 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/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                        |
-
-## Build API
+| Path                              | Purpose                          |
+| --------------------------------- | -------------------------------- |
+| `@frontmcp/uipack`                | Main exports                     |
+| `@frontmcp/uipack/types`          | Standalone UI config types       |
+| `@frontmcp/uipack/utils`          | XSS-safe escaping functions      |
+| `@frontmcp/uipack/bridge-runtime` | Platform bridge IIFE generator   |
+| `@frontmcp/uipack/typings`        | TypeScript .d.ts fetching engine |
+| `@frontmcp/uipack/resolver`       | Pluggable import resolution      |
+| `@frontmcp/uipack/shell`          | HTML shell builder               |
+| `@frontmcp/uipack/component`      | Polymorphic component loader     |
 
-```typescript
-import { buildToolUI, getOutputModeForClient } from '@frontmcp/uipack/build';
-
-// Build tool UI HTML
-const html = await buildToolUI({
-  template: '<div>{{output.data}}</div>',
-  context: { input: {}, output: { data: 'Hello' } },
-  platform: 'openai',
-});
-
-// Get output mode for client
-const mode = getOutputModeForClient('openai');
-```
-
-## Theme System
-
-### Default Theme (GitHub/OpenAI)
+## Shell Builder
 
 ```typescript
-import { DEFAULT_THEME, createTheme } from '@frontmcp/uipack/theme';
-
-// Colors
-DEFAULT_THEME.colors.semantic.primary; // '#24292f' (near-black)
-DEFAULT_THEME.colors.semantic.secondary; // '#57606a' (medium gray)
-DEFAULT_THEME.colors.semantic.accent; // '#0969da' (blue accent)
-```
-
-### Custom Themes
-
-```typescript
-const customTheme = createTheme({
-  name: 'my-theme',
-  colors: {
-    semantic: { primary: '#0969da' },
-  },
-  cdn: {
-    fonts: {
-      preconnect: ['https://fonts.googleapis.com'],
-      stylesheets: ['https://fonts.googleapis.com/css2?family=Roboto&display=swap'],
-    },
-  },
+import { buildShell, buildCSPMetaTag } from '@frontmcp/uipack/shell';
+
+// Build an HTML shell with CSP, data injection, and bridge
+const result = buildShell({
+  body: '<div id="app"></div>',
+  scripts: ['https://esm.sh/react'],
+  csp: { scriptSrc: ["'self'"], styleSrc: ["'unsafe-inline'"] },
+  data: { output: { temperature: 18 } },
 });
 ```
 
-## Platform Support
-
-### Available Platforms
-
-```typescript
-import { getPlatform, OPENAI_PLATFORM, CLAUDE_PLATFORM } from '@frontmcp/uipack/theme';
-
-OPENAI_PLATFORM.network; // 'open' - can fetch external resources
-CLAUDE_PLATFORM.network; // 'blocked' - needs inline scripts
-```
-
-### Building Platform-Aware HTML
+## Import Resolver
 
 ```typescript
-import { buildCdnScriptsFromTheme, DEFAULT_THEME } from '@frontmcp/uipack/theme';
-
-// For platforms with network access
-const scripts = buildCdnScriptsFromTheme(DEFAULT_THEME, { inline: false });
+import { resolveImports, createEsmShResolver } from '@frontmcp/uipack/resolver';
 
-// For blocked-network platforms (Claude)
-const inlineScripts = buildCdnScriptsFromTheme(DEFAULT_THEME, { inline: true });
+// Resolve NPM imports to CDN URLs
+const resolver = createEsmShResolver();
+const resolved = await resolver.resolve('react', '18.3.0');
 ```
 
-## Renderers
-
-### HTML Renderer
+## Component Loader
 
 ```typescript
-import { htmlRenderer, HtmlRenderer } from '@frontmcp/uipack/renderers';
-
-// Render HTML template
-const html = await htmlRenderer.render(template, context);
-```
+import { loadComponent } from '@frontmcp/uipack/component';
 
-### MDX Client Renderer (CDN-based)
+// Load component from npm
+const component = await loadComponent({ source: 'npm', package: '@my-org/widget' });
 
-```typescript
-import { mdxClientRenderer, MdxClientRenderer } from '@frontmcp/uipack/renderers';
-
-// Render MDX using CDN-based React (no bundled React)
-const html = await mdxClientRenderer.render(mdxContent, context);
+// Load from URL
+const component = await loadComponent({ source: 'url', href: 'https://cdn.example.com/widget.js' });
 ```
 
-> **Note:** For server-side MDX rendering with bundled React, use `@frontmcp/ui/renderers`.
-
-## Bundler Utilities
+## Custom Shell Templates
 
 ```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',
-});
+import { resolveShellTemplate, applyShellTemplate } from '@frontmcp/uipack/shell';
 
-if (!result.success) {
-  return result.error; // HTML error box
-}
+// Resolve a custom shell from npm, URL, or inline source
+const template = await resolveShellTemplate({ source: 'npm', package: '@my-org/shell' });
+const html = applyShellTemplate(template, { body: '<div>Content</div>' });
 ```
 
 ## Testing Requirements
 
 - **Coverage**: 95%+ across statements, branches, functions, lines
-- **Validation Tests**: Every component must test invalid inputs
 - **XSS Tests**: Test HTML escaping for user-provided content
-- **Platform Tests**: Test behavior across platform configurations
+- **CSP Tests**: Test Content Security Policy generation
 
 Note: No React dependency!
 
 ## Anti-Patterns to Avoid
 
 - Using `any` type without justification
-- Missing `.strict()` on Zod schemas
-- Not validating component options
-- Exposing internal error details
 - Skipping XSS escaping
-- Hard-coding CDN URLs (use theme.cdn)
+- Hard-coding CDN URLs (use resolver)
 - Adding React dependencies (use @frontmcp/ui for React)
+- Importing from deleted modules (renderers, bundler, build, theme, validation, etc.)
 
 ## Related Packages
 
-- **@frontmcp/ui** - React components, hooks, SSR rendering, HTML components
+- **@frontmcp/ui** - React components, hooks, SSR rendering
 - **@frontmcp/sdk** - Core FrontMCP SDK
 - **@frontmcp/testing** - E2E testing utilities