@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/watchers/project-watcher.ts

@@ -3,7 +3,8 @@ import chokidar, { type FSWatcher } from 'chokidar';
 import { fileSystem } from '@ecopages/file-system';
 import { appLogger } from '../global/app-logger.ts';
 import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../internal-types.ts';
-import type { ProcessorWatchContext } from '../plugins/processor.ts';
+import type { ProcessorWatchConfig, ProcessorWatchContext } from '../plugins/processor.ts';
+import { DevelopmentInvalidationService } from '../services/invalidation/development-invalidation.service.ts';
 
 /**
  * Configuration options for the ProjectWatcher
@@ -48,14 +49,17 @@ export class ProjectWatcher {
 	private refreshRouterRoutesCallback: () => void;
 	private hmrManager: IHmrManager;
 	private bridge: IClientBridge;
+	private readonly invalidationService: DevelopmentInvalidationService;
 	private watcher: FSWatcher | null = null;
 	private lastHandledChange = new Map<string, number>();
+	private changeQueue: Promise<void> = Promise.resolve();
 
 	constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig) {
 		this.appConfig = config;
 		this.refreshRouterRoutesCallback = refreshRouterRoutesCallback;
 		this.hmrManager = hmrManager;
 		this.bridge = bridge;
+		this.invalidationService = new DevelopmentInvalidationService(config);
 		this.triggerRouterRefresh = this.triggerRouterRefresh.bind(this);
 		this.handleError = this.handleError.bind(this);
 		this.handleFileChange = this.handleFileChange.bind(this);
@@ -79,6 +83,14 @@ export class ProjectWatcher {
 		}
 	}
 
+	private isRouteSourceFile(filePath: string): boolean {
+		return this.invalidationService.isRouteSourceFile(filePath);
+	}
+
+	private isIncludeSourceFile(filePath: string): boolean {
+		return this.invalidationService.isIncludeSourceFile(filePath);
+	}
+
 	/**
 	 * Handles public directory file changes by copying only the changed file.
 	 * @param filePath - Absolute path of the changed file
@@ -101,19 +113,34 @@ export class ProjectWatcher {
 		}
 	}
 
+	/**
+	 * Serializes file change handling so that concurrent chokidar events are
+	 * processed one at a time, preventing overlapping builds and race conditions.
+	 */
+	private enqueueChange(task: () => Promise<void>): void {
+		const queuedTask = this.changeQueue.then(task, task);
+		this.changeQueue = queuedTask.catch(() => undefined);
+	}
+
 	/**
 	 * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
-	 * Follows 4-rule priority:
-	 * 0. Public directory match? → copy file and reload
-	 * 1. additionalWatchPaths match? → reload
-	 * 2. Processor extension match? → processor handles (skip HMR)
-	 * 3. Otherwise → HMR strategies
+	 * Follows 5-rule priority:
+	 * 0. Public directory match? -> copy file and reload
+	 * 1. additionalWatchPaths match? -> reload
+	 * 2. Include template source? -> reload after processor notifications
+	 * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
+	 * 4. Otherwise -> HMR strategies
+	 *
+	 * Processors that watch a file extension as a dependency (e.g. PostCSS watching
+	 * .tsx for Tailwind class scanning) are always notified first, but do not
+	 * prevent the file from flowing through the normal HMR strategy pipeline.
 	 *
 	 * Duplicate identical watcher events for the same file are coalesced within a
 	 * short window before any of the priority rules run.
 	 * @param rawPath - Path of the changed file
+	 * @param event - The type of file system event
 	 */
