@ecopages/react 0.2.0-alpha.53 → 0.2.0-alpha.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react",
-  "version": "0.2.0-alpha.53",
+  "version": "0.2.0-alpha.54",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -69,16 +69,15 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.53",
+    "@ecopages/core": "0.2.0-alpha.54",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.53",
+    "@ecopages/file-system": "0.2.0-alpha.54",
     "@ecopages/logger": "^0.2.3",
-    "@mdx-js/esbuild": "^3.1.1",
     "@mdx-js/mdx": "^3.1.1",
     "oxc-parser": "^0.124.0",
     "oxc-transform": "^0.124.0",

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

@@ -10,6 +10,7 @@ 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 { ClientGraphBoundaryCache } from './utils/client-graph-boundary-cache.js';
 import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
 export interface ReactHmrStrategyOptions {
     context: DefaultHmrContext;
@@ -19,6 +20,13 @@ export interface ReactHmrStrategyOptions {
     ownedTemplateExtensions?: string[];
     allTemplateExtensions?: string[];
     explicitGraphEnabled?: boolean;
+    /**
+     * Per-app cache for client-graph-boundary transform results. Owned by
+     * the React plugin for the app's lifetime. When omitted, the strategy
+     * uses a fresh in-memory cache that does not persist across HMR
+     * rebuilds.
+     */
+    clientGraphBoundaryCache?: ClientGraphBoundaryCache;
 }
 /**
  * Strategy for handling React component HMR updates.
@@ -76,6 +84,8 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private pageMetadataCache;
     private explicitGraphEnabled;
     private readonly runtimeManifest;
+    private readonly clientGraphBoundaryCache;
+    private readonly pagesIndex;
     constructor(options: ReactHmrStrategyOptions);
     /**
      * Returns build plugins for React HMR bundling.
@@ -131,7 +141,8 @@ export declare class ReactHmrStrategy extends HmrStrategy {
     private isLayoutFile;
     private isPageEntrypoint;
     private getEntrypointOutput;
-    private getGroupedTempOutputPattern;
+    private getRolldownEntryKey;
+    private getTempFileBasename;
     private collectReactPageBuildTargets;
     /**
      * Expands one HMR request into the full React page build cohort when needed.
@@ -185,6 +196,20 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      */
     private bundleReactEntrypoints;
     private resolveTempOutputPath;
+    /**
+     * 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.
+     */
+    private clearHmrOutdir;
     /**
      * Encodes dynamic route segments (brackets) in file paths.
      * Converts `[slug]` to `_slug_` to avoid filesystem issues.

package/src/react-hmr-strategy.js

@@ -1,15 +1,17 @@
 import path from "node:path";
 import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
 import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
-import { createBrowserRuntimeImportRewritePlugin } from "@ecopages/core/build/browser-runtime-import-rewrite-plugin";
+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 { 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;
@@ -28,12 +30,20 @@ class ReactHmrStrategy extends HmrStrategy {
   pageMetadataCache;
   explicitGraphEnabled;
   runtimeManifest;
+  clientGraphBoundaryCache;
+  pagesIndex;
   constructor(options) {
     super();
     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(
@@ -54,7 +64,7 @@ class ReactHmrStrategy extends HmrStrategy {
     const allowSpecifiers = getReactClientGraphAllowSpecifiers(
       this.runtimeManifest.assets.map((asset) => asset.specifier)
     );
-    const runtimeRewritePlugin = createBrowserRuntimeImportRewritePlugin({
+    const runtimeRewritePlugin = createBrowserRuntimePlugin({
       name: "react-hmr-runtime-import-rewrite",
       manifest: this.runtimeManifest
     });
@@ -62,7 +72,8 @@ class ReactHmrStrategy extends HmrStrategy {
       createClientGraphBoundaryPlugin({
         absWorkingDir: path.dirname(this.context.getSrcDir()),
         alwaysAllowSpecifiers: allowSpecifiers,
-        declaredModules
+        declaredModules,
+        cache: this.clientGraphBoundaryCache
       }),
       ...runtimeRewritePlugin ? [runtimeRewritePlugin] : [],
       ...this.context.getPlugins()
@@ -189,30 +200,24 @@ class ReactHmrStrategy extends HmrStrategy {
     const outputUrl = `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", encodedPathJs).split(path.sep).join("/")}`;
     return { outputPath, outputUrl };
   }
-  getGroupedTempOutputPattern(entrypointPath) {
+  getRolldownEntryKey(entrypointPath) {
     const srcDir = this.context.getSrcDir();
     const relativePath = path.relative(srcDir, entrypointPath);
-    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx)$/, ".js");
-    return {
-      outputDir: path.join(this.context.getDistDir(), path.dirname(relativePathJs)),
-      outputBaseName: path.basename(relativePathJs, ".js")
-    };
+    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() {
-    const pagesDir = this.context.getPagesDir();
-    const scannedFiles = await fileSystem.glob(
-      this.allTemplateExtensions.map((extension) => `**/*${extension}`),
-      { cwd: pagesDir }
-    );
+    await this.pagesIndex.refresh();
+    const indexed = this.pagesIndex.list();
     const targets = /* @__PURE__ */ new Map();
-    for (const file of scannedFiles) {
-      if (file.includes(".ecopages-node.")) {
-        continue;
-      }
-      const entrypointPath = path.join(pagesDir, file);
-      if (!this.isPageEntrypoint(entrypointPath)) {
-        continue;
-      }
+    for (const entrypointPath of indexed) {
       this.pageMetadataCache.markOwnedEntrypoint(entrypointPath);
       targets.set(entrypointPath, {
         entrypointPath,
@@ -290,8 +295,12 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     const changedEntrypointOutput = watchedFiles.get(_filePath);
     if (changedEntrypointOutput && !this.ownsWatchedEntrypoint(_filePath)) {
-      appLogger.debug(`Skipping non-React watched entrypoint: ${_filePath}`);
-      return { type: "none" };
+      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;
@@ -400,12 +409,23 @@ class ReactHmrStrategy extends HmrStrategy {
       const isMdx = entrypointPath.endsWith(".mdx");
       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 mdxPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
         plugins.unshift(mdxPlugin);
       }
+      await this.clearHmrOutdir(tempDir);
       const result = await this.context.getBrowserBundleService().bundle({
         profile: "hmr-entrypoint",
         entrypoints: [entrypointPath],
@@ -469,12 +489,21 @@ class ReactHmrStrategy extends HmrStrategy {
       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: entrypoints.map(({ entrypointPath }) => entrypointPath),
+        entrypoints: Object.fromEntries(
+          entrypoints.map(({ entrypointPath }) => [entryNameByPath.get(entrypointPath).key, entrypointPath])
+        ),
         outdir: this.context.getDistDir(),
-        outbase: this.context.getSrcDir(),
-        naming: "[dir]/[name].[hash].tmp",
+        naming: "[name].[hash].tmp",
         splitting: true,
         plugins,
         minify: false
@@ -492,11 +521,12 @@ class ReactHmrStrategy extends HmrStrategy {
       const updatedOutputs = [];
       for (const { entrypointPath, outputUrl } of entrypoints) {
         const { outputPath } = this.getEntrypointOutput(entrypointPath);
-        const { outputDir, outputBaseName } = this.getGroupedTempOutputPattern(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) === outputDir && path.basename(output.path).startsWith(`${outputBaseName}.`) && path.basename(output.path).includes(".tmp");
+          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(outputDir, `${outputBaseName}.[hash].tmp.js`));
+        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;
@@ -517,7 +547,7 @@ class ReactHmrStrategy extends HmrStrategy {
       return tempPath;
     }
     if (!tempPath.includes("[hash]")) {
-      return tempPath;
+      return null;
     }
     const directory = path.dirname(tempPath);
     const pattern = path.basename(tempPath).replaceAll("[hash]", "*");
@@ -527,6 +557,35 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     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.

package/src/react.plugin.d.ts

@@ -22,6 +22,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
     private mdxLoaderPlugin;
     private readonly runtimeBundleService;
     private readonly hmrPageMetadataCache;
+    private readonly clientGraphBoundaryCache;
     private runtimeDependenciesInitialized;
     /**
      * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.

package/src/react.plugin.js

@@ -8,6 +8,7 @@ import { ReactHmrStrategy } from "./react-hmr-strategy.js";
 import { ReactRuntimeBundleService } from "./services/react-runtime-bundle.service.js";
 import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-cache.js";
 import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
+import { ClientGraphBoundaryCache } from "./utils/client-graph-boundary-cache.js";
 const appLogger = new Logger("[ReactPlugin]");
 const PLUGIN_NAME = REACT_PLUGIN_NAME;
 const mergePluginLists = (...lists) => {
@@ -72,6 +73,7 @@ class ReactPlugin extends IntegrationPlugin {
   mdxLoaderPlugin;
   runtimeBundleService;
   hmrPageMetadataCache;
+  clientGraphBoundaryCache;
   runtimeDependenciesInitialized = false;
   /**
    * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
@@ -93,6 +95,7 @@ class ReactPlugin extends IntegrationPlugin {
     this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
     this.mdxExtensions = rendererConfig.mdxExtensions ?? [".mdx"];
     this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new ReactHmrPageMetadataCache();
+    this.clientGraphBoundaryCache = new ClientGraphBoundaryCache();
     this.explicitGraphEnabled = rendererConfig.explicitGraphEnabled ?? false;
     this.rendererConfig = {
       ...rendererConfig,
@@ -187,7 +190,8 @@ class ReactPlugin extends IntegrationPlugin {
       mdxCompilerOptions: this.mdxCompilerOptions,
       ownedTemplateExtensions: this.extensions,
       allTemplateExtensions: this.appConfig.templatesExt,
-      explicitGraphEnabled: this.explicitGraphEnabled
+      explicitGraphEnabled: this.explicitGraphEnabled,
+      clientGraphBoundaryCache: this.clientGraphBoundaryCache
     });
   }
 }

package/src/services/pages-index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Per-app index of React-owned page entrypoints.
+ *
+ * @remarks
+ * The HMR strategy previously called `fileSystem.glob` on every
+ * layout change. For apps with many pages this is wasteful: O(pages)
+ * on every HMR event, and the result rarely changes between HMR
+ * rebuilds.
+ *
+ * `PagesIndex` maintains a `Set` of owned page entrypoint paths. The
+ * initial population is a single glob; subsequent mutations go through
+ * `add` / `remove` (called by the HMR strategy when it observes a
+ * file create/delete under `pagesDir`). The strategy reads via
+ * `list()` for an O(1) snapshot of the current set.
+ *
+ * Phase 1 ships the class and the `list()` consumer. Watcher-driven
+ * `add` / `remove` integration lands in a follow-up — for now the
+ * strategy calls `refresh()` lazily, which is equivalent to the old
+ * glob behavior but with a stable API for the future incremental
+ * path.
+ */
+export type PagesIndexOptions = {
+    pagesDir: string;
+    extensions?: string[];
+    /**
+     * Optional predicate to filter out non-page entrypoints (e.g.
+     * test fixtures, generated files). Defaults to including every
+     * file matching an extension.
+     */
+    isPageEntrypoint?: (absolutePath: string) => boolean;
+};
+export declare class PagesIndex {
+    private readonly pagesDir;
+    private readonly extensions;
+    private readonly isPageEntrypoint;
+    private readonly pages;
+    private lastRefreshAt;
+    constructor(options: PagesIndexOptions);
+    /**
+     * 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.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Add a single entrypoint. Idempotent.
+     */
+    add(absolutePath: string): void;
+    /**
+     * Remove a single entrypoint. Idempotent.
+     */
+    remove(absolutePath: string): void;
+    /** True if the index contains `absolutePath`. */
+    has(absolutePath: string): boolean;
+    /** Snapshot of the current set, sorted by absolute path. */
+    list(): string[];
+    /** Number of indexed entrypoints. */
+    get size(): number;
+    /** Last refresh timestamp (ms since epoch). */
+    get refreshedAt(): number;
+}

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
@@ -34,7 +34,7 @@ export interface ReactClientBundleOptions {
     splitting?: boolean;
 }
 /**
- * Manages esbuild bundle configuration and plugin creation for React page/component builds.
+ * Manages bundle configuration and plugin creation for React page/component builds.
  */
 export declare class ReactBundleService {
     private readonly runtimeBundleService;
@@ -45,7 +45,7 @@ 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

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

@@ -3,7 +3,7 @@ import {
   getReactClientGraphAllowSpecifiers,
   getReactRuntimeExternalSpecifiers
 } from "../utils/react-runtime-alias-map.js";
-import { createBrowserRuntimeImportRewritePlugin } from "@ecopages/core/build/browser-runtime-import-rewrite-plugin";
+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";
@@ -24,7 +24,7 @@ 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
@@ -67,7 +67,7 @@ class ReactBundleService {
       foreignExtensions: this.config.nonReactExtensions ?? []
     });
     const runtimeManifest = this.runtimeBundleService.getRuntimeManifest();
-    const runtimeRewritePlugin = createBrowserRuntimeImportRewritePlugin({
+    const runtimeRewritePlugin = createBrowserRuntimePlugin({
       name: "react-renderer-runtime-import-rewrite",
       manifest: runtimeManifest
     });

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

@@ -14,7 +14,7 @@ export declare class ReactHmrPageMetadataCache {
     /**
      * 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.
      */

package/src/services/react-page-module.service.d.ts

@@ -7,7 +7,7 @@
  * @module
  */
 import type { EcoComponentConfig, EcoPageFile } from '@ecopages/core';
-import type { BuildExecutor } from '@ecopages/core/build/build-adapter';
+import { type BuildExecutor } from '@ecopages/core/build/build-adapter';
 import type { CompileOptions } from '@mdx-js/mdx';
 /**
  * Configuration for the ReactPageModuleService.

package/src/services/react-page-module.service.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { rapidhash } from "@ecopages/core/hash";
 import { build } from "@ecopages/core/build/build-adapter";
+import { normalizeNodeRuntimeBuildOutputFile } from "@ecopages/core/build/runtime-build-output-normalizer";
+import { rapidhash } from "@ecopages/core/hash";
 import { fileSystem } from "@ecopages/file-system";
 import { someInConfigTree } from "../utils/component-config-traversal.js";
 import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
@@ -51,6 +52,7 @@ class ReactPageModuleService {
         splitting: false,
         minify: false,
         treeshaking: false,
+        externalPackages: true,
         naming: outputNamingTemplate,
         plugins: [mdxPlugin]
       },
@@ -65,6 +67,7 @@ class ReactPageModuleService {
     if (!compiledOutput) {
       throw new Error(`No compiled MDX output generated for page: ${filePath}`);
     }
+    normalizeNodeRuntimeBuildOutputFile(compiledOutput, this.config.rootDir);
     const compiledOutputUrl = pathToFileURL(compiledOutput);
     if (process?.env?.NODE_ENV === "development" || options?.cacheScope) {
       compiledOutputUrl.searchParams.set(

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

@@ -1,8 +1,5 @@
-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 { createBrowserRuntimePlugin } from "@ecopages/core/build/browser-runtime-plugin";
+import { DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME } from "@ecopages/core/build/browser-runtime-plugin";
 import {
   buildBrowserRuntimeAssetUrl,
   createBrowserRuntimeModuleAsset,
@@ -50,7 +47,7 @@ class ReactRuntimeBundleService {
     return mode === "development" ? "use-sync-external-store-with-selector.development.js" : "use-sync-external-store-with-selector.js";
   }
   createReactVendorImportRewritePlugin(mode) {
-    return createBrowserRuntimeImportRewritePlugin({
+    return createBrowserRuntimePlugin({
       name: `react-plugin-vendor-runtime-import-rewrite-${mode}`,
       manifest: createBrowserRuntimeManifest([
         {
@@ -93,12 +90,17 @@ class ReactRuntimeBundleService {
       const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin({
         reactSpecifier: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
       });
-      const reactRuntimeAliasPlugin = createRuntimeSpecifierAliasPlugin(
-        {
-          react: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
-        },
-        { name: `react-plugin-runtime-specifier-alias-${mode}` }
-      );
+      const reactRuntimeAliasPlugin = createBrowserRuntimePlugin({
+        name: `react-plugin-runtime-specifier-alias-${mode}`,
+        manifest: createBrowserRuntimeManifest([
+          {
+            specifier: "react",
+            owner: "",
+            importPath: "react",
+            publicPath: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
+          }
+        ])
+      });
       const reactDomBundlePlugins = [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin].filter(
         (plugin) => plugin !== null
       );
@@ -117,7 +119,7 @@ class ReactRuntimeBundleService {
           rootDir: this.config.rootDir,
           bundleOptions: {
             define: this.createRuntimeDefines(mode),
-            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME]
+            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME]
           }
         }),
         createBrowserRuntimeModuleAsset({
@@ -128,7 +130,7 @@ class ReactRuntimeBundleService {
           rootDir: this.config.rootDir,
           bundleOptions: {
             define: this.createRuntimeDefines(mode),
-            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME],
+            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
             plugins: reactDomBundlePlugins
           }
         }),
@@ -138,7 +140,7 @@ class ReactRuntimeBundleService {
           fileName: this.getUseSyncExternalStoreWithSelectorVendorFileName(mode),
           bundleOptions: {
             define: this.createRuntimeDefines(mode),
-            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_IMPORT_REWRITE_PLUGIN_NAME],
+            excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
             plugins: [reactVendorImportRewritePlugin]
           }
         })
@@ -164,8 +166,18 @@ class ReactRuntimeBundleService {
     return dependencies;
   }
   createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode()) {
-    return createRuntimeSpecifierAliasPlugin(this.getRuntimeAliasMap(mode), {
-      name: `react-plugin-runtime-alias-${mode}`
+    const aliasMap = this.getRuntimeAliasMap(mode);
+    const manifest = createBrowserRuntimeManifest(
+      Object.entries(aliasMap).map(([specifier, publicPath]) => ({
+        specifier,
+        owner: "",
+        importPath: specifier,
+        publicPath
+      }))
+    );
+    return createBrowserRuntimePlugin({
+      name: `react-plugin-runtime-alias-${mode}`,
+      manifest
     });
   }
 }

package/src/utils/client-graph-boundary-cache.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Per-app persistent cache for `client-graph-boundary` plugin transforms.
+ *
+ * @remarks
+ * The plugin's `transformModuleImports` function is the second most
+ * expensive operation in the React build path (after `parseSync`).
+ * It walks the AST to find reachable exports and prunes forbidden
+ * imports. On a no-op rebuild (file unchanged, no plugin signature
+ * change) the entire walk can be skipped if the inputs are identical.
+ *
+ * This cache is owned by the {@link ReactPlugin} for the app's lifetime.
+ * It persists across HMR rebuilds but is invalidated per-file when the
+ * watcher detects a source change. The `requestedExports` registry
+ * remains per-build (it's mutated during cross-file propagation and
+ * must not accumulate stale state across builds).
+ *
+ * The cache is content-hashed (via `rapidhash`) so a `touch`/`utimes`
+ * does not invalidate a still-valid entry.
+ *
+ * **`rulesAdded` semantics:** the map holds the **after-state** of
+ * every registry key this transform touched — both newly added keys
+ * and keys that were grown (Set union) or promoted to `'*'`. On
+ * replay the cache applies each entry via the same merge rules the
+ * live transform uses (`mergeRequestedExportRules`), so a key that
+ * was already in the live registry when the transform ran and grew
+ * during the transform is correctly grown on replay against a fresh
+ * registry as well.
+ */
+export type RequestedExportRules = Set<string> | '*';
+export type CachedTransform = {
+    /** Hash of the source string at the time the transform was cached. */
+    sourceHash: number | bigint;
+    /** Hash of the globally-allowed modules map at the time the transform was cached. */
+    allowListHash: number | bigint;
+    /** The transformed source (or original if `modified` is false). */
+    transformed: string;
+    /** Whether the transform changed the source. */
+    modified: boolean;
+    /**
+     * Map of `requestedExports` keys this transform touched, mapped to
+     * their **after-state**. Includes:
+     * - newly-added keys
+     * - keys whose Set grew (union of pre-existing and newly reachable exports)
+     * - keys promoted to `'*'`
+     *
+     * On cache hit, each entry is replayed via `mergeRequestedExportRules`,
+     * which handles all three cases correctly. Defensively copied at
+     * `set()` time to prevent later mutation from corrupting the cache.
+     */
+    rulesAdded: Map<string, RequestedExportRules>;
+};
+/**
+ * LRU-bounded cache for client-graph-boundary transform results.
+ *
+ * One instance is owned by the React plugin for the app's lifetime and
+ * shared across all builds. The cache key is `(filePath, source, allowList)`
+ * so a file whose source or whose global allow list changes gets a fresh
+ * entry, while everything else hits.
+ */
+export declare class ClientGraphBoundaryCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    /**
+     * Look up a cached transform for `filePath`.
+     *
+     * Returns `undefined` if the source or allow list has changed since
+     * the entry was stored. The caller is responsible for re-running the
+     * transform in that case and calling `set` to update the entry.
+     */
+    get(filePath: string, source: string, globallyAllowedSpecifiers: Iterable<string>): CachedTransform | undefined;
+    /**
+     * Store a transform result.
+     *
+     * Evicts the least recently used entry if the cache exceeds its
+     * capacity. Defensively copies any `Set`-typed rules in `rulesAdded`
+     * so later mutations to the caller's sets cannot corrupt the cache.
+     */
+    set(filePath: string, source: string, globallyAllowedSpecifiers: Iterable<string>, entry: Omit<CachedTransform, 'sourceHash' | 'allowListHash'>): void;
+    /**
+     * Invalidate a single file's entry. Call this from the file watcher
+     * when `filePath`'s content has changed.
+     */
+    invalidate(filePath: string): void;
+    /**
+     * Invalidate every file whose key matches a prefix. Useful for
+     * "anything under `src/pages/` changed" signals.
+     */
+    invalidateMatching(predicate: (filePath: string) => boolean): number;
+    /** Clear all entries. */
+    clear(): void;
+    /** Current cache size. */
+    get size(): number;
+    /** Hit/miss counters for observability. */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        hitRate: number;
+    };
+}
+/**
+ * Default shared cache. The React plugin owns one of these; tests can
+ * create their own.
+ */
+export declare const clientGraphBoundaryCache: ClientGraphBoundaryCache;

package/src/utils/client-graph-boundary-cache.js

@@ -0,0 +1,116 @@
+import { rapidhash } from "@ecopages/core/utils/hash";
+const DEFAULT_MAX_ENTRIES = 5e3;
+function cloneRules(rules) {
+  return rules instanceof Set ? new Set(rules) : rules;
+}
+class ClientGraphBoundaryCache {
+  entries = /* @__PURE__ */ new Map();
+  maxEntries;
+  hits = 0;
+  misses = 0;
+  constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    if (maxEntries <= 0) {
+      throw new Error(`ClientGraphBoundaryCache: maxEntries must be > 0, got ${maxEntries}`);
+    }
+    this.maxEntries = maxEntries;
+  }
+  /**
+   * Look up a cached transform for `filePath`.
+   *
+   * Returns `undefined` if the source or allow list has changed since
+   * the entry was stored. The caller is responsible for re-running the
+   * transform in that case and calling `set` to update the entry.
+   */
+  get(filePath, source, globallyAllowedSpecifiers) {
+    const sourceHash = rapidhash(source);
+    const allowListHash = hashAllowList(globallyAllowedSpecifiers);
+    const existing = this.entries.get(filePath);
+    if (existing && existing.sourceHash === sourceHash && existing.allowListHash === allowListHash) {
+      this.hits += 1;
+      this.entries.delete(filePath);
+      this.entries.set(filePath, existing);
+      return existing;
+    }
+    this.misses += 1;
+    return void 0;
+  }
+  /**
+   * Store a transform result.
+   *
+   * Evicts the least recently used entry if the cache exceeds its
+   * capacity. Defensively copies any `Set`-typed rules in `rulesAdded`
+   * so later mutations to the caller's sets cannot corrupt the cache.
+   */
+  set(filePath, source, globallyAllowedSpecifiers, entry) {
+    const sourceHash = rapidhash(source);
+    const allowListHash = hashAllowList(globallyAllowedSpecifiers);
+    const rulesAddedCopy = /* @__PURE__ */ new Map();
+    for (const [key, rules] of entry.rulesAdded) {
+      rulesAddedCopy.set(key, cloneRules(rules));
+    }
+    const full = {
+      sourceHash,
+      allowListHash,
+      transformed: entry.transformed,
+      modified: entry.modified,
+      rulesAdded: rulesAddedCopy
+    };
+    this.entries.set(filePath, full);
+    if (this.entries.size > this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.entries.delete(oldestKey);
+      }
+    }
+  }
+  /**
+   * Invalidate a single file's entry. Call this from the file watcher
+   * when `filePath`'s content has changed.
+   */
+  invalidate(filePath) {
+    this.entries.delete(filePath);
+  }
+  /**
+   * Invalidate every file whose key matches a prefix. Useful for
+   * "anything under `src/pages/` changed" signals.
+   */
+  invalidateMatching(predicate) {
+    let removed = 0;
+    for (const key of this.entries.keys()) {
+      if (predicate(key)) {
+        this.entries.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+  /** Clear all entries. */
+  clear() {
+    this.entries.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+  /** Current cache size. */
+  get size() {
+    return this.entries.size;
+  }
+  /** Hit/miss counters for observability. */
+  stats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.entries.size,
+      hitRate: total === 0 ? 0 : this.hits / total
+    };
+  }
+}
+const clientGraphBoundaryCache = new ClientGraphBoundaryCache();
+function hashAllowList(specifiers) {
+  const sorted = Array.from(specifiers).sort();
+  return rapidhash(sorted.join("\n"));
+}
+export {
+  ClientGraphBoundaryCache,
+  clientGraphBoundaryCache
+};

package/src/utils/client-graph-boundary-plugin.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module ClientGraphBoundaryPlugin
  *
- * This module defines the primary esbuild plugin responsible for securing the Ecopages
+ * This module defines the primary build plugin responsible for securing the Ecopages
  * isomorphic compilation pipeline. It ensures that backend-only code, sensitive Node.js APIs,
  * and massive server utilities do not accidentally leak into the browser bundle.
  *
@@ -15,8 +15,9 @@
  * inlines `fs.readFileSync(path.resolve(...))` calls to prevent server/client data mismatches.
  */
 import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import { ClientGraphBoundaryCache } from './client-graph-boundary-cache.js';
 /**
- * Configuration options for the Client Graph Boundary esbuild plugin.
+ * Configuration options for the Client Graph Boundary build plugin.
  *
  * This plugin serves as the primary security layer between server-only logic and the client-side JavaScript bundle.
  * It prevents Node.js built-ins (`node:fs`, `node:path`) and backend-exclusive dependencies (e.g. `pg`, `redis`)
@@ -29,12 +30,19 @@ type ClientGraphBoundaryOptions = {
      * Array of module specifiers that are explicitly whitelisted to be bundled in the client code.
      * This is typically populated by parsing `modules: ["..."]` declarations in React/Lit components.
      */
-    declaredModules?: string[];
+    declaredModules?: readonly string[];
     /** Array of emergency escape-hatch specifiers that always bypass the boundary checks regardless of component declarations. */
     alwaysAllowSpecifiers?: string[];
+    /**
+     * Persistent per-app cache for transform results. Owned by the React
+     * plugin for the app's lifetime; survives across HMR rebuilds. When
+     * omitted, transforms are still memoized inside the plugin for the
+     * duration of a single build but not across builds.
+     */
+    cache?: ClientGraphBoundaryCache;
 };
 /**
- * Instantiates the client graph boundary esbuild plugin.
+ * Instantiates the client graph boundary build plugin.
  *
  * @param options - Configuration options for the graph boundary.
  * @returns The resulting `EcoBuildPlugin`.

package/src/utils/client-graph-boundary-plugin.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, extname, resolve } from "node:path";
-import { parseSync } from "oxc-parser";
+import { cachedParseSync } from "@ecopages/core/cache";
+import { ClientGraphBoundaryCache } from "./client-graph-boundary-cache.js";
 import { analyzeReachability } from "./reachability-analyzer.js";
 const SOURCE_FILE_FILTER = /\.(tsx?|jsx?)$/;
 const SERVER_ONLY_ECO_PAGE_OPTION_KEYS = /* @__PURE__ */ new Set([
@@ -180,10 +181,38 @@ function mergeRequestedExportRules(registry, moduleKey, rules) {
     existing.add(rule);
   }
 }
+function cloneRequestedExportRules(rules) {
+  return rules === "*" ? rules : new Set(rules);
+}
+function snapshotRegistry(registry) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [key, rules] of registry) {
+    out.set(key, cloneRequestedExportRules(rules));
+  }
+  return out;
+}
+function diffRequestedExportRules(before, after) {
+  if (!before) {
+    return cloneRequestedExportRules(after);
+  }
+  if (before === "*") {
+    return void 0;
+  }
+  if (after === "*") {
+    return "*";
+  }
+  const addedRules = /* @__PURE__ */ new Set();
+  for (const rule of after) {
+    if (!before.has(rule)) {
+      addedRules.add(rule);
+    }
+  }
+  return addedRules.size > 0 ? addedRules : void 0;
+}
 function transformModuleImports(source, filename, globallyAllowed, requestedExports) {
   let result;
   try {
-    result = parseSync(filename, source, {
+    result = cachedParseSync(filename, source, {
       sourceType: "module",
       lang: parserLanguageForFile(filename)
     });
@@ -414,7 +443,7 @@ function transformModuleImports(source, filename, globallyAllowed, requestedExpo
   }
   let reparsedResult;
   try {
-    reparsedResult = parseSync(filename, transformed, {
+    reparsedResult = cachedParseSync(filename, transformed, {
       sourceType: "module",
       lang: parserLanguageForFile(filename)
     });
@@ -432,11 +461,13 @@ function createClientGraphBoundaryPlugin(options) {
     name: "ecopages-client-graph-boundary",
     setup(build) {
       const absWorkingDir = options?.absWorkingDir ?? process.cwd();
+      const cache = options?.cache;
       const globallyDeclaredSources = parseDeclaredModules(options?.declaredModules);
       const requestedExports = /* @__PURE__ */ new Map();
       for (const alwaysAllow of options?.alwaysAllowSpecifiers ?? []) {
         globallyDeclaredSources.set(toModuleBaseSpecifier(alwaysAllow), "*");
       }
+      const allowListForCache = Array.from(globallyDeclaredSources.keys()).sort();
       build.onLoad({ filter: SOURCE_FILE_FILTER }, (args) => {
         let source;
         try {
@@ -444,6 +475,17 @@ function createClientGraphBoundaryPlugin(options) {
         } catch {
           return void 0;
         }
+        if (cache) {
+          const cached = cache.get(args.path, source, allowListForCache);
+          if (cached) {
+            for (const [moduleKey, rules] of cached.rulesAdded) {
+              mergeRequestedExportRules(requestedExports, moduleKey, rules);
+            }
+            if (!cached.modified) return void 0;
+            const ext2 = extname(args.path).slice(1);
+            return { contents: cached.transformed, loader: ext2, resolveDir: dirname(args.path) };
+          }
+        }
         let transformed = source;
         let modified = false;
         if (source.includes("readFileSync")) {
@@ -472,6 +514,7 @@ function createClientGraphBoundaryPlugin(options) {
           );
           transformed = readFileTransformed;
         }
+        const registryBefore = snapshotRegistry(requestedExports);
         const { transformed: oxcTransformed, modified: importsModified } = transformModuleImports(
           transformed,
           args.path,
@@ -482,6 +525,21 @@ function createClientGraphBoundaryPlugin(options) {
           modified = true;
           transformed = oxcTransformed;
         }
+        if (cache) {
+          const rulesAdded = /* @__PURE__ */ new Map();
+          for (const [key, afterRules] of requestedExports) {
+            const beforeRules = registryBefore.get(key);
+            const diff = diffRequestedExportRules(beforeRules, afterRules);
+            if (!diff) continue;
+            rulesAdded.set(key, diff);
+          }
+          const entry = {
+            transformed,
+            modified,
+            rulesAdded
+          };
+          cache.set(args.path, source, allowListForCache, entry);
+        }
         if (!modified) return void 0;
         const ext = extname(args.path).slice(1);
         return { contents: transformed, loader: ext, resolveDir: dirname(args.path) };