@rangojs/router 0.20.0 → 0.21.0

package/dist/types/server/handle-store.d.ts

@@ -17,6 +17,25 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
  * Reads data directly from the store for each segment in order.
  */
 export declare function buildHandleSnapshot(handleStore: HandleStore, segmentOrder: string[]): HandleData;
+/**
+ * What a restored record is to one loader's handle pushes on this request
+ * (loader-cache.ts loaderPins; docs/design/handle-push-ownership.md). Two
+ * answers let the record's copies stand, two make them placeholders, and in
+ * each pair one also speaks for the loader's other pushes:
+ * - "pin": the request serves the loader's value from the pin stored with
+ *   the record, and the record lists every settled push of that run. Its
+ *   copies stand, and any other settled push of the loader is dropped.
+ * - "copies": its copies stand and nothing else is known: a dependency of
+ *   pinned loaders, or a pin written before captures recorded every push.
+ * - "hole": the route runs the loader on this request (it registers it and
+ *   the record does not pin it). Its copies are placeholders and a push made
+ *   in its body is its own, with or without copies.
+ * - "placeholders": its copies are placeholders and nothing else is known: a
+ *   dependency the route does not register while a pin is missing (the
+ *   record does not name the loader that ran it). Without copies its push
+ *   counts for the loader that awaits it.
+ */
+export type RecordAuthority = "pin" | "copies" | "hole" | "placeholders";
 /**
  * HandleStore tracks pending handler promises and stores handle data.
  *
@@ -81,69 +100,86 @@ export interface HandleStore {
      */
     push(handleName: string, segmentId: string, data: unknown, loaderPush?: boolean, owner?: string): void;
     /**
-     * push() a loader-cache HIT's replayed value, recorded from `loaderId`'s
-     * body (loader-cache.ts replayLoaderHandles). If that loader then runs live
-     * in this request, its first push removes every value replayed for it and
-     * takes the first one's position (later live pushes follow it), so the
-     * handle output stays live without a duplicate. A push counts as that
-     * loader's when it is made in its body, or in a body it entered that has
-     * no replayed values of its own (the capture credits a dependency's push
-     * under a live-lane loader to that loader); a hole's run that ends without
-     * one drops them (settleLoaderRun).
+     * push() a cached unit's copy of a value `loaderId`'s body pushed
+     * (handle-snapshot.ts appendHandles: a loader-cache or "use cache" HIT). If
+     * that loader then runs live in this request, its first push removes every
+     * copy pushed for it (replays and placeholders) and takes the first one's
+     * position, and the pushes of that run follow in push order, a dependency's
+     * included, so the handle output stays live without a duplicate. A push
+     * counts as that loader's when it is made in its body, or in a body it
+     * entered that has no copies of its own (the capture credits a dependency's
+     * push under a live-lane loader to that loader). A run that ends without a
+     * push leaves a replay in place, unless the loader is a hole
+     * (settleLoaderRun).
      */
     pushReplayed(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
     /**
-     * push() a document HIT's copy of `loaderId`'s settled push, restored from
-     * the shell's doc record (handle-snapshot.ts restoreHandles). The record is
-     * authoritative for that loader's settled pushes: the prelude was rendered
-     * from it, and a run of the loader on the HIT reads the store, not the
-     * capture's values. So from then on this request drops every settled,
-     * thenable-free push the loader makes (live, or replayed from a cache
-     * entry, anywhere inside its body), and keeps the ones holding a thenable
-     * (holdsThenable: what the record could not keep, `runs`), placed among the
-     * restored copies in the loader's push order. Only bake-lane owners are
-     * restored this way (withCacheLookup): a live-lane loader is a hole.
+     * push() a record's copy of `loaderId`'s push as a placeholder
+     * (handle-snapshot.ts restoreHandles): the record does not supply that
+     * loader's value on this request, so its own source decides its pushes. A
+     * live run replaces it as it does a replay; a run that ends without a push
+     * drops it (settleLoaderRun); a cached unit that claims the loader delivers
+     * in its place (replacePlaceholders).
+     */
+    pushPlaceholder(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
+    /**
+     * push() a record's copy of `loaderId`'s settled push that stands
+     * (restoreHandles): the record supplies the loader's value too. From then
+     * on this request drops every settled, thenable-free push the loader makes
+     * (live, or replayed from a cache entry, anywhere inside its body), and
+     * keeps the ones holding a thenable (holdsThenable: what the record could
+     * not keep), placed among the restored copies in the loader's push order.
      */
     pushRestored(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
     /**
-     * The loaders the route runs on the live lane (liveLaneLoaderIds), from a
-     * PPR shell record's restore (handle-snapshot.ts restoreHandles): the
-     * holes. A push counts for a restored loader when that loader is the
-     * replayed one or the innermost enclosing loader body that restored
-     * copies; the walk out through enclosing bodies stops at a hole's body,
-     * and a replay of a hole's push counts for none. So a restored loader
-     * never takes a push made inside a hole it awaited, while a body inside the
-     * hole that restored copies of its own (a dependency the capture ran under
-     * a bake-lane loader) still takes its pushes.
+     * What the record this request restored is to each loader (RecordAuthority;
+     * CacheScope.lookupRouteDetailed sets it on a hit). A "pin" loader counts
+     * as restored with or without copies. A hole is a "hole" loader or one with
+     * placeholders: the walk out through enclosing loader bodies that finds the
+     * loader a push counts for stops at its body, so a pinned loader never
+     * takes a push made inside a hole it awaited.
      */
-    markLiveLane(loaderIds: ReadonlySet<string>): void;
+    setRecordAuthority(authority: (loaderId: string) => RecordAuthority): void;
     /**
      * `loaderId`'s run in this request settled (resolved or rejected), its
-     * pushes made (loader-resolution.ts createLoaderExecutor). When the loader
-     * is a hole (markLiveLane), values replayed for it that no push of the run
-     * replaced are dropped: the run's output decides, so a hole that throws or
-     * skips its push shows none rather than the capture's. Any other loader's
-     * replayed values stay: a bake-lane loader's record is authoritative for
-     * its settled pushes, as its pin is for its data. Restored copies are not
-     * replays and stand.
+     * pushes made (loader-resolution.ts createLoaderExecutor). Its placeholders
+     * that no push of the run replaced are dropped: the run's output decides,
+     * so a loader that throws or skips its push shows none rather than the
+     * record's. A hole's replays go with them. Any other loader's replays stay
+     * (a dependency another entry's HIT replayed), and so do restored copies.
      */
     settleLoaderRun(loaderId: string): void;
     /**
-     * A hole's own cache() HIT (loader-cache.ts replayLoaderHandles, once it
-     * claims the hole): the values replayed for hole `loaderId` before (its
-     * shell copies, which restoreHandles leaves unclaimed, those of the
-     * dependencies credited to it included) give way to the pushes the entry
-     * recorded, none when it recorded none, so they match the entry's data.
-     * `deliver` makes the pushReplayed calls, which take the removed values'
-     * place in each array. Any other loader, or a hole with nothing replayed,
-     * delivers as a plain replay.
+     * A cached unit's HIT delivering the pushes it recorded for `loaderIds`,
+     * the loaders it claimed (appendHandles). Their placeholders give way to
+     * what `deliver` pushes for them, nothing when it pushes nothing, so the
+     * page shows the pushes of the run that produced the unit's value. The
+     * pushReplayed calls `deliver` makes take the removed values' place in each
+     * array, in order. Without placeholders it is a plain replay.
      */
-    redeliverReplays(loaderId: string, deliver: () => void): void;
+    replacePlaceholders(loaderIds: readonly string[], deliver: () => void): void;
     /**
      * Get all collected handle data after all handlers have settled.
      * Waits for `settled` (handler lane), then returns the data at that point.
      */
     getData(): Promise<HandleData>;
+    /**
+     * Fix the document lane at the store's current state. From then on
+     * `stream("settled")` yields this state and nothing newer, and
+     * `streamLate()` delivers every change made after it, whether or not it
+     * beat the handler barrier. The first call wins. It must run before the
+     * document stream is first read: a stream that started on the live state
+     * stays on it (reported through `onError` in development).
+     *
+     * A PPR shell HIT calls it once its record is replayed and before a loader
+     * runs (rsc-rendering.ts serveShellHit). The prelude was rendered from the
+     * record's handle data (resolvedHandleStream `recordedOnly`), so that is
+     * what the client must hydrate with. What the request's loaders then push,
+     * replace or drop is theirs, not the shell's: in the document snapshot it
+     * rendered elements the prelude never had, or left out ones it has (issue
+     * #1035), and it got there or not by a race with the lane's first read.
+     */
+    freezeDocumentSnapshot(): void;
     /**
      * Get an async iterator that yields handle data on each push.
      * Completes at the chosen settlement barrier: "fullySettled" (default —
@@ -152,6 +188,9 @@ export interface HandleStore {
      * blocking positions and must not wait on loader bodies).
      * Each yield contains the full accumulated state (not just the delta).
      * Safe for concurrent consumers (per-consumer version cursor).
+     * The "settled" lane of a frozen store (freezeDocumentSnapshot) yields the
+     * frozen state once, at once, and ends. That yield is the store's own
+     * frozen object: a consumer must not write to it.
      */
     stream(until?: "settled" | "fullySettled"): AsyncGenerator<HandleData, void, unknown>;
     /**
@@ -160,7 +199,9 @@ export interface HandleStore {
      * fullySettled. Returns without yielding when the auxiliary lane is empty
      * by the time `settled` resolves. The client consumes this post-hydration
      * (rsc-router.tsx) and merges via the same application path as nav-lane
-     * progressive handle updates.
+     * progressive handle updates. On a frozen store (freezeDocumentSnapshot)
+     * it starts from the frozen state instead: a change made before the
+     * handler barrier is late too.
      */
     streamLate(): AsyncGenerator<HandleData, void, unknown>;
     /**

package/dist/types/server/request-context.d.ts

@@ -20,6 +20,7 @@ import { type ContextVar } from "../context-var.js";
 import { type HandleStore, type HandleData } from "./handle-store.js";
 import { type MetricsStore } from "./context.js";
 import type { SegmentCacheStore } from "../cache/types.js";
+import type { RouterVersions } from "../router-versions.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
 import type { TransitionWhenRecord } from "../router/transition-when.js";
@@ -283,7 +284,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _routeRecordWindow?: RouteRecordWindow;
     /**
      * @internal Loader-family snapshot seed for a shell HIT's tail render:
-     * segment-key -> the capture's elided container (already Flight-deserialized
+     * loader id -> the capture's elided container (already Flight-deserialized
      * by serveShellHit) plus its capture-computed hole bit. resolveLoaderData
      * overlays it onto the fresh run's container (recorded paths pinned,
      * hole-marker paths keep the fresh nested promises) so the payload's baked
@@ -291,7 +292,9 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * and does not run the loader. Two owners: serveShellHit sets it on the
      * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
      * request context of a PPR partial replay once its doc record hits, and
-     * restores the previous value after the match.
+     * restores the previous value after the match. Read through servedPins
+     * (loader-cache.ts) only: it also decides which of the record's
+     * loader-owned handle pushes stand (loaderPins).
      */
     _shellLoaderSeed?: Map<string, import("../cache/shell-snapshot.js").ShellLoaderSeedEntry>;
     /**
@@ -348,9 +351,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * scope replaces any route-derived cache() scope for the tail's match
          * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
          * ShellRecordUnavailableError instead of resolving segments
-         * (withCacheLookup): a HIT never runs a handler. The record's
-         * loader-owned handle pushes restore as authoritative
-         * (HandleStore.pushRestored): the prelude rendered them.
+         * (withCacheLookup): a HIT never runs a handler.
          */
         docTail?: true;
         /**
@@ -708,6 +709,14 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     /** @internal Owning router id; scopes the search-schema/root-scope registry
      *  lookups per router (route-map-builder.ts) */
     _routerId?: string;
+    /**
+     * @internal Cache versions of the router serving this request. The cache
+     * factory builds a store per request without knowing the router, so a store
+     * reads its key versions from here, lazily, the same way CFCacheStore
+     * resolves its base URL (getCacheVersions, server/build-version-table.ts).
+     * Unset on a context no router created; a store then uses the build version.
+     */
+    _versions?: RouterVersions;
     /**
      * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
      * to avoid a second resolveRoute call. Cleared on HMR invalidation.
@@ -748,7 +757,7 @@ export interface RouteRecordWindow {
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
@@ -824,8 +833,13 @@ export interface CreateRequestContextOptions<TEnv> {
     themeConfig?: ResolvedThemeConfig | null;
     /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
     stateCookieName?: string;
-    /** Build version, used as the prefix of a server-rotated rango state value. */
-    version?: string;
+    /**
+     * The versions of the router serving this request (resolveRouterVersions).
+     * Stored as `_versions` for the cache stores; `document` is also the prefix
+     * of a server-rotated rango state value, which the browser compares with the
+     * payload's `metadata.version`.
+     */
+    versions?: RouterVersions;
 }
 /**
  * Create a full request context with all methods implemented

package/dist/types/testing/build-versions.d.ts

@@ -0,0 +1,32 @@
+import { type RouterVersions } from "../router-versions.js";
+export type { RouterVersions };
+/**
+ * The versions a simulated build ships.
+ *
+ * - `data` and `document`: the versions of every router the test does not list
+ *   under `routers` (the build's whole-build pair).
+ * - `routers`: versions per router id (`router.id`), as a host-router build
+ *   computes them.
+ */
+export interface BuildVersions extends RouterVersions {
+    routers?: Record<string, RouterVersions>;
+}
+/**
+ * Install the cache versions of a simulated build, or remove them with no
+ * argument (routers serve unversioned again, the default in tests).
+ *
+ * A router that sets `createRouter({ version })` keeps that value for both
+ * versions, exactly as in production.
+ *
+ * @example A deploy that changes the client only keeps cached data
+ * ```ts
+ * setBuildVersions({ data: "d1", document: "h1" });
+ * await serveShellRequest(router, "/product/1", { cacheStore });
+ * setBuildVersions({ data: "d1", document: "h2" });
+ * const { shellStatus } = await serveShellRequest(router, "/product/1", {
+ *   cacheStore,
+ * });
+ * // shellStatus is "MISS": the stored HTML was keyed by document version h1.
+ * ```
+ */
+export declare function setBuildVersions(versions?: BuildVersions): void;

package/dist/types/testing/dom.entry.d.ts

@@ -12,4 +12,4 @@
  * (`happy-dom` or `jsdom`).
  */
 export { renderRoute } from "./render-route.js";
-export type { RenderRouteSpec, RenderRouteOptions, TestRouterHandle, RenderRouteResult, HandleDataSeed, } from "./render-route.js";
+export type { RenderRouteSpec, RenderRouteOptions, TestRouterHandle, RenderRouteResult, RenderRouteHydrateResult, HandleDataSeed, } from "./render-route.js";

package/dist/types/testing/flight.entry.d.ts

@@ -31,4 +31,4 @@ export type { RenderServerTreeOptions, RenderServerTreeResult, ClientBoundary, B
 export { renderHandler } from "./render-handler.js";
 export type { TestableHandler, RenderHandlerOptions, RenderHandlerResult, StateCookieSeed, } from "./render-handler.js";
 export { serveShellRequest, resetShellTestState, } from "./serve-shell-request.js";
-export type { ServeShellRequestOptions, ServeShellRequestResult, } from "./serve-shell-request.js";
+export type { ServeShellRequestOptions, ServeShellRequestResult, ShellRequestHandles, } from "./serve-shell-request.js";

package/dist/types/testing/index.d.ts

@@ -48,6 +48,8 @@ export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache
 export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";
 export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
 export type { PprReplayBypassReason, PprReplayStatus, ShellCachePartition, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
+export { setBuildVersions } from "./build-versions.js";
+export type { BuildVersions, RouterVersions } from "./build-versions.js";
 export { collectHandle } from "./collect-handle.js";
 export { withLocationStateKey } from "./location-state-key.js";
 export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";

package/dist/types/testing/internal/seed-vars.d.ts

@@ -7,6 +7,7 @@
  * client/browser modules).
  */
 import { type ContextVar } from "../../context-var.js";
+import { type RouterVersions } from "../../router-versions.js";
 export interface StateCookieSeed {
     /**
      * Cookie-name prefix, sanitized then composed with `routerId` exactly like
@@ -20,11 +21,15 @@ export interface StateCookieSeed {
      */
     routerId?: string;
     /**
-     * Build version used as the rotated value's prefix (`{version}:{timestamp}`).
-     * Defaults to `"0"` (resolved inside createRequestContext).
+     * The app's version, as `createRouter({ version })` would set it: the
+     * rotated value's prefix (`{version}:{timestamp}`) and the version a cache
+     * store keys with. Defaults to `"0"` for the prefix (resolved inside
+     * createRequestContext) and to the build versions for the store.
      */
     version?: string;
 }
 export declare function resolveSeededStateCookieName(seed?: StateCookieSeed): string;
+/** The request context's `versions` for a seeded `stateCookie.version`. */
+export declare function seededVersions(seed?: StateCookieSeed): RouterVersions | undefined;
 export type VarsInit = Record<string, unknown> | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
 export declare function seedVariables(variables: Record<string, unknown>, vars?: VarsInit): Record<string, unknown>;

package/dist/types/testing/location-state-key.d.ts

@@ -6,11 +6,15 @@ import { type LocationStateDefinition } from "../browser/react/location-state-sh
  * use (`MyState(value)`, `useLocationState(MyState)`, `.read()`).
  *
  * - `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState`
- *   (a name that already starts with `__rsc_ls_` is used as-is).
+ *   (a name that already starts with `__rsc_ls_` is used as-is). A definition
+ *   with `clearOnReload` appends its suffix, so read the stored key back from
+ *   `GridState.__rsc_ls_key` (`__rsc_ls_GridState~r`).
  * - Without a name, a key already set (by the plugin or an earlier call) is
  *   kept; otherwise the definition gets a synthetic `__rsc_ls_test_<n>` key,
  *   which then stays on it.
  *
+ * A name may not contain "~": that separator is reserved for the suffix.
+ *
  * Returns the definition.
  *
  * @example

package/dist/types/testing/render-route.d.ts

@@ -35,11 +35,19 @@
  *     useRouter().replace kind "replace", refresh() kind "revalidate".
  *     Back/forward, action and optimistic clientUrls() swap decisions are
  *     e2e territory.
+ *   - Location state reaches readers the way it does in production:
+ *     NavigationProvider holds the committed entry's state next to the
+ *     payload, so a navigation whose loader the test holds keeps the entry
+ *     being left on screen with its own state. A `popstate` event is a
+ *     back/forward onto the entry history.state holds; the tree has one
+ *     location, so no page is restored with it. A server action's state, a
+ *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
  * descendant pending state, useLoader/useFetchLoader (seeded data),
- * useLocationState (seeded), and useHandle (seeded).
+ * useLocationState (seeded, or written by a navigation), and useHandle
+ * (seeded).
  * Basename-mounted apps: pass the `basename` option so useRouter().basename,
  * <Link> prefixing, and useMount/useHref resolve against the mount prefix
  * (without it they resolve at the root "/"). For an include("/shop", ...)
@@ -48,10 +56,10 @@
  */
 import { type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
-import type { NavigationStore } from "../browser/types.js";
+import type { NavigateOptions, NavigationStore } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { LoaderDefinition, TransitionConfig } from "../types.js";
-import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import { type LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
@@ -159,6 +167,8 @@ export interface RenderRouteOptions {
      * `useLocationState(StateDef)`. Like loaders, a real `createLocationState()`
      * handle has an empty injected key in a bare test, so pass `[def, value]`
      * pairs; renderRoute assigns a synthetic key and writes it to `history.state`.
+     * With `hydrate: true` a `clearOnReload` definition's seed is removed before
+     * hydration, as on a document load.
      *
      * @example
      * renderRoute([{ path: "/", Component: FlashBanner }], {
@@ -192,6 +202,24 @@ export interface RenderRouteOptions {
      * computes the segment id for you). Merged with `handles`.
      */
     handle?: HandleDataSeed;
+    /**
+     * Handle values a document delivers after hydration, as a loader's push
+     * that is not in the document's handle snapshot is (a push made after the
+     * handler output settled, or any loader push on a PPR shell HIT). Each
+     * entry is `[handle, values]`: the handle's values after the update, which
+     * replace its `handles` seed once the root has hydrated (or mounted). With
+     * `hydrate: true` the server HTML is rendered from `handles`, and a reader
+     * inside a `<Suspense>` boundary hydrates after the update was applied, as
+     * a boundary that hydrates after the root does in production.
+     *
+     * @example
+     * const { serverHtml, recoverableErrors } = await renderRoute(routes, {
+     *   hydrate: true,
+     *   handles: [[Notes, ["from-handler"]]],
+     *   lateHandles: [[Notes, ["from-handler", "from-loader"]]],
+     * });
+     */
+    lateHandles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
     /**
      * Route name -> pattern map. Informational for parity with the server test
      * context; client useReverse takes its map directly as an argument, so this
@@ -253,6 +281,25 @@ export interface RenderRouteOptions {
      * not override a `"none"` default.
      */
     defaultPrefetch?: PrefetchStrategy;
+    /**
+     * Hydrate instead of mounting fresh: the same element is rendered to HTML
+     * (react-dom/server `renderToString`), placed in the container and hydrated.
+     * The result gains `serverHtml` and `recoverableErrors`
+     * (RenderRouteHydrateResult). `data-hydrated` is set on `<html>` after
+     * hydration, as production's root does, and removed on unmount.
+     *
+     * Limits:
+     * - The server pass runs without `window` and `document`, and only those. A
+     *   hook that reads a global that stays defined there (`history`,
+     *   `localStorage`, `navigator`) outside a server snapshot renders the same
+     *   in both passes here and can still mismatch in real SSR.
+     * - Content that suspends in the server pass (`lazy`, a pending or untracked
+     *   `use()` promise) is emitted as its fallback and client-rendered, not
+     *   hydrated; React reports the boundary in `recoverableErrors`. Outside any
+     *   `<Suspense>` it rejects.
+     * - Needs @testing-library/react >= 16.2.0; throws on older versions.
+     */
+    hydrate?: boolean;
 }
 /**
  * Imperative handle returned alongside the RTL result.
@@ -282,10 +329,17 @@ export interface TestRouterHandle {
      * `options.transition: false` is the per-navigation opt-out
      * (`router.push(url, { transition: false })`, `<Link transition={false}>`):
      * the commit is urgent and no transition({ when }) predicate is called.
+     *
+     * `options.state` and `options.replace: true` write the history entry the
+     * way `useRouter().push(url, { state })` and `.replace(url, { state })` do,
+     * so a test can carry location state on a navigation whose loader it
+     * holds: `state` pushes an entry with it, `replace: true` replaces the
+     * current entry (with `state`, or with none, which drops the entry's
+     * location state as a production replace does). With neither, history is
+     * left alone and readers keep the state they have: `navigate(url)` and
+     * `navigate(url, { replace: false })` are the same call.
      */
-    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders"> & {
-        transition?: boolean;
-    }): Promise<void>;
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders"> & Pick<NavigateOptions, "state" | "replace" | "transition">): Promise<void>;
     /**
      * Re-render the current location, as router.refresh() does: a spec's
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
@@ -304,4 +358,21 @@ export interface TestRouterHandle {
 export type RenderRouteResult = RenderResult & {
     router: TestRouterHandle;
 };
+/** Result of renderRoute with `hydrate: true`. */
+export type RenderRouteHydrateResult = RenderRouteResult & {
+    /** The HTML the server pass produced, as placed in the container. */
+    serverHtml: string;
+    /**
+     * Messages of the errors React recovered from (`onRecoverableError`): a
+     * hydration mismatch that made it re-render on the client, or a boundary the
+     * server pass could not finish. Empty means the tree hydrated as rendered.
+     * Live: React appends for as long as the root is mounted. An attribute-only
+     * mismatch is NOT here — React keeps the server attribute and only logs it
+     * with `console.error` in development.
+     */
+    recoverableErrors: string[];
+};
+export declare function renderRoute(routes: RenderRouteSpec[], options: RenderRouteOptions & {
+    hydrate: true;
+}): Promise<RenderRouteHydrateResult>;
 export declare function renderRoute(routes: RenderRouteSpec[], options?: RenderRouteOptions): Promise<RenderRouteResult>;

package/dist/types/testing/serve-shell-request.d.ts

@@ -33,6 +33,7 @@
  */
 import { type Rango } from "../router/router-interfaces.js";
 import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import type { HandleData } from "../server/handle-store.js";
 import { type PprReplayStatus, type ShellStatus } from "./shell-status.js";
 /** Options for {@link serveShellRequest}. */
 export interface ServeShellRequestOptions<TEnv = any> {
@@ -60,6 +61,21 @@ export interface ServeShellRequestOptions<TEnv = any> {
         segments?: readonly string[];
     };
 }
+/** A response's handle data, as the browser consumes it. */
+export interface ShellRequestHandles {
+    /**
+     * What the document hydrates with: `metadata.handles`, read to its end
+     * before hydration starts. For a `partial` request, the last state the
+     * navigation streamed.
+     */
+    hydration: HandleData;
+    /**
+     * The states `metadata.handlesLate` delivered, in order. Each one replaces
+     * the client's handle data after hydration. Empty when nothing arrived
+     * late, and for a `partial` request.
+     */
+    late: HandleData[];
+}
 /** Result of {@link serveShellRequest}. */
 export interface ServeShellRequestResult {
     /** The handler's Response. Its body is already read: see `body`. */
@@ -96,6 +112,11 @@ export interface ServeShellRequestResult {
      * (CFCacheStore, VercelCacheStore) it warms the memo like any other read.
      */
     readEntry(): Promise<ShellCacheEntry | null>;
+    /**
+     * Decode the handle data of `flight` as the browser reads it, deferred
+     * values resolved. Undefined when no Flight was rendered.
+     */
+    readHandles(): Promise<ShellRequestHandles | undefined>;
 }
 /**
  * Reset the per-isolate PPR state requests leave behind, so the next test

package/dist/types/testing/vitest-stubs/version.d.ts

@@ -1 +1,2 @@
 export declare const VERSION = "";
+export declare const ROUTER_VERSIONS: undefined;

package/dist/types/types/handler-context.d.ts

@@ -342,11 +342,14 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      */
     _loaderCacheOriginalUse?: (item: any) => any;
     /**
-     * @internal A loader-cache HIT asks before replaying a loader's recorded
-     * pushes: true when that loader has not run in this request and no other
-     * replay delivered it; its later run then replaces the replayed values
-     * (HandleStore.pushReplayed). One copy per loader per request. See
-     * setupLoaderAccess.
+     * @internal A loader-cache or "use cache" HIT asks before replaying a
+     * loader's recorded pushes: true when that loader has not run in this
+     * request and no other replay delivered it; its later run then replaces
+     * the replayed values (HandleStore.pushReplayed). One copy per loader per
+     * request. A record's restore does not ask (restoreHandles): its copies
+     * are the pinned loader's own, or placeholders the claimed replay
+     * replaces. Absent on a stale refresh's ctx, whose pushes are diverted
+     * (handle-snapshot.ts appendHandles). See setupLoaderAccess.
      */
     _claimLoaderPushes?: (loaderId: string) => boolean;
     /**