@rangojs/router 0.22.0 → 0.23.0

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

@@ -587,6 +587,19 @@ 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";
     /**
      * Attach location state entries to the current response.
      *
@@ -803,7 +816,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" | "_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:

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)
@@ -39,8 +39,8 @@ 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/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-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

@@ -63,10 +63,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 +85,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 +165,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/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/segments.d.ts

@@ -158,6 +158,15 @@ export interface ResolvedSegment {
      */
     awaitBeforeFlush?: true;
     parallelLoading?: ReactNode;
+    /**
+     * A prefetch skipped this segment's work (`prefetch: false`): a loader
+     * carries no `loaderData`, a layout/route/parallel unit carries
+     * `component: null` and its fallback. The browser shows the fallback and
+     * sends a fill request for it (browser/partial-update.ts); until that
+     * lands the segment is a placeholder, never a held copy. Only ever on a
+     * prefetch response: see docs/design/prefetch-false.md.
+     */
+    deferred?: true;
     loaderDataPromise?: Promise<any[]> | any[];
     loaderIds?: string[];
     /**
@@ -228,10 +237,12 @@ export interface MatchResult {
     /**
      * Every segment id whose handler actually ran on the server this request,
      * including ones with `component === null` that get filtered out of
-     * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
-     * cleanup pass — a slot that re-resolves and pushes nothing must clear
-     * its previous handle bucket, but `diff` doesn't carry it because the
-     * segment payload doesn't either. A superset of `diff`.
+     * `segments`/`diff` to avoid wasted bytes, and every loader segment that
+     * ran. Drives the client's handle merge (handles/pushed-by.ts) — a slot
+     * that re-resolves and pushes nothing must clear its previous handle
+     * bucket, but `diff` doesn't carry it because the segment payload doesn't
+     * either; a loader that ran replaces its pushes, one that did not keeps
+     * them. A superset of `diff`.
      */
     resolvedIds: string[];
     /**
@@ -279,3 +290,9 @@ export interface MatchResult {
         params: Record<string, string>;
     }>;
 }
+/**
+ * A `prefetch: false` placeholder (ResolvedSegment.deferred): a segment whose
+ * work a prefetch skipped, waiting for its fill. Never a held copy of the
+ * segment it stands for.
+ */
+export declare function isPlaceholder(segment: Pick<ResolvedSegment, "deferred">): boolean;

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

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import type { ErrorBoundaryHandler, ExtractParams, Handler, HandlerContext, LoaderDefinition, LoaderOptions, MiddlewareFn, NotFoundBoundaryHandler, PartialCacheOptions, ShouldRevalidateFn, TransitionConfig } from "../types.js";
-import type { AllUseItems, TypedLayoutItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ResponseRouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, TypedCacheItem, TransitionItem, TypedTransitionItem, TypedRouteItem, TypedIncludeItem, UseItems } from "../route-types.js";
+import type { AllUseItems, TypedLayoutItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ResponseRouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, TypedCacheItem, TypedTransitionItem, TypedRouteItem, TypedIncludeItem, UseItems } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
 import type { PrerenderHandlerDefinition, PassthroughHandlerDefinition } from "../prerender.js";
 import type { StaticHandlerDefinition, StaticHandlerRef } from "../static-handler.js";
@@ -158,13 +158,34 @@ export type PathHelpers<TEnv> = {
      * flag BAKES: the loader executes at shell capture and its settled return
      * freezes into the shell (nested promises stay live holes) — the pre-flush
      * promise applied to the prelude.
+     *
+     * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+     * prefetch skips it and the click that adopts the prefetch fetches it in
+     * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+     * client does not have yet: a loader the client already holds runs in the
+     * prefetch when it revalidates.
      */
     loader: <TData>(loaderDef: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]), use?: () => LoaderUseItem[]) => LoaderItem;
     /**
-     * Attach a loading component to the current route/layout
+     * Attach a loading component to the current route/layout.
+     *
+     * `{ ssr: false }` skips the fallback on document requests. `{ prefetch:
+     * false }` keeps what the fallback covers out of prefetches, when this
+     * entry's segment is new to the client: the entry's handler, its loaders,
+     * its orphan layouts and parallel slots and, for a layout, every deeper
+     * entry. The click that adopts the prefetch shows the fallback and fetches
+     * them in one follow-up request, which reads cache() and "use cache" as
+     * any request does (a prefetch reads neither for skipped work). A segment
+     * the client already holds is never deferred: a prefetch renders it as
+     * usual when it revalidates, and what is below it follows its own flags.
+     * To keep a child out of prefetches while moving inside a section, flag
+     * the child's own loading(). An entry whose handler output is stored
+     * (cache(), ppr, Prerender/Static) is served as usual and only its loaders
+     * are skipped.
      */
     loading: (component: ReactNode | (() => ReactNode), options?: {
         ssr?: boolean;
+        prefetch?: boolean;
     }) => LoadingItem;
     /**
      * Attach an error boundary to catch errors in this segment
@@ -199,8 +220,8 @@ export type PathHelpers<TEnv> = {
      * the browser (never on the server); see TransitionWhenFn.
      */
     transition: {
-        (): TransitionItem;
-        (config: TransitionConfig): TransitionItem;
+        (): TypedTransitionItem<{}, {}>;
+        (config: TransitionConfig): TypedTransitionItem<{}, {}>;
         <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(children: () => TChildren): TypedTransitionItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
         <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(config: TransitionConfig, children: () => TChildren): TypedTransitionItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
     };

