@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.28

package/src/adapters/node/node-hmr-manager.js

@@ -15,7 +15,6 @@ import {
   InMemoryEntrypointDependencyGraph,
   setAppEntrypointDependencyGraph
 } from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
-import { getAppRuntimeSpecifierRegistry } from "../../services/runtime-state/runtime-specifier-registry.service.js";
 import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
 class NodeHmrManager {
   static entrypointRegistrationTimeoutMs = 4e3;
@@ -31,7 +30,6 @@ class NodeHmrManager {
   entrypointRegistrar;
   browserBundleService;
   entrypointDependencyGraph;
-  runtimeSpecifierRegistry;
   serverModuleTranspiler;
   constructor({ appConfig, bridge }) {
     this.appConfig = appConfig;
@@ -49,7 +47,6 @@ class NodeHmrManager {
     const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
     this.entrypointDependencyGraph = existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new InMemoryEntrypointDependencyGraph();
     setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
-    this.runtimeSpecifierRegistry = getAppRuntimeSpecifierRegistry(this.appConfig);
     this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
     this.cleanDistDir();
     this.initializeStrategies();
@@ -87,7 +84,6 @@ class NodeHmrManager {
   initializeStrategies() {
     const jsContext = {
       getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
       getDistDir: () => this.distDir,
       getPlugins: () => this.plugins,
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
@@ -112,18 +108,6 @@ class NodeHmrManager {
   isEnabled() {
     return this.enabled;
   }
-  /**
-   * Registers runtime bare-specifier mappings exposed by integrations.
-   *
-   * @remarks
-   * These mappings are consumed by framework-owned HMR strategies such as the
-   * React integration strategy when they rewrite browser bundles. The registry
-   * stays generic so the same mappings can support broader import-map-style
-   * runtime features later without moving integration semantics into core.
-   */
-  registerSpecifierMap(map) {
-    this.runtimeSpecifierRegistry.register(map);
-  }
   async buildRuntime() {
     const runtimeSource = path.resolve(import.meta.dirname, "../../hmr/client/hmr-runtime.js");
     try {
@@ -184,9 +168,6 @@ class NodeHmrManager {
   getWatchedFiles() {
     return this.watchedFiles;
   }
-  getSpecifierMap() {
-    return this.runtimeSpecifierRegistry.getAll();
-  }
   getDistDir() {
     return this.distDir;
   }
@@ -196,7 +177,6 @@ class NodeHmrManager {
   getDefaultContext() {
     return {
       getWatchedFiles: () => this.watchedFiles,
-      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
       getDistDir: () => this.distDir,
       getPlugins: () => this.plugins,
       getSrcDir: () => this.appConfig.absolutePaths.srcDir,
@@ -291,8 +271,8 @@ class NodeHmrManager {
    * @remarks
    * The manager intentionally does not remove emitted `_hmr` files from disk
    * because multiple app processes may share the same dist directory during test
-   * runs. It does clear in-memory indexes so old entrypoints, dependencies, and
-   * specifier maps cannot leak across a reused manager instance.
+   * runs. It does clear in-memory indexes so old entrypoints and dependencies
+   * cannot leak across a reused manager instance.
    */
   stop() {
     this.entrypointRegistrations.clear();
@@ -301,7 +281,6 @@ class NodeHmrManager {
     }
     this.watchers.clear();
     this.watchedFiles.clear();
-    this.runtimeSpecifierRegistry.clear();
     this.entrypointDependencyGraph.reset();
     this.plugins = [];
   }

package/src/adapters/shared/explicit-static-render-preparation.d.ts

@@ -0,0 +1,25 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { EcoFunctionComponent, EcoPageComponent } from '../../types/public-types.js';
+import type { ExplicitViewRenderer, ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
+type ExplicitStaticRenderPreparationResult = {
+    renderer: ExplicitViewRenderer;
+    props: Record<string, unknown>;
+    view: EcoFunctionComponent<Record<string, unknown>, any>;
+};
+/**
+ * Resolves the renderer and static props needed to render one explicit static
+ * view at runtime or during static generation.
+ */
+export declare function prepareExplicitStaticRender(input: {
+    routePath: string;
+    view: EcoPageComponent<any>;
+    params: Record<string, string | string[]>;
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    routeRendererFactory: ExplicitViewRendererResolver;
+    errors: {
+        missingIntegration(routePath: string): string;
+        noRendererForIntegration(integrationName: string): string;
+    };
+}): Promise<ExplicitStaticRenderPreparationResult>;
+export {};

package/src/adapters/shared/explicit-static-render-preparation.js

@@ -0,0 +1,26 @@
+function getViewIntegrationName(view) {
+  return view.config?.integration ?? view.config?.__eco?.integration;
+}
+async function prepareExplicitStaticRender(input) {
+  const integrationName = getViewIntegrationName(input.view);
+  if (!integrationName) {
+    throw new Error(input.errors.missingIntegration(input.routePath));
+  }
+  const renderer = input.routeRendererFactory.getExplicitViewRenderer(integrationName);
+  if (!renderer) {
+    throw new Error(input.errors.noRendererForIntegration(integrationName));
+  }
+  const props = input.view.staticProps ? (await input.view.staticProps({
+    pathname: { params: input.params },
+    appConfig: input.appConfig,
+    runtimeOrigin: input.runtimeOrigin
+  })).props : {};
+  return {
+    renderer,
+    props,
+    view: input.view
+  };
+}
+export {
+  prepareExplicitStaticRender
+};

package/src/adapters/shared/explicit-static-route-matcher.d.ts

@@ -1,19 +1,22 @@
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { StaticRoute } from '../../types/public-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
 export declare const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS: {
     readonly missingIntegration: (routePath: string) => string;
     readonly noRendererForIntegration: (integrationName: string) => string;
 };
 export interface ExplicitStaticRouteMatcherOptions {
     appConfig: EcoPagesAppConfig;
-    routeRendererFactory: RouteRendererFactory;
+    routeRendererFactory: ExplicitViewRendererResolver;
     staticRoutes: StaticRoute[];
 }
 export interface ExplicitRouteMatch {
     route: StaticRoute;
     params: Record<string, string>;
 }
+/**
+ * Matches and renders explicit static routes declared through `app.static()`.
+ */
 export declare class ExplicitStaticRouteMatcher {
     private readonly appConfig;
     private readonly routeRendererFactory;

package/src/adapters/shared/explicit-static-route-matcher.js

@@ -1,11 +1,9 @@
 import { appLogger } from "../../global/app-logger.js";
+import { prepareExplicitStaticRender } from "./explicit-static-render-preparation.js";
 const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
   missingIntegration: (routePath) => `View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page() and exported as default.`,
   noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`
 };
-function getViewIntegrationName(view) {
-  return view.config?.integration ?? view.config?.__eco?.integration;
-}
 class ExplicitStaticRouteMatcher {
   appConfig;
   routeRendererFactory;
@@ -74,20 +72,20 @@ class ExplicitStaticRouteMatcher {
     try {
       const mod = await route.loader();
       const view = mod.default;
-      const integrationName = getViewIntegrationName(view);
-      if (!integrationName) {
-        throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.missingIntegration(route.path));
-      }
-      const renderer = this.routeRendererFactory.getRendererByIntegration(integrationName);
-      if (!renderer) {
-        throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.noRendererForIntegration(integrationName));
-      }
-      const props = view.staticProps ? (await view.staticProps({
-        pathname: { params },
+      const {
+        renderer,
+        props,
+        view: renderableView
+      } = await prepareExplicitStaticRender({
+        routePath: route.path,
+        view,
+        params,
         appConfig: this.appConfig,
-        runtimeOrigin: this.appConfig.baseUrl
-      })).props : {};
-      return renderer.renderToResponse(view, props, {});
+        runtimeOrigin: this.appConfig.baseUrl,
+        routeRendererFactory: this.routeRendererFactory,
+        errors: EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS
+      });
+      return renderer.renderToResponse(renderableView, props, {});
     } catch (error) {
       appLogger.error(
         `Error rendering explicit static route ${route.path}:`,

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

@@ -1,8 +1,6 @@
-import type { Middleware, ApiHandlerContext, RequestLocals } from '../../types/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 '../../types/internal-types.js';
+import type { FileSystemServerOptions } from '../../types/internal-types.js';
 import type { RouteRendererBody } from '../../types/public-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.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

@@ -2,16 +2,8 @@ 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,13 +1,14 @@
 import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.js';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
-import type { FSRouter } from '../../router/server/fs-router.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 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;
@@ -17,18 +18,19 @@ export interface FileSystemResponseMatcherOptions {
 /**
  * Matches file-system routes to rendered HTML responses.
  *
- * 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 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.
@@ -48,6 +50,12 @@ 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.
      *

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

@@ -7,6 +7,7 @@ import { LocalsAccessError } from "../../errors/locals-access-error.js";
 import { isDevelopmentRuntime } from "../../utils/runtime.js";
 class FileSystemResponseMatcher {
   appConfig;
+  assetPrefix;
   router;
   routeRendererFactory;
   fileSystemResponseFactory;
@@ -14,6 +15,7 @@ class FileSystemResponseMatcher {
   fileRouteMiddlewarePipeline;
   constructor({
     appConfig,
+    assetPrefix,
     router,
     routeRendererFactory,
     fileSystemResponseFactory,
@@ -21,6 +23,7 @@ class FileSystemResponseMatcher {
     defaultCacheStrategy = "static"
   }) {
     this.appConfig = appConfig;
+    this.assetPrefix = assetPrefix;
     this.router = router;
     this.routeRendererFactory = routeRendererFactory;
     this.fileSystemResponseFactory = fileSystemResponseFactory;
@@ -36,12 +39,13 @@ class FileSystemResponseMatcher {
   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.
@@ -55,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();
@@ -90,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
       });
@@ -112,12 +107,56 @@ 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.
    *
@@ -130,7 +169,7 @@ class FileSystemResponseMatcher {
    * @returns Imported page module.
    */
   async importPageModule(filePath) {
-    const routeRenderer = this.routeRendererFactory.createRenderer(filePath);
+    const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
     return routeRenderer.loadPageModule(filePath, {
       cacheScope: "request-metadata"
     });

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

@@ -1,7 +1,7 @@
 import type { RenderContext } from '../../types/public-types.js';
-import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
-    integrations: IntegrationPlugin[];
+    integrations: AnyIntegrationPlugin[];
     rendererModules?: unknown;
 }
 /**