@seanhogg/builderforce-webcontainers 2026.10.6 → 2026.10.8

package/src/node/workerProcess.ts

@@ -1,25 +1,31 @@
 /**
  * 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
+ * stream its output back. Its servers' responses stream to the page as they
+ * are written, and connections the page upgrades reach the server's `upgrade`
+ * handler as a byte pipe. 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,
+  createChannelPair,
   defaultPrograms,
   resolveCommand,
   runProgram,
+  textResponse,
+  type ByteChannel,
   type ChildHandle,
   type FsChange,
   type HttpHandler,
-  type HttpResponseData,
   type PackageCache,
   type System,
+  type UpgradeHandler,
 } from '@seanhogg/builderforce-webcontainers-core';
 import type { FsOp, HostToWorker, StartMessage, WorkerToHost } from './protocol.js';
 import { portPath } from './protocol.js';
+import { ResponseReceiver, sendResponse } from './responseWire.js';
 
 export interface WorkerProcessDeps {
   post(message: WorkerToHost): void;
@@ -35,10 +41,15 @@ const EPHEMERAL = 49152;
 
 export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message: HostToWorker): void } {
   const fs = new VirtualFileSystem();
-  const handlers = new Map<number, HttpHandler>();
+  const handlers = new Map<number, { handler: HttpHandler; upgrade?: UpgradeHandler }>();
   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>();
+  /** Responses to this process's loopback requests, streaming in from the page. */
+  const loopbacks = new ResponseReceiver();
+  /** Responses this process's servers are streaming to the page, by the page's request id. */
+  const serving = new Map<number, () => void>();
+  /** Upgraded connections the page opened, by its connection id (our end of the pipe to the server). */
+  const sockets = new Map<number, ByteChannel>();
   let nextChild = 1;
   let nextReq = 1;
   let applying = false;
@@ -117,17 +128,18 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
         if (!resolveCommand(fs, programs, command, args, cwd, env)) throw commandNotFound(command);
         return remoteChild(command, args, { ...options, cwd, env });
       },
-      listen(port, handler) {
+      listen(port, handler, upgrade) {
         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);
+        const entry = { handler, upgrade };
+        handlers.set(actual, entry);
         deps.post({ type: 'listen', port: actual });
         return {
           port: actual,
           close() {
-            if (handlers.get(actual) !== handler) return;
+            if (handlers.get(actual) !== entry) return;
             handlers.delete(actual);
             knownPorts.delete(actual);
             deps.post({ type: 'unlisten', port: actual });
@@ -136,12 +148,11 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
       },
       loopback(port, request) {
         const local = handlers.get(port);
-        if (local) return local(request);
+        if (local) return local.handler(request);
         const reqId = nextReq++;
-        return new Promise((resolve) => {
-          loopbacks.set(reqId, resolve);
-          deps.post({ type: 'loopback', reqId, port, request });
-        });
+        const response = loopbacks.expect(reqId, () => deps.post({ type: 'request-cancel', reqId }));
+        deps.post({ type: 'loopback', reqId, port, request });
+        return response;
       },
       serverUrl: (port) => new URL(portPath(message.previewBase, port), message.previewOrigin).href,
       announceServer: (port, url) => deps.post({ type: 'listening', port, url }),
@@ -201,17 +212,37 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
           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)) }),
-          );
+          const { reqId } = message;
+          const entry = handlers.get(message.port);
+          const response = entry ? entry.handler(message.request) : Promise.resolve(textResponse(502, `Nothing is listening on port ${message.port}.`));
+          serving.set(reqId, sendResponse(deps.post, reqId, response, () => serving.delete(reqId)));
           return;
         }
-        case 'loopback-response':
-          loopbacks.get(message.reqId)?.(message.response ?? undefined);
-          loopbacks.delete(message.reqId);
+        case 'request-cancel':
+          return serving.get(message.reqId)?.();
+        case 'response-head':
+        case 'response-chunk':
+        case 'response-end':
+          return loopbacks.receive(message);
+        case 'socket-open': {
+          const { connId } = message;
+          const upgrade = handlers.get(message.port)?.upgrade;
+          if (!upgrade) return deps.post({ type: 'socket-close', connId });
+          const [ours, server] = createChannelPair();
+          sockets.set(connId, ours);
+          ours.onData((data) => deps.post({ type: 'socket-data', connId, data }));
+          ours.onClose(() => {
+            sockets.delete(connId);
+            deps.post({ type: 'socket-close', connId });
+          });
+          upgrade(message.request, server);
+          return;
+        }
+        case 'socket-data':
+          return sockets.get(message.connId)?.send(message.data);
+        case 'socket-close':
+          sockets.get(message.connId)?.close();
+          sockets.delete(message.connId);
           return;
       }
     },

