@rangojs/router 0.24.4 → 0.26.0

package/src/server/context.ts

@@ -92,6 +92,12 @@ export type EntryPropCommon = {
   cache?: EntryCacheConfig;
   /** URL prefix from include() scope, used for MountContext on client */
   mountPath?: string;
+  /**
+   * Include scope the entry's handler and loaders resolve `ctx.reverse(".name")`
+   * in. Structural entries only (layout, cache, parallel, wrapping
+   * middleware); a route resolves from its own name. See ReverseScope.
+   */
+  reverseScope?: ReverseScope;
   /** clientUrls() group key (PathOptions.clientGroup); route entries only. */
   clientGroup?: string;
 };
@@ -124,6 +130,11 @@ export type EntryPropRender = {
    * on both DSL evaluations, whatever `ssr` did to `loading`.
    */
   loadingPrefetch?: false;
+  /**
+   * loading(fallback, { ssr: false }), on both DSL evaluations; a document
+   * then sets `loading` to false (applyDocumentModeLoading).
+   */
+  loadingSsr?: false;
   transition?: TransitionConfig;
 };
 
@@ -145,7 +156,8 @@ export type LoaderEntry = {
    * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
    * per-isSSR (router/manifest.ts cache key), so the flag is already
    * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
-   * appears on navigation-lane entries.
+   * appears on navigation-lane entries. Set by documentModeLoader, which
+   * getDocumentModeEntry also applies to a lazy include's captured ancestors.
    */
   awaitBeforeFlush?: true;
   /**
@@ -163,6 +175,13 @@ export type LoaderEntry = {
    * (router/segment-resolution/prefetch-deferral.ts).
    */
   prefetch?: false;
+  /**
+   * The declaring layout's / parallel's / cache()'s include scope, for the
+   * loader body's `ctx.reverse(".name")` (its DSL kickoff carries it,
+   * runInsideLoaderScope). Unset on a route's loaders: they resolve from the
+   * route's name.
+   */
+  reverseScope?: ReverseScope;
 };
 
 /**
@@ -233,7 +252,6 @@ export type InterceptEntry = {
   slotName: `@${string}`; // e.g., "@modal"
   routeName: string; // e.g., "card"
   handler: ReactNode | Handler<any, any, any>;
-  middleware: MiddlewareFn<any, any>[];
   loader: LoaderEntry[];
   loading?: ReactNode | false;
   transition?: TransitionConfig;
@@ -327,10 +345,22 @@ export type EntryData =
       EntryPropSegments &
       EntryPropRender);
 
+/**
+ * Where an include()'s handler runs in the route tree. Hidden include-scope
+ * names (`$prefix_*`) derive from it, never from counter state, so build
+ * discovery and runtime expansion name every include the same (#1104).
+ */
+export interface IncludeScopePosition {
+  /** Sibling indexes of the enclosing includes, "_"-joined ("" at a mount root). */
+  scopePath?: string;
+  /** The scopePath tail since the nearest include that added a name segment. */
+  hiddenScopePath?: string;
+}
+
 /**
  * Tracked include info for build-time manifest generation
  */
