@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -2,11 +2,18 @@ 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 {
+  removeStaleHmrEntrypointOutput,
+  isRegisteredScriptEntrypoint,
+  isBrowserOnlyRegisteredScriptEntrypoint
+} from "../../hmr/hmr-entrypoint-output.js";
+import { requireBuildRuntime } from "../../build/build-runtime.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 { ServerRenderedTemplateHmrStrategy } from "../../hmr/strategies/server-rendered-template-hmr-strategy.js";
+import { DevelopmentInvalidationService } from "../../services/invalidation/development-invalidation.service.js";
 import { appLogger } from "../../global/app-logger.js";
 import { HmrEntrypointRegistrar } from "./hmr-entrypoint-registrar.js";
 import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
@@ -20,29 +27,27 @@ class SharedHmrManager {
   appConfig;
   bridge;
   watchers = /* @__PURE__ */ new Map();
-  watchedFiles = /* @__PURE__ */ new Map();
-  entrypointRegistrations = /* @__PURE__ */ new Map();
   distDir;
-  plugins = [];
-  enabled = true;
+  enabled = false;
   strategies = [];
   entrypointRegistrar;
   browserBundleService;
+  invalidationService;
   entrypointDependencyGraph;
   serverModuleTranspiler;
-  constructor({ appConfig, bridge, registrationTimeoutMs = 4e3 }) {
+  runtimeBuildPromise = null;
+  runtimeReady = false;
+  constructor({ appConfig, bridge }) {
     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
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath)
     });
     this.browserBundleService = new BrowserBundleService(appConfig);
+    this.invalidationService = new DevelopmentInvalidationService(appConfig);
     this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(
       getAppEntrypointDependencyGraph(appConfig)
     );