package/src/previewBridge.ts

@@ -0,0 +1,148 @@
+/**
+ * The host end of the preview bridge (see core's previewBridge.ts for the page
+ * end). A service worker cannot carry a WebSocket or set a cookie, so preview
+ * pages ask this page instead, each over a MessagePort they transfer:
+ *
+ *   • `SOCKET_MESSAGE_TYPE` — connect a WebSocket to the virtual server on a
+ *     port. The handshake and frames run over an upgraded connection to the
+ *     server (`connectWebSocket` over `ProcessHost.upgrade`), carrying the
+ *     preview's cookies for that port; messages relay both ways on the port.
+ *   • `COOKIE_MESSAGE_TYPE` — keep a virtual-server page's `document.cookie`
+ *     in step with the jar, and store what the page assigns.
+ *
+ * One window listener per runtime, accepting only messages from the preview
+ * origin whose page sits under this runtime's base (as `listenToPreview` does).
+ */
+import {
+  COOKIE_MESSAGE_TYPE,
+  SOCKET_MESSAGE_TYPE,
+  connectWebSocket,
+  parsePortPath,
+  type ByteChannel,
+  type HttpRequestData,
+  type PortCookieJars,
+  type WebSocketConnection,
+} from '@seanhogg/builderforce-webcontainers-core';
+import { previewPageOf } from './previewMessages.js';
+
+export interface PreviewBridgeOptions {
+  /** Open an upgraded connection to the server on `port` (`ProcessHost.upgrade`). */
+  upgrade(port: number, request: HttpRequestData): ByteChannel | undefined;
+  /** The runtime's cookie jars: sent with WebSocket handshakes and mirrored into `document.cookie`. */
+  cookies?: PortCookieJars;
+}
+
+/** The slice of MessagePort the bridge uses. */
+export interface BridgePort {
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  close(): void;
+}
+
+export interface PreviewBridge {
+  /** WebSockets currently open through the bridge. */
+  readonly openSockets: number;
+  dispose(): void;
+}
+
+/** Pages kept in sync per server port; older ones (navigated away, never said so) are dropped past this. */
+const COOKIE_PAGES_PER_PORT = 50;
+
+interface BridgeMessage {
+  type?: unknown;
+  href?: unknown;
+  port?: unknown;
+  path?: unknown;
+  protocols?: unknown;
+}
+
+export function listenToPreviewBridge(
+  target: Pick<Window, 'addEventListener' | 'removeEventListener'>,
+  origin: string,
+  base: string,
+  options: PreviewBridgeOptions,
+): PreviewBridge {
+  const sockets = new Set<WebSocketConnection>();
+  const cookiePages = new Map<number, Array<{ port: BridgePort; path: string }>>();
+
+  function openSocket(channel: BridgePort, data: BridgeMessage, page: URL): void {
+    const port = Number(data.port);
+    const path = typeof data.path === 'string' && data.path.startsWith('/') ? data.path : undefined;
+    const protocols = Array.isArray(data.protocols) ? data.protocols.filter((p): p is string => typeof p === 'string') : [];
+    if (!Number.isInteger(port) || port < 1 || port > 65535 || !path) {
+      channel.postMessage({ kind: 'close', code: 1006, reason: '', wasClean: false });
+      return channel.close();
+    }
+    const headers: Record<string, string> = { host: `localhost:${port}`, origin: page.origin };
+    const cookie = options.cookies?.jar(port).header(path);
+    if (cookie) headers.cookie = cookie;
+    if (typeof navigator !== 'undefined' && navigator.userAgent) headers['user-agent'] = navigator.userAgent;
+    const connection = connectWebSocket((request) => options.upgrade(port, request), { path, protocols, headers });
+    sockets.add(connection);
+    connection.onOpen(({ protocol }) => channel.postMessage({ kind: 'open', protocol }));
+    connection.onMessage((message) => {
+      if (typeof message === 'string') return channel.postMessage({ kind: 'message', data: message });
+      const buffer = new Uint8Array(message).buffer as ArrayBuffer;
+      channel.postMessage({ kind: 'message', data: buffer }, [buffer]);
+    });
+    connection.onClose((info) => {
+      sockets.delete(connection);
+      channel.postMessage({ kind: 'close', ...info });
+      channel.close();
+    });
+    channel.onmessage = (event) => {
+      const message = event.data as { kind?: unknown; data?: unknown; code?: unknown; reason?: unknown } | null;
+      if (message?.kind === 'send') {
+        if (typeof message.data === 'string') connection.send(message.data);
+        else if (message.data instanceof ArrayBuffer) connection.send(new Uint8Array(message.data));
+      } else if (message?.kind === 'close') {
+        connection.close(typeof message.code === 'number' ? message.code : undefined, typeof message.reason === 'string' ? message.reason : undefined);
+      }
+    };
+  }
+
+  function syncCookies(channel: BridgePort, page: URL): void {
+    const cookies = options.cookies;
+    const server = parsePortPath(page.pathname.slice(base.length - 1));
+    if (!cookies || !server) return channel.close();
+    const pages = cookiePages.get(server.port) ?? [];
+    pages.push({ port: channel, path: server.path });
+    if (pages.length > COOKIE_PAGES_PER_PORT) pages.shift()?.port.close();
+    cookiePages.set(server.port, pages);
+    channel.onmessage = (event) => {
+      const message = event.data as { kind?: unknown; value?: unknown } | null;
+      if (message?.kind === 'set-cookie' && typeof message.value === 'string') cookies.jar(server.port).setFromDocument(message.value, server.path);
+    };
+    // The page started from the jar as it was when served; catch up on anything since.
+    channel.postMessage({ kind: 'cookies', value: cookies.jar(server.port).documentCookie(server.path) });
+  }
+
+  const stopCookies = options.cookies?.onChange((port) => {
+    const jar = options.cookies!.jar(port);
+    for (const page of cookiePages.get(port) ?? []) page.port.postMessage({ kind: 'cookies', value: jar.documentCookie(page.path) });
+  });
+
+  const onMessage = (event: MessageEvent) => {
+    const data = event.data as BridgeMessage | null;
+    const channel = event.ports?.[0] as BridgePort | undefined;
+    const page = channel && data ? previewPageOf(event, origin, base) : undefined;
+    if (!page) return;
+    if (data!.type === SOCKET_MESSAGE_TYPE) openSocket(channel!, data!, page);
+    else if (data!.type === COOKIE_MESSAGE_TYPE) syncCookies(channel!, page);
+  };
+  target.addEventListener('message', onMessage as EventListener);
+
+  return {
+    get openSockets() {
+      return sockets.size;
+    },
+    dispose() {
+      target.removeEventListener('message', onMessage as EventListener);
+      stopCookies?.();
+      for (const connection of [...sockets]) connection.close(1001, 'The runtime stopped.');
+      sockets.clear();
+      for (const pages of cookiePages.values()) for (const page of pages) page.port.close();
+      cookiePages.clear();
+    },
+  };
+}