package/dist/types/urls/type-extraction.d.ts

@@ -1,6 +1,10 @@
 import type { JsonSerialize } from "../serialize.js";
 import type { TypedRouteItem, TypedIncludeItem, TypedLayoutItem, TypedCacheItem, TypedTransitionItem } from "../route-types.js";
 import type { LocalOnlyInclude, UnnamedRoute } from "./pattern-types.js";
+/** Drops string index signatures, keeping literal and template keys. */
+type StripStringIndex<T> = {
+    [K in keyof T as string extends K ? never : K]: T[K];
+};
 /**
  * Prefix route names with a given prefix (e.g., "blog" + "post" = "blog.post")
  *
@@ -52,7 +56,7 @@ type ExtractRoutesFromItem<T> = T extends TypedRouteItem<infer TName, infer TPat
         readonly path: TPattern;
         readonly search: TSearch;
     };
-} : {} : T extends TypedIncludeItem<infer TRoutes, infer TNamePrefix, infer TUrlPrefix> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TUrlPrefix extends string ? PrefixRoutes<PrefixPatterns<TRoutes, TUrlPrefix>, TNamePrefix> : PrefixRoutes<TRoutes, TNamePrefix> : TUrlPrefix extends string ? PrefixPatterns<TRoutes, TUrlPrefix> : TRoutes : T extends TypedLayoutItem<infer TChildRoutes> ? TChildRoutes : T extends TypedCacheItem<infer TChildRoutes> ? TChildRoutes : T extends TypedTransitionItem<infer TChildRoutes> ? TChildRoutes : {};
+} : {} : T extends TypedIncludeItem<infer TRoutes, infer TNamePrefix, infer TUrlPrefix> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TUrlPrefix extends string ? PrefixRoutes<PrefixPatterns<TRoutes, TUrlPrefix>, TNamePrefix> : PrefixRoutes<TRoutes, TNamePrefix> : TUrlPrefix extends string ? PrefixPatterns<TRoutes, TUrlPrefix> : TRoutes : T extends TypedLayoutItem<infer TChildRoutes> ? StripStringIndex<TChildRoutes> : T extends TypedCacheItem<infer TChildRoutes> ? StripStringIndex<TChildRoutes> : T extends TypedTransitionItem<infer TChildRoutes> ? StripStringIndex<TChildRoutes> : {};
 /**
  * Extract routes from an array of items using mapped types.
  * Uses UnionToIntersection to combine routes without recursive tuple processing,
@@ -82,7 +86,7 @@ type PrefixKeys<T extends Record<string, unknown>, TPrefix extends string> = TPr
  */
 type ExtractResponsesFromItem<T> = T extends TypedRouteItem<infer TName, any, infer TData> ? TName extends string ? string extends TName ? {} : TName extends UnnamedRoute ? {} : {
     [K in TName]: TData;
-} : {} : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TResponses extends Record<string, unknown> ? PrefixKeys<TResponses, TNamePrefix> : {} : TResponses extends Record<string, unknown> ? TResponses : {} : T extends TypedLayoutItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : T extends TypedCacheItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : T extends TypedTransitionItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : {};
+} : {} : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TResponses extends Record<string, unknown> ? PrefixKeys<TResponses, TNamePrefix> : {} : TResponses extends Record<string, unknown> ? TResponses : {} : T extends TypedLayoutItem<any, infer TChildResponses> ? StripStringIndex<TChildResponses> extends infer R extends Record<string, unknown> ? R : {} : T extends TypedCacheItem<any, infer TChildResponses> ? StripStringIndex<TChildResponses> extends infer R extends Record<string, unknown> ? R : {} : T extends TypedTransitionItem<any, infer TChildResponses> ? StripStringIndex<TChildResponses> extends infer R extends Record<string, unknown> ? R : {} : {};
 /**
  * Extract responses from an array of items using mapped types.
  * Parallel to ExtractRoutesFromItems.

package/dist/types/vite/discovery/discover-routers.d.ts

@@ -13,5 +13,14 @@ import type { DiscoveryState } from "./state.js";
  *
  * Returns the imported `@rangojs/router/server` module so the caller
  * can access the RouterRegistry and manifest setters.
+ *
+ * A pass reads the router registry and installs clientUrls projections on ONE
+ * `@rangojs/router/server` instance, and checks that the runner still serves
+ * it. A runner full reload during the pass (a watched-file change at boot)
+ * splits the realm: a router module bound to the old instance registers there
+ * while urls modules re-evaluate against a fresh one, so include() looks its
+ * projection up in the fresh, empty Map ("include() could not resolve the
+ * server projection"). Such a pass is redone, at most
+ * MAX_DISCOVERY_PASSES times; the redo evaluates the entry in one realm.
  */
 export declare function discoverRouters(state: DiscoveryState, rscEnv: any, ssrEnv?: any): Promise<any>;

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

