@rangojs/router 0.1.1 → 0.4.0

package/README.md

@@ -38,7 +38,7 @@ Node setup.
 
 ## Using the skills with your coding agent
 
-This package ships 43 agent skills in `node_modules/@rangojs/router/skills/` —
+This package ships agent skills in `node_modules/@rangojs/router/skills/` —
 task-focused guides written for LLM coding agents. Start at
 `skills/rango/SKILL.md` (the mental model + catalog); a machine-readable index
 is at `skills/catalog.json`.
@@ -375,6 +375,7 @@ when the requirement appears:
 | test loaders, middleware, handlers, Flight      | [`/testing`](./skills/testing/SKILL.md)                                                      |
 | see where request time goes                     | [`/observability`](./skills/observability/SKILL.md)                                          |
 | deploy to Vercel (cache store, tracing, output) | [`/vercel`](./skills/vercel/SKILL.md)                                                        |
+| choose in-function vs CDN caching               | [`/deployment-caching`](./skills/deployment-caching/SKILL.md)                                |
 | compare Rango with Next.js / TanStack / Waku    | [`/comparison`](./skills/comparison/SKILL.md)                                                |
 
 The [`/rango` skill](./skills/rango/SKILL.md) is the full catalog and the

package/dist/types/browser/prefetch/default-strategy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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";
+/**
+ * Apply the server-resolved default strategy. Called once at browser app init
+ * from payload metadata; also used by tests to reset state.
+ */
+export declare function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void;
+/** Current default strategy for Links without an explicit `prefetch` prop. */
+export declare function getDefaultPrefetchStrategy(): PrefetchStrategy;

package/dist/types/browser/prefetch/runtime.d.ts

@@ -1,3 +1,2 @@
 export { prefetchDirect, prefetchQueued, setPrefetchDecoder } from "./fetch.js";
 export { abortAllPrefetches, cancelAllPrefetches, setPrefetchConcurrency, } from "./queue.js";
-export { observeForPrefetch, unobserveForPrefetch } from "./observer.js";

package/dist/types/browser/react/Link.d.ts

@@ -8,15 +8,8 @@ import { type LocationStateEntry } from "./location-state.js";
  */
 export type StateOrGetter<T = unknown> = T | (() => T);
 export type LinkState = LocationStateEntry[] | StateOrGetter<Record<string, unknown>>;
-/**
- * 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";
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+export type { PrefetchStrategy } from "../../router/prefetch-default.js";
 /**
  * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
  * for the CURRENT input capability: "viewport" on touch (no-hover) devices,
@@ -56,8 +49,12 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      */
     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;
     /**

package/dist/types/browser/types.d.ts

@@ -77,6 +77,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/dist/types/cache/document-cache.d.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:

package/dist/types/cache/types.d.ts

@@ -265,6 +265,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
@@ -279,9 +285,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/dist/types/route-definition/helpers-types.d.ts

@@ -349,11 +349,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
@@ -380,7 +380,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: {

package/dist/types/router/match-handlers.d.ts

@@ -1,10 +1,9 @@
 import type { ReactNode } from "react";
-import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
-import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
+import type { ErrorBoundaryHandler, ErrorInfo, ErrorPhase, MatchResult } from "../types";
+import { type EntryData, type InterceptEntry, type InterceptSelectorContext } from "../server/context.js";
 import type { MatchApiDeps } from "./types.js";
 import type { RouterContext } from "./router-context.js";
 import { type ActionContext } from "./match-context.js";
-import type { ErrorBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import { type TelemetrySink } from "./telemetry.js";
 export interface MatchHandlerDeps<TEnv = any> {

package/dist/types/router/prefetch-default.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve the router-wide default Link prefetch strategy once, at router init.
+ * The resolved value ships to the client in payload metadata; the browser
+ * entry applies it via `setDefaultPrefetchStrategy` (browser/prefetch/
+ * default-strategy.ts) and every `<Link>` without an explicit `prefetch` prop
+ * falls back to it.
+ *
+ * The type lives HERE (not in browser/react/Link.tsx) because both seats need
+ * it: this server-side resolver and the client Link/default-strategy modules.
+ * Link.tsx re-exports it so the public `PrefetchStrategy` export path is
+ * unchanged.
+ *
+ * Policy note: automatic prefetch stays quiet in development, matching the
+ * production-only default used by Next.js. Explicit router and per-Link
+ * strategies still work in every mode. Invalid untyped inputs fall back to the
+ * current environment's default.
+ */
+/**
+ * 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
+ */
+export type PrefetchStrategy = "hover" | "viewport" | "render" | "adaptive" | "none";
+export declare const DEFAULT_PREFETCH_STRATEGY: PrefetchStrategy;
+export declare function resolveDefaultPrefetch(raw: PrefetchStrategy | undefined, nodeEnv?: string | undefined): PrefetchStrategy;

