@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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

@@ -1,7 +1,4 @@
-/**
- * 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";
 
 /**
  * Internal entry representing a state value with its unique key.
@@ -22,6 +19,80 @@ export interface LocationStateOptions {
   flash?: boolean;
 }
 
+type LocationStateUnsafeFn = (...args: never[]) => unknown;
+
+type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
+
+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 +105,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 +176,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 +246,59 @@ 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();
+      // history.state may be a non-null primitive (string/number/boolean) if
+      // non-Rango code called pushState/replaceState with one. `?? {}` only
+      // catches null/undefined, so spreading a primitive would yield indexed
+      // char/no keys and corrupt history.state. Coerce any non-object to a fresh
+      // dict — mirrors the delete() guard.
+      const existing = window.history.state;
+      const current =
+        existing !== null && typeof existing === "object" ? existing : {};
+      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;
+      // history.state may be a non-null primitive (string/number/boolean) if
+      // non-Rango code called pushState/replaceState with one. `key in
+      // <primitive>` throws, so require an object before the `in` check; a
+      // primitive carries no slots, so deletion is a no-op.
+      if (current === null || typeof current !== "object" || !(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,9 +1,8 @@
 "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
 export {
   createLocationState,
   isLocationStateEntry,
@@ -13,6 +12,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 +65,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 +101,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 () => {

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

@@ -32,40 +32,43 @@ import { shallowEqual } from "./shallow-equal.js";
  * const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
  * ```
  */
-export function useHandle<T, A>(handle: Handle<T, A>): A;
+export function useHandle<T, A>(handle: Handle<T, A>): Rango.FlightSerialize<A>;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector: (data: A) => S,
+  selector: (data: Rango.FlightSerialize<A>) => S,
 ): S;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector?: (data: A) => S,
-): A | S {
+  selector?: (data: Rango.FlightSerialize<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<A | S>(() => {
+  const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
-      const collected = collectHandleData(handle, {}, []);
+      const collected = collectHandleData(
+        handle,
+        {},
+        [],
+      ) as Rango.FlightSerialize<A>;
       return selector ? selector(collected) : collected;
     }
 
-    // On client, use event controller state
     const state = ctx.eventController.getHandleState();
-    const collected = collectHandleData(handle, state.data, state.segmentOrder);
+    const collected = collectHandleData(
+      handle,
+      state.data,
+      state.segmentOrder,
+    ) as Rango.FlightSerialize<A>;
     return selector ? selector(collected) : collected;
   });
   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;
 
@@ -76,7 +79,7 @@ export function useHandle<T, A, S>(
       handle,
       currentHandleState.data,
       currentHandleState.segmentOrder,
-    );
+    ) as Rango.FlightSerialize<A>;
     const currentValue = selectorRef.current
       ? selectorRef.current(currentCollected)
       : currentCollected;
@@ -93,7 +96,7 @@ export function useHandle<T, A, S>(
         handle,
         state.data,
         state.segmentOrder,
-      );
+      ) as Rango.FlightSerialize<A>;
       const nextValue = selectorRef.current
         ? selectorRef.current(collected)
         : collected;

package/src/browser/react/use-href.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useCallback } from "react";
 import { href, type ValidPaths } from "../../href-client.js";
 import { useMount } from "./use-mount.js";
 
