@rangojs/router 0.20.0 → 0.22.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>;
     /**
@@ -177,6 +218,8 @@ export interface HandleStore {
      * value are omitted; undefined when none has one.
      */
     getRecordOwners(segmentId: string): Record<string, (string | null)[]> | undefined;
+    /** The segment ids for which getRecordOwners returns an entry. */
+    getOwnedSegmentIds(): string[];
     /**
      * Replay cached handle data back into the store (for cache hits).
      * Used to restore handle data when serving cached segments.

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

@@ -19,7 +19,8 @@ import type { Handle } from "../handle.js";
 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 { SegmentCacheStore, ShellSnapshotHandlesValue } 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";
@@ -203,6 +204,25 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _pprReplayPostMatchReason?: "prerender-store" | "intercept";
     /** @internal Cache store for segment caching (optional, used by CacheScope) */
     _cacheStore?: SegmentCacheStore;
+    /**
+     * @internal Env-scoped writable prerender store (the durable overlay) plus the
+     * deployment identity for build-scoped keys, resolved per request from the
+     * `prerender` router option. Read by the serve-path overlay lookup before the
+     * bundled build manifest. Absent when no prerender store is configured.
+     */
+    _prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
+    /**
+     * @internal Set only on the requestless on-demand producer's context. When
+     * present, the standalone request-scoped READS — `cookies()`, `headers()`,
+     * `invalidateClientCache()`, `keepClientCache()` — throw a
+     * PrerenderPersonalizationError so a personalized render is skipped rather than
+     * baked into a shared payload. Response MUTATIONS on the producer context
+     * (`ctx.setStatus`/`header`/`setCookie`) stay silent no-op stubs, matching
+     * build-time prerender (the design's "throw or skip" contract permits skip):
+     * they write to a discarded synthetic response, so there is nothing to leak.
+     * Never set on the live request path.
+     */
+    _onDemandProducer?: true;
     /**
      * @internal Compiled `cache.searchParams` filter for default cache-key
      * generation (undefined = "all", the byte-stable unfiltered format). Set
@@ -271,6 +291,20 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * cache miss.
      */
     _shellForcedMiss?: true;
+    /**
+     * @internal This request is a router.prerender() warm
+     * (prerender/warm-request.ts). In `replace` mode every runtime cache read
+     * misses (isWarmReplace); the layers report into the record. A capture's
+     * derived context inherits it through the prototype.
+     */
+    _prerenderWarm?: import("../prerender/warm-request.js").PrerenderWarmRecord;
+    /**
+     * @internal Runs a callback in the async context this request entered the
+     * handler with (captureRequestEntryContext). router.prerender() dispatches
+     * a warm through it when called from inside a request. Absent where the
+     * runtime has no AsyncLocalStorage.snapshot.
+     */
+    _runAtRequestEntry?: <T>(fn: () => T) => T;
     /**
      * @internal The freshness window of the route cache() records this
      * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
@@ -283,7 +317,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 +325,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 +384,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;
         /**
@@ -360,6 +394,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
          * host) and miss the record.
          */
         fixedDocKey?: string;
+        /** @internal The snapshot's `handles` record (ShellSnapshotHandlesValue). */
+        prerenderHandles?: ShellSnapshotHandlesValue;
         /**
          * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
          * serve path. Its presence arms the explicit-scope composition in
@@ -671,6 +707,17 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * deriveShellCaptureContext gives the capture its own.
      */
     _renderErrors?: unknown[];
+    /**
+     * @internal Rejections of streamed (loading()) handlers that were recovered
+     * into a declared errorBoundary()/notFoundBoundary() fallback, by segment id.
+     * The recovered promise resolves, so Flight reports nothing; cacheRoute
+     * (cache-scope.ts) refuses a write only when one of ITS segments is listed,
+     * the granularity a Flight error row has. The same errors are also pushed to
+     * `_renderErrors` for the document cache and PPR shell capture. A render
+     * under a derived context (shell capture, SWR re-render) owns its own map.
+     * Allocated on the first recovery.
+     */
+    _recoveredHandlerErrors?: Map<string, unknown>;
     /**
      * @internal Report a non-fatal background error through the router's
      * onError callback. Wired by the RSC handler / router during request
@@ -708,6 +755,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 +803,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" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_locationState" | "_routeName" | "_prevRouteKey" | "_inActionRevalidation" | "_reportedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_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:
@@ -757,6 +812,15 @@ export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, str
  * @internal
  */
 export declare const UNTRACKED_BACKGROUND_TASK: unique symbol;
