@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.30

package/CHANGELOG.md

@@ -8,84 +8,84 @@ All notable changes to `@ecopages/core` are documented here.
 
 ### 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`).
+- Added app-owned runtime and build ownership around `createApp()`, host module loading, the browser-safe `eco` export, `eco.html()`, `eco.layout()`, and the published `EcoPagesAppConfig` surface.
+- Added boundary-plan metadata and a compatibility `renderBoundary()` payload contract for mixed-renderer orchestration.
 
 ### Refactoring
 
-- **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`).
+- Renamed route-renderer ownership and foreign-child contracts across core so ownership planning, foreign-subtree payloads, and queued foreign-subtree resolution now use the simplified terminology.
+- Introduced a single `RouteRenderFlow` owner for route render preparation and execution, removing the separate execution service seam while keeping boundary planning shared.
+- Narrowed route-render orchestration onto an explicit `RouteRenderFlowAdapter` seam and one structural Html finalization plan, reducing callback-bag plumbing between `RouteRenderFlow` and `IntegrationRenderer`.
+- Renamed renderer-owned page browser asset preparation onto an explicit `buildPageBrowserGraph()` seam so route orchestration no longer treats emitted browser dependencies as a flat route-asset append.
+- Removed the generic HMR runtime-specifier registry and plugin registration seam so core no longer carries import-map-era runtime state that integrations no longer use.
+- Moved foreign-boundary ownership validation out of boundary-plan construction so route root graphs are validated before dependency and data preparation.
+- Moved page-package classification into the asset-processing module so render orchestration no longer carries a dedicated packaging service wrapper.
+- Split file-route page middleware onto its own context contract so page middleware no longer exposes handler-only `ctx.render()` helpers and the pipeline stops carrying fake render traps.
+- Narrowed route-renderer consumers onto explicit resolver contracts, moved filesystem custom 404 rendering back under the filesystem matcher, and shared explicit static render preparation between runtime and static generation.
+
+- Added the `@ecopages/core/dev/host-runtime` seam so host integrations such as the Vite plugin use one explicit development bridge instead of importing host-module-loader and invalidation internals directly.
+- Moved extension-facing merge and assertion helpers behind the integration and processor plugin entrypoints so MDX and image processing no longer depend on raw `utils/deep-merge` or `utils/invariant` package paths.
+- Re-exported shared build-plugin authoring types through the integration and processor plugin entrypoints so extension packages depend on plugin surfaces instead of the raw `build/build-types` module.
+- Removed the legacy `@ecopages/core/errors/locals-access-error` and `@ecopages/core/adapters/bun/client-bridge` exports after moving their remaining consumers to the public `errors` and root type surfaces.
+- Removed the unused `@ecopages/core/utils/parse-cli-args` and `@ecopages/core/services/module-loading/app-server-module-transpiler.service` exports from the published package surface.
+- Removed the unused `@ecopages/core/bun/create-app` and `@ecopages/core/route-renderer/template-serialization` exports to keep the published package surface aligned with the documented entrypoints.
+- Removed the legacy `@ecopages/core/internal-types` export now that the public root package exposes the supported `EcoPagesAppConfig` contract.
+- Removed the duplicate `@ecopages/core/router/client/navigation-coordinator` export in favor of the canonical `@ecopages/core/router/navigation-coordinator` subpath.
+- Bundled page-local component stylesheets and standard file scripts into page-owned assets before processing, reducing per-page asset fan-out in emitted HTML.
+- Grouped Ecopages JSX page and lazy dependency entries into one multi-entry browser build so shared chunks can be emitted once without relying on the runtime alias vendor path.
+- Removed the transitional flat dependency write from render preparation so final HTML injection now follows the structured page-package path only.
+- Consolidated runtime state around shared module-loading services, app-owned build execution, and the universal `createApp()` boundary.
+- Simplified route-renderer orchestration around renderer-owned boundary runtimes, shared string-boundary queue helpers, and a smaller component render context.
+- Centralized shared integration renderer bootstrapping so package integrations only append renderer-specific config instead of duplicating core lifecycle wiring.
+- Moved shared queued boundary resolution to attachment-policy payloads and constructor-injectable planning services.
+- Extracted shared page, layout, and document-shell composition into a narrow `RouteShellComposer` while keeping renderer-owned boundary handoff in `IntegrationRenderer`.
+- Removed marker-era compatibility capture, the shared route-level fallback resolver, deprecated `@ecopages/core/node*` escape hatches, and other dead route-renderer internals.
+- Replaced the split `FSRouter` and `FSRouterScanner` flow with one `RouteRegistry` seam for filesystem route discovery, request matching, and static-generation planning.
 
 ### Bug Fixes
 
-- Fixed 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.
-- Kept source module HMR active when stylesheet processors also watch TSX and JSX files for Tailwind-driven CSS rebuilds.
-- Triggered HMR current-page refreshes instead of fallback reload suppression for processor-watched TSX and JSX changes that are not client entrypoints.
+- Fixed integration registry typing so `ConfigBuilder.setIntegrations()` accepts heterogeneous framework plugins without rejecting valid JSX or React integrations at type-check time.
+- Fixed page-owned dependency packaging so final Html output suppresses bundled source stylesheet assets that were reintroduced later during shell-time asset merging.
+- Fixed development page dependency packaging so script Dependencies stay source-backed for HMR instead of being collapsed into one page-owned script bundle.
+- Fixed Bun preview builds to start the static preview server only after static generation releases the live build server port, preventing preview mode from double-binding the configured port.
+- Fixed router-owned HMR current-page reloads to clear persisted layout caches so active shared layouts pick up updated implementations during development.
+- Fixed router-owned HMR layout refreshes to reuse the active HMR page entry instead of stale static bootstrap assets during persisted-layout reloads.
+- Fixed fetch-mode static generation to normalize absolute routes onto the active build runtime origin, restoring preview prerendering for routes discovered from absolute router entries.
+- Fixed global lazy-trigger bootstrap emission to inline the full bootstrap runtime in final HTML, removing separate initial injector bootstrap and runtime requests.
+- Fixed Ecopages JSX lazy-trigger finalization to preserve SSR custom-element markup nodes instead of coercing them to `[object Object]` inside parent renders.
+- Fixed legacy scripts-injector wrapping and grouped content-script bundling cleanup so non-string JSX SSR output stays intact and failed grouped builds do not leak temporary entries.
+- Fixed Ecopages JSX dependency resolution so page bundling now follows only declared `dependencies.scripts` entries, preventing SSR-only imports and lazy-declared scripts from being promoted into the page bundle.
+- Fixed Ecopages JSX lazy dependency bundling to keep page and lazy entries separate, preventing lazy scripts from forcing extra shared chunk requests into the page bundle.
+- Fixed Ecopages JSX dependency emission to collapse bundleable component CSS and module scripts into page-owned assets while preserving lazy trigger scripts.
+- Fixed Ecopages JSX page-owned dependency bundles to keep using the shared JSX and Radiant vendor runtimes so lazy chunks do not trigger duplicate runtime downloads.
+- Fixed Ecopages JSX page-owned browser bundles to keep intrinsic custom-element scripts out of final HTML when the current component tree already imports them, reducing docs home page script fan-out to one page bundle.
+- Fixed Node static builds so `ecopages build` no longer fails when the configured serve port is already in use.
+- Fixed mixed-integration page, layout, document, and component rendering to resolve foreign boundaries inside their owning renderer across the built-in integrations.
+- Fixed host/runtime module loading, published build-helper exports, asset output normalization, explicit render flows, and static or preview build stability across Bun, Node, Vite, and Nitro.
+- Fixed development project watcher setup to register chokidar paths and handlers only once per app runtime.
+- Fixed development script-entry registration to build only the requested HMR entrypoint instead of fanning out across all watched script entrypoints during startup.
+- Fixed Node bootstrap runtime package linking to refresh dangling `.eco/node_modules` symlinks instead of failing with `EEXIST` during page transpilation.
+- Fixed request-time and static-generation page inspection to preserve integration-specific page loading without reusing the normal render module identity.
+- Fixed Node preview and static-generation React runtime resolution so app-owned page modules and server rendering share one React module identity.
+- Fixed Bun browser output normalization so batched multi-entrypoint HMR rebuilds match emitted files to their expected served paths instead of Bun output order.
+- Fixed render-preparation graph traversal so sparse component dependency arrays do not break custom 404 rendering or file-system response fallback flows.
 
-### Tests
+### Documentation
 
-- 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.
+- Added architecture and API documentation for config, plugins, services, adapters, HMR, routing, and rendering.
+- Documented that Html-owned dependency assets stay shared while page, layout, and component dependency assets are packaged per route.
 
-### Documentation
+### Tests
 
-- Updated rendering graph documentation to cover extracted rendering services (`8bfcfd21`).
-- Refreshed server handler and module dependency guidance (`3494f44d`).
+- Added regression coverage for app-owned runtime services, Node fallback paths, and cross-runtime invalidation behavior.
+- Strengthened the core ghtml integration tests so route and explicit render paths await real outcomes and cover `renderToResponse` behavior.
+- Added core regression coverage for boundary plans, payload contracts, and typed mixed-boundary context flow.
+- Added router and static-generation regression coverage for `RouteRegistry`, explicit static route expansion, and file-response fallbacks.
 
 ---
 
 ## Migration Notes
 
-- **`createApp`** is now the recommended entrypoint (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/create-app`.
+- `defineApiHandler` keeps the same call shape, but the handler context is now explicitly runtime-agnostic.
+- The old explicit `renderingMode` config option has been removed and full orchestration is always active.

package/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.