@rangojs/router 0.19.1 → 0.21.0

package/src/cache/index.ts

@@ -56,3 +56,7 @@ export {
 } from "./document-cache.js";
 
 export type { CacheErrorCategory } from "./cache-error.js";
+
+// For a custom persistent store: the versions the built-in stores key with.
+export { getCacheVersions } from "../server/build-version-table.js";
+export type { RouterVersions } from "../router-versions.js";

package/src/cache/shell-snapshot.ts

@@ -18,7 +18,9 @@
  * the capture's copy of a value: it is dynamic or has its own cache. A
  * bake-lane loader body that runs on a HIT reads the store too; its pinned
  * container paths stay the pin's (overlayLoaderContainer), and its settled
- * pushes stay the record's (HandleStore.pushRestored).
+ * pushes stay the record's (HandleStore.pushRestored). The two go together:
+ * a loader whose pin the entry lost runs fresh, and the record's copies of
+ * its pushes give way to that run's (restoreHandles).
  */
 
 import type {
@@ -367,17 +369,40 @@ export interface ShellLoaderSeedEntry {
    * hole-free record: a hole-carrying one always runs.
    */
   runs: boolean;
+  /**
+   * The capture that wrote the pin recorded every settled push of the
+   * loader's run in the doc record (CachedEntryData.handleOwners): the pin
+   * carries the `runs` bit, which captures write since they record those
+   * pushes (v0.18). A replay then drops any other settled push of the loader
+   * (HandleStore RecordAuthority "pin"). False for an older pin, whose record
+   * may hold none and leaves them to the run.
+   */
+  complete: boolean;
 }
 
+/**
+ * A pin's loader. A pin is stored under its loader segment id,
+ * `${shortCode}D${index}.${loaderId}` (fresh.ts resolveLoaders), and a
+ * shortCode holds no "D" and no "." (server/context.ts getShortCode: M, L, P,
+ * R, C, I and digits), so the first `D<index>.` ends it. A loader id can hold
+ * both.
+ */
+const PIN_KEY_PREFIX = /^[^D.]*D\d+\./;
+
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane
- * container into a segment-key -> container Map, which serveShellHit assigns
- * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
+ * container into a loader-id -> pin Map, which serveShellHit assigns to the
+ * tail context's `_shellLoaderSeed` (loader-cache.ts servedPins).
  * Lives here so every snapshot family is decoded in this module (the segment
  * family via {@link SeededShellStore}); the loader family is not a store
  * read, so it seeds the context instead of a store.
  *
+ * Keyed by loader, not by the segment a pin was stored under: a loader runs
+ * once per capture, so every segment that registers it pinned the same
+ * container, and the loader's value and its handle pushes are both looked up
+ * by loader. A key that does not parse pins nothing.
+ *
  * Deserializations run in parallel; a record that fails to decode is skipped
  * (that loader drifts — the pre-snapshot behavior — instead of failing the
  * HIT). Returns undefined when the snapshot carries no loader records, without
@@ -396,10 +421,14 @@ export async function buildShellLoaderSeed(
   const entries = await Promise.all(
     loaderRecords.map(
       async (rec): Promise<[string, ShellLoaderSeedEntry] | null> => {
+        const prefix = PIN_KEY_PREFIX.exec(rec.key);
+        if (!prefix) return null;
         try {
-          const stored = rec.value as ShellSnapshotLoaderValue;
+          // Typed as always carrying the bits; an older record lacks them.
+          const stored = rec.value as Partial<ShellSnapshotLoaderValue> &
+            Pick<ShellSnapshotLoaderValue, "value">;
           return [
-            rec.key,
+            rec.key.slice(prefix[0].length),
             {
               container: await deserializeResult(stored.value),
               // A record stored before the bits existed (v0.17) lacks the
@@ -407,6 +436,7 @@ export async function buildShellLoaderSeed(
               // so the loader body supplies them.
               holes: stored.holes !== 0,
               runs: stored.runs !== 0,
+              complete: stored.runs !== undefined,
             },
           ];
         } catch {

package/src/cache/types.ts

@@ -49,6 +49,13 @@ export interface CacheGetResult {
  * The store deals with serialized data - RSC serialization is handled
  * by the cache provider layer.
  *
+ * A store that outlives the process has to keep one build from reading what
+ * other code wrote. The built-in stores prefix their keys with the serving
+ * router's cache versions; a custom store reads the same pair with
+ * `getCacheVersions()` (`@rangojs/router/cache`): `data` for segment entries
+ * and items, `document` for responses and shells, and no version on its
+ * tag-invalidation records, so an invalidation reaches every version.
+ *
  * @typeParam TEnv - Platform bindings type (e.g., Cloudflare env)
  */
 export interface SegmentCacheStore<TEnv = unknown> {
@@ -415,13 +422,14 @@ export interface ShellCacheEntry {
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
   /**
-   * Build version captured at prerender time (the RSC handler's `version` —
-   * the `@rangojs/router:version` build stamp by default, bumped per build and
-   * on dev RSC-module edits). The second read-time gate: a persistent shared
+   * Build version captured at prerender time: the RSC handler's `version`,
+   * which is the router's DOCUMENT version (router-versions.ts) — a hash of
+   * its server code and the client asset names by default, a stamp bumped on
+   * dev RSC-module edits. The second read-time gate: a persistent shared
    * store (KV/runtime-cache) survives deploys, and an app-code change that
    * keeps the same React version would otherwise leave a stale-build
-   * prelude+postponed live under the same key. A custom store returns it as
-   * putShell received it.
+   * prelude+postponed live under the same key. A deploy that changes neither
+   * keeps the entry. A custom store returns it as putShell received it.
    */
   buildVersion: string;
   /**
@@ -761,10 +769,13 @@ export type SegmentHandleData = Record<string, unknown[]>;
  * index (null: not owned). Only a PPR shell capture writes owners: the
  * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
  * the loaders it awaits, and its own cache() replays), which the record keeps
- * because the prelude rendered them. A document HIT restores a bake-lane
- * owner's value through HandleStore.pushRestored, and it stands against a run
- * of its loader there; a live-lane owner's (a hole), and every owner's on
- * any other replay of the record (a client navigation), go through
- * pushReplayed, so a run of the loader replaces it with its live push.
+ * because the prelude rendered them. A restore of the record
+ * (handle-snapshot.ts restoreHandles) keeps an owner's value where the
+ * request serves that loader from the pin stored with the record
+ * (HandleStore.pushRestored: it stands against a run of the loader), on a
+ * document HIT and on a navigation replay alike. Every other owner's value
+ * is a placeholder (pushPlaceholder): a live-lane loader's, and every
+ * owner's where the record has no pin for it. The loader's run, or its own
+ * cache() entry, replaces it.
  */
 export type HandleOwners = Record<string, Record<string, (string | null)[]>>;

package/src/cache/vercel/vercel-cache-store.ts

@@ -23,7 +23,8 @@
  *   3. The platform guardrails: the 2 MB per-item ceiling (oversized writes
  *      silently no-op on Vercel, so we skip + report), the per-item tag cap, and
  *      cross-deploy non-reconciliation (TTL/tag updates are not reconciled across
- *      deployments - bake a build id into `version` or the getCache namespace).
+ *      deployments - every key carries the serving router's cache version, see
+ *      toStoreKey).
  *
  * Dependency stance: this module imports NOTHING from `@vercel/functions`. The
  * runtime cache handle (and `waitUntil`) are injected through the constructor and
@@ -52,6 +53,10 @@ import {
   _getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import {
+  versionKeyPrefix,
+  type KeyVersion,
+} from "../../server/build-version-table.js";
 import { isPerClientSignalHeader } from "../../browser/cookie-name.js";
 import {
   resolveTtl,
@@ -170,6 +175,19 @@ const REVALIDATION_LOCK_MS = 30_000;
  *  the suffix; `rg:` namespaces every Rango entry. `h` is the PPR shell tier. */
 type CacheFamily = "s" | "i" | "r" | "h" | "tm";
 
+/**
+ * Which of the serving router's versions each family's keys carry
+ * (versionKeyPrefix). A tag marker carries none: an invalidation applies to
+ * every version, including one a rollback brings back.
+ */
+const FAMILY_VERSION: Record<CacheFamily, KeyVersion> = {
+  s: "data",
+  i: "data",
+  r: "document",
+  h: "document",
+  tm: null,
+};
+
 /**
  * TTL for tag-invalidation marker entries ("tm" family), written by
  * invalidateTags for isTagsInvalidatedSince (the build-shell read-through,
@@ -177,7 +195,7 @@ type CacheFamily = "s" | "i" | "r" | "h" | "tm";
  * The platform's expireTag() DELETES tagged entries (no queryable
  * history), so the markers are rango's own record of "tag X was invalidated
  * at T". One year: runtime tagged-shell retention is capped to this lifetime,
- * while buildVersion retires build shells on the next deploy. An expired marker
+ * while a build shell is replaced by the next build's. An expired marker
  * therefore cannot resurrect a runtime shell that outlived its invalidation.
  */
 const TAG_MARKER_TTL_SECONDS = 365 * 24 * 60 * 60;
@@ -299,14 +317,20 @@ export type VercelCacheDebug =
 export interface VercelCacheStoreOptions<TEnv = unknown> {
   /**
    * The Vercel Runtime Cache handle - `getCache()` from `@vercel/functions`.
-   * Required. Construct it with a build-hash namespace to bust stale-shaped
-   * entries across deployments, since Vercel does not reconcile TTL/tags between
-   * deploys:
+   * Required.
    *
    * ```ts
    * import { getCache } from "@vercel/functions";
-   * new VercelCacheStore({ cache: getCache({ namespace: BUILD_ID }) });
+   * new VercelCacheStore({ cache: getCache() });
    * ```
+   *
+   * Vercel does not reconcile entries between deployments; the store does it
+   * through its keys, which carry the serving router's cache versions (see
+   * `version`). So a deploy that changes a router's code stops reading that
+   * router's old entries, and a deploy that does not keeps them. A namespace
+   * that changes per deployment (`getCache({ namespace: VERCEL_DEPLOYMENT_ID })`)
+   * still works and clears the cache on every deploy, which is what you want
+   * only if you need that.
    */
   cache: VercelRuntimeCache;
 
@@ -336,9 +360,15 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
   ) => string | Promise<string>;
 
   /**
-   * Build/version id folded into every stored key as `v/{version}/...`. A second
-   * cross-deploy busting layer in addition to (or instead of) the getCache
-   * namespace. Changing it invalidates everything this store wrote previously.
+   * Version override, folded into every versioned key as `v/{version}/...`.
+   * When set, this exact value is used for cached data and stored HTML alike;
+   * changing it makes everything this store wrote before unreachable.
+   *
+   * Leave it unset for the default: the store keys with the versions of the
+   * router serving the request, as CFCacheStore does. Segments and `"use
+   * cache"` items use the router's data version; responses and PPR shells use
+   * its document version (see `createRouter({ version })`). Tag markers are
+   * never versioned, so an invalidation applies to every version.
    */
   version?: string;
 
@@ -447,8 +477,8 @@ function tagStamp(tags: string[]): { ta?: number } {
  * that propagates expireTag rejections does get the strict guarantee, which is
  * what the unit suite exercises.)
  *
- * Key hashing / family isolation. The store namespaces its three value tiers as
- * `rg:{s|i|r}:{key}` so segment, `"use cache"`, and response entries occupy
+ * Key hashing / family isolation. The store namespaces its value tiers as
+ * `rg:{s|i|r|h}:{key}` so segment, `"use cache"`, response and shell entries occupy
  * disjoint keyspaces. That separation is only as strong as the cache's
  * `keyHashFunction`: `getCache`'s default is djb2, which folds every key to 32
  * bits (8 hex chars), so at a large live-key count a collision can let one
@@ -464,11 +494,9 @@ function tagStamp(tags: string[]): { ta?: number } {
  *
  * // One handle per process: getCache() resolves the platform cache on every
  * // call, and the PPR shell and tag-marker memos are kept per handle.
- * // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
- * // would be undefined here) so cross-deploy busting via `version` works.
- * const runtimeCache = getCache({
- *   namespace: process.env.VERCEL_DEPLOYMENT_ID,
- * });
+ * // No deployment id in the namespace: the store's keys carry the serving
+ * // router's cache versions, so a deploy keeps what its code did not change.
+ * const runtimeCache = getCache();
  *
  * export const router = createRouter({
  *   cache: () => ({
@@ -493,7 +521,8 @@ export class VercelCacheStore<
 
   private readonly cache: VercelRuntimeCache;
   private readonly waitUntil?: (promise: Promise<unknown>) => void;
-  private readonly version?: string;
+  /** The `version` option: used for every versioned family when set. */
+  private readonly explicitVersion?: string;
   private readonly maxItemBytes: number;
   private readonly memo: ResolvedShellMemoOptions;
   private readonly handleMemos: VercelHandleMemos;
@@ -518,7 +547,7 @@ export class VercelCacheStore<
     this.waitUntil = options.waitUntil;
     this.defaults = options.defaults;
     this.keyGenerator = options.keyGenerator;
-    this.version = options.version;
+    this.explicitVersion = options.version;
     this.maxItemBytes = options.maxItemBytes ?? VERCEL_MAX_ITEM_BYTES;
     this.maxShellEntryBytes = Math.floor((this.maxItemBytes * 3) / 4);
     this.memo = resolveShellMemoOptions(options.memo, {
@@ -1469,8 +1498,7 @@ export class VercelCacheStore<
   // cross-family one reads as corrupt. See the class doc for passing a wider
   // hash (sha256) when many keys are live.
   private toStoreKey(key: string, family: CacheFamily): string {
-    const versionPrefix = this.version ? `v/${this.version}/` : "";
-    return `${versionPrefix}rg:${family}:${key}`;
+    return `${versionKeyPrefix(this.explicitVersion, FAMILY_VERSION[family])}rg:${family}:${key}`;
   }
 
   private async write(

package/src/client-urls/client-root.tsx

@@ -172,6 +172,7 @@ export function ClientUrlsRoot({
               params: presented.params,
               pathname: presented.pathname,
               search: presented.search,
+              state: presented.state,
             },
           }
         : null,

package/src/client-urls/navigation.ts

@@ -17,6 +17,8 @@ export interface ClientUrlNavigationIntent {
   /** Absolute destination pathname (mount included) and search ("?..." or ""). */
   readonly pathname: string;
   readonly search: string;
+  /** `history.state` the navigation will push (OptimisticLocation.state). */
+  readonly state: unknown;
   /**
    * transition({ when }) gated this navigation off at the swap: the
    * destination presents urgently instead of in a transition lane.
@@ -37,6 +39,8 @@ export interface ClientUrlDestination {
    * params minus these are the mount's (include prefix) params.
    */
   readonly originLocalParamNames: readonly string[];
+  /** `history.state` the navigation will push (ClientUrlNavigationIntent.state). */
+  readonly state: unknown;
 }
 
 interface ActiveClientUrlGroup {
@@ -124,6 +128,8 @@ export function registerClientUrlGroup(
 export function beginClientUrlNavigation(
   targetUrl: URL,
   signal: AbortSignal,
+  /** Builds the entry state; called only when the group presents the target. */
+  buildState?: () => unknown,
   decideTransition?: (destination: ClientUrlDestination) => boolean,
 ): ClientUrlNavigationPresentation | null {
   const group = activeGroup;
@@ -149,6 +155,8 @@ export function beginClientUrlNavigation(
     : undefined;
   if (canonicalName && activeInterceptTargets.has(canonicalName)) return null;
 
+  const state = buildState?.();
+
   // A same-route intent never swaps (ClientUrlsRoot), so transition({ when })
   // decides at the canonical commit; a cross-route one decides here, at the
   // navigation's first presentation.
@@ -163,6 +171,7 @@ export function beginClientUrlNavigation(
       routeName: canonicalName,
       when: typeof when === "function" ? when : undefined,
       originLocalParamNames: Object.keys(originMatch?.params ?? {}),
+      state,
     });
   }
 
@@ -171,6 +180,7 @@ export function beginClientUrlNavigation(
     params: match.params,
     pathname: targetUrl.pathname,
     search: targetUrl.search,
+    state,
     transitionGatedOff,
   };
   group.intent = intent;

package/src/client-urls/optimistic-location.ts

@@ -6,16 +6,22 @@ import { createContext, type Context } from "react";
  * Route identity of an optimistically rendered clientUrls() destination:
  * the values the local trie match produced for the URL the user navigated
  * to. Provided by ClientUrlsRoot around the optimistic branch ONLY, so
- * useParams / usePathname / useSearchParams inside that branch describe the
- * route being rendered while the same hooks in chrome outside it keep the
- * committed location until the canonical response commits (or redirects, in
- * which case the branch — and these values — are discarded).
+ * useParams / usePathname / useSearchParams / useLocationState inside that
+ * branch describe the route being rendered while the same hooks in chrome
+ * outside it keep the committed location until the canonical response commits
+ * (or redirects, in which case the branch — and these values — are discarded).
  */
 export interface OptimisticLocation {
   readonly params: Readonly<Record<string, string>>;
   readonly pathname: string;
   /** Search string including the leading "?" (or ""). */
   readonly search: string;
+  /**
+   * `history.state` the navigation will push: its `state` option, without
+   * what the server adds (that arrives with the canonical commit). History
+   * still holds the entry being left, so useLocationState reads this instead.
+   */
+  readonly state: unknown;
 }
 
 export const OptimisticLocationContext: Context<OptimisticLocation | null> =

package/src/handles/deferred-resolution.ts

@@ -88,9 +88,20 @@ async function resolveValues(values: unknown[]): Promise<unknown[]> {
  * A hung handle promise blocks the full render like any unresolved await (no
  * handle-specific timeout). Partial / action payloads keep streaming via
  * `handleStore.stream()`.
+ *
+ * `recordedOnly` is a PPR shell capture's render (full-payload.ts): the
+ * snapshot is cut down to the pushes the capture's record keeps
+ * (getDataForSegment's `excludeLoaderPushes`, the filter captureHandles
+ * writes the record with). A HIT restores that record and hydrates with it,
+ * so a push the record leaves out must not be in the prelude either: it
+ * rendered an element no HIT's hydration data matched (issue #1035). Which
+ * pushes a record keeps is the capture funnel's decision (shell-capture.ts
+ * deriveShellCaptureContext: today it leaves out a deferred loader push and
+ * one holding a masked promise), not this function's.
  */
 export async function* resolvedHandleStream(
   handleStore: HandleStore,
+  recordedOnly?: boolean,
 ): AsyncGenerator<HandleData, void, unknown> {
   // Drain stream() (NOT getData()) for the converged snapshot: consuming a
   // stream arms the store's late-push guard (LateHandlePushError for pushes
@@ -109,9 +120,29 @@ export async function* resolvedHandleStream(
   for await (const data of handleStore.stream("settled")) {
     snapshot = data;
   }
+  if (recordedOnly) snapshot = recordedHandleData(handleStore, snapshot);
   yield await resolveDeferredHandleValues(snapshot);
 }
 
+/** `snapshot` without the pushes a record leaves out (resolvedHandleStream). */
+function recordedHandleData(
+  handleStore: HandleStore,
+  snapshot: HandleData,
+): HandleData {
+  const segmentIds = new Set<string>();
+  for (const handleName in snapshot) {
+    for (const segmentId in snapshot[handleName]) segmentIds.add(segmentId);
+  }
+  const recorded: HandleData = {};
+  for (const segmentId of segmentIds) {
+    const kept = handleStore.getDataForSegment(segmentId, true);
+    for (const handleName in kept) {
+      (recorded[handleName] ??= {})[segmentId] = kept[handleName];
+    }
+  }
+  return recorded;
+}
+
 /**
  * Resolve the deferred (Promise) values in ONE segment's handle bucket
  * (`handleName -> entries[]`). Same shallow + drop-rejections rule as

package/src/prerender/build-shell-capture.ts

@@ -21,6 +21,7 @@
  */
 
 import type { ShellCacheEntry } from "../cache/types.js";
+import type { RouterVersions } from "../router-versions.js";
 import type { MatchResult } from "../types.js";
 import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
 import {
@@ -105,13 +106,14 @@ export interface BuildShellCaptureOptions {
   /** Build-time env bindings (rango plugin buildEnv), if configured. */
   buildEnv?: unknown;
   /**
-   * The MAIN build's version (the version plugin's value folded into the
-   * shipped worker) — NOT the temp server's own version-plugin value. The
-   * serve-side isValidShellHit gate compares entry.buildVersion against the
-   * running worker's ctx.version; stamping the temp server's would make every
-   * build entry an eternal MISS.
+   * The versions the SHIPPED build serves this router with (the build table,
+   * or the router's consumer-set version) — NOT the temp server's own
+   * version-plugin stamp. The serve-side isValidShellHit gate compares
+   * entry.buildVersion against the running worker's ctx.version, which is the
+   * document version; stamping the temp server's would make every build entry
+   * an eternal MISS.
    */
-  buildVersion: string;
+  versions: RouterVersions;
   /**
    * The SSR half, composed by the plugin from the temp server's SSR
    * environment runner (react-dom/static prerender + Flight client), with the
@@ -192,7 +194,7 @@ async function attemptBuildCapture(
     cacheStore: new MemorySegmentCacheStore(),
     themeConfig: router.themeConfig ?? null,
     stateCookieName: router.resolvedStateCookieName,
-    version: opts.buildVersion,
+    versions: opts.versions,
   });
   // Scope registry lookups (root-scope/search-schema) per router during the
   // bake, mirroring rsc/handler.ts on the request path (#762).
@@ -215,7 +217,7 @@ async function attemptBuildCapture(
 
   const descriptor: ShellCaptureDescriptor = {
     key: opts.key,
-    buildVersion: opts.buildVersion,
+    buildVersion: opts.versions.document,
     ttl: opts.ttl,
     swr: opts.swr,
     tags: opts.tags,
@@ -448,7 +450,7 @@ async function runBuildCaptureFinal(
         // buildFullPayload reads only ctx.router.* and ctx.version.
         {
           router,
-          version: opts.buildVersion,
+          version: opts.versions.document,
         } as unknown as HandlerContext<any>,
         url,
         derivedCtx,

package/src/router/manifest.ts

@@ -38,6 +38,8 @@ const MODULE_LOAD_FAILURE = Symbol.for("rango.moduleLoadFailure");
 // LP1 in docs/internal/matching-and-lazy-discovery.md. VERSION comes from the
 // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
+// Dev module generation only: in production VERSION is constant per process, so
+// the per-router cache versions play no part in this cache.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();
 
 /**

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

@@ -91,15 +91,14 @@
  *   - Request object
  *   - Action context (if POST)
  */
-import type { InternalHandlerContext, ResolvedSegment } from "../../types.js";
-import type { OwnedPushDelivery } from "../../cache/handle-snapshot.js";
-import type { EntryData } from "../../server/context.js";
+import type { ResolvedSegment } from "../../types.js";
+import { isPprEntry, type EntryData } from "../../server/context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
 import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import { treeHasStreaming } from "./segment-resolution.js";
-import { liveLaneLoaderIds } from "../segment-resolution/loader-cache.js";
+import { loaderPins } from "../segment-resolution/loader-cache.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
 import {
   _getRequestContext,
@@ -546,20 +545,14 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    // A record's loader-owned handle values claim their loader, so its own
-    // cache() HIT does not replay them again (restoreHandles). A document
-    // HIT tail restores a bake-lane owner's values as the prelude's, unclaimed:
-    // they stand against any later push of that loader
-    // (HandleStore.pushRestored). An owner the route runs on the live lane is
-    // a hole, so its live run still replaces them, even inside a restored
-    // loader's body.
-    const ownedPushes: OwnedPushDelivery = {
-      claim: (ctx.handlerContext as InternalHandlerContext)._claimLoaderPushes,
-    };
-    if (tailMarker) {
-      ownedPushes.liveLane = liveLaneLoaderIds(ctx.entries);
-      ownedPushes.restore = tailMarker.docTail === true;
-    }
+    // Only a ppr route's records hold loader pushes, and only its shell pins
+    // loaders (CachedEntryData.handleOwners, the loader seed): any other
+    // route's record restores as a plain replay.
+    const leaf = ctx.entries[ctx.entries.length - 1];
+    const ownedPushes =
+      leaf !== undefined && isPprEntry(leaf)
+        ? () => loaderPins(ctx.entries, pipelineReqCtx)
+        : undefined;
     const explicitLookup = await ctx.cacheScope.lookupRouteDetailed(
       ctx.pathname,
       ctx.matched.params,

package/src/router/navigation-snapshot.ts

@@ -38,12 +38,31 @@ export interface ResolveNavigationDeps {
  * never produce a partial match, so the replay path must decide
  * `no-navigation-context` BEFORE spending shell-store reads — the two
  * predicates drifting apart would misattribute the bypass again.
+ *
+ * `requestOrigin` is the origin pathname matching uses (`url.origin`), which
+ * may not be `request.url`'s. `X-RSC-Router-Client-Path` is returned as sent.
+ * A Referer counts only when it resolves against that origin and stays there.
+ * A cross-origin Referer is dropped: resolveNavigation matches only the
+ * pathname, so a foreign URL would be treated as a route on this app. A value
+ * that does not parse is no context either.
  */
-export function getNavigationContextHeader(request: Request): string | null {
-  return (
-    requestHeaders(request).get("X-RSC-Router-Client-Path") ||
-    requestHeaders(request).get("Referer")
-  );
+export function getNavigationContextHeader(
+  request: Request,
+  requestOrigin: string,
+): string | null {
+  const headers = requestHeaders(request);
+  const clientPath = headers.get("X-RSC-Router-Client-Path");
+  if (clientPath) return clientPath;
+
+  const referer = headers.get("Referer");
+  if (!referer) return null;
+
+  try {
+    if (new URL(referer, requestOrigin).origin !== requestOrigin) return null;
+  } catch {
+    return null;
+  }
+  return referer;
 }
 
 /**
@@ -84,7 +103,7 @@ export async function resolveNavigation(
   const clientSegmentIds =
     url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get("_rsc_stale") === "true";
-  const previousUrl = getNavigationContextHeader(request);
+  const previousUrl = getNavigationContextHeader(request, url.origin);
   const interceptSourceUrl = getInterceptSourceHeader(request);
   const isHmr = !!requestHeaders(request).get("X-RSC-HMR");
 

package/src/router/request-classification.ts

@@ -170,6 +170,21 @@ export async function classifyRequest<TEnv = any>(
   const willFullRender =
     !isAction && !isLoaderFetch && !isPartialReq && !isPeRender;
 
+  // Before the version check: each router has its own version, so a tab of
+  // another app always carries one this router does not have. That request is
+  // an app switch, not a stale client.
+  const clientRouterId = url.searchParams.get("_rsc_rid");
+  if (
+    clientRouterId &&
+    clientRouterId !== deps.routerId &&
+    url.searchParams.has("_rsc_partial")
+  ) {
+    return {
+      mode: "app-switch",
+      reloadUrl: stripInternalParams(url).toString(),
+    };
+  }
+
   const clientVersion = url.searchParams.get("_rsc_v");
   if (
     deps.routerVersion &&
@@ -195,18 +210,6 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  const clientRouterId = url.searchParams.get("_rsc_rid");
-  if (
-    clientRouterId &&
-    clientRouterId !== deps.routerId &&
-    url.searchParams.has("_rsc_partial")
-  ) {
-    return {
-      mode: "app-switch",
-      reloadUrl: stripInternalParams(url).toString(),
-    };
-  }
-
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,

package/src/router/router-interfaces.ts

@@ -457,7 +457,8 @@ export interface RangoInternal<
   readonly nonce?: NonceProvider<TEnv>;
 
   /**
-   * RSC version string
+   * 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;