@@ -75,9 +80,8 @@ class SharedHmrManager {
   }
   initializeStrategies() {
     const jsContext = {
-      getWatchedFiles: () => this.watchedFiles,
+      getWatchedFiles: () => this.entrypointRegistrar.getWatchedFiles(),
       getDistDir: () => this.distDir,
-      getPlugins: () => this.plugins,
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
       getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
       getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
@@ -86,41 +90,81 @@ class SharedHmrManager {
       getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
       shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
     };
-    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+    const invalidationService = new DevelopmentInvalidationService(this.appConfig);
+    this.strategies = [
+      new JsHmrStrategy(jsContext),
+      new ServerRenderedTemplateHmrStrategy(invalidationService),
+      new DefaultHmrStrategy()
+    ];
   }
   registerStrategy(strategy) {
     this.strategies.push(strategy);
   }
-  setPlugins(plugins) {
-    this.plugins = [...plugins];
-  }
   setEnabled(enabled) {
     this.enabled = enabled;
   }
   isEnabled() {
     return this.enabled;
   }
+  isRuntimeReady() {
+    return this.runtimeReady && fileSystem.exists(this.getRuntimePath());
+  }
+  /**
+   * Builds the browser HMR runtime once per manager session and reuses the in-flight build for concurrent callers.
+   */
+  async ensureRuntimeReady() {
+    if (this.runtimeReady) {
+      return true;
+    }
+    if (this.runtimeBuildPromise) {
+      return this.runtimeBuildPromise;
+    }
+    this.runtimeBuildPromise = this.buildRuntimeInternal();
+    try {
+      const ready = await this.runtimeBuildPromise;
+      this.runtimeReady = ready;
+      return ready;
+    } finally {
+      this.runtimeBuildPromise = null;
+    }
+  }
   async buildRuntime() {
+    await this.ensureRuntimeReady();
+  }
+  getRuntimePath() {
+    return path.join(this.distDir, "_hmr_runtime.js");
+  }
+  async buildRuntimeInternal() {
     const runtimeSource = fileURLToPath(import.meta.resolve("@ecopages/core/hmr/client/hmr-runtime"));
+    const runtimePath = this.getRuntimePath();
+    removeStaleHmrEntrypointOutput(runtimePath, "HMR");
     try {
       const result = await this.browserBundleService.bundle({
         profile: "hmr-runtime",
         entrypoints: [runtimeSource],
         outdir: this.distDir,
         naming: "_hmr_runtime.js",
-        minify: false,
-        plugins: this.plugins
+        minify: false
       });
       if (!result.success) {
         this.onRuntimeBundleFailure(result.logs);
+        return false;
+      }
+      const emittedRuntime = result.outputs.find(
+        (output) => path.resolve(output.path) === path.resolve(runtimePath)
+      );
+      if (!emittedRuntime || !fileSystem.exists(runtimePath)) {
+        this.onRuntimeBundleFailure(
+          new Error(`[HMR] Runtime bundle missing expected output at ${runtimePath}`)
+        );
+        return false;
       }
+      return true;
     } catch (error) {
       this.onRuntimeBundleFailure(error);
+      return false;
     }
   }
-  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}`
@@ -128,20 +172,16 @@ class SharedHmrManager {
     this.bridge.broadcast(event);
   }
   async handleFileChange(filePath, options = {}) {
+    const resolvedFilePath = path.resolve(filePath);
     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 (isRegisteredScriptEntrypoint(this.entrypointRegistrar.getRegistered(), resolvedFilePath)) {
+      await this.prepareRegisteredScriptChange(resolvedFilePath);
+    }
+    const strategy = this.selectChangeStrategy(filePath);
     if (!strategy) {
       appLogger.warn(`[HMR] No strategy found for ${filePath}`);
       return;
@@ -155,27 +195,123 @@ class SharedHmrManager {
       }
     }
   }
+  getStrategiesByPriority() {
+    return [...this.strategies].sort((left, right) => right.priority - left.priority);
+  }
+  selectChangeStrategy(filePath) {
+    return this.getStrategiesByPriority().find((candidate) => {
+      try {
+        return candidate.matches(filePath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  selectEntrypointEmitter(entrypointPath) {
+    return this.getStrategiesByPriority().find((candidate) => {
+      if (candidate.type !== HmrStrategyType.INTEGRATION) {
+        return false;
+      }
+      try {
+        return candidate.canEmitEntrypoint(entrypointPath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  createUnownedEntrypointError(entrypointPath) {
+    return new Error(
+      `[HMR] No integration owns entrypoint ${entrypointPath}. Page entrypoints must be emitted by their owning integration.`
+    );
+  }
+  /**
+   * Materializes one integration-owned page entrypoint during cold registration.
+   *
+   * @remarks
+   * Registration uses {@link HmrStrategy.canEmitEntrypoint} / {@link HmrStrategy.emitEntrypoint},
+   * not {@link HmrStrategy.matches} / {@link HmrStrategy.process}. File-change handling stays
+   * on `handleFileChange()`.
+   */
+  async emitIntegrationEntrypoint(entrypointPath, outputPath) {
+    const emitter = this.selectEntrypointEmitter(entrypointPath);
+    if (!emitter) {
+      throw this.createUnownedEntrypointError(entrypointPath);
+    }
+    appLogger.debug(`[${this.constructor.name}] Selected entrypoint emitter: ${emitter.constructor.name}`);
+    await emitter.emitEntrypoint(entrypointPath, outputPath);
+  }
+  /**
+   * Runs server invalidation and integration hooks before rebuilding a registered script entrypoint.
+   *
+   * @remarks
+   * Browser-only `*.script.ts` entrypoints skip server module invalidation and bypass-cache
+   * import; only integration change handlers and the downstream strategy rebuild run.
+   */
+  async prepareRegisteredScriptChange(filePath) {
+    const isBrowserOnlyRegisteredScript = isBrowserOnlyRegisteredScriptEntrypoint(filePath);
+    if (!isBrowserOnlyRegisteredScript) {
+      this.invalidationService.invalidateServerModules([filePath]);
+    }
+    const handlers = this.appConfig.runtime?.registeredScriptEntrypointChangeHandlers ?? [];
+    for (const handler of handlers) {
+      try {
+        await handler(filePath);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : `Failed to handle registered script entrypoint change for ${filePath}: ${String(error)}`;
+        this.broadcast({ type: "error", message });
+        throw error;
+      }
+    }
+    if (isBrowserOnlyRegisteredScript) {
+      return;
+    }
+    const appModuleLoader = this.appConfig.runtime?.appModuleLoader;
+    if (!appModuleLoader) {
+      return;
+    }
+    await appModuleLoader.importModule({
+      filePath,
+      rootDir: this.appConfig.rootDir,
+      outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+      externalPackages: true,
+      bypassCache: true
+    });
+  }
   getOutputUrl(entrypointPath) {
-    return this.watchedFiles.get(entrypointPath);
+    return this.entrypointRegistrar.getRegistered().get(path.resolve(entrypointPath))?.outputUrl;
+  }
+  /**
+   * Returns the emitted HMR script output when the entrypoint is already registered
+   * and its browser bundle exists on disk.
+   *
+   * @remarks
+   * Disk artifacts alone are not enough: a fresh dev session must still register
+   * the entrypoint so file watchers can rebuild it on change.
+   */
+  getResolvedScriptOutput(entrypointPath) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const registered = this.entrypointRegistrar.getRegistered().get(normalizedEntrypoint);
+    if (!registered || !fileSystem.exists(registered.outputPath)) {
+      return void 0;
+    }
+    return registered;
   }
   getWatchedFiles() {
-    return this.watchedFiles;
+    return this.entrypointRegistrar.getWatchedFiles();
   }
   getDistDir() {
     return this.distDir;
   }
-  getPlugins() {
-    return this.plugins;
-  }
   getDefaultContext() {
     return {
-      getWatchedFiles: () => this.watchedFiles,
+      getWatchedFiles: () => this.entrypointRegistrar.getWatchedFiles(),
       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),
+      getBuildExecutor: () => requireBuildRuntime(this.appConfig).getProfile("browser-hmr"),
       getBrowserBundleService: () => this.browserBundleService,
       getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
       importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
@@ -185,27 +321,34 @@ class SharedHmrManager {
       })
     };
   }
+  stop() {
+    this.runtimeReady = false;
+    this.entrypointRegistrar.clearAll();
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.entrypointDependencyGraph.reset();
+  }
   clearFailedEntrypointRegistration(entrypointPath) {
-    this.watchedFiles.delete(entrypointPath);
+    this.entrypointRegistrar.clearRegistration(entrypointPath);
     this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
   }
   async registerEntrypoint(entrypointPath) {
-    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
-      emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
+    const resolved = await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitIntegrationEntrypoint(normalizedEntrypoint, outputPath),
       getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
         `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
       )
     });
