@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.126

package/src/browser/server-action-bridge.ts

@@ -23,7 +23,10 @@ import {
   isBrowserDebugEnabled,
   startBrowserTransaction,
 } from "./logging.js";
-import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import {
+  validateRedirectOrigin,
+  validateExternalRedirect,
+} from "./validate-redirect-origin.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -83,6 +86,9 @@ export function createServerActionBridge(
 
   // SPA-navigate when onNavigate is set, else hard-reload. state is omitted (not
   // passed as undefined) to match the header path's prior call shape.
+  // Callers pass an already same-origin-validated url; the hard-reload fallback
+  // re-validates defensively so this leaf cannot become an open redirect if a
+  // future caller forgets (the SPA path validates inside the navigation bridge).
   async function dispatchRedirect(url: string, state?: unknown): Promise<void> {
     if (onNavigate) {
       await onNavigate(url, {
@@ -91,7 +97,10 @@ export function createServerActionBridge(
         _skipCache: true,
       });
     } else {
-      window.location.href = url;
+      const safe = validateRedirectOrigin(url, window.location.origin);
+      if (safe) {
+        window.location.href = safe;
+      }
     }
   }
 
@@ -161,6 +170,15 @@ export function createServerActionBridge(
     // Whether the action's response carried the keepClientCache() directive.
     // Set when the response arrives; gates the deferred invalidation below.
     let keepCache = false;
+    // Whether a Response actually settled from the network (the server saw the
+    // request). Set true as the first statement in the fetch .then() below.
+    // Gates the automatic invalidation: a pre-dispatch failure (encodeReply
+    // throw or a fetch rejection — server unreachable/DNS/connection refused)
+    // leaves this false, so finalizeAction() must NOT invalidate or broadcast —
+    // nothing reached the server, so nothing could have mutated. A failed Flight
+    // DECODE after the response arrived keeps it true (the mutation may have
+    // committed, so invalidating the now-possibly-stale client cache is correct).
+    let responseReceived = false;
     // Single deferred invalidation + fence release, run exactly ONCE however the
     // action terminates (normal, redirect, error, abort, intercept, concurrent).
     // This replaces main's eager clear at action start: every directive-free
@@ -176,7 +194,10 @@ export function createServerActionBridge(
       actionFinalized = true;
       // finally so a throw in invalidation cannot leak the fence (latch is set).
       try {
-        if (!keepCache && !skipInvalidation) {
+        // responseReceived gates the automatic invalidation: a pre-dispatch
+        // failure (serialize throw / fetch reject) never reached the server, so
+        // marking the cache stale + broadcasting cross-tab would be spurious.
+        if (responseReceived && !keepCache && !skipInvalidation) {
           store.markCacheAsStaleAndBroadcast();
         }
       } finally {
@@ -263,6 +284,12 @@ export function createServerActionBridge(
         body: encodedBody,
         signal: fetchAbort.signal,
       }).then(async (response) => {
+        // A settled fetch promise means the request reached the server and a
+        // Response came back (true for 2xx, 4xx, AND 5xx — fetch only rejects
+        // on network-layer failure, never on HTTP status). Record it as the
+        // first statement so every downstream terminal can invalidate; a
+        // pre-dispatch failure never gets here and stays gated out.
+        responseReceived = true;
         // Response arrived — disconnect fetch abort from handle abort so
         // abortAllActions() doesn't disrupt the in-progress Flight stream.
         handle.signal.removeEventListener("abort", onHandleAbort);
@@ -399,6 +426,27 @@ export function createServerActionBridge(
       // Check handle.signal.aborted to avoid redirecting from a stale action
       // when the user has already navigated away.
       if (metadata?.redirect && !handle.signal.aborted) {
+        // Explicit off-host redirect (redirect(url, { external: true })):
+        // hard-navigate, but still scheme-validate (http/https only). external
+        // waives the same-origin check, NOT scheme safety, so a forged payload
+        // carrying a javascript:/data: URL cannot script via location.assign.
+        if (metadata.redirect.external) {
+          const externalUrl = validateExternalRedirect(
+            metadata.redirect.url,
+            window.location.origin,
+          );
+          if (!externalUrl) {
+            log("blocked external action redirect payload", {
+              url: metadata.redirect.url,
+            });
+            handle.complete(returnValue?.data);
+            return returnValue?.data;
+          }
+          log("external action redirect", { url: externalUrl });
+          handle.complete(returnValue?.data);
+          window.location.assign(externalUrl);
+          return returnValue?.data;
+        }
         const redirectUrl = validateRedirectOrigin(
           metadata.redirect.url,
           window.location.origin,

package/src/browser/types.ts

@@ -14,7 +14,6 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 export interface RscPayload<TMetadata = RscMetadata> {
   metadata?: TMetadata;
   returnValue?: ActionResult;
-  formState?: unknown;
 }
 
 /**
@@ -91,8 +90,12 @@ export interface RscMetadata {
   basename?: string;
   /** Whether connection warmup is enabled */
   warmupEnabled?: boolean;
-  /** Server-side redirect with optional state (for partial requests) */
-  redirect?: { url: string };
+  /**
+   * Server-side redirect with optional state (for partial requests).
+   * `external: true` (from redirect(url, { external: true })) tells the client
+   * to hard-navigate to an off-host target instead of validating same-origin.
+   */
+  redirect?: { url: string; external?: boolean };
   /** Server-set location state to include in history.pushState */
   locationState?: Record<string, unknown>;
 }
@@ -193,6 +196,15 @@ export interface TrackedActionState {
   result: unknown | null;
 }
 
+/**
+ * The value returned by {@link useAction} when called without a selector.
+ *
+ * This is the stable, public name for the action-state shape; consumers can
+ * name it in their own signatures (e.g. a wrapper hook). It aliases the
+ * internal {@link TrackedActionState}.
+ */
+export type ActionState = TrackedActionState;
+
 /**
  * Listener for action state changes
  *
@@ -330,8 +342,14 @@ export interface RouterInstance {
   replace(url: string, options?: RouterNavigateOptions): Promise<void>;
   /** Refresh the current route (re-fetch server data, preserve client state) */
   refresh(): Promise<void>;
-  /** Prefetch a URL for faster client-side transition */
-  prefetch(url: string): void;
+  /**
+   * Prefetch a URL for faster client-side transition.
+   *
+   * Pass `{ key: ":source" }` to source-scope the prefetch cache entry (parity
+   * with `<Link prefetchKey=":source">`) when the target's response can differ
+   * by source page.
+   */
+  prefetch(url: string, options?: { key?: ":source" }): void;
   /** Go back in browser history */
   back(): void;
   /** Go forward in browser history */

package/src/browser/validate-redirect-origin.ts

@@ -1,29 +1,56 @@
+import {
+  resolveSameOriginRedirect,
+  resolveExternalRedirect,
+} from "../redirect-origin.js";
+
 /**
  * Validate that a client-consumed redirect URL (from headers or Flight payload)
  * targets the same origin as the current page. Prevents open-redirect attacks
  * via crafted responses.
  *
+ * Thin wrapper over the shared {@link resolveSameOriginRedirect} rule (also used
+ * by the server guard in `rsc/redirect-guard.ts`) so client and server enforce
+ * the identical same-origin contract. Adds the client-side `console.error` on a
+ * block; the resolver itself stays pure.
+ *
  * @returns The canonical (normalized) URL string on success, or null if blocked.
  */
 export function validateRedirectOrigin(
   url: string,
   currentOrigin: string,
 ): string | null {
-  try {
-    const target = new URL(url, currentOrigin);
-    if (target.origin !== currentOrigin) {
-      console.error(
-        `[rango] Redirect blocked: origin mismatch (${target.origin})`,
-      );
-      return null;
-    }
-    // Return pathname+search+hash for relative inputs, full href for absolute.
-    // This normalizes protocol-relative and other ambiguous forms.
-    return target.href.startsWith(currentOrigin)
-      ? target.href
-      : target.pathname + target.search + target.hash;
-  } catch {
-    console.error(`[rango] Redirect blocked: invalid URL "${url}"`);
-    return null;
+  const resolved = resolveSameOriginRedirect(url, currentOrigin);
+  if (resolved === null) {
+    console.error(
+      `[rango] Redirect blocked: cross-origin or invalid target "${url}"`,
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Validate an explicit off-origin redirect (`redirect(url, { external: true })`)
+ * the client is about to hard-navigate to via `window.location.assign()`.
+ *
+ * Thin wrapper over the shared {@link resolveExternalRedirect} rule (also used by
+ * the server guard in `rsc/redirect-guard.ts`) so client and server enforce the
+ * identical contract: `external` allows an off-origin target but only an
+ * http(s) scheme. This stops a forged or mistaken external payload carrying a
+ * `javascript:`/`data:` URL from turning `location.assign` into a scriptable
+ * navigation. Adds the client-side `console.error` on a block; the resolver
+ * itself stays pure.
+ *
+ * @returns The normalized URL string on success, or null if blocked.
+ */
+export function validateExternalRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  const resolved = resolveExternalRedirect(url, currentOrigin);
+  if (resolved === null) {
+    console.error(
+      `[rango] External redirect blocked: non-http(s) target "${url}"`,
+    );
   }
+  return resolved;
 }

package/src/build/index.ts

@@ -22,15 +22,14 @@ export {
   type GeneratedManifest,
 } from "./generate-manifest.js";
 
-export {
-  buildRouteTrie,
-  buildPerRouterTrie,
-  type TrieNode,
-  type TrieLeaf,
-} from "./route-trie.js";
-
-export { collectFallbackClientRefs } from "./collect-fallback-refs.js";
-
+// buildRouteTrie / buildPerRouterTrie / collectFallbackClientRefs and the
+// TrieNode/TrieLeaf types are NOT exported here: they are build-pipeline
+// internals, not public API. Their only build-time consumer (the Vite
+// discovery pass) imports them directly from source via a relative path
+// (vite/discovery/discover-routers.ts), and the runtime RSC realm likewise
+// imports route-trie.js directly (rsc/manifest-init.ts). Keeping them off the
+// public ./build surface (#569 decision 6) means consumers can't mistake them
+// for intended API. generateManifest* / route-types / hashParams stay public.
 export {
   writePerModuleRouteTypes,
   extractRoutesFromSource,

package/src/build/route-trie.ts

@@ -22,9 +22,6 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names declared on the route. Absent params are
-   * omitted from the matched params record (read as `undefined`). */
-  op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;
   /** Ordered param names for this route (positional) */
@@ -63,6 +60,9 @@ export interface TrieNode {
  * @param routeAncestry - Map of route name to ancestry shortCodes
  * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
  * @param routeTrailingSlash - Optional map of route name to trailing slash mode
+ * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
+ * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
+ * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,
@@ -97,9 +97,49 @@ export function buildRouteTrie(
     });
   }
 
+  sortSuffixParams(root);
   return root;
 }
 
+/**
+ * Sort every node's suffix-param map (`node.xp`) by descending suffix length so
+ * the matcher tries the most specific suffix first. Overlapping suffixes like
+ * `.min.js` and `.js` must resolve by specificity, not route declaration order:
+ * a request for `/app.min.js` should match `:file.min.js`, not `:file.js`.
+ *
+ * This started as a bug — `walkTrie` iterates `node.xp` in object order and
+ * returns the first suffix the segment ends with, so the winner depended on
+ * which route was declared first. Sorting at build time fixes it allocation-free
+ * on the match hot path: the serialized production trie preserves this key order
+ * through JSON.parse, so dev (per-request rebuild) and production match
+ * identically. Array.prototype.sort is stable (ES2019+), so equal-length
+ * suffixes keep their declaration order — the router's existing tiebreak.
+ */
+function sortSuffixParams(node: TrieNode): void {
+  if (node.xp) {
+    const sorted: Record<string, { n: string; c: TrieNode }> = {};
+    for (const suffix of Object.keys(node.xp).sort(
+      (a, b) => b.length - a.length,
+    )) {
+      sorted[suffix] = node.xp[suffix];
+    }
+    node.xp = sorted;
+  }
+  if (node.s) {
+    for (const child of Object.values(node.s)) {
+      sortSuffixParams(child);
+    }
+  }
+  if (node.p) {
+    sortSuffixParams(node.p.c);
+  }
+  if (node.xp) {
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
+  }
+}
+
 /**
  * Build a per-router trie from a generated manifest. This is the single
  * construction path shared by build/discovery (discover-routers.ts, serialized
@@ -155,18 +195,14 @@ function insertRoute(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
+  leaf: Omit<TrieLeaf, "cv" | "pa">,
 ): void {
-  // op (full optional list) and cv (full constraint map) are route-level and
-  // identical on every terminal, so compute them once on the shared base.
-  const optionalParams: string[] = [];
+  // cv (full constraint map) is route-level and identical on every terminal,
+  // so compute it once on the shared base.
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      if (seg.optional) {
-        optionalParams.push(seg.value);
-      }
       if (seg.constraint) {
         constraints[seg.value] = seg.constraint;
       }
@@ -175,7 +211,6 @@ function insertRoute(
 
   const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 

package/src/build/route-types/param-extraction.ts

@@ -37,12 +37,15 @@ export function formatRouteEntry(
 ): string {
   const hasSearch = search && Object.keys(search).length > 0;
 
+  // JSON.stringify the pattern and search values so backslashes and quotes in a
+  // route pattern (e.g. a custom regex constraint) survive interpolation into
+  // both the type-level string and the runtime NamedRoutes value.
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
 
   const searchBody = Object.entries(search!)
-    .map(([k, v]) => `${k}: "${v}"`)
+    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
     .join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }

package/src/build/route-types/router-processing.ts

@@ -617,9 +617,6 @@ export function writeCombinedRouteTypes(
       ? readFileSync(outPath, "utf-8")
       : null;
 
-    // When the static parser can't extract routes (e.g. callback-style urls()),
-    // write an empty placeholder so the build-time transform's injected import
-    // resolves. Runtime discovery will overwrite this with the real routes.
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
@@ -635,11 +632,6 @@ export function writeCombinedRouteTypes(
       hasSearchSchemas ? result.searchSchemas : undefined,
     );
     if (existing !== source) {
-      // On initial dev startup, don't overwrite a file from runtime discovery
-      // (which has all dynamic routes) with a smaller set from the static
-      // parser. The static parser can't see routes generated by Array.from()
-      // or other dynamic code. During HMR (file watcher), always write so
-      // newly added routes appear immediately.
       if (opts?.preserveIfLarger && existing) {
         const existingCount = countPublicRouteEntries(existing);
         const newCount = Object.keys(result.routes).filter(

package/src/cache/cache-policy.ts

@@ -69,24 +69,6 @@ export function computeExpiration(
   return { staleAt, expiresAt };
 }
 
-// ============================================================================
-// Cache Key Resolution
-// ============================================================================
-
-/**
- * Resolve cache key using the 3-tier priority:
- * 1. keyFn (full override from route/loader cache options)
- * 2. store.keyGenerator (modifies default key)
- * 3. defaultKey (used when neither keyFn nor keyGenerator is provided)
- *
- * Errors from keyFn and store.keyGenerator propagate to the caller.
- * Cache identity is correctness-critical: if explicit key logic throws,
- * silently remapping to a different key could cause cache collisions or
- * serve stale/wrong data. Callers must handle the error or let it surface.
- *
- * Uses _getRequestContext (non-throwing) so that calls outside ALS
- * (e.g. build-time) gracefully fall back to defaultKey.
- */
 export async function resolveCacheKey(
   keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
   store: SegmentCacheStore | null,
@@ -95,34 +77,17 @@ export async function resolveCacheKey(
 ): Promise<string> {
   const requestCtx = _getRequestContext();
 
-  // Priority 1: Route/loader-level key function (full override)
   if (keyFn && requestCtx) {
     return await keyFn(requestCtx);
   }
 
-  // Priority 2: Store-level keyGenerator (modifies default key)
   if (store?.keyGenerator && requestCtx) {
     return await store.keyGenerator(requestCtx, defaultKey);
   }
 
-  // Priority 3: Default key (no custom key logic provided)
   return defaultKey;
 }
 
-// ============================================================================
-// Cache Tag Resolution
-// ============================================================================
-
-/**
- * Resolve cache tags from a tags option (static array or function of ctx).
- *
- * Fails open: a thrown tag callback falls back to no tags rather than
- * aborting the request. Tags are additive metadata (not identity), so a
- * missing tag does not cause cache collisions, only a missed invalidation.
- *
- * Shared by the cache() DSL (cache-scope) and loader caching (loader-cache)
- * so tag resolution behaves identically across every cache axis.
- */
 export function resolveTagsOption<TEnv>(
   tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined,
   ctx: RequestContext<TEnv> | undefined,
@@ -131,10 +96,6 @@ export function resolveTagsOption<TEnv>(
   if (!tags) return undefined;
   if (typeof tags === "function") {
     if (!ctx) {
-      // A dynamic tags function needs the request context to run. Without it
-      // (e.g. resolved outside a request, at build/prerender time) the entry is
-      // cached UNTAGGED and can never be invalidated - surface that rather than
-      // silently dropping the tags, matching the thrown-callback branch below.
       console.warn(
         `[${label}] Dynamic tags function present but no request context; ` +
           `caching without tags (this entry will not be tag-invalidatable).`,
@@ -167,25 +128,10 @@ function normalizeTagList(tags: string[]): string[] | undefined {
   return out.length > 0 ? out : undefined;
 }
 
-// ============================================================================
-// Cache Store Resolution
-// ============================================================================
-
-/**
- * Resolve cache store from the 2-tier priority:
- * 1. Explicit store from cache options
- * 2. App-level store from request context
- */
 export function resolveCacheStore(
   explicitStore: SegmentCacheStore | undefined,
 ): SegmentCacheStore | null {
   if (explicitStore) {
-    // Register explicit per-scope stores so updateTag()/revalidateTag() can
-    // reach them. This is the single chokepoint every cache axis (segment,
-    // response, loader) resolves through, so registering here covers them all
-    // eagerly - no dependence on whether a tagged write has happened yet. The
-    // app-level store is intentionally not registered (always reachable via
-    // ctx._cacheStore).
     registerExplicitTaggedStore(explicitStore);
     return explicitStore;
   }

package/src/cache/cache-runtime.ts

@@ -21,6 +21,7 @@ import {
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
 import { getRequestContext } from "../server/request-context.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
   CACHED_FN_SYMBOL,
@@ -46,6 +47,7 @@ import {
   runWithCacheTagScope,
 } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
+import type { CacheItemResult } from "./types.js";
 
 /**
  * Convert encodeReply result to a stable string key.
@@ -58,6 +60,10 @@ async function replyToCacheKey(encoded: string | FormData): Promise<string> {
   return text;
 }
 
+// Cached-fn ids already warned about running uncached under a test runner, so
+// the test-ergonomics warning fires once per fn rather than once per call.
+const warnedUncachedUnderTest = new Set<string>();
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -84,7 +90,28 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // cacheTag() call inside the function degrades to a no-op rather than
     // throwing "must be called inside a use cache function" - adopting cacheTag()
     // must not hard-fail in apps/tests without an item-capable cache configured.
+    // Note: the INSIDE_CACHE_EXEC guard (cookies()/headers()/ctx.set() rejection)
+    // is intentionally NOT stamped here. It is a cached-path-only check; in the
+    // bypass the body actually executes, so the guarded side effects take effect
+    // and nothing is lost on a (non-existent) hit. Same applies to the
+    // non-serializable-args bypass below.
     if (!store?.getItem) {
+      // Test-ergonomics guard: under a test runner, a "use cache" function that
+      // executes with no item-capable store seeded is exercising the UNCACHED
+      // path — a green test that proves nothing about caching. Warn once per fn
+      // id so the author knows to seed a cacheStore. Advisory (never throws), so
+      // a test that DELIBERATELY runs uncached is unaffected. Gated on the test
+      // runner (process.env.VITEST, not folded) so production never evaluates it.
+      if (isUnderTestRunner() && !warnedUncachedUnderTest.has(id)) {
+        warnedUncachedUnderTest.add(id);
+        console.warn(
+          `[rango] "use cache" function "${id}" executed but no cacheStore was ` +
+            `seeded; the cached path is NOT under test (it ran uncached). Pass ` +
+            `{ cacheStore, cacheProfiles } to runLoader/runMiddleware/renderHandler/` +
+            `runInRequestContext (or configure createRouter({ cache }) for dispatch) ` +
+            `to exercise it.`,
+        );
+      }
       const scoped = runWithCacheTagScope(() => fn.apply(this, args));
       const result = await scoped.result;
       // Still record the runtime tags into the request set so a cacheTag() in an
@@ -185,23 +212,29 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Cache lookup
     const cached = await store.getItem(cacheKey);
 
+    // Serve a cached entry on the hit path: deserialize the stored value,
+    // replay handle data (gated on tainted args), and surface the entry's tags
+    // to the request set (the function did not re-run, so its runtime cacheTag()
+    // tags are only available from the stored entry). Shared by the fresh-hit
+    // and stale-hit branches; the only divergence is the stale branch scheduling
+    // background revalidation, which it does after this returns.
+    const serveCached = async (entry: CacheItemResult): Promise<any> => {
+      const result = await deserializeResult(entry.value);
+      if (entry.handles && hasTaintedArgs) {
+        const handleStore = requestCtx?._handleStore;
+        if (handleStore) {
+          const r = await decodeHandles(entry.handles);
+          if (r) restoreHandles(r, handleStore);
+        }
+      }
+      recordRequestTags(entry.tags, requestCtx);
+      return result;
+    };
+
     if (cached && !cached.shouldRevalidate) {
       // Fresh hit: deserialize and return
       try {
-        const result = await deserializeResult(cached.value);
-        // Restore handle data if present
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            const r = await decodeHandles(cached.handles);
-            if (r) restoreHandles(r, handleStore);
-          }
-        }
-        // Surface the hit's tags to the request set so a document built from a
-        // cached item is still tagged (the function did not re-run, so its
-        // runtime cacheTag() tags are only available from the stored entry).
-        recordRequestTags(cached.tags, requestCtx);
-        return result;
+        return await serveCached(cached);
       } catch (error) {
         // The stored value is corrupt/partial (failed RSC deserialize). Report
         // it, then fall through to fresh execution - the miss path below re-runs
@@ -217,16 +250,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     if (cached?.shouldRevalidate) {
       // Stale hit: return stale value, revalidate in background
       try {
-        const result = await deserializeResult(cached.value);
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            const r = await decodeHandles(cached.handles);
-            if (r) restoreHandles(r, handleStore);
-          }
-        }
-        // Tag the request with the stale entry's tags (see fresh-hit note).
-        recordRequestTags(cached.tags, requestCtx);
+        const result = await serveCached(cached);
         // Background revalidation — must capture handles if tainted args present.
         // Use an isolated handle store so background pushes don't pollute the
         // live response or throw LateHandlePushError on the completed store.

package/src/cache/cache-scope.ts

@@ -34,12 +34,6 @@ import {
 } from "./cache-policy.js";
 import type { RequestContext } from "../server/request-context.js";
 
-/**
- * Resolve tags for a cache() boundary from its config (static array or
- * function of ctx). Thin wrapper over the shared resolveTagsOption so the
- * cache() DSL and loader caching resolve tags identically.
- * @internal
- */
 export function resolveCacheTags(
   config: PartialCacheOptions | false,
   ctx: RequestContext | undefined,
@@ -54,17 +48,6 @@ function debugCacheLog(message: string): void {
   }
 }
 
-// ============================================================================
-// Key Generation (internal)
-// ============================================================================
-
-/**
- * Generate cache key base from host, pathname, route params, and search params.
- * Host is included to prevent cross-host cache collisions on shared stores.
- * Route params and search params are sorted alphabetically for deterministic keys.
- * Internal _rsc* and __* query params are excluded.
- * @internal
- */
 function getCacheKeyBase(
   host: string,
   pathname: string,
@@ -80,16 +63,6 @@ function getCacheKeyBase(
   return key;
 }
 
-/**
- * Generate default cache key for a route request.
- * Includes pathname, route params, and user-facing search params for
- * correct scoping. Internal _rsc* params are excluded.
- * Includes request type prefix since they produce different segment sets:
- * - doc: document requests (full page load)
- * - partial: navigation requests (client-side navigation)
- * - intercept: intercept navigation (modal/overlay routes)
- * @internal
- */
 function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,