@ecopages/ecopages-jsx 0.2.0-beta.3 → 0.2.0-beta.31

package/README.md

@@ -99,6 +99,7 @@ Ecopages JSX can own the outer page shell or just a nested foreign subtree. When
 
 Important:
 
+- Cross-integration JSX children must use `EcoEmbed`. Opaque plain objects fail fast at core foreign-child queue boundaries; they are not coerced with `String(object)`.
 - 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-beta.3",
+  "version": "0.2.0-beta.31",
   "description": "JSX integration plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -27,16 +27,17 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ecopages/ecopages.git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/integrations/ecopages-jsx"
   },
   "dependencies": {
+    "@ecopages/mdx": "0.2.0-beta.31",
     "@mdx-js/mdx": "^3.1.1",
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-beta.3",
-    "@ecopages/jsx": "0.3.0-alpha.25",
-    "@ecopages/radiant": "0.3.0-alpha.25"
+    "@ecopages/core": "0.2.0-beta.31",
+    "@ecopages/jsx": "0.3.0-beta.3",
+    "@ecopages/radiant": "0.3.0-beta.3"
   }
 }

package/src/ecopages-jsx-hmr-ownership.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tracks the source files that participate in the active SSR render tree.
+ *
+ * @remarks
+ * The JSX integration renderer calls {@link updateEjsxHmrOwnership} after each
+ * page, component, or view render so the HMR strategy can answer
+ * "does this changed file affect SSR HTML?" without re-walking the tree on
+ * every watcher event.
+ *
+ * The state is module-scoped because the HMR strategy and renderer live in
+ * different call sites (server strategy vs SSR renderer) and share no other
+ * lifecycle anchor. A fresh state is installed only when the source-file set
+ * changes, so the renderer's per-render hook stays O(1) in the steady state.
+ */
+import type { EcoComponent } from '@ecopages/core';
+export type EjsxHmrOwnershipState = {
+    fileOwners: ReadonlySet<string>;
+    hash: string;
+};
+/**
+ * Returns the most recently recorded active render tree.
+ */
+export declare function getEjsxHmrOwnership(): EjsxHmrOwnershipState;
+/**
+ * Updates the active render tree from one or more root components.
+ *
+ * @remarks
+ * Walks each root's `config.__eco.file`, `config.dependencies.components[*].config`,
+ * and `config.layouts[*].config` recursively, collecting every file path. The
+ * state is replaced only when the resulting file set has a different hash, so
+ * the renderer's per-render hook is free in the steady state.
+ */
+export declare function updateEjsxHmrOwnership(components: ReadonlyArray<EcoComponent | undefined>): void;
+/**
+ * Resets the state to empty. Used by tests and by HMR manager teardown.
+ */
+export declare function resetEjsxHmrOwnership(): void;

package/src/ecopages-jsx-hmr-ownership.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { rapidhash } from "@ecopages/core/hash";
+const EMPTY_STATE = {
+  fileOwners: /* @__PURE__ */ new Set(),
+  hash: ""
+};
+let currentState = EMPTY_STATE;
+function getEjsxHmrOwnership() {
+  return currentState;
+}
+function updateEjsxHmrOwnership(components) {
+  const files = collectFileOwners(components);
+  const hash = hashFileSet(files);
+  if (hash === currentState.hash) {
+    return;
+  }
+  currentState = {
+    fileOwners: files,
+    hash
+  };
+}
+function resetEjsxHmrOwnership() {
+  currentState = EMPTY_STATE;
+}
+function collectFileOwners(components) {
+  const files = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (config) => {
+    const file = config?.__eco?.file;
+    if (!file) {
+      return;
+    }
+    const resolved = path.resolve(file);
+    if (visited.has(resolved)) {
+      return;
+    }
+    visited.add(resolved);
+    files.add(resolved);
+    for (const dependency of config?.dependencies?.components ?? []) {
+      visit(dependency?.config);
+    }
+    for (const layout of config?.layouts ?? []) {
+      visit(layout?.config);
+    }
+  };
+  for (const component of components) {
+    visit(component?.config);
+  }
+  return files;
+}
+function hashFileSet(files) {
+  if (files.size === 0) {
+    return "";
+  }
+  const sorted = Array.from(files).sort();
+  const joined = sorted.join("\n");
+  return rapidhash(joined).toString(36);
+}
+export {
+  getEjsxHmrOwnership,
+  resetEjsxHmrOwnership,
+  updateEjsxHmrOwnership
+};

package/src/ecopages-jsx-hmr-strategy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * HMR strategy for JSX integration-owned SSR source modules.
+ *
+ * @remarks
+ * Edits to files that produce SSR HTML (page sources, layout sources, components
+ * that the active render tree depends on) need a soft page refetch so the
+ * browser picks up the new markup. Plain `update` events re-import modules on
+ * the client but leave the server-rendered DOM stale.
+ *
+ * The strategy matches a file when any of these hold:
+ * - the file lives under `pagesDir` or `layoutsDir` and has a JSX `templatesExt`
+ * - the file appears in the active render tree's component dependency graph
+ *
+ * It defers registered HMR entrypoints to {@link JsHmrStrategy} so script-only
+ * edits keep their existing `update`-then-hot-accept path. It also defers
+ * include templates and explicit server views to {@link ServerRenderedTemplateHmrStrategy}
+ * by returning `false` for those paths.
+ */
+import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+export interface EcopagesJsxHmrStrategyContext {
+    getWatchedFiles(): Map<string, string>;
+    getSrcDir(): string;
+    getPagesDir(): string;
+    getLayoutsDir(): string;
+    getIncludesDir(): string;
+    getTemplateExtensions(): ReadonlyArray<string>;
+}
+export declare class EcopagesJsxHmrStrategy extends HmrStrategy {
+    readonly type: 100;
+    private readonly context;
+    constructor(context: EcopagesJsxHmrStrategyContext);
+    matches(filePath: string): boolean;
+    process(filePath: string): Promise<HmrAction>;
+    private isPageOrLayoutSource;
+    private hasJsxTemplateExtension;
+}