package/dist/types/router/router-interfaces.d.ts

@@ -249,6 +249,13 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * prefetchConcurrency.
      */
     readonly prefetchConcurrency: number;
+    /**
+     * Router-wide default Link prefetch strategy for Links without an explicit
+     * `prefetch` prop. Shipped to the client in payload metadata. Derived from
+     * the `defaultPrefetch` option (default "none" in development and
+     * "viewport" in production).
+     */
+    readonly defaultPrefetch: import("./prefetch-default.js").PrefetchStrategy;
     /**
      * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
      * router init and shipped to the client in payload metadata. The server-side

package/dist/types/router/router-options.d.ts

@@ -7,6 +7,7 @@ import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
+import type { PrefetchStrategy } from "./prefetch-default.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { RouterTracingConfig } from "./tracing.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -495,6 +496,35 @@ export interface RangoOptions<TEnv = any> {
      * @default 2
      */
     prefetchConcurrency?: number;
+    /**
+     * Default prefetch strategy for every `<Link>` that does not set its own
+     * `prefetch` prop. A per-Link `prefetch` prop always wins, in both
+     * directions (a Link can opt out of an aggressive default with
+     * `prefetch="none"`, or opt in under `defaultPrefetch: "none"`).
+     *
+     * - `"viewport"` (production default): prefetch when the link enters the viewport —
+     *   idle-gated and queued (see `prefetchConcurrency`), so prefetches never
+     *   compete with hydration or an active navigation.
+     * - `"hover"`: prefetch on mouse enter only. Much lighter on the server —
+     *   only links the pointer approaches are fetched — at the cost of the
+     *   ~100-300ms head start viewport prefetch gives.
+     * - `"adaptive"`: `"hover"` on pointer devices, `"viewport"` on touch
+     *   devices (no hover to wait for).
+     * - `"render"`: prefetch on mount regardless of visibility.
+     * - `"none"`: manual mode — nothing prefetches unless a Link opts in.
+     *
+     * Automatic prefetch defaults to `"none"` in development and `"viewport"`
+     * in production. With the production default, every visible Link triggers an
+     * RSC render (loaders included) on the server. Routes served from cache/PPR
+     * absorb this cheaply; per-user dynamic routes pay full price per viewport
+     * entry. Set `"hover"`, `"adaptive"`, or `"none"` when that cost matters.
+     *
+     * To disable the prefetch subsystem entirely (including per-Link opt-ins
+     * and `useRouter().prefetch()`), set `prefetchCacheTTL: false` instead.
+     *
+     * @default "none" in development; "viewport" in production
+     */
+    defaultPrefetch?: PrefetchStrategy;
     /**
      * Prefix for the rango state cookie name. The resolved name is
      * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe

package/dist/types/router/segment-resolution/view-transition-default.d.ts

@@ -20,9 +20,8 @@ import type { EntryData } from "../../server/context";
  * gate, which also avoids needless object allocation and payload growth.
  *
  * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache) and recorded on the request
- * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
- * outside any cache scope — and drop this segment's transition when it returns
- * false. Used by both the fresh and revalidation resolution paths.
+ * function cannot cross Flight or the segment cache). PPR routes evaluate it
+ * from the manifest before the pipeline; other routes record it here for the
+ * existing post-handler gate. Used by both fresh and revalidation resolution.
  */
 export declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined, segmentId?: string): EntryData["transition"];

package/dist/types/router/transition-when.d.ts

