@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7d061845

package/src/browser/app-shell.ts

@@ -0,0 +1,52 @@
+import type { ComponentType, ReactNode } from "react";
+
+/**
+ * App-shell metadata: the set of per-router fields that describe the
+ * "envelope" around the current app's segment tree. These fields are set
+ * from the initial RSC payload and must be replaced atomically when the
+ * client navigates into a different router (app switch).
+ *
+ * Intentionally NOT part of the shell (all document-lifetime):
+ * - themeConfig / initialTheme: ThemeProvider is mounted above the segment
+ *   tree and must not remount on smooth transitions.
+ * - warmupEnabled: attached to the NavigationProvider's lifetime effect;
+ *   toggling it mid-session would tear down and restart idle listeners.
+ *   Also not serialized on every full-render path (e.g. the not-found
+ *   fallback), so carrying it here would be unreliable.
+ * - prefetchCacheTTL: the not-found full-render payload does not serialize
+ *   it, so a cross-app nav into a 404 would silently erase the setting.
+ *   Mutable shell fields must be serialized on EVERY full-render path,
+ *   otherwise absent fields are indistinguishable from "new app has no
+ *   value" and the old app's value is dropped.
+ *
+ * A new document navigation (hard reload) applies these fields from the
+ * target app's initial payload.
+ */
+export interface AppShell {
+  /** Router identity. Used to namespace per-app client state (e.g. the
+   *  rango-state localStorage key) so sibling apps on the same origin
+   *  cannot observe each other's cache invalidations. */
+  routerId?: string;
+  rootLayout?: ComponentType<{ children: ReactNode }>;
+  basename?: string;
+  version?: string;
+}
+
+/**
+ * Mutable container for the active app shell. Read-through via `get()` so
+ * closures capture the ref, not the shell, and pick up updates at call time.
+ */
+export interface AppShellRef {
+  get(): AppShell;
+  update(next: AppShell): void;
+}
+
+export function createAppShellRef(initial: AppShell): AppShellRef {
+  let current = initial;
+  return {
+    get: () => current,
+    update: (next) => {
+      current = next;
+    },
+  };
+}

package/src/browser/event-controller.ts

@@ -113,11 +113,24 @@ export type ActionStateListener = (state: TrackedActionState) => void;
 export type HandleListener = () => void;
 
 /**
- * Internal handle state stored in controller
+ * Internal handle state stored in controller.
+ *
+ * Two segment lists are exposed because they serve different consumers:
+ *
+ * - `segmentOrder` drives handle collection (collectHandleData). Includes
+ *   parallel slot ids and reorders them after their parent so later-wins
+ *   collect functions (e.g. Meta) get the right precedence.
+ * - `routeSegmentIds` is the layouts-and-routes-only list documented by
+ *   `useSegments().segmentIds`. Parallels and loader sub-ids are stripped;
+ *   raw matched order is preserved.
+ *
+ * Both are derived from the same `matched` input on each setHandleData call
+ * so they stay in sync.
  */
 export interface HandleState {
   data: HandleData;
   segmentOrder: string[];
+  routeSegmentIds: string[];
 }
 
 /**
@@ -202,6 +215,14 @@ export interface EventController {
     data: HandleData,
     matched?: string[],
     isPartial?: boolean,
+    /**
+     * Segment ids that were re-resolved on the server this request (the
+     * partial response's `diff`). On a partial update, any existing bucket
+     * keyed under one of these ids that has no incoming entry is treated as
+     * stale and cleared. Without this, a parallel slot that revalidates but
+     * pushes nothing leaves its previous bucket in place forever.
+     */
+    resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
 
@@ -247,6 +268,20 @@ function matchesActionId(
   return entryActionId.endsWith(`#${subscriptionId}`);
 }
 
+// Coalesce rapid notifications into one microtask-deferred fan-out; the
+// setTimeout(0) batching prevents render storms. Each notifier owns its timer
+// so listener kinds coalesce independently.
+function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  return () => {
+    if (timeout !== null) clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      timeout = null;
+      listeners.forEach((listener) => listener());
+    }, 0);
+  };
+}
+
 // ============================================================================
 // Implementation
 // ============================================================================
