@ecopages/ecopages-jsx 0.2.0-alpha.12

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [UNRELEASED] -- TBD
+
+### Features
+
+- Added `@ecopages/ecopages-jsx` integration plugin for server-side JSX rendering via `@ecopages/jsx`
+- Added optional `radiant` option (default `true`) to include `@ecopages/radiant` and `@ecopages/signals` vendor bundles; set to `false` for pages that do not use Radiant web components
+- Added optional MDX support via `@mdx-js/mdx` compile() when `mdx.enabled: true`
+- Added `jsxImportSource: '@ecopages/jsx'` pragma propagation to both SSR and MDX compile pipelines
+
+### Bug Fixes
+
+- Fixed the package contract to require the `@ecopages/radiant` peer dependency because the default JSX integration path depends on Radiant runtime assets.
+- Fixed custom Ecopages JSX MDX extension matching to escape full multi-dot extensions in both esbuild and Bun loader filters.
+- Fixed the kitchen-sink Ecopages JSX demo to use the shared light-DOM `radiant-counter` host so mixed routes render without leaking Radiant shadow-root SSR behavior into Lit pages.
+- Fixed Radiant browser bundles to publish the `@ecopages/jsx/server` import-map entry required by the vendored `@ecopages/radiant` runtime.
+- Fixed Ecopages JSX browser bundles to rewrite emitted `@ecopages/jsx` and `@ecopages/radiant` runtime imports to vendor asset URLs and avoid mapping server-only Radiant subpaths into the browser runtime.
+- Fixed the vendored Radiant browser runtime to emit exports from curated public subpaths instead of the package root surface.
+- Fixed MDX setup to register Bun-only loader hooks only when the integration is running on Bun.
+- Fixed deferred template compatibility registration to live on the JSX renderer instead of a side-effect bootstrap module.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Andrea Zanenghi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @ecopages/ecopages-jsx
+
+Integration plugin for [@ecopages/jsx](https://jsr.io/@ecopages/jsx) templates in Ecopages. It provides server-rendered JSX pages, Radiant-backed web component support, and optional MDX route handling.
+
+## Installation
+
+```bash
+bunx jsr add @ecopages/ecopages-jsx @ecopages/radiant
+```
+
+`@ecopages/radiant` is a required peer dependency for this package.
+
+## Usage
+
+Register the `ecopagesJsxPlugin` in your `eco.config.ts`.
+
+```ts
+import { ConfigBuilder } from '@ecopages/core/config-builder';
+import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
+
+const config = await new ConfigBuilder()
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
+	.setIntegrations([ecopagesJsxPlugin()])
+	.build();
+
+export default config;
+```
+
+## Radiant Support
+
+Radiant runtime bundles are enabled by default so JSX pages can render and hydrate Radiant custom elements.
+
+```ts
+ecopagesJsxPlugin({
+	radiant: true,
+});
+```
+
+Set `radiant: false` when your JSX pages do not need the Radiant browser runtime on a given app.
+
+## MDX Support
+
+Enable MDX to treat `.mdx` files as JSX routes compiled against the `@ecopages/jsx` runtime.
+
+```ts
+import { ConfigBuilder } from '@ecopages/core/config-builder';
+import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
+
+const config = await new ConfigBuilder()
+	.setIntegrations([
+		ecopagesJsxPlugin({
+			mdx: {
+				enabled: true,
+			},
+		}),
+	])
+	.build();
+
+export default config;
+```

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ecopages/ecopages-jsx",
+  "version": "0.2.0-alpha.12",
+  "description": "JSX integration plugin for Ecopages",
+  "keywords": [
+    "ecopages",
+    "jsx",
+    "plugin"
+  ],
+  "license": "MIT",
+  "main": "./src/ecopages-jsx.plugin.js",
+  "types": "./src/ecopages-jsx.plugin.d.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/integrations/ecopages-jsx"
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "vfile": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.12",
+    "@ecopages/jsx": "^0.3.0-alpha.0",
+    "@ecopages/radiant": "^0.3.0-alpha.0"
+  }
+}

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

@@ -0,0 +1,65 @@
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentConfig, EcoPageFile, GetMetadata, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import type { EcoPagesAppConfig } from '@ecopages/core/internal-types';
+import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
+import type { AssetProcessingService, ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
+import { type DeferredTemplateSerializer, type SerializableTemplateShape } from '@ecopages/core/route-renderer/template-serialization';
+import type { JsxRenderable } from '@ecopages/jsx';
+type EcopagesJsxTemplateShape = SerializableTemplateShape & {
+    _$rType$: 1;
+};
+type MdxPageModule = EcoPageFile<{
+    config?: EcoComponentConfig;
+    layout?: EcoComponent;
+    getMetadata?: GetMetadata;
+}>;
+/**
+ * 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> {
+    /**
+     * Deferred template serializers owned by the Ecopages JSX renderer.
+     *
+     * @remarks
+     * Ecopages JSX can emit runtime-specific deferred template payloads during
+     * mixed-integration rendering. Declaring the serializer here keeps JSX
+     * template-shape knowledge colocated with the renderer while the base
+     * `IntegrationRenderer` handles registration automatically.
+     */
+    static readonly deferredTemplateSerializers: DeferredTemplateSerializer<EcopagesJsxTemplateShape>[];
+    name: string;
+    static mdxExtensions: string[];
+    private intrinsicCustomElementAssets;
+    private collectedAssetFrames;
+    private radiantSsrEnabled;
+    constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, runtimeOrigin, }: {
+        appConfig: EcoPagesAppConfig;
+        assetProcessingService: AssetProcessingService;
+        resolvedIntegrationDependencies: ProcessedAsset[];
+        runtimeOrigin: string;
+    });
+    /** Returns whether the requested page file should be treated as MDX. */
+    isMdxFile(filePath: string): boolean;
+    /**
+     * Supplies the intrinsic custom-element assets discovered by the plugin so
+     * component renders can attach the correct client scripts.
+     */
+    setIntrinsicCustomElementAssets(assetsByTagName: Map<string, readonly ProcessedAsset[]>): void;
+    /** Enables the Radiant SSR light-DOM shim for this renderer instance. */
+    setRadiantSsrEnabled(enabled: boolean): void;
+    protected importPageFile(file: string): Promise<MdxPageModule>;
+    render(options: IntegrationRendererRenderOptions<JsxRenderable>): Promise<RouteRendererBody>;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    renderToResponse<P = any>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+    private resolveViewMetadata;
+    private renderDocument;
+    private beginCollectedAssetFrame;
+    private endCollectedAssetFrame;
+    private mergeCollectedAssets;
+    private renderJsx;
+    private renderEcoComponent;
+    private createIntrinsicCustomElementRenderHook;
+}
+export {};

