@rangojs/router 0.17.0 → 0.19.0

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

@@ -5,9 +5,11 @@
  * `@vercel/functions`). It is the production store analogue to CFCacheStore, but
  * 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, KV tag-marker comparison, marker memoization, or per-tier
- * timeout budgets are needed here - the platform does that work. What this store
- * adds on top of the raw primitive is the parts Vercel does NOT give us:
+ * L1/L2 tiering or per-tier timeout budgets are needed here - the platform does
+ * 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
  *      simply becomes a miss. We store our own {staleAt, expiresAt} envelope and
@@ -30,8 +32,9 @@
  * `getCache(...)` result, which satisfies the shape structurally. That keeps the
  * router free of a hard Vercel dependency.
  */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, CacheReadError } from "../types.js";
-import type { RequestContext } from "../../server/request-context.js";
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
+import { type RequestContext } from "../../server/request-context.js";
+import { type StoreMemoOptions } from "../shell-memo.js";
 /**
  * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
  * from `@vercel/functions`. Declared locally so @rangojs/router carries no hard
@@ -69,7 +72,7 @@ export declare const VERCEL_MAX_TAGS_PER_ITEM: number;
 /** Max tag length in UTF-8 bytes accepted by Vercel; longer tags are skipped. */
 export declare const VERCEL_MAX_TAG_BYTES: number;
 /** Read-path outcome for the debug sink. */
-export type VercelCacheReadOutcome = "miss" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
+export type VercelCacheReadOutcome = "miss" | "memo-hit" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
 /** Diagnostic event emitted on every read when `debug` is set. */
 export interface VercelCacheReadDebugEvent {
     op: "get" | "getItem" | "getResponse" | "getShell";
@@ -100,10 +103,13 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      */
     cache: VercelRuntimeCache;
     /**
-     * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
-     * write (herd dampening) off the response path - the router already
-     * backgrounds the actual writes. When omitted, the lock write runs detached
-     * (fire-and-forget) instead.
+     * `waitUntil` from `@vercel/functions`. Keeps two background reads/writes
+     * alive past the response: the stale-read lock write (herd dampening; the
+     * router already backgrounds the actual writes) and the PPR shell reads'
+     * tag-marker memo refreshes (`memo.markerMaxStaleMs`). When omitted, both
+     * run detached (fire-and-forget), and the platform may end a refresh when
+     * the response ends; the next read past the stale window then reads the
+     * marker itself.
      */
     waitUntil?: (promise: Promise<unknown>) => void;
     /**
@@ -136,6 +142,26 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      * receives the structured VercelCacheReadDebugEvent.
      */
     debug?: VercelCacheDebug;
+    /**
+     * Per-process memos ({@link StoreMemoOptions}), kept per `cache` handle:
+     * create the `getCache()` handle once per process, not per request, or the
+     * memos never hit. `shellMs` (default 2000) and `shellMaxBytes` (default
+     * 16 MiB) size the PPR shell memo; `markerFreshMs` (default 300) and
+     * `markerMaxStaleMs` (default 2000) the memo of the tag markers
+     * `invalidateTags()` writes, which PPR shell reads use
+     * (stale-while-revalidate). The process that invalidates writes the new
+     * marker into its memo; another process in the region rejects a memoized
+     * shell once its marker memo sees it (up to `markerMaxStaleMs`). The
+     * markers are a regional `cache.set` (only `expireTag` is global), so
+     * another region serves a shell it memoized before the invalidation until
+     * its window passes, where without the memo `expireTag` removes it within
+     * about 300 ms; a platform `expireTag` issued outside rango is likewise
+     * seen once the window passes. The response of a request that ran
+     * `updateTag()` / `revalidateTag()` sets the fresh-reads cookie, and the
+     * same user's requests carrying it skip both memos. `{ shellMs: 0 }` turns
+     * the shell memo off, `{ markerFreshMs: 0 }` the marker memo.
+     */
+    memo?: StoreMemoOptions;
 }
 /**
  * Vercel Runtime Cache-backed segment cache store.
@@ -170,12 +196,18 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
  * import { getCache, waitUntil } from "@vercel/functions";
  * import { VercelCacheStore } from "@rangojs/router/cache";
  *
+ * // One handle per process: getCache() resolves the platform cache on every
+ * // call, and the PPR shell and tag-marker memos are kept per handle.
+ * // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
+ * // would be undefined here) so cross-deploy busting via `version` works.
+ * const runtimeCache = getCache({
+ *   namespace: process.env.VERCEL_DEPLOYMENT_ID,
+ * });
+ *
  * export const router = createRouter({
  *   cache: () => ({
  *     store: new VercelCacheStore({
- *       // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
- *       // would be undefined here) so cross-deploy busting via `version` works.
- *       cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+ *       cache: runtimeCache,
  *       waitUntil,
  *       defaults: { ttl: 60, swr: 300 },
  *     }),
@@ -191,6 +223,16 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
     private readonly waitUntil?;
     private readonly version?;
     private readonly maxItemBytes;
+    private readonly memo;
+    private readonly handleMemos;
+    /** @internal SegmentCacheStore.freshReadsWindowMs */
+    readonly freshReadsWindowMs: number;
+    /**
+     * @internal SegmentCacheStore.maxShellEntryBytes: the item cap, less the
+     * base64 expansion of the prelude the shell envelope stores (the capture
+     * measures raw prelude bytes).
+     */
+    readonly maxShellEntryBytes: number;
     private readonly name?;
     private readonly debug?;
     constructor(options: VercelCacheStoreOptions<TEnv>);
