@rangojs/router 0.5.1 → 0.5.2

package/dist/types.backup/browser/react/use-mount.d.ts

@@ -1,24 +0,0 @@
-/**
- * Returns the current include() mount path.
- *
- * Inside `include("/articles", blogPatterns)`, returns "/articles".
- * For nested includes, returns the nearest mount path.
- * At root level (no include), returns "/".
- *
- * @example
- * ```tsx
- * "use client";
- * import { useMount, href } from "@rangojs/router/client";
- *
- * function BlogNav({ slug }: { slug: string }) {
- *   const mount = useMount(); // "/articles"
- *   return (
- *     <>
- *       <Link to={href("/", mount)}>Blog Home</Link>
- *       <Link to={href(`/${slug}`, mount)}>Post</Link>
- *     </>
- *   );
- * }
- * ```
- */
-export declare function useMount(): string;

package/dist/types.backup/browser/react/use-navigation.d.ts

@@ -1,15 +0,0 @@
-import type { PublicNavigationState } from "../types.js";
-/**
- * Hook to access reactive navigation state with optional selector for performance.
- *
- * Returns state only. For actions (push, replace, refresh, prefetch),
- * use useRouter() instead.
- *
- * @example
- * ```tsx
- * const { state, location } = useNavigation();
- * const isLoading = useNavigation(nav => nav.state === 'loading');
- * ```
- */
-export declare function useNavigation(): PublicNavigationState;
-export declare function useNavigation<T>(selector: (state: PublicNavigationState) => T): T;

package/dist/types.backup/browser/react/use-params.d.ts

@@ -1,21 +0,0 @@
-/**
- * Hook to access the current route params.
- *
- * Returns the merged route params from the matched route.
- * Updates when navigation completes, not during pending navigation.
- *
- * @example
- * ```tsx
- * // Route: /products/:productId
- * const params = useParams();
- * // { productId: "123" }
- *
- * // Annotate the expected shape via a generic
- * const { productId } = useParams<{ productId: string }>();
- *
- * // With selector
- * const productId = useParams(p => p.productId);
- * ```
- */
-export declare function useParams<T extends object = Record<string, string | undefined>>(): Readonly<T>;
-export declare function useParams<T>(selector: (params: Record<string, string | undefined>) => T): T;

package/dist/types.backup/browser/react/use-pathname.d.ts

@@ -1,13 +0,0 @@
-/**
- * Hook to access the current pathname.
- *
- * Returns the committed pathname string (excludes search params and hash).
- * Updates when navigation completes, not during pending navigation.
- *
- * @example
- * ```tsx
- * const pathname = usePathname();
- * // "/products/123"
- * ```
- */
-export declare function usePathname(): string;

package/dist/types.backup/browser/react/use-reverse.d.ts

@@ -1,40 +0,0 @@
-import type { LocalReverseFunction } from "../../reverse.js";
-type RouteEntry = string | {
-    readonly path: string;
-};
-type LocalRouteMap = Readonly<Record<string, RouteEntry>>;
-/**
- * Mount-aware reverse function for a locally-imported `routes` map.
- *
- * The `routes` map you pass IS the scope: `reverse("name")` looks the name up
- * in that map (verbatim), prefixes the result with the surrounding `include()`
- * mount path via `useMount()`, and substitutes params — auto-filling from the
- * current matched route's params, with explicit params overriding. A module's
- * components can therefore reverse their own routes without knowing where the
- * module is mounted: include it under any prefix and the URLs resolve correctly.
- *
- * The leading dot is optional and cosmetic: `reverse("post")` and
- * `reverse(".post")` resolve identically. The dot exists only as a readability
- * convention and for parity with `ctx.reverse(".name")` on the server; here the
- * passed map is the scope, so there is no separate global namespace to
- * disambiguate and the dot carries no meaning.
- *
- * @example
- * ```tsx
- * "use client";
- * import { Link, useReverse } from "@rangojs/router/client";
- * import { routes as blogRoutes } from "../urls/blog.gen.js";
- *
- * function BlogNav() {
- *   const reverse = useReverse(blogRoutes);
- *   return (
- *     <>
- *       <Link to={reverse("index")}>Blog</Link>
- *       <Link to={reverse("post", { postId: "hello" })}>Post</Link>
- *     </>
- *   );
- * }
- * ```
- */
-export declare function useReverse<const TRoutes extends LocalRouteMap>(routes: TRoutes): LocalReverseFunction<TRoutes>;
-export {};

