@aprovan/patchwork-compiler 0.1.0 → 0.1.2-dev.1a732c5

package/dist/index.d.cts

@@ -0,0 +1,835 @@
+import { z } from 'zod';
+import { Plugin } from 'esbuild-wasm';
+
+interface VirtualFile {
+    path: string;
+    content: string;
+    language?: string;
+    note?: string;
+    encoding?: "utf8" | "base64";
+}
+interface VirtualProject {
+    id: string;
+    entry: string;
+    files: Map<string, VirtualFile>;
+}
+
+/**
+ * Core types for the Patchwork compiler
+ */
+type Platform = 'browser' | 'cli';
+interface Manifest$1 {
+    name: string;
+    version: string;
+    description?: string;
+    platform: Platform;
+    image: string;
+    inputs?: Record<string, InputSpec>;
+    services?: string[];
+    packages?: Record<string, string>;
+}
+interface InputSpec {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    default?: unknown;
+    required?: boolean;
+    description?: string;
+}
+interface CompileOptions {
+}
+interface CompiledWidget {
+    /** Compiled ESM code */
+    code: string;
+    /** Content hash for caching */
+    hash: string;
+    /** Original manifest */
+    manifest: Manifest$1;
+    /** Source map (if generated) */
+    sourceMap?: string;
+}
+type MountMode = 'embedded' | 'iframe';
+interface MountOptions {
+    /** Target DOM element to mount into */
+    target: HTMLElement;
+    /** Mount mode: embedded (trusted) or iframe (sandboxed) */
+    mode: MountMode;
+    /** CSP sandbox attributes for iframe mode */
+    sandbox?: string[];
+    /** Initial props/inputs to pass to widget */
+    inputs?: Record<string, unknown>;
+}
+interface MountedWidget {
+    /** Unique mount ID */
+    id: string;
+    /** The compiled widget */
+    widget: CompiledWidget;
+    /** Mount mode used */
+    mode: MountMode;
+    /** Target element */
+    target: HTMLElement;
+    /** Iframe element (if mode is 'iframe') */
+    iframe?: HTMLIFrameElement;
+    /** Inputs used for the mount (if provided) */
+    inputs?: Record<string, unknown>;
+    /** Sandbox attributes used for iframe mode (if provided) */
+    sandbox?: string[];
+    /** Unmount function */
+    unmount: () => void;
+}
+interface ImageConfig$1 {
+    platform: Platform;
+    esbuild?: {
+        target?: string;
+        format?: 'esm' | 'cjs' | 'iife';
+        jsx?: 'automatic' | 'transform' | 'preserve';
+        jsxFactory?: string;
+        jsxFragment?: string;
+    };
+    framework?: {
+        /** Map of package names to window global names (e.g., { react: 'React' }) */
+        globals?: Record<string, string>;
+        /** CDN URLs to preload before widget execution */
+        preload?: string[];
+        /** Dependency version overrides for CDN packages (e.g., { react: '18' }) */
+        deps?: Record<string, string>;
+    };
+    /** Import path aliases (e.g., { '@/components/ui/*': '@packagedcn/react' }) */
+    aliases?: Record<string, string>;
+}
+/**
+ * Mount function signature provided by images to handle widget mounting.
+ * Takes the widget module exports and mounts it to the container.
+ *
+ * @param module - The widget module with its exports (default, mount, render, game, etc.)
+ * @param container - The DOM element to mount into
+ * @param inputs - Props/inputs to pass to the widget
+ * @returns A cleanup function to unmount, or void
+ */
+type ImageMountFn = (module: Record<string, unknown>, container: HTMLElement, inputs: Record<string, unknown>) => void | (() => void) | Promise<void | (() => void)>;
+interface LoadedImage {
+    /** Package name */
+    name: string;
+    /** Resolved version */
+    version: string;
+    /** Browser-importable module URL for this image (when loaded from CDN/local HTTP) */
+    moduleUrl?: string;
+    /** Package configuration */
+    config: ImageConfig$1;
+    /** Package dependencies */
+    dependencies: Record<string, string>;
+    /** Setup function (if available) */
+    setup?: (root: HTMLElement) => void | Promise<void>;
+    /** CSS content (if available) */
+    css?: string;
+    /**
+     * Mount function to handle widget mounting.
+     * Each image defines how it expects widgets to export their entry points.
+     * Falls back to default mounting behavior if not provided.
+     */
+    mount?: ImageMountFn;
+}
+interface CompilerOptions {
+    /** Image package to use (e.g., '@aprovan/patchwork-image-shadcnshadcn') */
+    image: string;
+    /** Backend proxy URL for service calls */
+    proxyUrl: string;
+    /** Base URL for CDN (default: 'https://esm.sh'). Used for loading image packages. */
+    cdnBaseUrl?: string;
+    /** Base URL for widget imports (default: same as cdnBaseUrl). Used for transforming imports in widget code. */
+    widgetCdnBaseUrl?: string;
+    /**
+     * URL overrides for bundled assets/packages.
+     * Keys are asset identifiers (e.g., 'esbuild-wasm/esbuild.wasm'), values are local URLs.
+     * Use this to bundle assets locally for offline support or improved performance.
+     */
+    urlOverrides?: Record<string, string>;
+}
+interface Compiler {
+    /** Pre-load an image package */
+    preloadImage(spec: string): Promise<void>;
+    /** Check if an image is loaded */
+    isImageLoaded(spec: string): boolean;
+    /** Compile widget source to ESM */
+    compile(source: string | VirtualProject, manifest: Manifest$1, options?: CompileOptions): Promise<CompiledWidget>;
+    /** Mount a compiled widget to the DOM */
+    mount(widget: CompiledWidget, options: MountOptions): Promise<MountedWidget>;
+    /** Unmount a mounted widget */
+    unmount(mounted: MountedWidget): void;
+    /** Hot reload a mounted widget */
+    reload(mounted: MountedWidget, source: string | VirtualProject, manifest: Manifest$1): Promise<void>;
+}
+/**
+ * Service proxy interface - abstracts service calls to backend
+ *
+ * The compiler provides the interface; actual implementation (e.g., UTCP, MCP)
+ * is handled by the runtime/backend.
+ */
+interface ServiceProxy {
+    call(namespace: string, procedure: string, args: unknown[]): Promise<unknown>;
+}
+/**
+ * Service call handler - function that handles calls for a specific namespace
+ */
+type ServiceCallHandler = (procedure: string, args: unknown[]) => Promise<unknown>;
+/**
+ * Global interface definition for code generation
+ *
+ * Describes available global namespaces and their methods that widgets can call.
+ * Used during compilation to generate proper TypeScript declarations.
+ */
+interface GlobalInterfaceDefinition {
+    /** Namespace name (e.g., 'git', 'github') */
+    name: string;
+    /** Methods available on this namespace (supports nested paths like 'repos.list') */
+    methods: string[];
+    /** Optional TypeScript type definitions for methods */
+    types?: string;
+}
+type BridgeMessageType = 'service-call' | 'service-result' | 'error';
+interface BridgeMessage {
+    type: BridgeMessageType;
+    id: string;
+    payload: unknown;
+}
+interface ServiceCallPayload {
+    namespace: string;
+    procedure: string;
+    args: unknown[];
+}
+interface ServiceResultPayload {
+    result?: unknown;
+    error?: string;
+}
+
+/**
+ * Create a compiler instance
+ */
+declare function createCompiler(options: CompilerOptions): Promise<Compiler>;
+
+/**
+ * Zod schemas for Patchwork compiler types
+ *
+ * These schemas validate:
+ * - ImageConfig from package.json patchwork field
+ * - Widget manifests
+ * - Input specifications
+ */
+
+declare const PlatformSchema: z.ZodEnum<["browser", "cli"]>;
+declare const EsbuildConfigSchema: z.ZodOptional<z.ZodObject<{
+    target: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["esm", "cjs", "iife"]>>;
+    jsx: z.ZodOptional<z.ZodEnum<["automatic", "transform", "preserve"]>>;
+    jsxFactory: z.ZodOptional<z.ZodString>;
+    jsxFragment: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    jsx?: "automatic" | "transform" | "preserve" | undefined;
+    target?: string | undefined;
+    format?: "esm" | "cjs" | "iife" | undefined;
+    jsxFactory?: string | undefined;
+    jsxFragment?: string | undefined;
+}, {
+    jsx?: "automatic" | "transform" | "preserve" | undefined;
+    target?: string | undefined;
+    format?: "esm" | "cjs" | "iife" | undefined;
+    jsxFactory?: string | undefined;
+    jsxFragment?: string | undefined;
+}>>;
+declare const ImageConfigSchema: z.ZodObject<{
+    platform: z.ZodEnum<["browser", "cli"]>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    esbuild: z.ZodOptional<z.ZodObject<{
+        target: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<["esm", "cjs", "iife"]>>;
+        jsx: z.ZodOptional<z.ZodEnum<["automatic", "transform", "preserve"]>>;
+        jsxFactory: z.ZodOptional<z.ZodString>;
+        jsxFragment: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        jsx?: "automatic" | "transform" | "preserve" | undefined;
+        target?: string | undefined;
+        format?: "esm" | "cjs" | "iife" | undefined;
+        jsxFactory?: string | undefined;
+        jsxFragment?: string | undefined;
+    }, {
+        jsx?: "automatic" | "transform" | "preserve" | undefined;
+        target?: string | undefined;
+        format?: "esm" | "cjs" | "iife" | undefined;
+        jsxFactory?: string | undefined;
+        jsxFragment?: string | undefined;
+    }>>;
+    framework: z.ZodOptional<z.ZodObject<{
+        globals: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        preload: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        globals?: Record<string, string> | undefined;
+        preload?: string[] | undefined;
+        deps?: Record<string, string> | undefined;
+    }, {
+        globals?: Record<string, string> | undefined;
+        preload?: string[] | undefined;
+        deps?: Record<string, string> | undefined;
+    }>>;
+    aliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    platform: "browser" | "cli";
+    dependencies?: Record<string, string> | undefined;
+    esbuild?: {
+        jsx?: "automatic" | "transform" | "preserve" | undefined;
+        target?: string | undefined;
+        format?: "esm" | "cjs" | "iife" | undefined;
+        jsxFactory?: string | undefined;
+        jsxFragment?: string | undefined;
+    } | undefined;
+    framework?: {
+        globals?: Record<string, string> | undefined;
+        preload?: string[] | undefined;
+        deps?: Record<string, string> | undefined;
+    } | undefined;
+    aliases?: Record<string, string> | undefined;
+}, {
+    platform: "browser" | "cli";
+    dependencies?: Record<string, string> | undefined;
+    esbuild?: {
+        jsx?: "automatic" | "transform" | "preserve" | undefined;
+        target?: string | undefined;
+        format?: "esm" | "cjs" | "iife" | undefined;
+        jsxFactory?: string | undefined;
+        jsxFragment?: string | undefined;
+    } | undefined;
+    framework?: {
+        globals?: Record<string, string> | undefined;
+        preload?: string[] | undefined;
+        deps?: Record<string, string> | undefined;
+    } | undefined;
+    aliases?: Record<string, string> | undefined;
+}>;
+type ImageConfig = z.infer<typeof ImageConfigSchema>;
+declare const InputSpecSchema: z.ZodObject<{
+    type: z.ZodEnum<["string", "number", "boolean", "object", "array"]>;
+    default: z.ZodOptional<z.ZodUnknown>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    default?: unknown;
+    required?: boolean | undefined;
+    description?: string | undefined;
+}, {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    default?: unknown;
+    required?: boolean | undefined;
+    description?: string | undefined;
+}>;
+declare const ManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    platform: z.ZodEnum<["browser", "cli"]>;
+    image: z.ZodString;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<["string", "number", "boolean", "object", "array"]>;
+        default: z.ZodOptional<z.ZodUnknown>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "string" | "number" | "boolean" | "object" | "array";
+        default?: unknown;
+        required?: boolean | undefined;
+        description?: string | undefined;
+    }, {
+        type: "string" | "number" | "boolean" | "object" | "array";
+        default?: unknown;
+        required?: boolean | undefined;
+        description?: string | undefined;
+    }>>>;
+    services: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    platform: "browser" | "cli";
+    name: string;
+    version: string;
+    image: string;
+    description?: string | undefined;
+    inputs?: Record<string, {
+        type: "string" | "number" | "boolean" | "object" | "array";
+        default?: unknown;
+        required?: boolean | undefined;
+        description?: string | undefined;
+    }> | undefined;
+    services?: string[] | undefined;
+    packages?: Record<string, string> | undefined;
+}, {
+    platform: "browser" | "cli";
+    name: string;
+    version: string;
+    image: string;
+    description?: string | undefined;
+    inputs?: Record<string, {
+        type: "string" | "number" | "boolean" | "object" | "array";
+        default?: unknown;
+        required?: boolean | undefined;
+        description?: string | undefined;
+    }> | undefined;
+    services?: string[] | undefined;
+    packages?: Record<string, string> | undefined;
+}>;
+type Manifest = z.infer<typeof ManifestSchema>;
+declare const CompileOptionsSchema: z.ZodOptional<z.ZodObject<{
+    typescript: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    typescript?: boolean | undefined;
+}, {
+    typescript?: boolean | undefined;
+}>>;
+declare const MountModeSchema: z.ZodEnum<["embedded", "iframe"]>;
+declare const MountOptionsSchema: z.ZodObject<{
+    target: z.ZodType<HTMLElement, z.ZodTypeDef, HTMLElement>;
+    mode: z.ZodEnum<["embedded", "iframe"]>;
+    sandbox: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    target: HTMLElement;
+    mode: "embedded" | "iframe";
+    inputs?: Record<string, unknown> | undefined;
+    sandbox?: string[] | undefined;
+}, {
+    target: HTMLElement;
+    mode: "embedded" | "iframe";
+    inputs?: Record<string, unknown> | undefined;
+    sandbox?: string[] | undefined;
+}>;
+/**
+ * Parse and validate ImageConfig from package.json patchwork field
+ *
+ * @param data - Raw data from package.json patchwork field
+ * @returns Validated ImageConfig
+ * @throws z.ZodError if validation fails
+ */
+declare function parseImageConfig(data: unknown): ImageConfig;
+/**
+ * Safely parse ImageConfig, returning null on failure
+ */
+declare function safeParseImageConfig(data: unknown): ImageConfig | null;
+/**
+ * Parse and validate widget manifest
+ */
+declare function parseManifest(data: unknown): Manifest;
+/**
+ * Safely parse manifest, returning null on failure
+ */
+declare function safeParseManifest(data: unknown): Manifest | null;
+declare const DEFAULT_IMAGE_CONFIG: ImageConfig;
+declare const DEFAULT_CLI_IMAGE_CONFIG: ImageConfig;
+
+/**
+ * Image loader - fetches and loads image packages from CDN or local
+ *
+ * Images must be installed as npm packages or available on CDN.
+ */
+
+/**
+ * Set the CDN base URL for image loading
+ */
+declare function setCdnBaseUrl(url: string): void;
+/**
+ * Get the current CDN base URL
+ */
+declare function getCdnBaseUrl(): string;
+interface ImagePackageJson {
+    name: string;
+    version: string;
+    main?: string;
+    dependencies?: Record<string, string>;
+    patchwork?: unknown;
+}
+/**
+ * Parse image specifier into name and version
+ */
+declare function parseImageSpec(spec: string): {
+    name: string;
+    version?: string;
+};
+/**
+ * Fetch package.json from CDN
+ */
+declare function fetchPackageJson(packageName: string, version?: string): Promise<ImagePackageJson>;
+/**
+ * Load an image package
+ *
+ * Priority:
+ * 1. Try to resolve locally (require.resolve for installed packages)
+ * 2. Fetch from CDN
+ *
+ * Images must be explicitly installed or available on CDN.
+ */
+declare function loadImage(spec: string): Promise<LoadedImage>;
+
+/**
+ * Image registry - manages loaded images
+ */
+
+/**
+ * Registry of loaded images
+ */
+declare class ImageRegistry {
+    private images;
+    private loading;
+    /**
+     * Get a loaded image by spec
+     */
+    get(spec: string): LoadedImage | undefined;
+    /**
+     * Check if an image is loaded
+     */
+    has(spec: string): boolean;
+    /**
+     * Load an image (or return cached)
+     */
+    load(spec: string): Promise<LoadedImage>;
+    /**
+     * Preload an image
+     */
+    preload(spec: string): Promise<void>;
+    /**
+     * Clear a specific image from cache
+     */
+    clear(spec: string): void;
+    /**
+     * Clear all cached images
+     */
+    clearAll(): void;
+    /**
+     * Get all loaded image names
+     */
+    getLoadedNames(): string[];
+}
+/**
+ * Get the global image registry
+ */
+declare function getImageRegistry(): ImageRegistry;
+/**
+ * Create a new isolated image registry
+ */
+declare function createImageRegistry(): ImageRegistry;
+
+/**
+ * CDN transform - converts bare imports to CDN URLs (esm.sh)
+ */
+
+interface CdnTransformOptions {
+    /** Map of package names to versions */
+    packages?: Record<string, string>;
+    /** Additional external packages */
+    external?: string[];
+    /** Use bundled versions from esm.sh (adds ?bundle) */
+    bundle?: boolean;
+    /** Packages to inject from window globals instead of CDN */
+    globals?: Record<string, string>;
+    /** Dependency version overrides for CDN URLs (e.g., { react: '18' }) */
+    deps?: Record<string, string>;
+    /** Import path aliases (e.g., { '@/components/ui/*': '@packagedcn/react' }) */
+    aliases?: Record<string, string>;
+}
+/**
+ * Create an esbuild plugin that transforms bare imports to CDN URLs
+ * and injects globals for specified packages (like React)
+ */
+declare function cdnTransformPlugin(options?: CdnTransformOptions): Plugin;
+/**
+ * Generate import map for CDN dependencies
+ */
+declare function generateImportMap(packages: Record<string, string>): Record<string, string>;
+
+interface VFSPluginOptions {
+    aliases?: Record<string, string>;
+}
+declare function vfsPlugin(project: VirtualProject, options?: VFSPluginOptions): Plugin;
+
+/**
+ * File statistics matching Node.js fs.Stats subset
+ */
+interface FileStats {
+    size: number;
+    mtime: Date;
+    isFile(): boolean;
+    isDirectory(): boolean;
+}
+/**
+ * Directory entry matching Node.js fs.Dirent
+ */
+interface DirEntry {
+    name: string;
+    isFile(): boolean;
+    isDirectory(): boolean;
+}
+type WatchEventType = "create" | "update" | "delete";
+type WatchCallback = (event: WatchEventType, path: string) => void;
+/**
+ * FSProvider - Node.js fs/promises compatible interface
+ * All paths are relative to provider root
+ */
+interface FSProvider {
+    readFile(path: string, encoding?: "utf8" | "base64"): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<FileStats>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<DirEntry[]>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    watch?(path: string, callback: WatchCallback): () => void;
+}
+/**
+ * Change record for sync operations
+ */
+interface ChangeRecord {
+    path: string;
+    type: WatchEventType;
+    mtime: Date;
+    checksum?: string;
+}
+type ConflictStrategy = "local-wins" | "remote-wins" | "newest-wins" | "manual";
+interface SyncResult {
+    pushed: number;
+    pulled: number;
+    conflicts: ConflictRecord[];
+}
+interface ConflictRecord {
+    path: string;
+    localMtime: Date;
+    remoteMtime: Date;
+    resolved?: "local" | "remote";
+}
+type SyncStatus = "idle" | "syncing" | "error";
+type SyncEventType = "change" | "conflict" | "error" | "status";
+type SyncEventCallback<T = unknown> = (data: T) => void;
+
+declare class IndexedDBBackend implements FSProvider {
+    private prefix;
+    constructor(prefix?: string);
+    private key;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<FileStats>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<DirEntry[]>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    private dirExists;
+}
+
+interface HttpBackendConfig {
+    baseUrl: string;
+}
+/**
+ * HTTP-based FSProvider for connecting to remote servers (e.g., stitchery)
+ */
+declare class HttpBackend implements FSProvider {
+    private config;
+    constructor(config: HttpBackendConfig);
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<FileStats>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<DirEntry[]>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    watch(path: string, callback: WatchCallback): () => void;
+    private startWatch;
+    private url;
+}
+
+declare function createProjectFromFiles(files: VirtualFile[], id?: string): VirtualProject;
+declare function resolveEntry(files: Map<string, VirtualFile>): string;
+declare function detectMainFile(language?: string): string;
+declare function createSingleFileProject(content: string, entry?: string, id?: string): VirtualProject;
+
+interface VFSStoreOptions {
+    root?: string;
+    sync?: boolean;
+    conflictStrategy?: ConflictStrategy;
+    autoSyncIntervalMs?: number;
+}
+declare class VFSStore {
+    private provider;
+    private local?;
+    private syncEngine?;
+    private root;
+    constructor(provider: FSProvider, options?: VFSStoreOptions);
+    readFile(path: string, encoding?: "utf8" | "base64"): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<FileStats>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<DirEntry[]>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    listFiles(prefix?: string): Promise<string[]>;
+    loadProject(id: string): Promise<VirtualProject | null>;
+    saveProject(project: VirtualProject): Promise<void>;
+    watch(path: string, callback: WatchCallback): () => void;
+    sync(): Promise<SyncResult>;
+    on<T extends SyncEventType>(event: T, callback: SyncEventCallback<T extends "change" ? ChangeRecord : T extends "conflict" ? ConflictRecord : T extends "error" ? Error : SyncStatus>): () => void;
+    private remotePath;
+    private walkFiles;
+}
+
+/**
+ * Embedded mount mode - mounts widgets directly in the DOM
+ *
+ * For trusted widgets that need full window access.
+ */
+
+/**
+ * Mount a widget in embedded mode (direct DOM injection)
+ */
+declare function mountEmbedded(widget: CompiledWidget, options: MountOptions, image: LoadedImage | null, proxy: ServiceProxy): Promise<MountedWidget>;
+/**
+ * Hot reload an embedded widget
+ */
+declare function reloadEmbedded(mounted: MountedWidget, widget: CompiledWidget, image: LoadedImage | null, proxy: ServiceProxy): Promise<MountedWidget>;
+
+/**
+ * Iframe mount mode - mounts widgets in sandboxed iframes
+ *
+ * For untrusted widgets that need isolation.
+ */
+
+/**
+ * Development sandbox attributes - includes allow-same-origin
+ *
+ * allow-same-origin is required when:
+ * - Fetching modules from the parent origin (e.g., /_local-packages/ in dev)
+ * - Using import maps that reference parent-relative URLs
+ * - Accessing the parent's CDN proxy
+ *
+ * Note: This does NOT allow the iframe to access parent's DOM or cookies,
+ * but it does allow same-origin network requests.
+ *
+ * WARNING: Combining allow-scripts + allow-same-origin allows the iframe to
+ * escape its sandbox. Only use in development or when hosting on a separate subdomain.
+ */
+declare const DEV_SANDBOX: string[];
+/**
+ * Mount a widget in iframe mode (sandboxed)
+ */
+declare function mountIframe(widget: CompiledWidget, options: MountOptions, image: LoadedImage | null, proxy: ServiceProxy): Promise<MountedWidget>;
+/**
+ * Hot reload an iframe widget
+ */
+declare function reloadIframe(mounted: MountedWidget, widget: CompiledWidget, image: LoadedImage | null, proxy: ServiceProxy): Promise<MountedWidget>;
+/**
+ * Dispose the shared bridge (call on app shutdown)
+ */
+declare function disposeIframeBridge(): void;
+
+/**
+ * Service bridge - handles communication between widgets and service proxy
+ */
+
+/**
+ * Create a service proxy that calls the backend via HTTP
+ */
+declare function createHttpServiceProxy(proxyUrl: string): ServiceProxy;
+/**
+ * Creates a proxy that enables fluent method chaining for dynamic field access.
+ *
+ * This allows arbitrary nested property access that resolves to a callable function,
+ * supporting patterns like `proxy.foo()`, `proxy.foo.bar()`, `proxy.bar.baz.qux()`.
+ *
+ * Used to create global namespace objects that proxy calls to a service backend.
+ */
+declare function createFieldAccessProxy<T = unknown>(namespace: string, handler: (namespace: string, methodPath: string, ...args: T[]) => Promise<unknown>): Record<string, (...args: T[]) => Promise<unknown>>;
+/**
+ * Create namespace globals that proxy calls to a service proxy
+ *
+ * Creates dynamic proxy objects for each namespace that support arbitrary
+ * nested method calls. This replaces the old static method registration.
+ *
+ * @param services - Array of service names (e.g., ['git', 'github'])
+ * @param proxy - The service proxy to forward calls to
+ * @returns Record of namespace names to proxy objects
+ *
+ * @example
+ * ```typescript
+ * const namespaces = generateNamespaceGlobals(['git', 'github'], proxy);
+ * // namespaces.git.status() calls proxy.call('git', 'status', [])
+ * // namespaces.github.repos.list_for_user({ username: 'x' })
+ * //   calls proxy.call('github', 'repos.list_for_user', [{ username: 'x' }])
+ * ```
+ */
+declare function generateNamespaceGlobals(services: string[], proxy: ServiceProxy): Record<string, unknown>;
+/**
+ * Inject namespace globals into a window object
+ */
+declare function injectNamespaceGlobals(target: Window | typeof globalThis, namespaces: Record<string, unknown>): void;
+/**
+ * Remove namespace globals from a window object
+ */
+declare function removeNamespaceGlobals(target: Window | typeof globalThis, namespaceNames: string[]): void;
+/**
+ * Extract unique namespace names from services array
+ */
+declare function extractNamespaces(services: string[]): string[];
+/**
+ * Parent-side bridge for iframe communication
+ *
+ * Listens for postMessage events from iframes and proxies service calls.
+ */
+declare class ParentBridge {
+    private proxy;
+    private pendingCalls;
+    private iframes;
+    private messageHandler;
+    constructor(proxy: ServiceProxy);
+    /**
+     * Register an iframe to receive messages from
+     */
+    registerIframe(iframe: HTMLIFrameElement): void;
+    /**
+     * Unregister an iframe
+     */
+    unregisterIframe(iframe: HTMLIFrameElement): void;
+    /**
+     * Handle incoming messages from iframes
+     */
+    private handleMessage;
+    /**
+     * Dispose the bridge
+     */
+    dispose(): void;
+}
+/**
+ * Child-side bridge for iframe communication
+ *
+ * Creates a service proxy that sends postMessage to parent.
+ */
+declare function createIframeServiceProxy(): ServiceProxy;
+/**
+ * Generate the bridge script to inject into iframes
+ *
+ * Creates a self-contained script that sets up:
+ * 1. Message handling for service results from parent
+ * 2. Dynamic proxy objects for each namespace that support arbitrary nested calls
+ */
+declare function generateIframeBridgeScript(services: string[]): string;
+
+export { type BridgeMessage, type BridgeMessageType, type CdnTransformOptions, type ChangeRecord, type CompileOptions, CompileOptionsSchema, type CompiledWidget, type Compiler, type CompilerOptions, DEFAULT_CLI_IMAGE_CONFIG, DEFAULT_IMAGE_CONFIG, DEV_SANDBOX, EsbuildConfigSchema, type GlobalInterfaceDefinition, HttpBackend, type HttpBackendConfig, type ImageConfig$1 as ImageConfig, ImageConfigSchema, type ImageMountFn, ImageRegistry, IndexedDBBackend, type InputSpec, InputSpecSchema, type LoadedImage, type Manifest$1 as Manifest, ManifestSchema, type MountMode, MountModeSchema, type MountOptions, MountOptionsSchema, type MountedWidget, ParentBridge, type Platform, PlatformSchema, type ServiceCallHandler, type ServiceCallPayload, type ServiceProxy, type ServiceResultPayload, type VFSPluginOptions, VFSStore, type VFSStoreOptions, type VirtualFile, type VirtualProject, type WatchCallback, type WatchEventType, cdnTransformPlugin, createCompiler, createFieldAccessProxy, createHttpServiceProxy, createIframeServiceProxy, createImageRegistry, createProjectFromFiles, createSingleFileProject, detectMainFile, disposeIframeBridge, extractNamespaces, fetchPackageJson, generateIframeBridgeScript, generateImportMap, generateNamespaceGlobals, getCdnBaseUrl, getImageRegistry, injectNamespaceGlobals, loadImage, mountEmbedded, mountIframe, parseImageConfig, parseImageSpec, parseManifest, reloadEmbedded, reloadIframe, removeNamespaceGlobals, resolveEntry, safeParseImageConfig, safeParseManifest, setCdnBaseUrl, vfsPlugin };