@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/sensitive-fields.ts

@@ -0,0 +1,230 @@
+/**
+ * Sensitive field stripping — removes password/token/CVV-style fields
+ * from form values before they are echoed back to the client as
+ * `submittedValues` for form repopulation.
+ *
+ * Applied to both action paths:
+ *  - With-JS action path: `createActionClient()` in `action-client.ts`
+ *  - No-JS form POST path: `handleFormAction()` in `action-handler.ts`
+ *
+ * Why: on a validation failure, timber echoes submitted form values back so
+ * the user doesn't have to re-type everything. Without filtering, plaintext
+ * passwords / credit-card numbers / TOTP codes would travel through the RSC
+ * stream (with-JS) or land in the HTML as `defaultValue` attributes (no-JS)
+ * — ending up in browser history, proxy logs, disk caches, and the
+ * back-forward cache.
+ *
+ * Safe by default: the built-in deny-list is applied unconditionally unless
+ * the user explicitly opts out via `forms.stripSensitiveFields: false` in
+ * `timber.config.ts` or per-action via `createActionClient({ stripSensitiveFields: false })`.
+ *
+ * See design/08-forms-and-actions.md §"Validation errors"
+ * See design/13-security.md §"Sensitive field stripping"
+ * See TIM-816
+ */
+
+import { isDebug } from './debug.ts';
+
+// ─── Public types ────────────────────────────────────────────────────────
+
+/**
+ * How to strip sensitive fields from `submittedValues`.
+ *
+ * - `true` / `undefined` — use the built-in deny-list (default, safe).
+ * - `false` — do not strip anything (dev convenience; never do this in prod).
+ * - `string[]` — additional field names to strip, merged with the built-in list.
+ * - `(name) => boolean` — custom predicate, fully replaces the built-in list.
+ *   Return `true` to strip, `false` to keep. The `name` argument is the raw
+ *   (un-normalized) field name as it appeared in the submitted form.
+ */
+export type SensitiveFieldsOption = boolean | readonly string[] | ((name: string) => boolean);
+
+// ─── Built-in deny-list ──────────────────────────────────────────────────
+
+/**
+ * Substring patterns matched against the normalized field name.
+ * Normalization = lowercase + strip `_` and `-`.
+ *
+ * Any field whose normalized name *contains* one of these strings is
+ * considered sensitive. Entries like `currentPassword`, `passwordConfirmation`,
+ * and `user.password` all match via the `password` substring.
+ */
+const BUILTIN_SUBSTRING_PATTERNS: readonly string[] = [
+  'password',
+  'passwd',
+  'pwd',
+  'secret',
+  'apikey',
+  'accesstoken',
+  'refreshtoken',
+  'cvv',
+  'cvc',
+  'cardnumber',
+  'cardcvc',
+  'ssn',
+  'socialsecuritynumber',
+  'otp',
+  'totp',
+  'mfacode',
+  'twofactorcode',
+  'privatekey',
+];
+
+/**
+ * Exact matches against the normalized field name. These are field names that
+ * are too short or too common to substring-match safely. e.g. `token` alone
+ * would match `csrfToken`, which is not sensitive — so `token` is exact-only,
+ * while legitimate token fields are covered by `accesstoken` / `refreshtoken`.
+ */
+const BUILTIN_EXACT_PATTERNS: readonly string[] = ['token'];
+
+/**
+ * Normalize a field name for deny-list comparison.
+ * Lowercases the string and strips `_` and `-` so camelCase, snake_case, and
+ * kebab-case variants all compare equal (`api_key` / `apiKey` / `api-key` →
+ * `apikey`).
+ */
+function normalize(name: string): string {
+  let out = '';
+  for (let i = 0; i < name.length; i++) {
+    const ch = name.charCodeAt(i);
+    if (ch === 0x5f /* _ */ || ch === 0x2d /* - */) continue;
+    // A-Z → a-z
+    if (ch >= 0x41 && ch <= 0x5a) {
+      out += String.fromCharCode(ch + 32);
+    } else {
+      out += name[i];
+    }
+  }
+  return out;
+}
+
+/**
+ * Check whether a name matches the built-in deny-list (with optional extras).
+ * Extras are merged into the substring pattern list after normalization.
+ */
+function isBuiltinSensitive(name: string, extras?: readonly string[]): boolean {
+  const normalized = normalize(name);
+  if (BUILTIN_EXACT_PATTERNS.includes(normalized)) return true;
+  for (const pattern of BUILTIN_SUBSTRING_PATTERNS) {
+    if (normalized.includes(pattern)) return true;
+  }
+  if (extras && extras.length > 0) {
+    for (const extra of extras) {
+      const normExtra = normalize(extra);
+      if (normExtra.length === 0) continue;
+      if (normalized.includes(normExtra)) return true;
+    }
+  }
+  return false;
+}
+
+// ─── Predicate resolution ────────────────────────────────────────────────
+
+/**
+ * A resolved predicate: `null` means "don't strip anything" (the option was
+ * explicitly `false`). Otherwise a function from raw field name → boolean.
+ */
+export type ResolvedSensitivePredicate = ((name: string) => boolean) | null;
+
+/**
+ * Resolve a `SensitiveFieldsOption` into a concrete predicate.
+ * Precedence: per-action > global > built-in default.
+ *
+ * - Per-action `undefined` → fall back to global.
+ * - Global `undefined` → use built-in list.
+ * - Either level set to `false` → disable stripping entirely (returns `null`).
+ * - `true` → built-in list.
+ * - `string[]` → built-in ∪ extras.
+ * - function → custom, replaces the built-in list entirely.
+ */
+export function resolveSensitivePredicate(
+  perAction: SensitiveFieldsOption | undefined,
+  global: SensitiveFieldsOption | undefined
+): ResolvedSensitivePredicate {
+  const chosen = perAction !== undefined ? perAction : global;
+
+  if (chosen === false) return null;
+  if (chosen === undefined || chosen === true) {
+    return (name) => isBuiltinSensitive(name);
+  }
+  if (typeof chosen === 'function') {
+    return chosen;
+  }
+  // Array of extra names merged with the built-in list.
+  const extras = chosen;
+  return (name) => isBuiltinSensitive(name, extras);
+}
+
+// ─── Module-level global config ──────────────────────────────────────────
+
+let globalConfig: SensitiveFieldsOption | undefined;
+
+/**
+ * Set the global `forms.stripSensitiveFields` config from `timber.config.ts`.
+ * Called once at startup from `rsc-entry`.
+ */
+export function setGlobalSensitiveFieldsConfig(option: SensitiveFieldsOption | undefined): void {
+  globalConfig = option;
+}
+
+/** Read the global `forms.stripSensitiveFields` config. */
+export function getGlobalSensitiveFieldsConfig(): SensitiveFieldsOption | undefined {
+  return globalConfig;
+}
+
+// ─── Stripping ───────────────────────────────────────────────────────────
+
+// One warning per field name per process — prevents log spam when a form is
+// submitted many times in dev mode.
+const warnedFields = new Set<string>();
+
+function warnStripped(name: string): void {
+  if (!isDebug()) return;
+  if (warnedFields.has(name)) return;
+  warnedFields.add(name);
+  console.warn(
+    `[timber] stripped sensitive field "${name}" from submittedValues. ` +
+      `Override via forms.stripSensitiveFields in timber.config.ts.`
+  );
+}
+
+/**
+ * Walk an object (recursively) and return a copy with every key matching
+ * `predicate` removed. Nested objects like `{ user: { password: '...' } }`
+ * are handled — `user.password` is stripped while other `user.*` fields remain.
+ *
+ * - Arrays are walked element-wise (object entries inside arrays are cleaned).
+ * - Non-plain values (strings, numbers, Files, Dates, etc.) are returned as-is.
+ * - When a stripped key is encountered, it is omitted from the result entirely
+ *   — we do NOT set it to an empty string, because that would overwrite a
+ *   valid `defaultValue` the form author might have set.
+ */
+export function stripSensitiveFields<T>(value: T, predicate: ResolvedSensitivePredicate): T {
+  // Null predicate = stripping disabled entirely.
+  if (predicate === null) return value;
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+  if (value instanceof File || value instanceof Date) return value;
+
+  if (Array.isArray(value)) {
+    return value.map((item) => stripSensitiveFields(item, predicate)) as unknown as T;
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+    if (predicate(key)) {
+      warnStripped(key);
+      continue;
+    }
+    result[key] = stripSensitiveFields(nested, predicate);
+  }
+  return result as unknown as T;
+}
+
+// ─── Test helpers ────────────────────────────────────────────────────────
+
+/** Reset the "warned once" cache. Exposed for tests. */
+export function __resetSensitiveFieldsWarnings(): void {
+  warnedFields.clear();
+}

