@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

package/README.md

@@ -4,10 +4,10 @@ The foundational engine for the Ecopages framework. It provides the core build p
 
 ## Overview
 
-Ecopages is an extensible static site generator (SSG) built for universal execution across Bun and Node.js. It embraces a strictly MPA (Multi-Page Application) architecture by default, rendering HTML at build-time or request-time, and hydrating interactive islands only where necessary.
+Ecopages is an extensible static site generator (SSG) built around a Bun-first core with Node fallback support and Vite-hosted compatibility for advanced dev and build orchestration. It embraces a strictly MPA (Multi-Page Application) architecture by default, rendering HTML at build-time or request-time, and hydrating interactive islands only where necessary.
 
-- **Universal Support**: First-class, optimized execution on both **Bun** and **Node.js** runtimes, powered by a unified `createApp` factory.
-- **Fast by default**: Uses native ESM, optimized file watching, and esbuild for high-performance bundling and server-side rendering.
+- **Runtime Boundary**: `createApp()` prefers Bun when available and falls back to Node otherwise. Vite and Nitro still own host-side dev and build orchestration.
+- **Build Ownership**: Bun-native execution keeps a core-owned build path. Vite and Nitro own host-side transforms, module graph behavior, and deployment-oriented builds.
 - **Framework agnostic**: First-class support for KitaJS, Lit, React, and MDX via official integration plugins.
 - **Extensible**: Hook into the build process with custom processors or rendering integrations.
 
@@ -31,18 +31,14 @@ flowchart TD
 	B --> D[App build manifest]
 	B --> E[Build executor]
 	B --> F[Dev graph service]
-	B --> G[Runtime specifier registry]
-	B --> H[Node runtime manifest]
-	H --> I[CLI launch plan]
-	I --> J[Node thin host]
-	J --> K[Node runtime adapter]
-	K --> L[TranspilerServerLoader]
-	L --> M[ServerModuleTranspiler]
-	M --> N[PageModuleImportService]
-	K --> O[Loaded app runtime]
-	D --> P[BrowserBundleService]
-	E --> M
-	E --> P
+	B --> G[Host module loader boundary]
+	G --> H[PageModuleImportService]
+	E --> H
+	E --> I
+	E --> I[BrowserBundleService]
+	H --> J[Runtime app adapter]
+	J --> K[Bun adapter or Node adapter]
+	D --> I
 ```
 
 ### Development Invalidation And HMR Flow
@@ -71,10 +67,11 @@ The manager/orchestration layer is core-owned, but framework-specific strategies
 
 ### Practical Summary
 
-- `ConfigBuilder` now seeds one app-owned build adapter, manifest, executor, dev graph, and runtime registry.
+- `ConfigBuilder` seeds one app-owned build ownership path, adapter, manifest, executor, dev graph, and runtime registry.
 - `BrowserBundleService` is the shared browser build seam used by HMR and asset-oriented browser output paths.
 - `ServerModuleTranspiler` is the shared server-side source loading seam used by runtime bootstrap and HMR metadata loading.
-- the Node thin-host path exists to keep startup framework-owned without putting source parsing or tsconfig ownership into the host itself.
+- `createApp()` stays the universal runtime entrypoint, while Vite and Nitro hosts own their advanced dev and build workflows.
+- One bundled adapter is the default bundler. Vite-based apps route through the `ViteHostBuildAdapter` boundary marker instead.
 
 ## Documentation Map
 
@@ -102,7 +99,7 @@ The intended reading order is:
 ## Installation
 
 ```bash
-bunx jsr add @ecopages/core
+bun add @ecopages/core
 ```
 
 _(You can also use `npm`, `yarn`, or `pnpm`)_
@@ -134,13 +131,13 @@ export default config;
 
 ### 2. Application Entry (`app.ts`)
 
-Start the application using the universal `createApp` factory. It automatically detects your runtime and applies the correct adapter.
+Start the application using `createApp`. It will choose the Bun adapter when Bun is available and fall back to Node otherwise.
 
 ```typescript
-import { createApp } from '@ecopages/core';
+import { createApp } from '@ecopages/core/create-app';
 import appConfig from './eco.config';
 
-const app = createApp({ appConfig });
+const app = await createApp({ appConfig });
 
 await app.start();
 ```
@@ -181,6 +178,12 @@ export const MyButton = eco.component({
 });
 ```
 
+Dependency ownership affects final asset packaging:
+
+- Stylesheets and scripts declared from `eco.html()` stay Html-owned and can be emitted as shared app-wide assets.
+- Stylesheets and scripts declared from Pages, Layouts, or Components are resolved into page-owned assets for the rendered route.
+- This split is intentional. Shared Html assets can be cached across routes, while page-owned assets can change without invalidating the global shell.
+
 ### 5. API Handlers
 
 Add server-side routes using `defineApiHandler`. Register them on your `app` instance before starting:
