@seanhogg/builderforce-webcontainers 2026.10.1 → 2026.10.3

package/src/protocol.ts

@@ -6,11 +6,33 @@
 
 export const PREVIEW_SEGMENT = '__bfwc';
 
+/**
+ * What a preview id may contain. No dots, so a file served beside the worker
+ * (`sw.js`, `relay.html`) can never be mistaken for a preview.
+ */
+export const PREVIEW_ID = /^[A-Za-z0-9_-]+$/;
+
 /** page → worker, with a MessagePort in `ports[0]`: "serve preview `id` over this port". */
 export const ATTACH = 'bfwc:attach';
 /** worker → pages: "I lost the port for `id` (I was restarted) — attach again". */
 export const REATTACH = 'bfwc:reattach';
 
+/**
+ * The cross-origin relay (`relay.html`, served on the preview origin and framed,
+ * hidden, by the host). The host cannot talk to a worker on another origin, so the
+ * relay registers it and passes messages both ways.
+ */
+/** relay → host: the worker is active; send ports. */
+export const RELAY_READY = 'bfwc:relay-ready';
+/** host → relay, with a MessagePort: forward as ATTACH for `id`. */
+export const RELAY_ATTACH = 'bfwc:relay-attach';
+/** relay → host: the worker asked for `id` again. */
+export const RELAY_REATTACH = 'bfwc:relay-reattach';
+/** host → relay: reload every frame showing the preview at `base`. */
+export const RELAY_RELOAD = 'bfwc:relay-reload';
+/** host → relay, with a MessagePort: start a process worker on the preview origin, bridged over the port. */
+export const RELAY_SPAWN = 'bfwc:relay-spawn';
+
 export interface AttachMessage {
   type: typeof ATTACH;
   id: string;
@@ -26,6 +48,17 @@ export interface WireRequest {
   reqId: number;
   path: string;
   search: string;
+  /** Present for requests to a virtual Node server (`/__port/<n>/…`), which see the full request. */
+  method?: string;
+  headers?: Record<string, string>;
+  body?: ArrayBuffer | null;
+}
+
+/** The path segment that routes a preview request to a virtual server: `/__port/3000/…`. */
+export const PORT_SEGMENT = '__port';
+
+export function isPortPath(path: string): boolean {
+  return path.startsWith(`/${PORT_SEGMENT}/`);
 }
 
 export interface WireResponse {

package/src/relay.ts

@@ -0,0 +1,44 @@
+/**
+ * The relay page's script (bundled inline into dist/relay.html). Served on the
+ * preview origin and framed, hidden, by the host page, it registers the preview
+ * worker on ITS origin and passes ports, re-attach requests and reloads between
+ * the two. See `relayTransport`.
+ *
+ * Whoever may frame this page may drive it, so the server that hosts relay.html
+ * must restrict that with `Content-Security-Policy: frame-ancestors <host origins>`.
+ */
+import { ATTACH, REATTACH, RELAY_ATTACH, RELAY_READY, RELAY_REATTACH, RELAY_RELOAD, RELAY_SPAWN } from './protocol.js';
+import { bridgeWorker, RELAY_PROCESS_WORKER } from './relayWorker.js';
+import { broadcastReload, waitForActive } from './worker.js';
+
+const host = window.parent;
+
+async function start(): Promise<void> {
+  const container = navigator.serviceWorker;
+  if (!container) throw new Error('Service workers are unavailable on the preview origin.');
+  const registration = await container.register(new URL('./sw.js', location.href).href, { scope: './' });
+  await waitForActive(registration);
+
+  container.addEventListener('message', (event) => {
+    if (event.data?.type === REATTACH && typeof event.data.id === 'string') host.postMessage({ type: RELAY_REATTACH, id: event.data.id }, '*');
+  });
+
+  addEventListener('message', (event) => {
+    if (event.source !== host) return;
+    const data = event.data as { type?: string; id?: unknown; base?: unknown } | null;
+    if (data?.type === RELAY_ATTACH && typeof data.id === 'string' && event.ports[0]) {
+      registration.active?.postMessage({ type: ATTACH, id: data.id }, [event.ports[0]]);
+    } else if (data?.type === RELAY_RELOAD && typeof data.base === 'string') {
+      broadcastReload(data.base);
+    } else if (data?.type === RELAY_SPAWN && event.ports[0]) {
+      // Process code runs HERE, on the preview origin, never on the host's.
+      bridgeWorker(event.ports[0], new Worker(new URL(`./${RELAY_PROCESS_WORKER}`, location.href), { name: 'bfwc-process' }));
+    }
+  });
+
+  host.postMessage({ type: RELAY_READY }, '*');
+}
+
+start().catch((error: unknown) => {
+  host.postMessage({ type: RELAY_READY, error: error instanceof Error ? error.message : String(error) }, '*');
+});

package/src/relayWorker.ts

@@ -0,0 +1,53 @@
+/**
+ * Process workers on the PREVIEW origin, driven from the host page.
+ *
+ * A process worker runs whatever the project runs — npm packages, the user's
+ * server, an AI-written script. A worker started by the host page shares the
+ * host's origin: its IndexedDB, Cache Storage and same-origin requests. In relay
+ * mode that is exactly what the preview origin exists to keep apart, so the
+ * relay frame starts each worker on ITS origin and this bridges the two over a
+ * MessageChannel. The host side is a `WorkerLike`, so the process host cannot
+ * tell the difference.
+ */
+import type { WorkerLike } from './node/processHost.js';
+
+type ToWorker = { kind: 'message'; data: unknown } | { kind: 'terminate' };
+type FromWorker = { kind: 'message'; data: unknown } | { kind: 'error'; message: string };
+
+/** Host side: a `WorkerLike` whose worker lives at the far end of `port`. */
+export function workerOverPort(port: MessagePort): WorkerLike {
+  const worker: WorkerLike = {
+    onmessage: null,
+    onerror: null,
+    postMessage(data) {
+      port.postMessage({ kind: 'message', data } satisfies ToWorker);
+    },
+    terminate() {
+      port.postMessage({ kind: 'terminate' } satisfies ToWorker);
+      port.close();
+    },
+  };
+  port.onmessage = (event: MessageEvent<FromWorker>) => {
+    const message = event.data;
+    if (message?.kind === 'message') worker.onmessage?.({ data: message.data });
+    else if (message?.kind === 'error') worker.onerror?.({ message: message.message });
+  };
+  return worker;
+}
+
+/** Relay side: run `worker`, relaying both ways over `port` until terminated. */
+export function bridgeWorker(port: MessagePort, worker: Worker): void {
+  worker.onmessage = (event) => port.postMessage({ kind: 'message', data: event.data } satisfies FromWorker);
+  worker.onerror = (event) => port.postMessage({ kind: 'error', message: event.message || 'The process worker failed.' } satisfies FromWorker);
+  port.onmessage = (event: MessageEvent<ToWorker>) => {
+    const message = event.data;
+    if (message?.kind === 'message') worker.postMessage(message.data);
+    else if (message?.kind === 'terminate') {
+      worker.terminate();
+      port.close();
+    }
+  };
+}
+
+/** The process worker's file name beside `relay.html` on the preview origin. */
+export const RELAY_PROCESS_WORKER = 'process-worker.js';

package/src/sw.ts

@@ -6,8 +6,8 @@
  * 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 { createSwRouter, type PortLike } from './swRouter.js';
-import { ATTACH, REATTACH, type AttachMessage } from './protocol.js';
+import { createSwRouter, type PortLike, type RequestDetails } from './swRouter.js';
+import { ATTACH, REATTACH, isPortPath, type AttachMessage } from './protocol.js';
 
 interface WindowClientLike {
   postMessage(message: unknown): void;
@@ -25,7 +25,7 @@ interface ServiceWorkerGlobalLike {
   addEventListener(type: 'message', listener: (event: { data: unknown; ports: readonly unknown[] }) => void): void;
   addEventListener(
     type: 'fetch',
-    listener: (event: { request: Request; respondWith(response: Promise<Response>): void }) => void,
+    listener: (event: { request: Request; clientId?: string; resultingClientId?: string; respondWith(response: Promise<Response>): void }) => void,
   ): void;
 }
 
@@ -53,9 +53,28 @@ worker.addEventListener('message', (event) => {
   if (message?.type === ATTACH && typeof message.id === 'string' && port) router.attach(message.id, port as PortLike);
 });
 
+/** Statuses whose responses must not carry a body. */
+const NULL_BODY = new Set([101, 204, 205, 304]);
+
 worker.addEventListener('fetch', (event) => {
-  if (event.request.method !== 'GET') return;
-  const target = router.match(new URL(event.request.url));
+  const { request } = event;
+  const target = router.matchForClient(new URL(request.url), event.clientId, new URL(worker.registration.scope).origin);
   if (!target) return;
-  event.respondWith(router.respond(target).then((r) => new Response(r.body, { status: r.status, headers: r.headers })));
+  const toServer = isPortPath(target.path);
+  // Only virtual Node servers take non-GET requests; the dev server serves files.
+  if (request.method !== 'GET' && !toServer) return;
+  if (toServer) router.rememberClient(event.resultingClientId, target);
+  event.respondWith(
+    (async () => {
+      let details: RequestDetails | undefined;
+      if (toServer) {
+        const headers: Record<string, string> = {};
+        request.headers.forEach((value, key) => (headers[key] = value));
+        const body = request.method === 'GET' || request.method === 'HEAD' ? null : await request.arrayBuffer();
+        details = { method: request.method, headers, body };
+      }
+      const r = await router.respond(target, details);
+      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 { isWireResponse, previewPrefix, type WireResponse } from './protocol.js';
+import { PREVIEW_ID, isPortPath, isWireResponse, previewPrefix, 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 {
@@ -12,6 +12,13 @@ export interface PreviewTarget {
   search: string;
 }
 
+/** The parts of a request a virtual server needs (method, headers, body). */
+export interface RequestDetails {
+  method: string;
+  headers: Record<string, string>;
+  body: ArrayBuffer | null;
+}
+
 export interface RoutedResponse {
   status: number;
   headers: Record<string, string>;
@@ -65,7 +72,9 @@ export function createSwRouter(options: SwRouterOptions) {
     const rest = url.pathname.slice(prefix.length);
     const slash = rest.indexOf('/');
     const id = slash < 0 ? rest : rest.slice(0, slash);
-    if (!id) return null;
+    // Ids are `[A-Za-z0-9_-]`; a dotted segment is a real file beside the worker
+    // (`sw.js`, `relay.html`), which must load from the network.
+    if (!id || !PREVIEW_ID.test(id)) return null;
     return { id, path: slash < 0 ? '/' : rest.slice(slash), search: url.search };
   }
 
@@ -82,7 +91,29 @@ export function createSwRouter(options: SwRouterOptions) {
     return arrived;
   }
 
-  async function respond(target: PreviewTarget): Promise<RoutedResponse> {
+  /**
+   * Pages served by a virtual server (`/__bfwc/<id>/__port/3000/`) write absolute
+   * URLs (`/style.css`, `fetch('/api')`). A service worker sees every request its
+   * clients make, so a same-origin request from such a page that falls outside
+   * the preview prefix is mapped back under that server's path.
+   */
+  const clientServers = new Map<string, { id: string; prefix: string }>();
+
+  function rememberClient(clientId: string | undefined, target: PreviewTarget): void {
+    if (!clientId || !isPortPath(target.path)) return;
+    const prefix = /^\/__port\/\d+/.exec(target.path)![0];
+    clientServers.set(clientId, { id: target.id, prefix });
+    if (clientServers.size > 200) clientServers.delete(clientServers.keys().next().value!);
+  }
+
+  function matchForClient(url: URL, clientId: string | undefined, origin: string): PreviewTarget | null {
+    const direct = match(url);
+    if (direct || !clientId || url.origin !== origin) return direct;
+    const server = clientServers.get(clientId);
+    return server ? { id: server.id, path: server.prefix + url.pathname, search: url.search } : null;
+  }
+
+  async function respond(target: PreviewTarget, details?: RequestDetails): Promise<RoutedResponse> {
     const port = await portFor(target.id);
     if (!port) return { status: 503, headers: TEXT, body: 'This preview is not running in any open tab.' };
     const reqId = ++nextId;
@@ -96,11 +127,11 @@ export function createSwRouter(options: SwRouterOptions) {
         clearTimeout(timer);
         resolve({ status: response.status, headers: response.headers, body: response.body });
       });
-      port.postMessage({ type: 'request', reqId, path: target.path, search: target.search });
+      port.postMessage({ type: 'request', reqId, path: target.path, search: target.search, ...details });
     });
   }
 
-  return { attach, match, respond, detach: (id: string) => ports.delete(id) };
+  return { attach, match, matchForClient, rememberClient, respond, detach: (id: string) => ports.delete(id) };
 }
 
 export type SwRouter = ReturnType<typeof createSwRouter>;

package/src/transport.ts

@@ -0,0 +1,141 @@
+/**
+ * How the host page reaches the preview service worker.
+ *
+ * Same origin: the page registers the worker itself. Simple, but the preview then
+ * runs on the host's origin, with the host's storage and session — fine for a
+ * page that only previews code its own user wrote and trusts.
+ *
+ * Relay: the worker lives on a SEPARATE preview origin. A hidden `relay.html` on
+ * that origin registers it and passes ports and reloads across. The preview can
+ * then never read the host's cookies, storage or DOM, which is what an editor
+ * running AI-written code or arbitrary npm packages needs.
+ */
+import {
+  ATTACH,
+  REATTACH,
+  RELAY_ATTACH,
+  RELAY_READY,
+  RELAY_REATTACH,
+  RELAY_RELOAD,
+  RELAY_SPAWN,
+} from './protocol.js';
+import type { WorkerLike } from './node/processHost.js';
+import { workerOverPort } from './relayWorker.js';
+import { broadcastReload, waitForActive } from './worker.js';
+
+export interface PreviewTransport {
+  /** The origin previews are served from. */
+  readonly origin: string;
+  /** The worker's scope path on that origin. */
+  readonly scope: string;
+  /** Hand the worker the port that serves preview `id`. */
+  attach(id: string, port: MessagePort): void;
+  /** The worker restarted and wants `id` again. */
+  onReattach(listener: (id: string) => void): () => void;
+  /** Reload every frame showing the preview at `base`. */
+  reload(base: string): void;
+  /**
+   * Start a process worker on the preview origin. Only the relay has one to
+   * offer; same-origin mode runs processes on the host's origin, which is the
+   * trust it already chose.
+   */
+  createWorker?(): WorkerLike;
+  dispose(): void;
+}
+
+/** How long the relay has to register its worker before boot gives up. */
+const RELAY_TIMEOUT_MS = 15_000;
+
+export async function sameOriginTransport(serviceWorkerUrl: string, scopeOption?: string): Promise<PreviewTransport> {
+  const container = navigator.serviceWorker;
+  if (!container) throw new Error('Service workers are unavailable here (a secure context — https or localhost — is required).');
+
+  const scriptUrl = new URL(serviceWorkerUrl, location.href);
+  const scope = new URL(scopeOption ?? './', scriptUrl).pathname;
+  const registration = await container.register(scriptUrl.href, { scope });
+  await waitForActive(registration);
+
+  const listeners = new Set<(id: string) => void>();
+  const onWorkerMessage = (event: MessageEvent) => {
+    if (event.data?.type === REATTACH && typeof event.data.id === 'string') for (const listener of listeners) listener(event.data.id);
+  };
+  container.addEventListener('message', onWorkerMessage);
+
+  return {
+    origin: location.origin,
+    scope,
+    attach: (id, port) => registration.active?.postMessage({ type: ATTACH, id }, [port]),
+    onReattach(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    reload: broadcastReload,
+    dispose() {
+      container.removeEventListener('message', onWorkerMessage);
+      listeners.clear();
+    },
+  };
+}
+
+export async function relayTransport(relayUrl: string): Promise<PreviewTransport> {
+  const url = new URL(relayUrl, location.href);
+  const frame = document.createElement('iframe');
+  frame.src = url.href;
+  frame.title = 'Preview relay';
+  frame.setAttribute('aria-hidden', 'true');
+  frame.tabIndex = -1;
+  frame.style.cssText = 'position:absolute;width:0;height:0;border:0;visibility:hidden';
+
+  const fromRelay = (event: MessageEvent) => event.origin === url.origin && event.source === frame.contentWindow;
+
+  const ready = new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      window.removeEventListener('message', onReady);
+      reject(new Error(`The preview relay at ${url.origin} did not start.`));
+    }, RELAY_TIMEOUT_MS);
+    function onReady(event: MessageEvent) {
+      if (!fromRelay(event) || event.data?.type !== RELAY_READY) return;
+      clearTimeout(timer);
+      window.removeEventListener('message', onReady);
+      if (typeof event.data.error === 'string') reject(new Error(event.data.error));
+      else resolve();
+    }
+    window.addEventListener('message', onReady);
+  });
+  document.body.appendChild(frame);
+  try {
+    await ready;
+  } catch (error) {
+    frame.remove();
+    throw error;
+  }
+
+  const listeners = new Set<(id: string) => void>();
+  const onRelayMessage = (event: MessageEvent) => {
+    if (!fromRelay(event) || event.data?.type !== RELAY_REATTACH || typeof event.data.id !== 'string') return;
+    for (const listener of listeners) listener(event.data.id);
+  };
+  window.addEventListener('message', onRelayMessage);
+  const post = (message: unknown, transfer: Transferable[] = []) => frame.contentWindow?.postMessage(message, url.origin, transfer);
+
+  return {
+    origin: url.origin,
+    scope: new URL('./', url).pathname,
+    attach: (id, port) => post({ type: RELAY_ATTACH, id }, [port]),
+    onReattach(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    reload: (base) => post({ type: RELAY_RELOAD, base }),
+    createWorker() {
+      const channel = new MessageChannel();
+      post({ type: RELAY_SPAWN }, [channel.port2]);
+      return workerOverPort(channel.port1);
+    },
+    dispose() {
+      window.removeEventListener('message', onRelayMessage);
+      listeners.clear();
+      frame.remove();
+    },
+  };
+}

package/src/worker.ts

@@ -0,0 +1,25 @@
+/**
+ * Small helpers shared by the page-side transports and the relay page.
+ */
+import { reloadChannelName } from '@seanhogg/builderforce-webcontainers-core';
+
+/** Resolve once the registration has an active worker. */
+export function waitForActive(registration: ServiceWorkerRegistration): Promise<ServiceWorker> {
+  if (registration.active) return Promise.resolve(registration.active);
+  const installing = registration.installing ?? registration.waiting;
+  if (!installing) return Promise.reject(new Error('The preview service worker did not install.'));
+  return new Promise((resolve, reject) => {
+    installing.addEventListener('statechange', () => {
+      if (installing.state === 'activated' && registration.active) resolve(registration.active);
+      if (installing.state === 'redundant') reject(new Error('The preview service worker failed to install.'));
+    });
+  });
+}
+
+/** Reload every frame (on this origin) showing the preview served at `base`. */
+export function broadcastReload(base: string): void {
+  if (typeof BroadcastChannel === 'undefined') return;
+  const channel = new BroadcastChannel(reloadChannelName(base));
+  channel.postMessage('reload');
+  channel.close();
+}