cilantro-react 0.1.0

package/README.md

@@ -0,0 +1,647 @@
+# cilantro-react
+
+React SDK/UI for [Cilantro Smart Wallet](https://www.npmjs.com/package/cilantro-sdk). Provides providers, hooks, and UI components so you can add auth, wallets, signers, and signing flows without wiring the low-level SDK directly. Components use [Shadcn/UI](https://ui.shadcn.com)-style primitives and are customizable via `className` and `classNames`.
+
+## Install
+
+```bash
+npm install cilantro-react cilantro-sdk react
+```
+
+**Peer dependencies:** `react` (^18.0.0 || ^19.0.0), `cilantro-sdk` (^0.0.40). For transaction signing and Solana helpers, optionally install `@solana/web3.js` (^1.98.0).
+
+**Styling:** Components use Tailwind CSS and Shadcn-compatible class names. Ensure your app has [Tailwind CSS](https://tailwindcss.com) configured; for theming, use your own Shadcn theme or CSS variables so styles apply correctly.
+
+## Polyfills
+
+Import the SDK polyfills once before any SDK usage (e.g. in your app entry or root layout):
+
+```ts
+import 'cilantro-sdk/polyfills'
+```
+
+## Setup
+
+Wrap your app with `CilantroProvider` and pass your platform API key:
+
+```tsx
+import { CilantroProvider } from 'cilantro-react'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <CilantroProvider platformApiKey="your-platform-api-key">
+      {children}
+    </CilantroProvider>
+  )
+}
+```
+
+**CilantroProvider props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `platformApiKey` | `string` | **Required.** Your Cilantro platform API key. |
+| `apiUrl` | `string` | Optional API base URL. |
+| `jwtStorageKey` | `string` | localStorage key for JWT (default: `cilantro_jwt`). |
+| `walletStorageKey` | `string` | localStorage key for selected wallet id (default: `cilantro_selected_wallet_id`). |
+| `onLoginSuccess` | `() => void` | Callback after successful login. |
+| `onLogout` | `() => void` | Callback after logout. |
+| `onRegisterSuccess` | `() => void` | Callback after successful registration. |
+
+**Connection:** The library does not create a Solana RPC connection. For transaction sign-and-send (wallet-adapter or passkey), pass your own `connection` from `@solana/web3.js` (or your Solana config) into `useTransactionSigning` / `TransactionSigningForm`. See [Transaction signing](#transaction-signing) below.
+
+---
+
+## API reference
+
+### Providers
+
+- **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`.
+
+**CilantroAuthProvider props:** `platformApiKey` (required), `apiUrl`, `jwtStorageKey`, `onLoginSuccess`, `onLogout`, `onRegisterSuccess`.
+
+**WalletProvider props:** `storageKey` (default: `cilantro_selected_wallet_id`).
+
+---
+
+### Custom hooks (detailed)
+
+All hooks must be used within the appropriate provider (see each hook below).
+
+#### useCilantroAuth
+
+Auth state and actions. Use inside `CilantroAuthProvider` or `CilantroProvider`.
+
+**Returns:** `CilantroAuthContextType`
+
+| 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. |
+
+---
+
+#### useWallets
+
+Wallet list and selection. Use inside `CilantroProvider` (which includes `WalletProvider`).
+
+**Returns:** `WalletContextType`
+
+| 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. |
+
+**WalletData:** `{ id, walletId, walletName?, address?, walletAddress?, chain?, active?, ... }`.
+
+---
+
+#### useSigners
+
+Load signers for a wallet. Use inside `CilantroProvider` (auth required).
+
+**Options:** `UseSignersOptions`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `walletId` | `string \| null \| undefined` | Wallet ID to load signers for. If omitted, you can pass it from `useWallets().selectedWallet?.id`. |
+
+**Returns:** `UseSignersResult`
+
+| 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.
+
+---
+
+#### useSignerSelection
+
+Wallet + signer selection state for signing flows. Uses `useWallets` and `useSigners` internally. Use inside `CilantroProvider`.
+
+**Options:** `UseSignerSelectionOptions`
+
+| 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. |
+
+**Returns:** `UseSignerSelectionResult`
+
+| 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.).
+
+---
+
+#### useMessageSigning
+
+Sign a message with the selected signer or wallet-adapter. Use inside `CilantroProvider`.
+
+**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. |
+
+**Returns:** `UseMessageSigningResult`
+
+| 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. |
+
+---
+
+#### useTransactionSigning
+
+Sign and/or send a transaction. Use inside `CilantroProvider`.
+
+**Options:** `UseTransactionSigningOptions`
+
+| 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. Provide your Solana `Connection` (e.g. from `@solana/web3.js`). |
+
+**Returns:** `UseTransactionSigningResult`
+
+| 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. |
+
+**Connection:** For passkey or wallet-adapter sign-and-send, you must pass a `connection` that has `getLatestBlockhash`, `sendRawTransaction`, and `confirmTransaction`. The library does not create a connection.
+
+---
+
+### Components (detailed)
+
+All components accept `className`. Many accept a `classNames` object (see TypeScript types e.g. `WalletSelectorClassNames`, `MessageSigningFormClassNames`).
+
+#### Auth components
+
+| 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
+
+| 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). |
+
+#### 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). |
+
+When token/wallet/signer/signingMethod are omitted, MessageSigningForm and TransactionSigningForm use `useCilantroAuth().token` and `useSignerSelection()` internally.
+
+### Types (detailed)
+
+#### ActionState
+
+Used by signing hooks and forms for result state.
+
+```ts
+type ActionState<T = unknown> = {
+  status: 'idle' | 'loading' | 'success' | 'error';
+  message?: string;
+  detail?: T;
+};
+```
+
+- **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
+
+From `useCilantroAuth().user`:
+
+```ts
+interface User {
+  username?: string;
+  email?: string;
+  userType?: string;
+}
+```
+
+#### WalletData
+
+From `useWallets().wallets` / `selectedWallet`:
+
+```ts
+interface WalletData {
+  id: string;
+  walletId: string;
+  walletName?: string;
+  address?: string;
+  walletAddress?: string;
+  chain?: string;
+  active?: boolean;
+  [key: string]: unknown;
+}
+```
+
+#### SignerData
+
+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.
+
+#### SignAndSendConnection
+
+Type for the `connection` prop when using sign-and-send (passkey or wallet-adapter). Your `Connection` from `@solana/web3.js` is compatible. Must have:
+
+- `getLatestBlockhash(commitment?)` → `Promise<{ blockhash, lastValidBlockHeight }>`
+- `confirmTransaction(opts: { signature, blockhash, lastValidBlockHeight })` → `Promise<void>`
+
+For wallet-adapter send, the hook also uses `sendRawTransaction(buf)` (standard Solana Connection has this).
+
+#### 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'`.
+
+#### Utilities
+
+- **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.
+
+---
+
+## Examples
+
+### Auth – single form (AuthForm)
+
+One form that switches between sign-in and create-account:
+
+```tsx
+import { AuthForm } 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"
+    />
+  )
+}
+```
+
+### Auth – separate Login and Register
+
+Use `LoginForm` and `RegisterForm` with links to switch pages:
+
+```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>
+      )}
+    />
+  )
+}
+
+function RegisterPage() {
+  return (
+    <RegisterForm
+      onSuccess={() => navigate('/dashboard')}
+      renderSwitchToLogin={() => (
+        <Link to="/login">Already have an account? Sign in</Link>
+      )}
+    />
+  )
+}
+```
+
+### Auth – protected route (AuthGuard)
+
+Show login when not authenticated, otherwise render children:
+
+```tsx
+import { AuthGuard, LoginForm } from 'cilantro-react'
+
+function DashboardRoute() {
+  return (
+    <AuthGuard fallback={<LoginForm />}>
+      <Dashboard />
+    </AuthGuard>
+  )
+}
+
+// Or use default fallback (LoginForm)
+<AuthGuard>
+  <Dashboard />
+</AuthGuard>
+
+// Hide content when unauthenticated (no fallback UI)
+<AuthGuard showFallback={false}>
+  <Dashboard />
+</AuthGuard>
+```
+
+### Wallets
+
+Wallet dropdown with optional customization:
+
+```tsx
+import { useWallets, WalletSelector } from 'cilantro-react'
+
+function Wallets() {
+  const { wallets, selectedWallet } = useWallets()
+
+  return (
+    <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>
+      )}
+    </div>
+  )
+}
+```
+
+### Signers – list and select
+
+Load signers for the selected wallet and let the user pick one:
+
+```tsx
+import { useSigners, useSignerSelection, SignerSelector } from 'cilantro-react'
+
+function SignerPick() {
+  const { walletId } = useSignerSelection({ walletId: selectedWalletId })
+  const { signers, isLoading, refresh } = useSigners({ walletId: walletId ?? undefined })
+
+  return (
+    <SignerSelector
+      selectedWalletId={walletId ?? undefined}
+      availableSigners={signers}
+      selectedSigner={selectedSigner}
+      onSignerSelect={setSelectedSigner}
+      isLoadingSigners={isLoading}
+      className="w-full"
+    />
+  )
+}
+```
+
+Headless: use `children` or `renderList` to render the list yourself.
+
+### Signers – add signer (AddSignerForm + SignerList)
+
+List signers and open a dialog to add a new one (email, phone, passkey, external wallet):
+
+```tsx
+import { SignerList } from 'cilantro-react'
+
+function SignersPage() {
+  const walletId = 'your-wallet-id'
+
+  return (
+    <SignerList
+      walletId={walletId}
+      onSignerAdded={() => console.log('Signer added')}
+    />
+  )
+}
+```
+
+AddSignerForm can also be used standalone (e.g. inline or in your own dialog):
+
+```tsx
+import { AddSignerForm } from 'cilantro-react'
+
+<AddSignerForm
+  walletId={walletId}
+  open={dialogOpen}
+  onOpenChange={setDialogOpen}
+  onSuccess={() => { refreshSigners(); setDialogOpen(false) }}
+  asDialog={true}
+/>
+```
+
+### Delegated keys
+
+Select a delegated key for a wallet:
+
+```tsx
+import { DelegatedKeySelector } from 'cilantro-react'
+
+function DelegatedKeys() {
+  const [keyId, setKeyId] = useState<string>('')
+
+  return (
+    <DelegatedKeySelector
+      walletId={walletId}
+      value={keyId}
+      onChange={(id, key) => setKeyId(id)}
+      placeholder="Select a delegated key"
+      filterActive={true}
+    />
+  )
+}
+```
+
+Use `children` for full control over the list UI.
+
+### Message signing
+
+Default UI with message textarea, sign button, and wallet/signer context:
+
+```tsx
+import { MessageSigningForm } from 'cilantro-react'
+
+function SignMessage() {
+  return (
+    <MessageSigningForm
+      showContext={true}
+      showCharCount={true}
+    />
+  )
+}
+```
+
+Headless: use `children` to get `messageText`, `setMessageText`, `handleSign`, `signResultState`, `isSigning`, `reset`:
+
+```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>
+```
+
+### Transaction signing
+
+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`):
+
+```tsx
+import { Connection } from '@solana/web3.js'
+import { TransactionSigningForm } from 'cilantro-react'
+
+function SendTx() {
+  const connection = new Connection('https://api.devnet.solana.com')
+
+  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>
+  )
+}
+```
+
+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.
+
+### Full flow example
+
+Typical app flow:
+
+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.
+
+---
+
+## Customization
+
+- **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`).
+
+---
+
+## Core types and utilities
+
+- **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`.
+
+---
+
+## Advanced / low-level
+
+**Signer signing (without React hooks):** For advanced usage you can call the core signer APIs directly:
+
+- `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.
+
+See TypeScript types and [cilantro-sdk](https://www.npmjs.com/package/cilantro-sdk) for full behavior.
+
+**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.
+
+---
+
+## Theming
+
+Components use Shadcn-style class names and CSS variables (e.g. `border-input`, `bg-primary`, `text-muted-foreground`). Ensure your app has Tailwind and, if you use Shadcn, your theme or `globals.css` defines those variables so colors and spacing match your design. You can override any part via `className` or `classNames`.
+
+For Shadcn theming, see [Theming - shadcn/ui](https://ui.shadcn.com/docs/theming).
+
+---
+
+## Low-level SDK
+
+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.