@rangojs/router 0.18.0 → 0.19.0

package/dist/types/cache/vercel/vercel-cache-store.d.ts

@@ -6,8 +6,9 @@
  * far smaller: Vercel's Runtime Cache already IS a distributed, tag-aware cache
  * (regional storage, global tag-expire within ~300ms), so none of CFCacheStore's
  * L1/L2 tiering or per-tier timeout budgets are needed here - the platform does
- * that work. Tag markers exist only for the shell family (`tm`, see
- * isTagsInvalidatedSince), and only PPR shell reads memoize them. What this
+ * that work. Tag markers (`tm`, see isTagsInvalidatedSince) gate shell reads
+ * and writes and every cache write that started before an invalidation
+ * (#977); only PPR shell reads memoize them. What this
  * store adds on top of the raw primitive is the parts Vercel does NOT give us:
  *
  *   1. Stale-while-revalidate. `getCache` has no stale-but-serve: a TTL'd entry
@@ -287,32 +288,38 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
      * fresh values are used as is, stale ones are used and refreshed in the
      * background, older ones block on the runtime-cache read. A request
      * carrying the fresh-reads cookie skips the memo. A failed read rejects and
-     * is never memoized. The shell write gate and build shells
-     * (isTagsInvalidatedSince) read the runtime cache every time.
+     * is never memoized. The shell write gate, build shells and the data
+     * write gates (isTagsInvalidatedSince) read the runtime cache each time
+     * they ask; gates of a request asking while a read is in flight share it
+     * (gateMarkerRead), and nothing is kept once it settles.
      */
     private readTagMarker;
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
     /**
-     * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
-     * expireTag() keeps no queryable history, so invalidateTags() writes "tm"
-     * markers for runtime capture races and immutable build shells. Marker >=
-     * generation start wins; read errors fail open like the CF marker check.
+     * SegmentCacheStore.isTagsInvalidatedSince. expireTag() keeps no queryable
+     * history, so invalidateTags() writes "tm" markers for runtime capture
+     * races, immutable build shells and data writes that started before an
+     * invalidation (#977, tag-invalidation.ts predatesInvalidation). Marker >=
+     * generation start wins. Read errors fail open like the CF marker check,
+     * except for the write gate (`failClosed`), which counts them as an
+     * invalidation. Each tag's marker is read through gateMarkerRead
+     * (request-tag-mask.ts): gates asking while a read is in flight share it.
      */
-    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    isTagsInvalidatedSince(tags: string[], sinceMs: number, options?: {
+        failClosed?: boolean;
+    }): Promise<boolean>;
     private tagsInvalidatedSince;
     invalidateTags(tags: string[]): Promise<void>;
     /**
      * The request-local half of invalidateTags(), run before its first await
-     * (#973): see requestInvalidations. revalidateTag() waits for nothing
-     * after it.
+     * (#973): the request masks the tags (request-tag-mask.ts). The platform's
+     * expireTag() and the tm marker writes are what other requests see, and
+     * revalidateTag() does not wait for them.
      */
     private maskTagsForRequest;
     /**
-     * Whether this request invalidated one of `tags` through this store at or
-     * after `taggedAt`. `>=`, as the marker check: an entry written in the
-     * invalidation's millisecond may hold a value computed before it, so it
-     * misses (a false miss, never a stale read). An entry without a stamp was
-     * written before the stamp existed and counts as older.
+     * Whether this request masked one of `tags` through this store at or after
+     * `taggedAt`. An entry without a stamp counts as older than any mask.
      */
     private maskedForRequest;
     /** A data read's mask check: reports the miss and returns true when masked. */

package/dist/types/client-urls/navigation.d.ts

@@ -1,4 +1,5 @@
 import type { ClientUrlPatterns } from "./types.js";
+import type { TransitionWhenFn } from "../types/segments.js";
 export interface ClientUrlNavigationIntent {
     readonly routeId: string;
     /** Destination params from the local trie match (definition-local). */
@@ -6,14 +7,39 @@ export interface ClientUrlNavigationIntent {
     /** Absolute destination pathname (mount included) and search ("?..." or ""). */
     readonly pathname: string;
     readonly search: string;
+    /**
+     * transition({ when }) gated this navigation off at the swap: the
+     * destination presents urgently instead of in a transition lane.
+     */
+    readonly transitionGatedOff?: boolean;
+}
+/** What the bridge needs to decide transition({ when }) at the swap. */
+export interface ClientUrlDestination {
+    /** Definition-local params of the destination match. */
+    readonly params: Readonly<Record<string, string>>;
+    /** Canonical route name (include prefix applied); undefined when unnamed. */
+    readonly routeName: string | undefined;
+    /** The destination route's own `when`, from its "use client" definition. */
+    readonly when: TransitionWhenFn | undefined;
+    /**
+     * Param names the ORIGIN route matched inside the group: the committed
+     * params minus these are the mount's (include prefix) params.
+     */
+    readonly originLocalParamNames: readonly string[];
 }
 export declare function setActiveInterceptTargets(targets: readonly string[] | undefined): void;
 export interface ClientUrlNavigationPresentation {
     readonly routeId: string;
+    /**
+     * The transition({ when }) decision made at the optimistic swap (true =
+     * gated off), or undefined when nothing was swapped (a same-route
+     * navigation decides at the canonical commit).
+     */
+    readonly transitionGatedOff: boolean | undefined;
     clear(): void;
 }
-export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mount: string, namePrefix: string, setIntent: (intent: ClientUrlNavigationIntent | null) => void): () => void;
-export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal): ClientUrlNavigationPresentation | null;
+export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mount: string, namePrefix: string, setIntent: (intent: ClientUrlNavigationIntent | null) => void, routeId?: string): () => void;
+export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal, decideTransition?: (destination: ClientUrlDestination) => boolean): ClientUrlNavigationPresentation | null;
 /**
  * Run the held clientUrls route's per-loader revalidate() predicates and
  * encode their decisions for the request header. Predicates are CLIENT code

package/dist/types/client-urls/server-projection.d.ts

@@ -32,9 +32,12 @@ export interface ClientUrlProjectionRoute {
      *  document renders await them before first flush. Absent (= none) in
      *  projections serialized before the option existed. */
     readonly awaitedLoaderIndices?: readonly number[];
