@ecopages/core 0.2.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# 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.
+
+### 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Andrea Zanenghi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# Ecopages
+
+Ecopages is a static site generator designed with the goal of simplifying the process of creating websites. It is suitable for a range of projects, from blogs to portfolios, emphasizing ease of use and flexibility.
+
+This project is built on a commitment to clarity and simplicity in web development, utilizing modern web technologies without obscuring the process with unnecessary complexity.
+
+Ecopages relies on a minimal set of dependencies, carefully chosen to support its core functionality.
+
+Ecopages is built on the [Bun](https://bun.sh/) runtime, primarily utilizing [Kita](https://kitajs.org/html/) and [Mdx](https://mdxjs.com/) for rendering. Additionally, it supports [Lit Elements](https://lit.dev/) and offers experimental integration with [React](https://react.dev/). This setup allows for the extension of the platform with custom rendering functions, providing flexibility to cater to the specific needs of each project. The integrations are designed to be extensible, with no limit to the customization and expansion possibilities.
+
+For styling, [Tailwind CSS](https://tailwindcss.com/) and [PostCSS](https://postcss.org/) have been integrated. Notably, we recommend using `css` stylesheets and `@apply` directives with Tailwind CSS, diverging from its usual inline styling approach to better suit the structure of Ecopages.
+
+As a project in its early stages, Ecopages is continuously evolving. Users may encounter limitations or areas in need of refinement. We welcome feedback and issue reports via our [GitHub repository](https://github.com/ecopages/ecopages).
+
+## Install
+
+```bash
+bunx jsr add @ecopages/core
+```
+
+## Portable imports first
+
+Use the root package exports for normal Ecopages authoring:
+
+```ts
+import { EcopagesApp, defineApiHandler, defineGroupHandler } from '@ecopages/core';
+```
+
+Use runtime-specific subpaths only as advanced escape hatches when you explicitly need Bun- or Node-native APIs:
+
+- `@ecopages/core/bun`
+- `@ecopages/core/node`

package/package.json

@@ -0,0 +1,279 @@
+{
+  "name": "@ecopages/core",
+  "version": "0.2.0-alpha.1",
+  "description": "Core package for Ecopages",
+  "keywords": [
+    "ecopages",
+    "core",
+    "ssg"
+  ],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/core"
+  },
+  "dependencies": {
+    "@ecopages/file-system": "0.2.0-alpha.1",
+    "@ecopages/logger": "latest",
+    "@ecopages/scripts-injector": "^0.1.3",
+    "@worker-tools/html-rewriter": "0.1.0-pre.19",
+    "chokidar": "^4.0.3",
+    "esbuild": "^0.27.3",
+    "ghtml": "^4.0.2",
+    "oxc-parser": "^0.110.0",
+    "ws": "^8.18.0"
+  },
+  "exports": {
+    ".": {
+      "browser": "./src/index.browser.js",
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./create-app": {
+      "types": "./src/create-app.d.ts",
+      "default": "./src/create-app.js"
+    },
+    "./route-renderer/integration-renderer": {
+      "types": "./src/route-renderer/integration-renderer.d.ts",
+      "default": "./src/route-renderer/integration-renderer.js"
+    },
+    "./errors/locals-access-error": {
+      "types": "./src/errors/locals-access-error.d.ts",
+      "default": "./src/errors/locals-access-error.js"
+    },
+    "./eco": {
+      "types": "./src/eco/eco.d.ts",
+      "default": "./src/eco/eco.js"
+    },
+    "./declarations": {
+      "types": "./src/declarations.d.ts"
+    },
+    "./env": {
+      "types": "./src/env.d.ts"
+    },
+    "./config-builder": {
+      "types": "./src/config/config-builder.d.ts",
+      "default": "./src/config/config-builder.js"
+    },
+    "./constants": {
+      "types": "./src/constants.d.ts",
+      "default": "./src/constants.js"
+    },
+    "./bun": {
+      "types": "./src/adapters/bun/index.d.ts",
+      "default": "./src/adapters/bun/index.js"
+    },
+    "./bun/create-app": {
+      "types": "./src/adapters/bun/create-app.d.ts",
+      "default": "./src/adapters/bun/create-app.js"
+    },
+    "./bun/define-api-handler": {
+      "types": "./src/adapters/bun/define-api-handler.d.ts",
+      "default": "./src/adapters/bun/define-api-handler.js"
+    },
+    "./hmr/hmr-strategy": {
+      "types": "./src/hmr/hmr-strategy.d.ts",
+      "default": "./src/hmr/hmr-strategy.js"
+    },
+    "./internal-types": {
+      "types": "./src/internal-types.d.ts"
+    },
+    "./services/asset-processing-service": {
+      "types": "./src/services/asset-processing-service/index.d.ts",
+      "default": "./src/services/asset-processing-service/index.js"
+    },
+    "./utils/deep-merge": {
+      "types": "./src/utils/deep-merge.d.ts",
+      "default": "./src/utils/deep-merge.js"
+    },
+    "./utils/invariant": {
+      "types": "./src/utils/invariant.d.ts",
+      "default": "./src/utils/invariant.js"
+    },
+    "./utils/parse-cli-args": {
+      "types": "./src/utils/parse-cli-args.d.ts",
+      "default": "./src/utils/parse-cli-args.js"
+    },
+    "./plugins/processor": {
+      "types": "./src/plugins/processor.d.ts",
+      "default": "./src/plugins/processor.js"
+    },
+    "./plugins/integration-plugin": {
+      "types": "./src/plugins/integration-plugin.d.ts",
+      "default": "./src/plugins/integration-plugin.js"
+    },
+    "./build/build-types": {
+      "types": "./src/build/build-types.d.ts",
+      "default": "./src/build/build-types.js"
+    },
+    "./build/build-adapter": {
+      "types": "./src/build/build-adapter.d.ts",
+      "default": "./src/build/build-adapter.js"
+    },
+    "./adapters/bun/client-bridge": {
+      "types": "./src/adapters/bun/client-bridge.d.ts",
+      "default": "./src/adapters/bun/client-bridge.js"
+    },
+    "./node": {
+      "types": "./src/adapters/node/index.d.ts",
+      "default": "./src/adapters/node/index.js"
+    },
+    "./node/server-adapter": {
+      "types": "./src/adapters/node/server-adapter.d.ts",
+      "default": "./src/adapters/node/server-adapter.js"
+    },
+    "./node/create-app": {
+      "types": "./src/adapters/node/create-app.d.ts",
+      "default": "./src/adapters/node/create-app.js"
+    },
+    "./html": {
+      "import": "./src/utils/html.js",
+      "default": "./src/utils/html.js",
+      "types": "./src/utils/html.d.ts"
+    },
+    "./css": {
+      "import": "./src/utils/css.js",
+      "default": "./src/utils/css.js",
+      "types": "./src/utils/css.d.ts"
+    },
+    "./hash": {
+      "import": "./src/utils/hash.js",
+      "default": "./src/utils/hash.js",
+      "types": "./src/utils/hash.d.ts"
+    },
+    "./errors": {
+      "types": "./src/errors/index.d.ts",
+      "default": "./src/errors/index.js"
+    },
+    "./integrations/ghtml": {
+      "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/integration-renderer.d.ts",
+      "default": "./src/route-renderer/integration-renderer.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"
+    },
+    "./bun/define-api-handler.ts": {
+      "types": "./src/adapters/bun/define-api-handler.d.ts",
+      "default": "./src/adapters/bun/define-api-handler.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/asset-processing-service/index.d.ts",
+      "default": "./src/services/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"
+    },
+    "./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"
+    },
+    "./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>;
+}