@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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

@@ -0,0 +1,75 @@
+import type { NavigateOptions, NavigationStore, ResolvedSegment, StreamingToken } from "./types.js";
+import type { EventController, NavigationHandle } from "./event-controller.js";
+export { resolveNavigationState } from "./history-state.js";
+/**
+ * Options for committing a navigation transaction
+ */
+interface CommitOptions {
+    url: string;
+    segmentIds: string[];
+    segments: ResolvedSegment[];
+    replace?: boolean;
+    scroll?: boolean;
+    /** User-provided state to store in history.state */
+    state?: unknown;
+    /** If true, only update store without changing URL/history (for server actions) */
+    storeOnly?: boolean;
+    /** If true, this is an intercept route - store in history.state for popstate handling */
+    intercept?: boolean;
+    /** Source URL where the intercept was triggered from (stored in history.state) */
+    interceptSourceUrl?: string;
+    /** If true, only update cache without touching store or history (for background stale revalidation) */
+    cacheOnly?: boolean;
+    /** Server-set location state to merge into history.pushState */
+    serverState?: Record<string, unknown>;
+}
+/**
+ * Options that can override the pre-configured commit settings
+ */
+interface BoundCommitOverrides {
+    /** Override scroll behavior (e.g., disable for intercepts) */
+    scroll?: boolean;
+    /** Override replace behavior (e.g., force replace for intercepts) */
+    replace?: boolean;
+    /** Override user-provided state */
+    state?: unknown;
+    /** Mark this as an intercept route */
+    intercept?: boolean;
+    /** Source URL where intercept was triggered from */
+    interceptSourceUrl?: string;
+    /** If true, only update cache (for stale revalidation) */
+    cacheOnly?: boolean;
+    /** Server-set location state to merge into history.pushState */
+    serverState?: Record<string, unknown>;
+}
+/**
+ * Bound transaction with pre-configured commit options (without segmentIds/segments)
+ */
+export interface BoundTransaction {
+    readonly currentUrl: string;
+    /** Start streaming and get a token to end it when the stream completes */
+    startStreaming(): StreamingToken;
+    /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
+    commit(segmentIds: string[], segments: ResolvedSegment[], overrides?: BoundCommitOverrides): {
+        scroll?: boolean;
+    };
+}
+/**
+ * Navigation transaction for managing state during navigation
+ * Uses the event controller handle for lifecycle management
+ */
+interface NavigationTransaction extends Disposable {
+    commit(options: CommitOptions): {
+        scroll?: boolean;
+    };
+    with(options: Omit<CommitOptions, "segmentIds" | "segments">): BoundTransaction;
+    /** The navigation handle from the event controller */
+    handle: NavigationHandle;
+}
+/**
+ * Creates a navigation transaction that coordinates with the event controller.
+ * Handles loading state transitions and cleanup on completion/abort.
+ */
+export declare function createNavigationTransaction(store: NavigationStore, eventController: EventController, url: string, options?: NavigateOptions & {
+    skipLoadingState?: boolean;
+}): NavigationTransaction;

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/notify-listeners.d.ts

