@ecopages/ecopages-jsx 0.2.0-beta.8 → 0.2.0-rc.0

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

@@ -1,79 +1,113 @@
-import { createMarkupNodeLike } from "@ecopages/jsx";
-import { createServerHydrationBindingState, withServerHydrationBindingState } from "@ecopages/jsx/server";
-class EcopagesJsxRadiantSsrPolicy {
-  static runtimeModules;
-  static runtimeModulesPromise;
-  enabled;
-  constructor(enabled) {
-    this.enabled = enabled;
-  }
-  /**
-   * Ensures the Radiant SSR runtime is installed before a render needs it.
-   */
-  async prepareRuntime() {
-    if (!this.enabled) {
-      return;
+import { createMarkupNodeLike } from '@ecopages/jsx';
+import { createServerHydrationBindingState, withServerHydrationBindingState } from '@ecopages/jsx/server';
+/**
+ * Owns optional Radiant SSR runtime installation for the JSX integration.
+ *
+ * @remarks
+ * Radiant's server bridge and light-DOM shim are loaded lazily because most JSX
+ * 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}; the
+ * Radiant installer also repairs incomplete DOM globals left by another runtime.
+ */
+export class EcopagesJsxRadiantSsrPolicy {
+    runtimeModules;
+    runtimeModulesPromise;
+    enabled;
+    constructor(enabled) {
+        this.enabled = enabled;
     }
-    await this.ensureRuntimeInstalled();
-  }
-  /**
-   * Runs one render inside Radiant's server runtime when the policy is enabled.
-   */
-  async withRuntime(render) {
-    if (!this.enabled) {
-      return render();
+    /**
+     * Ensures the Radiant SSR runtime is installed before a render needs it.
+     */
+    async prepareRuntime() {
+        if (!this.enabled) {
+            return;
+        }
+        await this.ensureRuntimeInstalled();
     }
-    const runtimeModules = await EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise;
-    if (!runtimeModules) {
-      return render();
+    /**
+     * Runs one render inside Radiant's server runtime when the policy is enabled.
+     */
+    async withRuntime(render) {
+        if (!this.enabled) {
+            return render();
+        }
+        const runtimeModules = await this.runtimeModulesPromise;
+        if (!runtimeModules) {
+            return render();
+        }
+        return runtimeModules.withServerRadiantElementSsrRuntime(render);
     }
-    return runtimeModules.withServerRadiantElementSsrRuntime(render);
-  }
-  /**
-   * Converts one Radiant custom-element instance into trusted SSR markup.
-   *
-   * @remarks
-   * The returned node-like wrapper lets the JSX server renderer preserve the
-   * generated host HTML without escaping it back into plain text.
-   */
-  renderIntrinsicElementMarkup(instance) {
-    const renderBridge = EcopagesJsxRadiantSsrPolicy.runtimeModules?.resolveRadiantElementRenderBridge(instance);
-    if (!renderBridge) {
-      return void 0;
+    /**
+     * Converts one Radiant custom-element instance into trusted SSR markup.
+     *
+     * @remarks
+     * The returned node-like wrapper lets the JSX server renderer preserve the
+     * generated host HTML without escaping it back into plain text.
+     */
+    renderIntrinsicElementMarkup(instance) {
+        const renderBridge = this.runtimeModules?.resolveRadiantElementRenderBridge(instance);
+        if (!renderBridge) {
+            return undefined;
+        }
+        return createMarkupNodeLike(withServerHydrationBindingState(createServerHydrationBindingState(), () => renderBridge.renderHostToString({
+            mode: 'hydrate',
+        })));
     }
-    return createMarkupNodeLike(
-      withServerHydrationBindingState(
-        createServerHydrationBindingState(),
-        () => renderBridge.renderHostToString({
-          mode: "hydrate"
-        })
-      )
-    );
-  }
-  async ensureRuntimeInstalled() {
-    if (!EcopagesJsxRadiantSsrPolicy.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]) => {
-        const modules = {
-          installLightDomShim: lightDomShimModule2.installLightDomShim,
-          resolveRadiantElementRenderBridge: radiantElementSsrRuntimeModule.resolveRadiantElementRenderBridge,
-          withServerRadiantElementSsrRuntime: radiantElementSsrRuntimeModule.withServerRadiantElementSsrRuntime
-        };
-        EcopagesJsxRadiantSsrPolicy.runtimeModules = modules;
-        return modules;
-      });
+    async ensureRuntimeInstalled() {
+        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;
+            this.runtimeModulesPromise = (async () => {
+                const lightDomShimModule = await import(radiantLightDomShimEntry);
+                ensureRadiantLightDomGlobals(lightDomShimModule.ensureLightDomShim);
+                const radiantElementSsrRuntimeModule = (await import(radiantElementSsrRuntimeModuleUrl));
+                const modules = {
+                    ensureLightDomShim: lightDomShimModule.ensureLightDomShim,
+                    resolveRadiantElementRenderBridge: radiantElementSsrRuntimeModule.resolveRadiantElementRenderBridge,
+                    withServerRadiantElementSsrRuntime: radiantElementSsrRuntimeModule.withServerRadiantElementSsrRuntime,
+                };
+                this.runtimeModules = modules;
+                return modules;
+            })();
+        }
+        await this.runtimeModulesPromise;
+        const lightDomShimModule = this.runtimeModules;
+        if (lightDomShimModule) {
+            ensureRadiantLightDomGlobals(lightDomShimModule.ensureLightDomShim);
+        }
     }
-    const lightDomShimModule = await EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise;
-    lightDomShimModule.installLightDomShim();
-  }
 }
-export {
-  EcopagesJsxRadiantSsrPolicy
-};
+/**
+ * Installs Radiant light-DOM constructors on `globalThis` once.
+ *
+ * @remarks
+ * Custom-element constructors must be process-global; undoing them between tests
+ * is unsafe. Callers that clear globals for isolation must rely on a fresh policy
+ * instance so {@link EcopagesJsxRadiantSsrPolicy.prepareRuntime} re-runs the
+ * completeness check.
+ */
+function ensureRadiantLightDomGlobals(ensureLightDomShim) {
+    const window = ensureLightDomShim();
+    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,
+        requestAnimationFrame: window.requestAnimationFrame,
+        cancelAnimationFrame: window.cancelAnimationFrame,
+        window,
+    });
+}

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

