@seanhogg/builderforce-webcontainers-core 2026.10.0

package/src/devServer.ts

@@ -0,0 +1,156 @@
+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 { isConfigFile, readProjectConfig, type ProjectConfig } from './projectConfig.js';
+import { detectProject, type ProjectProfile } from './detectProject.js';
+import { compileScript, type CompileContext, type ImportQuery } from './compileScript.js';
+import { transformHtml } from './html.js';
+import { cssToModule, jsonToModule, rawToModule, rewriteCssUrls, urlToModule } from './styleModules.js';
+import { loaderFor } from './transformer.js';
+import { extname, join, normalizePath } from './paths.js';
+import { JS_MIME, mimeFor } from './mime.js';
+
+export interface ServedFile {
+  status: number;
+  headers: Record<string, string>;
+  body: string | Uint8Array;
+}
+
+export interface DevServerOptions {
+  fs: VirtualFileSystem;
+  transformer: Transformer;
+  /** 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;
+  /** The "Built with Builderforce.ai" badge in served pages. Default true. */
+  attribution?: boolean;
+}
+
+const NO_STORE = { 'cache-control': 'no-store' };
+
+function reply(status: number, contentType: string, body: string | Uint8Array): ServedFile {
+  return { status, headers: { 'content-type': contentType, ...NO_STORE }, body };
+}
+
+/** A module that throws — evaluated in the preview, it reaches the error bridge. */
+function errorModule(message: string): ServedFile {
+  return reply(200, JS_MIME, `throw new Error(${JSON.stringify(message)});`);
+}
+
+function parseQuery(search: string): ImportQuery | undefined {
+  const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+  if (params.has('raw')) return 'raw';
+  if (params.has('url')) return 'url';
+  if (params.has('import')) return 'import';
+  return undefined;
+}
+
+/**
+ * The dev server: request path in, response out. It does not listen on anything —
+ * the host decides how requests arrive (a service worker in the browser, a plain
+ * function call in tests), which is what keeps it runtime-agnostic.
+ *
+ * Responses are cached per (file, query) and validated against the file's VFS
+ * version. Edits to an existing file evict only that file; creating or deleting a
+ * file, or touching a config file, clears everything, since either can change how
+ * OTHER files' imports resolve.
+ */
+export class DevServer {
+  private config?: ProjectConfig;
+  private cdn?: PackageCdn;
+  private profileCache?: ProjectProfile;
+  private readonly cache = new Map<string, { version: number; file: ServedFile }>();
+  private readonly unwatch: () => void;
+
+  constructor(private readonly options: DevServerOptions) {
+    if (!options.base.endsWith('/')) throw new Error('DevServer base must end with "/"');
+    this.unwatch = options.fs.watch((change) => this.onChange(change));
+  }
+
+  dispose(): void {
+    this.unwatch();
+    this.cache.clear();
+  }
+
+  profile(): ProjectProfile {
+    return (this.profileCache ??= detectProject(this.options.fs));
+  }
+
+  async handle(requestPath: string, search = ''): Promise<ServedFile> {
+    const { fs } = this.options;
+    const path = normalizePath(decodeURIComponent(requestPath));
+    const query = parseQuery(search);
+    const profile = this.profile();
+
+    if (path === '/' || path === '/index.html' || path === profile.htmlPath) return this.serveDocument(profile);
+
+    const publicPath = join(profile.publicDir, path);
+    const file = fs.isFile(path) ? path : fs.isFile(publicPath) ? publicPath : undefined;
+    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}`);
+    }
+
+    const key = `${file}?${query ?? ''}`;
+    const version = fs.version(file) ?? 0;
+    const hit = this.cache.get(key);
+    if (hit && hit.version === version) return hit.file;
+
+    const served = await this.produce(file, query);
+    this.cache.set(key, { version, file: served });
+    return served;
+  }
+
+  private async produce(file: string, query: ImportQuery | undefined): Promise<ServedFile> {
+    const { fs, base } = this.options;
+    const ext = extname(file);
+    try {
+      if (query === 'raw') return reply(200, JS_MIME, rawToModule(fs.readText(file) ?? ''));
+      if (query === 'url') return reply(200, JS_MIME, urlToModule(base + file.slice(1)));
+      if (ext === '.css') {
+        const css = rewriteCssUrls(fs, file, fs.readText(file) ?? '', base);
+        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 (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);
+    }
+  }
+
+  private serveDocument(profile: ProjectProfile): ServedFile {
+    if (!profile.supported || !profile.htmlPath) {
+      return reply(501, 'text/html; charset=utf-8', `<!doctype html><meta charset="utf-8"><p>${profile.reason ?? 'Unsupported project.'}</p>`);
+    }
+    const html = this.options.fs.readText(profile.htmlPath) ?? '';
+    const { base, attribution } = this.options;
+    return reply(200, 'text/html; charset=utf-8', transformHtml(html, { base, entry: profile.entry, attribution }));
+  }
+
+  private context(): 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 };
+  }
+
+  private onChange(change: FsChange): void {
+    const structural = change.type === 'remove' || change.created === true || isConfigFile(change.path) || extname(change.path) === '.html';
+    if (!structural) {
+      for (const key of [...this.cache.keys()]) if (key.startsWith(change.path + '?')) this.cache.delete(key);
+      return;
+    }
+    this.cache.clear();
+    this.config = undefined;
+    this.cdn = undefined;
+    this.profileCache = undefined;
+  }
+}

package/src/html.ts

@@ -0,0 +1,58 @@
+/**
+ * Prepare the project's HTML for the preview:
+ *   • absolute `src`/`href` paths (`/src/main.tsx`) are re-rooted under the preview
+ *     base, since the preview is served from a sub-path, not the origin root;
+ *   • CRA's `%PUBLIC_URL%` placeholder is filled;
+ *   • a page with no module script (CRA) gets its entry injected;
+ *   • the error bridge is prepended, so runtime errors reach the host;
+ *   • the attribution badge is appended unless the host turned it off.
+ */
+import { injectAttribution } from './attribution.js';
+
+export const ERROR_MESSAGE_TYPE = 'bfwc:error';
+
+/**
+ * Runs first in the preview. Forwards uncaught errors and rejections to the host
+ * page (`window.parent`), which is how an editor — or an agent — learns the app
+ * crashed without scraping the iframe.
+ */
+export function errorBridgeScript(): string {
+  return `<script>(function(){
+  var send = function (message, stack) {
+    try { parent.postMessage({ type: ${JSON.stringify(ERROR_MESSAGE_TYPE)}, message: String(message), stack: stack ? String(stack) : undefined, href: location.href }, '*'); } catch (_) {}
+  };
+  addEventListener('error', function (e) { send(e.message, e.error && e.error.stack); });
+  addEventListener('unhandledrejection', function (e) { var r = e.reason; send(r && r.message ? r.message : r, r && r.stack); });
+  window.process = window.process || { env: { NODE_ENV: 'development' } };
+})();</script>`;
+}
+
+const ABSOLUTE_ATTR = /(\s(?:src|href)\s*=\s*)(["'])\/(?!\/)([^"']*)\2/gi;
+const MODULE_SCRIPT = /<script\b[^>]*type\s*=\s*["']module["'][^>]*>/i;
+
+export interface HtmlOptions {
+  /** Preview base URL, ending in `/`. */
+  base: string;
+  /** Entry injected when the page has no module script. */
+  entry?: string;
+  /** The "Built with Builderforce.ai" badge. On unless explicitly `false`. */
+  attribution?: boolean;
+}
+
+export function transformHtml(html: string, options: HtmlOptions): string {
+  const { base } = options;
+  // `%PUBLIC_URL%/logo.png` becomes root-absolute here and is re-rooted once below;
+  // filling in the base directly would let the re-rooting prefix it a second time.
+  let out = html.replace(/%PUBLIC_URL%/g, '');
+  out = out.replace(ABSOLUTE_ATTR, (_m, attr: string, quote: string, rest: string) => `${attr}${quote}${base}${rest}${quote}`);
+
+  if (options.entry && !MODULE_SCRIPT.test(out)) {
+    const tag = `<script type="module" src="${base}${options.entry.slice(1)}"></script>`;
+    out = /<\/body>/i.test(out) ? out.replace(/<\/body>/i, `${tag}\n</body>`) : out + tag;
+  }
+  if (options.attribution !== false) out = injectAttribution(out);
+
+  const bridge = errorBridgeScript();
+  if (/<head[^>]*>/i.test(out)) return out.replace(/<head[^>]*>/i, (head) => `${head}\n${bridge}`);
+  return bridge + out;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { VirtualFileSystem } from './vfs.js';
+export type { FileContent, FileSystemTree, FlatFiles, FsChange } from './vfs.js';
+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 { createEsbuildTransformer, loaderFor } from './transformer.js';
+export type { Transformer, TransformRequest, Loader, EsbuildLike } from './transformer.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 { transformHtml, errorBridgeScript, 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';

package/src/mime.ts

@@ -0,0 +1,36 @@
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.wasm': 'application/wasm',
+  '.pdf': 'application/pdf',
+};
+
+export const JS_MIME = 'text/javascript; charset=utf-8';
+
+export function mimeFor(ext: string): string {
+  return MIME[ext] ?? 'application/octet-stream';
+}

package/src/packageCdn.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a bare import (`react`, `react-dom/client`) is fetched from. A PORT, so a
+ * fork can point at a self-hosted mirror or an offline cache without touching the
+ * rest of the runtime. The default speaks esm.sh's URL scheme.
+ */
+export interface PackageCdn {
+  /** The ES-module URL for `name` + `subpath` (`'' | '/client'`). */
+  urlFor(name: string, subpath: string): string;
+}
+
+export interface EsmShOptions {
+  /** Defaults to https://esm.sh. Any esm.sh-compatible server works. */
+  origin?: string;
+  /** The project's dependency ranges — pins versions and dedupes shared packages. */
+  dependencies?: Record<string, string>;
+  /** Serve development builds (readable React errors). Default true. */
+  dev?: boolean;
+}
+
+/** A range the CDN can't fetch (`workspace:*`, `file:../x`, `link:`, git URLs). */
+function isRegistryRange(range: string): boolean {
+  return !/^(workspace|file|link|portal|git\+|git:|github:|https?:)/.test(range) && !range.includes('/');
+}
+
+export function createEsmShCdn(options: EsmShOptions = {}): PackageCdn {
+  const origin = (options.origin ?? 'https://esm.sh').replace(/\/+$/, '');
+  const dependencies = options.dependencies ?? {};
+  const dev = options.dev ?? true;
+
+  // Pin every declared dependency into each package's own graph, so `react-dom`
+  // and the app share ONE `react` — two copies is the classic "invalid hook call".
+  const pinned = Object.entries(dependencies)
+    .filter(([, range]) => isRegistryRange(range))
+    .map(([name, range]) => `${name}@${range}`)
+    .sort();
+
+  return {
+    urlFor(name, subpath) {
+      const range = dependencies[name];
+      const versioned = range && isRegistryRange(range) ? `${name}@${range}` : name;
+      const params: string[] = [];
+      const deps = pinned.filter((entry) => !entry.startsWith(name + '@'));
+      if (deps.length) params.push('deps=' + deps.map(encodeURIComponent).join(','));
+      if (dev) params.push('dev');
+      return `${origin}/${versioned}${subpath}${params.length ? '?' + params.join('&') : ''}`;
+    },
+  };
+}

package/src/paths.ts

@@ -0,0 +1,37 @@
+/**
+ * POSIX path helpers for the virtual file system. Every path the runtime stores is
+ * absolute and normalised (`/src/App.tsx`), so comparisons are plain string equality.
+ */
+
+/** Absolute, normalised: resolves `.`/`..`, collapses slashes, accepts backslashes. */
+export function normalizePath(path: string): string {
+  const parts: string[] = [];
+  for (const segment of path.replace(/\\/g, '/').split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') parts.pop();
+    else parts.push(segment);
+  }
+  return '/' + parts.join('/');
+}
+
+export function dirname(path: string): string {
+  const normalized = normalizePath(path);
+  const cut = normalized.lastIndexOf('/');
+  return cut <= 0 ? '/' : normalized.slice(0, cut);
+}
+
+export function basename(path: string): string {
+  const normalized = normalizePath(path);
+  return normalized.slice(normalized.lastIndexOf('/') + 1);
+}
+
+export function join(...segments: string[]): string {
+  return normalizePath(segments.join('/'));
+}
+
+/** Lower-cased extension including the dot (`.tsx`), or `''`. Dotfiles have none. */
+export function extname(path: string): string {
+  const base = basename(path);
+  const dot = base.lastIndexOf('.');
+  return dot <= 0 ? '' : base.slice(dot).toLowerCase();
+}

package/src/projectConfig.ts

@@ -0,0 +1,157 @@
+import type { VirtualFileSystem } from './vfs.js';
+import { join, normalizePath } from './paths.js';
+
+/**
+ * What the dev server needs to know about a project, read from its own files:
+ * dependency versions (for the package CDN), tsconfig path aliases and JSX mode,
+ * and `VITE_*` variables from `.env` files.
+ *
+ * Everything here is derived, so it is recomputed whenever one of
+ * {@link CONFIG_FILES} changes and is otherwise read from the cache.
+ */
+export const CONFIG_FILES = [
+  '/package.json',
+  '/tsconfig.json',
+  '/jsconfig.json',
+  '/.env',
+  '/.env.local',
+  '/.env.development',
+  '/.env.development.local',
+] as const;
+
+export interface PathAlias {
+  /** The specifier prefix, without the trailing `*` (`@/`). Exact when `wildcard` is false. */
+  prefix: string;
+  wildcard: boolean;
+  /** Absolute VFS targets, without the trailing `*`, tried in order. */
+  targets: string[];
+}
+
+export interface ProjectConfig {
+  /** dependencies + devDependencies, name → version range. */
+  dependencies: Record<string, string>;
+  aliases: PathAlias[];
+  jsx: { runtime: 'automatic' | 'classic'; importSource: string };
+  /** `VITE_*` and `NODE_ENV` style variables from the `.env` files, in load order. */
+  env: Record<string, string>;
+}
+
+/** JSON that tolerates the comments and trailing commas tsconfig files carry. */
+export function parseLooseJson(text: string): unknown {
+  let out = '';
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (ch === '\\') { out += next ?? ''; i++; }
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; out += ch; continue; }
+    if (ch === '/' && next === '/') { while (i < text.length && text[i] !== '\n') i++; out += '\n'; continue; }
+    if (ch === '/' && next === '*') { i += 2; while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++; i++; continue; }
+    out += ch;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+}
+
+function readJson(fs: VirtualFileSystem, path: string): Record<string, unknown> | undefined {
+  const text = fs.readText(path);
+  if (text === undefined) return undefined;
+  try {
+    const value = parseLooseJson(text);
+    return value && typeof value === 'object' ? (value as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+}
+
+function readDependencies(fs: VirtualFileSystem): Record<string, string> {
+  const pkg = readJson(fs, '/package.json') ?? {};
+  const out: Record<string, string> = {};
+  for (const field of ['devDependencies', 'dependencies']) {
+    for (const [name, version] of Object.entries(asRecord(pkg[field]))) {
+      if (typeof version === 'string') out[name] = version;
+    }
+  }
+  return out;
+}
+
+function readCompilerOptions(fs: VirtualFileSystem): Record<string, unknown> {
+  const tsconfig = readJson(fs, '/tsconfig.json') ?? readJson(fs, '/jsconfig.json') ?? {};
+  return asRecord(tsconfig.compilerOptions);
+}
+
+function readAliases(options: Record<string, unknown>): PathAlias[] {
+  const baseUrl = typeof options.baseUrl === 'string' ? options.baseUrl : '.';
+  const aliases: PathAlias[] = [];
+  for (const [pattern, rawTargets] of Object.entries(asRecord(options.paths))) {
+    if (!Array.isArray(rawTargets)) continue;
+    const wildcard = pattern.endsWith('*');
+    const targets = rawTargets
+      .filter((t): t is string => typeof t === 'string')
+      .map((t) => {
+        const stripped = wildcard ? t.replace(/\*$/, '') : t;
+        const resolved = join('/', baseUrl, stripped);
+        return stripped.endsWith('/') && resolved !== '/' ? resolved + '/' : resolved;
+      });
+    aliases.push({ prefix: wildcard ? pattern.slice(0, -1) : pattern, wildcard, targets });
+  }
+  // Longest prefix first, so `@/components/*` wins over `@/*`.
+  return aliases.sort((a, b) => b.prefix.length - a.prefix.length);
+}
+
+function readJsx(options: Record<string, unknown>): ProjectConfig['jsx'] {
+  const importSource = typeof options.jsxImportSource === 'string' ? options.jsxImportSource : 'react';
+  const runtime = options.jsx === 'react' ? 'classic' : 'automatic';
+  return { runtime, importSource };
+}
+
+/** `KEY=value` lines; quotes stripped, `#` comments and blank lines ignored. */
+export function parseDotenv(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).replace(/^export\s+/, '').trim();
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function readEnv(fs: VirtualFileSystem): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const file of CONFIG_FILES) {
+    if (!file.startsWith('/.env')) continue;
+    const text = fs.readText(file);
+    if (text !== undefined) Object.assign(env, parseDotenv(text));
+  }
+  return env;
+}
+
+export function readProjectConfig(fs: VirtualFileSystem): ProjectConfig {
+  const options = readCompilerOptions(fs);
+  return {
+    dependencies: readDependencies(fs),
+    aliases: readAliases(options),
+    jsx: readJsx(options),
+    env: readEnv(fs),
+  };
+}
+
+/** 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));
+}

package/src/resolve.ts

@@ -0,0 +1,60 @@
+import type { VirtualFileSystem } from './vfs.js';
+import type { PathAlias } from './projectConfig.js';
+import { extname, join, normalizePath } from './paths.js';
+
+/** Extensions probed, in order, for an extension-less import — Vite's default order. */
+export const RESOLVE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.json', '.css'] as const;
+
+/** `foo`, `@scope/foo`, `foo/sub` — not relative, not absolute, not a URL. */
+export function isBareSpecifier(specifier: string): boolean {
+  if (specifier.startsWith('.') || specifier.startsWith('/')) return false;
+  return !/^[a-z][a-z0-9+.-]*:/i.test(specifier);
+}
+
+/** Split a bare specifier into its package name and subpath (`/client`, or `''`). */
+export function splitPackageSpecifier(specifier: string): { name: string; subpath: string } {
+  const parts = specifier.split('/');
+  const take = specifier.startsWith('@') ? 2 : 1;
+  return { name: parts.slice(0, take).join('/'), subpath: parts.length > take ? '/' + parts.slice(take).join('/') : '' };
+}
+
+function probe(fs: VirtualFileSystem, base: string): string | undefined {
+  if (fs.isFile(base)) return base;
+  for (const ext of RESOLVE_EXTENSIONS) if (fs.isFile(base + ext)) return base + ext;
+  // TypeScript ESM convention: `./util.js` written in source names `util.ts`.
+  const ext = extname(base);
+  if (ext === '.js' || ext === '.jsx' || ext === '.mjs') {
+    const stem = base.slice(0, -ext.length);
+    for (const alt of ['.ts', '.tsx']) if (fs.isFile(stem + alt)) return stem + alt;
+  }
+  if (fs.isDirectory(base)) {
+    for (const ext2 of RESOLVE_EXTENSIONS) {
+      const index = join(base, 'index' + ext2);
+      if (fs.isFile(index)) return index;
+    }
+  }
+  return undefined;
+}
+
+/** Resolve a relative or absolute specifier against the importing file's directory. */
+export function resolveLocal(fs: VirtualFileSystem, fromDir: string, specifier: string): string | undefined {
+  const base = specifier.startsWith('/') ? normalizePath(specifier) : join(fromDir, specifier);
+  return probe(fs, base);
+}
+
+/**
+ * Resolve a specifier through tsconfig `paths` (`@/components/Button` →
+ * `/src/components/Button.tsx`). Undefined when no alias matches or no target exists.
+ */
+export function resolveAlias(fs: VirtualFileSystem, aliases: readonly PathAlias[], specifier: string): string | undefined {
+  for (const alias of 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 = probe(fs, normalizePath(target + rest));
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}

package/src/rewriteImports.ts

@@ -0,0 +1,26 @@
+import { init, parse } from 'es-module-lexer';
+
+/**
+ * Rewrite every import specifier in an ES module — static `import`/`export … from`,
+ * side-effect `import 'x'`, and string-literal dynamic `import('x')` — through
+ * `map`. A `map` result of `undefined` leaves that specifier untouched, as are
+ * non-literal dynamic imports and `import.meta`.
+ *
+ * Positions come from es-module-lexer rather than a regex, so specifiers inside
+ * strings, comments and template literals are never touched.
+ */
+export async function rewriteImports(code: string, map: (specifier: string) => string | undefined): Promise<string> {
+  await init;
+  const [imports] = parse(code);
+  let out = '';
+  let cursor = 0;
+  for (const entry of imports) {
+    if (entry.d === -2 || entry.n === undefined) continue; // import.meta, or a non-literal dynamic import
+    const replacement = map(entry.n);
+    if (replacement === undefined || replacement === entry.n) continue;
+    const dynamic = entry.d > -1;
+    out += code.slice(cursor, entry.s) + (dynamic ? JSON.stringify(replacement) : replacement);
+    cursor = entry.e;
+  }
+  return out + code.slice(cursor);
+}

package/src/styleModules.ts

@@ -0,0 +1,57 @@
+import type { VirtualFileSystem } from './vfs.js';
+import { dirname } from './paths.js';
+import { resolveLocal } from './resolve.js';
+
+/**
+ * CSS handling. A stylesheet imported from JS is served as a JS module that
+ * injects a <style> tag (keyed by path, so a re-import replaces rather than
+ * duplicates). Its relative `url(...)` references are rewritten to absolute
+ * preview URLs, because once the text lives in a <style> tag the browser resolves
+ * them against the DOCUMENT, not the stylesheet's own location.
+ */
+
+const URL_REF = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+
+export function rewriteCssUrls(fs: VirtualFileSystem, cssPath: string, css: string, base: string): string {
+  return css.replace(URL_REF, (match, quote: string, ref: string) => {
+    if (/^(data:|https?:|\/\/|#)/i.test(ref)) return match;
+    const [pathPart] = ref.split(/[?#]/);
+    if (!pathPart) return match;
+    const resolved = resolveLocal(fs, dirname(cssPath), pathPart);
+    if (!resolved) return match;
+    return `url(${quote}${base}${resolved.slice(1)}${ref.slice(pathPart.length)}${quote})`;
+  });
+}
+
+/**
+ * The JS module for an imported stylesheet. `.module.css` exports an identity map
+ * (class name → itself): real scoping needs the build API, so for now CSS Modules
+ * render correctly as long as class names don't collide.
+ */
+export function cssToModule(path: string, css: string): string {
+  const id = JSON.stringify(path);
+  const exportsCssModule = /\.module\.css$/i.test(path);
+  return [
+    `const css = ${JSON.stringify(css)};`,
+    `let el = document.querySelector('style[data-bfwc=' + JSON.stringify(${id}) + ']');`,
+    `if (!el) { el = document.createElement('style'); el.setAttribute('data-bfwc', ${id}); document.head.appendChild(el); }`,
+    `el.textContent = css;`,
+    exportsCssModule
+      ? `export default new Proxy({}, { get: (_, key) => typeof key === 'string' ? key : undefined });`
+      : `export default css;`,
+  ].join('\n');
+}
+
+export function jsonToModule(text: string): string {
+  // Round-trip so a malformed file fails here with a clear message, not as a
+  // syntax error inside generated code.
+  return `export default ${JSON.stringify(JSON.parse(text))};`;
+}
+
+export function rawToModule(text: string): string {
+  return `export default ${JSON.stringify(text)};`;
+}
+
+export function urlToModule(url: string): string {
+  return `export default ${JSON.stringify(url)};`;
+}