@seanhogg/builderforce-webcontainers 2026.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Hogg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @seanhogg/builderforce-webcontainers
+
+The browser runtime of
+[BuilderForce WebContainers](https://github.com/SeanHogg/builderforce-webcontainers):
+boot an in-browser dev server and preview the project in an iframe. No COOP/COEP
+headers, no session caps, MIT licensed.
+
+1. Serve `dist/sw.js` from your site, ideally at `/__bfwc/sw.js` so the worker's
+   scope stays off the rest of your app. You can resolve its path with
+   `import.meta.resolve('@seanhogg/builderforce-webcontainers/sw.js')`, or copy it
+   in your build.
+2. Boot and mount:
+
+```ts
+import { bootPreviewRuntime } from '@seanhogg/builderforce-webcontainers';
+
+const runtime = await bootPreviewRuntime({ serviceWorkerUrl: '/__bfwc/sw.js', id: projectId });
+runtime.mount(files);
+if (runtime.profile().supported) iframe.src = runtime.url;
+else showFallback(runtime.profile().reason);
+```
+
+The package re-exports everything from
+[`@seanhogg/builderforce-webcontainers-core`](../core).

package/dist/esbuildWasm.d.ts

@@ -0,0 +1,12 @@
+import { type Transformer } from '@seanhogg/builderforce-webcontainers-core';
+export interface EsbuildWasmOptions {
+    /** Where to fetch esbuild.wasm. Defaults to jsDelivr at the installed version. */
+    wasmURL?: string;
+}
+/**
+ * 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).
+ */
+export declare function createEsbuildWasmTransformer(options?: EsbuildWasmOptions): Promise<Transformer>;
+//# sourceMappingURL=esbuildWasm.d.ts.map

package/dist/esbuildWasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuildWasm.d.ts","sourceRoot":"","sources":["../src/esbuildWasm.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,2CAA2C,CAAC;AAEvG,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAWnG"}

package/dist/esbuildWasm.js

@@ -0,0 +1,20 @@
+import { createEsbuildTransformer } from '@seanhogg/builderforce-webcontainers-core';
+let ready;
+/**
+ * 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).
+ */
+export function createEsbuildWasmTransformer(options = {}) {
+    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);
+    })().catch((error) => {
+        ready = undefined; // let a later call retry (a transient network failure fetching the wasm)
+        throw error;
+    });
+    return ready;
+}
+//# sourceMappingURL=esbuildWasm.js.map

package/dist/esbuildWasm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuildWasm.js","sourceRoot":"","sources":["../src/esbuildWasm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAoB,MAAM,2CAA2C,CAAC;AAOvG,IAAI,KAAuC,CAAC;AAE5C;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,UAA8B,EAAE;IAC3E,KAAK,KAAK,CAAC,KAAK,IAAI,EAAE;QACpB,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,6CAA6C,OAAO,CAAC,OAAO,eAAe,CAAC;QAC/G,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,OAAO,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC5B,KAAK,GAAG,SAAS,CAAC,CAAC,yEAAyE;QAC5F,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/host.d.ts

@@ -0,0 +1,42 @@
+import { DevServer, VirtualFileSystem, type DevServerOptions, type FileSystemTree, type FlatFiles, type ProjectProfile, type Transformer } from '@seanhogg/builderforce-webcontainers-core';
+export interface BootOptions {
+    /** 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;
+    /** 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. */
+    id?: string;
+    /** The "Built with Builderforce.ai" badge in the preview. Default true — please keep it. */
+    attribution?: boolean;
+}
+export interface PreviewError {
+    message: string;
+    stack?: string;
+    href: string;
+}
+export interface PreviewRuntime {
+    readonly id: string;
+    /** Absolute URL to load in the preview iframe. */
+    readonly url: string;
+    readonly fs: VirtualFileSystem;
+    readonly server: DevServer;
+    mount(files: FileSystemTree | FlatFiles): void;
+    /** Whether this runtime can serve the mounted project, and why not. */
+    profile(): ProjectProfile;
+    /** Uncaught errors and rejections raised inside the preview. */
+    onError(listener: (error: PreviewError) => void): () => void;
+    dispose(): void;
+}
+/**
+ * Boot a preview runtime in this page: a virtual file system, a dev server over
+ * 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.
+ */
+export declare function bootPreviewRuntime(options: BootOptions): Promise<PreviewRuntime>;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EAET,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,2CAA2C,CAAC;AAInD,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+CAA+C;IAC/C,GAAG,CAAC,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC9B,qFAAqF;IACrF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4FAA4F;IAC5F,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/C,uEAAuE;IACvE,OAAO,IAAI,cAAc,CAAC;IAC1B,gEAAgE;IAChE,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AA0BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA2DtF"}

