@seanhogg/builderforce-webcontainers-core 2026.10.1 → 2026.10.3

package/src/node/urlqs.ts

@@ -0,0 +1,162 @@
+/**
+ * `url` (WHATWG URL plus the legacy `parse`/`format`/`resolve`) and
+ * `querystring`. Legacy `url.parse` is still everywhere in Express-era code
+ * (`parseurl`, `send`), so it returns Node's full shape.
+ */
+
+export function createQuerystringModule(): Record<string, unknown> {
+  const escape = (s: string) => encodeURIComponent(s);
+  const unescape = (s: string) => {
+    try {
+      return decodeURIComponent(s);
+    } catch {
+      return s;
+    }
+  };
+  const stringifyPrimitive = (v: unknown) => (typeof v === 'string' ? v : typeof v === 'number' && Number.isFinite(v) ? String(v) : typeof v === 'boolean' || typeof v === 'bigint' ? String(v) : '');
+  const parse = (str: string, sep = '&', eq = '=', options?: { maxKeys?: number; decodeURIComponent?: (s: string) => string }) => {
+    const out: Record<string, string | string[]> = Object.create(null);
+    if (typeof str !== 'string' || !str) return out;
+    const decode = options?.decodeURIComponent ?? unescape;
+    const parts = str.split(sep);
+    const max = options?.maxKeys ?? 1000;
+    for (const part of max > 0 ? parts.slice(0, max) : parts) {
+      if (!part) continue;
+      const idx = part.indexOf(eq);
+      const key = decode((idx >= 0 ? part.slice(0, idx) : part).replace(/\+/g, ' '));
+      const value = idx >= 0 ? decode(part.slice(idx + eq.length).replace(/\+/g, ' ')) : '';
+      const existing = out[key];
+      if (existing === undefined) out[key] = value;
+      else if (Array.isArray(existing)) existing.push(value);
+      else out[key] = [existing, value];
+    }
+    return out;
+  };
+  const stringify = (obj: Record<string, unknown>, sep = '&', eq = '=', options?: { encodeURIComponent?: (s: string) => string }) => {
+    const encode = options?.encodeURIComponent ?? escape;
+    if (!obj || typeof obj !== 'object') return '';
+    return Object.keys(obj)
+      .map((k) => {
+        const v = obj[k];
+        const ks = encode(stringifyPrimitive(k)) + eq;
+        return Array.isArray(v) ? v.map((x) => ks + encode(stringifyPrimitive(x))).join(sep) : ks + encode(stringifyPrimitive(v));
+      })
+      .filter(Boolean)
+      .join(sep);
+  };
+  return { parse, decode: parse, stringify, encode: stringify, escape, unescape };
+}
+
+export interface LegacyUrl {
+  protocol: string | null;
+  slashes: boolean | null;
+  auth: string | null;
+  host: string | null;
+  port: string | null;
+  hostname: string | null;
+  hash: string | null;
+  search: string | null;
+  query: string | Record<string, unknown> | null;
+  pathname: string | null;
+  path: string | null;
+  href: string;
+}
+
+export function createUrlModule(qs: Record<string, any>): Record<string, unknown> {
+  function parse(input: string, parseQueryString = false, slashesDenoteHost = false): LegacyUrl {
+    let rest = input.trim();
+    const out: LegacyUrl = { protocol: null, slashes: null, auth: null, host: null, port: null, hostname: null, hash: null, search: null, query: null, pathname: null, path: null, href: '' };
+    const hashAt = rest.indexOf('#');
+    if (hashAt >= 0) {
+      out.hash = rest.slice(hashAt);
+      rest = rest.slice(0, hashAt);
+    }
+    const queryAt = rest.indexOf('?');
+    if (queryAt >= 0) {
+      out.search = rest.slice(queryAt);
+      out.query = rest.slice(queryAt + 1);
+      rest = rest.slice(0, queryAt);
+    } else if (parseQueryString) {
+      out.search = '';
+      out.query = {};
+    }
+    const proto = /^([a-z][a-z0-9.+-]*:)/i.exec(rest);
+    if (proto) {
+      out.protocol = proto[1]!.toLowerCase();
+      rest = rest.slice(proto[1]!.length);
+    }
+    if ((proto || slashesDenoteHost) && rest.startsWith('//')) {
+      out.slashes = true;
+      rest = rest.slice(2);
+      const end = rest.search(/[/]/);
+      let authority = end >= 0 ? rest.slice(0, end) : rest;
+      rest = end >= 0 ? rest.slice(end) : '';
+      const at = authority.lastIndexOf('@');
+      if (at >= 0) {
+        out.auth = decodeURIComponent(authority.slice(0, at));
+        authority = authority.slice(at + 1);
+      }
+      out.host = authority.toLowerCase();
+      const portMatch = /:(\d*)$/.exec(out.host);
+      if (portMatch) {
+        out.port = portMatch[1] || null;
+        out.hostname = out.host.slice(0, -portMatch[0].length);
+      } else out.hostname = out.host;
+      if (out.hostname.startsWith('[') && out.hostname.endsWith(']')) out.hostname = out.hostname.slice(1, -1);
+      if (!rest && out.protocol && /^(https?|ftp|wss?|file):$/.test(out.protocol)) rest = '/';
+    }
+    out.pathname = rest || (out.slashes ? '/' : null);
+    if (parseQueryString && typeof out.query === 'string') out.query = qs.parse(out.query);
+    out.path = (out.pathname ?? '') + (out.search ?? '') || null;
+    out.href = format(out);
+    return out;
+  }
+
+  function format(obj: Partial<LegacyUrl> | URL | string): string {
+    if (typeof obj === 'string') return format(parse(obj));
+    if (obj instanceof URL) return obj.href;
+    const protocol = obj.protocol ? (obj.protocol.endsWith(':') ? obj.protocol : obj.protocol + ':') : '';
+    let host = '';
+    if (obj.host) host = (obj.auth ? encodeURIComponent(obj.auth).replace(/%3A/i, ':') + '@' : '') + obj.host;
+    else if (obj.hostname) host = (obj.auth ? obj.auth + '@' : '') + (obj.hostname.includes(':') ? `[${obj.hostname}]` : obj.hostname) + (obj.port ? ':' + obj.port : '');
+    let search = obj.search ?? '';
+    if (!search && obj.query && typeof obj.query === 'object') {
+      const s = qs.stringify(obj.query);
+      if (s) search = '?' + s;
+    } else if (search && !search.startsWith('?')) search = '?' + search;
+    const slashes = obj.slashes || (host && /^(https?|ftp|wss?|file):$/.test(protocol)) ? '//' : '';
+    let pathname = obj.pathname ?? '';
+    if (host && pathname && !pathname.startsWith('/')) pathname = '/' + pathname;
+    const hash = obj.hash ? (obj.hash.startsWith('#') ? obj.hash : '#' + obj.hash) : '';
+    return `${protocol}${slashes}${host}${pathname}${search}${hash}`;
+  }
+
+  function resolve(from: string, to: string): string {
+    const base = new URL(from, 'resolve://');
+    const resolved = new URL(to, base);
+    if (resolved.protocol === 'resolve:') {
+      const { pathname, search, hash } = resolved;
+      return pathname + search + hash;
+    }
+    return resolved.href;
+  }
+
+  return {
+    URL,
+    URLSearchParams,
+    parse,
+    format,
+    resolve,
+    resolveObject: (from: string, to: string) => parse(resolve(from, to)),
+    fileURLToPath: (url: string | URL) => {
+      const u = typeof url === 'string' ? new URL(url) : url;
+      if (u.protocol !== 'file:') throw Object.assign(new TypeError('The URL must be of scheme file'), { code: 'ERR_INVALID_URL_SCHEME' });
+      return decodeURIComponent(u.pathname);
+    },
+    pathToFileURL: (path: string) => new URL('file://' + encodeURI(path).replace(/[?#]/g, encodeURIComponent)),
+    domainToASCII: (d: string) => d,
+    domainToUnicode: (d: string) => d,
+    urlToHttpOptions: (u: URL) => ({ protocol: u.protocol, hostname: u.hostname, hash: u.hash, search: u.search, pathname: u.pathname, path: u.pathname + u.search, href: u.href, port: u.port ? Number(u.port) : undefined }),
+    Url: function Url() {},
+  };
+}

package/src/node/util.ts

@@ -0,0 +1,145 @@
+/**
+ * Node's `util` module: formatting and inspection (inspect.ts), the classic
+ * helpers (`inherits`, `promisify`, `deprecate`, `callbackify`), `types` and
+ * `isDeepStrictEqual`.
+ */
+import { format, inspect } from './inspect.js';
+
+export const promisifyCustom = Symbol.for('nodejs.util.promisify.custom');
+
+export function promisify(fn: (...args: any[]) => unknown): (...args: any[]) => Promise<any> {
+  if (typeof fn !== 'function') throw new TypeError('The "original" argument must be of type function');
+  const custom = (fn as any)[promisifyCustom];
+  if (typeof custom === 'function') return custom;
+  function promisified(this: unknown, ...args: unknown[]) {
+    return new Promise((resolve, reject) => {
+      fn.call(this, ...args, (error: unknown, ...values: unknown[]) => {
+        if (error) reject(error);
+        else resolve(values.length > 1 ? values : values[0]);
+      });
+    });
+  }
+  Object.setPrototypeOf(promisified, Object.getPrototypeOf(fn));
+  return Object.defineProperties(promisified, Object.getOwnPropertyDescriptors(fn));
+}
+promisify.custom = promisifyCustom;
+
+export function inherits(ctor: { prototype: object; super_?: unknown }, superCtor: { prototype: object }): void {
+  if (!superCtor?.prototype) throw new TypeError('The "superCtor.prototype" property must be of type object');
+  ctor.super_ = superCtor;
+  Object.setPrototypeOf(ctor.prototype, superCtor.prototype);
+}
+
+export function isDeepStrictEqual(a: unknown, b: unknown, seen = new Map<object, object>()): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
+  if (seen.get(a) === b) return true;
+  seen.set(a, b);
+  if (a instanceof Date) return a.getTime() === (b as Date).getTime();
+  if (a instanceof RegExp) return String(a) === String(b);
+  if (a instanceof Map) {
+    const m = b as Map<unknown, unknown>;
+    if (a.size !== m.size) return false;
+    for (const [k, v] of a) if (!m.has(k) || !isDeepStrictEqual(v, m.get(k), seen)) return false;
+    return true;
+  }
+  if (a instanceof Set) {
+    const s = b as Set<unknown>;
+    if (a.size !== s.size) return false;
+    for (const v of a) if (!s.has(v) && ![...s].some((w) => isDeepStrictEqual(v, w, seen))) return false;
+    return true;
+  }
+  if (ArrayBuffer.isView(a)) {
+    const x = a as unknown as ArrayLike<number>;
+    const y = b as unknown as ArrayLike<number>;
+    if (x.length !== y.length) return false;
+    for (let i = 0; i < x.length; i++) if (!Object.is(x[i], y[i])) return false;
+    return true;
+  }
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && isDeepStrictEqual((a as any)[k], (b as any)[k], seen));
+}
+
+const tag = (v: unknown) => Object.prototype.toString.call(v).slice(8, -1);
+
+export const types = {
+  isPromise: (v: unknown) => v instanceof Promise,
+  isDate: (v: unknown) => v instanceof Date,
+  isRegExp: (v: unknown) => v instanceof RegExp,
+  isMap: (v: unknown) => v instanceof Map,
+  isSet: (v: unknown) => v instanceof Set,
+  isWeakMap: (v: unknown) => v instanceof WeakMap,
+  isWeakSet: (v: unknown) => v instanceof WeakSet,
+  isNativeError: (v: unknown) => v instanceof Error,
+  isTypedArray: (v: unknown) => ArrayBuffer.isView(v) && !(v instanceof DataView),
+  isUint8Array: (v: unknown) => v instanceof Uint8Array,
+  isArrayBuffer: (v: unknown) => v instanceof ArrayBuffer,
+  isAnyArrayBuffer: (v: unknown) => v instanceof ArrayBuffer || tag(v) === 'SharedArrayBuffer',
+  isArrayBufferView: (v: unknown) => ArrayBuffer.isView(v),
+  isDataView: (v: unknown) => v instanceof DataView,
+  isAsyncFunction: (v: unknown) => tag(v) === 'AsyncFunction' || tag(v) === 'AsyncGeneratorFunction',
+  isGeneratorFunction: (v: unknown) => tag(v) === 'GeneratorFunction' || tag(v) === 'AsyncGeneratorFunction',
+  isGeneratorObject: (v: unknown) => tag(v) === 'Generator',
+  isBoxedPrimitive: (v: unknown) => v instanceof Number || v instanceof String || v instanceof Boolean,
+  isProxy: () => false,
+  isExternal: () => false,
+  isModuleNamespaceObject: (v: unknown) => tag(v) === 'Module',
+};
+
+export function createUtilModule(env: () => Record<string, string | undefined>, warn: (message: string) => void): Record<string, unknown> {
+  const warned = new Set<string>();
+  return {
+    format,
+    formatWithOptions: (_options: unknown, ...args: unknown[]) => format(...args),
+    inspect,
+    inherits,
+    promisify,
+    callbackify(fn: (...args: any[]) => Promise<unknown>) {
+      return function (this: unknown, ...args: any[]) {
+        const callback = args.pop() as (error: unknown, value?: unknown) => void;
+        fn.apply(this, args).then((value) => callback(null, value), (error) => callback(error ?? new Error('Promise was rejected with a falsy value')));
+      };
+    },
+    deprecate<T extends (...args: any[]) => unknown>(fn: T, message: string, code?: string): T {
+      return function (this: unknown, ...args: unknown[]) {
+        const key = code ?? message;
+        if (!warned.has(key)) {
+          warned.add(key);
+          warn(`(node) [${code ?? 'DEP'}] DeprecationWarning: ${message}`);
+        }
+        return fn.apply(this, args);
+      } as T;
+    },
+    debuglog(section: string) {
+      const enabled = new RegExp(`\\b${section}\\b`, 'i').test(env().NODE_DEBUG ?? '');
+      const log = (...args: unknown[]) => enabled && warn(`${section.toUpperCase()}: ${format(...args)}`);
+      log.enabled = enabled;
+      return log;
+    },
+    isDeepStrictEqual: (a: unknown, b: unknown) => isDeepStrictEqual(a, b),
+    types,
+    TextEncoder,
+    TextDecoder,
+    stripVTControlCharacters: (s: string) => s.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, ''),
+    styleText: (_style: unknown, text: string) => text,
+    toUSVString: (s: string) => s.replace(/[\uD800-\uDFFF]/g, '�'),
+    isArray: Array.isArray,
+    isBoolean: (v: unknown) => typeof v === 'boolean',
+    isNull: (v: unknown) => v === null,
+    isNullOrUndefined: (v: unknown) => v == null,
+    isNumber: (v: unknown) => typeof v === 'number',
+    isString: (v: unknown) => typeof v === 'string',
+    isSymbol: (v: unknown) => typeof v === 'symbol',
+    isUndefined: (v: unknown) => v === undefined,
+    isRegExp: types.isRegExp,
+    isObject: (v: unknown) => v !== null && typeof v === 'object',
+    isDate: types.isDate,
+    isError: types.isNativeError,
+    isFunction: (v: unknown) => typeof v === 'function',
+    isPrimitive: (v: unknown) => v === null || (typeof v !== 'object' && typeof v !== 'function'),
+    isBuffer: (v: unknown) => (v as { constructor?: { name?: string } })?.constructor?.name === 'Buffer',
+  };
+}

