@rangojs/router 0.27.0 → 0.28.0

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

@@ -45,10 +45,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
  */
@@ -143,7 +135,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 +165,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
  */

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

@@ -1,9 +1,8 @@
 import type { ReactNode } from "react";
 import type { ErrorBoundaryHandler, ErrorInfo, ErrorPhase, MatchResult } from "../types";
 import { type EntryData, type InterceptEntry, type InterceptSelectorContext } from "../server/context.js";
-import type { MatchApiDeps } from "./types.js";
+import type { ActionContext, MatchApiDeps } from "./types.js";
 import type { RouterContext } from "./router-context.js";
-import { type ActionContext } from "./match-context.js";
 import type { MiddlewareFn } from "./middleware.js";
 import { type TelemetrySink } from "./telemetry.js";
 export interface MatchHandlerDeps<TEnv = any> {
@@ -33,11 +32,8 @@ export interface MatchHandlers<TEnv = any> {
             handler: MiddlewareFn;
             params: Record<string, string>;
         }>;
-        responseType?: string;
-        handler?: Function;
         params?: Record<string, string>;
-        negotiated?: boolean;
-        manifestEntry?: EntryData;
+        routeKey?: string;
     } | null>;
 }
 /**

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

@@ -36,7 +36,7 @@
  *         |
  *         v
  *   +---------------------------+
- *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
+ *   | FRESH segment pass      |  Fresh resolution (no revalidation)
  *   | + resolveIntercepts()   |  Ensures complete components
  *   +---------------------------+
  *         |
@@ -94,10 +94,12 @@
  * FRESH RESOLUTION (NO REVALIDATION)
  * ===================================
  *
- * Both full and partial requests use resolveAllSegments() (without
+ * Both full and partial requests resolve with a FRESH pass (without
  * revalidation logic) to ensure all segments have complete components.
  * Using revalidation-aware resolution would produce null components
- * for skipped segments, which would corrupt the cache entry.
+ * for skipped segments, which would corrupt the cache entry. Under an
+ * intercept the walk still skips the intercepted route's entry, as the MISS
+ * does: an intercept: record never holds the route's page.
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
@@ -118,23 +120,11 @@ import { type RequestContext } from "../../server/request-context.js";
  * MAX_REVALIDATION_INTERVAL, as after a refresh that throws.
  *
  * Runs on a DERIVED request context that owns the per-render state the
- * foreground reads while it is still producing the page (a stale HIT re-runs
- * its loaders; a proactive render starts once the Response exists, while its
- * body streams):
- *   - _handleStore: read late (loader pushes and aux-lane tracking in
- *     loader-resolution.ts, nested cache restores and captures in
- *     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.
- *   - _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
- *     needs its own run.
- *   - response writes (headers, cookies, status, onResponse callbacks) go to
- *     a throwaway context (whose status gates the write, above) and are
- *     dropped: a layout above the cache() boundary is outside the header
- *     guard and an error boundary sets a status, so they would otherwise
- *     reach the live response.
+ * foreground reads while it is still producing the page:
+ * RENDER_PASS_FIELDS["background-revalidation"] (server/render-pass.ts) lists
+ * each field and why. The DSL store below has `metrics` unset too (track()
+ * reads that one), so nothing lands on the foreground's perf timeline;
+ * ctx.Store.run closes over ctx.Store, so the derived store needs its own run.
  * runWithRequestContext also re-establishes the request ALS, which a waitUntil
  * task on workerd loses; the DSL store is a different ALS (build context).
  */

package/dist/types/router/match-middleware/cache-lookup.d.ts

