@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.21

package/CHANGELOG.md

@@ -8,82 +8,44 @@ 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`).
+- 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.
 
 ### 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 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.
 
-### 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.
 
 ---
 
 ## 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,230 @@
-# 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[Runtime specifier registry]
+	B --> H[Host module loader boundary]
+	H --> I[PageModuleImportService]
+	E --> I
+	E --> J[BrowserBundleService]
+	I --> K[Runtime app adapter]
+	K --> L[Bun adapter or Node adapter]
+	D --> J
+```
+
+### 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
+```
+
+_(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;
 ```
 
-## Portable imports first
+### 2. Application Entry (`app.ts`)
 
-Use the root package exports for normal Ecopages authoring:
+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:
+
+```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/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`