@@ -0,0 +1,2 @@
+/** Notify every active listener and surface every callback failure. */
+export declare function notifyListeners<T>(entries: Iterable<T>, notify: (entry: T) => void, isActive?: (entry: T) => boolean, shouldContinue?: () => boolean): void;

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,224 @@
+/**
+ * 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
+ *   source segment trees; `_rsc_segments` is omitted from this key. 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), the source href, and
+ *   the exact source segment tree. 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.
+     *
+     * On a respawned entry (see `respawn`) this starts true: the buffered bytes
+     * are a complete stream by construction.
+     */
+    complete: boolean;
+    /**
+     * Re-create this entry from its buffered raw Flight bytes. Attached (by
+     * `executePrefetchFetch`) only after the stream ended cleanly AND the eager
+     * decode succeeded — a truncated or failed prefetch must stay one-shot.
+     *
+     * Why bytes and not the decoded payload: the revived payload is a live graph
+     * with one-shot stream edges (the handle stream is an async generator drained
+     * during commit; userland payloads may embed serialized ReadableStreams).
+     * Re-decoding from the wire bytes manufactures fresh instances of every
+     * stream, which no amount of cloning the revived graph can do. Each call tees
+     * the reserve branch, so the replacement entry carries its own `respawn` —
+     * one prefetch serves unlimited adoptions within TTL/state validity.
+     */
+    respawn?: () => DecodedPrefetch;
+    /**
+     * Release the buffered reserve bytes. Called when the entry is evicted
+     * without being consumed (expiry, FIFO, sweep, cache clear) so the tee
+     * buffer is dropped promptly instead of waiting for GC.
+     */
+    dispose?: () => void;
+}
+/**
+ * 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).
+ *   `_rsc_segments` is omitted so sibling payloads prefetched from one page
+ *   remain reusable after another prefetched navigation commits. 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"`.
+ *
+ * Source-scoped keys retain `_rsc_segments` because their exact source tree is
+ * part of the opt-in contract. Wildcard responses are source-agnostic by
+ * contract; callers use source scope when a custom revalidation decision makes
+ * the response depend on the current URL or segment tree.
+ */
+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. Returns null when caching is disabled (TTL <= 0).
+ *
+ * A decoded payload is single-render (its handle stream is drained during the
+ * commit), so the returned entry is never served twice. When the entry carries
+ * `respawn` (clean-EOF prefetch with buffered bytes), the slot is re-armed in
+ * place with a fresh decode of those bytes — the ORIGINAL timestamp is kept so
+ * TTL bounds the age of the data, not of the latest adoption. Without
+ * `respawn` the entry is deleted (legacy one-shot behavior).
+ *
+ * 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;
+/** Whether this document may request stored segment fragment envelopes. */
+export declare function isFragmentPassthroughEnabled(): boolean;
+/**
+ * Disable fragment passthrough for the rest of this document after one stored
+ * fragment fails to decode. The recovery replaces shared cache entries, while
+ * this guard prevents the current tab's HTTP cache from serving its already-
+ * cached corrupt variant again.
+ */
+export declare function disableFragmentPassthrough(): void;
+export declare function clearPrefetchCache(rotateRangoState?: boolean): void;

package/dist/types/browser/prefetch/default-strategy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Router-wide default prefetch strategy (client seat).
+ *
+ * The server resolves `createRouter({ defaultPrefetch })` once at router init
+ * (router/prefetch-default.ts) and ships it in initial payload metadata; the
+ * browser entry applies it here before hydration — same lifecycle as
+ * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
+ * explicit `prefetch` prop and every eligible intercepted plain anchor that has
+ * not opted out with `data-prefetch="false"` or `data-prefetch="none"` uses it.
+ * Containers use the same `false`/`none` vocabulary via
+ * `data-prefetch-scope`.
+ *
+ * The module initial value must equal the server resolver's environment default:
+ * `"none"` in development and `"viewport"` in production. During SSR this
+ * module is never initialized from metadata, so keeping both seats aligned also
+ * gives metadata-less payloads the documented behavior.
+ */
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+/** Reset module state between tests that replace browser media globals. */
+export declare function resetAdaptiveStrategyForTesting(): void;
+/**
+ * Apply the server-resolved default strategy. Called once at browser app init
+ * from payload metadata; also used by tests to reset state.
+ */
+export declare function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void;
+/** Current default strategy for Links and delegated plain anchors. */
+export declare function getDefaultPrefetchStrategy(): PrefetchStrategy;
+/** Resolve adaptive to the strategy for the current input capability. */
+export declare function resolveAdaptiveStrategy(strategy: PrefetchStrategy): PrefetchStrategy;
+/** Subscribe to changes in the input capability used by adaptive prefetch. */
+export declare function subscribeToAdaptiveStrategyChange(listener: () => void): () => 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/invalidation.d.ts

@@ -0,0 +1,6 @@
+type PrefetchCacheInvalidationListener = () => void;
+/** Subscribe to completed local prefetch-cache invalidations. */
+export declare function subscribeToPrefetchCacheInvalidation(listener: PrefetchCacheInvalidationListener): () => void;
+/** Notify the registrations that existed when the cache was invalidated. */
+export declare function notifyPrefetchCacheInvalidated(): void;
+export {};

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

@@ -0,0 +1,12 @@
+import type { RscPayload } from "../types.js";
+import type { EventController } from "../event-controller.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;
+/** Run speculative work only when no navigation or stream is active. */
+export declare function schedulePrefetchWhenRouterIdle(eventController: Pick<EventController, "getState" | "subscribe">, callback: () => void): (() => void) | undefined;
+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,24 @@
+/**
+ * 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;
+/** Reset module state between tests that replace browser observer globals. */
+export declare function resetPrefetchObserverForTesting(): 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;
+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,2 @@
+export { prefetchDirect, prefetchQueued, setPrefetchDecoder } from "./fetch.js";
+export { abortAllPrefetches, cancelAllPrefetches, setPrefetchConcurrency, } from "./queue.js";