@rangojs/router 0.18.0 → 0.19.0

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

@@ -1,7 +1,7 @@
+import type { ServerRouteLocation } from "../types/segments.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ReactNode } from "react";
 import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn, TransitionConfig } from "../types";
-import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { ContextVar } from "../context-var.js";
 /**
  * Performance metric entry for a single measured operation
@@ -132,20 +132,22 @@ export type InterceptSegmentsState = {
  * Context passed to intercept selector functions (when())
  * Contains navigation context to determine if interception should occur.
  *
+ * `from` / `to` have the shape transition({ when }) sees, without `state`:
+ * history state never reaches the server.
+ *
  * Note: when() is evaluated during route matching, BEFORE middleware runs.
  * So ctx.get()/ctx.use() are not available, but env (platform bindings) is.
  *
  * @internal This type is an implementation detail and may change without notice.
  */
 export type InterceptSelectorContext<TEnv = any> = {
-    from: URL;
-    to: URL;
-    params: Record<string, string>;
+    /** Where the navigation comes from: the intercept source while one is open. */
+    from: ServerRouteLocation;
+    /** The navigation target. */
+    to: ServerRouteLocation;
     request: Request;
     env: TEnv;
     segments: InterceptSegmentsState;
-    fromRouteName?: DefaultRouteName;
-    toRouteName?: DefaultRouteName;
 };
 /**
  * Selector function for conditional interception
@@ -423,65 +425,82 @@ export declare function track(label: string, depth?: number): () => void;
  */
 export declare function isInsideCacheScope(): boolean;
 /**
- * Throw if called during the ACTIVE background shell-capture render
- * (`_shellCaptureRun` true on the derived request context built by
- * shell-capture.ts). The captured shell is shared across every user hitting
- * the URL, so a request-scoped read here would bake one user's cookies,
- * headers, or per-request variables into markup served to others — same
- * hazard as the cache scopes above, at the document tier. DSL segment loaders
- * need no exemption: the live lane is masked (never executed) during capture,
- * and the bake lane is exactly what this guard exists for.
- *
- * It covers everything the capture waits for, not only synchronous handler
- * code: a promise the handler passes or pushes, an async server component,
- * and a loader the handler awaits (`await ctx.use(Loader)`) all run under the
- * capture context and all bake. The last one used to be exempt (the
- * consumption-lane rule, #672/#674): while a HIT re-ran handlers, a slot
- * handler's `ctx.use` of an identity loader rendered per visitor on the HIT.
- * Now every HIT replays the capture's copy, so the exemption would bake the
- * capturing request's identity into every visitor's page. The cache()
- * guards above keep it (a cache() HIT is a separate tier).
- *
- * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
- * is also present during the FOREGROUND render (it means "a capture is wanted"),
- * and the foreground must read cookies/headers normally to serve the real user.
- * Only the derived capture context sets `_shellCaptureRun`.
+ * What a refused identity read says (guardIdentityRead): its `verb`, and per
+ * refusing scope the text after "<surface> cannot be <verb> ...": why the
+ * value must not reach that scope, and what to do instead. `fix.warning` is
+ * the fix the capture's refusal warning gives (shell-capture.ts
+ * refuseOnCaptureGuard).
+ */
+export interface IdentityReadWording {
+    /** "called" for a function (cookies(), ctx.get()), "read" for a property (the theme getters). */
+    verb: LoaderIdentityReadVerb;
+    fix: {
+        useCache: string;
+        cacheScope: string;
+        capture: string;
+        warning: string;
+    };
+    /**
+     * False when the read is recorded later, by the returned view's read
+     * methods (cookies(), headers()): a view taken outside a loader and read
+     * inside one still counts, and a cookie write alone is not a read.
+     */
+    record?: false;
+}
+/**
+ * The one guard every request-identity read goes through: cookies(),
+ * headers(), the theme reads (cookie-store.ts readGuardedTheme), a
+ * non-cacheable ctx.get() (assertNonCacheableReadAllowed), and the raw reads
+ * `ctx.request.headers` and `getRequestContext().cookie()` / `.cookies()`
+ * (cookie-store.ts guardRequestHeaders, guardRawCookieRead; #976). Each surface keeps
+ * its own wording; the ladder and its exemptions are shared, so the surfaces
+ * refuse in exactly the same places:
  *
- * Applies only to the READ surfaces (cookies(), headers(), a { cache: false }
- * variable, and the theme reads through tripShellCaptureGuard) whose values
- * become markup. Response directives
- * (invalidateClientCache(), keepClientCache()) stay callable: during capture
- * they are header effects on a discarded response, and on the live HIT path
- * the full pipeline runs so their headers flow to the client normally.
+ * 0. A cache's own key(), store keyGenerator, condition() and tags(), and
+ *    onError, read freely and record nothing (runIdentityExempt,
+ *    cache/cache-exec-scope.ts): the value picks or labels the entry, or is
+ *    only observed; it is never rendered. A cached body, loader body or
+ *    funnel they start is guarded again.
+ * 1. A PPR shell capture (`ctx` is the capture's derived context,
+ *    `_shellCaptureRun`) trips first: the capture context is flagged (so a
+ *    caught throw still refuses the capture) and the read throws. The shell is
+ *    shared per host+URL, and every HIT replays what the capture read. There
+ *    is no loader-body exemption here: a bake-lane loader and a loader a
+ *    handler awaits both bake.
+ * 2. A "use cache" body throws: the key does not include the value, so the
+ *    first caller's would be stored and served to later callers. That holds
+ *    for a loader body entered inside the cached function too (`await
+ *    ctx.use(Loader)` there): its value is part of what the function returns.
+ *    Before, a non-cacheable ctx.get() there was exempt while cookies() threw,
+ *    and the entry stored the first request's value.
+ * 3. A cache() boundary throws, except inside a loader body
+ *    (isInsideCacheScope): a route cache() never stores loader values.
+ * 4. The read is allowed, and recorded on the current loader execution for a
+ *    loader cache() fill without key() (#972, recordLoaderIdentityRead)
+ *    unless `wording.record` defers it to the returned view.
  *
- * The throw can be caught by the code that made the read, so the guard also
- * flags the capture context; the capture refuses on the flag
- * (shell-capture.ts refuseOnCaptureGuard), nothing is stored, and every
- * request keeps getting the normal axis-1 render.
+ * Outside these scopes every read is allowed, a live loader's included. The
+ * response directives (invalidateClientCache(), keepClientCache()) record
+ * nothing and are not captured reads: they take refuseInCacheScope alone.
+ */
+export declare function guardIdentityRead(ctx: unknown, surface: string, wording: IdentityReadWording): void;
+/**
+ * Steps 2 and 3 of guardIdentityRead: throw when a "use cache" body or a
+ * cache() boundary would store what `surface` produces.
  */
