@rangojs/router 0.27.0 → 0.29.0

package/src/browser/prefetch/fetch.ts

@@ -38,6 +38,7 @@ import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../../segment-fragments.js";
 import { PREFETCH_HEADER } from "../../prefetch-markers.js";
 import type { RscPayload } from "../types.js";
 import { getRegisteredStore } from "../navigation-store-handle.js";
+import { writePartialParams } from "../wire-protocol.js";
 
 /**
  * Decoder injected at app startup (see setPrefetchDecoder). This is
@@ -153,24 +154,15 @@ function buildPrefetchUrl(
   if (targetUrl.origin !== window.location.origin) {
     return null;
   }
-  targetUrl.searchParams.set("_rsc_partial", "true");
-  if (segmentIds.length > 0) {
-    targetUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
-  }
-  if (version) {
-    targetUrl.searchParams.set("_rsc_v", version);
-  }
-  if (routerId) {
-    targetUrl.searchParams.set("_rsc_rid", routerId);
-  }
   // The page's rewrite target, so the server diffs against the route that
   // rendered it, as for the navigation.
-  const rewriteTarget =
-    getRegisteredStore()?.getHistoryEntryMemory()?.rewriteTarget;
-  if (rewriteTarget) {
-    targetUrl.searchParams.set("_rsc_rt", rewriteTarget);
-  }
-  return targetUrl;
+  return writePartialParams(targetUrl, {
+    segmentIds,
+    emptySegments: "omit",
+    version,
+    routerId,
+    rewriteTarget: getRegisteredStore()?.getHistoryEntryMemory()?.rewriteTarget,
+  });
 }
 
 /**

package/src/browser/prefetch/queue.ts

@@ -15,6 +15,7 @@
  */
 
 import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
+import { WIRE_PREFIX } from "../../wire-params.js";
 
 // Max prefetches executing at once. Mirrors DEFAULT_PREFETCH_CONCURRENCY
 // (router/prefetch-limits.ts); kept as a local literal so the client bundle
