@ecopages/ecopages-jsx 0.2.0-beta.8 → 0.2.0-rc.0

package/src/ecopages-jsx-renderer.js

@@ -1,240 +1,284 @@
-import {
-  IntegrationRenderer
-} from "@ecopages/core/route-renderer/integration-renderer";
-import { createMarkupNodeLike } from "@ecopages/jsx";
-import { renderToString, withServerCustomElementRenderHook } from "@ecopages/jsx/server";
-import { ECOPAGES_JSX_PLUGIN_NAME } from "./ecopages-jsx.constants.js";
-import {
-  isMdxFile,
-  normalizeMdxPageModule
-} from "./ecopages-jsx-mdx.js";
-import { EcopagesJsxRenderSession } from "./ecopages-jsx-render-session.js";
-import { EcopagesJsxRadiantSsrPolicy } from "./ecopages-jsx-radiant-ssr-policy.js";
-class EcopagesJsxRenderer extends IntegrationRenderer {
-  name = ECOPAGES_JSX_PLUGIN_NAME;
-  mdxExtensions;
-  renderSession;
-  radiantSsrPolicy;
-  normalizeForeignChildProps(props) {
-    if (!("children" in props)) {
-      return props;
-    }
-    const children = props.children;
-    if (children === void 0 || typeof children === "string") {
-      return props;
-    }
-    if (typeof children === "object" && children !== null && "nodeType" in children && typeof children.nodeType === "number" && "outerHTML" in children && typeof children.outerHTML === "string") {
-      return {
-        ...props,
-        children: children.outerHTML
-      };
-    }
-    return {
-      ...props,
-      children: renderToString(children)
-    };
-  }
-  /**
-   * Re-renders queued JSX children inside the owning renderer so nested custom
-   * elements and queued foreign subtrees contribute assets to the same frame.
-   */
-  async renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken) {
-    if (children === void 0) {
-      return { assets: [] };
+import { IntegrationRenderer, } from '@ecopages/core/route-renderer/orchestration/integration-renderer';
+import { getForeignSubtreeResolutionContextKey, resolveOwningIntegrationRenderer, } from '@ecopages/core/route-renderer/orchestration/foreign-child/owning-renderer-resolution';
+import { createMarkupNodeLike } from '@ecopages/jsx';
+import { renderToString, withServerCustomElementRenderHook } from '@ecopages/jsx/server';
+import { ECOPAGES_JSX_PLUGIN_NAME } from './ecopages-jsx.constants.js';
+import { isMdxFile, normalizeMdxPageModule, } from './ecopages-jsx-mdx.js';
+import { EcopagesJsxRenderSession } from './ecopages-jsx-render-session.js';
+import { EcopagesJsxRadiantSsrPolicy } from './ecopages-jsx-radiant-ssr-policy.js';
+/**
+ * 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 class EcopagesJsxRenderer extends IntegrationRenderer {
+    name = ECOPAGES_JSX_PLUGIN_NAME;
+    mdxExtensions;
+    renderSession;
+    radiantSsrPolicy;
+    /**
+     * Serializes foreign-child props for string-first boundaries.
+     *
+     * @remarks
+     * DOM nodes become `outerHTML`. JSX trees, arrays, and template results are
+     * stringified here. Other values are left for core foreign-child interception,
+     * which rejects opaque plain objects before queueing. Cross-integration
+     * children must use `EcoEmbed`.
+     */
+    normalizeForeignChildProps(props) {
+        if (!('children' in props)) {
+            return props;
+        }
+        const children = props.children;
+        if (children === undefined || typeof children === 'string') {
+            return props;
+        }
+        if (typeof children === 'object' &&
+            children !== null &&
+            'nodeType' in children &&
+            typeof children.nodeType === 'number' &&
+            'outerHTML' in children &&
+            typeof children.outerHTML === 'string') {
+            return {
+                ...props,
+                children: children.outerHTML,
+            };
+        }
+        if (this.isJsxSerializableForeignChild(children)) {
+            return {
+                ...props,
+                children: renderToString(children),
+            };
+        }
+        return props;
     }
-    let assets = [];
-    let html;
-    if (typeof children === "string") {
-      html = children;
-    } else {
-      const renderedChildren = await this.renderJsx(children);
-      html = renderedChildren.html;
-      assets = renderedChildren.assets;
+    /**
+     * Returns whether children are a JSX/template shape this renderer can
+     * serialize before foreign-child queueing.
+     */
+    isJsxSerializableForeignChild(children) {
+        if (Array.isArray(children)) {
+            return true;
+        }
+        if (children === null || typeof children !== 'object') {
+            return false;
+        }
+        if ('$$typeof' in children) {
+            return true;
+        }
+        return 'strings' in children && Array.isArray(children.strings);
     }
-    html = await this.foreignSubtreeExecutionService.resolveQueuedTokens(
-      html,
-      queuedResolutionsByToken,
-      resolveToken
-    );
-    return {
-      assets,
-      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;
-    const interceptForeignChildSync = runtime.interceptForeignChildSync;
-    const wrapInput = (input) => ({
-      ...input,
-      props: input.targetIntegration && input.targetIntegration !== this.name ? this.normalizeForeignChildProps(input.props) : input.props
-    });
-    return {
-      interceptForeignChild: interceptForeignChild ? (input) => interceptForeignChild(wrapInput(input)) : void 0,
-      interceptForeignChildSync: interceptForeignChildSync ? (input) => interceptForeignChildSync(wrapInput(input)) : void 0
-    };
-  }
-  constructor({
-    appConfig,
-    assetProcessingService,
-    resolvedIntegrationDependencies,
-    jsxConfig,
-    runtimeOrigin
-  }) {
-    super({
-      appConfig,
-      assetProcessingService,
-      resolvedIntegrationDependencies,
-      runtimeOrigin
-    });
-    this.mdxExtensions = jsxConfig?.mdxExtensions ?? [".mdx"];
-    this.renderSession = new EcopagesJsxRenderSession(
-      (assets) => this.htmlTransformer.dedupeProcessedAssets(assets)
-    );
-    this.radiantSsrPolicy = jsxConfig?.radiantSsrPolicy ?? new EcopagesJsxRadiantSsrPolicy(jsxConfig?.radiantSsrEnabled ?? false);
-  }
-  /** Returns whether the requested page file should be treated as MDX. */
-  isMdxFile(filePath) {
-    return isMdxFile(filePath, this.mdxExtensions);
-  }
-  async importPageFile(file, options) {
-    return await this.withPreparedRadiantRuntime(async () => {
-      const module = await super.importPageFile(file, options);
-      return this.isMdxFile(file) ? normalizeMdxPageModule(file, module) : module;
-    });
-  }
-  async render(options) {
-    return await this.withPreparedRadiantRuntime(
-      () => this.renderSession.withActiveScope(async () => {
-        try {
-          return await this.renderPageWithDocumentShell({
-            page: {
-              component: options.Page,
-              props: {
-                ...options.pageProps,
-                locals: options.pageLocals
-              }
-            },
-            layout: options.Layout ? {
-              component: options.Layout,
-              props: {
-                ...options.pageProps,
-                locals: options.locals
-              }
-            } : void 0,
-            htmlTemplate: options.HtmlTemplate,
-            metadata: options.metadata,
-            pageProps: options.pageProps ?? {}
-          });
-        } catch (error) {
-          throw this.createRenderError("Error rendering page", error);
+    /**
+     * Re-renders queued JSX children inside the owning renderer so nested custom
+     * elements and queued foreign subtrees contribute assets to the same frame.
+     */
+    async renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken) {
+        if (children === undefined) {
+            return { assets: [] };
         }
-      })
-    );
-  }
-  async renderComponent(input) {
-    return await this.withPreparedRadiantRuntime(
-      () => this.renderSession.withActiveScope(async () => {
-        const assetFrame = this.renderSession.beginCollectedAssetFrame();
-        try {
-          if (typeof input.component !== "function") {
-            throw new TypeError("JSX renderer expected a callable component.");
-          }
-          const component = input.component;
-          const componentProps = input.children === void 0 ? input.props : {
-            ...input.props,
-            children: typeof input.children === "string" ? createMarkupNodeLike(input.children) : input.children
-          };
-          const content = await this.withCustomElementRenderHook(() => component(componentProps));
-          const rendered = await this.renderJsx(content);
-          const queuedForeignSubtreeResolution = await this.resolveOwnedForeignSubtreeHtml(
-            rendered.html,
-            this.getQueuedForeignSubtreeResolutionContext(
-              input
-            )
-          );
-          const componentAssets = input.component.config?.dependencies && typeof this.assetProcessingService?.processDependencies === "function" ? await this.processComponentDependencies([input.component]) : [];
-          const assets = this.htmlTransformer.dedupeProcessedAssets([
-            ...this.renderSession.endCollectedAssetFrame(assetFrame),
-            ...queuedForeignSubtreeResolution.assets,
-            ...componentAssets
-          ]);
-          return {
-            html: queuedForeignSubtreeResolution.html,
-            canAttachAttributes: true,
-            rootTag: this.getRootTagName(queuedForeignSubtreeResolution.html),
-            integrationName: this.name,
-            assets
-          };
-        } catch (error) {
-          this.renderSession.endCollectedAssetFrame(assetFrame);
-          throw this.createRenderError("Error rendering component", error);
+        let assets = [];
+        let html;
+        if (typeof children === 'string') {
+            html = children;
         }
-      })
-    );
-  }
-  async renderToResponse(view, props, ctx) {
-    return await this.withPreparedRadiantRuntime(
-      () => this.renderSession.withActiveScope(async () => {
-        try {
-          if (typeof view !== "function") {
-            throw new TypeError("JSX renderer expected a callable view component.");
-          }
-          const viewComponent = view;
-          return await this.renderViewWithDocumentShell({
-            view: viewComponent,
-            props,
-            ctx,
-            layout: viewComponent.config?.layout
-          });
-        } catch (error) {
-          throw this.createRenderError("Error rendering view", error);
+        else {
+            const renderedChildren = await this.renderJsx(children);
+            html = renderedChildren.html;
+            assets = renderedChildren.assets;
         }
-      })
-    );
-  }
-  async renderJsx(value) {
-    const collectedAssets = [];
-    const html = await this.withCustomElementRenderHook(() => renderToString(value));
-    const dedupedAssets = this.renderSession.recordCollectedAssets(collectedAssets);
-    return {
-      assets: dedupedAssets,
-      html
-    };
-  }
-  async withCustomElementRenderHook(render) {
-    return await this.radiantSsrPolicy.withRuntime(
-      () => withServerCustomElementRenderHook(this.createIntrinsicCustomElementRenderHook(), render)
-    );
-  }
-  async withPreparedRadiantRuntime(render) {
-    await this.radiantSsrPolicy.prepareRuntime();
-    return await render();
-  }
-  createIntrinsicCustomElementRenderHook() {
-    return ({ instance }) => {
-      return instance ? this.radiantSsrPolicy.renderIntrinsicElementMarkup(instance) : void 0;
-    };
-  }
+        html = await this.foreignSubtreeExecutionService.resolveQueuedTokens(html, queuedResolutionsByToken, resolveToken);
+        return {
+            assets,
+            html,
+        };
+    }
+    createForeignChildRuntime(options) {
+        const runtime = super.createForeignChildRuntime(options);
+        const interceptForeignChild = runtime.interceptForeignChild;
+        const interceptForeignChildSync = runtime.interceptForeignChildSync;
+        const wrapInput = (input) => ({
+            ...input,
+            props: input.targetIntegration && input.targetIntegration !== this.name
+                ? this.normalizeForeignChildProps(input.props)
+                : input.props,
+        });
+        return {
+            interceptForeignChild: interceptForeignChild
+                ? (input) => interceptForeignChild(wrapInput(input))
+                : undefined,
+            interceptForeignChildSync: interceptForeignChildSync
+                ? (input) => interceptForeignChildSync(wrapInput(input))
+                : undefined,
+        };
+    }
+    constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, jsxConfig, runtimeOrigin, }) {
+        super({
+            appConfig,
+            assetProcessingService,
+            resolvedIntegrationDependencies,
+            runtimeOrigin,
+        });
+        this.mdxExtensions = jsxConfig?.mdxExtensions ?? ['.mdx'];
+        this.renderSession = new EcopagesJsxRenderSession((assets) => this.htmlTransformer.dedupeProcessedAssets(assets));
+        this.radiantSsrPolicy =
+            jsxConfig?.radiantSsrPolicy ?? new EcopagesJsxRadiantSsrPolicy(jsxConfig?.radiantSsrEnabled ?? false);
+    }
+    /** Returns whether the requested page file should be treated as MDX. */
+    isMdxFile(filePath) {
+        return isMdxFile(filePath, this.mdxExtensions);
+    }
+    async importPageFile(file, options) {
+        return await this.withPreparedRadiantRuntime(async () => {
+            const module = (await super.importPageFile(file, options));
+            return this.isMdxFile(file) ? normalizeMdxPageModule(file, module) : module;
+        });
+    }
+    async render(options) {
+        return await this.withPreparedRadiantRuntime(async () => await this.renderSession.withActiveScope(async () => {
+            try {
+                const result = await this.renderPageWithDocumentShell({
+                    page: {
+                        component: options.Page,
+                        props: {
+                            ...options.pageProps,
+                            locals: options.pageLocals,
+                        },
+                    },
+                    layout: options.Layout
+                        ? {
+                            component: options.Layout,
+                            props: {
+                                ...options.pageProps,
+                                locals: options.locals,
+                            },
+                        }
+                        : undefined,
+                    htmlTemplate: options.HtmlTemplate,
+                    metadata: options.metadata,
+                    pageProps: options.pageProps ?? {},
+                });
+                this.recordHmrOwnership([
+                    options.Page,
+                    options.Layout,
+                    options.HtmlTemplate,
+                    ...(options.resolvedPageDependencyComponents ?? []),
+                ]);
+                return result;
+            }
+            catch (error) {
+                throw this.createRenderError('Error rendering page', error);
+            }
+        }));
+    }
+    async renderComponent(input) {
+        return await this.withPreparedRadiantRuntime(async () => await this.renderSession.withActiveScope(async () => {
+            const assetFrame = this.renderSession.beginCollectedAssetFrame();
+            try {
+                if (typeof input.component !== 'function') {
+                    throw new TypeError('JSX renderer expected a callable component.');
+                }
+                const component = input.component;
+                const componentProps = input.children === undefined
+                    ? input.props
+                    : {
+                        ...input.props,
+                        children: typeof input.children === 'string'
+                            ? createMarkupNodeLike(input.children)
+                            : input.children,
+                    };
+                const content = await this.withCustomElementRenderHook(() => component(componentProps));
+                const rendered = await this.renderJsx(content);
+                const queuedForeignSubtreeResolution = await this.foreignSubtreeExecutionService.resolveQueuedHtml({
+                    currentIntegrationName: this.name,
+                    html: rendered.html,
+                    runtimeContext: this.foreignSubtreeExecutionService.getQueuedRuntimeContext(input, getForeignSubtreeResolutionContextKey(this.name)),
+                    queueLabel: 'Ecopages JSX',
+                    getOwningRenderer: (integrationName, rendererCache) => resolveOwningIntegrationRenderer({
+                        appConfig: this.appConfig,
+                        runtimeOrigin: this.runtimeOrigin,
+                        currentIntegrationName: this.name,
+                        currentRenderer: this,
+                        integrationName,
+                        cache: rendererCache,
+                    }),
+                    applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
+                    dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+                    renderQueuedChildren: (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => this.renderQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken),
+                });
+                const componentAssets = input.component.config?.dependencies &&
+                    typeof this.assetProcessingService?.processDependencies === 'function'
+                    ? await this.processComponentDependencies([input.component])
+                    : [];
+                const assets = this.htmlTransformer.dedupeProcessedAssets([
+                    ...this.renderSession.endCollectedAssetFrame(assetFrame),
+                    ...queuedForeignSubtreeResolution.assets,
+                    ...componentAssets,
+                ]);
+                this.recordHmrOwnership([input.component]);
+                return this.finalizeIslandComponentRender(input, {
+                    html: queuedForeignSubtreeResolution.html,
+                    canAttachAttributes: true,
+                    rootTag: this.getRootTagName(queuedForeignSubtreeResolution.html),
+                    integrationName: this.name,
+                    assets,
+                });
+            }
+            catch (error) {
+                this.renderSession.endCollectedAssetFrame(assetFrame);
+                throw this.createRenderError('Error rendering component', error);
+            }
+        }));
+    }
+    async renderToResponse(view, props, ctx) {
+        return await this.withPreparedRadiantRuntime(async () => await this.renderSession.withActiveScope(async () => {
+            try {
+                if (typeof view !== 'function') {
+                    throw new TypeError('JSX renderer expected a callable view component.');
+                }
+                const viewComponent = view;
+                const layouts = viewComponent.config?.layouts;
+                const response = await this.renderViewWithDocumentShell({
+                    view: viewComponent,
+                    props: props,
+                    ctx,
+                    layout: layouts?.[layouts.length - 1],
+                });
+                this.recordHmrOwnership([view]);
+                return response;
+            }
+            catch (error) {
+                throw this.createRenderError('Error rendering view', error);
+            }
+        }));
+    }
+    async renderJsx(value) {
+        const collectedAssets = [];
+        const html = await this.withCustomElementRenderHook(() => renderToString(value));
+        const dedupedAssets = this.renderSession.recordCollectedAssets(collectedAssets);
+        return {
+            assets: dedupedAssets,
+            html,
+        };
+    }
+    async withCustomElementRenderHook(render) {
+        return await this.radiantSsrPolicy.withRuntime(() => withServerCustomElementRenderHook(this.createIntrinsicCustomElementRenderHook(), render));
+    }
+    async withPreparedRadiantRuntime(render) {
+        await this.radiantSsrPolicy.prepareRuntime();
+        return await render();
+    }
+    createIntrinsicCustomElementRenderHook() {
+        return ({ instance }) => {
+            return instance ? this.radiantSsrPolicy.renderIntrinsicElementMarkup(instance) : undefined;
+        };
+    }
+    /**
+     * 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) {
+        this.renderSession.mergeHmrOwnership(components);
+    }
 }
-export {
-  EcopagesJsxRenderer
-};

package/src/ecopages-jsx.constants.js

@@ -1,4 +1,7 @@
-const ECOPAGES_JSX_PLUGIN_NAME = "ecopages-jsx";
-export {
-  ECOPAGES_JSX_PLUGIN_NAME
-};
+/**
+ * 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 const ECOPAGES_JSX_PLUGIN_NAME = 'ecopages-jsx';

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

@@ -1,4 +1,7 @@
 import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+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 +24,20 @@ export declare class EcopagesJsxPlugin extends IntegrationPlugin<JsxRenderable>
     private getDependencies;
     /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
     prepareBuildContributions(): Promise<void>;
+    /** Assigns grouped-build metadata for page-owned JSX content scripts. */
+    prepareAssetDependencies(dependencies: AssetDefinition[]): AssetDefinition[];
+    /** Registers JSX HMR strategy, dev-transform plugins, 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.
      */