@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.135c6902

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

@@ -4,11 +4,22 @@
  */
 
 /**
- * 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;
+}
+
+/**
+ * Options for createLocationState
+ */
+export interface LocationStateOptions {
+  /** When true, the state is cleared from history after first read (flash message pattern) */
+  flash?: boolean;
 }
 
 /**
@@ -19,84 +30,113 @@ export interface LocationStateEntry {
  */
 export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   (...args: TArgs): LocationStateEntry;
-  readonly __rsc_ls_key: string;
+  /** Injected by Vite plugin - do not set manually */
+  __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(): TState | undefined;
 }
 
-// Track used keys to detect duplicates in development
-const usedKeys = new Set<string>();
-
 /**
  * Create a type-safe location state definition
  *
- * The key is auto-generated by the Vite exposeInternalIds plugin based on
- * file path and export name. No manual key required.
+ * The key is auto-injected by the Vite exposeInternalIds plugin as a property
+ * based on file path and export name. No manual key required.
  *
- * @param key Auto-injected by Vite plugin, do not provide manually
+ * @param options Optional configuration
  * @returns A typed state definition for use with Link and useLocationState
  *
  * @example
  * ```typescript
- * // Define typed state (key auto-generated from file + export)
+ * // Persistent state (survives back/forward)
  * export const ProductState = createLocationState<{ name: string; price: number }>();
  *
- * // Use in Link - state is captured at click time
- * <Link to="/product/123" state={[ProductState({ name: product.name, price: product.price })]}>
- *   View Product
- * </Link>
+ * // Flash state (cleared after first read)
+ * export const FlashMessage = createLocationState<{ text: string }>({ flash: true });
  *
- * // Multiple states
- * <Link to="/checkout" state={[ProductState(productData), CartState(cartData)]}>
- *   Checkout
- * </Link>
+ * // Use in Link
+ * <Link to="/product/123" state={[ProductState({ name: "Widget", price: 9.99 })]}>
  *
- * // For lazy evaluation (click-time), pass a getter
- * <Link to="/product" state={[ProductState(() => ({ name: product.name }))]}>
+ * // 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 type safety
- * const productState = useLocationState(ProductState);
- * // productState: { name: string; price: number } | undefined
+ * // Read with hook (reactive)
+ * const product = useLocationState(ProductState);
+ *
+ * // Read without hook (snapshot, client-side only)
+ * const snap = ProductState.read();
  * ```
  */
 export function createLocationState<TState>(
-  key?: string
+  options?: LocationStateOptions,
 ): LocationStateDefinition<[TState | (() => TState)], TState> {
-  if (!key && process.env.NODE_ENV !== "production") {
-    throw new Error(
-      "[rsc-router] createLocationState is missing a key. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the state is exported with: export const MyState = createLocationState(...)"
-    );
-  }
-  const fullKey = `__rsc_ls_${key}`;
+  const flash = options?.flash ?? false;
+  let _key: string | undefined;
 
-  // Warn about duplicate keys in development
-  if (process.env.NODE_ENV !== "production" && usedKeys.has(fullKey)) {
-    console.warn(
-      `[rsc-router] Duplicate location state key "${key}". ` +
-        `Each createLocationState call should have a unique key.`
-    );
+  function getKey(): string {
+    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 " +
+          "the state is exported with: export const MyState = createLocationState(...)",
+      );
+    }
+    return _key!;
   }
-  usedKeys.add(fullKey);
 
