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

package/src/build/rolldown-dev-build-adapter.js

@@ -8,7 +8,17 @@ import {
   toBuildLogs,
   transpileProfileToOptions
 } from "./rolldown-adapter-helpers.js";
+import { recordRolldownBuildInvocation } from "./rolldown-build-invocation-metrics.js";
 const moduleRequire = createRequire(import.meta.url);
+function normalizeEntrypointList(entrypoints) {
+  if (Array.isArray(entrypoints)) {
+    return entrypoints.map((entrypoint) => path.resolve(entrypoint)).sort();
+  }
+  if (entrypoints && typeof entrypoints === "object") {
+    return Object.values(entrypoints).map((entrypoint) => path.resolve(entrypoint)).sort();
+  }
+  return [];
+}
 class RolldownDevBuildAdapter {
   /**
    * `'rolldown-dev'` (not `'rolldown'`) so {@link getBuildAdapterOwnership}
@@ -22,12 +32,22 @@ class RolldownDevBuildAdapter {
   appRootRequireCache = /* @__PURE__ */ new Map();
   /**
    * Stable key over the inputs that affect the engine configuration.
-   * Plugin order is intentionally not part of the key: two plugin
-   * sets with the same names are interchangeable for caching.
+   * Output paths and entrypoints must participate — HMR registers many
+   * distinct script entrypoints with literal naming under the same outdir.
    */
-  getCacheKey(plugins, contextRoot, target, format) {
-    const pluginNames = plugins.map((p) => p.name).join(":");
-    return `${contextRoot}::${pluginNames}::${target ?? "default"}::${format ?? "esm"}`;
+  getCacheKey(options, contextRoot) {
+    const pluginNames = (options.plugins ?? []).map((plugin) => plugin.name).sort().join(":");
+    const outdir = path.resolve(options.outdir ?? "dist/assets");
+    const entrypoints = normalizeEntrypointList(options.entrypoints).join("|");
+    return [
+      contextRoot,
+      pluginNames,
+      options.target ?? "default",
+      options.format ?? "esm",
+      outdir,
+      options.naming ?? "[name]",
+      entrypoints
+    ].join("::");
   }
   /**
    * Returns the cached engine, creating a new one when the cache
@@ -36,15 +56,9 @@ class RolldownDevBuildAdapter {
    */
   async getOrCreateEngine(options, contextRoot) {
     const bundlePlugins = options.plugins ?? [];
-    const cacheKey = this.getCacheKey(bundlePlugins, contextRoot, options.target, options.format);
+    const cacheKey = this.getCacheKey(options, contextRoot);
     if (this.cachedEngine) {
-      const existingKey = this.getCacheKey(
-        this.cachedEngine.bundlePlugins,
-        this.cachedEngine.contextRoot,
-        options.target,
-        options.format
-      );
-      if (existingKey === cacheKey) {
+      if (this.cachedEngine.cacheKey === cacheKey) {
         return this.cachedEngine;
       }
       await this.cachedEngine.engine.close();
@@ -73,7 +87,8 @@ class RolldownDevBuildAdapter {
       engine,
       engineStarted: false,
       contextRoot,
-      bundlePlugins
+      bundlePlugins,
+      cacheKey
     };
     this.engineInstanceCount += 1;
     return this.cachedEngine;
@@ -108,6 +123,7 @@ class RolldownDevBuildAdapter {
   }
   /** Throws on error; see {@link build} for the no-throw variant. */
   async buildOrThrow(options) {
+    recordRolldownBuildInvocation("rolldown-dev");
     const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
     const outdir = path.resolve(options.outdir ?? "dist/assets");
     const plugins = options.plugins ?? [];

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

@@ -1,21 +1,15 @@
 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.
+ * Installs the app-owned runtime build executors for one app instance.
  *
  * @remarks
- * Wraps the app-owned adapter in a {@link SerializedBuildExecutor} so
- * every dev-watch caller issues builds against a single FIFO queue.
- * Plugin injection is applied here via {@link withBuildExecutorPlugins}
- * so app-owned plugins are merged into every rebuild without callers
- * having to know about the manifest.
+ * Route-module and HMR browser builds run through a {@link ParallelBuildExecutor}
+ * so independent compiles can overlap. Server-entry bundling continues to call
+ * the raw adapter directly and stays single-flight by design.
  *
- * Idempotent across calls: re-invoking replaces the existing executor
- * on `appConfig.runtime` with a fresh wrapper.
- *
- * @param appConfig - The app config whose runtime state is updated.
- *   The function reads the existing executor (falling back to the
- *   app-owned adapter) and writes the wrapped executor back.
- * @returns The installed {@link BuildExecutor}.
+ * Idempotent across calls: re-invoking replaces the existing executors on
+ * `appConfig.runtime` with fresh wrappers.
  */
 export declare function installAppRuntimeBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
+export declare function getInstalledServerEntryBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;

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

@@ -1,19 +1,43 @@
+import { availableParallelism } from "node:os";
 import {
   getAppBuildAdapter,
-  getAppBuildExecutor,
   getAppServerBuildPlugins,
   setAppBuildExecutor,
+  setAppHmrBuildExecutor,
+  setAppRouteModuleBuildExecutor,
   withBuildExecutorPlugins
 } from "./build-adapter.js";
+import { ParallelBuildExecutor } from "./parallel-build-executor.js";
 import { SerializedBuildExecutor } from "./serialized-build-executor.js";
+function createPluginWrappedExecutor(appConfig) {
+  return withBuildExecutorPlugins(getAppBuildAdapter(appConfig), () => getAppServerBuildPlugins(appConfig));
+}
+function resolveParallelismLimit() {
+  return Math.max(1, availableParallelism() - 1);
+}
 function installAppRuntimeBuildExecutor(appConfig) {
-  const baseExecutor = getAppBuildExecutor(appConfig) ?? getAppBuildAdapter(appConfig);
-  const buildExecutor = new SerializedBuildExecutor(
-    withBuildExecutorPlugins(baseExecutor, () => getAppServerBuildPlugins(appConfig))
-  );
-  setAppBuildExecutor(appConfig, buildExecutor);
-  return buildExecutor;
+  const pluginWrappedExecutor = createPluginWrappedExecutor(appConfig);
+  const parallelismLimit = resolveParallelismLimit();
+  const routeModuleBuildExecutor = new ParallelBuildExecutor(pluginWrappedExecutor, parallelismLimit);
+  const hmrBuildExecutor = new ParallelBuildExecutor(pluginWrappedExecutor, Math.min(3, parallelismLimit));
+  setAppRouteModuleBuildExecutor(appConfig, routeModuleBuildExecutor);
+  setAppHmrBuildExecutor(appConfig, hmrBuildExecutor);
+  setAppBuildExecutor(appConfig, routeModuleBuildExecutor);
+  return routeModuleBuildExecutor;
+}
+function getInstalledServerEntryBuildExecutor(appConfig) {
+  const existing = appConfig.runtime?.serverEntryBuildExecutor;
+  if (existing) {
+    return existing;
+  }
+  const serverEntryBuildExecutor = new SerializedBuildExecutor(createPluginWrappedExecutor(appConfig));
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    serverEntryBuildExecutor
+  };
+  return serverEntryBuildExecutor;
 }
 export {
+  getInstalledServerEntryBuildExecutor,
   installAppRuntimeBuildExecutor
 };

package/src/build/server-entry-build-cache.d.ts

@@ -0,0 +1,44 @@
+import type { BuildResult } from './build-adapter.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/** @deprecated Use {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}; both caches share the same manifest filename. */
+export declare const SERVER_ENTRY_BUILD_CACHE_FILENAME = ".build-cache.json";
+export declare const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
+export interface ServerBundleDeployManifest {
+    serverEntry: string;
+    distDir: string;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheManifest {
+    invalidationVersion: string;
+    entryPath: string;
+    entryHash: string;
+    buildInputsFingerprint: string;
+    buildKey: string;
+    outputPaths: string[];
+    dependencyHashes: Record<string, string>;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheLookup {
+    manifest: ServerEntryBuildCacheManifest;
+    outputPaths: string[];
+}
+export declare function getServerBundleOutputPaths(appConfig: EcoPagesAppConfig): {
+    distDir: string;
+    serverOutdir: string;
+    serverEntryPath: string;
+    manifestPath: string;
+};
+export declare function readServerEntryBuildCacheManifest(appConfig: EcoPagesAppConfig): ServerEntryBuildCacheManifest | undefined;
+export declare function writeServerBundleDeployManifest(appConfig: EcoPagesAppConfig, serverEntryPath: string): void;
+export declare function lookupServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    force?: boolean;
+}): ServerEntryBuildCacheLookup | undefined;
+export declare function recordServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    buildResult: BuildResult;
+    outputPaths: string[];
+}): void;
+export declare function resolveProductionServerEntry(cwd?: string): string | undefined;

package/src/build/server-entry-build-cache.js

@@ -0,0 +1,169 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { getAppServerBuildPlugins } from "./build-adapter.js";
+import { createBuildInputsFingerprint } from "./build-input-fingerprint.js";
+import { getCorePackageVersion } from "../services/module-loading/route-module-build-manifest.js";
+import {
+  RouteModuleDependencyHasher,
+  createRouteModuleDependencyHashes
+} from "../services/module-loading/route-module-dependency-hasher.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
+import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "../utils/resolve-entry-file.js";
+import { ROUTE_MODULE_BUILD_CACHE_FILENAME } from "../services/module-loading/route-module-build-manifest.js";
+const SERVER_ENTRY_BUILD_CACHE_FILENAME = ROUTE_MODULE_BUILD_CACHE_FILENAME;
+const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
+function getServerEntryCacheDir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), ".server-entry");
+}
+function getServerEntryCacheManifestPath(appConfig) {
+  return path.join(getServerEntryCacheDir(appConfig), SERVER_ENTRY_BUILD_CACHE_FILENAME);
+}
+function hashDependencyGraph(entryPath, dependencyGraph, hasher, rootDir) {
+  if (!dependencyGraph) {
+    return { [path.resolve(entryPath)]: fileSystem.hash(entryPath) };
+  }
+  return createRouteModuleDependencyHashes(hasher, { dependencyGraph }, entryPath, rootDir);
+}
+function createServerEntryBuildKey(appConfig) {
+  try {
+    const plugins = getAppServerBuildPlugins(appConfig);
+    const pluginNames = plugins.map((plugin) => plugin.name).sort().join("|");
+    return ["node", "esm", "external-packages", pluginNames].join("::");
+  } catch {
+    return "node::esm::external-packages";
+  }
+}
+function getServerBundleOutputPaths(appConfig) {
+  const distDir = appConfig.absolutePaths?.distDir ?? path.join(appConfig.rootDir, appConfig.distDir);
+  const serverOutdir = path.join(distDir, SERVER_BUNDLE_DIR);
+  const serverEntryPath = path.join(serverOutdir, SERVER_BUNDLE_FILENAME);
+  const manifestPath = path.join(serverOutdir, SERVER_BUNDLE_MANIFEST_FILENAME);
+  return { distDir, serverOutdir, serverEntryPath, manifestPath };
+}
+function readServerEntryBuildCacheManifest(appConfig) {
+  const manifestPath = getServerEntryCacheManifestPath(appConfig);
+  if (!fileSystem.exists(manifestPath)) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+    if (!parsed || typeof parsed !== "object") {
+      return void 0;
+    }
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+function writeServerEntryBuildCacheManifest(appConfig, manifest) {
+  const cacheDir = getServerEntryCacheDir(appConfig);
+  fileSystem.ensureDir(cacheDir);
+  fileSystem.write(
+    path.join(cacheDir, SERVER_ENTRY_BUILD_CACHE_FILENAME),
+    `${JSON.stringify(manifest, null, "	")}
+`
+  );
+}
+function writeServerBundleDeployManifest(appConfig, serverEntryPath) {
+  const { distDir, manifestPath } = getServerBundleOutputPaths(appConfig);
+  fileSystem.ensureDir(path.dirname(manifestPath));
+  const payload = {
+    serverEntry: path.relative(path.dirname(manifestPath), serverEntryPath) || SERVER_BUNDLE_FILENAME,
+    distDir,
+    builtAt: Date.now()
+  };
+  fileSystem.write(manifestPath, `${JSON.stringify(payload, null, "	")}
+`);
+}
+function lookupServerEntryBuildCache(options) {
+  if (options.force) {
+    return void 0;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    return void 0;
+  }
+  const entryPath = path.resolve(options.entryPath);
+  const entryHash = fileSystem.hash(entryPath);
+  const buildInputsFingerprint = createBuildInputsFingerprint(options.appConfig);
+  const buildKey = createServerEntryBuildKey(options.appConfig);
+  const manifest = readServerEntryBuildCacheManifest(options.appConfig);
+  if (!manifest) {
+    return void 0;
+  }
+  if (manifest.invalidationVersion !== getCorePackageVersion()) {
+    return void 0;
+  }
+  if (manifest.entryPath !== entryPath || manifest.entryHash !== entryHash || manifest.buildInputsFingerprint !== buildInputsFingerprint || manifest.buildKey !== buildKey) {
+    return void 0;
+  }
+  const hasher = new RouteModuleDependencyHasher();
+  if (!hasher.matchesStoredHashes(manifest.dependencyHashes, entryPath, entryHash)) {
+    return void 0;
+  }
+  const existingOutputs = manifest.outputPaths.filter((outputPath) => fileSystem.exists(outputPath));
+  if (existingOutputs.length === 0) {
+    return void 0;
+  }
+  return {
+    manifest,
+    outputPaths: existingOutputs
+  };
+}
+function recordServerEntryBuildCache(options) {
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  const entryPath = path.resolve(options.entryPath);
+  const entryHash = fileSystem.hash(entryPath);
+  const hasher = new RouteModuleDependencyHasher();
+  const dependencyHashes = hashDependencyGraph(
+    entryPath,
+    options.buildResult.dependencyGraph,
+    hasher,
+    options.appConfig.rootDir
+  );
+  const manifest = {
+    invalidationVersion: getCorePackageVersion(),
+    entryPath,
+    entryHash,
+    buildInputsFingerprint: createBuildInputsFingerprint(options.appConfig),
+    buildKey: createServerEntryBuildKey(options.appConfig),
+    outputPaths: options.outputPaths,
+    dependencyHashes,
+    builtAt: Date.now()
+  };
+  writeServerEntryBuildCacheManifest(options.appConfig, manifest);
+}
+function resolveProductionServerEntry(cwd = process.cwd()) {
+  const manifestPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_MANIFEST_FILENAME);
+  if (fileSystem.exists(manifestPath)) {
+    try {
+      const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+      if (parsed?.serverEntry) {
+        const fromManifest = path.isAbsolute(parsed.serverEntry) ? parsed.serverEntry : path.join(path.dirname(manifestPath), parsed.serverEntry);
+        if (fileSystem.exists(fromManifest)) {
+          return fromManifest;
+        }
+      }
+      if (parsed?.distDir) {
+        const fromDistDir = path.join(parsed.distDir, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+        if (fileSystem.exists(fromDistDir)) {
+          return fromDistDir;
+        }
+      }
+    } catch {
+    }
+  }
+  const legacyPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+  return fileSystem.exists(legacyPath) ? legacyPath : void 0;
+}
+export {
+  SERVER_BUNDLE_MANIFEST_FILENAME,
+  SERVER_ENTRY_BUILD_CACHE_FILENAME,
+  getServerBundleOutputPaths,
+  lookupServerEntryBuildCache,
+  readServerEntryBuildCacheManifest,
+  recordServerEntryBuildCache,
+  resolveProductionServerEntry,
+  writeServerBundleDeployManifest
+};

package/src/hmr/hmr.test.e2e.js

@@ -4,6 +4,15 @@ import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 const FIXTURE_DIR = resolve(process.cwd(), "packages/core/__fixtures__/app");
 const TEST_CSS_FILE = resolve(FIXTURE_DIR, "src/pages/index.css");
+async function readMainTitleColor(page) {
+  return page.evaluate(() => {
+    const element = document.querySelector(".main-title");
+    if (!(element instanceof HTMLElement)) {
+      return "";
+    }
+    return getComputedStyle(element).color;
+  });
+}
 test.describe("HMR E2E", () => {
   test("should load page with .main-title element", async ({ page }) => {
     await page.goto("/", { waitUntil: "networkidle" });
@@ -23,9 +32,10 @@ test.describe("HMR E2E", () => {
     const originalCss = readFileSync(TEST_CSS_FILE, "utf-8");
     const title = page.locator(".main-title").first();
     try {
-      await page.goto("/", { waitUntil: "networkidle" });
+      await page.goto("/", { waitUntil: "domcontentloaded" });
       await expect(title).toBeVisible();
-      const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+      await expect.poll(async () => readMainTitleColor(page), { timeout: 1e4 }).not.toBe("");
+      const initialColor = await readMainTitleColor(page);
       expect(initialColor).toBeTruthy();
       const modifiedCss = originalCss.replace(".main-title {", ".main-title {\n	color: rgb(255, 0, 0);");
       const reloadPromise = page.waitForEvent("framenavigated", {
@@ -34,8 +44,9 @@ test.describe("HMR E2E", () => {
       });
       await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
       await reloadPromise;
-      await page.waitForLoadState("networkidle");
-      await expect.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 1e4 }).toBe("rgb(255, 0, 0)");
+      await page.waitForLoadState("domcontentloaded");
+      await expect(title).toBeVisible();
+      await expect.poll(async () => readMainTitleColor(page), { timeout: 1e4 }).toBe("rgb(255, 0, 0)");
     } finally {
       await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
     }

package/src/plugins/integration-plugin.d.ts

@@ -6,10 +6,12 @@ import type { EcoPagesElement } from '../types/public-types.js';
 import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
 import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
 export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
+export type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
 /**
  * Type-erased integration plugin stored in app-level registries.
@@ -47,13 +49,6 @@ export interface IntegrationPluginConfig {
      * They are not specific to any particular page or component.
      */
     integrationDependencies?: AssetDefinition[];
-    /**
-     * The strategy to use for static building.
-     * - 'render': Execute component function directly (faster, efficient).
-     * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
-     * @default 'render'
-     */
-    staticBuildStep?: 'render' | 'fetch';
     /**
      * Declares runtime-specific requirements that must be satisfied before the
      * app can start with this integration enabled.
@@ -96,7 +91,6 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     readonly name: string;
     readonly extensions: string[];
     abstract renderer: RendererClass<C>;
-    readonly staticBuildStep: 'render' | 'fetch';
     readonly runtimeCapability?: RuntimeCapabilityDeclaration;
     readonly jsxImportSource?: string;
     protected integrationDependencies: AssetDefinition[];
@@ -213,6 +207,23 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this integration's build inputs changed since the last
+     * incremental static build.
+     */
+    didChange(): boolean;
+    /**
+     * Runs integration-specific setup before static page generation begins.
+     *
+     * @remarks
+     * Integrations that need build-scoped SSR preload or worker sessions should
+     * start them here rather than per-page inside the renderer.
+     */
+    beforeStaticExport?(_context: StaticExportContext): Promise<void>;
+    /**
+     * Releases resources started in {@link beforeStaticExport}.
+     */
+    afterStaticExport?(_context: StaticExportContext): Promise<void>;
     /**
      * Performs runtime-only integration setup after config build has already
      * sealed manifest contributions.

package/src/plugins/integration-plugin.js

@@ -15,7 +15,6 @@ function assertIntegrationInvariant(condition, message) {
 class IntegrationPlugin {
   name;
   extensions;
-  staticBuildStep;
   runtimeCapability;
   jsxImportSource;
   integrationDependencies;
@@ -60,7 +59,6 @@ class IntegrationPlugin {
     this.name = config.name;
     this.extensions = config.extensions;
     this.integrationDependencies = config.integrationDependencies || [];
-    this.staticBuildStep = config.staticBuildStep || "render";
     this.runtimeCapability = config.runtimeCapability;
     this.jsxImportSource = config.jsxImportSource;
   }
@@ -169,6 +167,13 @@ class IntegrationPlugin {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this integration's build inputs changed since the last
+   * incremental static build.
+   */
+  didChange() {
+    return false;
+  }
   /**
    * Performs runtime-only integration setup after config build has already
    * sealed manifest contributions.

package/src/plugins/processor.d.ts

@@ -80,6 +80,11 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
      * warming or watcher registration should stay in `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this processor's build inputs changed since the last
+     * incremental static build.
+     */
+    didChange(): boolean;
     abstract setup(): Promise<void>;
     abstract teardown(): Promise<void>;
     abstract process(input: unknown, filePath?: string): Promise<unknown>;

package/src/plugins/processor.js

@@ -54,6 +54,13 @@ class Processor {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this processor's build inputs changed since the last
+   * incremental static build.
+   */
+  didChange() {
+    return false;
+  }
   getCachePath(key) {
     return `${this.context?.cache}/${key}`;
   }

package/src/route-renderer/GRAPH.md

@@ -33,11 +33,11 @@ flowchart TD
 
 ## 2) Route Render Flow
 
-`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderFlow`.
+`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderOrchestrator`.
 
 ```mermaid
 flowchart TD
-  A[IntegrationRenderer.execute] --> B[RouteRenderFlow.prepareRenderOptions]
+  A[IntegrationRenderer.execute] --> B[RouteRenderOrchestrator.prepareRenderOptions]
   B --> C[resolvePageModule]
   C --> D[ownershipValidationService.validate]
   D --> E[resolvePageData]
@@ -121,7 +121,7 @@ flowchart TD
 The most useful reading order is:
 
 1. `route-renderer.ts`
-2. `orchestration/route-render-flow.ts`
+2. `orchestration/route-render-orchestrator.ts`
 3. `orchestration/integration-renderer.ts`
 4. `orchestration/ownership-validation.service.ts`
 5. `orchestration/ownership-planning.service.ts`
@@ -134,7 +134,7 @@ The most useful reading order is:
 ## 7) Key Files
 
 - `packages/core/src/route-renderer/route-renderer.ts`
-- `packages/core/src/route-renderer/orchestration/route-render-flow.ts`
+- `packages/core/src/route-renderer/orchestration/route-render-orchestrator.ts`
 - `packages/core/src/route-renderer/orchestration/integration-renderer.ts`
 - `packages/core/src/route-renderer/orchestration/ownership-validation.service.ts`
 - `packages/core/src/route-renderer/orchestration/ownership-planning.service.ts`

package/src/route-renderer/README.md

@@ -27,7 +27,7 @@ These concepts intentionally live in different places:
 - `component-render-context.ts` intercepts foreign children during active component render
 - `queued-foreign-subtree-resolution.service.ts` resolves queued foreign subtrees for renderers that cannot hand them off inline
 - `integration-renderer.ts` owns renderer-to-renderer delegation and shared shell composition
-- `route-render-flow.ts` owns route preparation, final response capture, and unresolved artifact enforcement
+- `route-render-orchestrator.ts` owns route preparation, final response capture, and unresolved artifact enforcement
 
 ## Main Files
 
@@ -38,7 +38,7 @@ These concepts intentionally live in different places:
 
 ### `orchestration/`
 
-- `route-render-flow.ts`: one route render from page-module loading through final HTML output
+- `route-render-orchestrator.ts`: one route render from page-module loading through final HTML output
 - `integration-renderer.ts`: abstract base class for route rendering, explicit view rendering, and foreign-child delegation
 - `ownership-planning.service.ts`: declared ownership graph construction
 - `ownership-validation.service.ts`: up-front ownership validation for route roots and declared descendants
@@ -56,11 +56,11 @@ These concepts intentionally live in different places:
 The route-render contract is:
 
 1. `RouteRendererFactory` selects the owning integration renderer.
-2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderFlow`.
-3. `RouteRenderFlow.prepareRenderOptions()` loads the page module, validates ownership, builds `ownershipPlan`, resolves page data, resolves dependencies, and builds the page browser graph.
+2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderOrchestrator`.
+3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership, builds `ownershipPlan`, resolves page data, resolves dependencies, and builds the page browser graph.
 4. The integration renderer performs page, layout, and document-shell rendering. When it encounters a foreign child, it delegates that child back to the owning renderer.
 5. If a renderer needs queued handoff, it emits internal foreign-subtree tokens and resolves them before returning final HTML.
-6. `RouteRenderFlow.execute()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
+6. `RouteRenderOrchestrator.executePrepared()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
 
 Important:
 
@@ -115,4 +115,5 @@ Not every integration needs queue-based handoff.
 ## Current Limits
 
 - `ownershipPlan` is still diagnostic and preparatory metadata; it does not yet drive a full route-composer execution model.
+- `integration-renderer.ts` remains large (~1,400 lines); document-shell helpers and foreign-subtree wiring are the likely future extraction targets.
 - Different integrations still own different foreign-child runtime strategies, which is intentional where child transport or hydration behavior differs.

package/src/route-renderer/orchestration/foreign-subtree-execution.service.js

@@ -5,9 +5,7 @@ import {
 import {
   QueuedForeignSubtreeResolutionService
 } from "./queued-foreign-subtree-resolution.service.js";
-function isMarkupNodeLike(value) {
-  return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && (!("outerHTML" in value) || typeof value.outerHTML === "string");
-}
+import { isMarkupNodeLike } from "./render-output.utils.js";
 class ForeignSubtreeExecutionService {
   queuedForeignSubtreeResolutionService;
   constructor(queuedForeignSubtreeResolutionService = new QueuedForeignSubtreeResolutionService()) {

package/src/route-renderer/orchestration/integration-renderer.d.ts

@@ -4,7 +4,7 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, PagePackageResult, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
 import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
@@ -59,7 +59,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     protected pageModuleLoaderService: PageModuleLoaderService;
     protected routeRenderOrchestrator: RouteRenderOrchestrator;
     protected readonly foreignSubtreeExecutionService: ForeignSubtreeExecutionService;
+    /**
+     * Serializes route and view renders that mutate `htmlTransformer` state.
+     *
+     * Integration renderers are cached per integration, so concurrent static builds
+     * and overlapping SSR requests must not share one transformer page package.
+     */
+    private renderExclusiveChain;
     protected DOC_TYPE: string;
+    private runRenderExclusive;
     /**
      * Loads one route module through the owning renderer's import path.
      *
@@ -351,7 +359,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     }): Promise<ComponentRenderResult | undefined>;
     protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
     protected getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
-    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
+    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
     /**
      * Prepares the render options for the integration renderer.
      * It imports the page file, collects dependencies, and prepares the render options.