@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/build/dev-build-coordinator.d.ts

@@ -0,0 +1,72 @@
+import { type BuildAdapter, type BuildExecutor, type BuildOptions, type BuildResult } from './build-adapter.js';
+import { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
+import type { EcoBuildPlugin } from './build-types.js';
+export declare function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor;
+/**
+ * Serialized build coordinator for the shared esbuild adapter.
+ *
+ * The underlying adapter remains responsible for plain build execution. This
+ * coordinator owns the policy that must be shared across callers while Bun-native
+ * execution still uses the shared esbuild compatibility backend:
+ *
+ * - serialized access to the shared esbuild service
+ * - recovery from known esbuild worker protocol faults
+ *
+ * Unlike the previous design, the coordinator does not monkey-patch the adapter
+ * or install process-level fault handlers. The owning app/runtime passes this
+ * executor explicitly to build consumers that need coordinated builds.
+ */
+export declare class DevBuildCoordinator implements BuildExecutor {
+    private buildQueue;
+    private esbuildSessionWarm;
+    private esbuildModuleGeneration;
+    private readonly adapter;
+    constructor(adapter: EsbuildBuildAdapter);
+    /**
+     * Executes a build through the serialized development queue.
+     *
+     * If an esbuild protocol fault is detected, the coordinator resets the queue,
+     * stops the corrupted service, increments the module generation, and retries
+     * the build once.
+     */
+    build(options: BuildOptions): Promise<BuildResult>;
+    /**
+     * Attempts recovery from a known esbuild worker protocol fault.
+     *
+     * Returns `true` only when the error matches the protocol-fault signature and
+     * the coordinator successfully reset its shared state.
+     */
+    recoverFromProtocolFault(error: unknown): Promise<boolean>;
+    /**
+     * Clears internal coordinator state for isolated tests.
+     */
+    resetForTests(): void;
+    /**
+     * Overrides the internal queue promise for fault-recovery tests.
+     */
+    setBuildQueueForTests(queue: Promise<void>): void;
+    /**
+     * Returns the current internal queue promise for fault-recovery tests.
+     */
+    getBuildQueueForTests(): Promise<void>;
+    private runSerialized;
+}
+/**
+ * Creates the appropriate build executor for one app/runtime instance.
+ *
+ * Bun-native esbuild execution always uses the compatibility coordinator so
+ * preview/static generation and development flows share the same serialized
+ * access and protocol-fault recovery policy. Host-owned execution stays on the
+ * plain adapter boundary.
+ */
+export declare function createAppBuildExecutor(options: {
+    development: boolean;
+    adapter?: BuildAdapter;
+    getPlugins?: () => EcoBuildPlugin[];
+}): BuildExecutor;
+export declare function createOrReuseAppBuildExecutor(options: {
+    development: boolean;
+    adapter?: BuildAdapter;
+    currentExecutor?: BuildExecutor;
+    getPlugins?: () => EcoBuildPlugin[];
+}): BuildExecutor;

package/src/build/dev-build-coordinator.js

@@ -0,0 +1,154 @@
+import { appLogger } from "../global/app-logger.js";
+import {
+  defaultBunBuildAdapter
+} from "./build-adapter.js";
+import { EsbuildBuildAdapter, ESBUILD_ADAPTER_BRAND } from "./esbuild-build-adapter.js";
+import { mergeEcoBuildPlugins } from "./build-manifest.js";
+function isEsbuildBuildAdapter(adapter) {
+  return adapter instanceof EsbuildBuildAdapter || typeof adapter === "object" && adapter !== null && adapter[ESBUILD_ADAPTER_BRAND] === true;
+}
+function mergeBuildPlugins(options, appPlugins) {
+  if (appPlugins.length === 0) {
+    return options;
+  }
+  return {
+    ...options,
+    plugins: mergeEcoBuildPlugins(options.plugins, appPlugins)
+  };
+}
+class BuildExecutorWithPlugins {
+  executor;
+  getPlugins;
+  constructor(executor, getPlugins) {
+    this.executor = executor;
+    this.getPlugins = getPlugins;
+  }
+  async build(options) {
+    return await this.executor.build(mergeBuildPlugins(options, this.getPlugins()));
+  }
+  unwrap() {
+    return this.executor;
+  }
+}
+function unwrapBuildExecutor(executor) {
+  if (executor instanceof BuildExecutorWithPlugins) {
+    return unwrapBuildExecutor(executor.unwrap());
+  }
+  return executor;
+}
+function withBuildExecutorPlugins(executor, getPlugins) {
+  return new BuildExecutorWithPlugins(executor, getPlugins);
+}
+class DevBuildCoordinator {
+  buildQueue = Promise.resolve();
+  esbuildSessionWarm = false;
+  esbuildModuleGeneration = 0;
+  adapter;
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+  /**
+   * Executes a build through the serialized development queue.
+   *
+   * If an esbuild protocol fault is detected, the coordinator resets the queue,
+   * stops the corrupted service, increments the module generation, and retries
+   * the build once.
+   */
+  async build(options) {
+    return this.runSerialized(async () => {
+      try {
+        const result = await this.adapter.buildOrThrow(options, this.esbuildModuleGeneration);
+        this.esbuildSessionWarm = true;
+        return result;
+      } catch (error) {
+        if (await this.recoverFromProtocolFault(error)) {
+          appLogger.warn("Recovered from esbuild protocol fault. Retrying build.");
+          try {
+            const retry = await this.adapter.buildOrThrow(options, this.esbuildModuleGeneration);
+            this.esbuildSessionWarm = true;
+            return retry;
+          } catch (retryError) {
+            return this.adapter.createFailureResult(retryError);
+          }
+        }
+        return this.adapter.createFailureResult(error);
+      }
+    });
+  }
+  /**
+   * Attempts recovery from a known esbuild worker protocol fault.
+   *
+   * Returns `true` only when the error matches the protocol-fault signature and
+   * the coordinator successfully reset its shared state.
+   */
+  async recoverFromProtocolFault(error) {
+    if (!this.adapter.isEsbuildProtocolError(error)) {
+      return false;
+    }
+    this.buildQueue = Promise.resolve();
+    this.esbuildSessionWarm = false;
+    await this.adapter.stopEsbuildService(this.esbuildModuleGeneration);
+    this.esbuildModuleGeneration += 1;
+    return true;
+  }
+  /**
+   * Clears internal coordinator state for isolated tests.
+   */
+  resetForTests() {
+    this.buildQueue = Promise.resolve();
+    this.esbuildSessionWarm = false;
+    this.esbuildModuleGeneration = 0;
+  }
+  /**
+   * Overrides the internal queue promise for fault-recovery tests.
+   */
+  setBuildQueueForTests(queue) {
+    this.buildQueue = queue;
+  }
+  /**
+   * Returns the current internal queue promise for fault-recovery tests.
+   */
+  getBuildQueueForTests() {
+    return this.buildQueue;
+  }
+  async runSerialized(operation) {
+    let releaseBuild;
+    const currentBuild = new Promise((resolve) => {
+      releaseBuild = resolve;
+    });
+    const previousBuild = this.buildQueue;
+    this.buildQueue = previousBuild.catch(() => void 0).then(async () => await currentBuild);
+    await previousBuild.catch(() => void 0);
+    try {
+      return await operation();
+    } finally {
+      releaseBuild?.();
+    }
+  }
+}
+function createAppBuildExecutor(options) {
+  const adapter = options.adapter ?? defaultBunBuildAdapter;
+  const baseExecutor = isEsbuildBuildAdapter(adapter) ? new DevBuildCoordinator(adapter) : adapter;
+  if (!options.getPlugins) {
+    return baseExecutor;
+  }
+  return new BuildExecutorWithPlugins(baseExecutor, options.getPlugins);
+}
+function createOrReuseAppBuildExecutor(options) {
+  const adapter = options.adapter ?? defaultBunBuildAdapter;
+  const currentBaseExecutor = options.currentExecutor ? unwrapBuildExecutor(options.currentExecutor) : void 0;
+  const baseExecutor = options.development && currentBaseExecutor instanceof DevBuildCoordinator ? currentBaseExecutor : createAppBuildExecutor({
+    development: options.development,
+    adapter
+  });
+  if (!options.getPlugins) {
+    return baseExecutor;
+  }
+  return withBuildExecutorPlugins(baseExecutor, options.getPlugins);
+}
+export {
+  DevBuildCoordinator,
+  createAppBuildExecutor,
+  createOrReuseAppBuildExecutor,
+  withBuildExecutorPlugins
+};

package/src/build/esbuild-build-adapter.d.ts

@@ -1,4 +1,3 @@
-import type { EcoBuildPlugin } from './build-types.js';
 import type { BuildAdapter, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from './build-adapter.js';
 /**
  * Node build adapter backed by esbuild.
@@ -6,8 +5,13 @@ import type { BuildAdapter, BuildOptions, BuildResult, BuildTranspileOptions, Bu
  * This adapter keeps Ecopages build plugin compatibility (`onResolve`, `onLoad`,
  * and `module`) while delegating bundling and TypeScript/decorator transforms to esbuild.
  */
+export declare const ESBUILD_ADAPTER_BRAND: unique symbol;
 export declare class EsbuildBuildAdapter implements BuildAdapter {
-    private registeredPlugins;
+    readonly ownership: "bun-native";
+    readonly [ESBUILD_ADAPTER_BRAND] = true;
+    private collectWorkspaceNodePaths;
+    private getFallbackNodePaths;
+    private rewriteAliasedRuntimeSpecifiers;
     private escapeRegExp;
     private getPluginsForBuild;
     private normalizeEsbuildLoader;
@@ -40,6 +44,14 @@ export declare class EsbuildBuildAdapter implements BuildAdapter {
      */
     private createEcoPluginBridge;
     private loadEsbuildModule;
+    private isMockedEsbuildModule;
+    /**
+     * Detects the subset of runtime faults that indicate esbuild's worker
+     * protocol is corrupted rather than a normal build error.
+     */
+    isEsbuildProtocolError(error: unknown): boolean;
+    stopEsbuildService(moduleGeneration?: number): Promise<void>;
+    buildOrThrow(options: BuildOptions, moduleGeneration?: number): Promise<BuildResult>;
     private mapEsbuildSourcemap;
     private mapEsbuildFormat;
     private hasTemplateTokens;
@@ -50,6 +62,7 @@ export declare class EsbuildBuildAdapter implements BuildAdapter {
      * Normalizes esbuild errors into Ecopages `BuildLog` entries.
      */
     private toBuildLogs;
+    createFailureResult(error: unknown): BuildResult;
     /**
      * Bundles entrypoints using esbuild for Node runtime builds.
      */
@@ -58,10 +71,6 @@ export declare class EsbuildBuildAdapter implements BuildAdapter {
      * Resolves module specifiers from a project root.
      */
     resolve(importPath: string, rootDir: string): string;
-    /**
-     * Registers a build plugin once by plugin name.
-     */
-    registerPlugin(plugin: EcoBuildPlugin): void;
     /**
      * Returns transpile defaults for a known transpile profile.
      */

package/src/build/esbuild-build-adapter.js

@@ -1,6 +1,12 @@
-import path from "node:path";
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { fileSystem } from "@ecopages/file-system";
+import { collectRuntimeSpecifierAliasMap, rewriteRuntimeSpecifierAliases } from "./runtime-specifier-aliases.js";
+const moduleRequire = createRequire(import.meta.url);
+const esbuildPath = moduleRequire.resolve("esbuild");
+const workspaceNodePathsCache = /* @__PURE__ */ new Map();
 function transpileProfileToOptions(profile) {
   switch (profile) {
     case "browser-script":
@@ -23,15 +29,84 @@ function transpileProfileToOptions(profile) {
       };
   }
 }
+const ESBUILD_ADAPTER_BRAND = /* @__PURE__ */ Symbol.for("EsbuildBuildAdapter");
 class EsbuildBuildAdapter {
-  registeredPlugins = [];
+  ownership = "bun-native";
+  [ESBUILD_ADAPTER_BRAND] = true;
+  collectWorkspaceNodePaths(scanRoot, maxDepth = 3) {
+    const normalizedRoot = path.resolve(scanRoot);
+    const cached = workspaceNodePathsCache.get(normalizedRoot);
+    if (cached) {
+      return cached;
+    }
+    const nodePaths = /* @__PURE__ */ new Set();
+    const skippedDirectoryNames = /* @__PURE__ */ new Set([".git", ".turbo", "dist", "node_modules", "test-results"]);
+    const visit = (dirPath, depth) => {
+      if (depth > maxDepth) {
+        return;
+      }
+      const packageJsonPath = path.join(dirPath, "package.json");
+      const nodeModulesPath = path.join(dirPath, "node_modules");
+      if (fileSystem.exists(packageJsonPath) && fileSystem.exists(nodeModulesPath)) {
+        nodePaths.add(nodeModulesPath);
+      }
+      if (depth === maxDepth) {
+        return;
+      }
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+          continue;
+        }
+        if (skippedDirectoryNames.has(entry.name) || entry.name.startsWith(".")) {
+          continue;
+        }
+        visit(path.join(dirPath, entry.name), depth + 1);
+      }
+    };
+    if (fileSystem.exists(normalizedRoot) && fileSystem.isDirectory(normalizedRoot)) {
+      visit(normalizedRoot, 0);
+    }
+    const resolvedNodePaths = Array.from(nodePaths);
+    workspaceNodePathsCache.set(normalizedRoot, resolvedNodePaths);
+    return resolvedNodePaths;
+  }
+  getFallbackNodePaths(contextRoot) {
+    const nodePaths = /* @__PURE__ */ new Set();
+    const contextNodeModulesPath = path.join(contextRoot, "node_modules");
+    if (fileSystem.exists(contextNodeModulesPath)) {
+      nodePaths.add(contextNodeModulesPath);
+    }
+    for (const workspaceNodePath of this.collectWorkspaceNodePaths(process.cwd())) {
+      nodePaths.add(workspaceNodePath);
+    }
+    return Array.from(nodePaths);
+  }
+  rewriteAliasedRuntimeSpecifiers(result, plugins) {
+    if (!result.success || result.outputs.length === 0) {
+      return result;
+    }
+    const aliasMap = collectRuntimeSpecifierAliasMap(plugins);
+    if (aliasMap.size === 0) {
+      return result;
+    }
+    for (const output of result.outputs) {
+      if (!/\.(?:[cm]?js)$/u.test(output.path)) {
+        continue;
+      }
+      const code = readFileSync(output.path, "utf-8");
+      const rewritten = rewriteRuntimeSpecifierAliases(code, aliasMap);
+      if (rewritten !== code) {
+        writeFileSync(output.path, rewritten);
+      }
+    }
+    return result;
+  }
   escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   }
   getPluginsForBuild(additionalPlugins) {
-    const merged = [...additionalPlugins ?? [], ...this.registeredPlugins];
     const byName = /* @__PURE__ */ new Map();
-    for (const plugin of merged) {
+    for (const plugin of additionalPlugins ?? []) {
       if (!byName.has(plugin.name)) {
         byName.set(plugin.name, plugin);
       }
@@ -207,13 +282,110 @@ class EsbuildBuildAdapter {
       }
     };
   }
-  async loadEsbuildModule() {
-    const esbuildModule = await import("esbuild");
+  async loadEsbuildModule(moduleGeneration = 0) {
+    const importedModule = await import("esbuild");
+    const esbuildModule = typeof importedModule.build === "function" ? importedModule : importedModule.default ?? importedModule;
+    if (moduleGeneration > 0 && !this.isMockedEsbuildModule(esbuildModule)) {
+      const freshModule = await import(
+        /* @vite-ignore */
+        `${pathToFileURL(esbuildPath).href}?ecopages_esbuild=${moduleGeneration}`
+      );
+      const normalizedFreshModule = typeof freshModule.build === "function" ? freshModule : freshModule.default ?? freshModule;
+      if (typeof normalizedFreshModule.build === "function") {
+        return normalizedFreshModule;
+      }
+    }
     if (typeof esbuildModule.build !== "function") {
       throw new Error("esbuild is not available. Install esbuild to use Node bundling.");
     }
     return esbuildModule;
   }
+  isMockedEsbuildModule(esbuildModule) {
+    const build = esbuildModule.build;
+    const stop = esbuildModule.stop;
+    return typeof build?.mock === "object" || typeof stop?.mock === "object";
+  }
+  /**
+   * Detects the subset of runtime faults that indicate esbuild's worker
+   * protocol is corrupted rather than a normal build error.
+   */
+  isEsbuildProtocolError(error) {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    return ["Unexpected end of JSON input", "Unexpected EOF", "parseJSON", "buildResponseToResult"].some(
+      (fragment) => error.message.includes(fragment) || error.stack?.includes(fragment)
+    );
+  }
+  async stopEsbuildService(moduleGeneration = 0) {
+    const esbuild = await this.loadEsbuildModule(moduleGeneration);
+    if (typeof esbuild.stop === "function") {
+      esbuild.stop();
+    }
+  }
+  async buildOrThrow(options, moduleGeneration = 0) {
+    const esbuild = await this.loadEsbuildModule(moduleGeneration);
+    const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
+    const outdir = path.resolve(options.outdir ?? "dist/assets");
+    const tsconfigPath = path.join(contextRoot, "tsconfig.json");
+    const tsconfigExists = fileSystem.exists(tsconfigPath);
+    const nodePaths = this.getFallbackNodePaths(contextRoot);
+    const plugins = this.getPluginsForBuild(options.plugins);
+    const esbuildPlugins = [
+      ...plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : []
+    ];
+    const transpileTarget = "es2022";
+    const usesTemplatedNaming = this.hasTemplateTokens(options.naming);
+    const outfile = options.naming && !usesTemplatedNaming ? path.join(outdir, options.naming) : void 0;
+    if (outfile) {
+      fileSystem.ensureDir(path.dirname(outfile));
+    }
+    const outputOptions = outfile ? { outfile } : {
+      outdir,
+      ...options.outbase ? { outbase: path.resolve(options.outbase) } : {},
+      entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : "[name]",
+      chunkNames: "[name]-[hash]",
+      assetNames: "[name]-[hash]"
+    };
+    const result = await esbuild.build({
+      absWorkingDir: contextRoot,
+      ...nodePaths.length > 0 ? { nodePaths } : {},
+      entryPoints: options.entrypoints,
+      bundle: options.bundle ?? true,
+      ...outputOptions,
+      ...options.conditions ? { conditions: options.conditions } : {},
+      ...options.define ? { define: options.define } : {},
+      format: this.mapEsbuildFormat(options.format),
+      platform: options.target === "browser" ? "browser" : "node",
+      sourcemap: this.mapEsbuildSourcemap(options.sourcemap),
+      splitting: outfile ? false : !!options.splitting,
+      minify: !!options.minify,
+      ...typeof options.treeshaking === "boolean" ? { treeShaking: options.treeshaking } : {},
+      external: options.external,
+      ...options.target !== "browser" && options.externalPackages !== false ? { packages: "external" } : {},
+      target: transpileTarget,
+      metafile: true,
+      write: true,
+      plugins: esbuildPlugins,
+      jsx: "automatic",
+      tsconfig: tsconfigExists ? tsconfigPath : void 0,
+      logLevel: "silent"
+    });
+    const outputs = Object.keys(result.metafile.outputs).map((outputPath) => ({
+      path: path.isAbsolute(outputPath) ? outputPath : path.join(contextRoot, outputPath)
+    }));
+    const logs = result.warnings.map((warning) => ({ message: warning.text }));
+    const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
+    return this.rewriteAliasedRuntimeSpecifiers(
+      {
+        success: true,
+        logs,
+        outputs,
+        dependencyGraph
+      },
+      plugins
+    );
+  }
   mapEsbuildSourcemap(value) {
     switch (value) {
       case "none":
@@ -297,86 +469,28 @@ class EsbuildBuildAdapter {
     }
     return [{ message: "Unknown esbuild error" }];
   }
+  createFailureResult(error) {
+    return {
+      success: false,
+      logs: this.toBuildLogs(error),
+      outputs: []
+    };
+  }
   /**
    * Bundles entrypoints using esbuild for Node runtime builds.
    */
   async build(options) {
-    const esbuild = await this.loadEsbuildModule();
-    const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
-    const outdir = path.resolve(options.outdir ?? ".eco/assets");
-    const tsconfigPath = path.join(contextRoot, "tsconfig.json");
-    const tsconfigExists = fileSystem.exists(tsconfigPath);
-    const plugins = this.getPluginsForBuild(options.plugins);
-    const esbuildPlugins = [
-      ...plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : []
-    ];
-    const transpileTarget = "es2022";
-    const usesTemplatedNaming = this.hasTemplateTokens(options.naming);
-    const outfile = options.naming && !usesTemplatedNaming ? path.join(outdir, options.naming) : void 0;
-    if (outfile) {
-      fileSystem.ensureDir(path.dirname(outfile));
-    }
-    const outputOptions = outfile ? { outfile } : {
-      outdir,
-      entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : "[name]",
-      chunkNames: "[name]-[hash]",
-      assetNames: "[name]-[hash]"
-    };
     try {
-      const result = await esbuild.build({
-        absWorkingDir: contextRoot,
-        entryPoints: options.entrypoints,
-        bundle: options.bundle ?? true,
-        ...outputOptions,
-        format: this.mapEsbuildFormat(options.format),
-        platform: options.target === "browser" ? "browser" : "node",
-        sourcemap: this.mapEsbuildSourcemap(options.sourcemap),
-        splitting: outfile ? false : !!options.splitting,
-        minify: !!options.minify,
-        ...typeof options.treeshaking === "boolean" ? { treeShaking: options.treeshaking } : {},
-        external: options.external,
-        ...options.target !== "browser" && options.externalPackages !== false ? { packages: "external" } : {},
-        target: transpileTarget,
-        metafile: true,
-        write: true,
-        plugins: esbuildPlugins,
-        jsx: "automatic",
-        tsconfig: tsconfigExists ? tsconfigPath : void 0,
-        logLevel: "silent"
-      });
-      const outputs = Object.keys(result.metafile.outputs).map((outputPath) => ({
-        path: path.isAbsolute(outputPath) ? outputPath : path.join(contextRoot, outputPath)
-      }));
-      const logs = result.warnings.map((warning) => ({ message: warning.text }));
-      const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
-      return {
-        success: true,
-        logs,
-        outputs,
-        dependencyGraph
-      };
+      return await this.buildOrThrow(options);
     } catch (error) {
-      return {
-        success: false,
-        logs: this.toBuildLogs(error),
-        outputs: []
-      };
+      return this.createFailureResult(error);
     }
   }
   /**
    * Resolves module specifiers from a project root.
    */
   resolve(importPath, rootDir) {
-    const localRequire = createRequire(path.join(rootDir, "package.json"));
-    return localRequire.resolve(importPath);
-  }
-  /**
-   * Registers a build plugin once by plugin name.
-   */
-  registerPlugin(plugin) {
-    if (!this.registeredPlugins.find((registered) => registered.name === plugin.name)) {
-      this.registeredPlugins.push(plugin);
-    }
+    return moduleRequire.resolve(importPath, { paths: [rootDir] });
   }
   /**
    * Returns transpile defaults for a known transpile profile.
@@ -386,5 +500,6 @@ class EsbuildBuildAdapter {
   }
 }
 export {
+  ESBUILD_ADAPTER_BRAND,
   EsbuildBuildAdapter
 };

package/src/build/runtime-build-executor.d.ts

@@ -0,0 +1,14 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { type BuildExecutor } from './build-adapter.js';
+/**
+ * Installs the app-owned runtime build executor for one app instance.
+ *
+ * @remarks
+ * This is the single runtime executor boundary for adapter-owned startup.
+ * Bun-native ownership may reuse `DevBuildCoordinator` in development, while
+ * Vite-host ownership stays on a plain host-owned executor boundary with no
+ * Bun-specific coordination policy.
+ */
+export declare function installAppRuntimeBuildExecutor(appConfig: EcoPagesAppConfig, options: {
+    development: boolean;
+}): BuildExecutor;

package/src/build/runtime-build-executor.js

@@ -0,0 +1,22 @@
+import {
+  getAppBuildAdapter,
+  getAppBuildExecutor,
+  getAppBuildOwnership,
+  getAppServerBuildPlugins,
+  setAppBuildExecutor
+} from "./build-adapter.js";
+import { createOrReuseAppBuildExecutor, withBuildExecutorPlugins } from "./dev-build-coordinator.js";
+function installAppRuntimeBuildExecutor(appConfig, options) {
+  const buildOwnership = getAppBuildOwnership(appConfig);
+  const buildExecutor = buildOwnership === "bun-native" ? createOrReuseAppBuildExecutor({
+    development: options.development,
+    adapter: getAppBuildAdapter(appConfig),
+    currentExecutor: getAppBuildExecutor(appConfig),
+    getPlugins: () => getAppServerBuildPlugins(appConfig)
+  }) : withBuildExecutorPlugins(getAppBuildAdapter(appConfig), () => getAppServerBuildPlugins(appConfig));
+  setAppBuildExecutor(appConfig, buildExecutor);
+  return buildExecutor;
+}
+export {
+  installAppRuntimeBuildExecutor
+};

package/src/build/runtime-specifier-alias-plugin.d.ts

@@ -0,0 +1,15 @@
+import type { EcoBuildPlugin } from './build-types.js';
+type RuntimeSpecifierMap = ReadonlyMap<string, string> | Record<string, string>;
+/**
+ * Creates a build plugin that aliases runtime bare specifiers to concrete URLs.
+ *
+ * @remarks
+ * This helper is used when browser-target builds must preserve integration-owned
+ * runtime specifier semantics while letting the bundler treat the mapped URLs as
+ * external runtime assets.
+ */
+export declare function createRuntimeSpecifierAliasPlugin(specifierMapInput: RuntimeSpecifierMap, options?: {
+    name?: string;
+    external?: boolean;
+}): EcoBuildPlugin | null;
+export {};

package/src/build/runtime-specifier-alias-plugin.js

@@ -0,0 +1,35 @@
+import { attachRuntimeSpecifierAliasMap } from "./runtime-specifier-aliases.js";
+function toRuntimeSpecifierMap(specifierMap) {
+  return specifierMap instanceof Map ? specifierMap : new Map(Object.entries(specifierMap));
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createRuntimeSpecifierAliasPlugin(specifierMapInput, options) {
+  const specifierMap = toRuntimeSpecifierMap(specifierMapInput);
+  if (specifierMap.size === 0) {
+    return null;
+  }
+  const filter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join("|")})$`);
+  return attachRuntimeSpecifierAliasMap(
+    {
+      name: options?.name ?? "runtime-specifier-alias",
+      setup(build) {
+        build.onResolve({ filter }, (args) => {
+          const mappedPath = specifierMap.get(args.path);
+          if (!mappedPath) {
+            return void 0;
+          }
+          return {
+            path: mappedPath,
+            external: options?.external ?? true
+          };
+        });
+      }
+    },
+    specifierMap
+  );
+}
+export {
+  createRuntimeSpecifierAliasPlugin
+};