@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.41

package/README.md

@@ -1,32 +1,286 @@
-# Ecopages
+# @ecopages/core
 
-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.
+The foundational engine for the Ecopages framework. It provides the core build pipeline, development server, routing, and plugin architecture required to run an Ecopages application.
 
-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.
+## Overview
 
-Ecopages relies on a minimal set of dependencies, carefully chosen to support its core functionality.
+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.
 
-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.
+- **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.
 
-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.
+## Current Architecture
 
-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).
+The current core package is organized around app-owned runtime state and explicit service boundaries.
 
-## Install
+The important ownership rules are:
+
+- `ConfigBuilder.build()` finalizes app-owned build and runtime services.
+- browser bundling and server module loading are explicit, separate paths.
+- runtime hosts stay thin and delegate framework work into core services.
+- HMR and invalidation use shared graph-aware services instead of runtime-specific ad hoc wiring.
+
+### Bootstrap And Runtime Ownership
+
+```mermaid
+flowchart TD
+	A[eco.config.ts] --> B[ConfigBuilder.build]
+	B --> C[App build adapter]
+	B --> D[App build manifest]
+	B --> E[Build executor]
+	B --> F[Dev graph service]
+	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
+
+```mermaid
+flowchart TD
+	A[File change] --> B[ProjectWatcher]
+	B --> C[DevelopmentInvalidationService]
+	C --> D{Change kind}
+	D -->|Route or server source| E[Invalidate server modules]
+	D -->|Public or include| F[Reload browser]
+	D -->|Processor-owned asset| G[Notify processor only]
+	D -->|HMR-eligible source| H[Core HMR manager]
+	H --> I[Strategy selection]
+	I --> J[Core JsHmrStrategy]
+	I --> K[Integration strategy e.g. ReactHmrStrategy]
+	J --> L[BrowserBundleService]
+	K --> L
+	K --> M[importServerModule]
+	M --> N[ServerModuleTranspiler]
+	L --> O[Updated browser bundle]
+	O --> P[Client bridge broadcast]
+```
+
+The manager/orchestration layer is core-owned, but framework-specific strategies such as React HMR are contributed by integrations and registered with the shared HMR manager.
+
+### Practical Summary
+
+- `ConfigBuilder` now 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.
+- `createApp()` stays the universal runtime entrypoint, while Vite and Nitro hosts own their advanced dev and build workflows.
+- esbuild remains only as a temporary Bun-path implementation detail and is not a strategic core dependency.
+
+## Documentation Map
+
+Use this package README as the top-level map, then drill into the focused subsystem READMEs:
+
+- `src/config/README.md`: config finalization and app-owned runtime/build state
+- `src/plugins/README.md`: integration and processor authoring contracts
+- `src/build/README.md`: build adapter, executor, and development build coordination
+- `src/services/README.md`: cross-cutting runtime services and orchestration helpers
+- `src/adapters/README.md`: Bun, Node, and shared adapter boundaries
+- `src/hmr/README.md`: HMR strategy and update-layer ownership
+- `src/router/README.md`: route discovery, matching, and browser navigation coordination
+- `src/route-renderer/README.md`: rendering orchestration and dependency resolution
+- `src/static-site-generator/README.md`: static build execution path
+- `src/eco/README.md`: `eco` authoring APIs for pages, layouts, and components
+
+The intended reading order is:
+
+1. this file for the big-picture architecture
+2. `src/config/README.md` for config and lifecycle ownership
+3. `src/plugins/README.md` and `src/build/README.md` for contribution contracts
+4. `src/services/README.md` and `src/adapters/README.md` for runtime execution
+5. `src/router/README.md` and `src/route-renderer/README.md` for request-time flow
+
+## Installation
 
 ```bash