package/src/ecopages-jsx-renderer.js

@@ -0,0 +1,298 @@
+import { rapidhash } from "@ecopages/core/hash";
+import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
+import {
+  serializeTemplateShape
+} from "@ecopages/core/route-renderer/template-serialization";
+import { renderToString, withServerCustomElementRenderHook } from "@ecopages/jsx/server";
+import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.plugin.js";
+let radiantLightDomShimInstallPromise;
+const ecopagesJsxDeferredTemplateSerializer = {
+  matches(value) {
+    return typeof value === "object" && value !== null && value._$rType$ === 1 && Array.isArray(value.strings) && (value.values === void 0 || Array.isArray(value.values));
+  },
+  serialize(template, serializeValue) {
+    return serializeTemplateShape(template, serializeValue);
+  }
+};
+async function ensureRadiantLightDomShimInstalled() {
+  if (!radiantLightDomShimInstallPromise) {
+    radiantLightDomShimInstallPromise = import("@ecopages/radiant/server/light-dom-shim").then((module) => {
+      module.installLightDomShim();
+    }).then(() => void 0);
+  }
+  await radiantLightDomShimInstallPromise;
+}
+const isEcoFunctionComponent = (component) => {
+  return typeof component === "function";
+};
+const renderComponent = async (component, props) => {
+  return await component(props);
+};
+const createEcoMeta = (file) => ({
+  id: String(rapidhash(file)),
+  file,
+  integration: ECOPAGES_JSX_PLUGIN_NAME
+});
+const wrapMdxPage = (page, {
+  config,
+  metadata
+}) => {
+  const wrappedPage = (async (props) => renderComponent(page, props));
+  wrappedPage.config = config;
+  if (metadata) {
+    wrappedPage.metadata = metadata;
+  }
+  return wrappedPage;
+};
+class EcopagesJsxRenderer extends IntegrationRenderer {
+  /**
+   * Deferred template serializers owned by the Ecopages JSX renderer.
+   *
+   * @remarks
+   * Ecopages JSX can emit runtime-specific deferred template payloads during
+   * mixed-integration rendering. Declaring the serializer here keeps JSX
+   * template-shape knowledge colocated with the renderer while the base
+   * `IntegrationRenderer` handles registration automatically.
+   */
+  static deferredTemplateSerializers = [ecopagesJsxDeferredTemplateSerializer];
+  name = ECOPAGES_JSX_PLUGIN_NAME;
+  static mdxExtensions = [".mdx"];
+  intrinsicCustomElementAssets = /* @__PURE__ */ new Map();
+  collectedAssetFrames = [];
+  radiantSsrEnabled = false;
+  constructor({
+    appConfig,
+    assetProcessingService,
+    resolvedIntegrationDependencies,
+    runtimeOrigin
+  }) {
+    super({
+      appConfig,
+      assetProcessingService,
+      resolvedIntegrationDependencies,
+      runtimeOrigin
+    });
+  }
+  /** Returns whether the requested page file should be treated as MDX. */
+  isMdxFile(filePath) {
+    return EcopagesJsxRenderer.mdxExtensions.some((ext) => filePath.endsWith(ext));
+  }
+  /**
+   * Supplies the intrinsic custom-element assets discovered by the plugin so
+   * component renders can attach the correct client scripts.
+   */
+  setIntrinsicCustomElementAssets(assetsByTagName) {
+    this.intrinsicCustomElementAssets = assetsByTagName;
+  }
+  /** Enables the Radiant SSR light-DOM shim for this renderer instance. */
+  setRadiantSsrEnabled(enabled) {
+    this.radiantSsrEnabled = enabled;
+  }
+  async importPageFile(file) {
+    const module = await super.importPageFile(file);
+    if (!this.isMdxFile(file)) {
+      return module;
+    }
+    const Page = module.default;
+    const normalizedConfig = {
+      ...module.config ?? Page.config ?? {},
+      ...module.layout ? { layout: module.layout } : {},
+      __eco: module.config?.__eco ?? Page.config?.__eco ?? createEcoMeta(file)
+    };
+    const wrappedPage = wrapMdxPage(Page, {
+      config: normalizedConfig,
+      metadata: module.getMetadata ?? Page.metadata
+    });
+    return {
+      ...module,
+      default: wrappedPage,
+      config: normalizedConfig
+    };
+  }
+  async render(options) {
+    const assetFrame = this.beginCollectedAssetFrame();
+    try {
+      const page = await this.renderEcoComponent(options.Page, {
+        ...options.pageProps,
+        locals: options.pageLocals
+      });
+      const content = options.Layout ? await this.renderEcoComponent(options.Layout, {
+        ...options.pageProps,
+        children: page,
+        locals: options.locals
+      }) : page;
+      const document = await this.renderEcoComponent(
+        options.HtmlTemplate,
+        {
+          metadata: options.metadata,
+          pageProps: options.pageProps ?? {},
+          children: content
+        }
+      );
+      const renderedDocument = await this.renderJsx(document);
+      this.mergeCollectedAssets(this.endCollectedAssetFrame(assetFrame));
+      return `${this.DOC_TYPE}${renderedDocument.html}`;
+    } catch (error) {
+      this.endCollectedAssetFrame(assetFrame);
+      throw this.createRenderError("Error rendering page", error);
+    }
+  }
+  async renderComponent(input) {
+    const assetFrame = this.beginCollectedAssetFrame();
+    try {
+      if (!isEcoFunctionComponent(input.component)) {
+        throw new TypeError("JSX renderer expected a callable component.");
+      }
+      const props = input.children === void 0 ? input.props : { ...input.props, children: input.children };
+      const content = await this.renderEcoComponent(
+        input.component,
+        props
+      );
+      const rendered = await this.renderJsx(content);
+      const componentAssets = input.component.config?.dependencies && typeof this.assetProcessingService?.processDependencies === "function" ? await this.processComponentDependencies([input.component]) : [];
+      const html = rendered.html;
+      const assets = this.htmlTransformer.dedupeProcessedAssets([
+        ...this.endCollectedAssetFrame(assetFrame),
+        ...componentAssets
+      ]);
+      return {
+        html,
+        canAttachAttributes: true,
+        rootTag: this.getRootTagName(html),
+        integrationName: this.name,
+        assets
+      };
+    } catch (error) {
+      this.endCollectedAssetFrame(assetFrame);
+      throw this.createRenderError("Error rendering component", error);
+    }
+  }
+  async renderToResponse(view, props, ctx) {
+    try {
+      if (!isEcoFunctionComponent(view)) {
+        throw new TypeError("JSX renderer expected a callable view component.");
+      }
+      const layout = ctx.partial ? void 0 : view.config?.layout;
+      await this.prepareViewDependencies(view, layout);
+      const HtmlTemplate = ctx.partial ? void 0 : await this.getHtmlTemplate();
+      const metadata = ctx.partial ? void 0 : await this.resolveViewMetadata(view, props);
+      const assetFrame = this.beginCollectedAssetFrame();
+      const capturedRender = await this.captureHtmlRender(async () => {
+        const viewContent = await this.renderEcoComponent(view, props);
+        if (ctx.partial) {
+          return (await this.renderJsx(viewContent)).html;
+        }
+        return (await this.renderDocument(viewContent, {
+          metadata,
+          pageProps: props ?? {},
+          layout
+        })).html;
+      });
+      this.mergeCollectedAssets(this.endCollectedAssetFrame(assetFrame));
+      const html = await this.finalizeCapturedHtmlRender({
+        html: capturedRender.html,
+        graphContext: capturedRender.graphContext,
+        componentsToResolve: HtmlTemplate ? layout ? [HtmlTemplate, layout, view] : [HtmlTemplate, view] : [view],
+        partial: ctx.partial
+      });
+      return this.createHtmlResponse(html, ctx);
+    } catch (error) {
+      throw this.createRenderError("Error rendering view", error);
+    }
+  }
+  async resolveViewMetadata(view, props) {
+    return view.metadata ? await view.metadata({
+      params: {},
+      query: {},
+      props,
+      appConfig: this.appConfig
+    }) : this.appConfig.defaultMetadata;
+  }
+  async renderDocument(content, {
+    metadata,
+    pageProps,
+    layout
+  }) {
+    const resolvedContent = layout ? await this.renderEcoComponent(layout, {
+      ...pageProps,
+      children: content
+    }) : content;
+    const HtmlTemplate = await this.getHtmlTemplate();
+    const document = await this.renderEcoComponent(HtmlTemplate, {
+      metadata,
+      pageProps,
+      children: resolvedContent
+    });
+    const renderedDocument = await this.renderJsx(document);
+    return {
+      assets: renderedDocument.assets,
+      html: `${this.DOC_TYPE}${renderedDocument.html}`
+    };
+  }
+  beginCollectedAssetFrame() {
+    const frame = [];
+    this.collectedAssetFrames.push(frame);
+    return frame;
+  }
+  endCollectedAssetFrame(frame) {
+    const activeFrame = this.collectedAssetFrames.pop();
+    if (!activeFrame || activeFrame !== frame) {
+      return this.htmlTransformer.dedupeProcessedAssets(frame);
+    }
+    return this.htmlTransformer.dedupeProcessedAssets(activeFrame);
+  }
+  mergeCollectedAssets(assets) {
+    if (assets.length === 0) {
+      return;
+    }
+    this.htmlTransformer.setProcessedDependencies(
+      this.htmlTransformer.dedupeProcessedAssets([...this.htmlTransformer.getProcessedDependencies(), ...assets])
+    );
+  }
+  async renderJsx(value) {
+    if (this.radiantSsrEnabled) {
+      await ensureRadiantLightDomShimInstalled();
+    }
+    const collectedAssets = [];
+    const html = withServerCustomElementRenderHook(
+      this.createIntrinsicCustomElementRenderHook(collectedAssets),
+      () => renderToString(value)
+    );
+    const dedupedAssets = this.htmlTransformer.dedupeProcessedAssets(collectedAssets);
+    const activeFrame = this.collectedAssetFrames[this.collectedAssetFrames.length - 1];
+    if (activeFrame) {
+      activeFrame.push(...dedupedAssets);
+    }
+    return {
+      assets: dedupedAssets,
+      html
+    };
+  }
+  async renderEcoComponent(component, props) {
+    if (this.radiantSsrEnabled) {
+      await ensureRadiantLightDomShimInstalled();
+    }
+    const collectedAssets = [];
+    const rendered = await withServerCustomElementRenderHook(
+      this.createIntrinsicCustomElementRenderHook(collectedAssets),
+      () => renderComponent(component, props)
+    );
+    const activeFrame = this.collectedAssetFrames[this.collectedAssetFrames.length - 1];
+    if (activeFrame) {
+      activeFrame.push(...this.htmlTransformer.dedupeProcessedAssets(collectedAssets));
+    }
+    return rendered;
+  }
+  createIntrinsicCustomElementRenderHook(target) {
+    return ({ tagName }) => {
+      const assets = this.intrinsicCustomElementAssets.get(tagName);
+      if (assets) {
+        target.push(...assets);
+      }
+      return void 0;
+    };
+  }
+}
+export {
+  EcopagesJsxRenderer
+};

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

