@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

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

@@ -0,0 +1,55 @@
+/**
+ * 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[] {
+  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

@@ -15,14 +15,10 @@ export { useParams } from "./use-params.js";
 export { useAction, type TrackedActionState } from "./use-action.js";
 
 // Segments state hook
-export {
-  useSegments,
-  initSegmentsSync,
-  type SegmentsState,
-} from "./use-segments.js";
+export { useSegments, type SegmentsState } from "./use-segments.js";
 
 // Handle data hook
-export { useHandle, initHandleDataSync } from "./use-handle.js";
+export { useHandle } from "./use-handle.js";
 
 // Client cache controls hook
 export {

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

@@ -4,11 +4,14 @@
  */
 
 /**
- * Internal entry representing a state value with its unique key
+ * Internal entry representing a state value with its unique key.
+ * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
+ * that is called at navigation time (not at entry creation time).
  */
 export interface LocationStateEntry {
   readonly __rsc_ls_key: string;
   readonly __rsc_ls_value: unknown;
+  readonly __rsc_ls_lazy?: boolean;
 }
 
 /**
@@ -55,6 +58,13 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  * // Use in Link
  * <Link to="/product/123" state={[ProductState({ name: "Widget", price: 9.99 })]}>
  *
+ * // Just-in-time typed state (getter called at click time, not render time).
+ * // Must be in a client component — the getter function can't cross the RSC boundary.
+ * <Link
+ *   to="/product/123"
+ *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+ * >
+ *
  * // Read with hook (reactive)
  * const product = useLocationState(ProductState);
  *
@@ -69,7 +79,7 @@ export function createLocationState<TState>(
   let _key: string | undefined;
 
   function getKey(): string {
-    if (!_key && process.env.NODE_ENV !== "production") {
+    if (!_key && process.env.NODE_ENV === "development") {
       throw new Error(
         "[rsc-router] createLocationState key not set. " +
           "Make sure the exposeInternalIds Vite plugin is enabled and " +
@@ -79,14 +89,20 @@ export function createLocationState<TState>(
     return _key!;
   }
 
-  const fn = (stateOrGetter: TState | (() => TState)): LocationStateEntry => ({
-    __rsc_ls_key: getKey(),
-    // Resolve getter immediately - lazy evaluation happens via Link's stateRef pattern
-    __rsc_ls_value:
-      typeof stateOrGetter === "function"
-        ? (stateOrGetter as () => TState)()
-        : stateOrGetter,
-  });
+  const fn = (stateOrGetter: TState | (() => TState)): LocationStateEntry => {
+    if (typeof stateOrGetter === "function") {
+      // Store getter as-is; resolved at navigation time by resolveLocationStateEntries()
+      return {
+        __rsc_ls_key: getKey(),
+        __rsc_ls_value: stateOrGetter,
+        __rsc_ls_lazy: true,
+      };
+    }
+    return {
+      __rsc_ls_key: getKey(),
+      __rsc_ls_value: stateOrGetter,
+    };
+  };
 
   // Use defineProperty for __rsc_ls_key to avoid Object.assign evaluating
   // the getter during construction (before the Vite plugin sets the key).
@@ -138,7 +154,9 @@ export function resolveLocationStateEntries(
 ): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const entry of entries) {
-    result[entry.__rsc_ls_key] = entry.__rsc_ls_value;
+    result[entry.__rsc_ls_key] = entry.__rsc_ls_lazy
+      ? (entry.__rsc_ls_value as () => unknown)()
+      : entry.__rsc_ls_value;
   }
   return result;
 }

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

@@ -22,7 +22,7 @@ export {
  *
  * Overloaded:
  * - With definition: Returns typed state from the specific key
- * - With type param only: Returns legacy state from history.state.state (backwards compat)
+ * - With type param only: Returns plain state from history.state.state
  *
  * @example
  * ```typescript
@@ -34,8 +34,8 @@ export {
  * const FlashMsg = createLocationState<{ text: string }>({ flash: true });
  * const flash = useLocationState(FlashMsg);
  *
- * // Legacy typed access (backwards compatible)
- * const legacyState = useLocationState<{ from?: string }>();
+ * // Plain state access (reads from history.state.state)
+ * const state = useLocationState<{ from?: string }>();
  * ```
  */
 export function useLocationState<TArgs extends unknown[], TState>(
@@ -53,7 +53,7 @@ export function useLocationState<TArgs extends unknown[], TState>(
     if (key) {
       return window.history.state?.[key] as TState | undefined;
     }
-    // Legacy: return history.state.state for backwards compatibility
+    // Plain state: stored under history.state.state
     return window.history.state?.state as TState | undefined;
   });
 
@@ -80,6 +80,8 @@ export function useLocationState<TArgs extends unknown[], TState>(
         } else {
           setState(val);
         }
