@ecopages/react 0.2.0-alpha.14 → 0.2.0-alpha.15

package/src/react.plugin.d.ts

@@ -1,92 +1,10 @@
-/**
- * This module contains the react plugin for Ecopages
- * @module
- */
 import { IntegrationPlugin } from '@ecopages/core/plugins/integration-plugin';
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
 import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
-import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
-import type { CompileOptions } from '@mdx-js/mdx';
 import type React from 'react';
 import { ReactRenderer } from './react-renderer.js';
-import type { ReactRouterAdapter } from './router-adapter.js';
-/**
- * MDX configuration options for the React plugin
- */
-export type ReactMdxOptions = {
-    /**
-     * Whether to enable MDX support.
-     * @default false
-     */
-    enabled: boolean;
-    /**
-     * Compiler options for MDX.
-     * @default undefined
-     */
-    compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
-    /**
-     * Remark plugins.
-     * @default undefined
-     */
-    remarkPlugins?: CompileOptions['remarkPlugins'];
-    /**
-     * Rehype plugins.
-     * @default undefined
-     */
-    rehypePlugins?: CompileOptions['rehypePlugins'];
-    /**
-     * Recma plugins.
-     * @default undefined
-     */
-    recmaPlugins?: CompileOptions['recmaPlugins'];
-    /**
-     * Custom extensions to be treated as MDX files.
-     * @default ['.mdx']
-     */
-    extensions?: string[];
-};
-/**
- * Options for the React plugin
- */
-export type ReactPluginOptions = {
-    extensions?: string[];
-    dependencies?: AssetDefinition[];
-    /**
-     * Enables explicit client graph mode for React page entries.
-     *
-     * When enabled, React page-entry bundling relies on explicit dependency declarations
-     * and skips AST-based `middleware`/`requires` stripping in the React path.
-     * @default false
-     */
-    explicitGraph?: boolean;
-    /**
-     * Router adapter for SPA navigation.
-     * When provided, pages with layouts will be wrapped in the router for client-side navigation.
-     * @example
-     * ```ts
-     * import { ecoRouter } from '@ecopages/react-router';
-     * reactPlugin({ router: ecoRouter() })
-     * ```
-     */
-    router?: ReactRouterAdapter;
-    /**
-     * MDX configuration for handling .mdx files within the React plugin.
-     * When enabled, MDX files are treated as React pages with full router support.
-     * @example
-     * ```ts
-     * reactPlugin({
-     *   router: ecoRouter(),
-     *   mdx: {
-     *     enabled: true,
-     *     extensions: ['.mdx', '.md'],
-     *     remarkPlugins: [remarkGfm],
-     *     rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
-     *   }
-     * })
-     * ```
-     */
-    mdx?: ReactMdxOptions;
-};
+import type { ReactPluginOptions } from './react.types.js';
+export type { ReactMdxOptions, ReactPluginOptions, ReactRendererConfig } from './react.types.js';
 /**
  * The name of the React plugin
  */