package/dist/types.backup/browser/react/use-router.d.ts

@@ -1,23 +0,0 @@
-import type { RouterInstance } from "../types.js";
-/**
- * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
- *
- * Returns a STABLE reference that never changes, so components using
- * useRouter() do not re-render on navigation state changes.
- * For reactive navigation state, use useNavigation() instead.
- *
- * Methods read `basename` from the context on each call. It is set once from
- * the initial payload and is stable within a session — a cross-app navigation
- * is a full document load (X-RSC-Reload), so the target app mounts fresh with
- * its own basename.
- *
- * @example
- * ```tsx
- * const router = useRouter();
- * router.push("/products");
- * router.replace("/login", { scroll: false });
- * router.prefetch("/dashboard");
- * router.back();
- * ```
- */
-export declare function useRouter(): RouterInstance;

package/dist/types.backup/browser/react/use-search-params.d.ts

@@ -1,19 +0,0 @@
-import type { ReadonlyURLSearchParams } from "../types.js";
-/**
- * Hook to access the current URL search params.
- *
- * Returns a read-only URLSearchParams object from the committed location.
- * Updates when navigation completes, not during pending navigation.
- *
- * Note: During SSR the search params are not available (the server only sends
- * the pathname). The hook returns empty params during SSR and syncs from
- * the browser URL on mount.
- *
- * @example
- * ```tsx
- * const searchParams = useSearchParams();
- * const query = searchParams.get("q"); // "react"
- * const page = searchParams.get("page"); // "2"
- * ```
- */
-export declare function useSearchParams(): ReadonlyURLSearchParams;

package/dist/types.backup/browser/react/use-segments.d.ts

@@ -1,29 +0,0 @@
-/**
- * Segments state returned by useSegments hook
- */
-export interface SegmentsState {
-    /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
-    path: readonly string[];
-    /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
-    segmentIds: readonly string[];
-    /** Current URL location */
-    location: URL;
-}
-/**
- * Hook to access current route segments with optional selector for performance
- *
- * Provides information about the current URL path and matched route segments.
- * Uses the event controller for reactive state management.
- *
- * @example
- * ```tsx
- * // Get full segments state
- * const { path, segmentIds, location } = useSegments();
- *
- * // Use selector for specific values (better performance)
- * const path = useSegments(s => s.path);
- * const isShopRoute = useSegments(s => s.path[0] === "shop");
- * ```
- */
-export declare function useSegments(): SegmentsState;
-export declare function useSegments<T>(selector: (state: SegmentsState) => T): T;

package/dist/types.backup/browser/response-adapter.d.ts

