@seanhogg/builderforce-webcontainers-core 2026.10.0

package/dist/transformer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The compiler, as a PORT. The core never imports esbuild: the browser runtime
+ * plugs in esbuild-wasm, tests plug in native esbuild, and a fork can plug in SWC
+ * or anything else that turns TS/JSX into an ES module.
+ */
+export type Loader = 'js' | 'jsx' | 'ts' | 'tsx';
+export interface TransformRequest {
+    loader: Loader;
+    /** The VFS path — shows up in error messages and source maps. */
+    sourcefile: string;
+    /** Compile-time replacements, esbuild `define` semantics (values are JS source). */
+    define: Record<string, string>;
+    jsx: {
+        runtime: 'automatic' | 'classic';
+        importSource: string;
+    };
+}
+export interface Transformer {
+    transform(code: string, request: TransformRequest): Promise<{
+        code: string;
+    }>;
+}
+/** The subset of esbuild's (and esbuild-wasm's) API the adapter uses. */
+export interface EsbuildLike {
+    transform(code: string, options: {
+        loader: Loader;
+        sourcefile: string;
+        format: 'esm';
+        target: string;
+        define: Record<string, string>;
+        jsx: 'automatic' | 'transform';
+        jsxImportSource?: string;
+        sourcemap: 'inline';
+    }): Promise<{
+        code: string;
+    }>;
+}
+/** Adapt esbuild or esbuild-wasm to {@link Transformer}. */
+export declare function createEsbuildTransformer(esbuild: EsbuildLike): Transformer;
+/** The loader for a source extension, or undefined when the file is not compiled. */
+export declare function loaderFor(ext: string): Loader | undefined;
+//# sourceMappingURL=transformer.d.ts.map

package/dist/transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../src/transformer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,GAAG,EAAE;QAAE,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,GAAG,EAAE,WAAW,GAAG,WAAW,CAAC;QAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,QAAQ,CAAC;KACrB,GACA,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9B;AAED,4DAA4D;AAC5D,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAe1E;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAmBzD"}

package/dist/transformer.js