@@ -97,19 +15,30 @@ export declare const PLUGIN_NAME = "react";
  */
 export declare class ReactPlugin extends IntegrationPlugin<React.JSX.Element> {
     renderer: typeof ReactRenderer;
-    routerAdapter: ReactRouterAdapter | undefined;
-    private mdxEnabled;
-    private mdxCompilerOptions?;
-    private mdxExtensions;
+    private readonly routerAdapter;
+    private readonly mdxEnabled;
+    private readonly mdxCompilerOptions?;
+    private readonly mdxExtensions;
     private mdxLoaderPlugin;
-    private runtimeBundleService;
+    private readonly runtimeBundleService;
     private readonly hmrPageMetadataCache;
     private runtimeDependenciesInitialized;
     /**
      * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
      */
-    private explicitGraphEnabled;
-    constructor(options?: Omit<ReactPluginOptions, 'name'>);
+    private readonly explicitGraphEnabled;
+    private readonly rendererConfig;
+    constructor(options?: ReactPluginOptions);
+    /**
+     * Creates a React renderer with instance-owned runtime configuration.
+     *
+     * React renderers depend on plugin-owned router, MDX, and HMR metadata state.
+     * Keeping that state on the instance avoids cross-plugin static mutation while
+     * preserving the same runtime services the base initializer wires up.
+     */
+    initializeRenderer(options?: {
+        rendererModules?: unknown;
+    }): ReactRenderer;
     private ensureRuntimeDependencies;
     get plugins(): EcoBuildPlugin[];
     /**

package/src/react.plugin.js

@@ -6,6 +6,59 @@ import { ReactRuntimeBundleService } from "./services/react-runtime-bundle.servi
 import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-cache.js";
 const appLogger = new Logger("[ReactPlugin]");
 const PLUGIN_NAME = "react";
+const mergePluginLists = (...lists) => {
+  const merged = lists.flatMap((list) => list ? [...list] : []);
+  return merged.length > 0 ? merged : void 0;
+};
+const appendMdxExtensions = (target, mdxExtensions) => {
+  for (const extension of mdxExtensions) {
+    if (!target.includes(extension)) {
+      target.push(extension);
+    }
+  }
+};
+const resolveReactMdxCompilerOptions = (mdxOptions) => {
+  const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = mdxOptions;
+  const resolved = {
+    ...compilerOptions,
+    jsxImportSource: "react",
+    jsxRuntime: "automatic",
+    development: process.env.NODE_ENV === "development"
+  };
+  const mergedRemark = mergePluginLists(compilerOptions?.remarkPlugins, remarkPlugins);
+  const mergedRehype = mergePluginLists(compilerOptions?.rehypePlugins, rehypePlugins);
+  const mergedRecma = mergePluginLists(compilerOptions?.recmaPlugins, recmaPlugins);
+  if (mergedRemark) resolved.remarkPlugins = mergedRemark;
+  if (mergedRehype) resolved.rehypePlugins = mergedRehype;
+  if (mergedRecma) resolved.recmaPlugins = mergedRecma;
+  return resolved;
+};
+const resolveReactPluginOptions = (options) => {
+  const { extensions: userExtensions, router, mdx, explicitGraph, dependencies, ...baseConfig } = options ?? {};
+  const extensions = [...userExtensions ?? [".tsx"]];
+  const mdxEnabled = mdx?.enabled ?? false;
+  const mdxExtensions = mdx?.extensions ?? [".mdx"];
+  if (mdxEnabled) {
+    appendMdxExtensions(extensions, mdxExtensions);
+  } else if (mdx?.extensions?.length) {
+    appLogger.warn(
+      "MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support."
+    );
+  }
+  const rendererConfig = {
+    routerAdapter: router,
+    mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : void 0,
+    mdxExtensions,
+    hmrPageMetadataCache: new ReactHmrPageMetadataCache(),
+    explicitGraphEnabled: explicitGraph ?? false
+  };
+  return {
+    ...baseConfig,
+    extensions,
+    integrationDependencies: dependencies,
+    rendererConfig
+  };
+};
 class ReactPlugin extends IntegrationPlugin {
   renderer = ReactRenderer;
   routerAdapter;
@@ -14,58 +67,55 @@ class ReactPlugin extends IntegrationPlugin {
   mdxExtensions;
   mdxLoaderPlugin;
   runtimeBundleService;
-  hmrPageMetadataCache = new ReactHmrPageMetadataCache();
+  hmrPageMetadataCache;
   runtimeDependenciesInitialized = false;
   /**
    * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
    */
   explicitGraphEnabled;
+  rendererConfig;
   constructor(options) {
-    const { extensions: _ignoredExtensions, ...restOptions } = options ?? {};
-    const extensions = [...options?.extensions ?? [".tsx"]];
-    const mdxExtensions = options?.mdx?.extensions ?? [".mdx"];
-    if (options?.mdx?.enabled) {
-      for (const extension of mdxExtensions) {
-        if (!extensions.includes(extension)) {
-          extensions.push(extension);
-        }
-      }
-    } else if (options?.mdx?.extensions?.length) {
-      appLogger.warn(
-        "MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support."
-      );
-    }
+    const config = resolveReactPluginOptions(options);
+    const { extensions, rendererConfig, integrationDependencies, ...baseConfig } = config;
     super({
       name: PLUGIN_NAME,
       extensions,
       jsxImportSource: "react",
-      ...restOptions
+      integrationDependencies,
+      ...baseConfig
     });
-    this.mdxEnabled = options?.mdx?.enabled ?? false;
-    this.mdxExtensions = mdxExtensions;
+    this.routerAdapter = rendererConfig.routerAdapter;
+    this.mdxCompilerOptions = rendererConfig.mdxCompilerOptions;
+    this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
+    this.mdxExtensions = rendererConfig.mdxExtensions ?? [".mdx"];
+    this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new ReactHmrPageMetadataCache();
+    this.explicitGraphEnabled = rendererConfig.explicitGraphEnabled ?? false;
+    this.rendererConfig = {
+      ...rendererConfig,
+      mdxExtensions: this.mdxExtensions,
+      hmrPageMetadataCache: this.hmrPageMetadataCache,
+      explicitGraphEnabled: this.explicitGraphEnabled
+    };
     if (this.mdxEnabled) {
-      const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = options?.mdx || {};
-      this.mdxCompilerOptions = {
-        ...compilerOptions,
-        remarkPlugins: [...compilerOptions?.remarkPlugins || [], ...remarkPlugins || []],
-        rehypePlugins: [...compilerOptions?.rehypePlugins || [], ...rehypePlugins || []],
-        recmaPlugins: [...compilerOptions?.recmaPlugins || [], ...recmaPlugins || []],
-        jsxImportSource: "react",
-        jsxRuntime: "automatic",
-        development: process.env.NODE_ENV === "development"
-      };
       appLogger.debug("MDX mode enabled with React jsx runtime");
     }
-    this.routerAdapter = options?.router;
     this.runtimeBundleService = new ReactRuntimeBundleService({
       routerAdapter: this.routerAdapter
     });
-    this.explicitGraphEnabled = options?.explicitGraph ?? false;
-    ReactRenderer.routerAdapter = this.routerAdapter;
-    ReactRenderer.mdxCompilerOptions = this.mdxCompilerOptions;
-    ReactRenderer.mdxExtensions = this.mdxExtensions;
-    ReactRenderer.explicitGraphEnabled = this.explicitGraphEnabled;
-    ReactRenderer.hmrPageMetadataCache = this.hmrPageMetadataCache;
+  }
+  /**
+   * Creates a React renderer with instance-owned runtime configuration.
+   *
+   * React renderers depend on plugin-owned router, MDX, and HMR metadata state.
+   * Keeping that state on the instance avoids cross-plugin static mutation while
+   * preserving the same runtime services the base initializer wires up.
+   */
+  initializeRenderer(options) {
+    const renderer = new this.renderer({
+      ...this.createRendererOptions(options),
+      reactConfig: this.rendererConfig
+    });
+    return this.attachRendererRuntimeServices(renderer);
   }
   ensureRuntimeDependencies() {
     if (this.runtimeDependenciesInitialized) {

package/src/react.types.d.ts

@@ -0,0 +1,88 @@
+import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+import type { CompileOptions } from '@mdx-js/mdx';
+import type { ReactRouterAdapter } from './router-adapter.js';
+import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
+/**
+ * MDX configuration options for the React plugin.
+ */
+export type ReactMdxOptions = {
+    /**
+     * Whether to enable MDX support.
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Compiler options for MDX.
+     * @default undefined
+     */
+    compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
+    /**
+     * Remark plugins.
+     * @default undefined
+     */
+    remarkPlugins?: CompileOptions['remarkPlugins'];
+    /**
+     * Rehype plugins.
+     * @default undefined
+     */
+    rehypePlugins?: CompileOptions['rehypePlugins'];
+    /**
+     * Recma plugins.
+     * @default undefined
+     */
+    recmaPlugins?: CompileOptions['recmaPlugins'];
+    /**
+     * Custom extensions to be treated as MDX files.
+     * @default ['.mdx']
+     */
+    extensions?: string[];
+};
+/**
+ * Options for the React plugin.
+ */
+export type ReactPluginOptions = {
+    extensions?: string[];
+    dependencies?: AssetDefinition[];
+    /**
+     * Enables explicit client graph mode for React page entries.
+     *
+     * When enabled, React page-entry bundling relies on explicit dependency declarations
+     * and skips AST-based `middleware`/`requires` stripping in the React path.
+     * @default false
+     */
+    explicitGraph?: boolean;
+    /**
+     * Router adapter for SPA navigation.
+     * When provided, pages with layouts will be wrapped in the router for client-side navigation.
+     * @example
+     * ```ts
+     * import { ecoRouter } from '@ecopages/react-router';
+     * reactPlugin({ router: ecoRouter() })
+     * ```
+     */
+    router?: ReactRouterAdapter;
+    /**
+     * MDX configuration for handling .mdx files within the React plugin.
+     * When enabled, MDX files are treated as React pages with full router support.
+     * @example
+     * ```ts
+     * reactPlugin({
+     *   router: ecoRouter(),
+     *   mdx: {
+     *     enabled: true,
+     *     extensions: ['.mdx', '.md'],
+     *     remarkPlugins: [remarkGfm],
+     *     rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
+     *   }
+     * })
+     * ```
+     */
+    mdx?: ReactMdxOptions;
+};
+export type ReactRendererConfig = {
+    routerAdapter?: ReactRouterAdapter;
+    mdxCompilerOptions?: CompileOptions;
+    mdxExtensions?: string[];
+    hmrPageMetadataCache?: ReactHmrPageMetadataCache;
+    explicitGraphEnabled?: boolean;
+};

package/src/services/react-mdx-config-dependency.service.d.ts

@@ -0,0 +1,36 @@
+import type { EcoComponent, EcoComponentConfig } from '@ecopages/core';
+import { type AssetProcessingService, type ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
+import type { ReactPageModuleService } from './react-page-module.service.js';
+type MdxConfigDependencyProcessor = (components: Partial<EcoComponent>[]) => Promise<ProcessedAsset[]>;
+export interface ReactMdxConfigDependencyServiceConfig {
+    integrationName: string;
+    pageModuleService: Pick<ReactPageModuleService, 'ensureConfigFileMetadata'>;
+    assetProcessingService?: Pick<AssetProcessingService, 'processDependencies'>;
+}
+/**
+ * Resolves MDX-owned config dependencies that live outside the normal React component tree.
+ *
+ * React MDX pages can declare dependencies on the page config itself or on a
+ * resolved layout config. Those roots need to be materialized as synthetic
+ * component configs so the shared dependency pipeline can process them without
+ * growing more MDX-specific logic inside the renderer.
+ */
+export declare class ReactMdxConfigDependencyService {
+    private readonly config;
+    constructor(config: ReactMdxConfigDependencyServiceConfig);
+    /**
+     * Processes MDX-owned config dependencies and eagerly emits any SSR-marked lazy scripts.
+     */
+    processMdxConfigDependencies(options: {
+        pagePath: string;
+        config?: EcoComponentConfig;
+        processComponentDependencies: MdxConfigDependencyProcessor;
+    }): Promise<ProcessedAsset[]>;
+    private createOwnedConfigComponents;
+    private processDeclaredSsrLazyDependencies;
+    /**
+     * Collects `lazy` script dependencies that also opt into SSR from an MDX config graph.
+     */
+    private collectDeclaredSsrLazyDependencies;
+}
+export {};

package/src/services/react-mdx-config-dependency.service.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { rapidhash } from "@ecopages/core/hash";
+import {
+  AssetFactory
+} from "@ecopages/core/services/asset-processing-service";
+import { collectFromConfigForest, getComponentConfigs } from "../utils/component-config-traversal.js";
+class ReactMdxConfigDependencyService {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Processes MDX-owned config dependencies and eagerly emits any SSR-marked lazy scripts.
+   */
+  async processMdxConfigDependencies(options) {
+    const components = this.createOwnedConfigComponents(options.pagePath, options.config);
+    if (components.length === 0) {
+      return [];
+    }
+    const processedDependencies = await options.processComponentDependencies(components);
+    const eagerSsrLazyDependencies = await this.processDeclaredSsrLazyDependencies(components, options.pagePath);
+    return [...processedDependencies, ...eagerSsrLazyDependencies];
+  }
+  createOwnedConfigComponents(pagePath, config) {
+    const components = [];
+    const resolvedLayout = config?.layout;
+    if (resolvedLayout?.config?.dependencies) {
+      const layoutConfig = this.config.pageModuleService.ensureConfigFileMetadata(
+        resolvedLayout.config,
+        pagePath
+      );
+      components.push({ config: layoutConfig });
+    }
+    if (config?.dependencies) {
+      components.push({
+        config: {
+          ...config,
+          __eco: {
+            id: rapidhash(pagePath).toString(36),
+            file: pagePath,
+            integration: this.config.integrationName
+          }
+        }
+      });
+    }
+    return components;
+  }
+  async processDeclaredSsrLazyDependencies(components, pagePath) {
+    if (!this.config.assetProcessingService?.processDependencies) {
+      return [];
+    }
+    const dependencies = this.collectDeclaredSsrLazyDependencies(components);
+    if (dependencies.length === 0) {
+      return [];
+    }
+    return this.config.assetProcessingService.processDependencies(
+      dependencies,
+      `${this.config.integrationName}-mdx-ssr-lazy:${pagePath}`
+    );
+  }
+  /**
+   * Collects `lazy` script dependencies that also opt into SSR from an MDX config graph.
+   */
+  collectDeclaredSsrLazyDependencies(components) {
+    const dependencies = [];
+    const seenKeys = /* @__PURE__ */ new Set();
+    const normalizeAttributes = (attributes) => ({
+      type: "module",
+      defer: "",
+      ...attributes ?? {}
+    });
+    collectFromConfigForest(getComponentConfigs(components), (config) => {
+      const componentFile = config.__eco?.file;
+      if (!componentFile) {
+        return [];
+      }
+      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
+          })
+        );
+      }
+      return [];
+    });
+    return dependencies;
+  }
+}
+export {
+  ReactMdxConfigDependencyService
+};