@@ -1,58 +0,0 @@
-type HeaderResult = {
-    url: string;
-} | "blocked" | null;
-/**
- * Extract and validate an RSC response header URL (X-RSC-Reload, X-RSC-Redirect).
- * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
- */
-export declare function extractRscHeaderUrl(response: Response, header: string): HeaderResult;
-/**
- * Empty 200 response that won't choke Flight parsing.
- * Used when a header URL is blocked by origin validation.
- */
-export declare function emptyResponse(): Response;
-/**
- * Whether an RSC content response carries a server-stamped router identity
- * (`X-RSC-Router-Id`) that DIFFERS from the id this client expects (its own
- * routerId, also sent as `_rsc_rid`). Pre-decode integrity check: lets a caller
- * refuse a foreign app's payload before `createFromFetch` imports its chunks.
- *
- * True ONLY when both the header and the expected id are present and differ. An
- * absent header (control-only reload/redirect responses are not stamped) or an
- * absent expected id (e.g. before the client is seeded) is a pass-through —
- * never a false reject.
- */
-export declare function isForeignRouterId(response: Response, expectedId: string | undefined): boolean;
-/**
- * Handle the X-RSC-Reload control header (server requests a full page reload on
- * a version mismatch). Returns a short-circuit response when the header is
- * present -- emptyResponse() if the URL was blocked by origin validation, or a
- * never-resolving promise while the page reloads -- and null when absent, so
- * the caller continues processing (e.g. the X-RSC-Redirect check). Scoped to
- * X-RSC-Reload only; redirect handling differs between callers.
- */
-export declare function handleReloadHeader(response: Response, opts: {
-    onBlocked: () => void;
-    onReload: (url: string) => void;
-}): Response | Promise<Response> | null;
-/**
- * Tee a response body for RSC parsing and stream completion tracking.
- * Returns a new Response with one branch; the other is consumed to detect
- * end-of-stream, calling onComplete when done.
- *
- * `onComplete` receives `endedCleanly`: true only on a normal EOF drain, false
- * on a read error or an abort (the signal cancelled the reader). Callers that
- * gate a "fully complete" fast path (e.g. prefetch's `entry.complete`) must
- * treat a non-clean end as incomplete — a broken stream is not complete data.
- *
- * If the response has no body, onComplete fires synchronously with `true`
- * (an empty body is a clean, complete stream).
- * If signal is provided, an abort cancels the tracking reader.
- *
- * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
- * low-priority prefetch that is aborted or never consumed can error its stream
- * benignly, which is not worth surfacing. The fresh-navigation path keeps the
- * log (default), where a stream error reflects a real failed navigation.
- */
-export declare function teeWithCompletion(response: Response, onComplete: (endedCleanly: boolean) => void, signal?: AbortSignal, silent?: boolean): Response;
-export {};

package/dist/types.backup/browser/rsc-router.d.ts

