@rangojs/router 0.15.1 → 0.17.0

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

@@ -102,10 +102,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   intercept("@modal", "card", () => <CardModal />),
      * ])
      *
-     * // With loaders and revalidation
+     * // With loaders and revalidation (revalidate() goes on the loader;
+     * // an intercept-level revalidate() throws)
      * intercept("@modal", "card", () => <CardModal />, () => [
-     *   loader(CardModalLoader),
-     *   revalidate(() => false),
+     *   loader(CardModalLoader, () => [revalidate(() => false)]),
      * ])
      *
      * // Conditional activation via the config object's `when` selector
@@ -127,7 +127,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * @param handler - Component or handler for intercepted render
      * @param config - Optional InterceptConfig (e.g. `{ when }`), or the use
      *   callback directly when there is no config
-     * @param use - Optional callback for loaders, middleware, revalidate, etc.
+     * @param use - Optional callback for loader(), middleware(), loading(),
+     *   transition() and a layout() modal chrome without use() items.
+     *   revalidate() (goes on the loader), errorBoundary()/notFoundBoundary()
+     *   (go on the enclosing layout) and cache() (goes on the target route)
+     *   throw here.
      */
     intercept: {
         <K extends keyof ResolvedRouteMap<T> & string>(slotName: `@${string}`, routeName: `.${K}`, handler: ReactNode | Handler<ExtractRouteParams<T, K>, {}, TEnv>, config?: import("../server/context.js").InterceptConfig<TEnv> | (() => UseItems<InterceptUseItem>), use?: () => UseItems<InterceptUseItem>): InterceptItem;
@@ -183,6 +187,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   ({ defaultShouldRevalidate: true })
      * )
      * ```
+     * Not valid directly inside intercept() use() (throws at definition time):
+     * intercepts only revalidate their loaders, so attach it there with
+     * `loader(Def, () => [revalidate(...)])`.
      * @param fn - Function returning either:
      *   - `boolean` (hard decision — short-circuits the chain),
      *   - `{ defaultShouldRevalidate: boolean }` (soft — updates the suggestion
@@ -245,16 +252,19 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * ```typescript
      * errorBoundary(<ErrorFallback />)
      *
