@ecopages/react 0.2.0-alpha.3 → 0.2.0-alpha.31

package/CHANGELOG.md

@@ -6,57 +6,45 @@ All notable changes to `@ecopages/react` are documented here.
 
 ## [UNRELEASED] — TBD
 
-### Features
-
-#### Render Reachability Analysis
-
-- **Client render graph (Phase 1)** — Introduces a static reachability analysis step that builds an explicit graph of which components are rendered client-side (`cdfbd69e`).
-- **OXC-powered reachability analyzer** — `reachability-analyzer.ts` uses OXC to parse and walk component ASTs, building a `ClientRenderGraph` that maps exported components to their client-side reach (`5412df6b`).
-- **Explicit client graph boundaries** — Components must now declare explicit boundaries; the analyser enforces these to prevent over-hydration (`2912d6bd`).
-- **Declared modules utility** — `declared-modules.ts` tracks which modules are declared as client boundaries.
-
-#### Service Architecture Refactor
-
-- **`ReactRuntimeBundleService`** — Manages runtime assets and specifier mapping for the React integration (`cfd3cb05`).
-- **`ReactHydrationAssetService`** — Creates and manages hydration assets for client-side rendering (`cfd3cb05`).
-- **`ReactBundleService`** — Handles esbuild bundle configuration for React components (`cfd3cb05`).
-- **`ReactPageModuleService`** — Loads and compiles MDX/TSX page modules, including config resolution (`cfd3cb05`).
-- The integration no longer builds a monolithic renderer — each concern is handled by a focused service.
-
-#### HMR Improvements
+### Bug Fixes
 
-- **HMR page metadata caching** — Page metadata is now cached between HMR refreshes, preventing unnecessary re-fetches during Fast Refresh (`a663788c`).
-- **Stale temp module race fix** — HMR no longer incorrectly reads a stale temporary module during rapid refresh cycles (`b2cf8466`).
-- **Client graph HMR stability** — HMR reloads now correctly respect client graph boundaries to avoid partial hydration mismatches (`2912d6bd`).
+- Fixed router-managed React HMR page entries to reload the active route with a cleared persisted-layout cache so shared layout edits apply while the current page stays mounted.
+- Fixed router-managed React HMR handlers to forward the active page HMR entry when reloading the current route through React Router.
+- Fixed production React route hydration bundles to inline React runtime dependencies and import the router through the emitted page browser graph instead of a published import-map key.
+- Removed the redundant React page props bootstrap script so route hydration relies on the canonical `__ECO_PAGE_DATA__` payload.
+- Fixed React hydration, Fast Refresh, module loading, doctype handling, island asset reuse, and mixed-renderer foreign-subtree resolution across Bun, Vite, and Nitro flows.
+- Restored direct `ReactPlugin` construction so the exported class still accepts the public plugin options shape.
+- Fixed React foreign-subtree payload compatibility coverage and removed the plugin/renderer integration-name import cycle.
 
-#### HTML Boundary Utilities
+### Features
 
-- **`html-boundary.ts`** — New utility that wraps rendered output in explicit boundary markers for the cross-integration boundary rendering policy (`ec1e4d66`).
-- **`hydration-scripts.ts`** — Expanded with new helpers for generating and injecting hydration entry scripts.
+- Added built-in React MDX support and reachability-based hydration analysis for React page bundles.
 
 ### Refactoring
 
-- Aligned React renderer to full orchestration mode — removed legacy rendering path (`fc07bdb0`).
-- Ambient module declarations cleaned up (`5f46ecc5`).
-- Client graph boundaries and runtime dependency wiring corrected (`4b6cd32e`).
-- Updated test suite for esbuild adapter and Node.js runtime compatibility (`31a44458`).
+- Collapsed React route hydration into one page-owned entry module that re-exports the page component and bundles runtime dependencies in production.
+- Removed the router adapter `importMapKey` contract so both development and production route hydration follow the router bundle import path instead of split import-map and bundle-path models.
+- Replaced the positional `ReactHmrStrategy` constructor with an options object so React HMR wiring can evolve without argument-order churn.
+- Renamed the remaining React runtime alias internals away from `specifierMap` terminology now that import-map-era core seams are gone.
+- Consolidated React bundling, hydration, and runtime state behind shared service boundaries and `window.__ECO_PAGES__`.
+- Moved React plugin option/default resolution into the factory and replaced renderer static config with instance-owned runtime wiring.
+- Extracted React page-payload and locals serialization into a dedicated service to keep the renderer focused on orchestration.
+- Centralized recursive React component-config traversal so module discovery and MDX SSR-lazy asset collection no longer reimplement graph walking.
+- Moved MDX config dependency resolution out of the renderer into a dedicated React service.
+- Collected shared React plugin and renderer config types into a dedicated module while keeping renderer-local runtime types close to implementation.
 
