cilantro-react 0.1.5 → 0.1.7

package/dist/AuthGuard-siMJeYPD.d.mts

@@ -0,0 +1,42 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface AuthGuardClassNames {
+    root?: string;
+    fallback?: string;
+    skeleton?: string;
+    loading?: string;
+    /** Centered/fullscreen layout wrapper */
+    layout?: string;
+}
+type AuthGuardLayout = "inline" | "centered" | "fullscreen";
+interface AuthGuardProps {
+    children: ReactNode;
+    /** Shown when not authenticated. Default: <LoginForm /> */
+    fallback?: ReactNode;
+    /** Redirect unauthenticated users to this path (e.g. "/login"). Uses onRedirect if provided, else window.location. */
+    redirectTo?: string;
+    /** Custom redirect function for SPA routers (Next.js, React Router). e.g. (path) => router.replace(path) */
+    onRedirect?: (path: string) => void;
+    /** Query param for return URL when redirecting. Default: "returnUrl" */
+    returnUrlParam?: string;
+    /** Layout for fallback content. "centered" and "fullscreen" give polished auth UX. */
+    layout?: AuthGuardLayout;
+    /** Root class when showing fallback */
+    className?: string;
+    classNames?: AuthGuardClassNames;
+    /** When true, show fallback (login) instead of redirecting. When false, redirect when redirectTo is set, else render null. */
+    showFallback?: boolean;
+    /** When true, show skeleton while loading. When false, show "Loading..." text. */
+    useSkeleton?: boolean;
+}
+/**
+ * Wraps content and shows fallback (e.g. LoginForm) when the user is not authenticated.
+ * Use inside CilantroProvider.
+ *
+ * For Next.js: pass onRedirect={(path) => router.replace(path)} and redirectTo="/login".
+ * For return-after-login flow: set redirectTo="/login"; AuthGuard will redirect with ?returnUrl=currentPath.
+ */
+declare function AuthGuard({ children, fallback, redirectTo, onRedirect, returnUrlParam, layout, className, classNames, showFallback, useSkeleton, }: AuthGuardProps): react_jsx_runtime.JSX.Element | null;
+
+export { AuthGuard as A, type AuthGuardClassNames as a, type AuthGuardLayout as b, type AuthGuardProps as c };

package/dist/AuthGuard-siMJeYPD.d.ts

@@ -0,0 +1,42 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface AuthGuardClassNames {
+    root?: string;
+    fallback?: string;
+    skeleton?: string;
+    loading?: string;
+    /** Centered/fullscreen layout wrapper */
+    layout?: string;
+}
+type AuthGuardLayout = "inline" | "centered" | "fullscreen";
+interface AuthGuardProps {
+    children: ReactNode;
+    /** Shown when not authenticated. Default: <LoginForm /> */
+    fallback?: ReactNode;
+    /** Redirect unauthenticated users to this path (e.g. "/login"). Uses onRedirect if provided, else window.location. */
+    redirectTo?: string;
+    /** Custom redirect function for SPA routers (Next.js, React Router). e.g. (path) => router.replace(path) */
+    onRedirect?: (path: string) => void;
+    /** Query param for return URL when redirecting. Default: "returnUrl" */
+    returnUrlParam?: string;
+    /** Layout for fallback content. "centered" and "fullscreen" give polished auth UX. */
+    layout?: AuthGuardLayout;
+    /** Root class when showing fallback */
+    className?: string;
+    classNames?: AuthGuardClassNames;
+    /** When true, show fallback (login) instead of redirecting. When false, redirect when redirectTo is set, else render null. */
+    showFallback?: boolean;
+    /** When true, show skeleton while loading. When false, show "Loading..." text. */
+    useSkeleton?: boolean;
+}
+/**
+ * Wraps content and shows fallback (e.g. LoginForm) when the user is not authenticated.
+ * Use inside CilantroProvider.
+ *
+ * For Next.js: pass onRedirect={(path) => router.replace(path)} and redirectTo="/login".
+ * For return-after-login flow: set redirectTo="/login"; AuthGuard will redirect with ?returnUrl=currentPath.
+ */
+declare function AuthGuard({ children, fallback, redirectTo, onRedirect, returnUrlParam, layout, className, classNames, showFallback, useSkeleton, }: AuthGuardProps): react_jsx_runtime.JSX.Element | null;
+
+export { AuthGuard as A, type AuthGuardClassNames as a, type AuthGuardLayout as b, type AuthGuardProps as c };

package/dist/index.d.mts

