@rangojs/router 0.33.2 → 0.34.0

package/dist/vite/index.js

@@ -111,6 +111,17 @@ var init_debug = __esm({
   }
 });
 
+// src/prefetch-markers.ts
+var PREFETCH_HEADER, PREFETCH_INTENT, PREFETCH_FAILED_ROW;
+var init_prefetch_markers = __esm({
+  "src/prefetch-markers.ts"() {
+    "use strict";
+    PREFETCH_HEADER = "X-Rango-Prefetch";
+    PREFETCH_INTENT = "intent";
+    PREFETCH_FAILED_ROW = ":H_0\n";
+  }
+});
+
 // src/internal-debug.ts
 var INTERNAL_RANGO_DEBUG;
 var init_internal_debug = __esm({
@@ -725,17 +736,6 @@ var init_validate_redirect_origin = __esm({
   }
 });
 
-// src/prefetch-markers.ts
-var PREFETCH_HEADER, PREFETCH_INTENT, PREFETCH_FAILED_ROW;
-var init_prefetch_markers = __esm({
-  "src/prefetch-markers.ts"() {
-    "use strict";
-    PREFETCH_HEADER = "X-Rango-Prefetch";
-    PREFETCH_INTENT = "intent";
-    PREFETCH_FAILED_ROW = ":H_0\n";
-  }
-});
-
 // src/browser/response-adapter.ts
 function isForeignRouterId(response, expectedId) {
   const got = response.headers.get("X-RSC-Router-Id");
@@ -4594,6 +4594,9 @@ import * as React4 from "react";
 // src/server/context.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
+// src/errors.ts
+init_prefetch_markers();
+
 // src/cache/cache-key-utils.ts
 function routerKeyPrefix(routerId2) {
   return `${encodeURIComponent(routerId2)}@`;
@@ -5363,6 +5366,9 @@ function insertSegments(node, segments, index, leafBase, paramNames) {
   }
 }
 
+// src/client-urls/client-urls.ts
+init_prefetch_markers();
+
 // src/browser/react/use-navigation.ts
 import { useContext as useContext9, useEffect as useEffect7, useRef as useRef5 } from "react";
 
@@ -5924,6 +5930,9 @@ import { jsx as jsx9 } from "react/jsx-runtime";
 // src/server/root-layout.tsx
 import { Fragment as Fragment3, jsx as jsx10 } from "react/jsx-runtime";
 
+// src/route-definition/dsl-helpers.ts
+init_prefetch_markers();
+
 // src/prerender.ts
 var PRERENDER_PASSTHROUGH = Object.freeze({
   __brand: "prerenderPassthrough"
@@ -6318,8 +6327,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))
@@ -7330,7 +7344,7 @@ function resolveVersionsFrom(table, routerId2) {
 // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.33.2",
+  "version": "0.34.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/app-structure/large-app.md

@@ -706,6 +706,9 @@ Rules of thumb:
   never become clicks: activity feeds, analytics panels, reviews below the
   fold, a list behind a tab.
 - Do not flag what the likely click needs first: the page's main content.
+- Flag a loader worth starting on hover `prefetch: "intent"` instead: viewport
+  and render prefetches skip it, and a hover or `useRouter().prefetch()` runs
+  it, so that click needs no fill for it.
 - Read a flagged loader inside its own `<Suspense>`; with no boundary, React
   keeps the page being left on screen until the fill answers.
 - A same-route click (`/app/projects/1` to `/app/projects/2`) prefetches a

package/skills/client-urls/SKILL.md

@@ -132,7 +132,7 @@ flow into the generated route map, so `href()`, `ctx.reverse()` and
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see `/ppr` → The loader lane rule); no response variants. Use callback may contain `loader()`, `loading()`, `transition()` |
 | `layout()`     | `layout(Component, () => [...])` — children are required and must contain at least one `path()`; may also hold `loader()`, `loading()`, `intercept()`, nested `layout()`                         |
-| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false, prefetch: false }, use?)` — see below                                                                                                          |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false, prefetch: false \| "intent" }, use?)` — see below                                                                                              |
 | `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait                                            |
 | `revalidate()` | Valid **inside a loader() use callback only**; runs on the server (the build hoists it out of the `"use client"` module)                                                                         |
 | `transition()` | Inside a `path()` use callback only (at most one). ViewTransition config plus a browser-run `when` predicate (see `/view-transitions`); same-route navs in a group already hold without it       |
@@ -623,25 +623,27 @@ shell, such as a `useActionState` form (React suspends it once to encode its
 action), is in the first flush too: the router gives React up to three more
 turns before it, and none when the document is already complete.
 
-## `prefetch: false` — keep a loader out of speculative prefetches
+## `prefetch: false` — keep a loader out of prefetches
 
 A `<Link>` prefetch of a group route runs its loaders. Flag the expensive one
-and a viewport or render prefetch skips it. A hover prefetch, and
-`useRouter().prefetch()`, is intent to click: it runs the loader, and the
-click sends no fill (`/loader` → "`prefetch: false`").
+`prefetch: false` and every prefetch skips it. Flag it `prefetch: "intent"`
+and only a viewport or render prefetch skips it: a hover prefetch, and
+`useRouter().prefetch()`, is intent to click, runs it, and the click sends
+no fill for it (`/loader` → "`prefetch: false`").
 
 ```tsx
 path("/product/:slug", ProductPage, { name: "product" }, () => [
   loader(PriceLoader),
-  loader(ReviewsLoader, { prefetch: false }), // kept out of viewport prefetches
+  loader(RelatedLoader, { prefetch: "intent" }), // kept out of viewport prefetches
+  loader(ReviewsLoader, { prefetch: false }), // kept out of every prefetch
   loading(<ProductSkeleton />),
 ]),
 ```
 
 A click inside the group still shows the destination at once. With a
-viewport or render prefetch received, the URL and the other loaders' data move with the click
+prefetch received, the URL and the other loaders' data move with the click
 too, `useOutlet().pending` ends with that commit, and one follow-up request
-(the fill) runs only the flagged loaders. Read the flagged loader inside its
+(the fill) runs only the loaders it skipped. Read the flagged loader inside its
 own `<Suspense>` to show the page and that fallback at once; with no boundary
 React holds the page being left until the fill answers, as it would with no
 prefetch. Same rules as on a server route (`/loader` → "`prefetch: false`"):
@@ -660,8 +662,9 @@ rest of the destination; otherwise it is held. A same-route click
 - `loading()` in `clientUrls()` takes no options, and a flagged `loading()`
   on a server layout above the group defers nothing for the group's routes.
 - On an `intercept()` loader the flag works as in `urls()`: an in-group
-  viewport or render prefetch of the intercept's target defers it, and the
-  click opens the modal at once with one fill for it; a hover's runs it.
+  prefetch of the intercept's target defers it, and the click opens the
+  modal at once with one fill for it; a hover's runs a loader marked
+  `"intent"`.
 - With `ssr: false` on a `ppr` group route the flag works as on a server
   route: deferred unless the prefetch serves the loader from a pin of a
   document-captured shell (`/ppr` → "`prefetch: false` on a `ppr` route").

package/skills/intercept/SKILL.md

@@ -69,6 +69,7 @@ export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) =
 | Click link `/shop/product/abc`                        | `<ProductModal />` in `@modal`, background preserved |
 | Direct URL `/shop/product/abc`, or a reload           | Full `<ProductPage />` page                          |
 | `router.refresh()`, or another tab's action           | Full `<ProductPage />` page, as a reload             |
+| Link inside the intercept to another intercepted URL  | That intercept, over the same source page            |
 | Back from the open intercept                          | The intercept closes; the source page stays          |
 | Back/Forward onto the intercept's entry               | The intercept over its source page                   |
 | The same, uncached, from a page other than the source | Full `<ProductPage />` page, as a document load      |
@@ -311,13 +312,16 @@ intercepted: it gets the full page.
 ### `prefetch: false` on an intercept's loaders
 
 `loader(Def, { prefetch: false })` inside `intercept()` keeps that loader out
-of a viewport or render prefetch of the target from the source page (a hover
-prefetch runs it, and its click opens the modal complete with no fill):
+of every prefetch of the target from the source page. `{ prefetch: "intent" }`
+keeps it out of viewport and render prefetches only: a hover prefetch runs
+it, and when every flagged loader of the modal is `"intent"` its click opens
+the modal complete with no fill:
 
 ```typescript
 intercept("@modal", "product", <ProductModal />, () => [
   loader(ProductLoader),
-  loader(ReviewsLoader, { prefetch: false }), // skipped in a viewport prefetch
+  loader(PhotosLoader, { prefetch: "intent" }), // skipped in a viewport prefetch, runs on hover
+  loader(ReviewsLoader, { prefetch: false }), // skipped in every prefetch
   loading(<ModalSkeleton />),
 ]);
 ```
@@ -330,7 +334,7 @@ click shows nothing until its response. The modal's loaders resolve together,
 so its `loading()` shows until the last one arrives. A handler that reads the
 flagged loader with `ctx.use()` before its first `await` (or one with no
 `loading()`) gets it run in the prefetch instead: one run, no fill for it.
-`loading(…, { prefetch: false })` inside `intercept()` defers nothing.
+A `prefetch` option on `loading()` inside `intercept()` defers nothing.
 
 A prefetch of a route an intercept targets, or one sent from such a route, is
 stored per source page, whether or not the intercept applies from that page

package/skills/links/SKILL.md

@@ -619,14 +619,15 @@ A prefetch is a navigation sent early (a partial request with an
 `X-Rango-Prefetch` header), and by default the server renders everything for
 it: every handler and every loader. That is the point, a click then commits
 without a request, but it is also forty renders for a grid of forty links.
-Keep the expensive part out of speculative (viewport, render) prefetches on
-the route, not on the link:
+Keep the expensive part out of prefetches on the route, not on the link:
 
 ```tsx
