@rangojs/router 0.0.0-experimental.115 → 0.0.0-experimental.117

package/skills/response-routes/SKILL.md

@@ -68,16 +68,16 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## Available Tags
 
-| Tag      | Usage           | Handler returns    | Auto-wrap                |
-| -------- | --------------- | ------------------ | ------------------------ |
-| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
-| `text`   | `path.text()`   | string             | text/plain Response      |
-| `html`   | `path.html()`   | string             | text/html Response       |
-| `xml`    | `path.xml()`    | string             | application/xml Response |
-| `md`     | `path.md()`     | string             | text/markdown Response   |
-| `image`  | `path.image()`  | Response           | pass-through             |
-| `stream` | `path.stream()` | Response           | pass-through             |
-| `any`    | `path.any()`    | Response           | pass-through             |
+| Tag      | Usage           | Handler returns    | Auto-wrap                     |
+| -------- | --------------- | ------------------ | ----------------------------- |
+| `json`   | `path.json()`   | plain object/array | bare JSON value (no envelope) |
+| `text`   | `path.text()`   | string             | text/plain Response           |
+| `html`   | `path.html()`   | string             | text/html Response            |
+| `xml`    | `path.xml()`    | string             | application/xml Response      |
+| `md`     | `path.md()`     | string             | text/markdown Response        |
+| `image`  | `path.image()`  | Response           | pass-through                  |
+| `stream` | `path.stream()` | Response           | pass-through                  |
+| `any`    | `path.any()`    | Response           | pass-through                  |
 
 ## ResponseHandlerContext
 
@@ -139,22 +139,31 @@ path.json(
 );
 ```
 
-## JSON Envelope
+## JSON Wire Shape
 
-`path.json()` handlers return plain data. The framework auto-wraps it
-in a `ResponseEnvelope<T>` discriminated union:
+`path.json()` handlers return plain data. The framework serializes the handler's
+return value **verbatim** (no envelope) on success, and an RFC 9457 `problem+json`
+body on error. Discriminate with `res.ok` / the HTTP status — there is no in-body
+`data`/`error` union:
 
 ```typescript
-// Success: HTTP 200
-{ "data": { "status": "ok", "timestamp": 1700000000 } }
-
-// Error: HTTP 404 (or whatever status RouterError specifies)
-{ "error": { "message": "Product 999 not found", "code": "NOT_FOUND" } }
+// Success: HTTP 200, content-type application/json
+{ "status": "ok", "timestamp": 1700000000 }
+
+// Error: HTTP 404 (or whatever status RouterError specifies),
+//        content-type application/problem+json
+{
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Product 999 not found",
+  "code": "NOT_FOUND"
+  // "stack": included in development only
+}
 ```
 
 ### Error Handling with RouterError
 
-Throw `RouterError` to return structured error envelopes:
+Throw `RouterError` to return a structured `problem+json` body:
 
 ```typescript
 import { RouterError } from "@rangojs/router";
