@ecopages/react 0.2.0-alpha.8 → 0.2.1

package/CHANGELOG.md

@@ -4,24 +4,26 @@ All notable changes to `@ecopages/react` are documented here.
 
 > **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
 
-## [UNRELEASED] — TBD
+## [0.2.1] — 2026-04-16
 
-### Features & Performance
+### Bug Fixes
 
-- **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.
+- Fixed React hydration, Fast Refresh, module loading, doctype handling, island asset reuse, and mixed-renderer boundary resolution across Bun, Vite, and Nitro flows.
 
-### Bug Fixes & Refactoring
+### Features
 
-- **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__`.
+- Added built-in React MDX support and reachability-based hydration analysis for React page bundles.
+
+### Refactoring
+
+- Consolidated React bundling, hydration, and runtime state behind shared service boundaries and `window.__ECO_PAGES__`.
+
+### Documentation
+
+- Updated the README to document React-owned mixed boundaries and React MDX setup.
 
 ---
 
 ## Migration Notes
 
-- 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

@@ -60,6 +60,16 @@ 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 component boundaries 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 enters a React-owned boundary, Ecopages hands that boundary 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.
+
 ## Server and Client Graph Contract
 
 The React integration supports Node.js modules and server-only code **only on the server execution graph**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.1",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -53,19 +53,19 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.8",
+    "@ecopages/core": "0.2.1",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.8",
-    "@ecopages/logger": "latest",
+    "@ecopages/file-system": "0.2.1",
+    "@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,7 +6,7 @@
  *
  * @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';
@@ -49,7 +49,7 @@ import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metada
  * ```
  */
 export declare class ReactHmrStrategy extends HmrStrategy {
-    readonly type = HmrStrategyType.INTEGRATION;
+    readonly type: 100;
     private mdxCompilerOptions?;
     private readonly ownedTemplateExtensions;
     private readonly allTemplateExtensions;
@@ -89,6 +89,7 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      */
     private isRouteTemplate;
     private resolveTemplateExtension;
+    private ownsWatchedEntrypoint;
     /**
      * Determines if the file is a React/MDX entrypoint that's registered for HMR.
      *
@@ -128,6 +129,7 @@ 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.

package/src/react-hmr-strategy.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
+import { rewriteRuntimeSpecifierAliases } from "@ecopages/core/build/runtime-specifier-aliases";
 import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
 import { FileNotFoundError, fileSystem } from "@ecopages/file-system";
 import { Logger } from "@ecopages/logger";
@@ -49,8 +50,9 @@ class ReactHmrStrategy extends HmrStrategy {
    * (including `node:*`) from breaking the browser bundle.
    */
   getBuildPlugins(declaredModules) {
-    const allowSpecifiers = getReactClientGraphAllowSpecifiers(this.context.getSpecifierMap().keys());
-    const runtimeAliasPlugin = createRuntimeSpecifierAliasPlugin(this.context.getSpecifierMap(), {
+    const runtimeSpecifierMap = this.context.getSpecifierMap();
+    const allowSpecifiers = getReactClientGraphAllowSpecifiers(runtimeSpecifierMap.keys());
+    const runtimeAliasPlugin = createRuntimeSpecifierAliasPlugin(runtimeSpecifierMap, {
       name: "react-hmr-runtime-specifier-alias"
     });
     return [
@@ -97,6 +99,9 @@ class ReactHmrStrategy extends HmrStrategy {
   resolveTemplateExtension(filePath) {
     return this.allTemplateExtensions.find((extension) => filePath.endsWith(extension));
   }
+  ownsWatchedEntrypoint(filePath) {
+    return this.pageMetadataCache.ownsEntrypoint(filePath);
+  }
   /**
    * Determines if the file is a React/MDX entrypoint that's registered for HMR.
    *
@@ -109,6 +114,9 @@ class ReactHmrStrategy extends HmrStrategy {
     if (watchedFiles.size === 0) {
       return false;
     }
+    if (watchedFiles.has(filePath)) {
+      return this.ownsWatchedEntrypoint(filePath);
+    }
     return this.isReactEntrypoint(filePath);
   }
   /**
@@ -148,6 +156,10 @@ class ReactHmrStrategy extends HmrStrategy {
       appLogger.debug(`Detected layout file change: ${_filePath}`);
     }
     const changedEntrypointOutput = watchedFiles.get(_filePath);
+    if (changedEntrypointOutput && !this.ownsWatchedEntrypoint(_filePath)) {
+      appLogger.debug(`Skipping non-React watched entrypoint: ${_filePath}`);
+      return { type: "none" };
+    }
     const entrypointsToBuild = changedEntrypointOutput ? [[_filePath, changedEntrypointOutput]] : watchedFiles.entries();
     const updates = [];
     for (const [entrypoint, outputUrl] of entrypointsToBuild) {
@@ -225,13 +237,33 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`No output file generated for ${entrypointPath}`);
         return false;
       }
-      const processed = await this.processOutput(tempFile, outputPath, outputUrl);
+      const resolvedTempFile = await this.resolveTempOutputPath(tempFile);
+      if (!resolvedTempFile) {
+        appLogger.debug(`Skipping stale temp output for ${outputUrl}: ${tempFile}`);
+        return false;
+      }
+      const processed = await this.processOutput(resolvedTempFile, outputPath, outputUrl);
       return processed;
     } catch (error) {
       appLogger.error(`Error bundling ${entrypointPath}:`, error);
       return false;
     }
   }
+  async resolveTempOutputPath(tempPath) {
+    if (fileSystem.exists(tempPath)) {
+      return tempPath;
+    }
+    if (!tempPath.includes("[hash]")) {
+      return tempPath;
+    }
+    const directory = path.dirname(tempPath);
+    const pattern = path.basename(tempPath).replaceAll("[hash]", "*");
+    const matches = await fileSystem.glob([pattern], { cwd: directory });
+    if (matches.length === 0) {
+      return null;
+    }
+    return path.isAbsolute(matches[0]) ? matches[0] : path.join(directory, matches[0]);
+  }
   /**
    * Encodes dynamic route segments (brackets) in file paths.
    * Converts `[slug]` to `_slug_` to avoid filesystem issues.
@@ -255,6 +287,7 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     try {
       let code = await fileSystem.readFile(tempPath);
+      code = rewriteRuntimeSpecifierAliases(code, this.context.getSpecifierMap());
       code = injectHmrHandler(code);
       await fileSystem.writeAsync(finalPath, code);
       await fileSystem.removeAsync(tempPath).catch(() => {

package/src/react-renderer.d.ts

@@ -2,7 +2,7 @@
  * This module contains the React renderer
  * @module
  */
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentConfig, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
 import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
 import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
 import { type ReactNode } from 'react';
@@ -12,11 +12,6 @@ import { ReactBundleService } from './services/react-bundle.service.js';
 import { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
 import { ReactPageModuleService } from './services/react-page-module.service.js';
 import { ReactHydrationAssetService } from './services/react-hydration-asset.service.js';
-type ReactPageModule = EcoPageFile<{
-    config?: EcoComponentConfig;
-}> & {
-    config?: EcoComponentConfig;
-};
 /**
  * Error thrown when an error occurs while rendering a React component.
  */
@@ -82,7 +77,7 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      *
      * React pages embedded in a non-React HTML shell still need to expose the same
      * page-data contract as fully React-owned documents so navigation and hydration
-     * can read one marker consistently.
+     * can read one shared document payload consistently.
      */
     private buildRouterPageDataScript;
     private getRouterDocumentAttributes;
@@ -116,14 +111,6 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * HTML transformer state.
      */
     private appendHydrationAssetsForFile;
-    /**
-     * Resolves metadata for direct `renderToResponse()` calls.
-     *
-     * View rendering bypasses the normal route-file pipeline, so metadata has to be
-     * evaluated here from either the component-level generator or the application
-     * default.
-     */
-    private resolveViewMetadata;
     /**
      * Renders a non-React layout or HTML template and enforces that mixed shells
      * return serialized HTML.
@@ -133,21 +120,23 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      */
     private renderNonReactShellComponent;
     /**
-     * Produces the page body before the final HTML template is applied.
+     * Renders one React component boundary while preserving already-resolved child HTML.
      *
-     * This method owns the React/non-React layout split. React-managed layouts stay
-     * as React elements so they can stream normally; non-React layouts are rendered
-     * to HTML first and then passed through as serialized content.
-     */
-    private composePageContent;
-    /**
-     * Wraps composed page content in the final document template.
+     * When nested boundary resolution has already produced child HTML for this
+     * boundary, the child payload must remain raw SSR output rather than a React
+     * string child, otherwise React would escape it. This helper renders a unique
+     * token through React and swaps that token back to the resolved HTML
+     * afterward.
      *
-     * React-owned HTML templates stream directly. Non-React templates receive
-     * pre-rendered page HTML plus the canonical React page-data payload so the
-     * client runtime can recover page data after cross-integration handoff.
+     * @param input Component render input for the current boundary.
+     * @param context React-specific render context for stable token generation.
+     * @returns Serialized component HTML with resolved child markup preserved.
      */
-    private renderDocument;
+    private renderComponentHtml;
+    private restoreRuntimeChildHtml;
+    private renderQueuedChildrenToHtml;
+    private resolveQueuedBoundaryHtml;
+    private buildHydrationProps;
     /**
      * Renders a React component for component-level orchestration.
      *
@@ -156,17 +145,26 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * - When an explicit component instance id is provided, a stable
      *   `data-eco-component-id` attribute is attached so island hydration can target it.
      * - Without an explicit instance id, component renders remain plain SSR output.
+     * - When resolved child HTML is provided, that boundary is treated as a pure SSR
+     *   composition step and does not emit hydration assets for the parent wrapper.
      *
      * This preserves DOM shape for global CSS/layout selectors while keeping a
      * deterministic mount target per component instance.
      */
     renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    protected createComponentBoundaryRuntime(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): import("@ecopages/core").ComponentBoundaryRuntime;
     /**
      * Checks if the given file path corresponds to an MDX file based on configured extensions.
      * @param filePath - The file path to check
      * @returns True if the file is an MDX file
      */
     isMdxFile(filePath: string): boolean;
+    protected usesIntegrationPageImporter(file: string): boolean;
+    protected importIntegrationPageFile(file: string): Promise<EcoPageFile>;
+    protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(file: string, pageModule: TPageModule): TPageModule;
     /**
      * Processes MDX-specific configuration dependencies including layout dependencies.
      * @param pagePath - Absolute path to the MDX page file
@@ -176,15 +174,6 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
     private processDeclaredMdxSsrLazyDependencies;
     private collectDeclaredMdxSsrLazyDependencies;
     buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
-    /**
-     * Imports a page module while normalizing React MDX modules to the same shape
-     * as ordinary React page files.
-     *
-     * MDX page imports can expose `config` separately from the default export. The
-     * React renderer reattaches that config to the page component so downstream
-     * layout, dependency, and hydration logic can treat MDX and TSX pages the same.
-     */
-    protected importPageFile(file: string): Promise<ReactPageModule>;
     /**
      * Renders a full route response for the filesystem page pipeline.
      *
@@ -222,4 +211,3 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      */
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }
-export {};