@ecopages/react 0.2.0-alpha.1 → 0.2.0-alpha.11

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

@@ -1,205 +1,123 @@
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
+import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
+import {
+  buildBrowserRuntimeAssetUrl,
+  createBrowserRuntimeModuleAsset,
+  createBrowserRuntimeScriptAsset
+} from "@ecopages/core/services/asset-processing-service";
+import { createReactDomRuntimeInteropPlugin } from "../utils/react-dom-runtime-interop-plugin.js";
+import { buildReactRuntimeSpecifierMap } from "../utils/react-runtime-specifier-map.js";
 class ReactRuntimeBundleService {
+  config;
   constructor(config) {
     this.config = config;
   }
-  getRuntimeImports() {
+  get isDevelopment() {
+    return process.env.NODE_ENV === "development";
+  }
+  getCurrentRuntimeMode() {
+    return this.isDevelopment ? "development" : "production";
+  }
+  createRuntimeDefines(mode) {
+    const nodeEnv = JSON.stringify(mode);
+    return {
+      "process.env.NODE_ENV": nodeEnv,
+      "import.meta.env.NODE_ENV": nodeEnv
+    };
+  }
+  getReactVendorFileName(mode) {
+    return mode === "development" ? "react.development.js" : "react.js";
+  }
+  getReactDomVendorFileName(mode) {
+    return mode === "development" ? "react-dom.development.js" : "react-dom.js";
+  }
+  getRouterVendorFileName(mode) {
+    if (!this.config.routerAdapter) {
+      return "";
+    }
+    return mode === "development" ? `${this.config.routerAdapter.bundle.outputName}.development.js` : `${this.config.routerAdapter.bundle.outputName}.js`;
+  }
+  getRuntimeImports(mode = this.getCurrentRuntimeMode()) {
+    const reactVendorFileName = this.getReactVendorFileName(mode);
+    const reactDomVendorFileName = this.getReactDomVendorFileName(mode);
     const runtimeImports = {
-      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")
+      react: buildBrowserRuntimeAssetUrl(reactVendorFileName),
+      reactDomClient: buildBrowserRuntimeAssetUrl(reactDomVendorFileName),
+      reactJsxRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
+      reactJsxDevRuntime: buildBrowserRuntimeAssetUrl(reactVendorFileName),
+      reactDom: buildBrowserRuntimeAssetUrl(reactDomVendorFileName)
     };
     if (this.config.routerAdapter) {
-      runtimeImports.router = this.buildImportMapSourceUrl(`${this.config.routerAdapter.bundle.outputName}.js`);
+      runtimeImports.router = buildBrowserRuntimeAssetUrl(this.getRouterVendorFileName(mode));
     }
     return runtimeImports;
   }
-  getSpecifierMap() {
-    const runtimeImports = this.getRuntimeImports();
-    const map = {
-      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;
+  getSpecifierMap(mode = this.getCurrentRuntimeMode()) {
+    return buildReactRuntimeSpecifierMap(this.getRuntimeImports(mode), this.config.routerAdapter);
   }
   getDependencies() {
-    const runtimeAttrs = { type: "module", defer: "" };
-    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 = [
-      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]
+    const reactDomRuntimeInteropPlugin = createReactDomRuntimeInteropPlugin();
+    const dependencies = [];
+    for (const mode of ["production", "development"]) {
+      const reactRuntimeAliasPlugin = createRuntimeSpecifierAliasPlugin(
+        {
+          react: buildBrowserRuntimeAssetUrl(this.getReactVendorFileName(mode))
         },
-        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)
+        { name: `react-plugin-runtime-specifier-alias-${mode}` }
       );
+      const reactDomBundlePlugins = [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin].filter(
+        (plugin) => plugin !== null
+      );
+      const runtimeAliasPlugin = this.createRuntimeAliasPlugin(mode);
+      const mappedSpecifiers = new Set(Object.keys(this.getSpecifierMap(mode)));
       dependencies.push(
-        AssetFactory.createNodeModuleScript({
-          position: "head",
-          importPath: this.config.routerAdapter.bundle.importPath,
-          name: this.config.routerAdapter.bundle.outputName,
-          excludeFromHtml: true,
+        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: {
-            naming: `${this.config.routerAdapter.bundle.outputName}.js`,
-            external: unresolvedExternals,
-            plugins: [runtimeAliasPlugin]
-          },
-          attributes: runtimeAttrs
-        })
-      );
-    }
-    return dependencies;
-  }
-  createRuntimeAliasPlugin() {
-    const specifierMap = this.getSpecifierMap();
-    const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const filter = new RegExp(
-      `^(${Object.keys(specifierMap).map((key) => escapeRegExp(key)).join("|")})$`
-    );
-    return {
-      name: "react-plugin-runtime-alias",
-      setup(build) {
-        build.onResolve({ filter }, (args) => {
-          const mappedPath = specifierMap[args.path];
-          if (!mappedPath) {
-            return void 0;
+            define: this.createRuntimeDefines(mode)
           }
-          return {
-            path: mappedPath,
-            external: true
-          };
-        });
-      }
-    };
-  }
-  buildImportMapSourceUrl(fileName) {
-    return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
-  }
-  createRuntimeSpecifierAliasPlugin(specifierMap, external = true) {
-    const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const filter = new RegExp(
-      `^(${Object.keys(specifierMap).map((key) => escapeRegExp(key)).join("|")})$`
-    );
-    return {
-      name: "react-plugin-runtime-specifier-alias",
-      setup(build) {
-        build.onResolve({ filter }, (args) => {
-          const mappedPath = specifierMap[args.path];
-          if (!mappedPath) {
-            return void 0;
-          }
-          return {
-            path: mappedPath,
-            external
-          };
-        });
-      }
-    };
-  }
-  createReactDomRuntimeInteropPlugin() {
-    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 void 0;
+        }),
+        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
           }
-          reactRequirePattern.lastIndex = 0;
-          const rewritten = content.replace(reactRequirePattern, "__ecopages_react_runtime");
-          return {
-            contents: `import * as __ecopages_react_runtime from 'react';
-${rewritten}`,
-            loader: "js",
-            resolveDir: path.dirname(args.path)
-          };
-        });
-      }
-    };
-  }
-  getRuntimeArtifactsDir() {
-    const tmpDir = path.join(process.cwd(), "node_modules", ".cache", "ecopages-react-runtime");
-    fs.mkdirSync(tmpDir, { recursive: true });
-    return tmpDir;
-  }
-  createRuntimeEntry(modules, fileName) {
-    const tmpDir = this.getRuntimeArtifactsDir();
-    const requireFromRoot = createRequire(path.join(process.cwd(), "package.json"));
-    const seenExports = /* @__PURE__ */ new Set();
-    const statements = [];
-    for (const module of modules) {
-      if (module.defaultExport) {
-        statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
-        statements.push("export default __ecopages_default_export__;");
-      }
-      const exportNames = this.getModuleExportNames(module.specifier, requireFromRoot).filter(
-        (name) => !seenExports.has(name)
+        })
       );