@@ -300,6 +335,7 @@ export function createEventController(
   // Handle data from RSC payload
   let handleData: HandleData = {};
   let handleSegmentOrder: string[] = [];
+  let routeSegmentIds: string[] = [];
 
   // Merged route params from current match
   let routeParams: Record<string, string> = {};
@@ -312,18 +348,7 @@ export function createEventController(
   const actionListeners = new Map<string, Set<ActionStateListener>>();
   const handleListeners = new Set<HandleListener>();
 
-  // Debounce state notifications to batch rapid updates
-  let notifyTimeout: ReturnType<typeof setTimeout> | null = null;
-
-  function notify() {
-    if (notifyTimeout !== null) {
-      clearTimeout(notifyTimeout);
-    }
-    notifyTimeout = setTimeout(() => {
-      notifyTimeout = null;
-      stateListeners.forEach((listener) => listener());
-    }, 0);
-  }
+  const notify = makeDebouncedNotifier(stateListeners);
 
   // Debounce per-action notifications
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
@@ -349,18 +374,7 @@ export function createEventController(
     );
   }
 
-  // Debounce handle notifications
-  let handleNotifyTimeout: ReturnType<typeof setTimeout> | null = null;
-
-  function notifyHandles() {
-    if (handleNotifyTimeout !== null) {
-      clearTimeout(handleNotifyTimeout);
-    }
-    handleNotifyTimeout = setTimeout(() => {
-      handleNotifyTimeout = null;
-      handleListeners.forEach((listener) => listener());
-    }, 0);
-  }
+  const notifyHandles = makeDebouncedNotifier(handleListeners);
 
   // ========================================================================
   // Derived State
@@ -407,22 +421,17 @@ export function createEventController(
   }
 
   function getActionState(actionId: string): TrackedActionState {
-    // Find the most recent action with this ID that's not settling
-    // Uses suffix matching when actionId is just a name (no #)
-    const activeEntry = [...inflightActions.values()]
-      .filter(
-        (a) => matchesActionId(actionId, a.actionId) && a.phase !== "settling",
-      )
-      .sort((a, b) => b.startedAt - a.startedAt)[0];
-
-    // Also check for settling entries to get result/error
-    const settlingEntry = [...inflightActions.values()]
-      .filter(
-        (a) => matchesActionId(actionId, a.actionId) && a.phase === "settling",
-      )
-      .sort((a, b) => b.startedAt - a.startedAt)[0];
-
-    const entry = activeEntry || settlingEntry;
+    // Prefer the most-recent non-settling entry; fall back to most-recent
+    // settling so a just-settled action's result/error stays readable.
+    const entry = [...inflightActions.values()]
+      .filter((a) => matchesActionId(actionId, a.actionId))
+      .reduce<ActionEntry | undefined>((best, a) => {
+        if (!best) return a;
+        const aActive = a.phase !== "settling";
+        const bActive = best.phase !== "settling";
+        if (aActive !== bActive) return aActive ? a : best;
+        return a.startedAt > best.startedAt ? a : best;
+      }, undefined);
 
     if (!entry) {
       return { ...DEFAULT_ACTION_STATE };
@@ -610,6 +619,19 @@ export function createEventController(
       doSettle();
     }
 
+    // streamingEnded is forced here for the "streaming never started" case so
+    // tryFinalize can run; otherwise the streaming token's end() finalizes.
+    function settleWith(result: NonNullable<typeof pendingResult>) {
+      if (!inflightActions.has(id) || settled) return;
+      actionCompleted = true;
+      entry.completed = true;
+      pendingResult = result;
+      if (entry.phase === "fetching" || streamingEnded) {
+        streamingEnded = true;
+        tryFinalize();
+      }
+    }
+
     return {
       id,
       abort,
@@ -646,35 +668,11 @@ export function createEventController(
       },
 
       complete(result?: unknown) {
-        if (!inflightActions.has(id) || settled) return;
-
-        actionCompleted = true;
-        entry.completed = true;
-        pendingResult = { type: "success", value: result };
-
-        // If streaming never started or already ended, finalize immediately
-        // Otherwise wait for streaming to end
-        if (entry.phase === "fetching" || streamingEnded) {
-          streamingEnded = true; // Mark as ended if never started
-          tryFinalize();
-        }
-        // If streaming is in progress, tryFinalize() will be called when streaming ends
+        settleWith({ type: "success", value: result });
       },
 
       fail(error: unknown) {
-        if (!inflightActions.has(id) || settled) return;
-
-        actionCompleted = true;
-        entry.completed = true;
-        pendingResult = { type: "error", value: error };
-
-        // If streaming never started or already ended, finalize immediately
-        // Otherwise wait for streaming to end
-        if (entry.phase === "fetching" || streamingEnded) {
-          streamingEnded = true; // Mark as ended if never started
-          tryFinalize();
-        }
-        // If streaming is in progress, tryFinalize() will be called when streaming ends
+        settleWith({ type: "error", value: error });
       },
 
       getRevalidatedSegments(): Set<string> {
@@ -744,8 +742,15 @@ export function createEventController(
     data: HandleData,
     matched?: string[],
     isPartial?: boolean,
+    resolvedIds?: string[],
   ): void {
-    const newSegmentOrder = filterSegmentOrder(matched ?? []);
+    const rawMatched = matched ?? [];
+    const newSegmentOrder = filterSegmentOrder(rawMatched);
+    // Separate list for useSegments(): "layouts and routes only" — strip
+    // parallels (".@") and loader sub-ids (D digit) without reordering.
+    const newRouteSegmentIds = rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    );
 
     if (isPartial && newSegmentOrder.length > 0) {
       // Partial update: merge new data with existing
@@ -757,10 +762,19 @@ export function createEventController(
           handleData[handleName][segmentId] = data[handleName][segmentId];
         }
       }
-      // Clean up data from segments no longer in the matched list
+      const resolvedIdSet =
+        resolvedIds && resolvedIds.length > 0 ? new Set(resolvedIds) : null;
+      // Cleanup pass:
+      //   a) segment dropped from the match list — delete its bucket.
+      //   b) segment was re-resolved this request but pushed nothing for
+      //      this handle — its previous bucket is stale.
+      // (a) is the existing behavior; (b) requires resolvedIds.
       for (const handleName of Object.keys(handleData)) {
         for (const segmentId of Object.keys(handleData[handleName])) {
-          if (!newSegmentOrder.includes(segmentId)) {
+          const droppedFromMatch = !newSegmentOrder.includes(segmentId);
+          const reresolvedWithoutPush =
+            resolvedIdSet?.has(segmentId) && !data[handleName]?.[segmentId];
+          if (droppedFromMatch || reresolvedWithoutPush) {
             delete handleData[handleName][segmentId];
           }
         }
@@ -770,6 +784,7 @@ export function createEventController(
       handleData = data;
     }
     handleSegmentOrder = newSegmentOrder;
+    routeSegmentIds = newRouteSegmentIds;
 
     notifyHandles();
   }
@@ -778,6 +793,7 @@ export function createEventController(
     return {
       data: handleData,
       segmentOrder: handleSegmentOrder,
+      routeSegmentIds,
     };
   }
 

package/src/browser/history-state.ts

@@ -61,6 +61,27 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * Stamp an `idx` on the next history entry's state and call push/replaceState.
+ * Push increments the current idx; replace keeps it. Initial entry idx is 0.
+ * Used by useRouter().back() to detect "first entry in this session" without
+ * relying on the Navigation API.
+ */
+export function pushHistoryWithIdx(
+  state: Record<string, unknown> | null,
+  url: string,
+  replace: boolean,
+): void {
+  const oldIdx = (window.history.state as { idx?: number } | null)?.idx ?? 0;
+  const newIdx = replace ? oldIdx : oldIdx + 1;
+  const finalState = { ...(state ?? {}), idx: newIdx };
+  if (replace) {
+    window.history.replaceState(finalState, "", url);
+  } else {
+    window.history.pushState(finalState, "", url);
+  }
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/src/browser/index.ts

@@ -1,9 +1,9 @@
 // ============================================================================
-// Browser Module - Browser entry point for RSC Router
+// Browser Module - Browser entry point for Rango
 // ============================================================================
 //
 // Usage:
-//   import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+//   import { initBrowserApp, Rango } from "rsc-router/browser";
 //
 // For React components (Link, useNavigation, etc.):
 //   import { Link, useNavigation, useAction, href } from "rsc-router/client";
@@ -13,6 +13,6 @@
 // Browser app initialization
 export {
   initBrowserApp,
-  RSCRouter,
+  Rango,
   type InitBrowserAppOptions,
 } from "./rsc-router.js";

package/src/browser/navigation-bridge.ts

@@ -5,13 +5,15 @@ import type {
   ResolvedSegment,
 } from "./types.js";
 import { setAppVersion } from "./app-version.js";
+import { setRangoStateLocal } from "./rango-state.js";
+import type { AppShell, AppShellRef } from "./app-shell.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -48,8 +50,13 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
+  /** RSC version from initial payload metadata (fallback when appShellRef is not provided) */
   version?: string;
+  /**
+   * Live app-shell ref. When supplied, the bridge reads version/basename
+   * from this ref so cross-app navigations propagate correctly.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -68,9 +75,46 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments } = config;
+  const {
+    store,
+    client,
+    eventController,
+    onUpdate,
+    renderSegments,
+    appShellRef,
+  } = config;
   let version = config.version;
 
+  /**
+   * Replace the active app-shell snapshot atomically. Called by the partial
+   * updater when a response's routerId indicates the navigation crossed
+   * into a different app. Runs the local-only side-effects tied to
+   * app-shell fields (app version, rango-state namespace) so the new app
+   * owns them after the swap. Theme, warmup, and prefetch TTL are
+   * document-lifetime and are NOT touched here.
+   */
+  function applyAppShell(next: AppShell): void {
+    if (appShellRef) {
+      appShellRef.update(next);
+    }
+    if (next.version !== undefined) {
+      version = next.version;
+      setAppVersion(next.version);
+      // Use the local-only setter — initRangoState writes the shared
+      // localStorage key and fires a storage event in other tabs still in
+      // the old app. setRangoStateLocal only mutates this tab's in-memory
+      // cache and rebinds it to the target app's routerId-scoped key,
+      // preserving the "local-only, no broadcast/rotation" contract for
+      // smooth app-switch transitions.
+      setRangoStateLocal(next.version, next.routerId);
+    }
+    // Cross-app: prior cache entries belong to a different app's segments.
+    // Drop them locally only — do NOT broadcast invalidation or rotate the
+    // shared X-Rango-State token, since other tabs still in the old app are
+    // unaffected by this tab's transition.
+    store.clearHistoryCacheLocal();
+  }
+
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
     store,
@@ -78,6 +122,7 @@ export function createNavigationBridge(
     onUpdate,
     renderSegments,
     getVersion: () => version,
+    applyAppShell,
   });
 
   return {
@@ -159,11 +204,7 @@ export function createNavigationBridge(
           },
           {},
         );
-        if (options.replace) {
-          window.history.replaceState(historyState, "", url);
-        } else {
-          window.history.pushState(historyState, "", url);
-        }
+        pushHistoryWithIdx(historyState, url, options?.replace ?? false);
 
         // Ensure new history entry has a scroll restoration key
         ensureHistoryKey();
@@ -496,7 +537,14 @@ export function createNavigationBridge(
             },
             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) {
@@ -659,11 +707,19 @@ export function createNavigationBridge(
       };
     },
 
+    getVersion(): string | undefined {
+      return version;
+    },
+
     updateVersion(newVersion: string): void {
       version = newVersion;
       setAppVersion(newVersion);
       store.clearHistoryCache();
     },
+
+    updateAppShell(next: AppShell): void {
+      applyAppShell(next);
+    },
   };
 }
 

package/src/browser/navigation-client.ts

@@ -15,10 +15,12 @@ import { getRangoState } from "./rango-state.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
+  handleReloadHeader,
   teeWithCompletion,
 } from "./response-adapter.js";
 import {
   buildPrefetchKey,
+  buildSourceKey,
   consumeInflightPrefetch,
   consumePrefetch,
 } from "./prefetch/cache.js";
@@ -30,8 +32,10 @@ import {
  * 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
@@ -93,17 +97,19 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
 
-      // Check completed 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 canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
-      const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      // Wildcard key matches prefetch entries stored with a custom prefetchKey
-      // (Link's prefetchKey prop stores under "*" instead of the source URL).
-      const wildcardKey = "*\0" + fetchUrl.pathname + fetchUrl.search;
+      const rangoState = getRangoState();
+      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
+      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
 
       let cachedResponse: Response | null = null;
       let hitKey: string | null = null;
@@ -143,21 +149,17 @@ export function createNavigationClient(
         source: string,
       ): Response | Promise<Response> => {
         // Version mismatch — server wants a full page reload
-        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-        if (reload === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
-        }
-        if (reload) {
-          if (tx) {
-            browserDebugLog(tx, `version mismatch, reloading (${source})`, {
-              reloadUrl: reload.url,
-            });
-          }
-          window.location.href = reload.url;
-          // Block further processing — page is reloading
-          return new Promise<Response>(() => {});
-        }
+        const reloadResult = handleReloadHeader(response, {
+          onBlocked: resolveStreamComplete,
+          onReload: (url) => {
+            if (tx) {
+              browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+                reloadUrl: url,
+              });
+            }
+          },
+        });
+        if (reloadResult) return reloadResult;
 
         // Server-side redirect without state: the server returned 204 with
         // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
@@ -244,6 +246,7 @@ export function createNavigationClient(
             wildcard: hitKey === wildcardKey,
           });
         }
