@ecopages/react 0.2.0-alpha.3 → 0.2.0-alpha.30

package/src/react-hmr-strategy.js

@@ -1,96 +1,43 @@
 import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
-import { defaultBuildAdapter } from "@ecopages/core/build/build-adapter";
+import { rewriteRuntimeSpecifierAliases } from "@ecopages/core/build/runtime-specifier-aliases";
+import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
 import { FileNotFoundError, fileSystem } from "@ecopages/file-system";
 import { Logger } from "@ecopages/logger";
 import { injectHmrHandler } from "./utils/hmr-scripts.js";
 import { createClientGraphBoundaryPlugin } from "./utils/client-graph-boundary-plugin.js";
 import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from "./utils/declared-modules.js";
+import { getReactClientGraphAllowSpecifiers } from "./utils/react-runtime-alias-map.js";
+import { createUseSyncExternalStoreShimPlugin } from "./utils/use-sync-external-store-shim-plugin.js";
 const appLogger = new Logger("[ReactHmrStrategy]");
 class ReactHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.INTEGRATION;
+  mdxCompilerOptions;
+  ownedTemplateExtensions;
+  allTemplateExtensions;
+  async importNodePageModule(entrypointPath) {
+    return await this.context.importServerModule(entrypointPath);
+  }
   /**
    * Creates a new React HMR strategy instance.
    *
-   * @param context - The HMR context providing access to watched files, plugins, build directories,
-   *                  and the layouts directory for detecting layout file changes that require full
-   *                  page reloads instead of module-level HMR updates.
-   * @param pageMetadataCache - React-only cache of declared browser modules discovered during
-   *                            server rendering. This avoids re-importing unchanged page modules
-   *                            during save-time Fast Refresh rebuilds.
-   * @param mdxCompilerOptions - Optional MDX compiler options for processing .mdx files
-   * @param explicitGraphEnabled - Enables explicit graph mode for React HMR bundling.
-   * In explicit mode, HMR builds omit AST server-only stripping plugins in React paths.
+   * @param options - React HMR runtime services and behavior flags.
    */
