@rangojs/router 0.32.0 → 0.33.0

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

@@ -71,12 +71,21 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      * server cannot see.
      *
      * The server scopes a prefetch to its source automatically
-     * (`x-rsc-prefetch-scope: source`) when an intercept targets the route,
-     * whether or not it applies from this page (the modal and the full page
-     * are both source-specific), and when a `revalidate()` of the target
-     * read `currentParams`, `currentUrl` or `fromRouteName` and kept the
-     * segment: that diff is the source page's (#1331). Every other response
-     * stays shared.
+     * (`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

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" | "_documentLocationState">): 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/router/intercept-resolution.d.ts

@@ -7,20 +7,15 @@
 import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
 import type { ResolvedSegment } from "../types";
 import type { ResolutionPass } from "./segment-resolution/resolution-pass.js";
+import { type InterceptResult } from "./router-context.js";
 /**
  * Check if an intercept's when conditions are satisfied.
  * All when() functions must return true for the intercept to activate.
  * If no when() conditions are defined, the intercept always activates.
  * A selector that throws yields the conservative default, no intercept (the
  * full page renders), and is logged; it never fails the request.
- *
- * During action revalidation, when() is NOT evaluated.
- */
-export declare function evaluateInterceptWhen(intercept: InterceptEntry, selectorContext: InterceptSelectorContext | null, isAction: boolean): boolean;
-/**
- * Find an intercept for the target route by walking up the entry chain.
- * Returns the first (innermost) matching intercept along with the entry that defines it.
  */
+export declare function evaluateInterceptWhen(intercept: InterceptEntry, selectorContext: InterceptSelectorContext | null): boolean;
 /**
  * Collect every intercept TARGET route name reachable from an origin entry —
  * the same chain walk findInterceptForRoute() performs when this location is
@@ -33,10 +28,29 @@ export declare function evaluateInterceptWhen(intercept: InterceptEntry, selecto
  * loses its optimistic loading, never the reverse.
  */
 export declare function collectInterceptTargetNames(fromEntry: EntryData | null): string[];
-export declare function findInterceptForRoute(targetRouteKey: string, fromEntry: EntryData | null, selectorContext?: InterceptSelectorContext | null, isAction?: boolean): {
-    intercept: InterceptEntry;
-    entry: EntryData;
-} | null;
+/**
+ * The intercept for the target route, with the entry that declares it.
+ * `targetRouteKeys` are the names it may be declared for, in precedence
+ * order: the route's own name, then its local name inside include()
+ * (match-api.ts). A navigation, or an action with no `held`, takes the first
+ * along the chain from `fromEntry` up under the first name that has one: on a
+ * navigation, the first whose when() passes; on an action, the first, when()
+ * not evaluated.
+ *
+ * An action given `held` (the request's segment ids) re-renders the intercept
+ * on screen: one whose slot id the client holds, null when it holds none. Its
+ * candidates are collected under every name in one walk, the route's own
+ * name's first: a held id under the own name (a parallel() default of the
+ * slot's name) must not win before the local name is looked at. One held:
+ * that one, when() not evaluated, so an open intercept stays open when its
+ * when() would now reject. Several held (intercepts on one entry that fill one
+ * slot share its id, as does a parallel() slot of that name): the ones whose
+ * slot has no parallel() default on their entry, if any (a default holds its
+ * slot id whether or not an intercept is open there). One left: that one,
+ * when() not evaluated. Else the first whose when() passes against the
+ * action's intercept source, else the first.
+ */
+export declare function findInterceptForRoute(targetRouteKeys: string | readonly string[], fromEntry: EntryData | null, selectorContext?: InterceptSelectorContext | null, isAction?: boolean, held?: ReadonlySet<string>): InterceptResult | null;
 /** The segment id of `intercept`'s slot on `parentEntry`. */
 export declare function interceptSlotId(parentEntry: EntryData, intercept: InterceptEntry): string;
 /**

package/dist/types/router/match-context.d.ts

@@ -177,6 +177,7 @@ export interface MatchPipelineState {
     cachedSegments?: ResolvedSegment[];
     cachedMatchedIds?: string[];
     shouldRevalidate?: boolean;
+    storedStale?: boolean;
     cacheSource?: "runtime" | "prerender";
     segments: ResolvedSegment[];
     matchedIds: string[];

package/dist/types/router/match-handlers.d.ts

@@ -11,7 +11,7 @@ export interface MatchHandlerDeps<TEnv = any> {
     matchApiDeps: MatchApiDeps<TEnv>;
     defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined;
     findMatch: (pathname: string, ms?: any) => any;
-    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext | null, isAction: boolean) => {
+    findInterceptForRoute: (routeKeys: string | readonly string[], parentEntry: EntryData | null, selectorContext: InterceptSelectorContext | null, isAction: boolean, held?: ReadonlySet<string>) => {
         intercept: InterceptEntry;
         entry: EntryData;
     } | null;

package/dist/types/router/prefetch-cache-ttl.d.ts

@@ -1,9 +1,10 @@
 /**
  * Resolve the prefetch cache TTL once, at router init, into the values the
  * rest of the router consumes: seconds, and milliseconds for the client-side
- * in-memory prefetch cache (shipped in payload metadata). Prefetch responses
- * carry no Cache-Control: the browser HTTP cache would keep a prefetch whose
- * render failed after its 200 went out (#1170).
+ * in-memory prefetch cache (shipped in payload metadata). A prefetch with a
+ * live part carries no Cache-Control: the browser HTTP cache would keep a
+ * prefetch whose render failed after its 200 went out (#1170). One answered
+ * from storage carries storedPrefetchCacheControl.
  *
  * `false` disables prefetch caching (seconds 0). A non-finite input
  * (NaN/Infinity, e.g. from an env-derived number that failed to parse) is
@@ -22,3 +23,10 @@ export interface ResolvedPrefetchCacheTTL {
     ms: number;
 }
 export declare function resolvePrefetchCacheTTL(rawTTL: number | false | undefined): ResolvedPrefetchCacheTTL;
+/**
+ * The Cache-Control of a prefetch answer with nothing live in it
+ * (`_servedFromStorage`): the browser HTTP cache keeps it as long
+ * as the in-memory prefetch cache would. Undefined when prefetch caching is
+ * off.
+ */
+export declare function storedPrefetchCacheControl(ttlMs: number): string | undefined;

package/dist/types/router/router-context.d.ts

@@ -33,7 +33,7 @@ export interface RouterContext<TEnv = any> {
     };
     getMetricsStore: () => MetricsStore | undefined;
     createCacheScope: (cacheConfig: any, parent: CacheScope | null) => CacheScope | null;
-    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext, isAction: boolean) => InterceptResult | null;
+    findInterceptForRoute: (routeKeys: string | readonly string[], parentEntry: EntryData | null, selectorContext: InterceptSelectorContext, isAction: boolean, held?: ReadonlySet<string>) => InterceptResult | null;
     /** The segment walker; a full match passes freshPassInput (FRESH). */
     resolveAllSegments: (pass: ResolutionPassInput<TEnv>, entries: EntryData[], walk: RevalidatingWalkOptions) => Promise<{
         segments: ResolvedSegment[];