@rangojs/router 0.2.0 → 0.4.0

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

@@ -0,0 +1,61 @@
+import type { TrackedActionState } from "../types.js";
+/**
+ * Server action function type
+ * Server actions have a $$id property added by the RSC compiler
+ */
+export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
+    $$id?: string;
+};
+/**
+ * Hook to track the lifecycle of a specific server action
+ *
+ * Unlike useNavigation which tracks global navigation state, useAction
+ * tracks the state of individual server action invocations.
+ *
+ * Uses the event controller for reactive state management.
+ * State is derived from the inflight actions tracked by the controller.
+ *
+ * Features:
+ * - Tracks action lifecycle: idle → loading → streaming → idle
+ * - Captures result/error locally (React handles cleanup)
+ * - If multiple actions fire, tracks only the last one
+ * - Supports selector pattern like useNavigation
+ *
+ * Matching behavior:
+ * - **Function reference**: Uses full $$id for exact matching. This is precise
+ *   and distinguishes between actions with the same name in different files.
+ * - **String**: Matches by suffix (action name after #). This is convenient
+ *   but may be ambiguous if multiple files export the same action name.
+ *
+ * @param action - Either a server action function or a string action name.
+ *   - **Function**: Must be directly imported in the client component.
+ *     Actions passed as props from server components will throw an error.
+ *   - **String**: The exported function name from your "use server" file.
+ *     Matches any action ending with "#actionName" (suffix match).
+ *
+ * @example
+ * ```tsx
+ * // Option 1: Direct import (precise matching)
+ * import { addToCart } from './actions';
+ * const actionState = useAction(addToCart);
+ *
+ * // Option 2: String-based (suffix matching)
+ * // Matches "hash#addToCart" or "src/actions.ts#addToCart"
+ * const actionState = useAction('addToCart');
+ *
+ * // With selector for specific values
+ * const isLoading = useAction(addToCart, state => state.state === 'loading');
+ * const error = useAction(addToCart, state => state.error);
+ * ```
+ *
+ * @note The selector is expected to be stable for a given hook instance.
+ * This hook tracks one projection of one action. Changing selector semantics
+ * for the same action ID without a new action event is not a supported pattern;
+ * use separate useAction() subscriptions if you need different projections.
+ *
+ * @note Actions passed as props from server components lose their metadata
+ * during RSC serialization. Use a string action name or import directly.
+ */
+export declare function useAction(action: ServerActionFunction | string): TrackedActionState;
+export declare function useAction<T>(action: ServerActionFunction | string, selector: (state: TrackedActionState) => T): T;
+export type { TrackedActionState };

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

@@ -0,0 +1,21 @@
+import type { Handle } from "../../handle.js";
+/**
+ * Hook to access collected handle data.
+ *
+ * Returns the collected value from all route segments that pushed to this handle.
+ * Re-renders when handle data changes (navigation, actions).
+ *
+ * @param handle - The handle to read
+ * @param selector - Optional selector for performance (only re-render when selected value changes)
+ *
+ * @example
+ * ```tsx
+ * // Get all breadcrumbs
+ * const breadcrumbs = useHandle(Breadcrumbs);
+ *
+ * // With selector - only re-render when last crumb changes
+ * const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
+ * ```
+ */
+export declare function useHandle<T, A>(handle: Handle<T, A>): Rango.FlightSerialize<A>;
+export declare function useHandle<T, A, S>(handle: Handle<T, A>, selector: (data: Rango.FlightSerialize<A>) => S): S;

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

@@ -0,0 +1,32 @@
+/**
+ * Client-side hook for mount-aware URL resolution.
+ *
+ * Returns an href function that automatically prepends the current
+ * include() mount prefix. Inside an include("/shop", ...) scope,
+ * the returned function resolves local paths relative to /shop.
+ *
+ * For absolute paths (outside the current mount), use the bare
+ * href() function directly instead.
+ *
+ * @returns A function that prepends the mount prefix to paths
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useHref, href } from "@rangojs/router/client";
+ *
+ * // Inside include("/shop", shopPatterns)
+ * function ShopNav() {
+ *   const href = useHref();
+ *
+ *   return (
+ *     <>
+ *       {// Local paths - auto-prefixed with /shop}
+ *       <Link to={href("/cart")}>Cart</Link>
+ *       <Link to={href("/product/widget")}>Widget</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHref(): (path: `/${string}`) => string;

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

@@ -0,0 +1,36 @@
+import { type Context } from "react";
+/**
+ * Context for Link component to provide its destination URL
+ * Used by useLinkStatus to determine if this specific link is pending
+ */
+export declare const LinkContext: Context<string | null>;
+/**
+ * Link status returned by useLinkStatus hook
+ */
+export interface LinkStatus {
+    /** Whether navigation to this link's destination is in progress */
+    pending: boolean;
+}
+/**
+ * Hook to track the pending state of a Link component
+ *
+ * Must be used inside a Link component. Returns `{ pending: true }`
+ * when navigation to this link's destination is in progress.
+ *
+ * Useful for showing inline loading indicators on individual links.
+ *
+ * @example
+ * ```tsx
+ * function LoadingIndicator() {
+ *   const { pending } = useLinkStatus();
+ *   return pending ? <Spinner /> : null;
+ * }
+ *
+ * // In your component:
+ * <Link to="/dashboard">
+ *   Dashboard
+ *   <LoadingIndicator />
+ * </Link>
+ * ```
+ */
+export declare function useLinkStatus(): LinkStatus;

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,103 @@
+/**
+ * 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 {};