@rangojs/router 0.5.1 → 0.6.0

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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,28 +0,0 @@
-/**
- * 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.backup/browser/rango-state.d.ts

@@ -1,52 +0,0 @@
-/**
- * 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.backup/browser/react/Link.d.ts

@@ -1,140 +0,0 @@
-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>>;

package/dist/types.backup/browser/react/NavigationProvider.d.ts

@@ -1,88 +0,0 @@
-import { type ReactNode } from "react";
-import type { NavigationStore, NavigationUpdate, NavigationBridge } from "../types.js";
-import type { EventController } from "../event-controller.js";
-import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
-import { type AppShellRef } from "../app-shell.js";
-/**
- * Props for NavigationProvider
- */
-export interface NavigationProviderProps {
-    /**
-     * Navigation store instance (for cache/segment management)
-     */
-    store: NavigationStore;
-    /**
-     * Event controller instance (for navigation/action state)
-     */
-    eventController: EventController;
-    /**
-     * Initial rendered tree + metadata from server payload
-     */
-    initialPayload: NavigationUpdate;
-    /**
-     * Navigation bridge for handling navigation
-     */
-    bridge: NavigationBridge;
-    /**
-     * Theme configuration (null if theme not enabled)
-     * When provided, wraps content in ThemeProvider
-     */
-    themeConfig?: ResolvedThemeConfig | null;
-    /**
-     * Initial theme from server (from cookie)
-     * Only used when themeConfig is provided
-     */
-    initialTheme?: Theme;
-    /**
-     * Whether connection warmup is enabled.
-     * When true, keeps TLS alive by sending HEAD requests after idle periods.
-     */
-    warmupEnabled?: boolean;
-    /**
-     * App version from server payload.
-     * Used only as a fallback when `appShellRef` is not supplied.
-     */
-    version?: string;
-    /**
-     * URL prefix for all routes (from createRouter({ basename })).
-     * Used only as a fallback when `appShellRef` is not supplied.
-     */
-    basename?: string;
-    /**
-     * App-shell ref. When provided, the context's `basename` and `version` are
-     * read through it (live getters) so they don't close over a stale snapshot or
-     * invalidate the memoized context value. The shell is set once at init and is
-     * not swapped within a session — a cross-app navigation is a full document
-     * load (X-RSC-Reload), so the target app establishes its own shell on load.
-     */
-    appShellRef?: AppShellRef;
-    /**
-     * CSP nonce to expose via NonceContext. Production leaves this undefined — the
-     * browser has no nonce (it is a server-side HTML concern), and SSR provides the
-     * nonce through its own NonceContext.Provider. Test harnesses (renderRoute) set
-     * it to seed a nonce so components calling useNonce() can be exercised.
-     */
-    nonce?: string;
-}
-/**
- * Navigation provider component
- *
- * Provides navigation context to the component tree and handles:
- * - Providing stable store and event controller references (never re-renders consumers)
- * - Subscribing to UI updates to re-render the tree
- * - Providing navigate/refresh methods (delegated to bridge)
- *
- * State subscriptions happen via useNavigation hook (via event controller), not via context.
- * This means context consumers don't re-render on state changes.
- *
- * @example
- * ```tsx
- * <NavigationProvider
- *   store={store}
- *   eventController={eventController}
- *   initialPayload={payload}
- *   bridge={navigationBridge}
- * />
- * ```
- */
-export declare function NavigationProvider({ store, eventController, initialPayload, bridge, themeConfig, initialTheme, warmupEnabled, version, basename, appShellRef, nonce, }: NavigationProviderProps): ReactNode;

package/dist/types.backup/browser/react/ScrollRestoration.d.ts

@@ -1,78 +0,0 @@
-/**
- * Props for ScrollRestoration component
- */
-export interface ScrollRestorationProps {
-    /**
-     * Custom function to determine the scroll restoration key.
-     * By default, uses a unique key per history entry (location.key).
-     *
-     * Return location.pathname to restore scroll based on path
-     * (useful for keeping scroll position on the same page).
-     *
-     * Provide a stable reference: a module-level function or one wrapped in
-     * useCallback. The init effect re-runs when getKey's identity changes, and
-     * teardown clears in-memory scroll positions — a fresh inline arrow on every
-     * parent render would discard unpersisted positions mid-session.
-     *
-     * @example
-     * ```tsx
-     * // Stable module-level getKey (recommended)
-     * const byPathname = (location) => location.pathname;
-     *
-     * // Restore based on pathname (same URL = same scroll)
-     * <ScrollRestoration getKey={byPathname} />
-     *
-     * // Restore based on unique history entry (default)
-     * // <ScrollRestoration /> — omit getKey to use location.key
-     * ```
-     */
-    getKey?: (location: {
-        pathname: string;
-        search: string;
-        hash: string;
-        key: string;
-    }) => string;
-}
-/**
- * ScrollRestoration component
- *
- * Enables scroll position restoration across navigations:
- * - Saves scroll positions to sessionStorage
- * - Restores scroll on back/forward navigation
- * - Scrolls to top on new navigation
- * - Supports hash link scrolling
- *
- * Should be rendered once in your app, typically in the root layout.
- *
- * @example
- * ```tsx
- * // In your root layout
- * export default function RootLayout({ children }) {
- *   return (
- *     <html>
- *       <body>
- *         <ScrollRestoration />
- *         {children}
- *       </body>
- *     </html>
- *   );
- * }
- * ```
- */
-export declare function ScrollRestoration({ getKey }: ScrollRestorationProps): null;
-/**
- * Hook to initialize scroll restoration
- *
- * Alternative to the ScrollRestoration component for more control.
- *
- * @example
- * ```tsx
- * function App() {
- *   useScrollRestoration();
- *   return <div>...</div>;
- * }
- * ```
- */
-export declare function useScrollRestoration(options?: {
-    getKey?: ScrollRestorationProps["getKey"];
-}): void;

