perf(router): warm prefetched navigations by decoding eagerly - #554

Problem

A consumer who adds prefetch to a <Link> expects a clicked-while-visible route to be warm — instant, no loading work. Today it is only half-warm. The prefetch fetches and buffers the route's RSC bytes, but it does not decode them. Decoding the Flight stream is what resolves the route's client references and imports its JS chunk — and that was deferred to click time. So in DevTools the consumer sees the route's app-*.js chunk download on click, not on hover/scroll, and the navigation stalls behind a code fetch + RSC decode that the prefetch was supposed to have already paid for.

This is the same gap waku hit in #2099 / #2100. This PR closes it for rango: prefetch now decodes eagerly, so the route's chunk is imported during the prefetch and the click loads no new code.

Before vs. after

The consumer writes the same code — only the runtime behavior changes:

<Link to="/dashboard" prefetch="hover">Dashboard</Link>

Observable in DevTools Network: the route's .js chunk now appears on hover/scroll/render, and no new JS request fires on click.

End-to-end example

Nothing to adopt — warming is automatic for every prefetch strategy (hover, viewport, render, adaptive). A realistic product nav:

export function ProductCard({ id }: { id: string }) {
  // viewport-prefetched as the card scrolls into view: by the time the user
  // taps, /product/:id's client chunk is already imported and decoded.
  return (
    <Link to={`/product/${id}`} prefetch="viewport">
      <img src={`/img/${id}.webp`} loading="lazy" />
      View details
    </Link>
  );
}

Semantics

The prefetch decode happens up front; navigation reuses the result. Each prefetch outcome:

A speculative prefetch never reloads the page or throws a redirect — only a real navigation acts on control headers.

Code changes

• browser/prefetch/fetch.ts — executePrefetchFetch decodes the response with the injected createFromFetch (new setPrefetchDecoder, wired once in rsc-router.tsx init like setServerCallback). Tees off a silent completion tracker; drops control-header responses; stores a DecodedPrefetch.
• browser/prefetch/cache.ts — entries are now DecodedPrefetch { payload, streamComplete, scope } instead of a raw Response. Decoded payloads are reusable (safer than a single-use stream body); TTL/FIFO/generation/inflight-alias machinery unchanged.
• browser/navigation-client.ts — warm hits reuse entry.payload / entry.streamComplete and skip createFromFetch; cross-source discard keys off entry.scope. Fresh path (control-header validation + decode) is unchanged.
• browser/response-adapter.ts — teeWithCompletion(..., silent): prefetch suppresses benign speculative-stream-error logs; the fresh-navigation path still logs.

Why no waku-style store-rebinding: rango dispatches server actions through the global __viteRscCallServer (set once via setServerCallback, read live at invocation), and the nav/prefetch decode passes no per-call callServer — so nothing navigation-specific is baked into the decoded tree. Why waku's issue #1 (wrong-chunk preload table) is N/A: rango resolves chunks by the reference id embedded in the payload (virtual:vite-rsc/client-references), not a per-route index table. Both waku fixes collapse to the single eager-decode change here.

Test plan

• Unit (pnpm test:unit) — 3387 passed. New: prefetch-fetch asserts the decode runs exactly once at prefetch and control-header responses are not warmed; navigation-client asserts warm hits skip createFromFetch + the source-scoped-wildcard discard; prefetch-cache updated to the decoded-entry contract.
• e2e — dev + production — new mini test clientChunks: prefetch warms the route's client chunk before the click (nameless /warm route, render-prefetch to /widgets): asserts the /widget/ resource loads during the prefetch and no new .js loads on click, in both modes. Existing link-behavior + prefetch-cache-control green dev + prod.
• Full e2e — rangojs-router 1664 passed, vite-rsc-demo 221 passed, cloudflare-basic 435 passed (isolated). The only failures across runs were flaky HMR watcher tests (route-types-hmr, cloudflare hmr.test.ts), unrelated to this change and confirmed passing in isolation.
• typecheck, lint (0/0), format — clean.

Notes

• Warming applies to all strategies, including viewport — visible links now also import their route chunk, not just buffer bytes. This is intentional (matches waku) and bounded by the existing 5-min TTL + 50-entry FIFO cap.
• setPrefetchDecoder / DecodedPrefetch are internal (browser runtime), not public API — no export-surface change.