summary

Canon Summary

Auto-generated during canon synthesis. Consumed by agents at branch start. Target: 300–500 tokens. Optimize for density, not readability.

Purpose

Patchwork is a platform for building generative UI experiences — compile JSX/TypeScript widgets in-browser via esbuild-wasm, mount them with configurable isolation, and connect them to external tool services. Ships as a TypeScript monorepo (pnpm + Turbo) with a VS Code extension and standalone chat app.

Architecture

• Layered library architecture: independently publishable packages composed by integration surfaces (VS Code extension, chat app)
• Compiler pipeline: Source → VFS → esbuild-wasm + transforms (CDN rewriting, VFS resolution) → ESM bundle → Mount (embedded or iframe with postMessage bridge)
• ServiceBackend abstraction: all external calls flow through callProcedure(namespace, procedure, args) — Stitchery aggregates MCP/UTCP tools into a unified service registry
• VFS with pluggable backends: Memory, IndexedDB, HTTP — same compiler works in browser, VS Code, and remote contexts; bidirectional sync with explicit conflict resolution
• iframe isolation: widgets sandboxed with configurable permissions; service calls bridged via structured postMessage RPC

Modules

• compiler (packages/compiler): esbuild-wasm compilation, VFS (3 backends + sync), widget mounting (embedded/iframe + bridge), image/dependency loading, CDN transforms
• bobbin (packages/bobbin): Visual DOM inspector — element selection, margin/padding overlays, style editing with design tokens, change serialization
• editor (packages/editor): TipTap markdown editor, code block extraction from markdown, edit sessions (state machine), diff preview, file tree
• patchwork (packages/patchwork): Service proxy layer — callProcedure, createProxy, ServiceBackend interface (zero deps)
• stitchery (packages/stitchery): Backend server — MCP/UTCP tool aggregation, service registry, /api/chat, /api/edit, /api/proxy/* endpoints
• utcp (packages/utcp): UTCP protocol adapter → ServiceBackend interface
• images/shadcn (packages/images/shadcn): ShadCN/ui runtime — Tailwind Play CDN injection, CSS variable theming, utility exports
• vscode (packages/vscode): VS Code extension — TreeProvider, FileSystemProvider, PreviewPanel, embedded Stitchery, Copilot proxy edits
• chat (apps/chat): Standalone React SPA — Vercel AI SDK (useChat), TipTap input, inline widget preview

Conventions

• All packages export via single index.ts barrel; no cross-package internal imports
• Libraries built with tsup; apps built with vite
• React components: PascalCase files; hooks: use prefix camelCase; utilities: camelCase files
• External calls always via ServiceBackend interface — never call APIs directly from widgets
• File ops always via VFS abstraction — never use fs directly in browser-targeted code
• ShadCN/ui (Radix + Tailwind) is the standard component system