package/src/server/server-only-guard-noop.js

@@ -0,0 +1,3 @@
+// No-op module for Node.js and vitest resolution of #server-only-guard.
+// The shims plugin intercepts this specifier in the client environment
+// and returns the server-only poison pill instead.

package/src/server/server-timing.ts

@@ -11,7 +11,7 @@
  * Task: LOCAL-290
  */
 
-import { timingAls } from './als-registry.js';
+import { timingAls } from './als-registry.ts';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 

package/src/server/signal-identity.ts

@@ -0,0 +1,112 @@
+// Signal identity — the brands framework signals carry, the predicates that
+// recognise them, and SsrStreamError.
+//
+// No runtime imports (the one import is type-only), so any environment can
+// load it. The SSR entry's import graph
+// must not reach RSC request state (`request-context.ts` and friends, held
+// to that by `tests/ssr-import-boundary.test.ts`), and the signal classes
+// in primitives.ts sit beside `deny()` and `redirect()`, which read it. SSR
+// code that has to recognise a signal (the logger skips them) imports the
+// predicates from here; the classes stamp the brands exported here.
+
+import type { DenySignal, RedirectSignal } from './primitives.ts';
+
+// ─── Signal branding ────────────────────────────────────────────────────────
+//
+// Catch sites must NOT use `instanceof` on these classes. In dev, an HMR
+// program reload clears the RSC module cache; a request that is mid-render
+// still holds the catch sites from the old evaluation of primitives.ts while
+// user code loaded after the reload throws from the new one. The two
+// evaluations are distinct classes, so `instanceof` fails and a correct
+// deny() falls through every catch site as an unhandled 500 (TIM-1499).
+//
+// Each class stamps a `Symbol.for` brand on its instances in the constructor.
+// `Symbol.for` keys live in the realm-wide symbol registry, so every
+// evaluation of these modules — and every module graph in the same process —
+// agrees on the key. The `is*` predicates below check the brand and are the
+// only supported way to detect a signal. The classes themselves are NOT
+// anchored on globalThis: a re-evaluated module must hand out its own
+// (possibly updated) class, not a stale one.
+//
+// See design/18-build-system.md §"Dev Mode: Signal Identity Across Program Reloads".
+
+export const DENY_BRAND: unique symbol = Symbol.for('timber:signal.deny');
+export const REDIRECT_BRAND: unique symbol = Symbol.for('timber:signal.redirect');
+const SSR_STREAM_ERROR_BRAND: unique symbol = Symbol.for('timber:signal.ssr-stream-error');
+
+function hasBrand(value: unknown, brand: symbol): boolean {
+  return typeof value === 'object' && value !== null && brand in value;
+}
+
+/** True for any `DenySignal`, regardless of which module evaluation created it. */
+export function isDenySignal(error: unknown): error is DenySignal {
+  return hasBrand(error, DENY_BRAND);
+}
+
+/** True for any `RedirectSignal`, regardless of which module evaluation created it. */
+export function isRedirectSignal(error: unknown): error is RedirectSignal {
+  return hasBrand(error, REDIRECT_BRAND);
+}
+
+/**
+ * True for any `SsrStreamError`. This one also crosses Vite environments:
+ * it is thrown in SSR and caught in RSC, which are separate module graphs in
+ * the same process — the brand is the only identity the two share.
+ */
+export function isSsrStreamError(error: unknown): error is SsrStreamError {
+  return hasBrand(error, SSR_STREAM_ERROR_BRAND);
+}
+
+/**
+ * Returns true if the error is a framework control-flow signal (RedirectSignal
+ * or DenySignal) rather than a genuine application error. Works both for direct
+ * instances (RSC-side) and deserialized digest errors (SSR cross-boundary).
+ *
+ * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
+ */
+export function isControlFlowSignal(error: unknown): boolean {
+  if (isDenySignal(error) || isRedirectSignal(error)) {
+    return true;
+  }
+  if (error && typeof error === 'object') {
+    const digest = (error as { digest?: unknown }).digest;
+    if (typeof digest === 'string') {
+      try {
+        const parsed = JSON.parse(digest) as { type?: unknown } | null;
+        if (parsed && typeof parsed === 'object') {
+          return parsed.type === 'redirect' || parsed.type === 'deny';
+        }
+      } catch {
+        // Not valid digest JSON
+      }
+    }
+  }
+  return false;
+}
+
+// ─── SsrStreamError ─────────────────────────────────────────────────────────
+
+/**
+ * Error thrown when SSR's renderToReadableStream fails due to an error
+ * in the decoded RSC stream (e.g., uncontained slot errors).
+ *
+ * The RSC entry checks for this error type in its catch block. A captured
+ * deny or redirect is rethrown to the pipeline first; with no captured
+ * signal, it renders the error page for the uncontained error.
+ *
+ * Not defined in ssr-entry.ts because ssr-entry.ts imports react-dom/server,
+ * which cannot be loaded in the RSC environment.
+ *
+ * Detect with `isSsrStreamError()` — it is thrown in the SSR environment and
+ * caught in RSC, so `instanceof` never matches. See "Signal branding" above.
+ */
+export class SsrStreamError extends Error {
+  readonly [SSR_STREAM_ERROR_BRAND] = true;
+  override readonly cause: unknown;
+
+  constructor(message: string, cause: unknown) {
+    super(message);
+    this.name = 'SsrStreamError';
+    this.cause = cause;
+  }
+}