package/dist/host.js

@@ -0,0 +1,96 @@
+import { DevServer, ERROR_MESSAGE_TYPE, VirtualFileSystem, } from '@seanhogg/builderforce-webcontainers-core';
+import { ATTACH, REATTACH, isWireRequest, previewBase } from './protocol.js';
+import { createEsbuildWasmTransformer } from './esbuildWasm.js';
+function waitForActive(registration) {
+    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() {
+    return globalThis.crypto?.randomUUID?.().replace(/-/g, '').slice(0, 16) ?? Math.random().toString(36).slice(2, 18);
+}
+function toWire(reqId, served) {
+    if (typeof served.body === 'string') {
+        return { message: { type: 'response', reqId, status: served.status, headers: served.headers, body: served.body }, transfer: [] };
+    }
+    const body = served.body.slice().buffer; // a copy: transferring must not detach the VFS's own bytes
+    return { message: { type: 'response', reqId, status: served.status, headers: served.headers, body }, transfer: [body] };
+}
+/**
+ * Boot a preview runtime in this page: a virtual file system, a dev server over
+ * 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.
+ */
+export async function bootPreviewRuntime(options) {
+    const container = navigator.serviceWorker;
+    if (!container)
+        throw new Error('Service workers are unavailable here (a secure context — https or localhost — is required).');
+    const scriptUrl = new URL(options.serviceWorkerUrl, location.href);
+    const scope = new URL(options.scope ?? './', scriptUrl).pathname;
+    const registration = await container.register(scriptUrl.href, { scope });
+    await waitForActive(registration);
+    const id = options.id ?? randomId();
+    const base = previewBase(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 attach = (worker) => {
+        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));
+            channel.port1.postMessage(message, transfer);
+        };
+        worker.postMessage({ type: ATTACH, id }, [channel.port2]);
+    };
+    attach(registration.active);
+    const onWorkerMessage = (event) => {
+        if (event.data?.type === REATTACH && event.data.id === id && registration.active)
+            attach(registration.active);
+    };
+    container.addEventListener('message', onWorkerMessage);
+    const errorListeners = new Set();
+    const onWindowMessage = (event) => {
+        const data = event.data;
+        if (data?.type !== ERROR_MESSAGE_TYPE || typeof data.href !== 'string')
+            return;
+        if (!new URL(data.href).pathname.startsWith(base))
+            return; // another runtime's preview
+        const error = { message: String(data.message ?? ''), stack: data.stack, href: data.href };
+        for (const listener of errorListeners)
+            listener(error);
+    };
+    window.addEventListener('message', onWindowMessage);
+    return {
+        id,
+        url: new URL(base, location.origin).href,
+        fs,
+        server,
+        mount: (files) => fs.mount(files),
+        profile: () => server.profile(),
+        onError(listener) {
+            errorListeners.add(listener);
+            return () => errorListeners.delete(listener);
+        },
+        dispose() {
+            container.removeEventListener('message', onWorkerMessage);
+            window.removeEventListener('message', onWindowMessage);
+            errorListeners.clear();
+            server.dispose();
+        },
+    };
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { bootPreviewRuntime } from './host.js';
+export type { BootOptions, PreviewRuntime, PreviewError } from './host.js';
+export { createEsbuildWasmTransformer } from './esbuildWasm.js';
+export type { EsbuildWasmOptions } from './esbuildWasm.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 * from '@seanhogg/builderforce-webcontainers-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAChE,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5E,cAAc,2CAA2C,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { bootPreviewRuntime } from './host.js';
+export { createEsbuildWasmTransformer } from './esbuildWasm.js';
+export { createSwRouter } from './swRouter.js';
+export { previewBase, previewPrefix, PREVIEW_SEGMENT } from './protocol.js';
+export * from '@seanhogg/builderforce-webcontainers-core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAEhE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5E,cAAc,2CAA2C,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The wire between the host page (which owns the file system and the dev server)
+ * and the service worker (which owns the network). The worker holds no project
+ * state: every request it intercepts is forwarded over a MessagePort to the page.
+ */
+export declare const PREVIEW_SEGMENT = "__bfwc";
+/** page → worker, with a MessagePort in `ports[0]`: "serve preview `id` over this port". */
+export declare const ATTACH = "bfwc:attach";
+/** worker → pages: "I lost the port for `id` (I was restarted) — attach again". */
+export declare const REATTACH = "bfwc:reattach";
+export interface AttachMessage {
+    type: typeof ATTACH;
+    id: string;
+}
+export interface ReattachMessage {
+    type: typeof REATTACH;
+    id: string;
+}
+export interface WireRequest {
+    type: 'request';
+    reqId: number;
+    path: string;
+    search: string;
+}
+export interface WireResponse {
+    type: 'response';
+    reqId: number;
+    status: number;
+    headers: Record<string, string>;
+    body: string | ArrayBuffer;
+}
+/**
+ * The URL prefix previews live under, for a worker scope. Serving the worker from
+ * `/__bfwc/sw.js` (scope `/__bfwc/`) keeps it off every other page of the host app;
+ * a root-scoped worker still only answers under `/__bfwc/`.
+ */
+export declare function previewPrefix(scopePath: string): string;
+export declare function previewBase(scopePath: string, id: string): string;
+export declare function isWireRequest(value: unknown): value is WireRequest;
+export declare function isWireResponse(value: unknown): value is WireResponse;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,4FAA4F;AAC5F,eAAO,MAAM,MAAM,gBAAgB,CAAC;AACpC,mFAAmF;AACnF,eAAO,MAAM,QAAQ,kBAAkB,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,QAAQ,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAGlE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAGpE"}

