@ecopages/react 0.2.0-alpha.5 → 0.2.0-alpha.50

package/src/react-renderer.d.ts

@@ -2,16 +2,24 @@
  * 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';
+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,75 +40,194 @@ export declare class BundleError extends Error {
 export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
     name: string;
     componentDirectory: string;
-    private componentRenderSequence;
-    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.
+     *
+     * We honor both the explicit `config.integration` override and injected
+     * `config.__eco.integration` metadata because pages can arrive here through
+     * authored config as well as build-time component metadata.
+     */
+    private getComponentIntegration;
+    /**
+     * Returns whether a component should stay inside the React render lane.
+     *
+     * Components without explicit integration metadata are treated as React-owned
+     * here because this renderer only receives them after the route pipeline has
+     * already selected the React integration.
+     */
+    private isReactManagedComponent;
+    private getComponentRequires;
+    private getRouterDocumentAttributes;
+    /**
+     * Commits a framework-agnostic component to React semantics.
+     *
+     * This is one of the two real cast boundaries in this file. Core keeps
+     * `EcoComponent` broad so integrations can share the same public surface; once
+     * the React renderer is executing, `createElement()` needs a concrete React
+     * component signature.
+     */
+    private asReactComponent;
+    /**
+     * Commits a mixed-shell component to the string-returning contract required by
+     * non-React layouts and HTML templates.
+     *
+     * This is the second real cast boundary: once we decide a shell is not managed
+     * by React, we call it directly and require serialized HTML back.
+     */
+    private asNonReactShellComponent;
+    protected resolveReactRuntimeModules(): ReactRuntimeModules;
+    private getReactRuntimeModules;
+    /**
+     * Appends route hydration assets for a concrete page/view file to the current
+     * HTML transformer state.
+     */
+    private appendHydrationAssetsForFile;
+    /**
+     * Renders a non-React layout or HTML template and enforces that mixed shells
+     * return serialized HTML.
+     *
+     * The React renderer can compose through another integration's shell, but only
+     * if that shell yields a string that can be inserted into the final document.
+     */
+    private renderNonReactShellComponent;
+    /**
+     * 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 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 renderQueuedChildrenToHtml;
+    /**
+     * Resolves queued renderer-owned foreign-subtree tokens produced during React component rendering.
+     *
+     * 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 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.
      *
      * Behavior:
      * - SSR always returns the component's own root HTML (no synthetic wrapper).
-     * - For single-root output, a stable `data-eco-component-id` attribute is attached
-     *   to the root element so the client island runtime can target it directly.
-     * - Island client scripts are emitted through `assets` and mounted independently.
+     * - 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;
+    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[];
+    }>;
     /**
-     * Processes MDX-specific configuration dependencies including layout dependencies.
-     * @param pagePath - Absolute path to the MDX page file
-     * @returns Processed assets for MDX configuration dependencies
+     * Renders a full route response for the filesystem page pipeline.
+     *
+     * This path receives already-resolved route metadata, layout, locals, and HTML
+     * template instances from the shared renderer orchestration. Its main job is to
+     * serialize only the browser-safe page payload, compose the mixed React/non-
+     * React shell tree, and hand the result back as a document body.
      */
-    private processMdxConfigDependencies;
-    buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
-    protected importPageFile(file: string): Promise<EcoPageFile<{
-        config?: EcoComponentConfig;
-    }>>;
     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 locals for client-side hydration.
-     *
-     * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
-     * request-scoped data (e.g., session). This data needs to be serialized to the
-     * client for hydration to match the server-rendered output.
-     *
-     * 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.
+     * Renders an arbitrary React view through the application's HTML shell.
      *
-     * @param locals - The locals object from the render context
-     * @returns The locals object if serializable, undefined otherwise
+     * Unlike route rendering, this path starts from a single component rather than a
+     * page module discovered by the router. It still needs to resolve metadata,
+     * layout dependencies, and hydration assets so direct `ctx.render()` calls match
+     * normal page responses.
      */
-    private getSerializableLocals;
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }