@rangojs/router 0.32.0 → 0.33.1

package/dist/types/bin/rango.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/dist/types/browser/action-fence.d.ts

@@ -35,8 +35,28 @@
  * document. A future multi-router-in-one-document feature must not silently
  * inherit this global, cross-router cache suppression.
  */
+/**
+ * Register what runs when the fence drops holding a write no landing took:
+ * the navigation store's markCachesStaleAfterWrite (navigation-store-handle.ts).
+ */
+export declare function setUnlandedWriteHandler(handler: (() => void) | null): void;
 export declare function enterActionFence(): void;
 export declare function exitActionFence(): void;
+/** A cookie read saw an external state rotation (rango-state.ts observer). */
+export declare function noteStateRotation(): void;
+/**
+ * A cookie read saw a write-only change (rango-state.ts write observer).
+ * Returns whether the fence is up and took it; with the fence down the
+ * caller marks the caches stale itself.
+ */
+export declare function noteStateWrite(): boolean;
+/** A landing marked every cache stale: a write seen so far is covered. */
+export declare function takeStateWriteInActionFence(): void;
+/**
+ * Whether the state rotated externally since the fence went up or the last
+ * landing took it, and clear it. False with the fence down.
+ */
+export declare function takeStateRotationInActionFence(): boolean;
 export declare function isActionFenceActive(): boolean;
 /** Test-only: reset the refcount between cases. */
 export declare function __resetActionFence(): void;

package/dist/types/browser/cookie-name.d.ts

@@ -36,31 +36,72 @@ export declare function stripPerClientSignals(headers: Headers): void;
  */
 export declare function getRawCookieValue(cookieString: string | null, name: string): string | null;
 /**
- * Encode a state value for the wire: `encodeURIComponent(version):timestamp`.
- * Only the build-derived version is encoded (it is arbitrary); the `:`
- * separator and numeric timestamp stay raw, so the `{version}:{timestamp}`
- * shape survives and `:` is a legal cookie-value octet.
+ * Encode a state value for the wire: `encodeURIComponent(version):timestamp`,
+ * plus `:write` when the write part is not 0. Only the build-derived version
+ * is encoded (it is arbitrary); the `:` separators and the numeric parts stay
+ * raw, so the shape survives and `:` is a legal cookie-value octet. A value no
+ * server action has bumped keeps the two-part shape it had before the write
+ * part existed.
+ */
+export declare function encodeStateValue(version: string, timestamp: number, write?: number): string;
+/**
+ * Parsed state value. `version` is decoded; `timestamp` (the invalidation
+ * part) and `write` are the raw integers. `write` is 0 for a two-part value.
  */
-export declare function encodeStateValue(version: string, timestamp: number): string;
-/** Parsed state value. `version` is decoded; `timestamp` is the raw integer. */
 export interface StateValue {
     version: string;
     timestamp: number;
+    write: number;
 }
 /**
- * Decode a wire value back into `{version, timestamp}`. Returns null for a
- * malformed value (no `:`, empty version, or non-numeric timestamp) so callers
- * mint fresh instead of trusting garbage.
+ * Decode a wire value back into `{version, timestamp, write}`. Accepts the
+ * two-part `{version}:{timestamp}` (a value no action bumped, or one an open
+ * tab wrote before the write part existed) and the three-part
+ * `{version}:{timestamp}:{write}`. Returns null for a malformed value (no `:`,
+ * empty version, a non-numeric part, or more parts) so callers mint fresh
+ * instead of trusting garbage.
  */
 export declare function decodeStateValue(raw: string): StateValue | null;
