@ecopages/react 0.2.0-alpha.4 → 0.2.0-alpha.41

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.4",
+  "version": "0.2.0-alpha.41",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -16,6 +16,10 @@
       "default": "./src/react.plugin.js",
       "types": "./src/react.plugin.d.ts"
     },
+    "./eco-embed": {
+      "default": "./src/eco-embed.js",
+      "types": "./src/eco-embed.d.ts"
+    },
     "./declarations": {
       "types": "./src/declarations.d.ts"
     },
@@ -31,6 +35,10 @@
       "types": "./src/router-adapter.d.ts",
       "default": "./src/router-adapter.js"
     },
+    "./eco-embed.ts": {
+      "default": "./src/eco-embed.js",
+      "types": "./src/eco-embed.d.ts"
+    },
     "./declarations.ts": {
       "types": "./src/declarations.d.ts"
     },
@@ -53,24 +61,20 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.4",
+    "@ecopages/core": "0.2.0-alpha.34",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.4",
-    "@ecopages/logger": "latest",
-    "@mdx-js/esbuild": "^3.0.1",
-    "@mdx-js/mdx": "^3.1.0",
-    "oxc-parser": "^0.114.0",
-    "oxc-transform": "^0.114.0",
+    "@ecopages/file-system": "0.2.0-alpha.34",
+    "@ecopages/logger": "^0.2.3",
+    "@mdx-js/esbuild": "^3.1.1",
+    "@mdx-js/mdx": "^3.1.1",
+    "oxc-parser": "^0.124.0",
+    "oxc-transform": "^0.124.0",
     "source-map": "^0.7.6",
     "vfile": "^6.0.3"
-  },
-  "overrides": {
-    "react": "^19",
-    "react-dom": "^19"
   }
 }

package/src/eco-embed.d.ts

@@ -0,0 +1,11 @@
+import type { EcoComponent, EcoEmbedProps as CoreEcoEmbedProps } from '@ecopages/core';
+import type { ReactNode } from 'react';
+/**
+ * Props for the React-owned `EcoEmbed` adapter.
+ */
+export type EcoEmbedProps<TComponent extends EcoComponent> = CoreEcoEmbedProps<TComponent>;
+/**
+ * Renders a foreign or same-integration eco component from a React JSX file
+ * without forcing inline mixed-JSX authoring.
+ */
+export declare function EcoEmbed<TComponent extends EcoComponent>({ component, props, children, }: EcoEmbedProps<TComponent>): ReactNode;

package/src/eco-embed.js

@@ -0,0 +1,11 @@
+import { eco } from "@ecopages/core";
+function EcoEmbed({
+  component,
+  props,
+  children
+}) {
+  return eco.embed(component, props, children);
+}
+export {
+  EcoEmbed
+};

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;
 }