@@ -0,0 +1,116 @@
+import type { CompileOptions } from '@mdx-js/mdx';
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
+import type { JsxRenderable } from '@ecopages/jsx';
+import { EcopagesJsxRenderer } from './ecopages-jsx-renderer.js';
+type MdxPluginList = NonNullable<CompileOptions['remarkPlugins']>;
+type MdxCompileOptions = Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime' | 'remarkPlugins' | 'rehypePlugins' | 'recmaPlugins'> & {
+    remarkPlugins?: MdxPluginList;
+    rehypePlugins?: MdxPluginList;
+    recmaPlugins?: MdxPluginList;
+};
+/**
+ * Stable integration name shared by the JSX plugin and renderer.
+ *
+ * Ecopages uses this identifier to match route files, renderer instances, and
+ * cross-integration component boundaries.
+ */
+export declare const ECOPAGES_JSX_PLUGIN_NAME = "ecopages-jsx";
+/**
+ * MDX configuration for the JSX integration.
+ *
+ * Mirrors Ecopages' built-in combined integration pattern where a single
+ * JSX-capable plugin can own both `.tsx` and `.mdx` route files.
+ */
+export type EcopagesJsxMdxOptions = {
+    /** Enables MDX file handling inside the JSX integration. */
+    enabled: boolean;
+    /** Additional MDX compiler options. JSX runtime fields are managed by the integration. */
+    compilerOptions?: MdxCompileOptions;
+    /** Extra remark plugins appended to `compilerOptions.remarkPlugins`. */
+    remarkPlugins?: MdxPluginList;
+    /** Extra rehype plugins appended to `compilerOptions.rehypePlugins`. */
+    rehypePlugins?: MdxPluginList;
+    /** Extra recma plugins appended to `compilerOptions.recmaPlugins`. */
+    recmaPlugins?: MdxPluginList;
+    /** Custom file extensions to treat as MDX. */
+    extensions?: string[];
+};
+/** Options for the JSX integration plugin. */
+export type EcopagesJsxPluginOptions = Omit<IntegrationPluginConfig, 'name' | 'extensions'> & {
+    /** Optional JSX route extensions. Defaults to `.tsx`. */
+    extensions?: string[];
+    /**
+     * Whether to include the `@ecopages/radiant` and `@ecopages/signals` vendor
+     * bundles and bare-specifier mappings.
+     *
+     * Set to `false` when pages do not use Radiant web components.
+     * @default true
+     */
+    radiant?: boolean;
+    /** Optional MDX integration configuration. */
+    mdx?: EcopagesJsxMdxOptions;
+};
+/** JSX integration plugin for Ecopages, supporting `.tsx` templates and optional Radiant web components. */
+export declare class EcopagesJsxPlugin extends IntegrationPlugin<JsxRenderable> {
+    /** Renderer implementation used for JSX and MDX routes. */
+    renderer: IntegrationPlugin<JsxRenderable>["renderer"];
+    private intrinsicCustomElementAssets;
+    private includeRadiant;
+    private mdxEnabled;
+    private mdxCompilerOptions?;
+    private mdxExtensions;
+    private mdxLoaderPlugin?;
+    private runtimeBundleService;
+    private runtimeSpecifierMap;
+    private runtimeDepsInitialized;
+    /** Returns the build plugins required by the JSX integration. */
+    get plugins(): EcoBuildPlugin[];
+    /** Returns the browser-only build plugins required by the JSX integration. */
+    get browserBuildPlugins(): EcoBuildPlugin[];
+    /**
+     * Exposes the bare-module specifier map used by the import map.
+     *
+     * Client bundles keep these imports external so the browser can load the
+     * shared runtime packages from the generated vendor assets.
+     */
+    getRuntimeSpecifierMap(): Record<string, string>;
+    /**
+     * Creates the renderer instance and attaches the discovered intrinsic custom
+     * element assets before the renderer handles any requests.
+     */
+    initializeRenderer(): EcopagesJsxRenderer;
+    /**
+     * Creates a JSX integration plugin.
+     *
+     * When MDX is enabled, the plugin also claims the configured MDX extensions
+     * and prepares compiler options around the shared `@ecopages/jsx` runtime.
+     */
+    constructor(options?: EcopagesJsxPluginOptions);
+    /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Registers MDX tooling, discovers intrinsic custom-element assets, and then
+     * completes the base integration setup.
+     */
+    setup(): Promise<void>;
+    /**
+     * Defers boundaries only when another integration renders a component that is
+     * owned by this JSX integration.
+     */
+    shouldDeferComponentBoundary(input: {
+        currentIntegration: string;
+        targetIntegration?: string;
+    }): boolean;
+    private ensureMdxLoaderPlugin;
+    private setupMdxBunPlugin;
+    private buildIntrinsicCustomElementAssetRegistry;
+    private collectScriptEntryFiles;
+    private resolveIntrinsicCustomElementAsset;
+    private extractIntrinsicCustomElementTagNames;
+}
+/**
+ * Creates the JSX integration plugin.
+ */
+export declare const ecopagesJsxPlugin: (options?: EcopagesJsxPluginOptions) => EcopagesJsxPlugin;
+export {};

