@rangojs/router 0.31.0 → 0.33.0

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

@@ -6,11 +6,25 @@
  * requests; the server responds with `Vary: X-Rango-State`, so the browser HTTP
  * cache keys responses by (URL, X-Rango-State value).
  *
- * Value format: `{buildVersion}:{invalidationTimestamp}`
+ * Value format: `{buildVersion}:{invalidationTimestamp}[:{write}]`
  * - Build version: the router's document version. It changes when a deploy
  *   changes the router's server code or the client assets, busting all cached
  *   prefetches at boot; a deploy that changes neither keeps them.
- * - Timestamp rotates on invalidation (server action, invalidateClientCache).
+ * - Timestamp rotates on invalidation (invalidateClientCache, either seat).
+ * - Write: bumped by the response of a server action without a directive (its
+ *   `Set-Cookie`, server side, so a no-JS action bumps it too); left out while
+ *   0. It changes the `X-Rango-State` every tab and every reload sends, so
+ *   responses the browser HTTP cache holds from before the write miss.
+ *
+ * The client's in-memory comparisons read only `{buildVersion}:{timestamp}`
+ * (`stateEpoch`): the prefetch cache keys, the action fence's rotation check,
+ * the external-rotation observer below and the cross-tab adopt. A write-only
+ * change is soft: prefetches and history entries are marked stale and nothing
+ * is flushed. The tab that ran the action marks its own when it lands
+ * (navigation-store.ts markStaleSoftAndBroadcast) and tells the tabs that
+ * share a segment with it. Any other tab marks its own when a read sees the
+ * write part change (the write observer below), so a tab that ignores the
+ * broadcast or has crossTabSync off does not serve a pre-write prefetch fresh.
  *
  * Storage is a session cookie named by the server-resolved name passed to
  * initRangoState (`{prefix}_{routerId}`, default prefix `rango-state`). The
@@ -27,10 +41,20 @@
  */
 /**
  * Register the observer invoked when a read detects an EXTERNAL rotation (a
- * sibling tab, a server `Set-Cookie`, or a cookie clear). Self-rotations
+ * sibling tab, a server `Set-Cookie`, or a cookie clear) of the
+ * `{version}:{timestamp}` part. A change to the write part alone (a server
+ * action's write) goes to the write observer instead. Self-rotations
  * (invalidateRangoState) update the mirror synchronously and never fire it.
  */
 export declare function setRangoStateObserver(observer: ((value: string) => void) | null): void;
+/**
+ * Register the observer invoked when a read sees the write part change while
+ * the `{version}:{timestamp}` part stays: a server action's response, in this
+ * tab or another, bumped it in the shared jar since the last read. Every read
+ * updates the mirror, and a prefetch reads the state before it starts, so a
+ * prefetch sent with the new value is never one this observer sees as old.
+ */
+export declare function setRangoStateWriteObserver(observer: (() => void) | null): void;
 /** Return the resolved cookie name used to namespace cross-tab messages. */
 export declare function getRangoStateCookieName(): string;
 /**
@@ -49,10 +73,15 @@ export declare function initRangoState(version: string, stateCookieName?: string
 export declare function getRangoState(): string;
 /**
  * Invalidate the Rango state (self-rotation). Called when the client clears its
- * prefetch caches (e.g. via the server-action bridge). Rotates the timestamp,
+ * prefetch caches (e.g. invalidateClientCache()). Rotates the timestamp,
  * keeps the version, writes the cookie, and updates the mirror synchronously so
  * the external-rotation observer is NOT triggered by our own write.
  */
 export declare function invalidateRangoState(): void;
-/** Adopt the state carried by a same-origin cache-invalidation broadcast. */
+/**
+ * Adopt the state carried by a same-origin cache-invalidation broadcast when
+ * its timestamp is newer (a rotation). The write part is not compared: a soft
+ * broadcast's newer write is already in the shared jar, and a value that
+ * differs only there is no rotation to adopt.
+ */
 export declare function adoptRangoState(value: string): boolean;

