@ecopages/react 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/utils/reachability-analyzer.d.ts

@@ -42,6 +42,15 @@ export type ReachabilityResult = {
      */
     analyzed: boolean;
 };
+/**
+ * Optional export filter supplied by the client graph boundary when a local
+ * module is imported through a narrower named-export surface.
+ *
+ * `'*'` means the whole module namespace is considered reachable, while a
+ * `Set` restricts analysis to the named exports that are actually requested by
+ * downstream client-reachable modules.
+ */
+type ExplicitlyRequestedExports = Set<string> | '*';
 /**
  * Analyzes a module using Oxc AST and extracts a strict reachability graph
  * starting from client roots (`render`, `errorBoundary`, `loadingFallback` of `eco.page` or `eco.component`).
@@ -50,6 +59,8 @@ export type ReachabilityResult = {
  * @param filename - Absolute or relative path to the module file.
  * @param program - Optional pre-parsed Oxc program AST. When supplied, the
  *   internal `parseSync` call is skipped entirely (avoids double-parsing).
+ * @param explicitlyRequestedExports - Optional named export filter propagated
+ *   from a downstream importer when this module is only partially reachable.
  */
-export declare function analyzeReachability(source: string, filename: string, program?: ReturnType<typeof parseSync>['program']): ReachabilityResult;
+export declare function analyzeReachability(source: string, filename: string, program?: ReturnType<typeof parseSync>['program'], explicitlyRequestedExports?: ExplicitlyRequestedExports): ReachabilityResult;
 export {};

package/src/utils/reachability-analyzer.js

@@ -7,7 +7,7 @@ function parserLanguageForFile(filename) {
   if (extension === ".jsx") return "jsx";
   return "js";
 }
