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

package/dist/vite/index.js

@@ -2130,7 +2130,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.116",
+  version: "0.0.0-experimental.117",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.116",
+  "version": "0.0.0-experimental.117",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -132,6 +132,16 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.26",
@@ -142,17 +152,17 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
     "jiti": "^2.6.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0",
-    "@shared/e2e": "0.0.1"
+    "vitest": "^4.0.0"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.38.0",
@@ -168,14 +178,5 @@
     "vite": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
   }
-}
+}

package/skills/loader/SKILL.md

@@ -160,23 +160,23 @@ Loaders receive the same context shape as route handlers.
 
 ### Full field surface
 
-| Field          | Type                           | Notes                                                                                               |
-| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
-| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                 |
-| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                        |
-| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                 |
-| `url`          | `URL`                          | Parsed request URL.                                                                                 |
-| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                     |
-| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                |
-| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                   |
-| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                 |
-| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                     |
-| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`). |
-| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for non-loader segments before reading handle data.      |
-| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.               |
-| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                      |
-| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                     |
-| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).              |
+| Field          | Type                           | Notes                                                                                                                                                   |
+| -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                                                                     |
+| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                                                                            |
+| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                                                                     |
+| `url`          | `URL`                          | Parsed request URL.                                                                                                                                     |
+| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                                                                         |
+| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                                                                    |
+| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                                                                       |
+| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                     |
+| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                                                                         |
+| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`).                                                     |
+| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for all non-loader segments (including `loading()` streaming handlers) to settle before reading handle data. |
+| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.                                                                   |
+| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                                                                          |
+| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                                                                         |
+| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                  |
 
 ### Example
 

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);

package/src/browser/prefetch/fetch.ts

@@ -3,12 +3,16 @@
  *
  * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
  * and useRouter().prefetch(). Sends the same headers and segment IDs as a
