@rangojs/router 0.17.0 → 0.19.0

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. */
@@ -104,6 +119,39 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _rotateStateCookie(): void;
     /** @internal Set the keepClientCache() directive header on the response. */
     _setKeepCacheDirective(): void;
+    /**
+     * @internal This request carries the fresh-reads cookie: it follows an
+     * updateTag()/revalidateTag() by the same user, so the stores read tag
+     * markers and shells from the store, not from an isolate memo.
+     */
+    _freshReads?: boolean;
+    /**
+     * @internal Set the fresh-reads cookie on this response for `maxAgeMs`
+     * (rounded up to whole seconds; the longest stays). Called by
+     * updateTag()/revalidateTag().
+     */
+    _setFreshReadsCookie(maxAgeMs: number): void;
+    /**
+     * @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 (the
+     * stores' masks) is keyed by the request, not by whichever derived object
+     * called or read (#973).
+     */
+    _requestRoot?: RequestContext<any, any>;
+    /**
+     * @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.
+     */
+    _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
+     * a streaming loader or render.
+     */
+    _responseSent?: boolean;
     /**
      * Access loader data or push handle data.
      *
@@ -137,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
@@ -172,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
@@ -191,6 +234,53 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * property of the capture's derived context only.
      */
     _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
+    /**
+     * @internal Set on a capture's derived context when a loader pushed a
+     * value the record cannot keep (a deferred push, masked nested promises,
+     * or a push outside a loader body): the loader records then carry
+     * `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
+     * keyGenerator (one per default key). A shell capture's derived context
+     * reads it through the prototype chain, so the capture reuses the
+     * partition its request resolved instead of running `key()` again.
+     */
+    _resolvedCacheKeys?: Map<unknown, Map<string, Promise<string>>>;
+    /**
+     * @internal The shell store key the PPR serve path resolved for this
+     * document request (rsc-rendering.ts shellServePlan), request partition
+     * included. Read by the testing helper serveShellRequest.
+     */
+    _shellKey?: string;
+    /**
+     * @internal The request carried the forced-MISS reload marker
+     * (shell-serve.ts SHELL_MISS_PARAM). The handler strips the marker from the
+     * request on entry and sets this; the shell gate renders the request like a
+     * cache miss.
+     */
+    _shellForcedMiss?: true;
+    /**
+     * @internal The freshness window of the route cache() records this
+     * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+     * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+     * its scope's swr. The narrowest record wins. A shell capture caps its
+     * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+     * shell is never fresher, or served longer, than the route cache() entry
+     * it replayed or wrote.
+     */
+    _routeRecordWindow?: RouteRecordWindow;
     /**
      * @internal Loader-family snapshot seed for a shell HIT's tail render:
      * segment-key -> the capture's elided container (already Flight-deserialized
@@ -198,21 +288,24 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * overlays it onto the fresh run's container (recorded paths pinned,
      * hole-marker paths keep the fresh nested promises) so the payload's baked
      * bytes match the frozen prelude; a hole-free entry resolves pin-first
-     * without gating on the fresh run. Own property of the HIT tail's derived
-     * context only.
+     * and does not run the loader. Two owners: serveShellHit sets it on the
+     * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
+     * request context of a PPR partial replay once its doc record hits, and
+     * restores the previous value after the match.
      */
     _shellLoaderSeed?: Map<string, import("../cache/shell-snapshot.js").ShellLoaderSeedEntry>;
     /**
-     * @internal Shell fast-path marker: makes the next eligible match treat the
-     * whole matched route as an implicit doc-level cache() boundary (see
+     * @internal The doc record marker: makes the next match treat the whole
+     * matched route as an implicit doc-level cache() boundary (see
      * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
      * (a) the capture's derived context — with a record-only store so the
      * capture's cacheRoute write lands in the snapshot, never the real store —
-     * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
-     * replay, where `store` is a request-local segment overlay. Handler-live holes
-     * and conditional transitions decline replay.
-     * Routes with their own cache() config are never overridden — their scope's
-     * store/key/ttl/swr/condition semantics stay authoritative. On the
+     * (b) a document HIT tail's seeded context (`docTail`), and (c) an eligible
+     * normal-route partial replay, where `store` is a request-local segment
+     * overlay.
+     * A document HIT tail replays the record even for a route with its own
+     * cache() config (the gate before the commit already evaluated that
+     * scope's opt-outs). Elsewhere the route's scope stays authoritative. On the
      * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
      * such a scope instead of being ignored: the seeded doc record supplies the match
      * only when the explicit tier misses (withCacheLookup). cache(false) and a
@@ -229,12 +322,17 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * segment record even when the triggering request is partial.
          */
         keyPrefix?: "doc";
