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

package/src/services/react-bundle.service.js

@@ -1,13 +1,24 @@
 import { createClientGraphBoundaryPlugin } from "../utils/client-graph-boundary-plugin.js";
+import {
+  buildReactRuntimeAliasMap,
+  getReactClientGraphAllowSpecifiers,
+  getReactRuntimeExternalSpecifiers
+} from "../utils/react-runtime-alias-map.js";
+import { createUseSyncExternalStoreShimPlugin } from "../utils/use-sync-external-store-shim-plugin.js";
+import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
+import { createForeignJsxOverridePlugin } from "@ecopages/core/plugins/foreign-jsx-override-plugin";
 import { ReactRuntimeBundleService } from "./react-runtime-bundle.service.js";
+import { createReactMdxLoaderPlugin } from "../utils/react-mdx-loader-plugin.js";
 class ReactBundleService {
+  runtimeBundleService;
+  config;
   constructor(config) {
     this.config = config;
     this.runtimeBundleService = new ReactRuntimeBundleService({
+      rootDir: config.rootDir,
       routerAdapter: config.routerAdapter
     });
   }
-  runtimeBundleService;
   /**
    * Returns resolved runtime import paths for the React runtime.
    */
@@ -22,39 +33,58 @@ class ReactBundleService {
    * @param declaredModules - Explicitly declared browser module specifiers
    * @returns Bundle options object for the build adapter
    */
-  async createBundleOptions(componentName, isMdx, declaredModules) {
+  async createBundleOptions(componentName, isMdx, declaredModules, bundleOptions = {}) {
     const runtimeImports = this.getRuntimeImports();
     const options = {
-      external: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"],
       mainFields: ["module", "browser", "main"],
       naming: `${componentName}.[ext]`,
       ...import.meta.env?.NODE_ENV === "production" && {
         minify: true,
-        splitting: false,
         treeshaking: true
-      }
+      },
+      ...bundleOptions.splitting === void 0 ? {} : { splitting: bundleOptions.splitting }
     };
+    if (!bundleOptions.includeRuntime) {
+      const reactRuntimeSpecifiers = new Set(getReactRuntimeExternalSpecifiers());
+      options.external = [
+        ...Object.values(runtimeImports).filter(
+          (specifier) => Boolean(specifier) && !reactRuntimeSpecifiers.has(
+            specifier
+          )
+        )
+      ];
+    }
     const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
       absWorkingDir: this.config.rootDir,
       declaredModules,
-      alwaysAllowSpecifiers: [
-        "@ecopages/core",
-        "react",
-        "react-dom",
-        "react/jsx-runtime",
-        "react/jsx-dev-runtime",
-        "react-dom/client",
-        ...this.config.routerAdapter ? [this.config.routerAdapter.importMapKey] : []
-      ]
+      alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers([], this.config.routerAdapter)
+    });
+    const foreignJsxOverridePlugin = createForeignJsxOverridePlugin({
+      name: "react-renderer-foreign-jsx-override",
+      hostJsxImportSource: this.config.jsxImportSource ?? "react",
+      foreignExtensions: this.config.nonReactExtensions ?? []
     });
-    const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeImports);
-    const useSyncExternalStoreShimPlugin = this.createSyncExternalStorePlugin();
+    const useSyncExternalStoreShimPlugin = createUseSyncExternalStoreShimPlugin({
+      name: "react-renderer-use-sync-external-store-shim",
+      namespace: "ecopages-react-renderer-shim"
+    });
+    const runtimePlugins = bundleOptions.includeRuntime ? [] : [this.createRuntimeAliasPlugin(buildReactRuntimeAliasMap(runtimeImports))];
     if (isMdx && this.config.mdxCompilerOptions) {
-      const { createReactMdxLoaderPlugin } = await import("../utils/react-mdx-loader-plugin.js");
       const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
-      options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin];
+      options.plugins = [
+        foreignJsxOverridePlugin,
+        graphBoundaryPlugin,
+        ...runtimePlugins,
+        mdxPlugin,
+        useSyncExternalStoreShimPlugin
+      ];
     } else {
-      options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, useSyncExternalStoreShimPlugin];
+      options.plugins = [
+        foreignJsxOverridePlugin,
+        graphBoundaryPlugin,
+        ...runtimePlugins,
+        useSyncExternalStoreShimPlugin
+      ];
     }
     return options;
   }
