@rangojs/router 0.20.0 → 0.22.0

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

@@ -82,14 +82,15 @@ export function useLinkStatus(): LinkStatus {
   const linkTo = useContext(LinkContext);
   const ctx = useContext(NavigationStoreContext);
 
-  const origin =
-    typeof window !== "undefined" ? window.location.origin : "http://localhost";
+  const origin = ctx?.origin ?? "http://localhost";
 
   const [basePending, setBasePending] = useState<boolean>(() => {
     if (!ctx || linkTo === null) {
       return false;
     }
-    const state = ctx.eventController.getState();
+    const state =
+      ctx.eventController.getHydrationSnapshot()?.state ??
+      ctx.eventController.getState();
     return isPendingFor(linkTo, state.pendingUrl, origin);
   });
 

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

@@ -47,7 +47,10 @@ export function useNavigation<T>(
   }
 
   const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
-    const publicState = toPublicState(ctx.eventController.getState());
+    const publicState = toPublicState(
+      ctx.eventController.getHydrationSnapshot()?.state ??
+        ctx.eventController.getState(),
+    );
     return selector ? selector(publicState) : publicState;
   });
   const prevState = useRef(baseValue);

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

@@ -49,7 +49,10 @@ export function useParams<T>(
   const optimistic = useContext(OptimisticLocationContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {
-    const params = ctx ? ctx.eventController.getParams() : EMPTY_PARAMS;
+    const params = ctx
+      ? (ctx.eventController.getHydrationSnapshot()?.params ??
+        ctx.eventController.getParams())
+      : EMPTY_PARAMS;
     return selector ? selector(params) : params;
   });
 

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

@@ -26,7 +26,10 @@ export function usePathname(): string {
     if (!ctx) {
       return "/";
     }
-    return (ctx.eventController.getState().location as URL).pathname;
+    const state =
+      ctx.eventController.getHydrationSnapshot()?.state ??
+      ctx.eventController.getState();
+    return (state.location as URL).pathname;
   });
 
   const prevPathname = useRef(pathname);

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

@@ -119,9 +119,11 @@ export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
   // (no provider) seeds empty.
   const [searchParams, setSearchParamsState] =
     useState<ReadonlyURLSearchParams>(() => {
-      const location = ctx?.eventController.getState().location as
-        | URL
-        | undefined;
+      const state = ctx
+        ? (ctx.eventController.getHydrationSnapshot()?.state ??
+          ctx.eventController.getState())
+        : undefined;
+      const location = state?.location as URL | undefined;
       return new URLSearchParams(location?.searchParams);
     });
 

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

