@ecopages/react 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/react-renderer.js

@@ -1,15 +1,19 @@
-import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
-import { LocalsAccessError } from "@ecopages/core/errors/locals-access-error";
+import {
+  IntegrationRenderer
+} from "@ecopages/core/route-renderer/integration-renderer";
 import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
-import { rapidhash } from "@ecopages/core/hash";
-import { createElement } from "react";
-import { renderToReadableStream, renderToString } from "react-dom/server";
-import { PLUGIN_NAME } from "./react.plugin.js";
+import { getAppBuildExecutor } from "@ecopages/core/build/build-adapter";
+import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from "@ecopages/core/router/navigation-coordinator";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { REACT_PLUGIN_NAME } from "./react.constants.js";
 import { hasSingleRootElement } from "./utils/html-boundary.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 { ReactHydrationAssetService } from "./services/react-hydration-asset.service.js";
+import { ReactPagePayloadService } from "./services/react-page-payload.service.js";
+import { getReactIslandComponentKey, ReactHydrationAssetService } from "./services/react-hydration-asset.service.js";
 class ReactRenderError extends Error {
   constructor(message) {
     super(message);
@@ -17,103 +21,417 @@ class ReactRenderError extends Error {
   }
 }
 class BundleError extends Error {
+  logs;
   constructor(message, logs) {
     super(message);
-    this.logs = logs;
     this.name = "BundleError";
+    this.logs = logs;
   }
 }
 class ReactRenderer extends IntegrationRenderer {
-  name = PLUGIN_NAME;
+  name = REACT_PLUGIN_NAME;
   componentDirectory = RESOLVED_ASSETS_DIR;
-  componentRenderSequence = 0;
-  static routerAdapter;
-  static mdxCompilerOptions;
-  static mdxExtensions = [".mdx"];
-  static hmrPageMetadataCache;
+  reactRuntimeModules;
+  routerAdapter;
+  mdxCompilerOptions;
+  mdxExtensions;
+  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 = false;
+  explicitGraphEnabled;
   /** @internal */
   bundleService;
   /** @internal */
   pageModuleService;
   /** @internal */
   hydrationAssetService;
+  /** @internal */
+  pagePayloadService;
+  /** @internal */
+  mdxConfigDependencyService;
   constructor(options) {
-    super(options);
+    const { reactConfig, ...rendererOptions } = options;
+    super(rendererOptions);
+    this.routerAdapter = reactConfig?.routerAdapter;
+    this.mdxCompilerOptions = reactConfig?.mdxCompilerOptions;
+    this.mdxExtensions = reactConfig?.mdxExtensions ?? [".mdx"];
+    this.hmrPageMetadataCache = reactConfig?.hmrPageMetadataCache;
+    this.explicitGraphEnabled = reactConfig?.explicitGraphEnabled ?? false;
     this.bundleService = new ReactBundleService({
       rootDir: this.appConfig.rootDir,
-      routerAdapter: ReactRenderer.routerAdapter,
-      mdxCompilerOptions: ReactRenderer.mdxCompilerOptions
+      routerAdapter: this.routerAdapter,
+      mdxCompilerOptions: this.mdxCompilerOptions,
+      jsxImportSource: (this.appConfig.integrations ?? []).find((integration) => integration.name === this.name)?.jsxImportSource,
+      nonReactExtensions: (this.appConfig.integrations ?? []).filter((integration) => integration.name !== this.name).flatMap((integration) => integration.extensions)
     });
     this.pageModuleService = new ReactPageModuleService({
       rootDir: this.appConfig.rootDir,
       distDir: this.appConfig.absolutePaths.distDir,
+      workDir: this.appConfig.absolutePaths.workDir,
+      buildExecutor: getAppBuildExecutor(this.appConfig),
       layoutsDir: this.appConfig.absolutePaths.layoutsDir,
       componentsDir: this.appConfig.absolutePaths.componentsDir,
-      mdxCompilerOptions: ReactRenderer.mdxCompilerOptions,
-      mdxExtensions: ReactRenderer.mdxExtensions,
+      mdxCompilerOptions: this.mdxCompilerOptions,
+      mdxExtensions: this.mdxExtensions,
       integrationName: this.name,
-      hasRouterAdapter: Boolean(ReactRenderer.routerAdapter)
+      hasRouterAdapter: Boolean(this.routerAdapter)
     });
     this.hydrationAssetService = new ReactHydrationAssetService({
       srcDir: this.appConfig.srcDir,
-      routerAdapter: ReactRenderer.routerAdapter,
+      routerAdapter: this.routerAdapter,
       assetProcessingService: this.assetProcessingService,
       bundleService: this.bundleService,
-      hmrPageMetadataCache: ReactRenderer.hmrPageMetadataCache
+      hmrPageMetadataCache: this.hmrPageMetadataCache
+    });
+    this.pagePayloadService = new ReactPagePayloadService();
+    this.mdxConfigDependencyService = new ReactMdxConfigDependencyService({
+      integrationName: this.name,
+      pageModuleService: this.pageModuleService,
+      assetProcessingService: this.assetProcessingService
     });
   }
   shouldRenderPageComponent() {
     return false;
   }
   /**
-   * Renders a React component for component-level orchestration.
+   * Reads the declared integration name for a component or layout.
    *
-   * 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.
+   * 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.
+   */
+  getComponentIntegration(component) {
+    return component?.config?.integration ?? component?.config?.__eco?.integration;
+  }
+  /**
+   * Returns whether a component should stay inside the React render lane.
    *
-   * This preserves DOM shape for global CSS/layout selectors while keeping a
-   * deterministic mount target per component instance.
+   * 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.
    */
-  async renderComponent(input) {
-    const Component = input.component;
+  isReactManagedComponent(component) {
+    const integration = this.getComponentIntegration(component);
+    return integration === void 0 || integration === this.name;
+  }
+  getComponentRequires(component) {
+    return component?.requires;
+  }
+  getRouterDocumentAttributes() {
+    if (!this.routerAdapter) {
+      return void 0;
+    }
+    return {
+      [ECO_DOCUMENT_OWNER_ATTRIBUTE]: "react-router"
+    };
+  }
+  /**
+   * 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.
+   */
+  asReactComponent(component) {
+    return component;
+  }
+  /**
+   * 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.
+   */
+  asNonReactShellComponent(component) {
+    return component;
+  }
+  resolveReactRuntimeModules() {
+    const appPackageJsonPath = path.resolve(this.appConfig.rootDir || process.cwd(), "package.json");
+    try {
+      const requireFromApp = createRequire(appPackageJsonPath);
+      return {
+        react: requireFromApp("react"),
+        reactDomServer: requireFromApp("react-dom/server")
+      };
+    } catch {
+      const requireFromIntegration = createRequire(import.meta.url);
+      return {
+        react: requireFromIntegration("react"),
+        reactDomServer: requireFromIntegration("react-dom/server")
+      };
+    }
+  }
+  getReactRuntimeModules() {
+    this.reactRuntimeModules ??= this.resolveReactRuntimeModules();
+    return this.reactRuntimeModules;
+  }
+  /**
+   * Appends route hydration assets for a concrete page/view file to the current
+   * HTML transformer state.
+   */
+  async appendHydrationAssetsForFile(filePath) {
+    if (!filePath) {
+      return;
+    }
+    const pageBrowserGraph = await this.resolvePageBrowserGraphForFile(filePath);
+    this.mergePageBrowserGraphIntoPagePackage(pageBrowserGraph);
+  }
+  /**
+   * 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.
+   */
+  async renderNonReactShellComponent(Component, props, label) {
+    const output = await Component(props);
+    if (typeof output === "string") {
+      return output;
+    }
+    throw new ReactRenderError(`${label} must return a string when used as a mixed shell for React pages.`);
+  }
+  /**
+   * 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.
+   */
+  renderComponentHtml(input, context, runtimeContext) {
+    const { react, reactDomServer } = this.getReactRuntimeModules();
+    if (input.children === void 0) {
+      return this.normalizeUnresolvedMarkerArtifactHtml(
+        reactDomServer.renderToString(react.createElement(this.asReactComponent(input.component), input.props))
+      );
+    }
+    const resolvedChildHtml = typeof input.children === "string" ? input.children : String(input.children ?? "");
+    const rawChildrenToken = `__ECO_RAW_HTML_CHILD_${context.componentInstanceId ?? "component"}__`;
+    if (runtimeContext) {
+      runtimeContext.rawChildrenToken = rawChildrenToken;
+      runtimeContext.rawChildrenHtml = resolvedChildHtml;
+    }
+    const html = reactDomServer.renderToString(
+      react.createElement(this.asReactComponent(input.component), input.props, rawChildrenToken)
+    );
+    return this.normalizeUnresolvedMarkerArtifactHtml(html.split(rawChildrenToken).join(resolvedChildHtml));
+  }
+  /**
+   * 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.
+   */
+  restoreRuntimeChildHtml(html, runtimeContext) {
+    if (!runtimeContext?.rawChildrenToken || runtimeContext.rawChildrenHtml === void 0) {
+      return html;
+    }
+    return html.split(runtimeContext.rawChildrenToken).join(runtimeContext.rawChildrenHtml);
+  }
+  /**
+   * 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.
+   */
+  async renderQueuedChildrenToHtml(children, runtimeContext, queuedResolutionsByToken, resolveToken) {
+    if (children === void 0) {
+      return void 0;
+    }
+    const { react, reactDomServer } = this.getReactRuntimeModules();
+    let html = this.normalizeUnresolvedMarkerArtifactHtml(
+      reactDomServer.renderToString(react.createElement(react.Fragment, null, children))
+    );
+    html = this.restoreRuntimeChildHtml(html, runtimeContext);
+    html = await this.foreignSubtreeExecutionService.resolveQueuedTokens(
+      html,
+      queuedResolutionsByToken,
+      resolveToken
+    );
+    return html;
+  }
+  /**
+   * 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.
+   */
+  async resolveQueuedForeignSubtreeHtml(html, runtimeContext) {
+    return this.foreignSubtreeExecutionService.resolveQueuedHtml({
+      currentIntegrationName: this.name,
+      html,
+      runtimeContext,
+      queueLabel: "React",
+      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache),
+      applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
+      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+      renderQueuedChildren: async (children, currentRuntimeContext, queuedResolutionsByToken, resolveToken) => {
+        const renderedHtml = await this.renderQueuedChildrenToHtml(
+          children,
+          currentRuntimeContext,
+          queuedResolutionsByToken,
+          resolveToken
+        );
+        return {
+          assets: [],
+          html: renderedHtml
+        };
+      }
+    });
+  }
+  buildHydrationProps(props) {
+    if (!props || !Object.prototype.hasOwnProperty.call(props, "locals")) {
+      return props ?? {};
+    }
+    const { locals: _locals, ...hydrationProps } = props;
+    return hydrationProps;
+  }
+  /**
+   * Builds shared document html contributions for router-backed React pages rendered
+   * through a non-React HTML shell.
+   */
+  buildNonReactDocumentContributions(htmlTemplate, pageProps) {
+    if (this.isReactManagedComponent(htmlTemplate) || !this.routerAdapter) {
+      return void 0;
+    }
+    return [
+      {
+        placement: "head-append",
+        html: this.pagePayloadService.buildRouterPageDataScript(pageProps)
+      }
+    ];
+  }
+  /**
+   * 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.
+   */
+  async renderForeignComponentWithSerializedHtml(input, runtimeContext) {
+    let props = input.props;
+    if (input.children !== void 0) {
+      props = {
+        ...input.props,
+        children: typeof input.children === "string" ? input.children : String(input.children ?? "")
+      };
+    }
+    const html = await this.renderNonReactShellComponent(
+      this.asNonReactShellComponent(input.component),
+      props,
+      "Component"
+    );
+    const hasDependencies = Boolean(input.component.config?.dependencies);
+    const canResolveAssets = typeof this.assetProcessingService?.processDependencies === "function";
+    const assets = hasDependencies && canResolveAssets ? await this.processComponentDependencies([input.component]) : void 0;
+    const queuedForeignSubtreeResolution = await this.resolveQueuedForeignSubtreeHtml(html, runtimeContext);
+    const mergedAssets = this.htmlTransformer.dedupeProcessedAssets([
+      ...assets ?? [],
+      ...queuedForeignSubtreeResolution.assets
+    ]);
+    return {
+      html: queuedForeignSubtreeResolution.html,
+      canAttachAttributes: true,
+      rootTag: this.getRootTagName(queuedForeignSubtreeResolution.html),
+      integrationName: this.name,
+      assets: mergedAssets.length > 0 ? mergedAssets : void 0
+    };
+  }
+  /**
+   * 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.
+   */
+  async renderReactManagedComponent(input, runtimeContext) {
     const componentConfig = input.component.config;
-    const element = input.children === void 0 ? createElement(Component, input.props) : createElement(Component, input.props, input.children);
-    let html = renderToString(element);
-    let canAttachAttributes = hasSingleRootElement(html);
-    let rootTag = this.getRootTagName(html);
+    const context = {
+      componentInstanceId: input.integrationContext?.componentInstanceId
+    };
+    const hasResolvedChildHtml = input.children !== void 0;
+    let html = this.renderComponentHtml(input, context, runtimeContext);
+    const queuedForeignSubtreeResolution = await this.resolveQueuedForeignSubtreeHtml(html, runtimeContext);
+    html = queuedForeignSubtreeResolution.html;
+    const canAttachAttributes = hasSingleRootElement(html);
+    const rootTag = this.getRootTagName(html);
     const componentFile = componentConfig?.__eco?.file;
-    const context = input.integrationContext ?? {};
     let rootAttributes;
     let assets;
-    if (canAttachAttributes && componentFile && this.assetProcessingService) {
-      const componentInstanceId = context.componentInstanceId ?? `eco-component-${rapidhash(componentFile)}-${++this.componentRenderSequence}`;
-      assets = await this.hydrationAssetService.buildComponentRenderAssets(
-        componentFile,
-        componentInstanceId,
-        input.props,
-        componentConfig
-      );
-      rootAttributes = { "data-eco-component-id": componentInstanceId };
+    if (canAttachAttributes && componentFile && context.componentInstanceId && this.assetProcessingService && !hasResolvedChildHtml) {
+      const componentInstanceId = context.componentInstanceId;
+      assets = await this.hydrationAssetService.buildComponentRenderAssets(componentFile, componentConfig);
+      rootAttributes = {
+        "data-eco-component-id": componentInstanceId,
+        "data-eco-component-key": getReactIslandComponentKey(componentFile, componentConfig),
+        "data-eco-props": btoa(JSON.stringify(this.buildHydrationProps(input.props)))
+      };
     }
+    const mergedAssets = this.htmlTransformer.dedupeProcessedAssets([
+      ...assets ?? [],
+      ...queuedForeignSubtreeResolution.assets
+    ]);
     return {
       html,
       canAttachAttributes,
       rootTag,
       integrationName: this.name,
       rootAttributes,
-      assets
+      assets: mergedAssets.length > 0 ? mergedAssets : void 0
     };
   }
+  /**
+   * Renders a React component for component-level orchestration.
+   *
+   * Behavior:
+   * - SSR always returns the component's own root HTML (no synthetic wrapper).
+   * - 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.
+   */
+  async renderComponent(input) {
+    const runtimeContext = this.getQueuedForeignSubtreeResolutionContext(input);
+    if (!this.isReactManagedComponent(input.component)) {
+      return this.renderForeignComponentWithSerializedHtml(input, runtimeContext);
+    }
+    return this.renderReactManagedComponent(input, runtimeContext);
+  }
+  createForeignChildRuntime(options) {
+    return this.createQueuedForeignSubtreeExecutionRuntime({
+      renderInput: options.renderInput,
+      rendererCache: options.rendererCache,
+      createRuntimeContext: (integrationContext, rendererCache) => ({
+        rendererCache,
+        componentInstanceScope: integrationContext.componentInstanceId,
+        nextForeignSubtreeId: 0,
+        queuedResolutions: [],
+        rawChildrenToken: void 0,
+        rawChildrenHtml: void 0
+      })
+    });
+  }
   /**
    * Checks if the given file path corresponds to an MDX file based on configured extensions.
    * @param filePath - The file path to check
@@ -122,47 +440,49 @@ class ReactRenderer extends IntegrationRenderer {
   isMdxFile(filePath) {
     return this.pageModuleService.isMdxFile(filePath);
   }
-  /**
-   * Processes MDX-specific configuration dependencies including layout dependencies.
-   * @param pagePath - Absolute path to the MDX page file
-   * @returns Processed assets for MDX configuration dependencies
-   */
-  async processMdxConfigDependencies(pagePath) {
-    const { config } = await this.importPageFile(pagePath);
-    const resolvedLayout = config?.layout;
-    const components = [];
-    if (resolvedLayout?.config?.dependencies) {
-      const layoutConfig = this.pageModuleService.ensureConfigFileMetadata(resolvedLayout.config, pagePath);
-      components.push({ config: layoutConfig });
-    }
-    if (config?.dependencies) {
-      const configWithMeta = {
-        ...config,
-        __eco: { id: rapidhash(pagePath).toString(36), file: pagePath, integration: "react" }
-      };
-      components.push({ config: configWithMeta });
+  usesIntegrationPageImporter(file) {
+    return this.pageModuleService.isMdxFile(file);
+  }
+  async importIntegrationPageFile(file, options) {
+    return await this.pageModuleService.importMdxPageFile(file, options);
+  }
+  normalizeImportedPageFile(file, pageModule) {
+    const reactModule = pageModule;
+    const { default: Page, getMetadata, config } = reactModule;
+    if (this.pageModuleService.isMdxFile(file) && config) {
+      Page.config = config;
     }
-    return this.processComponentDependencies(components);
+    return {
+      ...pageModule,
+      default: Page,
+      getMetadata,
+      config
+    };
   }
-  async buildRouteRenderAssets(pagePath) {
+  async collectPageBrowserGraphContribution(context) {
     try {
-      const pageModule = await this.importPageFile(pagePath);
-      const shouldHydrate = ReactRenderer.explicitGraphEnabled ? true : this.pageModuleService.shouldHydratePage(pageModule);
+      const { file: pagePath, pageModule } = context;
+      const shouldHydrate = this.explicitGraphEnabled ? true : this.pageModuleService.shouldHydratePage(pageModule);
       if (!shouldHydrate) {
-        return [];
+        return { assets: [] };
       }
       const isMdx = this.pageModuleService.isMdxFile(pagePath);
       const declaredModules = this.pageModuleService.collectPageDeclaredModules(pageModule);
-      const processedAssets = await this.hydrationAssetService.buildRouteRenderAssets(
+      const dependencies = await this.hydrationAssetService.createPageBrowserGraphDependencies(
         pagePath,
         isMdx,
         declaredModules
       );
+      const assets = [];
       if (isMdx) {
-        const mdxConfigAssets = await this.processMdxConfigDependencies(pagePath);
-        return [...processedAssets, ...mdxConfigAssets];
+        const mdxConfigAssets = await this.mdxConfigDependencyService.processMdxConfigDependencies({
+          pagePath,
+          config: pageModule.config,
+          processComponentDependencies: async (components) => await this.processComponentDependencies(components)
+        });
+        assets.push(...mdxConfigAssets);
       }
-      return processedAssets;
+      return { dependencies, assets };
     } catch (error) {
       if (error instanceof BundleError) {
         console.error("[ecopages] Bundle errors:", error.logs);
@@ -172,18 +492,14 @@ class ReactRenderer extends IntegrationRenderer {
       );
     }
   }
-  async importPageFile(file) {
-    const module = this.pageModuleService.isMdxFile(file) ? await this.pageModuleService.importMdxPageFile(file) : await super.importPageFile(file);
-    const { default: Page, getMetadata, config } = module;
-    if (this.pageModuleService.isMdxFile(file) && config) {
-      Page.config = config;
-    }
-    return {
-      default: Page,
-      getMetadata,
-      config
-    };
-  }
+  /**
+   * 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.
+   */
   async render({
     params,
     query,
@@ -197,99 +513,103 @@ class ReactRenderer extends IntegrationRenderer {
     pageProps
   }) {
     try {
-      const pageElement = createElement(Page, { params, query, ...props, locals: pageLocals });
-      const contentElement = Layout ? createElement(Layout, { locals }, pageElement) : pageElement;
-      const safeLocals = this.getSerializableLocals(locals);
-      const allPageProps = {
-        ...pageProps,
+      const safeLocals = this.pagePayloadService.getSerializableLocals(locals, this.getComponentRequires(Page));
+      const allPageProps = this.pagePayloadService.buildSerializedPageProps({
+        pageProps,
         params,
         query,
-        ...safeLocals && { locals: safeLocals }
-      };
-      return await renderToReadableStream(
-        createElement(
-          HtmlTemplate,
-          {
-            metadata,
-            pageProps: allPageProps
-          },
-          contentElement
-        )
-      );
+        safeLocals
+      });
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: { params, query, ...props, locals: pageLocals }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
+        metadata,
+        pageProps: allPageProps
+      });
     } catch (error) {
       throw this.createRenderError("Failed to render component", error);
     }
   }
-  /**
-   * 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.
-   *
-   * @param locals - The locals object from the render context
-   * @returns The locals object if serializable, undefined otherwise
-   */
-  getSerializableLocals(locals) {
-    try {
-      if (locals && Object.keys(locals).length > 0) {
-        return locals;
-      }
+  getHtmlDocumentContributions(options) {
+    if (options.partial || !options.renderOptions) {
       return void 0;
-    } catch (e) {
-      if (e instanceof LocalsAccessError) {
-        return void 0;
-      }
-      throw e;
     }
+    const safeLocals = this.pagePayloadService.getSerializableLocals(
+      options.renderOptions.locals,
+      this.getComponentRequires(options.renderOptions.Page)
+    );
+    const allPageProps = this.pagePayloadService.buildSerializedPageProps({
+      pageProps: options.renderOptions.pageProps,
+      params: options.renderOptions.params,
+      query: options.renderOptions.query,
+      safeLocals
+    });
+    return this.buildNonReactDocumentContributions(options.renderOptions.HtmlTemplate, allPageProps);
+  }
+  getDocumentAttributes() {
+    return this.getRouterDocumentAttributes();
   }
+  /**
+   * 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.
+   */
   async renderToResponse(view, props, ctx) {
     try {
+      const { react, reactDomServer } = this.getReactRuntimeModules();
       const viewConfig = view.config;
       const Layout = viewConfig?.layout;
-      const ViewComponent = view;
-      const pageElement = createElement(ViewComponent, props || {});
+      const ViewComponent = this.asReactComponent(view);
+      const normalizedProps = props ?? {};
       if (ctx.partial) {
-        const stream = await renderToReadableStream(pageElement);
-        return this.createHtmlResponse(stream, ctx);
+        return this.renderPartialViewResponse({
+          view,
+          props,
+          ctx,
+          renderInline: async () => await reactDomServer.renderToReadableStream(
+            react.createElement(ViewComponent, normalizedProps)
+          )
+        });
       }
-      const contentElement = Layout ? createElement(Layout, {}, pageElement) : pageElement;
       const HtmlTemplate = await this.getHtmlTemplate();
-      const metadata = view.metadata ? await view.metadata({
-        params: {},
-        query: {},
-        props,
-        appConfig: this.appConfig
-      }) : this.appConfig.defaultMetadata;
+      const metadata = await this.resolveViewMetadata(view, props);
       await this.prepareViewDependencies(view, Layout);
-      const viewFilePath = viewConfig?.__eco?.file;
-      if (viewFilePath) {
-        const hydrationAssets = await this.buildRouteRenderAssets(viewFilePath);
-        this.htmlTransformer.setProcessedDependencies([
-          ...this.htmlTransformer.getProcessedDependencies(),
-          ...hydrationAssets
-        ]);
-      }
-      const streamBody = await renderToReadableStream(
-        createElement(
-          HtmlTemplate,
-          {
-            metadata,
-            pageProps: props
-          },
-          contentElement
-        )
-      );
-      const transformedResponse = await this.htmlTransformer.transform(
-        new Response(streamBody, {
-          headers: { "Content-Type": "text/html" }
-        })
-      );
-      return this.createHtmlResponse(transformedResponse.body ?? "", ctx);
+      await this.appendHydrationAssetsForFile(viewConfig?.__eco?.file);
+      const viewRender = await this.renderComponentWithForeignChildren({
+        component: view,
+        props: normalizedProps
+      });
+      const layoutRender = Layout ? await this.renderComponentWithForeignChildren({
+        component: Layout,
+        props: {},
+        children: viewRender.html
+      }) : void 0;
+      const documentRender = await this.renderComponentWithForeignChildren({
+        component: HtmlTemplate,
+        props: {
+          metadata,
+          pageProps: normalizedProps
+        },
+        children: layoutRender?.html ?? viewRender.html
+      });
+      this.appendProcessedDependencies(viewRender.assets, layoutRender?.assets, documentRender.assets);
+      const transformedHtml = await this.finalizeResolvedHtml({
+        html: `${this.DOC_TYPE}${documentRender.html}`,
+        partial: false,
+        documentAttributes: this.getRouterDocumentAttributes(),
+        htmlContributions: this.buildNonReactDocumentContributions(HtmlTemplate, normalizedProps)
+      });
+      return this.createHtmlResponse(transformedHtml, ctx);
     } catch (error) {
       throw this.createRenderError("Failed to render view", error);
     }