package/dist/protocol.js

@@ -0,0 +1,31 @@
+/**
+ * The wire between the host page (which owns the file system and the dev server)
+ * and the service worker (which owns the network). The worker holds no project
+ * state: every request it intercepts is forwarded over a MessagePort to the page.
+ */
+export const PREVIEW_SEGMENT = '__bfwc';
+/** page → worker, with a MessagePort in `ports[0]`: "serve preview `id` over this port". */
+export const ATTACH = 'bfwc:attach';
+/** worker → pages: "I lost the port for `id` (I was restarted) — attach again". */
+export const REATTACH = 'bfwc:reattach';
+/**
+ * The URL prefix previews live under, for a worker scope. Serving the worker from
+ * `/__bfwc/sw.js` (scope `/__bfwc/`) keeps it off every other page of the host app;
+ * a root-scoped worker still only answers under `/__bfwc/`.
+ */
+export function previewPrefix(scopePath) {
+    const scope = scopePath.endsWith('/') ? scopePath : scopePath + '/';
+    return scope.endsWith(`/${PREVIEW_SEGMENT}/`) ? scope : `${scope}${PREVIEW_SEGMENT}/`;
+}
+export function previewBase(scopePath, id) {
+    return `${previewPrefix(scopePath)}${id}/`;
+}
+export function isWireRequest(value) {
+    const v = value;
+    return !!v && v.type === 'request' && typeof v.reqId === 'number' && typeof v.path === 'string';
+}
+export function isWireResponse(value) {
+    const v = value;
+    return !!v && v.type === 'response' && typeof v.reqId === 'number';
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC;AAExC,4FAA4F;AAC5F,MAAM,CAAC,MAAM,MAAM,GAAG,aAAa,CAAC;AACpC,mFAAmF;AACnF,MAAM,CAAC,MAAM,QAAQ,GAAG,eAAe,CAAC;AA2BxC;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC;IACpE,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,eAAe,GAAG,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,EAAU;IACvD,OAAO,GAAG,aAAa,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,CAAC,GAAG,KAA2B,CAAC;IACtC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,CAAC,GAAG,KAA4B,CAAC;IACvC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC;AACrE,CAAC"}

package/dist/sw.js

@@ -0,0 +1 @@
+"use strict";(()=>{var f="__bfwc",g="bfwc:attach",m="bfwc:reattach";function w(e){let n=e.endsWith("/")?e:e+"/";return n.endsWith(`/${f}/`)?n:`${n}${f}/`}function y(e){let n=e;return!!n&&n.type==="response"&&typeof n.reqId=="number"}var v={"content-type":"text/plain; charset=utf-8","cache-control":"no-store"};function R(e){let n=w(e.scopePath),i=e.timeoutMs??3e4,k=e.reattachWaitMs??3e3,c=new Map,d=new Map,p=new Map,T=0;function W(t,r){c.set(t,r),r.onmessage=s=>{y(s.data)&&(p.get(s.data.reqId)?.(s.data),p.delete(s.data.reqId))};for(let s of d.get(t)??[])s(r);d.delete(t)}function P(t){if(!t.pathname.startsWith(n))return null;let r=t.pathname.slice(n.length),s=r.indexOf("/"),o=s<0?r:r.slice(0,s);return o?{id:o,path:s<0?"/":r.slice(s),search:t.search}:null}async function b(t){let r=c.get(t);if(r)return r;let s=new Promise(o=>{let u=d.get(t)??[];u.push(o),d.set(t,u),setTimeout(()=>o(void 0),k)});return await e.requestReattach(t),s}async function x(t){let r=await b(t.id);if(!r)return{status:503,headers:v,body:"This preview is not running in any open tab."};let s=++T;return new Promise(o=>{let u=setTimeout(()=>{p.delete(s),c.get(t.id)===r&&c.delete(t.id),o({status:504,headers:v,body:"The preview did not answer in time."})},i);p.set(s,l=>{clearTimeout(u),o({status:l.status,headers:l.headers,body:l.body})}),r.postMessage({type:"request",reqId:s,path:t.path,search:t.search})})}return{attach:W,match:P,respond:x,detach:t=>c.delete(t)}}var a=globalThis,h=R({scopePath:new URL(a.registration.scope).pathname,async requestReattach(e){let n=await a.clients.matchAll({type:"window",includeUncontrolled:!0});for(let i of n)i.postMessage({type:m,id:e})}});a.addEventListener("install",()=>{a.skipWaiting()});a.addEventListener("activate",e=>{e.waitUntil(a.clients.claim())});a.addEventListener("message",e=>{let n=e.data,i=e.ports[0];n?.type===g&&typeof n.id=="string"&&i&&h.attach(n.id,i)});a.addEventListener("fetch",e=>{if(e.request.method!=="GET")return;let n=h.match(new URL(e.request.url));n&&e.respondWith(h.respond(n).then(i=>new Response(i.body,{status:i.status,headers:i.headers})))});})();

package/dist/swRouter.d.ts

@@ -0,0 +1,44 @@
+/** The part of MessagePort the router uses — a fake in tests, a real port in the worker. */
+export interface PortLike {
+    postMessage(message: unknown): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+}
+export interface PreviewTarget {
+    id: string;
+    path: string;
+    search: string;
+}
+export interface RoutedResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string | ArrayBuffer;
+}
+export interface SwRouterOptions {
+    /** The worker registration's scope path (`/__bfwc/` or `/`). */
+    scopePath: string;
+    /** Ask open pages to re-attach `id` (the worker restarted and lost its ports). */
+    requestReattach(id: string): Promise<void> | void;
+    /** How long a page has to answer one request. */
+    timeoutMs?: number;
+    /** How long to wait for a page to re-attach before giving up. */
+    reattachWaitMs?: number;
+}
+/**
+ * Request routing for the preview service worker, with no worker globals in it.
+ *
+ * Browsers stop idle service workers at will, and a stopped worker forgets every
+ * MessagePort it held. So a request for an unknown preview id is not a 404: the
+ * router asks open pages to re-attach and waits briefly. A port that stops
+ * answering (its tab closed) is dropped on timeout, so the NEXT request goes
+ * through the re-attach path instead of timing out forever.
+ */
+export declare function createSwRouter(options: SwRouterOptions): {
+    attach: (id: string, port: PortLike) => void;
+    match: (url: URL) => PreviewTarget | null;
+    respond: (target: PreviewTarget) => Promise<RoutedResponse>;
+    detach: (id: string) => boolean;
+};
+export type SwRouter = ReturnType<typeof createSwRouter>;
+//# sourceMappingURL=swRouter.d.ts.map