@@ -1,141 +0,0 @@
-import React from "react";
-import type { RscPayload, RscBrowserDependencies, NavigationStore, NavigationBridge } from "./types.js";
-import type { EventController } from "./event-controller.js";
-import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
-/**
- * Options for initializing the browser app
- */
-export interface InitBrowserAppOptions {
-    /**
-     * RSC stream containing the initial payload (from rsc-html-stream/client)
-     */
-    rscStream: ReadableStream<Uint8Array>;
-    /**
-     * RSC browser dependencies from @vitejs/plugin-rsc/browser
-     */
-    deps: RscBrowserDependencies;
-    /**
-     * Optional store configuration
-     */
-    storeOptions?: {
-        /**
-         * Maximum number of history entries to cache
-         * @default 10
-         */
-        cacheSize?: number;
-    };
-    /**
-     * Enable global link interception for SPA navigation.
-     * When enabled, clicks on same-origin anchor elements are intercepted
-     * and handled via client-side navigation instead of full page loads.
-     *
-     * Links rendered with the Link component handle their own navigation
-     * regardless of this setting.
-     *
-     * Set to false to disable global interception and rely solely on
-     * Link components for SPA navigation.
-     *
-     * @default true
-     */
-    linkInterception?: boolean;
-    /**
-     * Theme configuration from router.
-     * When provided, enables theme support via useTheme hook.
-     * Pass router.themeConfig here to enable theme features.
-     *
-     * @example
-     * ```tsx
-     * import { router } from "./router.js";
-     *
-     * await initBrowserApp({
-     *   rscStream,
-     *   deps: rscBrowser,
-     *   themeConfig: router.themeConfig,
-     *   initialTheme: document.documentElement.className.includes("dark") ? "dark" : "light",
-     * });
-     * ```
-     */
-    themeConfig?: ResolvedThemeConfig | null;
-    /**
-     * Initial theme from server (typically read from cookie).
-     * Only used when themeConfig is provided.
-     */
-    initialTheme?: Theme;
-}
-/**
- * Result from initializing the browser app
- */
-export interface BrowserAppContext {
-    store: NavigationStore;
-    eventController: EventController;
-    bridge: NavigationBridge;
-    initialPayload: RscPayload;
-    initialTree: React.ReactNode | Promise<React.ReactNode>;
-    /** Theme configuration (null if theme not enabled) */
-    themeConfig?: ResolvedThemeConfig | null;
-    /** Initial theme from server */
-    initialTheme?: Theme;
-    /** Whether connection warmup is enabled */
-    warmupEnabled?: boolean;
-    /** Whether the hydrated tree should be wrapped in React.StrictMode */
-    strictMode?: boolean;
-    /** App version for prefetch version mismatch detection */
-    version?: string;
-    /**
-     * App-shell ref, read through on each render so renderSegments and the
-     * NavigationProvider see rootLayout/basename/version without closing over a
-     * stale snapshot. Set once from the initial payload and 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. Theme, warmup, and
-     * prefetch TTL are document-lifetime too (see AppShell).
-     */
-    appShellRef?: import("./app-shell.js").AppShellRef;
-}
-/**
- * Initialize the browser app. Must be called before rendering Rango.
- *
- * This function:
- * - Loads the initial RSC payload from the stream
- * - Creates the navigation store and event controller
- * - Sets up action and navigation bridges
- * - Configures HMR support
- */
-export declare function initBrowserApp(options: InitBrowserAppOptions): Promise<BrowserAppContext>;
-/**
- * Get the browser app context. Throws if initBrowserApp hasn't been called.
- */
-export declare function getBrowserAppContext(): BrowserAppContext;
-/**
- * Reset the browser app context (for testing)
- */
-export declare function resetBrowserAppContext(): void;
-/**
- * Props for the Rango component
- */
-export interface RangoProps {
-}
-/**
- * Rango component - renders the RSC router with all internal wiring.
- *
- * Must be called after initBrowserApp() has completed.
- *
- * @example
- * ```tsx
- * import { initBrowserApp, Rango } from "rsc-router/browser";
- * import { rscStream } from "rsc-html-stream/client";
- * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
- *
- * async function main() {
- *   await initBrowserApp({ rscStream, deps: rscBrowser });
- *
- *   hydrateRoot(
- *     document,
- *     <React.StrictMode>
- *       <Rango />
- *     </React.StrictMode>
- *   );
- * }
- * main();
- * ```
- */
-export declare function Rango(_props: RangoProps): React.ReactElement;

package/dist/types.backup/browser/scroll-restoration.d.ts