-     * // With dynamic error handler
-     * errorBoundary(({ error, reset }) => (
+     * // With dynamic error handler (server fallback: receives only { error })
+     * errorBoundary(({ error }) => (
      *   <div>
      *     <h2>Something went wrong</h2>
      *     <p>{error.message}</p>
-     *     <button onClick={reset}>Try again</button>
+     *     <a href="/">Go home</a>
      *   </div>
      * ))
      * ```
-     * @param fallback - Static JSX or handler receiving error info and reset function
+     * Not valid inside intercept() use() (throws at definition time): an
+     * intercept has no boundary of its own, and its loader errors resolve
+     * against the enclosing layout/path boundary.
+     * @param fallback - Static JSX or handler receiving `{ error }`
      */
     errorBoundary: (fallback: ReactNode | ErrorBoundaryHandler) => ErrorBoundaryItem;
     /**
@@ -270,6 +280,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   </div>
      * ))
      * ```
+     * Not valid inside intercept() use() (throws at definition time): an
+     * intercept has no boundary of its own, and notFound() from its loaders
+     * resolves against the enclosing layout/path boundary.
      * @param fallback - Static JSX or handler receiving not-found info
      */
     notFoundBoundary: (fallback: ReactNode | NotFoundBoundaryHandler) => NotFoundBoundaryItem;
@@ -285,6 +298,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * Note: Loaders are NOT cached by default. Use cache() inside loader()
      * to explicitly opt-in to loader caching.
      *
+     * Not valid inside intercept() use() (throws at definition time): an
+     * intercept navigation is cached under the target route's cache() scope.
+     *
      * ```typescript
      * // Using app-level defaults (ttl inherited from store.defaults)
      * cache(() => [
@@ -319,6 +335,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   route("archive/:year"),     // uses KV store
      * ])
      *
+     * // Among a path's children: caches that path (handler, layouts, parallels)
+     * path("/product/:id", ProductPage, { name: "product" }, () => [
+     *   cache({ ttl: 60 }),
+     *   layout(<ProductChrome />),  // cached with the path
+     * ])
+     *
      * // Opt-in loader caching
      * route("product/:id", ProductHandler, () => [
      *   loader(ProductLoader),               // NOT cached (default)
@@ -343,8 +365,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *    through React's startTransition, so a same-route nav (same route,
      *    different params, e.g. /product/1 -> /product/2) holds the previous
      *    content while the new loader resolves instead of flashing the route's
-     *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
-     *    also the precondition for any view-transition animation.
+     *    loading() skeleton (see segment-system.tsx inTransitionScope). Held
+     *    useLoader readers of the re-run loaders report isLoading: true until
+     *    the new data commits (use-loader.tsx). The pin is per loader family
+     *    (`$$id`), not per segment — a layout reader of the same createLoader
+     *    the child is re-running is flagged too. This is also the precondition
+     *    for any view-transition animation.
      * 2. <ViewTransition> (experimental React only): the segment content is also
      *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
      *    Layered on by default; pass { viewTransition: false } to keep #1 without

package/dist/types/route-definition/resolve-handler-use.d.ts

@@ -6,6 +6,28 @@ import type { AllUseItems } from "../route-types.js";
  * ReactNode handlers return undefined (no .use possible).
  */
 export declare function resolveHandlerUse(handler: unknown): (() => any[]) | undefined;
+/**
+ * Validate every item an intercept's merged use() returned (explicit use()
+ * and handler.use) against MOUNT_SITE_ALLOWED_TYPES.intercept, plus two
+ * structural rules:
+ * - a nested layout() is only the modal chrome (intercept() keeps its
+ *   handler), so it may not carry use() items of its own;
+ * - a cache entry in `capturedLayouts` means cache() ran in the scope even if
+ *   it was not returned; its orphan form re-parents the following siblings
+ *   onto that entry, so it is rejected the same way. Inside a path, cache()
+ *   writes `sinks.cache` instead (dsl-helpers.ts cache()).
+ */
+export declare function validateInterceptUseItems(items: AllUseItems[], capturedLayouts: readonly {
+    type: string;
+}[], slotName: string, routeName: string, sinks: {
+    readonly revalidate: readonly unknown[];
+    readonly errorBoundary: readonly unknown[];
+    readonly notFoundBoundary: readonly unknown[];
+    readonly intercept: readonly unknown[];
+    readonly parallel: Readonly<Record<string, unknown>>;
+    /** Set by cache() when the intercept is declared inside a path. */
+    readonly cache?: unknown;
+}): void;
 /**
  * Validate that items from handler.use() are valid for the given mount site.
  * Throws a descriptive error if any item is not allowed.
@@ -16,4 +38,4 @@ export declare function validateHandlerUseItems(items: AllUseItems[], mountSite:
  * handler.use items come first (defaults), explicit items second (overrides).
  * Returns undefined if both are absent.
  */
-export declare function mergeHandlerUse(handlerUse: (() => any[]) | undefined, explicitUse: (() => any[]) | undefined, mountSite: string): (() => any[]) | undefined;
+export declare function mergeHandlerUse(handlerUse: (() => any[]) | undefined, explicitUse: (() => any[]) | undefined, mountSite: string | null): (() => any[]) | undefined;

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

@@ -89,6 +89,8 @@ export type CacheItem = {
 export type TransitionItem = {
     name: string;
     type: "transition";
+    /** Wrapper form only: the children it wraps (see hasRoutesInItem). */
+    uses?: AllUseItems[];
 };
 /**
  * Typed transition item that carries child routes as phantom type
@@ -154,7 +156,7 @@ export type RouteUseItem = LayoutItem | ParallelItem | InterceptItem | Middlewar
 /** Items that can be used inside a response route (path.json(), etc.) */
 export type ResponseRouteUseItem = MiddlewareItem | CacheItem;
 export type ParallelUseItem = RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | TransitionItem;
-export type InterceptUseItem = MiddlewareItem | RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | LayoutItem | RouteItem | TransitionItem;
+export type InterceptUseItem = MiddlewareItem | LoaderItem | LoadingItem | LayoutItem | RouteItem | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
 /**
  * Allow composition factories in use() callbacks.

package/dist/types/router/debug-manifest.d.ts

@@ -1,7 +1,8 @@
 import { type SerializedManifest } from "../debug.js";
 import type { RouteEntry } from "../types";
 /**
- * Build a serialized manifest from all route entries for debug inspection.
- * Used by the `debugManifest()` method on the router instance.
+ * Build a serialized manifest from the eager route entries for debug
+ * inspection. Used by the `debugManifest()` method on the router instance.
+ * include() children are not expanded (lazy placeholders are skipped).
  */
 export declare function buildDebugManifest<TEnv = any>(routesEntries: RouteEntry<TEnv>[]): Promise<SerializedManifest>;

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

@@ -42,10 +42,30 @@ export interface InvokeOnErrorContext<TEnv = any> {
  * @param logPrefix - Prefix for console.error messages (e.g., "Router" or "RSC")
  */
 export declare function invokeOnError<TEnv = any>(onError: OnErrorCallback<TEnv> | undefined, error: unknown, phase: ErrorPhase, context: InvokeOnErrorContext<TEnv>, logPrefix?: string): void;
+/**
+ * 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).
+ *
+ * `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
+ * scanned at its chain position.
+ */
+export declare function findInOrphans<T>(entry: EntryData, pick: (orphan: EntryData) => T | undefined, skip?: EntryData | null): T | undefined;
+/** `findInOrphans` pick: the orphan when it declares an errorBoundary(). */
+export declare const withErrorBoundary: (entry: EntryData) => EntryData | undefined;
 /**
  * Find the nearest error boundary by walking up the entry chain
  * Also checks sibling layouts (orphan layouts) for error boundaries
  * Returns the first fallback found, or the default error boundary if configured
+ *
+ * An orphan's parent is null, so from an orphan the walk continues at its
+ * orphanOwner (EntryData). Without that step, errors from an intercept declared
+ * in a routeless layout, or from that layout's loaders, stopped at the orphan
+ * and skipped every ancestor boundary (#898).
  */
 export declare function findNearestErrorBoundary(entry: EntryData | null, defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler): ReactNode | ErrorBoundaryHandler | null;
 /**

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

@@ -4,6 +4,12 @@
  * Creates the handler context object passed to route handlers, middleware, and loaders.
  */
 import type { InternalHandlerContext } from "../types";
+/**
+ * `headers` whose mutating methods run `assertWrite(method)` first. Shared by
+ * the handler ctx (createHandlerContext) and the middleware ctx
+ * (createMiddlewareContext).
+ */
+export declare function guardHeaderWrites(headers: Headers, assertWrite: (method: string | symbol) => void): Headers;
 /**
  * Strip internal _rsc* query params from a URL.
  * Returns a new URL with only user-facing params.

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

@@ -82,13 +82,13 @@
  * ISOLATION FROM RESPONSE
  * =======================
  *
- * Background revalidation creates fully isolated context:
- *   - Fresh handleStore (prevents polluting the response stream)
+ * Background revalidation re-renders through rerenderAndCacheRoute (shared
+ * with proactive caching in cache-store.ts):
+ *   - Derived request context with its own handleStore, transition({ when })
+ *     predicates and no perf metrics (the shared fields are never touched;
+ *     the foreground is still producing the page)
  *   - Fresh handlerContext + loaderPromises (prevents reusing memoized
  *     loader results from the foreground pass)
- *   - handleStore is saved/restored in try/finally
- *
- * This matches the proactive caching pattern in cache-store.ts.
  *
  *
  * FRESH RESOLUTION (NO REVALIDATION)
@@ -101,7 +101,48 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { type RouterContext } from "../router-context.js";
+import type { CacheScope } from "../../cache/cache-scope.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
+import { type RequestContext } from "../../server/request-context.js";
+/**
+ * Re-render a cached route in the background and write it with
+ * cacheScope.cacheRoute: the stale-hit refresh below and proactive caching
+ * (cache-store.ts). Returns the number of segments written.
+ *
+ * A render whose status is not 200 (an error or notFound boundary resolved)
+ * is not written and returns 0, as a non-200 MISS is not cached
+ * (cache-store.ts): the entry it would replace keeps serving until a later
+ * refresh succeeds or it expires. Nothing is held in process; a store's own
+ * revalidation marker (CFCacheStore's REVALIDATING) re-arms after
+ * 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.
+ *   - _transitionWhen: fresh resolution appends transition({ when })
+ *     predicates; the foreground's gateTransitions reads the array after the
+ *     match, and a stale HIT (which replays the stored transition) must not
+ *     evaluate this render's predicates.
+ *   - _metricsStore: undefined, and the DSL store below has `metrics` unset
+ *     (track() reads that one), so nothing lands on the foreground's perf
+ *     timeline. ctx.Store.run closes over ctx.Store, so the derived store
+ *     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.
+ * runWithRequestContext also re-establishes the request ALS, which a waitUntil
+ * task on workerd loses; the DSL store is a different ALS (build context).
+ */
+export declare function rerenderAndCacheRoute<TEnv>(ctx: MatchContext<TEnv>, requestCtx: RequestContext<TEnv>, cacheScope: CacheScope, routerCtx: RouterContext<TEnv>): Promise<number>;
 /**
  * Creates background revalidation middleware
  *

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

@@ -1,6 +1,6 @@
 import type { ContextVar } from "../context-var.js";
 import type { DefaultReverseRouteMap, DefaultRouteName, DefaultVars } from "../types/global-namespace.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { GlobalReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RequestScope } from "../types/request-scope.js";
@@ -51,7 +51,8 @@ export interface MiddlewareContext<TEnv = any, TParams = Record<string, string |
     theme?: Theme;
     setTheme?: (theme: Theme) => void;
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
-    reverse: ScopedReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
+    /** Global route names only; see {@link GlobalReverseFunction}. */
+    reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
 }
 export type MiddlewareFn<TEnv = any, TParams = Record<string, string | undefined>> = (ctx: MiddlewareContext<TEnv, TParams>, next: () => Promise<Response>) => Response | void | Promise<Response | void>;
 export interface MiddlewareEntry<TEnv = any> {

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

@@ -49,7 +49,9 @@ export interface RouterContext<TEnv = any> {
     getMetricsStore: () => MetricsStore | undefined;
     createCacheScope: (cacheConfig: any, parent: CacheScope | null) => CacheScope | null;
     findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext, isAction: boolean) => InterceptResult | null;
-    resolveAllSegmentsWithRevalidation: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: any | undefined, interceptResult: InterceptResult | null, localRouteName: string, pathname: string, stale?: boolean) => Promise<{
+    resolveAllSegmentsWithRevalidation: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: any | undefined, interceptResult: InterceptResult | null, localRouteName: string, pathname: string, stale?: boolean, 
+    /** The matched route's full chain when `entries` is part of it (ResolveSegmentOptions.chain). */
+    chain?: readonly EntryData[]) => Promise<{
         segments: ResolvedSegment[];
         matchedIds: string[];
     }>;

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

@@ -137,6 +137,22 @@ export interface Rango<TEnv = any, TRoutes extends Record<string, unknown> = Rec
      * ```
      */
     readonly routeMap: TRoutes;
+    /**
+     * Serialize the route manifest for inspection: every route and layout the
+     * router's `.routes()` / `urls` mounts register, with shortCodes, parent
+     * links, and loader/middleware/error-boundary/parallel/intercept flags.
+     *
+     * Server-only development aid. It re-evaluates each mount's `urls()` tree.
+     * Groups mounted with `include()` are lazy and are not expanded: their
+     * routes are absent from the result.
+     *
+     * @example
+     * ```typescript
+     * const manifest = await router.debugManifest();
+     * console.log(manifest.totalRoutes, Object.keys(manifest.routes));
+     * ```
+     */
+    debugManifest(): Promise<SerializedManifest>;
     /**
      * Handle an RSC request.
      *
@@ -147,7 +163,13 @@ export interface Rango<TEnv = any, TRoutes extends Record<string, unknown> = Rec
      * ```tsx
      * import { router } from "./router";
      *
-     * export default { fetch: router.fetch };
+     * // Workers call fetch(request, env, ctx); `{ fetch: router.fetch }` would
+     * // drop env and ctx.
+     * export default {
+     *   fetch(request, env, ctx) {
+     *     return router.fetch(request, { env, ctx });
+     *   },
+     * } satisfies ExportedHandler;
      * ```
      *
      * @example Direct export
@@ -238,7 +260,7 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
     readonly notFound?: RangoOptions<TEnv>["notFound"];
     /**
      * Resolved theme configuration (null if theme not enabled)
-     * Used by NavigationProvider to include ThemeProvider and by MetaTags to render theme script
+     * Used by NavigationProvider to include ThemeProvider and by `Html.Meta` to render theme script
      */
     readonly themeConfig: import("../theme/types.js").ResolvedThemeConfig | null;
     /**

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

@@ -146,8 +146,10 @@ export interface RangoOptions<TEnv = any> {
      *
      * Must be a client component ("use client") that accepts { children }.
      *
-     * If not provided, a default document with basic HTML structure is used:
-     * `<html><head><meta charset/viewport></head><body>{children}</body></html>`
+     * If not provided, a default document is used: `Html.Meta` and `Html.Scripts`
+     * in `<head>`, `Html.Scripts position="body"` before `{children}` and
+     * `Html.ScrollRestoration` after it. Pass your own to set `getKey` or to
+     * leave back/forward scrolling to the browser.
      *
      * @example
      * ```typescript
@@ -181,7 +183,8 @@ export interface RangoOptions<TEnv = any> {
     defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
     /**
      * Default not-found boundary fallback used when no notFoundBoundary is defined in the route tree
-     * If not provided, DataNotFoundError will be treated as a regular error
+     * If not provided, notFound() renders the `notFound` option, else a plain
+     * `<h1>Not Found</h1>` (status 404)
      */
     defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
     /**
@@ -190,7 +193,7 @@ export interface RangoOptions<TEnv = any> {
      * This is rendered within your document/app shell with a 404 status code.
      * Use this for a custom 404 page that maintains your app's look and feel.
      *
-     * If not provided, a default "Page not found" component is rendered.
+     * If not provided, a plain `<h1>Not Found</h1>` is rendered.
      *
      * Can be a static ReactNode or a function receiving the pathname.
      *
@@ -337,7 +340,7 @@ export interface RangoOptions<TEnv = any> {
      * When provided, enables:
      * - ctx.theme and ctx.setTheme() in route handlers
      * - useTheme() hook for client components
-     * - FOUC prevention via inline script in MetaTags
+     * - FOUC prevention via inline script in `<Html.Meta />`
      * - Automatic ThemeProvider wrapping in NavigationProvider
      *
      * @example

package/dist/types/router/segment-resolution/fresh.d.ts

@@ -27,6 +27,16 @@ export interface ResolveSegmentOptions {
      * so error boundaries keep catching at request time.
      */
     throwOnError?: boolean;
+    /**
+     * The matched route's full entry chain. resolveAllSegments defaults it to
+     * its `entries`; withCacheLookup passes it when it resolves only the entries
+     * above a cache() boundary. An orphan list can hold an entry of the chain: a
+     * bare cache() marker sits in its layout's layout[] (it wraps that layout's
+     * routes) and is the parent of the routes after it. For those routes it
+     * resolves once, as a chain entry, below the cache() header latch (issue
+     * #918: resolved twice on a MISS, once and discarded on a HIT).
+     */
+    chain?: readonly EntryData[];
 }
 /**
  * Resolve segments from EntryData.

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

@@ -16,8 +16,15 @@
  * On hit: returns cached data directly, skips loader execution.
  * On stale hit (SWR): returns stale data, schedules background revalidation.
  * On miss: executes loader, schedules non-blocking cache write.
+ *
+ * Handle pushes (`ctx.use(Handle)(...)` in the loader body) are a side effect
+ * the HIT must reproduce: the MISS records the pushes of the body and of the
+ * loaders it awaits via ctx.use into the entry's `handles` blob (the
+ * "use cache" capture/encode), and every HIT — stale included — replays
+ * them, each loader's pushes at most once per request (a dependency another
+ * reader already ran keeps its live pushes). See replayLoaderHandles.
  */
-import type { LoaderEntry } from "../../server/context.js";
+import { type LoaderEntry } from "../../server/context.js";
 import type { HandlerContext } from "../../types.js";
 /**
  * Resolve loader data with optional caching.
@@ -29,5 +36,34 @@ import type { HandlerContext } from "../../types.js";
  * (observePhase; see instrument.ts). A cache HIT returns without calling ctx.use,
  * so it emits no loader phase (the loader did not execute; the hit is only a
  * LoaderCache debug log).
+ *
+ * PPR loader lane rule — the canonical source statement; other sites point
+ * here (consumer docs: skills/ppr/SKILL.md "The loader lane rule";
+ * docs/design/loader-container-bake.md). This is the single funnel every
+ * loader segment path routes through (fresh resolveLoaders, cache-hit
+ * resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation, and
+ * intercept loaders in intercept-resolution.ts, which pass no bake key and
+ * never run under a shell capture), so the lane is decided here, per LOADER,
+ * never by the entry's loading():
+ *
+ * - BAKE lane: `loader(Def, { ssr: false })` (awaitBeforeFlush) with a
+ *   `bakeSegmentKey` from the caller. The loader EXECUTES at capture (the
+ *   flag's "data in the HTML before first flush" maps to the frozen prelude)
+ *   and its settled non-promise data bakes into the shell. Promises nested in
+ *   plain objects/arrays are masked (mask-nested.ts) and stay live holes at
+ *   the consumer's own Suspense — per-request material must be promise-shaped
+ *   (the #692 cross-session scar). The masked container registers on
+ *   `_shellCaptureLoaderRecords`: it holds the capture gate (bounded by
+ *   `ppr.captureTimeout`) and pins into the snapshot's loader family, and on a
+ *   HIT the recorded container is overlaid onto the fresh run (below) so the
+ *   payload matches the frozen prelude byte-for-byte. cookies()/headers() in
+ *   its body (nested promise bodies included) trip the capture guard.
+ * - LIVE lane: every other loader, whatever its entry's loading(). Never
+ *   executes at capture: the slot gets a never-resolving promise
+ *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an
+ *   inline Suspense — then streams fresh per request. A masked read with NO
+ *   boundary above it root-postpones and the <body> sanity gate refuses the
+ *   shell (eternal-MISS warning). A route whose loaders are ALL `ssr: false`
+ *   needs no loading(): nothing masks.
  */
 export declare function resolveLoaderData<TEnv>(loaderEntry: LoaderEntry, ctx: HandlerContext<any, TEnv>, pathname: string, bakeSegmentKey?: string | null): Promise<any>;

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

@@ -2,13 +2,10 @@
  * PPR shell-capture loader masking.
  *
  * During a shell CAPTURE re-render (Axis 2, see docs/design/ppr-shell-resume.md)
- * route loaders are the "live lane": they must NOT execute — no side effects, no
- * cost, no cache round-trips. Instead every loader segment's value slot receives
- * a never-resolving promise, so the loader-consuming Suspense subtree stays
- * pending and React's static `prerender` marks it as a postponed hole. The frozen
- * shell (prelude) captures only the fallback; the resumed serve pass runs the
- * loaders fresh through the unchanged execution path and streams their output
- * into the holes.
+ * live-lane loaders (lane rule: see resolveLoaderData, loader-cache.ts) must
+ * NOT execute; their value slot gets a never-resolving promise so the
+ * consuming Suspense subtree postpones as a hole, and the serve pass runs them
+ * fresh into it.
  *
  * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
  * the derived request context of the background capture task (shell-capture.ts) —
@@ -28,17 +25,10 @@ import { type RequestContext } from "../../server/request-context.js";
 export declare function isShellCaptureActive(reqCtx?: RequestContext<any> | undefined): boolean;
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 /**
- * Entry-level lane input for an entry's loaders under PPR (the loading()
- * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
- * is per LOADER in loader-cache.ts: an `ssr: false`
- * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
- * flag's document promise ("data in the HTML before first flush") maps to
- * the frozen prelude — while every other loader is LIVE (masked at capture,
- * fresh on every serve), postponing at loading() or an inline Suspense.
- * This helper still gates which entries pass a bake segment key for the
- * legacy loading()-less shape and the HIT-tail seed overlay.
- *
- * Mirrors segment-system's isRenderableLoading so the mask decision and the
- * tree's boundary placement can never disagree.
+ * True when the entry's loading() is renderable (mirrors segment-system's
+ * isRenderableLoading). Not the lane decision (lane rule: see
+ * resolveLoaderData, loader-cache.ts): callers only use it to decide whether
+ * an unflagged loader's segment key rides as the bake/seed key, which is inert
+ * at capture.
  */
 export declare function entryLoadingMasksLoaders(loading: unknown): boolean;

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

@@ -2,9 +2,9 @@
  * Loader-family capture snapshot: elide + overlay for bake-lane loader
  * containers (docs/design/loader-container-bake.md).
  *
- * A loader on an entry with NO renderable loading() executes during shell
- * capture; its settled container bakes into the prelude while every promise
- * still pending at the quiet window postpones as a hole. To keep a HIT's fresh
+ * A bake-lane loader (lane rule: see resolveLoaderData, loader-cache.ts)
+ * executes during shell capture; its settled container bakes into the prelude
+ * while nested promises postpone as holes. To keep a HIT's fresh
  * payload byte-identical to that frozen prelude, the capture pins the container
  * in the shell snapshot:
  *

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

@@ -1,12 +1,12 @@
 /**
  * Capture-side nested-thenable masking — the mechanism behind "nested-promise
  * shape is the liveness declaration" for BOTH bake-lane loader containers
- * (loader-cache.ts) and pushed handle containers (request-context.ts
- * createUseFunction).
+ * (loader-cache.ts) and pushed handle containers (the capture handle store's
+ * push wrap in rsc/shell-capture.ts).
  *
- * Deliberately a LEAF module: request-context needs the mask for handle
- * pushes, and loader-mask (the other natural home) imports request-context —
- * importing from there would cycle. This module imports only is-thenable.
+ * Deliberately a LEAF module: loader-mask (the other natural home) imports
+ * request-context, so any funnel importing the mask from there inherits that
+ * graph. This module imports only is-thenable.
  */
 /**
  * A promise that never settles — the masked stand-in for a per-request value
@@ -21,8 +21,8 @@ export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
  * Deep-copy a container with every NESTED thenable replaced by a masked
  * (never-resolving) promise. Applied during shell capture to (a) bake-lane
  * loader containers (loader-cache.ts) and (b) pushed handle containers
- * (createUseFunction) — the two rango-owned funnels where consumers declare
- * per-request data by promise SHAPE.
+ * (shell-capture.ts capture store push wrap) — the two rango-owned funnels
+ * where consumers declare per-request data by promise SHAPE.
  *
  * Why: a nested promise that happened to SETTLE before the capture's quiet
  * window closed used to bake its value into the SHARED shell (and, for

package/dist/types/router/segment-resolution/revalidation.d.ts

@@ -66,7 +66,9 @@ export declare function resolveEntryHandlerWithRevalidation<TEnv>(entry: Exclude
  */
 export declare function resolveSegmentWithRevalidation<TEnv>(entry: Exclude<EntryData, {
     type: "parallel";
-}>, routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean): Promise<SegmentRevalidationResult>;
+}>, routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean, 
+/** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+chain?: readonly EntryData[]): Promise<SegmentRevalidationResult>;
 /**
  * Resolve orphan layout with revalidation.
  */
