@rangojs/router 0.20.0 → 0.22.0

package/dist/bin/rango.js

@@ -1571,6 +1571,11 @@ function mergeFullManifests(manifests) {
         manifest.passthroughRoutes,
         overwrittenRoutes
       ),
+      onDemandRoutes: mergeRouteList(
+        merged.onDemandRoutes,
+        manifest.onDemandRoutes,
+        overwrittenRoutes
+      ),
       responseTypeRoutes: mergeRouteRecord(
         merged.responseTypeRoutes,
         manifest.responseTypeRoutes,
@@ -1599,14 +1604,33 @@ var init_merge_full_manifests = __esm({
   }
 });
 
+// src/router-versions.ts
+var DEFAULT_ROUTER_VERSIONS_KEY;
+var init_router_versions = __esm({
+  "src/router-versions.ts"() {
+    "use strict";
+    DEFAULT_ROUTER_VERSIONS_KEY = "*";
+  }
+});
+
 // src/vite/plugins/virtual-entries.ts
 function getVirtualVersionContent(version) {
-  return `export const VERSION = ${JSON.stringify(version)};`;
-}
-var VIRTUAL_ENTRY_BROWSER, VIRTUAL_IDS;
+  return [
+    `export const VERSION = ${JSON.stringify(version)};`,
+    `export const ROUTER_VERSIONS = undefined;`
+  ].join("\n");
+}
+function getVirtualBuildVersionContent() {
+  return [
+    `export const ROUTER_VERSIONS = ${ROUTER_VERSIONS_PLACEHOLDER};`,
+    `export const VERSION = ROUTER_VERSIONS[${JSON.stringify(DEFAULT_ROUTER_VERSIONS_KEY)}][1];`
+  ].join("\n");
+}
+var VIRTUAL_ENTRY_BROWSER, VIRTUAL_IDS, ROUTER_VERSIONS_PLACEHOLDER;
 var init_virtual_entries = __esm({
   "src/vite/plugins/virtual-entries.ts"() {
     "use strict";
+    init_router_versions();
     VIRTUAL_ENTRY_BROWSER = `
 import {
   createFromReadableStream,
@@ -1634,6 +1658,12 @@ async function initializeApp() {
   // is the default; createRouter({ strictMode: false }) ships the opt-out in the
   // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
   const { strictMode, initialPayload } = await initBrowserApp({ rscStream, deps });
+  // Set only on a document a no-JS useActionState POST rendered: React needs
+  // the server's form state to hydrate the hook without resetting it. A state
+  // Flight could not carry rejects: hydrate without it, as before.
+  const formState = await Promise.resolve(initialPayload.formState).catch(
+    () => undefined
+  );
 
   if (import.meta.hot) {
     const { startDevDiscoveryHandshake } = await import(
@@ -1648,7 +1678,8 @@ async function initializeApp() {
   const app = createElement(Rango);
   hydrateRoot(
     document,
-    strictMode === false ? app : createElement(StrictMode, null, app)
+    strictMode === false ? app : createElement(StrictMode, null, app),
+    formState ? { formState } : undefined
   );
 }
 
@@ -1660,6 +1691,7 @@ initializeApp().catch(console.error);
       rsc: "virtual:rsc-router/entry.rsc.js",
       version: "@rangojs/router:version"
     };
+    ROUTER_VERSIONS_PLACEHOLDER = "__RANGO_ROUTER_VERSIONS__";
   }
 });
 
@@ -1772,8 +1804,7 @@ function getClientModuleSignature(source) {
   };
 }
 function createVersionPlugin() {
-  const buildVersion = Date.now().toString(16);
-  let currentVersion = buildVersion;
+  let currentVersion = Date.now().toString(16);
   let isDev = false;
   let server = null;
   let resolvedCacheDir;
@@ -1793,13 +1824,6 @@ function createVersionPlugin() {
   return {
     name: "@rangojs/router:version",
     enforce: "pre",
-    // The build-time shell capture phase (producer B, #699) stamps entries
-    // with THIS instance's version — the value folded into the shipped worker
-    // — never the discovery temp server's own version-plugin value (a
-    // different Date.now() stamp that would fail the serve-side gate).
-    api: {
-      getBuildVersion: () => currentVersion
-    },
     configResolved(config) {
       isDev = config.command === "serve";
       resolvedCacheDir = config.cacheDir ? String(config.cacheDir).replace(/\\/g, "/") : void 0;
@@ -1821,7 +1845,7 @@ function createVersionPlugin() {
     },
     load(id) {
       if (id === "\0" + VIRTUAL_IDS.version) {
-        return getVirtualVersionContent(currentVersion);
+        return isDev ? getVirtualVersionContent(currentVersion) : getVirtualBuildVersionContent();
       }
       return null;
     },
@@ -2150,7 +2174,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/dist/types/browser/event-controller.d.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { NavigationLocation, NavigateOptionsInternal, TrackedActionState, InflightAction, RscMetadata, HandleData, StreamingToken } from "./types.js";
+import { type LocationStateSnapshot } from "./react/location-state-shared.js";
 /**
  * Phase of a navigation operation
  */
@@ -101,6 +102,15 @@ export interface HandleState {
     segmentOrder: string[];
     routeSegmentIds: string[];
 }
+/**
+ * What the document's HTML was rendered with, kept for the hydration window
+ * (EventController.lockHydration).
+ */
+export interface HydrationSnapshot {
+    state: DerivedNavigationState;
+    params: Record<string, string>;
+    handles: HandleState;
+}
 /**
  * Result from starting a navigation
  * Implements Disposable for use with `using` keyword
@@ -196,6 +206,31 @@ export interface EventController {
      */
     resolvedIds?: string[]): void;
     getHandleState(): HandleState;
+    /**
+     * Open the hydration window. Until releaseHydrationLock(), getHandleState()
+     * returns the state the document's HTML was rendered with, and handle writes
+     * (setHandleData, setRouteSegmentIds) wait in order. initBrowserApp opens it
+     * before hydrateRoot, once the document's handle snapshot is applied: a hook
+     * reading the handle state when its boundary hydrates, however late, reads
+     * what SSR rendered (issue #1035).
+     */
+    lockHydration(): void;
+    /**
+     * While the hydration window is open, the state the document's HTML was
+     * rendered with; undefined once it closes. A router hook's first render
+     * reads it: a component hydrating in a boundary that streamed in late
+     * renders what SSR rendered, even after a navigation or an action started.
+     * The hook's effect then catches up with the live state, and its
+     * subscription stays live, so pending UI is not held back.
+     */
+    getHydrationSnapshot(): HydrationSnapshot | undefined;
+    /**
+     * Close the hydration window: apply the writes that waited, in order, and
+     * notify handle subscribers. NavigationProvider calls it after the commit
+     * that made React hydrate every boundary still dehydrated (its barrier).
+     * Idempotent.
+     */
+    releaseHydrationLock(): void;
     /**
      * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
      * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
@@ -206,6 +241,20 @@ export interface EventController {
     setRouteSegmentIds(matched: string[]): void;
     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;
     getCurrentNavigation(): NavigationEntry | null;
     getInflightActions(): Map<string, ActionEntry>;
     /** Whether any concurrent actions have occurred (shared across all handles) */

package/dist/types/browser/history-state.d.ts

@@ -37,8 +37,20 @@ export declare const SHELL_MISS_MARKER: string;
  */
 export declare 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 declare function mergeLocationState(locationState: Record<string, unknown>): void;
+export declare function clearLocationStateOnDocumentLoad(): void;
+/**
+ * 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 declare function mergeLocationState(locationState: Record<string, unknown>): Record<string, unknown>;

package/dist/types/browser/navigation-store.d.ts

@@ -1,4 +1,5 @@
 import type { NavigationStore, ResolvedSegment, HandleData } from "./types.js";
+import type { EventController } from "./event-controller.js";
 /**
  * Clone the handleData CONTAINERS (the handle-name map and each segment map) so
  * a cache entry is decoupled from the live map that eventController mutates — it
@@ -11,6 +12,14 @@ import type { NavigationStore, ResolvedSegment, HandleData } from "./types.js";
  * non-serializable bucket contents (React elements, functions, etc.).
  */
 export declare function cloneHandleData(handleData: HandleData): HandleData;
+/**
+ * Handle data to write into the history cache for the page on screen. During
+ * the hydration window getHandleState() is the document snapshot while late
+ * pushes sit queued in the controller (they are already in the cache entry,
+ * written by rsc-router), so writing the snapshot back would drop them; the
+ * entry's own data is the live view then.
+ */
+export declare function liveHandleDataForCache(eventController: Pick<EventController, "getHandleState" | "getHydrationSnapshot">, store: Pick<NavigationStore, "getCachedSegments">, historyKey: string): HandleData;
 /**
  * Options for generating a history key
  */

package/dist/types/browser/navigation-transaction.d.ts

@@ -36,6 +36,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;
 }
 /**
  * Options that can override the pre-configured commit settings
@@ -57,6 +62,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;
 }
 /**
  * Bound transaction with pre-configured commit options (without segmentIds/segments)

package/dist/types/browser/partial-update.d.ts

@@ -3,6 +3,7 @@ import type { ReactNode } from "react";
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import type { NavigationUpdate } from "./types.js";
+import type { LoaderStore } from "../loader-store.js";
 import { type TransitionWhenActionInput } from "./transition-when.js";
 /**
  * Hold/animate decision for a commit: a non-intercept segment carries a
@@ -18,7 +19,7 @@ export declare function shouldStartViewTransition(segments: readonly ResolvedSeg
  * directly: nothing is held there, a reader of a pending stream suspends to
  * its fallback. Also used by renderRoute's navigate() (testing/render-route.tsx).
  */
-export declare function commitInTransition(onUpdate: UpdateSubscriber, segments: readonly ResolvedSegment[], update: NavigationUpdate, transitionTypes: readonly string[]): void;
+export declare function commitInTransition(loaders: LoaderStore, onUpdate: UpdateSubscriber, segments: readonly ResolvedSegment[], update: NavigationUpdate, transitionTypes: readonly string[]): void;
 /**
  * Configuration for creating a partial updater
  */

package/dist/types/browser/prefetch/default-strategy.d.ts

@@ -2,30 +2,26 @@
  * Router-wide default prefetch strategy (client seat).
  *
  * The server resolves `createRouter({ defaultPrefetch })` once at router init
- * (router/prefetch-default.ts) and ships it in initial payload metadata; the
- * browser entry applies it here before hydration — same lifecycle as
- * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
- * explicit `prefetch` prop and every eligible intercepted plain anchor that has
- * not opted out with `data-prefetch="false"` or `data-prefetch="none"` uses it.
- * Containers use the same `false`/`none` vocabulary via
- * `data-prefetch-scope`.
- *
- * The module initial value must equal the server resolver's environment default:
- * `"none"` in development and `"viewport"` in production. During SSR this
- * module is never initialized from metadata, so keeping both seats aligned also
- * gives metadata-less payloads the documented behavior.
+ * (router/prefetch-default.ts) and ships it in initial payload metadata. The
+ * router store carries it to its readers: `<Link>` reads
+ * `NavigationStoreContext.defaultPrefetch`, and delegated plain anchors get it
+ * from the navigation bridge. Every `<Link>` without an explicit `prefetch`
+ * prop and every eligible intercepted plain anchor that has not opted out with
+ * `data-prefetch="false"` or `data-prefetch="none"` uses it. Containers use the
+ * same `false`/`none` vocabulary via `data-prefetch-scope`.
  */
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
-/** Reset module state between tests that replace browser media globals. */
-export declare function resetAdaptiveStrategyForTesting(): void;
 /**
- * Apply the server-resolved default strategy. Called once at browser app init
- * from payload metadata; also used by tests to reset state.
+ * The default for a payload without `defaultPrefetch`: the server resolver's
+ * environment default (`"none"` in development, `"viewport"` in production),
+ * mirrored without pulling router-layer code into the client bundle. NODE_ENV
+ * is folded by the app build.
+ */
+export declare const ENVIRONMENT_DEFAULT_PREFETCH: PrefetchStrategy;
+/**
+ * Resolve adaptive to the strategy for the current input capability. Called
+ * when a prefetch is armed or triggered, never during render.
  */
-export declare function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void;
-/** Current default strategy for Links and delegated plain anchors. */
-export declare function getDefaultPrefetchStrategy(): PrefetchStrategy;
-/** Resolve adaptive to the strategy for the current input capability. */
 export declare function resolveAdaptiveStrategy(strategy: PrefetchStrategy): PrefetchStrategy;
 /** Subscribe to changes in the input capability used by adaptive prefetch. */
 export declare function subscribeToAdaptiveStrategyChange(listener: () => void): () => void;

package/dist/types/browser/rango-state.d.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/dist/types/browser/react/NavigationProvider.d.ts

@@ -63,6 +63,19 @@ 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>;
+    };
 }
 /**
  * Navigation provider component
@@ -85,4 +98,4 @@ export interface NavigationProviderProps {
  * />
  * ```
  */
-export declare function NavigationProvider({ store, eventController, initialPayload, bridge, themeConfig, initialTheme, warmupEnabled, version, basename, appShellRef, nonce, }: NavigationProviderProps): ReactNode;
+export declare function NavigationProvider({ store, eventController, initialPayload, bridge, themeConfig, initialTheme, warmupEnabled, version, basename, appShellRef, nonce, hydration, }: NavigationProviderProps): ReactNode;

package/dist/types/browser/react/context.d.ts

@@ -2,6 +2,7 @@ import { 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
  *
@@ -47,6 +48,12 @@ export interface NavigationStoreContextValue {
     basename: string | undefined;
     /** 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;
 }
 /**
  * React context for navigation store
@@ -55,3 +62,21 @@ export interface NavigationStoreContextValue {
  * Use useNavigation hook for reactive state access.
  */
 export declare const NavigationStoreContext: Context<NavigationStoreContextValue | 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 declare const LocationStateContext: Context<LocationStateSnapshot>;
+/**
+ * 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 declare const HydrationBarrierContext: Context<number>;

package/dist/types/browser/react/location-state-shared.d.ts

@@ -9,12 +9,82 @@ export interface LocationStateEntry {
     readonly __rsc_ls_value: unknown;
     readonly __rsc_ls_lazy?: boolean;
 }
+/** Prefix of every typed location-state slot in `history.state`. */
+export declare const LOCATION_STATE_KEY_PREFIX: string;
+export declare function isLocationStateKey(key: string): boolean;
+/**
+ * `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 declare const LOCATION_STATE_KEY_SUFFIX_SEPARATOR: string;
+export declare const CLEAR_ON_RELOAD_KEY_SUFFIX: string;
+/**
+ * @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 declare function setLocationStateVersion(version: string | undefined): void;
+/**
+ * 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 declare function readableLocationState(location?: {
+    readonly state: unknown;
+} | undefined): 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 declare function locationStateSnapshot(entryState: unknown, previous?: LocationStateSnapshot): LocationStateSnapshot;
+/**
+ * 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 declare function stampLocationState(state: Record<string, unknown>): void;
+/**
+ * `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 declare function addLocationState(entryState: unknown, additions?: Record<string, unknown>): Record<string, unknown>;
 /**
  * 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;
 type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
@@ -116,13 +186,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
@@ -145,13 +218,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).
      */
@@ -161,8 +235,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).
      */

package/dist/types/browser/react/location-state.d.ts

@@ -1,10 +1,15 @@
 import { type LocationStateDefinition } from "./location-state-shared.js";
 export { createLocationState, isLocationStateEntry, resolveLocationStateEntries, type LocationStateEntry, type LocationStateDefinition, type LocationStateOptions, } from "./location-state-shared.js";
 /**
- * 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:

package/dist/types/browser/rsc-router.d.ts

@@ -95,6 +95,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>;
 }
 /**
  * Initialize the browser app. Must be called before rendering Rango.
@@ -131,13 +137,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();

package/dist/types/browser/types.d.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";
@@ -9,6 +10,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>;
 }
 /**
  * Handle data structure: handleName -> segmentId -> entries[]
@@ -406,6 +412,8 @@ export interface NavigateOptionsInternal extends Omit<NavigateOptions, "state">
     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;
 }
 /**
  * Options for useRouter push/replace methods.
@@ -476,6 +484,8 @@ 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;
     getSegmentState(): SegmentState;
     setPath(path: string): void;
     setCurrentUrl(url: string): void;

package/dist/types/build/generate-manifest.d.ts

@@ -37,6 +37,8 @@ export interface GeneratedManifest {
     prerenderRoutes?: string[];
     /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
     passthroughRoutes?: string[];
+    /** Route names opted into on-demand prerender (Prerender(..., { onDemand })) */
+    onDemandRoutes?: string[];
     /** Route name → response type for non-RSC routes */
     responseTypeRoutes?: Record<string, string>;
     /** Route name -> search schema descriptor for typed URL helpers */