@seanhogg/builderforce-webcontainers 2026.10.6 → 2026.10.8

package/src/index.ts

@@ -5,17 +5,22 @@ export type {
   RelayOptions,
   CommonRuntimeOptions,
   PreviewRuntime,
-  PreviewError,
   RuntimeBuildOptions,
 } from './host.js';
+export { listenToPreview } from './previewMessages.js';
+export { createSnapshotStore } from './snapshotStore.js';
+export type { SnapshotStore, SnapshotStoreOptions } from './snapshotStore.js';
+export type { PreviewError, PreviewConsoleMessage, ConsoleLevel, PreviewMessages } from './previewMessages.js';
+export { listenToPreviewBridge } from './previewBridge.js';
+export type { PreviewBridge, PreviewBridgeOptions, BridgePort } from './previewBridge.js';
 export type { PreviewTransport } from './transport.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 { ProcessHost, createWorkerProcess, servePortRequest, createPortResponder, openPortResponse, injectBridge } from './node/index.js';
+export type { NodeRuntimeOptions, ProcessHostOptions, ProcessInfo, WorkerLike, PortResponder, PortResponderOptions, OpenedPortResponse } from './node/index.js';
 export { createSwRouter } from './swRouter.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';

package/src/node/index.ts

@@ -1,15 +1,16 @@
 /**
  * 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.
+ * virtual server listening on that port (portResponder.ts).
  */
-import { parsePortPath, type VirtualFileSystem } from '@seanhogg/builderforce-webcontainers-core';
-import type { WireRequest, WireResponse } from '../protocol.js';
+import type { VirtualFileSystem } from '@seanhogg/builderforce-webcontainers-core';
 import { ProcessHost, type WorkerLike } from './processHost.js';
 
 export { ProcessHost } from './processHost.js';
-export type { ProcessHostOptions, WorkerLike } from './processHost.js';
+export type { ProcessHostOptions, ProcessInfo, WorkerLike } from './processHost.js';
 export { createWorkerProcess } from './workerProcess.js';