package/src/previewMessages.ts

@@ -0,0 +1,79 @@
+/**
+ * What a preview reports to the host page: uncaught errors and console output,
+ * posted by the bridge script every served page starts with. One window
+ * listener per runtime, accepting only messages from the preview origin whose
+ * page sits under this runtime's base, so two runtimes on one page never hear
+ * each other's previews.
+ */
+import { CONSOLE_MESSAGE_TYPE, ERROR_MESSAGE_TYPE } from '@seanhogg/builderforce-webcontainers-core';
+
+export interface PreviewError {
+  message: string;
+  stack?: string;
+  href: string;
+}
+
+export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+
+export interface PreviewConsoleMessage {
+  level: ConsoleLevel;
+  /** The arguments flattened to text, capped at 4,000 characters. */
+  text: string;
+  href: string;
+}
+
+export interface PreviewMessages {
+  onError(listener: (error: PreviewError) => void): () => void;
+  onConsole(listener: (message: PreviewConsoleMessage) => void): () => void;
+  dispose(): void;
+}
+
+const LEVELS = new Set<string>(['log', 'info', 'warn', 'error', 'debug']);
+
+/**
+ * The preview page a window message came from, when it is one of THIS runtime's:
+ * sent from the preview origin, by a page under `base`. Undefined otherwise.
+ */
+export function previewPageOf(event: MessageEvent, origin: string, base: string): URL | undefined {
+  const href = (event.data as { href?: unknown } | null)?.href;
+  if (typeof href !== 'string' || event.origin !== origin) return undefined;
+  try {
+    const page = new URL(href);
+    return page.pathname.startsWith(base) ? page : undefined; // else: another runtime's preview
+  } catch {
+    return undefined;
+  }
+}
+
+function subscribe<T>(set: Set<(value: T) => void>, listener: (value: T) => void): () => void {
+  set.add(listener);
+  return () => set.delete(listener);
+}
+
+export function listenToPreview(target: Pick<Window, 'addEventListener' | 'removeEventListener'>, origin: string, base: string): PreviewMessages {
+  const errors = new Set<(error: PreviewError) => void>();
+  const consoles = new Set<(message: PreviewConsoleMessage) => void>();
+
+  const onMessage = (event: MessageEvent) => {
+    if (!previewPageOf(event, origin, base)) return;
+    const data = event.data as { type?: unknown; href: string; message?: unknown; stack?: unknown; level?: unknown; text?: unknown };
+    if (data.type === ERROR_MESSAGE_TYPE) {
+      const error: PreviewError = { message: String(data.message ?? ''), stack: typeof data.stack === 'string' ? data.stack : undefined, href: data.href };
+      for (const listener of errors) listener(error);
+    } else if (data.type === CONSOLE_MESSAGE_TYPE && typeof data.level === 'string' && LEVELS.has(data.level)) {
+      const message: PreviewConsoleMessage = { level: data.level as ConsoleLevel, text: String(data.text ?? ''), href: data.href };
+      for (const listener of consoles) listener(message);
+    }
+  };
+  target.addEventListener('message', onMessage as EventListener);
+
+  return {
+    onError: (listener) => subscribe(errors, listener),
+    onConsole: (listener) => subscribe(consoles, listener),
+    dispose() {
+      target.removeEventListener('message', onMessage as EventListener);
+      errors.clear();
+      consoles.clear();
+    },
+  };
+}

