@ecopages/react 0.2.0-alpha.5 → 0.2.0-alpha.8

package/CHANGELOG.md

@@ -6,62 +6,22 @@ All notable changes to `@ecopages/react` are documented here.
 
 ## [UNRELEASED] — TBD
 
-### Features
+### Features & Performance
 
-#### Render Reachability Analysis
+- **Performance Hydration**: Introduced static reachability analysis to enforce explicit hydration boundaries and optimized HMR via metadata caching.
+- **Service-Oriented Internals**: Refactored the integration into focused core-backed services for bundling, hydration, and page-module loading.
+- **React MDX**: Inlined MDX support directly into the React integration for a zero-config setup, including Node-native compatibility for experimental startup.
 
-- **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.
+### Bug Fixes & Refactoring
 
-#### 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
-
-- **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`).
-
-#### HTML Boundary Utilities
-
-- **`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.
-
-### 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`).
-
-### Bug Fixes
-
-- 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`).
-- Fixed shared React barrel handling so client-reachable server-only re-exports now fail the build instead of being silently pruned (`unreleased`).
-
-### Documentation
-
-- Documented the React integration server/client graph contract for shared modules and barrel exports (`unreleased`).
-
-### Tests
-
-- 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`).
+- **Handoff Stability**: Standardized router-backed page payloads and document owner markers for mixed-router stability during navigation.
+- **Hydration Hardening**: Fixed island remount races, prop collisions, and layout metadata resolution during development and route handoffs.
+- **Architecture**: Centralized runtime specifiers and consolidated browser-side integration state under `window.__ECO_PAGES__`.
 
 ---
 
 ## 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.
+- The React integration now requires explicit client boundary declarations for client-rendered components.
+- React MDX support is built in and no longer requires installing `@ecopages/mdx` just to enable React MDX routes.
+- The internal service layer is not part of the public API and may change between releases.

package/README.md

@@ -1,8 +1,8 @@
-# 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
@@ -10,10 +10,10 @@ bunx jsr add @ecopages/react
 
 ## 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 +24,27 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
+## Component-Level Islands
+
+By default, Ecopages React acts in island mode:
+
+- 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 client bootstrap mounts the component via `createRoot()` strictly within that root boundary.
+
+> [!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,37 +60,132 @@ 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.
+## Server and Client Graph Contract
 
-## Component-Level Islands
+The React integration supports Node.js modules and server-only code **only on the server execution graph**.
 
-Current behavior:
+- 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**.
 
-- 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.
+Keep server helpers close, but separate them physically or logically so they do not leak into the client bundle.
 
-This design preserves global CSS/layout selectors while keeping runtime ownership isolated per island instance.
+## Client Graph Boundary Architecture
 
-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.
+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.
 
-## Server And Client Graph Contract
+### Goal
 
-The React integration supports Node.js modules and server-only code, but only on the server execution graph.
+The React integration has two jobs that must hold at the same time:
 
-- Server rendering can import and execute `node:*` modules, database clients, filesystem utilities, and `*.server.*` modules.
-- Client-hydrated React code must resolve to browser-safe modules only.
-- Shared files and barrel files are allowed when the exports that become client-reachable are browser-safe.
-- If a server-only import becomes client-reachable, the client build fails instead of silently replacing the import.
+- 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.
 
-In practice, this means you can keep server helpers close to your React code, but the browser bundle boundary is strict:
+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.
 
-```ts
-export { Button } from './button';
-export { db } from './db.server';
+### 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 [packages/integrations/react/src/utils/client-graph-boundary-plugin.ts](packages/integrations/react/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 a client entry only reaches `Button`, the `db` re-export is removed from the browser transform. If a client entry reaches `db`, the build fails because the server-only export crossed into the client graph.
+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 [packages/integrations/react/src/react-renderer.ts](packages/integrations/react/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 [packages/integrations/react/src/utils/hydration-scripts.ts](packages/integrations/react/src/utils/hydration-scripts.ts)
+- router-backed hydration in [packages/react-router/src/router.ts](packages/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.
+
+### Tests That Guard This Contract
+
+The main regression coverage lives in:
+
+- [packages/integrations/react/src/utils/client-graph-boundary-plugin.test.ts](packages/integrations/react/src/utils/client-graph-boundary-plugin.test.ts): verifies server-only `eco.page(...)` options are stripped from browser bundles.
+- [packages/integrations/react/src/react-renderer.locals.test.ts](packages/integrations/react/src/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
+- [packages/integrations/react/src/utils/hydration-scripts.test.ts](packages/integrations/react/src/utils/hydration-scripts.test.ts): verifies non-router hydration passes serialized `locals` into layouts.
+- [packages/react-router/test/hmr-reload.test.browser.ts](packages/react-router/test/hmr-reload.test.browser.ts): verifies router-backed layout hydration receives `locals` with `persistLayouts` both enabled and disabled.
 
-This contract keeps SSR and server functions free to use Node.js while ensuring the final browser bundle contains no client-reachable server-only code.
+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.5",
+  "version": "0.2.0-alpha.8",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -53,14 +53,14 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.5",
+    "@ecopages/core": "0.2.0-alpha.8",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.5",
+    "@ecopages/file-system": "0.2.0-alpha.8",
     "@ecopages/logger": "latest",
     "@mdx-js/esbuild": "^3.0.1",
     "@mdx-js/mdx": "^3.1.0",

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

@@ -19,9 +19,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
@@ -47,25 +49,11 @@ import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metada
  * ```
  */
 export declare class ReactHmrStrategy extends HmrStrategy {
-    private context;
-    private pageMetadataCache;
-    private explicitGraphEnabled;
     readonly type = HmrStrategyType.INTEGRATION;
     private mdxCompilerOptions?;
-    private readonly knownEntrypoints;
+    private readonly ownedTemplateExtensions;
+    private readonly allTemplateExtensions;
     private importNodePageModule;
-    /**
-     * Redirects `use-sync-external-store/shim` imports to React's built-in
-     * `useSyncExternalStore`.
-     *
-     * Libraries like React Aria still list `use-sync-external-store` as a
-     * dependency to support React 16/17. On React 18+ the `/shim` export is
-     * already a pass-through, but without this plugin esbuild would bundle
-     * the full CJS shim (including `process.env` branching) into the browser
-     * bundle. The plugin short-circuits the resolution so only a single clean
-     * ESM re-export is emitted.
-     */
-    private createUseSyncExternalStoreShimPlugin;
     /**
      * Creates a new React HMR strategy instance.
      *
@@ -79,7 +67,10 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      * @param explicitGraphEnabled - Enables explicit graph mode for React HMR bundling.
      * In explicit mode, HMR builds omit AST server-only stripping plugins in React paths.
      */
-    constructor(context: DefaultHmrContext, pageMetadataCache: ReactHmrPageMetadataCache, mdxCompilerOptions?: CompileOptions, explicitGraphEnabled?: boolean);
+    private context;
+    private pageMetadataCache;
+    private explicitGraphEnabled;
+    constructor(context: DefaultHmrContext, pageMetadataCache: ReactHmrPageMetadataCache, mdxCompilerOptions?: CompileOptions, ownedTemplateExtensions?: string[], allTemplateExtensions?: string[], explicitGraphEnabled?: boolean);
     /**
      * Returns build plugins for React HMR bundling.
      *
@@ -88,6 +79,16 @@ 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;
     /**
      * Determines if the file is a React/MDX entrypoint that's registered for HMR.
      *
@@ -133,7 +134,7 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      */
     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
@@ -142,13 +143,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;
 }