@rangojs/router 0.24.4 → 0.26.0

package/src/rsc/rsc-rendering.ts

@@ -40,6 +40,7 @@ import {
   renderRscFlightStage,
   renderRscResponse,
 } from "./render-pipeline.js";
+import { markPrefetchOnRenderError } from "./prefetch-render-error.js";
 import {
   createRoutineTrace,
   handoff,
@@ -51,7 +52,7 @@ import {
 import type { HandlerContext } from "./handler-context.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
 import { publicRouteName } from "../route-name.js";
-import { buildFullPayload, renderedLocation } from "./full-payload.js";
+import { buildFullPayload, payloadLocation } from "./full-payload.js";
 import {
   capShellWindow,
   lastStoredCaptureSeq,
@@ -94,6 +95,8 @@ import {
   type DevShellLookup,
 } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
+import { rewriteShellAudience, rewriteTrail } from "../server/rewrite-trail.js";
+import { visitorShellKey } from "./shell-capture-constants.js";
 import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import {
   isWarmReplace,
@@ -155,10 +158,52 @@ function describePprReplayStatus(status: PprReplayStatus): string {
     : `bypass:${status.reason}`;
 }
 
+/**
+ * The shell key before the route's own partition, or undefined: a request
+ * middleware rewrote reads and captures no shell unless its rewrite chose
+ * `.shell()`, so a URL's shared shell is read and written only by requests
+ * on that URL (#1146).
+ */
+interface RequestShellBase {
+  baseKey: string;
+  /** shellSearchSeed of the URL the key names. */
+  searchSeed: string;
+  /** A visitor-keyed shell's location (ShellCacheEntry.pathname). */
+  pathname?: string;
+}
+
+function requestShellBase(
+  ctx: HandlerContext<any>,
+  reqCtx: RequestContext<any>,
+  url: URL,
+): RequestShellBase | undefined {
+  const filter = reqCtx._searchParamsFilter;
+  const trail = rewriteTrail(reqCtx);
+  const shell = rewriteShellAudience(reqCtx);
+  if (trail && shell === "visitor") {
+    const visitor = new URL(trail[0]!);
+    return {
+      baseKey: visitorShellKey(
+        ctx.router.id,
+        visitor,
+        new URL(trail[trail.length - 1]!),
+        filter,
+      ),
+      searchSeed: shellSearchSeed(visitor, filter),
+      pathname: visitor.pathname,
+    };
+  }
+  if (trail && shell !== "target") return undefined;
+  return {
+    baseKey: buildShellKey(ctx.router.id, url, filter),
+    searchSeed: shellSearchSeed(url, filter),
+  };
+}
+
 function createShellCaptureDescriptor(
   ctx: HandlerContext<any>,
   key: string,
-  searchSeed: string,
+  base: RequestShellBase,
   originSeed: string,
   pprConfig: ResolvedPprConfig,
   store: SegmentCacheStore<any>,
@@ -166,7 +211,8 @@ function createShellCaptureDescriptor(
 ): ShellCaptureDescriptor {
   return {
     key,
-    searchSeed,
+    searchSeed: base.searchSeed,
+    pathname: base.pathname,
     // Derived from the same request URL as the key (the callers compute
     // both next to each other, so they cannot drift): seeding the origin
     // keeps origin-dependent static markup (Link's data-external)
@@ -499,13 +545,15 @@ function* shellServePlan<TEnv>(
   // no shell read, no capture, so it can never degrade again. The handler
   // stripped the marker from the request and left this flag.
   if (reqCtx._shellForcedMiss) return { kind: "pass" };
+  const base = requestShellBase(ctx, reqCtx, url);
+  if (!base) return { kind: "pass" };
 
   // A per-request CSP nonce pins the route to axis 1: a shared shell would
   // freeze the capture request's nonce and CSP would reject it for every
   // other visitor. Every step below, a HIT included, therefore runs without
   // one.
   const store = reqCtx._cacheStore;
-  const baseKey = buildShellKey(ctx.router.id, url, reqCtx._searchParamsFilter);
+  const { baseKey } = base;
   if (activeRequestNonce(nonce, reqCtx) !== undefined) {
     // Declared intent that cannot be honored deserves a diagnostic (unlike an
     // undeclared route, which is silent): a ppr route gated off by an active
@@ -596,7 +644,7 @@ function* shellServePlan<TEnv>(
   const descriptor = createShellCaptureDescriptor(
     ctx,
     key,
-    shellSearchSeed(url, reqCtx._searchParamsFilter),
+    base,
     url.origin,
     pprConfig,
     store,
@@ -626,10 +674,13 @@ function* shellServePlan<TEnv>(
   // A HIT replays the handler layer from the entry's doc record (`docKey`),
   // or, for a Prerender route, from the prerender store. An entry that has
   // neither is a MISS: serving it would run handlers after the commit.
+  // The entry must have rendered this request's location: the browser
+  // hydrates against the address bar.
   if (
     cached &&
     !cached.entry.navigationOnly &&
     (cached.entry.docKey !== undefined || route?.matched?.pr === true) &&
+    cached.entry.pathname === base.pathname &&
     isValidShellHit(cached.entry, ctx.version)
   ) {
     const document = openShellDocumentMetered(reqCtx, cached);
@@ -713,7 +764,9 @@ function* shellServePlan<TEnv>(
   // compile-time constant).
   const devShellLookup = resolveDevShellLookup(reqCtx, pprConfig);
   let buildHit: Awaited<ReturnType<typeof lookupBuildShell>> = null;
-  if (key !== baseKey) {
+  if (base.pathname !== undefined) {
+    // A build shell is the target's: never served under a visitor key.
+  } else if (key !== baseKey) {
     // Probed once per path without a build shell, and not again once the
     // route warned. A search-bearing URL never reads one: nothing to probe.
     const routeName = reqCtx._classifiedRoute?.routeKey;
@@ -845,7 +898,7 @@ function* preparePayloadPlan<TEnv>(
       kind: "payload",
       payload: {
         metadata: {
-          pathname: renderedLocation(reqCtx, url).pathname,
+          ...payloadLocation(reqCtx, url),
           // routerId is serialized on every payload (including within-session
           // ones) so the frontend can read the current app/router identity. It
           // always equals the current app's id: a cross-app navigation is
@@ -1209,16 +1262,6 @@ function renderPreparedRscResponse<TEnv>(
   if (sourceScoped) {
     rscHeaders["x-rsc-prefetch-scope"] = "source";
   }
-  // Enable browser HTTP caching for prefetch responses only.
-  // Requires a prefetch request (X-Rango-Prefetch, sent by Link prefetch
-  // fetch), a source-agnostic response (see sourceScoped above), and a
-  // configured cache-control value (false disables caching).
-  if (reqCtx._requestKind === "prefetch" && isPartial && !sourceScoped) {
-    const cc = ctx.router.prefetchCacheControl;
-    if (cc) {
-      rscHeaders["cache-control"] = cc;
-    }
-  }
   // prefetch: false (docs/design/prefetch-false.md, R7). A response that
   // carries deferred units answers one page's prefetch, and a fill is the
   // second half of one adoption: neither is reused by a shared cache or the
@@ -1248,7 +1291,7 @@ function renderPreparedRscResponse<TEnv>(
       reqCtx._activeRoutine &&
       createRenderStageTraceBridge(reqCtx._activeRoutine),
   };
-  return renderRscResponse(
+  const rendered = renderRscResponse(
     {
       ctx,
       request,
@@ -1272,6 +1315,11 @@ function renderPreparedRscResponse<TEnv>(
           }),
         },
   );
+  // A prefetch whose render reported an error is not kept (#1170).
+  if (reqCtx._requestKind !== "prefetch" || !isPartial) return rendered;
+  return rendered.then((response) =>
+    markPrefetchOnRenderError(response, reqCtx._renderErrors ?? []),
+  );
 }
 
 /**
@@ -1286,6 +1334,8 @@ function scheduleNavigationShellCapture<TEnv>(
   const { ctx, request, env, url, reqCtx } = input;
   const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry)!;
   const store = reqCtx._cacheStore!;
+  const base = requestShellBase(ctx, reqCtx, url);
+  if (!base) return;
   scheduleShellCapture(
     ctx,
     request,
@@ -1305,7 +1355,7 @@ function scheduleNavigationShellCapture<TEnv>(
     createShellCaptureDescriptor(
       ctx,
       captureKey,
-      shellSearchSeed(url, reqCtx._searchParamsFilter),
+      base,
       url.origin,
       pprConfig,
       store,
@@ -1464,10 +1514,13 @@ async function matchPartialWithPprReplay<TEnv>(
     return runMatch({ outcome: "BYPASS", reason: "cache-disabled" });
   }
 
+  const base = requestShellBase(ctx, reqCtx, url);
+  if (!base) return runMatch({ outcome: "BYPASS", reason: "rewritten" });
+
   // The visitor's own partition (resolveShellPartition): replay never
   // crosses into another partition's shell.
   const key = await resolveRequestShellKey(
-    buildShellKey(ctx.router.id, url, reqCtx._searchParamsFilter),
+    base.baseKey,
     routeSnapshot,
     store,
     reqCtx,
@@ -1806,6 +1859,9 @@ function serveShellHit(
   descriptor: ShellCaptureDescriptor,
 ): Response {
   const { entry, prelude: preludeBytes } = document;
+  // A visitor-keyed shell shows the visitor's URL: the document cache keys
+  // this response by the target.
+  if (entry.pathname !== undefined) reqCtx._payloadVisitorLocation = true;
   const metricsStore = reqCtx._metricsStore;
   // Per-stage tail timing for the `ppr:tail` Server-Timing mirror and the
   // perf console line: always in dev, in production only when this request
@@ -1867,8 +1923,8 @@ function serveShellHit(
       payload.metadata.initialTheme = entry.initialTheme as
         | import("../theme/types.js").Theme
         | undefined;
-      // Same for the location: the capture rendered the target's.
-      payload.metadata.pathname = url.pathname;
+      // Same for the location: the key's URL, or a visitor-keyed shell's.
+      payload.metadata.pathname = entry.pathname ?? url.pathname;
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).
@@ -1911,7 +1967,7 @@ function serveShellHit(
         nonce: undefined,
         // The shell key's own search — identical to the capture seed for
         // this key, so the resume tree matches the captured tree.
-        search: shellSearchSeed(url, reqCtx._searchParamsFilter),
+        search: descriptor.searchSeed,
         // The HIT request's origin — same host as the capture's (key-scoped).
         origin: url.origin,
         // The document cache reads the list before storing this composite.

package/src/rsc/server-action.ts

@@ -24,6 +24,7 @@ import { observePhase, PHASES } from "../router/instrument.js";
 import { resolveActionRefId } from "../router/is-action.js";
 import type { TraceSpan } from "../router/tracing.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
+import { payloadLocation } from "./full-payload.js";
 import { publicRouteName } from "../route-name.js";
 import type { RscPayload } from "./types.js";
 import {
@@ -323,6 +324,28 @@ export async function executeServerAction<TEnv>(
   };
 }
 
+/**
+ * The continuation for a rewrite pass after the action ran (#1145): a failed
+ * action's error boundary is re-matched on the target, since the one pass 1
+ * matched (or missed) is the rewriting route's.
+ */
+export async function continuationForRewritePass<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  continuation: ActionContinuation,
+): Promise<ActionContinuation> {
+  if (continuation.returnValue.ok) return continuation;
+  const errorBoundary =
+    (await ctx.router.matchError(
+      request,
+      { env },
+      continuation.actionContext.actionResult,
+      "route",
+    )) ?? undefined;
+  return { ...continuation, errorBoundary };
+}
+
 /**
  * Phase 2: Revalidate after action.
  *
@@ -513,7 +536,7 @@ function renderActionBoundaryResponse<TEnv>(
 
   const errorPayload: RscPayload = {
     metadata: {
-      pathname: url.pathname,
+      ...payloadLocation(reqCtx, url),
       // routerId exposed for the frontend (current app identity); see
       // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,
@@ -576,7 +599,7 @@ function renderRevalidationResponse<TEnv>(
 
   const payload: RscPayload = {
     metadata: {
-      pathname: url.pathname,
+      ...payloadLocation(reqCtx, url),
       // routerId exposed for the frontend (current app identity); see
       // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,

package/src/rsc/shell-capture-constants.ts

@@ -67,6 +67,8 @@ export const PPR_REPLAY_BYPASS_REASONS = [
   "no-segment-snapshot",
   "snapshot-miss",
   "explicit-cache-hit",
+  // A rewritten request whose rewrite chose no `.shell()`.
+  "rewritten",
 ] as const;
 
 /** One of {@link PPR_REPLAY_BYPASS_REASONS}. */
@@ -126,6 +128,26 @@ export function partitionShellKey(key: string, partition: string): string {
   return `${key}|${encodeURIComponent(partition)}`;
 }
 
+/**
+ * The shell key of a `rewrite(...).shell("visitor")` request: the visitor's
+ * URL, partitioned by `rw:` + the target's path and search (both searches
+ * filtered and sorted, shellSearchSeed). The visitor's URL keeps two public
+ * URLs of one target apart; the target keeps a conditional rewrite (an A/B
+ * arm, a lock) apart from the URL's own shell. The route's own partition
+ * composes after it.
+ */
+export function visitorShellKey(
+  routerId: string,
+  visitor: URL,
+  target: URL,
+  filter?: SearchParamsFilter,
+): string {
+  return partitionShellKey(
+    buildShellKey(routerId, visitor, filter),
+    `rw:${target.pathname}${shellSearchSeed(target, filter)}`,
+  );
+}
+
 /**
  * The navigation-only entry beside a document shell key (a cold partial
  * request's capture, rsc-rendering.ts). A suffix after the (encoded)
@@ -186,9 +208,10 @@ export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;
  * (ShellCaptureDebugEvent.refusal, `caches.refusal` on a `router.prerender()`
  * result): `identity` (a request-scoped read: cookies(), headers(), the
  * theme, a `{ cache: false }` variable), `dynamic` (`ctx.dynamic()`),
- * `loader` (a `{ ssr: false }` loader rejected, or settled with
- * redirect()/notFound()), `no-record` (no doc record: the route's cache()
- * refused the write, or the handler output failed), `handles` (a pushed
+ * `loader` (a `{ ssr: false }` loader rejected, settled with
+ * redirect()/notFound(), or a promise it pushed rejected),
+ * `no-record` (no doc record: the route's cache() refused the write, or the
+ * handler output failed), `handles` (a pushed
  * handle value did not finish encoding), `size` (over the store's value
  * limit), `record-expired` (the route cache() record the capture wrote ran
  * out first), `invalidated` (a tag of the shell was invalidated after the

package/src/rsc/shell-capture.ts

@@ -508,6 +508,11 @@ function refuse(
   return "refused";
 }
 
+/** A bake-lane loader's promise push, as a refusal names it. */
+function describeLoaderPromisePush(push: LoaderPromisePush): string {
+  return `the promise the loader "${push.loaderId}" pushed to the handle "${push.handleName}"`;
+}
+
 /** The no-shell cause for handler output that missed the capture deadline. */
 const HANDLER_OUTPUT_TIMEOUT_REASON: string =
   "the handler output (a promise it passes or pushes, or an async server " +
@@ -1063,6 +1068,13 @@ export interface ShellCaptureDescriptor {
   debugSink?: (event: ShellCaptureDebugEvent) => void;
   /** Store the snapshot for navigation replay, never the captured HTML prelude. */
   navigationOnly?: true;
+  /**
+   * Set for a shell keyed by the visitor's URL (`rewrite(...).shell("visitor")`,
+   * visitorShellKey): the capture renders the visitor's location
+   * (`RequestContext._shellCaptureForVisitor`) and stores it as
+   * ShellCacheEntry.pathname.
+   */
+  pathname?: string;
   /**
    * lastStoredCaptureSeq(key) when a document request read the store and
    * missed. The request schedules its capture only after rendering the MISS,
@@ -1660,8 +1672,9 @@ export type CaptureRecordOutcome =
  * component showed one value in the prelude and another on every HIT.
  *
  * Order, all bounded by the one capture deadline (`ppr.captureTimeout`):
- * top-level handle promises, the handler pushes' nested promises, and the
- * bake-lane loader containers settle first (the record encodes the handles
+ * top-level handle promises (a bake-lane loader's pushed promises among
+ * them, #1182), the handler pushes' nested promises, and the bake-lane
+ * loader containers settle first (the record encodes the handles
  * a HIT restores, and its handle encode has its own 5s timeout that must
  * never be the one that fires); then the capture's onResponse callbacks fire
  * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
@@ -1704,7 +1717,33 @@ export async function settleCaptureRecord(
   if (!settled.done) {
     if (refuseOnCaptureGuard(capture.key, derivedCtx))
       return { kind: "refused", refusal: guardRefusal(derivedCtx) };
-    return { kind: "timeout", reason: HANDLER_OUTPUT_TIMEOUT_REASON };
+    const pending = derivation.loaderPromisePushes.find(
+      (p) => p.state === "pending",
+    );
+    return {
+      kind: "timeout",
+      reason: pending
+        ? `${describeLoaderPromisePush(pending)} did not settle within ppr.captureTimeout`
+        : HANDLER_OUTPUT_TIMEOUT_REASON,
+    };
+  }
+  // A rejected value must not bake, and the record's encode would fail on
+  // it anyway: refuse before the write starts. A guard trip in that promise
+  // names the read instead.
+  const rejected = derivation.loaderPromisePushes.find(
+    (p) => p.state === "rejected",
+  );
+  if (rejected) {
+    if (refuseOnCaptureGuard(capture.key, derivedCtx))
+      return { kind: "refused", refusal: guardRefusal(derivedCtx) };
+    warnCaptureRefusedOnce(
+      capture.key,
+      `${describeLoaderPromisePush(rejected)} rejected during capture; a ` +
+        "failed value must not bake into the shared shell. Catch it and push " +
+        "a fallback, or push it from a loader without ssr: false.",
+      PPR_LANE_HINT,
+    );
+    return { kind: "refused", refusal: "loader" };
   }
 
   const callbacks = derivedCtx._onResponseCallbacks?.splice(0) ?? [];
@@ -1878,6 +1917,9 @@ async function attemptCapture(
     descriptor.navigationOnly ? { request, url } : undefined,
   );
   const { derivedCtx, freshHandleStore } = derivation;
+  if (descriptor.pathname !== undefined) {
+    derivedCtx._shellCaptureForVisitor = true;
+  }
   // The capture generation starts before matching or any snapshot read
   // (ShellCacheEntry.createdAt): a tag invalidated after it wins.
   const captureStartedAt = Date.now();
@@ -1996,6 +2038,20 @@ export interface CaptureContextDerivation {
    * record encodes its handles, so that encode never races a pending value.
    */
   handlerPushesSettled: () => Promise<void>;
+  /**
+   * Every promise a bake-lane loader body pushed (#1182), in push order.
+   * The record-first step waits for them (they are in the recorded cut) and
+   * names the loader and the handle of one that rejects or misses the
+   * deadline.
+   */
+  loaderPromisePushes: readonly LoaderPromisePush[];
+}
+
+/** A promise a bake-lane loader pushed at capture, owned by that loader. */
+export interface LoaderPromisePush {
+  loaderId: string;
+  handleName: string;
+  state: "pending" | "fulfilled" | "rejected";
 }
 
 /**
@@ -2031,30 +2087,35 @@ export function deriveShellCaptureContext(
   //    masked), their pushes are in the captured HTML (<head> title/meta,
   //    useHandle echoes), and a HIT does not run a promise-free bake-lane
   //    loader (loader-cache.ts), so the stored record carries them: each
-  //    settled, thenable-free push from a loader body keeps that loader as
-  //    `owner` (HandleStore.push), the record stores it
+  //    push from a loader body whose value, once settled, is thenable-free
+  //    keeps that loader as `owner` (HandleStore.push), the record stores it
   //    (CachedEntryData.handleOwners), and a replay that serves the loader
-  //    from its pin restores it through pushRestored (restoreHandles). Those
-  //    copies stand: a promise-carrying bake-lane loader that runs on the
-  //    replay reads the store, so its settled pushes (and those replayed
-  //    inside its body) are dropped and only its thenable ones are added. A
-  //    loader the replay does not serve from a pin is a hole: one the route
-  //    also runs on the live lane, or one whose pin the entry lost. Its run
-  //    replaces its copies (pushPlaceholder, #936), those of the
-  //    dependencies it awaits included (they are credited to it). Nested
-  //    thenables stay masked (the promise shape is the liveness
-  //    declaration, mask-nested.ts). A deferred (thenable) push,
-  //    one with masked nested promises, or one outside a loader body (a
-  //    loader-cache replay names its loader: pushReplayed below) stays
-  //    tagged (HandleStore.push loaderPush) so the
-  //    handle encode cannot stall on a never-resolving mask. A tagged push
-  //    is out of the record (captureHandles) and out of the capture's own
-  //    render (resolvedHandleStream `recordedOnly`, issue #1035): the
-  //    prelude is rendered from what the record keeps, which is what a HIT
-  //    hydrates with. The loader records then carry `runs: 1` so a HIT runs
-  //    those bodies for them, and what they push reaches the client after
+  //    from its pin restores it through pushRestored (restoreHandles). A
+  //    pushed promise (push(promise), .defer()) is judged by its settled
+  //    value, as push(await promise) would be (#1182): the record-first step
+  //    waits for it under the capture deadline, and one that rejects or
+  //    misses the deadline refuses the capture. Those copies stand: a
+  //    promise-carrying bake-lane loader that runs on the replay reads the
+  //    store, so its pushes that settle thenable-free (and those replayed
+  //    inside its body) are dropped and only the ones holding a promise are
+  //    added. A loader the replay does not serve from a pin is a hole: one
+  //    the route also runs on the live lane, or one whose pin the entry
+  //    lost. Its run replaces its copies (pushPlaceholder, #936), those of
+  //    the dependencies it awaits included (they are credited to it). Nested
+  //    thenables stay masked (the promise shape is the liveness declaration,
+  //    mask-nested.ts). A push whose settled value holds a masked nested
+  //    promise, one credited to a live-lane body, or one no body or replay
+  //    names (a loader-cache replay names its loader: pushReplayed below)
+  //    stays tagged (HandleStore.push loaderPush) so the handle encode cannot
+  //    stall on a never-resolving mask. A tagged push is out of the record
+  //    (captureHandles) and out of the capture's own render
+  //    (resolvedHandleStream `recordedOnly`, issue #1035): the prelude is
+  //    rendered from what the record keeps, which is what a HIT hydrates
+  //    with. The loader records then carry `runs: 1` so a HIT runs those
+  //    bodies for them, and what they push reaches the client after
   //    hydration (HandleStore.freezeDocumentSnapshot).
   const handlerPushSettles: Promise<void>[] = [];
+  const loaderPromisePushes: LoaderPromisePush[] = [];
   // A replay (a loader-cache HIT, loader-cache.ts replayLoaderHandles, or a
   // route cache() record's owned values, restoreHandles) re-pushes a loader's
   // recorded values through pushReplayed or pushPlaceholder, which call
@@ -2108,39 +2169,62 @@ export function deriveShellCaptureContext(
       if (report.thenable) maskedNestedThenable = true;
       return masked;
     };
+    // The loader the push is credited to (see the funnel comment above). A
+    // push under a live-lane loader's body, at any depth, is that hole's
+    // output: its live run replaces it on a HIT and a navigation. Otherwise
+    // the first loader around the push that the route registers decides: a
+    // bake-lane one keeps the push under the innermost body, and a
+    // dependency on neither lane is walked past. A replay of a hole's push
+    // is that hole's, unless a live-lane body around it takes it first.
+    const live = liveLaneOwner();
+    const bodyLoaderId = live ?? getCurrentLoaderBodyId() ?? replayOwner;
     let masked: unknown;
-    let loaderPush = true;
     let owner: string | undefined;
-    if (isThenable(value)) {
-      // Deferred (thenable) loader pushes always keep the tag — the
-      // carve-out below is for settled values only. Promise.resolve first: a
-      // loader cache() entry replays a deferred push as the thenable Flight
-      // decoded it to, whose then() returns nothing, and the slot was
-      // `undefined` (the empty element of issue #1035).
-      masked = Promise.resolve(value).then(mask);
-    } else {
+    if (!isThenable(value)) {
       masked = mask(value);
-      if (!maskedNestedThenable) {
-        // A settled, thenable-free push from a loader body is shell
-        // material (see the funnel comment above): only bake-lane loaders
-        // and the loaders they await run at capture, and a HIT does not run
-        // a promise-free bake-lane loader (loader-cache.ts), so the record
-        // keeps the push under the loader that made it. A push under a
-        // live-lane loader's body, at any depth, is that hole's output: it
-        // is credited to the hole, whose live run replaces it on a HIT and
-        // a navigation. The first loader around the push that the route
-        // registers decides: a bake-lane one keeps the push under the
-        // innermost body, and a dependency on neither lane is walked past. A
-        // replay of a hole's push is that hole's, unless a live-lane body
-        // around it takes it first.
-        const bodyLoaderId =
-          liveLaneOwner() ?? getCurrentLoaderBodyId() ?? replayOwner;
-        loaderPush = bodyLoaderId === undefined;
-        if (!loaderPush) owner = bodyLoaderId;
-      }
+      if (!maskedNestedThenable) owner = bodyLoaderId;
+    } else if (live === undefined && bodyLoaderId !== undefined) {
+      // Owned now, judged by its settled value (funnel comment above).
+      // Promise.resolve first: a loader cache() entry replays a deferred
+      // push as the thenable Flight decoded it to, whose then() returns
+      // nothing (issue #1035). The retag runs inside the slot's own then(),
+      // so it lands before the wait on it (settleCaptureRecord) resumes and
+      // the record encodes. The state handler is attached now, which also
+      // marks a rejection as handled.
+      const slot: Promise<unknown> = Promise.resolve(value).then((settled) => {
+        const judged = mask(settled);
+        if (maskedNestedThenable) {
+          freshHandleStore.unrecordPush(handleName, segmentId, slot);
+          derivedCtx._shellCaptureUnrecordedLoaderPush = true;
+        }
+        return judged;
+      });
+      const push: LoaderPromisePush = {
+        loaderId: bodyLoaderId,
+        handleName,
+        state: "pending",
+      };
+      slot.then(
+        () => {
+          push.state = "fulfilled";
+        },
+        () => {
+          push.state = "rejected";
+        },
+      );
+      loaderPromisePushes.push(push);
+      masked = slot;
+      owner = bodyLoaderId;
+    } else {
+      // A hole's promise, or one no body or replay names: tagged. Nothing
+      // awaits the slot at capture, so its rejection is handled here.
+      const tagged = Promise.resolve(value).then(mask);
+      tagged.catch(() => {});
+      masked = tagged;
     }
     // A push the record cannot keep reaches a HIT only from a live run of
     // its loader, so the loader records ask for one (runs: 1).
+    const loaderPush = owner === undefined;
     if (loaderPush) derivedCtx._shellCaptureUnrecordedLoaderPush = true;
     rawCapturePush(handleName, segmentId, masked, loaderPush, owner);
   };
@@ -2261,6 +2345,7 @@ export function deriveShellCaptureContext(
     freshHandleStore,
     handlerPushesSettled: () =>
       Promise.all(handlerPushSettles).then(() => undefined),
+    loaderPromisePushes,
   };
 }
 
@@ -2647,6 +2732,7 @@ async function captureAndStoreShell(
           // default, #971). The serve tail replays it so the resume tree
           // matches the frozen prelude — see ShellCacheEntry.initialTheme.
           initialTheme: payloadInitialTheme(reqCtx),
+          pathname: capture.pathname,
           snapshot,
           prunedRecords: snapshot.length > 0 ? prunedRecords : undefined,
           // The canonical doc segment record's key, published by the doc

package/src/rsc/types.ts

@@ -18,6 +18,11 @@ import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 export interface RscPayload {
   metadata?: {
     pathname: string;
+    /**
+     * Path and search of the URL the route rendered for, when middleware
+     * rewrote the request there (full-payload.ts payloadLocation).
+     */
+    rewriteTarget?: string;
     segments: ResolvedSegment[];
     /** Router instance ID. When this changes between navigations, the client
      *  discards cached segments and does a full tree replacement (app switch). */
@@ -364,15 +369,6 @@ export interface CreateRSCHandlerOptions<
    */
   cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
 
-  /**
-   * Version override for this handler. Same meaning as
-   * `createRouter({ version })`, which it takes precedence over: this exact
-   * value is used for both of the router's versions.
-   *
-   * @default createRouter({ version }), else the router's build versions
-   */
-  version?: string;
-
   /**
    * Nonce provider for Content Security Policy (CSP).
    *