package/src/protocol.ts

@@ -66,9 +66,33 @@ export interface WireResponse {
   reqId: number;
   status: number;
   headers: Record<string, string>;
-  body: string | ArrayBuffer;
+  /** The whole body — or, with `streaming`, null: the body follows as `chunk` messages until `end`. */
+  body: string | ArrayBuffer | null;
+  streaming?: boolean;
 }
 
+/** page → worker: the next piece of a streaming response's body. */
+export interface WireChunk {
+  type: 'chunk';
+  reqId: number;
+  data: ArrayBuffer;
+}
+
+/** page → worker: a streaming response is complete (`error`: it broke off, e.g. the server process exited). */
+export interface WireEnd {
+  type: 'end';
+  reqId: number;
+  error?: string;
+}
+
+/** worker → page: the preview stopped reading a streaming response (closed an EventSource, navigated away). */
+export interface WireCancel {
+  type: 'cancel';
+  reqId: number;
+}
+
+export type WireReply = WireResponse | WireChunk | WireEnd;
+
 /**
  * The URL prefix previews live under, for a worker scope. Serving the worker from
  * `/__bfwc/sw.js` (scope `/__bfwc/`) keeps it off every other page of the host app;
@@ -92,3 +116,13 @@ export function isWireResponse(value: unknown): value is WireResponse {
   const v = value as WireResponse | null;
   return !!v && v.type === 'response' && typeof v.reqId === 'number';
 }
+
+export function isWireReply(value: unknown): value is WireReply {
+  const v = value as WireReply | null;
+  return !!v && (v.type === 'response' || v.type === 'chunk' || v.type === 'end') && typeof v.reqId === 'number';
+}
+
+export function isWireCancel(value: unknown): value is WireCancel {
+  const v = value as WireCancel | null;
+  return !!v && v.type === 'cancel' && typeof v.reqId === 'number';
+}

package/src/snapshotStore.ts

@@ -0,0 +1,135 @@
+/**
+ * Snapshots that outlive the page: `exportZip` bytes kept in IndexedDB under a
+ * key the host chooses (say, the project id plus a hash of package.json), so a
+ * reload can `importZip` an installed `node_modules` instead of reinstalling.
+ *
+ * Bounded: snapshots over `maxBytes` are not stored, and only the
+ * `maxEntries` most recently used are kept. Every operation fails soft —
+ * storage blocked (private windows) or full means a miss, never a throw.
+ */
+
+export interface SnapshotStoreOptions {
+  /** IndexedDB database name. Default `bfwc-snapshots`. */
+  name?: string;
+  /** Snapshots kept, least recently used dropped first. Default 4. */
+  maxEntries?: number;
+  /** Largest snapshot stored, in bytes. Default 256 MB. */
+  maxBytes?: number;
+  /** Injected for tests; defaults to `globalThis.indexedDB`. */
+  indexedDB?: IDBFactory;
+}
+
+export interface SnapshotStore {
+  /** The snapshot saved under `key`, or undefined. */
+  load(key: string): Promise<Uint8Array | undefined>;
+  /** Save (replacing any snapshot under `key`); false when it was not stored (too large, storage unavailable). */
+  save(key: string, zip: Uint8Array): Promise<boolean>;
+  remove(key: string): Promise<void>;
+  /** Keys held, most recently used first. */
+  keys(): Promise<string[]>;
+}
+
+interface Row {
+  key: string;
+  zip: Uint8Array;
+  usedAt: number;
+}
+
+const STORE = 'snapshots';
+
+function request<T>(req: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function done(tx: IDBTransaction): Promise<void> {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error);
+  });
+}
+
+export function createSnapshotStore(options: SnapshotStoreOptions = {}): SnapshotStore {
+  const maxEntries = options.maxEntries ?? 4;
+  const maxBytes = options.maxBytes ?? 256 * 1024 * 1024;
+  let opening: Promise<IDBDatabase | undefined> | undefined;
+
+  const open = () =>
+    (opening ??= (async () => {
+      const factory = options.indexedDB ?? globalThis.indexedDB;
+      if (!factory) return undefined;
+      try {
+        const req = factory.open(options.name ?? 'bfwc-snapshots', 1);
+        req.onupgradeneeded = () => {
+          if (!req.result.objectStoreNames.contains(STORE)) req.result.createObjectStore(STORE, { keyPath: 'key' });
+        };
+        return await request(req);
+      } catch {
+        return undefined;
+      }
+    })());
+
+  const rows = async (db: IDBDatabase): Promise<Row[]> => {
+    const all = (await request(db.transaction(STORE, 'readonly').objectStore(STORE).getAll())) as Row[];
+    return all.sort((a, b) => b.usedAt - a.usedAt);
+  };
+
+  return {
+    async load(key) {
+      const db = await open();
+      if (!db) return undefined;
+      try {
+        const tx = db.transaction(STORE, 'readwrite');
+        const store = tx.objectStore(STORE);
+        const row = (await request(store.get(key))) as Row | undefined;
+        if (row) store.put({ ...row, usedAt: Date.now() });
+        await done(tx);
+        return row?.zip;
+      } catch {
+        return undefined;
+      }
+    },
+    async save(key, zip) {
+      if (zip.byteLength > maxBytes) return false;
+      const db = await open();
+      if (!db) return false;
+      try {
+        const tx = db.transaction(STORE, 'readwrite');
+        tx.objectStore(STORE).put({ key, zip, usedAt: Date.now() } satisfies Row);
+        await done(tx);
+        const stale = (await rows(db)).slice(maxEntries);
+        if (stale.length) {
+          const prune = db.transaction(STORE, 'readwrite');
+          for (const row of stale) prune.objectStore(STORE).delete(row.key);
+          await done(prune);
+        }
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async remove(key) {
+      const db = await open();
+      if (!db) return;
+      try {
+        const tx = db.transaction(STORE, 'readwrite');
+        tx.objectStore(STORE).delete(key);
+        await done(tx);
+      } catch {
+        // storage unavailable: nothing to remove
+      }
+    },
+    async keys() {
+      const db = await open();
+      if (!db) return [];
+      try {
+        return (await rows(db)).map((row) => row.key);
+      } catch {
+        return [];
+      }
+    },
+  };
+}

package/src/sw.ts

@@ -74,6 +74,8 @@ worker.addEventListener('fetch', (event) => {
         details = { method: request.method, headers, body };
       }
       const r = await router.respond(target, details);
+      // A virtual server's body is a stream fed as the server writes (SSE, chunked progress).
+      if (NULL_BODY.has(r.status) && r.body instanceof ReadableStream) void r.body.cancel();
       return new Response(NULL_BODY.has(r.status) ? null : r.body, { status: r.status, headers: r.headers });
     })(),
   );