package/src/ecopages-jsx-hmr-strategy.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
+import { getEjsxHmrOwnership } from "./ecopages-jsx-hmr-ownership.js";
+class EcopagesJsxHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.INTEGRATION;
+  context;
+  constructor(context) {
+    super();
+    this.context = context;
+  }
+  matches(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    const watchedFiles = this.context.getWatchedFiles();
+    if (watchedFiles.has(resolvedPath) || [...watchedFiles.keys()].some((key) => path.resolve(key) === resolvedPath)) {
+      return false;
+    }
+    const srcDir = path.resolve(this.context.getSrcDir());
+    if (!resolvedPath.startsWith(`${srcDir}${path.sep}`) && resolvedPath !== srcDir) {
+      return false;
+    }
+    const includesDir = path.resolve(this.context.getIncludesDir());
+    if (includesDir && (resolvedPath === includesDir || resolvedPath.startsWith(`${includesDir}${path.sep}`))) {
+      return false;
+    }
+    if (this.isPageOrLayoutSource(resolvedPath)) {
+      return this.hasJsxTemplateExtension(resolvedPath);
+    }
+    const ownership = getEjsxHmrOwnership();
+    if (ownership.fileOwners.has(resolvedPath)) {
+      return true;
+    }
+    return false;
+  }
+  async process(filePath) {
+    return {
+      type: "broadcast",
+      events: [
+        {
+          type: "layout-update",
+          path: filePath,
+          timestamp: Date.now()
+        }
+      ]
+    };
+  }
+  isPageOrLayoutSource(resolvedPath) {
+    const pagesDir = path.resolve(this.context.getPagesDir());
+    const layoutsDir = path.resolve(this.context.getLayoutsDir());
+    if (pagesDir && (resolvedPath === pagesDir || resolvedPath.startsWith(`${pagesDir}${path.sep}`))) {
+      return true;
+    }
+    if (layoutsDir && (resolvedPath === layoutsDir || resolvedPath.startsWith(`${layoutsDir}${path.sep}`))) {
+      return true;
+    }
+    return false;
+  }
+  hasJsxTemplateExtension(resolvedPath) {
+    return this.context.getTemplateExtensions().some((extension) => resolvedPath.endsWith(extension));
+  }
+}
+export {
+  EcopagesJsxHmrStrategy
+};

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

@@ -1,6 +1,7 @@
 import type { CompileOptions } from '@mdx-js/mdx';
 import type { EcoComponent, EcoComponentConfig, EcoFunctionComponent, EcoPageFile, GetMetadata } from '@ecopages/core';
 import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import { appendMdxExtensions, createMdxExtensionFilter } from '@ecopages/mdx/core';
 import type { JsxRenderable } from '@ecopages/jsx';
 import type { EcopagesJsxMdxCompileOptions, EcopagesJsxMdxOptions } from './ecopages-jsx.types.js';
 export type ResolvedMdxCompileOptions = EcopagesJsxMdxCompileOptions & Pick<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
@@ -10,10 +11,7 @@ export type EcopagesJsxMdxPageModule = EcoPageFile<{
     layout?: EcoComponent;
     getMetadata?: GetMetadata;
 }>;
-export declare const createMdxExtensionFilter: (extensions: string[], options?: {
-    allowQueryString?: boolean;
-}) => RegExp;
-export declare const appendMdxExtensions: (target: string[], mdxExtensions: string[]) => void;
+export { appendMdxExtensions, createMdxExtensionFilter };
 export declare const resolveMdxCompilerOptions: (mdxOptions: EcopagesJsxMdxOptions) => ResolvedMdxCompileOptions;
 export declare const createMdxLoaderPlugin: (compilerOptions: ResolvedMdxCompileOptions, extensions: string[]) => EcoBuildPlugin;
 export declare const registerBunMdxPlugin: (compilerOptions: ResolvedMdxCompileOptions, extensions: string[]) => Promise<void>;

package/src/ecopages-jsx-mdx.js

@@ -1,62 +1,28 @@
 import { readFile } from "node:fs/promises";
-import path from "node:path";
+import { ensurePageConfigLayouts } from "@ecopages/core/eco/page-layout-normalization";
 import { rapidhash } from "@ecopages/core/hash";
+import {
+  appendMdxExtensions,
+  createMdxExtensionFilter,
+  createMdxLoaderPlugin as createMdxLoaderPluginCore,
+  resolveMdxCompilerOptions as resolveMdxCompilerOptionsCore
+} from "@ecopages/mdx/core";
 import { VFile } from "vfile";
 import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
