@rangojs/router 0.28.0 → 0.29.0

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.28.0",
+      version: "0.29.0",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

package/dist/types/browser/action-fence.d.ts

@@ -20,7 +20,8 @@
  *
  * The drop runs the batch's follow-up: when an action of the batch did not
  * land on the page on screen, the action bridge refetches that page once,
- * whole, after the navigation the user started, unless an intercept is on
+ * whole (or whole above an action's error boundary on screen, which it
+ * holds), after the navigation the user started, unless an intercept is on
  * screen (server-action-bridge.ts followUp; the rules are R1-R7 in
  * docs/internal/execution-model.md).
  *

package/dist/types/browser/event-controller.d.ts

@@ -59,6 +59,11 @@ export interface ActionEntry {
     startedAt: number;
     /** Whether action processing is complete (may still be streaming) */
     completed?: boolean;
+    /**
+     * Set when a later call started (see startAction): "id" hides this call
+     * from every reader, "name" from readers that match by export name.
+     */
+    supersededBy?: "id" | "name";
 }
 /**
  * Derived navigation state (computed from source of truth)
@@ -70,7 +75,7 @@ export interface DerivedNavigationState {
     isStreaming: boolean;
     /** Whether a navigation is active (fetching or streaming, before commit) */
     isNavigating: boolean;
-    /** Current committed location */
+    /** The location of the last page flushed to React (useNavigation keeps the page on screen) */
     location: NavigationLocation;
     /** URL being navigated to (null if idle) */
     pendingUrl: string | null;

package/dist/types/browser/partial-update.d.ts

@@ -112,18 +112,29 @@ export type UpdateMode = {
      * transition({ when }) sees kind "revalidate", not "replace".
      */
     refresh?: boolean;
+    /** The cross-tab refresh's held boundary (see `action`). */
+    boundary?: string;
 } | {
     type: "leave-intercept";
     interceptSourceUrl?: string;
+    boundary?: never;
 } | {
     type: "stale-revalidation";
     interceptSourceUrl?: string;
+    /** Back/Forward's held boundary (see `action`). */
+    boundary?: string;
 } | {
     type: "action";
     interceptSourceUrl?: string;
     actionId?: string;
     /** The action's FormData and result, for transition({ when }) `action`. */
     action?: TransitionWhenActionInput;
+    /**
+     * An action's error boundary the page shows (actionBoundaryAt): the
+     * server renders above it, its cached segment stays, and the page
+     * holds only the ids above it.
+     */
+    boundary?: string;
 };
 /**
  * Type for the fetchPartialUpdate function. In `action` mode it resolves with

package/dist/types/browser/react/use-action.d.ts

@@ -18,14 +18,19 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * Features:
  * - Tracks action lifecycle: idle → loading → streaming → idle
  * - Captures result/error locally (React handles cleanup)
- * - If multiple actions fire, tracks only the last one
+ * - If the same action fires several times, reports the latest call to
+ *   start. An earlier call that settles later changes nothing it reports;
+ *   a latest call that was aborted reports idle with nothing. One call at a
+ *   time, not one per argument: a reader filtering on `payload` cannot track
+ *   an earlier call once a later one starts.
  * - Supports selector pattern like useNavigation
  *
  * Matching behavior:
  * - **Function reference**: Uses full $$id for exact matching. This is precise
  *   and distinguishes between actions with the same name in different files.
  * - **String**: Matches by suffix (action name after #). This is convenient
- *   but may be ambiguous if multiple files export the same action name.
+ *   but may be ambiguous if multiple files export the same action name: it
+ *   follows the latest call of any action with that export name.
  *
  * @param action - Either a server action function or a string action name.
  *   - **Function**: Must be directly imported in the client component.

package/dist/types/browser/react/use-handle.d.ts

@@ -21,21 +21,24 @@ import type { RouteStateSignal } from "../event-controller.js";
 export declare function useHandle<T, A>(handle: Handle<T, A>): Rango.FlightSerialize<A>;
 export declare function useHandle<T, A, S>(handle: Handle<T, A>, selector: (data: Rango.FlightSerialize<A>) => S): S;
 /**
- * Route state the controller's handle notifications drive (useHandle,
- * useSegments) commits with the page it belongs to. NavigationProvider
- * flushes the controller inside every payload update, so a value known then
- * is set in the page's lane. A page handed over urgently (signal "release")
- * takes a value that arrives before it commits the same way: set at default
- * priority, it renders in the page's lane, and the page's effects read it.
- * A page in a transition (signal "anchor") does not: until it commits
+ * Route state the controller's handle notifications drive commits with the
+ * page it belongs to. NavigationProvider flushes the controller inside every
+ * payload update, with signal "anchor" for a page in a transition and
+ * "release" for an urgent one, so the page's own change is set in the page's
+ * lane and the page's effects read it. From the anchor until the page commits
  * (releaseRouteState() from the provider's layout effect, signal "release"),
- * a new value waits, and is applied in the commit's task, right after the
- * page's own commit. In the page's lane, a value that suspends in a revealed
- * <Suspense> (a crumb's content) would hold the page; in a lane of its own,
- * it commits over the page being left and takes the page's transition types
- * (#1165); and a transition entangled with the page misses its commit when it
- * is set after React rendered the page, before its view transition's
- * mutation, and starts a view transition of its own. A value shallow-equal to
- * the last one sets nothing, so a reader renders only when its value moves.
+ * a later change waits and is applied in the commit's task, right after the
+ * page's own commit: set in a lane of its own, it would commit over the page
+ * being left (#1165).
+ *
+ * `waitForRelease`, set by useHandle only: the anchor's own change waits too,
+ * so a handle value lands right after its page's commit, never in its lane. A
+ * handle value can carry a promise that suspends, and in the page's lane one
+ * that suspends in a revealed <Suspense> would hold the page. Nothing
+ * useSegments reads can suspend, so it leaves it off and its path and
+ * location commit with their page.
+ *
+ * A value shallow-equal to the last one sets nothing, so a reader renders only
+ * when its value moves.
  */
