@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.20

package/src/hmr/hmr-entrypoint-output.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns whether a source path is a registered client script HMR entrypoint.
+ *
+ * @remarks
+ * Registration comes from `dependencies.scripts` via `FileScriptProcessor`,
+ * not from filename conventions such as `.script.tsx`.
+ */
+export declare function isRegisteredScriptEntrypoint(watchedFiles: ReadonlyMap<string, string>, filePath: string): boolean;
+export declare function encodeHmrDynamicSegments(filepath: string): string;
+/**
+ * Resolves the on-disk and browser URL targets for one HMR script entrypoint.
+ */
+export declare function resolveHmrEntrypointOutputPaths(srcDir: string, distDir: string, entrypointPath: string): {
+    outputPath: string;
+    outputUrl: string;
+};
+/**
+ * @remarks
+ * Rebuilds must delete the previous artifact so browser-hmr does not reuse a
+ * stale bundle when the source file changed.
+ */
+export declare function removeStaleHmrEntrypointOutput(outputPath: string, scope: string): void;
+/**
+ * @remarks
+ * Guards against broadcasting reload/update before the bundler has flushed a
+ * fresher artifact than the edited source file.
+ */
+export declare function isHmrOutputFresh(outputPath: string, sourcePath: string): boolean;

package/src/hmr/hmr-entrypoint-output.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RESOLVED_ASSETS_DIR } from "../config/constants.js";
+import { appLogger } from "../global/app-logger.js";
+function isRegisteredScriptEntrypoint(watchedFiles, filePath) {
+  const resolvedPath = path.resolve(filePath);
+  if (watchedFiles.has(resolvedPath)) {
+    return true;
+  }
+  for (const entrypointPath of watchedFiles.keys()) {
+    if (path.resolve(entrypointPath) === resolvedPath) {
+      return true;
+    }
+  }
+  return false;
+}
+function encodeHmrDynamicSegments(filepath) {
+  return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+}
+function resolveHmrEntrypointOutputPaths(srcDir, distDir, entrypointPath) {
+  const normalizedEntrypoint = path.resolve(entrypointPath);
+  const relativePath = path.relative(srcDir, normalizedEntrypoint);
+  const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+  const encodedPathJs = encodeHmrDynamicSegments(relativePathJs);
+  const urlPath = encodedPathJs.split(path.sep).join("/");
+  return {
+    outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath).split(path.sep).join("/")}`,
+    outputPath: path.join(distDir, urlPath)
+  };
+}
+function removeStaleHmrEntrypointOutput(outputPath, scope) {
+  if (!fileSystem.exists(outputPath)) {
+    return;
+  }
+  try {
+    fileSystem.remove(outputPath);
+  } catch (error) {
+    appLogger.warn(
+      `[${scope}] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function isHmrOutputFresh(outputPath, sourcePath) {
+  if (!fileSystem.exists(outputPath) || !fileSystem.exists(sourcePath)) {
+    return false;
+  }
+  const outputMtimeMs = fs.statSync(outputPath).mtimeMs;
+  const sourceMtimeMs = fs.statSync(sourcePath).mtimeMs;
+  return outputMtimeMs >= sourceMtimeMs;
+}
+export {
+  encodeHmrDynamicSegments,
+  isHmrOutputFresh,
+  isRegisteredScriptEntrypoint,
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths
+};

package/src/hmr/strategies/js-hmr-strategy.d.ts

@@ -98,6 +98,7 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * Matches if:
      * 1. There are registered entrypoints to rebuild
      * 2. The changed file is a JS/TS file in the src directory
+     * 3. Registered entrypoints always match, even when they share an integration template extension
      *
      * @param filePath - Absolute path to the changed file
      * @returns True if this file should trigger entrypoint rebuilds
