@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

package/src/build/README.md

@@ -2,51 +2,113 @@
 
 The build layer is the bundler contract for Ecopages. One bundled adapter is the default; one host-owned boundary marker covers the Vite-host path.
 
+## Contents
+
+- [Mental Model](#mental-model)
+- [Files](#files)
+- [Default Flow](#default-flow)
+- [App build manifest](#app-build-manifest)
+- [Vite-Host Boundary](#vite-host-boundary)
+- [Plugin Authoring](#plugin-authoring)
+- [BuildOptions Caveats](#buildoptions-caveats)
+- [Dev / watch path](#dev--watch-path)
+- [Metrics](#metrics)
+- [Production build caches](#production-build-caches)
+- [Unified pages graph](#unified-pages-graph)
+- [JSX Ownership Plugins](#jsx-ownership-plugins)
+- [Rolldown operator notes](#rolldown-operator-notes)
+- [Testing Strategy](#testing-strategy)
+
 ## Mental Model
 
-Three concentric shapes, plus a serializer and a plugin injector:
+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). |
-| `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 when strict single-flight ordering is required.                                                                         |
-| `ParallelBuildExecutor`    | `parallel-build-executor.ts`   | Concurrency-limited wrapper for independent route-module and HMR browser builds.                                                                                    |
-| `withBuildExecutorPlugins` | `build-adapter.ts`             | Merges app-owned plugins into every `build` call. The single point of plugin injection.                                                                             |
+| 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-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 wraps the app-owned adapter in `ParallelBuildExecutor` layers plus `withBuildExecutorPlugins`. Server-entry bundling uses `getInstalledServerEntryBuildExecutor()` (serialized, single-flight, cached on `appConfig.runtime.serverEntryBuildExecutor`).
-- `server-entry-build-cache.ts`: production server-entry bundle cache (`.eco/.server-entry/.build-cache.json` + `dist/.server/manifest.json`).
-- `*.test.ts`: regression coverage.
+```
+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, manifest, executor, dev graph, and runtime registry. The executor it stores is the raw `BuildAdapter`; the plugin-wrap step lives in the runtime path.
+`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`.
 
-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:
+**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.
 
 ```
-BuildExecutor
-  ├─ ParallelBuildExecutor (route modules)   // limited concurrency
-  ├─ ParallelBuildExecutor (HMR browser)     // separate pool, max 3
-  └─ SerializedBuildExecutor (server entry)  // single-flight when used directly
-       └─ withBuildExecutorPlugins
-            └─ BuildAdapter (bundled adapter or Vite-host)
+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
 ```
 
-Every dev-watch caller reads `appConfig.runtime.buildExecutor` and gets the merged plugin set without further ceremony.
+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')` 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()`, `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()`, `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,15 +133,13 @@ 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
 
 `BuildOptions` is modeled on the bundler's options shape. Most fields map cleanly. The exceptions:
 
-- `splitting` — accepted but currently ignored. The bundler splits by default. The per-chunk naming is fixed to `[name]-[hash]`. If you need to disable splitting or rename chunks, the adapter will need a new option.
+- `splitting` — when `false` with a single entrypoint, maps to Rolldown `codeSplitting: false` so dynamic imports stay in one file. Multi-entrypoint builds ignore `splitting: false` because Rolldown cannot inline across multiple inputs.
 - `bundle` — accepted but ignored. The bundler always bundles.
 - `outbase` — accepted but ignored. The adapter derives the base from `options.root` directly.
 
@@ -87,22 +147,34 @@ These fields are kept in the type so existing call-sites compile. The proper fix
 
 ## Dev / watch path
 
-`installAppRuntimeBuildExecutor` wraps the app-owned `BuildAdapter` in two `ParallelBuildExecutor` pools (route modules and HMR browser scripts). Both pools share one plugin-wrapped inner executor today.
+`installBuildRuntime` installs profile-based executors:
 
-`RolldownDevBuildAdapter` (DevEngine-backed incremental rebuilds) is available via `createBuildAdapter({ ownership: 'rolldown-dev' })` but is **not** yet selected by `installAppRuntimeBuildExecutor`. HMR browser bundles in `browser-bundle.service.ts` may construct a dedicated dev adapter where needed.
+| 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` 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.
 
+## 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` |
+| 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 one `SerializedBuildExecutor` per app instance (stored on `appConfig.runtime`). `clearProductionBuildCaches()` wipes both manifest trees and resets in-memory route-module state.
+`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`.
 
@@ -115,17 +187,65 @@ 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/rolldown-build-invocation-metrics.ts` counters used by bench and parity tests.
+
+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
+
+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`). |
+| component identity source transform  | Component identity attribution            | Prepends the **owning** integration pragma when injecting `identity` into native files.                                 |
+
+`foreign-jsx-override-plugin.ts` is the shared implementation. Prefer the helpers above instead of calling it directly from integrations.
+
+## Rolldown operator notes
+
+Ecopages bundles with Rolldown across Node, Bun, and browser targets. Vite-hosted apps use `ViteHostBuildAdapter` as a boundary marker; the host runs its own pipeline.
+
+### Plugin hook filters
+
+Rolldown evaluates plugin hooks on the Rust side and only calls JavaScript when the filter matches. Hooks without filters run for every module through Rust→JS FFI, causing **3–4× slowdown** with multiple plugins.
+
+```typescript
+// BAD — called for every module
+resolveId(source, importer) { /* ... */ }
+
+// GOOD — skipped unless the filter matches
+resolveId: {
+  filter: { id: /\.tsx?$/ },
+  handler(source, importer) { /* ... */ },
+}
+```
+
+If patterns are dynamic (populated during `buildStart`), Rolldown cannot use filters because they are read at registration time. Consolidate dynamic plugins into a **single** Rolldown plugin to minimize FFI calls. See [rolldown.rs/reference/plugin-hooks](https://rolldown.rs/reference/plugin-hooks).
+
+### Consolidate plugins
+
+Each Rolldown plugin adds FFI overhead per module per hook. Ecopages merges all `EcoBuildPlugin` instances into one Rolldown plugin in `rolldown-plugin-bridge.ts` with JavaScript-side routing.
+
+### Benchmarks
+
+Kitchen-sink benchmarks (`ECOPAGES_BENCH=1 pnpm vitest bench`) show Rolldown winning 15/18 scenarios versus esbuild, with a **1.21×** geometric mean speedup. Largest wins: React page rebuilds (1.56×), production single page (1.49×), Lit (1.52×), Ecopages-JSX (1.47×). Three scenarios regressed (KitaJS postcss, dynamic route, no-op rebuild); route-module disk cache and fingerprinted production caches reduce repeated work on warm paths.
 
-`ECOPAGES_ROLLDOWN_BUILD_METRICS=1` enables `rolldown-build-invocation-metrics.ts` counters used by bench and parity tests.
+### Native MagicString and CSS shim
 
-Build-input fingerprinting lives in `build-input-fingerprint.ts` and is shared with server-entry cache, unified pages graph, and static-render invalidation.
+- `experimental.nativeMagicString: true` enables Rust-native string manipulation for faster transforms.
+- Server-side builds use `createServerSideCssShimPlugin()` to turn `.css` imports into empty ESM modules. Skipped for browser builds.
 
 ## 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.
+- `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

@@ -0,0 +1,39 @@
+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.
+ *
+ * @remarks
+ * Concurrent callers share a single in-flight promise per integration name.
+ * Failed activations are evicted so a later caller can retry.
+ */
+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

@@ -0,0 +1,145 @@
+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 './browser/lit-static-render-worker-context.js';
+function patchAppRuntime(appConfig, patch) {
+    appConfig.runtime = {
+        ...(appConfig.runtime ?? {}),
+        ...patch,
+    };
+}
+function registerRuntimePlugins(appConfig, onRuntimePlugin) {
+    for (const loader of appConfig.loaders.values()) {
+        onRuntimePlugin?.(loader);
+    }
+    for (const processor of appConfig.processors.values()) {
+        if (processor.plugins) {
+            for (const plugin of processor.plugins) {
+                onRuntimePlugin?.(plugin);
+            }
+        }
+    }
+    for (const integration of appConfig.integrations) {
+        for (const plugin of integration.plugins) {
+            onRuntimePlugin?.(plugin);
+        }
+    }
+}
+/**
+ * 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 async function collectConfiguredAppBuildManifestContributions(appConfig) {
+    const runtimePlugins = [];
+    const browserBundlePlugins = [];
+    const browserRuntimeManifests = [];
+    for (const processor of appConfig.processors.values()) {
+        await processor.prepareBuildContributions();
+        if (processor.plugins) {
+            runtimePlugins.push(...processor.plugins);
+        }
+        if (processor.buildPlugins) {
+            browserBundlePlugins.push(...processor.buildPlugins);
+        }
+    }
+    for (const integration of appConfig.integrations) {
+        integration.setConfig(appConfig);
+        await integration.prepareBuildContributions();
+        runtimePlugins.push(...(integration.plugins ?? []));
+        browserBundlePlugins.push(...(integration.browserBuildPlugins ?? []));
+        browserRuntimeManifests.push(integration.browserRuntimeManifest);
+    }
+    return {
+        runtimePlugins,
+        browserBundlePlugins,
+        browserRuntimeManifest: mergeBrowserRuntimeManifests(...browserRuntimeManifests),
+    };
+}
+export async function setupAppRuntimePlugins(options) {
+    startupTrace.markPhaseStart('setupAppRuntimePlugins');
+    if (options.appConfig.runtime?.runtimeAssetsPrepared) {
+        appLogger.debug('Skipped setupAppRuntimePlugins: runtime assets already prepared');
+        registerRuntimePlugins(options.appConfig, options.onRuntimePlugin);
+        startupTrace.markPhaseEnd('setupAppRuntimePlugins');
+        return;
+    }
+    if (isLitStaticRenderWorkerThread()) {
+        appLogger.debug('Lit static-render worker: skipping processor setup (main thread already prepared artifacts)');
+    }
+    appLogger.debugTime('setupAppRuntimePlugins');
+    try {
+        if (options.onRuntimePlugin) {
+            patchAppRuntime(options.appConfig, { onRuntimePlugin: options.onRuntimePlugin });
+        }
+        for (const loader of options.appConfig.loaders.values()) {
+            options.onRuntimePlugin?.(loader);
+        }
+        const skipProcessorSetup = isLitStaticRenderWorkerThread();
+        for (const processor of options.appConfig.processors.values()) {
+            if (!skipProcessorSetup) {
+                await processor.setup();
+            }
+            if (processor.plugins) {
+                for (const plugin of processor.plugins) {
+                    options.onRuntimePlugin?.(plugin);
+                }
+            }
+        }
+        patchAppRuntime(options.appConfig, { runtimeAssetsPrepared: true });
+    }
+    finally {
+        appLogger.debugTimeEnd('setupAppRuntimePlugins');
+        startupTrace.markPhaseEnd('setupAppRuntimePlugins');
+    }
+}
+/**
+ * Activates one integration's runtime setup on first use.
+ *
+ * @remarks
+ * Concurrent callers share a single in-flight promise per integration name.
+ * Failed activations are evicted so a later caller can retry.
+ */
+export async function ensureIntegrationRuntimeReady(options) {
+    const runtime = options.appConfig.runtime ?? {};
+    options.appConfig.runtime = runtime;
+    runtime.integrationActivations ??= new Map();
+    const existing = runtime.integrationActivations.get(options.integrationName);
+    if (existing) {
+        await existing;
+        return;
+    }
+    const integration = options.appConfig.integrations.find((plugin) => plugin.name === options.integrationName);
+    if (!integration) {
+        return;
+    }
+    const activation = (async () => {
+        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.integrationActivations.set(options.integrationName, activation);
+    try {
+        await activation;
+    }
+    catch (error) {
+        runtime.integrationActivations.delete(options.integrationName);
+        throw error;
+    }
+}

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

@@ -29,3 +29,7 @@ export declare class BrowserRuntimeManifestConflictError extends Error {
 export declare function createBrowserRuntimeManifest(declarations?: readonly BrowserRuntimeAssetDeclaration[]): BrowserRuntimeManifest;
 export declare function mergeBrowserRuntimeManifests(...manifests: Array<BrowserRuntimeManifest | undefined>): BrowserRuntimeManifest;
 export declare function getBrowserRuntimeSpecifierMap(manifest: BrowserRuntimeManifest): ReadonlyMap<string, string>;
+/** Resolves a runtime public URL for an exact specifier. */
+export declare function resolveRuntimeSpecifierPublicPath(specifier: string, publicPathsBySpecifier: ReadonlyMap<string, string>): string | undefined;
+/** Resolves a manifest-owned runtime public URL for an exact specifier. */
+export declare function resolveBrowserRuntimePublicPath(specifier: string, manifest: BrowserRuntimeManifest): string | undefined;

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

@@ -0,0 +1,65 @@
+export class BrowserRuntimeManifestConflictError extends Error {
+    specifier;
+    existing;
+    incoming;
+    constructor(specifier, existing, incoming) {
+        super(`Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ` +
+            `${incoming.owner} maps to ${incoming.publicPath}`);
+        this.name = 'BrowserRuntimeManifestConflictError';
+        this.specifier = specifier;
+        this.existing = existing;
+        this.incoming = incoming;
+    }
+}
+function normalizeDeclaration(declaration) {
+    return {
+        ...declaration,
+        externals: declaration.externals ?? [],
+    };
+}
+function hasCompatibleRuntimeAsset(existing, incoming) {
+    return (existing.importPath === incoming.importPath &&
+        existing.publicPath === incoming.publicPath &&
+        existing.mode === incoming.mode &&
+        arrayEquals(existing.externals, incoming.externals));
+}
+function arrayEquals(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+export function createBrowserRuntimeManifest(declarations = []) {
+    const assets = [];
+    const bySpecifier = new Map();
+    for (const declaration of declarations) {
+        const asset = normalizeDeclaration(declaration);
+        const existing = bySpecifier.get(asset.specifier);
+        if (existing) {
+            if (!hasCompatibleRuntimeAsset(existing, asset)) {
+                throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
+            }
+            continue;
+        }
+        assets.push(asset);
+        bySpecifier.set(asset.specifier, asset);
+    }
+    return {
+        assets,
+        bySpecifier,
+    };
+}
+export function mergeBrowserRuntimeManifests(...manifests) {
+    return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
+}
+export function getBrowserRuntimeSpecifierMap(manifest) {
+    return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
+}
+/** Resolves a runtime public URL for an exact specifier. */
+export function resolveRuntimeSpecifierPublicPath(specifier, publicPathsBySpecifier) {
+    return publicPathsBySpecifier.get(specifier);
+}
+/** Resolves a manifest-owned runtime public URL for an exact specifier. */
+export function resolveBrowserRuntimePublicPath(specifier, manifest) {
+    return manifest.bySpecifier.get(specifier)?.publicPath;
+}

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

@@ -5,7 +5,7 @@
  * `createBrowserRuntimePlugin` needs to:
  *
  * 1. Escape each specifier for inclusion in a regex filter.
- * 2. Build a `RegExp` whose alternation matches any of those specifiers.
+ * 2. Build a `RegExp` whose alternation matches registered specifiers.
  *
  * These utilities are extracted here so the plugin does not duplicate
  * the same code path.
@@ -17,10 +17,8 @@
  */
 export declare function escapeRegExp(value: string): string;
 /**
- * Builds a `RegExp` whose alternation matches any of the keys in
- * `specifierMap`.
+ * Builds a `RegExp` that matches registered specifiers exactly.
  *
- * Returns `null` for an empty map so callers can short-circuit and
- * avoid registering a no-op `onResolve` / `onLoad` filter.
+ * Returns `null` for an empty map so callers can short-circuit registration.
  */
 export declare function buildSpecifierFilter(specifierMap: ReadonlyMap<string, string>): RegExp | null;

package/src/build/browser/browser-runtime-plugin-helpers.js

@@ -0,0 +1,32 @@
+/**
+ * Shared helpers for the browser-runtime plugin.
+ *
+ * @remarks
+ * `createBrowserRuntimePlugin` needs to:
+ *
+ * 1. Escape each specifier for inclusion in a regex filter.
+ * 2. Build a `RegExp` whose alternation matches registered specifiers.
+ *
+ * These utilities are extracted here so the plugin does not duplicate
+ * the same code path.
+ */
+/**
+ * Escapes a literal specifier for inclusion in a regular expression.
+ *
+ * Only the regex metacharacters are escaped: `. * + ? ^ $ { } ( ) | [ ] \`
+ */
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Builds a `RegExp` that matches registered specifiers exactly.
+ *
+ * Returns `null` for an empty map so callers can short-circuit registration.
+ */
+export function buildSpecifierFilter(specifierMap) {
+    if (specifierMap.size === 0) {
+        return null;
+    }
+    const alternation = Array.from(specifierMap.keys()).map(escapeRegExp).join('|');
+    return new RegExp(`^(?:${alternation})$`);
+}