@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/browser/network-error-handler.d.ts

@@ -0,0 +1,35 @@
+import { NetworkError } from "../errors.js";
+import type { UpdateSubscriber } from "./types.js";
+/**
+ * Convert an unknown error to a NetworkError, or return null if not network-related.
+ *
+ * Pure function: extracts the "is this a network error?" decision from
+ * navigation-bridge and server-action-bridge so it can be unit tested.
+ */
+export declare function toNetworkError(error: unknown, context: {
+    url: string;
+    operation: "action" | "navigation" | "revalidation";
+}): NetworkError | null;
+/**
+ * Emit a NetworkError to the nearest error boundary (offline, failed fetch).
+ */
+export declare function emitNetworkError(onUpdate: UpdateSubscriber, error: NetworkError, pathname: string): void;
+/**
+ * Emit a navigation processing error to the nearest error boundary. Used when a
+ * navigation response cannot be processed (an undecodable Flight body, or any
+ * unanticipated failure while building the response) -- for both fresh and
+ * prefetched responses, since both funnel through the navigation catch. Without
+ * this, such a failure becomes an uncaught rejection that silently aborts the
+ * navigation instead of surfacing the route's error boundary.
+ */
+export declare function emitNavigationError(onUpdate: UpdateSubscriber, error: unknown, pathname: string): void;
+/**
+ * Check if an error is safe to suppress in background operations.
+ *
+ * Background revalidation (SWR, navigated-away refetch) should silently
+ * swallow AbortErrors and network errors since the user has already moved
+ * on and showing an error would be disruptive.
+ *
+ * Pure function, easily unit tested.
+ */
+export declare function isBackgroundSuppressible(error: unknown): boolean;

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

@@ -0,0 +1,61 @@
+import type { NavigationStore, NavigationClient, UpdateSubscriber, ResolvedSegment } from "./types.js";
+import type { ReactNode } from "react";
+import type { RenderSegmentsOptions } from "../segment-system.js";
+import type { BoundTransaction } from "./navigation-transaction.js";
+/**
+ * Configuration for creating a partial updater
+ */
+export interface PartialUpdateConfig {
+    store: NavigationStore;
+    client: NavigationClient;
+    onUpdate: UpdateSubscriber;
+    renderSegments: (segments: ResolvedSegment[], options?: RenderSegmentsOptions) => Promise<ReactNode> | ReactNode;
+    /** RSC version getter — returns the current version (may change after HMR) */
+    getVersion?: () => string | undefined;
+}
+/**
+ * Options that can override the pre-configured commit settings
+ */
+export interface CommitOverrides {
+    /** Override scroll behavior (e.g., disable for intercepts) */
+    scroll?: boolean;
+    /** Override replace behavior (e.g., force replace for intercepts) */
+    replace?: boolean;
+    /** Mark this as an intercept route */
+    intercept?: boolean;
+    /** Source URL where intercept was triggered from */
+    interceptSourceUrl?: string;
+    /** Server-set location state to merge into history.pushState */
+    serverState?: Record<string, unknown>;
+}
+/**
+ * Discriminated update mode for partial updates.
+ */
+export type UpdateMode = {
+    type: "navigate";
+    /** Cached segments for the target URL. When provided, these are used to build
+     * the segment map instead of the current page's segments. This ensures consistency
+     * when we send cached segment IDs to the server - if the server returns empty diff,
+     * we use the same segments we told the server we have. */
+    targetCacheSegments?: ResolvedSegment[];
+    /** Cached handle data for the target URL. When server returns empty diff and we're
+     * rendering from cache, this is passed to the UI to restore breadcrumbs etc. */
+    targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
+    /** Source URL for intercept restore (popstate cache miss) */
+    interceptSourceUrl?: string;
+} | {
+    type: "leave-intercept";
+    interceptSourceUrl?: string;
+} | {
+    type: "stale-revalidation";
+    interceptSourceUrl?: string;
+} | {
+    type: "action";
+    interceptSourceUrl?: string;
+};
+/**
+ * Type for the fetchPartialUpdate function
+ */
+export type PartialUpdater = (targetUrl: string, segmentIds: string[] | undefined, isRetry: boolean, signal: AbortSignal | undefined, tx: BoundTransaction, mode?: UpdateMode) => Promise<void>;
+export declare function createPartialUpdater(config: PartialUpdateConfig): PartialUpdater;
+export { createPartialUpdater as default };

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

