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

package/src/browser/prefetch/cache.ts

@@ -31,6 +31,12 @@
  *
  * Replaces the previous browser HTTP cache approach which was unreliable
  * due to response draining race conditions and browser inconsistencies.
+ *
+ * State here lives in module-level singletons (cache, inflight, generation,
+ * cacheTTL, etc.) rather than a per-instance factory. This is correct because
+ * exactly one router is live per document — an SPA navigation crossing a
+ * host-router boundary forces a full document reload — so the singletons are
+ * effectively per-document. Unit tests reset them via clearPrefetchCache().
  */
 
 import { abortAllPrefetches } from "./queue.js";
@@ -61,9 +67,6 @@ export interface DecodedPrefetch {
   scope: "source" | "wildcard";
 }
 
-// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
-// the server-configured prefetchCacheTTL from router options.
-// 0 disables the in-memory cache entirely.
 let cacheTTL = 300_000;
 
 /**
@@ -92,41 +95,12 @@ interface PrefetchCacheEntry {
 const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
-/**
- * In-flight promise map. When a prefetch fetch+decode is in progress, its
- * Promise<DecodedPrefetch | null> is stored here so navigation can await it
- * instead of starting a duplicate request. Resolves to null when the prefetch
- * failed, was aborted, or carried a control header (reload/redirect) that the
- * navigation must re-fetch to act on.
- */
 const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
 
-/**
- * Alias map for in-flight promises registered under multiple keys (see
- * dual inflight in prefetch/fetch.ts). Records each key's sibling set so
- * that consuming or clearing any one key atomically removes every alias —
- * guaranteeing a single consumer for the shared decode.
- */
 const inflightAliases = new Map<string, string[]>();
 
-/**
- * Keys whose in-flight prefetch promise was adopted by a navigation (via
- * `consumeInflightPrefetch`). A `DecodedPrefetch` carries a single-use
- * `metadata.handles` async generator; the adopter drains it. The same entry is
- * also published to the `cache` map by `storePrefetch` when the fetch resolves
- * — which runs AFTER adoption (adoption only succeeds while the fetch is still
- * in flight, so the entry is not yet cached). Without this guard the adopted,
- * now-drained entry would be left in the cache and served to a later navigation
- * whose handle generator yields nothing, silently dropping that route's
- * breadcrumbs. Recording the adopted keys lets `storePrefetch` skip publishing
- * them, keeping the existing one-time-consumption contract (a consumed prefetch
- * is gone; the next navigation re-fetches).
- */
 const adoptedKeys = new Set<string>();
 
-// Generation counter incremented on each clearPrefetchCache(). Fetches that
-// started before a clear carry a stale generation and must not store their
-// response (the data may be stale due to a server action invalidation).
 let generation = 0;
 
 /**
@@ -306,9 +280,6 @@ export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
 
-/**
- * Store the in-flight Promise for a prefetch so navigation can reuse it.
- */
 export function setInflightPromise(
   key: string,
   promise: Promise<DecodedPrefetch | null>,
@@ -337,20 +308,10 @@ export function clearPrefetchInflight(key: string): void {
     inflight.delete(k);
     inflightPromises.delete(k);
     inflightAliases.delete(k);
-    // Clear any adopted marker too, so a fetch that failed before storePrefetch
-    // (the marker's normal consumer) does not strand it across the next prefetch.
     adoptedKeys.delete(k);
   });
 }
 
-/**
- * Invalidate all prefetch state. Called when server actions mutate data.
- * Clears the in-memory cache, cancels in-flight prefetches, and rotates
- * the Rango state key so CDN-cached responses are also invalidated.
- *
- * Uses abortAllPrefetches (hard cancel) because in-flight responses
- * may contain stale data after a mutation.
- */
 export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();

package/src/browser/prefetch/queue.ts

