@ecopages/core 0.2.0-alpha.13 → 0.2.0-alpha.15

package/CHANGELOG.md

@@ -14,12 +14,17 @@ All notable changes to `@ecopages/core` are documented here.
 
 - Consolidated runtime state around shared module-loading services, app-owned build execution, and the universal `createApp()` boundary.
 - Simplified route-renderer orchestration around renderer-owned boundary runtimes, shared string-boundary queue helpers, and a smaller component render context.
+- Centralized shared integration renderer bootstrapping so package integrations only append renderer-specific config instead of duplicating core lifecycle wiring.
 - Removed marker-era compatibility capture, the shared route-level fallback resolver, deprecated `@ecopages/core/node*` escape hatches, and other dead route-renderer internals.
 
 ### Bug Fixes
 
 - Fixed mixed-integration page, layout, document, and component rendering to resolve foreign boundaries inside their owning renderer across the built-in integrations.
 - Fixed host/runtime module loading, published build-helper exports, asset output normalization, explicit render flows, and static or preview build stability across Bun, Node, Vite, and Nitro.
+- Fixed request-time and static-generation page inspection to preserve integration-specific page loading without reusing the normal render module identity.
+- Fixed Node preview and static-generation React runtime resolution so app-owned page modules and server rendering share one React module identity.
+- Fixed Bun HMR script output normalization so multi-entrypoint browser builds preserve the expected outbase-relative source paths for emitted files.
+- Fixed render-preparation graph traversal so sparse component dependency arrays do not break custom 404 rendering or file-system response fallback flows.
 
 ### Documentation
 
@@ -28,6 +33,7 @@ All notable changes to `@ecopages/core` are documented here.
 ### Tests
 
 - Added regression coverage for app-owned runtime services, Node fallback paths, and cross-runtime invalidation behavior.
+- Strengthened the core ghtml integration tests so route and explicit render paths await real outcomes and cover `renderToResponse` behavior.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.13",
+  "version": "0.2.0-alpha.15",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.13",
+    "@ecopages/file-system": "0.2.0-alpha.15",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",

package/src/adapters/shared/fs-server-response-matcher.d.ts

@@ -4,10 +4,6 @@ import type { FSRouter } from '../../router/server/fs-router.js';
 import type { PageCacheService } from '../../services/cache/page-cache-service.js';
 import type { CacheStrategy } from '../../services/cache/cache.types.js';
 import type { FileSystemServerResponseFactory } from './fs-server-response-factory.js';