-export interface TrackedInclude {
+export interface TrackedInclude extends IncludeScopePosition {
   prefix: string;
   fullPrefix: string;
   namePrefix?: string;
@@ -352,7 +382,7 @@ export type CachedHeaderScope = {
 /**
  * Context stored in AsyncLocalStorage
  */
-interface HelperContext {
+interface HelperContext extends IncludeScopePosition {
   manifest: Map<string, EntryData>;
   namespace: string;
   parent: EntryData | null;
@@ -364,7 +394,8 @@ interface HelperContext {
    *  different routers don't clobber each other (route-map-builder.ts). */
   routerId?: string;
   metrics?: MetricsStore;
-  /** True when rendering for SSR (document requests) */
+  /** True when rendering for SSR (document requests). DSL decisions on it
+   *  go through the document-mode helpers (documentModeLoader). */
   isSSR?: boolean;
   /** URL patterns map for path() routes (route name -> pattern) */
   patterns?: Map<string, string>;
@@ -597,6 +628,8 @@ export const getContext = (): {
           trackedIncludes: store.trackedIncludes,
           cacheProfiles: store.cacheProfiles,
           includeScope: store.includeScope,
+          scopePath: store.scopePath,
+          hiddenScopePath: store.hiddenScopePath,
           // cachedHeaderScope (and insideCacheScope) deliberately NOT copied —
           // the header guard's middleware exemption depends on the latch dying
           // with the funnel scope (see assertCachedHeaderWriteAllowed).
@@ -641,6 +674,8 @@ export const getContext = (): {
           rootScoped: store?.rootScoped,
           trackedIncludes: store?.trackedIncludes,
           cacheProfiles: store?.cacheProfiles,
+          scopePath: store?.scopePath,
+          hiddenScopePath: store?.hiddenScopePath,
         },
         callback,
       );
@@ -763,6 +798,54 @@ export function getRootScoped(): boolean {
   return store?.rootScoped ?? true;
 }
 
+/**
+ * The include scope a segment's dot-local `ctx.reverse(".name")` resolves in.
+ *
+ * One handler ctx serves every segment of a request and is built from the
+ * matched route's name (match-api.ts), so a parent module's layout resolved
+ * `.settings` from the matched CHILD module's prefix first: on
+ * `/acme/web/issues` the account layout's `.settings` hit the project
+ * module's route. Structural entries (layout, cache, parallel, wrapping
+ * middleware) and the loaders they declare capture the scope where the DSL
+ * defined them. Their handler gets a ctx whose `reverse` carries it
+ * (withReverseScope, router/handler-context.ts), and their loaders' DSL
+ * kickoff carries it in the loader scope (runInsideLoaderScope) for the
+ * loader ctx the executor builds. Global names and mount-param autofill do
+ * not change.
+ */
+export interface ReverseScope {
+  /** Include name prefix ("account.project"); undefined outside named includes. */
+  readonly prefix: string | undefined;
+  /** getRootScoped() where the segment was defined: bare-name fallback allowed. */
+  readonly rootScoped: boolean;
+}
+
+/** The ReverseScope of the DSL position being evaluated. */
+export function getReverseScope(): ReverseScope {
+  return { prefix: getNamePrefix(), rootScoped: getRootScoped() };
+}
+
+/**
+ * A createReverseFunction result (router/handler-context.ts). The internal
+ * 4th argument resolves dot names in a segment's ReverseScope instead of the
+ * route's name.
+ */
+export type ScopableReverse = (
+  name: string,
+  hrefParams?: Record<string, string>,
+  search?: Record<string, unknown>,
+  segmentScope?: ReverseScope,
+) => string;
+
+/** `reverse` with dot names resolved in `scope`, if any. */
+export function scopeReverse(
+  reverse: ScopableReverse,
+  scope: ReverseScope | undefined,
+): ScopableReverse {
+  if (scope === undefined) return reverse;
+  return (name, hrefParams, search) => reverse(name, hrefParams, search, scope);
+}
+
 /**
  * Stamp build-time scope identity onto a Static() definition at mount time.
  * The bake collector (prerender-collection.ts) renders defs OUTSIDE any
@@ -817,6 +900,61 @@ export function getIsolatedLazyParent(
   };
 }
 
+/*
+ * The DSL's document-only decisions. A document (isSSR) evaluation applies
+ * them in dsl-helpers.ts; getDocumentModeEntry applies the same ones to a
+ * chain built without isSSR. A new ctx.isSSR decision gets a helper here,
+ * called from both.
+ */
+
+/** loader(Def, { ssr: false }): a document awaits it before the first flush. */
+export function documentModeLoader(entry: LoaderEntry): LoaderEntry {
+  return entry.bake ? { ...entry, awaitBeforeFlush: true } : entry;
+}
+
+/** loading(fallback, { ssr: false }): a document renders no fallback. */
+export function applyDocumentModeLoading(entry: EntryPropRender): void {
+  if (entry.loadingSsr === false) entry.loading = false;
+}
+
+const documentModeEntries = new WeakMap<EntryData, EntryData>();
+
+/**
+ * `entry`, its ancestors, orphan layouts and parallels as a document (isSSR)
+ * DSL evaluation builds them, from an evaluation without isSSR.
+ *
+ * include() captures its parent chain on router.ts routes() or
+ * lazy-includes.ts runExpansion, neither of which has isSSR, and loadManifest
+ * reuses it for every request. Handed to a document as is, every ancestor
+ * outside the include kept its navigation-mode decisions (#1179). Intercepts
+ * stay as they are: a document never resolves one.
+ *
+ * Memoized per entry, so an ancestor several includes share maps to one copy.
+ */
+export function getDocumentModeEntry(entry: EntryData): EntryData {
+  const known = documentModeEntries.get(entry);
+  if (known) return known;
+  const copy = { ...entry };
+  documentModeEntries.set(entry, copy);
+  documentModeEntries.set(copy, copy);
+  copy.loader = entry.loader.map(documentModeLoader);
+  applyDocumentModeLoading(copy);
+  copy.layout = entry.layout.map(getDocumentModeEntry);
+  const parallel: ParallelEntries = {};
+  for (const slot of Object.keys(entry.parallel) as `@${string}`[]) {
+    const slotEntry = entry.parallel[slot];
+    if (slotEntry) {
+      parallel[slot] = getDocumentModeEntry(slotEntry) as ParallelEntryData;
+    }
+  }
+  copy.parallel = parallel;
+  if (entry.parent) copy.parent = getDocumentModeEntry(entry.parent);
+  if (entry.orphanOwner) {
+    copy.orphanOwner = getDocumentModeEntry(entry.orphanOwner);
+  }
+  return copy;
+}
+
 export function getParallelEntries(
   parallels: ParallelEntries | EntryData[] | undefined,
 ): ParallelEntryData[] {
@@ -909,6 +1047,8 @@ interface LoaderScope {
   active: true;
   /** $$id of the DSL loader this scope resolves (runInsideLoaderScope). */
   loaderId?: string;
+  /** The declaring entry's ReverseScope (LoaderEntry.reverseScope). */
+  reverseScope?: ReverseScope;
 }
 const loaderScopeALS: AsyncLocalStorage<LoaderScope> = ((globalThis as any)[
   LOADER_SCOPE_KEY
@@ -1472,8 +1612,21 @@ export function assertCachedHeaderWriteAllowed(
  * are bypassed because loaders are always fresh (never cached) and
  * their side effects (setCookie, header, etc.) are safe.
  */
-export function runInsideLoaderScope<T>(fn: () => T, loaderId?: string): T {
-  return loaderScopeALS.run({ active: true, loaderId }, fn);
+export function runInsideLoaderScope<T>(
+  fn: () => T,
+  loaderId?: string,
+  reverseScope?: ReverseScope,
+): T {
+  return loaderScopeALS.run({ active: true, loaderId, reverseScope }, fn);
+}
+
+/**
+ * The ReverseScope of the DSL loader kickoff around this call: a loader the
+ * kickoff starts, and one its body starts with ctx.use(), resolve dot names
+ * in it. A handler's ctx.use(Loader) runs outside any kickoff: none.
+ */
+export function getLoaderReverseScope(): ReverseScope | undefined {
+  return loaderScopeALS.getStore()?.reverseScope;
 }
 
 /**

package/src/server/handle-store.ts

@@ -4,6 +4,7 @@ import {
   isInsideLoaderScope,
 } from "./context.js";
 import { holdsThenable } from "../router/segment-resolution/mask-nested.js";
+import { isThenable } from "../handles/is-thenable.js";
 import { pushedByKey } from "../handles/pushed-by.js";
 import { defineSlot } from "./slot-accessors.js";
 
@@ -47,8 +48,9 @@ function createLateHandlePushError(
 ): Error {
   const error = new Error(
     `Handle "${handleName}" for segment "${segmentId}" was pushed after handle collection completed. ` +
-      `This usually means an async JSX subtree suspended and later tried to push a handle during streaming. ` +
-      `Push handles from the route/layout handler or during the initial synchronous JSX render instead.`,
+      `This usually means an async component pushed it after an await. ` +
+      `Push from the route or layout handler, or reserve the slot there with ` +
+      `ctx.use(Handle).defer() and resolve it from the component.`,
   );
   error.name = "LateHandlePushError";
   return error;
@@ -253,12 +255,14 @@ export interface HandleStore {
   ): void;
 
   /**
-   * push() a record's copy of `loaderId`'s settled push that stands
-   * (restoreHandles): the record supplies the loader's value too. From then
-   * on this request drops every settled, thenable-free push the loader makes
-   * (live, or replayed from a cache entry, anywhere inside its body), and
-   * keeps the ones holding a thenable (holdsThenable: what the record could
-   * not keep), placed among the restored copies in the loader's push order.
+   * push() a record's copy of `loaderId`'s push that stands (restoreHandles):
+   * the record supplies the loader's value too. From then on this request
+   * drops every thenable-free push the loader makes (live, or replayed from
+   * a cache entry, anywhere inside its body), and keeps the ones holding a
+   * thenable (holdsThenable: what the record could not keep), placed among
+   * the restored copies in the loader's push order. A top-level promise is
+   * judged by its settled value, as the capture judged it (#1182): dropped
+   * when it settles thenable-free or rejects, else kept once it settles.
    */
   pushRestored(
     handleName: string,
@@ -277,6 +281,16 @@ export interface HandleStore {
    */
   setRecordAuthority(authority: (loaderId: string) => RecordAuthority): void;
 
+  /**
+   * Capture only (shell-capture.ts deriveShellCaptureContext): the slot
+   * holding `value` becomes a DSL-loader push without an owner, so the
+   * record and the prelude leave it out (getDataForSegment's
+   * `excludeLoaderPushes`). The capture owns a bake-lane loader's promise
+   * when it is pushed, and calls this once the promise settled to a value
+   * that holds one (#1182).
+   */
+  unrecordPush(handleName: string, segmentId: string, value: unknown): void;
+
   /**
    * `loaderId`'s run in this request settled (resolved or rejected), its
    * pushes made (loader-resolution.ts createLoaderExecutor). Its placeholders
@@ -665,6 +679,39 @@ export function createHandleStore(): HandleStore {
     return after;
   }
 
+  // A restored loader's top-level promise push, judged by its settled value
+  // as push(await value) would be: thenable-free, the record's copy stands
+  // (the capture recorded that value, #1182); holding a promise, it is kept
+  // where the loader's pushes go, once it settles; rejected, it is dropped.
+  // Tracked on the auxiliary lane, so the late channel stays open for it.
+  function judgeRestoredPromise(
+    store: HandleStore,
+    handleName: string,
+    segmentId: string,
+    value: unknown,
+    loaderId: string,
+    tag: SlotTag,
+  ): void {
+    const judged = Promise.resolve(value).then(
+      (settled) => {
+        if (!holdsThenable(settled)) {
+          const existing = data[handleName]?.[segmentId];
+          if (existing) matchRestoredSlot(existing, loaderId);
+          return;
+        }
+        const values = ((data[handleName] ??= {})[segmentId] ??= []);
+        insertSlot(values, restoredInsertIndex(values, loaderId), value, tag);
+        if (tag.replayOf !== undefined) {
+          addPending(pendingReplays, tag.replayOf, values);
+        }
+        version++;
+        signalEmission();
+      },
+      () => {},
+    );
+    store.trackAuxiliary(judged);
+  }
+
   function replayPush(
     store: HandleStore,
     replay: NonNullable<typeof replaying>,
@@ -859,10 +906,22 @@ export function createHandleStore(): HandleStore {
           restoredBy = restoringLoader(replayOf);
         }
       }
-      if (restoredBy !== undefined && !holdsThenable(value)) {
-        const existing = data[handleName]?.[segmentId];
-        if (existing) matchRestoredSlot(existing, restoredBy);
-        return;
+      if (restoredBy !== undefined) {
+        if (isThenable(value)) {
+          judgeRestoredPromise(this, handleName, segmentId, value, restoredBy, {
+            loader: (loaderPush ?? isInsideLoaderScope()) || undefined,
+            replayOf,
+            liveOf: replayOf === undefined ? restoredBy : undefined,
+            owner,
+            by: getHandlePushOwner() ?? replayOf ?? owner,
+          });
+          return;
+        }
+        if (!holdsThenable(value)) {
+          const existing = data[handleName]?.[segmentId];
+          if (existing) matchRestoredSlot(existing, restoredBy);
+          return;
+        }
       }
 
       if (!data[handleName]) {
@@ -976,6 +1035,15 @@ export function createHandleStore(): HandleStore {
       authority = of;
     },
 
+    unrecordPush(handleName: string, segmentId: string, value: unknown): void {
+      const values = data[handleName]?.[segmentId];
+      if (!values) return;
+      const i = values.indexOf(value);
+      if (i < 0) return;
+      const tags = tagsFor(values);
+      tags[i] = { ...tags[i], loader: true, owner: undefined };
+    },
+
     settleLoaderRun(loaderId: string): void {
       if (completed) return;
       const hole = isHole(loaderId);

package/src/server/request-context.ts

@@ -23,7 +23,7 @@ import {
   serializeStateCookie,
 } from "../browser/cookie-name.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { AutofillAwareReverseFunction } from "../types/handler-context.js";
 import type {
   DefaultEnv,
   DefaultReverseRouteMap,
@@ -65,6 +65,8 @@ import {
 } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RoutineTrace } from "../rsc/routine-plan.js";
+import type { ActionContinuation } from "../rsc/server-action.js";
+import type { FormActionOutcome } from "../rsc/progressive-enhancement.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import {
   assertCachedHeaderWriteAllowed,
@@ -345,6 +347,13 @@ export interface RequestContext<
    */
   _shellCaptureRun?: boolean;
 
+  /**
+   * @internal Set beside `_shellCaptureRun` when the shell is keyed by the
+   * visitor's URL (`rewrite(...).shell("visitor")`): the capture renders the
+   * visitor's location and `ctx.rewrittenFrom`; the theme stays the default.
+   */
+  _shellCaptureForVisitor?: boolean;
+
   /**
    * @internal Bake-lane loader containers collected DURING a shell capture:
    * segment-key -> the loader's (pre-wrap) result promise. Populated by
@@ -359,9 +368,10 @@ export interface RequestContext<
 
   /**
    * @internal Set on a capture's derived context when a loader pushed a
-   * value the record cannot keep (a deferred push, masked nested promises,
-   * or a push outside a loader body): the loader records then carry
-   * `runs: 1`, so a HIT still runs their bodies for those pushes.
+   * value the record cannot keep (masked nested promises, a pushed promise
+   * that settled to one, a live-lane loader's push, or a push outside a
+   * loader body): the loader records then carry `runs: 1`, so a HIT still
+   * runs their bodies for those pushes.
    */
   _shellCaptureUnrecordedLoaderPush?: true;
 
@@ -774,8 +784,15 @@ export interface RequestContext<
    * Generate URLs from route names.
    * Uses the global route map. After route matching, scoped (`.name`) resolution
    * works within the matched include() scope.
-   */
-  reverse: ScopedReverseFunction<
+   *
+   * Params are optional in the type because the fill depends on the phase.
+   * After the route match (route middleware, handlers, loaders, server actions)
+   * missing params come from the matched route's params; explicit params win.
+   * In global middleware before `next()` nothing is matched and the fill is
+   * empty, so a route with a required param throws `Missing param "<name>" for
+   * route "<route>"` at runtime (a param-less route still resolves).
+   */
+  reverse: AutofillAwareReverseFunction<
     Record<string, string>,
     DefaultReverseRouteMap
   >;
@@ -786,6 +803,13 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
+  /**
+   * @internal Leaving a rewritten page, the visitor's URL moved
+   * (router/match-api.ts): the default revalidation counts it as a search
+   * change, since the render may read `ctx.rewrittenFrom`.
+   */
+  _visitorMoved?: boolean;
+
   /**
    * @internal True while the post-action revalidation render is running (set by
    * revalidateAfterAction). The "use cache" runtime reads this to prefer
@@ -796,6 +820,19 @@ export interface RequestContext<
    */
   _inActionRevalidation?: boolean;
 
+  /**
+   * @internal The outcome of the action this request ran (a JS server
+   * action's continuation, a no-JS form post's form state), set before route
+   * middleware wraps the re-render. While it is unset, applyRewrite
+   * (rsc/rewrite-passes.ts) moves a mutation with its body, so the action
+   * runs on the target's pass, or refuses it (`disallowMutations()`, or a
+   * body middleware read); once set, the request moves to the target, whose
+   * pass re-renders from it instead of running the action again (#1145).
+   */
+  _actionRan?:
+    | { kind: "action"; continuation: ActionContinuation }
+    | { kind: "form"; outcome: FormActionOutcome };
+
   /**
    * @internal Render barrier for experimental `rendered()` API.
    * Resolves when all non-loader segments have settled and handle data
@@ -1017,6 +1054,7 @@ export type PublicRequestContext<
   | "_onDemandProducer"
   | "_searchParamsFilter"
   | "_shellCaptureRun"
+  | "_shellCaptureForVisitor"
   | "_shellImplicitCache"
   | "_shellLoaderSeed"
   | "_shellCaptureLoaderRecords"
@@ -1048,7 +1086,9 @@ export type PublicRequestContext<
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
+  | "_visitorMoved"
   | "_inActionRevalidation"
+  | "_actionRan"
   | "_reportedErrors"
   | "_renderErrors"
   | "_recoveredHandlerErrors"

package/src/server/request-headers.ts

@@ -45,6 +45,38 @@ export function requestHeaders(request: Request): Headers {
   return RAW_HEADERS.get(request) ?? request.headers;
 }
 
+/**
+ * A copy of `request`'s headers for a bodyless mirror of it (the PE
+ * re-render, route middleware around it, a rewrite pass after an action),
+ * without the body-framing ones and `content-type`, so a body check gated on
+ * the content-type passes over a request that has no body.
+ */
+export function bodylessHeaders(request: Request): Headers {
+  const headers = new Headers(requestHeaders(request));
+  headers.delete("content-length");
+  headers.delete("content-encoding");
+  headers.delete("transfer-encoding");
+  headers.delete("content-type");
+  return headers;
+}
+
+/**
+ * A bodyless mirror of `request` at `url`: `method`, its
+ * {@link bodylessHeaders}, the signal and workerd's `cf`.
+ */
+export function bodylessRequest(
+  url: string | URL,
+  request: Request,
+  method: string,
+): Request {
+  return new Request(url, {
+    method,
+    headers: bodylessHeaders(request),
+    signal: request.signal,
+    cf: (request as { cf?: unknown }).cf,
+  } as RequestInit);
+}
+
 /**
  * Shadow `request.headers` with an own, non-enumerable getter that calls
  * `beforeRead` and returns the request's own Headers (stable per request, so

package/src/server/rewrite-trail.ts

@@ -11,8 +11,15 @@
 import { contextGet, contextSet, createVar } from "../context-var.js";
 import { RewriteLoopError } from "../errors.js";
 import { documentCacheStoresRender } from "../cache/document-cache-policy.js";
-import { guardIdentityRead, type IdentityReadWording } from "./context.js";
+import {
+  guardIdentityRead,
+  recordLoaderIdentityRead,
+  refuseInCacheScope,
+  type IdentityReadWording,
+} from "./context.js";
+import { isInsideIdentityExempt } from "../cache/cache-exec-scope.js";
 import { stripInternalParams } from "../router/internal-params.js";
+import type { RewriteShell } from "../route-definition/rewrite.js";
 import type { RequestContext } from "./request-context.js";
 
 /** Most rewrites one request may take; the next one is a RewriteLoopError. */
@@ -23,7 +30,8 @@ const REWRITE_TRAIL = createVar<readonly string[]>();
 
 type TrailContext = Pick<RequestContext<any>, "_variables">;
 
-function pathKey(url: URL): string {
+/** A URL's path and search: what a rewrite hop, a target and a visitor's move compare. */
+export function pathKey(url: URL): string {
   return url.pathname + url.search;
 }
 
@@ -60,6 +68,25 @@ export function recordRewriteHop(
   return hops;
 }
 
+/** The `.shell()` choice of the hop that reached the route that renders. */
+const REWRITE_SHELL = createVar<RewriteShell | undefined>();
+
+export function recordRewriteShell(
+  reqCtx: TrailContext,
+  audience: RewriteShell | undefined,
+): void {
+  contextSet(reqCtx._variables, REWRITE_SHELL, audience);
+}
+
+/** The last hop's `rewrite(...).shell()` choice; undefined: none. */
+export function rewriteShellAudience(
+  reqCtx: TrailContext | undefined,
+): RewriteShell | undefined {
+  return reqCtx?._variables
+    ? (contextGet(reqCtx._variables, REWRITE_SHELL) as RewriteShell | undefined)
+    : undefined;
+}
+
 type AudienceContext = Pick<
   RequestContext<any>,
   "_shellCaptureRun" | "_documentCacheRender" | "res"
@@ -68,7 +95,8 @@ type AudienceContext = Pick<
 /**
  * A render other visitors may be served: a PPR shell capture, or a render
  * the document cache stores (its response opted in before next()). It shows
- * what a direct visit to its URL shows: no visitor theme, no visitor URL.
+ * no visitor theme, and no visitor URL unless it is a visitor-keyed shell
+ * capture (`_shellCaptureForVisitor`).
  */
 export function rendersForSharedAudience(reqCtx: AudienceContext): boolean {
   return reqCtx._shellCaptureRun === true || documentCacheStoresRender(reqCtx);
@@ -112,9 +140,9 @@ export type RewrittenFromReader = "render" | "middleware";
  * The read behind every `ctx.rewrittenFrom`. Guarded like cookies(): inside
  * a `cache()` boundary or a `"use cache"` function it throws, and a loader's
  * own `cache()` fill records it. A render other visitors may be served sees
- * `undefined`, as on a direct visit; any other render that sees the visitor's
- * URL marks `_payloadVisitorLocation`, so the document cache does not store
- * it.
+ * `undefined`, as on a direct visit, except a visitor-keyed shell capture,
+ * whose key covers the URL; any other render that sees the visitor's URL
+ * marks `_payloadVisitorLocation`, so the document cache does not store it.
  */
 function readRewrittenFrom(
   reqCtx: RequestContext<any> | undefined,
@@ -122,7 +150,15 @@ function readRewrittenFrom(
 ): string | undefined {
   if (!reqCtx) return undefined;
   if (reader === "render" && rendersForSharedAudience(reqCtx)) {
-    return undefined;
+    if (!reqCtx._shellCaptureForVisitor) return undefined;
+    // guardIdentityRead minus the capture guard: a cache() boundary, a "use
+    // cache" body or a loader's own cache() inside the capture is keyed
+    // without the URL.
+    if (!isInsideIdentityExempt()) {
+      refuseInCacheScope("ctx.rewrittenFrom", REWRITTEN_FROM_READ, reqCtx);
+      recordLoaderIdentityRead("ctx.rewrittenFrom", REWRITTEN_FROM_READ.verb);
+    }
+    return rewriteTrail(reqCtx)?.[0];
   }
   guardIdentityRead(reqCtx, "ctx.rewrittenFrom", REWRITTEN_FROM_READ);
   const href = rewriteTrail(reqCtx)?.[0];
@@ -145,15 +181,25 @@ function copyFor(holder: object, href: string | undefined): URL | undefined {
   return copy;
 }
 
+/**
+ * The ctx defineRewrittenFrom ran on: `holder`, or the one it derives from
+ * (a layout's ctx is an Object.create child of the route's, withReverseScope).
+ */
+function definedOn(holder: object): object {
+  while (!SOURCES.has(holder)) holder = Object.getPrototypeOf(holder);
+  return holder;
+}
+
 /**
  * Non-enumerable, like `ctx.theme`: serializing a ctx (React's dev debug
  * info) must not count as a read.
  */
 const SCOPED_DESCRIPTOR: PropertyDescriptor = {
   get(this: object): URL | undefined {
+    const owner = definedOn(this);
     const href = readRewrittenFrom(
-      SOURCES.get(this),
-      READERS.get(this) ?? "render",
+      SOURCES.get(owner),
+      READERS.get(owner) ?? "render",
     );
     return copyFor(this, href);
   },