@rangojs/router 0.24.3 → 0.25.0

package/dist/types/segment-system.d.ts

@@ -1,6 +1,21 @@
 import { type ReactNode, type ComponentType } from "react";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 export declare function restoreParallelLoaderMarkers(segments: ResolvedSegment[]): ResolvedSegment[];
+/**
+ * An intercept's loaders arrive as loader segments of its slot
+ * (`${slot.id}D${i}.${$$id}`, router/intercept-resolution.ts). Folded back
+ * onto the slot before the tree walk, as one aggregate the slot's
+ * LoaderBoundary reads (client.tsx renderSlotContent): walked as loaders they
+ * would attach to the slot's parent, whose subtree (the page under the modal)
+ * would change shape and remount. Any other loader segment passes through; a
+ * list with nothing to fold is returned as it is, synchronously.
+ * The slot is a new object (rule 6, suspense-contract.md); its aggregate is
+ * memoized on the loaders' data (rule 1). Settled before the commit when
+ * nothing in it is deferred and the slot has no loading() or the lane settles
+ * loaders (forceAwait, action): a modal with no loading() commits whole, as
+ * when the server awaited its loaders.
+ */
+export declare function foldInterceptLoaders(segments: ResolvedSegment[], settleLoaders: boolean): ResolvedSegment[] | Promise<ResolvedSegment[]>;
 /**
  * Options for renderSegments
  */

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

@@ -61,6 +61,12 @@ export type EntryPropCommon = {
     cache?: EntryCacheConfig;
     /** URL prefix from include() scope, used for MountContext on client */
     mountPath?: string;
+    /**
+     * Include scope the entry's handler and loaders resolve `ctx.reverse(".name")`
+     * in. Structural entries only (layout, cache, parallel, wrapping
+     * middleware); a route resolves from its own name. See ReverseScope.
+     */
+    reverseScope?: ReverseScope;
     /** clientUrls() group key (PathOptions.clientGroup); route entries only. */
     clientGroup?: string;
 };
@@ -129,6 +135,13 @@ export type LoaderEntry = {
      * (router/segment-resolution/prefetch-deferral.ts).
      */
     prefetch?: false;
+    /**
+     * The declaring layout's / parallel's / cache()'s include scope, for the
+     * loader body's `ctx.reverse(".name")` (its DSL kickoff carries it,
+     * runInsideLoaderScope). Unset on a route's loaders: they resolve from the
+     * route's name.
+     */
+    reverseScope?: ReverseScope;
 };
 /**
  * Segments state for intercept context
@@ -192,7 +205,6 @@ export type InterceptEntry = {
     slotName: `@${string}`;
     routeName: string;
     handler: ReactNode | Handler<any, any, any>;
-    middleware: MiddlewareFn<any, any>[];
     loader: LoaderEntry[];
     loading?: ReactNode | false;
     transition?: TransitionConfig;
@@ -267,10 +279,21 @@ export type EntryData = ({
     /** Cache entries create cache boundaries and render like layouts (with Outlet) */
     handler: ReactNode | Handler<any, any, any>;
 } & EntryPropCommon & EntryPropDatas & EntryPropSegments & EntryPropRender);
+/**
+ * Where an include()'s handler runs in the route tree. Hidden include-scope
+ * names (`$prefix_*`) derive from it, never from counter state, so build
+ * discovery and runtime expansion name every include the same (#1104).
+ */
+export interface IncludeScopePosition {
+    /** Sibling indexes of the enclosing includes, "_"-joined ("" at a mount root). */
+    scopePath?: string;
+    /** The scopePath tail since the nearest include that added a name segment. */
+    hiddenScopePath?: string;
+}
 /**
  * Tracked include info for build-time manifest generation
  */