+/**
+ * Capture the current async context (RequestContext._runAtRequestEntry), taken
+ * on handler entry before any router scope, so a nested dispatch (a
+ * router.prerender() warm called from a handler, loader or action) does not
+ * inherit the caller's route-definition, loader and cache-scope state. Per
+ * request: workerd refuses a snapshot outside the request that created it.
+ * See docs/design/prerender-every-route.md.
+ */
+export declare function captureRequestEntryContext(): (<T>(fn: () => T) => T) | undefined;
 /**
  * Run a function within a request context
  * Used by the RSC handler to provide context to server actions
@@ -804,6 +868,12 @@ export interface CreateRequestContextOptions<TEnv> {
     initialResponse?: Response;
     /** Optional cache store for segment caching (used by CacheScope) */
     cacheStore?: SegmentCacheStore;
+    /**
+     * Optional env-scoped writable prerender store + deployment identity (the
+     * durable overlay), resolved per request by the RSC handler from the
+     * `prerender` router option.
+     */
+    prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
     /**
      * Compiled `cache.searchParams` filter from the resolved handler cache
      * config (handler.ts). Stored as _searchParamsFilter.
@@ -824,8 +894,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/suspense-audit-react.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import { type BoundaryAudit } from "./suspense-audit.js";
+/**
+ * One boundary: what each render hands it, what each commit carries, and its
+ * mount. Called above the Suspense, which commits while the content waits.
+ * `streams` and `nodes` are what else its content waits for (I3 only).
+ */
+export declare function useBoundaryAudit(boundary: string, segmentId: string, value: unknown, streams?: Record<string, unknown>, nodes?: unknown): BoundaryAudit;
+/** The boundary's content is on screen. */
+export declare function useRevealAudit(rec: BoundaryAudit): void;
+/**
+ * One `useLoader` read of a per-loader stream (I1, I2 at the read site). A
+ * read that suspends while mounting keeps no record: only a reader on screen
+ * is audited.
+ */
+export declare function useReadAudit(loaderId: string, stream: unknown): void;
+/** Wraps a boundary's fallback: mounted means the fallback is on screen. */
+export declare function AuditedFallback({ audit, children, }: {
+    audit: BoundaryAudit;
+    children: ReactNode;
+}): ReactNode;
+/** Wraps a segment's outlet children: the segment's mount (I4). */
+export declare function AuditedOutlet({ segmentId, children, }: {
+    segmentId: string;
+    children: ReactNode;
+}): ReactNode;

package/dist/types/suspense-audit.d.ts

