@rangojs/router 0.0.0-experimental.116 → 0.0.0-experimental.118

package/src/browser/partial-update.ts

@@ -61,13 +61,6 @@ export interface PartialUpdateConfig {
   ) => Promise<ReactNode> | ReactNode;
   /** RSC version getter — returns the current version (may change after HMR) */
   getVersion?: () => string | undefined;
-  /**
-   * Replace the active app-shell when a cross-app navigation is detected.
-   * Called before the full-update tree replacement renders, so the new
-   * payload's rootLayout, basename, and version are picked up. Theme,
-   * warmup, and prefetch TTL are not part of the shell — see AppShell.
-   */
-  applyAppShell?: (next: import("./app-shell.js").AppShell) => void;
 }
 
 /**
@@ -137,7 +130,6 @@ export function createPartialUpdater(
     onUpdate,
     renderSegments,
     getVersion = () => undefined,
-    applyAppShell,
   } = config;
 
   /**
@@ -245,30 +237,25 @@ export function createPartialUpdater(
       streamingToken.end();
     });
 
-    // Detect app switch: if routerId changed, the navigation crossed into
-    // a different router (e.g., via host router path mount). Downgrade
-    // partial to full so the entire tree is replaced without reconciliation
-    // against stale segments from the previous app, and replace the app
-    // shell (rootLayout, basename, version) so the target app's document
-    // and router config take effect instead of remaining captured from the
-    // initial load. Theme, warmup, and prefetch TTL are intentionally
-    // document-lifetime (see AppShell doc); a new document navigation
-    // applies them.
-    if (payload.metadata?.routerId) {
-      const prevRouterId = store.getRouterId?.();
-      if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
-        debugLog(
-          `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
-        );
-        payload.metadata.isPartial = false;
-        applyAppShell?.({
-          routerId: payload.metadata.routerId,
-          rootLayout: payload.metadata.rootLayout,
-          basename: payload.metadata.basename,
-          version: payload.metadata.version,
-        });
-      }
-      store.setRouterId?.(payload.metadata.routerId);
+    // Integrity guard (defense in depth). The server redirects on a cross-app
+    // routerId mismatch (X-RSC-Reload), so a partial payload's routerId must
+    // match this client's. If it doesn't — a stale/edge cache keyed without the
+    // routerId, a proxy mixing app responses, or a server classification bug —
+    // do NOT splice a foreign app's segments and client references into this
+    // document. Force a full reload so the server re-establishes the
+    // authoritative document for this URL.
+    const currentRouterId = store.getRouterId?.();
+    if (
+      payload.metadata?.routerId &&
+      currentRouterId &&
+      payload.metadata.routerId !== currentRouterId
+    ) {
+      console.error(
+        `[rango] Partial response router id "${payload.metadata.routerId}" does not ` +
+          `match this client ("${currentRouterId}"); discarding it and reloading to re-sync.`,
+      );
+      window.location.href = url;
+      return;
     }
 
     // Handle server-side redirect with state

package/src/browser/prefetch/cache.ts

@@ -1,8 +1,13 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetched Response objects for instant cache hits
- * on subsequent navigation. Two key scopes are in play:
+ * In-memory cache storing eagerly-decoded prefetch payloads for instant,
+ * already-warm cache hits on subsequent navigation. A prefetch fetches the
+ * RSC partial AND decodes it (createFromFetch) up front — decoding the Flight
+ * stream resolves the route's client references, so the route's JS chunks are
+ * imported during prefetch rather than on click. The decoded payload is reused
+ * verbatim by navigation, so a prefetched click loads no new code. Two key
+ * scopes are in play:
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
  *   invalidated automatically when Rango state bumps (deploy or
@@ -17,8 +22,8 @@
  *   from other pages.
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
- * navigation branch of a tee'd Response, allowing navigation to adopt a
- * still-downloading prefetch without reparsing or buffering the body. A
+ * decoded prefetch entry (or null), letting navigation adopt a
+ * still-downloading prefetch without issuing a duplicate request. A
  * single promise can be registered under multiple alias keys (see
  * `setInflightPromiseWithAliases`) so same-source navigations adopt via
  * their source key while cross-source ones fall through to the wildcard
@@ -30,6 +35,31 @@
 
 import { abortAllPrefetches } from "./queue.js";
 import { invalidateRangoState } from "../rango-state.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
+ * payload (not the raw Response) is what makes a prefetched navigation "warm":
+ * decoding the Flight stream during prefetch pulls the route's client chunks,
+ * so the click reuses ready elements and loads no new JS.
+ */
+export interface DecodedPrefetch {
+  /** The eagerly-decoded RSC payload. Reused verbatim by navigation. */
+  payload: Promise<RscPayload>;
+  /**
+   * Resolves when the underlying RSC stream finishes draining. Navigation
+   * forwards this as its streamComplete so scroll/revalidation gating is
+   * unchanged from the fresh-fetch path.
+   */
+  streamComplete: Promise<void>;
+  /**
+   * Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
+   * `"source"` means the response is source-page-sensitive and must not be
+   * reused by a navigation from a different page — navigation enforces this
+   * when it adopted an inflight entry through the wildcard key.
+   */
+  scope: "source" | "wildcard";
+}
 
 // Default TTL: 5 minutes. Overridden by initPrefetchCache() with
 // the server-configured prefetchCacheTTL from router options.
