@ecopages/ecopages-jsx 0.2.0-alpha.16 → 0.2.0-alpha.18

package/CHANGELOG.md

@@ -8,12 +8,18 @@
 
 ### Bug Fixes
 
+- Aligned Radiant SSR and hydration wiring with the public `@ecopages/radiant/server/render-component` and `@ecopages/radiant/client/hydrator` entrypoints so JSX apps install an explicit client hydrator bootstrap instead of relying on implicit side effects.
 - Fixed Radiant SSR page inspection to install the light-DOM shim before JSX page modules are imported outside the normal render pass.
 - Restored direct `EcopagesJsxPlugin` construction so the exported class still accepts the public plugin options shape.
 - Fixed intrinsic custom-element asset discovery so Ecopages JSX registers scripts declared with decorator and function-call `customElement(...)` syntax.
 - Fixed the Ecopages JSX browser runtime import map so browser builds no longer expose `@ecopages/jsx/server` through the shared JSX vendor bundle.
 - Fixed the Ecopages JSX browser runtime bundle so Radiant custom-element scripts no longer fail on a duplicate `jsxDEV` export cycle.
+- Fixed Ecopages JSX boundary payload compatibility coverage and removed the plugin/renderer integration-name import cycle.
 
 ### Refactoring
 
 - Replaced Ecopages JSX renderer static and post-construction configuration with instance-owned renderer wiring and extracted shared plugin and renderer types into a dedicated module.
+
+### Tests
+
+- Added renderer-level coverage for the boundary payload compatibility contract.

package/README.md

@@ -29,7 +29,7 @@ export default config;
 ## What This Integration Owns
 
 - `.tsx` route files by default. Use `extensions` to change the JSX route suffix list.
-- Optional Radiant runtime assets and import-map entries.
+- Optional Radiant SSR/runtime wiring through the public `@ecopages/radiant` entrypoints.
 - Optional `.mdx` routes compiled against the `@ecopages/jsx` runtime.
 
 ## Route Extensions
@@ -44,7 +44,13 @@ ecopagesJsxPlugin({
 
 ## Radiant Support
 
-Radiant runtime bundles are enabled by default so JSX pages can render and hydrate Radiant custom elements.
+Radiant support is enabled by default. When `radiant: true`, the plugin keeps the ownership split explicit:
+
+- Ecopages JSX owns page-level JSX SSR and container hydration.
+- Radiant SSR is activated on the server through `@ecopages/radiant/server/render-component`.
+- Radiant host hydration is activated on the client through an explicit head bootstrap that calls `installRadiantHydrator()` from `@ecopages/radiant/client/hydrator` before intrinsic custom-element modules load.
+
+That means server-rendered `RadiantComponent` hosts hydrate in place only when both the SSR markers and the explicit client hydrator are present. Without the client hydrator, Radiant intentionally falls back to a fresh client render on first connect.
 
 ```ts
 ecopagesJsxPlugin({
@@ -52,7 +58,9 @@ ecopagesJsxPlugin({
 });
 ```
 
-Set `radiant: false` when your JSX pages do not need the Radiant browser runtime on a given app.
+Set `radiant: false` when your JSX pages do not need Radiant SSR or the Radiant browser runtime on a given app.
+
+The plugin bootstrap is intentionally explicit rather than relying on unrelated imports to install the Radiant hydrator as a side effect.
 
 ## MDX Support
 
@@ -79,3 +87,9 @@ export default config;
 ## Mixed Rendering
 
 Ecopages JSX can own the outer page shell or just the nested boundary. When another integration reaches a JSX-owned boundary, Ecopages hands that boundary back to the JSX renderer so it can serialize the correct output before the outer renderer resumes.
+
+Important:
+
+- Components that may render foreign children must declare those children in `config.dependencies.components`.
+- Ecopages validates mixed-renderer ownership from declared dependencies during render preparation. It does not treat rendered HTML alone as the source of truth.
+- Ecopages JSX keeps raw-markup preservation and asset collection inside the JSX renderer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/ecopages-jsx",
-  "version": "0.2.0-alpha.16",
+  "version": "0.2.0-alpha.18",
   "description": "JSX integration plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -21,8 +21,8 @@
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.16",
-    "@ecopages/jsx": "^0.3.0-alpha.0",
-    "@ecopages/radiant": "^0.3.0-alpha.0"
+    "@ecopages/core": "0.2.0-alpha.18",
+    "@ecopages/jsx": "^0.3.0-alpha.1",
+    "@ecopages/radiant": "^0.3.0-alpha.1"
   }
 }