package/src/ecopages-jsx.plugin.js

@@ -0,0 +1,251 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
+import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
+import { VFile } from "vfile";
+import { EcopagesJsxRenderer } from "./ecopages-jsx-renderer.js";
+import { JsxRuntimeBundleService } from "./services/jsx-runtime-bundle.service.js";
+const mergePluginLists = (...lists) => {
+  const merged = lists.flatMap((list) => list ? [...list] : []);
+  return merged.length > 0 ? merged : void 0;
+};
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const createMdxLoaderPlugin = (compilerOptions, extensions) => {
+  const escapedExts = extensions.map(escapeRegex);
+  const filter = new RegExp(`(${escapedExts.join("|")})(\\?.*)?$`);
+  return {
+    name: "ecopages-jsx-mdx-loader",
+    setup(build) {
+      build.onLoad({ filter }, async (args) => {
+        const { compile } = await import("@mdx-js/mdx");
+        const filePath = args.path.includes("?") ? args.path.split("?")[0] : args.path;
+        const source = await readFile(filePath, "utf-8");
+        const compiled = await compile(new VFile({ value: source, path: filePath }), compilerOptions);
+        return {
+          contents: String(compiled.value),
+          loader: "js",
+          resolveDir: path.dirname(filePath)
+        };
+      });
+    }
+  };
+};
+const ECOPAGES_JSX_PLUGIN_NAME = "ecopages-jsx";
+class EcopagesJsxPlugin extends IntegrationPlugin {
+  /** Renderer implementation used for JSX and MDX routes. */
+  renderer = EcopagesJsxRenderer;
+  intrinsicCustomElementAssets = /* @__PURE__ */ new Map();
+  includeRadiant;
+  mdxEnabled;
+  mdxCompilerOptions;
+  mdxExtensions;
+  mdxLoaderPlugin;
+  runtimeBundleService;
+  runtimeSpecifierMap = {};
+  runtimeDepsInitialized = false;
+  /** Returns the build plugins required by the JSX integration. */
+  get plugins() {
+    return [this.mdxLoaderPlugin].filter((plugin) => plugin !== void 0);
+  }
+  /** Returns the browser-only build plugins required by the JSX integration. */
+  get browserBuildPlugins() {
+    return [this.runtimeBundleService.getBuildPlugin()].filter(
+      (plugin) => plugin !== void 0
+    );
+  }
+  /**
+   * Exposes the bare-module specifier map used by the import map.
+   *
+   * Client bundles keep these imports external so the browser can load the
+   * shared runtime packages from the generated vendor assets.
+   */
+  getRuntimeSpecifierMap() {
+    return this.runtimeSpecifierMap;
+  }
+  /**
+   * Creates the renderer instance and attaches the discovered intrinsic custom
+   * element assets before the renderer handles any requests.
+   */
+  initializeRenderer() {
+    const renderer = super.initializeRenderer();
+    renderer.setIntrinsicCustomElementAssets(this.intrinsicCustomElementAssets);
+    renderer.setRadiantSsrEnabled(this.includeRadiant);
+    return renderer;
+  }
+  /**
+   * Creates a JSX integration plugin.
+   *
+   * When MDX is enabled, the plugin also claims the configured MDX extensions
+   * and prepares compiler options around the shared `@ecopages/jsx` runtime.
+   */
+  constructor(options) {
+    const { extensions: _ignoredExtensions, ...restOptions } = options ?? {};
+    const extensions = [...options?.extensions ?? [".tsx"]];
+    const mdxExtensions = options?.mdx?.extensions ?? [".mdx"];
+    const includeRadiant = options?.radiant ?? true;
+    if (options?.mdx?.enabled) {
+      for (const extension of mdxExtensions) {
+        if (!extensions.includes(extension)) {
+          extensions.push(extension);
+        }
+      }
+    }
+    super({
+      name: ECOPAGES_JSX_PLUGIN_NAME,
+      extensions,
+      jsxImportSource: "@ecopages/jsx",
+      ...restOptions
+    });
+    this.includeRadiant = includeRadiant;
+    this.runtimeBundleService = new JsxRuntimeBundleService({ radiant: includeRadiant });
+    this.mdxEnabled = options?.mdx?.enabled ?? false;
+    this.mdxExtensions = mdxExtensions;
+    EcopagesJsxRenderer.mdxExtensions = this.mdxExtensions;
+    if (this.mdxEnabled) {
+      const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = options?.mdx ?? {};
+      const resolvedCompilerOptions = {
+        format: "detect",
+        outputFormat: "program",
+        ...compilerOptions,
+        jsxImportSource: "@ecopages/jsx",
+        jsxRuntime: "automatic",
+        development: process.env.NODE_ENV === "development"
+      };
+      const mergedRemarkPlugins = mergePluginLists(compilerOptions?.remarkPlugins, remarkPlugins);
+      const mergedRehypePlugins = mergePluginLists(compilerOptions?.rehypePlugins, rehypePlugins);
+      const mergedRecmaPlugins = mergePluginLists(compilerOptions?.recmaPlugins, recmaPlugins);
+      if (mergedRemarkPlugins) {
+        resolvedCompilerOptions.remarkPlugins = mergedRemarkPlugins;
+      }
+      if (mergedRehypePlugins) {
+        resolvedCompilerOptions.rehypePlugins = mergedRehypePlugins;
+      }
+      if (mergedRecmaPlugins) {
+        resolvedCompilerOptions.recmaPlugins = mergedRecmaPlugins;
+      }
+      this.mdxCompilerOptions = resolvedCompilerOptions;
+    }
+  }
+  /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
+  async prepareBuildContributions() {
+    if (!this.runtimeDepsInitialized) {
+      this.runtimeDepsInitialized = true;
+      this.runtimeBundleService.setRootDir(this.appConfig?.rootDir);
+      this.runtimeSpecifierMap = await this.runtimeBundleService.getSpecifierMap();
+      const vendorDeps = await this.runtimeBundleService.getDependencies();
+      this.integrationDependencies.unshift(...vendorDeps);
+    }
+    this.ensureMdxLoaderPlugin();
+  }
+  /**
+   * Registers MDX tooling, discovers intrinsic custom-element assets, and then
+   * completes the base integration setup.
+   */
+  async setup() {
+    this.ensureMdxLoaderPlugin();
+    if (typeof Bun !== "undefined" && this.mdxEnabled && this.mdxCompilerOptions) {
+      await this.setupMdxBunPlugin();
+    }
+    await this.buildIntrinsicCustomElementAssetRegistry();
+    await super.setup();
+  }
+  /**
+   * Defers boundaries only when another integration renders a component that is
+   * owned by this JSX integration.
+   */
+  shouldDeferComponentBoundary(input) {
+    return input.targetIntegration === this.name && input.currentIntegration !== this.name;
+  }
+  ensureMdxLoaderPlugin() {
+    if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
+      return;
+    }
+    this.mdxLoaderPlugin = createMdxLoaderPlugin(this.mdxCompilerOptions, this.mdxExtensions);
+  }
+  async setupMdxBunPlugin() {
+    if (typeof Bun === "undefined" || !this.mdxEnabled || !this.mdxCompilerOptions) {
+      return;
+    }
+    const compilerOptions = this.mdxCompilerOptions;
+    const escapedExts = this.mdxExtensions.map(escapeRegex);
+    const filter = new RegExp(`(${escapedExts.join("|")})$`);
+    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" };
+        });
+      }
+    });
+  }
+  async buildIntrinsicCustomElementAssetRegistry() {
+    if (!this.appConfig || !this.assetProcessingService) {
+      return;
+    }
+    this.intrinsicCustomElementAssets.clear();
+    const scriptFiles = await this.collectScriptEntryFiles(this.appConfig.absolutePaths.srcDir);
+    for (const scriptFile of scriptFiles) {
+      const tagNames = await this.extractIntrinsicCustomElementTagNames(scriptFile);
+      if (tagNames.length === 0) {
+        continue;
+      }
+      const processedAsset = await this.resolveIntrinsicCustomElementAsset(scriptFile);
+      if (!processedAsset) {
+        continue;
+      }
+      for (const tagName of tagNames) {
+        this.intrinsicCustomElementAssets.set(tagName, [processedAsset]);
+      }
+    }
+  }
+  async collectScriptEntryFiles(directory) {
+    const directoryEntries = await readdir(directory, { withFileTypes: true });
+    const scriptFiles = [];
+    for (const directoryEntry of directoryEntries) {
+      const entryPath = path.join(directory, directoryEntry.name);
+      if (directoryEntry.isDirectory()) {
+        scriptFiles.push(...await this.collectScriptEntryFiles(entryPath));
+        continue;
+      }
+      if (/\.script\.(?:ts|tsx)$/.test(directoryEntry.name)) {
+        scriptFiles.push(entryPath);
+      }
+    }
+    return scriptFiles;
+  }
+  async resolveIntrinsicCustomElementAsset(scriptFile) {
+    if (!this.assetProcessingService) {
+      return void 0;
+    }
+    const [processedAsset] = await this.assetProcessingService.processDependencies(
+      [
+        AssetFactory.createFileScript({
+          filepath: scriptFile,
+          position: "head"
+        })
+      ],
+      `${this.name}:intrinsic-custom-elements:${scriptFile}`
+    );
+    return processedAsset;
+  }
+  async extractIntrinsicCustomElementTagNames(scriptFile) {
+    const source = await readFile(scriptFile, "utf8");
+    const tagNames = /* @__PURE__ */ new Set();
+    for (const match of source.matchAll(/@customElement\(\s*['"]([^'"]+)['"]/g)) {
+      const tagName = match[1];
+      if (tagName) {
+        tagNames.add(tagName);
+      }
+    }
+    return [...tagNames];
+  }
+}
+const ecopagesJsxPlugin = (options) => new EcopagesJsxPlugin(options);
+export {
+  ECOPAGES_JSX_PLUGIN_NAME,
+  EcopagesJsxPlugin,
+  ecopagesJsxPlugin
+};

