@rangojs/router 0.33.2 → 0.34.1

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

@@ -3,7 +3,7 @@ import {
   prefetchDirect,
   prefetchQueued,
   schedulePrefetchWhenRouterIdle
-} from "./chunk-3B7CKBRO.js";
+} from "./chunk-MWOHBDPM.js";
 import {
   findTsFiles,
   firstCodeMatchIndex,
@@ -1386,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-J2BGDKQ4.js → client-urls-projection-4Q5EQDAL.js}

@@ -10,8 +10,8 @@ import {
   refreshRecordedClientUrlProjections,
   resolveClientUrlsSource,
   scanForClientUrlModules
-} from "./chunk-YP4HENIU.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-O6KQ5KO2.js");
+    const mod = await import("./runtime-discovery-RY6NMQM3.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-O6KQ5KO2.js → runtime-discovery-RY6NMQM3.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-BOHXBOR7.js");
+  const { createTempRscServer } = await import("./temp-rsc-server-F7AHOPV4.js");
   const { createDiscoveryState } = await import("./state-ACD2MGKJ.js");
-  const { discoverClientUrlProjections } = await import("./client-urls-projection-J2BGDKQ4.js");
+  const { discoverClientUrlProjections } = await import("./client-urls-projection-4Q5EQDAL.js");
   const {
     isFrameworkPlugin,
     pickForwardedRunnerConfig,

package/dist/bin/{temp-rsc-server-BOHXBOR7.js → temp-rsc-server-F7AHOPV4.js}

@@ -27,8 +27,8 @@ import {
   propertyKeyIs,
   recordClientUrlsModule,
   unwrapExpression
-} from "./chunk-YP4HENIU.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.2",
+  version: "0.34.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

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

@@ -28,6 +28,10 @@
  *     cancelled on resubscribe so a StrictMode / transition remount does not
  *     reclaim a bucket that is about to be reused, and is held until any
  *     in-flight load settles.
+ *   - Owned buckets (one reader's private refresh-group bucket,
+ *     `useLoader(L, { refreshGroup })` without a key) are sticky while that
+ *     reader is mounted and dropped like an ephemeral bucket once it leaves:
+ *     no other reader names the bucket, and a remount takes a new one.
  *
  * Each router's NavigationStore owns one (navigation-store.ts), and hooks reach
  * it through NavigationStoreContext: the router store is the single source of
@@ -79,6 +83,13 @@ export interface SubscribeOptions {
      * subscriber attaches, and from then on resets via `clearFamily`.
      */
     ephemeral?: boolean;
+    /**
+     * When true, the bucket belongs to this subscriber alone (a private
+     * refresh-group bucket, which no other reader names): it is reset by
+     * `clearFamily` while subscribed, and dropped after the subscriber leaves
+     * even when sticky. Read at unsubscribe, so pass it on every subscribe.
+     */
+    owned?: boolean;
     /**
      * Cross-loader refresh group name(s). Tags this bucket so `refreshGroups(name)`
      * can refresh it alongside buckets of other loaders. A bucket may be tagged
@@ -130,8 +141,8 @@ export declare class LoaderStore {
      * Subscribe to entry changes for `bucketKey`.
      * Returns an unsubscribe function. A sticky bucket's entry is kept around even
      * after the last subscriber leaves so that an in-flight `load()` can still
-     * commit if the consumer remounts. An ephemeral bucket is dropped once its
-     * last subscriber leaves (deferred, see maybeScheduleRefcountClear).
+     * commit if the consumer remounts. An ephemeral or owned bucket is dropped
+     * once its last subscriber leaves (deferred, see maybeScheduleRefcountClear).
      */
     subscribe(bucketKey: string, cb: () => void, options?: SubscribeOptions): () => void;
     private addToGroup;
@@ -149,14 +160,14 @@ export declare class LoaderStore {
      */
     refreshGroups(groups: string | string[]): Promise<void>;
     /**
-     * Schedule a deferred drop for an ad-hoc (never-sticky) bucket whose last
-     * subscriber just left. Deferred to a microtask so a StrictMode / transition
-     * remount that resubscribes in the same tick cancels it.
+     * Schedule a deferred drop for an ad-hoc (never-sticky) or owned bucket
+     * whose last subscriber just left. Deferred to a microtask so a StrictMode /
+     * transition remount that resubscribes in the same tick cancels it.
      */
     private maybeScheduleRefcountClear;
     /** Remove a bucket entry entirely and prune it from its family/group indexes. */
     private dropBucket;
-    /** Drop an ephemeral bucket that settled with no subscribers left. */
+    /** Drop an ephemeral or owned bucket that settled with no subscribers left. */
     private dropIfSettled;
     /**
      * Returns the current snapshot for `bucketKey`. Stable reference between
@@ -205,7 +216,8 @@ export declare class LoaderStore {
      * Reset a single bucket entry. Bumps `latestRequestId` so any in-flight
      * `load()` whose promise is still pending will fail its gate when it resolves
      * and be dropped — prevents pre-navigation loads from clobbering the new
-     * route's context. The entry itself is kept (sticky-bucket semantics).
+     * route's context. The entry itself is kept (sticky-bucket semantics),
+     * unless it was only waiting for that request to be dropped.
      */
     clear(bucketKey: string): void;
     /**

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/match-context.d.ts

@@ -112,6 +112,7 @@ import type { CacheScope } from "../cache/cache-scope.js";
 import type { EntryData, InterceptSelectorContext, MetricsStore } from "../server/context.js";
 import type { HandlerContext, ResolvedSegment } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { PrevPage } from "./navigation-snapshot.js";
 import type { InterceptResult } from "./router-context.js";
 import type { ResolutionPassInput } from "./segment-resolution/resolution-pass.js";
 import type { ActionContext } from "./types.js";
@@ -130,7 +131,10 @@ export interface MatchContext<TEnv = any> {
     heldBoundary?: string;
     prevUrl: URL;
     prevParams: Record<string, string>;
+    /** The match of the page left: the intercept's URL while one is open. */
     prevMatch: RouteMatchResult | null;
+    /** The page an open intercept's slot was rendered for. */
+    interceptPrev: PrevPage;
     matched: RouteMatchResult;
     manifestEntry: EntryData;
     entries: EntryData[];
@@ -169,6 +173,14 @@ export interface MatchContext<TEnv = any> {
 export declare function rendersLive(ctx: Pick<MatchContext, "isAction" | "stale">): boolean;
 /** This match as the input of a revalidating resolution pass (resolution-pass.ts). */
 export declare function resolutionPassInput<TEnv>(ctx: MatchContext<TEnv>): ResolutionPassInput<TEnv>;
+/**
+ * This match as the input of the pass that resolves its intercept's slot: its
+ * held segments compare with the intercept's own URL (`interceptPrev`), not
+ * with the source page under it. From /item/2 over /list/1, a link to /item/1
+ * compared with the source's params would read as param-equal and keep item
+ * 2's slot.
+ */
+export declare function interceptPassInput<TEnv>(ctx: MatchContext<TEnv>): ResolutionPassInput<TEnv>;
 /**
  * Mutable state that flows through the pipeline
  */

package/dist/types/router/navigation-snapshot.d.ts

@@ -1,10 +1,27 @@
 import type { RouteMatchResult } from "./pattern-matching.js";
+/** A page held segments were rendered for: what their revalidation compares with. */
+export interface PrevPage {
+    url: URL;
+    params: Record<string, string>;
+}
 export interface NavigationSnapshot {
+    /**
+     * `prevUrl` and `prevParams`: the page the held page segments were rendered
+     * for. That is the page left, or the source page while an intercept is open
+     * (`hasInterceptSource`).
+     */
     prevUrl: URL;
     /** The visitor's URL of the page left, when `prevUrl` is its rewrite target. */
     prevVisitorUrl: URL | null;
     prevParams: Record<string, string>;
+    /** The match of the page left: the intercept's URL while one is open. */
     prevMatch: RouteMatchResult | null;
+    /**
+     * The page an open intercept's slot was rendered for: the intercept's own
+     * URL (match-context.ts interceptPassInput). Equals `prevUrl`/`prevParams`
+     * when the request names no intercept source.
+     */
+    interceptPrev: PrevPage;
     interceptContextUrl: URL;
     interceptContextMatch: RouteMatchResult | null;
     clientSegmentIds: string[];

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/serve-shell-request.d.ts

@@ -66,13 +66,13 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * `result.replayStatus`.
      *
      * `prefetch: true` sends the speculative kind a viewport or render
-     * `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false`
-     * loaders and `loading()` entries are deferred: `result.readDeferred()`
-     * lists them. A hover's or `prefetch()`'s intent prefetch defers nothing;
-     * serve it with `prefetch: true` and `headers: { "X-Rango-Prefetch":
-     * "intent" }`, which `prefetch: true` leaves as given. `fill: true`
-     * sends the request the browser follows an adopted prefetch with
-     * (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
+     * `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so loaders and
+     * `loading()` entries flagged `prefetch: false` or `"intent"` are deferred:
+     * `result.readDeferred()` lists them. A hover's intent prefetch defers
+     * `false` only; serve it with `prefetch: true` and `headers: {
+     * "X-Rango-Prefetch": "intent" }`, which `prefetch: true` leaves as given.
+     * `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`. `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