@frontmcp/uipack 0.12.1 → 1.0.0-beta.1

package/resolver/types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Pluggable Import Resolver Types
+ *
+ * Defines the interface for resolving bare import specifiers to URLs
+ * or other loadable expressions. Users can implement custom resolvers
+ * or use the built-in esm.sh resolver.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Context provided to the resolver for platform/version-aware resolution.
+ */
+export interface ResolveContext {
+    /** Target platform (affects CDN selection) */
+    platform?: string;
+    /** Requested package version */
+    version?: string;
+}
+/**
+ * Result of resolving an import specifier.
+ */
+export interface ResolvedImport {
+    /** The resolved URL or expression */
+    value: string;
+    /** How to load: 'url' = ESM import URL, 'global' = window.X, 'function' = resolver fn call */
+    type: 'url' | 'global' | 'function';
+    /** Optional integrity hash (SRI) */
+    integrity?: string;
+}
+/**
+ * Pluggable import resolver interface.
+ *
+ * Implement this to control how bare import specifiers are resolved.
+ * The default implementation uses esm.sh CDN.
+ *
+ * @example
+ * ```typescript
+ * const myResolver: ImportResolver = {
+ *   resolve(specifier) {
+ *     if (specifier === 'react') {
+ *       return { value: 'https://cdn.example.com/react.js', type: 'url' };
+ *     }
+ *     return null; // fall through to default
+ *   }
+ * };
+ * ```
+ */
+export interface ImportResolver {
+    /** Resolve a bare import specifier to a URL or expression. Return null to skip. */
+    resolve(specifier: string, context?: ResolveContext): ResolvedImport | null;
+}
+/**
+ * Options for configuring import resolution behavior.
+ */
+export interface ResolverOptions {
+    /** Custom resolver (overrides default esm.sh) */
+    resolver?: ImportResolver;
+    /** Packages to skip (keep as bare imports) */
+    skipPackages?: string[];
+    /** Per-package URL overrides */
+    overrides?: Record<string, string>;
+}
+/**
+ * Supported CDN providers for external library hosting.
+ */
+export type CDNProvider = 'cloudflare' | 'jsdelivr' | 'unpkg' | 'esm.sh' | 'skypack' | 'custom';
+/**
+ * Configuration for a single CDN dependency.
+ */
+export interface CDNDependency {
+    /** CDN URL for the library (MUST be HTTPS) */
+    url: string;
+    /** Subresource Integrity hash */
+    integrity?: string;
+    /** Global variable name (for UMD builds) */
+    global?: string;
+    /** Named exports */
+    exports?: string[];
+    /** Whether this is an ES module */
+    esm?: boolean;
+    /** Cross-origin attribute */
+    crossorigin?: 'anonymous' | 'use-credentials';
+    /** Peer dependencies (npm package names) */
+    peerDependencies?: string[];
+}
+/**
+ * CDN configuration per provider for a package.
+ */
+export type CDNProviderConfig = Partial<Record<CDNProvider, CDNDependency>>;
+/**
+ * Entry in the CDN registry for a known package.
+ */
+export interface CDNRegistryEntry {
+    /** NPM package name */
+    packageName: string;
+    /** Default/recommended version */
+    defaultVersion: string;
+    /** CDN configurations per provider */
+    providers: CDNProviderConfig;
+    /** Preferred CDN provider order */
+    preferredProviders?: CDNProvider[];
+    /** Package metadata */
+    metadata?: {
+        description?: string;
+        homepage?: string;
+        license?: string;
+    };
+}
+/**
+ * Full CDN registry mapping package names to their CDN configurations.
+ */
+export type CDNRegistry = Record<string, CDNRegistryEntry>;
+/**
+ * Browser import map structure.
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
+ */
+export interface ImportMap {
+    /** Module specifier to URL mappings */
+    imports: Record<string, string>;
+    /** Scoped mappings for specific paths */
+    scopes?: Record<string, Record<string, string>>;
+    /** Integrity hashes for imported modules */
+    integrity?: Record<string, string>;
+}
+/**
+ * Entry for a resolved dependency.
+ */
+export interface ResolvedDependency {
+    /** NPM package name */
+    packageName: string;
+    /** Resolved version string */
+    version: string;
+    /** CDN URL for the package */
+    cdnUrl: string;
+    /** SRI integrity hash */
+    integrity?: string;
+    /** Global variable name (for UMD) */
+    global?: string;
+    /** Whether this is an ES module */
+    esm: boolean;
+    /** CDN provider used */
+    provider: CDNProvider;
+}
+/**
+ * A parsed import statement from source code.
+ */
+export interface ParsedImport {
+    /** Full import statement as it appears in source */
+    statement: string;
+    /** Module specifier (package name or path) */
+    specifier: string;
+    /** Import type */
+    type: 'named' | 'default' | 'namespace' | 'side-effect' | 'dynamic';
+    /** Named imports */
+    namedImports?: string[];
+    /** Default import name */
+    defaultImport?: string;
+    /** Namespace import name */
+    namespaceImport?: string;
+    /** Line number in source (1-indexed) */
+    line: number;
+    /** Column number in source (0-indexed) */
+    column: number;
+}
+/**
+ * Result of parsing imports from a source file.
+ */
+export interface ParsedImportResult {
+    /** All parsed imports */
+    imports: ParsedImport[];
+    /** External package imports (npm packages) */
+    externalImports: ParsedImport[];
+    /** Relative imports (local files) */
+    relativeImports: ParsedImport[];
+    /** Unique external package names */
+    externalPackages: string[];
+}
+/**
+ * Result of rewriting imports.
+ */
+export interface RewriteImportsResult {
+    /** Rewritten source code */
+    code: string;
+    /** Number of imports rewritten */
+    rewrittenCount: number;
+    /** Map of original specifiers to resolved URLs */
+    rewrites: Map<string, string>;
+    /** Packages that used fallback resolution */
+    fallbackPackages: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/resolver/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/resolver/types.ts"],"names":[],"mappings":"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"}

package/shell/builder.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shell Builder
+ *
+ * Generates HTML documents (shells) that wrap UI widget content
+ * with CSP, data injection, and optional bridge runtime.
+ *
+ * @packageDocumentation
+ */
+import type { ShellConfig, ShellResult } from './types';
+/**
+ * Build an HTML shell wrapping the provided content.
+ *
+ * When `withShell: false`, returns just the content with data injection prepended.
+ * When `withShell: true` (default), returns a full HTML document.
+ *
+ * @example
+ * ```typescript
+ * const result = buildShell('<div id="root">Hello</div>', {
+ *   toolName: 'my_tool',
+ *   output: { message: 'Hello World' },
+ * });
+ *
+ * // result.html is a complete HTML document with:
+ * // - CSP meta tag
+ * // - Data injection script
+ * // - Bridge runtime
+ * // - The content in <body>
+ * ```
+ */
+export declare function buildShell(content: string, config: ShellConfig): ShellResult;
+//# sourceMappingURL=builder.d.ts.map

package/shell/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/shell/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,CAkE5E"}

package/shell/csp.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Content Security Policy Builder
+ *
+ * Generates CSP meta tags for sandboxed UI templates.
+ *
+ * @packageDocumentation
+ */
+import type { CSPConfig } from './types';
+/**
+ * Default CDN domains used by FrontMCP UI templates.
+ */
+export declare const DEFAULT_CDN_DOMAINS: readonly ["https://cdn.jsdelivr.net", "https://cdnjs.cloudflare.com", "https://fonts.googleapis.com", "https://fonts.gstatic.com", "https://esm.sh"];
+/**
+ * Default CSP when no custom policy is provided.
+ */
+export declare const DEFAULT_CSP_DIRECTIVES: readonly ["default-src 'none'", `script-src 'self' 'unsafe-inline' ${string}`, `style-src 'self' 'unsafe-inline' ${string}`, `img-src 'self' data: ${string}`, `font-src 'self' data: ${string}`, `connect-src ${string}`, "object-src 'self' data:"];
+/**
+ * Restrictive CSP for sandboxed environments with no external resources.
+ */
+export declare const RESTRICTIVE_CSP_DIRECTIVES: readonly ["default-src 'none'", "script-src 'self' 'unsafe-inline'", "style-src 'self' 'unsafe-inline'", "img-src 'self' data:", "font-src 'self' data:", "connect-src 'none'", "object-src 'self' data:"];
+/**
+ * Build CSP directives from a CSPConfig configuration.
+ */
+export declare function buildCSPDirectives(csp?: CSPConfig): string[];
+/**
+ * Build a CSP meta tag from config.
+ */
+export declare function buildCSPMetaTag(csp?: CSPConfig): string;
+/**
+ * Validate CSP domain format.
+ */
+export declare function validateCSPDomain(domain: string): boolean;
+/**
+ * Filter and warn about invalid CSP domains.
+ */
+export declare function sanitizeCSPDomains(domains: string[] | undefined): string[];
+//# sourceMappingURL=csp.d.ts.map

package/shell/csp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csp.d.ts","sourceRoot":"","sources":["../../src/shell/csp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,mBAAmB,sJAMtB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,sBAAsB,uPAQzB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,0BAA0B,4MAQ7B,CAAC;AAEX;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,MAAM,EAAE,CA+B5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,MAAM,CAIvD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAYzD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAa1E"}

package/shell/custom-shell-applier.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Custom Shell Template Applier
+ *
+ * Replaces placeholder tokens in a custom shell template with
+ * the generated fragment values (CSP, data script, bridge, content, title).
+ *
+ * Uses sequential `replaceAll` — injected content is NOT re-scanned,
+ * so `{{CSP}}` inside user content is safe.
+ *
+ * @packageDocumentation
+ */
+import type { ShellPlaceholderValues } from './custom-shell-types';
+/**
+ * Apply placeholder values to a custom shell template.
+ *
+ * Each `{{PLACEHOLDER}}` token is replaced with the corresponding value.
+ * Replacement is single-pass per token — values injected for one placeholder
+ * are not re-scanned for other placeholders.
+ *
+ * @param template - The shell template with `{{PLACEHOLDER}}` tokens
+ * @param values - The values to inject for each placeholder
+ * @returns The final HTML string with all placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * const html = applyShellTemplate(
+ *   '<html><head>{{CSP}}{{DATA}}</head><body>{{CONTENT}}</body></html>',
+ *   { csp: '<meta ...>', data: '<script>...</script>', bridge: '', content: '<div>Hi</div>', title: 'My Tool' },
+ * );
+ * ```
+ */
+export declare function applyShellTemplate(template: string, values: ShellPlaceholderValues): string;
+//# sourceMappingURL=custom-shell-applier.d.ts.map

package/shell/custom-shell-applier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-shell-applier.d.ts","sourceRoot":"","sources":["../../src/shell/custom-shell-applier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAU3F"}

package/shell/custom-shell-resolver.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Custom Shell Template Resolver
+ *
+ * Resolves custom shell template sources (inline, URL, npm) to
+ * validated `ResolvedShellTemplate` objects. URL and npm sources
+ * are cached in-memory to avoid redundant fetches.
+ *
+ * @packageDocumentation
+ */
+import type { CustomShellSource, ResolvedShellTemplate } from './custom-shell-types';
+import type { ImportResolver } from '../resolver/types';
+/** Options for resolving shell templates */
+export interface ResolveShellOptions {
+    /** Custom import resolver (for npm sources) */
+    resolver?: ImportResolver;
+    /** Skip cache lookup and storage */
+    noCache?: boolean;
+}
+/**
+ * Resolve a custom shell source to a validated template.
+ *
+ * - **Inline:** validates immediately and returns
+ * - **URL:** fetches with timeout, validates, caches by URL
+ * - **NPM:** resolves specifier via ImportResolver → CDN URL, fetches, extracts template string, validates, caches
+ *
+ * @throws {Error} If the template is missing required placeholders
+ * @throws {Error} If the URL fetch fails or times out
+ * @throws {Error} If npm resolution fails or template extraction fails
+ *
+ * @example
+ * ```typescript
+ * // Inline
+ * const resolved = await resolveShellTemplate({ inline: '<html>{{CONTENT}}</html>' });
+ *
+ * // URL
+ * const resolved = await resolveShellTemplate({ url: 'https://example.com/shell.html' });
+ *
+ * // NPM
+ * const resolved = await resolveShellTemplate({ npm: 'my-shell-package' });
+ * ```
+ */
+export declare function resolveShellTemplate(source: CustomShellSource, options?: ResolveShellOptions): Promise<ResolvedShellTemplate>;
+/**
+ * Clear the in-memory shell template cache.
+ */
+export declare function clearShellTemplateCache(): void;
+//# sourceMappingURL=custom-shell-resolver.d.ts.map

package/shell/custom-shell-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-shell-resolver.d.ts","sourceRoot":"","sources":["../../src/shell/custom-shell-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAkB,MAAM,sBAAsB,CAAC;AAGrG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAQxD,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CA2ChC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/shell/custom-shell-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Custom Shell Template Types
+ *
+ * Types, constants, and type guards for custom HTML shell templates
+ * with placeholder-based injection.
+ *
+ * @packageDocumentation
+ */
+/** All supported placeholder names */
+export declare const SHELL_PLACEHOLDER_NAMES: readonly ["CSP", "DATA", "BRIDGE", "CONTENT", "TITLE"];
+/** Placeholder name type */
+export type ShellPlaceholderName = (typeof SHELL_PLACEHOLDER_NAMES)[number];
+/** Placeholder tokens as they appear in templates (e.g., `{{CSP}}`) */
+export declare const SHELL_PLACEHOLDERS: Record<ShellPlaceholderName, string>;
+/** Placeholders that MUST be present in a custom shell template */
+export declare const REQUIRED_PLACEHOLDERS: readonly ShellPlaceholderName[];
+/** Placeholders that are optional (omitted silently if absent) */
+export declare const OPTIONAL_PLACEHOLDERS: readonly ShellPlaceholderName[];
+/** Mode 1: Inline HTML string */
+export interface InlineShellSource {
+    inline: string;
+}
+/** Mode 2: Fetch from URL */
+export interface UrlShellSource {
+    url: string;
+    /** Fetch timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+/** Mode 3: Load from npm package */
+export interface NpmShellSource {
+    npm: string;
+    /** Named export to use (default: 'default') */
+    exportName?: string;
+    /** Package version */
+    version?: string;
+}
+/** Union of all custom shell source types */
+export type CustomShellSource = InlineShellSource | UrlShellSource | NpmShellSource;
+export declare function isInlineShellSource(source: CustomShellSource): source is InlineShellSource;
+export declare function isUrlShellSource(source: CustomShellSource): source is UrlShellSource;
+export declare function isNpmShellSource(source: CustomShellSource): source is NpmShellSource;
+/** Result of validating a shell template for placeholder presence */
+export interface ShellTemplateValidation {
+    /** Whether all required placeholders are present */
+    valid: boolean;
+    /** Map of placeholder name → whether it was found in the template */
+    found: Record<ShellPlaceholderName, boolean>;
+    /** Required placeholders that are missing */
+    missingRequired: ShellPlaceholderName[];
+    /** Optional placeholders that are missing */
+    missingOptional: ShellPlaceholderName[];
+}
+/** A resolved and validated shell template ready for use */
+export interface ResolvedShellTemplate {
+    /** The raw template string with placeholders */
+    template: string;
+    /** How the template was sourced */
+    sourceType: 'inline' | 'url' | 'npm';
+    /** Validation result */
+    validation: ShellTemplateValidation;
+}
+/** Values to inject into shell template placeholders */
+export interface ShellPlaceholderValues {
+    /** CSP meta tag HTML */
+    csp: string;
+    /** Data injection script HTML */
+    data: string;
+    /** Bridge runtime script HTML */
+    bridge: string;
+    /** Widget content HTML */
+    content: string;
+    /** Page title */
+    title: string;
+}
+//# sourceMappingURL=custom-shell-types.d.ts.map

package/shell/custom-shell-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-shell-types.d.ts","sourceRoot":"","sources":["../../src/shell/custom-shell-types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,sCAAsC;AACtC,eAAO,MAAM,uBAAuB,wDAAyD,CAAC;AAE9F,4BAA4B;AAC5B,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAM1D,CAAC;AAEX,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,EAAE,SAAS,oBAAoB,EAAgB,CAAC;AAElF,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,EAAE,SAAS,oBAAoB,EAAuC,CAAC;AAMzG,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,cAAc,GAAG,cAAc,CAAC;AAMpF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,IAAI,iBAAiB,CAE1F;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,IAAI,cAAc,CAEpF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,IAAI,cAAc,CAEpF;AAMD,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;IAC7C,6CAA6C;IAC7C,eAAe,EAAE,oBAAoB,EAAE,CAAC;IACxC,6CAA6C;IAC7C,eAAe,EAAE,oBAAoB,EAAE,CAAC;CACzC;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,UAAU,EAAE,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;IACrC,wBAAwB;IACxB,UAAU,EAAE,uBAAuB,CAAC;CACrC;AAMD,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;CACf"}

package/shell/custom-shell-validator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Custom Shell Template Validator
+ *
+ * Validates that a shell template contains the required placeholders
+ * and reports which optional placeholders are missing.
+ *
+ * @packageDocumentation
+ */
+import type { ShellTemplateValidation } from './custom-shell-types';
+/**
+ * Validate a shell template string for placeholder presence.
+ *
+ * Scans for all known placeholders (`{{CSP}}`, `{{DATA}}`, `{{BRIDGE}}`,
+ * `{{CONTENT}}`, `{{TITLE}}`) and reports which are found/missing.
+ *
+ * @returns Validation result with `valid: true` only if all required placeholders are present
+ *
+ * @example
+ * ```typescript
+ * const v = validateShellTemplate('<html>{{CSP}}{{CONTENT}}</html>');
+ * // v.valid === true (CONTENT is present)
+ * // v.missingOptional === ['DATA', 'BRIDGE', 'TITLE']
+ * ```
+ */
+export declare function validateShellTemplate(template: string): ShellTemplateValidation;
+//# sourceMappingURL=custom-shell-validator.d.ts.map

package/shell/custom-shell-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-shell-validator.d.ts","sourceRoot":"","sources":["../../src/shell/custom-shell-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAAwB,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE1F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAgB/E"}

package/shell/data-injector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Data Injector
+ *
+ * Injects tool data (input, output, metadata) into HTML as window globals.
+ * Provides template helper functions for safe HTML rendering.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Generate a script tag that injects tool data as window globals.
+ *
+ * Sets `window.__mcpToolName`, `window.__mcpToolInput`,
+ * `window.__mcpToolOutput`, and `window.__mcpStructuredContent`.
+ */
+export declare function buildDataInjectionScript(options: {
+    toolName: string;
+    input?: unknown;
+    output?: unknown;
+    structuredContent?: unknown;
+}): string;
+/**
+ * Template helper functions for safe rendering.
+ */
+export interface TemplateHelpers {
+    /** Escape HTML special characters to prevent XSS */
+    escapeHtml: (str: unknown) => string;
+    /** Format a date for display */
+    formatDate: (date: Date | string, format?: string) => string;
+    /** Format a number as currency */
+    formatCurrency: (amount: number, currency?: string) => string;
+    /** Generate a unique ID for DOM elements */
+    uniqueId: (prefix?: string) => string;
+    /** Safely embed JSON data in HTML */
+    jsonEmbed: (data: unknown) => string;
+}
+/**
+ * Create template helper functions.
+ */
+export declare function createTemplateHelpers(): TemplateHelpers;
+//# sourceMappingURL=data-injector.d.ts.map

package/shell/data-injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-injector.d.ts","sourceRoot":"","sources":["../../src/shell/data-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,MAAM,CAWT;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACrC,gCAAgC;IAChC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7D,kCAAkC;IAClC,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9D,4CAA4C;IAC5C,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,qCAAqC;IACrC,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;CACtC;AAID;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CA6BvD"}

package/shell/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shell Module
+ *
+ * HTML shell builder for wrapping UI widget content with
+ * CSP, data injection, and bridge runtime.
+ *
+ * @packageDocumentation
+ */
+export type { ShellConfig, ShellResult, CSPConfig } from './types';
+export { buildShell } from './builder';
+export { DEFAULT_CDN_DOMAINS, DEFAULT_CSP_DIRECTIVES, RESTRICTIVE_CSP_DIRECTIVES, buildCSPDirectives, buildCSPMetaTag, validateCSPDomain, sanitizeCSPDomains, } from './csp';
+export { buildDataInjectionScript, createTemplateHelpers, type TemplateHelpers } from './data-injector';
+export type { ShellPlaceholderName, InlineShellSource, UrlShellSource, NpmShellSource, CustomShellSource, ShellTemplateValidation, ResolvedShellTemplate, ShellPlaceholderValues, } from './custom-shell-types';
+export { SHELL_PLACEHOLDER_NAMES, SHELL_PLACEHOLDERS, REQUIRED_PLACEHOLDERS, OPTIONAL_PLACEHOLDERS, isInlineShellSource, isUrlShellSource, isNpmShellSource, } from './custom-shell-types';
+export { validateShellTemplate } from './custom-shell-validator';
+export { applyShellTemplate } from './custom-shell-applier';
+export { resolveShellTemplate, clearShellTemplateCache } from './custom-shell-resolver';
+export type { ResolveShellOptions } from './custom-shell-resolver';
+//# sourceMappingURL=index.d.ts.map

package/shell/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,OAAO,CAAC;AAGf,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGxG,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}