@seanhogg/builderforce-webcontainers 2026.10.1 → 2026.10.3

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 });
+    });
+  }
+}

package/src/node/protocol.ts

@@ -0,0 +1,63 @@
+/**
+ * Messages between the page (the process host, which owns the master file
+ * system and the port table) and one process Worker. Everything is plain
+ * structured-clone data; file contents travel as strings or bytes.
+ */
+import type { FileContent, HttpRequestData, HttpResponseData } from '@seanhogg/builderforce-webcontainers-core';
+
+export type FsOp = { op: 'write'; path: string; content: FileContent } | { op: 'remove'; path: string } | { op: 'mkdir'; path: string };
+
+export interface StartMessage {
+  type: 'start';
+  pid: number;
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+  terminal?: { cols: number; rows: number };
+  files: Array<[string, FileContent]>;
+  dirs: string[];
+  /** Ports already listening anywhere in the runtime (so `listen` can fail fast with EADDRINUSE). */
+  ports: number[];
+  /** `/__bfwc/<id>/` on the preview origin, for `serverUrl`. */
+  previewOrigin: string;
+  previewBase: string;
+  previewUrl?: string;
+  registry?: string;
+  /** Use Cache Storage for npm tarballs. */
+  packageCache: boolean;
+}
+
+/** page → worker */
+export type HostToWorker =
+  | StartMessage
+  | { type: 'stdin'; data: string | null }
+  | { type: 'kill'; signal: string }
+  | { type: 'resize'; cols: number; rows: number }
+  | { type: 'fs'; ops: FsOp[] }
+  | { type: 'ports'; open: number[]; closed: number[] }
+  | { type: 'child-out'; childId: number; stream: 'stdout' | 'stderr'; data: string }
+  | { type: 'child-exit'; childId: number; code: number }
+  | { type: 'child-error'; childId: number; code: string; message: string }
+  | { type: 'http-request'; reqId: number; port: number; request: HttpRequestData }
+  | { type: 'loopback-response'; reqId: number; response: HttpResponseData | null };
+
+/** worker → page */
+export type WorkerToHost =
+  | { type: 'stdout' | 'stderr'; data: string }
+  | { type: 'exit'; code: number }
+  | { type: 'fs'; ops: FsOp[] }
+  | { type: 'spawn'; childId: number; command: string; args: string[]; cwd?: string; env?: Record<string, string>; terminal?: { cols: number; rows: number } }
+  | { type: 'child-stdin'; childId: number; data: string | null }
+  | { type: 'child-kill'; childId: number; signal: string }
+  | { type: 'child-resize'; childId: number; cols: number; rows: number }
+  | { type: 'listen'; port: number }
+  | { type: 'unlisten'; port: number }
+  | { type: 'http-response'; reqId: number; response: HttpResponseData }
+  | { type: 'loopback'; reqId: number; port: number; request: HttpRequestData }
+  | { type: 'server-ready'; port: number; url: string };
+
+/** The preview-relative URL a virtual server on `port` is reachable at. */
+export function portPath(previewBase: string, port: number): string {
+  return `${previewBase}__port/${port}/`;
+}

package/src/node/worker.ts