-// skip one loader
+// skip one loader in every prefetch
 loader(ReviewsLoader, { prefetch: false }),
 // skip what the fallback covers
 loading(<OrdersSkeleton />, { prefetch: false }),
+// skip it in viewport and render prefetches only: a hover runs it
+loader(RelatedLoader, { prefetch: "intent" }),
 ```
 
 A click that adopts such a prefetch commits what was prefetched, shows the
@@ -635,13 +636,15 @@ is new to the page is deferred: a segment already on screen (the layout of the
 section you are in, the route itself on `/product/a` to `/product/b`) is
 prefetched as usual.
 
-A hover prefetch is treated as intent and runs everything, flagged work
-included (`X-Rango-Prefetch: intent`, where a viewport or render prefetch
-sends `1`); so does `useRouter().prefetch()`. Its click commits complete with
-no extra request. A hover sends that request only when the link has no
-prefetch cached or in flight: on a viewport link whose prefetch has already
-answered, it sends nothing, and the click fetches the deferred part as above.
-See
+A hover prefetch is treated as intent (`X-Rango-Prefetch: intent`, where a
+viewport or render prefetch sends `1`); so is `useRouter().prefetch()`. It
+runs the work marked `prefetch: "intent"` and still skips the work marked
+`prefetch: false`, so on a route whose flags are all `"intent"` its click
+commits complete with no extra request. A hover sends that request only when
+the link has no prefetch cached or in flight: on a viewport link whose
+prefetch has already answered, it sends nothing, and the click fetches the
+deferred part as above. Middleware that skips side effects in prefetches
+should test for the header's presence, not for `=== "1"`. See
 `/loader` → "`prefetch: false`" and `/route` → "`loading()` options". To stop
 a link or a whole section from prefetching at all, use the `prefetch` prop or
 `data-prefetch-scope` above.
@@ -668,8 +671,8 @@ The answer is page-only (`x-rsc-prefetch-scope: source`) when:
 
 - An intercept targets the route, or the page that sent the prefetch,
   whether or not it applies here.
-- The answer defers a `prefetch: false` loader or `loading()` that the page
-  does not show yet (a viewport or render prefetch; a hover's defers nothing).
+- The answer defers a `prefetch: false` or `prefetch: "intent"` loader or
+  `loading()` that the page does not show yet.
 - A `revalidate()` on the target read `currentUrl` and kept its segment.
 - A `revalidate()` on the route, or on a segment inside its `path()`, read
   the page being left and kept the segment through the route's default

package/skills/loader/SKILL.md

@@ -1191,20 +1191,22 @@ The costs and constraints:
 Also available in `clientUrls()` route groups (`/client-urls`), where the
 loader-heavy shape makes it most useful.
 
-## `prefetch: false` — Keep a Loader Out of Speculative Prefetches
+## `prefetch: false` and `prefetch: "intent"` — Keep a Loader Out of Prefetches
 
 A `<Link>` prefetch is a navigation sent early: the server renders every
 handler and every loader for it. With the default `"viewport"` strategy that
 means a grid of forty product links runs forty copies of your slowest loader
 for pages most visitors never open. Pass `prefetch: false` to keep one loader
-out of those speculative (viewport and render) prefetches:
+out of every prefetch, or `prefetch: "intent"` to keep it out of the
+speculative ones only:
 
 ```tsx
 import { Suspense } from "react";
 
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(PriceLoader), // cheap: still runs in the prefetch
-  loader(ReviewsLoader, { prefetch: false }), // expensive: skipped in a viewport prefetch
+  loader(PriceLoader), // cheap: runs in every prefetch
+  loader(RelatedLoader, { prefetch: "intent" }), // skipped in a viewport prefetch, runs on hover
+  loader(ReviewsLoader, { prefetch: false }), // expensive: skipped in every prefetch
   loading(<ProductSkeleton />),
 ]),
 ```
@@ -1212,22 +1214,30 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 (`prefetch` sits beside `ssr` in `LoaderOptions`; combine them as
 `{ ssr: false, prefetch: false }` if you need both.)
 
-A hover is different: the visitor is about to click. A hover prefetch (on a
+| Request                                                      | unflagged  | `prefetch: false`        | `prefetch: "intent"`     |
+| ------------------------------------------------------------ | ---------- | ------------------------ | ------------------------ |
+| Document, navigation                                         | runs       | runs                     | runs                     |
+| Viewport or render prefetch (`X-Rango-Prefetch: 1`)          | runs       | skipped, filled at click | skipped, filled at click |
+| Hover, `useRouter().prefetch()` (`X-Rango-Prefetch: intent`) | runs       | skipped, filled at click | runs, no fill            |
+| A prefetch already cached or in flight when the hover lands  | used as is | used as is               | used as is               |
+
+A hover means the visitor is about to click. A hover prefetch (on a
 `"hover"`, `"viewport"` or `"adaptive"` link, or a delegated plain anchor) and
-`useRouter().prefetch()` send `X-Rango-Prefetch: intent` and run the loader
-with the rest of the page, so the click commits complete and sends no second
-request. A hover sends its prefetch only when the link has none cached or in
-flight: on a link a viewport prefetch already answered, the hover sends
-nothing and the click fills the deferred loader as below. The cost is plain:
-each hover that misses the prefetch cache runs the loader, so a pointer
-passing over a list of `"hover"` links runs it once per link. Touch devices
-have no hover (`"adaptive"` resolves to viewport there) and keep the fill.
-
-What happens in a speculative prefetch:
-
-- A **viewport or render prefetch** of the route does not run the loader and
-  does not read its `cache()`; the payload marks it deferred. The rest of the
-  page prefetches as usual.
+`useRouter().prefetch()` run a loader marked `"intent"` with the rest of the
+page; when every flagged loader and `loading()` on the route is marked
+`"intent"`, the click commits complete and sends no second request. A hover
+sends its prefetch only when the link has none cached or in flight: on a link
+a viewport prefetch already answered, the hover sends nothing and the click
+fills the deferred loader as below. The cost of `"intent"` is plain: each
+hover that misses the prefetch cache runs the loader, so a pointer passing
+over a list of `"hover"` links runs it once per link. Keep a loader that is
+too expensive for that on `false`. Touch devices have no hover (`"adaptive"`
+resolves to viewport there) and keep the fill.
+
+What happens in a prefetch that skips the loader:
+
+- The prefetch does not run the loader and does not read its `cache()`; the
+  payload marks it deferred. The rest of the page prefetches as usual.
 - Only on a loader new to the page. A loader already on screen is never
   deferred: if its revalidation (its `revalidate()` or the default) re-runs
   it, it runs in the prefetch with the rest of the destination, exactly as
@@ -1277,18 +1287,18 @@ function Reviews() {
 
 The limits:
 
-- **A click before its viewport prefetch has answered waits for it, then
-  fetches the deferred part.** The flag is there to keep expensive or slow
-  work out of every speculative prefetch, so that an API that is costly to
-  call is not called for every link a visitor might click. A click that comes
-  while the link's viewport or render prefetch is still in flight reuses that
-  prefetch, as it does without the
-  flag, and sends the fill when the prefetch answers. The page shows no later
+- **A click before its prefetch has answered waits for it, then fetches the
+  deferred part.** The flag is there to keep expensive or slow work out of
+  prefetches, so that an API that is costly to call is not called for every
+  link a visitor might click. A click that comes while the link's prefetch is
+  still in flight reuses that prefetch, as it does without the flag, and
+  sends the fill when the prefetch answers. The page shows no later
   than with no prefetch; the deferred part shows its fallback until the fill
   lands, and can complete later than a click with no prefetch, by up to what
   was left of the prefetch. That is the price of keeping the work out of the
-  prefetch. A click while a hover's prefetch is in flight adopts it with no
-  fill: the loader is already running in it.
+  prefetch. A click while a hover's prefetch is in flight, on a route whose
+  flags are all `"intent"`, adopts it with no fill: the loader is already
+  running in it.
 - **A navigation started before the fill answers cancels it.** It is
   cancelled when the newer navigation starts, not when that one commits. If
   the newer navigation then ends without replacing the page (a redirect the
@@ -1313,8 +1323,9 @@ The limits:
   every request kind (a document load included, so you see it the first time
   you open the page in development) if it calls `await ctx.rendered()`. The
   fill does not re-run the entry's handler, so there is no render to wait for
-  and no handle data to read. Remove `{ prefetch: false }` from the loader, or
-  stop calling `ctx.rendered()`. Pushing a handle from the loader is fine.
+  and no handle data to read. That holds for `"intent"` too, on every request.
+  Remove the `prefetch` flag from the loader, or stop calling
+  `ctx.rendered()`. Pushing a handle from the loader is fine.
 - **`ctx.set()` values from held handlers are not visible.** The fill runs the
   deferred work and middleware only. A handler or layout the client already
   holds does not run again, so a variable it set with `ctx.set()` is missing
@@ -1376,16 +1387,17 @@ The limits:
   need it), or drop the flag from a loader the page cannot render without.
 
 - **`clientUrls()` routes take it on `loader()`.** In a `clientUrls()`
-  definition `loader(Def, { prefetch: false })` works as here: a click
+  definition `loader(Def, { prefetch: false })` and `{ prefetch: "intent" }`
+  work as here: a click
   inside the group shows the destination at once, commits the prefetched
   data with the URL, and one fill runs the flagged loaders (see
   `/client-urls` → "`prefetch: false`"). A flagged `loading()` defers nothing
   on a group route, from the group or from a server layout above it.
-- **Inside `intercept()`.** In `urls()` and in `clientUrls()`, a viewport or
-  render prefetch of the intercept's target from its source page defers the
-  flagged loader (a hover's runs it, and its click sends no fill): the
-  click opens the modal at once, with its `loading()`, and one fill, sent
-  from the source, runs the loader. The page under the modal stays. With no
+- **Inside `intercept()`.** In `urls()` and in `clientUrls()`, a prefetch of
+  the intercept's target from its source page defers the flagged loader (a
+  hover's runs a loader marked `"intent"`, and its click sends no fill for
+  it): the click opens the modal at once, with its `loading()`, and one fill,
+  sent from the source, runs the loader. The page under the modal stays. With no
   `loading()` the slot is empty until the fill answers, as on a plain click
   until its response. The modal's loaders resolve together: it shows its
   `loading()` until every one has arrived. A flagged `loading()` inside
@@ -1401,13 +1413,14 @@ The limits:
   `/caching`, `/prerender`, `/ppr` → "`prefetch: false` on a `ppr` route").
 
 To skip a handler along with its loaders, flag the `loading()` instead (see
-`/route` → "`loading()` options"). `loader(Def, { prefetch: false })` accepts
-only a boolean; anything else throws `loader() prefetch must be a boolean`.
+`/route` → "`loading()` options"). `loader(Def, { prefetch })` accepts a
+boolean or `"intent"`; anything else throws
+`loader() prefetch must be a boolean or "intent"`.
 
 Test it with `serveShellRequest(router, url, { partial: { prefetch: true } })`
 and `result.readDeferred()` (see `/testing`). That is a speculative prefetch;
 add `headers: { "X-Rango-Prefetch": "intent" }` to serve a hover's, which
-defers nothing.
+runs the `"intent"` loaders and defers the `false` ones.
 
 ## Fetchable Loaders
 

package/skills/ppr/SKILL.md

@@ -1176,7 +1176,7 @@ document request captured:
 | Replays a shell a document request captured (`HIT`)    | Served from its pin, not deferred, never run; the click sends nothing |
 | Replays a navigation-only shell, or misses (cold page) | Deferred: the click sends one fill that runs it                       |
 | Serves an explicit `cache()` hit                       | Deferred: the click sends one fill that runs it                       |
-| Hover prefetch (`X-Rango-Prefetch: intent`)            | Never deferred                                                        |
+| Hover prefetch (`X-Rango-Prefetch: intent`)            | As the rows above; a loader marked `prefetch: "intent"` runs instead  |
 
 A cold prefetch still schedules the background capture that stores the
 page's navigation shell, and that capture runs the loader once. Once a

package/skills/route/SKILL.md

@@ -242,10 +242,11 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 
 `loading(fallback, options?)` takes two options:
 
-| Option            | Effect                                                                                                                                                            |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ssr: false`      | Skip the fallback on document requests; it shows on client navigations only.                                                                                      |
-| `prefetch: false` | Keep everything behind this fallback out of viewport and render prefetches (a hover prefetch runs it); the click shows the fallback and fetches that part itself. |
+| Option               | Effect                                                                                                                                    |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ssr: false`         | Skip the fallback on document requests; it shows on client navigations only.                                                              |
+| `prefetch: false`    | Keep everything behind this fallback out of every prefetch, hovers included; the click shows the fallback and fetches that part itself.   |
+| `prefetch: "intent"` | The same for viewport and render prefetches; a hover prefetch or `useRouter().prefetch()` runs it, and its click sends no second request. |
 
 ```tsx
 path("/orders", OrdersPage, { name: "orders" }, () => [
@@ -255,13 +256,17 @@ path("/orders", OrdersPage, { name: "orders" }, () => [
 ```
 
 **What `prefetch: false` defers.** The flag applies when the entry is new to
-the browser: the page the prefetch is sent from does not show it. A viewport
-or render prefetch then skips the entry's handler, its loaders, its orphan layouts and its
+the browser: the page the prefetch is sent from does not show it. A prefetch
+then skips the entry's handler, its loaders, its orphan layouts and its
 parallel slots. On a `layout()` the fallback covers the whole outlet, so every
 deeper entry is skipped with it. A parallel slot with its own flagged
 `loading()` is a separate unit: the route beside it still renders in the
 prefetch. The prefetch payload carries a placeholder for each skipped piece,
-marked deferred, with its fallback: the page's skeleton.
+marked deferred, with its fallback: the page's skeleton. `prefetch: "intent"`
+defers the same pieces in a viewport or render prefetch; a hover's prefetch
+renders them, so a route whose flags are all `"intent"` is prefetched whole
+on hover. Everything below about `false` holds for `"intent"` in the
+prefetches that defer it.
 
 **An entry the browser already holds is never deferred.** Inside a section
 whose `layout()` has a flagged `loading()`, the layout is on screen, so its
@@ -347,7 +352,7 @@ the block's work, its loaders included, out of prefetches. See `/caching`,
   flag does nothing there. The last `loading()` on an entry wins, flag
   included.
 - A loader behind the fallback cannot call `ctx.rendered()`; it throws on every
-  request kind. See `/loader` → "`prefetch: false`" for this and the other
+  request kind, for either flag. See `/loader` → "`prefetch: false`" for this and the other
   loader limits (`ctx.set()` values, late `redirect()`/`notFound()`, a loader a
   handler awaits).
 - A layout the client already holds is not deferred (its fallback would not
@@ -373,7 +378,8 @@ the block's work, its loaders included, out of prefetches. See `/caching`,
 - `clientUrls()` routes and `intercept()` ignore the flag.
 
 To defer a single loader and keep the handler in the prefetch, use
-`loader(Def, { prefetch: false })` instead (see `/loader`).
+`loader(Def, { prefetch: false })` or `{ prefetch: "intent" }` instead (see
+`/loader`).
 
 A `loading()` skeleton that has appeared stays at least about 300 ms before React reveals what replaces it (React's fallback throttle, [#1078](https://github.com/rangojs/rango/issues/1078)); see "Streaming with Suspense" in [loader](../loader/SKILL.md).
 

package/skills/testing/serve-shell-request.md

@@ -20,13 +20,13 @@ A `Prerender` route is served as in production: from the artifact `router.matchF
 
 ### Options — `ServeShellRequestOptions`
 
-| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends the speculative kind a viewport or render `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false` work is deferred; add `headers: { "X-Rango-Prefetch": "intent" }` to send a hover's or `prefetch()`'s intent prefetch instead, which defers nothing. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, 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 with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
-| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends the speculative kind a viewport or render `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false` and `prefetch: "intent"` work is deferred; add `headers: { "X-Rango-Prefetch": "intent" }` to send a hover's or `prefetch()`'s intent prefetch instead, which runs the `"intent"` work and defers the `false` work. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, 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 with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
+| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 ### Returns — `ServeShellRequestResult`
 
@@ -294,6 +294,18 @@ expect(await fill.readDeferred()).toEqual([]); // a fill defers nothing
 
 `deliveredIds` is the payload's `metadata.matched`, read from `prefetch.flight`. Count the loader's runs in your own fixture: the prefetch ran it zero times, the fill once.
 
+For a loader marked `prefetch: "intent"`, send the hover's prefetch too: it runs that loader and still defers a `prefetch: false` one beside it.
+
+```ts
+const hover = await serveShellRequest(router, "/product/1", {
+  cacheStore,
+  headers: { "X-Rango-Prefetch": "intent" },
+  partial: { from: "/", prefetch: true },
+});
+// loader(RelatedLoader, { prefetch: "intent" }) ran; ReviewsLoader is deferred.
+expect(await hover.readDeferred()).toHaveLength(1);
+```
+
 ### Intercepts
 
 A prefetch of an `intercept()`'s target from its source page defers the intercept's flagged loaders, loader segments of its slot (`${parent}.@modalD${i}.${$$id}`). The browser sends the fill of an intercept from the source, with the intercept source header: pass both.