compiler

Module: Compiler

Generated by Cicadas Bootstrap on 2026-03-22.

Purpose

The compiler package (@aprovan/patchwork-compiler) is the core engine of Patchwork. It compiles JSX/TypeScript source code into executable ESM bundles in-browser using esbuild-wasm, manages project files through a virtual file system with multiple storage backends and bidirectional sync, and mounts compiled widgets into the DOM with configurable isolation and service bridging.

Interfaces

Exports:

• compile(options) — Compile JSX/TSX source to ESM bundle
• mount(widget, options) — Mount a compiled widget (embedded or iframe)
• VirtualFS — Virtual file system with pluggable backends
• MemoryBackend, IndexedDBBackend, HttpBackend — VFS storage backends
• SyncEngine — Bidirectional sync with conflict resolution
• ImageRegistry, loadImage — Widget dependency/image loading from CDN
• generateImportMap — CDN import map generation for bare specifiers
• Zod schemas: ImageConfigSchema, ManifestSchema, MountOptionsSchema

Dependencies:

• esbuild-wasm — In-browser TypeScript/JSX compilation
• zod — Runtime schema validation
• No runtime dependency on other Patchwork packages

Subsystems

Compilation Pipeline

• compiler.ts — Orchestrator: loads images, initializes VFS, runs esbuild with transform plugins
• transforms/cdn.ts — esbuild plugin rewriting bare imports to CDN URLs (esm.sh)
• transforms/vfs.ts — esbuild plugin resolving imports from VirtualFS during build

Virtual File System (VFS)

• vfs/core/virtual-fs.ts — VirtualFS class wrapping an FSProvider backend; tracks local changes
• vfs/backends/memory.ts — In-RAM storage (ephemeral)
• vfs/backends/indexeddb.ts — Browser-persistent storage via IndexedDB
• vfs/backends/http.ts — Remote storage with configurable server URL
• vfs/sync/engine.ts — SyncEngineImpl: bidirectional sync (upload local changes, download remote, resolve conflicts)
• vfs/sync/differ.ts — Change detection by comparing local state to last-known remote state
• vfs/sync/resolver.ts — Conflict resolution strategies: accept-local, accept-remote, abort
• vfs/store.ts — VFS store/state management
• vfs/project.ts — VirtualProject abstraction over a collection of files

Mounting

• mount/embedded.ts — Direct DOM injection with namespace globals for frameworks
• mount/iframe.ts — Iframe sandbox with configurable permissions
• mount/bridge.ts — ParentBridge for cross-context RPC via postMessage (SERVICE_CALL / SERVICE_RESULT)

Image System

• images/registry.ts — ImageRegistry singleton caching loaded images by specifier
• images/loader.ts — Fetches package.json from CDN, validates with ImageConfigSchema, extracts framework config

Key Decisions

• esbuild-wasm over alternatives: Chosen for compilation speed and full browser compatibility without requiring a server-side build step.
• VFS with pluggable backends: Enables the same compiler to operate in browser (Memory/IndexedDB), local development (HTTP → Stitchery), and VS Code (FileSystemProvider) contexts without code changes.
• Bidirectional sync with explicit conflict strategy: Sync engine requires a declared conflict resolution strategy rather than auto-merging, preventing silent data loss.
• postMessage bridge for iframe isolation: Widgets in iframes call services through a structured RPC protocol, maintaining sandbox security while enabling full service access.