@@ -0,0 +1,183 @@
+/**
+ * Prefetch Cache
+ *
+ * In-memory cache storing eagerly-decoded prefetch payloads for instant,
+ * already-warm cache hits on subsequent navigation. A prefetch fetches the
+ * RSC partial AND decodes it (createFromFetch) up front — decoding the Flight
+ * 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:
+ * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
+ *   shape `rangoState\0/target?...`. Shared across all source pages and
+ *   invalidated automatically when Rango state bumps (deploy or
+ *   server-action invalidation).
+ * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
+ *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
+ *   (so rotation invalidates source-scoped entries too) plus the source
+ *   href (so each originating page gets its own slot). Populated when the
+ *   server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
+ *   modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
+ *   both cases so source-sensitive responses cannot bleed into navigations
+ *   from other pages.
+ *
+ * Also tracks in-flight prefetch promises. Each promise resolves to the
+ * decoded prefetch entry (or null), letting navigation adopt a
+ * still-downloading prefetch without issuing a duplicate request. A
+ * single promise can be registered under multiple alias keys (see
+ * `setInflightPromiseWithAliases`) so same-source navigations adopt via
+ * their source key while cross-source ones fall through to the wildcard
+ * alias — with consume/clear atomically removing every alias.
+ *
+ * Replaces the previous browser HTTP cache approach which was unreliable
+ * due to response draining race conditions and browser inconsistencies.
+ *
+ * State here lives in module-level singletons (cache, inflight, generation,
+ * cacheTTL, etc.) rather than a per-instance factory. This is correct because
+ * exactly one router is live per document — an SPA navigation crossing a
+ * host-router boundary forces a full document reload — so the singletons are
+ * effectively per-document. Unit tests reset them via clearPrefetchCache().
+ */
+import type { RscPayload } from "../types.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":
+ * decoding the Flight stream during prefetch pulls the route's client chunks,
+ * so the click reuses ready elements and loads no new JS.
+ */
+export interface DecodedPrefetch {
+    /** The eagerly-decoded RSC payload. Reused verbatim by navigation. */
+    payload: Promise<RscPayload>;
+    /**
+     * Resolves when the underlying RSC stream finishes draining. Navigation
+     * forwards this as its streamComplete so scroll/revalidation gating is
+     * unchanged from the fresh-fetch path.
+     */
+    streamComplete: Promise<void>;
+    /**
+     * 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.
+     */
+    scope: "source" | "wildcard";
+    /**
+     * Synchronously-readable flag, flipped to true when `streamComplete` resolves
+     * (the entire RSC stream has drained). Navigation reads this at click time to
+     * tell a FULLY warmed prefetch (payload commits without suspending → safe to
+     * commit in a startTransition, no fallback flash) from a partially-warmed one
+     * (still streaming → stream its fallbacks like a cold load). Starts false.
+     */
+    complete: boolean;
+}
+/**
+ * Initialize the prefetch cache with the configured TTL and max size.
+ * Called once at app startup with the values from server metadata. Each
+ * argument is applied only when provided, so a caller can set just the TTL.
+ * A TTL of 0 disables the in-memory cache and all prefetching. A size below 1
+ * is ignored (the default is kept) — disabling prefetch is the TTL's job.
+ */
+export declare function initPrefetchCache(ttlMs?: number, maxSize?: number): void;
+/**
+ * Check if the prefetch cache is disabled (TTL <= 0).
+ * When disabled, no prefetch requests should be issued.
+ */
+export declare function isPrefetchCacheDisabled(): boolean;
+/**
+ * Build a cache key by combining a scope prefix with the target URL.
+ *
+ * Low-level primitive — callers that want a specific scope should use
+ * 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).
+ *   Key shape: `rangoState\0/target?...`.
+ * - Source-scoped: use `buildSourceKey()`. Key shape:
+ *   `rangoState\0sourceHref\0/target?...` — embeds the Rango state so
+ *   rotation invalidates source-scoped entries alongside wildcard ones,
+ *   plus the source page href so the key is unique per originating page.
+ *   Populated either when the server tags a response with
+ *   `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
+ *   Link opts in via `prefetchKey=":source"`.
+ *
+ * The `_rsc_segments` query param that travels in the target URL means
+ * clients with different mounted segment trees naturally get different
+ * keys — so segment-level diffs remain consistent across both scopes.
+ */
+export declare function buildPrefetchKey(prefix: string, targetUrl: URL): string;
+/**
+ * Build a source-scoped cache key. Key shape:
+ * `rangoState\0sourceHref\0/target?...`.
+ *
+ * - `rangoState` is included so state rotation invalidates source-scoped
+ *   entries alongside wildcard ones.
+ * - `sourceHref` makes the key unique per originating page.
+ */
+export declare function buildSourceKey(rangoState: string, sourceHref: string, targetUrl: URL): string;
+/**
+ * Check if a prefetch is already cached, in-flight, or queued for the given key.
+ */
+export declare function hasPrefetch(key: string): boolean;
+/**
+ * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
+ * expired. One-time consumption: the entry is deleted after retrieval.
+ * Returns null when caching is disabled (TTL <= 0).
+ *
+ * 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;
+/**
+ * Consume an in-flight prefetch promise. Returns null if no prefetch is
+ * in-flight for this key. The returned Promise resolves to the decoded
+ * prefetch entry (or null if the fetch failed/was aborted, or carried a
+ * control header the navigation must re-fetch to honor).
+ *
+ * One-time consumption: the promise entry is removed (along with any
+ * sibling aliases registered via `setInflightPromiseWithAliases`) so a
+ * second call on any alias returns null — only one caller can adopt the
+ * shared Response stream. The `inflight` set entry is intentionally
+ * kept so that `hasPrefetch()` continues to return true while the
+ * underlying fetch is still downloading — this prevents
+ * `prefetchDirect()` or other callers from starting a duplicate request
+ * during the handoff window. The inflight flag is cleaned up naturally
+ * by `clearPrefetchInflight()` in the fetch's `.finally()`.
+ */
+export declare function consumeInflightPrefetch(key: string): Promise<DecodedPrefetch | null> | null;
+/**
+ * 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).
+ */
+export declare function storePrefetch(key: string, entry: DecodedPrefetch, fetchGeneration: number): void;
+/**
+ * Remove a single stored prefetch entry. Used to evict an entry whose body
+ * stream stalled after headers arrived (its payload / streamComplete never
+ * settle), so future prefetches and navigation refetch instead of dedupe-ing
+ * against — and awaiting — a stuck entry.
+ *
+ * Identity-guarded: only evicts when the entry CURRENTLY stored under `key` is
+ * the exact `entry` we published. A generation check alone is insufficient —
+ * after this entry is consumed (consumePrefetch) and a fresh prefetch
+ * republishes under the SAME key in the SAME generation, a gen-only guard would
+ * delete that valid newer entry. Reference identity drops only our own stalled
+ * entry.
+ */
+export declare function removePrefetch(key: string, entry: DecodedPrefetch): void;
+/**
+ * Capture the current generation. The returned value is passed to
+ * storePrefetch so it can detect stale completions.
+ */
+export declare function currentGeneration(): number;
+export declare function markPrefetchInflight(key: string): void;
+export declare function setInflightPromise(key: string, promise: Promise<DecodedPrefetch | null>): void;
+/**
+ * Store the same in-flight Promise under multiple keys, recording them
+ * as sibling aliases. Consuming or clearing any one alias atomically
+ * removes every entry, guaranteeing the shared Response stream has a
+ * single consumer even when navigation looks up either key.
+ */
+export declare function setInflightPromiseWithAliases(keys: string[], promise: Promise<DecodedPrefetch | null>): void;
+export declare function clearPrefetchInflight(key: string): void;
+export declare function clearPrefetchCache(): void;

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