@@ -0,0 +1,157 @@
+export type SuspenseAuditKind = "swap" | "untracked" | "idle-fallback" | "resuspended" | "remount" | "drift" | "uncaused" | "mutated";
+/** What may hand React a tree (I6). */
+export type TreeUpdateCause = "navigation" | "popstate" | "stale-revalidation" | "action" | "error" | "hmr";
+export interface SuspenseAuditEvent {
+    /** I1 swap, I2 untracked, I3 idle-fallback and resuspended, I4 remount, I5 drift, I6 uncaused, I7 mutated. */
+    kind: SuspenseAuditKind;
+    /** `content:<segment id>`, `loaders:<outlet key>`, `outlet:<segment id>`, `read:<loader id>`, `segment:<segment id>`. */
+    boundary: string;
+    detail: string;
+    url: string;
+    at: number;
+}
+export interface SuspenseAuditReport {
+    swaps: number;
+    untracked: number;
+    idleFallbacks: number;
+    resuspended: number;
+    remounts: number;
+    drifts: number;
+    uncaused: number;
+    mutations: number;
+    /**
+     * Not a violation: fallbacks the router cannot attribute. Nothing it handed
+     * the boundary was a promise React read, so the content's own suspension
+     * put the fallback up: an app's use(), a React.lazy, a client reference.
+     */
+    unattributedFallbacks: number;
+    /** Not a violation: tree updates React was handed, by cause ("none" without one). */
+    treeUpdates: Record<string, number>;
+    /**
+     * Not a violation: the distinct thenables each boundary or read was handed.
+     * One per value it waited for; two for one navigation is a gate replaced
+     * by the real promise.
+     */
+    readonly handed: Record<string, number>;
+    /**
+     * Not a violation: fallbacks shown over content on screen while what the
+     * boundary waits for was pending. An urgent commit does that by design.
+     */
+    shownWhilePending: number;
+    /** Mounts per boundary since the document loaded. */
+    readonly mounts: Record<string, number>;
+    /** The last events, oldest first. */
+    events: SuspenseAuditEvent[];
+    reset(): void;
+}
+/** One boundary, or one `useLoader` read. Lives as long as its fiber. */
+export interface BoundaryAudit {
+    boundary: string;
+    /** Segment id, for the place in the tree. */
+    segmentId: string;
+    /** The React key the segment was mounted under (I4 identity). */
+    key: string;
+    /** 0 until the boundary is on screen. */
+    mountId: number;
+    /** Last value a render ran with, and the URL it ran under. */
+    seen: unknown;
+    hasSeen: boolean;
+    seenUrl: string;
+    /** Last value a commit carried. */
+    committed: unknown;
+    hasCommitted: boolean;
+    /** What else the boundary's content waits for: per-loader streams, nodes. */
+    streams: Record<string, unknown> | undefined;
+    nodes: unknown;
+    /** The content has been on screen. */
+    revealed: boolean;
+    /** The fallback's effect was cleaned up in this task (auditFallback). */
+    fallbackGone: boolean;
+}
+export declare function createBoundaryAudit(boundary: string, segmentId: string): BoundaryAudit;
+/**
+ * Render phase: the value this render hands the boundary.
+ *
+ * I1: a boundary on screen was handed a thenable that is still pending, and
+ * is handed another one that is not already settled, for the same URL. React
+ * starts waiting again. A settled replacement is read at once, and another
+ * URL is another navigation: both are exempt.
+ * I2: a boundary whose content has been on screen is handed a native promise
+ * React has not read, and React finds it settled when it reads it. A render
+ * that cannot wait suspends on it and commits the fallback over the content,
+ * which React keeps up for 300 ms. Judged from the status React leaves on
+ * the promise when it reads it in the same task.
+ */
+export declare function auditHandover(rec: BoundaryAudit, value: unknown): void;
+/** Commit phase: what the boundary on screen now reads. */
+export declare function auditCommit(rec: BoundaryAudit, value: unknown, streams?: Record<string, unknown>, nodes?: unknown): void;
+export declare function auditReveal(rec: BoundaryAudit): void;
+/** One `useLoader` read on screen: it has a mount and reveals with it. */
+export declare function auditRead(rec: BoundaryAudit, stream: unknown): void;
+/**
+ * How the audit learns that a payload is still streaming: the event
+ * controller, set at boot (browser/rsc-router.tsx). Not read from
+ * NavigationStoreContext in AuditedFallback: see the header.
+ */
+export declare function setSuspenseAuditStreamProbe(probe: () => boolean): void;
+/**
+ * I3: the boundary's fallback is on screen with nothing to wait for: nothing
+ * the router handed the boundary is pending, no payload is streaming and no
+ * client reference is loading. `idle-fallback` on a boundary new to the page,
+ * `resuspended` when the fallback replaced content that had been on screen.
+ *
+ * Reported only when the router owns the fallback: React suspended on a
+ * promise the router handed unread that was already settled (`needless`).
+ * Any other fallback is the content's own (an app's use(), a React.lazy, a
+ * client reference) and is counted as `unattributedFallbacks`, not reported,
+ * also when the boundary holds a promise React has read.
+ *
+ * A fallback over content on screen while something is pending is counted
+ * (`shownWhilePending`) and not reported: an urgent commit does that by
+ * design (transition({ when }) gated off, #995), and so does dev while a
+ * client reference loads.
+ */
+export declare function auditFallback(rec: BoundaryAudit): () => void;
+/** One renderSegments call, collected while it builds. */
+export interface TreeAudit {
+    /** Segment ids, leaf first while building, root first once finished. */
+    order: string[];
+    keys: Map<string, string>;
+    types: Map<string, string>;
+    chains: Map<string, string[]>;
+    /** Segments this tree remounts by the documented rules. */
+    replaced: Set<string>;
+    /** The segment objects the tree is built from (I7), until it is held. */
+    segments: object[];
+}
+export declare function startTreeAudit(): TreeAudit | undefined;
+/** The element renderSegments built for one segment, leaf first. */
+export declare function auditSegmentElement(tree: TreeAudit | undefined, id: string, type: string, key: string, element: unknown, outletTransition: boolean, slots: readonly string[], segments: readonly object[]): void;
+/**
+ * A finished tree. The first is the document's, which React holds from
+ * hydration; any later one is held when an emit hands its root to React
+ * (auditTreeUpdate).
+ */
+export declare function finishTreeAudit(tree: TreeAudit | undefined, root: unknown): void;
+/**
+ * I4: a boundary that stays on the page under the same React key is
+ * unmounted and mounted again. A different key is the documented remount.
+ */
+export declare function auditMount(rec: BoundaryAudit): void;
+export declare function auditUnmount(rec: BoundaryAudit): void;
+/**
+ * I6: the cause of the tree update the caller emits next, in the same task.
+ * It does not outlive the task: an emit after an await names its cause again,
+ * or a cause left behind would cover an emitter that names none.
+ */
+export declare function auditTreeCause(cause: TreeUpdateCause): void;
+/**
+ * I6: a tree update reached React (the store.onUpdate subscriber in
+ * browser/react/NavigationProvider.tsx), with the root it hands React. Only a
+ * navigation, a back/forward, its stale revalidation, an action, an error and
+ * HMR hand React a tree; anything else updates in place through a store its
+ * readers subscribe to, or through a pending promise read with use().
+ */
+export declare function auditTreeUpdate(root?: unknown): void;
+/** Forget every tree and mount seen so far. For tests of the audit itself. */
+export declare function forgetSuspenseAudit(): void;

