@seanhogg/builderforce-webcontainers 2026.10.1 → 2026.10.3

package/src/check/index.ts

@@ -0,0 +1,98 @@
+/**
+ * `@seanhogg/builderforce-webcontainers/check` — type-check a project in a Web
+ * Worker, with no install and no server.
+ *
+ * The worker loads the TypeScript compiler from a CDN (pinned below) and fetches
+ * dependency types from esm.sh, caching both, so the page's main thread never
+ * parses lib.dom.d.ts. Diagnostics come back as plain data (see CheckDiagnostic).
+ */
+import { VirtualFileSystem, type FlatFiles } from '@seanhogg/builderforce-webcontainers-core';
+import type { TypeSources, TypecheckResult } from '@seanhogg/builderforce-webcontainers-core/check';
+import { CHECK, CHECK_RESULT, isCheckInput, isCheckReply, type CheckReply } from './protocol.js';
+
+export type { CheckDiagnostic, DiagnosticCategory, TypecheckResult } from '@seanhogg/builderforce-webcontainers-core/check';
+export { formatDiagnostic } from '@seanhogg/builderforce-webcontainers-core/check';
+
+/** The TypeScript the checker runs. Pinned, so results do not change under a project. */
+export const TYPESCRIPT_VERSION = '5.9.3';
+export const DEFAULT_TYPESCRIPT_URL = `https://cdn.jsdelivr.net/npm/typescript@${TYPESCRIPT_VERSION}/lib/typescript.js`;
+
+export interface CheckerOptions {
+  /**
+   * The worker script (this package's `dist/check/worker.js`). By default it is
+   * resolved beside this module, a pattern Vite, webpack 5 and Next.js all bundle.
+   */
+  workerUrl?: string | URL;
+  /** Build the Worker yourself (a CSP that needs a specific origin, a test double). */
+  createWorker?: () => Worker;
+  /** A classic-script build of TypeScript that sets `self.ts`. Default: jsDelivr, {@link TYPESCRIPT_VERSION}. */
+  typescriptUrl?: string;
+  /** Where types, libs and tsconfig packages come from. Libs default to the loaded TypeScript's version. */
+  sources?: Partial<TypeSources>;
+}
+
+export interface CheckResult extends TypecheckResult {
+  durationMs: number;
+}
+
+export interface Checker {
+  /** Type-check the project. Checks queue; each resolves with its own result. */
+  check(files: VirtualFileSystem | FlatFiles): Promise<CheckResult>;
+  /** Stop the worker; pending checks reject. */
+  dispose(): void;
+}
+
+/** Only the files that can affect checking, as text: assets never cross to the worker. */
+export function checkInputs(files: VirtualFileSystem | FlatFiles): Record<string, string> {
+  let fs: VirtualFileSystem;
+  if (files instanceof VirtualFileSystem) fs = files;
+  else {
+    fs = new VirtualFileSystem();
+    fs.mount(files);
+  }
+  const out: Record<string, string> = {};
+  for (const path of fs.list()) if (isCheckInput(path)) out[path.slice(1)] = fs.readText(path) ?? '';
+  return out;
+}
+
+export function createChecker(options: CheckerOptions = {}): Checker {
+  const worker = options.createWorker?.() ?? new Worker(options.workerUrl ?? new URL('./worker.js', import.meta.url));
+  const pending = new Map<number, { resolve(result: CheckResult): void; reject(error: Error): void }>();
+  let nextId = 0;
+
+  worker.addEventListener('message', (event: MessageEvent) => {
+    if (!isCheckReply(event.data)) return;
+    const reply: CheckReply = event.data;
+    const waiter = pending.get(reply.id);
+    pending.delete(reply.id);
+    if (reply.type === CHECK_RESULT) waiter?.resolve({ ...reply.result, durationMs: reply.durationMs });
+    else waiter?.reject(new Error(reply.message));
+  });
+  worker.addEventListener('error', (event: ErrorEvent) => {
+    const error = new Error(event.message || 'The check worker failed to start.');
+    for (const waiter of pending.values()) waiter.reject(error);
+    pending.clear();
+  });
+
+  return {
+    check(files) {
+      const id = ++nextId;
+      return new Promise<CheckResult>((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        worker.postMessage({
+          type: CHECK,
+          id,
+          files: checkInputs(files),
+          typescriptUrl: options.typescriptUrl ?? DEFAULT_TYPESCRIPT_URL,
+          sources: options.sources,
+        });
+      });
+    },
+    dispose() {
+      worker.terminate();
+      const error = new Error('The checker was disposed.');
+      for (const waiter of pending.values()) waiter.reject(error);
+      pending.clear();
+    },
+  };
+}

