@rangojs/router 0.30.1 → 0.32.0

package/src/build/runtime-discovery.ts

@@ -1,5 +1,6 @@
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { Plugin, PluginOption, ViteDevServer } from "vite";
 import {
   generateRouteTypesSource,
   genFileTsPath,
@@ -35,14 +36,13 @@ export async function discoverAndWriteRouteTypes(
   routeCount: number;
   outputFiles: string[];
 }> {
-  let createViteServer: typeof import("vite").createServer;
   let loadConfigFromFile: typeof import("vite").loadConfigFromFile;
-  let rsc: any;
+  let resolveConfig: typeof import("vite").resolveConfig;
 
   try {
     const vite = await import("vite");
-    createViteServer = vite.createServer;
     loadConfigFromFile = vite.loadConfigFromFile;
+    resolveConfig = vite.resolveConfig;
   } catch {
     throw new Error(
       "Runtime discovery requires 'vite'. Install it with: pnpm add -D vite",
@@ -50,61 +50,93 @@ export async function discoverAndWriteRouteTypes(
   }
 
   try {
-    const rscMod = await import("@vitejs/plugin-rsc");
-    rsc = rscMod.default;
+    await import("@vitejs/plugin-rsc");
   } catch {
     throw new Error(
       "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc",
     );
   }
 
-  const { createVersionPlugin } =
-    await import("../vite/plugins/version-plugin.ts");
-  const { createVirtualStubPlugin } =
-    await import("../vite/plugins/virtual-stub-plugin.ts");
+  const { createTempRscServer } = await import("../vite/temp-rsc-server.js");
+  const { createDiscoveryState } = await import("../vite/discovery/state.js");
+  const { discoverClientUrlProjections } =
+    await import("../vite/discovery/client-urls-projection.js");
+  const {
+    isFrameworkPlugin,
+    pickForwardedRunnerConfig,
+    selectForwardableResolvePlugins,
+  } = await import("../vite/utils/forward-user-plugins.js");
 
-  // Load user's vite config to get resolve.alias (unless provided directly)
-  let userResolveAlias: any = opts.resolveAlias;
-  if (!userResolveAlias) {
-    const configPath = opts.configFile;
+  // The discovery temp server of `vite dev/build` (expose-internal-ids, the
+  // cloudflare:* stubs, the user's resolver plugins and resolve/define/oxc).
+  // Resolver plugins are forwarded from a resolved config, as `vite dev` does:
+  // vite-tsconfig-paths and the like build their matchers in config /
+  // configResolved, and resolving drops `apply: "build"` plugins. The
+  // framework plugins are left out of that resolve: rango()'s configResolved
+  // writes the static gen files.
+  const entryPath = resolve(opts.entry);
+  const state = createDiscoveryState(entryPath, undefined);
+  state.projectRoot = opts.root;
+  state.userResolveAlias = opts.resolveAlias;
+  if (!opts.resolveAlias) {
     try {
       const loaded = await loadConfigFromFile(
         { command: "serve", mode: "development" },
-        configPath,
+        opts.configFile,
         opts.root,
       );
-      if (loaded?.config?.resolve?.alias) {
-        userResolveAlias = loaded.config.resolve.alias;
+      if (loaded) {
+        state.userRunnerConfig = pickForwardedRunnerConfig(loaded.config);
+        const userPlugins = (
+          await flattenPluginOptions(loaded.config.plugins)
+        ).filter((p) => !isFrameworkPlugin(p.name ?? ""));
+        try {
+          // The temp server's root, so a resolver's root-relative state
+          // matches the server it runs in.
+          const resolved = await resolveConfig(
+            {
+              ...loaded.config,
+              root: opts.root,
+              configFile: false,
+              plugins: userPlugins,
+            },
+            "serve",
+            "development",
+          );
+          state.userResolvePlugins = selectForwardableResolvePlugins(
+            resolved.plugins,
+          );
+        } catch (err: any) {
+          console.warn(
+            `[rango] Could not resolve the Vite config (${err?.message ?? err}); forwarding its resolver plugins without their config hooks. rango() and rsc() are left out of that resolve, so a plugin that needs the rsc environment fails there`,
+          );
+          // The resolve would have applied `apply`; do the same for the serve
+          // pass, including the function form.
+          const serveEnv = { command: "serve", mode: "development" } as const;
+          state.userResolvePlugins = selectForwardableResolvePlugins(
+            userPlugins.filter((p) =>
+              typeof p.apply === "function"
+                ? p.apply(loaded.config, serveEnv)
+                : p.apply !== "build",
+            ),
+          );
+        }
       }
-    } catch {
-      // Config loading failed; proceed without aliases
+    } catch (err: any) {
+      // Discovery without the app's resolvers fails later on an unrelated
+      // import; name the cause here.
+      console.warn(
+        `[rango] Could not load the Vite config (${err?.message ?? err}); discovering without its resolve config and plugins`,
+      );
     }
   }
 
-  const entryPath = resolve(opts.entry);
-  let tempServer: any = null;
+  let tempServer: ViteDevServer | null = null;
 
   try {
-    tempServer = await createViteServer({
-      root: opts.root,
-      configFile: false,
-      server: { middlewareMode: true },
-      appType: "custom",
-      logLevel: "silent",
+    tempServer = await createTempRscServer(state, {
       cacheDir: "node_modules/.vite_rango_generate",
-      resolve: userResolveAlias ? { alias: userResolveAlias } : undefined,
-      esbuild: { jsx: "automatic", jsxImportSource: "react" },
-      plugins: [
-        rsc({
-          entries: {
-            client: "virtual:entry-client",
-            ssr: "virtual:entry-ssr",
-            rsc: entryPath,
-          },
-        }),
-        createVersionPlugin(),
-        createVirtualStubPlugin(),
-      ],
+      plugins: [missingGenFileStubPlugin()],
     });
 
     const rscEnv = (tempServer.environments as any)?.rsc;
@@ -125,6 +157,14 @@ export async function discoverAndWriteRouteTypes(
       );
     }
 
+    // include() of a clientUrls() module resolves from these projections.
+    await discoverClientUrlProjections(
+      state,
+      (tempServer.environments as any)?.ssr,
+      serverMod,
+      rscEnv,
+    );
+
     // Import build utilities for manifest generation
     const buildMod = await rscEnv.runner.import("@rangojs/router/build");
     const generateManifestFull = buildMod.generateManifestFull;
@@ -149,7 +189,11 @@ export async function discoverAndWriteRouteTypes(
       const mountManifests = [];
       for (const mount of mounts) {
         mountManifests.push(
-          await generateManifestFull(mount.patterns, globalMountIndex),
+          await generateManifestFull(
+            mount.patterns,
+            globalMountIndex,
+            router.__basename ? { urlPrefix: router.__basename } : undefined,
+          ),
         );
         globalMountIndex++;
       }
@@ -232,3 +276,46 @@ export async function discoverAndWriteRouteTypes(
     }
   }
 }
+
+const MISSING_GEN_PREFIX = "\0rango-missing-named-routes-gen:";
+
+/**
+ * expose-router-id makes every createRouter() file import its sibling
+ * `./<name>.named-routes.gen.js`. `vite dev/build` write those from static
+ * parsing before discovery; the CLI does not, so a missing one resolves to an
+ * empty NamedRoutes here and discovery writes the real file. An existing gen
+ * file loads from disk as usual.
+ */
+function missingGenFileStubPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:missing-gen-file-stub",
+    enforce: "pre",
+    resolveId(id, importer) {
+      if (!importer || !id.endsWith(".named-routes.gen.js")) return null;
+      const genPath = genFileTsPath(importer.split("?", 1)[0]);
+      if (id !== `./${basename(genPath, ".ts")}.js` || existsSync(genPath)) {
+        return null;
+      }
+      return MISSING_GEN_PREFIX + genPath;
+    },
+    load(id) {
+      return id.startsWith(MISSING_GEN_PREFIX)
+        ? "export const NamedRoutes = {};\n"
+        : null;
+    },
+  };
+}
+
+/**
+ * Flatten an unresolved `plugins` option (nested arrays, promises, falsy
+ * entries) the way Vite's config resolution does, without running any hook.
+ */
+async function flattenPluginOptions(
+  option: PluginOption | undefined,
+): Promise<Plugin[]> {
+  const value = await option;
+  if (Array.isArray(value)) {
+    return (await Promise.all(value.map(flattenPluginOptions))).flat();
+  }
+  return value ? [value as Plugin] : [];
+}

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/client-urls/server-projection.ts

@@ -170,8 +170,10 @@ function serializeSearchSchema(
     throw projectionError(route, 'path option "search" must be an object');
   }
 
+  // Source order, not sorted: the build writes the gen file's search keys from
+  // this projection and must match `rango generate`'s static parse (#1322).
   const entries: Array<[string, SearchSchemaValue]> = [];
-  for (const key of Object.keys(value).sort()) {
+  for (const key of Object.keys(value)) {
     const schemaValue = (value as Record<string, unknown>)[key];
     if (
       typeof schemaValue !== "string" ||

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).