package/src/ecopages-jsx-renderer.d.ts

@@ -16,7 +16,7 @@ type MdxPageModule = EcoPageFile<{
  */
 export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderable> {
     name: string;
-    private static radiantLightDomShimInstallPromise;
+    private static radiantServerRuntimeInstallPromise;
     private readonly intrinsicCustomElementAssets;
     private collectedAssetFrames;
     private readonly mdxExtensions;
@@ -56,7 +56,9 @@ export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderab
     private endCollectedAssetFrame;
     private renderJsx;
     private renderEcoComponent;
-    private ensureRadiantLightDomShimInstalled;
+    private recordCollectedAssets;
+    private ensureRadiantServerRuntimeIfEnabled;
+    private ensureRadiantServerRuntimeInstalled;
     private isFunctionComponent;
     private createComponentProps;
     private collectComponentAssets;

package/src/ecopages-jsx-renderer.js

@@ -4,10 +4,10 @@ import {
 } from "@ecopages/core/route-renderer/integration-renderer";
 import { createMarkupNodeLike } from "@ecopages/jsx";
 import { renderToString, withServerCustomElementRenderHook } from "@ecopages/jsx/server";
-import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.plugin.js";
+import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
 class EcopagesJsxRenderer extends IntegrationRenderer {
   name = ECOPAGES_JSX_PLUGIN_NAME;
-  static radiantLightDomShimInstallPromise;
+  static radiantServerRuntimeInstallPromise;
   intrinsicCustomElementAssets;
   collectedAssetFrames = [];
   mdxExtensions;
@@ -71,9 +71,7 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
     return this.mdxExtensions.some((ext) => filePath.endsWith(ext));
   }
   async importPageFile(file, options) {
-    if (this.radiantSsrEnabled) {
-      await this.ensureRadiantLightDomShimInstalled();
-    }
+    await this.ensureRadiantServerRuntimeIfEnabled();
     const module = await super.importPageFile(file, options);
     return this.isMdxFile(file) ? this.normalizeMdxPageModule(file, module) : module;
   }
@@ -193,46 +191,52 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
     return this.htmlTransformer.dedupeProcessedAssets(activeFrame);
   }
   async renderJsx(value) {
-    if (this.radiantSsrEnabled) {
-      await this.ensureRadiantLightDomShimInstalled();
-    }
+    await this.ensureRadiantServerRuntimeIfEnabled();
     const collectedAssets = [];
     const html = withServerCustomElementRenderHook(
       this.createIntrinsicCustomElementRenderHook(collectedAssets),
       () => renderToString(value)
     );
-    const dedupedAssets = this.htmlTransformer.dedupeProcessedAssets(collectedAssets);
-    const activeFrame = this.collectedAssetFrames[this.collectedAssetFrames.length - 1];
-    if (activeFrame) {
-      activeFrame.push(...dedupedAssets);
-    }
+    const dedupedAssets = this.recordCollectedAssets(collectedAssets);
     return {
       assets: dedupedAssets,
       html
     };
   }
   async renderEcoComponent(component, props) {
-    if (this.radiantSsrEnabled) {
-      await this.ensureRadiantLightDomShimInstalled();
-    }
+    await this.ensureRadiantServerRuntimeIfEnabled();
     const collectedAssets = [];
     const rendered = await withServerCustomElementRenderHook(
       this.createIntrinsicCustomElementRenderHook(collectedAssets),
       () => this.invokeComponent(component, props)
     );
+    this.recordCollectedAssets(collectedAssets);
+    return rendered;
+  }
+  recordCollectedAssets(collectedAssets) {
+    const dedupedAssets = this.htmlTransformer.dedupeProcessedAssets(collectedAssets);
     const activeFrame = this.collectedAssetFrames[this.collectedAssetFrames.length - 1];
     if (activeFrame) {
-      activeFrame.push(...this.htmlTransformer.dedupeProcessedAssets(collectedAssets));
+      activeFrame.push(...dedupedAssets);
     }
-    return rendered;
+    return dedupedAssets;
+  }
+  async ensureRadiantServerRuntimeIfEnabled() {
+    if (!this.radiantSsrEnabled) {
+      return;
+    }
+    await this.ensureRadiantServerRuntimeInstalled();
   }
-  async ensureRadiantLightDomShimInstalled() {
-    if (!EcopagesJsxRenderer.radiantLightDomShimInstallPromise) {
-      EcopagesJsxRenderer.radiantLightDomShimInstallPromise = import("@ecopages/radiant/server/light-dom-shim").then((module) => {
-        module.installLightDomShim();
-      }).then(() => void 0);
+  async ensureRadiantServerRuntimeInstalled() {
+    if (!EcopagesJsxRenderer.radiantServerRuntimeInstallPromise) {
+      EcopagesJsxRenderer.radiantServerRuntimeInstallPromise = Promise.all([
+        import("@ecopages/radiant/server/render-component"),
+        import("@ecopages/radiant/server/light-dom-shim").then((module) => {
+          module.installLightDomShim();
+        })
+      ]).then(() => void 0);
     }
-    await EcopagesJsxRenderer.radiantLightDomShimInstallPromise;
+    await EcopagesJsxRenderer.radiantServerRuntimeInstallPromise;
   }
   isFunctionComponent(component) {
     return typeof component === "function";

package/src/ecopages-jsx.constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stable integration name shared by the JSX plugin and renderer.
+ *
+ * Ecopages uses this identifier to match route files, renderer instances, and
+ * cross-integration component boundaries.
+ */
+export declare const ECOPAGES_JSX_PLUGIN_NAME = "ecopages-jsx";

package/src/ecopages-jsx.constants.js

@@ -0,0 +1,4 @@
+const ECOPAGES_JSX_PLUGIN_NAME = "ecopages-jsx";
+export {
+  ECOPAGES_JSX_PLUGIN_NAME
+};

package/src/ecopages-jsx.plugin.d.ts

@@ -4,13 +4,6 @@ import type { JsxRenderable } from '@ecopages/jsx';
 import { EcopagesJsxRenderer } from './ecopages-jsx-renderer.js';
 import type { EcopagesJsxPluginOptions } from './ecopages-jsx.types.js';
 export type { EcopagesJsxMdxCompileOptions, EcopagesJsxMdxOptions, EcopagesJsxPluginOptions, EcopagesJsxRendererConfig, } from './ecopages-jsx.types.js';
-/**
- * Stable integration name shared by the JSX plugin and renderer.
- *
- * Ecopages uses this identifier to match route files, renderer instances, and
- * cross-integration component boundaries.
- */
-export declare const ECOPAGES_JSX_PLUGIN_NAME = "ecopages-jsx";
 /** JSX integration plugin for Ecopages, supporting `.tsx` templates and optional Radiant web components. */
 export declare class EcopagesJsxPlugin extends IntegrationPlugin<JsxRenderable> {
     renderer: typeof EcopagesJsxRenderer;

package/src/ecopages-jsx.plugin.js

@@ -3,9 +3,9 @@ import path from "node:path";
 import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
 import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
 import { VFile } from "vfile";
+import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
 import { EcopagesJsxRenderer } from "./ecopages-jsx-renderer.js";
 import { JsxRuntimeBundleService } from "./services/jsx-runtime-bundle.service.js";
-const ECOPAGES_JSX_PLUGIN_NAME = "ecopages-jsx";
 const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const mergePluginLists = (...lists) => {
   const merged = lists.flatMap((list) => list ? [...list] : []);
@@ -271,7 +271,6 @@ class EcopagesJsxPlugin extends IntegrationPlugin {
 }
 const ecopagesJsxPlugin = (options) => new EcopagesJsxPlugin(options);
 export {
-  ECOPAGES_JSX_PLUGIN_NAME,
   EcopagesJsxPlugin,
   ecopagesJsxPlugin
 };

package/src/ecopages-jsx.types.d.ts

@@ -33,8 +33,13 @@ export type EcopagesJsxPluginOptions = Omit<IntegrationPluginConfig, 'name' | 'e
     /** Optional JSX route extensions. Defaults to `.tsx`. */
     extensions?: string[];
     /**
-     * Whether to include the `@ecopages/radiant` and `@ecopages/signals` vendor
-     * bundles and bare-specifier mappings.
+     * Whether to include the Radiant integration contract for JSX apps.
+     *
+     * When enabled, Ecopages JSX:
+     * - imports `@ecopages/radiant/server/render-component` before Radiant SSR
+     * - exposes browser-safe Radiant bare specifiers through the runtime import map
+     * - injects an explicit client bootstrap that calls `installRadiantHydrator()`
+     *   before intrinsic custom-element modules load
      *
      * Set to `false` when pages do not use Radiant web components.
      * @default true

package/src/services/jsx-runtime-bundle.service.d.ts

@@ -10,6 +10,7 @@
  */
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
 import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+export declare const RADIANT_HYDRATOR_BOOTSTRAP_ATTRIBUTE = "data-ecopages-jsx-radiant-hydrator";
 export interface JsxRuntimeBundleServiceConfig {
     radiant: boolean;
     rootDir?: string;
@@ -44,9 +45,12 @@ export declare class JsxRuntimeBundleService {
      * script plus one `createBrowserRuntimeScriptAsset` per vendor bundle.
      */
     getDependencies(): Promise<AssetDefinition[]>;
+    private createRadiantHydratorBootstrapAsset;
+    private createRadiantHydratorBootstrapSource;
+    private getArtifactsDir;
+    private getEntryImportPath;
     private getOrCreateSpecifierMap;
     private getOrCreateJsxEntryModulePath;
-    private getRadiantBrowserRuntimeSpecifiers;
     private getRadiantBrowserRuntimeModules;
     private resolvePackageExportModulePath;
     private getOrCreateRadiantEntryModulePath;

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

@@ -2,6 +2,7 @@ import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
 import {
+  BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
   buildBrowserRuntimeAssetUrl,
   createBrowserRuntimeScriptAsset,
   AssetFactory
@@ -10,6 +11,7 @@ const VENDOR_FILE_NAMES = {
   jsx: "ecopages-jsx-esm.js",
   radiant: "ecopages-radiant-esm.js"
 };
+const RADIANT_HYDRATOR_BOOTSTRAP_ATTRIBUTE = "data-ecopages-jsx-radiant-hydrator";
 function getNamedExportNamesFromModuleSource(source) {
   const exportNames = /* @__PURE__ */ new Set();
   for (const match of source.matchAll(/export\s*\{([^}]+)\}/g)) {
@@ -37,6 +39,9 @@ function isBrowserRuntimeRadiantSpecifier(exportKey) {
   if (exportKey === "." || exportKey.startsWith("./context/")) {
     return true;
   }
+  if (exportKey === "./client/hydrator") {
+    return true;
+  }
   if (exportKey.startsWith("./decorators/") || exportKey.startsWith("./helpers/")) {
     return true;
   }
@@ -105,13 +110,18 @@ class JsxRuntimeBundleService {
         bundle: false,
         content: JSON.stringify({ imports: specifierMap }, null, 2),
         attributes: { type: "importmap" }
-      }),
+      })
+    ];
+    if (this.config.radiant) {
+      deps.push(this.createRadiantHydratorBootstrapAsset());
+    }
+    deps.push(
       createBrowserRuntimeScriptAsset({
         importPath: jsxEntryModulePath,
         name: "ecopages-jsx-esm",
         fileName: VENDOR_FILE_NAMES.jsx
       })
-    ];
+    );
     if (this.config.radiant) {
       const radiantEntryModulePath = await this.getOrCreateRadiantEntryModulePath();
       deps.push(
@@ -124,6 +134,31 @@ class JsxRuntimeBundleService {
     }
     return deps;
   }
+  createRadiantHydratorBootstrapAsset() {
+    return AssetFactory.createInlineContentScript({
+      position: "head",
+      bundle: false,
+      content: this.createRadiantHydratorBootstrapSource(),
+      attributes: {
+        ...BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+        [RADIANT_HYDRATOR_BOOTSTRAP_ATTRIBUTE]: "true"
+      }
+    });
+  }
+  createRadiantHydratorBootstrapSource() {
+    return [
+      "import { installRadiantHydrator } from '@ecopages/radiant/client/hydrator';",
+      "installRadiantHydrator();"
+    ].join("\n");
+  }
+  getArtifactsDir() {
+    const rootDir = this.config.rootDir ?? process.cwd();
+    return path.join(rootDir, "node_modules", ".cache", "ecopages-browser-runtime");
+  }
+  getEntryImportPath(fromDir, targetPath) {
+    const relativeModulePath = path.relative(fromDir, targetPath).split(path.sep).join("/");
+    return relativeModulePath.startsWith(".") ? relativeModulePath : `./${relativeModulePath}`;
+  }
   getOrCreateSpecifierMap() {
     if (this.cachedSpecifierMap) {
       return this.cachedSpecifierMap;
@@ -155,8 +190,7 @@ class JsxRuntimeBundleService {
     if (this.cachedJsxEntryModulePath) {
       return this.cachedJsxEntryModulePath;
     }
-    const rootDir = this.config.rootDir ?? process.cwd();
-    const artifactsDir = path.join(rootDir, "node_modules", ".cache", "ecopages-browser-runtime");
+    const artifactsDir = this.getArtifactsDir();
     const filePath = path.join(artifactsDir, "ecopages-jsx-esm-entry.mjs");
     const manifestPath = findPackageManifestPath("@ecopages/jsx");
     const packageDir = path.dirname(realpathSync(manifestPath));
@@ -166,16 +200,12 @@ class JsxRuntimeBundleService {
       ".",
       jsxPkg.exports?.["."]
     );
-    const relativeModulePath = path.relative(artifactsDir, jsxModulePath).split(path.sep).join("/");
-    const entryImportPath = relativeModulePath.startsWith(".") ? relativeModulePath : `./${relativeModulePath}`;
+    const entryImportPath = this.getEntryImportPath(artifactsDir, jsxModulePath);
     mkdirSync(artifactsDir, { recursive: true });
     writeFileSync(filePath, [`export * from '${entryImportPath}';`].join("\n"), "utf8");
     this.cachedJsxEntryModulePath = filePath;
     return filePath;
   }
-  getRadiantBrowserRuntimeSpecifiers() {
-    return this.getRadiantBrowserRuntimeModules().map(({ exportKey }) => `@ecopages/radiant${exportKey.slice(1)}`);
-  }
   getRadiantBrowserRuntimeModules() {
     const manifestPath = findPackageManifestPath("@ecopages/radiant");
     const packageDir = path.dirname(realpathSync(manifestPath));
@@ -205,8 +235,7 @@ class JsxRuntimeBundleService {
     if (this.cachedRadiantEntryModulePath) {
       return this.cachedRadiantEntryModulePath;
     }
-    const rootDir = this.config.rootDir ?? process.cwd();
-    const artifactsDir = path.join(rootDir, "node_modules", ".cache", "ecopages-browser-runtime");
+    const artifactsDir = this.getArtifactsDir();
     const filePath = path.join(artifactsDir, "ecopages-radiant-esm-entry.mjs");
     const seenExports = /* @__PURE__ */ new Set();
     const statements = [];
@@ -216,8 +245,7 @@ class JsxRuntimeBundleService {
       if (exportNames.length === 0) {
         continue;
       }
-      const relativeModulePath = path.relative(artifactsDir, module.modulePath).split(path.sep).join("/");
-      const entryImportPath = relativeModulePath.startsWith(".") ? relativeModulePath : `./${relativeModulePath}`;
+      const entryImportPath = this.getEntryImportPath(artifactsDir, module.modulePath);
       statements.push(`export { ${exportNames.join(", ")} } from '${entryImportPath}';`);
       for (const exportName of exportNames) {
         seenExports.add(exportName);
@@ -229,5 +257,6 @@ class JsxRuntimeBundleService {
   }
 }
 export {
-  JsxRuntimeBundleService
+  JsxRuntimeBundleService,
+  RADIANT_HYDRATOR_BOOTSTRAP_ATTRIBUTE
 };