@seanhogg/builderforce-webcontainers 2026.10.2 → 2026.10.3

package/src/componentCompilers.ts

@@ -0,0 +1,66 @@
+import {
+  createSvelteCompiler,
+  createVueCompiler,
+  isRegistryRange,
+  type ComponentCompiler,
+  type ComponentCompilers,
+  type SvelteCompilerLike,
+  type VueCompilerSfcLike,
+} from '@seanhogg/builderforce-webcontainers-core';
+
+/**
+ * The Vue and Svelte compilers, fetched from a CDN the first time a project
+ * needs one — nothing is downloaded for a React app — and pinned to the
+ * project's own framework range, so compiler and runtime agree. (Svelte's
+ * compiled output calls internal runtime functions that change between minors;
+ * the runtime is served by esm.sh from the same range, so the compiler is too.)
+ */
+export interface CdnComponentCompilerOptions {
+  /** The ES module URL of `@vue/compiler-sfc`'s browser build for a `vue` range. */
+  vueCompilerUrl?: (range: string) => string;
+  /** The ES module URL of `svelte/compiler` for a `svelte` range. */
+  svelteCompilerUrl?: (range: string) => string;
+  /** Loads a module by URL. Default: native `import()`. */
+  importModule?: (url: string) => Promise<unknown>;
+}
+
+/** Self-contained ESM build the official Vue SFC playground loads. */
+export const defaultVueCompilerUrl = (range: string) =>
+  `https://cdn.jsdelivr.net/npm/@vue/compiler-sfc@${range}/dist/compiler-sfc.esm-browser.js`;
+
+export const defaultSvelteCompilerUrl = (range: string) => `https://esm.sh/svelte@${range}/compiler`;
+
+/**
+ * `import()` of a runtime URL. The magic comments stop the host app's bundler
+ * (webpack, Vite) from trying to resolve the CDN URL at build time.
+ */
+const nativeImport = (url: string): Promise<unknown> => import(/* webpackIgnore: true */ /* @vite-ignore */ url);
+
+function rangeOf(dependencies: Readonly<Record<string, string>>, name: string, fallback: string): string {
+  const range = dependencies[name];
+  return range && isRegistryRange(range) ? range : fallback;
+}
+
+export function createCdnComponentCompilers(options: CdnComponentCompilerOptions = {}): ComponentCompilers {
+  const load = options.importModule ?? nativeImport;
+  const cache = new Map<string, Promise<ComponentCompiler>>();
+
+  const memo = (url: string, make: (module: unknown) => ComponentCompiler): Promise<ComponentCompiler> => {
+    let hit = cache.get(url);
+    if (!hit) {
+      hit = load(url).then(make);
+      hit.catch(() => cache.delete(url)); // a failed download may be retried
+      cache.set(url, hit);
+    }
+    return hit;
+  };
+
+  return (extension, dependencies) => {
+    if (extension === '.vue') {
+      const url = (options.vueCompilerUrl ?? defaultVueCompilerUrl)(rangeOf(dependencies, 'vue', '3'));
+      return memo(url, (module) => createVueCompiler(module as VueCompilerSfcLike));
+    }
+    const url = (options.svelteCompilerUrl ?? defaultSvelteCompilerUrl)(rangeOf(dependencies, 'svelte', '5'));
+    return memo(url, (module) => createSvelteCompiler(module as SvelteCompilerLike));
+  };
+}

package/src/esbuildWasm.ts

@@ -1,26 +1,38 @@
-import { createEsbuildTransformer, type Transformer } from '@seanhogg/builderforce-webcontainers-core';
+import { createEsbuildBundler, createEsbuildTransformer, type Bundler, type Transformer } from '@seanhogg/builderforce-webcontainers-core';
 
 export interface EsbuildWasmOptions {
   /** Where to fetch esbuild.wasm. Defaults to jsDelivr at the installed version. */
   wasmURL?: string;
 }
 
