@seanhogg/builderforce-webcontainers-core 2026.10.5 → 2026.10.7

package/dist/system/serverEvents.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Who hears about servers in a runtime: a port opening or closing, and a
+ * server becoming reachable (which a dev-server handoff announces without
+ * opening a port). One instance per runtime — the core `Kernel` and the
+ * browser's process host both own one, so the listener contract is the same.
+ */
+export interface ServerAddress {
+    port: number;
+    /** Where a browser reaches it (the preview URL for that port). */
+    url: string;
+}
+export interface PortChange extends ServerAddress {
+    type: 'open' | 'close';
+}
+export declare class ServerEvents {
+    private readonly listening;
+    private readonly changes;
+    /** A server started listening (or a dev script handed off to the preview); `url` loads it in an iframe. */
+    onListening(listener: (server: ServerAddress) => void): () => void;
+    /** A virtual server opened or closed its port. */
+    onPortChange(listener: (change: PortChange) => void): () => void;
+    /** Report a port table change; an opened port is also a server listening. */
+    portChanged(change: PortChange): void;
+    /** Report a reachable server that did not open a port of its own. */
+    announce(server: ServerAddress): void;
+}
+//# sourceMappingURL=serverEvents.d.ts.map

package/dist/system/serverEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverEvents.d.ts","sourceRoot":"","sources":["../../src/system/serverEvents.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8C;IACxE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IAEnE,2GAA2G;IAC3G,WAAW,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlE,kDAAkD;IAClD,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;IAKhE,6EAA6E;IAC7E,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKrC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;CAGtC"}

package/dist/system/serverEvents.js

@@ -0,0 +1,33 @@
+/**
+ * Who hears about servers in a runtime: a port opening or closing, and a
+ * server becoming reachable (which a dev-server handoff announces without
+ * opening a port). One instance per runtime — the core `Kernel` and the
+ * browser's process host both own one, so the listener contract is the same.
+ */
+export class ServerEvents {
+    listening = new Set();
+    changes = new Set();
+    /** A server started listening (or a dev script handed off to the preview); `url` loads it in an iframe. */
+    onListening(listener) {
+        this.listening.add(listener);
+        return () => this.listening.delete(listener);
+    }
+    /** A virtual server opened or closed its port. */
+    onPortChange(listener) {
+        this.changes.add(listener);
+        return () => this.changes.delete(listener);
+    }
+    /** Report a port table change; an opened port is also a server listening. */
+    portChanged(change) {
+        for (const listener of this.changes)
+            listener(change);
+        if (change.type === 'open')
+            this.announce({ port: change.port, url: change.url });
+    }
+    /** Report a reachable server that did not open a port of its own. */
+    announce(server) {
+        for (const listener of this.listening)
+            listener(server);
+    }
+}
+//# sourceMappingURL=serverEvents.js.map

package/dist/system/serverEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverEvents.js","sourceRoot":"","sources":["../../src/system/serverEvents.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,MAAM,OAAO,YAAY;IACN,SAAS,GAAG,IAAI,GAAG,EAAmC,CAAC;IACvD,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEnE,2GAA2G;IAC3G,WAAW,CAAC,QAAyC;QACnD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,kDAAkD;IAClD,YAAY,CAAC,QAAsC;QACjD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,6EAA6E;IAC7E,WAAW,CAAC,MAAkB;QAC5B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,OAAO;YAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;YAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,qEAAqE;IACrE,QAAQ,CAAC,MAAqB;QAC5B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS;YAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1D,CAAC;CACF"}

package/dist/system/types.d.ts

@@ -21,7 +21,7 @@ export interface ProgramIO {
     /** Present when attached to a terminal (xterm.js). */
     terminal?: TerminalPort;
 }