@@ -64,16 +64,22 @@ export function useSegments<T>(
 ): T | SegmentsState {
   const ctx = useContext(NavigationStoreContext);
 
-  // Build initial state from event controller when context exists.
-  // Inlined rather than calling recompute() because the segmentsCache ref
-  // is not yet initialized during the useState initializer.
+  // The selector is applied when the store changes, never during render, as in
+  // useNavigation and useAction: the hook renders its own state only. A new
+  // selector identity is not a reactive input; it applies from the next store
+  // change.
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
   const [state, setState] = useState<T | SegmentsState>(() => {
     if (!ctx) {
       const fallbackLocation = new URL("/", "http://localhost");
       const fallbackState = buildSegmentsState(fallbackLocation, []);
       return selector ? selector(fallbackState) : fallbackState;
     }
-    const location = ctx.eventController.getLocation();
+    const location =
+      ctx.eventController.getHydrationSnapshot()?.state.location ??
+      ctx.eventController.getLocation();
     const handleState = ctx.eventController.getHandleState();
     const segmentsState = buildSegmentsState(
       location as URL,
@@ -83,69 +89,45 @@ export function useSegments<T>(
   });
 
   const prevState = useRef(state);
-  const selectorRef = useRef(selector);
-  selectorRef.current = selector;
-
-  const prevSelectorIdentity = useRef(selector);
-
-  const segmentsCache = useRef<{
-    location: URL;
-    routeSegmentIds: string[];
-    state: SegmentsState;
-  } | null>(null);
-
-  function recompute(
-    sel: ((state: SegmentsState) => T) | undefined,
-  ): T | SegmentsState {
-    const location = ctx!.eventController.getLocation();
-    const handleState = ctx!.eventController.getHandleState();
 
-    const cache = segmentsCache.current;
-    let segmentsState: SegmentsState;
-    if (
-      cache &&
-      cache.location === location &&
-      cache.routeSegmentIds === handleState.routeSegmentIds
-    ) {
-      segmentsState = cache.state;
-    } else {
-      segmentsState = buildSegmentsState(
-        location as URL,
-        handleState.routeSegmentIds,
-      );
-      segmentsCache.current = {
-        location: location as URL,
-        routeSegmentIds: handleState.routeSegmentIds,
-        state: segmentsState,
-      };
-    }
-    return sel ? sel(segmentsState) : segmentsState;
-  }
-
-  if (ctx && selector !== prevSelectorIdentity.current) {
-    prevSelectorIdentity.current = selector;
-    const nextSelected = recompute(selector);
-    if (!shallowEqual(nextSelected, prevState.current)) {
-      prevState.current = nextSelected;
-      setState(nextSelected);
-    }
-  }
-
-  // Subscribe to store changes. The eager block above handles selector
-  // changes and SSR drift, so no initial updateState() call is needed.
   useEffect(() => {
     if (!ctx) {
       return;
     }
 
+    // Reused while the location and route segments are unchanged, so a
+    // selector returning part of it keeps the same references.
+    let cache: {
+      location: URL;
+      routeSegmentIds: string[];
+      state: SegmentsState;
+    } | null = null;
+
     const updateState = () => {
-      const nextSelected = recompute(selectorRef.current);
+      const location = ctx.eventController.getLocation() as URL;
+      const { routeSegmentIds } = ctx.eventController.getHandleState();
+      if (
+        !cache ||
+        cache.location !== location ||
+        cache.routeSegmentIds !== routeSegmentIds
+      ) {
+        cache = {
+          location,
+          routeSegmentIds,
+          state: buildSegmentsState(location, routeSegmentIds),
+        };
+      }
+      const sel = selectorRef.current;
+      const nextSelected = sel ? sel(cache.state) : cache.state;
       if (!shallowEqual(nextSelected, prevState.current)) {
         prevState.current = nextSelected;
         setState(nextSelected);
       }
     };
 
+    // Catch up with a change between the seeding render and this effect.
+    updateState();
+
     const unsubscribeNav = ctx.eventController.subscribe(updateState);
     const unsubscribeHandles =
       ctx.eventController.subscribeToHandles(updateState);

package/src/browser/rsc-router.tsx

@@ -6,6 +6,7 @@ import {
 import {
   createNavigationStore,
   generateHistoryKey,
+  liveHandleDataForCache,
 } from "./navigation-store.js";
 import { createEventController } from "./event-controller.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
@@ -27,11 +28,14 @@ import { expandPayloadFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import {
+  auditTreeCause,
+  setSuspenseAuditStreamProbe,
+} from "../suspense-audit.js";
 import {
   setPrefetchConcurrency,
   setPrefetchDecoder,
 } from "./prefetch/loader.js";
-import { setDefaultPrefetchStrategy } from "./prefetch/default-strategy.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -39,7 +43,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
@@ -143,6 +151,12 @@ export interface BrowserAppContext {
    * prefetch TTL are document-lifetime too (see AppShell).
    */
   appShellRef?: import("./app-shell.js").AppShellRef;
+  /**
+   * Resolves when the document's stream has ended and every Suspense boundary
+   * in it has been revealed. NavigationProvider closes the hydration window
+   * then (NavigationProviderProps.hydration).
+   */
+  documentRevealed: Promise<void>;
 }
 
 // Module-level state for the initialized app
@@ -174,6 +188,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 +228,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
@@ -246,6 +265,13 @@ export async function initBrowserApp(
   const eventController = createEventController({
     initialLocation: new URL(window.location.href),
   });
+  if (process.env.NODE_ENV !== "production") {
+    setSuspenseAuditStreamProbe(() => eventController.getState().isStreaming);
+  }
+
+  // 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,11 +320,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
-          // meanwhile; nothing is lost.
-          await hydrationCommitted;
+          // Applied as they arrive: during the hydration window (lockHydration
+          // below) the store keeps them in order, and readers see them after
+          // the commit that hydrates every boundary (NavigationProvider).
           for await (const rawLateData of lateGenerator) {
             // Handles are async by design: a push(promise) value resolves
             // whenever it resolves — only SSR'd handles are awaited server-
@@ -324,6 +348,11 @@ export async function initBrowserApp(
   } else {
     bootLog("handles: none in payload");
   }
+  // The hydration window: until NavigationProvider's barrier commit has
+  // hydrated every boundary, reads return the handle state the document's HTML
+  // was rendered with, and the late channel's and any navigation's handle
+  // writes wait in order (EventController.lockHydration).
+  eventController.lockHydration();
 
   // Create composable utilities
   const client = createNavigationClient(deps);
@@ -354,13 +383,10 @@ export async function initBrowserApp(
   if (prefetchConcurrency !== undefined) {
     setPrefetchConcurrency(prefetchConcurrency);
   }
-  // Apply the router-wide default Link prefetch strategy. Undefined (older
-  // server payload) keeps the module's environment-aware default, which equals
-  // the server resolver's default by contract — see default-strategy.ts.
+  // The router-wide default Link prefetch strategy, for delegated plain
+  // anchors (navigation bridge). Undefined falls back to the environment
+  // default (default-strategy.ts).
   const defaultPrefetch = initialPayload.metadata?.defaultPrefetch;
-  if (defaultPrefetch !== undefined) {
-    setDefaultPrefetchStrategy(defaultPrefetch);
-  }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
   // client chunks (same createFromFetch the navigation client uses). Fragment
@@ -563,7 +589,11 @@ export async function initBrowserApp(
               intercept: responseIsIntercept,
             });
             store.setHistoryKey(historyKey);
-            const currentHandleData = eventController.getHandleState().data;
+            const currentHandleData = liveHandleDataForCache(
+              eventController,
+              store,
+              historyKey,
+            );
             store.cacheSegmentsForHistory(
               historyKey,
               segments,
@@ -571,6 +601,7 @@ export async function initBrowserApp(
             );
 
             const { main, intercept } = splitInterceptSegments(segments);
+            if (process.env.NODE_ENV !== "production") auditTreeCause("hmr");
             store.emitUpdate({
               root: renderSegments(main, {
                 interceptSegments: intercept.length > 0 ? intercept : undefined,
@@ -610,6 +641,28 @@ export async function initBrowserApp(
     linkInterceptionEnabled: linkInterception,
     version,
     appShellRef,
+    documentRevealed: new Promise<void>((resolve) => {
+      // Parsing ends with the stream, but React reveals a streamed boundary
+      // in batches up to 300 ms later (Fizz's $RC marks it `$~` and reveals
+      // it from a timer), so the boundary is still pending at
+      // DOMContentLoaded. A transition then would make React client-render
+      // it over its server HTML.
+      const start = (): void => {
+        // A reveal rewrites the same comment's data, or React removes the
+        // node; a boundary nested in revealed content joins the document
+        // only then, so resolve only once a full walk finds none.
+        let pending = unrevealedBoundaries();
+        const check = (): void => {
+          pending = pending.filter(isUnrevealed);
+          if (pending.length === 0) pending = unrevealedBoundaries();
+          if (pending.length > 0) requestAnimationFrame(check);
+          else resolve();
+        };
+        check();
+      };
+      if (document.readyState !== "loading") start();
+      else document.addEventListener("DOMContentLoaded", start, { once: true });
+    }),
   };
   browserAppContext = context;
 
@@ -617,22 +670,27 @@ export async function initBrowserApp(
   return context;
 }
 
+/**
+ * A Suspense boundary of the document React has not revealed yet: Fizz marks
+ * one `$?` while its content streams and `$~` once its reveal is queued.
+ */
+function isUnrevealed(node: Comment): boolean {
+  return node.isConnected && (node.data === "$?" || node.data === "$~");
+}
+
+function unrevealedBoundaries(): Comment[] {
+  const found: Comment[] = [];
+  const walker = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (isUnrevealed(node as Comment)) found.push(node as Comment);
+  }
+  return found;
+}
+
 // Once-flag so the hydration-commit boot log fires a single time (StrictMode
 // 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.
-let resolveHydrationCommitted!: () => void;
-const hydrationCommitted: Promise<void> = new Promise((resolve) => {
-  resolveHydrationCommitted = resolve;
-});
-
 /**
  * Get the browser app context. Throws if initBrowserApp hasn't been called.
  */
@@ -669,13 +727,18 @@ export interface RangoProps {}
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *
  * async function main() {
- *   await initBrowserApp({ rscStream, deps: rscBrowser });
+ *   const { initialPayload } = await initBrowserApp({ rscStream, deps: rscBrowser });
+ *   // Rejects when the action's state is not Flight-serializable.
+ *   const formState = await Promise.resolve(initialPayload.formState).catch(
+ *     () => undefined,
+ *   );
  *
  *   hydrateRoot(
  *     document,
  *     <React.StrictMode>
  *       <Rango />
- *     </React.StrictMode>
+ *     </React.StrictMode>,
+ *     formState ? { formState } : undefined
  *   );
  * }
  * main();
@@ -694,6 +757,7 @@ export function Rango(_props: RangoProps): React.ReactElement {
     version,
     appShellRef,
     linkInterceptionEnabled,
+    documentRevealed,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -708,9 +772,6 @@ export function Rango(_props: RangoProps): React.ReactElement {
       hydrationCommitLogged = true;
       bootLog("hydration commit (root effect flushed)");
     }
-    // Release the late handle channel (see hydrationCommitted above).
-    // StrictMode double-invoke: resolving twice is a no-op.
-    resolveHydrationCommitted();
     return cleanupPrefetch;
   }, [bridge, linkInterceptionEnabled]);
 
@@ -726,6 +787,7 @@ export function Rango(_props: RangoProps): React.ReactElement {
       version={version}
       basename={initialPayload.metadata?.basename}
       appShellRef={appShellRef}
+      hydration={{ settled: documentRevealed }}
     />
   );
 }

package/src/browser/segment-reconciler.ts

@@ -201,9 +201,9 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
       // inside renderSegments, causing React to unmount the entire chain
       // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
       // Suspender) every time the user opened an intercept or navigated back
-      // to a cached page. The flicker is now prevented by renderSegments'
-      // promise memoization keeping React's use() in "known fulfilled" state,
-      // so preserving `loading` keeps the element tree stable.
+      // to a cached page. The flicker is now prevented by renderSegments
+      // handing the boundary settled content and loader data, so preserving
+      // `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

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

@@ -13,6 +13,7 @@ import {
   reconcileErrorSegments,
 } from "./segment-reconciler.js";
 import { startTransition } from "react";
+import { liveHandleDataForCache } from "./navigation-store.js";
 import type { EventController, ActionHandle } from "./event-controller.js";
 import {
   toNetworkError,
@@ -36,6 +37,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";
@@ -45,6 +47,7 @@ import {
   type TransitionWhenActionInput,
 } from "./transition-when.js";
 import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
+import { auditTreeCause } from "../suspense-audit.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -79,11 +82,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();
   }
 }
 
@@ -636,7 +650,11 @@ export function createServerActionBridge(
         // handle pushed by the error-boundary render still applies — see the
         // "normal" case below for why caching after onUpdate dropped it.
         store.setSegmentIds(segmentIdsAfterError);
-        const currentHandleData = eventController.getHandleState().data;
+        const currentHandleData = liveHandleDataForCache(
+          eventController,
+          store,
+          currentKey,
+        );
         store.cacheSegmentsForHistory(
           currentKey,
           errorResult.segments,
@@ -647,6 +665,7 @@ export function createServerActionBridge(
         // Update UI with error boundary: urgent when transition({ when })
         // gated it off, like every gated-off commit.
         const errorUpdate = { root: errorTree, metadata: metadata! };
+        if (process.env.NODE_ENV !== "production") auditTreeCause("action");
         if (errorGatedOff) onUpdate(errorUpdate);
         else startTransition(() => onUpdate(errorUpdate));
 
@@ -734,7 +753,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).
@@ -834,7 +857,11 @@ export function createServerActionBridge(
             // Location state already applied above (pre-switch); this action's
             // UI render is skipped because a later sibling consolidates.
             store.setSegmentIds(matched);
-            const currentHandleData = eventController.getHandleState().data;
+            const currentHandleData = liveHandleDataForCache(
+              eventController,
+              store,
+              currentKey,
+            );
             store.cacheSegmentsForHistory(
               currentKey,
               fullSegments,
@@ -846,9 +873,13 @@ export function createServerActionBridge(
 
         case "normal": {
           // transition({ when }) for the action commit (kind "action"): the
-          // page does not move, so `to` is `from`. False commits urgently (a
-          // re-suspending segment streams its loading()) and switches every
-          // <ViewTransition> class to "none"; true keeps the startTransition.
+          // page does not move, so `to` is `from`. False commits urgently and
+          // switches every <ViewTransition> class to "none"; the tree below
+          // is built with isAction, which awaits segment content and loader
+          // data, so a boundary on screen is handed settled values. A build
+          // then shows no loading(); the dev server still does, because the
+          // client references of a fresh payload are still importing in that
+          // first render. True keeps the startTransition.
           // This commit runs after awaits, outside the transition React opens
           // for a form action / useActionState call, so React does not force
           // a transition on it. The tree shape never changes, so
@@ -894,7 +925,11 @@ export function createServerActionBridge(
           //
           // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
-          const currentHandleData = eventController.getHandleState().data;
+          const currentHandleData = liveHandleDataForCache(
+            eventController,
+            store,
+            currentKey,
+          );
           store.cacheSegmentsForHistory(
             currentKey,
             fullSegments,
@@ -903,6 +938,7 @@ export function createServerActionBridge(
           store.rememberDisplayedEntry(metadata?.routeName);
 
           const actionUpdate = { root: newTree, metadata: metadata! };
+          if (process.env.NODE_ENV !== "production") auditTreeCause("action");
           if (gatedOff) onUpdate(actionUpdate);
           else startTransition(() => onUpdate(actionUpdate));
           // Invalidation deferred to finalizeAction() (runs after this caches

package/src/browser/types.ts

@@ -1,4 +1,5 @@
 import type { ReactNode, ComponentType } from "react";
+import type { ReactFormState } from "react-dom/client";
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import type { RenderSegmentsOptions } from "../segment-system.js";
@@ -14,6 +15,11 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 export interface RscPayload<TMetadata = RscMetadata> {
   metadata?: TMetadata;
   returnValue?: ActionResult;
+  /**
+   * Form state of a PE POST document, for hydrateRoot's `formState` option.
+   * Rejects when the action's state is not Flight-serializable.
+   */
+  formState?: Promise<ReactFormState>;
 }
 
 /**
@@ -459,6 +465,8 @@ export interface NavigateOptionsInternal extends Omit<
   state?: unknown;
   /** Skip segment cache (used by redirect-with-state to force re-render) */
   _skipCache?: boolean;
+  /** Server redirects already followed by this navigation chain (0 for a user navigation) */
+  _redirectHops?: number;
 }
 
 /**
@@ -554,6 +562,9 @@ export type StateListener = () => void;
  * EventController owns the public navigation lifecycle exposed by hooks.
  */
 export interface NavigationStore {
+  /** Client loader data for useLoader / useFetchLoader (loader-store.ts). */
+  readonly loaders: import("../loader-store.js").LoaderStore;
+
   // Internal segment state (for bridges)
   getSegmentState(): SegmentState;
   setPath(path: string): void;