@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

package/src/browser/rango-state.ts

@@ -1,152 +1,194 @@
 /**
  * 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. 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.
+ * 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";
 
-function buildStorageKey(routerId: string | undefined): string {
-  return routerId ? `${LEGACY_STORAGE_KEY}:${routerId}` : LEGACY_STORAGE_KEY;
-}
+let cookieName: string = DEFAULT_STATE_COOKIE_PREFIX;
 
-// 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. 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.
-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;
-}
+let currentVersion = "0";
+
+let mirror: string | null = null;
+let cookieBacked = false;
+
+let externalRotationObserver: ((value: string) => void) | null = null;
 
 /**
- * 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.
+ * 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 initRangoState(version: string, routerId?: string): void {
-  currentStorageKey = buildStorageKey(routerId);
-  if (typeof window === "undefined") return;
+export function setRangoStateObserver(
+  observer: ((value: string) => void) | null,
+): void {
+  externalRotationObserver = observer;
+}
 
-  attachStorageListener();
+function notifyExternalRotation(value: string): void {
+  externalRotationObserver?.(value);
+}
 
+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;
+}
+
+function readCookie(name: string): CookieRead {
+  if (typeof document === "undefined") return { readable: false, value: null };
+  let raw: string;
   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;
+    raw = document.cookie;
   } catch {
-    // localStorage may be unavailable (private browsing in some browsers)
-    cachedState = `${version}:${Date.now()}`;
+    return { readable: false, value: null };
   }
+  return { readable: true, value: getRawCookieValue(raw, name) };
 }
 
-/**
- * Get the current Rango state key value.
- * Used as the `X-Rango-State` header value for prefetch and navigation requests.
- */
-export function getRangoState(): string {
-  if (cachedState) return cachedState;
+function writeCookie(name: string, value: string): void {
+  if (typeof document === "undefined") return;
+  const secure =
+    typeof location !== "undefined" && location.protocol === "https:";
+  try {
+    document.cookie = serializeStateCookie(name, value, secure);
+  } catch {}
+}
 
-  if (typeof window === "undefined") return "0:0";
+function mintValue(): string {
+  return mintStateValue(currentVersion, mirror);
+}
 
-  try {
-    const stored = localStorage.getItem(currentStorageKey);
-    if (stored) {
-      cachedState = stored;
-      return stored;
+/**
+ * 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;
     }
-  } catch {
-    // Fallback for unavailable localStorage
   }
-
-  return "0:0";
+  // Absent, malformed, or a version change (deploy): mint fresh and write.
+  mirror = mintValue();
+  cookieBacked = false;
+  writeCookie(cookieName, mirror);
 }
 
 /**
- * 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.
+ * 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 setRangoStateLocal(version: string, routerId?: string): void {
-  currentStorageKey = buildStorageKey(routerId);
-  cachedState = `${version}:${Date.now()}`;
+export function getRangoState(): string {
+  const read = readCookie(cookieName);
+
+  if (!read.readable) {
+    // Mirror authoritative when the jar is unreadable.
+    return mirror ?? "0:0";
+  }
+
+  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;
+    }
+    return read.value;
+  }
+
+  // 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);
+}
 
+function cleanupLegacyStorage(): void {
+  if (typeof localStorage === "undefined") return;
   try {
-    localStorage.setItem(currentStorageKey, newState);
-  } catch {
-    // Silently handle localStorage errors
-  }
+    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 {}
 }

package/src/browser/react/Link.tsx

@@ -39,8 +39,6 @@ import {
   unobserveForPrefetch,
 } from "../prefetch/observer.js";
 
-// Touch device detection for adaptive strategy.
-// Checked once at module load (Link.tsx is "use client", runs only in browser).
 const isTouchDevice =
   typeof window !== "undefined" && window.matchMedia("(hover: none)").matches;
 

package/src/browser/react/NavigationProvider.tsx

@@ -28,7 +28,8 @@ import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
 import { handleNavigationEnd } from "../scroll-restoration.js";
-import type { AppShellRef } from "../app-shell.js";
+import { createAppShellRef, type AppShellRef } from "../app-shell.js";
+import { debugLog } from "../logging.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -70,7 +71,7 @@ async function processHandles(
     // This prevents handle data from cancelled navigations polluting
     // the current route's breadcrumbs (e.g., quick popstate after clicking a link).
     if (historyKey !== store.getHistoryKey()) {
-      console.log(
+      debugLog(
         "[NavigationProvider] Stopping handle processing - user navigated away",
       );
       return;
@@ -157,9 +158,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;
 }
@@ -217,38 +220,34 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never
-  // change). When an appShellRef is supplied, `basename` and `version` are
-  // installed as live getters so app-switch transitions (which update the ref)
-  // propagate to consumers without forcing a tree-wide rerender.
+  // basename/version are always read through a shell ref so the context value
+  // 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 });
+  }
+  const shellRef = appShellRef ?? fallbackShellRef.current;
+
   const contextValue = useMemo<NavigationStoreContextValue>(() => {
-    if (appShellRef) {
-      const value = {
-        store,
-        eventController,
-        navigate,
-        refresh,
-      } as NavigationStoreContextValue;
-      Object.defineProperty(value, "basename", {
-        configurable: true,
-        enumerable: true,
-        get: () => appShellRef.get().basename,
-      });
-      Object.defineProperty(value, "version", {
-        configurable: true,
-        enumerable: true,
-        get: () => appShellRef.get().version,
-      });
-      return value;
-    }
-    return {
+    const value = {
       store,
       eventController,
       navigate,
       refresh,
-      version,
-      basename,
-    };
+    } as NavigationStoreContextValue;
+    Object.defineProperty(value, "basename", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().basename,
+    });
+    Object.defineProperty(value, "version", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().version,
+    });
+    return value;
   }, []);
 
   // Connection warmup: keep TLS alive after idle periods.
@@ -410,21 +409,15 @@ export function NavigationProvider({
         }).catch((err) =>
           console.error("[NavigationProvider] Error consuming handles:", err),
         );
-      } else if (update.metadata.cachedHandleData) {
-        // For back/forward navigation from cache, restore the cached handleData
-        // This restores breadcrumbs to the exact state they were when the page was cached
-        eventController.setHandleData(
-          update.metadata.cachedHandleData,
-          update.metadata.matched,
-          false, // full replace - restore entire cached state
-        );
       } else if (update.metadata.matched) {
-        // For cached navigations without handleData, update segmentOrder to clean up stale data
+        // cachedHandleData present -> full restore (back/forward); absent ->
+        // partial cleanup of segments no longer matched.
+        const cached = update.metadata.cachedHandleData;
         eventController.setHandleData(
-          {}, // Empty data - all existing data not in matched will be cleaned up
+          cached ?? {},
           update.metadata.matched,
-          true, // partial update - will clean up segments not in matched
-          update.metadata.resolvedIds,
+          cached === undefined,
+          cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
     });
@@ -447,10 +440,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/ScrollRestoration.tsx

@@ -14,17 +14,21 @@ export interface ScrollRestorationProps {
    * Return location.pathname to restore scroll based on path
    * (useful for keeping scroll position on the same page).
    *
+   * Provide a stable reference: a module-level function or one wrapped in
+   * useCallback. The init effect re-runs when getKey's identity changes, and
+   * teardown clears in-memory scroll positions — a fresh inline arrow on every
+   * parent render would discard unpersisted positions mid-session.
+   *
    * @example
    * ```tsx
+   * // Stable module-level getKey (recommended)
+   * const byPathname = (location) => location.pathname;
+   *
    * // Restore based on pathname (same URL = same scroll)
-   * <ScrollRestoration
-   *   getKey={(location) => location.pathname}
-   * />
+   * <ScrollRestoration getKey={byPathname} />
    *
    * // Restore based on unique history entry (default)
-   * <ScrollRestoration
-   *   getKey={(location) => location.key}
-   * />
+   * // <ScrollRestoration /> — omit getKey to use location.key
    * ```
    */
   getKey?: (location: {

package/src/browser/react/filter-segment-order.ts

@@ -46,8 +46,6 @@ export function filterSegmentOrder(matched: string[]): string[] {
     const slots = slotsByParent.get(id);
     if (slots) result.push(...slots);
   }
-  // Defensive: any slot whose parent is missing from the filtered list still
-  // gets included rather than silently dropped. Shouldn't happen in practice.
   for (const [parent, slots] of slotsByParent) {
     if (!nonSlotSet.has(parent)) result.push(...slots);
   }

package/src/browser/react/index.ts

@@ -1,52 +1,4 @@
-// React exports for browser navigation
-
-// Hook with Zustand-style selectors
-export { useNavigation } from "./use-navigation.js";
-
-// Router actions hook (stable reference, no re-renders)
-export { useRouter } from "./use-router.js";
-
-// URL hooks
-export { usePathname } from "./use-pathname.js";
-export { useSearchParams } from "./use-search-params.js";
-export { useParams } from "./use-params.js";
-
-// Action state tracking hook
-export { useAction, type TrackedActionState } from "./use-action.js";
-
-// Segments state hook
-export { useSegments, type SegmentsState } from "./use-segments.js";
-
-// Handle data hook
-export { useHandle } from "./use-handle.js";
-
-// Client cache controls hook
-export {
-  useClientCache,
-  type ClientCacheControls,
-} from "./use-client-cache.js";
-
-// Provider
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./NavigationProvider.js";
-
-// Context (for advanced usage)
-export {
-  NavigationStoreContext,
-  type NavigationStoreContextValue,
-} from "./context.js";
-
-// Link component
-export { Link, type LinkProps, type PrefetchStrategy } from "./Link.js";
-
-// Link status hook
-export { useLinkStatus, type LinkStatus } from "./use-link-status.js";
-
-// Scroll restoration
-export {
-  ScrollRestoration,
-  useScrollRestoration,
-  type ScrollRestorationProps,
-} from "./ScrollRestoration.js";