@@ -201,11 +204,11 @@ Attach the handler in your `app.ts` entry:
 
 ```typescript
 // app.ts
-import { createApp } from '@ecopages/core';
+import { createApp } from '@ecopages/core/create-app';
 import { helloWorld } from './handlers/hello';
 import appConfig from './eco.config';
 
-const app = createApp({ appConfig });
+const app = await createApp({ appConfig });
 
 app.get(helloWorld); // Register the API handler
 
@@ -216,18 +219,66 @@ See the [official documentation](https://ecopages.app) for advanced usage, API h
 
 ## Import Structure
 
-Use the root package exports for standard authoring. The framework automatically detects your runtime and uses the optimal internal adapter:
+Use the `create-app` subpath for runtime startup and the root package for standard authoring helpers:
 
 ```ts
-import { createApp, defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
+import { createApp } from '@ecopages/core/create-app';
+import { defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
 ```
 
 > [!NOTE]
-> `createApp` is now the recommended universal entrypoint over `EcopagesApp`.
+> `createApp` is the recommended entrypoint over `EcopagesApp`.
 
 ### Runtime Escape Hatches
 
-Use runtime-specific subpaths only when you explicitly need Bun-native or Node-native APIs that bypass the universal abstractions:
+Use runtime-specific subpaths only when you explicitly need Bun-native APIs that bypass the universal abstractions:
 
 - `@ecopages/core/bun`
-- `@ecopages/core/node`
+
+## Entry Point Roles
+
+The published subpaths are grouped by architectural role rather than by source folder.
+
+### App Authoring
+
+Use these entrypoints when building an Ecopages app:
+
+- `@ecopages/core`
+- `@ecopages/core/create-app`
+- `@ecopages/core/config-builder`
+- `@ecopages/core/errors`
+- `@ecopages/core/html`
+- `@ecopages/core/hash`
+- `@ecopages/core/declarations`
+- `@ecopages/core/env`
+- `@ecopages/core/bun`
+
+### Browser Navigation
+
+Use these entrypoints when a browser runtime needs to coordinate document ownership and link intent:
+
+- `@ecopages/core/router/navigation-coordinator`
+- `@ecopages/core/router/link-intent`
+
+### Extension Authoring
+
+Use these entrypoints when implementing integrations, processors, or source transforms:
+
+- `@ecopages/core/plugins/integration-plugin`
+- `@ecopages/core/plugins/processor`
+- `@ecopages/core/plugins/source-transform`
+- `@ecopages/core/route-renderer/integration-renderer`
+- `@ecopages/core/services/asset-processing-service`
+- `@ecopages/core/hmr/hmr-strategy`
+- `@ecopages/core/integrations/ghtml`
+
+### Host And Runtime Composition
+
+Use these entrypoints only when implementing host adapters or framework-owned bundling seams:
+
+- `@ecopages/core/dev/host-runtime`
+- `@ecopages/core/build/build-adapter`
+- `@ecopages/core/build/build-types`
+- `@ecopages/core/plugins/foreign-jsx-override-plugin`
+
+These host-facing entrypoints are narrower compatibility seams. App code and most extensions should prefer the app-authoring or extension-authoring surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.1-beta.0",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,15 +17,17 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.9",
-    "@ecopages/logger": "latest",
-    "@ecopages/scripts-injector": "^0.1.3",
+    "@ecopages/file-system": "0.2.1-beta.0",
+    "@ecopages/logger": "^0.2.3",
+    "@ecopages/scripts-injector": "^0.1.5",
+    "@oxc-project/runtime": "0.134.0",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
-    "chokidar": "^4.0.3",
-    "esbuild": "^0.27.3",
+    "chokidar": "^5.0.0",
+    "esbuild": "^0.28.0",
     "ghtml": "^4.0.2",
-    "oxc-parser": "^0.110.0",
-    "ws": "^8.18.0"
+    "oxc-parser": "^0.124.0",
+    "rolldown": "^1.1.0",
+    "ws": "^8.20.1"
   },
   "exports": {
     ".": {
@@ -35,13 +37,19 @@
       "default": "./src/index.js"
     },
     "./create-app": {
-      "types": "./src/create-app.d.ts",
-      "default": "./src/create-app.js"
+      "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.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
+    "./route-renderer/component-render-context": {
+      "import": "./src/route-renderer/orchestration/component-render-context.js",
+      "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
+      "default": "./src/route-renderer/orchestration/component-render-context.js"
+    },
     "./router/navigation-coordinator": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
@@ -50,15 +58,8 @@
       "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.d.ts",
-      "default": "./src/router/client/navigation-coordinator.js"
-    },
-    "./errors/locals-access-error": {
-      "types": "./src/errors/locals-access-error.d.ts",
-      "default": "./src/errors/locals-access-error.js"
-    },
     "./eco": {
+      "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
@@ -73,40 +74,29 @@
       "default": "./src/config/config-builder.js"
     },
     "./constants": {
-      "types": "./src/constants.d.ts",
-      "default": "./src/constants.js"
+      "types": "./src/config/constants.d.ts",
+      "default": "./src/config/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"
-    },
     "./hmr/hmr-strategy": {
       "types": "./src/hmr/hmr-strategy.d.ts",
       "default": "./src/hmr/hmr-strategy.js"
     },
-    "./internal-types": {
-      "types": "./src/internal-types.d.ts"
+    "./hmr/client/hmr-runtime": {
+      "types": "./src/hmr/client/hmr-runtime.d.ts",
+      "default": "./src/hmr/client/hmr-runtime.js"
+    },
+    "./dev/host-runtime": {
+      "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.d.ts",
       "default": "./src/services/assets/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"
@@ -115,6 +105,10 @@
       "types": "./src/plugins/integration-plugin.d.ts",
       "default": "./src/plugins/integration-plugin.js"
     },
+    "./plugins/source-transform": {
+      "types": "./src/plugins/source-transform.d.ts",
+      "default": "./src/plugins/source-transform.js"
+    },
     "./build/build-types": {
       "types": "./src/build/build-types.d.ts",
       "default": "./src/build/build-types.js"
@@ -123,45 +117,41 @@
       "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.d.ts",
-      "default": "./src/build/runtime-specifier-alias-plugin.js"
+    "./build/runtime-build-output-normalizer": {
+      "types": "./src/build/runtime-build-output-normalizer.d.ts",
+      "default": "./src/build/runtime-build-output-normalizer.js"
     },
-    "./adapters/bun/client-bridge": {
-      "types": "./src/adapters/bun/client-bridge.d.ts",
-      "default": "./src/adapters/bun/client-bridge.js"
+    "./build/browser-runtime-manifest": {
+      "types": "./src/build/browser-runtime-manifest.d.ts",
+      "default": "./src/build/browser-runtime-manifest.js"
     },
-    "./node": {
-      "types": "./src/adapters/node/index.d.ts",
-      "default": "./src/adapters/node/index.js"
+    "./build/browser-runtime-plugin": {
+      "types": "./src/build/browser-runtime-plugin.d.ts",
+      "default": "./src/build/browser-runtime-plugin.js"
     },
-    "./node/server-adapter": {
-      "types": "./src/adapters/node/server-adapter.d.ts",
-      "default": "./src/adapters/node/server-adapter.js"
+    "./cache": {
+      "types": "./src/cache/index.d.ts",
+      "default": "./src/cache/index.js"
     },
-    "./node/create-app": {
-      "types": "./src/adapters/node/create-app.d.ts",
-      "default": "./src/adapters/node/create-app.js"
-    },
-    "./node/runtime-adapter": {
-      "types": "./src/adapters/node/runtime-adapter.d.ts",
-      "default": "./src/adapters/node/runtime-adapter.js"
+    "./plugins/foreign-jsx-override-plugin": {
+      "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
+      "default": "./src/plugins/foreign-jsx-override-plugin.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"
     },
+    "./utils/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"
@@ -171,13 +161,19 @@
       "default": "./src/integrations/ghtml/ghtml.plugin.js"
     },
     "./create-app.ts": {
-      "types": "./src/create-app.d.ts",
-      "default": "./src/create-app.js"
+      "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"
     },
+    "./route-renderer/component-render-context.ts": {
+      "import": "./src/route-renderer/orchestration/component-render-context.js",
+      "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
+      "default": "./src/route-renderer/orchestration/component-render-context.js"
+    },
     "./router/navigation-coordinator.ts": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
@@ -186,15 +182,8 @@
       "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": {
+      "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
@@ -209,40 +198,29 @@
       "default": "./src/config/config-builder.js"
     },
     "./constants.ts": {
-      "types": "./src/constants.d.ts",
-      "default": "./src/constants.js"
+      "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"
     },
-    "./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"
+    "./hmr/client/hmr-runtime.ts": {
+      "types": "./src/hmr/client/hmr-runtime.d.ts",
+      "default": "./src/hmr/client/hmr-runtime.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"
     },
-    "./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"
@@ -251,6 +229,10 @@
       "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"
@@ -259,45 +241,41 @@
       "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-build-output-normalizer.ts": {
+      "types": "./src/build/runtime-build-output-normalizer.d.ts",
+      "default": "./src/build/runtime-build-output-normalizer.js"
     },
-    "./adapters/bun/client-bridge.ts": {
-      "types": "./src/adapters/bun/client-bridge.d.ts",
-      "default": "./src/adapters/bun/client-bridge.js"
+    "./build/browser-runtime-manifest.ts": {
+      "types": "./src/build/browser-runtime-manifest.d.ts",
+      "default": "./src/build/browser-runtime-manifest.js"
     },
-    "./node.ts": {
-      "types": "./src/adapters/node/index.d.ts",
-      "default": "./src/adapters/node/index.js"
+    "./build/browser-runtime-plugin.ts": {
+      "types": "./src/build/browser-runtime-plugin.d.ts",
+      "default": "./src/build/browser-runtime-plugin.js"
     },
-    "./node/server-adapter.ts": {
-      "types": "./src/adapters/node/server-adapter.d.ts",
-      "default": "./src/adapters/node/server-adapter.js"
+    "./cache.ts": {
+      "types": "./src/cache/index.d.ts",
+      "default": "./src/cache/index.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"
+    "./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"
     },
-    "./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"
     },
+    "./utils/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"

package/src/adapters/README.md

@@ -4,7 +4,7 @@ This directory contains the runtime-host integration layer for Ecopages.
 
 ## Purpose
 
-Adapters translate app-owned core services into concrete runtime behavior on Bun and Node.
+Adapters translate app-owned core services into concrete runtime behavior at the host boundary. Bun remains the direct core runtime, while Node compatibility is driven by the Ecopages CLI thin-host path and reuses internal adapter pieces here.
 
 They are responsible for:
 
@@ -23,7 +23,7 @@ They are not responsible for:
 ## Main Areas
 
 - `bun/`: Bun server adapter, lifecycle coordination, bridge, and HMR transport
-- `node/`: Node server adapter plus thin-host runtime bootstrap path
+- `node/`: internal Node compatibility adapter pieces used by the CLI thin-host path
 - `shared/`: runtime-neutral adapter helpers used by both hosts
 
 ## Ownership Boundary

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

@@ -6,15 +6,40 @@
  *
  * @module ApplicationAdapter
  */
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../public-types.js';
+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
@@ -43,6 +68,7 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
     protected appConfig: EcoPagesAppConfig;
     protected serverOptions: Record<string, any>;
     protected cliArgs: ReturnParseCliArgs;
+    protected runtimeOptions: ApplicationRuntimeOptions;
     protected apiHandlers: ApiHandler[];
     protected staticRoutes: StaticRoute[];
     protected errorHandler?: ErrorHandler;

package/src/adapters/abstract/application-adapter.js

@@ -1,4 +1,9 @@
 import { appLogger } from "../../global/app-logger.js";
+import {
+  getAppModuleLoader,
+  setAppHostModuleLoader
+} from "../../services/module-loading/app-server-module-transpiler.service.js";
+import { getHostModuleLoader } from "../../services/module-loading/host-module-loader-registry.js";
 import { invariant } from "../../utils/invariant.js";
 import { fileSystem } from "@ecopages/file-system";
 import { parseCliArgs } from "../../utils/parse-cli-args.js";
@@ -6,20 +11,27 @@ class AbstractApplicationAdapter {
   appConfig;
   serverOptions;
   cliArgs;
+  runtimeOptions;
   apiHandlers = [];
   staticRoutes = [];
   errorHandler;
   constructor(options) {
     this.appConfig = options.appConfig;
     this.serverOptions = options.serverOptions || {};
-    this.cliArgs = parseCliArgs();
+    this.runtimeOptions = options.runtime ?? {};
+    this.cliArgs = parseCliArgs({ embeddedRuntime: this.runtimeOptions.embedded });
+    const hostModuleLoader = this.runtimeOptions.hostModuleLoader ?? (this.runtimeOptions.embedded ? getHostModuleLoader() : void 0);
+    if (hostModuleLoader) {
+      setAppHostModuleLoader(this.appConfig, hostModuleLoader);
+    }
+    getAppModuleLoader(this.appConfig);
     if (options.clearOutput) {
       this.clearDistFolder().catch((error) => {
         appLogger.error("Error clearing dist folder", error);
       });
     }
   }
-  async clearDistFolder(_filter = []) {
+  async clearDistFolder() {
     const distPath = this.appConfig.absolutePaths.distDir;
     const distExists = fileSystem.exists(distPath);
     if (!distExists) return;