cilantro-react 0.1.6 → 0.1.7

package/README.md

@@ -14,6 +14,7 @@ React SDK/UI for [Cilantro Smart Wallet](https://www.npmjs.com/package/cilantro-
     - [Storage Adapters](#storage-adapters)
   - [Hooks](#hooks)
     - [useAuth](#useauth)
+    - [useReturnUrl](#usereturnurl)
     - [useWallet](#usewallet)
     - [useSigners](#usesigners)
     - [usePasskey](#usepasskey)
@@ -23,8 +24,11 @@ React SDK/UI for [Cilantro Smart Wallet](https://www.npmjs.com/package/cilantro-
   - [Components](#components)
     - [Auth Components](#auth-components)
       - [LoginForm](#loginform)
+      - [RegisterForm](#registerform)
       - [LogoutButton](#logoutbutton)
       - [AuthGuard](#authguard)
+      - [AuthShell](#authshell)
+      - [NextAuthGuard (Next.js)](#nextauthguard-nextjs)
     - [Wallet Components](#wallet-components)
       - [WalletSelector](#walletselector)
       - [CreateWalletForm](#createwalletform)
@@ -144,10 +148,16 @@ const storage = createIndexedDBAdapter();
 | `apiKey` | `string` | No* | — | Platform API key for server-side operations |
 | `baseURL` | `string` | No | `https://api.cilantro.gg` | API base URL |
 | `storageAdapter` | `DeviceKeyStorage` | No | IndexedDB | Storage adapter for device keys |
+| `syncJwtToCookie` | `boolean` | No | `false` | When true, sync JWT to a cookie for Next.js/middleware |
+| `jwtCookieName` | `string` | No | `cilantro_jwt` | Cookie name when `syncJwtToCookie` is true |
 | `children` | `ReactNode` | Yes | — | App content |
 
 *Either `apiKey` or JWT (obtained via login) is required for authenticated requests.
 
+### SDK Auth (automatic)
+
+**CilantroProvider configures the underlying cilantro-sdk authentication when the user is logged in.** Once you have a JWT in context (from login or session restore), all cilantro-sdk calls in the same app use that auth automatically. You do **not** need to call `setSdkAuth` or similar before each request; the provider handles it.
+
 ### Storage Adapters
 
 For email and phone signers, device keys must be stored. Choose an adapter:
@@ -171,6 +181,28 @@ const storage = createLocalStorageAdapter();
 const storage = createMemoryAdapter();
 ```
 
+### Next.js / Middleware
+
+For Next.js apps, middleware runs on the server and cannot access `localStorage`. To protect routes or read the JWT in middleware:
+
+1. Enable JWT cookie sync: `<CilantroProvider syncJwtToCookie>`
+2. In middleware, read the cookie (default name: `cilantro_jwt`) to check auth.
+3. Optionally redirect unauthenticated users. Example:
+
+```ts
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('cilantro_jwt')?.value;
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+  return NextResponse.next();
+}
+```
+
 ---
 
 ## Hooks
@@ -183,12 +215,16 @@ Authentication state and actions.
 import { useAuth } from 'cilantro-react';
 
 function MyComponent() {
-  const { user, jwt, isLoading, isAuthenticated, login, logout } = useAuth();
+  const { user, jwt, isLoading, isAuthenticated, login, register, logout, clearSessionDueToAuthError } = useAuth();
 
   const handleLogin = async () => {
     await login({ usernameOrEmail: 'user@example.com', password: 'password123' });
   };
 
+  const handleRegister = async () => {
+    await register('johndoe', 'john@example.com', 'password123');
+  };
+
   return (
     <div>
       {isLoading && <p>Loading...</p>}
@@ -210,11 +246,35 @@ function MyComponent() {
 | Property | Type | Description |
 |----------|------|-------------|
 | `user` | `User \| null` | Current user object (`{ username?, email?, userType? }`) |
-| `jwt` | `string \| null` | JWT token (null when not authenticated) |
+| `jwt` | `string \| null` | JWT token (null when not authenticated). Prefer this name. |
+| `token` | `string \| null` | Alias for `jwt`. Same value. |
 | `isLoading` | `boolean` | True while restoring session from storage |
 | `isAuthenticated` | `boolean` | True when user has valid JWT |
 | `login` | `(params: { usernameOrEmail: string; password: string }) => Promise<void>` | Log in; throws on error |
+| `register` | `(username: string, email: string, password: string, isActive?: boolean) => Promise<void>` | Register and auto-login |
 | `logout` | `() => void` | Clear session and token |
+| `clearSessionDueToAuthError` | `() => void` | Clear session when API returns 401/403; calls `onSessionExpired` |
+
+---
+
+### useReturnUrl
+
+Read `returnUrl` from URL search params for redirect-after-auth flows.
+
+```tsx
+import { useReturnUrl } from 'cilantro-react';
+
+function LoginPage() {
+  const { returnPath, redirect, rawReturnUrl } = useReturnUrl({ param: 'returnUrl', defaultPath: '/' });
+
+  return (
+    <LoginForm
+      redirectAfterSuccess={returnPath}
+      onRedirect={(path) => router.replace(path)}
+    />
+  );
+}
+```
 
 ---
 
@@ -226,7 +286,7 @@ Wallet state and actions.
 import { useWallet } from 'cilantro-react';
 
 function WalletManager() {
-  const { wallet, wallets, createWallet, selectWallet, isLoading } = useWallet();
+  const { wallet, wallets, createWallet, selectWallet, refreshWallets, isLoading, error } = useWallet();
 
   const handleCreate = async () => {
     const result = await createWallet({ name: 'My New Wallet' });
@@ -236,6 +296,7 @@ function WalletManager() {
   return (
     <div>
       {isLoading && <p>Loading wallets...</p>}
+      {error && <p className="text-red-500">{error}</p>}
       <p>Current wallet: {wallet?.walletName ?? 'None selected'}</p>
       <ul>
         {wallets.map((w) => (
@@ -245,6 +306,7 @@ function WalletManager() {
         ))}
       </ul>
       <button onClick={handleCreate}>Create Wallet</button>
+      <button onClick={refreshWallets}>Refresh</button>
     </div>
   );
 }
@@ -258,7 +320,9 @@ function WalletManager() {
 | `wallets` | `WalletData[]` | All wallets for the authenticated user |
 | `createWallet` | `(params: { name: string; userId?: string }) => Promise<WalletControllerCreateResult>` | Create a new wallet |
 | `selectWallet` | `(walletId: string) => void` | Select a wallet by ID |
+| `refreshWallets` | `() => Promise<void>` | Refresh wallet list from API |
 | `isLoading` | `boolean` | True while loading wallets |
+| `error` | `string \| null` | Error from wallet operations (e.g. fetch failed) |
 
 ---
 
@@ -524,6 +588,8 @@ import { LoginForm } from 'cilantro-react';
 <LoginForm
   onSuccess={() => console.log('Logged in!')}
   onError={(err) => console.error(err.message)}
+  redirectAfterSuccess="/dashboard"
+  onRedirect={(path) => router.replace(path)}
   title="Welcome back"
   description="Sign in to your account"
   submitLabel="Sign in"
@@ -538,6 +604,9 @@ import { LoginForm } from 'cilantro-react';
 |------|------|---------|-------------|
 | `onSuccess` | `() => void` | — | Called after successful login |
 | `onError` | `(error: Error) => void` | — | Called on login error |
+| `redirectAfterSuccess` | `string` | — | Redirect to this path after login. If unset, reads from URL `?returnUrl=` |
+| `onRedirect` | `(path: string) => void` | — | Custom redirect for SPA routers |
+| `returnUrlParam` | `string` | `"returnUrl"` | Query param to read return URL from |
 | `title` | `string` | `"Sign in"` | Form title |
 | `description` | `string` | — | Form description |
 | `submitLabel` | `string` | `"Sign in"` | Submit button label |
@@ -557,6 +626,8 @@ import { LogoutButton } from 'cilantro-react';
 
 <LogoutButton
   onLogout={() => console.log('Logged out')}
+  redirectAfterLogout="/login"
+  onRedirect={(path) => router.replace(path)}
   confirmBeforeLogout={true}
 >
   Sign out
@@ -568,6 +639,8 @@ import { LogoutButton } from 'cilantro-react';
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `onLogout` | `() => void` | — | Called after logout |
+| `redirectAfterLogout` | `string` | — | Redirect to this path after logout |
+| `onRedirect` | `(path: string) => void` | — | Custom redirect for SPA routers |
 | `confirmBeforeLogout` | `boolean` | `false` | Show confirmation dialog |
 | `className` | `string` | — | Button class |
 | `children` | `ReactNode` | `"Log out"` | Button content |
@@ -591,11 +664,23 @@ import { AuthGuard, LoginForm } from 'cilantro-react';
   <ProtectedContent />
 </AuthGuard>
 
-// Redirect instead of showing fallback
+// Redirect to login page (appends ?returnUrl=currentPath for redirect-after-login)
 <AuthGuard redirectTo="/login">
   <ProtectedContent />
 </AuthGuard>
 
+// Next.js / React Router: use onRedirect for client-side navigation (no full page reload)
+import { useRouter } from 'next/navigation';
+const router = useRouter();
+<AuthGuard redirectTo="/login" onRedirect={(path) => router.replace(path)}>
+  <ProtectedContent />
+</AuthGuard>
+
+// Polished UX: centered or fullscreen layout for auth fallback
+<AuthGuard layout="centered">  {/* or "fullscreen" */}
+  <ProtectedContent />
+</AuthGuard>
+
 // Hide content when not authenticated (no fallback)
 <AuthGuard showFallback={false}>
   <ProtectedContent />
@@ -613,7 +698,10 @@ import { AuthGuard, LoginForm } from 'cilantro-react';
 |------|------|---------|-------------|
 | `children` | `ReactNode` | — | Content to show when authenticated |
 | `fallback` | `ReactNode` | `<LoginForm />` | Content when not authenticated |
-| `redirectTo` | `string` | — | Redirect URL when not authenticated |
+| `redirectTo` | `string` | — | Redirect unauthenticated users to this path (appends `?returnUrl=`) |
+| `onRedirect` | `(path: string) => void` | — | Custom redirect for SPA routers (e.g. `router.replace`) |
+| `returnUrlParam` | `string` | `"returnUrl"` | Query param name for return URL |
+| `layout` | `"inline" \| "centered" \| "fullscreen"` | `"inline"` | Layout for fallback content |
 | `showFallback` | `boolean` | `true` | Whether to show fallback or null |
 | `useSkeleton` | `boolean` | `false` | Show skeleton while loading auth state |
 | `className` | `string` | — | Root element class |
@@ -621,6 +709,52 @@ import { AuthGuard, LoginForm } from 'cilantro-react';
 
 ---
 
+#### RegisterForm
+
+Registration form with username, email, and password. Auto-login after success.
+
+```tsx
+import { RegisterForm } from 'cilantro-react';
+
+<RegisterForm
+  onSuccess={() => console.log('Registered!')}
+  redirectAfterSuccess="/dashboard"
+  onRedirect={(path) => router.replace(path)}  // For Next.js/React Router
+  renderSwitchToLogin={() => <a href="/login">Already have an account? Sign in</a>}
+/>
+```
+
+---
+
+#### AuthShell
+
+Full-page centered layout for auth screens. Use for standalone login/register pages.
+
+```tsx
+import { AuthShell, LoginForm } from 'cilantro-react';
+
+<AuthShell logo={<img src="/logo.svg" alt="App" />} maxWidth="sm">
+  <LoginForm redirectAfterSuccess="/dashboard" />
+</AuthShell>
+```
+
+---
+
+#### NextAuthGuard (Next.js)
+
+Drop-in AuthGuard for Next.js App Router. Uses `router.replace()` for client-side redirects.
+Requires `next` to be installed.
+
+```tsx
+import { NextAuthGuard } from 'cilantro-react/next';
+
+<NextAuthGuard redirectTo="/login" layout="fullscreen">
+  <ProtectedContent />
+</NextAuthGuard>
+```
+
+---
+
 ### Wallet Components
 
 #### WalletSelector
@@ -1191,11 +1325,17 @@ const adapted = adaptSolanaConnection(connection);
 |----------|-------------|
 | `extractErrorMessage(error)` | Normalize unknown errors to string |
 | `extractResponseData(response)` | Unwrap SDK response shapes |
-| `normalizeWallet(dto)` | Normalize wallet data from SDK |
+| `normalizeWallet(dto)` | Normalize wallet data from SDK (ensures `id` and `address`) |
 | `normalizeSigner(dto)` | Normalize signer data from SDK |
-| `isJwtExpired(jwt)` | Check if JWT is expired |
+| `getWalletId(wallet)` | Get wallet ID from wallet-like object (`id ?? walletId`) |
+| `getWalletAddress(wallet)` | Get wallet address from wallet-like object (`address ?? walletAddress`) |
+| `isJwtExpired(token, bufferSeconds?)` | Check if JWT is expired. Uses `exp` claim; optional buffer (default 60s) treats tokens near expiry as expired. Exported for apps that sync JWT to cookies or need expiry checks. |
 | `isAuthError(error)` | Check if error is an auth error |
 
+### Wallet shape
+
+Wallet data from the SDK may use `walletId`/`walletAddress` or `id`/`address`. The library normalizes at boundaries so **`id`** and **`address`** are preferred. Use `getWalletId(wallet)` and `getWalletAddress(wallet)` when you need to handle both shapes consistently.
+
 ---
 
 ## Types

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 };