+/**
+ * The `{version}:{timestamp}` part of a wire value: what every in-memory
+ * comparison on the client reads (the prefetch cache keys, the action
+ * fence's rotation check, the external-rotation observer). A change to it is
+ * a hard invalidation (a deploy, or invalidateClientCache() on either seat);
+ * a change to the write part alone is a server action's write, which marks
+ * caches stale and flushes nothing. The full value, write part included, is
+ * what requests send as `X-Rango-State`, so the browser HTTP cache (Vary)
+ * misses after every write. A raw cut, no decode: the version is
+ * percent-encoded, so the second `:` is always the write separator.
+ */
+export declare function stateEpoch(raw: string): string;
 /**
  * Mint a fresh state value whose timestamp is strictly greater than the previous
  * one, so a re-mint inside the same millisecond (or a backward clock step) still
  * differs from the current value. `prevRaw` is the current wire value (the
  * client's in-memory mirror, or the server's inbound header/cookie) or null; its
- * timestamp is the floor. Shared by both seats so the monotonic guard lives once.
+ * timestamp is the floor. The write part starts over (left out): the new
+ * timestamp alone makes the value one no response was cached under. Shared by
+ * both seats so the monotonic guard lives once.
  */
 export declare function mintStateValue(version: string, prevRaw: string | null): string;
+/**
+ * Bump the write part of `prevRaw`, keeping its version and timestamp: what
+ * the response of a server action without a directive sets. Keeping the
+ * version keeps the bump soft for a client still on another build (a form
+ * posted from a document served before a deploy); its own boot handles the
+ * deploy. Returns null when `prevRaw` is absent or malformed: a client with
+ * no state value sends no `X-Rango-State` and has nothing in the HTTP cache
+ * keyed by one.
+ *
+ * The new write part must be one no response was cached under. It is
+ * strictly greater than the previous one, and it is the current time in
+ * microseconds with random low digits: two actions that start from the same
+ * value (two tabs, or two in flight in one tab) can run in the same server
+ * millisecond (a Worker's clock does not move between I/O), and the second
+ * response must not set the value the first one set, under which a prefetch
+ * between them may have been cached with the second write missing.
+ */
+export declare function bumpStateWrite(prevRaw: string | null): string | null;
 /**
  * Attribute string for the state cookie. Session cookie (no Max-Age/Expires),
  * Path=/ (whole app), SameSite=Lax (sent on top-level navigations), and Secure

package/dist/types/browser/invalidate-client-cache.d.ts

@@ -1,12 +1,14 @@
 /**
  * Client seat of `invalidateClientCache()` (the `default` export condition).
  *
- * Makes the current client behave as if a server action had just completed:
- * the history cache is marked stale (SWR), the prefetch map is flushed, the
- * state rotates, and sibling tabs are broadcast to — the same
- * `markCacheAsStaleAndBroadcast()` path the server-action bridge uses. This is
- * the gentler mark-stale (not hard-clear) behavior, so Back renders the cached
- * entry instantly and revalidates.
+ * The full client invalidation, more than a server action without a
+ * directive does: the history cache is marked stale (SWR), the prefetch map
+ * is flushed (in-flight prefetches aborted, visible links prefetch again), the
+ * state rotates, and sibling tabs are broadcast to, which adopt the new state
+ * and flush too (`invalidateCacheAndBroadcast()`). A directive-free action
+ * only marks history and prefetches stale and rotates nothing
+ * (`markCacheAsStaleAndBroadcast()`). History is marked stale, not cleared, so
+ * Back renders the cached entry instantly and revalidates.
  */
 export declare function invalidateClientCache(): void;
 /**

package/dist/types/browser/navigation-bridge.d.ts

@@ -1,6 +1,6 @@
 import type { NavigationBridge, NavigationBridgeConfig, NavigationStore } from "./types.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
-import type { EventController } from "./event-controller.js";
+import type { EventController, NavigationEntry } from "./event-controller.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
 export { createNavigationTransaction };
 /**
@@ -22,6 +22,41 @@ export interface NavigationBridgeDelegatedPrefetchOptions {
 }
 /** Register delegated anchor prefetch with the production bridge wiring. */
 export declare function setupNavigationBridgeDelegatedPrefetch(store: NavigationStore, eventController: EventController, getVersion: () => string | undefined, options?: NavigationBridgeDelegatedPrefetchOptions): () => void;