package/src/check/protocol.ts

@@ -0,0 +1,34 @@
+/**
+ * Messages between `createChecker()` (page) and the check worker. Files travel as
+ * strings: only source and config files are sent, never assets.
+ */
+import type { TypeSources, TypecheckResult } from '@seanhogg/builderforce-webcontainers-core/check';
+
+export const CHECK = 'bfwc:check';
+export const CHECK_RESULT = 'bfwc:check-result';
+export const CHECK_ERROR = 'bfwc:check-error';
+
+export interface CheckRequest {
+  type: typeof CHECK;
+  id: number;
+  files: Record<string, string>;
+  /** Classic script URL of the TypeScript compiler (sets `self.ts`). */
+  typescriptUrl: string;
+  sources?: Partial<TypeSources>;
+}
+
+export type CheckReply =
+  | { type: typeof CHECK_RESULT; id: number; result: TypecheckResult; durationMs: number }
+  | { type: typeof CHECK_ERROR; id: number; message: string };
+
+/** Paths whose contents can affect type-checking. */
+const CHECKED = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|json)$/i;
+
+export function isCheckInput(path: string): boolean {
+  return CHECKED.test(path) && !/(^|\/)(node_modules|dist)\//.test(path);
+}
+
+export function isCheckReply(value: unknown): value is CheckReply {
+  const v = value as CheckReply | null;
+  return !!v && (v.type === CHECK_RESULT || v.type === CHECK_ERROR) && typeof v.id === 'number';
+}

package/src/check/worker.ts

@@ -0,0 +1,49 @@
+/**
+ * The check worker (bundled to dist/check/worker.js as one classic script). It
+ * loads the TypeScript compiler with `importScripts` — TypeScript's own UMD
+ * build, which sets `self.ts` — and keeps one TypeStore for its lifetime, so
+ * every check after the first reuses fetched and parsed declarations.
+ *
+ * Worker globals are typed locally, as in sw.ts: `lib.webworker` cannot share a
+ * compilation with the DOM lib the rest of the package needs.
+ */
+import type * as TS from 'typescript';
+import { TypeStore, typecheckProject } from '@seanhogg/builderforce-webcontainers-core/check';
+import { createCachedFetch } from './cachedFetch.js';
+import { CHECK, CHECK_ERROR, CHECK_RESULT, type CheckReply, type CheckRequest } from './protocol.js';
+
+interface WorkerGlobalLike {
+  ts?: typeof TS;
+  importScripts(url: string): void;
+  postMessage(message: CheckReply): void;
+  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void;
+}
+
+const worker = globalThis as unknown as WorkerGlobalLike;
+const store = new TypeStore();
+const fetchTypes = createCachedFetch();
+let loadedFrom: string | undefined;
+
+function typescript(url: string): typeof TS {
+  if (!worker.ts || loadedFrom !== url) {
+    worker.importScripts(url);
+    loadedFrom = url;
+  }
+  if (!worker.ts) throw new Error(`${url} did not define the TypeScript compiler.`);
+  return worker.ts;
+}
+
+worker.addEventListener('message', (event) => {
+  const request = event.data as CheckRequest | null;
+  if (request?.type !== CHECK) return;
+  const started = Date.now();
+  void (async () => {
+    try {
+      const ts = typescript(request.typescriptUrl);
+      const result = await typecheckProject(ts, request.files, { fetch: fetchTypes, store, sources: request.sources });
+      worker.postMessage({ type: CHECK_RESULT, id: request.id, result, durationMs: Date.now() - started });
+    } catch (error) {
+      worker.postMessage({ type: CHECK_ERROR, id: request.id, message: error instanceof Error ? error.message : String(error) });
+    }
+  })();
+});

package/src/componentCompilers.ts

@@ -0,0 +1,66 @@
+import {
+  createSvelteCompiler,
+  createVueCompiler,
+  isRegistryRange,
+  type ComponentCompiler,
+  type ComponentCompilers,
+  type SvelteCompilerLike,
+  type VueCompilerSfcLike,
+} from '@seanhogg/builderforce-webcontainers-core';
+
+/**
+ * The Vue and Svelte compilers, fetched from a CDN the first time a project
+ * needs one — nothing is downloaded for a React app — and pinned to the
+ * project's own framework range, so compiler and runtime agree. (Svelte's
+ * compiled output calls internal runtime functions that change between minors;
+ * the runtime is served by esm.sh from the same range, so the compiler is too.)
+ */
+export interface CdnComponentCompilerOptions {
+  /** The ES module URL of `@vue/compiler-sfc`'s browser build for a `vue` range. */
+  vueCompilerUrl?: (range: string) => string;
+  /** The ES module URL of `svelte/compiler` for a `svelte` range. */
+  svelteCompilerUrl?: (range: string) => string;
+  /** Loads a module by URL. Default: native `import()`. */
+  importModule?: (url: string) => Promise<unknown>;
+}
+
+/** Self-contained ESM build the official Vue SFC playground loads. */
+export const defaultVueCompilerUrl = (range: string) =>
+  `https://cdn.jsdelivr.net/npm/@vue/compiler-sfc@${range}/dist/compiler-sfc.esm-browser.js`;
+
+export const defaultSvelteCompilerUrl = (range: string) => `https://esm.sh/svelte@${range}/compiler`;
+
+/**
+ * `import()` of a runtime URL. The magic comments stop the host app's bundler
+ * (webpack, Vite) from trying to resolve the CDN URL at build time.
+ */
+const nativeImport = (url: string): Promise<unknown> => import(/* webpackIgnore: true */ /* @vite-ignore */ url);
+
+function rangeOf(dependencies: Readonly<Record<string, string>>, name: string, fallback: string): string {
+  const range = dependencies[name];
+  return range && isRegistryRange(range) ? range : fallback;
+}
+
+export function createCdnComponentCompilers(options: CdnComponentCompilerOptions = {}): ComponentCompilers {
+  const load = options.importModule ?? nativeImport;
+  const cache = new Map<string, Promise<ComponentCompiler>>();
+
+  const memo = (url: string, make: (module: unknown) => ComponentCompiler): Promise<ComponentCompiler> => {
+    let hit = cache.get(url);
+    if (!hit) {
+      hit = load(url).then(make);
+      hit.catch(() => cache.delete(url)); // a failed download may be retried
+      cache.set(url, hit);
+    }
+    return hit;
+  };
+
+  return (extension, dependencies) => {
+    if (extension === '.vue') {
+      const url = (options.vueCompilerUrl ?? defaultVueCompilerUrl)(rangeOf(dependencies, 'vue', '3'));
+      return memo(url, (module) => createVueCompiler(module as VueCompilerSfcLike));
+    }
+    const url = (options.svelteCompilerUrl ?? defaultSvelteCompilerUrl)(rangeOf(dependencies, 'svelte', '5'));
+    return memo(url, (module) => createSvelteCompiler(module as SvelteCompilerLike));
+  };
+}

package/src/esbuildWasm.ts

