@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.3

package/src/check/compilerHost.ts

@@ -0,0 +1,138 @@
+import type * as TS from 'typescript';
+import type { VirtualFileSystem } from '../vfs.js';
+import type { PathAlias } from '../projectConfig.js';
+import { dirname, extname, join, normalizePath } from '../paths.js';
+import { isBareSpecifier } from '../resolve.js';
+import { AMBIENT_SHIM_PATH, EMPTY_TYPES_PATH, SHIMMED_TYPE_REFERENCES, SHIM_DIR } from './shims.js';
+import { dtsCandidates, LIB_DIR, packageRequestUrl, TYPES_DIR, type TypeStore } from './typeStore.js';
+
+/**
+ * A synchronous TypeScript CompilerHost over the project's VFS and a filled
+ * {@link TypeStore}. Module resolution is done here rather than by TypeScript's
+ * node resolver: project imports follow the runtime's own rules (resolve.ts
+ * probing, tsconfig aliases), bare imports go to the types the CDN named, and
+ * references inside fetched declaration files resolve as URLs.
+ */
+export interface VirtualHostOptions {
+  fs: VirtualFileSystem;
+  store: TypeStore;
+  typesOrigin: string;
+  dependencies: Readonly<Record<string, string>>;
+  aliases: readonly PathAlias[];
+  /** The ambient shim's text (see shims.ts). */
+  shim: string;
+}
+
+const TS_PROBE = ['.ts', '.tsx', '.d.ts', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'];
+
+function extensionOf(ts: typeof TS, path: string): TS.Extension {
+  if (path.endsWith('.d.ts')) return ts.Extension.Dts;
+  if (path.endsWith('.d.mts')) return ts.Extension.Dmts;
+  if (path.endsWith('.d.cts')) return ts.Extension.Dcts;
+  const map: Record<string, TS.Extension> = {
+    '.ts': ts.Extension.Ts, '.tsx': ts.Extension.Tsx, '.mts': ts.Extension.Mts, '.cts': ts.Extension.Cts,
+    '.js': ts.Extension.Js, '.jsx': ts.Extension.Jsx, '.mjs': ts.Extension.Mjs, '.cjs': ts.Extension.Cjs, '.json': ts.Extension.Json,
+  };
+  return map[extname(path)] ?? ts.Extension.Ts;
+}
+
+/** TypeScript's probing for a project-relative path: extensions, `.js` → `.ts`, `index`. */
+function probeProject(fs: VirtualFileSystem, base: string): string | undefined {
+  const ext = extname(base);
+  if (fs.isFile(base) && TS_PROBE.includes(ext)) return base;
+  for (const candidate of TS_PROBE) if (fs.isFile(base + candidate)) return base + candidate;
+  if (ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs') {
+    const stem = base.slice(0, -ext.length);
+    for (const alt of ['.ts', '.tsx', '.d.ts', '.mts', '.cts']) if (fs.isFile(stem + alt)) return stem + alt;
+  }
+  for (const candidate of TS_PROBE) if (fs.isFile(join(base, `index${candidate}`))) return join(base, `index${candidate}`);
+  return undefined;
+}
+
+export function createVirtualHost(ts: typeof TS, options: VirtualHostOptions): TS.CompilerHost {
+  const { fs, store } = options;
+
+  const readFile = (path: string): string | undefined => {
+    if (path === AMBIENT_SHIM_PATH) return options.shim;
+    if (path === EMPTY_TYPES_PATH) return 'export {};\n';
+    return fs.readText(path) ?? store.read(path);
+  };
+
+  function typesFor(url: string | undefined | null): string | undefined {
+    return url ? store.virtualPath(url) : undefined;
+  }
+
+  function resolveInTypes(specifier: string, containingUrl: string): string | undefined {
+    if (isBareSpecifier(specifier)) return typesFor(store.packages.get(packageRequestUrl(options.typesOrigin, specifier, {})));
+    for (const candidate of dtsCandidates(specifier, containingUrl)) {
+      const final = store.finalUrl(candidate);
+      if (final) return typesFor(final);
+    }
+    return undefined;
+  }
+
+  function resolveInProject(specifier: string, containingFile: string): string | undefined {
+    if (specifier.includes('?')) return undefined; // `?raw`/`?url`: the ambient shim declares them
+    if (!isBareSpecifier(specifier)) {
+      const base = specifier.startsWith('/') ? normalizePath(specifier) : join(dirname(containingFile), specifier);
+      return probeProject(fs, base);
+    }
+    for (const alias of options.aliases) {
+      const matches = alias.wildcard ? specifier.startsWith(alias.prefix) : specifier === alias.prefix;
+      if (!matches) continue;
+      const rest = alias.wildcard ? specifier.slice(alias.prefix.length) : '';
+      for (const target of alias.targets) {
+        const hit = probeProject(fs, normalizePath(target + rest));
+        if (hit) return hit;
+      }
+    }
+    return typesFor(store.packages.get(packageRequestUrl(options.typesOrigin, specifier, options.dependencies)));
+  }
+
+  function resolveModule(specifier: string, containingFile: string): TS.ResolvedModuleFull | undefined {
+    const containingUrl = store.urlOf(containingFile);
+    const resolved = containingUrl ? resolveInTypes(specifier, containingUrl) : resolveInProject(specifier, containingFile);
+    if (!resolved) return undefined;
+    return { resolvedFileName: resolved, extension: extensionOf(ts, resolved), isExternalLibraryImport: resolved.startsWith(`${TYPES_DIR}/`) };
+  }
+
+  /** `/// <reference types>` resolves the same from anywhere: acquisition keyed it by name. */
+  function resolveTypeReference(name: string): string | undefined {
+    if (SHIMMED_TYPE_REFERENCES.has(name)) return EMPTY_TYPES_PATH;
+    return typesFor(store.packages.get(`types:${name}`));
+  }
+
+  return {
+    getSourceFile(fileName, languageVersion) {
+      const shared = !fs.isFile(fileName);
+      const cached = shared ? store.sourceFiles.get(fileName) : undefined;
+      if (cached) return cached;
+      const text = readFile(fileName);
+      if (text === undefined) return undefined;
+      const file = ts.createSourceFile(fileName, text, languageVersion, true);
+      // Lib and package files never change for a URL: parse once per store.
+      if (shared && fileName !== AMBIENT_SHIM_PATH) store.sourceFiles.set(fileName, file);
+      return file;
+    },
+    getDefaultLibFileName: (compilerOptions) => `${LIB_DIR}/${ts.getDefaultLibFileName(compilerOptions)}`,
+    getDefaultLibLocation: () => LIB_DIR,
+    writeFile: () => undefined,
+    getCurrentDirectory: () => '/',
+    getCanonicalFileName: (fileName) => fileName,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => '\n',
+    fileExists: (fileName) => readFile(fileName) !== undefined,
+    readFile,
+    directoryExists: (dir) => fs.isDirectory(dir) || dir.startsWith(TYPES_DIR) || dir === LIB_DIR || dir === SHIM_DIR,
+    getDirectories: () => [],
+    resolveModuleNameLiterals: (literals, containingFile) =>
+      literals.map((literal) => ({ resolvedModule: resolveModule(literal.text, containingFile) })),
+    resolveTypeReferenceDirectiveReferences: (references) =>
+      references.map((reference) => {
+        const resolved = resolveTypeReference(typeof reference === 'string' ? reference : reference.fileName);
+        return {
+          resolvedTypeReferenceDirective: resolved ? { primary: true, resolvedFileName: resolved, isExternalLibraryImport: true } : undefined,
+        };
+      }),
+  };
+}

package/src/check/diagnostics.ts

@@ -0,0 +1,48 @@
+import type * as TS from 'typescript';
+
+export type DiagnosticCategory = 'error' | 'warning' | 'suggestion' | 'message';
+
+/**
+ * One problem, in a shape an editor (or an agent) can act on without the
+ * TypeScript API: positions are 1-based like an editor's gutter, and `file` is
+ * the project-relative path (`src/App.tsx`), the same key `FlatFiles` uses.
+ */
+export interface CheckDiagnostic {
+  /** Project-relative path; absent for global problems (compiler options, a missing lib). */
+  file?: string;
+  line: number;
+  column: number;
+  message: string;
+  /** TypeScript's code (2322 for TS2322). */
+  code: number;
+  category: DiagnosticCategory;
+}
+
+const CATEGORIES: Record<number, DiagnosticCategory> = { 0: 'warning', 1: 'error', 2: 'suggestion', 3: 'message' };
+
+export function toCheckDiagnostic(ts: typeof TS, diagnostic: TS.Diagnostic): CheckDiagnostic {
+  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+  const category = CATEGORIES[diagnostic.category] ?? 'error';
+  if (!diagnostic.file || diagnostic.start === undefined) return { line: 1, column: 1, message, code: diagnostic.code, category };
+  const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+  return { file: diagnostic.file.fileName.replace(/^\//, ''), line: line + 1, column: character + 1, message, code: diagnostic.code, category };
+}
+
+/** `src/App.tsx(3,7): error TS2322: Type 'number' is not assignable to type 'string'.` — tsc's own format. */
+export function formatDiagnostic(diagnostic: CheckDiagnostic): string {
+  const where = diagnostic.file ? `${diagnostic.file}(${diagnostic.line},${diagnostic.column}): ` : '';
+  return `${where}${diagnostic.category} TS${diagnostic.code}: ${diagnostic.message}`;
+}
+
+/** Stable order (file, then position) and no duplicates — a file in two tsconfig projects reports once. */
+export function sortDiagnostics(diagnostics: CheckDiagnostic[]): CheckDiagnostic[] {
+  const seen = new Set<string>();
+  return diagnostics
+    .filter((d) => {
+      const key = `${d.file ?? ''}:${d.line}:${d.column}:${d.code}:${d.message}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => (a.file ?? '').localeCompare(b.file ?? '') || a.line - b.line || a.column - b.column);
+}

package/src/check/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@seanhogg/builderforce-webcontainers-core/check` — type-checking a project in
+ * memory. A separate entry point because it is typed against the `typescript`
+ * package (an optional peer dependency), which the rest of the core never needs.
+ */
+export { typecheckProject } from './typecheck.js';
+export type { TypecheckOptions, TypecheckResult } from './typecheck.js';
+export { toCheckDiagnostic, formatDiagnostic, sortDiagnostics } from './diagnostics.js';
+export type { CheckDiagnostic, DiagnosticCategory } from './diagnostics.js';
+export { acquireTypes, acquireExtendedConfigs } from './acquire.js';
+export type { FetchLike, FetchResponseLike, AcquireRequest, AcquireOptions } from './acquire.js';
+export { resolveCheckProjects, defaultCompilerOptions, createParseConfigHost } from './projects.js';
+export type { CheckProject } from './projects.js';
+export { createVirtualHost } from './compilerHost.js';
+export type { VirtualHostOptions } from './compilerHost.js';
+export { ambientShim, declaresModule, AMBIENT_SHIM_PATH, SHIMMED_TYPE_REFERENCES } from './shims.js';
+export {
+  TypeStore,
+  libBaseUrlFor,
+  typesPackageName,
+  dtsCandidates,
+  packageRequestUrl,
+  DEFAULT_TYPES_ORIGIN,
+  DEFAULT_NPM_BASE_URL,
+  TYPES_DIR,
+  LIB_DIR,
+} from './typeStore.js';
+export type { TypeSources } from './typeStore.js';

package/src/check/projects.ts

@@ -0,0 +1,149 @@
+import type * as TS from 'typescript';
+import type { VirtualFileSystem } from '../vfs.js';
+import { dirname, extname, join } from '../paths.js';
+import type { TypeStore } from './typeStore.js';
+
+/**
+ * Which programs to build, with which options, over which files — what `tsc -b`
+ * would derive from the project's tsconfig files.
+ *
+ * Vite's templates keep a root `tsconfig.json` holding only `references` (to
+ * `tsconfig.app.json` and `tsconfig.node.json`); each reference is its own
+ * program. With no tsconfig at all, the checker synthesises Vite's defaults for
+ * a React + TS app, so a generated project with no config still gets checked.
+ */
+export interface CheckProject {
+  /** The tsconfig this came from; undefined when synthesised. */
+  configPath?: string;
+  options: TS.CompilerOptions;
+  rootNames: string[];
+  /** Problems parsing the config itself. */
+  errors: readonly TS.Diagnostic[];
+}
+
+/** Tool configs (`vite.config.ts`…) describe the build, which runs elsewhere: not checked. */
+const TOOL_CONFIG = /(^|\/)(vite|vitest|svelte|tailwind|postcss|eslint|prettier|playwright)\.config\.[cm]?[jt]s$/;
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'];
+/** "No inputs were found in config file" — a reference covering only tool configs. */
+const NO_INPUTS = 18003;
+
+/** Vite's React + TS template, made strict-ish; what a project with no tsconfig gets. */
+export function defaultCompilerOptions(ts: typeof TS, jsxImportSource?: string): TS.CompilerOptions {
+  return {
+    target: ts.ScriptTarget.ES2020,
+    lib: ['lib.es2020.d.ts', 'lib.dom.d.ts', 'lib.dom.iterable.d.ts'],
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    jsx: ts.JsxEmit.ReactJSX,
+    ...(jsxImportSource ? { jsxImportSource } : {}),
+    strict: true,
+    noFallthroughCasesInSwitch: true,
+    isolatedModules: true,
+    resolveJsonModule: true,
+    allowImportingTsExtensions: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+    noEmit: true,
+  };
+}
+
+/** Options no in-browser check wants, whatever the config says: nothing is emitted. */
+function forCheck(options: TS.CompilerOptions): TS.CompilerOptions {
+  return {
+    ...options,
+    noEmit: true,
+    skipLibCheck: true,
+    composite: false,
+    incremental: false,
+    declaration: false,
+    declarationMap: false,
+    emitDeclarationOnly: false,
+    tsBuildInfoFile: undefined,
+  };
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let source = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]!;
+    if (ch === '*' && pattern[i + 1] === '*' && pattern[i + 2] === '/') {
+      source += '(?:[^/]+/)*';
+      i += 2;
+    } else if (ch === '*') source += '[^/]*';
+    else if (ch === '?') source += '[^/]';
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/** A tsconfig `include`/`exclude` spec as a matcher; a bare directory means everything under it. */
+function specMatcher(root: string, spec: string): RegExp {
+  let abs = join(root, spec);
+  const last = abs.slice(abs.lastIndexOf('/') + 1);
+  if (!/[*?]/.test(last) && !extname(last)) abs = `${abs === '/' ? '' : abs}/**/*`;
+  return globToRegExp(abs);
+}
+
+/** The ParseConfigHost the config parser reads through: the VFS plus fetched `extends` packages. */
+export function createParseConfigHost(fs: VirtualFileSystem, store: TypeStore): TS.ParseConfigHost {
+  return {
+    useCaseSensitiveFileNames: true,
+    fileExists: (path) => fs.isFile(path) || store.read(path) !== undefined,
+    readFile: (path) => fs.readText(path) ?? store.read(path),
+    readDirectory(rootDir, extensions, excludes, includes) {
+      const include = (includes ?? ['**/*']).map((spec) => specMatcher(rootDir, spec));
+      const exclude = (excludes ?? []).map((spec) => specMatcher(rootDir, spec));
+      return fs.list().filter((path) =>
+        extensions.some((ext) => path.endsWith(ext)) &&
+        !path.includes('/node_modules/') &&
+        include.some((re) => re.test(path)) &&
+        !exclude.some((re) => re.test(path)),
+      );
+    },
+  };
+}
+
+function parseConfig(ts: typeof TS, host: TS.ParseConfigHost, configPath: string): TS.ParsedCommandLine | { errors: TS.Diagnostic[] } {
+  const text = host.readFile(configPath) ?? '';
+  const json = ts.parseConfigFileTextToJson(configPath, text);
+  if (json.error) return { errors: [json.error] };
+  return ts.parseJsonConfigFileContent(json.config, host, dirname(configPath), undefined, configPath);
+}
+
+function referencedConfigs(ts: typeof TS, host: TS.ParseConfigHost, configPath: string): string[] {
+  const json = ts.parseConfigFileTextToJson(configPath, host.readFile(configPath) ?? '').config as { references?: Array<{ path?: unknown }>; files?: unknown[]; include?: unknown[] } | undefined;
+  const references = json?.references ?? [];
+  // A "solution" config — references and nothing of its own — is checked through its references.
+  const ownsFiles = (json?.files?.length ?? 0) > 0 || json?.include !== undefined;
+  if (!references.length || ownsFiles) return [];
+  return references
+    .map((ref) => (typeof ref.path === 'string' ? join(dirname(configPath), ref.path) : undefined))
+    .filter((path): path is string => !!path)
+    .map((path) => (path.endsWith('.json') ? path : join(path, 'tsconfig.json')))
+    .filter((path) => host.fileExists(path));
+}
+
+export function resolveCheckProjects(ts: typeof TS, fs: VirtualFileSystem, store: TypeStore, jsxImportSource?: string): CheckProject[] {
+  const host = createParseConfigHost(fs, store);
+  const root = ['/tsconfig.json', '/jsconfig.json'].find((path) => fs.isFile(path));
+
+  if (!root) {
+    const rootNames = fs.list().filter((path) => SOURCE_EXTENSIONS.some((ext) => path.endsWith(ext)) && !path.includes('/node_modules/') && !TOOL_CONFIG.test(path));
+    return rootNames.length ? [{ options: defaultCompilerOptions(ts, jsxImportSource), rootNames, errors: [] }] : [];
+  }
+
+  const configs = referencedConfigs(ts, host, root);
+  const projects: CheckProject[] = [];
+  for (const configPath of configs.length ? configs : [root]) {
+    const parsed = parseConfig(ts, host, configPath);
+    const errors = parsed.errors.filter((d) => d.code !== NO_INPUTS);
+    if (!('options' in parsed)) {
+      projects.push({ configPath, options: {}, rootNames: [], errors });
+      continue;
+    }
+    const rootNames = parsed.fileNames.filter((path) => !TOOL_CONFIG.test(path));
+    if (!rootNames.length && !errors.length) continue;
+    projects.push({ configPath, options: forCheck(parsed.options), rootNames, errors });
+  }
+  return projects;
+}

package/src/check/shims.ts

@@ -0,0 +1,88 @@
+/**
+ * Ambient declarations the checker adds, standing in for what a local install
+ * would provide:
+ *   • Vite's `vite/client` (`import.meta.env`, CSS/asset/`?raw` imports) and CRA's
+ *     `react-scripts` types. Shimmed rather than fetched: they are what every
+ *     generated app references, and a small local copy never fails to load;
+ *   • `.vue` / `.svelte` imports. Component internals are not type-checked yet;
+ *     importing one must not be an error;
+ *   • packages whose types could not be found, declared as `any` — a CDN miss is
+ *     not the user's type error.
+ *
+ * A pattern the project (or a fetched package) already declares is skipped: two
+ * declarations of `*.vue` with a default export each would be an error of ours.
+ */
+
+export const SHIM_DIR = '/__bfwc_shims__';
+export const AMBIENT_SHIM_PATH = `${SHIM_DIR}/ambient.d.ts`;
+/** What a shimmed type reference (`/// <reference types="vite/client" />`) resolves to. */
+export const EMPTY_TYPES_PATH = `${SHIM_DIR}/empty.d.ts`;
+export const SHIMMED_TYPE_REFERENCES: ReadonlySet<string> = new Set(['vite/client', 'react-scripts']);
+
+const STRING_DEFAULT = '{ const src: string; export default src; }';
+const ANY_DEFAULT = '{ const value: any; export default value; }';
+
+const MODULE_SHIMS: ReadonlyArray<[pattern: string, body: string]> = [
+  ['*.module.css', '{ const classes: { readonly [key: string]: string }; export default classes; }'],
+  ['*.module.scss', '{ const classes: { readonly [key: string]: string }; export default classes; }'],
+  ['*.css', '{}'],
+  ['*.scss', '{}'],
+  ['*.sass', '{}'],
+  ['*.less', '{}'],
+  ...['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'ico', 'bmp', 'woff', 'woff2', 'ttf', 'otf', 'eot', 'mp4', 'webm', 'mp3', 'wav', 'ogg', 'pdf', 'txt', 'md', 'wasm'].map(
+    (ext): [string, string] => [`*.${ext}`, STRING_DEFAULT],
+  ),
+  ['*?raw', STRING_DEFAULT],
+  ['*?url', STRING_DEFAULT],
+  ['*?inline', STRING_DEFAULT],
+  ['*.vue', ANY_DEFAULT],
+  ['*.svelte', ANY_DEFAULT],
+];
+
+const IMPORT_META = `interface ImportMetaEnv {
+  readonly [key: string]: any;
+  readonly MODE: string;
+  readonly BASE_URL: string;
+  readonly PROD: boolean;
+  readonly DEV: boolean;
+  readonly SSR: boolean;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+  readonly hot?: any;
+  readonly glob: any;
+}`;
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** True when any of `texts` declares `declare module '<pattern>'`. */
+export function declaresModule(texts: Iterable<string>, pattern: string): boolean {
+  const re = new RegExp(`declare\\s+module\\s+['"]${escapeRegExp(pattern)}['"]`);
+  for (const text of texts) if (re.test(text)) return true;
+  return false;
+}
+
+export interface AmbientShimOptions {
+  /** Declarations already loaded: the project's own `.d.ts` files and fetched package types. */
+  existing: string[];
+  /** Packages with no types found — declared as `any`. */
+  untyped: string[];
+}
+
+export function ambientShim(options: AmbientShimOptions): string {
+  const lines = [IMPORT_META];
+  // CRA reads `process.env.REACT_APP_*`; @types/node, when loaded, declares it properly.
+  if (!options.existing.some((text) => /declare\s+var\s+process\b/.test(text))) {
+    lines.push('declare var process: { env: { readonly [key: string]: string | undefined; readonly NODE_ENV: string } };');
+  }
+  for (const [pattern, body] of MODULE_SHIMS) {
+    if (!declaresModule(options.existing, pattern)) lines.push(`declare module ${JSON.stringify(pattern)} ${body}`);
+  }
+  for (const name of options.untyped) {
+    lines.push(`declare module ${JSON.stringify(name)};`);
+    lines.push(`declare module ${JSON.stringify(`${name}/*`)};`);
+  }
+  return lines.join('\n') + '\n';
+}

package/src/check/typeStore.ts

@@ -0,0 +1,103 @@
+import type * as TS from 'typescript';
+import { isRegistryRange } from '../packageCdn.js';
+import { splitPackageSpecifier } from '../resolve.js';
+
+/**
+ * Where the checker's non-project files live, and the cache that holds them.
+ *
+ * A TypeScript program is synchronous, but type definitions come from the
+ * network. So checking is two phases: acquisition fetches everything the project
+ * can reach into a {@link TypeStore}; the program then reads only the store. The
+ * store outlives one check (a worker keeps it), so a second check of the same
+ * project makes no requests and reuses parsed lib files.
+ *
+ * Fetched files are addressed by URL and exposed to TypeScript under virtual
+ * paths; libs and `extends`-ed tsconfig packages likewise.
+ */
+
+export const TYPES_DIR = '/__bfwc_types__';
+export const LIB_DIR = '/__bfwc_lib__';
+/** tsconfig `extends: "@vue/tsconfig/..."` resolves through node_modules, so fetched configs live there. */
+export const CONFIG_MODULES_DIR = '/node_modules';
+
+export interface TypeSources {
+  /** An esm.sh-compatible CDN: answers `X-TypeScript-Types` for a package URL. */
+  typesOrigin: string;
+  /** Directory holding `lib.*.d.ts` for the TypeScript version in use. */
+  libBaseUrl: string;
+  /** Raw npm files (for tsconfig `extends` packages), jsDelivr's `/npm` layout. */
+  npmBaseUrl: string;
+}
+
+export const DEFAULT_TYPES_ORIGIN = 'https://esm.sh';
+export const DEFAULT_NPM_BASE_URL = 'https://cdn.jsdelivr.net/npm';
+
+export function libBaseUrlFor(typescriptVersion: string): string {
+  return `${DEFAULT_NPM_BASE_URL}/typescript@${typescriptVersion}/lib`;
+}
+
+/** `@scope/name` → `@types/scope__name`, DefinitelyTyped's naming. */
+export function typesPackageName(name: string): string {
+  return `@types/${name.startsWith('@') ? name.slice(1).replace('/', '__') : name}`;
+}
+
+/** `name@range` when the project declares a registry range for it, else `name`. */
+export function versioned(name: string, dependencies: Readonly<Record<string, string>>): string {
+  const range = dependencies[name];
+  return range && isRegistryRange(range) ? `${name}@${range}` : name;
+}
+
+/** The CDN module URL whose `X-TypeScript-Types` names a specifier's types. */
+export function packageRequestUrl(origin: string, specifier: string, dependencies: Readonly<Record<string, string>>): string {
+  const { name, subpath } = splitPackageSpecifier(specifier);
+  return `${origin}/${versioned(name, dependencies)}${subpath}`;
+}
+
+/** URLs to try, in order, for a relative or absolute reference inside a fetched `.d.ts`. */
+export function dtsCandidates(specifier: string, fromUrl: string): string[] {
+  const url = new URL(specifier, fromUrl).href.replace(/[?#].*$/, '');
+  if (/\.d\.[mc]?ts$/.test(url)) return [url];
+  if (/\.[mc]?js$/.test(url)) return [url.replace(/\.([mc]?)js$/, '.d.$1ts')];
+  if (/\.[mc]?ts$/.test(url)) return [url];
+  return [`${url}.d.ts`, `${url}/index.d.ts`];
+}
+
+export class TypeStore {
+  /** Final (post-redirect) URL → text. */
+  readonly files = new Map<string, string>();
+  /** Requested URL → final URL; `''` records a failure so it is not retried. */
+  readonly redirects = new Map<string, string>();
+  /** Package request URL (or `types:<name>`) → final types URL, or null when it has none. */
+  readonly packages = new Map<string, string | null>();
+  /** `lib.dom.d.ts` → text, or null when missing. */
+  readonly libs = new Map<string, string | null>();
+  /** `/node_modules/@vue/tsconfig/tsconfig.json` → text, or null when missing. */
+  readonly configs = new Map<string, string | null>();
+  /** Parsed lib and package files, reused by every program built over this store. */
+  readonly sourceFiles = new Map<string, TS.SourceFile>();
+
+  /** The final URL for a requested one, when it was fetched. */
+  finalUrl(url: string): string | undefined {
+    const final = this.redirects.get(url) ?? (this.files.has(url) ? url : undefined);
+    return final || undefined;
+  }
+
+  virtualPath(url: string): string {
+    return `${TYPES_DIR}/${url.replace(/^[a-z]+:\/\//i, '')}`;
+  }
+
+  urlOf(virtualPath: string): string | undefined {
+    if (!virtualPath.startsWith(`${TYPES_DIR}/`)) return undefined;
+    const rest = virtualPath.slice(TYPES_DIR.length + 1);
+    for (const scheme of ['https://', 'http://']) if (this.files.has(scheme + rest)) return scheme + rest;
+    return undefined;
+  }
+
+  /** Text for any virtual non-project path, or undefined. */
+  read(path: string): string | undefined {
+    if (path.startsWith(`${LIB_DIR}/`)) return this.libs.get(path.slice(LIB_DIR.length + 1)) ?? undefined;
+    if (path.startsWith(`${CONFIG_MODULES_DIR}/`)) return this.configs.get(path) ?? undefined;
+    const url = this.urlOf(path);
+    return url ? this.files.get(url) : undefined;
+  }
+}