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

package/src/ecopages-jsx.plugin.js

@@ -1,120 +1,171 @@
-import {
-  IntegrationPlugin
-} 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 {
-  appendMdxExtensions,
-  createMdxLoaderPlugin,
-  registerBunMdxPlugin,
-  resolveMdxCompilerOptions
-} from "./ecopages-jsx-mdx.js";
-import { EcopagesJsxRenderer } from "./ecopages-jsx-renderer.js";
-const RADIANT_HYDRATOR_SCRIPT_ID = "ecopages-jsx-radiant-hydrator";
+import { IntegrationPlugin, } 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, registerBunMdxPlugin, resolveMdxCompilerOptions, } from './ecopages-jsx-mdx.js';
+import { EcopagesJsxRenderer } from './ecopages-jsx-renderer.js';
+import { EcopagesJsxHmrStrategy } from './ecopages-jsx-hmr-strategy.js';
+import { EcopagesJsxDevTransformContributor } from './dev-transform/ecopages-jsx-dev-transform-contributor.js';
+import { assignPageOwnedContentScriptGroupedBundles } from './page-owned-content-script-grouping.js';
+import { invalidateRadiantRegisteredScriptSsrRegistration } from './radiant-registered-script-ssr-invalidation.js';
+const RADIANT_HYDRATOR_SCRIPT_ID = 'ecopages-jsx-radiant-hydrator';
+/**
+ * Resolves user-facing plugin options into a fully-defaulted internal config.
+ *
+ * Defaults:
+ * - `extensions`: `['.tsx']`
+ * - `radiant`: `true`
+ * - `mdx.enabled`: `false`
+ * - `mdx.extensions`: `['.mdx']`
+ */
 const resolvePluginOptions = (options) => {
-  const { extensions: userExtensions, radiant, mdx, ...baseConfig } = options ?? {};
-  const extensions = [...userExtensions ?? [".tsx"]];
-  const mdxExtensions = mdx?.extensions ?? [".mdx"];
-  const mdxEnabled = mdx?.enabled ?? false;
-  if (mdxEnabled) {
-    appendMdxExtensions(extensions, mdxExtensions);
-  }
-  return {
-    ...baseConfig,
-    extensions,
-    includeRadiant: radiant ?? true,
-    mdxEnabled,
-    mdxExtensions,
-    mdxCompilerOptions: mdxEnabled && mdx ? resolveMdxCompilerOptions(mdx) : void 0
-  };
+    const { extensions: userExtensions, radiant, mdx, ...baseConfig } = options ?? {};
+    const extensions = [...(userExtensions ?? ['.tsx'])];
+    const mdxExtensions = mdx?.extensions ?? ['.mdx'];
+    const mdxEnabled = mdx?.enabled ?? false;
+    if (mdxEnabled) {
+        appendMdxExtensions(extensions, mdxExtensions);
+    }
+    return {
+        ...baseConfig,
+        extensions,
+        includeRadiant: radiant ?? true,
+        mdxEnabled,
+        mdxExtensions,
+        mdxCompilerOptions: mdxEnabled && mdx ? resolveMdxCompilerOptions(mdx) : undefined,
+    };
 };