@@ -36,5 +37,11 @@ import { useMount } from "./use-mount.js";
  */
 export function useHref(): (path: `/${string}`) => string {
   const mount = useMount();
-  return (path: `/${string}`) => href(path as ValidPaths, mount);
+  // Memoize on `mount` (stable within a route) so the returned function is
+  // referentially stable across re-renders — a consumer can safely pass it as a
+  // dependency or a prop to a memoized child without forcing re-renders.
+  return useCallback(
+    (path: `/${string}`) => href(path as ValidPaths, mount),
+    [mount],
+  );
 }

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,13 @@ export function useLinkStatus(): LinkStatus {
 
   const prevPending = useRef(basePending);
 
-  // useOptimistic allows immediate updates during transitions
+  // Tracks whether the most recent setOptimisticPending call pinned the value
+  // to a non-idle (loading) state. Used to decide whether to emit a release
+  // update when returning to idle, so the optimistic store doesn't stay pinned
+  // to `true` if a parent transition (e.g. the <Link> click / view transition
+  // commit) is still pending. Mirrors useNavigation's optimisticPinnedRef.
+  const optimisticPinnedRef = useRef(false);
+
   const [pending, setOptimisticPending] = useOptimistic(basePending);
 
   useEffect(() => {
@@ -105,25 +109,46 @@ export function useLinkStatus(): LinkStatus {
       return;
     }
 
-    // Subscribe to navigation state changes
-    return ctx.eventController.subscribe(() => {
+    const update = () => {
       const state = ctx.eventController.getState();
       const isPending = isPendingFor(linkTo, state.pendingUrl, origin);
 
       if (isPending !== prevPending.current) {
         prevPending.current = isPending;
 
-        // Use optimistic update for immediate feedback during navigation
-        if (state.state !== "idle") {
+        const shouldPin = isPending && state.state !== "idle";
+
+        if (shouldPin) {
+          // Pin the optimistic value so the spinner shows immediately even if
+          // a parent transition (e.g. <Link> click) defers the urgent
+          // setBasePending commit.
           startTransition(() => {
             setOptimisticPending(isPending);
           });
+          optimisticPinnedRef.current = true;
+        } else if (optimisticPinnedRef.current) {
+          // Release a previously-pinned optimistic value. Without this,
+          // useOptimistic keeps returning the stale `true` while any parent
+          // transition is still pending, even after basePending flipped to
+          // false at navigation completion — leaving the link spinner stuck.
+          startTransition(() => {
+            setOptimisticPending(isPending);
+          });
+          optimisticPinnedRef.current = false;
         }
 
         // Always update base state
         setBasePending(isPending);
       }
-    });
+    };
+
+    // Catch-up: re-read state synchronously on mount before subscribing, so a
+    // navigation that started between the seeding render and this effect commit
+    // isn't dropped until the next (debounced) notify. Mirrors usePathname /
+    // useSearchParams.
+    update();
+
+    return ctx.eventController.subscribe(update);
   }, [linkTo, origin]);
 
   // If not inside a Link, return not pending

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,8 +70,7 @@ 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 update = () => {
       const currentState = ctx.eventController.getState();
       const publicState = toPublicState(currentState);
       const nextSelected = selectorRef.current
@@ -112,7 +109,15 @@ export function useNavigation<T>(
         // Always update base state so UI reflects current state
         setBaseValue(nextSelected);
       }
-    });
+    };
+
+    // Catch-up: re-read state synchronously on mount before subscribing, so a
+    // state change between the seeding render and this effect commit isn't
+    // dropped until the next (debounced) notify. Mirrors usePathname /
+    // useSearchParams.
+    update();
+
+    return ctx.eventController.subscribe(update);
   }, []);
 
   return value as T | PublicNavigationState;

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

@@ -4,6 +4,8 @@ import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 
+const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
+
 /**
  * Hook to access the current route params.
  *
@@ -27,29 +29,27 @@ import { shallowEqual } from "./shallow-equal.js";
 // interface shapes pass the constraint — interfaces lack an implicit
 // index signature and would otherwise be rejected. The generic is a
 // shape annotation, not a runtime check; the body always returns the
-// underlying params map unchanged.
+// underlying params map unchanged. The default and selector input use
+// `string | undefined` because absent optional params are omitted from
+// the params record at runtime — the type must reflect that so callers
+// don't write `p.locale.length` and crash when the segment is absent.
 export function useParams<
-  T extends object = Record<string, string>,
+  T extends object = Record<string, string | undefined>,
 >(): Readonly<T>;
 export function useParams<T>(
-  selector: (params: Record<string, string>) => T,
+  selector: (params: Record<string, string | undefined>) => T,
 ): T;
 export function useParams<T>(
-  selector?: (params: Record<string, string>) => T,
-): T | Record<string, string> {
+  selector?: (params: Record<string, string | undefined>) => T,
+): T | Record<string, string | undefined> {
   const ctx = useContext(NavigationStoreContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {
-    if (!ctx) {
-      return selector ? selector({}) : {};
-    }
-    const params = ctx.eventController.getParams();
+    const params = ctx ? ctx.eventController.getParams() : EMPTY_PARAMS;
     return selector ? selector(params) : params;
   });
 
   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;