+/**
+ * The request a stale-prefetch revalidation makes (scheduleStalePrefetch-
+ * Revalidation): the ids it holds, and the intercept and action error
+ * boundary on screen.
+ */
+export interface StalePrefetchRevalidation {
+    segmentIds: string[];
+    intercept: {
+        isIntercept: boolean;
+        sourceUrl?: string;
+    };
+    boundary: string | undefined;
+}
+/**
+ * A click that adopted a prefetch a server action marked stale
+ * (prefetch/cache.ts isPrefetchStale) committed the pre-write payload, as any
+ * prefetched click commits. Once that navigation settled
+ * (NavigationEntry.settled: its commit, any `prefetch: false` fill and its
+ * stream, so this never supersedes the click nor cuts a response
+ * that arrived short), `revalidate` runs the page's request in
+ * Back's lane (the bridge's revalidateInBackground), with the ids on screen
+ * and the action error boundary it shows held, as Back onto a stale entry
+ * does.
+ *
+ * The entry is marked stale first, so a Back onto it revalidates when this
+ * one never ran or was left. Nothing runs when the click did not commit, or
+ * when the page moved since (a newer navigation aborts the click's entry, a
+ * shallow one moves the history key) or another navigation is open. An
+ * action in flight does not hold it back, as it does not hold Back's: its
+ * follow-up, when it owes one, starts a navigation that supersedes this one.
+ *
+ * Exported so renderRoute (testing/render-route.tsx) drives these guards and
+ * this plan rather than a copy of them.
+ */
+export declare function scheduleStalePrefetchRevalidation(store: Pick<NavigationStore, "getCachedSegments" | "getHistoryKey" | "updateCacheHandleData">, eventController: Pick<EventController, "getUnsettledNavigation">, entry: Pick<NavigationEntry, "settled">, historyKey: string, revalidate: (request: StalePrefetchRevalidation) => void): void;
 /**
  * Create a navigation bridge for handling client-side navigation
  *

package/dist/types/browser/navigation-client.d.ts

@@ -1,4 +1,23 @@
 import type { NavigationClient, RscBrowserDependencies } from "./types.js";
+import { type DecodedPrefetch } from "./prefetch/cache.js";
+import type { SourcePage } from "../prefetch-source-scope.js";
+/**
+ * The completed prefetch a navigation adopts: the one stored under its
+ * source key, else one stored for a group of source pages the page is in
+ * (`paramsKeys`, paramsCandidateKeys), else the one every source page
+ * shares. None when the navigation cannot use a prefetch. A stale one only
+ * when `acceptStale` (FetchPartialOptions.acceptStalePrefetch).
+ */
+export declare function consumeStoredPrefetch(canUsePrefetch: boolean, sourceKey: string, paramsKeys: readonly string[], wildcardKey: string, acceptStale?: boolean): {
+    entry: DecodedPrefetch | null;
+    hitKey: string | null;
+};
+/**
+ * Whether a navigation from `page` may serve an in-flight prefetch it
+ * adopted through the wildcard key: not one the server scoped to its own
+ * source page, nor one scoped to a group of source pages `page` is not in.
+ */
+export declare function wildcardAdoptionFits(entry: DecodedPrefetch, page: SourcePage | null): boolean;
 /**
  * Create a navigation client for fetching RSC payloads
  *

package/dist/types/browser/navigation-store-handle.d.ts

@@ -7,19 +7,52 @@
  * receive it by argument: the jar-divergence observer (below) and the client
  * seat of `invalidateClientCache()` (added later).
  *
- * Dependency-light on purpose: it imports only `setRangoStateObserver` and the
- * store type, so pulling it into the default root entry does not drag the
- * navigation store into bundles that previously lacked it.
+ * Dependency-light on purpose: it imports only the action fence, the
+ * rango-state observers and the store type, so pulling it into the default
+ * root entry does not drag the navigation store into bundles that previously
+ * lacked it.
  */
 import type { NavigationStore } from "./types.js";
