@ecopages/ecopages-jsx 0.2.0-beta.2 → 0.2.0-beta.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/ecopages-jsx",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.21",
   "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.21",
     "@mdx-js/mdx": "^3.1.1",
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-beta.2",
-    "@ecopages/jsx": "0.3.0-alpha.25",
-    "@ecopages/radiant": "0.3.0-alpha.25"
+    "@ecopages/core": "0.2.0-beta.21",
+    "@ecopages/jsx": "0.3.0-beta.0",
+    "@ecopages/radiant": "0.3.0-beta.0"
   }
 }

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

@@ -0,0 +1,37 @@
+/**
+ * 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's `config.__eco.file`, `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 | undefined>): 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,63 @@
+import path from "node:path";
+import { rapidhash } from "@ecopages/core/hash";
+const EMPTY_STATE = {
+  fileOwners: /* @__PURE__ */ new Set(),
+  hash: ""
+};
+let currentState = EMPTY_STATE;
+function getEjsxHmrOwnership() {
+  return currentState;
+}
+function updateEjsxHmrOwnership(components) {
+  const files = collectFileOwners(components);
+  const hash = hashFileSet(files);
+  if (hash === currentState.hash) {
+    return;
+  }
+  currentState = {
+    fileOwners: files,
+    hash
+  };
+}
+function resetEjsxHmrOwnership() {
+  currentState = EMPTY_STATE;
+}
+function collectFileOwners(components) {
+  const files = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (config) => {
+    const file = config?.__eco?.file;
+    if (!file) {
+      return;
+    }
+    const resolved = path.resolve(file);
+    if (visited.has(resolved)) {
+      return;
+    }
+    visited.add(resolved);
+    files.add(resolved);
+    for (const dependency of config?.dependencies?.components ?? []) {
+      visit(dependency?.config);
+    }
+    for (const layout of config?.layouts ?? []) {
+      visit(layout?.config);
+    }
+  };
+  for (const component of components) {
+    visit(component?.config);
+  }
+  return files;
+}
+function hashFileSet(files) {
+  if (files.size === 0) {
+    return "";
+  }
+  const sorted = Array.from(files).sort();
+  const joined = sorted.join("\n");
+  return rapidhash(joined).toString(36);
+}
+export {
+  getEjsxHmrOwnership,
+  resetEjsxHmrOwnership,
+  updateEjsxHmrOwnership
+};

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

@@ -0,0 +1,36 @@
+/**
+ * HMR strategy for JSX integration-owned SSR source modules.
+ *
+ * @remarks
+ * Edits to files that produce SSR HTML (page sources, layout sources, components
+ * that the active render tree depends on) need a soft page refetch so the
+ * browser picks up the new markup. Plain `update` events re-import modules on
+ * the client but leave the server-rendered DOM stale.
+ *
+ * The strategy matches a file when any of these hold:
+ * - the file lives under `pagesDir` or `layoutsDir` and has a JSX `templatesExt`
+ * - the file appears in the active render tree's component dependency graph
+ *
+ * It defers registered HMR entrypoints to {@link JsHmrStrategy} so script-only
+ * edits keep their existing `update`-then-hot-accept path. It also defers
+ * include templates and explicit server views to {@link ServerRenderedTemplateHmrStrategy}
+ * by returning `false` for those paths.
+ */
+import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
+export interface EcopagesJsxHmrStrategyContext {
+    getWatchedFiles(): Map<string, string>;
+    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;
+    process(filePath: string): Promise<HmrAction>;
+    private isPageOrLayoutSource;
+    private hasJsxTemplateExtension;
+}

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

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
+import { getEjsxHmrOwnership } from "./ecopages-jsx-hmr-ownership.js";
+class EcopagesJsxHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.INTEGRATION;
+  context;
+  constructor(context) {
+    super();
+    this.context = context;
+  }
+  matches(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    const watchedFiles = this.context.getWatchedFiles();
+    if (watchedFiles.has(resolvedPath) || [...watchedFiles.keys()].some((key) => path.resolve(key) === 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;
+  }
+  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));
+  }
+}
+export {
+  EcopagesJsxHmrStrategy
+};

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,62 +1,28 @@
 import { readFile } from "node:fs/promises";
