@ecopages/core 0.2.0-alpha.9 → 0.2.0-beta.1

package/src/services/assets/browser-bundle.service.d.ts

@@ -1,11 +1,50 @@
-import type { BuildOptions, BuildResult, BuildTranspileProfile } from '../../build/build-adapter.js';
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-export type BrowserBundleOptions = Omit<BuildOptions, 'target' | 'format' | 'sourcemap'> & {
+import type { BuildResult, BuildTranspileProfile } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type BrowserBundleOptions = {
+    entrypoints: string[] | Record<string, string>;
+    outdir?: string;
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    splitting?: boolean;
+    root?: string;
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    plugins?: EcoBuildPlugin[];
+    [key: string]: unknown;
     profile: BuildTranspileProfile;
+    excludeAppBuildPlugins?: string[];
+};
+type BrowserBundleGroupedOptions = {
+    outdir?: string;
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    splitting?: boolean;
+    root?: string;
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    plugins?: EcoBuildPlugin[];
+    [key: string]: unknown;
+    profile: BuildTranspileProfile;
+    excludeAppBuildPlugins?: string[];
 };
 export interface BrowserBundleExecutor {
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
 }
+export type BrowserBundleGroupedEntry = {
+    entrypoint: string;
+    entryName: string;
+};
 /**
  * App-owned boundary for browser-oriented bundle work.
  *
@@ -29,4 +68,6 @@ export declare class BrowserBundleService implements BrowserBundleExecutor {
      * site.
      */
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
+    bundleGroupedEntries(entries: BrowserBundleGroupedEntry[], options: BrowserBundleGroupedOptions): Promise<BuildResult>;
 }
+export {};

package/src/services/assets/browser-bundle.service.js

@@ -1,4 +1,4 @@
-import { getAppBrowserBuildPlugins, getAppBuildExecutor, getTranspileOptions } from "../../build/build-adapter.js";
+import { getAppBrowserBuildPlugins, getAppBuildExecutor, getAppTranspileOptions } from "../../build/build-adapter.js";
 import { mergeEcoBuildPlugins } from "../../build/build-manifest.js";
 class BrowserBundleService {
   appConfig;
@@ -17,16 +17,24 @@ class BrowserBundleService {
    * site.
    */
   async bundle(options) {
-    const { profile, ...rawBuildOptions } = options;
-    const buildOptions = rawBuildOptions;
-    const plugins = buildOptions.plugins;
+    const { profile, excludeAppBuildPlugins, plugins, ...rawBuildOptions } = options;
+    const appBrowserPlugins = getAppBrowserBuildPlugins(this.appConfig);
+    const filteredAppBrowserPlugins = excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0 ? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name)) : appBrowserPlugins;
     const request = {
-      ...buildOptions,
-      ...getTranspileOptions(profile),
-      plugins: mergeEcoBuildPlugins(plugins, getAppBrowserBuildPlugins(this.appConfig))
+      ...rawBuildOptions,
+      entrypoints: options.entrypoints,
+      ...getAppTranspileOptions(this.appConfig, profile),
+      plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins)
     };
     return await getAppBuildExecutor(this.appConfig).build(request);
   }