-export declare function assertNotInsideShellCapture(ctx: unknown, fnName: string): void;
+export declare function refuseInCacheScope(surface: string, { verb, fix }: IdentityReadWording): void;
 /**
- * True when `ctx` is the active capture render (assertNotInsideShellCapture
- * above). On true the capture context is flagged with the read (`surface`,
- * e.g. "cookies()", "ctx.theme") and the fix the refusal warning gives, plus
- * the loader body (if any) that made the read, and the caller throws.
+ * The capture refusal for a request-scoped read (cookies(), headers(), a
+ * { cache: false } variable): the message after the surface, and the fix the
+ * refusal warning gives. `what` names the data that would leak.
  */
-export declare function tripShellCaptureGuard(ctx: unknown, surface: string, fix: string): boolean;
+export declare function requestReadCaptureFix(what: string): Pick<IdentityReadWording["fix"], "capture" | "warning">;
 /**
  * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
- * `ctx.set(..., { cache: false })` write). Callers check isNonCacheable() first
- * so ordinary reads never reach the scope lookups.
- *
- * Throws during a PPR shell capture (`requestCtx` is the ambient request
- * context; assertNotInsideShellCapture): the shell is shared per host+URL.
- *
- * Throws inside a "use cache" body: the key does not include the value, so the
- * first caller's value would be stored and served to later callers (#925). A
- * loader body entered INSIDE the cached function is exempt, the same baked-copy
- * trade isInsideCacheScope() makes for cache(). A cached function called FROM a
- * loader is not: the loader re-runs, the cached body does not. The body scope
- * records the exec scope it was entered in, so the exemption holds only while
- * that is still the innermost one.
+ * `ctx.set(..., { cache: false })` write), through guardIdentityRead.
+ * Callers check isNonCacheable() first so ordinary reads never reach the
+ * scope lookups. `requestCtx` is the ambient request context, whose capture
+ * flag the guard reads.
  */
 export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>, requestCtx?: unknown): void;
 /** How the identity error words a read: a function call or a property read. */
