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

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

@@ -3,6 +3,14 @@ import { dirname, extname, resolve } from "node:path";
 import { parseSync } from "oxc-parser";
 import { analyzeReachability } from "./reachability-analyzer";
 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;

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

@@ -22,6 +22,14 @@ import { parseSync } from 'oxc-parser';
 import { analyzeReachability } from './reachability-analyzer';
 
 const SOURCE_FILE_FILTER = /\.(tsx?|jsx?)$/;
+const SERVER_ONLY_ECO_PAGE_OPTION_KEYS = new Set([
+	'cache',
+	'middleware',
+	'requires',
+	'metadata',
+	'staticProps',
+	'staticPaths',
+]);
 
 /**
  * Configuration options for the Client Graph Boundary esbuild plugin.
@@ -64,6 +72,20 @@ function isProjectAliasSpecifier(specifier: string): boolean {
 	return specifier.startsWith('@/') || specifier.startsWith('~/') || specifier.startsWith('ecopages:');
 }
 
+/**
+ * Determines whether a specifier should be treated as server-only.
+ *
+ * This covers Node built-ins as well as local module conventions such as
+ * `.server.ts` and extensionless imports that resolve to `.server.*` files.
+ *
+ * @param specifier - Raw import specifier from the module source.
+ * @returns True when the import must never become client-reachable.
+ */
+function isServerOnlySpecifier(specifier: string): boolean {
+	if (specifier.startsWith('node:')) return true;
+	return /(?:^|[/])[^/]+\.server(?:$|\.)/.test(specifier);
+}
+
 /**
  * Strips down a deep path module specifier to its foundational root package name.
  *
@@ -191,6 +213,179 @@ function parserLanguageForFile(filename: string): 'js' | 'jsx' | 'ts' | 'tsx' {
 	return 'js';
 }
 
+/**
+ * Extracts a static property key name from an object literal property node.
+ *
+ * The client graph boundary rewrite only strips known `eco.page(...)` keys when
+ * it can prove the property name statically. Computed or otherwise dynamic keys
+ * are ignored so the transform remains conservative.
+ *
+ * @param node - OXC AST node representing an object property key.
+ * @returns Static property key name when it can be resolved, otherwise `undefined`.
+ */
+function getObjectPropertyKeyName(node: any): string | undefined {
+	if (!node) return undefined;
+	if (node.type === 'Identifier') return node.name;
+	if (node.type === 'StringLiteral' || node.type === 'Literal') {
+		return typeof node.value === 'string' ? node.value : undefined;
+	}
+	return undefined;
+}
+
+/**
+ * Removes server-only `eco.page(...)` options from browser-bound modules.
+ *
+ * Import pruning alone is not sufficient because a page module can still retain
+ * references to stripped server imports through config fields like `middleware`
+ * or `metadata`. This pass rewrites the `eco.page(...)` object literal so only
+ * browser-relevant properties remain.
+ *
+ * @param source - Original or already-transformed module source.
+ * @param program - Parsed OXC program for the same source text.
+ * @returns Updated source plus a flag indicating whether any rewrite occurred.
+ */
+function stripServerOnlyEcoPageOptions(source: string, program: any): { transformed: string; modified: boolean } {
+	const edits: { start: number; end: number; replacement: string }[] = [];
+
+	function walk(node: any) {
+		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: string[] = [];
+			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 };
+}
+
+/**
+ * Tracks the subset of exports that a downstream local module is allowed to expose.
+ *
+ * `'*'` means the full module namespace is reachable, while a `Set` limits the
+ * consumer to specific named exports.
+ */
+type RequestedExportRules = Set<string> | '*';
+
+/**
+ * Normalizes a file path into a registry key used for requested-export propagation.
+ *
+ * The normalization strips JS/TS extensions and collapses `/index` suffixes so
+ * equivalent local import forms resolve to the same key.
+ *
+ * @param pathname - Absolute or resolved local module path.
+ * @returns Stable registry key for `requestedExports`.
+ */
+function normalizeRequestedExportsKey(pathname: string): string {
+	let normalized = pathname.replace(/\\/g, '/');
+	normalized = normalized.replace(/\.(tsx?|jsx?)$/i, '');
+	if (normalized.endsWith('/index')) {
+		normalized = normalized.slice(0, -'/index'.length);
+	}
+	return normalized;
+}
+
+/**
+ * Resolves a local import specifier into a requested-export registry key.
+ *
+ * Bare package specifiers and project aliases are intentionally ignored because
+ * requested-export propagation is only used for cross-file local reachability.
+ *
+ * @param importer - Absolute path of the importing module.
+ * @param specifier - Raw import or re-export specifier.
+ * @returns Registry key for a local dependency, or `undefined` when not applicable.
+ */
+function resolveRequestedExportsKey(importer: string, specifier: string): string | undefined {
+	if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
+		return undefined;
+	}
+
+	const resolved = specifier.startsWith('/') ? specifier : resolve(dirname(importer), specifier);
+	return normalizeRequestedExportsKey(resolved);
+}
+
+/**
+ * Merges newly discovered requested-export rules into the local propagation registry.
+ *
+ * Once a module is promoted to `'*'`, it stays fully reachable for the remainder
+ * of the transform pass.
+ *
+ * @param registry - Cross-module requested-export registry.
+ * @param moduleKey - Normalized local module key.
+ * @param rules - Newly observed reachable export rules for the module.
+ */
+function mergeRequestedExportRules(
+	registry: Map<string, RequestedExportRules>,
+	moduleKey: string,
+	rules: Set<string> | '*',
+) {
+	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);
+	}
+}
+
 /**
  * Parses a module using Oxc AST and surgically removes forbidden imports.
  * Filters down to the exact specifiers requested via `{namedImport}` syntax.
@@ -198,12 +393,14 @@ function parserLanguageForFile(filename: string): 'js' | 'jsx' | 'ts' | 'tsx' {
  * @param source - The raw string source content of the module.
  * @param filename - The absolute path of the module.
  * @param globallyAllowed - A map of modules declared globally allowable by the build configuration.
+ * @param requestedExports - Local requested-export registry used to propagate named reachability across files.
  * @returns An object containing the transformed string and a boolean indicating if changes occurred.
  */
 function transformModuleImports(
 	source: string,
 	filename: string,
 	globallyAllowed: Map<string, Set<string> | '*'>,
+	requestedExports: Map<string, RequestedExportRules>,
 ): { transformed: string; modified: boolean } {
 	/**
 	 * Parse the source
@@ -273,7 +470,36 @@ function transformModuleImports(
 	 */
 	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 as string);