@@ -79,7 +81,9 @@ parentRouteEntry?: EntryData): Promise<SegmentRevalidationResult>;
 export declare function resolveAllSegmentsWithRevalidation<TEnv>(entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: ActionContext | undefined, interceptResult: {
     intercept: any;
     entry: EntryData;
-} | null, localRouteName: string, pathname: string, deps: SegmentResolutionDeps<TEnv>, stale?: boolean): Promise<{
+} | null, localRouteName: string, pathname: string, deps: SegmentResolutionDeps<TEnv>, stale?: boolean, 
+/** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+chain?: readonly EntryData[]): Promise<{
     segments: ResolvedSegment[];
     matchedIds: string[];
 }>;

package/dist/types/router/segment-wrappers.d.ts

@@ -27,7 +27,7 @@ export interface SegmentWrappers<TEnv = any> {
     } | undefined, interceptResult: {
         intercept: InterceptEntry;
         entry: EntryData;
-    } | null, localRouteName: string, pathname: string) => Promise<{
+    } | null, localRouteName: string, pathname: string, stale?: boolean, chain?: readonly EntryData[]) => Promise<{
         segments: ResolvedSegment[];
         matchedIds: string[];
     }>;

package/dist/types/rsc/response-route-handler.d.ts

@@ -6,7 +6,7 @@
  * dispatch, route middleware execution, and response caching with SWR.
  */
 import type { MiddlewareFn } from "../router/middleware.js";
