@ecopages/core 0.2.0-beta.26 → 0.2.0-beta.28

package/src/build/README.md

@@ -4,49 +4,94 @@ The build layer is the bundler contract for Ecopages. One bundled adapter is the
 
 ## Mental Model
 
-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). |
-| `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.                                                                             |
+Three concentric shapes, plus profile executors and request policy:
+
+| 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). |
+| `BuildRuntime`              | `runtime/build-runtime.ts`             | Profile-based executor registry. Scheduling, concurrency, and dedupe only.                                                                                          |
+| `BuildExecutor`             | `contracts/build-contracts.ts`         | Narrower runtime facade. Only `build` is exposed. Retrieved via `buildRuntime.getProfile(...)`.                                                                     |
+| `build-request-policy.ts`   | `runtime/build-request-policy.ts`      | Assembles complete `BuildOptions` before scheduling. Server: plugins + JSX ownership. Browser: plugins + source transforms + transpile overlay.                     |
+| `build-request-identity.ts` | `runtime/build-request-identity.ts`    | Canonical request identity for in-flight and request-scope dedupe.                                                                                                  |
+| `SerializedBuildExecutor`   | `runtime/serialized-build-executor.ts` | FIFO queue around any `BuildExecutor`. Used for server-entry single-flight ordering.                                                                                |
+| `ParallelBuildExecutor`     | `runtime/parallel-build-executor.ts`   | Concurrency-limited wrapper for independent route-module and HMR browser builds.                                                                                    |
 
 Plus one translation bridge:
 
-- `rolldown-plugin-bridge.ts` — converts the runtime-agnostic `EcoBuildPlugin[]` array (the contract integrations and processors register) into the bundler's native `Plugin` array. Each `EcoBuildPlugin` becomes its own plugin entry to preserve plugin-priority order.
+- `rolldown/rolldown-plugin-bridge.ts` — converts the runtime-agnostic `EcoBuildPlugin[]` array (the contract integrations and processors register) into the bundler's native `Plugin` array. Each `EcoBuildPlugin` becomes its own plugin entry to preserve plugin-priority order.
 
 ## 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`: 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.
+```
+build/
+  build-adapter.ts              app-owned adapter/manifest wiring
+  app-build-manifest-runtime.ts contributor collection at startup
+  contracts/                    EcoBuildPlugin, BuildOptions, AppBuildManifest
+  runtime/                        profiles, executors, request policy/identity
+  rolldown/                       bundler adapter, plugin bridge, output normalization
+  cache/                          persisted caches, fingerprints, unified pages graph
+  browser/                        client runtime rewrites, JSX ownership, Lit worker guard
+```
+
+- `contracts/build-manifest.ts` + `app-build-manifest-runtime.ts`: sealed `AppBuildManifest` buckets and contributor collection.
+- `build-adapter.ts`: types, factories, and app-owned adapter/manifest helpers.
+- `runtime/build-runtime.ts`: profile-based executor installation (`server-entry`, `route-module`, `browser-hmr`).
+- `runtime/build-request-policy.ts`: server/browser request constructors and plugin collision rules.
+- `runtime/build-request-identity.ts` / `cache/cache-keys.ts`: canonical request identity and shared cache fingerprints.
+- `contracts/build-types.ts`: the `EcoBuildPlugin` contract used by integrations and processors.
+- `rolldown/rolldown-build-adapter.ts`: the production `BuildAdapter`. Wraps the bundler, normalizes Node output imports, and exposes a normalized `BuildResult`.
+- `rolldown/rolldown-plugin-bridge.ts`: `EcoBuildPlugin[]` → bundler-plugin translation.
+- `runtime/serialized-build-executor.ts`: FIFO queue primitive.
+- `cache/server-entry-build-cache.ts`: production server-entry bundle cache (`.eco/.server-entry/.build-cache.json` + `dist/.server/manifest.json`).
+- `cache/cache-constants.ts`: shared `.build-cache.json` filename for persisted production caches.
+- `*.test.ts`: regression coverage colocated with each module.
 
 ## Default Flow
 
