@ecopages/react 0.2.0-alpha.14 → 0.2.0-alpha.15

package/CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to `@ecopages/react` are documented here.
 ### Bug Fixes
 
 - Fixed React hydration, Fast Refresh, module loading, doctype handling, island asset reuse, and mixed-renderer boundary resolution across Bun, Vite, and Nitro flows.
+- Restored direct `ReactPlugin` construction so the exported class still accepts the public plugin options shape.
 
 ### Features
 
@@ -17,6 +18,16 @@ All notable changes to `@ecopages/react` are documented here.
 ### Refactoring
 
 - 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.
+
+### Tests
+
+- 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.
 
 ### Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react",
-  "version": "0.2.0-alpha.14",
+  "version": "0.2.0-alpha.15",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -53,14 +53,14 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.14",
+    "@ecopages/core": "0.2.0-alpha.15",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.14",
+    "@ecopages/file-system": "0.2.0-alpha.15",
     "@ecopages/logger": "^0.2.3",
     "@mdx-js/esbuild": "^3.0.1",
     "@mdx-js/mdx": "^3.1.0",

package/src/react-renderer.d.ts

@@ -3,15 +3,23 @@
  * @module
  */
 import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
-import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
+import { IntegrationRenderer, type RenderToResponseContext, type RouteModuleLoadOptions } from '@ecopages/core/route-renderer/integration-renderer';
 import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
-import { type ReactNode } from 'react';
-import type { CompileOptions } from '@mdx-js/mdx';
-import type { ReactRouterAdapter } from './router-adapter.js';
+import type { ReactNode } from 'react';
+import type { ReactRendererConfig } from './react.types.js';
 import { ReactBundleService } from './services/react-bundle.service.js';