package/dist/swRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swRouter.d.ts","sourceRoot":"","sources":["../src/swRouter.ts"],"names":[],"mappings":"AAEA,4FAA4F;AAC5F,MAAM,WAAW,QAAQ;IACvB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClD,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe;iBASjC,MAAM,QAAQ,QAAQ,KAAG,IAAI;iBAW7B,GAAG,KAAG,aAAa,GAAG,IAAI;sBAsBf,aAAa,KAAG,OAAO,CAAC,cAAc,CAAC;iBAkBxB,MAAM;EACrD;AAED,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/swRouter.js

@@ -0,0 +1,76 @@
+import { isWireResponse, previewPrefix } from './protocol.js';
+const TEXT = { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' };
+/**
+ * Request routing for the preview service worker, with no worker globals in it.
+ *
+ * Browsers stop idle service workers at will, and a stopped worker forgets every
+ * MessagePort it held. So a request for an unknown preview id is not a 404: the
+ * router asks open pages to re-attach and waits briefly. A port that stops
+ * answering (its tab closed) is dropped on timeout, so the NEXT request goes
+ * through the re-attach path instead of timing out forever.
+ */
+export function createSwRouter(options) {
+    const prefix = previewPrefix(options.scopePath);
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const reattachWaitMs = options.reattachWaitMs ?? 3_000;
+    const ports = new Map();
+    const waiters = new Map();
+    const pending = new Map();
+    let nextId = 0;
+    function attach(id, port) {
+        ports.set(id, port);
+        port.onmessage = (event) => {
+            if (!isWireResponse(event.data))
+                return;
+            pending.get(event.data.reqId)?.(event.data);
+            pending.delete(event.data.reqId);
+        };
+        for (const wake of waiters.get(id) ?? [])
+            wake(port);
+        waiters.delete(id);
+    }
+    function match(url) {
+        if (!url.pathname.startsWith(prefix))
+            return null;
+        const rest = url.pathname.slice(prefix.length);
+        const slash = rest.indexOf('/');
+        const id = slash < 0 ? rest : rest.slice(0, slash);
+        if (!id)
+            return null;
+        return { id, path: slash < 0 ? '/' : rest.slice(slash), search: url.search };
+    }
+    async function portFor(id) {
+        const known = ports.get(id);
+        if (known)
+            return known;
+        const arrived = new Promise((resolve) => {
+            const list = waiters.get(id) ?? [];
+            list.push(resolve);
+            waiters.set(id, list);
+            setTimeout(() => resolve(undefined), reattachWaitMs);
+        });
+        await options.requestReattach(id);
+        return arrived;
+    }
+    async function respond(target) {
+        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;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                pending.delete(reqId);
+                if (ports.get(target.id) === port)
+                    ports.delete(target.id);
+                resolve({ status: 504, headers: TEXT, body: 'The preview did not answer in time.' });
+            }, timeoutMs);
+            pending.set(reqId, (response) => {
+                clearTimeout(timer);
+                resolve({ status: response.status, headers: response.headers, body: response.body });
+            });
+            port.postMessage({ type: 'request', reqId, path: target.path, search: target.search });
+        });
+    }
+    return { attach, match, respond, detach: (id) => ports.delete(id) };
+}
+//# sourceMappingURL=swRouter.js.map