-`ConfigBuilder.build()` creates one app-owned adapter and manifest. When a server adapter initializes, it calls `installAppRuntimeBuildExecutor(appConfig)`, which installs `BuildRuntime`:
+`ConfigBuilder.build()` creates one app-owned adapter and manifest. When a server adapter initializes, it calls `installBuildRuntime(appConfig)`:
+
+## App build manifest
+
+`AppBuildManifest` is the sealed registry of build plugins and browser runtime assets on `appConfig.runtime.buildManifest`. Integrations and processors declare contributions through getters; core maps them into manifest buckets during `ConfigBuilder.build()`.
+
+| Integration getter       | Processor getter | Manifest bucket          | Used in                                                          |
+| ------------------------ | ---------------- | ------------------------ | ---------------------------------------------------------------- |
+| — (loaders on config)    | —                | `loaderPlugins`          | Server and browser                                               |
+| `plugins`                | `plugins`        | `runtimePlugins`         | Server and browser                                               |
+| `browserBuildPlugins`    | `buildPlugins`   | `browserBundlePlugins`   | Browser only                                                     |
+| `browserRuntimeManifest` | —                | `browserRuntimeManifest` | Browser (rewrite map; core synthesizes `browser-runtime-plugin`) |
+
+**Sealing flow**
+
+1. `collectConfiguredAppBuildManifestContributions(config)` walks processors and integrations (after `prepareBuildContributions()`).
+2. `updateAppBuildManifest(config, contributions)` merges loader plugins from `config.loaders` with the collected buckets.
+3. `createServerBuildRequest` / `createBrowserBuildRequest` read the sealed manifest through `getAppServerBuildPlugins` / `getAppBrowserBuildPlugins`.
+
+**Rule of thumb**
+
+- Shared transforms (MDX loaders, virtual modules, route-module hooks) → `plugins` / `runtimePlugins`.
+- Client-bundle-only work (vendor aliasing, async production CSS) → `browserBuildPlugins` or `buildPlugins` / `browserBundlePlugins`.
+- Vendor specifier → public URL rewrites → `browserRuntimeManifest` (not a plugin list).
+
+Direct `setAppBuildManifest` is for tests and full manifest replacement. Production code should rely on `updateAppBuildManifest` during config build.
 
 ```
-BuildRuntime.getProfile(...)
-  ├─ server-entry  → SerializedBuildExecutor → withBuildExecutorPlugins → RolldownBuildAdapter
-  ├─ route-module  → ParallelBuildExecutor   → withBuildExecutorPlugins → RolldownBuildAdapter
-  └─ browser-hmr   → ParallelBuildExecutor   → withBuildExecutorPlugins → RolldownBuildAdapter
+Caller intent
+  → createServerBuildRequest / createBrowserBuildRequest (plugins + transforms assembled once)
+  → BuildRuntime.getProfile(...)
+      ├─ server-entry  → SerializedBuildExecutor → RolldownBuildAdapter
+      ├─ route-module  → DedupingBuildExecutor → ParallelBuildExecutor → RolldownBuildAdapter
+      └─ browser-hmr   → DedupingBuildExecutor → ParallelBuildExecutor → RolldownBuildAdapter
+  → RolldownBuildAdapter rewrites Node/browser runtime imports in emitted outputs
 ```
 
-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.
+For `rolldown` ownership, 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. With `vite-host` ownership, the same scheduling wrappers delegate to a boundary marker that rejects framework-owned builds.
 
-Runtime code should call `requireBuildRuntime(appConfig).getProfile('route-module' | 'browser-hmr' | 'server-entry')` instead of reading legacy executor slots.
+Runtime code should call `requireBuildRuntime(appConfig).getProfile('route-module' | 'browser-hmr' | 'server-entry')` with a complete `BuildOptions` object from the request-policy helpers. Profiles are scheduling-only: bare `getProfile(...).build()` does **not** inject app plugins.
 
