@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.3

package/src/buildHost.ts

@@ -0,0 +1,154 @@
+import type { VirtualFileSystem } from './vfs.js';
+import type { ProjectConfig } from './projectConfig.js';
+import type { PackageCdn } from './packageCdn.js';
+import type { BundleHost, BundleLoad, ResolveKind } from './bundler.js';
+import type { ComponentCompilers } from './components.js';
+import { componentExtension } from './components.js';
+import { loaderFor } from './transformer.js';
+import { basename, dirname, extname, join } from './paths.js';
+import { isBareSpecifier, resolveAlias, resolveLocal, splitPackageSpecifier } from './resolve.js';
+import { contentHash } from './hash.js';
+
+/**
+ * The project side of a production build: the same resolution rules the dev
+ * server uses (resolve.ts, tsconfig aliases, the package CDN), expressed as a
+ * {@link BundleHost} so any bundler can walk the graph.
+ *
+ * Packages stay on the CDN — a bare import becomes an absolute, version-pinned
+ * URL with the same `?deps=` dedupe as the dev server — so the output runs
+ * without node_modules. Assets (images, fonts, `?url`) are emitted by the host
+ * itself with content-hashed names, so one asset referenced from JS and CSS is
+ * written once.
+ */
+export interface BuildHostOptions {
+  fs: VirtualFileSystem;
+  config: ProjectConfig;
+  cdn: PackageCdn;
+  components: ComponentCompilers;
+  publicDir: string;
+  /** The URL the site is served under: `./` (relative) or absolute, ending in `/`. */
+  base: string;
+}
+
+export interface BuildHost extends BundleHost {
+  /** Emitted assets, output path (`assets/logo-1a2b3c4d.svg`) → bytes. */
+  readonly assets: Map<string, Uint8Array>;
+}
+
+/** The query a compiled component's own CSS is imported under. */
+const COMPONENT_CSS = 'bfwc-component-css';
+/** The query (and virtual directory) of a package stylesheet imported from JS. */
+const PACKAGE_CSS = 'bfwc-package-css';
+const encoder = new TextEncoder();
+
+function splitAnyQuery(specifier: string): { path: string; query?: string } {
+  const at = specifier.indexOf('?');
+  return at < 0 ? { path: specifier } : { path: specifier.slice(0, at), query: specifier.slice(at + 1) || undefined };
+}
+
+/** Relative base: every chunk and asset lives in `assets/`, so siblings are `./x`. */
+function isRelativeBase(base: string): boolean {
+  return base.startsWith('.');
+}
+
+export function createBuildHost(options: BuildHostOptions): BuildHost {
+  const { fs, config, cdn, publicDir, base } = options;
+  const assets = new Map<string, Uint8Array>();
+  const componentCss = new Map<string, string>();
+
+  function emitAsset(path: string): string {
+    const raw = fs.readFile(path) ?? new Uint8Array();
+    const bytes = typeof raw === 'string' ? encoder.encode(raw) : raw;
+    const ext = extname(path);
+    const stem = basename(path).slice(0, basename(path).length - ext.length) || 'asset';
+    const name = `${stem}-${contentHash(bytes)}${ext}`;
+    assets.set(`assets/${name}`, bytes);
+    return name;
+  }
+
+  /** An asset's URL from a stylesheet. CSS lives in `assets/` beside it. */
+  function cssAssetUrl(path: string): string {
+    const name = emitAsset(path);
+    return isRelativeBase(base) ? `./${name}` : `${base}assets/${name}`;
+  }
+
+  /**
+   * An asset imported from JS. With a relative base the URL is resolved against
+   * the chunk (`import.meta.url`), not the page — the same app must work when
+   * served from any directory, and from client-side routes deeper than `/`.
+   */
+  function assetModule(path: string): string {
+    const name = emitAsset(path);
+    return isRelativeBase(base)
+      ? `export default new URL(${JSON.stringify(`./${name}`)}, import.meta.url).href;`
+      : `export default ${JSON.stringify(`${base}assets/${name}`)};`;
+  }
+
+  function resolveFile(fromDir: string, path: string, kind: ResolveKind): string | undefined {
+    const local = resolveLocal(fs, fromDir, path);
+    if (local) return local;
+    // `/vite.svg` in source names `public/vite.svg`, served from the site root.
+    if (path.startsWith('/')) return resolveLocal(fs, '/', join(publicDir, path));
+    // CSS `url(bg.png)` is relative even without `./`.
+    if (kind === 'css-url' || kind === 'css-import') return resolveLocal(fs, fromDir, `./${path}`);
+    return undefined;
+  }
+
+  return {
+    assets,
+
+    resolve(specifier, importer, kind) {
+      if (/^(https?:|data:|blob:|node:|\/\/)/i.test(specifier)) return { external: specifier };
+      const css = kind === 'css-import' || kind === 'css-url';
+      // `~pkg/x.css` is the webpack/Vite spelling of a package path inside CSS.
+      const unhashed = (css && specifier.startsWith('~') ? specifier.slice(1) : specifier).split('#');
+      const fragment = unhashed.length > 1 ? `#${unhashed.slice(1).join('#')}` : ''; // `icons.svg#close`
+      const { path, query } = splitAnyQuery(unhashed[0]!);
+      const fromDir = importer ? dirname(importer) : '/';
+
+      let file: string | undefined;
+      if (isBareSpecifier(path)) {
+        file = (css ? resolveLocal(fs, fromDir, `./${path}`) : undefined) ?? resolveAlias(fs, config.aliases, path);
+        if (!file) {
+          const { name, subpath } = splitPackageSpecifier(path);
+          // A package stylesheet imported from JS (`import 'bootstrap/dist/css/bootstrap.css'`)
+          // can't stay a JS import of a CSS URL; it joins the CSS bundle as an @import.
+          if (!css && extname(subpath) === '.css') return { path: `/${PACKAGE_CSS}/${path}`, query: PACKAGE_CSS };
+          return { external: cdn.urlFor(name, subpath) };
+        }
+      } else {
+        file = resolveFile(fromDir, path, kind);
+      }
+      if (!file) return undefined;
+      if (kind === 'css-url' && extname(file) !== '.css') return { external: cssAssetUrl(file) + fragment };
+      return { path: file, ...(query ? { query } : {}) };
+    },
+
+    async load(path, query): Promise<BundleLoad> {
+      if (query === 'raw') return { contents: fs.readText(path) ?? '', loader: 'text' };
+      if (query === COMPONENT_CSS) return { contents: componentCss.get(path) ?? '', loader: 'css' };
+      if (query === PACKAGE_CSS) {
+        const { name, subpath } = splitPackageSpecifier(path.slice(PACKAGE_CSS.length + 2));
+        return { contents: `@import ${JSON.stringify(cdn.urlFor(name, subpath))};`, loader: 'css' };
+      }
+
+      const ext = extname(path);
+      if (query === 'url') return { contents: assetModule(path), loader: 'js' };
+      const loader = loaderFor(ext);
+      if (loader) return { contents: fs.readFile(path) ?? '', loader };
+      if (ext === '.css') return { contents: fs.readFile(path) ?? '', loader: /\.module\.css$/i.test(path) ? 'local-css' : 'css' };
+      if (ext === '.json') return { contents: fs.readFile(path) ?? '', loader: 'json' };
+
+      const extension = componentExtension(ext);
+      if (extension) {
+        const compiler = await options.components(extension, config.dependencies);
+        const compiled = await compiler.compile(fs.readText(path) ?? '', { path, dev: false });
+        if (!compiled.css) return { contents: compiled.code, loader: compiled.loader };
+        componentCss.set(path, compiled.css);
+        // Importing its own CSS puts the component's styles in the entry's CSS bundle.
+        return { contents: `${compiled.code}\nimport ${JSON.stringify(`${path}?${COMPONENT_CSS}`)};`, loader: compiled.loader };
+      }
+      return { contents: assetModule(path), loader: 'js' };
+    },
+  };
+}

