@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.df410dd5

package/src/browser/react/NavigationProvider.tsx

@@ -28,6 +28,7 @@ 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 { createAppShellRef, type AppShellRef } from "../app-shell.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -46,10 +47,22 @@ async function processHandles(
     store: NavigationStore;
     matched?: string[];
     isPartial?: boolean;
+    /** Server's `resolvedIds`: every segment re-resolved this request,
+     *  including null-component ones excluded from `diff`/`segments`.
+     *  Drives cleanup of stale handle buckets when a re-resolved segment
+     *  pushed nothing. */
+    resolvedIds?: string[];
     historyKey: string;
   },
 ): Promise<void> {
-  const { eventController, store, matched, isPartial, historyKey } = opts;
+  const {
+    eventController,
+    store,
+    matched,
+    isPartial,
+    resolvedIds,
+    historyKey,
+  } = opts;
 
   let yieldCount = 0;
   for await (const handleData of handlesGenerator) {
@@ -64,7 +77,7 @@ async function processHandles(
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial);
+    eventController.setHandleData(handleData, matched, isPartial, resolvedIds);
   }
 
   // Check again before final updates
@@ -72,12 +85,11 @@ async function processHandles(
     return;
   }
 
-  // For partial updates where the generator yielded nothing (cached handlers),
-  // we still need to update the segment order to clean up stale handle data.
-  // This happens when navigating away from a route - the handlers for the new
-  // route might not push any breadcrumbs, but we still need to remove the old ones.
+  // For partial updates where the generator yielded nothing (every
+  // re-resolved handler pushed nothing), still call setHandleData so the
+  // cleanup pass can clear out stale buckets for those segments.
   if (yieldCount === 0 && matched) {
-    eventController.setHandleData({}, matched, true);
+    eventController.setHandleData({}, matched, true, resolvedIds);
   }
 
   // After handles processing completes, update the cache's handleData.
@@ -133,10 +145,23 @@ export interface NavigationProviderProps {
   warmupEnabled?: boolean;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Forwarded to prefetch requests for version mismatch detection.
+   * App version from server payload.
+   * Used only as a fallback when `appShellRef` is not supplied.
    */
   version?: string;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used only as a fallback when `appShellRef` is not supplied.
+   */
+  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.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -169,6 +194,8 @@ export function NavigationProvider({
   initialTheme,
   warmupEnabled,
   version,
+  basename,
+  appShellRef,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -190,17 +217,34 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never change)
-  const contextValue = useMemo<NavigationStoreContextValue>(
-    () => ({
+  // basename/version are always read through a shell ref so the context value
+  // has a single shape: a supplied appShellRef stays live (app-switch updates
+  // it), the standalone fallback is a frozen ref over 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>(() => {
+    const value = {
       store,
       eventController,
       navigate,
       refresh,
-      version,
-    }),
-    [],
-  );
+    } 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.
   // After 60s of no user interaction, marks connection as "cold".
@@ -289,15 +333,17 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
-  // Cancel speculative prefetches when navigation starts.
-  // Viewport/render prefetches should not compete with navigation fetches.
+  // Cancel non-matching prefetches when navigation starts.
+  // Frees connections so the navigation fetch isn't competing with
+  // speculative prefetches. The prefetch matching the navigation target
+  // is kept alive so it can be reused via consumeInflightPrefetch.
   useEffect(() => {
     let wasIdle = true;
     const unsub = eventController.subscribe(() => {
       const state = eventController.getState();
       const isIdle = state.state === "idle" && !state.isStreaming;
       if (wasIdle && !isIdle) {
-        cancelAllPrefetches();
+        cancelAllPrefetches(state.pendingUrl);
       }
       wasIdle = isIdle;
     });
@@ -336,8 +382,12 @@ export function NavigationProvider({
         metadata: update.metadata,
       });
 
-      // Update route params
-      eventController.setParams(update.metadata.params ?? {});
+      // Update route params. Only reset when the server actually sends a params
+      // map — an absent `params` field means "no change" (e.g., legacy action
+      // responses that omitted params). Explicit `{}` still clears correctly.
+      if (update.metadata.params !== undefined) {
+        eventController.setParams(update.metadata.params);
+      }
 
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {
@@ -350,24 +400,20 @@ export function NavigationProvider({
           store,
           matched: update.metadata.matched,
           isPartial: update.metadata.isPartial,
+          resolvedIds: update.metadata.resolvedIds,
           historyKey,
         }).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
+          cached === undefined,
+          cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
     });
@@ -389,7 +435,11 @@ export function NavigationProvider({
   // Build the content tree
   let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
 
-  // Wrap with ThemeProvider when theme is enabled
+  // 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.
   if (themeConfig) {
     content = (
       <ThemeProvider config={themeConfig} initialTheme={initialTheme}>

package/src/browser/react/context.ts

@@ -43,10 +43,15 @@ export interface NavigationStoreContextValue {
   refresh: () => Promise<void>;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Used in prefetch requests for version mismatch detection.
+   * App version from the initial server payload.
    */
   version: string | undefined;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used by Link and useRouter() to auto-prefix app-local paths.
+   */
+  basename: string | undefined;
 }
 
 /**

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

@@ -1,11 +1,55 @@
 /**
- * Filter segment IDs to only include routes and layouts.
- * Excludes parallels (contain .@) and loaders (contain D followed by digit).
+ * Build the handle-collection segment order from a raw `matched` list.
+ *
+ * Two responsibilities:
+ *
+ * 1. Drop loader sub-ids ("D" followed by a digit, e.g. "M0L0D1.user") —
+ *    loaders never push handles.
+ *
+ * 2. Place each parallel slot id (contains ".@") immediately after its
+ *    parent layout/route id. Raw segment-resolution emission order does NOT
+ *    guarantee this: route-mounted parallels are resolved/pushed BEFORE the
+ *    route handler's segment is appended (see fresh.ts:resolveSegment for
+ *    routes, and revalidation.ts ~915-919), so matched can read
+ *    `[..., R0.@panel, R0]`. collectHandleData consumes segmentOrder verbatim
+ *    with later-wins semantics, so without normalization the route handler's
+ *    Meta would override the slot's more-specific Meta — backwards.
+ *
+ * Slot-id format is `<parentShortCode>.@<slotName>`; `parentShortCode` never
+ * contains ".@", so splitting at the first ".@" reliably yields the parent.
  */
 export function filterSegmentOrder(matched: string[]): string[] {
-  return matched.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
+  const slotsByParent = new Map<string, string[]>();
+  const nonSlots: string[] = [];
+  const nonSlotSet = new Set<string>();
+
+  for (const id of matched) {
+    if (/D\d+\./.test(id)) continue;
+    const slotIdx = id.indexOf(".@");
+    if (slotIdx >= 0) {
+      const parent = id.slice(0, slotIdx);
+      const list = slotsByParent.get(parent);
+      if (list) {
+        list.push(id);
+      } else {
+        slotsByParent.set(parent, [id]);
+      }
+    } else {
+      nonSlots.push(id);
+      nonSlotSet.add(id);
+    }
+  }
+
+  const result: string[] = [];
+  for (const id of nonSlots) {
+    result.push(id);
+    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);
+  }
+  return result;
 }

package/src/browser/react/index.ts

@@ -20,6 +20,9 @@ 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";
+
 // Client cache controls hook
 export {
   useClientCache,

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

@@ -3,6 +3,8 @@
  * No "use client" directive so it can be imported from RSC
  */
 
+import type { ReactElement } from "react";
+
 /**
  * Internal entry representing a state value with its unique key.
  * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
@@ -22,6 +24,88 @@ export interface LocationStateOptions {
   flash?: boolean;
 }
 
+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;
+
+/**
+ * Branded error surfaced when a value that cannot live in location state is
+ * used. Location state is written into `history.state`, which uses the
+ * structured clone algorithm; React elements, functions, and symbols throw a
+ * `DataCloneError` at runtime. Carries a human-readable reason so the compile
+ * error explains the fix.
+ */
+export type LocationStateUnsafe<Reason extends string> = {
+  readonly __rango_location_state_unsafe: Reason;
+};
+
+/**
+ * Maps `T` to itself when it is safe to store in location state, or to a branded
+ * {@link LocationStateUnsafe} error for the disallowed parts: `unknown`, React
+ * elements (RSC/JSX content), functions, class constructors, and symbols.
+ * Recurses through arrays, `Map`, `Set`, and plain objects; structured-clone
+ * built-ins (`Date`, `RegExp`, typed arrays, `Blob`, `File`, `FormData`) pass
+ * through. Consumed by {@link ValidateLocationState}, which is intersected into a
+ * definition's value parameter so posting RSC content is a COMPILE error, not a
+ * runtime `DataCloneError`. (`any` is unguardable and remains an escape hatch.)
+ */
+export type LocationStateSafe<T> =
+  IsUnknown<T> extends true
+    ? LocationStateUnsafe<"location state needs an explicit, concrete type; `unknown` cannot be verified as serializable">
+    : T extends LocationStateUnsafeFn
+      ? LocationStateUnsafe<"functions cannot be stored in location state">
+      : T extends LocationStateUnsafeCtor
+        ? LocationStateUnsafe<"class constructors cannot be stored in location state">
+        : T extends symbol
+          ? LocationStateUnsafe<"symbols cannot be stored in location state">
+          : T extends ReactElement
+            ? LocationStateUnsafe<"React/RSC content cannot be stored in location state; store plain data and render it on arrival">
+            : T extends string | number | boolean | bigint | null | undefined
+              ? T
+              : T extends
+                    | Date
+                    | RegExp
+                    | ArrayBuffer
+                    | ArrayBufferView
+                    | Blob
+                    | File
+                    | FormData
+                ? T
+                : T extends ReadonlyMap<infer K, infer V>
+                  ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>>
+                  : T extends ReadonlySet<infer V>
+                    ? ReadonlySet<LocationStateSafe<V>>
+                    : T extends readonly unknown[]
+                      ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                      : T extends object
+                        ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                        : T;
+
+/**
+ * `unknown` (a no-op) when `T` is safe to store in location state, otherwise a
+ * branded {@link LocationStateUnsafe} object. Intersected into the value
+ * parameter of a definition's call and `write()` so POSTING RSC content (or any
+ * non-serializable value) is a compile error whose text carries the reason —
+ * without a `TState extends ...` self-constraint, which TypeScript rejects as
+ * circular (TS2313). For safe `T`, `value & unknown` collapses back to `value`,
+ * so valid usage is unchanged.
+ */
+export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>]
+  ? unknown
+  : LocationStateUnsafe<"location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival">;
+
 /**
  * Type-safe location state definition
  *
@@ -34,8 +118,43 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   __rsc_ls_key: string;
   /** Whether this state auto-clears after first read */
   readonly __rsc_ls_flash: boolean;
-  /** Read the current value from history.state (client-side only, undefined during SSR) */
+  /**
+   * Read the current value from history.state.
+   *
+   * Returns undefined during SSR (no `window`). To stay hydration-safe, do
+   * NOT call read() inline during the initial render — the server returns
+   * undefined while the client may have a value preserved in history.state
+   * (e.g. after a hard reload of an entry that earlier called write()),
+   * which causes a hydration mismatch. Call read() inside an event handler
+   * or a useEffect post-mount instead, or use useLocationState() if you
+   * want React to manage subscription/hydration for you.
+   */
   read(): TState | undefined;
+  /**
+   * Statically write the value into the current history entry under this
+   * definition's key, preserving any other keys already on history.state
+   * (e.g. router bookkeeping, other LocationState slots).
+   *
+   * This is the non-reactive counterpart to read(): it does not dispatch any
+   * event, so components reading via useLocationState() will NOT re-render
+   * until the next navigation/popstate. Use it when you only need the value
+   * to be there on the next read() or on the next mount (including after
+   * back/forward and hard refresh of the same entry).
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  write(value: TState & ValidateLocationState<TState>): void;
+  /**
+   * Statically remove this definition's slot from the current history entry,
+   * leaving any other keys on history.state untouched. Idempotent: removing
+   * a slot that isn't present is a no-op.
+   *
+   * Same non-reactive semantics as write(): no event is dispatched, so
+   * useLocationState() readers will NOT re-render until the next navigation.
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  delete(): void;
 }
 
 /**
@@ -70,18 +189,30 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  *
  * // Read without hook (snapshot, client-side only)
  * const snap = ProductState.read();
+ *
+ * // Static write to current history entry (non-reactive, client-side only).
+ * // Survives back/forward and hard refresh; useLocationState() readers will
+ * // NOT see the new value until the next navigation. Pair with .read() or a
+ * // fresh mount.
+ * ProductState.write({ name: "Widget", price: 9.99 });
+ *
+ * // Manually clear the slot (non-reactive, client-side only).
+ * ProductState.delete();
  * ```
  */
 export function createLocationState<TState>(
   options?: LocationStateOptions,
-): LocationStateDefinition<[TState | (() => TState)], TState> {
+): LocationStateDefinition<
+  [(TState | (() => TState)) & ValidateLocationState<TState>],
+  TState
+> {
   const flash = options?.flash ?? false;
   let _key: string | undefined;
 
   function getKey(): string {
     if (!_key && process.env.NODE_ENV === "development") {
       throw new Error(
-        "[rsc-router] createLocationState key not set. " +
+        "[rango] createLocationState key not set. " +
           "Make sure the exposeInternalIds Vite plugin is enabled and " +
           "the state is exported with: export const MyState = createLocationState(...)",
       );
@@ -128,7 +259,47 @@ export function createLocationState<TState>(
     enumerable: true,
   });
 
-  return fn as LocationStateDefinition<[TState | (() => TState)], TState>;
+  Object.defineProperty(fn, "write", {
+    value: (value: TState): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rango] LocationState.write() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state ?? {};
+      window.history.replaceState(
+        { ...current, [key]: value },
+        "",
+        window.location.href,
+      );
+    },
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "delete", {
+    value: (): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rango] LocationState.delete() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state;
+      if (current == null || !(key in current)) return;
+      const next = { ...current };
+      delete next[key];
+      window.history.replaceState(next, "", window.location.href);
+    },
+    enumerable: true,
+  });
+
+  return fn as unknown as LocationStateDefinition<
+    [(TState | (() => TState)) & ValidateLocationState<TState>],
+    TState
+  >;
 }
 
 /**

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
 // Re-export shared utilities and types
@@ -13,6 +13,24 @@ export {
   type LocationStateOptions,
 } from "./location-state-shared.js";
 
+function readLocationStateValue<TState>(
+  key: string | undefined,
+): TState | undefined {
+  if (typeof window === "undefined") return undefined;
+  if (key) {
+    return window.history.state?.[key] as TState | undefined;
+  }
+  // Plain state: stored under history.state.state
+  return window.history.state?.state as TState | undefined;
+}
+
+function hasHydrated(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.hasAttribute("data-hydrated")
+  );
+}
+
 /**
  * Hook to read location state from history.state
  *
@@ -48,30 +66,33 @@ export function useLocationState<TArgs extends unknown[], TState>(
   const key = definition?.__rsc_ls_key;
   const isFlash = definition?.__rsc_ls_flash ?? false;
 
+  // Track whether the initial render returned undefined because the page
+  // hadn't hydrated yet. If so, the mount effect catches up by reading
+  // history.state once. If not, we already have the right value and must
+  // not re-read on mount — under StrictMode, the flash-cleanup effect runs
+  // before the second setup pass, so a re-read would clobber the captured
+  // value with the now-cleared `undefined`.
+  const initialReadDeferredRef = useRef(false);
+
   const [state, setState] = useState<TState | undefined>(() => {
-    if (typeof window === "undefined") return undefined;
-    if (key) {
-      return window.history.state?.[key] as TState | undefined;
+    if (!hasHydrated()) {
+      initialReadDeferredRef.current = true;
+      return undefined;
     }
-    // Plain state: stored under history.state.state
-    return window.history.state?.state as TState | undefined;
+    return readLocationStateValue<TState>(key);
   });
 
   // Subscribe to popstate and programmatic state changes
   useEffect(() => {
     const handlePopstate = () => {
-      if (key) {
-        setState(window.history.state?.[key] as TState | undefined);
-      } else {
-        setState(window.history.state?.state as TState | undefined);
-      }
+      setState(readLocationStateValue<TState>(key));
     };
 
     // Handle programmatic state changes (same-page navigation with
     // ctx.setLocationState where components don't remount)
     const handleLocationState = () => {
       if (key) {
-        const val = window.history.state?.[key] as TState | undefined;
+        const val = readLocationStateValue<TState>(key);
         if (isFlash) {
           // For flash state, only update if there's a new value
           if (val !== undefined) {
@@ -81,10 +102,15 @@ export function useLocationState<TArgs extends unknown[], TState>(
           setState(val);
         }
       } else {
-        setState(window.history.state?.state as TState | undefined);
+        setState(readLocationStateValue<TState>(key));
       }
     };
 
+    if (initialReadDeferredRef.current) {
+      initialReadDeferredRef.current = false;
+      setState(readLocationStateValue<TState>(key));
+    }
+
     window.addEventListener("popstate", handlePopstate);
     window.addEventListener("__rsc_locationstate", handleLocationState);
     return () => {