@rangojs/router 0.4.3 → 0.5.1

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

@@ -0,0 +1,95 @@
+import type { NavigationStore, ResolvedSegment, HandleData } from "./types.js";
+/**
+ * Clone the handleData CONTAINERS (the handle-name map and each segment map) so
+ * a cache entry is decoupled from the live map that eventController mutates — it
+ * adds/deletes segment keys and REPLACES bucket arrays in place. The bucket
+ * arrays themselves are shared by reference, NOT copied: a bucket array is only
+ * ever replaced wholesale (eventController.setHandleData reassigns it,
+ * resolveDeferredHandleValues builds a fresh one) and collect functions read it
+ * without mutating, so sharing is safe and skips an O(elements) copy on every
+ * cache write — the per-yield streaming hot path. This also preserves any
+ * non-serializable bucket contents (React elements, functions, etc.).
+ */
+export declare function cloneHandleData(handleData: HandleData): HandleData;
+/**
+ * Options for generating a history key
+ */
+export interface HistoryKeyOptions {
+    /** If true, append :intercept suffix to differentiate intercept entries */
+    intercept?: boolean;
+}
+/**
+ * Generate a cache key from a URL.
+ * Uses pathname + search (query params) directly as the key.
+ * Hash fragments (#) are excluded since they don't affect server data.
+ *
+ * For intercept routes, append `:intercept` suffix to cache them separately
+ * from non-intercept versions of the same URL.
+ */
+export declare function generateHistoryKey(url?: string, options?: HistoryKeyOptions): string;
+/**
+ * Configuration for creating a navigation store
+ */
+export interface NavigationStoreConfig {
+    initialLocation?: {
+        href: string;
+    };
+    initialSegmentIds?: string[];
+    initialHistoryKey?: string;
+    initialSegments?: ResolvedSegment[];
+    /**
+     * Maximum number of history entries to cache (default: 20)
+     * Older entries are evicted when limit is reached
+     */
+    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
+     */
+    crossTabSync?: boolean;
+    /**
+     * Auto-refresh when another tab mutates data on the same path (default: true)
+     * Triggered when cache is cleared via server actions or invalidateClientCache()
+     * Requires crossTabSync to be enabled
+     */
+    crossTabAutoRefresh?: boolean;
+    /**
+     * Callback to invoke when cross-tab refresh is triggered
+     * Called when another tab invalidates the cache for a related route
+     */
+    onCrossTabRefresh?: () => void;
+}
+/**
+ * Create a navigation store for managing browser-side navigation state
+ *
+ * The store manages two types of state:
+ * - NavigationState: Public state exposed via useNavigation hook
+ * - SegmentState: Internal segment management for partial RSC updates
+ *
+ * @param config - Initial configuration
+ * @returns NavigationStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = createNavigationStore({
+ *   initialLocation: window.location,
+ *   initialSegmentIds: [],
+ * });
+ *
+ * // Subscribe to state changes (for useNavigation hook)
+ * const unsubscribe = store.subscribe(() => {
+ *   const state = store.getState();
+ *   console.log('Navigation state:', state);
+ * });
+ *
+ * // Update state
+ * store.setState({ state: 'loading' });
+ *
+ * // Subscribe to UI updates (for re-rendering)
+ * store.onUpdate((update) => {
+ *   console.log('New root:', update.root);
+ * });
+ * ```
+ */
+export declare function createNavigationStore(config?: NavigationStoreConfig): NavigationStore;

package/dist/types.backup/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.backup/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.backup/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.backup/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.backup/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.backup/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.backup/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.backup/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.backup/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>;