package/src/buildHtml.ts

@@ -0,0 +1,101 @@
+import type { VirtualFileSystem } from './vfs.js';
+import { dirname } from './paths.js';
+import { resolveLocal } from './resolve.js';
+
+/**
+ * The HTML side of a production build: find the page's local entry points
+ * (module scripts and stylesheets), then rewrite the page to load their bundles
+ * instead — the job Vite's build does to `index.html`.
+ */
+
+export interface HtmlEntry {
+  tag: 'script' | 'style';
+  /** The attribute value as written (`/src/main.tsx`). */
+  url: string;
+  /** The VFS file it names. */
+  path: string;
+}
+
+const TAG = /<([a-zA-Z][\w-]*)\b[^>]*>/g;
+const URL_ATTR = /(\s(src|href)\s*=\s*)(["'])([^"']*)\3/gi;
+
+function attribute(tag: string, name: string): string | undefined {
+  const match = new RegExp(`\\s${name}\\s*=\\s*(["'])([^"']*)\\1`, 'i').exec(tag);
+  return match?.[2];
+}
+
+function isEntryTag(name: string, tag: string): HtmlEntry['tag'] | undefined {
+  const lower = name.toLowerCase();
+  if (lower === 'script' && attribute(tag, 'type')?.toLowerCase() === 'module' && attribute(tag, 'src')) return 'script';
+  if (lower === 'link' && /(^|\s)stylesheet(\s|$)/i.test(attribute(tag, 'rel') ?? '') && attribute(tag, 'href')) return 'style';
+  return undefined;
+}
+
+/** `%PUBLIC_URL%` (CRA) becomes root-absolute, then is rebased like any other root path. */
+function fillPublicUrl(html: string): string {
+  return html.replace(/%PUBLIC_URL%/g, '');
+}
+
+/** The local file an entry URL names, or undefined for URLs and files that do not exist. */
+function resolveEntry(fs: VirtualFileSystem, htmlPath: string, url: string): string | undefined {
+  if (/^([a-z][a-z0-9+.-]*:|\/\/)/i.test(url)) return undefined;
+  const [path] = url.split(/[?#]/);
+  if (!path) return undefined;
+  // Root-absolute means the project root (Vite's convention), wherever the page lives.
+  return path.startsWith('/') ? resolveLocal(fs, '/', path) : resolveLocal(fs, dirname(htmlPath), path);
+}
+
+export function findHtmlEntries(fs: VirtualFileSystem, html: string, htmlPath: string): HtmlEntry[] {
+  const entries: HtmlEntry[] = [];
+  for (const match of fillPublicUrl(html).matchAll(TAG)) {
+    const kind = isEntryTag(match[1]!, match[0]);
+    if (!kind) continue;
+    const url = attribute(match[0], kind === 'script' ? 'src' : 'href')!;
+    const path = resolveEntry(fs, htmlPath, url);
+    if (path) entries.push({ tag: kind, url, path });
+  }
+  return entries;
+}
+
+export interface BuiltHtmlOptions {
+  /** Where the site is served from, ending in `/` (`./` for relative). */
+  base: string;
+  entries: HtmlEntry[];
+  /** Per entry path, the bundle files (relative to the site root). */
+  outputs: Record<string, { js?: string; css?: string }>;
+  /** Entry script to add when the page has none of its own (CRA). */
+  inject?: string;
+}
+
+function insertBefore(html: string, closing: RegExp, markup: string): string {
+  return closing.test(html) ? html.replace(closing, (tag) => `${markup}\n${tag}`) : html + markup;
+}
+
+export function rewriteBuiltHtml(html: string, options: BuiltHtmlOptions): string {
+  const { base, entries, outputs } = options;
+  const byUrl = new Map(entries.map((entry) => [`${entry.tag}:${entry.url}`, entry]));
+  const stylesheets: string[] = [];
+
+  let out = fillPublicUrl(html).replace(TAG, (tag, name: string) => {
+    const kind = isEntryTag(name, tag);
+    const entry = kind && byUrl.get(`${kind}:${attribute(tag, kind === 'script' ? 'src' : 'href')}`);
+    if (entry) {
+      const output = outputs[entry.path];
+      const file = entry.tag === 'script' ? output?.js : output?.css;
+      if (entry.tag === 'script' && output?.css) stylesheets.push(output.css);
+      return file ? tag.replace(URL_ATTR, (m, attr: string, _n, quote: string) => `${attr}${quote}${base}${file}${quote}`) : tag;
+    }
+    // Any other root-absolute URL (`/favicon.svg` from public/) moves under the base.
+    return tag.replace(URL_ATTR, (m, attr: string, _n, quote: string, value: string) =>
+      value.startsWith('/') && !value.startsWith('//') ? `${attr}${quote}${base}${value.slice(1)}${quote}` : m,
+    );
+  });
+
+  if (options.inject) {
+    const output = outputs[options.inject];
+    if (output?.css) stylesheets.push(output.css);
+    if (output?.js) out = insertBefore(out, /<\/body>/i, `<script type="module" src="${base}${output.js}"></script>`);
+  }
+  const links = [...new Set(stylesheets)].map((css) => `<link rel="stylesheet" href="${base}${css}">`).join('\n');
+  return links ? insertBefore(out, /<\/head>/i, links) : out;
+}

package/src/bundler.ts

@@ -0,0 +1,190 @@
+/**
+ * The production bundler, as a PORT — the build-time sibling of {@link Transformer}.
+ *
+ * The split of responsibilities is deliberate: everything that knows about the
+ * project (how a specifier resolves, what a file compiles to, where assets go)
+ * lives behind {@link BundleHost}, written once in the core; a bundler only walks
+ * the graph through the host's two callbacks and writes chunks. So the esbuild
+ * adapter below is the only esbuild-specific code, and a fork could put Rollup
+ * behind the same port without re-implementing resolution.
+ */
+import type { Loader } from './transformer.js';
+
+export type BundleLoader = Loader | 'css' | 'local-css' | 'json' | 'text';
+
+/** Where an import appears: an entry point, JS, a CSS `@import`, or a CSS `url()`. */
+export type ResolveKind = 'entry' | 'import' | 'css-import' | 'css-url';
+
+/** A module inside the graph (with an optional `?query`), or a URL left as-is in the output. */
+export type BundleResolution = { path: string; query?: string } | { external: string };
+
+export interface BundleLoad {
+  contents: string | Uint8Array;
+  loader: BundleLoader;
+}
+
+export interface BundleHost {
+  /** Undefined means "cannot resolve", reported as a build error. */
+  resolve(specifier: string, importer: string | undefined, kind: ResolveKind): BundleResolution | undefined;
+  load(path: string, query: string | undefined): Promise<BundleLoad> | BundleLoad;
+}
+
+export interface BundleRequest {
+  /** VFS paths of the entry modules (scripts or stylesheets). */
+  entryPoints: string[];
+  host: BundleHost;
+  /** esbuild `define` semantics (values are JS source). */
+  define: Record<string, string>;
+  jsx: { runtime: 'automatic' | 'classic'; importSource: string };
+  minify: boolean;
+}
+
+export interface BundleOutputFile {
+  /** Relative to the site root, e.g. `assets/main-1a2b3c4d.js`. */
+  path: string;
+  contents: Uint8Array;
+}
+
+export interface BundleOutput {
+  files: BundleOutputFile[];
+  /** Per entry point (VFS path): its JS chunk and the CSS extracted from it. */
+  entries: Record<string, { js?: string; css?: string }>;
+}
+
+export interface Bundler {
+  bundle(request: BundleRequest): Promise<BundleOutput>;
+}
+
+// ---- esbuild adapter ------------------------------------------------------
+
+interface EsbuildResolveArgs {
+  path: string;
+  importer: string;
+  kind: string;
+}
+
+interface EsbuildLoadArgs {
+  path: string;
+  suffix?: string;
+}
+
+interface EsbuildResolveResult {
+  path?: string;
+  namespace?: string;
+  suffix?: string;
+  external?: boolean;
+  errors?: Array<{ text: string }>;
+}
+
+interface EsbuildPluginBuild {
+  onResolve(options: { filter: RegExp }, callback: (args: EsbuildResolveArgs) => EsbuildResolveResult): void;
+  onLoad(
+    options: { filter: RegExp; namespace: string },
+    callback: (args: EsbuildLoadArgs) => Promise<{ contents: string | Uint8Array; loader: BundleLoader }>,
+  ): void;
+}
+
+/** The subset of esbuild's (and esbuild-wasm's) `build` API the adapter uses. */
+export interface EsbuildBuildLike {
+  build(options: {
+    entryPoints: string[];
+    bundle: true;
+    write: false;
+    metafile: true;
+    format: 'esm';
+    splitting: true;
+    target: string;
+    outdir: string;
+    entryNames: string;
+    chunkNames: string;
+    assetNames: string;
+    minify: boolean;
+    define: Record<string, string>;
+    jsx: 'automatic' | 'transform';
+    jsxImportSource?: string;
+    charset: 'utf8';
+    logLevel: 'silent';
+    plugins: Array<{ name: string; setup(build: EsbuildPluginBuild): void }>;
+  }): Promise<{
+    outputFiles?: Array<{ path: string; contents: Uint8Array }>;
+    metafile?: { outputs: Record<string, { entryPoint?: string; cssBundle?: string }> };
+  }>;
+}
+
+const NAMESPACE = 'bfwc';
+/** A marker directory: nothing is written; output paths are made relative to it. */
+const OUT_DIR = '__bfwc_dist__';
+
+const KINDS: Record<string, ResolveKind> = {
+  'entry-point': 'entry',
+  'import-rule': 'css-import',
+  'composes-from': 'css-import',
+  'url-token': 'css-url',
+};
+
+/** An output path (absolute, OS-specific, or metafile-relative) → `assets/x.js`. */
+function relativeOutput(path: string): string {
+  const normalized = path.replace(/\\/g, '/');
+  const at = normalized.lastIndexOf(`${OUT_DIR}/`);
+  return at < 0 ? normalized : normalized.slice(at + OUT_DIR.length + 1);
+}
+
+/** Adapt esbuild or esbuild-wasm's `build` to {@link Bundler}. */
+export function createEsbuildBundler(esbuild: EsbuildBuildLike): Bundler {
+  return {
+    async bundle(request) {
+      const { host } = request;
+      const result = await esbuild.build({
+        entryPoints: request.entryPoints,
+        bundle: true,
+        write: false,
+        metafile: true,
+        format: 'esm',
+        splitting: true,
+        target: 'es2022',
+        outdir: OUT_DIR,
+        entryNames: 'assets/[name]-[hash]',
+        chunkNames: 'assets/[name]-[hash]',
+        assetNames: 'assets/[name]-[hash]',
+        minify: request.minify,
+        define: request.define,
+        jsx: request.jsx.runtime === 'automatic' ? 'automatic' : 'transform',
+        ...(request.jsx.runtime === 'automatic' ? { jsxImportSource: request.jsx.importSource } : {}),
+        charset: 'utf8',
+        logLevel: 'silent',
+        plugins: [
+          {
+            name: 'bfwc-vfs',
+            setup(build) {
+              build.onResolve({ filter: /.*/ }, (args) => {
+                const importer = args.importer || undefined;
+                const resolved = host.resolve(args.path, importer, KINDS[args.kind] ?? 'import');
+                if (!resolved) return { errors: [{ text: `Cannot resolve "${args.path}"${importer ? ` from ${importer}` : ''}` }] };
+                if ('external' in resolved) return { path: resolved.external, external: true };
+                return { path: resolved.path, namespace: NAMESPACE, ...(resolved.query ? { suffix: `?${resolved.query}` } : {}) };
+              });
+              build.onLoad({ filter: /.*/, namespace: NAMESPACE }, async (args) => {
+                const query = args.suffix?.startsWith('?') ? args.suffix.slice(1) : undefined;
+                return host.load(args.path, query);
+              });
+            },
+          },
+        ],
+      });
+
+      const files = (result.outputFiles ?? []).map((file) => ({ path: relativeOutput(file.path), contents: file.contents }));
+      const entries: BundleOutput['entries'] = {};
+      for (const [output, meta] of Object.entries(result.metafile?.outputs ?? {})) {
+        if (!meta.entryPoint) continue;
+        const entry = meta.entryPoint.replace(`${NAMESPACE}:`, '').replace(/\?.*$/, '');
+        const slot = (entries[entry] ??= {});
+        if (output.endsWith('.css')) slot.css = relativeOutput(output);
+        else {
+          slot.js = relativeOutput(output);
+          if (meta.cssBundle) slot.css = relativeOutput(meta.cssBundle);
+        }
+      }
+      return { files, entries };
+    },
+  };
+}

package/src/check/acquire.ts

@@ -0,0 +1,212 @@
+import type * as TS from 'typescript';
+import { isBareSpecifier, splitPackageSpecifier } from '../resolve.js';
+import { dirname, join } from '../paths.js';
+import { parseLooseJson } from '../projectConfig.js';
+import type { VirtualFileSystem } from '../vfs.js';
+import { SHIMMED_TYPE_REFERENCES } from './shims.js';
+import {
+  CONFIG_MODULES_DIR,
+  dtsCandidates,
+  packageRequestUrl,
+  typesPackageName,
+  versioned,
+  type TypeSources,
+  type TypeStore,
+} from './typeStore.js';
+
+/** The part of a fetch `Response` acquisition reads; the real `fetch` satisfies it. */
+export interface FetchResponseLike {
+  ok: boolean;
+  /** The final URL after redirects. Relative references resolve against it. */
+  url: string;
+  headers: { get(name: string): string | null };
+  text(): Promise<string>;
+}
+
+export type FetchLike = (url: string) => Promise<FetchResponseLike>;
+
+export interface AcquireRequest {
+  /** Bare module specifiers imported by project files (`react`, `react/jsx-runtime`). */
+  specifiers: string[];
+  /** `types` entries and `/// <reference types>` names. */
+  typeReferences: string[];
+  /** Lib file names (`lib.es2020.full.d.ts`). */
+  libFiles: string[];
+  dependencies: Readonly<Record<string, string>>;
+}
+
+export interface AcquireOptions {
+  fetch: FetchLike;
+  sources: TypeSources;
+  /** Upper bound on fetched `.d.ts` files — one run-away graph must not stall a check. */
+  maxFiles: number;
+}
+
+const TYPES_HEADER = 'X-TypeScript-Types';
+
+/**
+ * Fetch every declaration file the request can reach into the store: package
+ * entry types (via the CDN's `X-TypeScript-Types` header), then everything those
+ * import or reference, transitively; lib files and their `/// <reference lib>`s.
+ *
+ * Fetches run concurrently. Each URL is fetched once and its references are
+ * scheduled rather than awaited inside the fetch, so reference cycles between
+ * declaration files cannot deadlock.
+ */
+export async function acquireTypes(ts: typeof TS, store: TypeStore, request: AcquireRequest, options: AcquireOptions): Promise<void> {
+  const { sources } = options;
+  const inflight = new Map<string, Promise<unknown>>();
+  const tasks: Promise<unknown>[] = [];
+  const schedule = (task: () => Promise<unknown>) => tasks.push(task().catch(() => undefined));
+  const once = <T>(key: string, task: () => Promise<T>): Promise<T> => {
+    if (!inflight.has(key)) inflight.set(key, task());
+    return inflight.get(key) as Promise<T>;
+  };
+  const get = (url: string) => options.fetch(url).then((res) => (res.ok ? res : undefined), () => undefined);
+
+  function walk(fromUrl: string, text: string): void {
+    const info = ts.preProcessFile(text, true, true);
+    for (const ref of info.referencedFiles) schedule(() => fetchFirst(dtsCandidates(ref.fileName, fromUrl)));
+    for (const ref of info.typeReferenceDirectives) schedule(() => ensureTypeReference(ref.fileName));
+    for (const ref of info.libReferenceDirectives) schedule(() => ensureLib(`lib.${ref.fileName.toLowerCase()}.d.ts`));
+    for (const ref of info.importedFiles) {
+      const spec = ref.fileName;
+      schedule(() => (isBareSpecifier(spec) ? ensurePackage(spec) : fetchFirst(dtsCandidates(spec, fromUrl))));
+    }
+  }
+
+  /** Fetch one declaration file; resolves to its final URL. */
+  function fetchDts(url: string): Promise<string | undefined> {
+    const known = store.redirects.get(url);
+    if (known !== undefined) return Promise.resolve(known || undefined);
+    if (store.files.has(url)) return Promise.resolve(url);
+    return once(`dts:${url}`, async () => {
+      if (store.files.size >= options.maxFiles) return undefined;
+      const res = await get(url);
+      if (!res) {
+        store.redirects.set(url, '');
+        return undefined;
+      }
+      const final = res.url || url;
+      store.redirects.set(url, final);
+      if (!store.files.has(final)) {
+        const text = await res.text();
+        store.files.set(final, text);
+        walk(final, text);
+      }
+      return final;
+    });
+  }
+
+  async function fetchFirst(candidates: string[]): Promise<string | undefined> {
+    for (const url of candidates) {
+      const final = await fetchDts(url);
+      if (final) return final;
+    }
+    return undefined;
+  }
+
+  /** A bare specifier's entry types, located by the CDN's header. */
+  function ensurePackage(specifier: string, dependencies: Readonly<Record<string, string>> = {}): Promise<string | undefined> {
+    const key = packageRequestUrl(sources.typesOrigin, specifier, dependencies);
+    if (store.packages.has(key)) return Promise.resolve(store.packages.get(key) ?? undefined);
+    return once(`pkg:${key}`, async () => {
+      const res = await get(key);
+      const header = res?.headers.get(TYPES_HEADER);
+      const final = header ? await fetchDts(new URL(header, res!.url || key).href) : undefined;
+      store.packages.set(key, final ?? null);
+      return final;
+    });
+  }
+
+  /** `/// <reference types="x" />` and `types: ["x"]`: the package's own types, else DefinitelyTyped. */
+  function ensureTypeReference(name: string, dependencies: Readonly<Record<string, string>> = {}): Promise<unknown> {
+    if (SHIMMED_TYPE_REFERENCES.has(name)) return Promise.resolve();
+    const key = `types:${name}`;
+    if (store.packages.has(key)) return Promise.resolve();
+    return once(key, async () => {
+      // `node` is DefinitelyTyped's, not the npm package called "node".
+      const own = name === 'node' ? undefined : await ensurePackage(name, dependencies);
+      const { name: pkg, subpath } = splitPackageSpecifier(name);
+      const typesPkg = typesPackageName(pkg);
+      const definitelyTyped = own
+        ? undefined
+        : await fetchDts(`${sources.typesOrigin}/${versioned(typesPkg, dependencies)}${subpath || '/index'}.d.ts`);
+      store.packages.set(key, own ?? definitelyTyped ?? null);
+    });
+  }
+
+  function ensureLib(file: string): Promise<unknown> {
+    if (store.libs.has(file)) return Promise.resolve();
+    return once(`lib:${file}`, async () => {
+      const res = await get(`${sources.libBaseUrl}/${file}`);
+      const text = res ? await res.text() : null;
+      store.libs.set(file, text);
+      if (text) {
+        for (const ref of ts.preProcessFile(text, true, false).libReferenceDirectives) {
+          schedule(() => ensureLib(`lib.${ref.fileName.toLowerCase()}.d.ts`));
+        }
+      }
+    });
+  }
+
+  for (const spec of request.specifiers) schedule(() => ensurePackage(spec, request.dependencies));
+  for (const name of request.typeReferences) schedule(() => ensureTypeReference(name, request.dependencies));
+  for (const file of request.libFiles) schedule(() => ensureLib(file));
+  while (tasks.length) await Promise.all(tasks.splice(0));
+}
+
+/**
+ * Fetch tsconfig files the project `extends` from packages (`@vue/tsconfig`,
+ * `@tsconfig/svelte`) into the store's virtual node_modules, following their own
+ * `extends` chains, so the config parser sees what a local install would hold.
+ */
+export async function acquireExtendedConfigs(
+  fs: VirtualFileSystem,
+  store: TypeStore,
+  dependencies: Readonly<Record<string, string>>,
+  options: Pick<AcquireOptions, 'fetch' | 'sources'>,
+): Promise<void> {
+  const tasks: Promise<void>[] = [];
+
+  function extendsOf(text: string): string[] {
+    try {
+      const value = (parseLooseJson(text) as { extends?: unknown }).extends;
+      return (Array.isArray(value) ? value : [value]).filter((v): v is string => typeof v === 'string');
+    } catch {
+      return [];
+    }
+  }
+
+  function follow(fromPath: string, text: string): void {
+    for (const spec of extendsOf(text)) {
+      let path: string;
+      if (isBareSpecifier(spec)) {
+        const { name, subpath } = splitPackageSpecifier(spec);
+        path = `${CONFIG_MODULES_DIR}/${name}${subpath ? (subpath.endsWith('.json') ? subpath : `${subpath}.json`) : '/tsconfig.json'}`;
+      } else if (fromPath.startsWith(`${CONFIG_MODULES_DIR}/`)) {
+        path = join(dirname(fromPath), spec.endsWith('.json') ? spec : `${spec}.json`);
+      } else {
+        continue; // a project-local config: already in the VFS
+      }
+      if (store.configs.has(path)) continue;
+      store.configs.set(path, null);
+      tasks.push(fetchConfig(path));
+    }
+  }
+
+  async function fetchConfig(path: string): Promise<void> {
+    const rest = path.slice(CONFIG_MODULES_DIR.length + 1);
+    const { name, subpath } = splitPackageSpecifier(rest);
+    const res = await options.fetch(`${options.sources.npmBaseUrl}/${versioned(name, dependencies)}${subpath}`).catch(() => undefined);
+    if (!res?.ok) return;
+    const text = await res.text();
+    store.configs.set(path, text);
+    follow(path, text);
+  }
+
+  for (const path of fs.list()) {
+    if (/^\/tsconfig[^/]*\.json$/.test(path)) follow(path, fs.readText(path) ?? '');
+  }
+  while (tasks.length) await Promise.all(tasks.splice(0));
+}