-const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-const mergePluginLists = (...lists) => {
-  const merged = lists.flatMap((list) => list ? [...list] : []);
-  return merged.length > 0 ? merged : void 0;
-};
-const createMdxExtensionFilter = (extensions, options) => {
-  const escaped = extensions.map(escapeRegex);
-  const suffix = options?.allowQueryString ? "(\\?.*)?$" : "$";
-  return new RegExp(`(${escaped.join("|")})${suffix}`);
-};
-const appendMdxExtensions = (target, mdxExtensions) => {
-  for (const ext of mdxExtensions) {
-    if (!target.includes(ext)) {
-      target.push(ext);
-    }
-  }
-};
-const resolveMdxCompilerOptions = (mdxOptions) => {
-  const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = mdxOptions;
-  const resolved = {
+const resolveMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptionsCore(mdxOptions, {
+  jsxImportSource: "@ecopages/jsx",
+  defaults: {
     format: "detect",
-    outputFormat: "program",
-    ...compilerOptions,
-    jsxImportSource: "@ecopages/jsx",
-    jsxRuntime: "automatic",
-    development: process.env.NODE_ENV === "development"
-  };
-  const mergedRemark = mergePluginLists(compilerOptions?.remarkPlugins, remarkPlugins);
-  const mergedRehype = mergePluginLists(compilerOptions?.rehypePlugins, rehypePlugins);
-  const mergedRecma = mergePluginLists(compilerOptions?.recmaPlugins, recmaPlugins);
-  if (mergedRemark) resolved.remarkPlugins = mergedRemark;
-  if (mergedRehype) resolved.rehypePlugins = mergedRehype;
-  if (mergedRecma) resolved.recmaPlugins = mergedRecma;
-  return resolved;
-};
-const createMdxLoaderPlugin = (compilerOptions, extensions) => {
-  const filter = createMdxExtensionFilter(extensions, { allowQueryString: true });
-  return {
-    name: "ecopages-jsx-mdx-loader",
-    setup(build) {
-      build.onLoad({ filter }, async (args) => {
-        const { compile } = await import("@mdx-js/mdx");
-        const filePath = args.path.includes("?") ? args.path.split("?")[0] : args.path;
-        const source = await readFile(filePath, "utf-8");
-        const compiled = await compile(new VFile({ value: source, path: filePath }), compilerOptions);
-        return {
-          contents: String(compiled.value),
-          loader: "js",
-          resolveDir: path.dirname(filePath)
-        };
-      });
-    }
-  };
-};
+    outputFormat: "program"
+  }
+});
+const createMdxLoaderPlugin = (compilerOptions, extensions) => createMdxLoaderPluginCore({
+  name: "ecopages-jsx-mdx-loader",
+  compilerOptions,
+  extensions,
+  includeSourceMap: false,
+  loader: "js"
+});
 const registerBunMdxPlugin = async (compilerOptions, extensions) => {
   if (typeof Bun === "undefined") {
     return;
@@ -84,13 +50,16 @@ const normalizeMdxPageModule = (file, module) => {
   const Page = module.default;
   const normalizedConfig = {
     ...module.config ?? Page.config ?? {},
-    ...module.layout ? { layout: module.layout } : {},
     __eco: module.config?.__eco ?? Page.config?.__eco ?? {
       id: String(rapidhash(file)),
       file,
       integration: ECOPAGES_JSX_PLUGIN_NAME
     }
   };
+  if (module.layout && !(normalizedConfig.layouts && normalizedConfig.layouts.length > 0)) {
+    normalizedConfig.layout = module.layout;
+  }
+  ensurePageConfigLayouts(normalizedConfig);
   const wrappedPage = async (props) => await Page(props);
   wrappedPage.config = normalizedConfig;
   if (module.getMetadata ?? Page.metadata) {

package/src/ecopages-jsx-radiant-ssr-policy.d.ts

@@ -4,13 +4,14 @@ import { createMarkupNodeLike } from '@ecopages/jsx';
  *
  * @remarks
  * Radiant's server bridge and light-DOM shim are loaded lazily because most JSX
- * renders do not need them. Once enabled, the resolved runtime modules are
- * cached statically so repeated page and component renders do not keep paying
- * module-resolution or shim-installation costs.
+ * renders do not need them. Resolved runtime modules are cached on the policy
+ * instance so repeated renders on the same renderer reuse one load without
+ * process-wide mutable class state. Light-DOM constructor installation remains
+ * process-global and idempotent via {@link ensureRadiantLightDomGlobals}.
  */
 export declare class EcopagesJsxRadiantSsrPolicy {
-    private static runtimeModules;
-    private static runtimeModulesPromise;
+    private runtimeModules;
+    private runtimeModulesPromise;
     private readonly enabled;
     constructor(enabled: boolean);
     /**

package/src/ecopages-jsx-radiant-ssr-policy.js

@@ -1,8 +1,8 @@
 import { createMarkupNodeLike } from "@ecopages/jsx";
 import { createServerHydrationBindingState, withServerHydrationBindingState } from "@ecopages/jsx/server";
 class EcopagesJsxRadiantSsrPolicy {
-  static runtimeModules;
-  static runtimeModulesPromise;
+  runtimeModules;
+  runtimeModulesPromise;
   enabled;
   constructor(enabled) {
     this.enabled = enabled;
@@ -23,7 +23,7 @@ class EcopagesJsxRadiantSsrPolicy {
     if (!this.enabled) {
       return render();
     }
-    const runtimeModules = await EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise;
+    const runtimeModules = await this.runtimeModulesPromise;
     if (!runtimeModules) {
       return render();
     }
@@ -37,7 +37,7 @@ class EcopagesJsxRadiantSsrPolicy {
    * generated host HTML without escaping it back into plain text.
    */
   renderIntrinsicElementMarkup(instance) {
-    const renderBridge = EcopagesJsxRadiantSsrPolicy.runtimeModules?.resolveRadiantElementRenderBridge(instance);
+    const renderBridge = this.runtimeModules?.resolveRadiantElementRenderBridge(instance);
     if (!renderBridge) {
       return void 0;
     }
@@ -51,28 +51,54 @@ class EcopagesJsxRadiantSsrPolicy {
     );
   }
   async ensureRuntimeInstalled() {
-    if (!EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise) {
+    if (!this.runtimeModulesPromise) {
       const radiantLightDomShimEntry = import.meta.resolve("@ecopages/radiant/server/light-dom-shim");
       const radiantElementSsrRuntimeModuleUrl = new URL(
         "./radiant-element-ssr-bridge.js",
         radiantLightDomShimEntry
       ).href;
-      EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise = Promise.all([
-        import(radiantElementSsrRuntimeModuleUrl),
-        import(radiantLightDomShimEntry)
-      ]).then(([radiantElementSsrRuntimeModule, lightDomShimModule2]) => {
+      this.runtimeModulesPromise = (async () => {
+        const lightDomShimModule2 = await import(radiantLightDomShimEntry);
+        ensureRadiantLightDomGlobals(lightDomShimModule2.installLightDomShim);
+        const radiantElementSsrRuntimeModule = await import(radiantElementSsrRuntimeModuleUrl);
         const modules = {
           installLightDomShim: lightDomShimModule2.installLightDomShim,
           resolveRadiantElementRenderBridge: radiantElementSsrRuntimeModule.resolveRadiantElementRenderBridge,
           withServerRadiantElementSsrRuntime: radiantElementSsrRuntimeModule.withServerRadiantElementSsrRuntime
         };
-        EcopagesJsxRadiantSsrPolicy.runtimeModules = modules;
+        this.runtimeModules = modules;
         return modules;
-      });
+      })();
     }
-    const lightDomShimModule = await EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise;
-    lightDomShimModule.installLightDomShim();
+    await this.runtimeModulesPromise;
+    const lightDomShimModule = this.runtimeModules;
+    if (lightDomShimModule) {
+      ensureRadiantLightDomGlobals(lightDomShimModule.installLightDomShim);
+    }
+  }
+}
+function ensureRadiantLightDomGlobals(installLightDomShim) {
+  if (typeof globalThis.HTMLElement !== "undefined") {
+    return;
+  }
+  const window = installLightDomShim();
+  if (!window) {
+    return;
   }
+  Object.assign(globalThis, {
+    CSS: window.CSS,
+    CustomEvent: window.CustomEvent,
+    Document: window.Document,
+    Element: window.Element,
+    Event: window.Event,
+    EventTarget: window.EventTarget,
+    HTMLScriptElement: window.HTMLScriptElement,
+    HTMLElement: window.HTMLElement,
+    Node: window.Node,
+    document: window.document,
+    customElements: window.customElements,
+    window
+  });
 }
 export {
   EcopagesJsxRadiantSsrPolicy

package/src/ecopages-jsx-render-session.d.ts

@@ -24,13 +24,6 @@ export declare class EcopagesJsxRenderSession {
      * JSX SSR scope bridge.
      */
     withActiveScope<T>(render: () => T): T;
-    /**
-     * Runs work with the current page-level hydrate binding namespace attached to JSX SSR.
-     *
-     * This lets page, layout, and document renders participate in one client-owned
-     * hydration root even though Ecopages composes them through multiple sibling render calls.
-     */
-    withHydrationBindingScope<T>(render: () => T): T;
     beginCollectedAssetFrame(): ProcessedAsset[];
     endCollectedAssetFrame(frame: ProcessedAsset[]): ProcessedAsset[];
     recordCollectedAssets(collectedAssets: ProcessedAsset[]): ProcessedAsset[];

package/src/ecopages-jsx-render-session.js

@@ -1,10 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import {
-  createServerHydrationBindingState,
-  getActiveSsrScopeValue,
-  withActiveSsrScopeValue,
-  withServerHydrationBindingState
-} from "@ecopages/jsx/server";
+import { getActiveSsrScopeValue, withActiveSsrScopeValue } from "@ecopages/jsx/server";
 const ECOPAGES_JSX_SSR_RENDER_STATE_KEY = /* @__PURE__ */ Symbol.for("@ecopages/ecopages-jsx.ssr-render-state");
 const renderStateStorage = new AsyncLocalStorage();
 class EcopagesJsxRenderSession {
@@ -32,23 +27,13 @@ class EcopagesJsxRenderSession {
       return renderStateStorage.run(jsxScopeState, () => render());
     }
     const state = {
-      collectedAssetFrames: [],
-      hydrationBindingState: createServerHydrationBindingState()
+      collectedAssetFrames: []
     };
     return renderStateStorage.run(
       state,
       () => withActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY, state, render)
     );
   }
-  /**
-   * Runs work with the current page-level hydrate binding namespace attached to JSX SSR.
-   *
-   * This lets page, layout, and document renders participate in one client-owned
-   * hydration root even though Ecopages composes them through multiple sibling render calls.
-   */
-  withHydrationBindingScope(render) {
-    return withServerHydrationBindingState(this.getState().hydrationBindingState, render);
-  }
   beginCollectedAssetFrame() {
     const state = this.getState();
     const frame = [];

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

@@ -1,6 +1,6 @@
 import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
-import { IntegrationRenderer, type RenderToResponseContext, type RouteModuleLoadOptions } from '@ecopages/core/route-renderer/integration-renderer';
-import type { ForeignChildRuntime } from '@ecopages/core/route-renderer/component-render-context';
+import { IntegrationRenderer, type RenderToResponseContext, type RouteModuleLoadOptions } from '@ecopages/core/route-renderer/orchestration/integration-renderer';
+import type { ForeignChildRuntime } from '@ecopages/core/route-renderer/orchestration/foreign-child/component-render-context';
 import { type JsxRenderable } from '@ecopages/jsx';
 import { type EcopagesJsxMdxPageModule } from './ecopages-jsx-mdx.js';
 import type { EcopagesJsxRendererOptions } from './ecopages-jsx.types.js';
@@ -16,19 +16,26 @@ export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderab
     private readonly mdxExtensions;
     private readonly renderSession;
     private readonly radiantSsrPolicy;
+    /**
+     * Serializes foreign-child props for string-first boundaries.
+     *
+     * @remarks
+     * DOM nodes become `outerHTML`. JSX trees, arrays, and template results are
+     * stringified here. Other values are left for core foreign-child interception,
+     * which rejects opaque plain objects before queueing. Cross-integration
+     * children must use `EcoEmbed`.
+     */
     private normalizeForeignChildProps;
+    /**
+     * Returns whether children are a JSX/template shape this renderer can
+     * serialize before foreign-child queueing.
+     */
+    private isJsxSerializableForeignChild;
     /**
      * Re-renders queued JSX children inside the owning renderer so nested custom
      * elements and queued foreign subtrees contribute assets to the same frame.
      */
     private renderQueuedForeignSubtreeChildren;
-    /**
-     * Resolves queued foreign subtrees after JSX has been stringified.
-     *
-     * JSX content needs one extra render pass because child foreign subtrees may emit
-     * additional browser assets while also replacing placeholder tokens.
-     */
-    private resolveOwnedForeignSubtreeHtml;
     protected createForeignChildRuntime(options: {
         renderInput: ComponentRenderInput;
         rendererCache: Map<string, IntegrationRenderer<any>>;
@@ -44,4 +51,10 @@ export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderab
     private withCustomElementRenderHook;
     private withPreparedRadiantRuntime;
     private createIntrinsicCustomElementRenderHook;
+    /**
+     * Records the source files that produced the current render so
+     * {@link EcopagesJsxHmrStrategy} can match later watcher events without
+     * re-walking the component tree.
+     */
+    private recordHmrOwnership;
 }

package/src/ecopages-jsx-renderer.js

@@ -1,6 +1,10 @@
 import {
   IntegrationRenderer
-} from "@ecopages/core/route-renderer/integration-renderer";
+} from "@ecopages/core/route-renderer/orchestration/integration-renderer";
+import {
+  getForeignSubtreeResolutionContextKey,
+  resolveOwningIntegrationRenderer
+} from "@ecopages/core/route-renderer/orchestration/foreign-child/owning-renderer-resolution";
 import { createMarkupNodeLike } from "@ecopages/jsx";
 import { renderToString, withServerCustomElementRenderHook } from "@ecopages/jsx/server";
 import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
@@ -10,11 +14,21 @@ import {
 } from "./ecopages-jsx-mdx.js";
 import { EcopagesJsxRenderSession } from "./ecopages-jsx-render-session.js";
 import { EcopagesJsxRadiantSsrPolicy } from "./ecopages-jsx-radiant-ssr-policy.js";
+import { updateEjsxHmrOwnership } from "./ecopages-jsx-hmr-ownership.js";
 class EcopagesJsxRenderer extends IntegrationRenderer {
   name = ECOPAGES_JSX_PLUGIN_NAME;
   mdxExtensions;
   renderSession;
   radiantSsrPolicy;
+  /**
+   * Serializes foreign-child props for string-first boundaries.
+   *
+   * @remarks
+   * DOM nodes become `outerHTML`. JSX trees, arrays, and template results are
+   * stringified here. Other values are left for core foreign-child interception,
+   * which rejects opaque plain objects before queueing. Cross-integration
+   * children must use `EcoEmbed`.
+   */
   normalizeForeignChildProps(props) {
     if (!("children" in props)) {
       return props;
@@ -29,10 +43,29 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
         children: children.outerHTML
       };
     }
-    return {
-      ...props,
-      children: renderToString(children)
-    };
+    if (this.isJsxSerializableForeignChild(children)) {
+      return {
+        ...props,
+        children: renderToString(children)
+      };
+    }
+    return props;
+  }
+  /**
+   * Returns whether children are a JSX/template shape this renderer can
+   * serialize before foreign-child queueing.
+   */
+  isJsxSerializableForeignChild(children) {
+    if (Array.isArray(children)) {
+      return true;
+    }
+    if (children === null || typeof children !== "object") {
+      return false;
+    }
+    if ("$$typeof" in children) {
+      return true;
+    }
+    return "strings" in children && Array.isArray(children.strings);
   }
   /**
    * Re-renders queued JSX children inside the owning renderer so nested custom
@@ -61,24 +94,6 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
       html
     };
   }
-  /**
-   * Resolves queued foreign subtrees after JSX has been stringified.
-   *
-   * JSX content needs one extra render pass because child foreign subtrees may emit
-   * additional browser assets while also replacing placeholder tokens.
-   */
-  async resolveOwnedForeignSubtreeHtml(html, runtimeContext) {
-    return this.foreignSubtreeExecutionService.resolveQueuedHtml({
-      currentIntegrationName: this.name,
-      html,
-      runtimeContext,
-      queueLabel: "Ecopages JSX",
-      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache),
-      applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
-      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
-      renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => this.renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken)
-    });
-  }
   createForeignChildRuntime(options) {
     const runtime = super.createForeignChildRuntime(options);
     const interceptForeignChild = runtime.interceptForeignChild;
@@ -125,7 +140,7 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
     return await this.withPreparedRadiantRuntime(
       () => this.renderSession.withActiveScope(async () => {
         try {
-          return await this.renderPageWithDocumentShell({
+          const result = await this.renderPageWithDocumentShell({
             page: {
               component: options.Page,
               props: {
@@ -144,6 +159,8 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
             metadata: options.metadata,
             pageProps: options.pageProps ?? {}
           });
+          this.recordHmrOwnership([options.Page, options.Layout, options.HtmlTemplate]);
+          return result;
         } catch (error) {
           throw this.createRenderError("Error rendering page", error);
         }
@@ -165,18 +182,33 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
           };
           const content = await this.withCustomElementRenderHook(() => component(componentProps));
           const rendered = await this.renderJsx(content);
-          const queuedForeignSubtreeResolution = await this.resolveOwnedForeignSubtreeHtml(
-            rendered.html,
-            this.getQueuedForeignSubtreeResolutionContext(
-              input
-            )
-          );
+          const queuedForeignSubtreeResolution = await this.foreignSubtreeExecutionService.resolveQueuedHtml({
+            currentIntegrationName: this.name,
+            html: rendered.html,
+            runtimeContext: this.foreignSubtreeExecutionService.getQueuedRuntimeContext(
+              input,
+              getForeignSubtreeResolutionContextKey(this.name)
+            ),
+            queueLabel: "Ecopages JSX",
+            getOwningRenderer: (integrationName, rendererCache) => resolveOwningIntegrationRenderer({
+              appConfig: this.appConfig,
+              runtimeOrigin: this.runtimeOrigin,
+              currentIntegrationName: this.name,
+              currentRenderer: this,
+              integrationName,
+              cache: rendererCache
+            }),
+            applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
+            dedupeProcessedAssets: (assets2) => this.htmlTransformer.dedupeProcessedAssets(assets2),
+            renderQueuedChildren: (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => this.renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken)
+          });
           const componentAssets = input.component.config?.dependencies && typeof this.assetProcessingService?.processDependencies === "function" ? await this.processComponentDependencies([input.component]) : [];
           const assets = this.htmlTransformer.dedupeProcessedAssets([
             ...this.renderSession.endCollectedAssetFrame(assetFrame),
             ...queuedForeignSubtreeResolution.assets,
             ...componentAssets
           ]);
+          this.recordHmrOwnership([input.component]);
           return {
             html: queuedForeignSubtreeResolution.html,
             canAttachAttributes: true,
@@ -199,12 +231,15 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
             throw new TypeError("JSX renderer expected a callable view component.");
           }
           const viewComponent = view;
-          return await this.renderViewWithDocumentShell({
+          const layouts = viewComponent.config?.layouts;
+          const response = await this.renderViewWithDocumentShell({
             view: viewComponent,
             props,
             ctx,
-            layout: viewComponent.config?.layout
+            layout: layouts?.[layouts.length - 1]
           });
+          this.recordHmrOwnership([view]);
+          return response;
         } catch (error) {
           throw this.createRenderError("Error rendering view", error);
         }
@@ -234,6 +269,14 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
       return instance ? this.radiantSsrPolicy.renderIntrinsicElementMarkup(instance) : void 0;
     };
   }
+  /**
+   * Records the source files that produced the current render so
+   * {@link EcopagesJsxHmrStrategy} can match later watcher events without
+   * re-walking the component tree.
+   */
+  recordHmrOwnership(components) {
+    updateEjsxHmrOwnership(components);
+  }
 }
 export {
   EcopagesJsxRenderer

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

@@ -1,4 +1,7 @@
 import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
+import type { IHmrManager } from '@ecopages/core';
 import type { JsxRenderable } from '@ecopages/jsx';
 import { EcopagesJsxRenderer } from './ecopages-jsx-renderer.js';
 import type { EcopagesJsxPluginOptions } from './ecopages-jsx.types.js';
@@ -21,6 +24,20 @@ export declare class EcopagesJsxPlugin extends IntegrationPlugin<JsxRenderable>
     private getDependencies;
     /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
     prepareBuildContributions(): Promise<void>;
+    /** Assigns grouped-build metadata for page-owned JSX content scripts. */
+    prepareAssetDependencies(dependencies: AssetDefinition[]): AssetDefinition[];
+    /** Registers JSX HMR strategy and Radiant SSR invalidation hooks. */
+    setHmrManager(hmrManager: IHmrManager): void;
+    /**
+     * Returns the JSX-integration HMR strategy.
+     *
+     * @remarks
+     * The strategy handles `layout-update` broadcasts for page sources, layout
+     * sources, and any component file in the active render tree. It defers
+     * registered script entrypoints to the generic JS strategy and includes /
+     * explicit server views to `ServerRenderedTemplateHmrStrategy`.
+     */
+    getHmrStrategy(): HmrStrategy | undefined;
     /**
      * Registers MDX tooling and completes the base integration setup.
      */

package/src/ecopages-jsx.plugin.js

@@ -3,6 +3,7 @@ import {
 } from "@ecopages/core/plugins/integration-plugin";
 import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
 import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
+import { RADIANT_INSTALL_HYDRATOR_FILEPATH } from "./resolve-radiant-install-hydrator.js";
 import {
   appendMdxExtensions,
   createMdxLoaderPlugin,
@@ -10,6 +11,9 @@ import {
   resolveMdxCompilerOptions
 } from "./ecopages-jsx-mdx.js";
 import { EcopagesJsxRenderer } from "./ecopages-jsx-renderer.js";
+import { EcopagesJsxHmrStrategy } from "./ecopages-jsx-hmr-strategy.js";
+import { assignPageOwnedContentScriptGroupedBundles } from "./page-owned-content-script-grouping.js";
+import { invalidateRadiantRegisteredScriptSsrRegistration } from "./radiant-registered-script-ssr-invalidation.js";
 const RADIANT_HYDRATOR_SCRIPT_ID = "ecopages-jsx-radiant-hydrator";
 const resolvePluginOptions = (options) => {
   const { extensions: userExtensions, radiant, mdx, ...baseConfig } = options ?? {};
@@ -72,7 +76,7 @@ class EcopagesJsxPlugin extends IntegrationPlugin {
     return [
       AssetFactory.createNodeModuleScript({
         position: "head",
-        importPath: "@ecopages/radiant/client/install-hydrator",
+        importPath: RADIANT_INSTALL_HYDRATOR_FILEPATH,
         bundle: false,
         attributes: {
           "data-eco-script-id": RADIANT_HYDRATOR_SCRIPT_ID
@@ -84,6 +88,45 @@ class EcopagesJsxPlugin extends IntegrationPlugin {
   async prepareBuildContributions() {
     this.ensureMdxLoaderPlugin();
   }
+  /** Assigns grouped-build metadata for page-owned JSX content scripts. */
+  prepareAssetDependencies(dependencies) {
+    return assignPageOwnedContentScriptGroupedBundles(dependencies);
+  }
+  /** Registers JSX HMR strategy and Radiant SSR invalidation hooks. */
+  setHmrManager(hmrManager) {
+    super.setHmrManager(hmrManager);
+    if (!this.includeRadiant || !this.appConfig) {
+      return;
+    }
+    const runtime = this.appConfig.runtime ?? {};
+    this.appConfig.runtime = runtime;
+    runtime.registeredScriptEntrypointChangeHandlers ??= [];
+    runtime.registeredScriptEntrypointChangeHandlers.push(invalidateRadiantRegisteredScriptSsrRegistration);
+  }
+  /**
+   * Returns the JSX-integration HMR strategy.
+   *
+   * @remarks
+   * The strategy handles `layout-update` broadcasts for page sources, layout
+   * sources, and any component file in the active render tree. It defers
+   * registered script entrypoints to the generic JS strategy and includes /
+   * explicit server views to `ServerRenderedTemplateHmrStrategy`.
+   */
+  getHmrStrategy() {
+    if (!this.hmrManager || !this.appConfig) {
+      return void 0;
+    }
+    const context = this.hmrManager.getDefaultContext();
+    const absolutePaths = this.appConfig.absolutePaths;
+    return new EcopagesJsxHmrStrategy({
+      getWatchedFiles: context.getWatchedFiles,
+      getSrcDir: context.getSrcDir,
+      getPagesDir: context.getPagesDir,
+      getLayoutsDir: context.getLayoutsDir,
+      getIncludesDir: () => absolutePaths.includesDir,
+      getTemplateExtensions: () => this.extensions
+    });
+  }
   /**
    * Registers MDX tooling and completes the base integration setup.
    */

package/src/page-owned-content-script-grouping.d.ts

@@ -0,0 +1,12 @@
+import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+/** Returns the stable grouped-build id for one integration's page-owned content scripts. */
+export declare function createPageOwnedContentScriptBundleId(integrationName: string): string;
+/**
+ * Tags page-owned content scripts in one dependency batch with a shared grouped-build id.
+ *
+ * @remarks
+ * Lazy hydration entries (`excludeFromHtml`), component file scripts, and integration runtime
+ * assets stay ungrouped. Integrations that already assign a grouped id (for example React
+ * Router pages) are left unchanged.
+ */
+export declare function assignPageOwnedContentScriptGroupedBundles(dependencies: AssetDefinition[]): AssetDefinition[];

package/src/page-owned-content-script-grouping.js

@@ -0,0 +1,57 @@
+import { rapidhash } from "@ecopages/core/utils/hash";
+import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
+const PAGE_OWNED_CONTENT_SCRIPT_BUNDLE_PREFIX = "ecopages";
+function createPageOwnedContentScriptBundleId(integrationName) {
+  return `${PAGE_OWNED_CONTENT_SCRIPT_BUNDLE_PREFIX}-${integrationName}-page-content-scripts`;
+}
+function isPageOwnedGroupableContentScript(dep) {
+  if (dep.kind !== "script" || dep.source !== "content" || dep.inline) {
+    return false;
+  }
+  if (dep.excludeFromHtml) {
+    return false;
+  }
+  if (dep.groupedBundle?.id) {
+    return false;
+  }
+  if (dep.packageRole === "keep-separate" || dep.packageRole === "runtime" || dep.packageRole === "dynamic-chunk") {
+    return false;
+  }
+  return true;
+}
+function createPageOwnedGroupedEntryName(dep, usedEntryNames) {
+  const baseName = dep.name ?? `script-${rapidhash(dep.content).toString(16)}`;
+  if (!usedEntryNames.has(baseName)) {
+    usedEntryNames.add(baseName);
+    return baseName;
+  }
+  let suffix = 2;
+  let candidate = `${baseName}-${suffix}`;
+  while (usedEntryNames.has(candidate)) {
+    suffix += 1;
+    candidate = `${baseName}-${suffix}`;
+  }
+  usedEntryNames.add(candidate);
+  return candidate;
+}
+function assignPageOwnedContentScriptGroupedBundles(dependencies) {
+  const bundleId = createPageOwnedContentScriptBundleId(ECOPAGES_JSX_PLUGIN_NAME);
+  const usedEntryNames = /* @__PURE__ */ new Set();
+  for (const dependency of dependencies) {
+    if (!isPageOwnedGroupableContentScript(dependency)) {
+      continue;
+    }
+    dependency.groupedBundle = {
+      id: bundleId,
+      entryName: createPageOwnedGroupedEntryName(dependency, usedEntryNames)
+    };
+    if (dependency.bundle === false) {
+      dependency.bundle = true;
+    }
+  }
+  return dependencies;
+}
+export {
+  assignPageOwnedContentScriptGroupedBundles,
+  createPageOwnedContentScriptBundleId
+};

package/src/radiant-registered-script-ssr-invalidation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reads the custom-element tag name from a registered script module source file.
+ */
+export declare function resolveRadiantCustomElementTag(scriptPath: string): string | undefined;
+/**
+ * Removes one custom-element definition from the active runtime registry.
+ *
+ * @remarks
+ * Radiant's `@customElement` decorator and the SSR light-DOM shim both skip
+ * re-registration when a tag is already defined. During dev, server requests
+ * reuse the same process-global registry, so script edits would otherwise keep
+ * serving stale SSR markup until a full dev-server restart.
+ */
+export declare function clearRadiantCustomElementDefinition(tagName: string): void;
+/**
+ * Clears the SSR custom-element registry entry for one registered Radiant script module.
+ */
+export declare function invalidateRadiantRegisteredScriptSsrRegistration(scriptPath: string): void;

package/src/radiant-registered-script-ssr-invalidation.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from "node:fs";
+const CUSTOM_ELEMENT_TAG_PATTERN = /@customElement\s*\(\s*['"`]([^'"`]+)['"`]/u;
+function resolveRadiantCustomElementTag(scriptPath) {
+  if (!existsSync(scriptPath)) {
+    return void 0;
+  }
+  const content = readFileSync(scriptPath, "utf8");
+  const match = content.match(CUSTOM_ELEMENT_TAG_PATTERN);
+  return match?.[1];
+}
+function clearRadiantCustomElementDefinition(tagName) {
+  const registry = globalThis.customElements;
+  if (!registry) {
+    return;
+  }
+  if (typeof registry.delete === "function") {
+    registry.delete(tagName);
+    return;
+  }
+  const definitions = registry.definitions;
+  if (definitions instanceof Map && definitions.has(tagName)) {
+    definitions.delete(tagName);
+  }
+}
+function invalidateRadiantRegisteredScriptSsrRegistration(scriptPath) {
+  const tagName = resolveRadiantCustomElementTag(scriptPath);
+  if (!tagName) {
+    return;
+  }
+  clearRadiantCustomElementDefinition(tagName);
+}
+export {
+  clearRadiantCustomElementDefinition,
+  invalidateRadiantRegisteredScriptSsrRegistration,
+  resolveRadiantCustomElementTag
+};

package/src/resolve-radiant-install-hydrator.d.ts

@@ -0,0 +1,2 @@
+/** Absolute path to `@ecopages/radiant/client/install-hydrator` from this integration package. */
+export declare const RADIANT_INSTALL_HYDRATOR_FILEPATH: string;

package/src/resolve-radiant-install-hydrator.js

@@ -0,0 +1,7 @@
+import { fileURLToPath } from "node:url";
+const RADIANT_INSTALL_HYDRATOR_FILEPATH = fileURLToPath(
+  import.meta.resolve("@ecopages/radiant/client/install-hydrator")
+);
+export {
+  RADIANT_INSTALL_HYDRATOR_FILEPATH
+};