@seanhogg/builderforce-webcontainers-core 2026.10.6 → 2026.10.8

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();
@@ -125,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.6",
+  "version": "2026.10.8",
   "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,63 @@
+/**
+ * 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 {
+  /** Only these path prefixes (`node_modules`), relative to the root, no leading slash. Default: everything. */
+  include?: string[];
+  /** 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 under(relative: string, prefixes: string[]): boolean {
+  return prefixes.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 include = options.include;
+  const excluded = (relative: string) => (include !== undefined && !under(relative, include)) || under(relative, exclude);
+  const entries: Zippable = {};
+  for (const dir of fs.explicitDirectories()) {
+    const relative = dir.slice(1);
+    if (!excluded(relative) && fs.readdir(dir).length === 0) entries[relative + '/'] = new Uint8Array(0);
+  }
+  for (const path of fs.list()) {
+    const relative = path.slice(1);
+    if (excluded(relative)) 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/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,26 @@
  *     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 WebSocket bridge follows, so `new WebSocket('ws://localhost:3000')` reaches a virtual server;
+ *   • 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';
+import { previewSocketScript } from './previewBridge.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 +32,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 +79,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[];
 }
 
+/** A host script as a tag. `</script>` inside the body would end the tag early, so it is escaped. */
+export const scriptTag = (source: string): 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 +99,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(), previewSocketScript(), 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, 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,8 @@ 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, scriptTag, errorBridgeScript, liveReloadScript, reloadChannelName, ERROR_MESSAGE_TYPE, CONSOLE_MESSAGE_TYPE, CONSOLE_MESSAGE_LIMIT } from './html.js';
+export { previewSocketScript, previewCookieScript, bridgeInsertionPoint, SOCKET_MESSAGE_TYPE, COOKIE_MESSAGE_TYPE, SOCKET_CONNECT_TIMEOUT_MS } from './previewBridge.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);

package/src/installer/npmrc.ts

