@ecopages/ecopages-jsx 0.2.1-beta.0 → 0.3.0

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

@@ -4,13 +4,15 @@ 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}; the
+ * Radiant installer also repairs incomplete DOM globals left by another runtime.
  */
 export declare class EcopagesJsxRadiantSsrPolicy {
-    private static runtimeModules;
-    private static runtimeModulesPromise;
+    private runtimeModules;
+    private runtimeModulesPromise;
     private readonly enabled;
     constructor(enabled: boolean);
     /**
@@ -27,7 +29,11 @@ export declare class EcopagesJsxRadiantSsrPolicy {
      * @remarks
      * The returned node-like wrapper lets the JSX server renderer preserve the
      * generated host HTML without escaping it back into plain text.
+     *
+     * The render hook owns the host's JSX children, so `applyChildren` runs inside the host's context providers.
+     * A consumer passed as a child of a provider host then resolves that provider in the server HTML instead of
+     * rendering its fallback state.
      */
-    renderIntrinsicElementMarkup(instance: unknown): ReturnType<typeof createMarkupNodeLike> | undefined;
+    renderIntrinsicElementMarkup(instance: unknown, applyChildren?: () => void): ReturnType<typeof createMarkupNodeLike> | undefined;
     private ensureRuntimeInstalled;
 }

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

@@ -1,79 +1,122 @@
-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.
+     *
+     * The render hook owns the host's JSX children, so `applyChildren` runs inside the host's context providers.
+     * A consumer passed as a child of a provider host then resolves that provider in the server HTML instead of
+     * rendering its fallback state.
+     */
+    renderIntrinsicElementMarkup(instance, applyChildren) {
+        const runtime = this.runtimeModules;
+        if (!runtime?.resolveRadiantElementRenderBridge(instance)) {
+            return undefined;
+        }
+        return createMarkupNodeLike(withServerHydrationBindingState(createServerHydrationBindingState(), () => {
+            const service = runtime.createRadiantElementSsrService(instance);
+            service.applyLightDom(() => applyChildren?.());
+            return service.renderHostToString({ mode: 'hydrate' }, service.getHostAttributes());
+        }));
     }
-    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 = import.meta
+                .resolve('@ecopages/radiant/server/radiant-element-ssr');
+            this.runtimeModulesPromise = (async () => {
+                const lightDomShimModule = await import(/* @vite-ignore */ radiantLightDomShimEntry);
+                ensureRadiantLightDomGlobals(lightDomShimModule.ensureLightDomShim);
+                const radiantElementSsrRuntimeModule = (await import(
+                /* @vite-ignore */ radiantElementSsrRuntimeModuleUrl));
+                const modules = {
+                    createRadiantElementSsrService: radiantElementSsrRuntimeModule.createRadiantElementSsrService,
+                    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-renderer.d.ts

@@ -1,47 +1,12 @@
-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 { createIntegrationRenderer, type IntegrationRendererHookFactory } from '@ecopages/core/integration';
 import { type JsxRenderable } from '@ecopages/jsx';
-import { type EcopagesJsxMdxPageModule } from './ecopages-jsx-mdx.js';
-import type { EcopagesJsxRendererOptions } from './ecopages-jsx.types.js';
-export type { EcopagesJsxRendererConfig, EcopagesJsxRendererOptions } from './ecopages-jsx.types.js';
-/**
- * Local Ecopages renderer for JSX templates in the docs app.
- *
- * This keeps the integration scoped to the docs package while supporting
- * async page, layout, and html template components on the server.
- */
-export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderable> {
+import type { EcopagesJsxRendererConfig } from './ecopages-jsx.types.js';
+export type { EcopagesJsxRendererConfig } from './ecopages-jsx.types.js';
+export type EcopagesJsxRenderer = InstanceType<ReturnType<typeof createEcopagesJsxRenderer>>;
+/** Creates the hook-based Ecopages JSX renderer for one plugin configuration. */
+export declare function createEcopagesJsxRenderer(jsxConfig?: EcopagesJsxRendererConfig): ReturnType<typeof createIntegrationRenderer<JsxRenderable>>;
+/** Creates JSX renderer hooks that can also configure a custom renderer subclass. */
+export declare function createEcopagesJsxRendererHookFactory(jsxConfig?: EcopagesJsxRendererConfig): IntegrationRendererHookFactory;
+export declare const EcopagesJsxRenderer: new (options: import("@ecopages/core/integration").IntegrationRendererOptions) => import("@ecopages/core/integration").IntegrationRenderer<JsxRenderable> & {
     name: string;
-    private readonly mdxExtensions;
-    private readonly renderSession;
-    private readonly radiantSsrPolicy;
-    private normalizeForeignChildProps;
-    /**
-     * 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>>;
-    }): ForeignChildRuntime;
-    constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, jsxConfig, runtimeOrigin, }: EcopagesJsxRendererOptions);
-    /** Returns whether the requested page file should be treated as MDX. */
-    isMdxFile(filePath: string): boolean;
-    protected importPageFile(file: string, options?: RouteModuleLoadOptions): Promise<EcopagesJsxMdxPageModule>;
-    render(options: IntegrationRendererRenderOptions<JsxRenderable>): Promise<RouteRendererBody>;
-    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    renderToResponse<P = any>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
-    private renderJsx;
-    private withCustomElementRenderHook;
-    private withPreparedRadiantRuntime;
-    private createIntrinsicCustomElementRenderHook;
-}
+};