@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

package/src/services/module-loading/route-module-build-manifest.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { readProductionCacheManifest, writeProductionCacheManifest } from "../../build/cache/production-build-cache.js";
+import { createJsxCacheKey, createPluginCacheKey, getCorePackageVersion } from "../../build/cache/cache-keys.js";
+import {
+  createJsxCacheKey as createJsxCacheKey2,
+  createPluginCacheKey as createPluginCacheKey2,
+  getCorePackageVersion as getCorePackageVersion2,
+  hashPluginSetup
+} from "../../build/cache/cache-keys.js";
+import { ROUTE_MODULE_BUILD_CACHE_FILENAME } from "../../build/cache/cache-constants.js";
+function normalizeRouteModuleCachePath(filePath) {
+  return path.resolve(filePath);
+}
+function shouldPersistRouteModuleBuildCache(options) {
+  if (process.env.NODE_ENV !== "production") {
+    return false;
+  }
+  if (options.bypassCache) {
+    return false;
+  }
+  if ((options.invalidationVersion ?? 0) > 0) {
+    return false;
+  }
+  if (options.cacheScope) {
+    return false;
+  }
+  return true;
+}
+function resolvePageModuleOutputFileName(options) {
+  const fileBaseName = path.basename(options.filePath, path.extname(options.filePath));
+  const cacheScopeSuffix = options.cacheScope ? `-${sanitizeCacheScope(options.cacheScope)}` : "";
+  const invalidationSuffix = shouldVersionBuildOutputPath(options.invalidationVersion ?? 0) ? `-v${options.invalidationVersion}` : "";
+  return `${fileBaseName}-${options.fileHash}${cacheScopeSuffix}${invalidationSuffix}.mjs`;
+}
+function createPersistedRouteModuleBuildKey(options) {
+  return [
+    path.resolve(options.rootDir),
+    path.resolve(options.outdir),
+    options.splitting ?? "default",
+    options.externalPackages ?? "default",
+    createJsxCacheKey(options.jsx),
+    createPluginCacheKey(options.plugins)
+  ].join("::");
+}
+function createEmptyRouteModuleBuildCacheManifest() {
+  return {
+    invalidationVersion: getCorePackageVersion(),
+    entries: {}
+  };
+}
+function readRouteModuleBuildCacheManifest(manifestPath) {
+  const parsed = readProductionCacheManifest(manifestPath);
+  if (!parsed || typeof parsed.entries !== "object") {
+    return void 0;
+  }
+  return {
+    invalidationVersion: parsed.invalidationVersion ?? "",
+    configHash: parsed.configHash,
+    buildInputsFingerprint: parsed.buildInputsFingerprint,
+    entries: parsed.entries
+  };
+}
+function writeRouteModuleBuildCacheManifest(manifestPath, manifest) {
+  writeProductionCacheManifest(manifestPath, manifest);
+}
+function shouldVersionBuildOutputPath(invalidationVersion) {
+  return typeof Bun !== "undefined" && invalidationVersion > 0;
+}
+function sanitizeCacheScope(cacheScope) {
+  return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+export {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME,
+  createEmptyRouteModuleBuildCacheManifest,
+  createJsxCacheKey2 as createJsxCacheKey,
+  createPersistedRouteModuleBuildKey,
+  createPluginCacheKey2 as createPluginCacheKey,
+  getCorePackageVersion2 as getCorePackageVersion,
+  hashPluginSetup,
+  normalizeRouteModuleCachePath,
+  readRouteModuleBuildCacheManifest,
+  resolvePageModuleOutputFileName,
+  shouldPersistRouteModuleBuildCache,
+  writeRouteModuleBuildCacheManifest
+};

package/src/services/module-loading/route-module-dependency-hasher.d.ts

@@ -0,0 +1,81 @@
+import type { BuildResult } from '../../build/build-adapter.js';
+/**
+ * Content hashes for every trackable source file in one route module's import graph.
+ *
+ * @remarks
+ * Keys are normalized absolute filesystem paths. Values are opaque content hashes
+ * produced by the active {@link FileSystem} implementation. Only app-owned source
+ * files are tracked; `node:` builtins and `node_modules` paths are excluded
+ * because they are covered by the core package {@link getCorePackageVersion | invalidation version}.
+ */
+export type RouteModuleDependencyHashes = Record<string, string>;
+type HashFileFn = (filePath: string) => string;
+type ExistsFn = (filePath: string) => boolean;
+/**
+ * Lazily hashes route-module dependency files while memoizing results for one build run.
+ *
+ * @remarks
+ * Multiple route modules often share layouts or utilities. Memoizing per path avoids
+ * re-reading the same dependency file while validating or recording many cache entries
+ * during one production build.
+ */
+export declare class RouteModuleDependencyHasher {
+    private readonly memo;
+    private readonly hashFile;
+    private readonly exists;
+    constructor(dependencies?: {
+        hashFile?: HashFileFn;
+        exists?: ExistsFn;
+    });
+    /**
+     * Returns a memoized content hash for one trackable dependency path.
+     *
+     * @param filePath - Absolute or project-relative source path.
+     * @returns The content hash, or `undefined` when the path is not trackable or missing.
+     */
+    hashDependency(filePath: string): string | undefined;
+    /**
+     * Builds the dependency-hash map for one route entrypoint graph.
+     *
+     * @param modulePaths - Raw module ids from the bundler dependency graph.
+     * @returns Hashes for every trackable, existing source file in the graph.
+     */
+    createDependencyHashes(modulePaths: readonly string[]): RouteModuleDependencyHashes;
+    /**
+     * Returns whether every stored dependency hash still matches the current file contents.
+     *
+     * @param storedHashes - Dependency hashes previously persisted for one route module.
+     * @param entrypointPath - Route entry file whose hash is validated separately.
+     * @param entrypointSourceHash - Already-validated content hash for {@link entrypointPath}.
+     * @returns `true` when all stored hashes are present and still valid.
+     */
+    matchesStoredHashes(storedHashes: RouteModuleDependencyHashes | undefined, entrypointPath?: string, entrypointSourceHash?: string): boolean;
+    /** Clears the per-build memo so subsequent reads reflect current file contents. */
+    clearMemo(): void;
+}
+/**
+ * Returns whether a bundler module id should participate in route-module cache invalidation.
+ *
+ * @remarks
+ * Builtins and installed packages are excluded. Their changes are expected to be
+ * reflected through framework-level invalidation instead of per-route file hashing.
+ */
+export declare function isTrackableRouteModuleDependency(modulePath: string): boolean;
+/**
+ * Filters a bundler module list down to trackable app-owned source files.
+ */
+export declare function filterTrackableRouteModuleDependencies(modulePaths: readonly string[]): string[];
+/**
+ * Resolves the dependency module list for one route entrypoint from a build result.
+ *
+ * @param buildResult - Completed route-module build output.
+ * @param entrypointPath - Absolute or root-relative route source path used as the build entry.
+ * @param rootDir - Project root used to normalize relative module ids.
+ * @returns Normalized module paths, falling back to the entrypoint when no graph is available.
+ */
+export declare function resolveRouteModuleDependencyPaths(buildResult: Pick<BuildResult, 'dependencyGraph'>, entrypointPath: string, rootDir: string): string[];
+/**
+ * Convenience helper that combines graph extraction and dependency hashing.
+ */
+export declare function createRouteModuleDependencyHashes(hasher: RouteModuleDependencyHasher, buildResult: Pick<BuildResult, 'dependencyGraph'>, entrypointPath: string, rootDir: string): RouteModuleDependencyHashes;
+export {};

package/src/services/module-loading/route-module-dependency-hasher.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+class RouteModuleDependencyHasher {
+  memo = /* @__PURE__ */ new Map();
+  hashFile;
+  exists;
+  constructor(dependencies) {
+    this.hashFile = dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath));
+    this.exists = dependencies?.exists ?? ((filePath) => fileSystem.exists(filePath));
+  }
+  /**
+   * Returns a memoized content hash for one trackable dependency path.
+   *
+   * @param filePath - Absolute or project-relative source path.
+   * @returns The content hash, or `undefined` when the path is not trackable or missing.
+   */
+  hashDependency(filePath) {
+    const normalizedPath = path.normalize(filePath);
+    if (!isTrackableRouteModuleDependency(normalizedPath)) {
+      return void 0;
+    }
+    if (!this.exists(normalizedPath)) {
+      return void 0;
+    }
+    const cachedHash = this.memo.get(normalizedPath);
+    if (cachedHash) {
+      return cachedHash;
+    }
+    const nextHash = this.hashFile(normalizedPath);
+    this.memo.set(normalizedPath, nextHash);
+    return nextHash;
+  }
+  /**
+   * Builds the dependency-hash map for one route entrypoint graph.
+   *
+   * @param modulePaths - Raw module ids from the bundler dependency graph.
+   * @returns Hashes for every trackable, existing source file in the graph.
+   */
+  createDependencyHashes(modulePaths) {
+    const dependencyHashes = {};
+    for (const modulePath of filterTrackableRouteModuleDependencies(modulePaths)) {
+      const dependencyHash = this.hashDependency(modulePath);
+      if (dependencyHash) {
+        dependencyHashes[modulePath] = dependencyHash;
+      }
+    }
+    return dependencyHashes;
+  }
+  /**
+   * Returns whether every stored dependency hash still matches the current file contents.
+   *
+   * @param storedHashes - Dependency hashes previously persisted for one route module.
+   * @param entrypointPath - Route entry file whose hash is validated separately.
+   * @param entrypointSourceHash - Already-validated content hash for {@link entrypointPath}.
+   * @returns `true` when all stored hashes are present and still valid.
+   */
+  matchesStoredHashes(storedHashes, entrypointPath, entrypointSourceHash) {
+    this.clearMemo();
+    if (!storedHashes || Object.keys(storedHashes).length === 0) {
+      return false;
+    }
+    const normalizedEntrypoint = entrypointPath ? path.normalize(entrypointPath) : void 0;
+    for (const [dependencyPath, storedHash] of Object.entries(storedHashes)) {
+      if (normalizedEntrypoint && path.normalize(dependencyPath) === normalizedEntrypoint) {
+        if (entrypointSourceHash && storedHash !== entrypointSourceHash) {
+          return false;
+        }
+        continue;
+      }
+      const currentHash = this.hashDependency(dependencyPath);
+      if (!currentHash || currentHash !== storedHash) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /** Clears the per-build memo so subsequent reads reflect current file contents. */
+  clearMemo() {
+    this.memo.clear();
+  }
+}
+function isTrackableRouteModuleDependency(modulePath) {
+  const normalizedPath = path.normalize(modulePath);
+  if (normalizedPath.startsWith("node:")) {
+    return false;
+  }
+  if (normalizedPath.includes(`${path.sep}node_modules${path.sep}`)) {
+    return false;
+  }
+  return /\.(?:[cm]?[jt]sx?|mdx)$/iu.test(normalizedPath) || normalizedPath.endsWith(".json");
+}
+function filterTrackableRouteModuleDependencies(modulePaths) {
+  const uniquePaths = /* @__PURE__ */ new Set();
+  for (const modulePath of modulePaths) {
+    const normalizedPath = path.normalize(modulePath);
+    if (isTrackableRouteModuleDependency(normalizedPath)) {
+      uniquePaths.add(normalizedPath);
+    }
+  }
+  return Array.from(uniquePaths).sort();
+}
+function resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir) {
+  const normalizedEntrypoint = path.isAbsolute(entrypointPath) ? path.normalize(entrypointPath) : path.normalize(path.resolve(rootDir, entrypointPath));
+  const graphEntrypoints = buildResult.dependencyGraph?.entrypoints ?? {};
+  const dependencyPaths = graphEntrypoints[normalizedEntrypoint] ?? graphEntrypoints[entrypointPath] ?? Object.entries(graphEntrypoints).find(([candidate]) => path.normalize(candidate) === normalizedEntrypoint)?.[1];
+  if (!dependencyPaths || dependencyPaths.length === 0) {
+    return [normalizedEntrypoint];
+  }
+  return dependencyPaths.map(
+    (dependencyPath) => path.isAbsolute(dependencyPath) ? path.normalize(dependencyPath) : path.normalize(path.resolve(rootDir, dependencyPath))
+  );
+}
+function createRouteModuleDependencyHashes(hasher, buildResult, entrypointPath, rootDir) {
+  return hasher.createDependencyHashes(resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir));
+}
+export {
+  RouteModuleDependencyHasher,
+  createRouteModuleDependencyHashes,
+  filterTrackableRouteModuleDependencies,
+  isTrackableRouteModuleDependency,
+  resolveRouteModuleDependencyPaths
+};

