@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.4

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;
+  }
+}

package/src/check/typecheck.ts

@@ -0,0 +1,134 @@
+import type * as TS from 'typescript';
+import { VirtualFileSystem, type FileSystemTree, type FlatFiles } from '../vfs.js';
+import { readProjectConfig } from '../projectConfig.js';
+import { isBareSpecifier, resolveAlias, splitPackageSpecifier } from '../resolve.js';
+import { acquireExtendedConfigs, acquireTypes, type FetchLike } from './acquire.js';
+import { createVirtualHost } from './compilerHost.js';
+import { sortDiagnostics, toCheckDiagnostic, type CheckDiagnostic } from './diagnostics.js';
+import { resolveCheckProjects, type CheckProject } from './projects.js';
+import { AMBIENT_SHIM_PATH, ambientShim } from './shims.js';
+import {
+  DEFAULT_NPM_BASE_URL,
+  DEFAULT_TYPES_ORIGIN,
+  libBaseUrlFor,
+  packageRequestUrl,
+  TypeStore,
+  type TypeSources,
+} from './typeStore.js';
+
+/**
+ * `tsc --noEmit` over a project held in memory. Runtime-agnostic: the caller
+ * passes the TypeScript module (the npm package in Node, the CDN build in a
+ * worker) and a `fetch` for type definitions, so the same code is tested in Node
+ * and run in the browser.
+ */
+export interface TypecheckOptions {
+  fetch: FetchLike;
+  /** Where types, libs and tsconfig packages come from. Libs default to jsDelivr at `ts.version`. */
+  sources?: Partial<TypeSources>;
+  /** Reuse fetched and parsed declarations across checks (a long-lived worker keeps one). */
+  store?: TypeStore;
+  /** Cap on fetched declaration files. Default 2000. */
+  maxTypeFiles?: number;
+}
+
+export interface TypecheckResult {
+  diagnostics: CheckDiagnostic[];
+  /** Imported packages with no types on the CDN — checked as `any` rather than reported. */
+  untypedPackages: string[];
+  /** Project files that were checked, project-relative. */
+  files: string[];
+}
+
+interface Reach {
+  specifiers: Set<string>;
+  typeReferences: Set<string>;
+  libFiles: Set<string>;
+}
+
+function toFileSystem(files: VirtualFileSystem | FlatFiles | FileSystemTree): VirtualFileSystem {
+  if (files instanceof VirtualFileSystem) return files;
+  const fs = new VirtualFileSystem();
+  fs.mount(files);
+  return fs;
+}
+
+/** Everything a set of programs can reach outside the project: packages, type references, libs. */
+function collectReach(ts: typeof TS, fs: VirtualFileSystem, projects: CheckProject[], isAliased: (spec: string) => boolean): Reach {
+  const reach: Reach = { specifiers: new Set(), typeReferences: new Set(), libFiles: new Set() };
+  for (const project of projects) {
+    const { options } = project;
+    for (const path of project.rootNames) {
+      const info = ts.preProcessFile(fs.readText(path) ?? '', true, true);
+      for (const ref of info.importedFiles) {
+        if (isBareSpecifier(ref.fileName) && !ref.fileName.includes('?') && !isAliased(ref.fileName)) reach.specifiers.add(ref.fileName);
+      }
+      for (const ref of info.typeReferenceDirectives) reach.typeReferences.add(ref.fileName);
+      for (const ref of info.libReferenceDirectives) reach.libFiles.add(`lib.${ref.fileName.toLowerCase()}.d.ts`);
+    }
+    for (const name of options.types ?? []) reach.typeReferences.add(name);
+    if (options.jsx === ts.JsxEmit.ReactJSX || options.jsx === ts.JsxEmit.ReactJSXDev) {
+      const runtime = options.jsx === ts.JsxEmit.ReactJSXDev ? 'jsx-dev-runtime' : 'jsx-runtime';
+      reach.specifiers.add(`${options.jsxImportSource ?? 'react'}/${runtime}`);
+    }
+    if (!options.noLib) for (const lib of options.lib ?? [ts.getDefaultLibFileName(options)]) reach.libFiles.add(lib);
+  }
+  return reach;
+}
+
+export async function typecheckProject(
+  ts: typeof TS,
+  files: VirtualFileSystem | FlatFiles | FileSystemTree,
+  options: TypecheckOptions,
+): Promise<TypecheckResult> {
+  const fs = toFileSystem(files);
+  const store = options.store ?? new TypeStore();
+  const sources: TypeSources = {
+    typesOrigin: DEFAULT_TYPES_ORIGIN,
+    npmBaseUrl: DEFAULT_NPM_BASE_URL,
+    libBaseUrl: libBaseUrlFor(ts.version),
+    ...options.sources,
+  };
+  const config = readProjectConfig(fs);
+  const { dependencies } = config;
+
+  await acquireExtendedConfigs(fs, store, dependencies, { fetch: options.fetch, sources });
+  const projects = resolveCheckProjects(ts, fs, store, config.jsx.importSource === 'react' ? undefined : config.jsx.importSource);
+  const reach = collectReach(ts, fs, projects, (spec) => resolveAlias(fs, config.aliases, spec) !== undefined);
+  await acquireTypes(
+    ts,
+    store,
+    { specifiers: [...reach.specifiers], typeReferences: [...reach.typeReferences], libFiles: [...reach.libFiles], dependencies },
+    { fetch: options.fetch, sources, maxFiles: options.maxTypeFiles ?? 2000 },
+  );
+
+  const untypedPackages = [
+    ...new Set(
+      [...reach.specifiers]
+        .filter((spec) => !store.packages.get(packageRequestUrl(sources.typesOrigin, spec, dependencies)))
+        .map((spec) => splitPackageSpecifier(spec).name),
+    ),
+  ].sort();
+  const projectDeclarations = fs.list().filter((path) => path.endsWith('.d.ts')).map((path) => fs.readText(path) ?? '');
+  const shim = ambientShim({ existing: [...projectDeclarations, ...store.files.values()], untyped: untypedPackages });
+
+  const diagnostics: CheckDiagnostic[] = [];
+  const checked = new Set<string>();
+  for (const project of projects) {
+    for (const error of project.errors) diagnostics.push(toCheckDiagnostic(ts, error));
+    if (!project.rootNames.length) continue;
+    const host = createVirtualHost(ts, { fs, store, typesOrigin: sources.typesOrigin, dependencies, aliases: config.aliases, shim });
+    const program = ts.createProgram({ rootNames: [...project.rootNames, AMBIENT_SHIM_PATH], options: project.options, host });
+    const found = [...program.getOptionsDiagnostics(), ...program.getGlobalDiagnostics()];
+    for (const file of program.getSourceFiles()) {
+      if (!fs.isFile(file.fileName)) continue; // libs, package types, shims
+      checked.add(file.fileName.slice(1));
+      found.push(...program.getSyntacticDiagnostics(file), ...program.getSemanticDiagnostics(file));
+    }
+    for (const diagnostic of found) {
+      if (diagnostic.file && !fs.isFile(diagnostic.file.fileName)) continue;
+      diagnostics.push(toCheckDiagnostic(ts, diagnostic));
+    }
+  }
+  return { diagnostics: sortDiagnostics(diagnostics), untypedPackages, files: [...checked].sort() };
+}

