@rangojs/router 0.28.0 → 0.30.0

package/src/browser/server-action-bridge.ts

@@ -15,6 +15,9 @@ import {
 import { KEEP_CACHE_HEADER } from "./cookie-name.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
+  actionBoundaries,
+  actionBoundaryAt,
+  idsAboveBoundary,
   reconcileSegments,
   reconcileErrorSegments,
 } from "./segment-reconciler.js";
@@ -206,6 +209,8 @@ export function createServerActionBridge(
     actionId?: string;
     /** transition({ when }) `action` fields for the refetch commit. */
     action?: TransitionWhenActionInput;
+    /** The follow-up's held error boundary (UpdateMode `action`). */
+    boundary?: string;
   };
 
   /** The follow-up's transition({ when }) fields: the last owing action's. */
@@ -255,13 +260,13 @@ export function createServerActionBridge(
   let followUpsStarted = 0;
   /** The newest follow-up, until it ends: leaveFollowUp() aborts it. */
   let followUpRunning: { handle: NavigationHandle; due: FollowUp } | undefined;
-
   /**
    * The follow-up revalidation: the rules are R1-R7 in
    * docs/internal/execution-model.md. Once the batch's last action exited,
    * the page on screen that missed a write is refetched once, whole (no
-   * segments held, so every loader re-runs), in the action lane (storeOnly,
-   * skipLoadingState: useNavigation() stays idle).
+   * segments held, so every loader re-runs; above an action's boundary, see
+   * below), in the action lane (storeOnly, skipLoadingState:
+   * useNavigation() stays idle).
    *
    * - Never over an intercept: a request holding no segments drops the page
    *   under it (match-result.ts buildMatchResult). Checked when it would run,
@@ -271,6 +276,10 @@ export function createServerActionBridge(
    *   keeps its error on screen, and the debt is dropped.
    * - Runs again when it is left before its commit (a navigation, or an action
    *   that started: leaveFollowUp), for the page then on screen.
+   * - Holds the action error boundary the page shows (actionBoundaryAt): it
+   *   is that action's outcome, which no GET reproduces, so the server
+   *   renders every segment above it and nothing at or below it. With
+   *   nothing above it (the page's first segment), the debt is dropped.
    */
   function followUp(): void {
     if (!owed || isActionFenceActive()) return;
@@ -285,8 +294,16 @@ export function createServerActionBridge(
     const due = owed;
     owed = undefined;
     if (store.getInterceptSourceUrl()) return;
+    // The deepest action boundary the page shows: none (-1) refetches the
+    // page whole, the first segment (0) leaves nothing above it.
+    const shown =
+      store.getCachedSegments(store.getHistoryKey())?.segments ?? [];
+    const at = actionBoundaryAt(shown);
+    if (at === 0) return;
+    // Not on `due`: a run owed again (owed ??= due) looks again.
+    const held = { ...due, boundary: shown[at]?.id };
     const generation = ++followUpsStarted;
-    refetchRoute(due, {
+    refetchRoute(held, {
       started: (handle) => (followUpRunning = { handle, due }),
       ended: (left) => {
         if (generation !== followUpsStarted) return;
@@ -359,6 +376,7 @@ export function createServerActionBridge(
           ...(src ? { interceptSourceUrl: src } : {}),
           ...(opts.actionId !== undefined ? { actionId: opts.actionId } : {}),
           ...(opts.action ? { action: opts.action } : {}),
+          boundary: opts.boundary,
         },
       );
       return { started: true, error };
@@ -794,11 +812,15 @@ export function createServerActionBridge(
         // Cache (and bump the nav instance) BEFORE the UI update so a deferred
         // handle pushed by the error-boundary render still applies — see the
         // "normal" case below for why caching after onUpdate dropped it. The
-        // page stops claiming the error segments only: the loaders the
-        // response re-ran above the boundary stay held.
+        // action's boundary is the last error segment: the server's cut stops
+        // there (segment-resolution/revalidation.ts resolveAllSegments). The
+        // page holds what is above it, the loaders the response re-ran
+        // included, and no error segment.
+        const errors = segments.filter((s) => s.type === "error");
+        const boundary = errors[errors.length - 1];
         store.setSegmentIds(
-          segmentState.currentSegmentIds.filter(
-            (id) => !segments.some((s) => s.id === id && s.type === "error"),
+          idsAboveBoundary(segmentState.currentSegmentIds, boundary?.id).filter(
+            (id) => !errors.some((s) => s.id === id),
           ),
         );
         const currentHandleData = liveHandleDataForCache(
@@ -812,6 +834,7 @@ export function createServerActionBridge(
           currentHandleData,
         );
         store.rememberDisplayedEntry();
+        if (boundary) actionBoundaries.add(boundary);
 
         // Update UI with error boundary.
         if (process.env.NODE_ENV !== "production") auditTreeCause("action");
@@ -912,6 +935,10 @@ export function createServerActionBridge(
           metadata?.locationState,
           eventController,
         );
+        // A success on the page supersedes the action boundary it shows
+        // (R4): a repair that stands in for this commit, direct or owed to
+        // the batch's end, holds none.
+        for (const s of cachedSegments) actionBoundaries.delete(s);
       }
       whenAction = { ...whenAction, result: returnData };
 

package/src/browser/types.ts

@@ -201,13 +201,27 @@ 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) */
@@ -239,7 +253,11 @@ export type ActionLifecycleState = "idle" | "loading" | "streaming";
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface TrackedActionState {
-  /** Current lifecycle state of the action */
+  /**
+   * Current lifecycle state of the action. Once the call settles it is
+   * "idle" and the rest of the call's state is kept until the action's next
+   * call.
+   */
   state: ActionLifecycleState;
 
   /** Server action function ID (e.g., "addToCart") */
@@ -251,13 +269,13 @@ export interface TrackedActionState {
   /** Error if action failed */
   error: unknown | null;
 
-  /** Result data from the action (preserved after completion) */
+  /** Result data from the action */
   result: unknown | null;
 
   /**
    * The error of a loader that threw while it re-ran after this successful
-   * action (the first, when several did). The loader also throws at its
-   * useLoader read, where the nearest error boundary catches it.
+   * action (the first, when several did). The loader also throws at its useLoader read, where the nearest
+   * error boundary catches it.
    */
   revalidationError: unknown | null;
 }
@@ -505,6 +523,8 @@ export interface NavigateOptionsInternal extends Omit<
   _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;
 }
 
 /**
@@ -718,6 +738,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;
@@ -803,7 +825,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/src/browser/wire-protocol.ts

@@ -13,6 +13,7 @@ export interface PartialRequestInit {
    */
   emptySegments: "send" | "omit";
   stale?: boolean;
+  boundary?: string;
   version?: string;
   routerId?: string;
   rewriteTarget?: string;
@@ -33,6 +34,7 @@ export function writePartialParams(url: URL, init: PartialRequestInit): URL {
     params.set(WIRE.segments, init.segmentIds.join(","));
   }
   if (init.stale) params.set(WIRE.stale, "true");
+  if (init.boundary) params.set(WIRE.boundary, init.boundary);
   if (init.version) params.set(WIRE.version, init.version);
   if (init.routerId) params.set(WIRE.routerId, init.routerId);
   if (init.rewriteTarget) params.set(WIRE.rewriteTarget, init.rewriteTarget);

package/src/cache/cache-runtime.ts

@@ -22,6 +22,7 @@ import {
 } from "../deps/rsc-client.js";
 import {
   getRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../server/request-context.js";
 import { isUnderTestRunner } from "../runtime-env.js";
@@ -75,7 +76,6 @@ import {
   executionStart,
   invalidatedSince,
   predatesInvalidation,
-  runAsBackgroundRefresh,
   type ExecutionStart,
 } from "./tag-invalidation.js";
 import type { CacheItemResult } from "./types.js";
@@ -727,22 +727,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // user's value into the shared entry — with zero visibility to the
             // concurrent foreground.
 
-            try {
-              // Re-establish the request-context ALS so a "use cache" body that
-              // reads the ambient getRequestContext() (e.g.
-              // getRequestContext().env.ApiKey) resolves during the background
-              // revalidation instead of throwing "called outside of a request
-              // context". runAsBackgroundRefresh sets the store for fn's
-              // synchronous kickoff; its async continuations inherit it. No
-              // visitor made the invalidations it runs: they set no
-              // fresh-reads cookie.
-              //
-              // The span opens inside the request ALS and wraps the WHOLE task —
-              // fn kickoff through the store write — so its platform spans nest
-              // under rango.background and a slow or failing setItem is part of
-              // the traced revalidation, not an untraced tail.
-              await runAsBackgroundRefresh(requestCtx, () =>
-                observePhase(
+            // Re-establish the request-context ALS so a "use cache" body that
+            // reads the ambient getRequestContext() (e.g.
+            // getRequestContext().env.ApiKey) resolves during the background
+            // revalidation instead of throwing "called outside of a request
+            // context". runAsBackgroundWork sets the store for fn's synchronous
+            // kickoff; its async continuations inherit it. No visitor made the
+            // invalidations it runs (no fresh-reads cookie), and onError marks
+            // its errors `background`, the failure caught below included.
+            //
+            // The span opens inside the request ALS and wraps the WHOLE task —
+            // fn kickoff through the store write — so its platform spans nest
+            // under rango.background and a slow or failing setItem is part of
+            // the traced revalidation, not an untraced tail.
+            await runAsBackgroundWork(requestCtx, async () => {
+              try {
+                await observePhase(
                   PHASES.background("use-cache-revalidation"),
                   async () => {
                     const refreshArgs = args.map(refreshView);
@@ -796,20 +796,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                       noteWarmWrite(requestCtx, "item");
                     }
                   },
-                ),
-              );
-            } catch (bgError) {
-              bgCapture?.stop();
-              // Pass requestCtx explicitly: this runs in a detached background
-              // task where the ALS context is gone, so onError can only fire if
-              // we hand it the context captured up front.
-              reportCacheError(
-                bgError,
-                "stale-revalidation",
-                "[use cache] background revalidation failed",
-                requestCtx,
-              );
-            }
+                );
+              } catch (bgError) {
+                bgCapture?.stop();
+                reportCacheError(
+                  bgError,
+                  "stale-revalidation",
+                  "[use cache] background revalidation failed",
+                  requestCtx,
+                );
+              }
+            });
           }),
         );
         return result;

package/src/cache/document-cache.ts

@@ -22,7 +22,7 @@ import {
 import {
   createRequestContext,
   getRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../server/request-context.js";
 import { deriveRenderPass } from "../server/render-pass.js";
@@ -378,24 +378,25 @@ export function createDocumentCacheMiddleware<TEnv = any>(
           }),
         });
 
-        runBackground(requestCtx, async () => {
-          try {
-            // Re-establish the request-context ALS around the whole background
-            // task: next() re-runs the full handler pipeline, and on workerd a
-            // waitUntil task runs detached from the request's I/O context, so a
-            // handler/component reading getRequestContext() would otherwise
-            // throw. Same fix as the route-level/use-cache background
-            // revalidation paths. The rango.background span (kind=
-            // document-revalidation) wraps the re-render AND the store write so
-            // the task's spans — the re-run's own rango.* set and the drain/put
-            // platform spans — nest under one explanatory parent instead of
-            // dangling under the ended foreground phases. Running the put
-            // inside the ALS matches the MISS path, where putResponse already
-            // executes within the foreground request context. No visitor made
-            // the invalidations the re-run makes: the pass's fresh-reads
-            // writer is the sink's, which sets nothing.
-            await runWithRequestContext(rerunCtx, () =>
-              observePhase(
+        // Re-establish the request-context ALS around the whole background
+        // task: next() re-runs the full handler pipeline, and on workerd a
+        // waitUntil task runs detached from the request's I/O context, so a
+        // handler/component reading getRequestContext() would otherwise
+        // throw. Same fix as the route-level/use-cache background
+        // revalidation paths. The rango.background span (kind=
+        // document-revalidation) wraps the re-render AND the store write so
+        // the task's spans — the re-run's own rango.* set and the drain/put
+        // platform spans — nest under one explanatory parent instead of
+        // dangling under the ended foreground phases. Running the put
+        // inside the ALS matches the MISS path, where putResponse already
+        // executes within the foreground request context. No visitor made
+        // the invalidations the re-run makes: the pass's fresh-reads
+        // writer is the sink's, which sets nothing. onError marks the
+        // re-run's errors `background`, the failure caught below included.
+        runBackground(requestCtx, () =>
+          runAsBackgroundWork(rerunCtx, async () => {
+            try {
+              await observePhase(
                 PHASES.background("document-revalidation"),
                 async () => {
                   const fresh = await next();
@@ -425,24 +426,20 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                     `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
                   );
                 },
-              ),
-            );
-          } catch (error) {
-            // The route now rewrites (route middleware): nothing to refresh
-            // this entry with.
-            if (isRewrite(error)) return;
-            // Pass requestCtx explicitly: this runs in a detached waitUntil task
-            // where the ALS context is gone, so onError only fires if we hand it
-            // the captured context (reportCacheError falls back to _getRequestContext
-            // otherwise, which is null here).
-            reportCacheError(
-              error,
-              "cache-write",
-              "[DocumentCache] revalidation",
-              requestCtx,
-            );
-          }
-        });
+              );
+            } catch (error) {
+              // The route now rewrites (route middleware): nothing to refresh
+              // this entry with.
+              if (isRewrite(error)) return;
+              reportCacheError(
+                error,
+                "cache-write",
+                "[DocumentCache] revalidation",
+                requestCtx,
+              );
+            }
+          }),
+        );
 
         return drainOnResponseCallbacks(
           addCacheStatusHeader(cached.response, "STALE"),

package/src/cache/read-through-swr.ts

@@ -117,29 +117,31 @@ export async function readThroughItem<T>(
       // span cover the write too (a slow or failing store write is part of
       // the revalidation, not an untraced tail). The foreground miss below
       // stays unwrapped: its context is already established.
+      // Reported inside the task, within wrapBackground's frame, so onError
+      // marks it `background`; rethrown so the span records the failure.
       const revalidateTask = async () => {
-        const fresh = await execute();
-        const serialized = await serialize(fresh);
-        if (serialized !== null) {
-          await setItem(key, serialized, storeOptions);
+        try {
+          const fresh = await execute();
+          const serialized = await serialize(fresh);
+          if (serialized !== null) {
+            await setItem(key, serialized, storeOptions);
+          }
+        } catch (error) {
+          reportCacheError(
+            error,
+            "stale-revalidation",
+            "[read-through] background revalidation",
+            host ?? undefined,
+          );
+          throw error;
         }
       };
       runBackground(
         host,
-        async () => {
-          try {
-            await (wrapBackground
-              ? wrapBackground(revalidateTask)
-              : revalidateTask());
-          } catch (error) {
-            reportCacheError(
-              error,
-              "stale-revalidation",
-              "[read-through] background revalidation",
-              host ?? undefined,
-            );
-          }
-        },
+        () =>
+          (wrapBackground ? wrapBackground(revalidateTask) : revalidateTask())
+            // Reported above.
+            .catch(() => {}),
         true,
       );
       return data;

package/src/cache/tag-invalidation.ts

@@ -36,11 +36,9 @@
  * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
  */
 
-import { AsyncLocalStorage } from "node:async_hooks";
 import {
   _getRequestContext,
-  runWithRequestContext,
-  type RequestContext,
+  isBackgroundWork,
 } from "../server/request-context.js";
 import { reportingAsync } from "./cache-error.js";
 import { normalizeTags } from "./cache-tag.js";
@@ -134,20 +132,6 @@ function warnPartialTagStore(fn: string, incapable: number): void {
   );
 }
 
-const backgroundRefresh = new AsyncLocalStorage<true>();
-
-/**
- * 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 function runAsBackgroundRefresh<T>(ctx: RequestContext, fn: () => T): T {
-  return runWithRequestContext(ctx, () => backgroundRefresh.run(true, fn));
-}
-
 /**
  * Set the fresh-reads cookie on this request's response for as long as the
  * invalidated stores' isolate memos can stay stale (isolate-tag-memo.ts), so
@@ -155,7 +139,8 @@ export function runAsBackgroundRefresh<T>(ctx: RequestContext, fn: () => T): T {
  */
 function markFreshReads(stores: SegmentCacheStore[]): void {
   const ctx = _getRequestContext();
-  if (!ctx?._setFreshReadsCookie || backgroundRefresh.getStore()) return;
+  // No visitor made an invalidation in background work (runAsBackgroundWork).
+  if (!ctx?._setFreshReadsCookie || isBackgroundWork()) return;
   let windowMs = 0;
   for (const store of stores) {
     windowMs = Math.max(windowMs, store.freshReadsWindowMs ?? 0);

package/src/router/error-handling.ts

@@ -8,6 +8,10 @@
 import { createElement, type ReactNode } from "react";
 import type { EntryData } from "../server/context.js";
 import { runIdentityExempt } from "../cache/cache-exec-scope.js";
+import {
+  _getRequestContext,
+  isBackgroundWork,
+} from "../server/request-context.js";
 import type {
   ResolvedSegment,
   ErrorInfo,
@@ -39,7 +43,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;
 }
 
@@ -50,6 +54,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
@@ -66,9 +76,10 @@ export function invokeOnError<TEnv = any>(
   if (!onError) return;
 
   const errorObj = error instanceof Error ? error : new Error(String(error));
-  const duration = context.requestStartTime
-    ? performance.now() - context.requestStartTime
-    : undefined;
+  const reqCtx = _getRequestContext();
+  const background = isBackgroundWork() || undefined;
+  const start = context.requestStartTime ?? reqCtx?._handlerStart;
+  const duration = start !== undefined ? performance.now() - start : undefined;
 
   const errorContext: OnErrorContext<TEnv> = {
     error: errorObj,
@@ -84,10 +95,11 @@ export function invokeOnError<TEnv = any>(
     loaderName: context.loaderName,
     middlewareId: context.middlewareId,
     actionId: context.actionId,
-    env: context.env,
+    env: context.env ?? (reqCtx?.env as TEnv | undefined),
     duration,
     isPartial: context.isPartial,
-    handledByBoundary: context.handledByBoundary,
+    background,
+    handledByBoundary: background ? false : context.handledByBoundary,
     stack: errorObj.stack,
     metadata: context.metadata,
   };

package/src/router/intercept-resolution.ts

@@ -164,15 +164,16 @@ export function findInterceptForRoute(
 /**
  * An intercept handler's throw or notFound() renders the declaring entry's
  * boundary as the slot component (catchSegmentError, as for route handlers on
- * partial navigations: 500/404 status, onError "handler"). Responses rethrow.
- * The background re-render (`background`) reports the error the same way and
- * then rethrows it, so a failed re-render aborts its cache write instead of
- * storing the fallback.
+ * partial navigations: 500/404 status, onError "handler" naming the slot).
+ * Responses rethrow. The background re-render (`background`) reports the
+ * error the same way and then rethrows it, so a failed re-render aborts its
+ * cache write instead of storing the fallback.
  */
 function renderInterceptHandlerError<TEnv>(
   pass: ResolutionPass<TEnv>,
   error: unknown,
   parentEntry: EntryData,
+  slotSegmentId: string,
   background: boolean | undefined,
 ): ReactNode {
   if (error instanceof Response) throw error;
@@ -193,6 +194,7 @@ function renderInterceptHandlerError<TEnv>(
       telemetry,
     },
     pass.context.pathname,
+    { id: slotSegmentId, type: "parallel" },
   );
   if (background) throw error;
   return component;
@@ -363,6 +365,7 @@ export async function resolveInterceptEntry<TEnv>(
       pass,
       error,
       parentEntry,
+      slotSegmentId,
       options?.background,
     );
   }
@@ -402,6 +405,7 @@ export async function resolveInterceptEntry<TEnv>(
       context,
       routeKey: interceptEntry.routeName,
       params,
+      isPartial: true,
       recover: !options?.background,
     });
 
@@ -429,6 +433,7 @@ export async function resolveInterceptEntry<TEnv>(
           pass,
           error,
           parentEntry,
+          slotSegmentId,
           options?.background,
         );
       }

package/src/router/match-api.ts

@@ -514,6 +514,7 @@ export async function createMatchContextForPartial<TEnv>(
     clientSegmentIds: nav.clientSegmentIds,
     clientSegmentSet,
     stale: nav.stale,
+    heldBoundary: nav.heldBoundary,
     prevUrl: nav.prevUrl,
     prevParams: nav.prevParams,
     prevMatch: nav.prevMatch,

package/src/router/match-context.ts

@@ -136,6 +136,8 @@ export interface MatchContext<TEnv = any> {
   clientSegmentIds: string[];
   clientSegmentSet: Set<string>;
   stale: boolean;
+  /** NavigationSnapshot.heldBoundary: the walk stops above it. */
+  heldBoundary?: string;
 
   // Previous navigation state
   prevUrl: URL;
@@ -219,6 +221,7 @@ export function resolutionPassInput<TEnv>(
     routeKey: ctx.routeKey,
     actionContext: ctx.actionContext,
     stale: ctx.stale,
+    heldBoundary: ctx.heldBoundary,
   };
 }