@rangojs/router 0.27.0 → 0.29.0

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

@@ -145,7 +145,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * the faulty per-colo entry ONLY when that fall-through found no good copy.
      *
      * The conditional evict is the load-bearing detail: when KV DOES serve a copy,
-     * kvGet* has already scheduled a same-key promote (`cache.put`); an eager
+     * readKv has already scheduled a same-key promote (`cache.put`); an eager
      * `cache.delete` here would race that put with no CF Cache API ordering
      * guarantee and could clobber the freshly-restored entry. So in that case we
      * lean on #558's heal-by-overwrite (the non-suppressed fall-through promotes /
@@ -164,7 +164,10 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private healCorruptL1;
     /**
      * Re-put a stale L1 entry marked REVALIDATING, so concurrent requests serve it
-     * without each triggering a revalidation. Shared by get()/getItem().
+     * without each triggering a revalidation (readL1). A JSON family re-puts its
+     * parsed body as a string, without a status text as set() writes it; the
+     * document re-puts a clone (`source`) whose original body still streams to
+     * the client.
      *
      * The write is NON-BLOCKING (waitUntil) and best-effort by design:
      * - It runs in waitUntil, so it never adds the put latency to the served stale
@@ -185,20 +188,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private markRevalidating;
-    /**
-     * Document-tier counterpart of markRevalidating for getResponse's herd guard.
-     * The segment/item tiers JSON-parse the body, so they re-put with a string
-     * body; document bodies are streamed verbatim, so we re-put with a CLONED
-     * response body (`response.clone()`) supplied by the caller -- the original
-     * body still streams to the client while the marker carries the clone. Same
-     * REVALIDATING status header, same revalidating-at stamp, same
-     * remainingCacheControl re-put math as markRevalidating, so the document tier
-     * suppresses concurrent revalidation for the identical MAX_REVALIDATION_INTERVAL
-     * window the segment tier does. Best-effort and non-blocking: a failed marker
-     * write must not affect the served stale read.
-     * @internal
-     */
-    private markResponseRevalidating;
     /**
      * Guard the segment tier against a `keyGenerator` that returns a key colliding
      * with a reserved tag-marker namespace: `__tag__/` (the KV marker key) or
@@ -212,17 +201,29 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private isReservedSegmentKey;
     /**
-     * Get cached entry data by key.
-     *
-     * Handles SWR atomically:
+     * Get cached entry data by key (readL1). On L1 miss, falls back to KV (L2)
+     * if configured; KV hits are promoted to L1 in the background.
+     */
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    /**
+     * The family's debug sink for one read; the document family is outside the
+     * debug surface (op is only get/getItem). Undefined when debug is off, so
+     * the hot path allocates no event.
+     * @internal
+     */
+    private debugSink;
+    /**
+     * The L1 read of a family, which handles SWR atomically:
      * - If stale and not already revalidating, marks as REVALIDATING and returns shouldRevalidate: true
      * - If already REVALIDATING (and recent), returns shouldRevalidate: false
      * - If fresh, returns shouldRevalidate: false
      *
-     * On L1 miss, falls back to KV (L2) if configured.
-     * KV hits are promoted to L1 in the background.
+     * Every degraded L1 read falls through to KV (readKv). The family methods
+     * return it unwrapped: an async wrapper adds two promises and two microtask
+     * ticks to every read.
+     * @internal
      */