+      } else {
+        setState(window.history.state?.state as TState | undefined);
       }
     };
 

package/src/browser/react/nonce-context.ts

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Context for CSP nonce propagation to client components during SSR.
+ *
+ * The SSR renderer wraps the tree with NonceContext.Provider so that
+ * client components (e.g. MetaTags) can apply nonces to inline scripts.
+ * On the browser side, no provider is needed — the default undefined
+ * is correct since CSP nonces are a server-side HTML concern.
+ */
+
+import { createContext, useContext, type Context } from "react";
+
+export const NonceContext: Context<string | undefined> = createContext<
+  string | undefined
+>(undefined);
+
+/**
+ * Read the CSP nonce during SSR. Returns undefined on the client.
+ */
+export function useNonce(): string | undefined {
+  return useContext(NonceContext);
+}

package/src/browser/react/shallow-equal.ts

@@ -0,0 +1,27 @@
+/**
+ * Shallow equality check for selector results.
+ * Uses Object.is for value comparison (handles NaN and +-0 correctly).
+ */
+export function shallowEqual<T>(a: T, b: T): boolean {
+  if (Object.is(a, b)) return true;
+  if (
+    typeof a !== "object" ||
+    a === null ||
+    typeof b !== "object" ||
+    b === null
+  ) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (
+      !Object.hasOwn(b, key) ||
+      !Object.is((a as any)[key], (b as any)[key])
+    ) {
+      return false;
+    }
+  }
+  return true;
+}

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

