@rangojs/router 0.22.1 → 0.24.0

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

@@ -587,6 +587,26 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * document cache does not store that response (#978).
      */
     _payloadVisitorTheme?: boolean;
+    /**
+     * @internal Set by the partial render when its payload carries deferred
+     * units (`prefetch: false`): what one page's prefetch left for the fill.
+     * The document cache does not store that response, whatever Cache-Control
+     * it ends up with (docs/design/prefetch-false.md, R7).
+     */
+    _payloadDeferred?: boolean;
+    /**
+     * @internal What the request says it is: a `<Link>` prefetch or a fill
+     * (`prefetch: false`), read once at creation
+     * (segment-resolution/prefetch-deferral.ts requestKind).
+     */
+    _requestKind?: "prefetch" | "fill";
+    /**
+     * @internal Set when a render shows the visitor's URL of a rewritten
+     * request: the payload or SSR seed (renderedLocation, rsc/full-payload.ts)
+     * or a `ctx.rewrittenFrom` read (server/rewrite-trail.ts). The document
+     * cache does not store that response: it is keyed by the target.
+     */
+    _payloadVisitorLocation?: boolean;
     /**
      * Attach location state entries to the current response.
      *
@@ -803,7 +823,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" | "_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" | "_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">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
@@ -812,6 +832,13 @@ export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, str
  * @internal
  */
 export declare const UNTRACKED_BACKGROUND_TASK: unique symbol;
+/**
+ * Define `ctx.res` as an own accessor that reads `get`. Assigning it throws
+ * the read-only error. A context derived from another (Object.create) gets
+ * its own response this way; copying the descriptor would read the
+ * prototype's slot.
+ */
+export declare function bindRes(ctx: RequestContext<any, any>, get: () => Response): void;
 /**
  * Capture the current async context (RequestContext._runAtRequestEntry), taken
  * on handler entry before any router scope, so a nested dispatch (a
@@ -911,6 +938,26 @@ export interface CreateRequestContextOptions<TEnv> {
  * - Passed to handlers as ctx
  */
 export declare function createRequestContext<TEnv>(options: CreateRequestContextOptions<TEnv>): RequestContext<TEnv>;
+/**
+ * Move a request context to a rewrite target for the next pass of the
+ * request (rsc/rewrite-passes.ts, `throw rewrite()`). The context object
+ * stays the same, so what the visitor's pass set is still there: variables
+ * (the rewrite trail among them), the response stub (status, headers,
+ * cookies), location state, theme, `dynamic()`, metrics, request tags,
+ * onResponse callbacks, the handle store.
+ *
+ * Moved to the target: the request (`rawUrl`, the visitor's `_rsc*` params
+ * included), url, originalUrl, pathname, searchParams and the request kind.
+ * Cleared for the target's match: params, route name, reverse, the
+ * classified route, the request mode, and the document cache's render mark
+ * (its middleware runs again for the target). The loader memo behind
+ * `getRequestContext().use()` is new: a loader that middleware started in
+ * the visitor's pass read the visitor's URL. A pass never renders before it
+ * rewrites: router/middleware.ts refuses a rewrite thrown after a next()
+ * unless that next() rejected with a Rewrite (a downstream middleware
+ * rewrote before its own next()), so there is no render state to reset.
+ */
+export declare function rebaseRequestContext(ctx: RequestContext<any>, request: Request, rawUrl: URL): void;
 /**
  * Wire a fresh render barrier onto `ctx`, closure-bound to THIS ctx and THIS
  * handle store. Called by createRequestContext for every fresh context, and by
@@ -927,8 +974,11 @@ export declare function createRequestContext<TEnv>(options: CreateRequestContext
  * read the foreground's handle snapshot; the capture's fresh `_handleStore`
  * was invisible, so foreground per-request handle data could bake into the
  * shared shell.
+ *
+ * A derived context's `_renderBarrier` is non-enumerable (the default
+ * descriptor); a fresh context's is enumerable like its other fields.
  */
-export declare function wireRenderBarrier(ctx: RequestContext<any, any>, handleStore: HandleStore): void;
+export declare function wireRenderBarrier(ctx: RequestContext<any, any>, handleStore: HandleStore, descriptor?: PropertyDescriptor): void;
 export { parseCookiesFromHeader };
 export declare function serializeCookieValue(name: string, value: string, options?: CookieOptions): string;
 /**

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

@@ -0,0 +1,49 @@
+/**
+ * The URLs a rewritten request moved through (`throw rewrite()`), and what
+ * each context sees of them.
+ *
+ * One source: the trail lives in the request's variables under a token no
+ * user code can reach, so a middleware cannot reset the loop count. The
+ * visitor's URL is its first entry (`ctx.rewrittenFrom`); the hops are its
+ * length minus one.
+ */
+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">;
+/** The trail of a rewritten request; undefined when nothing rewrote. */
+export declare function rewriteTrail(reqCtx: TrailContext | undefined): readonly string[] | undefined;
+/**
+ * Count one hop from `from` to `to` (clean URLs) and return its number.
+ * Throws RewriteLoopError past {@link MAX_REWRITE_HOPS}, or when `to` is the
+ * URL the request is on (pathname and search).
+ */
+export declare function recordRewriteHop(reqCtx: TrailContext, from: URL, to: URL): number;
+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.
+ */
+export declare function rendersForSharedAudience(reqCtx: AudienceContext): boolean;
+/**
+ * The URL the visitor is on: the first URL of a rewritten request, else
+ * `url` with the internal `_rsc*` params stripped. A reload the router asks
+ * the browser for points here.
+ */
+export declare function visitorUrl(reqCtx: TrailContext | undefined, url: URL): URL;
+/**
+ * Who reads `rewrittenFrom`: "render" for the contexts a render reads
+ * (handler, loader, response route, getRequestContext()), "middleware" for a
+ * middleware ctx, which runs once per request and is never stored.
+ */
+export type RewrittenFromReader = "render" | "middleware";
+/**
+ * Define `ctx.rewrittenFrom` on a handler, loader, response-route or
+ * middleware ctx, read through `source` (the request context it belongs
+ * to). Each ctx gets its own copy of the URL.
+ */
+export declare function defineRewrittenFrom(ctx: object, source: RequestContext<any> | undefined, reader?: RewrittenFromReader): void;
+/** Define `rewrittenFrom` on a request context, read through itself. */
+export declare function defineRequestRewrittenFrom(ctx: RequestContext<any>): void;
+export {};

package/dist/types/server/slot-accessors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Property definitions for per-request objects that keep V8 fast properties
+ * (#1109): the request context, the middleware ctx, the handle store and a
+ * guarded request.
+ *
+ * V8 puts an object in dictionary mode, where every property read is a hash
+ * lookup for the object's whole lifetime, when an object literal declares a
+ * get/set member, when a data property is redefined as an accessor after
+ * creation, or when an accessor is defined with a function its shape
+ * transition has not recorded: a closure created per request is a new
+ * function every time. So an accessor on a per-request object is a
+ * module-level descriptor, and one that needs per-object state reads a
+ * per-object closure from a non-enumerable symbol slot (slotAccessor +
+ * defineSlot). A derived object (Object.create(obj)) reads the slot through
+ * its prototype; the descriptor copied onto another object reads that
+ * object's slot instead. context-fast-properties.test.ts pins all of it.
+ *
+ * Dependency-free leaf: handle-store.ts is imported by request-context.ts,
+ * so these cannot live in either.
+ */
+/**
+ * An accessor descriptor whose getter calls the receiver's `slot` closure.
+ * Call it once at module level and share the result.
+ */
+export declare function slotAccessor(slot: symbol, enumerable: boolean): PropertyDescriptor;
+/** Define `slot` on `target` as a non-enumerable, read-only data property. */
+export declare function defineSlot(target: object, slot: symbol, value: unknown): void;
+/** Define `key` on `target` as a non-enumerable, writable data property. */
+export declare function defineHidden(target: object, key: PropertyKey, value: unknown): void;

package/dist/types/server.d.ts

@@ -15,3 +15,4 @@ export { createRequestContext, type CreateRequestContextOptions, } from "./serve
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
 export { enableTransitionWhenValidation } from "./transition-when-ref.js";
 export { clearClientUrlProjections, setClientUrlProjection, type ClientUrlProjection, } from "./client-urls/server-projection.js";
+export { registerClientUrlRevalidators } from "./client-urls/revalidate-registry.js";

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 { ServeShellRequestOptions, ServeShellRequestResult, ShellRequestHandles, } from "./serve-shell-request.js";
+export type { ServeShellRequestAction, ServeShellRequestOptions, ServeShellRequestResult, ShellRequestHandles, } from "./serve-shell-request.js";

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

@@ -26,7 +26,7 @@
  *   condition and would throw if pulled into this barrel.
  *
  * Layers:
- * - Unit:        runMiddleware, runLoader, runClientRevalidate
+ * - Unit:        runMiddleware, runLoader, runRevalidate, runTransitionWhen
  * - Integration: dispatch (request -> Response)
  * - Cross-cut:   assertCacheStatus, assertShellStatus, assertGeneratedRoutesMatch
  * - Component:   see @rangojs/router/testing/dom (renderRoute)
@@ -34,13 +34,13 @@
  * - RSC:         see @rangojs/router/testing/flight
  */
 export { runMiddleware } from "./run-middleware.js";
-export type { RunMiddlewareOptions, RunMiddlewareResult, } from "./run-middleware.js";
+export type { RunMiddlewareOptions, RunMiddlewareResult, RunMiddlewareRewrite, } from "./run-middleware.js";
 export { runLoader, runLoaderResult } from "./run-loader.js";
 export type { RunLoaderOptions, RunLoaderResult, UseResolver, TestLoaderContext, } from "./run-loader.js";
 export { runTransitionWhen } from "./run-transition-when.js";
 export type { RunTransitionWhenAction, RunTransitionWhenLocation, RunTransitionWhenOptions, RunTransitionWhenResult, } from "./run-transition-when.js";
-export { runClientRevalidate } from "./run-client-revalidate.js";
-export type { RunClientRevalidateOptions } from "./run-client-revalidate.js";
+export { runRevalidate } from "./run-revalidate.js";
+export type { RunRevalidateAction, RunRevalidateOptions, } from "./run-revalidate.js";
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";
 export { createMemoryPrerenderStore } from "../prerender/memory-prerender-store.js";

package/dist/types/testing/internal/action-id.d.ts

@@ -1,7 +1,16 @@
+/** An imported server action, as a testing primitive's `action` option takes it. */
+export type ImportedAction = (...args: never[]) => unknown;
+/**
+ * Normalizes a testing primitive's `action` option: a bare imported action or
+ * actionId string becomes `{ ref }`; the object form passes through.
+ */
+export declare function normalizeTestAction<T extends {
+    ref?: ImportedAction | string;
+}>(action: ImportedAction | string | T | undefined): T | undefined;
 /**
  * The id a testing primitive's `action` option names: a single imported
  * server action (its `$id ?? $$id`, as the action boundary derives it) or a
  * raw actionId string. A function without either id throws, naming the
  * primitive.
  */
-export declare function resolveTestActionId(action: ((...args: never[]) => unknown) | string | undefined, primitive: string): string | undefined;
+export declare function resolveTestActionId(action: ImportedAction | string | undefined, primitive: string): string | undefined;

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

@@ -0,0 +1,16 @@
+/**
+ * Install the projection of a `"use client"` clientUrls() module under its
+ * client reference id, as discovery installs it for an app
+ * (discoverClientUrlProjections in vite/discovery/client-urls-projection.ts):
+ * the same projection step, into the same registry include() materializes
+ * from. rangoUseClientTransform (testing/vitest.ts) appends a call to every
+ * such module, passing the module's own source evaluated without the
+ * transform, so a router under test mounts the group with no setup.
+ *
+ * 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.
+ */
+export declare function installClientUrlsProjection(referenceId: string, source: Readonly<Record<string, unknown>>): void;

package/dist/types/testing/internal/test-action.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Register `action` under its reference id, `<module id>#<export name>`,
+ * tagged as a server reference like a built "use server" export so it keeps
+ * its `$$id`, where the plugin-rsc stub's decodeAction / loadServerAction
+ * resolve it. `primitive` names the caller in the error for a malformed id.
+ * Loads the react-server build: callers run under the react-server condition.
+ */
+export declare function registerTestAction(action: (...args: any[]) => unknown, id: string, primitive: string): void;

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

@@ -300,6 +300,14 @@ export interface RenderRouteOptions {
      * - Needs @testing-library/react >= 16.2.0; throws on older versions.
      */
     hydrate?: boolean;
+    /**
+     * The path middleware rewrote `request` to (`throw rewrite()`): the leaf
+     * route is matched against it for params, while the location stays
+     * `request`, as on a rewritten document. The server pass and hydration
+     * both see `request` (`usePathname()`, `useSearchParams()`), as production
+     * renders a rewritten page with the visitor's URL (`/middleware` skill).
+     */
+    rewrite?: string;
 }
 /**
  * Imperative handle returned alongside the RTL result.

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

@@ -20,8 +20,9 @@
  * - `ctx.reverse()` throws unless `routeMap` is provided (it does NOT fall back
  *   to the global route map — that would leak whichever routes another test
  *   registered).
- * - `ctx.use(handle)` follows the production rule: reading a handle before
+ * - `ctx.get(handle)` follows the production rule: reading a handle before
  *   `await ctx.rendered()` throws (pass `rendered` to mock the barrier).
+ *   `ctx.use(handle)` is the push and needs no barrier.
  * - `use cache` functions only cache (and only fire their taint/profile guards)
  *   when a `cacheStore` is provided — without one, registerCachedFunction
  *   bypasses (it checks for a store first). Pass `cacheStore`/`cacheProfiles`

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

@@ -13,6 +13,10 @@
  *
  * `nextCalled` counts how many times the terminal `next()` (the finalHandler)
  * ran: 0 when the chain short-circuited, 1 when it ran to completion.
+ *
+ * A `throw rewrite(target)` is reported as `result.rewrite` (the resolved
+ * target) instead of failing the run: production re-dispatches the request
+ * there, which this primitive does not do.
  */
 import { type RequestContext } from "../server/request-context.js";
 import type { MiddlewareFn } from "../router/middleware-types.js";
@@ -79,6 +83,12 @@ export interface RunMiddlewareOptions<TEnv = any> {
      */
     stateCookie?: StateCookieSeed;
 }
+/** A rewrite the chain threw (RunMiddlewareResult.rewrite). */
+export interface RunMiddlewareRewrite {
+    pathname: string;
+    search: string;
+    routeName?: string;
+}
 /**
  * Result of runMiddleware.
  */
@@ -94,6 +104,16 @@ export interface RunMiddlewareResult<TEnv = any> {
     ctx: RequestContext<TEnv>;
     /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
     nextCalled: number;
+    /**
+     * The target of a `throw rewrite(...)` from the chain, resolved as
+     * production resolves it (a path basename-prefixed, a route name through
+     * `routeMap`): `pathname` and `search` of the URL the request would render,
+     * and `routeName` when the rewrite named a route. `undefined` when the chain
+     * did not rewrite. On a rewrite, `response` carries what the chain set
+     * before the throw (status, headers, cookies), which production keeps for
+     * the target's response.
+     */
+    rewrite?: RunMiddlewareRewrite;
     /**
      * Whether the chain called `ctx.dynamic()` (the PPR shell opt-out). The public
      * way to assert the opt-out without reading the `@internal` `ctx._dynamic`.

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

@@ -0,0 +1,74 @@
+/**
+ * runRevalidate — unit-test revalidate() predicates: a urls() segment's, or a
+ * clientUrls() loader's (which the build moves to the server, where it runs
+ * the same way).
+ *
+ * Evaluates the predicate(s) through the router's own evaluateRevalidation
+ * (router/revalidation.ts) inside a seeded request context: the default
+ * decision, the argument object, boolean short-circuit, soft-verdict
+ * threading and the fail-open on a throw are the production code paths, not
+ * a re-implementation. Pass an array to test a chain in declaration order.
+ */
+import type { ShouldRevalidateFn } from "../types.js";
+import { type ImportedAction } from "./internal/action-id.js";
+import type { VarsInit } from "./internal/seed-vars.js";
+type RevalidateArgs = Parameters<ShouldRevalidateFn<any, any>>[0];
+/** The action fields a predicate receives on an action request. */
+export interface RunRevalidateAction {
+    /** The triggering action: an imported server action or its actionId. */
+    ref?: ImportedAction | string;
+    /** `actionResult`: the action's return value. */
+    result?: unknown;
+    /** `formData`: the action's FormData argument. */
+    formData?: FormData;
+    /** `actionUrl`. Defaults to `currentUrl`. */
+    url?: string | URL;
+}
+/**
+ * Options for {@link runRevalidate}. Defaults model a same-URL navigation
+ * with no action, for a route-owned loader segment.
+ */
+export interface RunRevalidateOptions<TEnv = any> {
+    /** The page being left. Defaults to `http://localhost/`. */
+    currentUrl?: string | URL;
+    /** The destination. Defaults to `currentUrl`. */
+    nextUrl?: string | URL;
+    currentParams?: Record<string, string>;
+    /** Defaults to `currentParams`. */
+    nextParams?: Record<string, string>;
+    /**
+     * The triggering action: an imported server action (id via
+     * `$id ?? $$id`), an actionId string, or `{ ref, result, formData, url }`.
+     * Makes the request a POST, as an action request is.
+     */
+    action?: ImportedAction | string | RunRevalidateAction;
+    /** Overrides the request method (`POST` with `action`, else `GET`). */
+    method?: string;
+    /** The segment the predicate is attached to. Defaults to `"loader"`. */
+    segmentType?: RevalidateArgs["segmentType"];
+    /**
+     * The segment belongs to the matched route (a route's own loaders, a
+     * clientUrls() group loader). Defaults to true; false models a layout's
+     * loader, which a navigation keeps by default.
+     */
+    belongsToRoute?: boolean;
+    /** `stale`: a history-entry background revalidation. */
+    stale?: boolean;
+    /** `toRouteName` (and `routeName`). */
+    routeName?: string;
+    /** `fromRouteName`. */
+    fromRouteName?: string;
+    /** Environment bindings of the seeded context. */
+    env?: TEnv;
+    /** Variables a middleware would have set, readable with `context.get()`. */
+    vars?: VarsInit;
+    /** `context`, in place of the seeded request context. */
+    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.
+ */
+export declare function runRevalidate<TEnv = any>(fn: ShouldRevalidateFn<any, TEnv> | readonly ShouldRevalidateFn<any, TEnv>[], opts?: RunRevalidateOptions<TEnv>): Promise<boolean>;
+export {};

package/dist/types/testing/run-transition-when.d.ts

@@ -11,8 +11,8 @@
  *
  * Synchronous: a transition predicate returns a boolean and has no I/O.
  */
+import { type ImportedAction } from "./internal/action-id.js";
 import type { RouteLocation, TransitionConfig, TransitionWhenContext, TransitionWhenFn, TransitionWhenKind } from "../types/segments.js";
-type ImportedAction = (...args: never[]) => unknown;
 /** A navigation side: a URL, or a partial RouteLocation. */
 export type RunTransitionWhenLocation = string | URL | (Partial<Omit<RouteLocation, "url">> & {
     url?: string | URL;
@@ -35,7 +35,7 @@ export interface RunTransitionWhenOptions {
     /** The destination. Defaults to `from`; always `from` for "action" and "revalidate". */
     to?: RunTransitionWhenLocation;
     /**
-     * The triggering action (like runClientRevalidate's): an imported server
+     * The triggering action (like runRevalidate's): an imported server
      * action (id via `$id ?? $$id`), an actionId string, or
      * `{ ref, formData, result, error }`.
      */
@@ -50,4 +50,3 @@ export interface RunTransitionWhenResult {
     context: TransitionWhenContext;
 }
 export declare function runTransitionWhen(whenOrConfig: TransitionWhenFn | TransitionConfig, opts?: RunTransitionWhenOptions): RunTransitionWhenResult;
-export {};

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

@@ -29,7 +29,8 @@
  *
  * A `Prerender` route serves its handler layer from the artifact
  * `router.matchForPrerender` bakes for the URL (on its first request, kept
- * until resetShellTestState), through the production prerender store. Its
+ * until resetShellTestState), through the production prerender store; an
+ * intercept of it serves from the intercept variant the bake keeps. Its
  * first `ppr` request is a MISS with a runtime capture, as a URL without a
  * build-time shell is in production; build-time shells are e2e-only. An
  * on-demand route (`Prerender(..., { onDemand })`) bakes nothing here: it
@@ -63,10 +64,19 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * of a document GET: from `from` (default `/`) with `segments` mounted
      * (default none), advertising fragment passthrough. The replay decision is
      * `result.replayStatus`.
+     *
+     * `prefetch: true` sends it as a `<Link>` prefetch does (the
+     * `X-Rango-Prefetch` header), so `prefetch: false` loaders and `loading()`
+     * 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`.
      */
     partial?: true | {
         from?: string;
         segments?: readonly string[];
+        prefetch?: boolean;
+        fill?: boolean;
     };
     /**
      * POST this form as a submit before hydration: the no-JS request the
@@ -76,6 +86,29 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * Not with `partial`.
      */
     form?: FormData;
+    /**
+     * Send the request a JS server action call makes from the page at `url`:
+     * a POST of `args` (encoded as the browser encodes them) for `ref`, with
+     * the page's mounted `segments` (default none), as
+     * browser/server-action-bridge.ts sends it. The response is the action's
+     * Flight payload (its return value and the re-rendered segments).
+     * Not with `partial` or `form`.
+     */
+    action?: ServeShellRequestAction;
+}
+/** The JS server action call of {@link ServeShellRequestOptions.action}. */
+export interface ServeShellRequestAction {
+    /** The server action. */
+    ref: (...args: any[]) => unknown;
+    /**
+     * Its reference id, `<module id>#<export name>`, as the build gives a
+     * "use server" export; registered so the handler loads `ref` by it.
+     */
+    id: string;
+    /** The arguments the page calls it with. */
+    args?: readonly unknown[];
+    /** The segment ids the page holds (`_rsc_segments`). */
+    segments?: readonly string[];
 }
 /** A response's handle data, as the browser consumes it. */
 export interface ShellRequestHandles {
@@ -133,6 +166,12 @@ export interface ServeShellRequestResult {
      * values resolved. Undefined when no Flight was rendered.
      */
     readHandles(): Promise<ShellRequestHandles | undefined>;
+    /**
+     * The ids of the segments `flight` marks deferred (a prefetch skipped
+     * them; the fill request renders them), in payload order. Empty when
+     * nothing was deferred, undefined when no Flight was rendered.
+     */
+    readDeferred(): Promise<string[] | undefined>;
     /**
      * The form state the SSR render received (the `formState` render option),
      * or undefined when it received none.

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

@@ -146,6 +146,10 @@ export declare function rangoTestConfig(opts?: RangoTestAliasOptions): RangoTest
 /** A minimal Vite plugin shape (avoids a hard dependency on Vite's types). */
 interface FlightTransformPlugin {
     name: string;
+    resolveId: {
+        order: "pre";
+        handler(source: string, importer: string | undefined): string | undefined;
+    };
     transform(code: string, id: string): Promise<{
         code: string;
         map: unknown;
@@ -202,6 +206,13 @@ interface FlightTransformPlugin {
  * by the module's absolute path (the boundary id), the export name becoming the
  * boundary name. Modules without the directive (server components) are untouched,
  * so `renderToFlightString` of pure leaf trees is unaffected.
+ *
+ * A `"use client"` module whose default export is a `clientUrls()` definition
+ * also installs its server projection, as the rango plugin's discovery does for
+ * an app: the module imports its own source without this transform and projects
+ * it under its client reference. A router that mounts the group
+ * (`include("/shop", shopUrls)` or `.routes(shopUrls)`) then serves its routes
+ * through `serveShellRequest` and `dispatch` with no setup.
  */
 export declare function rangoUseClientTransform(): FlightTransformPlugin;
 /** The Vite plugin shape {@link rangoUseCacheTransform} returns. */

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

@@ -13,3 +13,9 @@ 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/boundaries.d.ts

@@ -87,6 +87,15 @@ export type LoaderDataResult<T = unknown> = {
     };
 };
 export declare function isLoaderDataResult(value: unknown): value is LoaderDataResult;
+/**
+ * A loading skeleton is renderable only when it is a real ReactNode value;
+ * `false` counts as "not renderable". This is the three-term gate. The
+ * distinct two-term gate at the LoaderBoundary site (segment-system.tsx)
+ * deliberately treats `false` as "create a boundary without a
+ * RouteContentWrapper" (tree-structure.md), so it must NOT use this helper.
+ * Leaf module: shared by client (segment-system) and server (DSL, resolution).
+ */
+export declare function isRenderableLoading(loading: unknown): boolean;
 export interface NotFoundInfo {
     message: string;
     segmentId: string;

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

@@ -372,6 +372,20 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      * setupLoaderAccess.
      */
     _bindLoaderCacheTags?: (loaderId: string, tags: Set<string>) => void;
+    /**
+     * @internal This match's `prefetch: false` plan: what a prefetch defers,
+     * whether the request is a fill, and the loaders that cannot call
+     * ctx.rendered(). Set by match-api.ts when the tree declares a flag or the
+     * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
+     */
+    _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+    /**
+     * @internal Whether a loader was started in this request: a run of it (a
+     * handler's or another loader's ctx.use()) or its cache() binding. A
+     * prefetch delivers such a loader instead of deferring it. See
+     * setupLoaderAccess.
+     */
+    _loaderStarted?: (loaderId: string) => boolean;
 };
 /**
  * Generic params type - flexible object with string keys

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

@@ -175,6 +175,36 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
  */
 export type LoaderOptions = {
     ssr?: boolean;
+    /**
+     * `prefetch: false` keeps this loader out of prefetches. A `<Link>`
+     * prefetch (a partial request with `X-Rango-Prefetch`) does not execute it;
+     * the payload marks it deferred. A document request and a navigation with
+     * no prefetch to adopt run it as usual.
+     *
+     * A deferred loader never blocks the navigation that adopts the prefetch:
+     * it behaves like a loader that is still streaming. Its own `<Suspense>`
+     * shows at once; if the nearest boundary is the route's `loading()`, that
+     * shows; with no boundary React holds the page until the fill returns. The
+     * fill is the one follow-up request that runs the loader.
+     *
+     * The fill reads through the loader's own `cache()` and any `"use cache"`
+     * function it calls. A prefetch reads neither, by intent: looking would
+     * mean running the loader on a miss.
+     *
+     * The flag applies only to a segment the client does not have yet. A
+     * loader the client already holds (the same route with new params, say)
+     * runs in the prefetch when it revalidates, exactly as without the flag:
+     * a click that adopts a prefetch is never worse than the same click with
+     * no prefetch at all.
+     *
+     * Limits: a handler that awaits the loader with `ctx.use()` makes it run in
+     * the prefetch anyway; the loader cannot call `ctx.rendered()` (it throws
+     * on every request); on a `ppr` route the flag is ignored for an
+     * `ssr: false` loader (the bake lane), with a dev warning. In the fill
+     * request only deferred work and middleware run, so values a held handler
+     * would have set with `ctx.set()` are not visible.
+     */
+    prefetch?: boolean;
 };
 /**
  * Options for fetchable loaders

package/dist/types/types/request-scope.d.ts

@@ -48,6 +48,13 @@ export interface RequestScope<TEnv = DefaultEnv> {
      * cache keying.
      */
     originalUrl: URL;
+    /**
+     * The visitor's URL (the address bar, search included) when middleware
+     * rewrote this request with `throw rewrite()`; `undefined` otherwise. `url`,
+     * `pathname` and `searchParams` are the rewrite target's. After several
+     * rewrites this is still the first URL. Each context gets its own copy.
+     */
+    rewrittenFrom?: URL;
     /** URL pathname (same as `url.pathname`). */
     pathname: string;
     /**