@@ -1,95 +1,44 @@
 /**
  * Cache Lookup Middleware
  *
- * First middleware in the pipeline. Checks cache before segment resolution.
+ * First middleware in the pipeline. Before segment resolution runs, it serves
+ * a stored match from the first source that answers:
  *
- * FLOW DIAGRAM
- * ============
- *
- *   source (empty)
- *         |
- *         v
- *   +---------------------+
- *   | Is action request?  |──yes──> yield* source (pass through)
- *   +---------------------+
- *         | no
- *         v
- *   +---------------------+
- *   | Cache enabled?      |──no───> yield* source (pass through)
- *   +---------------------+
- *         | yes
- *         v
- *   +---------------------+
- *   | Lookup cache        |
- *   | (pathname, params)  |
- *   +---------------------+
- *         |
- *   +-----+-----+
- *   |           |
- *  miss        hit
- *   |           |
- *   v           v
- * yield*    Set state.cacheHit = true
- * source    Set state.shouldRevalidate
- *   |           |
- *   |           v
- *   |    +---------------------------+
- *   |    | For each cached segment:  |
- *   |    |  - Apply revalidation     |
- *   |    |  - Set component = null   |
- *   |    |    if client has it       |
- *   |    +---------------------------+
- *   |           |
- *   |           v
- *   |    +---------------------------+
- *   |    | Resolve fresh loaders     |  <-- Loaders are NEVER cached
- *   |    | (always fresh data)       |
- *   |    +---------------------------+
- *   |           |
- *   |           v
- *   |    yield cached segments
- *   |    yield fresh loader segments
- *   |           |
- *   +-----------+
- *         |
- *         v
- *      next middleware
+ *   1. Prerender: the writable on-demand overlay, then the bundled build
+ *      manifest. A live render (an action or a stale partial) reads them too
+ *      when the route has no live handler (not a Passthrough).
+ *   2. The dev Static store (`__PRERENDER_DEV_URL`, isStaticPrerender entries).
+ *   3. The route's cache() record (the segment cache). An action or a stale
+ *      partial renders live (rendersLive) and reads no record.
  *
+ * Every source serves through serveStoredSegments: pre-rendering is caching
+ * at build time, so a prerender entry is a cache hit through the same segment
+ * path. When no source answers, the request passes through to
+ * segment-resolution.
  *
- * CACHE BEHAVIOR
- * ==============
+ * A STORED HIT
+ * ============
  *
- * Cache HIT:
  *   - state.cacheHit = true signals downstream middleware to skip
- *   - Cached segments have their components nullified if client already has them
- *   - Loaders are always re-resolved for fresh data
- *   - state.shouldRevalidate triggers background SWR if cache was stale
- *
- * Cache MISS:
- *   - Passes through to segment-resolution middleware
- *   - No segments yielded from this middleware
- *
- * Loaders:
- *   - NEVER cached in the segment cache
- *   - Always resolved fresh on every request
- *   - Ensures data freshness even with cached UI components
- *   - Segment cache staleness does NOT propagate to loader revalidation;
+ *   - A segment the client already holds and keeps has its component nullified
+ *   - Loaders are always re-resolved fresh: never cached or pre-rendered.
+ *     Segment cache staleness does NOT propagate to loader revalidation;
  *     loaders use their own revalidation rules (actionId, user-defined)
+ *   - A cache() record sets state.shouldRevalidate, which triggers background
+ *     SWR when the record was stale
  *
+ * REVALIDATION RULES (cache() record)
+ * ===================================
  *
- * REVALIDATION RULES
- * ==================
- *
- * Each cached segment is evaluated against its revalidation rules:
+ * Each record segment the client holds is evaluated against its rules:
  *
- *   1. No rules defined -> use default (skip if client has segment)
+ *   1. No rules defined -> re-render the route's own segments when the search
+ *      or the route params changed; otherwise skip (nullify component)
  *   2. Rules return false -> skip re-render (nullify component)
  *   3. Rules return true -> re-render (keep component)
  *
- * Revalidation context includes:
- *   - Previous/next URL and params
- *   - Request object
- *   - Action context (if POST)
+ * Revalidation context includes the previous/next URL and params, the request
+ * and the action context (if POST).
  */
 import type { ResolvedSegment } from "../../types.js";
 import { type EntryData } from "../../server/context.js";
