@rangojs/router 0.31.0 → 0.33.0

package/dist/types/router/intercept-resolution.d.ts

@@ -7,20 +7,15 @@
 import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
 import type { ResolvedSegment } from "../types";
 import type { ResolutionPass } from "./segment-resolution/resolution-pass.js";
+import { type InterceptResult } from "./router-context.js";
 /**
  * Check if an intercept's when conditions are satisfied.
  * All when() functions must return true for the intercept to activate.
  * If no when() conditions are defined, the intercept always activates.
  * A selector that throws yields the conservative default, no intercept (the
  * full page renders), and is logged; it never fails the request.
- *
- * During action revalidation, when() is NOT evaluated.
- */
-export declare function evaluateInterceptWhen(intercept: InterceptEntry, selectorContext: InterceptSelectorContext | null, isAction: boolean): boolean;
-/**
- * Find an intercept for the target route by walking up the entry chain.
- * Returns the first (innermost) matching intercept along with the entry that defines it.
  */
+export declare function evaluateInterceptWhen(intercept: InterceptEntry, selectorContext: InterceptSelectorContext | null): boolean;
 /**
  * Collect every intercept TARGET route name reachable from an origin entry —
  * the same chain walk findInterceptForRoute() performs when this location is
@@ -33,10 +28,29 @@ export declare function evaluateInterceptWhen(intercept: InterceptEntry, selecto
  * loses its optimistic loading, never the reverse.
  */
 export declare function collectInterceptTargetNames(fromEntry: EntryData | null): string[];
-export declare function findInterceptForRoute(targetRouteKey: string, fromEntry: EntryData | null, selectorContext?: InterceptSelectorContext | null, isAction?: boolean): {
-    intercept: InterceptEntry;
-    entry: EntryData;
-} | null;
+/**
+ * The intercept for the target route, with the entry that declares it.
+ * `targetRouteKeys` are the names it may be declared for, in precedence
+ * order: the route's own name, then its local name inside include()
+ * (match-api.ts). A navigation, or an action with no `held`, takes the first
+ * along the chain from `fromEntry` up under the first name that has one: on a
+ * navigation, the first whose when() passes; on an action, the first, when()
+ * not evaluated.
+ *
+ * An action given `held` (the request's segment ids) re-renders the intercept
+ * on screen: one whose slot id the client holds, null when it holds none. Its
+ * candidates are collected under every name in one walk, the route's own
+ * name's first: a held id under the own name (a parallel() default of the
+ * slot's name) must not win before the local name is looked at. One held:
+ * that one, when() not evaluated, so an open intercept stays open when its
+ * when() would now reject. Several held (intercepts on one entry that fill one
+ * slot share its id, as does a parallel() slot of that name): the ones whose
+ * slot has no parallel() default on their entry, if any (a default holds its
+ * slot id whether or not an intercept is open there). One left: that one,
+ * when() not evaluated. Else the first whose when() passes against the
+ * action's intercept source, else the first.
+ */
+export declare function findInterceptForRoute(targetRouteKeys: string | readonly string[], fromEntry: EntryData | null, selectorContext?: InterceptSelectorContext | null, isAction?: boolean, held?: ReadonlySet<string>): InterceptResult | null;
 /** The segment id of `intercept`'s slot on `parentEntry`. */
 export declare function interceptSlotId(parentEntry: EntryData, intercept: InterceptEntry): string;
 /**

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

@@ -177,6 +177,7 @@ export interface MatchPipelineState {
     cachedSegments?: ResolvedSegment[];
     cachedMatchedIds?: string[];
     shouldRevalidate?: boolean;
+    storedStale?: boolean;
     cacheSource?: "runtime" | "prerender";
     segments: ResolvedSegment[];
     matchedIds: string[];

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

@@ -11,7 +11,7 @@ export interface MatchHandlerDeps<TEnv = any> {
     matchApiDeps: MatchApiDeps<TEnv>;
     defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined;
     findMatch: (pathname: string, ms?: any) => 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/router/middleware-types.d.ts

@@ -56,6 +56,12 @@ export interface MiddlewareContext<TEnv = any, TParams = Record<string, string |
      */
     readonly theme?: Theme;
     setTheme?: (theme: Theme) => void;
+    /**
+     * Attach location state entries to this response (see the handler
+     * context's `setLocationState`). Entries accumulate across definitions;
+     * for one definition the last write wins. Set it here rather than in a
+     * handler on a `ppr` route: a shell HIT runs no handler.
+     */
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
     /** Global route names only; see {@link GlobalReverseFunction}. */
     reverse: GlobalReverseFunction<DefaultReverseRouteMap>;

package/dist/types/router/prefetch-cache-ttl.d.ts

