@rangojs/router 0.17.0 → 0.19.0

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

@@ -39,6 +39,7 @@ import {
 } from "./intercept-utils.js";
 import { createAppShellRef } from "./app-shell.js";
 import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
+import { stripShellMissMarker } from "./history-state.js";
 import { setActiveInterceptTargets } from "../client-urls/navigation.js";
 
 // Vite HMR types are provided by vite/client
@@ -169,6 +170,10 @@ export async function initBrowserApp(
   } = options;
 
   bootLog("initBrowserApp start");
+  // Before any location read (the history key, the navigation store, the
+  // event controller): the server rendered the marked request for the clean
+  // URL, so the client starts from the same one and hydration agrees.
+  stripShellMissMarker();
   bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
@@ -221,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

package/src/browser/server-action-bridge.ts

@@ -2,6 +2,7 @@ import type {
   ServerActionBridge,
   ServerActionBridgeConfig,
   RscPayload,
+  ResolvedSegment,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { enterActionFence, exitActionFence } from "./action-fence.js";
@@ -38,6 +39,11 @@ import { mergeLocationState } from "./history-state.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
 import { getAppVersion } from "./app-version.js";
 import { collectClientRevalidationDecisions } from "../client-urls/navigation.js";
+import {
+  decideCommitGatedOff,
+  findActionFormData,
+  type TransitionWhenActionInput,
+} from "./transition-when.js";
 import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
@@ -137,6 +143,20 @@ export function createServerActionBridge(
     getVersion: getAppVersion,
   });
 
