@ecopages/ecopages-jsx 0.2.1 → 0.3.1

package/README.md

@@ -1,35 +1,30 @@
 # @ecopages/ecopages-jsx
 
-Integration plugin for [@ecopages/jsx](https://jsr.io/@ecopages/jsx) templates in Ecopages. Use it when Ecopages JSX should own `.tsx` routes, Radiant-backed web components, or MDX compiled against the `@ecopages/jsx` runtime.
+Integration plugin for [@ecopages/jsx](https://www.npmjs.com/package/@ecopages/jsx) templates in Ecopages. Use it when Ecopages JSX should own `.tsx` routes, Radiant-backed web components, or MDX compiled against the `@ecopages/jsx` runtime.
 
 ## Installation
 
 ```bash
-bunx jsr add @ecopages/ecopages-jsx @ecopages/radiant
+bun add @ecopages/ecopages-jsx @ecopages/jsx @ecopages/radiant
 ```
 
-`@ecopages/radiant` is a required peer dependency for this package.
+`@ecopages/jsx` and `@ecopages/radiant` are required peer dependencies for this package.
 
 ## Usage
 
 Register the `ecopagesJsxPlugin` in your `eco.config.ts`.
 
 ```ts
-import { ConfigBuilder } from '@ecopages/core/config-builder';
+import { defineConfig } from '@ecopages/core/config';
 import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
 
-const config = await new ConfigBuilder()
-	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
-	.setIntegrations([ecopagesJsxPlugin()])
-	.build();
-
-export default config;
+export default defineConfig({ integrations: [ecopagesJsxPlugin()] });
 ```
 
 ## What This Integration Owns
 
 - `.tsx` route files by default. Use `extensions` to change the JSX route suffix list.
-- Optional Radiant runtime assets and import-map entries.
+- Optional Radiant SSR/runtime wiring through the public `@ecopages/radiant` entrypoints.
 - Optional `.mdx` routes compiled against the `@ecopages/jsx` runtime.
 
 ## Route Extensions
@@ -42,9 +37,26 @@ ecopagesJsxPlugin({
 });
 ```
 
+## Development HMR
+
+In development, editing a registered Ecopages JSX page refreshes the current page through the navigation runtime. The shared Layout stays mounted where the router can preserve it; elements marked with `data-eco-persist` retain their DOM state. Declared client scripts continue to use script HMR.
+
 ## Radiant Support
 
-Radiant runtime bundles are enabled by default so JSX pages can render and hydrate Radiant custom elements.
+Radiant support is enabled by default. When `radiant: true`, the plugin keeps the ownership split explicit:
+
+- Ecopages JSX owns page-level JSX SSR and container hydration.
+- Radiant SSR is activated on the server through `@ecopages/radiant/server/render-component`.
+- The server reuses Radiant's complete light-DOM surface, replacing partial globals before Radiant elements are imported.
+- Radiant host hydration is activated on the client through an explicit head bootstrap that imports `@ecopages/radiant/client/install-hydrator` before intrinsic custom-element modules load.
+
+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({
@@ -52,30 +64,64 @@ ecopagesJsxPlugin({
 });
 ```
 
-Set `radiant: false` when your JSX pages do not need the Radiant browser runtime on a given app.
+Set `radiant: false` when your JSX pages do not need Radiant SSR or the Radiant browser runtime on a given app.
+
+The plugin bootstrap is intentionally explicit rather than depending on custom-element modules to install the Radiant hydrator opportunistically.
+
+For server-side custom-element examples, prefer explicit SSR modes over the older boolean-only contract.
+
+```ts
+new MyElement().renderHostToString({ mode: 'plain' });
+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. Preload deduplication and invalidation state belongs to the app's `AppRuntime`, so separate apps keep separate preload history.
+
+```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.
+Add an `mdx` object to treat `.mdx` files as JSX routes compiled against the `@ecopages/jsx` runtime. Omit the property to disable MDX. Put `remarkPlugins`, `rehypePlugins`, and `recmaPlugins` next to `compilerOptions`, not inside it.
 
 ```ts
-import { ConfigBuilder } from '@ecopages/core/config-builder';
+import { defineConfig } from '@ecopages/core/config';
 import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
 
-const config = await new ConfigBuilder()
-	.setIntegrations([
+export default defineConfig({
+	integrations: [
 		ecopagesJsxPlugin({
 			mdx: {
-				enabled: true,
 				extensions: ['.mdx', '.md'],
 			},
 		}),
-	])
-	.build();
-
-export default config;
+	],
+});
 ```
 
 ## Mixed Rendering
 
-Ecopages JSX can own the outer page shell or just the nested boundary. When another integration reaches a JSX-owned boundary, Ecopages hands that boundary back to the JSX renderer so it can serialize the correct output before the outer renderer resumes.
+Ecopages JSX can own the outer page shell or just a nested foreign subtree. When another integration reaches a JSX-owned foreign child, Ecopages hands that foreign subtree back to the JSX renderer so it can serialize the correct output before the outer renderer resumes.
+
+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.
+- JSX renderers use the required core `AssetProcessingService` to process declared component dependencies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/ecopages-jsx",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "JSX integration plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -11,18 +11,37 @@
   "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",
+      "types": "./src/ecopages-jsx.plugin.d.ts"
+    },
+    "./eco-embed": {
+      "default": "./src/eco-embed.js",
+      "types": "./src/eco-embed.d.ts"
+    },
+    "./eco-embed.ts": {
+      "default": "./src/eco-embed.js",
+      "types": "./src/eco-embed.d.ts"
+    }
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ecopages/ecopages.git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/integrations/ecopages-jsx"
   },
   "dependencies": {
+    "@ecopages/file-system": "0.3.1",
+    "@ecopages/mdx": "0.3.1",
     "@mdx-js/mdx": "^3.1.1",
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.1",
-    "@ecopages/jsx": "^0.3.0-alpha.0",
-    "@ecopages/radiant": "^0.3.0-alpha.0"
+    "@ecopages/core": "0.3.1",
+    "@ecopages/jsx": "^0.4.0",
+    "@ecopages/radiant": "^0.4.0"
   }