-function analyzeReachability(source, filename, program) {
+function analyzeReachability(source, filename, program, explicitlyRequestedExports) {
   let resolvedProgram;
   if (program) {
     resolvedProgram = program;
@@ -114,12 +114,86 @@ function analyzeReachability(source, filename, program) {
       potentialClientRoots.push(node);
     }
   }
+  function getExportedName(specifier) {
+    if (specifier?.exported?.type === "Identifier") return specifier.exported.name;
+    if (typeof specifier?.exported?.value === "string") return specifier.exported.value;
+    if (specifier?.local?.type === "Identifier") return specifier.local.name;
+    if (typeof specifier?.local?.value === "string") return specifier.local.value;
+    return void 0;
+  }
+  function getReexportedImportName(specifier) {
+    if (specifier?.local?.type === "Identifier") return specifier.local.name;
+    if (typeof specifier?.local?.value === "string") return specifier.local.value;
+    if (specifier?.imported?.type === "Identifier") return specifier.imported.name;
+    if (typeof specifier?.imported?.value === "string") return specifier.imported.value;
+    return getExportedName(specifier);
+  }
+  function getLocalExportName(specifier) {
+    if (specifier?.local?.type === "Identifier") return specifier.local.name;
+    if (typeof specifier?.local?.value === "string") return specifier.local.value;
+    return void 0;
+  }
+  function isExplicitlyRequestedExport(name) {
+    if (explicitlyRequestedExports === "*") return true;
+    return explicitlyRequestedExports?.has(name) ?? false;
+  }
   let isFallbackRoots = false;
   if (potentialClientRoots.length === 0) {
-    isFallbackRoots = true;
-    for (const node of resolvedProgram.body) {
-      if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration" || node.type === "ExportAllDeclaration") {
-        potentialClientRoots.push(node);
+    if (explicitlyRequestedExports) {
+      for (const node of resolvedProgram.body) {
+        if (node.type === "ExportNamedDeclaration") {
+          const exportNode = node;
+          if (exportNode.source && exportNode.specifiers?.length) {
+            const hasRequestedReexport = exportNode.specifiers.some((specifier) => {
+              const exportedName = getExportedName(specifier);
+              return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
+            });
+            if (hasRequestedReexport) {
+              potentialClientRoots.push(node);
+            }
+            continue;
+          }
+          if (exportNode.declaration?.type === "FunctionDeclaration" || exportNode.declaration?.type === "ClassDeclaration") {
+            const declarationName = exportNode.declaration.id?.name;
+            if (declarationName && isExplicitlyRequestedExport(declarationName)) {
+              potentialClientRoots.push(node);
+            }
+            continue;
+          }
+          if (exportNode.declaration?.type === "VariableDeclaration") {
+            const hasRequestedDeclaration = exportNode.declaration.declarations.some(
+              (declaration) => declaration.id?.type === "Identifier" && isExplicitlyRequestedExport(declaration.id.name)
+            );
+            if (hasRequestedDeclaration) {
+              potentialClientRoots.push(node);
+            }
+            continue;
+          }
+          if (exportNode.specifiers?.length) {
+            const hasRequestedSpecifier = exportNode.specifiers.some((specifier) => {
+              const exportedName = getExportedName(specifier);
+              return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
+            });
+            if (hasRequestedSpecifier) {
+              potentialClientRoots.push(node);
+            }
+          }
+        } else if (node.type === "ExportDefaultDeclaration") {
+          if (isExplicitlyRequestedExport("default")) {
+            potentialClientRoots.push(node);
+          }
+        } else if (node.type === "ExportAllDeclaration") {
+          if (explicitlyRequestedExports === "*") {
+            potentialClientRoots.push(node);
+          }
+        }
+      }
+    } else {
+      isFallbackRoots = true;
+      for (const node of resolvedProgram.body) {
+        if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration" || node.type === "ExportAllDeclaration") {
+          potentialClientRoots.push(node);
+        }
       }
     }
   }
@@ -167,6 +241,28 @@ function analyzeReachability(source, filename, program) {
       markImportReachable(node.source.value, "*");
       return;
     }
+    if (node.type === "ExportNamedDeclaration" && typeof node.source?.value === "string") {
+      for (const specifier of node.specifiers ?? []) {
+        const importedName = getReexportedImportName(specifier);
+        if (importedName) {
+          markImportReachable(node.source.value, importedName);
+        }
+      }
+      return;
+    }
+    if (node.type === "ExportNamedDeclaration" && !node.source && explicitlyRequestedExports && node.specifiers?.length) {
+      for (const specifier of node.specifiers) {
+        const exportedName = getExportedName(specifier);
+        if (!exportedName || !isExplicitlyRequestedExport(exportedName)) {
+          continue;
+        }
+        const localName = getLocalExportName(specifier);
+        if (localName && !currentScope.has(localName)) {
+          checkIdentifier(localName);
+        }
+      }
+      return;
+    }
     if (node.type === "Identifier" || node.type === "JSXIdentifier" && /^[A-Z]/.test(node.name)) {
       if (!currentScope.has(node.name)) {
         checkIdentifier(node.name);

package/src/utils/react-dom-runtime-interop-plugin.d.ts

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

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

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+function createReactDomRuntimeInteropPlugin(options) {
+  const reactDomFileFilter = /[\\/]react-dom[\\/].*\.js$/;
+  const reactRequirePattern = /\brequire\((['"])react\1\)/g;
+  const reactSpecifier = options?.reactSpecifier ?? "react";
+  return {
+    name: options?.name ?? "react-dom-runtime-interop",
+    setup(build) {
+      build.onLoad({ filter: reactDomFileFilter }, (args) => {
+        const content = fs.readFileSync(args.path, "utf-8");
+        if (!reactRequirePattern.test(content)) {
+          return void 0;
+        }
+        reactRequirePattern.lastIndex = 0;
+        const rewritten = content.replace(reactRequirePattern, "__ecopages_react_runtime");
+        return {
+          contents: `import * as __ecopages_react_runtime from '${reactSpecifier}';
+${rewritten}`,
+          loader: "js",
+          resolveDir: path.dirname(args.path)
+        };
+      });
+    }
+  };
+}
+export {
+  createReactDomRuntimeInteropPlugin
+};

package/src/utils/react-mdx-loader-plugin.d.ts

@@ -1,3 +1,3 @@
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
 import { type CompileOptions } from '@mdx-js/mdx';
 export declare function createReactMdxLoaderPlugin(compilerOptions?: CompileOptions): EcoBuildPlugin;

package/src/utils/react-mdx-loader-plugin.js

@@ -1,11 +1,18 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { compile } from "@mdx-js/mdx";
-import { SourceMapGenerator } from "source-map";
+import sourceMap from "source-map";
 import { VFile } from "vfile";
+function resolveCompileFormat(filePath, compilerOptions) {
+  const configuredFormat = compilerOptions?.format;
+  if (configuredFormat && configuredFormat !== "detect") {
+    return configuredFormat;
+  }
+  return path.extname(filePath).toLowerCase() === ".md" ? "mdx" : configuredFormat;
+}
 function createReactMdxLoaderPlugin(compilerOptions) {
   const mdxExtensions = compilerOptions?.mdxExtensions ?? [".mdx"];
-  const mdExtensions = compilerOptions?.mdExtensions ?? [".md"];
+  const mdExtensions = compilerOptions?.mdExtensions ?? [];
   const allExtensions = [...mdxExtensions, ...mdExtensions];
   const escapedExts = allExtensions.map((ext) => ext.replace(".", "\\."));
   const filter = new RegExp(`(${escapedExts.join("|")})(\\?.*)?$`);
@@ -18,13 +25,14 @@ function createReactMdxLoaderPlugin(compilerOptions) {
         const file = new VFile({ path: filePath, value: source });
         const compiled = await compile(file, {
           ...compilerOptions,
-          SourceMapGenerator
+          format: resolveCompileFormat(filePath, compilerOptions),
+          SourceMapGenerator: sourceMap.SourceMapGenerator
         });
-        const sourceMap = compiled.map ? `
+        const inlineSourceMap = compiled.map ? `
 //# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(compiled.map)).toString("base64")}
 ` : "";
         return {
-          contents: `${String(compiled.value)}${sourceMap}`,
+          contents: `${String(compiled.value)}${inlineSourceMap}`,
           loader: compilerOptions?.jsx ? "jsx" : "js",
           resolveDir: path.dirname(args.path)
         };

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

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

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

@@ -0,0 +1,33 @@
+const REACT_RUNTIME_SPECIFIERS = [
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom/client"
+];
+function buildReactRuntimeAliasMap(runtimeImports) {
+  return {
+    react: runtimeImports.react,
+    "react/jsx-runtime": runtimeImports.reactJsxRuntime,
+    "react/jsx-dev-runtime": runtimeImports.reactJsxDevRuntime,
+    "react-dom": runtimeImports.reactDom,
+    "react-dom/client": runtimeImports.reactDomClient
+  };
+}
+function getReactRuntimeExternalSpecifiers() {
+  return [...REACT_RUNTIME_SPECIFIERS];
+}
+function getReactClientGraphAllowSpecifiers(runtimeSpecifiers, routerAdapter) {
+  return [
+    "@ecopages/core",
+    ...REACT_RUNTIME_SPECIFIERS,
+    ...routerAdapter ? [routerAdapter.bundle.importPath] : [],
+    ...Array.from(runtimeSpecifiers)
+  ];
+}
+export {
+  REACT_RUNTIME_SPECIFIERS,
+  buildReactRuntimeAliasMap,
+  getReactClientGraphAllowSpecifiers,
+  getReactRuntimeExternalSpecifiers
+};

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

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

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

@@ -0,0 +1,41 @@
+function createUseSyncExternalStoreShimPlugin(options) {
+  const namespace = options?.namespace ?? "ecopages-react-use-sync-external-store-shim";
+  return {
+    name: options?.name ?? "react-use-sync-external-store-shim",
+    setup(build) {
+      build.onResolve({ filter: /^use-sync-external-store\/shim(?:\/index\.js)?$/ }, () => ({
+        path: "use-sync-external-store/shim",
+        namespace
+      }));
+      build.onLoad({ filter: /^use-sync-external-store\/shim$/, namespace }, () => ({
+        contents: "export { useSyncExternalStore } from 'react';",
+        loader: "js"
+      }));
+      build.onLoad({ filter: /[\\/]use-sync-external-store[\\/]shim[\\/]index\.js$/ }, () => ({
+        contents: "export { useSyncExternalStore } from 'react';",
+        loader: "js"
+      }));
+      build.onLoad(
+        {
+          filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.development\.js$/
+        },
+        () => ({
+          contents: "export { useSyncExternalStore } from 'react';",
+          loader: "js"
+        })
+      );
+      build.onLoad(
+        {
+          filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.production\.js$/
+        },
+        () => ({
+          contents: "export { useSyncExternalStore } from 'react';",
+          loader: "js"
+        })
+      );
+    }
+  };
+}
+export {
+  createUseSyncExternalStoreShimPlugin
+};

package/CHANGELOG.md

@@ -1,62 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/react` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Features
-
-#### Render Reachability Analysis
-
-- **Client render graph (Phase 1)** — Introduces a static reachability analysis step that builds an explicit graph of which components are rendered client-side (`cdfbd69e`).
-- **OXC-powered reachability analyzer** — `reachability-analyzer.ts` uses OXC to parse and walk component ASTs, building a `ClientRenderGraph` that maps exported components to their client-side reach (`5412df6b`).
-- **Explicit client graph boundaries** — Components must now declare explicit boundaries; the analyser enforces these to prevent over-hydration (`2912d6bd`).
-- **Declared modules utility** — `declared-modules.ts` tracks which modules are declared as client boundaries.
-
-#### Service Architecture Refactor
-
-- **`ReactRuntimeBundleService`** — Manages runtime assets and specifier mapping for the React integration (`cfd3cb05`).
-- **`ReactHydrationAssetService`** — Creates and manages hydration assets for client-side rendering (`cfd3cb05`).
-- **`ReactBundleService`** — Handles esbuild bundle configuration for React components (`cfd3cb05`).
-- **`ReactPageModuleService`** — Loads and compiles MDX/TSX page modules, including config resolution (`cfd3cb05`).
-- The integration no longer builds a monolithic renderer — each concern is handled by a focused service.
-
-#### HMR Improvements
-
-- **HMR page metadata caching** — Page metadata is now cached between HMR refreshes, preventing unnecessary re-fetches during Fast Refresh (`a663788c`).
-- **Stale temp module race fix** — HMR no longer incorrectly reads a stale temporary module during rapid refresh cycles (`b2cf8466`).
-- **Client graph HMR stability** — HMR reloads now correctly respect client graph boundaries to avoid partial hydration mismatches (`2912d6bd`).
-
-#### HTML Boundary Utilities
-
-- **`html-boundary.ts`** — New utility that wraps rendered output in explicit boundary markers for the cross-integration boundary rendering policy (`ec1e4d66`).
-- **`hydration-scripts.ts`** — Expanded with new helpers for generating and injecting hydration entry scripts.
-
-### Refactoring
-
-- Aligned React renderer to full orchestration mode — removed legacy rendering path (`fc07bdb0`).
-- Ambient module declarations cleaned up (`5f46ecc5`).
-- Client graph boundaries and runtime dependency wiring corrected (`4b6cd32e`).
-- Updated test suite for esbuild adapter and Node.js runtime compatibility (`31a44458`).
-
-### Bug Fixes
-
-- Inlined the React MDX loader so React apps no longer need to install `@ecopages/mdx` when enabling React MDX support (`unreleased`).
-- Fixed stale temp module race during Fast Refresh cycles (`b2cf8466`).
-- Fixed client graph boundary wiring for runtime dependencies (`4b6cd32e`).
-
-### Tests
-
-- Added `html-boundary.test.ts` covering boundary wrapping utilities.
-- Added `hydration-scripts.test.ts` with hydration script generation coverage.
-- Added `reachability-analyzer.test.ts` (187 lines) covering export declaration reachability.
-- Updated integration tests for esbuild adapter compatibility (`31a44458`).
-
----
-
-## Migration Notes
-
-- The React integration now requires explicit client boundary declarations. Components that should be hydrated client-side must be marked at a boundary entry point.
-- The internal service layer (`ReactRuntimeBundleService`, `ReactBundleService`, etc.) is not part of the public API and may change between releases.