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

package/src/react-renderer.d.ts

@@ -12,6 +12,11 @@ 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.
  */
@@ -32,7 +37,6 @@ 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[];
@@ -57,14 +61,101 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
         runtimeOrigin: string;
     });
     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;
+    /**
+     * 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 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     *
+     * 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;
+    /**
+     * Produces the page body before the final HTML template is applied.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    private renderDocument;
     /**
      * 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.
      *
      * This preserves DOM shape for global CSS/layout selectors while keeping a
      * deterministic mount target per component instance.
@@ -82,25 +173,53 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * @returns Processed assets for MDX configuration dependencies
      */
     private processMdxConfigDependencies;
+    private processDeclaredMdxSsrLazyDependencies;
+    private collectDeclaredMdxSsrLazyDependencies;
     buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
-    protected importPageFile(file: string): Promise<EcoPageFile<{
-        config?: EcoComponentConfig;
-    }>>;
+    /**
+     * 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.
+     *
+     * 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.
+     */
     render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody>;
+    protected getDocumentAttributes(): Record<string, string> | undefined;
     /**
-     * Safely extracts locals for client-side hydration.
+     * 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). This data needs to be serialized to the
-     * client for hydration to match the server-rendered output.
+     * 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
-     * @returns The locals object if serializable, undefined otherwise
+     * @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.
+     *
+     * 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.
+     */
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }
+export {};