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

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

@@ -17,6 +17,11 @@ import {
   prebuildProductionPageBrowserGraphs,
   shouldPrebuildProductionPageBrowserGraphs
 } from "./production-page-browser-graph-prebuild.js";
+import { PageModuleLoaderService } from "../route-renderer/page-loading/page-module-loader.js";
+import { renderSitemap } from "./sitemap.js";
+import { resolveSitemapLocations } from "./sitemap-routes.js";
+import { toEcopagesRouteInfo } from "../utils/ecopages-route-info.js";
+import { normalizePathname } from "../utils/path-pattern.js";
 const STATIC_SITE_GENERATOR_ERRORS = {
   ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy",
   unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
@@ -46,6 +51,7 @@ class StaticSiteGenerator {
   routeModuleBuildCacheOverride;
   staticRenderCacheContext;
   forceFullStaticGeneration = false;
+  pageModuleLoader;
   /**
    * Creates the static-site generator for one app config.
    */
@@ -64,8 +70,9 @@ class StaticSiteGenerator {
     return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
   }
   async shouldSkipStaticPageFile(filePath, routeRendererFactory) {
-    const module = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
-    return module.default?.cache === "dynamic";
+    const pageModule = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
+    const Page = pageModule.default;
+    return Page.cache === "dynamic";
   }
   shouldSkipStaticView(_routePath, view) {
     return view.cache === "dynamic";
@@ -88,6 +95,14 @@ class StaticSiteGenerator {
     fileSystem.ensureDir(this.getExportDir());
     fileSystem.write(path.join(this.getExportDir(), "robots.txt"), data);
   }
+  /**
+   * Writes the configured sitemap file to the export directory.
+   */
+  generateSitemap(locations, sitemap) {
+    const fileName = sitemap.fileName ?? "sitemap.xml";
+    fileSystem.ensureDir(this.getExportDir());
+    fileSystem.write(path.join(this.getExportDir(), fileName), renderSitemap(locations));
+  }
   /**
    * Returns whether the input path points at the root directory.
    */
@@ -116,7 +131,6 @@ class StaticSiteGenerator {
     return outputPath;
   }
   async writeStaticPageArtifact(options) {
-    options.activeStaticPathnames?.add(options.pathname);
     const directories = options.directories ?? this.getDirectories([options.pathname]);
     const renderedOutputPath = this.getOutputPath(options.pathname, directories);
     const routeModuleBuildCache = this.getRouteModuleBuildCache();
@@ -127,6 +141,8 @@ class StaticSiteGenerator {
       context: this.staticRenderCacheContext,
       force: this.forceFullStaticGeneration
     })) {
+      options.activeStaticPathnames?.add(options.pathname);
+      await options.onSuccessfulExport?.();
       appLogger.debug(`Skipped unchanged static page: ${options.debugLabel ?? options.pathname}`);
       return;
     }
@@ -135,15 +151,80 @@ class StaticSiteGenerator {
       return;
     }
     const outputPath = this.writeStaticOutput(options.pathname, contents, directories);
+    options.activeStaticPathnames?.add(options.pathname);
     if (options.sourceFile) {
-      routeModuleBuildCache.recordStaticRender({
-        filePath: options.sourceFile,
-        pathname: options.pathname,
-        sourceHash: fileSystem.hash(options.sourceFile),
-        renderedOutputPath: outputPath,
-        context: this.staticRenderCacheContext
-      });
+      try {
+        routeModuleBuildCache.recordStaticRender({
+          filePath: options.sourceFile,
+          pathname: options.pathname,
+          sourceHash: fileSystem.hash(options.sourceFile),
+          renderedOutputPath: outputPath,
+          context: this.staticRenderCacheContext
+        });
+      } catch (error) {
+        appLogger.debug(
+          `Failed to record static render cache for ${options.pathname}`,
+          error instanceof Error ? error.message : String(error)
+        );
+      }
     }
+    await options.onSuccessfulExport?.();
+  }
+  /**
+   * Marks a successfully exported pathname as sitemap-eligible when robots allow indexing.
+   *
+   * @remarks
+   * Fail-closed: metadata resolution errors omit the URL. `robots.index === false`
+   * also omits it. Eligibility is decided during generation, not by reloading modules
+   * after `afterStaticExport`.
+   */
+  async considerSitemapEligibility(input) {
+    if (!input.sitemapEligiblePathnames || !this.appConfig.sitemap?.enabled) {
+      return;
+    }
+    try {
+      const metadata = await input.resolveMetadata();
+      if (metadata.robots?.index === false) {
+        return;
+      }
+      input.sitemapEligiblePathnames.add(normalizePathname(input.pathname));
+    } catch (error) {
+      appLogger.debug(
+        `Sitemap eligibility skipped for ${input.pathname}; metadata resolution failed`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  getPageModuleLoader(baseUrl) {
+    this.pageModuleLoader ??= new PageModuleLoaderService(this.appConfig, baseUrl);
+    return this.pageModuleLoader;
+  }
+  async resolveFilesystemPageMetadata(input) {
+    const loader = this.getPageModuleLoader(input.baseUrl);
+    const pageModule = await loader.resolvePageModule({
+      file: input.filePath,
+      importPageFileFn: (file) => input.routeRendererFactory.getPageRenderer(file).loadPageModule(file)
+    });
+    const { metadata } = await loader.resolvePageData({
+      pageModule,
+      routeOptions: {
+        file: input.filePath,
+        params: input.params
+      }
+    });
+    return metadata;
+  }
+  async resolveExplicitViewMetadata(input) {
+    if (!input.view.metadata) {
+      return this.appConfig.defaultMetadata;
+    }
+    const dynamicMetadata = await input.view.metadata({
+      params: input.params,
+      query: {},
+      props: input.props,
+      appConfig: this.appConfig
+    });
+    return { ...this.appConfig.defaultMetadata, ...dynamicMetadata };
   }
   pruneStaleStaticOutputs(activeStaticPathnames) {
     const removedOutputPaths = this.getRouteModuleBuildCache().pruneStaleRenderedOutputs(activeStaticPathnames);
@@ -155,11 +236,15 @@ class StaticSiteGenerator {
       }
     }
   }
-  async createFilesystemStaticContents(route, _baseUrl, routeRendererFactory, skipped) {
+  async createFilesystemStaticContents(input) {
     const {
-      templateRoute: { filePath },
-      params
-    } = route;
+      route: {
+        templateRoute: { filePath },
+        params
+      },
+      routeRendererFactory,
+      skipped
+    } = input;
     if (!routeRendererFactory) {
       throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
     }
@@ -187,8 +272,9 @@ class StaticSiteGenerator {
    * @remarks
    * Routes are rendered through the normal route renderer directly.
    */
-  async generateStaticPages(router, baseUrl, routeRendererFactory, skipped, activeStaticPathnames, preloadedRoutes) {
-    const routes = preloadedRoutes ?? await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+  async generateStaticPages(input) {
+    const { router, baseUrl, routeRendererFactory, skipped, activeStaticPathnames, sitemapEligiblePathnames } = input;
+    const routes = input.preloadedRoutes ?? await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
     appLogger.debug(
       "Static Pages",
       routes.map((route) => route.requestUrl)
@@ -202,7 +288,27 @@ class StaticSiteGenerator {
           directories,
           debugLabel: route.requestUrl,
           activeStaticPathnames,
-          createContents: () => this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory, skipped)
+          onSuccessfulExport: () => this.considerSitemapEligibility({
+            pathname: route.pathname,
+            sitemapEligiblePathnames,
+            resolveMetadata: () => {
+              if (!routeRendererFactory) {
+                throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
+              }
+              return this.resolveFilesystemPageMetadata({
+                filePath: route.templateRoute.filePath,
+                params: route.params,
+                baseUrl,
+                routeRendererFactory
+              });
+            }
+          }),
+          createContents: () => this.createFilesystemStaticContents({
+            route,
+            baseUrl,
+            routeRendererFactory,
+            skipped
+          })
         });
       } catch (error) {
         appLogger.error(
@@ -220,7 +326,8 @@ class StaticSiteGenerator {
       routeRendererFactory: input.routeRendererFactory,
       staticRoutes: input.staticRoutes,
       force: input.force,
-      preserveExportDirectory: input.preserveExportDirectory
+      preserveExportDirectory: input.preserveExportDirectory,
+      routes: input.routes
     };
   }
   async invokeStaticExportHook(hook, context) {
@@ -244,8 +351,10 @@ class StaticSiteGenerator {
   }) {
     const skippedDynamicPages = [];
     const activeStaticPathnames = /* @__PURE__ */ new Set();
+    const sitemapEligiblePathnames = this.appConfig.sitemap?.enabled ? /* @__PURE__ */ new Set() : void 0;
     this.forceFullStaticGeneration = force;
     this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(this.appConfig);
+    this.pageModuleLoader = void 0;
     if (!force) {
       this.getRouteModuleBuildCache().ensureIncrementalStaticGenerationContext(this.staticRenderCacheContext);
     }
@@ -253,6 +362,7 @@ class StaticSiteGenerator {
       clearProductionPageBrowserGraphSession(this.appConfig);
     }
     const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+    const exportRoutes = routes.map((route) => toEcopagesRouteInfo(route));
     if (shouldBuildPagesUnifiedGraph()) {
       await ensurePagesUnifiedGraphBuilt({
         appConfig: this.appConfig,
@@ -267,7 +377,8 @@ class StaticSiteGenerator {
       routeRendererFactory,
       staticRoutes,
       force,
-      preserveExportDirectory
+      preserveExportDirectory,
+      routes: exportRoutes
     });
     await this.invokeStaticExportHook("beforeStaticExport", staticExportContext);
     try {
@@ -278,21 +389,23 @@ class StaticSiteGenerator {
         );
       }
       this.generateRobotsTxt();
-      await this.generateStaticPages(
+      await this.generateStaticPages({
         router,
         baseUrl,
         routeRendererFactory,
-        skippedDynamicPages,
+        skipped: skippedDynamicPages,
         activeStaticPathnames,
-        routes
-      );
+        preloadedRoutes: routes,
+        sitemapEligiblePathnames
+      });
       if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
-        await this.generateExplicitStaticPages(
+        await this.generateExplicitStaticPages({
           staticRoutes,
           routeRendererFactory,
-          skippedDynamicPages,
-          activeStaticPathnames
-        );
+          skipped: skippedDynamicPages,
+          activeStaticPathnames,
+          sitemapEligiblePathnames
+        });
       }
       if (preserveExportDirectory) {
         this.pruneStaleStaticOutputs(activeStaticPathnames);
@@ -305,6 +418,14 @@ class StaticSiteGenerator {
     } finally {
       await this.invokeStaticExportHook("afterStaticExport", staticExportContext);
     }
+    if (this.appConfig.sitemap?.enabled && sitemapEligiblePathnames) {
+      const locations = resolveSitemapLocations({
+        eligiblePathnames: [...sitemapEligiblePathnames],
+        sitemap: this.appConfig.sitemap,
+        baseUrl
+      });
+      this.generateSitemap(locations, this.appConfig.sitemap);
+    }
     if (skippedDynamicPages.length > 0) {
       appLogger.debug(
         `Skipped ${skippedDynamicPages.length} page(s) with cache: 'dynamic' (not supported in static generation)`,
@@ -312,24 +433,26 @@ class StaticSiteGenerator {
       );
     }
   }
-  /**
-   * Generates static pages from explicit static routes registered via app.static().
-   * These routes use eco.page views via loader functions for HMR support.
-   */
-  async generateExplicitStaticPages(staticRoutes, routeRendererFactory, skipped, activeStaticPathnames) {
+  async generateExplicitStaticPages(input) {
     appLogger.debug(
       "Generating explicit static routes",
-      staticRoutes.map((r) => r.path)
+      input.staticRoutes.map((r) => r.path)
     );
-    for (const route of staticRoutes) {
+    for (const route of input.staticRoutes) {
       try {
         const mod = await route.loader();
         const view = mod.default;
         if (this.shouldSkipStaticView(route.path, view)) {
-          skipped?.push(route.path);
+          input.skipped?.push(route.path);
           continue;
         }
-        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory, activeStaticPathnames);
+        await this.generateExplicitStaticRoute({
+          routePath: route.path,
+          view,
+          routeRendererFactory: input.routeRendererFactory,
+          activeStaticPathnames: input.activeStaticPathnames,
+          sitemapEligiblePathnames: input.sitemapEligiblePathnames
+        });
       } catch (error) {
         appLogger.error(
           `Error generating explicit static page for ${route.path}:`,
@@ -345,8 +468,13 @@ class StaticSiteGenerator {
     }
     return path.isAbsolute(sourceFile) ? sourceFile : path.join(this.appConfig.rootDir, sourceFile);
   }
-  async generateExplicitStaticRoute(routePath, view, routeRendererFactory, activeStaticPathnames) {
-    const { renderer, routeEntries } = await this.planExplicitStaticRoute(routePath, view, routeRendererFactory);
+  async generateExplicitStaticRoute(input) {
+    const { routePath, view, routeRendererFactory, activeStaticPathnames, sitemapEligiblePathnames } = input;
+    const { renderer, routeEntries } = await this.planExplicitStaticRoute({
+      routePath,
+      view,
+      routeRendererFactory
+    });
     const sourceFile = this.resolveExplicitViewSourceFile(view);
     for (const { pathname, params } of routeEntries) {
       await this.writeStaticPageArtifact({
@@ -354,37 +482,59 @@ class StaticSiteGenerator {
         sourceFile,
         debugLabel: pathname,
         activeStaticPathnames,
-        createContents: () => this.createExplicitStaticContents(routePath, view, params, routeRendererFactory, renderer)
+        onSuccessfulExport: () => this.considerSitemapEligibility({
+          pathname,
+          sitemapEligiblePathnames,
+          resolveMetadata: async () => {
+            const { props } = await prepareExplicitStaticRender({
+              routePath,
+              view,
+              params,
+              appConfig: this.appConfig,
+              runtimeOrigin: this.appConfig.baseUrl,
+              routeRendererFactory,
+              errors: STATIC_SITE_GENERATOR_ERRORS
+            });
+            return this.resolveExplicitViewMetadata({ view, params, props });
+          }
+        }),
+        createContents: () => this.createExplicitStaticContents({
+          routePath,
+          view,
+          params,
+          routeRendererFactory,
+          renderer
+        })
       });
       appLogger.debug(`Generated static page: ${pathname}`);
     }
   }
-  async planExplicitStaticRoute(routePath, view, routeRendererFactory) {
+  async planExplicitStaticRoute(input) {
     const { renderer } = await prepareExplicitStaticRender({
-      routePath,
-      view,
+      routePath: input.routePath,
+      view: input.view,
       params: {},
       appConfig: this.appConfig,
       runtimeOrigin: this.appConfig.baseUrl,
-      routeRendererFactory,
+      routeRendererFactory: input.routeRendererFactory,
       errors: STATIC_SITE_GENERATOR_ERRORS
     });
     return {
       renderer,
-      routeEntries: await this.listExplicitStaticRouteEntries(routePath, view)
+      routeEntries: await this.listExplicitStaticRouteEntries(input.routePath, input.view)
     };
   }
-  async createExplicitStaticContents(routePath, view, params, routeRendererFactory, renderer) {
+  async createExplicitStaticContents(input) {
     const { props, view: renderableView } = await prepareExplicitStaticRender({
-      routePath,
-      view,
-      params,
+      routePath: input.routePath,
+      view: input.view,
+      params: input.params,
       appConfig: this.appConfig,
       runtimeOrigin: this.appConfig.baseUrl,
-      routeRendererFactory,
+      routeRendererFactory: input.routeRendererFactory,
       errors: STATIC_SITE_GENERATOR_ERRORS
     });
-    const response = await renderer.renderToResponse(renderableView, props, {});
+    const response = await input.renderer.renderToResponse(renderableView, props, {});
     return response.text();
   }
   async listExplicitStaticRouteEntries(routePath, view) {

package/src/types/internal-types.d.ts

@@ -5,14 +5,14 @@ import type { BuildRuntime } from '../build/runtime/build-runtime.js';
 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 './public-types.js';
+import type { PageMetadataProps, SitemapConfig } from './public-types.js';
 import type { RouteRegistry } from '../router/server/route-registry.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 import type { DevGraphService } from '../services/runtime-state/dev-graph.service.js';
 import type { AppModuleLoader } from '../services/module-loading/app-module-loader.service.js';
 import type { SourceModuleLoader } from '../services/module-loading/module-loading-types.js';
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
-import type { SessionPageBrowserGraphCache } from '../route-renderer/orchestration/page-browser-graph-session.js';
+import type { SessionPageBrowserGraphCache } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
 import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
 import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
 import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
@@ -99,6 +99,12 @@ export type EcoPagesAppConfig = {
          */
         preferences: RobotsPreference;
     };
+    /**
+     * Automatic sitemap.xml generation during static export.
+     *
+     * @default { enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }
+     */
+    sitemap: SitemapConfig;
     /** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
     additionalWatchPaths: string[];
     /**
@@ -123,6 +129,7 @@ export type EcoPagesAppConfig = {
         srcDir: string;
         htmlTemplatePath: string;
         error404TemplatePath: string;
+        error500TemplatePath: string;
     };
     /**
      * The processors to be used in the app

package/src/types/public-types.d.ts

@@ -1,7 +1,7 @@
 import type { Readable } from 'node:stream';
 import type { ApiResponseBuilder } from '../adapters/shared/api-response.js';
 import type { BuildExecutor } from '../build/build-adapter.js';
-import type { ForeignChildRuntime } from '../route-renderer/orchestration/component-render-context.js';
+import type { ForeignChildRuntime } from '../route-renderer/orchestration/foreign-child/component-render-context.js';
 import type { EcoPageComponent } from '../eco/eco.types.js';
 import type { EcoPagesAppConfig } from './internal-types.js';
 import type { HmrStrategy } from '../hmr/hmr-strategy.js';
@@ -534,6 +534,21 @@ export type EcoComponent<P = any, R = any> = IsAny<P> extends true ? EcoFunction
 export type PageProps<T = unknown> = T & StaticPageContext & {
     locals?: RequestLocals;
 };
+/**
+ * Page-level robots directives for the document head and sitemap filtering.
+ *
+ * @remarks
+ * When `index` is `false`, the page is omitted from the auto-generated sitemap
+ * for routes whose metadata can be resolved during static export (filesystem
+ * pages and `app.static()` views with `metadata`). Defaults when omitted:
+ * `index: true`, `follow: true`. A `<meta name="robots">` tag is emitted by the
+ * route HTML finalization path when directives differ from those defaults.
+ */
+export interface PageRobotsMetadata {
+    index?: boolean;
+    follow?: boolean;
+    nocache?: boolean;
+}
 /**
  * Represents the metadata for a page.
  */
@@ -543,6 +558,48 @@ export interface PageMetadataProps {
     image?: string;
     url?: string;
     keywords?: string[];
+    robots?: PageRobotsMetadata;
+}
+/**
+ * Configuration for automatic `sitemap.xml` generation during static export.
+ *
+ * @remarks
+ * Disabled by default. When enabled, the sitemap is written after
+ * `afterStaticExport` so integration-generated URLs can be listed via
+ * `extraUrls`. Use `exclude` for bulk pathname filters and `metadata.robots.index: false`
+ * for page-level noindex that also removes the URL from the sitemap when metadata
+ * is available during export.
+ */
+export interface SitemapConfig {
+    /** Emit sitemap.xml during static generation. @default false */
+    enabled?: boolean;
+    /** Output file name. @default "sitemap.xml" */
+    fileName?: string;
+    /**
+     * Extra, non-page URLs to include (e.g. "/rss.xml").
+     *
+     * @remarks
+     * Relative paths are resolved against `baseUrl`. Absolute `http(s)` URLs pass
+     * through. Always appended after page URLs; not filtered by `exclude` or page robots.
+     */
+    extraUrls?: string[];
+    /**
+     * Pathname patterns to exclude even if a page exists.
+     *
+     * @remarks
+     * Supported patterns: exact paths (`/admin`) and prefix wildcards (`/admin/**`).
+     * Unsupported patterns are treated as exact matches. This is not a full glob engine.
+     */
+    exclude?: string[];
+}
+/**
+ * Slim route descriptor for static-export hooks and runtime consumers.
+ */
+export interface EcopagesRouteInfo {
+    /** Resolved URL pathname, e.g. `/blog/my-post`. */
+    pathname: string;
+    /** Route params for dynamic routes (empty for static routes). */
+    params: Record<string, string>;
 }
 /**
  * Represents the props for the head of a page.
@@ -622,12 +679,25 @@ export type EcoLayoutComponent<T = EcoPagesElement> = EcoComponent<LayoutProps<T
  */
 export type EcoHtmlComponent<T = EcoPagesElement> = EcoComponent<HtmlTemplateProps, T>;
 /**
- * Represents the props for the error 404 template.
+ * Props type for the semantic `404.*` page template.
+ * @remarks `message` and `stack` are declared for future error context. The
+ * runtime does not currently pass these props when rendering the custom 404 page.
  */
 export interface Error404TemplateProps extends Omit<HtmlTemplateProps, 'children'> {
     message: string;
     stack?: string;
 }
+/**
+ * Props type for the semantic `500.*` page template.
+ * @remarks In development, the page-pipeline passes `message` and `stack` from the
+ * thrown error when rendering this page after a failure. In production those
+ * fields are omitted so stacks are not serialized into HTML. Direct visits to
+ * `/500` also omit them.
+ */
+export interface Error500TemplateProps extends Omit<HtmlTemplateProps, 'children'> {
+    message?: string;
+    stack?: string;
+}
 /**
  * Represents the parameters for a page.
  * The keys are strings, and the values can be either a string or an array of strings.
@@ -751,6 +821,12 @@ export type RouteRendererOptions = {
     params?: PageParams;
     query?: PageQuery;
     locals?: RequestLocals;
+    /**
+     * Extra props merged into the page props for this render.
+     * @remarks Used by semantic error pages (for example development `message` /
+     * `stack` on the custom 500 page).
+     */
+    props?: Record<string, unknown>;
 };
 /**
  * The body of the route renderer.

package/src/utils/ecopages-route-info.d.ts

@@ -0,0 +1,26 @@
+import type { EcopagesRouteInfo } from '../types/public-types.js';
+/**
+ * Maps a static-generation or registry route into the public slim route shape.
+ */
+export declare function toEcopagesRouteInfo(route: {
+    pathname: string;
+    params: Record<string, string | string[]>;
+}): EcopagesRouteInfo;
+/**
+ * Flattens string | string[] route params into string values for public APIs.
+ */
+export declare function normalizeRouteParams(params: Record<string, string | string[]>): Record<string, string>;
+type StaticGenerationRouteLister = (input: {
+    runtimeOrigin: string;
+}) => Promise<readonly {
+    pathname: string;
+    params: Record<string, string | string[]>;
+}[]>;
+/**
+ * Resolves {@link EcopagesRouteInfo} entries for app-start and similar consumers.
+ */
+export declare function resolveAppStartRoutes(input: {
+    listStaticGenerationRoutes?: StaticGenerationRouteLister;
+    runtimeOrigin: string;
+}): Promise<EcopagesRouteInfo[]>;
+export {};

package/src/utils/ecopages-route-info.js

@@ -0,0 +1,26 @@
+import { normalizePathname } from "./path-pattern.js";
+function toEcopagesRouteInfo(route) {
+  return {
+    pathname: normalizePathname(route.pathname),
+    params: normalizeRouteParams(route.params)
+  };
+}
+function normalizeRouteParams(params) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(params)) {
+    normalized[key] = Array.isArray(value) ? value.join("/") : value;
+  }
+  return normalized;
+}
+async function resolveAppStartRoutes(input) {
+  if (!input.listStaticGenerationRoutes) {
+    return [];
+  }
+  const routes = await input.listStaticGenerationRoutes({ runtimeOrigin: input.runtimeOrigin });
+  return routes.map(toEcopagesRouteInfo);
+}
+export {
+  normalizeRouteParams,
+  resolveAppStartRoutes,
+  toEcopagesRouteInfo
+};

package/src/utils/html-escaping.d.ts

@@ -5,3 +5,10 @@
  * @returns Escaped attribute-safe string.
  */
 export declare function escapeHtmlAttribute(value: string): string;
+/**
+ * Escapes a string for safe use as XML text content (e.g. `<loc>` values).
+ *
+ * @param value Raw text node value.
+ * @returns Escaped XML-safe string.
+ */
+export declare function escapeXmlText(value: string): string;

package/src/utils/html-escaping.js

@@ -1,6 +1,10 @@
 function escapeHtmlAttribute(value) {
   return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
+function escapeXmlText(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
 export {
-  escapeHtmlAttribute
+  escapeHtmlAttribute,
+  escapeXmlText
 };

package/src/utils/path-pattern.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalizes a URL pathname for matching and sitemap location building.
+ *
+ * @remarks
+ * Ensures a leading slash and strips trailing slashes except for `/`.
+ */
+export declare function normalizePathname(pathname: string): string;
+/**
+ * Matches a pathname against a small set of supported patterns.
+ *
+ * @remarks
+ * Supported forms:
+ * - exact: `/admin`
+ * - prefix wildcard: `/admin/**` (matches `/admin` and descendants)
+ * - trailing `**` only as a full segment after `/`
+ *
+ * This is not a full glob engine. Unsupported patterns are treated as exact matches.
+ */
+export declare function matchPathPattern(pathname: string, pattern: string): boolean;
+/**
+ * Returns true when the pathname matches any of the patterns.
+ */
+export declare function matchesAnyPathPattern(pathname: string, patterns: readonly string[]): boolean;