@ecopages/react 0.2.0-alpha.8 → 0.2.0-beta.0

package/src/react-hmr-strategy.js

@@ -1,13 +1,17 @@
 import path from "node:path";
 import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
-import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
+import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
+import { createBrowserRuntimePlugin } from "@ecopages/core/build/browser-runtime-plugin";
 import { FileNotFoundError, fileSystem } from "@ecopages/file-system";
 import { Logger } from "@ecopages/logger";
 import { injectHmrHandler } from "./utils/hmr-scripts.js";
 import { createClientGraphBoundaryPlugin } from "./utils/client-graph-boundary-plugin.js";
+import { ClientGraphBoundaryCache } from "./utils/client-graph-boundary-cache.js";
 import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from "./utils/declared-modules.js";
-import { getReactClientGraphAllowSpecifiers } from "./utils/react-runtime-specifier-map.js";
-import { createUseSyncExternalStoreShimPlugin } from "./utils/use-sync-external-store-shim-plugin.js";
+import { someInConfigTree } from "./utils/component-config-traversal.js";
+import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
+import { getReactClientGraphAllowSpecifiers } from "./utils/react-runtime-alias-map.js";
+import { PagesIndex } from "./services/pages-index.js";
 const appLogger = new Logger("[ReactHmrStrategy]");
 class ReactHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.INTEGRATION;
