@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

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

@@ -0,0 +1,170 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../config/constants.ts';
+import { StaticContentServer } from '../../dev/sc-server.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { ApiHandler, StaticRoute } from '../../types/public-types.ts';
+import type { RouteRegistry } from '../../router/server/route-registry.ts';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.ts';
+import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.ts';
+
+export interface StaticBuildOptions {
+	preview?: boolean;
+	baseUrl?: string;
+}
+
+export interface ServeOptions {
+	hostname?: string;
+	port?: number | string;
+}
+
+export interface ServerStaticBuilderParams {
+	appConfig: EcoPagesAppConfig;
+	staticSiteGenerator: StaticSiteGenerator;
+	serveOptions: ServeOptions;
+	apiHandlers?: ApiHandler[];
+	logger?: ServerStaticBuilderLogger;
+	previewServerFactory?: ServerStaticPreviewServerFactory;
+}
+
+/**
+ * Minimal logger dependency used by the static builder.
+ */
+export interface ServerStaticBuilderLogger {
+	warn(message: string, detail?: string): unknown;
+	info(message: string): unknown;
+	error(message: string): unknown;
+}
+
+/**
+ * Preview server factory dependency used when static preview mode is enabled.
+ */
+export interface ServerStaticPreviewServerFactory {
+	createServer(args: { appConfig: EcoPagesAppConfig; options: { port: number } }): {
+		server?: {
+			port?: number;
+		} | null;
+	};
+}
+
+/**
+ * Handles static site generation and previews.
+ */
+export class ServerStaticBuilder {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly staticSiteGenerator: StaticSiteGenerator;
+	private readonly serveOptions: ServeOptions;
+	private readonly apiHandlers: ApiHandler[];
+	private readonly logger: ServerStaticBuilderLogger;
+	private readonly previewServerFactory: ServerStaticPreviewServerFactory;
+
+	constructor({
+		appConfig,
+		staticSiteGenerator,
+		serveOptions,
+		apiHandlers,
+		logger,
+		previewServerFactory,
+	}: ServerStaticBuilderParams) {
+		this.appConfig = appConfig;
+		this.staticSiteGenerator = staticSiteGenerator;
+		this.serveOptions = serveOptions;
+		this.apiHandlers = apiHandlers ?? [];
+		this.logger = logger ?? appLogger;
+		this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+	}
+
+	private warnApiHandlersUnavailableInStaticMode(): void {
+		if (this.apiHandlers.length === 0) {
+			return;
+		}
+
+		const uniqueHandlers = Array.from(
+			new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`)),
+		);
+		const visibleHandlers = uniqueHandlers.slice(0, 5).join(', ');
+		const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
+		const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
+
+		this.logger.warn(
+			'Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n',
+			`➤ ${summary}`,
+		);
+	}
+
+	private prepareExportDirectory(): void {
+		const exportDir =
+			this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+		fileSystem.ensureDir(exportDir, true);
+
+		const srcPublicDir = path.join(
+			this.appConfig.rootDir,
+			this.appConfig.srcDir ?? 'src',
+			this.appConfig.publicDir ?? 'public',
+		);
+		if (fileSystem.exists(srcPublicDir)) {
+			fileSystem.copyDir(srcPublicDir, exportDir);
+		}
+	}
+
+	private async refreshRuntimeAssets(): Promise<void> {
+		for (const processor of this.appConfig.processors.values()) {
+			await processor.setup();
+		}
+
+		for (const integration of this.appConfig.integrations) {
+			await integration.setup();
+		}
+	}
+
+	/**
+	 * Generates a static build of the site for deployment.
+	 * @param options.preview - If true, starts a preview server after build
+	 * @param dependencies.router - The initialized router
+	 * @param dependencies.routeRendererFactory - The route renderer factory
+	 * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
+	 */
+	async build(
+		options: StaticBuildOptions | undefined,
+		dependencies: {
+			router: RouteRegistry;
+			routeRendererFactory: StaticGenerationRendererResolver;
+			staticRoutes?: StaticRoute[];
+		},
+	): Promise<void> {
+		const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+
+		const baseUrl =
+			explicitBaseUrl ??
+			`http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+		this.warnApiHandlersUnavailableInStaticMode();
+		this.prepareExportDirectory();
+		await this.refreshRuntimeAssets();
+
+		await this.staticSiteGenerator.run({
+			router: dependencies.router,
+			baseUrl,
+			routeRendererFactory: dependencies.routeRendererFactory,
+			staticRoutes: dependencies.staticRoutes,
+		});
+
+		if (!preview) {
+			this.logger.info('Build completed');
+			return;
+		}
+
+		const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
+
+		const { server } = this.previewServerFactory.createServer({
+			appConfig: this.appConfig,
+			options: { port: Number(previewPort) },
+		});
+
+		if (server?.port) {
+			this.logger.info(`Preview running at http://localhost:${server.port}`);
+		} else {
+			this.logger.error('Failed to start preview server');
+		}
+	}
+}

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

@@ -0,0 +1,298 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RESOLVED_ASSETS_DIR } from '../../config/constants.ts';
+import { getAppBuildExecutor } from '../../build/build-adapter.ts';
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../types/internal-types.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import { fileSystem } from '@ecopages/file-system';
+import { HmrStrategyType, type HmrStrategy } from '../../hmr/hmr-strategy.ts';
+import { DefaultHmrStrategy } from '../../hmr/strategies/default-hmr-strategy.ts';
+import { JsHmrStrategy } from '../../hmr/strategies/js-hmr-strategy.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { ClientBridgeEvent } from '../../types/public-types.ts';
+import { HmrEntrypointRegistrar } from './hmr-entrypoint-registrar.ts';
+import { BrowserBundleService } from '../../services/assets/browser-bundle.service.ts';
+import { getAppServerModuleTranspiler } from '../../services/module-loading/app-server-module-transpiler.service.ts';
+import {
+	getAppEntrypointDependencyGraph,
+	setAppEntrypointDependencyGraph,
+	type EntrypointDependencyGraph,
+} from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
+import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service.ts';
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from '../../utils/resolve-work-dir.ts';
+
+type HandleFileChangeOptions = {
+	broadcast?: boolean;
+};
+
+type SharedHmrManagerParams = {
+	appConfig: EcoPagesAppConfig;
+	bridge: IClientBridge;
+	registrationTimeoutMs?: number;
+};
+
+export abstract class SharedHmrManager implements IHmrManager {
+	public readonly appConfig: EcoPagesAppConfig;
+	protected readonly bridge: IClientBridge;
+	protected watchers = new Map<string, fs.FSWatcher>();
+	protected watchedFiles = new Map<string, string>();
+	protected entrypointRegistrations = new Map<string, Promise<string>>();
+	protected distDir: string;
+	protected plugins: EcoBuildPlugin[] = [];
+	protected enabled = true;
+	protected strategies: HmrStrategy[] = [];
+	protected readonly entrypointRegistrar: HmrEntrypointRegistrar;
+	protected readonly browserBundleService: BrowserBundleService;
+	protected readonly entrypointDependencyGraph: EntrypointDependencyGraph;
+	protected readonly serverModuleTranspiler: ServerModuleTranspiler;
+
+	constructor({ appConfig, bridge, registrationTimeoutMs = 4000 }: SharedHmrManagerParams) {
+		this.appConfig = appConfig;
+		this.bridge = bridge;
+		this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, '_hmr');
+		this.entrypointRegistrar = new HmrEntrypointRegistrar({
+			srcDir: this.appConfig.absolutePaths.srcDir,
+			distDir: this.distDir,
+			entrypointRegistrations: this.entrypointRegistrations,
+			watchedFiles: this.watchedFiles,
+			clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+			registrationTimeoutMs,
+		});
+		this.browserBundleService = new BrowserBundleService(appConfig);
+		this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(
+			getAppEntrypointDependencyGraph(appConfig),
+		);
+		setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+		this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+		this.ensureDistDir();
+		this.initializeStrategies();
+	}
+
+	protected abstract createEntrypointDependencyGraph(
+		existingEntrypointDependencyGraph: EntrypointDependencyGraph,
+	): EntrypointDependencyGraph;
+
+	protected shouldSkipMissingFileChange(_filePath: string): boolean {
+		return false;
+	}
+
+	protected onRuntimeBundleFailure(error: unknown): void {
+		appLogger.error('[HMR] Failed to build runtime script:', error);
+	}
+
+	protected ensureDistDir(): void {
+		fileSystem.ensureDir(this.distDir);
+	}
+
+	protected shouldJsStrategyProcessEntrypoint(entrypointPath: string): boolean {
+		return !this.strategies.some((strategy) => {
+			if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+				return false;
+			}
+
+			try {
+				return strategy.matches(entrypointPath);
+			} catch (error) {
+				appLogger.error(error);
+				return false;
+			}
+		});
+	}
+
+	protected initializeStrategies(): void {
+		const jsContext = {
+			getWatchedFiles: () => this.watchedFiles,
+			getDistDir: () => this.distDir,
+			getPlugins: () => this.plugins,
+			getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+			getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+			getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+			getTemplateExtensions: () => this.appConfig.templatesExt,
+			getBrowserBundleService: () => this.browserBundleService,
+			getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+			shouldProcessEntrypoint: (entrypointPath: string) => this.shouldJsStrategyProcessEntrypoint(entrypointPath),
+		};
+
+		this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+	}
+
+	public registerStrategy(strategy: HmrStrategy): void {
+		this.strategies.push(strategy);
+	}
+
+	public setPlugins(plugins: EcoBuildPlugin[]): void {
+		this.plugins = [...plugins];
+	}
+
+	public setEnabled(enabled: boolean): void {
+		this.enabled = enabled;
+	}
+
+	public isEnabled(): boolean {
+		return this.enabled;
+	}
+
+	public async buildRuntime(): Promise<void> {
+		const runtimeSource = fileURLToPath(import.meta.resolve('@ecopages/core/hmr/client/hmr-runtime'));
+
+		try {
+			const result = await this.browserBundleService.bundle({
+				profile: 'hmr-runtime',
+				entrypoints: [runtimeSource],
+				outdir: this.distDir,
+				naming: '_hmr_runtime.js',
+				minify: false,
+				plugins: this.plugins,
+			});
+
+			if (!result.success) {
+				this.onRuntimeBundleFailure(result.logs);
+			}
+		} catch (error) {
+			this.onRuntimeBundleFailure(error);
+		}
+	}
+
+	public getRuntimePath(): string {
+		return path.join(this.distDir, '_hmr_runtime.js');
+	}
+
+	public broadcast(event: ClientBridgeEvent) {
+		appLogger.debug(
+			`[HMR] Broadcasting ${event.type} event, path=${event.path || 'all'}, subscribers=${this.bridge.subscriberCount}`,
+		);
+		this.bridge.broadcast(event);
+	}
+
+	public async handleFileChange(filePath: string, options: HandleFileChangeOptions = {}): Promise<void> {
+		if (this.shouldSkipMissingFileChange(filePath) && !fileSystem.exists(filePath)) {
+			appLogger.debug(`[${this.constructor.name}] Skipping missing file change: ${filePath}`);
+			this.clearFailedEntrypointRegistration(filePath);
+			return;
+		}
+
+		const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
+		const strategy = sorted.find((candidate) => {
+			try {
+				return candidate.matches(filePath);
+			} catch (error) {
+				appLogger.error(error);
+				return false;
+			}
+		});
+
+		if (!strategy) {
+			appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+			return;
+		}
+
+		appLogger.debug(`[${this.constructor.name}] Selected strategy: ${strategy.constructor.name}`);
+
+		const action = await strategy.process(filePath);
+		const shouldBroadcast = options.broadcast ?? true;
+
+		if (shouldBroadcast && action.type === 'broadcast' && action.events) {
+			for (const event of action.events) {
+				this.broadcast(event);
+			}
+		}
+	}
+
+	public getOutputUrl(entrypointPath: string): string | undefined {
+		return this.watchedFiles.get(entrypointPath);
+	}
+
+	public getWatchedFiles(): Map<string, string> {
+		return this.watchedFiles;
+	}
+
+	public getDistDir(): string {
+		return this.distDir;
+	}
+
+	public getPlugins(): EcoBuildPlugin[] {
+		return this.plugins;
+	}
+
+	public getDefaultContext(): DefaultHmrContext {
+		return {
+			getWatchedFiles: () => this.watchedFiles,
+			getDistDir: () => this.distDir,
+			getPlugins: () => this.plugins,
+			getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+			getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+			getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+			getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+			getBrowserBundleService: () => this.browserBundleService,
+			getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+			importServerModule: async <T>(filePath: string) =>
+				await this.serverModuleTranspiler.importModule<T>({
+					filePath,
+					outdir: path.join(resolveInternalExecutionDir(this.appConfig), '.server-modules'),
+					externalPackages: true,
+				}),
+		};
+	}
+
+	protected clearFailedEntrypointRegistration(entrypointPath: string): void {
+		this.watchedFiles.delete(entrypointPath);
+		this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+	}
+
+	public async registerEntrypoint(entrypointPath: string): Promise<string> {
+		return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+			emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
+			getMissingOutputError: (normalizedEntrypoint, outputPath) =>
+				new Error(
+					`[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`,
+				),
+		});
+	}
+
+	public async registerScriptEntrypoint(entrypointPath: string): Promise<string> {
+		return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+			emit: async (normalizedEntrypoint, outputPath) =>
+				await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+			getMissingOutputError: (normalizedEntrypoint) =>
+				new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`),
+		});
+	}
+
+	protected async emitStrictEntrypoint(entrypointPath: string): Promise<void> {
+		await this.handleFileChange(entrypointPath, { broadcast: false });
+	}
+
+	protected async emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void> {
+		const naming = path.relative(this.distDir, outputPath).split(path.sep).join('/');
+		const buildResult = await this.browserBundleService.bundle({
+			profile: 'hmr-entrypoint',
+			entrypoints: [entrypointPath],
+			outdir: this.distDir,
+			naming,
+			minify: false,
+			plugins: this.plugins,
+		});
+
+		if (!buildResult.success) {
+			appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
+			return;
+		}
+
+		const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
+		if (entrypointDependencies) {
+			this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
+		}
+	}
+
+	public stop() {
+		this.entrypointRegistrations.clear();
+		for (const watcher of this.watchers.values()) {
+			watcher.close();
+		}
+		this.watchers.clear();
+		this.watchedFiles.clear();
+		this.entrypointDependencyGraph.reset();
+		this.plugins = [];
+	}
+}

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

@@ -0,0 +1,12 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+
+export interface StaticPreviewHost {
+	start(options: StaticPreviewHostStartOptions): Promise<number | null>;
+	stop(force?: boolean): Promise<void>;
+}
+
+export interface StaticPreviewHostStartOptions {
+	appConfig: EcoPagesAppConfig;
+	hostname: string;
+	port: number;
+}

package/src/build/README.md

@@ -1,107 +1,91 @@
 # Build Layer
 
-This directory contains the runtime-neutral build contract used across Ecopages, the Bun-native adapter that currently uses esbuild under the hood, and the explicit host-owned Vite compatibility boundary.
+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.
 
-## Files
-
-- `build-adapter.ts`: shared build interfaces, explicit Bun-native versus Vite-host ownership helpers, app-owned adapter/executor helpers, and compatibility fallback helpers for older Bun-native call paths.
-- `build-types.ts`: plugin bridge types used by integrations and processors.
-- `esbuild-build-adapter.ts`: the concrete Bun-native adapter implementation. It is compatibility infrastructure, not strategic architecture.
-- `dev-build-coordinator.ts`: development-only orchestration around the temporary Bun-native esbuild backend.
-- `*.test.ts`: focused regression coverage for plain builds and development serialization and recovery.
-
-## Responsibilities
+## Mental Model
 
-The build layer is intentionally split into two parts.
+Three concentric shapes, plus a serializer and a plugin injector:
 
-`BuildExecutor` is the runtime-facing contract.
+| Shape                      | Lives in                       | Purpose                                                                                                                                                             |
+| -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BuildAdapter`             | `build-adapter.ts`             | Low-level backend. Two implementations: the bundled adapter (the real bundler) and `ViteHostBuildAdapter` (a host-owned boundary marker that throws on direct use). |
+| `BuildExecutor`            | `build-adapter.ts`             | Narrower runtime facade. Only `build` is exposed. Stored on `appConfig.runtime.buildExecutor`.                                                                      |
+| `SerializedBuildExecutor`  | `serialized-build-executor.ts` | FIFO queue around any `BuildExecutor`. Used by the dev watch pipeline.                                                                                              |
+| `withBuildExecutorPlugins` | `build-adapter.ts`             | Merges app-owned plugins into every `build` call. The single point of plugin injection.                                                                             |
 
-- It is the narrow facade stored on `appConfig.runtime.buildExecutor`.
-- It answers only how a given app instance should execute builds right now.
-- the Bun-native adapter satisfies this contract directly in plain flows.
-- `DevBuildCoordinator` also satisfies this contract by wrapping the temporary Bun-native esbuild adapter with development-only serialization and recovery policy.
+Plus one translation bridge:
 
-`EsbuildBuildAdapter` is the current Bun-native backend. It knows how to:
+- `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.
 
-- load the esbuild module
-- translate Ecopages `BuildOptions` into esbuild options
-- bridge Ecopages build plugins into esbuild hooks
-- normalize build output, logs, and dependency graph metadata
-- detect the subset of runtime faults that mean the esbuild worker protocol is corrupted
-
-`ViteHostBuildAdapter` is a boundary marker, not a real backend. It exists so app/runtime state can represent that Vite owns host-side build execution instead of silently falling back to a framework-owned esbuild path.
+## Files
 
-`DevBuildCoordinator` is the development policy layer. It exists because one app/runtime can have many build callers during dev mode, including:
+- `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`: dev-watch entrypoint that wraps the app-owned adapter in a `SerializedBuildExecutor + withBuildExecutorPlugins` chain.
+- `*.test.ts`: regression coverage.
 
-- page module imports
-- HMR entrypoint builds
-- script and asset processors
-- React integration build paths
+## Default Flow
 
-Those callers must not race each other against one long-lived esbuild worker. The coordinator therefore owns temporary compatibility policy for the Bun-native path:
+`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.
 
-- serialized access to the shared adapter in development
-- recycling warm Node-target esbuild sessions between builds
-- recovery from known esbuild worker protocol faults
+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:
 
-## Default Flow
+```
+BuildExecutor
+  └─ SerializedBuildExecutor            // FIFO queue
+       └─ withBuildExecutorPlugins       // injects app plugins
+            └─ BuildAdapter (bundled adapter or Vite-host)
+```
 
-Each `EcoPagesAppConfig` owns explicit build ownership, a build adapter, a build manifest, and a `buildExecutor` in `appConfig.runtime`. `ConfigBuilder.build()` now creates that app-owned build state up front so later runtime startup can reuse it rather than mutating a shared adapter.
+Every dev-watch caller reads `appConfig.runtime.buildExecutor` and gets the merged plugin set without further ceremony.
 
-When a Bun server adapter starts in watch mode, it replaces that executor with a per-app `DevBuildCoordinator`. Vite-hosted flows should not use that coordinator; the host owns watch, graph, and HMR policy there. Build consumers then either call the executor directly or pass it explicitly to the top-level `build()` helper.
+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 top-level `getTranspileOptions()` helper are compatibility fallbacks only. New runtime code should prefer app-owned access through `getAppBuildAdapter()`, `getAppBuildExecutor()`, and `getAppTranspileOptions()`.
+## Vite-Host Boundary
 
-The same rule applies to source-module loading: host-owned import behavior must be injected through abstract runtime state rather than imported directly into core services.
+`ViteHostBuildAdapter` is not a real backend. It exists so `appConfig.runtime.buildAdapter` can carry the `'vite-host'` ownership without falling back to a framework-owned bundler path. Every method throws a clear `Vite-hosted builds are owned by the host runtime. Core cannot …` error so misrouted calls fail loudly.
 
-Plugins are part of app-owned manifest or per-build input now. The source build contract no longer exposes adapter-level plugin registration, which keeps build composition scoped to an app/runtime instance instead of leaking across instances.
+Vite-based apps (or any future host runtime) should:
 
-HMR callers follow the same ownership model. Integration-specific runtime aliasing stays with the integration that owns those specifiers, rather than in generic core HMR bundling.
+1. Construct a `ViteHostBuildAdapter` via `createViteHostBuildAdapter()` and install it on the app config with `setAppBuildAdapter`.
+2. Run their own build pipeline outside the core.
+3. Reuse the core's `BuildExecutor`-shaped surface where possible so call-sites stay backend-neutral.
 
-## Orchestration Diagram
+## Plugin Authoring
 
-```mermaid
-flowchart TD
-    Config["ConfigBuilder.build()"] --> DefaultExec["appConfig.runtime.buildExecutor = createAppBuildExecutor(app adapter, manifest)"]
-    Adapter["Server adapter initialize() in watch mode"] --> DevExec["appConfig.runtime.buildExecutor = DevBuildCoordinator"]
-    Caller["Any build caller with app/runtime context"] --> Build["executor.build(options) or build(options, executor)"]
-    Build --> Executor["BuildExecutor"]
-    Executor --> Coordinator["DevBuildCoordinator.build()"]
-    Coordinator --> Backend["EsbuildBuildAdapter.buildOrThrow()"]
-    Executor -->|plain flow| Direct["EsbuildBuildAdapter.build()"]
-    Backend --> Result["BuildResult"]
-    Direct --> Result["BuildResult"]
-    Result --> Browser["Browser consumes emitted bundle directly"]
-```
+`EcoBuildPlugin` is the runtime-agnostic contract integrations and processors register. The shape:
 
-## Recovery Model
+- `name: string`
+- `setup(build: EcoBuildPluginBuilder): void | Promise<void>`
 
-The recovery path is narrow on purpose. The coordinator only treats an error as recoverable when `EsbuildBuildAdapter.isEsbuildProtocolError()` matches one of the known worker-protocol failure signatures.
+`EcoBuildPluginBuilder` exposes three hooks:
 
-When that happens, recovery does three things in order:
+- `onResolve({ filter, namespace? }, callback)` — the bundler's `resolveId` mapped to the shared plugin shape.
+- `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.
 
-1. Reset the serialized queue so future builds are not stuck behind a wedged promise.
-2. Stop the current esbuild service instance.
-3. Increment the esbuild module generation so the next import gets a fresh worker instance.
+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.
 
-After that reset, the coordinator retries the failed build once.
+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.
 
-## Why Explicit App Ownership
+## BuildOptions Caveats
 
-There are many build callsites across core and integrations. The coordinator still needs to stay centralized for the remaining Bun-native compatibility path, but process-global installation hid the real dependency and tied behavior to startup order.
+`BuildOptions` is modeled on the bundler's options shape. Most fields map cleanly. The exceptions:
 
-The explicit app-owned executor model keeps the design honest:
+- `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.
+- `bundle` — accepted but ignored. The bundler always bundles.
+- `outbase` — accepted but ignored. The adapter derives the base from `options.root` directly.
 
-- each app/runtime owns its own build executor
-- development policy stays in one place (`DevBuildCoordinator`) for the remaining Bun-native path only
-- callers with app context use that executor explicitly instead of consulting global state
-- tests can still instantiate `EsbuildBuildAdapter`, `ViteHostBuildAdapter`, or `DevBuildCoordinator` directly when they want the raw ownership boundary or compatibility backend only
+These fields are kept in the type so existing call-sites compile. The proper fix is a more focused `BuildOptions` schema in a follow-up.
 
 ## Testing Strategy
 
-The build tests are split by concern.
-
-- `build-adapter.test.ts` verifies plain backend behavior and plugin bridging.
-- `build-adapter-serialization.test.ts` verifies development orchestration behavior such as serialization, warm-session recycling, and protocol-fault recovery.
+- `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.
 
-If you change the build orchestration rules, update the coordinator tests first. If you change esbuild option mapping or plugin behavior, update the backend tests first.
+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.