@rangojs/router 0.4.0 → 0.4.2

package/dist/browser/react/index.js

@@ -0,0 +1,22 @@
+// React exports for browser navigation
+// Hook with Zustand-style selectors
+export { useNavigation, } from "./use-navigation.js";
+// Action state tracking hook
+export { useAction } from "./use-action.js";
+// Segments state hook
+export { useSegments, initSegmentsSync } from "./use-segments.js";
+// Handle data hook
+export { useHandle, initHandleDataSync } from "./use-handle.js";
+// Client cache controls hook
+export { useClientCache, } from "./use-client-cache.js";
+// Provider
+export { NavigationProvider, } from "./NavigationProvider.js";
+// Context (for advanced usage)
+export { NavigationStoreContext, } from "./context.js";
+// Link component
+export { Link, } from "./Link.js";
+// Link status hook
+export { useLinkStatus } from "./use-link-status.js";
+// Scroll restoration
+export { ScrollRestoration, useScrollRestoration, } from "./ScrollRestoration.js";
+//# sourceMappingURL=index.js.map

package/dist/browser/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/react/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AAEvC,oCAAoC;AACpC,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAE7B,6BAA6B;AAC7B,OAAO,EAAE,SAAS,EAA2B,MAAM,iBAAiB,CAAC;AAErE,sBAAsB;AACtB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAsB,MAAM,mBAAmB,CAAC;AAEtF,mBAAmB;AACnB,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEhE,6BAA6B;AAC7B,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAC;AAE/B,WAAW;AACX,OAAO,EACL,kBAAkB,GAEnB,MAAM,yBAAyB,CAAC;AAEjC,+BAA+B;AAC/B,OAAO,EACL,sBAAsB,GAEvB,MAAM,cAAc,CAAC;AAEtB,iBAAiB;AACjB,OAAO,EACL,IAAI,GAGL,MAAM,WAAW,CAAC;AAEnB,mBAAmB;AACnB,OAAO,EAAE,aAAa,EAAmB,MAAM,sBAAsB,CAAC;AAEtE,qBAAqB;AACrB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,GAErB,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,63 @@
+/**
+ * Shared location state utilities - works in both RSC and client contexts
+ * No "use client" directive so it can be imported from RSC
+ */
+/**
+ * Internal entry representing a state value with its unique key
+ */
+export interface LocationStateEntry {
+    readonly __rsc_ls_key: string;
+    readonly __rsc_ls_value: unknown;
+}
+/**
+ * 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;
+    readonly __rsc_ls_key: string;
+}
+/**
+ * Create a type-safe location state definition
+ *
+ * The key is auto-generated by the Vite exposeInternalIds plugin based on
+ * file path and export name. No manual key required.
+ *
+ * @param key Auto-injected by Vite plugin, do not provide manually
+ * @returns A typed state definition for use with Link and useLocationState
+ *
+ * @example
+ * ```typescript
+ * // Define typed state (key auto-generated from file + export)
+ * export const ProductState = createLocationState<{ name: string; price: number }>();
+ *
+ * // Use in Link - state is captured at click time
+ * <Link to="/product/123" state={[ProductState({ name: product.name, price: product.price })]}>
+ *   View Product
+ * </Link>
+ *
+ * // Multiple states
+ * <Link to="/checkout" state={[ProductState(productData), CartState(cartData)]}>
+ *   Checkout
+ * </Link>
+ *
+ * // For lazy evaluation (click-time), pass a getter
+ * <Link to="/product" state={[ProductState(() => ({ name: product.name }))]}>
+ *
+ * // Read with type safety
+ * const productState = useLocationState(ProductState);
+ * // productState: { name: string; price: number } | undefined
+ * ```
+ */
+export declare function createLocationState<TState>(key?: string): LocationStateDefinition<[TState | (() => 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>;
+//# sourceMappingURL=location-state-shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"location-state-shared.d.ts","sourceRoot":"","sources":["../../../src/browser/react/location-state-shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,MAAM;IACtE,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,kBAAkB,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EACxC,GAAG,CAAC,EAAE,MAAM,GACX,uBAAuB,CAAC,CAAC,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAgC5D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAQhF;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kBAAkB,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB"}

package/dist/browser/react/location-state-shared.js

@@ -0,0 +1,81 @@
+/**
+ * Shared location state utilities - works in both RSC and client contexts
+ * No "use client" directive so it can be imported from RSC
+ */
+// Track used keys to detect duplicates in development
+const usedKeys = new Set();
+/**
+ * Create a type-safe location state definition
+ *
+ * The key is auto-generated by the Vite exposeInternalIds plugin based on
+ * file path and export name. No manual key required.
+ *
+ * @param key Auto-injected by Vite plugin, do not provide manually
+ * @returns A typed state definition for use with Link and useLocationState
+ *
+ * @example
+ * ```typescript
+ * // Define typed state (key auto-generated from file + export)
+ * export const ProductState = createLocationState<{ name: string; price: number }>();
+ *
+ * // Use in Link - state is captured at click time
+ * <Link to="/product/123" state={[ProductState({ name: product.name, price: product.price })]}>
+ *   View Product
+ * </Link>
+ *
+ * // Multiple states
+ * <Link to="/checkout" state={[ProductState(productData), CartState(cartData)]}>
+ *   Checkout
+ * </Link>
+ *
+ * // For lazy evaluation (click-time), pass a getter
+ * <Link to="/product" state={[ProductState(() => ({ name: product.name }))]}>
+ *
+ * // Read with type safety
+ * const productState = useLocationState(ProductState);
+ * // productState: { name: string; price: number } | undefined
+ * ```
+ */
+export function createLocationState(key) {
+    if (!key && process.env.NODE_ENV !== "production") {
+        throw new Error("[rsc-router] createLocationState is missing a key. " +
+            "Make sure the exposeInternalIds Vite plugin is enabled and " +
+            "the state is exported with: export const MyState = createLocationState(...)");
+    }
+    const fullKey = `__rsc_ls_${key}`;
+    // Warn about duplicate keys in development
+    if (process.env.NODE_ENV !== "production" && usedKeys.has(fullKey)) {
+        console.warn(`[rsc-router] Duplicate location state key "${key}". ` +
+            `Each createLocationState call should have a unique key.`);
+    }
+    usedKeys.add(fullKey);
+    const definition = Object.assign((stateOrGetter) => ({
+        __rsc_ls_key: fullKey,
+        // Resolve getter immediately - lazy evaluation happens via Link's stateRef pattern
+        __rsc_ls_value: typeof stateOrGetter === "function"
+            ? stateOrGetter()
+            : stateOrGetter,
+    }), { __rsc_ls_key: fullKey });
+    return definition;
+}
+/**
+ * Check if a value is a LocationStateEntry
+ */
+export function isLocationStateEntry(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "__rsc_ls_key" in value &&
+        "__rsc_ls_value" in value &&
+        typeof value.__rsc_ls_key === "string");
+}
+/**
+ * Resolve state entries into a flat object for history.state
+ */
+export function resolveLocationStateEntries(entries) {
+    const result = {};
+    for (const entry of entries) {
+        result[entry.__rsc_ls_key] = entry.__rsc_ls_value;
+    }
+    return result;
+}
+//# sourceMappingURL=location-state-shared.js.map

package/dist/browser/react/location-state-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-state-shared.js","sourceRoot":"","sources":["../../../src/browser/react/location-state-shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH,sDAAsD;AACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAY;IAEZ,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,qDAAqD;YACnD,6DAA6D;YAC7D,6EAA6E,CAChF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,GAAG,EAAE,CAAC;IAElC,2CAA2C;IAC3C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACnE,OAAO,CAAC,IAAI,CACV,8CAA8C,GAAG,KAAK;YACpD,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAEtB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAC9B,CAAC,aAAsC,EAAsB,EAAE,CAAC,CAAC;QAC/D,YAAY,EAAE,OAAO;QACrB,mFAAmF;QACnF,cAAc,EACZ,OAAO,aAAa,KAAK,UAAU;YACjC,CAAC,CAAE,aAA8B,EAAE;YACnC,CAAC,CAAC,aAAa;KACpB,CAAC,EACF,EAAE,YAAY,EAAE,OAAO,EAAE,CAC1B,CAAC;IAEF,OAAO,UAAwE,CAAC;AAClF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,cAAc,IAAI,KAAK;QACvB,gBAAgB,IAAI,KAAK;QACzB,OAAQ,KAA4B,CAAC,YAAY,KAAK,QAAQ,CAC/D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAA6B;IAE7B,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,23 @@
+import type { LocationStateDefinition } from "./location-state-shared.js";
+export { createLocationState, isLocationStateEntry, resolveLocationStateEntries, type LocationStateEntry, type LocationStateDefinition, } from "./location-state-shared.js";
+/**
+ * Hook to read location state from history.state
+ *
+ * Overloaded:
+ * - With definition: Returns typed state from the specific key
+ * - With type param only: Returns legacy state from history.state.state (backwards compat)
+ *
+ * @example
+ * ```typescript
+ * // Typed access with definition (recommended)
+ * const ProductState = createLocationState<{ name: string }>("product");
+ * const state = useLocationState(ProductState);
+ * // state: { name: string } | undefined
+ *
+ * // Legacy typed access (backwards compatible)
+ * const legacyState = 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;
+//# sourceMappingURL=location-state.d.ts.map

package/dist/browser/react/location-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-state.d.ts","sourceRoot":"","sources":["../../../src/browser/react/location-state.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAG1E,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,MAAM,EAC9D,UAAU,EAAE,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,GACjD,MAAM,GAAG,SAAS,CAAC;AACtB,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,SAAS,CAAC"}

package/dist/browser/react/location-state.js

@@ -0,0 +1,29 @@
+"use client";
+import { useState, useEffect } from "react";
+// Re-export shared utilities and types
+export { createLocationState, isLocationStateEntry, resolveLocationStateEntries, } from "./location-state-shared.js";
+export function useLocationState(definition) {
+    const [state, setState] = useState(() => {
+        if (typeof window === "undefined")
+            return undefined;
+        if (definition) {
+            return window.history.state?.[definition.__rsc_ls_key];
+        }
+        // Legacy: return history.state.state for backwards compatibility
+        return window.history.state?.state;
+    });
+    useEffect(() => {
+        const handlePopstate = () => {
+            if (definition) {
+                setState(window.history.state?.[definition.__rsc_ls_key]);
+            }
+            else {
+                setState(window.history.state?.state);
+            }
+        };
+        window.addEventListener("popstate", handlePopstate);
+        return () => window.removeEventListener("popstate", handlePopstate);
+    }, [definition]);
+    return state;
+}
+//# sourceMappingURL=location-state.js.map

package/dist/browser/react/location-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-state.js","sourceRoot":"","sources":["../../../src/browser/react/location-state.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAG5C,uCAAuC;AACvC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,GAG5B,MAAM,4BAA4B,CAAC;AAwBpC,MAAM,UAAU,gBAAgB,CAC9B,UAAmD;IAEnD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAqB,GAAG,EAAE;QAC1D,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO,SAAS,CAAC;QACpD,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,UAAU,CAAC,YAAY,CAAuB,CAAC;QAC/E,CAAC;QACD,iEAAiE;QACjE,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAA2B,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,cAAc,GAAG,GAAG,EAAE;YAC1B,IAAI,UAAU,EAAE,CAAC;gBACf,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,UAAU,CAAC,YAAY,CAAuB,CAAC,CAAC;YAClF,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAA2B,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;QACpD,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACtE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjB,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,24 @@
+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;
+//# sourceMappingURL=mount-context.d.ts.map

package/dist/browser/react/mount-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-context.d.ts","sourceRoot":"","sources":["../../../src/browser/react/mount-context.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgC,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEnF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,MAAM,CAA8B,CAAC;AAExE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,SAAS,CAEZ"}

package/dist/browser/react/mount-context.js

@@ -0,0 +1,24 @@
+"use client";
+import { createContext, createElement } 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 const MountContext = createContext("/");
+/**
+ * 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 function MountContextProvider({ value, children, }) {
+    return createElement(MountContext, { value }, children);
+}
+//# sourceMappingURL=mount-context.js.map

package/dist/browser/react/mount-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-context.js","sourceRoot":"","sources":["../../../src/browser/react/mount-context.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,aAAa,EAAgC,MAAM,OAAO,CAAC;AAEnF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAoB,aAAa,CAAS,GAAG,CAAC,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,EACnC,KAAK,EACL,QAAQ,GAIT;IACC,OAAO,aAAa,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC1D,CAAC"}

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

@@ -0,0 +1,64 @@
+import type { TrackedActionState } from "../types.js";
+/**
+ * Extract action ID from a server action function or string.
+ *
+ * Actions passed as props from server components lose their metadata
+ * during RSC serialization - use a string action name instead.
+ */
+export declare function getActionId(action: ServerActionFunction | string): string;
+/**
+ * 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 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 };
+//# sourceMappingURL=use-action.d.ts.map

package/dist/browser/react/use-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-action.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-action.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAwB,MAAM,aAAa,CAAC;AA0B5E;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,MAAM,CAiCzE;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,oBAAoB,GAAG,MAAM,GACpC,kBAAkB,CAAC;AACtB,wBAAgB,SAAS,CAAC,CAAC,EACzB,MAAM,EAAE,oBAAoB,GAAG,MAAM,EACrC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,CAAC,GACzC,CAAC,CAAC;AAsGL,YAAY,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/browser/react/use-action.js

@@ -0,0 +1,134 @@
+"use client";
+import { useContext, useState, useEffect, useRef, useOptimistic, startTransition, } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { invariant } from "../../errors.js";
+/**
+ * Default action state (idle with no payload)
+ */
+const DEFAULT_ACTION_STATE = {
+    state: "idle",
+    actionId: null,
+    payload: null,
+    error: null,
+    result: null,
+};
+/**
+ * Normalize action ID - returns the ID as-is
+ *
+ * Server actions have IDs like "hash#actionName" or "src/actions.ts#actionName".
+ * When using function references, we use the full ID for exact matching.
+ * When using strings, the event controller supports suffix matching
+ * (e.g., "addToCart" matches "hash#addToCart").
+ */
+function normalizeActionId(actionId) {
+    return actionId;
+}
+/**
+ * Extract action ID from a server action function or string.
+ *
+ * Actions passed as props from server components lose their metadata
+ * during RSC serialization - use a string action name instead.
+ */
+export function getActionId(action) {
+    invariant(typeof action === "function" || typeof action === "string", `useAction: action must be a function or string, got ${typeof action}`);
+    const actionId = action?.$$id;
+    if (actionId) {
+        return normalizeActionId(actionId);
+    }
+    // If action is a string, use it directly
+    if (typeof action === "string") {
+        return action;
+    }
+    // If we get here, this is likely an action passed as prop from a server component
+    // These lose their metadata during RSC serialization
+    throw new Error(`useAction: Cannot extract action ID from function reference.
+
+This typically happens when an action is passed as a prop from a server component.
+Actions passed through RSC lose their metadata during serialization.
+
+Solutions:
+1. Import the action directly in your client component:
+   import { myAction } from './actions';
+   const state = useAction(myAction);
+
+2. Use the action name as a string:
+   const state = useAction("myAction");
+
+The string must match the exported function name from your "use server" file.`);
+}
+export function useAction(action, selector) {
+    const ctx = useContext(NavigationStoreContext);
+    const actionId = typeof window !== "undefined" && typeof document !== "undefined"
+        ? getActionId(action)
+        : "";
+    // Base state for useOptimistic
+    const [baseState, setBaseState] = useState(() => {
+        if (!ctx) {
+            return selector ? selector(DEFAULT_ACTION_STATE) : DEFAULT_ACTION_STATE;
+        }
+        const state = ctx.eventController.getActionState(actionId);
+        return selector ? selector(state) : state;
+    });
+    const prevSelected = useRef(baseState);
+    prevSelected.current = baseState;
+    // useOptimistic allows immediate updates during transitions/actions
+    const [optimisticState, setOptimisticState] = useOptimistic(null);
+    // Memoize the selector to avoid unnecessary re-subscriptions
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    // Subscribe to action state changes from event controller
+    useEffect(() => {
+        if (!ctx)
+            return;
+        // Subscribe to action-specific updates
+        const unsubscribe = ctx.eventController.subscribeToAction(actionId, (state) => {
+            const selectedState = selectorRef.current
+                ? selectorRef.current(state)
+                : state;
+            if (!isShallowEqual(selectedState, prevSelected.current)) {
+                prevSelected.current = selectedState;
+                setBaseState(selectedState);
+                startTransition(() => {
+                    setOptimisticState(selectedState);
+                });
+            }
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [actionId]);
+    return (optimisticState ?? baseState);
+}
+function isShallowEqual(selectedState, baseState) {
+    // If references are equal, they're shallow equal
+    //@ts-expect-error -- TS doesn't like comparing generics
+    if (selectedState === baseState) {
+        return true;
+    }
+    // If either is null/undefined and they're not equal, they're not shallow equal
+    if (selectedState == null || baseState == null) {
+        return false;
+    }
+    // If types are different, they're not shallow equal
+    if (typeof selectedState !== typeof baseState) {
+        return false;
+    }
+    // For primitives, === comparison is sufficient (already checked above)
+    if (typeof selectedState !== "object") {
+        return false;
+    }
+    // For objects, compare keys and values shallowly
+    const keysA = Object.keys(selectedState);
+    const keysB = Object.keys(baseState);
+    if (keysA.length !== keysB.length) {
+        return false;
+    }
+    for (const key of keysA) {
+        if (!Object.prototype.hasOwnProperty.call(baseState, key) ||
+            selectedState[key] !== baseState[key]) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=use-action.js.map

package/dist/browser/react/use-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-action.js","sourceRoot":"","sources":["../../../src/browser/react/use-action.ts"],"names":[],"mappings":"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"}

package/dist/browser/react/use-client-cache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Return type for useClientCache hook
+ */
+export interface ClientCacheControls {
+    /**
+     * Clear the client-side navigation cache.
+     * Call this after data changes that happen outside of server actions
+     * (e.g., REST API calls, WebSocket updates, etc.)
+     *
+     * This will also broadcast to other tabs to clear their caches.
+     */
+    clear: () => void;
+}
+/**
+ * Hook to access client-side cache controls
+ *
+ * Use this when you need to manually invalidate the navigation cache
+ * after data changes that happen outside of server actions.
+ *
+ * Server actions automatically clear the cache, so you only need this for:
+ * - REST API mutations
+ * - WebSocket-driven updates
+ * - Other non-RSC data changes
+ *
+ * @example
+ * ```tsx
+ * function DataEditor() {
+ *   const { clear } = useClientCache();
+ *
+ *   async function handleSave() {
+ *     await fetch('/api/data', { method: 'POST', body: JSON.stringify(data) });
+ *     // Clear cache so back/forward navigation shows fresh data
+ *     clear();
+ *   }
+ *
+ *   return <button onClick={handleSave}>Save</button>;
+ * }
+ * ```
+ */
+export declare function useClientCache(): ClientCacheControls;
+//# sourceMappingURL=use-client-cache.d.ts.map

package/dist/browser/react/use-client-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-client-cache.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-client-cache.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,IAAI,mBAAmB,CAUpD"}

package/dist/browser/react/use-client-cache.js

@@ -0,0 +1,39 @@
+"use client";
+import { useContext, useCallback } from "react";
+import { NavigationStoreContext } from "./context.js";
+/**
+ * Hook to access client-side cache controls
+ *
+ * Use this when you need to manually invalidate the navigation cache
+ * after data changes that happen outside of server actions.
+ *
+ * Server actions automatically clear the cache, so you only need this for:
+ * - REST API mutations
+ * - WebSocket-driven updates
+ * - Other non-RSC data changes
+ *
+ * @example
+ * ```tsx
+ * function DataEditor() {
+ *   const { clear } = useClientCache();
+ *
+ *   async function handleSave() {
+ *     await fetch('/api/data', { method: 'POST', body: JSON.stringify(data) });
+ *     // Clear cache so back/forward navigation shows fresh data
+ *     clear();
+ *   }
+ *
+ *   return <button onClick={handleSave}>Save</button>;
+ * }
+ * ```
+ */
+export function useClientCache() {
+    const ctx = useContext(NavigationStoreContext);
+    const clear = useCallback(() => {
+        if (ctx?.store) {
+            ctx.store.clearHistoryCache();
+        }
+    }, [ctx]);
+    return { clear };
+}
+//# sourceMappingURL=use-client-cache.js.map

package/dist/browser/react/use-client-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-client-cache.js","sourceRoot":"","sources":["../../../src/browser/react/use-client-cache.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAgBtD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;IAE/C,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,GAAG,EAAE,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAChC,CAAC;IACH,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,31 @@
+import type { Handle } from "../../handle.js";
+import type { HandleData } from "../types.js";
+/**
+ * Initialize handle data synchronously for SSR.
+ * Called before rendering to populate state for useState initializer.
+ *
+ * @param data - Handle data from RSC payload
+ * @param matched - Segment order for reduction
+ */
+export declare function initHandleDataSync(data: HandleData, matched?: string[]): void;
+/**
+ * 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>): A;
+export declare function useHandle<T, A, S>(handle: Handle<T, A>, selector: (data: A) => S): S;
+//# sourceMappingURL=use-handle.d.ts.map

package/dist/browser/react/use-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-handle.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-handle.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAqG9C;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAG7E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;AACzD,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GACvB,CAAC,CAAC"}