@ecopages/react 0.2.0-alpha.9 → 0.2.0-beta.1

package/src/services/pages-index.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+const DEFAULT_EXTENSIONS = [".tsx", ".kita.tsx", ".lit.tsx", ".eco.tsx", ".mdx", ".react.tsx"];
+class PagesIndex {
+  pagesDir;
+  extensions;
+  isPageEntrypoint;
+  pages = /* @__PURE__ */ new Set();
+  lastRefreshAt = 0;
+  constructor(options) {
+    this.pagesDir = options.pagesDir;
+    this.extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+    this.isPageEntrypoint = options.isPageEntrypoint ?? (() => true);
+  }
+  /**
+   * Rescan the pages directory and rebuild the index.
+   *
+   * Cheap to call multiple times in sequence (just a glob). The
+   * real value of `PagesIndex` is the `add` / `remove` path that
+   * callers can wire to the file watcher; for now this is the
+   * fallback used on layout changes.
+   */
+  async refresh() {
+    const files = await fileSystem.glob(
+      this.extensions.map((ext) => `**/*${ext}`),
+      {
+        cwd: this.pagesDir
+      }
+    );
+    const next = /* @__PURE__ */ new Set();
+    for (const file of files) {
+      const absolutePath = path.join(this.pagesDir, file);
+      if (!this.isPageEntrypoint(absolutePath)) continue;
+      if (file.includes(".ecopages-node.")) continue;
+      next.add(absolutePath);
+    }
+    this.pages.clear();
+    for (const p of next) this.pages.add(p);
+    this.lastRefreshAt = Date.now();
+  }
+  /**
+   * Add a single entrypoint. Idempotent.
+   */
+  add(absolutePath) {
+    if (!this.isPageEntrypoint(absolutePath)) return;
+    this.pages.add(absolutePath);
+  }
+  /**
+   * Remove a single entrypoint. Idempotent.
+   */
+  remove(absolutePath) {
+    this.pages.delete(absolutePath);
+  }
+  /** True if the index contains `absolutePath`. */
+  has(absolutePath) {
+    return this.pages.has(absolutePath);
+  }
+  /** Snapshot of the current set, sorted by absolute path. */
+  list() {
+    return Array.from(this.pages).sort();
+  }
+  /** Number of indexed entrypoints. */
+  get size() {
+    return this.pages.size;
+  }
+  /** Last refresh timestamp (ms since epoch). */
+  get refreshedAt() {
+    return this.lastRefreshAt;
+  }
+}
+export {
+  PagesIndex
+};

package/src/services/react-bundle.service.d.ts

@@ -1,7 +1,7 @@
 /**
  * Bundle configuration service for React integration.
  *
- * Encapsulates all esbuild plugin creation and bundle options
+ * Encapsulates all build plugin creation and bundle options
  * for client-side React component builds.
  *
  * @module
@@ -16,9 +16,25 @@ export interface ReactBundleServiceConfig {
     rootDir: string;
     routerAdapter?: ReactRouterAdapter;
     mdxCompilerOptions?: CompileOptions;
+    nonReactExtensions?: string[];
+    jsxImportSource?: string;
 }
 /**
- * Manages esbuild bundle configuration and plugin creation for React page/component builds.
+ * Optional flags that adjust how a React client entry is bundled.
+ */
+export interface ReactClientBundleOptions {
+    /**
+     * When `true`, bundle React runtime dependencies into the emitted entry instead of
+     * rewriting them to external runtime specifiers.
+     */
+    includeRuntime?: boolean;
+    /**
+     * When set, overrides the build adapter chunk splitting mode for this entry.
+     */
+    splitting?: boolean;
+}
+/**
+ * Manages bundle configuration and plugin creation for React page/component builds.
  */
 export declare class ReactBundleService {
     private readonly runtimeBundleService;
@@ -29,17 +45,16 @@ export declare class ReactBundleService {
      */
     getRuntimeImports(): ReactRuntimeImports;
     /**
-     * Creates esbuild bundle options for a page or component entry.
+     * Creates bundle options for a page or component entry.
+     *
+     * @remarks
+     * React derives runtime specifier mappings from the core browser runtime manifest
+     * so ESM imports resolve to concrete runtime asset URLs during module loading.
      *
      * @param componentName - Generated unique component name for output naming
      * @param isMdx - Whether the source file is an MDX file
      * @param declaredModules - Explicitly declared browser module specifiers
      * @returns Bundle options object for the build adapter
      */
-    createBundleOptions(componentName: string, isMdx: boolean, declaredModules: string[]): Promise<Record<string, unknown>>;
-    /**
-     * Creates the esbuild plugin that rewrites bare React specifiers
-     * to their runtime asset URLs.
-     */
-    createRuntimeAliasPlugin(runtimeSpecifierMap: Record<string, string>): import("packages/core/src/build/build-types.ts").EcoBuildPlugin | null;
+    createBundleOptions(componentName: string, isMdx: boolean, declaredModules: string[], bundleOptions?: ReactClientBundleOptions): Promise<Record<string, unknown>>;
 }

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

@@ -1,18 +1,19 @@
 import { createClientGraphBoundaryPlugin } from "../utils/client-graph-boundary-plugin.js";
 import {
-  buildReactRuntimeSpecifierMap,
   getReactClientGraphAllowSpecifiers,
   getReactRuntimeExternalSpecifiers
-} from "../utils/react-runtime-specifier-map.js";
-import { createUseSyncExternalStoreShimPlugin } from "../utils/use-sync-external-store-shim-plugin.js";
-import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
+} from "../utils/react-runtime-alias-map.js";
+import { createBrowserRuntimePlugin } from "@ecopages/core/build/browser-runtime-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
     });
   }