package/src/server/sitemap-generator.ts

@@ -0,0 +1,337 @@
+/**
+ * Auto-generate sitemap.xml from the route tree.
+ *
+ * When enabled via `sitemap: { enabled: true, baseUrl: '...' }` in timber.config.ts,
+ * this module walks the route tree and produces sitemap XML for all discoverable pages.
+ *
+ * Features:
+ * - Collects all static page routes automatically
+ * - Calls `generateStaticSegmentParams()` on dynamic routes to enumerate URLs
+ * - Skips API routes (route.ts), layout-only segments, slots, intercepting routes
+ * - Skips auth-protected routes (access.ts in segment chain) by default
+ * - Automatic pagination: sitemap index when > 50,000 URLs
+ *
+ * See design/16-metadata.md §"Auto-generated Sitemap"
+ */
+
+import { serializeSitemap, serializeSitemapIndex } from './pipeline-metadata.ts';
+import type { SegmentNode } from '../routing/types.ts';
+import type { CoercedParams } from '../shared/param-value.ts';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** Configuration for sitemap generation from timber.config.ts. */
+export interface SitemapConfig {
+  /** Must be explicitly true to enable auto-generation. */
+  enabled: boolean;
+  /** Base URL for absolute URLs in the sitemap. Required. e.g., 'https://example.com' */
+  baseUrl: string;
+  /** Default changefreq for all entries. Optional. */
+  defaultChangeFrequency?: string;
+  /** Default priority for all entries (0.0–1.0). Optional. */
+  defaultPriority?: number;
+  /** Include routes protected by access.ts. Default: false. */
+  includeProtected?: boolean;
+}
+
+/** A single sitemap entry ready for serialization. */
+export interface SitemapEntry {
+  url: string;
+  changeFrequency?: string;
+  priority?: number;
+}
+
+/**
+ * A route discovered during tree walk that may need async resolution
+ * (dynamic routes with generateStaticSegmentParams).
+ */
+export interface SitemapRoute {
+  /** The URL path pattern (e.g., '/products/[id]'). */
+  urlPath: string;
+  /** Whether this route has dynamic segments that need generateStaticSegmentParams. */
+  isDynamic: boolean;
+  /** Loader for the page module (from route manifest). */
+  pageLoader?: { load: () => Promise<unknown>; filePath: string };
+}
+
+/**
+ * Function signature for loading a page module.
+ * Takes the manifest loader and returns the module exports.
+ */
+export type ModuleLoader = (loader: {
+  load: () => Promise<unknown>;
+  filePath: string;
+}) => Promise<Record<string, unknown>>;
+
+/** Result of sitemap generation. */
+export type SitemapResult =
+  | { type: 'single'; xml: string }
+  | { type: 'index'; indexXml: string; pages: Map<number, string> };
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Maximum URLs per sitemap file per the sitemap protocol. */
+export const URLS_PER_SITEMAP = 50_000;
+
+// ─── Tree Walking ────────────────────────────────────────────────────────────
+
+/**
+ * Walk the route tree and collect all routes eligible for the sitemap.
+ *
+ * Pure synchronous function — no module loading. Returns routes that may
+ * need async resolution (dynamic routes with generateStaticSegmentParams).
+ *
+ * @param root - The root segment node from the route tree
+ * @param config - Sitemap configuration
+ * @returns Array of sitemap routes to resolve
+ */
+export function collectSitemapRoutes(root: SegmentNode, config: SitemapConfig): SitemapRoute[] {
+  const routes: SitemapRoute[] = [];
+  walkNode(root, routes, config.includeProtected ?? false, false);
+  return routes;
+}
+
+/**
+ * Recursive tree walker. Collects page routes, skipping ineligible segments.
+ *
+ * @param node - Current segment node
+ * @param routes - Accumulator for discovered routes
+ * @param includeProtected - Whether to include routes with access.ts
+ * @param hasAccessInChain - Whether any ancestor has access.ts
+ */
+function walkNode(
+  node: SegmentNode,
+  routes: SitemapRoute[],
+  includeProtected: boolean,
+  hasAccessInChain: boolean
+): void {
+  // Track whether this node or any ancestor has access.ts
+  const protectedChain = hasAccessInChain || !!node.access;
+
+  // Skip intercepting routes — they're conditional rewrites, not real pages
+  if (node.segmentType === 'intercepting') return;
+
+  // Skip private folders
+  if (node.segmentType === 'private') return;
+
+  // Skip slots — parallel routes don't contribute independent URLs
+  // (slots are handled via the parent's slots map, but we skip them here)
+
+  // Check if this node has a page (not a route.ts API endpoint)
+  if (node.page && !node.route) {
+    // Skip protected routes unless configured to include them
+    if (!protectedChain || includeProtected) {
+      const isDynamic = hasDynamicSegments(node.urlPath);
+      // At runtime (manifest), page has a `load` function. At scan time (RouteFile),
+      // it only has filePath + extension. We check for `load` at runtime.
+      const page = node.page as {
+        filePath: string;
+        extension: string;
+        load?: () => Promise<unknown>;
+      };
+      routes.push({
+        urlPath: node.urlPath,
+        isDynamic,
+        pageLoader: page.load ? { load: page.load, filePath: page.filePath } : undefined,
+      });
+    }
+  }
+
+  // Recurse into children (not slots — slots don't contribute sitemap URLs)
+  for (const child of node.children) {
+    walkNode(child, routes, includeProtected, protectedChain);
+  }
+
+  // Do NOT recurse into slots — they are parallel routes at the same URL
+}
+
+/**
+ * Check if a URL path contains dynamic segments.
+ *
+ * Dynamic segments are enclosed in brackets: [param], [...param], [[...param]]
+ */
+export function hasDynamicSegments(urlPath: string): boolean {
+  return /\[/.test(urlPath);
+}
+
+// ─── URL Resolution ──────────────────────────────────────────────────────────
+
+/**
+ * Resolve sitemap routes into concrete URLs.
+ *
+ * For static routes, the URL is derived directly from the path.
+ * For dynamic routes, calls `generateStaticSegmentParams()` from the page module.
+ *
+ * @param routes - Routes collected by collectSitemapRoutes
+ * @param config - Sitemap configuration
+ * @param loadModule - Async function to load a page module by file path
+ * @returns Array of sitemap entries with absolute URLs
+ */
+export async function resolveSitemapUrls(
+  routes: SitemapRoute[],
+  config: SitemapConfig,
+  loadModule?: ModuleLoader
+): Promise<SitemapEntry[]> {
+  const baseUrl = config.baseUrl.replace(/\/+$/, ''); // strip trailing slash
+  const entries: SitemapEntry[] = [];
+
+  for (const route of routes) {
+    if (!route.isDynamic) {
+      // Static route — direct URL
+      const url = route.urlPath === '/' ? baseUrl + '/' : baseUrl + route.urlPath;
+      entries.push({
+        url,
+        changeFrequency: config.defaultChangeFrequency,
+        priority: config.defaultPriority,
+      });
+    } else if (loadModule && route.pageLoader) {
+      // Dynamic route — try to call generateStaticSegmentParams
+      try {
+        const mod = await loadModule(route.pageLoader);
+        const generateFn = mod.generateStaticSegmentParams;
+        if (typeof generateFn !== 'function') {
+          // No generateStaticSegmentParams export — skip this dynamic route
+          continue;
+        }
+
+        const paramSets: Record<string, string>[] = await generateFn();
+        for (const params of paramSets) {
+          const resolvedPath = resolvePathWithParams(route.urlPath, params);
+          if (resolvedPath) {
+            entries.push({
+              url: baseUrl + resolvedPath,
+              changeFrequency: config.defaultChangeFrequency,
+              priority: config.defaultPriority,
+            });
+          }
+        }
+      } catch (error) {
+        // Log and skip — don't fail the entire sitemap for one bad route
+        const filePath = route.pageLoader.filePath;
+        console.warn(
+          `[timber] sitemap: failed to call generateStaticSegmentParams for ${filePath}:`,
+          error instanceof Error ? error.message : error
+        );
+      }
+    }
+    // If no loadModule provided and route is dynamic, skip it
+  }
+
+  return entries;
+}
+
+/**
+ * Replace dynamic segments in a URL path with concrete param values.
+ *
+ * Handles:
+ * - `[param]` → single value
+ * - `[...param]` → slash-joined values
+ * - `[[...param]]` → slash-joined values (or empty string if not provided)
+ *
+ * @returns The resolved path, or null if params are missing
+ */
+export function resolvePathWithParams(urlPath: string, params: CoercedParams): string | null {
+  let resolved = urlPath;
+
+  // Optional catch-all: [[...param]]
+  resolved = resolved.replace(/\[\[\.\.\.([^\]]+)\]\]/g, (_, name) => {
+    const value = params[name];
+    if (value === undefined || value === '') return '';
+    if (Array.isArray(value)) return value.map(String).join('/');
+    return String(value);
+  });
+
+  // Catch-all: [...param]
+  resolved = resolved.replace(/\[\.\.\.([^\]]+)\]/g, (_, name) => {
+    const value = params[name];
+    if (value === undefined) return '';
+    if (Array.isArray(value)) return value.map(String).join('/');
+    return String(value);
+  });
+
+  // Single dynamic: [param] (possibly with affixes like img-[id].png)
+  // Match optional prefix before [ and optional suffix after ]
+  let missingRequired = false;
+  resolved = resolved.replace(/([^/[]*)\[([^\]]+)\]([^/[]*)/g, (match, prefix, name, suffix) => {
+    const value = params[name];
+    if (value === undefined) {
+      missingRequired = true;
+      return match; // keep original to avoid malformed URL
+    }
+    const v = Array.isArray(value) ? String(value[0] ?? '') : String(value);
+    return prefix + v + suffix;
+  });
+
+  if (missingRequired) return null;
+
+  // Clean up double slashes from empty optional catch-alls
+  resolved = resolved.replace(/\/+/g, '/');
+
+  // Remove trailing slash (except for root)
+  if (resolved.length > 1 && resolved.endsWith('/')) {
+    resolved = resolved.slice(0, -1);
+  }
+
+  return resolved;
+}
+
+// ─── Sitemap Generation ──────────────────────────────────────────────────────
+
+/**
+ * Generate the complete sitemap result from a route tree.
+ *
+ * Orchestrates tree walking, URL resolution, and XML serialization.
+ * Returns either a single sitemap or a paginated sitemap index.
+ *
+ * @param root - The root segment node from the route tree
+ * @param config - Sitemap configuration
+ * @param loadModule - Optional async function to load page modules (for generateStaticSegmentParams)
+ * @returns The sitemap result (single or index with pages)
+ */
+export async function generateSitemap(
+  root: SegmentNode,
+  config: SitemapConfig,
+  loadModule?: ModuleLoader
+): Promise<SitemapResult> {
+  const routes = collectSitemapRoutes(root, config);
+  const entries = await resolveSitemapUrls(routes, config, loadModule);
+
+  if (entries.length <= URLS_PER_SITEMAP) {
+    // Single sitemap
+    return {
+      type: 'single',
+      xml: serializeSitemap(entries),
+    };
+  }
+
+  // Paginated — split into chunks
+  const baseUrl = config.baseUrl.replace(/\/+$/, '');
+  const pageCount = Math.ceil(entries.length / URLS_PER_SITEMAP);
+  const pages = new Map<number, string>();
+  const sitemapUrls: string[] = [];
+
+  for (let i = 0; i < pageCount; i++) {
+    const start = i * URLS_PER_SITEMAP;
+    const end = Math.min(start + URLS_PER_SITEMAP, entries.length);
+    const chunk = entries.slice(start, end);
+    pages.set(i, serializeSitemap(chunk));
+    sitemapUrls.push(`${baseUrl}/sitemap/${i}.xml`);
+  }
+
+  return {
+    type: 'index',
+    indexXml: serializeSitemapIndex(sitemapUrls),
+    pages,
+  };
+}
+
+/**
+ * Check if the route tree root has a user-authored sitemap metadata route.
+ *
+ * When a user-authored sitemap exists at the root, auto-generation is disabled
+ * to avoid conflicts — the user takes full control.
+ */
+export function hasUserSitemap(root: SegmentNode<unknown>): boolean {
+  if (!root.metadataRoutes) return false;
+  return 'sitemap' in root.metadataRoutes;
+}