@@ -9,7 +9,8 @@ import {
   startTransition,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
-import type { TrackedActionState, ActionLifecycleState } from "../types.js";
+import { shallowEqual } from "./shallow-equal.js";
+import type { TrackedActionState } from "../types.js";
 import { invariant } from "../../errors.js";
 
 /**
@@ -126,6 +127,11 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * const error = useAction(addToCart, state => state.error);
  * ```
  *
+ * @note The selector is expected to be stable for a given hook instance.
+ * This hook tracks one projection of one action. Changing selector semantics
+ * for the same action ID without a new action event is not a supported pattern;
+ * use separate useAction() subscriptions if you need different projections.
+ *
  * @note Actions passed as props from server components lose their metadata
  * during RSC serialization. Use a string action name or import directly.
  */
@@ -161,7 +167,10 @@ export function useAction<T>(
     T | TrackedActionState
   >(null!);
 
-  // Memoize the selector to avoid unnecessary re-subscriptions
+  // Ref keeps the latest selector for subscription callbacks without
+  // re-subscribing on every render. Selector changes themselves are not
+  // treated as a reactive input; this hook expects a stable selector and
+  // represents one subscription/projection for one action.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
@@ -169,6 +178,17 @@ export function useAction<T>(
   useEffect(() => {
     if (!ctx) return;
 
+    // Sync current state for the (possibly new) actionId so that switching
+    // actions on an idle page doesn't leave stale data from the old action.
+    const currentState = ctx.eventController.getActionState(actionId);
+    const currentSelected = selectorRef.current
+      ? selectorRef.current(currentState)
+      : currentState;
+    if (!shallowEqual(currentSelected, prevSelected.current)) {
+      prevSelected.current = currentSelected;
+      setBaseState(currentSelected);
+    }
+
     // Subscribe to action-specific updates
     const unsubscribe = ctx.eventController.subscribeToAction(
       actionId,
@@ -177,7 +197,7 @@ export function useAction<T>(
           ? selectorRef.current(state)
           : state;
 
-        if (!isShallowEqual(selectedState, prevSelected.current)) {
+        if (!shallowEqual(selectedState, prevSelected.current)) {
           prevSelected.current = selectedState;
           setBaseState(selectedState);
           startTransition(() => {
@@ -195,46 +215,4 @@ export function useAction<T>(
   return (optimisticState ?? baseState) as T | TrackedActionState;
 }
 
-function isShallowEqual<T, U>(selectedState: T, baseState: U): boolean {
-  // If references are equal, they're shallow equal
-  //@ts-expect-error -- TS doesn't like comparing generics
-  if (selectedState === baseState) {
-    return true;
-  }
-
-  // If either is null/undefined and they're not equal, they're not shallow equal
-  if (selectedState == null || baseState == null) {
-    return false;
-  }
-
-  // If types are different, they're not shallow equal
-  if (typeof selectedState !== typeof baseState) {
-    return false;
-  }
-
-  // For primitives, === comparison is sufficient (already checked above)
-  if (typeof selectedState !== "object") {
-    return false;
-  }
-
-  // For objects, compare keys and values shallowly
-  const keysA = Object.keys(selectedState as object);
-  const keysB = Object.keys(baseState as object);
-
-  if (keysA.length !== keysB.length) {
-    return false;
-  }
-
-  for (const key of keysA) {
-    if (
-      !Object.prototype.hasOwnProperty.call(baseState, key) ||
-      (selectedState as any)[key] !== (baseState as any)[key]
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
 export type { TrackedActionState };

package/src/browser/react/use-client-cache.ts

@@ -46,10 +46,12 @@ export interface ClientCacheControls {
 export function useClientCache(): ClientCacheControls {
   const ctx = useContext(NavigationStoreContext);
 
+  if (!ctx) {
+    throw new Error("useClientCache must be used within NavigationProvider");
+  }
+
   const clear = useCallback(() => {
-    if (ctx?.store) {
-      ctx.store.clearHistoryCache();
-    }
+    ctx.store.clearHistoryCache();
   }, [ctx]);
 
   return { clear };

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

@@ -9,121 +9,10 @@ import {
   startTransition,
 } from "react";
 import type { Handle } from "../../handle.js";
-import { getCollectFn } from "../../handle.js";
+import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
-
-/**
- * SSR module-level state.
- * Populated by initHandleDataSync before React renders.
- * Used by useState initializer during SSR.
- */
-let ssrHandleData: HandleData = {};
-let ssrSegmentOrder: string[] = [];
-
-/**
- * Filter segment IDs to only include routes and layouts.
- * Excludes parallels (contain .@) and loaders (contain D followed by digit).
- */
-function filterSegmentOrder(matched: string[]): string[] {
-  return matched.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
-}
-
-/**
- * Resolve the collect function for a handle.
- * Handle objects are plain { __brand, $$id } - collect is stored in the registry
- * (populated when createHandle runs on the client).
- */
-function resolveCollect<T, A>(handle: Handle<T, A>): (segments: T[][]) => A {
-  // Look up collect from the registry (populated when the handle module is imported).
-  const registered = getCollectFn(handle.$$id);
-  if (registered) {
-    return registered as (segments: T[][]) => A;
-  }
-
-  // Fall back to default flat collect with a dev warning.
-  if (process.env.NODE_ENV !== "production") {
-    console.warn(
-      `[rsc-router] Handle "${handle.$$id}" was passed as a prop but its collect ` +
-        `function could not be resolved. Falling back to flat array. ` +
-        `Import the handle module in a client component to register its collect function.`,
-    );
-  }
-  return ((segments: unknown[][]) => segments.flat()) as unknown as (
-    segments: T[][],
-  ) => A;
-}
-
-/**
- * Collect handle data from segments and transform to final value.
- */
-function collectHandle<T, A>(
-  handle: Handle<T, A>,
-  data: HandleData,
-  segmentOrder: string[],
-): A {
-  const collect = resolveCollect(handle);
-  const segmentData = data[handle.$$id];
-
-  if (!segmentData) {
-    return collect([]);
-  }
-
-  // Build array of segment arrays in parent -> child order
-  const segmentArrays: T[][] = [];
-  for (const segmentId of segmentOrder) {
-    const entries = segmentData[segmentId];
-    if (entries && entries.length > 0) {
-      segmentArrays.push(entries as T[]);
-    }
-  }
-
-  // Call collect once with all segment data
-  return collect(segmentArrays);
-}
-
-/**
- * Shallow equality check for selector results.
- */
-function shallowEqual<T>(a: T, b: T): boolean {
-  if (Object.is(a, b)) return true;
-  if (
-    typeof a !== "object" ||
-    a === null ||
-    typeof b !== "object" ||
-    b === null
-  ) {
-    return false;
-  }
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-  if (keysA.length !== keysB.length) return false;
-  for (const key of keysA) {
-    if (
-      !Object.hasOwn(b, key) ||
-      !Object.is((a as any)[key], (b as any)[key])
-    ) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * Initialize handle data synchronously for SSR.
- * Called before rendering to populate state for useState initializer.
- *
- * @param data - Handle data from RSC payload
- * @param matched - Segment order for reduction
- */
-export function initHandleDataSync(data: HandleData, matched?: string[]): void {
-  ssrHandleData = data;
-  ssrSegmentOrder = filterSegmentOrder(matched ?? []);
-}
+import { shallowEqual } from "./shallow-equal.js";
 
 /**
  * Hook to access collected handle data.
@@ -154,17 +43,16 @@ export function useHandle<T, A, S>(
 ): A | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // Initial state from SSR module state or event controller
+  // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<A | S>(() => {
-    // During SSR, use module-level state
-    if (typeof document === "undefined" || !ctx) {
-      const collected = collectHandle(handle, ssrHandleData, ssrSegmentOrder);
+    if (!ctx) {
+      const collected = collectHandleData(handle, {}, []);
       return selector ? selector(collected) : collected;
     }
 
     // On client, use event controller state
     const state = ctx.eventController.getHandleState();
-    const collected = collectHandle(handle, state.data, state.segmentOrder);
+    const collected = collectHandleData(handle, state.data, state.segmentOrder);
     return selector ? selector(collected) : collected;
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -173,7 +61,7 @@ export function useHandle<T, A, S>(
   const prevValueRef = useRef(value);
   prevValueRef.current = value;
 
-  // Memoize selector ref
+  // Ref keeps the latest selector without re-subscribing on every render.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
@@ -181,11 +69,31 @@ export function useHandle<T, A, S>(
   useEffect(() => {
     if (!ctx) return;
 
+    // Sync current state for the (possibly new) handle so that switching
+    // handles on an idle page doesn't leave stale data from the old handle.
+    const currentHandleState = ctx.eventController.getHandleState();
+    const currentCollected = collectHandleData(
+      handle,
+      currentHandleState.data,
+      currentHandleState.segmentOrder,
+    );
+    const currentValue = selectorRef.current
+      ? selectorRef.current(currentCollected)
+      : currentCollected;
+    if (!shallowEqual(currentValue, prevValueRef.current)) {
+      prevValueRef.current = currentValue;
+      setValue(currentValue);
+    }
+
     return ctx.eventController.subscribeToHandles(() => {
       const state = ctx.eventController.getHandleState();
       const isAction =
         ctx.eventController.getState().inflightActions.length > 0;
-      const collected = collectHandle(handle, state.data, state.segmentOrder);
+      const collected = collectHandleData(
+        handle,
+        state.data,
+        state.segmentOrder,
+      );
       const nextValue = selectorRef.current
         ? selectorRef.current(collected)
         : collected;

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

@@ -9,36 +9,10 @@ import {
   useRef,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
 import type { PublicNavigationState } from "../types.js";
 import type { DerivedNavigationState } from "../event-controller.js";
 
-/**
- * Shallow equality check for selector results
- */
-function shallowEqual<T>(a: T, b: T): boolean {
-  if (Object.is(a, b)) return true;
-  if (
-    typeof a !== "object" ||
-    a === null ||
-    typeof b !== "object" ||
-    b === null
-  ) {
-    return false;
-  }
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-  if (keysA.length !== keysB.length) return false;
-  for (const key of keysA) {
-    if (
-      !Object.hasOwn(b, key) ||
-      !Object.is((a as any)[key], (b as any)[key])
-    ) {
-      return false;
-    }
-  }
-  return true;
-}
-
 /**
  * Convert derived state to public version (strips inflightActions)
  */
@@ -69,9 +43,7 @@ export function useNavigation<T>(
   const ctx = useContext(NavigationStoreContext);
 
   if (!ctx) {
-    throw new Error(
-      "useNavigation must be used within NavigationStoreContext.Provider",
-    );
+    throw new Error("useNavigation must be used within NavigationProvider");
   }
 
   // Base state for useOptimistic
@@ -81,11 +53,20 @@ export function useNavigation<T>(
   });
   const prevState = useRef(baseValue);
 
+  // Tracks whether the most recent setOptimisticValue call pinned the value
+  // to a non-idle state. Used to decide whether to emit a release update when
+  // returning to idle, so the optimistic store doesn't stay pinned if a
+  // 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 to avoid re-subscribing when an inline
-  // function is passed (its identity changes every render).
+  // Store selector in a ref so the subscription callback always uses the
+  // latest selector without re-subscribing on every render (inline functions
+  // have a new identity each render). This is event-driven by design: the
+  // value updates when the store emits, not when the selector changes.
+  // Between events there is nothing new to select from.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
@@ -107,11 +88,25 @@ export function useNavigation<T>(
         const hasInflightActions =
           ctx.eventController.getInflightActions().size > 0;
 
-        if (hasInflightActions || publicState.state !== "idle") {
-          // Use optimistic update for immediate feedback during transitions
+        const shouldPin = hasInflightActions || publicState.state !== "idle";
+
+        if (shouldPin) {
+          // Pin the optimistic store so the loading value shows immediately
+          // even if a parent transition (e.g. <Link> click) defers the
+          // urgent setBaseValue commit.
+          startTransition(() => {
+            setOptimisticValue(nextSelected);
+          });
+          optimisticPinnedRef.current = true;
+        } else if (optimisticPinnedRef.current) {
+          // Release a previously-pinned optimistic value. Without this,
+          // useOptimistic keeps returning the stale loading value while
+          // any parent transition is still pending, even after baseValue
+          // flipped to idle.
           startTransition(() => {
             setOptimisticValue(nextSelected);
           });
+          optimisticPinnedRef.current = false;
         }
 
         // Always update base state so UI reflects current state