@@ -116,6 +117,8 @@ export declare class JsHmrStrategy extends HmrStrategy {
      * @returns Action to broadcast update events
      */
     process(filePath: string): Promise<HmrAction>;
+    private resolveEntrypointOutputPath;
+    private removeStaleEntrypointOutput;
     /**
      * Bundles one or more entrypoints in a single build invocation.
      * Uses the source directory as the output base so that the directory structure

package/src/hmr/strategies/js-hmr-strategy.js

@@ -2,6 +2,12 @@ import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
 import { appLogger } from "../../global/app-logger.js";
+import {
+  removeStaleHmrEntrypointOutput,
+  resolveHmrEntrypointOutputPaths,
+  isRegisteredScriptEntrypoint,
+  isHmrOutputFresh
+} from "../hmr-entrypoint-output.js";
 class JsHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.SCRIPT;
   context;
@@ -15,27 +21,30 @@ class JsHmrStrategy extends HmrStrategy {
    * Matches if:
    * 1. There are registered entrypoints to rebuild
    * 2. The changed file is a JS/TS file in the src directory
+   * 3. Registered entrypoints always match, even when they share an integration template extension
    *
    * @param filePath - Absolute path to the changed file
    * @returns True if this file should trigger entrypoint rebuilds
    */
   matches(filePath) {
     const watchedFiles = this.context.getWatchedFiles();
-    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
-    const isInSrc = filePath.startsWith(this.context.getSrcDir());
-    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
+    const resolvedPath = path.resolve(filePath);
+    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(resolvedPath);
+    const srcDir = path.resolve(this.context.getSrcDir());
+    const isInSrc = resolvedPath.startsWith(`${srcDir}${path.sep}`) || resolvedPath === srcDir;
+    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => resolvedPath.endsWith(extension));
     if (watchedFiles.size === 0) {
       return false;
     }
     if (!isJsTs || !isInSrc) {
       return false;
     }
+    if (watchedFiles.has(resolvedPath)) {
+      return true;
+    }
     if (isIntegrationTemplate) {
       return false;
     }
-    if (watchedFiles.has(filePath)) {
-      return true;
-    }
     return true;
   }
   /**
@@ -53,22 +62,27 @@ class JsHmrStrategy extends HmrStrategy {
   async process(filePath) {
     appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
     const watchedFiles = this.context.getWatchedFiles();
+    const resolvedChanged = path.resolve(filePath);
+    const isRegisteredEntrypointEdit = isRegisteredScriptEntrypoint(watchedFiles, resolvedChanged);
     if (watchedFiles.size === 0) {
       appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
       return { type: "none" };
     }
     const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
     const hasDependencyHit = dependencyHits.size > 0;
-    const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
+    const impactedEntrypoints = isRegisteredEntrypointEdit ? [resolvedChanged] : hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(path.resolve(entrypoint))) : Array.from(watchedFiles.keys());
     const buildableEntrypoints = impactedEntrypoints.filter(
       (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
     );
-    if (!hasDependencyHit) {
+    if (!hasDependencyHit && !isRegisteredEntrypointEdit) {
       appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
     }
     if (buildableEntrypoints.length === 0) {
       return { type: "none" };
     }
+    for (const entrypoint of buildableEntrypoints) {
+      this.removeStaleEntrypointOutput(this.resolveEntrypointOutputPath(entrypoint));
+    }
     const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
     if (!buildResult.success) {
       return { type: "none" };
@@ -76,17 +90,19 @@ class JsHmrStrategy extends HmrStrategy {
     const updates = [];
     let reloadRequired = false;
     for (const entrypoint of buildableEntrypoints) {
-      const outputUrl = watchedFiles.get(entrypoint);
-      if (!outputUrl) continue;
+      const resolvedEntrypoint = path.resolve(entrypoint);
+      const derivedOutput = resolveHmrEntrypointOutputPaths(
+        this.context.getSrcDir(),
+        this.context.getDistDir(),
+        resolvedEntrypoint
+      );
+      const outputUrl = watchedFiles.get(resolvedEntrypoint) ?? derivedOutput.outputUrl;
+      const outputPath = this.resolveEntrypointOutputPath(resolvedEntrypoint);
       if (buildResult.dependencies) {
-        const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
-        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
+        const entrypointDeps = buildResult.dependencies.get(resolvedEntrypoint) ?? [];
+        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(resolvedEntrypoint, entrypointDeps);
       }
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypoint);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
-      const result = await this.processOutput(outputPath, outputUrl);
+      const result = await this.processOutput(outputPath, outputUrl, resolvedEntrypoint);
       if (result.success) {
         updates.push(outputUrl);
         if (result.requiresReload) {
@@ -113,6 +129,12 @@ class JsHmrStrategy extends HmrStrategy {
     }
     return { type: "none" };
   }
+  resolveEntrypointOutputPath(entrypointPath) {
+    return resolveHmrEntrypointOutputPaths(this.context.getSrcDir(), this.context.getDistDir(), entrypointPath).outputPath;
+  }
+  removeStaleEntrypointOutput(outputPath) {
+    removeStaleHmrEntrypointOutput(outputPath, "JsHmrStrategy");
+  }
   /**
    * Bundles one or more entrypoints in a single build invocation.
    * Uses the source directory as the output base so that the directory structure
@@ -120,6 +142,30 @@ class JsHmrStrategy extends HmrStrategy {
    */
   async bundleEntrypoints(entrypoints) {
     try {
+      if (entrypoints.length === 1) {
+        const entrypoint = entrypoints[0];
+        const outputPath = this.resolveEntrypointOutputPath(entrypoint);
+        const naming = path.relative(this.context.getDistDir(), outputPath).split(path.sep).join("/");
+        const result2 = await this.context.getBrowserBundleService().bundle({
+          profile: "hmr-entrypoint",
+          entrypoints: [entrypoint],
+          outdir: this.context.getDistDir(),
+          naming,
+          plugins: this.context.getPlugins(),
+          minify: false
+        });
+        if (!result2.success) {
+          appLogger.error("[JsHmrStrategy] Entrypoint build failed:", result2.logs);
+          return { success: false };
+        }
+        const dependencies2 = /* @__PURE__ */ new Map();
+        if (result2.dependencyGraph?.entrypoints) {
+          for (const [resolvedEntrypoint, deps] of Object.entries(result2.dependencyGraph.entrypoints)) {
+            dependencies2.set(path.resolve(resolvedEntrypoint), deps);
+          }
+        }
+        return { success: true, dependencies: dependencies2 };
+      }
       const result = await this.context.getBrowserBundleService().bundle({
         profile: "hmr-entrypoint",
         entrypoints,
@@ -153,8 +199,12 @@ class JsHmrStrategy extends HmrStrategy {
    * @param url - URL path for the bundled file
    * @returns True if processing was successful and update should be broadcast
    */
-  async processOutput(filepath, url) {
+  async processOutput(filepath, url, sourcePath) {
     try {
+      if (sourcePath && !isHmrOutputFresh(filepath, sourcePath)) {
+        appLogger.warn(`[JsHmrStrategy] Skipping broadcast for stale HMR output ${url}`);
+        return { success: false, requiresReload: false };
+      }
       const code = await fileSystem.readFile(filepath);
       if (code.includes("/* [ecopages] hmr */")) {
         return { success: true, requiresReload: !code.includes("import.meta.hot.accept") };

package/src/hmr/strategies/server-rendered-template-hmr-strategy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HMR strategy for server-rendered include templates and explicit server views.
+ *
+ * These files affect SSR output (head, layout shell, explicit views) but are not
+ * client HMR entrypoints. Broadcast a layout-update so the active navigation
+ * runtime can refresh the current page without a full document reload.
+ */
+import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
+import type { DevelopmentInvalidationService } from '../../services/invalidation/development-invalidation.service.js';
+export declare class ServerRenderedTemplateHmrStrategy extends HmrStrategy {
+    private readonly invalidationService;
+    readonly type: 100;
+    readonly priorityOffset = 50;
+    constructor(invalidationService: DevelopmentInvalidationService);
+    matches(filePath: string): boolean;
+    process(filePath: string): Promise<HmrAction>;
+}

package/src/hmr/strategies/server-rendered-template-hmr-strategy.js

@@ -0,0 +1,29 @@
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
+const SERVER_RENDERED_TEMPLATE_PRIORITY_OFFSET = 50;
+class ServerRenderedTemplateHmrStrategy extends HmrStrategy {
+  constructor(invalidationService) {
+    super();
+    this.invalidationService = invalidationService;
+  }
+  invalidationService;
+  type = HmrStrategyType.INTEGRATION;
+  priorityOffset = SERVER_RENDERED_TEMPLATE_PRIORITY_OFFSET;
+  matches(filePath) {
+    return this.invalidationService.isIncludeSourceFile(filePath) || this.invalidationService.isExplicitServerViewFile(filePath);
+  }
+  async process(filePath) {
+    return {
+      type: "broadcast",
+      events: [
+        {
+          type: "layout-update",
+          path: filePath,
+          timestamp: Date.now()
+        }
+      ]
+    };
+  }
+}
+export {
+  ServerRenderedTemplateHmrStrategy
+};

package/src/integrations/ghtml/ghtml-renderer.d.ts

@@ -2,15 +2,11 @@
  * This module contains the ghtml renderer
  * @module
  */
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
-import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/orchestration/integration-renderer.js';
+import { StringMarkupRenderer } from '../../route-renderer/orchestration/string-markup-renderer.js';
 /**
  * A renderer for the ghtml integration.
  * It renders a page using the HtmlTemplate and Page components.
  */
-export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
+export declare class GhtmlRenderer extends StringMarkupRenderer {
     name: string;
-    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
-    renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }

package/src/integrations/ghtml/ghtml-renderer.js

@@ -1,56 +1,7 @@
-import {
-  IntegrationRenderer
-} from "../../route-renderer/orchestration/integration-renderer.js";
+import { StringMarkupRenderer } from "../../route-renderer/orchestration/string-markup-renderer.js";
 import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
-class GhtmlRenderer extends IntegrationRenderer {
+class GhtmlRenderer extends StringMarkupRenderer {
   name = GHTML_PLUGIN_NAME;
-  async renderComponent(input) {
-    return this.renderStringComponentWithQueuedForeignSubtrees(
-      input,
-      input.component
-    );
-  }
-  async render({
-    params,
-    query,
-    props,
-    locals,
-    pageLocals,
-    metadata,
-    Page,
-    Layout,
-    HtmlTemplate
-  }) {
-    try {
-      return await this.renderPageWithDocumentShell({
-        page: {
-          component: Page,
-          props: { params, query, ...props, locals: pageLocals }
-        },
-        layout: Layout ? {
-          component: Layout,
-          props: locals ? { locals } : {}
-        } : void 0,
-        htmlTemplate: HtmlTemplate,
-        metadata,
-        pageProps: props ?? {}
-      });
-    } catch (error) {
-      throw this.createRenderError("Error rendering page", error);
-    }
-  }
-  async renderToResponse(view, props, ctx) {
-    try {
-      return await this.renderViewWithDocumentShell({
-        view,
-        props,
-        ctx,
-        layout: view.config?.layout
-      });
-    } catch (error) {
-      throw this.createRenderError("Error rendering view", error);
-    }
-  }
 }
 export {
   GhtmlRenderer

package/src/integrations/ghtml/ghtml.plugin.d.ts

@@ -1,16 +1,3 @@
-import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.js';
-import { GhtmlRenderer } from './ghtml-renderer.js';
-/**
- * The Ghtml plugin class
- * This plugin provides support for ghtml components in Ecopages
- */
-export declare class GhtmlPlugin extends IntegrationPlugin {
-    renderer: typeof GhtmlRenderer;
-    constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
-}
-/**
- * Factory function to create a Ghtml plugin instance
- * @param options Configuration options for the Ghtml plugin
- * @returns A new GhtmlPlugin instance
- */
-export declare function ghtmlPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): GhtmlPlugin;
+export declare const ghtmlPlugin: import("../../plugins/define-integration.js").DefinedIntegration<import("../../index.browser.js").EcoPagesElement>;
+/** @deprecated Use {@link ghtmlPlugin.Plugin} or {@link ghtmlPlugin} instead. */
+export declare const GhtmlPlugin: new (options?: Omit<import("../../plugins/integration-plugin.js").IntegrationPluginConfig, "name">) => import("../../plugins/integration-plugin.js").IntegrationPlugin<import("../../index.browser.js").EcoPagesElement>;

package/src/integrations/ghtml/ghtml.plugin.js

@@ -1,19 +1,12 @@
-import { IntegrationPlugin } from "../../plugins/integration-plugin.js";
+import { defineIntegration } from "../../plugins/define-integration.js";
 import { GhtmlRenderer } from "./ghtml-renderer.js";
 import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
-class GhtmlPlugin extends IntegrationPlugin {
-  renderer = GhtmlRenderer;
-  constructor(options) {
-    super({
-      name: GHTML_PLUGIN_NAME,
-      extensions: [".ghtml.ts", ".ghtml.tsx", ".ghtml"],
-      ...options
-    });
-  }
-}
-function ghtmlPlugin(options) {
-  return new GhtmlPlugin(options);
-}
+const ghtmlPlugin = defineIntegration({
+  name: GHTML_PLUGIN_NAME,
+  extensions: [".ghtml.ts", ".ghtml.tsx", ".ghtml"],
+  renderer: GhtmlRenderer
+});
+const GhtmlPlugin = ghtmlPlugin.Plugin;
 export {
   GhtmlPlugin,
   ghtmlPlugin

package/src/plugins/define-integration.d.ts

@@ -0,0 +1,26 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
+import type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { EcoPagesElement } from '../types/public-types.js';
+import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
+import { IntegrationPlugin, type IntegrationPluginConfig } from './integration-plugin.js';
+type RendererClass<C> = new (options: {
+    appConfig: EcoPagesAppConfig;
+    assetProcessingService: AssetProcessingService;
+    resolvedIntegrationDependencies: ProcessedAsset[];
+    rendererModules?: unknown;
+    runtimeOrigin: string;
+}) => IntegrationRenderer<C>;
+export interface DefineIntegrationDefinition<C = EcoPagesElement> extends IntegrationPluginConfig {
+    renderer: RendererClass<C>;
+}
+export interface DefinedIntegration<C = EcoPagesElement> {
+    (options?: Omit<IntegrationPluginConfig, 'name'>): IntegrationPlugin<C>;
+    Plugin: new (options?: Omit<IntegrationPluginConfig, 'name'>) => IntegrationPlugin<C>;
+}
+/**
+ * Creates a typed integration plugin factory for integrations that only need
+ * declarative config and a renderer class.
+ */
+export declare function defineIntegration<C = EcoPagesElement>(definition: DefineIntegrationDefinition<C>): DefinedIntegration<C>;
+export {};

package/src/plugins/define-integration.js

@@ -0,0 +1,19 @@
+import { IntegrationPlugin } from "./integration-plugin.js";
+function defineIntegration(definition) {
+  const { renderer, ...defaultConfig } = definition;
+  class DefinedIntegrationPlugin extends IntegrationPlugin {
+    renderer = renderer;
+    constructor(options) {
+      super({
+        ...defaultConfig,
+        ...options
+      });
+    }
+  }
+  const factory = ((options) => new DefinedIntegrationPlugin(options));
+  factory.Plugin = DefinedIntegrationPlugin;
+  return factory;
+}
+export {
+  defineIntegration
+};

package/src/plugins/eco-component-meta-plugin.js

@@ -1,4 +1,5 @@
 import { cachedParseSync } from "../cache/module-parse-cache.js";
+import { prependJsxImportSourceIfMissing } from "./jsx-import-source.utils.js";
 import { rapidhash } from "../utils/hash.js";
 import {
   createEcoBuildPluginFromSourceTransform,
@@ -38,13 +39,6 @@ function detectIntegration(filePath, extensionToIntegration) {
   }
   return { name: "ghtml" };
 }
-function prependJsxImportSource(code, jsxImportSource) {
-  if (!jsxImportSource || code.includes("@jsxImportSource")) {
-    return code;
-  }
-  return `/** @jsxImportSource ${jsxImportSource} */
-${code}`;
-}
 function createExtensionPattern(extensions) {
   if (extensions.length === 0) {
     throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
@@ -67,7 +61,10 @@ function createEcoComponentMetaTransform(options) {
     transform(code, id) {
       const integration = detectIntegration(id, extensionToIntegration);
       return {
-        code: prependJsxImportSource(injectEcoMeta(code, id, integration.name), integration.jsxImportSource)
+        code: prependJsxImportSourceIfMissing(
+          injectEcoMeta(code, id, integration.name),
+          integration.jsxImportSource
+        )
       };
     }
   };

package/src/plugins/foreign-jsx-override-plugin.js

@@ -1,10 +1,9 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { createJsxImportSourcePragma, filterJsxSourceExtensions } from "./jsx-import-source.utils.js";
 function createForeignJsxOverridePlugin(options) {
-  const extensions = options.foreignExtensions.filter((ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx"));
-  const excludedExtensions = (options.excludeExtensions ?? []).filter(
-    (ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx")
-  );
+  const extensions = filterJsxSourceExtensions(options.foreignExtensions);
+  const excludedExtensions = filterJsxSourceExtensions(options.excludeExtensions ?? []);
   if (extensions.length === 0) {
     return {
       name: options.name ?? "foreign-jsx-override",
@@ -12,8 +11,7 @@ function createForeignJsxOverridePlugin(options) {
       }
     };
   }
-  const pragma = `/** @jsxImportSource ${options.hostJsxImportSource} */
-`;
+  const pragma = createJsxImportSourcePragma(options.hostJsxImportSource);
   const filter = new RegExp(`(${extensions.map((e) => e.replace(".", "\\.")).join("|")})$`);
   return {
     name: options.name ?? "foreign-jsx-override",

package/src/plugins/integration-plugin.d.ts

@@ -6,10 +6,12 @@ import type { EcoPagesElement } from '../types/public-types.js';
 import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
 import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
 export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
+export type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
 /**
  * Type-erased integration plugin stored in app-level registries.
@@ -47,13 +49,6 @@ export interface IntegrationPluginConfig {
      * They are not specific to any particular page or component.
      */
     integrationDependencies?: AssetDefinition[];
-    /**
-     * The strategy to use for static building.
-     * - 'render': Execute component function directly (faster, efficient).
-     * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
-     * @default 'render'
-     */
-    staticBuildStep?: 'render' | 'fetch';
     /**
      * Declares runtime-specific requirements that must be satisfied before the
      * app can start with this integration enabled.
@@ -96,7 +91,6 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     readonly name: string;
     readonly extensions: string[];
     abstract renderer: RendererClass<C>;
-    readonly staticBuildStep: 'render' | 'fetch';
     readonly runtimeCapability?: RuntimeCapabilityDeclaration;
     readonly jsxImportSource?: string;
     protected integrationDependencies: AssetDefinition[];
@@ -199,7 +193,6 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * Renderers are cheap runtime objects. They receive the finalized app config,
      * a fresh asset-processing service, integration-global processed assets, and
      * any renderer module context supplied by the active runtime.
-            renderer.name ||= this.name;
      */
     initializeRenderer(options?: {
         rendererModules?: unknown;
@@ -213,6 +206,23 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this integration's build inputs changed since the last
+     * incremental static build.
+     */
+    didChange(): boolean;
+    /**
+     * Runs integration-specific setup before static page generation begins.
+     *
+     * @remarks
+     * Integrations that need build-scoped SSR preload or worker sessions should
+     * start them here rather than per-page inside the renderer.
+     */
+    beforeStaticExport?(_context: StaticExportContext): Promise<void>;
+    /**
+     * Releases resources started in {@link beforeStaticExport}.
+     */
+    afterStaticExport?(_context: StaticExportContext): Promise<void>;
     /**
      * Performs runtime-only integration setup after config build has already
      * sealed manifest contributions.

package/src/plugins/integration-plugin.js

@@ -15,7 +15,6 @@ function assertIntegrationInvariant(condition, message) {
 class IntegrationPlugin {
   name;
   extensions;
-  staticBuildStep;
   runtimeCapability;
   jsxImportSource;
   integrationDependencies;
@@ -60,7 +59,6 @@ class IntegrationPlugin {
     this.name = config.name;
     this.extensions = config.extensions;
     this.integrationDependencies = config.integrationDependencies || [];
-    this.staticBuildStep = config.staticBuildStep || "render";
     this.runtimeCapability = config.runtimeCapability;
     this.jsxImportSource = config.jsxImportSource;
   }
@@ -152,7 +150,6 @@ class IntegrationPlugin {
    * Renderers are cheap runtime objects. They receive the finalized app config,
    * a fresh asset-processing service, integration-global processed assets, and
    * any renderer module context supplied by the active runtime.
-  		renderer.name ||= this.name;
    */
   initializeRenderer(options) {
     const renderer = new this.renderer(this.createRendererOptions(options));
@@ -169,6 +166,13 @@ class IntegrationPlugin {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this integration's build inputs changed since the last
+   * incremental static build.
+   */
+  didChange() {
+    return false;
+  }
   /**
    * Performs runtime-only integration setup after config build has already
    * sealed manifest contributions.
@@ -180,7 +184,6 @@ class IntegrationPlugin {
       this.integrationDependencies,
       this.name
     );
-    this.initializeRenderer();
   }
   /**
    * Releases runtime resources owned by the integration.