-export interface TrackedInclude {
+export interface TrackedInclude extends IncludeScopePosition {
     prefix: string;
     fullPrefix: string;
     namePrefix?: string;
@@ -290,7 +313,7 @@ export type CachedHeaderScope = {
 /**
  * Context stored in AsyncLocalStorage
  */
-interface HelperContext {
+interface HelperContext extends IncludeScopePosition {
     manifest: Map<string, EntryData>;
     namespace: string;
     parent: EntryData | null;
@@ -399,6 +422,37 @@ export declare function getNamePrefix(): string | undefined;
  * Returns true at root or inside { name: "" } includes, false inside named includes.
  */
 export declare function getRootScoped(): boolean;
+/**
+ * The include scope a segment's dot-local `ctx.reverse(".name")` resolves in.
+ *
+ * One handler ctx serves every segment of a request and is built from the
+ * matched route's name (match-api.ts), so a parent module's layout resolved
+ * `.settings` from the matched CHILD module's prefix first: on
+ * `/acme/web/issues` the account layout's `.settings` hit the project
+ * module's route. Structural entries (layout, cache, parallel, wrapping
+ * middleware) and the loaders they declare capture the scope where the DSL
+ * defined them. Their handler gets a ctx whose `reverse` carries it
+ * (withReverseScope, router/handler-context.ts), and their loaders' DSL
+ * kickoff carries it in the loader scope (runInsideLoaderScope) for the
+ * loader ctx the executor builds. Global names and mount-param autofill do
+ * not change.
+ */
+export interface ReverseScope {
+    /** Include name prefix ("account.project"); undefined outside named includes. */
+    readonly prefix: string | undefined;
+    /** getRootScoped() where the segment was defined: bare-name fallback allowed. */
+    readonly rootScoped: boolean;
+}
+/** The ReverseScope of the DSL position being evaluated. */
+export declare function getReverseScope(): ReverseScope;
+/**
+ * A createReverseFunction result (router/handler-context.ts). The internal
+ * 4th argument resolves dot names in a segment's ReverseScope instead of the
+ * route's name.
+ */
+export type ScopableReverse = (name: string, hrefParams?: Record<string, string>, search?: Record<string, unknown>, segmentScope?: ReverseScope) => string;
+/** `reverse` with dot names resolved in `scope`, if any. */
+export declare function scopeReverse(reverse: ScopableReverse, scope: ReverseScope | undefined): ScopableReverse;
 /**
  * Stamp build-time scope identity onto a Static() definition at mount time.
  * The bake collector (prerender-collection.ts) renders defs OUTSIDE any
@@ -689,7 +743,13 @@ export declare function assertCachedHeaderWriteAllowed(surface: string, surfaceP
  * are bypassed because loaders are always fresh (never cached) and
  * their side effects (setCookie, header, etc.) are safe.
  */
-export declare function runInsideLoaderScope<T>(fn: () => T, loaderId?: string): T;
+export declare function runInsideLoaderScope<T>(fn: () => T, loaderId?: string, reverseScope?: ReverseScope): T;
+/**
+ * The ReverseScope of the DSL loader kickoff around this call: a loader the
+ * kickoff starts, and one its body starts with ctx.use(), resolve dot names
+ * in it. A handler's ctx.use(Loader) runs outside any kickoff: none.
+ */
+export declare function getLoaderReverseScope(): ReverseScope | undefined;
 /**
  * The loader whose run a handle push here belongs to, for the browser's
  * merge of a partial response (handles/pushed-by.ts): the DSL loader

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

@@ -13,7 +13,7 @@ import { parseCookiesFromHeader } from "./cookie-parse.js";
 import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
 import type { LoaderDefinition } from "../types.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { AutofillAwareReverseFunction } from "../types/handler-context.js";
 import type { DefaultEnv, DefaultReverseRouteMap, DefaultRouteName } from "../types/global-namespace.js";
 import type { Handle } from "../handle.js";
 import { type ContextVar } from "../context-var.js";
@@ -28,6 +28,8 @@ import type { ResolvedTracing } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RoutineTrace } from "../rsc/routine-plan.js";
+import type { ActionContinuation } from "../rsc/server-action.js";
+import type { FormActionOutcome } from "../rsc/progressive-enhancement.js";
 import { type ExecutionStart } from "../cache/invalidation-order.js";
 export interface RenderForegroundCursor {
     mode: RenderMode;
@@ -243,6 +245,12 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * locally and passes it to scheduleShellCapture directly.
      */
     _shellCaptureRun?: boolean;
+    /**
+     * @internal Set beside `_shellCaptureRun` when the shell is keyed by the
+     * visitor's URL (`rewrite(...).shell("visitor")`): the capture renders the
+     * visitor's location and `ctx.rewrittenFrom`; the theme stays the default.
+     */
+    _shellCaptureForVisitor?: boolean;
     /**
      * @internal Bake-lane loader containers collected DURING a shell capture:
      * segment-key -> the loader's (pre-wrap) result promise. Populated by
@@ -635,12 +643,25 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * Generate URLs from route names.
      * Uses the global route map. After route matching, scoped (`.name`) resolution
      * works within the matched include() scope.
-     */
-    reverse: ScopedReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
+     *
+     * Params are optional in the type because the fill depends on the phase.
+     * After the route match (route middleware, handlers, loaders, server actions)
+     * missing params come from the matched route's params; explicit params win.
+     * In global middleware before `next()` nothing is matched and the fill is
+     * empty, so a route with a required param throws `Missing param "<name>" for
+     * route "<route>"` at runtime (a param-less route still resolves).
+     */
+    reverse: AutofillAwareReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
     /** @internal Route name from route matching, used for scoped reverse resolution */
     _routeName?: string;
     /** @internal Previous route key (from the navigation source), used for revalidation */
     _prevRouteKey?: string;
+    /**
+     * @internal Leaving a rewritten page, the visitor's URL moved
+     * (router/match-api.ts): the default revalidation counts it as a search
+     * change, since the render may read `ctx.rewrittenFrom`.
+     */
+    _visitorMoved?: boolean;
     /**
      * @internal True while the post-action revalidation render is running (set by
      * revalidateAfterAction). The "use cache" runtime reads this to prefer
@@ -650,6 +671,22 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * revalidating in the background. A plain navigation (flag unset) keeps SWR.
      */
     _inActionRevalidation?: boolean;
+    /**
+     * @internal The outcome of the action this request ran (a JS server
+     * action's continuation, a no-JS form post's form state), set before route
+     * middleware wraps the re-render. While it is unset, applyRewrite
+     * (rsc/rewrite-passes.ts) moves a mutation with its body, so the action
+     * runs on the target's pass, or refuses it (`disallowMutations()`, or a
+     * body middleware read); once set, the request moves to the target, whose
+     * pass re-renders from it instead of running the action again (#1145).
+     */
+    _actionRan?: {
+        kind: "action";
+        continuation: ActionContinuation;
+    } | {
+        kind: "form";
+        outcome: FormActionOutcome;
+    };
     /**
      * @internal Render barrier for experimental `rendered()` API.
      * Resolves when all non-loader segments have settled and handle data
@@ -823,7 +860,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" | "_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" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_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">;
+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" | "_shellCaptureForVisitor" | "_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" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_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:

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

@@ -18,6 +18,18 @@
  * fill); the rest follow the rule so a new call site cannot drift into one.
  */
 export declare function requestHeaders(request: Request): Headers;
+/**
+ * A copy of `request`'s headers for a bodyless mirror of it (the PE
+ * re-render, route middleware around it, a rewrite pass after an action),
+ * without the body-framing ones and `content-type`, so a body check gated on
+ * the content-type passes over a request that has no body.
+ */
+export declare function bodylessHeaders(request: Request): Headers;
+/**
+ * A bodyless mirror of `request` at `url`: `method`, its
+ * {@link bodylessHeaders}, the signal and workerd's `cf`.
+ */
+export declare function bodylessRequest(url: string | URL, request: Request, method: string): Request;
 /**
  * Shadow `request.headers` with an own, non-enumerable getter that calls
  * `beforeRead` and returns the request's own Headers (stable per request, so

package/dist/types/server/rewrite-trail.d.ts

@@ -7,10 +7,13 @@
  * visitor's URL is its first entry (`ctx.rewrittenFrom`); the hops are its
  * length minus one.
  */
+import type { RewriteShell } from "../route-definition/rewrite.js";
 import type { RequestContext } from "./request-context.js";
 /** Most rewrites one request may take; the next one is a RewriteLoopError. */
 export declare const MAX_REWRITE_HOPS = 5;
 type TrailContext = Pick<RequestContext<any>, "_variables">;
+/** A URL's path and search: what a rewrite hop, a target and a visitor's move compare. */
+export declare function pathKey(url: URL): string;
 /** The trail of a rewritten request; undefined when nothing rewrote. */
 export declare function rewriteTrail(reqCtx: TrailContext | undefined): readonly string[] | undefined;
 /**
@@ -19,11 +22,15 @@ export declare function rewriteTrail(reqCtx: TrailContext | undefined): readonly
  * URL the request is on (pathname and search).
  */
 export declare function recordRewriteHop(reqCtx: TrailContext, from: URL, to: URL): number;
+export declare function recordRewriteShell(reqCtx: TrailContext, audience: RewriteShell | undefined): void;
+/** The last hop's `rewrite(...).shell()` choice; undefined: none. */
+export declare function rewriteShellAudience(reqCtx: TrailContext | undefined): RewriteShell | undefined;
 type AudienceContext = Pick<RequestContext<any>, "_shellCaptureRun" | "_documentCacheRender" | "res">;
 /**
  * A render other visitors may be served: a PPR shell capture, or a render
  * the document cache stores (its response opted in before next()). It shows
- * what a direct visit to its URL shows: no visitor theme, no visitor URL.
+ * no visitor theme, and no visitor URL unless it is a visitor-keyed shell
+ * capture (`_shellCaptureForVisitor`).
  */
 export declare function rendersForSharedAudience(reqCtx: AudienceContext): boolean;
 /**

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

@@ -4,7 +4,7 @@ import { blockPrefetch, unblockPrefetch, createPageHelpers, createStopwatch, get
 import { createParity, type ExpectParityOptions, type Parity, type ParityDescribeOptions, type ParityIntent } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, type CacheSink, type ExpectedCacheStatus, type CacheStatusTarget, } from "../cache-status.js";
-export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, type PprReplayBypassReason, type PprReplayStatus, type ShellCachePartition, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, visitorShellCacheKey, type PprReplayBypassReason, type PprReplayStatus, type ShellCachePartition, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
 export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, isPrefetchRequest, blockPrefetch, unblockPrefetch, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
 export type { Fixture, FixtureOptions, PageHelpers, Stopwatch, Parity, ParityIntent, ParityDescribeOptions, ExpectParityOptions, RangoMatchers, };
 export interface RangoE2E extends PageHelpers, Parity {

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

@@ -33,4 +33,4 @@ export type { TestableHandler, RenderHandlerOptions, RenderHandlerResult, StateC
 export { createActionForm } from "./action-form.js";
 export type { CreateActionFormOptions } from "./action-form.js";
 export { serveShellRequest, resetShellTestState, } from "./serve-shell-request.js";
-export type { ServeShellRequestAction, ServeShellRequestOptions, ServeShellRequestResult, ShellRequestHandles, } from "./serve-shell-request.js";
+export type { ServeShellRequestAction, ServeShellRequestOptions, ServeShellRequestResult, ShellRequestAction, ShellRequestHandles, } from "./serve-shell-request.js";

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

@@ -50,7 +50,7 @@ export type { PrerenderConfig, PrerenderResult, PrerenderWarmCaches, } from "../
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";
 export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
 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 { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, visitorShellCacheKey, } 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";

package/dist/types/testing/internal/client-urls-projection.d.ts

@@ -9,8 +9,9 @@
  *
  * A Vitest project runs no hoist plugin, so the source's revalidate()
  * predicates are plain functions. Each is registered under a key named for
- * its reference, route and loader, as the plugin's generated module registers
- * its own, and the projection carries the keys: materialization attaches them
- * and the server runs them, as in an app.
+ * its reference, route or intercept, and loader, as the plugin's generated
+ * module registers its own, and the projection carries the keys:
+ * materialization attaches them and the server runs them, as in an app. A
+ * boolean rides in the projection as itself, as the plugin leaves a literal.
  */
 export declare function installClientUrlsProjection(referenceId: string, source: Readonly<Record<string, unknown>>): void;

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

@@ -23,13 +23,16 @@
  *     SEEDED directly into client context (see the `loaders` / `locationState` /
  *     `handles` / `outletPending` options) — nothing is executed on the server.
  *     This exercises the context read path, not the run path.
- *   - navigate() does NOT drive the navigation lifecycle: useNavigation().state,
- *     useLinkStatus().pending, and useAction().state stay "idle". Assert
- *     pending/loading/submitting transition states with renderServerTree / e2e
- *     instead (navigate() warns once if used). The one pending state it does
- *     model is the held-navigation useLoader().isLoading: a `transition` spec
- *     plus a pending Promise seeded via navigate(url, { loaders }) commits
- *     through production's commitInTransition (browser/partial-update.ts).
+ *   - navigate() drives the navigation lifecycle as a click does:
+ *     useNavigation() reads loading from the call and idle with the commit,
+ *     and useLinkStatus().pending is true for a link to the destination until
+ *     the commit is handed to React. A `transition` spec plus a pending
+ *     Promise seeded via navigate(url, { loaders }) commits through
+ *     production's commitInTransition (browser/partial-update.ts), which React
+ *     holds: useNavigation() stays loading and the held reader's
+ *     useLoader().isLoading reads true until the data lands. Without
+ *     `transition` the commit is urgent (production's same-structure hold is
+ *     not modeled). useAction().state stays idle: no action runs.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
  *     useRouter().replace kind "replace", refresh() kind "revalidate".
@@ -324,9 +327,10 @@ export interface TestRouterHandle {
      * pending Promise suspends the read like a streaming Flight chunk. When a
      * spec in the chain has `transition`, the commit goes through production's
      * commitInTransition: the reader stays on screen with
-     * `useLoader().isLoading === true` until the promise settles. Settle it
-     * inside RTL's `act()` to flush the commit. Without `transition` the commit
-     * is urgent and the read suspends to the nearest Suspense boundary.
+     * `useLoader().isLoading === true`, and `useNavigation().state` reads
+     * "loading", until the promise settles. Settle it inside RTL's `act()` to
+     * flush the commit. Without `transition` the commit is urgent and the read
+     * suspends to the nearest Suspense boundary.
      *
      * @example
      * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
@@ -346,8 +350,14 @@ export interface TestRouterHandle {
      * 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.
+     *
+     * `options.handles` are the destination's handle pushes (`[handle,
+     * values]`, attached to its leaf route as in `renderRoute`'s own
+     * `handles`). They arrive on the response's handle stream, so `useHandle`
+     * readers take them with the page's commit: while React holds the page,
+     * readers keep the values of the page being left.
      */
-    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders"> & Pick<NavigateOptions, "state" | "replace" | "transition">): Promise<void>;
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & 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`).

package/dist/types/testing/run-loader.d.ts

@@ -100,6 +100,13 @@ export interface RunLoaderOptions<TEnv = any> {
     routeMap?: Record<string, string>;
     /** Matched route name for scoped `.name` reverse resolution. */
     routeName?: string;
+    /**
+     * Include name prefix of the module whose `layout()` / `parallel()` /
+     * `cache()` declares the loader (`"account"`, or `""` for the root module).
+     * `ctx.reverse(".name")` then resolves in that module, as such a loader's
+     * does in production, instead of from `routeName`.
+     */
+    declaredIn?: string;
     /** HTTP method surfaced as `ctx.method`. Defaults to "GET". */
     method?: string;
     /** Request body surfaced as `ctx.body`. */

package/dist/types/testing/run-middleware.d.ts

@@ -88,6 +88,13 @@ export interface RunMiddlewareRewrite {
     pathname: string;
     search: string;
     routeName?: string;
+    /**
+     * Present, `true`, only when the rewrite was thrown with
+     * `.disallowMutations()`: production refuses it for a non-GET, non-HEAD
+     * request in global middleware, before the action runs, instead of moving
+     * the mutation to the target.
+     */
+    mutationsDisallowed?: true;
 }
 /**
  * Result of runMiddleware.

package/dist/types/testing/run-revalidate.d.ts

@@ -66,9 +66,10 @@ export interface RunRevalidateOptions<TEnv = any> {
     context?: RevalidateArgs["context"];
 }
 /**
- * Run one revalidate() predicate, or a chain in declaration order, the way
- * the router does for a request. Resolves to the final decision: true
- * re-runs the segment, false keeps the client's copy.
+ * Run one revalidate() argument, or a chain in declaration order, the way
+ * the router does for a request: a predicate, or `true` / `false` as
+ * `revalidate()` takes them. Resolves to the final decision: true re-runs
+ * the segment, false keeps the client's copy.
  */
-export declare function runRevalidate<TEnv = any>(fn: ShouldRevalidateFn<any, TEnv> | readonly ShouldRevalidateFn<any, TEnv>[], opts?: RunRevalidateOptions<TEnv>): Promise<boolean>;
+export declare function runRevalidate<TEnv = any>(fn: ShouldRevalidateFn<any, TEnv> | boolean | readonly (ShouldRevalidateFn<any, TEnv> | boolean)[], opts?: RunRevalidateOptions<TEnv>): Promise<boolean>;
 export {};

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

@@ -70,13 +70,20 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * entries are deferred: `result.readDeferred()` lists them. `fill: true`
      * sends the request the browser follows an adopted prefetch with
      * (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
-     * ones, as `segments`, and the same URL as `from`.
+     * ones, as `segments`, and the same URL as `from`. `interceptSource` sends
+     * the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends
+     * from an open modal and with the fill of an intercept, whose `from` is
+     * that source. `rewriteTarget` sends the `metadata.rewriteTarget` the page at
+     * `from` carried when middleware rewrote it (`_rsc_rt`), as the browser
+     * does: the server then diffs against the route that rendered that page.
      */
     partial?: true | {
         from?: string;
+        rewriteTarget?: string;
         segments?: readonly string[];
         prefetch?: boolean;
         fill?: boolean;
+        interceptSource?: string;
     };
     /**
      * POST this form as a submit before hydration: the no-JS request the
@@ -109,6 +116,8 @@ export interface ServeShellRequestAction {
     args?: readonly unknown[];
     /** The segment ids the page holds (`_rsc_segments`). */
     segments?: readonly string[];
+    /** The page's payload `metadata.rewriteTarget`, as for `partial`. */
+    rewriteTarget?: string;
 }
 /** A response's handle data, as the browser consumes it. */
 export interface ShellRequestHandles {
@@ -125,6 +134,24 @@ export interface ShellRequestHandles {
      */
     late: HandleData[];
 }
+/**
+ * An `action` request's answer, as browser/server-action-bridge.ts reads it.
+ */
+export interface ShellRequestAction {
+    /** False when the action threw: the call rejects with `result`. */
+    ok: boolean;
+    /** What the call resolves (or rejects) with. */
+    result: unknown;
+    /**
+     * The error of the first loader that threw while it re-ran in the action's
+     * revalidation, the value `useAction(action).revalidationError` reports.
+     * That loader throws at its `useLoader` read, where the nearest boundary
+     * catches it, and the call still resolves. `null` when every loader
+     * answered (a `notFound()` or `redirect()` is not an error), or `ok` is
+     * false, as `useAction` reports it.
+     */
+    revalidationError: Error | null;
+}
 /** Result of {@link serveShellRequest}. */
 export interface ServeShellRequestResult {
     /** The handler's Response. Its body is already read: see `body`. */
@@ -150,9 +177,12 @@ export interface ServeShellRequestResult {
      * The shell key production resolved for this request: for a document the
      * serve path read and captured (a MISS or a HIT), the key it used, request
      * partition included (a route partitioned by `cache({ key })` or the
-     * store's `keyGenerator`). Otherwise (a route without `ppr`, a request
-     * passed to axis 1 before its key was resolved, a partial request) the
-     * document URL's key without a partition, as `shellCacheKey` builds it.
+     * store's `keyGenerator`), and for a request middleware rewrote with
+     * `rewrite(...).shell("visitor")` the visitor's key, as
+     * `visitorShellCacheKey` builds it. Otherwise (a route without `ppr`, a
+     * request passed to axis 1 before its key was resolved, a rewritten
+     * request whose rewrite chose no shell, a partial request) the document
+     * URL's key without a partition, as `shellCacheKey` builds it.
      */
     key: string;
     /**
@@ -185,6 +215,13 @@ export interface ServeShellRequestResult {
      * hydrates without it.
      */
     readPayloadFormState(): Promise<unknown>;
+    /**
+     * For an `action` request, the call's answer as the browser reads it: its
+     * result and the `revalidationError` its loaders' reruns report.
+     * Undefined when no Flight was rendered or the payload carries no action
+     * result.
+     */
+    readAction(): Promise<ShellRequestAction | undefined>;
 }
 /**
  * Reset the per-isolate PPR state requests leave behind, so the next test

package/dist/types/testing/shell-status.d.ts

@@ -95,6 +95,23 @@ export interface ShellCachePartition {
 export declare function shellCacheKey(router: {
     readonly id: string;
 }, url: URL | string, searchParams?: CacheSearchParams, partition?: string | readonly string[] | ShellCachePartition): string;
+/**
+ * Shell store key of a request middleware rewrote with
+ * `throw rewrite(...).shell("visitor")`: the visitor's `url`, partitioned by
+ * the rewrite's `target` (its path and search), as production builds it
+ * (`visitorShellKey`, `rsc/shell-capture-constants.ts`). `searchParams` is
+ * the target route's `cache.searchParams` config, applied to the visitor's
+ * search; `partition` is the target route's own, as for
+ * {@link shellCacheKey}, composed after the target's.
+ *
+ * ```ts
+ * const hit = await serveShellRequest(router, "/summer", { cacheStore });
+ * expect(hit.key).toBe(visitorShellCacheKey(router, "/summer", "/item/1"));
+ * ```
+ */
+export declare function visitorShellCacheKey(router: {
+    readonly id: string;
+}, url: URL | string, target: URL | string, searchParams?: CacheSearchParams, partition?: string | readonly string[] | ShellCachePartition): string;
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).

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

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

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

@@ -144,11 +144,20 @@ export interface RangoTestConfig {
  */
 export declare function rangoTestConfig(opts?: RangoTestAliasOptions): RangoTestConfig;
 /** A minimal Vite plugin shape (avoids a hard dependency on Vite's types). */
+/** The part of a Vite plugin context {@link rangoUseClientTransform} resolves with. */
+interface SourceResolveContext {
+    resolve(source: string, importer?: string, options?: {
+        skipSelf?: boolean;
+    }): Promise<{
+        id: string;
+        external?: boolean | string;
+    } | null>;
+}
 interface FlightTransformPlugin {
     name: string;
     resolveId: {
         order: "pre";
-        handler(source: string, importer: string | undefined): string | undefined;
+        handler(this: SourceResolveContext, source: string, importer: string | undefined): Promise<string | undefined>;
     };
     transform(code: string, id: string): Promise<{
         code: string;

package/dist/types/thenable-status.d.ts

@@ -13,9 +13,3 @@ export declare function unwrapsSynchronously(stream: Promise<unknown>): boolean;
  * listing a 0 ms promise on every reader that calls it.
  */
 export declare const SETTLED_THENABLE: Promise<undefined>;
-/**
- * The value React reads from `value` without suspending: `value` itself when
- * it is not a promise, a promise's `value` once it carries React's or Flight's
- * `status: "fulfilled"`. Undefined while it is pending or rejected.
- */
-export declare function settledValue<T>(value: T | Promise<T>): T | undefined;

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

@@ -53,7 +53,13 @@ type AutofillParamsFromEntry<TEntry> = TEntry extends string ? string extends TE
 type AutofillSearchFromEntry<TMap, TKey> = TKey extends keyof TMap ? TMap[TKey] extends {
     readonly search: infer S extends SearchSchema;
 } ? ResolveSearchSchema<S> : Record<string, unknown> : Record<string, unknown>;
-type AutofillAwareReverseFunction<TLocalRoutes, TGlobalRoutes> = ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
+/**
+ * `ScopedReverseFunction` whose global-name params are optional: the runtime
+ * fills missing ones from the matched route's params (`createReverseFunction`
+ * in `router/handler-context.ts`, explicit params win). Shared by handler,
+ * loader and request-context `reverse`.
+ */
+export type AutofillAwareReverseFunction<TLocalRoutes, TGlobalRoutes> = ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
     <TName extends keyof TGlobalRoutes & string>(name: TName, params?: AutofillParamsFromEntry<TGlobalRoutes[TName]>, search?: AutofillSearchFromEntry<TGlobalRoutes, TName>): string;
     <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params?: AutofillParamsFromEntry<TLocalRoutes[TName]>, search?: AutofillSearchFromEntry<TLocalRoutes, TName>): string;
 };
@@ -329,6 +335,11 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
     _responseType?: string;
     /** Route name for cache key scoping (prevents cross-route collisions). */
     _routeName?: string;
+    /**
+     * The segment's ReverseScope on a layout's / parallel's ctx and its
+     * loaders' (withReverseScope): keys a "use cache" call taking the ctx.
+     */
+    _reverseScope?: import("../server/context.js").ReverseScope;
     /**
      * @internal The on-demand overlay holds a "removed" marker for this request
      * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On