@@ -210,15 +252,78 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
+    /**
+     * @internal The document serve path's read (SegmentCacheStore
+     * .readShellDocument): the same read as getShell, with the prelude decoded
+     * here, once per memoized shell rather than once per HIT, and the read's
+     * `debugPerformance` stats. The runtime cache returns a parsed value, so
+     * there is no prelude-first read and the tag-marker read follows the entry
+     * read (`markerSerial`).
+     */
+    readShellDocument(key: string, options?: ShellDocumentReadOptions): Promise<ShellDocumentRead | null>;
+    /** @internal SegmentCacheStore.dropShellMemo */
+    dropShellMemo(key: string): void;
+    /**
+     * getShell's read, shared with readShellDocument: the shell memo first
+     * (shell-memo.ts), then the runtime cache. A memoized shell still runs the
+     * tag-marker check; `memoized` is the memo slot's value when the read came
+     * from, or went into, the memo (readShellDocument keeps the decoded prelude
+     * there).
+     */
+    private readShell;
+    /**
+     * The shell's tag-marker check, timed into `stats`. Markers a prefetch
+     * already started (hinted tags) are awaited, not re-read; the check itself
+     * always uses the entry's own tags.
+     */
+    private shellTagsInvalidated;
+    /**
+     * Start the tm-marker reads of the tags this shell key carried last time
+     * (and the route's static tags) alongside the entry read.
+     */
+    private prefetchShellMarkers;
+    /**
+     * A tag's latest invalidatedAt (or null). With `isolateMemo` (PPR shell
+     * reads only) through the per-process marker memo (isolate-tag-memo.ts):
+     * 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, 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): 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 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. */
+    private maskedMiss;
     private toStoreKey;
     private write;
     /**

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/prerender/build-shell-capture.d.ts

@@ -4,9 +4,9 @@
  * Runs in the RSC realm of the build's temp server, AFTER all bundles are
  * written (the prelude embeds built client asset URLs — bootstrap module,
  * chunk preloads — that only exist post-client-build). The capture core is
- * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
- * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
- * quiesce, tags union, putShell barrier). Build capture first replays global
+ * producer A's, verbatim: deriveShellCaptureContext (push funnel, snapshot
+ * recording, implicit doc-cache scope) + settleCaptureRecord (the record-first
+ * step) + captureAndStoreShell (gates, quiesce, tags union, putShell barrier). Build capture first replays global
  * and route middleware with a synthetic build request context
  * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
  * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
@@ -95,10 +95,17 @@ export interface BuildShellCaptureResult {
     tags?: string[];
     /** On route-mismatch: what this router's match actually landed on. */
     matchedRouteName?: string;
+    /**
+     * On no-shell: the attempt ran out of ppr.captureTimeout. It is not
+     * retried: its match may still be running, and the retry would start the
+     * same work beside it (runtime twin: shell-capture.ts runShellCapture).
+     */
+    timedOut?: true;
 }
 /**
  * Capture the PPR shell for one prerendered URL at build time. Retries once
  * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
- * transform graph, mirroring producer A's cold-start retry — same delay).
+ * transform graph, mirroring producer A's cold-start retry — same delay),
+ * unless the attempt ran out of ppr.captureTimeout (`timedOut`).
  */
 export declare function captureShellForBuild(opts: BuildShellCaptureOptions): Promise<BuildShellCaptureResult>;

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/instrument.d.ts