package/src/services/module-loading/server-module-transpiler.service.d.ts

@@ -1,5 +1,5 @@
 import type { BuildExecutor } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
 import type { AppModuleLoader } from './app-module-loader.service.js';
 import { type PageModuleBuildImportOptions } from './page-module-import.service.js';
 import type { SourceModuleLoaderFactory } from './module-loading-types.js';

package/src/services/module-loading/server-module-transpiler.service.js

@@ -11,7 +11,7 @@ class ServerModuleTranspiler {
    * context.
    */
   constructor(args) {
-    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService({
+    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService(void 0, {
       canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
       getHostModuleLoader: args.getHostModuleLoader
     });

package/src/services/validation/schema-validation-service.d.ts

@@ -113,10 +113,7 @@ export declare class SchemaValidationService {
     validateRequest(source: ValidationSource, schemas: ValidationSchemas): Promise<ValidationResult<ValidatedData>>;
     /**
      * Validates a single value against a Standard Schema.
-     *
-     * @param schema - The Standard Schema validator
-     * @param data - The data to validate
-     * @returns Validation result with validated data or errors
      */
+    private mapSchemaIssue;
     private validateWithSchema;
 }

package/src/services/validation/schema-validation-service.js

@@ -1,3 +1,4 @@
+import { SchemaError, validateStandardSchema } from "./validate-standard-schema.js";
 class SchemaValidationService {
   /**
    * Validates request data against provided schemas.
@@ -65,26 +66,24 @@ class SchemaValidationService {
   }
   /**
    * Validates a single value against a Standard Schema.
-   *
-   * @param schema - The Standard Schema validator
-   * @param data - The data to validate
-   * @returns Validation result with validated data or errors
    */
+  mapSchemaIssue(issue) {
+    return {
+      message: issue.message,
+      path: issue.path?.map((p) => typeof p === "object" && "key" in p ? p.key : p)
+    };
+  }
   async validateWithSchema(schema, data) {
     try {
-      const resultOrPromise = schema["~standard"].validate(data);
-      const result = resultOrPromise instanceof Promise ? await resultOrPromise : resultOrPromise;
-      if (result.issues) {
+      const value = await validateStandardSchema(schema, data);
+      return { success: true, data: value };
+    } catch (error) {
+      if (error instanceof SchemaError) {
         return {
           success: false,
-          errors: result.issues.map((issue) => ({
-            message: issue.message,
-            path: issue.path?.map((p) => typeof p === "object" && "key" in p ? p.key : p)
-          }))
+          errors: error.issues.map((issue) => this.mapSchemaIssue(issue))
         };
       }
-      return { success: true, data: result.value };
-    } catch (error) {
       return {
         success: false,
         errors: [

package/src/services/validation/standard-schema.types.d.ts

@@ -1,65 +1,12 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 /**
- * Standard Schema interface for universal validation.
- * Compatible with Zod, Valibot, ArkType, Effect Schema, and other validation libraries.
- *
+ * Ecopages aliases for the official Standard Schema V1 types.
  * @see https://standardschema.dev
- *
- * @example Using with Zod
- * ```typescript
- * import { z } from 'zod';
- *
- * const bodySchema = z.object({
- *   title: z.string().min(1),
- *   content: z.string()
- * });
- *
- * app.post('/posts', async (ctx) => {
- *   const { title, content } = ctx.body;
- *   return ctx.json({ id: 1, title, content });
- * }, {
- *   schema: { body: bodySchema }
- * });
- * ```
  */
-export interface StandardSchema<Input = unknown, Output = Input> {
-    readonly '~standard': {
-        readonly version: 1;
-        readonly vendor: string;
-        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
-        readonly types?: {
-            readonly input: Input;
-            readonly output: Output;
-        };
-    };
-}
-/**
- * Result of Standard Schema validation.
- */
-export type StandardSchemaResult<Output> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
-/**
- * Successful validation result.
- */
-export interface StandardSchemaSuccessResult<Output> {
-    readonly value: Output;
-    readonly issues?: undefined;
-}
-/**
- * Failed validation result.
- */
-export interface StandardSchemaFailureResult {
-    readonly value?: undefined;
-    readonly issues: ReadonlyArray<StandardSchemaIssue>;
-}
-/**
- * Validation issue details.
- */
-export interface StandardSchemaIssue {
-    readonly message: string;
-    readonly path?: ReadonlyArray<PropertyKey | {
-        key: PropertyKey;
-    }>;
-}
-/**
- * Infers the output type from a Standard Schema.
- */
-export type InferOutput<T extends StandardSchema> = T extends StandardSchema<any, infer O> ? O : never;
+export type StandardSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>;
+export type StandardSchemaResult<Output> = StandardSchemaV1.Result<Output>;
+export type StandardSchemaSuccessResult<Output> = StandardSchemaV1.SuccessResult<Output>;
+export type StandardSchemaFailureResult = StandardSchemaV1.FailureResult;
+export type StandardSchemaIssue = StandardSchemaV1.Issue;
+export type InferOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
+export type { StandardSchemaV1 } from '@standard-schema/spec';

package/src/services/validation/validate-standard-schema.d.ts

@@ -0,0 +1,7 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export { SchemaError } from '@standard-schema/utils';
+/**
+ * Validates a value with any Standard Schema-compliant validator.
+ * Throws {@link SchemaError} when validation fails.
+ */
+export declare function validateStandardSchema<T>(schema: StandardSchemaV1<unknown, T>, value: unknown): Promise<T>;

package/src/services/validation/validate-standard-schema.js

@@ -0,0 +1,14 @@
+import { SchemaError } from "@standard-schema/utils";
+import { SchemaError as SchemaError2 } from "@standard-schema/utils";
+async function validateStandardSchema(schema, value) {
+  const resultOrPromise = schema["~standard"].validate(value);
+  const result = resultOrPromise instanceof Promise ? await resultOrPromise : resultOrPromise;
+  if (result.issues) {
+    throw new SchemaError(result.issues);
+  }
+  return result.value;
+}
+export {
+  SchemaError2 as SchemaError,
+  validateStandardSchema
+};

package/src/static-site-generator/README.md

@@ -24,3 +24,44 @@ That means it should reuse:
 - asset processing
 
 It should not invent a parallel rendering stack just for build mode.
+
+## Files
+
+| File                           | Role                                                                         |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `static-site-generator.ts`     | Route enumeration, HTML artifact writes, integration export hooks, sitemap   |
+| `static-export-context.ts`     | Hook context type for `beforeStaticExport` / `afterStaticExport`             |
+| `sitemap.ts`                   | Pure sitemap.xml renderer                                                    |
+| `sitemap-routes.ts`            | Sitemap location assembly (`exclude`, `extraUrls`, dedupe)                   |
+| `static-build-invalidation.ts` | `dist/` reset policy, production cache clearing, static-render cache context |
+
+Build-input fingerprinting (`hashAppConfigFile`, `createBuildInputsFingerprint`) lives in `packages/core/src/build/cache/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
+
+## Incremental static export
+
+`ServerStaticBuilder.prepareExportDirectory()` decides whether to wipe `dist/`:
+
+1. `force: true` → always reset
+2. Any processor/integration reports `didChange()` → reset
+3. Route-module manifest lacks matching `configHash` + `buildInputsFingerprint` → reset
+
+When `dist/` is preserved (`preserveExportDirectory: true`), `StaticSiteGenerator.run()` prunes HTML files no longer in the active route set.
+
+Rendered HTML reuse is tracked in `.eco/.server-modules/.build-cache.json` under each route module's `renderedOutputs`. `canReuseStaticRender()` skips re-rendering when the source file, dependency hashes, and output path are unchanged.
+
+`clearProductionBuildCaches()` runs on `force` builds and removes all persisted `.eco` build manifests (route modules, server entry, unified pages graph).
+
+## Integration hooks
+
+Integrations may implement:
+
+- `beforeStaticExport(context)` — runs after unified-graph prebuild, before page rendering
+- `afterStaticExport(context)` — runs in a `finally` block after generation completes
+
+When `appConfig.sitemap.enabled` is true, `sitemap.xml` is written **after** `afterStaticExport` so integration-generated URLs can be listed via `extraUrls`.
+
+Sitemap eligibility is decided during successful page export (`activeStaticPathnames` plus `robots.index !== false`, fail-closed on metadata errors). `resolveSitemapLocations` then applies `exclude` and appends `extraUrls`.
+
+`StaticExportContext.routes` is the unfiltered static-generation route list. Sitemap filtering is applied separately.
+
+See `StaticExportContext` in `static-export-context.ts`.

package/src/static-site-generator/production-page-browser-graph-prebuild.d.ts

@@ -0,0 +1,28 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { PageRendererResolver } from '../route-renderer/route-renderer.js';
+/**
+ * Returns whether production static export should warm Page Browser Graphs before rendering.
+ *
+ * @remarks
+ * True only when `NODE_ENV === 'production'`. Independent of `force` and of
+ * unified pages-graph env flags. Does not persist a disk manifest.
+ */
+export declare function shouldPrebuildProductionPageBrowserGraphs(): boolean;
+/**
+ * Clears in-memory production Page Browser Graph session records.
+ *
+ * @remarks
+ * Clears only the `'production'` policy so a failed or force export cannot
+ * reuse staged graph output. Development session records are left intact.
+ */
+export declare function clearProductionPageBrowserGraphSession(appConfig: EcoPagesAppConfig): void;
+/**
+ * Warms production Page Browser Graphs for the supplied static route files.
+ *
+ * @remarks
+ * Deduplicates and lexicographically sorts absolute route paths, then calls
+ * each integration renderer's `prebuildProductionPageBrowserGraph` sequentially
+ * (activates integration runtime, then resolves into
+ * `page-browser-graph-session`). Does not persist a disk manifest.
+ */
+export declare function prebuildProductionPageBrowserGraphs(routeFiles: readonly string[], routeRendererFactory: PageRendererResolver): Promise<void>;

package/src/static-site-generator/production-page-browser-graph-prebuild.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { getAppPageBrowserGraphSession } from "../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js";
+function shouldPrebuildProductionPageBrowserGraphs() {
+  return process.env.NODE_ENV === "production";
+}
+function clearProductionPageBrowserGraphSession(appConfig) {
+  getAppPageBrowserGraphSession(appConfig).clearPolicyRecords("production");
+}
+async function prebuildProductionPageBrowserGraphs(routeFiles, routeRendererFactory) {
+  const uniqueRouteFiles = [...new Set(routeFiles.map((routeFile) => path.resolve(routeFile)))].sort(
+    (left, right) => left.localeCompare(right)
+  );
+  for (const routeFile of uniqueRouteFiles) {
+    const renderer = routeRendererFactory.getPageRenderer(routeFile);
+    await renderer.prebuildProductionPageBrowserGraph(routeFile);
+  }
+}
+export {
+  clearProductionPageBrowserGraphSession,
+  prebuildProductionPageBrowserGraphs,
+  shouldPrebuildProductionPageBrowserGraphs
+};

package/src/static-site-generator/sitemap-routes.d.ts

@@ -0,0 +1,14 @@
+import type { SitemapConfig } from '../types/public-types.js';
+/**
+ * Builds the ordered absolute locations for sitemap.xml.
+ *
+ * @remarks
+ * `eligiblePathnames` must already be successfully exported and robots-indexable.
+ * Filtering here is only `sitemap.exclude`, then `extraUrls` are appended.
+ * `extraUrls` always include (deduped) and are not subject to `exclude` or page robots.
+ */
+export declare function resolveSitemapLocations(input: {
+    eligiblePathnames: readonly string[];
+    sitemap: SitemapConfig;
+    baseUrl: string;
+}): string[];

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

@@ -0,0 +1,31 @@
+import { matchesAnyPathPattern, normalizePathname } from "../utils/path-pattern.js";
+import { buildSitemapLocation } from "./sitemap.js";
+function resolveSitemapLocations(input) {
+  const exclude = input.sitemap.exclude ?? [];
+  const locations = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const pathname of input.eligiblePathnames) {
+    const normalized = normalizePathname(pathname);
+    if (matchesAnyPathPattern(normalized, exclude)) {
+      continue;
+    }
+    const location = buildSitemapLocation(input.baseUrl, normalized);
+    if (seen.has(location)) {
+      continue;
+    }
+    seen.add(location);
+    locations.push(location);
+  }
+  for (const extraUrl of input.sitemap.extraUrls ?? []) {
+    const location = buildSitemapLocation(input.baseUrl, extraUrl);
+    if (seen.has(location)) {
+      continue;
+    }
+    seen.add(location);
+    locations.push(location);
+  }
+  return locations;
+}
+export {
+  resolveSitemapLocations
+};

package/src/static-site-generator/sitemap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Joins a base origin with a pathname or absolute URL into a sitemap `<loc>` value.
+ *
+ * @remarks
+ * Trailing slashes are stripped except for the site root (`/`). Absolute `http(s)`
+ * URLs in `extraUrls` are returned as-is (still slash-normalized).
+ */
+export declare function buildSitemapLocation(baseUrl: string, pathnameOrUrl: string): string;
+/**
+ * Renders a sitemap.org 0.9 urlset document from absolute location URLs.
+ *
+ * @remarks
+ * Callers are responsible for deduplication; this serializer preserves input order.
+ */
+export declare function renderSitemap(locations: readonly string[]): string;

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

@@ -0,0 +1,33 @@
+import { escapeXmlText } from "../utils/html-escaping.js";
+import { normalizePathname } from "../utils/path-pattern.js";
+function buildSitemapLocation(baseUrl, pathnameOrUrl) {
+  const trimmed = pathnameOrUrl.trim();
+  if (/^https?:\/\//i.test(trimmed)) {
+    return normalizeLocation(trimmed);
+  }
+  const origin = baseUrl.replace(/\/+$/, "");
+  const pathname = normalizePathname(trimmed);
+  return pathname === "/" ? `${origin}/` : `${origin}${pathname}`;
+}
+function renderSitemap(locations) {
+  const urls = locations.map((loc) => `  <url>
+    <loc>${escapeXmlText(normalizeLocation(loc))}</loc>
+  </url>`).join("\n");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    urls,
+    "</urlset>",
+    ""
+  ].join("\n");
+}
+function normalizeLocation(location) {
+  if (/^https?:\/\/[^/]+\/?$/i.test(location)) {
+    return `${location.replace(/\/+$/, "")}/`;
+  }
+  return location.replace(/\/+$/, "");
+}
+export {
+  buildSitemapLocation,
+  renderSitemap
+};