-    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    private readL1;
     /**
      * Store entry data with TTL and optional SWR window.
      * Resolves once the L1 write lands, per the SegmentCacheStore.set contract
@@ -236,9 +237,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     delete(key: string): Promise<boolean>;
     /**
-     * Get a cached Response by key (for document-level caching).
-     * Returns the response and whether it should be revalidated (SWR).
-     * Falls back to KV (L2) on L1 miss.
+     * Get a cached Response by key (for document-level caching): see readL1.
+     * Its body streams to the client unread, outside the debug surface. Falls
+     * back to KV (L2) on L1 miss.
      */
     getResponse(key: string): Promise<{
         response: Response;
@@ -258,7 +259,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
     /**
      * Get a cached function result by key.
-     * Follows the same SWR pattern as get() for segment caching.
+     * Follows the same SWR pattern as get() for segment caching (readL1).
      * Falls back to KV (L2) on L1 miss.
      */
     getItem(key: string): Promise<CacheItemResult | null>;
@@ -351,7 +352,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * caller's `tagHints`: cfTagHints may have evicted the key while the memo
      * still holds it. A shell a tag marker rejects is dropped and read from
      * the store too, which may hold a capture from after the marker (see
-     * get(), "Tag invalidation"), unless the request's own mask rejected it
+     * readL1(), "Tag invalidation"), unless the request's own mask rejected it
      * (declinesKvFallThrough).
      */
     private readMemoizedShell;
@@ -538,15 +539,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private skipUncacheableTagSet;
-    /**
-     * Merge the internal tag headers onto an existing Headers instance. The
-     * from-scratch paths spread tagHeaderEntries() into an object-literal init;
-     * the document put/promote paths build a Headers first, so they .set() each
-     * entry instead — except `Cache-Tag`, which is APPENDED: a document author
-     * may have set their own Cache-Tag, and clobbering it would break their CDN
-     * purging. Append produces the comma-merged list CF expects.
-     */
-    private setTagHeaders;
     /** Read an entry's tags/taggedAt back from its headers. */
     private readTagInfo;
     /**
@@ -780,12 +772,27 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /** invalidateTags' marker writes, tag purge, and hooks. */
     private writeTagInvalidation;
     /**
-     * KV fallback for segment cache reads.
-     * Returns null if KV is not configured, entry is missing, or expired.
-     * Promotes hits to L1 via waitUntil.
+     * The KV (L2) read behind an L1 miss, for every family: a missing,
+     * timed-out, corrupt (kvGetOrEvict reports and evicts it), expired or
+     * tag-invalidated envelope is a miss, a read failure is the family's read
+     * error, and a hit is promoted to L1 in the background.
+     *
+     * A degraded L1 fall-through (body-timeout / non-200) passes
+     * `suppressRevalidate`: KV has no REVALIDATING herd guard, so N concurrent
+     * degraded reads would otherwise each spawn a render exactly when the colo
+     * is already struggling. The stale data is still served and promoted; only
+     * the revalidation is withheld.
+     * @internal
+     */
+    private readKv;
+    /**
+     * Promote a KV hit to L1 in the background, under its remaining ttl, with
+     * its deadlines (so a promoted entry that later goes stale re-puts with the
+     * correct remaining ttl, see set()) and its tags (so it stays
+     * tag-invalidatable). The family builds the entry (toL1).
      * @internal
      */
-    private kvGetSegment;
+    private promoteToL1;
     /**
      * Write segment data to KV.
      *
@@ -794,29 +801,4 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private kvSetSegment;
-    /**
-     * Promote segment data from KV to L1 Cache API.
-     * @internal
-     */
-    private promoteSegmentToL1;
-    /**
-     * KV fallback for function cache reads.
-     * @internal
-     */
-    private kvGetItem;
-    /**
-     * Promote function cache data from KV to L1.
-     * @internal
-     */
-    private promoteItemToL1;
-    /**
-     * KV fallback for document cache reads.
-     * @internal
-     */
-    private kvGetResponse;
-    /**
-     * Promote document cache data from KV to L1.
-     * @internal
-     */
-    private promoteResponseToL1;
 }

package/dist/types/cache/cf/cf-kv-utils.d.ts

@@ -37,7 +37,7 @@ export declare function kvKeyDigest(value: string): Promise<string>;
  * of restarting it -- copying set()'s original full-window max-age would reset
  * CF's retention clock on every re-arm and pin a perpetually-stale entry forever.
  * An entry lacking a valid deadline (legacy/tampered) floors to max-age=1, so it
