@rangojs/router 0.1.1 → 0.4.0

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

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

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

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

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

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

package/dist/types.backup/browser/react/location-state-shared.d.ts

@@ -0,0 +1,162 @@
+import type { ReactElement } from "react";
+/**
+ * Internal entry representing a state value with its unique key.
+ * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
+ * that is called at navigation time (not at entry creation time).
+ */
+export interface LocationStateEntry {
+    readonly __rsc_ls_key: string;
+    readonly __rsc_ls_value: unknown;
+    readonly __rsc_ls_lazy?: boolean;
+}
+/**
+ * Options for createLocationState
+ */
+export interface LocationStateOptions {
+    /** When true, the state is cleared from history after first read (flash message pattern) */
+    flash?: boolean;
+}
+type LocationStateUnsafeFn = (...args: never[]) => unknown;
+type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type IsUnknown<T> = IsAny<T> extends true ? false : unknown extends T ? true : false;
+/**
+ * Branded error surfaced when a value that cannot live in location state is
+ * used. Location state is written into `history.state`, which uses the
+ * structured clone algorithm; React elements, functions, and symbols throw a
+ * `DataCloneError` at runtime. Carries a human-readable reason so the compile
+ * error explains the fix.
+ */
+export type LocationStateUnsafe<Reason extends string> = {
+    readonly __rango_location_state_unsafe: Reason;
+};
+/**
+ * Maps `T` to itself when it is safe to store in location state, or to a branded
+ * {@link LocationStateUnsafe} error for the disallowed parts: `unknown`, React
+ * elements (RSC/JSX content), functions, class constructors, and symbols.
+ * Recurses through arrays, `Map`, `Set`, and plain objects; structured-clone
+ * built-ins (`Date`, `RegExp`, typed arrays, `Blob`, `File`, `FormData`) pass
+ * through. Consumed by {@link ValidateLocationState}, which is intersected into a
+ * definition's value parameter so posting RSC content is a COMPILE error, not a
+ * runtime `DataCloneError`. (`any` is unguardable and remains an escape hatch.)
+ */
+export type LocationStateSafe<T> = IsUnknown<T> extends true ? LocationStateUnsafe<"location state needs an explicit, concrete type; `unknown` cannot be verified as serializable"> : T extends LocationStateUnsafeFn ? LocationStateUnsafe<"functions cannot be stored in location state"> : T extends LocationStateUnsafeCtor ? LocationStateUnsafe<"class constructors cannot be stored in location state"> : T extends symbol ? LocationStateUnsafe<"symbols cannot be stored in location state"> : T extends ReactElement ? LocationStateUnsafe<"React/RSC content cannot be stored in location state; store plain data and render it on arrival"> : T extends string | number | boolean | bigint | null | undefined ? T : T extends Date | RegExp | ArrayBuffer | ArrayBufferView | Blob | File | FormData ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<LocationStateSafe<V>> : T extends readonly unknown[] ? {
+    [K in keyof T]: LocationStateSafe<T[K]>;
+} : T extends object ? {
+    [K in keyof T]: LocationStateSafe<T[K]>;
+} : T;
+/**
+ * `unknown` (a no-op) when `T` is safe to store in location state, otherwise a
+ * branded {@link LocationStateUnsafe} object. Intersected into the value
+ * parameter of a definition's call and `write()` so POSTING RSC content (or any
+ * non-serializable value) is a compile error whose text carries the reason —
+ * without a `TState extends ...` self-constraint, which TypeScript rejects as
+ * circular (TS2313). For safe `T`, `value & unknown` collapses back to `value`,
+ * so valid usage is unchanged.
+ */
+export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>] ? unknown : LocationStateUnsafe<"location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival">;
+/**
+ * Type-safe location state definition
+ *
+ * Created via createLocationState(), used with Link's state prop
+ * and useLocationState() hook.
+ */
+export interface LocationStateDefinition<TArgs extends unknown[], TState> {
+    (...args: TArgs): LocationStateEntry;
+    /** Injected by Vite plugin - do not set manually */
+    __rsc_ls_key: string;
+    /** Whether this state auto-clears after first read */
+    readonly __rsc_ls_flash: boolean;
+    /**
+     * Read the current value from history.state.
+     *
+     * Returns undefined during SSR (no `window`). To stay hydration-safe, do
+     * NOT call read() inline during the initial render — the server returns
+     * undefined while the client may have a value preserved in history.state
+     * (e.g. after a hard reload of an entry that earlier called write()),
+     * which causes a hydration mismatch. Call read() inside an event handler
+     * or a useEffect post-mount instead, or use useLocationState() if you
+     * want React to manage subscription/hydration for you.
+     */
+    read(): TState | undefined;
+    /**
+     * Statically write the value into the current history entry under this
+     * definition's key, preserving any other keys already on history.state
+     * (e.g. router bookkeeping, other LocationState slots).
+     *
+     * This is the non-reactive counterpart to read(): it does not dispatch any
+     * event, so components reading via useLocationState() will NOT re-render
+     * until the next navigation/popstate. Use it when you only need the value
+     * to be there on the next read() or on the next mount (including after
+     * back/forward and hard refresh of the same entry).
+     *
+     * Client-only: throws when called on the server (no history available).
+     */
+    write(value: TState & ValidateLocationState<TState>): void;
+    /**
+     * Statically remove this definition's slot from the current history entry,
+     * leaving any other keys on history.state untouched. Idempotent: removing
+     * a slot that isn't present is a no-op.
+     *
+     * Same non-reactive semantics as write(): no event is dispatched, so
+     * useLocationState() readers will NOT re-render until the next navigation.
+     *
+     * Client-only: throws when called on the server (no history available).
+     */
+    delete(): void;
+}
+/**
+ * Create a type-safe location state definition
+ *
+ * The key is auto-injected by the Vite exposeInternalIds plugin as a property
+ * based on file path and export name. No manual key required.
+ *
+ * @param options Optional configuration
+ * @returns A typed state definition for use with Link and useLocationState
+ *
+ * @example
+ * ```typescript
+ * // Persistent state (survives back/forward)
+ * export const ProductState = createLocationState<{ name: string; price: number }>();
+ *
+ * // Flash state (cleared after first read)
+ * export const FlashMessage = createLocationState<{ text: string }>({ flash: true });
+ *
+ * // Use in Link
+ * <Link to="/product/123" state={[ProductState({ name: "Widget", price: 9.99 })]}>
+ *
+ * // Just-in-time typed state (getter called at click time, not render time).
+ * // Must be in a client component — the getter function can't cross the RSC boundary.
+ * <Link
+ *   to="/product/123"
+ *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+ * >
+ *
+ * // Read with hook (reactive)
+ * const product = useLocationState(ProductState);
+ *
+ * // Read without hook (snapshot, client-side only)
+ * const snap = ProductState.read();
+ *
+ * // Static write to current history entry (non-reactive, client-side only).
+ * // Survives back/forward and hard refresh; useLocationState() readers will
+ * // NOT see the new value until the next navigation. Pair with .read() or a
+ * // fresh mount.
+ * ProductState.write({ name: "Widget", price: 9.99 });
+ *
+ * // Manually clear the slot (non-reactive, client-side only).
+ * ProductState.delete();
+ * ```
+ */
+export declare function createLocationState<TState>(options?: LocationStateOptions): LocationStateDefinition<[
+    (TState | (() => TState)) & ValidateLocationState<TState>
+], TState>;
+/**
+ * Check if a value is a LocationStateEntry
+ */
+export declare function isLocationStateEntry(value: unknown): value is LocationStateEntry;
+/**
+ * Resolve state entries into a flat object for history.state
+ */
+export declare function resolveLocationStateEntries(entries: LocationStateEntry[]): Record<string, unknown>;
+export {};