-import path from "node:path";
+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";
-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);
-    }
-  }
-};
-const resolveMdxCompilerOptions = (mdxOptions) => {
-  const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = mdxOptions;
-  const resolved = {
+const resolveMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptionsCore(mdxOptions, {
+  jsxImportSource: "@ecopages/jsx",
+  defaults: {
     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;
-};
-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)
-        };
-      });
-    }
-  };
-};
+    outputFormat: "program"
+  }
+});
+const createMdxLoaderPlugin = (compilerOptions, extensions) => createMdxLoaderPluginCore({
+  name: "ecopages-jsx-mdx-loader",
+  compilerOptions,
+  extensions,
+  includeSourceMap: false,
+  loader: "js"
+});
 const registerBunMdxPlugin = async (compilerOptions, extensions) => {
   if (typeof Bun === "undefined") {
     return;
@@ -84,13 +50,16 @@ const normalizeMdxPageModule = (file, module) => {
   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
     }
   };
+  if (module.layout && !(normalizedConfig.layouts && normalizedConfig.layouts.length > 0)) {
+    normalizedConfig.layout = module.layout;
+  }
+  ensurePageConfigLayouts(normalizedConfig);
   const wrappedPage = async (props) => await Page(props);
   wrappedPage.config = normalizedConfig;
   if (module.getMetadata ?? Page.metadata) {

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

@@ -57,10 +57,10 @@ class EcopagesJsxRadiantSsrPolicy {
         "./radiant-element-ssr-bridge.js",
         radiantLightDomShimEntry
       ).href;
-      EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise = Promise.all([
-        import(radiantElementSsrRuntimeModuleUrl),
-        import(radiantLightDomShimEntry)
-      ]).then(([radiantElementSsrRuntimeModule, lightDomShimModule2]) => {
+      EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise = (async () => {
+        const lightDomShimModule2 = await import(radiantLightDomShimEntry);
+        ensureRadiantLightDomGlobals(lightDomShimModule2.installLightDomShim);
+        const radiantElementSsrRuntimeModule = await import(radiantElementSsrRuntimeModuleUrl);
         const modules = {
           installLightDomShim: lightDomShimModule2.installLightDomShim,
           resolveRadiantElementRenderBridge: radiantElementSsrRuntimeModule.resolveRadiantElementRenderBridge,
@@ -68,11 +68,37 @@ class EcopagesJsxRadiantSsrPolicy {
         };
         EcopagesJsxRadiantSsrPolicy.runtimeModules = modules;
         return modules;
-      });
+      })();
     }
-    const lightDomShimModule = await EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise;
-    lightDomShimModule.installLightDomShim();
+    await EcopagesJsxRadiantSsrPolicy.runtimeModulesPromise;
+    const lightDomShimModule = EcopagesJsxRadiantSsrPolicy.runtimeModules;
+    if (lightDomShimModule) {
+      ensureRadiantLightDomGlobals(lightDomShimModule.installLightDomShim);
+    }
+  }
+}
+function ensureRadiantLightDomGlobals(installLightDomShim) {
+  if (typeof globalThis.HTMLElement !== "undefined") {
+    return;
+  }
+  const window = installLightDomShim();
+  if (!window) {
+    return;
   }
+  Object.assign(globalThis, {
+    CSS: window.CSS,
+    CustomEvent: window.CustomEvent,
+    Document: window.Document,
+    Element: window.Element,
+    Event: window.Event,
+    EventTarget: window.EventTarget,
+    HTMLScriptElement: window.HTMLScriptElement,
+    HTMLElement: window.HTMLElement,
+    Node: window.Node,
+    document: window.document,
+    customElements: window.customElements,
+    window
+  });
 }
 export {
   EcopagesJsxRadiantSsrPolicy

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

@@ -22,13 +22,6 @@ export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderab
      * elements and queued foreign subtrees contribute assets to the same frame.
      */
     private renderQueuedForeignSubtreeChildren;
-    /**
-     * Resolves queued foreign subtrees after JSX has been stringified.
-     *
-     * JSX content needs one extra render pass because child foreign subtrees may emit
-     * additional browser assets while also replacing placeholder tokens.
-     */
-    private resolveOwnedForeignSubtreeHtml;
     protected createForeignChildRuntime(options: {
         renderInput: ComponentRenderInput;
         rendererCache: Map<string, IntegrationRenderer<any>>;
@@ -44,4 +37,10 @@ export declare class EcopagesJsxRenderer extends IntegrationRenderer<JsxRenderab
     private withCustomElementRenderHook;
     private withPreparedRadiantRuntime;
     private createIntrinsicCustomElementRenderHook;
+    /**
+     * Records the source files that produced the current render so
+     * {@link EcopagesJsxHmrStrategy} can match later watcher events without
+     * re-walking the component tree.
+     */
+    private recordHmrOwnership;
 }

package/src/ecopages-jsx-renderer.js

@@ -10,6 +10,7 @@ import {
 } from "./ecopages-jsx-mdx.js";
 import { EcopagesJsxRenderSession } from "./ecopages-jsx-render-session.js";
 import { EcopagesJsxRadiantSsrPolicy } from "./ecopages-jsx-radiant-ssr-policy.js";
+import { updateEjsxHmrOwnership } from "./ecopages-jsx-hmr-ownership.js";
 class EcopagesJsxRenderer extends IntegrationRenderer {
   name = ECOPAGES_JSX_PLUGIN_NAME;
   mdxExtensions;
@@ -61,24 +62,6 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
       html
     };
   }
-  /**
-   * Resolves queued foreign subtrees after JSX has been stringified.
-   *
-   * JSX content needs one extra render pass because child foreign subtrees may emit
-   * additional browser assets while also replacing placeholder tokens.
-   */
-  async resolveOwnedForeignSubtreeHtml(html, runtimeContext) {
-    return this.foreignSubtreeExecutionService.resolveQueuedHtml({
-      currentIntegrationName: this.name,
-      html,
-      runtimeContext,
-      queueLabel: "Ecopages JSX",
-      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache),
-      applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
-      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
-      renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => this.renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken)
-    });
-  }
   createForeignChildRuntime(options) {
     const runtime = super.createForeignChildRuntime(options);
     const interceptForeignChild = runtime.interceptForeignChild;
@@ -125,7 +108,7 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
     return await this.withPreparedRadiantRuntime(
       () => this.renderSession.withActiveScope(async () => {
         try {
-          return await this.renderPageWithDocumentShell({
+          const result = await this.renderPageWithDocumentShell({
             page: {
               component: options.Page,
               props: {
@@ -144,6 +127,8 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
             metadata: options.metadata,
             pageProps: options.pageProps ?? {}
           });
+          this.recordHmrOwnership([options.Page, options.Layout, options.HtmlTemplate]);
+          return result;
         } catch (error) {
           throw this.createRenderError("Error rendering page", error);
         }
@@ -165,11 +150,11 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
           };
           const content = await this.withCustomElementRenderHook(() => component(componentProps));
           const rendered = await this.renderJsx(content);
-          const queuedForeignSubtreeResolution = await this.resolveOwnedForeignSubtreeHtml(
+          const queuedForeignSubtreeResolution = await this.resolveQueuedForeignSubtreeHtml(
             rendered.html,
-            this.getQueuedForeignSubtreeResolutionContext(
-              input
-            )
+            this.getQueuedForeignSubtreeResolutionContext(input),
+            (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => this.renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken),
+            "Ecopages JSX"
           );
           const componentAssets = input.component.config?.dependencies && typeof this.assetProcessingService?.processDependencies === "function" ? await this.processComponentDependencies([input.component]) : [];
           const assets = this.htmlTransformer.dedupeProcessedAssets([
@@ -177,6 +162,7 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
             ...queuedForeignSubtreeResolution.assets,
             ...componentAssets
           ]);
+          this.recordHmrOwnership([input.component]);
           return {
             html: queuedForeignSubtreeResolution.html,
             canAttachAttributes: true,
@@ -199,12 +185,15 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
             throw new TypeError("JSX renderer expected a callable view component.");
           }
           const viewComponent = view;
-          return await this.renderViewWithDocumentShell({
+          const layouts = viewComponent.config?.layouts;
+          const response = await this.renderViewWithDocumentShell({
             view: viewComponent,
             props,
             ctx,
-            layout: viewComponent.config?.layout
+            layout: layouts?.[layouts.length - 1]
           });
+          this.recordHmrOwnership([view]);
+          return response;
         } catch (error) {
           throw this.createRenderError("Error rendering view", error);
         }
@@ -234,6 +223,14 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
       return instance ? this.radiantSsrPolicy.renderIntrinsicElementMarkup(instance) : void 0;
     };
   }
+  /**
+   * Records the source files that produced the current render so
+   * {@link EcopagesJsxHmrStrategy} can match later watcher events without
+   * re-walking the component tree.
+   */
+  recordHmrOwnership(components) {
+    updateEjsxHmrOwnership(components);
+  }
 }
 export {
   EcopagesJsxRenderer

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

@@ -1,4 +1,6 @@
 import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
+import type { IHmrManager } from '@ecopages/core';
 import type { JsxRenderable } from '@ecopages/jsx';
 import { EcopagesJsxRenderer } from './ecopages-jsx-renderer.js';
 import type { EcopagesJsxPluginOptions } from './ecopages-jsx.types.js';
@@ -21,6 +23,18 @@ export declare class EcopagesJsxPlugin extends IntegrationPlugin<JsxRenderable>
     private getDependencies;
     /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
     prepareBuildContributions(): Promise<void>;
+    /** Registers JSX HMR strategy and Radiant SSR invalidation hooks. */
+    setHmrManager(hmrManager: IHmrManager): void;
+    /**
+     * Returns the JSX-integration HMR strategy.
+     *
+     * @remarks
+     * The strategy handles `layout-update` broadcasts for page sources, layout
+     * sources, and any component file in the active render tree. It defers
+     * registered script entrypoints to the generic JS strategy and includes /
+     * explicit server views to `ServerRenderedTemplateHmrStrategy`.
+     */
+    getHmrStrategy(): HmrStrategy | undefined;
     /**
      * Registers MDX tooling and completes the base integration setup.
      */

package/src/ecopages-jsx.plugin.js

@@ -3,6 +3,7 @@ import {
 } from "@ecopages/core/plugins/integration-plugin";
 import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
 import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
+import { RADIANT_INSTALL_HYDRATOR_FILEPATH } from "./resolve-radiant-install-hydrator.js";
 import {
   appendMdxExtensions,
   createMdxLoaderPlugin,
@@ -10,6 +11,8 @@ import {
   resolveMdxCompilerOptions
 } from "./ecopages-jsx-mdx.js";
 import { EcopagesJsxRenderer } from "./ecopages-jsx-renderer.js";
+import { EcopagesJsxHmrStrategy } from "./ecopages-jsx-hmr-strategy.js";
+import { invalidateRadiantRegisteredScriptSsrRegistration } from "./radiant-registered-script-ssr-invalidation.js";
 const RADIANT_HYDRATOR_SCRIPT_ID = "ecopages-jsx-radiant-hydrator";
 const resolvePluginOptions = (options) => {
   const { extensions: userExtensions, radiant, mdx, ...baseConfig } = options ?? {};
@@ -72,7 +75,7 @@ class EcopagesJsxPlugin extends IntegrationPlugin {
     return [
       AssetFactory.createNodeModuleScript({
         position: "head",
-        importPath: "@ecopages/radiant/client/install-hydrator",
+        importPath: RADIANT_INSTALL_HYDRATOR_FILEPATH,
         bundle: false,
         attributes: {
           "data-eco-script-id": RADIANT_HYDRATOR_SCRIPT_ID
@@ -84,6 +87,41 @@ class EcopagesJsxPlugin extends IntegrationPlugin {
   async prepareBuildContributions() {
     this.ensureMdxLoaderPlugin();
   }
+  /** Registers JSX HMR strategy and Radiant SSR invalidation hooks. */
+  setHmrManager(hmrManager) {
+    super.setHmrManager(hmrManager);
+    if (!this.includeRadiant || !this.appConfig) {
+      return;
+    }
+    const runtime = this.appConfig.runtime ?? {};
+    this.appConfig.runtime = runtime;
+    runtime.registeredScriptEntrypointChangeHandlers ??= [];
+    runtime.registeredScriptEntrypointChangeHandlers.push(invalidateRadiantRegisteredScriptSsrRegistration);
+  }
+  /**
+   * Returns the JSX-integration HMR strategy.
+   *
+   * @remarks
+   * The strategy handles `layout-update` broadcasts for page sources, layout
+   * sources, and any component file in the active render tree. It defers
+   * registered script entrypoints to the generic JS strategy and includes /
+   * explicit server views to `ServerRenderedTemplateHmrStrategy`.
+   */
+  getHmrStrategy() {
+    if (!this.hmrManager || !this.appConfig) {
+      return void 0;
+    }
+    const context = this.hmrManager.getDefaultContext();
+    const absolutePaths = this.appConfig.absolutePaths;
+    return new EcopagesJsxHmrStrategy({
+      getWatchedFiles: context.getWatchedFiles,
+      getSrcDir: context.getSrcDir,
+      getPagesDir: context.getPagesDir,
+      getLayoutsDir: context.getLayoutsDir,
+      getIncludesDir: () => absolutePaths.includesDir,
+      getTemplateExtensions: () => this.extensions
+    });
+  }
   /**
    * Registers MDX tooling and completes the base integration setup.
    */

package/src/radiant-registered-script-ssr-invalidation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reads the custom-element tag name from a registered script module source file.
+ */
+export declare function resolveRadiantCustomElementTag(scriptPath: string): string | undefined;
+/**
+ * Removes one custom-element definition from the active runtime registry.
+ *
+ * @remarks
+ * Radiant's `@customElement` decorator and the SSR light-DOM shim both skip
+ * re-registration when a tag is already defined. During dev, server requests
+ * reuse the same process-global registry, so script edits would otherwise keep
+ * serving stale SSR markup until a full dev-server restart.
+ */
+export declare function clearRadiantCustomElementDefinition(tagName: string): void;
+/**
+ * Clears the SSR custom-element registry entry for one registered Radiant script module.
+ */
+export declare function invalidateRadiantRegisteredScriptSsrRegistration(scriptPath: string): void;

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

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from "node:fs";
+const CUSTOM_ELEMENT_TAG_PATTERN = /@customElement\s*\(\s*['"`]([^'"`]+)['"`]/u;
+function resolveRadiantCustomElementTag(scriptPath) {
+  if (!existsSync(scriptPath)) {
+    return void 0;
+  }
+  const content = readFileSync(scriptPath, "utf8");
+  const match = content.match(CUSTOM_ELEMENT_TAG_PATTERN);
+  return match?.[1];
+}
+function clearRadiantCustomElementDefinition(tagName) {
+  const registry = globalThis.customElements;
+  if (!registry) {
+    return;
+  }
+  if (typeof registry.delete === "function") {
+    registry.delete(tagName);
+    return;
+  }
+  const definitions = registry.definitions;
+  if (definitions instanceof Map && definitions.has(tagName)) {
+    definitions.delete(tagName);
+  }
+}
+function invalidateRadiantRegisteredScriptSsrRegistration(scriptPath) {
+  const tagName = resolveRadiantCustomElementTag(scriptPath);
+  if (!tagName) {
+    return;
+  }
+  clearRadiantCustomElementDefinition(tagName);
+}
+export {
+  clearRadiantCustomElementDefinition,
+  invalidateRadiantRegisteredScriptSsrRegistration,
+  resolveRadiantCustomElementTag
+};

package/src/resolve-radiant-install-hydrator.d.ts

@@ -0,0 +1,2 @@
+/** Absolute path to `@ecopages/radiant/client/install-hydrator` from this integration package. */
+export declare const RADIANT_INSTALL_HYDRATOR_FILEPATH: string;

package/src/resolve-radiant-install-hydrator.js

@@ -0,0 +1,7 @@
+import { fileURLToPath } from "node:url";
+const RADIANT_INSTALL_HYDRATOR_FILEPATH = fileURLToPath(
+  import.meta.resolve("@ecopages/radiant/client/install-hydrator")
+);
+export {
+  RADIANT_INSTALL_HYDRATOR_FILEPATH
+};