- * hard-expires in ~1s and self-heals via KV. Mirrors promoteSegmentToL1's math.
+ * hard-expires in ~1s and self-heals via KV. Mirrors promoteToL1's math.
  * @internal
  */
 export declare function remainingCacheControl(headers: Headers, now: number): string;

package/dist/types/cache/handle-snapshot.d.ts

@@ -31,7 +31,7 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
  *
  * DSL-loader pushes stay out of the CACHE WRITE: a HIT runs loaders exactly
  * as an uncached render of the same request would (cache-lookup.ts
- * resolveFreshLoadersAndYield), so replaying a recorded copy would duplicate
+ * serveStoredSegments), so replaying a recorded copy would duplicate
  * the live push. Handler pushes, including
  * handler-invoked ctx.use(Loader) bodies (skipped with their handler on a
  * HIT), are kept. The store tags loader pushes by array position at push
@@ -75,19 +75,24 @@ export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
  * owner. Neither claims its loader, so the loader's own cache() HIT still
  * delivers (the pushes holding a promise a restored copy lets through, or its
  * entry's pushes in a placeholder's place).
+ *
+ * `sent` (a partial request) names the segments the response sends. Any
+ * other segment is kept with its handler's values, as on a live walk: only
+ * its loaders' copies are restored, which follow their loader as above.
  */
-export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
+export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery, sent?: ReadonlySet<string>): void;
 /**
  * Serve a doc record's handles: set its authority over the loaders' pushes
  * (with or without a handles blob: a pinned loader whose capture pushed
  * nothing has no copy, and its run must still add no settled push), then
  * decode and restoreHandles. `keepIds` limits the restore to the segments a
- * boundary-scoped scope serves. A decode failure skips the restore.
+ * boundary-scoped scope serves; `sent` is restoreHandles'. A decode failure
+ * skips the restore.
  */
 export declare function restoreRecordHandles(handleStore: HandleStore, record: {
     handles?: string;
     handleOwners?: HandleOwners;
-}, owned: OwnedPushDelivery | undefined, keepIds?: ReadonlySet<string>): Promise<void>;
+}, owned: OwnedPushDelivery | undefined, keepIds?: ReadonlySet<string>, sent?: ReadonlySet<string>): Promise<void>;
 /**
  * Append recorded handle pushes to the store, in recorded order, via push()
  * so active captures and loader-scope tagging see them like live pushes. For

package/dist/types/cache/segment-codec.d.ts

@@ -37,6 +37,20 @@ export declare function rscDeserialize<T>(encoded: string | undefined): Promise<
  * Returns null only on serialization failure.
  */
 export declare function serializeResult(value: unknown, onError?: (error: unknown) => void): Promise<string | null>;
+/** The Flight encode of a value and a decoded copy of it (teeResult). */
+export interface TeedResult {
+    /** The copy: settles when the root row arrives; later rows stream in. */
+    decoded: Promise<unknown>;
+    /** The whole encoded text, or null when the stream failed. */
+    serialized: Promise<string | null>;
+}
+/**
+ * Encode `value` once and decode a copy of it as the encode streams, so a
+ * "use cache" miss renders the copy as a hit renders a stored entry, and
+ * stores the same bytes. Null when the encode could not start.
+ */
+export declare function teeResult(value: unknown, onError?: (error: unknown) => void): TeedResult | null;
+export declare function isUnsupportedValueError(error: unknown): boolean;
 /**
  * RSC-deserialize a cached result string.
  * Counterpart to serializeResult() — always receives a non-empty string.

package/dist/types/cache/shell-snapshot.d.ts

@@ -210,7 +210,7 @@ export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[], on
 export declare const SHELL_HANDLES_RECORD_KEY = "handles";
 /**
  * The `handles` record of a prerender-served entry, which a HIT tail restores
- * after the prerender store's handles (cache-lookup.ts yieldFromStore), or
+ * after the prerender store's handles (cache-lookup.ts decodeStoredEntry), or
  * undefined: an entry with a doc record, or one written before the record
  * existed (v0.21), which serves as it did.
  */