package/src/node/zlib.ts

@@ -0,0 +1,145 @@
+/**
+ * `zlib` over fflate: gzip/deflate/raw deflate in sync, callback, promise-less
+ * and streaming forms (compression middleware pipes through `createGzip`).
+ * Brotli is not available and says so.
+ */
+import * as fflate from 'fflate';
+import { Buffer } from './buffer.js';
+import { Transform } from './stream/index.js';
+
+type Input = string | ArrayBufferView | ArrayBuffer;
+type Options = { level?: number };
+
+const bytes = (input: Input): Uint8Array =>
+  typeof input === 'string' ? Buffer.from(input) : input instanceof ArrayBuffer ? new Uint8Array(input) : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+
+const level = (options?: Options) => (options?.level === undefined || options.level < 0 ? 6 : Math.min(9, options.level)) as fflate.DeflateOptions['level'];
+
+const SYNC: Record<string, (data: Uint8Array, options?: Options) => Uint8Array> = {
+  gzip: (d, o) => fflate.gzipSync(d, { level: level(o) }),
+  gunzip: (d) => fflate.gunzipSync(d),
+  deflate: (d, o) => fflate.zlibSync(d, { level: level(o) }),
+  inflate: (d) => fflate.unzlibSync(d),
+  deflateRaw: (d, o) => fflate.deflateSync(d, { level: level(o) }),
+  inflateRaw: (d) => fflate.inflateSync(d),
+  unzip: (d) => fflate.decompressSync(d),
+};
+
+type StreamCtor = new (cb?: fflate.FlateStreamHandler) => { push(chunk: Uint8Array, final?: boolean): void; ondata: fflate.FlateStreamHandler };
+const STREAMS: Record<string, (options?: Options) => InstanceType<StreamCtor>> = {
+  Gzip: (o) => new fflate.Gzip({ level: level(o) }),
+  Gunzip: () => new fflate.Gunzip(),
+  Deflate: (o) => new fflate.Zlib({ level: level(o) }),
+  Inflate: () => new fflate.Unzlib(),
+  DeflateRaw: (o) => new fflate.Deflate({ level: level(o) }),
+  InflateRaw: () => new fflate.Inflate(),
+  Unzip: () => new fflate.Decompress() as unknown as InstanceType<StreamCtor>,
+};
+
+function zlibError(error: unknown): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  return Object.assign(new Error(message || 'invalid compressed data'), { code: 'Z_DATA_ERROR', errno: -3 });
+}
+
+class ZlibStream extends Transform {
+  private readonly engine: InstanceType<StreamCtor>;
+  bytesWritten = 0;
+
+  constructor(kind: string, options?: Options) {
+    super();
+    this.engine = STREAMS[kind]!(options);
+    this.engine.ondata = (data: Uint8Array) => {
+      if (data.length) this.push(Buffer.from(data));
+    };
+  }
+
+  override _transform(chunk: Uint8Array, _encoding: string, callback: (error?: Error | null) => void): void {
+    try {
+      this.bytesWritten += chunk.length;
+      this.engine.push(chunk, false);
+      callback();
+    } catch (error) {
+      callback(zlibError(error));
+    }
+  }
+
+  override _flush(callback: (error?: Error | null) => void): void {
+    try {
+      this.engine.push(new Uint8Array(0), true);
+      callback();
+    } catch (error) {
+      callback(zlibError(error));
+    }
+  }
+
+  flush(_kind?: unknown, callback?: () => void): void {
+    callback?.();
+  }
+
+  params(_level: number, _strategy: number, callback?: () => void): void {
+    callback?.();
+  }
+
+  close(callback?: () => void): void {
+    this.destroy();
+    callback?.();
+  }
+}
+
+const noBrotli = () => {
+  throw Object.assign(new Error('Brotli is not available in the browser runtime'), { code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM' });
+};
+
+export function createZlibModule(): Record<string, unknown> {
+  const mod: Record<string, unknown> = {
+    constants: {
+      Z_NO_FLUSH: 0, Z_PARTIAL_FLUSH: 1, Z_SYNC_FLUSH: 2, Z_FULL_FLUSH: 3, Z_FINISH: 4, Z_BLOCK: 5,
+      Z_OK: 0, Z_STREAM_END: 1, Z_NEED_DICT: 2, Z_ERRNO: -1, Z_STREAM_ERROR: -2, Z_DATA_ERROR: -3, Z_BUF_ERROR: -5,
+      Z_NO_COMPRESSION: 0, Z_BEST_SPEED: 1, Z_BEST_COMPRESSION: 9, Z_DEFAULT_COMPRESSION: -1,
+      Z_FILTERED: 1, Z_HUFFMAN_ONLY: 2, Z_RLE: 3, Z_FIXED: 4, Z_DEFAULT_STRATEGY: 0,
+      BROTLI_OPERATION_PROCESS: 0, BROTLI_OPERATION_FLUSH: 1, BROTLI_OPERATION_FINISH: 2, BROTLI_PARAM_QUALITY: 1,
+    },
+    brotliCompressSync: noBrotli,
+    brotliDecompressSync: noBrotli,
+    brotliCompress: noBrotli,
+    brotliDecompress: noBrotli,
+    createBrotliCompress: noBrotli,
+    createBrotliDecompress: noBrotli,
+    crc32: (data: Input, value = 0) => {
+      let crc = ~value >>> 0;
+      for (const byte of bytes(data)) {
+        crc ^= byte;
+        for (let k = 0; k < 8; k++) crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+      }
+      return ~crc >>> 0;
+    },
+  };
+  for (const [name, fn] of Object.entries(SYNC)) {
+    mod[`${name}Sync`] = (input: Input, options?: Options) => {
+      try {
+        return Buffer.from(fn(bytes(input), options));
+      } catch (error) {
+        throw zlibError(error);
+      }
+    };
+    mod[name] = (input: Input, options: Options | ((e: Error | null, r?: Buffer) => void), callback?: (e: Error | null, r?: Buffer) => void) => {
+      const cb = (typeof options === 'function' ? options : callback)!;
+      queueMicrotask(() => {
+        try {
+          cb(null, Buffer.from(fn(bytes(input), typeof options === 'object' ? options : undefined)));
+        } catch (error) {
+          cb(zlibError(error));
+        }
+      });
+    };
+  }
+  for (const kind of Object.keys(STREAMS)) {
+    mod[`create${kind}`] = (options?: Options) => new ZlibStream(kind, options);
+    mod[kind] = class extends ZlibStream {
+      constructor(options?: Options) {
+        super(kind, options);
+      }
+    };
+  }
+  return mod;
+}

package/src/packageCdn.ts

@@ -8,6 +8,16 @@ export interface PackageCdn {
   urlFor(name: string, subpath: string): string;
 }
 
+/**
+ * Makes the CDN for one project, from its dependency ranges. `dev` is true for the
+ * dev server and false for a production build, so a factory can pick development
+ * or production package builds (React's readable errors vs its small bundle).
+ */
+export type PackageCdnFactory = (dependencies: Record<string, string>, options: { dev: boolean }) => PackageCdn;
+
+/** esm.sh, pinned to the project's ranges. */
+export const esmShCdnFactory: PackageCdnFactory = (dependencies, { dev }) => createEsmShCdn({ dependencies, dev });
+
 export interface EsmShOptions {
   /** Defaults to https://esm.sh. Any esm.sh-compatible server works. */
   origin?: string;
@@ -18,7 +28,7 @@ export interface EsmShOptions {
 }
 
 /** A range the CDN can't fetch (`workspace:*`, `file:../x`, `link:`, git URLs). */
-function isRegistryRange(range: string): boolean {
+export function isRegistryRange(range: string): boolean {
   return !/^(workspace|file|link|portal|git\+|git:|github:|https?:)/.test(range) && !range.includes('/');
 }
 

package/src/projectConfig.ts

@@ -17,8 +17,18 @@ export const CONFIG_FILES = [
   '/.env.local',
   '/.env.development',
   '/.env.development.local',
+  '/.env.production',
+  '/.env.production.local',
 ] as const;
 
+/** Which `.env.<mode>` files apply: the dev server reads development, a build production. */
+export type BuildMode = 'development' | 'production';
+
+/** Vite's load order — later files win. */
+export function envFiles(mode: BuildMode): string[] {
+  return ['/.env', '/.env.local', `/.env.${mode}`, `/.env.${mode}.local`];
+}
+
 export interface PathAlias {
   /** The specifier prefix, without the trailing `*` (`@/`). Exact when `wildcard` is false. */
   prefix: string;
@@ -83,9 +93,25 @@ function readDependencies(fs: VirtualFileSystem): Record<string, string> {
   return out;
 }
 
+/**
+ * The root tsconfig's compiler options. Current Vite templates (React, Vue,
+ * Svelte) keep a root `tsconfig.json` with only `references`, and the app's real
+ * options — `paths` included — in `tsconfig.app.json`; options missing from the
+ * root are taken from the referenced configs, in order.
+ */
 function readCompilerOptions(fs: VirtualFileSystem): Record<string, unknown> {
   const tsconfig = readJson(fs, '/tsconfig.json') ?? readJson(fs, '/jsconfig.json') ?? {};
-  return asRecord(tsconfig.compilerOptions);
+  const options = { ...asRecord(tsconfig.compilerOptions) };
+  const references = Array.isArray(tsconfig.references) ? tsconfig.references : [];
+  for (const reference of references) {
+    const target = asRecord(reference).path;
+    if (typeof target !== 'string') continue;
+    const file = target.endsWith('.json') ? join('/', target) : join('/', target, 'tsconfig.json');
+    for (const [key, value] of Object.entries(asRecord(readJson(fs, file)?.compilerOptions))) {
+      if (!(key in options)) options[key] = value;
+    }
+  }
+  return options;
 }
 
 function readAliases(options: Record<string, unknown>): PathAlias[] {
@@ -131,27 +157,28 @@ export function parseDotenv(text: string): Record<string, string> {
   return out;
 }
 
-function readEnv(fs: VirtualFileSystem): Record<string, string> {
+function readEnv(fs: VirtualFileSystem, mode: BuildMode): Record<string, string> {
   const env: Record<string, string> = {};
-  for (const file of CONFIG_FILES) {
-    if (!file.startsWith('/.env')) continue;
+  for (const file of envFiles(mode)) {
     const text = fs.readText(file);
     if (text !== undefined) Object.assign(env, parseDotenv(text));
   }
   return env;
 }
 
-export function readProjectConfig(fs: VirtualFileSystem): ProjectConfig {
+export function readProjectConfig(fs: VirtualFileSystem, mode: BuildMode = 'development'): ProjectConfig {
   const options = readCompilerOptions(fs);
   return {
     dependencies: readDependencies(fs),
     aliases: readAliases(options),
     jsx: readJsx(options),
-    env: readEnv(fs),
+    env: readEnv(fs, mode),
   };
 }
 
 /** True when a change to `path` invalidates the derived {@link ProjectConfig}. */
 export function isConfigFile(path: string): boolean {
-  return (CONFIG_FILES as readonly string[]).includes(normalizePath(path));
+  const normalized = normalizePath(path);
+  // Any root tsconfig: the root one may reference `tsconfig.app.json` and friends.
+  return (CONFIG_FILES as readonly string[]).includes(normalized) || /^\/tsconfig[^/]*\.json$/.test(normalized);
 }