-import { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+import { ReactMdxConfigDependencyService } from './services/react-mdx-config-dependency.service.js';
 import { ReactPageModuleService } from './services/react-page-module.service.js';
+import { ReactPagePayloadService } from './services/react-page-payload.service.js';
 import { ReactHydrationAssetService } from './services/react-hydration-asset.service.js';
+export type { ReactRendererConfig } from './react.types.js';
+type ReactRuntimeModules = {
+    react: Pick<typeof import('react'), 'createElement' | 'Fragment'>;
+    reactDomServer: Pick<typeof import('react-dom/server'), 'renderToReadableStream' | 'renderToString'>;
+};
+export type ReactRendererOptions = ConstructorParameters<typeof IntegrationRenderer>[0] & {
+    reactConfig?: ReactRendererConfig;
+};
 /**
  * Error thrown when an error occurs while rendering a React component.
  */
@@ -32,29 +40,29 @@ export declare class BundleError extends Error {
 export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
     name: string;
     componentDirectory: string;
-    static routerAdapter: ReactRouterAdapter | undefined;
-    static mdxCompilerOptions: CompileOptions | undefined;
-    static mdxExtensions: string[];
-    static hmrPageMetadataCache: ReactHmrPageMetadataCache | undefined;
+    private reactRuntimeModules?;
+    private readonly routerAdapter?;
+    private readonly mdxCompilerOptions?;
+    private readonly mdxExtensions;
+    private readonly hmrPageMetadataCache?;
     /**
      * Enables explicit graph behavior for React page-entry bundling.
      *
      * When true, page-entry bundles disable AST server-only stripping and rely
      * on explicit dependency declarations for browser graph composition.
      */
-    static explicitGraphEnabled: boolean;
+    private readonly explicitGraphEnabled;
     /** @internal */
     readonly bundleService: ReactBundleService;
     /** @internal */
     readonly pageModuleService: ReactPageModuleService;
     /** @internal */
     readonly hydrationAssetService: ReactHydrationAssetService;
-    constructor(options: {
-        appConfig: ConstructorParameters<typeof IntegrationRenderer>[0]['appConfig'];
-        assetProcessingService: ConstructorParameters<typeof IntegrationRenderer>[0]['assetProcessingService'];
-        resolvedIntegrationDependencies?: ProcessedAsset[];
-        runtimeOrigin: string;
-    });
+    /** @internal */
+    readonly pagePayloadService: ReactPagePayloadService;
+    /** @internal */
+    readonly mdxConfigDependencyService: ReactMdxConfigDependencyService;
+    constructor(options: ReactRendererOptions);
     protected shouldRenderPageComponent(): boolean;
     /**
      * Reads the declared integration name for a component or layout.
@@ -72,14 +80,6 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * already selected the React integration.
      */
     private isReactManagedComponent;
-    /**
-     * Creates the canonical page-props payload used by router hydration.
-     *
-     * 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 shared document payload consistently.
-     */
-    private buildRouterPageDataScript;
     private getRouterDocumentAttributes;
     /**
      * Commits a framework-agnostic component to React semantics.
@@ -98,14 +98,8 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * by React, we call it directly and require serialized HTML back.
      */
     private asNonReactShellComponent;
-    /**
-     * Builds the serialized page-props payload embedded into the final HTML.
-     *
-     * The document payload is intentionally narrower than the full server render
-     * input: only routing data, public page props, and explicitly allowed locals are
-     * exposed to the browser.
-     */
-    private buildSerializedPageProps;
+    protected resolveReactRuntimeModules(): ReactRuntimeModules;
+    private getReactRuntimeModules;
     /**
      * Appends route hydration assets for a concrete page/view file to the current
      * HTML transformer state.
@@ -133,10 +127,58 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * @returns Serialized component HTML with resolved child markup preserved.
      */
     private renderComponentHtml;
+    /**
+     * Restores raw child HTML that was temporarily replaced by a token during React SSR.
+     *
+     * Queued boundary resolution may render children through a fragment path before all
+     * nested integration tokens are resolved. When that happens, React must never see
+     * the resolved child HTML as a normal string child or it would escape it. The
+     * runtime context stores the placeholder token and the raw child HTML so the
+     * fragment render path can reinsert it before foreign boundary tokens are handled.
+     */
     private restoreRuntimeChildHtml;
+    /**
+     * Renders queued child content through React and then resolves nested boundary tokens.
+     *
+     * This path is only used for children that were deferred while React rendered the
+     * parent boundary. It first restores any raw child HTML placeholders owned by the
+     * current runtime context, then asks the shared queued-boundary resolver to swap
+     * foreign integration tokens with their resolved HTML.
+     */
     private renderQueuedChildrenToHtml;
+    /**
+     * Resolves queued renderer-owned boundary tokens produced during React component rendering.
+     *
+     * React components can enqueue nested boundaries while the parent HTML is being
+     * rendered. This delegates to the shared renderer-owned queue resolver but keeps
+     * the React-specific child rendering behavior local so raw child HTML and React's
+     * fragment rendering semantics stay coordinated.
+     */
     private resolveQueuedBoundaryHtml;
     private buildHydrationProps;
+    /**
+     * Builds the extra document props needed when React renders through a non-React HTML shell.
+     *
+     * Router-backed React pages still need to publish the canonical page-data script
+     * even when the outer document shell belongs to another integration.
+     */
+    private buildNonReactDocumentProps;
+    /**
+     * Renders a foreign integration component boundary that participates in React composition.
+     *
+     * Non-React components must resolve to serialized HTML so React can embed them as
+     * mixed-shell boundaries. Any component-owned dependencies still need to flow
+     * through the shared dependency resolver before queued boundary tokens are finalized.
+     */
+    private renderForeignComponentBoundary;
+    /**
+     * Renders a React-owned component boundary and attaches island hydration metadata when possible.
+     *
+     * This path keeps React-owned SSR, queued boundary resolution, and optional
+     * island hydration wiring together so the public `renderComponent()` method can
+     * read as orchestration rather than implementation detail.
+     */
+    private renderReactComponentBoundary;
     /**
      * Renders a React component for component-level orchestration.
      *
@@ -163,16 +205,8 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      */
     isMdxFile(filePath: string): boolean;
     protected usesIntegrationPageImporter(file: string): boolean;
-    protected importIntegrationPageFile(file: string): Promise<EcoPageFile>;
+    protected importIntegrationPageFile(file: string, options?: RouteModuleLoadOptions): 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
-     * @returns Processed assets for MDX configuration dependencies
-     */
-    private processMdxConfigDependencies;
-    private processDeclaredMdxSsrLazyDependencies;
-    private collectDeclaredMdxSsrLazyDependencies;
     buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
     /**
      * Renders a full route response for the filesystem page pipeline.
@@ -184,23 +218,6 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      */
     render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody>;
     protected getDocumentAttributes(): Record<string, string> | undefined;
-    /**
-     * Safely extracts the declared subset of locals for client-side hydration.
-     *
-     * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
-     * request-scoped data (e.g., session). Only keys explicitly declared via
-     * `Page.requires` are serialized to the client so sensitive request-only data
-     * is not leaked into hydration payloads by default.
-     *
-     * On static pages, `locals` is a Proxy that throws `LocalsAccessError` on access
-     * to prevent accidental use. This method safely detects that case and returns
-     * `undefined` instead of throwing.
-     *
-     * @param locals - The locals object from the render context
-     * @param requiredLocals - Keys explicitly requested for client hydration
-     * @returns The filtered locals object if serializable, undefined otherwise
-     */
-    private getSerializableLocals;
     /**
      * Renders an arbitrary React view through the application's HTML shell.
      *