@@ -0,0 +1,46 @@
+/**
+ * The process Worker (bundled to dist/node/worker.js): one program per worker,
+ * so a busy loop blocks only itself and `kill` can always terminate it.
+ *
+ * Worker globals are typed locally rather than through `lib.webworker`, which
+ * cannot share a compilation with the DOM lib the rest of the package needs.
+ */
+import { createWorkerProcess } from './workerProcess.js';
+import { createCacheStoragePackageCache } from '../packageCache.js';
+import type { HostToWorker } from './protocol.js';
+
+interface WorkerScope {
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+  addEventListener(type: 'message', listener: (event: { data: HostToWorker }) => void): void;
+  addEventListener(type: 'error', listener: (event: { error: unknown; message: string; preventDefault(): void }) => void): void;
+  addEventListener(type: 'unhandledrejection', listener: (event: { reason: unknown; preventDefault(): void }) => void): void;
+}
+
+const scope = globalThis as unknown as WorkerScope;
+const nativeFetch = globalThis.fetch.bind(globalThis);
+let cache: ReturnType<typeof createCacheStoragePackageCache> | undefined;
+const uncaught = new Set<(error: unknown) => void>();
+
+scope.addEventListener('error', (event) => {
+  if (!uncaught.size) return;
+  event.preventDefault();
+  for (const handler of uncaught) handler(event.error ?? new Error(event.message));
+});
+scope.addEventListener('unhandledrejection', (event) => {
+  if (!uncaught.size) return;
+  event.preventDefault();
+  for (const handler of uncaught) handler(event.reason);
+});
+
+const process = createWorkerProcess({
+  post: (message) => scope.postMessage(message),
+  fetch: (input, init) => nativeFetch(input, init),
+  packageCache: () => (cache ??= createCacheStoragePackageCache()),
+  ownsRealm: true,
+  trapUncaught(handler) {
+    uncaught.add(handler);
+    return () => uncaught.delete(handler);
+  },
+});
+
+scope.addEventListener('message', (event) => process.receive(event.data));

package/src/node/workerProcess.ts