+import type { SourcePage } from "../prefetch-source-scope.js";
 /**
  * Register the active navigation store at boot, and wire the jar-divergence
  * observer: when a per-request cookie read detects an EXTERNAL rotation (a
  * sibling tab, a server `Set-Cookie`, or a cookie clear), mark this tab's
  * history cache stale. The history cache is not state-keyed, so the value
  * rotation alone does not reach it. No broadcast, no prefetch clear, no
- * re-rotation — the value already changed externally.
+ * re-rotation — the value already changed externally. A rotation seen while
+ * an action is in flight is recorded on the fence: the action's landing then
+ * sends the full broadcast (navigation-store.ts markCacheAsStaleAndBroadcast).
+ *
+ * A read that sees only the write part change (a server action's response,
+ * in this tab or another) marks this tab's history entries and prefetches
+ * stale, as a soft broadcast's receiver does: a tab the broadcast does not
+ * reach would otherwise serve a prefetch made before the write as fresh.
+ * While an action is in flight the write is recorded on the fence instead:
+ * the action's landing marks every cache stale once (navigation-store.ts
+ * markStaleSoftAndBroadcast), and when no landing does, the fence's drop
+ * marks them.
  */
 export declare function registerNavigationStore(store: NavigationStore): void;
 /** The active navigation store, or null before boot has registered it. */
 export declare function getRegisteredStore(): NavigationStore | null;
+/**
+ * Register the reader of the committed page's params and route name: the
+ * router store's own state, which useParams reads (the event controller's
+ * params, the displayed history entry's route name). Read by the prefetch
+ * cache outside render, at request time, to look up an answer shared by the
+ * pages with equal values of what a revalidate() rule read
+ * (prefetch-source-scope.ts). A reader, not a copy: there is no second
+ * source of truth for the params.
+ */
+export declare function registerCommittedPageReader(read: () => SourcePage): void;
+/**
+ * The boot reader (rsc-router.tsx): the event controller's params, which
+ * useParams reads and only a commit sets (an optimistic clientUrls() frame
+ * sets React context, not them), and the displayed entry's route name.
+ */
+export declare function committedPageOf(controller: {
+    getParams(): Record<string, string>;
+}, store: Pick<NavigationStore, "getHistoryEntryMemory">): () => SourcePage;
+/** The committed page, or null before boot has registered its reader. */
+export declare function getCommittedPage(): SourcePage | null;

package/dist/types/browser/navigation-store.d.ts