-}
+}

package/src/dev-transform/ecopages-jsx-dev-transform-contributor.d.ts

@@ -0,0 +1,17 @@
+import type { EcoBuildPlugin } from '@ecopages/core/integration';
+import type { DevTransformBundleContributor } from '@ecopages/core/integration';
+import type { EcopagesJsxHmrStrategy } from '../ecopages-jsx-hmr-strategy.js';
+export type EcopagesJsxDevTransformContributorOptions = {
+    strategy: EcopagesJsxHmrStrategy;
+    getMdxLoaderPlugin: () => EcoBuildPlugin | undefined;
+};
+/**
+ * Supplies Ecopages JSX module plugins for the core dev transform bundler.
+ */
+export declare class EcopagesJsxDevTransformContributor implements DevTransformBundleContributor {
+    private readonly strategy;
+    private readonly getMdxLoaderPlugin;
+    constructor(options: EcopagesJsxDevTransformContributorOptions);
+    ownsModule(sourcePath: string): boolean;
+    getModulePlugins(sourcePath: string): Promise<readonly EcoBuildPlugin[]>;
+}

package/src/dev-transform/ecopages-jsx-dev-transform-contributor.js

@@ -0,0 +1,21 @@
+/**
+ * Supplies Ecopages JSX module plugins for the core dev transform bundler.
+ */
+export class EcopagesJsxDevTransformContributor {
+    strategy;
+    getMdxLoaderPlugin;
+    constructor(options) {
+        this.strategy = options.strategy;
+        this.getMdxLoaderPlugin = options.getMdxLoaderPlugin;
+    }
+    ownsModule(sourcePath) {
+        return this.strategy.ownsDevTransformEntrypoint(sourcePath);
+    }
+    async getModulePlugins(sourcePath) {
+        if (!sourcePath.endsWith('.mdx')) {
+            return [];
+        }
+        const mdxLoader = this.getMdxLoaderPlugin();
+        return mdxLoader ? [mdxLoader] : [];
+    }
+}

package/src/eco-embed.d.ts

@@ -0,0 +1,11 @@
+import type { EcoComponent, EcoEmbedProps as CoreEcoEmbedProps } from '@ecopages/core';
+import type { JsxRenderable } from '@ecopages/jsx';
+/**
+ * Props for the Ecopages JSX-owned `EcoEmbed` adapter.
+ */
+export type EcoEmbedProps<TComponent extends EcoComponent> = CoreEcoEmbedProps<TComponent>;
+/**
+ * Renders a foreign or same-integration eco component from an Ecopages JSX
+ * file without forcing inline mixed-JSX authoring.
+ */
+export declare function EcoEmbed<TComponent extends EcoComponent>({ component, props, children, }: EcoEmbedProps<TComponent>): JsxRenderable;

package/src/eco-embed.js

@@ -0,0 +1,9 @@
+/** @jsxImportSource @ecopages/jsx */
+import { eco } from '@ecopages/core';
+/**
+ * Renders a foreign or same-integration eco component from an Ecopages JSX
+ * file without forcing inline mixed-JSX authoring.
+ */
+export function EcoEmbed({ component, props, children, }) {
+    return eco.embed(component, props, children);
+}

