@rangojs/router 0.24.4 → 0.25.0

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

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

@@ -2,7 +2,7 @@ import type { ContextVar } from "../context-var.js";
 import type { Handle } from "../handle.js";
 import type { HandlePush } from "../defer.js";
 import type { MiddlewareFn } from "../router/middleware.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { AutofillAwareReverseFunction } from "./handler-context.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
 import type { UseItems, LoaderUseItem } from "../route-types.js";
 import type { DefaultEnv, DefaultReverseRouteMap, DefaultVars } from "./global-namespace.js";
@@ -118,9 +118,10 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
     /**
      * Generate URLs from route names.
      * Same scoped reverse as route handlers — `.name` resolves within the
-     * current include() scope, `name` resolves globally.
+     * current include() scope, `name` resolves globally, and params the matched
+     * route already carries (e.g. include() mount params) are filled in.
      */
-    reverse: ScopedReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
+    reverse: AutofillAwareReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
 };
 /**
  * Loader function signature

package/dist/types/types/route-entry.d.ts

@@ -1,6 +1,7 @@
 import type { AllUseItems } from "../route-types.js";
+import type { IncludeScopePosition } from "../server/context.js";
 import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
-export interface LazyIncludeContext {
+export interface LazyIncludeContext extends IncludeScopePosition {
     urlPrefix: string;
     namePrefix: string | undefined;
     parent: unknown;

package/dist/types/urls/path-helper-types.d.ts

@@ -144,9 +144,11 @@ export type PathHelpers<TEnv> = {
         (fns: MiddlewareFn<TEnv>[], children: () => UseItems<LayoutUseItem>): MiddlewareItem;
     };
     /**
-     * Control when a segment should revalidate during navigation
+     * Control when a segment should revalidate during navigation.
+     * `revalidate(true)` / `revalidate(false)` are shorthand for
+     * `revalidate(() => true)` / `revalidate(() => false)`.
      */
-    revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+    revalidate: (fn: ShouldRevalidateFn<any, TEnv> | boolean) => RevalidateItem;
     /**
      * Attach a data loader to the current route/layout.
      *

package/dist/types/vite/discovery/client-urls-projection.d.ts

@@ -1,3 +1,4 @@
+import { type EnvironmentModuleNode } from "vite";
 import { type ClientUrlProjection } from "../../client-urls/server-projection.js";
 import type { DiscoveryState } from "./state.js";
 interface ClientUrlSsrEnvironment {
@@ -9,7 +10,40 @@ interface ClientUrlProjectionServerModule {
     clearClientUrlProjections(): void;
     setClientUrlProjection(referenceId: string, projection: ClientUrlProjection): void;
 }
+/** The RSC environment whose realm `ClientUrlProjectionServerModule` is. */
+interface ClientUrlRscEnvironment {
+    readonly runner: {
+        import(id: string): Promise<unknown>;
+    };
+    readonly moduleGraph?: {
+        getModuleById(id: string): EnvironmentModuleNode | undefined;
+        invalidateModule(mod: EnvironmentModuleNode): void;
+    };
+}
+export declare const CLIENT_URLS_REVALIDATE_QUERY = "rango-revalidate";
+/** The id of the module registering `file`'s hoisted revalidate() predicates. */
+export declare function hoistedRevalidateId(file: string): string;
 export declare function recordClientUrlsModule(state: DiscoveryState, code: string, id: string): void;
+/** A module that imports the router's client entry (a cheap pre-filter). */
+export declare const CLIENT_IMPORT_RE: RegExp;
+/**
+ * Whether an edited module can carry a clientUrls() component's own items: it
+ * imports "@rangojs/router/client" and assigns a `.use` in code (not in a
+ * comment or string). Such a module changes its groups' projections and
+ * hoisted revalidate() registrations like a group edit, with or without
+ * "use client".
+ */
+export declare function isClientUrlsComponentUseSource(source: string): boolean;
+/**
+ * A hash of the text of every `X.use = ...` assignment of a component-use
+ * module (isClientUrlsComponentUseSource), or undefined for any other module.
+ * Equal before and after a save, the edit (markup, hooks) left what its
+ * groups read unchanged: the dev watcher skips re-discovery and the client
+ * keeps Fast Refresh. An edit outside the assignments that changes what one
+ * means (a helper it calls, an import's source) is not seen. A module that
+ * does not parse hashes whole.
+ */
+export declare function componentUseSignature(source: string, file: string): string | undefined;
 export declare function resolveClientUrlsSource(state: DiscoveryState, referenceId: string): string | undefined;
 /**
  * Deterministic filesystem discovery of clientUrls modules. Transform-based
@@ -33,11 +67,13 @@ export declare function scanForClientUrlModules(state: DiscoveryState): void;
  * import, so `.routes(reference)` materialized the previous pass's projection.
  *
  * Errors are deliberately swallowed per source (a module mid-edit keeps its
- * last-known projection); the strict discoverClientUrlProjections() pass still
- * surfaces real failures afterwards. No-ops on cold start (nothing recorded
- * yet) and when the SSR runner is unavailable.
+ * last-known projection), and all refreshed projections keep their
+ * last-known state when any registration fails to load; the strict
+ * discoverClientUrlProjections() pass still surfaces real failures afterwards.
+ * No-ops on cold start (nothing recorded yet) and when the SSR runner is
+ * unavailable.
  */
-export declare function refreshRecordedClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+export declare function refreshRecordedClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule, rscEnv: ClientUrlRscEnvironment): Promise<void>;
 /**
  * Strict projection discovery over every RECORDED clientUrls module. Recorded
  * modules — not router references — are the source of truth: include() mounts
@@ -49,5 +85,19 @@ export declare function refreshRecordedClientUrlProjections(state: DiscoveryStat
  * (recordClientUrlsModule never un-records, so deletions must self-heal here).
  * A present-but-broken module is a hard error: it is part of the app graph.
  */
-export declare function discoverClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+export declare function discoverClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule, rscEnv: ClientUrlRscEnvironment): Promise<void>;
+/**
+ * Assign each group of `projections` the other files holding the predicates
+ * it reads (each key's file, as the hoist transform recorded it: a key with
+ * none stays unregistered, and materialization names it), after loading their
+ * registrations into `rscEnv`. The group's own registrations load with its
+ * proxy, and its `?rango-revalidate` module imports the assigned files'
+ * (plugins/client-urls-revalidate-hoist.ts). When a group's files change, that
+ * module is invalidated, so a later evaluation (a reload, a request realm)
+ * imports the current ones. Another realm (workerd, a production bundle)
+ * loads a group only after discovery: its entry imports the routes-manifest
+ * module first, whose load waits for discovery (RSC_ENTRY_BOOTSTRAP_IMPORTS),
+ * and a build discovers in buildStart.
+ */
+export declare function assignClientUrlRevalidateFiles(state: Pick<DiscoveryState, "clientUrlRevalidate" | "clientUrlSourceByReferenceId">, rscEnv: ClientUrlRscEnvironment, projections: ReadonlyMap<string, ClientUrlProjection>): Promise<void>;
 export {};