-export interface SpawnOptions {
+export interface ProcessOptions {
     cwd?: string;
     env?: Record<string, string>;
     /** Attach to a terminal of this size (`isTTY`, line discipline, `\r\n` output). */
@@ -30,7 +30,7 @@ export interface SpawnOptions {
         rows: number;
     };
 }
-/** A child as its parent sees it (separate stdout/stderr, unlike the public API). */
+/** A child as its parent sees it (separate stdout/stderr listeners, unlike the streams of the public `RuntimeProcess`). */
 export interface ChildHandle {
     readonly pid: number;
     onStdout(listener: (chunk: string) => void): () => void;
@@ -59,7 +59,7 @@ export interface System {
     fs: VirtualFileSystem;
     /** Outbound network (registry, `http.request`, `fetch`). */
     fetch(input: string, init?: RequestInit): Promise<Response>;
-    spawn(command: string, args: string[], options?: SpawnOptions): ChildHandle;
+    spawn(command: string, args: string[], options?: ProcessOptions): ChildHandle;
     /** Register a virtual server; throws `EADDRINUSE`. Port 0 picks a free one. Returns the port and an unlisten. */
     listen(port: number, handler: HttpHandler): {
         port: number;
@@ -69,7 +69,7 @@ export interface System {
     loopback(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined>;
     /** Where a browser reaches a server on `port` (the preview URL), if known. */
     serverUrl(port: number): string | undefined;
-    /** Tell the host a server is ready (`server-ready`); used by the dev-server handoff. */
+    /** Tell the host a server is reachable without opening a port; used by the dev-server handoff. */
     announceServer(port: number, url: string): void;
     /** The in-browser dev server's preview URL, for `vite`/`react-scripts start` handoff. */
     previewUrl?: string;

package/dist/system/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/system/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/system/types.ts"],"names":[],"mappings":"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"}

package/dist/vfs.d.ts

@@ -1,16 +1,18 @@
 export type FileContent = string | Uint8Array;
-/** The nested tree shape `@webcontainer/api`'s `mount()` takes — accepted as-is. */
-export interface FileSystemTree {
-    [name: string]: {
-        file: {
-            contents: FileContent;
-        };
-    } | {
-        directory: FileSystemTree;
-    };
-}
-/** A flat `{ 'src/main.tsx': '...' }` map, the other shape callers commonly hold. */
+/** A flat `{ 'src/main.tsx': '...' }` map: path → contents. */
 export type FlatFiles = Record<string, FileContent>;
+/**
+ * Files to write: a name maps to contents (a file) or to another tree (a
+ * directory). Names may hold slashes, so a {@link FlatFiles} map is a tree too,
+ * and the two styles mix freely: `{ src: { 'main.tsx': '…' }, 'public/a.svg': '…' }`.
+ */
+export interface FileTree {
+    [name: string]: FileContent | FileTree;
+}
+export interface DirectoryEntry {
+    name: string;
+    kind: 'file' | 'directory';
+}
 export interface FsChange {
     /** `mkdir` is an explicitly created (possibly empty) directory. */
     type: 'write' | 'remove' | 'mkdir';
@@ -51,6 +53,14 @@ export declare class VirtualFileSystem {
     mkdir(path: string): void;
     /** Direct children of a directory (files and sub-directories), sorted. */
     readdir(path: string): string[];
+    /** Direct children with their kind, sorted by name — `readdir` for callers that render a tree. */
+    entries(path: string): DirectoryEntry[];
+    /**
+     * Move a file or a directory (with everything under it). Throws when `from` is
+     * missing or `to` already exists. Watchers see the old paths removed and the
+     * new ones written, which is what every consumer (dev server, process sync) needs.
+     */
+    rename(from: string, to: string): void;
     /** Every file path, sorted. */
     list(): string[];
     /** Directories created explicitly with `mkdir` — what `list()` cannot reproduce. */
@@ -61,14 +71,14 @@ export declare class VirtualFileSystem {
     version(path: string): number | undefined;
     /** When the file was last written (epoch ms), or undefined when absent. */
     mtime(path: string): number | undefined;
-    /**
-     * Write many files at once. Takes either the nested WebContainer tree or a flat
-     * path→contents map — or a mix, since each entry is judged on its own.
-     */
-    mount(files: FileSystemTree | FlatFiles, at?: string): void;
+    /** Write many files at once, under `at` (default `/`). A nested object is a directory, created even when empty. */
+    writeTree(files: FileTree, at?: string): void;
     /** Flat snapshot keyed without the leading slash (`src/main.tsx`). */
     toFlat(): FlatFiles;
-    watch(listener: (change: FsChange) => void): () => void;
+    /** Every change, or with `under` only changes at or below that path. */
+    watch(listener: (change: FsChange) => void, options?: {
+        under?: string;
+    }): () => void;
     private removeFile;
     /** Register `key` under its parent, creating implicit ancestors as needed. */
     private link;

package/dist/vfs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vfs.d.ts","sourceRoot":"","sources":["../src/vfs.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9C,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE;YAAE,QAAQ,EAAE,WAAW,CAAA;SAAE,CAAA;KAAE,GAAG;QAAE,SAAS,EAAE,cAAc,CAAA;KAAE,CAAC;CACrF;AAED,qFAAqF;AACrF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAID;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoD;IAC7E,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,KAAK,CAAK;IAElB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI;IAWpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAI/C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM1C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,4EAA4E;IAC5E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAWzB,0EAA0E;IAC1E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAI/B,+BAA+B;IAC/B,IAAI,IAAI,MAAM,EAAE;IAIhB,oFAAoF;IACpF,mBAAmB,IAAI,MAAM,EAAE;IAI/B,6DAA6D;IAC7D,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IActB,4EAA4E;IAC5E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzC,2EAA2E;IAC3E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIvC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,EAAE,EAAE,SAAM,GAAG,IAAI;IAYxD,sEAAsE;IACtE,MAAM,IAAI,SAAS;IAMnB,KAAK,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAKvD,OAAO,CAAC,UAAU;IAQlB,8EAA8E;IAC9E,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,SAAS;IAOjB,2EAA2E;IAC3E,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,IAAI;CAGb"}
+{"version":3,"file":"vfs.d.ts","sourceRoot":"","sources":["../src/vfs.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAID;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoD;IAC7E,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,KAAK,CAAK;IAElB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI;IAWpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAI/C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM1C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,4EAA4E;IAC5E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAWzB,0EAA0E;IAC1E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAI/B,kGAAkG;IAClG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE;IAKvC;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAsBtC,+BAA+B;IAC/B,IAAI,IAAI,MAAM,EAAE;IAIhB,oFAAoF;IACpF,mBAAmB,IAAI,MAAM,EAAE;IAI/B,6DAA6D;IAC7D,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IActB,4EAA4E;IAC5E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzC,2EAA2E;IAC3E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIvC,mHAAmH;IACnH,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,SAAM,GAAG,IAAI;IAW1C,sEAAsE;IACtE,MAAM,IAAI,SAAS;IAMnB,wEAAwE;IACxE,KAAK,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,IAAI,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM,IAAI;IASzF,OAAO,CAAC,UAAU;IAQlB,8EAA8E;IAC9E,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,SAAS;IAOjB,2EAA2E;IAC3E,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,IAAI;CAGb"}

package/dist/vfs.js

@@ -71,6 +71,43 @@ export class VirtualFileSystem {
     readdir(path) {
         return [...(this.children.get(normalizePath(path)) ?? [])].sort();
     }
+    /** Direct children with their kind, sorted by name — `readdir` for callers that render a tree. */
+    entries(path) {
+        const dir = normalizePath(path);
+        return this.readdir(dir).map((name) => ({ name, kind: this.children.has(join(dir, name)) ? 'directory' : 'file' }));
+    }
+    /**
+     * Move a file or a directory (with everything under it). Throws when `from` is
+     * missing or `to` already exists. Watchers see the old paths removed and the
+     * new ones written, which is what every consumer (dev server, process sync) needs.
+     */
+    rename(from, to) {
+        const source = normalizePath(from);
+        const target = normalizePath(to);
+        if (source === target)
+            return;
+        if (!this.exists(source))
+            throw new Error(`ENOENT: no such file or directory, rename '${source}' -> '${target}'`);
+        if (this.exists(target))
+            throw new Error(`EEXIST: file already exists, rename '${source}' -> '${target}'`);
+        if (target.startsWith(source + '/'))
+            throw new Error(`EINVAL: cannot move '${source}' into itself`);
+        if (this.files.has(source)) {
+            const contents = this.files.get(source);
+            this.removeFile(source);
+            this.writeFile(target, contents);
+            return;
+        }
+        const prefix = source + '/';
+        const moved = [...this.files].filter(([path]) => path.startsWith(prefix));
+        const dirs = [...this.explicit].filter((dir) => dir === source || dir.startsWith(prefix));
+        this.rm(source);
+        this.mkdir(target);
+        for (const dir of dirs)
+            this.mkdir(target + dir.slice(source.length));
+        for (const [path, contents] of moved)
+            this.writeFile(target + path.slice(source.length), contents);
+    }
     /** Every file path, sorted. */
     list() {
         return [...this.files.keys()].sort();
@@ -106,20 +143,15 @@ export class VirtualFileSystem {
     mtime(path) {
         return this.mtimes.get(normalizePath(path));
     }
-    /**
-     * Write many files at once. Takes either the nested WebContainer tree or a flat
-     * path→contents map — or a mix, since each entry is judged on its own.
-     */
-    mount(files, at = '/') {
+    /** Write many files at once, under `at` (default `/`). A nested object is a directory, created even when empty. */
+    writeTree(files, at = '/') {
         for (const [name, entry] of Object.entries(files)) {
             const path = join(at, name);
             if (typeof entry === 'string' || entry instanceof Uint8Array)
                 this.writeFile(path, entry);
-            else if ('file' in entry)
-                this.writeFile(path, entry.file.contents);
             else {
                 this.mkdir(path);
-                this.mount(entry.directory, path);
+                this.writeTree(entry, path);
             }
         }
     }
@@ -130,9 +162,14 @@ export class VirtualFileSystem {
             out[path.slice(1)] = contents;
         return out;
     }
-    watch(listener) {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
+    /** Every change, or with `under` only changes at or below that path. */
+    watch(listener, options = {}) {
+        const root = options.under === undefined ? undefined : normalizePath(options.under);
+        const filtered = root === undefined || root === '/'
+            ? listener
+            : (change) => (change.path === root || change.path.startsWith(root + '/')) && listener(change);
+        this.listeners.add(filtered);
+        return () => this.listeners.delete(filtered);
     }
     removeFile(key) {
         this.files.delete(key);

package/dist/vfs.js.map

@@ -1 +1 @@
-{"version":3,"file":"vfs.js","sourceRoot":"","sources":["../src/vfs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vfs.js","sourceRoot":"","sources":["../src/vfs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-webcontainers-core",
-  "version": "2026.10.5",
+  "version": "2026.10.7",
   "description": "BuilderForce WebContainers — core. A runtime-agnostic in-browser dev server: virtual file system, module resolution, import rewriting to a package CDN, CSS/JSON/asset modules and project detection. No COOP/COEP required.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/archive.ts

@@ -0,0 +1,59 @@
+/**
+ * The file system as a zip: one format for "Download project" and for a
+ * snapshot a host stores and restores later (with `node_modules`, so a
+ * restored project needs no reinstall). Empty directories created with `mkdir`
+ * travel as `name/` entries; text comes back as strings, everything else as bytes.
+ */
+import { unzipSync, zipSync, type Zippable } from 'fflate';
+import { VirtualFileSystem } from './vfs.js';
+import { join } from './paths.js';
+
+export interface ZipExportOptions {
+  /** Path prefixes left out (`node_modules`, `dist`), relative to the root, no leading slash. */
+  exclude?: string[];
+  /** 0 (store, fastest) to 9. Default 6. */
+  level?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+}
+
+const encoder = new TextEncoder();
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true });
+
+function excluded(relative: string, exclude: string[]): boolean {
+  return exclude.some((prefix) => {
+    const clean = prefix.replace(/^\/+|\/+$/g, '');
+    return relative === clean || relative.startsWith(clean + '/');
+  });
+}
+
+export function exportZip(fs: VirtualFileSystem, options: ZipExportOptions = {}): Uint8Array {
+  const exclude = options.exclude ?? [];
+  const entries: Zippable = {};
+  for (const dir of fs.explicitDirectories()) {
+    const relative = dir.slice(1);
+    if (!excluded(relative, exclude) && fs.readdir(dir).length === 0) entries[relative + '/'] = new Uint8Array(0);
+  }
+  for (const path of fs.list()) {
+    const relative = path.slice(1);
+    if (excluded(relative, exclude)) continue;
+    const contents = fs.readFile(path)!;
+    entries[relative] = typeof contents === 'string' ? encoder.encode(contents) : contents;
+  }
+  return zipSync(entries, { level: options.level ?? 6 });
+}
+
+/** Write a zip's contents into `fs` under `at` (default `/`), over whatever is there. */
+export function importZip(fs: VirtualFileSystem, zip: Uint8Array, at = '/'): void {
+  for (const [name, bytes] of Object.entries(unzipSync(zip))) {
+    if (name.endsWith('/')) {
+      fs.mkdir(join(at, name.slice(0, -1)));
+      continue;
+    }
+    let contents: string | Uint8Array = bytes;
+    try {
+      contents = strictUtf8.decode(bytes);
+    } catch {
+      // binary: keep the bytes
+    }
+    fs.writeFile(join(at, name), contents);
+  }
+}

package/src/build.ts

@@ -1,4 +1,4 @@
-import { VirtualFileSystem, type FileSystemTree, type FlatFiles } from './vfs.js';
+import { VirtualFileSystem, type FileTree } from './vfs.js';
 import type { Bundler, BundleOutput } from './bundler.js';
 import type { PackageCdnFactory } from './packageCdn.js';
 import { esmShCdnFactory } from './packageCdn.js';
@@ -18,8 +18,8 @@ import { findHtmlEntries, rewriteBuiltHtml } from './buildHtml.js';
  * content hash in its name and can be cached forever.
  */
 export interface BuildOptions {
-  /** The project: a file system, or files as `mount()` takes them. */
-  files: VirtualFileSystem | FlatFiles | FileSystemTree;
+  /** The project: a file system, or files as `writeTree()` takes them. */
+  files: VirtualFileSystem | FileTree;
   bundler: Bundler;
   /** Package CDN factory (called with `dev: false`). Default: esm.sh. */
   cdn?: PackageCdnFactory;
@@ -50,7 +50,7 @@ const encoder = new TextEncoder();
 function toFileSystem(files: BuildOptions['files']): VirtualFileSystem {
   if (files instanceof VirtualFileSystem) return files;
   const fs = new VirtualFileSystem();
-  fs.mount(files);
+  fs.writeTree(files);
   return fs;
 }
 

package/src/check/typecheck.ts

@@ -1,5 +1,5 @@
 import type * as TS from 'typescript';
-import { VirtualFileSystem, type FileSystemTree, type FlatFiles } from '../vfs.js';
+import { VirtualFileSystem, type FileTree } from '../vfs.js';
 import { readProjectConfig } from '../projectConfig.js';
 import { isBareSpecifier, resolveAlias, splitPackageSpecifier } from '../resolve.js';
 import { acquireExtendedConfigs, acquireTypes, type FetchLike } from './acquire.js';
@@ -46,10 +46,10 @@ interface Reach {
   libFiles: Set<string>;
 }
 
-function toFileSystem(files: VirtualFileSystem | FlatFiles | FileSystemTree): VirtualFileSystem {
+function toFileSystem(files: VirtualFileSystem | FileTree): VirtualFileSystem {
   if (files instanceof VirtualFileSystem) return files;
   const fs = new VirtualFileSystem();
-  fs.mount(files);
+  fs.writeTree(files);
   return fs;
 }
 
@@ -78,7 +78,7 @@ function collectReach(ts: typeof TS, fs: VirtualFileSystem, projects: CheckProje
 
 export async function typecheckProject(
   ts: typeof TS,
-  files: VirtualFileSystem | FlatFiles | FileSystemTree,
+  files: VirtualFileSystem | FileTree,
   options: TypecheckOptions,
 ): Promise<TypecheckResult> {
   const fs = toFileSystem(files);

package/src/devServer.ts

@@ -30,6 +30,8 @@ export interface DevServerOptions {
   components?: ComponentCompilers;
   /** The "Built with Builderforce.ai" badge in served pages. Default true. */
   attribution?: boolean;
+  /** Host scripts (JavaScript source) run in every preview page before the app. */
+  previewScripts?: readonly string[];
 }
 
 const NO_STORE = { 'cache-control': 'no-store' };
@@ -81,9 +83,11 @@ export class DevServer {
   private profileCache?: ProjectProfile;
   private readonly cache = new Map<string, { version: number; file: ServedFile }>();
   private readonly unwatch: () => void;
+  private previewScripts: readonly string[];
 
   constructor(private readonly options: DevServerOptions) {
     if (!options.base.endsWith('/')) throw new Error('DevServer base must end with "/"');
+    this.previewScripts = options.previewScripts ?? [];
     this.unwatch = options.fs.watch((change) => this.onChange(change));
   }
 
@@ -92,6 +96,12 @@ export class DevServer {
     this.cache.clear();
   }
 
+  /** Replace the host scripts injected into preview pages; takes effect on the next page load. */
+  setPreviewScripts(scripts: readonly string[]): void {
+    this.previewScripts = [...scripts];
+    for (const key of [...this.cache.keys()]) if (/\.html?\?/.test(key)) this.cache.delete(key);
+  }
+
   profile(): ProjectProfile {
     return (this.profileCache ??= detectProject(this.options.fs));
   }
@@ -136,7 +146,7 @@ export class DevServer {
       if (loaderFor(ext)) return reply(200, JS_MIME, await compileScript(await this.context(), file));
       if (isScriptPath(file)) return reply(200, JS_MIME, await compileComponent(await this.context(), file));
       if (ext === '.html' || ext === '.htm') {
-        return reply(200, mimeFor(ext), transformHtml(fs.readText(file) ?? '', { base, attribution: this.options.attribution }));
+        return reply(200, mimeFor(ext), transformHtml(fs.readText(file) ?? '', { base, attribution: this.options.attribution, scripts: this.previewScripts }));
       }
       return reply(200, mimeFor(ext), fs.readFile(file) ?? '');
     } catch (error) {
@@ -151,7 +161,7 @@ export class DevServer {
     }
     const html = this.options.fs.readText(profile.htmlPath) ?? '';
     const { base, attribution } = this.options;
-    return reply(200, 'text/html; charset=utf-8', transformHtml(html, { base, entry: profile.entry, attribution }));
+    return reply(200, 'text/html; charset=utf-8', transformHtml(html, { base, entry: profile.entry, attribution, scripts: this.previewScripts }));
   }
 
   private async context(): Promise<CompileContext> {

package/src/html.ts

@@ -4,18 +4,24 @@
  *     base, since the preview is served from a sub-path, not the origin root;
  *   • CRA's `%PUBLIC_URL%` placeholder is filled;
  *   • a page with no module script (CRA) gets its entry injected;
- *   • the error bridge is prepended, so runtime errors reach the host;
+ *   • the error bridge is prepended, so runtime errors and console output reach the host;
+ *   • the host's preview scripts run next, before the app;
  *   • the live-reload listener is prepended, so an edit re-renders the preview;
  *   • the attribution badge is appended unless the host turned it off.
  */
 import { injectAttribution } from './attribution.js';
 
 export const ERROR_MESSAGE_TYPE = 'bfwc:error';
+export const CONSOLE_MESSAGE_TYPE = 'bfwc:console';
+/** Console messages forwarded per page load; past this the bridge goes quiet (a log loop must not flood the host). */
+export const CONSOLE_MESSAGE_LIMIT = 1000;
 
 /**
- * Runs first in the preview. Forwards uncaught errors and rejections to the host
- * page (`window.parent`), which is how an editor — or an agent — learns the app
- * crashed without scraping the iframe.
+ * Runs first in the preview. Forwards uncaught errors and rejections, and the
+ * app's console output, to the host page (`window.parent`): how an editor — or
+ * an agent — learns what the app did without scraping the iframe. Console
+ * arguments are flattened to text (errors with their stack, objects as JSON),
+ * each message capped at 4,000 characters.
  */
 export function errorBridgeScript(): string {
   return `<script>(function(){
@@ -24,6 +30,22 @@ export function errorBridgeScript(): string {
   };
   addEventListener('error', function (e) { send(e.message, e.error && e.error.stack); });
   addEventListener('unhandledrejection', function (e) { var r = e.reason; send(r && r.message ? r.message : r, r && r.stack); });
+  var sent = 0;
+  var text = function (value) {
+    if (typeof value === 'string') return value;
+    if (value instanceof Error) return value.stack || String(value);
+    try { var json = JSON.stringify(value); return json === undefined ? String(value) : json; } catch (_) { return String(value); }
+  };
+  ['log', 'info', 'warn', 'error', 'debug'].forEach(function (level) {
+    var original = console[level];
+    console[level] = function () {
+      if (sent < ${CONSOLE_MESSAGE_LIMIT}) {
+        sent++;
+        try { parent.postMessage({ type: ${JSON.stringify(CONSOLE_MESSAGE_TYPE)}, level: level, text: Array.prototype.map.call(arguments, text).join(' ').slice(0, 4000), href: location.href }, '*'); } catch (_) {}
+      }
+      return original.apply(console, arguments);
+    };
+  });
   window.process = window.process || { env: { NODE_ENV: 'development' } };
 })();</script>`;
 }
@@ -55,8 +77,13 @@ export interface HtmlOptions {
   entry?: string;
   /** The "Built with Builderforce.ai" badge. On unless explicitly `false`. */
   attribution?: boolean;
+  /** Host scripts (JavaScript source) run in every preview page before the app. */
+  scripts?: readonly string[];
 }
 
+/** `</script>` inside a script body would end the tag early. */
+const scriptTag = (source: string) => `<script>${source.replace(/<\/script/gi, '<\\/script')}</script>`;
+
 export function transformHtml(html: string, options: HtmlOptions): string {
   const { base } = options;
   // `%PUBLIC_URL%/logo.png` becomes root-absolute here and is re-rooted once below;
@@ -70,7 +97,7 @@ export function transformHtml(html: string, options: HtmlOptions): string {
   }
   if (options.attribution !== false) out = injectAttribution(out);
 
-  const bridge = `${errorBridgeScript()}\n${liveReloadScript(base)}`;
+  const bridge = [errorBridgeScript(), liveReloadScript(base), ...(options.scripts ?? []).map(scriptTag)].join('\n');
   if (/<head[^>]*>/i.test(out)) return out.replace(/<head[^>]*>/i, (head) => `${head}\n${bridge}`);
   return bridge + out;
 }

package/src/index.ts

@@ -1,5 +1,8 @@
 export { VirtualFileSystem } from './vfs.js';
-export type { FileContent, FileSystemTree, FlatFiles, FsChange } from './vfs.js';
+export type { FileContent, FileTree, FlatFiles, FsChange } from './vfs.js';
+export type { DirectoryEntry } from './vfs.js';
+export { exportZip, importZip } from './archive.js';
+export type { ZipExportOptions } from './archive.js';
 export { normalizePath, dirname, basename, join, extname } from './paths.js';
 export { DevServer } from './devServer.js';
 export type { DevServerOptions, ServedFile } from './devServer.js';
@@ -41,7 +44,7 @@ export { rewriteImports } from './rewriteImports.js';
 export { resolveLocal, resolveAlias, isBareSpecifier, splitPackageSpecifier, resolvePackage, RESOLVE_EXTENSIONS } from './resolve.js';
 export { compileScript, compileModule, isScriptPath, mapSpecifier, moduleUrl, buildDefine } from './compileScript.js';
 export { compileComponent } from './compileComponent.js';
-export { transformHtml, errorBridgeScript, liveReloadScript, reloadChannelName, ERROR_MESSAGE_TYPE } from './html.js';
+export { transformHtml, errorBridgeScript, liveReloadScript, reloadChannelName, ERROR_MESSAGE_TYPE, CONSOLE_MESSAGE_TYPE, CONSOLE_MESSAGE_LIMIT } from './html.js';
 export { mimeFor } from './mime.js';
 export { attributionScript, injectAttribution, ATTRIBUTION_URL, ATTRIBUTION_LABEL } from './attribution.js';
 export type { AttributionOptions } from './attribution.js';

package/src/installer/index.ts

@@ -1,5 +1,7 @@
 export { installPackages, chooseVersion } from './install.js';
 export type { InstallOptions, InstallResult, InstallProgress } from './install.js';
+export { parseNpmrc, readNpmConfig, registryFor, authHeaders, emptyNpmConfig } from './npmrc.js';
+export type { NpmConfig } from './npmrc.js';
 export { RegistryClient, createMemoryCache, verifyIntegrity, DEFAULT_REGISTRY } from './registry.js';
 export type { FetchLike, PackageCache, PackageManifest, Packument, RegistryOptions, BinField } from './registry.js';
 export { resolveTree, childLocation, parentLocation, PLATFORM } from './tree.js';

package/src/installer/install.ts

@@ -13,6 +13,7 @@ import { gunzipSync } from 'fflate';
 import type { VirtualFileSystem } from '../vfs.js';
 import { join } from '../paths.js';
 import { RegistryClient, type FetchLike, type PackageCache, type PackageManifest, type Packument } from './registry.js';
+import type { NpmConfig } from './npmrc.js';
 import { parseInstallSpec, sortObject, type PackageJson, type ParsedSpec } from './spec.js';
 import { childLocation, parentLocation, resolveTree, type ResolvedPackage } from './tree.js';
 import { buildLockfile, lockMatchesPackage, lockedManifests, parseLockfile, pickLocked, type Lockfile } from './lockfile.js';
@@ -32,6 +33,8 @@ export interface InstallOptions {
   fs: VirtualFileSystem;
   fetch: FetchLike;
   registry?: string;
+  /** `.npmrc` settings: scoped registries and auth tokens. */
+  npmrc?: NpmConfig;
   cache?: PackageCache;
   /** The project directory holding package.json. Default `/`. */
   cwd?: string;
@@ -158,7 +161,7 @@ export async function installPackages(options: InstallOptions): Promise<InstallR
   const pkgPath = join(base, 'package.json');
   const lockPath = join(base, 'package-lock.json');
   const warnings: string[] = [];
-  const client = new RegistryClient({ fetch: options.fetch, registry: options.registry, cache: options.cache, signal });
+  const client = new RegistryClient({ fetch: options.fetch, registry: options.registry ?? options.npmrc?.registry, npmrc: options.npmrc, cache: options.cache, signal });
   const progress = (p: InstallProgress) => options.onProgress?.(p);
 
   let pkg = readJson<PackageJson>(fs, pkgPath);