@@ -0,0 +1,52 @@
+/**
+ * Prefetch Fetch
+ *
+ * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
+ * and useRouter().prefetch(). Sends the same headers and segment IDs as a
+ * real navigation so the server returns a proper diff. The response is fetched
+ * AND eagerly decoded (createFromFetch) up front: decoding the Flight 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 stored in an
+ * in-memory cache and reused verbatim by navigation, so a prefetched click
+ * loads no new code.
+ *
+ * In-flight promises are tracked in the cache so that navigation can reuse
+ * a prefetch that is still downloading/decoding instead of starting a
+ * duplicate request.
+ */
+import type { RscPayload } from "../types.js";
+/**
+ * Decoder injected at app startup (see setPrefetchDecoder). This is
+ * `deps.createFromFetch` — decoupled from the RSC runtime exactly like the
+ * navigation client. Prefetch decodes through it so the route's client chunks
+ * are pulled during the prefetch, not on click.
+ */
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+/**
+ * Wire the RSC decoder used to eagerly decode prefetched responses. Called
+ * once from initBrowserApp with the same createFromFetch the navigation client
+ * uses. Until set, prefetch warming is inert (prefetches are skipped) — the
+ * browser app always sets it before any Link can fire.
+ */
+export declare function setPrefetchDecoder(fn: PrefetchDecoder): void;
+/**
+ * Prefetch (direct): fetch with low priority and store in in-memory cache.
+ * Used by hover strategy -- fires immediately without queueing.
+ *
+ * By default the wildcard key (Rango-state-keyed) is used for inflight
+ * dedup and for responses that are not source-sensitive; source-scoped
+ * storage is automatic when the server emits `X-RSC-Prefetch-Scope: source`.
+ *
+ * Pass `prefetchKey=":source"` to force source-scoped inflight + storage
+ * (e.g. when the target uses a custom `revalidate()` that reads
+ * `currentUrl` and the wildcard slot would serve the wrong diff).
+ */
+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.
+ * Returns the inflight key (wildcard by default, source-scoped when
+ * `prefetchKey=":source"` is passed).
+ */
+export declare function prefetchQueued(url: string, segmentIds: string[], version?: string, routerId?: string, prefetchKey?: ":source"): string;
+export {};

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