+  /**
+   * transition({ when }) for an action commit: the location on screen,
+   * refreshed by the response's params and route name when it carries them.
+   */
+  const decideActionGatedOff = (
+    segments: readonly ResolvedSegment[],
+    metadata: RscPayload["metadata"] | undefined,
+    action: TransitionWhenActionInput,
+  ): boolean =>
+    decideCommitGatedOff(store, segments, "action", {
+      from: metadata,
+      action,
+    });
+
   /**
    * Refetch current route via a navigation transaction.
    * Encapsulates the repeated pattern of creating a navTx + fetchPartialUpdate
@@ -146,6 +166,8 @@ export function createServerActionBridge(
     segments?: string[];
     interceptSourceUrl?: string | null;
     actionId?: string;
+    /** transition({ when }) `action` fields for the refetch commit. */
+    action?: TransitionWhenActionInput;
   }): Promise<void> {
     const src = opts?.interceptSourceUrl ?? null;
     const navTx = createNavigationTransaction(
@@ -169,6 +191,7 @@ export function createServerActionBridge(
           type: "action" as const,
           ...(src ? { interceptSourceUrl: src } : {}),
           ...(opts?.actionId !== undefined ? { actionId: opts.actionId } : {}),
+          ...(opts?.action ? { action: opts.action } : {}),
         },
       );
     } finally {
@@ -560,8 +583,22 @@ export function createServerActionBridge(
         // Reconcile error segments with cached tree
         const errorResult = reconcileErrorSegments(cachedSegments, segments);
 
+        // transition({ when }) decides the error-boundary commit too, with
+        // `action.error` set.
+        const errorGatedOff = decideActionGatedOff(
+          errorResult.segments,
+          metadata,
+          {
+            id,
+            formData: findActionFormData(args),
+            error:
+              returnValue && !returnValue.ok ? returnValue.data : undefined,
+          },
+        );
+
         // Render the full tree with error segment merged with parent layouts
         const errorTree = await renderSegments(errorResult.mainSegments, {
+          transitionGatedOff: errorGatedOff,
           isAction: true,
           interceptSegments:
             errorResult.interceptSegments.length > 0
@@ -605,11 +642,13 @@ export function createServerActionBridge(
           errorResult.segments,
           currentHandleData,
         );
+        store.rememberDisplayedEntry();
 
-        // Update UI with error boundary
-        startTransition(() => {
-          onUpdate({ root: errorTree, metadata: metadata! });
-        });
+        // Update UI with error boundary: urgent when transition({ when })
+        // gated it off, like every gated-off commit.
+        const errorUpdate = { root: errorTree, metadata: metadata! };
+        if (errorGatedOff) onUpdate(errorUpdate);
+        else startTransition(() => onUpdate(errorUpdate));
 
         // Throw the error so the action promise rejects
         if (returnValue && !returnValue.ok) {
@@ -697,6 +736,13 @@ export function createServerActionBridge(
       if (scenario.type !== "navigated-away") {
         applyActionLocationState(handle, metadata?.locationState);
       }
+      // transition({ when }) `action` for this action's commit, whichever
+      // lane applies it (normal, or a refetch below).
+      const whenAction: TransitionWhenActionInput = {
+        id,
+        formData: findActionFormData(args),
+        result: returnData,
+      };
 
       switch (scenario.type) {
         case "navigated-away": {
@@ -712,13 +758,15 @@ export function createServerActionBridge(
             // Invalidation is deferred to finalizeAction(); here we only trigger
             // the revalidation refetch of the new route (suppressed on keep).
             if (!scenario.onInterceptRoute && !keepCache) {
-              refetchRoute({ actionId: id }).catch((error) => {
-                if (isBackgroundSuppressible(error)) return;
-                console.error(
-                  "[Browser] Background revalidation failed:",
-                  error,
-                );
-              });
+              refetchRoute({ actionId: id, action: whenAction }).catch(
+                (error) => {
+                  if (isBackgroundSuppressible(error)) return;
+                  console.error(
+                    "[Browser] Background revalidation failed:",
+                    error,
+                  );
+                },
+              );
             }
             break;
           }
@@ -730,6 +778,7 @@ export function createServerActionBridge(
             await refetchRoute({
               interceptSourceUrl: store.getInterceptSourceUrl(),
               actionId: id,
+              action: whenAction,
             });
           }
           break;
@@ -743,7 +792,11 @@ export function createServerActionBridge(
           // resolving last must discharge a directive-free sibling's repair.
           // See the keep row in docs/design/rango-state-cookie.md (the all-keep
           // edge, and the benign re-mark-stale-after-refetch end-state delta).
-          await refetchRoute({ interceptSourceUrl, actionId: id });
+          await refetchRoute({
+            interceptSourceUrl,
+            actionId: id,
+            action: whenAction,
+          });
           break;
         }
 
@@ -766,6 +819,7 @@ export function createServerActionBridge(
             segments: segmentsToSend,
             interceptSourceUrl,
             actionId: id,
+            action: whenAction,
           });
           break;
         }
@@ -791,8 +845,22 @@ export function createServerActionBridge(
         }
 
         case "normal": {
+          // transition({ when }) for the action commit (kind "action"): the
+          // page does not move, so `to` is `from`. False commits urgently (a
+          // re-suspending segment streams its loading()) and switches every
+          // <ViewTransition> class to "none"; true keeps the startTransition.
+          // This commit runs after awaits, outside the transition React opens
+          // for a form action / useActionState call, so React does not force
+          // a transition on it. The tree shape never changes, so
+          // useActionState and other client state survive (#995).
+          const gatedOff = decideActionGatedOff(
+            fullSegments,
+            metadata,
+            whenAction,
+          );
           // Prepare new tree (await loader data resolution)
           const newTree = await renderSegments(reconciled.mainSegments, {
+            transitionGatedOff: gatedOff,
             isAction: true,
             interceptSegments:
               reconciled.interceptSegments.length > 0
@@ -832,10 +900,11 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
+          store.rememberDisplayedEntry(metadata?.routeName);
 
-          startTransition(() => {
-            onUpdate({ root: newTree, metadata: metadata! });
-          });
+          const actionUpdate = { root: newTree, metadata: metadata! };
+          if (gatedOff) onUpdate(actionUpdate);
+          else startTransition(() => onUpdate(actionUpdate));
           // Invalidation deferred to finalizeAction() (runs after this caches
           // the fresh segments), suppressed when the action called
           // keepClientCache().