@ecopages/react 0.2.0-alpha.5 → 0.2.0-alpha.8

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

@@ -2,23 +2,22 @@
  * Runtime bundle service for React integration.
  *
  * Owns creation of the browser runtime assets for React and React DOM,
- * including temporary entry generation, specifier mapping, and React DOM
- * interop rewriting.
+ * including shared runtime entry generation and specifier mapping.
  *
  * @module
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
-import { createRequire } from 'node:module';
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import { type AssetDefinition, AssetFactory } from '@ecopages/core/services/asset-processing-service';
+import { createRuntimeSpecifierAliasPlugin } from '@ecopages/core/build/runtime-specifier-alias-plugin';
+import {
+	buildBrowserRuntimeAssetUrl,
+	createBrowserRuntimeModuleAsset,
+	createBrowserRuntimeScriptAsset,
+	type AssetDefinition,
+} from '@ecopages/core/services/asset-processing-service';
 import type { ReactRouterAdapter } from '../router-adapter.ts';
-
-type RuntimeModuleConfig = {
-	specifier: string;
-	defaultExport?: boolean;
-};
+import { createReactDomRuntimeInteropPlugin } from '../utils/react-dom-runtime-interop-plugin.ts';
+import { buildReactRuntimeSpecifierMap } from '../utils/react-runtime-specifier-map.ts';
 
 export type ReactRuntimeImports = {
 	react: string;
@@ -33,239 +32,141 @@ export interface ReactRuntimeBundleServiceConfig {
 	routerAdapter?: ReactRouterAdapter;
 }
 
-export class ReactRuntimeBundleService {
-	constructor(private readonly config: ReactRuntimeBundleServiceConfig) {}
-
-	getRuntimeImports(): ReactRuntimeImports {
-		const runtimeImports: ReactRuntimeImports = {
-			react: this.buildImportMapSourceUrl('react.js'),
-			reactDomClient: this.buildImportMapSourceUrl('react-dom.js'),
-			reactJsxRuntime: this.buildImportMapSourceUrl('react.js'),
-			reactJsxDevRuntime: this.buildImportMapSourceUrl('react.js'),
-			reactDom: this.buildImportMapSourceUrl('react-dom.js'),
-		};
+type RuntimeMode = 'development' | 'production';
 
-		if (this.config.routerAdapter) {
-			runtimeImports.router = this.buildImportMapSourceUrl(`${this.config.routerAdapter.bundle.outputName}.js`);
-		}
+export class ReactRuntimeBundleService {
+	private readonly config: ReactRuntimeBundleServiceConfig;
 
-		return runtimeImports;
+	constructor(config: ReactRuntimeBundleServiceConfig) {
+		this.config = config;
 	}
 
-	getSpecifierMap(): Record<string, string> {
-		const runtimeImports = this.getRuntimeImports();
-		const map: Record<string, string> = {
-			react: runtimeImports.react,
-			'react/jsx-runtime': runtimeImports.reactJsxRuntime,
-			'react/jsx-dev-runtime': runtimeImports.reactJsxDevRuntime,
-			'react-dom': runtimeImports.reactDom,
-			'react-dom/client': runtimeImports.reactDomClient,
-		};
-
-		if (this.config.routerAdapter && runtimeImports.router) {
-			map[this.config.routerAdapter.importMapKey] = runtimeImports.router;
-		}
-
-		return map;
+	private get isDevelopment(): boolean {
+		return process.env.NODE_ENV === 'development';
 	}
 
-	getDependencies(): AssetDefinition[] {
-		const runtimeAttrs = { type: 'module', defer: '' } as const;
-		const runtimeImports = this.getRuntimeImports();
-		const reactRuntimeAliasPlugin = this.createRuntimeSpecifierAliasPlugin({
-			react: runtimeImports.react,
-		});
-		const reactDomRuntimeInteropPlugin = this.createReactDomRuntimeInteropPlugin();
-
-		const reactEntry = this.createRuntimeEntry(
-			[
-				{ specifier: 'react', defaultExport: true },
-				{ specifier: 'react/jsx-runtime' },
-				{ specifier: 'react/jsx-dev-runtime' },
-			],
-			'react-entry.mjs',
-		);
-		const reactDomEntry = this.createRuntimeEntry(
-			[{ specifier: 'react-dom', defaultExport: true }, { specifier: 'react-dom/client' }],
-			'react-dom-entry.mjs',
-		);
-
-		const dependencies: AssetDefinition[] = [
-			AssetFactory.createNodeModuleScript({
-				position: 'head',
-				importPath: reactEntry,
-				name: 'react',
-				excludeFromHtml: true,
-				bundleOptions: { naming: 'react.js' },
-				attributes: runtimeAttrs,
-			}),
-			AssetFactory.createNodeModuleScript({
-				position: 'head',
-				importPath: reactDomEntry,
-				name: 'react-dom',
-				excludeFromHtml: true,
-				bundleOptions: {
-					naming: 'react-dom.js',
-					plugins: [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin],
-				},
-				attributes: runtimeAttrs,
-			}),
-		];
-
-		if (this.config.routerAdapter) {
-			const runtimeAliasPlugin = this.createRuntimeAliasPlugin();
-			const mappedSpecifiers = new Set(Object.keys(this.getSpecifierMap()));
-			const unresolvedExternals = this.config.routerAdapter.bundle.externals.filter(
-				(external) => !mappedSpecifiers.has(external),
-			);
-
-			dependencies.push(
-				AssetFactory.createNodeModuleScript({
-					position: 'head',
-					importPath: this.config.routerAdapter.bundle.importPath,
-					name: this.config.routerAdapter.bundle.outputName,
-					excludeFromHtml: true,
-					bundleOptions: {
-						naming: `${this.config.routerAdapter.bundle.outputName}.js`,
-						external: unresolvedExternals,
-						plugins: [runtimeAliasPlugin],
-					},
-					attributes: runtimeAttrs,
-				}),
-			);
-		}
-
-		return dependencies;
+	private getCurrentRuntimeMode(): RuntimeMode {
+		return this.isDevelopment ? 'development' : 'production';
 	}
 
-	createRuntimeAliasPlugin(): EcoBuildPlugin {
-		const specifierMap = this.getSpecifierMap();
-		const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-		const filter = new RegExp(
-			`^(${Object.keys(specifierMap)
-				.map((key) => escapeRegExp(key))
-				.join('|')})$`,
-		);
+	private createRuntimeDefines(mode: RuntimeMode): Record<string, string> {
+		const nodeEnv = JSON.stringify(mode);
 
 		return {
-			name: 'react-plugin-runtime-alias',
-			setup(build) {
-				build.onResolve({ filter }, (args) => {
-					const mappedPath = specifierMap[args.path];
-					if (!mappedPath) {
-						return undefined;
-					}
-
-					return {
-						path: mappedPath,
-						external: true,
-					};
-				});
-			},
+			'process.env.NODE_ENV': nodeEnv,
+			'import.meta.env.NODE_ENV': nodeEnv,
 		};
 	}
 
-	private buildImportMapSourceUrl(fileName: string): string {
-		return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
+	private getReactVendorFileName(mode: RuntimeMode): string {
+		return mode === 'development' ? 'react.development.js' : 'react.js';
 	}
 
-	private createRuntimeSpecifierAliasPlugin(specifierMap: Record<string, string>, external = true): EcoBuildPlugin {
-		const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-		const filter = new RegExp(
-			`^(${Object.keys(specifierMap)
-				.map((key) => escapeRegExp(key))
-				.join('|')})$`,
-		);
+	private getReactDomVendorFileName(mode: RuntimeMode): string {
+		return mode === 'development' ? 'react-dom.development.js' : 'react-dom.js';
+	}
 
-		return {
-			name: 'react-plugin-runtime-specifier-alias',
-			setup(build) {
-				build.onResolve({ filter }, (args) => {
-					const mappedPath = specifierMap[args.path];
-					if (!mappedPath) {
-						return undefined;
-					}
+	private getRouterVendorFileName(mode: RuntimeMode): string {
+		if (!this.config.routerAdapter) {
+			return '';
+		}
 
-					return {
-						path: mappedPath,
-						external,
-					};
-				});
-			},
-		};
+		return mode === 'development'
+			? `${this.config.routerAdapter.bundle.outputName}.development.js`
+			: `${this.config.routerAdapter.bundle.outputName}.js`;
 	}
 
-	private createReactDomRuntimeInteropPlugin(): EcoBuildPlugin {
-		const reactDomFileFilter = /[\\/]react-dom[\\/].*\.js$/;
-		const reactRequirePattern = /\brequire\((['"])react\1\)/g;
-
-		return {
-			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 undefined;
-					}
+	getRuntimeImports(mode = this.getCurrentRuntimeMode()): ReactRuntimeImports {
+		const reactVendorFileName = this.getReactVendorFileName(mode);
+		const reactDomVendorFileName = this.getReactDomVendorFileName(mode);
+		const runtimeImports: ReactRuntimeImports = {
+			react: buildBrowserRuntimeAssetUrl(reactVendorFileName),
+			reactDomClient: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
+			reactJsxRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
+			reactJsxDevRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
+			reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
+		};
 
-					reactRequirePattern.lastIndex = 0;
-					const rewritten = content.replace(reactRequirePattern, '__ecopages_react_runtime');
+		if (this.config.routerAdapter) {
+			runtimeImports.router = buildBrowserRuntimeAssetUrl(this.getRouterVendorFileName(mode));
+		}
 
-					return {
-						contents: `import * as __ecopages_react_runtime from 'react';\n${rewritten}`,
-						loader: 'js',
-						resolveDir: path.dirname(args.path),
-					};
-				});
-			},
-		};
+		return runtimeImports;
 	}
 
-	private getRuntimeArtifactsDir(): string {
-		const tmpDir = path.join(process.cwd(), 'node_modules', '.cache', 'ecopages-react-runtime');
-		fs.mkdirSync(tmpDir, { recursive: true });
-		return tmpDir;
+	getSpecifierMap(mode = this.getCurrentRuntimeMode()): Record<string, string> {
+		return buildReactRuntimeSpecifierMap(this.getRuntimeImports(mode), this.config.routerAdapter);
 	}
 
-	private createRuntimeEntry(modules: RuntimeModuleConfig[], fileName: string): string {
-		const tmpDir = this.getRuntimeArtifactsDir();
-		const requireFromRoot = createRequire(path.join(process.cwd(), 'package.json'));
-		const seenExports = new Set<string>();
-		const statements: string[] = [];
+	getDependencies(): AssetDefinition[] {
+		const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin();
+		const dependencies: AssetDefinition[] = [];
 
-		for (const module of modules) {
-			if (module.defaultExport) {
-				statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
-				statements.push('export default __ecopages_default_export__;');
-			}
+		for (const mode of ['production', 'development'] as const) {
+			const reactRuntimeAliasPlugin = createRuntimeSpecifierAliasPlugin(
+				{
+					react: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode)),
+				},
+				{ name: `react-plugin-runtime-specifier-alias-${mode}` },
+			);
+			const reactDomBundlePlugins = [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin].filter(
+				(plugin): plugin is EcoBuildPlugin => plugin !== null,
+			);
+			const runtimeAliasPlugin = this.createRuntimeAliasPlugin(mode);
+			const mappedSpecifiers = new Set(Object.keys(this.getSpecifierMap(mode)));
 
-			const exportNames = this.getModuleExportNames(module.specifier, requireFromRoot).filter(
-				(name) => !seenExports.has(name),
+			dependencies.push(
+				createBrowserRuntimeModuleAsset({
+					modules: [
+						{ specifier: 'react', defaultExport: true },
+						{ specifier: 'react/jsx-runtime' },
+						{ specifier: 'react/jsx-dev-runtime' },
+					],
+					name: 'react',
+					fileName: this.getReactVendorFileName(mode),
+					cacheDirName: `ecopages-react-runtime-${mode}`,
+					bundleOptions: {
+						define: this.createRuntimeDefines(mode),
+					},
+				}),
+				createBrowserRuntimeModuleAsset({
+					modules: [{ specifier: 'react-dom', defaultExport: true }, { specifier: 'react-dom/client' }],
+					name: 'react-dom',
+					fileName: this.getReactDomVendorFileName(mode),
+					cacheDirName: `ecopages-react-runtime-${mode}`,
+					bundleOptions: {
+						define: this.createRuntimeDefines(mode),
+						plugins: reactDomBundlePlugins,
+					},
+				}),
 			);
 
-			if (exportNames.length > 0) {
-				statements.push(`export { ${exportNames.join(', ')} } from '${module.specifier}';`);
-				for (const exportName of exportNames) {
-					seenExports.add(exportName);
-				}
+			if (this.config.routerAdapter) {
+				const unresolvedExternals = this.config.routerAdapter.bundle.externals.filter(
+					(external) => !mappedSpecifiers.has(external),
+				);
+
+				dependencies.push(
+					createBrowserRuntimeScriptAsset({
+						importPath: this.config.routerAdapter.bundle.importPath,
+						name: this.config.routerAdapter.bundle.outputName,
+						fileName: this.getRouterVendorFileName(mode),
+						bundleOptions: {
+							define: this.createRuntimeDefines(mode),
+							external: unresolvedExternals,
+							plugins: [runtimeAliasPlugin],
+						},
+					}),
+				);
 			}
 		}
 
-		const filePath = path.join(tmpDir, fileName);
-		fs.writeFileSync(filePath, statements.join('\n'), 'utf-8');
-		return filePath;
-	}
-
-	private getModuleExportNames(specifier: string, requireFromRoot: ReturnType<typeof createRequire>): string[] {
-		const moduleExports = requireFromRoot(specifier);
-
-		return Object.keys(moduleExports)
-			.filter((name) => name !== '__esModule' && name !== 'default')
-			.filter((name) => this.isValidExportName(name))
-			.sort();
+		return dependencies;
 	}
 
-	private isValidExportName(name: string): boolean {
-		return /^[$A-Z_a-z][$\w]*$/.test(name);
+	createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode()): EcoBuildPlugin {
+		return createRuntimeSpecifierAliasPlugin(this.getSpecifierMap(mode), {
+			name: `react-plugin-runtime-alias-${mode}`,
+		})!;
 	}
 }

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;
@@ -86,6 +94,62 @@ function parserLanguageForFile(filename) {
   if (extension === ".jsx") return "jsx";
   return "js";
 }
+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, "");
@@ -341,13 +405,26 @@ function transformModuleImports(source, filename, globallyAllowed, requestedExpo
   }
   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) {

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.
@@ -205,6 +213,104 @@ 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.
  *
@@ -610,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);
@@ -619,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 };
 }
 

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.
  */