@@ -1,9 +1,10 @@
 /**
  * Resolve the prefetch cache TTL once, at router init, into the values the
  * rest of the router consumes: seconds, and milliseconds for the client-side
- * in-memory prefetch cache (shipped in payload metadata). Prefetch responses
- * carry no Cache-Control: the browser HTTP cache would keep a prefetch whose
- * render failed after its 200 went out (#1170).
+ * in-memory prefetch cache (shipped in payload metadata). A prefetch with a
+ * live part carries no Cache-Control: the browser HTTP cache would keep a
+ * prefetch whose render failed after its 200 went out (#1170). One answered
+ * from storage carries storedPrefetchCacheControl.
  *
  * `false` disables prefetch caching (seconds 0). A non-finite input
  * (NaN/Infinity, e.g. from an env-derived number that failed to parse) is
@@ -22,3 +23,10 @@ export interface ResolvedPrefetchCacheTTL {
     ms: number;
 }
 export declare function resolvePrefetchCacheTTL(rawTTL: number | false | undefined): ResolvedPrefetchCacheTTL;
+/**
+ * The Cache-Control of a prefetch answer with nothing live in it
+ * (`_servedFromStorage`): the browser HTTP cache keeps it as long
+ * as the in-memory prefetch cache would. Undefined when prefetch caching is
+ * off.
+ */
+export declare function storedPrefetchCacheControl(ttlMs: number): string | undefined;

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

@@ -33,7 +33,7 @@ export interface RouterContext<TEnv = any> {
     };
     getMetricsStore: () => MetricsStore | undefined;
     createCacheScope: (cacheConfig: any, parent: CacheScope | null) => CacheScope | null;
-    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext, isAction: boolean) => InterceptResult | null;
+    findInterceptForRoute: (routeKeys: string | readonly string[], parentEntry: EntryData | null, selectorContext: InterceptSelectorContext, isAction: boolean, held?: ReadonlySet<string>) => InterceptResult | null;
     /** The segment walker; a full match passes freshPassInput (FRESH). */
     resolveAllSegments: (pass: ResolutionPassInput<TEnv>, entries: EntryData[], walk: RevalidatingWalkOptions) => Promise<{
         segments: ResolvedSegment[];

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";
@@ -95,10 +96,14 @@ export declare function interceptRedirectForPartial(response: Response, createRe
 /**
  * Attach location state set during a request to a payload's metadata.
  * No-op if no location state was set. Callers must ensure payload.metadata
- * is populated (the non-null assertion holds for the partial/action payloads
- * that reach this helper).
+ * 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). `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): 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

@@ -36,6 +36,10 @@ export interface StageRouter<TEnv = unknown> {
     readonly telemetry?: TelemetrySink;
     readonly timeouts?: ResolvedTimeouts;
     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

@@ -0,0 +1,59 @@
+/**
+ * Location state on document responses (#1330).
+ *
+ * A client navigation or an action carries server-set location state in its
+ * Flight payload, and a redirect on either becomes a Flight redirect that
+ * carries it too. A document request has no such channel for a 3xx: the
+ * browser follows it with a plain GET. This module carries the state across
+ * that one hop in a short-lived cookie:
+ *
+ * - `carryLocationStateAcrossRedirect` (rsc/request-stages.ts
+ *   finalizeRequestResponse) writes it on a document request's same-origin
+ *   3xx when the request set location state;
+ * - `consumeDocumentLocationState` (rsc/request-stages.ts runRequestPasses)
+ *   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. 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
+ * shell, and leaves with `Cache-Control: private, no-store`
+ * (`markDocumentResponsePrivate`).
+ *
+ * The value is JSON, not Flight: a cookie holds text, and the client merges
+ * it as `history.state` would hold it. `Path=/` because the `__Host-` prefix
+ * (https) requires it, which keeps a sibling subdomain from planting state;
+ * the target pathname inside the value decides who consumes it.
+ */
+import { type RequestContext } from "./request-context.js";
+/** The cookie's name for a router: `__Host-` on https. */
+export declare function documentLocationStateCookieName(stateCookieName: string, secure: boolean): string;
+/**
+ * Read the cookie a document redirect left for this request: seed
+ * `_locationState` with its slots and clear it. Only a GET document request
+ * of the target pathname that navigates consumes it (the request the browser
+ * makes for a 301/302/303, see isNavigationRequest); any other request, a
+ * form POST to that path or a prefetch of it included, leaves it to its
+ * 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" | "_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
+ * redirect is a Flight payload), an external or cross-origin target (the
+ * cookie would never reach it) or a response that is not a 3xx with a
+ * Location. Returns the response to send: a new one when its headers are
+ * immutable.
+ */
+export declare function carryLocationStateAcrossRedirect(response: Response, reqCtx: Pick<RequestContext, "_locationState">, request: Request, url: URL, stateCookieName: string): Response;
+/**
+ * `Cache-Control: private, no-store` on a document that carries location
+ * state, after every middleware: a shared cache must never store or replay
+ * one visitor's state. Returns the response to send.
+ */
+export declare function markDocumentResponsePrivate(response: Response, reqCtx: Pick<RequestContext, "_documentLocationState">): Response;

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;
     /**