package/dist/swRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swRouter.js","sourceRoot":"","sources":["../src/swRouter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAqB,MAAM,eAAe,CAAC;AA+BjF,MAAM,IAAI,GAAG,EAAE,cAAc,EAAE,2BAA2B,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC;AAE1F;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB;IACrD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IACvD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2C,CAAC;IACnE,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4C,CAAC;IACpE,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,SAAS,MAAM,CAAC,EAAU,EAAE,IAAc;QACxC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACpB,IAAI,CAAC,SAAS,GAAG,CAAC,KAAK,EAAE,EAAE;YACzB,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,OAAO;YACxC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;IAED,SAAS,KAAK,CAAC,GAAQ;QACrB,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QAClD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACnD,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAC/E,CAAC;IAED,KAAK,UAAU,OAAO,CAAC,EAAU;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;QACxB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAuB,CAAC,OAAO,EAAE,EAAE;YAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACnB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACtB,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QACH,MAAM,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;QAClC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,UAAU,OAAO,CAAC,MAAqB;QAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,8CAA8C,EAAE,CAAC;QACvG,MAAM,KAAK,GAAG,EAAE,MAAM,CAAC;QACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACtB,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,IAAI;oBAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,qCAAqC,EAAE,CAAC,CAAC;YACvF,CAAC,EAAE,SAAS,CAAC,CAAC;YACd,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE;gBAC9B,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;YACvF,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACzF,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@seanhogg/builderforce-webcontainers",
+  "version": "2026.10.0",
+  "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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sw.js": "./dist/sw.js"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "webcontainer",
+    "service-worker",
+    "in-browser",
+    "dev-server",
+    "preview",
+    "esbuild-wasm",
+    "builderforce"
+  ],
+  "author": {
+    "name": "Sean Hogg",
+    "email": "seanhogg@gmail.com",
+    "url": "https://builderforce.ai"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SeanHogg/builderforce-webcontainers.git",
+    "directory": "packages/browser"
+  },
+  "bugs": {
+    "url": "https://github.com/SeanHogg/builderforce-webcontainers/issues"
+  },
+  "homepage": "https://github.com/SeanHogg/builderforce-webcontainers/tree/main/packages/browser#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "esbuild-wasm": "^0.24.0",
+    "@seanhogg/builderforce-webcontainers-core": "^2026.10.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/build-sw.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/esbuildWasm.ts