@@ -23,52 +24,62 @@ class ReactBundleService {
     return this.runtimeBundleService.getRuntimeImports();
   }
   /**
-   * Creates esbuild bundle options for a page or component entry.
+   * Creates bundle options for a page or component entry.
+   *
+   * @remarks
+   * React derives runtime specifier mappings from the core browser runtime manifest
+   * so ESM imports resolve to concrete runtime asset URLs during module loading.
    *
    * @param componentName - Generated unique component name for output naming
    * @param isMdx - Whether the source file is an MDX file
    * @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 runtimeSpecifierMap = buildReactRuntimeSpecifierMap(runtimeImports, this.config.routerAdapter);
     const options = {
-      external: getReactRuntimeExternalSpecifiers(),
       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: getReactClientGraphAllowSpecifiers([], this.config.routerAdapter)
     });
-    const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeSpecifierMap);
-    const useSyncExternalStoreShimPlugin = createUseSyncExternalStoreShimPlugin({
-      name: "react-renderer-use-sync-external-store-shim",
-      namespace: "ecopages-react-renderer-shim"
+    const foreignJsxOverridePlugin = createForeignJsxOverridePlugin({
+      name: "react-renderer-foreign-jsx-override",
+      hostJsxImportSource: this.config.jsxImportSource ?? "react",
+      foreignExtensions: this.config.nonReactExtensions ?? []
+    });
+    const runtimeManifest = this.runtimeBundleService.getRuntimeManifest();
+    const runtimeRewritePlugin = createBrowserRuntimePlugin({
+      name: "react-renderer-runtime-import-rewrite",
+      manifest: runtimeManifest
     });
+    const runtimePlugins = bundleOptions.includeRuntime ? [] : [runtimeRewritePlugin].filter((plugin) => plugin !== null);
     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];
     } else {
-      options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, useSyncExternalStoreShimPlugin];
+      options.plugins = [foreignJsxOverridePlugin, graphBoundaryPlugin, ...runtimePlugins];
     }
     return options;
   }
-  /**
-   * Creates the esbuild plugin that rewrites bare React specifiers
-   * to their runtime asset URLs.
-   */
-  createRuntimeAliasPlugin(runtimeSpecifierMap) {
-    return createRuntimeSpecifierAliasPlugin(runtimeSpecifierMap, { name: "react-runtime-import-alias" });
-  }
 }
 export {
   ReactBundleService

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

@@ -6,12 +6,21 @@
  */
 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.
      */
-    setDeclaredModules(entrypointPath: string, declaredModules: string[]): void;
+    setDeclaredModules(entrypointPath: string, declaredModules: readonly string[]): void;
     /**
      * 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

@@ -6,109 +6,106 @@ import {
 } from "@ecopages/core/services/asset-processing-service";
 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_PAGES__=window.__ECO_PAGES__||{};window.__ECO_PAGES__.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
 };