package/src/compileComponent.ts

@@ -0,0 +1,21 @@
+import type { CompileContext } from './compileScript.js';
+import { compileModule } from './compileScript.js';
+import { componentExtension } from './components.js';
+import { extname } from './paths.js';
+import { injectStyleStatement, rewriteCssUrls } from './styleModules.js';
+
+/**
+ * A `.vue` / `.svelte` file → one ES module for the dev server: the compiled
+ * component, its imports mapped like any script's, and its scoped CSS injected
+ * as a <style> tag keyed by the component's path (an edit replaces it in place).
+ */
+export async function compileComponent(ctx: CompileContext, path: string): Promise<string> {
+  const extension = componentExtension(extname(path));
+  if (!extension) throw new Error(`Not a component: ${path}`);
+  const compiler = await ctx.components(extension, ctx.config.dependencies);
+  const compiled = await compiler.compile(ctx.fs.readText(path) ?? '', { path, dev: true });
+  const js = await compileModule(ctx, path, compiled.code, compiled.loader);
+  if (!compiled.css) return js;
+  const css = rewriteCssUrls(ctx.fs, path, compiled.css, ctx.base);
+  return `${js}\n${injectStyleStatement(path, JSON.stringify(css))}\n`;
+}

package/src/compileScript.ts

@@ -1,7 +1,9 @@
 import type { VirtualFileSystem } from './vfs.js';