-    /** Data-only transition config (no `when` — server-tree only); absent in
-     *  projections serialized before transition support. */
+    /** Data-only transition config (never `when`); absent in projections
+     *  serialized before transition support. */
     readonly transition?: Readonly<ClientTransitionConfig>;
+    /** The route's transition() declares a browser-run `when`. Materialization
+     *  attaches a clientUrls when reference (definition + route id). */
+    readonly transitionWhen?: true;
 }
 export interface ClientUrlProjectionIntercept {
     readonly slotName: `@${string}`;

package/dist/types/client-urls/types.d.ts

@@ -88,12 +88,12 @@ export interface ClientUrlLoaderRecord {
     readonly ssr?: false;
 }
 /**
- * The data-only subset of TransitionConfig a clientUrls() route may declare:
- * ViewTransition classes/name plus the boundary opt-out. The `when` gate is a
- * server-executed predicate and stays in the server tree — it cannot cross the
- * "use client" projection boundary.
+ * The TransitionConfig subset a clientUrls() route may declare: ViewTransition
+ * classes/name, the boundary opt-out, and the browser-run `when` gate. The
+ * projection carries only a "has when" marker; the browser calls the function
+ * this module declares (transition-when-ref.ts resolveTransitionWhen).
  */
-export type ClientTransitionConfig = Pick<TransitionConfig, "enter" | "exit" | "update" | "share" | "default" | "name" | "viewTransition">;
+export type ClientTransitionConfig = Pick<TransitionConfig, "enter" | "exit" | "update" | "share" | "default" | "name" | "viewTransition" | "when">;
 export interface ClientUrlRouteRecord {
     readonly id: string;
     readonly pattern: string;

package/dist/types/client.d.ts

@@ -167,7 +167,7 @@ export { useSearchParams } from "./browser/react/use-search-params.js";
 export type { SearchParamsInit, SetSearchParams, SetSearchParamsOptions, } from "./browser/react/use-search-params.js";
 export { useParams } from "./browser/react/use-params.js";
 export { useNonce } from "./browser/react/nonce-context.js";
-export type { RouterInstance, RouterNavigateOptions, ReadonlyURLSearchParams, ActionState, ActionLifecycleState, } from "./browser/types.js";
+export type { RouterInstance, RouterNavigateOptions, HistoryState, PlainHistoryState, ReadonlyURLSearchParams, ActionState, ActionLifecycleState, } from "./browser/types.js";
 export { useAction, type ServerActionFunction, } from "./browser/react/use-action.js";
 export { useSegments, type SegmentsState, } from "./browser/react/use-segments.js";
 export { NavigationProvider, type NavigationProviderProps, } from "./browser/react/NavigationProvider.js";

package/dist/types/index.d.ts

@@ -16,7 +16,7 @@ export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchP
 export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./cache/search-params-filter.js";
 export { createLoader } from "./loader.js";
 export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
-export type { TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
+export type { TransitionConfig, TransitionWhenFn, TransitionWhenContext, TransitionWhenKind, RouteLocation, ServerRouteLocation, ViewTransitionClass, } from "./types.js";
 export type { RouteUseItem, LayoutUseItem, AllUseItems, UseItems, HandlerUseItem, } from "./route-types.js";
 export type { ResponseHandler, ResponseHandlerContext, JsonResponseHandler, TextResponseHandler, JsonValue, ResponsePathFn, JsonResponsePathFn, TextResponsePathFn, RouteResponse, ProblemDetails, PartialPrerenderProps, } from "./urls.js";
 export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";

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

@@ -9,7 +9,7 @@
  * in RSC context, while the regular index.ts is used in client components.
  */
 export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, HandlerError, BuildError, DslContextError, InvalidHandlerError, RouterError, Skip, isSkip, } from "./index.js";
-export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, IsActionFn, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, LoaderOptions, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
+export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, IsActionFn, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, LoaderOptions, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, TransitionConfig, TransitionWhenFn, TransitionWhenContext, TransitionWhenKind, RouteLocation, ServerRouteLocation, ViewTransitionClass, } from "./types.js";
 export type { RangoOptions, SSRStreamMode, SSROptions, ResolveStreamingContext, } from "./router.js";
 export type { OriginCheckConfig, OriginCheckContext, OriginCheckPhase, } from "./rsc/origin-guard.js";
 export type { ShellCaptureDebug, ShellCaptureDebugEvent, } from "./rsc/shell-capture.js";

package/dist/types/route-definition/helpers-types.d.ts

@@ -110,7 +110,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *
      * // Conditional activation via the config object's `when` selector
      * intercept("@modal", "card", <CardModal />, {
-     *   when: ({ from }) => from.pathname.startsWith("/board"),
+     *   when: ({ from }) => from.url.pathname.startsWith("/board"),
      * })
      *
      * // Config + other use-items: config is arg 4, use is arg 5
@@ -118,7 +118,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   "@modal",
      *   "card",
      *   <CardModal />,
-     *   { when: ({ from }) => from.pathname.startsWith("/board") },
+     *   { when: ({ from }) => from.url.pathname.startsWith("/board") },
      *   () => [loader(CardDetailLoader)],
      * )
      * ```
@@ -387,12 +387,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * transition({}) is startTransition + ViewTransition under the default and
      * startTransition only when the router sets viewTransition: false.
      *
-     * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
-     * request. It normally runs server-side after the route handler. On a `ppr`
-     * route it is automatically hoisted before route handlers and reevaluated on
-     * every replay, so it may read URL/params/action/env and middleware-set context
-     * but not handler-set context. Returning false drops this transition for the
-     * request. This is distinct from intercept()'s match-time `when` selector.
+     * Conditional hold: pass `when` to gate the navigation in the browser,
+     * inline (the build hoists the literal into a client module) or as a
+     * "use client" export. It runs once per
+     * navigation with { kind, from, to, isAction, action }, never on the server;
+     * false makes the commit urgent (no hold, no view transition). This is
+     * distinct from intercept()'s match-time `when` selector.
      *
      * ```typescript
      * // Attach to a single route