-bunx jsr add @ecopages/core
+bun add @ecopages/core
 ```
 
-## Portable imports first
+_(You can also use `npm`, `yarn`, or `pnpm`)_
+
+## Basic Usage
+
+The Ecopages architecture revolves around an `eco.config.ts` file and an application entry point.
+
+### 1. Configuration (`eco.config.ts`)
+
+Configure your integratons, processors, and default metadata. Ecopages uses a builder pattern:
+
+```typescript
+import { ConfigBuilder } from '@ecopages/core/config-builder';
+// import your desired plugins...
+
+const config = await new ConfigBuilder()
+	.setRootDir(import.meta.dirname)
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL ?? 'http://localhost:3000')
+	.setDefaultMetadata({
+		title: 'My Ecopages Site',
+		description: 'Built with Ecopages',
+	})
+	// .setIntegrations([kitajsPlugin()])
+	.build();
+
+export default config;
+```
+
+### 2. Application Entry (`app.ts`)
+
+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/create-app';
+import appConfig from './eco.config';
+
+const app = await createApp({ appConfig });
+
+await app.start();
+```
+
+### 3. Creating Pages
+
+Use the `eco.page()` factory to define static routes. Place these in `src/pages/`:
+
+```tsx
+import { eco } from '@ecopages/core';
+import { BaseLayout } from '@/layouts/base-layout';
+
+export default eco.page({
+	layout: BaseLayout,
+	metadata: () => ({
+		title: 'Home',
+	}),
+	render: () => (
+		<div>
+			<h1>Welcome to Ecopages</h1>
+		</div>
+	),
+});
+```
+
+### 4. Reusable Components
+
+Define components with `eco.component()` to automatically inject necessary stylesheets or scripts only when that component is rendered:
 