- * real navigation so the server returns a proper diff. The Response is fully
- * buffered and stored in an in-memory cache for instant consumption on
- * subsequent navigation.
+ * real navigation so the server returns a proper diff. The response is fetched
+ * AND eagerly decoded (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 stored in an
+ * in-memory cache and reused verbatim by navigation, so a prefetched click
+ * loads no new code.
  *
  * In-flight promises are tracked in the cache so that navigation can reuse
- * a prefetch that is still downloading instead of starting a duplicate request.
+ * a prefetch that is still downloading/decoding instead of starting a
+ * duplicate request.
  */
 
 import {
@@ -20,11 +24,34 @@ import {
   storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
+  type DecodedPrefetch,
 } from "./cache.js";
 import { getRangoState } from "../rango-state.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
 import { debugLog } from "../logging.js";
+import { teeWithCompletion } from "../response-adapter.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * Decoder injected at app startup (see setPrefetchDecoder). This is
+ * `deps.createFromFetch` — decoupled from the RSC runtime exactly like the
+ * navigation client. Prefetch decodes through it so the route's client chunks
+ * are pulled during the prefetch, not on click.
+ */
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+
+let decoder: PrefetchDecoder | null = null;
+
+/**
+ * Wire the RSC decoder used to eagerly decode prefetched responses. Called
+ * once from initBrowserApp with the same createFromFetch the navigation client
+ * uses. Until set, prefetch warming is inert (prefetches are skipped) — the
+ * browser app always sets it before any Link can fire.
+ */
+export function setPrefetchDecoder(fn: PrefetchDecoder): void {
+  decoder = fn;
+}
 
 /**
  * Check if a URL resolves to the current page (same pathname + search).
@@ -78,24 +105,34 @@ function buildPrefetchUrl(
 }
 
 /**
- * Core prefetch fetch logic. Fetches the response, tees the body, and stores
- * one branch in the in-memory cache. The returned Promise resolves to the
- * sibling navigation branch (or null on failure) so navigation can safely
- * reuse an in-flight prefetch via consumeInflightPrefetch().
+ * Core prefetch fetch logic. Fetches the response, eagerly decodes it, and
+ * stores the decoded payload in the in-memory cache. The returned Promise
+ * resolves to the decoded entry (or null on failure / control header) so
+ * navigation can safely reuse an in-flight prefetch via
+ * consumeInflightPrefetch().
+ *
+ * Eager decode is the warming step: createFromFetch parses the Flight stream,
+ * which resolves the route's client references and imports its JS chunks. The
+ * stored payload is reused as-is by navigation, so the click loads no new code.
+ *
+ * Control headers are NOT acted on here. A speculative prefetch must never
+ * reload the page or throw a redirect — if the response carries X-RSC-Reload
+ * or X-RSC-Redirect, we drop it (resolve null) and let the real navigation
+ * re-fetch and honor it.
  *
  * Inflight + storage key selection:
  *
  * - `forceSourceScope` (Link opted in with `prefetchKey=":source"`): single
- *   inflight registration under `sourceKey`; response stored under
- *   `sourceKey`. No wildcard leak is possible.
+ *   inflight registration under `sourceKey`; entry stored under `sourceKey`.
+ *   No wildcard leak is possible.
  *
  * - Otherwise: dual inflight registration under both `wildcardKey` and
  *   `sourceKey` so same-source navigations adopt directly via their own
  *   source key. Storage key is chosen at response time from the
  *   `X-RSC-Prefetch-Scope` header — `"source"` → `sourceKey` (intercept
- *   modals etc.), anything else → `wildcardKey`. Cross-source navigations
- *   that adopted via `wildcardKey` must bail out in `navigation-client.ts`
- *   if the adopted response turns out to be source-scoped.
+ *   modals etc.), anything else → `wildcardKey`. The entry records its scope
+ *   so cross-source navigations that adopted via `wildcardKey` can bail out
+ *   in `navigation-client.ts` when the adopted entry turns out source-scoped.
  */
 function executePrefetchFetch(
   wildcardKey: string,
@@ -103,14 +140,14 @@ function executePrefetchFetch(
   fetchUrl: string,
   forceSourceScope: boolean,
   signal?: AbortSignal,
-): Promise<Response | null> {
+): Promise<DecodedPrefetch | null> {
   const gen = currentGeneration();
   const inflightKeys = forceSourceScope
     ? [sourceKey]
     : [wildcardKey, sourceKey];
   for (const k of inflightKeys) markPrefetchInflight(k);
 
-  const promise: Promise<Response | null> = fetch(fetchUrl, {
+  const promise: Promise<DecodedPrefetch | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
     signal,
     headers: {
@@ -120,25 +157,47 @@ function executePrefetchFetch(
     },
   })
     .then((response) => {
-      if (!response.ok) return null;
-      // Don't buffer with arrayBuffer() — that blocks until the entire
-      // body downloads, defeating streaming for slow loaders.
-      // Tee the body: one branch for navigation, one for cache storage.
-      const [navStream, cacheStream] = response.body!.tee();
-      const responseInit = {
-        headers: response.headers,
-        status: response.status,
-        statusText: response.statusText,
-      };
-      let storageKey: string;
-      if (forceSourceScope) {
-        storageKey = sourceKey;
-      } else {
-        const scope = response.headers.get("x-rsc-prefetch-scope");
-        storageKey = scope === "source" ? sourceKey : wildcardKey;
+      if (!response.ok || !decoder) return null;
+      // Control headers mean this response is stale (reload) or redirecting.
+      // Don't warm it — drop so navigation re-fetches and acts on the header.
+      if (
+        response.headers.has("X-RSC-Reload") ||
+        response.headers.has("X-RSC-Redirect")
+      ) {
+        return null;
       }
-      storePrefetch(storageKey, new Response(cacheStream, responseInit), gen);
-      return new Response(navStream, responseInit);
+
+      const scope: "source" | "wildcard" =
+        forceSourceScope ||
+        response.headers.get("x-rsc-prefetch-scope") === "source"
+          ? "source"
+          : "wildcard";
+      const storageKey = scope === "source" ? sourceKey : wildcardKey;
+
+      // Track stream completion off a tee so navigation's scroll/revalidation
+      // gating matches the fresh-fetch path; decode the other branch.
+      let resolveStreamComplete!: () => void;
+      const streamComplete = new Promise<void>((resolve) => {
+        resolveStreamComplete = resolve;
+      });
+      const tracked = teeWithCompletion(
+        response,
+        () => resolveStreamComplete(),
+        signal,
+        // Speculative prefetch: a never-consumed/aborted stream error is benign.
+        true,
+      );
+
+      // Eager decode: parsing the Flight stream imports the route's client
+      // chunks now, not on click.
+      const payload = decoder(Promise.resolve(tracked));
+      // Mark handled so an unconsumed prefetch decode error stays quiet; the
+      // error is still surfaced to navigation if it consumes the entry.
+      payload.catch(() => {});
+
+      const entry: DecodedPrefetch = { payload, streamComplete, scope };
+      storePrefetch(storageKey, entry, gen);
+      return entry;
     })
     .catch(() => null)
     .finally(() => {

package/src/browser/response-adapter.ts

@@ -56,11 +56,17 @@ export function handleReloadHeader(
  *
  * If the response has no body, onComplete fires synchronously.
  * If signal is provided, an abort cancels the tracking reader.
+ *
+ * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
+ * low-priority prefetch that is aborted or never consumed can error its stream
+ * benignly, which is not worth surfacing. The fresh-navigation path keeps the
+ * log (default), where a stream error reflects a real failed navigation.
  */
 export function teeWithCompletion(
   response: Response,
   onComplete: () => void,
   signal?: AbortSignal,
+  silent = false,
 ): Response {
   if (!response.body) {
     onComplete();
@@ -84,7 +90,7 @@ export function teeWithCompletion(
       onComplete();
     }
   })().catch((error) => {
-    if (!signal?.aborted) {
+    if (!silent && !signal?.aborted) {
       console.error("[Browser] Error reading tracking stream:", error);
     }
     onComplete();

package/src/browser/rsc-router.tsx

@@ -23,6 +23,7 @@ import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import { setPrefetchDecoder } from "./prefetch/fetch.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -238,6 +239,10 @@ export async function initBrowserApp(
     initPrefetchCache(prefetchCacheTTL);
   }
 
+  // Wire the RSC decoder so prefetches decode eagerly and warm the route's
+  // client chunks (same createFromFetch the navigation client uses).
+  setPrefetchDecoder((response) => deps.createFromFetch<RscPayload>(response));
+
   // Create a bound renderSegments that reads rootLayout through the shell
   // ref. On app switch the ref is updated before the tree re-renders, so
   // the new app's Document (rootLayout) replaces the previous one.

package/src/router/lazy-includes.ts

@@ -119,7 +119,7 @@ export function evaluateLazyEntry<TEnv = any>(
   const lazyContext = entry.lazyContext;
 
   // Create a new context for evaluating the lazy patterns.
-  // KNOWN REDUNDANCY (LP3, docs/internal/matching-stability-review.md): this
+  // KNOWN REDUNDANCY (LP3, docs/internal/matching-and-lazy-discovery.md): this
   // runs lazyPatterns.handler() purely to extract `patterns` (route name ->
   // pattern) for matching, and DISCARDS the EntryData `manifest` it builds.
   // loadManifest() then runs the SAME handler again on the first request to

package/src/router/loader-resolution.ts

@@ -27,6 +27,8 @@ import { _getRequestContext } from "../server/request-context.js";
 import {
   isInsideLoaderScope,
   runInsideLoaderBodyScope,
+  isInsidePushCallbackScope,
+  runInsidePushCallbackScope,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
@@ -290,6 +292,12 @@ function createLoaderExecutor<TEnv>(
             );
           }
           const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
+          // The complete snapshot is cached at barrier resolution for
+          // non-streaming trees, and by rendered() after handleStore.settled for
+          // streaming trees (where the eager snapshot would have been incomplete
+          // because loading() handlers were still in flight). Either way it is
+          // present by the time a loader reads a handle; the fresh build is only
+          // a defensive fallback.
           const snapshot =
             reqCtx._renderBarrierHandleSnapshot ??
             buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
@@ -311,15 +319,7 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
-        // Guard: reject streaming trees
         const reqCtx = reqCtxRef ?? _getRequestContext();
-        if (reqCtx?._treeHasStreaming) {
-          throw new Error(
-            `ctx.rendered() is not supported when the matched route tree uses loading(). ` +
-              `Streaming handlers may not have settled when rendered() resolves. ` +
-              `Remove loading() from the route tree or restructure to avoid rendered().`,
-          );
-        }
 
         if (renderedPromise) return renderedPromise;
 
@@ -330,7 +330,10 @@ function createLoaderExecutor<TEnv>(
         }
 
         // Bidirectional deadlock check: if a handler already started
-        // awaiting this loader, calling rendered() would deadlock.
+        // awaiting this loader, calling rendered() would deadlock. This is the
+        // real cycle guard (it holds for both streaming and non-streaming): the
+        // handler blocks segment resolution, which blocks the barrier, which
+        // blocks this loader.
         if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
           throw new Error(
             `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
@@ -348,7 +351,29 @@ function createLoaderExecutor<TEnv>(
         }
         reqCtx._renderBarrierWaiters.add(currentLoaderId);
 
-        renderedPromise = reqCtx._renderBarrier.then(() => {
+        // Streaming trees (loading()): the barrier resolves once the segment
+        // tree is resolved, but loading() handlers stream behind Suspense and
+        // their handle pushes are still in flight then. Their async execution
+        // IS tracked in the handle store (trackHandler -> store.track), so after
+        // the barrier we seal (no further handlers register once the tree is
+        // resolved) and wait for settled — every tracked handler, streaming
+        // included, has finished pushing. The loader's own segment streams in
+        // after, so this does not block the shell; the deadlock guard above
+        // keeps a handler from depending on this loader.
+        const streaming = reqCtx._treeHasStreaming === true;
+        renderedPromise = reqCtx._renderBarrier.then(async () => {
+          if (streaming) {
+            reqCtx._handleStore.seal();
+            await reqCtx._handleStore.settled;
+            // The eager snapshot was intentionally left unbuilt for streaming
+            // (it would have been incomplete). Build the complete one once, now
+            // that the store has settled, so every ctx.use(handle) reads the
+            // cached snapshot instead of rebuilding it per call.
+            reqCtx._renderBarrierHandleSnapshot ??= buildHandleSnapshot(
+              reqCtx._handleStore,
+              reqCtx._renderBarrierSegmentOrder ?? [],
+            );
+          }
           renderedResolved = true;
         });
         return renderedPromise;
@@ -404,12 +429,6 @@ export function setupLoaderAccess<TEnv>(
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
-  // Track whether we're inside a handle push callback. Loaders started
-  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
-  // block segment resolution, so they must not be registered as handler
-  // dependencies for deadlock detection.
-  let insideHandlePush = false;
-
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -430,15 +449,17 @@ export function setupLoaderAccess<TEnv>(
         if (!store) return;
 
         if (typeof dataOrFn === "function") {
-          // Mark scope so ctx.use(loader) calls inside the callback
-          // are not registered as handler-to-loader deps.
-          insideHandlePush = true;
-          try {
-            const result = (dataOrFn as () => Promise<unknown>)();
-            store.push(handle.$$id, segmentId, result);
-          } finally {
-            insideHandlePush = false;
-          }
+          // Run the callback inside the push-callback scope so ctx.use(loader)
+          // calls it makes — including after its own awaits, for an async
+          // callback — are not registered as handler-to-loader deps and do not
+          // trip the deadlock guard. A pushed promise value is not tracked by
+          // handleStore.settled and does not block segment resolution, so it
+          // cannot form a rendered() deadlock. The ALS scope (not a plain
+          // boolean) is what survives the callback's awaits.
+          const result = runInsidePushCallbackScope(() =>
+            (dataOrFn as () => Promise<unknown>)(),
+          );
+          store.push(handle.$$id, segmentId, result);
           return;
         }
 
@@ -450,9 +471,12 @@ export function setupLoaderAccess<TEnv>(
     // Skip when inside a DSL loader scope (resolveLoaderData also calls
     // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
     // inside a handle push callback (push callbacks don't block segment
-    // resolution so they can't cause rendered() deadlocks).
+    // resolution so they can't cause rendered() deadlocks). The push-callback
+    // check is an ALS scope so it also exempts an ASYNC callback's continuation
+    // after its first await — relevant on streaming trees, where the guard
+    // state now stays live until handleStore.settled.
     const loader = item as LoaderDefinition<any, any>;
-    if (!isInsideLoaderScope() && !insideHandlePush) {
+    if (!isInsideLoaderScope() && !isInsidePushCallbackScope()) {
       const reqCtx = reqCtxRef ?? _getRequestContext();
       if (reqCtx) {
         // Direction 1: handler awaits loader that already called rendered()
@@ -466,13 +490,18 @@ export function setupLoaderAccess<TEnv>(
               `Move the data dependency to a loader-to-loader pattern instead.`,
           );
         }
-        // Direction 2: track dep so rendered() can detect the deadlock
-        // if the loader calls it later. Skip when the barrier has already
-        // resolved — no deadlock is possible (rendered() resolves immediately).
-        // _renderBarrierSegmentOrder is undefined before resolution, string[]
-        // after. This also prevents false positives from handle push callbacks
-        // that resume after their first await (post-barrier-resolution).
-        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+        // Direction 2: track dep so rendered() can detect the deadlock if the
+        // loader calls it later. Skip once the guard window is CLOSED — for a
+        // non-streaming tree that is when the barrier resolves (rendered()
+        // resolves immediately), and for a streaming tree it is when
+        // handleStore.settled completes (rendered() keeps waiting until then, so
+        // a loading() handler resuming after the barrier can still form a
+        // cycle). Using the explicit guard-closed flag rather than
+        // _renderBarrierSegmentOrder keeps tracking live across the streaming
+        // settle wait. (Handle push callbacks are already excluded above via
+        // isInsidePushCallbackScope(), so they cannot produce false positives
+        // here.)
+        if (!reqCtx._renderBarrierGuardClosed) {
           if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
           reqCtx._handlerLoaderDeps.add(loader.$$id);
         }

package/src/router/manifest.ts

@@ -32,7 +32,7 @@ import { VERSION } from "@rangojs/router:version";
 // own pruned manifest, so alternating sibling requests would thrash (re-run the
 // handler every time). Running the include handler once per isolate instead of once
 // per route is possible but needs an unpruned manifest cache with prune-on-read — see
-// LP1 in docs/internal/matching-stability-review.md. VERSION comes from the
+// LP1 in docs/internal/matching-and-lazy-discovery.md. VERSION comes from the
 // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();

package/src/server/context.ts

@@ -805,3 +805,35 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
 export function runInsideLoaderBodyScope<T>(fn: () => T): T {
   return loaderBodyScopeALS.run({ active: true }, fn);
 }
+
+// Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).
+// A push callback's value is stored as-is; if it is a promise it is NOT tracked
+// by handleStore.settled and does not block segment resolution, so a
+// ctx.use(loader) made from inside such a callback can never form a rendered()
+// deadlock. This is an ALS (not a plain boolean) so the exemption survives the
+// callback's own awaits — an async push callback that resumes after `await`
+// still reads as "inside a push callback" and stays out of the deadlock guard.
+const PUSH_CALLBACK_SCOPE_KEY = Symbol.for(
+  "rangojs-router:push-callback-scope",
+);
+const pushCallbackScopeALS: AsyncLocalStorage<{ active: true }> = ((
+  globalThis as any
+)[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+
+/**
+ * Check if the current execution is inside a handle push callback (sync or an
+ * async callback's continuation). Used by the handler-to-loader deadlock guard
+ * to exempt push-callback continuations.
+ */
+export function isInsidePushCallbackScope(): boolean {
+  return pushCallbackScopeALS.getStore()?.active === true;
+}
+
+/**
+ * Run `fn` inside a push-callback scope. Wraps the invocation of a handle push
+ * callback so that any ctx.use(loader) it makes — including after one of its own
+ * awaits — is exempt from the deadlock guard.
+ */
+export function runInsidePushCallbackScope<T>(fn: () => T): T {
+  return pushCallbackScopeALS.run({ active: true }, fn);
+}

package/src/server/request-context.ts

@@ -273,7 +273,9 @@ export interface RequestContext<
 
   /**
    * @internal Set to true when the matched entry tree contains any `loading()`
-   * entries (streaming). Used by rendered() to fail fast.
+   * entries (streaming). On a streaming tree rendered() waits for the streaming
+   * handlers to settle (via handleStore.settled) before resolving, and the
+   * deadlock guard state is kept live until that wait completes.
    */
   _treeHasStreaming?: boolean;
 
@@ -297,6 +299,18 @@ export interface RequestContext<
    */
   _renderBarrierHandleSnapshot?: HandleData;
 
+  /**
+   * @internal The deadlock guard window is closed (no further handler-awaits-
+   * loader cycle is possible). For non-streaming trees this is set when the
+   * barrier resolves. For streaming trees the window stays open until
+   * handleStore.settled — rendered() keeps waiting past the barrier and a
+   * loading() handler can still resume and await a still-waiting loader — so it
+   * is set only after settled. The guard (loader-resolution `setupLoaderAccess`)
+   * reads this instead of `_renderBarrierSegmentOrder` so it does not go blind
+   * during the streaming settle wait.
+   */
+  _renderBarrierGuardClosed?: boolean;
+
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -355,6 +369,7 @@ export type PublicRequestContext<
   | "_renderBarrierWaiters"
   | "_handlerLoaderDeps"
   | "_renderBarrierHandleSnapshot"
+  | "_renderBarrierGuardClosed"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
@@ -797,14 +812,37 @@ export function createRequestContext<TEnv>(
       .filter((s) => s.type !== "loader")
       .map((s) => s.id);
     ctx._renderBarrierSegmentOrder = segOrder;
-    // Build and cache handle snapshot so loader ctx.use(handle) calls
-    // don't rebuild it on every invocation.
-    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
-      handleStore,
-      segOrder,
-    );
-    ctx._renderBarrierWaiters = undefined;
-    ctx._handlerLoaderDeps = undefined;
+
+    // Closing the guard window means no handler can still form a deadlock cycle
+    // with a rendered() loader: drop the dependency-tracking state and mark it
+    // closed. WHEN this runs is the only streaming/non-streaming difference.
+    const closeGuard = () => {
+      ctx._renderBarrierWaiters = undefined;
+      ctx._handlerLoaderDeps = undefined;
+      ctx._renderBarrierGuardClosed = true;
+    };
+
+    if (ctx._treeHasStreaming) {
+      // Streaming: rendered() keeps waiting on handleStore.settled past this
+      // point, and loading() handlers are still in flight. The eager snapshot
+      // here would be incomplete, so leave it unset — rendered() builds and
+      // caches the complete one after settled. Keep the guard window OPEN so a
+      // handler that resumes and awaits a still-waiting rendered() loader is
+      // still caught; close it once settled (every tracked handler has finished
+      // then, so none can await a loader anymore). settled resolves after
+      // rendered() seals; if no loader used rendered(), nothing seals and the
+      // (empty) guard state is simply GC'd at request end.
+      handleStore.settled.then(closeGuard);
+    } else {
+      // Non-streaming: all handlers have settled by now. Build and cache the
+      // snapshot so loader ctx.use(handle) calls don't rebuild it, and close the
+      // guard window immediately.
+      ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+        handleStore,
+        segOrder,
+      );
+      closeGuard();
+    }
     if (resolveBarrier) resolveBarrier();
   };
   Object.defineProperty(ctx, "_renderBarrier", {

package/src/types/loader-types.ts

@@ -72,9 +72,12 @@ export type LoaderContext<
    * **Experimental.** Wait for all non-loader segments to settle.
    *
    * After the returned promise resolves, handle data is available via
-   * `ctx.use(handle)`. Only supported in DSL loaders on non-streaming
-   * trees (no `loading()`). Throws if called from a handler-invoked
-   * loader or when the tree uses streaming.
+   * `ctx.use(handle)`. Supported in DSL loaders, including on streaming
+   * trees that use `loading()` — the barrier waits for the streaming
+   * handlers to finish pushing before it resolves. Throws if called from a
+   * handler-invoked loader, or if a handler is already awaiting this loader
+   * via `ctx.use()` (that would deadlock — use a loader-to-loader
+   * dependency instead).
    *
    * @example
    * ```typescript