@ecopages/react 0.2.0-alpha.2 → 0.2.0-alpha.20

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

@@ -1,8 +1,16 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, extname, resolve } from "node:path";
 import { parseSync } from "oxc-parser";
-import { analyzeReachability } from "./reachability-analyzer";
+import { analyzeReachability } from "./reachability-analyzer.js";
 const SOURCE_FILE_FILTER = /\.(tsx?|jsx?)$/;
+const SERVER_ONLY_ECO_PAGE_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "cache",
+  "middleware",
+  "requires",
+  "metadata",
+  "staticProps",
+  "staticPaths"
+]);
 function isBareSpecifier(specifier) {
   if (specifier.startsWith(".")) return false;
   if (specifier.startsWith("/")) return false;
@@ -12,6 +20,10 @@ function isBareSpecifier(specifier) {
 function isProjectAliasSpecifier(specifier) {
   return specifier.startsWith("@/") || specifier.startsWith("~/") || specifier.startsWith("ecopages:");
 }
+function isServerOnlySpecifier(specifier) {
+  if (specifier.startsWith("node:")) return true;
+  return /(?:^|[/])[^/]+\.server(?:$|\.)/.test(specifier);
+}
 function toModuleBaseSpecifier(specifier) {
   if (!isBareSpecifier(specifier) || specifier.startsWith("node:")) {
     return specifier;
@@ -82,7 +94,93 @@ function parserLanguageForFile(filename) {
   if (extension === ".jsx") return "jsx";
   return "js";
 }
-function transformModuleImports(source, filename, globallyAllowed) {
+function getObjectPropertyKeyName(node) {
+  if (!node) return void 0;
+  if (node.type === "Identifier") return node.name;
+  if (node.type === "StringLiteral" || node.type === "Literal") {
+    return typeof node.value === "string" ? node.value : void 0;
+  }
+  return void 0;
+}
+function stripServerOnlyEcoPageOptions(source, program) {
+  const edits = [];
+  function walk(node) {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const child of node) walk(child);
+      return;
+    }
+    if (node.type === "CallExpression" && node.callee?.type === "MemberExpression" && node.callee.object?.type === "Identifier" && node.callee.object.name === "eco" && node.callee.property?.type === "Identifier" && node.callee.property.name === "page" && node.arguments?.[0]?.type === "ObjectExpression") {
+      const objectExpression = node.arguments[0];
+      const keptProperties = [];
+      let removedProperty = false;
+      for (const property of objectExpression.properties ?? []) {
+        if (property?.type === "Property") {
+          const keyName = getObjectPropertyKeyName(property.key);
+          if (keyName && SERVER_ONLY_ECO_PAGE_OPTION_KEYS.has(keyName)) {
+            removedProperty = true;
+            continue;
+          }
+        }
+        keptProperties.push(source.slice(property.start, property.end));
+      }
+      if (removedProperty) {
+        const replacement = keptProperties.length > 0 ? `{ ${keptProperties.join(", ")} }` : "{}";
+        edits.push({
+          start: objectExpression.start,
+          end: objectExpression.end,
+          replacement
+        });
+      }
+    }
+    for (const key in node) {
+      if (key !== "type" && key !== "start" && key !== "end") {
+        walk(node[key]);
+      }
+    }
+  }
+  walk(program);
+  if (edits.length === 0) {
+    return { transformed: source, modified: false };
+  }
+  edits.sort((a, b) => b.start - a.start);
+  let transformed = source;
+  for (const edit of edits) {
+    transformed = transformed.slice(0, edit.start) + edit.replacement + transformed.slice(edit.end);
+  }
+  return { transformed, modified: true };
+}
+function normalizeRequestedExportsKey(pathname) {
+  let normalized = pathname.replace(/\\/g, "/");
+  normalized = normalized.replace(/\.(tsx?|jsx?)$/i, "");
+  if (normalized.endsWith("/index")) {
+    normalized = normalized.slice(0, -"/index".length);
+  }
+  return normalized;
+}
+function resolveRequestedExportsKey(importer, specifier) {
+  if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
+    return void 0;
+  }
+  const resolved = specifier.startsWith("/") ? specifier : resolve(dirname(importer), specifier);
+  return normalizeRequestedExportsKey(resolved);
+}
+function mergeRequestedExportRules(registry, moduleKey, rules) {
+  const existing = registry.get(moduleKey);
+  if (existing === "*") return;
+  if (rules === "*") {
+    registry.set(moduleKey, "*");
+    return;
+  }
+  if (!existing) {
+    registry.set(moduleKey, new Set(rules));
+    return;
+  }
+  for (const rule of rules) {
+    existing.add(rule);
+  }
+}
+function transformModuleImports(source, filename, globallyAllowed, requestedExports) {
   let result;
   try {
     result = parseSync(filename, source, {
@@ -116,12 +214,35 @@ function transformModuleImports(source, filename, globallyAllowed) {
   walk(program);
   const locallyAllowed = parseDeclaredModules(localDeclared);
   const allowedMap = mergeDeclaredModulesMap(globallyAllowed, locallyAllowed);
-  const reachability = analyzeReachability(source, filename, program);
+  const explicitRequestedExports = requestedExports.get(normalizeRequestedExportsKey(filename));
+  const reachability = analyzeReachability(source, filename, program, explicitRequestedExports);
+  for (const statement of program.body) {
+    if (statement.type === "ImportDeclaration") {
+      const reachableRules = reachability.reachableImports.get(statement.source.value);
+      const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value);
+      if (!requestedModuleKey || !reachableRules) continue;
+      mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+      continue;
+    }
+    if (statement.type === "ExportNamedDeclaration" && statement.source) {
+      const reachableRules = reachability.reachableImports.get(statement.source.value);
+      const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value);
+      if (!requestedModuleKey || !reachableRules) continue;
+      mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+      continue;
+    }
+    if (statement.type === "ExportAllDeclaration" && statement.source) {
+      const reachableRules = reachability.reachableImports.get(statement.source.value);
+      const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value);
+      if (!requestedModuleKey || !reachableRules) continue;
+      mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+    }
+  }
   const edits = [];
   function processSpecifier(specifier) {
     const moduleBase = toModuleBaseSpecifier(specifier);
     const explicitRules = allowedMap.get(moduleBase);
-    if (specifier.startsWith("node:") || specifier.includes(".server.")) {
+    if (isServerOnlySpecifier(specifier)) {
       if (explicitRules) {
         return { allowed: true, rules: explicitRules };
       }
@@ -208,9 +329,10 @@ function transformModuleImports(source, filename, globallyAllowed) {
       const specifier = node.source.value;
       const { allowed } = processSpecifier(specifier);
       if (!allowed) {
-        if (!reachability.isFallbackRoots) {
+        const reachableRules = reachability.reachableImports.get(specifier);
+        if (reachableRules && !reachability.isFallbackRoots) {
           throw new Error(
-            `[Ecopages Client Reachability] Forbidden client export from '${specifier}' at ${filename}:${node.start}.`
+            `[Ecopages Client Reachability] Forbidden client export from '${specifier}' at ${filename}:${node.start}. This export is explicitly reachable from the React render function.`
           );
         } else {
           edits.push({ start: node.start, end: node.end, replacement: "" });
@@ -222,9 +344,10 @@ function transformModuleImports(source, filename, globallyAllowed) {
       const specifier = node.source.value;
       const { allowed } = processSpecifier(specifier);
       if (!allowed) {
-        if (!reachability.isFallbackRoots) {
+        const reachableRules = reachability.reachableImports.get(specifier);
+        if (reachableRules && !reachability.isFallbackRoots) {
           throw new Error(
-            `[Ecopages Client Reachability] Forbidden client export * from '${specifier}' at ${filename}:${node.start}.`
+            `[Ecopages Client Reachability] Forbidden client export * from '${specifier}' at ${filename}:${node.start}. This export is explicitly reachable from the React render function.`
           );
         } else {
           edits.push({ start: node.start, end: node.end, replacement: "" });
@@ -282,13 +405,26 @@ function transformModuleImports(source, filename, globallyAllowed) {
   }
   walkImports(program);
   if (edits.length === 0) {
-    return { transformed: source, modified: false };
+    return stripServerOnlyEcoPageOptions(source, program);
   }
   edits.sort((a, b) => b.start - a.start);
   let transformed = source;
   for (const edit of edits) {
     transformed = transformed.slice(0, edit.start) + edit.replacement + transformed.slice(edit.end);
   }
+  let reparsedResult;
+  try {
+    reparsedResult = parseSync(filename, transformed, {
+      sourceType: "module",
+      lang: parserLanguageForFile(filename)
+    });
+  } catch {
+    return { transformed, modified: true };
+  }
+  const strippedPageOptions = stripServerOnlyEcoPageOptions(transformed, reparsedResult.program);
+  if (strippedPageOptions.modified) {
+    return strippedPageOptions;
+  }
   return { transformed, modified: true };
 }
 function createClientGraphBoundaryPlugin(options) {
@@ -297,6 +433,7 @@ function createClientGraphBoundaryPlugin(options) {
     setup(build) {
       const absWorkingDir = options?.absWorkingDir ?? process.cwd();
       const globallyDeclaredSources = parseDeclaredModules(options?.declaredModules);
+      const requestedExports = /* @__PURE__ */ new Map();
       for (const alwaysAllow of options?.alwaysAllowSpecifiers ?? []) {
         globallyDeclaredSources.set(toModuleBaseSpecifier(alwaysAllow), "*");
       }
@@ -338,7 +475,8 @@ function createClientGraphBoundaryPlugin(options) {
         const { transformed: oxcTransformed, modified: importsModified } = transformModuleImports(
           transformed,
           args.path,
-          globallyDeclaredSources
+          globallyDeclaredSources,
+          requestedExports
         );
         if (importsModified) {
           modified = true;
@@ -346,7 +484,7 @@ function createClientGraphBoundaryPlugin(options) {
         }
         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

@@ -30,10 +30,8 @@ export type IslandHydrationScriptOptions = {
     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. */
@@ -43,7 +41,18 @@ export type IslandHydrationScriptOptions = {
 };
 /**
  * Creates a hydration script for client-side React hydration.
- * Generates appropriate script based on environment and router configuration.
+ *
+ * Why this dispatcher exists:
+ * the runtime matrix is small but behaviorally different across development vs
+ * production and router vs non-router pages. Keeping that branch here preserves
+ * a compact public API while allowing each emitted script to stay focused.
+ *
+ * Selection rules:
+ * - development uses readable scripts with HMR hooks
+ * - production uses minified equivalents
+ * - router presence decides whether page updates flow through the router runtime
+ *   or rebuild directly from the page module
+ *
  * @param options - Configuration options for script generation
  * @returns The generated hydration script as a string
  */
@@ -63,8 +72,14 @@ export declare function createHydrationScript(options: HydrationScriptOptions):
  * - resolves the component export by metadata (`componentRef`, `componentFile`)
  *   before falling back to default/first function export
  * - selects island root using `targetSelector`
+ * - replaces the SSR host with a dedicated client-owned container
  * - creates a fresh React root and renders with serialized `props`
  *
+ * Why it remounts instead of hydrating:
+ * island SSR intentionally avoids synthetic wrapper elements. The runtime swaps
+ * the authored SSR node for a dedicated client-owned container before mounting
+ * so the server markup stays clean while the client still gets a stable root.
+ *
  * @param options Island script generation options.
  * @returns Browser-executable JavaScript module source.
  */