+export { servePortRequest, createPortResponder, openPortResponse, injectBridge } from './portResponder.js';
+export type { PortResponder, PortResponderOptions, OpenedPortResponse } from './portResponder.js';
 
 export interface NodeRuntimeOptions {
   /**
@@ -47,23 +48,3 @@ export function createProcessHost(args: { fs: VirtualFileSystem; base: string; o
     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/portResponder.ts

@@ -0,0 +1,175 @@
+/**
+ * Answering preview requests addressed to virtual servers (`/__port/<n>/…`).
+ * The request reaches the server carrying the cookies the host holds for that
+ * port; the response streams back to the service worker as the server writes
+ * it (head, then `chunk` messages, then `end`); its `Set-Cookie`s go into the
+ * jar (a service worker could not set them); and an HTML page gets the preview
+ * bridge — the WebSocket shim and `document.cookie` — injected after `<head>`.
+ */
+import {
+  bridgeInsertionPoint,
+  drainBody,
+  errorBridgeScript,
+  scriptTag,
+  parsePortPath,
+  previewCookieScript,
+  previewSocketScript,
+  readBody,
+  textResponse,
+  type CookieJar,
+  type PortCookieJars,
+} from '@seanhogg/builderforce-webcontainers-core';
+import type { WireReply, WireRequest, WireResponse } from '../protocol.js';
+import type { ProcessHost } from './processHost.js';
+
+export interface PortResponderOptions {
+  /** The runtime's cookie jars. Without them, the browser's own `Cookie` header passes through and `Set-Cookie` is lost. */
+  cookies?: PortCookieJars;
+  /** Inject the preview bridge (errors and console to the host, WebSocket shim, `document.cookie`) into HTML pages. Default true. */
+  bridge?: boolean;
+  /** The host's preview scripts, read per page so `setPreviewScripts` applies to virtual servers too. */
+  scripts?: () => readonly string[];
+}
+
+export interface OpenedPortResponse {
+  status: number;
+  /** Flattened for a `Response` (`Set-Cookie` removed — it went to the jar). */
+  headers: Record<string, string>;
+  body: ReadableStream<Uint8Array>;
+}
+
+const NO_STORE = { 'cache-control': 'no-store' };
+
+function headerKey(headers: Record<string, unknown>, name: string): string | undefined {
+  return Object.keys(headers).find((key) => key.toLowerCase() === name);
+}
+
+/** Send a preview request to its virtual server; resolves with the head and a body that streams. */
+export async function openPortResponse(host: ProcessHost, request: WireRequest, options: PortResponderOptions = {}): Promise<OpenedPortResponse> {
+  const target = parsePortPath(request.path)!;
+  const jar = options.cookies?.jar(target.port);
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(request.headers ?? {})) if (!jar || key.toLowerCase() !== 'cookie') headers[key] = value;
+  const cookie = jar?.header(target.path);
+  if (cookie) headers.cookie = cookie;
+  const response =
+    (await host.requestStream(target.port, { method: request.method ?? 'GET', url: target.path + request.search, headers, body: request.body ? new Uint8Array(request.body) : null })) ??
+    textResponse(502, `Nothing is listening on port ${target.port}. Start a server (node server.js) first.`);
+
+  const out: Record<string, string> = {};
+  const setCookies: string[] = [];
+  for (const [key, value] of Object.entries(response.headers)) {
+    if (key.toLowerCase() === 'set-cookie') setCookies.push(...(Array.isArray(value) ? value : [value]));
+    else out[key] = Array.isArray(value) ? value.join(', ') : String(value);
+  }
+  if (response.status === 502 && !headerKey(out, 'cache-control')) Object.assign(out, NO_STORE);
+  jar?.store(setCookies, target.path);
+
+  let body = response.body;
+  const type = headerKey(out, 'content-type');
+  // A compressed body cannot be edited in flight; such a page goes without the bridge.
+  const hasBody = request.method !== 'HEAD' && response.status !== 204 && response.status !== 304;
+  if (options.bridge !== false && hasBody && type && /^\s*text\/html/i.test(out[type]!) && !headerKey(out, 'content-encoding')) {
+    body = injectBridge(body, bridgeFor(jar, target.path, options.scripts?.() ?? []));
+    const length = headerKey(out, 'content-length');
+    if (length) delete out[length];
+    // The bridge pushes a `<meta charset>` past the 1,024-byte prescan; say it in the header instead.
+    if (!/charset=/i.test(out[type]!)) out[type] = `${out[type]}; charset=utf-8`;
+  }
+  return { status: response.status, headers: out, body };
+}
+
+/** The same bridge a dev-server page gets (errors, console, sockets), plus cookies and the host's scripts. */
+function bridgeFor(jar: CookieJar | undefined, path: string, scripts: readonly string[]): string {
+  return [errorBridgeScript(), previewSocketScript(), jar ? previewCookieScript(jar.documentCookie(path)) : '', ...scripts.map(scriptTag)].join('');
+}
+
+/** Insert `script` into a streamed document, after `<head>` (see `bridgeInsertionPoint`), passing the rest through as it arrives. */
+export function injectBridge(body: ReadableStream<Uint8Array>, script: string): ReadableStream<Uint8Array> {
+  // windows-1252 maps every byte to one UTF-16 unit, so string indices are byte offsets.
+  const latin1 = new TextDecoder('latin1');
+  const bridge = new TextEncoder().encode(script);
+  let held = new Uint8Array(0);
+  let injected = false;
+  const tryInject = (controller: TransformStreamDefaultController<Uint8Array>, complete: boolean) => {
+    const at = bridgeInsertionPoint(latin1.decode(held), complete);
+    if (at === undefined) return;
+    if (at) controller.enqueue(held.subarray(0, at));
+    controller.enqueue(bridge);
+    if (at < held.byteLength) controller.enqueue(held.subarray(at));
+    held = new Uint8Array(0);
+    injected = true;
+  };
+  return body.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        if (injected) return controller.enqueue(chunk);
+        const joined = new Uint8Array(held.byteLength + chunk.byteLength);
+        joined.set(held);
+        joined.set(chunk, held.byteLength);
+        held = joined;
+        tryInject(controller, false);
+      },
+      flush(controller) {
+        if (!injected) tryInject(controller, true);
+      },
+    }),
+  );
+}
+
+/** A transferable copy of a chunk. */
+const transferable = (data: Uint8Array) => new Uint8Array(data).buffer as ArrayBuffer;
+
+/** Answer a preview request with the whole body (tests, simple hosts). The preview path streams instead: {@link createPortResponder}. */
+export async function servePortRequest(host: ProcessHost, request: WireRequest, options?: PortResponderOptions): Promise<{ message: WireResponse; transfer: Transferable[] }> {
+  const opened = await openPortResponse(host, request, options);
+  const body = transferable(await readBody(opened.body));
+  return { message: { type: 'response', reqId: request.reqId, status: opened.status, headers: opened.headers, body }, transfer: [body] };
+}
+
+export interface PortResponder {
+  /** Answer one preview request: post the head, then the body chunk by chunk as the server writes it. */
+  serve(request: WireRequest, post: (reply: WireReply, transfer: Transferable[]) => void): Promise<void>;
+  /** The preview stopped reading `reqId`: hang up on the server. */
+  cancel(reqId: number): void;
+  /** Hang up on every response still streaming. */
+  dispose(): void;
+}
+
+/** One per service-worker channel (request ids are unique within a channel). */
+export function createPortResponder(host: ProcessHost, options?: PortResponderOptions): PortResponder {
+  const streaming = new Map<number, () => void>();
+  return {
+    async serve(request, post) {
+      const { reqId } = request;
+      let opened: OpenedPortResponse;
+      try {
+        opened = await openPortResponse(host, request, options);
+      } catch (error) {
+        return post({ type: 'response', reqId, status: 500, headers: { 'content-type': 'text/plain; charset=utf-8', ...NO_STORE }, body: String(error instanceof Error ? error.message : error) }, []);
+      }
+      post({ type: 'response', reqId, status: opened.status, headers: opened.headers, body: null, streaming: true }, []);
+      streaming.set(
+        reqId,
+        drainBody(opened.body, {
+          chunk(data) {
+            const buffer = transferable(data);
+            post({ type: 'chunk', reqId, data: buffer }, [buffer]);
+          },
+          end(error) {
+            streaming.delete(reqId);
+            post(error ? { type: 'end', reqId, error } : { type: 'end', reqId }, []);
+          },
+        }),
+      );
+    },
+    cancel(reqId) {
+      streaming.get(reqId)?.();
+      streaming.delete(reqId);
+    },
+    dispose() {
+      for (const stop of streaming.values()) stop();
+      streaming.clear();
+    },
+  };
+}

