@rangojs/router 0.0.0-experimental.31 → 0.0.0-experimental.3232cd17

package/src/browser/navigation-bridge.ts

@@ -4,12 +4,21 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.js";
+import { isActionFenceActive } from "./action-fence.js";
+import { getRangoState } from "./rango-state.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  handleNavigationStart,
+  handleNavigationEnd,
+  ensureHistoryKey,
+} from "./scroll-restoration.js";
 
 // addTransitionType is only available in React experimental
 const addTransitionType: ((type: string) => void) | undefined =
@@ -18,7 +27,6 @@ const addTransitionType: ((type: string) => void) | undefined =
 import { setupLinkInterception } from "./link-interceptor.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { generateHistoryKey } from "./navigation-store.js";
-import { handleNavigationEnd } from "./scroll-restoration.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
@@ -35,11 +43,6 @@ if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
 
-/** Get IDs of non-loader segments (layouts, routes, parallels). */
-function getNonLoaderSegmentIds(segments: ResolvedSegment[]): string[] {
-  return segments.filter((s) => s.type !== "loader").map((s) => s.id);
-}
-
 export { createNavigationTransaction };
 
 /**
@@ -47,7 +50,7 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
+  /** RSC version from initial payload metadata. */
   version?: string;
 }
 
@@ -67,8 +70,8 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments, version } =
-    config;
+  const { store, client, eventController, onUpdate, renderSegments } = config;
+  let version = config.version;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -76,7 +79,7 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
   });
 
   return {
@@ -114,6 +117,81 @@ export function createNavigationBridge(
         return;
       }
 
+      // Shallow navigation: skip RSC fetch when revalidate is false
+      // and the pathname hasn't changed (search param / hash only change).
+      if (
+        options?.revalidate === false &&
+        targetUrl.pathname === new URL(window.location.href).pathname
+      ) {
+        // Preserve intercept context from the current history entry so that
+        // popstate uses the correct cache key (:intercept suffix) and restores
+        // the right full-page vs modal semantics.
+        const currentHistoryState = window.history.state;
+        const isIntercept = currentHistoryState?.intercept === true;
+        const interceptSourceUrl = isIntercept
+          ? currentHistoryState?.sourceUrl
+          : undefined;
+
+        const historyKey = generateHistoryKey(url, { intercept: isIntercept });
+
+        // Copy current segments to the new history key so back/forward restores instantly
+        const currentKey = store.getHistoryKey();
+        const currentCache = store.getCachedSegments(currentKey);
+        if (currentCache?.segments) {
+          const currentHandleData = eventController.getHandleState().data;
+          store.cacheSegmentsForHistory(
+            historyKey,
+            currentCache.segments,
+            currentHandleData,
+          );
+        }
+
+        // Save current scroll position before changing URL
+        handleNavigationStart();
+
+        // Snapshot old state before pushState/replaceState overwrites it
+        const oldState = window.history.state;
+
+        // Update browser URL (carry intercept context into history state)
+        const historyState = buildHistoryState(
+          resolvedState,
+          {
+            intercept: isIntercept || undefined,
+            sourceUrl: interceptSourceUrl,
+          },
+          {},
+        );
+        pushHistoryWithIdx(historyState, url, options?.replace ?? false);
+
+        // Ensure new history entry has a scroll restoration key
+        ensureHistoryKey();
+
+        // Notify useLocationState() hooks when state changes
+        const hasOldState =
+          oldState &&
+          typeof oldState === "object" &&
+          ("state" in oldState ||
+            Object.keys(oldState).some((k) => k.startsWith("__rsc_ls_")));
+        const hasNewState =
+          historyState &&
+          ("state" in historyState ||
+            Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_")));
+        if (hasOldState || hasNewState) {
+          window.dispatchEvent(new Event("__rsc_locationstate"));
+        }
+
+        // Update store history key so future navigations reference the right cache
+        store.setHistoryKey(historyKey);
+        store.setCurrentUrl(url);
+
+        // Notify hooks — location updates, state stays idle
+        eventController.setLocation(targetUrl);
+
+        // Handle post-navigation scroll
+        handleNavigationEnd({ scroll: options.scroll });
+        return;
+      }
+
       // Only abort pending requests when navigating to a different route
       // Same-route navigation (e.g., /todos -> /todos) should not cancel in-flight actions
       const currentPath = new URL(window.location.href).pathname;
@@ -181,18 +259,24 @@ export function createNavigationBridge(
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
+      // 5. stale cache - server action invalidated it, need fresh data with loading state
       const hasUsableCache =
         cachedSegments &&
         cachedSegments.length > 0 &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
+        !cached?.stale &&
         !options?._skipCache;
 
+      // Forward navigations always await fetchPartialUpdate before rendering,
+      // so useNavigation should always report "loading". skipLoadingState is
+      // only used for popstate background revalidation (line ~526) where
+      // cached content renders instantly without a network wait.
       const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
-        skipLoadingState: hasUsableCache,
+        skipLoadingState: false,
       });
 
       // REVALIDATE: Fetch fresh data from server
@@ -200,7 +284,7 @@ export function createNavigationBridge(
         await fetchPartialUpdate(
           url,
           hasUsableCache
-            ? getNonLoaderSegmentIds(cachedSegments!)
+            ? cachedSegments!.map((s) => s.id)
             : options?._skipCache
               ? [] // Action redirect: send no segments so server renders everything fresh
               : undefined,
@@ -332,6 +416,15 @@ export function createNavigationBridge(
         eventController.abortAllActions();
       }
 
+      // Popstate that exits an intercept to a non-intercept destination. The
+      // fallback fetch path below needs `leave-intercept` mode so it filters
+      // the cached @modal segment from the request and forces a re-render —
+      // otherwise a cache-miss popstate whose server response has an empty
+      // diff hits the "no changes" branch in partial-update and the modal
+      // stays on screen.
+      const isLeavingIntercept =
+        !isIntercept && currentInterceptSource !== null;
+
       // Compute history key from URL (with intercept suffix if applicable)
       const historyKey = generateHistoryKey(url, { intercept: isIntercept });
 
@@ -355,11 +448,22 @@ export function createNavigationBridge(
       // Helper to check if streaming is in progress
       const isStreaming = () => eventController.getState().isStreaming;
 
+      // Surface any external rotation of the rango state cookie (a server
+      // Set-Cookie, a sibling tab, a cookie clear) BEFORE reading the stale bit.
+      // The divergence observer only runs inside getRangoState() — fetch-time —
+      // so a popstate-first interaction would otherwise serve a pre-mutation
+      // page as fresh and never fetch to trigger the observer. Reading here lets
+      // the observer mark the history cache stale so getCachedSegments sees it.
+      getRangoState();
+
       // Check if we can restore from history cache
       const cached = store.getCachedSegments(historyKey);
       const cachedSegments = cached?.segments;
       const cachedHandleData = cached?.handleData;
-      const isStale = cached?.stale ?? false;
+      // While an action is in flight the fence persists no stale flag, so OR it
+      // in here: a popstate during the flight serves the cached entry AND
+      // revalidates (SWR) instead of serving it as fresh.
+      const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
       if (cachedSegments && cachedSegments.length > 0) {
         // Update store to point to this history entry
@@ -368,6 +472,12 @@ export function createNavigationBridge(
         store.setCurrentUrl(url);
         store.setPath(new URL(url).pathname);
 
+        // Restore router identity from cache so subsequent navigations
+        // don't falsely detect an app switch.
+        if (cached?.routerId) {
+          store.setRouterId?.(cached.routerId);
+        }
+
         // Render from cache - force await to skip loading fallbacks
         try {
           const root = await renderSegments(cachedSegments, {
@@ -393,8 +503,16 @@ export function createNavigationBridge(
               cachedHandleData,
               params: cachedParams,
             },
+            scroll: { restore: true, isStreaming },
           };
-          const hasTransition = cachedSegments.some((s) => s.transition);
+          // Intercept-driven popstate (entering OR leaving an intercept) only
+          // mutates the parallel slot; the main outlet shows the same content.
+          // Skip startViewTransition in those cases — same rationale as the
+          // intercept guard in partial-update.ts's hasTransition computation.
+          const hasTransition =
+            !isIntercept &&
+            !isLeavingIntercept &&
+            cachedSegments.some((s) => s.transition);
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {
@@ -406,14 +524,11 @@ export function createNavigationBridge(
             onUpdate(popstateUpdate);
           }
 
-          // Restore scroll position for back/forward navigation
-          handleNavigationEnd({ restore: true, isStreaming });
-
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");
             // Background revalidation - don't await, just fire and forget
-            const segmentIds = getNonLoaderSegmentIds(cachedSegments);
+            const segmentIds = cachedSegments.map((s) => s.id);
 
             const tx = createNavigationTransaction(
               store,
@@ -478,7 +593,11 @@ export function createNavigationBridge(
             intercept: isIntercept,
             interceptSourceUrl,
           }),
-          isIntercept ? { type: "navigate", interceptSourceUrl } : undefined,
+          isIntercept
+            ? { type: "navigate", interceptSourceUrl }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" }
+              : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
@@ -555,6 +674,16 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    getVersion(): string | undefined {
+      return version;
+    },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }
 

package/src/browser/navigation-client.ts

@@ -12,12 +12,21 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
+import { isActionFenceActive } from "./action-fence.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
+  handleReloadHeader,
   teeWithCompletion,
+  isForeignRouterId,
 } from "./response-adapter.js";
-import { buildPrefetchKey, consumePrefetch } from "./prefetch/cache.js";
+import {
+  buildPrefetchKey,
+  buildSourceKey,
+  consumeInflightPrefetch,
+  consumePrefetch,
+  type DecodedPrefetch,
+} from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -26,8 +35,10 @@ import { buildPrefetchKey, consumePrefetch } from "./prefetch/cache.js";
  * deserializing the response using the RSC runtime.
  *
  * Checks the in-memory prefetch cache before making a network request.
- * The cache key is source-dependent (includes the previous URL) so
- * prefetch responses match the exact diff the server would produce.
+ * Tries the source-scoped key first (populated when the server tagged
+ * the response as source-sensitive via `X-RSC-Prefetch-Scope: source`)
+ * and falls back to the Rango-state-keyed wildcard slot used for the
+ * common source-agnostic case.
  *
  * @param deps - RSC browser dependencies (createFromFetch)
  * @returns NavigationClient instance
@@ -57,6 +68,7 @@ export function createNavigationClient(
         staleRevalidation,
         interceptSourceUrl,
         version,
+        routerId,
         hmr,
       } = options;
 
@@ -84,50 +96,130 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
+      if (routerId) {
+        fetchUrl.searchParams.set("_rsc_rid", routerId);
+      }
 
-      // Check in-memory prefetch cache before making a network request.
-      // The cache key includes the source URL (previousUrl) because the
-      // server's diff response depends on the source page context.
+      // Check completed in-memory prefetch cache before making a network
+      // request. Try the source-scoped key first (populated when the server
+      // tagged the prefetch response as source-sensitive, e.g. intercepts,
+      // or when a Link opted in with `prefetchKey=":source"`), then fall
+      // back to the wildcard slot shared across source pages.
+      // Both keys embed the Rango state, so state rotation (deploy or
+      // server-action invalidation) auto-invalidates both scopes.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs
       // fresh modules), and intercept contexts (source-dependent responses).
-      const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      const cachedResponse =
-        !staleRevalidation && !hmr && !interceptSourceUrl
-          ? consumePrefetch(cacheKey)
-          : null;
+      // Suspend prefetch consumption while an action is in flight: a queued
+      // prefetch holds pre-mutation data and must not be served until the
+      // action's response decides whether anything changed.
+      const canUsePrefetch =
+        !staleRevalidation &&
+        !hmr &&
+        !interceptSourceUrl &&
+        !isActionFenceActive();
+      const rangoState = getRangoState();
+      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
+      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
 
+      let cachedEntry: DecodedPrefetch | null = null;
+      let hitKey: string | null = null;
+      if (canUsePrefetch) {
+        cachedEntry = consumePrefetch(cacheKey);
+        if (cachedEntry) {
+          hitKey = cacheKey;
+        } else {
+          cachedEntry = consumePrefetch(wildcardKey);
+          if (cachedEntry) hitKey = wildcardKey;
+        }
+      }
+
+      let inflightEntryPromise: Promise<DecodedPrefetch | null> | null = null;
+      if (canUsePrefetch && !cachedEntry) {
+        inflightEntryPromise = consumeInflightPrefetch(cacheKey);
+        if (inflightEntryPromise) {
+          hitKey = cacheKey;
+        } else {
+          inflightEntryPromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightEntryPromise) hitKey = wildcardKey;
+        }
+      }
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
         resolveStreamComplete = resolve;
       });
 
-      let responsePromise: Promise<Response>;
+      /**
+       * Validate RSC control headers on any response (fresh, cached, or
+       * in-flight). Handles version-mismatch reloads and server redirects.
+       * Returns the response unchanged when no control header is present.
+       */
+      const validateRscHeaders = (
+        response: Response,
+        source: string,
+      ): Response | Promise<Response> => {
+        // Version mismatch — server wants a full page reload
+        const reloadResult = handleReloadHeader(response, {
+          onBlocked: resolveStreamComplete,
+          onReload: (url) => {
+            if (tx) {
+              browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+                reloadUrl: url,
+              });
+            }
+          },
+        });
+        if (reloadResult) return reloadResult;
 
-      if (cachedResponse) {
-        if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+        // Server-side redirect without state: the server returned 204 with
+        // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
+        // to a URL rendering full HTML). Throw ServerRedirect so the
+        // navigation bridge catches it and re-navigates with _skipCache.
+        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+        if (redirect === "blocked") {
+          resolveStreamComplete();
+          return emptyResponse();
         }
-        // Cached response body is already fully buffered (arrayBuffer),
-        // so stream completion is immediate.
-        responsePromise = Promise.resolve(cachedResponse).then((response) => {
-          return teeWithCompletion(
-            response,
-            () => {
-              if (tx) browserDebugLog(tx, "stream complete (from cache)");
-              resolveStreamComplete();
-            },
-            signal,
-          );
-        });
-      } else {
+        if (redirect) {
+          if (tx) {
+            browserDebugLog(tx, `server redirect (${source})`, {
+              redirectUrl: redirect.url,
+            });
+          }
+          resolveStreamComplete();
+          throw new ServerRedirect(redirect.url, undefined);
+        }
+
+        // Integrity check (pre-decode): refuse a foreign app's content response
+        // before createFromFetch imports its chunks. Ordered AFTER the reload
+        // and redirect handlers — control responses are never stamped with
+        // X-RSC-Router-Id, so they are steered first and never reach here.
+        if (isForeignRouterId(response, routerId)) {
+          if (tx) {
+            browserDebugLog(tx, `router id mismatch, reloading (${source})`);
+          }
+          resolveStreamComplete();
+          window.location.href = targetUrl;
+          return new Promise<Response>(() => {});
+        }
+
+        return response;
+      };
+
+      /** Start a fresh navigation fetch (no cache / inflight hit). */
+      const doFreshFetch = (): Promise<Response> => {
         if (tx) {
           browserDebugLog(tx, "fetching", {
             path: `${fetchUrl.pathname}${fetchUrl.search}`,
           });
         }
 
-        responsePromise = fetch(fetchUrl, {
+        return fetch(fetchUrl, {
+          // During an action's flight the state is not rotated, so the old
+          // X-Rango-State still matches the Vary-keyed HTTP-cache entry; bypass
+          // it so a genuine mid-action navigation fetches fresh instead of being
+          // served the stale prefetched bytes.
+          ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
           headers: {
             "X-RSC-Router-Client-Path": previousUrl,
             "X-Rango-State": getRangoState(),
@@ -139,43 +231,11 @@ export function createNavigationClient(
           },
           signal,
         }).then((response) => {
-          // Check for version mismatch - server wants us to reload
-          const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-          if (reload === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (reload) {
-            if (tx) {
-              browserDebugLog(tx, "version mismatch, reloading", {
-                reloadUrl: reload.url,
-              });
-            }
-            window.location.href = reload.url;
-            return new Promise<Response>(() => {});
-          }
-
-          // Server-side redirect without state: the server returned 204 with
-          // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
-          // to a URL rendering full HTML). Throw ServerRedirect so the
-          // navigation bridge catches it and re-navigates with _skipCache.
-          const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
-          if (redirect === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (redirect) {
-            if (tx) {
-              browserDebugLog(tx, "server redirect", {
-                redirectUrl: redirect.url,
-              });
-            }
-            resolveStreamComplete();
-            throw new ServerRedirect(redirect.url, undefined);
-          }
+          const validated = validateRscHeaders(response, "fetch");
+          if (validated instanceof Promise) return validated;
 
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) browserDebugLog(tx, "stream complete");
               resolveStreamComplete();
@@ -183,11 +243,71 @@ export function createNavigationClient(
             signal,
           );
         });
+      };
+
+      // A warm prefetch hit returns its eagerly-decoded payload directly: the
+      // route's chunks were imported during the prefetch, so this click runs
+      // no decode and no network. Only the fresh path runs createFromFetch and
+      // resolves the local streamComplete (via doFreshFetch's teeWithCompletion
+      // and the control-header short-circuits in validateRscHeaders).
+      const freshResult = (): {
+        payload: Promise<RscPayload>;
+        streamComplete: Promise<void>;
+      } => ({
+        payload: deps.createFromFetch<RscPayload>(doFreshFetch()),
+        streamComplete,
+      });
+
+      let payloadPromise: Promise<RscPayload>;
+      let streamCompletePromise: Promise<void>;
+
+      if (cachedEntry) {
+        if (tx) {
+          browserDebugLog(tx, "prefetch cache hit (warm)", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
+        }
+        payloadPromise = cachedEntry.payload;
+        streamCompletePromise = cachedEntry.streamComplete;
+      } else if (inflightEntryPromise) {
+        if (tx) {
+          browserDebugLog(tx, "reusing inflight prefetch", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
+        }
+        const adoptedViaWildcard = hitKey === wildcardKey;
+        const entry = await inflightEntryPromise;
+        if (!entry) {
+          if (tx) {
+            browserDebugLog(tx, "inflight prefetch unavailable, refetching");
+          }
+          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+            freshResult());
+        } else if (adoptedViaWildcard && entry.scope === "source") {
+          // A wildcard-adopted inflight that turned out source-scoped was
+          // built for a different source page. Discard and refetch.
+          if (tx) {
+            browserDebugLog(
+              tx,
+              "wildcard inflight turned out source-scoped, refetching",
+            );
+          }
+          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+            freshResult());
+        } else {
+          payloadPromise = entry.payload;
+          streamCompletePromise = entry.streamComplete;
+        }
+      } else {
+        ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+          freshResult());
       }
 
       try {
-        // Deserialize RSC payload
-        const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+        const payload = await payloadPromise;
+
         if (tx) {
           browserDebugLog(tx, "response received", {
             isPartial: payload.metadata?.isPartial,
@@ -195,7 +315,7 @@ export function createNavigationClient(
             diffCount: payload.metadata?.diff?.length ?? 0,
           });
         }
-        return { payload, streamComplete };
+        return { payload, streamComplete: streamCompletePromise };
       } catch (error) {
         // Convert network-level errors to NetworkError for proper handling
         if (isNetworkError(error)) {

package/src/browser/navigation-store-handle.ts

@@ -0,0 +1,38 @@
+/**
+ * A module-level handle to the active navigation store.
+ *
+ * The boot path (`rsc-router.tsx`) calls `createNavigationStore()` directly;
+ * there is no global store singleton. This handle is the live reference for
+ * code that needs the store but does not
+ * receive it by argument: the jar-divergence observer (below) and the client
+ * seat of `invalidateClientCache()` (added later).
+ *
+ * Dependency-light on purpose: it imports only `setRangoStateObserver` and the
+ * store type, so pulling it into the default root entry does not drag the
+ * navigation store into bundles that previously lacked it.
+ */
+
+import { setRangoStateObserver } from "./rango-state.js";
+import type { NavigationStore } from "./types.js";
+
+let registeredStore: NavigationStore | null = null;
+
+/**
+ * Register the active navigation store at boot, and wire the jar-divergence
+ * observer: when a per-request cookie read detects an EXTERNAL rotation (a
+ * sibling tab, a server `Set-Cookie`, or a cookie clear), mark this tab's
+ * history cache stale. The history cache is not state-keyed, so the value
+ * rotation alone does not reach it. No broadcast, no prefetch clear, no
+ * re-rotation — the value already changed externally.
+ */
+export function registerNavigationStore(store: NavigationStore): void {
+  registeredStore = store;
+  setRangoStateObserver(() => {
+    registeredStore?.markHistoryCacheStale();
+  });
+}
+
+/** The active navigation store, or null before boot has registered it. */
+export function getRegisteredStore(): NavigationStore | null {
+  return registeredStore;
+}