@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 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
+
+- Renamed route-renderer ownership and foreign-child contracts across core so ownership planning, foreign-subtree payloads, and queued foreign-subtree resolution now use the simplified terminology.
+- Introduced a single `RouteRenderFlow` owner for route render preparation and execution, removing the separate execution service seam while keeping boundary planning shared.
+- Narrowed route-render orchestration onto an explicit `RouteRenderFlowAdapter` seam and one structural Html finalization plan, reducing callback-bag plumbing between `RouteRenderFlow` and `IntegrationRenderer`.
+- Renamed renderer-owned page browser asset preparation onto an explicit `buildPageBrowserGraph()` seam so route orchestration no longer treats emitted browser dependencies as a flat route-asset append.
+- Removed the generic HMR runtime-specifier registry and plugin registration seam so core no longer carries import-map-era runtime state that integrations no longer use.
+- Moved foreign-boundary ownership validation out of boundary-plan construction so route root graphs are validated before dependency and data preparation.
+- Moved page-package classification into the asset-processing module so render orchestration no longer carries a dedicated packaging service wrapper.
+- Split file-route page middleware onto its own context contract so page middleware no longer exposes handler-only `ctx.render()` helpers and the pipeline stops carrying fake render traps.
+- Narrowed route-renderer consumers onto explicit resolver contracts, moved filesystem custom 404 rendering back under the filesystem matcher, and shared explicit static render preparation between runtime and static generation.
+
+- Added the `@ecopages/core/dev/host-runtime` seam so host integrations such as the Vite plugin use one explicit development bridge instead of importing host-module-loader and invalidation internals directly.
+- Moved extension-facing merge and assertion helpers behind the integration and processor plugin entrypoints so MDX and image processing no longer depend on raw `utils/deep-merge` or `utils/invariant` package paths.
+- Re-exported shared build-plugin authoring types through the integration and processor plugin entrypoints so extension packages depend on plugin surfaces instead of the raw `build/build-types` module.
+- Removed the legacy `@ecopages/core/errors/locals-access-error` and `@ecopages/core/adapters/bun/client-bridge` exports after moving their remaining consumers to the public `errors` and root type surfaces.
+- Removed the unused `@ecopages/core/utils/parse-cli-args` and `@ecopages/core/services/module-loading/app-server-module-transpiler.service` exports from the published package surface.
+- Removed the unused `@ecopages/core/bun/create-app` and `@ecopages/core/route-renderer/template-serialization` exports to keep the published package surface aligned with the documented entrypoints.
+- Removed the legacy `@ecopages/core/internal-types` export now that the public root package exposes the supported `EcoPagesAppConfig` contract.
+- Removed the duplicate `@ecopages/core/router/client/navigation-coordinator` export in favor of the canonical `@ecopages/core/router/navigation-coordinator` subpath.
+- Bundled page-local component stylesheets and standard file scripts into page-owned assets before processing, reducing per-page asset fan-out in emitted HTML.
+- Grouped Ecopages JSX page and lazy dependency entries into one multi-entry browser build so shared chunks can be emitted once without relying on the runtime alias vendor path.
+- Removed the transitional flat dependency write from render preparation so final HTML injection now follows the structured page-package path only.
+- 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.
+- Replaced the split `FSRouter` and `FSRouterScanner` flow with one `RouteRegistry` seam for filesystem route discovery, request matching, and static-generation planning.
+
+### Bug Fixes
+
+- Fixed integration registry typing so `ConfigBuilder.setIntegrations()` accepts heterogeneous framework plugins without rejecting valid JSX or React integrations at type-check time.
+- Fixed page-owned dependency packaging so final Html output suppresses bundled source stylesheet assets that were reintroduced later during shell-time asset merging.
+- Fixed development page dependency packaging so script Dependencies stay source-backed for HMR instead of being collapsed into one page-owned script bundle.
+- Fixed Bun preview builds to start the static preview server only after static generation releases the live build server port, preventing preview mode from double-binding the configured port.
+- Fixed router-owned HMR current-page reloads to clear persisted layout caches so active shared layouts pick up updated implementations during development.
+- Fixed router-owned HMR layout refreshes to reuse the active HMR page entry instead of stale static bootstrap assets during persisted-layout reloads.
+- Fixed fetch-mode static generation to normalize absolute routes onto the active build runtime origin, restoring preview prerendering for routes discovered from absolute router entries.
+- Fixed global lazy-trigger bootstrap emission to inline the full bootstrap runtime in final HTML, removing separate initial injector bootstrap and runtime requests.
+- Fixed Ecopages JSX lazy-trigger finalization to preserve SSR custom-element markup nodes instead of coercing them to `[object Object]` inside parent renders.
+- Fixed legacy scripts-injector wrapping and grouped content-script bundling cleanup so non-string JSX SSR output stays intact and failed grouped builds do not leak temporary entries.
+- Fixed Ecopages JSX dependency resolution so page bundling now follows only declared `dependencies.scripts` entries, preventing SSR-only imports and lazy-declared scripts from being promoted into the page bundle.
+- Fixed Ecopages JSX lazy dependency bundling to keep page and lazy entries separate, preventing lazy scripts from forcing extra shared chunk requests into the page bundle.
+- Fixed Ecopages JSX dependency emission to collapse bundleable component CSS and module scripts into page-owned assets while preserving lazy trigger scripts.
+- Fixed Ecopages JSX page-owned dependency bundles to keep using the shared JSX and Radiant vendor runtimes so lazy chunks do not trigger duplicate runtime downloads.
+- Fixed Ecopages JSX page-owned browser bundles to keep intrinsic custom-element scripts out of final HTML when the current component tree already imports them, reducing docs home page script fan-out to one page bundle.
+- Fixed Node static builds so `ecopages build` no longer fails when the configured serve port is already in use.
+- 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.
+- Documented that Html-owned dependency assets stay shared while page, layout, and component dependency assets are packaged per route.
+
+### 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.
+- Added router and static-generation regression coverage for `RouteRegistry`, explicit static route expansion, and file-response fallbacks.
+
+---
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.27",
+  "version": "0.2.0-alpha.28",
   "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.28",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
