@rangojs/router 0.32.0 → 0.33.1

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

@@ -493,9 +493,12 @@ export interface RangoOptions<TEnv = any> {
      * TTL (in seconds) for the client-side in-memory prefetch cache.
      *
      * Controls how long prefetch responses are kept in the client-side
-     * in-memory cache. Prefetch responses carry no `Cache-Control`, so the
-     * browser's HTTP cache does not keep them: a prefetch whose render failed
-     * after its 200 went out would otherwise answer later requests.
+     * in-memory cache. A prefetch with nothing live in it (a document cache
+     * HIT, or every sent segment from a `cache()` record or a Prerender entry,
+     * with no loader) also carries `Cache-Control: private, max-age=<ttl>`,
+     * so the browser's HTTP cache keeps it as long. Any other prefetch carries
+     * none: a prefetch whose render failed after its 200 went out would
+     * otherwise answer later requests.
      *
      * The cache is automatically invalidated on server actions regardless
      * of TTL, so this is primarily a staleness safety net.

package/dist/types/router/segment-resolution/loader-cache.d.ts

@@ -61,6 +61,14 @@ export declare function bindsLoaderCache(entries: readonly EntryData[]): boolean
  * one is live (shell-capture.ts deriveShellCaptureContext).
  */
 export declare function routeLoaderLanes(entries: readonly EntryData[]): ReadonlyMap<string, "live" | "bake">;
+/**
+ * This request serves `loaderEntry` from a pin (servedPins), so its body does
+ * not decide the value: resolveLoaderData serves a pin to an `ssr: false`
+ * registration only. A prefetch does not defer such a loader
+ * (prefetch-deferral.ts defersLoader): nothing would run, and the pin is the
+ * value the document shows.
+ */
+export declare function servesLoaderPin(loaderEntry: LoaderEntry, reqCtx?: RequestContext<any> | undefined): boolean;
 /**
  * What a record restored on a request over the matched chain `entries` is to
  * each loader's handle pushes (HandleStore RecordAuthority), from the pins

package/dist/types/router/segment-resolution/prefetch-deferral.d.ts

@@ -30,11 +30,18 @@ import type { CacheScope } from "../../cache/cache-scope.js";
 /**
  * What a request says it is, read once when its context is created
  * (RequestContext._requestKind). A fill is marked on the raw URL and wins
- * over the prefetch header. Whether a prefetch defers anything is decided per
- * match, by partialDeferralMode: a shell capture inherits the context of the
- * request that scheduled it and is never a prefetch.
+ * over the prefetch header. `"prefetch"` is a speculative prefetch (viewport,
+ * render) and `"intent"` a hover or an explicit `prefetch()` call
+ * (PREFETCH_INTENT): both are prefetches, and only the first defers. Whether
+ * a prefetch defers anything is decided per match, by partialDeferralMode: a
+ * shell capture inherits the context of the request that scheduled it and is
+ * never a prefetch.
  */
-export declare function requestKind(request: Request, rawUrl: URL): "prefetch" | "fill" | undefined;
+export declare function requestKind(request: Request, rawUrl: URL): RequestKind | undefined;
+/** requestKind's answer for a marked request. */
+export type RequestKind = "prefetch" | "intent" | "fill";
+/** A prefetch of either kind: speculative or intent. */
+export declare function isPrefetchKind(kind: RequestKind | undefined): boolean;
 /** Static, per matched chain. */
 interface DeferralScope {
     /**
@@ -158,7 +165,9 @@ export declare function resolveDeferralScope(entries: readonly EntryData[]): Def
 export declare function resolveInterceptDeferralScope(intercept: InterceptEntry): DeferralScope;
 /**
  * Which half of the feature a partial request is, if either (`fill` and
- * `prefetch` are requestKind's answer). Both halves are GETs: a request of
+ * `prefetch` are requestKind's answer). `prefetch` is a speculative prefetch
+ * only: an intent prefetch defers nothing, like the navigation it starts
+ * early (R16). Both halves are GETs: a request of
  * another method that carries either marker is a normal request. A prefetch
  * defers only on a plain GET navigation: an action re-renders what it
  * changed, and a shell capture is never a prefetch whatever the request that
@@ -234,7 +243,7 @@ export declare function startDeferredLoader(ctx: HandlerContext<any, any>, loade
 /**
  * The segment a run of `loaderId` files its handle pushes under: the one
  * that registers it when it is registered (registerDeferredLoader), else the
- * segment being resolved.
+ * segment whose code starts it (segmentPinOf).
  */
 export declare function loaderOwner(ctx: HandlerContext<any, any>, loaderId: string): string | undefined;
 /**
@@ -242,8 +251,15 @@ export declare function loaderOwner(ctx: HandlerContext<any, any>, loaderId: str
  * does not hold that segment, and the loader is flagged itself or sits behind
  * the fallback of a flagged entry the client does not hold either. Under a
  * flagged layout the client holds, a new route's loaders run.
+ *
+ * `servesPin` (loader-cache.ts servesLoaderPin) answers whether this request
+ * serves the loader from a pin of a document-captured shell. Such a loader
+ * is not deferred: its body does not decide the value, and the pin is what
+ * the document shows. On every other request it would run, so it is
+ * deferred as on a route without ppr. Asked when loaders resolve, after a
+ * replay HIT has armed the pins (rsc-rendering.ts matchPartialWithPprReplay).
  */
-export declare function defersLoader(ctx: HandlerContext<any, any>, loaderEntry: LoaderEntry, segmentId: string): boolean;
+export declare function defersLoader(ctx: HandlerContext<any, any>, loaderEntry: LoaderEntry, segmentId: string, servesPin: (loaderEntry: LoaderEntry) => boolean): boolean;
 /**
  * This prefetch skips the handler of the entry whose segment is `segmentId`:
  * a unit the client does not hold, or anything the client does not hold

package/dist/types/router/segment-resolution/revalidation.d.ts

@@ -53,6 +53,25 @@ export interface LoaderOwner {
 }
 /** A route entry as a LoaderOwner, under `shortCodeOverride` when inherited. */
 export declare function ownerOf(entry: EntryData, shortCodeOverride?: string): LoaderOwner;
+/**
+ * A route's loader copies inherited into a child layout with parallel slots
+ * are redundant beside the route's own loader segments: true when the route
+ * renders no loading() fallback on any request, so nothing hides the route's
+ * copy from useLoader() in the slots. A redundant copy is never resolved, on
+ * any request: the walkers check this before they inherit.
+ *
+ * Decided from the entry, never from the route segment's `loading`, which
+ * differs between requests: `loading(fallback, { ssr: false })` is `null` on
+ * a document (applyDocumentModeLoading) and the fallback on partials, and the
+ * walkers emit `loading(false)` as `null` too. A copy sent on one request and
+ * not on the next gives the layout a loader entry it did not have, so
+ * renderSegments wraps it in StreamedLoaderErrorBoundary and React remounts
+ * it with its Outlet (docs/tree-structure.md). Resolving a redundant copy and
+ * dropping it from the payload later is not enough: when the route's own
+ * loader is held (its revalidate() declines), the copy is new to the client,
+ * so it re-runs and is sent without the route's copy beside it.
+ */
+export declare function inheritedCopyRedundant(route: EntryData): boolean;
 /**
  * The walker's one loader funnel: each loader is a segment, run when the
  * client lacks it, asked its revalidate() when held, kept outright in a fill

package/dist/types/router/source-reads.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Recording what revalidate() rules read of the source page, so a prefetch
+ * answer a rule kept is shared between the pages with equal values of what
+ * was read (prefetch-source-scope.ts).
+ */
+import { type SourcePage, type SourceReads } from "../prefetch-source-scope.js";
+/**
+ * The source group of a match whose diff a source read decided: the reads
+ * every kept decision made, unioned, and the source page they read.
+ */
+export interface SourceHeld extends SourcePage {
+    reads: SourceReads;
+}
+/**
+ * A copy of `params` whose reads land in `reads`: an enumerable getter per
+ * key, so a spread, Object.entries, JSON.stringify or structuredClone reads
+ * every key. Not a Proxy: structuredClone refuses one. A read of an absent
+ * key is not recorded and needs no record: the key set is part of the group
+ * (`reads.keys`), so a page in the group lacks that key too.
+ */
+export declare function recordingParams(params: Readonly<Record<string, string>>, reads: SourceReads): Record<string, string>;
+/**
+ * Add `reads` to the source group of the match `context` decides for. All
+ * of one match's decisions read the same source page; a caller that reads
+ * no route name passes none.
+ */
+export declare function markSourceHeld(context: {
+    _sourceHeld?: SourceHeld;
+}, reads: SourceReads, page: SourcePage): void;
+/**
+ * The `x-rsc-prefetch-scope` of a partial response, or undefined when every
+ * source page may share it.
+ *
+ * - `source`: the exact source page's. A route an intercept targets renders
+ *   the modal or the full page depending on the source, so a full page
+ *   prefetched where the intercept does not apply would otherwise serve a
+ *   later click where it does (#1007); a response with deferred units
+ *   answers one page's prefetch (`sourceOnly`); a kept rule that read
+ *   `currentUrl` can depend on anything in it; and a source-held answer that
+ *   sends nothing (`sentNothing`) commits treeless on the page that adopts
+ *   it, which keeps its whole tree without checking it holds the ids the
+ *   answer kept (partial-update.ts): only the source is known to hold them.
+ * - `params; <label>`: a revalidate() rule read the source's params or route
+ *   name and kept a segment. A page that adopted the answer would keep its
+ *   own copy of that segment (#1331), which is right only where the rule
+ *   decides the same: on pages with equal values of what it read. The label
+ *   names them (prefetch-source-scope.ts); the browser stores the answer
+ *   under it. A page that lacks a kept id refetches (the commit's
+ *   missing-segment check), as for a shared answer.
+ */
+export declare function prefetchScopeOf(sourceOnly: boolean, held: SourceHeld | undefined, sentNothing: boolean): string | undefined;
+/** Every param of the source read: its params must equal the page's. */
+export declare function readsOfAllParams(params: Readonly<Record<string, string>>): SourceReads;

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

@@ -60,7 +60,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
 export interface MatchApiDeps<TEnv = any> {
     findMatch: (pathname: string, ms?: any) => any;
     getMetricsStore: () => any;
-    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext | null, isAction: boolean) => {
+    findInterceptForRoute: (routeKeys: string | readonly string[], parentEntry: EntryData | null, selectorContext: InterceptSelectorContext | null, isAction: boolean, held?: ReadonlySet<string>) => {
         intercept: InterceptEntry;
         entry: EntryData;
     } | null;

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

@@ -4,6 +4,7 @@
  * Utility functions for RSC request handling.
  */
 import type { RequestContext } from "../server/request-context.js";
+import { type LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import type { RscPayload } from "./types.js";
 import type { HandlerContext } from "./handler-context.js";
@@ -98,9 +99,11 @@ export declare function interceptRedirectForPartial(response: Response, createRe
  * is populated. A `document` payload (a page load's or a no-JS form post's
  * bootstrap payload) that carries state marks the request
  * `_documentLocationState`: it is the visitor's, so no shared cache keeps it
- * (server/document-location-state.ts).
+ * (server/document-location-state.ts). `locationState` defaults to the
+ * current request context's; a shell HIT's tail passes the state set before
+ * its render (rsc/rsc-rendering.ts serveShellHit).
  */
-export declare function attachLocationStateIfPresent(payload: RscPayload, document?: boolean): void;
+export declare function attachLocationStateIfPresent(payload: RscPayload, document?: boolean, locationState?: LocationStateEntry[] | undefined): void;
 /**
  * Only cache successful responses. Non-200 statuses (errors, redirects) are
  * not cached -- notFound() produces 500 in response routes, and explicit

package/dist/types/rsc/prefetch-render-error.d.ts

@@ -11,8 +11,13 @@
  * So the body ends cleanly with one more row, PREFETCH_FAILED_ROW, which the
  * Flight decoder skips and teeWithCompletion (browser/response-adapter.ts)
  * reads as a stream that did not end cleanly: the client evicts the prefetch
- * and never respawns it. Prefetch responses carry no Cache-Control, so the
- * browser HTTP cache keeps none of it either.
+ * and never respawns it. The router puts no Cache-Control of its own on a
+ * prefetch with a live part, the only kind whose render can report an error
+ * here, so the browser HTTP cache keeps none of it unless the route sets one;
+ * a prefetch with nothing live in it carries `private, max-age`
+ * (request-stages.ts applyStoredPrefetchCacheControl); a prefetch
+ * scoped to its source page or carrying deferred units is sent
+ * `private, no-cache` (rsc-rendering.ts NOT_REUSED).
  *
  * The errors are the render's `_renderErrors`: a Flight error row, a streamed
  * handler recovered into its boundary, a loader that threw (redirect() and

package/dist/types/rsc/request-stages.d.ts

@@ -38,6 +38,8 @@ export interface StageRouter<TEnv = unknown> {
     readonly onTimeout?: OnTimeoutCallback<TEnv>;
     /** Names the cookie location state crosses a document redirect in. */
     readonly resolvedStateCookieName: string;
+    /** The in-memory prefetch TTL in ms; also a stored prefetch's max-age. */
+    readonly prefetchCacheTTL: number;
 }
 /** Report an error through the router's onError. */
 export type ReportError<TEnv = unknown> = (error: unknown, phase: ErrorPhase, context: InvokeOnErrorContext<TEnv>) => void;

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

@@ -99,8 +99,13 @@ export declare function withoutShellMissMarker(request: Request): Request | unde
  * the page. window.stop() runs only when it reloads: it keeps the half-sent
  * Flight stream from being closed by DOMContentLoaded, which would throw
  * React's "Connection closed" (#412) before the reload lands.
+ *
+ * `restoreCookie` is the request's `_carriedLocationStateCookie`: the HIT's
+ * headers already cleared the location state cookie a document redirect left
+ * (server/document-location-state.ts), so the script sets it again before it
+ * reloads, and the reload carries the state.
  */
-export declare function shellReloadScript(): string;
+export declare function shellReloadScript(restoreCookie?: string): string;
 /**
  * An inline script a shell HIT's tail appends. It carries no CSP nonce: a
  * request with an active per-request nonce never reaches a HIT

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

@@ -92,9 +92,10 @@ export type EntryPropRender = {
     loading?: ReactNode | false;
     /**
      * loading(fallback, { prefetch: false }) with a renderable fallback: a
-     * prefetch defers what the fallback covers while the entry's segment is
-     * new to the client (router/segment-resolution/prefetch-deferral.ts). Set
-     * on both DSL evaluations, whatever `ssr` did to `loading`.
+     * speculative prefetch defers what the fallback covers while the entry's
+     * segment is new to the client
+     * (router/segment-resolution/prefetch-deferral.ts). Set on both DSL
+     * evaluations, whatever `ssr` did to `loading`.
      */
     loadingPrefetch?: false;
     /**
@@ -136,8 +137,8 @@ export type LoaderEntry = {
      */
     bake?: true;
     /**
-     * loader(Def, { prefetch: false }): a prefetch defers this registration
-     * while its segment is new to the client
+     * loader(Def, { prefetch: false }): a speculative prefetch defers this
+     * registration while its segment is new to the client
      * (router/segment-resolution/prefetch-deferral.ts).
      */
     prefetch?: false;
@@ -174,7 +175,10 @@ export type InterceptSegmentsState = {
  * @internal This type is an implementation detail and may change without notice.
  */
 export type InterceptSelectorContext<TEnv = any> = {
-    /** Where the navigation comes from: the intercept source while one is open. */
+    /**
+     * Where the navigation comes from: the intercept source while one is open.
+     * Its `url` never carries a #fragment.
+     */
     from: ServerRouteLocation;
     /** The navigation target. */
     to: ServerRouteLocation;
@@ -818,6 +822,19 @@ export declare function findEnclosingLoaderBody(match: (loaderId: string) => boo
  * reader runs in that request only reaches the page through the replay.
  */
 export declare function isInsideLoaderBody(loaderId: string): boolean;
+/**
+ * Run `fn` as segment `segmentId`'s code: a handle push, a loader kickoff or
+ * a "use cache" call it makes, before or after an await, files under
+ * `segmentId` (segmentPinOf).
+ */
+export declare function runAsSegment<R>(segmentId: string | undefined, fn: () => R): R;
+/**
+ * The segment code here runs for: the innermost runAsSegment scope, else
+ * `ctx`'s pin (a handler the walker awaits).
+ */
+export declare function segmentPinOf(ctx: {
+    _currentSegmentId?: string;
+}): string | undefined;
 /**
  * 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

package/dist/types/server/cookie-store.d.ts

@@ -134,7 +134,21 @@ export declare function invalidateClientCache(): void;
  *
  * Sets an internal response header the bridge reads. Idempotent within a
  * request. Inert (a dev warning) outside a request context — there is no
- * automatic invalidation to suppress.
+ * automatic invalidation to suppress. It also keeps the state's write part
+ * (runActionBody).
  */
 export declare function keepClientCache(): void;
+/**
+ * Run a server action's body (the JS call or a no-JS form post), then bump the
+ * rango state's write part for the client that called it: the response's
+ * state `Set-Cookie` keeps the client's timestamp and carries a new write part
+ * (browser/cookie-name.ts). Every later request of every tab and reload sends
+ * the new `X-Rango-State`, so a prefetch or navigation the browser HTTP cache
+ * holds from before the write (a response's own `Cache-Control: max-age`)
+ * misses, while the client's in-memory caches only go stale, as the action
+ * bridge marks them. Bumped however the body ends (returned, threw, or
+ * redirected), since the write may have committed either way, and not after
+ * keepClientCache() or invalidateClientCache() (whose rotation covers it).
+ */
+export declare function runActionBody<T>(body: () => T | Promise<T>): Promise<T>;
 export {};

package/dist/types/server/document-location-state.d.ts

@@ -14,7 +14,10 @@
  *   reads it on the next GET document request that navigates to the target
  *   pathname (`Sec-Fetch-Dest` a browsing context, where sent), seeds
  *   `_locationState` with its entries (so the render attaches them to the
- *   bootstrap payload, rsc/rsc-rendering.ts) and clears it.
+ *   bootstrap payload, rsc/rsc-rendering.ts) and clears it. A shell HIT that
+ *   degrades into a reload after its headers cleared the cookie sets it
+ *   again from script first (`_carriedLocationStateCookie`), so the reload
+ *   carries the state.
  *
  * A document that carries location state is per visitor: it is marked
  * `_documentLocationState`, never stored by the document cache or as a PPR
@@ -38,7 +41,7 @@ export declare function documentLocationStateCookieName(stateCookieName: string,
  * expiry. A malformed value is cleared and ignored, and only `__rsc_ls_*`
  * slots are taken from it (the value comes from the browser).
  */
-export declare function consumeDocumentLocationState(reqCtx: Pick<RequestContext, "_locationState" | "setCookie">, request: Request, url: URL, stateCookieName: string): void;
+export declare function consumeDocumentLocationState(reqCtx: Pick<RequestContext, "_locationState" | "_carriedLocationStateCookie" | "setCookie">, request: Request, url: URL, stateCookieName: string): void;
 /**
  * Write the cookie on a document request's redirect that set location state,
  * and mark the redirect private. Not for a partial or action request (their

package/dist/types/server/handle-store.d.ts

@@ -158,6 +158,8 @@ export interface HandleStore {
      * so a loader that throws or skips its push shows none rather than the
      * record's. A hole's replays go with them. Any other loader's replays stay
      * (a dependency another entry's HIT replayed), and so do restored copies.
+     * A prefetch that defers the loader calls it too (revalidation.ts
+     * resolveOwnerLoaders): no run is made, so none of its placeholders stand.
      */
     settleLoaderRun(loaderId: string): void;
     /**

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

@@ -31,6 +31,7 @@ import type { RoutineTrace } from "../rsc/routine-plan.js";
 import type { ActionContinuation } from "../rsc/server-action.js";
 import type { ShellCaptureState } from "../rsc/shell-capture.js";
 import type { FormActionOutcome } from "../rsc/progressive-enhancement.js";
+import { type RequestKind } from "../router/segment-resolution/prefetch-deferral.js";
 import { type ExecutionStart } from "../cache/invalidation-order.js";
 export interface RenderForegroundCursor {
     mode: RenderMode;
@@ -119,8 +120,12 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     setStatus(status: number): void;
     /** @internal Set status bypassing cache-exec guard (for framework error handling) */
     _setStatus(status: number): void;
-    /** @internal Rotate the rango state cookie (server seat of invalidateClientCache). */
-    _rotateStateCookie(): void;
+    /**
+     * @internal Rotate the rango state cookie: its timestamp (the server seat of
+     * invalidateClientCache), or with `"write"` only its write part (a server
+     * action without a directive, cookie-store.ts runActionBody).
+     */
+    _rotateStateCookie(part?: "write"): void;
     /** @internal Set the keepClientCache() directive header on the response. */
     _setKeepCacheDirective(): void;
     /**
@@ -532,11 +537,28 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _payloadDeferred?: boolean;
     /**
-     * @internal What the request says it is: a `<Link>` prefetch or a fill
-     * (`prefetch: false`), read once at creation
-     * (segment-resolution/prefetch-deferral.ts requestKind).
+     * @internal Set by the RSC handler when a partial response carries an
+     * `x-rsc-prefetch-scope` (router/source-reads.ts prefetchScopeOf): its diff
+     * is right for its source page, or a group of them, only. The document
+     * cache keys a partial without its source, so it does not store that
+     * response, whatever Cache-Control it ends up with.
      */
-    _requestKind?: "prefetch" | "fill";
+    _payloadSourceScoped?: boolean;
+    /**
+     * @internal Set when the answer has nothing live in it, so nothing in it can
+     * fail after the 200's headers left: the document cache middleware on a
+     * fresh HIT, and the RSC handler when the partial match came from storage
+     * (MatchResult.fromStorage). finalizeRequestResponse (rsc/request-stages.ts)
+     * sends such a prefetch the router's prefetch Cache-Control.
+     */
+    _servedFromStorage?: boolean;
+    /**
+     * @internal What the request says it is: a speculative `<Link>` prefetch,
+     * an intent prefetch (hover, `prefetch()`) or a fill (`prefetch: false`),
+     * read once at creation (segment-resolution/prefetch-deferral.ts
+     * requestKind).
+     */
+    _requestKind?: RequestKind;
     /**
      * @internal Set when a render shows the visitor's URL of a rewritten
      * request: the payload or SSR seed (renderedLocation, rsc/full-payload.ts)
@@ -558,6 +580,11 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * `Cache-Control: private, no-store` and never stored by the document cache
      * or as a PPR shell.
      *
+     * Call it from middleware, a handler or an action. A loader's call
+     * (through `getRequestContext()`) is not supported: the payload takes the
+     * state before loaders settle, so the write may be dropped, and a PPR
+     * shell HIT never sends it.
+     *
      * Multiple calls accumulate entries across definitions. For one definition
      * the last write wins: two entries of the same definition share its slot
      * in history.state, so a later call (or a later entry in one array)
@@ -579,6 +606,15 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * and it leaves `private, no-store` (server/document-location-state.ts).
      */
     _documentLocationState?: boolean;
+    /**
+     * @internal The `document.cookie` line that re-creates the location state
+     * cookie this request consumed (server/document-location-state.ts). The
+     * consuming response clears the cookie in its headers; a shell HIT that
+     * degrades into a reload after those headers left writes this line first
+     * (rsc/shell-serve.ts shellReloadScript), so the reload reads the state
+     * again.
+     */
+    _carriedLocationStateCookie?: string;
     /**
      * The matched route name, if the route has an explicit name.
      * Undefined before route matching or for unnamed routes.
@@ -812,7 +848,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" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureState" | "_shellImplicitCache" | "_shellLoaderSeed" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_shellFragmentPayload" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_documentLocationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_throwers" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_handlerTiming" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureState" | "_shellImplicitCache" | "_shellLoaderSeed" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_shellFragmentPayload" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadSourceScoped" | "_servedFromStorage" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_documentLocationState" | "_carriedLocationStateCookie" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_throwers" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_handlerTiming" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_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/server.d.ts

@@ -11,7 +11,13 @@ export interface RunCliHandle {
      */
     exitCode: Promise<number | null>;
     findPort: (timeoutMs?: number) => Promise<number>;
-    kill: () => void;
+    /**
+     * Stop the process and what it spawned (the whole process group). SIGTERM by
+     * default; `stopServer` escalates to SIGKILL for a process that outlives the
+     * wait.
+     */
+    kill: (signal?: NodeJS.Signals) => void;
+    readonly pid: number | undefined;
     stdout: () => string;
     stderr: () => string;
 }
@@ -19,6 +25,15 @@ export declare function runCli(options: {
     command: string;
     label?: string;
 } & SpawnOptions): RunCliHandle;
+/**
+ * Stop a server started by `runCli` and wait for its whole process group to
+ * exit: SIGTERM to the group, then SIGKILL (and a log naming the pid) for a
+ * process that outlives the wait, so a leaked server is visible rather than
+ * left holding its port.
+ */
+export declare function stopServer(server: RunCliHandle, options?: {
+    exitWaitMs?: number;
+}): Promise<void>;
 export declare function tailOutput(text: string, maxChars?: number): string;
 export declare function createIsolatedViteCacheDir(cwd: string, projectName: string, mode: "dev" | "build" | undefined): string;
 export declare function waitForReady(url: string, getOutput?: () => {

package/dist/types/testing/render-route.d.ts

@@ -35,6 +35,16 @@
  *     not modeled). navigate(url, { streamUntil }) gives the navigation a
  *     response stream that stays open past the commit (isStreaming).
  *     useAction().state stays idle: no action runs.
+ *   - prefetch(url) keeps a page as a prefetch made now carries it, and
+ *     action() lands a server action's response: the page on screen
+ *     re-renders with its post-write loader data, and, without
+ *     `keepClientCache`, production's store marks every history entry and
+ *     prefetch stale (browser/navigation-store.ts). A navigate(url) to a
+ *     prefetched page commits the prefetch's data; when an action made it
+ *     stale, the page then revalidates once the navigation settled, in the
+ *     lane production's Back uses (useNavigation() idle), with the loader
+ *     data current then. The prefetch request, its decode and the HTTP cache
+ *     are e2e territory.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
  *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
@@ -49,8 +59,8 @@
  *     written there, and another page is on screen, its page is restored
  *     from the history cache, with the handle values it had, as production's
  *     restore is; otherwise the tree keeps its location. A stale entry's
- *     revalidation, a restore that fetches, a server action's state, a
- *     redirect's and an intercept's are e2e territory.
+ *     revalidation on Back, a restore that fetches, a server action's
+ *     location state, a redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
@@ -420,6 +430,60 @@ export interface TestRouterHandle {
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
      */
     refresh(): Promise<void>;
+    /**
+     * Prefetch `url`, as a `<Link>` hover or viewport trigger does: the page is
+     * kept with the loader data its response would carry now (the render-time
+     * seeds, `options.loaders` merged over). A later `navigate(url)` without
+     * `loaders` commits that data, whatever the seeds are by then.
+     *
+     * The prefetch is stamped with production's stale epoch
+     * (browser/prefetch/cache.ts): an `action()` without `keepClientCache`
+     * makes it stale. A click on a stale prefetch commits it at once, then the
+     * page revalidates once the navigation settled (its `streamUntil` ended),
+     * in Back's stale-revalidation lane: `useNavigation().state` stays "idle"
+     * and `isNavigating` reads true while its request is open, `useLinkStatus`
+     * shows no pending state, and the commit runs through commitInTransition
+     * with kind "revalidate", reading the loader data current then. A newer
+     * navigation aborts it.
+     *
+     * @example
+     * router.prefetch("/cart"); // carries count 2
+     * await router.action({ loaders: [[BasketLoader, { count: 3 }]] });
+     * await router.navigate("/cart"); // count 2, at once
+     * await waitFor(() => expect(count()).toBe("3")); // revalidated
+     */
+    prefetch(url: string, options?: Pick<RenderRouteOptions, "loaders">): void;
+    /**
+     * Land a server action's response on the page on screen. `loaders` are the
+     * loader values after the action's write: they become the data every
+     * later response carries, and the page on screen re-renders with them in
+     * the action lane (commitInTransition, kind "action", unless
+     * transition({ when }) gates it off). Without `keepClientCache`,
+     * production's store then marks every history entry and every prefetch
+     * stale (`markCacheAsStaleAndBroadcast()`), as the action bridge does:
+     * nothing is flushed and the state cookie is not rotated.
+     * `keepClientCache: true` is the `keepClientCache()` directive: caches stay
+     * fresh. The action's own lifecycle (`useAction()`), its follow-up and its
+     * redirect are e2e territory.
+     */
+    action(options?: Pick<RenderRouteOptions, "loaders"> & {
+        keepClientCache?: boolean;
+    }): Promise<void>;
+    /**
+     * The background revalidations a click on a stale prefetch started, in
+     * order: the page's pathname and search, and the segment ids the request
+     * holds, as production's bridge plans them
+     * (navigation-bridge.ts scheduleStalePrefetchRevalidation). A click on a
+     * fresh prefetch, or after a `keepClientCache` action, starts none.
+     *
+     * @example
+     * await router.navigate("/cart"); // a stale prefetch
+     * await waitFor(() => expect(router.revalidations()).toHaveLength(1));
+     */
+    revalidations(): ReadonlyArray<{
+        url: string;
+        segmentIds: string[];
+    }>;
     /** The current committed pathname. */
     pathname(): string;
     /** The current committed params. */

package/dist/types/testing/serve-shell-request.d.ts

@@ -65,9 +65,12 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * (default none), advertising fragment passthrough. The replay decision is
      * `result.replayStatus`.
      *
-     * `prefetch: true` sends it as a `<Link>` prefetch does (the
-     * `X-Rango-Prefetch` header), so `prefetch: false` loaders and `loading()`
-     * entries are deferred: `result.readDeferred()` lists them. `fill: true`
+     * `prefetch: true` sends the speculative kind a viewport or render
+     * `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false`
+     * loaders and `loading()` entries are deferred: `result.readDeferred()`
+     * lists them. A hover's or `prefetch()`'s intent prefetch defers nothing;
+     * serve it with `prefetch: true` and `headers: { "X-Rango-Prefetch":
+     * "intent" }`, which `prefetch: true` leaves as given. `fill: true`
      * sends the request the browser follows an adopted prefetch with
      * (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
      * ones, as `segments`, and the same URL as `from`. `interceptSource` sends

package/dist/types/types/handler-context.d.ts

@@ -400,11 +400,13 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
     /**
      * @internal A revalidate() predicate that read the source page
      * (`currentParams`, `currentUrl`, `fromRouteName`) kept a held segment, so
-     * this match's diff is right for that source only (#1331). Set by
-     * evaluateRevalidation (router/revalidation.ts); match-result.ts turns it
-     * into `sourceHeld`, which scopes a prefetch of the response to its source.
+     * this match's diff is right only for pages with equal values of what the
+     * kept decisions read (#1331). Set by evaluateRevalidation
+     * (router/revalidation.ts) and the stored-entry keep
+     * (match-middleware/cache-lookup.ts); match-result.ts turns it into
+     * `sourceHeld`, which scopes a prefetch of the response to that group.
      */
-    _sourceHeld?: true;
+    _sourceHeld?: import("../router/source-reads.js").SourceHeld;
     /**
      * @internal DSL loaders registered and not started, by `$$id`: a prefetch
      * deferred them, or a pass that skips loaders (`skipLoaders`) did not run
@@ -549,7 +551,7 @@ export type IsActionFn = (...actions: ActionRef[]) => boolean;
 export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
     /** Route params from the page being navigated away from. */
     currentParams: TParams;
-    /** Full URL of the page being navigated away from. */
+    /** Full URL of the page being navigated away from, without its #fragment. */
     currentUrl: URL;
     /** Route params for the navigation target. */
     nextParams: TParams;