@@ -0,0 +1,10 @@
+import type { RscPayload } from "../types.js";
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+export declare function setPrefetchDecoder(fn: PrefetchDecoder): void;
+export declare function setPrefetchConcurrency(value: number): void;
+export declare function prefetchDirect(url: string, segmentIds: string[], version?: string, routerId?: string, prefetchKey?: ":source"): void;
+export declare function prefetchQueued(url: string, segmentIds: string[], version?: string, routerId?: string, prefetchKey?: ":source"): void;
+export declare function observeForPrefetch(element: Element, callback: () => void): () => void;
+export declare function cancelAllPrefetches(keepUrl?: string | null): void;
+export declare function abortAllPrefetches(): void;
+export {};

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

@@ -0,0 +1,27 @@
+/**
+ * Prefetch Observer
+ *
+ * Shared singleton IntersectionObserver for viewport-based prefetching.
+ * One observer handles all Link components with prefetch="viewport".
+ *
+ * Lazy-created on first call to avoid issues in SSR or test environments
+ * where IntersectionObserver may not exist.
+ *
+ * Observation is one-shot: once a link enters the viewport and the callback
+ * fires, the element is unobserved. This prevents re-prefetching when a link
+ * scrolls in and out repeatedly.
+ */
+type PrefetchCallback = () => void;
+/**
+ * Observe an element for viewport intersection.
+ * When the element becomes visible (within 200px margin), the callback fires
+ * and the element is automatically unobserved.
+ * No-op in environments without IntersectionObserver (SSR, some test runners).
+ */
+export declare function observeForPrefetch(element: Element, onVisible: PrefetchCallback): void;
+/**
+ * Stop observing an element. Used for cleanup when a Link unmounts
+ * before entering the viewport.
+ */
+export declare function unobserveForPrefetch(element: Element): void;
+export {};

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

@@ -0,0 +1,13 @@
+/**
+ * Prefetch Policy
+ *
+ * Determines whether speculative prefetching should run for the current user.
+ * Honors browser reduced-data preferences when available.
+ */
+/**
+ * Evaluate on every call so runtime changes to Save-Data or
+ * prefers-reduced-data are respected immediately.
+ */
+export declare function shouldPrefetch(): boolean;
+/** No-op, kept for test compatibility. */
+export declare function resetPrefetchPolicy(): void;

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

@@ -0,0 +1,48 @@
+/**
+ * Prefetch Queue
+ *
+ * Concurrency-limited FIFO queue for speculative prefetches (viewport/render).
+ * Hover prefetches bypass this queue — they fire directly for immediate response
+ * to user intent.
+ *
+ * Draining waits for an idle main-thread moment and for viewport images to
+ * finish loading, so prefetch fetch() calls never compete with critical
+ * resources for the browser's connection pool.
+ *
+ * When a navigation starts, queued prefetches are cancelled but executing ones
+ * are left running. Navigation can reuse their in-flight responses via the
+ * prefetch cache's inflight promise map, avoiding duplicate requests.
+ */
+/**
+ * Set the max number of concurrently-executing speculative prefetches.
+ * Called once at app startup with the value from server metadata. A value
+ * below 1 (or non-finite) is ignored, keeping the default.
+ */
+export declare function setPrefetchConcurrency(n: number): void;
+/**
+ * Enqueue a prefetch for concurrency-limited execution.
+ * Execution is deferred until the browser is idle and viewport images
+ * have finished loading, so prefetches never compete with critical
+ * resources. Deduplicates by key — items already queued or executing
+ * are skipped.
+ *
+ * The executor receives an AbortSignal that is aborted when
+ * cancelAllPrefetches() is called (e.g. on navigation start).
+ */
+export declare function enqueuePrefetch(key: string, execute: (signal: AbortSignal) => Promise<void>): void;
+/**
+ * Cancel queued prefetches and abort in-flight ones that don't match
+ * the current navigation target. If `keepUrl` is provided, the
+ * executing prefetch whose key targets that URL is kept alive so
+ * navigation can reuse its response via consumeInflightPrefetch.
+ *
+ * Called when a navigation starts via the NavigationProvider's
+ * event controller subscription.
+ */
+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.
+ */
+export declare function abortAllPrefetches(): void;

