@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.10

package/CHANGELOG.md

@@ -6,84 +6,27 @@ All notable changes to `@ecopages/core` are documented here.
 
 ## [UNRELEASED] — TBD
 
-### Features
-
-#### Node.js Runtime Support
-
-- **Node server adapter** — Full HTTP server adapter for Node.js via `packages/core/src/adapters/node/`, including request bridging, route handling, static content serving, and graceful shutdown.
-- **Node static build pipeline** — Static-site build and preview server for Node.js runtime (`ab22f167`, `a47b4da3`, `435dc250`).
-- **Node API handler pipeline** — `define-api-handler` now works cross-runtime; Node adapter wires API handler execution end-to-end (`73e57d87`, `f46aa528`).
-- **Node client bridge** — `NodeClientBridge` with SSE-based HMR stream and heartbeat mechanism for connection health (`3361445f`).
-- **Node HMR manager** — `NodeHmrManager` that mirrors Bun HMR capabilities on the Node runtime.
-- **`createApp` universal factory** — Top-level `createApp` export that selects the correct adapter (Bun or Node) at runtime (`ce691bdf`, `2f1b1109`).
-
-#### Build System
-
-- **`EsbuildBuildAdapter`** — A new build backend backed by esbuild, replacing the Bun-only transpilation path. Includes module resolution routing, plugin registration, and transpilation defaults (`f503e86e`, `94c37d38`, `e4e124a1`).
-- **Build dependency graph** — `BuildDependencyGraph` interface for tracking entrypoints and their asset dependencies, enabling more accurate HMR invalidation (`e7653c9b`).
-- **Build adapter abstraction** — `build-adapter.ts` and `build-types.ts` decouple build and plugin contracts from Bun-specific types (`11b03bcc`).
-
-#### Rendering & Orchestration
-
-- **Boundary rendering policy** — Cross-integration component boundaries are now explicitly enforced (`ec1e4d66`).
-- **Full orchestration mode** — Legacy rendering mode branches removed; the engine always runs in unified orchestration mode (`f652fa0a`).
-- **Extracted render services** — The render pipeline is decomposed into focused services:
-    - `RenderExecutionService`
-    - `HtmlPostProcessingService`
-    - `RenderPreparationService`
-    - `MarkerGraphResolver`
-    - `FileRouteMiddlewarePipeline`
-    - `PageRequestCacheCoordinator`
-    - `PageModuleImportService`
-- **Component render context** — New `ComponentRenderContext` consolidates component-level state during rendering (`eco/component-render-context.ts`).
-- **Worker-tools HTML rewriter fallback** — `html-transformer` adopts `@worker-tools/html-rewriter` as a fallback for non-Bun environments (`54056d4f`).
-
-#### Dependency & Injection
-
-- **Global injector map** — `GlobalInjectorMap` and `LazyInjectorMap` provide structured, testable dependency injection for global and lazy assets (`c3a25072`).
-- **Lazy dependency resolution** — SSR lazy script resolution now uses dedicated utility functions for dependency entry attributes and content generation (`71ce2f4f`).
-- **Dependency entry type refactor** — Unified types for script and stylesheet dependency entries, with improved error messages (`1e02dba6`).
-- **Module dependencies** — New `module-dependencies.ts` tracks explicit module-level asset relationships.
-- **Eco utils extraction** — Shared utilities moved to `eco.utils.ts` to remove runtime metadata fallbacks (`bdc60d50`).
-
-#### API Handlers
-
-- **Unified typed API handler context** — `defineApiHandler` now exposes a fully typed, runtime-agnostic context object. The Bun-specific adapter is slimmed down to a thin wrapper (`2f1b1109`, `08e194b4`).
-- **Portable root runtime API** — Core exposes a portable API surface that avoids runtime escape hatches (`ce691bdf`, `1ec42c02`).
-
-### Refactoring
-
-- **Bun adapter isolation** — Bun-specific types (`serve` options, file reads, env access, argv/hash helpers) are routed through dedicated helpers, making the remaining adapter code portable (`73668f52`, `0c90ced1`, `73fb904a`, `5eb0957b`, `4bdc74a9`, `e9ce163c`, `22f9de4a`, `f7b3d95e`).
-- **Shared server adapter** — Common server adapter logic extracted to `adapters/shared/application-adapter.ts` and `adapters/shared/server-adapter.ts`, shared between Bun and Node adapters (`5a872eda`).
-- **Route assets isolation** — Route-level assets are now isolated per-request, hardening dependency processing (`3fd76a12`).
-- **Shared matcher error constants** — Matcher error strings are now constants shared across test and source (`ff4db106`).
-- **App registration & fetch pipeline** — App creation and request handling consolidated into a single unified pipeline (`86e20a3d`).
-- **Adapter escape hatch surface** trimmed — Public adapter API is narrowed to reduce surface area (`1ec42c02`).
-
 ### Bug Fixes
 