@@ -5,6 +5,7 @@ import { WalletControllerFindAllResult, WalletControllerCreateResult, WalletCont
 export { WalletControllerFindAllResult, WalletControllerFindOneResult, WalletControllerListSignersResult, WalletControllerSubmitTransactionResult } from 'cilantro-sdk/wallet';
 import { createIndexedDBAdapter, SignerInfo } from 'cilantro-sdk/helpers';
 export { createIndexedDBAdapter, createLocalStorageAdapter, createMemoryAdapter } from 'cilantro-sdk/helpers';
+export { A as AuthGuard, a as AuthGuardClassNames, b as AuthGuardLayout, c as AuthGuardProps } from './AuthGuard-siMJeYPD.mjs';
 import { PublicKey, Transaction, Connection } from '@solana/web3.js';
 export { AuthControllerLogin200Data } from 'cilantro-sdk/auth';
 export { TransactionControllerSendRawPasskeyTransactionResult } from 'cilantro-sdk/transactions';
@@ -62,12 +63,16 @@ interface CilantroContextProviderProps {
     storageAdapter?: DeviceKeyStorage | null;
     jwtStorageKey?: string;
     walletStorageKey?: string;
+    /** When true, sync JWT to a cookie (same name as jwtStorageKey) for Next.js/middleware. Default: false. */
+    syncJwtToCookie?: boolean;
+    /** Cookie name for JWT when syncJwtToCookie is true. Default: cilantro_jwt. */
+    jwtCookieName?: string;
     onLoginSuccess?: () => void;
     onLogout?: () => void;
     onRegisterSuccess?: () => void;
     onSessionExpired?: () => void;
 }
-declare function CilantroContextProvider({ children, apiKey, baseURL, storageAdapter, jwtStorageKey, walletStorageKey, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroContextProviderProps): react_jsx_runtime.JSX.Element;
+declare function CilantroContextProvider({ children, apiKey, baseURL, storageAdapter, jwtStorageKey, walletStorageKey, syncJwtToCookie, jwtCookieName, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroContextProviderProps): react_jsx_runtime.JSX.Element;
 declare function useCilantroContext(): CilantroContextValue;
 
 interface CilantroProviderProps {
@@ -86,15 +91,21 @@ interface CilantroProviderProps {
     jwtStorageKey?: string;
     /** localStorage key for selected wallet id (default: cilantro_selected_wallet_id) */
     walletStorageKey?: string;
+    /** When true, sync JWT to a cookie for Next.js/middleware. Default: false. */
+    syncJwtToCookie?: boolean;
+    /** Cookie name for JWT when syncJwtToCookie is true. Default: cilantro_jwt. */
+    jwtCookieName?: string;
     onLoginSuccess?: () => void;
     onLogout?: () => void;
     onRegisterSuccess?: () => void;
     onSessionExpired?: () => void;
 }
-declare function CilantroProvider({ children, apiKey: apiKeyProp, baseURL, storageAdapter, platformApiKey, apiUrl, jwtStorageKey, walletStorageKey, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroProviderProps): react_jsx_runtime.JSX.Element;
+declare function CilantroProvider({ children, apiKey: apiKeyProp, baseURL, storageAdapter, platformApiKey, apiUrl, jwtStorageKey, walletStorageKey, syncJwtToCookie, jwtCookieName, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroProviderProps): react_jsx_runtime.JSX.Element;
 
 interface CilantroAuthContextType {
     user: User | null;
+    /** JWT token. Alias for token. */
+    jwt: string | null;
     token: string | null;
     isAuthenticated: boolean;
     login: (usernameOrEmail: string, password: string) => Promise<void>;
@@ -106,6 +117,9 @@ interface CilantroAuthContextType {
 declare function useCilantroAuth(): CilantroAuthContextType;
 
 interface WalletContextType {
+    /** Selected wallet. Primary name. */
+    wallet: WalletData | null;
+    /** @deprecated Use wallet instead. Alias for backward compat. */
     selectedWallet: WalletData | null;
     wallets: WalletData[];
     selectWallet: (walletId: string) => void;
@@ -124,19 +138,54 @@ interface UseCilantroConfigResult {
 declare function useCilantroConfig(): UseCilantroConfigResult;
 
 interface UseAuthResult {
+    /** Current user (from JWT payload or login response). */
     user: User | null;
+    /** JWT token. Prefer this name. */
     jwt: string | null;
+    /** Alias for jwt. Same value. */
+    token: string | null;
     isLoading: boolean;
     isAuthenticated: boolean;
     login: (params: {
         usernameOrEmail: string;
         password: string;
     }) => Promise<void>;
+    /** Register a new user and auto-login. */
+    register: (username: string, email: string, password: string, isActive?: boolean) => Promise<void>;
     logout: () => void;
+    /** Clear session when API returns 401/403. Call onSessionExpired. */
+    clearSessionDueToAuthError: () => void;
 }
 declare function useAuth(): UseAuthResult;
 
+interface UseReturnUrlOptions {
+    /** Query param name for return URL. Default: "returnUrl" */
+    param?: string;
+    /** Default path when no returnUrl in URL. Default: "/" */
+    defaultPath?: string;
+    /** Only allow relative paths (no protocol). Default: true */
+    allowRelativeOnly?: boolean;
+}
+/**
+ * Read returnUrl from URL search params and provide a safe redirect path.
+ * Use with LoginForm/RegisterForm to redirect users back after auth.
+ *
+ * @example
+ * // In LoginForm wrapper - redirect to returnUrl after login
+ * const { returnPath, redirect } = useReturnUrl();
+ * <LoginForm onSuccess={() => redirect()} redirectAfterSuccess={returnPath} onRedirect={router.replace} />
+ */
+declare function useReturnUrl(options?: UseReturnUrlOptions): {
+    /** Safe path to redirect to (from URL or defaultPath) */
+    returnPath: string;
+    /** Redirect to returnPath using window.location (or pass custom fn) */
+    redirect: (customRedirect?: (path: string) => void) => void;
+    /** Raw value from URL (may be empty) */
+    rawReturnUrl: string | null;
+};
+
 interface UseWalletResult {
+    /** Selected wallet. Use this as primary. */
     wallet: WalletData | null;
     wallets: WalletData[];
     createWallet: (params: {
@@ -144,7 +193,11 @@ interface UseWalletResult {
         userId?: string;
     }) => Promise<WalletControllerCreateResult>;
     selectWallet: (walletId: string) => void;
+    /** Refresh wallet list from API. */
+    refreshWallets: () => Promise<void>;
     isLoading: boolean;
+    /** Error from wallet operations (e.g. fetch failed). */
+    error: string | null;
 }
 declare function useWallet(_walletId?: string): UseWalletResult;
 
@@ -277,6 +330,12 @@ interface LoginFormProps {
     style?: React.CSSProperties;
     onSuccess?: () => void;
     onError?: (error: Error) => void;
+    /** Redirect to this path after successful login. If not set, reads from URL ?returnUrl= (when returnUrlParam provided). */
+    redirectAfterSuccess?: string;
+    /** Custom redirect function for SPA routers. e.g. (path) => router.replace(path) */
+    onRedirect?: (path: string) => void;
+    /** Query param to read returnUrl from URL. Default: "returnUrl". Used when redirectAfterSuccess not set. */
+    returnUrlParam?: string;
     rememberMe?: boolean;
     /** Override submit button label */
     submitLabel?: string;
@@ -287,41 +346,78 @@ interface LoginFormProps {
     /** Render "Create account" link (e.g. to switch to register). Shown below submit. */
     renderSwitchToRegister?: () => React.ReactNode;
 }
-declare function LoginForm({ className, classNames, style, onSuccess, onError, submitLabel, title, description, renderSwitchToRegister, }: LoginFormProps): react_jsx_runtime.JSX.Element;
+declare function LoginForm({ className, classNames, style, onSuccess, onError, redirectAfterSuccess, onRedirect, returnUrlParam, submitLabel, title, description, renderSwitchToRegister, }: LoginFormProps): react_jsx_runtime.JSX.Element;
+
+interface RegisterFormClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    description?: string;
+    form?: string;
+    label?: string;
+    input?: string;
+    submitButton?: string;
+    error?: string;
+}
+interface RegisterFormProps {
+    className?: string;
+    classNames?: RegisterFormClassNames;
+    style?: React.CSSProperties;
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+    /** Redirect to this path after successful registration. If not set, reads from URL ?returnUrl= */
+    redirectAfterSuccess?: string;
+    /** Custom redirect function for SPA routers */
+    onRedirect?: (path: string) => void;
+    /** Query param to read returnUrl from URL. Default: "returnUrl" */
+    returnUrlParam?: string;
+    /** Override submit button label */
+    submitLabel?: string;
+    /** Override title */
+    title?: string;
+    /** Override description */
+    description?: string;
+    /** Render "Already have an account?" link to switch to login */
+    renderSwitchToLogin?: () => React.ReactNode;
+}
+declare function RegisterForm({ className, classNames, style, onSuccess, onError, redirectAfterSuccess, onRedirect, returnUrlParam, submitLabel, title, description, renderSwitchToLogin, }: RegisterFormProps): react_jsx_runtime.JSX.Element;
 
 interface LogoutButtonProps {
     onLogout?: () => void;
+    /** Redirect to this path after logout (e.g. "/login") */
+    redirectAfterLogout?: string;
+    /** Custom redirect for SPA routers. e.g. (path) => router.replace(path) */
+    onRedirect?: (path: string) => void;
     confirmBeforeLogout?: boolean;
     className?: string;
     children?: ReactNode;
 }
-declare function LogoutButton({ onLogout, confirmBeforeLogout, className, children, }: LogoutButtonProps): react_jsx_runtime.JSX.Element;
+declare function LogoutButton({ onLogout, redirectAfterLogout, onRedirect, confirmBeforeLogout, className, children, }: LogoutButtonProps): react_jsx_runtime.JSX.Element;
 
-interface AuthGuardClassNames {
+interface AuthShellClassNames {
     root?: string;
-    fallback?: string;
-    skeleton?: string;
-    loading?: string;
+    inner?: string;
+    logo?: string;
 }
-interface AuthGuardProps {
+interface AuthShellProps {
     children: ReactNode;
-    /** Shown when not authenticated. Default: <LoginForm /> */
-    fallback?: ReactNode;
-    /** If using a router, redirect to this path when not authenticated (consumer can pass fallback={<Navigate to={redirectTo} />}) */
-    redirectTo?: string;
-    /** Root class when showing fallback */
+    /** Optional logo/brand (e.g. <img> or <Logo />) */
+    logo?: ReactNode;
+    /** Max width of the auth card area. Default: "sm" (24rem) */
+    maxWidth?: "sm" | "md" | "lg";
     className?: string;
-    classNames?: AuthGuardClassNames;
-    /** When true, show fallback (login) instead of children when unauthenticated. When false, render null when unauthenticated. */
-    showFallback?: boolean;
-    /** When true, show a small skeleton card while loading; when false (default), show "Loading..." text. */
-    useSkeleton?: boolean;
+    classNames?: AuthShellClassNames;
 }
 /**
- * Wraps content and shows fallback (e.g. LoginForm) when the user is not authenticated.
- * Use inside CilantroProvider.
+ * Full-page centered layout for auth screens (login, register).
+ * Provides a polished, accessible UX with consistent spacing and optional logo.
+ *
+ * @example
+ * <AuthShell logo={<img src="/logo.svg" alt="App" />}>
+ *   <LoginForm />
+ * </AuthShell>
  */
-declare function AuthGuard({ children, fallback, redirectTo, className, classNames, showFallback, useSkeleton, }: AuthGuardProps): react_jsx_runtime.JSX.Element | null;
+declare function AuthShell({ children, logo, maxWidth, className, classNames, }: AuthShellProps): react_jsx_runtime.JSX.Element;
 
 interface CreateEmailSignerFormProps {
     walletId: string;
@@ -673,6 +769,21 @@ interface NormalizedWallet {
  * Accepts any object with optional walletId/id, walletAddress/address, isActive.
  */
 declare function normalizeWallet(dto: Record<string, unknown>): NormalizedWallet;
+/** Wallet-like object with optional id/walletId and address/walletAddress. */
+type WalletLike = {
+    id?: string;
+    walletId?: string;
+    address?: string;
+    walletAddress?: string;
+} & Record<string, unknown>;
+/**
+ * Get wallet ID from a wallet-like object. Prefer id; fallback to walletId.
+ */
+declare function getWalletId(wallet: WalletLike | null | undefined): string;
+/**
+ * Get wallet address from a wallet-like object. Prefer address; fallback to walletAddress.
+ */
+declare function getWalletAddress(wallet: WalletLike | null | undefined): string;
 
 declare function extractErrorMessage(error: unknown): string;
 declare function isAuthError(error: unknown): boolean;
@@ -716,4 +827,4 @@ interface SignAndSendConnectionAdapter {
  */
 declare function adaptSolanaConnection(connection: Connection): SignAndSendConnectionAdapter;
 
-export { type ActionState, AddPasskeyButton, type AddPasskeyButtonProps, type ApiResponse, AuthGuard, type AuthGuardClassNames, type AuthGuardProps, type CilantroAuthContextType, type CilantroConfig, CilantroConnect, type CilantroConnectProps, CilantroContextProvider, type CilantroContextValue, CilantroProvider, type CilantroProviderProps, ConnectWalletButton, type ConnectWalletButtonProps, CreateEmailSignerForm, type CreateEmailSignerFormProps, CreatePhoneSignerForm, type CreatePhoneSignerFormProps, CreateWalletForm, type CreateWalletFormProps, type DeviceKeyStorage, ErrorBoundary, type ErrorBoundaryProps, type ErrorResponse, LoadingOverlay, type LoadingOverlayProps, LoginForm, type LoginFormClassNames, type LoginFormProps, LogoutButton, type LogoutButtonProps, type NormalizedWallet, type ResolvedTheme, SIGNER_TYPES, SendSOLForm, type SendSOLFormProps, type SignerType as SendSOLSignerType, SendSPLForm, type SendSPLFormProps, type SignerType$2 as SendTransactionSignerType, type SignAndSendConnection, type SignAndSendConnectionAdapter, type SignAndSendResult, type SignMessageResult, type SignerData, SignerList, type SignerListClassNames, type SignerListProps, SignerSelector, type SignerSelectorClassNames, type SignerSelectorProps, type SignerType$1 as SignerType, Skeleton, type SolanaWallet, type SubmitTransactionDataDto, type SubmitTransactionResult, type Theme, ThemeProvider, type ThemeProviderProps, TransactionHistory, type TransactionHistoryProps, TransactionStatus, type TransactionStatusProps, type UseAuthResult, type UseCilantroConfigResult, type UseExternalWalletResult, type UsePasskeyResult, type UseSendTransactionResult, type UseSignersOptions, type UseSignersResult, type UseWalletResult, type User, WalletAddress, type WalletAddressProps, WalletBalance, type WalletBalanceProps, type WalletContextType, type WalletData, type WalletDataDto$1 as WalletDataDto, type WalletDataDto as WalletDataDtoFromHook, type WalletData as WalletDataFromHook, type WalletInfo, WalletSelector, type WalletSelectorClassNames, type WalletSelectorProps, adaptSolanaConnection, extractErrorMessage, extractResponseData, getSignerPublicKey, getWalletData, isAuthError, isJwtExpired, normalizeSigner, normalizeWallet, signAndSendTransactionWithSigner, signMessageWithSigner, signTransactionWithSigner, useAuth, useCilantroAuth, useCilantroConfig, useCilantroContext, useExternalWallet, usePasskey, useSendTransaction, useSigners, useWallet, useWallets };
+export { type ActionState, AddPasskeyButton, type AddPasskeyButtonProps, type ApiResponse, AuthShell, type AuthShellClassNames, type AuthShellProps, type CilantroAuthContextType, type CilantroConfig, CilantroConnect, type CilantroConnectProps, CilantroContextProvider, type CilantroContextValue, CilantroProvider, type CilantroProviderProps, ConnectWalletButton, type ConnectWalletButtonProps, CreateEmailSignerForm, type CreateEmailSignerFormProps, CreatePhoneSignerForm, type CreatePhoneSignerFormProps, CreateWalletForm, type CreateWalletFormProps, type DeviceKeyStorage, ErrorBoundary, type ErrorBoundaryProps, type ErrorResponse, LoadingOverlay, type LoadingOverlayProps, LoginForm, type LoginFormClassNames, type LoginFormProps, LogoutButton, type LogoutButtonProps, type NormalizedWallet, RegisterForm, type RegisterFormClassNames, type RegisterFormProps, type ResolvedTheme, SIGNER_TYPES, SendSOLForm, type SendSOLFormProps, type SignerType as SendSOLSignerType, SendSPLForm, type SendSPLFormProps, type SignerType$2 as SendTransactionSignerType, type SignAndSendConnection, type SignAndSendConnectionAdapter, type SignAndSendResult, type SignMessageResult, type SignerData, SignerList, type SignerListClassNames, type SignerListProps, SignerSelector, type SignerSelectorClassNames, type SignerSelectorProps, type SignerType$1 as SignerType, Skeleton, type SolanaWallet, type SubmitTransactionDataDto, type SubmitTransactionResult, type Theme, ThemeProvider, type ThemeProviderProps, TransactionHistory, type TransactionHistoryProps, TransactionStatus, type TransactionStatusProps, type UseAuthResult, type UseCilantroConfigResult, type UseExternalWalletResult, type UsePasskeyResult, type UseReturnUrlOptions, type UseSendTransactionResult, type UseSignersOptions, type UseSignersResult, type UseWalletResult, type User, WalletAddress, type WalletAddressProps, WalletBalance, type WalletBalanceProps, type WalletContextType, type WalletData, type WalletDataDto$1 as WalletDataDto, type WalletDataDto as WalletDataDtoFromHook, type WalletData as WalletDataFromHook, type WalletInfo, type WalletLike, WalletSelector, type WalletSelectorClassNames, type WalletSelectorProps, adaptSolanaConnection, extractErrorMessage, extractResponseData, getSignerPublicKey, getWalletAddress, getWalletData, getWalletId, isAuthError, isJwtExpired, normalizeSigner, normalizeWallet, signAndSendTransactionWithSigner, signMessageWithSigner, signTransactionWithSigner, useAuth, useCilantroAuth, useCilantroConfig, useCilantroContext, useExternalWallet, usePasskey, useReturnUrl, useSendTransaction, useSigners, useWallet, useWallets };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { WalletControllerFindAllResult, WalletControllerCreateResult, WalletCont
 export { WalletControllerFindAllResult, WalletControllerFindOneResult, WalletControllerListSignersResult, WalletControllerSubmitTransactionResult } from 'cilantro-sdk/wallet';
 import { createIndexedDBAdapter, SignerInfo } from 'cilantro-sdk/helpers';
 export { createIndexedDBAdapter, createLocalStorageAdapter, createMemoryAdapter } from 'cilantro-sdk/helpers';
+export { A as AuthGuard, a as AuthGuardClassNames, b as AuthGuardLayout, c as AuthGuardProps } from './AuthGuard-siMJeYPD.js';
 import { PublicKey, Transaction, Connection } from '@solana/web3.js';
 export { AuthControllerLogin200Data } from 'cilantro-sdk/auth';
 export { TransactionControllerSendRawPasskeyTransactionResult } from 'cilantro-sdk/transactions';
@@ -62,12 +63,16 @@ interface CilantroContextProviderProps {
     storageAdapter?: DeviceKeyStorage | null;
     jwtStorageKey?: string;
     walletStorageKey?: string;
+    /** When true, sync JWT to a cookie (same name as jwtStorageKey) for Next.js/middleware. Default: false. */
+    syncJwtToCookie?: boolean;
+    /** Cookie name for JWT when syncJwtToCookie is true. Default: cilantro_jwt. */
+    jwtCookieName?: string;
     onLoginSuccess?: () => void;
     onLogout?: () => void;
     onRegisterSuccess?: () => void;
     onSessionExpired?: () => void;
 }
-declare function CilantroContextProvider({ children, apiKey, baseURL, storageAdapter, jwtStorageKey, walletStorageKey, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroContextProviderProps): react_jsx_runtime.JSX.Element;
+declare function CilantroContextProvider({ children, apiKey, baseURL, storageAdapter, jwtStorageKey, walletStorageKey, syncJwtToCookie, jwtCookieName, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroContextProviderProps): react_jsx_runtime.JSX.Element;
 declare function useCilantroContext(): CilantroContextValue;
 
 interface CilantroProviderProps {
@@ -86,15 +91,21 @@ interface CilantroProviderProps {
     jwtStorageKey?: string;
     /** localStorage key for selected wallet id (default: cilantro_selected_wallet_id) */
     walletStorageKey?: string;
+    /** When true, sync JWT to a cookie for Next.js/middleware. Default: false. */
+    syncJwtToCookie?: boolean;
+    /** Cookie name for JWT when syncJwtToCookie is true. Default: cilantro_jwt. */
+    jwtCookieName?: string;
     onLoginSuccess?: () => void;
     onLogout?: () => void;
     onRegisterSuccess?: () => void;
     onSessionExpired?: () => void;
 }
-declare function CilantroProvider({ children, apiKey: apiKeyProp, baseURL, storageAdapter, platformApiKey, apiUrl, jwtStorageKey, walletStorageKey, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroProviderProps): react_jsx_runtime.JSX.Element;
+declare function CilantroProvider({ children, apiKey: apiKeyProp, baseURL, storageAdapter, platformApiKey, apiUrl, jwtStorageKey, walletStorageKey, syncJwtToCookie, jwtCookieName, onLoginSuccess, onLogout, onRegisterSuccess, onSessionExpired, }: CilantroProviderProps): react_jsx_runtime.JSX.Element;
 
 interface CilantroAuthContextType {
     user: User | null;
+    /** JWT token. Alias for token. */
+    jwt: string | null;
     token: string | null;
     isAuthenticated: boolean;
     login: (usernameOrEmail: string, password: string) => Promise<void>;
@@ -106,6 +117,9 @@ interface CilantroAuthContextType {
 declare function useCilantroAuth(): CilantroAuthContextType;
 
 interface WalletContextType {
+    /** Selected wallet. Primary name. */
+    wallet: WalletData | null;
+    /** @deprecated Use wallet instead. Alias for backward compat. */
     selectedWallet: WalletData | null;
     wallets: WalletData[];
     selectWallet: (walletId: string) => void;
@@ -124,19 +138,54 @@ interface UseCilantroConfigResult {
 declare function useCilantroConfig(): UseCilantroConfigResult;
 
 interface UseAuthResult {
+    /** Current user (from JWT payload or login response). */
     user: User | null;
+    /** JWT token. Prefer this name. */
     jwt: string | null;
+    /** Alias for jwt. Same value. */
+    token: string | null;
     isLoading: boolean;
     isAuthenticated: boolean;
     login: (params: {
         usernameOrEmail: string;
         password: string;
     }) => Promise<void>;
+    /** Register a new user and auto-login. */
+    register: (username: string, email: string, password: string, isActive?: boolean) => Promise<void>;
     logout: () => void;
+    /** Clear session when API returns 401/403. Call onSessionExpired. */
+    clearSessionDueToAuthError: () => void;
 }
 declare function useAuth(): UseAuthResult;
 
+interface UseReturnUrlOptions {
+    /** Query param name for return URL. Default: "returnUrl" */
+    param?: string;
+    /** Default path when no returnUrl in URL. Default: "/" */
+    defaultPath?: string;
+    /** Only allow relative paths (no protocol). Default: true */
+    allowRelativeOnly?: boolean;
+}
+/**
+ * Read returnUrl from URL search params and provide a safe redirect path.
+ * Use with LoginForm/RegisterForm to redirect users back after auth.
+ *
+ * @example
+ * // In LoginForm wrapper - redirect to returnUrl after login
+ * const { returnPath, redirect } = useReturnUrl();
+ * <LoginForm onSuccess={() => redirect()} redirectAfterSuccess={returnPath} onRedirect={router.replace} />
+ */
+declare function useReturnUrl(options?: UseReturnUrlOptions): {
+    /** Safe path to redirect to (from URL or defaultPath) */
+    returnPath: string;
+    /** Redirect to returnPath using window.location (or pass custom fn) */
+    redirect: (customRedirect?: (path: string) => void) => void;
+    /** Raw value from URL (may be empty) */
+    rawReturnUrl: string | null;
+};
+
 interface UseWalletResult {
+    /** Selected wallet. Use this as primary. */
     wallet: WalletData | null;
     wallets: WalletData[];
     createWallet: (params: {
@@ -144,7 +193,11 @@ interface UseWalletResult {
         userId?: string;
     }) => Promise<WalletControllerCreateResult>;
     selectWallet: (walletId: string) => void;
+    /** Refresh wallet list from API. */
+    refreshWallets: () => Promise<void>;
     isLoading: boolean;
+    /** Error from wallet operations (e.g. fetch failed). */
+    error: string | null;
 }
 declare function useWallet(_walletId?: string): UseWalletResult;
 
@@ -277,6 +330,12 @@ interface LoginFormProps {
     style?: React.CSSProperties;
     onSuccess?: () => void;
     onError?: (error: Error) => void;
+    /** Redirect to this path after successful login. If not set, reads from URL ?returnUrl= (when returnUrlParam provided). */
+    redirectAfterSuccess?: string;
+    /** Custom redirect function for SPA routers. e.g. (path) => router.replace(path) */
+    onRedirect?: (path: string) => void;
+    /** Query param to read returnUrl from URL. Default: "returnUrl". Used when redirectAfterSuccess not set. */
+    returnUrlParam?: string;
     rememberMe?: boolean;
     /** Override submit button label */
     submitLabel?: string;
@@ -287,41 +346,78 @@ interface LoginFormProps {
     /** Render "Create account" link (e.g. to switch to register). Shown below submit. */
     renderSwitchToRegister?: () => React.ReactNode;
 }
-declare function LoginForm({ className, classNames, style, onSuccess, onError, submitLabel, title, description, renderSwitchToRegister, }: LoginFormProps): react_jsx_runtime.JSX.Element;
+declare function LoginForm({ className, classNames, style, onSuccess, onError, redirectAfterSuccess, onRedirect, returnUrlParam, submitLabel, title, description, renderSwitchToRegister, }: LoginFormProps): react_jsx_runtime.JSX.Element;
+
+interface RegisterFormClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    description?: string;
+    form?: string;
+    label?: string;
+    input?: string;
+    submitButton?: string;
+    error?: string;
+}
+interface RegisterFormProps {
+    className?: string;
+    classNames?: RegisterFormClassNames;
+    style?: React.CSSProperties;
+    onSuccess?: () => void;
+    onError?: (error: Error) => void;
+    /** Redirect to this path after successful registration. If not set, reads from URL ?returnUrl= */
+    redirectAfterSuccess?: string;
+    /** Custom redirect function for SPA routers */
+    onRedirect?: (path: string) => void;
+    /** Query param to read returnUrl from URL. Default: "returnUrl" */
+    returnUrlParam?: string;
+    /** Override submit button label */
+    submitLabel?: string;
+    /** Override title */
+    title?: string;
+    /** Override description */
+    description?: string;
+    /** Render "Already have an account?" link to switch to login */
+    renderSwitchToLogin?: () => React.ReactNode;
+}
+declare function RegisterForm({ className, classNames, style, onSuccess, onError, redirectAfterSuccess, onRedirect, returnUrlParam, submitLabel, title, description, renderSwitchToLogin, }: RegisterFormProps): react_jsx_runtime.JSX.Element;
 
 interface LogoutButtonProps {
     onLogout?: () => void;
+    /** Redirect to this path after logout (e.g. "/login") */
+    redirectAfterLogout?: string;
+    /** Custom redirect for SPA routers. e.g. (path) => router.replace(path) */
+    onRedirect?: (path: string) => void;
     confirmBeforeLogout?: boolean;
     className?: string;
     children?: ReactNode;
 }
-declare function LogoutButton({ onLogout, confirmBeforeLogout, className, children, }: LogoutButtonProps): react_jsx_runtime.JSX.Element;
+declare function LogoutButton({ onLogout, redirectAfterLogout, onRedirect, confirmBeforeLogout, className, children, }: LogoutButtonProps): react_jsx_runtime.JSX.Element;
 
-interface AuthGuardClassNames {
+interface AuthShellClassNames {
     root?: string;
-    fallback?: string;
-    skeleton?: string;
-    loading?: string;
+    inner?: string;
+    logo?: string;
 }
-interface AuthGuardProps {
+interface AuthShellProps {
     children: ReactNode;
-    /** Shown when not authenticated. Default: <LoginForm /> */
-    fallback?: ReactNode;
-    /** If using a router, redirect to this path when not authenticated (consumer can pass fallback={<Navigate to={redirectTo} />}) */
-    redirectTo?: string;
-    /** Root class when showing fallback */
+    /** Optional logo/brand (e.g. <img> or <Logo />) */
+    logo?: ReactNode;
+    /** Max width of the auth card area. Default: "sm" (24rem) */
+    maxWidth?: "sm" | "md" | "lg";
     className?: string;
-    classNames?: AuthGuardClassNames;
-    /** When true, show fallback (login) instead of children when unauthenticated. When false, render null when unauthenticated. */
-    showFallback?: boolean;
-    /** When true, show a small skeleton card while loading; when false (default), show "Loading..." text. */
-    useSkeleton?: boolean;
+    classNames?: AuthShellClassNames;
 }
 /**
- * Wraps content and shows fallback (e.g. LoginForm) when the user is not authenticated.
- * Use inside CilantroProvider.
+ * Full-page centered layout for auth screens (login, register).
+ * Provides a polished, accessible UX with consistent spacing and optional logo.
+ *
+ * @example
+ * <AuthShell logo={<img src="/logo.svg" alt="App" />}>
+ *   <LoginForm />
+ * </AuthShell>
  */
-declare function AuthGuard({ children, fallback, redirectTo, className, classNames, showFallback, useSkeleton, }: AuthGuardProps): react_jsx_runtime.JSX.Element | null;
+declare function AuthShell({ children, logo, maxWidth, className, classNames, }: AuthShellProps): react_jsx_runtime.JSX.Element;
 
 interface CreateEmailSignerFormProps {
     walletId: string;
@@ -673,6 +769,21 @@ interface NormalizedWallet {
  * Accepts any object with optional walletId/id, walletAddress/address, isActive.
  */
 declare function normalizeWallet(dto: Record<string, unknown>): NormalizedWallet;
+/** Wallet-like object with optional id/walletId and address/walletAddress. */
+type WalletLike = {
+    id?: string;
+    walletId?: string;
+    address?: string;
+    walletAddress?: string;
+} & Record<string, unknown>;
+/**
+ * Get wallet ID from a wallet-like object. Prefer id; fallback to walletId.
+ */
+declare function getWalletId(wallet: WalletLike | null | undefined): string;
+/**
+ * Get wallet address from a wallet-like object. Prefer address; fallback to walletAddress.
+ */
+declare function getWalletAddress(wallet: WalletLike | null | undefined): string;
 
 declare function extractErrorMessage(error: unknown): string;
 declare function isAuthError(error: unknown): boolean;
@@ -716,4 +827,4 @@ interface SignAndSendConnectionAdapter {
  */
 declare function adaptSolanaConnection(connection: Connection): SignAndSendConnectionAdapter;
 
-export { type ActionState, AddPasskeyButton, type AddPasskeyButtonProps, type ApiResponse, AuthGuard, type AuthGuardClassNames, type AuthGuardProps, type CilantroAuthContextType, type CilantroConfig, CilantroConnect, type CilantroConnectProps, CilantroContextProvider, type CilantroContextValue, CilantroProvider, type CilantroProviderProps, ConnectWalletButton, type ConnectWalletButtonProps, CreateEmailSignerForm, type CreateEmailSignerFormProps, CreatePhoneSignerForm, type CreatePhoneSignerFormProps, CreateWalletForm, type CreateWalletFormProps, type DeviceKeyStorage, ErrorBoundary, type ErrorBoundaryProps, type ErrorResponse, LoadingOverlay, type LoadingOverlayProps, LoginForm, type LoginFormClassNames, type LoginFormProps, LogoutButton, type LogoutButtonProps, type NormalizedWallet, type ResolvedTheme, SIGNER_TYPES, SendSOLForm, type SendSOLFormProps, type SignerType as SendSOLSignerType, SendSPLForm, type SendSPLFormProps, type SignerType$2 as SendTransactionSignerType, type SignAndSendConnection, type SignAndSendConnectionAdapter, type SignAndSendResult, type SignMessageResult, type SignerData, SignerList, type SignerListClassNames, type SignerListProps, SignerSelector, type SignerSelectorClassNames, type SignerSelectorProps, type SignerType$1 as SignerType, Skeleton, type SolanaWallet, type SubmitTransactionDataDto, type SubmitTransactionResult, type Theme, ThemeProvider, type ThemeProviderProps, TransactionHistory, type TransactionHistoryProps, TransactionStatus, type TransactionStatusProps, type UseAuthResult, type UseCilantroConfigResult, type UseExternalWalletResult, type UsePasskeyResult, type UseSendTransactionResult, type UseSignersOptions, type UseSignersResult, type UseWalletResult, type User, WalletAddress, type WalletAddressProps, WalletBalance, type WalletBalanceProps, type WalletContextType, type WalletData, type WalletDataDto$1 as WalletDataDto, type WalletDataDto as WalletDataDtoFromHook, type WalletData as WalletDataFromHook, type WalletInfo, WalletSelector, type WalletSelectorClassNames, type WalletSelectorProps, adaptSolanaConnection, extractErrorMessage, extractResponseData, getSignerPublicKey, getWalletData, isAuthError, isJwtExpired, normalizeSigner, normalizeWallet, signAndSendTransactionWithSigner, signMessageWithSigner, signTransactionWithSigner, useAuth, useCilantroAuth, useCilantroConfig, useCilantroContext, useExternalWallet, usePasskey, useSendTransaction, useSigners, useWallet, useWallets };
+export { type ActionState, AddPasskeyButton, type AddPasskeyButtonProps, type ApiResponse, AuthShell, type AuthShellClassNames, type AuthShellProps, type CilantroAuthContextType, type CilantroConfig, CilantroConnect, type CilantroConnectProps, CilantroContextProvider, type CilantroContextValue, CilantroProvider, type CilantroProviderProps, ConnectWalletButton, type ConnectWalletButtonProps, CreateEmailSignerForm, type CreateEmailSignerFormProps, CreatePhoneSignerForm, type CreatePhoneSignerFormProps, CreateWalletForm, type CreateWalletFormProps, type DeviceKeyStorage, ErrorBoundary, type ErrorBoundaryProps, type ErrorResponse, LoadingOverlay, type LoadingOverlayProps, LoginForm, type LoginFormClassNames, type LoginFormProps, LogoutButton, type LogoutButtonProps, type NormalizedWallet, RegisterForm, type RegisterFormClassNames, type RegisterFormProps, type ResolvedTheme, SIGNER_TYPES, SendSOLForm, type SendSOLFormProps, type SignerType as SendSOLSignerType, SendSPLForm, type SendSPLFormProps, type SignerType$2 as SendTransactionSignerType, type SignAndSendConnection, type SignAndSendConnectionAdapter, type SignAndSendResult, type SignMessageResult, type SignerData, SignerList, type SignerListClassNames, type SignerListProps, SignerSelector, type SignerSelectorClassNames, type SignerSelectorProps, type SignerType$1 as SignerType, Skeleton, type SolanaWallet, type SubmitTransactionDataDto, type SubmitTransactionResult, type Theme, ThemeProvider, type ThemeProviderProps, TransactionHistory, type TransactionHistoryProps, TransactionStatus, type TransactionStatusProps, type UseAuthResult, type UseCilantroConfigResult, type UseExternalWalletResult, type UsePasskeyResult, type UseReturnUrlOptions, type UseSendTransactionResult, type UseSignersOptions, type UseSignersResult, type UseWalletResult, type User, WalletAddress, type WalletAddressProps, WalletBalance, type WalletBalanceProps, type WalletContextType, type WalletData, type WalletDataDto$1 as WalletDataDto, type WalletDataDto as WalletDataDtoFromHook, type WalletData as WalletDataFromHook, type WalletInfo, type WalletLike, WalletSelector, type WalletSelectorClassNames, type WalletSelectorProps, adaptSolanaConnection, extractErrorMessage, extractResponseData, getSignerPublicKey, getWalletAddress, getWalletData, getWalletId, isAuthError, isJwtExpired, normalizeSigner, normalizeWallet, signAndSendTransactionWithSigner, signMessageWithSigner, signTransactionWithSigner, useAuth, useCilantroAuth, useCilantroConfig, useCilantroContext, useExternalWallet, usePasskey, useReturnUrl, useSendTransaction, useSigners, useWallet, useWallets };