@rangojs/router 0.26.6 → 0.28.0

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

@@ -35,9 +35,19 @@
  * request, is neither joined nor written (#973, #977): see
  * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
  */
+import { type RequestContext } from "../server/request-context.js";
 import type { SegmentCacheStore } from "./types.js";
 import { type ExecutionStart } from "./invalidation-order.js";
 export { executionStart, invalidatedSince, markResponseStart, type ExecutionStart, } from "./invalidation-order.js";
+/**
+ * Run a stale entry's background refresh on the visitor's request context: a
+ * "use cache" function's (cache-runtime.ts) or a cached loader's
+ * (loader-cache.ts). No visitor made the invalidations in it, so they set no
+ * fresh-reads cookie, as in a stale cache() HIT's re-render or a document
+ * cache entry's re-run, whose passes take a sink's no-op writer
+ * (server/render-pass.ts).
+ */
+export declare function runAsBackgroundRefresh<T>(ctx: RequestContext, fn: () => T): T;
 /**
  * The write gate of every cache execution (#977): whether one of `tags` was
  * invalidated after the execution that produced the value started.

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,14 +1,12 @@
 /**
- * The wire markers of prefetches and of `prefetch: false`
- * (docs/design/prefetch-false.md): shared by the browser and the server
+ * The wire markers of prefetches: shared by the browser and the server
  * (router/segment-resolution/prefetch-deferral.ts requestKind,
- * rsc/prefetch-render-error.ts). Dependency free, like segment-fragments.ts:
- * the browser must not import the server modules that use them.
+ * 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";
 /**
  * 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;
@@ -166,6 +157,16 @@ export interface MatchContext<TEnv = any> {
     }>;
     isFullMatch: boolean;
 }
+/**
+ * An action, or a stale partial (`_rsc_stale`: Back/Forward onto an entry
+ * marked stale, `refresh()`, the cross-tab refresh, the action follow-up, a
+ * zero-segment refetch), renders live: no route-cache or prerender-store read
+ * a live handler can replace, and no store. An action's render is never
+ * 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).
  */