-- Fixed invariant checks for route paths with improved error messaging in `AbstractApplicationAdapter` (`9c2a6242`).
-- Fixed dependency import name extraction in `extractEcopagesVirtualImports` (`39bbc472`).
-- Removed an invalid npm export entry that pointed to a non-existent `utils/ecopages-url-resolver` declaration target.
+- Fixed npm release packaging to publish rewritten internal dependency versions instead of unresolved `workspace:*` ranges.
+- Fixed published npm packaging to exclude raw TypeScript sources from tarballs so consumers resolve the built JavaScript and declaration outputs consistently.
 
-### Tests
+### Features & Architecture
 
-- Added node static content server test coverage (`435dc250`).
-- Strengthened HTML transformer mode matrix coverage (`286c1253`).
-- Aligned integration and dependency processing tests to new orchestration model (`7cc73316`).
-- Added `EsbuildBuildAdapter` test suite with 500+ lines (`build-adapter.test.ts`).
-- Added `file-route-middleware-pipeline` tests.
+- **Experimental Node.js Support**: Introduced a framework-owned thin-host bootstrap and runtime manifest flow for Node.js, providing cross-runtime parity while keeping the core agnostic.
+- **Architectural Consolidation**: Unified server-side loading, browser bundling, and HMR strategy orchestration across all runtimes using shared core services (`ServerModuleTranspiler`, `BrowserBundleService`).
+- **Build & Asset Refinement**: Introduced an internal `.eco` work directory to isolate development artifacts from production exports, and added `eco.html()`/`eco.layout()` for semantic component definitions.
+- **Performance & Reliability**: Refactored internal watchers and HMR dispatching to improve build stability during rapid development cycles.
 
-### Documentation
+### Tests & Documentation
 
-- Updated rendering graph documentation to cover extracted rendering services (`8bfcfd21`).
-- Refreshed server handler and module dependency guidance (`3494f44d`).
+- **Robust Regression Suite**: Added coverage for experimental Node.js paths, the new shared services, and cross-runtime file-change dispatching.
+- **Architecture Docs**: Added focused architecture and API documentation for config, plugins, services, adapters, HMR, router, and the rendering lifecycle.
 
 ---
 
 ## Migration Notes
 
-- **`createApp`** is now the recommended entrypoint (previously `EcopagesApp`). Import from `@ecopages/core`.
-- **`defineApiHandler`** signature is unchanged but the handler context object now carries explicit runtime-agnostic types. No breaking changes for existing handlers.
-- Bun adapter still works as before; the new Node adapter is additive.
-- The old explicit `renderingMode` config option has been removed — full orchestration is always active.
+- `createApp` is now the recommended entrypoint. Import it from `@ecopages/core`.
+- `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/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.1",
+  "version": "0.2.0-alpha.10",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.1",
+    "@ecopages/file-system": "0.2.0-alpha.10",
     "@ecopages/logger": "latest",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",
@@ -39,8 +39,20 @@
       "default": "./src/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"
+    },
+    "./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"
+    },
+    "./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",
@@ -72,10 +84,6 @@
       "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"
@@ -84,8 +92,8 @@
       "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"
+      "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",
@@ -115,6 +123,10 @@
       "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"
+    },
     "./adapters/bun/client-bridge": {
       "types": "./src/adapters/bun/client-bridge.d.ts",
       "default": "./src/adapters/bun/client-bridge.js"
@@ -131,6 +143,10 @@
       "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"
+    },
     "./html": {
       "import": "./src/utils/html.js",
       "default": "./src/utils/html.js",
@@ -159,8 +175,20 @@
       "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"
+      "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"
+    },
+    "./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",
@@ -192,10 +220,6 @@
       "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"
@@ -204,8 +228,8 @@
       "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"
+      "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",
@@ -235,6 +259,10 @@
       "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"
+    },
     "./adapters/bun/client-bridge.ts": {
       "types": "./src/adapters/bun/client-bridge.d.ts",
       "default": "./src/adapters/bun/client-bridge.js"
@@ -251,6 +279,10 @@
       "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"
+    },
     "./html.ts": {
       "import": "./src/utils/html.js",
       "default": "./src/utils/html.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 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