@@ -0,0 +1,26 @@
+import { createEsbuildTransformer, 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;
+
+/**
+ * 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).
+ */
+export function createEsbuildWasmTransformer(options: EsbuildWasmOptions = {}): Promise<Transformer> {
+  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);
+  })().catch((error: unknown) => {
+    ready = undefined; // let a later call retry (a transient network failure fetching the wasm)
+    throw error;
+  });
+  return ready;
+}

package/src/host.ts

@@ -0,0 +1,139 @@
+import {
+  DevServer,
+  ERROR_MESSAGE_TYPE,
+  VirtualFileSystem,
+  type DevServerOptions,
+  type FileSystemTree,
+  type FlatFiles,
+  type ProjectProfile,
+  type Transformer,
+} from '@seanhogg/builderforce-webcontainers-core';
+import { ATTACH, REATTACH, isWireRequest, previewBase, type WireResponse } from './protocol.js';
+import { createEsbuildWasmTransformer } from './esbuildWasm.js';
+
+export interface BootOptions {
+  /** 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;
+  /** 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. */
+  id?: string;
+  /** The "Built with Builderforce.ai" badge in the preview. Default true — please keep it. */
+  attribution?: boolean;
+}
+
+export interface PreviewError {
+  message: string;
+  stack?: string;
+  href: string;
+}
+
+export interface PreviewRuntime {
+  readonly id: string;
+  /** Absolute URL to load in the preview iframe. */
+  readonly url: string;
+  readonly fs: VirtualFileSystem;
+  readonly server: DevServer;
+  mount(files: FileSystemTree | FlatFiles): void;
+  /** Whether this runtime can serve the mounted project, and why not. */
+  profile(): ProjectProfile;
+  /** Uncaught errors and rejections raised inside the preview. */
+  onError(listener: (error: PreviewError) => 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[] } {
+  if (typeof served.body === 'string') {
+    return { message: { type: 'response', reqId, status: served.status, headers: served.headers, body: served.body }, transfer: [] };
+  }
+  const body = served.body.slice().buffer as ArrayBuffer; // a copy: transferring must not detach the VFS's own bytes
+  return { message: { type: 'response', reqId, status: served.status, headers: served.headers, body }, transfer: [body] };
+}
+
+/**
+ * Boot a preview runtime in this page: a virtual file system, a dev server over
+ * 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.
+ */
+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 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 id = options.id ?? randomId();
+  const base = previewBase(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 attach = (worker: ServiceWorker) => {
+    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));
+      channel.port1.postMessage(message, transfer);
+    };
+    worker.postMessage({ type: ATTACH, id }, [channel.port2]);
+  };
+  attach(registration.active!);
+
+  const onWorkerMessage = (event: MessageEvent) => {
+    if (event.data?.type === REATTACH && event.data.id === id && registration.active) attach(registration.active);
+  };
+  container.addEventListener('message', onWorkerMessage);
+
+  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
+    const error: PreviewError = { message: String(data.message ?? ''), stack: data.stack, href: data.href };
+    for (const listener of errorListeners) listener(error);
+  };
+  window.addEventListener('message', onWindowMessage);
+
+  return {
+    id,
+    url: new URL(base, location.origin).href,
+    fs,
+    server,
+    mount: (files) => fs.mount(files),
+    profile: () => server.profile(),
+    onError(listener) {
+      errorListeners.add(listener);
+      return () => errorListeners.delete(listener);
+    },
+    dispose() {
+      container.removeEventListener('message', onWorkerMessage);
+      window.removeEventListener('message', onWindowMessage);
+      errorListeners.clear();
+      server.dispose();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { bootPreviewRuntime } from './host.js';
+export type { BootOptions, PreviewRuntime, PreviewError } from './host.js';
+export { createEsbuildWasmTransformer } from './esbuildWasm.js';
+export type { EsbuildWasmOptions } from './esbuildWasm.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 * from '@seanhogg/builderforce-webcontainers-core';

package/src/protocol.ts

@@ -0,0 +1,61 @@
+/**
+ * The wire between the host page (which owns the file system and the dev server)
+ * and the service worker (which owns the network). The worker holds no project
+ * state: every request it intercepts is forwarded over a MessagePort to the page.
+ */
+
+export const PREVIEW_SEGMENT = '__bfwc';
+
+/** page → worker, with a MessagePort in `ports[0]`: "serve preview `id` over this port". */
+export const ATTACH = 'bfwc:attach';
+/** worker → pages: "I lost the port for `id` (I was restarted) — attach again". */
+export const REATTACH = 'bfwc:reattach';
+
+export interface AttachMessage {
+  type: typeof ATTACH;
+  id: string;
+}
+
+export interface ReattachMessage {
+  type: typeof REATTACH;
+  id: string;
+}
+
+export interface WireRequest {
+  type: 'request';
+  reqId: number;
+  path: string;
+  search: string;
+}
+
+export interface WireResponse {
+  type: 'response';
+  reqId: number;
+  status: number;
+  headers: Record<string, string>;
+  body: string | ArrayBuffer;
+}
+
+/**
+ * The URL prefix previews live under, for a worker scope. Serving the worker from
+ * `/__bfwc/sw.js` (scope `/__bfwc/`) keeps it off every other page of the host app;
+ * a root-scoped worker still only answers under `/__bfwc/`.
+ */
+export function previewPrefix(scopePath: string): string {
+  const scope = scopePath.endsWith('/') ? scopePath : scopePath + '/';
+  return scope.endsWith(`/${PREVIEW_SEGMENT}/`) ? scope : `${scope}${PREVIEW_SEGMENT}/`;
+}
+
+export function previewBase(scopePath: string, id: string): string {
+  return `${previewPrefix(scopePath)}${id}/`;
+}
+
+export function isWireRequest(value: unknown): value is WireRequest {
+  const v = value as WireRequest | null;
+  return !!v && v.type === 'request' && typeof v.reqId === 'number' && typeof v.path === 'string';
+}
+
+export function isWireResponse(value: unknown): value is WireResponse {
+  const v = value as WireResponse | null;
+  return !!v && v.type === 'response' && typeof v.reqId === 'number';
+}

package/src/sw.ts

@@ -0,0 +1,61 @@
+/**
+ * The preview service worker (bundled to dist/sw.js). It answers only requests
+ * under the preview prefix; everything else falls through to the network
+ * untouched, so registering it never changes how the host app itself loads.
+ *
+ * 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';
+
+interface WindowClientLike {
+  postMessage(message: unknown): void;
+}
+
+interface ServiceWorkerGlobalLike {
+  registration: { scope: string };
+  clients: {
+    matchAll(options: { type: 'window'; includeUncontrolled: boolean }): Promise<WindowClientLike[]>;
+    claim(): Promise<void>;
+  };
+  skipWaiting(): Promise<void>;
+  addEventListener(type: 'install', listener: () => void): void;
+  addEventListener(type: 'activate', listener: (event: { waitUntil(promise: Promise<unknown>): void }) => void): void;
+  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,
+  ): void;
+}
+
+const worker = globalThis as unknown as ServiceWorkerGlobalLike;
+
+const router = createSwRouter({
+  scopePath: new URL(worker.registration.scope).pathname,
+  async requestReattach(id) {
+    const pages = await worker.clients.matchAll({ type: 'window', includeUncontrolled: true });
+    for (const page of pages) page.postMessage({ type: REATTACH, id });
+  },
+});
+
+worker.addEventListener('install', () => {
+  void worker.skipWaiting();
+});
+
+worker.addEventListener('activate', (event) => {
+  event.waitUntil(worker.clients.claim());
+});
+
+worker.addEventListener('message', (event) => {
+  const message = event.data as AttachMessage | null;
+  const port = event.ports[0];
+  if (message?.type === ATTACH && typeof message.id === 'string' && port) router.attach(message.id, port as PortLike);
+});
+
+worker.addEventListener('fetch', (event) => {
+  if (event.request.method !== 'GET') return;
+  const target = router.match(new URL(event.request.url));
+  if (!target) return;
+  event.respondWith(router.respond(target).then((r) => new Response(r.body, { status: r.status, headers: r.headers })));
+});

package/src/swRouter.ts

@@ -0,0 +1,106 @@
+import { 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 {
+  postMessage(message: unknown): void;
+  onmessage: ((event: { data: unknown }) => void) | null;
+}
+
+export interface PreviewTarget {
+  id: string;
+  path: string;
+  search: string;
+}
+
+export interface RoutedResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string | ArrayBuffer;
+}
+
+export interface SwRouterOptions {
+  /** The worker registration's scope path (`/__bfwc/` or `/`). */
+  scopePath: string;
+  /** Ask open pages to re-attach `id` (the worker restarted and lost its ports). */
+  requestReattach(id: string): Promise<void> | void;
+  /** How long a page has to answer one request. */
+  timeoutMs?: number;
+  /** How long to wait for a page to re-attach before giving up. */
+  reattachWaitMs?: number;
+}
+
+const TEXT = { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' };
+
+/**
+ * Request routing for the preview service worker, with no worker globals in it.
+ *
+ * Browsers stop idle service workers at will, and a stopped worker forgets every
+ * MessagePort it held. So a request for an unknown preview id is not a 404: the
+ * router asks open pages to re-attach and waits briefly. A port that stops
+ * answering (its tab closed) is dropped on timeout, so the NEXT request goes
+ * through the re-attach path instead of timing out forever.
+ */
+export function createSwRouter(options: SwRouterOptions) {
+  const prefix = previewPrefix(options.scopePath);
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const reattachWaitMs = options.reattachWaitMs ?? 3_000;
+  const ports = new Map<string, PortLike>();
+  const waiters = new Map<string, Array<(port: PortLike) => void>>();
+  const pending = new Map<number, (response: WireResponse) => void>();
+  let nextId = 0;
+
+  function attach(id: string, port: PortLike): void {
+    ports.set(id, port);
+    port.onmessage = (event) => {
+      if (!isWireResponse(event.data)) return;
+      pending.get(event.data.reqId)?.(event.data);
+      pending.delete(event.data.reqId);
+    };
+    for (const wake of waiters.get(id) ?? []) wake(port);
+    waiters.delete(id);
+  }
+
+  function match(url: URL): PreviewTarget | null {
+    if (!url.pathname.startsWith(prefix)) return null;
+    const rest = url.pathname.slice(prefix.length);
+    const slash = rest.indexOf('/');
+    const id = slash < 0 ? rest : rest.slice(0, slash);
+    if (!id) return null;
+    return { id, path: slash < 0 ? '/' : rest.slice(slash), search: url.search };
+  }
+
+  async function portFor(id: string): Promise<PortLike | undefined> {
+    const known = ports.get(id);
+    if (known) return known;
+    const arrived = new Promise<PortLike | undefined>((resolve) => {
+      const list = waiters.get(id) ?? [];
+      list.push(resolve);
+      waiters.set(id, list);
+      setTimeout(() => resolve(undefined), reattachWaitMs);
+    });
+    await options.requestReattach(id);
+    return arrived;
+  }
+
+  async function respond(target: PreviewTarget): 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;
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        pending.delete(reqId);
+        if (ports.get(target.id) === port) ports.delete(target.id);
+        resolve({ status: 504, headers: TEXT, body: 'The preview did not answer in time.' });
+      }, timeoutMs);
+      pending.set(reqId, (response) => {
+        clearTimeout(timer);
+        resolve({ status: response.status, headers: response.headers, body: response.body });
+      });
+      port.postMessage({ type: 'request', reqId, path: target.path, search: target.search });
+    });
+  }
+
+  return { attach, match, respond, detach: (id: string) => ports.delete(id) };
+}
+
+export type SwRouter = ReturnType<typeof createSwRouter>;