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

package/src/services/react-hydration-asset.service.js

@@ -4,111 +4,108 @@ import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
 import {
   AssetFactory
 } from "@ecopages/core/services/asset-processing-service";
-import { createHydrationScript } from "../utils/hydration-scripts.js";
-import { createIslandHydrationScript } from "../utils/hydration-scripts.js";
+import { createHydrationScript, createIslandHydrationScript } from "../utils/hydration-scripts.js";
 import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
+function getReactIslandComponentKey(componentFile, config) {
+  return rapidhash(`${componentFile}:${config?.__eco?.id ?? ""}`).toString();
+}
 class ReactHydrationAssetService {
+  config;
+  static ROUTER_PAGE_GROUPED_BUNDLE_ID = "ecopages-react-router-pages";
   constructor(config) {
     this.config = config;
   }
+  getIslandBundleName(componentFile) {
+    return `ecopages-react-island-${rapidhash(componentFile)}`;
+  }
+  getIslandHydrationName(bundleName, componentKey) {
+    return `${bundleName}-hydration-${componentKey}`;
+  }
+  getRouterPageGroupedEntryName(pagePath) {
+    const relativePath = path.relative(this.config.srcDir, pagePath);
+    return relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, "").replace(/[\\/]+/g, "__").replace(/\[([^\]]+)\]/g, "_$1_");
+  }
   /**
-   * Resolves the import path for the bundled page component.
+   * Resolves the browser import path used for a React-owned page or island module.
    * Uses HMR manager for development or constructs static path for production.
    *
    * @param pagePath - Absolute path to the page source file
-   * @param componentName - Generated unique component name
-   * @returns The resolved import path for the bundled component
+   * @param assetName - Generated asset name
+   * @returns The resolved browser import path for the module
    */
-  async resolveAssetImportPath(pagePath, componentName) {
+  async resolveAssetImportPath(pagePath, assetName) {
     const hmrManager = this.config.assetProcessingService?.getHmrManager();
     if (hmrManager?.isEnabled()) {
       return hmrManager.registerEntrypoint(pagePath);
     }
-    return `/${path.join(RESOLVED_ASSETS_DIR, path.relative(this.config.srcDir, pagePath)).replace(path.basename(pagePath), `${componentName}.js`).replace(/\\/g, "/")}`;
+    return `/${path.join(RESOLVED_ASSETS_DIR, path.relative(this.config.srcDir, pagePath)).replace(path.basename(pagePath), `${assetName}.js`).replace(/\\/g, "/")}`;
   }
   /**
-   * Creates the asset dependencies for a page: the bundled component and hydration script.
+   * Creates the page-owned route entry asset for hydration and client navigation.
    *
    * @param pagePath - Absolute path to the page source file
    * @param componentName - Generated unique component name
-   * @param importPath - Resolved import path for the bundled component
+   * @param importPath - Resolved browser import path used by development HMR
    * @param bundleOptions - Bundle configuration options
    * @param isDevelopment - Whether running in development mode with HMR
    * @param isMdx - Whether the source file is an MDX file
-   * @param props - Optional page props for client serialization
-   * @returns Array of asset definitions for processing
+   * @returns One page-owned asset definition for processing
    */
-  createPageDependencies(pagePath, componentName, importPath, bundleOptions, isDevelopment, isMdx, props) {
+  createPageDependencies(pagePath, componentName, importPath, pageModuleUrlExpression, bundleOptions, isDevelopment, useBrowserRuntimeImports, isMdx) {
     const runtimeImports = this.config.bundleService.getRuntimeImports();
-    const dependencies = [
-      AssetFactory.createFileScript({
-        position: "head",
-        filepath: pagePath,
-        name: componentName,
-        excludeFromHtml: true,
-        bundle: true,
-        bundleOptions,
-        attributes: {
-          type: "module",
-          defer: "",
-          "data-eco-persist": "true"
-        }
-      })
-    ];
-    if (props && Object.keys(props).length > 0) {
-      dependencies.push(
-        AssetFactory.createContentScript({
-          position: "head",
-          content: `window.__ECO_PAGE__={module:"${importPath}",props:${JSON.stringify(props)}};`,
-          name: `${componentName}-props`,
-          bundle: false,
-          attributes: {
-            type: "module"
-          }
-        })
-      );
-    }
-    dependencies.push(
+    const groupedBundle = this.config.routerAdapter ? {
+      id: ReactHydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
+      entryName: this.getRouterPageGroupedEntryName(pagePath)
+    } : void 0;
+    return [
       AssetFactory.createContentScript({
         position: "head",
         content: createHydrationScript({
-          importPath,
-          reactImportPath: runtimeImports.react,
-          reactDomClientImportPath: runtimeImports.reactDomClient,
-          routerImportPath: runtimeImports.router,
+          importPath: isDevelopment ? importPath : pagePath,
+          pageModuleUrlExpression,
+          reactImportPath: useBrowserRuntimeImports ? runtimeImports.react : "react",
+          reactDomClientImportPath: useBrowserRuntimeImports ? runtimeImports.reactDomClient : "react-dom/client",
+          routerImportPath: useBrowserRuntimeImports ? runtimeImports.router : this.config.routerAdapter?.bundle.importPath,
           isDevelopment,
           isMdx,
-          router: this.config.routerAdapter
+          router: this.config.routerAdapter,
+          scriptId: componentName
         }),
-        name: `${componentName}-hydration`,
-        bundle: false,
+        name: componentName,
+        packageRole: "page-script",
+        bundle: !isDevelopment,
+        groupedBundle,
+        bundleOptions,
         attributes: {
           type: "module",
           defer: "",
           "data-eco-rerun": "true",
-          "data-eco-script-id": `${componentName}-hydration`,
+          "data-eco-script-id": componentName,
+          ...this.config.routerAdapter ? { "data-eco-page-bootstrap": "react-router" } : {},
           "data-eco-persist": "true"
         }
       })
-    );
-    return dependencies;
+    ];
   }
   /**
    * Builds client-side assets for a React component island.
    *
-   * Includes the bundled component entry and an inline hydration bootstrap script.
+   * Includes the bundled component entry and a shared hydration bootstrap script.
    *
    * @param componentFile - Absolute path to the component source file
-   * @param componentInstanceId - Unique instance ID for DOM targeting
-   * @param props - Serialized props for client-side hydration
    * @param config - Optional component config with `__eco` metadata
    * @returns Processed assets ready for injection
    */
-  async buildComponentRenderAssets(componentFile, componentInstanceId, props, config) {
-    const componentName = `ecopages-react-island-${rapidhash(`${componentFile}:${componentInstanceId}`)}`;
-    const importPath = await this.resolveAssetImportPath(componentFile, componentName);
+  async buildComponentRenderAssets(componentFile, config) {
+    const componentName = this.getIslandBundleName(componentFile);
+    const componentKey = getReactIslandComponentKey(componentFile, config);
+    const hydrationName = this.getIslandHydrationName(componentName, componentKey);
     const hmrManager = this.config.assetProcessingService?.getHmrManager();
     const isDevelopment = hmrManager?.isEnabled() ?? false;
+    if (isDevelopment) {
+      this.config.hmrPageMetadataCache?.markOwnedEntrypoint(componentFile);
+    }
+    const importPath = await this.resolveAssetImportPath(componentFile, componentName);
     const declaredModules = collectDeclaredModulesInConfig(config);
     const bundleOptions = await this.config.bundleService.createBundleOptions(
       componentName,
@@ -121,6 +118,7 @@ class ReactHydrationAssetService {
         position: "head",
         filepath: componentFile,
         name: componentName,
+        packageRole: "dynamic-chunk",
         excludeFromHtml: true,
         bundle: true,
         bundleOptions,
@@ -134,21 +132,22 @@ class ReactHydrationAssetService {
         position: "head",
         content: createIslandHydrationScript({
           importPath,
+          scriptId: hydrationName,
           reactImportPath: runtimeImports.react,
           reactDomClientImportPath: runtimeImports.reactDomClient,
-          targetSelector: `[data-eco-component-id="${componentInstanceId}"]`,
-          props,
+          targetSelector: `[data-eco-component-key="${componentKey}"]`,
           componentRef: config?.__eco?.id,
           componentFile,
           isDevelopment
         }),
-        name: `${componentName}-hydration`,
+        name: hydrationName,
+        packageRole: "keep-separate",
         bundle: false,
         attributes: {
           type: "module",
           defer: "",
           "data-eco-rerun": "true",
-          "data-eco-script-id": `${componentName}-hydration`,
+          "data-eco-script-id": hydrationName,
           "data-eco-persist": "true"
         }
       })
@@ -159,34 +158,53 @@ class ReactHydrationAssetService {
     return this.config.assetProcessingService.processDependencies(dependencies, componentName);
   }
   /**
-   * Builds all client-side route assets for a page.
+   * Creates the Page Browser Graph dependency declarations for a React page.
    *
    * @param pagePath - Absolute file path of the page
    * @param isMdx - Whether the page is an MDX file
    * @param declaredModules - Explicitly declared browser module specifiers
-   * @returns Processed assets for the route
+   * @returns Declarative assets for core-owned processing
    */
-  async buildRouteRenderAssets(pagePath, isMdx, declaredModules) {
+  async createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules) {
     const componentName = `ecopages-react-${rapidhash(pagePath)}`;
     const hmrManager = this.config.assetProcessingService?.getHmrManager();
     const isDevelopment = hmrManager?.isEnabled() ?? false;
+    const isHostedDevelopment = !isDevelopment && process.env.NODE_ENV !== "production";
+    const usesRouterRuntime = Boolean(this.config.routerAdapter);
+    const useBrowserRuntimeImports = isDevelopment || isHostedDevelopment || usesRouterRuntime;
     if (isDevelopment) {
       this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
     }
     const importPath = await this.resolveAssetImportPath(pagePath, componentName);
+    const pageModuleUrlExpression = isDevelopment ? JSON.stringify(importPath) : "import.meta.url";
     const bundleOptions = await this.config.bundleService.createBundleOptions(
       componentName,
       isMdx,
-      declaredModules
+      declaredModules,
+      { includeRuntime: !useBrowserRuntimeImports, splitting: usesRouterRuntime }
     );
     const dependencies = this.createPageDependencies(
       pagePath,
       componentName,
       importPath,
+      pageModuleUrlExpression,
       bundleOptions,
       isDevelopment,
+      useBrowserRuntimeImports,
       isMdx
     );
+    return dependencies;
+  }
+  /**
+   * Builds the Page Browser Graph assets for a React page.
+   *
+   * @remarks
+   * Kept as a compatibility wrapper while callers migrate to core-owned page
+   * graph assembly.
+   */
+  async buildPageBrowserGraphAssets(pagePath, isMdx, declaredModules) {
+    const componentName = `ecopages-react-${rapidhash(pagePath)}`;
+    const dependencies = await this.createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules);
     if (!this.config.assetProcessingService) {
       throw new Error("AssetProcessingService is not set");
     }
@@ -194,5 +212,6 @@ class ReactHydrationAssetService {
   }
 }
 export {
-  ReactHydrationAssetService
+  ReactHydrationAssetService,
+  getReactIslandComponentKey
 };

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

@@ -7,6 +7,7 @@
  * @module
  */
 import type { EcoComponentConfig, EcoPageFile } from '@ecopages/core';
+import type { BuildExecutor } from '@ecopages/core/build/build-adapter';
 import type { CompileOptions } from '@mdx-js/mdx';
 /**
  * Configuration for the ReactPageModuleService.
@@ -14,6 +15,8 @@ import type { CompileOptions } from '@mdx-js/mdx';
 export interface ReactPageModuleServiceConfig {
     rootDir: string;
     distDir: string;
+    workDir: string;
+    buildExecutor: BuildExecutor;
     layoutsDir?: string;
     componentsDir?: string;
     mdxCompilerOptions?: CompileOptions;
@@ -40,7 +43,12 @@ 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<EcoPageFile<{
+        config?: EcoComponentConfig;
+    }>>;
     /**
      * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
      * Resolves the file path from dependency declarations when not already set.
@@ -54,7 +62,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

@@ -1,10 +1,13 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { rapidhash } from "@ecopages/core/hash";
-import { defaultBuildAdapter } from "@ecopages/core/build/build-adapter";
+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";
+import { createReactMdxLoaderPlugin } from "../utils/react-mdx-loader-plugin.js";
 class ReactPageModuleService {
+  config;
   constructor(config) {
     this.config = config;
   }
@@ -22,8 +25,7 @@ class ReactPageModuleService {
    * @param filePath - Absolute path to the MDX file
    * @returns The imported module
    */
-  async importMdxPageFile(filePath) {
-    const { createReactMdxLoaderPlugin } = await import("../utils/react-mdx-loader-plugin.js");
+  async importMdxPageFile(filePath, options) {
     const mdxPlugin = createReactMdxLoaderPlugin(
       this.config.mdxCompilerOptions ?? {
         jsxImportSource: "react",
@@ -31,34 +33,49 @@ class ReactPageModuleService {
         development: process?.env?.NODE_ENV === "development"
       }
     );
-    const outdir = path.join(this.config.distDir, ".server-modules-react-mdx");
+    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 buildResult = await defaultBuildAdapter.build({
-      entrypoints: [filePath],
-      root: this.config.rootDir,
-      outdir,
-      target: "node",
-      format: "esm",
-      sourcemap: "none",
-      splitting: false,
-      minify: false,
-      treeshaking: false,
-      naming: outputFileName,
-      plugins: [mdxPlugin]
-    });
+    const cacheScopeSuffix = options?.cacheScope ? `-${sanitizeCacheScope(options.cacheScope)}` : "";
+    const cacheBuster = options?.bypassCache || process?.env?.NODE_ENV === "development" ? `-${Date.now()}` : "";
+    const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${cacheBuster}.mjs`;
+    const outputNamingTemplate = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${cacheBuster}.[ext]`;
+    const buildResult = await build(
+      {
+        entrypoints: [filePath],
+        root: this.config.rootDir,
+        outdir,
+        target: "es2022",
+        format: "esm",
+        sourcemap: "none",
+        splitting: false,
+        minify: false,
+        treeshaking: false,
+        naming: outputNamingTemplate,
+        plugins: [mdxPlugin]
+      },
+      this.config.buildExecutor
+    );
     if (!buildResult.success) {
       const details = buildResult.logs.map((log) => log.message).join(" | ");
       throw new Error(`Failed to compile MDX 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;
+    const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => /\.(?:[cm]?js)$/u.test(output.path))?.path;
     if (!compiledOutput) {
       throw new Error(`No compiled MDX output generated for page: ${filePath}`);
     }
-    return await import(pathToFileURL(compiledOutput).href);
+    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 */
+      compiledOutputUrl.href
+    );
   }
   /**
    * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
@@ -91,7 +108,7 @@ class ReactPageModuleService {
         if (fileSystem.exists(resolvedDependency)) {
           return {
             ...config,
-            __eco: buildEcoMeta(resolvedDependency)
+            __eco: buildEcoMeta(path.join(candidateDir, path.basename(pagePath)))
           };
         }
       }
@@ -105,23 +122,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.
@@ -150,6 +155,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 {};