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

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

@@ -16,13 +16,29 @@ export interface ReactBundleServiceConfig {
     rootDir: string;
     routerAdapter?: ReactRouterAdapter;
     mdxCompilerOptions?: CompileOptions;
+    nonReactExtensions?: string[];
+    jsxImportSource?: string;
+}
+/**
+ * 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 esbuild bundle configuration and plugin creation for React page/component builds.
  */
 export declare class ReactBundleService {
-    private readonly config;
     private readonly runtimeBundleService;
+    private readonly config;
     constructor(config: ReactBundleServiceConfig);
     /**
      * Returns resolved runtime import paths for the React runtime.
@@ -31,43 +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[]): Promise<Record<string, unknown>>;
-    /**
-     * Creates the esbuild plugin that rewrites bare React specifiers
-     * to their runtime asset URLs.
-     */
-    createRuntimeAliasPlugin(runtimeImports: ReactRuntimeImports): {
-        name: string;
-        setup(build: {
-            onResolve: (options: {
-                filter: RegExp;
-                namespace?: string;
-            }, callback: (args: {
-                path: string;
-                importer: string;
-                namespace: string;
-            }) => {
-                path?: string;
-                namespace?: string;
-                external?: boolean;
-            } | undefined) => void;
-        }): void;
-    };
-    /**
-     * 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.
-     */
-    private createSyncExternalStorePlugin;
+    createBundleOptions(componentName: string, isMdx: boolean, declaredModules: string[], bundleOptions?: ReactClientBundleOptions): Promise<Record<string, unknown>>;
 }

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

@@ -1,13 +1,22 @@
 import { createClientGraphBoundaryPlugin } from "../utils/client-graph-boundary-plugin.js";
+import {
+  getReactClientGraphAllowSpecifiers,
+  getReactRuntimeExternalSpecifiers
+} from "../utils/react-runtime-alias-map.js";
+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";
 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.
    */
@@ -17,133 +26,60 @@ 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
    */
-  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 runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeImports);
-    const useSyncExternalStoreShimPlugin = this.createSyncExternalStorePlugin();
+    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 = createBrowserRuntimeImportRewritePlugin({
+      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(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"
-          })
-        );
-      }
-    };
-  }
 }
 export {
   ReactBundleService

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[]>;
 }