package/src/node/processHost.ts

@@ -5,6 +5,10 @@
  * 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.
+ *
+ * Responses from a worker's servers stream through here chunk by chunk (see
+ * responseWire.ts), and upgraded connections (WebSockets) are relayed as raw
+ * bytes between the client end the caller holds and the server's worker.
  */
 import {
   DEFAULT_ENV,
@@ -12,17 +16,21 @@ import {
   ServerEvents,
   allocatePid,
   runArguments,
+  textResponse,
   toRuntimeProcess,
+  type ByteChannel,
   type ChildHandle,
   type FsChange,
   type HttpRequestData,
   type HttpResponseData,
+  type HttpStreamResponse,
   type ProcessOptions,
   type RuntimeProcess,
   type VirtualFileSystem,
 } from '@seanhogg/builderforce-webcontainers-core';
 import type { FsOp, HostToWorker, WorkerToHost } from './protocol.js';
 import { portPath } from './protocol.js';
+import { ResponseReceiver, sendResponse } from './responseWire.js';
 
 /** The part of `Worker` the host uses — a real Worker, or an in-thread fake in tests. */
 export interface WorkerLike {
@@ -50,8 +58,21 @@ export interface ProcessHostOptions {
 
 const SIGNAL_CODES: Record<string, number> = { SIGINT: 130, SIGTERM: 143, SIGKILL: 137, SIGHUP: 129 };
 
+/** A running process, as `listProcesses()` reports it. */
+export interface ProcessInfo {
+  pid: number;
+  command: string;
+  args: string[];
+  cwd: string;
+  /** Epoch ms. */
+  startedAt: number;
+  /** Ports its servers listen on. */
+  ports: number[];
+}
+
 interface Proc {
   pid: number;
+  info: Omit<ProcessInfo, 'ports'>;
   worker: WorkerLike;
   stdout: Set<(chunk: string) => void>;
   stderr: Set<(chunk: string) => void>;
@@ -59,10 +80,17 @@ interface Proc {
   resolveExit(code: number): void;
   registrations: Map<number, { close(): void }>;
   children: Map<number, ChildHandle>;
-  pendingHttp: Map<number, (response: HttpResponseData) => void>;
+  /** Responses its servers are streaming back to requests forwarded here. */
+  responses: ResponseReceiver;
+  /** Its loopback requests being answered, by the worker's request id: cancel functions. */
+  loopbacks: Map<number, () => void>;
+  /** Upgraded connections to its servers: the page-side end of each, by connection id. */
+  sockets: Map<number, ByteChannel>;
   outbox: FsOp[];
 }
 
+const EXITED = 'The server process exited.';
+
 export class ProcessHost {
   readonly ports = new PortRegistry();
   /** Servers listening, ports opening and closing. */
@@ -71,6 +99,7 @@ export class ProcessHost {
   private applyingFrom?: Proc;
   private flushScheduled = false;
   private nextReq = 1;
+  private nextConn = 1;
   private readonly unwatch: () => void;
   private readonly stopPorts: () => void;
 
@@ -102,6 +131,7 @@ export class ProcessHost {
     const exit = new Promise<number>((resolve) => (resolveExit = resolve));
     const proc: Proc = {
       pid,
+      info: { pid, command, args: [...args], cwd: options.cwd ?? '/', startedAt: Date.now() },
       worker,
       stdout: new Set(),
       stderr: new Set(),
@@ -114,7 +144,9 @@ export class ProcessHost {
       },
       registrations: new Map(),
       children: new Map(),
-      pendingHttp: new Map(),
+      responses: new ResponseReceiver(),
+      loopbacks: new Map(),
+      sockets: new Map(),
       outbox: [],
     };
     this.procs.add(proc);
@@ -154,11 +186,26 @@ export class ProcessHost {
     };
   }
 
-  /** Dispatch an HTTP request to the server on `port` (the preview service worker's `/__port/<port>/` path). */
+  /** Every process still running, oldest first — children started by a shell included. */
+  list(): ProcessInfo[] {
+    return [...this.procs].map((proc) => ({ ...proc.info, args: [...proc.info.args], ports: [...proc.registrations.keys()] }));
+  }
+
+  /** Dispatch an HTTP request to the server on `port` and wait for the whole response. */
   request(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined> {
+    return this.ports.requestBuffered(port, request);
+  }
+
+  /** Dispatch an HTTP request to the server on `port` (the preview's `/__port/<port>/` path); resolves at the head, the body streaming. */
+  requestStream(port: number, request: HttpRequestData): Promise<HttpStreamResponse | undefined> {
     return this.ports.request(port, request);
   }
 
+  /** Open an upgraded connection (a WebSocket) to the server on `port`; returns the client end. */
+  upgrade(port: number, request: HttpRequestData): ByteChannel | undefined {
+    return this.ports.upgrade(port, request);
+  }
+
   dispose(): void {
     for (const proc of [...this.procs]) {
       proc.worker.terminate();
@@ -187,8 +234,11 @@ export class ProcessHost {
   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();
+    proc.responses.abort(() => textResponse(502, EXITED), EXITED);
+    for (const cancel of [...proc.loopbacks.values()]) cancel();
+    proc.loopbacks.clear();
+    for (const socket of proc.sockets.values()) socket.close();
+    proc.sockets.clear();
     this.procs.delete(proc);
     queueMicrotask(() => proc.worker.terminate());
   }
@@ -268,7 +318,11 @@ export class ProcessHost {
         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));
+          const registration = this.ports.listen(
+            message.port,
+            (request) => this.forward(proc, message.port, request),
+            (request, socket) => this.forwardUpgrade(proc, message.port, request, socket),
+          );
           proc.registrations.set(message.port, registration);
         } catch (error) {
           for (const l of proc.stderr) l(`${(error as Error).message}\n`);
@@ -279,12 +333,23 @@ export class ProcessHost {
         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);
+      case 'response-head':
+      case 'response-chunk':
+      case 'response-end':
+        return proc.responses.receive(message);
+      case 'loopback': {
+        const { reqId } = message;
+        const cancel = sendResponse((reply) => this.post(proc, reply), reqId, this.ports.request(message.port, message.request), () => proc.loopbacks.delete(reqId));
+        proc.loopbacks.set(reqId, cancel);
         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 }));
+      }
+      case 'request-cancel':
+        return proc.loopbacks.get(message.reqId)?.();
+      case 'socket-data':
+        return proc.sockets.get(message.connId)?.send(message.data);
+      case 'socket-close':
+        proc.sockets.get(message.connId)?.close();
+        proc.sockets.delete(message.connId);
         return;
       case 'listening':
         this.servers.announce({ port: message.port, url: message.url });
@@ -292,11 +357,23 @@ export class ProcessHost {
     }
   }
 
-  private forward(proc: Proc, port: number, request: HttpRequestData): Promise<HttpResponseData> {
+  private async forward(proc: Proc, port: number, request: HttpRequestData): Promise<HttpStreamResponse> {
+    if (proc.exited) return textResponse(502, EXITED);
     const reqId = this.nextReq++;
-    return new Promise((resolve) => {
-      proc.pendingHttp.set(reqId, resolve);
-      this.post(proc, { type: 'http-request', reqId, port, request });
+    const response = proc.responses.expect(reqId, () => this.post(proc, { type: 'request-cancel', reqId }));
+    this.post(proc, { type: 'http-request', reqId, port, request });
+    return (await response) ?? textResponse(502, `Nothing is listening on port ${port}.`);
+  }
+
+  /** Relay an upgraded connection: `socket` is the server end; its bytes go to the worker, and the worker's come back. */
+  private forwardUpgrade(proc: Proc, port: number, request: HttpRequestData, socket: ByteChannel): void {
+    if (proc.exited) return socket.close();
+    const connId = this.nextConn++;
+    proc.sockets.set(connId, socket);
+    socket.onData((data) => this.post(proc, { type: 'socket-data', connId, data }));
+    socket.onClose(() => {
+      if (proc.sockets.delete(connId)) this.post(proc, { type: 'socket-close', connId });
     });
+    this.post(proc, { type: 'socket-open', connId, port, request });
   }
 }

package/src/node/protocol.ts

@@ -2,8 +2,15 @@
  * 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.
+ *
+ * HTTP responses stream in both directions with the same three messages: a
+ * `response-head`, `response-chunk`s as the server writes, a `response-end`.
+ * Worker → page they answer an `http-request` (ids the page allocated); page →
+ * worker they answer a `loopback` (ids the worker allocated). `request-cancel`
+ * goes the other way: the reader hung up. Upgraded connections (WebSockets)
+ * are opened by the page (`socket-open`) and carry raw bytes both ways.
  */
-import type { FileContent, HttpRequestData, HttpResponseData } from '@seanhogg/builderforce-webcontainers-core';
+import type { FileContent, HttpRequestData, HttpResponseHead } from '@seanhogg/builderforce-webcontainers-core';
 
 export type FsOp = { op: 'write'; path: string; content: FileContent } | { op: 'remove'; path: string } | { op: 'mkdir'; path: string };
 
@@ -28,6 +35,15 @@ export interface StartMessage {
   packageCache: boolean;
 }
 
+/** A streamed response, chunk by chunk; `head: null` means nothing listens on that port (loopback only). */
+export type ResponseMessage =
+  | { type: 'response-head'; reqId: number; head: HttpResponseHead | null }
+  | { type: 'response-chunk'; reqId: number; data: Uint8Array }
+  | { type: 'response-end'; reqId: number; error?: string };
+
+/** Raw bytes of an upgraded connection, either way; ids allocated by the page. */
+export type SocketMessage = { type: 'socket-data'; connId: number; data: Uint8Array } | { type: 'socket-close'; connId: number };
+
 /** page → worker */
 export type HostToWorker =
   | StartMessage
@@ -40,7 +56,10 @@ export type HostToWorker =
   | { 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 };
+  | { type: 'request-cancel'; reqId: number }
+  | { type: 'socket-open'; connId: number; port: number; request: HttpRequestData }
+  | ResponseMessage
+  | SocketMessage;
 
 /** worker → page */
 export type WorkerToHost =
@@ -53,9 +72,11 @@ export type WorkerToHost =
   | { 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: 'listening'; port: number; url: string };
+  | { type: 'request-cancel'; reqId: number }
+  | { type: 'listening'; port: number; url: string }
+  | ResponseMessage
+  | SocketMessage;
 
 /** The preview-relative URL a virtual server on `port` is reachable at. */
 export function portPath(previewBase: string, port: number): string {

package/src/node/responseWire.ts

@@ -0,0 +1,97 @@
+/**
+ * Streamed HTTP responses over postMessage, used on both sides of the
+ * page ↔ process-worker boundary: the side that holds a response sends it as
+ * head / chunk / end messages as the server writes it, and the side that asked
+ * rebuilds an `HttpStreamResponse` whose body stream is fed by them. A reader
+ * that cancels the body sends `request-cancel` back, so the server hears the
+ * client hang up.
+ */
+import { drainBody, headOf, pushStream, type HttpStreamResponse, type PushStream } from '@seanhogg/builderforce-webcontainers-core';
+import type { ResponseMessage } from './protocol.js';
+
+const encoder = new TextEncoder();
+
+/**
+ * Send `response` as messages once it resolves (`undefined`: nothing listens).
+ * A rejected handler becomes a 500 carrying the error. Returns a cancel for
+ * when the requester hangs up; `onDone` runs once, when the exchange is over.
+ */
+export function sendResponse(post: (message: ResponseMessage) => void, reqId: number, response: Promise<HttpStreamResponse | undefined>, onDone?: () => void): () => void {
+  let finished = false;
+  let stop: (() => void) | undefined;
+  const done = () => {
+    if (finished) return;
+    finished = true;
+    onDone?.();
+  };
+  response.then(
+    (res) => {
+      if (finished) return void res?.body.cancel().catch(() => undefined);
+      if (!res) {
+        post({ type: 'response-head', reqId, head: null });
+        return done();
+      }
+      post({ type: 'response-head', reqId, head: headOf(res) });
+      stop = drainBody(res.body, {
+        chunk: (data) => post({ type: 'response-chunk', reqId, data }),
+        end: (error) => {
+          post(error ? { type: 'response-end', reqId, error } : { type: 'response-end', reqId });
+          done();
+        },
+      });
+    },
+    (error: unknown) => {
+      if (finished) return;
+      post({ type: 'response-head', reqId, head: { status: 500, headers: { 'content-type': 'text/plain' } } });
+      post({ type: 'response-chunk', reqId, data: encoder.encode(String(error instanceof Error ? error.stack : error)) });
+      post({ type: 'response-end', reqId });
+      done();
+    },
+  );
+  return () => {
+    stop?.();
+    done();
+  };
+}
+
+/** Rebuilds streamed responses from the messages answering requests this side sent. */
+export class ResponseReceiver {
+  private readonly heads = new Map<number, { resolve(response: HttpStreamResponse | undefined): void; cancel(): void }>();
+  private readonly bodies = new Map<number, PushStream>();
+
+  /** The response to request `reqId`; `cancel` runs if its reader hangs up before the end. */
+  expect(reqId: number, cancel: () => void): Promise<HttpStreamResponse | undefined> {
+    return new Promise((resolve) => this.heads.set(reqId, { resolve, cancel }));
+  }
+
+  receive(message: ResponseMessage): void {
+    const { reqId } = message;
+    if (message.type === 'response-head') {
+      const waiting = this.heads.get(reqId);
+      this.heads.delete(reqId);
+      if (!waiting) return;
+      if (!message.head) return waiting.resolve(undefined);
+      const body = pushStream(() => {
+        this.bodies.delete(reqId);
+        waiting.cancel();
+      });
+      this.bodies.set(reqId, body);
+      waiting.resolve({ ...message.head, body: body.stream });
+    } else if (message.type === 'response-chunk') {
+      this.bodies.get(reqId)?.push(message.data);
+    } else {
+      const body = this.bodies.get(reqId);
+      this.bodies.delete(reqId);
+      if (message.error) body?.fail(new Error(message.error));
+      else body?.end();
+    }
+  }
+
+  /** The other side is gone: waiting requests get `fallback`, bodies in flight break off with `reason`. */
+  abort(fallback: () => HttpStreamResponse | undefined, reason: string): void {
+    for (const { resolve } of this.heads.values()) resolve(fallback());
+    this.heads.clear();
+    for (const body of this.bodies.values()) body.fail(new Error(reason));
+    this.bodies.clear();
+  }
+}