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

package/src/react-renderer.d.ts

@@ -2,20 +2,23 @@
  * This module contains the React renderer
  * @module
  */
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentConfig, 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';
-import type { CompileOptions } from '@mdx-js/mdx';
-import type { ReactRouterAdapter } from './router-adapter.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import { IntegrationRenderer, type HtmlDocumentContribution, type HtmlDocumentContributionContext, type PageBrowserGraphContributionContext, type RenderToResponseContext, type RouteModuleLoadOptions } from '@ecopages/core/route-renderer/integration-renderer';
+import type { AssetDefinition, ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
+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';
-type ReactPageModule = EcoPageFile<{
-    config?: EcoComponentConfig;
-}> & {
-    config?: EcoComponentConfig;
+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.
@@ -37,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.
@@ -77,14 +80,7 @@ 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 marker consistently.
-     */
-    private buildRouterPageDataScript;
+    private getComponentRequires;
     private getRouterDocumentAttributes;
     /**
      * Commits a framework-agnostic component to React semantics.
@@ -103,27 +99,13 @@ 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.
      */
     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 +115,69 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      */
     private renderNonReactShellComponent;
     /**
-     * Produces the page body before the final HTML template is applied.
+     * Renders one React component while preserving already-resolved child HTML.
+     *
+     * When nested foreign-subtree resolution has already produced child HTML for this
+     * component, 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.
+     *
+     * @param input Component render input for the current render step.
+     * @param context React-specific render context for stable token generation.
+     * @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 foreign-subtree 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-subtree tokens are handled.
+     */
+    private restoreRuntimeChildHtml;
+    /**
+     * Renders queued child content through React and then resolves nested foreign-subtree tokens.
      *
-     * 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.
+     * This path is only used for children that were deferred while React rendered the
+     * parent component. It first restores any raw child HTML placeholders owned by the
+     * current runtime context, then asks the shared queued foreign-subtree resolver to swap
+     * foreign integration tokens with their resolved HTML.
      */
-    private composePageContent;
+    private renderQueuedChildrenToHtml;
     /**
-     * Wraps composed page content in the final document template.
+     * Resolves queued renderer-owned foreign-subtree tokens produced during React component rendering.
      *
-     * 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.
+     * React components can enqueue nested foreign subtrees 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 renderDocument;
+    private resolveQueuedForeignSubtreeHtml;
+    private buildHydrationProps;
+    /**
+     * Builds shared document html contributions for router-backed React pages rendered
+     * through a non-React HTML shell.
+     */
+    private buildNonReactDocumentContributions;
+    /**
+     * Renders a foreign integration component that participates in React composition.
+     *
+     * Non-React components must resolve to serialized HTML so React can embed them as
+     * mixed-shell children. Any component-owned dependencies still need to flow
+     * through the shared dependency resolver before queued foreign-subtree tokens are finalized.
+     */
+    private renderForeignComponentWithSerializedHtml;
+    /**
+     * Renders a React-owned component and attaches island hydration metadata when possible.
+     *
+     * This path keeps React-owned SSR, queued foreign-subtree resolution, and optional
+     * island hydration wiring together so the public `renderComponent()` method can
+     * read as orchestration rather than implementation detail.
+     */
+    private renderReactManagedComponent;
     /**
      * Renders a React component for component-level orchestration.
      *
@@ -156,35 +186,30 @@ 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 foreign subtree 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 createForeignChildRuntime(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): import("@ecopages/core").ForeignChildRuntime;
     /**
      * 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;
-    /**
-     * 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[]>;
-    /**
-     * 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>;
+    protected usesIntegrationPageImporter(file: string): boolean;
+    protected importIntegrationPageFile(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
+    protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(file: string, pageModule: TPageModule): TPageModule;
+    protected collectPageBrowserGraphContribution(context: PageBrowserGraphContributionContext): Promise<{
+        dependencies?: AssetDefinition[];
+        assets?: ProcessedAsset[];
+    }>;
     /**
      * Renders a full route response for the filesystem page pipeline.
      *
@@ -194,24 +219,8 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * React shell tree, and hand the result back as a document body.
      */
     render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody>;
+    protected getHtmlDocumentContributions(options: HtmlDocumentContributionContext<ReactNode>): HtmlDocumentContribution[] | undefined;
     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.
      *
@@ -222,4 +231,3 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      */
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }
-export {};