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

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

@@ -1,105 +1,112 @@
-import { createMarkupNodeLike } from "@ecopages/jsx";
-import { createServerHydrationBindingState, withServerHydrationBindingState } from "@ecopages/jsx/server";
-class EcopagesJsxRadiantSsrPolicy {
-  runtimeModules;
-  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}.
+ */
+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 this.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 = this.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 (!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 lightDomShimModule2 = await import(radiantLightDomShimEntry);
-        ensureRadiantLightDomGlobals(lightDomShimModule2.installLightDomShim);
-        const radiantElementSsrRuntimeModule = await import(radiantElementSsrRuntimeModuleUrl);
-        const modules = {
-          installLightDomShim: lightDomShimModule2.installLightDomShim,
-          resolveRadiantElementRenderBridge: radiantElementSsrRuntimeModule.resolveRadiantElementRenderBridge,
-          withServerRadiantElementSsrRuntime: radiantElementSsrRuntimeModule.withServerRadiantElementSsrRuntime
-        };
-        this.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.installLightDomShim);
+                const radiantElementSsrRuntimeModule = (await import(radiantElementSsrRuntimeModuleUrl));
+                const modules = {
+                    installLightDomShim: lightDomShimModule.installLightDomShim,
+                    resolveRadiantElementRenderBridge: radiantElementSsrRuntimeModule.resolveRadiantElementRenderBridge,
+                    withServerRadiantElementSsrRuntime: radiantElementSsrRuntimeModule.withServerRadiantElementSsrRuntime,
+                };
+                this.runtimeModules = modules;
+                return modules;
+            })();
+        }
+        await this.runtimeModulesPromise;
+        const lightDomShimModule = this.runtimeModules;
+        if (lightDomShimModule) {
+            ensureRadiantLightDomGlobals(lightDomShimModule.installLightDomShim);
+        }
     }
-    await this.runtimeModulesPromise;
-    const lightDomShimModule = this.runtimeModules;
-    if (lightDomShimModule) {
-      ensureRadiantLightDomGlobals(lightDomShimModule.installLightDomShim);
-    }
-  }
 }
+/**
+ * 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 install.
+ */
 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
-  });
+    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.js

@@ -1,78 +1,82 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { getActiveSsrScopeValue, withActiveSsrScopeValue } 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';
+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);
+/**
+ * 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;
     }
-    const jsxScopeState = getActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY);
-    if (jsxScopeState) {
-      return renderStateStorage.run(jsxScopeState, () => render());
+    /**
+     * 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);
+        }
+        const jsxScopeState = getActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY);
+        if (jsxScopeState) {
+            return renderStateStorage.run(jsxScopeState, () => render());
+        }
+        const state = {
+            collectedAssetFrames: [],
+        };
+        return renderStateStorage.run(state, () => withActiveSsrScopeValue(ECOPAGES_JSX_SSR_RENDER_STATE_KEY, state, render));
     }
-    const state = {
-      collectedAssetFrames: []
-    };
-    return 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);
+    beginCollectedAssetFrame() {
+        const state = this.getState();
+        const frame = [];
+        state.collectedAssetFrames.push(frame);
+        return frame;
     }
-    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);
+    endCollectedAssetFrame(frame) {
+        const activeFrame = this.getState().collectedAssetFrames.pop();
+        if (!activeFrame || activeFrame !== frame) {
+            return this.dedupeProcessedAssets(frame);
+        }
+        return this.dedupeProcessedAssets(activeFrame);
     }
-    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.");
+    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;
+    }
+    /**
+     * 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
-};