@@ -199,25 +208,27 @@ path.json(
 
 ## Client-Side Type Safety
 
-### ResponseEnvelope and isResponseError
+### Discriminating success vs. error with res.ok
+
+Success bodies are the bare value; error bodies are RFC 9457 `ProblemDetails`.
+Branch on `res.ok` (or the HTTP status) — not an in-body union:
 
 ```typescript
 "use client";
-import type { ResponseEnvelope, ResponseError } from "@rangojs/router/client";
-import { isResponseError } from "@rangojs/router/client";
+import type { ProblemDetails } from "@rangojs/router";
 
 // Fetch a typed response
 const res = await fetch("/api/products/1");
-const result: ResponseEnvelope<Product> = await res.json();
 
-if (isResponseError(result)) {
-  // result.error: ResponseError  (message, code?, type?)
-  // result.data: undefined
-  console.error(result.error.message);
+if (!res.ok) {
+  // Error body: application/problem+json
+  const problem: ProblemDetails = await res.json();
+  // problem.detail: string, problem.code: string, problem.status: number
+  console.error(problem.code, problem.detail);
 } else {
-  // result.data: Product
-  // result.error: undefined
-  console.log(result.data.name);
+  // Success body: the bare value (no envelope)
+  const product: Product = await res.json();
+  console.log(product.name);
 }
 ```
 
@@ -230,20 +241,23 @@ import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
 type ProductsData = RouteResponse<typeof apiPatterns, "products">;
-// = ResponseEnvelope<{ id: string; name: string; price: number }[]>
+// = { id: string; name: string; price: number }[]
 ```
 
+`RouteResponse` is the bare success payload (the JSON wire shape) — the same value
+a `fetch().then(r => r.json())` yields on a 2xx. Error bodies are `ProblemDetails`,
+keyed off `res.ok` at runtime, not part of this type.
+
 ### Rango.PathResponse (global lookup by URL pattern or concrete path)
 
 `Rango.PathResponse` is ambient (no import) and reads from `RegisteredRoutes`,
 which carries response payload metadata. That surface is **not** auto-wired —
 without the augmentation below, `Rango.PathResponse` falls back to the generated
 path/search map, or to a permissive map when nothing is generated. Either way, it
-has no response payload metadata, so response routes resolve to
-`ResponseEnvelope<never>`:
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
 // router.tsx
@@ -261,11 +275,11 @@ With that in place, look up the response type by URL pattern (ambient, no import
 ```typescript
 // After include("/api", apiPatterns) in main urls
 type Health = Rango.PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
-// RSC routes return ResponseEnvelope<never>
+// RSC routes (no JSON payload) return never
 type Home = Rango.PathResponse<"/">;
-// = ResponseEnvelope<never>
+// = never
 ```
 
 `Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
@@ -280,7 +294,7 @@ async function get<T extends Rango.Path>(
   return fetch(href(path)).then((r) => r.json());
 }
 
-const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
 Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
@@ -288,7 +302,7 @@ route can match several patterns and union their responses.
 
 `Rango.PathResponse` reports the JSON **wire** shape, not the handler's raw
 return: `path.json()` serializes with `JSON.stringify`, so a handler returning
-`{ createdAt: Date }` resolves to `ResponseEnvelope<{ createdAt: string }>`. This
+`{ createdAt: Date }` resolves to the bare `{ createdAt: string }`. This
 runs through the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
 honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). The
 `RouteResponse` surface below applies the same `Rango.JsonSerialize` transform, so
@@ -412,13 +426,13 @@ import type { ParamsFor } from "@rangojs/router/client";
 
 // Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
 // After mounting -- names get prefixed.
 // Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
-// otherwise it resolves to ResponseEnvelope<never>.
+// otherwise it resolves to never.
 type BlogStats = Rango.PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -462,7 +476,11 @@ best-effort basis.
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes auto-wrap return values in `{ data }` / `{ error }` envelope
+4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)
+
+## Consuming response routes
+
+To call your own response-route JSON APIs from first-party TypeScript with a typed client (typed params, typed payloads inferred from the handler, no `.data`, typed `ProblemDetails` errors), see `/api-client` — a copy-paste recipe over `RouteResponse` + `ExtractParams` + a client-safe path builder. External/third-party consumers use the plain wire directly: bare JSON on success, `application/problem+json` on error.

package/skills/typesafety/SKILL.md

@@ -57,7 +57,7 @@ the auto-generated `GeneratedRouteMap`, so **`rango generate` alone gives you
 path-checked `href()`** with no manual augmentation. Response and MIME payload
 inference is the exception: it comes only from `typeof router.routeMap` (via
 `RegisteredRoutes`), because `GeneratedRouteMap` carries paths + search but no
-payloads — so `Rango.PathResponse` resolves to `ResponseEnvelope<never>` until you wire
+payloads — so `Rango.PathResponse` resolves to `never` until you wire
 `RegisteredRoutes`.
 
 Recommended setup:
@@ -237,7 +237,7 @@ async function get<T extends Rango.Path>(
 ): Promise<Rango.PathResponse<T>> {
   return fetch(href(path)).then((r) => r.json());
 }
-const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
 Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
@@ -245,7 +245,7 @@ route can match several patterns and union their responses.
 
 `Rango.PathResponse` describes the JSON **wire** shape, not the handler's raw
 return. A `path.json()` handler returning `{ createdAt: Date }` resolves here to
-`ResponseEnvelope<{ createdAt: string }>`, matching what `r.json()` yields. This
+`{ createdAt: string }` (bare value), matching what `r.json()` yields. This
 is applied via the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
 honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). A separate
 `Rango.FlightSerialize<T>` models the higher-fidelity RSC Flight boundary

package/src/__augment-tests__/augmented.check.ts

@@ -9,7 +9,6 @@ import "./augment.js";
 import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import { href } from "../href-client.js";
-import type { ResponseEnvelope } from "../urls.js";
 import type { Money, TestBindings } from "./augment.js";
 
 type Expect<T extends true> = T;
@@ -79,13 +78,13 @@ wrappedHref("/not-a-route");
 type _orderWireByPattern = Expect<
   Equal<
     Rango.PathResponse<"/orders/:id">,