-Use the root package exports for normal Ecopages authoring:
+```tsx
+import { eco } from '@ecopages/core';
+
+export const MyButton = eco.component({
+	dependencies: {
+		stylesheets: ['./button.css'],
+	},
+	render: ({ label }) => <button className="my-button">{label}</button>,
+});
+```
+
+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:
+
+```typescript
+import { defineApiHandler } from '@ecopages/core';
+
+export const helloWorld = defineApiHandler({
+	path: '/api/hello',
+	method: 'GET',
+	handler: async ({ response }) => {
+		return response.json({ message: 'Hello World' });
+	},
+});
+```
+
+Attach the handler in your `app.ts` entry:
+
+```typescript
+// app.ts
+import { createApp } from '@ecopages/core/create-app';
+import { helloWorld } from './handlers/hello';
+import appConfig from './eco.config';
+
+const app = await createApp({ appConfig });
+
+app.get(helloWorld); // Register the API handler
+
+await app.start();
+```
+
+See the [official documentation](https://ecopages.app) for advanced usage, API handlers, and integrations.
+
+## Import Structure
+
+Use the `create-app` subpath for runtime startup and the root package for standard authoring helpers:
 
 ```ts
-import { EcopagesApp, defineApiHandler, defineGroupHandler } from '@ecopages/core';
+import { createApp } from '@ecopages/core/create-app';
+import { defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
 ```
 
-Use runtime-specific subpaths only as advanced escape hatches when you explicitly need Bun- or Node-native APIs:
+> [!NOTE]
+> `createApp` is the recommended entrypoint over `EcopagesApp`.
+
+### Runtime Escape Hatches
+
+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/build/runtime-specifier-alias-plugin`
+- `@ecopages/core/build/runtime-specifier-aliases`
+- `@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.4",
+  "version": "0.2.0-alpha.41",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,15 +17,15 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.4",
-    "@ecopages/logger": "latest",
-    "@ecopages/scripts-injector": "^0.1.3",
+    "@ecopages/file-system": "0.2.0-alpha.41",
+    "@ecopages/logger": "^0.2.3",
+    "@ecopages/scripts-injector": "^0.1.5",
     "@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",
+    "ws": "^8.20.1"
   },
   "exports": {
     ".": {
@@ -35,18 +35,29 @@
       "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/integration-renderer.d.ts",
-      "default": "./src/route-renderer/integration-renderer.js"
+      "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
+      "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
-    "./errors/locals-access-error": {
-      "types": "./src/errors/locals-access-error.d.ts",
-      "default": "./src/errors/locals-access-error.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"
+    },
+    "./router/link-intent": {
+      "types": "./src/router/client/link-intent.d.ts",
+      "default": "./src/router/client/link-intent.js"
     },
     "./eco": {
+      "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
@@ -61,43 +72,28 @@
       "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"
-    },
-    "./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"
+    "./hmr/client/hmr-runtime": {
+      "types": "./src/hmr/client/hmr-runtime.d.ts",
+      "default": "./src/hmr/client/hmr-runtime.js"
     },
-    "./utils/deep-merge": {
-      "types": "./src/utils/deep-merge.d.ts",
-      "default": "./src/utils/deep-merge.js"
+    "./dev/host-runtime": {
+      "types": "./src/dev/host-runtime.d.ts",
+      "default": "./src/dev/host-runtime.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"
+    "./services/asset-processing-service": {
+      "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.d.ts",
@@ -107,6 +103,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"
@@ -115,32 +115,23 @@
       "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"
+    "./build/runtime-specifier-alias-plugin": {
+      "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
+      "default": "./src/build/runtime-specifier-alias-plugin.js"
     },
-    "./node": {
-      "types": "./src/adapters/node/index.d.ts",
-      "default": "./src/adapters/node/index.js"
+    "./build/runtime-specifier-aliases": {
+      "types": "./src/build/runtime-specifier-aliases.d.ts",
+      "default": "./src/build/runtime-specifier-aliases.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"
+    "./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",
@@ -155,18 +146,29 @@
       "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/integration-renderer.d.ts",
-      "default": "./src/route-renderer/integration-renderer.js"
+      "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
+      "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
-    "./errors/locals-access-error.ts": {
-      "types": "./src/errors/locals-access-error.d.ts",
-      "default": "./src/errors/locals-access-error.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"
+    },
+    "./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"
     },
@@ -181,43 +183,28 @@
       "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"
-    },
-    "./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"
+    "./hmr/client/hmr-runtime.ts": {
+      "types": "./src/hmr/client/hmr-runtime.d.ts",
+      "default": "./src/hmr/client/hmr-runtime.js"
     },
-    "./utils/deep-merge.ts": {
-      "types": "./src/utils/deep-merge.d.ts",
-      "default": "./src/utils/deep-merge.js"
+    "./dev/host-runtime.ts": {
+      "types": "./src/dev/host-runtime.d.ts",
+      "default": "./src/dev/host-runtime.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"
+    "./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",
@@ -227,6 +214,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"
@@ -235,32 +226,23 @@
       "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"
+    "./build/runtime-specifier-alias-plugin.ts": {
+      "types": "./src/build/runtime-specifier-alias-plugin.d.ts",
+      "default": "./src/build/runtime-specifier-alias-plugin.js"
     },
-    "./node.ts": {
-      "types": "./src/adapters/node/index.d.ts",
-      "default": "./src/adapters/node/index.js"
+    "./build/runtime-specifier-aliases.ts": {
+      "types": "./src/build/runtime-specifier-aliases.d.ts",
+      "default": "./src/build/runtime-specifier-aliases.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"
+    "./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",

package/src/adapters/README.md

@@ -0,0 +1,39 @@
+# Runtime Adapters
+
+This directory contains the runtime-host integration layer for Ecopages.
+
+## Purpose
+
+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:
+
+- starting and stopping runtime-specific servers or thin hosts
+- delegating startup into framework-owned loaders and services
+- bridging runtime-specific request/response or HMR transport details
+- keeping host/runtime transport details out of generic core orchestration
+
+They are not responsible for:
+
+- deciding plugin lifecycle ordering
+- owning server-module semantics
+- owning browser bundling policy
+- owning route rendering semantics
+
+## Main Areas
+
+- `bun/`: Bun server adapter, lifecycle coordination, bridge, and HMR transport
+- `node/`: internal Node compatibility adapter pieces used by the CLI thin-host path
+- `shared/`: runtime-neutral adapter helpers used by both hosts
+
+## Ownership Boundary
+
+The adapter layer is transport-oriented.
+
+Core services still own:
+
+- config finalization
+- build-manifest assembly
+- server loading
+- invalidation classification
+- route rendering orchestration