-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()`.
+The exported `defaultBuildAdapter` and the top-level `build()` / `getTranspileOptions()` helpers are non-app-aware escape hatches. New runtime code should prefer `getAppBuildAdapter()`, `requireBuildRuntime()`, `createServerBuildRequest()`, `createBrowserBuildRequest()`, and `getAppTranspileOptions()`.
+
+`BuildTranspileProfile` (`browser-script` | `hmr-runtime` | `hmr-entrypoint`) selects transpile settings only. `BuildProfile` (`server-entry` | `route-module` | `browser-hmr`) selects the concurrency/dedupe wrapper. `BrowserBundleService` maps `hmr` + (`hmr-entrypoint` | `hmr-runtime`) to the `browser-hmr` profile; all other browser work (including `browser-script`) uses `route-module`.
 
 ## Vite-Host Boundary
 
@@ -71,9 +116,7 @@ Vite-based apps (or any future host runtime) should:
 - `onLoad({ filter, namespace? }, callback)` — the bundler's `load` mapped the same way.
 - `module(specifier, callback)` — declares a virtual module by name, with bundler-side namespace encoding.
 
-Namespace handling: the shared plugin contract scopes handlers with a `namespace` string; the bundler encodes namespaces into the module id. The bridge prepends `<namespace>:` to resolved ids and matches filters against that prefix, then strips it before forwarding back to callbacks. Plugin code keeps the same `path` shape it had on the shared contract.
-
-Plugin ordering: the bundler's `resolveId` and `load` are "first" hooks. The bridge translates each `EcoBuildPlugin` into its own plugin and preserves the array order, so position determines priority: index 0 wins first, the last index is the lowest priority. Security-critical plugins (e.g. `ecopages-client-graph-boundary`) should be placed before general-purpose loaders in the array.
+App-manifest plugins keep canonical registration order and cannot be silently replaced by caller plugins. Use `excludeAppBuildPlugins` on browser requests to omit app-owned plugins explicitly.
 
 ## BuildOptions Caveats
 
@@ -87,7 +130,7 @@ These fields are kept in the type so existing call-sites compile. The proper fix
 
 ## Dev / watch path
 
-`installBuildRuntime` (via `installAppRuntimeBuildExecutor`) installs profile-based executors:
+`installBuildRuntime` installs profile-based executors:
 
 | Profile        | Backend           | Concurrency          |
 | -------------- | ----------------- | -------------------- |
@@ -95,7 +138,9 @@ These fields are kept in the type so existing call-sites compile. The proper fix
 | `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`.
+`hmr-entrypoint` and `hmr-runtime` rebuilds with `executor: 'hmr'` use the `browser-hmr` profile. Other browser builds (`browser-script`, and any build with `executor: 'build'`) use `route-module`.
+
+The table describes `rolldown` ownership. With `vite-host` ownership, profiles wrap `ViteHostBuildAdapter`, which rejects framework-owned builds so the host must run its own pipeline.
 
 `ProjectWatcher` deduplicates watch roots, ignores `.eco/` and `dist/`, and coalesces duplicate chokidar events within 150ms.
 
@@ -107,12 +152,12 @@ Set `ECOPAGES_ROLLDOWN_BUILD_METRICS=1` to log Rolldown invocation counts during
 
 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` |
+| Cache                                  | On-disk location                                    | Module                                               |
+| -------------------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
+| Server-entry bundle                    | `.eco/.server-entry/.build-cache.json`              | `cache/server-entry-build-cache.ts`                  |
+| Route-module transpile + static render | `<server-outdir>/.server-modules/.build-cache.json` | `route-module-build-cache.store.ts` (module-loading) |
 
-`getInstalledServerEntryBuildExecutor()` returns the `server-entry` profile from `BuildRuntime`. `clearProductionBuildCaches()` wipes both manifest trees, resets in-memory route-module state, and clears `buildRuntime`.
+`requireBuildRuntime(appConfig).getProfile('server-entry')` serves server-entry bundling. `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`.
 
@@ -125,11 +170,11 @@ Production static exports compile all template pages in one Rolldown invocation
 | 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.