@@ -1,103 +0,0 @@
-/**
- * Scroll Restoration Module
- *
- * Provides scroll position persistence across navigations, following React Router v7 patterns:
- * - Saves scroll positions to sessionStorage keyed by unique history entry key
- * - Restores scroll on back/forward navigation
- * - Scrolls to top on new navigation (unless scroll: false)
- * - Supports hash link scrolling
- */
-/**
- * Custom getKey function for determining scroll restoration key
- */
-type GetScrollKeyFunction = (location: {
-    pathname: string;
-    search: string;
-    hash: string;
-    key: string;
-}) => string;
-/**
- * Generate a unique key for the current history entry.
- * Uses history.state.key if available, otherwise generates and stores a new one.
- */
-export declare function getHistoryStateKey(): string;
-/**
- * Get the scroll restoration key for a location.
- * Uses custom getKey function if set, otherwise uses history state key.
- */
-export declare function getScrollKey(): string;
-/**
- * Initialize scroll restoration.
- * Sets manual scroll restoration mode and loads saved positions from sessionStorage.
- */
-export declare function initScrollRestoration(options?: {
-    getKey?: GetScrollKeyFunction;
-}): () => void;
-/**
- * Save the current scroll position for the current history entry.
- * Maintains bounded size by evicting oldest entries when the limit is exceeded.
- */
-export declare function saveCurrentScrollPosition(): void;
-/**
- * Persist scroll positions to sessionStorage.
- * If the write fails (typically QuotaExceededError), evict the oldest ~1/4 of
- * entries ONCE and retry the write a single time; if that still fails, remove
- * our storage key entirely so we don't block other sessionStorage consumers.
- * This is a single evict-then-retry-then-clear ladder, not a loop.
- *
- * Exported so that single eviction/retry/clear ladder is unit-testable directly.
- * The browser drives it from the `pagehide` handler.
- */
-export declare function persistToSessionStorage(): void;
-/**
- * Get the saved scroll position for a history key
- */
-export declare function getSavedScrollPosition(key?: string): number | undefined;
-/**
- * Cancel any pending scroll restoration polling
- */
-export declare function cancelScrollRestorationPolling(): void;
-/**
- * Restore scroll position for the current history entry.
- * Returns true if position was fully restored, false otherwise.
- *
- * @param options.retryIfStreaming - If true, poll while streaming until we can scroll to target
- * @param options.isStreaming - Function to check if streaming is in progress
- */
-export declare function restoreScrollPosition(options?: {
-    retryIfStreaming?: boolean;
-    isStreaming?: () => boolean;
-}): boolean;
-/**
- * Handle hash link scrolling.
- * Scrolls to element with matching ID if hash is present.
- * Returns true if scrolled to element, false otherwise.
- */
-export declare function scrollToHash(): boolean;
-/**
- * Scroll to top of page
- */
-export declare function scrollToTop(): void;
-/**
- * Handle scroll for a new navigation.
- * - Saves current position before navigating
- * - Ensures new history entry has a key
- */
-export declare function handleNavigationStart(): void;
-/**
- * Handle scroll after navigation completes.
- * @param options.restore - If true, restore saved position (for popstate)
- * @param options.scroll - If false, don't scroll at all
- * @param options.isStreaming - Function to check if streaming is in progress (for retry logic)
- */
-export declare function handleNavigationEnd(options: {
-    restore?: boolean;
-    scroll?: boolean;
-    isStreaming?: () => boolean;
-}): void;
-/**
- * Update the history state key after pushState/replaceState.
- * Call this after changing history to ensure new entry has a key.
- */
-export declare function ensureHistoryKey(): void;
-export {};

package/dist/types.backup/browser/segment-reconciler.d.ts