@@ -0,0 +1,13 @@
+import { type EntryData } from "../server/context.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+export type TransitionWhenErrorReporter = (error: unknown, segmentId: string) => void;
+export declare function createTransitionWhenContext<TEnv>(ctx: RequestContext<TEnv>, target?: {
+    params: Record<string, string>;
+    routeName?: string;
+}): TransitionWhenContext<Record<string, string>, TEnv>;
+/** Evaluate server-only transition gates before handlers on a PPR route. */
+export declare function evaluatePprTransitionWhen<TEnv>(entries: EntryData[], ctx: RequestContext<TEnv>, target: {
+    params: Record<string, string>;
+    routeName?: string;
+}, reportError: TransitionWhenErrorReporter): void;

package/dist/types/rsc/capture-queue.d.ts

@@ -1,3 +1,9 @@
+/** Bound queued/running capture closures retained by one isolate. */
+export declare const MAX_ADMITTED_CAPTURES: number;
+/** The caller may drop this best-effort capture and retry on a later request. */
+export declare class CaptureQueueFullError extends Error {
+    constructor();
+}
 /**
  * Run `task` after every previously enqueued capture has settled. Returns a
  * promise for THIS task's completion (rejections propagate to the caller —

package/dist/types/rsc/shell-capture.d.ts

@@ -124,10 +124,11 @@ export interface ShellCaptureDebugEvent {
      *   the key (stampede guard) and scheduled nothing
      * - skip-backoff: the key is inside its refused-capture backoff window and
      *   the capture was not attempted
+     * - skip-capacity: the isolate capture queue is full; a later request may retry
      * - backoff: the key entered (or escalated) backoff after a terminal
      *   no-shell — carries the new backoff state
      */
-    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "backoff";
     /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
     attempt?: number;
     /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
@@ -148,6 +149,8 @@ export interface ShellCaptureDebugEvent {
     snapshotBytes?: number;
     /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
     snapshotSkipped?: boolean;
+    /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
+    untaggedBake?: true;
     /** Outcome reported by a store that supports shell-write acknowledgements. */
     storeWrite?: "stored" | "invalidated";
     /** Consecutive failure count in the key's backoff entry, when one exists. */
@@ -280,6 +283,8 @@ export interface ShellCaptureDescriptor {
      * {@link ShellCaptureDebugEvent} per attempt/skip.
      */
     debugSink?: (event: ShellCaptureDebugEvent) => void;
+    /** Store the snapshot for navigation replay, never the captured HTML prelude. */
+    navigationOnly?: true;
 }
 /**
  * Schedule the background shell capture for a served document. Stampede-guarded:
@@ -288,11 +293,11 @@ export interface ShellCaptureDescriptor {
  * error is routed through reportCacheError — capture is best-effort; a failure just
  * means the next request recaptures.
  *
- * Eligibility (nonce/allReady/partial/status/strategy) is decided by the caller
- * (rsc-rendering.ts maybeScheduleShellCapture); this function only owns the
- * stampede guard and the background dispatch.
+ * Eligibility (nonce/partial/status/strategy) is decided by the caller. An SSR
+ * module loader may be passed for cold partial requests; it runs only after the
+ * capture enters the guarded background queue, never on response latency.
  */
-export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor): void;
+export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule | ((request: Request, url: URL) => Promise<SSRModule | null>), descriptor: ShellCaptureDescriptor): void;
 /**
  * The outcome of one capture attempt.
  * - `stored`: a usable shell was captured (and a putShell was attempted; a store
@@ -310,7 +315,7 @@ type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
  * bag, not a return value: captureAndStoreShell's outcome type stays a string
  * union its existing callers (producer B, tests) consume unchanged.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "storeWrite">;
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite">;
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -351,7 +356,10 @@ export interface CaptureContextDerivation {
  * createRequestContext over the build env, with a fresh MemorySegmentCacheStore
  * as `_cacheStore` so the recording/snapshot machinery arms identically.
  */
-export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">): CaptureContextDerivation;
+export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">, identity?: {
+    request: Request;
+    url: URL;
+}): CaptureContextDerivation;
 /**
  * Seal handles, derive the quiesce signal, prerender + abort via the SSR module's
  * captureShellHTML, and store the result. Returns the attempt outcome (the caller

package/dist/types/rsc/shell-serve.d.ts

@@ -19,6 +19,8 @@ import { type EntryData } from "../server/context.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export declare const SHELL_STATUS_HEADER = "x-rango-shell";
+/** Partial-navigation status header set only after captured PPR segments are consumed. */
+export declare const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
  * that omits `ttl`.
