@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/router/pattern-matching.ts

@@ -7,58 +7,70 @@
 import type { RouteEntry, TrailingSlashMode } from "../types";
 import type { EntryData } from "../server/context";
 import { debugLog, isRouterDebugEnabled } from "./logging.js";
+import { escapeRegExp } from "../regex-escape.js";
+import { safeDecodeURIComponent } from "./url-params.js";
+import { parsePattern, type ParsedSegment } from "./parse-pattern.js";
+
+// `parsePattern`/`ParsedSegment` live in the dependency-free `parse-pattern.ts`
+// so the client reverse helper can import them without dragging this module's
+// server-only deps into the browser bundle. Re-exported here for existing
+// importers (build/route-trie, middleware, tests).
+export { parsePattern, type ParsedSegment };
 
 /**
- * Parsed segment info
+ * Compiled pattern result containing regex, param metadata, and trailing slash info.
  */
-export interface ParsedSegment {
-  type: "static" | "param" | "wildcard";
-  value: string; // static text, param name, or "*"
-  optional: boolean;
-  constraint?: string[]; // enum values like ["en", "gb"]
+export interface CompiledPattern {
+  regex: RegExp;
+  paramNames: string[];
+  hasTrailingSlash: boolean;
+  /**
+   * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
+   * Validated against the **decoded** param value after regex extraction so
+   * a URL like `/en%20GB` still matches `:lang(en GB)` — matching the trie
+   * path's behavior (trie-matching.ts:validateAndBuild).
+   */
+  constraints?: Record<string, string[]>;
+  /**
+   * The pattern's catch-all param, if any (`*` for bare `/*`, the name for a
+   * named `:name+`/`:name*`). A zero-or-more catch-all (`oneOrMore: false`)
+   * whose optional group is absent binds "" rather than being omitted — so
+   * `/docs` matches `/docs/:slug*` with `slug === ""`. `oneOrMore` keeps the
+   * same polarity as `ParsedSegment.oneOrMore` and the trie's `w1`.
+   */
+  catchAll?: { name: string; oneOrMore: boolean };
 }
 
+// Module-level cache for compiled patterns. Route patterns are a finite set
+// defined at build time, so this map is bounded by the number of routes.
+const compiledPatternCache = new Map<string, CompiledPattern>();
+
 /**
- * Parse a route pattern into segments
- *
- * Supports:
- * - Static: /blog, /about
- * - Params: /:slug, /:id
- * - Optional: /:locale?, /:page?
- * - Constrained: /:locale(en|gb), /:type(post|page)
- * - Optional + Constrained: /:locale(en|gb)?
- * - Wildcard: /*
+ * Get a compiled pattern from cache or compile and cache it.
+ * Avoids O(routes) regex compilations per request in the fallback path.
  */
-export function parsePattern(pattern: string): ParsedSegment[] {
-  const segments: ParsedSegment[] = [];
-  // Match: /segment where segment can be:
-  // - static text
-  // - :param
-  // - :param?
-  // - :param(a|b)
-  // - :param(a|b)?
-  // - *
-  const segmentRegex = /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?|(\*)|([^/]+))/g;
-
-  let match;
-  while ((match = segmentRegex.exec(pattern)) !== null) {
-    const [, , paramName, , constraint, optional, wildcard, staticText] = match;
-
-    if (wildcard) {
-      segments.push({ type: "wildcard", value: "*", optional: false });
-    } else if (paramName) {
-      segments.push({
-        type: "param",
-        value: paramName,
-        optional: optional === "?",
-        constraint: constraint ? constraint.split("|") : undefined,
-      });
-    } else if (staticText) {
-      segments.push({ type: "static", value: staticText, optional: false });
-    }
-  }
+export function getCompiledPattern(pattern: string): CompiledPattern {
+  let compiled = compiledPatternCache.get(pattern);
+  if (compiled) return compiled;
+  compiled = compilePattern(pattern);
+  compiledPatternCache.set(pattern, compiled);
+  return compiled;
+}
+
+/**
+ * Return the current size of the compiled pattern cache.
+ * Exposed for testing.
+ */
+export function getPatternCacheSize(): number {
+  return compiledPatternCache.size;
+}
 
-  return segments;
+/**
+ * Clear the compiled pattern cache.
+ * Exposed for testing.
+ */
+export function clearPatternCache(): void {
+  compiledPatternCache.clear();
 }
 
 /**
@@ -78,12 +90,7 @@ export function parsePattern(pattern: string): ParsedSegment[] {
  * compilePattern("/:locale(en|gb)/blog")  // matches /en/blog or /gb/blog
  * compilePattern("/:locale(en|gb)?/blog") // matches /blog, /en/blog, or /gb/blog
  */
-export function compilePattern(pattern: string): {
-  regex: RegExp;
-  paramNames: string[];
-  optionalParams: Set<string>;
-  hasTrailingSlash: boolean;
-} {
+export function compilePattern(pattern: string): CompiledPattern {
   // Detect if pattern has trailing slash (but not just "/")
   const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
   // Remove trailing slash for parsing (we'll add it back to regex if needed)
@@ -91,38 +98,75 @@ export function compilePattern(pattern: string): {
 
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
-  const optionalParams = new Set<string>();
+  let constraints: Record<string, string[]> | undefined;
+  let catchAll: { name: string; oneOrMore: boolean } | undefined;
 
   let regexPattern = "";
 
   for (const segment of segments) {
     if (segment.type === "wildcard") {
-      paramNames.push("*");
-      regexPattern += "/(.*)";
+      // Wildcards capture the remainder under `segment.value` ("*" for the bare
+      // form, the param name for a named catch-all).
+      paramNames.push(segment.value);
+      catchAll = { name: segment.value, oneOrMore: Boolean(segment.oneOrMore) };
+      if (segment.oneOrMore) {
+        // `:name+` — one-or-more, rejects the zero-segment (bare-prefix) case.
+        regexPattern += "/(.+)";
+      } else {
+        // Zero-or-more catch-all: named `:name*` OR the bare `/*` (both parse to
+        // `oneOrMore: false`). The whole `/segment` is optional so the bare
+        // prefix matches directly, aligning the regex fallback with the trie
+        // (which already matches the bare prefix binding "" — trie-matching.ts);
+        // buildParamsFromMatch binds "" when the optional group is absent.
+        //
+        // The bare `/*` previously used a required `/(.*)`, so `/files/*` failed
+        // to match `/files` and fell through to trailing-slash normalization,
+        // emitting a corrupt `/file` redirect instead of a match (issue #636,
+        // parity row C1). It is the same alignment #635 made for named `:name*`.
+        regexPattern += "(?:/(.*))?";
+      }
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
-      const valuePattern = segment.constraint
-        ? `(${segment.constraint.join("|")})`
-        : "([^/]+)";
+      const suffixPattern = segment.suffix ? escapeRegExp(segment.suffix) : "";
+      // Constrained params capture anything here; the allowed values are
+      // checked post-decode in findMatch so URL-encoded constraint values
+      // (e.g. `:lang(en GB)` via `/en%20GB`) still match.
+      const valuePattern = segment.suffix ? "([^/]+?)" : "([^/]+)";
+
+      if (segment.constraint) {
+        (constraints ??= {})[segment.value] = segment.constraint;
+      }
 
       if (segment.optional) {
-        optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
-        regexPattern += `(?:/${valuePattern})?`;
+        regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
-        regexPattern += `/${valuePattern}`;
+        regexPattern += `/${valuePattern}${suffixPattern}`;
       }
     } else {
       // Static segment
-      regexPattern += `/${escapeRegex(segment.value)}`;
+      regexPattern += `/${escapeRegExp(segment.value)}`;
     }
   }
 
-  // Handle root path
   if (regexPattern === "") {
     regexPattern = "/";
   }
 
+  // Patterns of only optional segments (e.g. `/:locale?`, `/:a?/:b?`) need
+  // an explicit `/` alternative so a bare `/` matches the absent form. The
+  // optional template `(?:/X)?` matches `/X` or empty string, but pathnames
+  // are never empty. Arises from `include("/:locale?", routes)` + inner
+  // `path("/")`. Skip when an explicit trailing slash already anchors the
+  // match.
+  const hasOnlyOptionalSegments =
+    !hasTrailingSlash &&
+    segments.length > 0 &&
+    segments.every((segment) => segment.type === "param" && segment.optional);
+  if (hasOnlyOptionalSegments) {
+    regexPattern = `(?:/|${regexPattern})`;
+  }
+
   // Add trailing slash to regex if pattern has one
   if (hasTrailingSlash) {
     regexPattern += "/";
@@ -131,16 +175,69 @@ export function compilePattern(pattern: string): {
   return {
     regex: new RegExp(`^${regexPattern}$`),
     paramNames,
-    optionalParams,
     hasTrailingSlash,
+    ...(constraints ? { constraints } : {}),
+    ...(catchAll ? { catchAll } : {}),
   };
 }
 
 /**
- * Escape special regex characters in a string
+ * Validate decoded params against a compiled pattern's constraints.
+ * Returns false if any constrained param has a non-empty value not in the
+ * allowed list. Absent optionals (key missing or `undefined`) are allowed;
+ * `""` is also tolerated as "absent" so user-provided params or fixtures
+ * that pass empty strings explicitly behave the same way.
  */
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function satisfiesConstraints(
+  params: Record<string, string>,
+  constraints: Record<string, string[]> | undefined,
+): boolean {
+  if (!constraints) return true;
+  for (const name in constraints) {
+    const value = params[name];
+    if (
+      value !== undefined &&
+      value !== "" &&
+      !constraints[name].includes(value)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Build the named-params record from a regex match. Optional segments that
+ * didn't capture leave the corresponding group `undefined`; we skip those
+ * keys so `ctx.params.<name>` reads as `undefined` rather than `""`. This
+ * keeps the runtime aligned with the `ExtractParams` type and matches the
+ * trie matcher's contract (see `trie-matching.ts:validateAndBuild`).
+ *
+ * A zero-or-more catch-all (`compiled.catchAll`, `oneOrMore: false`) whose
+ * optional group didn't capture binds "" instead of being omitted, so `/docs`
+ * matches `/docs/:slug*` with `slug === ""`. Exported so the `renderRoute`
+ * testing harness (`matchLeaf`) shares this exact logic instead of forking it.
+ */
+export function buildParamsFromMatch(
+  match: RegExpExecArray,
+  paramNames: string[],
+  catchAll?: { name: string; oneOrMore: boolean },
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  paramNames.forEach((name, index) => {
+    const captured = match[index + 1];
+    if (captured !== undefined) {
+      // A catch-all remainder decodes identically whether split-per-segment or
+      // whole-string (a literal `/` never lives inside a `%XX` escape), so a
+      // single decode is correct and cheapest.
+      params[name] = safeDecodeURIComponent(captured);
+    } else if (catchAll && name === catchAll.name && !catchAll.oneOrMore) {
+      // A zero-or-more catch-all (`:name*` or the bare `/*`) whose optional
+      // group was absent binds "" rather than being omitted.
+      params[name] = "";
+    }
+  });
+  return params;
 }
 
 /**
@@ -159,43 +256,58 @@ function escapeRegex(str: string): string {
 export function extractStaticPrefix(pattern: string): string {
   if (!pattern || pattern === "/") return "";
 
-  // Find the first occurrence of : or *
-  const paramIndex = pattern.indexOf(":");
-  const wildcardIndex = pattern.indexOf("*");
-
-  let cutIndex = -1;
-  if (paramIndex !== -1 && wildcardIndex !== -1) {
-    cutIndex = Math.min(paramIndex, wildcardIndex);
-  } else if (paramIndex !== -1) {
-    cutIndex = paramIndex;
-  } else if (wildcardIndex !== -1) {
-    cutIndex = wildcardIndex;
-  }
-
-  if (cutIndex === -1) {
-    // No params or wildcards - entire pattern is static
-    return pattern;
+  // Walk segments and stop at the first that is a real param (`:name`) or a
+  // wildcard (`*`). A literal `:` or `*` not at a segment boundary (e.g. the
+  // `a:b` in `/a:b/c/:id`, or `tel:+1`) is a STATIC segment and must NOT
+  // terminate the prefix — `pattern.indexOf(":")` misread it as a param marker,
+  // returning "" and dropping the findMatch fast-skip optimization for that
+  // entry on every request. Classification mirrors parsePattern: a leading `:`
+  // marks a param, a leading `*` marks a wildcard.
+  const hasLeadingSlash = pattern.startsWith("/");
+  const body = hasLeadingSlash ? pattern.slice(1) : pattern;
+  const segments = body.split("/");
+
+  const staticSegments: string[] = [];
+  for (const segment of segments) {
+    if (segment.startsWith(":") || segment.startsWith("*")) {
+      break;
+    }
+    staticSegments.push(segment);
   }
 
-  if (cutIndex === 0) {
-    // Pattern starts with : or * - no static prefix
-    return "";
-  }
+  // No leading static segment (first segment is a param/wildcard) -> no prefix.
+  if (staticSegments.length === 0) return "";
+  // Every segment was static (no param/wildcard) -> the whole pattern is the
+  // prefix. Preserve a trailing slash only when it existed in the input; a
+  // split of "/a/b" yields ["a","b"] (no empty tail) so a re-join is exact.
+  if (staticSegments.length === segments.length) return pattern;
 
-  // Find the last / before the param
-  const lastSlash = pattern.lastIndexOf("/", cutIndex - 1);
-  if (lastSlash === -1 || lastSlash === 0) {
-    return "";
-  }
+  const prefix = staticSegments.join("/");
+  return hasLeadingSlash ? "/" + prefix : prefix;
+}
 
-  return pattern.slice(0, lastSlash);
+/**
+ * Join a URL prefix to a sub-prefix, collapsing the duplicate slash when the
+ * base ends with "/" and the sub-prefix starts with "/". This mirrors the
+ * canonical join in `include()` (urls/include-helper.ts) and `runWithPrefixes`
+ * (server/context.ts) so a nested lazy include's runtime staticPrefix matches
+ * the build-time trie's `sp` (e.g. `include("/parent/", …)` containing
+ * `include("/child", …)` resolves to `/parent/child`, not `/parent//child`).
+ */
+export function joinPrefix(base: string | undefined, prefix: string): string {
+  if (!base) return prefix;
+  return base.endsWith("/") && prefix.startsWith("/")
+    ? base + prefix.slice(1)
+    : base + prefix;
 }
 
 /**
  * Match a pathname against registered routes
  *
- * Note: Optional params that are absent in the path will have empty string value.
- * Use the pattern definition to determine if a param is optional.
+ * Note: Optional params that are absent in the path are omitted from the
+ * returned `params` (read as `undefined`), matching the trie matcher and
+ * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition to
+ * determine which keys are optional.
  *
  * Trailing slash handling (priority order):
  * 1. Per-route `trailingSlash` config from route()
@@ -213,10 +325,7 @@ export interface RouteMatchResult<TEnv = any> {
   entry: RouteEntry<TEnv>;
   routeKey: string;
   params: Record<string, string>;
-  optionalParams: Set<string>;
   redirectTo?: string;
-  /** Ancestry shortCodes for layout pruning (from trie match) */
-  ancestry?: string[];
   /** Route has pre-rendered data available (from trie) */
   pr?: true;
   /** Passthrough: handler kept for live fallback on unknown params (from trie) */
@@ -240,7 +349,7 @@ export interface LazyEvaluationNeeded<TEnv = any> {
  * Type guard to check if result is a lazy evaluation needed response
  */
 export function isLazyEvaluationNeeded<TEnv>(
-  result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null
+  result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null,
 ): result is LazyEvaluationNeeded<TEnv> {
   return result !== null && "lazyEntry" in result;
 }
@@ -261,12 +370,16 @@ export function enableMatchDebug(enabled: boolean): void {
 }
 
 export function getMatchDebugStats(): MatchDebugStats {
-  return { entriesChecked: debugStats.entriesChecked, entriesSkipped: debugStats.entriesSkipped, routesChecked: debugStats.routesChecked };
+  return {
+    entriesChecked: debugStats.entriesChecked,
+    entriesSkipped: debugStats.entriesSkipped,
+    routesChecked: debugStats.routesChecked,
+  };
 }
 
 export function findMatch<TEnv>(
   pathname: string,
-  routesEntries: RouteEntry<TEnv>[]
+  routesEntries: RouteEntry<TEnv>[],
 ): RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null {
   const effectiveDebug = debugEnabled || isRouterDebugEnabled();
 
@@ -282,15 +395,14 @@ export function findMatch<TEnv>(
     }
   }
 
-  const pathnameHasTrailingSlash = pathname.length > 1 && pathname.endsWith("/");
+  const pathnameHasTrailingSlash =
+    pathname.length > 1 && pathname.endsWith("/");
   // Try alternate pathname for redirect matching
   const alternatePathname = pathnameHasTrailingSlash
     ? pathname.slice(0, -1)
     : pathname + "/";
 
   for (const entry of routesEntries) {
-    // Short-circuit: skip entry if pathname doesn't start with static prefix
-    // staticPrefix is pre-computed at registration time, so this is O(1)
     if (entry.staticPrefix && !pathname.startsWith(entry.staticPrefix)) {
       if (effectiveDebug) {
         debugStats.entriesSkipped++;
@@ -302,8 +414,6 @@ export function findMatch<TEnv>(
       continue;
     }
 
-    // Check if this is a lazy entry that needs evaluation
-    // When staticPrefix matches but routes are not yet populated, signal caller to evaluate
     if (entry.lazy && !entry.lazyEvaluated) {
       if (effectiveDebug) {
         debugLog("findMatch", "lazy entry requires evaluation", {
@@ -324,7 +434,6 @@ export function findMatch<TEnv>(
         debugStats.routesChecked++;
       }
 
-      // Join prefix and pattern, handling edge cases
       let fullPattern: string;
       if (entry.prefix === "" || entry.prefix === "/") {
         fullPattern = pattern;
@@ -334,22 +443,26 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const { regex, paramNames, optionalParams, hasTrailingSlash } = compilePattern(fullPattern);
-
-      // Get trailing slash mode for this route (per-route config or pattern-based)
-      const trailingSlashMode: TrailingSlashMode | undefined = entry.trailingSlash?.[routeKey];
+      const { regex, paramNames, hasTrailingSlash, constraints, catchAll } =
+        getCompiledPattern(fullPattern);
 
+      const trailingSlashMode: TrailingSlashMode | undefined =
+        entry.trailingSlash?.[routeKey];
 
-      // Prerender flag from entry metadata (set by urls() for prerender handlers)
-      const prFlag = entry.prerenderRouteKeys?.has(routeKey) ? { pr: true as const } : {};
+      const prFlag = entry.prerenderRouteKeys?.has(routeKey)
+        ? { pr: true as const }
+        : {};
+      const ptFlag = entry.passthroughRouteKeys?.has(routeKey)
+        ? { pt: true as const }
+        : {};
 
-      // Try exact match first
       const match = regex.exec(pathname);
       if (match) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = match[index + 1] ?? "";
-        });
+        const params = buildParamsFromMatch(match, paramNames, catchAll);
+
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
 
         if (effectiveDebug) {
           debugLog("findMatch", "matched route", {
@@ -359,47 +472,103 @@ export function findMatch<TEnv>(
           });
         }
 
-        // Check if trailing slash mode requires redirect even on exact match
-        if (trailingSlashMode === "always" && !pathnameHasTrailingSlash && pathname !== "/") {
-          // Mode says always have trailing slash, but pathname doesn't have it
-          return { entry, routeKey, params, optionalParams, redirectTo: pathname + "/", ...prFlag };
+        if (
+          trailingSlashMode === "always" &&
+          !pathnameHasTrailingSlash &&
+          pathname !== "/"
+        ) {
+          return {
+            entry,
+            routeKey,
+            params,
+            redirectTo: pathname + "/",
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
-          // Mode says never have trailing slash, but pathname has it
-          return { entry, routeKey, params, optionalParams, redirectTo: pathname.slice(0, -1), ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            redirectTo: pathname.slice(0, -1),
+            ...prFlag,
+            ...ptFlag,
+          };
         }
 
-        return { entry, routeKey, params, optionalParams, ...prFlag };
+        return {
+          entry,
+          routeKey,
+          params,
+          ...prFlag,
+          ...ptFlag,
+        };
       }
 
-      // Try alternate pathname (opposite trailing slash)
       const altMatch = regex.exec(alternatePathname);
       if (altMatch) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = altMatch[index + 1] ?? "";
-        });
+        const params = buildParamsFromMatch(altMatch, paramNames, catchAll);
+
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
 
-        // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
-          // Match without redirect
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never") {
-          // Redirect to no trailing slash
           if (pathnameHasTrailingSlash) {
-            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname, ...prFlag };
+            return {
+              entry,
+              routeKey,
+              params,
+              redirectTo: alternatePathname,
+              ...prFlag,
+              ...ptFlag,
+            };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "always") {
-          // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
-            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname, ...prFlag };
+            return {
+              entry,
+              routeKey,
+              params,
+              redirectTo: alternatePathname,
+              ...prFlag,
+              ...ptFlag,
+            };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else {
-          // No explicit mode - use pattern-based detection
-          // Redirect to canonical form (what the pattern defines)
-          const canonicalPath = hasTrailingSlash ? alternatePathname : pathname.slice(0, -1);
-          return { entry, routeKey, params, optionalParams, redirectTo: canonicalPath, ...prFlag };
+          const canonicalPath = hasTrailingSlash
+            ? alternatePathname
+            : pathname.slice(0, -1);
+          return {
+            entry,
+            routeKey,
+            params,
+            redirectTo: canonicalPath,
+            ...prFlag,
+            ...ptFlag,
+          };
         }
       }
     }
@@ -416,7 +585,7 @@ export function* traverseBack(entry: EntryData): Generator<EntryData> {
   let current: EntryData | null = entry;
   const items = [] as EntryData[];
   while (current !== null) {
-    items.push(current); // Move up to next parent
+    items.push(current);
     current = current.parent;
   }
   for (let i = items.length - 1; i >= 0; i--) {

package/src/router/prefetch-cache-ttl.ts

@@ -0,0 +1,51 @@
+/**
+ * Resolve the prefetch cache TTL once, at router init, into the three derived
+ * values the rest of the router consumes: seconds (for the Cache-Control
+ * max-age), milliseconds (for the client-side in-memory cache), and the
+ * Cache-Control header string (or false when caching is disabled).
+ *
+ * `false` disables prefetch caching (seconds 0). A non-finite input
+ * (NaN/Infinity, e.g. from an env-derived number that failed to parse) is
+ * treated as the default rather than producing a malformed
+ * `Cache-Control: max-age=NaN` header; CDNs/browsers ignore such a directive,
+ * which would silently disable caching on EVERY prefetch response. Negative
+ * finite values clamp to 0 (disabled).
+ *
+ * Policy note: this is the prefetch-TTL policy specifically. Other finite-number
+ * guards in the codebase deliberately differ — defer.ts treats Infinity as an
+ * intentional disable, and profile-registry.ts THROWS on non-finite/negative ttl
+ * at config time. They are NOT the same guard, so don't unify them.
+ */
+export interface ResolvedPrefetchCacheTTL {
+  /** TTL in seconds for the Cache-Control max-age directive. */
+  seconds: number;
+  /** TTL in milliseconds for the client-side in-memory prefetch cache. */
+  ms: number;
+  /** Cache-Control header value, or false when caching is disabled. */
+  cacheControl: string | false;
+}
+
+const DEFAULT_PREFETCH_CACHE_TTL_SECONDS = 300;
+
+export function resolvePrefetchCacheTTL(
+  rawTTL: number | false | undefined,
+): ResolvedPrefetchCacheTTL {
+  let seconds: number;
+  if (rawTTL === false) {
+    seconds = 0;
+  } else if (rawTTL === undefined) {
+    seconds = DEFAULT_PREFETCH_CACHE_TTL_SECONDS;
+  } else if (typeof rawTTL === "number" && Number.isFinite(rawTTL)) {
+    seconds = Math.max(0, Math.floor(rawTTL));
+  } else {
+    // Non-finite (NaN/Infinity): fall back to the default rather than emit a
+    // malformed max-age=NaN/Infinity that CDNs and browsers reject.
+    seconds = DEFAULT_PREFETCH_CACHE_TTL_SECONDS;
+  }
+
+  return {
+    seconds,
+    ms: seconds * 1000,
+    cacheControl: seconds === 0 ? false : `private, max-age=${seconds}`,
+  };
+}