+`StaticSiteGenerator` calls `ensurePagesUnifiedGraphBuilt()` before the export loop. `PageModuleImportService` imports prebuilt chunks via `importPagesUnifiedGraphModule()` and falls back to per-page Rolldown on miss. This is separate from production Page Browser Graph prebuild (`production-page-browser-graph-prebuild.ts`), which warms browser assets in `page-browser-graph-session`.
 
-`ECOPAGES_ROLLDOWN_BUILD_METRICS=1` enables `rolldown-build-invocation-metrics.ts` counters used by bench and parity tests.
+`ECOPAGES_ROLLDOWN_BUILD_METRICS=1` enables `rolldown/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.
+Build-input fingerprinting lives in `cache/build-input-fingerprint.ts` and is shared with server-entry cache, unified pages graph, and static-render invalidation.
 
 ## JSX Ownership Plugins
 
@@ -145,10 +190,11 @@ Mixed-integration apps need explicit `@jsxImportSource` handling in two differen
 
 ## 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.
-- `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.
+- `rolldown/rolldown-build-adapter.test.ts` covers the adapter's `build`, `resolve`, `getTranspileOptions`, and dependency-graph extraction end-to-end.
+- `rolldown/rolldown-plugin-bridge.test.ts` covers the `EcoBuildPlugin[]` → plugin translation in isolation.
+- `build-adapter.test.ts` covers the app-owned helpers, the `BuildOwnership` routing, and the default-fallback behaviour.
+- `runtime/build-runtime.test.ts` covers profile executor installation and parallelism.
+- `runtime/build-request-policy.test.ts` and `runtime/build-request-identity.test.ts` cover request assembly and dedupe identity.
+- `rolldown/runtime-build-output-normalizer.test.ts` covers Node output finalization.
 
 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

@@ -1,9 +1,35 @@
-import type { EcoBuildPlugin } from './build-types.js';
-import type { AppBuildManifest } from './build-manifest.js';
+import type { EcoBuildPlugin } from './contracts/build-types.js';
+import type { AppBuildManifest } from './contracts/build-manifest.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/**
+ * Collects integration and processor contributions before the app build manifest is sealed.
+ *
+ * @remarks
+ * Called from {@link ConfigBuilder.build} via {@link updateAppBuildManifest}. Walks
+ * processors first, then integrations, invoking {@link Processor.prepareBuildContributions}
+ * and {@link IntegrationPlugin.prepareBuildContributions} so dynamic plugin lists can be
+ * materialized before sealing.
+ *
+ * Maps contributor getters to manifest buckets:
+ * - `processor.plugins` / `integration.plugins` → `runtimePlugins`
+ * - `processor.buildPlugins` / `integration.browserBuildPlugins` → `browserBundlePlugins`
+ * - `integration.browserRuntimeManifest` → merged `browserRuntimeManifest`
+ *
+ * Loaders are not collected here; {@link createConfiguredAppBuildManifest} always takes
+ * them from `appConfig.loaders`.
+ */
 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>;
+/**
+ * Activates one integration's runtime setup on first use.
+ */
+export declare function ensureIntegrationRuntimeReady(options: {
+    appConfig: EcoPagesAppConfig;
+    integrationName: string;
+    runtimeOrigin: string;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
+}): Promise<void>;

package/src/build/app-build-manifest-runtime.js

@@ -1,7 +1,7 @@
-import { mergeBrowserRuntimeManifests } from "./browser-runtime-manifest.js";
+import { mergeBrowserRuntimeManifests } from "./browser/browser-runtime-manifest.js";
 import { appLogger } from "../global/app-logger.js";
 import { startupTrace } from "../diagnostics/startup-trace.js";