+    return resolved.outputUrl;
   }
   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}`)
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint} to ${outputPath}`)
     });
   }
-  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({
@@ -213,27 +356,30 @@ class SharedHmrManager {
       entrypoints: [entrypointPath],
       outdir: this.distDir,
       naming,
-      minify: false,
-      plugins: this.plugins
+      minify: false
     });
     if (!buildResult.success) {
-      appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
-      return;
+      throw new Error(
+        `[HMR] Generic script entrypoint build failed for ${entrypointPath}: ${JSON.stringify(buildResult.logs)}`
+      );
+    }
+    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);
     }
   }
-  stop() {
-    this.entrypointRegistrations.clear();
-    for (const watcher of this.watchers.values()) {
-      watcher.close();
-    }
-    this.watchers.clear();
-    this.watchedFiles.clear();
-    this.entrypointDependencyGraph.reset();
-    this.plugins = [];
+  [Symbol.dispose]() {
+    this.stop();
   }
 }
 export {

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

@@ -7,4 +7,9 @@ export interface StaticPreviewHostStartOptions {
     appConfig: EcoPagesAppConfig;
     hostname: string;
     port: number;
+    /**
+     * When true, bind to the next available port if the preferred one is busy.
+     * Should remain false when the port was explicitly configured.
+     */
+    allowPortFallback?: boolean;
 }

package/src/adapters/shared/websocket-lifecycle.d.ts

@@ -0,0 +1,24 @@
+import type { EcopagesSocket, WebSocketCloseInfo } from '../../types/public-types.js';
+/**
+ * @remarks
+ * Bun and Node expose different raw socket types but share the same
+ * {@link OutgoingWebSocketMessage} contract. Adapters supply only `send`/`close`;
+ * {@link createEcopagesSocket} owns message normalization and stream forwarding.
+ */
+export interface WebSocketSendTransport {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * @remarks
+ * Bun and Node adapters previously duplicated outgoing-message dispatch and
+ * stream forwarding; this is the shared implementation both transports delegate to.
+ */
+export declare function createEcopagesSocket<TContext, TParams extends Record<string, string>>(transport: WebSocketSendTransport, meta: {
+    kind: string;
+    params: TParams;
+    search: Record<string, string>;
+    context: TContext;
+}): EcopagesSocket<TContext, TParams>;
+export declare function toWebSocketCloseInfo(code: number, reason: string): WebSocketCloseInfo;
+export declare function invokeWebSocketHandlerHook(kind: string, hookName: string, result: void | Promise<void>): void;

package/src/adapters/shared/websocket-lifecycle.js

@@ -0,0 +1,55 @@
+import { appLogger } from "../../global/app-logger.js";
+function sendOutgoingMessage(transport, message) {
+  if (typeof message === "string") {
+    transport.send(message);
+  } else if (message instanceof Blob) {
+    void message.arrayBuffer().then((buffer) => transport.send(new Uint8Array(buffer)));
+  } else if (message instanceof ArrayBuffer) {
+    transport.send(new Uint8Array(message));
+  } else if (ArrayBuffer.isView(message)) {
+    transport.send(new Uint8Array(message.buffer, message.byteOffset, message.byteLength));
+  } else {
+    transport.send(message);
+  }
+}
+function createEcopagesSocket(transport, meta) {
+  return {
+    kind: meta.kind,
+    params: meta.params,
+    search: meta.search,
+    context: meta.context,
+    send: (message) => sendOutgoingMessage(transport, message),
+    sendStream: async (stream) => {
+      const reader = stream.getReader();
+      try {
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (value) transport.send(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    },
+    close: (code, reason) => transport.close(code, reason)
+  };
+}
+function toWebSocketCloseInfo(code, reason) {
+  return {
+    code,
+    reason,
+    wasClean: code === 1e3 || code === 1001
+  };
+}
+function invokeWebSocketHandlerHook(kind, hookName, result) {
+  if (result instanceof Promise) {
+    result.catch((error) => {
+      appLogger.error(`[WS:${kind}] ${hookName} failed:`, error);
+    });
+  }
+}
+export {
+  createEcopagesSocket,
+  invokeWebSocketHandlerHook,
+  toWebSocketCloseInfo
+};

package/src/build/README.md

@@ -4,13 +4,15 @@ The build layer is the bundler contract for Ecopages. One bundled adapter is the
 
 ## Mental Model
 
-Three concentric shapes, plus a serializer and a plugin injector:
+Three concentric shapes, plus profile executors and a plugin injector:
 
 | Shape                      | Lives in                       | Purpose                                                                                                                                                             |
 | -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `BuildAdapter`             | `build-adapter.ts`             | Low-level backend. Two implementations: the bundled adapter (the real bundler) and `ViteHostBuildAdapter` (a host-owned boundary marker that throws on direct use). |
-| `BuildExecutor`            | `build-adapter.ts`             | Narrower runtime facade. Only `build` is exposed. Stored on `appConfig.runtime.buildExecutor`.                                                                      |
-| `SerializedBuildExecutor`  | `serialized-build-executor.ts` | FIFO queue around any `BuildExecutor`. Used by the dev watch pipeline.                                                                                              |
+| `BuildRuntime`             | `build-runtime.ts`             | Profile-based executor registry. Single entry point on `appConfig.runtime.buildRuntime`.                                                                            |
+| `BuildExecutor`            | `build-contracts.ts`           | Narrower runtime facade. Only `build` is exposed. Retrieved via `buildRuntime.getProfile(...)`.                                                                     |
+| `SerializedBuildExecutor`  | `serialized-build-executor.ts` | FIFO queue around any `BuildExecutor`. Used for server-entry single-flight ordering.                                                                                |
+| `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:
@@ -20,29 +22,31 @@ Plus one translation bridge:
 ## Files
 
 - `build-adapter.ts`: types, factories, app-owned helpers, `withBuildExecutorPlugins`.
+- `build-runtime.ts`: profile-based executor installation (`server-entry`, `route-module`, `browser-hmr`).
 - `build-types.ts`: the `EcoBuildPlugin` contract used by integrations and processors.
 - `rolldown-build-adapter.ts`: the production `BuildAdapter`. Wraps the bundler and exposes a normalized `BuildResult` (outputs, dependency graph, logs).
 - `rolldown-plugin-bridge.ts`: `EcoBuildPlugin[]` → bundler-plugin translation.
 - `serialized-build-executor.ts`: FIFO queue primitive.
-- `runtime-build-executor.ts`: dev-watch entrypoint that wraps the app-owned adapter in a `SerializedBuildExecutor + withBuildExecutorPlugins` chain.
+- `runtime-build-executor.ts`: server-adapter entrypoint that installs `BuildRuntime` via `installAppRuntimeBuildExecutor()`.
+- `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
 
-`ConfigBuilder.build()` creates one app-owned adapter, manifest, executor, dev graph, and runtime registry. The executor it stores is the raw `BuildAdapter`; the plugin-wrap step lives in the runtime path.
-
-When a server adapter initializes, it calls `installAppRuntimeBuildExecutor(appConfig)`. That function reads the existing executor (or falls back to the app-owned adapter) and stores a fresh wrapper:
+`ConfigBuilder.build()` creates one app-owned adapter and manifest. When a server adapter initializes, it calls `installAppRuntimeBuildExecutor(appConfig)`, which installs `BuildRuntime`:
 
 ```
-BuildExecutor
-  └─ SerializedBuildExecutor            // FIFO queue
-       └─ withBuildExecutorPlugins       // injects app plugins
-            └─ BuildAdapter (bundled adapter or Vite-host)
+BuildRuntime.getProfile(...)
+  ├─ server-entry  → SerializedBuildExecutor → withBuildExecutorPlugins → RolldownBuildAdapter
+  ├─ route-module  → ParallelBuildExecutor   → withBuildExecutorPlugins → RolldownBuildAdapter
+  └─ browser-hmr   → ParallelBuildExecutor   → withBuildExecutorPlugins → RolldownBuildAdapter
 ```
 
-Every dev-watch caller reads `appConfig.runtime.buildExecutor` and gets the merged plugin set without further ceremony.
+All profiles use one-shot Rolldown in both dev and production. Route-module and browser-HMR builds run in parallel; server-entry stays serialized single-flight.
+
+Runtime code should call `requireBuildRuntime(appConfig).getProfile('route-module' | 'browser-hmr' | 'server-entry')` instead of reading legacy executor slots.
 
-The exported `defaultBuildAdapter` and the top-level `build()` / `getTranspileOptions()` helpers are non-app-aware escape hatches. New runtime code should prefer `getAppBuildAdapter()`, `getAppBuildExecutor()`, and `getAppTranspileOptions()`.
+The exported `defaultBuildAdapter` and the top-level `build()` / `getTranspileOptions()` helpers are non-app-aware escape hatches. New runtime code should prefer `getAppBuildAdapter()`, `requireBuildRuntime()`, and `getAppTranspileOptions()`.
 
 ## Vite-Host Boundary
 
@@ -81,11 +85,70 @@ 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
+
+`installBuildRuntime` (via `installAppRuntimeBuildExecutor`) installs profile-based executors:
+
+| Profile        | Backend           | Concurrency          |
+| -------------- | ----------------- | -------------------- |
+| `server-entry` | Rolldown one-shot | Serialized           |
+| `route-module` | Rolldown one-shot | Parallel             |
+| `browser-hmr`  | Rolldown one-shot | Parallel (limit ≤ 3) |
+
+`hmr-entrypoint` rebuilds use the `browser-hmr` profile. Other browser builds (`browser-script`, `hmr-runtime`) use `route-module`.
+
+`ProjectWatcher` deduplicates watch roots, ignores `.eco/` and `dist/`, and coalesces duplicate chokidar events within 150ms.
+
+## Metrics
+
+Set `ECOPAGES_ROLLDOWN_BUILD_METRICS=1` to log Rolldown invocation counts during dev and production builds. Compare kitchen-sink dev navigation and `static-build-bench` before/after runtime changes.
+
+## 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 the `server-entry` profile from `BuildRuntime`. `clearProductionBuildCaches()` wipes both manifest trees, resets in-memory route-module state, and clears `buildRuntime`.
+
+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.
+
+## JSX Ownership Plugins
+
+Mixed-integration apps need explicit `@jsxImportSource` handling in two different shapes:
+
+| Helper                               | Use when                                  | Behavior                                                                                                                |
+| ------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `getJsxOwnershipPlugins()`           | App-wide server/transpile builds          | Each JSX integration extension gets its **own** `jsxImportSource` so native files keep their owning runtime.            |
+| `getHostScopedJsxOwnershipPlugins()` | One integration's **client** bundle graph | Foreign `.tsx`/`.jsx` files compile with the **host** integration JSX runtime (for example React bundling `.kita.tsx`). |
+| `eco-component-meta-plugin`          | Component metadata injection              | Prepends the **owning** integration pragma only when injecting `__eco` metadata into native files.                      |
+
+`foreign-jsx-override-plugin.ts` is the shared implementation. Prefer the helpers above instead of calling it directly from integrations.
+
 ## Testing Strategy
 
 - `rolldown-build-adapter.test.ts` covers the adapter's `build`, `resolve`, `getTranspileOptions`, and dependency-graph extraction end-to-end.
 - `rolldown-plugin-bridge.test.ts` covers the `EcoBuildPlugin[]` → plugin translation in isolation.
 - `build-adapter.test.ts` covers the app-owned helpers, the `BuildOwnership` routing, the `withBuildExecutorPlugins` injection, and the default-fallback behaviour.
-- `runtime-build-executor.test.ts` covers the dev-watch wrapper: serialization, plugin injection, and the Vite-host rejection path.
+- `build-runtime.test.ts` covers profile executor installation and parallelism.
+- `runtime-build-executor.test.ts` covers the runtime wrapper: plugin injection and the Vite-host rejection path.
 
 If you change option mapping or plugin-bridge semantics, update the adapter and bridge tests first. If you change the app-owned helper contracts, update `build-adapter.test.ts` first.

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

@@ -0,0 +1,9 @@
+import type { EcoBuildPlugin } from './build-types.js';
+import type { AppBuildManifest } from './build-manifest.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins' | 'browserRuntimeManifest'>>;
+export declare function setupAppRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
+}): Promise<void>;