package/src/swRouter.ts

@@ -1,4 +1,4 @@
-import { PREVIEW_ID, isPortPath, isWireResponse, previewPrefix, type WireResponse } from './protocol.js';
+import { PREVIEW_ID, isPortPath, isWireReply, previewPrefix, type WireCancel, type WireResponse } from './protocol.js';
 
 /** The part of MessagePort the router uses — a fake in tests, a real port in the worker. */
 export interface PortLike {
@@ -22,7 +22,8 @@ export interface RequestDetails {
 export interface RoutedResponse {
   status: number;
   headers: Record<string, string>;
-  body: string | ArrayBuffer;
+  /** A stream when the page streams the body (a virtual server's response): chunks arrive as the server writes them. */
+  body: string | ArrayBuffer | ReadableStream<Uint8Array> | null;
 }
 
 export interface SwRouterOptions {
@@ -46,6 +47,12 @@ const TEXT = { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no
  * router asks open pages to re-attach and waits briefly. A port that stops
  * answering (its tab closed) is dropped on timeout, so the NEXT request goes
  * through the re-attach path instead of timing out forever.
+ *
+ * A virtual server's response streams: the page sends the head (`streaming`),
+ * then `chunk` messages and an `end`, and the router answers the fetch with a
+ * ReadableStream fed by them. The timeout covers only the wait for the head (an
+ * event stream may stay open indefinitely); cancelling the stream (the preview
+ * closed its EventSource) tells the page to hang up on the server.
  */
 export function createSwRouter(options: SwRouterOptions) {
   const prefix = previewPrefix(options.scopePath);
@@ -54,14 +61,29 @@ export function createSwRouter(options: SwRouterOptions) {
   const ports = new Map<string, PortLike>();
   const waiters = new Map<string, Array<(port: PortLike) => void>>();
   const pending = new Map<number, (response: WireResponse) => void>();
+  const streams = new Map<number, ReadableStreamDefaultController<Uint8Array>>();
   let nextId = 0;
 
   function attach(id: string, port: PortLike): void {
     ports.set(id, port);
     port.onmessage = (event) => {
-      if (!isWireResponse(event.data)) return;
-      pending.get(event.data.reqId)?.(event.data);
-      pending.delete(event.data.reqId);
+      const reply = event.data;
+      if (!isWireReply(reply)) return;
+      if (reply.type === 'response') {
+        pending.get(reply.reqId)?.(reply);
+        pending.delete(reply.reqId);
+        return;
+      }
+      const controller = streams.get(reply.reqId);
+      if (!controller) return;
+      try {
+        if (reply.type === 'chunk') return controller.enqueue(new Uint8Array(reply.data));
+        streams.delete(reply.reqId);
+        if (reply.error) controller.error(new Error(reply.error));
+        else controller.close();
+      } catch {
+        streams.delete(reply.reqId); // the reader already went away
+      }
     };
     for (const wake of waiters.get(id) ?? []) wake(port);
     waiters.delete(id);
@@ -125,7 +147,14 @@ export function createSwRouter(options: SwRouterOptions) {
       }, timeoutMs);
       pending.set(reqId, (response) => {
         clearTimeout(timer);
-        resolve({ status: response.status, headers: response.headers, body: response.body });
+        if (!response.streaming) return resolve({ status: response.status, headers: response.headers, body: response.body });
+        const body = new ReadableStream<Uint8Array>({
+          start: (controller) => void streams.set(reqId, controller),
+          cancel: () => {
+            if (streams.delete(reqId)) port.postMessage({ type: 'cancel', reqId } satisfies WireCancel);
+          },
+        });
+        resolve({ status: response.status, headers: response.headers, body });
       });
       port.postMessage({ type: 'request', reqId, path: target.path, search: target.search, ...details });
     });