@rangojs/router 0.20.0 → 0.21.0

package/skills/testing/server-tree.md

@@ -128,7 +128,7 @@ it("asserts the server-rendered host content", async () => {
 - A client boundary's props come back as REAL JS values after deserialization (a `Date` is a `Date`, not a `$D...` encoding) — but there is NO hydration and NO interaction; boundaries are inert placeholders carrying props.
 - Server COMPONENTS do not survive Flight as identities (they are executed during serialization), so `findElements` matches the host elements they PRODUCED, not the component function. Client islands keep identity — use `findClientBoundaries` for those.
 - `findClientBoundaries` finds islands (`I` rows); `findElements` finds host elements. A `testId` on an island matches with `findClientBoundaries`; a `testId` on a host element matches with `findElements`. Use `textContent(node)` in place of `JSON.stringify(tree).toContain`.
-- A true interactive, clickable DOM `renderServer` is intentionally NOT shipped: in-process happy-dom hydration re-tests React more than your app and misses server/client divergence (the only hydration bug worth a dedicated test, which needs a real browser). Test interaction at e2e.
+- A true interactive, clickable DOM `renderServer` is intentionally NOT shipped: in-process happy-dom hydration of a Flight tree re-tests React more than your app and misses the divergence that needs the real document (streaming order, client-reference identity, the browser's HTML parser). Test interaction at e2e. A CLIENT component's own server/client divergence is unit-reachable: `renderRoute` with `hydrate: true` ([`./client-components.md`](./client-components.md#hydration)).
 
 ## See also
 

package/skills/typesafety/generated-files-and-cli.md

@@ -113,7 +113,7 @@ and client helpers.
 CLI flags: the default mode fails (and writes nothing) when an `include()` cannot
 be resolved statically (factory functions, dynamic expressions); `--static`
 accepts partial output with warnings; `--runtime` uses Vite-based discovery for
-full coverage (needs `vite` and `@vitejs/plugin-rsc`, optional
+full coverage (needs `vite`, optional
 `--config <path>`). Passing a directory scans it for router and `urls()` files.
 
 ### Named Routes, `$$routeNames`, And `router.routeMap`

package/skills/use-cache/SKILL.md

@@ -485,11 +485,22 @@ the current time and expect freshness -- those are frozen at cache-write. The
 `cookies()`/`headers()` read guard applies to the cached function body, NOT to an
 inline action's body.
 
-Deploy note: captured values are encrypted with a per-build key by default. If
-cache entries can outlive a deploy (a persistent store such as the Cloudflare
-cache store), set `RANGO_ENCRYPTION_KEY` (base64-encoded 32 bytes) in the build
-environment so actions embedded in entries written by a previous deploy still
-decrypt; without it they fail until the entry expires or revalidates.
+Deploy note: captured values are encrypted with a key that is generated per
+build by default. Set a stable one in the plugin options:
+
+```ts
+rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY });
+```
+
+The value is base64-encoded 32 bytes (`openssl rand -base64 32`), never a
+literal, and is validated when `rango()` is called. `undefined` falls back to the
+`RANGO_ENCRYPTION_KEY` environment variable, then to a key generated per build.
+The key is part of the cache version of every router whose server code encrypts
+inline server-action bound arguments, so without a stable key those routers get a
+new version (and a cleared cache) on every build, and the build prints one note
+when that applies. With a stable key, actions embedded in entries written by a
+previous deploy still decrypt. A router that renders no inline action with bound
+arguments keeps its cache without a stable key. See `/cache-guide`.
 
 ## Vite Transform
 

package/skills/vercel/SKILL.md

@@ -98,9 +98,7 @@ const memoryStore = new MemorySegmentCacheStore({ defaults });
 // passes, since the tag markers are regional and only expireTag is global. A
 // platform expireTag issued outside rango writes no marker, so every memo
 // serves the shell until its window passes.
-const runtimeCache = process.env.VERCEL
-  ? getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })
-  : undefined;
+const runtimeCache = process.env.VERCEL ? getCache() : undefined;
 
 function resolveCache() {
   if (runtimeCache) {
@@ -120,6 +118,8 @@ export const router = createRouter({ cache: resolveCache }).routes(/* ... */);
 
 The cache factory receives `(env, ctx)`: on Vercel `env` is `process.env` and `ctx` is `{ waitUntil }`; off-platform `ctx` is `undefined`. Cache semantics and tag invalidation: `/caching`, `/cache-guide`.
 
+`getCache()` takes no deployment id: `VercelCacheStore` puts a version in front of every key itself (data version for families `s`, `i`; document version for `r`, `h`; none for tag markers), computed per `createRouter()` from its built code. A deploy that does not change a router keeps its entries; a deploy that changes it reads under new keys. `version` on the store (or on `createRouter`) replaces both versions. To clear the cache on every deploy, set `version` to a per-deploy value or keep a deployment-scoped `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`. Two environments built from the same code share entries if they share a cache namespace; give each its own namespace or `version`.
+
 ## Host routers (multi-app)
 
 A multi-app host router deploys as a **single function** running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model). Two requirements:

package/src/bin/rango.ts

@@ -76,7 +76,7 @@ if (command === "generate") {
 Modes:
   (default)   Static parser with error on unresolvable includes
   --runtime   Vite-based runtime discovery (100% coverage)
-              Requires vite and @vitejs/plugin-rsc
+              Requires vite
   --static    Static parser, accept partial output with warnings
 
 Options:

package/src/browser/event-controller.ts

@@ -15,6 +15,11 @@ import {
   filterRouteSegmentIds,
 } from "./react/filter-segment-order.js";
 import { notifyListeners } from "./notify-listeners.js";
+import { cloneHandleData } from "./navigation-store.js";
+import {
+  locationStateSnapshot,
+  type LocationStateSnapshot,
+} from "./react/location-state-shared.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -224,7 +229,8 @@ export interface EventController {
   getActionState(actionId: string): TrackedActionState;
   getLocation(): NavigationLocation;
 
-  // Location updates (for popstate where navigation doesn't go through startNavigation)
+  // Location of a commit no transaction completes: a shallow navigation, a
+  // back/forward restored from the history cache, a back/forward that failed.
   setLocation(location: NavigationLocation): void;
 
   // Subscriptions
@@ -256,6 +262,23 @@ export interface EventController {
     resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
+  /**
+   * Keep the current handle state as the one the document's HTML was rendered
+   * with. initBrowserApp calls it before hydrateRoot, once the document's
+   * handle snapshot is applied.
+   */
+  freezeHydrationHandleState(): void;
+  /**
+   * The handle state the document's HTML was rendered with, once the live
+   * state has moved on from it; undefined while the live state is still that
+   * state (nothing changed since the freeze, or nothing was frozen: a tree
+   * that was mounted, an SSR pass). A render React is hydrating reads it
+   * (useHandle), whenever its boundary hydrates: the late handle channel
+   * (rsc-router.tsx) waits for the root to hydrate, not for a `<Suspense>`
+   * boundary that hydrates after it, and by then the live state can hold
+   * values that boundary's HTML does not (issue #1035).
+   */
+  getHydrationHandleState(): HandleState | undefined;
   /**
    * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
    * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
@@ -269,6 +292,21 @@ export interface EventController {
   setParams(params: Record<string, string>): void;
   getParams(): Record<string, string>;
 
+  /**
+   * Record the committed history entry's location state from `entryState`:
+   * the state object the commit pushed, restored or merged into the entry,
+   * so the entry and its readers have one source. Notifies nobody:
+   * NavigationProvider takes the snapshot with the entry's payload
+   * (LocationStateContext). `treeless` marks a commit no payload follows (a
+   * shallow navigation, a commit that keeps every segment, an action's
+   * state): the provider takes it with this commit's state notification, in
+   * the batch of the location.
+   */
+  commitLocationState(entryState: unknown, treeless?: boolean): void;
+  getLocationState(): LocationStateSnapshot;
+  /** True once after a `treeless` commit. */
+  takeTreelessLocationState(): boolean;
+
   // Direct state access for advanced use
   getCurrentNavigation(): NavigationEntry | null;
   getInflightActions(): Map<string, ActionEntry>;
@@ -460,9 +498,14 @@ export function createEventController(
   let handleData: HandleData = {};
   let handleSegmentOrder: string[] = [];
   let routeSegmentIds: string[] = [];
+  // freezeHydrationHandleState: what the document's HTML was rendered with.
+  let hydrationHandleState: HandleState | undefined;
 
   let routeParams: Record<string, string> = {};
 
+  let locationState: LocationStateSnapshot;
+  let treelessLocationState = false;
+
   const stateListeners = new Set<StateListener>();
   const actionListeners = new Map<string, Set<ActionStateListener>>();
   const handleListeners = new Set<HandleListener>();
@@ -992,7 +1035,11 @@ export function createEventController(
     const newRouteSegmentIds = filterRouteSegmentIds(rawMatched);
 
     if (isPartial && newSegmentOrder.length > 0) {
-      // Partial update: merge new data with existing
+      // Partial update: merge new data with existing, into a copy of the
+      // containers. The object a reader was handed is never written to: the
+      // hydration snapshot (freezeHydrationHandleState) and a history entry
+      // restored from the store's cache can be that object.
+      handleData = cloneHandleData(handleData);
       for (const handleName of Object.keys(data)) {
         if (!handleData[handleName]) {
           handleData[handleName] = {};
@@ -1094,6 +1141,20 @@ export function createEventController(
     return routeParams;
   }
 
+  function commitLocationState(entryState: unknown, treeless?: boolean): void {
+    locationState = locationStateSnapshot(entryState, locationState);
+    if (treeless) {
+      treelessLocationState = true;
+      notify();
+    }
+  }
+
+  function takeTreelessLocationState(): boolean {
+    const taken = treelessLocationState;
+    treelessLocationState = false;
+    return taken;
+  }
+
   // ========================================================================
   // Return Controller
   // ========================================================================
@@ -1116,12 +1177,24 @@ export function createEventController(
     // Handles
     setHandleData,
     getHandleState,
+    freezeHydrationHandleState: () => {
+      hydrationHandleState = getHandleState();
+    },
+    getHydrationHandleState: () =>
+      hydrationHandleState?.data === handleData
+        ? undefined
+        : hydrationHandleState,
     setRouteSegmentIds,
 
     // Params
     setParams,
     getParams,
 
+    // Location state
+    commitLocationState,
+    getLocationState: () => locationState,
+    takeTreelessLocationState,
+
     // Subscriptions
     subscribe,
     subscribeToAction,

package/src/browser/history-state.ts

@@ -1,9 +1,13 @@
 import {
+  addLocationState,
+  CLEAR_ON_RELOAD_KEY_SUFFIX,
   isLocationStateDefinition,
   isLocationStateEntry,
+  isLocationStateKey,
   peekLocationStateKey,
   replaceCurrentHistoryState,
   resolveLocationStateEntries,
+  stampLocationState,
 } from "./react/location-state-shared.js";
 
 /**
@@ -13,7 +17,7 @@ function isTypedLocationState(
   state: unknown,
 ): state is Record<string, unknown> {
   if (state === null || typeof state !== "object") return false;
-  return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
+  return Object.keys(state).some(isLocationStateKey);
 }
 
 /**
@@ -100,16 +104,15 @@ export function buildHistoryState(
     Object.assign(result, serverState);
   }
 
+  if (hasLocationState(result)) stampLocationState(result);
+
   return Object.keys(result).length > 0 ? result : null;
 }
 
 /** Check if a history state object contains location state keys. */
 export function hasLocationState(state: unknown): boolean {
   if (!state || typeof state !== "object") return false;
-  return (
-    "state" in state ||
-    Object.keys(state).some((k) => k.startsWith("__rsc_ls_"))
-  );
+  return "state" in state || Object.keys(state).some(isLocationStateKey);
 }
 
 /**
@@ -157,19 +160,38 @@ export function stripShellMissMarker(): void {
 }
 
 /**
- * Merge server-set location state into the current history entry.
- * Replaces the current history state and dispatches notification event
- * so useLocationState hooks re-read from history.state.
+ * Remove the `clearOnReload` slots of the entry a document load starts on:
+ * the server rendered this document without them. One pass before hydration
+ * (initBrowserApp; renderRoute's `hydrate` mode), so no reader needs to know
+ * the page began as a document load, and a slot nobody reads is removed too.
+ * No server-set state exists yet to lose: a document response carries none
+ * (rsc-rendering.ts attaches it to partial payloads only).
+ *
+ * A slot is recognised by its key alone (the `~r` suffix): at start-up the
+ * module that defines it may not be loaded.
+ */
+export function clearLocationStateOnDocumentLoad(): void {
+  const state: unknown = window.history.state;
+  if (state === null || typeof state !== "object") return;
+  let next: Record<string, unknown> | undefined;
+  for (const key in state) {
+    if (isLocationStateKey(key) && key.endsWith(CLEAR_ON_RELOAD_KEY_SUFFIX)) {
+      next ??= { ...state };
+      delete next[key];
+    }
+  }
+  if (next) window.history.replaceState(next, "");
+}
+
+/**
+ * Merge server-set location state into the current history entry and return
+ * the entry state written. Readers see it when the caller commits it
+ * (EventController.commitLocationState).
  */
 export function mergeLocationState(
   locationState: Record<string, unknown>,
-): void {
-  const merged = {
-    ...window.history.state,
-    ...locationState,
-  };
-  replaceCurrentHistoryState(merged);
-  if (Object.keys(locationState).some((k) => k.startsWith("__rsc_ls_"))) {
-    window.dispatchEvent(new Event("__rsc_locationstate"));
-  }
+): Record<string, unknown> {
+  const entryState = addLocationState(window.history.state, locationState);
+  replaceCurrentHistoryState(entryState);
+  return entryState;
 }

package/src/browser/navigation-bridge.ts

@@ -14,11 +14,7 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import {
-  buildHistoryState,
-  hasLocationState,
-  pushHistoryWithIdx,
-} from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -220,8 +216,6 @@ export function createNavigationBridge(
         // Save current scroll position before changing URL
         handleNavigationStart();
 
-        // Snapshot old state before pushState/replaceState overwrites it
-        const oldState = window.history.state;
         const shallowRouteName = store.getHistoryEntryMemory()?.routeName;
 
         // Update browser URL (carry intercept context into history state)
@@ -239,11 +233,8 @@ export function createNavigationBridge(
         ensureHistoryKey();
         // Same route, new entry (transition({ when }) back/forward source).
         store.rememberDisplayedEntry(shallowRouteName);
-
-        // Notify useLocationState() hooks when state changes
-        if (hasLocationState(oldState) || hasLocationState(historyState)) {
-          window.dispatchEvent(new Event("__rsc_locationstate"));
-        }
+        // Treeless: readers take the entry's state with setLocation below.
+        eventController.commitLocationState(historyState, true);
 
         // Update store history key so future navigations reference the right cache
         store.setHistoryKey(historyKey);
@@ -357,6 +348,8 @@ export function createNavigationBridge(
       const clientUrlPresentation = beginClientUrlNavigation(
         targetUrl,
         tx.handle.signal,
+        // The entry the commit will push, without what the server adds.
+        () => buildHistoryState(resolvedState),
         transitionOptOut
           ? () => true
           : (destination) =>
@@ -378,7 +371,7 @@ export function createNavigationBridge(
                       url: targetUrl,
                       params: { ...params, ...destination.params },
                       routeName: destination.routeName,
-                      state: buildHistoryState(resolvedState),
+                      state: destination.state,
                     };
                   },
                   extra: destination.when,
@@ -578,9 +571,6 @@ export function createNavigationBridge(
         historyKey,
       );
 
-      // Update location in event controller
-      eventController.setLocation(new URL(url));
-
       // If this is an intercept, restore the intercept context
       if (isIntercept && interceptSourceUrl) {
         store.setInterceptSourceUrl(interceptSourceUrl);
@@ -648,9 +638,16 @@ export function createNavigationBridge(
             transitionGatedOff: gatedOff,
           });
           store.rememberDisplayedEntry();
-          // Set params on event controller before onUpdate so both location
-          // and params are current when the debounced notify() fires.
+          // The restored entry's location and params, set before onUpdate so
+          // the hooks take both in the batch that renders its tree. Not at
+          // the popstate event: the page being left is on screen until here
+          // (#1031). A restore that has to fetch gets its location from
+          // tx.commit() instead (navigation-transaction.ts).
+          eventController.setLocation(new URL(url));
           eventController.setParams(cachedParams);
+          // The entry this handler found at the event, which the cached tree
+          // was built for: history may have moved during the render above.
+          eventController.commitLocationState(historyState);
 
           const popstateUpdate = {
             root,
@@ -783,6 +780,32 @@ export function createNavigationBridge(
           return;
         }
 
+        // The browser is already on the entry that redirected. Replacing makes
+        // that entry the redirect target, so Back from the target reaches the
+        // entry before it; a push would leave the redirecting entry in history
+        // and Back would hit the redirect again. Before setLocation below, or
+        // the hooks would report the redirecting URL first.
+        if (error instanceof ServerRedirect) {
+          const redirectUrl = validateRedirectOrigin(
+            error.url,
+            window.location.origin,
+          );
+          if (!redirectUrl) {
+            return;
+          }
+          return this.navigate(redirectUrl, {
+            state: error.state,
+            replace: true,
+            _skipCache: true,
+          } as NavigateOptionsInternal);
+        }
+
+        // tx.commit() never ran, so the location is still the page being
+        // left. The error boundary below replaces that page, and history is
+        // already on the entry that failed: the hooks report that entry, in
+        // the boundary's batch.
+        eventController.setLocation(new URL(url));
+
         const networkError = toNetworkError(error, {
           url,
           operation: "navigation",

package/src/browser/navigation-transaction.ts

@@ -13,7 +13,6 @@ import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
 import {
   buildHistoryState,
-  hasLocationState,
   mergeLocationState,
   pushHistoryWithIdx,
 } from "./history-state.js";
@@ -59,6 +58,11 @@ interface CommitOptions {
    * partial updater reuses it instead of deciding again.
    */
   transitionGatedOff?: boolean;
+  /**
+   * No payload follows this commit: every segment is kept and the tree on
+   * screen stays (EventController.commitLocationState).
+   */
+  treeless?: boolean;
 }
 
 /**
@@ -81,6 +85,8 @@ interface BoundCommitOverrides {
   serverState?: Record<string, unknown>;
   /** The committed route's name (payload metadata), remembered per history entry. */
   routeName?: string;
+  /** No payload follows this commit (CommitOptions.treeless). */
+  treeless?: boolean;
 }
 
 /**
@@ -187,10 +193,13 @@ export function createNavigationTransaction(
     }
 
     if (traversal) {
-      if (serverState && Object.keys(serverState).length > 0) {
-        mergeLocationState(serverState);
-      }
+      // The entry as history restored it, plus what the server adds.
+      const entryState: unknown =
+        serverState && Object.keys(serverState).length > 0
+          ? mergeLocationState(serverState)
+          : window.history.state;
       store.rememberDisplayedEntry(opts.routeName);
+      eventController.commitLocationState(entryState, opts.treeless);
       handle.complete(parsedUrl);
       debugLog("[Browser] Traversal committed, historyKey:", historyKey);
       return { scroll };
@@ -202,15 +211,10 @@ export function createNavigationTransaction(
       serverState,
     );
 
-    const oldState = window.history.state;
-
     pushHistoryWithIdx(historyState, url, replace ?? false);
     ensureHistoryKey();
     store.rememberDisplayedEntry(opts.routeName);
-
-    if (hasLocationState(oldState) || hasLocationState(historyState)) {
-      window.dispatchEvent(new Event("__rsc_locationstate"));
-    }
+    eventController.commitLocationState(historyState, opts.treeless);
 
     handle.complete(parsedUrl);
 
@@ -269,6 +273,7 @@ export function createNavigationTransaction(
             cacheOnly,
             serverState,
             routeName: overrides?.routeName ?? opts.routeName,
+            treeless: overrides?.treeless,
           });
         },
       };

package/src/browser/partial-update.ts

@@ -42,6 +42,7 @@ import {
   type TransitionWhenActionInput,
 } from "./transition-when.js";
 import { buildHistoryState } from "./history-state.js";
+import { addLocationState } from "./react/location-state-shared.js";
 import type { TransitionWhenKind } from "../types/segments.js";
 
 function toScrollPayload(
@@ -225,8 +226,14 @@ export function createPartialUpdater(
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
+    // The page the client is on, which the server diffs the target against.
+    // tx.currentUrl is window.location when the transaction was created: on
+    // a back/forward the popstate event had already moved it to the target,
+    // and a server told the target is also the source revalidates nothing on
+    // the same route, so the page being left stayed on screen (#1030). The
+    // store's URL is the committed entry's until tx.commit().
     const previousUrl =
-      mode.type === "leave-intercept"
+      mode.type === "leave-intercept" || (tx.traversal && !interceptSourceUrl)
         ? segmentState.currentUrl || tx.currentUrl
         : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
 
@@ -279,7 +286,7 @@ export function createPartialUpdater(
             params: metadata.params ?? mergeSegmentParams(segmentsToCommit),
             routeName: metadata.routeName,
             state: tx.traversal
-              ? { ...window.history.state, ...metadata.locationState }
+              ? addLocationState(window.history.state, metadata.locationState)
               : buildHistoryState(tx.state, undefined, metadata.locationState),
           }),
           action:
@@ -499,6 +506,7 @@ export function createPartialUpdater(
         );
         tx.commit(matchedIds, existingSegments, {
           routeName: payload.metadata.routeName,
+          treeless: true,
         });
         debugLog("[Browser] Navigation complete (no re-render)");
         return;

package/src/browser/rango-state.ts

@@ -7,7 +7,9 @@
  * cache keys responses by (URL, X-Rango-State value).
  *
  * Value format: `{buildVersion}:{invalidationTimestamp}`
- * - Build version changes on deploy, busting all cached prefetches at boot.
+ * - Build version: the router's document version. It changes when a deploy
+ *   changes the router's server code or the client assets, busting all cached
+ *   prefetches at boot; a deploy that changes neither keeps them.
  * - Timestamp rotates on invalidation (server action, invalidateClientCache).
  *
  * Storage is a session cookie named by the server-resolved name passed to

package/src/browser/react/Link.tsx

@@ -20,6 +20,7 @@ import {
   subscribeToPrefetchScopeChange,
 } from "../link-interceptor.js";
 import { subscribeToLocationChange } from "../event-controller.js";
+import { subscribeToNothing } from "./subscribe-to-nothing.js";
 import { isLocationStateDefinition } from "./location-state-shared.js";
 
 export type StateOrGetter<T = unknown> = T | (() => T);
@@ -51,8 +52,6 @@ import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 export type { PrefetchStrategy } from "../../router/prefetch-default.js";
 export { resolveAdaptiveStrategy } from "../prefetch/default-strategy.js";
 
-const IGNORE_STRATEGY_CHANGES = (_listener: () => void) => () => {};
-
 /**
  * Link component props
  */
@@ -274,7 +273,7 @@ export const Link: ForwardRefExoticComponent<
   const resolvedStrategy = useSyncExternalStore(
     configuredStrategy === "adaptive"
       ? subscribeToAdaptiveStrategyChange
-      : IGNORE_STRATEGY_CHANGES,
+      : subscribeToNothing,
     () => resolveAdaptiveStrategy(configuredStrategy),
     () => (configuredStrategy === "adaptive" ? "hover" : configuredStrategy),
   );

package/src/browser/react/NavigationProvider.tsx

@@ -11,6 +11,7 @@ import React, {
   type ReactNode,
 } from "react";
 import {
+  LocationStateContext,
   NavigationStoreContext,
   type NavigationStoreContextValue,
 } from "./context.js";
@@ -315,6 +316,11 @@ export function NavigationProvider({
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
+  // The location state of the entry `payload` renders (LocationStateContext).
+  // Only ever set next to setPayload, or for a commit that has no payload.
+  const [locationState, setLocationState] = useState(
+    eventController.getLocationState,
+  );
 
   /**
    * Navigate to a URL (delegates to bridge)
@@ -373,6 +379,19 @@ export function NavigationProvider({
     return startConnectionWarmup();
   }, [warmupEnabled]);
 
+  // A commit no payload follows (a shallow navigation, a commit that keeps
+  // every segment, merged server-set state): the tree on screen is already
+  // the entry's, so its state is taken with the commit's notification.
+  useEffect(
+    () =>
+      eventController.subscribe(() => {
+        if (eventController.takeTreelessLocationState()) {
+          setLocationState(eventController.getLocationState());
+        }
+      }),
+    [eventController],
+  );
+
   // Cancel non-matching prefetches when navigation starts.
   // Frees connections so the navigation fetch isn't competing with
   // speculative prefetches. The prefetch matching the navigation target
@@ -421,6 +440,9 @@ export function NavigationProvider({
         root: update.root,
         metadata: update.metadata,
       });
+      // The state of the entry this payload renders, as its commit recorded
+      // it: one update, so one lane, so one React commit with the tree.
+      setLocationState(eventController.getLocationState());
 
       // Update route params. Only reset when the server actually sends a params
       // map — an absent `params` field means "no change" (e.g., legacy action
@@ -506,7 +528,9 @@ export function NavigationProvider({
 
   return (
     <NavigationStoreContext.Provider value={contextValue}>
-      {content}
+      <LocationStateContext.Provider value={locationState}>
+        {content}
+      </LocationStateContext.Provider>
     </NavigationStoreContext.Provider>
   );
 }

package/src/browser/react/context.ts

@@ -4,6 +4,7 @@ import { createContext, type Context } from "react";
 import type { NavigationStore, NavigateOptionsInternal } from "../types.js";
 import type { EventController } from "../event-controller.js";
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+import type { LocationStateSnapshot } from "./location-state-shared.js";
 
 /**
  * Navigation context value provided by NavigationProvider
@@ -66,3 +67,15 @@ export interface NavigationStoreContextValue {
  */
 export const NavigationStoreContext: Context<NavigationStoreContextValue | null> =
   createContext<NavigationStoreContextValue | null>(null);
+
+/**
+ * The location state of the history entry whose tree is on screen, for
+ * useLocationState. NavigationProvider holds it as React state next to the
+ * payload and sets both in one update, so a render sees an entry's state
+ * exactly when it sees that entry's tree: a transition React holds renders
+ * the destination's value, an urgent render of the content still on screen
+ * (a reader mounting there included) the value of the entry being left
+ * (#1029). Undefined on the server and outside a provider.
+ */
+export const LocationStateContext: Context<LocationStateSnapshot> =
+  createContext<LocationStateSnapshot>(undefined);