@ecopages/ecopages-jsx 0.2.0-rc.6 → 0.2.0-rc.8

package/README.md

@@ -53,6 +53,12 @@ Radiant support is enabled by default. When `radiant: true`, the plugin keeps th
 
 That means server-rendered `RadiantElement` hosts hydrate in place only when both the SSR markers and the explicit client hydrator are present. Without the client hydrator, Radiant intentionally falls back to a fresh client render on first connect.
 
+### Hydration Semantics: RadiantElement vs. RadiantController
+
+- **`RadiantElement` (DOM Preservation)**: Custom elements extending `RadiantElement` support true in-place hydration. When `@ecopages/radiant/client/install-hydrator` executes before elements connect, existing light-DOM SSR nodes are preserved, retaining DOM node identity, form input state, active focus, and media playback.
+- **`RadiantController` (Activation / Template Re-mount)**: Controllers attached via `[data-controller]` activate when `startControllers(document)` is called. Activation executes the controller's `render()` method and mounts its template fresh into the host container, replacing server-rendered child nodes. Reactive properties and signal bindings remain fully interactive, but individual child DOM nodes are reconstructed.
+- **Guidance**: Use `RadiantElement` when in-place preservation of SSR nodes (e.g., focused inputs, media elements, or CSS transitions) is required. Use `RadiantController` for Stimulus-style progressive enhancement on arbitrary markup where child DOM reconstruction is acceptable.
+
 ```ts
 ecopagesJsxPlugin({
 	radiant: true,
@@ -72,6 +78,23 @@ new MyElement().renderHostToString({ mode: 'hydrate' });
 
 The legacy `hydrate: true` option remains compatible, but `mode` is the current SSR contract. Registered intrinsic tags that contain a dash are SSR candidates, and framework-specific host rendering should be adapted through the server custom-element render hook instead of hardcoding framework branches into JSX page code.
 
+The integration loads Radiant host serialization through the public `@ecopages/radiant/server/radiant-element-ssr` export after installing the light-DOM shim. Applications do not need a separate Radiant SSR side-effect import.
+
+### Registered Radiant scripts (`ssr: true`)
+
+Declare custom-element registration once in `dependencies.scripts`. Ecopages JSX preloads entries marked `ssr: true` on the server before render so hosts can SSR without a redundant `import './my-element.script.ts'` in the component file.
+
+```ts
+export const ThemeToggle = eco.component({
+	dependencies: {
+		scripts: [{ src: './theme-toggle.script.ts', ssr: true, lazy: { 'on:idle': true } }],
+	},
+	render: () => <theme-toggle />,
+});
+```
+
+Keep `import type` when you only need props from the script module. Do not add `ssr: true` to browser-only scripts that touch `window` or `document` without guards.
+
 ## MDX Support
 
 Enable MDX to treat `.mdx` files as JSX routes compiled against the `@ecopages/jsx` runtime.
@@ -103,4 +126,5 @@ Important:
 - Cross-integration shell stacks should use `EcoEmbed` from `@ecopages/ecopages-jsx/eco-embed` (or the matching integration adapter). Plain opaque objects fail fast at core foreign-subtree queue boundaries; they are not coerced with `String(object)`. Pass already-serialized HTML when `EcoEmbed` is not needed.
 - 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.
+- Route-level dependency resolvers can supply Components at request time; Ecopages JSX includes those resolved roots when deciding whether a Foreign Subtree needs handoff.
 - 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-rc.6",
+  "version": "0.2.0-rc.8",
   "description": "JSX integration plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -34,13 +34,13 @@
     "directory": "packages/integrations/ecopages-jsx"
   },
   "dependencies": {
-    "@ecopages/mdx": "0.2.0-rc.6",
+    "@ecopages/mdx": "0.2.0-rc.8",
     "@mdx-js/mdx": "^3.1.1",
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-rc.6",
-    "@ecopages/jsx": "^0.3.0-rc.2",
-    "@ecopages/radiant": "^0.3.0-rc.2"
+    "@ecopages/core": "0.2.0-rc.8",
+    "@ecopages/jsx": "^0.3.0-rc.9",
+    "@ecopages/radiant": "^0.3.0-rc.9"
   }
 }

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

@@ -59,7 +59,8 @@ export class EcopagesJsxRadiantSsrPolicy {
     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;
+            const radiantElementSsrRuntimeModuleUrl = import.meta
+                .resolve('@ecopages/radiant/server/radiant-element-ssr');
             this.runtimeModulesPromise = (async () => {
                 const lightDomShimModule = await import(radiantLightDomShimEntry);
                 ensureRadiantLightDomGlobals(lightDomShimModule.ensureLightDomShim);

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

@@ -16,6 +16,7 @@ export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderab
     private readonly mdxExtensions;
     private readonly renderSession;
     private readonly radiantSsrPolicy;
+    private readonly ssrScriptPreloader;
     /**
      * Serializes foreign-child props for string-first boundaries.
      *

package/src/ecopages-jsx-renderer.js

@@ -7,6 +7,8 @@ import { ECOPAGES_JSX_PLUGIN_NAME } from './ecopages-jsx.constants.js';
 import { isMdxFile, normalizeMdxPageModule, } from './ecopages-jsx-mdx.js';
 import { EcopagesJsxRenderSession } from './ecopages-jsx-render-session.js';
 import { EcopagesJsxRadiantSsrPolicy } from './ecopages-jsx-radiant-ssr-policy.js';
+import { CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES, CustomElementScriptPreloader, } from '@ecopages/core/route-renderer/orchestration/custom-element-scripts/custom-element-script-preloader';
+import { createCustomElementSsrPreloadEntrypointResolver } from '@ecopages/core/route-renderer/orchestration/custom-element-scripts/custom-element-ssr-preload-entrypoint';
 /**
  * Local Ecopages renderer for JSX templates in the docs app.
  *
@@ -18,6 +20,7 @@ export class EcopagesJsxRenderer extends IntegrationRenderer {
     mdxExtensions;
     renderSession;
     radiantSsrPolicy;
+    ssrScriptPreloader;
     /**
      * Serializes foreign-child props for string-first boundaries.
      *
@@ -122,8 +125,26 @@ export class EcopagesJsxRenderer extends IntegrationRenderer {
         });
         this.mdxExtensions = jsxConfig?.mdxExtensions ?? ['.mdx'];
         this.renderSession = new EcopagesJsxRenderSession((assets) => this.htmlTransformer.dedupeProcessedAssets(assets));
-        this.radiantSsrPolicy =
-            jsxConfig?.radiantSsrPolicy ?? new EcopagesJsxRadiantSsrPolicy(jsxConfig?.radiantSsrEnabled ?? false);
+        const radiantSsrEnabled = jsxConfig?.radiantSsrEnabled ?? false;
+        this.radiantSsrPolicy = jsxConfig?.radiantSsrPolicy ?? new EcopagesJsxRadiantSsrPolicy(radiantSsrEnabled);
+        const preferSourceImports = typeof Bun !== 'undefined';
+        this.ssrScriptPreloader = new CustomElementScriptPreloader({
+            cacheScope: CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES.ecopagesJsx,
+            /**
+             * @remarks
+             * Node production builds evaluate registration scripts through the
+             * asset pipeline during render. Preloading through the app module loader
+             * registers Radiant hosts in an isolated graph and breaks SSR.
+             */
+            enabled: radiantSsrEnabled && preferSourceImports,
+            logLabel: 'ecopages-jsx',
+            preferSourceImports,
+            resolveDependencyPath: (componentDir, sourcePath) => this.resolveDependencyPath(componentDir, sourcePath),
+            resolvePreloadEntrypoint: createCustomElementSsrPreloadEntrypointResolver({
+                preferSourceImports,
+                processDependencies: this.assetProcessingService?.processDependencies?.bind(this.assetProcessingService),
+            }),
+        });
     }
     /** Returns whether the requested page file should be treated as MDX. */
     isMdxFile(filePath) {
@@ -136,120 +157,140 @@ export class EcopagesJsxRenderer extends IntegrationRenderer {
         });
     }
     async render(options) {
-        return await this.withPreparedRadiantRuntime(async () => await this.renderSession.withActiveScope(async () => {
-            try {
-                const result = await this.renderPageWithDocumentShell({
-                    page: {
-                        component: options.Page,
-                        props: {
-                            ...options.pageProps,
-                            locals: options.pageLocals,
+        return await this.withPreparedRadiantRuntime(async () => {
+            await this.ssrScriptPreloader.preloadSsrScripts([
+                options.Page,
+                options.Layout,
+                options.HtmlTemplate,
+                ...(options.resolvedPageDependencyComponents ?? []),
+            ]);
+            return await this.renderSession.withActiveScope(async () => {
+                try {
+                    const result = await this.renderPageWithDocumentShell({
+                        page: {
+                            component: options.Page,
+                            props: {
+                                ...options.pageProps,
+                                locals: options.pageLocals,
+                            },
                         },
-                    },
-                    layouts: resolveDocumentShellLayouts({
-                        layout: options.Layout,
-                        layoutEntries: options.layoutEntries,
-                        params: options.params,
-                        query: options.query,
-                        locals: options.locals,
-                    }),
-                    htmlTemplate: options.HtmlTemplate,
-                    metadata: options.metadata,
-                    pageProps: options.pageProps ?? {},
-                });
-                this.recordHmrOwnership([
-                    options.Page,
-                    options.Layout,
-                    options.HtmlTemplate,
-                    ...(options.resolvedPageDependencyComponents ?? []),
-                ]);
-                return result;
-            }
-            catch (error) {
-                throw this.createRenderError('Error rendering page', error);
-            }
-        }));
+                        /**
+                         * @remarks Content components supplied by the Page dependency
+                         * resolver (for example the active MDX entry) carry foreign
+                         * ownership the static Page config cannot declare.
+                         */
+                        foreignChildRoots: options.resolvedPageDependencyComponents,
+                        layouts: resolveDocumentShellLayouts({
+                            layout: options.Layout,
+                            layoutEntries: options.layoutEntries,
+                            params: options.params,
+                            query: options.query,
+                            locals: options.locals,
+                        }),
+                        htmlTemplate: options.HtmlTemplate,
+                        metadata: options.metadata,
+                        pageProps: options.pageProps ?? {},
+                    });
+                    this.recordHmrOwnership([
+                        options.Page,
+                        options.Layout,
+                        options.HtmlTemplate,
+                        ...(options.resolvedPageDependencyComponents ?? []),
+                    ]);
+                    return result;
+                }
+                catch (error) {
+                    throw this.createRenderError('Error rendering page', error);
+                }
+            });
+        });
     }
     async renderComponent(input) {
-        return await this.withPreparedRadiantRuntime(async () => await this.renderSession.withActiveScope(async () => {
-            const assetFrame = this.renderSession.beginCollectedAssetFrame();
-            try {
-                if (typeof input.component !== 'function') {
-                    throw new TypeError('JSX renderer expected a callable component.');
-                }
-                const component = input.component;
-                const componentProps = input.children === undefined
-                    ? input.props
-                    : {
-                        ...input.props,
-                        children: typeof input.children === 'string'
-                            ? createMarkupNodeLike(input.children)
-                            : input.children,
-                    };
-                const content = await this.withCustomElementRenderHook(() => component(componentProps));
-                const rendered = await this.renderJsx(content);
-                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,
+        return await this.withPreparedRadiantRuntime(async () => {
+            await this.ssrScriptPreloader.preloadSsrScripts([input.component]);
+            return await this.renderSession.withActiveScope(async () => {
+                const assetFrame = this.renderSession.beginCollectedAssetFrame();
+                try {
+                    if (typeof input.component !== 'function') {
+                        throw new TypeError('JSX renderer expected a callable component.');
+                    }
+                    const component = input.component;
+                    const componentProps = input.children === undefined
+                        ? input.props
+                        : {
+                            ...input.props,
+                            children: typeof input.children === 'string'
+                                ? createMarkupNodeLike(input.children)
+                                : input.children,
+                        };
+                    const content = await this.withCustomElementRenderHook(() => component(componentProps));
+                    const rendered = await this.renderJsx(content);
+                    const queuedForeignSubtreeResolution = await this.foreignSubtreeExecutionService.resolveQueuedHtml({
                         currentIntegrationName: this.name,
-                        currentRenderer: this,
-                        integrationName,
-                        cache: rendererCache,
-                    }),
-                    applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
-                    dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
-                    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 this.finalizeIslandComponentRender(input, {
-                    html: queuedForeignSubtreeResolution.html,
-                    canAttachAttributes: true,
-                    rootTag: this.getRootTagName(queuedForeignSubtreeResolution.html),
-                    integrationName: this.name,
-                    assets,
-                });
-            }
-            catch (error) {
-                this.renderSession.endCollectedAssetFrame(assetFrame);
-                throw this.createRenderError('Error rendering component', error);
-            }
-        }));
+                        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: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+                        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 this.finalizeIslandComponentRender(input, {
+                        html: queuedForeignSubtreeResolution.html,
+                        canAttachAttributes: true,
+                        rootTag: this.getRootTagName(queuedForeignSubtreeResolution.html),
+                        integrationName: this.name,
+                        assets,
+                    });
+                }
+                catch (error) {
+                    this.renderSession.endCollectedAssetFrame(assetFrame);
+                    throw this.createRenderError('Error rendering component', error);
+                }
+            });
+        });
     }
     async renderToResponse(view, props, ctx) {
-        return await this.withPreparedRadiantRuntime(async () => await this.renderSession.withActiveScope(async () => {
-            try {
-                if (typeof view !== 'function') {
-                    throw new TypeError('JSX renderer expected a callable view component.');
+        return await this.withPreparedRadiantRuntime(async () => {
+            const viewComponent = view;
+            const layouts = viewComponent.config?.layouts;
+            await this.ssrScriptPreloader.preloadSsrScripts([view, ...(layouts ?? [])]);
+            return await this.renderSession.withActiveScope(async () => {
+                try {
+                    if (typeof view !== 'function') {
+                        throw new TypeError('JSX renderer expected a callable view component.');
+                    }
+                    const response = await this.renderViewWithDocumentShell({
+                        view: viewComponent,
+                        props: props,
+                        ctx,
+                        layout: layouts?.[layouts.length - 1],
+                    });
+                    this.recordHmrOwnership([view]);
+                    return response;
+                }
+                catch (error) {
+                    throw this.createRenderError('Error rendering view', error);
                 }
-                const viewComponent = view;
-                const layouts = viewComponent.config?.layouts;
-                const response = await this.renderViewWithDocumentShell({
-                    view: viewComponent,
-                    props: props,
-                    ctx,
-                    layout: layouts?.[layouts.length - 1],
-                });
-                this.recordHmrOwnership([view]);
-                return response;
-            }
-            catch (error) {
-                throw this.createRenderError('Error rendering view', error);
-            }
-        }));
+            });
+        });
     }
     async renderJsx(value) {
         const collectedAssets = [];

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

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES, invalidateCustomElementScriptPreload, } from '@ecopages/core/route-renderer/orchestration/custom-element-scripts/custom-element-script-preloader';
 const CUSTOM_ELEMENT_TAG_PATTERN = /@customElement\s*\(\s*['"`]([^'"`]+)['"`]/u;
 /**
  * Reads the custom-element tag name from a registered script module source file.
@@ -38,6 +39,7 @@ export function clearRadiantCustomElementDefinition(tagName) {
  * Clears the SSR custom-element registry entry for one registered Radiant script module.
  */
 export function invalidateRadiantRegisteredScriptSsrRegistration(scriptPath) {
+    invalidateCustomElementScriptPreload(scriptPath, CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES.ecopagesJsx);
     const tagName = resolveRadiantCustomElementTag(scriptPath);
     if (!tagName) {
         return false;