@@ -608,10 +627,12 @@ export declare function assertCachedHeaderWriteAllowed(surface: string, surfaceP
 export declare function runInsideLoaderScope<T>(fn: () => T): T;
 /**
  * Run `fn` inside a loader BODY scope. Marks loader-function execution for the
- * cache-purity guard only (isInsideCacheScope), WITHOUT affecting
+ * cache() purity guard only (isInsideCacheScope), WITHOUT affecting
  * isInsideLoaderScope()/rendered() gating. Applied to every loader body (DSL
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
- * never trip the cache-scope guards — loaders always run fresh.
+ * never trip the cache() guard — a route cache() never stores loader values.
+ * A "use cache" body the loader was entered in still refuses them
+ * (guardIdentityRead).
  */
 export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, tags?: Set<string>): T;
 /** The innermost loader body's execution tag set (runInsideLoaderBodyScope). */
@@ -619,12 +640,19 @@ export declare function getLoaderBodyTags(): Set<string> | undefined;
 /**
  * The $$id of the loader whose body is currently executing, or undefined
  * outside any loader body. Used by the shell-capture identity guard
- * (assertNotInsideShellCapture) so its refusal warning can name the loader that read
+ * (guardIdentityRead) so its refusal warning can name the loader that read
  * cookies()/headers() instead of blaming a lane it cannot see — the old
  * hardcoded "bake-lane loader" text misled a live-lane debugging session
  * (issue #672, secondary).
  */
 export declare function getCurrentLoaderBodyId(): string | undefined;
+/**
+ * The innermost loader body running here, or around it through the
+ * ctx.use(Loader) chain, whose id `match` accepts (HandleStore.push, the
+ * shell capture's push funnel). A body `stop` accepts, and `match` does not,
+ * ends the walk: nothing around it is returned.
+ */
+export declare function findEnclosingLoaderBody(match: (loaderId: string) => boolean, stop?: (loaderId: string) => boolean): string | undefined;
 /**
  * True while `loaderId`'s body, or a loader it awaits via ctx.use at any
  * depth, is executing. The loader-level cache records these pushes

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

@@ -7,6 +7,8 @@
  * Writes append Set-Cookie to the response stub.
  */
 import type { CookieOptions } from "../router/middleware-types.js";
+import type { Theme } from "../theme/types.js";
+import { type RequestContext } from "./request-context.js";
 /**
  * A single cookie entry returned by get() and getAll().
  */
@@ -63,27 +65,37 @@ export interface ReadonlyHeaders {
     [Symbol.iterator](): HeadersIterator<[string, string]>;
 }
 type HeadersIterator<T> = IterableIterator<T>;
-/** The public reads of the visitor's theme cookie that assertThemeReadAllowed guards. */
+/**
+ * Run the identity guard for a raw cookie read on `ctx`
+ * (request-context.ts `cookie()` / `cookies()`). Before #976 they were plain
+ * reads of the Cookie header that no shared scope refused. The guard reads
+ * the ambient context, as cookies() does, and falls back to `ctx`.
+ */
+export declare function guardRawCookieRead(ctx: RequestContext<any>, surface: "getRequestContext().cookie()" | "getRequestContext().cookies()"): void;
+/**
+ * Guard `request.headers` like headers() (#976): the request every ctx
+ * exposes (request context, handler, middleware and loader `ctx.request`)
+ * gets an own getter that runs guardIdentityRead against the ambient request
+ * context, so a read inside a ppr capture, a cache() boundary, a "use cache"
+ * body or an unkeyed loader cache() fill refuses as cookies() does. A Request
+ * argument keys a "use cache" entry by its URL only (cache-runtime.ts), so a
+ * header read there baked the first caller's value into the shared entry.
+ * The router's own reads go through requestHeaders() (request-headers.ts).
+ * Idempotent; returns `request`.
+ */
+export declare function guardRequestHeaders(request: Request): Request;
+/** The public reads of the visitor's theme cookie that readGuardedTheme guards. */
 export type ThemeReadSurface = "ctx.theme" | "getRequestContext().theme";
 /**
- * Guard for a read of the visitor's theme: the handler and middleware
- * `ctx.theme` (handler-context.ts, middleware.ts) and `getRequestContext().theme`
- * (request-context.ts). The theme is the visitor's theme cookie, so it is an
- * identity read like cookies(): it refuses in the same scopes, in the same
- * order (refusingCacheScope, then tripShellCaptureGuard in context.ts), with
- * the same exemption (a loader body under cache(); at capture there is none).
- * Before #971 each read was a plain cookie read, so a ppr shell, a cache()
- * entry or a "use cache" entry stored the first visitor's theme and served it
- * to every later visitor.
- *
- * A read the guards allow is recorded on the current loader execution, as a
- * cookies() read method records it (#972, recordLoaderIdentityRead).
- *
- * `ctx` is the request context at read time, as cookies() reads it. The
- * router's own payload read (payloadInitialTheme, rsc/full-payload.ts) goes
- * through the unguarded `_readTheme()`.
+ * `ctx`'s theme through guardIdentityRead: the one body of every public theme
+ * read (the handler and middleware `ctx.theme`, handler-context.ts and
+ * middleware.ts, and `getRequestContext().theme`, request-context.ts). The
+ * guard reads the ambient context, as cookies() does, and falls back to
+ * `ctx`; the value is `ctx`'s unguarded `_readTheme()`, which the router's
+ * own payload read (payloadInitialTheme, rsc/full-payload.ts) calls directly.
+ * Undefined without a theme config.
  */
