@rangojs/router 0.20.0 → 0.22.0

package/src/browser/react/NavigationProvider.tsx

@@ -8,9 +8,12 @@ import React, {
   useMemo,
   useRef,
   use,
+  startTransition,
   type ReactNode,
 } from "react";
 import {
+  HydrationBarrierContext,
+  LocationStateContext,
   NavigationStoreContext,
   type NavigationStoreContextValue,
 } from "./context.js";
@@ -36,6 +39,7 @@ import {
   deferredHandleNames,
   resolveDeferredHandleValues,
 } from "../../handles/deferred-resolution.js";
+import { auditTreeUpdate } from "../../suspense-audit.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -277,6 +281,18 @@ export interface NavigationProviderProps {
    * it to seed a nonce so components calling useNonce() can be exercised.
    */
   nonce?: string;
+
+  /**
+   * The document this provider hydrates (initBrowserApp; renderRoute with
+   * `hydrate: true`), whose store EventController.lockHydration locked.
+   * `settled` resolves once the stream has ended and React has revealed every
+   * boundary. Until then location state is `undefined`, as SSR rendered it;
+   * then one transition gives the entry's state and changes
+   * HydrationBarrierContext, and the store is released after that commit. A
+   * navigation committed earlier releases the store before its update.
+   * Absent for a provider mounted on the client.
+   */
+  hydration?: { settled: Promise<void> };
 }
 
 /**
@@ -312,9 +328,18 @@ export function NavigationProvider({
   basename,
   appShellRef,
   nonce,
+  hydration,
 }: 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(() =>
+    hydration ? undefined : eventController.getLocationState(),
+  );
+  // HydrationBarrierContext's value; see NavigationProviderProps.hydration.
+  const [hydrationBarrier, setHydrationBarrier] = useState(0);
+  const hydrationOpen = useRef(hydration !== undefined);
 
   /**
    * Navigate to a URL (delegates to bridge)
@@ -350,6 +375,8 @@ export function NavigationProvider({
       navigate,
       refresh,
       defaultPrefetch: initialPayload.metadata.defaultPrefetch,
+      // Fixed for the document: read once, with the stable value.
+      origin: (eventController.getState().location as URL | undefined)?.origin,
     } as NavigationStoreContextValue;
     Object.defineProperty(value, "basename", {
       configurable: true,
@@ -373,6 +400,45 @@ export function NavigationProvider({
     return startConnectionWarmup();
   }, [warmupEnabled]);
 
+  // The document has been revealed: one transition gives the entry's location
+  // state and moves the barrier, so React hydrates every boundary still
+  // dehydrated before it commits.
+  useEffect(() => {
+    if (!hydration) return;
+    let cancelled = false;
+    void hydration.settled.then(() => {
+      if (cancelled || !hydrationOpen.current) return;
+      startTransition(() => {
+        setLocationState(eventController.getLocationState());
+        setHydrationBarrier((n) => n + 1);
+      });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // After the barrier's commit no boundary under this provider is dehydrated:
+  // release the store, and its handle writes reach their readers.
+  useEffect(() => {
+    if (hydrationBarrier === 0) return;
+    hydrationOpen.current = false;
+    eventController.releaseHydrationLock();
+  }, [hydrationBarrier]);
+
+  // 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
@@ -411,16 +477,30 @@ export function NavigationProvider({
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
+      if (process.env.NODE_ENV !== "production") auditTreeUpdate(update.root);
       // Capture scroll intent — it will be applied in useLayoutEffect
       // after React commits this state update to the DOM.
       // Always assign (even undefined) to clear stale scroll from prior navigations,
       // so server actions or error updates don't accidentally replay old scroll.
       pendingScrollRef.current = update.scroll;
 
+      // Committed before the document finished hydrating: end the window
+      // first, so the page this update mounts reads the live store. A
+      // boundary of the document still dehydrated then hydrates against the
+      // live store; where that differs from its HTML, React reports the
+      // mismatch and renders the boundary on the client.
+      if (hydrationOpen.current) {
+        hydrationOpen.current = false;
+        eventController.releaseHydrationLock();
+      }
+
       setPayload({
         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 +586,11 @@ export function NavigationProvider({
 
   return (
     <NavigationStoreContext.Provider value={contextValue}>
-      {content}
+      <LocationStateContext.Provider value={locationState}>
+        <HydrationBarrierContext.Provider value={hydrationBarrier}>
+          {content}
+        </HydrationBarrierContext.Provider>
+      </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
@@ -56,6 +57,13 @@ export interface NavigationStoreContextValue {
 
   /** Router default from this instance's initial payload. */
   defaultPrefetch?: PrefetchStrategy;
+
+  /**
+   * The document's origin, fixed for its lifetime. Link compares absolute
+   * hrefs against it (data-external) and useLinkStatus resolves link targets
+   * with it.
+   */
+  origin: string | undefined;
 }
 
 /**
@@ -66,3 +74,25 @@ 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);
+
+/**
+ * Read by no component. NavigationProvider changes its value in a transition so
+ * that React hydrates every boundary still dehydrated beneath it before that
+ * commit: React hydrates a dehydrated boundary first when a provider above it
+ * changes, and nothing re-renders for a value nobody reads. See
+ * NavigationProviderProps.hydration.
+ */
+export const HydrationBarrierContext: Context<number> =
+  createContext<number>(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,10 @@
 "use client";
 
-import { useState, useEffect, useRef } from "react";
+import { useContext, useEffect } from "react";
+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 +18,16 @@ 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")
-  );
-}
-
 /**
- * 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 +57,30 @@ 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.
+  // While the document hydrates, the provider holds `undefined`, what SSR
+  // rendered, and gives the entry's state once every boundary has hydrated
+  // (NavigationProvider's hydration barrier, issue #992).
+  const state = (optimistic ? readableLocationState(optimistic) : entry)?.[
+    key || "state"
+  ] as TState | undefined;
 
-  // 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/use-action.ts

@@ -149,7 +149,10 @@ export function useAction<T>(
     if (!ctx) {
       return selector ? selector(DEFAULT_ACTION_STATE) : DEFAULT_ACTION_STATE;
     }
-    const state = ctx.eventController.getActionState(actionId);
+    // The document renders no action in flight.
+    const state = ctx.eventController.getHydrationSnapshot()
+      ? DEFAULT_ACTION_STATE
+      : ctx.eventController.getActionState(actionId);
     return selector ? selector(state) : state;
   });
   const prevSelected = useRef(baseState);

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

@@ -53,6 +53,9 @@ export function useHandle<T, A, S>(
       return selector ? selector(collected) : collected;
     }
 
+    // Until every boundary has hydrated the store returns the state the
+    // document's HTML was rendered with (EventController.lockHydration), so a
+    // reader hydrating late reads what SSR rendered (issue #1035).
     const state = ctx.eventController.getHandleState();
     const collected = collectHandleData(
       handle,