@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# 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
+
+### Bug Fixes
+
+- Fixed npm release packaging to publish rewritten internal dependency versions instead of unresolved `workspace:*` ranges.
+
+### Features & Architecture
+
+- **Experimental Node.js Support**: Introduced a framework-owned thin-host bootstrap and runtime manifest flow for Node.js, providing cross-runtime parity while keeping the core agnostic.
+- **Architectural Consolidation**: Unified server-side loading, browser bundling, and HMR strategy orchestration across all runtimes using shared core services (`ServerModuleTranspiler`, `BrowserBundleService`).
+- **Build & Asset Refinement**: Introduced an internal `.eco` work directory to isolate development artifacts from production exports, and added `eco.html()`/`eco.layout()` for semantic component definitions.
+- **Performance & Reliability**: Refactored internal watchers and HMR dispatching to improve build stability during rapid development cycles.
+
+### Tests & Documentation
+
+- **Robust Regression Suite**: Added coverage for experimental Node.js paths, the new shared services, and cross-runtime file-change dispatching.
+- **Architecture Docs**: Added focused architecture and API documentation for config, plugins, services, adapters, HMR, router, and the rendering lifecycle.
+
+---
+
+## Migration Notes
+
+- `createApp` is now the recommended entrypoint. Import it from `@ecopages/core`.
+- `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.7",
+  "version": "0.2.0-alpha.9",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -8,23 +8,16 @@
     "ssg"
   ],
   "license": "MIT",
-  "main": "./src/index.ts",
+  "main": "./src/index.js",
   "type": "module",
-  "files": [
-    "src"
-  ],
   "sideEffects": false,
   "repository": {
     "type": "git",
     "url": "https://github.com/ecopages/ecopages.git",
     "directory": "packages/core"
   },
-  "scripts": {
-    "typecheck": "bunx tsc --noEmit",
-    "release:jsr": "bunx jsr publish"
-  },
   "dependencies": {
-    "@ecopages/file-system": "workspace:*",
+    "@ecopages/file-system": "0.2.0-alpha.9",
     "@ecopages/logger": "latest",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
@@ -34,49 +27,40 @@
     "oxc-parser": "^0.110.0",
     "ws": "^8.18.0"
   },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/ws": "^8.5.14",
-    "arktype": "^2.1.29",
-    "tailwindcss": "^3.4.19",
-    "tsx": "^4.20.5",
-    "valibot": "^1.2.0",
-    "zod": "^4.3.6"
-  },
   "exports": {
     ".": {
-      "browser": "./src/index.browser.ts",
-      "import": "./src/index.ts",
-      "require": "./src/index.ts",
-      "types": "./src/index.ts"
+      "browser": "./src/index.browser.js",
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
     },
     "./create-app": {
-      "types": "./src/create-app.ts",
-      "default": "./src/create-app.ts"
+      "types": "./src/create-app.d.ts",
+      "default": "./src/create-app.js"
     },
     "./route-renderer/integration-renderer": {
-      "types": "./src/route-renderer/orchestration/integration-renderer.ts",
-      "default": "./src/route-renderer/orchestration/integration-renderer.ts"
+      "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
+      "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
     "./router/navigation-coordinator": {
-      "types": "./src/router/client/navigation-coordinator.ts",
-      "default": "./src/router/client/navigation-coordinator.ts"
+      "types": "./src/router/client/navigation-coordinator.d.ts",
+      "default": "./src/router/client/navigation-coordinator.js"
     },
     "./router/link-intent": {
-      "types": "./src/router/client/link-intent.ts",
-      "default": "./src/router/client/link-intent.ts"
+      "types": "./src/router/client/link-intent.d.ts",
+      "default": "./src/router/client/link-intent.js"
     },
     "./router/client/navigation-coordinator": {
-      "types": "./src/router/client/navigation-coordinator.ts",
-      "default": "./src/router/client/navigation-coordinator.ts"
+      "types": "./src/router/client/navigation-coordinator.d.ts",
+      "default": "./src/router/client/navigation-coordinator.js"
     },
     "./errors/locals-access-error": {
-      "types": "./src/errors/locals-access-error.ts",
-      "default": "./src/errors/locals-access-error.ts"
+      "types": "./src/errors/locals-access-error.d.ts",
+      "default": "./src/errors/locals-access-error.js"
     },
     "./eco": {
-      "types": "./src/eco/eco.ts",
-      "default": "./src/eco/eco.ts"
+      "types": "./src/eco/eco.d.ts",
+      "default": "./src/eco/eco.js"
     },
     "./declarations": {
       "types": "./src/declarations.d.ts"
@@ -85,107 +69,243 @@
       "types": "./src/env.d.ts"
     },
     "./config-builder": {
-      "types": "./src/config/config-builder.ts",
-      "default": "./src/config/config-builder.ts"
+      "types": "./src/config/config-builder.d.ts",
+      "default": "./src/config/config-builder.js"
     },
     "./constants": {
-      "types": "./src/constants.ts",
-      "default": "./src/constants.ts"
+      "types": "./src/constants.d.ts",
+      "default": "./src/constants.js"
     },
     "./bun": {
-      "types": "./src/adapters/bun/index.ts",
-      "default": "./src/adapters/bun/index.ts"
+      "types": "./src/adapters/bun/index.d.ts",
+      "default": "./src/adapters/bun/index.js"
     },
     "./bun/create-app": {
-      "types": "./src/adapters/bun/create-app.ts",
-      "default": "./src/adapters/bun/create-app.ts"
-    },
-    "./bun/define-api-handler": {
-      "types": "./src/adapters/bun/define-api-handler.ts",
-      "default": "./src/adapters/bun/define-api-handler.ts"
+      "types": "./src/adapters/bun/create-app.d.ts",
+      "default": "./src/adapters/bun/create-app.js"
     },
     "./hmr/hmr-strategy": {
-      "types": "./src/hmr/hmr-strategy.ts",
-      "default": "./src/hmr/hmr-strategy.ts"
+      "types": "./src/hmr/hmr-strategy.d.ts",
+      "default": "./src/hmr/hmr-strategy.js"
     },
     "./internal-types": {
-      "types": "./src/internal-types.ts"
+      "types": "./src/internal-types.d.ts"
     },
     "./services/asset-processing-service": {
-      "types": "./src/services/assets/asset-processing-service/index.ts",
-      "default": "./src/services/assets/asset-processing-service/index.ts"
+      "types": "./src/services/assets/asset-processing-service/index.d.ts",
+      "default": "./src/services/assets/asset-processing-service/index.js"
     },
     "./utils/deep-merge": {
-      "types": "./src/utils/deep-merge.ts",
-      "default": "./src/utils/deep-merge.ts"
+      "types": "./src/utils/deep-merge.d.ts",
+      "default": "./src/utils/deep-merge.js"
     },
     "./utils/invariant": {
-      "types": "./src/utils/invariant.ts",
-      "default": "./src/utils/invariant.ts"
+      "types": "./src/utils/invariant.d.ts",
+      "default": "./src/utils/invariant.js"
     },
     "./utils/parse-cli-args": {
-      "types": "./src/utils/parse-cli-args.ts",
-      "default": "./src/utils/parse-cli-args.ts"
+      "types": "./src/utils/parse-cli-args.d.ts",
+      "default": "./src/utils/parse-cli-args.js"
     },
     "./plugins/processor": {
-      "types": "./src/plugins/processor.ts",
-      "default": "./src/plugins/processor.ts"
+      "types": "./src/plugins/processor.d.ts",
+      "default": "./src/plugins/processor.js"
     },
     "./plugins/integration-plugin": {
-      "types": "./src/plugins/integration-plugin.ts",
-      "default": "./src/plugins/integration-plugin.ts"
+      "types": "./src/plugins/integration-plugin.d.ts",
+      "default": "./src/plugins/integration-plugin.js"
     },
     "./build/build-types": {
-      "types": "./src/build/build-types.ts",
-      "default": "./src/build/build-types.ts"
+      "types": "./src/build/build-types.d.ts",
+      "default": "./src/build/build-types.js"
     },
     "./build/build-adapter": {
-      "types": "./src/build/build-adapter.ts",
-      "default": "./src/build/build-adapter.ts"
+      "types": "./src/build/build-adapter.d.ts",
+      "default": "./src/build/build-adapter.js"
     },
     "./build/runtime-specifier-alias-plugin": {
-      "types": "./src/build/runtime-specifier-alias-plugin.ts",
-      "default": "./src/build/runtime-specifier-alias-plugin.ts"
+      "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
+      "default": "./src/build/runtime-specifier-alias-plugin.js"
     },
     "./adapters/bun/client-bridge": {
-      "types": "./src/adapters/bun/client-bridge.ts",
-      "default": "./src/adapters/bun/client-bridge.ts"
+      "types": "./src/adapters/bun/client-bridge.d.ts",
+      "default": "./src/adapters/bun/client-bridge.js"
     },
     "./node": {
-      "types": "./src/adapters/node/index.ts",
-      "default": "./src/adapters/node/index.ts"
+      "types": "./src/adapters/node/index.d.ts",
+      "default": "./src/adapters/node/index.js"
     },
     "./node/server-adapter": {
-      "types": "./src/adapters/node/server-adapter.ts",
-      "default": "./src/adapters/node/server-adapter.ts"
+      "types": "./src/adapters/node/server-adapter.d.ts",
+      "default": "./src/adapters/node/server-adapter.js"
     },
     "./node/create-app": {
-      "types": "./src/adapters/node/create-app.ts",
-      "default": "./src/adapters/node/create-app.ts"
+      "types": "./src/adapters/node/create-app.d.ts",
+      "default": "./src/adapters/node/create-app.js"
     },
     "./node/runtime-adapter": {
-      "types": "./src/adapters/node/runtime-adapter.ts",
-      "default": "./src/adapters/node/runtime-adapter.ts"
+      "types": "./src/adapters/node/runtime-adapter.d.ts",
+      "default": "./src/adapters/node/runtime-adapter.js"
     },
     "./html": {
-      "import": "./src/utils/html.ts",
-      "require": "./src/utils/html.ts"
+      "import": "./src/utils/html.js",
+      "default": "./src/utils/html.js",
+      "types": "./src/utils/html.d.ts"
     },
     "./css": {
-      "import": "./src/utils/css.ts",
-      "require": "./src/utils/css.ts"
+      "import": "./src/utils/css.js",
+      "default": "./src/utils/css.js",
+      "types": "./src/utils/css.d.ts"
     },
     "./hash": {
-      "import": "./src/utils/hash.ts",
-      "require": "./src/utils/hash.ts"
+      "import": "./src/utils/hash.js",
+      "default": "./src/utils/hash.js",
+      "types": "./src/utils/hash.d.ts"
     },
     "./errors": {
-      "types": "./src/errors/index.ts",
-      "default": "./src/errors/index.ts"
+      "types": "./src/errors/index.d.ts",
+      "default": "./src/errors/index.js"
     },
     "./integrations/ghtml": {
-      "types": "./src/integrations/ghtml/ghtml.plugin.ts",
-      "default": "./src/integrations/ghtml/ghtml.plugin.ts"
+      "types": "./src/integrations/ghtml/ghtml.plugin.d.ts",
+      "default": "./src/integrations/ghtml/ghtml.plugin.js"
+    },
+    "./create-app.ts": {
+      "types": "./src/create-app.d.ts",
+      "default": "./src/create-app.js"
+    },
+    "./route-renderer/integration-renderer.ts": {
+      "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
+      "default": "./src/route-renderer/orchestration/integration-renderer.js"
+    },
+    "./router/navigation-coordinator.ts": {
+      "types": "./src/router/client/navigation-coordinator.d.ts",
+      "default": "./src/router/client/navigation-coordinator.js"
+    },
+    "./router/link-intent.ts": {
+      "types": "./src/router/client/link-intent.d.ts",
+      "default": "./src/router/client/link-intent.js"
+    },
+    "./router/client/navigation-coordinator.ts": {
+      "types": "./src/router/client/navigation-coordinator.d.ts",
+      "default": "./src/router/client/navigation-coordinator.js"
+    },
+    "./errors/locals-access-error.ts": {
+      "types": "./src/errors/locals-access-error.d.ts",
+      "default": "./src/errors/locals-access-error.js"
+    },
+    "./eco.ts": {
+      "types": "./src/eco/eco.d.ts",
+      "default": "./src/eco/eco.js"
+    },
+    "./declarations.ts": {
+      "types": "./src/declarations.d.ts"
+    },
+    "./env.ts": {
+      "types": "./src/env.d.ts"
+    },
+    "./config-builder.ts": {
+      "types": "./src/config/config-builder.d.ts",
+      "default": "./src/config/config-builder.js"
+    },
+    "./constants.ts": {
+      "types": "./src/constants.d.ts",
+      "default": "./src/constants.js"
+    },
+    "./bun.ts": {
+      "types": "./src/adapters/bun/index.d.ts",
+      "default": "./src/adapters/bun/index.js"
+    },
+    "./bun/create-app.ts": {
+      "types": "./src/adapters/bun/create-app.d.ts",
+      "default": "./src/adapters/bun/create-app.js"
+    },
+    "./hmr/hmr-strategy.ts": {
+      "types": "./src/hmr/hmr-strategy.d.ts",
+      "default": "./src/hmr/hmr-strategy.js"
+    },
+    "./internal-types.ts": {
+      "types": "./src/internal-types.d.ts"
+    },
+    "./services/asset-processing-service.ts": {
+      "types": "./src/services/assets/asset-processing-service/index.d.ts",
+      "default": "./src/services/assets/asset-processing-service/index.js"
+    },
+    "./utils/deep-merge.ts": {
+      "types": "./src/utils/deep-merge.d.ts",
+      "default": "./src/utils/deep-merge.js"
+    },
+    "./utils/invariant.ts": {
+      "types": "./src/utils/invariant.d.ts",
+      "default": "./src/utils/invariant.js"
+    },
+    "./utils/parse-cli-args.ts": {
+      "types": "./src/utils/parse-cli-args.d.ts",
+      "default": "./src/utils/parse-cli-args.js"
+    },
+    "./plugins/processor.ts": {
+      "types": "./src/plugins/processor.d.ts",
+      "default": "./src/plugins/processor.js"
+    },
+    "./plugins/integration-plugin.ts": {
+      "types": "./src/plugins/integration-plugin.d.ts",
+      "default": "./src/plugins/integration-plugin.js"
+    },
+    "./build/build-types.ts": {
+      "types": "./src/build/build-types.d.ts",
+      "default": "./src/build/build-types.js"
+    },
+    "./build/build-adapter.ts": {
+      "types": "./src/build/build-adapter.d.ts",
+      "default": "./src/build/build-adapter.js"
+    },
+    "./build/runtime-specifier-alias-plugin.ts": {
+      "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
+      "default": "./src/build/runtime-specifier-alias-plugin.js"
+    },
+    "./adapters/bun/client-bridge.ts": {
+      "types": "./src/adapters/bun/client-bridge.d.ts",
+      "default": "./src/adapters/bun/client-bridge.js"
+    },
+    "./node.ts": {
+      "types": "./src/adapters/node/index.d.ts",
+      "default": "./src/adapters/node/index.js"
+    },
+    "./node/server-adapter.ts": {
+      "types": "./src/adapters/node/server-adapter.d.ts",
+      "default": "./src/adapters/node/server-adapter.js"
+    },
+    "./node/create-app.ts": {
+      "types": "./src/adapters/node/create-app.d.ts",
+      "default": "./src/adapters/node/create-app.js"
+    },
+    "./node/runtime-adapter.ts": {
+      "types": "./src/adapters/node/runtime-adapter.d.ts",
+      "default": "./src/adapters/node/runtime-adapter.js"
+    },
+    "./html.ts": {
+      "import": "./src/utils/html.js",
+      "default": "./src/utils/html.js",
+      "types": "./src/utils/html.d.ts"
+    },
+    "./css.ts": {
+      "import": "./src/utils/css.js",
+      "default": "./src/utils/css.js",
+      "types": "./src/utils/css.d.ts"
+    },
+    "./hash.ts": {
+      "import": "./src/utils/hash.js",
+      "default": "./src/utils/hash.js",
+      "types": "./src/utils/hash.d.ts"
+    },
+    "./errors.ts": {
+      "types": "./src/errors/index.d.ts",
+      "default": "./src/errors/index.js"
+    },
+    "./integrations/ghtml.ts": {
+      "types": "./src/integrations/ghtml/ghtml.plugin.d.ts",
+      "default": "./src/integrations/ghtml/ghtml.plugin.js"
     }
-  }
-}
+  },
+  "types": "./src/index.d.ts"
+}

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

@@ -0,0 +1,168 @@
+/**
+ * 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>;
+}