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

package/src/react-renderer.js

@@ -1,19 +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 { getAppBuildExecutor } from "@ecopages/core/build/build-adapter";
-import { rapidhash } from "@ecopages/core/hash";
-import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
 import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from "@ecopages/core/router/navigation-coordinator";
+import { createRequire } from "node:module";
 import path from "node:path";
-import { createElement } from "react";
-import { renderToReadableStream, renderToString } from "react-dom/server";
-import { PLUGIN_NAME } from "./react.plugin.js";
+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);
@@ -29,31 +29,44 @@ class BundleError extends Error {
   }
 }
 class ReactRenderer extends IntegrationRenderer {
-  name = PLUGIN_NAME;
+  name = REACT_PLUGIN_NAME;
   componentDirectory = RESOLVED_ASSETS_DIR;
-  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,
@@ -62,17 +75,23 @@ class ReactRenderer extends IntegrationRenderer {
       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() {
@@ -99,19 +118,11 @@ class ReactRenderer extends IntegrationRenderer {
     const integration = this.getComponentIntegration(component);
     return integration === void 0 || integration === this.name;
   }
-  /**
-   * 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.
-   */
-  buildRouterPageDataScript(pageProps) {
-    const safeJson = JSON.stringify(pageProps || {}).replace(/</g, "\\u003c");
-    return `<script id="__ECO_PAGE_DATA__" type="application/json">${safeJson}<\/script>`;
+  getComponentRequires(component) {
+    return component?.requires;
   }
   getRouterDocumentAttributes() {
-    if (!ReactRenderer.routerAdapter) {
+    if (!this.routerAdapter) {
       return void 0;
     }
     return {
@@ -139,20 +150,25 @@ class ReactRenderer extends IntegrationRenderer {
   asNonReactShellComponent(component) {
     return component;
   }
-  /**
-   * 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.
-   */
-  buildSerializedPageProps(options) {
-    return {
-      ...options.pageProps,
-      params: options.params,
-      query: options.query,
-      ...options.safeLocals && { locals: options.safeLocals }
-    };
+  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
@@ -162,26 +178,8 @@ class ReactRenderer extends IntegrationRenderer {
     if (!filePath) {
       return;
     }
-    const hydrationAssets = await this.buildRouteRenderAssets(filePath);
-    this.htmlTransformer.setProcessedDependencies([
-      ...this.htmlTransformer.getProcessedDependencies(),
-      ...hydrationAssets
-    ]);
-  }
-  /**
-   * 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.
-   */
-  async resolveViewMetadata(view, props) {
-    return view.metadata ? await view.metadata({
-      params: {},
-      query: {},
-      props,
-      appConfig: this.appConfig
-    }) : this.appConfig.defaultMetadata;
+    const pageBrowserGraph = await this.resolvePageBrowserGraphForFile(filePath);
+    this.mergePageBrowserGraphIntoPagePackage(pageBrowserGraph);
   }
   /**
    * Renders a non-React layout or HTML template and enforces that mixed shells
@@ -198,110 +196,242 @@ class ReactRenderer extends IntegrationRenderer {
     throw new ReactRenderError(`${label} must return a string when used as a mixed shell for React pages.`);
   }
   /**
-   * 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.
    *
-   * 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.
+   * @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.
    */
-  async composePageContent(options) {
-    const pageElement = createElement(options.Page, options.pageProps);
-    const pageHtml = renderToString(pageElement);
-    const layoutProps = options.locals ? { locals: options.locals } : {};
-    if (!options.Layout) {
-      return { contentNode: pageElement, contentHtml: pageHtml };
+  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))
+      );
     }
-    if (this.isReactManagedComponent(options.Layout)) {
-      const layoutElement = createElement(this.asReactComponent(options.Layout), layoutProps, pageElement);
-      return {
-        contentNode: layoutElement,
-        contentHtml: renderToString(layoutElement)
-      };
+    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 layoutHtml = await this.renderNonReactShellComponent(
-      this.asNonReactShellComponent(options.Layout),
-      { ...layoutProps, children: pageHtml },
-      "Layout"
+    const html = reactDomServer.renderToString(
+      react.createElement(this.asReactComponent(input.component), input.props, rawChildrenToken)
     );
-    return { contentNode: layoutHtml, contentHtml: layoutHtml };
+    return this.normalizeUnresolvedMarkerArtifactHtml(html.split(rawChildrenToken).join(resolvedChildHtml));
   }
   /**
-   * Wraps composed page content in the final document template.
+   * Restores raw child HTML that was temporarily replaced by a token during React SSR.
    *
-   * 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.
+   * 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.
    */
-  async renderDocument(options) {
-    if (this.isReactManagedComponent(options.HtmlTemplate)) {
-      return renderToReadableStream(
-        createElement(
-          this.asReactComponent(options.HtmlTemplate),
-          {
-            metadata: options.metadata,
-            pageProps: options.pageProps
-          },
-          options.contentNode
-        )
-      );
+  restoreRuntimeChildHtml(html, runtimeContext) {
+    if (!runtimeContext?.rawChildrenToken || runtimeContext.rawChildrenHtml === void 0) {
+      return html;
     }
-    const headContent = ReactRenderer.routerAdapter ? this.buildRouterPageDataScript(options.pageProps) : void 0;
-    return this.renderNonReactShellComponent(
-      this.asNonReactShellComponent(options.HtmlTemplate),
-      {
-        metadata: options.metadata,
-        pageProps: options.pageProps,
-        children: options.contentHtml,
-        headContent
-      },
-      "HtmlTemplate"
+    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;
   }
   /**
-   * Renders a React component for component-level orchestration.
+   * Resolves queued renderer-owned foreign-subtree tokens produced during React component rendering.
    *
-   * 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.
+   * 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.
    *
-   * This preserves DOM shape for global CSS/layout selectors while keeping a
-   * deterministic mount target per component instance.
+   * 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 renderComponent(input) {
-    const Component = this.asReactComponent(input.component);
+  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 && context.componentInstanceId && this.assetProcessingService) {
+    if (canAttachAttributes && componentFile && context.componentInstanceId && this.assetProcessingService && !hasResolvedChildHtml) {
       const componentInstanceId = context.componentInstanceId;
-      assets = await this.hydrationAssetService.buildComponentRenderAssets(
-        componentFile,
-        componentInstanceId,
-        input.props,
-        componentConfig
-      );
+      assets = await this.hydrationAssetService.buildComponentRenderAssets(componentFile, componentConfig);
       rootAttributes = {
         "data-eco-component-id": componentInstanceId,
-        "data-eco-props": btoa(JSON.stringify(input.props ?? {}))
+        "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
@@ -310,126 +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 });
-    }
-    const processedDependencies = await this.processComponentDependencies(components);
-    const eagerSsrLazyDependencies = await this.processDeclaredMdxSsrLazyDependencies(components, pagePath);
-    return [...processedDependencies, ...eagerSsrLazyDependencies];
+  usesIntegrationPageImporter(file) {
+    return this.pageModuleService.isMdxFile(file);
   }
-  async processDeclaredMdxSsrLazyDependencies(components, pagePath) {
-    if (!this.assetProcessingService?.processDependencies) {
-      return [];
-    }
-    const dependencies = this.collectDeclaredMdxSsrLazyDependencies(components);
-    if (dependencies.length === 0) {
-      return [];
+  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.assetProcessingService.processDependencies(dependencies, `react-mdx-ssr-lazy:${pagePath}`);
-  }
-  collectDeclaredMdxSsrLazyDependencies(components) {
-    const dependencies = [];
-    const visitedConfigs = /* @__PURE__ */ new Set();
-    const seenKeys = /* @__PURE__ */ new Set();
-    const normalizeAttributes = (attributes) => ({
-      type: "module",
-      defer: "",
-      ...attributes ?? {}
-    });
-    const collect = (config) => {
-      if (!config || visitedConfigs.has(config)) {
-        return;
-      }
-      visitedConfigs.add(config);
-      const componentFile = config.__eco?.file;
-      if (componentFile) {
-        const componentDir = path.dirname(componentFile);
-        for (const script of config.dependencies?.scripts ?? []) {
-          if (typeof script === "string" || !script.lazy || script.ssr !== true) {
-            continue;
-          }
-          const attributes = normalizeAttributes(script.attributes);
-          if (script.content) {
-            const key2 = `content:${script.content}:${JSON.stringify(attributes)}`;
-            if (seenKeys.has(key2)) {
-              continue;
-            }
-            seenKeys.add(key2);
-            dependencies.push(
-              AssetFactory.createContentScript({
-                position: "head",
-                content: script.content,
-                attributes
-              })
-            );
-            continue;
-          }
-          if (!script.src) {
-            continue;
-          }
-          const resolvedPath = path.resolve(componentDir, script.src);
-          const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
-          if (seenKeys.has(key)) {
-            continue;
-          }
-          seenKeys.add(key);
-          dependencies.push(
-            AssetFactory.createFileScript({
-              filepath: resolvedPath,
-              position: "head",
-              attributes
-            })
-          );
-        }
-      }
-      if (config.layout?.config) {
-        collect(config.layout.config);
-      }
-      for (const nestedComponent of config.dependencies?.components ?? []) {
-        collect(nestedComponent?.config);
-      }
+    return {
+      ...pageModule,
+      default: Page,
+      getMetadata,
+      config
     };
-    for (const component of components) {
-      collect(component.config);
-    }
-    return dependencies;
   }
-  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);
@@ -439,26 +492,6 @@ class ReactRenderer extends IntegrationRenderer {
       );
     }
   }
-  /**
-   * 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.
-   */
-  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.
    *
@@ -480,71 +513,48 @@ class ReactRenderer extends IntegrationRenderer {
     pageProps
   }) {
     try {
-      const safeLocals = this.getSerializableLocals(locals, Page.requires);
-      const allPageProps = this.buildSerializedPageProps({
+      const safeLocals = this.pagePayloadService.getSerializableLocals(locals, this.getComponentRequires(Page));
+      const allPageProps = this.pagePayloadService.buildSerializedPageProps({
         pageProps,
         params,
         query,
         safeLocals
       });
-      const { contentNode, contentHtml } = await this.composePageContent({
-        Page: this.asReactComponent(Page),
-        Layout,
-        pageProps: { params, query, ...props, locals: pageLocals },
-        locals
-      });
-      return await this.renderDocument({
-        HtmlTemplate,
+      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,
-        contentNode,
-        contentHtml
+        pageProps: allPageProps
       });
     } catch (error) {
       throw this.createRenderError("Failed to render component", error);
     }
   }
-  getDocumentAttributes() {
-    return this.getRouterDocumentAttributes();
-  }
-  /**
-   * 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
-   */
-  getSerializableLocals(locals, requiredLocals) {
-    try {
-      if (!locals) {
-        return void 0;
-      }
-      const requiredKeys = requiredLocals ? Array.isArray(requiredLocals) ? requiredLocals : [requiredLocals] : [];
-      if (requiredKeys.length === 0) {
-        return void 0;
-      }
-      const serializedLocals = Object.fromEntries(
-        requiredKeys.filter((key) => Object.prototype.hasOwnProperty.call(locals, key)).map((key) => [key, locals[key]])
-      );
-      if (Object.keys(serializedLocals).length > 0) {
-        return serializedLocals;
-      }
+  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.
@@ -556,43 +566,49 @@ class ReactRenderer extends IntegrationRenderer {
    */
   async renderToResponse(view, props, ctx) {
     try {
+      const { react, reactDomServer } = this.getReactRuntimeModules();
       const viewConfig = view.config;
       const Layout = viewConfig?.layout;
       const ViewComponent = this.asReactComponent(view);
       const normalizedProps = props ?? {};
       if (ctx.partial) {
-        const stream = await renderToReadableStream(createElement(ViewComponent, normalizedProps));
-        return this.createHtmlResponse(stream, ctx);
+        return this.renderPartialViewResponse({
+          view,
+          props,
+          ctx,
+          renderInline: async () => await reactDomServer.renderToReadableStream(
+            react.createElement(ViewComponent, normalizedProps)
+          )
+        });
       }
       const HtmlTemplate = await this.getHtmlTemplate();
       const metadata = await this.resolveViewMetadata(view, props);
       await this.prepareViewDependencies(view, Layout);
       await this.appendHydrationAssetsForFile(viewConfig?.__eco?.file);
-      const { contentNode, contentHtml } = await this.composePageContent({
-        Page: ViewComponent,
-        Layout,
-        pageProps: normalizedProps
+      const viewRender = await this.renderComponentWithForeignChildren({
+        component: view,
+        props: normalizedProps
       });
-      const body = await this.renderDocument({
-        HtmlTemplate,
-        metadata,
-        pageProps: normalizedProps,
-        contentNode,
-        contentHtml
+      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)
       });
-      const transformedResponse = await this.htmlTransformer.transform(
-        new Response(body, {
-          headers: { "Content-Type": "text/html" }
-        })
-      );
-      let transformedHtml = await transformedResponse.text();
-      const documentAttributes = this.getRouterDocumentAttributes();
-      if (documentAttributes) {
-        transformedHtml = this.htmlTransformer.applyAttributesToHtmlElement(
-          transformedHtml,
-          documentAttributes
-        );
-      }
       return this.createHtmlResponse(transformedHtml, ctx);
     } catch (error) {
       throw this.createRenderError("Failed to render view", error);