@seanhogg/builderforce-webcontainers 2026.10.2 → 2026.10.4

package/src/node/protocol.ts

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

package/src/node/worker.ts

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

package/src/node/workerProcess.ts

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

package/src/packageCache.ts

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

package/src/protocol.ts

@@ -30,6 +30,8 @@ export const RELAY_ATTACH = 'bfwc:relay-attach';
 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;
@@ -46,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

@@ -7,7 +7,8 @@
  * 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 } from './protocol.js';
+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;
@@ -29,6 +30,9 @@ async function start(): Promise<void> {
       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' }));
     }
   });
 

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 { PREVIEW_ID, 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>;
@@ -84,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;
@@ -98,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

@@ -17,7 +17,10 @@ import {
   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 {
@@ -31,6 +34,12 @@ export interface PreviewTransport {
   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;
 }
 
@@ -118,6 +127,11 @@ export async function relayTransport(relayUrl: string): Promise<PreviewTransport
       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();