@ecopages/ecopages-jsx 0.2.0-rc.1 → 0.2.0-rc.11

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.
@@ -100,7 +123,8 @@ 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)`.
+- 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.1",
+  "version": "0.2.0-rc.11",
   "description": "JSX integration plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -11,6 +11,9 @@
   "main": "./src/ecopages-jsx.plugin.js",
   "types": "./src/ecopages-jsx.plugin.d.ts",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "default": "./src/ecopages-jsx.plugin.js",
@@ -31,13 +34,13 @@
     "directory": "packages/integrations/ecopages-jsx"
   },
   "dependencies": {
-    "@ecopages/mdx": "0.2.0-rc.1",
+    "@ecopages/mdx": "0.2.0-rc.11",
     "@mdx-js/mdx": "^3.1.1",
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-rc.1",
-    "@ecopages/jsx": "^0.3.0-rc.2",
-    "@ecopages/radiant": "^0.3.0-rc.2"
+    "@ecopages/core": "0.2.0-rc.11",
+    "@ecopages/jsx": "^0.3.0-rc.9",
+    "@ecopages/radiant": "^0.3.0-rc.9"
   }
-}
+}

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

@@ -13,7 +13,11 @@ export type EcopagesJsxMdxPageModule = EcoPageFile<{
 }>;
 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>;
+export interface CreateEcopagesJsxMdxLoaderPluginOptions {
+    compilerOptions: ResolvedMdxCompileOptions;
+    extensions: string[];
+    projectRoot: string;
+}
+export declare const createMdxLoaderPlugin: (options: CreateEcopagesJsxMdxLoaderPluginOptions) => EcoBuildPlugin;
 export declare const isMdxFile: (filePath: string, extensions: string[]) => boolean;
 export declare const normalizeMdxPageModule: (file: string, module: EcopagesJsxMdxPageModule) => EcopagesJsxMdxPageModule;

package/src/ecopages-jsx-mdx.js

@@ -1,8 +1,5 @@
-import { readFile } from 'node:fs/promises';
 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';
 export { appendMdxExtensions, createMdxExtensionFilter };
 export const resolveMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptionsCore(mdxOptions, {
@@ -12,30 +9,15 @@ export const resolveMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptio
         outputFormat: 'program',
     },
 });
-export const createMdxLoaderPlugin = (compilerOptions, extensions) => createMdxLoaderPluginCore({
+export const createMdxLoaderPlugin = (options) => createMdxLoaderPluginCore({
     name: 'ecopages-jsx-mdx-loader',
-    compilerOptions,
-    extensions,
+    integrationName: ECOPAGES_JSX_PLUGIN_NAME,
+    compilerOptions: options.compilerOptions,
+    extensions: options.extensions,
     includeSourceMap: false,
     loader: 'js',
+    projectRoot: options.projectRoot,
 });
-export const registerBunMdxPlugin = async (compilerOptions, extensions) => {
-    if (typeof Bun === 'undefined') {
-        return;
-    }
-    const filter = createMdxExtensionFilter(extensions);
-    Bun.plugin({
-        name: 'ecopages-jsx-mdx',
-        setup(build) {
-            build.onLoad({ filter }, async (args) => {
-                const { compile } = await import('@mdx-js/mdx');
-                const source = await readFile(args.path, 'utf-8');
-                const compiled = await compile(new VFile({ value: source, path: args.path }), compilerOptions);
-                return { contents: String(compiled.value), loader: 'js' };
-            });
-        },
-    });
-};
 export const isMdxFile = (filePath, extensions) => {
     return extensions.some((ext) => filePath.endsWith(ext));
 };
@@ -44,27 +26,22 @@ export const normalizeMdxPageModule = (file, module) => {
         throw new TypeError('MDX file must export a callable default component.');
     }
     const Page = module.default;
-    const normalizedConfig = {
-        ...(module.config ?? Page.config ?? {}),
-        identity: module.config?.identity ??
-            Page.config?.identity ?? {
-            id: String(rapidhash(file)),
-            file,
-            integration: ECOPAGES_JSX_PLUGIN_NAME,
-        },
-    };
-    if (module.layout && !(normalizedConfig.layouts && normalizedConfig.layouts.length > 0)) {
-        normalizedConfig.layout = module.layout;
+    const attributedConfig = module.config ?? Page.config;
+    if (!attributedConfig?.identity) {
+        throw new Error(`[ecopages] MDX page "${file}" is missing component identity; the MDX loader must attribute it.`);
+    }
+    if (module.layout && !(attributedConfig.layouts && attributedConfig.layouts.length > 0)) {
+        attributedConfig.layout = module.layout;
     }
-    ensurePageConfigLayouts(normalizedConfig);
+    ensurePageConfigLayouts(attributedConfig);
     const wrappedPage = async (props) => await Page(props);
-    wrappedPage.config = normalizedConfig;
+    wrappedPage.config = attributedConfig;
     if (module.getMetadata ?? Page.metadata) {
         wrappedPage.metadata = module.getMetadata ?? Page.metadata;
     }
     return {
         ...module,
         default: wrappedPage,
-        config: normalizedConfig,
+        config: attributedConfig,
     };
 };

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-render-session.d.ts

@@ -1,8 +1,7 @@
 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;
 /**
- * Tracks JSX SSR asset-collection state for one active render flow.
+ * Tracks JSX SSR HMR-ownership state for one active render flow.
  *
  * @remarks
  * The renderer still mirrors this state into `@ecopages/jsx/server` so nested
@@ -12,24 +11,19 @@ export declare const ECOPAGES_JSX_SSR_RENDER_STATE_KEY: unique symbol;
  * JSX server helpers.
  */
 export declare class EcopagesJsxRenderSession {
-    private readonly dedupeProcessedAssets;
-    constructor(dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[]);
     /**
      * 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
+     * the same HMR-ownership set. 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.
      */
     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

@@ -26,7 +26,7 @@ async function runWithCommittedHmrOwnership(state, render) {
     }
 }
 /**
- * Tracks JSX SSR asset-collection state for one active render flow.
+ * Tracks JSX SSR HMR-ownership state for one active render flow.
  *
  * @remarks
  * The renderer still mirrors this state into `@ecopages/jsx/server` so nested
@@ -36,17 +36,13 @@ async function runWithCommittedHmrOwnership(state, render) {
  * 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
+     * the same HMR-ownership set. 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.
@@ -62,36 +58,13 @@ export class EcopagesJsxRenderSession {
             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);
-    }
     mergeHmrOwnership(components) {
         mergeEjsxHmrOwnership(ensurePendingHmrFileOwners(this.getState()), components);
     }
-    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.
      *

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.
      *
@@ -33,7 +34,7 @@ export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderab
     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.
+     * elements and queued foreign subtrees resolve here rather than as opaque markup.
      */
     private renderQueuedForeignSubtreeChildren;
     protected createForeignChildRuntime(options: {

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 { createSharedServerModuleImporter } from '@ecopages/core/route-renderer/orchestration/custom-element-scripts/custom-element-server-module-importer';
 /**
  * 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.
      *
@@ -72,25 +75,22 @@ export class EcopagesJsxRenderer extends IntegrationRenderer {
     }
     /**
      * Re-renders queued JSX children inside the owning renderer so nested custom
-     * elements and queued foreign subtrees contribute assets to the same frame.
+     * elements and queued foreign subtrees resolve here rather than as opaque markup.
      */
     async renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken) {
         if (children === undefined) {
             return { assets: [] };
         }
-        let assets = [];
         let html;
         if (typeof children === 'string') {
             html = children;
         }
         else {
-            const renderedChildren = await this.renderJsx(children);
-            html = renderedChildren.html;
-            assets = renderedChildren.assets;
+            html = await this.renderJsx(children);
         }
         html = await this.foreignSubtreeExecutionService.resolveQueuedTokens(html, queuedResolutionsByToken, resolveToken);
         return {
-            assets,
+            assets: [],
             html,
         };
     }
@@ -121,9 +121,27 @@ export class EcopagesJsxRenderer extends IntegrationRenderer {
             runtimeOrigin,
         });
         this.mdxExtensions = jsxConfig?.mdxExtensions ?? ['.mdx'];
-        this.renderSession = new EcopagesJsxRenderSession((assets) => this.htmlTransformer.dedupeProcessedAssets(assets));
-        this.radiantSsrPolicy =
-            jsxConfig?.radiantSsrPolicy ?? new EcopagesJsxRadiantSsrPolicy(jsxConfig?.radiantSsrEnabled ?? false);
+        this.renderSession = new EcopagesJsxRenderSession();
+        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,
+            collectForIntegration: ECOPAGES_JSX_PLUGIN_NAME,
+            enabled: radiantSsrEnabled,
+            logLabel: 'ecopages-jsx',
+            preferSourceImports,
+            resolveDependencyPath: (componentDir, sourcePath) => this.resolveDependencyPath(componentDir, sourcePath),
+            /**
+             * @remarks
+             * Bun imports the source file through `preferSourceImports`. Node must
+             * not: dev asset output is still the `.tsx` source, and a browser bundle
+             * is a second Radiant graph. The page server-module loader transpiles
+             * the script and externalizes packages, so `customElements.define` hits
+             * the same module instances the page already loaded.
+             */
+            importServerModule: preferSourceImports ? undefined : createSharedServerModuleImporter(this.appConfig),
+        });
     }
     /** Returns whether the requested page file should be treated as MDX. */
     isMdxFile(filePath) {
@@ -136,129 +154,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 () => {
+                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 html = 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,
+                        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([
+                        ...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) {
+                    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 = [];
-        const html = await this.withCustomElementRenderHook(() => renderToString(value));
-        const dedupedAssets = this.renderSession.recordCollectedAssets(collectedAssets);
-        return {
-            assets: dedupedAssets,
-            html,
-        };
+        return await this.withCustomElementRenderHook(() => renderToString(value));
     }
     async withCustomElementRenderHook(render) {
         return await this.radiantSsrPolicy.withRuntime(() => withServerCustomElementRenderHook(this.createIntrinsicCustomElementRenderHook(), render));

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

@@ -39,17 +39,14 @@ export declare class EcopagesJsxPlugin extends IntegrationPlugin<JsxRenderable>
      */
     getHmrStrategy(): HmrStrategy | undefined;
     /**
-     * Registers MDX tooling and completes the base integration setup.
+     * Ensures the MDX loader exists, then completes the base integration setup.
+     *
+     * @remarks
+     * Bun registers `integration.plugins` after `setup()` returns. Calling
+     * `Bun.plugin` here would install the same MDX loader twice.
      */
     setup(): Promise<void>;
     private ensureMdxLoaderPlugin;
-    /**
-     * Registers Bun's MDX loader at runtime setup time.
-     *
-     * Build-time contribution collection may run where Bun is absent, so
-     * this hook stays isolated from manifest preparation.
-     */
-    private registerMdxBunPlugin;
 }
 /**
  * Creates the JSX integration plugin with resolved defaults.

package/src/ecopages-jsx.plugin.js

@@ -2,7 +2,7 @@ import { IntegrationPlugin, } 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, registerBunMdxPlugin, resolveMdxCompilerOptions, } from './ecopages-jsx-mdx.js';
+import { appendMdxExtensions, createMdxLoaderPlugin, resolveMdxCompilerOptions, } from './ecopages-jsx-mdx.js';
 import { EcopagesJsxRenderer } from './ecopages-jsx-renderer.js';
 import { EcopagesJsxHmrStrategy } from './ecopages-jsx-hmr-strategy.js';
 import { EcopagesJsxDevTransformContributor } from './dev-transform/ecopages-jsx-dev-transform-contributor.js';
@@ -137,32 +137,28 @@ export class EcopagesJsxPlugin extends IntegrationPlugin {
         });
     }
     /**
-     * Registers MDX tooling and completes the base integration setup.
+     * Ensures the MDX loader exists, then completes the base integration setup.
+     *
+     * @remarks
+     * Bun registers `integration.plugins` after `setup()` returns. Calling
+     * `Bun.plugin` here would install the same MDX loader twice.
      */
     async setup() {
         this.ensureMdxLoaderPlugin();
-        if (typeof Bun !== 'undefined' && this.mdxEnabled && this.mdxCompilerOptions) {
-            await this.registerMdxBunPlugin();
-        }
         await super.setup();
     }
     ensureMdxLoaderPlugin() {
         if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
             return;
         }
-        this.mdxLoaderPlugin = createMdxLoaderPlugin(this.mdxCompilerOptions, this.mdxExtensions);
-    }
-    /**
-     * Registers Bun's MDX loader at runtime setup time.
-     *
-     * Build-time contribution collection may run where Bun is absent, so
-     * this hook stays isolated from manifest preparation.
-     */
-    async registerMdxBunPlugin() {
-        if (typeof Bun === 'undefined' || !this.mdxCompilerOptions) {
-            return;
+        if (!this.appConfig?.rootDir) {
+            throw new Error('[EcopagesJsxPlugin] Cannot create MDX loader: appConfig.rootDir is required.');
         }
-        await registerBunMdxPlugin(this.mdxCompilerOptions, this.mdxExtensions);
+        this.mdxLoaderPlugin = createMdxLoaderPlugin({
+            compilerOptions: this.mdxCompilerOptions,
+            extensions: this.mdxExtensions,
+            projectRoot: this.appConfig.rootDir,
+        });
     }
 }
 /**

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

@@ -1,4 +1,4 @@
-import { rapidhash } from '@ecopages/core/utils/hash';
+import { rapidhash } from '@ecopages/core/hash';
 import { ECOPAGES_JSX_PLUGIN_NAME } from './ecopages-jsx.constants.js';
 /** Shared grouped-build id prefix for page-owned content scripts. */
 const PAGE_OWNED_CONTENT_SCRIPT_BUNDLE_PREFIX = 'ecopages';

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;