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

package/README.md

@@ -1,32 +1,233 @@
-# 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 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 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.
+- **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.
+- **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[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
+```
+
+### 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 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.
+
+## 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
 ```
 
-## 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`)
 
-Use the root package exports for normal Ecopages authoring:
+Start the application using the universal `createApp` factory. It automatically detects your runtime and applies the correct adapter.
+
+```typescript
+import { createApp } from '@ecopages/core';
+import appConfig from './eco.config';
+
+const app = 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:
+
+```tsx
+import { eco } from '@ecopages/core';
+
+export const MyButton = eco.component({
+	dependencies: {
+		stylesheets: ['./button.css'],
+	},
+	render: ({ label }) => <button className="my-button">{label}</button>,
+});
+```
+
+### 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';
+import { helloWorld } from './handlers/hello';
+import appConfig from './eco.config';
+
+const app = 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 root package exports for standard authoring. The framework automatically detects your runtime and uses the optimal internal adapter:
 
 ```ts
-import { EcopagesApp, defineApiHandler, defineGroupHandler } from '@ecopages/core';
+import { createApp, 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 now the recommended universal 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:
 
 - `@ecopages/core/bun`
 - `@ecopages/core/node`

package/package.json

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

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 on Bun and Node.
+
+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/`: Node server adapter plus thin-host runtime bootstrap 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