@rangojs/router 0.26.6 → 0.27.0

package/src/router/match-middleware/cache-lookup.ts

@@ -93,7 +93,11 @@
  */
 import type { InternalHandlerContext, ResolvedSegment } from "../../types.js";
 import { isPprEntry, type EntryData } from "../../server/context.js";
-import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import {
+  rendersLive,
+  type MatchContext,
+  type MatchPipelineState,
+} from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
 import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
@@ -280,9 +284,9 @@ async function* yieldFromStore<TEnv>(
   /**
    * The entry may be newer than the client's copy: an on-demand overlay entry
    * that a refresh (possibly inside this very action) replaced. On an action
-   * the route's own segments are then re-sent, as a live action re-render
-   * re-sends them (revalidation.ts "action:route-segment"); the immutable
-   * bundled manifest keeps the client's copy.
+   * or a stale request the route's own segments are then re-sent, as a live
+   * action re-render re-sends them (revalidation.ts "action:route-segment");
+   * the immutable bundled manifest keeps the client's copy.
    */
   replaceable?: boolean,
 ): AsyncGenerator<ResolvedSegment> {
@@ -348,7 +352,9 @@ async function* yieldFromStore<TEnv>(
   // different content, so we must NOT nullify.
   const paramsChanged =
     !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
-  const resendRouteSegments = replaceable === true && ctx.isAction;
+  // The action defaults' route segment (revalidation.ts), not a cache skip.
+  const resendRouteSegments =
+    replaceable === true && (ctx.isAction || ctx.stale);
   for (const segment of segments) {
     if (interceptFillSkips(ctx, segment)) continue;
     if (!ctx.isFullMatch && ctx.clientSegmentSet.has(segment.id)) {
@@ -679,8 +685,9 @@ export function withCacheLookup<TEnv>(
       // its result is applied client-side via useActionState). A plain on-demand
       // route is the same case, served from the overlay first (an overlay entry
       // is newer than the build one, and may be the only one). Passthrough
-      // routes keep a liveHandler, so they still re-render fresh on actions.
-      if (!ctx.isAction || !isPassthroughPrerenderRoute) {
+      // routes keep a liveHandler, so a live render (rendersLive) re-renders
+      // them fresh.
+      if (!rendersLive(ctx) || !isPassthroughPrerenderRoute) {
         await ensurePrerenderDeps();
         if (prerenderStoreInstance || prerenderOverlay) {
           const served = yield* tryPrerenderLookup(
@@ -698,7 +705,11 @@ export function withCacheLookup<TEnv>(
       }
     }
 
-    if (!ctx.isAction && !ctx.matched.pr && globalThis.__PRERENDER_DEV_URL) {
+    if (
+      !rendersLive(ctx) &&
+      !ctx.matched.pr &&
+      globalThis.__PRERENDER_DEV_URL
+    ) {
       const hasStatic = ctx.entries.some(
         (e) =>
           (e.type === "layout" ||
@@ -737,7 +748,7 @@ export function withCacheLookup<TEnv>(
     // pushes of segments the response does not carry. withCacheStore skips
     // the write for the same request.
     if (
-      ctx.isAction ||
+      rendersLive(ctx) ||
       !ctx.cacheScope?.enabled ||
       !recordUse(ctx.handlerContext).read
     ) {
@@ -1004,7 +1015,7 @@ export function withCacheLookup<TEnv>(
         routeKey: ctx.routeKey,
         context: ctx.handlerContext,
         actionContext: ctx.actionContext,
-        stale: cacheResult.shouldRevalidate || ctx.stale || undefined,
+        cacheStale: cacheResult.shouldRevalidate,
         traceSource: "cache-hit",
       });
 

package/src/router/match-middleware/cache-store.ts

@@ -19,7 +19,7 @@
  *   +---------------------+
  *   | Should skip cache?  |
  *   | - !cacheScope       |──yes──> return
- *   | - isAction          |
+ *   | - rendersLive       |
  *   | - cacheHit          |
  *   | - method !== GET    |
  *   +---------------------+
@@ -105,7 +105,11 @@ import {
   getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
-import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import {
+  rendersLive,
+  type MatchContext,
+  type MatchPipelineState,
+} from "../match-context.js";
 import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
 import { recordSegmentTags } from "../../cache/cache-tag.js";
 import { executionStart } from "../../cache/tag-invalidation.js";
@@ -155,7 +159,7 @@ export function withCacheStore<TEnv>(
     // and could only write an incomplete one.
     if (
       !ctx.cacheScope?.enabled ||
-      ctx.isAction ||
+      rendersLive(ctx) ||
       state.cacheHit ||
       ctx.request.method !== "GET" ||
       !recordUse(ctx.handlerContext).write
@@ -355,7 +359,9 @@ function recordShellCaptureDocRecord<TEnv>(
   if (!marker?.store) return;
   const scope = ctx.cacheScope;
   if (!scope || scope.isShellImplicitDocScope) return;
-  if (ctx.isAction || ctx.isIntercept || ctx.request.method !== "GET") return;
+  if (rendersLive(ctx) || ctx.isIntercept || ctx.request.method !== "GET") {
+    return;
+  }
   if (state.cacheSource === "prerender") return;
   if (!scope.allowsCache("write")) return;
 

package/src/router/match-result.ts

@@ -109,7 +109,7 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import { isPlaceholder } from "../types/segments.js";
-import { loaderParentId } from "../browser/react/filter-segment-order.js";
+import { interceptMatched } from "../browser/intercept-utils.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { debugLog } from "./logging.js";
 import { appendMetric } from "./metrics.js";
@@ -196,25 +196,6 @@ function deduplicateLoaderSegments(
   return { segments: result, removedIds };
 }
 
-/**
- * An intercept's `matched`: the client's ids without any of the slot's (its
- * id and every loader segment on it, another intercept's into the same slot
- * included), then the slot's (interceptSegmentIds). One order for the
- * prefetch, its fill, an action and a revisit: a fill whose `matched` differs
- * from its tree's is rendered as a new tree (browser/partial-update.ts
- * fillHoles).
- */
-function interceptMatched(
-  clientIds: readonly string[],
-  slotIds: readonly string[],
-): string[] {
-  // loaderParentId leaves a non-loader id as it is: the slot's own id goes too.
-  return [
-    ...clientIds.filter((id) => loaderParentId(id) !== slotIds[0]),
-    ...slotIds,
-  ];
-}
-
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,

package/src/router/navigation-snapshot.ts

@@ -1,5 +1,6 @@
 import { isLoaderSegmentId } from "../browser/react/filter-segment-order.js";
 import { requestHeaders } from "../server/request-headers.js";
+import { STALE_PARAM } from "../prefetch-markers.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface NavigationSnapshot {
@@ -134,7 +135,7 @@ export async function resolveNavigation(
 ): Promise<NavigationSnapshot | null> {
   const clientSegmentIds =
     url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
-  const stale = url.searchParams.get("_rsc_stale") === "true";
+  const stale = url.searchParams.get(STALE_PARAM) === "true";
   const previousUrl = getNavigationContextHeader(request, url.origin);
   const interceptSourceUrl = getInterceptSourceHeader(request);
   const isHmr = !!requestHeaders(request).get("X-RSC-HMR");

package/src/router/revalidation.ts

@@ -24,6 +24,22 @@ import { makeIsAction } from "./is-action.js";
 const REVALIDATE_ALWAYS: ShouldRevalidateFn<any, any> = () => true;
 const REVALIDATE_NEVER: ShouldRevalidateFn<any, any> = () => false;
 
+/** Trace reasons of the action defaults, per lane: an action, a stale request. */
+const ACTION_DEFAULT_REASONS = {
+  action: {
+    route: "action:route-segment",
+    loader: "action:loader-segment",
+    routeChild: "action:belongs-to-route",
+    parentChain: "action:parent-chain-skip",
+  },
+  stale: {
+    route: "stale:route-segment",
+    loader: "stale:loader-segment",
+    routeChild: "stale:belongs-to-route",
+    parentChain: "stale:parent-chain-skip",
+  },
+} as const;
+
 /**
  * The predicate `revalidate(true)` / `revalidate(false)` stands for: the
  * constant hard decision of `revalidate(() => true)` / `() => false`.
@@ -61,8 +77,13 @@ export interface EvaluateRevalidationOptions<TEnv> {
   context: HandlerContext<any, TEnv>;
   /** Action context if triggered by action */
   actionContext?: ActionContext;
-  /** If true, this is a stale cache revalidation request */
+  /** The browser's `_rsc_stale` signal: seeds the action defaults. */
   stale?: boolean;
+  /**
+   * The route-cache entry is past its TTL (SWR). Predicates see it as `stale`;
+   * it never seeds the action defaults.
+   */
+  cacheStale?: boolean;
   /** Trace source hint for the revalidation trace */
   traceSource?: RevalidationTraceEntry["source"];
   /**
@@ -100,6 +121,7 @@ export async function evaluateRevalidation<TEnv>(
     context,
     actionContext,
     stale,
+    cacheStale,
     traceSource,
     defaultOverride,
   } = options;
@@ -147,19 +169,23 @@ export async function evaluateRevalidation<TEnv>(
   if (defaultOverride) {
     defaultShouldRevalidate = defaultOverride.value;
     defaultReason = defaultOverride.reason;
-  } else if (request.method === "POST") {
+  } else if (request.method === "POST" || stale) {
+    // A stale request re-renders a page an action may have changed after the
+    // client cached it. Not an action: no actionContext, isAction() is false.
+    const reasons =
+      ACTION_DEFAULT_REASONS[request.method === "POST" ? "action" : "stale"];
     if (segment.type === "route") {
       defaultShouldRevalidate = true;
-      defaultReason = "action:route-segment";
+      defaultReason = reasons.route;
     } else if (segment.type === "loader") {
       defaultShouldRevalidate = true;
-      defaultReason = "action:loader-segment";
+      defaultReason = reasons.loader;
     } else if (segment.belongsToRoute) {
       defaultShouldRevalidate = true;
-      defaultReason = "action:belongs-to-route";
+      defaultReason = reasons.routeChild;
     } else {
       defaultShouldRevalidate = false;
-      defaultReason = "action:parent-chain-skip";
+      defaultReason = reasons.parentChain;
     }
   } else {
     if (segment.type === "route") {
@@ -251,7 +277,7 @@ export async function evaluateRevalidation<TEnv>(
         routeName: toRouteName,
         fromRouteName,
         toRouteName,
-        stale,
+        stale: cacheStale ? true : stale,
       });
     } catch (error) {
       // A thrown Response is control flow (e.g. `throw redirect(...)`), not a

package/src/router/router-context.ts

@@ -20,6 +20,7 @@ import type {
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { ResolveSegmentOptions } from "./segment-resolution.js";
+import type { EvaluateRevalidationOptions } from "./revalidation.js";
 
 /**
  * Revalidation context passed to segment resolution
@@ -166,28 +167,9 @@ export interface RouterContext<TEnv = any> {
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<{ items: T[]; matchedIds: string[] }>;
 
-  evaluateRevalidation: (params: {
-    segment: ResolvedSegment;
-    prevParams: Record<string, string>;
-    getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
-    request: Request;
-    prevUrl: URL;
-    nextUrl: URL;
-    revalidations: Array<{ name: string; fn: any }>;
-    routeKey: string;
-    context: HandlerContext<any, TEnv>;
-    actionContext?: any;
-    stale?: boolean;
-    traceSource?:
-      | "segment-resolution"
-      | "cache-hit"
-      | "loader"
-      | "parallel"
-      | "orphan-layout"
-      | "route-handler"
-      | "layout-handler"
-      | "intercept-loader";
-  }) => Promise<boolean>;
+  evaluateRevalidation: (
+    params: EvaluateRevalidationOptions<TEnv>,
+  ) => Promise<boolean>;
 
   getRequestContext: () =>
     | {

package/src/rsc/rsc-rendering.ts

@@ -99,7 +99,7 @@ import {
 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 { PREFETCH_HEADER, STALE_PARAM } from "../prefetch-markers.js";
 import {
   isWarmReplace,
   noteWarmShellEvent,
@@ -1268,11 +1268,14 @@ function renderPreparedRscResponse<TEnv>(
   // 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
   // document cache (which also refuses a payload marked `_payloadDeferred`),
-  // whatever Cache-Control the route set. A route with no flag keeps its
-  // headers.
+  // whatever Cache-Control the route set; so is a stale partial render, which
+  // a shared cache keyed by URL must not store or serve. A route with no flag
+  // keeps its headers.
   if (
     reqCtx._payloadDeferred ||
-    (isPartial && reqCtx._requestKind === "fill")
+    (isPartial &&
+      (reqCtx._requestKind === "fill" ||
+        url.searchParams.get(STALE_PARAM) === "true"))
   ) {
     rscHeaders["cache-control"] = NOT_REUSED;
   }
@@ -1460,6 +1463,11 @@ async function matchPartialWithPprReplay<TEnv>(
   if (!getNavigationContextHeader(request, url.origin)) {
     return runMatch({ outcome: "BYPASS", reason: "no-navigation-context" });
   }
+  // A stale partial renders live, as an action does (rendersLive,
+  // router/match-context.ts): the record may predate the action's write.
+  if (url.searchParams.get(STALE_PARAM) === "true") {
+    return runMatch({ outcome: "BYPASS", reason: "stale" });
+  }
   // Fragment passthrough (#700), extended to partial replay. Navigation
   // context proves the request can be matched; the separate capability header
   // proves its payload consumer can expand envelopes. Older clients and the

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

@@ -52,6 +52,8 @@ export const PPR_REPLAY_STATUS_HEADER: string = "x-rango-ppr-replay";
  */
 export const PPR_REPLAY_BYPASS_REASONS = [
   "method",
+  // A stale request (`_rsc_stale`) renders live, as an action does.
+  "stale",
   "dynamic",
   "nonce",
   "store-unavailable",

package/src/ssr/ssr-root.tsx

@@ -140,6 +140,7 @@ function createSsrEventController(opts: {
     },
     abortAllActions: () => {},
     getCurrentNavigation: () => null,
+    getUnsettledNavigation: () => null,
     getInflightActions: () => new Map(),
     hadAnyConcurrentActions: () => false,
   };

package/src/testing/serve-shell-request.ts

@@ -58,7 +58,11 @@ import {
   SHELL_CAPTURE_MAX_WAIT_MS,
 } from "../rsc/shell-capture-constants.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../segment-fragments.js";
-import { FILL_PARAM, PREFETCH_HEADER } from "../prefetch-markers.js";
+import {
+  FILL_PARAM,
+  PREFETCH_HEADER,
+  STALE_PARAM,
+} from "../prefetch-markers.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { withoutPushedBy } from "../handles/pushed-by.js";
 import type { HandleData } from "../server/handle-store.js";
@@ -105,6 +109,12 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * that source. `rewriteTarget` sends the `metadata.rewriteTarget` the page at
    * `from` carried when middleware rewrote it (`_rsc_rt`), as the browser
    * does: the server then diffs against the route that rendered that page.
+   * `stale: true` sends a stale request (`_rsc_stale`), as the browser sends
+   * it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`)
+   * and segments take an action's revalidation defaults; it renders live, as
+   * an action does, so neither the route cache nor the document cache answers
+   * or stores it, and a `ppr` route's `replayStatus` is
+   * `{ outcome: "BYPASS", reason: "stale" }`.
    */
   partial?:
     | true
@@ -115,6 +125,7 @@ export interface ServeShellRequestOptions<TEnv = any> {
         prefetch?: boolean;
         fill?: boolean;
         interceptSource?: string;
+        stale?: boolean;
       };
   /**
    * POST this form as a submit before hydration: the no-JS request the
@@ -628,14 +639,21 @@ async function buildRequest(
     prefetch = false,
     fill = false,
     interceptSource,
+    stale = false,
   } = partial === true ? {} : partial;
+  if (stale && prefetch) {
+    throw new Error(
+      "serveShellRequest: partial.stale cannot be combined with partial.prefetch",
+    );
+  }
   const target = new URL(url);
   target.searchParams.set("_rsc_partial", "true");
   target.searchParams.set("_rsc_segments", segments.join(","));
   if (rewriteTarget) target.searchParams.set("_rsc_rt", rewriteTarget);
-  // As the browser sends them: browser/navigation-client.ts (fill) and
+  // As the browser sends them: browser/navigation-client.ts (fill, stale) and
   // browser/prefetch/fetch.ts (prefetch).
   if (fill) target.searchParams.set(FILL_PARAM, "1");
+  if (stale) target.searchParams.set(STALE_PARAM, "true");
   if (prefetch && !headers.has(PREFETCH_HEADER)) {
     headers.set(PREFETCH_HEADER, "1");
   }

package/src/types/handler-context.ts

@@ -637,10 +637,10 @@ export type IsActionFn = (...actions: ActionRef[]) => boolean;
  * ```ts
  * import * as CartActions from "./actions/cart";
  *
- * // Idiom A — "mine, else defer": re-render on my actions, otherwise return
- * // undefined so the segment's default decision still applies (and downstream
- * // revalidators get a say).
- * revalidate((ctx) => ctx.isAction(CartActions) || undefined)
+ * // Idiom A — "mine, else defer": re-render on my actions and on Back after
+ * // an action, otherwise return undefined so the segment's default decision
+ * // still applies (and downstream revalidators get a say).
+ * revalidate((ctx) => ctx.isAction(CartActions) || ctx.stale || undefined)
  *
  * // Idiom B — "mine only": re-render on my actions and suppress everything
  * // else (isAction returns a raw boolean, so an unrelated action yields false).
@@ -768,8 +768,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
   // ── Staleness signal ─────────────────────────────────────────────────
 
   /**
-   * `true` when the browser signals that data may be stale — typically because
-   * a server action was executed in this or another tab (`_rsc_stale` header).
+   * `true` on a revalidation of a page the browser marked stale (the
+   * `_rsc_stale` query param): Back/Forward onto a history entry after a
+   * server action in this or another tab, or while one is in flight. A request
+   * that holds no segments (the follow-up after an action, `refresh()`) is
+   * marked stale too, but there every segment renders and no predicate runs.
    *
    * This is NOT segment cache staleness (loaders are never segment-cached).
    * Use this to decide whether loader data should be re-fetched after an