@@ -51,9 +53,10 @@ export interface ResolvedPprConfig {
     captureTimeout?: number;
 }
 /**
- * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms passes
- * through; anything else (including 0/negative/NaN/Infinity/non-number)
- * resolves to undefined, which means "use the capture default" downstream.
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms is
+ * clamped to the default ceiling; anything else (including
+ * 0/negative/NaN/Infinity/non-number) resolves to undefined, which means "use
+ * the capture default" downstream.
  * Mirrors the prefetch-limit option policy: invalid values silently fall back
  * to the default rather than throwing at request time. Also the boundary
  * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),

package/dist/types/rsc/transition-gate.d.ts

@@ -4,24 +4,20 @@ import type { OnErrorCallback } from "../types/error-types.js";
 /**
  * Apply transition({ when }) gates to a payload's segments.
  *
- * The predicates were collected during resolution (keyed by segment id) and
- * stripped from the serialized config; here — after handlers ran and outside any
- * cache scope — we evaluate each and drop the segment's transition when the
- * predicate does not hold, so the navigation streams its loading fallback
- * instead of holding the previous content. A predicate that throws is reported
- * to the router's onError (phase "rendering") and then treated as "do not hold"
- * (conservative), so a buggy predicate degrades to no transition rather than
- * failing the response.
+ * PPR predicates were evaluated from the manifest before cache lookup and route
+ * handlers; their request-specific decisions are projected onto a copy so they
+ * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
+ * were collected during fresh resolution and are evaluated here after handlers.
+ * Both paths drop the segment transition when the predicate does not hold.
  *
  * Mutating the segments here is safe: the segment cache stores a serialized copy
  * (segment-codec), written during match() BEFORE this gate runs, so dropping a
- * transition never corrupts a cache entry. The flip side is that a cache hit
+ * transition never corrupts a cache entry. On an ordinary route, a cache hit
  * skips resolution, collects no predicate, and replays the cached transition
- * as-is (it was serialized before the gate) — combining transition({ when })
- * with cache() on the same segment freezes the gate to its cached state, so
- * avoid caching a route whose transition decision is request-dependent.
+ * as-is (it was serialized before the gate). PPR routes are the exception: their
+ * manifest predicates were evaluated before lookup and apply to replayed data.
  *
- * Returns the same array (mutated) for inline use at the payload's `segments`
- * field.
+ * Returns the same array for the ordinary post-handler path. A PPR drop returns a
+ * copy containing only the request-specific transition changes.
  */
 export declare function gateTransitions(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>, onError?: OnErrorCallback): MatchResult["segments"];

package/dist/types/rsc/types.d.ts

@@ -49,6 +49,8 @@ export interface RscPayload {
         prefetchCacheSize?: number;
         /** Max concurrent speculative prefetch requests on the client */
         prefetchConcurrency?: number;
+        /** Router-wide default prefetch strategy for Links without a `prefetch` prop */
+        defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
         /** Server-resolved rango state cookie name; the client reads it verbatim. */
         stateCookieName?: string;
         /** Theme configuration for FOUC prevention */

package/dist/types/server/request-context.d.ts

@@ -141,6 +141,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         id: string;
         when: TransitionWhenFn;
     }>;
+    /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
+    _pprTransitionDecisions?: Map<string, boolean>;
     /** @internal Cache store for segment caching (optional, used by CacheScope) */
     _cacheStore?: SegmentCacheStore;
     /**
@@ -202,6 +204,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * segment record even when the triggering request is partial.
          */
         keyPrefix?: "doc";
