@rangojs/router 0.18.0 → 0.19.0

package/src/browser/react/Link.tsx

@@ -13,30 +13,23 @@ import React, {
 } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { LinkContext } from "./use-link-status.js";
-import type { NavigateOptions } from "../types.js";
+import type { HistoryState } from "../types.js";
 import {
   isHashOnlyNavigation,
   isPrefetchScopeDisabled,
   subscribeToPrefetchScopeChange,
 } from "../link-interceptor.js";
 import { subscribeToLocationChange } from "../event-controller.js";
-import {
-  isLocationStateEntry,
-  type LocationStateEntry,
-  resolveLocationStateEntries,
-} from "./location-state.js";
+import { isLocationStateDefinition } from "./location-state-shared.js";
 
-/**
- * State prop type for Link component.
- * - LocationStateEntry[]: Type-safe state entries via createLocationState()
- * - StateOrGetter: Plain state object or click-time getter function
- * - Record<string, unknown>: Plain state object passed to history.pushState
- */
 export type StateOrGetter<T = unknown> = T | (() => T);
 
-export type LinkState =
-  | LocationStateEntry[]
-  | StateOrGetter<Record<string, unknown>>;
+/**
+ * State prop type for Link component: the `router.push()` state type
+ * ({@link HistoryState}: `LocationStateEntry[]` from createLocationState(), or
+ * plain structured-clone-safe state), or a getter for it called at click time.
+ */
+export type LinkState = StateOrGetter<HistoryState>;
 
 import {
   prefetchDirect,
@@ -93,6 +86,14 @@ export interface LinkProps extends Omit<
    * @default true
    */
   revalidate?: boolean;
+  /**
+   * Set to `false` to present this navigation without a transition (urgent
+   * commit, `<ViewTransition>` classes `"none"`); no `transition({ when })`
+   * predicate is called. See `NavigateOptions.transition`.
+   *
+   * @default true
+   */
+  transition?: boolean;
   /**
    * Prefetch strategy for the link destination. When omitted, falls back to
    * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
@@ -118,8 +119,11 @@ export interface LinkProps extends Omit<
    * therefore serve the wrong diff to a navigation from a different
    * source.
    *
-   * Intercept responses are auto-scoped to the source via a server-side
-   * tag, so `":source"` is only needed for custom revalidation logic.
+   * A route an intercept targets is scoped to the source automatically
+   * (server-side `x-rsc-prefetch-scope: source`), whether or not the
+   * intercept applies from this page: the modal and the full page are
+   * both source-specific. Every other route stays shared, so `":source"`
+   * is only needed for custom revalidation logic.
    *
    * @example
    * ```tsx
@@ -226,6 +230,7 @@ export const Link: ForwardRefExoticComponent<
     scroll = true,
     reloadDocument = false,
     revalidate,
+    transition,
     prefetch,
     prefetchKey,
     state,
@@ -334,28 +339,26 @@ export const Link: ForwardRefExoticComponent<
       // Stop propagation to prevent link-interceptor from also handling this
       e.stopPropagation();
 
+      // Call a click-time getter; typed entries are resolved (and, in dev,
+      // checked) by the bridge's resolveNavigationState, like router.push().
+      // In dev an uncalled definition passes through to that check instead of
+      // being called as a getter.
       const currentState = stateRef.current;
-      let resolvedState: unknown;
-
-      if (
-        Array.isArray(currentState) &&
-        currentState.length > 0 &&
-        isLocationStateEntry(currentState[0])
-      ) {
-        resolvedState = resolveLocationStateEntries(
-          currentState as LocationStateEntry[],
-        );
-      } else if (typeof currentState === "function") {
-        resolvedState = currentState();
-      } else if (currentState != null) {
-        resolvedState = currentState;
-      }
+      const state =
+        typeof currentState === "function" &&
+        !(
+          process.env.NODE_ENV !== "production" &&
+          isLocationStateDefinition(currentState)
+        )
+          ? currentState()
+          : (currentState ?? undefined);
 
       ctx.navigate(resolvedTo, {
         replace,
         scroll,
-        state: resolvedState,
+        state,
         revalidate,
+        transition,
       });
     },
     [
@@ -365,6 +368,7 @@ export const Link: ForwardRefExoticComponent<
       replace,
       scroll,
       revalidate,
+      transition,
       ctx,
       onClick,
     ],
@@ -487,6 +491,7 @@ export const Link: ForwardRefExoticComponent<
       data-scroll={scroll === false ? "false" : undefined}
       data-replace={replace ? "true" : undefined}
       data-revalidate={revalidate === false ? "false" : undefined}
+      data-transition={transition === false ? "false" : undefined}
       {...props}
     >
       <LinkContext.Provider value={resolvedTo}>{children}</LinkContext.Provider>

package/src/browser/react/NavigationProvider.tsx

@@ -17,7 +17,7 @@ import {
 import type {
   NavigationStore,
   NavigationUpdate,
-  NavigateOptions,
+  NavigateOptionsInternal,
   NavigationBridge,
 } from "../types.js";
 import type { EventController } from "../event-controller.js";
@@ -320,7 +320,7 @@ export function NavigationProvider({
    * Navigate to a URL (delegates to bridge)
    */
   const navigate = useCallback(
-    async (url: string, options?: NavigateOptions): Promise<void> => {
+    async (url: string, options?: NavigateOptionsInternal): Promise<void> => {
       await bridge.navigate(url, options);
     },
     [],

package/src/browser/react/context.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { createContext, type Context } from "react";
-import type { NavigationStore, NavigateOptions } from "../types.js";
+import type { NavigationStore, NavigateOptionsInternal } from "../types.js";
 import type { EventController } from "../event-controller.js";
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
@@ -34,7 +34,7 @@ export interface NavigationStoreContextValue {
    * @param options - Navigation options (replace, scroll)
    * @returns Promise that resolves when navigation is complete
    */
-  navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+  navigate: (url: string, options?: NavigateOptionsInternal) => Promise<void>;
 
   /**
    * Refresh the current route

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

@@ -27,17 +27,64 @@ type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> =
   IsAny<T> extends true ? false : unknown extends T ? true : false;
 
+type UnknownReason =
+  "`unknown` cannot be verified as serializable; give it a concrete type";
+type FunctionReason = "functions cannot be stored in location state";
+type ConstructorReason =
+  "class constructors cannot be stored in location state";
+type SymbolReason = "symbols cannot be stored in location state";
+type ReactReason =
+  "React/RSC content cannot be stored in location state; store plain data and render it on arrival";
+type DepthReason =
+  "nested too deep to locate the unsafe field; it is below this path";
+
 /**
  * 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.
+ * `DataCloneError` at runtime. Carries the reason and the offending field's
+ * path (`items[].info.values`; `<root>` for the value itself) so the compile
+ * error names the field to fix.
  */
-export type LocationStateUnsafe<Reason extends string> = {
+export type LocationStateUnsafe<
+  Reason extends string,
+  Path extends string = "<root>",
+> = {
   readonly __rango_location_state_unsafe: Reason;
+  readonly __rango_location_state_path: Path;
 };
 
+/**
+ * Why a value cannot be structured-cloned, for the kinds that fail on their
+ * own (not through something nested in them), or `never`. Distributes over a
+ * union, one reason per unsafe member.
+ */
+type UnsafeReason<T> = T extends LocationStateUnsafeFn
+  ? FunctionReason
+  : T extends LocationStateUnsafeCtor
+    ? ConstructorReason
+    : T extends symbol
+      ? SymbolReason
+      : T extends ReactElement
+        ? ReactReason
+        : never;
+
+/** Primitives and structured-clone built-ins, stored as-is. */
+type LocationStatePassthrough =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | undefined
+  | Date
+  | RegExp
+  | ArrayBuffer
+  | ArrayBufferView
+  | Blob
+  | File
+  | FormData;
+
 /**
  * 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
@@ -50,48 +97,134 @@ export type LocationStateUnsafe<Reason extends string> = {
  */
 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;
+    ? LocationStateUnsafe<UnknownReason>
+    : T extends unknown
+      ? [UnsafeReason<T>] extends [never]
+        ? T extends LocationStatePassthrough
+          ? T
+          : T extends ReadonlyMap<infer K, infer V>
+            ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>>
+            : T extends ReadonlySet<infer V>
+              ? ReadonlySet<LocationStateSafe<V>>
+              : T extends object
+                ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                : T
+        : LocationStateUnsafe<UnsafeReason<T>>
+      : never;
+
+type AtPath<P extends string> = P extends "" ? "<root>" : P;
+
+/** `a.b` for a named key; `a[string]` / `a[number]` for an index signature. */
+type ChildPath<P extends string, K> = string extends K
+  ? `${P}[string]`
+  : number extends K
+    ? `${P}[number]`
+    : K extends string | number
+      ? P extends ""
+        ? `${K}`
+        : `${P}.${K}`
+      : `${P}[symbol]`;
+
+type UnsafeAt<R, P extends string> = R extends string
+  ? LocationStateUnsafe<R, AtPath<P>>
+  : never;
+
+/**
+ * Walks `T` to the fields {@link LocationStateSafe} rejects and returns one
+ * {@link LocationStateUnsafe} brand per offending path (a union when several
+ * fail). Reports the shallowest failures: a value that is itself unsafe stops
+ * the walk, and an object with unsafe fields of its own reports only those, so
+ * a class instance or DOM node stops at its methods instead of walking its
+ * whole object graph (`{ el: HTMLElement }` took 8.4M instantiations and hit
+ * TS2589 before). Descends only into children that fail the cached
+ * `LocationStateSafe` check, and stops at depth 8.
+ */
+type LocateUnsafe<
+  T,
+  P extends string,
+  D extends unknown[],
+> = D["length"] extends 8
+  ? LocationStateUnsafe<DepthReason, AtPath<P>>
+  : IsUnknown<T> extends true
+    ? LocationStateUnsafe<UnknownReason, AtPath<P>>
+    : [UnsafeReason<T>] extends [never]
+      ? LocateNested<T, P, D>
+      : UnsafeAt<UnsafeReason<T>, P>;
+
+type LocateNested<
+  T,
+  P extends string,
+  D extends unknown[],
+> = T extends LocationStatePassthrough
+  ? never
+  : T extends ReadonlyMap<infer K, infer V>
+    ? LocateChild<K, `${P}<key>`, D> | LocateChild<V, `${P}<value>`, D>
+    : T extends ReadonlySet<infer V>
+      ? LocateChild<V, `${P}[]`, D>
+      : T extends readonly unknown[]
+        ? number extends T["length"]
+          ? LocateChild<T[number], `${P}[]`, D>
+          : {
+              [K in keyof T & `${number}`]-?: LocateChild<
+                T[K],
+                `${P}[${K}]`,
+                D
+              >;
+            }[keyof T & `${number}`]
+        : T extends object
+          ? LocateFields<T, P, D, OwnUnsafeKeys<T>>
+          : never;
+
+/**
+ * Keys whose value is unsafe itself, not through something nested in it.
+ * `any` is never one: it passes LocationStateSafe, so reporting it would
+ * leave nothing to report and hide its siblings' paths.
+ */
+type OwnUnsafeKeys<T> = {
+  [K in keyof T]-?: IsAny<T[K]> extends true
+    ? never
+    : IsUnknown<T[K]> extends true
+      ? K
+      : [UnsafeReason<T[K]>] extends [never]
+        ? never
+        : K;
+}[keyof T];
+
+type LocateFields<
+  T,
+  P extends string,
+  D extends unknown[],
+  Own extends keyof T,
+> = [Own] extends [never]
+  ? { [K in keyof T]-?: LocateChild<T[K], ChildPath<P, K>, D> }[keyof T]
+  : { [K in Own]-?: LocateChild<T[K], ChildPath<P, K>, D> }[Own];
+
+type LocateChild<T, P extends string, D extends unknown[]> = [T] extends [
+  LocationStateSafe<T>,
+]
+  ? never
+  : LocateUnsafe<T, P, [...D, unknown]>;
+
+type GenericReason =
+  "location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival";
 
 /**
  * `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.
+ * branded {@link LocationStateUnsafe} object naming the reason and the path of
+ * each offending field, e.g. `LocationStateUnsafe<"...", "items[].info.values">`.
+ * 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 and the field — 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">;
+  : OrGenericUnsafe<LocateUnsafe<T, "", []>>;
+
+type OrGenericUnsafe<U> = [U] extends [never]
+  ? LocationStateUnsafe<GenericReason>
+  : U;
 
 /**
  * Type-safe location state definition
@@ -101,7 +234,10 @@ export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>]
  */
 export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   (...args: TArgs): LocationStateEntry;
-  /** Injected by Vite plugin - do not set manually */
+  /**
+   * Injected by Vite plugin - do not set manually. Unit tests without the
+   * plugin use withLocationStateKey() from @rangojs/router/testing.
+   */
   __rsc_ls_key: string;
   /** Whether this state auto-clears after first read */
   readonly __rsc_ls_flash: boolean;
@@ -117,6 +253,13 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
    * want React to manage subscription/hydration for you.
    */
   read(): TState | undefined;
+  /**
+   * Read this definition's slot from a location snapshot instead of the
+   * current entry: a transition({ when }) context's `from` / `to`, or any
+   * `{ state }` holding a `history.state` object. A snapshot read never clears
+   * flash state.
+   */
+  read(location: { readonly state: unknown }): TState | undefined;
   /**
    * Statically write the value into the current history entry under this
    * definition's key, preserving any other keys already on history.state
@@ -187,6 +330,26 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  * ProductState.delete();
  * ```
  */
+let onCurrentStateReplaced: (() => void) | undefined;
+
+/**
+ * @internal The navigation store registers here (navigation-store.ts) to
+ * refresh its per-entry memory: back/forward reads the entry being left from
+ * that memory (at popstate history.state already belongs to the destination),
+ * so a write after the entry's commit must reach it.
+ */
+export function setCurrentHistoryStateListener(
+  listener: (() => void) | undefined,
+): void {
+  onCurrentStateReplaced = listener;
+}
+
+/** Replace the current entry's history.state in place (same URL). */
+export function replaceCurrentHistoryState(state: unknown): void {
+  window.history.replaceState(state, "", window.location.href);
+  onCurrentStateReplaced?.();
+}
+
 export function createLocationState<TState>(
   options?: LocationStateOptions,
 ): LocationStateDefinition<
@@ -196,12 +359,17 @@ export function createLocationState<TState>(
   const flash = options?.flash ?? false;
   let _key: string | undefined;
 
+  // Dev and test throw; production folds the check away (the plugin always
+  // injects the key there). Without it, reads and writes silently target
+  // history.state["undefined"].
   function getKey(): string {
-    if (!_key && process.env.NODE_ENV === "development") {
+    if (!_key && process.env.NODE_ENV !== "production") {
       throw new Error(
         "[rango] createLocationState key not set. " +
           "Make sure the exposeInternalIds Vite plugin is enabled and " +
-          "the state is exported with: export const MyState = createLocationState(...)",
+          "the state is exported with: export const MyState = createLocationState(...). " +
+          "In a unit test without the plugin, assign one with " +
+          "withLocationStateKey(MyState) from @rangojs/router/testing.",
       );
     }
     return _key!;
@@ -239,7 +407,13 @@ export function createLocationState<TState>(
   });
 
   Object.defineProperty(fn, "read", {
-    value: (): TState | undefined => {
+    value: (location?: { readonly state: unknown }): TState | undefined => {
+      if (location !== undefined) {
+        const state = location.state;
+        return state !== null && typeof state === "object"
+          ? ((state as Record<string, unknown>)[getKey()] as TState | undefined)
+          : undefined;
+      }
       if (typeof window === "undefined") return undefined;
       return window.history.state?.[getKey()] as TState | undefined;
     },
@@ -263,11 +437,7 @@ export function createLocationState<TState>(
       const existing = window.history.state;
       const current =
         existing !== null && typeof existing === "object" ? existing : {};
-      window.history.replaceState(
-        { ...current, [key]: value },
-        "",
-        window.location.href,
-      );
+      replaceCurrentHistoryState({ ...current, [key]: value });
     },
     enumerable: true,
   });
@@ -290,7 +460,7 @@ export function createLocationState<TState>(
         return;
       const next = { ...current };
       delete next[key];
-      window.history.replaceState(next, "", window.location.href);
+      replaceCurrentHistoryState(next);
     },
     enumerable: true,
   });
@@ -301,6 +471,28 @@ export function createLocationState<TState>(
   >;
 }
 
+/**
+ * A definition's key, or undefined when none is set, without the missing-key
+ * throw of the `__rsc_ls_key` getter. For dev checks and test helpers.
+ */
+export function peekLocationStateKey(definition: object): string | undefined {
+  try {
+    return (definition as { __rsc_ls_key?: string }).__rsc_ls_key || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Check if a value is a LocationStateDefinition (a createLocationState()
+ * result, callable, not an entry).
+ */
+export function isLocationStateDefinition(
+  value: unknown,
+): value is LocationStateDefinition<unknown[], unknown> {
+  return typeof value === "function" && "__rsc_ls_flash" in value;
+}
+
 /**
  * Check if a value is a LocationStateEntry
  */

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

@@ -1,7 +1,10 @@
 "use client";
 
 import { useState, useEffect, useRef } from "react";
-import type { LocationStateDefinition } from "./location-state-shared.js";
+import {
+  replaceCurrentHistoryState,
+  type LocationStateDefinition,
+} from "./location-state-shared.js";
 
 export {
   createLocationState,
@@ -124,7 +127,7 @@ export function useLocationState<TArgs extends unknown[], TState>(
     if (isFlash && key && state !== undefined) {
       const cleaned = { ...window.history.state };
       delete cleaned[key];
-      window.history.replaceState(cleaned, "", window.location.href);
+      replaceCurrentHistoryState(cleaned);
     }
   }, [isFlash, key, state]);
 

package/src/browser/rsc-router.tsx

@@ -226,6 +226,10 @@ export async function initBrowserApp(
     ...(storeOptions?.cacheSize && { cacheSize: storeOptions.cacheSize }),
   });
 
+  // The document's entry: the transition({ when }) source of the first
+  // navigation, and of a later back/forward that leaves it.
+  store.rememberDisplayedEntry(initialPayload.metadata?.routeName);
+
   // Register the active store on the module-level handle and wire the
   // jar-divergence observer before any getRangoState() read can detect a
   // cross-tab/server rotation. There is no global store singleton, so this