@@ -0,0 +1,219 @@
+/**
+ * The worker side of one process: mirror the file system, build a `System`
+ * whose spawn/listen/loopback are relayed to the page, run the program, and
+ * stream its output back. No worker globals in here — `post` and the message
+ * feed are injected — so the same code runs in a real Worker (worker.ts) and
+ * in-thread in tests.
+ */
+import {
+  VirtualFileSystem,
+  commandNotFound,
+  defaultPrograms,
+  resolveCommand,
+  runProgram,
+  type ChildHandle,
+  type FsChange,
+  type HttpHandler,
+  type HttpResponseData,
+  type PackageCache,
+  type System,
+} from '@seanhogg/builderforce-webcontainers-core';
+import type { FsOp, HostToWorker, StartMessage, WorkerToHost } from './protocol.js';
+import { portPath } from './protocol.js';
+
+export interface WorkerProcessDeps {
+  post(message: WorkerToHost): void;
+  fetch: System['fetch'];
+  packageCache?: () => PackageCache | undefined;
+  /** Register for the realm's uncaught errors (a real worker's `error`/`unhandledrejection`). */
+  trapUncaught?(handler: (error: unknown) => void): () => void;
+  /** This process has the realm to itself (true in a real Worker). */
+  ownsRealm?: boolean;
+}
+
+const EPHEMERAL = 49152;
+
+export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message: HostToWorker): void } {
+  const fs = new VirtualFileSystem();
+  const handlers = new Map<number, HttpHandler>();
+  const knownPorts = new Set<number>();
+  const children = new Map<number, { stdout: Set<(s: string) => void>; stderr: Set<(s: string) => void>; exit: (code: number) => void }>();
+  const loopbacks = new Map<number, (response: HttpResponseData | undefined) => void>();
+  let nextChild = 1;
+  let nextReq = 1;
+  let applying = false;
+  let pending: FsOp[] = [];
+  let flushScheduled = false;
+  let process: ChildHandle | undefined;
+  const programs = defaultPrograms();
+
+  const flush = () => {
+    flushScheduled = false;
+    if (!pending.length) return;
+    const ops = pending;
+    pending = [];
+    deps.post({ type: 'fs', ops });
+  };
+
+  fs.watch((change: FsChange) => {
+    if (applying) return;
+    if (change.type === 'write') pending.push({ op: 'write', path: change.path, content: fs.readFile(change.path)! });
+    else pending.push({ op: change.type, path: change.path });
+    if (!flushScheduled) {
+      flushScheduled = true;
+      queueMicrotask(flush);
+    }
+  });
+
+  const apply = (ops: FsOp[]) => {
+    applying = true;
+    try {
+      for (const op of ops) {
+        if (op.op === 'write') fs.writeFile(op.path, op.content);
+        else if (op.op === 'mkdir') fs.mkdir(op.path);
+        else fs.rm(op.path);
+      }
+    } finally {
+      applying = false;
+    }
+  };
+
+  function remoteChild(command: string, args: string[], options: { cwd?: string; env?: Record<string, string>; terminal?: { cols: number; rows: number } } = {}): ChildHandle {
+    flush(); // the child must see every write made so far
+    const childId = nextChild++;
+    const stdout = new Set<(s: string) => void>();
+    const stderr = new Set<(s: string) => void>();
+    let resolveExit!: (code: number) => void;
+    const exit = new Promise<number>((resolve) => (resolveExit = resolve));
+    children.set(childId, { stdout, stderr, exit: resolveExit });
+    deps.post({ type: 'spawn', childId, command, args, cwd: options.cwd, env: options.env, terminal: options.terminal });
+    return {
+      pid: childId,
+      onStdout: (l) => (stdout.add(l), () => stdout.delete(l)),
+      onStderr: (l) => (stderr.add(l), () => stderr.delete(l)),
+      write: (data) => deps.post({ type: 'child-stdin', childId, data }),
+      closeStdin: () => deps.post({ type: 'child-stdin', childId, data: null }),
+      kill: (signal = 'SIGTERM') => deps.post({ type: 'child-kill', childId, signal }),
+      resize: (cols, rows) => deps.post({ type: 'child-resize', childId, cols, rows }),
+      exit,
+    };
+  }
+
+  function start(message: StartMessage): void {
+    applying = true;
+    for (const dir of message.dirs) fs.mkdir(dir);
+    for (const [path, content] of message.files) fs.writeFile(path, content);
+    applying = false;
+    for (const port of message.ports) knownPorts.add(port);
+
+    const system: System = {
+      fs,
+      fetch: deps.fetch,
+      spawn(command, args, options = {}) {
+        // Resolve here, against the mirror, so a missing command fails synchronously
+        // with ENOENT exactly as it does in-process.
+        const cwd = options.cwd ?? message.cwd;
+        const env = { ...message.env, ...options.env };
+        if (!resolveCommand(fs, programs, command, args, cwd, env)) throw commandNotFound(command);
+        return remoteChild(command, args, { ...options, cwd, env });
+      },
+      listen(port, handler) {
+        let actual = port;
+        if (!actual) for (actual = EPHEMERAL + (message.pid % 1000) * 8; knownPorts.has(actual); actual++);
+        if (knownPorts.has(actual)) throw Object.assign(new Error(`listen EADDRINUSE: address already in use :::${actual}`), { code: 'EADDRINUSE', errno: -98, syscall: 'listen', port: actual });
+        knownPorts.add(actual);
+        handlers.set(actual, handler);
+        deps.post({ type: 'listen', port: actual });
+        return {
+          port: actual,
+          close() {
+            if (handlers.get(actual) !== handler) return;
+            handlers.delete(actual);
+            knownPorts.delete(actual);
+            deps.post({ type: 'unlisten', port: actual });
+          },
+        };
+      },
+      loopback(port, request) {
+        const local = handlers.get(port);
+        if (local) return local(request);
+        const reqId = nextReq++;
+        return new Promise((resolve) => {
+          loopbacks.set(reqId, resolve);
+          deps.post({ type: 'loopback', reqId, port, request });
+        });
+      },
+      serverUrl: (port) => new URL(portPath(message.previewBase, port), message.previewOrigin).href,
+      announceServer: (port, url) => deps.post({ type: 'server-ready', port, url }),
+      previewUrl: message.previewUrl,
+      registry: message.registry,
+      packageCache: message.packageCache ? deps.packageCache?.() : undefined,
+      ownsRealm: deps.ownsRealm,
+      trapUncaught: deps.trapUncaught,
+    };
+
+    const resolved = resolveCommand(fs, programs, message.command, message.args, message.cwd, message.env);
+    if (!resolved) {
+      deps.post({ type: 'stderr', data: `jsh: command not found: ${message.command}\n` });
+      deps.post({ type: 'exit', code: 127 });
+      return;
+    }
+    process = runProgram({ program: resolved.program, args: resolved.args, system, cwd: message.cwd, env: message.env, terminal: message.terminal, pid: message.pid });
+    process.onStdout((data) => deps.post({ type: 'stdout', data }));
+    process.onStderr((data) => deps.post({ type: 'stderr', data }));
+    void process.exit.then((code) => {
+      flush();
+      deps.post({ type: 'exit', code });
+    });
+  }
+
+  return {
+    receive(message) {
+      switch (message.type) {
+        case 'start':
+          return start(message);
+        case 'stdin':
+          if (message.data === null) process?.closeStdin();
+          else process?.write(message.data);
+          return;
+        case 'kill':
+          return process?.kill(message.signal);
+        case 'resize':
+          return process?.resize?.(message.cols, message.rows);
+        case 'fs':
+          return apply(message.ops);
+        case 'ports':
+          for (const port of message.open) knownPorts.add(port);
+          for (const port of message.closed) if (!handlers.has(port)) knownPorts.delete(port);
+          return;
+        case 'child-out':
+          for (const l of children.get(message.childId)?.[message.stream] ?? []) l(message.data);
+          return;
+        case 'child-exit':
+          children.get(message.childId)?.exit(message.code);
+          children.delete(message.childId);
+          return;
+        case 'child-error': {
+          const child = children.get(message.childId);
+          for (const l of child?.stderr ?? []) l(`${message.message}\n`);
+          child?.exit(message.code === 'ENOENT' ? 127 : 1);
+          children.delete(message.childId);
+          return;
+        }
+        case 'http-request': {
+          const handler = handlers.get(message.port);
+          const respond = (response: HttpResponseData) => deps.post({ type: 'http-response', reqId: message.reqId, response });
+          if (!handler) return respond({ status: 502, headers: { 'content-type': 'text/plain' }, body: new TextEncoder().encode(`Nothing is listening on port ${message.port}.`) });
+          void handler(message.request).then(respond, (error: unknown) =>
+            respond({ status: 500, headers: { 'content-type': 'text/plain' }, body: new TextEncoder().encode(String(error instanceof Error ? error.stack : error)) }),
+          );
+          return;
+        }
+        case 'loopback-response':
+          loopbacks.get(message.reqId)?.(message.response ?? undefined);
+          loopbacks.delete(message.reqId);
+          return;
+      }
+    },
+  };
+}