package/dist/types.backup/browser/react/location-state.d.ts

@@ -0,0 +1,29 @@
+import type { LocationStateDefinition } from "./location-state-shared.js";
+export { createLocationState, isLocationStateEntry, resolveLocationStateEntries, type LocationStateEntry, type LocationStateDefinition, type LocationStateOptions, } from "./location-state-shared.js";
+/**
+ * Hook to read location state from history.state
+ *
+ * Behavior depends on the definition:
+ * - Normal state: persists across navigations, reactive to popstate
+ * - Flash state (created with { flash: true }): read once, cleared after paint
+ *
+ * Overloaded:
+ * - With definition: Returns typed state from the specific key
+ * - With type param only: Returns plain state from history.state.state
+ *
+ * @example
+ * ```typescript
+ * // Persistent state
+ * const ProductState = createLocationState<{ name: string }>();
+ * const state = useLocationState(ProductState);
+ *
+ * // Flash state (auto-clears after paint)
+ * const FlashMsg = createLocationState<{ text: string }>({ flash: true });
+ * const flash = useLocationState(FlashMsg);
+ *
+ * // Plain state access (reads from history.state.state)
+ * const state = useLocationState<{ from?: string }>();
+ * ```
+ */
+export declare function useLocationState<TArgs extends unknown[], TState>(definition: LocationStateDefinition<TArgs, TState>): TState | undefined;
+export declare function useLocationState<T = unknown>(): T | undefined;

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

@@ -0,0 +1,23 @@
+import { type Context, type ReactNode } from "react";
+/**
+ * Context for the current include() mount path.
+ *
+ * Each include() wraps its subtree with a MountContext.Provider
+ * carrying the URL prefix. Nested includes override the context,
+ * so useMount() returns the nearest mount path.
+ *
+ * Default value "/" means root-level (no include wrapping).
+ */
+export declare const MountContext: Context<string>;
+/**
+ * Provider wrapper for MountContext.
+ *
+ * RSC server components cannot use MountContext.Provider directly because
+ * .Provider is a property on the context object, not a named export.
+ * Client reference proxies on the RSC server return undefined for property
+ * access. This wrapper is a proper "use client" export that RSC can reference.
+ */
+export declare function MountContextProvider({ value, children, }: {
+    value: string;
+    children: ReactNode;
+}): ReactNode;

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

@@ -0,0 +1,14 @@
+/**
+ * Context for CSP nonce propagation to client components during SSR.
+ *
+ * The SSR renderer wraps the tree with NonceContext.Provider so that
+ * client components (e.g. MetaTags) can apply nonces to inline scripts.
+ * On the browser side, no provider is needed — the default undefined
+ * is correct since CSP nonces are a server-side HTML concern.
+ */
+import { type Context } from "react";
+export declare const NonceContext: Context<string | undefined>;
+/**
+ * Read the CSP nonce during SSR. Returns undefined on the client.
+ */
+export declare function useNonce(): string | undefined;

package/dist/types.backup/browser/react/shallow-equal.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shallow equality check for selector results.
+ * Uses Object.is for value comparison (handles NaN and +-0 correctly).
+ */
+export declare function shallowEqual<T>(a: T, b: T): boolean;

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;