@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.55

package/README.md

@@ -67,11 +67,11 @@ The manager/orchestration layer is core-owned, but framework-specific strategies
 
 ### Practical Summary
 
-- `ConfigBuilder` now seeds one app-owned build ownership path, adapter, manifest, executor, dev graph, and runtime registry.
+- `ConfigBuilder` seeds one app-owned build ownership path, adapter, manifest, executor, dev graph, and runtime registry.
 - `BrowserBundleService` is the shared browser build seam used by HMR and asset-oriented browser output paths.
 - `ServerModuleTranspiler` is the shared server-side source loading seam used by runtime bootstrap and HMR metadata loading.
 - `createApp()` stays the universal runtime entrypoint, while Vite and Nitro hosts own their advanced dev and build workflows.
-- esbuild remains only as a temporary Bun-path implementation detail and is not a strategic core dependency.
+- One bundled adapter is the default bundler. Vite-based apps route through the `ViteHostBuildAdapter` boundary marker instead.
 
 ## Documentation Map
 
@@ -279,7 +279,6 @@ Use these entrypoints only when implementing host adapters or framework-owned bu
 - `@ecopages/core/dev/host-runtime`
 - `@ecopages/core/build/build-adapter`
 - `@ecopages/core/build/build-types`
-- `@ecopages/core/build/runtime-specifier-alias-plugin`
 - `@ecopages/core/plugins/foreign-jsx-override-plugin`
 
 These host-facing entrypoints are narrower compatibility seams. App code and most extensions should prefer the app-authoring or extension-authoring surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.53",
+  "version": "0.2.0-alpha.55",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,14 +17,16 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.53",
+    "@ecopages/file-system": "0.2.0-alpha.55",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
+    "@oxc-project/runtime": "0.134.0",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
     "chokidar": "^5.0.0",
     "esbuild": "^0.28.0",
     "ghtml": "^4.0.2",
     "oxc-parser": "^0.124.0",
+    "rolldown": "^1.1.0",
     "ws": "^8.20.1"
   },
   "exports": {
@@ -115,17 +117,21 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/runtime-build-output-normalizer": {
+      "types": "./src/build/runtime-build-output-normalizer.d.ts",
+      "default": "./src/build/runtime-build-output-normalizer.js"
+    },
     "./build/browser-runtime-manifest": {
       "types": "./src/build/browser-runtime-manifest.d.ts",
       "default": "./src/build/browser-runtime-manifest.js"
     },