package/src/services/jsx-runtime-bundle.service.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Runtime bundle service for the JSX integration.
+ *
+ * Owns creation of browser runtime vendor assets, the import map specifier
+ * mapping, and the build external plugin. Radiant sub-path specifiers are
+ * derived at runtime from `@ecopages/radiant/package.json` exports so the
+ * list stays in sync with whatever version is installed.
+ *
+ * @module
+ */
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+export interface JsxRuntimeBundleServiceConfig {
+    radiant: boolean;
+    rootDir?: string;
+}
+export declare class JsxRuntimeBundleService {
+    private readonly config;
+    private cachedSpecifierMap;
+    private cachedRadiantEntryModulePath;
+    constructor(config: JsxRuntimeBundleServiceConfig);
+    setRootDir(rootDir: string | undefined): void;
+    /**
+     * Returns the build plugin that aliases JSX and Radiant runtime specifiers to
+     * their emitted browser vendor URLs.
+     *
+     * @remarks
+     * The returned plugin both externalizes the mapped specifiers during bundle
+     * resolution and exposes alias metadata so Ecopages can rewrite any emitted JS
+     * imports that still reference bare runtime specifiers.
+     */
+    getBuildPlugin(): EcoBuildPlugin;
+    /**
+     * Builds the bare-specifier-to-vendor-URL map for the browser import map.
+     *
+     * JSX sub-paths are always included. When `radiant` is enabled, radiant
+     * sub-paths are derived from `@ecopages/radiant/package.json` exports and
+     * the result is cached for the lifetime of this service instance.
+     */
+    getSpecifierMap(): Promise<Record<string, string>>;
+    /**
+     * Builds the full list of vendor asset definitions: the import map inline
+     * script plus one `createBrowserRuntimeScriptAsset` per vendor bundle.
+     */
+    getDependencies(): Promise<AssetDefinition[]>;
+    private getOrCreateSpecifierMap;
+    private getRadiantBrowserRuntimeSpecifiers;
+    private getRadiantBrowserRuntimeModules;
+    private resolveRadiantExportModulePath;
+    private getOrCreateRadiantEntryModulePath;
+}

