@rangojs/router 0.20.0 → 0.21.0

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

@@ -11,12 +11,177 @@ export interface LocationStateEntry {
   readonly __rsc_ls_lazy?: boolean;
 }
 
+/** Prefix of every typed location-state slot in `history.state`. */
+export const LOCATION_STATE_KEY_PREFIX: string = "__rsc_ls_";
+
+export function isLocationStateKey(key: string): boolean {
+  return key.startsWith(LOCATION_STATE_KEY_PREFIX);
+}
+
+/**
+ * `clearOnReload` is part of a slot's KEY (`<key>~r`); the value is always
+ * stored raw. Slots outlive deploys, so nothing that reads one may depend on a
+ * stored format: a definition without the option reads the plain key and never
+ * sees such a slot.
+ *
+ * An injected key ends in `#<ExportName>` (expose-id-utils.ts makeStubId; only
+ * identifier exports are keyed) and "~" cannot occur in an identifier, so no
+ * file or export name produces a suffix. withLocationStateKey rejects it.
+ */
+export const LOCATION_STATE_KEY_SUFFIX_SEPARATOR: string = "~";
+export const CLEAR_ON_RELOAD_KEY_SUFFIX: string = "~r";
+
+/**
+ * A history entry records the app version its location state (typed slots and
+ * plain `state`) was written under, in this one field; a read returns only
+ * state recorded under the version this document loaded with. Entries outlive
+ * deploys, and state an older release stored would otherwise reach code that
+ * no longer expects its shape. An entry without the field counts as another
+ * version.
+ *
+ * Not a slot key (no LOCATION_STATE_KEY_PREFIX): hasLocationState must not
+ * count it.
+ */
+const LOCATION_STATE_VERSION_KEY = "__rsc_lsv";
+
+let documentVersion: string | undefined;
+
+/**
+ * @internal The version the document loaded under (rsc-router.tsx
+ * initBrowserApp). Deliberately not getAppVersion(): a dev HMR bump moves that
+ * one inside a running session (bridge.updateVersion), and the state that
+ * session wrote must stay readable until the next document load.
+ */
+export function setLocationStateVersion(version: string | undefined): void {
+  documentVersion = version;
+}
+
+/**
+ * The state of a `{ state }` snapshot when its location state may be read:
+ * an object recorded under the client's version. Without a snapshot, the
+ * current entry (`window.history` is a `{ state }`), and nothing on the
+ * server.
+ */
+export function readableLocationState(
+  location: { readonly state: unknown } | undefined = typeof window ===
+  "undefined"
+    ? undefined
+    : window.history,
+): Record<string, unknown> | undefined {
+  const state = location?.state;
+  return state !== null &&
+    typeof state === "object" &&
+    (state as Record<string, unknown>)[LOCATION_STATE_VERSION_KEY] ===
+      documentVersion
+    ? (state as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * One history entry's location state as useLocationState readers receive it:
+ * its typed slots and plain `state`, or undefined when it holds none.
+ */
+export type LocationStateSnapshot =
+  | Readonly<Record<string, unknown>>
+  | undefined;
+
+/**
+ * The snapshot of `entryState`: the state object a commit pushes, restores or
+ * merges into its history entry. Only state recorded under the client's
+ * version is in it (readableLocationState).
+ *
+ * The snapshot is a React context value, so identity decides who re-renders.
+ * It is `previous` itself when every slot holds the value `previous` holds:
+ * an entry without state after another, a primitive carried over, or the
+ * object a reader got from `previous` passed back by the navigation. Any
+ * other value is new, equal content included: a link clicked twice announces
+ * its state twice (a flash message, a scroll target). A new value is a
+ * structured clone, as history.state holds it, so a reader never shares an
+ * object with the caller of the navigation.
+ */
+export function locationStateSnapshot(
+  entryState: unknown,
+  previous?: LocationStateSnapshot,
+): LocationStateSnapshot {
+  const state = readableLocationState({ state: entryState });
+  let next: Record<string, unknown> | undefined;
+  let kept = 0;
+  for (const key in state) {
+    if (key !== "state" && !isLocationStateKey(key)) continue;
+    next ??= {};
+    const value = state[key];
+    if (
+      previous &&
+      Object.hasOwn(previous, key) &&
+      Object.is(previous[key], value)
+    ) {
+      next[key] = value;
+      kept++;
+    } else {
+      next[key] = structuredClone(value);
+    }
+  }
+  return previous &&
+    next &&
+    kept === Object.keys(next).length &&
+    kept === Object.keys(previous).length
+    ? previous
+    : next;
+}
+
+/**
+ * Record the client's version on a state object that carries location state
+ * and no record yet. A client without a version (a renderRoute tree) writes
+ * none.
+ */
+export function stampLocationState(state: Record<string, unknown>): void {
+  if (documentVersion !== undefined) {
+    state[LOCATION_STATE_VERSION_KEY] = documentVersion;
+  }
+}
+
+/**
+ * `entryState` plus `additions`, recorded under the client's version. The
+ * record is per entry, so location state another version left there is dropped
+ * first, with its record: under the new one it would be readable again. Router
+ * bookkeeping (idx, scroll key, intercept) is kept.
+ */
+export function addLocationState(
+  entryState: unknown,
+  additions?: Record<string, unknown>,
+): Record<string, unknown> {
+  // history.state may be a primitive if non-Rango code stored one; spreading a
+  // string would yield indexed char keys.
+  const next: Record<string, unknown> = {
+    ...(typeof entryState === "object" ? entryState : null),
+  };
+  if (next[LOCATION_STATE_VERSION_KEY] !== documentVersion) {
+    for (const key in next) {
+      if (
+        key === "state" ||
+        key === LOCATION_STATE_VERSION_KEY ||
+        isLocationStateKey(key)
+      ) {
+        delete next[key];
+      }
+    }
+    stampLocationState(next);
+  }
+  return Object.assign(next, additions);
+}
+
 /**
  * Options for createLocationState
  */
 export interface LocationStateOptions {
   /** When true, the state is cleared from history after first read (flash message pattern) */
   flash?: boolean;
+  /**
+   * When true, the state does not survive a document load of its entry (a
+   * refresh, a back/forward that loads the document): the server rendered
+   * without it. Not together with `flash`.
+   */
+  clearOnReload?: boolean;
 }
 
 type LocationStateUnsafeFn = (...args: never[]) => unknown;
@@ -236,13 +401,16 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   (...args: TArgs): LocationStateEntry;
   /**
    * Injected by Vite plugin - do not set manually. Unit tests without the
-   * plugin use withLocationStateKey() from @rangojs/router/testing.
+   * plugin use withLocationStateKey() from @rangojs/router/testing. Reads back
+   * as the slot's key in `history.state`: the injected key plus the
+   * `clearOnReload` suffix.
    */
   __rsc_ls_key: string;
   /** Whether this state auto-clears after first read */
   readonly __rsc_ls_flash: boolean;
   /**
-   * Read the current value from history.state.
+   * Read the current value from history.state. State the entry holds from
+   * another version of the app (an older build) reads as undefined.
    *
    * Returns undefined during SSR (no `window`). To stay hydration-safe, do
    * NOT call read() inline during the initial render — the server returns
@@ -263,13 +431,14 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   /**
    * Statically write the value into the current history entry under this
    * definition's key, preserving any other keys already on history.state
-   * (e.g. router bookkeeping, other LocationState slots).
+   * (e.g. router bookkeeping, other LocationState slots). Location state
+   * another version of the app left on the entry is dropped.
    *
-   * This is the non-reactive counterpart to read(): it does not dispatch any
-   * event, so components reading via useLocationState() will NOT re-render
-   * until the next navigation/popstate. Use it when you only need the value
-   * to be there on the next read() or on the next mount (including after
-   * back/forward and hard refresh of the same entry).
+   * This is the non-reactive counterpart to read(): it changes the history
+   * entry and nothing a useLocationState() reader shows, whether the reader
+   * is mounted now or mounts later. read() returns the value at once; a
+   * reader gets it when the entry is next restored: back/forward to it, or
+   * (unless the definition sets `clearOnReload`) a hard refresh of it.
    *
    * Client-only: throws when called on the server (no history available).
    */
@@ -279,8 +448,8 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
    * leaving any other keys on history.state untouched. Idempotent: removing
    * a slot that isn't present is a no-op.
    *
-   * Same non-reactive semantics as write(): no event is dispatched, so
-   * useLocationState() readers will NOT re-render until the next navigation.
+   * Same non-reactive semantics as write(): useLocationState() readers keep
+   * the value until the entry is next restored.
    *
    * Client-only: throws when called on the server (no history available).
    */
@@ -321,9 +490,8 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  * const snap = ProductState.read();
  *
  * // Static write to current history entry (non-reactive, client-side only).
- * // Survives back/forward and hard refresh; useLocationState() readers will
- * // NOT see the new value until the next navigation. Pair with .read() or a
- * // fresh mount.
+ * // Survives back/forward and hard refresh; useLocationState() readers see
+ * // the new value when the entry is next restored. Pair with .read().
  * ProductState.write({ name: "Widget", price: 9.99 });
  *
  * // Manually clear the slot (non-reactive, client-side only).
@@ -357,6 +525,19 @@ export function createLocationState<TState>(
   TState
 > {
   const flash = options?.flash ?? false;
+  const clearOnReload = options?.clearOnReload ?? false;
+  // Empty without `clearOnReload`: the injected key is then the storage key,
+  // as it was before the option existed.
+  const keySuffix = clearOnReload ? CLEAR_ON_RELOAD_KEY_SUFFIX : "";
+  // Flash state ends at its first read, so the pair could only drop a message
+  // nobody has seen. Folded out of production, like the missing-key check.
+  if (process.env.NODE_ENV !== "production" && flash && clearOnReload) {
+    throw new Error(
+      "[rango] createLocationState: `flash` and `clearOnReload` cannot be combined. " +
+        "Flash state is removed at its first read, so `clearOnReload` could only " +
+        "drop a flash message that has not been shown yet.",
+    );
+  }
   let _key: string | undefined;
 
   // Dev and test throw; production folds the check away (the plugin always
@@ -395,7 +576,7 @@ export function createLocationState<TState>(
   Object.defineProperty(fn, "__rsc_ls_key", {
     get: () => getKey(),
     set: (k: string) => {
-      _key = k;
+      _key = k && k + keySuffix;
     },
     enumerable: true,
     configurable: true,
@@ -407,16 +588,8 @@ export function createLocationState<TState>(
   });
 
   Object.defineProperty(fn, "read", {
-    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;
-    },
+    value: (location?: { readonly state: unknown }): TState | undefined =>
+      readableLocationState(location)?.[getKey()] as TState | undefined,
     enumerable: true,
   });
 
@@ -428,16 +601,9 @@ export function createLocationState<TState>(
             "It mutates window.history.state and cannot run on the server.",
         );
       }
-      const key = getKey();
-      // history.state may be a non-null primitive (string/number/boolean) if
-      // non-Rango code called pushState/replaceState with one. `?? {}` only
-      // catches null/undefined, so spreading a primitive would yield indexed
-      // char/no keys and corrupt history.state. Coerce any non-object to a fresh
-      // dict — mirrors the delete() guard.
-      const existing = window.history.state;
-      const current =
-        existing !== null && typeof existing === "object" ? existing : {};
-      replaceCurrentHistoryState({ ...current, [key]: value });
+      replaceCurrentHistoryState(
+        addLocationState(window.history.state, { [getKey()]: value }),
+      );
     },
     enumerable: true,
   });

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

@@ -1,7 +1,11 @@
 "use client";
 
-import { useState, useEffect, useRef } from "react";
+import { useContext, useEffect, useSyncExternalStore } from "react";
+import { subscribeToNothing } from "./subscribe-to-nothing.js";
+import { LocationStateContext } from "./context.js";
+import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 import {
+  readableLocationState,
   replaceCurrentHistoryState,
   type LocationStateDefinition,
 } from "./location-state-shared.js";
@@ -15,29 +19,25 @@ export {
   type LocationStateOptions,
 } from "./location-state-shared.js";
 
-function readLocationStateValue<TState>(
-  key: string | undefined,
-): TState | undefined {
-  if (typeof window === "undefined") return undefined;
-  if (key) {
-    return window.history.state?.[key] as TState | undefined;
-  }
-  // Plain state: stored under history.state.state
-  return window.history.state?.state as TState | undefined;
-}
-
-function hasHydrated(): boolean {
-  return (
-    typeof document !== "undefined" &&
-    document.documentElement.hasAttribute("data-hydrated")
-  );
+/**
+ * Server and hydration renders must match the SSR output (`undefined`).
+ * React then re-renders with `getSnapshot`, including a reader whose Suspense
+ * boundary hydrates after the root has set `data-hydrated`.
+ */
+function getServerSnapshot(): undefined {
+  return undefined;
 }
 
 /**
- * Hook to read location state from history.state
+ * Hook to read the location state of the history entry on screen
+ *
+ * A reader sees an entry's state together with that entry's tree: on a
+ * navigation the value changes in the React commit that brings the
+ * destination, so content a pending navigation keeps on screen keeps the
+ * state of the entry being left, for a reader that mounts there too (#1029).
  *
  * Behavior depends on the definition:
- * - Normal state: persists across navigations, reactive to popstate
+ * - Normal state: persists across navigations and back/forward
  * - Flash state (created with { flash: true }): read once, cleared after paint
  *
  * Overloaded:
@@ -67,69 +67,34 @@ export function useLocationState<TArgs extends unknown[], TState>(
 ): TState | undefined {
   const key = definition?.__rsc_ls_key;
   const isFlash = definition?.__rsc_ls_flash ?? false;
+  const entry = useContext(LocationStateContext);
+  const optimistic = useContext(OptimisticLocationContext);
 
-  // Track whether the initial render returned undefined because the page
-  // hadn't hydrated yet. If so, the mount effect catches up by reading
-  // history.state once. If not, we already have the right value and must
-  // not re-read on mount — under StrictMode, the flash-cleanup effect runs
-  // before the second setup pass, so a re-read would clobber the captured
-  // value with the now-cleared `undefined`.
-  const initialReadDeferredRef = useRef(false);
-
-  const [state, setState] = useState<TState | undefined>(() => {
-    if (!hasHydrated()) {
-      initialReadDeferredRef.current = true;
-      return undefined;
-    }
-    return readLocationStateValue<TState>(key);
-  });
-
-  // Subscribe to popstate and programmatic state changes
-  useEffect(() => {
-    const handlePopstate = () => {
-      setState(readLocationStateValue<TState>(key));
-    };
-
-    // Handle programmatic state changes (same-page navigation with
-    // ctx.setLocationState where components don't remount)
-    const handleLocationState = () => {
-      if (key) {
-        const val = readLocationStateValue<TState>(key);
-        if (isFlash) {
-          // For flash state, only update if there's a new value
-          if (val !== undefined) {
-            setState(val);
-          }
-        } else {
-          setState(val);
-        }
-      } else {
-        setState(readLocationStateValue<TState>(key));
-      }
-    };
-
-    if (initialReadDeferredRef.current) {
-      initialReadDeferredRef.current = false;
-      setState(readLocationStateValue<TState>(key));
-    }
-
-    window.addEventListener("popstate", handlePopstate);
-    window.addEventListener("__rsc_locationstate", handleLocationState);
-    return () => {
-      window.removeEventListener("popstate", handlePopstate);
-      window.removeEventListener("__rsc_locationstate", handleLocationState);
-    };
-  }, [key, isFlash]);
+  // Typed state: the slot under its key. Plain state: the `state` slot.
+  // Inside an optimistically rendered clientUrls() destination the provider
+  // still holds the entry being left: read the entry the navigation will push.
+  const shown = (optimistic ? readableLocationState(optimistic) : entry)?.[
+    key || "state"
+  ] as TState | undefined;
+  // useSyncExternalStore only for its server snapshot: no other hook tells a
+  // hydrating render from a client one.
+  const state = useSyncExternalStore<TState | undefined>(
+    subscribeToNothing,
+    () => shown,
+    getServerSnapshot,
+  );
 
-  // Flash: clear from history.state after paint so subsequent navigations don't see it.
-  // Depends on `state` so it re-runs when state is set via the event listener.
+  // Flash: removed from history.state after paint, so a reload or a return to
+  // the entry does not show it again. The provider's snapshot keeps it, so it
+  // stays on screen until the next commit of the entry's state. Not while the
+  // value is the optimistic entry's: history.state is another entry's.
   useEffect(() => {
-    if (isFlash && key && state !== undefined) {
+    if (isFlash && key && !optimistic && state !== undefined) {
       const cleaned = { ...window.history.state };
       delete cleaned[key];
       replaceCurrentHistoryState(cleaned);
     }
-  }, [isFlash, key, state]);
+  }, [isFlash, key, state, optimistic]);
 
   return state;
 }

package/src/browser/react/subscribe-to-nothing.ts

@@ -0,0 +1,7 @@
+/**
+ * `subscribe` for a useSyncExternalStore whose snapshot nothing notifies: the
+ * hook is there for its server snapshot (useLocationState, useHandle), or the
+ * value only changes with a render (Link's non-adaptive prefetch strategy).
+ * One function, so its identity is stable across renders and hooks.
+ */
+export const subscribeToNothing: () => () => void = () => () => {};

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

@@ -6,6 +6,7 @@ import {
   useEffect,
   useRef,
   useOptimistic,
+  useSyncExternalStore,
   startTransition,
 } from "react";
 import type { Handle } from "../../handle.js";
@@ -13,6 +14,9 @@ import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
+import { subscribeToNothing } from "./subscribe-to-nothing.js";
+
+const noHydrationState = (): undefined => undefined;
 
 /**
  * Hook to access collected handle data.
@@ -43,6 +47,21 @@ export function useHandle<T, A, S>(
 ): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
+  // useSyncExternalStore only for its server snapshot, as useLocationState
+  // (#992): no other hook tells a hydrating render from a client one. A
+  // hydrating render gets the handle state the document's HTML was rendered
+  // with (EventController.getHydrationHandleState), whenever its boundary
+  // hydrates; the mount effect below moves it on to the live state. That
+  // state is undefined while the live state is still it, and the client
+  // snapshot is always undefined: a reader that hydrated before anything
+  // arrived late is not rendered again, and to React the store never
+  // changes (issue #1035).
+  const hydrationState = useSyncExternalStore(
+    subscribeToNothing,
+    noHydrationState,
+    () => ctx?.eventController.getHydrationHandleState(),
+  );
+
   const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
       const collected = collectHandleData(
@@ -53,7 +72,7 @@ export function useHandle<T, A, S>(
       return selector ? selector(collected) : collected;
     }
 
-    const state = ctx.eventController.getHandleState();
+    const state = hydrationState ?? ctx.eventController.getHandleState();
     const collected = collectHandleData(
       handle,
       state.data,

package/src/browser/rsc-router.tsx

@@ -39,7 +39,11 @@ 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 {
+  clearLocationStateOnDocumentLoad,
+  stripShellMissMarker,
+} from "./history-state.js";
+import { setLocationStateVersion } from "./react/location-state-shared.js";
 import { setActiveInterceptTargets } from "../client-urls/navigation.js";
 
 // Vite HMR types are provided by vite/client
@@ -174,6 +178,9 @@ export async function initBrowserApp(
   // event controller): the server rendered the marked request for the clean
   // URL, so the client starts from the same one and hydration agrees.
   stripShellMissMarker();
+  // Before the first await: the store's entry memory, readers and the
+  // navigation / action lanes that deliver server-set state all come later.
+  clearLocationStateOnDocumentLoad();
   bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
@@ -211,6 +218,8 @@ export async function initBrowserApp(
   // default name active during that wait would discard this router's messages.
   const version = initialPayload.metadata?.version;
   initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
+  // Before anything can read location state: hydration starts further down.
+  setLocationStateVersion(version);
 
   // Seed the intercept-target set for the initial location so the FIRST
   // clientUrls navigation already declines intercepted targets (refreshed on
@@ -247,6 +256,10 @@ export async function initBrowserApp(
     initialLocation: new URL(window.location.href),
   });
 
+  // The document's entry, after the clearOnReload pass and under the version
+  // set above: what readers get once they have hydrated.
+  eventController.commitLocationState(window.history.state);
+
   // Initialize event controller with segment order (even without handles)
   eventController.setHandleData({}, initialPayload.metadata?.matched);
 
@@ -294,9 +307,9 @@ export async function initBrowserApp(
     if (lateGenerator) {
       void (async () => {
         try {
-          // Never apply before React commits hydration — a pre-commit
-          // application mutates the state useHandle initializers read during
-          // the hydration render (mismatch). Yields buffer in the generator
+          // Applied once the root has hydrated (see hydrationCommitted): the
+          // readers that hydrated with it are subscribed by then and take
+          // the update as an ordinary one. Yields buffer in the generator
           // meanwhile; nothing is lost.
           await hydrationCommitted;
           for await (const rawLateData of lateGenerator) {
@@ -324,6 +337,10 @@ export async function initBrowserApp(
   } else {
     bootLog("handles: none in payload");
   }
+  // What every reader hydrates with, whenever its boundary hydrates
+  // (useHandle): the late channel above changes the live state once the root
+  // has hydrated, and a navigation can before a streamed boundary has.
+  eventController.freezeHydrationHandleState();
 
   // Create composable utilities
   const client = createNavigationClient(deps);
@@ -621,13 +638,18 @@ export async function initBrowserApp(
 // re-runs the root effect; the second flush is not a second hydration).
 let hydrationCommitLogged = false;
 
-// Hydration-commit barrier for the late handle channel. useHandle's useState
-// initializer reads the eventController's LIVE state during the hydration
-// render, so applying a late handle update BEFORE hydration commits changes
-// that state out from under React — the classic "external changing data"
-// hydration mismatch (seen when a loader's push lost the handler-barrier race
-// by milliseconds and its late yield landed mid-hydration). The root effect
-// below resolves this; the late consumer awaits it before applying anything.
+// Hydration-commit barrier for the late handle channel: the late consumer
+// applies nothing before the root's effects have run. A hydrating render
+// reads the handle state frozen before hydrateRoot (useHandle,
+// EventController.getHydrationHandleState), so an earlier application would
+// no longer mismatch (it did while the initializer read the LIVE state: seen
+// when a loader's push lost the handler-barrier race by milliseconds and its
+// late yield landed mid-hydration). What the barrier still buys: a reader
+// that hydrates after the live state moved on is rendered a second time
+// right after, since React re-renders a reader whose hydration state is not
+// the client one. Readers that hydrate with the root would all pay that;
+// after the commit they are subscribed and take the update as an ordinary
+// one. The root effect below resolves this.
 let resolveHydrationCommitted!: () => void;
 const hydrationCommitted: Promise<void> = new Promise((resolve) => {
   resolveHydrationCommitted = resolve;

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

@@ -36,6 +36,7 @@ import {
   isForeignRouterId,
 } from "./response-adapter.js";
 import { mergeLocationState } from "./history-state.js";
+import { stampLocationState } from "./react/location-state-shared.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
 import { getAppVersion } from "./app-version.js";
 import { collectClientRevalidationDecisions } from "../client-urls/navigation.js";
@@ -79,11 +80,22 @@ export interface ServerActionBridgeConfigWithController extends ServerActionBrid
 function applyActionLocationState(
   handle: ActionHandle,
   locationState: Record<string, unknown> | undefined,
+  eventController: EventController,
 ): void {
   if (!locationState) return;
   const winning = handle.claimLocationState(locationState);
   if (Object.keys(winning).length > 0) {
     mergeLocationState(winning);
+    // The entry and its tree stay, so readers take the action's slots now,
+    // not with its revalidated tree: several terminals commit no tree, and a
+    // navigation during that render drops it. Added to what readers hold,
+    // not re-read from the entry: a flash value on screen was already cleared
+    // from history, and a write()/delete() stays unseen until the entry is
+    // restored.
+    const shown = { ...eventController.getLocationState(), ...winning };
+    stampLocationState(shown);
+    eventController.commitLocationState(shown, true);
+    eventController.flushRouteState();
   }
 }
 
@@ -734,7 +746,11 @@ export function createServerActionBridge(
       // before the normal branch's async renderSegments) so a slow render racing
       // a navigation cannot drop it.
       if (scenario.type !== "navigated-away") {
-        applyActionLocationState(handle, metadata?.locationState);
+        applyActionLocationState(
+          handle,
+          metadata?.locationState,
+          eventController,
+        );
       }
       // transition({ when }) `action` for this action's commit, whichever
       // lane applies it (normal, or a refetch below).