package/src/ecopages-jsx-hmr-ownership.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tracks the source files that produced the most recent JSX render.
+ *
+ * @remarks
+ * The JSX renderer runs each page, component, or view render inside
+ * {@link withEjsxHmrOwnershipScope} and records its components with
+ * {@link recordEjsxHmrOwnership}. `EcopagesJsxHmrStrategy` reads the result to
+ * decide whether a changed file affects SSR HTML without walking the component
+ * tree on every watcher event.
+ *
+ * The state is module-scoped because the renderer and the HMR strategy share no
+ * other lifecycle anchor. Publishing replaces it only when the file set changes,
+ * so repeated renders of the same page keep the existing state.
+ *
+ * Only the latest top-level render is kept. With several pages open, a file
+ * used only by a page that rendered earlier is not matched until that page
+ * renders again.
+ */
+import type { EcoComponent } from '@ecopages/core';
+export type EjsxHmrOwnershipState = {
+    fileOwners: ReadonlySet<string>;
+    hash: string;
+};
+/**
+ * Returns the most recently recorded active render tree.
+ */
+export declare function getEjsxHmrOwnership(): EjsxHmrOwnershipState;
+/**
+ * Runs one render and publishes the files it recorded once the outermost scope ends.
+ *
+ * @remarks
+ * Nested renders, such as components and foreign subtrees resolved inside a
+ * page, join the outer scope, so the published set covers the whole render tree
+ * instead of the last nested render.
+ */
+export declare function withEjsxHmrOwnershipScope<T>(render: () => T | Promise<T>): Promise<T>;
+/**
+ * Adds the source files of `components`, their declared dependencies and their
+ * layouts to the active render scope.
+ *
+ * @throws Error when called outside {@link withEjsxHmrOwnershipScope}.
+ */
+export declare function recordEjsxHmrOwnership(components: ReadonlyArray<EcoComponent | undefined>): void;

package/src/ecopages-jsx-hmr-ownership.js

@@ -0,0 +1,91 @@
+/**
+ * Tracks the source files that produced the most recent JSX render.
+ *
+ * @remarks
+ * The JSX renderer runs each page, component, or view render inside
+ * {@link withEjsxHmrOwnershipScope} and records its components with
+ * {@link recordEjsxHmrOwnership}. `EcopagesJsxHmrStrategy` reads the result to
+ * decide whether a changed file affects SSR HTML without walking the component
+ * tree on every watcher event.
+ *
+ * The state is module-scoped because the renderer and the HMR strategy share no
+ * other lifecycle anchor. Publishing replaces it only when the file set changes,
+ * so repeated renders of the same page keep the existing state.
+ *
+ * Only the latest top-level render is kept. With several pages open, a file
+ * used only by a page that rendered earlier is not matched until that page
+ * renders again.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { contentHash } from '@ecopages/core/build';
+import { collectComponentConfigFilePaths } from '@ecopages/core/integration';
+const EMPTY_STATE = {
+    fileOwners: new Set(),
+    hash: '',
+};
+let currentState = EMPTY_STATE;
+const pendingFileOwners = new AsyncLocalStorage();
+/**
+ * Returns the most recently recorded active render tree.
+ */
+export function getEjsxHmrOwnership() {
+    return currentState;
+}
+/**
+ * Runs one render and publishes the files it recorded once the outermost scope ends.
+ *
+ * @remarks
+ * Nested renders, such as components and foreign subtrees resolved inside a
+ * page, join the outer scope, so the published set covers the whole render tree
+ * instead of the last nested render.
+ */
+export async function withEjsxHmrOwnershipScope(render) {
+    if (pendingFileOwners.getStore()) {
+        return await render();
+    }
+    const fileOwners = new Set();
+    try {
+        return await pendingFileOwners.run(fileOwners, render);
+    }
+    finally {
+        if (fileOwners.size > 0) {
+            publishEjsxHmrOwnership(fileOwners);
+        }
+    }
+}
+/**
+ * Adds the source files of `components`, their declared dependencies and their
+ * layouts to the active render scope.
+ *
+ * @throws Error when called outside {@link withEjsxHmrOwnershipScope}.
+ */
+export function recordEjsxHmrOwnership(components) {
+    const fileOwners = pendingFileOwners.getStore();
+    if (!fileOwners) {
+        throw new Error('Ecopages JSX HMR ownership can only be recorded inside an active render scope.');
+    }
+    for (const file of collectFileOwners(components)) {
+        fileOwners.add(file);
+    }
+}
+function publishEjsxHmrOwnership(files) {
+    const hash = hashFileSet(files);
+    if (hash === currentState.hash) {
+        return;
+    }
+    currentState = {
+        fileOwners: new Set(files),
+        hash,
+    };
+}
+function collectFileOwners(components) {
+    return collectComponentConfigFilePaths(components, { includeLayouts: true });
+}
+function hashFileSet(files) {
+    if (files.size === 0) {
+        return '';
+    }
+    const sorted = Array.from(files).sort();
+    const joined = sorted.join('\n');
+    return BigInt(`0x${contentHash(joined, 16)}`).toString(36);
+}