-### Bug Fixes
+### Tests
 
-- Inlined the React MDX loader so React apps no longer need to install `@ecopages/mdx` when enabling React MDX support (`unreleased`).
-- Fixed stale temp module race during Fast Refresh cycles (`b2cf8466`).
-- Fixed client graph boundary wiring for runtime dependencies (`4b6cd32e`).
+- Added Vitest browser coverage for the React `dynamic()` utility using React Testing Library.
+- Added browser execution coverage for the generated React hydration bootstrap, including router ownership registration and page-root cleanup.
+- Added renderer-level coverage for the foreign-subtree payload compatibility contract, including non-attachable fragment roots.
 
-### Tests
+### Documentation
 
-- Added `html-boundary.test.ts` covering boundary wrapping utilities.
-- Added `hydration-scripts.test.ts` with hydration script generation coverage.
-- Added `reachability-analyzer.test.ts` (187 lines) covering export declaration reachability.
-- Updated integration tests for esbuild adapter compatibility (`31a44458`).
+- Updated the README to document React-owned mixed boundaries and React MDX setup.
 
 ---
 
 ## Migration Notes
 
-- The React integration now requires explicit client boundary declarations. Components that should be hydrated client-side must be marked at a boundary entry point.
-- The internal service layer (`ReactRuntimeBundleService`, `ReactBundleService`, etc.) is not part of the public API and may change between releases.
+- React MDX support is built in and no longer requires installing `@ecopages/mdx` just to enable React MDX routes.

package/README.md

@@ -1,19 +1,20 @@
-# Ecopages React Integration Plugin
+# @ecopages/react
 