-	private async handleFileChange(rawPath: string): Promise<void> {
+	private async handleFileChange(rawPath: string, event: 'change' | 'add' | 'unlink' = 'change'): Promise<void> {
 		const filePath = path.resolve(rawPath);
 		const now = Date.now();
 		const lastHandledAt = this.lastHandledChange.get(filePath);
@@ -123,33 +150,41 @@ export class ProjectWatcher {
 		this.lastHandledChange.set(filePath, now);
 
 		try {
-			if (this.isPublicDirFile(filePath)) {
+			const plan = this.invalidationService.planFileChange(filePath);
+
+			if (plan.category === 'public-asset') {
 				await this.handlePublicDirFileChange(filePath);
 				return;
 			}
 
 			this.uncacheModules();
-			const isPageFile = filePath.startsWith(this.appConfig.absolutePaths.pagesDir);
+			if (plan.invalidateServerModules) {
+				this.invalidationService.invalidateServerModules([filePath]);
+			}
 
-			if (isPageFile) {
+			if (plan.refreshRoutes) {
 				this.refreshRouterRoutesCallback();
 			}
 
-			if (this.matchesAdditionalWatchPaths(filePath)) {
+			if (plan.category === 'additional-watch') {
 				this.bridge.reload();
 				return;
 			}
 
-			if (this.isHandledByProcessor(filePath)) {
+			await this.notifyProcessors(filePath, event);
+
+			if (plan.category === 'include-source') {
+				this.bridge.reload();
 				return;
 			}
 
-			if (this.isWatchedByProcessor(filePath) && !this.hmrManager.canHandleFileChange(filePath)) {
-				this.hmrManager.broadcast({ type: 'layout-update' });
+			if (plan.processorHandledAsset) {
 				return;
 			}
 
-			await this.hmrManager.handleFileChange(filePath);
+			if (plan.delegateToHmr) {
+				await this.hmrManager.handleFileChange(filePath);
+			}
 		} catch (error) {
 			if (error instanceof Error) {
 				this.bridge.error(error.message);
@@ -159,78 +194,65 @@ export class ProjectWatcher {
 	}
 
 	/**
-	 * Checks if a file is in the public directory.
-	 */
-	private isPublicDirFile(filePath: string): boolean {
-		return filePath.startsWith(this.appConfig.absolutePaths.publicDir);
-	}
-
-	/**
-	 * Checks if file path matches any additionalWatchPaths patterns.
+	 * Notifies all processors whose watch config matches the given file extension.
+	 * This is called before checking processor ownership so that dependency-only
+	 * processors (e.g. PostCSS watching .tsx for class scanning) receive their
+	 * notifications regardless of whether they own the file.
 	 */
-	private matchesAdditionalWatchPaths(filePath: string): boolean {
-		const patterns = this.appConfig.additionalWatchPaths;
-		if (!patterns.length) return false;
-
-		for (const pattern of patterns) {
-			if (pattern.includes('*')) {
-				const ext = pattern.replace(/\*\*?\/\*/, '');
-				if (filePath.endsWith(ext)) return true;
-			} else {
-				if (filePath.endsWith(pattern) || filePath === path.resolve(pattern)) return true;
-			}
-		}
-		return false;
-	}
+	private async notifyProcessors(filePath: string, event: 'change' | 'add' | 'unlink'): Promise<void> {
+		const ctx: ProcessorWatchContext = { path: filePath, bridge: this.bridge };
 
-	/**
-	 * Checks whether a file is watched by any processor, even if that processor
-	 * does not own the file as a primary asset.
-	 */
-	private isWatchedByProcessor(filePath: string): boolean {
 		for (const processor of this.appConfig.processors.values()) {
 			const watchConfig = processor.getWatchConfig();
 			if (!watchConfig) continue;
 
 			const { extensions = [] } = watchConfig;
-			if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
-				return true;
+			if (extensions.length && !extensions.some((ext) => filePath.endsWith(ext))) {
+				continue;
+			}
+
+			const handler = this.getProcessorHandler(watchConfig, event);
+			if (handler) {
+				await handler(ctx);
 			}
 		}
+	}
 
-		return false;
+	private getProcessorHandler(
+		watchConfig: ProcessorWatchConfig,
+		event: 'change' | 'add' | 'unlink',
+	): ((ctx: ProcessorWatchContext) => Promise<void>) | undefined {
+		switch (event) {
+			case 'change':
+				return watchConfig.onChange;
+			case 'add':
+				return watchConfig.onCreate;
+			case 'unlink':
+				return watchConfig.onDelete;
+		}
 	}
 
 	/**
-	 * Checks if a file is handled by a processor.
-	 * Processors that declare extensions own those file types.
+	 * Checks if a file is in the public directory.
 	 */
-	private isHandledByProcessor(filePath: string): boolean {
-		for (const processor of this.appConfig.processors.values()) {
-			const capabilities = processor.getAssetCapabilities?.() ?? [];
-			if (capabilities.length > 0) {
-				const matchesConfiguredAsset =
-					typeof processor.matchesFileFilter !== 'function' || processor.matchesFileFilter(filePath);
-
-				if (
-					matchesConfiguredAsset &&
-					capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))
-				) {
-					return true;
-				}
-
-				continue;
-			}
+	private isPublicDirFile(filePath: string): boolean {
+		return this.invalidationService.isPublicDirFile(filePath);
+	}
 
-			const watchConfig = processor.getWatchConfig();
-			if (!watchConfig) continue;
+	/**
+	 * Checks if file path matches any additionalWatchPaths patterns.
+	 */
+	private matchesAdditionalWatchPaths(filePath: string): boolean {
+		return this.invalidationService.matchesAdditionalWatchPaths(filePath);
+	}
 
-			const { extensions = [] } = watchConfig;
-			if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
-				return true;
-			}
-		}
-		return false;
+	/**
+	 * Checks if a file is handled by a processor.
+	 * Processors that declare asset capabilities own those file types.
+	 * Processors without capabilities fall back to checking watch extensions.
+	 */
+	private isHandledByProcessor(filePath: string): boolean {
+		return this.invalidationService.isProcessorOwnedAsset(filePath);
 	}
 
 	/**
@@ -239,9 +261,12 @@ export class ProjectWatcher {
 	 *
 	 * @param {string} path - Path of the changed directory
 	 */
-	triggerRouterRefresh(path: string) {
-		const isPageDir = path.startsWith(this.appConfig.absolutePaths.pagesDir);
-		if (isPageDir) {
+	triggerRouterRefresh(changedPath: string) {
+		const resolvedPath = path.resolve(changedPath);
+		const isPageDir =
+			resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir) && path.extname(resolvedPath) === '';
+
+		if (isPageDir || this.isRouteSourceFile(resolvedPath)) {
 			this.refreshRouterRoutesCallback();
 		}
 	}
@@ -258,28 +283,15 @@ export class ProjectWatcher {
 		appLogger.error(`Watcher error: ${error}`);
 	}
 
-	/**
-	 * Processes file changes for specific file extensions.
-	 * Used by processors to handle their specific file types.
-	 *
-	 * @private
-	 * @param {string} path - Path of the changed file
-	 * @param {string[]} extensions - File extensions to process
-	 * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
-	 */
-	private shouldProcess(path: string, extensions: string[], handler: (ctx: ProcessorWatchContext) => void) {
-		if (!extensions.length || extensions.some((ext) => path.endsWith(ext))) {
-			handler({ path, bridge: this.bridge });
-		}
-	}
-
 	/**
 	 * Creates and configures the file system watcher.
 	 * This sets up:
-	 * 1. Processor-specific file watching
-	 * 2. Page file watching
-	 * 3. Directory watching
-	 * 4. Error handling
+	 * 1. Page file watching
+	 * 2. Directory watching
+	 * 3. Error handling
+	 *
+	 * Processor notifications are dispatched inside handleFileChange, ensuring
+	 * a single unified event pipeline with no parallel chokidar bindings.
 	 *
 	 * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
 	 * rapid file changes efficiently.
@@ -293,6 +305,14 @@ export class ProjectWatcher {
 				processorPaths.push(...watchConfig.paths);
 			}
 
+			if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
+				processorPaths.push(this.appConfig.absolutePaths.includesDir);
+			}
+
+			if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
+				processorPaths.push(this.appConfig.absolutePaths.srcDir);
+			}
+
 			if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
 				processorPaths.push(this.appConfig.absolutePaths.pagesDir);
 			}
@@ -315,30 +335,29 @@ export class ProjectWatcher {
 			});
 		}
 
-		for (const processor of this.appConfig.processors.values()) {
-			const watchConfig = processor.getWatchConfig();
-			if (!watchConfig) continue;
-			const { extensions = [], onCreate, onChange, onDelete, onError } = watchConfig;
-
-			if (onCreate) this.watcher.on('add', (path) => this.shouldProcess(path, extensions, onCreate));
-			if (onChange) this.watcher.on('change', (path) => this.shouldProcess(path, extensions, onChange));
-			if (onDelete) this.watcher.on('unlink', (path) => this.shouldProcess(path, extensions, onDelete));
-			if (onError) this.watcher.on('error', onError as (error: unknown) => void);
-		}
-
 		this.watcher.add(this.appConfig.absolutePaths.srcDir);
 
 		this.watcher
-			.on('change', (path) => this.handleFileChange(path))
-			.on('add', (path) => {
-				this.handleFileChange(path);
-				this.triggerRouterRefresh(path);
+			.on('change', (p) => this.enqueueChange(() => this.handleFileChange(p, 'change')))
+			.on('add', (p) => {
+				this.enqueueChange(() => this.handleFileChange(p, 'add'));
+				this.triggerRouterRefresh(p);
+			})
+			.on('addDir', (p) => this.triggerRouterRefresh(p))
+			.on('unlink', (p) => {
+				this.enqueueChange(() => this.handleFileChange(p, 'unlink'));
+				this.triggerRouterRefresh(p);
 			})
-			.on('addDir', (path) => this.triggerRouterRefresh(path))
-			.on('unlink', (path) => this.triggerRouterRefresh(path))
-			.on('unlinkDir', (path) => this.triggerRouterRefresh(path))
+			.on('unlinkDir', (p) => this.triggerRouterRefresh(p))
 			.on('error', (error) => this.handleError(error));
 
+		for (const processor of this.appConfig.processors.values()) {
+			const watchConfig = processor.getWatchConfig();
+			if (watchConfig?.onError) {
+				this.watcher.on('error', watchConfig.onError as (error: unknown) => void);
+			}
+		}
+
 		return this.watcher;
 	}
 }

package/CHANGELOG.md

@@ -1,91 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/core` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Features
-
-#### Node.js Runtime Support
-
-- **Node server adapter** — Full HTTP server adapter for Node.js via `packages/core/src/adapters/node/`, including request bridging, route handling, static content serving, and graceful shutdown.
-- **Node static build pipeline** — Static-site build and preview server for Node.js runtime (`ab22f167`, `a47b4da3`, `435dc250`).
-- **Node API handler pipeline** — `define-api-handler` now works cross-runtime; Node adapter wires API handler execution end-to-end (`73e57d87`, `f46aa528`).
-- **Node client bridge** — `NodeClientBridge` with SSE-based HMR stream and heartbeat mechanism for connection health (`3361445f`).
-- **Node HMR manager** — `NodeHmrManager` that mirrors Bun HMR capabilities on the Node runtime.
-- **`createApp` universal factory** — Top-level `createApp` export that selects the correct adapter (Bun or Node) at runtime (`ce691bdf`, `2f1b1109`).
-
-#### Build System
-
-- **`EsbuildBuildAdapter`** — A new build backend backed by esbuild, replacing the Bun-only transpilation path. Includes module resolution routing, plugin registration, and transpilation defaults (`f503e86e`, `94c37d38`, `e4e124a1`).
-- **Build dependency graph** — `BuildDependencyGraph` interface for tracking entrypoints and their asset dependencies, enabling more accurate HMR invalidation (`e7653c9b`).
-- **Build adapter abstraction** — `build-adapter.ts` and `build-types.ts` decouple build and plugin contracts from Bun-specific types (`11b03bcc`).
-
-#### Rendering & Orchestration
-
-- **Boundary rendering policy** — Cross-integration component boundaries are now explicitly enforced (`ec1e4d66`).
-- **Full orchestration mode** — Legacy rendering mode branches removed; the engine always runs in unified orchestration mode (`f652fa0a`).
-- **Extracted render services** — The render pipeline is decomposed into focused services:
-    - `RenderExecutionService`
-    - `HtmlPostProcessingService`
-    - `RenderPreparationService`
-    - `MarkerGraphResolver`
-    - `FileRouteMiddlewarePipeline`
-    - `PageRequestCacheCoordinator`
-    - `PageModuleImportService`
-- **Component render context** — New `ComponentRenderContext` consolidates component-level state during rendering (`eco/component-render-context.ts`).
-- **Worker-tools HTML rewriter fallback** — `html-transformer` adopts `@worker-tools/html-rewriter` as a fallback for non-Bun environments (`54056d4f`).
-
-#### Dependency & Injection
-
-- **Global injector map** — `GlobalInjectorMap` and `LazyInjectorMap` provide structured, testable dependency injection for global and lazy assets (`c3a25072`).
-- **Lazy dependency resolution** — SSR lazy script resolution now uses dedicated utility functions for dependency entry attributes and content generation (`71ce2f4f`).
-- **Dependency entry type refactor** — Unified types for script and stylesheet dependency entries, with improved error messages (`1e02dba6`).
-- **Module dependencies** — New `module-dependencies.ts` tracks explicit module-level asset relationships.
-- **Eco utils extraction** — Shared utilities moved to `eco.utils.ts` to remove runtime metadata fallbacks (`bdc60d50`).
-
-#### API Handlers
-
-- **Unified typed API handler context** — `defineApiHandler` now exposes a fully typed, runtime-agnostic context object. The Bun-specific adapter is slimmed down to a thin wrapper (`2f1b1109`, `08e194b4`).
-- **Portable root runtime API** — Core exposes a portable API surface that avoids runtime escape hatches (`ce691bdf`, `1ec42c02`).
-
-### Refactoring
-
-- **Bun adapter isolation** — Bun-specific types (`serve` options, file reads, env access, argv/hash helpers) are routed through dedicated helpers, making the remaining adapter code portable (`73668f52`, `0c90ced1`, `73fb904a`, `5eb0957b`, `4bdc74a9`, `e9ce163c`, `22f9de4a`, `f7b3d95e`).
-- **Shared server adapter** — Common server adapter logic extracted to `adapters/shared/application-adapter.ts` and `adapters/shared/server-adapter.ts`, shared between Bun and Node adapters (`5a872eda`).
-- **Route assets isolation** — Route-level assets are now isolated per-request, hardening dependency processing (`3fd76a12`).
-- **Shared matcher error constants** — Matcher error strings are now constants shared across test and source (`ff4db106`).
-- **App registration & fetch pipeline** — App creation and request handling consolidated into a single unified pipeline (`86e20a3d`).
-- **Adapter escape hatch surface** trimmed — Public adapter API is narrowed to reduce surface area (`1ec42c02`).
-
-### Bug Fixes
-
-- Fixed invariant checks for route paths with improved error messaging in `AbstractApplicationAdapter` (`9c2a6242`).
-- Fixed dependency import name extraction in `extractEcopagesVirtualImports` (`39bbc472`).
-- Removed an invalid npm export entry that pointed to a non-existent `utils/ecopages-url-resolver` declaration target.
-- Kept source module HMR active when stylesheet processors also watch TSX and JSX files for Tailwind-driven CSS rebuilds.
-- Triggered HMR current-page refreshes instead of fallback reload suppression for processor-watched TSX and JSX changes that are not client entrypoints.
-
-### Tests
-
-- Added node static content server test coverage (`435dc250`).
-- Strengthened HTML transformer mode matrix coverage (`286c1253`).
-- Aligned integration and dependency processing tests to new orchestration model (`7cc73316`).
-- Added `EsbuildBuildAdapter` test suite with 500+ lines (`build-adapter.test.ts`).
-- Added `file-route-middleware-pipeline` tests.
-
-### Documentation
-
-- Updated rendering graph documentation to cover extracted rendering services (`8bfcfd21`).
-- Refreshed server handler and module dependency guidance (`3494f44d`).
-
----
-
-## Migration Notes
-
-- **`createApp`** is now the recommended entrypoint (previously `EcopagesApp`). Import from `@ecopages/core`.
-- **`defineApiHandler`** signature is unchanged but the handler context object now carries explicit runtime-agnostic types. No breaking changes for existing handlers.
-- Bun adapter still works as before; the new Node adapter is additive.
-- The old explicit `renderingMode` config option has been removed — full orchestration is always active.

package/src/adapters/abstract/application-adapter.d.ts

@@ -1,168 +0,0 @@
-/**
- * This file defines the abstract class for application adapters in EcoPages.
- * It provides a common interface for different runtimes (e.g., Node.js, Deno) to implement.
- * The class includes methods for handling HTTP requests and managing application state.
- * It also includes a method for parsing command-line arguments.
- *
- * @module ApplicationAdapter
- */
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../public-types.js';
-import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
-/**
- * Configuration options for application adapters
- */
-export interface ApplicationAdapterOptions {
-    appConfig: EcoPagesAppConfig;
-    serverOptions?: Record<string, any>;
-    /**
-     * Options for clearing the output directory before starting the server
-     * @default false
-     */
-    clearOutput?: boolean;
-}
-/**
- * Common interface for application adapters
- */
-export interface ApplicationAdapter<T = any> {
-    start(): Promise<T | void>;
-}
-/**
- * Handler function type for route handlers
- */
-export type RouteHandler<TRequest extends Request = Request, TServer = any, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>> = (context: TContext) => Promise<Response> | Response;
-export type RouteGroupDefinition<TRequest extends Request = Request, TServer = any> = {
-    prefix: string;
-    middleware?: readonly Middleware<TRequest, TServer, any>[];
-    routes: readonly ApiHandler<string, TRequest, TServer>[];
-};
-/**
- * Abstract base class for application adapters across different runtimes
- */
-export declare abstract class AbstractApplicationAdapter<TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions, TServer = any, TRequest extends Request = any> implements ApplicationAdapter<TServer> {
-    protected appConfig: EcoPagesAppConfig;
-    protected serverOptions: Record<string, any>;
-    protected cliArgs: ReturnParseCliArgs;
-    protected apiHandlers: ApiHandler[];
-    protected staticRoutes: StaticRoute[];
-    protected errorHandler?: ErrorHandler;
-    constructor(options: TOptions);
-    private clearDistFolder;
-    /**
-     * Register a GET route handler.
-     *
-     * Use verb methods for inline route definitions.
-     * For dynamic HTTP method registration, use `route(...)`.
-     */
-    abstract get<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
-    /**
-     * Register a POST route handler
-     */
-    abstract post<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
-    /**
-     * Register a PUT route handler
-     */
-    abstract put<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
-    /**
-     * Register a DELETE route handler
-     */
-    abstract delete<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
-    /**
-     * Register a PATCH route handler
-     */
-    abstract patch<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
-    /**
-     * Register an OPTIONS route handler
-     */
-    abstract options<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
-    /**
-     * Register a HEAD route handler
-     */
-    abstract head<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(path: P, handler: RouteHandler<TRequest, TServer, TContext>, options?: RouteOptions<TRequest, TServer, TContext>): this;
-    /**
-     * Register a route with an explicit HTTP method.
-     *
-     * This is useful when the method is determined programmatically, or when
-     * registering a pre-built route declaration object by forwarding its
-     * `path`, `method`, and `handler` fields.
-     */
-    abstract route<P extends string>(path: P, method: ApiHandler['method'], handler: RouteHandler<TRequest, TServer>, options?: RouteOptions<TRequest, TServer>): this;
-    /**
-     * Register a pre-built API handler declaration.
-     */
-    abstract add(handler: ApiHandler<string, TRequest, TServer>): this;
-    /**
-     * Internal method to add route handlers to the API handlers array
-     */
-    protected addRouteHandler<P extends string, TSpecRequest extends TRequest = TRequest, TSpecServer extends TServer = TServer, TContext extends ApiHandlerContext<TSpecRequest, TSpecServer> = ApiHandlerContext<TSpecRequest, TSpecServer>>(path: P, method: ApiHandler['method'], handler: RouteHandler<TSpecRequest, TSpecServer, TContext>, middleware?: Middleware<TSpecRequest, TSpecServer, TContext>[], schema?: ApiHandler['schema']): this;
-    /**
-     * Create a route group with shared prefix and middleware.
-     * Routes defined within the group inherit the prefix and middleware.
-     *
-     * Each adapter implements this with its own builder type to support
-     * runtime-specific features (e.g., Bun's path parameter inference).
-     * Implementations may also support passing a pre-built group object.
-     *
-     * @param prefix - URL prefix for all routes in the group (e.g., '/api/v1')
-     * @param callback - Function that receives a builder to define routes
-     * @param options - Optional group-level middleware
-     */
-    abstract group(prefix: string, callback: (builder: unknown) => void, options?: {
-        middleware?: readonly Middleware<TRequest, TServer, any>[];
-    }): this;
-    abstract group(group: RouteGroupDefinition<TRequest, TServer>): this;
-    /**
-     * Get all registered API handlers
-     */
-    getApiHandlers(): ApiHandler[];
-    /**
-     * Register a view for static generation at build time.
-     * The view must have staticPaths defined for dynamic routes.
-     *
-     * Uses a loader function to enable HMR in development.
-     *
-     * @param path - URL path pattern (e.g., '/posts/:slug')
-     * @param loader - A function that dynamically imports the eco.page view module
-     * @example
-     * ```typescript
-     * app.static('/login', () => import('./src/views/login.kita'))
-     * app.static('/posts/:slug', () => import('./src/views/post-view.kita'))
-     * ```
-     */
-    static<P>(path: string, loader: ViewLoader<P>): this;
-    /**
-     * Get all registered static routes
-     */
-    getStaticRoutes(): StaticRoute[];
-    /**
-     * Register a global error handler for all routes.
-     * Useful for logging, monitoring integration, and custom error formatting.
-     *
-     * @example
-     * ```typescript
-     * app.onError(async (error, ctx) => {
-     *   logger.error(error);
-     *   return ctx.response.status(500).json({ error: 'Something went wrong' });
-     * });
-     * ```
-     */
-    onError(handler: ErrorHandler<TRequest, TServer>): this;
-    /**
-     * Get the registered error handler
-     */
-    getErrorHandler(): ErrorHandler | undefined;
-    /**
-     * Initialize the server adapter based on the runtime
-     */
-    protected abstract initializeServerAdapter(): Promise<any>;
-    /**
-     * Start the application server
-     */
-    abstract start(): Promise<TServer | void>;
-    /**
-     * Handles a standard Web request without requiring a bound network server.
-     * This is the primary interoperability surface for embedding Ecopages inside
-     * other runtimes and frameworks.
-     */
-    abstract fetch(request: TRequest): Promise<Response>;
-}