package/dist/types/cache/taint.d.ts

@@ -11,9 +11,11 @@ export declare const NOCACHE_SYMBOL: unique symbol;
  */
 export declare function isTainted(value: unknown): boolean;
 /**
- * Symbol stamped on tainted ctx objects PASSED AS ARGUMENTS to a "use cache"
- * function during its execution. ctx.set(), ctx.header(), etc. check this
- * flag and throw if present — those side effects are lost on cache hit.
+ * Symbol stamped on tainted handler and middleware ctx objects PASSED AS
+ * ARGUMENTS to a "use cache" function during its execution. ctx.set(),
+ * ctx.header(), etc. check this flag and throw if present — those side
+ * effects are lost on cache hit. A request context passed as an argument is
+ * not stamped (registerCachedFunction in cache-runtime.ts).
  *
  * Argument objects only. Ambient access (cookies()/headers() and ctx methods
  * reached via getRequestContext()) is guarded by the AsyncLocalStorage scope

package/dist/types/cache/types.d.ts

@@ -86,10 +86,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * Return value becomes the final cache key (unless route overrides with `key` option).
      *
      * Resolution priority:
-     * 1. Route-level `key` function (full override)
+     * 1. Route-level `key` function (replaces the URL part; the request kind stays)
      * 2. Store-level `keyGenerator` (modifies default key)
      * 3. Default key generation (prefix:pathname:params)
      *
+     * Keep `defaultKey` in the result: its prefix names the request kind (a
+     * document, a navigation or an intercept navigation), whose records hold
+     * different segments. A result without it gives every kind one record.
+     *
      * Return `defaultKey` unchanged to leave a request unpartitioned. An empty
      * string is not a key: where the result partitions a nested cache() on
      * another store, or a ppr shell, it fails key resolution, so the request
@@ -250,7 +254,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
     /**
      * Declares the shell family present-but-inert: getShell/putShell exist but
      * no-op (a custom store whose backing tier is conditionally unavailable).
-     * scheduleShellCapture skips captures whose only write target is inert —
+     * planShellCapture skips captures whose only write target is inert —
      * the background render would be dead work that still occupies the
      * per-isolate serialized capture queue (a promise-heavy route bakes for
      * seconds per MISS with nothing stored). Absent/false means the family,
@@ -602,7 +606,7 @@ export type ShellSnapshotFamily = "segment" | "loader" | "handles";
  * format (CachedEntryData `handles` + `handleOwners`). A Prerender + ppr
  * route's handler layer comes from the prerender store, whose build-time
  * entry has no loader push, so the entry keeps these for the HIT to restore
- * as a doc record's (issue #1057, yieldFromStore in cache-lookup.ts). An
+ * as a doc record's (issue #1057, decodeStoredEntry in cache-lookup.ts). An
  * entry written before it (v0.21) has none and serves as it did.
  */
 export type ShellSnapshotHandlesValue = Pick<CachedEntryData, "handles" | "handleOwners">;

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