package/dist/types.backup/browser/react/context.d.ts

@@ -1,54 +0,0 @@
-import { type Context } from "react";
-import type { NavigationStore, NavigateOptions } from "../types.js";
-import type { EventController } from "../event-controller.js";
-/**
- * Navigation context value provided by NavigationProvider
- *
- * This context provides a STABLE reference to the store, event controller, and methods.
- * The store itself never changes, so context consumers don't re-render
- * when navigation state changes.
- *
- * Components subscribe to state changes via eventController.subscribe() in useNavigation.
- */
-export interface NavigationStoreContextValue {
-    /**
-     * The navigation store instance (stable reference)
-     * Used for cache/segment management
-     */
-    store: NavigationStore;
-    /**
-     * The event controller instance (stable reference)
-     * Used for navigation/action state
-     */
-    eventController: EventController;
-    /**
-     * Navigate to a new URL
-     *
-     * @param url - The URL to navigate to
-     * @param options - Navigation options (replace, scroll)
-     * @returns Promise that resolves when navigation is complete
-     */
-    navigate: (url: string, options?: NavigateOptions) => Promise<void>;
-    /**
-     * Refresh the current route
-     *
-     * @returns Promise that resolves when refresh is complete
-     */
-    refresh: () => Promise<void>;
-    /**
-     * App version from the initial server payload.
-     */
-    version: string | undefined;
-    /**
-     * URL prefix for all routes (from createRouter({ basename })).
-     * Used by Link and useRouter() to auto-prefix app-local paths.
-     */
-    basename: string | undefined;
-}
-/**
- * React context for navigation store
- *
- * Provides stable reference to the store - does NOT re-render on state changes.
- * Use useNavigation hook for reactive state access.
- */
-export declare const NavigationStoreContext: Context<NavigationStoreContextValue | null>;

package/dist/types.backup/browser/react/filter-segment-order.d.ts

@@ -1,35 +0,0 @@
-/**
- * Build the handle-collection segment order from a raw `matched` list.
- *
- * Two responsibilities:
- *
- * 1. Drop loader sub-ids ("D" followed by a digit, e.g. "M0L0D1.user") —
- *    loaders never push handles.
- *
- * 2. Place each parallel slot id (contains ".@") immediately after its
- *    parent layout/route id. Raw segment-resolution emission order does NOT
- *    guarantee this: route-mounted parallels are resolved/pushed BEFORE the
- *    route handler's segment is appended (see fresh.ts:resolveSegment for
- *    routes, and revalidation.ts ~915-919), so matched can read
- *    `[..., R0.@panel, R0]`. collectHandleData consumes segmentOrder verbatim
- *    with later-wins semantics, so without normalization the route handler's
- *    Meta would override the slot's more-specific Meta — backwards.
- *
- * Slot-id format is `<parentShortCode>.@<slotName>`; `parentShortCode` never
- * contains ".@", so splitting at the first ".@" reliably yields the parent.
- */
-export declare function filterSegmentOrder(matched: string[]): string[];
-/**
- * Build the "layouts and routes only" id list for useSegments().segmentIds.
- *
- * Strips parallel slot ids (contain ".@") and loader sub-ids ("D" followed by
- * a digit, e.g. "M0L0D1.user") without reordering. Distinct from
- * filterSegmentOrder, which also reorders slots after their parent for handle
- * collection.
- *
- * Shared by SSR (ssr/index.tsx) and the client event controller
- * (event-controller.ts) so both produce identical output; if they diverge,
- * useSegments().segmentIds rendered during SSR and after hydration disagree
- * and React reports a hydration mismatch.
- */
-export declare function filterRouteSegmentIds(matched: string[]): string[];

package/dist/types.backup/browser/react/index.d.ts

@@ -1 +0,0 @@
-export { NavigationProvider, type NavigationProviderProps, } from "./NavigationProvider.js";