+			const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value as string);
+			if (!requestedModuleKey || !reachableRules) continue;
+
+			mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+			continue;
+		}
+
+		if (statement.type === 'ExportNamedDeclaration' && statement.source) {
+			const reachableRules = reachability.reachableImports.get(statement.source.value as string);
+			const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value as string);
+			if (!requestedModuleKey || !reachableRules) continue;
+
+			mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+			continue;
+		}
+
+		if (statement.type === 'ExportAllDeclaration' && statement.source) {
+			const reachableRules = reachability.reachableImports.get(statement.source.value as string);
+			const requestedModuleKey = resolveRequestedExportsKey(filename, statement.source.value as string);
+			if (!requestedModuleKey || !reachableRules) continue;
+
+			mergeRequestedExportRules(requestedExports, requestedModuleKey, reachableRules);
+		}
+	}
 
 	/**
 	 * Build the edit list
@@ -294,7 +520,7 @@ function transformModuleImports(
 		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 };
 			}
@@ -405,14 +631,11 @@ function transformModuleImports(
 			const specifier = node.source.value as string;
 			const { allowed } = processSpecifier(specifier);
 
-			/**
-			 * We skip checking reachability of re-exports for now to avoid false negatives.
-			 * But we MUST check security.
-			 */
 			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: '' });
@@ -425,9 +648,10 @@ function transformModuleImports(
 			const specifier = node.source.value as string;
 			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: '' });
@@ -492,7 +716,7 @@ function transformModuleImports(
 	walkImports(program);
 
 	if (edits.length === 0) {
-		return { transformed: source, modified: false };
+		return stripServerOnlyEcoPageOptions(source, program);
 	}
 
 	edits.sort((a, b) => b.start - a.start);
@@ -501,6 +725,21 @@ function transformModuleImports(
 		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 };
 }
 
@@ -516,6 +755,7 @@ export function createClientGraphBoundaryPlugin(options?: ClientGraphBoundaryOpt
 		setup(build) {
 			const absWorkingDir = options?.absWorkingDir ?? process.cwd();
 			const globallyDeclaredSources = parseDeclaredModules(options?.declaredModules);
+			const requestedExports = new Map<string, RequestedExportRules>();
 			for (const alwaysAllow of options?.alwaysAllowSpecifiers ?? []) {
 				globallyDeclaredSources.set(toModuleBaseSpecifier(alwaysAllow), '*');
 			}
@@ -573,6 +813,7 @@ export function createClientGraphBoundaryPlugin(options?: ClientGraphBoundaryOpt
 					transformed,
 					args.path,
 					globallyDeclaredSources,
+					requestedExports,
 				);
 
 				if (importsModified) {

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

@@ -43,7 +43,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 +74,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.
  */