@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.10

package/src/adapters/shared/server-static-builder.d.ts

@@ -1,7 +1,7 @@
 import type { EcoPagesAppConfig } from '../../internal-types';
-import type { StaticRoute } from '../../public-types';
+import type { ApiHandler, StaticRoute } from '../../public-types';
 import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
-import type { FSRouter } from '../../router/fs-router';
+import type { FSRouter } from '../../router/server/fs-router';
 import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
 export interface StaticBuildOptions {
     preview?: boolean;
@@ -14,6 +14,32 @@ export interface ServerStaticBuilderParams {
     appConfig: EcoPagesAppConfig;
     staticSiteGenerator: StaticSiteGenerator;
     serveOptions: ServeOptions;
+    apiHandlers?: ApiHandler[];
+    logger?: ServerStaticBuilderLogger;
+    previewServerFactory?: ServerStaticPreviewServerFactory;
+}
+/**
+ * Minimal logger dependency used by the static builder.
+ */
+export interface ServerStaticBuilderLogger {
+    warn(message: string, detail?: string): unknown;
+    info(message: string): unknown;
+    error(message: string): unknown;
+}
+/**
+ * Preview server factory dependency used when static preview mode is enabled.
+ */
+export interface ServerStaticPreviewServerFactory {
+    createServer(args: {
+        appConfig: EcoPagesAppConfig;
+        options: {
+            port: number;
+        };
+    }): {
+        server?: {
+            port?: number;
+        } | null;
+    };
 }
 /**
  * Handles static site generation and previews.
@@ -22,7 +48,13 @@ export declare class ServerStaticBuilder {
     private readonly appConfig;
     private readonly staticSiteGenerator;
     private readonly serveOptions;
-    constructor({ appConfig, staticSiteGenerator, serveOptions }: ServerStaticBuilderParams);
+    private readonly apiHandlers;
+    private readonly logger;
+    private readonly previewServerFactory;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, }: ServerStaticBuilderParams);
+    private warnApiHandlersUnavailableInStaticMode;
+    private prepareExportDirectory;
+    private refreshRuntimeAssets;
     /**
      * Generates a static build of the site for deployment.
      * @param options.preview - If true, starts a preview server after build

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

@@ -1,13 +1,63 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
 import { StaticContentServer } from "../../dev/sc-server";
 import { appLogger } from "../../global/app-logger";
 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.
@@ -19,6 +69,9 @@ class ServerStaticBuilder {
   async build(options, dependencies) {
     const { preview = false } = options ?? {};
     const baseUrl = `http://${this.serveOptions.hostname || "localhost"}:${this.serveOptions.port || 3e3}`;
+    this.warnApiHandlersUnavailableInStaticMode();
+    this.prepareExportDirectory();
+    await this.refreshRuntimeAssets();
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,
@@ -26,18 +79,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 { 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/build/README.md

@@ -0,0 +1,101 @@
+# 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.
+
+## Files
+
+- `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.
+
+## 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.
+- `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.
+
+`EsbuildBuildAdapter` is the 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
+
+`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:
+
+- 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 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.
+
+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.
+
+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, 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`)
+- 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
+
+## 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/build-adapter.d.ts

@@ -1,4 +1,7 @@
 import type { EcoBuildPlugin } from './build-types.js';
+import { type AppBuildManifest } from './build-manifest.js';
+import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { IHmrManager } from '../public-types.js';
 export { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
 export interface BuildLog {
     message: string;
@@ -36,7 +39,10 @@ export interface BuildResult {
 export interface BuildOptions {
     entrypoints: string[];
     outdir?: string;
+    outbase?: string;
     naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
     minify?: boolean;
     treeshaking?: boolean;
     target?: string;
@@ -57,18 +63,124 @@ export interface BuildTranspileOptions {
     sourcemap: string;
 }
 export interface BuildAdapter {
+    /**
+     * Executes one concrete backend build.
+     *
+     * @remarks
+     * `BuildAdapter` is the low-level backend contract. The default adapter is
+     * `EsbuildBuildAdapter`, but alternate adapters may satisfy the same shape.
+     */
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
-    registerPlugin(plugin: EcoBuildPlugin): void;
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
+/**
+ * Runtime-owned facade for issuing builds.
+ *
+ * @remarks
+ * This is intentionally narrower than `BuildAdapter`. A build executor answers
+ * only the question "how should this app execute a build right now?".
+ *
+ * In production and non-watch flows the executor is usually the adapter itself,
+ * which today means `EsbuildBuildAdapter`. In development watch flows the
+ * executor is typically `DevBuildCoordinator`, which wraps the shared esbuild
+ * adapter to serialize callers and recover from known worker faults.
+ */
+export interface BuildExecutor {
+    build(options: BuildOptions): Promise<BuildResult>;
+}
+export declare function createBuildAdapter(): BuildAdapter;
 /**
  * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
  */
 export declare class BunBuildAdapter implements BuildAdapter {
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
-    registerPlugin(plugin: EcoBuildPlugin): void;
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
 export declare const defaultBuildAdapter: BuildAdapter;
+/**
+ * Returns the adapter owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder installs a dedicated adapter per app. The shared default
+ * adapter remains only as a compatibility fallback for older tests and helpers
+ * that do not yet thread app runtime state explicitly.
+ */
+export declare function getAppBuildAdapter(appConfig: EcoPagesAppConfig): BuildAdapter;
+/**
+ * Installs the adapter that should serve future builds for one app instance.
+ */
+export declare function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAdapter: BuildAdapter): void;
+/**
+ * Returns the build manifest owned by an app/runtime instance.
+ */
+export declare function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest;
+/**
+ * Installs the build manifest that should be visible to one app instance.
+ */
+export declare function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void;
+/**
+ * Rebuilds an app-owned manifest from config-owned loaders plus explicit
+ * runtime/browser contribution input.
+ *
+ * @remarks
+ * This keeps loader ownership with config finalization while still letting a
+ * caller supply the non-loader plugin buckets that were discovered elsewhere.
+ */
+export declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Replaces the app-owned manifest using config-owned loaders and explicit
+ * contribution input.
+ */
+export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
+/**
+ * Collects the build-facing processor and integration contributions that should
+ * be sealed into the app manifest during config finalization.
+ *
+ * @remarks
+ * This runs `prepareBuildContributions()` only. Runtime-only side effects such
+ * as HMR registration, cache prewarming, and runtime-origin wiring belong to
+ * the startup path and must not be triggered here.
+ */
+export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins'>>;
+/**
+ * Runs runtime-only processor and integration setup against an already sealed
+ * app manifest.
+ *
+ * @remarks
+ * Startup paths call this after config build has finalized manifest
+ * contributions. The manifest is reused as-is; this helper only performs the
+ * runtime side effects that still need live startup context.
+ */
+export declare function setupAppRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
+}): Promise<void>;
+export declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * Returns the executor owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder seeds this with the shared default adapter. Runtime
+ * adapters may replace it with a coordinator that still delegates to the same
+ * backend while adding development policy.
+ */
+export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
+/**
+ * Installs the executor that should serve future builds for one app instance.
+ */
+export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+/**
+ * Runs a build through the active pipeline.
+ *
+ * @remarks
+ * Callers can pass an explicit executor when builds should be routed through an
+ * app-owned development coordinator. Without one, the shared default adapter is
+ * used directly.
+ */
+export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
+export declare function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;

package/src/build/build-adapter.js

@@ -1,6 +1,14 @@
+import {
+  createAppBuildManifest,
+  getBrowserBuildPlugins,
+  getServerBuildPlugins
+} from "./build-manifest.js";
 import { EsbuildBuildAdapter } from "./esbuild-build-adapter.js";
 import { getRequiredBunRuntime } from "../utils/runtime.js";
 import { EsbuildBuildAdapter as EsbuildBuildAdapter2 } from "./esbuild-build-adapter.js";
+function createBuildAdapter() {
+  return new EsbuildBuildAdapter();
+}
 function transpileProfileToOptions(profile) {
   switch (profile) {
     case "browser-script":
@@ -39,16 +47,122 @@ class BunBuildAdapter {
   resolve(importPath, rootDir) {
     return getRequiredBunRuntime().resolveSync(importPath, rootDir);
   }
-  registerPlugin(plugin) {
-    getRequiredBunRuntime().plugin(plugin);
-  }
   getTranspileOptions(profile) {
     return transpileProfileToOptions(profile);
   }
 }
-const defaultBuildAdapter = new EsbuildBuildAdapter();
+const defaultBuildAdapter = createBuildAdapter();
+function getAppBuildAdapter(appConfig) {
+  return appConfig.runtime?.buildAdapter ?? defaultBuildAdapter;
+}
+function setAppBuildAdapter(appConfig, buildAdapter) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    buildAdapter
+  };
+}
+function getAppBuildManifest(appConfig) {
+  return appConfig.runtime?.buildManifest ?? createAppBuildManifest({
+    loaderPlugins: Array.from(appConfig.loaders.values())
+  });
+}
+function setAppBuildManifest(appConfig, buildManifest) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    buildManifest
+  };
+}
+function createConfiguredAppBuildManifest(appConfig, input) {
+  return createAppBuildManifest({
+    loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
+    runtimePlugins: input?.runtimePlugins,
+    browserBundlePlugins: input?.browserBundlePlugins
+  });
+}
+function updateAppBuildManifest(appConfig, input) {
+  setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
+}
+async function collectConfiguredAppBuildManifestContributions(appConfig) {
+  const runtimePlugins = [];
+  const browserBundlePlugins = [];
+  for (const processor of appConfig.processors.values()) {
+    await processor.prepareBuildContributions();
+    if (processor.plugins) {
+      runtimePlugins.push(...processor.plugins);
+    }
+    if (processor.buildPlugins) {
+      browserBundlePlugins.push(...processor.buildPlugins);
+    }
+  }
+  for (const integration of appConfig.integrations) {
+    integration.setConfig(appConfig);
+    await integration.prepareBuildContributions();
+    runtimePlugins.push(...integration.plugins);
+  }
+  return {
+    runtimePlugins,
+    browserBundlePlugins
+  };
+}
+async function setupAppRuntimePlugins(options) {
+  for (const processor of options.appConfig.processors.values()) {
+    await processor.setup();
+    if (processor.plugins) {
+      for (const plugin of processor.plugins) {
+        options.onRuntimePlugin?.(plugin);
+      }
+    }
+  }
+  for (const integration of options.appConfig.integrations) {
+    integration.setConfig(options.appConfig);
+    integration.setRuntimeOrigin(options.runtimeOrigin);
+    if (options.hmrManager) {
+      integration.setHmrManager(options.hmrManager);
+    }
+    await integration.setup();
+    for (const plugin of integration.plugins) {
+      options.onRuntimePlugin?.(plugin);
+    }
+  }
+}
+function getAppServerBuildPlugins(appConfig) {
+  return getServerBuildPlugins(getAppBuildManifest(appConfig));
+}
+function getAppBrowserBuildPlugins(appConfig) {
+  return getBrowserBuildPlugins(getAppBuildManifest(appConfig));
+}
+function getAppBuildExecutor(appConfig) {
+  return appConfig.runtime?.buildExecutor ?? getAppBuildAdapter(appConfig);
+}
+function setAppBuildExecutor(appConfig, buildExecutor) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    buildExecutor
+  };
+}
+function build(options, executor = defaultBuildAdapter) {
+  return executor.build(options);
+}
+function getTranspileOptions(profile) {
+  return defaultBuildAdapter.getTranspileOptions(profile);
+}
 export {
   BunBuildAdapter,
   EsbuildBuildAdapter2 as EsbuildBuildAdapter,
-  defaultBuildAdapter
+  build,
+  collectConfiguredAppBuildManifestContributions,
+  createBuildAdapter,
+  createConfiguredAppBuildManifest,
+  defaultBuildAdapter,
+  getAppBrowserBuildPlugins,
+  getAppBuildAdapter,
+  getAppBuildExecutor,
+  getAppBuildManifest,
+  getAppServerBuildPlugins,
+  getTranspileOptions,
+  setAppBuildAdapter,
+  setAppBuildExecutor,
+  setAppBuildManifest,
+  setupAppRuntimePlugins,
+  updateAppBuildManifest
 };

package/src/build/build-manifest.d.ts

@@ -0,0 +1,27 @@
+import type { EcoBuildPlugin } from './build-types.js';
+export interface AppBuildManifest {
+    loaderPlugins: EcoBuildPlugin[];
+    runtimePlugins: EcoBuildPlugin[];
+    browserBundlePlugins: EcoBuildPlugin[];
+}
+/**
+ * Merges plugin lists while preserving first-registration precedence by name.
+ *
+ * @remarks
+ * Build manifests treat plugin names as stable identities. The first plugin
+ * with a given name wins so config-time assembly stays deterministic across
+ * loader, runtime, and browser buckets.
+ */
+export declare function mergeEcoBuildPlugins(...pluginLists: Array<EcoBuildPlugin[] | undefined>): EcoBuildPlugin[];
+/**
+ * Creates one app-owned build manifest from the supplied plugin buckets.
+ */
+export declare function createAppBuildManifest(input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Returns the plugin list used for server-oriented builds.
+ */
+export declare function getServerBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];
+/**
+ * Returns the plugin list used for browser-oriented builds.
+ */
+export declare function getBrowserBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];

package/src/build/build-manifest.js

@@ -0,0 +1,30 @@
+function mergeEcoBuildPlugins(...pluginLists) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const plugins of pluginLists) {
+    for (const plugin of plugins ?? []) {
+      if (!byName.has(plugin.name)) {
+        byName.set(plugin.name, plugin);
+      }
+    }
+  }
+  return Array.from(byName.values());
+}
+function createAppBuildManifest(input) {
+  return {
+    loaderPlugins: mergeEcoBuildPlugins(input?.loaderPlugins),
+    runtimePlugins: mergeEcoBuildPlugins(input?.runtimePlugins),
+    browserBundlePlugins: mergeEcoBuildPlugins(input?.browserBundlePlugins)
+  };
+}
+function getServerBuildPlugins(manifest) {
+  return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins);
+}
+function getBrowserBuildPlugins(manifest) {
+  return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins, manifest.browserBundlePlugins);
+}
+export {
+  createAppBuildManifest,
+  getBrowserBuildPlugins,
+  getServerBuildPlugins,
+  mergeEcoBuildPlugins
+};

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

@@ -0,0 +1,74 @@
+import { type BuildAdapter, type BuildExecutor, type BuildOptions, type BuildResult, EsbuildBuildAdapter } from './build-adapter.js';
+import type { EcoBuildPlugin } from './build-types.js';
+export declare function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor;
+/**
+ * Serialized development 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 in dev mode:
+ *
+ * - serialized access to the shared esbuild service
+ * - warm-service recycling for Node-target builds
+ * - 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 development
+ * 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.
+     *
+     * Node-target builds recycle the warmed esbuild service between requests to
+     * avoid stale worker state accumulating across long-lived dev sessions.
+     *
+     * 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 shouldRecycleEsbuildService;
+    private runSerialized;
+}
+/**
+ * Creates the appropriate build executor for one app/runtime instance.
+ *
+ * Development runtimes get a dedicated coordinator around the shared esbuild
+ * adapter. Non-development runtimes use the adapter directly.
+ */
+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;