-export declare function useCommitAnchoredState<T>(init: () => T): [T, (value: T, signal?: RouteStateSignal) => void];
+export declare function useCommitAnchoredState<T>(init: () => T, waitForRelease?: boolean): [T, (value: T, signal?: RouteStateSignal) => void];

package/dist/types/browser/react/use-link-status.d.ts

@@ -14,8 +14,11 @@ export interface LinkStatus {
 /**
  * Hook to track the pending state of a Link component
  *
- * Must be used inside a Link component. Returns `{ pending: true }`
- * when navigation to this link's destination is in progress.
+ * Must be used inside a Link component. Returns `{ pending: true }` while a
+ * navigation to the link's destination is in flight, until the page it
+ * brings commits: under transition() while React holds that page, and
+ * through a server redirect until the target page commits. A newer
+ * navigation ends it at once.
  *
  * Useful for showing inline loading indicators on individual links.
  *

package/dist/types/browser/segment-reconciler.d.ts

@@ -71,3 +71,29 @@ export declare function reconcileSegments(input: ReconcileInput): ReconcileResul
  * other segment merges as an action's does (mergeCached).
  */
 export declare function reconcileErrorSegments(cachedSegments: ResolvedSegment[], errorSegments: ResolvedSegment[]): ReconcileResult;
+/**
+ * The ids a page holds once an action's error boundary `boundary` shows: the
+ * ones above it. Nothing at or below the boundary ran after the action's
+ * write (its response and the follow-up cut there), so the next request must
+ * not hold it. ShortCodes nest, so those ids start with the boundary's: the
+ * boundary, its loaders (`${id}D…`), its slots and every entry under it. A
+ * sibling with a longer index (`…R10` beside `…R1`) is kept.
+ */
+export declare function idsAboveBoundary(ids: string[], boundary: string | undefined): string[];
+/**
+ * The error segment of every action error boundary committed, by identity
+ * (server-action-bridge.ts adds and deletes). An entry shows one while its
+ * cached list still holds that object: a later commit on the entry replaces
+ * the list, and a refetch that holds the boundary keeps it. Weak, so a
+ * replaced boundary is not kept alive. Two routers never share a segment
+ * object. No hook reads it.
+ */
+export declare const actionBoundaries: WeakSet<ResolvedSegment>;
+/**
+ * The index of the deepest action error boundary in `segments`, -1 for none.
+ * It is that action's outcome, which no GET reproduces: a background refetch
+ * of the page (the follow-up, Back/Forward's stale revalidation, the
+ * cross-tab refresh) holds it and renders what is above it. At 0 nothing is
+ * above it.
+ */
+export declare function actionBoundaryAt(segments: readonly ResolvedSegment[]): number;

package/dist/types/browser/types.d.ts

@@ -191,11 +191,24 @@ export interface InflightAction {
  * @internal This type is an implementation detail. Use PublicNavigationState instead.
  */
 export interface NavigationState {
-    /** Navigation lifecycle state (idle or loading during navigation) */
+    /**
+     * Lifecycle state: `"loading"` while a navigation is in flight and while a
+     * server action runs, `"idle"` otherwise
+     */
     state: "idle" | "loading";
-    /** Whether RSC data is currently streaming (initial load or navigation) */
+    /**
+     * Whether RSC data is currently streaming: a navigation's response, or a
+     * server action's response (initial load, navigation or action)
+     */
     isStreaming: boolean;
-    /** Current location */
+    /**
+     * True while a navigation is in flight (fetching or streaming, before its
+     * commit); false during a server action, whose `state` is still `"loading"`.
+     * Drive a navigation progress bar from this and an action spinner from
+     * `state`.
+     */
+    isNavigating: boolean;
+    /** The page on screen; moves when the next page shows (`pendingUrl` is the page being fetched) */
     location: NavigationLocation;
     /** URL being navigated to (null when idle) */
     pendingUrl: string | null;
@@ -450,6 +463,8 @@ export interface NavigateOptionsInternal extends Omit<NavigateOptions, "state">
     _skipCache?: boolean;
     /** Server redirects already followed by this navigation chain (0 for a user navigation) */
     _redirectHops?: number;
+    /** The URL a redirected navigation chain started from: a link to it stays pending (useLinkStatus) */
+    _redirectFrom?: string;
 }
 /**
  * Options for useRouter push/replace methods.
@@ -603,6 +618,8 @@ export interface FetchPartialOptions {
     signal?: AbortSignal;
     /** If true, this is a stale cache revalidation request - server should force revalidators */
     staleRevalidation?: boolean;
+    /** Sent as `_rsc_boundary` (wire-params.ts WIRE.boundary). */
+    boundary?: string;
     interceptSourceUrl?: string;
     /** RSC version for cache invalidation detection */
     version?: string;
@@ -667,7 +684,8 @@ export interface ServerActionBridgeConfig {
  */
 export interface NavigationBridge {
     navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
-    refresh(): Promise<void>;
+    /** `crossTab`: another tab's write; an action's error boundary stays. */
+    refresh(crossTab?: boolean): Promise<void>;
     /** `event`: the popstate event; a traversal the browser animated itself (hasUAVisualTransition) is not animated again. */
     handlePopstate(event?: PopStateEvent): Promise<void>;
     registerLinkInterception(): () => void;

package/dist/types/browser/wire-protocol.d.ts

@@ -11,6 +11,7 @@ export interface PartialRequestInit {
      */
     emptySegments: "send" | "omit";
     stale?: boolean;
+    boundary?: string;
     version?: string;
     routerId?: string;
     rewriteTarget?: string;

package/dist/types/cache/tag-invalidation.d.ts

@@ -35,19 +35,9 @@
  * 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/router/error-handling.d.ts

@@ -25,7 +25,7 @@ export interface InvokeOnErrorContext<TEnv = any> {
     isPartial?: boolean;
     handledByBoundary?: boolean;
     metadata?: Record<string, unknown>;
-    /** Request start time from performance.now() for duration calculation */
+    /** performance.now() at request entry; the request context's by default. */
     requestStartTime?: number;
 }
 /**
@@ -35,6 +35,12 @@ export interface InvokeOnErrorContext<TEnv = any> {
  * This is a shared utility used by both the router and RSC handler to ensure
  * consistent error callback behavior across the codebase.
  *
+ * `background` is set inside runAsBackgroundWork (server/request-context.ts),
+ * and `duration` and `env` come from the request context on the ALS
+ * (`_handlerStart`, `env`) when the call site leaves them out, so no call
+ * site has to know. A Prerender pass's ctx.env throws without buildEnv, so
+ * the walk never reads it eagerly.
+ *
  * @param onError - The onError callback to invoke (may be undefined)
  * @param error - The error that occurred
  * @param phase - The phase where the error occurred

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

@@ -126,6 +126,8 @@ export interface MatchContext<TEnv = any> {
     clientSegmentIds: string[];
     clientSegmentSet: Set<string>;
     stale: boolean;
+    /** NavigationSnapshot.heldBoundary: the walk stops above it. */
+    heldBoundary?: string;
     prevUrl: URL;
     prevParams: Record<string, string>;
     prevMatch: RouteMatchResult | null;

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

@@ -125,8 +125,9 @@ import { type RequestContext } from "../../server/request-context.js";
  * 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).
+ * runAsBackgroundWork also re-establishes the request ALS, which a waitUntil
+ * task on workerd loses, and marks the pass's onError reports `background`;
+ * 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>;
 /**

package/dist/types/router/navigation-snapshot.d.ts

@@ -11,6 +11,13 @@ export interface NavigationSnapshot {
     clientSegmentSet: Set<string>;
     filteredSegmentIds: string[];
     stale: boolean;
+    /**
+     * The id of an action's error boundary on screen that a stale request holds
+     * (`_rsc_boundary`, the action follow-up): read only beside `stale`, so it
+     * has every stale guarantee (a live render, no route-cache or document-cache
+     * read or store, no PPR replay).
+     */
+    heldBoundary?: string;
     isSameRouteNavigation: boolean;
     effectiveFromUrl: URL;
     effectiveFromMatch: RouteMatchResult | null;

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

@@ -9,7 +9,7 @@
  */
 import type { ReactNode } from "react";
 import type { EntryData } from "../../server/context";
-import type { ResolvedSegment, HandlerContext } from "../../types";
+import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import type { TelemetrySink } from "../telemetry.js";
 /** The errorContext shape wrapLoaderPromise expects as its 5th argument. */
@@ -70,16 +70,32 @@ export interface ErrorReportContext {
     routeKey?: string;
     env?: any;
     isPartial?: boolean;
-    requestStartTime?: number;
     telemetry?: TelemetrySink;
 }
+type Thrower = {
+    id: string;
+    type: ErrorInfo["segmentType"];
+};
+/**
+ * Note that `id` threw `error`, for an error its owning entry's boundary
+ * catches (a parallel slot's sync throw, an orphan layout's): onError names
+ * the segment that threw, as a streamed slot's rejection does. Kept on the
+ * request context, never the module: a reused error object (a constant, a
+ * memoized rejection) can be thrown by another request, or by a Prerender
+ * pass that rethrows before catchSegmentError reads it. Returns `error`, to
+ * rethrow.
+ */
+export declare function noteThrower(error: unknown, id: string, type: ErrorInfo["segmentType"]): unknown;
 /**
  * Handle a caught error during segment resolution by creating an
  * error or not-found segment with the nearest boundary.
  *
  * Called by resolveWithErrorBoundary to produce error/notFound segments.
+ * `entry` is where the boundary is looked up; `thrower` names the segment
+ * that threw when it is not `entry` (an intercept's slot, under its declaring
+ * entry), for the report, the server print and the client's ErrorInfo.
  */
-export declare function catchSegmentError<TEnv>(error: unknown, entry: EntryData, params: Record<string, string>, deps: SegmentResolutionDeps<TEnv>, report?: ErrorReportContext, pathname?: string): ResolvedSegment;
+export declare function catchSegmentError<TEnv>(error: unknown, entry: EntryData, params: Record<string, string>, deps: SegmentResolutionDeps<TEnv>, report?: ErrorReportContext, pathname?: string, thrower?: Thrower): ResolvedSegment;
 /**
  * Generic error boundary wrapper for segment resolution.
  * Catches non-Response errors and produces an error/notFound segment

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

@@ -46,6 +46,8 @@ export interface ResolutionPassInput<TEnv = any> {
     readonly routeKey: string;
     readonly actionContext?: ActionContext;
     readonly stale?: boolean;
+    /** NavigationSnapshot.heldBoundary: the walk cuts there, sending no segment. */
+    readonly heldBoundary?: string;
     /**
      * No loader is started and no loader segment is emitted: build time
      * (prerender-match.ts) and the background re-render of a route record

package/dist/types/router/segment-resolution/streamed-handler-boundary.d.ts

@@ -32,6 +32,8 @@ export interface StreamedHandlerOptions<TEnv> {
     context: HandlerContext<any, TEnv>;
     routeKey?: string;
     params: Record<string, string>;
+    /** onError's `isPartial`, as the walk reports a sync handler's error. */
+    isPartial: true | undefined;
     /** False where the rejection must reach the caller (prerender, intercept background re-render). */
     recover: boolean;
 }

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

@@ -34,13 +34,13 @@ export interface SegmentResolutionDeps<TEnv = any> {
         params?: Record<string, string>;
         env?: TEnv;
         isPartial?: boolean;
-        requestStartTime?: number;
     }, 
     /** An `ssr: false` loader on a document or capture render. */
     useDefaultErrorBoundary?: boolean) => Promise<LoaderDataResult<T>>;
     trackHandler: <T>(promise: Promise<T>, errorContext?: {
         segmentId?: string;
         segmentType?: string;
+        isPartial?: boolean;
     }) => Promise<T>;
     findNearestErrorBoundary: (entry: EntryData | null) => ReactNode | ErrorBoundaryHandler | null;
     findNearestNotFoundBoundary: (entry: EntryData | null) => ReactNode | NotFoundBoundaryHandler | null;

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

@@ -683,6 +683,15 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _renderBarrierGuardClosed?: boolean;
     /** @internal Per-request error dedup set for onError reporting */
     _reportedErrors: WeakSet<object>;
+    /**
+     * @internal The segment a parallel slot's or orphan layout's error came
+     * from, for the owning entry's catch (segment-resolution/helpers.ts
+     * noteThrower). Per request: an error object can be thrown by several.
+     */
+    _throwers?: WeakMap<object, {
+        id: string;
+        type: string;
+    }>;
     /**
      * @internal The errors this request printed to the server console, so a
      * failure prints once where it originated (server/print-server-error.ts). A derived context shares it through the prototype.
@@ -786,7 +795,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureState" | "_shellImplicitCache" | "_shellLoaderSeed" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_shellFragmentPayload" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_handlerTiming" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureState" | "_shellImplicitCache" | "_shellLoaderSeed" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_shellFragmentPayload" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_throwers" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_handlerTiming" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
@@ -816,6 +825,26 @@ export declare function captureRequestEntryContext(): (<T>(fn: () => T) => T) |
  * Used by the RSC handler to provide context to server actions
  */
 export declare function runWithRequestContext<TEnv, T>(context: RequestContext<TEnv>, fn: () => T): T;
+/**
+ * Run work whose output goes only to a cache, never to the response of the
+ * request that started it, on `context`: a stale entry's refresh (a "use
+ * cache" function, a cached loader, a cache() record, a document), a
+ * navigation's proactive cache() write, a PPR shell capture. No visitor made
+ * the invalidations in it, so they set no fresh-reads cookie
+ * (cache/tag-invalidation.ts), and onError marks every error reported inside
+ * it `background` (router/error-handling.ts invokeOnError). Its failure is
+ * reported inside it too: a catch outside runs on the visitor's frame.
+ */
+export declare function runAsBackgroundWork<TEnv, T>(context: RequestContext<TEnv>, fn: () => T): T;
+/** Whether the caller runs inside runAsBackgroundWork. */
+export declare function isBackgroundWork(): boolean;
+/**
+ * The set onError's dedupe records a reported error in. Background work keeps
+ * its own: an error object both the visitor's render and background work
+ * reach (a memoized rejection, a thrown constant) is reported by each, so a
+ * background report never takes the place of the visitor's.
+ */
+export declare function reportedErrorsOf(context: RequestContext<any>): WeakSet<object>;
 /**
  * Get the current request context
  * Throws if called outside of a request context

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

@@ -26,24 +26,30 @@
  *   - navigate() drives the navigation lifecycle as a click does:
  *     useNavigation() reads loading from the call and idle with the commit,
  *     and useLinkStatus().pending is true for a link to the destination until
- *     the commit is handed to React. A `transition` spec plus a pending
+ *     the commit, which React holds with it. A `transition` spec plus a pending
  *     Promise seeded via navigate(url, { loaders }) commits through
  *     production's commitInTransition (browser/partial-update.ts), which React
  *     holds: useNavigation() stays loading and the held reader's
  *     useLoader().isLoading reads true until the data lands. Without
  *     `transition` the commit is urgent (production's same-structure hold is
- *     not modeled). useAction().state stays idle: no action runs.
+ *     not modeled). navigate(url, { streamUntil }) gives the navigation a
+ *     response stream that stays open past the commit (isStreaming).
+ *     useAction().state stays idle: no action runs.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
- *     useRouter().replace kind "replace", refresh() kind "revalidate".
- *     Back/forward, action and optimistic clientUrls() swap decisions are
- *     e2e territory.
+ *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
+ *     back/forward that restores a page kind "pop". Action and optimistic
+ *     clientUrls() swap decisions are e2e territory.
  *   - Location state reaches readers the way it does in production:
  *     NavigationProvider holds the committed entry's state next to the
  *     payload, so a navigation whose loader the test holds keeps the entry
  *     being left on screen with its own state. A `popstate` event is a
- *     back/forward onto the entry history.state holds; the tree has one
- *     location, so no page is restored with it. A server action's state, a
+ *     back/forward onto the entry history.state holds. When it is the
+ *     mounted entry or one a navigate() wrote, history still holds the state
+ *     written there, and another page is on screen, its page is restored
+ *     from the history cache, with the handle values it had, as production's
+ *     restore is; otherwise the tree keeps its location. A stale entry's
+ *     revalidation, a restore that fetches, a server action's state, a
  *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
@@ -361,8 +367,37 @@ export interface TestRouterHandle {
      * `handles`). They arrive on the response's handle stream, so `useHandle`
      * readers take them with the page's commit: while React holds the page,
      * readers keep the values of the page being left.
+     *
+     * `options.streamUntil` gives the navigation a response stream, as a real
+     * response has: it opens in a task after the call, before the commit (the
+     * response arrives, and `useNavigation().pendingUrl` clears), and stays open
+     * until the promise settles (a page that streams a tail past its commit:
+     * `isStreaming` reads true until then). Without it the navigation has no
+     * stream. A navigation that a newer one or a back/forward aborts before its
+     * response arrives opens none and commits nothing; one aborted after its
+     * response arrived stops counting as streaming at the abort, as in
+     * production, where its response streams on and is ignored.
+     *
+     * @example
+     * const tail = deferred();
+     * await router.navigate("/products/2", { streamUntil: tail.promise });
+     * // useNavigation(): idle, isStreaming true
+     * await act(async () => tail.resolve());
+     * // useNavigation(): idle, isStreaming false
+     *
+     * A navigation started while React holds a page goes inside
+     * `await act(async () => ...)`. Its first update makes React retry the held
+     * page, which suspends again; a synchronous act() scope drops that retry
+     * and React renders no later update of the same priority.
+     *
+     * @example
+     * await act(async () => {
+     *   await router.navigate("/products/3", { transition: false });
+     * });
      */
-    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & Pick<NavigateOptions, "state" | "replace" | "transition">): Promise<void>;
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & Pick<NavigateOptions, "state" | "replace" | "transition"> & {
+        streamUntil?: Promise<unknown>;
+    }): Promise<void>;
     /**
      * Re-render the current location, as router.refresh() does: a spec's
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).

package/dist/types/testing/serve-shell-request.d.ts

@@ -81,7 +81,13 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * and segments take an action's revalidation defaults; it renders live, as
      * an action does, so neither the route cache nor the document cache answers
      * or stores it, and a `ppr` route's `replayStatus` is
-     * `{ outcome: "BYPASS", reason: "stale" }`.
+     * `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error
+     * segment of a thrown action's boundary the page at `from` shows
+     * (`_rsc_boundary`), as the follow-up an earlier action owes that page
+     * sends it, with `stale: true` and no `segments`: the response renders
+     * every segment above the boundary and nothing at or below it, claims the
+     * boundary in `matched` and sends no segment for it. The server reads it
+     * only beside `stale`.
      */
     partial?: true | {
         from?: string;
@@ -91,6 +97,7 @@ export interface ServeShellRequestOptions<TEnv = any> {
         fill?: boolean;
         interceptSource?: string;
         stale?: boolean;
+        boundary?: string;
     };
     /**
      * POST this form as a submit before hydration: the no-JS request the

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

@@ -67,19 +67,38 @@ export interface OnErrorContext<TEnv = any> {
     actionId?: string;
     /** Environment/bindings (platform context) */
     env?: TEnv;
-    /** Duration from request start to error (milliseconds) */
+    /**
+     * Duration from request start to error (milliseconds). For a `background`
+     * error it counts from the start of the request that started the work, so
+     * it includes that response and any wait before the work ran.
+     */
     duration?: number;
     /**
      * Whether this is a partial/navigation request, on an error the segment
-     * walk catches (a handler that throws, a DSL loader that rejects): `true`
-     * for a navigation, unset for a document. An error in the background
-     * re-render of a `cache()` record (a stale HIT's refresh, the write of a
-     * navigation that kept a layout mounted) reports the request that started
-     * it. A streamed (`loading()`) handler's rejection does not carry it, in
-     * either render; the `routing` phase reports `false`.
+     * walk catches (a handler that throws, a streamed `loading()` handler that
+     * rejects, a DSL loader that rejects): `true` for a navigation, unset for a
+     * document. A `cache()` record's refresh or proactive write reports the
+     * request that started it; a PPR shell capture renders a document. The
+     * `routing` phase reports `false`.
      */
     isPartial?: boolean;
-    /** Whether an error boundary caught the error */
+    /**
+     * `true` when the error came from work whose output goes to a cache and
+     * never to the response of the request that started it: a stale `cache()`
+     * record's refresh, the write of a navigation that kept a layout mounted, a
+     * stale document cache entry's re-run, a PPR shell capture, or a stale
+     * `"use cache"` function's or cached loader's refresh, the work's own
+     * failure included. `request` and `url` are the starting request's (a
+     * shell capture's handler errors name the page it captures). A
+     * `router.prerender()` warm's own render is its request's: unset, while a
+     * shell capture it makes is `true`. Unset for every other error.
+     */
+    background?: boolean;
+    /**
+     * Whether an error boundary caught the error and its fallback reached the
+     * response. `false` on a `background` error: the failed render is never
+     * stored, so no visitor sees the fallback.
+     */
     handledByBoundary?: boolean;
     /** Stack trace (if available) */
     stack?: string;