@rangojs/router 0.1.1 → 0.4.0

package/skills/rango/SKILL.md

@@ -110,6 +110,7 @@ stated, greppable contract.
 | pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
 | feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
 | cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
+| choose in-function vs CDN caching       | deployment cache boundary          | /deployment-caching     |
 | stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
 ## Invariants
@@ -161,8 +162,8 @@ Same words, different jobs — this is the most common source of the
 | Next.js `export const revalidate = N`   | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                                                                          |
 | Next.js `revalidateTag` / `updateTag`   | **Axis 1** (cache) | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
 | React Router / Remix `shouldRevalidate` | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
-| HTTP `Cache-Control` / ISR              | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                                                                           |
-| Next.js PPR (partial prerendering)      | HTML shell layer   | Same idea, different wiring: the opt-in `ppr` path option captures at runtime (no build-time default); holes are render-defined — `loading()` subtrees plus pending promises under a consumer's own `<Suspense>`. See `/ppr`.                                                           |
+| HTTP `Cache-Control` / ISR              | Deployment layer   | Complete-response deployment layer. A CDN hit bypasses Rango entirely; the store-backed middleware does not. See `/deployment-caching` and `/document-cache`.                                                                                                                           |
+| Next.js PPR (partial prerendering)      | HTML shell layer   | Same React primitive, different transport: Rango serves shells in-function after middleware. Ordinary `ppr` captures at runtime; `Prerender + ppr` captures at build. See `/ppr`, `/prerender`, and `/deployment-caching`.                                                              |
 | Remix/RR `loader`                       | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
 
 See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
@@ -257,17 +258,18 @@ Grouped by concern — read when you need to…
 
 **Data & caching** — fetch, mutate, and cache:
 
-| Skill             | Description                                                                                                                                                       |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
-| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
-| `/caching`        | Segment caching with memory or KV stores                                                                                                                          |
-| `/use-cache`      | Function-level caching with `"use cache"` directive                                                                                                               |
-| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
-| `/document-cache` | Edge caching with Cache-Control headers                                                                                                                           |
-| `/ppr`            | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
-| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
-| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
+| Skill                 | Description                                                                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/loader`             | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
+| `/server-actions`     | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
+| `/caching`            | Segment caching with memory or KV stores                                                                                                                          |
+| `/use-cache`          | Function-level caching with `"use cache"` directive                                                                                                               |
+| `/cache-guide`        | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
+| `/document-cache`     | Store-backed complete-response middleware using Cache-Control policy                                                                                              |
+| `/deployment-caching` | Choose between in-function caches, store-backed responses, and an external CDN cache                                                                              |
+| `/ppr`                | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
+| `/prerender`          | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
+| `/shell-manifest`     | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
 
 **Client & presentation** — build the client-side UX:
 
@@ -295,10 +297,11 @@ Grouped by concern — read when you need to…
 
 **Deployment**:
 
-| Skill         | Description                                                                                                      |
-| ------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `/cloudflare` | Deploy to Cloudflare Workers with the Vite plugin, typed D1/KV bindings, migrations, secrets, and preview parity |
-| `/vercel`     | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing`                        |
+| Skill                 | Description                                                                                                      |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `/cloudflare`         | Deploy to Cloudflare Workers with the Vite plugin, typed D1/KV bindings, migrations, secrets, and preview parity |
+| `/vercel`             | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing`                        |
+| `/deployment-caching` | Compare deployment cache boundaries, middleware execution, PPR transport, and HTTP CDN caching                   |
 
 **Testing**:
 

package/skills/router-setup/SKILL.md

@@ -120,6 +120,10 @@ interface RangoOptions<TEnv> {
   // Set to false to disable prefetch caching.
   prefetchCacheTTL?: number | false;
 
+  // Default prefetch strategy for Links without a `prefetch` prop
+  // (dev: "none", production: "viewport"). Per-Link props win in both directions.
+  defaultPrefetch?: "hover" | "viewport" | "render" | "adaptive" | "none";
+
   // CSP nonce provider (for router.fetch)
   nonce?: (
     request: Request,

package/skills/testing/SKILL.md

@@ -88,7 +88,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
 | one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
 | a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
-| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`)                                                 | `@rangojs/router/testing`        |
+| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`; pass `{ ppr: true }` for pre-handler timing)    | `@rangojs/router/testing`        |
 | a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
 | a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |

package/skills/testing/cache-prerender.md

@@ -113,7 +113,7 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 
 `events` accumulates across requests, so the FIRST matching segment for a `routeKey` wins — slice or recreate the sink between requests for the same route.
 
-## PPR shell (`x-rango-shell`)
+## PPR shell and navigation replay
 
 **DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — shell is a second render axis.
 
@@ -123,6 +123,9 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 | `parseShellStatus(res)`                   | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                        |
 | `shellCacheKey(url)`                      | same                                 | Production shell store key (`host+pathname+sorted search+:shell`) for `store.getShell` / custom stores |
 | `SHELL_STATUS_HEADER`                     | same                                 | `"x-rango-shell"` constant                                                                             |
+| `assertPprReplayStatus(res, expected)`    | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                 |
+| `parsePprReplayStatus(res)`               | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                             |
+| `PPR_REPLAY_STATUS_HEADER`                | same                                 | `"x-rango-ppr-replay"` constant                                                                        |
 
 ### What unit can prove vs e2e
 
@@ -131,6 +134,7 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 | **Unit** | store family + key identity | `MemorySegmentCacheStore` + `shellCacheKey(url)` + `putShell`/`getShell` / tag eviction — dogfood in `e2e/mini/test/shell-store-family.test.ts` and `src/testing/__tests__/shell-status.test.ts` |
 | **Unit** | header helper contract      | `assertShellStatus` on a Response that already carries the header (characterizes the helper; **never** invent a HIT to claim capture worked)                                                     |
 | **E2E**  | live MISS → capture → HIT   | document GET, poll until `x-rango-shell: HIT` (background capture) — `e2e/shell-cache.test.ts`                                                                                                   |
+| **E2E**  | partial replay decision     | soft navigation to a warmed shell and `assertPprReplayStatus(response, { outcome: "HIT", freshness: "fresh" })`                                                                                  |
 
 `dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve.
 