@@ -0,0 +1,39 @@
+/** Adapt esbuild or esbuild-wasm to {@link Transformer}. */
+export function createEsbuildTransformer(esbuild) {
+    return {
+        transform(code, request) {
+            return esbuild.transform(code, {
+                loader: request.loader,
+                sourcefile: request.sourcefile,
+                format: 'esm',
+                target: 'es2020',
+                define: request.define,
+                jsx: request.jsx.runtime === 'automatic' ? 'automatic' : 'transform',
+                ...(request.jsx.runtime === 'automatic' ? { jsxImportSource: request.jsx.importSource } : {}),
+                sourcemap: 'inline',
+            });
+        },
+    };
+}
+/** The loader for a source extension, or undefined when the file is not compiled. */
+export function loaderFor(ext) {
+    switch (ext) {
+        case '.ts':
+        case '.mts':
+        case '.cts':
+            return 'ts';
+        case '.tsx':
+            return 'tsx';
+        // `.js` gets the JSX loader: Create React App puts JSX in `.js` files, and the
+        // JSX loader accepts plain JavaScript unchanged.
+        case '.js':
+        case '.jsx':
+            return 'jsx';
+        case '.mjs':
+        case '.cjs':
+            return 'js';
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=transformer.js.map

package/dist/transformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.js","sourceRoot":"","sources":["../src/transformer.ts"],"names":[],"mappings":"AAqCA,4DAA4D;AAC5D,MAAM,UAAU,wBAAwB,CAAC,OAAoB;IAC3D,OAAO;QACL,SAAS,CAAC,IAAI,EAAE,OAAO;YACrB,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE;gBAC7B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,QAAQ;gBAChB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW;gBACpE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7F,SAAS,EAAE,QAAQ;aACpB,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;QACd,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,+EAA+E;QAC/E,iDAAiD;QACjD,KAAK,KAAK,CAAC;QACX,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;QACd;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/vfs.d.ts

@@ -0,0 +1,57 @@
+export type FileContent = string | Uint8Array;
+/** The nested tree shape `@webcontainer/api`'s `mount()` takes — accepted as-is. */
+export interface FileSystemTree {
+    [name: string]: {
+        file: {
+            contents: FileContent;
+        };
+    } | {
+        directory: FileSystemTree;
+    };
+}
+/** A flat `{ 'src/main.tsx': '...' }` map, the other shape callers commonly hold. */
+export type FlatFiles = Record<string, FileContent>;
+export interface FsChange {
+    type: 'write' | 'remove';
+    path: string;
+    /** For a write: the file did not exist before. A new file can change how imports resolve. */
+    created?: boolean;
+}
+/**
+ * An in-memory file system. Files only — a directory exists while it contains a
+ * file, which keeps the store a single map and makes "is this a directory?" a
+ * prefix check rather than a second structure to keep consistent.
+ *
+ * Every write bumps a per-file version, so a transform cache can key on
+ * (path, version) instead of hashing contents.
+ */
+export declare class VirtualFileSystem {
+    private readonly files;
+    private readonly versions;
+    private readonly listeners;
+    private clock;
+    writeFile(path: string, contents: FileContent): void;
+    readFile(path: string): FileContent | undefined;
+    readText(path: string): string | undefined;
+    isFile(path: string): boolean;
+    isDirectory(path: string): boolean;
+    exists(path: string): boolean;
+    /** Direct children of a directory (files and sub-directories), sorted. */
+    readdir(path: string): string[];
+    /** Every file path, sorted. */
+    list(): string[];
+    /** Remove a file, or a directory and everything under it. */
+    rm(path: string): void;
+    /** The file's version (bumped on every write), or undefined when absent. */
+    version(path: string): number | undefined;
+    /**
+     * Write many files at once. Takes either the nested WebContainer tree or a flat
+     * path→contents map — or a mix, since each entry is judged on its own.
+     */
+    mount(files: FileSystemTree | FlatFiles, at?: string): void;
+    /** Flat snapshot keyed without the leading slash (`src/main.tsx`). */
+    toFlat(): FlatFiles;
+    watch(listener: (change: FsChange) => void): () => void;
+    private emit;
+}
+//# sourceMappingURL=vfs.d.ts.map

package/dist/vfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs.d.ts","sourceRoot":"","sources":["../src/vfs.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9C,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE;YAAE,QAAQ,EAAE,WAAW,CAAA;SAAE,CAAA;KAAE,GAAG;QAAE,SAAS,EAAE,cAAc,CAAA;KAAE,CAAC;CACrF;AAED,qFAAqF;AACrF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAID;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,KAAK,CAAK;IAElB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI;IAQpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAI/C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM1C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQlC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,0EAA0E;IAC1E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAa/B,+BAA+B;IAC/B,IAAI,IAAI,MAAM,EAAE;IAIhB,6DAA6D;IAC7D,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAYtB,4EAA4E;IAC5E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,EAAE,EAAE,SAAM,GAAG,IAAI;IASxD,sEAAsE;IACtE,MAAM,IAAI,SAAS;IAMnB,KAAK,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAKvD,OAAO,CAAC,IAAI;CAGb"}

package/dist/vfs.js

@@ -0,0 +1,114 @@
+import { normalizePath, join } from './paths.js';
+const decoder = new TextDecoder();
+/**
+ * An in-memory file system. Files only — a directory exists while it contains a
+ * file, which keeps the store a single map and makes "is this a directory?" a
+ * prefix check rather than a second structure to keep consistent.
+ *
+ * Every write bumps a per-file version, so a transform cache can key on
+ * (path, version) instead of hashing contents.
+ */
+export class VirtualFileSystem {
+    files = new Map();
+    versions = new Map();
+    listeners = new Set();
+    clock = 0;
+    writeFile(path, contents) {
+        const key = normalizePath(path);
+        const created = !this.files.has(key);
+        this.files.set(key, contents);
+        this.versions.set(key, ++this.clock);
+        this.emit({ type: 'write', path: key, created });
+    }
+    readFile(path) {
+        return this.files.get(normalizePath(path));
+    }
+    readText(path) {
+        const contents = this.readFile(path);
+        if (contents === undefined)
+            return undefined;
+        return typeof contents === 'string' ? contents : decoder.decode(contents);
+    }
+    isFile(path) {
+        return this.files.has(normalizePath(path));
+    }
+    isDirectory(path) {
+        const key = normalizePath(path);
+        if (key === '/')
+            return true;
+        const prefix = key + '/';
+        for (const file of this.files.keys())
+            if (file.startsWith(prefix))
+                return true;
+        return false;
+    }
+    exists(path) {
+        return this.isFile(path) || this.isDirectory(path);
+    }
+    /** Direct children of a directory (files and sub-directories), sorted. */
+    readdir(path) {
+        const key = normalizePath(path);
+        const prefix = key === '/' ? '/' : key + '/';
+        const names = new Set();
+        for (const file of this.files.keys()) {
+            if (!file.startsWith(prefix))
+                continue;
+            const rest = file.slice(prefix.length);
+            const name = rest.split('/')[0];
+            if (name)
+                names.add(name);
+        }
+        return [...names].sort();
+    }
+    /** Every file path, sorted. */
+    list() {
+        return [...this.files.keys()].sort();
+    }
+    /** Remove a file, or a directory and everything under it. */
+    rm(path) {
+        const key = normalizePath(path);
+        const prefix = key === '/' ? '/' : key + '/';
+        for (const file of [...this.files.keys()]) {
+            if (file === key || file.startsWith(prefix)) {
+                this.files.delete(file);
+                this.versions.delete(file);
+                this.emit({ type: 'remove', path: file });
+            }
+        }
+    }
+    /** The file's version (bumped on every write), or undefined when absent. */
+    version(path) {
+        return this.versions.get(normalizePath(path));
+    }
+    /**
+     * Write many files at once. Takes either the nested WebContainer tree or a flat
+     * path→contents map — or a mix, since each entry is judged on its own.
+     */
+    mount(files, at = '/') {
+        for (const [name, entry] of Object.entries(files)) {
+            const path = join(at, name);
+            if (typeof entry === 'string' || entry instanceof Uint8Array)
+                this.writeFile(path, entry);
+            else if ('file' in entry)
+                this.writeFile(path, entry.file.contents);
+            else
+                this.mount(entry.directory, path);
+        }
+    }
+    /** Flat snapshot keyed without the leading slash (`src/main.tsx`). */
+    toFlat() {
+        const out = {};
+        for (const [path, contents] of this.files)
+            out[path.slice(1)] = contents;
+        return out;
+    }
+    watch(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(change) {
+        for (const listener of this.listeners)
+            listener(change);
+    }
+}
+//# sourceMappingURL=vfs.js.map

package/dist/vfs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs.js","sourceRoot":"","sources":["../src/vfs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@seanhogg/builderforce-webcontainers-core",
+  "version": "2026.10.0",
+  "description": "BuilderForce WebContainers — core. A runtime-agnostic in-browser dev server: virtual file system, module resolution, import rewriting to a package CDN, CSS/JSON/asset modules and project detection. No COOP/COEP required.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "webcontainer",
+    "in-browser",
+    "dev-server",
+    "esbuild",
+    "vite",
+    "sandbox",
+    "preview",
+    "builderforce"
+  ],
+  "author": {
+    "name": "Sean Hogg",
+    "email": "seanhogg@gmail.com",
+    "url": "https://builderforce.ai"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SeanHogg/builderforce-webcontainers.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/SeanHogg/builderforce-webcontainers/issues"
+  },
+  "homepage": "https://github.com/SeanHogg/builderforce-webcontainers/tree/main/packages/core#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "es-module-lexer": "^1.5.4"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/attribution.ts

@@ -0,0 +1,57 @@
+/**
+ * The "Built with Builderforce.ai" badge, on by default in every preview.
+ *
+ * It is a DEFAULT, not a licence condition: the project stays MIT, and a host turns
+ * it off with `attribution: false`. Keeping it on is how this runtime pays for
+ * itself, and the README asks forks to leave it.
+ *
+ * The badge lives in a shadow root, so the previewed app's CSS can't restyle or hide
+ * it by accident and the badge's styles can't leak into the app. It follows the
+ * system light/dark preference and sits in the bottom-right corner, small enough
+ * not to cover app UI on a phone-width screen.
+ */
+
+export const ATTRIBUTION_URL = 'https://builderforce.ai/?utm_source=webcontainers&utm_medium=badge&utm_campaign=preview';
+export const ATTRIBUTION_LABEL = 'Built with Builderforce.ai';
+
+export interface AttributionOptions {
+  href?: string;
+  label?: string;
+}
+
+export function attributionScript(options: AttributionOptions = {}): string {
+  const href = JSON.stringify(options.href ?? ATTRIBUTION_URL);
+  const label = JSON.stringify(options.label ?? ATTRIBUTION_LABEL);
+  const css = [
+    ':host{all:initial;position:fixed;right:8px;bottom:8px;z-index:2147483647}',
+    'a{display:inline-flex;align-items:center;gap:6px;padding:4px 10px;border-radius:999px;',
+    'font:500 12px/1.4 system-ui,-apple-system,Segoe UI,sans-serif;text-decoration:none;',
+    'background:rgba(255,255,255,.92);color:#1f2328;border:1px solid rgba(31,35,40,.15);',
+    'box-shadow:0 1px 3px rgba(0,0,0,.12)}',
+    'a:hover{text-decoration:underline}',
+    '@media (prefers-color-scheme:dark){a{background:rgba(22,27,34,.92);color:#e6edf3;border-color:rgba(230,237,243,.18)}}',
+    '@media print{:host{display:none}}',
+  ].join('');
+  return `<script>(function(){
+  if (document.getElementById('bfwc-attribution')) return;
+  var mount = function () {
+    var host = document.createElement('bfwc-attribution');
+    host.id = 'bfwc-attribution';
+    var root = host.attachShadow({ mode: 'closed' });
+    var style = document.createElement('style');
+    style.textContent = ${JSON.stringify(css)};
+    var a = document.createElement('a');
+    a.href = ${href}; a.target = '_blank'; a.rel = 'noopener';
+    a.textContent = ${label};
+    root.appendChild(style); root.appendChild(a);
+    document.body.appendChild(host);
+  };
+  if (document.body) mount(); else addEventListener('DOMContentLoaded', mount);
+})();</script>`;
+}
+
+/** Append the badge before `</body>` (or at the end of a fragment). */
+export function injectAttribution(html: string, options?: AttributionOptions): string {
+  const badge = attributionScript(options);
+  return /<\/body>/i.test(html) ? html.replace(/<\/body>(?![\s\S]*<\/body>)/i, `${badge}\n</body>`) : html + badge;
+}

package/src/compileScript.ts

@@ -0,0 +1,87 @@
+import type { VirtualFileSystem } from './vfs.js';
+import type { ProjectConfig } from './projectConfig.js';
+import type { PackageCdn } from './packageCdn.js';
+import type { Transformer } from './transformer.js';
+import { loaderFor } from './transformer.js';
+import { dirname, extname } from './paths.js';
+import { isBareSpecifier, resolveAlias, resolveLocal, splitPackageSpecifier } from './resolve.js';
+import { rewriteImports } from './rewriteImports.js';
+
+export interface CompileContext {
+  fs: VirtualFileSystem;
+  config: ProjectConfig;
+  cdn: PackageCdn;
+  transformer: Transformer;
+  /** Preview base URL, ending in `/`. */
+  base: string;
+}
+
+/** Vite-style import queries this runtime honours. */
+export type ImportQuery = 'import' | 'raw' | 'url';
+
+/**
+ * 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,
+ * fonts) exports its URL, as in Vite.
+ */
+export function moduleUrl(base: string, path: string, query?: ImportQuery): string {
+  const url = base + path.slice(1);
+  if (query === 'raw' || query === 'url') return `${url}?${query}`;
+  const ext = extname(path);
+  if (loaderFor(ext)) return url;
+  if (ext === '.css' || ext === '.json') return `${url}?import`;
+  return `${url}?url`;
+}
+
+function splitQuery(specifier: string): { path: string; query?: ImportQuery } {
+  const at = specifier.indexOf('?');
+  if (at < 0) return { path: specifier };
+  const query = specifier.slice(at + 1);
+  return { path: specifier.slice(0, at), query: query === 'raw' || query === 'url' ? query : undefined };
+}
+
+/**
+ * Map one import specifier to the URL the browser should fetch. Undefined leaves
+ * it unchanged: URLs, `node:` builtins, and local paths that do not resolve (the
+ * browser's 404 then surfaces through the error bridge).
+ */
+export function mapSpecifier(ctx: CompileContext, fromDir: string, specifier: string): string | undefined {
+  if (/^(https?:|data:|blob:|node:)/i.test(specifier)) return undefined;
+  const { path, query } = splitQuery(specifier);
+
+  if (isBareSpecifier(path)) {
+    const aliased = resolveAlias(ctx.fs, ctx.config.aliases, path);
+    if (aliased) return moduleUrl(ctx.base, aliased, query);
+    const { name, subpath } = splitPackageSpecifier(path);
+    return ctx.cdn.urlFor(name, subpath);
+  }
+  const resolved = resolveLocal(ctx.fs, fromDir, path);
+  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"' };
+  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);
+  }
+  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) ?? '';
+  const { code } = await ctx.transformer.transform(source, {
+    loader,
+    sourcefile: path,
+    define: buildDefine(ctx.config, ctx.base),
+    jsx: ctx.config.jsx,
+  });
+  const fromDir = dirname(path);
+  return rewriteImports(code, (specifier) => mapSpecifier(ctx, fromDir, specifier));
+}

