@seanhogg/builderforce-webcontainers 2026.10.7 → 2026.10.8

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

@@ -30,6 +30,21 @@ export interface PreviewMessages {
 
 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);
@@ -40,15 +55,8 @@ export function listenToPreview(target: Pick<Window, 'addEventListener' | 'remov
   const consoles = new Set<(message: PreviewConsoleMessage) => void>();
 
   const onMessage = (event: MessageEvent) => {
-    const data = event.data as { type?: unknown; href?: unknown; message?: unknown; stack?: unknown; level?: unknown; text?: unknown } | null;
-    if (!data || typeof data.href !== 'string' || event.origin !== origin) return;
-    let path: string;
-    try {
-      path = new URL(data.href).pathname;
-    } catch {
-      return;
-    }
-    if (!path.startsWith(base)) return; // another runtime's preview
+    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);

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