-import { isLitStaticRenderWorkerThread } from "./lit-static-render-worker-context.js";
+import { isLitStaticRenderWorkerThread } from "./browser/lit-static-render-worker-context.js";
 function patchAppRuntime(appConfig, patch) {
   appConfig.runtime = {
     ...appConfig.runtime ?? {},
@@ -64,6 +64,9 @@ async function setupAppRuntimePlugins(options) {
   }
   appLogger.debugTime("setupAppRuntimePlugins");
   try {
+    if (options.onRuntimePlugin) {
+      patchAppRuntime(options.appConfig, { onRuntimePlugin: options.onRuntimePlugin });
+    }
     for (const loader of options.appConfig.loaders.values()) {
       options.onRuntimePlugin?.(loader);
     }
@@ -78,21 +81,34 @@ async function setupAppRuntimePlugins(options) {
         }
       }
     }
-    for (const integration of options.appConfig.integrations) {
-      integration.setConfig(options.appConfig);
-      integration.setRuntimeOrigin(options.runtimeOrigin);
-      await integration.setup();
-      for (const plugin of integration.plugins) {
-        options.onRuntimePlugin?.(plugin);
-      }
-    }
     patchAppRuntime(options.appConfig, { runtimeAssetsPrepared: true });
   } finally {
     appLogger.debugTimeEnd("setupAppRuntimePlugins");
     startupTrace.markPhaseEnd("setupAppRuntimePlugins");
   }
 }
+async function ensureIntegrationRuntimeReady(options) {
+  const runtime = options.appConfig.runtime ?? {};
+  options.appConfig.runtime = runtime;
+  runtime.activatedIntegrations ??= /* @__PURE__ */ new Set();
+  if (runtime.activatedIntegrations.has(options.integrationName)) {
+    return;
+  }
+  const integration = options.appConfig.integrations.find((plugin) => plugin.name === options.integrationName);
+  if (!integration) {
+    return;
+  }
+  integration.setConfig(options.appConfig);
+  integration.setRuntimeOrigin(options.runtimeOrigin);
+  await integration.setup();
+  const onRuntimePlugin = options.onRuntimePlugin ?? options.appConfig.runtime?.onRuntimePlugin;
+  for (const plugin of integration.plugins ?? []) {
+    onRuntimePlugin?.(plugin);
+  }
+  runtime.activatedIntegrations.add(options.integrationName);
+}
 export {
   collectConfiguredAppBuildManifestContributions,
+  ensureIntegrationRuntimeReady,
   setupAppRuntimePlugins
 };

package/src/build/{browser-runtime-plugin.d.ts → browser/browser-runtime-plugin.d.ts}

@@ -19,7 +19,7 @@
  * This is the single source of truth for browser-runtime plugin behavior.
  * Per-bundler bridges can treat it as a single plugin.
  */
-import type { EcoBuildPlugin } from './build-types.js';
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
 import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
 /**
  * Symbol used to attach the manifest's `specifier → publicPath` map to a

package/src/build/{browser-runtime-plugin.js → browser/browser-runtime-plugin.js}

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { existsSync, readFileSync } from "node:fs";
-import { cachedParseSync } from "../cache/module-parse-cache.js";
+import { cachedParseSync } from "../../cache/module-parse-cache.js";
 import { getBrowserRuntimeSpecifierMap } from "./browser-runtime-manifest.js";
 import { buildSpecifierFilter } from "./browser-runtime-plugin-helpers.js";
 const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = /* @__PURE__ */ Symbol.for("ecopages.browserRuntimeImportRewriteMap");

package/src/build/{jsx-ownership-plugins.d.ts → browser/jsx-ownership-plugins.d.ts}

@@ -1,5 +1,5 @@
-import type { EcoBuildPlugin } from './build-types.js';
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * Foreign JSX override plugins for mixed-integration app builds.
  *

package/src/build/{jsx-ownership-plugins.js → browser/jsx-ownership-plugins.js}

