@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/adapters/shared/server-static-builder.js

@@ -1,13 +1,64 @@
-import { StaticContentServer } from "../../dev/sc-server";
-import { appLogger } from "../../global/app-logger";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { StaticContentServer } from "../../dev/sc-server.js";
+import { appLogger } from "../../global/app-logger.js";
 class ServerStaticBuilder {
   appConfig;
   staticSiteGenerator;
   serveOptions;
-  constructor({ appConfig, staticSiteGenerator, serveOptions }) {
+  apiHandlers;
+  logger;
+  previewServerFactory;
+  constructor({
+    appConfig,
+    staticSiteGenerator,
+    serveOptions,
+    apiHandlers,
+    logger,
+    previewServerFactory
+  }) {
     this.appConfig = appConfig;
     this.staticSiteGenerator = staticSiteGenerator;
     this.serveOptions = serveOptions;
+    this.apiHandlers = apiHandlers ?? [];
+    this.logger = logger ?? appLogger;
+    this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+  }
+  warnApiHandlersUnavailableInStaticMode() {
+    if (this.apiHandlers.length === 0) {
+      return;
+    }
+    const uniqueHandlers = Array.from(
+      new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`))
+    );
+    const visibleHandlers = uniqueHandlers.slice(0, 5).join(", ");
+    const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
+    const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
+    this.logger.warn(
+      "Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n",
+      `\u27A4 ${summary}`
+    );
+  }
+  prepareExportDirectory() {
+    const exportDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+    fileSystem.ensureDir(exportDir, true);
+    const srcPublicDir = path.join(
+      this.appConfig.rootDir,
+      this.appConfig.srcDir ?? "src",
+      this.appConfig.publicDir ?? "public"
+    );
+    if (fileSystem.exists(srcPublicDir)) {
+      fileSystem.copyDir(srcPublicDir, exportDir);
+    }
+  }
+  async refreshRuntimeAssets() {
+    for (const processor of this.appConfig.processors.values()) {
+      await processor.setup();
+    }
+    for (const integration of this.appConfig.integrations) {
+      await integration.setup();
+    }
   }
   /**
    * Generates a static build of the site for deployment.
@@ -17,8 +68,11 @@ class ServerStaticBuilder {
    * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
    */
   async build(options, dependencies) {
-    const { preview = false } = options ?? {};
-    const baseUrl = `http://${this.serveOptions.hostname || "localhost"}:${this.serveOptions.port || 3e3}`;
+    const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+    const baseUrl = explicitBaseUrl ?? `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+    this.warnApiHandlersUnavailableInStaticMode();
+    this.prepareExportDirectory();
+    await this.refreshRuntimeAssets();
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,
@@ -26,18 +80,18 @@ class ServerStaticBuilder {
       staticRoutes: dependencies.staticRoutes
     });
     if (!preview) {
-      appLogger.info("Build completed");
+      this.logger.info("Build completed");
       return;
     }
-    const previewPort = this.serveOptions.port || 3e3;
-    const { server } = StaticContentServer.createServer({
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
+    const { server } = this.previewServerFactory.createServer({
       appConfig: this.appConfig,
       options: { port: Number(previewPort) }
     });
-    if (server) {
-      appLogger.info(`Preview running at http://localhost:${server.port}`);
+    if (server?.port) {
+      this.logger.info(`Preview running at http://localhost:${server.port}`);
     } else {
-      appLogger.error("Failed to start preview server");
+      this.logger.error("Failed to start preview server");
     }
   }
 }

package/src/adapters/shared/shared-hmr-manager.d.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import { type HmrStrategy } from '../../hmr/hmr-strategy.js';
+import type { ClientBridgeEvent } from '../../types/public-types.js';
+import { HmrEntrypointRegistrar } from './hmr-entrypoint-registrar.js';
+import { BrowserBundleService } from '../../services/assets/browser-bundle.service.js';
+import { type EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service.js';
+type HandleFileChangeOptions = {
+    broadcast?: boolean;
+};
+type SharedHmrManagerParams = {
+    appConfig: EcoPagesAppConfig;
+    bridge: IClientBridge;
+    registrationTimeoutMs?: number;
+};
+export declare abstract class SharedHmrManager implements IHmrManager {
+    readonly appConfig: EcoPagesAppConfig;
+    protected readonly bridge: IClientBridge;
+    protected watchers: Map<string, fs.FSWatcher>;
+    protected watchedFiles: Map<string, string>;
+    protected entrypointRegistrations: Map<string, Promise<string>>;
+    protected distDir: string;
+    protected plugins: EcoBuildPlugin[];
+    protected enabled: boolean;
+    protected strategies: HmrStrategy[];
+    protected readonly entrypointRegistrar: HmrEntrypointRegistrar;
+    protected readonly browserBundleService: BrowserBundleService;
+    protected readonly entrypointDependencyGraph: EntrypointDependencyGraph;
+    protected readonly serverModuleTranspiler: ServerModuleTranspiler;
+    constructor({ appConfig, bridge, registrationTimeoutMs }: SharedHmrManagerParams);
+    protected abstract createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): EntrypointDependencyGraph;
+    protected shouldSkipMissingFileChange(_filePath: string): boolean;
+    protected onRuntimeBundleFailure(error: unknown): void;
+    protected ensureDistDir(): void;
+    protected shouldJsStrategyProcessEntrypoint(entrypointPath: string): boolean;
+    protected initializeStrategies(): void;
+    registerStrategy(strategy: HmrStrategy): void;
+    setPlugins(plugins: EcoBuildPlugin[]): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    buildRuntime(): Promise<void>;
+    getRuntimePath(): string;
+    broadcast(event: ClientBridgeEvent): void;
+    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
+    getOutputUrl(entrypointPath: string): string | undefined;
+    getWatchedFiles(): Map<string, string>;
+    getDistDir(): string;
+    getPlugins(): EcoBuildPlugin[];
+    getDefaultContext(): DefaultHmrContext;
+    protected clearFailedEntrypointRegistration(entrypointPath: string): void;
+    registerEntrypoint(entrypointPath: string): Promise<string>;
+    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    protected emitStrictEntrypoint(entrypointPath: string): Promise<void>;
+    protected emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
+    stop(): void;
+}
+export {};

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

@@ -0,0 +1,240 @@
+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,
+      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

@@ -0,0 +1,107 @@
+# 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.
+
+## 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
+
+The build layer is intentionally split into two parts.
+
+`BuildExecutor` is the runtime-facing contract.
+
+- 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.
+
+`EsbuildBuildAdapter` is the current Bun-native backend. It knows how to:
+
+- 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.
+
+`DevBuildCoordinator` is the development policy layer. It exists because one app/runtime can have many build callers during dev mode, including:
+
+- page module imports
+- HMR entrypoint builds
+- script and asset processors
+- React integration build paths
+
+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:
+
+- serialized access to the shared adapter in development
+- recycling warm Node-target esbuild sessions between builds
+- recovery from known esbuild worker protocol faults
+
+## Default Flow
+
+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.
+
+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 top-level `getTranspileOptions()` helper are compatibility fallbacks only. New runtime code should prefer app-owned access through `getAppBuildAdapter()`, `getAppBuildExecutor()`, and `getAppTranspileOptions()`.
+
+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.
+
+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.
+
+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.
+
+## Orchestration Diagram
+
+```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"]
+```
+
+## Recovery Model
+
+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.
+
+When that happens, recovery does three things in order:
+
+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.
+
+After that reset, the coordinator retries the failed build once.
+
+## Why Explicit App Ownership
+
+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.
+
+The explicit app-owned executor model keeps the design honest:
+
+- 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
+
+## 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.
+
+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.

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

@@ -0,0 +1,26 @@
+import type { EcoBuildPlugin } from './build-types.js';
+import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
+export declare const DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME = "browser-runtime-import-rewrite";
+export type CreateBrowserRuntimeImportRewritePluginOptions = {
+    /** Stable build plugin name used for deduplication and selective exclusion. */
+    name?: string;
+    /** Manifest containing specifier-to-public-URL runtime asset mappings. */
+    manifest: BrowserRuntimeManifest;
+};
+/**
+ * Rewrites static ESM import/export specifiers and string-literal dynamic imports
+ * from manifest-owned runtime specifiers to concrete browser public URLs.
+ */
+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 applies browser runtime manifest import rewrites
+ * before the bundler resolves source modules.
+ *
+ * @remarks
+ * This is the migration path away from browser import-map-style runtime aliases:
+ * generated and authored browser modules can keep importing manifest-owned
+ * specifiers, while the build turns those specifiers into concrete public URLs.
+ */
+export declare function createBrowserRuntimeImportRewritePlugin(options: CreateBrowserRuntimeImportRewritePluginOptions): EcoBuildPlugin | null;