-export declare function assertThemeReadAllowed(ctx: unknown, surface: ThemeReadSurface): void;
+export declare function readGuardedTheme(ctx: RequestContext<any> | undefined, surface: ThemeReadSurface): Theme | undefined;
 /**
  * Get the original request headers (read-only).
  *

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

@@ -85,9 +85,60 @@ export interface HandleStore {
      * body (loader-cache.ts replayLoaderHandles). If that loader then runs live
      * in this request, its first push removes every value replayed for it and
      * takes the first one's position (later live pushes follow it), so the
-     * handle output stays live without a duplicate.
+     * handle output stays live without a duplicate. A push counts as that
+     * loader's when it is made in its body, or in a body it entered that has
+     * no replayed values of its own (the capture credits a dependency's push
+     * under a live-lane loader to that loader); a hole's run that ends without
+     * one drops them (settleLoaderRun).
      */
     pushReplayed(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
+    /**
+     * push() a document HIT's copy of `loaderId`'s settled push, restored from
+     * the shell's doc record (handle-snapshot.ts restoreHandles). The record is
+     * authoritative for that loader's settled pushes: the prelude was rendered
+     * from it, and a run of the loader on the HIT reads the store, not the
+     * capture's values. So from then on this request drops every settled,
+     * thenable-free push the loader makes (live, or replayed from a cache
+     * entry, anywhere inside its body), and keeps the ones holding a thenable
+     * (holdsThenable: what the record could not keep, `runs`), placed among the
+     * restored copies in the loader's push order. Only bake-lane owners are
+     * restored this way (withCacheLookup): a live-lane loader is a hole.
+     */
+    pushRestored(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
+    /**
+     * The loaders the route runs on the live lane (liveLaneLoaderIds), from a
+     * PPR shell record's restore (handle-snapshot.ts restoreHandles): the
+     * holes. A push counts for a restored loader when that loader is the
+     * replayed one or the innermost enclosing loader body that restored
+     * copies; the walk out through enclosing bodies stops at a hole's body,
+     * and a replay of a hole's push counts for none. So a restored loader
+     * never takes a push made inside a hole it awaited, while a body inside the
+     * hole that restored copies of its own (a dependency the capture ran under
+     * a bake-lane loader) still takes its pushes.
+     */
+    markLiveLane(loaderIds: ReadonlySet<string>): void;
+    /**
+     * `loaderId`'s run in this request settled (resolved or rejected), its
+     * pushes made (loader-resolution.ts createLoaderExecutor). When the loader
+     * is a hole (markLiveLane), values replayed for it that no push of the run
+     * replaced are dropped: the run's output decides, so a hole that throws or
+     * skips its push shows none rather than the capture's. Any other loader's
+     * replayed values stay: a bake-lane loader's record is authoritative for
+     * its settled pushes, as its pin is for its data. Restored copies are not
+     * replays and stand.
+     */
+    settleLoaderRun(loaderId: string): void;
+    /**
+     * A hole's own cache() HIT (loader-cache.ts replayLoaderHandles, once it
+     * claims the hole): the values replayed for hole `loaderId` before (its
+     * shell copies, which restoreHandles leaves unclaimed, those of the
+     * dependencies credited to it included) give way to the pushes the entry
+     * recorded, none when it recorded none, so they match the entry's data.
+     * `deliver` makes the pushReplayed calls, which take the removed values'
+     * place in each array. Any other loader, or a hole with nothing replayed,
+     * delivers as a plain replay.
+     */
+    redeliverReplays(loaderId: string, deliver: () => void): void;
     /**
      * Get all collected handle data after all handlers have settled.
      * Waits for `settled` (handler lane), then returns the data at that point.

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

@@ -22,11 +22,12 @@ import { type MetricsStore } from "./context.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
-import type { TransitionWhenFn } from "../types/segments.js";
+import type { TransitionWhenRecord } from "../router/transition-when.js";
 import type { ResolvedTracing } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RoutineTrace } from "../rsc/routine-plan.js";
+import { type ExecutionStart } from "../cache/invalidation-order.js";
 export interface RenderForegroundCursor {
     mode: RenderMode;
     phase: RenderPhase;
@@ -86,10 +87,24 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     dynamic(): void;
     /** @internal Request-local PPR opt-out marker set by ctx.dynamic(). */
     _dynamic?: boolean;
-    /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
+    /**
+     * @internal Get a cookie value (effective: request + response mutations).
+     * Use cookies().get() instead. Guarded like cookies() (#976).
+     */
     cookie(name: string): string | undefined;
-    /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
+    /**
+     * @internal Get all cookies (effective merged view). Use
+     * cookies().getAll() instead. Guarded like cookies() (#976).
+     */
     cookies(): Record<string, string>;
+    /**
+     * @internal `cookie()` without the identity guard: the read behind the
+     * cookies() store, which guards at its own call and records per read
+     * method. Non-enumerable, like `_readTheme`.
+     */
+    _readCookie(name: string): string | undefined;
+    /** @internal `cookies()` without the identity guard (see `_readCookie`). */
+    _readCookies(): Record<string, string>;
     /** @internal Set a cookie on the response. Use cookies().set() instead. */
     setCookie(name: string, value: string, options?: CookieOptions): void;
     /** @internal Delete a cookie. Use cookies().delete() instead. */
@@ -119,19 +134,18 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     /**
      * @internal The context createRequestContext() returned. A context derived
      * from it with Object.create (a PPR HIT tail, a shell capture, a background
-     * revalidation render) inherits it, so per-request invalidation state
-     * (tag-invalidation.ts, the stores' masks) is keyed by the request, not by
-     * whichever derived object called or read (#973).
+     * revalidation render) inherits it, so per-request invalidation state (the
+     * stores' masks) is keyed by the request, not by whichever derived object
+     * called or read (#973).
      */
     _requestRoot?: RequestContext<any, any>;
     /**
-     * @internal The tags this request invalidated with
-     * updateTag()/revalidateTag(), each with its position in the invalidation
-     * order (tag-invalidation.ts currentCacheSeq). Kept on _requestRoot. A
-     * "use cache" execution that started before one of its own tags was
-     * invalidated is neither joined nor written (cache-runtime.ts, #973).
+     * @internal Where the request started in the isolate's invalidation order
+     * (cache/invalidation-order.ts), taken when createRequestContext() ran. The
+     * document cache gates its write on it (#977): a middleware ahead of the
+     * document cache can read tagged data the document bakes.
      */
-    _tagInvalidations?: Map<string, number>;
+    _requestStart?: ExecutionStart;
     /**
      * @internal The handler has handed the response to the host (rsc/handler.ts
      * `rango.response`): header and cookie writes after this are lost, as from
@@ -171,18 +185,13 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     readonly _handleStore: HandleStore;
     /**
-     * @internal transition({ when }) predicates for segments matched this request,
-     * keyed by segment id. Collected during resolution (the function is stripped
-     * from the serialized segment config), then evaluated post-handler in
-     * rsc-rendering — outside any cache scope — to drop the transition of any
-     * segment whose predicate returns false.
+     * @internal transition({ when }) client references of the matched entry
+     * chain, keyed by segment id. Recorded at match time from the static route
+     * definition (router/transition-when.ts) and attached to the payload's
+     * segments right before Flight (rsc/attach-transition-when.ts). The server
+     * never calls them, and no cache or snapshot stores them.
      */
-    _transitionWhen?: Array<{
-        id: string;
-        when: TransitionWhenFn;
-    }>;
-    /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
-    _pprTransitionDecisions?: Map<string, boolean>;
+    _transitionWhenRefs?: ReadonlyMap<string, TransitionWhenRecord>;
     /**
      * @internal Post-match serve-source truth for the PPR replay reporter.
      * Stamped from the match context as `intercept`, then overwritten as
@@ -206,8 +215,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * capture task's derived request context (built by shell-capture.ts). This is
      * the switch every capture-specific behavior reads: loader masking
      * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
-     * cookies()/headers() capture guard (cookie-store.ts
-     * assertNotInsideShellCapture). The foreground render never sets it, so the
+     * identity-read capture guard (server/context.ts guardIdentityRead). The
+     * foreground render never sets it, so the
      * served response is byte-identical to axis 1. The capture descriptor itself
      * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
      * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
@@ -232,6 +241,15 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * `runs: 1`, so a HIT still runs their bodies for those pushes.
      */
     _shellCaptureUnrecordedLoaderPush?: true;
+    /**
+     * @internal The lane of each loader the capture's matched route registers
+     * (loader-cache.ts routeLoaderLanes), set by createMatchContextForFull
+     * before any loader runs. The capture's push funnel credits a push made
+     * under a live-lane loader's body, at any depth, to that loader
+     * (shell-capture.ts deriveShellCaptureContext). Own property of the
+     * capture's derived context only.
+     */
+    _shellCaptureLoaderLanes?: ReadonlyMap<string, "live" | "bake">;
     /**
      * @internal Record keys resolved for this request (CacheScope
      * resolveKeyFrom): by the scope's `key()` (one result) or its store's
@@ -330,7 +348,9 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * scope replaces any route-derived cache() scope for the tail's match
          * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
          * ShellRecordUnavailableError instead of resolving segments
-         * (withCacheLookup): a HIT never runs a handler.
+         * (withCacheLookup): a HIT never runs a handler. The record's
+         * loader-owned handle pushes restore as authoritative
+         * (HandleStore.pushRestored): the prelude rendered them.
          */
         docTail?: true;
         /**
@@ -382,8 +402,9 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _shellFragmentPayload?: boolean;
     /**
      * @internal Set by the capture guard (server/context.ts
-     * tripShellCaptureGuard) when it throws DURING a capture render: the read
-     * ("cookies()", "headers()", "ctx.get()", "ctx.theme") and the fix the
+     * guardIdentityRead) when it throws DURING a capture render: the read
+     * ("cookies()", "headers()", `ctx.get() for a non-cacheable variable`,
+     * "ctx.theme") and the fix the
      * refusal warning gives for it. Load-bearing for the
      * bake lane: a guard throw inside an executing loader is swallowed by
      * wrapLoaderPromise into per-loader error UI, which would otherwise bake
@@ -512,11 +533,24 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     /**
      * @internal The theme cookie (or the default) read with no identity guard.
      * The guarded reads (`theme` here, the handler and middleware `ctx.theme`)
-     * call it after assertThemeReadAllowed; the router's own payload read goes
-     * through payloadInitialTheme (rsc/full-payload.ts). Undefined without
+     * call it after guardIdentityRead (readGuardedTheme); the router's own payload read goes
+     * through payloadInitialTheme (rsc/full-payload.ts), except the unmatched
+     * route's 404 (rsc/handler.ts), which is never stored. Undefined without
      * theme config.
      */
     _readTheme(): Theme | undefined;
+    /**
+     * @internal Set by the document-cache middleware (cache/document-cache.ts)
+     * before it runs a render whose response it may store: the MISS and the
+     * stale refresh. payloadInitialTheme reads it (#978).
+     */
+    _documentCacheRender?: boolean;
+    /**
+     * @internal Set by payloadInitialTheme when the document payload carries
+     * the visitor's theme and it differs from the no-cookie default. The
+     * document cache does not store that response (#978).
+     */
+    _payloadVisitorTheme?: boolean;
     /**
      * Attach location state entries to the current response.
      *
@@ -551,19 +585,6 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _routeName?: string;
     /** @internal Previous route key (from the navigation source), used for revalidation */
     _prevRouteKey?: string;
-    /**
-     * @internal Navigation/action source data the transition({ when }) gate reads
-     * to build its ShouldRevalidateFn-shaped predicate context. currentUrl/Params
-     * come from the navigation snapshot (set at match time); action* are stashed
-     * at the action-bearing gate call sites. All undefined when there is no source
-     * (initial full load) or no action (plain navigation).
-     */
-    _gateCurrentUrl?: URL;
-    _gateCurrentParams?: Record<string, string>;
-    _gateActionId?: string;
-    _gateActionUrl?: URL;
-    _gateActionResult?: unknown;
-    _gateFormData?: FormData;
     /**
      * @internal True while the post-action revalidation render is running (set by
      * revalidateAfterAction). The "use cache" runtime reads this to prefer
@@ -727,7 +748,7 @@ export interface RouteRecordWindow {
  * 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" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_tagInvalidations" | "_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" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_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:
@@ -762,7 +783,7 @@ export declare function setRequestContextParams(params: Record<string, string>,
  * route key available for revalidation and intercept evaluation.
  * @internal
  */
-export declare function setRequestContextPrevRouteKey(prevRouteKey: string | undefined, currentUrl?: URL, currentParams?: Record<string, string>): void;
+export declare function setRequestContextPrevRouteKey(prevRouteKey: string | undefined): void;
 /**
  * Get accumulated location state entries from the current request context.
  * Returns undefined if no state has been set.

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

@@ -0,0 +1,44 @@
+/**
+ * The guarded `ctx.request.headers` (#976) and the router's raw reads.
+ *
+ * The Request the router hands to user code (handler, middleware and loader
+ * `ctx.request`, `getRequestContext().request`) carries an own `headers`
+ * getter that shadows the prototype's and runs the identity guard
+ * (cookie-store.ts guardRequestHeaders). A Proxy around the Request is not an
+ * option: `fetch(request)`, `new Request(request)` and `request.clone()` read
+ * the platform's internal slots, which a Proxy does not have. The own getter
+ * keeps the object a real Request, and those operations never call it.
+ */
+/**
+ * A request's headers, past the guard. The rule: router code never reads a
+ * request's headers through the getter, only through this, so the guard sees
+ * user reads alone. Several router reads run inside the scopes the guard
+ * refuses (the state cookie rotation at a ppr capture, match's HMR marker,
+ * a store's cf-ray inside a "use cache" body, telemetry inside a loader
+ * fill); the rest follow the rule so a new call site cannot drift into one.
+ */
+export declare function requestHeaders(request: Request): Headers;
+/**
+ * Shadow `request.headers` with an own, non-enumerable getter that calls
+ * `beforeRead` and returns the request's own Headers (stable per request, so
+ * a header set through it stays visible to every reader). Idempotent. Leaves
+ * the request as is when `headers` is a non-configurable own property (a
+ * runtime that defines it per instance). Three inherited members are
+ * shadowed with it:
+ *
+ * - `clone()` returns a clone shadowed the same way. A plain clone was a
+ *   Request without the getter, so `ctx.request.clone().headers` read the
+ *   visitor's headers past the guard. (`new Request(ctx.request)` still
+ *   returns a plain Request: the constructor cannot be intercepted.)
+ * - `_request`, on a lazy srvx NodeRequest (what @vitejs/plugin-rsc's Node
+ *   dev and preview servers and the vercel-output launcher hand the
+ *   router), runs unguarded: it builds the platform Request on first use
+ *   from `this.headers`, for clone() and the body readers. Through the
+ *   getter, a clone() inside a cache() boundary threw as a user read. It
+ *   stays lazy, so a request whose body srvx reads from its buffered
+ *   `rawBody` never builds one.
+ * - Node's util.inspect hook runs unguarded: undici's inspect reads
+ *   `this.headers`, so `console.log(ctx.request)` inside a "use cache" body
+ *   threw. A log is not a read into a shared entry.
+ */
+export declare function shadowRequestHeaders(request: Request, beforeRead: () => void): Request;

package/dist/types/server.d.ts

@@ -13,4 +13,5 @@ export { registerRouteMap, setCachedManifest, clearCachedManifest, clearAllRoute
 export { registerLoaderById, setLoaderImports, } from "./server/loader-registry.js";
 export { createRequestContext, type CreateRequestContextOptions, } from "./server/request-context.js";
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
+export { enableTransitionWhenValidation } from "./transition-when-ref.js";
 export { clearClientUrlProjections, setClientUrlProjection, type ClientUrlProjection, } from "./client-urls/server-projection.js";

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

@@ -4,7 +4,7 @@ import { blockPrefetch, unblockPrefetch, createPageHelpers, createStopwatch, get
 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 { 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 { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, type PprReplayBypassReason, type PprReplayStatus, type ShellCachePartition, 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 {