package/src/services/jsx-runtime-bundle.service.js

@@ -0,0 +1,206 @@
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
+import {
+  buildBrowserRuntimeAssetUrl,
+  createBrowserRuntimeScriptAsset,
+  AssetFactory
+} from "@ecopages/core/services/asset-processing-service";
+const VENDOR_FILE_NAMES = {
+  jsx: "ecopages-jsx-esm.js",
+  radiant: "ecopages-radiant-esm.js"
+};
+function getNamedExportNamesFromModuleSource(source) {
+  const exportNames = /* @__PURE__ */ new Set();
+  for (const match of source.matchAll(/export\s*\{([^}]+)\}/g)) {
+    for (const specifier of match[1].split(",")) {
+      const trimmedSpecifier = specifier.trim();
+      if (!trimmedSpecifier) {
+        continue;
+      }
+      const aliasMatch = trimmedSpecifier.match(/(?:.+\s+as\s+)?([A-Z_a-z$][\w$]*)$/);
+      if (aliasMatch?.[1] && aliasMatch[1] !== "default") {
+        exportNames.add(aliasMatch[1]);
+      }
+    }
+  }
+  for (const match of source.matchAll(
+    /export\s+(?:async\s+)?(?:const|function|class|let|var)\s+([A-Z_a-z$][\w$]*)/g
+  )) {
+    if (match[1] !== "default") {
+      exportNames.add(match[1]);
+    }
+  }
+  return [...exportNames].sort();
+}
+function isBrowserRuntimeRadiantSpecifier(exportKey) {
+  if (exportKey === "." || exportKey.startsWith("./context/")) {
+    return true;
+  }
+  if (exportKey.startsWith("./decorators/") || exportKey.startsWith("./helpers/")) {
+    return true;
+  }
+  return exportKey === "./core/radiant-component" || exportKey === "./core/radiant-element";
+}
+function findPackageManifestPath(packageName) {
+  let currentDir = path.dirname(new URL(import.meta.url).pathname);
+  while (true) {
+    const candidatePath = path.join(currentDir, "node_modules", packageName, "package.json");
+    if (existsSync(candidatePath)) {
+      return candidatePath;
+    }
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  throw new Error(`Could not locate ${packageName}/package.json from ${import.meta.url}`);
+}
+class JsxRuntimeBundleService {
+  config;
+  cachedSpecifierMap;
+  cachedRadiantEntryModulePath;
+  constructor(config) {
+    this.config = config;
+  }
+  setRootDir(rootDir) {
+    this.config.rootDir = rootDir;
+  }
+  /**
+   * Returns the build plugin that aliases JSX and Radiant runtime specifiers to
+   * their emitted browser vendor URLs.
+   *
+   * @remarks
+   * The returned plugin both externalizes the mapped specifiers during bundle
+   * resolution and exposes alias metadata so Ecopages can rewrite any emitted JS
+   * imports that still reference bare runtime specifiers.
+   */
+  getBuildPlugin() {
+    return createRuntimeSpecifierAliasPlugin(this.getOrCreateSpecifierMap(), {
+      name: "ecopages-jsx-runtime-alias"
+    });
+  }
+  /**
+   * Builds the bare-specifier-to-vendor-URL map for the browser import map.
+   *
+   * JSX sub-paths are always included. When `radiant` is enabled, radiant
+   * sub-paths are derived from `@ecopages/radiant/package.json` exports and
+   * the result is cached for the lifetime of this service instance.
+   */
+  async getSpecifierMap() {
+    return this.getOrCreateSpecifierMap();
+  }
+  /**
+   * Builds the full list of vendor asset definitions: the import map inline
+   * script plus one `createBrowserRuntimeScriptAsset` per vendor bundle.
+   */
+  async getDependencies() {
+    const specifierMap = await this.getSpecifierMap();
+    const deps = [
+      AssetFactory.createInlineContentScript({
+        position: "head",
+        bundle: false,
+        content: JSON.stringify({ imports: specifierMap }, null, 2),
+        attributes: { type: "importmap" }
+      }),
+      createBrowserRuntimeScriptAsset({
+        importPath: "@ecopages/jsx",
+        name: "ecopages-jsx-esm",
+        fileName: VENDOR_FILE_NAMES.jsx
+      })
+    ];
+    if (this.config.radiant) {
+      const radiantEntryModulePath = await this.getOrCreateRadiantEntryModulePath();
+      deps.push(
+        createBrowserRuntimeScriptAsset({
+          importPath: radiantEntryModulePath,
+          name: "ecopages-radiant-esm",
+          fileName: VENDOR_FILE_NAMES.radiant
+        })
+      );
+    }
+    return deps;
+  }
+  getOrCreateSpecifierMap() {
+    if (this.cachedSpecifierMap) {
+      return this.cachedSpecifierMap;
+    }
+    const jsxVendorUrl = buildBrowserRuntimeAssetUrl(VENDOR_FILE_NAMES.jsx);
+    const specifierMap = {
+      "@ecopages/jsx": jsxVendorUrl,
+      "@ecopages/jsx/server": jsxVendorUrl,
+      "@ecopages/jsx/client": jsxVendorUrl,
+      "@ecopages/jsx/jsx-runtime": jsxVendorUrl,
+      "@ecopages/jsx/jsx-dev-runtime": jsxVendorUrl
+    };
+    if (this.config.radiant) {
+      const radiantVendorUrl = buildBrowserRuntimeAssetUrl(VENDOR_FILE_NAMES.radiant);
+      const radiantPkg = JSON.parse(
+        readFileSync(findPackageManifestPath("@ecopages/radiant"), "utf8")
+      );
+      for (const key of Object.keys(radiantPkg.exports ?? {})) {
+        if (!isBrowserRuntimeRadiantSpecifier(key)) {
+          continue;
+        }
+        const specifier = key === "." ? "@ecopages/radiant" : `@ecopages/radiant${key.slice(1)}`;
+        specifierMap[specifier] = radiantVendorUrl;
+      }
+    }
+    this.cachedSpecifierMap = specifierMap;
+    return specifierMap;
+  }
+  getRadiantBrowserRuntimeSpecifiers() {
+    return this.getRadiantBrowserRuntimeModules().map(({ exportKey }) => `@ecopages/radiant${exportKey.slice(1)}`);
+  }
+  getRadiantBrowserRuntimeModules() {
+    const manifestPath = findPackageManifestPath("@ecopages/radiant");
+    const packageDir = path.dirname(realpathSync(manifestPath));
+    const radiantPkg = JSON.parse(readFileSync(manifestPath, "utf8"));
+    return Object.entries(radiantPkg.exports ?? {}).filter(([key]) => isBrowserRuntimeRadiantSpecifier(key) && key !== ".").sort(([left], [right]) => left.localeCompare(right)).map(([exportKey, exportTarget]) => ({
+      exportKey,
+      modulePath: this.resolveRadiantExportModulePath(packageDir, exportKey, exportTarget)
+    })).filter((module) => existsSync(module.modulePath));
+  }
+  resolveRadiantExportModulePath(packageDir, exportKey, exportTarget) {
+    if (typeof exportTarget === "string") {
+      return path.resolve(packageDir, exportTarget);
+    }
+    if (exportTarget && typeof exportTarget === "object" && "import" in exportTarget) {
+      const importTarget = exportTarget.import;
+      if (typeof importTarget === "string") {
+        return path.resolve(packageDir, importTarget);
+      }
+    }
+    throw new Error(`Missing import target for @ecopages/radiant export ${exportKey}`);
+  }
+  async getOrCreateRadiantEntryModulePath() {
+    if (this.cachedRadiantEntryModulePath) {
+      return this.cachedRadiantEntryModulePath;
+    }
+    const rootDir = this.config.rootDir ?? process.cwd();
+    const artifactsDir = path.join(rootDir, "node_modules", ".cache", "ecopages-browser-runtime");
+    const filePath = path.join(artifactsDir, "ecopages-radiant-esm-entry.mjs");
+    const seenExports = /* @__PURE__ */ new Set();
+    const statements = [];
+    mkdirSync(artifactsDir, { recursive: true });
+    for (const module of this.getRadiantBrowserRuntimeModules()) {
+      const exportNames = getNamedExportNamesFromModuleSource(readFileSync(module.modulePath, "utf8")).filter((name) => !seenExports.has(name)).filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name)).sort();
+      if (exportNames.length === 0) {
+        continue;
+      }
+      const relativeModulePath = path.relative(artifactsDir, module.modulePath).split(path.sep).join("/");
+      const entryImportPath = relativeModulePath.startsWith(".") ? relativeModulePath : `./${relativeModulePath}`;
+      statements.push(`export { ${exportNames.join(", ")} } from '${entryImportPath}';`);
+      for (const exportName of exportNames) {
+        seenExports.add(exportName);
+      }
+    }
+    writeFileSync(filePath, statements.join("\n"), "utf8");
+    this.cachedRadiantEntryModulePath = filePath;
+    return filePath;
+  }
+}
+export {
+  JsxRuntimeBundleService
+};