-    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+    { id: string; total: number; placedAt: string }
   >
 >;
 type _orderWireByPath = Expect<
   Equal<
     Rango.PathResponse<"/orders/42">,
-    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+    { id: string; total: number; placedAt: string }
   >
 >;
 

package/src/browser/navigation-client.ts

@@ -23,6 +23,7 @@ import {
   buildSourceKey,
   consumeInflightPrefetch,
   consumePrefetch,
+  type DecodedPrefetch,
 } from "./prefetch/cache.js";
 
 /**
@@ -111,26 +112,26 @@ export function createNavigationClient(
       const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
       const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
 
-      let cachedResponse: Response | null = null;
+      let cachedEntry: DecodedPrefetch | null = null;
       let hitKey: string | null = null;
       if (canUsePrefetch) {
-        cachedResponse = consumePrefetch(cacheKey);
-        if (cachedResponse) {
+        cachedEntry = consumePrefetch(cacheKey);
+        if (cachedEntry) {
           hitKey = cacheKey;
         } else {
-          cachedResponse = consumePrefetch(wildcardKey);
-          if (cachedResponse) hitKey = wildcardKey;
+          cachedEntry = consumePrefetch(wildcardKey);
+          if (cachedEntry) hitKey = wildcardKey;
         }
       }
 
-      let inflightResponsePromise: Promise<Response | null> | null = null;
-      if (canUsePrefetch && !cachedResponse) {
-        inflightResponsePromise = consumeInflightPrefetch(cacheKey);
-        if (inflightResponsePromise) {
+      let inflightEntryPromise: Promise<DecodedPrefetch | null> | null = null;
+      if (canUsePrefetch && !cachedEntry) {
+        inflightEntryPromise = consumeInflightPrefetch(cacheKey);
+        if (inflightEntryPromise) {
           hitKey = cacheKey;
         } else {
-          inflightResponsePromise = consumeInflightPrefetch(wildcardKey);
-          if (inflightResponsePromise) hitKey = wildcardKey;
+          inflightEntryPromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightEntryPromise) hitKey = wildcardKey;
         }
       }
       // Track when the stream completes
@@ -217,29 +218,32 @@ export function createNavigationClient(
         });
       };
 
-      let responsePromise: Promise<Response>;
+      // A warm prefetch hit returns its eagerly-decoded payload directly: the
+      // route's chunks were imported during the prefetch, so this click runs
+      // no decode and no network. Only the fresh path runs createFromFetch and
+      // resolves the local streamComplete (via doFreshFetch's teeWithCompletion
+      // and the control-header short-circuits in validateRscHeaders).
+      const freshResult = (): {
+        payload: Promise<RscPayload>;
+        streamComplete: Promise<void>;
+      } => ({
+        payload: deps.createFromFetch<RscPayload>(doFreshFetch()),
+        streamComplete,
+      });
+
+      let payloadPromise: Promise<RscPayload>;
+      let streamCompletePromise: Promise<void>;
 
-      if (cachedResponse) {
+      if (cachedEntry) {
         if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", {
+          browserDebugLog(tx, "prefetch cache hit (warm)", {
             key: hitKey,
             wildcard: hitKey === wildcardKey,
           });
         }
-        responsePromise = Promise.resolve(cachedResponse).then((response) => {
-          const validated = validateRscHeaders(response, "prefetch cache");
-          if (validated instanceof Promise) return validated;
-
-          return teeWithCompletion(
-            validated,
-            () => {
-              if (tx) browserDebugLog(tx, "stream complete (from cache)");
-              resolveStreamComplete();
-            },
-            signal,
-          );
-        });
-      } else if (inflightResponsePromise) {
+        payloadPromise = cachedEntry.payload;
+        streamCompletePromise = cachedEntry.streamComplete;
+      } else if (inflightEntryPromise) {
         if (tx) {
           browserDebugLog(tx, "reusing inflight prefetch", {
             key: hitKey,
@@ -247,51 +251,35 @@ export function createNavigationClient(
           });
         }
         const adoptedViaWildcard = hitKey === wildcardKey;
-        responsePromise = inflightResponsePromise.then(async (response) => {
-          if (!response) {
-            if (tx) {
-              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
-            }
-            return doFreshFetch();
+        const entry = await inflightEntryPromise;
+        if (!entry) {
+          if (tx) {
+            browserDebugLog(tx, "inflight prefetch unavailable, refetching");
           }
-
-          // Cross-source safety: an inflight promise adopted via the
-          // wildcard key may turn out to be source-scoped (server emitted
-          // `X-RSC-Prefetch-Scope: source`), which means it was built for
-          // a different source page. Discard and refetch.
-          if (
-            adoptedViaWildcard &&
-            response.headers.get("x-rsc-prefetch-scope") === "source"
-          ) {
-            if (tx) {
-              browserDebugLog(
-                tx,
-                "wildcard inflight turned out source-scoped, refetching",
-              );
-            }
-            return doFreshFetch();
+          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+            freshResult());
+        } else if (adoptedViaWildcard && entry.scope === "source") {
+          // A wildcard-adopted inflight that turned out source-scoped was
+          // built for a different source page. Discard and refetch.
+          if (tx) {
+            browserDebugLog(
+              tx,
+              "wildcard inflight turned out source-scoped, refetching",
+            );
           }
-
-          const validated = validateRscHeaders(response, "inflight prefetch");
-          if (validated instanceof Promise) return validated;
-
-          return teeWithCompletion(
-            validated,
-            () => {
-              if (tx) {
-                browserDebugLog(tx, "stream complete (from inflight prefetch)");
-              }
-              resolveStreamComplete();
-            },
-            signal,
-          );
-        });
+          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+            freshResult());
+        } else {
+          payloadPromise = entry.payload;
+          streamCompletePromise = entry.streamComplete;
+        }
       } else {
-        responsePromise = doFreshFetch();
+        ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+          freshResult());
       }
 
       try {
-        const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+        const payload = await payloadPromise;
 
         if (tx) {
           browserDebugLog(tx, "response received", {
@@ -300,7 +288,7 @@ export function createNavigationClient(
             diffCount: payload.metadata?.diff?.length ?? 0,
           });
         }
-        return { payload, streamComplete };
+        return { payload, streamComplete: streamCompletePromise };
       } catch (error) {
         // Convert network-level errors to NetworkError for proper handling
         if (isNetworkError(error)) {

package/src/browser/prefetch/cache.ts

@@ -1,8 +1,13 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetched Response objects for instant cache hits
- * on subsequent navigation. Two key scopes are in play:
+ * In-memory cache storing eagerly-decoded prefetch payloads for instant,
+ * already-warm cache hits on subsequent navigation. A prefetch fetches the
+ * RSC partial AND decodes it (createFromFetch) up front — decoding the Flight
+ * stream resolves the route's client references, so the route's JS chunks are
+ * imported during prefetch rather than on click. The decoded payload is reused
+ * verbatim by navigation, so a prefetched click loads no new code. Two key
+ * scopes are in play:
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
  *   invalidated automatically when Rango state bumps (deploy or
@@ -17,8 +22,8 @@
  *   from other pages.
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
- * navigation branch of a tee'd Response, allowing navigation to adopt a
- * still-downloading prefetch without reparsing or buffering the body. A
+ * decoded prefetch entry (or null), letting navigation adopt a
+ * still-downloading prefetch without issuing a duplicate request. A
  * single promise can be registered under multiple alias keys (see
  * `setInflightPromiseWithAliases`) so same-source navigations adopt via
  * their source key while cross-source ones fall through to the wildcard
@@ -30,6 +35,31 @@
 
 import { abortAllPrefetches } from "./queue.js";
 import { invalidateRangoState } from "../rango-state.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
+ * payload (not the raw Response) is what makes a prefetched navigation "warm":
+ * decoding the Flight stream during prefetch pulls the route's client chunks,
+ * so the click reuses ready elements and loads no new JS.
+ */
+export interface DecodedPrefetch {
+  /** The eagerly-decoded RSC payload. Reused verbatim by navigation. */
+  payload: Promise<RscPayload>;
+  /**
+   * Resolves when the underlying RSC stream finishes draining. Navigation
+   * forwards this as its streamComplete so scroll/revalidation gating is
+   * unchanged from the fresh-fetch path.
+   */
+  streamComplete: Promise<void>;
+  /**
+   * Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
+   * `"source"` means the response is source-page-sensitive and must not be
+   * reused by a navigation from a different page — navigation enforces this
+   * when it adopted an inflight entry through the wildcard key.
+   */
+  scope: "source" | "wildcard";
+}
 
 // Default TTL: 5 minutes. Overridden by initPrefetchCache() with
 // the server-configured prefetchCacheTTL from router options.