-let ready: Promise<Transformer> | undefined;
+type EsbuildWasm = typeof import('esbuild-wasm');
+
+let ready: Promise<EsbuildWasm> | undefined;
 
 /**
- * The default compiler: esbuild compiled to WebAssembly, run off the main thread.
- * esbuild may be initialised once per page, so the transformer is shared by every
- * runtime booted on it (the options of the first call win).
+ * esbuild compiled to WebAssembly, run off the main thread. esbuild may be
+ * initialised once per page, so the dev-server transformer and the production
+ * bundler share one instance (the options of the first call win).
  */
-export function createEsbuildWasmTransformer(options: EsbuildWasmOptions = {}): Promise<Transformer> {
+export function loadEsbuildWasm(options: EsbuildWasmOptions = {}): Promise<EsbuildWasm> {
   ready ??= (async () => {
     const esbuild = await import('esbuild-wasm');
     const wasmURL = options.wasmURL ?? `https://cdn.jsdelivr.net/npm/esbuild-wasm@${esbuild.version}/esbuild.wasm`;
     await esbuild.initialize({ wasmURL, worker: true });
-    return createEsbuildTransformer(esbuild);
+    return esbuild;
   })().catch((error: unknown) => {
     ready = undefined; // let a later call retry (a transient network failure fetching the wasm)
     throw error;
   });
   return ready;
 }
+
+/** The default compiler for the dev server. */
+export async function createEsbuildWasmTransformer(options: EsbuildWasmOptions = {}): Promise<Transformer> {
+  return createEsbuildTransformer(await loadEsbuildWasm(options));
+}
+
+/** The default bundler for `runtime.build()`. */
+export async function createEsbuildWasmBundler(options: EsbuildWasmOptions = {}): Promise<Bundler> {
+  return createEsbuildBundler(await loadEsbuildWasm(options));
+}

package/src/host.ts

@@ -2,15 +2,23 @@ import {
   DevServer,
   ERROR_MESSAGE_TYPE,
   VirtualFileSystem,
-  type DevServerOptions,
+  buildProject,
+  type BuildResult,
+  type Bundler,
+  type ComponentCompilers,
   type FileSystemTree,
   type FlatFiles,
+  type PackageCdnFactory,
   type ProjectProfile,
   type Transformer,
+  type SpawnOptions,
+  type WebContainerProcess,
 } from '@seanhogg/builderforce-webcontainers-core';
-import { PREVIEW_ID, isWireRequest, previewBase, type WireResponse } from './protocol.js';
+import { PREVIEW_ID, isPortPath, isWireRequest, previewBase, type WireRequest, type WireResponse } from './protocol.js';
+import { createProcessHost, servePortRequest, type NodeRuntimeOptions } from './node/index.js';
 import { relayTransport, sameOriginTransport } from './transport.js';
-import { createEsbuildWasmTransformer } from './esbuildWasm.js';
+import { createEsbuildWasmBundler, createEsbuildWasmTransformer } from './esbuildWasm.js';
+import { createCdnComponentCompilers } from './componentCompilers.js';
 
 /** Serve previews on THIS page's origin. Only for code the page's own user trusts. */
 export interface SameOriginOptions {
@@ -38,14 +46,20 @@ export type BootOptions = (SameOriginOptions | RelayOptions) & CommonBootOptions
 export interface CommonBootOptions {
   /** Compiler. Defaults to esbuild-wasm. */
   transformer?: Transformer;
-  /** Package CDN factory. Defaults to esm.sh. */
-  cdn?: DevServerOptions['cdn'];
+  /** Package CDN factory, for previews (`dev: true`) and builds (`dev: false`). Defaults to esm.sh. */
+  cdn?: PackageCdnFactory;
+  /** `.vue` / `.svelte` compilers. Default: the official ones, fetched from a CDN on first use. */
+  components?: ComponentCompilers;
+  /** Bundler for `build()`. Default: esbuild-wasm (the same instance as the compiler). */
+  bundler?: Bundler;
   /** Stable id (e.g. the project id; `[A-Za-z0-9_-]`) — keeps the preview URL stable across reloads. */
   id?: string;
   /** The "Built with Builderforce.ai" badge in the preview. Default true — please keep it. */
   attribution?: boolean;
   /** Reload open previews when files change. Default true. */
   liveReload?: boolean;
+  /** The Node runtime behind `spawn` (process workers, npm registry). */
+  node?: NodeRuntimeOptions;
 }
 
 /** Edits arrive in bursts (a save, an agent writing several files): reload once per burst. */
@@ -57,6 +71,13 @@ export interface PreviewError {
   href: string;
 }
 
+export interface RuntimeBuildOptions {
+  /** Where the site will be served from. Default `./` (works from any directory). */
+  base?: string;
+  /** Default true. */
+  minify?: boolean;
+}
+
 export interface PreviewRuntime {
   readonly id: string;
   /** Absolute URL to load in the preview iframe. */
@@ -66,8 +87,26 @@ export interface PreviewRuntime {
   mount(files: FileSystemTree | FlatFiles): void;
   /** Whether this runtime can serve the mounted project, and why not. */
   profile(): ProjectProfile;
+  /**
+   * `npm run build` for the mounted files: a deployable static site (index.html,
+   * hashed `assets/`, `public/` copied). Rejects with the reason when the project
+   * is not one this runtime supports, or with the bundler's errors.
+   */
+  build(options?: RuntimeBuildOptions): Promise<BuildResult>;
   /** Uncaught errors and rejections raised inside the preview. */
   onError(listener: (error: PreviewError) => void): () => void;
+  /**
+   * Run a command — `node server.js`, `npm install`, `npm run dev`, `jsh` for a
+   * terminal — in its own Web Worker. Same shape as `@webcontainer/api`'s
+   * `spawn`: `output`/`input` streams, `exit`, `kill()`, `resize()`. Pass
+   * `{ terminal: { cols, rows } }` when wiring it to xterm.js.
+   */
+  spawn(command: string, args?: string[], options?: SpawnOptions): WebContainerProcess;
+  spawn(command: string, options?: SpawnOptions): WebContainerProcess;
+  /** `server-ready`: a process started listening (or a dev script handed off to the preview); `url` loads it in an iframe. */
+  on(event: 'server-ready', listener: (port: number, url: string) => void): () => void;
+  /** `port`: a virtual server opened or closed. */
+  on(event: 'port', listener: (port: number, type: 'open' | 'close', url: string) => void): () => void;
   dispose(): void;
 }
 
@@ -75,7 +114,7 @@ function randomId(): string {
   return globalThis.crypto?.randomUUID?.().replace(/-/g, '').slice(0, 16) ?? Math.random().toString(36).slice(2, 18);
 }
 
-function toWire(reqId: number, served: Awaited<ReturnType<DevServer['handle']>>): { message: WireResponse; transfer: Transferable[] } {
+export function toWire(reqId: number, served: Awaited<ReturnType<DevServer['handle']>>): { message: WireResponse; transfer: Transferable[] } {
   if (typeof served.body === 'string') {
     return { message: { type: 'response', reqId, status: served.status, headers: served.headers, body: served.body }, transfer: [] };
   }
@@ -101,20 +140,29 @@ export async function bootPreviewRuntime(options: BootOptions): Promise<PreviewR
 
   const base = previewBase(transport.scope, id);
   const fs = new VirtualFileSystem();
+  const components = options.components ?? createCdnComponentCompilers();
   let server: DevServer;
   try {
     const transformer = options.transformer ?? (await createEsbuildWasmTransformer());
-    server = new DevServer({ fs, transformer, base, cdn: options.cdn, attribution: options.attribution });
+    server = new DevServer({ fs, transformer, base, cdn: options.cdn, components, attribution: options.attribution });
   } catch (error) {
     transport.dispose();
     throw error;
   }
 
+  const previewUrl = new URL(base, transport.origin).href;
+  // In relay mode processes run on the preview origin (the relay starts them), never the host's.
+  const node = { ...options.node, createWorker: options.node?.createWorker ?? transport.createWorker?.bind(transport) };
+  const processes = createProcessHost({ fs, base, origin: transport.origin, previewUrl, options: node });
+
+  const answer = async (request: WireRequest) =>
+    isPortPath(request.path) ? servePortRequest(processes, request) : toWire(request.reqId, await server.handle(request.path, request.search));
+
   const attach = () => {
     const channel = new MessageChannel();
     channel.port1.onmessage = async (event) => {
       if (!isWireRequest(event.data)) return;
-      const { message, transfer } = toWire(event.data.reqId, await server.handle(event.data.path, event.data.search));
+      const { message, transfer } = await answer(event.data);
       channel.port1.postMessage(message, transfer);
     };
     transport.attach(id, channel.port2);
@@ -145,16 +193,23 @@ export async function bootPreviewRuntime(options: BootOptions): Promise<PreviewR
 
   return {
     id,
-    url: new URL(base, transport.origin).href,
+    url: previewUrl,
     fs,
     server,
     mount: (files) => fs.mount(files),
     profile: () => server.profile(),
+    async build(buildOptions = {}) {
+      const bundler = options.bundler ?? (await createEsbuildWasmBundler());
+      return buildProject({ files: fs, bundler, cdn: options.cdn, components, base: buildOptions.base, minify: buildOptions.minify });
+    },
     onError(listener) {
       errorListeners.add(listener);
       return () => errorListeners.delete(listener);
     },
+    spawn: (command: string, args?: string[] | SpawnOptions, spawnOptions?: SpawnOptions) => processes.spawn(command, args as string[], spawnOptions),
+    on: ((event: 'server-ready' | 'port', listener: (...args: any[]) => void) => processes.on(event as 'port', listener)) as PreviewRuntime['on'],
     dispose() {
+      processes.dispose();
       window.removeEventListener('message', onWindowMessage);
       errorListeners.clear();
       clearTimeout(reloadTimer);

package/src/index.ts

@@ -1,9 +1,22 @@
 export { bootPreviewRuntime } from './host.js';
-export type { BootOptions, SameOriginOptions, RelayOptions, CommonBootOptions, PreviewRuntime, PreviewError } from './host.js';
+export type {
+  BootOptions,
+  SameOriginOptions,
+  RelayOptions,
+  CommonBootOptions,
+  PreviewRuntime,
+  PreviewError,
+  RuntimeBuildOptions,
+} from './host.js';
 export type { PreviewTransport } from './transport.js';
-export { createEsbuildWasmTransformer } from './esbuildWasm.js';
+export { createEsbuildWasmTransformer, createEsbuildWasmBundler, loadEsbuildWasm } from './esbuildWasm.js';
 export type { EsbuildWasmOptions } from './esbuildWasm.js';
+export { createCdnComponentCompilers, defaultVueCompilerUrl, defaultSvelteCompilerUrl } from './componentCompilers.js';
+export type { CdnComponentCompilerOptions } from './componentCompilers.js';
+export { createCacheStoragePackageCache } from './packageCache.js';
+export { ProcessHost, createWorkerProcess } from './node/index.js';
+export type { NodeRuntimeOptions, ProcessHostOptions, WorkerLike } from './node/index.js';
 export { createSwRouter } from './swRouter.js';
-export type { SwRouter, SwRouterOptions, PortLike, PreviewTarget, RoutedResponse } from './swRouter.js';
-export { previewBase, previewPrefix, PREVIEW_SEGMENT, PREVIEW_ID } from './protocol.js';
+export type { SwRouter, SwRouterOptions, PortLike, PreviewTarget, RoutedResponse, RequestDetails } from './swRouter.js';
+export { previewBase, previewPrefix, PREVIEW_SEGMENT, PREVIEW_ID, PORT_SEGMENT, isPortPath } from './protocol.js';
 export * from '@seanhogg/builderforce-webcontainers-core';

package/src/node/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Glue between the preview runtime and the Node process host: options, the
+ * default Worker, and answering `/__port/<n>/…` preview requests from the
+ * virtual server listening on that port.
+ */
+import { parsePortPath, type VirtualFileSystem } from '@seanhogg/builderforce-webcontainers-core';
+import type { WireRequest, WireResponse } from '../protocol.js';
+import { ProcessHost, type WorkerLike } from './processHost.js';
+
+export { ProcessHost } from './processHost.js';
+export type { ProcessHostOptions, WorkerLike } from './processHost.js';
+export { createWorkerProcess } from './workerProcess.js';
+
+export interface NodeRuntimeOptions {
+  /**
+   * Where this package's `dist/node/worker.js` is served. Default: resolved
+   * beside this module (`new URL('./worker.js', import.meta.url)`), which
+   * bundlers that understand `new Worker(new URL(…))` handle automatically.
+   */
+  workerUrl?: string | URL;
+  /** Build each process Worker yourself (CSP, a test double). Wins over `workerUrl`. */
+  createWorker?: () => WorkerLike;
+  /** npm registry. Default https://registry.npmjs.org (it sends CORS headers). */
+  registry?: string;
+  /** Cache npm tarballs in Cache Storage. Default true. */
+  packageCache?: boolean;
+  /** Extra environment for every process. */
+  env?: Record<string, string>;
+  /** Grace period before a killed process's worker is terminated. Default 2000ms. */
+  killGraceMs?: number;
+}
+
+export function createProcessHost(args: { fs: VirtualFileSystem; base: string; origin: string; previewUrl: string; options?: NodeRuntimeOptions }): ProcessHost {
+  const { options = {} } = args;
+  const createWorker =
+    options.createWorker ??
+    (() => new Worker(options.workerUrl ?? new URL('./worker.js', import.meta.url), { name: 'bfwc-process' }) as unknown as WorkerLike);
+  return new ProcessHost({
+    fs: args.fs,
+    createWorker,
+    previewOrigin: args.origin,
+    previewBase: args.base,
+    previewUrl: args.previewUrl,
+    registry: options.registry,
+    packageCache: options.packageCache,
+    env: options.env,
+    killGraceMs: options.killGraceMs,
+  });
+}
+
+const TEXT = { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' };
+
+/** Answer a preview request addressed to a virtual server. */
+export async function servePortRequest(host: ProcessHost, request: WireRequest): Promise<{ message: WireResponse; transfer: Transferable[] }> {
+  const target = parsePortPath(request.path)!;
+  const response = await host.request(target.port, {
+    method: request.method ?? 'GET',
+    url: target.path + request.search,
+    headers: request.headers ?? {},
+    body: request.body ? new Uint8Array(request.body) : null,
+  });
+  if (!response) {
+    return { message: { type: 'response', reqId: request.reqId, status: 502, headers: TEXT, body: `Nothing is listening on port ${target.port}. Start a server (node server.js) first.` }, transfer: [] };
+  }
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(response.headers)) headers[key] = Array.isArray(value) ? value.join(', ') : String(value);
+  const body = response.body.slice().buffer as ArrayBuffer;
+  return { message: { type: 'response', reqId: request.reqId, status: response.status, headers, body }, transfer: [body] };
+}

package/src/node/processHost.ts

@@ -0,0 +1,307 @@
+/**
+ * The page side of the Node runtime: one Web Worker per process. The page owns
+ * the master file system and the port table; each worker gets a snapshot of
+ * the files at start, and writes flow both ways as batched ops (a worker's
+ * write reaches the page, then every other worker). Children a worker spawns
+ * (the shell running `node`, `child_process`) are started here too, so every
+ * process — however deep — can be killed by terminating its worker.
+ */
+import {
+  DEFAULT_ENV,
+  PortRegistry,
+  allocatePid,
+  toWebContainerProcess,
+  type ChildHandle,
+  type FsChange,
+  type HttpRequestData,
+  type HttpResponseData,
+  type SpawnOptions,
+  type VirtualFileSystem,
+  type WebContainerProcess,
+} from '@seanhogg/builderforce-webcontainers-core';
+import type { FsOp, HostToWorker, WorkerToHost } from './protocol.js';
+import { portPath } from './protocol.js';
+
+/** The part of `Worker` the host uses — a real Worker, or an in-thread fake in tests. */
+export interface WorkerLike {
+  postMessage(message: unknown): void;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  onerror?: ((event: { message?: string }) => void) | null;
+  terminate(): void;
+}
+
+export interface ProcessHostOptions {
+  fs: VirtualFileSystem;
+  createWorker(): WorkerLike;
+  /** Origin and base path previews are served under (`/__bfwc/<id>/`). */
+  previewOrigin: string;
+  previewBase: string;
+  /** The dev server's preview URL, for the `vite`/`react-scripts start` handoff. */
+  previewUrl?: string;
+  registry?: string;
+  /** Cache npm tarballs in Cache Storage. Default true. */
+  packageCache?: boolean;
+  env?: Record<string, string>;
+  /** How long a killed process may take to exit before its worker is terminated. Default 2000ms. */
+  killGraceMs?: number;
+}
+
+const SIGNAL_CODES: Record<string, number> = { SIGINT: 130, SIGTERM: 143, SIGKILL: 137, SIGHUP: 129 };
+
+interface Proc {
+  pid: number;
+  worker: WorkerLike;
+  stdout: Set<(chunk: string) => void>;
+  stderr: Set<(chunk: string) => void>;
+  exited: boolean;
+  resolveExit(code: number): void;
+  registrations: Map<number, { close(): void }>;
+  children: Map<number, ChildHandle>;
+  pendingHttp: Map<number, (response: HttpResponseData) => void>;
+  outbox: FsOp[];
+}
+
+export class ProcessHost {
+  readonly ports = new PortRegistry();
+  private readonly procs = new Set<Proc>();
+  private readonly serverReady = new Set<(port: number, url: string) => void>();
+  private readonly portListeners = new Set<(port: number, type: 'open' | 'close', url: string) => void>();
+  private applyingFrom?: Proc;
+  private flushScheduled = false;
+  private nextReq = 1;
+  private readonly unwatch: () => void;
+  private readonly stopPorts: () => void;
+
+  constructor(private readonly options: ProcessHostOptions) {
+    this.unwatch = options.fs.watch((change) => this.onFsChange(change));
+    this.stopPorts = this.ports.watch(({ type, port }) => {
+      const url = this.serverUrl(port);
+      for (const proc of this.procs) this.post(proc, { type: 'ports', open: type === 'open' ? [port] : [], closed: type === 'close' ? [port] : [] });
+      for (const l of this.portListeners) l(port, type, url);
+      if (type === 'open') for (const l of this.serverReady) l(port, url);
+    });
+  }
+
+  serverUrl(port: number): string {
+    return new URL(portPath(this.options.previewBase, port), this.options.previewOrigin).href;
+  }
+
+  /** Same shape as `WebContainer#spawn`. */
+  spawn(command: string, args: string[] | SpawnOptions = [], options: SpawnOptions = {}): WebContainerProcess {
+    if (!Array.isArray(args)) [options, args] = [args, []];
+    return toWebContainerProcess(this.spawnChild(command, args, options), !!options.terminal);
+  }
+
+  spawnChild(command: string, args: string[] = [], options: SpawnOptions = {}): ChildHandle {
+    const pid = allocatePid();
+    const worker = this.options.createWorker();
+    let resolveExit!: (code: number) => void;
+    const exit = new Promise<number>((resolve) => (resolveExit = resolve));
+    const proc: Proc = {
+      pid,
+      worker,
+      stdout: new Set(),
+      stderr: new Set(),
+      exited: false,
+      resolveExit: (code) => {
+        if (proc.exited) return;
+        proc.exited = true;
+        this.cleanup(proc);
+        resolveExit(code);
+      },
+      registrations: new Map(),
+      children: new Map(),
+      pendingHttp: new Map(),
+      outbox: [],
+    };
+    this.procs.add(proc);
+    worker.onmessage = (event) => this.onWorkerMessage(proc, event.data as WorkerToHost);
+    worker.onerror = (event) => {
+      for (const l of proc.stderr) l(`Process worker failed: ${event?.message ?? 'unknown error'}\n`);
+      proc.resolveExit(1);
+    };
+    const { fs } = this.options;
+    this.post(proc, {
+      type: 'start',
+      pid,
+      command,
+      args,
+      cwd: options.cwd ?? '/',
+      env: { ...DEFAULT_ENV, ...this.options.env, ...options.env },
+      terminal: options.terminal,
+      files: fs.list().map((path) => [path, fs.readFile(path)!]),
+      dirs: fs.explicitDirectories(),
+      ports: this.ports.ports(),
+      previewOrigin: this.options.previewOrigin,
+      previewBase: this.options.previewBase,
+      previewUrl: this.options.previewUrl,
+      registry: this.options.registry,
+      packageCache: this.options.packageCache !== false,
+    });
+
+    return {
+      pid,
+      onStdout: (l) => (proc.stdout.add(l), () => proc.stdout.delete(l)),
+      onStderr: (l) => (proc.stderr.add(l), () => proc.stderr.delete(l)),
+      write: (data) => this.post(proc, { type: 'stdin', data }),
+      closeStdin: () => this.post(proc, { type: 'stdin', data: null }),
+      kill: (signal = 'SIGTERM') => this.kill(proc, signal),
+      resize: (cols, rows) => this.post(proc, { type: 'resize', cols, rows }),
+      exit,
+    };
+  }
+
+  /** Dispatch an HTTP request to the server on `port` (the preview service worker's `/__port/<port>/` path). */
+  request(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined> {
+    return this.ports.request(port, request);
+  }
+
+  on(event: 'server-ready', listener: (port: number, url: string) => void): () => void;
+  on(event: 'port', listener: (port: number, type: 'open' | 'close', url: string) => void): () => void;
+  on(event: 'server-ready' | 'port', listener: (...args: any[]) => void): () => void {
+    const set = (event === 'server-ready' ? this.serverReady : this.portListeners) as Set<(...args: any[]) => void>;
+    set.add(listener);
+    return () => set.delete(listener);
+  }
+
+  dispose(): void {
+    for (const proc of [...this.procs]) {
+      proc.worker.terminate();
+      proc.resolveExit(SIGNAL_CODES.SIGKILL!);
+    }
+    this.unwatch();
+    this.stopPorts();
+  }
+
+  private kill(proc: Proc, signal: string): void {
+    if (proc.exited) return;
+    if (signal === 'SIGKILL') {
+      proc.worker.terminate();
+      proc.resolveExit(SIGNAL_CODES.SIGKILL!);
+      return;
+    }
+    this.post(proc, { type: 'kill', signal });
+    // A process stuck in a loop never sees the signal: terminate its worker.
+    setTimeout(() => {
+      if (proc.exited) return;
+      proc.worker.terminate();
+      proc.resolveExit(SIGNAL_CODES[signal] ?? 1);
+    }, this.options.killGraceMs ?? 2000);
+  }
+
+  private cleanup(proc: Proc): void {
+    for (const registration of proc.registrations.values()) registration.close();
+    proc.registrations.clear();
+    for (const respond of proc.pendingHttp.values()) respond({ status: 502, headers: { 'content-type': 'text/plain' }, body: new TextEncoder().encode('The server process exited.') });
+    proc.pendingHttp.clear();
+    this.procs.delete(proc);
+    queueMicrotask(() => proc.worker.terminate());
+  }
+
+  private post(proc: Proc, message: HostToWorker): void {
+    if (!proc.exited || message.type === 'start') proc.worker.postMessage(message);
+  }
+
+  private onFsChange(change: FsChange): void {
+    const op: FsOp = change.type === 'write' ? { op: 'write', path: change.path, content: this.options.fs.readFile(change.path)! } : { op: change.type, path: change.path };
+    for (const proc of this.procs) if (proc !== this.applyingFrom) proc.outbox.push(op);
+    if (this.flushScheduled) return;
+    this.flushScheduled = true;
+    queueMicrotask(() => this.flushOutboxes());
+  }
+
+  private flushOutboxes(): void {
+    this.flushScheduled = false;
+    for (const proc of this.procs) {
+      if (!proc.outbox.length) continue;
+      const ops = proc.outbox;
+      proc.outbox = [];
+      this.post(proc, { type: 'fs', ops });
+    }
+  }
+
+  private onWorkerMessage(proc: Proc, message: WorkerToHost): void {
+    switch (message.type) {
+      case 'stdout':
+        for (const l of proc.stdout) l(message.data);
+        return;
+      case 'stderr':
+        for (const l of proc.stderr) l(message.data);
+        return;
+      case 'exit':
+        this.flushOutboxes();
+        return proc.resolveExit(message.code);
+      case 'fs': {
+        this.applyingFrom = proc;
+        try {
+          for (const op of message.ops) {
+            if (op.op === 'write') this.options.fs.writeFile(op.path, op.content);
+            else if (op.op === 'mkdir') this.options.fs.mkdir(op.path);
+            else this.options.fs.rm(op.path);
+          }
+        } finally {
+          this.applyingFrom = undefined;
+        }
+        return;
+      }
+      case 'spawn': {
+        this.flushOutboxes();
+        let child: ChildHandle;
+        try {
+          child = this.spawnChild(message.command, message.args, { cwd: message.cwd, env: message.env, terminal: message.terminal });
+        } catch (error) {
+          return this.post(proc, { type: 'child-error', childId: message.childId, code: (error as { code?: string }).code ?? 'EFAIL', message: (error as Error).message });
+        }
+        proc.children.set(message.childId, child);
+        child.onStdout((data) => this.post(proc, { type: 'child-out', childId: message.childId, stream: 'stdout', data }));
+        child.onStderr((data) => this.post(proc, { type: 'child-out', childId: message.childId, stream: 'stderr', data }));
+        void child.exit.then((code) => {
+          proc.children.delete(message.childId);
+          this.post(proc, { type: 'child-exit', childId: message.childId, code });
+        });
+        return;
+      }
+      case 'child-stdin': {
+        const child = proc.children.get(message.childId);
+        if (message.data === null) child?.closeStdin();
+        else child?.write(message.data);
+        return;
+      }
+      case 'child-kill':
+        return proc.children.get(message.childId)?.kill(message.signal);
+      case 'child-resize':
+        return proc.children.get(message.childId)?.resize?.(message.cols, message.rows);
+      case 'listen': {
+        try {
+          const registration = this.ports.listen(message.port, (request) => this.forward(proc, message.port, request));
+          proc.registrations.set(message.port, registration);
+        } catch (error) {
+          for (const l of proc.stderr) l(`${(error as Error).message}\n`);
+        }
+        return;
+      }
+      case 'unlisten':
+        proc.registrations.get(message.port)?.close();
+        proc.registrations.delete(message.port);
+        return;
+      case 'http-response':
+        proc.pendingHttp.get(message.reqId)?.(message.response);
+        proc.pendingHttp.delete(message.reqId);
+        return;
+      case 'loopback':
+        void this.ports.request(message.port, message.request).then((response) => this.post(proc, { type: 'loopback-response', reqId: message.reqId, response: response ?? null }));
+        return;
+      case 'server-ready':
+        for (const l of this.serverReady) l(message.port, message.url);
+        return;
+    }
+  }
+
+  private forward(proc: Proc, port: number, request: HttpRequestData): Promise<HttpResponseData> {
+    const reqId = this.nextReq++;
+    return new Promise((resolve) => {
+      proc.pendingHttp.set(reqId, resolve);
+      this.post(proc, { type: 'http-request', reqId, port, request });
+    });
+  }
+}