@rangojs/router 0.24.4 → 0.26.0

package/src/router/middleware.ts

@@ -34,11 +34,7 @@ import { assertNonCacheableReadAllowed } from "../server/context.js";
 import { readGuardedTheme } from "../server/cookie-store.js";
 import { defineSlot, slotAccessor } from "../server/slot-accessors.js";
 import type { Theme } from "../theme/types.js";
-import {
-  isRewrite,
-  rewriteNotSupported,
-  type Rewrite,
-} from "../route-definition/rewrite.js";
+import { isRewrite, type Rewrite } from "../route-definition/rewrite.js";
 import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 
 // Re-export types consumed through this module's path.
@@ -324,8 +320,8 @@ export function createMiddlewareContext<TEnv>(
     waitUntil: reqCtx ? reqCtx.waitUntil.bind(reqCtx) : fireAndForgetWaitUntil,
 
     get: ((keyOrVar: any) => {
-      // "use cache" only: intercept middleware runs inside a cache()
-      // subtree's render scope, and a middleware read is never cached there.
+      // "use cache" only: middleware runs before any cache() subtree
+      // renders, so the cache() read guard never applies to it.
       if (
         isNonCacheable(variables, keyOrVar) &&
         getCacheExecScope() !== undefined
@@ -517,13 +513,11 @@ function mergeReqCtxStub(
 // Clone `base` with stub headers merged into a fresh Headers (the clone keeps
 // the body mutable for post-next() modifications). Set-Cookie is always
 // appended; other headers obey stubOverridesNonCookie (see mergeStubHeaders).
-// mergeReqCtx folds in RequestContext stub cookies/headers; the intercept
-// short-circuit path passes false (its reqCtx headers are not merged here),
-// which is the one deliberate divergence between the call sites.
+// RequestContext stub cookies/headers are folded in last.
 function mergeResponse(
   base: Response,
   stub: Headers,
-  opts: { stubOverridesNonCookie: boolean; mergeReqCtx: boolean },
+  opts: { stubOverridesNonCookie: boolean },
 ): Response {
   const mergedHeaders = new Headers(base.headers);
   // The reserved external-redirect marker is never a trust signal and must never
@@ -532,9 +526,7 @@ function mergeResponse(
   // guard would not touch) to the client. The opt-in is the out-of-band brand.
   mergedHeaders.delete(EXTERNAL_REDIRECT_MARKER);
   mergeStubHeaders(mergedHeaders, stub, opts.stubOverridesNonCookie);
-  if (opts.mergeReqCtx) {
-    mergeReqCtxStub(mergedHeaders, _getRequestContext());
-  }
+  mergeReqCtxStub(mergedHeaders, _getRequestContext());
   const merged = new Response(base.body, {
     status: base.status,
     statusText: base.statusText,
@@ -597,7 +589,6 @@ export async function executeMiddleware<TEnv>(
       // and reqCtx stub headers are merged in.
       responseHolder.response = mergeResponse(response, stubResponse.headers, {
         stubOverridesNonCookie: true,
-        mergeReqCtx: true,
       });
 
       return responseHolder.response;
@@ -740,7 +731,6 @@ export async function executeMiddleware<TEnv>(
       // (stubOverridesNonCookie=false); reqCtx stub headers still merge in.
       const merged = mergeResponse(result, stubResponse.headers, {
         stubOverridesNonCookie: false,
-        mergeReqCtx: true,
       });
       responseHolder.response = merged;
       return merged;
@@ -796,137 +786,6 @@ export async function executeMiddleware<TEnv>(
   return finalResponse;
 }
 
-/**
- * Execute middleware for intercepts (simplified execution)
- *
- * Intercepts use a shared stubResponse from the request context. This function:
- * - Runs middleware in sequence with a simple next() chain
- * - Returns Response if any middleware short-circuits (returns OR throws a Response, or redirects, BEFORE next())
- * - Returns null if all middleware calls next() - headers set after next() remain on stubResponse
- *
- * @param middlewares - Array of middleware functions
- * @param request - Original request
- * @param env - Environment bindings
- * @param params - Route params
- * @param variables - Shared variables object
- * @param stubResponse - Response from request context for collecting headers/cookies
- */
-export async function executeInterceptMiddleware<TEnv>(
-  middlewares: MiddlewareFn<TEnv>[],
-  request: Request,
-  env: TEnv,
-  params: Record<string, string>,
-  variables: Record<string, any>,
-  stubResponse: Response,
-  reverse?: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string,
-): Promise<Response | null> {
-  if (middlewares.length === 0) {
-    return null;
-  }
-
-  let index = 0;
-  let earlyResponse: Response | null = null;
-
-  // Use provided stubResponse - headers/cookies set here will be merged by the caller
-  const responseHolder: ResponseHolder = { response: stubResponse };
-
-  const next = async (): Promise<Response> => {
-    if (index >= middlewares.length || earlyResponse) {
-      return stubResponse;
-    }
-
-    const ordinal = index;
-    const middleware = middlewares[index++];
-    const ctx = createMiddlewareContext(
-      request,
-      env,
-      params,
-      variables,
-      responseHolder,
-      reverse,
-    );
-
-    let nextCalled = false;
-    const guardedNext = (): Promise<Response> => {
-      if (nextCalled) {
-        throw new Error(
-          `[@rangojs/router] Intercept middleware called next() more than once.`,
-        );
-      }
-      nextCalled = true;
-      return next();
-    };
-
-    // Span-wrap each intercept middleware as rango.middleware (metric:false —
-    // intercept runs inside the render phase already metered by render:total, so
-    // it contributes a span but no separate perf metric). Bare MiddlewareFns
-    // have no pattern, so the label is scoped to "*" like a pattern-less entry.
-    const label = getMiddlewareMetricLabel(
-      { handler: middleware, pattern: null } as MiddlewareEntry<TEnv>,
-      ordinal,
-    );
-
-    const result: Response | void = await observePhase(
-      PHASES.middleware(label),
-      async () => {
-        try {
-          return await middleware(ctx, guardedNext);
-        } catch (error) {
-          // Thrown Response is short-circuit control flow, parity with the
-          // explicit-return path below. Absorb it INSIDE the span so the tracing
-          // runner settles rango.middleware as success, not STATUS_ERROR (same
-          // reasoning as executeMiddleware's main chain). Real errors propagate.
-          if (error instanceof Response) return error;
-          if (isRewrite(error)) throw rewriteNotSupported(error, "intercept");
-          throw error;
-        }
-      },
-    );
-    if (isRewrite(result)) throw returnedRewriteError(middleware);
-
-    if (result instanceof Response) {
-      earlyResponse = result;
-      return result;
-    }
-
-    return stubResponse;
-  };
-
-  await next();
-
-  // Return early response if middleware short-circuited (returned Response BEFORE next())
-  if (earlyResponse) {
-    // Capture in const for TypeScript narrowing (earlyResponse is `let` which loses narrowing in callbacks)
-    const response: Response = earlyResponse;
-
-    // Merge any headers/cookies set on stub into the early response
-    let hasStubHeaders = false;
-    stubResponse.headers.forEach(() => {
-      hasStubHeaders = true;
-    });
-
-    if (hasStubHeaders) {
-      // Only fill in missing headers — the returned Response's explicit headers
-      // take precedence (stubOverridesNonCookie=false), matching executeMiddleware.
-      // mergeReqCtx=false: the intercept path deliberately does NOT merge reqCtx
-      // stub headers here (pinned by intercept-middleware-headers.test.ts).
-      return mergeResponse(response, stubResponse.headers, {
-        stubOverridesNonCookie: false,
-        mergeReqCtx: false,
-      });
-    }
-    return response;
-  }
-
-  // All middleware completed without short-circuit
-  // Headers/cookies set on stubResponse will be merged into the final response by the caller
-  return null;
-}
-
 /**
  * Execute middleware chain for loaders (simpler signature)
  *

package/src/router/navigation-snapshot.ts

@@ -4,6 +4,8 @@ import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface NavigationSnapshot {
   prevUrl: URL;
+  /** The visitor's URL of the page left, when `prevUrl` is its rewrite target. */
+  prevVisitorUrl: URL | null;
   prevParams: Record<string, string>;
   prevMatch: RouteMatchResult | null;
 
@@ -95,6 +97,35 @@ export function getInterceptSourceHeader(request: Request): string | null {
   return requestHeaders(request).get("X-RSC-Router-Intercept-Source");
 }
 
+/**
+ * The URL the page left rendered, when middleware rewrote it there (#1144):
+ * `_rsc_rt`, the payload's `rewriteTarget` the browser sends back while
+ * `X-RSC-Router-Client-Path` names the visitor's URL. Matching the visitor's
+ * URL would find the rewriting route. Same origin only. It names the page
+ * left, never what renders, so a forged value runs or skips no middleware.
+ */
+function getShownRouteUrl(url: URL): URL | null {
+  const shown = url.searchParams.get("_rsc_rt");
+  if (!shown) return null;
+  try {
+    const parsed = new URL(shown, url.origin);
+    return parsed.origin === url.origin ? formSearch(parsed) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `url` with its query as URLSearchParams writes it, as the request's own URL
+ * has it: setting and stripping `_rsc*` params rewrote that one (`?q=a%2Cb`),
+ * while a URL the browser names keeps the address bar's (`?q=a,b`). Compared
+ * as sent, every navigation from such a page was a search change.
+ */
+function formSearch(url: URL): URL {
+  url.search = String(url.searchParams);
+  return url;
+}
+
 export async function resolveNavigation(
   request: Request,
   url: URL,
@@ -112,12 +143,15 @@ export async function resolveNavigation(
     return null;
   }
 
-  let prevUrl: URL;
+  let visitor: URL;
   try {
-    prevUrl = new URL(previousUrl, url.origin);
+    visitor = formSearch(new URL(previousUrl, url.origin));
   } catch {
     return null;
   }
+  // An intercept's request diffs from its source, which _rsc_rt does not name.
+  const shown = interceptSourceUrl ? null : getShownRouteUrl(url);
+  const prevUrl = shown ?? visitor;
 
   let interceptContextUrl: URL;
   try {
@@ -154,6 +188,7 @@ export async function resolveNavigation(
 
   return {
     prevUrl,
+    prevVisitorUrl: shown && visitor,
     prevParams,
     prevMatch,
     interceptContextUrl,
@@ -176,6 +211,7 @@ export function createNavigationSnapshot(
   const defaultUrl = new URL("http://localhost/");
   return {
     prevUrl: defaultUrl,
+    prevVisitorUrl: null,
     prevParams: {},
     prevMatch: null,
     interceptContextUrl: defaultUrl,

package/src/router/prefetch-cache-ttl.ts

@@ -1,15 +1,14 @@
 /**
- * Resolve the prefetch cache TTL once, at router init, into the three derived
- * values the rest of the router consumes: seconds (for the Cache-Control
- * max-age), milliseconds (for the client-side in-memory cache), and the
- * Cache-Control header string (or false when caching is disabled).
+ * Resolve the prefetch cache TTL once, at router init, into the values the
+ * rest of the router consumes: seconds, and milliseconds for the client-side
+ * in-memory prefetch cache (shipped in payload metadata). Prefetch responses
+ * carry no Cache-Control: the browser HTTP cache would keep a prefetch whose
+ * render failed after its 200 went out (#1170).
  *
  * `false` disables prefetch caching (seconds 0). A non-finite input
  * (NaN/Infinity, e.g. from an env-derived number that failed to parse) is
- * treated as the default rather than producing a malformed
- * `Cache-Control: max-age=NaN` header; CDNs/browsers ignore such a directive,
- * which would silently disable caching on EVERY prefetch response. Negative
- * finite values clamp to 0 (disabled).
+ * treated as the default rather than disabling the cache. Negative finite
+ * values clamp to 0 (disabled).
  *
  * Policy note: this is the prefetch-TTL policy specifically. Other finite-number
  * guards in the codebase deliberately differ — defer.ts treats Infinity as an
@@ -17,12 +16,10 @@
  * at config time. They are NOT the same guard, so don't unify them.
  */
 export interface ResolvedPrefetchCacheTTL {
-  /** TTL in seconds for the Cache-Control max-age directive. */
+  /** TTL in seconds. */
   seconds: number;
   /** TTL in milliseconds for the client-side in-memory prefetch cache. */
   ms: number;
-  /** Cache-Control header value, or false when caching is disabled. */
-  cacheControl: string | false;
 }
 
 const DEFAULT_PREFETCH_CACHE_TTL_SECONDS = 300;
@@ -38,14 +35,9 @@ export function resolvePrefetchCacheTTL(
   } else if (typeof rawTTL === "number" && Number.isFinite(rawTTL)) {
     seconds = Math.max(0, Math.floor(rawTTL));
   } else {
-    // Non-finite (NaN/Infinity): fall back to the default rather than emit a
-    // malformed max-age=NaN/Infinity that CDNs and browsers reject.
+    // Non-finite (NaN/Infinity): fall back to the default.
     seconds = DEFAULT_PREFETCH_CACHE_TTL_SECONDS;
   }
 
-  return {
-    seconds,
-    ms: seconds * 1000,
-    cacheControl: seconds === 0 ? false : `private, max-age=${seconds}`,
-  };
+  return { seconds, ms: seconds * 1000 };
 }

package/src/router/prerender-match.ts

@@ -16,6 +16,7 @@ import { detectPrerenderPassthrough } from "../prerender.js";
 import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { findInOrphans } from "./error-handling.js";
+import { interceptSlotId } from "./intercept-resolution.js";
 import { loadManifest } from "./manifest.js";
 import { traverseBack } from "./pattern-matching.js";
 import type { RouterContext } from "./router-context.js";
@@ -487,7 +488,7 @@ export async function matchForPrerender<TEnv = any>(
             // artifact. Re-pinned per iteration so multiple intercepts targeting
             // the same route each get their own id (mirrors fresh.ts parallel-slot
             // pinning).
-            const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
+            const interceptSegmentId = interceptSlotId(parentEntry, intercept);
             (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
               interceptSegmentId;
 

package/src/router/revalidation.ts

@@ -4,7 +4,11 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext } from "../types";
+import type {
+  ResolvedSegment,
+  HandlerContext,
+  ShouldRevalidateFn,
+} from "../types";
 import type { ActionContext } from "./types";
 import {
   debugLog,
@@ -17,6 +21,22 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 import { paramsEqual } from "./params-util.js";
 import { makeIsAction } from "./is-action.js";
 
+const REVALIDATE_ALWAYS: ShouldRevalidateFn<any, any> = () => true;
+const REVALIDATE_NEVER: ShouldRevalidateFn<any, any> = () => false;
+
+/**
+ * The predicate `revalidate(true)` / `revalidate(false)` stands for: the
+ * constant hard decision of `revalidate(() => true)` / `() => false`.
+ * Booleans are converted where they enter (the urls() helper, clientUrls()
+ * materialization, runRevalidate), so evaluation only ever sees functions.
+ */
+export function toShouldRevalidateFn(
+  fn: ShouldRevalidateFn<any, any> | boolean,
+): ShouldRevalidateFn<any, any> {
+  if (typeof fn !== "boolean") return fn;
+  return fn ? REVALIDATE_ALWAYS : REVALIDATE_NEVER;
+}
+
 /**
  * Options for revalidation evaluation
  */
@@ -85,7 +105,9 @@ export async function evaluateRevalidation<TEnv>(
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
-  const searchChanged = prevUrl.search !== nextUrl.search;
+  const reqCtx = _getRequestContext();
+  const searchChanged =
+    prevUrl.search !== nextUrl.search || reqCtx?._visitorMoved === true;
 
   function pushTrace(
     defaultVal: boolean,
@@ -197,7 +219,6 @@ export async function evaluateRevalidation<TEnv>(
 
   const toRouteName =
     routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
-  const reqCtx = _getRequestContext();
   const prevRouteKey = reqCtx?._prevRouteKey;
   const fromRouteName =
     prevRouteKey && !isAutoGeneratedRouteName(prevRouteKey)

package/src/router/router-context.ts

@@ -25,7 +25,7 @@ import type { ResolveSegmentOptions } from "./segment-resolution.js";
  * Revalidation context passed to segment resolution
  */
 export interface RevalidationContext {
-  clientSegmentIds: Set<string>;
+  clientSegmentIds: ReadonlySet<string>;
   prevParams: Record<string, string>;
   request: Request;
   prevUrl: URL;
@@ -37,7 +37,7 @@ export interface RevalidationContext {
     actionResult?: any;
     formData?: FormData;
   };
-  stale: boolean;
+  stale?: boolean;
 }
 
 /**
@@ -159,7 +159,7 @@ export interface RouterContext<TEnv = any> {
     handlerContext: HandlerContext<any, TEnv>,
     belongsToRoute: boolean,
     revalidationContext?: RevalidationContext,
-    options?: { skipMiddleware?: boolean },
+    options?: { background?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
   collectWithMarkers?: <T>(
@@ -250,23 +250,10 @@ export interface RouterContext<TEnv = any> {
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,
     entry: EntryData,
-    params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     belongsToRoute: boolean,
-    revalidationContext: {
-      clientSegmentIds: Set<string>;
-      prevParams: Record<string, string>;
-      request: Request;
-      prevUrl: URL;
-      nextUrl: URL;
-      routeKey: string;
-      actionContext?: any;
-      stale?: boolean;
-    },
-  ) => Promise<{
-    loaderDataPromise: Promise<any[]> | any[];
-    loaderIds: string[];
-  } | null>;
+    revalidationContext: RevalidationContext,
+  ) => Promise<ResolvedSegment[]>;
 }
 
 const routerContext = new AsyncLocalStorage<RouterContext<any>>();

package/src/router/router-interfaces.ts

@@ -382,13 +382,6 @@ export interface RangoInternal<
     import("../cache/profile-registry.js").CacheProfile
   >;
 
-  /**
-   * Cache-Control header value for prefetch responses.
-   * False means no caching of prefetch responses.
-   * Derived from prefetchCacheTTL.
-   */
-  readonly prefetchCacheControl: string | false;
-
   /**
    * TTL in milliseconds for the client-side in-memory prefetch cache.
    * 0 means caching is disabled.
@@ -486,12 +479,6 @@ export interface RangoInternal<
    */
   readonly nonce?: NonceProvider<TEnv>;
 
-  /**
-   * The consumer-set version (createRouter({ version })), used for both of the
-   * router's versions. Undefined when the router uses its build versions.
-   */
-  readonly version?: string;
-
   /**
    * URL patterns reference for build-time manifest generation
    */

package/src/router/router-options.ts

@@ -532,36 +532,12 @@ export interface RangoOptions<TEnv = any> {
   nonce?: NonceProvider<TEnv>;
 
   /**
-   * Version override. When set, this exact value is used for both of the
-   * router's versions: it keys the router's cached data (segments, `"use
-   * cache"` values, loader data) and its stored HTML (PPR shells,
-   * document-cache responses), is sent in payload metadata, and is what the
-   * browser's `_rsc_v` is compared with (a mismatch reloads the tab).
-   *
-   * Leave it unset for the default: rango computes two versions per router at
-   * build time, a data version from the router's server code and a document
-   * version that also covers the client assets. The same code builds to the
-   * same versions, so a deploy that does not change this router keeps its
-   * cache. In dev both are a stamp bumped on every RSC module edit.
-   *
-   * Set it to clear this router's cache on demand (change the value), or to
-   * tie the cache to your own release id (a per-deploy value clears the cache
-   * on every deploy).
-   *
-   * @default the router's build versions
-   */
-  version?: string;
-
-  /**
-   * TTL (in seconds) for the in-memory prefetch cache and the
-   * Cache-Control header on prefetch responses.
+   * TTL (in seconds) for the client-side in-memory prefetch cache.
    *
    * Controls how long prefetch responses are kept in the client-side
-   * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
-   * on prefetch responses, so the browser's HTTP cache may reuse them
-   * (`private`: shared caches such as a CDN do not store them). A route an
-   * intercept targets gets no prefetch `Cache-Control`: whether its
-   * response is the modal or the full page depends on the source page.
+   * in-memory cache. Prefetch responses carry no `Cache-Control`, so the
+   * browser's HTTP cache does not keep them: a prefetch whose render failed
+   * after its 200 went out would otherwise answer later requests.
    *
    * The cache is automatically invalidated on server actions regardless
    * of TTL, so this is primarily a staleness safety net.

package/src/router/segment-resolution/fresh.ts

@@ -38,6 +38,7 @@ import { _getRequestContext } from "../../server/request-context.js";
 import { getRouterContext } from "../router-context.js";
 import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import { observeSegmentHandler } from "../instrument.js";
+import { withReverseScope } from "../handler-context.js";
 import {
   track,
   RangoContext,
@@ -177,6 +178,7 @@ export async function resolveLoaders<TEnv>(
                 bakeLane || loaderEntry.bake === true ? segmentId : null,
               ),
             loader.$$id,
+            loaderEntry.reverseScope,
           ),
           entry,
           segmentId,
@@ -227,6 +229,7 @@ export async function resolveLoaders<TEnv>(
             bakeLane || loaderEntry.bake === true ? segmentId : null,
           ),
         loader.$$id,
+        loaderEntry.reverseScope,
       ),
       entry,
       segmentId,
@@ -646,6 +649,7 @@ export async function resolveParallelEntry<TEnv>(
   >;
 
   const slotsToResolve = slotNames ?? (Object.keys(slots) as `@${string}`[]);
+  const slotContext = withReverseScope(context, parallelEntry.reverseScope);
 
   for (const slot of slotsToResolve) {
     // Try static lookup first — in production, handler bodies are evicted
@@ -683,7 +687,7 @@ export async function resolveParallelEntry<TEnv>(
                 `${parentShortCode}.${slot}`,
                 `${parallelEntry.id}.${slot}`,
                 handler,
-                context,
+                slotContext,
               )
             : handler;
         if (result instanceof Promise) {
@@ -708,7 +712,7 @@ export async function resolveParallelEntry<TEnv>(
                 `${parentShortCode}.${slot}`,
                 `${parallelEntry.id}.${slot}`,
                 handler,
-                context,
+                slotContext,
               )
             : handler;
         doneParallelHandler();

package/src/router/segment-resolution/helpers.ts

@@ -30,6 +30,7 @@ import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
 import { observeSegmentHandler } from "../instrument.js";
+import { withReverseScope } from "../handler-context.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
@@ -176,7 +177,12 @@ export async function resolveLayoutComponent<TEnv>(
   // the span so a handler that returns a Response (redirect control flow, which it
   // rethrows) is not recorded as a span error — mirrors the route-handler sites.
   return handleHandlerResult(
-    await observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+    await observeSegmentHandler(
+      entry.shortCode,
+      entry.id,
+      handler,
+      withReverseScope(context, entry.reverseScope),
+    ),
   );
 }
 

package/src/router/segment-resolution/loader-cache.ts

@@ -378,9 +378,10 @@ function getLoaderStore(
  * push funnel reads the pushReplayed owner, shell-capture.ts), so a replay
  * of that shell that serves this loader from its pin restores them owned
  * (HandleStore.pushRestored), on a document HIT and on a navigation alike.
- * This replay still runs there: the store drops its settled values, which
- * the record already restored, and keeps the thenable ones the record could
- * not keep (a deferred push, the reason the loader's pin carries `runs`).
+ * This replay still runs there: the store drops its values that settle
+ * thenable-free, which the record already restored, and keeps the ones
+ * holding a promise the record could not keep (the reason the loader's pin
+ * carries `runs`).
  */
 async function replayLoaderHandles(
   encoded: string | undefined,

package/src/router/segment-resolution/mask-nested.ts

@@ -125,9 +125,11 @@ function someNestedThenable(
 /**
  * True when `value` is a thenable or holds one where the capture's loader
  * push funnel masks it (maskNestedContainerThenables): through plain data
- * objects, arrays and React element props. Such a push stays out of a shell's
- * record and reaches a HIT only from a run of its loader there, so a HIT
- * keeps it; a push without one is the record's (HandleStore.pushRestored).
+ * objects, arrays and React element props. A settled push that holds one
+ * stays out of a shell's record and reaches a HIT only from a run of its
+ * loader there, so a HIT keeps it; a push without one is the record's
+ * (HandleStore.pushRestored). A top-level thenable is judged by the value it
+ * settles to, on both sides (#1182).
  */
 export function holdsThenable(value: unknown): boolean {
   return someNestedThenable(value, () => true);