-      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;
-  }
-  getModuleExportNames(specifier, requireFromRoot) {
-    const moduleExports = requireFromRoot(specifier);
-    return Object.keys(moduleExports).filter((name) => name !== "__esModule" && name !== "default").filter((name) => this.isValidExportName(name)).sort();
+    return dependencies;
   }
-  isValidExportName(name) {
-    return /^[$A-Z_a-z][$\w]*$/.test(name);
+  createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode()) {
+    return createRuntimeSpecifierAliasPlugin(this.getSpecifierMap(mode), {
+      name: `react-plugin-runtime-alias-${mode}`
+    });
   }
 }
 export {

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/declared-modules.js

@@ -41,7 +41,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/foreign-jsx-override-plugin.d.ts

@@ -0,0 +1,19 @@
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+interface ForeignJsxOverrideOptions {
+    jsxImportSource: string;
+    name?: string;
+}
+/**
+ * Esbuild plugin that overrides the JSX import source for non-host integration
+ * files (`.lit.tsx`, `.kita.tsx`, etc.) when bundled into a host client bundle.
+ *
+ * Without this plugin, non-host component files inherit the project-level
+ * `jsxImportSource` from tsconfig (typically `@kitajs/html`), which produces
+ * HTML strings from JSX. When the host framework calls those functions during
+ * hydration, it renders the string as a text node instead of a DOM element.
+ *
+ * This plugin prepends the host's `@jsxImportSource` pragma so esbuild compiles
+ * their JSX to the host framework's element creation calls.
+ */
+export declare function createForeignJsxOverridePlugin(nonReactExtensions: string[], options: ForeignJsxOverrideOptions): EcoBuildPlugin;
+export {};

package/src/utils/foreign-jsx-override-plugin.js

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+function createForeignJsxOverridePlugin(nonReactExtensions, options) {
+  const extensions = nonReactExtensions.filter((ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx"));
+  if (extensions.length === 0) {
+    return {
+      name: options.name ?? "react-foreign-jsx-override",
+      setup() {
+      }
+    };
+  }
+  function matchesNonReactExtension(id) {
+    for (const ext of extensions) {
+      if (id.endsWith(ext)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  const pragma = `/** @jsxImportSource ${options.jsxImportSource} */
+`;
+  const filter = new RegExp(`(${extensions.map((e) => e.replace(".", "\\.")).join("|")})$`);
+  return {
+    name: options.name ?? "react-foreign-jsx-override",
+    setup(build) {
+      build.onLoad({ filter }, (args) => {
+        if (!matchesNonReactExtension(args.path)) {
+          return void 0;
+        }
+        const source = readFileSync(args.path, "utf-8");
+        if (source.includes("@jsxImportSource")) {
+          return void 0;
+        }
+        return {
+          contents: pragma + source,
+          loader: "tsx"
+        };
+      });
+    }
+  };
+}
+export {
+  createForeignJsxOverridePlugin
+};

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