@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

package/src/adapters/shared/file-route-middleware-pipeline.d.ts

@@ -1,8 +1,6 @@
-import type { Middleware, ApiHandlerContext, RequestLocals } from '../../public-types.js';
+import type { FileRouteMiddleware, FileRouteMiddlewareContext, RequestLocals } from '../../types/public-types.js';
 import type { PageCacheService } from '../../services/cache/page-cache-service.js';
 export declare const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS: {
-    readonly CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware";
-    readonly CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware";
     readonly middlewareRequiresDynamic: (filePath: string) => string;
 };
 /**
@@ -26,7 +24,7 @@ export declare class FileRouteMiddlewarePipeline {
      * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
      */
     assertValidConfiguration(input: {
-        middleware: Middleware[];
+        middleware: FileRouteMiddleware[];
         pageCacheStrategy: 'static' | 'dynamic' | {
             revalidate: number;
             tags?: string[];
@@ -36,9 +34,8 @@ export declare class FileRouteMiddlewarePipeline {
     /**
      * Creates the request-scoped middleware context used by page middleware.
      *
-     * The context intentionally disables `render()` and `renderPartial()` inside
-     * file-route middleware because rendering is owned by the page route pipeline,
-     * not by middleware stages.
+     * The context intentionally omits `render()` and `renderPartial()` because
+     * rendering is owned by the page route pipeline, not by middleware stages.
      *
      * @param input Request details and the mutable locals store.
      * @returns Middleware execution context.
@@ -47,7 +44,7 @@ export declare class FileRouteMiddlewarePipeline {
         request: Request;
         params: Record<string, string>;
         locals: RequestLocals;
-    }): ApiHandlerContext;
+    }): FileRouteMiddlewareContext;
     /**
      * Runs the middleware chain and eventually delegates to the render callback.
      *
@@ -58,8 +55,8 @@ export declare class FileRouteMiddlewarePipeline {
      * @returns Response from middleware or final render stage.
      */
     run(input: {
-        middleware: Middleware[];
-        context: ApiHandlerContext;
+        middleware: FileRouteMiddleware[];
+        context: FileRouteMiddlewareContext;
         renderResponse: () => Promise<Response>;
     }): Promise<Response>;
 }

package/src/adapters/shared/file-route-middleware-pipeline.js

@@ -2,8 +2,6 @@ import { createRequire } from "../../utils/locals-utils.js";
 import { ApiResponseBuilder } from "./api-response.js";
 import { LocalsAccessError } from "../../errors/locals-access-error.js";
 const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
-  CTX_RENDER_UNAVAILABLE: "[ecopages] ctx.render is not available in file-route middleware",
-  CTX_RENDER_PARTIAL_UNAVAILABLE: "[ecopages] ctx.renderPartial is not available in file-route middleware",
   middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`
 };
 class FileRouteMiddlewarePipeline {
@@ -30,9 +28,8 @@ class FileRouteMiddlewarePipeline {
   /**
    * Creates the request-scoped middleware context used by page middleware.
    *
-   * The context intentionally disables `render()` and `renderPartial()` inside
-   * file-route middleware because rendering is owned by the page route pipeline,
-   * not by middleware stages.
+   * The context intentionally omits `render()` and `renderPartial()` because
+   * rendering is owned by the page route pipeline, not by middleware stages.
    *
    * @param input Request details and the mutable locals store.
    * @returns Middleware execution context.
@@ -48,12 +45,6 @@ class FileRouteMiddlewarePipeline {
       },
       locals: input.locals,
       require: createRequire(() => context.locals),
-      render: async () => {
-        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_UNAVAILABLE);
-      },
-      renderPartial: async () => {
-        throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_PARTIAL_UNAVAILABLE);
-      },
       json: (data, options) => {
         const builder = new ApiResponseBuilder();
         if (options?.status) builder.status(options.status);

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

@@ -1,19 +1,23 @@
-import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../internal-types.js';
-import type { RouteRendererBody } from '../../public-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { FileSystemServerOptions } from '../../types/internal-types.js';
+import type { RouteRendererBody } from '../../types/public-types.js';
+/**
+ * Builds HTTP responses for static files and shared file-system fallbacks.
+ */
 export declare class FileSystemServerResponseFactory {
-    private appConfig;
-    private routeRendererFactory;
     private options;
-    constructor({ appConfig, routeRendererFactory, options, }: {
-        appConfig: EcoPagesAppConfig;
-        routeRendererFactory: RouteRendererFactory;
+    constructor({ options }: {
         options: FileSystemServerOptions;
     });
     isHtml(contentType: string): contentType is "text/html";
     shouldEnableGzip(contentType: string): boolean;
     createResponseWithBody(body: RouteRendererBody, init?: ResponseInit): Promise<Response>;
     createDefaultNotFoundResponse(): Promise<Response>;
-    createCustomNotFoundResponse(): Promise<Response>;
-    createFileResponse(filePath: string, contentType: string): Promise<Response>;
+    /**
+     * Wraps already-rendered HTML in a 404 response envelope.
+     */
+    createHtmlNotFoundResponse(body: RouteRendererBody): Promise<Response>;
+    /**
+     * Reads a static file response, returning `null` when the file is missing.
+     */
+    createFileResponse(filePath: string, contentType: string): Promise<Response | null>;
 }

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

@@ -1,17 +1,9 @@
-import { STATUS_MESSAGE } from "../../constants.js";
+import { STATUS_MESSAGE } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
 class FileSystemServerResponseFactory {
-  appConfig;
-  routeRendererFactory;
   options;
-  constructor({
-    appConfig,
-    routeRendererFactory,
-    options
-  }) {
-    this.appConfig = appConfig;
-    this.routeRendererFactory = routeRendererFactory;
+  constructor({ options }) {
     this.options = options;
   }
   isHtml(contentType) {
@@ -34,22 +26,11 @@ class FileSystemServerResponseFactory {
       status: 404
     });
   }
-  async createCustomNotFoundResponse() {
-    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
-    try {
-      fileSystem.verifyFileExists(error404TemplatePath);
-    } catch {
-      appLogger.debug(
-        "Custom 404 template not found, falling back to default 404 response",
-        error404TemplatePath
-      );
-      return this.createDefaultNotFoundResponse();
-    }
-    const routeRenderer = this.routeRendererFactory.createRenderer(error404TemplatePath);
-    const result = await routeRenderer.createRoute({
-      file: error404TemplatePath
-    });
-    return await this.createResponseWithBody(result.body, {
+  /**
+   * Wraps already-rendered HTML in a 404 response envelope.
+   */
+  async createHtmlNotFoundResponse(body) {
+    return await this.createResponseWithBody(body, {
       status: 404,
       statusText: STATUS_MESSAGE[404],
       headers: {
@@ -57,6 +38,9 @@ class FileSystemServerResponseFactory {
       }
     });
   }
+  /**
+   * Reads a static file response, returning `null` when the file is missing.
+   */
   async createFileResponse(filePath, contentType) {
     try {
       let file;
@@ -88,7 +72,7 @@ class FileSystemServerResponseFactory {
       } else {
         appLogger.error("Error reading file", filePath, err);
       }
-      return this.createCustomNotFoundResponse();
+      return null;
     }
   }
 }

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

@@ -1,17 +1,14 @@
-import type { EcoPagesAppConfig, MatchResult } from '../../internal-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import type { FSRouter } from '../../router/server/fs-router.js';
+import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.js';
+import type { PageRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { RouteRegistry } from '../../router/server/route-registry.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;
-    routeRendererFactory: RouteRendererFactory;
+    assetPrefix: string;
+    router: RouteRegistry;
+    routeRendererFactory: PageRendererResolver;
     fileSystemResponseFactory: FileSystemServerResponseFactory;
     /** Optional cache service. When null, caching is disabled. */
     cacheService?: PageCacheService | null;
@@ -21,24 +18,22 @@ 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,
+ * This render pipeline coordinates page module inspection, request-local policy,
  * renderer invocation, middleware execution, cache integration, and fallback
  * error translation.
  */
 export declare class FileSystemResponseMatcher {
     private appConfig;
+    private assetPrefix;
     private router;
     private routeRendererFactory;
     private fileSystemResponseFactory;
-    private serverModuleTranspiler;
     private pageRequestCacheCoordinator;
     private fileRouteMiddlewarePipeline;
-    constructor({ appConfig, router, routeRendererFactory, fileSystemResponseFactory, cacheService, defaultCacheStrategy, }: FileSystemResponseMatcherOptions);
+    constructor({ appConfig, assetPrefix, 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.
      */
@@ -55,14 +50,19 @@ export declare class FileSystemResponseMatcher {
      * @returns Final response for the matched route.
      */
     handleMatch(match: MatchResult, request?: Request): Promise<Response>;
+    /**
+     * Renders the app-owned custom 404 page, falling back to the default text 404
+     * when the page template cannot be resolved.
+     */
+    private renderCustomNotFoundResponse;
+    private createExecutionPlan;
     /**
      * 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,26 +1,21 @@
 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;
+  assetPrefix;
   router;
   routeRendererFactory;
   fileSystemResponseFactory;
-  serverModuleTranspiler;
   pageRequestCacheCoordinator;
   fileRouteMiddlewarePipeline;
   constructor({
     appConfig,
+    assetPrefix,
     router,
     routeRendererFactory,
     fileSystemResponseFactory,
@@ -28,29 +23,29 @@ class FileSystemResponseMatcher {
     defaultCacheStrategy = "static"
   }) {
     this.appConfig = appConfig;
+    this.assetPrefix = assetPrefix;
     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.
    */
   async handleNoMatch(requestUrl) {
     const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
     if (!isStaticFileRequest) {
-      return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+      return this.renderCustomNotFoundResponse();
     }
     const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
-    const filePath = path.join(this.router.assetPrefix, relativeUrl);
+    const filePath = path.join(this.assetPrefix, relativeUrl);
     const contentType = ServerUtils.getContentType(filePath);
-    return this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+    const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+    return response ?? this.renderCustomNotFoundResponse();
   }
   /**
    * Handles a matched file-system page route.
@@ -64,34 +59,25 @@ class FileSystemResponseMatcher {
    * @returns Final response for the matched route.
    */
   async handleMatch(match, request) {
-    const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey(match);
     try {
-      const resolvedRequest = request ?? new Request(new URL(cacheKey, this.router.origin).toString(), {
-        method: "GET"
-      });
-      const localsStore = {};
-      const pageModule = await this.importPageModule(match.filePath);
-      const Page = pageModule?.default;
-      const pageMiddleware = Page?.middleware ?? [];
-      const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-      const localsForRender = pageCacheStrategy === "dynamic" ? localsStore : void 0;
+      const executionPlan = await this.createExecutionPlan(match, request);
       this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-        middleware: pageMiddleware,
-        pageCacheStrategy,
-        filePath: match.filePath
+        middleware: executionPlan.pageMiddleware,
+        pageCacheStrategy: executionPlan.pageCacheStrategy,
+        filePath: executionPlan.pageFilePath
       });
-      const routeRenderer = this.routeRendererFactory.createRenderer(match.filePath);
+      const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
       const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-        request: resolvedRequest,
+        request: executionPlan.request,
         params: match.params,
-        locals: localsStore
+        locals: executionPlan.localsStore
       });
       const renderFn = async () => {
-        const result = await routeRenderer.createRoute({
-          file: match.filePath,
+        const result = await routeRenderer.execute({
+          file: executionPlan.pageFilePath,
           params: match.params,
           query: match.query,
-          locals: localsForRender
+          locals: executionPlan.localsForRender
         });
         const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
         const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
@@ -99,13 +85,13 @@ class FileSystemResponseMatcher {
       };
       const renderResponse = async () => {
         return this.pageRequestCacheCoordinator.render({
-          cacheKey,
-          pageCacheStrategy,
+          cacheKey: executionPlan.cacheKey,
+          pageCacheStrategy: executionPlan.pageCacheStrategy,
           renderFn
         });
       };
       return await this.fileRouteMiddlewarePipeline.run({
-        middleware: pageMiddleware,
+        middleware: executionPlan.pageMiddleware,
         context: middlewareContext,
         renderResponse
       });
@@ -121,30 +107,71 @@ class FileSystemResponseMatcher {
       }
       if (error instanceof Error) {
         if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.pathname}`);
+          appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.requestedPathname}`);
         }
       }
-      return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+      return this.renderCustomNotFoundResponse();
+    }
+  }
+  /**
+   * Renders the app-owned custom 404 page, falling back to the default text 404
+   * when the page template cannot be resolved.
+   */
+  async renderCustomNotFoundResponse() {
+    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    try {
+      const routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
+      const result = await routeRenderer.execute({
+        file: error404TemplatePath
+      });
+      return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+    } catch {
+      appLogger.debug(
+        "Custom 404 template not found, falling back to default 404 response",
+        error404TemplatePath
+      );
+      return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
     }
   }
+  async createExecutionPlan(match, request) {
+    const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({
+      pathname: match.requestedPathname,
+      query: match.query
+    });
+    const resolvedRequest = request ?? new Request(new URL(cacheKey, this.router.origin).toString(), {
+      method: "GET"
+    });
+    const localsStore = {};
+    const pageFilePath = match.templateRoute.filePath;
+    const pageModule = await this.importPageModule(pageFilePath);
+    const Page = pageModule?.default;
+    const pageMiddleware = Page?.middleware ?? [];
+    const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+    return {
+      cacheKey,
+      request: resolvedRequest,
+      pageFilePath,
+      pageMiddleware,
+      pageCacheStrategy,
+      localsStore,
+      localsForRender: pageCacheStrategy === "dynamic" ? localsStore : void 0
+    };
+  }
   /**
    * 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.getPageRenderer(filePath);
+    return routeRenderer.loadPageModule(filePath, {
+      cacheScope: "request-metadata"
     });
   }
   /**
@@ -155,6 +182,5 @@ class FileSystemResponseMatcher {
   }
 }
 export {
-  FILE_SYSTEM_RESPONSE_MATCHER_ERRORS,
   FileSystemResponseMatcher
 };

package/src/adapters/shared/hmr-entrypoint-registrar.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { appLogger } from "../../global/app-logger.js";
-import { RESOLVED_ASSETS_DIR } from "../../constants.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
 class HmrEntrypointRegistrar {
   options;
   constructor(options) {

package/src/adapters/shared/hmr-html-response.d.ts

@@ -1,4 +1,4 @@
-import type { IHmrManager } from '../../public-types';
+import type { IHmrManager } from '../../types/public-types.js';
 /**
  * Returns whether a response is HTML and therefore eligible for development HMR
  * runtime injection.

package/src/adapters/shared/hmr-html-response.js

@@ -9,16 +9,17 @@ function shouldInjectHmrHtmlResponse(watch, hmrManager) {
 }
 async function injectHmrRuntimeIntoHtmlResponse(response) {
   const html = await response.text();
+  const headers = new Headers(response.headers);
+  headers.set("Cache-Control", "no-store, must-revalidate");
+  headers.delete("Content-Length");
   if (html.includes(HMR_RUNTIME_IMPORT)) {
     return new Response(html, {
       status: response.status,
       statusText: response.statusText,
-      headers: response.headers
+      headers
     });
   }
   const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
-  const headers = new Headers(response.headers);
-  headers.delete("Content-Length");
   return new Response(updatedHtml, {
     status: response.status,
     statusText: response.statusText,

package/src/adapters/shared/render-context.d.ts

@@ -1,7 +1,9 @@
-import type { RenderContext } from '../../public-types.js';
-import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { RenderContext } from '../../types/public-types.js';
+import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
-    integrations: IntegrationPlugin[];
+    integrations: AnyIntegrationPlugin[];
+    rendererModules?: unknown;
+    importServerModule?: (filePath: string) => Promise<unknown>;
 }
 /**
  * Creates a render context for route handlers.

package/src/adapters/shared/render-context.js

@@ -1,4 +1,8 @@
+import { fileURLToPath } from "node:url";
 import { invariant } from "../../utils/invariant.js";
+function resolveServerModulePath(filePath) {
+  return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+}
 function mergePropsWithLocals(props, locals) {
   if (!locals || typeof props !== "object" || props === null) {
     return props;
@@ -15,9 +19,28 @@ function createRenderContext(options) {
     );
     const integration = integrations.find((i) => i.name === integrationName);
     invariant(!!integration, `No integration found for: ${integrationName}`);
-    return integration.initializeRenderer();
+    return integration.initializeRenderer({
+      rendererModules: options.rendererModules
+    });
   };
   const renderContext = {
+    importServerModule: async (filePath) => {
+      invariant(!!options.importServerModule, "Server module importing is not available in this render context.");
+      return await options.importServerModule(resolveServerModulePath(filePath));
+    },
+    async renderServerModule(filePath, props, renderOptions) {
+      const module = await renderContext.importServerModule(filePath);
+      const view = module.default;
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: false,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return await renderer.renderToResponse(view, mergedProps, ctx);
+    },
     async render(view, props, renderOptions) {
       const locals = this?.locals;
       const mergedProps = mergePropsWithLocals(props ?? {}, locals);

package/src/adapters/shared/runtime-app-bootstrap.d.ts

@@ -0,0 +1,26 @@
+import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type RuntimeBinding = {
+    preferredPort: number;
+    preferredHostname: string;
+    runtimeOrigin: string;
+    serveOptions: Record<string, unknown>;
+    watch: boolean;
+};
+export type StaticRuntimeMode = {
+    requiresFetchRuntime: boolean;
+    canBuildWithoutRuntimeServer: boolean;
+};
+export declare function resolveServeRuntimeOrigin(serveOptions: {
+    hostname?: string;
+    port?: number | string;
+}): string;
+export declare function resolveRuntimeBinding(options: {
+    cliArgs: ReturnParseCliArgs;
+    serverOptions?: Record<string, unknown>;
+    env?: NodeJS.ProcessEnv;
+}): RuntimeBinding;
+export declare function resolveStaticRuntimeMode(options: {
+    appConfig: EcoPagesAppConfig;
+    cliArgs: ReturnParseCliArgs;
+}): StaticRuntimeMode;

package/src/adapters/shared/runtime-app-bootstrap.js

@@ -0,0 +1,46 @@
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+function normalizeOriginHostname(hostname) {
+  if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
+    return `[${hostname}]`;
+  }
+  return hostname;
+}
+function resolveServeRuntimeOrigin(serveOptions) {
+  const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
+  const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+  return `http://${hostname}:${port}`;
+}
+function resolveRuntimeBinding(options) {
+  const env = options.env ?? process.env;
+  const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
+  const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
+  return {
+    preferredPort,
+    preferredHostname,
+    runtimeOrigin: resolveServeRuntimeOrigin({
+      hostname: preferredHostname,
+      port: preferredPort
+    }),
+    serveOptions: {
+      port: preferredPort,
+      hostname: preferredHostname,
+      ...options.serverOptions ?? {}
+    },
+    watch: options.cliArgs.dev
+  };
+}
+function resolveStaticRuntimeMode(options) {
+  const requiresFetchRuntime = options.appConfig.integrations.some(
+    (integration) => integration.staticBuildStep === "fetch"
+  );
+  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
+  return {
+    requiresFetchRuntime,
+    canBuildWithoutRuntimeServer
+  };
+}
+export {
+  resolveRuntimeBinding,
+  resolveServeRuntimeOrigin,
+  resolveStaticRuntimeMode
+};

package/src/adapters/shared/runtime-host.d.ts

@@ -0,0 +1,12 @@
+export interface RuntimeHost<TServer, TServeOptions> {
+    start(options: RuntimeHostStartOptions<TServeOptions>): Promise<TServer>;
+    stop(server: TServer, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    getOrigin(server: TServer, fallbackServeOptions: TServeOptions): string;
+}
+export interface RuntimeHostStartOptions<TServeOptions> {
+    serveOptions: TServeOptions;
+    handleRequest(request: Request): Promise<Response>;
+    onError(error: Error): Promise<void> | void;
+}