package/src/ecopages-jsx-hmr-strategy.d.ts

@@ -0,0 +1,19 @@
+import { HmrStrategy, type HmrAction } from '@ecopages/core/integration';
+import type { HmrRegisteredEntrypointsContext } from '@ecopages/core/integration';
+export type EcopagesJsxHmrStrategyContext = HmrRegisteredEntrypointsContext & {
+    getSrcDir(): string;
+    getPagesDir(): string;
+    getLayoutsDir(): string;
+    getIncludesDir(): string;
+    getTemplateExtensions(): ReadonlyArray<string>;
+};
+export declare class EcopagesJsxHmrStrategy extends HmrStrategy {
+    readonly type: 100;
+    private readonly context;
+    constructor(context: EcopagesJsxHmrStrategyContext);
+    matches(filePath: string): boolean;
+    ownsDevTransformEntrypoint(filePath: string): boolean;
+    process(filePath: string): Promise<HmrAction>;
+    private isPageOrLayoutSource;
+    private hasJsxTemplateExtension;
+}

package/src/ecopages-jsx-hmr-strategy.js

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import { HmrStrategy, HmrStrategyType } from '@ecopages/core/integration';
+import { isRegisteredDevTransformEntrypoint, isRegisteredScriptEntrypoint } from '@ecopages/core/integration';
+import { getEjsxHmrOwnership } from './ecopages-jsx-hmr-ownership.js';
+export class EcopagesJsxHmrStrategy extends HmrStrategy {
+    type = HmrStrategyType.INTEGRATION;
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    matches(filePath) {
+        const resolvedPath = path.resolve(filePath);
+        if (isRegisteredScriptEntrypoint(this.context.getRegisteredEntrypoints(), resolvedPath)) {
+            return false;
+        }
+        const srcDir = path.resolve(this.context.getSrcDir());
+        if (!resolvedPath.startsWith(`${srcDir}${path.sep}`) && resolvedPath !== srcDir) {
+            return false;
+        }
+        const includesDir = path.resolve(this.context.getIncludesDir());
+        if (includesDir && (resolvedPath === includesDir || resolvedPath.startsWith(`${includesDir}${path.sep}`))) {
+            return false;
+        }
+        if (this.isPageOrLayoutSource(resolvedPath)) {
+            return this.hasJsxTemplateExtension(resolvedPath);
+        }
+        const ownership = getEjsxHmrOwnership();
+        if (ownership.fileOwners.has(resolvedPath)) {
+            return true;
+        }
+        return false;
+    }
+    ownsDevTransformEntrypoint(filePath) {
+        const resolvedPath = path.resolve(filePath);
+        if (!isRegisteredDevTransformEntrypoint(this.context.getRegisteredEntrypoints(), resolvedPath)) {
+            return false;
+        }
+        return this.isPageOrLayoutSource(resolvedPath) && this.hasJsxTemplateExtension(resolvedPath);
+    }
+    async process(filePath) {
+        return {
+            type: 'broadcast',
+            events: [
+                {
+                    type: 'layout-update',
+                    path: filePath,
+                    timestamp: Date.now(),
+                },
+            ],
+        };
+    }
+    isPageOrLayoutSource(resolvedPath) {
+        const pagesDir = path.resolve(this.context.getPagesDir());
+        const layoutsDir = path.resolve(this.context.getLayoutsDir());
+        if (pagesDir && (resolvedPath === pagesDir || resolvedPath.startsWith(`${pagesDir}${path.sep}`))) {
+            return true;
+        }
+        if (layoutsDir && (resolvedPath === layoutsDir || resolvedPath.startsWith(`${layoutsDir}${path.sep}`))) {
+            return true;
+        }
+        return false;
+    }
+    hasJsxTemplateExtension(resolvedPath) {
+        return this.context.getTemplateExtensions().some((extension) => resolvedPath.endsWith(extension));
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { CompileOptions } from '@mdx-js/mdx';
+import type { EcoComponent, EcoComponentConfig, EcoFunctionComponent, EcoPageFile, GetMetadata } from '@ecopages/core';
+import type { EcoBuildPlugin } from '@ecopages/core/integration';
+import { appendMdxExtensions, createMdxExtensionFilter } from '@ecopages/mdx/core';
+import type { JsxRenderable } from '@ecopages/jsx';
+import type { EcopagesJsxMdxOptions } from './ecopages-jsx.types.js';
+import type { RequestPipelineMetricsState } from '@ecopages/core/build';
+export type ResolvedMdxCompileOptions = CompileOptions & {
+    jsxImportSource: '@ecopages/jsx';
+};
+export type AsyncEcoComponent<P = Record<string, unknown>, R = JsxRenderable> = EcoFunctionComponent<P, R | Promise<R>>;
+type AsyncEcoPageComponent = AsyncEcoComponent<Record<string, unknown>> & {
+    metadata?: GetMetadata;
+};
+export type EcopagesJsxMdxPageModule = Omit<EcoPageFile<{
+    config?: EcoComponentConfig;
+    layout?: EcoComponent;
+    getMetadata?: GetMetadata;
+}>, 'default'> & {
+    default: AsyncEcoPageComponent;
+};
+export { appendMdxExtensions, createMdxExtensionFilter };
+export declare const resolveMdxCompilerOptions: (mdxOptions: EcopagesJsxMdxOptions) => ResolvedMdxCompileOptions;
+export interface CreateEcopagesJsxMdxLoaderPluginOptions {
+    compilerOptions: ResolvedMdxCompileOptions;
+    extensions: string[];
+    projectRoot: string;
+    requestPipelineMetrics: RequestPipelineMetricsState;
+}
+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

@@ -0,0 +1,48 @@
+import { ensurePageConfigLayouts } from '@ecopages/core/integration';
+import { appendMdxExtensions, createMdxExtensionFilter, createMdxLoaderPlugin as createMdxLoaderPluginCore, resolveMdxCompilerOptions as resolveMdxCompilerOptionsCore, } from '@ecopages/mdx/core';
+import { ECOPAGES_JSX_PLUGIN_NAME } from './ecopages-jsx.constants.js';
+export { appendMdxExtensions, createMdxExtensionFilter };
+export const resolveMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptionsCore(mdxOptions, {
+    jsxImportSource: '@ecopages/jsx',
+    defaults: {
+        format: 'detect',
+        outputFormat: 'program',
+    },
+});
+export const createMdxLoaderPlugin = (options) => createMdxLoaderPluginCore({
+    name: 'ecopages-jsx-mdx-loader',
+    integrationName: ECOPAGES_JSX_PLUGIN_NAME,
+    compilerOptions: options.compilerOptions,
+    extensions: options.extensions,
+    includeSourceMap: false,
+    loader: 'js',
+    projectRoot: options.projectRoot,
+    requestPipelineMetrics: options.requestPipelineMetrics,
+});
+export const isMdxFile = (filePath, extensions) => {
+    return extensions.some((ext) => filePath.endsWith(ext));
+};
+export const normalizeMdxPageModule = (file, module) => {
+    if (typeof module.default !== 'function') {
+        throw new TypeError('MDX file must export a callable default component.');
+    }
+    const Page = module.default;
+    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(attributedConfig);
+    const wrappedPage = async (props) => await Page(props);
+    wrappedPage.config = attributedConfig;
+    if (module.getMetadata ?? Page.metadata) {
+        wrappedPage.metadata = module.getMetadata ?? Page.metadata;
+    }
+    return {
+        ...module,
+        default: wrappedPage,
+        config: attributedConfig,
+    };
+};

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

@@ -0,0 +1,39 @@
+import { createMarkupNodeLike } from '@ecopages/jsx';
+/**
+ * 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 declare class EcopagesJsxRadiantSsrPolicy {
+    private runtimeModules;
+    private runtimeModulesPromise;
+    private readonly enabled;
+    constructor(enabled: boolean);
+    /**
+     * Ensures the Radiant SSR runtime is installed before a render needs it.
+     */
+    prepareRuntime(): Promise<void>;
+    /**
+     * Runs one render inside Radiant's server runtime when the policy is enabled.
+     */
+    withRuntime<T>(render: () => T): Promise<T>;
+    /**
+     * 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: unknown, applyChildren?: () => void): ReturnType<typeof createMarkupNodeLike> | undefined;
+    private ensureRuntimeInstalled;
+}