@@ -163,6 +163,14 @@ export declare function observePhase<T>(spec: PhaseSpec, fn: (span: TraceSpan) =
  * nothing to record here and short-circuits.
  */
 export declare function observeHandler<C, R>(id: string, handler: (ctx: C) => R, ctx: C): R;
+/**
+ * observeHandler, inside segment `segmentId`'s tag scope, so the tags the
+ * handler records reach the route's cache() record (#957, cache-tag.ts
+ * runInSegmentTagScope). `spanId` is observeHandler's `id`. A request that
+ * cannot write a record takes observeHandler's path as is, with the same one
+ * request-context read: no scope, no closure.
+ */
+export declare function observeSegmentHandler<C, R>(segmentId: string, spanId: string, handler: (ctx: C) => R, ctx: C): R;
 /**
  * Emit one discrete telemetry event (the event-shaped counterpart to
  * observePhase). Resolves the sink from the active router context and stamps the

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/middleware-types.d.ts

@@ -48,7 +48,12 @@ export interface MiddlewareContext<TEnv = any, TParams = Record<string, string |
     header(name: string, value: string): void;
     routeName?: DefaultRouteName;
     debugPerformance(): void;
-    theme?: Theme;
+    /**
+     * The visitor's theme (cookie or default); undefined without theme config.
+     * Guarded like `cookies()`: a read inside a `"use cache"` function throws
+     * (#971).
+     */
+    readonly theme?: Theme;
     setTheme?: (theme: Theme) => void;
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
     /** Global route names only; see {@link GlobalReverseFunction}. */

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
  *
@@ -17,15 +18,55 @@
  * On stale hit (SWR): returns stale data, schedules background revalidation.
  * On miss: executes loader, schedules non-blocking cache write.
  *
+ * Identity (#972): without a key() or a store keyGenerator the entry is
+ * shared across users, so a fill whose execution recorded a request-identity
+ * read fails and is not stored, whoever started that execution
+ * (server/context.ts recordLoaderIdentityRead).
+ *
  * Handle pushes (`ctx.use(Handle)(...)` in the loader body) are a side effect
  * the HIT must reproduce: the MISS records the pushes of the body and of the
  * loaders it awaits via ctx.use into the entry's `handles` blob (the
  * "use cache" capture/encode), and every HIT — stale included — replays
  * them, each loader's pushes at most once per request (a dependency another
  * reader already ran keeps its live pushes). See replayLoaderHandles.
+ *
+ * Tags too (#964): the entry stores its cache() tags plus every tag its
+ * execution recorded, those of the loader values it read included
+ * (cache-tag.ts "Recorded-tag sets"), so updateTag() of any of them drops it.
+ * Every HIT records the stored tags through the loader's tag owner
+ * (recordLoaderTags), so a route cache() record, PPR shell or document built
+ * over the HIT carries them, and a loader that reads this one takes them on.
+ * Once the binding started, a loader body's ctx.use of it gets the same
+ * dataPromise as a handler read (createLoaderExecutor's useLoader); a stale
+ * refresh does not (setupLoaderAccess _runLoaderIsolated).
  */
-import { type LoaderEntry } from "../../server/context.js";
+import { type EntryData, type LoaderEntry } from "../../server/context.js";
 import type { HandlerContext } from "../../types.js";
+/**
+ * Whether a request over the matched chain `entries` resolves a loader bound
+ * with its own cache(): on a chain entry, or on its parallel slots, orphan
+ * layouts or intercepts. The match arms the per-execution loader tag sets on
+ * it (cache-tag.ts armLoaderTagSets), before any loader starts, so a
+ * dependency the handler or another binding starts first still records.
+ * 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.
  *
@@ -46,18 +87,23 @@ import type { HandlerContext } from "../../types.js";
  * never run under a shell capture), so the lane is decided here, per LOADER,
  * never by the entry's loading():
  *
- * - BAKE lane: `loader(Def, { ssr: false })` (awaitBeforeFlush) with a
- *   `bakeSegmentKey` from the caller. The loader EXECUTES at capture (the
+ * - BAKE lane: `loader(Def, { ssr: false })` (LoaderEntry `bake`: the
+ *   caller passes a `bakeSegmentKey` for it on document and navigation
+ *   evaluations alike; a capture, a document evaluation, also has
+ *   awaitBeforeFlush). The loader EXECUTES at capture (the
  *   flag's "data in the HTML before first flush" maps to the frozen prelude)
  *   and its settled non-promise data bakes into the shell. Promises nested in
- *   plain objects/arrays are masked (mask-nested.ts) and stay live holes at
- *   the consumer's own Suspense — per-request material must be promise-shaped
- *   (the #692 cross-session scar). The masked container registers on
- *   `_shellCaptureLoaderRecords`: it holds the capture gate (bounded by
- *   `ppr.captureTimeout`) and pins into the snapshot's loader family, and on a
- *   HIT the recorded container is overlaid onto the fresh run (below) so the
- *   payload matches the frozen prelude byte-for-byte. cookies()/headers() in
- *   its body (nested promise bodies included) trip the capture guard.
+ *   plain objects, arrays and JSX props are masked (mask-nested.ts) and stay
+ *   live holes at the consumer's own Suspense — per-request material must be
+ *   promise-shaped (the #692 cross-session scar). The masked container
+ *   registers on `_shellCaptureLoaderRecords`: it holds the capture gate
+ *   (bounded by `ppr.captureTimeout`) and pins into the snapshot's loader
+ *   family, and on a HIT the recorded container is overlaid onto the fresh
+ *   run (below) so the payload matches the frozen prelude outside the holes.
+ *   A server-component element holding a promise is a hole as a whole, so its
+ *   other props come from the fresh run (loader-snapshot.ts
+ *   elideLoaderContainer). cookies()/headers() in its body (nested promise
+ *   bodies included) trip the capture guard.
  * - LIVE lane: every other loader, whatever its entry's loading(). Never
  *   executes at capture: the slot gets a never-resolving promise
  *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an

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";