-class EcopagesJsxPlugin extends IntegrationPlugin {
-  renderer = EcopagesJsxRenderer;
-  includeRadiant;
-  mdxEnabled;
-  mdxCompilerOptions;
-  mdxExtensions;
-  mdxLoaderPlugin;
-  /** Returns the build plugins required by the JSX integration. */
-  get plugins() {
-    return [this.mdxLoaderPlugin].filter((plugin) => plugin !== void 0);
-  }
-  /** Creates the renderer instance with the resolved JSX integration runtime options. */
-  initializeRenderer(options) {
-    return this.attachRendererRuntimeServices(
-      new this.renderer({
-        ...this.createRendererOptions(options),
-        jsxConfig: {
-          mdxExtensions: this.mdxExtensions,
-          radiantSsrEnabled: this.includeRadiant
+/** JSX integration plugin for Ecopages, supporting `.tsx` templates and optional Radiant web components. */
+export class EcopagesJsxPlugin extends IntegrationPlugin {
+    renderer = EcopagesJsxRenderer;
+    includeRadiant;
+    mdxEnabled;
+    mdxCompilerOptions;
+    mdxExtensions;
+    mdxLoaderPlugin;
+    /** Returns the build plugins required by the JSX integration. */
+    get plugins() {
+        return [this.mdxLoaderPlugin].filter((plugin) => plugin !== undefined);
+    }
+    /** Creates the renderer instance with the resolved JSX integration runtime options. */
+    initializeRenderer(options) {
+        return this.attachRendererRuntimeServices(new this.renderer({
+            ...this.createRendererOptions(options),
+            jsxConfig: {
+                mdxExtensions: this.mdxExtensions,
+                radiantSsrEnabled: this.includeRadiant,
+            },
+        }));
+    }
+    constructor(options) {
+        const config = resolvePluginOptions(options);
+        const { extensions, includeRadiant, mdxEnabled, mdxExtensions, mdxCompilerOptions, ...baseConfig } = config;
+        super({
+            name: ECOPAGES_JSX_PLUGIN_NAME,
+            extensions,
+            jsxImportSource: '@ecopages/jsx',
+            ...baseConfig,
+        });
+        this.includeRadiant = includeRadiant;
+        this.mdxEnabled = mdxEnabled;
+        this.mdxExtensions = mdxExtensions;
+        this.mdxCompilerOptions = mdxCompilerOptions;
+        if (this.includeRadiant) {
+            this.integrationDependencies.unshift(...this.getDependencies());
+        }
+    }
+    getDependencies() {
+        return [
+            AssetFactory.createNodeModuleScript({
+                position: 'head',
+                importPath: RADIANT_INSTALL_HYDRATOR_FILEPATH,
+                bundle: false,
+                attributes: {
+                    'data-eco-script-id': RADIANT_HYDRATOR_SCRIPT_ID,
+                },
+            }),
+        ];
+    }
+    /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
+    async prepareBuildContributions() {
+        this.ensureMdxLoaderPlugin();
+    }
+    /** Assigns grouped-build metadata for page-owned JSX content scripts. */
+    prepareAssetDependencies(dependencies) {
+        return assignPageOwnedContentScriptGroupedBundles(dependencies);
+    }
+    /** Registers JSX HMR strategy, dev-transform plugins, and Radiant SSR invalidation hooks. */
+    setHmrManager(hmrManager) {
+        super.setHmrManager(hmrManager);
+        const strategy = this.getHmrStrategy();
+        if (strategy) {
+            hmrManager.registerDevTransformContributor(new EcopagesJsxDevTransformContributor({
+                strategy: strategy,
+                getMdxLoaderPlugin: () => this.mdxLoaderPlugin,
+            }));
+        }
+        if (!this.includeRadiant || !this.appConfig) {
+            return;
         }
-      })
-    );
-  }
-  constructor(options) {
-    const config = resolvePluginOptions(options);
-    const { extensions, includeRadiant, mdxEnabled, mdxExtensions, mdxCompilerOptions, ...baseConfig } = config;
-    super({
-      name: ECOPAGES_JSX_PLUGIN_NAME,
-      extensions,
-      jsxImportSource: "@ecopages/jsx",
-      ...baseConfig
-    });
-    this.includeRadiant = includeRadiant;
-    this.mdxEnabled = mdxEnabled;
-    this.mdxExtensions = mdxExtensions;
-    this.mdxCompilerOptions = mdxCompilerOptions;
-    if (this.includeRadiant) {
-      this.integrationDependencies.unshift(...this.getDependencies());
+        const runtime = this.appConfig.runtime ?? {};
+        this.appConfig.runtime = runtime;
+        runtime.registeredScriptEntrypointChangeHandlers ??= [];
+        runtime.registeredScriptEntrypointChangeHandlers.push(invalidateRadiantRegisteredScriptSsrRegistration);
     }
-  }
-  getDependencies() {
-    return [
-      AssetFactory.createNodeModuleScript({
-        position: "head",
-        importPath: "@ecopages/radiant/client/install-hydrator",
-        bundle: false,
-        attributes: {
-          "data-eco-script-id": RADIANT_HYDRATOR_SCRIPT_ID
+    /**
+     * 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 undefined;
         }
-      })
-    ];
-  }
-  /** Ensures MDX build hooks are ready before Ecopages collects contributions. */
-  async prepareBuildContributions() {
-    this.ensureMdxLoaderPlugin();
-  }
-  /**
-   * Registers MDX tooling and completes the base integration setup.
-   */
-  async setup() {
-    this.ensureMdxLoaderPlugin();
-    if (typeof Bun !== "undefined" && this.mdxEnabled && this.mdxCompilerOptions) {
-      await this.registerMdxBunPlugin();
+        const context = this.hmrManager.getDefaultContext();
+        const absolutePaths = this.appConfig.absolutePaths;
+        return new EcopagesJsxHmrStrategy({
+            getRegisteredEntrypoints: context.getRegisteredEntrypoints,
+            getSrcDir: context.getSrcDir,
+            getPagesDir: context.getPagesDir,
+            getLayoutsDir: context.getLayoutsDir,
+            getIncludesDir: () => absolutePaths.includesDir,
+            getTemplateExtensions: () => this.extensions,
+        });
     }
-    await super.setup();
-  }
-  ensureMdxLoaderPlugin() {
-    if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
-      return;
+    /**
+     * Registers MDX tooling and completes the base integration setup.
+     */
+    async setup() {
+        this.ensureMdxLoaderPlugin();
+        if (typeof Bun !== 'undefined' && this.mdxEnabled && this.mdxCompilerOptions) {
+            await this.registerMdxBunPlugin();
+        }
+        await super.setup();
     }
-    this.mdxLoaderPlugin = createMdxLoaderPlugin(this.mdxCompilerOptions, this.mdxExtensions);
-  }
-  /**
-   * Registers Bun's MDX loader at runtime setup time.
-   *
-   * Build-time contribution collection may run where Bun is absent, so
-   * this hook stays isolated from manifest preparation.
-   */
-  async registerMdxBunPlugin() {
-    if (typeof Bun === "undefined" || !this.mdxCompilerOptions) {
-      return;
+    ensureMdxLoaderPlugin() {
+        if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
+            return;
+        }
+        this.mdxLoaderPlugin = createMdxLoaderPlugin(this.mdxCompilerOptions, this.mdxExtensions);
+    }
+    /**
+     * Registers Bun's MDX loader at runtime setup time.
+     *
+     * Build-time contribution collection may run where Bun is absent, so
+     * this hook stays isolated from manifest preparation.
+     */
+    async registerMdxBunPlugin() {
+        if (typeof Bun === 'undefined' || !this.mdxCompilerOptions) {
+            return;
+        }
+        await registerBunMdxPlugin(this.mdxCompilerOptions, this.mdxExtensions);
     }
-    await registerBunMdxPlugin(this.mdxCompilerOptions, this.mdxExtensions);
-  }
 }
-const ecopagesJsxPlugin = (options) => new EcopagesJsxPlugin(options);
-export {
-  EcopagesJsxPlugin,
-  ecopagesJsxPlugin
-};
+/**
+ * Creates the JSX integration plugin with resolved defaults.
+ */
+export const ecopagesJsxPlugin = (options) => new EcopagesJsxPlugin(options);

package/src/ecopages-jsx.types.js

@@ -0,0 +1 @@
+export {};

package/src/page-owned-content-script-grouping.d.ts

@@ -0,0 +1,12 @@
+import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+/** Returns the stable grouped-build id for one integration's page-owned content scripts. */
+export declare function createPageOwnedContentScriptBundleId(integrationName: string): string;
+/**
+ * Tags page-owned content scripts in one dependency batch with a shared grouped-build id.
+ *
+ * @remarks
+ * Lazy hydration entries (`excludeFromHtml`), component file scripts, and integration runtime
+ * assets stay ungrouped. Integrations that already assign a grouped id (for example React
+ * Router pages) are left unchanged.
+ */
+export declare function assignPageOwnedContentScriptGroupedBundles(dependencies: AssetDefinition[]): AssetDefinition[];

package/src/page-owned-content-script-grouping.js

@@ -0,0 +1,63 @@
+import { rapidhash } from '@ecopages/core/utils/hash';
+import { ECOPAGES_JSX_PLUGIN_NAME } from './ecopages-jsx.constants.js';
+/** Shared grouped-build id prefix for page-owned content scripts. */
+const PAGE_OWNED_CONTENT_SCRIPT_BUNDLE_PREFIX = 'ecopages';
+/** Returns the stable grouped-build id for one integration's page-owned content scripts. */
+export function createPageOwnedContentScriptBundleId(integrationName) {
+    return `${PAGE_OWNED_CONTENT_SCRIPT_BUNDLE_PREFIX}-${integrationName}-page-content-scripts`;
+}
+function isPageOwnedGroupableContentScript(dep) {
+    if (dep.kind !== 'script' || dep.source !== 'content' || dep.inline) {
+        return false;
+    }
+    if (dep.excludeFromHtml) {
+        return false;
+    }
+    if (dep.groupedBundle?.id) {
+        return false;
+    }
+    if (dep.packageRole === 'keep-separate' || dep.packageRole === 'runtime' || dep.packageRole === 'dynamic-chunk') {
+        return false;
+    }
+    return true;
+}
+function createPageOwnedGroupedEntryName(dep, usedEntryNames) {
+    const baseName = dep.name ?? `script-${rapidhash(dep.content).toString(16)}`;
+    if (!usedEntryNames.has(baseName)) {
+        usedEntryNames.add(baseName);
+        return baseName;
+    }
+    let suffix = 2;
+    let candidate = `${baseName}-${suffix}`;
+    while (usedEntryNames.has(candidate)) {
+        suffix += 1;
+        candidate = `${baseName}-${suffix}`;
+    }
+    usedEntryNames.add(candidate);
+    return candidate;
+}
+/**
+ * Tags page-owned content scripts in one dependency batch with a shared grouped-build id.
+ *
+ * @remarks
+ * Lazy hydration entries (`excludeFromHtml`), component file scripts, and integration runtime
+ * assets stay ungrouped. Integrations that already assign a grouped id (for example React
+ * Router pages) are left unchanged.
+ */
+export function assignPageOwnedContentScriptGroupedBundles(dependencies) {
+    const bundleId = createPageOwnedContentScriptBundleId(ECOPAGES_JSX_PLUGIN_NAME);
+    const usedEntryNames = new Set();
+    for (const dependency of dependencies) {
+        if (!isPageOwnedGroupableContentScript(dependency)) {
+            continue;
+        }
+        dependency.groupedBundle = {
+            id: bundleId,
+            entryName: createPageOwnedGroupedEntryName(dependency, usedEntryNames),
+        };
+        if (dependency.bundle === false) {
+            dependency.bundle = true;
+        }
+    }
+    return dependencies;
+}

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): boolean;

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

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from 'node:fs';
+const CUSTOM_ELEMENT_TAG_PATTERN = /@customElement\s*\(\s*['"`]([^'"`]+)['"`]/u;
+/**
+ * Reads the custom-element tag name from a registered script module source file.
+ */
+export function resolveRadiantCustomElementTag(scriptPath) {
+    if (!existsSync(scriptPath)) {
+        return undefined;
+    }
+    const content = readFileSync(scriptPath, 'utf8');
+    const match = content.match(CUSTOM_ELEMENT_TAG_PATTERN);
+    return match?.[1];
+}
+/**
+ * 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 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);
+    }
+}
+/**
+ * Clears the SSR custom-element registry entry for one registered Radiant script module.
+ */
+export function invalidateRadiantRegisteredScriptSsrRegistration(scriptPath) {
+    const tagName = resolveRadiantCustomElementTag(scriptPath);
+    if (!tagName) {
+        return false;
+    }
+    clearRadiantCustomElementDefinition(tagName);
+    return true;
+}

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,3 @@
+import { fileURLToPath } from 'node:url';
+/** Absolute path to `@ecopages/radiant/client/install-hydrator` from this integration package. */
+export const RADIANT_INSTALL_HYDRATOR_FILEPATH = fileURLToPath(import.meta.resolve('@ecopages/radiant/client/install-hydrator'));