@@ -1,3 +1,4 @@
+import type { EcoComponent } from '@ecopages/core';
 import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
 export declare const ECOPAGES_JSX_SSR_RENDER_STATE_KEY: unique symbol;
 /**
@@ -21,18 +22,13 @@ export declare class EcopagesJsxRenderSession {
      * mirrored back into the JSX SSR scope so nested `renderToString()` calls see
      * the same asset frame stack. When no session exists yet, a new state is
      * created and published through both the internal async-local store and the
-     * JSX SSR scope bridge.
+     * JSX SSR scope bridge. HMR ownership accumulated during the outer scope is
+     * published once when that scope completes.
      */
-    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;
+    withActiveScope<T>(render: () => T | Promise<T>): Promise<T>;
     beginCollectedAssetFrame(): ProcessedAsset[];
     endCollectedAssetFrame(frame: ProcessedAsset[]): ProcessedAsset[];
+    mergeHmrOwnership(components: ReadonlyArray<EcoComponent | undefined>): void;
     recordCollectedAssets(collectedAssets: ProcessedAsset[]): ProcessedAsset[];
     /**
      * Resolves the current render-session state from the local async scope first.

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

@@ -1,93 +1,111 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import {
-  createServerHydrationBindingState,
-  getActiveSsrScopeValue,
-  withActiveSsrScopeValue,
-  withServerHydrationBindingState
-} from "@ecopages/jsx/server";
-const ECOPAGES_JSX_SSR_RENDER_STATE_KEY = /* @__PURE__ */ Symbol.for("@ecopages/ecopages-jsx.ssr-render-state");
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getActiveSsrScopeValue, withActiveSsrScopeValue } from '@ecopages/jsx/server';
+import { mergeEjsxHmrOwnership, publishEjsxHmrOwnership } from './ecopages-jsx-hmr-ownership.js';
+export const ECOPAGES_JSX_SSR_RENDER_STATE_KEY = Symbol.for('@ecopages/ecopages-jsx.ssr-render-state');
 const renderStateStorage = new AsyncLocalStorage();
