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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react",
-  "version": "0.2.0-alpha.50",
+  "version": "0.2.0-alpha.52",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -31,6 +31,10 @@
       "types": "./src/utils/client-only.d.ts",
       "default": "./src/utils/client-only.js"
     },
+    "./runtime/use-sync-external-store-with-selector": {
+      "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
+      "default": "./src/runtime/use-sync-external-store-with-selector.js"
+    },
     "./router-adapter": {
       "types": "./src/router-adapter.d.ts",
       "default": "./src/router-adapter.js"
@@ -50,6 +54,10 @@
       "types": "./src/utils/client-only.d.ts",
       "default": "./src/utils/client-only.js"
     },
+    "./runtime/use-sync-external-store-with-selector.ts": {
+      "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
+      "default": "./src/runtime/use-sync-external-store-with-selector.js"
+    },
     "./router-adapter.ts": {
       "types": "./src/router-adapter.d.ts",
       "default": "./src/router-adapter.js"
@@ -61,14 +69,14 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.50",
+    "@ecopages/core": "0.2.0-alpha.52",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.50",
+    "@ecopages/file-system": "0.2.0-alpha.52",
     "@ecopages/logger": "^0.2.3",
     "@mdx-js/esbuild": "^3.1.1",
     "@mdx-js/mdx": "^3.1.1",

package/src/react-hmr-strategy.d.ts

@@ -7,13 +7,14 @@
  * @module
  */
 import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
 import type { DefaultHmrContext } from '@ecopages/core';
 import type { CompileOptions } from '@mdx-js/mdx';
 import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
 export interface ReactHmrStrategyOptions {
     context: DefaultHmrContext;
     pageMetadataCache: ReactHmrPageMetadataCache;
-    runtimeAliasMap: ReadonlyMap<string, string>;
+    runtimeManifest: BrowserRuntimeManifest;
     mdxCompilerOptions?: CompileOptions;
     ownedTemplateExtensions?: string[];
     allTemplateExtensions?: string[];
@@ -56,7 +57,7 @@ export interface ReactHmrStrategyOptions {
  * const strategy = new ReactHmrStrategy({
  *   context,
  *   pageMetadataCache,
- *   runtimeAliasMap
+ *   runtimeManifest
  * });
  * ```
  */
@@ -74,13 +75,17 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private context;
     private pageMetadataCache;
     private explicitGraphEnabled;
-    private readonly runtimeAliasMap;
+    private readonly runtimeManifest;
     constructor(options: ReactHmrStrategyOptions);
     /**
      * Returns build plugins for React HMR bundling.
      *
      * Includes the client graph boundary plugin to prevent undeclared imports
      * (including `node:*`) from breaking the browser bundle.
+     *
+     * @remarks
+     * HMR builds receive the React runtime manifest and rewrite manifest-owned
+     * runtime imports to concrete asset URLs before module resolution.
      */
     private getBuildPlugins;
     private isReactEntrypoint;
@@ -98,8 +103,15 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     /**
      * Determines if the file is a React/MDX entrypoint that's registered for HMR.
      *
+     * Uses a three-way decision strategy for selective invalidation:
+     * 1. If the file is a watched entrypoint, check if React owns it
+     * 2. If the file is a dependency of watched entrypoints (via dependency graph),
+     *    check if any affected entrypoints are React-owned. Returns false if hits
+     *    exist but none are owned (prevents unnecessary rebuilds).
+     * 3. Otherwise, check if the file itself is a React entrypoint template
+     *
      * @param filePath - Absolute path to the changed file
-     * @returns True if this is a registered React or MDX entrypoint
+     * @returns True if this file should trigger React HMR rebuilds
      */
     matches(filePath: string): boolean;
     /**
@@ -118,7 +130,6 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private getEntrypointOutput;
     private getGroupedTempOutputPattern;
     private collectReactPageBuildTargets;
-    private getRequestedTargets;
     /**
      * Expands one HMR request into the full React page build cohort when needed.
      *
@@ -130,12 +141,17 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private resolveBuildTargets;
     private partitionBuildTargets;
     /**
-     * Processes a React file change by rebuilding all React entrypoints.
+     * Processes a React file change by rebuilding affected React entrypoints.
+     *
+     * Uses a three-way decision strategy for selective invalidation:
+     * 1. Changed file is a watched entrypoint: rebuild only that entrypoint
+     * 2. Dependency graph has hits: rebuild only affected React-owned entrypoints.
+     *    If hits exist but none map to React-owned entrypoints, return 'none' to
+     *    prevent unnecessary rebuilds.
+     * 3. Dependency graph miss: fall back to rebuilding all watched entrypoints
      *
      * For layout files, broadcasts a 'layout-update' event to trigger full page reload.
      * For regular components/pages, broadcasts 'update' events for module-level HMR.
-     * When a page entrypoint is first registered, only that entrypoint is built.
-     * Subsequent file updates rebuild all watched React entrypoints as usual.
      *
      * @param _filePath - Absolute path to the changed file
      * @returns Action to broadcast update events (layout-update for layouts, update for components)
@@ -144,11 +160,26 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     /**
      * Bundles a single React/MDX entrypoint with HMR support.
      *
+     * After successful bundling, populates the entrypoint dependency graph with
+     * the build's dependency metadata. This enables selective invalidation on
+     * subsequent file changes, so only entrypoints affected by a changed
+     * dependency are rebuilt.
+     *
      * @param entrypointPath - Absolute path to the source file
      * @param outputUrl - URL path for the bundled file
      * @returns True if bundling was successful
      */
     private bundleReactEntrypoint;
+    /**
+     * Bundles multiple React/MDX entrypoints in a single build pass.
+     *
+     * Uses code splitting to share common dependencies across entrypoints.
+     * After successful bundling, populates the entrypoint dependency graph with
+     * the build's dependency metadata for selective invalidation.
+     *
+     * @param entrypoints - Array of entrypoint paths and their output URLs
+     * @returns Array of output URLs that were successfully built
+     */
     private bundleReactEntrypoints;
     private resolveTempOutputPath;
     /**

package/src/react-hmr-strategy.js

@@ -1,8 +1,7 @@
 import path from "node:path";
 import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
 import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
-import { rewriteRuntimeSpecifierAliases } from "@ecopages/core/build/runtime-specifier-aliases";
-import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
+import { createBrowserRuntimeImportRewritePlugin } from "@ecopages/core/build/browser-runtime-import-rewrite-plugin";
 import { FileNotFoundError, fileSystem } from "@ecopages/file-system";
 import { Logger } from "@ecopages/logger";
 import { injectHmrHandler } from "./utils/hmr-scripts.js";
@@ -10,7 +9,6 @@ import { createClientGraphBoundaryPlugin } from "./utils/client-graph-boundary-p
 import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from "./utils/declared-modules.js";
 import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
 import { getReactClientGraphAllowSpecifiers } from "./utils/react-runtime-alias-map.js";
-import { createUseSyncExternalStoreShimPlugin } from "./utils/use-sync-external-store-shim-plugin.js";
 const appLogger = new Logger("[ReactHmrStrategy]");
 class ReactHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.INTEGRATION;
@@ -28,12 +26,12 @@ class ReactHmrStrategy extends HmrStrategy {
   context;
   pageMetadataCache;
   explicitGraphEnabled;
-  runtimeAliasMap;
+  runtimeManifest;
   constructor(options) {
     super();
     this.context = options.context;
     this.pageMetadataCache = options.pageMetadataCache;
-    this.runtimeAliasMap = options.runtimeAliasMap;
+    this.runtimeManifest = options.runtimeManifest;
     this.explicitGraphEnabled = options.explicitGraphEnabled ?? false;
     this.mdxCompilerOptions = options.mdxCompilerOptions;
     this.ownedTemplateExtensions = new Set(options.ownedTemplateExtensions ?? [".tsx"]);
@@ -46,11 +44,18 @@ class ReactHmrStrategy extends HmrStrategy {
    *
    * Includes the client graph boundary plugin to prevent undeclared imports
    * (including `node:*`) from breaking the browser bundle.
+   *
+   * @remarks
+   * HMR builds receive the React runtime manifest and rewrite manifest-owned
+   * runtime imports to concrete asset URLs before module resolution.
    */
   getBuildPlugins(declaredModules) {
-    const allowSpecifiers = getReactClientGraphAllowSpecifiers(this.runtimeAliasMap.keys());
-    const runtimeAliasPlugin = createRuntimeSpecifierAliasPlugin(this.runtimeAliasMap, {
-      name: "react-hmr-runtime-specifier-alias"
+    const allowSpecifiers = getReactClientGraphAllowSpecifiers(
+      this.runtimeManifest.assets.map((asset) => asset.specifier)
+    );
+    const runtimeRewritePlugin = createBrowserRuntimeImportRewritePlugin({
+      name: "react-hmr-runtime-import-rewrite",
+      manifest: this.runtimeManifest
     });
     return [
       createClientGraphBoundaryPlugin({
@@ -58,12 +63,8 @@ class ReactHmrStrategy extends HmrStrategy {
         alwaysAllowSpecifiers: allowSpecifiers,
         declaredModules
       }),
-      ...runtimeAliasPlugin ? [runtimeAliasPlugin] : [],
-      ...this.context.getPlugins(),
-      createUseSyncExternalStoreShimPlugin({
-        name: "react-hmr-use-sync-external-store-shim",
-        namespace: "ecopages-react-hmr-shim"
-      })
+      ...runtimeRewritePlugin ? [runtimeRewritePlugin] : [],
+      ...this.context.getPlugins()
     ];
   }
   isReactEntrypoint(filePath) {
@@ -105,8 +106,15 @@ class ReactHmrStrategy extends HmrStrategy {
   /**
    * Determines if the file is a React/MDX entrypoint that's registered for HMR.
    *
+   * Uses a three-way decision strategy for selective invalidation:
+   * 1. If the file is a watched entrypoint, check if React owns it
+   * 2. If the file is a dependency of watched entrypoints (via dependency graph),
+   *    check if any affected entrypoints are React-owned. Returns false if hits
+   *    exist but none are owned (prevents unnecessary rebuilds).
+   * 3. Otherwise, check if the file itself is a React entrypoint template
+   *
    * @param filePath - Absolute path to the changed file
-   * @returns True if this is a registered React or MDX entrypoint
+   * @returns True if this file should trigger React HMR rebuilds
    */
   matches(filePath) {
     const watchedFiles = this.context.getWatchedFiles();
@@ -117,6 +125,15 @@ class ReactHmrStrategy extends HmrStrategy {
     if (watchedFiles.has(filePath)) {
       return this.ownsWatchedEntrypoint(filePath);
     }
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
+    if (dependencyHits.size > 0) {
+      for (const entrypoint of dependencyHits) {
+        if (this.ownsWatchedEntrypoint(entrypoint)) {
+          return true;
+        }
+      }
+      return false;
+    }
     return this.isReactEntrypoint(filePath);
   }
   /**
@@ -179,13 +196,6 @@ class ReactHmrStrategy extends HmrStrategy {
       (left, right) => left.entrypointPath.localeCompare(right.entrypointPath)
     );
   }
-  getRequestedTargets(changedFilePath, changedEntrypointOutput, watchedFiles) {
-    const requestedEntries = changedEntrypointOutput ? [[changedFilePath, changedEntrypointOutput]] : Array.from(watchedFiles.entries());
-    return requestedEntries.map(([entrypointPath, outputUrl]) => ({
-      entrypointPath,
-      outputUrl
-    }));
-  }
   /**
    * Expands one HMR request into the full React page build cohort when needed.
    *
@@ -224,12 +234,17 @@ class ReactHmrStrategy extends HmrStrategy {
     };
   }
   /**
-   * Processes a React file change by rebuilding all React entrypoints.
+   * Processes a React file change by rebuilding affected React entrypoints.
+   *
+   * Uses a three-way decision strategy for selective invalidation:
+   * 1. Changed file is a watched entrypoint: rebuild only that entrypoint
+   * 2. Dependency graph has hits: rebuild only affected React-owned entrypoints.
+   *    If hits exist but none map to React-owned entrypoints, return 'none' to
+   *    prevent unnecessary rebuilds.
+   * 3. Dependency graph miss: fall back to rebuilding all watched entrypoints
    *
    * For layout files, broadcasts a 'layout-update' event to trigger full page reload.
    * For regular components/pages, broadcasts 'update' events for module-level HMR.
-   * When a page entrypoint is first registered, only that entrypoint is built.
-   * Subsequent file updates rebuild all watched React entrypoints as usual.
    *
    * @param _filePath - Absolute path to the changed file
    * @returns Action to broadcast update events (layout-update for layouts, update for components)
@@ -250,7 +265,22 @@ class ReactHmrStrategy extends HmrStrategy {
       appLogger.debug(`Skipping non-React watched entrypoint: ${_filePath}`);
       return { type: "none" };
     }
-    const requestedTargets = this.getRequestedTargets(_filePath, changedEntrypointOutput, watchedFiles);
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(_filePath);
+    const hasDependencyHits = dependencyHits.size > 0;
+    const affectedEntrypoints = /* @__PURE__ */ new Map();
+    if (hasDependencyHits && !changedEntrypointOutput) {
+      for (const entrypoint of dependencyHits) {
+        const outputUrl = watchedFiles.get(entrypoint);
+        if (outputUrl && this.ownsWatchedEntrypoint(entrypoint)) {
+          affectedEntrypoints.set(entrypoint, outputUrl);
+        }
+      }
+      if (affectedEntrypoints.size === 0) {
+        appLogger.debug(`Dependency hits found but none map to React-owned watched entrypoints`);
+        return { type: "none" };
+      }
+    }
+    const requestedTargets = changedEntrypointOutput ? [{ entrypointPath: _filePath, outputUrl: changedEntrypointOutput }] : hasDependencyHits ? Array.from(affectedEntrypoints, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl })) : Array.from(watchedFiles, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl }));
     const groupedPageTargets = await this.resolveBuildTargets(requestedTargets, _filePath);
     const { pageTargets, nonPageTargets } = this.partitionBuildTargets(requestedTargets, groupedPageTargets);
     const updates = [];
@@ -310,6 +340,11 @@ class ReactHmrStrategy extends HmrStrategy {
   /**
    * Bundles a single React/MDX entrypoint with HMR support.
    *
+   * After successful bundling, populates the entrypoint dependency graph with
+   * the build's dependency metadata. This enables selective invalidation on
+   * subsequent file changes, so only entrypoints affected by a changed
+   * dependency are rebuilt.
+   *
    * @param entrypointPath - Absolute path to the source file
    * @param outputUrl - URL path for the bundled file
    * @returns True if bundling was successful
@@ -337,6 +372,12 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`Failed to build ${entrypointPath}:`, result.logs);
         return false;
       }
+      if (result.dependencyGraph?.entrypoints) {
+        const dependencyGraph = this.context.getEntrypointDependencyGraph();
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencyGraph.setEntrypointDependencies(entrypoint, deps);
+        }
+      }
       const tempFile = result.outputs[0]?.path;
       if (!tempFile) {
         appLogger.error(`No output file generated for ${entrypointPath}`);
@@ -354,6 +395,16 @@ class ReactHmrStrategy extends HmrStrategy {
       return false;
     }
   }
+  /**
+   * Bundles multiple React/MDX entrypoints in a single build pass.
+   *
+   * Uses code splitting to share common dependencies across entrypoints.
+   * After successful bundling, populates the entrypoint dependency graph with
+   * the build's dependency metadata for selective invalidation.
+   *
+   * @param entrypoints - Array of entrypoint paths and their output URLs
+   * @returns Array of output URLs that were successfully built
+   */
   async bundleReactEntrypoints(entrypoints) {
     try {
       const declaredModules = /* @__PURE__ */ new Set();
@@ -386,6 +437,12 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`Failed to build grouped React entrypoints:`, result.logs);
         return [];
       }
+      if (result.dependencyGraph?.entrypoints) {
+        const dependencyGraph = this.context.getEntrypointDependencyGraph();
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencyGraph.setEntrypointDependencies(entrypoint, deps);
+        }
+      }
       const updatedOutputs = [];
       for (const { entrypointPath, outputUrl } of entrypoints) {
         const { outputPath } = this.getEntrypointOutput(entrypointPath);
@@ -469,7 +526,6 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     try {
       let code = await fileSystem.readFile(tempPath);
-      code = rewriteRuntimeSpecifierAliases(code, this.runtimeAliasMap);
       code = this.rewriteChunkImportUrls(code);
       code = injectHmrHandler(code);
       await fileSystem.writeAsync(finalPath, code);

package/src/react.plugin.d.ts

@@ -1,4 +1,5 @@
 import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
 import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
 import type React from 'react';
 import { ReactRenderer } from './react-renderer.js';
@@ -40,6 +41,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
     }): ReactRenderer;
     private ensureRuntimeDependencies;
     get plugins(): EcoBuildPlugin[];
+    get browserRuntimeManifest(): BrowserRuntimeManifest;
     /**
      * Ensures the optional React MDX loader exists before either config-time
      * manifest sealing or runtime setup needs it.

package/src/react.plugin.js

@@ -135,6 +135,10 @@ class ReactPlugin extends IntegrationPlugin {
     }
     return [];
   }
+  get browserRuntimeManifest() {
+    this.ensureRuntimeDependencies();
+    return this.runtimeBundleService.getRuntimeManifest();
+  }
   /**
    * Ensures the optional React MDX loader exists before either config-time
    * manifest sealing or runtime setup needs it.
@@ -179,7 +183,7 @@ class ReactPlugin extends IntegrationPlugin {
     return new ReactHmrStrategy({
       context,
       pageMetadataCache: this.hmrPageMetadataCache,
-      runtimeAliasMap: new Map(Object.entries(this.runtimeBundleService.getRuntimeAliasMap("development"))),
+      runtimeManifest: this.runtimeBundleService.getRuntimeManifest("development"),
       mdxCompilerOptions: this.mdxCompilerOptions,
       ownedTemplateExtensions: this.extensions,
       allTemplateExtensions: this.appConfig.templatesExt,

package/src/runtime/use-sync-external-store-with-selector.d.ts

@@ -0,0 +1,3 @@
+type Subscribe = (onStoreChange: () => void) => () => void;
+export declare function useSyncExternalStoreWithSelector<Snapshot, Selection>(subscribe: Subscribe, getSnapshot: () => Snapshot, getServerSnapshot: (() => Snapshot) | undefined, selector: (snapshot: Snapshot) => Selection, isEqual?: (left: Selection, right: Selection) => boolean): Selection;
+export {};

package/src/runtime/use-sync-external-store-with-selector.js

@@ -0,0 +1,56 @@
+import { useDebugValue, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+const objectIs = Object.is;
+function useSyncExternalStoreWithSelector(subscribe, getSnapshot, getServerSnapshot, selector, isEqual) {
+  const instRef = useRef({ hasValue: false, value: void 0 });
+  const memoizedSelectionRef = useMemo(() => {
+    let hasMemo = false;
+    let memoizedSnapshot;
+    let memoizedSelection;
+    const maybeGetServerSnapshot = getServerSnapshot === void 0 ? null : getServerSnapshot;
+    const memoizedSelector = (nextSnapshot) => {
+      if (!hasMemo) {
+        hasMemo = true;
+        memoizedSnapshot = nextSnapshot;
+        const nextSelection2 = selector(nextSnapshot);
+        const inst = instRef.current;
+        if (isEqual !== void 0 && inst.hasValue) {
+          const currentSelection2 = inst.value;
+          if (isEqual(currentSelection2, nextSelection2)) {
+            memoizedSelection = currentSelection2;
+            return currentSelection2;
+          }
+        }
+        memoizedSelection = nextSelection2;
+        return nextSelection2;
+      }
+      const currentSelection = memoizedSelection;
+      if (objectIs(memoizedSnapshot, nextSnapshot)) {
+        return currentSelection;
+      }
+      const nextSelection = selector(nextSnapshot);
+      if (isEqual !== void 0 && isEqual(currentSelection, nextSelection)) {
+        memoizedSnapshot = nextSnapshot;
+        return currentSelection;
+      }
+      memoizedSnapshot = nextSnapshot;
+      memoizedSelection = nextSelection;
+      return nextSelection;
+    };
+    return [
+      () => memoizedSelector(getSnapshot()),
+      maybeGetServerSnapshot === null ? void 0 : () => memoizedSelector(maybeGetServerSnapshot())
+    ];
+  }, [getSnapshot, getServerSnapshot, selector, isEqual]);
+  const value = useSyncExternalStore(subscribe, memoizedSelectionRef[0], memoizedSelectionRef[1]);
+  useEffect(() => {
+    instRef.current = {
+      hasValue: true,
+      value
+    };
+  }, [value]);
+  useDebugValue(value);
+  return value;
+}
+export {
+  useSyncExternalStoreWithSelector
+};

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

@@ -47,15 +47,14 @@ export declare class ReactBundleService {
     /**
      * Creates esbuild 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[], bundleOptions?: ReactClientBundleOptions): Promise<Record<string, unknown>>;
-    /**
-     * Creates the esbuild plugin that rewrites bare React specifiers
-     * to their runtime asset URLs.
-     */
-    createRuntimeAliasPlugin(runtimeAliasMap: Record<string, string>): import("@ecopages/core/build/build-types").EcoBuildPlugin | null;
 }

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

@@ -1,11 +1,9 @@
 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 { createBrowserRuntimeImportRewritePlugin } from "@ecopages/core/build/browser-runtime-import-rewrite-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";
@@ -28,6 +26,10 @@ class ReactBundleService {
   /**
    * Creates esbuild 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
@@ -64,37 +66,20 @@ class ReactBundleService {
       hostJsxImportSource: this.config.jsxImportSource ?? "react",
       foreignExtensions: this.config.nonReactExtensions ?? []
     });
-    const useSyncExternalStoreShimPlugin = createUseSyncExternalStoreShimPlugin({
-      name: "react-renderer-use-sync-external-store-shim",
-      namespace: "ecopages-react-renderer-shim"
+    const runtimeManifest = this.runtimeBundleService.getRuntimeManifest();
+    const runtimeRewritePlugin = createBrowserRuntimeImportRewritePlugin({
+      name: "react-renderer-runtime-import-rewrite",
+      manifest: runtimeManifest
     });
-    const runtimePlugins = bundleOptions.includeRuntime ? [] : [this.createRuntimeAliasPlugin(buildReactRuntimeAliasMap(runtimeImports))];
+    const runtimePlugins = bundleOptions.includeRuntime ? [] : [runtimeRewritePlugin].filter((plugin) => plugin !== null);
     if (isMdx && this.config.mdxCompilerOptions) {
       const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
-      options.plugins = [
-        foreignJsxOverridePlugin,
-        graphBoundaryPlugin,
-        ...runtimePlugins,
-        mdxPlugin,
-        useSyncExternalStoreShimPlugin
-      ];
+      options.plugins = [foreignJsxOverridePlugin, graphBoundaryPlugin, ...runtimePlugins, mdxPlugin];
     } else {
-      options.plugins = [
-        foreignJsxOverridePlugin,
-        graphBoundaryPlugin,
-        ...runtimePlugins,
-        useSyncExternalStoreShimPlugin
-      ];
+      options.plugins = [foreignJsxOverridePlugin, graphBoundaryPlugin, ...runtimePlugins];
     }
     return options;
   }
-  /**
-   * Creates the esbuild plugin that rewrites bare React specifiers
-   * to their runtime asset URLs.
-   */
-  createRuntimeAliasPlugin(runtimeAliasMap) {
-    return createRuntimeSpecifierAliasPlugin(runtimeAliasMap, { name: "react-runtime-import-alias" });
-  }
 }
 export {
   ReactBundleService

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

@@ -9,12 +9,14 @@
 import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
 import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
 import type { ReactRouterAdapter } from '../router-adapter.js';
+import { type BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
 export type ReactRuntimeImports = {
     react: string;
     reactDomClient: string;
     reactJsxRuntime: string;
     reactJsxDevRuntime: string;
     reactDom: string;
+    useSyncExternalStoreWithSelector: string;
     router?: string;
 };
 export interface ReactRuntimeBundleServiceConfig {
@@ -32,8 +34,11 @@ export declare class ReactRuntimeBundleService {
     private getReactVendorFileName;
     private getReactDomVendorFileName;
     private getRouterVendorFileName;
+    private getUseSyncExternalStoreWithSelectorVendorFileName;
+    private createReactVendorImportRewritePlugin;
     getRuntimeImports(mode?: RuntimeMode): ReactRuntimeImports;
     getRuntimeAliasMap(mode?: RuntimeMode): Record<string, string>;
+    getRuntimeManifest(mode?: RuntimeMode): BrowserRuntimeManifest;
     getDependencies(): AssetDefinition[];
     createRuntimeAliasPlugin(mode?: RuntimeMode): EcoBuildPlugin;
 }

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

@@ -1,3 +1,7 @@
+import {
+  createBrowserRuntimeImportRewritePlugin,
+  DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME
+} from "@ecopages/core/build/browser-runtime-import-rewrite-plugin";
 import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
 import {
   buildBrowserRuntimeAssetUrl,
@@ -5,7 +9,10 @@ import {
   createBrowserRuntimeScriptAsset
 } from "@ecopages/core/services/asset-processing-service";
 import { createReactDomRuntimeInteropPlugin } from "../utils/react-dom-runtime-interop-plugin.js";
-import { buildReactRuntimeAliasMap } from "../utils/react-runtime-alias-map.js";
+import { buildReactRuntimeAliasMap, buildReactRuntimeManifest } from "../utils/react-runtime-alias-map.js";
+import {
+  createBrowserRuntimeManifest
+} from "@ecopages/core/build/browser-runtime-manifest";
 class ReactRuntimeBundleService {
   config;
   constructor(config) {
@@ -39,6 +46,22 @@ class ReactRuntimeBundleService {
     }
     return mode === "development" ? `${this.config.routerAdapter.bundle.outputName}.development.js` : `${this.config.routerAdapter.bundle.outputName}.js`;
   }
+  getUseSyncExternalStoreWithSelectorVendorFileName(mode) {
+    return mode === "development" ? "use-sync-external-store-with-selector.development.js" : "use-sync-external-store-with-selector.js";
+  }
+  createReactVendorImportRewritePlugin(mode) {
+    return createBrowserRuntimeImportRewritePlugin({
+      name: `react-plugin-vendor-runtime-import-rewrite-${mode}`,
+      manifest: createBrowserRuntimeManifest([
+        {
+          specifier: "react",
+          owner: "@ecopages/react",
+          importPath: "react",
+          publicPath: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
+        }
+      ])
+    });
+  }
   getRuntimeImports(mode = this.getCurrentRuntimeMode()) {
     const reactVendorFileName = this.getReactVendorFileName(mode);
     const reactDomVendorFileName = this.getReactDomVendorFileName(mode);
@@ -47,7 +70,10 @@ class ReactRuntimeBundleService {
       reactDomClient: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
       reactJsxRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
       reactJsxDevRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
-      reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName)
+      reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
+      useSyncExternalStoreWithSelector: buildBrowserRuntimeAssetUrl(
+        this.getUseSyncExternalStoreWithSelectorVendorFileName(mode)
+      )
     };
     if (this.config.routerAdapter) {
       runtimeImports.router = buildBrowserRuntimeAssetUrl(this.getRouterVendorFileName(mode));
@@ -57,10 +83,16 @@ class ReactRuntimeBundleService {
   getRuntimeAliasMap(mode = this.getCurrentRuntimeMode()) {
     return buildReactRuntimeAliasMap(this.getRuntimeImports(mode));
   }
+  getRuntimeManifest(mode = this.getCurrentRuntimeMode()) {
+    return buildReactRuntimeManifest(this.getRuntimeImports(mode));
+  }
   getDependencies() {
-    const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin();
     const dependencies = [];
     for (const mode of ["production", "development"]) {
+      const reactVendorImportRewritePlugin = this.createReactVendorImportRewritePlugin(mode);
+      const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin({
+        reactSpecifier: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
+      });
       const reactRuntimeAliasPlugin = createRuntimeSpecifierAliasPlugin(
         {
           react: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
@@ -84,7 +116,8 @@ class ReactRuntimeBundleService {
           cacheDirName: `ecopages-react-runtime-${mode}`,
           rootDir: this.config.rootDir,
           bundleOptions: {
-            define: this.createRuntimeDefines(mode)
+            define: this.createRuntimeDefines(mode),
+            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME]
           }
         }),
         createBrowserRuntimeModuleAsset({
@@ -95,8 +128,19 @@ class ReactRuntimeBundleService {
           rootDir: this.config.rootDir,
           bundleOptions: {
             define: this.createRuntimeDefines(mode),
+            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME],
             plugins: reactDomBundlePlugins
           }
+        }),
+        createBrowserRuntimeScriptAsset({
+          importPath: "@ecopages/react/runtime/use-sync-external-store-with-selector",
+          name: "use-sync-external-store-with-selector",
+          fileName: this.getUseSyncExternalStoreWithSelectorVendorFileName(mode),
+          bundleOptions: {
+            define: this.createRuntimeDefines(mode),
+            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME],
+            plugins: [reactVendorImportRewritePlugin]
+          }
         })
       );
       if (this.config.routerAdapter) {

package/src/utils/react-dom-runtime-interop-plugin.js

@@ -1,5 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function createReactDomRuntimeInteropPlugin(options) {
   const reactDomFileFilter = /[\\/]react-dom[\\/].*\.js$/;
   const reactRequirePattern = /\brequire\((['"])react\1\)/g;
@@ -7,6 +10,12 @@ function createReactDomRuntimeInteropPlugin(options) {
   return {
     name: options?.name ?? "react-dom-runtime-interop",
     setup(build) {
+      if (reactSpecifier.startsWith("/")) {
+        build.onResolve({ filter: new RegExp(`^${escapeRegExp(reactSpecifier)}$`) }, (args) => ({
+          path: args.path,
+          external: true
+        }));
+      }
       build.onLoad({ filter: reactDomFileFilter }, (args) => {
         const content = fs.readFileSync(args.path, "utf-8");
         if (!reactRequirePattern.test(content)) {

package/src/utils/react-runtime-alias-map.d.ts

@@ -1,6 +1,8 @@
 import type { ReactRouterAdapter } from '../router-adapter.js';
 import type { ReactRuntimeImports } from '../services/react-runtime-bundle.service.js';
+import { type BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
 export declare const REACT_RUNTIME_SPECIFIERS: readonly ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"];
 export declare function buildReactRuntimeAliasMap(runtimeImports: ReactRuntimeImports): Record<string, string>;
+export declare function buildReactRuntimeManifest(runtimeImports: ReactRuntimeImports): BrowserRuntimeManifest;
 export declare function getReactRuntimeExternalSpecifiers(): string[];
 export declare function getReactClientGraphAllowSpecifiers(runtimeSpecifiers: Iterable<string>, routerAdapter?: ReactRouterAdapter): string[];

package/src/utils/react-runtime-alias-map.js

@@ -1,3 +1,7 @@
+import {
+  createBrowserRuntimeManifest,
+  getBrowserRuntimeSpecifierMap
+} from "@ecopages/core/build/browser-runtime-manifest";
 const REACT_RUNTIME_SPECIFIERS = [
   "react",
   "react-dom",
@@ -6,13 +10,65 @@ const REACT_RUNTIME_SPECIFIERS = [
   "react-dom/client"
 ];
 function buildReactRuntimeAliasMap(runtimeImports) {
-  return {
-    react: runtimeImports.react,
-    "react/jsx-runtime": runtimeImports.reactJsxRuntime,
-    "react/jsx-dev-runtime": runtimeImports.reactJsxDevRuntime,
-    "react-dom": runtimeImports.reactDom,
-    "react-dom/client": runtimeImports.reactDomClient
-  };
+  return Object.fromEntries(getBrowserRuntimeSpecifierMap(buildReactRuntimeManifest(runtimeImports)));
+}
+function buildReactRuntimeManifest(runtimeImports) {
+  return createBrowserRuntimeManifest([
+    {
+      specifier: "react",
+      owner: "@ecopages/react",
+      importPath: "react",
+      publicPath: runtimeImports.react
+    },
+    {
+      specifier: "react/jsx-runtime",
+      owner: "@ecopages/react",
+      importPath: "react/jsx-runtime",
+      publicPath: runtimeImports.reactJsxRuntime
+    },
+    {
+      specifier: "react/jsx-dev-runtime",
+      owner: "@ecopages/react",
+      importPath: "react/jsx-dev-runtime",
+      publicPath: runtimeImports.reactJsxDevRuntime
+    },
+    {
+      specifier: "react-dom",
+      owner: "@ecopages/react",
+      importPath: "react-dom",
+      publicPath: runtimeImports.reactDom
+    },
+    {
+      specifier: "react-dom/client",
+      owner: "@ecopages/react",
+      importPath: "react-dom/client",
+      publicPath: runtimeImports.reactDomClient
+    },
+    {
+      specifier: "use-sync-external-store/shim",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim",
+      publicPath: runtimeImports.react
+    },
+    {
+      specifier: "use-sync-external-store/shim/index.js",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim/index.js",
+      publicPath: runtimeImports.react
+    },
+    {
+      specifier: "use-sync-external-store/shim/with-selector",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim/with-selector",
+      publicPath: runtimeImports.useSyncExternalStoreWithSelector
+    },
+    {
+      specifier: "use-sync-external-store/shim/with-selector.js",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim/with-selector.js",
+      publicPath: runtimeImports.useSyncExternalStoreWithSelector
+    }
+  ]);
 }
 function getReactRuntimeExternalSpecifiers() {
   return [...REACT_RUNTIME_SPECIFIERS];
@@ -28,6 +84,7 @@ function getReactClientGraphAllowSpecifiers(runtimeSpecifiers, routerAdapter) {
 export {
   REACT_RUNTIME_SPECIFIERS,
   buildReactRuntimeAliasMap,
+  buildReactRuntimeManifest,
   getReactClientGraphAllowSpecifiers,
   getReactRuntimeExternalSpecifiers
 };

package/src/utils/use-sync-external-store-shim-plugin.d.ts

@@ -1,5 +0,0 @@
-import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
-export declare function createUseSyncExternalStoreShimPlugin(options?: {
-    name?: string;
-    namespace?: string;
-}): EcoBuildPlugin;

package/src/utils/use-sync-external-store-shim-plugin.js

@@ -1,41 +0,0 @@
-function createUseSyncExternalStoreShimPlugin(options) {
-  const namespace = options?.namespace ?? "ecopages-react-use-sync-external-store-shim";
-  return {
-    name: options?.name ?? "react-use-sync-external-store-shim",
-    setup(build) {
-      build.onResolve({ filter: /^use-sync-external-store\/shim(?:\/index\.js)?$/ }, () => ({
-        path: "use-sync-external-store/shim",
-        namespace
-      }));
-      build.onLoad({ filter: /^use-sync-external-store\/shim$/, namespace }, () => ({
-        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"
-        })
-      );
-    }
-  };
-}
-export {
-  createUseSyncExternalStoreShimPlugin
-};