@@ -20,51 +24,59 @@ class ReactHmrStrategy extends HmrStrategy {
   /**
    * Creates a new React HMR strategy instance.
    *
-   * @param context - The HMR context providing access to watched files, plugins, build directories,
-   *                  and the layouts directory for detecting layout file changes that require full
-   *                  page reloads instead of module-level HMR updates.
-   * @param pageMetadataCache - React-only cache of declared browser modules discovered during
-   *                            server rendering. This avoids re-importing unchanged page modules
-   *                            during save-time Fast Refresh rebuilds.
-   * @param mdxCompilerOptions - Optional MDX compiler options for processing .mdx files
-   * @param explicitGraphEnabled - Enables explicit graph mode for React HMR bundling.
-   * In explicit mode, HMR builds omit AST server-only stripping plugins in React paths.
+   * @param options - React HMR runtime services and behavior flags.
    */
   context;
   pageMetadataCache;
   explicitGraphEnabled;
-  constructor(context, pageMetadataCache, mdxCompilerOptions, ownedTemplateExtensions = [".tsx"], allTemplateExtensions = [".tsx"], explicitGraphEnabled = false) {
+  runtimeManifest;
+  clientGraphBoundaryCache;
+  pagesIndex;
+  constructor(options) {
     super();
-    this.context = context;
-    this.pageMetadataCache = pageMetadataCache;
-    this.explicitGraphEnabled = explicitGraphEnabled;
-    this.mdxCompilerOptions = mdxCompilerOptions;
-    this.ownedTemplateExtensions = new Set(ownedTemplateExtensions);
-    this.allTemplateExtensions = [...allTemplateExtensions].sort((a, b) => b.length - a.length);
+    this.context = options.context;
+    this.pageMetadataCache = options.pageMetadataCache;
+    this.runtimeManifest = options.runtimeManifest;
+    this.explicitGraphEnabled = options.explicitGraphEnabled ?? false;
+    this.clientGraphBoundaryCache = options.clientGraphBoundaryCache ?? new ClientGraphBoundaryCache();
+    this.pagesIndex = new PagesIndex({
+      pagesDir: this.context.getPagesDir(),
+      extensions: options.allTemplateExtensions,
+      isPageEntrypoint: (file) => this.isPageEntrypoint(file)
+    });
+    this.mdxCompilerOptions = options.mdxCompilerOptions;
+    this.ownedTemplateExtensions = new Set(options.ownedTemplateExtensions ?? [".tsx"]);
+    this.allTemplateExtensions = [...options.allTemplateExtensions ?? [".tsx"]].sort(
+      (a, b) => b.length - a.length
+    );
   }
   /**
    * 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.
    */
   getBuildPlugins(declaredModules) {
-    const allowSpecifiers = getReactClientGraphAllowSpecifiers(this.context.getSpecifierMap().keys());
-    const runtimeAliasPlugin = createRuntimeSpecifierAliasPlugin(this.context.getSpecifierMap(), {
-      name: "react-hmr-runtime-specifier-alias"
+    const allowSpecifiers = getReactClientGraphAllowSpecifiers(
+      this.runtimeManifest.assets.map((asset) => asset.specifier)
+    );
+    const runtimeRewritePlugin = createBrowserRuntimePlugin({
+      name: "react-hmr-runtime-import-rewrite",
+      manifest: this.runtimeManifest
     });
     return [
       createClientGraphBoundaryPlugin({
         absWorkingDir: path.dirname(this.context.getSrcDir()),
         alwaysAllowSpecifiers: allowSpecifiers,
-        declaredModules
+        declaredModules,
+        cache: this.clientGraphBoundaryCache
       }),
-      ...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) {
@@ -74,10 +86,13 @@ class ReactHmrStrategy extends HmrStrategy {
     if (!filePath.endsWith(".tsx")) {
       return false;
     }
+    const templateExtension = this.resolveTemplateExtension(filePath);
+    if (templateExtension && templateExtension !== ".tsx") {
+      return this.ownedTemplateExtensions.has(templateExtension);
+    }
     if (!this.isRouteTemplate(filePath)) {
       return true;
     }
-    const templateExtension = this.resolveTemplateExtension(filePath);
     if (!templateExtension) {
       return false;
     }
@@ -97,11 +112,47 @@ class ReactHmrStrategy extends HmrStrategy {
   resolveTemplateExtension(filePath) {
     return this.allTemplateExtensions.find((extension) => filePath.endsWith(extension));
   }
+  ownsWatchedEntrypoint(filePath) {
+    return this.pageMetadataCache.ownsEntrypoint(filePath);
+  }
+  configContainsFile(config, filePath) {
+    const resolvedFilePath = path.resolve(filePath);
+    return someInConfigTree(config, (node) => {
+      if (!node.__eco?.file) {
+        return false;
+      }
+      return path.resolve(node.__eco.file) === resolvedFilePath;
+    });
+  }
+  pageModuleRequiresLayoutRefresh(pageModule, filePath) {
+    return [pageModule.default?.config, pageModule.config].some((config) => {
+      return this.configContainsFile(config?.layout?.config, filePath);
+    });
+  }
+  async hasLayoutOwnedDependencyTarget(changedFilePath, requestedTargets) {
+    for (const target of requestedTargets) {
+      if (!this.isPageEntrypoint(target.entrypointPath)) {
+        continue;
+      }
+      const pageModule = await this.importNodePageModule(target.entrypointPath);
+      if (this.pageModuleRequiresLayoutRefresh(pageModule, changedFilePath)) {
+        return true;
+      }
+    }
+    return false;
+  }
   /**
    * 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();
@@ -109,6 +160,18 @@ class ReactHmrStrategy extends HmrStrategy {
     if (watchedFiles.size === 0) {
       return false;
     }
+    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);
   }
   /**
@@ -125,13 +188,95 @@ class ReactHmrStrategy extends HmrStrategy {
   isLayoutFile(filePath) {
     return filePath.startsWith(this.context.getLayoutsDir());
   }
+  isPageEntrypoint(filePath) {
+    return filePath.startsWith(this.context.getPagesDir()) && this.isReactEntrypoint(filePath);
+  }
+  getEntrypointOutput(entrypointPath) {
+    const srcDir = this.context.getSrcDir();
+    const relativePath = path.relative(srcDir, entrypointPath);
+    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx)$/, ".js");
+    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+    const outputPath = path.join(this.context.getDistDir(), encodedPathJs);
+    const outputUrl = `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", encodedPathJs).split(path.sep).join("/")}`;
+    return { outputPath, outputUrl };
+  }
+  getRolldownEntryKey(entrypointPath) {
+    const srcDir = this.context.getSrcDir();
+    const relativePath = path.relative(srcDir, entrypointPath);
+    const relativePathNoExt = relativePath.replace(/\.(tsx?|jsx?|mdx)$/, "");
+    return relativePathNoExt;
+  }
+  getTempFileBasename(entrypointPath) {
+    const srcDir = this.context.getSrcDir();
+    const relativePath = path.relative(srcDir, entrypointPath);
+    const relativePathNoExt = relativePath.replace(/\.(tsx?|jsx?|mdx)$/, "");
+    const encodedPath = this.encodeDynamicSegments(relativePathNoExt);
+    return path.basename(encodedPath);
+  }
+  async collectReactPageBuildTargets() {
+    await this.pagesIndex.refresh();
+    const indexed = this.pagesIndex.list();
+    const targets = /* @__PURE__ */ new Map();
+    for (const entrypointPath of indexed) {
+      this.pageMetadataCache.markOwnedEntrypoint(entrypointPath);
+      targets.set(entrypointPath, {
+        entrypointPath,
+        outputUrl: this.getEntrypointOutput(entrypointPath).outputUrl
+      });
+    }
+    return Array.from(targets.values()).sort(
+      (left, right) => left.entrypointPath.localeCompare(right.entrypointPath)
+    );
+  }
   /**
-   * Processes a React file change by rebuilding all React entrypoints.
+   * Expands one HMR request into the full React page build cohort when needed.
+   *
+   * @remarks
+   * Page and layout changes need one shared rebuild pass so sibling routes keep
+   * a consistent client module graph. Non-page changes that do not touch a page
+   * cohort can stay scoped to the originally requested targets.
+   */
+  async resolveBuildTargets(requestedTargets, changedFilePath) {
+    const requestedPageTargets = requestedTargets.filter((target) => this.isPageEntrypoint(target.entrypointPath));
+    const shouldGroupPageBuilds = this.isLayoutFile(changedFilePath) || requestedPageTargets.length > 0;
+    if (!shouldGroupPageBuilds) {
+      return [];
+    }
+    const groupedTargets = new Map(requestedPageTargets.map((target) => [target.entrypointPath, target]));
+    for (const target of await this.collectReactPageBuildTargets()) {
+      groupedTargets.set(target.entrypointPath, target);
+    }
+    return Array.from(groupedTargets.values()).sort(
+      (left, right) => left.entrypointPath.localeCompare(right.entrypointPath)
+    );
+  }
+  partitionBuildTargets(requestedTargets, groupedPageTargets) {
+    if (groupedPageTargets.length === 0) {
+      return {
+        pageTargets: [],
+        nonPageTargets: requestedTargets
+      };
+    }
+    const groupedPageEntrypoints = new Set(groupedPageTargets.map((target) => target.entrypointPath));
+    return {
+      pageTargets: groupedPageTargets,
+      nonPageTargets: requestedTargets.filter(
+        (target) => !groupedPageEntrypoints.has(target.entrypointPath) && !this.isPageEntrypoint(target.entrypointPath)
+      )
+    };
+  }
+  /**
+   * 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,24 +289,86 @@ class ReactHmrStrategy extends HmrStrategy {
       return { type: "none" };
     }
     const isLayout = this.isLayoutFile(_filePath);
+    const isChangedPageEntrypoint = this.isPageEntrypoint(_filePath);
     if (isLayout) {
       appLogger.debug(`Detected layout file change: ${_filePath}`);
     }
     const changedEntrypointOutput = watchedFiles.get(_filePath);
-    const entrypointsToBuild = changedEntrypointOutput ? [[_filePath, changedEntrypointOutput]] : watchedFiles.entries();
+    if (changedEntrypointOutput && !this.ownsWatchedEntrypoint(_filePath)) {
+      if (this.isReactEntrypoint(_filePath)) {
+        this.pageMetadataCache.markOwnedEntrypoint(_filePath);
+      } else {
+        appLogger.debug(`Skipping non-React watched entrypoint: ${_filePath}`);
+        return { type: "none" };
+      }
+    }
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(_filePath);
+    const hasDependencyHits = dependencyHits.size > 0;
+    const affectedEntrypoints = /* @__PURE__ */ new Map();
+    let hasOwnedLayoutDependencyHit = false;
+    let layoutOwnedPageTargets = [];
+    let hasLayoutOwnedRequestedTarget = false;
+    if (hasDependencyHits && !changedEntrypointOutput) {
+      for (const entrypoint of dependencyHits) {
+        const outputUrl = watchedFiles.get(entrypoint);
+        if (outputUrl && this.ownsWatchedEntrypoint(entrypoint)) {
+          affectedEntrypoints.set(entrypoint, outputUrl);
+          continue;
+        }
+        if (this.isLayoutFile(entrypoint) && this.ownsWatchedEntrypoint(entrypoint)) {
+          hasOwnedLayoutDependencyHit = true;
+        }
+      }
+      if (affectedEntrypoints.size === 0 && !hasOwnedLayoutDependencyHit) {
+        appLogger.debug(`Dependency hits found but none map to React-owned watched entrypoints`);
+        return { type: "none" };
+      }
+    }
+    if (changedEntrypointOutput && !isLayout && !isChangedPageEntrypoint) {
+      layoutOwnedPageTargets = await this.collectReactPageBuildTargets();
+      hasLayoutOwnedRequestedTarget = await this.hasLayoutOwnedDependencyTarget(
+        _filePath,
+        layoutOwnedPageTargets
+      );
+    }
+    const requestedTargets = changedEntrypointOutput ? hasLayoutOwnedRequestedTarget ? [{ entrypointPath: _filePath, outputUrl: changedEntrypointOutput }, ...layoutOwnedPageTargets] : [{ entrypointPath: _filePath, outputUrl: changedEntrypointOutput }] : hasOwnedLayoutDependencyHit ? await this.collectReactPageBuildTargets() : 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);
+    if (!changedEntrypointOutput) {
+      hasLayoutOwnedRequestedTarget = await this.hasLayoutOwnedDependencyTarget(_filePath, requestedTargets);
+    }
+    const requiresLayoutRefresh = isLayout || hasOwnedLayoutDependencyHit || hasLayoutOwnedRequestedTarget;
     const updates = [];
-    for (const [entrypoint, outputUrl] of entrypointsToBuild) {
-      if (!this.isReactEntrypoint(entrypoint)) {
+    const requestedOutputUrls = new Set(requestedTargets.map((target) => target.outputUrl));
+    if (pageTargets.length > 1) {
+      appLogger.debug(`Bundling ${pageTargets.length} React page entrypoints together`);
+      const rebuiltOutputs = await this.bundleReactEntrypoints(pageTargets);
+      for (const outputUrl of rebuiltOutputs) {
+        if (requestedOutputUrls.has(outputUrl)) {
+          updates.push(outputUrl);
+        }
+      }
+    } else {
+      for (const { entrypointPath, outputUrl } of pageTargets) {
+        appLogger.debug(`Bundling ${entrypointPath}`);
+        const success = await this.bundleReactEntrypoint(entrypointPath, outputUrl);
+        if (success && requestedOutputUrls.has(outputUrl)) {
+          updates.push(outputUrl);
+        }
+      }
+    }
+    for (const { entrypointPath, outputUrl } of nonPageTargets) {
+      if (!this.isReactEntrypoint(entrypointPath)) {
         continue;
       }
-      appLogger.debug(`Bundling ${entrypoint}`);
-      const success = await this.bundleReactEntrypoint(entrypoint, outputUrl);
-      if (success) {
+      appLogger.debug(`Bundling ${entrypointPath}`);
+      const success = await this.bundleReactEntrypoint(entrypointPath, outputUrl);
+      if (success && requestedOutputUrls.has(outputUrl)) {
         updates.push(outputUrl);
       }
     }
     if (updates.length > 0) {
-      if (isLayout) {
+      if (requiresLayoutRefresh) {
         appLogger.debug(`Layout update detected, sending layout-update event`);
         return {
           type: "broadcast",
@@ -188,6 +395,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
@@ -195,19 +407,25 @@ class ReactHmrStrategy extends HmrStrategy {
   async bundleReactEntrypoint(entrypointPath, outputUrl) {
     try {
       const isMdx = entrypointPath.endsWith(".mdx");
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypointPath);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx)$/, ".js");
-      const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
-      const outputPath = path.join(this.context.getDistDir(), encodedPathJs);
+      const { outputPath } = this.getEntrypointOutput(entrypointPath);
       const tempDir = path.dirname(outputPath);
-      const declaredModules = this.pageMetadataCache.getDeclaredModules(entrypointPath) ? this.pageMetadataCache.getDeclaredModules(entrypointPath) : isMdx ? await collectPageDeclaredModules(entrypointPath) : collectPageDeclaredModulesFromModule(await this.importNodePageModule(entrypointPath));
+      const cachedDeclared = this.pageMetadataCache.getDeclaredModules(entrypointPath);
+      let entrypointDeclaredModules;
+      let declaredModules;
+      if (cachedDeclared) {
+        entrypointDeclaredModules = cachedDeclared;
+        declaredModules = cachedDeclared;
+      } else {
+        entrypointDeclaredModules = isMdx ? await collectPageDeclaredModules(entrypointPath) : collectPageDeclaredModulesFromModule(await this.importNodePageModule(entrypointPath));
+        this.pageMetadataCache.setDeclaredModules(entrypointPath, entrypointDeclaredModules);
+        declaredModules = entrypointDeclaredModules;
+      }
       const plugins = this.getBuildPlugins(declaredModules);
       if (isMdx && this.mdxCompilerOptions) {
-        const { createReactMdxLoaderPlugin } = await import("./utils/react-mdx-loader-plugin.js");
         const mdxPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
         plugins.unshift(mdxPlugin);
       }
+      await this.clearHmrOutdir(tempDir);
       const result = await this.context.getBrowserBundleService().bundle({
         profile: "hmr-entrypoint",
         entrypoints: [entrypointPath],
@@ -220,18 +438,154 @@ 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}`);
         return false;
       }
-      const processed = await this.processOutput(tempFile, outputPath, outputUrl);
+      const resolvedTempFile = await this.resolveTempOutputPath(tempFile);
+      if (!resolvedTempFile) {
+        appLogger.debug(`Skipping stale temp output for ${outputUrl}: ${tempFile}`);
+        return false;
+      }
+      const processed = await this.processOutput(resolvedTempFile, outputPath, outputUrl);
       return processed;
     } catch (error) {
       appLogger.error(`Error bundling ${entrypointPath}:`, error);
       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();
+      let shouldEnableMdx = false;
+      for (const { entrypointPath } of entrypoints) {
+        const entrypointDeclaredModules = this.pageMetadataCache.getDeclaredModules(entrypointPath) ? this.pageMetadataCache.getDeclaredModules(entrypointPath) : entrypointPath.endsWith(".mdx") ? await collectPageDeclaredModules(entrypointPath) : collectPageDeclaredModulesFromModule(await this.importNodePageModule(entrypointPath));
+        this.pageMetadataCache.setDeclaredModules(entrypointPath, entrypointDeclaredModules);
+        for (const declaredModule of entrypointDeclaredModules) {
+          declaredModules.add(declaredModule);
+        }
+        if (entrypointPath.endsWith(".mdx")) {
+          shouldEnableMdx = true;
+        }
+      }
+      const plugins = this.getBuildPlugins([...declaredModules]);
+      if (shouldEnableMdx && this.mdxCompilerOptions) {
+        plugins.unshift(createReactMdxLoaderPlugin(this.mdxCompilerOptions));
+      }
+      await this.clearHmrOutdir(this.context.getDistDir());
+      const entryNameByPath = /* @__PURE__ */ new Map();
+      for (const { entrypointPath } of entrypoints) {
+        entryNameByPath.set(entrypointPath, {
+          key: this.getRolldownEntryKey(entrypointPath),
+          basename: this.getTempFileBasename(entrypointPath)
+        });
+      }
+      const result = await this.context.getBrowserBundleService().bundle({
+        profile: "hmr-entrypoint",
+        entrypoints: Object.fromEntries(
+          entrypoints.map(({ entrypointPath }) => [entryNameByPath.get(entrypointPath).key, entrypointPath])
+        ),
+        outdir: this.context.getDistDir(),
+        naming: "[name].[hash].tmp",
+        splitting: true,
+        plugins,
+        minify: false
+      });
+      if (!result.success) {
+        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);
+        const { basename: tempBasename, key: entryKey } = entryNameByPath.get(entrypointPath);
+        const expectedSubdir = path.join(this.context.getDistDir(), path.dirname(entryKey));
+        const tempOutput = result.outputs.find((output) => {
+          return path.dirname(output.path) === expectedSubdir && path.basename(output.path).startsWith(`${tempBasename}.`) && path.basename(output.path).includes(".tmp");
+        })?.path;
+        const resolvedTempOutput = tempOutput ? await this.resolveTempOutputPath(tempOutput) : await this.resolveTempOutputPath(path.join(expectedSubdir, `${tempBasename}.[hash].tmp.js`));
+        if (!resolvedTempOutput) {
+          appLogger.debug(`Missing grouped temp output for ${outputUrl}`);
+          continue;
+        }
+        const processed = await this.processOutput(resolvedTempOutput, outputPath, outputUrl);
+        if (processed) {
+          updatedOutputs.push(outputUrl);
+        }
+      }
+      return updatedOutputs;
+    } catch (error) {
+      appLogger.error(`Error bundling grouped React entrypoints:`, error);
+      return [];
+    }
+  }
+  async resolveTempOutputPath(tempPath) {
+    if (fileSystem.exists(tempPath)) {
+      return tempPath;
+    }
+    if (!tempPath.includes("[hash]")) {
+      return null;
+    }
+    const directory = path.dirname(tempPath);
+    const pattern = path.basename(tempPath).replaceAll("[hash]", "*");
+    const matches = await fileSystem.glob([pattern], { cwd: directory });
+    if (matches.length === 0) {
+      return null;
+    }
+    return path.isAbsolute(matches[0]) ? matches[0] : path.join(directory, matches[0]);
+  }
+  /**
+   * Clears stale HMR output from a directory before a rebuild.
+   *
+   * Only removes:
+   * - `*.tmp.js` files (the per-build bundler output the strategy owns)
+   * - the `chunks/` subdirectory (the bundler's splitting target)
+   *
+   * The HMR runtime script (`_hmr_runtime.js`) and any user-authored
+   * assets in the outdir are preserved. This is the minimal set of
+   * files that, if left from a previous build, can cause the bundler
+   * to emit `ENOENT` for chunk references that point to entrypoints
+   * whose hash has since changed.
+   */
+  async clearHmrOutdir(outdir) {
+    if (!fileSystem.exists(outdir)) {
+      return;
+    }
+    const tempFiles = await fileSystem.glob(["**/*.tmp.js"], { cwd: outdir });
+    await Promise.all(
+      tempFiles.map((relativePath) => {
+        const absolutePath = path.isAbsolute(relativePath) ? relativePath : path.join(outdir, relativePath);
+        return fileSystem.removeAsync(absolutePath).catch(() => void 0);
+      })
+    );
+    const chunksDir = path.join(outdir, "chunks");
+    if (fileSystem.exists(chunksDir)) {
+      await fileSystem.removeAsync(chunksDir).catch(() => void 0);
+    }
+  }
   /**
    * Encodes dynamic route segments (brackets) in file paths.
    * Converts `[slug]` to `_slug_` to avoid filesystem issues.
@@ -239,6 +593,28 @@ class ReactHmrStrategy extends HmrStrategy {
   encodeDynamicSegments(filepath) {
     return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
   }
+  rewriteChunkImportUrls(code) {
+    const hmrChunkBaseUrl = `/${path.join(RESOLVED_ASSETS_DIR, "_hmr").split(path.sep).join("/")}`;
+    return code.replace(/(['"])(?:\.\.\/)+(chunk-[^'"]+\.js)\1/g, (_match, quote, chunkFile) => {
+      return `${quote}${hmrChunkBaseUrl}/${chunkFile}${quote}`;
+    });
+  }
+  isMissingTempOutputError(error) {
+    if (error instanceof FileNotFoundError) {
+      return true;
+    }
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    if (error.message.includes("not found") || error.message.includes("ENOENT")) {
+      return true;
+    }
+    const errorCause = error.cause;
+    if (errorCause instanceof FileNotFoundError) {
+      return true;
+    }
+    return typeof errorCause === "object" && errorCause !== null && "code" in errorCause && errorCause.code === "ENOENT";
+  }
   /**
    * Processes bundled output and injects the React HMR handler.
    * Writes to temp file first, then renames atomically to avoid conflicts.
@@ -255,6 +631,7 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     try {
       let code = await fileSystem.readFile(tempPath);
+      code = this.rewriteChunkImportUrls(code);
       code = injectHmrHandler(code);
       await fileSystem.writeAsync(finalPath, code);
       await fileSystem.removeAsync(tempPath).catch(() => {
@@ -262,7 +639,7 @@ class ReactHmrStrategy extends HmrStrategy {
       appLogger.debug(`Processed ${url} with HMR handler`);
       return true;
     } catch (error) {
-      if (error instanceof FileNotFoundError || error instanceof Error && error.message.includes("not found") || error instanceof Error && "code" in error && error.code === "ENOENT") {
+      if (this.isMissingTempOutputError(error)) {
         appLogger.debug(`Skipping stale temp output for ${url}: ${tempPath}`);
         await fileSystem.removeAsync(tempPath).catch(() => {
         });