-import type { ProjectConfig } from './projectConfig.js';
+import type { BuildMode, ProjectConfig } from './projectConfig.js';
 import type { PackageCdn } from './packageCdn.js';
-import type { Transformer } from './transformer.js';
+import type { Loader, Transformer } from './transformer.js';
+import type { ComponentCompilers } from './components.js';
+import { componentExtension } from './components.js';
 import { loaderFor } from './transformer.js';
 import { dirname, extname } from './paths.js';
 import { isBareSpecifier, resolveAlias, resolveLocal, splitPackageSpecifier } from './resolve.js';
@@ -14,11 +16,19 @@ export interface CompileContext {
   transformer: Transformer;
   /** Preview base URL, ending in `/`. */
   base: string;
+  /** `.vue` / `.svelte` compilers. */
+  components: ComponentCompilers;
 }
 
 /** Vite-style import queries this runtime honours. */
 export type ImportQuery = 'import' | 'raw' | 'url';
 
+/** A file served as a script module: TS/JS, or a component compiled to one. */
+export function isScriptPath(path: string): boolean {
+  const ext = extname(path);
+  return loaderFor(ext) !== undefined || componentExtension(ext) !== undefined;
+}
+
 /**
  * The URL a resolved VFS file is imported by. Scripts are served as-is; CSS and
  * JSON need the `?import` JS wrapper; anything else imported from JS (images,
@@ -28,12 +38,13 @@ export function moduleUrl(base: string, path: string, query?: ImportQuery): stri
   const url = base + path.slice(1);
   if (query === 'raw' || query === 'url') return `${url}?${query}`;
   const ext = extname(path);
-  if (loaderFor(ext)) return url;
+  if (isScriptPath(path)) return url;
   if (ext === '.css' || ext === '.json') return `${url}?import`;
   return `${url}?url`;
 }
 
-function splitQuery(specifier: string): { path: string; query?: ImportQuery } {
+/** Split `./notes.md?raw` into the path and the query this runtime honours (if any). */
+export function splitQuery(specifier: string): { path: string; query?: ImportQuery } {
   const at = specifier.indexOf('?');
   if (at < 0) return { path: specifier };
   const query = specifier.slice(at + 1);
@@ -59,23 +70,34 @@ export function mapSpecifier(ctx: CompileContext, fromDir: string, specifier: st
   return resolved ? moduleUrl(ctx.base, resolved, query) : undefined;
 }
 
-/** Compile-time constants: Vite's `import.meta.env` and CRA's `process.env.REACT_APP_*`. */
-export function buildDefine(config: ProjectConfig, base: string): Record<string, string> {
-  const env: Record<string, unknown> = { MODE: 'development', DEV: true, PROD: false, SSR: false, BASE_URL: base };
-  const define: Record<string, string> = { 'process.env.NODE_ENV': '"development"' };
+/**
+ * Compile-time constants: Vite's `import.meta.env`, CRA's `process.env.REACT_APP_*`
+ * and `PUBLIC_URL`. `base` is the URL the app is served under.
+ */
+export function buildDefine(config: ProjectConfig, base: string, mode: BuildMode = 'development'): Record<string, string> {
+  const production = mode === 'production';
+  const env: Record<string, unknown> = { MODE: mode, DEV: !production, PROD: production, SSR: false, BASE_URL: base };
+  const define: Record<string, string> = {
+    'process.env.NODE_ENV': JSON.stringify(mode),
+    // CRA's convention: the base without its trailing slash ('' at the root).
+    'process.env.PUBLIC_URL': JSON.stringify(base.replace(/\/$/, '')),
+  };
   for (const [key, value] of Object.entries(config.env)) {
     if (key.startsWith('VITE_')) env[key] = value;
     if (key.startsWith('VITE_') || key.startsWith('REACT_APP_')) define[`process.env.${key}`] = JSON.stringify(value);
   }
+  // Each key on its own, so `import.meta.env.VITE_X` becomes a literal in place; the
+  // whole object only where code reads `import.meta.env` itself. (Defining just the
+  // object makes a bundler hoist it into a shared variable.)
+  for (const [key, value] of Object.entries(env)) {
+    if (/^[A-Za-z_$][\w$]*$/.test(key)) define[`import.meta.env.${key}`] = JSON.stringify(value);
+  }
   define['import.meta.env'] = JSON.stringify(env);
   return define;
 }
 
-/** TS/JSX → an ES module whose imports point at preview and CDN URLs. */
-export async function compileScript(ctx: CompileContext, path: string): Promise<string> {
-  const loader = loaderFor(extname(path));
-  if (!loader) throw new Error(`Not a script: ${path}`);
-  const source = ctx.fs.readText(path) ?? '';
+/** Compile module source (TS/JSX or plain JS) and point its imports at preview and CDN URLs. */
+export async function compileModule(ctx: CompileContext, path: string, source: string, loader: Loader): Promise<string> {
   const { code } = await ctx.transformer.transform(source, {
     loader,
     sourcefile: path,
@@ -85,3 +107,10 @@ export async function compileScript(ctx: CompileContext, path: string): Promise<
   const fromDir = dirname(path);
   return rewriteImports(code, (specifier) => mapSpecifier(ctx, fromDir, specifier));
 }
+
+/** TS/JSX → an ES module whose imports point at preview and CDN URLs. */
+export async function compileScript(ctx: CompileContext, path: string): Promise<string> {
+  const loader = loaderFor(extname(path));
+  if (!loader) throw new Error(`Not a script: ${path}`);
+  return compileModule(ctx, path, ctx.fs.readText(path) ?? '', loader);
+}

package/src/components.ts

@@ -0,0 +1,59 @@
+import type { Loader } from './transformer.js';
+
+/**
+ * Single-file components (`.vue`, `.svelte`) as a PORT, like the Transformer. A
+ * component compiler turns one file into a script module plus the CSS it owns;
+ * the dev server injects that CSS with a <style> tag and the build extracts it
+ * into the CSS bundle, so the compilers themselves never touch the DOM.
+ *
+ * The core never imports a framework compiler. The browser runtime loads the
+ * official ones from a CDN on first use, pinned to the project's own framework
+ * version (a Svelte compiler must match its runtime exactly); Node tests pass the
+ * npm packages in.
+ */
+export type ComponentExtension = '.vue' | '.svelte';
+
+export const COMPONENT_EXTENSIONS: readonly ComponentExtension[] = ['.vue', '.svelte'];
+
+export function componentExtension(ext: string): ComponentExtension | undefined {
+  return (COMPONENT_EXTENSIONS as readonly string[]).includes(ext) ? (ext as ComponentExtension) : undefined;
+}
+
+export interface ComponentRequest {
+  /** The VFS path — names the component in errors and seeds its style scope id. */
+  path: string;
+  /** Development output (dev warnings, readable names) vs production. */
+  dev: boolean;
+}
+
+export interface CompiledComponent {
+  /** An ES module (still TS when `loader` says so) whose default export is the component. */
+  code: string;
+  loader: Loader;
+  /** The component's styles, already scoped. Empty when it has none. */
+  css: string;
+}
+
+export interface ComponentCompiler {
+  compile(source: string, request: ComponentRequest): Promise<CompiledComponent> | CompiledComponent;
+}
+
+/**
+ * Supplies the compiler for an extension. Given the project's dependency ranges
+ * so a loader can fetch the compiler version that matches the project's runtime.
+ */
+export type ComponentCompilers = (
+  extension: ComponentExtension,
+  dependencies: Readonly<Record<string, string>>,
+) => Promise<ComponentCompiler>;
+
+/** Compilers already in hand (tests, a host that bundles them), keyed by extension. */
+export function staticComponentCompilers(compilers: Partial<Record<ComponentExtension, ComponentCompiler>>): ComponentCompilers {
+  return (extension) => {
+    const compiler = compilers[extension];
+    return compiler ? Promise.resolve(compiler) : Promise.reject(new Error(`No compiler for ${extension} files is configured.`));
+  };
+}
+
+/** The default when a host configures none: a clear error instead of serving source. */
+export const noComponentCompilers: ComponentCompilers = staticComponentCompilers({});

package/src/detectProject.ts

@@ -3,9 +3,13 @@ import { RESOLVE_EXTENSIONS } from './resolve.js';
 
 export type ProjectKind = 'vite' | 'cra' | 'static';
 
+/** The UI framework, when the project uses one this runtime compiles. */
+export type ProjectFramework = 'react' | 'vue' | 'svelte';
+
 export interface ProjectProfile {
   supported: boolean;
   kind?: ProjectKind;
+  framework?: ProjectFramework;
   /** The HTML document served at `/`. */
   htmlPath?: string;
   /** Script injected when the HTML has no module entry of its own (CRA). */
@@ -17,8 +21,10 @@ export interface ProjectProfile {
 }
 
 /**
- * Frameworks that need a server or a compiler this runtime does not have yet.
- * Data, not branches: supporting one later means deleting its row.
+ * Frameworks that need a server or a build pipeline this runtime does not have.
+ * Data, not branches: supporting one later means deleting its row. Checked before
+ * the plain-framework rules below, so SvelteKit and Nuxt (which depend on svelte
+ * and vue) are declined rather than mistaken for a Vite + Svelte/Vue app.
  */
 const NEEDS_NODE: ReadonlyArray<{ dependency: string; reason: string }> = [
   { dependency: 'next', reason: 'Next.js needs its Node server.' },
@@ -26,8 +32,6 @@ const NEEDS_NODE: ReadonlyArray<{ dependency: string; reason: string }> = [
   { dependency: '@remix-run/dev', reason: 'Remix needs its Node server.' },
   { dependency: '@sveltejs/kit', reason: 'SvelteKit needs its Node server.' },
   { dependency: 'astro', reason: 'Astro needs its build pipeline.' },
-  { dependency: 'svelte', reason: 'Svelte components need the Svelte compiler.' },
-  { dependency: 'vue', reason: 'Vue single-file components need the Vue compiler.' },
 ];
 
 const SERVER_ONLY = ['express', 'fastify', 'koa', '@nestjs/core', '@hapi/hapi'];
@@ -41,6 +45,13 @@ function readDependencyNames(fs: VirtualFileSystem): Set<string> {
   }
 }
 
+function detectFramework(deps: Set<string>): ProjectFramework | undefined {
+  if (deps.has('vue')) return 'vue';
+  if (deps.has('svelte')) return 'svelte';
+  if (deps.has('react')) return 'react';
+  return undefined;
+}
+
 function findEntry(fs: VirtualFileSystem): string | undefined {
   for (const stem of ['/src/index', '/src/main']) {
     for (const ext of RESOLVE_EXTENSIONS) if (fs.isFile(stem + ext)) return stem + ext;
@@ -53,11 +64,12 @@ export function detectProject(fs: VirtualFileSystem): ProjectProfile {
   const blocker = NEEDS_NODE.find((row) => deps.has(row.dependency));
   if (blocker) return { supported: false, publicDir: '/public', reason: blocker.reason };
 
+  const framework = detectFramework(deps);
   if (fs.isFile('/index.html')) {
-    return { supported: true, kind: deps.has('vite') ? 'vite' : 'static', htmlPath: '/index.html', publicDir: '/public' };
+    return { supported: true, kind: deps.has('vite') ? 'vite' : 'static', framework, htmlPath: '/index.html', publicDir: '/public' };
   }
   if (fs.isFile('/public/index.html')) {
-    return { supported: true, kind: 'cra', htmlPath: '/public/index.html', entry: findEntry(fs), publicDir: '/public' };
+    return { supported: true, kind: 'cra', framework, htmlPath: '/public/index.html', entry: findEntry(fs), publicDir: '/public' };
   }
   if (SERVER_ONLY.some((name) => deps.has(name))) {
     return { supported: false, publicDir: '/public', reason: 'This is a Node server app with no browser entry page.' };

package/src/devServer.ts

@@ -1,10 +1,12 @@
 import type { FsChange, VirtualFileSystem } from './vfs.js';
 import type { Transformer } from './transformer.js';
-import type { PackageCdn } from './packageCdn.js';
-import { createEsmShCdn } from './packageCdn.js';
+import type { PackageCdn, PackageCdnFactory } from './packageCdn.js';
+import { esmShCdnFactory } from './packageCdn.js';
+import { noComponentCompilers, type ComponentCompilers } from './components.js';
 import { isConfigFile, readProjectConfig, type ProjectConfig } from './projectConfig.js';
 import { detectProject, type ProjectProfile } from './detectProject.js';
-import { compileScript, type CompileContext, type ImportQuery } from './compileScript.js';
+import { compileScript, isScriptPath, type CompileContext, type ImportQuery } from './compileScript.js';
+import { compileComponent } from './compileComponent.js';
 import { transformHtml } from './html.js';
 import { cssToModule, jsonToModule, rawToModule, rewriteCssUrls, urlToModule } from './styleModules.js';
 import { loaderFor } from './transformer.js';
@@ -23,7 +25,9 @@ export interface DevServerOptions {
   /** The URL the preview is served under, ending in `/` (`/__bfwc/<id>/`). */
   base: string;
   /** Package CDN factory, given the project's dependency ranges. Default: esm.sh. */
-  cdn?: (dependencies: Record<string, string>) => PackageCdn;
+  cdn?: PackageCdnFactory;
+  /** `.vue` / `.svelte` compilers. Without them, requesting a component is an error. */
+  components?: ComponentCompilers;
   /** The "Built with Builderforce.ai" badge in served pages. Default true. */
   attribution?: boolean;
 }
@@ -73,7 +77,7 @@ function parseQuery(search: string): ImportQuery | undefined {
  */
 export class DevServer {
   private config?: ProjectConfig;
-  private cdn?: PackageCdn;
+  private cdn?: Promise<PackageCdn>;
   private profileCache?: ProjectProfile;
   private readonly cache = new Map<string, { version: number; file: ServedFile }>();
   private readonly unwatch: () => void;
@@ -105,7 +109,7 @@ export class DevServer {
     if (!file) {
       // An extension-less path is a client-side route: serve the app (SPA fallback).
       if (!extname(path) && !query) return this.serveDocument(profile);
-      return query || loaderFor(extname(path)) ? errorModule(`Cannot find module ${path}`) : reply(404, 'text/plain; charset=utf-8', `Not found: ${path}`);
+      return query || isScriptPath(path) ? errorModule(`Cannot find module ${path}`) : reply(404, 'text/plain; charset=utf-8', `Not found: ${path}`);
     }
 
     const key = `${file}?${query ?? ''}`;
@@ -129,14 +133,15 @@ export class DevServer {
         return query === 'import' ? reply(200, JS_MIME, cssToModule(file, css)) : reply(200, mimeFor(ext), css);
       }
       if (ext === '.json' && query === 'import') return reply(200, JS_MIME, jsonToModule(fs.readText(file) ?? ''));
-      if (loaderFor(ext)) return reply(200, JS_MIME, await compileScript(this.context(), file));
+      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), fs.readFile(file) ?? '');
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      return query || loaderFor(ext) ? errorModule(`${file}: ${message}`) : reply(500, 'text/plain; charset=utf-8', message);
+      return query || isScriptPath(file) ? errorModule(`${file}: ${message}`) : reply(500, 'text/plain; charset=utf-8', message);
     }
   }
 
@@ -149,11 +154,11 @@ export class DevServer {
     return reply(200, 'text/html; charset=utf-8', transformHtml(html, { base, entry: profile.entry, attribution }));
   }
 
-  private context(): CompileContext {
+  private async context(): Promise<CompileContext> {
     const { fs, transformer, base } = this.options;
     this.config ??= readProjectConfig(fs);
-    this.cdn ??= (this.options.cdn ?? ((dependencies) => createEsmShCdn({ dependencies })))(this.config.dependencies);
-    return { fs, config: this.config, cdn: this.cdn, transformer, base };
+    this.cdn ??= Promise.resolve((this.options.cdn ?? esmShCdnFactory)(this.config.dependencies, { dev: true }));
+    return { fs, config: this.config, cdn: await this.cdn, transformer, base, components: this.options.components ?? noComponentCompilers };
   }
 
   private onChange(change: FsChange): void {

package/src/hash.ts

@@ -0,0 +1,22 @@
+/**
+ * A short, deterministic content hash: cache-busting file names in a build and
+ * stable scope ids for component styles. Not cryptographic, and does not need to
+ * be — it only has to change when the bytes change. Synchronous (two FNV-1a
+ * variants mixed), so it works inside a bundler's resolve hook without
+ * `crypto.subtle`, which is async and missing outside secure contexts.
+ */
+const encoder = new TextEncoder();
+
+export function contentHash(data: string | Uint8Array, length = 8): string {
+  const bytes = typeof data === 'string' ? encoder.encode(data) : data;
+  let h1 = 0x811c9dc5;
+  let h2 = 0x5bd1e995;
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i]!;
+    h1 = Math.imul(h1 ^ byte, 0x01000193);
+    h2 = Math.imul(h2 ^ byte, 0x5bd1e995);
+    h2 ^= h2 >>> 15;
+  }
+  const hex = (h1 >>> 0).toString(16).padStart(8, '0') + (h2 >>> 0).toString(16).padStart(8, '0');
+  return hex.slice(0, length);
+}

package/src/index.ts

@@ -4,17 +4,46 @@ export { normalizePath, dirname, basename, join, extname } from './paths.js';
 export { DevServer } from './devServer.js';
 export type { DevServerOptions, ServedFile } from './devServer.js';
 export { detectProject } from './detectProject.js';
-export type { ProjectKind, ProjectProfile } from './detectProject.js';
-export { readProjectConfig, parseLooseJson, parseDotenv } from './projectConfig.js';
-export type { ProjectConfig, PathAlias } from './projectConfig.js';
-export { createEsmShCdn } from './packageCdn.js';
-export type { PackageCdn, EsmShOptions } from './packageCdn.js';
+export type { ProjectKind, ProjectFramework, ProjectProfile } from './detectProject.js';
+export { readProjectConfig, parseLooseJson, parseDotenv, envFiles } from './projectConfig.js';
+export type { ProjectConfig, PathAlias, BuildMode } from './projectConfig.js';
+export { createEsmShCdn, esmShCdnFactory, isRegistryRange, loadPackageManifests } from './packageCdn.js';
+export type { PackageCdn, PackageCdnFactory, EsmShOptions, PackageDependencyFields, ManifestLoadOptions } from './packageCdn.js';
 export { createEsbuildTransformer, loaderFor } from './transformer.js';
 export type { Transformer, TransformRequest, Loader, EsbuildLike } from './transformer.js';
+export { createEsbuildBundler } from './bundler.js';
+export type {
+  Bundler,
+  BundleRequest,
+  BundleOutput,
+  BundleOutputFile,
+  BundleHost,
+  BundleLoad,
+  BundleLoader,
+  BundleResolution,
+  ResolveKind,
+  EsbuildBuildLike,
+} from './bundler.js';
+export { buildProject, normalizeBase } from './build.js';
+export type { BuildOptions, BuildResult, BuiltFile } from './build.js';
+export { createBuildHost } from './buildHost.js';
+export type { BuildHost, BuildHostOptions } from './buildHost.js';
+export { findHtmlEntries, rewriteBuiltHtml } from './buildHtml.js';
+export type { HtmlEntry, BuiltHtmlOptions } from './buildHtml.js';
+export { COMPONENT_EXTENSIONS, componentExtension, staticComponentCompilers, noComponentCompilers } from './components.js';
+export type { ComponentCompiler, ComponentCompilers, ComponentExtension, ComponentRequest, CompiledComponent } from './components.js';
+export { createVueCompiler } from './vueCompiler.js';
+export type { VueCompilerSfcLike, VueDescriptor } from './vueCompiler.js';
+export { createSvelteCompiler } from './svelteCompiler.js';
+export type { SvelteCompilerLike } from './svelteCompiler.js';
+export { contentHash } from './hash.js';
 export { rewriteImports } from './rewriteImports.js';
 export { resolveLocal, resolveAlias, isBareSpecifier, splitPackageSpecifier, RESOLVE_EXTENSIONS } from './resolve.js';
-export { compileScript, mapSpecifier, moduleUrl, buildDefine } from './compileScript.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 { mimeFor } from './mime.js';
 export { attributionScript, injectAttribution, ATTRIBUTION_URL, ATTRIBUTION_LABEL } from './attribution.js';
 export type { AttributionOptions } from './attribution.js';
+export * from './installer/index.js';
+export * from './system/index.js';