-        /** @internal Called only after the implicit cache hit decodes successfully. */
-        onHit?: () => void;
+        /**
+         * @internal Called only after the implicit cache hit decodes
+         * successfully; the lookup awaits it before returning the hit, so work
+         * it starts lands before the route's loaders resolve.
+         */
+        onHit?: () => void | Promise<void>;
         /**
          * @internal Called when the seeded document record fails server-side
          * deserialization. Partial replay uses it to replace the enclosing shell
-         * snapshot after serving the fresh fallback.
+         * snapshot after serving the fresh fallback. A document HIT tail does not
+         * set it: withCacheLookup throws ShellRecordUnavailableError instead.
          */
         onCorrupt?: () => void;
         /**
@@ -245,6 +343,23 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * require the exact consumable record instead of "any segment record".
          */
         docKey?: string;
+        /**
+         * @internal Set on a document HIT tail (serveShellHit). The implicit doc
+         * 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. The record's
+         * loader-owned handle pushes restore as authoritative
+         * (HandleStore.pushRestored): the prelude rendered them.
+         */
+        docTail?: true;
+        /**
+         * @internal The key a document HIT tail looks the doc record up by: the
+         * entry's own `docKey`. Recomputing it could name another key (a store
+         * keyGenerator folding request data, a build-time capture's synthetic
+         * host) and miss the record.
+         */
+        fixedDocKey?: string;
         /**
          * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
          * serve path. Its presence arms the explicit-scope composition in
@@ -286,30 +401,20 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _shellFragmentPayload?: boolean;
     /**
-     * @internal Handler-layer liveness observed DURING a shell capture, from
-     * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
-     * when a push made OUTSIDE a DSL loader scope carries a nested thenable
-     * (masked to a never-filling hole); (b) still-pending top-level handler
-     * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
-     * executing during the capture (loader-resolution.ts — its consumption-lane
-     * value would freeze on a handler-free HIT). captureAndStoreShell folds it
-     * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
-     * property of the capture's derived context only.
-     */
-    _shellCaptureHandleLiveness?: {
-        holes: boolean;
-        pendingPushes: number;
-        handlerInvokedLoader: boolean;
-    };
-    /**
-     * @internal Set (to the offending fn name) by the cookies()/headers()
-     * capture guard when it throws DURING a capture render. Load-bearing for the
+     * @internal Set by the capture guard (server/context.ts
+     * 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
      * silently into the shared shell — the capture checks this flag after the
      * render and refuses instead. Deterministic, so the capture does not retry.
      */
-    _shellCaptureGuardTripped?: string;
+    _shellCaptureGuardTripped?: {
+        surface: string;
+        fix: string;
+    };
     /**
      * @internal The loader $$id whose BODY was executing when the capture guard
      * tripped (read off the loader-body ALS scope at trip time), or undefined
@@ -336,6 +441,21 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * content used and can therefore be invalidated by updateTag()/revalidateTag().
      */
     _requestTags: Set<string>;
+    /**
+     * @internal This request can write a route cache() record: its match
+     * resolved a cache scope (match-api.ts). Arms the record tag owners
+     * (cache-tag.ts armRecordTagOwners); off, the segment scopes, loader links
+     * and owned tag sets are skipped entirely. A capture's or background
+     * re-render's derived context (Object.create) inherits it.
+     */
+    _recordTagOwners?: true;
+    /**
+     * @internal This request resolves a loader bound with its own cache()
+     * (match-api.ts, or the binding's funnel). Arms the per-execution loader
+     * tag sets (cache-tag.ts armLoaderTagSets); off, a loader execution
+     * allocates no set and a read links nothing. Derived contexts inherit it.
+     */
+    _recordLoaderTags?: true;
     /** @internal Cache profiles for "use cache" profile resolution (per-router) */
     _cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
     /**
@@ -376,6 +496,11 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * Returns the theme value from the cookie, or the default theme if not set.
      * This is the user's preference ("light", "dark", or "system"), not the resolved value.
      *
+     * The visitor's cookie, so it is guarded like `cookies()`: reading it
+     * refuses a ppr shell capture and throws inside a `cache()` boundary or a
+     * `"use cache"` function (#971). A non-enumerable getter: a spread or
+     * `Object.assign` copy of the context does not carry it.
+     *
      * @example
      * ```typescript
      * route("settings", (ctx) => {
@@ -384,7 +509,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * });
      * ```
      */
-    theme?: Theme;
+    readonly theme?: Theme;
     /**
      * Set the theme (only available when theme is enabled in router config)
      *
@@ -405,6 +530,27 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     setTheme?: (theme: Theme) => void;
     /** @internal Theme configuration (null if theme not enabled) */
     _themeConfig?: ResolvedThemeConfig | null;
+    /**
+     * @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 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.
      *
@@ -439,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
@@ -595,13 +728,27 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * request wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+    freshUntil: number;
+    staleUntil: number;
+    ttl: number;
+    swr: number;
+    written: boolean;
+}
 /**
  * Public view of RequestContext, without internal methods and fields.
  *
  * 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" | "_shellCaptureHandleLiveness" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_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" | "_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:
@@ -636,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/ssr/index.d.ts

@@ -238,6 +238,15 @@ interface ShellCaptureOptions {
      * refuses to store the shell (issue #915).
      */
     onError?: (error: unknown) => void;