@@ -0,0 +1,69 @@
+/**
+ * `.npmrc`: the default registry, per-scope registries (`@acme:registry=…`) and
+ * auth tokens keyed by registry path (`//npm.acme.dev/:_authToken=${NPM_TOKEN}`).
+ * Project and user files are read like npm does — the project's wins — and
+ * `${VAR}` is filled from the process environment.
+ *
+ * A private registry is reached with the browser's `fetch`, so it must answer
+ * CORS requests that carry an `Authorization` header.
+ */
+import type { VirtualFileSystem } from '../vfs.js';
+
+export interface NpmConfig {
+  registry?: string;
+  /** `@scope` → registry URL. */
+  scopes: Record<string, string>;
+  /** `//host/path/` → bearer token. */
+  tokens: Record<string, string>;
+}
+
+export function emptyNpmConfig(): NpmConfig {
+  return { scopes: {}, tokens: {} };
+}
+
+const trimSlash = (url: string) => url.replace(/\/+$/, '');
+
+export function parseNpmrc(text: string, env: Record<string, string | undefined> = {}, into: NpmConfig = emptyNpmConfig()): NpmConfig {
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+    const eq = line.indexOf('=');
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim().replace(/^(["'])(.*)\1$/, '$2').replace(/\$\{([^}]+)\}/g, (_m, name: string) => env[name] ?? '');
+    if (key === 'registry') into.registry = trimSlash(value);
+    else if (/^@[^:]+:registry$/.test(key)) into.scopes[key.slice(0, key.indexOf(':'))] = trimSlash(value);
+    else if (key.startsWith('//') && key.endsWith(':_authToken')) into.tokens[key.slice(0, -':_authToken'.length).replace(/\/?$/, '/')] = value;
+  }
+  return into;
+}
+
+/** Read `.npmrc` files, lowest precedence first (user, then project). Missing files are skipped. */
+export function readNpmConfig(fs: VirtualFileSystem, paths: string[], env: Record<string, string | undefined> = {}): NpmConfig {
+  const config = emptyNpmConfig();
+  for (const path of paths) {
+    const text = fs.readText(path);
+    if (text !== undefined) parseNpmrc(text, env, config);
+  }
+  return config;
+}
+
+/** The registry a package is fetched from: its scope's, else the default. */
+export function registryFor(config: NpmConfig | undefined, name: string, fallback: string): string {
+  if (name.startsWith('@')) {
+    const scoped = config?.scopes[name.slice(0, name.indexOf('/'))];
+    if (scoped) return scoped;
+  }
+  return fallback;
+}
+
+/** `Authorization` for a URL: the token whose registry path is the longest prefix of it. */
+export function authHeaders(config: NpmConfig | undefined, url: string): Record<string, string> {
+  if (!config) return {};
+  const target = url.replace(/^https?:/, '');
+  let best = '';
+  for (const prefix of Object.keys(config.tokens)) {
+    if ((target.startsWith(prefix) || target + '/' === prefix) && prefix.length > best.length) best = prefix;
+  }
+  return best ? { authorization: `Bearer ${config.tokens[best]}` } : {};
+}

package/src/installer/registry.ts

@@ -5,6 +5,8 @@
  * caller injects one, which is what keeps this testable against a fake registry.
  */
 
+import { authHeaders, registryFor, type NpmConfig } from './npmrc.js';
+
 export type FetchLike = (url: string, init?: { headers?: Record<string, string>; signal?: AbortSignal }) => Promise<{
   ok: boolean;
   status: number;
@@ -60,6 +62,8 @@ export interface RegistryOptions {
   fetch: FetchLike;
   registry?: string;
   cache?: PackageCache;
+  /** `.npmrc` settings: scoped registries and auth tokens. */
+  npmrc?: NpmConfig;
   /** How long a cached packument is trusted. Default 10 minutes. */
   packumentMaxAgeMs?: number;
   signal?: AbortSignal;
@@ -136,7 +140,8 @@ export class RegistryClient {
   }
 
   private async loadPackument(name: string): Promise<Packument> {
-    const key = `packument:${this.registry}/${name}`;
+    const registry = registryFor(this.options.npmrc, name, this.registry);
+    const key = `packument:${registry}/${name}`;
     const maxAge = this.options.packumentMaxAgeMs ?? 10 * 60_000;
     const cached = await this.options.cache?.get(key);
     if (cached) {
@@ -147,15 +152,16 @@ export class RegistryClient {
         // a corrupt entry is just a miss
       }
     }
-    const url = `${this.registry}/${name.startsWith('@') ? '@' + encodeURIComponent(name.slice(1)) : encodeURIComponent(name)}`;
-    const bytes = await this.get(url, { accept: ABBREVIATED }, name);
+    const url = `${registry}/${name.startsWith('@') ? '@' + encodeURIComponent(name.slice(1)) : encodeURIComponent(name)}`;
+    const bytes = await this.get(url, { accept: ABBREVIATED }, name, registry);
     const packument = JSON.parse(decoder.decode(bytes)) as Packument;
     if (!packument.versions) throw new Error(`The registry returned no versions for "${name}".`);
     await this.options.cache?.put(key, encoder.encode(JSON.stringify({ t: Date.now(), p: packument })));
     return packument;
   }
 
-  private async get(url: string, headers: Record<string, string>, packageName?: string): Promise<Uint8Array> {
+  private async get(url: string, headers: Record<string, string>, packageName?: string, registry = this.registry): Promise<Uint8Array> {
+    headers = { ...headers, ...authHeaders(this.options.npmrc, url) };
     let lastError: unknown;
     for (let attempt = 0; attempt < 2; attempt++) {
       let response: Awaited<ReturnType<FetchLike>>;
@@ -166,7 +172,8 @@ export class RegistryClient {
         lastError = error; // network blip: retry once
         continue;
       }
-      if (response.status === 404 && packageName) throw new Error(`Package "${packageName}" was not found in ${this.registry}.`);
+      if (response.status === 404 && packageName) throw new Error(`Package "${packageName}" was not found in ${registry}.`);
+      if ((response.status === 401 || response.status === 403) && packageName) throw new Error(`${registry} refused "${packageName}" (HTTP ${response.status}). Add an auth token to .npmrc.`);
       if (!response.ok) throw new Error(`GET ${url} failed with HTTP ${response.status}.`);
       return new Uint8Array(await response.arrayBuffer());
     }

package/src/node/http/client.ts

@@ -3,12 +3,13 @@
  * the `fetch` global a program sees. Requests to localhost reach this runtime's
  * own virtual servers (`loopback`); everything else goes through the browser's
  * fetch, so CORS applies — a public API without CORS headers is unreachable
- * from a browser page, and no shim can change that.
+ * from a browser page, and no shim can change that. Response bodies stream:
+ * `res.on('data')` and `response.body` see chunks as the server writes them.
  */
 import { Buffer } from '../buffer.js';
 import type { EventLoop } from '../loop.js';
 import type { HttpRequestData, System } from '../../system/types.js';
-import { FakeSocket, IncomingMessage, OutgoingHeaders } from './server.js';
+import { FakeSocket, IncomingMessage, OutgoingHeaders } from './messages.js';
 
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1', '[::1]']);
 /** Headers a browser refuses to let script set; dropping them beats a TypeError. */
@@ -70,7 +71,8 @@ export async function sendRequest(system: System, url: URL, request: HttpRequest
     const headers = new Headers();
     for (const [k, v] of Object.entries(reply.headers)) for (const item of Array.isArray(v) ? v : [v]) headers.append(k, String(item));
     const empty = reply.status === 204 || reply.status === 304 || request.method === 'HEAD';
-    return new Response(empty ? null : (reply.body as unknown as BodyInit), { status: reply.status, statusText: reply.statusText, headers });
+    if (empty) void reply.body.cancel().catch(() => undefined);
+    return new Response(empty ? null : reply.body, { status: reply.status, statusText: reply.statusText, headers });
   }
   const headers: Record<string, string> = {};
   for (const [k, v] of Object.entries(request.headers)) if (!FORBIDDEN.has(k.toLowerCase())) headers[k] = v;
@@ -92,7 +94,9 @@ export class ClientRequest extends OutgoingHeaders {
   private readonly options: RequestOptions;
 
   constructor(private readonly deps: ClientDeps, input: unknown, extra: unknown, callback: ((res: IncomingMessage) => void) | undefined, defaultProtocol: string) {
-    super({ decodeStrings: true });
+    // Not auto-destroyed on 'finish' (as in Node): the request body is done long before the
+    // response streams in, and destroy() aborts the request — which would cut that response off.
+    super({ decodeStrings: true, autoDestroy: false });
     if (typeof extra === 'function') [callback, extra] = [extra as typeof callback, undefined];
     this.options = toOptions(input, extra, defaultProtocol);
     this.method = this.options.method!;
@@ -131,6 +135,33 @@ export class ClientRequest extends OutgoingHeaders {
   setNoDelay(): void {}
   setSocketKeepAlive(): void {}
 
+  /** Push the body into `res` chunk by chunk; aborting the request hangs up on the server. */
+  private async streamBody(response: Response, res: IncomingMessage): Promise<void> {
+    const reader = response.body?.getReader();
+    if (reader) {
+      const stop = () => void reader.cancel().catch(() => undefined);
+      this.controller.signal.addEventListener('abort', stop);
+      try {
+        for (;;) {
+          const { value, done } = await reader.read();
+          if (done || this.controller.signal.aborted) break;
+          this.deps.loop._run(() => res.push(Buffer.from(value.buffer as ArrayBuffer, value.byteOffset, value.byteLength)));
+        }
+      } catch (error) {
+        if (this.controller.signal.aborted) return;
+        this.deps.loop._run(() => {
+          res.aborted = true;
+          res.destroy(error as Error);
+        });
+        return;
+      } finally {
+        this.controller.signal.removeEventListener('abort', stop);
+      }
+    }
+    if (this.controller.signal.aborted) return;
+    this.deps.loop._run(() => res._complete());
+  }
+
   private async perform(): Promise<void> {
     const release = this.deps.loop.hold();
     try {
@@ -144,10 +175,11 @@ export class ClientRequest extends OutgoingHeaders {
       const res = new IncomingMessage(this.socket);
       res.statusCode = response.status;
       res.statusMessage = response.statusText;
-      res._fill(headersToRecord(response.headers), new Uint8Array(await response.arrayBuffer()));
+      res._setHeaders(headersToRecord(response.headers));
       this.deps.loop._run(() => {
         if (!this.emit('response', res)) res.resume();
       });
+      await this.streamBody(response, res);
     } catch (error) {
       if (!this.aborted) this.deps.loop._run(() => this.emit('error', error));
     } finally {
@@ -165,9 +197,40 @@ export function createFetch(deps: ClientDeps): typeof fetch {
       const url = new URL(request.url);
       if (!isLocalHost(url.hostname)) return await deps.system.fetch(url.href, init ?? (typeof input === 'object' && !(input instanceof URL) ? { method: request.method, headers: request.headers, body: request.body, signal: request.signal } : undefined));
       const body = request.method === 'GET' || request.method === 'HEAD' ? null : new Uint8Array(await request.arrayBuffer());
-      return await sendRequest(deps.system, url, { method: request.method, url: url.pathname + url.search, headers: headersToRecord(request.headers), body });
+      const response = await sendRequest(deps.system, url, { method: request.method, url: url.pathname + url.search, headers: headersToRecord(request.headers), body });
+      return holdWhileReading(response, () => deps.loop.hold());
     } finally {
       release();
     }
   };
 }
+
+/**
+ * A loopback body streams from a server that may live in another process, so
+ * nothing else keeps this one alive while the program awaits the next chunk:
+ * hold the loop for each pending read — and only then, so a body nobody reads
+ * does not keep the process running.
+ */
+function holdWhileReading(response: Response, hold: () => () => void): Response {
+  if (!response.body) return response;
+  const reader = response.body.getReader();
+  const body = new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        const release = hold();
+        try {
+          const { value, done } = await reader.read();
+          if (done) controller.close();
+          else controller.enqueue(value);
+        } catch (error) {
+          controller.error(error);
+        } finally {
+          release();
+        }
+      },
+      cancel: (reason) => reader.cancel(reason),
+    },
+    { highWaterMark: 0 },
+  );
+  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}

package/src/node/http/index.ts

@@ -8,6 +8,7 @@ import { EventEmitterBase } from '../events.js';
 import { ClientRequest, createFetch, type ClientDeps } from './client.js';
 import { FakeSocket, IncomingMessage, OutgoingHeaders, Server, ServerResponse } from './server.js';
 import { METHODS, STATUS_CODES } from './status.js';
+import { textResponse } from '../../system/httpStream.js';
 
 export { createFetch };
 
@@ -74,7 +75,7 @@ export function createNetModule(deps: ClientDeps): Record<string, unknown> {
       const port = typeof first === 'object' && first ? Number((first as { port?: number }).port ?? 0) : Number(first ?? 0);
       if (callback) this.once('listening', callback);
       try {
-        this.reservation = deps.system.listen(port, async () => ({ status: 502, headers: { 'content-type': 'text/plain' }, body: new TextEncoder().encode('Not an HTTP server') }));
+        this.reservation = deps.system.listen(port, async () => textResponse(502, 'Not an HTTP server'));
       } catch (error) {
         queueMicrotask(() => this.emit('error', error));
         return this;