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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.28",
+  "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.28",
+    "@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",

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.

package/src/config/config-builder.js

@@ -53,6 +53,12 @@ class ConfigBuilder {
         "*": []
       }
     },
+    sitemap: {
+      enabled: false,
+      fileName: "sitemap.xml",
+      extraUrls: [],
+      exclude: []
+    },
     integrations: [],
     integrationsDependencies: [],
     distDir: DEFAULT_ECOPAGES_DIST_DIR,
@@ -74,7 +80,8 @@ class ConfigBuilder {
       publicDir: "",
       srcDir: "",
       htmlTemplatePath: "",
-      error404TemplatePath: ""
+      error404TemplatePath: "",
+      error500TemplatePath: ""
     },
     processors: /* @__PURE__ */ new Map(),
     loaders: /* @__PURE__ */ new Map(),
@@ -201,6 +208,31 @@ class ConfigBuilder {
     this.config.robotsTxt = robotsTxt;
     return 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) {
+    const defaults = {
+      enabled: false,
+      fileName: "sitemap.xml",
+      extraUrls: [],
+      exclude: []
+    };
+    this.config.sitemap = {
+      ...defaults,
+      ...this.config.sitemap,
+      ...sitemap,
+      extraUrls: sitemap.extraUrls ?? this.config.sitemap.extraUrls ?? defaults.extraUrls,
+      exclude: sitemap.exclude ?? this.config.sitemap.exclude ?? defaults.exclude
+    };
+    return this;
+  }
   /**
    * Sets the integration plugins to use.
    * These plugins provide additional functionality to the application.
@@ -381,11 +413,18 @@ class ConfigBuilder {
       error404TemplatePath: this.resolveSemanticTemplatePath({
         dirPath: absolutePagesDir,
         basename: "404"
+      }),
+      error500TemplatePath: this.resolveSemanticTemplatePath({
+        dirPath: absolutePagesDir,
+        basename: "500"
       })
     };
     return this;
   }
-  resolveSemanticTemplatePath({ dirPath, basename }) {
+  resolveSemanticTemplatePath({
+    dirPath,
+    basename
+  }) {
     const extensions = this.config.templatesExt.length > 0 ? this.config.templatesExt : [".ghtml.ts"];
     const matches = extensions.map((extension) => path.join(dirPath, `${basename}${extension}`)).filter((candidate) => fileSystem.exists(candidate));
     invariant(matches.length <= 1, CONFIG_BUILDER_ERRORS.duplicateSemanticTemplate(basename, matches));

package/src/config/constants.d.ts

@@ -7,6 +7,7 @@
  */
 export declare const STATUS_MESSAGE: {
     404: string;
+    500: string;
 };
 /**
  *Variables used to determine if the app is running on Bun

package/src/config/constants.js

@@ -1,5 +1,6 @@
 const STATUS_MESSAGE = {
-  404: "404 Not Found"
+  404: "404 Not Found",
+  500: "Internal Server Error"
 };
 const IS_BUN = typeof Bun !== "undefined";
 const RESOLVED_ASSETS_DIR = "assets";

package/src/route-renderer/orchestration/route-pipeline/robots-meta.contribution.d.ts

@@ -0,0 +1,15 @@
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import type { PageMetadataProps, PageRobotsMetadata } from '../../../types/public-types.js';
+/**
+ * Builds a head contribution for non-default `metadata.robots` values.
+ *
+ * @remarks
+ * When `robots` is omitted or matches the default `index,follow` behaviour,
+ * no tag is emitted (Next.js parity). Otherwise a single
+ * `<meta name="robots" content="...">` contribution is returned.
+ */
+export declare function buildRobotsMetaContribution(metadata: Pick<PageMetadataProps, 'robots'>): HtmlDocumentContribution | undefined;
+/**
+ * Formats robots directives for a meta tag, or `undefined` when defaults apply.
+ */
+export declare function formatRobotsMetaContent(robots: PageRobotsMetadata | undefined): string | undefined;

package/src/route-renderer/orchestration/route-pipeline/robots-meta.contribution.js

@@ -0,0 +1,36 @@
+import { escapeHtmlAttribute } from "../../../utils/html-escaping.js";
+function buildRobotsMetaContribution(metadata) {
+  const content = formatRobotsMetaContent(metadata.robots);
+  if (!content) {
+    return void 0;
+  }
+  return {
+    placement: "head-append",
+    html: `<meta name="robots" content="${escapeHtmlAttribute(content)}">`
+  };
+}
+function formatRobotsMetaContent(robots) {
+  if (!robots) {
+    return void 0;
+  }
+  const index = robots.index !== false;
+  const follow = robots.follow !== false;
+  const directives = [];
+  if (!index) {
+    directives.push("noindex");
+  }
+  if (!follow) {
+    directives.push("nofollow");
+  }
+  if (robots.nocache) {
+    directives.push("nocache");
+  }
+  if (directives.length === 0) {
+    return void 0;
+  }
+  return directives.join(", ");
+}
+export {
+  buildRobotsMetaContribution,
+  formatRobotsMetaContent
+};

package/src/route-renderer/orchestration/route-pipeline/route-html-finalization.service.d.ts

@@ -12,5 +12,9 @@ export type RouteHtmlFinalizationContext<C> = {
 };
 /**
  * Builds the structural HTML finalization plan for one prepared route render.
+ *
+ * @remarks
+ * Merges core robots meta contributions with integration-owned document
+ * contributions so page-level `metadata.robots` works across templates.
  */
 export declare function buildRouteHtmlFinalization<C>(context: RouteHtmlFinalizationContext<C>): RouteHtmlFinalization;