@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

package/src/adapters/shared/shared-hmr-manager.js

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { getAppBuildExecutor } from "../../build/build-adapter.js";
+import { fileSystem } from "@ecopages/file-system";
+import { HmrStrategyType } from "../../hmr/hmr-strategy.js";
+import { DefaultHmrStrategy } from "../../hmr/strategies/default-hmr-strategy.js";
+import { JsHmrStrategy } from "../../hmr/strategies/js-hmr-strategy.js";
+import { appLogger } from "../../global/app-logger.js";
+import { HmrEntrypointRegistrar } from "./hmr-entrypoint-registrar.js";
+import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
+import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import {
+  getAppEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
+class SharedHmrManager {
+  appConfig;
+  bridge;
+  watchers = /* @__PURE__ */ new Map();
+  watchedFiles = /* @__PURE__ */ new Map();
+  entrypointRegistrations = /* @__PURE__ */ new Map();
+  distDir;
+  plugins = [];
+  enabled = true;
+  strategies = [];
+  entrypointRegistrar;
+  browserBundleService;
+  entrypointDependencyGraph;
+  serverModuleTranspiler;
+  constructor({ appConfig, bridge, registrationTimeoutMs = 4e3 }) {
+    this.appConfig = appConfig;
+    this.bridge = bridge;
+    this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
+    this.entrypointRegistrar = new HmrEntrypointRegistrar({
+      srcDir: this.appConfig.absolutePaths.srcDir,
+      distDir: this.distDir,
+      entrypointRegistrations: this.entrypointRegistrations,
+      watchedFiles: this.watchedFiles,
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+      registrationTimeoutMs
+    });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+    this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(
+      getAppEntrypointDependencyGraph(appConfig)
+    );
+    setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+    this.ensureDistDir();
+    this.initializeStrategies();
+  }
+  shouldSkipMissingFileChange(_filePath) {
+    return false;
+  }
+  onRuntimeBundleFailure(error) {
+    appLogger.error("[HMR] Failed to build runtime script:", error);
+  }
+  ensureDistDir() {
+    fileSystem.ensureDir(this.distDir);
+  }
+  shouldJsStrategyProcessEntrypoint(entrypointPath) {
+    return !this.strategies.some((strategy) => {
+      if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+        return false;
+      }
+      try {
+        return strategy.matches(entrypointPath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  initializeStrategies() {
+    const jsContext = {
+      getWatchedFiles: () => this.watchedFiles,
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getTemplateExtensions: () => this.appConfig.templatesExt,
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
+    };
+    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+  }
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+  }
+  setPlugins(plugins) {
+    this.plugins = [...plugins];
+  }
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  async buildRuntime() {
+    const runtimeSource = fileURLToPath(import.meta.resolve("@ecopages/core/hmr/client/hmr-runtime"));
+    try {
+      const result = await this.browserBundleService.bundle({
+        profile: "hmr-runtime",
+        entrypoints: [runtimeSource],
+        outdir: this.distDir,
+        naming: "_hmr_runtime.js",
+        minify: false,
+        plugins: this.plugins
+      });
+      if (!result.success) {
+        this.onRuntimeBundleFailure(result.logs);
+      }
+    } catch (error) {
+      this.onRuntimeBundleFailure(error);
+    }
+  }
+  getRuntimePath() {
+    return path.join(this.distDir, "_hmr_runtime.js");
+  }
+  broadcast(event) {
+    appLogger.debug(
+      `[HMR] Broadcasting ${event.type} event, path=${event.path || "all"}, subscribers=${this.bridge.subscriberCount}`
+    );
+    this.bridge.broadcast(event);
+  }
+  async handleFileChange(filePath, options = {}) {
+    if (this.shouldSkipMissingFileChange(filePath) && !fileSystem.exists(filePath)) {
+      appLogger.debug(`[${this.constructor.name}] Skipping missing file change: ${filePath}`);
+      this.clearFailedEntrypointRegistration(filePath);
+      return;
+    }
+    const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
+    const strategy = sorted.find((candidate) => {
+      try {
+        return candidate.matches(filePath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+    if (!strategy) {
+      appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+      return;
+    }
+    appLogger.debug(`[${this.constructor.name}] Selected strategy: ${strategy.constructor.name}`);
+    const action = await strategy.process(filePath);
+    const shouldBroadcast = options.broadcast ?? true;
+    if (shouldBroadcast && action.type === "broadcast" && action.events) {
+      for (const event of action.events) {
+        this.broadcast(event);
+      }
+    }
+  }
+  getOutputUrl(entrypointPath) {
+    return this.watchedFiles.get(entrypointPath);
+  }
+  getWatchedFiles() {
+    return this.watchedFiles;
+  }
+  getDistDir() {
+    return this.distDir;
+  }
+  getPlugins() {
+    return this.plugins;
+  }
+  getDefaultContext() {
+    return {
+      getWatchedFiles: () => this.watchedFiles,
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true
+      })
+    };
+  }
+  clearFailedEntrypointRegistration(entrypointPath) {
+    this.watchedFiles.delete(entrypointPath);
+    this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+  }
+  async registerEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
+        `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
+      )
+    });
+  }
+  async registerScriptEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`)
+    });
+  }
+  async emitStrictEntrypoint(entrypointPath) {
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+  }
+  async emitScriptEntrypoint(entrypointPath, outputPath) {
+    const naming = path.relative(this.distDir, outputPath).split(path.sep).join("/");
+    const buildResult = await this.browserBundleService.bundle({
+      profile: "hmr-entrypoint",
+      entrypoints: [entrypointPath],
+      outdir: this.distDir,
+      naming,
+      minify: false,
+      plugins: this.plugins
+    });
+    if (!buildResult.success) {
+      appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
+      return;
+    }
+    const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
+    if (entrypointDependencies) {
+      this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
+    }
+  }
+  stop() {
+    this.entrypointRegistrations.clear();
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.watchedFiles.clear();
+    this.entrypointDependencyGraph.reset();
+    this.plugins = [];
+  }
+}
+export {
+  SharedHmrManager
+};

package/src/adapters/shared/static-preview-host.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export interface StaticPreviewHost {
+    start(options: StaticPreviewHostStartOptions): Promise<number | null>;
+    stop(force?: boolean): Promise<void>;
+}
+export interface StaticPreviewHostStartOptions {
+    appConfig: EcoPagesAppConfig;
+    hostname: string;
+    port: number;
+}

package/src/build/README.md

@@ -1,101 +1,91 @@
 # Build Layer
 
-This directory contains the runtime-neutral build contract used across Ecopages and the esbuild-backed implementation that currently powers the default fallback adapter.
+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
+## Mental Model
 
-- `build-adapter.ts`: shared build interfaces, result types, app-owned adapter/executor helpers, the exported `defaultBuildAdapter` fallback, and the top-level `build()` / `getTranspileOptions()` pipeline functions.
-- `build-types.ts`: plugin bridge types used by integrations and processors.
-- `esbuild-build-adapter.ts`: the concrete esbuild backend.
-- `dev-build-coordinator.ts`: development-only orchestration around the shared esbuild backend.
-- `*.test.ts`: focused regression coverage for plain builds and development serialization and recovery.
+Three concentric shapes, plus a serializer and a plugin injector:
 
-## Responsibilities
+| 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.                                                                             |
 
-The build layer is intentionally split into two parts.
+Plus one translation bridge:
 
-`BuildExecutor` is the runtime-facing contract.
+- `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.
 
-- It is the narrow facade stored on `appConfig.runtime.buildExecutor`.
-- It answers only how a given app instance should execute builds right now.
-- `EsbuildBuildAdapter` satisfies this contract directly in plain flows.
-- `DevBuildCoordinator` also satisfies this contract by wrapping the shared esbuild adapter with development-only serialization and recovery policy.
+## Files
 
-`EsbuildBuildAdapter` is the backend. It knows how to:
+- `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.
 
-- 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
+## Default Flow
 
-`DevBuildCoordinator` is the development policy layer. It exists because one app/runtime can have many build callers during dev mode, including:
+`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.
 
-- page module imports
-- HMR entrypoint builds
-- script and asset processors
-- React integration build paths
+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:
 
-Those callers must not race each other against one long-lived esbuild worker. The coordinator therefore owns:
+```
+BuildExecutor
+  └─ SerializedBuildExecutor            // FIFO queue
+       └─ withBuildExecutorPlugins       // injects app plugins
+            └─ BuildAdapter (bundled adapter or Vite-host)
+```
 
-- serialized access to the shared adapter in development
-- recycling warm Node-target esbuild sessions between builds
-- recovery from known esbuild worker protocol faults
+Every dev-watch caller reads `appConfig.runtime.buildExecutor` and gets the merged plugin set without further ceremony.
 
-## Default Flow
+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()`.
 
-Each `EcoPagesAppConfig` owns a build adapter, build manifest, and `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.
+## Vite-Host Boundary
 
-When a Node or Bun server adapter starts in watch mode, it replaces that executor with a per-app `DevBuildCoordinator`. Build consumers then either call the executor directly or pass it explicitly to the top-level `build()` helper.
+`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, 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`)
-- callers with app context use that executor explicitly instead of consulting global state
-- tests can still instantiate `EsbuildBuildAdapter` or `DevBuildCoordinator` directly when they want the raw 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-manifest.d.ts

@@ -0,0 +1,31 @@
+export type BrowserRuntimeMode = 'development' | 'production';
+export type BrowserRuntimeAssetDeclaration = {
+    /** Bare or virtual specifier used by authored/generated browser modules. */
+    specifier: string;
+    /** Integration, processor, or core subsystem that owns this runtime asset. */
+    owner: string;
+    /** Source import path used to build or resolve the runtime asset. */
+    importPath: string;
+    /** Concrete browser URL emitted or served for this runtime asset. */
+    publicPath: string;
+    /** Runtime mode this declaration applies to. Omit when the URL is mode-independent. */
+    mode?: BrowserRuntimeMode;
+    /** Specifiers that should be treated as external while building this runtime asset. */
+    externals?: readonly string[];
+};
+export type BrowserRuntimeAsset = BrowserRuntimeAssetDeclaration & {
+    externals: readonly string[];
+};
+export type BrowserRuntimeManifest = {
+    assets: readonly BrowserRuntimeAsset[];
+    bySpecifier: ReadonlyMap<string, BrowserRuntimeAsset>;
+};
+export declare class BrowserRuntimeManifestConflictError extends Error {
+    readonly specifier: string;
+    readonly existing: BrowserRuntimeAsset;
+    readonly incoming: BrowserRuntimeAsset;
+    constructor(specifier: string, existing: BrowserRuntimeAsset, incoming: BrowserRuntimeAsset);
+}
+export declare function createBrowserRuntimeManifest(declarations?: readonly BrowserRuntimeAssetDeclaration[]): BrowserRuntimeManifest;
+export declare function mergeBrowserRuntimeManifests(...manifests: Array<BrowserRuntimeManifest | undefined>): BrowserRuntimeManifest;
+export declare function getBrowserRuntimeSpecifierMap(manifest: BrowserRuntimeManifest): ReadonlyMap<string, string>;

package/src/build/browser-runtime-manifest.js

@@ -0,0 +1,61 @@
+class BrowserRuntimeManifestConflictError extends Error {
+  specifier;
+  existing;
+  incoming;
+  constructor(specifier, existing, incoming) {
+    super(
+      `Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ${incoming.owner} maps to ${incoming.publicPath}`
+    );
+    this.name = "BrowserRuntimeManifestConflictError";
+    this.specifier = specifier;
+    this.existing = existing;
+    this.incoming = incoming;
+  }
+}
+function normalizeDeclaration(declaration) {
+  return {
+    ...declaration,
+    externals: declaration.externals ?? []
+  };
+}
+function hasCompatibleRuntimeAsset(existing, incoming) {
+  return existing.owner === incoming.owner && existing.importPath === incoming.importPath && existing.publicPath === incoming.publicPath && existing.mode === incoming.mode && arrayEquals(existing.externals, incoming.externals);
+}
+function arrayEquals(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  return left.every((value, index) => value === right[index]);
+}
+function createBrowserRuntimeManifest(declarations = []) {
+  const assets = [];
+  const bySpecifier = /* @__PURE__ */ new Map();
+  for (const declaration of declarations) {
+    const asset = normalizeDeclaration(declaration);
+    const existing = bySpecifier.get(asset.specifier);
+    if (existing) {
+      if (!hasCompatibleRuntimeAsset(existing, asset)) {
+        throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
+      }
+      continue;
+    }
+    assets.push(asset);
+    bySpecifier.set(asset.specifier, asset);
+  }
+  return {
+    assets,
+    bySpecifier
+  };
+}
+function mergeBrowserRuntimeManifests(...manifests) {
+  return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
+}
+function getBrowserRuntimeSpecifierMap(manifest) {
+  return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
+}
+export {
+  BrowserRuntimeManifestConflictError,
+  createBrowserRuntimeManifest,
+  getBrowserRuntimeSpecifierMap,
+  mergeBrowserRuntimeManifests
+};

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;