-  const definition = Object.assign(
-    (stateOrGetter: TState | (() => TState)): LocationStateEntry => ({
-      __rsc_ls_key: fullKey,
-      // Resolve getter immediately - lazy evaluation happens via Link's stateRef pattern
-      __rsc_ls_value:
-        typeof stateOrGetter === "function"
-          ? (stateOrGetter as () => TState)()
-          : stateOrGetter,
-    }),
-    { __rsc_ls_key: fullKey }
-  );
+  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).
+  Object.defineProperty(fn, "__rsc_ls_key", {
+    get: () => getKey(),
+    set: (k: string) => {
+      _key = k;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+
+  Object.defineProperty(fn, "__rsc_ls_flash", {
+    value: flash,
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "read", {
+    value: (): TState | undefined => {
+      if (typeof window === "undefined") return undefined;
+      return window.history.state?.[getKey()] as TState | undefined;
+    },
+    enumerable: true,
+  });
 
-  return definition as LocationStateDefinition<[TState | (() => TState)], TState>;
+  return fn as LocationStateDefinition<[TState | (() => TState)], TState>;
 }
 
 /**
  * Check if a value is a LocationStateEntry
  */
-export function isLocationStateEntry(value: unknown): value is LocationStateEntry {
+export function isLocationStateEntry(
+  value: unknown,
+): value is LocationStateEntry {
   return (
     value !== null &&
     typeof value === "object" &&
@@ -110,11 +150,13 @@ export function isLocationStateEntry(value: unknown): value is LocationStateEntr
  * Resolve state entries into a flat object for history.state
  */
 export function resolveLocationStateEntries(
-  entries: LocationStateEntry[]
+  entries: LocationStateEntry[],
 ): 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

@@ -10,53 +10,98 @@ export {
   resolveLocationStateEntries,
   type LocationStateEntry,
   type LocationStateDefinition,
+  type LocationStateOptions,
 } from "./location-state-shared.js";
 
 /**
  * Hook to read location state from history.state
  *
+ * Behavior depends on the definition:
+ * - Normal state: persists across navigations, reactive to popstate
+ * - Flash state (created with { flash: true }): read once, cleared after paint
+ *
  * 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
- * // Typed access with definition (recommended)
- * const ProductState = createLocationState<{ name: string }>("product");
+ * // Persistent state
+ * const ProductState = createLocationState<{ name: string }>();
  * const state = useLocationState(ProductState);
- * // state: { name: string } | undefined
  *
- * // Legacy typed access (backwards compatible)
- * const legacyState = useLocationState<{ from?: string }>();
+ * // Flash state (auto-clears after paint)
+ * const FlashMsg = createLocationState<{ text: string }>({ flash: true });
+ * const flash = useLocationState(FlashMsg);
+ *
+ * // Plain state access (reads from history.state.state)
+ * const state = useLocationState<{ from?: string }>();
  * ```
  */
 export function useLocationState<TArgs extends unknown[], TState>(
-  definition: LocationStateDefinition<TArgs, TState>
+  definition: LocationStateDefinition<TArgs, TState>,
 ): TState | undefined;
 export function useLocationState<T = unknown>(): T | undefined;
 export function useLocationState<TArgs extends unknown[], TState>(
-  definition?: LocationStateDefinition<TArgs, TState>
+  definition?: LocationStateDefinition<TArgs, TState>,
 ): TState | undefined {
+  const key = definition?.__rsc_ls_key;
+  const isFlash = definition?.__rsc_ls_flash ?? false;
+
   const [state, setState] = useState<TState | undefined>(() => {
     if (typeof window === "undefined") return undefined;
-    if (definition) {
-      return window.history.state?.[definition.__rsc_ls_key] as TState | undefined;
+    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;
   });
 
+  // Subscribe to popstate and programmatic state changes
   useEffect(() => {
     const handlePopstate = () => {
-      if (definition) {
-        setState(window.history.state?.[definition.__rsc_ls_key] as TState | undefined);
+      if (key) {
+        setState(window.history.state?.[key] as TState | undefined);
       } else {
         setState(window.history.state?.state as TState | undefined);
       }
     };
+
+    // 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;
+        if (isFlash) {
+          // For flash state, only update if there's a new value
+          if (val !== undefined) {
+            setState(val);
+          }
+        } else {
+          setState(val);
+        }
+      } else {
+        setState(window.history.state?.state as TState | undefined);
+      }
+    };
+
     window.addEventListener("popstate", handlePopstate);
-    return () => window.removeEventListener("popstate", handlePopstate);
-  }, [definition]);
+    window.addEventListener("__rsc_locationstate", handleLocationState);
+    return () => {
+      window.removeEventListener("popstate", handlePopstate);
+      window.removeEventListener("__rsc_locationstate", handleLocationState);
+    };
+  }, [key, isFlash]);
+
+  // Flash: clear from history.state after paint so subsequent navigations don't see it.
+  // Depends on `state` so it re-runs when state is set via the event listener.
+  useEffect(() => {
+    if (isFlash && key && state !== undefined) {
+      const cleaned = { ...window.history.state };
+      delete cleaned[key];
+      window.history.replaceState(cleaned, "", window.location.href);
+    }
+  }, [isFlash, key, state]);
 
   return state;
 }

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

@@ -1,6 +1,11 @@
 "use client";
 
-import { createContext, createElement, type Context, type ReactNode } from "react";
+import {
+  createContext,
+  createElement,
+  type Context,
+  type ReactNode,
+} from "react";
 
 /**
  * Context for the current include() mount path.

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";
 
 /**
@@ -44,7 +45,7 @@ function normalizeActionId(actionId: string): string {
 export function getActionId(action: ServerActionFunction | string): string {
   invariant(
     typeof action === "function" || typeof action === "string",
-    `useAction: action must be a function or string, got ${typeof action}`
+    `useAction: action must be a function or string, got ${typeof action}`,
   );
   const actionId = (action as any)?.$$id;
   if (actionId) {
@@ -72,7 +73,7 @@ Solutions:
 2. Use the action name as a string:
    const state = useAction("myAction");
 
-The string must match the exported function name from your "use server" file.`
+The string must match the exported function name from your "use server" file.`,
   );
 }
 
@@ -126,19 +127,24 @@ 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.
  */
 export function useAction(
-  action: ServerActionFunction | string
+  action: ServerActionFunction | string,
 ): TrackedActionState;
 export function useAction<T>(
   action: ServerActionFunction | string,
-  selector: (state: TrackedActionState) => T
+  selector: (state: TrackedActionState) => T,
 ): T;
 export function useAction<T>(
   action: ServerActionFunction | string,
-  selector?: (state: TrackedActionState) => T
+  selector?: (state: TrackedActionState) => T,
 ): T | TrackedActionState {
   const ctx = useContext(NavigationStoreContext);
   const actionId =
@@ -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,14 +197,14 @@ export function useAction<T>(
           ? selectorRef.current(state)
           : state;
 
-        if (!isShallowEqual(selectedState, prevSelected.current)) {
+        if (!shallowEqual(selectedState, prevSelected.current)) {
           prevSelected.current = selectedState;
           setBaseState(selectedState);
           startTransition(() => {
             setOptimisticState(selectedState);
           });
         }
-      }
+      },
     );
 
     return () => {
@@ -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 };