@@ -411,15 +411,15 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   transition({ viewTransition: false }),
      * ])
      *
-     * // Hold only when the handler decided to (post-handler predicate):
+     * // Hold only when arriving from the list (a browser predicate):
      * path("/product/:id", ProductPage, { name: "product" }, () => [
-     *   transition({ when: (ctx) => ctx.get(KeepScroll) === true }),
+     *   transition({ when: ({ from }) => from.routeName === "products.list" }),
      * ])
      * ```
      * @param config - ViewTransition configuration (enter, exit, update, share,
      *   default, name), `viewTransition: "auto" | false` to toggle the router
      *   boundary (createRouter({ viewTransition }) sets the app-wide default), and
-     *   `when: (ctx) => boolean` to gate the transition per request
+     *   `when` to gate the transition per navigation (a browser predicate)
      * @param children - Optional callback returning child routes to wrap
      */
     transition: {

package/dist/types/route-name.d.ts

@@ -17,6 +17,13 @@ export declare const INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
  * be preserved.
  */
 export declare function isAutoGeneratedRouteName(name: string): boolean;
+/**
+ * The route name user code may see: a user-defined name, or undefined for an
+ * internal one (unnamed path(), hidden include scope). Internal names are
+ * route keys, not API, and must not leak into transition({ when }) or
+ * intercept({ when }) locations.
+ */
+export declare function publicRouteName(routeKey: string | undefined): string | undefined;
 /**
  * Validate that a user-provided route name does not collide with
  * reserved internal prefixes. Checks every dot-separated segment,

package/dist/types/router/error-handling.d.ts

@@ -5,7 +5,7 @@
  * Also includes the shared invokeOnError utility for error callback invocation.
  */
 import { type ReactNode } from "react";
-import type { EntryData } from "../server/context";
+import type { EntryData } from "../server/context.js";
 import type { ResolvedSegment, ErrorInfo, ErrorBoundaryHandler, NotFoundInfo, NotFoundBoundaryHandler, ErrorPhase, OnErrorCallback } from "../types";
 /**
  * Context required to invoke the onError callback.

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

@@ -11,6 +11,8 @@ import type { SegmentResolutionDeps } from "./types.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.
  */

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

@@ -151,6 +151,11 @@ export interface MatchContext<TEnv = any> {
     interceptSelectorContext: InterceptSelectorContext;
     isSameRouteNavigation: boolean;
     interceptResult: InterceptResult | null;
+    /**
+     * An intercept targets this route, matched or not (a same-route navigation
+     * skips it), so the response depends on the source. Partial matches only.
+     */
+    interceptTargeted?: boolean;
     cacheScope: CacheScope | null;
     isIntercept: boolean;
     actionContext?: ActionContext;

package/dist/types/router/match-middleware/background-revalidation.d.ts

@@ -126,10 +126,6 @@ import { type RequestContext } from "../../server/request-context.js";
  *     cache-scope.ts), so a swap sent live pushes into this render.
  *     setupLoaderAccess binds the store at setup, so it runs inside the
  *     derived context too.
- *   - _transitionWhen: fresh resolution appends transition({ when })
- *     predicates; the foreground's gateTransitions reads the array after the
- *     match, and a stale HIT (which replays the stored transition) must not
- *     evaluate this render's predicates.
  *   - _metricsStore: undefined, and the DSL store below has `metrics` unset
  *     (track() reads that one), so nothing lands on the foreground's perf
  *     timeline. ctx.Store.run closes over ctx.Store, so the derived store

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

@@ -481,7 +481,10 @@ export interface RangoOptions<TEnv = any> {
      *
      * Controls how long prefetch responses are kept in the client-side
      * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
-     * on server responses for CDN/edge caching.
+     * on prefetch responses, so the browser's HTTP cache may reuse them
+     * (`private`: shared caches such as a CDN do not store them). A route an
+     * intercept targets gets no prefetch `Cache-Control`: whether its
+     * response is the modal or the full page depends on the source page.
      *
      * 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

@@ -6,7 +6,8 @@
  * getItem()/setItem() methods on SegmentCacheStore.
  *
  * Cache key resolution (3-tier, matching CacheScope.resolveKey):
- *   1. options.key(requestCtx) — full override
+ *   1. options.key(requestCtx) — full override, stored namespaced as
+ *      loader:{loaderId}:key:{encodeURIComponent(result)} (#1009)
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
  *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
  *
@@ -50,6 +51,22 @@ import type { HandlerContext } from "../../types.js";
  * Memoized per entry.
  */
 export declare function bindsLoaderCache(entries: readonly EntryData[]): boolean;
+/**
+ * The ids of the loaders a request over the matched chain `entries` runs on
+ * the live lane (no `ssr: false`), on a chain entry, its orphan layouts or
+ * its parallel slots. A document HIT tail restores the record's pushes of
+ * every other owner as authoritative (withCacheLookup, HandleStore
+ * pushRestored); a live-lane loader is a hole, so its live run replaces its
+ * recorded pushes instead. Memoized per entry.
+ */
+export declare function liveLaneLoaderIds(entries: readonly EntryData[]): ReadonlySet<string>;
+/**
+ * The lane of each loader the matched chain `entries` registers: "live" (no
+ * `ssr: false`) or "bake". A loader registered on both is "live". A PPR
+ * capture credits a push to the first registered loader around it when that
+ * one is live (shell-capture.ts deriveShellCaptureContext).
+ */
+export declare function routeLoaderLanes(entries: readonly EntryData[]): ReadonlyMap<string, "live" | "bake">;
 /**
  * Resolve loader data with optional caching.
  *

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

@@ -8,10 +8,9 @@
  * fresh into it.
  *
  * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
- * the derived request context of the background capture task (shell-capture.ts) —
- * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
- * capture is wanted" and must not change behavior. This module is the single home
- * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * the derived request context of the background capture task (shell-capture.ts);
+ * the foreground render never sets it. This module is the single home for the
+ * mask so every loader execution site gates the same way (loader-cache.ts
  * `resolveLoaderData`, fresh.ts `resolveLoaders`).
  */
 import { type RequestContext } from "../../server/request-context.js";

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

@@ -10,24 +10,18 @@
  * server-component element holding a promise, which is a hole as a whole (see
  * elideLoaderContainer):
  *
- *   - elide:   deep-walk the settled container; a PENDING nested promise is a
- *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
- *              loader-cache masks every nested thenable at capture
- *              ({@link maskNestedContainerThenables}), nested promises are
- *              ALWAYS pending here for new captures. The SETTLED-marker branch
- *              below is legacy: it fires only if a settled thenable reaches
- *              elide anyway, and the overlay keeps decoding SETTLED markers
- *              from pre-mask snapshots. The result is promise-free and
- *              Flight-serializable.
+ *   - elide:   deep-walk the settled container; a nested promise is a hole,
+ *              replaced by {@link LOADER_HOLE_KEY}. loader-cache masks every
+ *              nested thenable at capture ({@link maskNestedContainerThenables},
+ *              a never-settling promise), so the promise shape alone decides:
+ *              a value that settled in time does not bake (#692). The result
+ *              is promise-free and Flight-serializable.
  *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
  *              the live nested promises), then the recorded container is laid
  *              over it: recorded paths win (they are what the prelude froze),
  *              hole-marker paths take the fresh run's value (the live hole),
- *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
- *              wrote use(data.x) against a promise-shaped container, and
- *              handing them the raw value throws React #438 on every HIT (the
- *              storefront PDP regression) — and fresh-only paths pass through
- *              (they cannot contradict prelude bytes that never rendered them).
+ *              and fresh-only paths pass through (they cannot contradict
+ *              prelude bytes that never rendered them).
  */
 import { maskNestedContainerThenables } from "./mask-nested.js";
 export { maskNestedContainerThenables };
@@ -41,26 +35,6 @@ export interface LoaderHoleMarker {
     [LOADER_HOLE_KEY]: 1;
 }
 export declare function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker;
-/**
- * Marker wrapping the inlined value of a NESTED promise that settled during
- * capture. The value baked (physics), but the container key was a promise —
- * the overlay must hand consumers a Promise.resolve(value), not the raw value,
- * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
- * container is never wrapped: loader-cache overlays against the awaited fresh
- * container value.
- */
-export declare const LOADER_SETTLED_KEY: "$rangoLoaderSettled";
-export interface LoaderSettledMarker {
-    [LOADER_SETTLED_KEY]: 1;
-    value: unknown;
-    /**
-     * Present when the pinned subtree contains hole markers. Computed once at
-     * capture (elide already visits every node) so the per-HIT overlay never
-     * rescans the pinned structure to pick its rehydration path.
-     */
-    holes?: 1;
-}
-export declare function isLoaderSettledMarker(value: unknown): value is LoaderSettledMarker;
 export type ElideResult = {
     state: "ok";
     value: unknown;
@@ -69,12 +43,12 @@ export type ElideResult = {
     state: "rejected";
 };
 /**
- * Deep-elide a settled bake-lane container for recording. Settled nested
- * promises pin their value behind a settled marker (they baked, but consumers
- * hold a promise-shaped key); pending ones become hole markers; a REJECTED
- * nested promise poisons the record (error UI must never bake into a shared
- * shell) — the caller refuses the capture. Plain data objects, arrays and the
- * props of host, Suspense/Fragment and client-reference elements are
+ * Deep-elide a settled bake-lane container for recording. Nested promises
+ * become hole markers: the capture masked each of them (never settles), so
+ * it postponed as a hole. A REJECTED container poisons the record (error UI
+ * must never bake into a shared shell) — the caller refuses the capture.
+ * Plain data objects, arrays and the props of host, Suspense/Fragment and
+ * client-reference elements are
  * traversed copy-on-write (an element through cloneElementWithProps); a shared
  * subtree or a cycle resolves to the same elided result. An element Flight
  * renders by calling user code (see rendersOnServer) is a leaf, or ONE hole

package/dist/types/router/segment-resolution/mask-nested.d.ts

@@ -54,6 +54,14 @@ export declare function cloneElementWithProps(element: ReactElement, props: Reco
  * encodes the handles every HIT replays.
  */
 export declare function settleNestedThenables(value: unknown): Promise<void>;
+/**
+ * True when `value` is a thenable or holds one where the capture's loader
+ * push funnel masks it (maskNestedContainerThenables): through plain data
+ * objects, arrays and React element props. Such a push stays out of a shell's
+ * record and reaches a HIT only from a run of its loader there, so a HIT
+ * keeps it; a push without one is the record's (HandleStore.pushRestored).
+ */
+export declare function holdsThenable(value: unknown): boolean;
 /**
  * Optional single-walk report for maskNestedContainerThenables: `thenable`
  * flips true when the walk masked at least one thenable. The capture push
@@ -87,8 +95,8 @@ export interface MaskReport {
  * nodes included, are leaves. Copy-on-write: a subtree without a thenable
  * comes back by identity, so an element is rebuilt only when its props hold
  * one, and then through cloneElementWithProps, which keeps its type, key,
- * owner, dev fields and key validation. The INPUT IS NEVER MUTATED — handler-side loader consumption (the
- * consumption-lane rule, semantic-matrix PPR3) shares the raw container and
- * must keep real values. Cycles are preserved as cycles in the copy.
+ * owner, dev fields and key validation. The INPUT IS NEVER MUTATED: a handler
+ * that reads the loader (`ctx.use`) reads the raw container and must keep
+ * real values. Cycles are preserved as cycles in the copy.
  */
 export declare function maskNestedContainerThenables(value: unknown, seen?: Map<object, unknown>, report?: MaskReport): unknown;

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

@@ -19,9 +19,11 @@ import type { EntryData } from "../../server/context";
  * (or "auto") value is left untouched because it already means "wrap" at the
  * gate, which also avoids needless object allocation and payload growth.
  *
- * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache). PPR routes evaluate it
- * from the manifest before the pipeline; other routes record it here for the
- * existing post-handler gate. Used by both fresh and revalidation resolution.
+ * `when`: a client reference the server never calls. It is STRIPPED here so no
+ * segment record (segment cache, prerender artifact, shell snapshot) carries
+ * it: those stores JSON-serialize the config and would silently drop it on
+ * some stores and keep it on others. rsc/attach-transition-when.ts attaches it
+ * from the route definition right before Flight instead. Used by both fresh
+ * and revalidation resolution.
  */
-export declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined, segmentId?: string): EntryData["transition"];
+export declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined): EntryData["transition"];

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

@@ -1,13 +1,27 @@
 import { type EntryData } from "../server/context.js";
 import type { RequestContext } from "../server/request-context.js";
-import type { TransitionWhenContext } from "../types/segments.js";
-export type TransitionWhenErrorReporter = (error: unknown, segmentId: string) => void;
-export declare function createTransitionWhenContext<TEnv>(ctx: RequestContext<TEnv>, target?: {
-    params: Record<string, string>;
+import type { TransitionWhenSite } from "../transition-when-ref.js";
+import type { TransitionWhenFn } from "../types/segments.js";
+/** A matched entry's transition({ when }) and where it was declared. */
+export interface TransitionWhenRecord {
+    readonly when: TransitionWhenFn;
+    readonly site: TransitionWhenSite;
+}
+/**
+ * Record the transition({ when }) references of a matched entry chain, keyed
+ * by the segment id each entry resolves to. The server never calls them:
+ * rsc/attach-transition-when.ts attaches them to the payload's segments right
+ * before Flight, and the browser decides (browser/transition-when.ts).
+ *
+ * Recorded from the static route definition on EVERY match (fresh, cache hit,
+ * prerender, PPR replay) because stored segments never carry them:
+ * applyViewTransitionDefault strips `when` at resolution, since segment stores
+ * JSON-serialize the transition config (dropping a function on some stores,
+ * keeping it by reference on others). Segment ids follow resolution: an
+ * entry's shortCode, and `${owner.shortCode}.${slot}` for a rendered parallel
+ * slot.
+ */
+export declare function recordTransitionWhenRefs<TEnv>(entries: readonly EntryData[] | undefined, ctx: RequestContext<TEnv>, route?: {
     routeName?: string;
-}): TransitionWhenContext<Record<string, string>, TEnv>;
-/** Evaluate server-only transition gates before handlers on a PPR route. */
-export declare function evaluatePprTransitionWhen<TEnv>(entries: EntryData[], ctx: RequestContext<TEnv>, target: {
-    params: Record<string, string>;
-    routeName?: string;
-}, reportError: TransitionWhenErrorReporter): void;
+    pattern?: string;
+}): void;

package/dist/types/rsc/attach-transition-when.d.ts

@@ -0,0 +1,18 @@
+import type { MatchResult } from "../types.js";
+import type { getRequestContext } from "../server/request-context.js";
+/**
+ * Attach transition({ when }) references to a payload's segments, right before
+ * Flight. Returns a copy for every segment it changes: the input segments may
+ * be the records a cache, prerender, or shell snapshot holds.
+ *
+ * Only a segment that carries `transition` gets its predicate. The config
+ * itself never varies per request, so the segment key and the <ViewTransition>
+ * wrapper depend only on the route definition (#995); the browser decides for
+ * every committed segment, kept ones included (#989).
+ *
+ * Render-time backstop for an invalid `when` that route discovery did not see
+ * (a route evaluated lazily at runtime): it throws the discovery error. A
+ * plain function reaching Flight would otherwise fail with React's generic
+ * "Functions cannot be passed directly to Client Components", or be dropped.
+ */
+export declare function attachTransitionWhen(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>): MatchResult["segments"];

package/dist/types/rsc/full-payload.d.ts

@@ -26,11 +26,18 @@ export declare function buildFullPayload(m: MatchResult, ctx: HandlerContext<any
  * ThemeProvider's first state), read with no identity guard: it is the
  * router's own read, not handler code (#971).
  *
- * A shell capture carries the no-cookie default, not the capturing visitor's
- * theme. The shell and its ShellCacheEntry.initialTheme serve every visitor,
- * and ThemeProvider re-syncs only from an explicitly stored theme, so a
- * visitor with none kept the capturer's `useTheme().theme` for the page's
- * lifetime. A visitor with a stored theme gets it pre-paint (theme script)
- * and in the provider after mount.
+ * A render other visitors may be served carries the no-cookie default, not
+ * the rendering visitor's theme: a shell capture, and a render the document
+ * cache runs whose response opted in before next() (documentCacheStoresRender,
+ * #978). The shell, its ShellCacheEntry.initialTheme and the stored document
+ * serve every visitor, and ThemeProvider re-syncs only from an explicitly
+ * stored theme, so a visitor with none kept the first visitor's
+ * `useTheme().theme` for the page's lifetime. A visitor with a stored theme
+ * gets it pre-paint (theme script) and in the provider after mount.
+ *
+ * Any other render carries the visitor's theme (the unmatched-route 404 reads
+ * it without this function, rsc/handler.ts); when that differs from the
+ * default it marks `_payloadVisitorTheme`, and the document cache does not
+ * store the response.
  */
-export declare function payloadInitialTheme(reqCtx: Pick<RequestContext<any>, "_themeConfig" | "_shellCaptureRun" | "_readTheme">): Theme | undefined;
+export declare function payloadInitialTheme(reqCtx: Pick<RequestContext<any>, "_themeConfig" | "_shellCaptureRun" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "res">): Theme | undefined;