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

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.
  *
@@ -14,9 +14,10 @@
  * Additionally, this plugin provides a build-time transform that statically resolves and
  * inlines `fs.readFileSync(path.resolve(...))` calls to prevent server/client data mismatches.
  */
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+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,7 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, extname, resolve } from "node:path";
-import { parseSync } from "oxc-parser";
-import { analyzeReachability } from "./reachability-analyzer";
+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([
   "cache",
@@ -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,9 +525,24 @@ 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 };
+        return { contents: transformed, loader: ext, resolveDir: dirname(args.path) };
       });
     }
   };

package/src/utils/component-config-traversal.d.ts

@@ -0,0 +1,36 @@
+import type { EcoComponent, EcoComponentConfig } from '@ecopages/core';
+/**
+ * Walks a component config tree once, including nested layout configs and
+ * dependency component configs.
+ *
+ * The shared React integration code performs several different analyses over the
+ * same config graph. Centralizing the traversal keeps cycle handling and graph
+ * shape assumptions in one place instead of repeating them in the renderer and
+ * services.
+ */
+export declare function walkConfigTree(config: EcoComponentConfig | undefined, visitor: (config: EcoComponentConfig) => void, visited?: Set<EcoComponentConfig>): void;
+/**
+ * Walks a forest of root component configs using one shared visited set.
+ *
+ * This is useful when a page contributes multiple config roots, such as a page
+ * config plus a resolved layout config, and duplicate nested nodes should still
+ * be processed only once.
+ */
+export declare function walkConfigForest(configs: Iterable<EcoComponentConfig | undefined>, visitor: (config: EcoComponentConfig) => void): void;
+/**
+ * Collects values from a config tree while preserving the shared traversal and
+ * cycle protection behavior used across the React integration.
+ */
+export declare function collectFromConfigTree<T>(config: EcoComponentConfig | undefined, collector: (config: EcoComponentConfig) => T[]): T[];
+/**
+ * Collects values from multiple config roots with one shared visited set.
+ */
+export declare function collectFromConfigForest<T>(configs: Iterable<EcoComponentConfig | undefined>, collector: (config: EcoComponentConfig) => T[]): T[];
+/**
+ * Returns true when any node in the config tree matches the predicate.
+ */
+export declare function someInConfigTree(config: EcoComponentConfig | undefined, predicate: (config: EcoComponentConfig) => boolean): boolean;
+/**
+ * Reads config roots from partial components while tolerating undefined config.
+ */
+export declare function getComponentConfigs(components: Partial<EcoComponent>[]): Array<EcoComponentConfig | undefined>;

package/src/utils/component-config-traversal.js

@@ -0,0 +1,54 @@
+function walkConfigTree(config, visitor, visited = /* @__PURE__ */ new Set()) {
+  if (!config || visited.has(config)) {
+    return;
+  }
+  visited.add(config);
+  visitor(config);
+  if (config.layout?.config) {
+    walkConfigTree(config.layout.config, visitor, visited);
+  }
+  for (const component of config.dependencies?.components ?? []) {
+    walkConfigTree(component.config, visitor, visited);
+  }
+}
+function walkConfigForest(configs, visitor) {
+  const visited = /* @__PURE__ */ new Set();
+  for (const config of configs) {
+    walkConfigTree(config, visitor, visited);
+  }
+}
+function collectFromConfigTree(config, collector) {
+  const values = [];
+  walkConfigTree(config, (node) => {
+    values.push(...collector(node));
+  });
+  return values;
+}
+function collectFromConfigForest(configs, collector) {
+  const values = [];
+  walkConfigForest(configs, (node) => {
+    values.push(...collector(node));
+  });
+  return values;
+}
+function someInConfigTree(config, predicate) {
+  let matched = false;
+  walkConfigTree(config, (node) => {
+    if (matched) {
+      return;
+    }
+    matched = predicate(node);
+  });
+  return matched;
+}
+function getComponentConfigs(components) {
+  return components.map((component) => component.config);
+}
+export {
+  collectFromConfigForest,
+  collectFromConfigTree,
+  getComponentConfigs,
+  someInConfigTree,
+  walkConfigForest,
+  walkConfigTree
+};

package/src/utils/declared-modules.d.ts

@@ -29,7 +29,7 @@ export declare function normalizeDeclaredModuleSources(modules?: string[]): stri
  * Recursively walks a component config tree (including layouts and nested
  * `dependencies.components`) to collect all declared module sources.
  */
-export declare function collectDeclaredModulesInConfig(config: EcoComponentConfig | undefined, visited?: Set<EcoComponentConfig>): string[];
+export declare function collectDeclaredModulesInConfig(config: EcoComponentConfig | undefined): string[];
 /**
  * Collects declared module sources from an already imported page module.
  */

