@rangojs/router 0.33.1 → 0.34.0

package/dist/bin/{chunk-TTXC2U3G.js → chunk-4HHFQSDC.js}

@@ -3,7 +3,7 @@ import {
   prefetchDirect,
   prefetchQueued,
   schedulePrefetchWhenRouterIdle
-} from "./chunk-3B7CKBRO.js";
+} from "./chunk-MWOHBDPM.js";
 import {
   findTsFiles,
   firstCodeMatchIndex,
@@ -488,12 +488,15 @@ import {
 } from "react";
 
 // src/loader-store.ts
+var NO_ROUTE_DATA = /* @__PURE__ */ new Set();
 var EMPTY_SNAPSHOT = Object.freeze({
   value: void 0,
   hasValue: false,
   error: null,
   isLoading: false,
-  requestId: 0
+  requestId: 0,
+  valueFor: NO_ROUTE_DATA,
+  requestFor: NO_ROUTE_DATA
 });
 
 // src/client-urls/hoisted-revalidate.ts
@@ -1383,8 +1386,13 @@ function serializeLoaderOptions(loaders, owner, options) {
     loaders,
     ({ prefetch }) => prefetch === false
   );
+  const intentLoaderIndices = indicesWhere(
+    loaders,
+    ({ prefetch }) => prefetch === "intent"
+  );
   return {
     ...deferrableLoaderIndices.length > 0 ? { deferrableLoaderIndices: Object.freeze(deferrableLoaderIndices) } : {},
+    ...intentLoaderIndices.length > 0 ? { intentLoaderIndices: Object.freeze(intentLoaderIndices) } : {},
     ...loaderRevalidate.some((keys) => keys.length > 0) ? {
       loaderRevalidate: Object.freeze(
         loaderRevalidate.map((keys) => Object.freeze(keys))

package/dist/bin/{chunk-3B7CKBRO.js → chunk-MWOHBDPM.js}

@@ -1,3 +1,8 @@
+// src/prefetch-markers.ts
+var PREFETCH_HEADER = "X-Rango-Prefetch";
+var PREFETCH_INTENT = "intent";
+var PREFETCH_FAILED_ROW = ":H_0\n";
+
 // src/internal-debug.ts
 var INTERNAL_RANGO_DEBUG = typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
 
@@ -209,7 +214,7 @@ var requestGeneration = 0;
 function loadRuntime() {
   if (runtime) return Promise.resolve(runtime);
   if (!runtimePromise) {
-    runtimePromise = import("./runtime-EPUDEHO4.js").then(
+    runtimePromise = import("./runtime-6WLCJCN7.js").then(
       (loaded) => {
         runtime = loaded;
         if (decoder) loaded.setPrefetchDecoder(decoder);
@@ -423,12 +428,10 @@ function isActionFenceActive() {
   return fenceCount > 0;
 }
 
-// src/prefetch-markers.ts
-var PREFETCH_HEADER = "X-Rango-Prefetch";
-var PREFETCH_INTENT = "intent";
-var PREFETCH_FAILED_ROW = ":H_0\n";
-
 export {
+  PREFETCH_HEADER,
+  PREFETCH_INTENT,
+  PREFETCH_FAILED_ROW,
   IS_BROWSER_DEBUG,
   debugLog,
   notifyListeners,
@@ -454,9 +457,6 @@ export {
   clearPrefetchInflight,
   isFragmentPassthroughEnabled,
   isActionFenceActive,
-  PREFETCH_HEADER,
-  PREFETCH_INTENT,
-  PREFETCH_FAILED_ROW,
   prefetchDirect,
   prefetchQueued,
   schedulePrefetchWhenRouterIdle

package/dist/bin/{client-urls-projection-DQLWPDAT.js → client-urls-projection-4Q5EQDAL.js}

@@ -10,8 +10,8 @@ import {
   refreshRecordedClientUrlProjections,
   resolveClientUrlsSource,
   scanForClientUrlModules
-} from "./chunk-TTXC2U3G.js";
-import "./chunk-3B7CKBRO.js";
+} from "./chunk-4HHFQSDC.js";
+import "./chunk-MWOHBDPM.js";
 import "./chunk-LD7UBHT4.js";
 export {
   CLIENT_IMPORT_RE,

package/dist/bin/rango.js

@@ -229,7 +229,7 @@ ${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}
   }
   let discoverAndWriteRouteTypes;
   try {
-    const mod = await import("./runtime-discovery-3HH6BP3K.js");
+    const mod = await import("./runtime-discovery-2ZTYRZ3V.js");
     discoverAndWriteRouteTypes = mod.discoverAndWriteRouteTypes;
   } catch (err) {
     if (err.code === "ERR_MODULE_NOT_FOUND" || err.code === "MODULE_NOT_FOUND") {

package/dist/bin/{runtime-EPUDEHO4.js → runtime-6WLCJCN7.js}

@@ -26,7 +26,7 @@ import {
   setInflightPromiseWithAliases,
   stateEpoch,
   storePrefetch
-} from "./chunk-3B7CKBRO.js";
+} from "./chunk-MWOHBDPM.js";
 
 // src/browser/prefetch/resource-ready.ts
 function waitForViewportImages() {

package/dist/bin/{runtime-discovery-3HH6BP3K.js → runtime-discovery-2ZTYRZ3V.js}

@@ -163,9 +163,9 @@ async function discoverAndWriteRouteTypes(opts) {
       "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc"
     );
   }
-  const { createTempRscServer } = await import("./temp-rsc-server-JALTIWLT.js");
+  const { createTempRscServer } = await import("./temp-rsc-server-EUNKRFJD.js");
   const { createDiscoveryState } = await import("./state-ACD2MGKJ.js");
-  const { discoverClientUrlProjections } = await import("./client-urls-projection-DQLWPDAT.js");
+  const { discoverClientUrlProjections } = await import("./client-urls-projection-4Q5EQDAL.js");
   const {
     isFrameworkPlugin,
     pickForwardedRunnerConfig,

package/dist/bin/{temp-rsc-server-JALTIWLT.js → temp-rsc-server-EUNKRFJD.js}

@@ -27,8 +27,8 @@ import {
   propertyKeyIs,
   recordClientUrlsModule,
   unwrapExpression
-} from "./chunk-TTXC2U3G.js";
-import "./chunk-3B7CKBRO.js";
+} from "./chunk-4HHFQSDC.js";
+import "./chunk-MWOHBDPM.js";
 import {
   codeMatchIndices,
   isSkippedSourceScanDir
@@ -47,7 +47,7 @@ var DEFAULT_ROUTER_VERSIONS_KEY = "*";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.33.1",
+  version: "0.34.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/dist/testing/vitest.js

@@ -296,6 +296,11 @@ function rangoTestAliases(opts = {}) {
     {
       find: /^@vitejs\/plugin-rsc\/rsc(\/(server|client))?$/,
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts")
+    },
+    // useLoader().load() decodes renderRoute's loader answers through it.
+    {
+      find: /^@vitejs\/plugin-rsc\/browser$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc-browser.ts")
     }
   ];
   if (rsdServerEdgePath) {

package/dist/types/browser/history-state.d.ts

@@ -1,3 +1,4 @@
+import { type LocationStateSnapshot } from "./react/location-state-shared.js";
 /**
  * Resolve navigation state - handles both LocationStateEntry[] and plain formats
  */
@@ -11,6 +12,26 @@ export declare function buildHistoryState(userState: unknown, routerState?: {
     intercept?: boolean;
     sourceUrl?: string;
 }, serverState?: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * The entry a commit onto the entry on screen writes (router.refresh(), the
+ * cross-tab refresh): `entryState`, read when the commit lands, keeps its
+ * location state. Its scroll key and idx go (pushHistoryWithIdx and
+ * ensureHistoryKey write them again), and its intercept marks are this
+ * commit's: a refresh renders the URL's full page. Server-set state merges
+ * over the kept state. A flash a reader already cleared from the entry stays
+ * cleared: the entry is copied, never rebuilt from what readers show.
+ */
+export declare function keptEntryState(entryState: unknown, routerState?: {
+    intercept?: boolean;
+    sourceUrl?: string;
+}, serverState?: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * What readers get from a commit onto the entry on screen: the state they
+ * show, plus the server's, recorded under the client's version. Not re-read
+ * from the entry, so a flash value on screen stays until the next navigation
+ * or back/forward.
+ */
+export declare function shownLocationState(shown: LocationStateSnapshot, serverState?: Record<string, unknown>): Record<string, unknown>;
 /** Check if a history state object contains location state keys. */
 export declare function hasLocationState(state: unknown): boolean;
 /**

package/dist/types/browser/navigation-transaction.d.ts

@@ -41,6 +41,8 @@ interface CommitOptions {
      * screen stays (EventController.commitLocationState).
      */
     treeless?: boolean;
+    /** Commits onto the entry on screen, keeping its location state (see keptEntryState). */
+    sameEntry?: boolean;
 }
 /**
  * Options that can override the pre-configured commit settings

package/dist/types/client-urls/server-projection.d.ts

@@ -38,6 +38,11 @@ export interface ClientUrlProjectionRoute {
      *  loader(), so a prefetch of the route defers them. Absent (= none) in
      *  projections serialized before the option existed. */
     readonly deferrableLoaderIndices?: readonly number[];
+    /** Indices into loaderIds of loaders declared loader(Def, { prefetch:
+     *  "intent" }); materialization passes the option through, so a
+     *  speculative prefetch defers them and an intent prefetch runs them.
+     *  Absent (= none) in projections serialized before the option existed. */
+    readonly intentLoaderIndices?: readonly number[];
     /** Per loader (aligned with loaderIds), its revalidate() arguments in
      *  declaration order: a hoisted predicate's key, whose registration
      *  materialization attaches (revalidate-registry.ts), or a boolean
@@ -64,6 +69,8 @@ export interface ClientUrlProjectionIntercept {
     readonly hasLoading: boolean;
     /** As on a route (ClientUrlProjectionRoute.deferrableLoaderIndices). */
     readonly deferrableLoaderIndices?: readonly number[];
+    /** As on a route (ClientUrlProjectionRoute.intentLoaderIndices). */
+    readonly intentLoaderIndices?: readonly number[];
     /** As on a route (ClientUrlProjectionRoute.loaderRevalidate). */
     readonly loaderRevalidate?: readonly (readonly (string | boolean)[])[];
 }

package/dist/types/client-urls/types.d.ts

@@ -2,6 +2,7 @@ import type { ComponentType, ReactNode } from "react";
 import type { LoaderDefinition, LoaderOptions, ShouldRevalidateFn, TransitionConfig } from "../types.js";
 import type { DefaultEnv } from "../types/global-namespace.js";
 import type { HoistedRevalidateRef } from "./hoisted-revalidate.js";
+import type { PrefetchFlag } from "../prefetch-markers.js";
 import type { TrieMatchResult } from "../router/trie-matching.js";
 import type { PathOptions } from "../urls/pattern-types.js";
 import type { SearchSchema } from "../search-params.js";
@@ -48,13 +49,12 @@ export interface ClientUrlLoaderRecord {
      */
     readonly ssr?: false;
     /**
-     * loader(Def, { prefetch: false }): a viewport or render prefetch of the
-     * route, or of an intercept's target from its source, defers this loader
-     * (a hover prefetch runs it) and the click
-     * that adopts it runs it in its fill request (see {@link LoaderOptions}).
-     * Projected onto the materialized stub.
+     * loader(Def, { prefetch: false | "intent" }): a prefetch of the route, or
+     * of an intercept's target from its source, defers this loader and the
+     * click that adopts it runs it in its fill request (see
+     * {@link LoaderOptions}). Projected onto the materialized stub.
      */
-    readonly prefetch?: false;
+    readonly prefetch?: PrefetchFlag;
 }
 /**
  * The TransitionConfig subset a clientUrls() route may declare: ViewTransition
@@ -118,14 +118,13 @@ export interface ClientUrlHelpers {
      * settled return freezes into the shell (nested promises stay live
      * holes).
      *
-     * Pass `{ prefetch: false }` to keep this loader out of the route's
-     * viewport and render prefetches; a hover prefetch runs it (see
-     * {@link LoaderOptions}). An in-group click still shows
-     * the destination at once, commits the adopted prefetch with the other
-     * loaders' data, and runs only the flagged loaders in its one fill
-     * request. A `layout()` loader with the flag is flagged on every route
-     * below it. Inside intercept() it defers the loader in a viewport or
-     * render prefetch of the intercept from its source, as in urls().
+     * Pass `{ prefetch: false | "intent" }` to keep this loader out of the
+     * route's prefetches (see {@link LoaderOptions}). An in-group click still
+     * shows the destination at once, commits the adopted prefetch with the
+     * other loaders' data, and runs only the flagged loaders in its one fill
+     * request. A `layout()` loader with the
+     * flag is flagged on every route below it. Inside intercept() it defers
+     * the loader in a prefetch of the intercept from its source, as in urls().
      */
     readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: Pick<LoaderOptions, "ssr" | "prefetch"> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem;
     readonly loading: (component: ReactNode) => ClientUrlItem;

package/dist/types/errors.d.ts

@@ -247,6 +247,11 @@ export declare function invariant(condition: any, message: string): asserts cond
  * passes), as an invariant.
  */
 export declare function assertBooleanOption(value: unknown, option: string, effect: string): void;
+/**
+ * Rejects a `prefetch` DSL option that is neither a boolean nor `"intent"`
+ * (undefined passes), as an invariant.
+ */
+export declare function assertPrefetchOption(value: unknown, option: string, effect: string): void;
 /**
  * Sanitize errors for production - prevents leaking sensitive information
  *

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

@@ -53,6 +53,14 @@ export interface LoaderEntry<T = unknown> {
     readonly isLoading: boolean;
     /** Identifies the request that produced this snapshot. 0 means "no request". */
     readonly requestId: number;
+    /**
+     * Route data (a route reader's `contextData`, by identity) of the readers on
+     * screen when `value` was requested. A route reader shows `value` only while
+     * its own route data is in this set.
+     */
+    readonly valueFor: ReadonlySet<unknown>;
+    /** The same for the latest request: `isLoading` and `error`. */
+    readonly requestFor: ReadonlySet<unknown>;
 }
 /**
  * Options for `subscribe`.
@@ -92,6 +100,8 @@ export interface SubscribeOptions {
      * its own lifecycle.
      */
     onStreamPending?: () => void;
+    /** The subscriber's committed route data. Route-context readers only. */
+    routeData?: () => unknown;
 }
 export declare class LoaderStore {
     private readonly entries;
@@ -172,7 +182,7 @@ export declare class LoaderStore {
      * error during the new request. Gated on `requestId === latestRequestId`
      * for symmetry with the other mutators.
      */
-    beginRequest(bucketKey: string, requestId: number): void;
+    beginRequest(bucketKey: string, requestId: number, initiatorRouteData?: () => unknown): void;
     /**
      * Commit a successful result. No-op if `requestId` is not the latest
      * (a newer `load()` was issued or `clear()` ran). Clearing `error` is

package/dist/types/prefetch-markers.d.ts

@@ -10,12 +10,21 @@ export declare const PREFETCH_HEADER = "X-Rango-Prefetch";
 /**
  * PREFETCH_HEADER's value on an intent prefetch: a hover or an explicit
  * `prefetch()` call (browser/prefetch/fetch.ts prefetchDirect). The server
- * defers nothing in it: `prefetch: false` loaders and the work behind a
- * flagged `loading()` run, as in the navigation it starts early. A
- * speculative prefetch (viewport, render) sends `1`, and any value other than
- * this one reads as speculative.
+ * runs the work flagged `prefetch: "intent"` in it and defers the work
+ * flagged `prefetch: false`. A speculative prefetch (viewport, render) sends
+ * `1` and defers both; any value other than this one reads as speculative.
  */
 export declare const PREFETCH_INTENT = "intent";
+/**
+ * A recorded `prefetch` flag of loader() or loading(): `false` defers the
+ * work in every prefetch, `"intent"` in a speculative one only
+ * (router/segment-resolution/prefetch-deferral.ts).
+ */
+export type PrefetchFlag = false | typeof PREFETCH_INTENT;
+/** A `prefetch` DSL option as written: a boolean, or `"intent"`. */
+export type PrefetchOption = boolean | PrefetchFlag;
+/** The option asks for deferral: `prefetch: false` or `prefetch: "intent"`. */
+export declare function isPrefetchFlag(value: unknown): value is PrefetchFlag;
 /**
  * The last row of a prefetch whose render reported an error
  * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not

package/dist/types/route-definition/helpers-types.d.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import type { ExtractRouteParams, Handler, PartialCacheOptions, ErrorBoundaryHandler, LoaderDefinition, LoaderOptions, MiddlewareFn, NotFoundBoundaryHandler, ResolvedRouteMap, RouteDefinition, ShouldRevalidateFn, TransitionConfig } from "../types.js";
 import type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, CacheItem, TransitionItem, UseItems } from "../route-types.js";
 import type { StaticHandlerRef } from "../static-handler.js";
+import type { PrefetchOption } from "../prefetch-markers.js";
 export type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, CacheItem, } from "../route-types.js";
 export type { InterceptConfig, InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "../server/context";
 /**
@@ -231,15 +232,16 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * loader(RecommendationsLoader),  // still streams behind loading()
      * ```
      *
-     * Pass `{ prefetch: false }` to keep the loader out of speculative
-     * prefetches (viewport, render): such a prefetch skips it and the click
-     * that adopts it fetches it in one follow-up request; a hover prefetch runs
-     * it (see {@link LoaderOptions}). Only on a segment the
+     * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+     * prefetch skips it and the click that adopts it fetches it in one
+     * follow-up request. `{ prefetch: "intent" }` defers it in viewport and
+     * render prefetches only (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.
      *
      * ```typescript
      * loader(ReviewsLoader, { prefetch: false }),
+     * loader(RelatedLoader, { prefetch: "intent" }),
      * ```
      *
      * @param loaderDef - Loader created with createLoader()
@@ -256,16 +258,18 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * // Skip loading on SSR, only show on client navigation
      * loading(<Skeleton />, { ssr: false })
      *
-     * // Keep everything behind this fallback out of viewport and render
-     * // prefetches (a hover prefetch runs it)
+     * // Keep everything behind this fallback out of prefetches
      * loading(<Skeleton />, { prefetch: false })
+     *
+     * // Deferred in viewport and render prefetches only
+     * loading(<Skeleton />, { prefetch: "intent" })
      * ```
      * @param component - The loading UI to show during navigation
      * @param options - Configuration options
      * @param options.ssr - If false, skip showing loading on document requests (SSR)
-     * @param options.prefetch - If false, the flag applies when this entry's
-     *   segment is new to the client. A viewport or render prefetch then skips
-     *   the whole unit (a hover prefetch runs it): the
+     * @param options.prefetch - `false` or `"intent"` (see
+     *   {@link LoaderOptions}); the flag applies when this entry's segment is
+     *   new to the client. A prefetch then skips the whole unit: the
      *   handler, its loaders, its orphan layouts and parallel slots and, for a
      *   layout, every deeper entry; the click that adopts the prefetch shows
      *   this fallback and fetches them in one follow-up request, which reads
@@ -280,7 +284,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      */
     loading: (component: ReactNode | (() => ReactNode), options?: {
         ssr?: boolean;
-        prefetch?: boolean;
+        prefetch?: PrefetchOption;
     }) => LoadingItem;
     /**
      * Attach an error boundary to catch errors in this segment and children

package/dist/types/router/segment-resolution/prefetch-deferral.d.ts

@@ -1,6 +1,9 @@
 /**
- * `prefetch: false`: what a prefetch request defers and what its fill request
- * runs (docs/design/prefetch-false.md).
+ * `prefetch: false` and `prefetch: "intent"`: what a prefetch request defers
+ * and what its fill request runs (docs/design/prefetch-false.md). A
+ * speculative prefetch (viewport, render) defers both flags; an intent
+ * prefetch (a hover, `prefetch()`) defers `false` only and runs `"intent"`
+ * work as if it were unflagged.
  *
  * Two layers. The SCOPE is static per matched chain: which loader
  * registrations are deferrable and which entries can be a handler unit. The
@@ -30,20 +33,15 @@ import type { CacheScope } from "../../cache/cache-scope.js";
 /**
  * What a request says it is, read once when its context is created
  * (RequestContext._requestKind). A fill is marked on the raw URL and wins
- * over the prefetch header. `"prefetch"` is a speculative prefetch (viewport,
- * render) and `"intent"` a hover or an explicit `prefetch()` call
- * (PREFETCH_INTENT): both are prefetches, and only the first defers. Whether
- * a prefetch defers anything is decided per match, by partialDeferralMode: a
- * shell capture inherits the context of the request that scheduled it and is
- * never a prefetch.
+ * over the prefetch header; an intent prefetch carries PREFETCH_INTENT.
  */
 export declare function requestKind(request: Request, rawUrl: URL): RequestKind | undefined;
 /** requestKind's answer for a marked request. */
 export type RequestKind = "prefetch" | "intent" | "fill";
 /** A prefetch of either kind: speculative or intent. */
 export declare function isPrefetchKind(kind: RequestKind | undefined): boolean;
-/** Static, per matched chain. */
-interface DeferralScope {
+/** What one kind of prefetch can defer in a matched chain. */
+interface DeferralSet {
     /**
      * Loader registrations a prefetch can defer, each with what makes it so:
      * `true` for its own flag, else the segment ids of the flagged entries whose
@@ -51,8 +49,6 @@ interface DeferralScope {
      * segments is new to the client.
      */
     readonly loaders: ReadonlyMap<LoaderEntry, true | readonly string[]>;
-    /** `$$id`s of `loaders`: the loaders that cannot call ctx.rendered(). */
-    readonly loaderIds: ReadonlySet<string>;
     /**
      * Entries whose handler a prefetch can skip (a flagged loading() with a
      * fallback to show). `index` is the chain index that owns the entry: its
@@ -62,6 +58,23 @@ interface DeferralScope {
      */
     readonly units: ReadonlyMap<EntryData, DeferralUnit>;
 }
+/**
+ * Static, per matched chain: what a speculative prefetch defers (every flag,
+ * `false` or `"intent"`), and in `intent` what an intent prefetch defers.
+ */
+interface DeferralScope extends DeferralSet {
+    /**
+     * `$$id`s of `loaders`: the loaders that cannot call ctx.rendered(). The
+     * speculative set on every request: a loader an intent prefetch runs is
+     * still run by a speculative prefetch's fill, where its handler does not.
+     */
+    readonly loaderIds: ReadonlySet<string>;
+    /**
+     * What an intent prefetch defers: the scope with every `"intent"` flag
+     * read as unflagged. Absent when no flag is `"intent"`: the scope itself.
+     */
+    readonly intent?: DeferralSet;
+}
 interface DeferralUnit {
     readonly index: number;
     readonly ids: readonly string[];
@@ -69,6 +82,11 @@ interface DeferralUnit {
 /** Per match: InternalHandlerContext._prefetchDeferral. */
 export interface PrefetchDeferral {
     readonly scope: DeferralScope;
+    /**
+     * What this request defers: `scope`, or `scope.intent` for an intent
+     * prefetch. The ctx.rendered() guards read `scope`.
+     */
+    readonly defers: DeferralSet;
     /**
      * "prefetch": deferral replaces execution. "fill": the request that follows
      * an adopted prefetch; a held segment is skipped outright. Unset on every
@@ -151,7 +169,7 @@ export interface DeferredLoader {
 /**
  * The deferral scope of a matched chain, memoized on its leaf entry (entries
  * are per-isSSR manifest objects, replaced on HMR). EMPTY_SCOPE when nothing
- * in the tree declares `prefetch: false`.
+ * in the tree declares `prefetch: false` or `prefetch: "intent"`.
  */
 export declare function resolveDeferralScope(entries: readonly EntryData[]): DeferralScope;
 /**
@@ -164,10 +182,8 @@ export declare function resolveDeferralScope(entries: readonly EntryData[]): Def
  */
 export declare function resolveInterceptDeferralScope(intercept: InterceptEntry): DeferralScope;
 /**
- * Which half of the feature a partial request is, if either (`fill` and
- * `prefetch` are requestKind's answer). `prefetch` is a speculative prefetch
- * only: an intent prefetch defers nothing, like the navigation it starts
- * early (R16). Both halves are GETs: a request of
+ * The kind a partial request plans its deferral as, if any (requestKind's
+ * answer, filtered). Both halves of the feature are GETs: a request of
  * another method that carries either marker is a normal request. A prefetch
  * defers only on a plain GET navigation: an action re-renders what it
  * changed, and a shell capture is never a prefetch whatever the request that
@@ -175,20 +191,22 @@ export declare function resolveInterceptDeferralScope(intercept: InterceptEntry)
  * capture runs the full match): each one states its own reason.
  */
 export declare function partialDeferralMode(request: {
-    fill: boolean;
-    prefetch: boolean;
+    kind: RequestKind | undefined;
     method: string;
     isAction: boolean;
     isShellCapture: boolean;
-}): PrefetchDeferral["mode"];
+}): RequestKind | undefined;
 export declare const NOTHING_HELD: ReadonlySet<string>;
 /**
  * The plan for one match, or undefined when the tree declares no flag and the
  * request is not a fill (the common case: nothing to carry). `held` is the
  * client's segment ids as the request listed them. `scope` is the chain's
  * unless the request resolves an intercept (resolveInterceptDeferralScope).
+ * An intent prefetch plans as a prefetch over `scope.intent`: a tree whose
+ * flags are all `"intent"` defers nothing in it, and its response is the
+ * navigation's (no `_payloadDeferred`, so no source scope).
  */
-export declare function planPrefetchDeferral(entries: readonly EntryData[], mode: PrefetchDeferral["mode"], matched: {
+export declare function planPrefetchDeferral(entries: readonly EntryData[], requested: RequestKind | undefined, matched: {
     pr?: boolean;
     od?: boolean;
 }, cacheScope: CacheScope | null | undefined, held?: ReadonlySet<string>, scope?: DeferralScope): PrefetchDeferral | undefined;

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

@@ -3,6 +3,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { ReactNode } from "react";
 import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn, TransitionConfig } from "../types";
 import type { ContextVar } from "../context-var.js";
+import type { PrefetchFlag } from "../prefetch-markers.js";
 import { type WarmContext } from "../prerender/warm-request.js";
 /**
  * Performance metric entry for a single measured operation
@@ -91,13 +92,13 @@ export type EntryPropDatas = {
 export type EntryPropRender = {
     loading?: ReactNode | false;
     /**
-     * loading(fallback, { prefetch: false }) with a renderable fallback: a
-     * speculative prefetch defers what the fallback covers while the entry's
+     * loading(fallback, { prefetch: false | "intent" }) with a renderable
+     * fallback: a prefetch defers what the fallback covers while the entry's
      * segment is new to the client
      * (router/segment-resolution/prefetch-deferral.ts). Set on both DSL
      * evaluations, whatever `ssr` did to `loading`.
      */
-    loadingPrefetch?: false;
+    loadingPrefetch?: PrefetchFlag;
     /**
      * loading(fallback, { ssr: false }), on both DSL evaluations; a document
      * then sets `loading` to false (applyDocumentModeLoading).
@@ -137,11 +138,11 @@ export type LoaderEntry = {
      */
     bake?: true;
     /**
-     * loader(Def, { prefetch: false }): a speculative prefetch defers this
+     * loader(Def, { prefetch: false | "intent" }): a prefetch defers this
      * registration while its segment is new to the client
      * (router/segment-resolution/prefetch-deferral.ts).
      */
-    prefetch?: false;
+    prefetch?: PrefetchFlag;
     /**
      * The declaring layout's / parallel's / cache()'s include scope, for the
      * loader body's `ctx.reverse(".name")` (its DSL kickoff carries it,

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

@@ -45,6 +45,13 @@
  *     lane production's Back uses (useNavigation() idle), with the loader
  *     data current then. The prefetch request, its decode and the HTTP cache
  *     are e2e territory.
+ *   - useLoader().load() and a refreshGroup refresh reach the loader endpoint:
+ *     renderRoute answers a GET for `_rsc_loader=<id>` with the last value the
+ *     test gave that loader (the render seeds or respondToLoads()),
+ *     unencoded; a pending Promise holds the answer until it settles, and a
+ *     rejection is the loader's error. Needs the testing kit's
+ *     `@vitejs/plugin-rsc/browser` alias (rangoTestAliases). A load() with params
+ *     is answered with a loaderError; a body and non-GET loads are not answered.
  *   - 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", and a
@@ -428,8 +435,10 @@ export interface TestRouterHandle {
     /**
      * Re-render the current location, as router.refresh() does: a spec's
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
+     * `options.loaders` is the loader data the response carries, merged over
+     * the render-time seeds as in navigate().
      */
-    refresh(): Promise<void>;
+    refresh(options?: Pick<RenderRouteOptions, "loaders">): Promise<void>;
     /**
      * Prefetch `url`, as a `<Link>` hover or viewport trigger does: the page is
      * kept with the loader data its response would carry now (the render-time
@@ -469,6 +478,17 @@ export interface TestRouterHandle {
     action(options?: Pick<RenderRouteOptions, "loaders"> & {
         keepClientCache?: boolean;
     }): Promise<void>;
+    /**
+     * Set what the loader endpoint answers from now on: a later
+     * `useLoader().load()` or refreshGroup refresh of each loader resolves to
+     * its value (a pending Promise holds the answer, a rejection is the
+     * loader's error). Renders nothing; the page on screen keeps its data.
+     *
+     * @example
+     * router.respondToLoads({ loaders: [[CartLoader, { count: 3 }]] });
+     * fireEvent.click(getByText("Refresh")); // load(): count 3
+     */
+    respondToLoads(options: Pick<RenderRouteOptions, "loaders">): void;
     /**
      * The background revalidations a click on a stale prefetch started, in
      * order: the page's pathname and search, and the segment ids the request