-The `@ecopages/react` package introduces first-class integration with [React](https://reactjs.org/) version 19, enabling developers to leverage React's robust ecosystem and component model within the Ecopages platform. This integration provides a seamless experience for using React components in your Ecopages projects, combining React's declarative UI library with the flexibility and simplicity of Ecopages.
+First-class integration for [React 19](https://react.dev/) in Ecopages. This plugin enables React SSR and client hydration, allowing you to build component-level React islands or full React Single Page Applications (SPAs).
 
-## Install
+## Installation
 
 ```bash
-bunx jsr add @ecopages/react
+bun add @ecopages/react react react-dom
+bun add -d @types/react @types/react-dom
 ```
 
 ## Usage
 
-To incorporate the React integration into your Ecopages project, configure your project as follows:
+Configure the plugin in your `eco.config.ts`:
 
 ```ts
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { reactPlugin } from '@ecopages/react';
 
 const config = await new ConfigBuilder()
@@ -24,16 +25,27 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
+## Component-Level Islands
+
+For component-level islands, Ecopages React uses this contract:
+
+- SSR output preserves the authored DOM structure (no unnecessary wrapper elements).
+- A stable `data-eco-component-id` attribute is attached to the component SSR root.
+- The island runtime replaces the SSR host with a dedicated client-owned container and mounts it with `createRoot()`. Full-page hydration paths use `hydrateRoot()`.
+
+> [!TIP]
+> **Full React SPA Routing:**
+> If you are building full React pages and want client-side navigation (SPA), use [@ecopages/react-router](../../react-router/README.md) and pass it to the react plugin: `reactPlugin({ router: ecoRouter() })`.
+
 ## MDX Support
 
-The React plugin includes optional MDX support. When enabled, you can write `.mdx` pages alongside `.tsx` pages with unified client-side routing, hydration, and HMR.
+The React plugin includes built-in MDX support. When enabled, you can write `.mdx` pages alongside `.tsx` pages with unified client-side routing, hydration, and HMR.
 
 ```ts
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { reactPlugin } from '@ecopages/react';
 
 const config = await new ConfigBuilder()
-	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
 	.setIntegrations([
 		reactPlugin({
 			mdx: {
@@ -49,17 +61,148 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-This approach is recommended when using a client-side router (e.g., `@ecopages/react-router`) as it ensures consistent navigation between TSX and MDX pages.
+## Mixed Rendering
 
-## Component-Level Islands
+The React integration can participate in mixed-renderer apps in three ways:
+
+- React can own the page or view directly.
+- React can render nested foreign subtrees inside pages owned by another integration.
+- React can render through non-React page, layout, or document shells when those shell components return strings.
+
+When a non-React render pass reaches a React-owned foreign child, Ecopages hands that foreign subtree back to the React renderer. When React renders through a non-React shell, that shell must serialize to HTML so React can insert the result into the final response without escaping it.
+
+Important:
+
+- Components that may render foreign children must declare those children in `config.dependencies.components`.
+- Ecopages validates mixed-renderer ownership from declared dependencies during render preparation. It does not infer every foreign subtree from rendered HTML alone.
+- React still keeps its own child transport and hydration rules for React-owned subtrees.
+
+## Server and Client Graph Contract
+
+The React integration supports Node.js modules and server-only code **only on the server execution graph**.
+
+- Server rendering can safely import `node:*` modules, database clients, filesystem utilities, etc.
+- Client-hydrated React code must resolve to browser-safe modules only.
+- If a server-only import crosses the boundary and becomes reachable by client code, **the client build will intentionally fail**.
+
+Keep server helpers close, but separate them physically or logically so they do not leak into the client bundle.
+
+## Client Graph Boundary Architecture
+
+This section explains the internal contract used to keep the browser bundle minimal while preventing server-only code and request-only configuration from leaking into client output.
+
+### Goal
+
+The React integration has two jobs that must hold at the same time:
+
+- Produce a browser-safe bundle for hydrated pages and islands.
+- Preserve enough page code for hydration to reconstruct the same React tree the server rendered.
+
+That means the client bundle must keep client-safe render logic, but it must drop server-only imports and server-only `eco.page(...)` options such as middleware and build-time metadata.
+
+### Mental Model
+
+Think about each React page as two related graphs:
+
+1. **Server graph**: everything needed to render the page on the server. This graph may include middleware, request locals, database access, filesystem access, and other server-only modules.
+2. **Client graph**: the smallest browser-safe subset needed to hydrate the rendered output in the browser.
+
+The React integration builds the client graph conservatively. If a server-only module becomes reachable from the hydrated render path, the build should fail rather than silently shipping unsafe code.
+
+### What Stays and What Goes
+
+The client bundle keeps:
+
+- The page component render path.
+- Client-safe component dependencies reachable from render.
+- Layout wiring needed for hydration.
+- Router runtime state needed by [@ecopages/react-router](../../react-router/README.md) when SPA mode is enabled.
+
+The client bundle removes or excludes:
+
+- Server-only imports that are not reachable from the hydrated render path.
+- Server-only `eco.page(...)` options such as `cache`, `middleware`, `metadata`, `staticProps`, and `staticPaths`.
+- Request-time configuration that has no meaning in the browser.
+
+Important:
+
+- `render` must stay in the client bundle, because hydration needs it to reconstruct the page tree.
+- `requires` does **not** stay in the browser page config. It is used on the server to decide which `locals` keys may be serialized into the hydration payload.
+
+### AST Pipeline Order
+
+The browser-bound transform in [src/utils/client-graph-boundary-plugin.ts](src/utils/client-graph-boundary-plugin.ts) follows this order:
+
+1. Parse the module and build a reachability view of the client render graph.
+2. Remove imports that are not allowed or not reachable from the client graph.
+3. Reparse the transformed source.
+4. Strip server-only `eco.page(...)` object properties from the reparsed AST.
+5. Return the rewritten source to the bundle step.
+
+The reparse step is important. Once import edits change source offsets, the original AST locations are stale. Reusing them for later edits can corrupt the output or remove the wrong code.
+
+### Why `eco.page(...)` Options Are Stripped
+
+Import pruning alone is not enough.
+
+Consider a page like this:
+
+```tsx
+import { authMiddleware } from './auth.server';
+
+export default eco.page({
+	cache: 'dynamic',
+	middleware: [authMiddleware],
+	requires: ['session'] as const,
+	render: () => <div>Dashboard</div>,
+});
+```
+
+If the client transform removes the `auth.server` import but leaves `middleware: [authMiddleware]` in place, the browser bundle still contains a dangling identifier. That breaks production hydration even though the import was removed correctly.
+
+The fix is to strip server-only `eco.page(...)` options after import pruning, while keeping `render` intact.
+
+### Hydration Contract for `locals`
+
+The browser must not receive arbitrary request-scoped data.
+
+The React renderer in [src/react-renderer.ts](src/react-renderer.ts) serializes only the top-level `locals` keys explicitly declared by `Page.requires`. If a page does not declare `requires`, no `locals` are serialized for hydration.
+
+Example:
+
+```tsx
+export default eco.page({
+	requires: ['session'] as const,
+	render: ({ locals }) => <Dashboard user={locals?.session?.user} />,
+});
+```
+
+In this case, the hydration payload may include `locals.session`, but it will exclude unrelated request-only keys.
+
+Important:
+
+- This filtering is currently top-level only.
+- If `locals.session` itself contains sensitive nested fields, those fields will still be serialized.
+- Middleware should therefore expose a client-safe shape for any key declared in `requires`.
+
+### Layout Hydration Invariant
+
+Hydration must rebuild the same tree the server rendered.
+
+That applies to both:
+
+- non-router hydration scripts in [src/utils/hydration-scripts.ts](src/utils/hydration-scripts.ts)
+- router-backed hydration in [../../react-router/src/router.ts](../../react-router/src/router.ts)
+
+If the page render receives `locals` on the server and the layout also depends on those values, the client must pass the same serialized `locals` into the layout during hydration. Otherwise React will detect a mismatch.
 
-Current behavior:
+### Tests That Guard This Contract
 
-- SSR output keeps the authored component DOM structure (no synthetic wrapper element).
-- A stable `data-eco-component-id` attribute is attached to the component SSR root when a single root element is available.
-- Client bootstrap resolves the component export and mounts with `createRoot()` into that root boundary.
-- Component assets are emitted through the shared dependency pipeline and deduplicated with other integrations.
+The main regression coverage lives in:
 
-This design preserves global CSS/layout selectors while keeping runtime ownership isolated per island instance.
+- [src/utils/client-graph-boundary-plugin.test.ts](src/utils/client-graph-boundary-plugin.test.ts): verifies server-only `eco.page(...)` options are stripped from browser bundles.
+- [src/react-renderer.locals.test.ts](src/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
+- [src/utils/hydration-scripts.test.ts](src/utils/hydration-scripts.test.ts): verifies non-router hydration passes serialized `locals` into layouts.
+- [../../react-router/test/hmr-reload.test.browser.ts](../../react-router/test/hmr-reload.test.browser.ts): verifies router-backed layout hydration receives `locals` with `persistLayouts` both enabled and disabled.
 
-For full React pages with client-side navigation, prefer [@ecopages/react-router](../react-router/README.md), where routing and hydration are handled by the React-specific runtime.
+If you change the AST transform or hydration flow, update the corresponding tests in the same change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.31",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -53,19 +53,19 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.3",
+    "@ecopages/core": "0.2.0-alpha.31",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.3",
-    "@ecopages/logger": "latest",
+    "@ecopages/file-system": "0.2.0-alpha.31",
+    "@ecopages/logger": "^0.2.3",
     "@mdx-js/esbuild": "^3.0.1",
     "@mdx-js/mdx": "^3.1.0",
-    "oxc-parser": "^0.114.0",
-    "oxc-transform": "^0.114.0",
+    "oxc-parser": "^0.124.0",
+    "oxc-transform": "^0.124.0",
     "source-map": "^0.7.6",
     "vfile": "^6.0.3"
   },

package/src/react-hmr-strategy.d.ts

@@ -6,10 +6,19 @@
  *
  * @module
  */
-import { HmrStrategy, HmrStrategyType, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
 import type { DefaultHmrContext } from '@ecopages/core';
 import type { CompileOptions } from '@mdx-js/mdx';
 import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+export interface ReactHmrStrategyOptions {
+    context: DefaultHmrContext;
+    pageMetadataCache: ReactHmrPageMetadataCache;
+    runtimeAliasMap: ReadonlyMap<string, string>;
+    mdxCompilerOptions?: CompileOptions;
+    ownedTemplateExtensions?: string[];
+    allTemplateExtensions?: string[];
+    explicitGraphEnabled?: boolean;
+}
 /**
  * Strategy for handling React component HMR updates.
  *
@@ -19,9 +28,11 @@ import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metada
  * The processing steps are:
  * 1. Check if any React entrypoints are registered
  * 2. Rebuild all React entrypoints (the changed file could be a dependency)
- * 3. Replace bare specifiers with runtime URLs
- * 4. Inject HMR acceptance handler
- * 5. Broadcast update events for each rebuilt entrypoint
+ * 3. Rebuild browser output through the shared browser bundle service while
+ *    preserving React-specific runtime aliases and graph policy
+ * 4. Read page config metadata through the shared server-module loading path
+ * 5. Inject HMR acceptance handler
+ * 6. Broadcast update events for each rebuilt entrypoint
  *
  * @remarks
  * This strategy has higher priority than generic JsHmrStrategy, allowing it
@@ -37,38 +48,34 @@ import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metada
  * ```typescript
  * const context = {
  *   getWatchedFiles: () => watchedFilesMap,
- *   getSpecifierMap: () => specifierMap,
  *   getDistDir: () => '/path/to/dist/_hmr',
  *   getPlugins: () => [],
  *   getSrcDir: () => '/path/to/src',
  *   getLayoutsDir: () => '/path/to/src/layouts'
  * };
- * const strategy = new ReactHmrStrategy(context);
+ * const strategy = new ReactHmrStrategy({
+ *   context,
+ *   pageMetadataCache,
+ *   runtimeAliasMap
+ * });
  * ```
  */
 export declare class ReactHmrStrategy extends HmrStrategy {
-    private context;
-    private pageMetadataCache;
-    private explicitGraphEnabled;
-    readonly type = HmrStrategyType.INTEGRATION;
+    readonly type: 100;
     private mdxCompilerOptions?;
-    private readonly knownEntrypoints;
+    private readonly ownedTemplateExtensions;
+    private readonly allTemplateExtensions;
     private importNodePageModule;
-    private createUseSyncExternalStoreShimPlugin;
     /**
      * Creates a new React HMR strategy instance.
      *
-     * @param context - The HMR context providing access to watched files, plugins, build directories,
-     *                  and the layouts directory for detecting layout file changes that require full
-     *                  page reloads instead of module-level HMR updates.
-     * @param pageMetadataCache - React-only cache of declared browser modules discovered during
-     *                            server rendering. This avoids re-importing unchanged page modules
-     *                            during save-time Fast Refresh rebuilds.
-     * @param mdxCompilerOptions - Optional MDX compiler options for processing .mdx files
-     * @param explicitGraphEnabled - Enables explicit graph mode for React HMR bundling.
-     * In explicit mode, HMR builds omit AST server-only stripping plugins in React paths.
+     * @param options - React HMR runtime services and behavior flags.
      */
-    constructor(context: DefaultHmrContext, pageMetadataCache: ReactHmrPageMetadataCache, mdxCompilerOptions?: CompileOptions, explicitGraphEnabled?: boolean);
+    private context;
+    private pageMetadataCache;
+    private explicitGraphEnabled;
+    private readonly runtimeAliasMap;
+    constructor(options: ReactHmrStrategyOptions);
     /**
      * Returns build plugins for React HMR bundling.
      *
@@ -77,6 +84,17 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      */
     private getBuildPlugins;
     private isReactEntrypoint;
+    /**
+     * Returns true when a route file uses a compound extension like `page.foo.tsx`.
+     *
+     * @remarks
+     * React integration owns plain `.tsx` route templates. Compound extensions in
+     * pages/layouts are integration-specific route templates and should not be
+     * claimed by React HMR strategy.
+     */
+    private isRouteTemplate;
+    private resolveTemplateExtension;
+    private ownsWatchedEntrypoint;
     /**
      * Determines if the file is a React/MDX entrypoint that's registered for HMR.
      *
@@ -116,13 +134,14 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      * @returns True if bundling was successful
      */
     private bundleReactEntrypoint;
+    private resolveTempOutputPath;
     /**
      * Encodes dynamic route segments (brackets) in file paths.
      * Converts `[slug]` to `_slug_` to avoid filesystem issues.
      */
     private encodeDynamicSegments;
     /**
-     * Processes bundled output by replacing specifiers and injecting HMR handler.
+     * Processes bundled output and injects the React HMR handler.
      * Writes to temp file first, then renames atomically to avoid conflicts.
      *
      * @param tempPath - Path to the temporary bundled file
@@ -131,13 +150,4 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      * @returns True if processing was successful
      */
     private processOutput;
-    /**
-     * Replaces bare specifiers with runtime URLs.
-     *
-     * Handles both static imports and dynamic imports.
-     *
-     * @param code - The bundled code to transform
-     * @returns The transformed code with runtime URLs
-     */
-    private replaceBareSpecifiers;
 }