@@ -34,42 +27,34 @@
     "oxc-parser": "^0.124.0",
     "ws": "^8.18.0"
   },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/ws": "^8.5.14",
-    "arktype": "^2.1.29",
-    "tailwindcss": "^3.4.19",
-    "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": {
-      "import": "./src/adapters/create-app.ts",
-      "types": "./src/adapters/create-app.ts",
-      "default": "./src/adapters/create-app.ts"
+      "import": "./src/adapters/create-app.js",
+      "types": "./src/adapters/create-app.d.ts",
+      "default": "./src/adapters/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"
     },
     "./eco": {
-      "browser": "./src/eco/eco.browser.ts",
-      "types": "./src/eco/eco.ts",
-      "default": "./src/eco/eco.ts"
+      "browser": "./src/eco/eco.browser.js",
+      "types": "./src/eco/eco.d.ts",
+      "default": "./src/eco/eco.js"
     },
     "./declarations": {
       "types": "./src/declarations.d.ts"
@@ -78,76 +63,181 @@
       "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/config/constants.ts",
-      "default": "./src/config/constants.ts"
+      "types": "./src/config/constants.d.ts",
+      "default": "./src/config/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"
     },
     "./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"
     },
     "./dev/host-runtime": {
-      "types": "./src/dev/host-runtime.ts",
-      "default": "./src/dev/host-runtime.ts"
+      "types": "./src/dev/host-runtime.d.ts",
+      "default": "./src/dev/host-runtime.js"
     },
     "./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"
     },
     "./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"
     },
     "./plugins/source-transform": {
-      "types": "./src/plugins/source-transform.ts",
-      "default": "./src/plugins/source-transform.ts"
+      "types": "./src/plugins/source-transform.d.ts",
+      "default": "./src/plugins/source-transform.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"
     },
     "./build/runtime-specifier-aliases": {
-      "types": "./src/build/runtime-specifier-aliases.ts",
-      "default": "./src/build/runtime-specifier-aliases.ts"
+      "types": "./src/build/runtime-specifier-aliases.d.ts",
+      "default": "./src/build/runtime-specifier-aliases.js"
     },
     "./plugins/foreign-jsx-override-plugin": {
-      "types": "./src/plugins/foreign-jsx-override-plugin.ts",
-      "default": "./src/plugins/foreign-jsx-override-plugin.ts"
+      "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
+      "default": "./src/plugins/foreign-jsx-override-plugin.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"
     },
     "./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": {
+      "import": "./src/adapters/create-app.js",
+      "types": "./src/adapters/create-app.d.ts",
+      "default": "./src/adapters/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"
+    },
+    "./eco.ts": {
+      "browser": "./src/eco/eco.browser.js",
+      "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/config/constants.d.ts",
+      "default": "./src/config/constants.js"
+    },
+    "./bun.ts": {
+      "types": "./src/adapters/bun/index.d.ts",
+      "default": "./src/adapters/bun/index.js"
+    },
+    "./hmr/hmr-strategy.ts": {
+      "types": "./src/hmr/hmr-strategy.d.ts",
+      "default": "./src/hmr/hmr-strategy.js"
+    },
+    "./dev/host-runtime.ts": {
+      "types": "./src/dev/host-runtime.d.ts",
+      "default": "./src/dev/host-runtime.js"
+    },
+    "./services/asset-processing-service.ts": {
+      "types": "./src/services/assets/asset-processing-service/index.d.ts",
+      "default": "./src/services/assets/asset-processing-service/index.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"
+    },
+    "./plugins/source-transform.ts": {
+      "types": "./src/plugins/source-transform.d.ts",
+      "default": "./src/plugins/source-transform.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"
+    },
+    "./build/runtime-specifier-aliases.ts": {
+      "types": "./src/build/runtime-specifier-aliases.d.ts",
+      "default": "./src/build/runtime-specifier-aliases.js"
+    },
+    "./plugins/foreign-jsx-override-plugin.ts": {
+      "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
+      "default": "./src/plugins/foreign-jsx-override-plugin.js"
+    },
+    "./html.ts": {
+      "import": "./src/utils/html.js",
+      "default": "./src/utils/html.js",
+      "types": "./src/utils/html.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,194 @@
+/**
+ * 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>;
+}