-class EcopagesJsxRenderSession {
-  dedupeProcessedAssets;
-  constructor(dedupeProcessedAssets) {
-    this.dedupeProcessedAssets = dedupeProcessedAssets;
-  }
-  /**
-   * Runs one render inside the active session scope.
-   *
-   * @remarks
-   * When a render is already active, the current session state is reused and
-   * mirrored back into the JSX SSR scope so nested `renderToString()` calls see
-   * the same asset frame stack. When no session exists yet, a new state is
-   * created and published through both the internal async-local store and the
-   * JSX SSR scope bridge.
-   */
-  withActiveScope(render) {
-    const activeState = renderStateStorage.getStore();
-    if (activeState) {
-      return withActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY, activeState, render);
+function ensurePendingHmrFileOwners(state) {
+    if (!state.pendingHmrFileOwners) {
+        state.pendingHmrFileOwners = new Set();
     }
-    const jsxScopeState = getActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY);
-    if (jsxScopeState) {
-      return renderStateStorage.run(jsxScopeState, () => render());
+    return state.pendingHmrFileOwners;
+}
+function commitPendingHmrOwnership(state) {
+    const pending = state.pendingHmrFileOwners;
+    if (!pending || pending.size === 0) {
+        return;
+    }
+    publishEjsxHmrOwnership(pending);
+    pending.clear();
+}
+async function runWithCommittedHmrOwnership(state, render) {
+    try {
+        return await render();
+    }
+    finally {
+        commitPendingHmrOwnership(state);
+    }
+}
+/**
+ * Tracks JSX SSR asset-collection state for one active render flow.
+ *
+ * @remarks
+ * The renderer still mirrors this state into `@ecopages/jsx/server` so nested
+ * JSX renders and existing SSR-scope probes can observe it, but it also keeps
+ * an internal async-local copy. That fallback avoids losing renderer state when
+ * host runtimes such as Vite end up loading separate module identities for the
+ * JSX server helpers.
+ */
+export class EcopagesJsxRenderSession {
+    dedupeProcessedAssets;
+    constructor(dedupeProcessedAssets) {
+        this.dedupeProcessedAssets = dedupeProcessedAssets;
+    }
+    /**
+     * Runs one render inside the active session scope.
+     *
+     * @remarks
+     * When a render is already active, the current session state is reused and
+     * mirrored back into the JSX SSR scope so nested `renderToString()` calls see
+     * the same asset frame stack. When no session exists yet, a new state is
+     * created and published through both the internal async-local store and the
+     * JSX SSR scope bridge. HMR ownership accumulated during the outer scope is
+     * published once when that scope completes.
+     */
+    async withActiveScope(render) {
+        const activeState = renderStateStorage.getStore();
+        if (activeState) {
+            return await withActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY, activeState, render);
+        }
+        const jsxScopeState = getActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY);
+        if (jsxScopeState) {
+            ensurePendingHmrFileOwners(jsxScopeState);
+            return await runWithCommittedHmrOwnership(jsxScopeState, () => renderStateStorage.run(jsxScopeState, () => render()));
+        }
+        const state = {
+            collectedAssetFrames: [],
+            pendingHmrFileOwners: new Set(),
+        };
+        return await runWithCommittedHmrOwnership(state, () => renderStateStorage.run(state, () => withActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY, state, render)));
+    }
+    beginCollectedAssetFrame() {
+        const state = this.getState();
+        const frame = [];
+        state.collectedAssetFrames.push(frame);
+        return frame;
+    }
+    endCollectedAssetFrame(frame) {
+        const activeFrame = this.getState().collectedAssetFrames.pop();
+        if (!activeFrame || activeFrame !== frame) {
+            return this.dedupeProcessedAssets(frame);
+        }
+        return this.dedupeProcessedAssets(activeFrame);
     }
-    const state = {
-      collectedAssetFrames: [],
-      hydrationBindingState: createServerHydrationBindingState()
-    };
-    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 = [];
-    state.collectedAssetFrames.push(frame);
-    return frame;
-  }
-  endCollectedAssetFrame(frame) {
-    const activeFrame = this.getState().collectedAssetFrames.pop();
-    if (!activeFrame || activeFrame !== frame) {
-      return this.dedupeProcessedAssets(frame);
+    mergeHmrOwnership(components) {
+        mergeEjsxHmrOwnership(ensurePendingHmrFileOwners(this.getState()), components);
     }
-    return this.dedupeProcessedAssets(activeFrame);
-  }
-  recordCollectedAssets(collectedAssets) {
-    const dedupedAssets = this.dedupeProcessedAssets(collectedAssets);
-    const state = this.getState();
-    const activeFrame = state.collectedAssetFrames[state.collectedAssetFrames.length - 1];
-    if (activeFrame) {
-      activeFrame.push(...dedupedAssets);
+    recordCollectedAssets(collectedAssets) {
+        const dedupedAssets = this.dedupeProcessedAssets(collectedAssets);
+        const state = this.getState();
+        const activeFrame = state.collectedAssetFrames[state.collectedAssetFrames.length - 1];
+        if (activeFrame) {
+            activeFrame.push(...dedupedAssets);
+        }
+        return dedupedAssets;
     }
-    return dedupedAssets;
-  }
-  /**
-   * Resolves the current render-session state from the local async scope first.
-   *
-   * @remarks
-   * The fallback read from `@ecopages/jsx/server` keeps compatibility with code
-   * that still inspects the public SSR scope directly, while the async-local
-   * store remains the authoritative source for renderer-owned bookkeeping.
-   */
-  getState() {
-    const state = renderStateStorage.getStore() ?? getActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY);
-    if (!state) {
-      throw new Error("Ecopages JSX SSR render state is unavailable outside the active render scope.");
+    /**
+     * Resolves the current render-session state from the local async scope first.
+     *
+     * @remarks
+     * The fallback read from `@ecopages/jsx/server` keeps compatibility with code
+     * that still inspects the public SSR scope directly, while the async-local
+     * store remains the authoritative source for renderer-owned bookkeeping.
+     */
+    getState() {
+        const state = renderStateStorage.getStore() ??
+            getActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY);
+        if (!state) {
+            throw new Error('Ecopages JSX SSR render state is unavailable outside the active render scope.');
+        }
+        return state;
     }
-    return state;
-  }
 }
-export {
-  ECOPAGES_JSX_SSR_RENDER_STATE_KEY,
-  EcopagesJsxRenderSession
-};

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;
 }