package/src/utils/declared-modules.js

@@ -1,3 +1,4 @@
+import { collectFromConfigTree } from "./component-config-traversal.js";
 function parseDeclaredModuleSource(value) {
   const source = value.trim();
   if (source.length === 0) return void 0;
@@ -16,21 +17,8 @@ function normalizeDeclaredModuleSources(modules) {
   }
   return Array.from(seen);
 }
-function collectDeclaredModulesInConfig(config, visited = /* @__PURE__ */ new Set()) {
-  if (!config || visited.has(config)) {
-    return [];
-  }
-  visited.add(config);
-  const declarations = normalizeDeclaredModuleSources(config.dependencies?.modules);
-  if (config.layout?.config) {
-    declarations.push(...collectDeclaredModulesInConfig(config.layout.config, visited));
-  }
-  for (const component of config.dependencies?.components ?? []) {
-    if (component.config) {
-      declarations.push(...collectDeclaredModulesInConfig(component.config, visited));
-    }
-  }
-  return declarations;
+function collectDeclaredModulesInConfig(config) {
+  return collectFromConfigTree(config, (node) => normalizeDeclaredModuleSources(node.dependencies?.modules));
 }
 function collectPageDeclaredModulesFromModule(pageModule) {
   const declarations = [
@@ -41,7 +29,10 @@ function collectPageDeclaredModulesFromModule(pageModule) {
 }
 async function collectPageDeclaredModules(pagePath) {
   try {
-    const pageModule = await import(pagePath);
+    const pageModule = await import(
+      /* @vite-ignore */
+      pagePath
+    );
     return collectPageDeclaredModulesFromModule(pageModule);
   } catch {
     return [];

package/src/utils/dynamic.test.browser.d.ts

@@ -0,0 +1 @@
+export {};

package/src/utils/dynamic.test.browser.js

@@ -0,0 +1,33 @@
+import { jsx } from "react/jsx-runtime";
+import { Suspense } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import { dynamic } from "./dynamic.js";
+function createDeferredImport() {
+  let resolve;
+  const promise = new Promise((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return {
+    promise,
+    resolve
+  };
+}
+describe("dynamic", () => {
+  afterEach(() => {
+    cleanup();
+  });
+  it("returns a browser lazy component that resolves through Suspense", async () => {
+    const deferredImport = createDeferredImport();
+    const DynamicComponent = dynamic(() => deferredImport.promise);
+    render(
+      /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx("span", { children: "Loading dynamic component" }), children: /* @__PURE__ */ jsx(DynamicComponent, {}) })
+    );
+    expect(screen.getByText("Loading dynamic component")).toBeTruthy();
+    deferredImport.resolve({
+      default: () => /* @__PURE__ */ jsx("span", { children: "Dynamic content" })
+    });
+    expect(await screen.findByText("Dynamic content")).toBeTruthy();
+    expect(screen.queryByText("Loading dynamic component")).toBeNull();
+  });
+});

package/src/utils/hydration-scripts.d.ts

@@ -1,6 +1,6 @@
 /**
  * Hydration script generators for React pages.
- * These functions create the client-side scripts that hydrate React components.
+ * These functions create the page entry modules that hydrate React routes.
  * @module
  */
 import type { ReactRouterAdapter } from '../router-adapter.js';
@@ -8,8 +8,12 @@ import type { ReactRouterAdapter } from '../router-adapter.js';
  * Options for generating a hydration script.
  */
 export type HydrationScriptOptions = {
-    /** The import path for the bundled page component */
+    /** The module path imported by the page entry module. */
     importPath: string;
+    /** Browser expression that resolves to the page module URL the router should import. */
+    pageModuleUrlExpression?: string;
+    /** Stable id of the page entry script tag in the document. */
+    scriptId: string;
     /** Direct import path for React runtime module */
     reactImportPath: string;
     /** Direct import path for react-dom/client runtime module */
@@ -26,14 +30,14 @@ export type HydrationScriptOptions = {
 export type IslandHydrationScriptOptions = {
     /** Bundled browser module path for the island component. */
     importPath: string;
+    /** Stable id of the island bootstrap script tag in the document. */
+    scriptId: string;
     /** Browser import path for React runtime. */
     reactImportPath: string;
     /** Browser import path for react-dom/client runtime. */
     reactDomClientImportPath: string;
-    /** Selector that resolves to the SSR root element for this island instance. */
+    /** Selector that resolves to all SSR root elements for this island component. */
     targetSelector: string;
-    /** Serialized component props emitted at render time. */
-    props: Record<string, unknown>;
     /** Optional stable component id used to resolve named exports reliably. */
     componentRef?: string;
     /** Optional source file hint used as fallback for component resolution. */