package/src/services/react-page-module.service.d.ts

@@ -43,7 +43,10 @@ export declare class ReactPageModuleService {
      * @param filePath - Absolute path to the MDX file
      * @returns The imported module
      */
-    importMdxPageFile(filePath: string): Promise<unknown>;
+    importMdxPageFile(filePath: string, options?: {
+        bypassCache?: boolean;
+        cacheScope?: string;
+    }): Promise<unknown>;
     /**
      * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
      * Resolves the file path from dependency declarations when not already set.
@@ -57,7 +60,7 @@ export declare class ReactPageModuleService {
      * Recursively checks whether a component config tree declares any browser modules.
      * Used to determine if a page needs hydration.
      */
-    hasModulesInConfig(config: EcoComponentConfig | undefined, visited?: Set<EcoComponentConfig>): boolean;
+    hasModulesInConfig(config: EcoComponentConfig | undefined): boolean;
     /**
      * Determines whether a page needs client-side hydration.
      *

package/src/services/react-page-module.service.js

@@ -3,6 +3,7 @@ import { pathToFileURL } from "node:url";
 import { rapidhash } from "@ecopages/core/hash";
 import { build } from "@ecopages/core/build/build-adapter";
 import { fileSystem } from "@ecopages/file-system";
+import { someInConfigTree } from "../utils/component-config-traversal.js";
 import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
 class ReactPageModuleService {
   config;
@@ -23,7 +24,7 @@ class ReactPageModuleService {
    * @param filePath - Absolute path to the MDX file
    * @returns The imported module
    */
-  async importMdxPageFile(filePath) {
+  async importMdxPageFile(filePath, options) {
     const { createReactMdxLoaderPlugin } = await import("../utils/react-mdx-loader-plugin.js");
     const mdxPlugin = createReactMdxLoaderPlugin(
       this.config.mdxCompilerOptions ?? {
@@ -35,8 +36,9 @@ class ReactPageModuleService {
     const outdir = path.join(this.config.workDir, ".server-modules-react-mdx");
     const fileBaseName = path.basename(filePath, path.extname(filePath));
     const fileHash = fileSystem.hash(filePath);
-    const cacheBuster = process?.env?.NODE_ENV === "development" ? `-${Date.now()}` : "";
-    const outputFileName = `${fileBaseName}-${fileHash}${cacheBuster}.js`;
+    const cacheScopeSuffix = options?.cacheScope ? `-${sanitizeCacheScope(options.cacheScope)}` : "";
+    const cacheBuster = options?.bypassCache || process?.env?.NODE_ENV === "development" ? `-${Date.now()}` : "";
+    const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${cacheBuster}.js`;
     const buildResult = await build(
       {
         entrypoints: [filePath],
@@ -62,9 +64,16 @@ class ReactPageModuleService {
     if (!compiledOutput) {
       throw new Error(`No compiled MDX output generated for page: ${filePath}`);
     }
+    const compiledOutputUrl = pathToFileURL(compiledOutput);
+    if (process?.env?.NODE_ENV === "development" || options?.cacheScope) {
+      compiledOutputUrl.searchParams.set(
+        "update",
+        [fileHash, options?.cacheScope ? sanitizeCacheScope(options.cacheScope) : void 0].filter((value) => value !== void 0).join("-")
+      );
+    }
     return await import(
       /* @vite-ignore */
-      pathToFileURL(compiledOutput).href
+      compiledOutputUrl.href
     );
   }
   /**
@@ -112,23 +121,11 @@ class ReactPageModuleService {
    * Recursively checks whether a component config tree declares any browser modules.
    * Used to determine if a page needs hydration.
    */
-  hasModulesInConfig(config, visited = /* @__PURE__ */ new Set()) {
-    if (!config || visited.has(config)) {
-      return false;
-    }
-    visited.add(config);
-    if (config.dependencies?.modules?.some((entry) => entry.trim().length > 0)) {
-      return true;
-    }
-    if (config.layout?.config && this.hasModulesInConfig(config.layout.config, visited)) {
-      return true;
-    }
-    for (const component of config.dependencies?.components ?? []) {
-      if (this.hasModulesInConfig(component.config, visited)) {
-        return true;
-      }
-    }
-    return false;
+  hasModulesInConfig(config) {
+    return someInConfigTree(
+      config,
+      (node) => node.dependencies?.modules?.some((entry) => entry.trim().length > 0) ?? false
+    );
   }
   /**
    * Determines whether a page needs client-side hydration.
@@ -157,6 +154,9 @@ class ReactPageModuleService {
     return Array.from(new Set(declarations));
   }
 }
+function sanitizeCacheScope(cacheScope) {
+  return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
 export {
   ReactPageModuleService
 };

package/src/services/react-page-payload.service.d.ts

@@ -0,0 +1,46 @@
+import type { HtmlTemplateProps, IntegrationRendererRenderOptions, RequestLocals } from '@ecopages/core';
+import type { ReactNode } from 'react';
+type PagePayloadOptions = {
+    pageProps?: HtmlTemplateProps['pageProps'];
+    params: IntegrationRendererRenderOptions<ReactNode>['params'];
+    query: IntegrationRendererRenderOptions<ReactNode>['query'];
+    safeLocals?: RequestLocals;
+};
+/**
+ * Builds the serialized page payload React exposes to document shells and the browser.
+ *
+ * This keeps hydration payload shaping away from the renderer so the renderer can
+ * stay focused on component orchestration instead of data serialization rules.
+ */
+export declare class ReactPagePayloadService {
+    /**
+     * 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 shared document payload consistently.
+     */
+    buildRouterPageDataScript(pageProps: HtmlTemplateProps['pageProps'] | undefined): string;
+    /**
+     * 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: PagePayloadOptions): HtmlTemplateProps['pageProps'];
+    /**
+     * 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.
+     */
+    getSerializableLocals(locals: RequestLocals | undefined, requiredLocals?: string | readonly string[]): RequestLocals | undefined;
+}
+export {};