package/dist/types/testing/action-form.d.ts

@@ -0,0 +1,34 @@
+/**
+ * createActionForm: the FormData a browser posts when a form is submitted
+ * before hydration (no JavaScript), for a server action.
+ *
+ * React's server render writes hidden fields on the form so the POST names its
+ * action and carries the bound state; decodeAction / decodeFormState read them
+ * back. A test cannot render those fields (react-dom/server does not load under
+ * the react-server condition), so this builds the same wire format and
+ * registers the action where the plugin-rsc stub's decodeAction resolves it,
+ * tagged as a server reference like a built "use server" export so the bound
+ * action keeps its `$$id` (onError's actionId, the action phase label).
+ * Post the result with `serveShellRequest(router, url, { form })`.
+ */
+/** Options for {@link createActionForm}. */
+export interface CreateActionFormOptions {
+    /**
+     * The action's reference id, `<module id>#<export name>`, as the build gives
+     * a "use server" export. Any unique string of that shape in a test.
+     */
+    id: string;
+    /**
+     * A `useActionState` form (default): the action runs as `(prevState, formData)`
+     * and the POST carries the state key. false: a plain `<form action={fn}>`
+     * ($ACTION_ID_), the action runs as `(formData)`.
+     */
+    useActionState?: boolean;
+    /** The form's own fields, as the person filled them. */
+    fields?: Record<string, string>;
+}
+/**
+ * Build a no-JS form POST body for `action` and register it so a handler
+ * decodes it back to `action`.
+ */
+export declare function createActionForm(action: (...args: any[]) => unknown, options: CreateActionFormOptions): FormData;

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";