@@ -55,7 +85,7 @@ export function isPrefetchCacheDisabled(): boolean {
 const MAX_PREFETCH_CACHE_SIZE = 50;
 
 interface PrefetchCacheEntry {
-  response: Response;
+  entry: DecodedPrefetch;
   timestamp: number;
 }
 
@@ -63,17 +93,19 @@ const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
 /**
- * In-flight promise map. When a prefetch fetch is in progress, its
- * Promise<Response | null> is stored here so navigation can await
- * it instead of starting a duplicate request.
+ * In-flight promise map. When a prefetch fetch+decode is in progress, its
+ * Promise<DecodedPrefetch | null> is stored here so navigation can await it
+ * instead of starting a duplicate request. Resolves to null when the prefetch
+ * failed, was aborted, or carried a control header (reload/redirect) that the
+ * navigation must re-fetch to act on.
  */
-const inflightPromises = new Map<string, Promise<Response | null>>();
+const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
 
 /**
  * Alias map for in-flight promises registered under multiple keys (see
  * dual inflight in prefetch/fetch.ts). Records each key's sibling set so
  * that consuming or clearing any one key atomically removes every alias —
- * guaranteeing a single consumer for the shared Response stream.
+ * guaranteeing a single consumer for the shared decode.
  */
 const inflightAliases = new Map<string, string[]>();
 
@@ -152,14 +184,14 @@ export function hasPrefetch(key: string): boolean {
 }
 
 /**
- * Consume a cached prefetch response. Returns null if not found or expired.
- * One-time consumption: the entry is deleted after retrieval.
+ * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
+ * expired. One-time consumption: the entry is deleted after retrieval.
  * Returns null when caching is disabled (TTL <= 0).
  *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
- * for that (returns a Promise instead of a Response).
+ * for that (returns a Promise instead of a resolved entry).
  */
-export function consumePrefetch(key: string): Response | null {
+export function consumePrefetch(key: string): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
   const entry = cache.get(key);
   if (!entry) return null;
@@ -168,13 +200,14 @@ export function consumePrefetch(key: string): Response | null {
     return null;
   }
   cache.delete(key);
-  return entry.response;
+  return entry.entry;
 }
 
 /**
  * Consume an in-flight prefetch promise. Returns null if no prefetch is
- * in-flight for this key. The returned Promise resolves to the buffered
- * Response (or null if the fetch failed/was aborted).
+ * in-flight for this key. The returned Promise resolves to the decoded
+ * prefetch entry (or null if the fetch failed/was aborted, or carried a
+ * control header the navigation must re-fetch to honor).
  *
  * One-time consumption: the promise entry is removed (along with any
  * sibling aliases registered via `setInflightPromiseWithAliases`) so a
@@ -188,7 +221,7 @@ export function consumePrefetch(key: string): Response | null {
  */
 export function consumeInflightPrefetch(
   key: string,
-): Promise<Response | null> | null {
+): Promise<DecodedPrefetch | null> | null {
   const promise = inflightPromises.get(key);
   if (!promise) return null;
   // Remove the promise under every alias so a second consumer cannot
@@ -201,16 +234,14 @@ export function consumeInflightPrefetch(
 }
 
 /**
- * Store a prefetch response in the in-memory cache.
- * The response should be a clone() of the original so the caller can
- * still consume the body. The clone's body streams independently.
+ * Store an eagerly-decoded prefetch in the in-memory cache.
  *
  * Skips storage if the generation has changed since the fetch started
  * (a server action invalidated the cache mid-flight).
  */
 export function storePrefetch(
   key: string,
-  response: Response,
+  entry: DecodedPrefetch,
   fetchGeneration: number,
 ): void {
   if (cacheTTL <= 0) return;
@@ -218,8 +249,8 @@ export function storePrefetch(
 
   // Evict expired entries
   const now = Date.now();
-  for (const [k, entry] of cache) {
-    if (now - entry.timestamp > cacheTTL) {
+  for (const [k, cached] of cache) {
+    if (now - cached.timestamp > cacheTTL) {
       cache.delete(k);
     }
   }
@@ -230,7 +261,7 @@ export function storePrefetch(
     if (oldest) cache.delete(oldest);
   }
 
-  cache.set(key, { response, timestamp: now });
+  cache.set(key, { entry, timestamp: now });
 }
 
 /**
@@ -250,7 +281,7 @@ export function markPrefetchInflight(key: string): void {
  */
 export function setInflightPromise(
   key: string,
-  promise: Promise<Response | null>,
+  promise: Promise<DecodedPrefetch | null>,
 ): void {
   inflightPromises.set(key, promise);
 }
@@ -263,7 +294,7 @@ export function setInflightPromise(
  */
 export function setInflightPromiseWithAliases(
   keys: string[],
-  promise: Promise<Response | null>,
+  promise: Promise<DecodedPrefetch | null>,
 ): void {
   for (const k of keys) {
     inflightPromises.set(k, promise);