@@ -55,8 +55,8 @@ export interface NavigationStoreConfig {
     cacheSize?: number;
     /**
      * Enable cross-tab cache invalidation via BroadcastChannel (default: true)
-     * When cache is cleared (via server actions or invalidateClientCache()),
-     * other tabs will also clear their cache
+     * After a server action other tabs that share a segment mark their caches
+     * stale; after invalidateClientCache() they adopt its state and flush
      */
     crossTabSync?: boolean;
     /**

package/dist/types/browser/navigation-transaction.d.ts

@@ -87,7 +87,6 @@ export interface CommitResult {
  * Bound transaction with pre-configured commit options (without segmentIds/segments)
  */
 export interface BoundTransaction {
-    readonly currentUrl: string;
     /** Bound `replace` option (history replace instead of push). */
     readonly replace?: boolean;
     /** Bound `traversal` option: a back/forward navigation. */

package/dist/types/browser/partial-update.d.ts

@@ -114,6 +114,19 @@ export type UpdateMode = {
     refresh?: boolean;
     /** The cross-tab refresh's held boundary (see `action`). */
     boundary?: string;
+    /**
+     * A click's: told of each response this navigation fetches, true when
+     * it is a prefetch a server action marked stale
+     * (FetchPartialResult.stalePrefetch), false otherwise, so a fresh
+     * refetch after it (a fill's start-over, an HMR retry) clears it. Its
+     * presence is what lets a stale prefetch answer
+     * (FetchPartialOptions.acceptStalePrefetch): only a navigation that
+     * revalidates afterwards takes one. The click commits it as it commits
+     * any prefetch; the bridge revalidates the page once the navigation
+     * settled (navigation-bridge.ts navigate). Nothing here changes how or
+     * when this commit lands.
+     */
+    onStalePrefetch?: (stale: boolean) => void;
 } | {
     type: "leave-intercept";
     interceptSourceUrl?: string;

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

@@ -7,11 +7,14 @@
  * stream resolves the route's client references, so the route's JS chunks are
  * imported during prefetch rather than on click. The decoded payload is reused
  * verbatim by navigation, so a prefetched click loads no new code. Two key
- * scopes are in play:
+ * scopes are in play. Wherever a key below says `rangoState`, callers pass the
+ * state's `{version}:{timestamp}` part (cookie-name.ts stateEpoch), not the
+ * whole value: a server action's write bump leaves the keys as they were.
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
  *   source segment trees; `_rsc_segments` is omitted from this key. Invalidated
- *   automatically when Rango state bumps (deploy or server-action invalidation).
+ *   automatically when Rango state bumps (deploy or invalidateClientCache()).
+ *   A server action marks entries stale instead (the stale epoch, below).
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
  *   (so rotation invalidates source-scoped entries too), the source href, and
@@ -20,6 +23,14 @@
  *   targets, matched or not), OR when a Link opts in with
  *   `prefetchKey=":source"` — in both cases so source-sensitive responses
  *   cannot bleed into navigations from other pages.
+ * - Params-scoped: built by `buildParamsKey(rangoState, label, target)` —
+ *   shape `rangoState\0p:<label>\0/target?...`. Populated when the server
+ *   tags a response with `X-RSC-Prefetch-Scope: params; <label>`: a
+ *   revalidate() rule read the source's params or route name and kept a
+ *   segment, so the answer is right for every page with equal values of
+ *   what it read (prefetch-source-scope.ts). `paramsShapes` remembers, per
+ *   target, what the stored labels read, so a lookup rebuilds the label of
+ *   the page on screen (paramsCandidateKeys).
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
  * decoded prefetch entry (or null), letting navigation adopt a
@@ -39,6 +50,7 @@
  * effectively per-document. Unit tests reset them via clearPrefetchCache().
  */
 import type { RscPayload } from "../types.js";
+import { type SourcePage } from "../../prefetch-source-scope.js";
 /**
  * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
  * payload (not the raw Response) is what makes a prefetched navigation "warm":
@@ -58,9 +70,23 @@ export interface DecodedPrefetch {
      * Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
      * `"source"` means the response is source-page-sensitive and must not be
      * reused by a navigation from a different page — navigation enforces this
-     * when it adopted an inflight entry through the wildcard key.
+     * when it adopted an inflight entry through the wildcard key. `"params"`
+     * means it serves the pages whose label equals `paramsLabel`.
      */
-    scope: "source" | "wildcard";
+    scope: PrefetchScope;
+    /** The label of a `"params"` entry (prefetch-source-scope.ts). */
+    paramsLabel?: string;
+    /**
+     * The stale epoch (`currentPrefetchEpoch()`) the prefetch's fetch started
+     * under. A server action without a directive marks every prefetch stale
+     * (`markPrefetchesStale()` bumps the epoch) instead of flushing it: an entry
+     * from an older epoch is still served, and the navigation that adopts it
+     * revalidates its page once it settled (`isPrefetchStale`). A stale entry
+     * is served at most once, and only to a click (`consumePrefetch`'s
+     * `acceptStale`). A respawn keeps the original fetch's epoch, as it keeps
+     * its timestamp.
+     */
+    epoch: number;
     /**
      * Synchronously-readable flag, flipped to true when `streamComplete` resolves
      * (the entire RSC stream has drained). Navigation reads this at click time to
@@ -101,6 +127,8 @@ export interface DecodedPrefetch {
      */
     dispose?: () => void;
 }
+/** Where a prefetch is stored: see the module comment. */
+export type PrefetchScope = "source" | "params" | "wildcard";
 /**
  * Initialize the prefetch cache with the configured TTL and max size.
  * Called once at app startup with the values from server metadata. Each
@@ -121,7 +149,7 @@ export declare function isPrefetchCacheDisabled(): boolean;
  * one of:
  * - Wildcard (source-agnostic): prefix is the Rango state value from
  *   `getRangoState()`. Shared across all source pages. Invalidated
- *   automatically when Rango state bumps (deploy or server-action).
+ *   automatically when Rango state bumps (deploy or invalidateClientCache()).
  *   `_rsc_segments` is omitted so sibling payloads prefetched from one page
  *   remain reusable after another prefetched navigation commits. Key shape:
  *   `rangoState\0/target?...`.
@@ -148,8 +176,38 @@ export declare function buildPrefetchKey(prefix: string, targetUrl: URL): string
  * - `sourceHref` makes the key unique per originating page.
  */
 export declare function buildSourceKey(rangoState: string, sourceHref: string, targetUrl: URL): string;
+/**
+ * Build a params-scoped cache key. Key shape:
+ * `rangoState\0p:<label>\0/target?...`, the target normalized like the
+ * wildcard key's: the answer serves every page with this label, whatever
+ * segments it holds, as a wildcard answer serves every page.
+ */
+export declare function buildParamsKey(rangoState: string, label: string, targetUrl: URL): string;
+/**
+ * Remember that a params-scoped answer for `targetUrl` is stored under a
+ * label of this shape. Called where the response header is read, with the
+ * store (fetch.ts executePrefetchFetch).
+ */
+export declare function rememberParamsShape(targetUrl: URL, label: string): void;
+/**
+ * The params-scoped keys a request for `targetUrl` from `page` may adopt:
+ * the page's label under each shape stored for the target, the shapes that
+ * read the most first. Empty without a page (before boot).
+ */
+export declare function paramsCandidateKeys(rangoState: string, targetUrl: URL, page: SourcePage | null): string[];
+/**
+ * Whether `page` is in the group a params-scoped entry serves: its label
+ * under the entry's shape equals the entry's.
+ */
+export declare function pageMatchesParamsLabel(label: string, page: SourcePage | null): boolean;
 /**
  * Check if a prefetch is already cached, in-flight, or queued for the given key.
+ *
+ * A stale stored entry (`isPrefetchStale`) counts as absent and is dropped, so
+ * a new hover or viewport trigger replaces it with a fresh prefetch, and a
+ * click made while that one is in flight adopts it rather than the stale one.
+ * An in-flight fetch counts whatever its epoch: it is never aborted, and a
+ * duplicate request for its key would race it for the slot.
  */
 export declare function hasPrefetch(key: string): boolean;
 /**
@@ -163,10 +221,19 @@ export declare function hasPrefetch(key: string): boolean;
  * TTL bounds the age of the data, not of the latest adoption. Without
  * `respawn` the entry is deleted (legacy one-shot behavior).
  *
+ * A stale entry (`isPrefetchStale`) is served only to a caller that passes
+ * `acceptStale` (a click, which revalidates its page once it settled,
+ * navigation-bridge.ts): for any other caller it is a miss and stays in its
+ * slot. It is served at most once: its slot is not re-armed, so a second
+ * click on the same link fetches fresh rather than showing pre-write data
+ * older than what the first click's revalidation showed.
+ *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
  * for that (returns a Promise instead of a resolved entry).
  */
-export declare function consumePrefetch(key: string): DecodedPrefetch | null;
+export declare function consumePrefetch(key: string, options?: {
+    acceptStale?: boolean;
+}): DecodedPrefetch | null;
 /**
  * Consume an in-flight prefetch promise. Returns null if no prefetch is
  * in-flight for this key. The returned Promise resolves to the decoded
@@ -188,9 +255,14 @@ export declare function consumeInflightPrefetch(key: string): Promise<DecodedPre
  * Store an eagerly-decoded prefetch in the in-memory cache.
  *
  * Skips storage if the generation has changed since the fetch started
- * (a server action invalidated the cache mid-flight).
+ * (the cache was flushed mid-flight). An entry from an older stale epoch (an
+ * action marked prefetches stale mid-flight) is stored, and stays stale.
+ *
+ * `inflightKey` is the key the prefetch was in flight under, when the
+ * storage key is not one of its aliases (a params-scoped answer): a
+ * navigation that adopted it marked the aliases.
  */
-export declare function storePrefetch(key: string, entry: DecodedPrefetch, fetchGeneration: number): void;
+export declare function storePrefetch(key: string, entry: DecodedPrefetch, fetchGeneration: number, inflightKey?: string): void;
 /**
  * Remove a single stored prefetch entry. Used to evict an entry whose body
  * stream stalled after headers arrived (its payload / streamComplete never
@@ -210,6 +282,22 @@ export declare function removePrefetch(key: string, entry: DecodedPrefetch): voi
  * storePrefetch so it can detect stale completions.
  */
 export declare function currentGeneration(): number;
+/**
+ * Capture the current stale epoch. A prefetch fetch stamps its entry with the
+ * value read when it started (`DecodedPrefetch.epoch`).
+ */
+export declare function currentPrefetchEpoch(): number;
+/** Whether an action marked prefetches stale after this entry's fetch began. */
+export declare function isPrefetchStale(entry: Pick<DecodedPrefetch, "epoch">): boolean;
+/**
+ * Mark every stored and in-flight prefetch stale: what a server action
+ * without a directive does (navigation-store.ts markCacheAsStaleAndBroadcast).
+ * Only bumps the epoch. Nothing is dropped, aborted or rotated, and visible
+ * links are not told (no `notifyPrefetchCacheInvalidated()`), so they do not
+ * prefetch again. A click on a stale entry commits it at once; the navigation
+ * then revalidates its page (navigation-bridge.ts navigate).
+ */
+export declare function markPrefetchesStale(): void;
 export declare function markPrefetchInflight(key: string): void;
 export declare function setInflightPromise(key: string, promise: Promise<DecodedPrefetch | null>): void;
 /**

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

@@ -14,6 +14,7 @@
  * a prefetch that is still downloading/decoding instead of starting a
  * duplicate request.
  */
+import { type PrefetchScope } from "./cache.js";
 import type { RscPayload } from "../types.js";
 /**
  * Decoder injected at app startup (see setPrefetchDecoder). This is
@@ -29,9 +30,31 @@ type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
  * browser app always sets it before any Link can fire.
  */
 export declare function setPrefetchDecoder(fn: PrefetchDecoder): void;
+/** Where a completed prefetch is stored, and the label of a params scope. */
+export interface PrefetchSlot {
+    scope: PrefetchScope;
+    key: string;
+    paramsLabel?: string;
+}
+/**
+ * Where a completed prefetch is stored: under the source key when the Link
+ * forced it or the response says `X-RSC-Prefetch-Scope: source`; under the
+ * label's key when it says `params; <label>`, for the pages with equal values
+ * of what a revalidate() rule read; else under the key every source page
+ * shares (#1331). `stateKey` is the state's epoch the other keys were built
+ * with (cookie-name.ts stateEpoch).
+ */
+export declare function prefetchStorageSlot(forceSourceScope: boolean, scopeHeader: string | null, sourceKey: string, wildcardKey: string, stateKey: string, targetUrl: URL): PrefetchSlot;
 /**
  * Prefetch (direct): fetch with low priority and store in in-memory cache.
- * Used by hover strategy -- fires immediately without queueing.
+ * Used by hover (on hover and viewport links, and delegated anchors) and
+ * useRouter().prefetch() -- fires immediately without queueing.
+ *
+ * An intent prefetch: the visitor is about to click, so it asks for the full
+ * response the navigation would get, `prefetch: false` loaders and flagged
+ * `loading()` work included. It runs only on a miss: a cached prefetch or one
+ * in flight, even a speculative one that deferred work, is used as it is,
+ * and its click sends the fill as before (docs/design/prefetch-false.md, R16).
  *
  * By default the wildcard key (Rango-state-keyed) is used for inflight
  * dedup and for responses that are not source-sensitive; source-scoped
@@ -44,7 +67,8 @@ export declare function setPrefetchDecoder(fn: PrefetchDecoder): void;
 export declare function prefetchDirect(url: string, segmentIds: string[], version?: string, routerId?: string, prefetchKey?: ":source"): void;
 /**
  * Prefetch (queued): goes through the concurrency-limited queue.
- * Used by viewport/render strategies to avoid flooding the server.
+ * Used by viewport/render strategies to avoid flooding the server. A
+ * speculative prefetch: the server defers `prefetch: false` work in it.
  * Returns the inflight key (wildcard by default, source-scoped when
  * `prefetchKey=":source"` is passed).
  */

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

@@ -42,7 +42,8 @@ export declare function enqueuePrefetch(key: string, execute: (signal: AbortSign
 export declare function cancelAllPrefetches(keepUrl?: string | null): void;
 /**
  * Hard-cancel everything including in-flight prefetches.
- * Used by clearPrefetchCache (server action invalidation) where
- * in-flight responses would be stale.
+ * Used by clearPrefetchCache (invalidateClientCache(), a deploy) where
+ * in-flight responses would be stale. A server action never calls it: it
+ * marks prefetches stale and lets in-flight ones finish (cache.ts).
  */
 export declare function abortAllPrefetches(): void;

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;