@rangojs/router 0.33.2 → 0.34.0

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-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-O6KQ5KO2.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-BOHXBOR7.js");
+  const { createTempRscServer } = await import("./temp-rsc-server-EUNKRFJD.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-EUNKRFJD.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.0",
   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/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/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

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

@@ -7,6 +7,7 @@ import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
 import type { UseItems, LoaderUseItem } from "../route-types.js";
 import type { DefaultEnv, DefaultReverseRouteMap, DefaultVars } from "./global-namespace.js";
 import type { RequestScope } from "./request-scope.js";
+import type { PrefetchOption } from "../prefetch-markers.js";
 /**
  * Context passed to loader functions during execution
  *
@@ -182,13 +183,14 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
 export type LoaderOptions = {
     ssr?: boolean;
     /**
-     * `prefetch: false` keeps this loader out of speculative prefetches. A
-     * viewport or render `<Link>` prefetch (a partial request with
-     * `X-Rango-Prefetch: 1`) does not execute it; the payload marks it
-     * deferred. A hover prefetch and `useRouter().prefetch()`
-     * (`X-Rango-Prefetch: intent`) count as intent to click and run it, so a
-     * click after a hover needs no follow-up request. A document request and a
-     * navigation with no prefetch to adopt run it as usual.
+     * `prefetch: false` keeps this loader out of every `<Link>` prefetch: a
+     * prefetch (a partial request with `X-Rango-Prefetch`) does not execute
+     * it; the payload marks it deferred. `prefetch: "intent"` keeps it out of
+     * speculative prefetches only: a viewport or render prefetch
+     * (`X-Rango-Prefetch: 1`) defers it, and a hover prefetch or
+     * `useRouter().prefetch()` (`X-Rango-Prefetch: intent`) runs it, so a click
+     * after a hover needs no follow-up request for it. 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>`
@@ -213,7 +215,7 @@ export type LoaderOptions = {
      * request only deferred work and middleware run, so values a held handler
      * would have set with `ctx.set()` are not visible.
      */
-    prefetch?: boolean;
+    prefetch?: PrefetchOption;
 };
 /**
  * Options for fetchable loaders

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

@@ -8,6 +8,7 @@ import type { ResponseHandler, ResponseHandlerContext, TextResponseHandler } fro
 import type { UnnamedRoute, LocalOnlyInclude, PathOptions, UrlPatterns, IncludeOptions } from "./pattern-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
 import type { ClientUrlPatterns } from "../client-urls/types.js";
+import type { PrefetchOption } from "../prefetch-markers.js";
 /**
  * Base path function signature for defining routes with URL patterns.
  */
@@ -161,10 +162,10 @@ export type PathHelpers<TEnv> = {
      * 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 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.
      */
@@ -173,9 +174,9 @@ export type PathHelpers<TEnv> = {
      * 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 viewport and render
-     * prefetches (a hover prefetch runs it), when this entry's segment is new
-     * to the client: the entry's handler, its loaders,
+     * false }` keeps what the fallback covers out of prefetches (`"intent"`:
+     * viewport and render prefetches only, see {@link LoaderOptions}), 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
@@ -189,7 +190,7 @@ export type PathHelpers<TEnv> = {
      */
     loading: (component: ReactNode | (() => ReactNode), options?: {
         ssr?: boolean;
-        prefetch?: boolean;
+        prefetch?: PrefetchOption;
     }) => LoadingItem;
     /**
      * Attach an error boundary to catch errors in this segment