@ecopages/ecopages-jsx 0.2.0-beta.13 → 0.2.0-beta.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/ecopages-jsx",
-  "version": "0.2.0-beta.13",
+  "version": "0.2.0-beta.14",
   "description": "JSX integration plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -31,13 +31,13 @@
     "directory": "packages/integrations/ecopages-jsx"
   },
   "dependencies": {
-    "@ecopages/mdx": "0.2.0-beta.13",
+    "@ecopages/mdx": "0.2.0-beta.14",
     "@mdx-js/mdx": "^3.1.1",
     "vfile": "^6.0.3"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-beta.13",
-    "@ecopages/jsx": "0.3.0-alpha.25",
-    "@ecopages/radiant": "0.3.0-alpha.25"
+    "@ecopages/core": "0.2.0-beta.14",
+    "@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,62 @@
+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) {
+    if (this.context.getWatchedFiles().has(filePath)) {
+      return false;
+    }
+    const resolvedPath = path.resolve(filePath);
+    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.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { ensurePageConfigLayouts } from "@ecopages/core/eco/page-layout-normalization";
 import { rapidhash } from "@ecopages/core/hash";
 import {
   appendMdxExtensions,
@@ -49,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

@@ -37,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;
@@ -107,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: {
@@ -126,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);
         }
@@ -159,6 +162,7 @@ class EcopagesJsxRenderer extends IntegrationRenderer {
             ...queuedForeignSubtreeResolution.assets,
             ...componentAssets
           ]);
+          this.recordHmrOwnership([input.component]);
           return {
             html: queuedForeignSubtreeResolution.html,
             canAttachAttributes: true,
@@ -181,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);
         }
@@ -216,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,5 @@
 import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
 import type { JsxRenderable } from '@ecopages/jsx';
 import { EcopagesJsxRenderer } from './ecopages-jsx-renderer.js';
 import type { EcopagesJsxPluginOptions } from './ecopages-jsx.types.js';
@@ -21,6 +22,16 @@ export declare class EcopagesJsxPlugin extends IntegrationPlugin<JsxRenderable>
     private getDependencies;
     /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
     prepareBuildContributions(): Promise<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,7 @@ import {
   resolveMdxCompilerOptions
 } from "./ecopages-jsx-mdx.js";
 import { EcopagesJsxRenderer } from "./ecopages-jsx-renderer.js";
+import { EcopagesJsxHmrStrategy } from "./ecopages-jsx-hmr-strategy.js";
 const RADIANT_HYDRATOR_SCRIPT_ID = "ecopages-jsx-radiant-hydrator";
 const resolvePluginOptions = (options) => {
   const { extensions: userExtensions, radiant, mdx, ...baseConfig } = options ?? {};
@@ -72,7 +74,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 +86,30 @@ class EcopagesJsxPlugin extends IntegrationPlugin {
   async prepareBuildContributions() {
     this.ensureMdxLoaderPlugin();
   }
+  /**
+   * 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/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
+};