@@ -71,10 +71,13 @@ function scheduleDrain(): void {
       Promise.race([waitForViewportImages(), wait(IMAGE_WAIT_TIMEOUT)]),
     )
     .then(() => {
-      drainScheduled = false;
-      // Stale drain: a cancel/abort happened while we were waiting.
-      // A fresh scheduleDrain will be called by whatever enqueues next.
+      // Stale drain: a cancel/abort happened while we were waiting, and a fresh
+      // scheduleDrain may already own drainScheduled for the new generation.
+      // Bail WITHOUT clearing the flag so we don't clobber the live wait's
+      // single-in-flight-drain coalescing (clearing it here would let the next
+      // enqueue start a third overlapping wait).
       if (gen !== drainGeneration) return;
+      drainScheduled = false;
       if (queue.length > 0) drain();
     });
 }

package/src/browser/rango-state.ts

@@ -32,23 +32,13 @@ import {
   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;
 
 /**
@@ -81,7 +71,6 @@ function readCookie(name: string): CookieRead {
   } 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) };
 }
 
@@ -91,14 +80,9 @@ function writeCookie(name: string, value: string): void {
     typeof location !== "undefined" && location.protocol === "https:";
   try {
     document.cookie = serializeStateCookie(name, value, secure);
-  } catch {
-    // Write failures are silently absorbed; the mirror carries the value.
-  }
+  } catch {}
 }
 
-// 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);
 }
@@ -195,9 +179,6 @@ export function invalidateRangoState(): void {
   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 {
@@ -209,7 +190,5 @@ function cleanupLegacyStorage(): void {
       }
     }
     for (const key of toRemove) localStorage.removeItem(key);
-  } catch {
-    // localStorage unavailable; nothing to clean.
-  }
+  } 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

@@ -29,6 +29,7 @@ import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
 import { handleNavigationEnd } from "../scroll-restoration.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;

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,49 +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";
-
-// Mount-aware reverse hook
-export { useReverse } from "./use-reverse.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";

package/src/browser/react/location-state-shared.ts

@@ -1,8 +1,3 @@
-/**
- * Shared location state utilities - works in both RSC and client contexts
- * No "use client" directive so it can be imported from RSC
- */
-
 import type { ReactElement } from "react";
 
 /**
@@ -26,16 +21,8 @@ export interface LocationStateOptions {
 
 type LocationStateUnsafeFn = (...args: never[]) => unknown;
 
-// Broadest constructor signature (`abstract` covers both abstract and concrete
-// classes). A class passed as state has a `new` signature, not a call signature,
-// so it slips past LocationStateUnsafeFn; at runtime the lazy-getter path
-// (`typeof value === "function"`) then mistakes it for a getter and throws.
 type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
 
-// `unknown` cannot be verified serializable, so it is rejected (callers must
-// supply a concrete type). `any` deliberately defeats type checking and is NOT
-// guardable — it is assignable to the branded error too, so the check always
-// passes; it remains an explicit escape hatch.
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> =
   IsAny<T> extends true ? false : unknown extends T ? true : false;

package/src/browser/react/location-state.ts

@@ -3,7 +3,6 @@
 import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
-// Re-export shared utilities and types
 export {
   createLocationState,
   isLocationStateEntry,

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

@@ -24,32 +24,24 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
   result: null,
 };
 
-/**
- * Normalize action ID - returns the ID as-is
- *
- * Server actions have IDs like "hash#actionName" or "src/actions.ts#actionName".
- * When using function references, we use the full ID for exact matching.
- * When using strings, the event controller supports suffix matching
- * (e.g., "addToCart" matches "hash#addToCart").
- */
-function normalizeActionId(actionId: string): string {
-  return actionId;
-}
-
 /**
  * Extract action ID from a server action function or string.
  *
  * Actions passed as props from server components lose their metadata
  * during RSC serialization - use a string action name instead.
+ *
+ * The extracted $$id (e.g. "hash#actionName" or "src/actions.ts#actionName")
+ * is returned as-is. Suffix-vs-exact matching against this ID happens
+ * downstream in the event controller, not here.
  */
-export function getActionId(action: ServerActionFunction | string): string {
+function getActionId(action: ServerActionFunction | string): string {
   invariant(
     typeof action === "function" || typeof action === "string",
     `useAction: action must be a function or string, got ${typeof action}`,
   );
   const actionId = (action as any)?.$$id;
   if (actionId) {
-    return normalizeActionId(actionId);
+    return actionId;
   }
 
   // If action is a string, use it directly
@@ -162,7 +154,6 @@ export function useAction<T>(
   });
   const prevSelected = useRef(baseState);
   prevSelected.current = baseState;
-  // useOptimistic allows immediate updates during transitions/actions
   const [optimisticState, setOptimisticState] = useOptimistic<
     T | TrackedActionState
   >(null!);

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

@@ -43,7 +43,6 @@ export function useHandle<T, A, S>(
 ): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
       const collected = collectHandleData(
@@ -54,7 +53,6 @@ export function useHandle<T, A, S>(
       return selector ? selector(collected) : collected;
     }
 
-    // On client, use event controller state
     const state = ctx.eventController.getHandleState();
     const collected = collectHandleData(
       handle,
@@ -65,15 +63,12 @@ export function useHandle<T, A, S>(
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
 
-  // Track previous value for shallow comparison
   const prevValueRef = useRef(value);
   prevValueRef.current = value;
 
-  // Ref keeps the latest selector without re-subscribing on every render.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Subscribe to handle data changes (client only)
   useEffect(() => {
     if (!ctx) return;
 

package/src/browser/react/use-link-status.ts

@@ -82,11 +82,9 @@ export function useLinkStatus(): LinkStatus {
   const linkTo = useContext(LinkContext);
   const ctx = useContext(NavigationStoreContext);
 
-  // Get origin for URL normalization (stable across renders)
   const origin =
     typeof window !== "undefined" ? window.location.origin : "http://localhost";
 
-  // Base state for useOptimistic
   const [basePending, setBasePending] = useState<boolean>(() => {
     if (!ctx || linkTo === null) {
       return false;
@@ -97,7 +95,6 @@ export function useLinkStatus(): LinkStatus {
 
   const prevPending = useRef(basePending);
 
-  // useOptimistic allows immediate updates during transitions
   const [pending, setOptimisticPending] = useOptimistic(basePending);
 
   useEffect(() => {
@@ -105,7 +102,6 @@ export function useLinkStatus(): LinkStatus {
       return;
     }
 
-    // Subscribe to navigation state changes
     return ctx.eventController.subscribe(() => {
       const state = ctx.eventController.getState();
       const isPending = isPendingFor(linkTo, state.pendingUrl, origin);

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

@@ -46,7 +46,6 @@ export function useNavigation<T>(
     throw new Error("useNavigation must be used within NavigationProvider");
   }
 
-  // Base state for useOptimistic
   const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
     const publicState = toPublicState(ctx.eventController.getState());
     return selector ? selector(publicState) : publicState;
@@ -59,7 +58,6 @@ export function useNavigation<T>(
   // parent transition (e.g. <Link> click) is still pending.
   const optimisticPinnedRef = useRef(false);
 
-  // useOptimistic allows immediate updates during transitions/actions
   const [value, setOptimisticValue] = useOptimistic(baseValue);
 
   // Store selector in a ref so the subscription callback always uses the
@@ -72,7 +70,6 @@ export function useNavigation<T>(
 
   // Subscribe to event controller state changes (only runs on client)
   useEffect(() => {
-    // Subscribe to updates from event controller
     return ctx.eventController.subscribe(() => {
       const currentState = ctx.eventController.getState();
       const publicState = toPublicState(currentState);

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

@@ -50,8 +50,6 @@ export function useParams<T>(
   });
 
   const prevValue = useRef(value);
-  // Ref keeps the latest selector without re-subscribing. Event-driven by
-  // design: value updates on store events, not on selector identity change.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 

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

@@ -60,7 +60,7 @@ export function useRouter(): RouterInstance {
         return ctx.refresh();
       },
 
-      prefetch(url: string): void {
+      prefetch(url: string, options?: { key?: ":source" }): void {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
           prefetchDirect(
@@ -68,6 +68,7 @@ export function useRouter(): RouterInstance {
             segmentState.currentSegmentIds,
             getAppVersion(),
             ctx.store?.getRouterId?.(),
+            options?.key,
           );
         }
       },

package/src/browser/react/use-search-params.ts

@@ -24,9 +24,6 @@ import type { ReadonlyURLSearchParams } from "../types.js";
 export function useSearchParams(): ReadonlyURLSearchParams {
   const ctx = useContext(NavigationStoreContext);
 
-  // Always initialize with empty URLSearchParams to match SSR output
-  // and avoid hydration mismatch. The useEffect below syncs from
-  // the real URL after hydration.
   const [searchParams, setSearchParams] = useState<ReadonlyURLSearchParams>(
     () => new URLSearchParams(),
   );
@@ -41,12 +38,10 @@ export function useSearchParams(): ReadonlyURLSearchParams {
       const nextSearch = location.searchParams.toString();
       if (nextSearch !== prevSearch.current) {
         prevSearch.current = nextSearch;
-        // Create a snapshot so callers cannot mutate the source URLSearchParams
         setSearchParams(new URLSearchParams(nextSearch));
       }
     };
 
-    // Sync on mount (picks up search params from browser URL)
     update();
 
     return ctx.eventController.subscribe(update);

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

@@ -86,31 +86,20 @@ export function useSegments<T>(
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Track selector identity to detect when the selector function changes.
-  // Only then do we eagerly recompute during render to avoid staleness.
-  // Without this guard, no-selector mode causes infinite re-renders because
-  // buildSegmentsState creates fresh arrays that fail Object.is checks.
   const prevSelectorIdentity = useRef(selector);
 
-  // Cache SegmentsState to stabilize nested references (path, segmentIds
-  // arrays) so selectors returning composite values don't cause spurious
-  // render-time setState calls.
   const segmentsCache = useRef<{
     location: URL;
     routeSegmentIds: string[];
     state: SegmentsState;
   } | null>(null);
 
-  // Recompute selected value from current store state and apply selector.
-  // Shared by the render-time eager check and the subscription callback.
   function recompute(
     sel: ((state: SegmentsState) => T) | undefined,
   ): T | SegmentsState {
     const location = ctx!.eventController.getLocation();
     const handleState = ctx!.eventController.getHandleState();
 
-    // Reuse cached state when inputs haven't changed by reference,
-    // keeping array/object references stable for composite selectors.
     const cache = segmentsCache.current;
     let segmentsState: SegmentsState;
     if (
@@ -165,8 +154,6 @@ export function useSegments<T>(
       unsubscribeNav();
       unsubscribeHandles();
     };
-    // Stable subscription: selector changes are handled via selectorRef,
-    // state comparison uses prevState ref. No re-subscribe needed.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 

package/src/browser/rsc-router.tsx

@@ -8,6 +8,7 @@ import {
   generateHistoryKey,
 } from "./navigation-store.js";
 import { createEventController } from "./event-controller.js";
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 import { createNavigationClient } from "./navigation-client.js";
 import { createServerActionBridge } from "./server-action-bridge.js";
 import { createNavigationBridge } from "./navigation-bridge.js";
@@ -178,8 +179,8 @@ export async function initBrowserApp(
 
   // 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.
+  // cross-tab/server rotation. There is no global store singleton, so this
+  // handle is the live reference.
   registerNavigationStore(store);
 
   // Seed router identity from the initial SSR payload so the first
@@ -280,7 +281,13 @@ export async function initBrowserApp(
     renderSegments,
     onNavigate: (url, options) => {
       if (!navigateFn) {
-        window.location.href = url;
+        // Navigation bridge not wired yet: hard-navigate, but re-validate
+        // same-origin defensively so this init-window fallback cannot become an
+        // open redirect (the normal path validates inside the navigation bridge).
+        const safe = validateRedirectOrigin(url, window.location.origin);
+        if (safe) {
+          window.location.href = safe;
+        }
         return Promise.resolve();
       }
       return navigateFn(url, options);