-    "./build/browser-runtime-import-rewrite-plugin": {
-      "types": "./src/build/browser-runtime-import-rewrite-plugin.d.ts",
-      "default": "./src/build/browser-runtime-import-rewrite-plugin.js"
+    "./build/browser-runtime-plugin": {
+      "types": "./src/build/browser-runtime-plugin.d.ts",
+      "default": "./src/build/browser-runtime-plugin.js"
     },
-    "./build/runtime-specifier-alias-plugin": {
-      "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
-      "default": "./src/build/runtime-specifier-alias-plugin.js"
+    "./cache": {
+      "types": "./src/cache/index.d.ts",
+      "default": "./src/cache/index.js"
     },
     "./plugins/foreign-jsx-override-plugin": {
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
@@ -141,6 +147,11 @@
       "default": "./src/utils/hash.js",
       "types": "./src/utils/hash.d.ts"
     },
+    "./utils/hash": {
+      "import": "./src/utils/hash.js",
+      "default": "./src/utils/hash.js",
+      "types": "./src/utils/hash.d.ts"
+    },
     "./errors": {
       "types": "./src/errors/index.d.ts",
       "default": "./src/errors/index.js"
@@ -230,17 +241,21 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/runtime-build-output-normalizer.ts": {
+      "types": "./src/build/runtime-build-output-normalizer.d.ts",
+      "default": "./src/build/runtime-build-output-normalizer.js"
+    },
     "./build/browser-runtime-manifest.ts": {
       "types": "./src/build/browser-runtime-manifest.d.ts",
       "default": "./src/build/browser-runtime-manifest.js"
     },
-    "./build/browser-runtime-import-rewrite-plugin.ts": {
-      "types": "./src/build/browser-runtime-import-rewrite-plugin.d.ts",
-      "default": "./src/build/browser-runtime-import-rewrite-plugin.js"
+    "./build/browser-runtime-plugin.ts": {
+      "types": "./src/build/browser-runtime-plugin.d.ts",
+      "default": "./src/build/browser-runtime-plugin.js"
     },
-    "./build/runtime-specifier-alias-plugin.ts": {
-      "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
-      "default": "./src/build/runtime-specifier-alias-plugin.js"
+    "./cache.ts": {
+      "types": "./src/cache/index.d.ts",
+      "default": "./src/cache/index.js"
     },
     "./plugins/foreign-jsx-override-plugin.ts": {
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
@@ -256,6 +271,11 @@
       "default": "./src/utils/hash.js",
       "types": "./src/utils/hash.d.ts"
     },
+    "./utils/hash.ts": {
+      "import": "./src/utils/hash.js",
+      "default": "./src/utils/hash.js",
+      "types": "./src/utils/hash.d.ts"
+    },
     "./errors.ts": {
       "types": "./src/errors/index.d.ts",
       "default": "./src/errors/index.js"

package/src/adapters/bun/server-adapter.d.ts

@@ -186,6 +186,13 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     createAdapter(): Promise<BunServerAdapterResult>;
     /**
      * Handles HTTP requests by passing them securely to the shared core router adapter.
+     *
+     * @remarks
+     * Filesystem page responses are wrapped by `ServerRouteHandler`. This
+     * adapter-level pass only covers HTML returned by explicit API handlers,
+     * which bypass that route-layer wrapper and would otherwise miss the
+     * dev HMR runtime — so the HMR script injection happens here, after
+     * the shared handler runs.
      */
     handleRequest(request: Request): Promise<Response>;
     /**

package/src/adapters/bun/server-adapter.js

@@ -91,9 +91,7 @@ class BunServerAdapter extends SharedServerAdapter {
    * Initializes the server adapter's core runtime components.
    */
   async initialize() {
-    installAppRuntimeBuildExecutor(this.appConfig, {
-      development: this.options?.watch === true
-    });
+    installAppRuntimeBuildExecutor(this.appConfig);
     this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
     await this.hmrManager.buildRuntime();
     this.prepareRuntimePublicDir();
@@ -387,6 +385,13 @@ class BunServerAdapter extends SharedServerAdapter {
   }
   /**
    * Handles HTTP requests by passing them securely to the shared core router adapter.
+   *
+   * @remarks
+   * Filesystem page responses are wrapped by `ServerRouteHandler`. This
+   * adapter-level pass only covers HTML returned by explicit API handlers,
+   * which bypass that route-layer wrapper and would otherwise miss the
+   * dev HMR runtime — so the HMR script injection happens here, after
+   * the shared handler runs.
    */
   async handleRequest(request) {
     const response = await this.handleSharedRequest(request, {

package/src/adapters/node/server-adapter.d.ts

@@ -118,7 +118,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      *   `upgrade` event (no separate port needed).
      * - `NodeClientBridge` tracks active WebSocket connections and handles
      *   broadcast + heartbeat cleanup.
-     * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
+     * - `NodeHmrManager` watches the filesystem and triggers incremental
      *   rebuilds, notifying connected clients via the bridge.
      * - Shared watcher bootstrapping listens for route-level file changes and
      *   refreshes the router and response handlers when pages are added or removed.

package/src/adapters/node/server-adapter.js

@@ -67,9 +67,7 @@ class NodeServerAdapter extends SharedServerAdapter {
    *    processors during their `setup()` calls.
    */
   async initialize() {
-    installAppRuntimeBuildExecutor(this.appConfig, {
-      development: this.options?.watch === true
-    });
+    installAppRuntimeBuildExecutor(this.appConfig);
     this.prepareRuntimePublicDir();
     await setupAppRuntimePlugins({
       appConfig: this.appConfig,
@@ -241,7 +239,7 @@ class NodeServerAdapter extends SharedServerAdapter {
    *   `upgrade` event (no separate port needed).
    * - `NodeClientBridge` tracks active WebSocket connections and handles
    *   broadcast + heartbeat cleanup.
-   * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
+   * - `NodeHmrManager` watches the filesystem and triggers incremental
    *   rebuilds, notifying connected clients via the bridge.
    * - Shared watcher bootstrapping listens for route-level file changes and
    *   refreshes the router and response handlers when pages are added or removed.

package/src/build/README.md

@@ -1,107 +1,91 @@
 # Build Layer
 
-This directory contains the runtime-neutral build contract used across Ecopages, the Bun-native adapter that currently uses esbuild under the hood, and the explicit host-owned Vite compatibility boundary.
+The build layer is the bundler contract for Ecopages. One bundled adapter is the default; one host-owned boundary marker covers the Vite-host path.
 
-## Files
-
-- `build-adapter.ts`: shared build interfaces, explicit Bun-native versus Vite-host ownership helpers, app-owned adapter/executor helpers, and compatibility fallback helpers for older Bun-native call paths.
-- `build-types.ts`: plugin bridge types used by integrations and processors.
-- `esbuild-build-adapter.ts`: the concrete Bun-native adapter implementation. It is compatibility infrastructure, not strategic architecture.
-- `dev-build-coordinator.ts`: development-only orchestration around the temporary Bun-native esbuild backend.
-- `*.test.ts`: focused regression coverage for plain builds and development serialization and recovery.
-
-## Responsibilities
+## Mental Model
 
-The build layer is intentionally split into two parts.
+Three concentric shapes, plus a serializer and a plugin injector:
 
-`BuildExecutor` is the runtime-facing contract.
+| Shape                      | Lives in                       | Purpose                                                                                                                                                             |
+| -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BuildAdapter`             | `build-adapter.ts`             | Low-level backend. Two implementations: the bundled adapter (the real bundler) and `ViteHostBuildAdapter` (a host-owned boundary marker that throws on direct use). |
+| `BuildExecutor`            | `build-adapter.ts`             | Narrower runtime facade. Only `build` is exposed. Stored on `appConfig.runtime.buildExecutor`.                                                                      |
+| `SerializedBuildExecutor`  | `serialized-build-executor.ts` | FIFO queue around any `BuildExecutor`. Used by the dev watch pipeline.                                                                                              |
+| `withBuildExecutorPlugins` | `build-adapter.ts`             | Merges app-owned plugins into every `build` call. The single point of plugin injection.                                                                             |
 
-- It is the narrow facade stored on `appConfig.runtime.buildExecutor`.
-- It answers only how a given app instance should execute builds right now.
-- the Bun-native adapter satisfies this contract directly in plain flows.
-- `DevBuildCoordinator` also satisfies this contract by wrapping the temporary Bun-native esbuild adapter with development-only serialization and recovery policy.
+Plus one translation bridge:
 
-`EsbuildBuildAdapter` is the current Bun-native backend. It knows how to:
+- `rolldown-plugin-bridge.ts` — converts the runtime-agnostic `EcoBuildPlugin[]` array (the contract integrations and processors register) into the bundler's native `Plugin` array. Each `EcoBuildPlugin` becomes its own plugin entry to preserve plugin-priority order.
 
-- load the esbuild module
-- translate Ecopages `BuildOptions` into esbuild options
-- bridge Ecopages build plugins into esbuild hooks
-- normalize build output, logs, and dependency graph metadata
-- detect the subset of runtime faults that mean the esbuild worker protocol is corrupted
-
-`ViteHostBuildAdapter` is a boundary marker, not a real backend. It exists so app/runtime state can represent that Vite owns host-side build execution instead of silently falling back to a framework-owned esbuild path.
+## Files
 
-`DevBuildCoordinator` is the development policy layer. It exists because one app/runtime can have many build callers during dev mode, including:
+- `build-adapter.ts`: types, factories, app-owned helpers, `withBuildExecutorPlugins`.
+- `build-types.ts`: the `EcoBuildPlugin` contract used by integrations and processors.
+- `rolldown-build-adapter.ts`: the production `BuildAdapter`. Wraps the bundler and exposes a normalized `BuildResult` (outputs, dependency graph, logs).
+- `rolldown-plugin-bridge.ts`: `EcoBuildPlugin[]` → bundler-plugin translation.
+- `serialized-build-executor.ts`: FIFO queue primitive.
+- `runtime-build-executor.ts`: dev-watch entrypoint that wraps the app-owned adapter in a `SerializedBuildExecutor + withBuildExecutorPlugins` chain.
+- `*.test.ts`: regression coverage.
 
-- page module imports
-- HMR entrypoint builds
-- script and asset processors
-- React integration build paths
+## Default Flow
 
-Those callers must not race each other against one long-lived esbuild worker. The coordinator therefore owns temporary compatibility policy for the Bun-native path:
+`ConfigBuilder.build()` creates one app-owned adapter, manifest, executor, dev graph, and runtime registry. The executor it stores is the raw `BuildAdapter`; the plugin-wrap step lives in the runtime path.
 
-- serialized access to the shared adapter in development
-- recycling warm Node-target esbuild sessions between builds
-- recovery from known esbuild worker protocol faults
+When a server adapter initializes, it calls `installAppRuntimeBuildExecutor(appConfig)`. That function reads the existing executor (or falls back to the app-owned adapter) and stores a fresh wrapper:
 
-## Default Flow
+```
+BuildExecutor
+  └─ SerializedBuildExecutor            // FIFO queue
+       └─ withBuildExecutorPlugins       // injects app plugins
+            └─ BuildAdapter (bundled adapter or Vite-host)
+```
 
-Each `EcoPagesAppConfig` owns explicit build ownership, a build adapter, a build manifest, and a `buildExecutor` in `appConfig.runtime`. `ConfigBuilder.build()` now creates that app-owned build state up front so later runtime startup can reuse it rather than mutating a shared adapter.
+Every dev-watch caller reads `appConfig.runtime.buildExecutor` and gets the merged plugin set without further ceremony.
 
-When a Bun server adapter starts in watch mode, it replaces that executor with a per-app `DevBuildCoordinator`. Vite-hosted flows should not use that coordinator; the host owns watch, graph, and HMR policy there. Build consumers then either call the executor directly or pass it explicitly to the top-level `build()` helper.
+The exported `defaultBuildAdapter` and the top-level `build()` / `getTranspileOptions()` helpers are non-app-aware escape hatches. New runtime code should prefer `getAppBuildAdapter()`, `getAppBuildExecutor()`, and `getAppTranspileOptions()`.
 
-The exported `defaultBuildAdapter` and top-level `getTranspileOptions()` helper are compatibility fallbacks only. New runtime code should prefer app-owned access through `getAppBuildAdapter()`, `getAppBuildExecutor()`, and `getAppTranspileOptions()`.
+## Vite-Host Boundary
 
-The same rule applies to source-module loading: host-owned import behavior must be injected through abstract runtime state rather than imported directly into core services.
+`ViteHostBuildAdapter` is not a real backend. It exists so `appConfig.runtime.buildAdapter` can carry the `'vite-host'` ownership without falling back to a framework-owned bundler path. Every method throws a clear `Vite-hosted builds are owned by the host runtime. Core cannot …` error so misrouted calls fail loudly.
 
-Plugins are part of app-owned manifest or per-build input now. The source build contract no longer exposes adapter-level plugin registration, which keeps build composition scoped to an app/runtime instance instead of leaking across instances.
+Vite-based apps (or any future host runtime) should:
 
-HMR callers follow the same ownership model. Integration-specific runtime aliasing stays with the integration that owns those specifiers, rather than in generic core HMR bundling.
+1. Construct a `ViteHostBuildAdapter` via `createViteHostBuildAdapter()` and install it on the app config with `setAppBuildAdapter`.
+2. Run their own build pipeline outside the core.
+3. Reuse the core's `BuildExecutor`-shaped surface where possible so call-sites stay backend-neutral.
 
-## Orchestration Diagram
+## Plugin Authoring
 
-```mermaid
-flowchart TD
-    Config["ConfigBuilder.build()"] --> DefaultExec["appConfig.runtime.buildExecutor = createAppBuildExecutor(app adapter, manifest)"]
-    Adapter["Server adapter initialize() in watch mode"] --> DevExec["appConfig.runtime.buildExecutor = DevBuildCoordinator"]
-    Caller["Any build caller with app/runtime context"] --> Build["executor.build(options) or build(options, executor)"]
-    Build --> Executor["BuildExecutor"]
-    Executor --> Coordinator["DevBuildCoordinator.build()"]
-    Coordinator --> Backend["EsbuildBuildAdapter.buildOrThrow()"]
-    Executor -->|plain flow| Direct["EsbuildBuildAdapter.build()"]
-    Backend --> Result["BuildResult"]
-    Direct --> Result["BuildResult"]
-    Result --> Browser["Browser consumes emitted bundle directly"]
-```
+`EcoBuildPlugin` is the runtime-agnostic contract integrations and processors register. The shape:
 
-## Recovery Model
+- `name: string`
+- `setup(build: EcoBuildPluginBuilder): void | Promise<void>`
 
-The recovery path is narrow on purpose. The coordinator only treats an error as recoverable when `EsbuildBuildAdapter.isEsbuildProtocolError()` matches one of the known worker-protocol failure signatures.
+`EcoBuildPluginBuilder` exposes three hooks:
 
-When that happens, recovery does three things in order:
+- `onResolve({ filter, namespace? }, callback)` — the bundler's `resolveId` mapped to the shared plugin shape.
+- `onLoad({ filter, namespace? }, callback)` — the bundler's `load` mapped the same way.
+- `module(specifier, callback)` — declares a virtual module by name, with bundler-side namespace encoding.
 
-1. Reset the serialized queue so future builds are not stuck behind a wedged promise.
-2. Stop the current esbuild service instance.
-3. Increment the esbuild module generation so the next import gets a fresh worker instance.
+Namespace handling: the shared plugin contract scopes handlers with a `namespace` string; the bundler encodes namespaces into the module id. The bridge prepends `<namespace>:` to resolved ids and matches filters against that prefix, then strips it before forwarding back to callbacks. Plugin code keeps the same `path` shape it had on the shared contract.
 
-After that reset, the coordinator retries the failed build once.
+Plugin ordering: the bundler's `resolveId` and `load` are "first" hooks. The bridge translates each `EcoBuildPlugin` into its own plugin and preserves the array order, so position determines priority: index 0 wins first, the last index is the lowest priority. Security-critical plugins (e.g. `ecopages-client-graph-boundary`) should be placed before general-purpose loaders in the array.
 
-## Why Explicit App Ownership
+## BuildOptions Caveats
 
-There are many build callsites across core and integrations. The coordinator still needs to stay centralized for the remaining Bun-native compatibility path, but process-global installation hid the real dependency and tied behavior to startup order.
+`BuildOptions` is modeled on the bundler's options shape. Most fields map cleanly. The exceptions:
 
-The explicit app-owned executor model keeps the design honest:
+- `splitting` — accepted but currently ignored. The bundler splits by default. The per-chunk naming is fixed to `[name]-[hash]`. If you need to disable splitting or rename chunks, the adapter will need a new option.
+- `bundle` — accepted but ignored. The bundler always bundles.
+- `outbase` — accepted but ignored. The adapter derives the base from `options.root` directly.
 
-- each app/runtime owns its own build executor
-- development policy stays in one place (`DevBuildCoordinator`) for the remaining Bun-native path only
-- callers with app context use that executor explicitly instead of consulting global state
-- tests can still instantiate `EsbuildBuildAdapter`, `ViteHostBuildAdapter`, or `DevBuildCoordinator` directly when they want the raw ownership boundary or compatibility backend only
+These fields are kept in the type so existing call-sites compile. The proper fix is a more focused `BuildOptions` schema in a follow-up.
 
 ## Testing Strategy
 
-The build tests are split by concern.
-
-- `build-adapter.test.ts` verifies plain backend behavior and plugin bridging.
-- `build-adapter-serialization.test.ts` verifies development orchestration behavior such as serialization, warm-session recycling, and protocol-fault recovery.
+- `rolldown-build-adapter.test.ts` covers the adapter's `build`, `resolve`, `getTranspileOptions`, and dependency-graph extraction end-to-end.
+- `rolldown-plugin-bridge.test.ts` covers the `EcoBuildPlugin[]` → plugin translation in isolation.
+- `build-adapter.test.ts` covers the app-owned helpers, the `BuildOwnership` routing, the `withBuildExecutorPlugins` injection, and the default-fallback behaviour.
+- `runtime-build-executor.test.ts` covers the dev-watch wrapper: serialization, plugin injection, and the Vite-host rejection path.
 
-If you change the build orchestration rules, update the coordinator tests first. If you change esbuild option mapping or plugin behavior, update the backend tests first.
+If you change option mapping or plugin-bridge semantics, update the adapter and bridge tests first. If you change the app-owned helper contracts, update `build-adapter.test.ts` first.

package/src/build/browser-runtime-plugin-helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared helpers for the browser-runtime plugin.
+ *
+ * @remarks
+ * `createBrowserRuntimePlugin` needs to:
+ *
+ * 1. Escape each specifier for inclusion in a regex filter.
+ * 2. Build a `RegExp` whose alternation matches any of those specifiers.
+ *
+ * These utilities are extracted here so the plugin does not duplicate
+ * the same code path.
+ */
+/**
+ * Escapes a literal specifier for inclusion in a regular expression.
+ *
+ * Only the regex metacharacters are escaped: `. * + ? ^ $ { } ( ) | [ ] \`
+ */
+export declare function escapeRegExp(value: string): string;
+/**
+ * Builds a `RegExp` whose alternation matches any of the keys in
+ * `specifierMap`.
+ *
+ * Returns `null` for an empty map so callers can short-circuit and
+ * avoid registering a no-op `onResolve` / `onLoad` filter.
+ */
+export declare function buildSpecifierFilter(specifierMap: ReadonlyMap<string, string>): RegExp | null;

package/src/build/browser-runtime-plugin-helpers.js

@@ -0,0 +1,14 @@
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildSpecifierFilter(specifierMap) {
+  if (specifierMap.size === 0) {
+    return null;
+  }
+  const alternation = Array.from(specifierMap.keys()).map(escapeRegExp).join("|");
+  return new RegExp(`^(${alternation})$`);
+}
+export {
+  buildSpecifierFilter,
+  escapeRegExp
+};

package/src/build/browser-runtime-plugin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Unified browser-runtime plugin factory.
+ *
+ * @remarks
+ * Single factory that exposes the union of behaviors for the browser
+ * runtime:
+ *
+ * - `onResolve` for manifest specifiers → mapped public URL, marked external
+ * - `onResolve` for paths starting with `/` whose target is in the manifest's
+ *   public path set → marked external
+ * - `onLoad` for JS/TS files → AST-walking import/export rewrite against the
+ *   manifest specifier set, with a `code.includes(specifier)` fast path
+ *
+ * The plugin object carries the manifest's `specifier → publicPath` map
+ * under `BROWSER_RUNTIME_IMPORT_REWRITE_MAP` so
+ * `collectBrowserRuntimeImportRewriteMap` and the post-build rewriter can
+ * read it without re-walking the manifest.
+ *
+ * This is the single source of truth for browser-runtime plugin behavior.
+ * Per-bundler bridges can treat it as a single plugin.
+ */
+import type { EcoBuildPlugin } from './build-types.js';
+import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
+/**
+ * Symbol used to attach the manifest's `specifier → publicPath` map to a
+ * plugin instance. Consumers read it via `getBrowserRuntimeImportRewriteMap`
+ * or `collectBrowserRuntimeImportRewriteMap`.
+ */
+export declare const BROWSER_RUNTIME_IMPORT_REWRITE_MAP: unique symbol;
+/**
+ * Default name used by `createBrowserRuntimePlugin` when the caller
+ * does not provide one.
+ */
+export declare const DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME = "browser-runtime-plugin";
+export type CreateBrowserRuntimePluginOptions = {
+    /** Manifest whose specifier → publicPath entries drive the plugin. */
+    manifest: BrowserRuntimeManifest;
+    /** Stable build plugin name used for deduplication and selective exclusion. */
+    name?: string;
+    /**
+     * Whether alias `onResolve` results should be marked `external`.
+     * Default `true`. Pass `false` to let the bundler try to bundle the
+     * mapped URL.
+     */
+    external?: boolean;
+    /**
+     * Enable source-level AST import/export rewrite via the `onLoad`
+     * hook. Default `true`. Set `false` for alias-only consumers
+     * (e.g. `react`/`react-dom` externals in vendor assets).
+     */
+    rewriteImports?: boolean;
+    /**
+     * Register an `onResolve` for paths starting with `/` whose target
+     * is in the manifest's public path set. Marks them external so the
+     * bundler does not try to resolve them as source modules. Default
+     * `true`.
+     */
+    matchPublicPaths?: boolean;
+};
+/**
+ * Rewrites static ESM import/export specifiers and string-literal dynamic imports
+ * from manifest-owned runtime specifiers to concrete browser public URLs.
+ *
+ * Exposed for the post-build rewriter and for tests.
+ */
+export declare function rewriteBrowserRuntimeImports(code: string, specifierMap: ReadonlyMap<string, string>, filePath?: string): string;
+export declare function getBrowserRuntimeImportRewriteMap(plugin: EcoBuildPlugin): ReadonlyMap<string, string> | undefined;
+export declare function collectBrowserRuntimeImportRewriteMap(plugins: EcoBuildPlugin[] | undefined): ReadonlyMap<string, string>;
+/**
+ * Creates a build plugin that exposes the union of browser-runtime
+ * manifest behaviors (alias resolution, public-path matching, and source
+ * import/export rewrite). See {@link CreateBrowserRuntimePluginOptions}
+ * for per-behavior toggles.
+ *
+ * Returns `null` for an empty manifest so callers can short-circuit
+ * registration without sprinkling `if (plugin)` everywhere.
+ */
+export declare function createBrowserRuntimePlugin(options: CreateBrowserRuntimePluginOptions): EcoBuildPlugin | null;

package/src/build/{browser-runtime-import-rewrite-plugin.js → browser-runtime-plugin.js}

@@ -1,9 +1,10 @@
 import path from "node:path";
 import { existsSync, readFileSync } from "node:fs";
-import { parseSync } from "oxc-parser";
+import { cachedParseSync } from "../cache/module-parse-cache.js";
 import { getBrowserRuntimeSpecifierMap } from "./browser-runtime-manifest.js";
+import { buildSpecifierFilter } from "./browser-runtime-plugin-helpers.js";
 const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = /* @__PURE__ */ Symbol.for("ecopages.browserRuntimeImportRewriteMap");
-const DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME = "browser-runtime-import-rewrite";
+const DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME = "browser-runtime-plugin";
 function isRecord(value) {
   return Boolean(value) && typeof value === "object";
 }
@@ -22,9 +23,6 @@ function inferLoaderFromPath(filePath) {
       return "js";
   }
 }
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function queueReplacement(options) {
   if (!isRecord(options.source) || typeof options.source.value !== "string") {
     return;
@@ -46,7 +44,7 @@ function rewriteBrowserRuntimeImports(code, specifierMap, filePath = "browser-ru
   }
   const edits = [];
   try {
-    const result = parseSync(filePath, code, {
+    const result = cachedParseSync(filePath, code, {
       sourceType: "module",
       lang: path.extname(filePath).endsWith("x") ? "tsx" : "ts"
     });
@@ -104,15 +102,19 @@ function collectBrowserRuntimeImportRewriteMap(plugins) {
   }
   return merged;
 }
-function createBrowserRuntimeImportRewritePlugin(options) {
-  const specifierMap = getBrowserRuntimeSpecifierMap(options.manifest);
-  const publicPathSet = new Set(specifierMap.values());
-  const specifierFilter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join("|")})$`);
-  if (specifierMap.size === 0) {
+function createBrowserRuntimePlugin(options) {
+  const { manifest } = options;
+  const specifierMap = getBrowserRuntimeSpecifierMap(manifest);
+  const specifierFilter = buildSpecifierFilter(specifierMap);
+  if (!specifierFilter) {
     return null;
   }
+  const external = options.external ?? true;
+  const rewriteImports = options.rewriteImports ?? true;
+  const matchPublicPaths = options.matchPublicPaths ?? true;
+  const publicPathSet = new Set(specifierMap.values());
   const plugin = {
-    name: options.name ?? DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME,
+    name: options.name ?? DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
     setup(build) {
       build.onResolve({ filter: specifierFilter }, (args) => {
         const mappedPath = specifierMap.get(args.path);
@@ -121,45 +123,50 @@ function createBrowserRuntimeImportRewritePlugin(options) {
         }
         return {
           path: mappedPath,
-          external: true
-        };
-      });
-      build.onResolve({ filter: /^\// }, (args) => {
-        if (!publicPathSet.has(args.path)) {
-          return void 0;
-        }
-        return {
-          path: args.path,
-          external: true
-        };
-      });
-      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
-        if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
-          return void 0;
-        }
-        const code = readFileSync(args.path, "utf-8");
-        if (!Array.from(specifierMap.keys()).some((specifier) => code.includes(specifier))) {
-          return void 0;
-        }
-        const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
-        if (rewritten === code) {
-          return void 0;
-        }
-        return {
-          contents: rewritten,
-          loader: inferLoaderFromPath(args.path),
-          resolveDir: path.dirname(args.path)
+          external
         };
       });
+      if (matchPublicPaths) {
+        build.onResolve({ filter: /^\// }, (args) => {
+          if (!publicPathSet.has(args.path)) {
+            return void 0;
+          }
+          return {
+            path: args.path,
+            external: true
+          };
+        });
+      }
+      if (rewriteImports) {
+        build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
+          if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
+            return void 0;
+          }
+          const code = readFileSync(args.path, "utf-8");
+          if (!Array.from(specifierMap.keys()).some((specifier) => code.includes(specifier))) {
+            return void 0;
+          }
+          const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
+          if (rewritten === code) {
+            return void 0;
+          }
+          return {
+            contents: rewritten,
+            loader: inferLoaderFromPath(args.path),
+            resolveDir: path.dirname(args.path)
+          };
+        });
+      }
     }
   };
   plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP] = specifierMap;
   return plugin;
 }
 export {
-  DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME,
+  BROWSER_RUNTIME_IMPORT_REWRITE_MAP,
+  DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
   collectBrowserRuntimeImportRewriteMap,
-  createBrowserRuntimeImportRewritePlugin,
+  createBrowserRuntimePlugin,
   getBrowserRuntimeImportRewriteMap,
   rewriteBrowserRuntimeImports
 };