package/src/packageCache.ts

@@ -0,0 +1,28 @@
+import type { PackageCache } from '@seanhogg/builderforce-webcontainers-core';
+
+/**
+ * The installer's cache backed by Cache Storage, so a second `npm install` (or a
+ * reload) reuses tarballs instead of downloading them again. Cache Storage keys
+ * must be http(s) requests, so each key is folded into a URL on a reserved
+ * `.invalid` host that can never be fetched for real.
+ *
+ * Falls back to a no-op cache where Cache Storage is unavailable (an insecure
+ * context, or a browser that blocks it in private mode).
+ */
+export function createCacheStoragePackageCache(name = 'bfwc-packages'): PackageCache {
+  const storage = (globalThis as { caches?: CacheStorage }).caches;
+  if (!storage) return { get: async () => undefined, put: async () => undefined };
+  let opened: Promise<Cache | undefined> | undefined;
+  const open = () => (opened ??= storage.open(name).catch(() => undefined));
+  const keyUrl = (key: string) => `https://bfwc-cache.invalid/${encodeURIComponent(key)}`;
+  return {
+    async get(key) {
+      const response = await (await open())?.match(keyUrl(key)).catch(() => undefined);
+      return response ? new Uint8Array(await response.arrayBuffer()) : undefined;
+    },
+    async put(key, data) {
+      const body = data.slice().buffer as ArrayBuffer;
+      await (await open())?.put(keyUrl(key), new Response(body)).catch(() => undefined); // quota errors just skip caching
+    },
+  };
+}