@rangojs/router 0.24.4 → 0.26.0

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/build-versions.d.ts

@@ -15,9 +15,6 @@ export interface BuildVersions extends RouterVersions {
  * Install the cache versions of a simulated build, or remove them with no
  * argument (routers serve unversioned again, the default in tests).
  *
- * A router that sets `createRouter({ version })` keeps that value for both
- * versions, exactly as in production.
- *
  * @example A deploy that changes the client only keeps cached data
  * ```ts
  * setBuildVersions({ data: "d1", document: "h1" });

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/internal/seed-vars.d.ts

@@ -21,10 +21,10 @@ export interface StateCookieSeed {
      */
     routerId?: string;
     /**
-     * The app's version, as `createRouter({ version })` would set it: the
-     * rotated value's prefix (`{version}:{timestamp}`) and the version a cache
-     * store keys with. Defaults to `"0"` for the prefix (resolved inside
-     * createRequestContext) and to the build versions for the store.
+     * The app's version: the rotated value's prefix (`{version}:{timestamp}`)
+     * and the request's cache versions, which a store keys with. Defaults to
+     * `"0"` for the prefix (resolved inside createRequestContext) and to the
+     * build versions for the store.
      */
     version?: string;
 }

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

@@ -2,7 +2,7 @@
  * serveShellRequest — one request through the production PPR serve path.
  *
  * Builds the router's request handler as `router.fetch` does
- * (`createRSCHandler` with the router's `nonce`, `version` and `cache`
+ * (`createRSCHandler` with the router's `nonce` and `cache`
  * config) and serves one GET through it, so middleware, the shell serve path
  * and a MISS's background capture all run production code, on real Flight
  * (the vendored react-server-dom serializer). The call settles every
@@ -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
@@ -163,7 +164,12 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
  * deterministically precedes Response construction, where the streamed
  * default only wins that race opportunistically). Under ppr it is also the
  * BAKE lane: the loader executes at shell capture and its settled return is
- * shell material (nested promises stay live holes) — see the ppr docs.
+ * shell material (nested promises stay live holes), and so are its handle
+ * pushes, a pushed promise or `.defer()` included: the capture awaits it and
+ * every HIT serves the value it settled to (#1182). A pushed promise that
+ * rejects, or misses `ppr.captureTimeout`, keeps the route on MISS. A value
+ * that must stay per request belongs to a loader without `ssr: false` — see
+ * the ppr docs.
  *
  * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
  * deliberately streaming sibling awaits only itself, and the sibling keeps

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 {};

package/dist/types/vite/discovery/state.d.ts

@@ -52,7 +52,26 @@ export interface PluginOptions {
      * budget into its capture/render handlers.
      */
     progressiveChunkSize?: number;
+    /**
+     * The index rango()'s clientUrls() revalidate() hoist plugin shares, so
+     * discovery's temp server records keys into it and assigns the files the
+     * dev server's or build's group modules import.
+     */
+    clientUrlRevalidate?: ClientUrlRevalidateIndex;
+}
+/**
+ * What the clientUrls() revalidate() hoist
+ * (plugins/client-urls-revalidate-hoist.ts) shares with discovery across the
+ * plugin instances of one rango(), the dev server or build and discovery's
+ * temp server: the file of every key the hoist transform saw, in any
+ * environment, and each group's files, which discovery assigns from the
+ * group's projection and the group's `?rango-revalidate` module imports.
+ */
+export interface ClientUrlRevalidateIndex {
+    readonly fileByKey: Map<string, string>;
+    readonly filesByGroup: Map<string, readonly string[]>;
 }
+export declare function createClientUrlRevalidateIndex(): ClientUrlRevalidateIndex;
 export interface PrecomputedEntry {
     staticPrefix: string;
     routes: Record<string, string>;
@@ -122,6 +141,7 @@ export interface DiscoveryState {
     perRouterManifestDataMap: Map<string, Record<string, string>>;
     clientUrlSourceByReferenceId?: Map<string, string>;
     clientUrlProjectionMap?: Map<string, ClientUrlProjection>;
+    clientUrlRevalidate: ClientUrlRevalidateIndex;
     prerenderManifestEntries: Record<string, string> | null;
     staticManifestEntries: Record<string, string> | null;
     /**