@@ -326,8 +326,14 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
      * `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;
+    /**
+     * The read of a data family (get, getItem, getResponse): a failed read is
+     * the family's `readError`; a missing, corrupt, expired or masked entry is a
+     * miss, and a corrupt or expired one is evicted. The hit is built before the
+     * stale claim, so an entry that does not rebuild is evicted as corrupt with
+     * no revalidation lock written for it.
+     */
+    private readRecord;
     private toStoreKey;
     private write;
     /**
@@ -370,8 +376,4 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
     private clampTagsForWrite;
     private safeDelete;
     private emitDebug;
-    private asSegmentEnvelope;
-    private asItemEnvelope;
-    private asShellEnvelope;
-    private asResponseEnvelope;
 }

package/dist/types/prefetch-markers.d.ts

@@ -1,21 +1,12 @@
 /**
- * The wire markers of prefetches, of `prefetch: false`
- * (docs/design/prefetch-false.md) and of stale requests: shared by the browser
- * and the server (router/segment-resolution/prefetch-deferral.ts requestKind,
- * rsc/prefetch-render-error.ts, rsc/rsc-rendering.ts,
- * cache/document-cache.ts, router/navigation-snapshot.ts). Dependency free,
- * like segment-fragments.ts: the browser must not import the server modules
- * that use them.
+ * The wire markers of prefetches: shared by the browser and the server
+ * (router/segment-resolution/prefetch-deferral.ts requestKind,
+ * rsc/prefetch-render-error.ts, rsc/rsc-rendering.ts). Dependency free, like
+ * segment-fragments.ts: the browser must not import the server modules that
+ * use them.
  */
 /** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
 export declare const PREFETCH_HEADER = "X-Rango-Prefetch";
-/** Query param of a fill request (browser/navigation-client.ts). */
-export declare const FILL_PARAM = "_rsc_fill";
-/**
- * Query param of a stale request (browser/navigation-client.ts): `revalidate()`
- * sees `stale: true` (router/navigation-snapshot.ts).
- */
-export declare const STALE_PARAM = "_rsc_stale";
 /**
  * The last row of a prefetch whose render reported an error
  * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not

package/dist/types/prerender/store.d.ts

@@ -54,6 +54,37 @@ export declare function createDevPrerenderStore(devUrl: string): PrerenderStore;
  * Returns null if no prerender data is available.
  */
 export declare function createPrerenderStore(): PrerenderStore | null;
+/**
+ * The segments of a prerendered URL's intercept variant (`/i`): the main
+ * variant's without the intercepted route's own (`belongsToRoute`: its
+ * handler, layouts and slots), then the intercept's. A render under an
+ * intercept skips the route's entry (resolveAllSegments), so the variant
+ * holds what a cache() intercept record holds. The producer
+ * (matchForPrerender) encodes `interceptHandles` for exactly these segments.
+ */
+export declare function interceptVariantSegments(segments: SerializedSegmentData[], interceptSegments: SerializedSegmentData[]): SerializedSegmentData[];
+/**
+ * The intercept variant as served under the intercept the match selected
+ * (findInterceptForRoute): its main segments and that intercept's slot,
+ * `slotId` in `intercept:<routeName>`. The build bakes every intercept that
+ * can target the route, since it cannot evaluate when(). Null when the
+ * variant does not hold that slot: the request renders live. The handles
+ * string is kept whole; decodeStoredEntry (cache-lookup.ts) replays only the
+ * served segments' pushes.
+ */
+export declare function selectInterceptVariant(entry: PrerenderEntry, slotId: string, routeName: string): PrerenderEntry | null;
+/**
+ * The manifest entries ([key, PrerenderEntry JSON]) one prerendered URL
+ * bakes, keyed as the production store's get() reads them. The intercept
+ * variant (`/i`) holds interceptVariantSegments with the handle string the
+ * producer encoded for it. Written by the build
+ * (vite/discovery/prerender-collection.ts) and serveShellRequest.
+ */
+export declare function prerenderManifestEntries(result: PrerenderEntry & {
+    routeName: string;
+    interceptSegments?: SerializedSegmentData[];
+    interceptHandles?: string;
+}, paramHash: string): Array<[key: string, value: string]>;
 /**
  * Create a static segment store.
  * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.

package/dist/types/prerender/warm-request.d.ts

@@ -7,7 +7,7 @@
  * layers import this without pulling the trigger.
  */
 import type { HandlerCacheConfig } from "../rsc/types.js";
-import type { ShellCaptureDebugEvent } from "../rsc/shell-capture.js";
+import type { ShellCaptureDebugEvent, ShellCaptureState } from "../rsc/shell-capture.js";
 import type { PrerenderWarmCaches } from "./on-demand.js";
 /** What one warm request did: written by the layers, read by the trigger. */
 export interface PrerenderWarmRecord extends PrerenderWarmCaches {
@@ -33,7 +33,7 @@ export interface PrerenderWarmRecord extends PrerenderWarmCaches {
 /** What the helpers read; a derived capture context inherits the record. */
 export interface WarmContext {
     _prerenderWarm?: PrerenderWarmRecord;
-    _shellCaptureRun?: boolean;
+    _shellCaptureState?: Pick<ShellCaptureState, "run">;
 }
 export declare function createWarmRecord(mode: PrerenderWarmRecord["mode"], cacheConfig: HandlerCacheConfig): PrerenderWarmRecord;
 /** The mark is the object: a clone or a rebuilt request carries none. */
@@ -46,7 +46,7 @@ export declare function readWarmMark(request: Request): PrerenderWarmRecord | un
  * "use cache" in-flight dedup lives outside the store, so a wrapper would
  * miss both.
  *
- * False in the warm's own shell capture (`_shellCaptureRun`): it runs after
+ * False in the warm's own shell capture (`_shellCaptureState`): it runs after
  * the warm's writes settled and must replay them, or it would render every
  * handler a second time and could bake another generation than the one just
  * written.

package/dist/types/prerender.d.ts

@@ -264,8 +264,8 @@ export declare function isPrerenderPassthrough(value: unknown): value is Prerend
  * A build handler signals passthrough by returning `ctx.passthrough()` (the
  * PRERENDER_PASSTHROUGH sentinel), which lands on the segment's `component`.
  * But when the route declares `loading()`, the handler result is deferred
- * upstream (segment-resolution/fresh.ts), so `component` is a thenable resolving
- * to the sentinel rather than the sentinel itself — a synchronous
+ * upstream (resolveEntryHandler), so `component` is a thenable
+ * resolving to the sentinel rather than the sentinel itself — a synchronous
  * `isPrerenderPassthrough(component)` on the Promise returns false and the build
  * bakes a corrupt artifact instead of deferring. Resolve thenables first.
  *

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

@@ -32,3 +32,8 @@ export declare function publicRouteName(routeKey: string | undefined): string |
  * Throws with a clear message when a reserved prefix is detected.
  */
 export declare function validateUserRouteName(name: string): void;
+/**
+ * The route key's last name segment ("item" for "shop.item"). An intercept
+ * that targets it is selected when none targets the full key (match-api.ts).
+ */
+export declare function localRouteName(routeKey: string): string;

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

@@ -25,7 +25,7 @@ export interface InvokeOnErrorContext<TEnv = any> {
     isPartial?: boolean;
     handledByBoundary?: boolean;
     metadata?: Record<string, unknown>;
-    /** Request start time from performance.now() for duration calculation */
+    /** performance.now() at request entry; the request context's by default. */
     requestStartTime?: number;
 }
 /**
@@ -35,6 +35,12 @@ export interface InvokeOnErrorContext<TEnv = any> {
  * This is a shared utility used by both the router and RSC handler to ensure
  * consistent error callback behavior across the codebase.
  *
+ * `background` is set inside runAsBackgroundWork (server/request-context.ts),
+ * and `duration` and `env` come from the request context on the ALS
+ * (`_handlerStart`, `env`) when the call site leaves them out, so no call
+ * site has to know. A Prerender pass's ctx.env throws without buildEnv, so
+ * the walk never reads it eagerly.
+ *
  * @param onError - The onError callback to invoke (may be undefined)
  * @param error - The error that occurred
  * @param phase - The phase where the error occurred
@@ -45,10 +51,10 @@ export declare function invokeOnError<TEnv = any>(onError: OnErrorCallback<TEnv>
 /**
  * First non-undefined `pick(orphan)` over the routeless entries in
  * `entry.layout` and, recursively, in theirs: depth-first in render order
- * (resolveOrphanLayout in segment-resolution/fresh.ts). Since #922 a routeless
- * entry nested in another renders (a layout() after a bare cache() marker, a
- * layout() in a routeless wrapper); a one-level scan missed the boundaries and
- * intercepts it declares (#926).
+ * (resolveOrphanLayout in segment-resolution/revalidation.ts).
+ * Since #922 a routeless entry nested in another renders (a layout() after a
+ * bare cache() marker, a layout() in a routeless wrapper); a one-level scan
+ * missed the boundaries and intercepts it declares (#926).
  *
  * `skip` is the entry an upward walk came from. Only a bare cache() marker is
  * both in its layout's layout[] and in the chain, and its subtree was already

package/dist/types/router/instrument.d.ts

@@ -190,9 +190,10 @@ export declare function observeSegmentHandler<C, R>(segmentId: string, spanId: s
  *     loop (request.start/end/error, cache.decision, ...).
  *   - segment-resolution/helpers.ts emits via a caller-provided report.telemetry
  *     sink rather than the ALS router context.
- *   - rsc/handler.ts handleTimeoutResponse (request.timeout), the origin guard
- *     (request.origin-rejected), and handleStore.onError (late-handle
- *     handler.error) emit via router.telemetry directly — they run outside the
+ *   - rsc/request-stages.ts timeoutResponse (request.timeout) and
+ *     originRejectedResponse (request.origin-rejected), and rsc/handler.ts
+ *     handleStore.onError (late-handle handler.error) emit via
+ *     router.telemetry directly — they run outside the
  *     RouterContext ALS (only match()/matchPartial() enter it), so a
  *     getRouterContext() read there throws and the event would vanish.
  */

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

@@ -5,9 +5,8 @@
  * functions for soft navigation (modals).
  */
 import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
-import type { HandlerContext, ResolvedSegment } from "../types";
-import type { SegmentResolutionDeps } from "./types.js";
-import type { RevalidationContext } from "./router-context.js";
+import type { ResolvedSegment } from "../types";
+import type { ResolutionPass } from "./segment-resolution/resolution-pass.js";
 /**
  * Check if an intercept's when conditions are satisfied.
  * All when() functions must return true for the intercept to activate.
@@ -40,6 +39,19 @@ export declare function findInterceptForRoute(targetRouteKey: string, fromEntry:
 } | null;
 /** The segment id of `intercept`'s slot on `parentEntry`. */
 export declare function interceptSlotId(parentEntry: EntryData, intercept: InterceptEntry): string;
+/**
+ * The intercept a match selected (findInterceptForRoute), as its cache()
+ * record names it (CacheScope): the slot id, then `~` and its position among
+ * the intercepts its entry declares for the same slot and target route. Two
+ * such intercepts share the slot id, and the position tells them apart; one
+ * for another slot or route does not renumber it. `~` is unreserved in a
+ * URL, so a store that maps the key onto one unencoded keeps the whole key.
+ * Undefined when the match selected none.
+ */
+export declare function interceptRecordKey(selected: {
+    intercept: InterceptEntry;
+    entry: EntryData;
+} | null): string | undefined;
 /**
  * Every segment id an intercept's slot owns, in order: the slot, then one
  * loader segment per loader in declaration order, run or not. A request that
@@ -47,15 +59,19 @@ export declare function interceptSlotId(parentEntry: EntryData, intercept: Inter
  */
 export declare function interceptSegmentIds(parentEntry: EntryData, intercept: InterceptEntry): string[];
 /**
- * Resolve an intercept entry: its slot segment, then its loader segments.
+ * Resolve an intercept entry: its slot segment, then its loader segments. The
+ * background re-render resolves with a pass that holds nothing
+ * (heldNothingPassInput, resolution-pass.ts): every segment renders fresh, and
+ * its loaders are skipped (skipLoaders), each registered for the handler's
+ * read.
  */
-export declare function resolveInterceptEntry<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext?: RevalidationContext, options?: {
+export declare function resolveInterceptEntry<TEnv>(pass: ResolutionPass<TEnv>, interceptEntry: InterceptEntry, parentEntry: EntryData, belongsToRoute: boolean, options?: {
     /**
      * Set ONLY by the post-response background re-render (stale background
      * revalidation), whose sole purpose is to re-render the segment tree to
-     * populate the cache: a handler error rejects instead of rendering the
-     * error boundary, so a failure is never cached. Never set on the
-     * foreground path.
+     * populate the cache: a handler error is reported, then rejects instead
+     * of rendering the error boundary, so a failure is never cached. Never
+     * set on the foreground path.
      */
     background?: boolean;
 }): Promise<ResolvedSegment[]>;
@@ -63,4 +79,4 @@ export declare function resolveInterceptEntry<TEnv>(interceptEntry: InterceptEnt
  * The loader segments of a cached intercept slot, on a cache hit: the slot
  * keeps its cached component and layout, its loaders are never cached.
  */
-export declare function resolveInterceptLoadersOnly<TEnv>(interceptEntry: InterceptEntry, parentEntry: EntryData, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, revalidationContext: RevalidationContext): Promise<ResolvedSegment[]>;
+export declare function resolveInterceptLoadersOnly<TEnv>(pass: ResolutionPass<TEnv>, interceptEntry: InterceptEntry, parentEntry: EntryData, belongsToRoute: boolean): Promise<ResolvedSegment[]>;

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

@@ -63,7 +63,6 @@
  *
  * Handler Context:
  *   - handlerContext: Context passed to loaders
- *   - loaderPromises: Memoized loader promises
  *
  * Intercepts:
  *   - interceptResult: Detected intercept (if soft navigation)
@@ -114,15 +113,8 @@ import type { EntryData, InterceptSelectorContext, MetricsStore } from "../serve
 import type { HandlerContext, ResolvedSegment } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { InterceptResult } from "./router-context.js";
-/**
- * Action context passed to matchPartial
- */
-export interface ActionContext {
-    actionId?: string;
-    actionUrl?: URL;
-    actionResult?: any;
-    formData?: FormData;
-}
+import type { ResolutionPassInput } from "./segment-resolution/resolution-pass.js";
+import type { ActionContext } from "./types.js";
 /**
  * Match context containing all state for the match pipeline
  */
@@ -134,6 +126,8 @@ export interface MatchContext<TEnv = any> {
     clientSegmentIds: string[];
     clientSegmentSet: Set<string>;
     stale: boolean;
+    /** NavigationSnapshot.heldBoundary: the walk stops above it. */
+    heldBoundary?: string;
     prevUrl: URL;
     prevParams: Record<string, string>;
     prevMatch: RouteMatchResult | null;
@@ -143,7 +137,6 @@ export interface MatchContext<TEnv = any> {
     routeKey: string;
     localRouteName: string;
     handlerContext: HandlerContext<any, TEnv>;
-    loaderPromises: Map<string, Promise<any>>;
     routeMap: Record<string, string>;
     metricsStore: MetricsStore | undefined;
     Store: any;
@@ -174,6 +167,8 @@ export interface MatchContext<TEnv = any> {
  * stored, so a record can be older than the copy the client holds after it.
  */
 export declare function rendersLive(ctx: Pick<MatchContext, "isAction" | "stale">): boolean;
+/** This match as the input of a revalidating resolution pass (resolution-pass.ts). */
+export declare function resolutionPassInput<TEnv>(ctx: MatchContext<TEnv>): ResolutionPassInput<TEnv>;
 /**
  * Mutable state that flows through the pipeline
  */