@rangojs/router 0.28.0 → 0.30.0

package/src/browser/react/use-link-status.ts

@@ -5,12 +5,10 @@ import {
   useContext,
   useState,
   useEffect,
-  useRef,
-  useOptimistic,
-  startTransition,
   type Context,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
+import type { EventController, NavigationEntry } from "../event-controller.js";
 
 /**
  * Context for Link component to provide its destination URL
@@ -43,24 +41,45 @@ function normalizeUrl(url: string, origin: string): string {
 }
 
 /**
- * Check if this link's destination matches the pending navigation URL
+ * The navigation in flight a link can be pending for. One that shows no
+ * loading state (a background revalidation, an action's refetch) is none: it
+ * goes to no link and ends none whose page React still holds.
+ */
+function visibleNavigation(ec: EventController): NavigationEntry | null {
+  const navigation = ec.getCurrentNavigation();
+  return navigation && !navigation.options?.skipLoadingState
+    ? navigation
+    : null;
+}
+
+/**
+ * Whether `navigation` goes to `linkTo`: its URL or, after a server redirect,
+ * the URL its chain started from.
  */
 function isPendingFor(
   linkTo: string | null,
-  pendingUrl: string | null,
+  navigation: NavigationEntry | null,
   origin: string,
 ): boolean {
-  if (linkTo === null || pendingUrl === null) {
+  if (linkTo === null || !navigation) {
     return false;
   }
-  return normalizeUrl(pendingUrl, origin) === normalizeUrl(linkTo, origin);
+  const to = normalizeUrl(linkTo, origin);
+  const from = navigation.options?._redirectFrom;
+  return (
+    normalizeUrl(navigation.url, origin) === to ||
+    (from !== undefined && normalizeUrl(from, origin) === to)
+  );
 }
 
 /**
  * Hook to track the pending state of a Link component
  *
- * Must be used inside a Link component. Returns `{ pending: true }`
- * when navigation to this link's destination is in progress.
+ * Must be used inside a Link component. Returns `{ pending: true }` while a
+ * navigation to the link's destination is in flight, until the page it
+ * brings commits: under transition() while React holds that page, and
+ * through a server redirect until the target page commits. A newer
+ * navigation ends it at once.
  *
  * Useful for showing inline loading indicators on individual links.
  *
@@ -84,63 +103,32 @@ export function useLinkStatus(): LinkStatus {
 
   const origin = ctx?.origin ?? "http://localhost";
 
-  const [basePending, setBasePending] = useState<boolean>(() => {
-    if (!ctx || linkTo === null) {
-      return false;
-    }
-    const state =
-      ctx.eventController.getHydrationSnapshot()?.state ??
-      ctx.eventController.getState();
-    return isPendingFor(linkTo, state.pendingUrl, origin);
-  });
-
-  const prevPending = useRef(basePending);
-
-  // 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.
-  const optimisticPinnedRef = useRef(false);
-
-  const [pending, setOptimisticPending] = useOptimistic(basePending);
-
+  // The document renders no navigation in flight.
+  const [pending, setPending] = useState<boolean>(
+    () =>
+      !!ctx &&
+      !ctx.eventController.getHydrationSnapshot() &&
+      isPendingFor(linkTo, visibleNavigation(ctx.eventController), origin),
+  );
+
+  // The value commits in the lane of the notification that carries it, as
+  // useNavigation's does: at once from the click's task, and with the page
+  // when its commit clears the navigation (NavigationProvider flushes that
+  // notification inside the page's update). Set once per navigation: a
+  // repeated urgent set would commit ahead of a held page's settle. A
+  // background navigation (an action's refetch) is not a newer one, so a
+  // held link stays pending.
   useEffect(() => {
     if (!ctx || linkTo === null) {
       return;
     }
 
+    let last: NavigationEntry | null | undefined;
     const update = () => {
-      const state = ctx.eventController.getState();
-      const isPending = isPendingFor(linkTo, state.pendingUrl, origin);
-
-      if (isPending !== prevPending.current) {
-        prevPending.current = isPending;
-
-        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);
-      }
+      const navigation = visibleNavigation(ctx.eventController);
+      if (navigation === last) return;
+      last = navigation;
+      setPending(isPendingFor(linkTo, navigation, origin));
     };
 
     // Catch-up: re-read state synchronously on mount before subscribing, so a

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

@@ -1,17 +1,14 @@
 "use client";
 
-import {
-  useContext,
-  useState,
-  useEffect,
-  useLayoutEffect,
-  startTransition,
-  useRef,
-} from "react";
+import { useContext, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
+import { useRouteState } from "./use-route-state.js";
 import type { PublicNavigationState } from "../types.js";
-import type { DerivedNavigationState } from "../event-controller.js";
+import type {
+  DerivedNavigationState,
+  RouteStateSignal,
+} from "../event-controller.js";
 
 /**
  * Convert derived state to public version (strips inflightActions)
@@ -21,6 +18,32 @@ function toPublicState(state: DerivedNavigationState): PublicNavigationState {
   return publicState;
 }
 
+/** The state a value was selected from, and the value. */
+interface Snapshot<T> {
+  state: PublicNavigationState;
+  value: T;
+}
+
+/**
+ * A notification while React holds a page: work that starts shows at once
+ * (loading, streaming, a newer click's URL), what settles waits for the
+ * page's commit (rango-d152), and location moves only with the notification
+ * that moves it (the page on screen until the next one shows).
+ */
+function hold(
+  base: PublicNavigationState,
+  live: PublicNavigationState,
+  moved: boolean,
+): PublicNavigationState {
+  return {
+    state: live.state === "loading" ? live.state : base.state,
+    isStreaming: live.isStreaming || base.isStreaming,
+    isNavigating: live.isNavigating || base.isNavigating,
+    pendingUrl: live.pendingUrl ?? base.pendingUrl,
+    location: moved ? live.location : base.location,
+  };
+}
+
 /**
  * Hook to access reactive navigation state with optional selector for performance.
  *
@@ -46,19 +69,20 @@ export function useNavigation<T>(
     throw new Error("useNavigation must be used within NavigationProvider");
   }
 
-  const [value, setValue] = useState<T | PublicNavigationState>(() => {
-    const publicState = toPublicState(
-      ctx.eventController.getHydrationSnapshot()?.state ??
-        ctx.eventController.getState(),
-    );
-    return selector ? selector(publicState) : publicState;
-  });
-  const prevState = useRef(value);
-  // The value on screen: a set value that differs has not committed yet.
-  const committedRef = useRef(value);
-  useLayoutEffect(() => {
-    committedRef.current = value;
-  });
+  // A release is compared with the state React renders it on
+  // (useRouteState). The anchor is compared with the last set, as an
+  // ordinary notification is: it sets inside its page's transition, which
+  // renders every set so far.
+  const [snapshot, set] = useRouteState<Snapshot<T | PublicNavigationState>>(
+    () => {
+      const state = toPublicState(
+        ctx.eventController.getHydrationSnapshot()?.state ??
+          ctx.eventController.getState(),
+      );
+      return { state, value: selector ? selector(state) : state };
+    },
+    (a, b) => shallowEqual(a.value, b.value),
+  );
 
   // Store selector in a ref so the subscription callback always uses the
   // latest selector without re-subscribing on every render (inline functions
@@ -74,34 +98,28 @@ export function useNavigation<T>(
   // the location hooks' values do: NavigationProvider flushes a navigation's
   // notification into the transition that commits its tree, so idle commits
   // with the destination's location (useSearchParams, usePathname,
-  // useParams). An optimistic update renders in the sync lane, ahead of that
-  // transition, and put idle on screen with the location being left (#1164).
+  // useParams). From that page's anchor to its release every other
+  // notification goes through hold(), urgently, so React rebases the same
+  // update onto the page when it commits. Never a transition of its own.
   useEffect(() => {
-    let last: DerivedNavigationState | undefined;
-    const update = () => {
-      const currentState = ctx.eventController.getState();
-      // Neither the state nor the location moved (the stream starting or
-      // ending): while a value of this hook's is held, a transition, which
-      // React entangles with it, so it never commits ahead of the location.
-      // Otherwise urgent: a transition of its own would start a view
-      // transition, and could commit ahead of a held page and take its
-      // transition types.
-      const quiet =
-        currentState.state === last?.state &&
-        currentState.location === last.location;
-      last = currentState;
-      const publicState = toPublicState(currentState);
-      const nextSelected = selectorRef.current
-        ? selectorRef.current(publicState)
-        : publicState;
-
-      // Check if selected value has changed
-      if (!shallowEqual(nextSelected, prevState.current)) {
-        const held = prevState.current !== committedRef.current;
-        prevState.current = nextSelected;
-        if (quiet && held) startTransition(() => setValue(nextSelected));
-        else setValue(nextSelected);
-      }
+    let pageHeld = false;
+    let location: PublicNavigationState["location"] | undefined;
+    const select = (state: PublicNavigationState) =>
+      selectorRef.current ? selectorRef.current(state) : state;
+    const update = (signal?: RouteStateSignal) => {
+      if (signal) pageHeld = signal === "anchor";
+      const live = toPublicState(ctx.eventController.getState());
+      const moved = live.location !== location;
+      location = live.location;
+      const held = pageHeld && !signal;
+      set(
+        (base) => {
+          const state = held ? hold(base.state, live, moved) : live;
+          return { state, value: select(state) };
+        },
+        signal,
+        held,
+      );
     };
 
     // Catch-up: re-read state synchronously on mount before subscribing, so a
@@ -110,8 +128,15 @@ export function useNavigation<T>(
     // useSearchParams.
     update();
 
-    return ctx.eventController.subscribe(update);
+    const unsubscribe = ctx.eventController.subscribe(update);
+    // The anchor and release signals ride the handle channel. One without a
+    // signal re-reads the same state, as the state channel's own would.
+    const unsubscribeSignals = ctx.eventController.subscribeToHandles(update);
+    return () => {
+      unsubscribe();
+      unsubscribeSignals();
+    };
   }, []);
 
-  return value as T | PublicNavigationState;
+  return snapshot.value as T | PublicNavigationState;
 }

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

@@ -1,12 +1,10 @@
 "use client";
 
-import { useContext, useState, useEffect, useRef } from "react";
-import { NavigationStoreContext } from "./context.js";
+import { useContext } from "react";
 import { shallowEqual } from "./shallow-equal.js";
+import { useUrlValue } from "./use-route-state.js";
 import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
-const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
-
 /**
  * Hook to access the current route params.
  *
@@ -45,38 +43,11 @@ export function useParams<T>(
 export function useParams<T>(
   selector?: (params: Record<string, string | undefined>) => T,
 ): T | Record<string, string | undefined> {
-  const ctx = useContext(NavigationStoreContext);
   const optimistic = useContext(OptimisticLocationContext);
-
-  const [value, setValue] = useState<T | Record<string, string>>(() => {
-    const params = ctx
-      ? (ctx.eventController.getHydrationSnapshot()?.params ??
-        ctx.eventController.getParams())
-      : EMPTY_PARAMS;
-    return selector ? selector(params) : params;
-  });
-
-  const prevValue = useRef(value);
-  const selectorRef = useRef(selector);
-  selectorRef.current = selector;
-
-  useEffect(() => {
-    if (!ctx) return;
-
-    const update = () => {
-      const params = ctx.eventController.getParams();
-      const next = selectorRef.current ? selectorRef.current(params) : params;
-
-      if (!shallowEqual(next, prevValue.current)) {
-        prevValue.current = next;
-        setValue(next);
-      }
-    };
-
-    update();
-
-    return ctx.eventController.subscribe(update);
-  }, []);
+  const value = useUrlValue<T | Record<string, string>>(
+    ({ params }) => (selector ? selector(params) : params),
+    shallowEqual,
+  );
 
   if (optimistic) {
     return selector ? selector(optimistic.params) : optimistic.params;

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

@@ -1,7 +1,7 @@
 "use client";
 
-import { useContext, useState, useEffect, useRef } from "react";
-import { NavigationStoreContext } from "./context.js";
+import { useContext } from "react";
+import { useUrlValue } from "./use-route-state.js";
 import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
 /**
@@ -19,36 +19,7 @@ import { OptimisticLocationContext } from "../../client-urls/optimistic-location
  * ```
  */
 export function usePathname(): string {
-  const ctx = useContext(NavigationStoreContext);
   const optimistic = useContext(OptimisticLocationContext);
-
-  const [pathname, setPathname] = useState<string>(() => {
-    if (!ctx) {
-      return "/";
-    }
-    const state =
-      ctx.eventController.getHydrationSnapshot()?.state ??
-      ctx.eventController.getState();
-    return (state.location as URL).pathname;
-  });
-
-  const prevPathname = useRef(pathname);
-
-  useEffect(() => {
-    if (!ctx) return;
-
-    const update = () => {
-      const next = (ctx.eventController.getState().location as URL).pathname;
-      if (next !== prevPathname.current) {
-        prevPathname.current = next;
-        setPathname(next);
-      }
-    };
-
-    update();
-
-    return ctx.eventController.subscribe(update);
-  }, []);
-
+  const pathname = useUrlValue((route) => route.location.pathname, Object.is);
   return optimistic ? optimistic.pathname : pathname;
 }

package/src/browser/react/use-route-state.ts

@@ -0,0 +1,141 @@
+"use client";
+
+import {
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { NavigationStoreContext } from "./context.js";
+import type { EventController, RouteStateSignal } from "../event-controller.js";
+
+/**
+ * The value a reader rendered in React's last commit of it, written by its
+ * layout effect. A page's release runs in the provider's layout effect, after
+ * every reader's (children first), so it reads the commit that brings the
+ * page.
+ */
+export function useCommitted<T>(value: T): { readonly current: T } {
+  const committed = useRef(value);
+  useLayoutEffect(() => {
+    committed.current = value;
+  }, [value]);
+  return committed;
+}
+
+/**
+ * Sets a route-state reader's value. `next` maps the value React ends on once
+ * every set so far commits (`latest`) to the reader's value; `rebase` sets
+ * `next` itself, so React recomputes it on whatever base it renders. The value
+ * must not be a function.
+ */
+export type RouteStateSetter<T> = (
+  next: (base: T) => T,
+  signal?: RouteStateSignal,
+  rebase?: boolean,
+) => void;
+
+/**
+ * Route state a reader sets as the router store notifies it, in the lane of
+ * the notification that carries it. A notification equal to `latest` sets
+ * nothing, so a reader renders only when its value moves.
+ *
+ * A release is compared with what React committed, not with `latest`: while
+ * React holds a page, its set is not on screen, and an urgent page that ends
+ * the hold brings an equal value. A release that finds every set committed
+ * with its value sets nothing.
+ */
+export function useRouteState<T>(
+  init: () => T,
+  same: (a: T, b: T) => boolean,
+): [T, RouteStateSetter<T>] {
+  const [value, setValue] = useState(init);
+  const latest = useRef(value);
+  const committed = useCommitted(value);
+  const [set] = useState(
+    (): RouteStateSetter<T> => (next, signal, rebase) => {
+      const target = next(latest.current);
+      if (signal === "release") {
+        if (
+          latest.current === committed.current &&
+          same(target, latest.current)
+        )
+          return;
+        latest.current = target;
+        setValue((prev) => (same(prev, target) ? prev : target));
+        return;
+      }
+      if (same(target, latest.current)) return;
+      latest.current = target;
+      setValue(rebase ? next : target);
+    },
+  );
+  return [value, set];
+}
+
+/** The route a URL hook reads. */
+export interface UrlRoute {
+  location: URL;
+  params: Record<string, string>;
+}
+
+const NO_ROUTE: UrlRoute = {
+  location: new URL("/", "http://localhost"),
+  params: Object.freeze({}) as Record<string, string>,
+};
+
+const routeOf = (controller: EventController): UrlRoute => ({
+  location: controller.getState().location,
+  params: controller.getParams(),
+});
+
+/**
+ * A URL hook's value (usePathname, useParams, useSearchParams): `read` of the
+ * route, seeded from the hydration snapshot while the document hydrates, then
+ * set as the store notifies it and at a page's release (useRouteState). The
+ * release rides the handle channel. `read` applies when the store changes,
+ * never in a later render: a new one takes effect from the next change.
+ *
+ * A read equal to the value it is set over keeps that value, so an object
+ * reader changes identity once per value: a release that ends a hold sets the
+ * held page's object, which React's render of the held lane keeps.
+ */
+export function useUrlValue<T>(
+  read: (route: UrlRoute) => T,
+  same: (a: T, b: T) => boolean,
+): T {
+  const ctx = useContext(NavigationStoreContext);
+  const [value, set] = useRouteState(() => {
+    if (!ctx) return read(NO_ROUTE);
+    const hydration = ctx.eventController.getHydrationSnapshot();
+    return read(
+      hydration
+        ? { location: hydration.state.location, params: hydration.params }
+        : routeOf(ctx.eventController),
+    );
+  }, same);
+  const readRef = useRef(read);
+  readRef.current = read;
+
+  useEffect(() => {
+    if (!ctx) return;
+    const controller = ctx.eventController;
+    const update = (signal?: RouteStateSignal): void => {
+      const next = readRef.current(routeOf(controller));
+      set((base) => (same(next, base) ? base : next), signal);
+    };
+    // Catch up with a change between the seeding render and this effect.
+    update();
+    const unsubscribe = controller.subscribe(update);
+    const unsubscribeRelease = controller.subscribeToHandles((signal) => {
+      if (signal === "release") update(signal);
+    });
+    return () => {
+      unsubscribe();
+      unsubscribeRelease();
+    };
+  }, []);
+
+  return value;
+}

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

@@ -1,14 +1,8 @@
 "use client";
 
-import {
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { useCallback, useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
+import { useUrlValue } from "./use-route-state.js";
 import type { ReadonlyURLSearchParams } from "../types.js";
 import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
@@ -113,38 +107,11 @@ export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
   const ctx = useContext(NavigationStoreContext);
   const optimistic = useContext(OptimisticLocationContext);
 
-  // Seed from the store location on BOTH sides (mirrors usePathname): the
-  // SSR store carries the live request's search, the browser store carries
-  // window.location — same URL, so the hydration renders agree. No ctx
-  // (no provider) seeds empty.
-  const [searchParams, setSearchParamsState] =
-    useState<ReadonlyURLSearchParams>(() => {
-      const state = ctx
-        ? (ctx.eventController.getHydrationSnapshot()?.state ??
-          ctx.eventController.getState())
-        : undefined;
-      const location = state?.location as URL | undefined;
-      return new URLSearchParams(location?.searchParams);
-    });
-
-  const prevSearch = useRef(searchParams.toString());
-
-  useEffect(() => {
-    if (!ctx) return;
-
-    const update = () => {
-      const location = ctx.eventController.getState().location as URL;
-      const nextSearch = location.searchParams.toString();
-      if (nextSearch !== prevSearch.current) {
-        prevSearch.current = nextSearch;
-        setSearchParamsState(new URLSearchParams(nextSearch));
-      }
-    };
-
-    update();
-
-    return ctx.eventController.subscribe(update);
-  }, []);
+  // A new object only when the string changes.
+  const searchParams = useUrlValue<ReadonlyURLSearchParams>(
+    (route) => new URLSearchParams(route.location.searchParams),
+    (a, b) => a.toString() === b.toString(),
+  );
 
   // Reads the committed location at CALL time (not the render closure), so a
   // functional init always merges against fresh params even when the caller's

package/src/browser/segment-reconciler.ts

@@ -260,3 +260,46 @@ export function reconcileErrorSegments(
     interceptSegments: intercept,
   };
 }
+
+/**
+ * The ids a page holds once an action's error boundary `boundary` shows: the
+ * ones above it. Nothing at or below the boundary ran after the action's
+ * write (its response and the follow-up cut there), so the next request must
+ * not hold it. ShortCodes nest, so those ids start with the boundary's: the
+ * boundary, its loaders (`${id}D…`), its slots and every entry under it. A
+ * sibling with a longer index (`…R10` beside `…R1`) is kept.
+ */
+export function idsAboveBoundary(
+  ids: string[],
+  boundary: string | undefined,
+): string[] {
+  return boundary
+    ? ids.filter(
+        (id) =>
+          !id.startsWith(boundary) || /\d/.test(id.charAt(boundary.length)),
+      )
+    : ids;
+}
+
+/**
+ * The error segment of every action error boundary committed, by identity
+ * (server-action-bridge.ts adds and deletes). An entry shows one while its
+ * cached list still holds that object: a later commit on the entry replaces
+ * the list, and a refetch that holds the boundary keeps it. Weak, so a
+ * replaced boundary is not kept alive. Two routers never share a segment
+ * object. No hook reads it.
+ */
+export const actionBoundaries: WeakSet<ResolvedSegment> = new WeakSet();
+
+/**
+ * The index of the deepest action error boundary in `segments`, -1 for none.
+ * It is that action's outcome, which no GET reproduces: a background refetch
+ * of the page (the follow-up, Back/Forward's stale revalidation, the
+ * cross-tab refresh) holds it and renders what is above it. At 0 nothing is
+ * above it.
+ */
+export function actionBoundaryAt(segments: readonly ResolvedSegment[]): number {
+  let at = segments.length;
+  while (at-- && !actionBoundaries.has(segments[at]));
+  return at;
+}