@rangojs/router 0.31.0 → 0.32.0

package/src/cache/document-cache-policy.ts

@@ -69,7 +69,10 @@ export function shouldCacheResponse(
   response: Response,
   requestCtx?: Pick<
     RequestContext,
-    "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation"
+    | "_payloadVisitorTheme"
+    | "_payloadDeferred"
+    | "_payloadVisitorLocation"
+    | "_documentLocationState"
   >,
 ): CacheDirectives | null {
   // Only cache successful responses
@@ -100,6 +103,12 @@ export function shouldCacheResponse(
     return null;
   }
 
+  // The payload carries the visitor's location state (#1330,
+  // server/document-location-state.ts).
+  if (requestCtx?._documentLocationState) {
+    return null;
+  }
+
   // prefetch: false. The payload carries deferred units: it answers one
   // page's prefetch and nothing else. parseCacheControl refuses the
   // Cache-Control it is sent with (rsc-rendering.ts NOT_REUSED), but a

package/src/cache/document-cache.ts

@@ -276,6 +276,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
+    // Location state is already set for this request (a document redirect's
+    // cookie, an earlier middleware): the response is the visitor's, so a
+    // stored body must not answer it, and it is not stored.
+    if ((requestCtx._locationState?.length ?? 0) > 0) {
+      return next();
+    }
+
     // The write gate's start (#977) and the entry's stamp (#1068): the
     // request's, not this middleware's, also for a stale refresh. A
     // middleware ahead of this one can read tagged data the document bakes,

package/src/route-definition/redirect.ts

@@ -20,6 +20,11 @@ import { prefixBasename } from "../router/basename.js";
  * Supports an optional state parameter to carry location state through the
  * redirect. On the target page, state can be read via useLocationState()
  * (use { flash: true } in createLocationState for read-once flash messages).
+ * On a client navigation or action the state travels in the redirect's
+ * payload. On a document request (a page load, a no-JS form post) it travels
+ * in a one-shot cookie the target's document request reads and clears, as
+ * JSON: give it plain JSON data there. `{ external: true }` carries none.
+ * Two entries of the same definition keep only the last.
  *
  * @param url - The URL to redirect to
  * @param statusOrOptions - HTTP status code (default: 302) or options object

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

@@ -313,12 +313,15 @@ function cachedSegmentSends<TEnv>(
  * Whether a prerender entry's segment is sent. On a partial navigation the
  * client keeps the segments it holds. The route's own segments (an
  * intercept's included) are sent again when the params changed (e.g., a
- * different guide slug). An overlay entry may be newer than the client's
- * copy: on an action or a stale request they are re-sent too, as a live
+ * different guide slug), and kept on equal params whatever the search: a
+ * prerender does not vary by search. An overlay entry may be newer than the
+ * client's copy: on an action or a stale request they are re-sent too, as a live
  * action re-render re-sends them (revalidation.ts "action:route-segment");
  * the immutable bundled manifest keeps the client's copy. A held segment
  * above the route stays held, as a live walk keeps it ("nav:non-route-skip"),
- * unless its revalidate() rules ask for it when the params changed.
+ * unless its revalidate() rules ask for it when the params changed. A route
+ * segment, or one with rules, kept on equal params marks the match
+ * source-held: the decision hangs on the source's params.
  *
  * Decided once per decoded segment, by object: an intercept variant can hold
  * a layout's parallel and the intercept's slot under one id. decodeStoredEntry