package/dist/types/browser/react/Link.d.ts

@@ -66,23 +66,29 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      * keyed on Rango state + target URL. This is correct for routes whose
      * response shape doesn't depend on where the user navigates from.
      *
-     * Set `":source"` when this Link's response would legitimately differ
-     * based on the source page — typically when the target route (or one
-     * of its layouts) uses a custom `revalidate()` handler that reads
-     * `currentUrl` / `currentParams`, and the wildcard entry would
-     * therefore serve the wrong diff to a navigation from a different
-     * source.
+     * Set `":source"` to scope every prefetch of this Link to the page that
+     * sent it, when its response would differ by source page in a way the
+     * server cannot see.
      *
-     * A route an intercept targets is scoped to the source automatically
-     * (server-side `x-rsc-prefetch-scope: source`), whether or not the
-     * intercept applies from this page: the modal and the full page are
-     * both source-specific. Every other route stays shared, so `":source"`
-     * is only needed for custom revalidation logic.
+     * The server scopes a prefetch to its source automatically
+     * (`x-rsc-prefetch-scope: source`) when an intercept targets the route or
+     * the source page, whether or not it applies (the modal and the full page
+     * are both source-specific), when the answer defers a `prefetch: false`
+     * unit the source does not hold, when a `revalidate()` of the target read
+     * `currentUrl` and kept the segment, and when a kept answer sends no
+     * segment. A `revalidate()` that read `currentParams` or `fromRouteName`
+     * and kept the segment, or a prerendered target that keeps segments on
+     * equal params (`storedEntrySends`), shares the answer between the pages
+     * with equal values of what was read (`x-rsc-prefetch-scope: params`,
+     * #1331). Every other response stays shared. Use the key
+     * for what the server does not track: `context` in a `revalidate()`, or
+     * a `Referer` read.
+     *
+     * A source-scoped entry is keyed by the source page's full URL, query
+     * and hash included, so every page prefetches the link again.
      *
      * @example
      * ```tsx
-     * // Route uses a `revalidate()` that branches on currentUrl — opt in
-     * // so prefetches don't bleed across source pages.
      * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
      * ```
      */

package/dist/types/browser/react/location-state-shared.d.ts

@@ -269,7 +269,8 @@ export declare function isLocationStateDefinition(value: unknown): value is Loca
  */
 export declare function isLocationStateEntry(value: unknown): value is LocationStateEntry;
 /**
- * Resolve state entries into a flat object for history.state
+ * Resolve state entries into a flat object for history.state. One slot per
+ * definition: a later entry of the same definition replaces an earlier one.
  */
 export declare function resolveLocationStateEntries(entries: LocationStateEntry[]): Record<string, unknown>;
 export {};

package/dist/types/browser/types.d.ts

@@ -600,7 +600,15 @@ export interface NavigationStore {
      */
     getPageHistoryKeys(historyKey: string): string[];
     markHistoryCacheStale(): void;
+    /**
+     * Mark history entries and prefetches stale without a broadcast: a cookie
+     * read saw another write (rango-state.ts setRangoStateWriteObserver).
+     */
+    markCachesStaleAfterWrite(): void;
+    /** A server action without a directive: mark stale, soft broadcast. */
     markCacheAsStaleAndBroadcast(): void;
+    /** The client seat of invalidateClientCache(): flush, rotate, broadcast. */
+    invalidateCacheAndBroadcast(): void;
     clearHistoryCache(): void;
     setCrossTabRefreshCallback(callback: () => void): void;
     getInterceptSourceUrl(): string | null;
@@ -637,6 +645,16 @@ export interface FetchPartialOptions {
      * to a prefetch cache or the HTTP cache, and it cancels no prefetch.
      */
     fill?: boolean;
+    /**
+     * Whether a prefetch a server action marked stale (prefetch/cache.ts
+     * isPrefetchStale) may answer this navigation. Only a click sets it: it
+     * revalidates its page once it settled (navigation-bridge.ts navigate,
+     * partial-update.ts onStalePrefetch). For any other caller (Back/Forward on
+     * a history-cache miss, leaving an intercept) a stale stored entry is a
+     * miss, and a stale in-flight one is dropped and fetched again, so no path
+     * that never revalidates commits pre-write data.
+     */
+    acceptStalePrefetch?: boolean;
 }
 /**
  * Result of a partial fetch including stream completion tracking
@@ -654,6 +672,13 @@ export interface FetchPartialResult {
      * fallbacks stream as usual.
      */
     fullyPrefetched?: boolean;
+    /**
+     * True when the payload is a prefetch a server action marked stale after it
+     * was fetched (prefetch/cache.ts isPrefetchStale). The click commits it as
+     * any prefetch; the navigation then revalidates its page once it settled,
+     * as Back onto a stale history entry does (navigation-bridge.ts navigate).
+     */
+    stalePrefetch?: boolean;
 }
 /**
  * Navigation client for fetching RSC payloads

package/dist/types/build/generate-route-types.d.ts

@@ -4,5 +4,5 @@ export { generatePerModuleTypesSource, generateRouteTypesSource, } from "./route
 export { DEFAULT_EXCLUDE_PATTERNS, type ScanFilter, createScanFilter, findTsFiles, isInSkippedScanDir, } from "./route-types/scan-filter.js";
 export { writePerModuleRouteTypes, writePerModuleRouteTypesForFile, } from "./route-types/per-module-writer.js";
 export { type UnresolvableReason, type UnresolvableInclude, extractIncludesWithDiagnostics, } from "./route-types/include-resolution.js";
-export { extractUrlsFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
+export { extractUrlsFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, isRoutableSourceFile, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
 export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/dist/types/build/route-types/include-resolution.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found" | "unresolvable-basename";
+export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found" | "unresolvable-basename" | "unresolvable-routes";
 export interface UnresolvableInclude {
     pathPrefix: string;
     namePrefix: string | null;
@@ -25,6 +25,14 @@ export interface ScanMemo {
     blockSourceFiles: Map<string, ts.SourceFile>;
 }
 export declare function createScanMemo(): ScanMemo;
+export declare function isUrlsDefinitionCall(node: ts.CallExpression, aliases?: ReadonlySet<string>): boolean;
+/**
+ * Local names that `import { urls as u, clientUrls as cu } from
+ * "@rangojs/router"` (or `/client`) binds to urls()/clientUrls(), so a renamed
+ * import is read like the plain name. Other modules' exports are not guessed
+ * at: a `urls` from elsewhere is read only under its own name.
+ */
+export declare function collectUrlsImportAliases(sourceFile: ts.SourceFile): ReadonlySet<string>;
 /**
  * Extract include() calls with diagnostics for unresolvable ones.
  * Returns both resolved includes (identifier second args) and unresolvable

package/dist/types/build/route-types/router-processing.d.ts

@@ -1,5 +1,6 @@
 import { type ScanFilter } from "./scan-filter.js";
 import { type UnresolvableInclude } from "./include-resolution.js";
+export declare function isRoutableSourceFile(name: string): boolean;
 export declare function findNestedRouterConflict(routerFiles: string[]): {
     ancestor: string;
     nested: string;
@@ -22,11 +23,12 @@ export type UrlsExtractionResult = {
 };
 /**
  * Extract the url patterns from a router file using AST.
- * Detects four patterns:
+ * Detects these patterns, in either mount (`.routes(x)` or `urls: x`):
  *   1. createRouter(...).routes(variableName)
  *   2. createRouter({ urls: variableName, ... })
  *   3. createRouter(...).routes(({ path, ... }) => [...])
  *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
+ *   5. createRouter(...).routes(urls(({ path, ... }) => [...])), and clientUrls()
  * Returns either a variable name or an inline code block.
  */
 export declare function extractUrlsFromRouter(code: string): UrlsExtractionResult | null;

package/dist/types/cache/cache-key-utils.d.ts

@@ -97,9 +97,10 @@ export declare const KEY_PART_PREFIX = "key:";
  * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
  * results of the scope's cache() chain, outermost first, then its default
  * parts: the keyGenerator results of enclosing scopes on another store
- * (#974) and, for a route record key, the scope's own part: without a
+ * (#974) and, for a route record key, the scope's own parts: without a
  * `key()` of its own, its default key (or its store's keyGenerator result,
- * #970); with one, the default key's request kind (`doc`, `partial` or
+ * #970, then the request kind when that result does not start with it,
+ * #1298); with one, the default key's request kind (`doc`, `partial` or
  * `intercept:<intercept>`, routeRecordKind in cache-scope.ts).
  *
  * Key scheme invariant (#975). A `key()` result is often request input,
@@ -119,7 +120,9 @@ export declare const KEY_PART_PREFIX = "key:";
  * - one `key()` part is the key; two or more parts are joined by `|`,
  *   `key()` parts first;
  * - a lone default part stays raw: with no `key()` on the chain the record
- *   key is the default key or the store's keyGenerator result, unchanged.
+ *   key is the default key or the store's keyGenerator result, unchanged
+ *   when that result starts with its request kind, else that result and
+ *   the kind composed (`items|doc`).
  *
  * Why nothing collides: the router's default keys (`doc:`, `partial:`,
  * `intercept:`, `response:<type>:`) never start with `key:` and hold a `:`.
@@ -128,11 +131,12 @@ export declare const KEY_PART_PREFIX = "key:";
  * Among composed keys, splitting on `|` recovers each part, a part's kind
  * (a `key:` prefix, or no `:` at all) and its value. A request kind part is
  * a default key's prefix without the URL after it, so it never equals a
- * default key part; a keyGenerator part can equal it (`doc`) only when the
- * keyGenerator returns a constant, which already gives every URL one record.
- * Pinned by the collision probe in
- * src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator result is
- * the store's own namespace, as before.
+ * default key part. A raw keyGenerator record key starts with its kind and
+ * holds a `:`, so it never equals a composed one, and two kinds' prefixes
+ * differ; a result without its kind is composed with it, never prefixed,
+ * since `doc:` + `x` would be the raw result `doc:x`. Pinned by the
+ * collision probes in src/cache/__tests__/cache-scope-chain.test.ts. A
+ * keyGenerator result is the store's own namespace, as before.
  *
  * Shared with the testing helper `shellCacheKey`, so a test builds the
  * production partition.

package/dist/types/cache/cache-scope.d.ts

@@ -200,8 +200,10 @@ export declare class CacheScope {
      * replaces the URL part, and its store's keyGenerator does not run. It
      * appends `kind` instead (routeRecordKind): the `key()` decides which
      * requests of one kind share a record, never that a document, a
-     * navigation and an intercept navigation do. With no partition part it is
-     * resolveDefaultKey alone. With a `key()` on the chain but no request
+     * navigation and an intercept navigation do. A keyGenerator result that
+     * does not start with its kind gets `kind` after it too (ownParts). With
+     * no partition part it is resolveDefaultKey alone, or that result and
+     * `kind` composed. With a `key()` on the chain but no request
      * context it rejects (keyWithoutContextError). `partitionedPrefix`
      * prefixes a key built from partition parts only (the response family's
      * `response:`, which passes no `kind`: a response route answers every

package/dist/types/cache/cf/cf-cache-types.d.ts

@@ -369,19 +369,23 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
     /**
      * Custom key generator applied to all cache operations.
      * Receives the full RequestContext (including env) and the default-generated key.
-     * Return value becomes the final cache key (unless route overrides with `key` option).
+     * The return value is the cache key (unless route overrides with `key`
+     * option), except that a route record keeps its request kind: a result that
+     * does not start with `defaultKey`'s prefix (`doc:`, `partial:`,
+     * `intercept:<intercept>:`) gets the kind appended (see
+     * SegmentCacheStore.keyGenerator).
      *
      * Reserved prefixes: tag-invalidation markers live in the SAME KV namespace as
      * data, keyed `__tag__/<tag>` (and `__tagmarker__/<tag>` for the L1 cache). A
      * returned key must NOT begin with `__tag__/` or `__tagmarker__/`, or it can
      * collide with a tag marker and corrupt invalidation. The documented
-     * prepend-style generators below are safe.
+     * generators below start with `defaultKey` and are safe.
      *
      * @example Using headers for user segmentation
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
      *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
-     *   return `${segment}:${defaultKey}`;
+     *   return `${defaultKey}|${segment}`;
      * }
      * ```
      *
@@ -389,7 +393,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
      *   const region = ctx.env.REGION || 'us';
-     *   return `${region}:${defaultKey}`;
+     *   return `${defaultKey}|${region}`;
      * }
      * ```
      *
@@ -397,7 +401,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
      *   const locale = cookies().get('locale')?.value || 'en';
-     *   return `${locale}:${defaultKey}`;
+     *   return `${defaultKey}|${locale}`;
      * }
      * ```
      */

package/dist/types/cache/document-cache-policy.d.ts

@@ -12,7 +12,15 @@ export interface CacheDirectives {
 /**
  * Check if response should be cached based on Cache-Control headers
  */
-export declare function shouldCacheResponse(response: Response, requestCtx?: Pick<RequestContext, "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation">): CacheDirectives | null;
+export declare function shouldCacheResponse(response: Response, requestCtx?: Pick<RequestContext, "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadSourceScoped" | "_payloadVisitorLocation" | "_documentLocationState">): CacheDirectives | null;
+/**
+ * Whether a response carries one client's state, which a stored copy would
+ * replay to that client's later requests: a per-client signal header (a state
+ * cookie rotation, `x-rango-keep-cache`) or location state. The stored
+ * prefetch Cache-Control (rsc/request-stages.ts) is not sent on
+ * one.
+ */
+export declare function carriesClientState(response: Response, requestCtx: Pick<RequestContext, "_locationState" | "_documentLocationState">): boolean;
 /**
  * Whether this cache will store the response the current render produces, as
  * far as the render can tell: the middleware runs it (a MISS or a stale

package/dist/types/cache/memory-segment-store.d.ts

@@ -46,13 +46,14 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
     defaults?: CacheDefaults;
     /**
      * Custom key generator applied to all cache operations.
-     * Receives the full RequestContext and the default-generated key.
+     * Receives the full RequestContext and the default-generated key. A route
+     * record keeps its request kind (see SegmentCacheStore.keyGenerator).
      *
      * @example
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
      *   const locale = cookies().get('locale')?.value || 'en';
-     *   return `${locale}:${defaultKey}`;
+     *   return `${defaultKey}|${locale}`;
      * }
      * ```
      */

package/dist/types/cache/segment-codec.d.ts

@@ -88,8 +88,8 @@ export declare function serializeSegments(segments: ResolvedSegment[], onError?:
  * cached with the route record).
  *
  * The loading "null" sentinel decodes here (not on the consumer): loading:null
- * must survive as null, and shipping the raw sentinel would change the
- * deduplicateLoaderSegments loading-presence check.
+ * must survive as null, and shipping the raw sentinel would hand renderSegments
+ * a truthy `loading`, the fallback tree shape (docs/tree-structure.md).
  */
 export declare function fragmentSegments(data: SerializedSegmentData[]): Promise<ResolvedSegment[]>;
 /**

package/dist/types/cache/shell-snapshot.d.ts

@@ -201,7 +201,7 @@ export interface ShellLoaderSeedEntry {
  * Deserializations run in parallel; a record that fails to decode is skipped
  * and reported to `onUndecodable`: its loader runs instead, which a document
  * HIT has already committed a prelude against, so serveShellHit retires the
- * entry (dc-t89). Returns undefined when the snapshot carries no loader
+ * entry. Returns undefined when the snapshot carries no loader
  * records, without touching the Flight codec (kept lazy for cold paths and
  * non-RSC configs).
  */

package/dist/types/cache/types.d.ts

@@ -83,16 +83,21 @@ export interface SegmentCacheStore<TEnv = unknown> {
     /**
      * Custom key generator applied to all cache operations using this store.
      * Receives the full RequestContext and the default-generated key.
-     * Return value becomes the final cache key (unless route overrides with `key` option).
+     * The return value is the cache key (unless route overrides with `key`
+     * option), with a route record's request kind appended when it does not
+     * start with that kind (below).
      *
      * Resolution priority:
      * 1. Route-level `key` function (replaces the URL part; the request kind stays)
      * 2. Store-level `keyGenerator` (modifies default key)
      * 3. Default key generation (prefix:pathname:params)
      *
-     * Keep `defaultKey` in the result: its prefix names the request kind (a
-     * document, a navigation or an intercept navigation), whose records hold
-     * different segments. A result without it gives every kind one record.
+     * A route record keeps its request kind (a document, a navigation or an
+     * intercept navigation), whose records hold different segments: the kind
+     * is `defaultKey`'s prefix (`doc:`, `partial:`, `intercept:<intercept>:`),
+     * and a result that does not start with it gets the kind appended as a
+     * key part of its own. Build on `defaultKey` (`${defaultKey}|${segment}`)
+     * and the result is the record key byte for byte.
      *
      * Return `defaultKey` unchanged to leave a request unpartitioned. An empty
      * string is not a key: where the result partitions a nested cache() on
@@ -104,7 +109,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
      *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
-     *   return `${segment}:${defaultKey}`;
+     *   return `${defaultKey}|${segment}`;
      * }
      * ```
      *
@@ -112,7 +117,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
      *   const region = ctx.env.REGION || 'us';
-     *   return `${region}:${defaultKey}`;
+     *   return `${defaultKey}|${region}`;
      * }
      * ```
      *
@@ -120,7 +125,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
      *   const locale = cookies().get('locale')?.value || 'en';
-     *   return `${locale}:${defaultKey}`;
+     *   return `${defaultKey}|${locale}`;
      * }
      * ```
      */

package/dist/types/cache/vercel/vercel-cache-store.d.ts

@@ -125,7 +125,8 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
     defaults?: CacheDefaults;
     /**
      * Custom key generator applied to all cache operations (region/locale/user
-     * segmentation). Receives the request context and the default key.
+     * segmentation). Receives the request context and the default key. A route
+     * record keeps its request kind (see SegmentCacheStore.keyGenerator).
      */
     keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     /**

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

@@ -48,8 +48,9 @@ export interface ClientUrlLoaderRecord {
      */
     readonly ssr?: false;
     /**
-     * loader(Def, { prefetch: false }): a prefetch of the route, or of an
-     * intercept's target from its source, defers this loader and the click
+     * 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.
      */
@@ -118,12 +119,13 @@ export interface ClientUrlHelpers {
      * holes).
      *
      * Pass `{ prefetch: false }` to keep this loader out of the route's
-     * prefetches (see {@link LoaderOptions}): an in-group click still shows
+     * 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 prefetch of the
-     * intercept from its source, as in urls().
+     * below it. Inside intercept() it defers the loader in a viewport or
+     * render 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/prefetch-markers.d.ts

@@ -7,6 +7,15 @@
  */
 /** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
 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.
+ */
+export declare const PREFETCH_INTENT = "intent";
 /**
  * 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/prefetch-source-scope.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The source group of a prefetch answer a revalidate() rule kept from the
+ * page being left (#1331). Shared by the server, which reports
+ * the group in `x-rsc-prefetch-scope: params; <label>` (rsc/rsc-rendering.ts),
+ * and the browser, which stores the answer under that label and rebuilds it
+ * from the page on screen to look it up (browser/prefetch/cache.ts).
+ * Dependency free, like prefetch-markers.ts: the browser must not import the
+ * server modules that record the reads (router/source-reads.ts).
+ *
+ * Why a label is enough: a rule's decision depends on the source page only
+ * through what it read. Two pages with equal values of everything the kept
+ * rules read run every rule the same way, so one answer serves both.
+ */
+/** What the revalidate() rules that kept a segment read of the source page. */
+export interface SourceReads {
+    /**
+     * `currentParams` was read. Its key set is then part of the group: a rule
+     * can test a key's presence (`in`, `Object.keys`) without reading a value.
+     */
+    keys: boolean;
+    /**
+     * Each `currentParams` value read; a spread or JSON.stringify reads all.
+     * Non-empty only with `keys`: a value is read through `currentParams`.
+     */
+    params: Set<string>;
+    /** `fromRouteName` was read. */
+    route: boolean;
+    /** `currentUrl` was read: the answer is the exact page's. */
+    url: boolean;
+}
+/** The page a label describes: the source on the server, the screen in the browser. */
+export interface SourcePage {
+    params: Readonly<Record<string, string | undefined>>;
+    /** The public route name (route-name.ts publicRouteName). */
+    routeName: string | undefined;
+}
+/** What a label reads, without the values: one per kind of rule set. */
+export interface SourceShape {
+    keys: boolean;
+    route: boolean;
+    /** Sorted. */
+    names: readonly string[];
+}
+/** `x-rsc-prefetch-scope` value prefix of a params-grouped answer. */
+export declare const PARAMS_SCOPE_PREFIX = "params; ";
+export declare function createSourceReads(): SourceReads;
+export declare function hasSourceReads(reads: SourceReads): boolean;
+/** Union `from` into `into`. */
+export declare function mergeSourceReads(into: SourceReads, from: SourceReads): void;
+export declare function shapeOfReads(reads: SourceReads): SourceShape;
+/**
+ * The label of `page` under `shape`: `&`-joined, `$k=<keys>` first, then
+ * `$r[=<route>]`, then `<name>[=<value>]` per read param, sorted. A missing
+ * value has no `=`. Names and values are URI-encoded, so a `$` entry never
+ * collides with a param (encodeURIComponent encodes `$`).
+ */
+export declare function formatSourceLabel(shape: SourceShape, page: SourcePage): string;
+/**
+ * The label of an `x-rsc-prefetch-scope` value, or undefined when the value
+ * is not a params scope.
+ */
+export declare function paramsScopeLabel(header: string | null | undefined): string | undefined;
+/** The shape of a label formatSourceLabel wrote. */
+export declare function parseSourceShape(label: string): SourceShape;
+/** A stable id of a shape, for indexing. */
+export declare function sourceShapeId(shape: SourceShape): string;

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

@@ -231,9 +231,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * loader(RecommendationsLoader),  // still streams behind loading()
      * ```
      *
-     * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
-     * prefetch skips it and the click that adopts the prefetch fetches it in
-     * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+     * 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
      * client does not have yet: a loader the client already holds runs in the
      * prefetch when it revalidates.
      *
@@ -255,14 +256,16 @@ 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 prefetches
+     * // Keep everything behind this fallback out of viewport and render
+     * // prefetches (a hover prefetch runs it)
      * loading(<Skeleton />, { prefetch: false })
      * ```
      * @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 prefetch then skips the whole unit: the
+     *   segment is new to the client. A viewport or render prefetch then skips
+     *   the whole unit (a hover prefetch runs it): 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

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

@@ -9,6 +9,11 @@ import type { LocationStateEntry } from "../browser/react/location-state-shared.
  * Supports an optional state parameter to carry location state through the
  * redirect. On the target page, state can be read via useLocationState()
  * (use { flash: true } in createLocationState for read-once flash messages).
+ * On a client navigation or action the state travels in the redirect's
+ * payload. On a document request (a page load, a no-JS form post) it travels
+ * in a one-shot cookie the target's document request reads and clears, as
+ * JSON: give it plain JSON data there. `{ external: true }` carries none.
+ * Two entries of the same definition keep only the last.
  *
  * @param url - The URL to redirect to
  * @param statusOrOptions - HTTP status code (default: 302) or options object