@ecopages/core 0.2.0-beta.27 → 0.2.0-beta.29

package/README.md

@@ -267,7 +267,7 @@ Use these entrypoints when implementing integrations, processors, or source tran
 - `@ecopages/core/plugins/integration-plugin`
 - `@ecopages/core/plugins/processor`
 - `@ecopages/core/plugins/source-transform`
-- `@ecopages/core/route-renderer/integration-renderer`
+- `@ecopages/core/route-renderer/orchestration/integration-renderer`
 - `@ecopages/core/services/asset-processing-service`
 - `@ecopages/core/hmr/hmr-strategy`
 - `@ecopages/core/integrations/ghtml`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.27",
+  "version": "0.2.0-beta.29",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.27",
+    "@ecopages/file-system": "0.2.0-beta.29",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -44,11 +44,11 @@
       "types": "./src/adapters/create-app.d.ts",
       "default": "./src/adapters/create-app.js"
     },
-    "./route-renderer/integration-renderer": {
+    "./route-renderer/orchestration/integration-renderer": {
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
-    "./route-renderer/string-markup-renderer": {
+    "./route-renderer/orchestration/string-markup-renderer": {
       "types": "./src/route-renderer/orchestration/string-markup-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/string-markup-renderer.js"
     },
@@ -56,18 +56,26 @@
       "types": "./src/route-renderer/route-renderer.d.ts",
       "default": "./src/route-renderer/route-renderer.js"
     },
-    "./route-renderer/component-render-context": {
-      "import": "./src/route-renderer/orchestration/component-render-context.js",
-      "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
-      "default": "./src/route-renderer/orchestration/component-render-context.js"
+    "./route-renderer/orchestration/foreign-child/component-render-context": {
+      "import": "./src/route-renderer/orchestration/foreign-child/component-render-context.js",
+      "types": "./src/route-renderer/orchestration/foreign-child/component-render-context.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-child/component-render-context.js"
     },
-    "./route-renderer/orchestration/foreign-subtree-execution.service": {
-      "types": "./src/route-renderer/orchestration/foreign-subtree-execution.service.d.ts",
-      "default": "./src/route-renderer/orchestration/foreign-subtree-execution.service.js"
+    "./route-renderer/orchestration/foreign-child/foreign-subtree-execution.service": {
+      "types": "./src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.js"
     },
-    "./route-renderer/orchestration/document-shell-render.service": {
-      "types": "./src/route-renderer/orchestration/document-shell-render.service.d.ts",
-      "default": "./src/route-renderer/orchestration/document-shell-render.service.js"
+    "./route-renderer/orchestration/document-shell/document-shell-render.service": {
+      "types": "./src/route-renderer/orchestration/document-shell/document-shell-render.service.d.ts",
+      "default": "./src/route-renderer/orchestration/document-shell/document-shell-render.service.js"
+    },
+    "./route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils": {
+      "types": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.d.ts",
+      "default": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.js"
+    },
+    "./route-renderer/orchestration/foreign-child/owning-renderer-resolution": {
+      "types": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.js"
     },
     "./router/navigation-coordinator": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
@@ -269,11 +277,11 @@
       "types": "./src/adapters/create-app.d.ts",
       "default": "./src/adapters/create-app.js"
     },
-    "./route-renderer/integration-renderer.ts": {
+    "./route-renderer/orchestration/integration-renderer.ts": {
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
-    "./route-renderer/string-markup-renderer.ts": {
+    "./route-renderer/orchestration/string-markup-renderer.ts": {
       "types": "./src/route-renderer/orchestration/string-markup-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/string-markup-renderer.js"
     },
@@ -281,18 +289,26 @@
       "types": "./src/route-renderer/route-renderer.d.ts",
       "default": "./src/route-renderer/route-renderer.js"
     },
-    "./route-renderer/component-render-context.ts": {
-      "import": "./src/route-renderer/orchestration/component-render-context.js",
-      "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
-      "default": "./src/route-renderer/orchestration/component-render-context.js"
+    "./route-renderer/orchestration/foreign-child/component-render-context.ts": {
+      "import": "./src/route-renderer/orchestration/foreign-child/component-render-context.js",
+      "types": "./src/route-renderer/orchestration/foreign-child/component-render-context.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-child/component-render-context.js"
+    },
+    "./route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.ts": {
+      "types": "./src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.js"
+    },
+    "./route-renderer/orchestration/document-shell/document-shell-render.service.ts": {
+      "types": "./src/route-renderer/orchestration/document-shell/document-shell-render.service.d.ts",
+      "default": "./src/route-renderer/orchestration/document-shell/document-shell-render.service.js"
     },
-    "./route-renderer/orchestration/foreign-subtree-execution.service.ts": {
-      "types": "./src/route-renderer/orchestration/foreign-subtree-execution.service.d.ts",
-      "default": "./src/route-renderer/orchestration/foreign-subtree-execution.service.js"
+    "./route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.ts": {
+      "types": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.d.ts",
+      "default": "./src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.js"
     },
-    "./route-renderer/orchestration/document-shell-render.service.ts": {
-      "types": "./src/route-renderer/orchestration/document-shell-render.service.d.ts",
-      "default": "./src/route-renderer/orchestration/document-shell-render.service.js"
+    "./route-renderer/orchestration/foreign-child/owning-renderer-resolution.ts": {
+      "types": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.js"
     },
     "./router/navigation-coordinator.ts": {
       "types": "./src/router/client/navigation-coordinator.d.ts",

package/src/adapters/abstract/application-adapter.d.ts

@@ -8,7 +8,7 @@
  */
 import type { SourceModuleLoader } from '../../services/module-loading/module-loading-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
+import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader, EcopagesRouteInfo } from '../../types/public-types.js';
 import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
 import { type EcopagesRuntimeLabel } from '../../dev/runtime-server-started-message.js';
 import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
@@ -52,6 +52,15 @@ export interface ApplicationRuntimeOptions {
 }
 export interface AppStartInfo {
     origin: string;
+    /**
+     * Static-generation routes available when the runtime becomes ready.
+     *
+     * @remarks
+     * Empty when the server adapter has no route registry yet, or when route
+     * resolution fails (failures never block startup). Route resolution completes
+     * before the `onAppStart` callback runs.
+     */
+    routes: EcopagesRouteInfo[];
 }
 export type OnAppStartCallback = (info: AppStartInfo) => void;
 /** @deprecated Use {@link AppStartInfo}. */
@@ -82,7 +91,7 @@ export interface ApplicationAdapter<T = any> extends AsyncDisposable {
     /** Boot the server. Pass a callback to run when the runtime is ready (optional). */
     start(onAppStart?: OnAppStartCallback): Promise<T | void>;
     /** Invoked by embedded hosts once the app can take traffic. */
-    handleListening(origin: string): void;
+    handleListening(origin: string): void | Promise<void>;
     stop(force?: boolean): Promise<void>;
 }
 /**
@@ -272,8 +281,17 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
     /**
      * Invoked by embedded hosts (for example Vite) once the app can take traffic.
      */
-    handleListening(origin: string): void;
-    protected notifyListening(origin: string): void;
+    handleListening(origin: string): Promise<void>;
+    protected notifyListening(origin: string): Promise<void>;
+    /**
+     * Resolves routes exposed on {@link AppStartInfo}.
+     *
+     * @remarks
+     * Default is empty. Runtime adapters override this to read from the
+     * initialized server route registry.
+     */
+    protected resolveAppRoutes(): Promise<EcopagesRouteInfo[]>;
+    private invokeAppStartCallback;
     /**
      * Stops the application server and releases runtime resources.
      *

package/src/adapters/abstract/application-adapter.js

@@ -218,16 +218,39 @@ class AbstractApplicationAdapter {
   /**
    * Invoked by embedded hosts (for example Vite) once the app can take traffic.
    */
-  handleListening(origin) {
-    this.notifyListening(origin);
+  async handleListening(origin) {
+    await this.notifyListening(origin);
   }
-  notifyListening(origin) {
+  async notifyListening(origin) {
     const normalizedOrigin = origin.replace(/\/$/, "");
     startupTrace.markServerListening();
     if (!this.onAppStartCallback) {
       this.logServerStarted(normalizedOrigin);
+      return;
+    }
+    await this.invokeAppStartCallback(normalizedOrigin);
+  }
+  /**
+   * Resolves routes exposed on {@link AppStartInfo}.
+   *
+   * @remarks
+   * Default is empty. Runtime adapters override this to read from the
+   * initialized server route registry.
+   */
+  async resolveAppRoutes() {
+    return [];
+  }
+  async invokeAppStartCallback(origin) {
+    let routes = [];
+    try {
+      routes = await this.resolveAppRoutes();
+    } catch (error) {
+      appLogger.debug(
+        "Failed to resolve app start routes; continuing with empty routes",
+        error instanceof Error ? error.message : String(error)
+      );
     }
-    this.onAppStartCallback?.({ origin: normalizedOrigin });
+    this.onAppStartCallback?.({ origin, routes });
   }
   /**
    * Stops the application server and releases runtime resources.

package/src/adapters/abstract/server-adapter.d.ts

@@ -8,6 +8,7 @@
  */
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ApiHandler } from '../../types/public-types.js';
+import type { StaticGenerationRoute } from '../../router/server/route-registry.js';
 /**
  * Configuration options for all server adapters
  */
@@ -35,6 +36,15 @@ export interface ServerAdapterResult {
     }) => Promise<string | undefined>;
     servePreviewOnly: () => Promise<string | undefined>;
     dispose(): Promise<void>;
+    /**
+     * Lists static-generation routes for app-start consumers.
+     *
+     * @remarks
+     * Optional so lightweight adapter stubs in tests need not implement routing.
+     */
+    listStaticGenerationRoutes?: (input: {
+        runtimeOrigin: string;
+    }) => Promise<readonly StaticGenerationRoute[]>;
 }
 /**
  * Abstract base class for server adapters across different runtimes

package/src/adapters/bun/create-app.d.ts

@@ -55,6 +55,7 @@ export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApp
      */
     protected bootServer(): Promise<Server<WebSocketData> | void>;
     stop(force?: boolean): Promise<void>;
+    protected resolveAppRoutes(): Promise<import("../../index.browser.js").EcopagesRouteInfo[]>;
 }
 /**
  * Factory function to create a Bun application

package/src/adapters/bun/create-app.js

@@ -5,6 +5,7 @@ import { startupTrace } from "../../diagnostics/startup-trace.js";
 import { createBunServerAdapter } from "./server-adapter.js";
 import { BunRuntimeHost } from "./runtime-host.js";
 import { hostOwnsDevClient } from "../../dev/dev-client-ownership.js";
+import { resolveAppStartRoutes } from "../../utils/ecopages-route-info.js";
 class BunEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
@@ -83,7 +84,7 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     if (preview && serveOnly) {
       const previewOrigin2 = await this.serverAdapter.servePreviewOnly();
       if (previewOrigin2) {
-        this.notifyListening(previewOrigin2);
+        await this.notifyListening(previewOrigin2);
       }
       return;
     }
@@ -92,7 +93,7 @@ class BunEcopagesApp extends SharedApplicationAdapter {
       const previewOrigin2 = await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
       if (preview && previewOrigin2) {
-        this.notifyListening(previewOrigin2);
+        await this.notifyListening(previewOrigin2);
       }
       if (build) {
         process.exit(0);
@@ -131,10 +132,10 @@ class BunEcopagesApp extends SharedApplicationAdapter {
         process.exit(0);
       }
     } else {
-      this.notifyListening(runtimeOrigin);
+      await this.notifyListening(runtimeOrigin);
     }
     if (preview && previewOrigin) {
-      this.notifyListening(previewOrigin);
+      await this.notifyListening(previewOrigin);
     }
     return this.server ?? void 0;
   }
@@ -152,6 +153,12 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     }
     this.stopped = true;
   }
+  async resolveAppRoutes() {
+    return resolveAppStartRoutes({
+      listStaticGenerationRoutes: this.serverAdapter?.listStaticGenerationRoutes,
+      runtimeOrigin: this.appConfig.baseUrl
+    });
+  }
 }
 async function createApp(options) {
   return new BunEcopagesApp(options, {

package/src/adapters/bun/server-adapter.js

@@ -539,6 +539,7 @@ class BunServerAdapter extends SharedServerAdapter {
       completeInitialization: this.completeInitialization.bind(this),
       handleRequest: this.handleRequest.bind(this),
       attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),
+      listStaticGenerationRoutes: (input) => this.router.listStaticGenerationRoutes(input),
       dispose: this.dispose.bind(this)
     };
   }

package/src/adapters/node/create-app.d.ts

@@ -17,6 +17,7 @@ export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAp
     });
     protected createServerAdapter(params: Parameters<typeof createNodeServerAdapter>[0]): Promise<NodeServerAdapterResult>;
     stop(force?: boolean): Promise<void>;
+    protected resolveAppRoutes(): Promise<import("../../index.browser.js").EcopagesRouteInfo[]>;
     protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
     protected bootServer(): Promise<NodeServerInstance | void>;
     fetch(request: Request): Promise<Response>;

package/src/adapters/node/create-app.js

@@ -6,6 +6,7 @@ import { NodeHttpRequestBridge } from "./http-request-bridge.js";
 import { NodeRuntimeHost } from "./runtime-host.js";
 import { hostOwnsDevClient } from "../../dev/dev-client-ownership.js";
 import { startupTrace } from "../../diagnostics/startup-trace.js";
+import { resolveAppStartRoutes } from "../../utils/ecopages-route-info.js";
 class NodeEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
@@ -33,6 +34,12 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     }
     this.stopped = true;
   }
+  async resolveAppRoutes() {
+    return resolveAppStartRoutes({
+      listStaticGenerationRoutes: this.serverAdapter?.listStaticGenerationRoutes,
+      runtimeOrigin: this.appConfig.baseUrl
+    });
+  }
   async initializeServerAdapter() {
     const binding = resolveRuntimeBinding({
       cliArgs: this.cliArgs,
@@ -71,7 +78,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     if (preview && serveOnly) {
       const previewOrigin = await this.serverAdapter.servePreviewOnly();
       if (previewOrigin) {
-        this.notifyListening(previewOrigin);
+        await this.notifyListening(previewOrigin);
       }
       return;
     }
@@ -80,7 +87,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
       const previewOrigin = await this.serverAdapter.buildStatic({ preview, force });
       appLogger.debugTimeEnd("Building static pages");
       if (preview && previewOrigin) {
-        this.notifyListening(previewOrigin);
+        await this.notifyListening(previewOrigin);
       }
       if (build) {
         process.exit(0);
@@ -97,7 +104,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     });
     this.runtimeOrigin = this.runtimeHost.getOrigin(this.server, serveOptions);
     await this.serverAdapter.completeInitialization(this.server);
-    this.notifyListening(this.runtimeOrigin);
+    await this.notifyListening(this.runtimeOrigin);
     return this.server;
   }
   async fetch(request) {

package/src/adapters/node/server-adapter.js

@@ -198,6 +198,7 @@ class NodeServerAdapter extends SharedServerAdapter {
       completeInitialization: this.completeInitialization.bind(this),
       handleRequest: this.handleRequest.bind(this),
       attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this),
+      listStaticGenerationRoutes: (input) => this.router.listStaticGenerationRoutes(input),
       dispose: this.dispose.bind(this)
     };
   }

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

@@ -16,6 +16,11 @@ export declare class FileSystemServerResponseFactory {
      * Wraps already-rendered HTML in a 404 response envelope.
      */
     createHtmlNotFoundResponse(body: RouteRendererBody): Promise<Response>;
+    createDefaultServerErrorResponse(): Promise<Response>;
+    /**
+     * Wraps already-rendered HTML in a 500 response envelope.
+     */
+    createHtmlServerErrorResponse(body: RouteRendererBody): Promise<Response>;
     /**
      * Reads a static file response, returning `null` when the file is missing.
      */

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

@@ -38,6 +38,26 @@ class FileSystemServerResponseFactory {
       }
     });
   }
+  async createDefaultServerErrorResponse() {
+    return new Response(STATUS_MESSAGE[500], {
+      status: 500,
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8"
+      }
+    });
+  }
+  /**
+   * Wraps already-rendered HTML in a 500 response envelope.
+   */
+  async createHtmlServerErrorResponse(body) {
+    return await this.createResponseWithBody(body, {
+      status: 500,
+      statusText: STATUS_MESSAGE[500],
+      headers: {
+        "Content-Type": "text/html"
+      }
+    });
+  }
   /**
    * Reads a static file response, returning `null` when the file is missing.
    */

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

@@ -55,7 +55,25 @@ export declare class FileSystemResponseMatcher {
      * when the page template cannot be resolved.
      */
     private renderCustomNotFoundResponse;
+    /**
+     * Renders the app-owned custom 500 page, falling back to the default text 500
+     * when the page template cannot be resolved.
+     */
+    private renderCustomServerErrorResponse;
+    /**
+     * Builds development-only error details for the custom 500 page.
+     * @remarks Production omits these fields so stacks are not serialized into HTML.
+     */
+    private buildServerErrorPageProps;
+    private renderCustomErrorPageResponse;
     private renderCustomNotFoundResponseOrServerError;
+    /**
+     * Logs the original render failure, then tries the custom 500 page once.
+     * @remarks Any failure while rendering the custom 500 page falls back to the
+     * default plain-text response and never re-enters the custom page path.
+     * In development the thrown error's `message` and `stack` are passed into the
+     * custom 500 page props.
+     */
     private createInternalServerErrorResponse;
     private createExecutionPlan;
     /**

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

@@ -100,9 +100,9 @@ class FileSystemResponseMatcher {
         return error;
       }
       if (error instanceof LocalsAccessError) {
-        return this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
+        return await this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
       }
-      return this.createInternalServerErrorResponse(
+      return await this.createInternalServerErrorResponse(
         error instanceof Error ? error.message : "Internal Server Error",
         match.requestedPathname,
         error
@@ -114,21 +114,66 @@ class FileSystemResponseMatcher {
    * when the page template cannot be resolved.
    */
   async renderCustomNotFoundResponse() {
-    const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+    return this.renderCustomErrorPageResponse({
+      templatePath: this.appConfig.absolutePaths.error404TemplatePath,
+      label: "404",
+      createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultNotFoundResponse(),
+      createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlNotFoundResponse(body)
+    });
+  }
+  /**
+   * Renders the app-owned custom 500 page, falling back to the default text 500
+   * when the page template cannot be resolved.
+   */
+  async renderCustomServerErrorResponse(error) {
+    return this.renderCustomErrorPageResponse({
+      templatePath: this.appConfig.absolutePaths.error500TemplatePath,
+      label: "500",
+      props: this.buildServerErrorPageProps(error),
+      createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultServerErrorResponse(),
+      createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlServerErrorResponse(body)
+    });
+  }
+  /**
+   * Builds development-only error details for the custom 500 page.
+   * @remarks Production omits these fields so stacks are not serialized into HTML.
+   */
+  buildServerErrorPageProps(error) {
+    if (!isDevelopmentRuntime()) {
+      return void 0;
+    }
+    if (error instanceof Error) {
+      return {
+        message: error.message,
+        stack: error.stack
+      };
+    }
+    return {
+      message: String(error)
+    };
+  }
+  async renderCustomErrorPageResponse({
+    templatePath,
+    label,
+    props,
+    createDefaultResponse,
+    createHtmlResponse
+  }) {
     let routeRenderer;
     try {
-      routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
+      routeRenderer = this.routeRendererFactory.getPageRenderer(templatePath);
     } catch {
       appLogger.debug(
-        "Custom 404 template not found, falling back to default 404 response",
-        error404TemplatePath
+        `Custom ${label} template not found, falling back to default ${label} response`,
+        templatePath
       );
-      return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
+      return createDefaultResponse();
     }
     const result = await routeRenderer.execute({
-      file: error404TemplatePath
+      file: templatePath,
+      props
     });
-    return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+    return createHtmlResponse(result.body);
   }
   async renderCustomNotFoundResponseOrServerError(pathname) {
     try {
@@ -137,23 +182,38 @@ class FileSystemResponseMatcher {
       if (error instanceof Response) {
         return error;
       }
-      return this.createInternalServerErrorResponse(
+      return await this.createInternalServerErrorResponse(
         error instanceof Error ? error.message : "Internal Server Error",
         pathname,
         error
       );
     }
   }
-  createInternalServerErrorResponse(message, pathname, error) {
+  /**
+   * Logs the original render failure, then tries the custom 500 page once.
+   * @remarks Any failure while rendering the custom 500 page falls back to the
+   * default plain-text response and never re-enters the custom page path.
+   * In development the thrown error's `message` and `stack` are passed into the
+   * custom 500 page props.
+   */
+  async createInternalServerErrorResponse(message, pathname, error) {
     if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
       appLogger.error(`[FileSystemResponseMatcher] ${message} at ${pathname}`, error);
     } else {
       appLogger.error(`[FileSystemResponseMatcher] Render error at ${pathname}`, error);
     }
-    return new Response("Internal Server Error", {
-      status: 500,
-      headers: { "Content-Type": "text/plain; charset=utf-8" }
-    });
+    try {
+      return await this.renderCustomServerErrorResponse(error);
+    } catch (serverErrorPageError) {
+      if (serverErrorPageError instanceof Response) {
+        return serverErrorPageError;
+      }
+      appLogger.error(
+        `[FileSystemResponseMatcher] Custom 500 template failed at ${pathname}`,
+        serverErrorPageError
+      );
+      return this.fileSystemResponseFactory.createDefaultServerErrorResponse();
+    }
   }
   async createExecutionPlan(match, request) {
     const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({

package/src/config/config-builder.d.ts

@@ -8,7 +8,7 @@ import type { EcoPagesAppConfig, RobotsPreference } from '../types/internal-type
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
 import type { EcoSourceTransform } from '../plugins/source-transform.js';
-import type { PageMetadataProps } from '../types/public-types.js';
+import type { PageMetadataProps, SitemapConfig } from '../types/public-types.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 export declare const CONFIG_BUILDER_ERRORS: {
     readonly DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique";
@@ -16,7 +16,7 @@ export declare const CONFIG_BUILDER_ERRORS: {
     readonly MIXED_JSX_ENGINES: "Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).";
     readonly duplicateProcessorName: (name: string) => string;
     readonly duplicateLoaderName: (name: string) => string;
-    readonly duplicateSemanticTemplate: (kind: "html" | "404", matches: string[]) => string;
+    readonly duplicateSemanticTemplate: (kind: "html" | "404" | "500", matches: string[]) => string;
     readonly incompatibleRuntimeCapability: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, reason: string) => string;
     readonly unsupportedRuntimeVersion: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, current: string, min: string) => string;
     readonly invalidRuntimeVersion: (kind: "integration" | "processor", name: string, version: string) => string;
@@ -138,6 +138,16 @@ export declare class ConfigBuilder {
     setRobotsTxt(robotsTxt: {
         preferences: RobotsPreference;
     }): this;
+    /**
+     * Sets automatic sitemap.xml generation during static export.
+     *
+     * @remarks
+     * Merged over `{ enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }`.
+     * Existing apps stay unchanged until `enabled: true` is set. Page-level
+     * `metadata.robots.index: false` and metadata resolution failures are handled
+     * during static generation (not by this config merge).
+     */
+    setSitemap(sitemap: SitemapConfig): this;
     /**
      * Sets the integration plugins to use.
      * These plugins provide additional functionality to the application.