@@ -333,9 +336,17 @@ function storedEntrySends<TEnv>(
   const paramsChanged = !paramsEqual(ctx.matched.params, ctx.prevParams);
   const resendRouteSegments = replaceable && (ctx.isAction || ctx.stale);
   const entryRevalidateMap =
-    paramsChanged && router.buildEntryRevalidateMap
-      ? router.buildEntryRevalidateMap(ctx.entries)
+    ctx.clientSegmentSet.size > 0
+      ? router.buildEntryRevalidateMap?.(ctx.entries)
       : undefined;
+  // A keep that hangs on the source's params is right for this source only:
+  // scope a prefetch of the answer to it, as a predicate that read the
+  // source would (#1331).
+  const heldForSource = (): false => {
+    (ctx.handlerContext as InternalHandlerContext<any, TEnv>)._sourceHeld =
+      true;
+    return false;
+  };
   const decide = (segment: ResolvedSegment): boolean | Promise<boolean> => {
     if (!ctx.clientSegmentSet.has(segment.id)) return true;
     // A fill keeps it (fillSends).
@@ -346,10 +357,16 @@ function storedEntrySends<TEnv>(
     );
     if (fill !== undefined) return fill;
     if (segment.type === "route" || segment.belongsToRoute === true) {
-      return paramsChanged || resendRouteSegments;
+      if (paramsChanged || resendRouteSegments) return true;
+      // Kept on equal params, whatever the search: a source with other
+      // params is sent it.
+      return heldForSource();
     }
     const revalidate = entryRevalidateMap?.get(segment.id)?.revalidate;
     if (!revalidate?.length) return false;
+    // Kept on equal params: from another source the rules run and may send
+    // it.
+    if (!paramsChanged) return heldForSource();
     return router.evaluateRevalidation({
       segment,
       prevParams: ctx.prevParams,

package/src/router/match-result.ts

@@ -107,7 +107,11 @@
  *   3. Diff against previous state with diff[]
  *   4. Render slot content if slots present
  */
-import type { MatchResult, ResolvedSegment } from "../types.js";
+import type {
+  InternalHandlerContext,
+  MatchResult,
+  ResolvedSegment,
+} from "../types.js";
 import { isPlaceholder } from "../types/segments.js";
 import { interceptMatched } from "../browser/intercept-utils.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
@@ -304,6 +308,10 @@ export function buildMatchResult<TEnv>(
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
     ...(interceptTargets.length > 0 ? { interceptTargets } : {}),
     ...(ctx.interceptTargeted ? { interceptTargeted: true } : {}),
+    ...((ctx.handlerContext as InternalHandlerContext<any, TEnv> | undefined)
+      ?._sourceHeld
+      ? { sourceHeld: true }
+      : {}),
     routeMiddleware:
       ctx.routeMiddleware.length > 0 ? ctx.routeMiddleware : undefined,
   };

package/src/router/middleware-types.ts

@@ -78,6 +78,12 @@ export interface MiddlewareContext<
 
   setTheme?: (theme: Theme) => void;
 
+  /**
+   * Attach location state entries to this response (see the handler
+   * context's `setLocationState`). Entries accumulate across definitions;
+   * for one definition the last write wins. Set it here rather than in a
+   * handler on a `ppr` route: a shell HIT runs no handler.
+   */
   setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
 
   /** Global route names only; see {@link GlobalReverseFunction}. */

package/src/router/revalidation.ts

@@ -7,6 +7,7 @@
 import type {
   ResolvedSegment,
   HandlerContext,
+  InternalHandlerContext,
   ShouldRevalidateFn,
 } from "../types";
 import type { ActionContext } from "./types";
@@ -154,11 +155,19 @@ export async function evaluateRevalidation<TEnv>(
   // second, contradicting entry would let flushRevalidationTrace count the
   // segment as both revalidated and skipped.
   const floorTrue = defaultOverride?.floor === true && defaultOverride.value;
+  // A predicate read the page navigated away from. A segment it keeps then
+  // stays held for this source only: a prefetch of the answer, adopted on
+  // another page, would keep that page's copy (#1331). A re-render is
+  // source-safe, it sends the segment.
+  let readSource = false;
   function decide(finalVal: boolean, reason: string): boolean {
     if (floorTrue && !finalVal) {
       pushTrace(defaultShouldRevalidate, true, `${reason}:floored`);
       return true;
     }
+    if (!finalVal && readSource) {
+      (context as InternalHandlerContext<any, TEnv>)._sourceHeld = true;
+    }
     pushTrace(defaultShouldRevalidate, finalVal, reason);
     return finalVal;
   }
@@ -253,12 +262,20 @@ export async function evaluateRevalidation<TEnv>(
 
   const isActionFn = makeIsAction(actionContext?.actionId);
 
+  const currentParams = prevSegment?.params || prevParams;
+
   for (const { name, fn } of revalidations) {
     let result: any;
     try {
       result = fn({
-        currentParams: prevSegment?.params || prevParams, // Use segment params if available, else route params
-        currentUrl: prevUrl,
+        get currentParams() {
+          readSource = true;
+          return currentParams;
+        },
+        get currentUrl() {
+          readSource = true;
+          return prevUrl;
+        },
         nextParams,
         nextUrl,
         defaultShouldRevalidate: currentSuggestion,
@@ -275,7 +292,10 @@ export async function evaluateRevalidation<TEnv>(
         formData: actionContext?.formData,
         method: request.method,
         routeName: toRouteName,
-        fromRouteName,
+        get fromRouteName() {
+          readSource = true;
+          return fromRouteName;
+        },
         toRouteName,
         stale: cacheStale ? true : stale,
       });

package/src/rsc/helpers.ts

@@ -340,14 +340,23 @@ export function interceptRedirectForPartial(
 /**
  * Attach location state set during a request to a payload's metadata.
  * No-op if no location state was set. Callers must ensure payload.metadata
- * is populated (the non-null assertion holds for the partial/action payloads
- * that reach this helper).
+ * is populated. A `document` payload (a page load's or a no-JS form post's
+ * bootstrap payload) that carries state marks the request
+ * `_documentLocationState`: it is the visitor's, so no shared cache keeps it
+ * (server/document-location-state.ts).
  */
-export function attachLocationStateIfPresent(payload: RscPayload): void {
+export function attachLocationStateIfPresent(
+  payload: RscPayload,
+  document = false,
+): void {
   const locationState = getLocationState();
-  if (locationState) {
+  if (locationState && locationState.length > 0) {
     payload.metadata!.locationState =
       resolveLocationStateEntries(locationState);
+    if (document) {
+      const ctx = _getRequestContext();
+      if (ctx) ctx._documentLocationState = true;
+    }
   }
 }
 

package/src/rsc/progressive-enhancement.ts

@@ -25,6 +25,7 @@ import type { RscPayload, ReactFormState } from "./types.js";
 import type { MatchResult } from "../types.js";
 import {
   actionRenderRequest,
+  attachLocationStateIfPresent,
   createResponseWithMergedHeaders,
   finalizeResponse,
   buildRouteMiddlewareEntries,
@@ -448,6 +449,10 @@ function renderPeResponse<TEnv>(
     // slot instead of failing the payload root and the whole document.
     ...(reactFormState ? { formState: Promise.resolve(reactFormState) } : {}),
   };
+  // The action's location state rides the re-rendered document's bootstrap
+  // payload, as a JS action's rides its response. Not on a failure render,
+  // like the JS path.
+  if (!failure) attachLocationStateIfPresent(payload, true);
 
   const trace = getRequestContext()._activeRoutine;
 

package/src/rsc/request-stages.ts

@@ -84,6 +84,11 @@ import {
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type { CacheErrorCategory } from "../cache/cache-error.js";
 import { WIRE } from "../wire-params.js";
+import {
+  carryLocationStateAcrossRedirect,
+  consumeDocumentLocationState,
+  markDocumentResponsePrivate,
+} from "../server/document-location-state.js";
 
 /**
  * The router members the stages read. The handler's `RangoInternal` carries
@@ -96,6 +101,8 @@ export interface StageRouter<TEnv = unknown> {
   readonly telemetry?: TelemetrySink;
   readonly timeouts?: ResolvedTimeouts;
   readonly onTimeout?: OnTimeoutCallback<TEnv>;
+  /** Names the cookie location state crosses a document redirect in. */
+  readonly resolvedStateCookieName: string;
 }
 
 /** Report an error through the router's onError. */
@@ -409,6 +416,14 @@ export async function runRequestPasses<TEnv>(
   opts: RequestPassesOptions<TEnv>,
 ): Promise<RequestPassesResult> {
   const { ctx, env, variables } = opts;
+  // Before any middleware: a document cache lookup, a PPR shell serve and the
+  // render all see the state a document redirect carried here.
+  consumeDocumentLocationState(
+    opts.reqCtx,
+    opts.request,
+    opts.url,
+    ctx.router.resolvedStateCookieName,
+  );
   let passIndex = 0;
   let hasMiddleware = false;
   const runChain = (
@@ -707,7 +722,19 @@ export function finalizeRequestResponse<TEnv>(
   // guarding browser-followed (3xx) redirects once covers them all and any
   // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
   // through untouched (validated client-side instead).
-  const guarded = guardOutgoingRedirect(response, url.origin, router.basename);
+  // After the guard, so the cookie names the target the browser follows.
+  // A document carrying location state, or a redirect carrying it on, leaves
+  // private: set after every middleware, so none can make it shared.
+  const guarded = markDocumentResponsePrivate(
+    carryLocationStateAcrossRedirect(
+      guardOutgoingRedirect(response, url.origin, router.basename),
+      reqCtx,
+      request,
+      url,
+      router.resolvedStateCookieName,
+    ),
+    reqCtx,
+  );
 
   // Stream-idle watchdog (opt-in via timeouts.streamIdleMs): bounds
   // end-to-end idle flow on the streamed body — see rsc/stream-idle.ts

package/src/rsc/rsc-rendering.ts

@@ -430,6 +430,12 @@ function* requestRenderPlan<TEnv>(
   // chain (executeRender wraps it), so no shell byte can precede a guard
   // decision — that ordering is what makes a shared shell safe. Routes
   // without the `ppr` option stay pure axis 1 at zero cost.
+  //
+  // Location state set by now (middleware, a document redirect's cookie) does
+  // not keep a request off the shell: a HIT attaches it to the live tail's
+  // payload, and a capture builds its own payload without it, so no shell
+  // ever holds a visitor's state (server/document-location-state.ts).
+  const stateBeforeRender = reqCtx._locationState?.length ?? 0;
   const shell = yield* scope("shell-serve", shellServePlan(input));
   if (shell.kind === "serve") return shell.response;
 
@@ -441,11 +447,12 @@ function* requestRenderPlan<TEnv>(
   );
   if (prepared.kind === "control") return prepared.response;
 
-  // For partial requests, include any server-set location state in the payload.
-  // SSR (full page) requests ignore location state since there's no history.state
-  // to write to on a fresh page load.
-  if (isPartial && prepared.payload.metadata) {
-    attachLocationStateIfPresent(prepared.payload);
+  // Server-set location state rides the payload: a navigation's, merged at
+  // its commit, or a document's bootstrap payload, merged when the client
+  // starts (browser/rsc-router.tsx). A document carrying it is per visitor
+  // (server/document-location-state.ts).
+  if (prepared.payload.metadata) {
+    attachLocationStateIfPresent(prepared.payload, !isPartial);
   }
 
   const response = yield* step("render", () =>
@@ -457,8 +464,14 @@ function* requestRenderPlan<TEnv>(
   // shell). Capture does not flow through the HTTP pipeline — middleware never
   // re-runs (it already ran for this request; guarding is serve-time).
   // reqCtx._dynamic is re-read here on purpose: a loader may have marked the
-  // request dynamic while rendering.
-  if (shell.kind === "miss" && !reqCtx._dynamic) {
+  // request dynamic while rendering. State a handler set in this render is
+  // not captured: a HIT replays the handler's output without running it, so
+  // the state would be lost on every HIT. The route renders in full instead.
+  if (
+    shell.kind === "miss" &&
+    !reqCtx._dynamic &&
+    (reqCtx._locationState?.length ?? 0) <= stateBeforeRender
+  ) {
     if (
       response.status === 200 &&
       (response.headers.get("content-type") ?? "").includes("text/html")
@@ -885,7 +898,10 @@ function* preparePayloadPlan<TEnv>(
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       },
-      sourceScoped: result.interceptTargeted === true || deferring,
+      sourceScoped:
+        result.interceptTargeted === true ||
+        result.sourceHeld === true ||
+        deferring,
       pprReplayStatus,
       healKey,
     };
@@ -1116,7 +1132,9 @@ function renderPreparedRscResponse<TEnv>(
   // intercept targets renders the modal or the full page depending on the
   // source, so neither response may be reused from another source: a full
   // page prefetched where the intercept does not apply would otherwise
-  // serve a later click where it does (#1007).
+  // serve a later click where it does (#1007). So is a diff a revalidate()
+  // decided from the source page: another page adopting it would keep its
+  // own copy of the segment the answer held (#1331).
   if (sourceScoped) {
     rscHeaders["x-rsc-prefetch-scope"] = "source";
   }
@@ -1712,6 +1730,15 @@ function serveShellHit(
   // 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;
+  // Location state set before the render (middleware, a document redirect's
+  // cookie) rides the tail's payload, not the shell. Marked here, on the
+  // request's own context and before the response leaves (the tail runs on a
+  // derived context, after an await), so the response goes
+  // `private, no-store` and stays out of the document cache
+  // (server/document-location-state.ts).
+  if ((reqCtx._locationState?.length ?? 0) > 0) {
+    reqCtx._documentLocationState = 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
@@ -1768,6 +1795,9 @@ function serveShellHit(
         | undefined;
       // Same for the location: the key's URL, or a visitor-keyed shell's.
       payload.metadata.pathname = entry.pathname ?? url.pathname;
+      // The visitor's location state, as a MISS document's payload carries
+      // it. The request was marked per visitor above.
+      attachLocationStateIfPresent(payload);
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).