+        const adoptedViaWildcard = hitKey === wildcardKey;
         responsePromise = inflightResponsePromise.then(async (response) => {
           if (!response) {
             if (tx) {
@@ -252,6 +255,23 @@ export function createNavigationClient(
             return doFreshFetch();
           }
 
+          // Cross-source safety: an inflight promise adopted via the
+          // wildcard key may turn out to be source-scoped (server emitted
+          // `X-RSC-Prefetch-Scope: source`), which means it was built for
+          // a different source page. Discard and refetch.
+          if (
+            adoptedViaWildcard &&
+            response.headers.get("x-rsc-prefetch-scope") === "source"
+          ) {
+            if (tx) {
+              browserDebugLog(
+                tx,
+                "wildcard inflight turned out source-scoped, refetching",
+              );
+            }
+            return doFreshFetch();
+          }
+
           const validated = validateRscHeaders(response, "inflight prefetch");
           if (validated instanceof Promise) return validated;
 

package/src/browser/navigation-store.ts

@@ -12,7 +12,10 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
-import { clearPrefetchCache } from "./prefetch/cache.js";
+import {
+  clearPrefetchCache,
+  clearPrefetchCacheLocal,
+} from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -280,18 +283,17 @@ export function createNavigationStore(
   /**
    * Create a debounced function that batches rapid calls
    */
+  // A non-keyed notifier is the keyed one restricted to a single constant key;
+  // its own keyed instance means the "" key never collides with action keys.
   function createDebouncedNotifier<T extends (...args: any[]) => void>(
     fn: T,
     ms: number = 20,
   ): T {
-    let timeout: ReturnType<typeof setTimeout> | null = null;
-    return ((...args: Parameters<T>) => {
-      if (timeout !== null) clearTimeout(timeout);
-      timeout = setTimeout(() => {
-        timeout = null;
-        fn(...args);
-      }, ms);
-    }) as T;
+    const keyed = createKeyedDebouncedNotifier(
+      (_key: string, ...args: any[]) => fn(...args),
+      ms,
+    );
+    return ((...args: Parameters<T>) => keyed("", ...args)) as T;
   }
 
   /**
@@ -335,6 +337,18 @@ export function createNavigationStore(
     clearPrefetchCache();
   }
 
+  /**
+   * Drop this tab's navigation + prefetch caches without broadcasting or
+   * rotating shared state. Used when the local session changes in a way that
+   * doesn't affect other tabs — e.g. this tab crosses into a different app
+   * via a cross-router navigation. Other tabs in the old app keep their
+   * caches and their X-Rango-State token.
+   */
+  function clearCacheInternalLocal(): void {
+    historyCache.length = 0;
+    clearPrefetchCacheLocal();
+  }
+
   /**
    * Mark all cache entries as stale (internal - does not broadcast)
    */
@@ -668,6 +682,15 @@ export function createNavigationStore(
       clearCacheAndBroadcast();
     },
 
+    /**
+     * Drop this tab's navigation + prefetch caches locally without
+     * broadcasting or rotating shared state. Intended for cross-app
+     * transitions where the session state diverges for this tab only.
+     */
+    clearHistoryCacheLocal(): void {
+      clearCacheInternalLocal();
+    },
+
     /**
      * Mark cache as stale and broadcast to other tabs
      * Called after server actions - allows SWR pattern for popstate