@ecopages/core 0.2.0-beta.1 → 0.2.0-beta.10

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.d.ts

@@ -9,12 +9,14 @@ export type BrowserRuntimeEntryModuleConfig = {
  * @remarks
  * Integrations use this helper when they need a browser runtime asset composed
  * from multiple bare specifiers but do not want to own temporary file assembly
- * logic themselves. The generated file lives under a cache directory inside the
- * consuming app root so repeated runs can reuse the same location.
+ * logic themselves. The generated file lives under the app work directory so
+ * repeated runs can reuse the same location without placing sources inside
+ * `node_modules`, which can cause bundlers to externalize bare imports.
  */
 export declare function createBrowserRuntimeEntryModule(options: {
     modules: BrowserRuntimeEntryModuleConfig[];
     fileName: string;
     rootDir?: string;
+    workDir?: string;
     cacheDirName?: string;
 }): string;

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.js

@@ -1,37 +1,57 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../../../config/constants.js";
 function createBrowserRuntimeEntryModule(options) {
+  if (options.modules.some((module) => !module.specifier.startsWith("node:")) && !options.rootDir) {
+    throw new Error("createBrowserRuntimeEntryModule requires rootDir to resolve package specifiers");
+  }
   const rootDir = options.rootDir ?? process.cwd();
+  const workDir = options.workDir ?? path.join(rootDir, DEFAULT_ECOPAGES_WORK_DIR);
   const artifactsDir = path.join(
-    rootDir,
-    "node_modules",
-    ".cache",
+    workDir,
+    ".browser-runtime-entries",
     options.cacheDirName ?? "ecopages-browser-runtime"
   );
   fs.mkdirSync(artifactsDir, { recursive: true });
   const requireFromRoot = createRequire(path.join(rootDir, "package.json"));
   const seenExports = /* @__PURE__ */ new Set();
   const statements = [];
+  const filePath = path.join(artifactsDir, options.fileName);
+  const entryDir = path.dirname(filePath);
   for (const module of options.modules) {
+    const importSpecifier = resolveEntryImportSpecifier(module.specifier, requireFromRoot, entryDir);
     if (module.defaultExport) {
-      statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
+      statements.push(`import __ecopages_default_export__ from '${importSpecifier}';`);
       statements.push("export default __ecopages_default_export__;");
     }
     const exportNames = getModuleExportNames(module.specifier, requireFromRoot).filter(
       (name) => !seenExports.has(name)
     );
     if (exportNames.length > 0) {
-      statements.push(`export { ${exportNames.join(", ")} } from '${module.specifier}';`);
+      statements.push(`export { ${exportNames.join(", ")} } from '${importSpecifier}';`);
       for (const exportName of exportNames) {
         seenExports.add(exportName);
       }
     }
   }
-  const filePath = path.join(artifactsDir, options.fileName);
-  fs.writeFileSync(filePath, statements.join("\n"), "utf-8");
+  const content = statements.join("\n");
+  if (!fs.existsSync(filePath) || fs.readFileSync(filePath, "utf-8") !== content) {
+    fs.writeFileSync(filePath, content, "utf-8");
+  }
   return filePath;
 }
+function resolveEntryImportSpecifier(specifier, requireFromRoot, entryDir) {
+  if (specifier.startsWith("node:") || specifier.startsWith("file:")) {
+    return specifier;
+  }
+  const resolvedPath = requireFromRoot.resolve(specifier);
+  let relativePath = path.relative(entryDir, resolvedPath).replace(/\\/g, "/");
+  if (!relativePath.startsWith(".")) {
+    relativePath = `./${relativePath}`;
+  }
+  return relativePath;
+}
 function getModuleExportNames(specifier, requireFromRoot) {
   const moduleExports = requireFromRoot(specifier);
   return Object.keys(moduleExports).filter((name) => name !== "__esModule" && name !== "default").filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name)).sort();

package/src/services/assets/asset-processing-service/processors/script/file-script.processor.js