@@ -1,74 +0,0 @@
-import type { ResolvedSegment } from "./types.js";
-/**
- * Determines the merging behavior for segment reconciliation.
- *
- * - 'action': From server-action-bridge's own merge. Always merges loaders,
- *   always preserves cached loading (even undefined), never clears cached
- *   segment loading.
- * - 'navigation': From partial-update during normal navigation. Does NOT merge
- *   loaders, preserves cached loading only when defined, clears truthy loading
- *   on cached segments not in server diff.
- * - 'stale-revalidation': From partial-update during stale revalidation or
- *   action-triggered refetch. Merges loaders, always preserves cached loading
- *   (same as action), clears truthy loading on cached segments not in server diff.
- */
-export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
-export interface ReconcileInput {
-    actor: ReconcileActor;
-    /** All segment IDs the server expects the client to have (matched array) */
-    matched: string[];
-    /** Segment IDs that changed (diff array) */
-    diff: string[];
-    /** Segments returned from server (raw array, keyed internally by ID) */
-    serverSegments: ResolvedSegment[];
-    /** Cached segments from current page (raw array, keyed internally by ID) */
-    cachedSegments: ResolvedSegment[];
-    /** When true, diff segments not in matched are inserted after their parent
-     *  layout. Used during navigation when consolidation fetch returns loader
-     *  segments that aren't in the matched array. */
-    insertMissingDiff?: boolean;
-}
-export interface ReconcileResult {
-    /** All merged segments in matched order (for caching and committing) */
-    segments: ResolvedSegment[];
-    /** Main segments excluding intercepts (for rendering) */
-    mainSegments: ResolvedSegment[];
-    /** Intercept segments only (passed via render options) */
-    interceptSegments: ResolvedSegment[];
-}
-/**
- * Single source of truth for merging server segments with cached segments.
- *
- * Replaces the duplicated merge loops in server-action-bridge.ts and
- * partial-update.ts. The actor parameter controls the subtle behavioral
- * differences between action and navigation merging:
- *
- * Loading preservation:
- * - action/stale-revalidation: Always preserves cached loading value when it
- *   differs from server (even when cached is undefined). This prevents tree
- *   structure changes that would remount components and destroy useActionState
- *   during action revalidation or action-triggered refetch.
- * - navigation: Preserves cached loading only when the cached value is defined
- *   (not undefined). When cached is undefined, lets server value through
- *   because we're building a new tree.
- *
- * Loader merging:
- * - action/stale-revalidation: Merges partial loader data when server returns
- *   fewer loaders than cached (revalidation only updated some loaders).
- * - navigation: Does not merge (full navigation fetches complete data).
- *
- * Cached segment handling (segments in matched but not in server response):
- * - action: Returns cached segment as-is (preserve tree structure).
- * - navigation/stale-revalidation: Clears truthy loading to undefined
- *   (prevents showing stale skeletons), but preserves loading=false
- *   (suppressed boundary is structural).
- */
-export declare function reconcileSegments(input: ReconcileInput): ReconcileResult;
-/**
- * Reconcile error segments with cached segments.
- *
- * For error responses, the server returns the error boundary segment.
- * This function overlays error segments onto the full cached tree,
- * preserving sibling layouts that aren't in the error parent chain.
- */
-export declare function reconcileErrorSegments(cachedSegments: ResolvedSegment[], errorSegments: ResolvedSegment[]): ReconcileResult;

package/dist/types.backup/browser/segment-structure-assert.d.ts

@@ -1,16 +0,0 @@
-import type { ResolvedSegment } from "./types.js";
-/**
- * Assert that merging a server segment with a cached segment won't change
- * the React tree structure. Logs a warning in development when a mismatch
- * is detected.
- *
- * This catches the class of bugs where `loading()` with `{ ssr: false }`
- * produces `loading=false` on SSR but `loading=<skeleton>` on actions,
- * causing React to remount LoaderBoundary/RouteContentWrapper and destroy
- * client state (useActionState, refs, etc.).
- *
- * @param cached - The currently cached segment
- * @param incoming - The new segment from server
- * @param context - Where this merge is happening (for the warning message)
- */
-export declare function assertSegmentStructure(cached: ResolvedSegment, incoming: ResolvedSegment, context: string): void;

package/dist/types.backup/browser/server-action-bridge.d.ts

@@ -1,29 +0,0 @@
-import type { ServerActionBridge, ServerActionBridgeConfig } from "./types.js";
-import type { EventController } from "./event-controller.js";
-/**
- * Extended configuration for server action bridge with event controller
- */
-export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
-    eventController: EventController;
-    /** Callback to trigger SPA navigation (for action redirects) */
-    onNavigate?: (url: string, options?: {
-        state?: unknown;
-        replace?: boolean;
-        _skipCache?: boolean;
-    }) => Promise<void>;
-}
-/**
- * Create a server action bridge for handling RSC server actions
- *
- * The bridge registers a callback with the RSC runtime that handles:
- * - Encoding action arguments
- * - Sending action requests to the server
- * - Processing responses and updating UI
- * - Managing concurrent action requests via event controller
- * - HMR resilience (refetching if segments are missing)
- *
- * @param config - Bridge configuration
- * @returns ServerActionBridge instance
- */
-export declare function createServerActionBridge(config: ServerActionBridgeConfigWithController): ServerActionBridge;
-export { createServerActionBridge as default };