-import type { EntryData } from "../server/context.js";
+import { type EntryData } from "../server/context.js";
 import type { HandlerContext } from "./handler-context.js";
 export interface ResponseRouteMatch {
     responseType: string;

package/dist/types/rsc/rsc-rendering.d.ts

@@ -2,8 +2,7 @@
  * RSC Rendering Handler (Navigation)
  *
  * Handles RSC rendering for both partial (client-side navigation) and full
- * (initial page load) requests. Includes prerender collection for build-time
- * static generation.
+ * (initial page load) requests.
  */
 import { getRequestContext } from "../server/request-context.js";
 import type { HandlerContext } from "./handler-context.js";

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -42,3 +42,11 @@ export declare const SHELL_CAPTURE_MAX_WAIT_MS = 15000;
  * check on the stampede guard, keyed off the same constant.
  */
 export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;
+/**
+ * Shared PPR loader-lane hint, appended to every capture warning or error
+ * whose fix depends on the lane (shell-capture.ts warnings, the cookie-store.ts
+ * capture guard). Lives in this import-free leaf so cookie-store.ts can import
+ * it without pulling the capture orchestration module. Source anchor for the
+ * rule: resolveLoaderData (router/segment-resolution/loader-cache.ts).
+ */
+export declare const PPR_LANE_HINT: string;