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

package/CHANGELOG.md

@@ -6,17 +6,18 @@ All notable changes to `@ecopages/react` are documented here.
 
 ## [UNRELEASED] — TBD
 
-### Features & Performance
+### Bug Fixes
 
-- **Performance Hydration**: Introduced static reachability analysis to enforce explicit hydration boundaries and optimized HMR via metadata caching.
-- **Service-Oriented Internals**: Refactored the integration into focused core-backed services for bundling, hydration, and page-module loading.
-- **React MDX**: Inlined MDX support directly into the React integration for a zero-config setup, including Node-native compatibility for experimental startup.
+- Fixed development hydration, router HMR ownership, and page bootstraps across Bun, Vite, and Nitro flows.
+- Fixed React page and MDX module loading to use host-provided loaders on Vite or Nitro and a lightweight browser `eco` shim in preview and build output.
 
-### Bug Fixes & Refactoring
+### Features
 
-- **Handoff Stability**: Standardized router-backed page payloads and document owner markers for mixed-router stability during navigation.
-- **Hydration Hardening**: Fixed island remount races, prop collisions, and layout metadata resolution during development and route handoffs.
-- **Architecture**: Centralized runtime specifiers and consolidated browser-side integration state under `window.__ECO_PAGES__`.
+- Added built-in React MDX support and reachability-based hydration analysis for React page bundles.
+
+### Refactoring
+
+- Consolidated React bundling, hydration, and runtime state behind shared service boundaries and `window.__ECO_PAGES__`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react",
-  "version": "0.2.0-alpha.10",
+  "version": "0.2.0-alpha.11",
   "description": "React integration for Ecopages",
   "keywords": [
     "ecopages",
@@ -53,14 +53,14 @@
     "directory": "packages/integrations/react"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.10",
+    "@ecopages/core": "0.2.0-alpha.11",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.10",
+    "@ecopages/file-system": "0.2.0-alpha.11",
     "@ecopages/logger": "latest",
     "@mdx-js/esbuild": "^3.0.1",
     "@mdx-js/mdx": "^3.1.0",

package/src/react-hmr-strategy.d.ts

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { HmrStrategy, HmrStrategyType, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
 import type { DefaultHmrContext } from '@ecopages/core';
 import type { CompileOptions } from '@mdx-js/mdx';
 import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
@@ -49,7 +49,7 @@ import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metada
  * ```
  */
 export declare class ReactHmrStrategy extends HmrStrategy {
-    readonly type = HmrStrategyType.INTEGRATION;
+    readonly type: 100;
     private mdxCompilerOptions?;
     private readonly ownedTemplateExtensions;
     private readonly allTemplateExtensions;
@@ -128,6 +128,7 @@ export declare class ReactHmrStrategy extends HmrStrategy {
      * @returns True if bundling was successful
      */
     private bundleReactEntrypoint;
+    private resolveTempOutputPath;
     /**
      * Encodes dynamic route segments (brackets) in file paths.
      * Converts `[slug]` to `_slug_` to avoid filesystem issues.

package/src/react-hmr-strategy.js

@@ -225,13 +225,33 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`No output file generated for ${entrypointPath}`);
         return false;
       }
-      const processed = await this.processOutput(tempFile, outputPath, outputUrl);
+      const resolvedTempFile = await this.resolveTempOutputPath(tempFile);
+      if (!resolvedTempFile) {
+        appLogger.debug(`Skipping stale temp output for ${outputUrl}: ${tempFile}`);
+        return false;
+      }
+      const processed = await this.processOutput(resolvedTempFile, outputPath, outputUrl);
       return processed;
     } catch (error) {
       appLogger.error(`Error bundling ${entrypointPath}:`, error);
       return false;
     }
   }
+  async resolveTempOutputPath(tempPath) {
+    if (fileSystem.exists(tempPath)) {
+      return tempPath;
+    }
+    if (!tempPath.includes("[hash]")) {
+      return tempPath;
+    }
+    const directory = path.dirname(tempPath);
+    const pattern = path.basename(tempPath).replaceAll("[hash]", "*");
+    const matches = await fileSystem.glob([pattern], { cwd: directory });
+    if (matches.length === 0) {
+      return null;
+    }
+    return path.isAbsolute(matches[0]) ? matches[0] : path.join(directory, matches[0]);
+  }
   /**
    * Encodes dynamic route segments (brackets) in file paths.
    * Converts `[slug]` to `_slug_` to avoid filesystem issues.

package/src/react-renderer.d.ts

@@ -2,7 +2,7 @@
  * This module contains the React renderer
  * @module
  */
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentConfig, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
 import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
 import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
 import { type ReactNode } from 'react';
@@ -12,11 +12,6 @@ import { ReactBundleService } from './services/react-bundle.service.js';
 import { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
 import { ReactPageModuleService } from './services/react-page-module.service.js';
 import { ReactHydrationAssetService } from './services/react-hydration-asset.service.js';
-type ReactPageModule = EcoPageFile<{
-    config?: EcoComponentConfig;
-}> & {
-    config?: EcoComponentConfig;
-};
 /**
  * Error thrown when an error occurs while rendering a React component.
  */
@@ -132,6 +127,20 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * if that shell yields a string that can be inserted into the final document.
      */
     private renderNonReactShellComponent;
+    /**
+     * Renders one React component boundary for marker-graph orchestration.
+     *
+     * When the marker resolver has already stitched child HTML for this boundary,
+     * the child payload must remain raw SSR output rather than a React string
+     * child, otherwise React would escape it. This helper renders a unique token
+     * through React and swaps that token back to the stitched HTML afterward.
+     *
+     * @param input Component render input reconstructed from marker metadata.
+     * @param context React-specific render context for stable token generation.
+     * @returns Serialized component HTML with stitched child markup preserved.
+     */
+    private renderComponentHtml;
+    private buildHydrationProps;
     /**
      * Produces the page body before the final HTML template is applied.
      *
@@ -156,6 +165,8 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * - When an explicit component instance id is provided, a stable
      *   `data-eco-component-id` attribute is attached so island hydration can target it.
      * - Without an explicit instance id, component renders remain plain SSR output.
+     * - When stitched child HTML is provided, that boundary is treated as a pure SSR
+     *   composition step and does not emit hydration assets for the parent wrapper.
      *
      * This preserves DOM shape for global CSS/layout selectors while keeping a
      * deterministic mount target per component instance.
@@ -167,6 +178,9 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * @returns True if the file is an MDX file
      */
     isMdxFile(filePath: string): boolean;
+    protected usesIntegrationPageImporter(file: string): boolean;
+    protected importIntegrationPageFile(file: string): Promise<EcoPageFile>;
+    protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(file: string, pageModule: TPageModule): TPageModule;
     /**
      * Processes MDX-specific configuration dependencies including layout dependencies.
      * @param pagePath - Absolute path to the MDX page file
@@ -176,15 +190,6 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
     private processDeclaredMdxSsrLazyDependencies;
     private collectDeclaredMdxSsrLazyDependencies;
     buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
-    /**
-     * Imports a page module while normalizing React MDX modules to the same shape
-     * as ordinary React page files.
-     *
-     * MDX page imports can expose `config` separately from the default export. The
-     * React renderer reattaches that config to the page component so downstream
-     * layout, dependency, and hydration logic can treat MDX and TSX pages the same.
-     */
-    protected importPageFile(file: string): Promise<ReactPageModule>;
     /**
      * Renders a full route response for the filesystem page pipeline.
      *
@@ -222,4 +227,3 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      */
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }
-export {};

package/src/react-renderer.js

@@ -14,6 +14,21 @@ import { ReactBundleService } from "./services/react-bundle.service.js";
 import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-cache.js";
 import { ReactPageModuleService } from "./services/react-page-module.service.js";
 import { ReactHydrationAssetService } from "./services/react-hydration-asset.service.js";
+function decodeHtmlEntities(value) {
+  let decoded = value;
+  let previous;
+  do {
+    previous = decoded;
+    decoded = decoded.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&#x27;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+  } while (decoded !== previous);
+  return decoded;
+}
+function restoreEscapedComponentMarkers(html) {
+  return html.replace(
+    /&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
+    (marker) => decodeHtmlEntities(marker)
+  );
+}
 class ReactRenderError extends Error {
   constructor(message) {
     super(message);
@@ -53,7 +68,9 @@ class ReactRenderer extends IntegrationRenderer {
     this.bundleService = new ReactBundleService({
       rootDir: this.appConfig.rootDir,
       routerAdapter: ReactRenderer.routerAdapter,
-      mdxCompilerOptions: ReactRenderer.mdxCompilerOptions
+      mdxCompilerOptions: ReactRenderer.mdxCompilerOptions,
+      jsxImportSource: (this.appConfig.integrations ?? []).find((integration) => integration.name === this.name)?.jsxImportSource,
+      nonReactExtensions: (this.appConfig.integrations ?? []).filter((integration) => integration.name !== this.name).flatMap((integration) => integration.extensions)
     });
     this.pageModuleService = new ReactPageModuleService({
       rootDir: this.appConfig.rootDir,
@@ -197,6 +214,37 @@ class ReactRenderer extends IntegrationRenderer {
     }
     throw new ReactRenderError(`${label} must return a string when used as a mixed shell for React pages.`);
   }
+  /**
+   * Renders one React component boundary for marker-graph orchestration.
+   *
+   * When the marker resolver has already stitched child HTML for this boundary,
+   * the child payload must remain raw SSR output rather than a React string
+   * child, otherwise React would escape it. This helper renders a unique token
+   * through React and swaps that token back to the stitched HTML afterward.
+   *
+   * @param input Component render input reconstructed from marker metadata.
+   * @param context React-specific render context for stable token generation.
+   * @returns Serialized component HTML with stitched child markup preserved.
+   */
+  renderComponentHtml(input, context) {
+    if (input.children === void 0) {
+      return restoreEscapedComponentMarkers(
+        renderToString(createElement(this.asReactComponent(input.component), input.props))
+      );
+    }
+    const rawChildrenToken = `__ECO_RAW_HTML_CHILD_${context.componentInstanceId ?? "component"}__`;
+    const html = renderToString(
+      createElement(this.asReactComponent(input.component), input.props, rawChildrenToken)
+    );
+    return restoreEscapedComponentMarkers(html.split(rawChildrenToken).join(input.children));
+  }
+  buildHydrationProps(props) {
+    if (!props || !Object.prototype.hasOwnProperty.call(props, "locals")) {
+      return props ?? {};
+    }
+    const { locals: _locals, ...hydrationProps } = props;
+    return hydrationProps;
+  }
   /**
    * Produces the page body before the final HTML template is applied.
    *
@@ -206,7 +254,7 @@ class ReactRenderer extends IntegrationRenderer {
    */
   async composePageContent(options) {
     const pageElement = createElement(options.Page, options.pageProps);
-    const pageHtml = renderToString(pageElement);
+    const pageHtml = restoreEscapedComponentMarkers(renderToString(pageElement));
     const layoutProps = options.locals ? { locals: options.locals } : {};
     if (!options.Layout) {
       return { contentNode: pageElement, contentHtml: pageHtml };
@@ -215,7 +263,7 @@ class ReactRenderer extends IntegrationRenderer {
       const layoutElement = createElement(this.asReactComponent(options.Layout), layoutProps, pageElement);
       return {
         contentNode: layoutElement,
-        contentHtml: renderToString(layoutElement)
+        contentHtml: restoreEscapedComponentMarkers(renderToString(layoutElement))
       };
     }
     const layoutHtml = await this.renderNonReactShellComponent(
@@ -234,16 +282,20 @@ class ReactRenderer extends IntegrationRenderer {
    */
   async renderDocument(options) {
     if (this.isReactManagedComponent(options.HtmlTemplate)) {
-      return renderToReadableStream(
-        createElement(
-          this.asReactComponent(options.HtmlTemplate),
-          {
-            metadata: options.metadata,
-            pageProps: options.pageProps
-          },
-          options.contentNode
+      const rawChildrenToken = "__ECO_RAW_HTML_DOCUMENT_CHILD__";
+      const html = restoreEscapedComponentMarkers(
+        renderToString(
+          createElement(
+            this.asReactComponent(options.HtmlTemplate),
+            {
+              metadata: options.metadata,
+              pageProps: options.pageProps
+            },
+            rawChildrenToken
+          )
         )
       );
+      return html.split(rawChildrenToken).join(options.contentHtml);
     }
     const headContent = ReactRenderer.routerAdapter ? this.buildRouterPageDataScript(options.pageProps) : void 0;
     return this.renderNonReactShellComponent(
@@ -265,32 +317,33 @@ class ReactRenderer extends IntegrationRenderer {
    * - When an explicit component instance id is provided, a stable
    *   `data-eco-component-id` attribute is attached so island hydration can target it.
    * - Without an explicit instance id, component renders remain plain SSR output.
+   * - When stitched child HTML is provided, that boundary is treated as a pure SSR
+   *   composition step and does not emit hydration assets for the parent wrapper.
    *
    * This preserves DOM shape for global CSS/layout selectors while keeping a
    * deterministic mount target per component instance.
    */
   async renderComponent(input) {
-    const Component = this.asReactComponent(input.component);
     const componentConfig = input.component.config;
-    const element = input.children === void 0 ? createElement(Component, input.props) : createElement(Component, input.props, input.children);
-    let html = renderToString(element);
+    const context = input.integrationContext ?? {};
+    const hasResolvedChildHtml = input.children !== void 0;
+    let html = this.renderComponentHtml(input, context);
     let canAttachAttributes = hasSingleRootElement(html);
     let rootTag = this.getRootTagName(html);
     const componentFile = componentConfig?.__eco?.file;
-    const context = input.integrationContext ?? {};
     let rootAttributes;
     let assets;
-    if (canAttachAttributes && componentFile && context.componentInstanceId && this.assetProcessingService) {
+    if (canAttachAttributes && componentFile && context.componentInstanceId && this.assetProcessingService && !hasResolvedChildHtml) {
       const componentInstanceId = context.componentInstanceId;
       assets = await this.hydrationAssetService.buildComponentRenderAssets(
         componentFile,
         componentInstanceId,
-        input.props,
+        this.buildHydrationProps(input.props),
         componentConfig
       );
       rootAttributes = {
         "data-eco-component-id": componentInstanceId,
-        "data-eco-props": btoa(JSON.stringify(input.props ?? {}))
+        "data-eco-props": btoa(JSON.stringify(this.buildHydrationProps(input.props)))
       };
     }
     return {
@@ -310,13 +363,33 @@ class ReactRenderer extends IntegrationRenderer {
   isMdxFile(filePath) {
     return this.pageModuleService.isMdxFile(filePath);
   }
+  usesIntegrationPageImporter(file) {
+    return this.pageModuleService.isMdxFile(file);
+  }
+  async importIntegrationPageFile(file) {
+    return await this.pageModuleService.importMdxPageFile(file);
+  }
+  normalizeImportedPageFile(file, pageModule) {
+    const reactModule = pageModule;
+    const { default: Page, getMetadata, config } = reactModule;
+    if (this.pageModuleService.isMdxFile(file) && config) {
+      Page.config = config;
+    }
+    return {
+      ...pageModule,
+      default: Page,
+      getMetadata,
+      config
+    };
+  }
   /**
    * Processes MDX-specific configuration dependencies including layout dependencies.
    * @param pagePath - Absolute path to the MDX page file
    * @returns Processed assets for MDX configuration dependencies
    */
   async processMdxConfigDependencies(pagePath) {
-    const { config } = await this.importPageFile(pagePath);
+    const pageModule = await this.importPageFile(pagePath);
+    const config = pageModule.config;
     const resolvedLayout = config?.layout;
     const components = [];
     if (resolvedLayout?.config?.dependencies) {
@@ -439,26 +512,6 @@ class ReactRenderer extends IntegrationRenderer {
       );
     }
   }
-  /**
-   * Imports a page module while normalizing React MDX modules to the same shape
-   * as ordinary React page files.
-   *
-   * MDX page imports can expose `config` separately from the default export. The
-   * React renderer reattaches that config to the page component so downstream
-   * layout, dependency, and hydration logic can treat MDX and TSX pages the same.
-   */
-  async importPageFile(file) {
-    const module = this.pageModuleService.isMdxFile(file) ? await this.pageModuleService.importMdxPageFile(file) : await super.importPageFile(file);
-    const { default: Page, getMetadata, config } = module;
-    if (this.pageModuleService.isMdxFile(file) && config) {
-      Page.config = config;
-    }
-    return {
-      default: Page,
-      getMetadata,
-      config
-    };
-  }
   /**
    * Renders a full route response for the filesystem page pipeline.
    *

package/src/react.plugin.js

@@ -38,6 +38,7 @@ class ReactPlugin extends IntegrationPlugin {
     super({
       name: PLUGIN_NAME,
       extensions,
+      jsxImportSource: "react",
       ...restOptions
     });
     this.mdxEnabled = options?.mdx?.enabled ?? false;

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

@@ -16,6 +16,8 @@ export interface ReactBundleServiceConfig {
     rootDir: string;
     routerAdapter?: ReactRouterAdapter;
     mdxCompilerOptions?: CompileOptions;
+    nonReactExtensions?: string[];
+    jsxImportSource?: string;
 }
 /**
  * Manages esbuild bundle configuration and plugin creation for React page/component builds.
@@ -41,5 +43,5 @@ export declare class ReactBundleService {
      * Creates the esbuild plugin that rewrites bare React specifiers
      * to their runtime asset URLs.
      */
-    createRuntimeAliasPlugin(runtimeSpecifierMap: Record<string, string>): import("packages/core/src/build/build-types.ts").EcoBuildPlugin | null;
+    createRuntimeAliasPlugin(runtimeSpecifierMap: Record<string, string>): import("@ecopages/core/build/build-types").EcoBuildPlugin | null;
 }

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

@@ -4,6 +4,7 @@ import {
   getReactClientGraphAllowSpecifiers,
   getReactRuntimeExternalSpecifiers
 } from "../utils/react-runtime-specifier-map.js";
+import { createForeignJsxOverridePlugin } from "../utils/foreign-jsx-override-plugin.js";
 import { createUseSyncExternalStoreShimPlugin } from "../utils/use-sync-external-store-shim-plugin.js";
 import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
 import { ReactRuntimeBundleService } from "./react-runtime-bundle.service.js";
@@ -48,6 +49,10 @@ class ReactBundleService {
       declaredModules,
       alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers([], this.config.routerAdapter)
     });
+    const foreignJsxOverridePlugin = createForeignJsxOverridePlugin(this.config.nonReactExtensions ?? [], {
+      name: "react-renderer-foreign-jsx-override",
+      jsxImportSource: this.config.jsxImportSource ?? "react"
+    });
     const runtimeAliasPlugin = this.createRuntimeAliasPlugin(runtimeSpecifierMap);
     const useSyncExternalStoreShimPlugin = createUseSyncExternalStoreShimPlugin({
       name: "react-renderer-use-sync-external-store-shim",
@@ -56,9 +61,20 @@ class ReactBundleService {
     if (isMdx && this.config.mdxCompilerOptions) {
       const { createReactMdxLoaderPlugin } = await import("../utils/react-mdx-loader-plugin.js");
       const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
-      options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, mdxPlugin, useSyncExternalStoreShimPlugin];
+      options.plugins = [
+        foreignJsxOverridePlugin,
+        graphBoundaryPlugin,
+        runtimeAliasPlugin,
+        mdxPlugin,
+        useSyncExternalStoreShimPlugin
+      ];
     } else {
-      options.plugins = [graphBoundaryPlugin, runtimeAliasPlugin, useSyncExternalStoreShimPlugin];
+      options.plugins = [
+        foreignJsxOverridePlugin,
+        graphBoundaryPlugin,
+        runtimeAliasPlugin,
+        useSyncExternalStoreShimPlugin
+      ];
     }
     return options;
   }

package/src/services/react-page-module.service.js

@@ -62,7 +62,10 @@ class ReactPageModuleService {
     if (!compiledOutput) {
       throw new Error(`No compiled MDX output generated for page: ${filePath}`);
     }
-    return await import(pathToFileURL(compiledOutput).href);
+    return await import(
+      /* @vite-ignore */
+      pathToFileURL(compiledOutput).href
+    );
   }
   /**
    * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.

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

@@ -1,7 +1,7 @@
 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",
@@ -484,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.js

@@ -31,16 +31,19 @@ function getProdPageRootCleanupScript() {
   return 'window.__ECO_PAGES__=window.__ECO_PAGES__||{};window.__ECO_PAGES__.react=window.__ECO_PAGES__.react||{};window.__ECO_PAGES__.react.cleanupPageRoot=()=>{const a=window.__ECO_PAGES__.react?.pageRoot||root;if(!a){window.__ECO_PAGES__.react.pageRoot=null;window.__ECO_PAGES__?.navigation?.releaseOwnership?.("react-router");delete window.__ECO_PAGES__.page;return}window.__ECO_PAGES__.react.pageRoot=null;window.__ECO_PAGES__?.navigation?.releaseOwnership?.("react-router");delete window.__ECO_PAGES__.page;root=null;a.unmount()};';
 }
 function getDevRouterBootstrapRegistrationScript() {
-  return `window.__ECO_PAGES__?.navigation?.register({
+  return `const currentOwnerState = window.__ECO_PAGES__?.navigation?.getOwnerState?.();
+if (!(currentOwnerState?.owner === "react-router" && currentOwnerState.canHandleSpaNavigation)) {
+window.__ECO_PAGES__?.navigation?.register({
   owner: "react-router",
   cleanupBeforeHandoff: async () => {
     window.__ECO_PAGES__?.react?.cleanupPageRoot?.();
   }
 });
-window.__ECO_PAGES__?.navigation?.claimOwnership?.("react-router");`;
+window.__ECO_PAGES__?.navigation?.claimOwnership?.("react-router");
+}`;
 }
 function getProdRouterBootstrapRegistrationScript() {
-  return 'window.__ECO_PAGES__?.navigation?.register({owner:"react-router",cleanupBeforeHandoff:async()=>{window.__ECO_PAGES__?.react?.cleanupPageRoot?.()}});window.__ECO_PAGES__?.navigation?.claimOwnership?.("react-router");';
+  return 'const o=window.__ECO_PAGES__?.navigation?.getOwnerState?.();if(!(o?.owner==="react-router"&&o.canHandleSpaNavigation)){window.__ECO_PAGES__?.navigation?.register({owner:"react-router",cleanupBeforeHandoff:async()=>{window.__ECO_PAGES__?.react?.cleanupPageRoot?.()}});window.__ECO_PAGES__?.navigation?.claimOwnership?.("react-router")}';
 }
 function createDevScriptWithRouter(options) {
   const { importPath, isMdx, router, reactImportPath, reactDomClientImportPath, routerImportPath } = options;
@@ -93,16 +96,20 @@ const mount = () => {
     window.__ECO_PAGES__.react.pageRoot = root;
   }
   window.__ECO_PAGES__.hmrHandlers["${importPath}"] = async (newUrl) => {
-    if (window.__ECO_PAGES__?.navigation?.getOwnerState().owner === "react-router") {
-      await window.__ECO_PAGES__?.navigation?.reloadCurrentPage?.({ clearCache: false, source: "react-router" });
-      console.log("[ecopages] ${getComponentType(isMdx)} component updated via router");
-      return;
-    }
     try {
       const newModule = await import(newUrl);
+      const nextProps = getPageData();
       ${getHmrImportStatement(isMdx)}
-      root.render(createTree(NewPage, props));
-      console.log("[ecopages] ${getComponentType(isMdx)} component updated");
+      window.__ECO_PAGES__.page = {
+        module: "${importPath}",
+        props: nextProps
+      };
+      root.render(createTree(NewPage, nextProps));
+      if (window.__ECO_PAGES__?.navigation?.getOwnerState().owner === "react-router") {
+        console.log("[ecopages] ${getComponentType(isMdx)} component updated via router");
+      } else {
+        console.log("[ecopages] ${getComponentType(isMdx)} component updated");
+      }
     } catch (e) {
       console.error("[ecopages] Failed to hot-reload ${getComponentType(isMdx)} component:", e);
     }