@@ -112,7 +61,7 @@ export declare function setPrerenderStoreForTests(store: PrerenderStore | null |
  * misses the store and renders live, and replay — including its heal
  * capture — must stay available for it (withCacheStore records the doc
  * record on that path; state.cacheSource is not "prerender"). The store
- * memoizes per routeKey/paramHash, so this probe and tryPrerenderLookup's
+ * memoizes per routeKey/paramHash, so this probe and readPrerenderSource's
  * subsequent get() share one underlying load.
  */
 export declare function prerenderEntryExists(routeKey: string | undefined, params: Record<string, string>, pathname: string, entries: EntryData[]): Promise<boolean>;
@@ -127,14 +76,13 @@ export type GeneratorMiddleware<T> = (source: AsyncGenerator<T>) => AsyncGenerat
 /**
  * Creates cache lookup middleware
  *
- * Checks cache for segments. If cache hit:
- * - Applies revalidation to determine which segments need re-rendering
- * - Resolves loaders fresh (loaders are NOT cached by design)
- * - Sets state.cacheHit = true
- * - Sets state.shouldRevalidate if SWR needed
- * - Yields cached segments + fresh loader segments
+ * The middleware is serveStoredSegments. It serves a stored match when one
+ * answers, in this order: the prerender overlay and build store (Prerender
+ * and on-demand routes), the dev Static store, then the route's cache()
+ * record. It yields the stored segments and the loaders resolved fresh and
+ * sets state.cacheHit (and state.shouldRevalidate for a cache() record, for
+ * background SWR).
  *
- * If cache miss:
- * - Passes through to next middleware
+ * If nothing answers, passes through to the next middleware.
  */
 export declare function withCacheLookup<TEnv>(ctx: MatchContext<TEnv>, state: MatchPipelineState): GeneratorMiddleware<ResolvedSegment>;

package/dist/types/router/match-middleware/segment-resolution.d.ts

@@ -29,15 +29,16 @@
  *  yes          no
  *   |           |
  *   v           v
- * resolveAll  resolveAllWithRevalidation
- * Segments    Segments
- *   |           |
+ * FRESH pass  partial pass
  *   |           | (compares with prev state)
  *   |           | (handles null components)
  *   |           |
  *   +-----------+
  *         |
  *         v
+ *   resolveAllSegments()
+ *         |
+ *         v
  *   +---------------------------+
  *   | Update state:             |
  *   |  - state.segments         |
@@ -54,13 +55,14 @@
  * RESOLUTION MODES
  * ================
  *
+ * Both use resolveAllSegments().
+ *
  * Full Match (document request):
- *   - Uses resolveAllSegments()
- *   - No revalidation logic (nothing to compare against)
+ *   - A FRESH pass (freshPassInput): no revalidation logic (nothing to
+ *     compare against)
  *   - Simple resolution of all route entries
  *
  * Partial Match (navigation):
- *   - Uses resolveAllSegmentsWithRevalidation()
  *   - Compares current vs previous params/URL
  *   - Sets component = null for segments client already has
  *   - Respects custom revalidation rules

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

@@ -1,12 +1,23 @@
 import type { RouterContext } from "./router-context.js";
-import type { ResolveSegmentOptions } from "./segment-resolution.js";
-import type { EntryData } from "../server/context";
 import type { PartialPrerenderProps } from "../urls/pattern-types.js";
-import type { HandlerContext, ResolvedSegment } from "../types";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { RouterVersions } from "../router-versions.js";
 import type { OnDemandRouteConfig } from "../prerender/on-demand.js";
+/**
+ * An intercept a navigation can select over the route that the build does
+ * not bake: its HIT misses (selectInterceptVariant) and it renders live,
+ * with the request instead of BuildContext.
+ * - `same-slot`: another intercept on its layout fills the same slot.
+ * - `handler-response` / `layout-response`: its handler or layout returned a
+ *   Response for this URL.
+ * - `local-name`: it targets the route's localRouteName, which the build
+ *   never bakes.
+ */
+export interface LiveIntercept {
+    slot: string;
+    reason: "same-slot" | "handler-response" | "layout-response" | "local-name";
+}
 export interface PrerenderMatchDeps<TEnv = any> {
     /** Owning router id; scopes bake-time root-scope/search-schema lookups the
      *  same way reqCtx._routerId does at runtime (issue #762). */
@@ -21,7 +32,7 @@ export interface PrerenderMatchDeps<TEnv = any> {
     findMatch: (pathname: string) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
     buildRouterContext: () => RouterContext<TEnv>;
     mergedRouteMap: Record<string, string>;
-    resolveAllSegments: (entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>, options?: ResolveSegmentOptions) => Promise<ResolvedSegment[]>;
+    resolveAllSegments: RouterContext<TEnv>["resolveAllSegments"];
 }
 /**
  * Build-time pre-render match. Resolves segments with a BuildContext
@@ -46,9 +57,13 @@ onDemand?: boolean): Promise<{
     routeName: string;
     params: Record<string, string>;
     interceptSegments?: SerializedSegmentData[];
-    /** RSC-encoded MERGED (main + intercept) handle map for the intercept artifact;
-     *  the sinks store it as-is (no longer merge raw records). */
+    /** RSC-encoded handle map for the intercept artifact: the intercept's
+     *  pushes and those of the main segments the intercepted route does not
+     *  own; the sinks store it as-is. */
     interceptHandles?: string;
+    /** The intercepts the intercept variant does not hold, for the build's
+     *  warning (warnLiveIntercepts). */
+    liveIntercepts?: LiveIntercept[];
     passthrough?: true;
     /** On-demand only: the render hit `notFound()` and nothing else failed. */
     notFound?: true;