+    /**
+     * Called with React's errorInfo for each task still pending when the
+     * capture's own abort froze the prelude; its componentStack is computed
+     * when read. The dev no-shell warning prints the stacks: one of them is what
+     * suspended above <body> (issue #941).
+     */
+    onAbortedTask?: (errorInfo: {
+        componentStack?: string;
+    } | undefined) => void;
 }
 /**
  * Result of a successful shell capture. `prelude` is the raw prelude bytes;

package/dist/types/ssr/ssr-root.d.ts

@@ -54,14 +54,15 @@ export interface SsrRootOptions {
     nonce?: string;
     /**
      * Fires once when the Flight payload root settles (resolve OR reject) — the
-     * signal that every client-module load the payload references completed and
-     * fizz can start emitting the tree. The capture pass gates its abort on
-     * this: a fully REPLAYED (prerendered) route's Flight stream goes
-     * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
-     * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
-     * graph), so an abort gated on Flight quiet alone fires first and freezes
-     * a zero-byte prelude. Masked-loader holes do NOT block this signal —
-     * they postpone below the root.
+     * signal that fizz can start emitting the tree. A client component used as
+     * an element type resolves lazily, so its module load can still be in
+     * flight (captureShellHTML waits for those separately, issue #949). The
+     * capture pass gates its abort on this: a fully REPLAYED (prerendered)
+     * route's Flight stream goes byte-quiet in ~1-3ms, but fizz cannot render
+     * even <html> until the module loads finish (real module-runner I/O in dev;
+     * 100ms+ on a cold graph), so an abort gated on Flight quiet alone fires
+     * first and freezes a zero-byte prelude. Masked-loader holes do NOT block
+     * this signal — they postpone below the root.
      */
     onPayloadSettled?: () => void;
     /**

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 {

package/dist/types/testing/flight.entry.d.ts

@@ -18,6 +18,11 @@
  * element tree, so you can assert typed prop fidelity across the client boundary
  * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
  * deserialize only — no hydration/interaction (that is the e2e tier).
+ *
+ * `serveShellRequest` serves one request through the router's production
+ * handler, so a `ppr` route's MISS runs the real shell capture and a later
+ * request is a real HIT; only the HTML step is stubbed. `resetShellTestState`
+ * clears the per-isolate PPR state between tests.
  */
 export { renderToFlightString, normalizeFlight, assertFlightRuntimeAvailable, } from "./flight.js";
 export type { RenderToFlightStringOptions } from "./flight.js";
@@ -25,3 +30,5 @@ export { renderServerTree, findClientBoundaries, findElements, textContent, asse
 export type { RenderServerTreeOptions, RenderServerTreeResult, ClientBoundary, BoundarySelector, FoundElement, ElementSelector, } from "./flight-tree.js";
 export { renderHandler } from "./render-handler.js";
 export type { TestableHandler, RenderHandlerOptions, RenderHandlerResult, StateCookieSeed, } from "./render-handler.js";
+export { serveShellRequest, resetShellTestState, } from "./serve-shell-request.js";
+export type { ServeShellRequestOptions, ServeShellRequestResult, } from "./serve-shell-request.js";

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

@@ -38,7 +38,7 @@ export type { RunMiddlewareOptions, RunMiddlewareResult, } from "./run-middlewar
 export { runLoader, runLoaderResult } from "./run-loader.js";
 export type { RunLoaderOptions, RunLoaderResult, UseResolver, TestLoaderContext, } from "./run-loader.js";
 export { runTransitionWhen } from "./run-transition-when.js";
-export type { RunTransitionWhenOptions, RunTransitionWhenResult, } from "./run-transition-when.js";
+export type { RunTransitionWhenAction, RunTransitionWhenLocation, RunTransitionWhenOptions, RunTransitionWhenResult, } from "./run-transition-when.js";
 export { runClientRevalidate } from "./run-client-revalidate.js";
 export type { RunClientRevalidateOptions } from "./run-client-revalidate.js";
 export { dispatch } from "./dispatch.js";
@@ -47,8 +47,9 @@ export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSi
 export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
 export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";
 export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
-export type { PprReplayBypassReason, PprReplayStatus, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
+export type { PprReplayBypassReason, PprReplayStatus, ShellCachePartition, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
 export { collectHandle } from "./collect-handle.js";
+export { withLocationStateKey } from "./location-state-key.js";
 export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";
 export type { GeneratedRoutesDiff, GeneratedRouteMismatch, } from "./generated-routes.js";
 export { createTestRequestContext, runInRequestContext, toRequest, seedVariables, } from "./internal/context.js";

package/dist/types/testing/internal/action-id.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The id a testing primitive's `action` option names: a single imported
+ * server action (its `$id ?? $$id`, as the action boundary derives it) or a
+ * raw actionId string. A function without either id throws, naming the
+ * primitive.
+ */
+export declare function resolveTestActionId(action: ((...args: never[]) => unknown) | string | undefined, primitive: string): string | undefined;