@@ -62,87 +92,8 @@ class ReactBundleService {
    * Creates the esbuild plugin that rewrites bare React specifiers
    * to their runtime asset URLs.
    */
-  createRuntimeAliasPlugin(runtimeImports) {
-    const aliases = /* @__PURE__ */ new Map([
-      ["react", runtimeImports.react],
-      ["react-dom/client", runtimeImports.reactDomClient],
-      ["react/jsx-runtime", runtimeImports.reactJsxRuntime],
-      ["react/jsx-dev-runtime", runtimeImports.reactJsxDevRuntime],
-      ["react-dom", runtimeImports.reactDom]
-    ]);
-    if (this.config.routerAdapter && runtimeImports.router) {
-      aliases.set(this.config.routerAdapter.importMapKey, runtimeImports.router);
-    }
-    const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const pattern = new RegExp(
-      `^(${Array.from(aliases.keys()).map((key) => escapeRegExp(key)).join("|")})$`
-    );
-    return {
-      name: "react-runtime-import-alias",
-      setup(build) {
-        build.onResolve({ filter: pattern }, (args) => {
-          const mappedPath = aliases.get(args.path);
-          if (!mappedPath) {
-            return void 0;
-          }
-          return {
-            path: mappedPath,
-            external: true
-          };
-        });
-      }
-    };
-  }
-  /**
-   * Redirects `use-sync-external-store/shim` imports to React's built-in
-   * `useSyncExternalStore`.
-   *
-   * Libraries like React Aria still list `use-sync-external-store` as a
-   * dependency to support React 16/17. On React 18+ the `/shim` export is
-   * already a pass-through, but without this plugin esbuild would bundle
-   * the full CJS shim (including `process.env` branching) into the browser
-   * bundle. The plugin short-circuits the resolution so only a single clean
-   * ESM re-export is emitted.
-   */
-  createSyncExternalStorePlugin() {
-    return {
-      name: "react-renderer-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-renderer-shim"
-        }));
-        build.onLoad(
-          { filter: /^use-sync-external-store\/shim$/, namespace: "ecopages-react-renderer-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"
-          })
-        );
-        build.onLoad(
-          {
-            filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.production\.js$/
-          },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-      }
-    };
+  createRuntimeAliasPlugin(runtimeAliasMap) {
+    return createRuntimeSpecifierAliasPlugin(runtimeAliasMap, { name: "react-runtime-import-alias" });
   }
 }
 export {

package/src/services/react-hmr-page-metadata-cache.d.ts

@@ -6,6 +6,11 @@
  */
 export declare class ReactHmrPageMetadataCache {
     private readonly declaredModulesByEntrypoint;
+    private readonly ownedEntrypoints;
+    /**
+     * Marks an HMR entrypoint as React-owned.
+     */
+    markOwnedEntrypoint(entrypointPath: string): void;
     /**
      * Stores the declared browser modules for a page entrypoint.
      */
@@ -14,4 +19,8 @@ export declare class ReactHmrPageMetadataCache {
      * Returns the last known declared browser modules for a page entrypoint.
      */
     getDeclaredModules(entrypointPath: string): string[] | undefined;
+    /**
+     * Returns true when the watched entrypoint is owned by the React integration.
+     */
+    ownsEntrypoint(entrypointPath: string): boolean;
 }

package/src/services/react-hmr-page-metadata-cache.js

@@ -1,18 +1,34 @@
+import path from "node:path";
 class ReactHmrPageMetadataCache {
   declaredModulesByEntrypoint = /* @__PURE__ */ new Map();
+  ownedEntrypoints = /* @__PURE__ */ new Set();
+  /**
+   * Marks an HMR entrypoint as React-owned.
+   */
+  markOwnedEntrypoint(entrypointPath) {
+    this.ownedEntrypoints.add(path.resolve(entrypointPath));
+  }
   /**
    * Stores the declared browser modules for a page entrypoint.
    */
   setDeclaredModules(entrypointPath, declaredModules) {
-    this.declaredModulesByEntrypoint.set(entrypointPath, [...declaredModules]);
+    const resolvedEntrypointPath = path.resolve(entrypointPath);
+    this.markOwnedEntrypoint(resolvedEntrypointPath);
+    this.declaredModulesByEntrypoint.set(resolvedEntrypointPath, [...declaredModules]);
   }
   /**
    * Returns the last known declared browser modules for a page entrypoint.
    */
   getDeclaredModules(entrypointPath) {
-    const declaredModules = this.declaredModulesByEntrypoint.get(entrypointPath);
+    const declaredModules = this.declaredModulesByEntrypoint.get(path.resolve(entrypointPath));
     return declaredModules ? [...declaredModules] : void 0;
   }
+  /**
+   * Returns true when the watched entrypoint is owned by the React integration.
+   */
+  ownsEntrypoint(entrypointPath) {
+    return this.ownedEntrypoints.has(path.resolve(entrypointPath));
+  }
 }
 export {
   ReactHmrPageMetadataCache

package/src/services/react-hydration-asset.service.d.ts

@@ -1,9 +1,8 @@
 /**
  * Hydration asset creation service for React integration.
  *
- * Builds the asset definitions (bundled component scripts + hydration bootstrap scripts)
- * required for client-side React rendering — both at the page level and the component
- * island level.
+ * Builds the asset definitions required for client-side React rendering — both at
+ * the page level and the component island level.
  *
  * @module
  */
@@ -23,53 +22,63 @@ export interface ReactHydrationAssetServiceConfig {
     bundleService: ReactBundleService;
     hmrPageMetadataCache?: ReactHmrPageMetadataCache;
 }
+export declare function getReactIslandComponentKey(componentFile: string, config?: EcoComponentConfig): string;
 /**
  * Manages the creation of client-side hydration assets for React pages and component islands.
  */
 export declare class ReactHydrationAssetService {
     private readonly config;
+    private static readonly ROUTER_PAGE_GROUPED_BUNDLE_ID;
     constructor(config: ReactHydrationAssetServiceConfig);
+    private getIslandBundleName;
+    private getIslandHydrationName;
+    private getRouterPageGroupedEntryName;
     /**
-     * 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
      */
-    resolveAssetImportPath(pagePath: string, componentName: string): Promise<string>;
+    resolveAssetImportPath(pagePath: string, assetName: string): Promise<string>;
     /**
-     * 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: string, componentName: string, importPath: string, bundleOptions: Record<string, unknown>, isDevelopment: boolean, isMdx: boolean, props?: Record<string, unknown>): AssetDefinition[];
+    createPageDependencies(pagePath: string, componentName: string, importPath: string, pageModuleUrlExpression: string, bundleOptions: Record<string, unknown>, isDevelopment: boolean, useBrowserRuntimeImports: boolean, isMdx: boolean): AssetDefinition[];
     /**
      * 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
      */
-    buildComponentRenderAssets(componentFile: string, componentInstanceId: string, props: Record<string, unknown>, config?: EcoComponentConfig): Promise<ProcessedAsset[]>;
+    buildComponentRenderAssets(componentFile: string, config?: EcoComponentConfig): Promise<ProcessedAsset[]>;
     /**
-     * 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
+     */
+    createPageBrowserGraphDependencies(pagePath: string, isMdx: boolean, declaredModules: string[]): Promise<AssetDefinition[]>;
+    /**
+     * 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.
      */
-    buildRouteRenderAssets(pagePath: string, isMdx: boolean, declaredModules: string[]): Promise<ProcessedAsset[]>;
+    buildPageBrowserGraphAssets(pagePath: string, isMdx: boolean, declaredModules: string[]): Promise<ProcessedAsset[]>;
 }

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 {};