@start.dev/container 0.0.1

package/dist/runtime-assets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Resolvers for the worker + Service-Worker assets that @start.dev/container SHIPS in its
+ * built `dist/`. These let an external consumer (start.dev) wire
+ * `WebContainer.boot({ runtime })` WITHOUT the monorepo, a runtime bundler, or
+ * hand-copied worker files: the URLs point at the assets that live inside the
+ * installed package.
+ *
+ * Mechanism: each resolver returns `new URL('./workers/<file>', import.meta.url)`.
+ * After the build this module lives at `dist/runtime-assets.js`, so `import.meta.url`
+ * is the installed package location and the workers resolve next to it. Every modern
+ * bundler (Vite, webpack 5, Rollup, esbuild) understands the
+ * `new URL('…', import.meta.url)` pattern and will EMIT these as first-class assets,
+ * so the consumer's build pipeline serves them automatically.
+ *
+ * NOTE — this file is only meaningful in the BUILT package. In the monorepo source
+ * there is no `dist/workers/*`, so the in-repo acceptance harness keeps building +
+ * serving the worker URLs itself (it does not import this module). External
+ * consumers import it from `@start.dev/container/runtime-assets`.
+ */
+/** URL of the shipped, pre-bundled real Vite-serve worker (ESM module worker). */
+export declare function viteWorkerUrl(): string;
+/** URL of the shipped, pre-bundled real Node streaming-process worker (ESM module worker). */
+export declare function processWorkerUrl(): string;
+/** URL of the shipped, pre-bundled real shell worker (@wc/shell / just-bash; ESM module worker). */
+export declare function shellWorkerUrl(): string;
+/**
+ * URL of the shipped substrate Service Worker script. The consumer must serve this
+ * UNDER its preview base scope with the runtime COOP/COEP headers (it cannot be a
+ * cross-origin URL — a Service Worker can only control same-origin scopes), so most
+ * hosts copy it into their served `previewBase` directory rather than importing this
+ * URL directly. Returned here for completeness / programmatic copying.
+ */
+export declare function serviceWorkerUrl(): string;
+/**
+ * Convenience: the worker-URL subset of `RuntimeWiring` filled from the shipped
+ * assets. The consumer still supplies the host-specific fields it owns
+ * (`serviceWorkerUrl` served under its scope, `previewBase`, the WASM URLs, and the
+ * project `dependencyClosure`). Spread this into `boot({ runtime: { ... } })`.
+ */
+export declare function shippedWorkerUrls(): {
+    viteWorkerUrl: string;
+    processWorkerUrl: string;
+    shellWorkerUrl: string;
+};

package/dist/runtime-assets.js

@@ -0,0 +1,27 @@
+// src/runtime-assets.ts
+function viteWorkerUrl() {
+  return new URL("./workers/vite-serve.worker.js", import.meta.url).href;
+}
+function processWorkerUrl() {
+  return new URL("./workers/streaming-process.worker.js", import.meta.url).href;
+}
+function shellWorkerUrl() {
+  return new URL("./workers/shell-host.worker.js", import.meta.url).href;
+}
+function serviceWorkerUrl() {
+  return new URL("./workers/runtime-sw.js", import.meta.url).href;
+}
+function shippedWorkerUrls() {
+  return {
+    viteWorkerUrl: viteWorkerUrl(),
+    processWorkerUrl: processWorkerUrl(),
+    shellWorkerUrl: shellWorkerUrl()
+  };
+}
+export {
+  viteWorkerUrl,
+  shippedWorkerUrls,
+  shellWorkerUrl,
+  serviceWorkerUrl,
+  processWorkerUrl
+};