+  async bundleGroupedEntries(entries, options) {
+    const request = {
+      ...options,
+      entrypoints: entries.map((entry) => entry.entrypoint)
+    };
+    return this.bundle(request);
+  }
 }
 export {
   BrowserBundleService

package/src/services/html/html-rewriter-provider.service.d.ts

@@ -1,4 +1,7 @@
 export type HtmlRewriterElement = {
+    prepend(content: string, options?: {
+        html?: boolean;
+    }): void;
     append(content: string, options?: {
         html?: boolean;
     }): void;

package/src/services/html/html-rewriter-provider.service.js

@@ -49,7 +49,10 @@ async function loadWorkerToolsHtmlRewriter() {
     return module.HTMLRewriter;
   } catch (primaryError) {
     try {
-      const runtimeLocalModule = await import(new URL("../node_modules/@worker-tools/html-rewriter/base64.js", import.meta.url).href);
+      const runtimeLocalModule = await import(
+        /* @vite-ignore */
+        new URL("../node_modules/@worker-tools/html-rewriter/base64.js", import.meta.url).href
+      );
       return runtimeLocalModule.HTMLRewriter;
     } catch {
       const message = primaryError instanceof Error ? primaryError.message : String(primaryError);

package/src/services/html/html-transformer.service.d.ts

@@ -1,11 +1,18 @@
-import type { ProcessedAsset } from '../assets/asset-processing-service/assets.types';
-import { type HtmlRewriterMode, type HtmlRewriterProvider } from './html-rewriter-provider.service';
+import type { ProcessedAsset } from '../assets/asset-processing-service/assets.types.js';
+import type { PagePackageResult } from '../../types/public-types.js';
+import { type HtmlRewriterMode, type HtmlRewriterProvider } from './html-rewriter-provider.service.js';
+export type HtmlDocumentContributionPlacement = 'head-prepend' | 'head-append' | 'body-prepend' | 'body-append';
+export type HtmlDocumentContribution = {
+    placement: HtmlDocumentContributionPlacement;
+    html: string;
+};
 export interface HtmlTransformerServiceOptions {
     htmlRewriterMode?: HtmlRewriterMode;
     htmlRewriterProvider?: HtmlRewriterProvider;
 }
 export declare class HtmlTransformerService {
     private processedDependencies;
+    private pagePackage?;
     private htmlRewriterProvider;
     constructor(options?: HtmlTransformerServiceOptions);
     /**
@@ -22,19 +29,30 @@ export declare class HtmlTransformerService {
     private generateStylesheetTag;
     private appendDependencies;
     private buildDependencyTags;
+    private applyContributions;
     /**
      * Injects generated markup immediately before the closing HTML tag when it is
      * present, or appends/prepends a fallback insertion otherwise.
      */
     private injectBeforeClosingTag;
+    private injectAfterOpeningTag;
+    private groupContributionsByPlacement;
     /**
      * Replaces the current processed dependency set used during HTML finalization.
      */
     setProcessedDependencies(processedDependencies: ProcessedAsset[]): void;
+    /**
+     * Replaces the current structured page package used during HTML finalization.
+     */
+    setPagePackage(pagePackage: PagePackageResult): void;
     /**
      * Returns the processed dependencies queued for the next transform pass.
      */
     getProcessedDependencies(): ProcessedAsset[];
+    /**
+     * Returns the structured page package queued for the next transform pass.
+     */
+    getPagePackage(): PagePackageResult | undefined;
     /**
      * Applies attributes to the opening `<html>` tag when present.
      */
@@ -65,11 +83,12 @@ export declare class HtmlTransformerService {
      * string-based fallback remains in place for runtimes that cannot provide one
      * of those rewriter implementations.
      */
-    transform(res: Response): Promise<Response>;
+    transform(res: Response, contributions?: HtmlDocumentContribution[]): Promise<Response>;
     /**
      * Splits processed assets into head and body injection groups.
      */
     private groupDependenciesByPosition;
+    private resolvePagePackageHtmlDependencies;
     /**
      * Builds a serialized HTML attribute string from an attribute object.
      */

package/src/services/html/html-transformer.service.js

@@ -1,8 +1,13 @@
 import {
   DefaultHtmlRewriterProvider
-} from "./html-rewriter-provider.service";
+} from "./html-rewriter-provider.service.js";
+import {
+  buildProcessedAssetDedupeKey,
+  dedupeProcessedAssets
+} from "../../route-renderer/orchestration/processed-asset-dedupe.js";
 class HtmlTransformerService {
   processedDependencies = [];
+  pagePackage;
   htmlRewriterProvider;
   constructor(options = {}) {
     this.htmlRewriterProvider = options.htmlRewriterProvider ?? new DefaultHtmlRewriterProvider();
@@ -42,6 +47,11 @@ class HtmlTransformerService {
       (dep) => dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep)
     ).join("");
   }
+  applyContributions(element, contributions, placement) {
+    for (const contribution of contributions) {
+      element[placement](contribution.html, { html: true });
+    }
+  }
   /**
    * Injects generated markup immediately before the closing HTML tag when it is
    * present, or appends/prepends a fallback insertion otherwise.
@@ -61,18 +71,52 @@ class HtmlTransformerService {
     }
     return `${html}${content}`;
   }
+  injectAfterOpeningTag(html, tag, content) {
+    if (!content) {
+      return html;
+    }
+    const openingTag = new RegExp(`<${tag}\\b[^>]*>`, "i");
+    const match = html.match(openingTag);
+    if (!match || match.index === void 0) {
+      return tag === "head" ? `${content}${html}` : html.replace(/<body\b[^>]*>/i, (value) => `${value}${content}`);
+    }
+    const insertAt = match.index + match[0].length;
+    return `${html.slice(0, insertAt)}${content}${html.slice(insertAt)}`;
+  }
+  groupContributionsByPlacement(contributions) {
+    return {
+      headPrepend: contributions.filter((item) => item.placement === "head-prepend"),
+      headAppend: contributions.filter((item) => item.placement === "head-append"),
+      bodyPrepend: contributions.filter((item) => item.placement === "body-prepend"),
+      bodyAppend: contributions.filter((item) => item.placement === "body-append")
+    };
+  }
   /**
    * Replaces the current processed dependency set used during HTML finalization.
    */
   setProcessedDependencies(processedDependencies) {
+    this.pagePackage = void 0;
     this.processedDependencies = processedDependencies;
   }
+  /**
+   * Replaces the current structured page package used during HTML finalization.
+   */
+  setPagePackage(pagePackage) {
+    this.pagePackage = pagePackage;
+    this.processedDependencies = this.resolvePagePackageHtmlDependencies(pagePackage);
+  }
   /**
    * Returns the processed dependencies queued for the next transform pass.
    */
   getProcessedDependencies() {
     return this.processedDependencies;
   }
+  /**
+   * Returns the structured page package queued for the next transform pass.
+   */
+  getPagePackage() {
+    return this.pagePackage;
+  }
   /**
    * Applies attributes to the opening `<html>` tag when present.
    */
@@ -134,23 +178,7 @@ class HtmlTransformerService {
    * variants.
    */
   dedupeProcessedAssets(assets) {
-    const unique = /* @__PURE__ */ new Map();
-    for (const asset of assets) {
-      const key = [
-        asset.kind,
-        asset.position ?? "",
-        asset.srcUrl ?? "",
-        asset.filepath ?? "",
-        asset.content ?? "",
-        asset.inline ? "inline" : "external",
-        asset.excludeFromHtml ? "excluded" : "included",
-        JSON.stringify(asset.attributes ?? {})
-      ].join("|");
-      if (!unique.has(key)) {
-        unique.set(key, asset);
-      }
-    }
-    return [...unique.values()];
+    return dedupeProcessedAssets(assets);
   }
   /**
    * Injects the currently processed dependencies into an HTML response.
@@ -160,30 +188,47 @@ class HtmlTransformerService {
    * string-based fallback remains in place for runtimes that cannot provide one
    * of those rewriter implementations.
    */
-  async transform(res) {
+  async transform(res, contributions = []) {
     const { head, body } = this.groupDependenciesByPosition();
+    const { headPrepend, headAppend, bodyPrepend, bodyAppend } = this.groupContributionsByPlacement(contributions);
     const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
-    const html = await res.text();
-    const headers = new Headers(res.headers);
     if (htmlRewriter) {
       htmlRewriter.on("head", {
-        element: (element) => this.appendDependencies(element, head)
+        element: (element) => {
+          this.applyContributions(element, headPrepend, "prepend");
+          this.appendDependencies(element, head);
+          this.applyContributions(element, headAppend, "append");
+        }
       }).on("body", {
-        element: (element) => this.appendDependencies(element, body)
+        element: (element) => {
+          this.applyContributions(element, bodyPrepend, "prepend");
+          this.appendDependencies(element, body);
+          this.applyContributions(element, bodyAppend, "append");
+        }
       });
-      return htmlRewriter.transform(
-        new Response(html, {
-          headers,
-          status: res.status,
-          statusText: res.statusText
-        })
-      );
-    }
-    const withHeadDependencies = this.injectBeforeClosingTag(html, "head", this.buildDependencyTags(head));
-    const transformedHtml = this.injectBeforeClosingTag(
+      return htmlRewriter.transform(res);
+    }
+    const html = await res.text();
+    const headers = new Headers(res.headers);
+    const withHeadPrependedContent = this.injectAfterOpeningTag(
+      html,
+      "head",
+      headPrepend.map((item) => item.html).join("")
+    );
+    const withHeadDependencies = this.injectBeforeClosingTag(
+      withHeadPrependedContent,
+      "head",
+      `${this.buildDependencyTags(head)}${headAppend.map((item) => item.html).join("")}`
+    );
+    const withBodyPrependedContent = this.injectAfterOpeningTag(
       withHeadDependencies,
       "body",
-      this.buildDependencyTags(body)
+      bodyPrepend.map((item) => item.html).join("")
+    );
+    const transformedHtml = this.injectBeforeClosingTag(
+      withBodyPrependedContent,
+      "body",
+      `${this.buildDependencyTags(body)}${bodyAppend.map((item) => item.html).join("")}`
     );
     return new Response(transformedHtml, {
       headers,
@@ -195,7 +240,8 @@ class HtmlTransformerService {
    * Splits processed assets into head and body injection groups.
    */
   groupDependenciesByPosition() {
-    return this.processedDependencies.reduce(
+    const dependencies = this.pagePackage ? this.resolvePagePackageHtmlDependencies(this.pagePackage) : this.processedDependencies;
+    return dependencies.reduce(
       (acc, dep) => {
         if (dep.kind === "script") {
           if (dep.excludeFromHtml) return acc;
@@ -209,6 +255,26 @@ class HtmlTransformerService {
       { head: [], body: [] }
     );
   }
+  resolvePagePackageHtmlDependencies(pagePackage) {
+    if (!pagePackage.pageBrowserGraph) {
+      return pagePackage.htmlAssets;
+    }
+    const chunkKeys = new Set(
+      pagePackage.pageBrowserGraph.chunkAssets.map((asset) => buildProcessedAssetDedupeKey(asset))
+    );
+    const graphKeys = new Set(
+      [...pagePackage.pageBrowserGraph.entryAssets, ...pagePackage.pageBrowserGraph.chunkAssets].map(
+        (asset) => buildProcessedAssetDedupeKey(asset)
+      )
+    );
+    const nonGraphHtmlAssets = pagePackage.htmlAssets.filter(
+      (asset) => !graphKeys.has(buildProcessedAssetDedupeKey(asset))
+    );
+    const entryHtmlAssets = pagePackage.pageBrowserGraph.entryAssets.filter(
+      (asset) => !chunkKeys.has(buildProcessedAssetDedupeKey(asset))
+    );
+    return dedupeProcessedAssets([...nonGraphHtmlAssets, ...entryHtmlAssets]);
+  }
   /**
    * Builds a serialized HTML attribute string from an attribute object.
    */

package/src/services/invalidation/development-invalidation.service.d.ts

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 export type DevelopmentInvalidationCategory = 'public-asset' | 'additional-watch' | 'include-source' | 'route-source' | 'processor-owned-asset' | 'server-source' | 'other';
 /**
  * Framework-owned invalidation plan for one changed file.

package/src/services/invalidation/development-invalidation.service.js

@@ -16,6 +16,7 @@ class DevelopmentInvalidationService {
    */
   invalidateServerModules(changedFiles) {
     getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
+    this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
   }
   /**
    * Resets runtime-owned graph state and invalidates server modules.

package/src/services/module-loading/app-module-loader.service.d.ts

@@ -0,0 +1,7 @@
+import type { PageModuleBuildImportOptions } from './page-module-import.service.js';
+export type AppModuleLoaderOwner = 'app' | 'host';
+export interface AppModuleLoader {
+    readonly owner: AppModuleLoaderOwner;
+    importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
+    invalidateDevelopmentGraph(): void;
+}

package/src/services/module-loading/app-server-module-transpiler.service.d.ts

@@ -1,5 +1,13 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { type AppModuleLoader } from './app-module-loader.service.js';
+import type { SourceModuleLoader } from './module-loading-types.js';
 import { ServerModuleTranspiler } from './server-module-transpiler.service.js';
+export declare function shouldAppUseHostModuleLoader(appConfig: EcoPagesAppConfig, filePath: string): boolean;
+export declare function getAppHostModuleLoader(appConfig: EcoPagesAppConfig): SourceModuleLoader | undefined;
+export declare function setAppHostModuleLoader(appConfig: EcoPagesAppConfig, hostModuleLoader?: SourceModuleLoader): void;
+export declare function createAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
+export declare function getAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
+export declare function setAppModuleLoader(appConfig: EcoPagesAppConfig, appModuleLoader: AppModuleLoader): void;
 /**
  * Creates the shared app-scoped server-module transpiler for one runtime
  * instance.

package/src/services/module-loading/app-server-module-transpiler.service.js

@@ -1,15 +1,105 @@
-import { getAppBuildExecutor } from "../../build/build-adapter.js";
-import { createAppNodeBootstrapPlugin } from "../../adapters/node/bootstrap-dependency-resolver.js";
+import { getAppBuildExecutor, getAppServerBuildPlugins } from "../../build/build-adapter.js";
+import { createForeignJsxOverridePlugin } from "../../plugins/foreign-jsx-override-plugin.js";
+import path from "node:path";
 import { DevelopmentInvalidationService } from "../invalidation/development-invalidation.service.js";
+import {} from "./app-module-loader.service.js";
+import { PageModuleImportService } from "./page-module-import.service.js";
+import { supportsSourceModuleLoading } from "./source-module-support.js";
 import { ServerModuleTranspiler } from "./server-module-transpiler.service.js";
+function shouldAppUseHostModuleLoader(appConfig, filePath) {
+  if (appConfig.runtime?.hostModuleLoader) {
+    return supportsSourceModuleLoading(filePath);
+  }
+  const normalizedFilePath = path.normalize(filePath);
+  const frameworkOwnedDirectories = [
+    appConfig.absolutePaths.pagesDir,
+    appConfig.absolutePaths.includesDir,
+    appConfig.absolutePaths.layoutsDir,
+    appConfig.absolutePaths.componentsDir
+  ].map((directoryPath) => path.normalize(directoryPath));
+  const isFrameworkOwnedModule = frameworkOwnedDirectories.some((directoryPath) => {
+    return normalizedFilePath === directoryPath || normalizedFilePath.startsWith(`${directoryPath}${path.sep}`);
+  });
+  const isConfiguredTemplateModule = appConfig.templatesExt.some(
+    (extension) => normalizedFilePath.endsWith(extension)
+  );
+  return !(isFrameworkOwnedModule && isConfiguredTemplateModule);
+}
+function getAppHostModuleLoader(appConfig) {
+  return appConfig.runtime?.hostModuleLoader;
+}
+function getAppModuleLoaderOwner(appConfig) {
+  return getAppHostModuleLoader(appConfig) ? "host" : "app";
+}
+function setAppHostModuleLoader(appConfig, hostModuleLoader) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    hostModuleLoader
+  };
+}
+function getJsxOwnershipPlugins(appConfig) {
+  const jsxExtensions = (appConfig.integrations ?? []).filter((integration) => integration.jsxImportSource).flatMap(
+    (integration) => integration.extensions.filter((extension) => extension.endsWith(".tsx") || extension.endsWith(".jsx")).map((extension) => ({ integration, extension }))
+  ).sort((left, right) => right.extension.length - left.extension.length);
+  return jsxExtensions.map(
+    ({ integration, extension }) => createForeignJsxOverridePlugin({
+      hostJsxImportSource: integration.jsxImportSource,
+      foreignExtensions: [extension],
+      excludeExtensions: jsxExtensions.filter((candidate) => candidate.extension.length > extension.length).filter((candidate) => candidate.extension.endsWith(extension)).map((candidate) => candidate.extension),
+      name: `ecopages-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, "-")}`
+    })
+  );
+}
+function createAppModuleLoader(appConfig) {
+  const invalidationService = new DevelopmentInvalidationService(appConfig);
+  const pageModuleImportService = new PageModuleImportService({
+    canLoadSourceModuleFromHost: (filePath) => shouldAppUseHostModuleLoader(appConfig, filePath),
+    getHostModuleLoader: () => getAppHostModuleLoader(appConfig)
+  });
+  const appServerBuildPlugins = appConfig.runtime?.buildManifest ? getAppServerBuildPlugins(appConfig) : Array.from(appConfig.loaders?.values() ?? []);
+  const jsxOwnershipPlugins = getJsxOwnershipPlugins(appConfig);
+  const appModuleLoader = {
+    get owner() {
+      return getAppModuleLoaderOwner(appConfig);
+    },
+    pageModuleImportService,
+    async importModule(options) {
+      const invalidationVersion = options.invalidationVersion ?? invalidationService.getServerModuleInvalidationVersion();
+      const mergedPlugins = [...appServerBuildPlugins, ...jsxOwnershipPlugins, ...options.plugins ?? []];
+      return await pageModuleImportService.importModule({
+        ...options,
+        ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
+        buildExecutor: options.buildExecutor ?? getAppBuildExecutor(appConfig),
+        invalidationVersion
+      });
+    },
+    invalidateDevelopmentGraph() {
+      pageModuleImportService.invalidateDevelopmentGraph();
+    }
+  };
+  return appModuleLoader;
+}
+function getAppModuleLoader(appConfig) {
+  const existingModuleLoader = appConfig.runtime?.appModuleLoader;
+  if (existingModuleLoader) {
+    return existingModuleLoader;
+  }
+  const appModuleLoader = createAppModuleLoader(appConfig);
+  setAppModuleLoader(appConfig, appModuleLoader);
+  return appModuleLoader;
+}
+function setAppModuleLoader(appConfig, appModuleLoader) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    appModuleLoader
+  };
+}
 function createAppServerModuleTranspiler(appConfig) {
   const invalidationService = new DevelopmentInvalidationService(appConfig);
   return new ServerModuleTranspiler({
     rootDir: appConfig.rootDir,
-    getBuildExecutor: () => getAppBuildExecutor(appConfig),
-    getInvalidationVersion: () => invalidationService.getServerModuleInvalidationVersion(),
     invalidateModules: (changedFiles) => invalidationService.invalidateServerModules(changedFiles),
-    getDefaultPlugins: typeof Bun === "undefined" && appConfig.rootDir ? () => [createAppNodeBootstrapPlugin(appConfig)] : void 0
+    pageModuleImportService: getAppModuleLoader(appConfig)
   });
 }
 function getAppServerModuleTranspiler(appConfig) {
@@ -28,7 +118,13 @@ function setAppServerModuleTranspiler(appConfig, serverModuleTranspiler) {
   };
 }
 export {
+  createAppModuleLoader,
   createAppServerModuleTranspiler,
+  getAppHostModuleLoader,
+  getAppModuleLoader,
   getAppServerModuleTranspiler,
-  setAppServerModuleTranspiler
+  setAppHostModuleLoader,
+  setAppModuleLoader,
+  setAppServerModuleTranspiler,
+  shouldAppUseHostModuleLoader
 };

package/src/services/module-loading/host-module-loader-registry.d.ts

@@ -0,0 +1,4 @@
+import type { SourceModuleLoader } from './module-loading-types.js';
+export declare function setHostModuleLoader(loader: SourceModuleLoader): void;
+export declare function getHostModuleLoader(): SourceModuleLoader | undefined;
+export declare function clearHostModuleLoader(): void;

package/src/services/module-loading/host-module-loader-registry.js

@@ -0,0 +1,15 @@
+let hostModuleLoader;
+function setHostModuleLoader(loader) {
+  hostModuleLoader = loader;
+}
+function getHostModuleLoader() {
+  return hostModuleLoader;
+}
+function clearHostModuleLoader() {
+  hostModuleLoader = void 0;
+}
+export {
+  clearHostModuleLoader,
+  getHostModuleLoader,
+  setHostModuleLoader
+};

package/src/services/module-loading/module-loading-types.d.ts

@@ -0,0 +1,2 @@
+export type SourceModuleLoader = (id: string) => Promise<unknown>;
+export type SourceModuleLoaderFactory = () => SourceModuleLoader | undefined;

package/src/services/module-loading/page-module-import.service.d.ts

@@ -1,13 +1,33 @@
 import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
-export interface PageModuleImportOptions {
+import type { SourceModuleLoaderFactory } from './module-loading-types.js';
+interface PageModuleImportBaseOptions {
     filePath: string;
+    bypassCache?: boolean;
+    cacheScope?: string;
+    invalidationVersion?: number;
+}
+/**
+ * Options for imports that must pass through the Ecopages build pipeline.
+ *
+ * @remarks
+ * Callers should use build mode for framework-owned page modules and any other
+ * source that relies on Ecopages build resolution before runtime execution.
+ */
+export interface PageModuleBuildImportOptions extends PageModuleImportBaseOptions {
     rootDir: string;
     outdir: string;
     buildExecutor?: BuildExecutor;
-    invalidationVersion?: number;
     splitting?: boolean;
     externalPackages?: boolean;
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
     plugins?: EcoBuildPlugin[];
     transpileErrorMessage?: (details: string) => string;
     noOutputMessage?: (filePath: string) => string;
@@ -23,14 +43,17 @@ export interface PageModuleImportOptions {
 export interface PageModuleImportDependencies {
     hashFile(filePath: string): string;
     buildModule(options: Parameters<typeof build>[0], buildExecutor?: BuildExecutor): Promise<BuildResult>;
+    canLoadSourceModuleFromHost(filePath: string): boolean;
+    getHostModuleLoader: SourceModuleLoaderFactory;
 }
 /**
- * Loads source page modules in a runtime-agnostic way.
+ * Loads page-like modules through the Ecopages build pipeline.
  *
- * This service centralizes the Bun-vs-Node import strategy used by route
- * scanning, page data loading, and request-time page inspection. In Bun it can
- * import source files directly; in Node it transpiles the file into a dedicated
- * output directory first and then imports the generated module.
+ * This service centralizes the shared build-first import strategy used by route
+ * scanning, page data loading, and request-time page inspection. In Node
+ * development it can still delegate compatible source imports to the active
+ * host loader, but the public contract remains one transpile-targeted module
+ * loading path.
  *
  * Keeping this logic in one place prevents subtle drift in cache-busting,
  * transpilation settings, and error semantics across the different callers.
@@ -66,6 +89,7 @@ export declare class PageModuleImportService {
      * @param options Runtime-specific import settings.
      * @returns The loaded module.
      */
-    importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+    importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
     private loadModule;
 }
+export {};