@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.25

package/src/watchers/project-watcher.ts

@@ -0,0 +1,357 @@
+import path from 'node:path';
+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 '../types/internal-types.ts';
+import type { ProcessorWatchConfig, ProcessorWatchContext } from '../plugins/processor.ts';
+import { DevelopmentInvalidationService } from '../services/invalidation/development-invalidation.service.ts';
+
+/**
+ * Configuration options for the ProjectWatcher
+ * @interface ProjectWatcherConfig
+ * @property {EcoPagesAppConfig} config - The application configuration
+ * @property {() => Promise<void>} refreshRouterRoutesCallback - Callback to refresh router routes
+ * @property {IHmrManager} hmrManager - The HMR manager instance
+ * @property {ClientBridge} bridge - The client bridge instance
+ */
+export interface ProjectWatcherConfig {
+	config: EcoPagesAppConfig;
+	refreshRouterRoutesCallback: () => Promise<void>;
+	hmrManager: IHmrManager;
+	bridge: IClientBridge;
+}
+
+/**
+ * ProjectWatcher handles file system changes for hot module replacement (HMR).
+ * It uses chokidar to watch for file changes and triggers appropriate actions:
+ * - Uncaches modules when files change
+ * - Refreshes router routes for page files
+ * - Triggers HMR server reload
+ * - Handles processor-specific file changes
+ *
+ * The watcher uses chokidar's built-in debouncing through `awaitWriteFinish`
+ * to handle rapid file changes efficiently:
+ * - stabilityThreshold: 50ms - Time to wait for writes to stabilize
+ * - pollInterval: 50ms - Interval to poll for file changes
+ *
+ * @class ProjectWatcher
+ */
+export class ProjectWatcher {
+	/**
+	 * Duplicate identical watcher events within this window are ignored.
+	 *
+	 * Some editors or save pipelines emit two near-identical filesystem change
+	 * notifications for the same file. Ecopages should treat those as one logical
+	 * update so HMR and route refresh work are not repeated unnecessarily.
+	 */
+	private static readonly duplicateChangeWindowMs = 150;
+	private appConfig: EcoPagesAppConfig;
+	private refreshRouterRoutesCallback: () => Promise<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);
+	}
+
+	/**
+	 * Uncaches modules in the source directory to ensure fresh imports.
+	 * This is necessary for hot module replacement to work correctly.
+	 * @private
+	 */
+	private uncacheModules(): void {
+		if (typeof require === 'undefined') return;
+
+		const { srcDir, rootDir } = this.appConfig;
+		const regex = new RegExp(`${rootDir}/${srcDir}/.*`);
+
+		for (const key in require.cache) {
+			if (regex.test(key)) {
+				delete require.cache[key];
+			}
+		}
+	}
+
+	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
+	 */
+	private async handlePublicDirFileChange(filePath: string): Promise<void> {
+		try {
+			const relativePath = path.relative(this.appConfig.absolutePaths.publicDir, filePath);
+			const destPath = path.join(this.appConfig.absolutePaths.distDir, relativePath);
+
+			if (fileSystem.exists(filePath)) {
+				const destDir = path.dirname(destPath);
+				fileSystem.ensureDir(destDir);
+				await fileSystem.copyFileAsync(filePath, destPath);
+			}
+
+			this.bridge.reload();
+		} catch (error) {
+			appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
+			this.bridge.reload();
+		}
+	}
+
+	/**
+	 * 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 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, event: 'change' | 'add' | 'unlink' = 'change'): Promise<void> {
+		const filePath = path.resolve(rawPath);
+		const now = Date.now();
+		const lastHandledAt = this.lastHandledChange.get(filePath);
+		if (lastHandledAt !== undefined && now - lastHandledAt < ProjectWatcher.duplicateChangeWindowMs) {
+			return;
+		}
+		this.lastHandledChange.set(filePath, now);
+
+		try {
+			const plan = this.invalidationService.planFileChange(filePath);
+
+			if (plan.category === 'public-asset') {
+				await this.handlePublicDirFileChange(filePath);
+				return;
+			}
+
+			this.uncacheModules();
+			if (plan.invalidateServerModules) {
+				this.invalidationService.invalidateServerModules([filePath]);
+			}
+
+			if (plan.refreshRoutes) {
+				await this.refreshRouterRoutesCallback();
+			}
+
+			if (plan.category === 'additional-watch') {
+				this.bridge.reload();
+				return;
+			}
+
+			await this.notifyProcessors(filePath, event);
+
+			if (plan.category === 'include-source') {
+				this.bridge.reload();
+				return;
+			}
+
+			if (plan.processorHandledAsset) {
+				return;
+			}
+
+			if (plan.delegateToHmr) {
+				await this.hmrManager.handleFileChange(filePath);
+			}
+		} catch (error) {
+			if (error instanceof Error) {
+				this.bridge.error(error.message);
+				this.handleError(error);
+			}
+		}
+	}
+
+	/**
+	 * 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 async notifyProcessors(filePath: string, event: 'change' | 'add' | 'unlink'): Promise<void> {
+		const ctx: ProcessorWatchContext = { path: filePath, bridge: this.bridge };
+
+		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))) {
+				continue;
+			}
+
+			const handler = this.getProcessorHandler(watchConfig, event);
+			if (handler) {
+				await handler(ctx);
+			}
+		}
+	}
+
+	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 in the public directory.
+	 */
+	private isPublicDirFile(filePath: string): boolean {
+		return this.invalidationService.isPublicDirFile(filePath);
+	}
+
+	/**
+	 * Checks if file path matches any additionalWatchPaths patterns.
+	 */
+	private matchesAdditionalWatchPaths(filePath: string): boolean {
+		return this.invalidationService.matchesAdditionalWatchPaths(filePath);
+	}
+
+	/**
+	 * 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);
+	}
+
+	/**
+	 * Triggers router refresh for page directory changes.
+	 * This ensures the router is updated when pages are added or removed.
+	 *
+	 * @param {string} path - Path of the changed directory
+	 */
+	async triggerRouterRefresh(changedPath: string): Promise<void> {
+		const resolvedPath = path.resolve(changedPath);
+		const isPageDir =
+			resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir) && path.extname(resolvedPath) === '';
+
+		if (isPageDir || this.isRouteSourceFile(resolvedPath)) {
+			await this.refreshRouterRoutesCallback();
+		}
+	}
+
+	/**
+	 * Handles and logs errors that occur during file watching.
+	 *
+	 * @param {unknown} error - The error to handle
+	 */
+	handleError(error: unknown) {
+		if (error instanceof Error) {
+			this.hmrManager.broadcast({ type: 'error', message: error.message });
+		}
+		appLogger.error(`Watcher error: ${error}`);
+	}
+
+	/**
+	 * Creates and configures the file system watcher.
+	 * This sets up:
+	 * 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.
+	 */
+	public async createWatcherSubscription() {
+		if (this.watcher) {
+			return this.watcher;
+		}
+
+		const processorPaths: string[] = [];
+		for (const processor of this.appConfig.processors.values()) {
+			const watchConfig = processor.getWatchConfig();
+			if (!watchConfig) continue;
+			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);
+		}
+
+		if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
+			processorPaths.push(this.appConfig.absolutePaths.publicDir);
+		}
+
+		if (this.appConfig.additionalWatchPaths.length) {
+			processorPaths.push(...this.appConfig.additionalWatchPaths);
+		}
+
+		this.watcher = chokidar.watch(processorPaths, {
+			ignoreInitial: true,
+			ignorePermissionErrors: true,
+			awaitWriteFinish: {
+				stabilityThreshold: 50,
+				pollInterval: 50,
+			},
+		});
+
+		this.watcher
+			.on('change', (p) => this.enqueueChange(() => this.handleFileChange(p, 'change')))
+			.on('add', (p) => this.enqueueChange(() => this.handleFileChange(p, 'add')))
+			.on('addDir', (p) => this.enqueueChange(() => this.triggerRouterRefresh(p)))
+			.on('unlink', (p) => this.enqueueChange(() => this.handleFileChange(p, 'unlink')))
+			.on('unlinkDir', (p) => this.enqueueChange(() => 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,51 +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
-
-- Added app-owned runtime and build ownership around `createApp()`, host module loading, the browser-safe `eco` export, `eco.html()`, `eco.layout()`, and the published `EcoPagesAppConfig` surface.
-- Added boundary-plan metadata and a compatibility `renderBoundary()` payload contract for mixed-renderer orchestration.
-
-### Refactoring
-
-- Consolidated runtime state around shared module-loading services, app-owned build execution, and the universal `createApp()` boundary.
-- Simplified route-renderer orchestration around renderer-owned boundary runtimes, shared string-boundary queue helpers, and a smaller component render context.
-- Centralized shared integration renderer bootstrapping so package integrations only append renderer-specific config instead of duplicating core lifecycle wiring.
-- Moved shared queued boundary resolution to attachment-policy payloads and constructor-injectable planning services.
-- Extracted shared page, layout, and document-shell composition into a narrow `RouteShellComposer` while keeping renderer-owned boundary handoff in `IntegrationRenderer`.
-- Removed marker-era compatibility capture, the shared route-level fallback resolver, deprecated `@ecopages/core/node*` escape hatches, and other dead route-renderer internals.
-
-### Bug Fixes
-
-- Fixed mixed-integration page, layout, document, and component rendering to resolve foreign boundaries inside their owning renderer across the built-in integrations.
-- Fixed host/runtime module loading, published build-helper exports, asset output normalization, explicit render flows, and static or preview build stability across Bun, Node, Vite, and Nitro.
-- Fixed development project watcher setup to register chokidar paths and handlers only once per app runtime.
-- Fixed development script-entry registration to build only the requested HMR entrypoint instead of fanning out across all watched script entrypoints during startup.
-- Fixed Node bootstrap runtime package linking to refresh dangling `.eco/node_modules` symlinks instead of failing with `EEXIST` during page transpilation.
-- Fixed request-time and static-generation page inspection to preserve integration-specific page loading without reusing the normal render module identity.
-- Fixed Node preview and static-generation React runtime resolution so app-owned page modules and server rendering share one React module identity.
-- Fixed Bun browser output normalization so batched multi-entrypoint HMR rebuilds match emitted files to their expected served paths instead of Bun output order.
-- Fixed render-preparation graph traversal so sparse component dependency arrays do not break custom 404 rendering or file-system response fallback flows.
-
-### Documentation
-
-- Added architecture and API documentation for config, plugins, services, adapters, HMR, routing, and rendering.
-
-### Tests
-
-- Added regression coverage for app-owned runtime services, Node fallback paths, and cross-runtime invalidation behavior.
-- Strengthened the core ghtml integration tests so route and explicit render paths await real outcomes and cover `renderToResponse` behavior.
-- Added core regression coverage for boundary plans, payload contracts, and typed mixed-boundary context flow.
-
----
-
-## Migration Notes
-
-- `createApp` is now the recommended entrypoint. Import it from `@ecopages/core/create-app`.
-- `defineApiHandler` keeps the same call shape, but the handler context is now explicitly runtime-agnostic.
-- The old explicit `renderingMode` config option has been removed and full orchestration is always active.

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

@@ -1,194 +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 { SourceModuleLoader } from '../../services/module-loading/module-loading-types.js';
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
-import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
-/**
- * Runtime bootstrap options layered on top of the app config.
- *
- * These options let a host runtime embed Ecopages without mutating process
- * globals or app runtime state before calling `createApp()`.
- */
-export interface ApplicationRuntimeOptions {
-    /**
-     * Forces the app into the embedded-runtime CLI mode used by host
-     * environments.
-     *
-     * When enabled and no explicit `hostModuleLoader` is provided, the
-     * adapter auto-detects a host module loader from the global scope.
-     */
-    embedded?: boolean;
-    /**
-     * Explicit source module loader for request-time imports.
-     *
-     * When omitted in embedded mode, the adapter attempts automatic
-     * detection from globals set by the host environment.
-     */
-    hostModuleLoader?: SourceModuleLoader;
-}
-/**
- * Configuration options for application adapters
- */
-export interface ApplicationAdapterOptions {
-    appConfig: EcoPagesAppConfig;
-    serverOptions?: Record<string, any>;
-    runtime?: ApplicationRuntimeOptions;
-    /**
-     * 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 runtimeOptions: ApplicationRuntimeOptions;
-    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>;
-}