package/dist/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Public TypeScript surface for `@start.dev/container`, mirroring StackBlitz's official
+ * `@webcontainer/api` so the start.dev adapter (and any consumer) can build against
+ * the canonical shape and drop us in. Names + signatures match `@webcontainer/api`
+ * 1.x; members our runtime does not yet cover are documented as honest stubs in
+ * `WebContainer` (they throw "not yet implemented"), never faked.
+ */
+import type { FsWatcher, WatchListener, WatchOptions } from './_wc-vendored-types';
+export type { FsWatcher, WatchListener, WatchOptions } from './_wc-vendored-types';
+/** A regular file node: `{ file: { contents } }`. */
+export interface FileNode {
+    file: {
+        /** UTF-8 string or raw bytes. Honors the runtime's 1 MiB/utf8 limits. */
+        contents: string | Uint8Array;
+    };
+}
+/**
+ * A symlink node: `{ file: { symlink } }`. Accepted by the type for drop-in
+ * compatibility; the current MemoryFS mount path materializes regular files +
+ * directories only, so a symlink node throws an honest "not yet implemented".
+ */
+export interface SymlinkNode {
+    file: {
+        symlink: string;
+    };
+}
+/** A directory node: `{ directory: { ...nested tree } }`. */
+export interface DirectoryNode {
+    directory: FileSystemTree;
+}
+/** A nested filesystem tree: directory names → file/dir nodes. */
+export interface FileSystemTree {
+    [name: string]: FileNode | SymlinkNode | DirectoryNode;
+}
+/**
+ * Boot options. `@webcontainer/api` exposes `coep`, `workdirName`, and
+ * `forwardPreviewErrors`; we mirror those and add the browser-runtime wiring our
+ * in-page orchestrator needs (the bundled worker + WASM URLs + the served
+ * dependency closure), which `@webcontainer/api` hides behind its hosted runtime.
+ */
+export interface BootOptions {
+    /**
+     * COEP policy hint, mirroring @webcontainer/api. Informational here — the
+     * cross-origin isolation headers are set by whoever serves the host page; the
+     * facade asserts `crossOriginIsolated` at boot.
+     */
+    coep?: 'require-corp' | 'credentialless' | 'none';
+    /** Name of the working directory (default 'proj'); `workdir` becomes `/<name>`. */
+    workdirName?: string;
+    /** Reserved for parity with @webcontainer/api; currently informational. */
+    forwardPreviewErrors?: boolean | 'exceptions-only';
+    /**
+     * Runtime wiring (browser-specific; not in @webcontainer/api, whose runtime is
+     * hosted). The host page supplies the bundled Vite-serve worker URL, the WASM
+     * override URLs, and the pre-mounted dependency closure so the facade stays
+     * browser-pure (no Node `fs`). The start.dev adapter fills these from its
+     * served artifact.
+     */
+    runtime?: RuntimeWiring;
+}
+/**
+ * The browser-runtime wiring the facade needs to boot the real Vite worker. The
+ * host page (or the start.dev adapter) provides these; the facade does not read
+ * the host filesystem itself.
+ */
+export interface RuntimeWiring {
+    /** URL of the bundled `vite-serve.worker.ts` (served same-origin, ESM). */
+    viteWorkerUrl: string;
+    /**
+     * URL of the bundled `streaming-process-host.worker.ts` (same-origin, ESM). This
+     * is the REAL Node process worker the command resolver uses for `node <file>`,
+     * `npm run <script>`, `npx <bin>`, and direct local bins — it runs the unmodified
+     * entry/bin on the node-compat module loader over the mounted MemoryFS and streams
+     * its real stdout/stderr/exit. Optional: when absent, those commands throw an
+     * honest "process worker not wired" error rather than faking output. (The
+     * dev-server path — `npm run dev` / `vite` — uses `viteWorkerUrl` instead.)
+     */
+    processWorkerUrl?: string;
+    /**
+     * URL of the bundled shell worker (same-origin, ESM) that runs the REAL @wc/shell
+     * (vercel-labs/just-bash) over the mounted MemoryFS. Used to back `spawn('jsh')`
+     * and `spawn('bash')` (jsh is StackBlitz's shell name; we substitute just-bash —
+     * a real AST-based bash interpreter). Optional: when absent, `jsh`/`bash` throw an
+     * honest "shell worker not wired" error rather than faking a prompt.
+     */
+    shellWorkerUrl?: string;
+    /** URL of the substrate Service Worker script (served under the preview base). */
+    serviceWorkerUrl: string;
+    /** Preview base path the SW is scoped to + Vite serves under (e.g. '/preview/'). */
+    previewBase: string;
+    /** URL of the served `esbuild.wasm` (esbuild-wasm needs `initialize({wasmURL})`). */
+    esbuildWasmUrl: string;
+    /** URL of the served `@rollup/wasm-node` `bindings_wasm_bg.wasm`. */
+    rollupWasmUrl: string;
+    /** Source of `@rollup/wasm-node/.../bindings_wasm.js` (eval'd in the worker). */
+    rollupBindingsSource: string;
+    /** Source of `@rollup/wasm-node/.../shared/parseAst.js` (eval'd in the worker). */
+    rollupParseAstSharedSource: string;
+    /**
+     * The pre-mounted dependency closure (vite + rollup + react + react-dom +
+     * @vitejs/plugin-react), keyed by VFS path. Mounted into the worker's MemoryFS
+     * alongside the user's project files. The host page builds this with
+     * `mountPackageClosure` (a Node-side op) and serves it as JSON.
+     */
+    dependencyClosure: Record<string, string>;
+}
+/** Options for `mount`. */
+export interface MountOptions {
+    /** Mount the tree under this absolute VFS dir (default: `workdir`). */
+    mountPoint?: string;
+}
+export type BufferEncoding = 'utf8' | 'utf-8';
+export interface FileSystemAPI {
+    /**
+     * Read a file. With no encoding, returns a `Uint8Array`; with 'utf8'/'utf-8',
+     * returns a string. Mirrors @webcontainer/api's `readFile`.
+     */
+    readFile(path: string): Promise<Uint8Array>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    /** Write a file (creates parent dirs). Honors the 1 MiB/utf8 limit (throws on overflow). */
+    writeFile(path: string, data: string | Uint8Array, options?: {
+        encoding?: BufferEncoding | null;
+    } | BufferEncoding | null): Promise<void>;
+    /** List a directory. `{ withFileTypes: true }` returns Dirent-like entries. */
+    readdir(path: string): Promise<string[]>;
+    readdir(path: string, options: {
+        withFileTypes: true;
+    }): Promise<DirEnt[]>;
+    readdir(path: string, options: {
+        encoding?: BufferEncoding;
+        withFileTypes?: false;
+    }): Promise<string[]>;
+    /** Create a directory. `{ recursive: true }` creates parents. */
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Remove a file or directory. `{ recursive: true }` removes a non-empty dir. */
+    rm(path: string, options?: {
+        force?: boolean;
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Rename / move a path. */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Watch a path for changes (mirrors @webcontainer/api). Backed by the REAL
+     * MemoryFS watch primitive: delivers genuine 'rename'/'change' events for the
+     * watched VFS subtree and returns a `{ close() }` watcher handle. The watcher is
+     * tracked by the container and closed on `teardown()`.
+     */
+    watch(path: string, listener: WatchListener): FsWatcher;
+    watch(path: string, options: WatchOptions, listener: WatchListener): FsWatcher;
+    watch(path: string, options?: WatchOptions): FsWatcher;
+}
+/** A Dirent-like entry returned by `readdir(path, { withFileTypes: true })`. */
+export interface DirEnt {
+    name: string;
+    isFile(): boolean;
+    isDirectory(): boolean;
+}
+export interface SpawnOptions {
+    /** Working directory for the command (default: `workdir`). */
+    cwd?: string;
+    /** Environment variables merged over the defaults. */
+    env?: Record<string, string | number | boolean>;
+    /** Initial terminal dimensions (accepted for parity; informational). */
+    terminal?: {
+        cols: number;
+        rows: number;
+    };
+    /** Output stream as raw bytes instead of decoded strings (parity; default false). */
+    output?: boolean;
+}
+/**
+ * A spawned process handle. Mirrors @webcontainer/api's `WebContainerProcess`:
+ * a string output stream, a string input stream, an exit promise, and `kill()`.
+ */
+export interface WebContainerProcess {
+    /** Combined stdout/stderr as decoded strings. */
+    readonly output: ReadableStream<string>;
+    /** stdin as decoded strings. */
+    readonly input: WritableStream<string>;
+    /** Resolves with the process exit code. */
+    readonly exit: Promise<number>;
+    /** Resize the (virtual) terminal (parity; informational for the dev server). */
+    resize?(dimensions: {
+        cols: number;
+        rows: number;
+    }): void;
+    /** Terminate the process. */
+    kill(): void;
+}
+export type Port = number;
+/** `on('server-ready')` — fired when a dev server starts listening. */
+export type ServerReadyListener = (port: Port, url: string) => void;
+/** Port lifecycle type for `on('port')`. */
+export type PortListenerType = 'open' | 'close';
+/** `on('port')` — fired when a port opens/closes; mirrors @webcontainer/api. */
+export type PortListener = (port: Port, type: PortListenerType, url: string) => void;
+/** `on('error')` — fired on an internal error. */
+export type ErrorListener = (error: {
+    message: string;
+}) => void;
+/**
+ * `on('preview-message')` — preview-origin postMessage relay. NOT yet
+ * implemented; the listener type exists for parity but the facade does not yet
+ * forward preview-origin messages (documented stub).
+ */
+export type PreviewMessageListener = (message: unknown) => void;
+/**
+ * `on('xdg-open')` — a guest "open this url/file" request, mirroring
+ * @webcontainer/api. Accepted for parity (registering a listener never throws);
+ * the facade does not yet EMIT it (no guest process surfaces xdg-open yet).
+ */
+export type XdgOpenListener = (url: string) => void;
+/**
+ * `on('code')` — a guest "open in editor" request, mirroring @webcontainer/api's
+ * IDE integration hook. Accepted for parity (registering a listener never
+ * throws); the facade does not yet EMIT it.
+ */
+export type CodeListener = (path: string) => void;
+export interface WebContainerEventMap {
+    'server-ready': ServerReadyListener;
+    port: PortListener;
+    error: ErrorListener;
+    'preview-message': PreviewMessageListener;
+    /** Parity hook (never emitted yet); registering a listener never throws. */
+    'xdg-open': XdgOpenListener;
+    /** Parity hook (never emitted yet); registering a listener never throws. */
+    code: CodeListener;
+}

package/dist/workers/runtime-sw.js

@@ -0,0 +1,269 @@
+self.addEventListener('install', (event) => {
+  event.waitUntil(self.skipWaiting());
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+let runtimeRequestId = 0;
+
+// ── Navigation-proxy opt-in (Next App Router document-level hydration) ──
+// The Vite preview injects a module entry into its own bootstrap document and
+// RELIES on navigations being bypassed (return fetch). The Next App Router calls
+// hydrateRoot(document, …) — it hydrates the WHOLE document — so the iframe
+// document must BE Next's real SSR HTML, which means the navigation itself has to
+// be served by the runtime (not the static bootstrap shell). This is enabled ONLY
+// when the SW script was registered with the explicit ?navProxy=1 marker, so the
+// Vite registration (plain runtime-sw.js) keeps the byte-identical navigate-bypass.
+const NAV_PROXY_ENABLED = (() => {
+  try {
+    return new URL(self.location.href).searchParams.get('navProxy') === '1';
+  } catch (_) {
+    return false;
+  }
+})();
+
+// The window client (the parent page that owns the runtime worker + dispatch glue)
+// that relays runtime HTTP requests for NAVIGATIONS. A navigation has no controlling
+// client yet (the document is mid-creation), so the SW cannot post to event.clientId.
+// The parent page registers itself here via a wc:nav-relay-register message; the SW
+// then routes navigation requests to it, exactly like a subresource but flagged
+// navigate:true so the parent can frame the response as a full document.
+let navRelayClientId = null;
+
+self.addEventListener('message', (event) => {
+  const data = event.data;
+  if (data && data.type === 'wc:nav-relay-register' && event.source && event.source.id) {
+    navRelayClientId = event.source.id;
+    if (event.ports && event.ports[0]) {
+      try { event.ports[0].postMessage({ type: 'wc:nav-relay-registered' }); } catch (_) {}
+    }
+  }
+});
+
+// Response headers that describe the ON-THE-WIRE transfer framing of the routed
+// response. The runtime worker buffers the whole body and hands us the decoded
+// bytes, so re-advertising chunked/gzip/length from the upstream Next response would
+// make the browser's native DOCUMENT loader mis-frame the navigation (observed as
+// net::ERR_FAILED / net::ERR_CONTENT_LENGTH_MISMATCH). Strip them for navigations so
+// the browser frames the already-decoded body itself.
+function stripTransferFramingHeaders(headers) {
+  if (!Array.isArray(headers)) return headers;
+  return headers.filter((header) => {
+    if (!Array.isArray(header) || typeof header[0] !== 'string') return true;
+    const name = header[0].toLowerCase();
+    return name !== 'transfer-encoding' && name !== 'content-encoding' && name !== 'content-length';
+  });
+}
+
+function responseFromMessage(message, expectedId, stripFraming) {
+  if (!message || !(message.type === 'wc:runtime-http-response') || message.id !== expectedId) {
+    throw new Error('Unexpected WebContainers runtime HTTP response for ' + expectedId);
+  }
+  if (!(message.status === 101 || (message.status >= 200 && message.status <= 599))) {
+    throw new Error('ERR_WC_SERVICE_WORKER_RESPONSE_STATUS_UNSUPPORTED: Runtime Service Worker routing received unsupported response status ' + message.status + ' for ' + expectedId + '. Refusing to construct a browser Response outside the currently proven 101/200-599 status subset; do not claim arbitrary Fetch Response construction, browser status normalization, or broad Service Worker response serialization parity until automated browser smoke proves those semantics.');
+  }
+  if (typeof ReadableStream !== 'undefined' && message.body instanceof ReadableStream) {
+    throw new Error('ERR_WC_SERVICE_WORKER_RESPONSE_STREAM_UNSUPPORTED: Runtime Service Worker routing streaming response bodies and backpressure are not implemented. Send string, ArrayBuffer, Blob, FormData, URLSearchParams, or null response bodies only; do not claim response streaming parity, browser UX parity, production Service Worker deployment readiness, or broad Service Worker routing parity until automated browser smoke proves streaming and cleanup semantics.');
+  }
+  const body = message.body;
+  const supportedBody = body === undefined || body === null || typeof body === 'string' || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || (typeof Blob !== 'undefined' && body instanceof Blob) || (typeof FormData !== 'undefined' && body instanceof FormData) || (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams);
+  if (!supportedBody) {
+    throw new Error('ERR_WC_SERVICE_WORKER_RESPONSE_BODY_UNSUPPORTED: Runtime Service Worker routing received an object response body for ' + expectedId + '. Send string, ArrayBuffer, Blob, FormData, URLSearchParams, or null response bodies only; do not claim arbitrary response body serialization, implicit body coercion, Fetch BodyInit parity, or broad Service Worker response parity until automated browser smoke proves those semantics.');
+  }
+  if (Array.isArray(message.headers) && message.headers.some((header) => !Array.isArray(header) || typeof header[0] !== 'string' || typeof header[1] !== 'string')) {
+    throw new Error('ERR_WC_SERVICE_WORKER_RESPONSE_HEADERS_UNSUPPORTED: Runtime Service Worker routing received a non-string routed response header for ' + expectedId + '. Refusing to coerce header names or values through browser Headers; do not claim arbitrary response header serialization, implicit header coercion, Fetch header normalization, or broad Service Worker response parity until automated browser smoke proves those semantics.');
+  }
+  if (Array.isArray(message.headers) && message.headers.some((header) => header[0].toLowerCase() === 'set-cookie')) {
+    throw new Error('ERR_WC_SERVICE_WORKER_RESPONSE_HEADERS_UNSUPPORTED: Set-Cookie response headers are not represented by the current Service Worker routing protocol. Refusing to construct a Response that could collapse, expose, or misrepresent forbidden response headers; do not claim multi-value Set-Cookie, forbidden response-header filtering, browser cookie, Fetch, or broad Service Worker header parity until automated browser smoke proves those semantics.');
+  }
+  return new Response(message.body ?? null, {
+    status: message.status,
+    statusText: message.statusText,
+    headers: stripFraming ? stripTransferFramingHeaders(message.headers) : message.headers,
+  });
+}
+
+function requestBodySerializationError(request, cause) {
+  const causeText = cause && cause.name ? cause.name + ': ' + cause.message : String(cause);
+  return new Error('ERR_WC_SERVICE_WORKER_REQUEST_BODY_UNSUPPORTED: Runtime Service Worker routing could not clone or serialize the request body for ' + request.method + ' ' + request.url + '. The request body has already been consumed, is locked, or cannot be represented by the current string/ArrayBuffer routing subset; do not claim arbitrary request cloning/body serialization parity, streamed upload parity, browser UX parity, production Service Worker deployment readiness, or broad Service Worker routing parity until automated browser smoke proves those semantics. Cause: ' + causeText);
+}
+
+function requestRedirectModeUnsupportedError(request) {
+  return new Error('ERR_WC_SERVICE_WORKER_REQUEST_REDIRECT_UNSUPPORTED: Runtime Service Worker routing only serializes requests with redirect mode follow. Refusing ' + request.method + ' ' + request.url + ' because redirect mode ' + request.redirect + ' is not represented by the current request/response protocol; do not claim redirect handling parity, browser UX parity, production Service Worker deployment readiness, or broad Service Worker routing parity until automated browser smoke proves manual/error redirect semantics.');
+}
+
+function requestCacheModeUnsupportedError(request) {
+  return new Error('ERR_WC_SERVICE_WORKER_REQUEST_CACHE_UNSUPPORTED: Runtime Service Worker routing only serializes requests with cache mode default. Refusing ' + request.method + ' ' + request.url + ' because cache mode ' + request.cache + ' is not represented by the current request/response protocol; do not claim browser cache routing parity, Cache API parity, offline readiness, browser UX parity, production Service Worker deployment readiness, or broad Service Worker routing parity until automated browser smoke proves cache-mode semantics.');
+}
+
+function requestModeUnsupportedError(request) {
+  return new Error('ERR_WC_SERVICE_WORKER_REQUEST_MODE_UNSUPPORTED: Runtime Service Worker routing does not serialize no-cors opaque request semantics. Refusing ' + request.method + ' ' + request.url + ' because request mode ' + request.mode + ' is not represented by the current request/response protocol; do not claim opaque request, browser fetch mode, cross-origin preview routing, or broad Service Worker routing parity until automated browser smoke proves these semantics.');
+}
+
+function requestCredentialsUnsupportedError(request) {
+  return new Error('ERR_WC_SERVICE_WORKER_REQUEST_CREDENTIALS_UNSUPPORTED: Runtime Service Worker routing does not serialize credentials mode omit. Refusing ' + request.method + ' ' + request.url + ' because credentials mode ' + request.credentials + ' is not represented by the current request/response protocol; do not claim browser cookie, credential forwarding, Fetch credentials, cross-origin preview routing, or broad Service Worker request serialization parity until automated browser smoke proves these semantics.');
+}
+
+function serviceWorkerPostMessageUnsupportedError(request, cause) {
+  const causeText = cause && cause.name ? cause.name + ': ' + cause.message : String(cause);
+  return new Error('ERR_WC_SERVICE_WORKER_POSTMESSAGE_UNSUPPORTED: Runtime Service Worker routing failed to post the serialized request for ' + request.method + ' ' + request.url + ' to the controlling client. Service Worker routing transfer lists must contain the response MessagePort and any ArrayBuffer body as valid transferables; do not claim Service Worker routing transfer-list readiness, arbitrary request/response serialization parity, browser UX parity, production Service Worker deployment readiness, or broad Service Worker routing parity until automated browser smoke proves this boundary. Cause: ' + causeText);
+}
+
+function assertSupportedRequestRedirectMode(request) {
+  if (request.redirect !== 'follow') throw requestRedirectModeUnsupportedError(request);
+}
+
+function assertSupportedRequestCacheMode(request) {
+  if (request.cache !== 'default') throw requestCacheModeUnsupportedError(request);
+}
+
+function isSameOriginRequest(request) {
+  try {
+    return new URL(request.url).origin === self.location.origin;
+  } catch (_) {
+    return false;
+  }
+}
+
+function assertSupportedRequestMode(request) {
+  // no-cors is only problematic CROSS-origin, where the response would be opaque
+  // and unreadable. For SAME-origin requests (every preview subresource — the
+  // browser issues classic <script src> chunk loads with mode 'no-cors') the
+  // response is a normal, fully-readable response, so routing it is correct and
+  // not an opaque/cross-origin claim. Refuse only cross-origin no-cors.
+  if (request.mode === 'no-cors' && !isSameOriginRequest(request)) throw requestModeUnsupportedError(request);
+}
+
+function assertSupportedRequestCredentials(request) {
+  if (request.credentials === 'omit') throw requestCredentialsUnsupportedError(request);
+}
+
+async function serializeRequestBody(request) {
+  const hasRequestBody = request.method !== 'GET' && request.method !== 'HEAD';
+  if (!hasRequestBody) return {};
+  const contentType = request.headers.get('content-type') || '';
+  const useTextBody = contentType === '' || /^(text\/)|json|javascript|xml|x-www-form-urlencoded/.test(contentType);
+  try {
+    if (request.bodyUsed) throw new Error('request body has already been consumed before Service Worker routing serialization');
+    const body = useTextBody ? await request.clone().text() : await request.clone().arrayBuffer();
+    return useTextBody ? { body } : { body, bodyEncoding: 'arrayBuffer' };
+  } catch (error) {
+    throw requestBodySerializationError(request, error);
+  }
+}
+
+// Route a fetch event through a window client over the MessagePort protocol. The
+// same path serves subresources (client = the iframe itself) and — when navigation
+// proxying is opted in — the iframe NAVIGATION (client = the registered nav relay,
+// isNavigate=true so we strip on-the-wire framing headers and tell the relay this is
+// a document request).
+async function routeThroughClient(event, client, isNavigate) {
+  const id = String(++runtimeRequestId);
+  const channel = new MessageChannel();
+  let serializedRequestBody;
+  try {
+    // A navigation request intercepted by a Service Worker carries redirect mode
+    // 'manual' (the browser handles document redirects itself), request mode
+    // 'navigate', and — for a reload navigation — cache mode 'reload'/'no-cache'.
+    // All three are correct for a document load and must not be refused by the
+    // subresource-oriented guards (refusing a reload navigation rejects respondWith →
+    // net::ERR_FAILED → the iframe lands on a browser error page). We still serialize
+    // the body normally (a navigation is GET, so there is none). Subresources keep the
+    // full guard set unchanged.
+    if (!isNavigate) {
+      assertSupportedRequestRedirectMode(event.request);
+      assertSupportedRequestMode(event.request);
+      assertSupportedRequestCacheMode(event.request);
+    }
+    assertSupportedRequestCredentials(event.request);
+    serializedRequestBody = await serializeRequestBody(event.request);
+  } catch (error) {
+    channel.port1.close();
+    channel.port2.close();
+    throw error;
+  }
+  const body = serializedRequestBody.body;
+  const bodyEncoding = serializedRequestBody.bodyEncoding;
+  const response = new Promise((resolve, reject) => {
+    channel.port1.onmessage = (portEvent) => {
+      try {
+        resolve(responseFromMessage(portEvent.data, id, isNavigate));
+      } catch (error) {
+        reject(error);
+      } finally {
+        channel.port1.close();
+      }
+    };
+    channel.port1.start();
+  });
+
+  const transfer = bodyEncoding === 'arrayBuffer' ? [channel.port2, body] : [channel.port2];
+  try {
+    client.postMessage({
+      type: 'wc:runtime-http-request',
+      id,
+      url: event.request.url,
+      method: event.request.method,
+      headers: [...event.request.headers.entries()],
+      body,
+      bodyEncoding,
+      navigate: isNavigate === true,
+    }, transfer);
+  } catch (error) {
+    channel.port1.close();
+    channel.port2.close();
+    throw serviceWorkerPostMessageUnsupportedError(event.request, error);
+  }
+
+  return response;
+}
+
+self.addEventListener('fetch', (event) => {
+  const clientId = event.clientId || event.resultingClientId;
+  event.respondWith((async () => {
+    const isNavigate = event.request.mode === 'navigate';
+
+    if (isNavigate && !NAV_PROXY_ENABLED) {
+      // Vite (and every non-opted-in registration) keeps the byte-identical bypass:
+      // its bootstrap shell is served statically and it injects its own module entry.
+      return fetch(event.request);
+    }
+
+    if (NAV_PROXY_ENABLED) {
+      // In nav-proxy mode the iframe document IS the runtime's real HTML (so React can
+      // hydrate the whole document), which means it carries no relay script. Route BOTH
+      // the navigation AND every subresource it then requests through the registered
+      // nav relay (the parent page that owns the runtime worker). Navigations strip the
+      // on-the-wire framing headers so the native document loader frames the body.
+      let inScope = false;
+      try {
+        const reqUrl = new URL(event.request.url);
+        const scopePath = self.registration.scope.indexOf(self.location.origin) === 0
+          ? self.registration.scope.slice(self.location.origin.length)
+          : self.registration.scope;
+        inScope = reqUrl.origin === self.location.origin && reqUrl.pathname.indexOf(scopePath) === 0;
+      } catch (_) {
+        inScope = false;
+      }
+      if (!inScope) return fetch(event.request);
+      const relay = navRelayClientId ? await self.clients.get(navRelayClientId) : undefined;
+      if (!relay) {
+        // No relay registered yet: navigations must not silently fall through to the
+        // static shell (that would defeat document-level hydration), but a subresource
+        // can still try the controlling client.
+        if (isNavigate) return fetch(event.request);
+        const fallback = clientId ? await self.clients.get(clientId) : undefined;
+        if (!fallback) return fetch(event.request);
+        return routeThroughClient(event, fallback, false);
+      }
+      return routeThroughClient(event, relay, isNavigate);
+    }
+
+    const client = clientId ? await self.clients.get(clientId) : undefined;
+    if (!client) return fetch(event.request);
+
+    return routeThroughClient(event, client, false);
+  })());
+});