@@ -1,5 +1,5 @@
-import { createForeignJsxOverridePlugin } from "../plugins/foreign-jsx-override-plugin.js";
-import { collectJsxExtensions, filterJsxSourceExtensions } from "../plugins/jsx-import-source.utils.js";
+import { createForeignJsxOverridePlugin } from "../../plugins/foreign-jsx-override-plugin.js";
+import { collectJsxExtensions, filterJsxSourceExtensions } from "../../plugins/jsx-import-source.utils.js";
 function collectJsxExtensionEntries(appConfig) {
   return (appConfig.integrations ?? []).filter((integration) => integration.jsxImportSource).flatMap(
     (integration) => filterJsxSourceExtensions(integration.extensions).map((extension) => ({ integration, extension }))

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

@@ -15,26 +15,11 @@
  *   per `EcoPagesAppConfig`. Profile executors live on
  *   `appConfig.runtime.buildRuntime`.
  */
-import type { EcoBuildPlugin } from './build-types.js';
-import { type BuildAdapter, type BuildExecutor, type BuildOptions, type BuildOwnership, type BuildResult, type BuildTranspileOptions, type BuildTranspileProfile } from './build-contracts.js';
-export type { BuildAdapter, BuildDependencyGraph, BuildExecutor, BuildLog, BuildOptions, BuildOutput, BuildOwnership, BuildResult, BuildTranspileOptions, BuildTranspileProfile, } from './build-contracts.js';
-import { type AppBuildManifest } from './build-manifest.js';
+import type { EcoBuildPlugin } from './contracts/build-types.js';
+import { type BuildAdapter, type BuildExecutor, type BuildOptions, type BuildOwnership, type BuildResult, type BuildTranspileOptions, type BuildTranspileProfile } from './contracts/build-contracts.js';
+export type { BuildAdapter, BuildDependencyGraph, BuildExecutor, BuildLog, BuildOptions, BuildOutput, BuildOwnership, BuildResult, BuildTranspileOptions, BuildTranspileProfile, } from './contracts/build-contracts.js';
+import { type AppBuildManifest } from './contracts/build-manifest.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
-/**
- * Wraps a {@link BuildExecutor} so each call to `build` receives the
- * union of the caller's `options.plugins` and the plugins sourced
- * from `getPlugins()`.
- *
- * @remarks
- * The single point of plugin injection in the runtime path: the
- * `ConfigBuilder` stores a raw adapter on
- * `appConfig.runtime.buildAdapter` and the
- * `installAppRuntimeBuildExecutor` step wraps that adapter with this
- * helper. Callers that issue builds through
- * `requireBuildRuntime(appConfig).getProfile(...)` get the merged plugin set
- * without further ceremony.
- */
-export declare function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor;
 /**
  * Boundary-marker adapter for Vite-host ownership.
  *
@@ -140,7 +125,14 @@ export declare function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAd
  * services.
  */
 export declare function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest;
-/** Installs the build manifest that should be visible to one app instance. */
+/** Installs the build manifest that should be visible to one app instance.
+ *
+ * @remarks
+ * Production apps are sealed via {@link updateAppBuildManifest} during
+ * {@link ConfigBuilder.build}. Call `setAppBuildManifest` directly only in tests or
+ * when replacing the entire manifest object; partial updates should use
+ * {@link updateAppBuildManifest}.
+ */
 export declare function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void;
 /**
  * Builds a fresh app manifest from the config's loaders plus optional
@@ -156,9 +148,14 @@ export declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppC
 /**
  * Replaces the app-owned manifest using config-owned loaders and the
  * caller-supplied contribution input.
+ *
+ * @remarks
+ * Primary production entry: `ConfigBuilder.build()` passes the return value of
+ * {@link collectConfiguredAppBuildManifestContributions} here to seal
+ * `appConfig.runtime.buildManifest` before startup.
  */
 export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
-export { collectConfiguredAppBuildManifestContributions, setupAppRuntimePlugins, } from './app-build-manifest-runtime.js';
+export { collectConfiguredAppBuildManifestContributions, ensureIntegrationRuntimeReady, setupAppRuntimePlugins, } from './app-build-manifest-runtime.js';
 /**
  * Returns the server-bundle plugin list for one app/runtime instance.
  *

package/src/build/build-adapter.js

@@ -1,42 +1,14 @@
-import { normalizeNodeRuntimeBuildOutputs } from "./runtime-build-output-normalizer.js";
 import {
-} from "./build-contracts.js";
+} from "./contracts/build-contracts.js";
 import {
   createAppBuildManifest,
   getBrowserBuildPlugins,
   getServerBuildPlugins
-} from "./build-manifest.js";
+} from "./contracts/build-manifest.js";
 import { getAppSourceTransforms } from "../plugins/source-transform.js";
 import { createAliasResolverPlugin } from "../plugins/alias-resolver-plugin.js";
-import { getJsxOwnershipPlugins } from "./jsx-ownership-plugins.js";
-import { createRolldownBuildAdapter } from "./rolldown-build-adapter.js";
-function mergeBuildExecutorPlugins(existing, appPlugins) {
-  if (!existing || existing.length === 0) {
-    return appPlugins;
-  }
-  const byName = /* @__PURE__ */ new Map();
-  for (const plugin of existing) {
-    byName.set(plugin.name, plugin);
-  }
-  for (const plugin of appPlugins) {
-    byName.set(plugin.name, plugin);
-  }
-  return Array.from(byName.values());
-}
-function withBuildExecutorPlugins(executor, getPlugins) {
-  return {
-    async build(options) {
-      const appPlugins = getPlugins();
-      if (appPlugins.length === 0) {
-        return executor.build(options);
-      }
-      return executor.build({
-        ...options,
-        plugins: mergeBuildExecutorPlugins(options.plugins, appPlugins)
-      });
-    }
-  };
-}
+import { getJsxOwnershipPlugins } from "./browser/jsx-ownership-plugins.js";
+import { createRolldownBuildAdapter } from "./rolldown/rolldown-build-adapter.js";
 function patchAppRuntime(appConfig, patch) {
   appConfig.runtime = {
     ...appConfig.runtime ?? {},
@@ -117,6 +89,7 @@ function updateAppBuildManifest(appConfig, input) {
 }
 import {
   collectConfiguredAppBuildManifestContributions,
+  ensureIntegrationRuntimeReady,
   setupAppRuntimePlugins
 } from "./app-build-manifest-runtime.js";
 function getAppServerBuildPlugins(appConfig) {
@@ -133,15 +106,7 @@ function getAppBrowserBuildPlugins(appConfig) {
   return [...aliasPlugin, ...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
 }
 function build(options, executor = defaultRolldownBuildAdapter) {
-  return executor.build(options).then((result) => {
-    if (result.success) {
-      normalizeNodeRuntimeBuildOutputs(
-        result.outputs.map((output) => output.path),
-        options.root ?? process.cwd()
-      );
-    }
-    return result;
-  });
+  return executor.build(options);
 }
 function getTranspileOptions(profile) {
   return defaultRolldownBuildAdapter.getTranspileOptions(profile);
@@ -159,6 +124,7 @@ export {
   defaultBuildAdapter,
   defaultRolldownBuildAdapter,
   defaultViteHostBuildAdapter,
+  ensureIntegrationRuntimeReady,
   getAppBrowserBuildPlugins,
   getAppBuildAdapter,
   getAppBuildManifest,
@@ -172,6 +138,5 @@ export {
   setAppBuildManifest,
   setAppBuildOwnership,
   setupAppRuntimePlugins,
-  updateAppBuildManifest,
-  withBuildExecutorPlugins
+  updateAppBuildManifest
 };

package/src/build/{build-input-fingerprint.d.ts → cache/build-input-fingerprint.d.ts}

@@ -1,6 +1,6 @@
-import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
-import type { Processor } from '../plugins/processor.js';
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { Processor } from '../../plugins/processor.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * Optional contributor surface for build-time cache invalidation.
  *

package/src/build/cache/cache-constants.d.ts

@@ -0,0 +1,4 @@
+/** Filename written beside persisted production build artifacts that store incremental metadata. */
+export declare const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
+/** @deprecated Use {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}; server-entry caches share the same filename. */
+export declare const SERVER_ENTRY_BUILD_CACHE_FILENAME = ".build-cache.json";

package/src/build/cache/cache-constants.js

@@ -0,0 +1,6 @@
+const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
+const SERVER_ENTRY_BUILD_CACHE_FILENAME = ROUTE_MODULE_BUILD_CACHE_FILENAME;
+export {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME,
+  SERVER_ENTRY_BUILD_CACHE_FILENAME
+};

package/src/build/cache/cache-keys.d.ts

@@ -0,0 +1,22 @@
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
+import type { BuildOptions } from '../contracts/build-contracts.js';
+/**
+ * Returns the installed `@ecopages/core` package version for cache invalidation.
+ */
+export declare function getCorePackageVersion(): string;
+/** Stable fingerprint for JSX options used in build and disk cache keys. */
+export declare function createJsxCacheKey(jsx: BuildOptions['jsx']): string;
+/** Stable fingerprint for ordered build plugins. */
+export declare function createPluginCacheKey(plugins?: EcoBuildPlugin[]): string;
+/** Stable fingerprint for ordered source transforms. */
+export declare function createSourceTransformCacheKey(sourceTransforms: BuildOptions['sourceTransforms']): string;
+/**
+ * Stable fingerprint of a function body for cache and request identity keys.
+ *
+ * @remarks
+ * Hashes `fn.toString()`. Suitable for in-process and persisted keys that must
+ * agree within one install; not stable across minifiers or renames.
+ */
+export declare function hashFunctionIdentity(fn: (...args: never[]) => unknown): string;
+/** @deprecated Use {@link hashFunctionIdentity}. */
+export declare const hashPluginSetup: typeof hashFunctionIdentity;

package/src/build/cache/cache-keys.js

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+let cachedCorePackageVersion;
+function getCorePackageVersion() {
+  if (cachedCorePackageVersion) {
+    return cachedCorePackageVersion;
+  }
+  const packageJsonPath = new URL("../../../package.json", import.meta.url);
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  cachedCorePackageVersion = packageJson.version ?? "0.0.0";
+  return cachedCorePackageVersion;
+}
+function createJsxCacheKey(jsx) {
+  if (!jsx) {
+    return "jsx:default";
+  }
+  return JSON.stringify({
+    development: jsx.development ?? false,
+    factory: jsx.factory ?? null,
+    fragment: jsx.fragment ?? null,
+    importSource: jsx.importSource ?? null,
+    runtime: jsx.runtime ?? null,
+    sideEffects: jsx.sideEffects ?? null
+  });
+}
+function createPluginCacheKey(plugins) {
+  if (!plugins || plugins.length === 0) {
+    return "plugins:default";
+  }
+  return `plugins:${plugins.map((plugin) => `${plugin.name}:${hashFunctionIdentity(plugin.setup)}`).join(",")}`;
+}
+function createSourceTransformCacheKey(sourceTransforms) {
+  if (!sourceTransforms || sourceTransforms.length === 0) {
+    return "sourceTransforms:default";
+  }
+  return `sourceTransforms:${sourceTransforms.map((transform) => {
+    const filterSource = transform.filter.source;
+    const filterFlags = transform.filter.flags;
+    return [
+      transform.name,
+      transform.enforce ?? "default",
+      filterSource,
+      filterFlags,
+      hashFunctionIdentity(transform.transform)
+    ].join(":");
+  }).join(",")}`;
+}
+function hashFunctionIdentity(fn) {
+  let hash = 0;
+  const source = fn.toString();
+  for (let index = 0; index < source.length; index += 1) {
+    hash = hash * 31 + source.charCodeAt(index) | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+const hashPluginSetup = hashFunctionIdentity;
+export {
+  createJsxCacheKey,
+  createPluginCacheKey,
+  createSourceTransformCacheKey,
+  getCorePackageVersion,
+  hashFunctionIdentity,
+  hashPluginSetup
+};

package/src/build/{dev-browser-script-cache.d.ts → cache/dev-browser-script-cache.d.ts}

@@ -1,5 +1,5 @@
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/assets.types.js';
 export declare const DEV_BROWSER_SCRIPT_CACHE_DIR = ".browser-script-bundles";
 export declare const DEV_BROWSER_SCRIPT_CACHE_FILENAME = ".build-cache.json";
 /** Output path restored from the dev disk cache before dependency metadata is merged. */