@@ -128,16 +129,15 @@ export function enqueuePrefetch(
 
 /**
  * Normalize a URL-like string for keep-alive matching: parse against a
- * placeholder origin and strip internal `_rsc_*` query params. Returns
+ * placeholder origin and strip every `WIRE_PREFIX` query param. Returns
  * `pathname + search` so comparisons ignore hash and the internal params
- * that prefetch appends to targets (`_rsc_partial`, `_rsc_segments`,
- * `_rsc_v`, `_rsc_rid`, `_rsc_stale`).
+ * that prefetch appends to targets.
  */
 function normalizeForMatch(urlish: string): string {
   try {
     const u = new URL(urlish, "http://placeholder");
     for (const k of [...u.searchParams.keys()]) {
-      if (k.startsWith("_rsc_")) u.searchParams.delete(k);
+      if (k.startsWith(WIRE_PREFIX)) u.searchParams.delete(k);
     }
     return u.pathname + u.search;
   } catch {

package/src/browser/react/NavigationProvider.tsx

@@ -78,7 +78,8 @@ async function processHandles(
 
   // This nav's instance token, captured before any await — processHandles runs
   // right after its own commit, so this is that commit's token. generateHistoryKey
-  // is URL-only, so an A->B->A revisit reuses the key; the token lets a late
+  // is the URL (plus the source page for an intercept), so an A->B->A revisit
+  // reuses the key; the token lets a late
   // resolution tell its own visit apart from a newer same-URL visit, so a stale
   // nav can never clobber a fresher one's live state or cache (P1).
   const myInstance = store.getNavInstance();

package/src/browser/react/filter-segment-order.ts

@@ -33,8 +33,8 @@ export function loaderParentId(id: string): string {
  * 2. Place each parallel slot id (contains ".@") immediately after its
  *    parent layout/route id. Raw segment-resolution emission order does NOT
  *    guarantee this: route-mounted parallels are resolved/pushed BEFORE the
- *    route handler's segment is appended (see fresh.ts:resolveSegment for
- *    routes, and revalidation.ts ~915-919), so matched can read
+ *    route handler's segment is appended (see resolveSegment in
+ *    segment-resolution/revalidation.ts), so matched can read
  *    `[..., R0.@panel, R0]`. collectHandleData consumes segmentOrder verbatim
  *    with later-wins semantics, so without normalization the route handler's
  *    Meta would override the slot's more-specific Meta — backwards.

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

@@ -1,13 +1,6 @@
 "use client";
 
-import {
-  useContext,
-  useState,
-  useEffect,
-  useRef,
-  useOptimistic,
-  startTransition,
-} from "react";
+import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 import type { TrackedActionState } from "../types.js";
@@ -83,14 +76,19 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * Features:
  * - Tracks action lifecycle: idle → loading → streaming → idle
  * - Captures result/error locally (React handles cleanup)
- * - If multiple actions fire, tracks only the last one
+ * - If the same action fires several times, reports the latest call to
+ *   start. An earlier call that settles later changes nothing it reports;
+ *   a latest call that was aborted reports idle with nothing. One call at a
+ *   time, not one per argument: a reader filtering on `payload` cannot track
+ *   an earlier call once a later one starts.
  * - Supports selector pattern like useNavigation
  *
  * Matching behavior:
  * - **Function reference**: Uses full $$id for exact matching. This is precise
  *   and distinguishes between actions with the same name in different files.
  * - **String**: Matches by suffix (action name after #). This is convenient
- *   but may be ambiguous if multiple files export the same action name.
+ *   but may be ambiguous if multiple files export the same action name: it
+ *   follows the latest call of any action with that export name.
  *
  * @param action - Either a server action function or a string action name.
  *   - **Function**: Must be directly imported in the client component.
@@ -138,8 +136,10 @@ export function useAction<T>(
       ? getActionId(action)
       : "";
 
-  // Base state for useOptimistic
-  const [baseState, setBaseState] = useState<T | TrackedActionState>(() => {
+  // Set urgently from notifyAction's task, also while React holds a page: a
+  // transition of its own would take the held page's transition types (see
+  // useNavigation).
+  const [value, setValue] = useState<T | TrackedActionState>(() => {
     if (!ctx) {
       return selector ? selector(DEFAULT_ACTION_STATE) : DEFAULT_ACTION_STATE;
     }
@@ -149,11 +149,8 @@ export function useAction<T>(
       : ctx.eventController.getActionState(actionId);
     return selector ? selector(state) : state;
   });
-  const prevSelected = useRef(baseState);
-  prevSelected.current = baseState;
-  const [optimisticState, setOptimisticState] = useOptimistic<
-    T | TrackedActionState
-  >(null!);
+  const prevSelected = useRef(value);
+  prevSelected.current = value;
 
   // Ref keeps the latest selector for subscription callbacks without
   // re-subscribing on every render. Selector changes themselves are not
@@ -166,41 +163,20 @@ export function useAction<T>(
   useEffect(() => {
     if (!ctx) return;
 
+    const sync = (state: TrackedActionState) => {
+      const selected = selectorRef.current ? selectorRef.current(state) : state;
+      if (!shallowEqual(selected, prevSelected.current)) {
+        prevSelected.current = selected;
+        setValue(selected);
+      }
+    };
     // Sync current state for the (possibly new) actionId so that switching
     // actions on an idle page doesn't leave stale data from the old action.
-    const currentState = ctx.eventController.getActionState(actionId);
-    const currentSelected = selectorRef.current
-      ? selectorRef.current(currentState)
-      : currentState;
-    if (!shallowEqual(currentSelected, prevSelected.current)) {
-      prevSelected.current = currentSelected;
-      setBaseState(currentSelected);
-    }
-
-    // Subscribe to action-specific updates
-    const unsubscribe = ctx.eventController.subscribeToAction(
-      actionId,
-      (state) => {
-        const selectedState = selectorRef.current
-          ? selectorRef.current(state)
-          : state;
-
-        if (!shallowEqual(selectedState, prevSelected.current)) {
-          prevSelected.current = selectedState;
-          setBaseState(selectedState);
-          startTransition(() => {
-            setOptimisticState(selectedState);
-          });
-        }
-      },
-    );
-
-    return () => {
-      unsubscribe();
-    };
+    sync(ctx.eventController.getActionState(actionId));
+    return ctx.eventController.subscribeToAction(actionId, sync);
   }, [actionId]);
 
-  return (optimisticState ?? baseState) as T | TrackedActionState;
+  return value;
 }
 
 export type { TrackedActionState };

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

@@ -53,7 +53,7 @@ export function useHandle<T, A, S>(
     return selectorRef.current ? selectorRef.current(collected) : collected;
   };
 
-  const [value, setValue] = useCommitAnchoredState(collect);
+  const [value, setValue] = useCommitAnchoredState(collect, true);
 
   useEffect(() => {
     if (!ctx) return;
@@ -68,25 +68,29 @@ export function useHandle<T, A, S>(
 }
 
 /**
- * Route state the controller's handle notifications drive (useHandle,
- * useSegments) commits with the page it belongs to. NavigationProvider
- * flushes the controller inside every payload update, so a value known then
- * is set in the page's lane. A page handed over urgently (signal "release")
- * takes a value that arrives before it commits the same way: set at default
- * priority, it renders in the page's lane, and the page's effects read it.
- * A page in a transition (signal "anchor") does not: until it commits
+ * Route state the controller's handle notifications drive commits with the
+ * page it belongs to. NavigationProvider flushes the controller inside every
+ * payload update, with signal "anchor" for a page in a transition and
+ * "release" for an urgent one, so the page's own change is set in the page's
+ * lane and the page's effects read it. From the anchor until the page commits
  * (releaseRouteState() from the provider's layout effect, signal "release"),
- * a new value waits, and is applied in the commit's task, right after the
- * page's own commit. In the page's lane, a value that suspends in a revealed
- * <Suspense> (a crumb's content) would hold the page; in a lane of its own,
- * it commits over the page being left and takes the page's transition types
- * (#1165); and a transition entangled with the page misses its commit when it
- * is set after React rendered the page, before its view transition's
- * mutation, and starts a view transition of its own. A value shallow-equal to
- * the last one sets nothing, so a reader renders only when its value moves.
+ * a later change waits and is applied in the commit's task, right after the
+ * page's own commit: set in a lane of its own, it would commit over the page
+ * being left (#1165).
+ *
+ * `waitForRelease`, set by useHandle only: the anchor's own change waits too,
+ * so a handle value lands right after its page's commit, never in its lane. A
+ * handle value can carry a promise that suspends, and in the page's lane one
+ * that suspends in a revealed <Suspense> would hold the page. Nothing
+ * useSegments reads can suspend, so it leaves it off and its path and
+ * location commit with their page.
+ *
+ * A value shallow-equal to the last one sets nothing, so a reader renders only
+ * when its value moves.
  */
 export function useCommitAnchoredState<T>(
   init: () => T,
+  waitForRelease?: boolean,
 ): [T, (value: T, signal?: RouteStateSignal) => void] {
   // An app that enables the React Compiler compiles the router too; its memo
   // cache gains nothing here and cost 107 B gzip in the router chunk.
@@ -102,8 +106,8 @@ export function useCommitAnchoredState<T>(
       r.last = next;
       r.held = true;
     }
-    // The anchor's own change goes in the page's lane, with the page.
-    if (!r.held || (r.waiting && signal !== "anchor")) return;
+    if (!r.held || (r.waiting && (waitForRelease || signal !== "anchor")))
+      return;
     r.held = false;
     setValue(() => r.last);
   });

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

@@ -5,13 +5,15 @@ import {
   useState,
   useEffect,
   useLayoutEffect,
-  startTransition,
   useRef,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.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 +23,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,18 +74,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);
+  const [snapshot, setSnapshot] = useState<Snapshot<T | PublicNavigationState>>(
+    () => {
+      const state = toPublicState(
+        ctx.eventController.getHydrationSnapshot()?.state ??
+          ctx.eventController.getState(),
+      );
+      return { state, value: selector ? selector(state) : state };
+    },
+  );
+  // What React ends on once every set so far commits, and what it committed.
+  const latest = useRef(snapshot);
+  const committed = useRef(snapshot);
   useLayoutEffect(() => {
-    committedRef.current = value;
+    committed.current = snapshot;
   });
 
   // Store selector in a ref so the subscription callback always uses the
@@ -74,34 +104,48 @@ 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;
+      const next = (
+        base: Snapshot<T | PublicNavigationState>,
+      ): Snapshot<T | PublicNavigationState> => {
+        const state = held ? hold(base.state, live, moved) : live;
+        return { state, value: select(state) };
+      };
+      const target = next(latest.current);
+      // A release is compared with the state React renders it on, not
+      // `latest`: an urgent page can end the hold before React commits the
+      // anchor's set. An anchor sets inside its page's transition, which
+      // renders every set so far, so `latest` is that state. A release that
+      // finds every set committed with its value sets nothing: the updater
+      // would render the reader again only to bail out.
+      if (signal === "release") {
+        if (
+          latest.current === committed.current &&
+          shallowEqual(target.value, latest.current.value)
+        )
+          return;
+        latest.current = target;
+        setSnapshot((prev) =>
+          shallowEqual(prev.value, target.value) ? prev : target,
+        );
+        return;
       }
+      if (shallowEqual(target.value, latest.current.value)) return;
+      latest.current = target;
+      setSnapshot(held ? next : target);
     };
 
     // Catch-up: re-read state synchronously on mount before subscribing, so a
@@ -110,8 +154,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/rsc-router.tsx

@@ -614,6 +614,7 @@ export async function initBrowserApp(
 
             const historyKey = generateHistoryKey(window.location.href, {
               intercept: responseIsIntercept,
+              interceptSource: interceptSourceUrl ?? undefined,
             });
             store.setHistoryKey(historyKey);
             const currentHandleData = liveHandleDataForCache(