package/src/detectProject.ts

@@ -0,0 +1,66 @@
+import type { VirtualFileSystem } from './vfs.js';
+import { RESOLVE_EXTENSIONS } from './resolve.js';
+
+export type ProjectKind = 'vite' | 'cra' | 'static';
+
+export interface ProjectProfile {
+  supported: boolean;
+  kind?: ProjectKind;
+  /** The HTML document served at `/`. */
+  htmlPath?: string;
+  /** Script injected when the HTML has no module entry of its own (CRA). */
+  entry?: string;
+  /** Files served from the site root, Vite/CRA `public/` convention. */
+  publicDir: string;
+  /** Why the project needs a full Node runtime instead — shown to the user. */
+  reason?: string;
+}
+
+/**
+ * Frameworks that need a server or a compiler this runtime does not have yet.
+ * Data, not branches: supporting one later means deleting its row.
+ */
+const NEEDS_NODE: ReadonlyArray<{ dependency: string; reason: string }> = [
+  { dependency: 'next', reason: 'Next.js needs its Node server.' },
+  { dependency: 'nuxt', reason: 'Nuxt needs its Node server.' },
+  { 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'];
+
+function readDependencyNames(fs: VirtualFileSystem): Set<string> {
+  try {
+    const pkg = JSON.parse(fs.readText('/package.json') ?? '{}') as Record<string, Record<string, string> | undefined>;
+    return new Set([...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})]);
+  } catch {
+    return new Set();
+  }
+}
+
+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;
+  }
+  return undefined;
+}
+
+export function detectProject(fs: VirtualFileSystem): ProjectProfile {
+  const deps = readDependencyNames(fs);
+  const blocker = NEEDS_NODE.find((row) => deps.has(row.dependency));
+  if (blocker) return { supported: false, publicDir: '/public', reason: blocker.reason };
+
+  if (fs.isFile('/index.html')) {
+    return { supported: true, kind: deps.has('vite') ? 'vite' : 'static', 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' };
+  }
+  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.' };
+  }
+  return { supported: false, publicDir: '/public', reason: 'No index.html found at the project root or in public/.' };
+}