package/skills/vercel/SKILL.md

@@ -8,6 +8,25 @@ argument-hint:
 
 The `vercel` preset builds like the `node` preset (Vercel runs Node Functions, not Workers): rango owns the RSC entry, folds `process.env.NODE_ENV` for the SSR/RSC build, and after `vite build` assembles a `.vercel/output` directory (Build Output API v3) from `dist/` — a single streaming Node Function plus the static client assets.
 
+## Deployment boundary
+
+Only client JS, CSS, and public assets are emitted under
+`.vercel/output/static`. HTML, Flight, prerender payloads, and PPR shells are
+served from the streaming Node Function. `VercelCacheStore` is an in-function
+Runtime Cache backend; it is separate from Vercel's CDN/ISR cache.
+
+The preset does not emit `.prerender-config.json`, a response `chain`, or a
+CDN-stitched PPR resume function. Rango PPR intentionally runs the whole global
+and route middleware chain before committing shell bytes. A CDN-first shell
+cannot preserve that contract because the resume function is invoked after the
+shell starts streaming.
+
+For fully public responses, HTTP `s-maxage`/`stale-while-revalidate` can cache
+the completed response at Vercel's CDN and avoid the function on a hit. That is
+whole-response caching: it freezes loader output and bypasses all Rango
+middleware. Use `/deployment-caching` for the execution matrix and safety
+checklist before adding shared-cache headers.
+
 ## Setup
 
 ```bash
@@ -48,7 +67,9 @@ rango({
 
 ## Runtime Cache
 
-`VercelCacheStore` wraps the Vercel Runtime Cache. Locally (no `process.env.VERCEL`) fall back to an in-memory store so dev/preview work without the platform:
+`VercelCacheStore` wraps the Vercel Runtime Cache for segment, item, response,
+and PPR shell families. Locally (no `process.env.VERCEL`) fall back to an
+in-memory store so dev/preview work without the platform:
 
 ```typescript
 import {

package/skills/view-transitions/SKILL.md

@@ -209,9 +209,8 @@ interface TransitionConfig {
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
   viewTransition?: "auto" | false; // boundary opt-out (see below)
-  // Conditional gate, evaluated server-side AFTER the route handler. Return
-  // false to drop this transition for the request, so the navigation streams its
-  // loading() fallback instead of holding. See the gate section below.
+  // Conditional server-side gate. PPR routes run it before route handlers and
+  // on every replay; other routes run it after handlers on fresh resolution.
   when?: (ctx: TransitionWhenContext) => boolean;
 }
 ```
@@ -223,14 +222,19 @@ interface TransitionConfig {
 
 ## Conditional transitions (`when`)
 
-`transition({ when })` gates the hold per request. The predicate runs **server-side, AFTER the route handler** and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
+`transition({ when })` gates the hold per request. The predicate runs server-side and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
 
-Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for post-handler reads:
+Timing follows the route's rendering contract:
+
+- On an ordinary route it runs after the route handler during fresh resolution, so `get()` can read handler- and middleware-set context. Cache/prerender hits replay the stored decision.
+- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers. This is what keeps the handler-free PPR fast path available without a second API.
+
+Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for request-context reads:
 
 ```ts
 import type { TransitionWhenContext } from "@rangojs/router";
 
-// Hold only when the handler marked this request (handler sets, gate reads):
+// Ordinary route: hold only when the handler marked this request:
 transition({ when: (ctx) => ctx.get(KeepScroll) === true });
 
 // Hold only when arriving from a specific page (the navigation SOURCE):
@@ -252,13 +256,13 @@ transition({
 | `toRouteName` (and `fromRouteName`)                    | route **name**                               | when the route is named (undefined for unnamed/auto-generated)                        |
 | `actionId` / `actionUrl` / `actionResult` / `formData` | the server action that triggered this render | action-triggered renders only                                                         |
 | `method`                                               | `"GET"` (nav) / `"POST"` (action)            | always                                                                                |
-| `get` / `env`                                          | read handler/middleware vars + app env       | always                                                                                |
+| `get` / `env`                                          | read request vars + app env                  | always; PPR timing exposes middleware vars, not handler writes                        |
 
 A predicate that throws is reported to `router.onError` (phase `"rendering"`) and treated as no-hold (conservative).
 
 **Same-route content-holds need the transition present on the FIRST render.** The same-route hold works by giving the route a param-agnostic key so a param change reconciles instead of remounting — but that key is established when the route first mounts. A source gate that returns `false` on the initial full load (where `currentUrl`/`currentParams`/`fromRouteName` are undefined) drops the transition before the route mounts, so the route mounts _outside_ a transition scope and **every** later same-route param nav remounts (flashing the skeleton) regardless of what the gate decides on those navs. Write source gates so they hold when there is no source — e.g. `({ currentParams }) => currentParams?.tab !== "raw"` (true on the initial load) rather than `=== "details"` (false on the initial load) — when the same-route content-hold must engage. This only affects same-route param navigations; action-only or cross-route gating is unaffected (no shared param key is in play).
 
-**Prefetch / cache caveat.** The gate runs during resolution, so a **prefetched** navigation decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source — and a `cache()`/prerender hit replays the stored transition without re-running the predicate. A source-sensitive gate can therefore be frozen to prefetch/store-time state. This covers ~99% of navigations; if yours must reflect the exact click-time source, source-scope the prefetch (`<Link prefetchKey=":source">`) and don't `cache()` that segment.
+**Prefetch / cache caveat.** A **prefetched** navigation still decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source. Non-PPR `cache()`/prerender hits also replay the stored transition without rerunning the predicate. PPR routes rerun it on the server for each cache/prerender/PPR match, but a completed browser prefetch still carries its earlier Flight decision. If the exact click-time source matters, source-scope the prefetch (`<Link prefetchKey=":source">`).
 
 ## Opting out of the router boundary (place your own `<ViewTransition>`)
 

package/src/browser/prefetch/default-strategy.ts

@@ -0,0 +1,34 @@
+/**
+ * Router-wide default Link prefetch strategy (client seat).
+ *
+ * The server resolves `createRouter({ defaultPrefetch })` once at router init
+ * (router/prefetch-default.ts) and ships it in initial payload metadata; the
+ * browser entry applies it here before hydration — same lifecycle as
+ * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
+ * explicit `prefetch` prop reads the value at render time.
+ *
+ * The module initial value must equal the server resolver's environment default:
+ * `"none"` in development and `"viewport"` in production. During SSR this
+ * module is never initialized from metadata, so keeping both seats aligned also
+ * gives metadata-less payloads the documented behavior.
+ */
+
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+
+// Mirrors DEFAULT_PREFETCH_STRATEGY without pulling router-layer code into the
+// client bundle. NODE_ENV is folded by the app build.
+let defaultStrategy: PrefetchStrategy =
+  process.env.NODE_ENV === "production" ? "viewport" : "none";
+
+/**
+ * Apply the server-resolved default strategy. Called once at browser app init
+ * from payload metadata; also used by tests to reset state.
+ */
+export function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void {
+  defaultStrategy = strategy;
+}
+
+/** Current default strategy for Links without an explicit `prefetch` prop. */
+export function getDefaultPrefetchStrategy(): PrefetchStrategy {
+  return defaultStrategy;
+}

package/src/browser/prefetch/loader.ts

@@ -1,4 +1,8 @@
 import type { RscPayload } from "../types.js";
+import {
+  observeForPrefetch as observeElementForPrefetch,
+  unobserveForPrefetch,
+} from "./observer.js";
 
 type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
 
@@ -83,19 +87,9 @@ export function observeForPrefetch(
   callback: () => void,
 ): () => void {
   if (typeof IntersectionObserver === "undefined") return () => {};
-  let active = true;
-  if (runtime) {
-    runtime.observeForPrefetch(element, callback);
-  } else {
-    void loadRuntime()
-      .then((loaded) => {
-        if (active) loaded.observeForPrefetch(element, callback);
-      })
-      .catch(() => {});
-  }
+  observeElementForPrefetch(element, callback);
   return () => {
-    active = false;
-    runtime?.unobserveForPrefetch(element);
+    unobserveForPrefetch(element);
   };
 }
 

package/src/browser/prefetch/runtime.ts

@@ -4,4 +4,3 @@ export {
   cancelAllPrefetches,
   setPrefetchConcurrency,
 } from "./queue.js";
-export { observeForPrefetch, unobserveForPrefetch } from "./observer.js";

package/src/browser/react/Link.tsx

@@ -37,7 +37,9 @@ import {
   prefetchDirect,
   prefetchQueued,
 } from "../prefetch/loader.js";
+import { getDefaultPrefetchStrategy } from "../prefetch/default-strategy.js";
 import { getAppVersion } from "../app-version.js";
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
 // The (hover: none) MediaQueryList, created lazily on first client read and
 // reused across every Link render. matchMedia allocates and registers a live
@@ -62,20 +64,10 @@ function isTouchDevice(): boolean {
   return hoverNoneQuery.matches;
 }
 
-/**
- * Prefetch strategy for the Link component
- * - "hover": Prefetch on mouse enter (direct, no queue)
- * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
- * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
- * - "adaptive": Hover on pointer devices, viewport on touch devices
- * - "none": No prefetching (default)
- */
-export type PrefetchStrategy =
-  | "hover"
-  | "viewport"
-  | "render"
-  | "adaptive"
-  | "none";
+// The PrefetchStrategy union is defined in router/prefetch-default.ts (both
+// the server-side option resolver and this client seat consume it); re-export
+// so the public `PrefetchStrategy` import path via client.tsx is unchanged.
+export type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
 /**
  * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
@@ -125,8 +117,12 @@ export interface LinkProps extends Omit<
    */
   revalidate?: boolean;
   /**
-   * Prefetch strategy for the link destination
-   * @default "none"
+   * Prefetch strategy for the link destination. When omitted, falls back to
+   * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
+   * development, `"viewport"` in production). An explicit value always wins
+   * over the router default, including `"none"` to opt a single Link out.
+   *
+   * @default the router's environment-aware `defaultPrefetch`
    */
   prefetch?: PrefetchStrategy;
   /**
@@ -240,7 +236,7 @@ export const Link: ForwardRefExoticComponent<
     scroll = true,
     reloadDocument = false,
     revalidate,
-    prefetch = "none",
+    prefetch,
     prefetchKey,
     state,
     children,
@@ -262,10 +258,15 @@ export const Link: ForwardRefExoticComponent<
     return to === "/" ? bn : bn + to;
   }, [to, isExternal, ctx?.basename]);
 
-  // Resolve adaptive: viewport on touch devices, hover on pointer devices.
-  // isTouchDevice() is read here (per render), not from a module-load snapshot,
-  // so a device whose input capability changes resolves to the current value.
-  const resolvedStrategy = resolveAdaptiveStrategy(prefetch);
+  // No explicit `prefetch` prop: fall back to the router-wide default
+  // (server-resolved, applied at browser init — before hydration, so this
+  // render-time read never races the metadata). Then resolve adaptive:
+  // viewport on touch devices, hover on pointer devices. isTouchDevice() is
+  // read here (per render), not from a module-load snapshot, so a device
+  // whose input capability changes resolves to the current value.
+  const resolvedStrategy = resolveAdaptiveStrategy(
+    prefetch ?? getDefaultPrefetchStrategy(),
+  );
 
   // Internal ref for viewport observation; merge with forwarded ref
   const internalRef = useRef<HTMLAnchorElement | null>(null);

package/src/browser/rsc-router.tsx

@@ -30,6 +30,7 @@ import {
   setPrefetchConcurrency,
   setPrefetchDecoder,
 } from "./prefetch/loader.js";
+import { setDefaultPrefetchStrategy } from "./prefetch/default-strategy.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -297,6 +298,13 @@ export async function initBrowserApp(
   if (prefetchConcurrency !== undefined) {
     setPrefetchConcurrency(prefetchConcurrency);
   }
+  // Apply the router-wide default Link prefetch strategy. Undefined (older
+  // server payload) keeps the module's environment-aware default, which equals
+  // the server resolver's default by contract — see default-strategy.ts.
+  const defaultPrefetch = initialPayload.metadata?.defaultPrefetch;
+  if (defaultPrefetch !== undefined) {
+    setDefaultPrefetchStrategy(defaultPrefetch);
+  }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
   // client chunks (same createFromFetch the navigation client uses).

package/src/browser/types.ts

@@ -82,6 +82,11 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its prefetch queue.
    */
   prefetchConcurrency?: number;
+  /**
+   * Router-wide default prefetch strategy for Links without a `prefetch` prop.
+   * Sent on initial render; applied once at init (default-strategy.ts).
+   */
+  defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
   /**
    * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
    * reads it verbatim and binds the rango state cookie to it; composition

package/src/cache/cache-scope.ts

@@ -108,6 +108,8 @@ function getDefaultRouteCacheKey(
 // CacheScope
 // ============================================================================
 
+const CACHE_HIT_OBSERVERS = new WeakMap<CacheScope, () => void>();
+
 /**
  * CacheScope represents a cache boundary in the route tree.
  *
@@ -348,6 +350,7 @@ export class CacheScope {
         );
       }
 
+      CACHE_HIT_OBSERVERS.get(this)?.();
       return { segments, shouldRevalidate };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
@@ -555,9 +558,11 @@ export function resolveShellImplicitCacheScope(
   if (scope) return scope;
   const marker = getRequestContext()?._shellImplicitCache;
   if (!marker) return null;
-  return new CacheScope(
+  const implicitScope = new CacheScope(
     { ttl: marker.ttl, swr: marker.swr, store: marker.store },
     null,
     marker.keyPrefix,
   );
+  if (marker.onHit) CACHE_HIT_OBSERVERS.set(implicitScope, marker.onHit);
+  return implicitScope;
 }

package/src/cache/cf/cf-cache-store.ts

@@ -295,6 +295,8 @@ interface KVShellEnvelope {
   lh?: boolean;
   /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
   tw?: true;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
 }
 
 /**
@@ -1819,6 +1821,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           snapshot: envelope.sn,
           handlerLiveHoles: envelope.lh,
           transitionWhen: envelope.tw,
+          navigationOnly: envelope.no,
           createdAt: envelope.c,
         },
         shouldRevalidate,
@@ -1907,6 +1910,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             sn: entry.snapshot,
             lh: entry.handlerLiveHoles,
             tw: entry.transitionWhen,
+            no: entry.navigationOnly,
           };
           await this.kv!.put(kvKey, JSON.stringify(envelope), {
             expirationTtl: retentionTtl,

package/src/cache/document-cache.ts

@@ -1,7 +1,9 @@
 /**
  * Document-Level Cache Middleware
  *
- * Caches full HTTP responses at the edge based on Cache-Control headers.
+ * Caches full HTTP responses in the configured app store based on Cache-Control
+ * headers. A deployment CDN may independently consume the same shared-cache
+ * directives; this middleware itself runs inside the worker/function.
  * Routes opt-in to caching by setting s-maxage or stale-while-revalidate headers.
  *
  * Flow:
@@ -58,7 +60,7 @@ function parseCacheControl(header: string | null): CacheDirectives | null {
 
   // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
   // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
-  // The document cache is a shared edge store, so refuse both regardless of any
+  // The document cache is a shared app store, so refuse both regardless of any
   // s-maxage / stale-while-revalidate also present. Match standalone directive
   // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
   // substring, so a value containing "private" cannot false-veto.

package/src/cache/types.ts

@@ -305,6 +305,12 @@ export interface ShellCacheEntry {
    * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
   snapshot?: ShellSnapshotRecord[];
+  /**
+   * The entry was captured from a partial request only to produce an eligible
+   * segment snapshot. Document serving must treat its HTML prelude as a miss;
+   * the partial request's headers and middleware state are not document state.
+   */
+  navigationOnly?: true;
   /**
    * True when the capture's HANDLER layer declared per-request liveness: a
    * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
@@ -319,9 +325,10 @@ export interface ShellCacheEntry {
    */
   handlerLiveHoles?: boolean;
   /**
-   * The capture encountered transition({ when }). Its effective hold policy is
-   * request-dependent, so handler-free document and navigation replay must
-   * re-run resolution to collect and evaluate the predicate.
+   * Legacy/fallback marker for a transition({ when }) predicate that was not
+   * evaluated by the PPR pre-handler gate. Such an entry stays conservatively
+   * ineligible for handler-free replay. New PPR matches evaluate known segment
+   * predicates before the pipeline and do not set this marker.
    */
   transitionWhen?: true;
   /** Capture-generation start time; tag invalidations at or after it win. */

package/src/cache/vercel/vercel-cache-store.ts

@@ -211,6 +211,8 @@ interface VercelShellEnvelope {
   lh?: boolean;
   /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
   tw?: true;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
 }
 
 /** Read-path outcome for the debug sink. */
@@ -816,6 +818,7 @@ export class VercelCacheStore<
         snapshot: env.sn,
         handlerLiveHoles: env.lh,
         transitionWhen: env.tw,
+        navigationOnly: env.no,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -865,6 +868,7 @@ export class VercelCacheStore<
         sn: entry.snapshot,
         lh: entry.handlerLiveHoles,
         tw: entry.transitionWhen,
+        no: entry.navigationOnly,
       };
       // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
       // oversized shell prelude is reported and skipped (fail-open to a full
@@ -1192,7 +1196,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, bv, c, s, e, t, i, sn, lh, tw } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn, lh, tw, no } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1210,6 +1214,7 @@ export class VercelCacheStore<
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : undefined,
       lh: lh === true ? true : undefined,
       tw: tw === true ? true : undefined,