@@ -1,26 +1,38 @@
-import { createEsbuildTransformer, type Transformer } from '@seanhogg/builderforce-webcontainers-core';
+import { createEsbuildBundler, createEsbuildTransformer, type Bundler, type Transformer } from '@seanhogg/builderforce-webcontainers-core';
 
 export interface EsbuildWasmOptions {
   /** Where to fetch esbuild.wasm. Defaults to jsDelivr at the installed version. */
   wasmURL?: string;
 }
 
-let ready: Promise<Transformer> | undefined;
+type EsbuildWasm = typeof import('esbuild-wasm');
+
+let ready: Promise<EsbuildWasm> | undefined;
 
 /**
- * The default compiler: esbuild compiled to WebAssembly, run off the main thread.
- * esbuild may be initialised once per page, so the transformer is shared by every
- * runtime booted on it (the options of the first call win).
+ * esbuild compiled to WebAssembly, run off the main thread. esbuild may be
+ * initialised once per page, so the dev-server transformer and the production
+ * bundler share one instance (the options of the first call win).
  */
-export function createEsbuildWasmTransformer(options: EsbuildWasmOptions = {}): Promise<Transformer> {
+export function loadEsbuildWasm(options: EsbuildWasmOptions = {}): Promise<EsbuildWasm> {
   ready ??= (async () => {
     const esbuild = await import('esbuild-wasm');
     const wasmURL = options.wasmURL ?? `https://cdn.jsdelivr.net/npm/esbuild-wasm@${esbuild.version}/esbuild.wasm`;
     await esbuild.initialize({ wasmURL, worker: true });
-    return createEsbuildTransformer(esbuild);
+    return esbuild;
   })().catch((error: unknown) => {
     ready = undefined; // let a later call retry (a transient network failure fetching the wasm)
     throw error;
   });
   return ready;
 }
+
+/** The default compiler for the dev server. */
+export async function createEsbuildWasmTransformer(options: EsbuildWasmOptions = {}): Promise<Transformer> {
+  return createEsbuildTransformer(await loadEsbuildWasm(options));
+}
+
+/** The default bundler for `runtime.build()`. */
+export async function createEsbuildWasmBundler(options: EsbuildWasmOptions = {}): Promise<Bundler> {
+  return createEsbuildBundler(await loadEsbuildWasm(options));
+}

package/src/host.ts

@@ -2,36 +2,82 @@ import {
   DevServer,
   ERROR_MESSAGE_TYPE,
   VirtualFileSystem,
-  type DevServerOptions,
+  buildProject,
+  type BuildResult,
+  type Bundler,
+  type ComponentCompilers,
   type FileSystemTree,
   type FlatFiles,
+  type PackageCdnFactory,
   type ProjectProfile,
   type Transformer,
+  type SpawnOptions,
+  type WebContainerProcess,
 } from '@seanhogg/builderforce-webcontainers-core';
-import { ATTACH, REATTACH, isWireRequest, previewBase, type WireResponse } from './protocol.js';
-import { createEsbuildWasmTransformer } from './esbuildWasm.js';
+import { PREVIEW_ID, isPortPath, isWireRequest, previewBase, type WireRequest, type WireResponse } from './protocol.js';
+import { createProcessHost, servePortRequest, type NodeRuntimeOptions } from './node/index.js';
+import { relayTransport, sameOriginTransport } from './transport.js';
+import { createEsbuildWasmBundler, createEsbuildWasmTransformer } from './esbuildWasm.js';
+import { createCdnComponentCompilers } from './componentCompilers.js';
 
-export interface BootOptions {
+/** Serve previews on THIS page's origin. Only for code the page's own user trusts. */
+export interface SameOriginOptions {
   /** Where the host serves this package's `dist/sw.js` (e.g. `/__bfwc/sw.js`). */
   serviceWorkerUrl: string;
   /** Worker scope. Defaults to the worker script's directory. */
   scope?: string;
+  relayUrl?: never;
+}
+
+/**
+ * Serve previews on a SEPARATE origin, isolated from this page's cookies, storage
+ * and DOM. That origin serves `dist/relay.html` and `dist/sw.js` side by side, with
+ * `frame-ancestors` limited to the pages allowed to drive it.
+ */
+export interface RelayOptions {
+  /** e.g. `https://preview.example.com/__bfwc/relay.html`. */
+  relayUrl: string;
+  serviceWorkerUrl?: never;
+  scope?: never;
+}
+
+export type BootOptions = (SameOriginOptions | RelayOptions) & CommonBootOptions;
+
+export interface CommonBootOptions {
   /** Compiler. Defaults to esbuild-wasm. */
   transformer?: Transformer;
-  /** Package CDN factory. Defaults to esm.sh. */
-  cdn?: DevServerOptions['cdn'];
-  /** Stable id (e.g. the project id) — keeps the preview URL stable across reloads. */
+  /** Package CDN factory, for previews (`dev: true`) and builds (`dev: false`). Defaults to esm.sh. */
+  cdn?: PackageCdnFactory;
+  /** `.vue` / `.svelte` compilers. Default: the official ones, fetched from a CDN on first use. */
+  components?: ComponentCompilers;
+  /** Bundler for `build()`. Default: esbuild-wasm (the same instance as the compiler). */
+  bundler?: Bundler;
+  /** Stable id (e.g. the project id; `[A-Za-z0-9_-]`) — keeps the preview URL stable across reloads. */
   id?: string;
   /** The "Built with Builderforce.ai" badge in the preview. Default true — please keep it. */
   attribution?: boolean;
+  /** Reload open previews when files change. Default true. */
+  liveReload?: boolean;
+  /** The Node runtime behind `spawn` (process workers, npm registry). */
+  node?: NodeRuntimeOptions;
 }
 
+/** Edits arrive in bursts (a save, an agent writing several files): reload once per burst. */
+const RELOAD_DEBOUNCE_MS = 120;
+
 export interface PreviewError {
   message: string;
   stack?: string;
   href: string;
 }
 
+export interface RuntimeBuildOptions {
+  /** Where the site will be served from. Default `./` (works from any directory). */
+  base?: string;
+  /** Default true. */
+  minify?: boolean;
+}
+
 export interface PreviewRuntime {
   readonly id: string;
   /** Absolute URL to load in the preview iframe. */
@@ -41,28 +87,34 @@ export interface PreviewRuntime {
   mount(files: FileSystemTree | FlatFiles): void;
   /** Whether this runtime can serve the mounted project, and why not. */
   profile(): ProjectProfile;
+  /**
+   * `npm run build` for the mounted files: a deployable static site (index.html,
+   * hashed `assets/`, `public/` copied). Rejects with the reason when the project
+   * is not one this runtime supports, or with the bundler's errors.
+   */
+  build(options?: RuntimeBuildOptions): Promise<BuildResult>;
   /** Uncaught errors and rejections raised inside the preview. */
   onError(listener: (error: PreviewError) => void): () => void;
+  /**
+   * Run a command — `node server.js`, `npm install`, `npm run dev`, `jsh` for a
+   * terminal — in its own Web Worker. Same shape as `@webcontainer/api`'s
+   * `spawn`: `output`/`input` streams, `exit`, `kill()`, `resize()`. Pass
+   * `{ terminal: { cols, rows } }` when wiring it to xterm.js.
+   */
+  spawn(command: string, args?: string[], options?: SpawnOptions): WebContainerProcess;
+  spawn(command: string, options?: SpawnOptions): WebContainerProcess;
+  /** `server-ready`: a process started listening (or a dev script handed off to the preview); `url` loads it in an iframe. */
+  on(event: 'server-ready', listener: (port: number, url: string) => void): () => void;
+  /** `port`: a virtual server opened or closed. */
+  on(event: 'port', listener: (port: number, type: 'open' | 'close', url: string) => void): () => void;
   dispose(): void;
 }
 
-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.'));
-    });
-  });
-}
-
 function randomId(): string {
   return globalThis.crypto?.randomUUID?.().replace(/-/g, '').slice(0, 16) ?? Math.random().toString(36).slice(2, 18);
 }
 
-function toWire(reqId: number, served: Awaited<ReturnType<DevServer['handle']>>): { message: WireResponse; transfer: Transferable[] } {
+export function toWire(reqId: number, served: Awaited<ReturnType<DevServer['handle']>>): { message: WireResponse; transfer: Transferable[] } {
   if (typeof served.body === 'string') {
     return { message: { type: 'response', reqId, status: served.status, headers: served.headers, body: served.body }, transfer: [] };
   }
@@ -75,44 +127,65 @@ function toWire(reqId: number, served: Awaited<ReturnType<DevServer['handle']>>)
  * it, and a service worker that routes the preview iframe's requests back here.
  *
  * Needs a secure context (https or localhost) for the service worker — and
- * nothing else: no cross-origin isolation headers, no SharedArrayBuffer.
+ * nothing else: no cross-origin isolation headers, no SharedArrayBuffer. Pass
+ * `relayUrl` to serve the preview from its own origin (see `RelayOptions`).
  */
 export async function bootPreviewRuntime(options: BootOptions): Promise<PreviewRuntime> {
-  const container = navigator.serviceWorker;
-  if (!container) throw new Error('Service workers are unavailable here (a secure context — https or localhost — is required).');
+  const id = options.id ?? randomId();
+  if (!PREVIEW_ID.test(id)) throw new Error(`Preview id "${id}" may only contain letters, digits, "_" and "-".`);
 
-  const scriptUrl = new URL(options.serviceWorkerUrl, location.href);
-  const scope = new URL(options.scope ?? './', scriptUrl).pathname;
-  const registration = await container.register(scriptUrl.href, { scope });
-  await waitForActive(registration);
+  const transport = options.relayUrl
+    ? await relayTransport(options.relayUrl)
+    : await sameOriginTransport((options as SameOriginOptions).serviceWorkerUrl, options.scope);
 
-  const id = options.id ?? randomId();
-  const base = previewBase(scope, id);
+  const base = previewBase(transport.scope, id);
   const fs = new VirtualFileSystem();
-  const transformer = options.transformer ?? (await createEsbuildWasmTransformer());
-  const server = new DevServer({ fs, transformer, base, cdn: options.cdn, attribution: options.attribution });
+  const components = options.components ?? createCdnComponentCompilers();
+  let server: DevServer;
+  try {
+    const transformer = options.transformer ?? (await createEsbuildWasmTransformer());
+    server = new DevServer({ fs, transformer, base, cdn: options.cdn, components, attribution: options.attribution });
+  } catch (error) {
+    transport.dispose();
+    throw error;
+  }
+
+  const previewUrl = new URL(base, transport.origin).href;
+  // In relay mode processes run on the preview origin (the relay starts them), never the host's.
+  const node = { ...options.node, createWorker: options.node?.createWorker ?? transport.createWorker?.bind(transport) };
+  const processes = createProcessHost({ fs, base, origin: transport.origin, previewUrl, options: node });
 
-  const attach = (worker: ServiceWorker) => {
+  const answer = async (request: WireRequest) =>
+    isPortPath(request.path) ? servePortRequest(processes, request) : toWire(request.reqId, await server.handle(request.path, request.search));
+
+  const attach = () => {
     const channel = new MessageChannel();
     channel.port1.onmessage = async (event) => {
       if (!isWireRequest(event.data)) return;
-      const { message, transfer } = toWire(event.data.reqId, await server.handle(event.data.path, event.data.search));
+      const { message, transfer } = await answer(event.data);
       channel.port1.postMessage(message, transfer);
     };
-    worker.postMessage({ type: ATTACH, id }, [channel.port2]);
+    transport.attach(id, channel.port2);
   };
-  attach(registration.active!);
+  attach();
+  const stopReattach = transport.onReattach((wanted) => {
+    if (wanted === id) attach();
+  });
 
-  const onWorkerMessage = (event: MessageEvent) => {
-    if (event.data?.type === REATTACH && event.data.id === id && registration.active) attach(registration.active);
-  };
-  container.addEventListener('message', onWorkerMessage);
+  // Live reload: any change to the files reloads every frame showing this preview.
+  let reloadTimer: ReturnType<typeof setTimeout> | undefined;
+  const stopWatching = options.liveReload === false
+    ? undefined
+    : fs.watch(() => {
+      clearTimeout(reloadTimer);
+      reloadTimer = setTimeout(() => transport.reload(base), RELOAD_DEBOUNCE_MS);
+    });
 
   const errorListeners = new Set<(error: PreviewError) => void>();
   const onWindowMessage = (event: MessageEvent) => {
     const data = event.data as Partial<PreviewError> & { type?: string };
     if (data?.type !== ERROR_MESSAGE_TYPE || typeof data.href !== 'string') return;
-    if (!new URL(data.href).pathname.startsWith(base)) return; // another runtime's preview
+    if (event.origin !== transport.origin || !new URL(data.href).pathname.startsWith(base)) return; // another runtime's preview
     const error: PreviewError = { message: String(data.message ?? ''), stack: data.stack, href: data.href };
     for (const listener of errorListeners) listener(error);
   };
@@ -120,19 +193,29 @@ export async function bootPreviewRuntime(options: BootOptions): Promise<PreviewR
 
   return {
     id,
-    url: new URL(base, location.origin).href,
+    url: previewUrl,
     fs,
     server,
     mount: (files) => fs.mount(files),
     profile: () => server.profile(),
+    async build(buildOptions = {}) {
+      const bundler = options.bundler ?? (await createEsbuildWasmBundler());
+      return buildProject({ files: fs, bundler, cdn: options.cdn, components, base: buildOptions.base, minify: buildOptions.minify });
+    },
     onError(listener) {
       errorListeners.add(listener);
       return () => errorListeners.delete(listener);
     },
+    spawn: (command: string, args?: string[] | SpawnOptions, spawnOptions?: SpawnOptions) => processes.spawn(command, args as string[], spawnOptions),
+    on: ((event: 'server-ready' | 'port', listener: (...args: any[]) => void) => processes.on(event as 'port', listener)) as PreviewRuntime['on'],
     dispose() {
-      container.removeEventListener('message', onWorkerMessage);
+      processes.dispose();
       window.removeEventListener('message', onWindowMessage);
       errorListeners.clear();
+      clearTimeout(reloadTimer);
+      stopWatching?.();
+      stopReattach();
+      transport.dispose();
       server.dispose();
     },
   };

package/src/index.ts

@@ -1,8 +1,22 @@
 export { bootPreviewRuntime } from './host.js';
-export type { BootOptions, PreviewRuntime, PreviewError } from './host.js';
-export { createEsbuildWasmTransformer } from './esbuildWasm.js';
+export type {
+  BootOptions,
+  SameOriginOptions,
+  RelayOptions,
+  CommonBootOptions,
+  PreviewRuntime,
+  PreviewError,
+  RuntimeBuildOptions,
+} from './host.js';
+export type { PreviewTransport } from './transport.js';
+export { createEsbuildWasmTransformer, createEsbuildWasmBundler, loadEsbuildWasm } from './esbuildWasm.js';
 export type { EsbuildWasmOptions } from './esbuildWasm.js';
+export { createCdnComponentCompilers, defaultVueCompilerUrl, defaultSvelteCompilerUrl } from './componentCompilers.js';
+export type { CdnComponentCompilerOptions } from './componentCompilers.js';
+export { createCacheStoragePackageCache } from './packageCache.js';
+export { ProcessHost, createWorkerProcess } from './node/index.js';
+export type { NodeRuntimeOptions, ProcessHostOptions, WorkerLike } from './node/index.js';
 export { createSwRouter } from './swRouter.js';
-export type { SwRouter, SwRouterOptions, PortLike, PreviewTarget, RoutedResponse } from './swRouter.js';
-export { previewBase, previewPrefix, PREVIEW_SEGMENT } from './protocol.js';
+export type { SwRouter, SwRouterOptions, PortLike, PreviewTarget, RoutedResponse, RequestDetails } from './swRouter.js';
+export { previewBase, previewPrefix, PREVIEW_SEGMENT, PREVIEW_ID, PORT_SEGMENT, isPortPath } from './protocol.js';
 export * from '@seanhogg/builderforce-webcontainers-core';

package/src/node/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Glue between the preview runtime and the Node process host: options, the
+ * default Worker, and answering `/__port/<n>/…` preview requests from the
+ * virtual server listening on that port.
+ */
+import { parsePortPath, type VirtualFileSystem } from '@seanhogg/builderforce-webcontainers-core';
+import type { WireRequest, WireResponse } from '../protocol.js';
+import { ProcessHost, type WorkerLike } from './processHost.js';
+
+export { ProcessHost } from './processHost.js';
+export type { ProcessHostOptions, WorkerLike } from './processHost.js';
+export { createWorkerProcess } from './workerProcess.js';
+
+export interface NodeRuntimeOptions {
+  /**
+   * Where this package's `dist/node/worker.js` is served. Default: resolved
+   * beside this module (`new URL('./worker.js', import.meta.url)`), which
+   * bundlers that understand `new Worker(new URL(…))` handle automatically.
+   */
+  workerUrl?: string | URL;
+  /** Build each process Worker yourself (CSP, a test double). Wins over `workerUrl`. */
+  createWorker?: () => WorkerLike;
+  /** npm registry. Default https://registry.npmjs.org (it sends CORS headers). */
+  registry?: string;
+  /** Cache npm tarballs in Cache Storage. Default true. */
+  packageCache?: boolean;
+  /** Extra environment for every process. */
+  env?: Record<string, string>;
+  /** Grace period before a killed process's worker is terminated. Default 2000ms. */
+  killGraceMs?: number;
+}
+
+export function createProcessHost(args: { fs: VirtualFileSystem; base: string; origin: string; previewUrl: string; options?: NodeRuntimeOptions }): ProcessHost {
+  const { options = {} } = args;
+  const createWorker =
+    options.createWorker ??
+    (() => new Worker(options.workerUrl ?? new URL('./worker.js', import.meta.url), { name: 'bfwc-process' }) as unknown as WorkerLike);
+  return new ProcessHost({
+    fs: args.fs,
+    createWorker,
+    previewOrigin: args.origin,
+    previewBase: args.base,
+    previewUrl: args.previewUrl,
+    registry: options.registry,
+    packageCache: options.packageCache,
+    env: options.env,
+    killGraceMs: options.killGraceMs,
+  });
+}
+
+const TEXT = { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' };
+
+/** Answer a preview request addressed to a virtual server. */
+export async function servePortRequest(host: ProcessHost, request: WireRequest): Promise<{ message: WireResponse; transfer: Transferable[] }> {
+  const target = parsePortPath(request.path)!;
+  const response = await host.request(target.port, {
+    method: request.method ?? 'GET',
+    url: target.path + request.search,
+    headers: request.headers ?? {},
+    body: request.body ? new Uint8Array(request.body) : null,
+  });
+  if (!response) {
+    return { message: { type: 'response', reqId: request.reqId, status: 502, headers: TEXT, body: `Nothing is listening on port ${target.port}. Start a server (node server.js) first.` }, transfer: [] };
+  }
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(response.headers)) headers[key] = Array.isArray(value) ? value.join(', ') : String(value);
+  const body = response.body.slice().buffer as ArrayBuffer;
+  return { message: { type: 'response', reqId: request.reqId, status: response.status, headers, body }, transfer: [body] };
+}