@@ -20,20 +20,38 @@ class FileScriptProcessor extends BaseScriptProcessor {
   }
   async process(dep) {
     if (this.hmrManager?.isEnabled() && !dep.inline) {
-      const outputUrl = await this.hmrManager.registerScriptEntrypoint(dep.filepath);
-      const outputFilepath = this.resolveHmrOutputFilepath(dep.filepath);
-      return {
-        filepath: outputFilepath ?? dep.filepath,
-        sourceFilepath: dep.filepath,
-        srcUrl: outputUrl,
-        kind: "script",
-        position: dep.position,
-        attributes: dep.attributes,
-        inline: false,
-        excludeFromHtml: dep.excludeFromHtml,
-        packageRole: dep.packageRole,
-        bundledSourceFilepaths: dep.bundledSourceFilepaths
-      };
+      const resolvedOutput = this.hmrManager.getResolvedScriptOutput?.(dep.filepath);
+      if (resolvedOutput) {
+        return {
+          filepath: resolvedOutput.outputPath,
+          sourceFilepath: dep.filepath,
+          srcUrl: resolvedOutput.outputUrl,
+          kind: "script",
+          position: dep.position,
+          attributes: dep.attributes,
+          inline: false,
+          excludeFromHtml: dep.excludeFromHtml,
+          packageRole: dep.packageRole,
+          bundledSourceFilepaths: dep.bundledSourceFilepaths
+        };
+      }
+      try {
+        const outputUrl = await this.hmrManager.registerScriptEntrypoint(dep.filepath);
+        const outputFilepath = this.resolveHmrOutputFilepath(dep.filepath);
+        return {
+          filepath: outputFilepath ?? dep.filepath,
+          sourceFilepath: dep.filepath,
+          srcUrl: outputUrl,
+          kind: "script",
+          position: dep.position,
+          attributes: dep.attributes,
+          inline: false,
+          excludeFromHtml: dep.excludeFromHtml,
+          packageRole: dep.packageRole,
+          bundledSourceFilepaths: dep.bundledSourceFilepaths
+        };
+      } catch {
+      }
     }
     const content = fileSystem.readFileSync(dep.filepath);
     const shouldBundle = this.shouldBundle(dep);

package/src/services/assets/asset-processing-service/processors/script/node-module-script.processor.js

@@ -8,19 +8,33 @@ class NodeModuleScriptProcessor extends BaseScriptProcessor {
     const modulePath = this.resolveModulePath(dep.importPath, this.appConfig.rootDir);
     const moduleName = path.basename(modulePath);
     const filename = dep.name ?? `nm-${moduleName}`;
+    const shouldBundle = this.shouldBundle(dep);
     const configHash = this.generateHash(
-      JSON.stringify({ inline: dep.inline, minify: !dep.inline && this.isProduction, opts: dep.bundleOptions })
+      JSON.stringify({
+        bundle: shouldBundle,
+        inline: dep.inline,
+        minify: shouldBundle && !dep.inline && this.isProduction,
+        opts: dep.bundleOptions
+      })
     );
     const cachekey = `${this.buildCacheKey(filename, this.generateHash(modulePath), dep)}:${configHash}`;
     return this.getOrProcess(cachekey, async () => {
-      if (dep.inline) {
+      if (dep.inline || !shouldBundle) {
         const content = fileSystem.readFileAsBuffer(modulePath).toString();
+        const filepath = dep.inline ? void 0 : path.join(this.getAssetsDir(), "vendors", filename);
+        if (filepath) {
+          fileSystem.ensureDir(path.dirname(filepath));
+          if (!fileSystem.exists(filepath) || fileSystem.readFileAsBuffer(filepath).toString() !== content) {
+            fileSystem.copyFile(modulePath, filepath);
+          }
+        }
         return {
+          filepath,
           content,
           kind: dep.kind,
           position: dep.position,
           attributes: dep.attributes,
-          inline: true,
+          inline: dep.inline,
           excludeFromHtml: dep.excludeFromHtml,
           packageRole: dep.packageRole,
           bundledSourceFilepaths: dep.bundledSourceFilepaths

package/src/services/assets/asset-processing-service/processors/stylesheet/content-stylesheet.processor.d.ts

@@ -1,8 +1,5 @@
 import type { ContentStylesheetAsset, ProcessedAsset } from '../../assets.types.js';
 import { BaseProcessor } from '../base/base-processor.js';
 export declare class ContentStylesheetProcessor extends BaseProcessor<ContentStylesheetAsset> {
-    private static readonly PROCESSABLE_STYLESHEET_EXTENSIONS;
-    private isProcessableStylesheet;
-    private applyStylesheetProcessors;
     process(dep: ContentStylesheetAsset): Promise<ProcessedAsset>;
 }

package/src/services/assets/asset-processing-service/processors/stylesheet/content-stylesheet.processor.js

@@ -1,40 +1,11 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { BaseProcessor } from "../base/base-processor.js";
+import { applyStylesheetProcessors } from "./stylesheet-processor-pipeline.js";
 class ContentStylesheetProcessor extends BaseProcessor {
-  static PROCESSABLE_STYLESHEET_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
-  isProcessableStylesheet(filepath) {
-    return ContentStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
-  }
-  async applyStylesheetProcessors(content, filepath) {
-    if (!this.isProcessableStylesheet(filepath)) {
-      return content;
-    }
-    let transformedContent = content;
-    const processors = this.appConfig.processors ? Array.from(this.appConfig.processors.values()) : [];
-    for (const processor of processors) {
-      const hasCapabilities = processor.getAssetCapabilities().length > 0;
-      const canProcessStylesheet = processor.canProcessAsset("stylesheet", filepath);
-      if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes("postcss"))) {
-        continue;
-      }
-      if (!processor.matchesFileFilter(filepath)) {
-        continue;
-      }
-      const result = await processor.process(transformedContent, filepath);
-      if (typeof result === "string") {
-        transformedContent = result;
-        continue;
-      }
-      if (result instanceof Buffer) {
-        transformedContent = result.toString();
-      }
-    }
-    return transformedContent;
-  }
   async process(dep) {
     const virtualFilepath = path.join(this.appConfig.absolutePaths.distDir, "styles", "page-bundle.css");
-    const processedContent = await this.applyStylesheetProcessors(dep.content, virtualFilepath);
+    const processedContent = await applyStylesheetProcessors(this.appConfig, dep.content, virtualFilepath);
     const hash = this.generateHash(processedContent);
     const filename = `style-${hash}.css`;
     const cachekey = this.buildCacheKey(filename, hash, dep);

package/src/services/assets/asset-processing-service/processors/stylesheet/file-stylesheet.processor.d.ts

@@ -1,9 +1,6 @@
 import type { FileStylesheetAsset, ProcessedAsset } from '../../assets.types.js';
 import { BaseProcessor } from '../base/base-processor.js';
 export declare class FileStylesheetProcessor extends BaseProcessor<FileStylesheetAsset> {
-    private static readonly PROCESSABLE_STYLESHEET_EXTENSIONS;
     getStyleContent: (srcUrl: string) => Buffer;
-    private isProcessableStylesheet;
-    private applyStylesheetProcessors;
     process(dep: FileStylesheetAsset): Promise<ProcessedAsset>;
 }

package/src/services/assets/asset-processing-service/processors/stylesheet/file-stylesheet.processor.js

@@ -1,43 +1,15 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { BaseProcessor } from "../base/base-processor.js";
+import { applyStylesheetProcessors } from "./stylesheet-processor-pipeline.js";
 class FileStylesheetProcessor extends BaseProcessor {
-  static PROCESSABLE_STYLESHEET_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
   getStyleContent = (srcUrl) => {
     return fileSystem.readFileAsBuffer(srcUrl);
   };
-  isProcessableStylesheet(filepath) {
-    return FileStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
-  }
-  async applyStylesheetProcessors(content, filepath) {
-    if (!this.isProcessableStylesheet(filepath)) {
-      return content;
-    }
-    let transformedContent = content;
-    for (const processor of this.appConfig.processors.values()) {
-      const hasCapabilities = processor.getAssetCapabilities().length > 0;
-      const canProcessStylesheet = processor.canProcessAsset("stylesheet", filepath);
-      if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes("postcss"))) {
-        continue;
-      }
-      if (!processor.matchesFileFilter(filepath)) {
-        continue;
-      }
-      const result = await processor.process(transformedContent, filepath);
-      if (typeof result === "string") {
-        transformedContent = result;
-        continue;
-      }
-      if (result instanceof Buffer) {
-        transformedContent = result.toString();
-      }
-    }
-    return transformedContent;
-  }
   async process(dep) {
     const buffer = this.getStyleContent(dep.filepath);
     const rawContent = buffer.toString();
-    const processedContent = await this.applyStylesheetProcessors(rawContent, dep.filepath);
+    const processedContent = await applyStylesheetProcessors(this.appConfig, rawContent, dep.filepath);
     const hash = this.generateHash(processedContent);
     const cachekey = this.buildCacheKey(dep.filepath, hash, dep);
     return this.getOrProcess(cachekey, () => {

package/src/services/assets/asset-processing-service/processors/stylesheet/stylesheet-processor-pipeline.d.ts

@@ -0,0 +1,2 @@
+import type { EcoPagesAppConfig } from '../../../../../types/internal-types.js';
+export declare function applyStylesheetProcessors(appConfig: EcoPagesAppConfig, content: string, filepath: string): Promise<string>;

package/src/services/assets/asset-processing-service/processors/stylesheet/stylesheet-processor-pipeline.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+const PROCESSABLE_STYLESHEET_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
+function isProcessableStylesheet(filepath) {
+  return PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
+}
+function shouldRunStylesheetProcessor(processor, filepath) {
+  const hasCapabilities = processor.getAssetCapabilities().length > 0;
+  const canProcessStylesheet = processor.canProcessAsset("stylesheet", filepath);
+  if (canProcessStylesheet) {
+    return true;
+  }
+  if (hasCapabilities) {
+    return false;
+  }
+  return processor.getName().includes("postcss");
+}
+async function applyStylesheetProcessors(appConfig, content, filepath) {
+  if (!isProcessableStylesheet(filepath)) {
+    return content;
+  }
+  let transformedContent = content;
+  const processors = appConfig.processors ? Array.from(appConfig.processors.values()) : [];
+  for (const processor of processors) {
+    if (!shouldRunStylesheetProcessor(processor, filepath)) {
+      continue;
+    }
+    if (!processor.matchesFileFilter(filepath)) {
+      continue;
+    }
+    const result = await processor.process(transformedContent, filepath);
+    if (typeof result === "string") {
+      transformedContent = result;
+      continue;
+    }
+    if (result instanceof Buffer) {
+      transformedContent = result.toString();
+    }
+  }
+  return transformedContent;
+}
+export {
+  applyStylesheetProcessors
+};

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

@@ -16,6 +16,7 @@ export type BrowserBundleOptions = {
     externalPackages?: boolean;
     external?: string[];
     plugins?: EcoBuildPlugin[];
+    executor?: 'build' | 'hmr';
     [key: string]: unknown;
     profile: BuildTranspileProfile;
     excludeAppBuildPlugins?: string[];
@@ -65,7 +66,8 @@ export declare class BrowserBundleService implements BrowserBundleExecutor {
      * @remarks
      * Browser defaults and app-owned browser build plugins are applied here so HMR
      * and runtime asset generation do not have to recreate that policy at each call
-     * site.
+     * site. Also forwards {@link getAppSourceTransforms | app source transforms} so
+     * metadata injection runs after boundary/runtime `onLoad` rewrites.
      */
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
     bundleGroupedEntries(entries: BrowserBundleGroupedEntry[], options: BrowserBundleGroupedOptions): Promise<BuildResult>;

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

@@ -1,5 +1,14 @@
-import { getAppBrowserBuildPlugins, getAppBuildExecutor, getAppTranspileOptions } from "../../build/build-adapter.js";
+import { getAppBrowserBuildPlugins, getAppTranspileOptions } from "../../build/build-adapter.js";
+import { requireBuildRuntime } from "../../build/build-runtime.js";
 import { mergeEcoBuildPlugins } from "../../build/build-manifest.js";
+import { getAppSourceTransforms } from "../../plugins/source-transform.js";
+function resolveBrowserBundleExecutor(appConfig, profile, executor) {
+  const buildRuntime = requireBuildRuntime(appConfig);
+  if (executor === "hmr" && profile === "hmr-entrypoint") {
+    return buildRuntime.getProfile("browser-hmr");
+  }
+  return buildRuntime.getProfile("route-module");
+}
 class BrowserBundleService {
   appConfig;
   /**
@@ -14,19 +23,22 @@ class BrowserBundleService {
    * @remarks
    * Browser defaults and app-owned browser build plugins are applied here so HMR
    * and runtime asset generation do not have to recreate that policy at each call
-   * site.
+   * site. Also forwards {@link getAppSourceTransforms | app source transforms} so
+   * metadata injection runs after boundary/runtime `onLoad` rewrites.
    */
   async bundle(options) {
-    const { profile, excludeAppBuildPlugins, plugins, ...rawBuildOptions } = options;
+    const { profile, excludeAppBuildPlugins, plugins, executor = "hmr", ...rawBuildOptions } = options;
     const appBrowserPlugins = getAppBrowserBuildPlugins(this.appConfig);
     const filteredAppBrowserPlugins = excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0 ? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name)) : appBrowserPlugins;
     const request = {
       ...rawBuildOptions,
       entrypoints: options.entrypoints,
       ...getAppTranspileOptions(this.appConfig, profile),
-      plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins)
+      plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins),
+      sourceTransforms: getAppSourceTransforms(this.appConfig)
     };
-    return await getAppBuildExecutor(this.appConfig).build(request);
+    const buildExecutor = resolveBrowserBundleExecutor(this.appConfig, profile, executor);
+    return await buildExecutor.build(request);
   }
   async bundleGroupedEntries(entries, options) {
     const request = {

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

@@ -83,7 +83,7 @@ export declare class HtmlTransformerService {
      * string-based fallback remains in place for runtimes that cannot provide one
      * of those rewriter implementations.
      */
-    transform(res: Response, contributions?: HtmlDocumentContribution[]): Promise<Response>;
+    transform(res: Response, contributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<Response>;
     /**
      * Splits processed assets into head and body injection groups.
      */

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

@@ -188,8 +188,8 @@ class HtmlTransformerService {
    * string-based fallback remains in place for runtimes that cannot provide one
    * of those rewriter implementations.
    */
-  async transform(res, contributions = []) {
-    const { head, body } = this.groupDependenciesByPosition();
+  async transform(res, contributions = [], pagePackage) {
+    const { head, body } = this.groupDependenciesByPosition(pagePackage);
     const { headPrepend, headAppend, bodyPrepend, bodyAppend } = this.groupContributionsByPlacement(contributions);
     const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
     if (htmlRewriter) {
@@ -239,8 +239,8 @@ class HtmlTransformerService {
   /**
    * Splits processed assets into head and body injection groups.
    */
-  groupDependenciesByPosition() {
-    const dependencies = this.pagePackage ? this.resolvePagePackageHtmlDependencies(this.pagePackage) : this.processedDependencies;
+  groupDependenciesByPosition(pagePackageOverride) {
+    const dependencies = pagePackageOverride ? this.resolvePagePackageHtmlDependencies(pagePackageOverride) : this.pagePackage ? this.resolvePagePackageHtmlDependencies(this.pagePackage) : this.processedDependencies;
     return dependencies.reduce(
       (acc, dep) => {
         if (dep.kind === "script") {

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

@@ -1,5 +1,5 @@
 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';
+export type DevelopmentInvalidationCategory = 'public-asset' | 'additional-watch' | 'include-source' | 'explicit-server-view' | 'route-source' | 'processor-owned-asset' | 'server-source' | 'other';
 /**
  * Framework-owned invalidation plan for one changed file.
  *
@@ -62,6 +62,15 @@ export declare class DevelopmentInvalidationService {
      * Returns whether the file is an include/template source file.
      */
     isIncludeSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether the file is an explicit server-rendered view module.
+     *
+     * @remarks
+     * These modules are typically registered through `renderServerModule` in
+     * `app.ts` rather than the filesystem router. They need a full browser reload
+     * because their HTML is produced on the server, not through client HMR entrypoints.
+     */
+    isExplicitServerViewFile(filePath: string): boolean;
     /**
      * Returns whether the file is a server-executed source module outside the
      * special route/include buckets.

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

@@ -55,8 +55,18 @@ class DevelopmentInvalidationService {
         category: "include-source",
         invalidateServerModules: true,
         refreshRoutes: false,
-        reloadBrowser: true,
-        delegateToHmr: false,
+        reloadBrowser: false,
+        delegateToHmr: true,
+        processorHandledAsset: false
+      };
+    }
+    if (this.isExplicitServerViewFile(filePath)) {
+      return {
+        category: "explicit-server-view",
+        invalidateServerModules: true,
+        refreshRoutes: false,
+        reloadBrowser: false,
+        delegateToHmr: true,
         processorHandledAsset: false
       };
     }
@@ -148,6 +158,25 @@ class DevelopmentInvalidationService {
     }
     return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
   }
+  /**
+   * Returns whether the file is an explicit server-rendered view module.
+   *
+   * @remarks
+   * These modules are typically registered through `renderServerModule` in
+   * `app.ts` rather than the filesystem router. They need a full browser reload
+   * because their HTML is produced on the server, not through client HMR entrypoints.
+   */
+  isExplicitServerViewFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    const viewsDir = path.join(this.appConfig.absolutePaths.srcDir, "views");
+    if (resolvedPath !== viewsDir && !resolvedPath.startsWith(`${viewsDir}${path.sep}`)) {
+      return false;
+    }
+    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+      return true;
+    }
+    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+  }
   /**
    * Returns whether the file is a server-executed source module outside the
    * special route/include buckets.

package/src/services/module-loading/README.md

@@ -0,0 +1,49 @@
+# Module Loading
+
+Server-side source loading for framework-owned page modules, includes, and related templates.
+
+## Import stack
+
+```
+Call site (route scan, renderer, SSG, API)
+  └─ AppModuleLoader.importModule()          app-server-module-transpiler.service.ts
+       ├─ merges server build plugins + JSX ownership plugins
+       ├─ resolves route-module BuildExecutor
+       └─ PageModuleImportService.importModule()
+            ├─ dev + host loader → host runtime (Node only, when configured)
+            ├─ production disk cache → route-module build cache
+            ├─ unified pages graph → prebuilt chunk import
+            └─ Rolldown per-page build → dynamic import of transpiled output
+```
+
+`ServerModuleTranspiler` is a thin wrapper that injects `rootDir`, optional default plugins, and invalidation version into the same `PageModuleImportService` path. App code should prefer `getAppModuleLoader(appConfig)` or `getAppServerModuleTranspiler(appConfig)`.
+
+## Host vs app ownership
+
+| Path                    | When                                                                                         |
+| ----------------------- | -------------------------------------------------------------------------------------------- |
+| Host loader             | `appConfig.runtime.hostModuleLoader` set (Vite host) and file supports direct source loading |
+| Ecopages build pipeline | Framework-owned template files under `pages/`, `includes/`, etc.                             |
+
+`shouldAppUseHostModuleLoader()` encodes the directory + extension rules. Bun always uses the build pipeline today.
+
+## Caching layers
+
+1. **In-memory promise cache** (`PageModuleImportService.importCache`) — keyed by file path, resolved `outdir`, JSX/plugin inputs, file hash, and invalidation version. Cleared by `invalidateDevelopmentGraph()`.
+2. **Disk transpile cache** (`.eco/.server-modules/.build-cache.json`) — production only; see route-module build cache slice.
+3. **Unified graph manifest** — production static export fast path; see build layer docs.
+
+## Files
+
+| File                                      | Role                                                      |
+| ----------------------------------------- | --------------------------------------------------------- |
+| `page-module-import.service.ts`           | Core import/cache/build orchestration                     |
+| `app-module-loader.service.ts`            | App-facing loader interface                               |
+| `app-server-module-transpiler.service.ts` | Factory for app-scoped loader + transpiler                |
+| `server-module-transpiler.service.ts`     | Injectable transpiler boundary for tests and bootstrap    |
+| `host-module-loader-registry.ts`          | Process-global host loader fallback for embedded runtimes |
+| `source-module-support.ts`                | Extension allowlist for host direct loading               |
+
+## Development invalidation
+
+`DevelopmentInvalidationService.invalidateServerModules()` bumps the app-owned invalidation version and calls `appModuleLoader.invalidateDevelopmentGraph()`, which clears the in-memory import cache and increments the per-service invalidation counter used in cache keys and dev `?update=` query params.

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

@@ -1,5 +1,6 @@
-import { getAppBuildExecutor, getAppServerBuildPlugins } from "../../build/build-adapter.js";
-import { createForeignJsxOverridePlugin } from "../../plugins/foreign-jsx-override-plugin.js";
+import { getAppServerBuildPlugins } from "../../build/build-adapter.js";
+import { requireBuildRuntime } from "../../build/build-runtime.js";
+import { getJsxOwnershipPlugins } from "../../build/jsx-ownership-plugins.js";
 import path from "node:path";
 import { DevelopmentInvalidationService } from "../invalidation/development-invalidation.service.js";
 import {} from "./app-module-loader.service.js";
@@ -37,22 +38,9 @@ function setAppHostModuleLoader(appConfig, hostModuleLoader) {
     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({
+  const pageModuleImportService = new PageModuleImportService(appConfig, {
     canLoadSourceModuleFromHost: (filePath) => shouldAppUseHostModuleLoader(appConfig, filePath),
     getHostModuleLoader: () => getAppHostModuleLoader(appConfig)
   });
@@ -69,7 +57,7 @@ function createAppModuleLoader(appConfig) {
       return await pageModuleImportService.importModule({
         ...options,
         ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
-        buildExecutor: options.buildExecutor ?? getAppBuildExecutor(appConfig),
+        buildExecutor: options.buildExecutor ?? requireBuildRuntime(appConfig).getProfile("route-module"),
         invalidationVersion
       });
     },

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

@@ -1,5 +1,6 @@
 import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { SourceModuleLoaderFactory } from './module-loading-types.js';
 interface PageModuleImportBaseOptions {
     filePath: string;
@@ -59,10 +60,11 @@ export interface PageModuleImportDependencies {
  * transpilation settings, and error semantics across the different callers.
  */
 export declare class PageModuleImportService {
+    private readonly appConfig?;
     private readonly dependencies;
     private readonly importCache;
     private developmentInvalidationVersion;
-    constructor(dependencies?: Partial<PageModuleImportDependencies>);
+    constructor(appConfig?: EcoPagesAppConfig, dependencies?: Partial<PageModuleImportDependencies>);
     /**
      * Clears the shared import cache used by framework-owned page-module loads.
      */
@@ -91,5 +93,6 @@ export declare class PageModuleImportService {
      */
     importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
     private loadModule;
+    private getRouteModuleBuildCache;
 }
 export {};