@ecopages/react 0.2.0-alpha.9 → 0.2.1-beta.0

package/README.md

@@ -5,7 +5,8 @@ First-class integration for [React 19](https://react.dev/) in Ecopages. This plu
 ## Installation
 
 ```bash
-bunx jsr add @ecopages/react
+bun add @ecopages/react react react-dom
+bun add -d @types/react @types/react-dom
 ```
 
 ## Usage
@@ -26,15 +27,15 @@ export default config;
 
 ## Component-Level Islands
 
-By default, Ecopages React acts in island mode:
+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 client bootstrap mounts the component via `createRoot()` strictly within that root boundary.
+- 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() })`.
+> 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
 
@@ -60,6 +61,22 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
+## Mixed Rendering
+
+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**.
@@ -99,7 +116,7 @@ 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.
+- Router runtime state needed by [@ecopages/react-router](../../react-router/README.md) when SPA mode is enabled.
 
 The client bundle removes or excludes:
 
@@ -114,7 +131,7 @@ Important:
 
 ### 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:
+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.
@@ -149,7 +166,7 @@ The fix is to strip server-only `eco.page(...)` options after import pruning, wh
 
 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.
+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:
 
@@ -174,8 +191,8 @@ 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)
+- 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.
 
@@ -183,9 +200,9 @@ If the page render receives `locals` on the server and the layout also depends o
 
 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.
+- [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.
 
 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.9",
+  "version": "0.2.1-beta.0",
   "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"
     },
@@ -27,10 +31,18 @@
       "types": "./src/utils/client-only.d.ts",
       "default": "./src/utils/client-only.js"
     },
+    "./runtime/use-sync-external-store-with-selector": {
+      "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
+      "default": "./src/runtime/use-sync-external-store-with-selector.js"
+    },
     "./router-adapter": {
       "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"
     },
@@ -42,6 +54,10 @@
       "types": "./src/utils/client-only.d.ts",
       "default": "./src/utils/client-only.js"
     },
+    "./runtime/use-sync-external-store-with-selector.ts": {
+      "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
+      "default": "./src/runtime/use-sync-external-store-with-selector.js"
+    },
     "./router-adapter.ts": {
       "types": "./src/router-adapter.d.ts",
       "default": "./src/router-adapter.js"
@@ -53,24 +69,19 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.9",
+    "@ecopages/core": "0.2.1-beta.0",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.9",
-    "@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.1-beta.0",
+    "@ecopages/logger": "^0.2.3",
+    "@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,28 @@
  *
  * @module
  */
-import { HmrStrategy, HmrStrategyType, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
 import type { DefaultHmrContext } from '@ecopages/core';
 import type { CompileOptions } from '@mdx-js/mdx';
+import { ClientGraphBoundaryCache } from './utils/client-graph-boundary-cache.js';
 import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+export interface ReactHmrStrategyOptions {
+    context: DefaultHmrContext;
+    pageMetadataCache: ReactHmrPageMetadataCache;
+    runtimeManifest: BrowserRuntimeManifest;
+    mdxCompilerOptions?: CompileOptions;
+    ownedTemplateExtensions?: string[];
+    allTemplateExtensions?: string[];
+    explicitGraphEnabled?: boolean;
+    /**
+     * Per-app cache for client-graph-boundary transform results. Owned by
+     * the React plugin for the app's lifetime. When omitted, the strategy
+     * uses a fresh in-memory cache that does not persist across HMR
+     * rebuilds.
+     */
+    clientGraphBoundaryCache?: ClientGraphBoundaryCache;
+}
 /**
  * Strategy for handling React component HMR updates.
  *
@@ -39,17 +57,20 @@ 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,
+ *   runtimeManifest
+ * });
  * ```
  */
 export declare class ReactHmrStrategy extends HmrStrategy {
-    readonly type = HmrStrategyType.INTEGRATION;
+    readonly type: 100;
     private mdxCompilerOptions?;
     private readonly ownedTemplateExtensions;
     private readonly allTemplateExtensions;
@@ -57,25 +78,24 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     /**
      * 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.
      */
     private context;
     private pageMetadataCache;
     private explicitGraphEnabled;
-    constructor(context: DefaultHmrContext, pageMetadataCache: ReactHmrPageMetadataCache, mdxCompilerOptions?: CompileOptions, ownedTemplateExtensions?: string[], allTemplateExtensions?: string[], explicitGraphEnabled?: boolean);
+    private readonly runtimeManifest;
+    private readonly clientGraphBoundaryCache;
+    private readonly pagesIndex;
+    constructor(options: ReactHmrStrategyOptions);
     /**
      * Returns build plugins for React HMR bundling.
      *
      * Includes the client graph boundary plugin to prevent undeclared imports
      * (including `node:*`) from breaking the browser bundle.
+     *
+     * @remarks
+     * HMR builds receive the React runtime manifest and rewrite manifest-owned
+     * runtime imports to concrete asset URLs before module resolution.
      */
     private getBuildPlugins;
     private isReactEntrypoint;
@@ -89,11 +109,22 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      */
     private isRouteTemplate;
     private resolveTemplateExtension;
+    private ownsWatchedEntrypoint;
+    private configContainsFile;
+    private pageModuleRequiresLayoutRefresh;
+    private hasLayoutOwnedDependencyTarget;
     /**
      * Determines if the file is a React/MDX entrypoint that's registered for HMR.
      *
+     * Uses a three-way decision strategy for selective invalidation:
+     * 1. If the file is a watched entrypoint, check if React owns it
+     * 2. If the file is a dependency of watched entrypoints (via dependency graph),
+     *    check if any affected entrypoints are React-owned. Returns false if hits
+     *    exist but none are owned (prevents unnecessary rebuilds).
+     * 3. Otherwise, check if the file itself is a React entrypoint template
+     *
      * @param filePath - Absolute path to the changed file
-     * @returns True if this is a registered React or MDX entrypoint
+     * @returns True if this file should trigger React HMR rebuilds
      */
     matches(filePath: string): boolean;
     /**
@@ -108,13 +139,33 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      * @returns True if the file is in the layouts directory
      */
     private isLayoutFile;
+    private isPageEntrypoint;
+    private getEntrypointOutput;
+    private getRolldownEntryKey;
+    private getTempFileBasename;
+    private collectReactPageBuildTargets;
+    /**
+     * Expands one HMR request into the full React page build cohort when needed.
+     *
+     * @remarks
+     * Page and layout changes need one shared rebuild pass so sibling routes keep
+     * a consistent client module graph. Non-page changes that do not touch a page
+     * cohort can stay scoped to the originally requested targets.
+     */
+    private resolveBuildTargets;
+    private partitionBuildTargets;
     /**
-     * Processes a React file change by rebuilding all React entrypoints.
+     * Processes a React file change by rebuilding affected React entrypoints.
+     *
+     * Uses a three-way decision strategy for selective invalidation:
+     * 1. Changed file is a watched entrypoint: rebuild only that entrypoint
+     * 2. Dependency graph has hits: rebuild only affected React-owned entrypoints.
+     *    If hits exist but none map to React-owned entrypoints, return 'none' to
+     *    prevent unnecessary rebuilds.
+     * 3. Dependency graph miss: fall back to rebuilding all watched entrypoints
      *
      * For layout files, broadcasts a 'layout-update' event to trigger full page reload.
      * For regular components/pages, broadcasts 'update' events for module-level HMR.
-     * When a page entrypoint is first registered, only that entrypoint is built.
-     * Subsequent file updates rebuild all watched React entrypoints as usual.
      *
      * @param _filePath - Absolute path to the changed file
      * @returns Action to broadcast update events (layout-update for layouts, update for components)
@@ -123,16 +174,49 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     /**
      * Bundles a single React/MDX entrypoint with HMR support.
      *
+     * After successful bundling, populates the entrypoint dependency graph with
+     * the build's dependency metadata. This enables selective invalidation on
+     * subsequent file changes, so only entrypoints affected by a changed
+     * dependency are rebuilt.
+     *
      * @param entrypointPath - Absolute path to the source file
      * @param outputUrl - URL path for the bundled file
      * @returns True if bundling was successful
      */
     private bundleReactEntrypoint;
+    /**
+     * Bundles multiple React/MDX entrypoints in a single build pass.
+     *
+     * Uses code splitting to share common dependencies across entrypoints.
+     * After successful bundling, populates the entrypoint dependency graph with
+     * the build's dependency metadata for selective invalidation.
+     *
+     * @param entrypoints - Array of entrypoint paths and their output URLs
+     * @returns Array of output URLs that were successfully built
+     */
+    private bundleReactEntrypoints;
+    private resolveTempOutputPath;
+    /**
+     * Clears stale HMR output from a directory before a rebuild.
+     *
+     * Only removes:
+     * - `*.tmp.js` files (the per-build bundler output the strategy owns)
+     * - the `chunks/` subdirectory (the bundler's splitting target)
+     *
+     * The HMR runtime script (`_hmr_runtime.js`) and any user-authored
+     * assets in the outdir are preserved. This is the minimal set of
+     * files that, if left from a previous build, can cause the bundler
+     * to emit `ENOENT` for chunk references that point to entrypoints
+     * whose hash has since changed.
+     */
+    private clearHmrOutdir;
     /**
      * Encodes dynamic route segments (brackets) in file paths.
      * Converts `[slug]` to `_slug_` to avoid filesystem issues.
      */
     private encodeDynamicSegments;
+    private rewriteChunkImportUrls;
+    private isMissingTempOutputError;
     /**
      * Processes bundled output and injects the React HMR handler.
      * Writes to temp file first, then renames atomically to avoid conflicts.