-export declare const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS: {
-    readonly transpilePageModuleFailed: (details: string) => string;
-    readonly noTranspiledOutputForPageModule: (filePath: string) => string;
-};
 export interface FileSystemResponseMatcherOptions {
     appConfig: EcoPagesAppConfig;
     router: FSRouter;
@@ -21,7 +17,6 @@ export interface FileSystemResponseMatcherOptions {
 /**
  * Matches file-system routes to rendered HTML responses.
  *
- * This class sits at the request-time boundary between router matches and the
  * render pipeline. It coordinates page module inspection, request-local policy,
  * renderer invocation, middleware execution, cache integration, and fallback
  * error translation.
@@ -31,14 +26,12 @@ export declare class FileSystemResponseMatcher {
     private router;
     private routeRendererFactory;
     private fileSystemResponseFactory;
-    private serverModuleTranspiler;
     private pageRequestCacheCoordinator;
     private fileRouteMiddlewarePipeline;
     constructor({ appConfig, router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
     /**
      * Resolves unmatched paths either as static asset requests or as the custom
      * not-found page.
-     *
      * @param requestUrl Incoming pathname.
      * @returns Static file response or rendered 404 response.
      */
@@ -59,10 +52,9 @@ export declare class FileSystemResponseMatcher {
      * Loads the matched page module for request-time inspection.
      *
      * The matcher needs access to page-level metadata such as `cache` and
-     * `middleware` before full rendering starts, so it uses the shared module
-     * import service directly rather than going through route rendering. The
-     * app config is injected explicitly so build ownership stays at the adapter
-     * boundary instead of leaking through nested router collaborators.
+     * `middleware` before full rendering starts, so it asks the owning route
+     * renderer to load the page module. That preserves integration-specific page
+     * import setup for request-time inspection as well as for full rendering.
      *
      * @param filePath Absolute page module path.
      * @returns Imported page module.

package/src/adapters/shared/fs-server-response-matcher.js

@@ -1,22 +1,15 @@
 import path from "node:path";
 import { appLogger } from "../../global/app-logger.js";
 import { PageRequestCacheCoordinator } from "../../services/cache/page-request-cache-coordinator.service.js";
-import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
-import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
 import { ServerUtils } from "../../utils/server-utils.module.js";
 import { FileRouteMiddlewarePipeline } from "./file-route-middleware-pipeline.js";
 import { LocalsAccessError } from "../../errors/locals-access-error.js";
 import { isDevelopmentRuntime } from "../../utils/runtime.js";
-const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS = {
-  transpilePageModuleFailed: (details) => `Error transpiling page module: ${details}`,
-  noTranspiledOutputForPageModule: (filePath) => `No transpiled output generated for page module: ${filePath}`
-};
 class FileSystemResponseMatcher {
   appConfig;
   router;
   routeRendererFactory;
   fileSystemResponseFactory;
-  serverModuleTranspiler;
   pageRequestCacheCoordinator;
   fileRouteMiddlewarePipeline;
   constructor({
@@ -31,14 +24,12 @@ class FileSystemResponseMatcher {
     this.router = router;
     this.routeRendererFactory = routeRendererFactory;
     this.fileSystemResponseFactory = fileSystemResponseFactory;
-    this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
     this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
     this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
   }
   /**
    * Resolves unmatched paths either as static asset requests or as the custom
    * not-found page.
-   *
    * @param requestUrl Incoming pathname.
    * @returns Static file response or rendered 404 response.
    */
@@ -131,20 +122,17 @@ class FileSystemResponseMatcher {
    * Loads the matched page module for request-time inspection.
    *
    * The matcher needs access to page-level metadata such as `cache` and
-   * `middleware` before full rendering starts, so it uses the shared module
-   * import service directly rather than going through route rendering. The
-   * app config is injected explicitly so build ownership stays at the adapter
-   * boundary instead of leaking through nested router collaborators.
+   * `middleware` before full rendering starts, so it asks the owning route
+   * renderer to load the page module. That preserves integration-specific page
+   * import setup for request-time inspection as well as for full rendering.
    *
    * @param filePath Absolute page module path.
    * @returns Imported page module.
    */
   async importPageModule(filePath) {
-    return this.serverModuleTranspiler.importModule({
-      filePath,
-      outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules-meta"),
-      transpileErrorMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.transpilePageModuleFailed,
-      noOutputMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.noTranspiledOutputForPageModule
+    const routeRenderer = this.routeRendererFactory.createRenderer(filePath);
+    return routeRenderer.loadPageModule(filePath, {
+      cacheScope: "request-metadata"
     });
   }
   /**
@@ -155,6 +143,5 @@ class FileSystemResponseMatcher {
   }
 }
 export {
-  FILE_SYSTEM_RESPONSE_MATCHER_ERRORS,
   FileSystemResponseMatcher
 };

package/src/build/build-adapter.d.ts

@@ -110,6 +110,9 @@ export declare class BunBuildAdapter implements BuildAdapter {
     private resolveConcreteOutputPath;
     private resolveTemplatedOutputPath;
     private relocateOutputFile;
+    private createDeterministicOutputReference;
+    private collectDeterministicOutputReferences;
+    private hasJavaScriptExtension;
     private normalizeBunOutputs;
     private rewriteAliasedRuntimeSpecifiers;
     build(options: BuildOptions): Promise<BuildResult>;

package/src/build/build-adapter.js

@@ -275,37 +275,64 @@ class BunBuildAdapter {
     fs.renameSync(currentPath, targetPath);
     return targetPath;
   }
+  createDeterministicOutputReference(outputPath) {
+    return path.normalize(outputPath).replace(/\.(?:[cm]?js)$/u, "");
+  }
+  collectDeterministicOutputReferences(options, entrypointPath) {
+    const expectedOutputsByReference = /* @__PURE__ */ new Map();
+    const expectedOutputPath = this.resolveTemplatedOutputPath(options, entrypointPath);
+    if (!expectedOutputPath) {
+      return expectedOutputsByReference;
+    }
+    expectedOutputsByReference.set(this.createDeterministicOutputReference(expectedOutputPath), expectedOutputPath);
+    if (!options.outbase) {
+      return expectedOutputsByReference;
+    }
+    const bunRootRelativeOutputPath = this.resolveTemplatedOutputPath(
+      { ...options, outbase: void 0 },
+      entrypointPath
+    );
+    if (bunRootRelativeOutputPath && bunRootRelativeOutputPath !== expectedOutputPath) {
+      expectedOutputsByReference.set(
+        this.createDeterministicOutputReference(bunRootRelativeOutputPath),
+        expectedOutputPath
+      );
+    }
+    return expectedOutputsByReference;
+  }
+  hasJavaScriptExtension(outputPath) {
+    return /\.(?:[cm]?js)$/u.test(outputPath);
+  }
   normalizeBunOutputs(result, options) {
     if (!result.success || result.outputs.length === 0) {
       return result;
     }
     const normalizedOutputs = [...result.outputs];
-    const canMapEntrypointsByIndex = options.entrypoints.length === normalizedOutputs.length;
-    if (canMapEntrypointsByIndex) {
-      for (const [index, entrypointPath] of options.entrypoints.entries()) {
-        const concreteOutputPath = this.resolveConcreteOutputPath(normalizedOutputs[index].path);
-        const expectedOutputPath = this.resolveTemplatedOutputPath(options, entrypointPath, concreteOutputPath);
-        if (!expectedOutputPath) {
-          continue;
-        }
-        normalizedOutputs[index] = {
-          path: this.relocateOutputFile(
-            concreteOutputPath ?? normalizedOutputs[index].path,
-            expectedOutputPath
-          )
-        };
+    const expectedOutputsByReference = /* @__PURE__ */ new Map();
+    for (const entrypointPath of options.entrypoints) {
+      for (const [reference, expectedOutputPath] of this.collectDeterministicOutputReferences(
+        options,
+        entrypointPath
+      )) {
+        expectedOutputsByReference.set(reference, expectedOutputPath);
       }
-      return {
-        ...result,
-        outputs: normalizedOutputs
-      };
     }
     return {
       ...result,
       outputs: normalizedOutputs.map((output) => {
         const concreteOutputPath = this.resolveConcreteOutputPath(output.path) ?? output.path;
-        if (path.extname(concreteOutputPath) !== "") {
-          return output;
+        const expectedOutputPath = expectedOutputsByReference.get(
+          this.createDeterministicOutputReference(concreteOutputPath)
+        );
+        if (expectedOutputPath) {
+          return {
+            path: this.relocateOutputFile(concreteOutputPath, expectedOutputPath)
+          };
+        }
+        if (this.hasJavaScriptExtension(concreteOutputPath)) {
+          return {
+            path: concreteOutputPath
+          };
         }
         const normalizedPath = `${concreteOutputPath}.js`;
         return {

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

@@ -165,6 +165,22 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * Returns processed global assets resolved during `setup()`.
      */
     getResolvedIntegrationDependencies(): ProcessedAsset[];
+    /**
+     * Creates the shared renderer options owned by core lifecycle setup.
+     */
+    protected createRendererOptions(options?: {
+        rendererModules?: unknown;
+    }): {
+        appConfig: EcoPagesAppConfig;
+        assetProcessingService: AssetProcessingService;
+        resolvedIntegrationDependencies: ProcessedAsset[];
+        rendererModules: unknown;
+        runtimeOrigin: string;
+    };
+    /**
+     * Attaches runtime-only services after a renderer instance has been created.
+     */
+    protected attachRendererRuntimeServices<T extends IntegrationRenderer<C>>(renderer: T): T;
     /**
      * Instantiates the integration renderer with app-owned services.
      *
@@ -172,6 +188,7 @@ 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;

package/src/plugins/integration-plugin.js

@@ -112,14 +112,9 @@ class IntegrationPlugin {
     return this.resolvedIntegrationDependencies;
   }
   /**
-   * Instantiates the integration renderer with app-owned services.
-   *
-   * @remarks
-   * 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.
+   * Creates the shared renderer options owned by core lifecycle setup.
    */
-  initializeRenderer(options) {
+  createRendererOptions(options) {
     if (!this.appConfig) {
       throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
     }
@@ -127,19 +122,40 @@ class IntegrationPlugin {
     if (this.hmrManager) {
       assetProcessingService.setHmrManager(this.hmrManager);
     }
-    const renderer = new this.renderer({
+    return {
       appConfig: this.appConfig,
       assetProcessingService,
       resolvedIntegrationDependencies: this.resolvedIntegrationDependencies,
       rendererModules: options?.rendererModules,
       runtimeOrigin: this.runtimeOrigin
-    });
-    renderer.name ||= this.name;
+    };
+  }
+  /**
+   * Attaches runtime-only services after a renderer instance has been created.
+   */
+  attachRendererRuntimeServices(renderer) {
+    if (typeof renderer.name !== "string" || renderer.name.length === 0) {
+      renderer.name = this.name;
+    }
     if (this.hmrManager) {
       renderer.setHmrManager(this.hmrManager);
     }
     return renderer;
   }
+  /**
+   * Instantiates the integration renderer with app-owned services.
+   *
+   * @remarks
+   * 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));
+    renderer.name ||= this.name;
+    return this.attachRendererRuntimeServices(renderer);
+  }
   /**
    * Prepares build-facing contributions before the app build manifest is sealed.
    *

package/src/route-renderer/orchestration/integration-renderer.d.ts

@@ -18,6 +18,17 @@ type BoundaryRenderDecisionInput = {
     currentIntegration: string;
     targetIntegration?: string;
 };
+/**
+ * Controls how one route module is loaded outside the normal render path.
+ *
+ * Request-time metadata inspection and static-generation probes use these
+ * options to isolate their module identity from the main render cache while
+ * still going through the owning integration's import setup.
+ */
+export type RouteModuleLoadOptions = {
+    bypassCache?: boolean;
+    cacheScope?: string;
+};
 /**
  * Context for renderToResponse method.
  */
@@ -47,6 +58,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     protected renderExecutionService: RenderExecutionService;
     protected readonly queuedBoundaryRuntimeService: QueuedBoundaryRuntimeService;
     protected DOC_TYPE: string;
+    /**
+     * Loads one route module through the owning renderer's import path.
+     *
+     * Request-time infrastructure may need page metadata such as cache strategy or
+     * middleware before full rendering starts. Exposing this narrow entrypoint lets
+     * those callers reuse integration-specific import setup instead of bypassing it
+     * with raw transpiler access.
+     */
+    loadPageModule(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
     /**
      * Reads the execution-scoped foreign renderer cache from one boundary input.
      *
@@ -287,7 +307,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected getMetadataProps(getMetadata: GetMetadata | undefined, { props, params, query }: GetMetadataContext): Promise<PageMetadataProps>;
     protected usesIntegrationPageImporter(_file: string): boolean;
-    protected importIntegrationPageFile(_file: string): Promise<EcoPageFile>;
+    protected importIntegrationPageFile(_file: string, _options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
     protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(_file: string, pageModule: TPageModule): TPageModule;
     /**
      * Imports the page file from the specified path.
@@ -296,7 +316,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @param file - The file path to import.
      * @returns The imported module.
      */
-    protected importPageFile(file: string): Promise<EcoPageFile>;
+    protected importPageFile(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
     /**
      * Resolves the dependency path based on the component directory.
      * It combines the component directory with the provided path URL.

package/src/route-renderer/orchestration/integration-renderer.js

@@ -56,6 +56,17 @@ class IntegrationRenderer {
   renderExecutionService;
   queuedBoundaryRuntimeService = new QueuedBoundaryRuntimeService();
   DOC_TYPE = "<!DOCTYPE html>";
+  /**
+   * Loads one route module through the owning renderer's import path.
+   *
+   * Request-time infrastructure may need page metadata such as cache strategy or
+   * middleware before full rendering starts. Exposing this narrow entrypoint lets
+   * those callers reuse integration-specific import setup instead of bypassing it
+   * with raw transpiler access.
+   */
+  async loadPageModule(file, options) {
+    return this.importPageFile(file, options);
+  }
   /**
    * Reads the execution-scoped foreign renderer cache from one boundary input.
    *
@@ -531,7 +542,7 @@ class IntegrationRenderer {
   usesIntegrationPageImporter(_file) {
     return false;
   }
-  async importIntegrationPageFile(_file) {
+  async importIntegrationPageFile(_file, _options) {
     invariant(false, "Integration page importer must be implemented when enabled");
   }
   normalizeImportedPageFile(_file, pageModule) {
@@ -544,9 +555,15 @@ class IntegrationRenderer {
    * @param file - The file path to import.
    * @returns The imported module.
    */
-  async importPageFile(file) {
-    const bypassCache = typeof Bun !== "undefined" && process.env.NODE_ENV === "development";
-    const pageModule = this.usesIntegrationPageImporter(file) ? await this.importIntegrationPageFile(file) : await this.pageModuleLoaderService.importPageFile(file, { bypassCache });
+  async importPageFile(file, options) {
+    const bypassCache = options?.bypassCache ?? (typeof Bun !== "undefined" && process.env.NODE_ENV === "development");
+    const pageModule = this.usesIntegrationPageImporter(file) ? await this.importIntegrationPageFile(file, {
+      bypassCache,
+      cacheScope: options?.cacheScope
+    }) : await this.pageModuleLoaderService.importPageFile(file, {
+      bypassCache,
+      cacheScope: options?.cacheScope
+    });
     return this.normalizeImportedPageFile(file, pageModule);
   }
   /**
@@ -775,9 +792,11 @@ class IntegrationRenderer {
     if (!boundaryOwner) {
       return void 0;
     }
-    return await this.getIntegrationRendererForName(boundaryOwner, rendererCache).renderComponentBoundary(
-      this.withBoundaryRendererCache(input, rendererCache)
-    );
+    const owningRenderer = this.getIntegrationRendererForName(boundaryOwner, rendererCache);
+    if (owningRenderer === this || owningRenderer.name === this.name) {
+      return void 0;
+    }
+    return await owningRenderer.renderComponentBoundary(this.withBoundaryRendererCache(input, rendererCache));
   }
   /**
    * Renders one component under this integration's boundary runtime and resolves

package/src/route-renderer/orchestration/render-preparation.service.js

@@ -115,6 +115,9 @@ class RenderPreparationService {
   collectResolvedTriggers(components, seen = /* @__PURE__ */ new Set()) {
     const triggers = [];
     for (const comp of components) {
+      if (!comp) {
+        continue;
+      }
       const ecoComp = comp;
       if (seen.has(ecoComp)) {
         continue;
@@ -165,6 +168,9 @@ class RenderPreparationService {
   collectIntegrationNames(components, seen = /* @__PURE__ */ new Set()) {
     const integrationNames = /* @__PURE__ */ new Set();
     for (const comp of components) {
+      if (!comp) {
+        continue;
+      }
       const ecoComp = comp;
       if (seen.has(ecoComp)) {
         continue;

package/src/route-renderer/page-loading/page-module-loader.d.ts

@@ -29,6 +29,7 @@ export declare class PageModuleLoaderService {
      */
     importPageFile(file: string, options?: {
         bypassCache?: boolean;
+        cacheScope?: string;
     }): Promise<EcoPageFile>;
     /**
      * Executes the page's static-props hook with Ecopages runtime context.

package/src/route-renderer/page-loading/page-module-loader.js

@@ -30,6 +30,7 @@ class PageModuleLoaderService {
         rootDir: this.appConfig.rootDir,
         outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
         bypassCache: options?.bypassCache,
+        cacheScope: options?.cacheScope,
         transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
         noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`
       });

package/src/route-renderer/route-renderer.d.ts

@@ -1,7 +1,7 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
-import type { RouteRenderResult, RouteRendererOptions } from '../types/public-types.js';
-import type { IntegrationRenderer } from './orchestration/integration-renderer.js';
+import type { EcoPageFile, RouteRenderResult, RouteRendererOptions } from '../types/public-types.js';
+import type { IntegrationRenderer, RouteModuleLoadOptions } from './orchestration/integration-renderer.js';
 /**
  * Thin wrapper around one initialized integration renderer.
  *
@@ -20,6 +20,10 @@ export declare class RouteRenderer {
      * Executes the render pipeline for one matched route.
      */
     createRoute(options: RouteRendererOptions): Promise<RouteRenderResult>;
+    /**
+     * Loads the route module through the owning integration renderer.
+     */
+    loadPageModule(filePath: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
 }
 /**
  * Selects and caches integration renderers for route files and explicit views.

package/src/route-renderer/route-renderer.js

@@ -14,6 +14,12 @@ class RouteRenderer {
   async createRoute(options) {
     return this.renderer.execute(options);
   }
+  /**
+   * Loads the route module through the owning integration renderer.
+   */
+  async loadPageModule(filePath, options) {
+    return this.renderer.loadPageModule(filePath, options);
+  }
 }
 class RouteRendererFactory {
   appConfig;

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

@@ -1,5 +1,6 @@
 import { PageModuleImportService, type PageModuleImportDependencies, type PageModuleImportOptions } from './page-module-import.service.js';
 import type { BuildExecutor } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
 export type AppModuleLoaderOwner = 'bun' | 'host';
 export interface AppModuleLoader {
     readonly owner: AppModuleLoaderOwner;
@@ -9,6 +10,7 @@ export interface AppModuleLoader {
 export type AppModuleLoaderOptions = {
     dependencies?: Partial<PageModuleImportDependencies>;
     getBuildExecutor?: () => BuildExecutor | undefined;
+    getDefaultPlugins?: () => EcoBuildPlugin[];
     getOwner?: () => AppModuleLoaderOwner;
     getInvalidationVersion?: () => number | undefined;
     pageModuleImportService?: PageModuleImportService;
@@ -16,6 +18,7 @@ export type AppModuleLoaderOptions = {
 export declare class RuntimeAppModuleLoader implements AppModuleLoader {
     private readonly pageModuleImportService;
     private readonly getBuildExecutorValue;
+    private readonly getDefaultPluginsValue;
     private readonly getOwnerValue;
     private readonly getInvalidationVersionValue;
     constructor(options?: AppModuleLoaderOptions);

package/src/services/module-loading/app-module-loader.service.js

@@ -4,11 +4,13 @@ import {
 class RuntimeAppModuleLoader {
   pageModuleImportService;
   getBuildExecutorValue;
+  getDefaultPluginsValue;
   getOwnerValue;
   getInvalidationVersionValue;
   constructor(options = {}) {
     this.pageModuleImportService = options.pageModuleImportService ?? new PageModuleImportService(options.dependencies);
     this.getBuildExecutorValue = options.getBuildExecutor ?? (() => void 0);
+    this.getDefaultPluginsValue = options.getDefaultPlugins ?? (() => []);
     this.getOwnerValue = options.getOwner ?? (() => "bun");
     this.getInvalidationVersionValue = options.getInvalidationVersion ?? (() => void 0);
   }
@@ -16,8 +18,10 @@ class RuntimeAppModuleLoader {
     return this.getOwnerValue();
   }
   async importModule(options) {
+    const mergedPlugins = [...this.getDefaultPluginsValue(), ...options.plugins ?? []];
     return await this.pageModuleImportService.importModule({
       ...options,
+      ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
       buildExecutor: options.buildExecutor ?? this.getBuildExecutorValue(),
       invalidationVersion: options.invalidationVersion ?? this.getInvalidationVersionValue()
     });

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

@@ -49,6 +49,7 @@ function createAppModuleLoader(appConfig) {
       getHostModuleLoader: () => getAppHostModuleLoader(appConfig)
     },
     getBuildExecutor: () => getAppBuildExecutor(appConfig),
+    getDefaultPlugins: typeof Bun === "undefined" && appConfig.rootDir ? () => [createAppNodeBootstrapPlugin(appConfig)] : void 0,
     getOwner: () => getAppModuleLoaderOwner(appConfig),
     getInvalidationVersion: () => invalidationService.getServerModuleInvalidationVersion()
   });
@@ -77,8 +78,7 @@ function createAppServerModuleTranspiler(appConfig) {
     canLoadSourceModuleFromHost: (filePath) => shouldAppUseHostModuleLoader(appConfig, filePath),
     getInvalidationVersion: () => invalidationService.getServerModuleInvalidationVersion(),
     invalidateModules: (changedFiles) => invalidationService.invalidateServerModules(changedFiles),
-    pageModuleImportService: getAppModuleLoader(appConfig),
-    getDefaultPlugins: typeof Bun === "undefined" && appConfig.rootDir ? () => [createAppNodeBootstrapPlugin(appConfig)] : void 0
+    pageModuleImportService: getAppModuleLoader(appConfig)
   });
 }
 function getAppServerModuleTranspiler(appConfig) {

package/src/services/module-loading/node-bootstrap-plugin.d.ts

@@ -6,7 +6,15 @@ import type { EcoPagesAppConfig } from '../../types/internal-types.js';
  */
 export declare function getAppRuntimeNodeModulesDir(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>): string;
 export interface NodeBootstrapResolutionOptions {
+    /**
+     * App root used as the fallback package boundary when an importer does not
+     * live under a more specific package.json.
+     */
     projectDir: string;
+    /**
+     * Runtime-local node_modules directory that receives symlinks to resolved
+     * package roots so transpiled Node imports share one package graph.
+     */
     runtimeNodeModulesDir: string;
     preserveImportMetaPaths?: string[];
 }
@@ -16,7 +24,22 @@ export interface NodeBootstrapResolutionOptions {
  */
 export declare function getNodeUnsupportedBuiltinError(specifier: string, importer?: string): string;
 export declare function resolveNodeBootstrapDependency(args: Pick<EcoBuildOnResolveArgs, 'path' | 'importer'>, options: NodeBootstrapResolutionOptions): EcoBuildOnResolveResult | undefined;
+/**
+ * Creates the Node bootstrap plugin used by app-owned server module loads.
+ *
+ * The resolver anchors third-party imports to the nearest package boundary for
+ * the importing file, then mirrors the resolved package root into the runtime
+ * node_modules directory. That keeps transpiled Node execution aligned with the
+ * package graph each source file was authored against.
+ */
 export declare function createNodeBootstrapPlugin(options: NodeBootstrapResolutionOptions): EcoBuildPlugin;
+/**
+ * Creates the default Node bootstrap plugin for one Ecopages app runtime.
+ *
+ * This binds the shared resolution policy to the app's internal execution
+ * directory so transpiled server modules can externalize packages into one
+ * stable runtime node_modules graph.
+ */
 export declare function createAppNodeBootstrapPlugin(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>, options?: {
     preserveImportMetaPaths?: string[];
 }): EcoBuildPlugin;

package/src/services/module-loading/node-bootstrap-plugin.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { existsSync, mkdirSync, readFileSync, symlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
@@ -32,7 +32,10 @@ function ensureRuntimePackageLink(nodeModulesDir, specifier, resolvedPath) {
   const packageRoot = findPackageRoot(resolvedPath);
   const linkPath = path.join(nodeModulesDir, packageName);
   if (existsSync(linkPath)) {
-    return;
+    if (realpathSync(linkPath) === realpathSync(packageRoot)) {
+      return;
+    }
+    rmSync(linkPath, { recursive: true, force: true });
   }
   mkdirSync(path.dirname(linkPath), { recursive: true });
   symlinkSync(packageRoot, linkPath, "dir");
@@ -40,9 +43,6 @@ function ensureRuntimePackageLink(nodeModulesDir, specifier, resolvedPath) {
 function getNodeUnsupportedBuiltinError(specifier, importer) {
   return `Node bootstrap transpilation does not support Bun builtin specifier ${JSON.stringify(specifier)}${importer ? ` imported from ${importer}` : ""}.`;
 }
-function shouldResolveFromImporter(importer) {
-  return Boolean(importer && importer.includes(`${path.sep}node_modules${path.sep}`));
-}
 function resolveSpecifier(specifier, parentPath) {
   try {
     return createRequire(parentPath).resolve(specifier);
@@ -53,6 +53,23 @@ function resolveSpecifier(specifier, parentPath) {
 function resolveFromCore(specifier) {
   return createRequire(import.meta.url).resolve(specifier);
 }
+function findResolutionParent(importer, projectDir) {
+  if (!importer || !path.isAbsolute(importer)) {
+    return path.join(projectDir, "package.json");
+  }
+  let currentPath = path.dirname(importer);
+  while (true) {
+    const packageJsonPath = path.join(currentPath, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return packageJsonPath;
+    }
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      return path.join(projectDir, "package.json");
+    }
+    currentPath = parentPath;
+  }
+}
 function getBootstrapBuildLoaderForPath(filePath) {
   switch (path.extname(filePath).toLowerCase()) {
     case ".ts":
@@ -98,7 +115,7 @@ function resolveNodeBootstrapDependency(args, options) {
   if (args.path.startsWith("./") || args.path.startsWith("../") || args.path.startsWith("@/") || args.path.startsWith("/") || args.path.startsWith("node:")) {
     return void 0;
   }
-  const resolveParent = args.importer && path.isAbsolute(args.importer) && shouldResolveFromImporter(args.importer) ? args.importer : path.join(options.projectDir, "package.json");
+  const resolveParent = findResolutionParent(args.importer, options.projectDir);
   if (args.path.startsWith("@ecopages/")) {
     let resolvedPath2;
     try {

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

@@ -6,6 +6,7 @@ export interface PageModuleImportOptions {
     rootDir: string;
     outdir: string;
     bypassCache?: boolean;
+    cacheScope?: string;
     buildExecutor?: BuildExecutor;
     invalidationVersion?: number;
     splitting?: boolean;

package/src/services/module-loading/page-module-import.service.js

@@ -51,7 +51,7 @@ class PageModuleImportService {
     const fileHash = this.dependencies.hashFile(filePath);
     const hostModuleLoader = typeof Bun === "undefined" && process.env.NODE_ENV === "development" && this.dependencies.canLoadSourceModuleFromHost(filePath) ? this.dependencies.getHostModuleLoader() : void 0;
     if (hostModuleLoader) {
-      const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion);
+      const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, options.cacheScope);
       return await hostModuleLoader(sourceModuleUrl.href);
     }
     if (options.bypassCache) {
@@ -69,6 +69,7 @@ class PageModuleImportService {
       rootDir,
       splitting ?? "default",
       externalPackages ?? "default",
+      options.cacheScope ?? "default",
       fileHash,
       invalidationVersion
     ].join("::");
@@ -96,11 +97,12 @@ class PageModuleImportService {
       invalidationVersion = this.developmentInvalidationVersion,
       splitting,
       externalPackages,
+      cacheScope,
       transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
       noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
       fileHash
     } = options;
-    const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion);
+    const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope);
     if (typeof Bun !== "undefined") {
       return await import(
         /* @vite-ignore */
@@ -108,7 +110,8 @@ class PageModuleImportService {
       );
     }
     const fileBaseName = path.basename(filePath, path.extname(filePath));
-    const outputFileName = `${fileBaseName}-${fileHash}.js`;
+    const cacheScopeSuffix = cacheScope ? `-${sanitizeCacheScope(cacheScope)}` : "";
+    const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}.js`;
     const buildResult = await this.dependencies.buildModule(
       {
         entrypoints: [filePath],
@@ -136,8 +139,11 @@ class PageModuleImportService {
       throw new Error(noOutputMessage(filePath));
     }
     const compiledOutputUrl = pathToFileURL(compiledOutput);
-    if (process.env.NODE_ENV === "development") {
-      compiledOutputUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
+    if (process.env.NODE_ENV === "development" || cacheScope) {
+      compiledOutputUrl.searchParams.set(
+        "update",
+        [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : void 0].filter((value) => value !== void 0).join("-")
+      );
     }
     return await import(
       /* @vite-ignore */
@@ -145,13 +151,19 @@ class PageModuleImportService {
     );
   }
 }
-function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion) {
+function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope) {
   const moduleUrl = pathToFileURL(filePath);
-  if (process.env.NODE_ENV === "development") {
-    moduleUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
+  if (process.env.NODE_ENV === "development" || cacheScope) {
+    moduleUrl.searchParams.set(
+      "update",
+      [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : void 0].filter((value) => value !== void 0).join("-")
+    );
   }
   return moduleUrl;
 }
+function sanitizeCacheScope(cacheScope) {
+  return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
 function supportsHostSourceModuleLoading(filePath) {
   const extension = path.extname(filePath);
   return extension === ".js" || extension === ".jsx" || extension === ".ts" || extension === ".tsx" || extension === ".mjs" || extension === ".mts" || extension === ".cjs" || extension === ".cts";

package/src/static-site-generator/static-site-generator.d.ts

@@ -20,17 +20,12 @@ export declare const STATIC_SITE_GENERATOR_ERRORS: {
  */
 export declare class StaticSiteGenerator {
     appConfig: EcoPagesAppConfig;
-    private serverModuleTranspiler;
     /**
      * Creates the static-site generator for one app config.
      */
     constructor({ appConfig }: {
         appConfig: EcoPagesAppConfig;
     });
-    /**
-     * Returns the transpiler output directory used for static page-module probes.
-     */
-    private getStaticPageModuleOutdir;
     private getExportDir;
     /**
      * Logs the standardized warning emitted when a dynamic-cache page is skipped.

package/src/static-site-generator/static-site-generator.js

@@ -1,9 +1,7 @@
 import path from "node:path";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
 import { appLogger } from "../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
 import { PathUtils } from "../utils/path-utils.module.js";
-import { getAppServerModuleTranspiler } from "../services/module-loading/app-server-module-transpiler.service.js";
 const STATIC_SITE_GENERATOR_ERRORS = {
   ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy",
   unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
@@ -13,20 +11,11 @@ const STATIC_SITE_GENERATOR_ERRORS = {
 };
 class StaticSiteGenerator {
   appConfig;
-  serverModuleTranspiler;
   /**
    * Creates the static-site generator for one app config.
    */
   constructor({ appConfig }) {
     this.appConfig = appConfig;
-    this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
-  }
-  /**
-   * Returns the transpiler output directory used for static page-module probes.
-   */
-  getStaticPageModuleOutdir() {
-    const workDir = this.appConfig.absolutePaths?.workDir ?? path.join(this.appConfig.rootDir, this.appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
-    return path.join(workDir, ".server-static-page-modules");
   }
   getExportDir() {
     return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
@@ -44,13 +33,9 @@ class StaticSiteGenerator {
    * Determines whether one filesystem-discovered page should be excluded from
    * static generation.
    */
-  async shouldSkipStaticPageFile(filePath) {
-    const module = await this.serverModuleTranspiler.importModule({
-      filePath,
-      outdir: this.getStaticPageModuleOutdir(),
-      externalPackages: false,
-      transpileErrorMessage: (details) => `Error transpiling static page module: ${details}`,
-      noOutputMessage: (targetFilePath) => `No transpiled output generated for static page module: ${targetFilePath}`
+  async shouldSkipStaticPageFile(filePath, routeRendererFactory) {
+    const module = await routeRendererFactory.createRenderer(filePath).loadPageModule(filePath, {
+      cacheScope: "static-page-probe"
     });
     if (module.default?.cache !== "dynamic") {
       return false;
@@ -146,9 +131,6 @@ class StaticSiteGenerator {
     for (const route of routes) {
       try {
         const { filePath, pathname: routePathname } = router.routes[route];
-        if (await this.shouldSkipStaticPageFile(filePath)) {
-          continue;
-        }
         const ext = PathUtils.getEcoTemplateExtension(filePath);
         const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
         const strategy = integration?.staticBuildStep || "render";
@@ -165,6 +147,9 @@ class StaticSiteGenerator {
           if (!routeRendererFactory) {
             throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
           }
+          if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
+            continue;
+          }
           let pathname2 = routePathname;
           const pathnameSegments2 = pathname2.split("/").filter(Boolean);
           if (pathname2 === "/") {