cilantro-react 0.1.5 → 0.1.7

package/README.md

@@ -1,8 +1,68 @@
 # cilantro-react
 
-React SDK/UI for [Cilantro Smart Wallet](https://www.npmjs.com/package/cilantro-sdk). Provides a single context provider, hooks, and UI components for auth, wallets, signers, and transactions. Install as **cilantro-react**; documentation may show `@cilantro/react-sdk` for illustration—use `cilantro-react` in install and imports.
+React SDK/UI for [Cilantro Smart Wallet](https://www.npmjs.com/package/cilantro-sdk). Provides a single context provider, hooks, and UI components for authentication, wallets, signers, and transactions.
+
+## Table of Contents
+
+- [cilantro-react](#cilantro-react)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [Polyfills (Browser)](#polyfills-browser)
+  - [Quick Start](#quick-start)
+  - [CilantroProvider](#cilantroprovider)
+    - [Props](#props)
+    - [Storage Adapters](#storage-adapters)
+  - [Hooks](#hooks)
+    - [useAuth](#useauth)
+    - [useReturnUrl](#usereturnurl)
+    - [useWallet](#usewallet)
+    - [useSigners](#usesigners)
+    - [usePasskey](#usepasskey)
+    - [useExternalWallet](#useexternalwallet)
+    - [useSendTransaction](#usesendtransaction)
+    - [useCilantroConfig](#usecilantroconfig)
+  - [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)
+      - [WalletAddress](#walletaddress)
+      - [WalletBalance](#walletbalance)
+      - [ConnectWalletButton](#connectwalletbutton)
+    - [Signer Components](#signer-components)
+      - [SignerSelector](#signerselector)
+      - [SignerList](#signerlist)
+      - [CreateEmailSignerForm](#createemailsignerform)
+      - [CreatePhoneSignerForm](#createphonesignerform)
+      - [AddPasskeyButton](#addpasskeybutton)
+    - [Transaction Components](#transaction-components)
+      - [SendSOLForm](#sendsolform)
+      - [SendSPLForm](#sendsplform)
+      - [TransactionStatus](#transactionstatus)
+      - [TransactionHistory](#transactionhistory)
+    - [Layout Components](#layout-components)
+      - [CilantroConnect](#cilantroconnect)
+      - [LoadingOverlay](#loadingoverlay)
+      - [ErrorBoundary](#errorboundary)
+  - [Theming](#theming)
+    - [Built-in Theme (ThemeProvider)](#built-in-theme-themeprovider)
+    - [Import Theme CSS Directly](#import-theme-css-directly)
+  - [Advanced Usage](#advanced-usage)
+    - [Low-Level Signer Signing](#low-level-signer-signing)
+    - [Solana Connection Adapter](#solana-connection-adapter)
+    - [Utilities](#utilities)
+  - [Types](#types)
+  - [License](#license)
 
-## Install
+---
+
+## Installation
 
 ```bash
 npm install cilantro-react cilantro-sdk
@@ -12,907 +72,1316 @@ yarn add cilantro-react cilantro-sdk
 pnpm add cilantro-react cilantro-sdk
 ```
 
-**Peer dependencies:** React 18+, `cilantro-sdk`. Optionally `@solana/web3.js` for transaction/signing. Components use Tailwind-compatible class names; ensure your app has [Tailwind CSS](https://tailwindcss.com) configured.
+**Requirements:**
+
+- React 18+
+- `cilantro-sdk` (peer dependency)
+- [Tailwind CSS](https://tailwindcss.com) for component styling (components use Tailwind-compatible class names)
 
-## Polyfills (browser)
+### Polyfills (Browser)
 
-Import at the very top of your entry file (e.g. `main.tsx`, `App.tsx`):
+Import polyfills at the very top of your entry file (before any other imports):
 
 ```ts
-import 'cilantro-sdk/polyfills'
+import 'cilantro-sdk/polyfills';
 ```
 
-## Wrap your app
+---
+
+## Quick Start
 
 ```tsx
-import { CilantroProvider } from 'cilantro-react'
+import 'cilantro-sdk/polyfills';
+import { CilantroProvider, LoginForm, AuthGuard, useAuth, useWallet } from 'cilantro-react';
 
-function Root() {
+function App() {
   return (
     <CilantroProvider
       apiKey={import.meta.env.VITE_API_KEY}
       baseURL="https://api.cilantro.gg"
     >
-      <App />
+      <AuthGuard>
+        <Dashboard />
+      </AuthGuard>
     </CilantroProvider>
-  )
+  );
+}
+
+function Dashboard() {
+  const { user, logout } = useAuth();
+  const { wallet, wallets } = useWallet();
+
+  return (
+    <div>
+      <p>Welcome, {user?.username}</p>
+      <p>Wallet: {wallet?.walletName}</p>
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
 }
 ```
 
-### Storage adapter (device keys)
+---
+
+## CilantroProvider
 
-For email and phone signers, device keys must be stored. Configure a storage adapter:
+The root provider that initializes configuration, storage, authentication, and wallet state.
 
 ```tsx
-import { CilantroProvider, createIndexedDBAdapter } from 'cilantro-react'
+import { CilantroProvider, createIndexedDBAdapter } from 'cilantro-react';
 
-const storage = createIndexedDBAdapter()
+const storage = createIndexedDBAdapter();
 
-<CilantroProvider apiKey={API_KEY} storageAdapter={storage}>
+<CilantroProvider
+  apiKey="your-platform-api-key"
+  baseURL="https://api.cilantro.gg"
+  storageAdapter={storage}
+>
   <App />
 </CilantroProvider>
 ```
 
-| Adapter | Use case |
-|---------|----------|
-| `createIndexedDBAdapter()` | Production – persistent, large capacity |
-| `createLocalStorageAdapter()` | Development – simple, limited capacity |
-| `createMemoryAdapter()` | Testing – not persisted |
+### Props
 
-**CilantroProvider props (guide API):**
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `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 |
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `apiKey` | `string` | Platform API key (optional if using JWT via login). |
-| `baseURL` | `string` | API base URL (default: `https://api.cilantro.gg`). |
-| `storageAdapter` | `DeviceKeyStorage` | Storage for device keys (default: IndexedDB in browser). |
-| `children` | `ReactNode` | App content. |
+*Either `apiKey` or JWT (obtained via login) is required for authenticated requests.
 
-Backward compatibility: `platformApiKey` / `apiUrl` are still supported (deprecated). See [API reference](#api-reference) for full props.
+### SDK Auth (automatic)
 
-**Connection:** The library does not create a Solana RPC connection. For transaction sign-and-send, pass your own `connection` from `@solana/web3.js` into `useTransactionSigning` / `TransactionSigningForm`. See [Connection setup](#connection-setup-solana) below.
+**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
 
-## Display logic and form visibility
+For email and phone signers, device keys must be stored. Choose an adapter:
 
-Message and transaction signing forms only show the actual form when **both** a wallet and a signer are selected:
+| Adapter | Use Case |
+|---------|----------|
+| `createIndexedDBAdapter()` | **Production** – persistent, large capacity |
+| `createLocalStorageAdapter()` | Development – simple, limited capacity |
+| `createMemoryAdapter()` | Testing – not persisted |
 
-- **Wallet selected:** Use `useWallets().selectedWallet` as the single source of truth. Derive `walletId` and `hasWallet` from it:  
-  `walletId = selectedWallet?.id ?? selectedWallet?.walletId ?? ""`,  
-  `hasWallet = !!walletId`.
-- **Signer selected:** Use `useSignerSelection().selectedSigner`; `hasSigner = !!selectedSigner`.
+```tsx
+import { createIndexedDBAdapter, createLocalStorageAdapter, createMemoryAdapter } from 'cilantro-react';
 
-Show the form only when `hasWallet && hasSigner`. Do not rely only on `useSignerSelection().selectedWalletId` for “wallet selected” to avoid sync issues between the two hooks. When building custom pages, pass `selectedWalletId={walletId}` and `selectedSigner={selectedSigner}` explicitly into `MessageSigningForm` / `TransactionSigningForm` so the forms use the same wallet/signer state as your UI.
+// Production
+const storage = createIndexedDBAdapter();
 
----
+// Development
+const storage = createLocalStorageAdapter();
 
-## Connection setup (Solana)
+// Testing
+const storage = createMemoryAdapter();
+```
 
-For transaction sign-and-send (wallet-adapter or passkey), the library expects a connection object with `sendRawTransaction`, `getLatestBlockhash`, and `confirmTransaction`. If you use `@solana/web3.js`, use the provided adapter so you don’t need type assertions:
+### Next.js / Middleware
 
-```tsx
-import { Connection } from '@solana/web3.js'
-import { adaptSolanaConnection, TransactionSigningForm } from 'cilantro-react'
+For Next.js apps, middleware runs on the server and cannot access `localStorage`. To protect routes or read the JWT in middleware:
 
-const connection = new Connection('https://api.mainnet-beta.solana.com')
+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:
 
-<TransactionSigningForm
-  connection={adaptSolanaConnection(connection)}
-  showContext
-/>
+```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();
+}
 ```
 
-`adaptSolanaConnection(connection)` returns an object that matches the library’s expected connection shape. You can pass it to `TransactionSigningForm` or `useTransactionSigning({ connection: adaptSolanaConnection(solanaConnection), ... })`.
-
 ---
 
-## Headless usage and custom selectors
+## Hooks
 
-You can build your own wallet/signer UI with the hooks and render props instead of the built-in selectors:
+### useAuth
 
-- **Wallet:** Use `useWallets()` for `wallets`, `selectedWallet`, `selectWallet`, and `refreshWallets`. Use the `WalletSelector` `children` render prop to render your own list/dropdown; you get `{ wallets, selectedWallet, selectWallet, isLoading, refreshWallets }`.
-- **Signer:** Use `useSignerSelection()` for `availableSigners`, `selectedSigner`, `setSelectedSigner`, and `isLoadingSigners`. Use the `SignerSelector` `children` or `renderList` prop to render your own list (e.g. Shadcn Select or custom buttons).
-
-Example: custom wallet + signer selection and conditional form:
+Authentication state and actions.
 
 ```tsx
-const { selectedWallet } = useWallets()
-const { availableSigners, selectedSigner, setSelectedSigner, isLoadingSigners } = useSignerSelection()
-const walletId = selectedWallet?.id ?? selectedWallet?.walletId ?? ''
-const hasWallet = !!walletId
-const hasSigner = !!selectedSigner
+import { useAuth } from 'cilantro-react';
 
-return (
-  <>
-    <WalletSelector>{({ wallets, selectedWallet, selectWallet, isLoading }) => (
-      /* your custom wallet dropdown */
-    )}</WalletSelector>
-    <SignerSelector
-      selectedWalletId={walletId}
-      availableSigners={availableSigners}
-      selectedSigner={selectedSigner}
-      onSignerSelect={setSelectedSigner}
-      isLoadingSigners={isLoadingSigners}
-    >
-      {({ signers, selectedSigner, onSignerSelect, isLoading }) => (
-        /* your custom signer list */
-      )}
-    </SignerSelector>
-    {hasWallet && hasSigner && (
-      <MessageSigningForm
-        selectedWalletId={walletId}
-        selectedSigner={selectedSigner}
-        showContext={false}
-      />
-    )}
-  </>
-)
-```
+function MyComponent() {
+  const { user, jwt, isLoading, isAuthenticated, login, register, logout, clearSessionDueToAuthError } = useAuth();
 
----
+  const handleLogin = async () => {
+    await login({ usernameOrEmail: 'user@example.com', password: 'password123' });
+  };
 
-## Property names (SDK → library)
+  const handleRegister = async () => {
+    await register('johndoe', 'john@example.com', 'password123');
+  };
 
-The library normalizes wallet and signer data at the boundary. You can rely on these fields in UI and hooks:
+  return (
+    <div>
+      {isLoading && <p>Loading...</p>}
+      {isAuthenticated ? (
+        <>
+          <p>Hello, {user?.username}</p>
+          <button onClick={logout}>Logout</button>
+        </>
+      ) : (
+        <button onClick={handleLogin}>Login</button>
+      )}
+    </div>
+  );
+}
+```
 
-| SDK / API field   | Normalized / library field | Notes                          |
-|-------------------|----------------------------|--------------------------------|
-| `walletId`        | `id`                       | WalletData always has `id`.    |
-| `walletAddress`   | `address`                  | WalletData always has `address`. |
-| `isActive`        | `active`                   | WalletData alias.              |
-| `signerId`        | `id`                       | SignerData always has `id` and `signerId`. |
-| `signerPubkey` / `publicKey` | `signerPubkey` and `publicKey` | SignerData has both.   |
-| `signerType` / `type` | `signerType` and `type` | SignerData has both.           |
+**Returns: `UseAuthResult`**
 
-Use `normalizeWallet(dto)` and `normalizeSigner(dto, category)` at API boundaries if you ingest raw SDK responses; the provider and `loadSigners` already use normalized shapes.
+| Property | Type | Description |
+|----------|------|-------------|
+| `user` | `User \| null` | Current user object (`{ username?, email?, userType? }`) |
+| `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` |
 
 ---
 
-## API reference
+### useReturnUrl
 
-### Providers
+Read `returnUrl` from URL search params for redirect-after-auth flows.
 
-- **CilantroProvider** – Root provider: initializes storage, auth, and wallet context. Requires `platformApiKey`; optional `apiUrl`, storage keys, and callbacks. Use this unless you only need auth.
-- **CilantroAuthProvider** – Auth only (token, user, login, register, logout). Use when you don’t need the full provider stack (e.g. auth-only pages).
-- **WalletProvider** – Wallet list and selection. Depends on auth; usually used inside `CilantroProvider`.
-- **ThemeProvider** – Optional: sets `data-theme="light"` or `"dark"` on a wrapper and injects default CSS variables for light/dark. Props: `theme` (`"light"` | `"dark"` | `"system"`), `defaultTheme`, `storageKey`, `className`, `injectStyles`. See [Themes](#built-in-theme-themeprovider).
+```tsx
+import { useReturnUrl } from 'cilantro-react';
 
-**CilantroAuthProvider props:** `platformApiKey` (required), `apiUrl`, `jwtStorageKey`, `onLoginSuccess`, `onLogout`, `onRegisterSuccess`.
+function LoginPage() {
+  const { returnPath, redirect, rawReturnUrl } = useReturnUrl({ param: 'returnUrl', defaultPath: '/' });
 
-**WalletProvider props:** `storageKey` (default: `cilantro_selected_wallet_id`).
+  return (
+    <LoginForm
+      redirectAfterSuccess={returnPath}
+      onRedirect={(path) => router.replace(path)}
+    />
+  );
+}
+```
 
 ---
 
-### Custom hooks (detailed)
+### useWallet
+
+Wallet state and actions.
+
+```tsx
+import { useWallet } from 'cilantro-react';
 
-All hooks must be used within the appropriate provider (see each hook below).
+function WalletManager() {
+  const { wallet, wallets, createWallet, selectWallet, refreshWallets, isLoading, error } = useWallet();
 
-#### useCilantroAuth
+  const handleCreate = async () => {
+    const result = await createWallet({ name: 'My New Wallet' });
+    console.log('Created:', result.data.id);
+  };
 
-Auth state and actions. Use inside `CilantroAuthProvider` or `CilantroProvider`.
+  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) => (
+          <li key={w.id} onClick={() => selectWallet(w.id)}>
+            {w.walletName}
+          </li>
+        ))}
+      </ul>
+      <button onClick={handleCreate}>Create Wallet</button>
+      <button onClick={refreshWallets}>Refresh</button>
+    </div>
+  );
+}
+```
 
-**Returns:** `CilantroAuthContextType`
+**Returns: `UseWalletResult`**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `token` | `string \| null` | JWT token (null when not authenticated). |
-| `user` | `User \| null` | User object: `{ username?, email?, userType? }`. |
-| `isAuthenticated` | `boolean` | True when `token` is set. |
-| `isLoading` | `boolean` | True while restoring session from storage. |
-| `login` | `(usernameOrEmail: string, password: string) => Promise<void>` | Log in; throws on error. |
-| `register` | `(username: string, email: string, password: string, isActive?: boolean) => Promise<void>` | Register and log in; throws on error. |
-| `logout` | `() => void` | Clear token and user; calls `onLogout` if provided. |
+| `wallet` | `WalletData \| null` | Currently selected wallet |
+| `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) |
 
 ---
 
-#### useWallets
-
-Wallet list and selection. Use inside `CilantroProvider` (which includes `WalletProvider`).
-
-**Returns:** `WalletContextType`
+### useSigners
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `wallets` | `WalletData[]` | List of wallets for the authenticated user. |
-| `selectedWallet` | `WalletData \| null` | Currently selected wallet (persisted in localStorage). |
-| `selectWallet` | `(walletId: string) => void` | Set the selected wallet by id. |
-| `refreshWallets` | `() => Promise<void>` | Reload wallets from the API. |
-| `isLoading` | `boolean` | True while loading wallets. |
+Signers for a specific wallet.
 
-**WalletData:** `{ id, walletId, walletName?, address?, walletAddress?, chain?, active?, ... }`.
+```tsx
+import { useSigners } from 'cilantro-react';
+
+function SignerManager({ walletId }: { walletId: string }) {
+  const {
+    signers,
+    isLoading,
+    error,
+    refresh,
+    createEmailSigner,
+    createPhoneSigner,
+    revokeSigner,
+  } = useSigners(walletId);
+
+  const handleCreateEmail = async () => {
+    const signer = await createEmailSigner({ email: 'user@example.com' });
+    console.log('Created signer:', signer.signerId);
+  };
+
+  const handleCreatePhone = async () => {
+    const signer = await createPhoneSigner({ phone: '+1234567890' });
+    console.log('Created signer:', signer.signerId);
+  };
 
----
+  return (
+    <div>
+      {isLoading && <p>Loading signers...</p>}
+      {error && <p className="text-red-500">{error}</p>}
+      <ul>
+        {signers.map((s) => (
+          <li key={s.id}>
+            {s.email || s.phone || s.id} ({s.signerType})
+            <button onClick={() => revokeSigner(s.id)}>Revoke</button>
+          </li>
+        ))}
+      </ul>
+      <button onClick={handleCreateEmail}>Add Email Signer</button>
+      <button onClick={handleCreatePhone}>Add Phone Signer</button>
+      <button onClick={refresh}>Refresh</button>
+    </div>
+  );
+}
+```
 
-#### useSelectedWallet
+**Parameters:**
 
-Convenience hook when you only need the currently selected wallet (and loading/refresh), not the full list. Use inside `CilantroProvider`.
+- `walletId: string | null | { walletId?: string | null }` — Wallet ID to load signers for
 
-**Returns:** `UseSelectedWalletResult`
+**Returns: `UseSignersResult`**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `selectedWallet` | `WalletData \| null` | Currently selected wallet. |
-| `isLoading` | `boolean` | True while loading wallets. |
-| `refreshWallets` | `() => Promise<void>` | Reload wallets from the API. |
-
-**Use when:** You need the current wallet without the full wallet list or `selectWallet`.
+| `signers` | `SignerData[]` | List of signers for the wallet |
+| `isLoading` | `boolean` | True while loading |
+| `error` | `string \| null` | Error message if load failed |
+| `refresh` | `() => Promise<void>` | Reload signers |
+| `createEmailSigner` | `(params: { email: string }) => Promise<SignerInfo>` | Create email signer |
+| `createPhoneSigner` | `(params: { phone: string }) => Promise<SignerInfo>` | Create phone signer |
+| `revokeSigner` | `(signerId: string) => Promise<void>` | Revoke a signer |
 
 ---
 
-#### useWalletAddress
+### usePasskey
 
-Returns the address of the currently selected wallet (handles both `address` and `walletAddress` on WalletData). Use inside `CilantroProvider`.
+Passkey (WebAuthn) registration and authentication.
 
-**Returns:** `string | null`
+```tsx
+import { usePasskey } from 'cilantro-react';
 
-**Use when:** You need the selected wallet's address for display or building transactions.
+function PasskeyManager({ walletId }: { walletId: string }) {
+  const { isSupported, register, authenticate, isLoading } = usePasskey(walletId);
 
----
+  if (!isSupported) {
+    return <p>Passkeys not supported in this browser.</p>;
+  }
 
-#### useSigners
+  const handleRegister = async () => {
+    const result = await register();
+    console.log('Passkey registered:', result.signerId);
+  };
 
-Load signers for a wallet. Use inside `CilantroProvider` (auth required).
+  const handleAuthenticate = async () => {
+    const result = await authenticate();
+    console.log('Authenticated with passkey');
+  };
 
-**Options:** `UseSignersOptions`
+  return (
+    <div>
+      <button onClick={handleRegister} disabled={isLoading}>
+        {isLoading ? 'Registering...' : 'Register Passkey'}
+      </button>
+      <button onClick={handleAuthenticate} disabled={isLoading}>
+        {isLoading ? 'Authenticating...' : 'Authenticate'}
+      </button>
+    </div>
+  );
+}
+```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `walletId` | `string \| null \| undefined` | Wallet ID to load signers for. If omitted, you can pass it from `useWallets().selectedWallet?.id`. |
+**Parameters:**
 
-**Returns:** `UseSignersResult`
+- `walletId: string | undefined` — Wallet ID to register passkey for
+
+**Returns: `UsePasskeyResult`**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `signers` | `SignerData[]` | List of signers for the wallet. |
-| `isLoading` | `boolean` | True while loading. |
-| `error` | `string \| null` | Error message if load failed. |
-| `refresh` | `() => Promise<void>` | Reload signers. |
-
-When `walletId` is null/undefined, `signers` is empty and `refresh` no-ops.
+| `isSupported` | `boolean` | True if WebAuthn is available |
+| `register` | `() => Promise<{ signerId: string; isNew: boolean }>` | Register a new passkey |
+| `authenticate` | `(signerId?: string) => Promise<{ credential: unknown }>` | Authenticate with passkey |
+| `isLoading` | `boolean` | True during operation |
 
 ---
 
-#### useSignersForSelectedWallet
+### useExternalWallet
 
-Signers for the currently selected wallet (or a `walletId` override). Composes `useWallets` + `useSigners` so you don't pass `walletId` yourself. Use inside `CilantroProvider`.
+Connect to external Solana wallets (Phantom, Solflare, etc.).
 
-**Options:** `UseSignersForSelectedWalletOptions`
+```tsx
+import { useExternalWallet } from 'cilantro-react';
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `walletId` | `string \| null \| undefined` | Override; when omitted, uses the selected wallet from context. |
+function ExternalWalletConnect() {
+  const { wallets, connectedWallet, connect, disconnect } = useExternalWallet();
 
-**Returns:** Same as `useSigners` – `UseSignersResult` (`signers`, `isLoading`, `error`, `refresh`).
+  return (
+    <div>
+      {connectedWallet ? (
+        <div>
+          <p>Connected: {connectedWallet.name}</p>
+          <p>Public Key: {connectedWallet.publicKey?.toBase58()}</p>
+          <button onClick={disconnect}>Disconnect</button>
+        </div>
+      ) : (
+        <div>
+          {wallets.map((wallet) => (
+            <button key={wallet.name} onClick={() => connect(wallet)}>
+              Connect {wallet.name}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+**Returns: `UseExternalWalletResult`**
 
-**Use when:** You need signers for the current wallet without calling `useWallets()` and `useSigners({ walletId })` in every component (e.g. SignerList-style UIs).
+| Property | Type | Description |
+|----------|------|-------------|
+| `wallets` | `SolanaWallet[]` | Detected Solana wallets (Phantom, Solflare, etc.) |
+| `connectedWallet` | `SolanaWallet \| null` | Currently connected wallet |
+| `connect` | `(wallet: SolanaWallet) => Promise<void>` | Connect to a wallet |
+| `disconnect` | `() => void` | Disconnect current wallet |
 
 ---
 
-#### useSignerSelection
+### useSendTransaction
+
+Send SOL and SPL tokens.
+
+```tsx
+import { useSendTransaction } from 'cilantro-react';
+
+function SendTransaction({ walletId, signerId }: { walletId: string; signerId: string }) {
+  const { sendSOL, sendSPL, isPending, error } = useSendTransaction(walletId, signerId, 'email');
+
+  const handleSendSOL = async () => {
+    const result = await sendSOL({
+      recipientAddress: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU',
+      amountLamports: 100000000, // 0.1 SOL
+    });
+    console.log('Transaction signature:', result.data.signature);
+  };
+
+  const handleSendSPL = async () => {
+    const result = await sendSPL({
+      mintAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+      recipientAddress: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU',
+      amount: 1000000, // 1 USDC (6 decimals)
+    });
+    console.log('Transaction signature:', result.data.signature);
+  };
 
-Wallet + signer selection state for signing flows. Uses `useWallets` and `useSigners` internally. Use inside `CilantroProvider`.
+  return (
+    <div>
+      {error && <p className="text-red-500">{error}</p>}
+      <button onClick={handleSendSOL} disabled={isPending}>
+        {isPending ? 'Sending...' : 'Send SOL'}
+      </button>
+      <button onClick={handleSendSPL} disabled={isPending}>
+        {isPending ? 'Sending...' : 'Send USDC'}
+      </button>
+    </div>
+  );
+}
+```
 
-**Options:** `UseSignerSelectionOptions`
+**Parameters:**
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `walletId` | `string \| null \| undefined` | Override wallet ID; if not set, uses `useWallets().selectedWallet?.id`. |
-| `signingMethod` | `'wallet-adapter' \| 'sdk-signer' \| null` | Current signing method (default: `'sdk-signer'`). When `'wallet-adapter'`, signer selection is ignored. |
+- `walletId: string | undefined` — Wallet to send from
+- `signerId?: string` — Signer ID (optional)
+- `signerType?: 'email' | 'phone' | 'passkey' | 'external'` — Signer type (optional)
 
-**Returns:** `UseSignerSelectionResult`
+**Returns: `UseSendTransactionResult`**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `selectedWalletId` | `string` | Effective wallet ID (override or from context). |
-| `setSelectedWalletId` | `(id: string) => void` | Set wallet ID (when not using context selection). |
-| `availableSigners` | `SignerData[]` | Signers for the selected wallet (from `useSigners`). |
-| `selectedSigner` | `SignerData \| null` | Currently selected signer. |
-| `setSelectedSigner` | `(signer: SignerData \| null) => void` | Set selected signer. |
-| `isLoadingSigners` | `boolean` | True while signers are loading. |
-| `reset` | `() => void` | Clear `selectedWalletId` and `selectedSigner`. |
-
-**SigningMethod:** `'wallet-adapter'` = use wallet adapter for signing; `'sdk-signer'` = use a Cilantro signer (email, phone, passkey, external, etc.).
+| `sendSOL` | `(params: { recipientAddress: string; amountLamports: number }) => Promise<SubmitTransactionResult>` | Send SOL |
+| `sendSPL` | `(params: { mintAddress: string; recipientAddress: string; amount: number }) => Promise<SubmitTransactionResult>` | Send SPL tokens |
+| `isPending` | `boolean` | True while sending |
+| `error` | `string \| null` | Error message if send failed |
 
 ---
 
-#### useDelegatedKeys
+### useCilantroConfig
+
+Access SDK configuration and storage adapter.
 
-Load delegated keys for a wallet (same data as DelegatedKeySelector). Use for custom delegated-key UI or logic. Use inside `CilantroProvider` (auth required).
+```tsx
+import { useCilantroConfig } from 'cilantro-react';
 
-**Options:** `UseDelegatedKeysOptions`
+function ConfigDisplay() {
+  const { config, storage } = useCilantroConfig();
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `walletId` | `string \| null \| undefined` | Wallet ID to load delegated keys for. When null/undefined, keys are empty. |
-| `filterActive` | `boolean` | When true (default), filter to active and non-expired keys only. |
+  return (
+    <div>
+      <p>API Key: {config.apiKey ? '***' : 'Not set'}</p>
+      <p>Base URL: {config.baseURL}</p>
+      <p>Storage: {storage ? 'Configured' : 'Not configured'}</p>
+    </div>
+  );
+}
+```
 
-**Returns:** `UseDelegatedKeysResult`
+**Returns: `UseCilantroConfigResult`**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `keys` | `DelegatedKeyData[]` | List of delegated keys. |
-| `isLoading` | `boolean` | True while loading. |
-| `error` | `string \| null` | Error message if load failed. |
-| `refresh` | `() => Promise<void>` | Reload delegated keys. |
-
-**Use when:** You need the list of delegated keys in custom UI or logic without using the DelegatedKeySelector component.
+| `config` | `{ apiKey?: string; baseURL?: string; jwt?: string }` | Current configuration |
+| `storage` | `DeviceKeyStorage \| null` | Storage adapter instance |
 
 ---
 
-#### useCanSign
-
-Derived "is the user ready to sign?" for disabling sign buttons or showing prompts. Use inside `CilantroProvider`.
+## Components
 
-**Options:** `UseCanSignOptions`
+### Auth Components
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `signingMethod` | `SigningMethod \| null` | Override; default `'sdk-signer'`. |
-| `requireSigner` | `boolean` | When true (default), require a selected signer for sdk-signer. |
-| `walletAdapterConnected` | `boolean` | When using wallet-adapter, pass true when the adapter is connected so `canSign*` reflects it. |
+#### LoginForm
 
-**Returns:** `UseCanSignResult`
+Username/email + password login form with loading and error states.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `hasToken` | `boolean` | True when the user has a valid token. |
-| `hasWallet` | `boolean` | True when a wallet is selected. |
-| `hasSigner` | `boolean` | True when a signer is selected (sdk-signer) or wallet-adapter is connected (when `walletAdapterConnected` is passed). |
-| `canSignMessage` | `boolean` | True when ready to sign a message. |
-| `canSignTransaction` | `boolean` | True when ready to sign/send a transaction (connection still required for send). |
+```tsx
+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"
+  renderSwitchToRegister={() => <a href="/register">Create account</a>}
+  className="max-w-sm"
+/>
+```
 
-**Use when:** You need to disable sign buttons or show "Select wallet" / "Select signer" prompts without reimplementing token/wallet/signer checks. For wallet-adapter, pass `walletAdapterConnected` from your adapter state.
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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 |
+| `rememberMe` | `boolean` | — | Show remember me option |
+| `renderSwitchToRegister` | `() => ReactNode` | — | Render link to register page |
+| `className` | `string` | — | Root element class |
+| `classNames` | `LoginFormClassNames` | — | Class names for inner elements |
 
 ---
 
-#### useMessageSigning
+#### LogoutButton
 
-Sign a message with the selected signer or wallet-adapter. Use inside `CilantroProvider`.
+Logout button with optional confirmation dialog.
 
-**Options:** `UseMessageSigningOptions`
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `token` | `string \| null` | JWT (usually from `useCilantroAuth().token`). |
-| `signingMethod` | `SigningMethod \| null` | `'sdk-signer'` or `'wallet-adapter'`. |
-| `selectedSigner` | `SignerData \| null` | Signer to use when `signingMethod === 'sdk-signer'`. |
-| `selectedWalletId` | `string` | Wallet ID when using SDK signer. |
-| `walletAdapterSignMessage` | `(message: Uint8Array) => Promise<Uint8Array>` | Optional; required when `signingMethod === 'wallet-adapter'`. |
-| `walletAdapterPublicKey` | `string \| null` | Optional; included in success detail when using wallet-adapter. |
+```tsx
+import { LogoutButton } from 'cilantro-react';
+
+<LogoutButton
+  onLogout={() => console.log('Logged out')}
+  redirectAfterLogout="/login"
+  onRedirect={(path) => router.replace(path)}
+  confirmBeforeLogout={true}
+>
+  Sign out
+</LogoutButton>
+```
 
-**Returns:** `UseMessageSigningResult`
+**Props:**
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `messageText` | `string` | Current message (default: `"Hello, Solana!"`). |
-| `setMessageText` | `(text: string) => void` | Update message. |
-| `signResultState` | `ActionState` | `{ status, message?, detail? }` – idle, loading, success, or error. |
-| `isSigning` | `boolean` | True while signing. |
-| `handleSign` | `() => Promise<void>` | Sign the current message; updates `signResultState`. |
-| `reset` | `() => void` | Reset message to default and clear result state. |
+| 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 |
 
 ---
 
-#### useTransactionSigning
+#### AuthGuard
 
-Sign and/or send a transaction. Use inside `CilantroProvider`.
+Protect content behind authentication. Shows fallback (default: LoginForm) when not authenticated.
 
-**Options:** `UseTransactionSigningOptions`
+```tsx
+import { AuthGuard, LoginForm } from 'cilantro-react';
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `token` | `string \| null` | JWT (usually from `useCilantroAuth().token`). |
-| `signingMethod` | `SigningMethod \| null` | `'sdk-signer'` or `'wallet-adapter'`. |
-| `selectedSigner` | `SignerData \| null` | Signer when `signingMethod === 'sdk-signer'`. |
-| `selectedWalletId` | `string` | Wallet ID when using SDK signer. |
-| `walletAdapterSignTransaction` | `(transaction: Transaction) => Promise<Transaction>` | Optional; required for wallet-adapter signing. |
-| `walletAdapterPublicKey` | `string \| null` | Optional; required for wallet-adapter send. |
-| `connection` | `SignAndSendConnection \| null` | **Required for sign-and-send** when using wallet-adapter or passkey. Use `adaptSolanaConnection(connection)` when you have a `@solana/web3.js` Connection; see [Connection setup](#connection-setup-solana). |
+// Basic usage - shows LoginForm when not authenticated
+<AuthGuard>
+  <ProtectedContent />
+</AuthGuard>
 
-**Returns:** `UseTransactionSigningResult`
+// Custom fallback
+<AuthGuard fallback={<CustomLoginPage />}>
+  <ProtectedContent />
+</AuthGuard>
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `transactionResultState` | `ActionState` | Result of last sign/send (idle, loading, success, error). |
-| `isSigningTransaction` | `boolean` | True while `signTransaction` is running. |
-| `isSendingTransaction` | `boolean` | True while `signAndSendTransaction` is running. |
-| `signTransaction` | `(transaction: Transaction) => Promise<void>` | Sign only (no send). Passkey signers cannot sign-only; use sign-and-send. |
-| `signAndSendTransaction` | `(transaction: Transaction) => Promise<void>` | Sign and send. Requires `connection` for wallet-adapter and passkey. |
-| `reset` | `() => void` | Set `transactionResultState` back to idle. |
+// Redirect to login page (appends ?returnUrl=currentPath for redirect-after-login)
+<AuthGuard redirectTo="/login">
+  <ProtectedContent />
+</AuthGuard>
 
-**Connection:** For passkey or wallet-adapter sign-and-send, pass a `connection` that has `getLatestBlockhash`, `sendRawTransaction`, and `confirmTransaction`. Use `adaptSolanaConnection(connection)` when you have a `@solana/web3.js` Connection; see [Connection setup](#connection-setup-solana).
+// 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>
 
-### Components (detailed)
+// Hide content when not authenticated (no fallback)
+<AuthGuard showFallback={false}>
+  <ProtectedContent />
+</AuthGuard>
 
-All components accept `className`. Many accept a `classNames` object (see TypeScript types e.g. `WalletSelectorClassNames`, `MessageSigningFormClassNames`).
+// Show skeleton while loading
+<AuthGuard useSkeleton={true}>
+  <ProtectedContent />
+</AuthGuard>
+```
 
-#### Auth components
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | Content to show when authenticated |
+| `fallback` | `ReactNode` | `<LoginForm />` | Content 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 |
+| `classNames` | `AuthGuardClassNames` | — | Class names for inner elements |
 
-| Component | Purpose | Key props |
-|-----------|---------|-----------|
-| **AuthForm** | Single form that toggles login/register. | `defaultMode?: 'login' \| 'register'`, `onSuccess?`, `onError?(error: string)`, `loginTitle`, `registerTitle`, `loginDescription`, `registerDescription`, `loginSubmitLabel`, `registerSubmitLabel`, `switchToRegisterText`, `switchToLoginText`, `isActive?`, `className`, `classNames?` (root, header, title, description, form, label, input, submitButton, toggle, toggleLink, error). |
-| **LoginForm** | Login (username/email + password). | `onSuccess?`, `onError?(error: string)`, `submitLabel`, `title`, `description`, `renderSwitchToRegister? () => ReactNode`, `className`, `classNames?`. |
-| **RegisterForm** | Registration (username, email, password). | `onSuccess?`, `onError?(error: string)`, `submitLabel`, `title`, `description`, `isActive?` (default true), `renderSwitchToLogin? () => ReactNode`, `className`, `classNames?`. |
-| **AuthGuard** | Renders children when authenticated; shows fallback otherwise. | `children`, `fallback?: ReactNode` (default: `<LoginForm />`), `showFallback?` (default true), `className`, `classNames?` (root, fallback). |
+---
 
-#### Wallet and signer components
+#### RegisterForm
 
-| Component | Purpose | Key props |
-|-----------|---------|-----------|
-| **WalletSelector** | Wallet dropdown (Shadcn Select). | `value?`, `onWalletChange?(walletId, wallet)`, `placeholder`, `className`, `classNames?` (root, trigger, content, item). Headless: `children?`, `renderTrigger?`, `renderList?`. |
-| **SignerSelector** | List/select signers (buttons). | `selectedWalletId?`, `availableSigners`, `selectedSigner`, `onSignerSelect(signer)`, `isLoadingSigners?`, `className`, `classNames?` (root, list, item, message). Headless: `children?`, `renderList?`. |
-| **SignerList** | List signers + “Add signer” (opens AddSignerForm in dialog). | `walletId`, `onSignerAdded`, `className`, `classNames`. Headless: `children`. |
-| **AddSignerForm** | Add signer (email, phone, passkey, external wallet). | `walletId`, `open?`, `onOpenChange?`, `onSuccess?`, `onCancel?`, `onError?(error)`, `asDialog?` (default true), `className`, `classNames?`. |
-| **DelegatedKeySelector** | Select delegated key for a wallet. | `walletId`, `value?`, `onChange?(keyId, key)`, `filterActive?` (default true), `placeholder`, `className`, `classNames?`. Headless: `children?` (keys, selectedKeyId, onSelect, isLoading, error, refresh). |
+Registration form with username, email, and password. Auto-login after success.
 
-#### UI primitives
+```tsx
+import { RegisterForm } from 'cilantro-react';
 
-- **Skeleton** – Shadcn-style skeleton placeholder (`rounded-md bg-muted animate-pulse`). Use for loading states or custom UI. Exported for headless use.
-- **ThemeProvider** – See [Themes](#built-in-theme-themeprovider).
+<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>}
+/>
+```
 
-#### Signing form components
+---
 
-| Component | Purpose | Key props |
-|-----------|---------|-----------|
-| **MessageSigningForm** | Message input + sign button; shows wallet/signer context. | `token?`, `selectedWalletId?`, `selectedSigner?`, `signingMethod?`, `walletAdapterSignMessage?`, `walletAdapterPublicKey?`, `showContext?`, `showCharCount?`, `className`, `classNames?`. Headless: `children?` (messageText, setMessageText, signResultState, isSigning, handleSign, reset). |
-| **TransactionSigningForm** | Sign/send transaction; pass `connection` for sign-and-send. | `token?`, `selectedWalletId?`, `selectedSigner?`, `signingMethod?`, `walletAdapterSignTransaction?`, `walletAdapterPublicKey?`, **`connection?`** (required for wallet-adapter or passkey sign-and-send), `showContext?`, `className`, `classNames?`. Headless: `children?` (transactionResultState, isSigningTransaction, isSendingTransaction, signTransaction, signAndSendTransaction, reset). |
+#### AuthShell
 
-When token/wallet/signer/signingMethod are omitted, MessageSigningForm and TransactionSigningForm use `useCilantroAuth().token` and `useSignerSelection()` internally.
+Full-page centered layout for auth screens. Use for standalone login/register pages.
 
-### Types (detailed)
+```tsx
+import { AuthShell, LoginForm } from 'cilantro-react';
 
-#### ActionState
+<AuthShell logo={<img src="/logo.svg" alt="App" />} maxWidth="sm">
+  <LoginForm redirectAfterSuccess="/dashboard" />
+</AuthShell>
+```
 
-Used by signing hooks and forms for result state.
+---
 
-```ts
-type ActionState<T = unknown> = {
-  status: 'idle' | 'loading' | 'success' | 'error';
-  message?: string;
-  detail?: T;
-};
+#### 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>
 ```
 
-- **idle** – No operation yet.
-- **loading** – Sign/send in progress.
-- **success** – Done; `message` and optional `detail` (e.g. signature, explorer URL).
-- **error** – Failed; `message` (and optional `detail`).
+---
 
-#### User
+### Wallet Components
 
-From `useCilantroAuth().user`:
+#### WalletSelector
 
-```ts
-interface User {
-  username?: string;
-  email?: string;
-  userType?: string;
-}
-```
+Dropdown to select from available wallets.
 
-#### WalletData
+```tsx
+import { WalletSelector } from 'cilantro-react';
 
-From `useWallets().wallets` / `selectedWallet`:
+// Controlled
+const [walletId, setWalletId] = useState('');
+<WalletSelector value={walletId} onChange={setWalletId} />
 
-```ts
-interface WalletData {
-  id: string;
-  walletId: string;
-  walletName?: string;
-  address?: string;
-  walletAddress?: string;
-  chain?: string;
-  active?: boolean;
-  [key: string]: unknown;
-}
+// With callback
+<WalletSelector
+  onWalletChange={(id, wallet) => console.log('Selected:', wallet?.walletName)}
+  placeholder="Choose a wallet"
+/>
+
+// Headless (custom rendering)
+<WalletSelector>
+  {({ wallets, selectedWallet, selectWallet, isLoading }) => (
+    <div>
+      {wallets.map((w) => (
+        <button key={w.id} onClick={() => selectWallet(w.id)}>
+          {w.walletName}
+        </button>
+      ))}
+    </div>
+  )}
+</WalletSelector>
 ```
 
-#### SignerData
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Controlled wallet ID |
+| `onChange` | `(walletId: string) => void` | — | Called when wallet changes |
+| `onWalletChange` | `(walletId: string, wallet: WalletData \| null) => void` | — | Called with wallet object |
+| `placeholder` | `string` | `"Select a wallet"` | Placeholder text |
+| `useSkeleton` | `boolean` | `true` | Show skeleton while loading |
+| `className` | `string` | — | Root element class |
+| `classNames` | `WalletSelectorClassNames` | — | Class names for inner elements |
+| `children` | `(props) => ReactNode` | — | Headless render function |
+| `renderTrigger` | `(props) => ReactNode` | — | Custom trigger render |
+| `renderList` | `(props) => ReactNode` | — | Custom list render |
+
+---
 
-From `useSigners().signers` or `useSignerSelection().availableSigners` / `selectedSigner`. Used by SignerSelector, MessageSigningForm, TransactionSigningForm. Contains at least: `id`, `signerId`, `type` or `signerType`, `walletId`, `publicKey` / `signerPubkey`, and optional `email`, `phone`, `isActive`, `signerConfig`, etc. See TypeScript type `SignerData` for full shape.
+#### CreateWalletForm
 
-#### SignAndSendConnection / adaptSolanaConnection
+Form to create a new wallet.
+
+```tsx
+import { CreateWalletForm } from 'cilantro-react';
 
-Type for the `connection` prop when using sign-and-send (passkey or wallet-adapter). Must have:
+<CreateWalletForm
+  onCreated={(result) => console.log('Created wallet:', result.data.id)}
+  onError={(err) => console.error(err.message)}
+  userId="optional-user-id"
+/>
+```
 
-- `sendRawTransaction(buf: Buffer)` → `Promise<string>`
-- `getLatestBlockhash()` → `Promise<{ blockhash, lastValidBlockHeight }>`
-- `confirmTransaction(opts: { signature, blockhash, lastValidBlockHeight })` → `Promise<void>`
+**Props:**
 
-If you use `@solana/web3.js`, call `adaptSolanaConnection(connection)` and pass the result; see [Connection setup](#connection-setup-solana).
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `userId` | `string` | — | Optional user ID to associate wallet with |
+| `onCreated` | `(wallet: WalletControllerCreateResult) => void` | — | Called after wallet is created |
+| `onError` | `(error: Error) => void` | — | Called on error |
+| `className` | `string` | — | Form class |
 
-#### Other types
+---
 
-- **ErrorResponse** – `{ message?, error?, code?, status?, statusText?, data?, ... }` for API error shapes.
-- **ApiResponse\<T\>** – SDK response shape; use `extractResponseData(response)` to unwrap.
-- **DelegatedKeyData** – From DelegatedKeySelector: `id`, `walletId`, `name?`, `publicKey`, `permissions`, `isActive?`, `createdAt?`, `expiresAt?`, etc.
-- **SigningMethod** – `'wallet-adapter' | 'sdk-signer'`.
-- **AddSignerType** – `'email' | 'phone' | 'passkey' | 'external'`.
-- **AuthFormMode** – `'login' | 'register'`.
+#### WalletAddress
 
-#### Utilities
+Display a wallet address with copy functionality.
 
-- **extractErrorMessage(error: unknown): string** – Returns a string from any thrown value (Error.message, object.message, response.data.message, etc.). Use in catch blocks when calling auth, signer, or SDK methods.
-- **extractResponseData\<T\>(response: unknown): T | null** – Unwraps SDK response shapes (`{ data }`, `{ success, data }`, signer arrays). Use after cilantro-sdk calls that return wrapped payloads.
+```tsx
+import { WalletAddress } from 'cilantro-react';
 
----
+<WalletAddress
+  address="7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
+  short={true}
+  copyable={true}
+/>
+```
+
+**Props:**
 
-## Examples
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `address` | `string` | — | Wallet address to display |
+| `short` | `boolean` | `false` | Truncate address for display |
+| `copyable` | `boolean` | `false` | Show copy button |
+| `className` | `string` | — | Element class |
+
+---
 
-### Auth – single form (AuthForm)
+#### WalletBalance
 
-One form that switches between sign-in and create-account:
+Display wallet SOL and token balances.
 
 ```tsx
-import { AuthForm } from 'cilantro-react'
+import { WalletBalance } from 'cilantro-react';
 
-function LoginPage() {
-  return (
-    <AuthForm
-      defaultMode="login"
-      onSuccess={() => window.location.href = '/dashboard'}
-      onError={(err) => console.error(err)}
-      loginTitle="Welcome back"
-      registerTitle="Create an account"
-      switchToRegisterText="Don't have an account? Create one"
-      switchToLoginText="Already have an account? Sign in"
-    />
-  )
-}
+<WalletBalance walletId={walletId} showTokens={true} />
 ```
 
-### Auth – separate Login and Register
+**Props:**
 
-Use `LoginForm` and `RegisterForm` with links to switch pages:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet ID to show balance for |
+| `showTokens` | `boolean` | `false` | Show SPL token balances |
+| `className` | `string` | — | Element class |
 
-```tsx
-import { LoginForm, RegisterForm } from 'cilantro-react'
-import { Link } from 'react-router-dom'
+---
 
-function LoginPage() {
-  return (
-    <LoginForm
-      onSuccess={() => navigate('/dashboard')}
-      renderSwitchToRegister={() => (
-        <Link to="/register">Create account</Link>
-      )}
-    />
-  )
-}
+#### ConnectWalletButton
 
-function RegisterPage() {
-  return (
-    <RegisterForm
-      onSuccess={() => navigate('/dashboard')}
-      renderSwitchToLogin={() => (
-        <Link to="/login">Already have an account? Sign in</Link>
-      )}
-    />
-  )
-}
+Connect to external Solana wallets (Phantom, Solflare).
+
+```tsx
+import { ConnectWalletButton } from 'cilantro-react';
+
+<ConnectWalletButton
+  onConnect={(publicKey, wallet) => console.log('Connected:', publicKey)}
+  onDisconnect={() => console.log('Disconnected')}
+>
+  Connect External Wallet
+</ConnectWalletButton>
 ```
 
-### Auth – protected route (AuthGuard)
+**Props:**
 
-Show login when not authenticated, otherwise render children:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onConnect` | `(publicKey: string, wallet: SolanaWallet) => void` | — | Called when connected |
+| `onDisconnect` | `() => void` | — | Called when disconnected |
+| `className` | `string` | — | Button class |
+| `children` | `ReactNode` | `"Connect Wallet"` | Button content |
+
+---
+
+### Signer Components
+
+#### SignerSelector
+
+Select a signer from the wallet's signers.
 
 ```tsx
-import { AuthGuard, LoginForm } from 'cilantro-react'
+import { SignerSelector } from 'cilantro-react';
 
-function DashboardRoute() {
-  return (
-    <AuthGuard fallback={<LoginForm />}>
-      <Dashboard />
-    </AuthGuard>
-  )
-}
+const [signerId, setSignerId] = useState('');
+const [signerType, setSignerType] = useState<'email' | 'phone'>('email');
 
-// Or use default fallback (LoginForm)
-<AuthGuard>
-  <Dashboard />
-</AuthGuard>
+<SignerSelector
+  walletId={walletId}
+  value={signerId}
+  onChange={(id, type) => {
+    setSignerId(id);
+    setSignerType(type);
+  }}
+/>
 
-// Hide content when unauthenticated (no fallback UI)
-<AuthGuard showFallback={false}>
-  <Dashboard />
-</AuthGuard>
+// Headless
+<SignerSelector walletId={walletId} onChange={handleChange}>
+  {({ signers, selectedSigner, onSignerSelect, isLoading }) => (
+    <div>
+      {signers.map((s) => (
+        <button key={s.id} onClick={() => onSignerSelect(s)}>
+          {s.email || s.phone}
+        </button>
+      ))}
+    </div>
+  )}
+</SignerSelector>
 ```
 
-### Wallets
+**Props:**
 
-Wallet dropdown with optional customization:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet ID to load signers for |
+| `value` | `string` | — | Selected signer ID |
+| `onChange` | `(signerId: string, signerType: SignerType) => void` | — | Called when signer changes |
+| `useSkeleton` | `boolean` | `true` | Show skeleton while loading |
+| `className` | `string` | — | Root element class |
+| `classNames` | `SignerSelectorClassNames` | — | Class names for inner elements |
+| `children` | `(props) => ReactNode` | — | Headless render function |
+| `renderList` | `(props) => ReactNode` | — | Custom list render |
+
+---
+
+#### SignerList
+
+List signers with "Add signer" dialog (includes email, phone, passkey forms).
 
 ```tsx
-import { useWallets, WalletSelector } from 'cilantro-react'
+import { SignerList } from 'cilantro-react';
 
-function Wallets() {
-  const { wallets, selectedWallet } = useWallets()
+<SignerList
+  walletId={walletId}
+  onSignerAdded={() => console.log('Signer added')}
+  onRevoke={(signerId) => console.log('Revoked:', signerId)}
+/>
 
-  return (
+// Headless
+<SignerList walletId={walletId}>
+  {({ signers, isLoading, openAddSigner }) => (
     <div>
-      <WalletSelector
-        placeholder="Choose a wallet"
-        onWalletChange={(id, wallet) => console.log('Selected', id, wallet)}
-        classNames={{
-          root: 'w-full max-w-xs',
-          trigger: 'border-2',
-        }}
-      />
-      {selectedWallet && (
-        <p>Selected: {selectedWallet.walletName ?? selectedWallet.id}</p>
-      )}
+      {signers.map((s) => <div key={s.id}>{s.email}</div>)}
+      <button onClick={openAddSigner}>Add Signer</button>
     </div>
-  )
-}
+  )}
+</SignerList>
 ```
 
-### Signers – list and select
+**Props:**
 
-Load signers for the selected wallet and let the user pick one:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet ID |
+| `onSignerAdded` | `() => void` | — | Called after signer is added |
+| `onRevoke` | `(signerId: string) => void` | — | Called when signer is revoked |
+| `useSkeleton` | `boolean` | `true` | Show skeleton while loading |
+| `className` | `string` | — | Root element class |
+| `classNames` | `SignerListClassNames` | — | Class names for inner elements |
+| `children` | `(props) => ReactNode` | — | Headless render function |
 
-```tsx
-import { useSigners, useSignerSelection, SignerSelector } from 'cilantro-react'
+---
 
-function SignerPick() {
-  const { walletId } = useSignerSelection({ walletId: selectedWalletId })
-  const { signers, isLoading, refresh } = useSigners({ walletId: walletId ?? undefined })
+#### CreateEmailSignerForm
 
-  return (
-    <SignerSelector
-      selectedWalletId={walletId ?? undefined}
-      availableSigners={signers}
-      selectedSigner={selectedSigner}
-      onSignerSelect={setSelectedSigner}
-      isLoadingSigners={isLoading}
-      className="w-full"
-    />
-  )
-}
+Form to create an email signer.
+
+```tsx
+import { CreateEmailSignerForm } from 'cilantro-react';
+
+<CreateEmailSignerForm
+  walletId={walletId}
+  onCreated={(signer) => console.log('Created:', signer.signerId)}
+  onError={(err) => console.error(err.message)}
+/>
 ```
 
-Headless: use `children` or `renderList` to render the list yourself.
+**Props:**
 
-### Signers – add signer (AddSignerForm + SignerList)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet ID |
+| `onCreated` | `(signer: SignerInfo) => void` | — | Called after signer is created |
+| `onError` | `(error: Error) => void` | — | Called on error |
+| `className` | `string` | — | Form class |
 
-List signers and open a dialog to add a new one (email, phone, passkey, external wallet):
+---
+
+#### CreatePhoneSignerForm
+
+Form to create a phone signer.
 
 ```tsx
-import { SignerList } from 'cilantro-react'
+import { CreatePhoneSignerForm } from 'cilantro-react';
 
-function SignersPage() {
-  const walletId = 'your-wallet-id'
+<CreatePhoneSignerForm
+  walletId={walletId}
+  onCreated={(signer) => console.log('Created:', signer.signerId)}
+  onError={(err) => console.error(err.message)}
+/>
+```
 
-  return (
-    <SignerList
-      walletId={walletId}
-      onSignerAdded={() => console.log('Signer added')}
-    />
-  )
-}
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet ID |
+| `onCreated` | `(signer: SignerInfo) => void` | — | Called after signer is created |
+| `onError` | `(error: Error) => void` | — | Called on error |
+| `className` | `string` | — | Form class |
+
+---
+
+#### AddPasskeyButton
+
+Button to register a passkey signer. Only renders if WebAuthn is supported.
+
+```tsx
+import { AddPasskeyButton } from 'cilantro-react';
+
+<AddPasskeyButton
+  walletId={walletId}
+  onRegistered={(signer) => console.log('Registered:', signer.signerId)}
+  onError={(err) => console.error(err.message)}
+>
+  Add Passkey
+</AddPasskeyButton>
 ```
 
-AddSignerForm can also be used standalone (e.g. inline or in your own dialog):
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet ID |
+| `onRegistered` | `(signer: SignerInfo) => void` | — | Called after passkey is registered |
+| `onError` | `(error: Error) => void` | — | Called on error |
+| `className` | `string` | — | Container class |
+| `children` | `ReactNode` | `"Add Passkey"` | Button content |
+
+---
+
+### Transaction Components
+
+#### SendSOLForm
+
+Form to send SOL.
 
 ```tsx
-import { AddSignerForm } from 'cilantro-react'
+import { SendSOLForm } from 'cilantro-react';
 
-<AddSignerForm
+<SendSOLForm
   walletId={walletId}
-  open={dialogOpen}
-  onOpenChange={setDialogOpen}
-  onSuccess={() => { refreshSigners(); setDialogOpen(false) }}
-  asDialog={true}
+  signerId={signerId}
+  signerType="email"
+  onSuccess={(result) => console.log('Sent! Signature:', result.data.signature)}
+  onError={(err) => console.error(err.message)}
 />
 ```
 
-### Delegated keys
+**Props:**
 
-Select a delegated key for a wallet:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet to send from |
+| `signerId` | `string` | — | Signer ID to authorize transaction |
+| `signerType` | `'email' \| 'phone' \| 'passkey' \| 'external'` | — | Signer type |
+| `onSuccess` | `(result: SubmitTransactionResult) => void` | — | Called after successful send |
+| `onError` | `(error: Error) => void` | — | Called on error |
+| `className` | `string` | — | Form class |
 
-```tsx
-import { DelegatedKeySelector } from 'cilantro-react'
+---
 
-function DelegatedKeys() {
-  const [keyId, setKeyId] = useState<string>('')
+#### SendSPLForm
 
-  return (
-    <DelegatedKeySelector
-      walletId={walletId}
-      value={keyId}
-      onChange={(id, key) => setKeyId(id)}
-      placeholder="Select a delegated key"
-      filterActive={true}
-    />
-  )
-}
+Form to send SPL tokens.
+
+```tsx
+import { SendSPLForm } from 'cilantro-react';
+
+<SendSPLForm
+  walletId={walletId}
+  signerId={signerId}
+  signerType="email"
+  mintAddress="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC
+  onSuccess={(result) => console.log('Sent! Signature:', result.data.signature)}
+  onError={(err) => console.error(err.message)}
+/>
 ```
 
-Use `children` for full control over the list UI.
+**Props:**
 
-### Message signing
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet to send from |
+| `signerId` | `string` | — | Signer ID |
+| `signerType` | `SignerType` | — | Signer type |
+| `mintAddress` | `string` | — | Pre-fill token mint address |
+| `onSuccess` | `(result: SubmitTransactionResult) => void` | — | Called after successful send |
+| `onError` | `(error: Error) => void` | — | Called on error |
+| `className` | `string` | — | Form class |
 
-Default UI with message textarea, sign button, and wallet/signer context:
+---
+
+#### TransactionStatus
+
+Display transaction status with explorer link.
 
 ```tsx
-import { MessageSigningForm } from 'cilantro-react'
+import { TransactionStatus } from 'cilantro-react';
 
-function SignMessage() {
-  return (
-    <MessageSigningForm
-      showContext={true}
-      showCharCount={true}
-    />
-  )
-}
+<TransactionStatus
+  signature="5wHu1qwD7q9..."
+  cluster="mainnet-beta"
+/>
 ```
 
-Headless: use `children` to get `messageText`, `setMessageText`, `handleSign`, `signResultState`, `isSigning`, `reset`:
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `signature` | `string` | — | Transaction signature |
+| `cluster` | `'mainnet-beta' \| 'devnet' \| 'testnet'` | `'mainnet-beta'` | Solana cluster |
+| `className` | `string` | — | Element class |
+
+---
+
+#### TransactionHistory
+
+Paginated list of recent transactions.
 
 ```tsx
-<MessageSigningForm>
-  {({ messageText, setMessageText, handleSign, signResultState, isSigning, reset }) => (
-    <div>
-      <textarea value={messageText} onChange={e => setMessageText(e.target.value)} />
-      <button onClick={handleSign} disabled={isSigning}>Sign</button>
-      {signResultState.status !== 'idle' && <p>{signResultState.message}</p>}
-      <button onClick={reset}>Clear</button>
-    </div>
-  )}
-</MessageSigningForm>
+import { TransactionHistory } from 'cilantro-react';
+
+<TransactionHistory walletId={walletId} pageSize={10} />
 ```
 
-### Transaction signing
+**Props:**
 
-Build a transaction in your app, then call `signTransaction(tx)` to sign only, or `signAndSendTransaction(tx)` to sign and send. **For wallet-adapter or passkey sign-and-send, pass `connection`** from your Solana config (e.g. `@solana/web3.js`):
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `walletId` | `string` | — | Wallet ID |
+| `pageSize` | `number` | `10` | Transactions per page |
+| `className` | `string` | — | Element class |
 
-```tsx
-import { Connection } from '@solana/web3.js'
-import { TransactionSigningForm } from 'cilantro-react'
+---
 
-function SendTx() {
-  const connection = new Connection('https://api.devnet.solana.com')
+### Layout Components
 
-  return (
-    <TransactionSigningForm
-      connection={connection}
-      showContext={true}
-    >
-      {({ signTransaction, signAndSendTransaction, transactionResultState, isSigningTransaction, isSendingTransaction, reset }) => (
-        <div>
-          <button
-            onClick={() => {
-              const tx = buildMyTransaction() // your code
-              signAndSendTransaction(tx)
-            }}
-            disabled={isSendingTransaction}
-          >
-            {isSendingTransaction ? 'Sending...' : 'Sign and send'}
-          </button>
-          {transactionResultState.status !== 'idle' && (
-            <p>{transactionResultState.message}</p>
-          )}
-          <button onClick={reset}>Reset status</button>
-        </div>
-      )}
-    </TransactionSigningForm>
-  )
-}
-```
+#### CilantroConnect
+
+All-in-one connect component combining wallet, signers, and auth.
 
-If you use passkey or wallet-adapter for sign-and-send, **connection is required**; otherwise the library will throw. The library does not create a Solana connection—you pass it in.
+```tsx
+import { CilantroConnect } from 'cilantro-react';
 
-### Full flow example
+<CilantroConnect
+  onConnect={(wallet, signers) => console.log('Connected:', wallet, signers)}
+  onDisconnect={() => console.log('Disconnected')}
+/>
+```
 
-Typical app flow:
+**Props:**
 
-1. Wrap app with `CilantroProvider` (see [Setup](#setup)).
-2. **Auth:** Use `AuthForm` on a login page, or `AuthGuard` around protected routes with `LoginForm` as fallback.
-3. **Wallets:** Use `WalletSelector` so the user picks a wallet; get `selectedWallet` from `useWallets()`.
-4. **Signers:** Use `SignerSelector` with `useSigners({ walletId })` and `useSignerSelection`, or use `SignerList` to list + add signers.
-5. **Message signing:** Use `MessageSigningForm` (optionally with `showContext` and `showCharCount`).
-6. **Transaction signing:** Use `TransactionSigningForm` with your `connection` and build the transaction in your app; call `signTransaction(tx)` or `signAndSendTransaction(tx)` from the render props.
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onConnect` | `(wallet: WalletInfo, signers: SignerInfo[]) => void` | — | Called when connected |
+| `onDisconnect` | `() => void` | — | Called when disconnected |
+| `className` | `string` | — | Element class |
 
 ---
 
-## Customization
+#### LoadingOverlay
 
-- **className** – All components accept `className` on the root element. Apply your own Tailwind or CSS.
-- **classNames** – Many components accept a `classNames` object to style inner parts (e.g. `root`, `trigger`, `input`, `button`, `label`). See TypeScript types: `WalletSelectorClassNames`, `SignerSelectorClassNames`, `MessageSigningFormClassNames`, `TransactionSigningFormClassNames`, `LoginFormClassNames`, `AuthFormClassNames`, etc.
-- **Headless** – Where supported, use `children` render props or `renderList` / `renderTrigger` to render the UI yourself and still use the component’s logic (e.g. `WalletSelector`, `SignerSelector`, `MessageSigningForm`, `TransactionSigningForm`, `SignerList`, `DelegatedKeySelector`).
+Overlay with loading spinner for async operations.
 
----
+```tsx
+import { LoadingOverlay } from 'cilantro-react';
 
-## Core types and utilities
+<LoadingOverlay isLoading={isPending} message="Sending transaction...">
+  <MyContent />
+</LoadingOverlay>
+```
 
-- **ActionState** – `{ status: 'idle' | 'loading' | 'success' | 'error', message?: string, detail?: unknown }`. Returned by signing hooks and used in signing form result UI. See [Types (detailed)](#types-detailed) for full shape.
-- **extractErrorMessage(error: unknown): string** – Normalizes unknown errors to a string. Handles `Error`, `{ message }`, `{ response: { data } }`, etc. Use when catching SDK or API errors to show a consistent message.
-- **extractResponseData\<T\>(response: unknown): T | null** – Extracts the data payload from SDK API responses. Handles `{ data }`, `{ success, data }`, and signer list shapes. Use when you need to unwrap the response shape (e.g. after calling cilantro-sdk).
-- **SignAndSendConnection** – Type for the `connection` prop when using sign-and-send. Your `Connection` from `@solana/web3.js` is compatible. Must provide `getLatestBlockhash`, `confirmTransaction`, and (for wallet-adapter send) `sendRawTransaction`.
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isLoading` | `boolean` | — | Show overlay when true |
+| `message` | `string` | — | Loading message |
+| `children` | `ReactNode` | — | Content to wrap |
+| `className` | `string` | — | Overlay class |
 
 ---
 
-## Advanced / low-level
+#### ErrorBoundary
 
-**Signer signing (without React hooks):** For advanced usage you can call the core signer APIs directly:
+Error boundary with retry functionality.
 
-- `signMessageWithSigner(walletId, signer, message)` – Sign a message with a given signer.
-- `signTransactionWithSigner(walletId, signer, transactionBuffer)` – Sign a transaction (no send).
-- `signAndSendTransactionWithSigner(walletId, signer, transaction, connection?)` – Sign and send; **connection is required for passkey**.
-- `getWalletData(walletId)`, `getSignerPublicKey(...)` – Helpers for wallet/signer data.
-- `SIGNER_TYPES`, `SignerType` – Signer type constants.
+```tsx
+import { ErrorBoundary } from 'cilantro-react';
 
-See TypeScript types and [cilantro-sdk](https://www.npmjs.com/package/cilantro-sdk) for full behavior.
+<ErrorBoundary
+  fallback={<div>Something went wrong</div>}
+  onRetry={() => window.location.reload()}
+>
+  <App />
+</ErrorBoundary>
+```
+
+**Props:**
 
-**Connection:** The library never creates a Solana RPC connection. Your app creates it (e.g. `new Connection(rpcUrl)`) and passes it into `useTransactionSigning` or `TransactionSigningForm` when using wallet-adapter or passkey sign-and-send.
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fallback` | `ReactNode` | — | Content to show on error |
+| `onRetry` | `() => void` | — | Retry callback |
+| `children` | `ReactNode` | — | Content to wrap |
 
 ---
 
 ## Theming
 
-Components use Shadcn-style class names and CSS variables (e.g. `border-input`, `bg-primary`, `text-muted-foreground`). Ensure your app has **Tailwind CSS** so utility classes work; the library does not bundle Tailwind.
+Components use Shadcn-style class names and CSS variables. Ensure your app has **Tailwind CSS** configured.
 
-### Built-in theme (ThemeProvider)
-
-You can opt into a built-in light/dark theme without bringing your own Shadcn setup. Wrap your app (or just the Cilantro UI) with `ThemeProvider`:
+### Built-in Theme (ThemeProvider)
 
 ```tsx
-import { ThemeProvider } from 'cilantro-react'
-
-<ThemeProvider theme="system" defaultTheme="dark" className="min-h-screen">
-  <CilantroProvider platformApiKey="...">
-    {children}
+import { ThemeProvider } from 'cilantro-react';
+
+<ThemeProvider
+  theme="system"
+  defaultTheme="dark"
+  injectStyles={true}
+  className="min-h-screen"
+>
+  <CilantroProvider apiKey="...">
+    <App />
   </CilantroProvider>
 </ThemeProvider>
 ```
 
-- **theme** – `"light"` | `"dark"` | `"system"`. `"system"` follows `prefers-color-scheme`.
-- **defaultTheme** – Initial theme when using `"system"` (default: `"dark"`).
-- **storageKey** – Optional localStorage key to persist the resolved theme when using `"system"`.
-- **injectStyles** – When `true` (default), the provider injects a minimal set of CSS variables (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--input`, `--ring`, etc.) for light and `[data-theme="dark"]`. You can set `injectStyles={false}` and import the theme file yourself: `import 'cilantro-react/themes/default.css'`.
+**Props:**
 
-Tailwind is still required so utility classes apply; ThemeProvider only sets the variables.
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Theme mode |
+| `defaultTheme` | `'light' \| 'dark'` | `'dark'` | Default when using system |
+| `storageKey` | `string` | — | localStorage key for persistence |
+| `injectStyles` | `boolean` | `true` | Inject CSS variables |
+| `className` | `string` | — | Wrapper class |
 
-For full Shadcn theming, see [Theming - shadcn/ui](https://ui.shadcn.com/docs/theming).
+### Import Theme CSS Directly
+
+```ts
+import 'cilantro-react/themes/default.css';
+```
 
 ---
 
-## Accessibility
+## Advanced Usage
 
-Components are built with screen readers and keyboard use in mind:
+### Low-Level Signer Signing
 
-- **Live regions** – Signing result messages (MessageSigningForm, TransactionSigningForm) use `role="status"` and `aria-live="polite"` (or `assertive` for errors). Loading states use `aria-busy`.
-- **Form labels** – Auth, login, register, message signing, and add-signer forms use visible labels with correct `id` / `htmlFor`. Error blocks use `role="alert"` so errors are announced immediately.
-- **Selects and dialogs** – WalletSelector and DelegatedKeySelector triggers have `aria-label`. Radix Dialog handles focus trap and restore in AddSignerForm.
-- **Loading** – WalletSelector, SignerSelector, SignerList, DelegatedKeySelector, and AuthGuard use `aria-busy` and `aria-live="polite"` when loading so screen readers announce loading state.
+For advanced use cases without React hooks:
 
-Buttons use `focus-visible:ring-2` for focus indication; icon-only or custom buttons can receive `aria-label` via standard HTML attributes.
+```tsx
+import {
+  signMessageWithSigner,
+  signTransactionWithSigner,
+  signAndSendTransactionWithSigner,
+  getWalletData,
+  getSignerPublicKey,
+  SIGNER_TYPES,
+} from 'cilantro-react';
+
+// Sign a message
+const result = await signMessageWithSigner(walletId, signer, 'Hello, Solana!');
+
+// Sign and send a transaction
+const txResult = await signAndSendTransactionWithSigner(walletId, signer, transaction, connection);
+```
 
----
+### Solana Connection Adapter
+
+For `@solana/web3.js` connection compatibility:
 
-## Mobile
+```tsx
+import { Connection } from '@solana/web3.js';
+import { adaptSolanaConnection } from 'cilantro-react';
+
+const connection = new Connection('https://api.mainnet-beta.solana.com');
+const adapted = adaptSolanaConnection(connection);
+```
 
-Key actions use touch-friendly targets and dialogs are responsive:
+### Utilities
 
-- **Touch targets** – The Button component has a `touch` size (`min-h-[44px] min-w-[44px]`) used on primary actions: AuthForm/LoginForm/RegisterForm submit, MessageSigningForm sign button, and SignerList “Add signer”. Use `size="touch"` on your own primary buttons when needed.
-- **Responsive layout** – Auth forms use `w-full max-w-sm`. MessageSigningForm and TransactionSigningForm use responsive button groups (`flex-col` on small screens). Result blocks use `overflow-auto` on `<pre>` so content doesn’t overflow.
-- **Dialog** – DialogContent has `max-h-[100dvh] sm:max-h-[90vh]` and `overflow-y-auto` so dialogs (e.g. AddSignerForm) are scrollable on small screens. You can add `className="rounded-none sm:rounded-lg"` or full-height classes for a more mobile-friendly dialog.
+| Function | Description |
+|----------|-------------|
+| `extractErrorMessage(error)` | Normalize unknown errors to string |
+| `extractResponseData(response)` | Unwrap SDK response shapes |
+| `normalizeWallet(dto)` | Normalize wallet data from SDK (ensures `id` and `address`) |
+| `normalizeSigner(dto)` | Normalize signer data from SDK |
+| `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.
 
 ---
 
-## Loading states
+## Types
 
-Loading is shown with skeleton placeholders where it improves perceived performance:
+Key exported types:
 
-- **Skeleton** – A `Skeleton` UI primitive is available (`import { Skeleton } from 'cilantro-react'`). Components use it when loading: WalletSelector and DelegatedKeySelector show a skeleton trigger; SignerSelector and SignerList show 2–3 skeleton rows.
-- **useSkeleton** – WalletSelector, SignerSelector, SignerList, and DelegatedKeySelector accept an optional **useSkeleton** prop (default: `true`). Set `useSkeleton={false}` to show plain “Loading…” text instead.
-- **classNames** – These components support `classNames.skeleton` and `classNames.loading` so you can style the skeleton or the loading container.
-- **AuthGuard** – Optional skeleton while checking auth: set **useSkeleton={true}** to show a small skeleton card instead of “Loading…” text.
+```ts
+import type {
+  // Config
+  CilantroConfig,
+  CilantroContextValue,
+  DeviceKeyStorage,
+
+  // User/Auth
+  User,
+  UseAuthResult,
+
+  // Wallet
+  WalletData,
+  UseWalletResult,
+  WalletControllerCreateResult,
+
+  // Signer
+  SignerData,
+  SignerInfo,
+  SignerType,
+  UseSignersResult,
+
+  // Transaction
+  SubmitTransactionResult,
+  UseSendTransactionResult,
+
+  // External Wallet
+  SolanaWallet,
+  UseExternalWalletResult,
+
+  // Passkey
+  UsePasskeyResult,
+
+  // UI
+  ActionState,
+} from 'cilantro-react';
+```
 
 ---
 
-## Low-level SDK
+## License
 
-For direct cilantro-sdk usage (auth, storage, wallets, signers, delegated keys, message/transaction signing), see the [cilantro-sdk](https://www.npmjs.com/package/cilantro-sdk) package.
+MIT