package/dist/types/browser/prefetch/resource-ready.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resource Readiness
+ *
+ * Utilities to defer speculative prefetches until critical resources
+ * (viewport images) have finished loading. Prevents prefetch fetch()
+ * calls from competing with images for the browser's connection pool.
+ */
+/**
+ * Resolve when all in-viewport images have finished loading.
+ * Returns immediately if no images are pending.
+ *
+ * Only checks images that exist at call time — does not observe
+ * dynamically added images. For SPA navigations where new images
+ * appear after render, call this after the navigation settles.
+ */
+export declare function waitForViewportImages(): Promise<void>;
+/**
+ * Resolve after the given number of milliseconds.
+ */
+export declare function wait(ms: number): Promise<void>;
+/**
+ * Resolve when the browser has an idle main-thread moment.
+ * Uses requestIdleCallback where available, falls back to setTimeout.
+ *
+ * This is a scheduling hint, not an asset-loaded detector — combine
+ * with waitForViewportImages() for full resource readiness.
+ */
+export declare function waitForIdle(timeout?: number): Promise<void>;

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

@@ -0,0 +1,3 @@
+export { prefetchDirect, prefetchQueued, setPrefetchDecoder } from "./fetch.js";
+export { abortAllPrefetches, cancelAllPrefetches, setPrefetchConcurrency, } from "./queue.js";
+export { observeForPrefetch, unobserveForPrefetch } from "./observer.js";

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

@@ -0,0 +1,52 @@
+/**
+ * Rango State
+ *
+ * Manages a session-cookie-based state value for HTTP cache invalidation. The
+ * value is sent as the `X-Rango-State` header on prefetch and navigation
+ * 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}`
+ * - Build version changes on deploy, busting all cached prefetches at boot.
+ * - Timestamp rotates on invalidation (server action, invalidateClientCache).
+ *
+ * Storage is a session cookie named by the server-resolved name passed to
+ * initRangoState (`{prefix}_{routerId}`, default prefix `rango-state`). The
+ * cookie jar is shared across tabs, so a per-request read IS the cross-tab
+ * value sync — no `storage` event is needed. An in-memory mirror is a
+ * write-through copy that is authoritative only when the cookie is unreadable
+ * (e.g. a sandboxed frame, or site data blocked wholesale): the failure
+ * direction is always toward freshness.
+ *
+ * Precedence is load-bearing: when `document.cookie` is readable, the
+ * per-request read wins; the mirror is a fallback, never a cache of the read.
+ * Caching the read across requests would reintroduce the staleness this
+ * mechanism removes.
+ */
+/**
+ * Register the observer invoked when a read detects an EXTERNAL rotation (a
+ * sibling tab, a server `Set-Cookie`, or a cookie clear). Self-rotations
+ * (invalidateRangoState) update the mirror synchronously and never fire it.
+ */
+export declare function setRangoStateObserver(observer: ((value: string) => void) | null): void;
+/**
+ * Initialize the Rango state cookie at app startup. `version` is the build
+ * version; `stateCookieName` is the server-resolved cookie name from payload
+ * metadata (falls back to the bare default prefix when a payload arrives
+ * without it). Keeps an existing matching-version cookie (preserves the cache
+ * key across reloads); mints fresh on a version change or a missing cookie.
+ */
+export declare function initRangoState(version: string, stateCookieName?: string): void;
+/**
+ * Get the current Rango state value, used as the `X-Rango-State` header on
+ * prefetch and navigation requests. Reads the cookie every call (the read is
+ * the cross-tab sync channel) and reconciles the mirror.
+ */
+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,
+ * 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;

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

