@rangojs/router 0.0.0-experimental.121 → 0.0.0-experimental.124

package/src/browser/navigation-bridge.ts

@@ -5,6 +5,8 @@ import type {
   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 {
@@ -446,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

package/src/browser/navigation-client.ts

@@ -12,6 +12,7 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
+import { isActionFenceActive } from "./action-fence.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -108,7 +109,14 @@ export function createNavigationClient(
       // 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;
+      // 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);
@@ -207,6 +215,11 @@ export function createNavigationClient(
         }
 
         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(),

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

@@ -0,0 +1,39 @@
+/**
+ * A module-level handle to the active navigation store.
+ *
+ * The real boot path (`rsc-router.tsx`) calls `createNavigationStore()`
+ * directly, so the `getNavigationStore()` singleton in `navigation-store.ts`
+ * is never populated in a running app (it throws; only unit tests use it).
+ * 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;
+}

package/src/browser/navigation-store.ts

@@ -130,14 +130,14 @@ export interface NavigationStoreConfig {
 
   /**
    * Enable cross-tab cache invalidation via BroadcastChannel (default: true)
-   * When cache is cleared (via server actions or useClientCache().clear()),
+   * When cache is cleared (via server actions or invalidateClientCache()),
    * other tabs will also clear their cache
    */
   crossTabSync?: boolean;
 
   /**
    * Auto-refresh when another tab mutates data on the same path (default: true)
-   * Triggered when cache is cleared via server actions or useClientCache().clear()
+   * Triggered when cache is cleared via server actions or invalidateClientCache()
    * Requires crossTabSync to be enabled
    */
   crossTabAutoRefresh?: boolean;
@@ -335,12 +335,24 @@ export function createNavigationStore(
   }
 
   /**
-   * Mark all cache entries as stale (internal - does not broadcast)
+   * Mark every history entry stale WITHOUT touching the prefetch caches or the
+   * rango state. Used by the jar-divergence observer: an external rotation has
+   * already changed the state value (so prefetch/HTTP entries strand under the
+   * retired key), and this tab must NOT re-rotate — only the history cache,
+   * which is not state-keyed, needs marking.
    */
-  function markCacheAsStaleInternal(): void {
+  function markHistoryStale(): void {
     for (let i = 0; i < historyCache.length; i++) {
       historyCache[i][2] = true;
     }
+  }
+
+  /**
+   * Mark all cache entries as stale (internal - does not broadcast). Also
+   * clears the prefetch caches, which rotates the rango state.
+   */
+  function markCacheAsStaleInternal(): void {
+    markHistoryStale();
     clearPrefetchCache();
   }
 
@@ -659,6 +671,16 @@ export function createNavigationStore(
       markCacheAsStaleInternal();
     },
 
+    /**
+     * Mark every history entry stale WITHOUT clearing the prefetch caches or
+     * rotating the rango state. The jar-divergence observer calls this after an
+     * external rotation has already changed the state value, so re-rotating
+     * here would ping-pong with the tab that rotated.
+     */
+    markHistoryCacheStale(): void {
+      markHistoryStale();
+    },
+
     /**
      * Clear the history cache and broadcast to other tabs
      * Use this for hard invalidation when data is definitely stale
@@ -675,14 +697,6 @@ export function createNavigationStore(
       markStaleAndBroadcast();
     },
 
-    /**
-     * Broadcast cache invalidation to other tabs without clearing local cache
-     * Used after consolidation fetch where local cache has fresh data
-     */
-    broadcastCacheInvalidation(): void {
-      broadcastInvalidation();
-    },
-
     /**
      * Set the callback to invoke when cross-tab refresh is triggered
      * Called by navigation bridge during initialization

package/src/browser/prefetch/fetch.ts

@@ -27,6 +27,7 @@ import {
   type DecodedPrefetch,
 } from "./cache.js";
 import { getRangoState } from "../rango-state.js";
+import { isActionFenceActive } from "../action-fence.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
 import { debugLog } from "../logging.js";
@@ -150,6 +151,12 @@ function executePrefetchFetch(
 
   const promise: Promise<DecodedPrefetch | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
+    // 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 prefetch fetches fresh rather than warming the map with stale bytes (the
+    // fence's HTTP-cache-bypass requirement applies to prefetch as well as
+    // navigation fetches).
+    ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
     signal,
     headers: {
       "X-Rango-State": getRangoState(),

package/src/browser/rango-state.ts

@@ -1,136 +1,215 @@
 /**
  * Rango State
  *
- * Manages a localStorage-based state key for HTTP cache invalidation.
- * The key is sent as the `X-Rango-State` header on both prefetch and
- * navigation requests. The server responds with `Vary: X-Rango-State`,
- * so the browser HTTP cache keys responses by (URL, X-Rango-State value).
+ * Manages a session-cookie-based state value for HTTP cache invalidation. The
+ * value is sent as the `X-Rango-State` header on prefetch and navigation
+ * requests; the server responds with `Vary: X-Rango-State`, so the browser HTTP
+ * cache keys responses by (URL, X-Rango-State value).
  *
  * Value format: `{buildVersion}:{invalidationTimestamp}`
- * - Build version changes on deploy, busting all cached prefetches.
- * - Timestamp changes on server action invalidation.
+ * - Build version changes on deploy, busting all cached prefetches at boot.
+ * - Timestamp rotates on invalidation (server action, invalidateClientCache).
  *
- * 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. 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).
+ * Storage is a session cookie named by the server-resolved name passed to
+ * initRangoState (`{prefix}_{routerId}`, default prefix `rango-state`). The
+ * cookie jar is shared across tabs, so a per-request read IS the cross-tab
+ * value sync — no `storage` event is needed. An in-memory mirror is a
+ * write-through copy that is authoritative only when the cookie is unreadable
+ * (e.g. a sandboxed frame, or site data blocked wholesale): the failure
+ * direction is always toward freshness.
  *
- * If no routerId is supplied, falls back to a single legacy key for
- * backward compatibility (single-app deployments unaffected).
+ * Precedence is load-bearing: when `document.cookie` is readable, the
+ * per-request read wins; the mirror is a fallback, never a cache of the read.
+ * Caching the read across requests would reintroduce the staleness this
+ * mechanism removes.
  */
 
-const LEGACY_STORAGE_KEY = "rango-state";
+import {
+  DEFAULT_STATE_COOKIE_PREFIX,
+  decodeStateValue,
+  getRawCookieValue,
+  mintStateValue,
+  serializeStateCookie,
+} from "./cookie-name.js";
+
+// The resolved cookie name this document is bound to (server-resolved, read
+// from payload metadata at boot). Bare default until initRangoState runs.
+let cookieName: string = DEFAULT_STATE_COOKIE_PREFIX;
+
+// Build version for this document, used as the prefix of minted values.
+let currentVersion = "0";
+
+// Write-through mirror of the value. Authoritative only when the cookie is
+// unreadable. `cookieBacked` records whether the mirror was last confirmed
+// present in the jar, so a present->absent transition (an external clear) is
+// detected exactly once instead of re-firing on every subsequent read.
+let mirror: string | null = null;
+let cookieBacked = false;
+
+// External-rotation observer, registered by the store-handle wiring (so a
+// sibling tab's rotation or a server Set-Cookie marks the history cache stale).
+// Null until registered; self-rotations never call it.
+let externalRotationObserver: ((value: string) => void) | null = null;
 
-function buildStorageKey(routerId: string | undefined): string {
-  return routerId ? `${LEGACY_STORAGE_KEY}:${routerId}` : LEGACY_STORAGE_KEY;
+/**
+ * Register the observer invoked when a read detects an EXTERNAL rotation (a
+ * sibling tab, a server `Set-Cookie`, or a cookie clear). Self-rotations
+ * (invalidateRangoState) update the mirror synchronously and never fire it.
+ */
+export function setRangoStateObserver(
+  observer: ((value: string) => void) | null,
+): void {
+  externalRotationObserver = observer;
 }
 
-// Module-level cache avoids hitting localStorage on every getRangoState() call.
-// Initialized from localStorage on first access or by initRangoState().
-let cachedState: string | null = null;
-
-// 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
-// to localStorage, keeping cachedState fresh without polling.
-let storageListenerAttached = false;
-
-function attachStorageListener(): void {
-  if (storageListenerAttached || typeof window === "undefined") return;
-  window.addEventListener("storage", (e) => {
-    // Only react to events for this tab's current app namespace. Events
-    // under other routerId-scoped keys belong to other apps and must not
-    // clobber this tab's state.
-    if (e.key !== currentStorageKey) return;
-    cachedState = e.newValue;
-  });
-  storageListenerAttached = true;
+function notifyExternalRotation(value: string): void {
+  externalRotationObserver?.(value);
 }
 
-/**
- * Initialize the Rango state key in localStorage.
- * Called once at app startup with the build version from the server.
- * The routerId scopes the storage key to this app; in multi-app setups
- * each app owns its own `rango-state:{routerId}` key and cannot observe
- * invalidations from sibling apps on the same origin.
- *
- * If localStorage already has a matching-version entry under the key,
- * keeps it (preserves invalidation state across refresh). Otherwise
- * writes a new value.
- */
-export function initRangoState(version: string, routerId?: string): void {
-  currentStorageKey = buildStorageKey(routerId);
-  if (typeof window === "undefined") return;
+interface CookieRead {
+  /** False when there is no document or the read threw (sandboxed frame). */
+  readable: boolean;
+  /** The cookie value, or null when readable but absent. */
+  value: string | null;
+}
 
-  attachStorageListener();
+function readCookie(name: string): CookieRead {
+  if (typeof document === "undefined") return { readable: false, value: null };
+  let raw: string;
+  try {
+    raw = document.cookie;
+  } catch {
+    return { readable: false, value: null };
+  }
+  // Shared parser with the server seat so both read the same jar entry.
+  return { readable: true, value: getRawCookieValue(raw, name) };
+}
 
+function writeCookie(name: string, value: string): void {
+  if (typeof document === "undefined") return;
+  const secure =
+    typeof location !== "undefined" && location.protocol === "https:";
   try {
-    const existing = localStorage.getItem(currentStorageKey);
-    if (existing) {
-      const colonIdx = existing.indexOf(":");
-      if (colonIdx > 0) {
-        const existingVersion = existing.slice(0, colonIdx);
-        if (existingVersion === version) {
-          cachedState = existing;
-          return;
-        }
-      }
-    }
-    // New version or first load
-    const newState = `${version}:${Date.now()}`;
-    localStorage.setItem(currentStorageKey, newState);
-    cachedState = newState;
+    document.cookie = serializeStateCookie(name, value, secure);
   } catch {
-    // localStorage may be unavailable (private browsing in some browsers)
-    cachedState = `${version}:${Date.now()}`;
+    // Write failures are silently absorbed; the mirror carries the value.
   }
 }
 
+// Mint a fresh value: same version, a timestamp strictly greater than the
+// current one (the in-memory mirror is the previous value). The monotonic guard
+// lives in mintStateValue, shared with the server seat.
+function mintValue(): string {
+  return mintStateValue(currentVersion, mirror);
+}
+
 /**
- * Get the current Rango state key value.
- * Used as the `X-Rango-State` header value for prefetch and navigation requests.
+ * Initialize the Rango state cookie at app startup. `version` is the build
+ * version; `stateCookieName` is the server-resolved cookie name from payload
+ * metadata (falls back to the bare default prefix when a payload arrives
+ * without it). Keeps an existing matching-version cookie (preserves the cache
+ * key across reloads); mints fresh on a version change or a missing cookie.
+ */
+export function initRangoState(
+  version: string,
+  stateCookieName?: string,
+): void {
+  currentVersion = version;
+  cookieName = stateCookieName || DEFAULT_STATE_COOKIE_PREFIX;
+  cleanupLegacyStorage();
+
+  const read = readCookie(cookieName);
+  if (!read.readable) {
+    // Cookies unreadable: the mirror is the source of truth for this session.
+    mirror = mintValue();
+    cookieBacked = false;
+    return;
+  }
+  if (read.value !== null) {
+    const decoded = decodeStateValue(read.value);
+    if (decoded && decoded.version === version) {
+      // Keep: a matching-version cookie survives the reload warm.
+      mirror = read.value;
+      cookieBacked = true;
+      return;
+    }
+  }
+  // Absent, malformed, or a version change (deploy): mint fresh and write.
+  mirror = mintValue();
+  cookieBacked = false;
+  writeCookie(cookieName, mirror);
+}
+
+/**
+ * Get the current Rango state value, used as the `X-Rango-State` header on
+ * prefetch and navigation requests. Reads the cookie every call (the read is
+ * the cross-tab sync channel) and reconciles the mirror.
  */
 export function getRangoState(): string {
-  if (cachedState) return cachedState;
+  const read = readCookie(cookieName);
 
-  if (typeof window === "undefined") return "0:0";
+  if (!read.readable) {
+    // Mirror authoritative when the jar is unreadable.
+    return mirror ?? "0:0";
+  }
 
-  try {
-    const stored = localStorage.getItem(currentStorageKey);
-    if (stored) {
-      cachedState = stored;
-      return stored;
+  if (read.value !== null) {
+    if (read.value !== mirror) {
+      // External rotation (sibling tab / server Set-Cookie): adopt it. The
+      // mirror update makes this idempotent across a burst of reads.
+      mirror = read.value;
+      cookieBacked = true;
+      notifyExternalRotation(read.value);
+    } else {
+      cookieBacked = true;
     }
-  } catch {
-    // Fallback for unavailable localStorage
+    return read.value;
   }
 
-  return "0:0";
+  // Readable but absent.
+  if (cookieBacked) {
+    // present -> absent: an external clear. Mint fresh, write back, and notify
+    // once (cookieBacked flips to false so we don't re-fire on the next read).
+    mirror = mintValue();
+    cookieBacked = false;
+    writeCookie(cookieName, mirror);
+    notifyExternalRotation(mirror);
+  } else if (mirror === null) {
+    // First access with no cookie yet (pre-boot): mint silently — there is
+    // nothing to invalidate.
+    mirror = mintValue();
+    writeCookie(cookieName, mirror);
+  }
+  return mirror;
 }
 
 /**
- * Invalidate the Rango state key. Called when server actions mutate data.
- * Updates the timestamp portion while keeping the version prefix.
- * The new value takes effect immediately for all subsequent fetches,
- * causing Vary mismatches with previously cached responses.
+ * Invalidate the Rango state (self-rotation). Called when the client clears its
+ * prefetch caches (e.g. via the server-action bridge). Rotates the timestamp,
+ * keeps the version, writes the cookie, and updates the mirror synchronously so
+ * the external-rotation observer is NOT triggered by our own write.
  */
 export function invalidateRangoState(): void {
-  const current = getRangoState();
-  const colonIdx = current.indexOf(":");
-  const version = colonIdx > 0 ? current.slice(0, colonIdx) : "0";
-  const newState = `${version}:${Date.now()}`;
-  cachedState = newState;
-
-  if (typeof window === "undefined") return;
+  mirror = mintValue();
+  cookieBacked = false;
+  writeCookie(cookieName, mirror);
+}
 
+// One-time migration: remove the legacy localStorage keys this mechanism used
+// before the cookie cutover. No value porting — a fresh cookie mint just misses
+// cleanly. Idempotent: scans for `rango-state` and `rango-state:{routerId}`.
+function cleanupLegacyStorage(): void {
+  if (typeof localStorage === "undefined") return;
   try {
-    localStorage.setItem(currentStorageKey, newState);
+    const toRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key === "rango-state" || (key && key.startsWith("rango-state:"))) {
+        toRemove.push(key);
+      }
+    }
+    for (const key of toRemove) localStorage.removeItem(key);
   } catch {
-    // Silently handle localStorage errors
+    // localStorage unavailable; nothing to clean.
   }
 }

package/src/browser/react/index.ts

@@ -23,12 +23,6 @@ export { useHandle } from "./use-handle.js";
 // Mount-aware reverse hook
 export { useReverse } from "./use-reverse.js";
 
-// Client cache controls hook
-export {
-  useClientCache,
-  type ClientCacheControls,
-} from "./use-client-cache.js";
-
 // Provider
 export {
   NavigationProvider,

package/src/browser/rsc-router.tsx

@@ -22,6 +22,7 @@ import type {
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
+import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
 import { setPrefetchDecoder } from "./prefetch/fetch.js";
 import { setAppVersion } from "./app-version.js";
@@ -175,6 +176,12 @@ export async function initBrowserApp(
     ...(storeOptions?.cacheSize && { cacheSize: storeOptions.cacheSize }),
   });
 
+  // Register the active store on the module-level handle and wire the
+  // jar-divergence observer before any getRangoState() read can detect a
+  // cross-tab/server rotation. The real boot path never populates the
+  // getNavigationStore() singleton, so this handle is the live reference.
+  registerNavigationStore(store);
+
   // Seed router identity from the initial SSR payload so the first
   // cross-app SPA navigation can detect the app switch.
   if (initialPayload.metadata?.routerId) {
@@ -228,10 +235,11 @@ export async function initBrowserApp(
     version,
   });
 
-  // Initialize the localStorage state key for cache invalidation.
-  // The build version busts cached prefetches on deploy; the routerId
-  // namespaces the key so sibling apps on the same origin don't collide.
-  initRangoState(version ?? "0", initialPayload.metadata?.routerId);
+  // Initialize the rango state cookie for cache invalidation. The build version
+  // busts cached prefetches on deploy; the server-resolved cookie name
+  // namespaces the cookie so sibling apps on the same origin don't collide
+  // (falls back to the bare default prefix if metadata lacks the name).
+  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
   setAppVersion(version);
 
   // Initialize the in-memory prefetch cache TTL from server config.