@@ -188,14 +188,21 @@ export interface DiscoveryState {
     /** Cleanup function for build-time env resources (e.g., miniflare). */
     buildEnvDispose?: (() => Promise<void> | void) | null;
     /**
-     * Set when the most recent HMR re-discovery threw. Cleared on the next
-     * successful discovery. Surfaced via debug logs so we can detect "manifest
-     * frozen at last-good after error → user fix in non-route file → no
-     * rediscovery trigger" scenarios.
+     * Set when the most recent discovery threw: an HMR re-discovery, or the
+     * cold dev discovery on a main RSC runner. Cleared on the next successful
+     * discovery. While set, the route-file watcher treats any in-scan source
+     * change as a rediscovery trigger (recovery mode).
      */
     lastDiscoveryError?: {
         message: string;
         at: number;
     } | null;
 }
+/**
+ * Whether the route-file watcher can re-run runtime discovery. A committed
+ * manifest is the usual precondition. A failed cold discovery commits none,
+ * so on a main RSC runner its recorded failure qualifies too; without that
+ * the dev server stayed broken until a restart.
+ */
+export declare function canRefreshRuntimeDiscovery(state: Pick<DiscoveryState, "perRouterManifests" | "lastDiscoveryError">, hasMainRunner: boolean): boolean;
 export declare function createDiscoveryState(entryPath: string | undefined, opts: PluginOptions | undefined): DiscoveryState & ClientUrlDiscoveryState;

package/dist/types/vite/plugins/client-urls-revalidate-hoist.d.ts

@@ -0,0 +1,54 @@
+import type { Plugin } from "vite";
+import MagicString from "magic-string";
+/**
+ * The key of the predicate `source` declared in `relativeFile` (relative to
+ * the project root): a hash of the file and the predicate's syntax, so the
+ * same predicate gets one key in every environment and however it is
+ * formatted.
+ */
+export declare function revalidateKey(relativeFile: string, source: string): string;
+interface HoistClientUrlsRevalidateDeps {
+    /** Project root: keys hash the file relative to it. */
+    readonly root: string;
+    /**
+     * Whether a module a predicate imports is a "use client" module beyond its
+     * specifier (the plugin resolves it and reads its directive prologue).
+     */
+    isClientModule?(source: string): Promise<boolean> | boolean;
+}
+interface HoistClientUrlsRevalidateResult {
+    /** The module with each predicate replaced by its marker. */
+    readonly code: string;
+    readonly map: ReturnType<MagicString["generateMap"]>;
+    /** The server module that registers every hoisted predicate. */
+    readonly module: string;
+    /** The keys, in declaration order, duplicates removed. */
+    readonly keys: readonly string[];
+}
+/**
+ * Hoist every clientUrls() `revalidate()` predicate of a "use client"
+ * module. Returns null when there is none. Throws, naming file:line, for a
+ * predicate that is not pure.
+ */
+export declare function hoistClientUrlsRevalidates(code: string, id: string, deps: HoistClientUrlsRevalidateDeps): Promise<HoistClientUrlsRevalidateResult | null>;
+/** The file a `?rango-revalidate` id names, or null. */
+export declare function parseHoistedRevalidateId(id: string): string | null;
+/**
+ * The plugins: a pre transform that hoists in every environment (markers in
+ * the client and SSR copies, the server module recorded from the RSC
+ * transform) and serves `?rango-revalidate`, and a post transform that
+ * appends its import to the RSC client-reference proxy.
+ *
+ * `load` serves the module the RSC transform emitted, which hoisted the
+ * pipeline code; the disk source is re-hoisted only when the transform has
+ * not seen the current file (loadEmittedOrDisk). A file whose edit removed
+ * every predicate serves an empty module to a proxy that still imports it.
+ *
+ * The transform's code filter skips a module that never mentions clientUrls,
+ * so a file that stops doing so would keep its `emitted` entry: watchChange
+ * drops it, together with the cached "use client" answer for an edited
+ * dependency (isClientModule memoizes per resolved file; buildStart resets
+ * it).
+ */
+export declare function clientUrlsRevalidateHoistPlugin(): Plugin[];
+export {};