-  constructor(context, pageMetadataCache, mdxCompilerOptions, explicitGraphEnabled = false) {
+  context;
+  pageMetadataCache;
+  explicitGraphEnabled;
+  runtimeAliasMap;
+  constructor(options) {
     super();
-    this.context = context;
-    this.pageMetadataCache = pageMetadataCache;
-    this.explicitGraphEnabled = explicitGraphEnabled;
-    this.mdxCompilerOptions = mdxCompilerOptions;
-  }
-  type = HmrStrategyType.INTEGRATION;
-  mdxCompilerOptions;
-  knownEntrypoints = /* @__PURE__ */ new Set();
-  async importNodePageModule(entrypointPath) {
-    const srcDir = this.context.getSrcDir();
-    const rootDir = path.dirname(srcDir);
-    const outdir = path.join(path.resolve(this.context.getDistDir(), "..", ".."), ".server-modules");
-    const fileBaseName = path.basename(entrypointPath, path.extname(entrypointPath));
-    const fileHash = fileSystem.hash(entrypointPath);
-    const outputFileName = `${fileBaseName}-${fileHash}.js`;
-    const buildResult = await defaultBuildAdapter.build({
-      entrypoints: [entrypointPath],
-      root: rootDir,
-      outdir,
-      target: "node",
-      format: "esm",
-      sourcemap: "none",
-      splitting: false,
-      minify: false,
-      naming: outputFileName
-    });
-    if (!buildResult.success) {
-      const details = buildResult.logs.map((log) => log.message).join(" | ");
-      throw new Error(`Error transpiling React HMR page module: ${details}`);
-    }
-    const preferredOutputPath = path.join(outdir, outputFileName);
-    const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => output.path.endsWith(".js"))?.path;
-    if (!compiledOutput) {
-      throw new Error(`No transpiled output generated for React HMR page module: ${entrypointPath}`);
-    }
-    return await import(pathToFileURL(compiledOutput).href);
-  }
-  createUseSyncExternalStoreShimPlugin() {
-    return {
-      name: "react-hmr-use-sync-external-store-shim",
-      setup(build) {
-        build.onResolve({ filter: /^use-sync-external-store\/shim(?:\/index\.js)?$/ }, () => ({
-          path: "use-sync-external-store/shim",
-          namespace: "ecopages-react-hmr-shim"
-        }));
-        build.onLoad(
-          { filter: /^use-sync-external-store\/shim$/, namespace: "ecopages-react-hmr-shim" },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-        build.onLoad({ filter: /[\\/]use-sync-external-store[\\/]shim[\\/]index\.js$/ }, () => ({
-          contents: "export { useSyncExternalStore } from 'react';",
-          loader: "js"
-        }));
-        build.onLoad(
-          {
-            filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.development\.js$/
-          },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-      }
-    };
+    this.context = options.context;
+    this.pageMetadataCache = options.pageMetadataCache;
+    this.runtimeAliasMap = options.runtimeAliasMap;
+    this.explicitGraphEnabled = options.explicitGraphEnabled ?? false;
+    this.mdxCompilerOptions = options.mdxCompilerOptions;
+    this.ownedTemplateExtensions = new Set(options.ownedTemplateExtensions ?? [".tsx"]);
+    this.allTemplateExtensions = [...options.allTemplateExtensions ?? [".tsx"]].sort(
+      (a, b) => b.length - a.length
+    );
   }
   /**
    * Returns build plugins for React HMR bundling.
@@ -99,30 +46,56 @@ class ReactHmrStrategy extends HmrStrategy {
    * (including `node:*`) from breaking the browser bundle.
    */
   getBuildPlugins(declaredModules) {
-    const allowSpecifiers = [
-      "@ecopages/core",
-      "react",
-      "react-dom",
-      "react/jsx-runtime",
-      "react/jsx-dev-runtime",
-      "react-dom/client",
-      ...Array.from(this.context.getSpecifierMap().keys())
-    ];
+    const allowSpecifiers = getReactClientGraphAllowSpecifiers(this.runtimeAliasMap.keys());
+    const runtimeAliasPlugin = createRuntimeSpecifierAliasPlugin(this.runtimeAliasMap, {
+      name: "react-hmr-runtime-specifier-alias"
+    });
     return [
       createClientGraphBoundaryPlugin({
         absWorkingDir: path.dirname(this.context.getSrcDir()),
         alwaysAllowSpecifiers: allowSpecifiers,
         declaredModules
       }),
+      ...runtimeAliasPlugin ? [runtimeAliasPlugin] : [],
       ...this.context.getPlugins(),
-      this.createUseSyncExternalStoreShimPlugin()
+      createUseSyncExternalStoreShimPlugin({
+        name: "react-hmr-use-sync-external-store-shim",
+        namespace: "ecopages-react-hmr-shim"
+      })
     ];
   }
   isReactEntrypoint(filePath) {
-    if (filePath.endsWith(".tsx")) {
+    if (filePath.endsWith(".mdx")) {
+      return this.mdxCompilerOptions !== void 0;
+    }
+    if (!filePath.endsWith(".tsx")) {
+      return false;
+    }
+    if (!this.isRouteTemplate(filePath)) {
       return true;
     }
-    return filePath.endsWith(".mdx") && this.mdxCompilerOptions !== void 0;
+    const templateExtension = this.resolveTemplateExtension(filePath);
+    if (!templateExtension) {
+      return false;
+    }
+    return this.ownedTemplateExtensions.has(templateExtension);
+  }
+  /**
+   * Returns true when a route file uses a compound extension like `page.foo.tsx`.
+   *
+   * @remarks
+   * React integration owns plain `.tsx` route templates. Compound extensions in
+   * pages/layouts are integration-specific route templates and should not be
+   * claimed by React HMR strategy.
+   */
+  isRouteTemplate(filePath) {
+    return filePath.startsWith(this.context.getPagesDir()) || filePath.startsWith(this.context.getLayoutsDir());
+  }
+  resolveTemplateExtension(filePath) {
+    return this.allTemplateExtensions.find((extension) => filePath.endsWith(extension));
+  }
+  ownsWatchedEntrypoint(filePath) {
+    return this.pageMetadataCache.ownsEntrypoint(filePath);
   }
   /**
    * Determines if the file is a React/MDX entrypoint that's registered for HMR.
@@ -136,6 +109,9 @@ class ReactHmrStrategy extends HmrStrategy {
     if (watchedFiles.size === 0) {
       return false;
     }
+    if (watchedFiles.has(filePath)) {
+      return this.ownsWatchedEntrypoint(filePath);
+    }
     return this.isReactEntrypoint(filePath);
   }
   /**
@@ -174,8 +150,12 @@ class ReactHmrStrategy extends HmrStrategy {
     if (isLayout) {
       appLogger.debug(`Detected layout file change: ${_filePath}`);
     }
-    const entrypointsToBuild = !this.knownEntrypoints.has(_filePath) && watchedFiles.has(_filePath) ? [[_filePath, watchedFiles.get(_filePath)]] : watchedFiles.entries();
-    this.knownEntrypoints.add(_filePath);
+    const changedEntrypointOutput = watchedFiles.get(_filePath);
+    if (changedEntrypointOutput && !this.ownsWatchedEntrypoint(_filePath)) {
+      appLogger.debug(`Skipping non-React watched entrypoint: ${_filePath}`);
+      return { type: "none" };
+    }
+    const entrypointsToBuild = changedEntrypointOutput ? [[_filePath, changedEntrypointOutput]] : watchedFiles.entries();
     const updates = [];
     for (const [entrypoint, outputUrl] of entrypointsToBuild) {
       if (!this.isReactEntrypoint(entrypoint)) {
@@ -235,16 +215,13 @@ class ReactHmrStrategy extends HmrStrategy {
         const mdxPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
         plugins.unshift(mdxPlugin);
       }
-      const result = await defaultBuildAdapter.build({
+      const result = await this.context.getBrowserBundleService().bundle({
+        profile: "hmr-entrypoint",
         entrypoints: [entrypointPath],
         outdir: tempDir,
         naming: `[name].[hash].tmp`,
-        target: "browser",
-        format: "esm",
-        sourcemap: "none",
         plugins,
-        minify: false,
-        external: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"]
+        minify: false
       });
       if (!result.success) {
         appLogger.error(`Failed to build ${entrypointPath}:`, result.logs);
@@ -255,13 +232,33 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`No output file generated for ${entrypointPath}`);
         return false;
       }
-      const processed = await this.processOutput(tempFile, outputPath, outputUrl);
+      const resolvedTempFile = await this.resolveTempOutputPath(tempFile);
+      if (!resolvedTempFile) {
+        appLogger.debug(`Skipping stale temp output for ${outputUrl}: ${tempFile}`);
+        return false;
+      }
+      const processed = await this.processOutput(resolvedTempFile, outputPath, outputUrl);
       return processed;
     } catch (error) {
       appLogger.error(`Error bundling ${entrypointPath}:`, error);
       return false;
     }
   }
+  async resolveTempOutputPath(tempPath) {
+    if (fileSystem.exists(tempPath)) {
+      return tempPath;
+    }
+    if (!tempPath.includes("[hash]")) {
+      return tempPath;
+    }
+    const directory = path.dirname(tempPath);
+    const pattern = path.basename(tempPath).replaceAll("[hash]", "*");
+    const matches = await fileSystem.glob([pattern], { cwd: directory });
+    if (matches.length === 0) {
+      return null;
+    }
+    return path.isAbsolute(matches[0]) ? matches[0] : path.join(directory, matches[0]);
+  }
   /**
    * Encodes dynamic route segments (brackets) in file paths.
    * Converts `[slug]` to `_slug_` to avoid filesystem issues.
@@ -270,7 +267,7 @@ class ReactHmrStrategy extends HmrStrategy {
     return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
   }
   /**
-   * Processes bundled output by replacing specifiers and injecting HMR handler.
+   * Processes bundled output and injects the React HMR handler.
    * Writes to temp file first, then renames atomically to avoid conflicts.
    *
    * @param tempPath - Path to the temporary bundled file
@@ -285,7 +282,7 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     try {
       let code = await fileSystem.readFile(tempPath);
-      code = this.replaceBareSpecifiers(code);
+      code = rewriteRuntimeSpecifierAliases(code, this.runtimeAliasMap);
       code = injectHmrHandler(code);
       await fileSystem.writeAsync(finalPath, code);
       await fileSystem.removeAsync(tempPath).catch(() => {
@@ -305,27 +302,6 @@ class ReactHmrStrategy extends HmrStrategy {
       return false;
     }
   }
-  /**
-   * Replaces bare specifiers with runtime URLs.
-   *
-   * Handles both static imports and dynamic imports.
-   *
-   * @param code - The bundled code to transform
-   * @returns The transformed code with runtime URLs
-   */
-  replaceBareSpecifiers(code) {
-    const specifierMap = this.context.getSpecifierMap();
-    if (specifierMap.size === 0) {
-      return code;
-    }
-    let result = code;
-    for (const [bareSpec, runtimeUrl] of specifierMap.entries()) {
-      const escaped = bareSpec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      result = result.replace(new RegExp(`from\\s*["']${escaped}["']`, "g"), `from "${runtimeUrl}"`);
-      result = result.replace(new RegExp(`import\\(["']${escaped}["']\\)`, "g"), `import("${runtimeUrl}")`);
-    }
-    return result;
-  }
 }
 export {
   ReactHmrStrategy

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 { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import { IntegrationRenderer, type RenderToResponseContext, type RouteModuleLoadOptions } 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 { 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 the extra document props needed when React renders through a non-React HTML shell.
+     *
+     * Router-backed React pages still need to publish the canonical page-data script
+     * even when the outer document shell belongs to another integration.
+     */
+    private buildNonReactDocumentProps;
+    /**
+     * 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;
+    buildPageBrowserGraph(pagePath: string): Promise<{
+        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 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>;
 }