@seanhogg/builderforce-webcontainers 2026.10.4 → 2026.10.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-webcontainers",
-  "version": "2026.10.4",
+  "version": "2026.10.6",
   "description": "BuilderForce WebContainers — browser runtime. Boots an in-browser dev server for a project held in memory and serves it to an iframe through a service worker. Open source, no COOP/COEP, no session caps.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -65,7 +65,7 @@
   },
   "dependencies": {
     "esbuild-wasm": "^0.24.0",
-    "@seanhogg/builderforce-webcontainers-core": "^2026.10.4"
+    "@seanhogg/builderforce-webcontainers-core": "^2026.10.6"
   },
   "devDependencies": {
     "@vue/compiler-sfc": "^3.5.0",

package/src/check/index.ts

@@ -48,7 +48,7 @@ export function checkInputs(files: VirtualFileSystem | FlatFiles): Record<string
   if (files instanceof VirtualFileSystem) fs = files;
   else {
     fs = new VirtualFileSystem();
-    fs.mount(files);
+    fs.writeTree(files);
   }
   const out: Record<string, string> = {};
   for (const path of fs.list()) if (isCheckInput(path)) out[path.slice(1)] = fs.readText(path) ?? '';

package/src/host.ts

@@ -6,13 +6,14 @@ import {
   type BuildResult,
   type Bundler,
   type ComponentCompilers,
-  type FileSystemTree,
-  type FlatFiles,
+  type FileTree,
   type PackageCdnFactory,
+  type PortChange,
+  type ProcessOptions,
   type ProjectProfile,
+  type RuntimeProcess,
+  type ServerAddress,
   type Transformer,
-  type SpawnOptions,
-  type WebContainerProcess,
 } from '@seanhogg/builderforce-webcontainers-core';
 import { PREVIEW_ID, isPortPath, isWireRequest, previewBase, type WireRequest, type WireResponse } from './protocol.js';
 import { createProcessHost, servePortRequest, type NodeRuntimeOptions } from './node/index.js';
@@ -41,9 +42,9 @@ export interface RelayOptions {
   scope?: never;
 }
 
-export type BootOptions = (SameOriginOptions | RelayOptions) & CommonBootOptions;
+export type PreviewRuntimeOptions = (SameOriginOptions | RelayOptions) & CommonRuntimeOptions;
 
-export interface CommonBootOptions {
+export interface CommonRuntimeOptions {
   /** Compiler. Defaults to esbuild-wasm. */
   transformer?: Transformer;
   /** Package CDN factory, for previews (`dev: true`) and builds (`dev: false`). Defaults to esm.sh. */
@@ -58,7 +59,7 @@ export interface CommonBootOptions {
   attribution?: boolean;
   /** Reload open previews when files change. Default true. */
   liveReload?: boolean;
-  /** The Node runtime behind `spawn` (process workers, npm registry). */
+  /** The Node runtime behind `run` (process workers, npm registry). */
   node?: NodeRuntimeOptions;
 }
 
@@ -84,7 +85,8 @@ export interface PreviewRuntime {
   readonly url: string;
   readonly fs: VirtualFileSystem;
   readonly server: DevServer;
-  mount(files: FileSystemTree | FlatFiles): void;
+  /** Write files into the runtime (nested or flat; see `FileTree`). Open previews reload. */
+  writeTree(files: FileTree): void;
   /** Whether this runtime can serve the mounted project, and why not. */
   profile(): ProjectProfile;
   /**
@@ -96,17 +98,16 @@ export interface PreviewRuntime {
   /** 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.
+   * Run a command — `node server.js`, `npm install`, `npm run dev`, `bfsh` for a
+   * terminal — in its own Web Worker. 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;
+  run(command: string, args?: string[], options?: ProcessOptions): RuntimeProcess;
+  run(command: string, options?: ProcessOptions): RuntimeProcess;
+  /** A process started listening (or a dev script handed off to the preview); `url` loads it in an iframe. */
+  onServerListening(listener: (server: ServerAddress) => void): () => void;
+  /** A virtual server opened or closed its port. */
+  onPortChange(listener: (change: PortChange) => void): () => void;
   dispose(): void;
 }
 
@@ -130,7 +131,7 @@ export function toWire(reqId: number, served: Awaited<ReturnType<DevServer['hand
  * 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> {
+export async function startPreviewRuntime(options: PreviewRuntimeOptions): Promise<PreviewRuntime> {
   const id = options.id ?? randomId();
   if (!PREVIEW_ID.test(id)) throw new Error(`Preview id "${id}" may only contain letters, digits, "_" and "-".`);
 
@@ -196,7 +197,7 @@ export async function bootPreviewRuntime(options: BootOptions): Promise<PreviewR
     url: previewUrl,
     fs,
     server,
-    mount: (files) => fs.mount(files),
+    writeTree: (files) => fs.writeTree(files),
     profile: () => server.profile(),
     async build(buildOptions = {}) {
       const bundler = options.bundler ?? (await createEsbuildWasmBundler());
@@ -206,8 +207,9 @@ export async function bootPreviewRuntime(options: BootOptions): Promise<PreviewR
       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'],
+    run: (command: string, args?: string[] | ProcessOptions, runOptions?: ProcessOptions) => processes.run(command, args as string[], runOptions),
+    onServerListening: (listener) => processes.servers.onListening(listener),
+    onPortChange: (listener) => processes.servers.onPortChange(listener),
     dispose() {
       processes.dispose();
       window.removeEventListener('message', onWindowMessage);

package/src/index.ts

@@ -1,9 +1,9 @@
-export { bootPreviewRuntime } from './host.js';
+export { startPreviewRuntime } from './host.js';
 export type {
-  BootOptions,
+  PreviewRuntimeOptions,
   SameOriginOptions,
   RelayOptions,
-  CommonBootOptions,
+  CommonRuntimeOptions,
   PreviewRuntime,
   PreviewError,
   RuntimeBuildOptions,

package/src/node/processHost.ts

@@ -9,15 +9,17 @@
 import {
   DEFAULT_ENV,
   PortRegistry,
+  ServerEvents,
   allocatePid,
-  toWebContainerProcess,
+  runArguments,
+  toRuntimeProcess,
   type ChildHandle,
   type FsChange,
   type HttpRequestData,
   type HttpResponseData,
-  type SpawnOptions,
+  type ProcessOptions,
+  type RuntimeProcess,
   type VirtualFileSystem,
-  type WebContainerProcess,
 } from '@seanhogg/builderforce-webcontainers-core';
 import type { FsOp, HostToWorker, WorkerToHost } from './protocol.js';
 import { portPath } from './protocol.js';
@@ -63,9 +65,9 @@ interface Proc {
 
 export class ProcessHost {
   readonly ports = new PortRegistry();
+  /** Servers listening, ports opening and closing. */
+  readonly servers = new ServerEvents();
   private readonly procs = new Set<Proc>();
-  private readonly serverReady = new Set<(port: number, url: string) => void>();
-  private readonly portListeners = new Set<(port: number, type: 'open' | 'close', url: string) => void>();
   private applyingFrom?: Proc;
   private flushScheduled = false;
   private nextReq = 1;
@@ -77,8 +79,7 @@ export class ProcessHost {
     this.stopPorts = this.ports.watch(({ type, port }) => {
       const url = this.serverUrl(port);
       for (const proc of this.procs) this.post(proc, { type: 'ports', open: type === 'open' ? [port] : [], closed: type === 'close' ? [port] : [] });
-      for (const l of this.portListeners) l(port, type, url);
-      if (type === 'open') for (const l of this.serverReady) l(port, url);
+      this.servers.portChanged({ type, port, url });
     });
   }
 
@@ -86,13 +87,15 @@ export class ProcessHost {
     return new URL(portPath(this.options.previewBase, port), this.options.previewOrigin).href;
   }
 
-  /** Same shape as `WebContainer#spawn`. */
-  spawn(command: string, args: string[] | SpawnOptions = [], options: SpawnOptions = {}): WebContainerProcess {
-    if (!Array.isArray(args)) [options, args] = [args, []];
-    return toWebContainerProcess(this.spawnChild(command, args, options), !!options.terminal);
+  /** Start a command in its own Web Worker, as a stream-based {@link RuntimeProcess}. */
+  run(command: string, args?: string[], options?: ProcessOptions): RuntimeProcess;
+  run(command: string, options?: ProcessOptions): RuntimeProcess;
+  run(command: string, argsOrOptions?: string[] | ProcessOptions, maybeOptions?: ProcessOptions): RuntimeProcess {
+    const [args, options] = runArguments(argsOrOptions, maybeOptions);
+    return toRuntimeProcess(this.spawnChild(command, args, options), !!options.terminal);
   }
 
-  spawnChild(command: string, args: string[] = [], options: SpawnOptions = {}): ChildHandle {
+  spawnChild(command: string, args: string[] = [], options: ProcessOptions = {}): ChildHandle {
     const pid = allocatePid();
     const worker = this.options.createWorker();
     let resolveExit!: (code: number) => void;
@@ -156,14 +159,6 @@ export class ProcessHost {
     return this.ports.request(port, request);
   }
 
-  on(event: 'server-ready', listener: (port: number, url: string) => void): () => void;
-  on(event: 'port', listener: (port: number, type: 'open' | 'close', url: string) => void): () => void;
-  on(event: 'server-ready' | 'port', listener: (...args: any[]) => void): () => void {
-    const set = (event === 'server-ready' ? this.serverReady : this.portListeners) as Set<(...args: any[]) => void>;
-    set.add(listener);
-    return () => set.delete(listener);
-  }
-
   dispose(): void {
     for (const proc of [...this.procs]) {
       proc.worker.terminate();
@@ -291,8 +286,8 @@ export class ProcessHost {
       case 'loopback':
         void this.ports.request(message.port, message.request).then((response) => this.post(proc, { type: 'loopback-response', reqId: message.reqId, response: response ?? null }));
         return;
-      case 'server-ready':
-        for (const l of this.serverReady) l(message.port, message.url);
+      case 'listening':
+        this.servers.announce({ port: message.port, url: message.url });
         return;
     }
   }

package/src/node/protocol.ts

@@ -55,7 +55,7 @@ export type WorkerToHost =
   | { 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 };
+  | { type: 'listening'; port: number; url: string };
 
 /** The preview-relative URL a virtual server on `port` is reachable at. */
 export function portPath(previewBase: string, port: number): string {

package/src/node/workerProcess.ts

@@ -144,7 +144,7 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
         });
       },
       serverUrl: (port) => new URL(portPath(message.previewBase, port), message.previewOrigin).href,
-      announceServer: (port, url) => deps.post({ type: 'server-ready', port, url }),
+      announceServer: (port, url) => deps.post({ type: 'listening', port, url }),
       previewUrl: message.previewUrl,
       registry: message.registry,
       packageCache: message.packageCache ? deps.packageCache?.() : undefined,
@@ -154,7 +154,7 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
 
     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: 'stderr', data: `bfsh: command not found: ${message.command}\n` });
       deps.post({ type: 'exit', code: 127 });
       return;
     }