@ecopages/ecopages-jsx 0.2.0-beta.4 → 0.2.0-beta.41

package/README.md

@@ -48,6 +48,7 @@ Radiant support is enabled by default. When `radiant: true`, the plugin keeps th
 
 - 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.
@@ -99,6 +100,7 @@ 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)`.
 - 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.
 - 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-beta.4",
+  "version": "0.2.0-beta.41",
   "description": "JSX integration plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -27,16 +27,17 @@
   },
   "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/mdx": "0.2.0-beta.41",
     "@mdx-js/mdx": "^3.1.1",
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-beta.4",
-    "@ecopages/jsx": "0.3.0-alpha.25",
-    "@ecopages/radiant": "0.3.0-alpha.25"
+    "@ecopages/core": "0.2.0-beta.41",
+    "@ecopages/jsx": "0.3.0-beta.6",
+    "@ecopages/radiant": "0.3.0-beta.6"
   }
 }

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

@@ -0,0 +1,17 @@
+import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import type { DevTransformBundleContributor } from '@ecopages/core/dev/transform-server';
+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.js

@@ -1,11 +1,9 @@
-import { eco } from "@ecopages/core";
-function EcoEmbed({
-  component,
-  props,
-  children
-}) {
-  return eco.embed(component, props, children);
+/** @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);
 }
-export {
-  EcoEmbed
-};

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

@@ -0,0 +1,45 @@
+/**
+ * Tracks the source files that participate in the active SSR render tree.
+ *
+ * @remarks
+ * The JSX integration renderer calls {@link updateEjsxHmrOwnership} after each
+ * page, component, or view render so the HMR strategy can answer
+ * "does this changed file affect SSR HTML?" without re-walking the tree on
+ * every watcher event.
+ *
+ * The state is module-scoped because the HMR strategy and renderer live in
+ * different call sites (server strategy vs SSR renderer) and share no other
+ * lifecycle anchor. A fresh state is installed only when the source-file set
+ * changes, so the renderer's per-render hook stays O(1) in the steady state.
+ */
+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;
+/**
+ * Updates the active render tree from one or more root components.
+ *
+ * @remarks
+ * Walks each root through `getComponentIdentity`, `config.dependencies.components[*].config`,
+ * and `config.layouts[*].config` recursively, collecting every file path. The
+ * state is replaced only when the resulting file set has a different hash, so
+ * the renderer's per-render hook is free in the steady state.
+ */
+export declare function updateEjsxHmrOwnership(components: ReadonlyArray<EcoComponent | Partial<EcoComponent> | undefined>): void;
+/**
+ * Merges one render tree into a pending ownership set during an active render.
+ */
+export declare function mergeEjsxHmrOwnership(target: Set<string>, components: ReadonlyArray<EcoComponent | undefined>): void;
+/**
+ * Publishes the merged ownership set for the completed render.
+ */
+export declare function publishEjsxHmrOwnership(files: ReadonlySet<string>): void;
+/**
+ * Resets the state to empty. Used by tests and by HMR manager teardown.
+ */
+export declare function resetEjsxHmrOwnership(): void;

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

@@ -0,0 +1,77 @@
+/**
+ * Tracks the source files that participate in the active SSR render tree.
+ *
+ * @remarks
+ * The JSX integration renderer calls {@link updateEjsxHmrOwnership} after each
+ * page, component, or view render so the HMR strategy can answer
+ * "does this changed file affect SSR HTML?" without re-walking the tree on
+ * every watcher event.
+ *
+ * The state is module-scoped because the HMR strategy and renderer live in
+ * different call sites (server strategy vs SSR renderer) and share no other
+ * lifecycle anchor. A fresh state is installed only when the source-file set
+ * changes, so the renderer's per-render hook stays O(1) in the steady state.
+ */
+import { rapidhash } from '@ecopages/core/hash';
+import { collectComponentConfigFilePaths } from '@ecopages/core/route-renderer/page-loading/file-scoped-dependency-components';
+const EMPTY_STATE = {
+    fileOwners: new Set(),
+    hash: '',
+};
+let currentState = EMPTY_STATE;
+/**
+ * Returns the most recently recorded active render tree.
+ */
+export function getEjsxHmrOwnership() {
+    return currentState;
+}
+/**
+ * Updates the active render tree from one or more root components.
+ *
+ * @remarks
+ * Walks each root through `getComponentIdentity`, `config.dependencies.components[*].config`,
+ * and `config.layouts[*].config` recursively, collecting every file path. The
+ * state is replaced only when the resulting file set has a different hash, so
+ * the renderer's per-render hook is free in the steady state.
+ */
+export function updateEjsxHmrOwnership(components) {
+    publishEjsxHmrOwnership(collectFileOwners(components));
+}
+/**
+ * Merges one render tree into a pending ownership set during an active render.
+ */
+export function mergeEjsxHmrOwnership(target, components) {
+    for (const file of collectFileOwners(components)) {
+        target.add(file);
+    }
+}
+/**
+ * Publishes the merged ownership set for the completed render.
+ */
+export function publishEjsxHmrOwnership(files) {
+    const hash = hashFileSet(files);
+    if (hash === currentState.hash) {
+        return;
+    }
+    currentState = {
+        fileOwners: new Set(files),
+        hash,
+    };
+}
+/**
+ * Resets the state to empty. Used by tests and by HMR manager teardown.
+ */
+export function resetEjsxHmrOwnership() {
+    currentState = EMPTY_STATE;
+}
+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 rapidhash(joined).toString(36);
+}

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

@@ -0,0 +1,19 @@
+import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+import type { HmrRegisteredEntrypointsContext } from '@ecopages/core/hmr/hmr-registered-entrypoints-context';
+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/hmr/hmr-strategy';
+import { isRegisteredDevTransformEntrypoint } from '@ecopages/core/hmr/hmr-entrypoint-output';
+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 (isRegisteredDevTransformEntrypoint(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

@@ -1,6 +1,7 @@
 import type { CompileOptions } from '@mdx-js/mdx';
 import type { EcoComponent, EcoComponentConfig, EcoFunctionComponent, EcoPageFile, GetMetadata } from '@ecopages/core';
 import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import { appendMdxExtensions, createMdxExtensionFilter } from '@ecopages/mdx/core';
 import type { JsxRenderable } from '@ecopages/jsx';
 import type { EcopagesJsxMdxCompileOptions, EcopagesJsxMdxOptions } from './ecopages-jsx.types.js';
 export type ResolvedMdxCompileOptions = EcopagesJsxMdxCompileOptions & Pick<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
@@ -10,10 +11,7 @@ export type EcopagesJsxMdxPageModule = EcoPageFile<{
     layout?: EcoComponent;
     getMetadata?: GetMetadata;
 }>;
-export declare const createMdxExtensionFilter: (extensions: string[], options?: {
-    allowQueryString?: boolean;
-}) => RegExp;
-export declare const appendMdxExtensions: (target: string[], mdxExtensions: string[]) => void;
+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>;

package/src/ecopages-jsx-mdx.js

@@ -1,113 +1,70 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { rapidhash } from "@ecopages/core/hash";
-import { VFile } from "vfile";
-import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
-const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-const mergePluginLists = (...lists) => {
-  const merged = lists.flatMap((list) => list ? [...list] : []);
-  return merged.length > 0 ? merged : void 0;
-};
-const createMdxExtensionFilter = (extensions, options) => {
-  const escaped = extensions.map(escapeRegex);
-  const suffix = options?.allowQueryString ? "(\\?.*)?$" : "$";
-  return new RegExp(`(${escaped.join("|")})${suffix}`);
-};
-const appendMdxExtensions = (target, mdxExtensions) => {
-  for (const ext of mdxExtensions) {
-    if (!target.includes(ext)) {
-      target.push(ext);
+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, {
+    jsxImportSource: '@ecopages/jsx',
+    defaults: {
+        format: 'detect',
+        outputFormat: 'program',
+    },
+});
+export const createMdxLoaderPlugin = (compilerOptions, extensions) => createMdxLoaderPluginCore({
+    name: 'ecopages-jsx-mdx-loader',
+    compilerOptions,
+    extensions,
+    includeSourceMap: false,
+    loader: 'js',
+});
+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' };
+            });
+        },
+    });
 };
-const resolveMdxCompilerOptions = (mdxOptions) => {
-  const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = mdxOptions;
-  const resolved = {
-    format: "detect",
-    outputFormat: "program",
-    ...compilerOptions,
-    jsxImportSource: "@ecopages/jsx",
-    jsxRuntime: "automatic",
-    development: process.env.NODE_ENV === "development"
-  };
-  const mergedRemark = mergePluginLists(compilerOptions?.remarkPlugins, remarkPlugins);
-  const mergedRehype = mergePluginLists(compilerOptions?.rehypePlugins, rehypePlugins);
-  const mergedRecma = mergePluginLists(compilerOptions?.recmaPlugins, recmaPlugins);
-  if (mergedRemark) resolved.remarkPlugins = mergedRemark;
-  if (mergedRehype) resolved.rehypePlugins = mergedRehype;
-  if (mergedRecma) resolved.recmaPlugins = mergedRecma;
-  return resolved;
+export const isMdxFile = (filePath, extensions) => {
+    return extensions.some((ext) => filePath.endsWith(ext));
 };
-const createMdxLoaderPlugin = (compilerOptions, extensions) => {
-  const filter = createMdxExtensionFilter(extensions, { allowQueryString: true });
-  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)
-        };
-      });
+export const normalizeMdxPageModule = (file, module) => {
+    if (typeof module.default !== 'function') {
+        throw new TypeError('MDX file must export a callable default component.');
     }
-  };
-};
-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" };
-      });
+    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 isMdxFile = (filePath, extensions) => {
-  return extensions.some((ext) => filePath.endsWith(ext));
-};
-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 normalizedConfig = {
-    ...module.config ?? Page.config ?? {},
-    ...module.layout ? { layout: module.layout } : {},
-    __eco: module.config?.__eco ?? Page.config?.__eco ?? {
-      id: String(rapidhash(file)),
-      file,
-      integration: ECOPAGES_JSX_PLUGIN_NAME
+    ensurePageConfigLayouts(normalizedConfig);
+    const wrappedPage = async (props) => await Page(props);
+    wrappedPage.config = normalizedConfig;
+    if (module.getMetadata ?? Page.metadata) {
+        wrappedPage.metadata = module.getMetadata ?? Page.metadata;
     }
-  };
-  const wrappedPage = async (props) => await Page(props);
-  wrappedPage.config = normalizedConfig;
-  if (module.getMetadata ?? Page.metadata) {
-    wrappedPage.metadata = module.getMetadata ?? Page.metadata;
-  }
-  return {
-    ...module,
-    default: wrappedPage,
-    config: normalizedConfig
-  };
-};
-export {
-  appendMdxExtensions,
-  createMdxExtensionFilter,
-  createMdxLoaderPlugin,
-  isMdxFile,
-  normalizeMdxPageModule,
-  registerBunMdxPlugin,
-  resolveMdxCompilerOptions
+    return {
+        ...module,
+        default: wrappedPage,
+        config: normalizedConfig,
+    };
 };

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

@@ -4,13 +4,15 @@ import { createMarkupNodeLike } from '@ecopages/jsx';
  *
  * @remarks
  * Radiant's server bridge and light-DOM shim are loaded lazily because most JSX
- * renders do not need them. Once enabled, the resolved runtime modules are
- * cached statically so repeated page and component renders do not keep paying
- * module-resolution or shim-installation costs.
+ * renders do not need them. Resolved runtime modules are cached on the policy
+ * instance so repeated renders on the same renderer reuse one load without
+ * process-wide mutable class state. Light-DOM constructor installation remains
+ * process-global and idempotent via {@link ensureRadiantLightDomGlobals}; the
+ * Radiant installer also repairs incomplete DOM globals left by another runtime.
  */
 export declare class EcopagesJsxRadiantSsrPolicy {
-    private static runtimeModules;
-    private static runtimeModulesPromise;
+    private runtimeModules;
+    private runtimeModulesPromise;
     private readonly enabled;
     constructor(enabled: boolean);
     /**