@@ -55,7 +85,7 @@ export function isPrefetchCacheDisabled(): boolean {
 const MAX_PREFETCH_CACHE_SIZE = 50;
 
 interface PrefetchCacheEntry {
-  response: Response;
+  entry: DecodedPrefetch;
   timestamp: number;
 }
 
@@ -63,20 +93,37 @@ const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
 /**
- * In-flight promise map. When a prefetch fetch is in progress, its
- * Promise<Response | null> is stored here so navigation can await
- * it instead of starting a duplicate request.
+ * In-flight promise map. When a prefetch fetch+decode is in progress, its
+ * Promise<DecodedPrefetch | null> is stored here so navigation can await it
+ * instead of starting a duplicate request. Resolves to null when the prefetch
+ * failed, was aborted, or carried a control header (reload/redirect) that the
+ * navigation must re-fetch to act on.
  */
-const inflightPromises = new Map<string, Promise<Response | null>>();
+const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
 
 /**
  * Alias map for in-flight promises registered under multiple keys (see
  * dual inflight in prefetch/fetch.ts). Records each key's sibling set so
  * that consuming or clearing any one key atomically removes every alias —
- * guaranteeing a single consumer for the shared Response stream.
+ * guaranteeing a single consumer for the shared decode.
  */
 const inflightAliases = new Map<string, string[]>();
 
+/**
+ * Keys whose in-flight prefetch promise was adopted by a navigation (via
+ * `consumeInflightPrefetch`). A `DecodedPrefetch` carries a single-use
+ * `metadata.handles` async generator; the adopter drains it. The same entry is
+ * also published to the `cache` map by `storePrefetch` when the fetch resolves
+ * — which runs AFTER adoption (adoption only succeeds while the fetch is still
+ * in flight, so the entry is not yet cached). Without this guard the adopted,
+ * now-drained entry would be left in the cache and served to a later navigation
+ * whose handle generator yields nothing, silently dropping that route's
+ * breadcrumbs. Recording the adopted keys lets `storePrefetch` skip publishing
+ * them, keeping the existing one-time-consumption contract (a consumed prefetch
+ * is gone; the next navigation re-fetches).
+ */
+const adoptedKeys = new Set<string>();
+
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
 // started before a clear carry a stale generation and must not store their
 // response (the data may be stale due to a server action invalidation).
@@ -152,14 +199,14 @@ export function hasPrefetch(key: string): boolean {
 }
 
 /**
- * Consume a cached prefetch response. Returns null if not found or expired.
- * One-time consumption: the entry is deleted after retrieval.
+ * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
+ * expired. One-time consumption: the entry is deleted after retrieval.
  * Returns null when caching is disabled (TTL <= 0).
  *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
- * for that (returns a Promise instead of a Response).
+ * for that (returns a Promise instead of a resolved entry).
  */
-export function consumePrefetch(key: string): Response | null {
+export function consumePrefetch(key: string): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
   const entry = cache.get(key);
   if (!entry) return null;
@@ -168,13 +215,14 @@ export function consumePrefetch(key: string): Response | null {
     return null;
   }
   cache.delete(key);
-  return entry.response;
+  return entry.entry;
 }
 
 /**
  * Consume an in-flight prefetch promise. Returns null if no prefetch is
- * in-flight for this key. The returned Promise resolves to the buffered
- * Response (or null if the fetch failed/was aborted).
+ * in-flight for this key. The returned Promise resolves to the decoded
+ * prefetch entry (or null if the fetch failed/was aborted, or carried a
+ * control header the navigation must re-fetch to honor).
  *
  * One-time consumption: the promise entry is removed (along with any
  * sibling aliases registered via `setInflightPromiseWithAliases`) so a
@@ -188,38 +236,51 @@ export function consumePrefetch(key: string): Response | null {
  */
 export function consumeInflightPrefetch(
   key: string,
-): Promise<Response | null> | null {
+): Promise<DecodedPrefetch | null> | null {
   const promise = inflightPromises.get(key);
   if (!promise) return null;
   // Remove the promise under every alias so a second consumer cannot
-  // adopt the same stream and race on the body. `inflightAliases` is
-  // intentionally preserved — `clearPrefetchInflight()` in the fetch's
-  // `.finally()` still needs it to clear every inflight flag; deleting
-  // here would strand the sibling's flag forever.
-  forEachAlias(key, (k) => inflightPromises.delete(k));
+  // adopt the same stream and race on the body, and mark every alias as
+  // adopted so the pending `storePrefetch` (which resolves later, after this
+  // adoption) does not leave the now-owned, single-use entry in the cache map.
+  // `inflightAliases` is intentionally preserved — `clearPrefetchInflight()` in
+  // the fetch's `.finally()` still needs it to clear every inflight flag and
+  // adopted marker; deleting here would strand the sibling's flag forever.
+  forEachAlias(key, (k) => {
+    inflightPromises.delete(k);
+    adoptedKeys.add(k);
+  });
   return promise;
 }
 
 /**
- * Store a prefetch response in the in-memory cache.
- * The response should be a clone() of the original so the caller can
- * still consume the body. The clone's body streams independently.
+ * Store an eagerly-decoded prefetch in the in-memory cache.
  *
  * Skips storage if the generation has changed since the fetch started
  * (a server action invalidated the cache mid-flight).
  */
 export function storePrefetch(
   key: string,
-  response: Response,
+  entry: DecodedPrefetch,
   fetchGeneration: number,
 ): void {
   if (cacheTTL <= 0) return;
   if (fetchGeneration !== generation) return;
 
+  // If a navigation already adopted this prefetch's in-flight promise, it owns
+  // the single-use entry (and has drained its handle generator). Do NOT also
+  // publish it to the cache map, or a later navigation would be served the
+  // exhausted entry and lose that route's handles. Clear the marker (under all
+  // aliases) now that the decision is made.
+  if (adoptedKeys.has(key)) {
+    forEachAlias(key, (k) => adoptedKeys.delete(k));
+    return;
+  }
+
   // Evict expired entries
   const now = Date.now();
-  for (const [k, entry] of cache) {
-    if (now - entry.timestamp > cacheTTL) {
+  for (const [k, cached] of cache) {
+    if (now - cached.timestamp > cacheTTL) {
       cache.delete(k);
     }
   }
@@ -230,7 +291,7 @@ export function storePrefetch(
     if (oldest) cache.delete(oldest);
   }
 
-  cache.set(key, { response, timestamp: now });
+  cache.set(key, { entry, timestamp: now });
 }
 
 /**
@@ -250,7 +311,7 @@ export function markPrefetchInflight(key: string): void {
  */
 export function setInflightPromise(
   key: string,
-  promise: Promise<Response | null>,
+  promise: Promise<DecodedPrefetch | null>,
 ): void {
   inflightPromises.set(key, promise);
 }
@@ -263,7 +324,7 @@ export function setInflightPromise(
  */
 export function setInflightPromiseWithAliases(
   keys: string[],
-  promise: Promise<Response | null>,
+  promise: Promise<DecodedPrefetch | null>,
 ): void {
   for (const k of keys) {
     inflightPromises.set(k, promise);
@@ -276,6 +337,9 @@ export function clearPrefetchInflight(key: string): void {
     inflight.delete(k);
     inflightPromises.delete(k);
     inflightAliases.delete(k);
+    // Clear any adopted marker too, so a fetch that failed before storePrefetch
+    // (the marker's normal consumer) does not strand it across the next prefetch.
+    adoptedKeys.delete(k);
   });
 }
 
@@ -292,23 +356,8 @@ export function clearPrefetchCache(): void {
   inflight.clear();
   inflightPromises.clear();
   inflightAliases.clear();
+  adoptedKeys.clear();
   cache.clear();
   abortAllPrefetches();
   invalidateRangoState();
 }
-
-/**
- * Drop all in-memory prefetch state for this tab without rotating rango-state.
- *
- * Use for local-only invalidations (e.g. app switch in this tab) where
- * other tabs should NOT observe a state rotation. Unlike clearPrefetchCache,
- * does not call invalidateRangoState, so the shared X-Rango-State token
- * stays intact and siblings in the old app keep their prefetches.
- */
-export function clearPrefetchCacheLocal(): void {
-  generation++;
-  inflight.clear();
-  inflightPromises.clear();
-  cache.clear();
-  abortAllPrefetches();
-}

package/src/browser/prefetch/fetch.ts

@@ -3,12 +3,16 @@
  *
  * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
  * and useRouter().prefetch(). Sends the same headers and segment IDs as a
- * real navigation so the server returns a proper diff. The Response is fully
- * buffered and stored in an in-memory cache for instant consumption on
- * subsequent navigation.
+ * real navigation so the server returns a proper diff. The response is fetched
+ * AND eagerly decoded (createFromFetch) up front: decoding the Flight stream
+ * resolves the route's client references, so the route's JS chunks are imported
+ * during prefetch rather than on click. The decoded payload is stored in an
+ * in-memory cache and reused verbatim by navigation, so a prefetched click
+ * loads no new code.
  *
  * In-flight promises are tracked in the cache so that navigation can reuse
- * a prefetch that is still downloading instead of starting a duplicate request.
+ * a prefetch that is still downloading/decoding instead of starting a
+ * duplicate request.
  */
 
 import {
@@ -20,11 +24,34 @@ import {
   storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
+  type DecodedPrefetch,
 } from "./cache.js";
 import { getRangoState } from "../rango-state.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
 import { debugLog } from "../logging.js";
+import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * Decoder injected at app startup (see setPrefetchDecoder). This is
+ * `deps.createFromFetch` — decoupled from the RSC runtime exactly like the
+ * navigation client. Prefetch decodes through it so the route's client chunks
+ * are pulled during the prefetch, not on click.
+ */
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+
+let decoder: PrefetchDecoder | null = null;
+
+/**
+ * Wire the RSC decoder used to eagerly decode prefetched responses. Called
+ * once from initBrowserApp with the same createFromFetch the navigation client
+ * uses. Until set, prefetch warming is inert (prefetches are skipped) — the
+ * browser app always sets it before any Link can fire.
+ */
+export function setPrefetchDecoder(fn: PrefetchDecoder): void {
+  decoder = fn;
+}
 
 /**
  * Check if a URL resolves to the current page (same pathname + search).
@@ -78,39 +105,50 @@ function buildPrefetchUrl(
 }
 
 /**
- * Core prefetch fetch logic. Fetches the response, tees the body, and stores
- * one branch in the in-memory cache. The returned Promise resolves to the
- * sibling navigation branch (or null on failure) so navigation can safely
- * reuse an in-flight prefetch via consumeInflightPrefetch().
+ * Core prefetch fetch logic. Fetches the response, eagerly decodes it, and
+ * stores the decoded payload in the in-memory cache. The returned Promise
+ * resolves to the decoded entry (or null on failure / control header) so
+ * navigation can safely reuse an in-flight prefetch via
+ * consumeInflightPrefetch().
+ *
+ * Eager decode is the warming step: createFromFetch parses the Flight stream,
+ * which resolves the route's client references and imports its JS chunks. The
+ * stored payload is reused as-is by navigation, so the click loads no new code.
+ *
+ * Control headers are NOT acted on here. A speculative prefetch must never
+ * reload the page or throw a redirect — if the response carries X-RSC-Reload
+ * or X-RSC-Redirect, we drop it (resolve null) and let the real navigation
+ * re-fetch and honor it.
  *
  * Inflight + storage key selection:
  *
  * - `forceSourceScope` (Link opted in with `prefetchKey=":source"`): single
- *   inflight registration under `sourceKey`; response stored under
- *   `sourceKey`. No wildcard leak is possible.
+ *   inflight registration under `sourceKey`; entry stored under `sourceKey`.
+ *   No wildcard leak is possible.
  *
  * - Otherwise: dual inflight registration under both `wildcardKey` and
  *   `sourceKey` so same-source navigations adopt directly via their own
  *   source key. Storage key is chosen at response time from the
  *   `X-RSC-Prefetch-Scope` header — `"source"` → `sourceKey` (intercept
- *   modals etc.), anything else → `wildcardKey`. Cross-source navigations
- *   that adopted via `wildcardKey` must bail out in `navigation-client.ts`
- *   if the adopted response turns out to be source-scoped.
+ *   modals etc.), anything else → `wildcardKey`. The entry records its scope
+ *   so cross-source navigations that adopted via `wildcardKey` can bail out
+ *   in `navigation-client.ts` when the adopted entry turns out source-scoped.
  */
 function executePrefetchFetch(
   wildcardKey: string,
   sourceKey: string,
   fetchUrl: string,
   forceSourceScope: boolean,
+  expectedRouterId?: string,
   signal?: AbortSignal,
-): Promise<Response | null> {
+): Promise<DecodedPrefetch | null> {
   const gen = currentGeneration();
   const inflightKeys = forceSourceScope
     ? [sourceKey]
     : [wildcardKey, sourceKey];
   for (const k of inflightKeys) markPrefetchInflight(k);
 
-  const promise: Promise<Response | null> = fetch(fetchUrl, {
+  const promise: Promise<DecodedPrefetch | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
     signal,
     headers: {
@@ -120,25 +158,53 @@ function executePrefetchFetch(
     },
   })
     .then((response) => {
-      if (!response.ok) return null;
-      // Don't buffer with arrayBuffer() — that blocks until the entire
-      // body downloads, defeating streaming for slow loaders.
-      // Tee the body: one branch for navigation, one for cache storage.
-      const [navStream, cacheStream] = response.body!.tee();
-      const responseInit = {
-        headers: response.headers,
-        status: response.status,
-        statusText: response.statusText,
-      };
-      let storageKey: string;
-      if (forceSourceScope) {
-        storageKey = sourceKey;
-      } else {
-        const scope = response.headers.get("x-rsc-prefetch-scope");
-        storageKey = scope === "source" ? sourceKey : wildcardKey;
+      if (!response.ok || !decoder) return null;
+      // Control headers mean this response is stale (reload) or redirecting.
+      // Don't warm it — drop so navigation re-fetches and acts on the header.
+      if (
+        response.headers.has("X-RSC-Reload") ||
+        response.headers.has("X-RSC-Redirect")
+      ) {
+        return null;
       }
-      storePrefetch(storageKey, new Response(cacheStream, responseInit), gen);
-      return new Response(navStream, responseInit);
+      // Integrity check: never warm (or decode/import the chunks of) a foreign
+      // app's payload. A speculative prefetch must never reload — just drop it;
+      // navigation re-fetches and the server steers it.
+      if (isForeignRouterId(response, expectedRouterId)) {
+        return null;
+      }
+
+      const scope: "source" | "wildcard" =
+        forceSourceScope ||
+        response.headers.get("x-rsc-prefetch-scope") === "source"
+          ? "source"
+          : "wildcard";
+      const storageKey = scope === "source" ? sourceKey : wildcardKey;
+
+      // Track stream completion off a tee so navigation's scroll/revalidation
+      // gating matches the fresh-fetch path; decode the other branch.
+      let resolveStreamComplete!: () => void;
+      const streamComplete = new Promise<void>((resolve) => {
+        resolveStreamComplete = resolve;
+      });
+      const tracked = teeWithCompletion(
+        response,
+        () => resolveStreamComplete(),
+        signal,
+        // Speculative prefetch: a never-consumed/aborted stream error is benign.
+        true,
+      );
+
+      // Eager decode: parsing the Flight stream imports the route's client
+      // chunks now, not on click.
+      const payload = decoder(Promise.resolve(tracked));
+      // Mark handled so an unconsumed prefetch decode error stays quiet; the
+      // error is still surfaced to navigation if it consumes the entry.
+      payload.catch(() => {});
+
+      const entry: DecodedPrefetch = { payload, streamComplete, scope };
+      storePrefetch(storageKey, entry, gen);
+      return entry;
     })
     .catch(() => null)
     .finally(() => {
@@ -223,6 +289,7 @@ export function prefetchDirect(
     sourceKey,
     targetUrl.toString(),
     forceSourceScope,
+    routerId,
   );
 }
 
@@ -275,6 +342,7 @@ export function prefetchQueued(
       sourceKey,
       fetchUrlStr,
       forceSourceScope,
+      routerId,
       signal,
     ).then(() => {});
   });

package/src/browser/rango-state.ts

@@ -13,9 +13,9 @@
  * Storage key is namespaced per routerId (`rango-state:{routerId}`) so
  * tabs in different apps on the same origin do not collide. Two tabs in
  * the same app share a key → one tab's invalidation is picked up by the
- * other via the `storage` event. A smooth cross-app transition in this
- * tab rebinds to the target app's key; other tabs still in the old app
- * keep their own key intact.
+ * other via the `storage` event. The key is bound once at document init; a
+ * cross-app navigation is a full document load (X-RSC-Reload), so the target
+ * app's document binds its own key on load (tabs in the old app keep theirs).
  *
  * If no routerId is supplied, falls back to a single legacy key for
  * backward compatibility (single-app deployments unaffected).
@@ -31,10 +31,9 @@ function buildStorageKey(routerId: string | undefined): string {
 // Initialized from localStorage on first access or by initRangoState().
 let cachedState: string | null = null;
 
-// The localStorage key this tab is currently bound to. Rebinds on
-// initRangoState (document boot) and setRangoStateLocal (smooth app
-// switch). The storage listener filters cross-tab events by this key so
-// events from tabs in a different app are ignored.
+// The localStorage key this tab is currently bound to. Bound on
+// initRangoState (document boot). The storage listener filters cross-tab
+// events by this key so events from tabs in a different app are ignored.
 let currentStorageKey: string = LEGACY_STORAGE_KEY;
 
 // Cross-tab sync: the `storage` event fires in OTHER tabs when one tab writes
@@ -114,21 +113,6 @@ export function getRangoState(): string {
   return "0:0";
 }
 
-/**
- * Update the in-memory rango-state to a new version WITHOUT writing
- * localStorage. Intended for smooth cross-app transitions in this tab only:
- * subsequent requests from this tab send the new token, but other tabs
- * still in the previous app do not observe a storage event. Rebinds this
- * tab's storage key to the target app's namespace (`rango-state:{routerId}`)
- * so subsequent storage events only reflect the new app. On the next hard
- * reload, initRangoState reconciles localStorage from the server's
- * authoritative version.
- */
-export function setRangoStateLocal(version: string, routerId?: string): void {
-  currentStorageKey = buildStorageKey(routerId);
-  cachedState = `${version}:${Date.now()}`;
-}
-
 /**
  * Invalidate the Rango state key. Called when server actions mutate data.
  * Updates the timestamp portion while keeping the version prefix.

package/src/browser/react/NavigationProvider.tsx

@@ -157,9 +157,11 @@ export interface NavigationProviderProps {
   basename?: string;
 
   /**
-   * Live app-shell ref. When provided, the context's `basename` and `version`
-   * properties become live getters that track app-switch updates without
-   * invalidating the memoized context value.
+   * App-shell ref. When provided, the context's `basename` and `version` are
+   * read through it (live getters) so they don't close over a stale snapshot or
+   * invalidate the memoized context value. The shell is set once at init and is
+   * not swapped within a session — a cross-app navigation is a full document
+   * load (X-RSC-Reload), so the target app establishes its own shell on load.
    */
   appShellRef?: AppShellRef;
 }
@@ -218,8 +220,9 @@ export function NavigationProvider({
   }, []);
 
   // basename/version are always read through a shell ref so the context value
-  // has a single shape: a supplied appShellRef stays live (app-switch updates
-  // it), the standalone fallback is a frozen ref over the mount-time props.
+  // has a single shape. Both are set once: a supplied appShellRef is seeded
+  // from the init payload (a cross-app navigation reloads, so it is not swapped
+  // in-session), and the standalone fallback wraps the mount-time props.
   const fallbackShellRef = useRef<AppShellRef | null>(null);
   if (!fallbackShellRef.current) {
     fallbackShellRef.current = createAppShellRef({ basename, version });
@@ -436,10 +439,10 @@ export function NavigationProvider({
   let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
 
   // Wrap with ThemeProvider when theme is enabled. The ThemeProvider is
-  // document-lifetime: its config comes from the initial load and does NOT
-  // swap on cross-app transitions, because the ThemeProvider sits above the
-  // segment tree and a smooth (no-reload) app switch cannot safely remount
-  // it. A new theme config only takes effect on a full document load.
+  // document-lifetime: its config comes from the initial load and persists for
+  // the session. It sits above the segment tree and is not remounted in-session;
+  // a cross-app navigation is a full document load (X-RSC-Reload), so the target
+  // app's theme config takes effect on its own load.
   if (themeConfig) {
     content = (
       <ThemeProvider config={themeConfig} initialTheme={initialTheme}>

package/src/browser/react/use-router.ts

@@ -13,9 +13,10 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  * useRouter() do not re-render on navigation state changes.
  * For reactive navigation state, use useNavigation() instead.
  *
- * Methods read `basename` from the live context on each call so that
- * cross-app navigation (app-switch) sees the current app's basename
- * rather than the one captured at mount time.
+ * Methods read `basename` from the context on each call. It is set once from
+ * the initial payload and is stable within a session — a cross-app navigation
+ * is a full document load (X-RSC-Reload), so the target app mounts fresh with
+ * its own basename.
  *
  * @example
  * ```tsx