+        /** @internal Called only after the implicit cache hit decodes successfully. */
+        onHit?: () => void;
     };
     /**
      * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
@@ -514,7 +518,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_cacheStore" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_cacheStore" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/testing/e2e/index.d.ts

@@ -1,11 +1,11 @@
 import type { Expect, TestType } from "@playwright/test";
 import { createUseFixture, type Fixture, type FixtureOptions } from "./fixture.js";
-import { createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, isVisibleInViewport, measureTime, type PageHelpers, parseNumber, type Stopwatch, testId, waitForElement, waitForHydration, waitForNavigation } from "./page-helpers.js";
+import { blockPrefetch, unblockPrefetch, createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, isPrefetchRequest, isVisibleInViewport, measureTime, type PageHelpers, parseNumber, type Stopwatch, testId, waitForElement, waitForHydration, waitForNavigation } from "./page-helpers.js";
 import { createParity, type ExpectParityOptions, type Parity, type ParityDescribeOptions, type ParityIntent } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, type CacheSink, type ExpectedCacheStatus, type CacheStatusTarget, } from "../cache-status.js";
-export { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
-export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, type PprReplayBypassReason, type PprReplayStatus, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
+export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, isPrefetchRequest, blockPrefetch, unblockPrefetch, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
 export type { Fixture, FixtureOptions, PageHelpers, Stopwatch, Parity, ParityIntent, ParityDescribeOptions, ExpectParityOptions, RangoMatchers, };
 export interface RangoE2E extends PageHelpers, Parity {
     useFixture: (options: FixtureOptions) => Fixture;

package/dist/types/testing/e2e/page-helpers.d.ts

@@ -43,6 +43,30 @@ export declare function measureTime<T>(fn: () => Promise<T>): Promise<{
     elapsed: number;
     result: T;
 }>;
+/**
+ * True when the request is a speculative prefetch (Link viewport/hover/render
+ * strategies or `useRouter().prefetch()`). Every prefetch fetch carries the
+ * `X-Rango-Prefetch` header. Links prefetch by default in production unless
+ * the router opts out, so tests that track `_rsc_partial` requests to pin
+ * NAVIGATION behavior must skip these — a request-count or first-request
+ * assertion otherwise races background prefetch traffic.
+ */
+export declare function isPrefetchRequest(req: {
+    headers: () => Record<string, string>;
+}): boolean;
+/**
+ * Abort every speculative prefetch request on this page. Install BEFORE
+ * `page.goto` so no prefetch can complete first. For tests whose semantics
+ * need a virgin prefetch cache: a click on a Link whose target was already
+ * prefetched ADOPTS the warmed entry and issues no navigation fetch at all —
+ * a `page.route` override, a request waiter, or a Set-Cookie assertion aimed
+ * at the navigation request then sees nothing (or sees the prefetch's side
+ * effects instead). Aborted prefetches are benign by design (evicted, never
+ * adopted, no page error), so the click's real fetch is guaranteed live.
+ */
+export declare function blockPrefetch(page: Page): Promise<void>;
+/** Remove a `blockPrefetch` guard, restoring normal prefetch traffic. */
+export declare function unblockPrefetch(page: Page): Promise<void>;
 export interface PageHelpers {
     /** Assert that no full page reload occurred between scope entry and exit. */
     expectNoReload: (page: Page) => AsyncDisposable;

package/dist/types/testing/index.d.ts

@@ -44,8 +44,8 @@ export type { DispatchOptions } from "./dispatch.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";
 export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
 export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";
-export { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
-export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
+export type { PprReplayBypassReason, PprReplayStatus, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
 export { collectHandle } from "./collect-handle.js";
 export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";
 export type { GeneratedRoutesDiff, GeneratedRouteMismatch, } from "./generated-routes.js";

package/dist/types/testing/run-transition-when.d.ts

@@ -1,10 +1,9 @@
 /**
  * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
  *
- * Runs the SAME two server functions the router uses — applyViewTransitionDefault
- * (strips the `when` function from the serialized config and records the
- * predicate on the request context) and gateTransitions (assembles the
- * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
+ * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
+ * function), and gateTransitions. So the
  * predicate sees exactly the navigation/action metadata it would at runtime
  * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
  * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
@@ -39,7 +38,7 @@ export interface RunTransitionWhenOptions<TEnv = any> {
     toRouteName?: string;
     /** Environment bindings surfaced as `env` (and `ctx.env`). */
     env?: TEnv;
-    /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+    /** Variables readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
     vars?: VarsInit;
     /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
     currentUrl?: string | URL;
@@ -57,6 +56,8 @@ export interface RunTransitionWhenOptions<TEnv = any> {
     formData?: FormData;
     /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
     onError?: OnErrorCallback;
+    /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
+    ppr?: boolean;
 }
 /**
  * Result of runTransitionWhen.