@ecopages/core 0.2.0-beta.6 → 0.2.0-beta.8

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

@@ -1,4 +1,4 @@
-import { createServer } from "node:http";
+import {} from "node:http";
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
@@ -20,6 +20,7 @@ import {
   isHtmlResponse,
   shouldInjectHmrHtmlResponse
 } from "../shared/hmr-html-response.js";
+import { copyRuntimePublicDirIfChanged } from "../shared/copy-runtime-public-dir.js";
 import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
 import { NodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
 import { NodeStaticPreviewHost } from "./static-preview-host.js";
@@ -32,6 +33,8 @@ class NodeServerAdapter extends SharedServerAdapter {
   errorHandler;
   bridge = null;
   hmrManager = null;
+  projectWatcher = null;
+  adapterDisposed = false;
   previewHost;
   requestBridge;
   devRuntimeFactory;
@@ -126,7 +129,7 @@ class NodeServerAdapter extends SharedServerAdapter {
   prepareRuntimePublicDir() {
     const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
     if (fileSystem.exists(srcPublicDir)) {
-      fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
+      copyRuntimePublicDirIfChanged(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
     }
     fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
   }
@@ -139,20 +142,15 @@ class NodeServerAdapter extends SharedServerAdapter {
     if (!this.initialized) {
       await this.initialize();
     }
-    const buildServer = await this.startBuildRuntimeServer();
-    const buildRuntimeOrigin = this.getListeningServerOrigin(buildServer);
-    try {
-      await this.staticBuilder.build(
-        { preview: false, baseUrl: buildRuntimeOrigin },
-        {
-          router: this.router,
-          routeRendererFactory: this.routeRendererFactory,
-          staticRoutes: this.staticRoutes
-        }
-      );
-    } finally {
-      await this.stopBuildRuntimeServer(buildServer);
-    }
+    const baseUrl = resolveServeRuntimeOrigin(this.serveOptions);
+    await this.staticBuilder.build(
+      { preview: false, baseUrl, force: options?.force },
+      {
+        router: this.router,
+        routeRendererFactory: this.routeRendererFactory,
+        staticRoutes: this.staticRoutes
+      }
+    );
     if (!options?.preview) {
       return;
     }
@@ -165,71 +163,6 @@ class NodeServerAdapter extends SharedServerAdapter {
     const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
     appLogger.info(`Preview running at http://${previewHostname}:${previewPort}`);
   }
-  async startBuildRuntimeServer() {
-    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
-    const port = 0;
-    const server = createServer(async (req, res) => {
-      try {
-        const webRequest = this.requestBridge.createWebRequest(req, this.runtimeOrigin);
-        const response = await this.handleRequest(webRequest);
-        await this.requestBridge.sendNodeResponse(res, response);
-      } catch (error) {
-        if (error instanceof NodeClientAbortError) {
-          return;
-        }
-        appLogger.error("Node static build runtime request failed", error);
-        res.statusCode = 500;
-        res.end("Internal Server Error");
-      }
-    });
-    await new Promise((resolve, reject) => {
-      server.once("error", reject);
-      server.listen(port, hostname, () => {
-        server.off("error", reject);
-        resolve();
-      });
-    });
-    this.serverInstance = server;
-    appLogger.info(`Server running at ${this.getListeningServerOrigin(server)}`);
-    return server;
-  }
-  getListeningServerOrigin(server) {
-    const address = server.address();
-    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
-    if (!address || typeof address === "string") {
-      throw new Error("Build runtime server did not expose a numeric listening port");
-    }
-    return `http://${hostname}:${address.port}`;
-  }
-  /**
-   * Gracefully shuts down the ephemeral build runtime server.
-   *
-   * `closeAllConnections()` is called *before* `close()` because `server.close()`
-   * only stops accepting new connections — it waits for existing keep-alive
-   * connections to finish naturally, which can stall the build indefinitely.
-   * `closeAllConnections()` force-closes any lingering sockets immediately so
-   * the `close()` callback fires promptly.
-   *
-   * The `NodeClientBridge` heartbeat is also destroyed here so its `setInterval`
-   * does not prevent the Node.js process from exiting cleanly after the build.
-   */
-  async stopBuildRuntimeServer(server) {
-    await new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-      server.closeAllConnections();
-    });
-    if (this.serverInstance === server) {
-      this.serverInstance = null;
-    }
-    this.bridge?.destroy();
-    this.bridge = null;
-  }
   async createAdapter() {
     await this.initialize();
     return {
@@ -237,9 +170,30 @@ class NodeServerAdapter extends SharedServerAdapter {
       buildStatic: this.buildStatic.bind(this),
       completeInitialization: this.completeInitialization.bind(this),
       handleRequest: this.handleRequest.bind(this),
-      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this)
+      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),
+      dispose: this.dispose.bind(this)
     };
   }
+  /**
+   * Releases dev-time resources owned by the adapter.
+   *
+   * @remarks
+   * Safe to call multiple times. Does not stop the bound HTTP server — callers
+   * should shut down transport through the runtime host before disposing.
+   */
+  async dispose() {
+    if (this.adapterDisposed) {
+      return;
+    }
+    this.adapterDisposed = true;
+    await this.projectWatcher?.close();
+    this.projectWatcher = null;
+    this.hmrManager?.stop();
+    this.hmrManager = null;
+    this.bridge?.destroy();
+    this.bridge = null;
+    await this.previewHost.stop();
+  }
   /**
    * Handles a single incoming Web `Request` and returns a Web `Response`.
    *
@@ -328,6 +282,7 @@ class NodeServerAdapter extends SharedServerAdapter {
         hmrManager: this.hmrManager,
         bridge: this.bridge
       });
+      this.projectWatcher = watcher;
       await watcher.createWatcherSubscription();
     } else if (hasUserWs) {
       this.wireUserWebSocketUpgrades(server);

package/src/adapters/node/static-content-server.d.ts

@@ -56,5 +56,6 @@ export declare class NodeStaticContentServer {
      * Stops the static preview server and optionally closes active connections.
      */
     stop(force?: boolean): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 export {};

package/src/adapters/node/static-content-server.js

@@ -188,6 +188,9 @@ class NodeStaticContentServer {
       }
     });
   }
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
 }
 export {
   NodeStaticContentServer

package/src/adapters/shared/copy-runtime-public-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copies a source public directory into the runtime dist dir, skipping unchanged files.
+ *
+ * Dev restarts call this on every boot; byte comparison avoids rewriting identical assets.
+ */
+export declare function copyRuntimePublicDirIfChanged(sourceDir: string, destinationDir: string): void;

package/src/adapters/shared/copy-runtime-public-dir.js

@@ -0,0 +1,24 @@
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+function copyRuntimePublicDirIfChanged(sourceDir, destinationDir) {
+  fileSystem.ensureDir(destinationDir);
+  for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+    if (entry.isDirectory()) {
+      copyRuntimePublicDirIfChanged(sourcePath, destinationPath);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (fileSystem.exists(destinationPath) && Buffer.compare(fileSystem.readFileAsBuffer(sourcePath), fileSystem.readFileAsBuffer(destinationPath)) === 0) {
+      continue;
+    }
+    fileSystem.copyFile(sourcePath, destinationPath);
+  }
+}
+export {
+  copyRuntimePublicDirIfChanged
+};

package/src/adapters/shared/runtime-app-bootstrap.d.ts

@@ -8,7 +8,6 @@ export type RuntimeBinding = {
     watch: boolean;
 };
 export type StaticRuntimeMode = {
-    requiresFetchRuntime: boolean;
     canBuildWithoutRuntimeServer: boolean;
 };
 export declare function resolveServeRuntimeOrigin(serveOptions: {

package/src/adapters/shared/runtime-app-bootstrap.js

@@ -30,13 +30,8 @@ function resolveRuntimeBinding(options) {
   };
 }
 function resolveStaticRuntimeMode(options) {
-  const requiresFetchRuntime = options.appConfig.integrations.some(
-    (integration) => integration.staticBuildStep === "fetch"
-  );
-  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
   return {
-    requiresFetchRuntime,
-    canBuildWithoutRuntimeServer
+    canBuildWithoutRuntimeServer: options.cliArgs.build || options.cliArgs.preview
   };
 }
 export {

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

@@ -6,6 +6,7 @@ import type { StaticGenerationRendererResolver } from '../../route-renderer/rout
 export interface StaticBuildOptions {
     preview?: boolean;
     baseUrl?: string;
+    force?: boolean;
 }
 export interface ServeOptions {
     hostname?: string;
@@ -55,24 +56,20 @@ export declare class ServerStaticBuilder {
     private readonly previewServerFactory;
     private readonly entryFile;
     constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, entryFile, }: ServerStaticBuilderParams);
-    private warnApiHandlersUnavailableInStaticMode;
     private prepareExportDirectory;
     private refreshRuntimeAssets;
     /**
      * Bundles the server entry file for production use.
      *
      * @remarks
-     * When the project has API endpoints, the entry file must be bundled
-     * into a single JS file so the production server can start without
-     * on-the-fly TypeScript transpilation. The bundle is output to
-     * `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` and used by
-     * `ecopages start` in production.
+     * Every production build emits a runnable server entry for `ecopages start`,
+     * including static-only and websocket-only apps. Incremental builds may skip
+     * Rolldown when the `.eco/.server-entry` cache is still valid.
      *
      * Package imports remain external so native addons and runtime-owned
      * dependencies continue to load through the app's installed
      * `node_modules` tree. Only the app entry graph is bundled.
      *
-     * Skips silently when no API endpoints are registered (static-only site).
      * Throws if the build adapter is unavailable, is owned by a host
      * runtime, or bundling fails.
      *

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

@@ -3,8 +3,19 @@ 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";
-import { getAppBuildAdapter } from "../../build/build-adapter.js";
-import { resolveEntryFile, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "../../utils/resolve-entry-file.js";
+import { build, getAppBuildAdapter } from "../../build/build-adapter.js";
+import {
+  getServerBundleOutputPaths,
+  lookupServerEntryBuildCache,
+  recordServerEntryBuildCache,
+  writeServerBundleDeployManifest
+} from "../../build/server-entry-build-cache.js";
+import { getInstalledServerEntryBuildExecutor } from "../../build/runtime-build-executor.js";
+import {
+  clearProductionBuildCaches,
+  shouldResetStaticExportDirectory
+} from "../../static-site-generator/static-build-invalidation.js";
+import { resolveEntryFile, SERVER_BUNDLE_FILENAME } from "../../utils/resolve-entry-file.js";
 class ServerStaticBuilder {
   appConfig;
   staticSiteGenerator;
@@ -30,24 +41,19 @@ class ServerStaticBuilder {
     this.previewServerFactory = previewServerFactory ?? StaticContentServer;
     this.entryFile = resolveEntryFile({ entryFile });
   }
-  warnApiHandlersUnavailableInStaticMode() {
-    if (this.apiHandlers.length === 0) {
-      return;
+  prepareExportDirectory(force) {
+    if (force) {
+      clearProductionBuildCaches(this.appConfig);
     }
-    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 shouldCleanDist = shouldResetStaticExportDirectory(this.appConfig, force);
+    fileSystem.ensureDir(exportDir, shouldCleanDist);
+    if (shouldCleanDist) {
+      this.appConfig.runtime = {
+        ...this.appConfig.runtime ?? {},
+        runtimeAssetsPrepared: false
+      };
+    }
     const srcPublicDir = path.join(
       this.appConfig.rootDir,
       this.appConfig.srcDir ?? "src",
@@ -56,39 +62,47 @@ class ServerStaticBuilder {
     if (fileSystem.exists(srcPublicDir)) {
       fileSystem.copyDir(srcPublicDir, exportDir);
     }
+    return !shouldCleanDist;
   }
   async refreshRuntimeAssets() {
-    for (const processor of this.appConfig.processors.values()) {
-      await processor.setup();
+    if (this.appConfig.runtime?.runtimeAssetsPrepared) {
+      appLogger.debug("Skipped refreshRuntimeAssets: runtime assets already prepared");
+      return;
     }
-    for (const integration of this.appConfig.integrations) {
-      await integration.setup();
+    appLogger.debugTime("refreshRuntimeAssets");
+    try {
+      for (const processor of this.appConfig.processors.values()) {
+        await processor.setup();
+      }
+      for (const integration of this.appConfig.integrations) {
+        await integration.setup();
+      }
+    } finally {
+      appLogger.debugTimeEnd("refreshRuntimeAssets");
     }
+    this.appConfig.runtime = {
+      ...this.appConfig.runtime ?? {},
+      runtimeAssetsPrepared: true
+    };
   }
   /**
    * Bundles the server entry file for production use.
    *
    * @remarks
-   * When the project has API endpoints, the entry file must be bundled
-   * into a single JS file so the production server can start without
-   * on-the-fly TypeScript transpilation. The bundle is output to
-   * `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` and used by
-   * `ecopages start` in production.
+   * Every production build emits a runnable server entry for `ecopages start`,
+   * including static-only and websocket-only apps. Incremental builds may skip
+   * Rolldown when the `.eco/.server-entry` cache is still valid.
    *
    * Package imports remain external so native addons and runtime-owned
    * dependencies continue to load through the app's installed
    * `node_modules` tree. Only the app entry graph is bundled.
    *
-   * Skips silently when no API endpoints are registered (static-only site).
    * Throws if the build adapter is unavailable, is owned by a host
    * runtime, or bundling fails.
    *
    * @throws If the build adapter is unavailable, is host-owned, or bundling fails.
    */
-  async bundleServerEntry() {
-    if (this.apiHandlers.length === 0) {
-      return;
-    }
+  async bundleServerEntry(options) {
     const buildAdapter = getAppBuildAdapter(this.appConfig);
     if (buildAdapter.ownership === "vite-host") {
       throw new Error(
@@ -101,24 +115,49 @@ class ServerStaticBuilder {
         `Cannot bundle server entry: file "${this.entryFile}" not found in "${this.appConfig.rootDir}".`
       );
     }
-    const distDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
-    const serverOutdir = path.join(distDir, SERVER_BUNDLE_DIR);
-    this.logger.info("Bundling server entry file...");
-    const result = await buildAdapter.build({
-      entrypoints: [entryPath],
-      outdir: serverOutdir,
-      naming: SERVER_BUNDLE_FILENAME,
-      target: "node",
-      format: "esm",
-      sourcemap: "hidden",
-      externalPackages: true,
-      root: this.appConfig.rootDir
+    const { serverOutdir, serverEntryPath } = getServerBundleOutputPaths(this.appConfig);
+    const cached = lookupServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      force: options?.force
     });
+    if (cached) {
+      const hasBundle = cached.outputPaths.some(
+        (outputPath) => path.resolve(outputPath) === path.resolve(serverEntryPath) && fileSystem.exists(outputPath)
+      );
+      if (hasBundle) {
+        this.logger.info("Reusing cached server entry bundle");
+        writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
+        return;
+      }
+    }
+    this.logger.info("Bundling server entry file...");
+    const result = await build(
+      {
+        entrypoints: [entryPath],
+        outdir: serverOutdir,
+        naming: SERVER_BUNDLE_FILENAME,
+        target: "node",
+        format: "esm",
+        sourcemap: "hidden",
+        externalPackages: true,
+        root: this.appConfig.rootDir
+      },
+      getInstalledServerEntryBuildExecutor(this.appConfig)
+    );
     if (!result.success) {
       const errorMessages = result.logs.map((log) => log.message).join("\n");
       throw new Error(`Failed to bundle server entry file:
 ${errorMessages}`);
     }
+    const outputPaths = result.outputs.length > 0 ? result.outputs.map((output) => output.path) : fileSystem.exists(serverEntryPath) ? [serverEntryPath] : [];
+    recordServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      buildResult: result,
+      outputPaths
+    });
+    writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
     this.logger.info("Server entry file bundled successfully");
   }
   /**
@@ -129,17 +168,18 @@ ${errorMessages}`);
    * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
    */
   async build(options, dependencies) {
-    const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+    const { preview = false, baseUrl: explicitBaseUrl, force = false } = options ?? {};
     const baseUrl = explicitBaseUrl ?? `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
-    this.warnApiHandlersUnavailableInStaticMode();
-    this.prepareExportDirectory();
+    const preserveExportDirectory = this.prepareExportDirectory(force);
     await this.refreshRuntimeAssets();
-    await this.bundleServerEntry();
+    await this.bundleServerEntry({ force });
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,
       routeRendererFactory: dependencies.routeRendererFactory,
-      staticRoutes: dependencies.staticRoutes
+      staticRoutes: dependencies.staticRoutes,
+      force,
+      preserveExportDirectory
     });
     if (!preview) {
       this.logger.info("Build completed");

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

@@ -56,5 +56,6 @@ export declare abstract class SharedHmrManager implements IHmrManager {
     protected emitStrictEntrypoint(entrypointPath: string): Promise<void>;
     protected emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
     stop(): void;
+    [Symbol.dispose](): void;
 }
 export {};

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

@@ -2,7 +2,7 @@ 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 { getAppHmrBuildExecutor } 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";
@@ -193,7 +193,7 @@ class SharedHmrManager {
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
       getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
       getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
-      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBuildExecutor: () => getAppHmrBuildExecutor(this.appConfig),
       getBrowserBundleService: () => this.browserBundleService,
       getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
       importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
@@ -238,6 +238,16 @@ class SharedHmrManager {
       appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
       return;
     }
+    if (!fileSystem.exists(outputPath) && buildResult.outputs.length > 0) {
+      const resolvedOutputPath = path.resolve(outputPath);
+      const emittedOutput = buildResult.outputs.find((output) => path.resolve(output.path) === resolvedOutputPath)?.path ?? buildResult.outputs.find((output) => path.basename(output.path) === path.basename(outputPath))?.path;
+      if (emittedOutput && fileSystem.exists(emittedOutput)) {
+        fileSystem.ensureDir(path.dirname(outputPath));
+        if (path.resolve(emittedOutput) !== resolvedOutputPath) {
+          fileSystem.copyFile(emittedOutput, outputPath);
+        }
+      }
+    }
     const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
     if (entrypointDependencies) {
       this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
@@ -253,6 +263,9 @@ class SharedHmrManager {
     this.entrypointDependencyGraph.reset();
     this.plugins = [];
   }
+  [Symbol.dispose]() {
+    this.stop();
+  }
 }
 export {
   SharedHmrManager,

package/src/build/README.md

@@ -10,7 +10,8 @@ Three concentric shapes, plus a serializer and a plugin injector:
 | -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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.                                                                                              |
+| `SerializedBuildExecutor`  | `serialized-build-executor.ts` | FIFO queue around any `BuildExecutor`. Used when strict single-flight ordering is required.                                                                         |
+| `ParallelBuildExecutor`    | `parallel-build-executor.ts`   | Concurrency-limited wrapper for independent route-module and HMR browser builds.                                                                                    |
 | `withBuildExecutorPlugins` | `build-adapter.ts`             | Merges app-owned plugins into every `build` call. The single point of plugin injection.                                                                             |
 
 Plus one translation bridge:
@@ -24,7 +25,8 @@ Plus one translation bridge:
 - `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.
+- `runtime-build-executor.ts`: server-adapter entrypoint that wraps the app-owned adapter in `ParallelBuildExecutor` layers plus `withBuildExecutorPlugins`. Server-entry bundling uses `getInstalledServerEntryBuildExecutor()` (serialized, single-flight, cached on `appConfig.runtime.serverEntryBuildExecutor`).
+- `server-entry-build-cache.ts`: production server-entry bundle cache (`.eco/.server-entry/.build-cache.json` + `dist/.server/manifest.json`).
 - `*.test.ts`: regression coverage.
 
 ## Default Flow
@@ -35,8 +37,10 @@ When a server adapter initializes, it calls `installAppRuntimeBuildExecutor(appC
 
 ```
 BuildExecutor
-  └─ SerializedBuildExecutor            // FIFO queue
-       └─ withBuildExecutorPlugins       // injects app plugins
+  ├─ ParallelBuildExecutor (route modules)   // limited concurrency
+  ├─ ParallelBuildExecutor (HMR browser)     // separate pool, max 3
+  └─ SerializedBuildExecutor (server entry)  // single-flight when used directly
+       └─ withBuildExecutorPlugins
             └─ BuildAdapter (bundled adapter or Vite-host)
 ```
 
@@ -81,6 +85,42 @@ Plugin ordering: the bundler's `resolveId` and `load` are "first" hooks. The bri
 
 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.
 
+## Dev / watch path
+
+`installAppRuntimeBuildExecutor` wraps the app-owned `BuildAdapter` in two `ParallelBuildExecutor` pools (route modules and HMR browser scripts). Both pools share one plugin-wrapped inner executor today.
+
+`RolldownDevBuildAdapter` (DevEngine-backed incremental rebuilds) is available via `createBuildAdapter({ ownership: 'rolldown-dev' })` but is **not** yet selected by `installAppRuntimeBuildExecutor`. HMR browser bundles in `browser-bundle.service.ts` may construct a dedicated dev adapter where needed.
+
+`ProjectWatcher` deduplicates watch roots, ignores `.eco/` and `dist/`, and coalesces duplicate chokidar events within 150ms.
+
+## Production build caches
+
+Two persisted cache layers accelerate production builds. Both use `.build-cache.json` manifests keyed by dependency hashes and a build-inputs fingerprint.
+
+| Cache                                  | On-disk location                                    | Module                              |
+| -------------------------------------- | --------------------------------------------------- | ----------------------------------- |
+| Server-entry bundle                    | `.eco/.server-entry/.build-cache.json`              | `server-entry-build-cache.ts`       |
+| Route-module transpile + static render | `<server-outdir>/.server-modules/.build-cache.json` | `route-module-build-cache.store.ts` |
+
+`getInstalledServerEntryBuildExecutor()` returns one `SerializedBuildExecutor` per app instance (stored on `appConfig.runtime`). `clearProductionBuildCaches()` wipes both manifest trees and resets in-memory route-module state.
+
+The route-module registry (`route-module-build-cache-registry.ts`) shares one `RouteModuleBuildCache` per `(app, outdir)` pair. Legacy `.server-route-modules` outdirs are still read for migration but new writes go to `.server-modules`.
+
+## Unified pages graph
+
+Production static exports compile all template pages in one Rolldown invocation when `shouldBuildPagesUnifiedGraph()` is true (default in production; opt out with `ECOPAGES_UNIFIED_PAGES_GRAPH=0`).
+
+| Artifact       | Location                                              |
+| -------------- | ----------------------------------------------------- |
+| Graph manifest | `.eco/.server-pages-graph/.build-cache.json`          |
+| Chunk outputs  | `.eco/.server-modules/` (shared with per-route cache) |
+
+`StaticSiteGenerator` calls `ensurePagesUnifiedGraphBuilt()` before the export loop. `PageModuleImportService` imports prebuilt chunks via `importPagesUnifiedGraphModule()` and falls back to per-page Rolldown on miss.
+
+`ECOPAGES_ROLLDOWN_BUILD_METRICS=1` enables `rolldown-build-invocation-metrics.ts` counters used by bench and parity tests.
+
+Build-input fingerprinting lives in `build-input-fingerprint.ts` and is shared with server-entry cache, unified pages graph, and static-render invalidation.
+
 ## Testing Strategy
 
 - `rolldown-build-adapter.test.ts` covers the adapter's `build`, `resolve`, `getTranspileOptions`, and dependency-graph extraction end-to-end.

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

@@ -476,12 +476,18 @@ export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig):
  * @remarks
  * Falls back to {@link getAppBuildAdapter} when no executor is set
  * on the runtime yet. The dev-watch pipeline replaces this value with
- * a {@link SerializedBuildExecutor} via
+ * a parallel route-module executor via
  * {@link installAppRuntimeBuildExecutor}.
  */
 export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
-/** Installs the executor that should serve future builds for one app instance. */
+/** Returns the HMR browser-bundle executor when installed. */
+export declare function getAppHmrBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
+/** Route-module executor (page imports, transpile). Falls back to {@link getAppBuildExecutor}. */
+export declare function getAppRouteModuleBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
+/** Installs the default executor for one app instance (ConfigBuilder / tests). */
 export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+export declare function setAppHmrBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+export declare function setAppRouteModuleBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
 /**
  * Runs a build through the active pipeline.
  *