+      no: no === true ? true : undefined,
     };
   }
 

package/src/route-definition/helpers-types.ts

@@ -460,11 +460,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * startTransition only when the router sets viewTransition: false.
    *
    * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
-   * request. It runs server-side AFTER the route handler (so it can read state
-   * the handler set via `ctx.get(...)`); returning false drops this transition
-   * for the request, so the navigation streams its loading() skeleton instead of
-   * holding. This is a post-handler predicate — distinct from intercept()'s
-   * match-time `when` config selector (`intercept(slot, route, Comp, { when })`).
+   * request. It normally runs server-side after the route handler. On a `ppr`
+   * route it is automatically hoisted before route handlers and reevaluated on
+   * every replay, so it may read URL/params/action/env and middleware-set context
+   * but not handler-set context. Returning false drops this transition for the
+   * request. This is distinct from intercept()'s match-time `when` selector.
    *
    * ```typescript
    * // Attach to a single route
@@ -491,7 +491,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * @param config - ViewTransition configuration (enter, exit, update, share,
    *   default, name), `viewTransition: "auto" | false` to toggle the router
    *   boundary (createRouter({ viewTransition }) sets the app-wide default), and
-   *   `when: (ctx) => boolean` to gate the transition per request post-handler
+   *   `when: (ctx) => boolean` to gate the transition per request
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {