@rangojs/router 0.16.0 → 0.17.0

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;

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

@@ -50,10 +50,11 @@ declare function delay(ms: number): Promise<void>;
  * mode's ceiling (60s in production, {@link REFUSED_CAPTURE_DEV_MAX_MS} in dev).
  *
  * Why exponential and not a flat 60s: a flat long window conflates two very
- * different failures. A STRUCTURALLY ineligible route (no loading(), a cookie
- * reader) fails forever and wants the long 60s cap. But a cold-but-ELIGIBLE route
- * can also fail the in-place retry under a truly cold graph (dev module transform,
- * or a cold worker under parallel load) — and it must recover FAST, on the next
+ * different failures. A STRUCTURALLY ineligible route (a boundary-less live
+ * loader read, a cookie reader) fails forever and wants the long 60s cap. But a
+ * cold-but-ELIGIBLE route can also fail the in-place retry under a truly cold
+ * graph (dev module transform, or a cold worker under parallel load) — and it
+ * must recover FAST, on the next
  * request or two, not be frozen for 60s (that would re-break the very cold-start DX
  * the retry fixes; it bit the cloudflare dev e2e). Escalating from 1s means the
  * eligible route re-probes almost immediately (warm now → HIT and clear), while the

package/dist/types/rsc/ssr-setup.d.ts

@@ -33,11 +33,11 @@ export interface SsrHtmlStageOptions<TEnv> {
     /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
     metricsStore: MetricsStore | undefined;
     /**
-     * renderHTML options minus streamMode (the stage resolves streamMode). Carries
-     * the per-site nonce and, for the PE action re-render, formState. Spread
-     * verbatim so each call site's exact key set is preserved.
+     * renderHTML options minus streamMode and onError (the stage owns both).
+     * Carries the per-site nonce and, for the PE action re-render, formState.
+     * Spread verbatim so each call site's exact key set is preserved.
      */
-    render: Omit<SSRRenderOptions, "streamMode">;
+    render: Omit<SSRRenderOptions, "streamMode" | "onError">;
     /** ResponseInit merged into the prepared render (e.g. content-type). */
     init?: ResponseInit;
 }
@@ -59,8 +59,8 @@ export declare function getSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Re
  * Classify whether a request may require SSR (HTML rendering).
  *
  * Returns false for requests that are definitively RSC-only: transport
- * params (partial/action/loader/__rsc), prerender collection, or an explicit
- * Accept: text/x-component. Must never return false for a request whose
+ * params (partial/action/loader/__rsc) or an explicit Accept:
+ * text/x-component. Must never return false for a request whose
  * render-time decision (isRscRequest) will be HTML — the two share
  * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
  * keys its HTML/RSC response slots off this function, so any divergence from

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

@@ -181,6 +181,12 @@ export interface SSRRenderOptions {
      * the browser across hydration. Absent on host-agnostic build captures.
      */
     origin?: string;
+    /**
+     * Called for each error Fizz reports through its onError: a component that
+     * threw inside a Suspense boundary, which leaves the boundary errored in an
+     * otherwise completed document. React's default console.error is kept.
+     */
+    onError?: (error: unknown) => void;
 }
 /**
  * SSR module interface for HTML rendering
@@ -200,6 +206,8 @@ export interface SSRModule {
         maxWaitMs?: number;
         search?: string;
         origin?: string;
+        /** Each component error the prerender reports (never the capture's own abort). */
+        onError?: (error: unknown) => void;
     }) => Promise<{
         prelude: Uint8Array;
         postponed: string | null;
@@ -217,6 +225,8 @@ export interface SSRModule {
         nonce?: string;
         search?: string;
         origin?: string;
+        /** Each component error the resumed holes report. */
+        onError?: (error: unknown) => void;
     }) => Promise<ReadableStream<Uint8Array>>;
 }
 /**

package/dist/types/server/context.d.ts

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { ReactNode } from "react";
 import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn, TransitionConfig } from "../types";
 import type { DefaultRouteName } from "../types/global-namespace.js";
+import type { ContextVar } from "../context-var.js";
 /**
  * Performance metric entry for a single measured operation
  *
@@ -44,6 +45,17 @@ export type EntryPropCommon = {
     id: string;
     shortCode: string;
     parent: EntryData | null;
+    /**
+     * Orphan siblings only (attachOrphanSibling in
+     * route-definition/dsl-helpers.ts): the entry whose `layout[]` holds this
+     * one. `parent` stays null on an orphan (matchError's matched-id stack in
+     * router/match-api.ts starts at the boundary-holding entry, possibly an
+     * orphan, and must stop there), so the boundary walkers in
+     * router/error-handling.ts follow this instead. A lookup that starts at an
+     * orphan (its loaders, an intercept it declares) then reaches the owner's
+     * boundaries and the owner's ancestors.
+     */
+    orphanOwner?: EntryData;
     /** Cache configuration for this entry (set by cache() DSL) */
     cache?: EntryCacheConfig;
     /** URL prefix from include() scope, used for MountContext on client */
@@ -156,9 +168,6 @@ export type InterceptEntry = {
     routeName: string;
     handler: ReactNode | Handler<any, any, any>;
     middleware: MiddlewareFn<any, any>[];
-    revalidate: ShouldRevalidateFn<any, any>[];
-    errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
-    notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
     loader: LoaderEntry[];
     loading?: ReactNode | false;
     transition?: TransitionConfig;
@@ -403,6 +412,20 @@ export declare function track(label: string, depth?: number): () => void;
  * (never cached), so non-cacheable reads are safe.
  */
 export declare function isInsideCacheScope(): boolean;
+/**
+ * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
+ * `ctx.set(..., { cache: false })` write). Callers check isNonCacheable() first
+ * so ordinary reads never reach the scope lookups.
+ *
+ * Throws inside a "use cache" body: the key does not include the value, so the
+ * first caller's value would be stored and served to later callers (#925). A
+ * loader body entered INSIDE the cached function is exempt, the same baked-copy
+ * trade isInsideCacheScope() makes for cache(). A cached function called FROM a
+ * loader is not: the loader re-runs, the cached body does not. The body scope
+ * records the exec scope it was entered in, so the exemption holds only while
+ * that is still the innermost one.
+ */
+export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>): void;
 /**
  * Check if the current execution is inside a DSL loader scope
  * (wrapped by runInsideLoaderScope). Used by rendered() barrier
@@ -498,6 +521,13 @@ export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: stri
  * (issue #672, secondary).
  */
 export declare function getCurrentLoaderBodyId(): string | undefined;
+/**
+ * True while `loaderId`'s body, or a loader it awaits via ctx.use at any
+ * depth, is executing. The loader-level cache records these pushes
+ * (loader-cache.ts): a HIT skips the cached body, so a dep that no other
+ * reader runs in that request only reaches the page through the replay.
+ */
+export declare function isInsideLoaderBody(loaderId: string): boolean;
 /**
  * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
  * handler, not the DSL segment funnel) is executing. The consumption-lane