@@ -0,0 +1,140 @@
+import React, { type ForwardRefExoticComponent, type RefAttributes } from "react";
+import { type LocationStateEntry } from "./location-state.js";
+/**
+ * State prop type for Link component.
+ * - LocationStateEntry[]: Type-safe state entries via createLocationState()
+ * - StateOrGetter: Plain state object or click-time getter function
+ * - Record<string, unknown>: Plain state object passed to history.pushState
+ */
+export type StateOrGetter<T = unknown> = T | (() => T);
+export type LinkState = LocationStateEntry[] | StateOrGetter<Record<string, unknown>>;
+/**
+ * Prefetch strategy for the Link component
+ * - "hover": Prefetch on mouse enter (direct, no queue)
+ * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
+ * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
+ * - "adaptive": Hover on pointer devices, viewport on touch devices
+ * - "none": No prefetching (default)
+ */
+export type PrefetchStrategy = "hover" | "viewport" | "render" | "adaptive" | "none";
+/**
+ * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
+ * for the CURRENT input capability: "viewport" on touch (no-hover) devices,
+ * "hover" on pointer devices. Non-adaptive strategies pass through unchanged.
+ * Reads touch capability live (not a module-load snapshot) so the result
+ * tracks input-capability changes.
+ */
+export declare function resolveAdaptiveStrategy(prefetch: PrefetchStrategy): PrefetchStrategy;
+/**
+ * Link component props
+ */
+export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    /**
+     * The URL to navigate to (typically from router.reverse())
+     */
+    to: string;
+    /**
+     * Replace current history entry instead of pushing
+     */
+    replace?: boolean;
+    /**
+     * Scroll to top after navigation (default: true)
+     */
+    scroll?: boolean;
+    /**
+     * Force full document navigation instead of SPA
+     */
+    reloadDocument?: boolean;
+    /**
+     * Whether to revalidate server data on navigation.
+     * Set to `false` to skip the RSC server fetch and only update the URL.
+     *
+     * Only takes effect when the pathname stays the same (search param / hash changes).
+     * If the pathname changes, this option is ignored and a full navigation occurs.
+     *
+     * @default true
+     */
+    revalidate?: boolean;
+    /**
+     * Prefetch strategy for the link destination
+     * @default "none"
+     */
+    prefetch?: PrefetchStrategy;
+    /**
+     * Opt-in override for the prefetch cache scope.
+     *
+     * The default cache is source-agnostic: one shared entry per target,
+     * 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.
+     *
+     * Intercept responses are auto-scoped to the source via a server-side
+     * tag, so `":source"` is only needed for custom revalidation logic.
+     *
+     * @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" />
+     * ```
+     */
+    prefetchKey?: ":source";
+    /**
+     * State to pass to history.pushState/replaceState.
+     * Accessible via useLocationState() hook.
+     *
+     * @example
+     * ```tsx
+     * // Type-safe state with createLocationState (recommended)
+     * const ProductState = createLocationState<{ name: string; price: number }>();
+     * <Link to="/product" state={[ProductState({ name: product.name, price: product.price })]}>
+     *   View
+     * </Link>
+     *
+     * // Type-safe just-in-time state (getter called at click time, not render time).
+     * // Must be in a client component -- getter can't cross the RSC boundary.
+     * <Link
+     *   to="/product"
+     *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+     * >
+     *   View
+     * </Link>
+     *
+     * // Multiple typed states
+     * <Link to="/checkout" state={[ProductState({ name: p.name, price: p.price }), CartState(c)]}>
+     *   Checkout
+     * </Link>
+     *
+     * // Plain static state
+     * <Link to="/product" state={{ from: "list" }}>View</Link>
+     *
+     * // Plain just-in-time state (called at click time, requires client component)
+     * <Link to="/product" state={() => ({ scrollY: window.scrollY })}>View</Link>
+     * ```
+     */
+    state?: LinkState;
+    children: React.ReactNode;
+}
+/**
+ * Type-safe Link component for SPA navigation
+ *
+ * Works with router.reverse() for type-safe URLs:
+ * ```tsx
+ * <Link to={router.reverse("shop.products.detail", { slug: "my-product" })}>
+ *   View Product
+ * </Link>
+ * ```
+ *
+ * Also supports regular URLs:
+ * ```tsx
+ * <Link to="/about">About</Link>
+ * <Link to="https://example.com">External</Link>
+ * ```
+ */
+export declare const Link: ForwardRefExoticComponent<LinkProps & RefAttributes<HTMLAnchorElement>>;