@solana/connector 0.1.3 → 0.1.5

package/README.md

@@ -3,255 +3,139 @@ title: @solana/connector
 description: Production-ready wallet connector for Solana applications
 ---
 
-**ConnectorKit is your Solana wallet infrastructure.** A headless, framework-agnostic wallet connector built on Wallet Standard with powerful transaction signing, event system, and performance optimizations that just work.
+**ConnectorKit is your Solana wallet infrastructure.** A headless, framework-agnostic wallet connector built on Wallet Standard that just work.
 
 ![npm](https://img.shields.io/npm/v/@solana/connector)
-![Bundle Size](https://img.shields.io/bundlephobia/minzip/@solana/connector)
+![Bundle Size](https://img.shields.io/badge/bundle-~45KB-gzip-green)
 ![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue)
-![Test Coverage](https://img.shields.io/badge/coverage-80%25+-green)
 
 ### Why ConnectorKit?
 
-- **Clean Transaction API**: Unified interface for signing and sending—no more wallet-specific logic
-- **Production Ready**: Event system, health checks, error boundaries, and monitoring built-in
-- **Better Performance**: 40-60% fewer re-renders via optimized state management
-- **Universal Compatibility**: Drop-in replacement for @solana/wallet-adapter
-- **Framework Agnostic**: React, Vue, Svelte, or vanilla JavaScript
-
-### Architecture
-
-- **Language**: TypeScript with full type safety
-- **Standard**: Built on Wallet Standard protocol
-- **Frameworks**: React hooks + headless core for any framework
-- **Mobile**: Solana Mobile Wallet Adapter integration
-- **Storage**: Enhanced persistence with SSR support
-
-### Features
-
-- Wallet Standard compliance with multi-wallet support
-- Clean transaction signer abstraction
-- Comprehensive event system for analytics
-- Connection pooling for better performance
-- Health checks and diagnostics
-- Auto-connect and account management
-- Network switching (mainnet, devnet, testnet, custom)
-- Browser polyfills for universal compatibility
-- Debug panel for development
-- Wallet Adapter compatibility bridge
-- 80%+ test coverage
+- **Wallet Standard First**: Built on the official Wallet Standard protocol for universal wallet compatibility
+- **Modern & Legacy Support**: Works with both `@solana/kit` (web3.js 2.0) and `@solana/web3.js` (legacy)
+- **Framework Agnostic**: React hooks + headless core for Vue, Svelte, or vanilla JavaScript
+- **Production Ready**: Event system for analytics, health checks for diagnostics, error boundaries for React apps
+- **Enhanced Storage**: Automatic validation, SSR fallback, and error handling out of the box
+- **Mobile Support**: Built-in Solana Mobile Wallet Adapter integration
 
 ---
 
 ## Quick Start
 
-Install ConnectorKit:
+### 1. Install
 
 ```bash
-pnpm add @solana/connector
-# or
 npm install @solana/connector
 # or
+pnpm add @solana/connector
+# or
 yarn add @solana/connector
+# or 
+bun add @solana/connector
 ```
 
-Basic usage:
+### 2. Setup Provider (once in your app root)
 
 ```typescript
-import {
-  ConnectorProvider,
-  getDefaultConfig,
-  useConnector,
-  useAccount,
-  useTransactionSigner
-} from '@solana/connector';
-
-// 1. Wrap your app
-function App() {
-  return (
-    <ConnectorProvider config={getDefaultConfig({ appName: "My App" })}>
-      <WalletButton />
-    </ConnectorProvider>
-  );
-}
-
-// 2. Connect wallet
-function WalletButton() {
-  const { wallets, select, connected, disconnect } = useConnector();
-  const { address, formatted } = useAccount();
-
-  if (!connected) {
-    return wallets.map(w => (
-      <button key={w.name} onClick={() => select(w.name)}>
-        Connect {w.name}
-      </button>
-    ));
-  }
-
-  return (
-    <>
-      <span>{formatted}</span>
-      <button onClick={disconnect}>Disconnect</button>
-    </>
-  );
-}
-
-// 3. Sign transactions
-function SendTransaction() {
-  const { signer, ready } = useTransactionSigner();
-
-  const handleSend = async () => {
-    const signature = await signer.signAndSendTransaction(transaction);
-  };
+'use client';
+
+import { useMemo } from 'react';
+import { AppProvider } from '@solana/connector/react';
+import { getDefaultConfig, getDefaultMobileConfig } from '@solana/connector/headless';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+    const connectorConfig = useMemo(() => {
+        // Optional: Get custom RPC URL from environment variable
+        const customRpcUrl = process.env.SOLANA_RPC_URL;
+
+        // Optional: Create custom cluster configuration
+        const clusters = customRpcUrl
+            ? [
+                  {
+                      id: 'solana:mainnet' as const,
+                      label: 'Mainnet (Custom RPC)',
+                      name: 'mainnet-beta' as const,
+                      url: customRpcUrl,
+                  },
+                  {
+                      id: 'solana:devnet' as const,
+                      label: 'Devnet',
+                      name: 'devnet' as const,
+                      url: 'https://api.devnet.solana.com',
+                  },
+              ]
+            : undefined;
+
+        return getDefaultConfig({
+            appName: 'My App',
+            appUrl: 'https://myapp.com',
+            autoConnect: true,
+            enableMobile: true,
+            clusters,
+        });
+    }, []);
 
-  return <button onClick={handleSend} disabled={!ready}>Send</button>;
+    const mobile = useMemo(
+        () =>
+            getDefaultMobileConfig({
+                appName: 'My App',
+                appUrl: 'https://myapp.com',
+            }),
+        [],
+    );
+
+    return (
+        <AppProvider connectorConfig={connectorConfig} mobile={mobile}>
+            {children}
+        </AppProvider>
+    );
 }
 ```
 
-**[→ Getting Started](#core-hooks)** - Learn the core hooks
-
-**[→ Transaction Signer](#transaction-signer)** - Sign and send transactions
-
-**[→ Event System](#event-system)** - Track wallet events for analytics
-
-**[→ Framework Guides](#headless-client-vue-svelte-vanilla-js)** - Use with Vue, Svelte, or vanilla JS
-
----
-
-## Documentation
-
-### Getting Started
-
-- [Installation](#quick-start)
-- [Quick Start Guide](#quick-start)
-- [TypeScript SDK](#typescript-sdk)
-- [Core Hooks](#core-hooks)
-- [Local Development](#local-development)
-
-### Production Features
-
-- [Transaction Signer](#transaction-signer) - Clean signing API
-- [Event System](#event-system) - Analytics and monitoring
-- [Debug Panel](#debug-panel) - Development tools
-- [Connection Pooling](#connection-pooling) - Performance optimization
-- [Health Checks](#health-checks) - Diagnostics
-- [Wallet Adapter Compatibility](#wallet-adapter-compatibility) - Drop-in replacement
-
-### Configuration & Usage
-
-- [Configuration](#configuration) - Setup options
-- [Network Selection](#network-selection) - Cluster management
-- [Custom Storage](#custom-storage) - Persistence options
-- [Mobile Wallet Adapter](#mobile-wallet-adapter) - Mobile support
-- [Advanced Usage](#advanced-usage) - Framework-specific guides
-
-### Reference
-
-- [Complete API Reference](#complete-api-reference)
-- [Configuration Functions](#configuration-functions)
-- [Transaction Signing API](#transaction-signing-api-new)
-- [Event System API](#event-system-api-new)
-- [Health Check API](#health-check-api-new)
-- [Connection Pool API](#connection-pool-api-new)
-- [Utility Functions](#utility-functions)
-- [TypeScript Types](#types)
-
-### Testing & Performance
-
-- [Testing](#testing) - Test suite and utilities
-- [Performance](#performance) - Bundle size and optimization
-- [Browser Compatibility](#browser-compatibility)
-
-### Migration & Examples
-
-- [Migration from wallet-adapter](#migration-from-solanawallet-adapter)
-- [Examples](#examples)
-- [Supported Wallets](#supported-wallets)
-
----
-
-## TypeScript SDK
-
-ConnectorKit provides React hooks and a headless core for any framework:
+### 3. Use Hooks (in any component)
 
 ```typescript
-// React
-import { useConnector, useTransactionSigner, useAccount } from '@solana/connector';
-
-// Headless (Vue, Svelte, vanilla JS)
-import { ConnectorClient, getDefaultConfig } from '@solana/connector/headless';
-
-const client = new ConnectorClient(getDefaultConfig({ appName: 'My App' }));
-await client.select('Phantom');
-```
-
-**[→ API Reference](#complete-api-reference)** - Full TypeScript API documentation
-
-**[→ Core Hooks](#core-hooks)** - React hooks reference
+'use client';
 
-**[→ Headless Guide](#headless-client-vue-svelte-vanilla-js)** - Use without React
+import { useConnector, useAccount } from '@solana/connector';
 
----
-
-## Local Development
-
-### Prerequisites
-
-- Node.js 20+ (or 18+)
-- pnpm, npm, or yarn
-- TypeScript 5.0+
-
-### Installation
-
-```bash
-git clone https://github.com/your-org/connectorkit.git
-cd connectorkit
-pnpm install
-```
-
-### Build
-
-```bash
-pnpm build
-```
+export function ConnectButton() {
+    const { wallets, select, disconnect, connected, connecting, selectedWallet, selectedAccount } = useConnector();
+    const { address, formatted, copy } = useAccount();
 
-### Running Examples
-
-```bash
-cd examples/react
-pnpm dev
-```
-
-Or run the Vite example:
-
-```bash
-cd examples/vite
-pnpm dev
-```
-
-### Local Testing
-
-Run all tests:
-
-```bash
-pnpm test
-```
+    if (connecting) {
+        return <button disabled>Connecting...</button>;
+    }
 
-Run tests in watch mode:
+    if (!connected) {
+        return (
+            <div>
+                {wallets.map(w => (
+                    <button key={w.wallet.name} onClick={() => select(w.wallet.name)}>
+                        Connect {w.wallet.name}
+                    </button>
+                ))}
+            </div>
+        );
+    }
 
-```bash
-pnpm test:watch
+    return (
+        <div>
+            <button onClick={copy}>{formatted}</button>
+            <button onClick={disconnect}>Disconnect</button>
+        </div>
+    );
+}
 ```
 
-Generate coverage report:
-
-```bash
-pnpm test:coverage
-```
+**That's it!** You're ready to go. Everything else below is optional.
 
 ---
 
 ## Core Hooks
 
+These are the main hooks you'll use in your components.
+
 ### `useConnector()`
 
 Main hook for wallet connection and state.
@@ -264,6 +148,7 @@ function Component() {
         // State
         wallets, // WalletInfo[] - All available wallets
         selectedWallet, // Wallet | null - Currently connected wallet
+        selectedAccount, // string | null - Currently selected account address
         accounts, // AccountInfo[] - Connected accounts
         connected, // boolean - Connection status
         connecting, // boolean - Connecting in progress
@@ -275,6 +160,41 @@ function Component() {
 }
 ```
 
+**Real Example** - Connect Button with wallet selection:
+
+```typescript
+'use client';
+
+import { useConnector } from '@solana/connector';
+import { useState } from 'react';
+
+export function ConnectButton() {
+    const [isModalOpen, setIsModalOpen] = useState(false);
+    const { connected, connecting, selectedWallet, selectedAccount, wallets, select } = useConnector();
+
+    if (connecting) {
+        return <button disabled>Connecting...</button>;
+    }
+
+    if (connected && selectedAccount && selectedWallet) {
+        const shortAddress = `${selectedAccount.slice(0, 4)}...${selectedAccount.slice(-4)}`;
+        return (
+            <div>
+                <span>{shortAddress}</span>
+                <button onClick={() => select(selectedWallet.name)}>Switch Wallet</button>
+            </div>
+        );
+    }
+
+    return (
+        <>
+            <button onClick={() => setIsModalOpen(true)}>Connect Wallet</button>
+            {/* Wallet selection modal */}
+        </>
+    );
+}
+```
+
 ### `useAccount()`
 
 Hook for working with the connected account.
@@ -295,6 +215,35 @@ function Component() {
 }
 ```
 
+**Real Example** - Account Switcher for multi-account wallets:
+
+```typescript
+'use client';
+
+import { useAccount } from '@solana/connector';
+
+export function AccountSwitcher() {
+    const { accounts, address, selectAccount, connected } = useAccount();
+
+    if (!connected || accounts.length <= 1) {
+        return null;
+    }
+
+    return (
+        <select
+            value={address || ''}
+            onChange={e => selectAccount(e.target.value)}
+        >
+            {accounts.map(account => (
+                <option key={account.address} value={account.address}>
+                    {account.address.slice(0, 6)}...{account.address.slice(-6)}
+                </option>
+            ))}
+        </select>
+    );
+}
+```
+
 ### `useCluster()`
 
 Hook for managing Solana network/cluster.
@@ -315,359 +264,583 @@ function Component() {
 }
 ```
 
+**Real Example** - Network Selector:
+
+```typescript
+'use client';
+
+import { useCluster } from '@solana/connector';
+
+export function ClusterSelector() {
+    const { cluster, clusters, setCluster } = useCluster();
+
+    return (
+        <select
+            value={cluster?.id || ''}
+            onChange={e => setCluster(e.target.value as SolanaClusterId)}
+        >
+            {clusters.map(c => (
+                <option key={c.id} value={c.id}>
+                    {c.label}
+                </option>
+            ))}
+        </select>
+    );
+}
+```
+
+### `useWalletInfo()`
+
+Hook for accessing current wallet metadata.
+
+```typescript
+import { useWalletInfo } from '@solana/connector';
+
+function Component() {
+    const {
+        name, // string | null - Wallet name
+        icon, // string | undefined - Wallet icon URL
+        wallet, // WalletInfo | null - Full wallet info
+        connecting, // boolean - Connection in progress
+    } = useWalletInfo();
+}
+```
+
 ---
 
-## Production Features
+## Transaction Signing
+
+ConnectorKit provides powerful transaction signing capabilities with support for both legacy `@solana/web3.js` and modern `@solana/kit` APIs.
 
-### Transaction Signer
+### Modern API (`@solana/kit`)
 
-Clean, unified interface for transaction signing operations.
+Use `useKitTransactionSigner()` for modern, type-safe transaction building:
 
 ```typescript
-import { useTransactionSigner } from '@solana/connector';
+'use client';
 
-function SendTx() {
-  const { signer, ready, capabilities } = useTransactionSigner();
+import { useState } from 'react';
+import {
+    address,
+    createSolanaRpc,
+    pipe,
+    createTransactionMessage,
+    setTransactionMessageFeePayerSigner,
+    setTransactionMessageLifetimeUsingBlockhash,
+    appendTransactionMessageInstructions,
+    sendAndConfirmTransactionFactory,
+    getSignatureFromTransaction,
+    signTransactionMessageWithSigners,
+    createSolanaRpcSubscriptions,
+    lamports,
+    assertIsTransactionWithBlockhashLifetime,
+} from '@solana/kit';
+import { getTransferSolInstruction } from '@solana-program/system';
+import { useKitTransactionSigner, useCluster, useConnectorClient, LAMPORTS_PER_SOL } from '@solana/connector';
+
+export function ModernSolTransfer() {
+    const { signer, ready } = useKitTransactionSigner();
+    const { cluster } = useCluster();
+    const client = useConnectorClient();
+    const [signature, setSignature] = useState<string | null>(null);
 
-  // Check capabilities
-  console.log('Can sign:', capabilities.canSign);
-  console.log('Can send:', capabilities.canSend);
-  console.log('Can sign messages:', capabilities.canSignMessage);
-  console.log('Batch support:', capabilities.supportsBatchSigning);
+    async function handleTransfer(recipientAddress: string, amount: number) {
+        if (!signer || !client) {
+            throw new Error('Wallet not connected');
+        }
 
-  const handleSend = async () => {
-    if (!signer) return;
+        // Get RPC URL from connector client
+        const rpcUrl = client.getRpcUrl();
+        if (!rpcUrl) {
+            throw new Error('No RPC endpoint configured');
+        }
 
-    try {
-      // Sign and send a transaction
-      const signature = await signer.signAndSendTransaction(transaction);
-      console.log('Success:', signature);
+        // Create RPC client using web3.js 2.0
+        const rpc = createSolanaRpc(rpcUrl);
+        const rpcSubscriptions = createSolanaRpcSubscriptions(rpcUrl.replace('http', 'ws'));
 
-      // Or just sign without sending
-      const signed = await signer.signTransaction(transaction);
+        // Get recent blockhash
+        const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
 
-      // Or sign multiple transactions
-      const signedBatch = await signer.signAllTransactions([tx1, tx2, tx3]);
+        // Convert SOL to lamports
+        const amountInLamports = lamports(BigInt(Math.floor(amount * Number(LAMPORTS_PER_SOL))));
 
-      // Or sign and send multiple
-      const signatures = await signer.signAndSendTransactions([tx1, tx2]);
+        // Create transfer instruction
+        const transferInstruction = getTransferSolInstruction({
+            source: signer,
+            destination: address(recipientAddress),
+            amount: amountInLamports,
+        });
 
-    } catch (error) {
-      if (error instanceof TransactionSignerError) {
-        console.error('Signing error:', error.code, error.message);
-      }
-    }
-  };
+        // Build transaction message
+        const transactionMessage = pipe(
+            createTransactionMessage({ version: 0 }),
+            tx => setTransactionMessageFeePayerSigner(signer, tx),
+            tx => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
+            tx => appendTransactionMessageInstructions([transferInstruction], tx),
+        );
 
-  return (
-    <button onClick={handleSend} disabled={!ready}>
-      Send Transaction
-    </button>
-  );
-}
-```
+        // Sign transaction
+        const signedTransaction = await signTransactionMessageWithSigners(transactionMessage);
 
-**Error Handling**:
+        // Send and confirm
+        assertIsTransactionWithBlockhashLifetime(signedTransaction);
+        await sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions })(signedTransaction, {
+            commitment: 'confirmed',
+        });
 
-```typescript
-import { isTransactionSignerError, TransactionSignerError } from '@solana/connector';
-
-try {
-    await signer.signAndSendTransaction(tx);
-} catch (error) {
-    if (isTransactionSignerError(error)) {
-        switch (error.code) {
-            case 'WALLET_NOT_CONNECTED':
-                // Show connect prompt
-                break;
-            case 'FEATURE_NOT_SUPPORTED':
-                // Show unsupported feature message
-                break;
-            case 'SIGNING_FAILED':
-                // User rejected or signing failed
-                break;
-            case 'SEND_FAILED':
-                // Transaction broadcast failed
-                break;
-        }
+        const transactionSignature = getSignatureFromTransaction(signedTransaction);
+        setSignature(transactionSignature);
     }
+
+    return (
+        <div>
+            {/* Your form UI */}
+            <button onClick={() => handleTransfer('...', 0.1)} disabled={!ready}>
+                Send SOL
+            </button>
+            {signature && <div>Transaction: {signature}</div>}
+        </div>
+    );
 }
 ```
 
-### Event System
+### Legacy API (`@solana/web3.js`)
 
-Track all connector lifecycle events for analytics and monitoring.
+Use `useTransactionSigner()` for legacy web3.js compatibility:
 
 ```typescript
-import { useConnectorClient } from '@solana/connector';
+import { useTransactionSigner } from '@solana/connector';
+import { Transaction, SystemProgram } from '@solana/web3.js';
 
-function AnalyticsTracker() {
-    const client = useConnectorClient();
+function SendTransaction() {
+    const { signer, ready } = useTransactionSigner();
 
-    useEffect(() => {
-        if (!client) return;
-
-        // Subscribe to events
-        const unsubscribe = client.on(event => {
-            switch (event.type) {
-                case 'wallet:connected':
-                    analytics.track('Wallet Connected', {
-                        wallet: event.wallet,
-                        account: event.account,
-                        timestamp: event.timestamp,
-                    });
-                    break;
-
-                case 'wallet:disconnected':
-                    analytics.track('Wallet Disconnected');
-                    break;
-
-                case 'cluster:changed':
-                    analytics.track('Network Changed', {
-                        from: event.previousCluster,
-                        to: event.cluster,
-                    });
-                    break;
-
-                case 'error':
-                    errorTracker.captureException(event.error, {
-                        context: event.context,
-                    });
-                    break;
-            }
-        });
+    const handleSend = async () => {
+        if (!signer) return;
 
-        return unsubscribe;
-    }, [client]);
+        const transaction = new Transaction().add(
+            SystemProgram.transfer({
+                fromPubkey: signer.address,
+                toPubkey: recipientPubkey,
+                lamports: 1000000,
+            })
+        );
+
+        const signature = await signer.signAndSendTransaction(transaction);
+        console.log('Transaction sent:', signature);
+    };
 
-    return null;
+    return <button onClick={handleSend} disabled={!ready}>Send</button>;
 }
 ```
 
-**Available Events**:
+---
+
+## UI Elements
 
-- `wallet:connected` - Wallet successfully connected
-- `wallet:disconnected` - Wallet disconnected
-- `wallet:changed` - Selected wallet changed
-- `account:changed` - Selected account changed
-- `cluster:changed` - Network/cluster changed
-- `wallets:detected` - New wallets detected
-- `connecting` - Connection attempt started
-- `connection:failed` - Connection attempt failed
-- `error` - Error occurred
+ConnectorKit provides composable UI elements that handle data fetching and state management for you. Use the render prop pattern to customize the UI.
 
-### Debug Panel
+### Available Elements
 
-Floating development panel for instant state visibility.
+- `BalanceElement` - Display SOL balance with refresh
+- `ClusterElement` - Network/cluster selector
+- `TokenListElement` - List of SPL tokens
+- `TransactionHistoryElement` - Recent transaction history
+- `DisconnectElement` - Disconnect button
+- `AccountElement` - Account display and switcher
+- `WalletListElement` - List of available wallets
+
+### Example: Wallet Dropdown
 
 ```typescript
-import { ConnectorDebugPanel } from '@solana/connector';
-
-function App() {
-  return (
-    <ConnectorProvider config={config}>
-      {/* Only visible in development mode */}
-      {process.env.NODE_ENV === 'development' && <ConnectorDebugPanel />}
-      <YourApp />
-    </ConnectorProvider>
-  );
+'use client';
+
+import {
+    BalanceElement,
+    ClusterElement,
+    TokenListElement,
+    TransactionHistoryElement,
+    DisconnectElement,
+} from '@solana/connector/react';
+
+export function WalletDropdown() {
+    return (
+        <div className="wallet-dropdown">
+            {/* Balance */}
+            <BalanceElement
+                render={({ solBalance, isLoading, refetch }) => (
+                    <div>
+                        <div>Balance: {isLoading ? '...' : `${solBalance?.toFixed(4)} SOL`}</div>
+                        <button onClick={refetch}>Refresh</button>
+                    </div>
+                )}
+            />
+
+            {/* Network Selector */}
+            <ClusterElement
+                render={({ cluster, clusters, setCluster }) => (
+                    <select value={cluster?.id} onChange={e => setCluster(e.target.value)}>
+                        {clusters.map(c => (
+                            <option key={c.id} value={c.id}>
+                                {c.label}
+                            </option>
+                        ))}
+                    </select>
+                )}
+            />
+
+            {/* Tokens */}
+            <TokenListElement
+                limit={5}
+                render={({ tokens, isLoading }) => (
+                    <div>
+                        {isLoading ? (
+                            <div>Loading tokens...</div>
+                        ) : (
+                            tokens.map(token => (
+                                <div key={token.mint}>
+                                    {token.symbol}: {token.formatted}
+                                </div>
+                            ))
+                        )}
+                    </div>
+                )}
+            />
+
+            {/* Transaction History */}
+            <TransactionHistoryElement
+                limit={5}
+                render={({ transactions, isLoading }) => (
+                    <div>
+                        {isLoading ? (
+                            <div>Loading transactions...</div>
+                        ) : (
+                            transactions.map(tx => (
+                                <a key={tx.signature} href={tx.explorerUrl} target="_blank">
+                                    {tx.type} - {tx.formattedTime}
+                                </a>
+                            ))
+                        )}
+                    </div>
+                )}
+            />
+
+            {/* Disconnect */}
+            <DisconnectElement
+                render={({ disconnect, disconnecting }) => (
+                    <button onClick={disconnect} disabled={disconnecting}>
+                        {disconnecting ? 'Disconnecting...' : 'Disconnect'}
+                    </button>
+                )}
+            />
+        </div>
+    );
 }
 ```
 
-**Features**:
+---
 
-- Shows connection status (connected/disconnected/connecting)
-- Displays current account and wallet
-- Shows active cluster and RPC URL
-- Lists detected wallets
-- Health check information
-- Click to expand/collapse
-- Automatically excluded in production builds
+## Configuration
 
-**Custom positioning**:
+### Basic Configuration
 
 ```typescript
-<ConnectorDebugPanel
-  position="top-left"    // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
-  defaultOpen={true}
-  zIndex={10000}
-/>
-```
+import { getDefaultConfig } from '@solana/connector';
 
-### Connection Pooling
+const config = getDefaultConfig({
+    appName: 'My App', // Required
+    appUrl: 'https://myapp.com', // Optional: for mobile wallet adapter
+    autoConnect: true, // Auto-reconnect (default: true)
+    network: 'mainnet-beta', // Initial network (default: 'mainnet-beta')
+    enableMobile: true, // Mobile Wallet Adapter (default: true)
+    debug: false, // Debug logging
+});
+```
 
-Reusable RPC connections for better performance.
+### Network Selection
 
 ```typescript
-import { ConnectionPool, createConnectionPool } from '@solana/connector/headless';
-import { Connection } from '@solana/web3.js';
-
-// Create custom pool
-const pool = createConnectionPool({
-    maxSize: 10,
-    createConnection: cluster => {
-        return new Connection(cluster.endpoint, {
-            commitment: 'confirmed',
-        });
-    },
+const config = getDefaultConfig({
+    appName: 'My App',
+    network: 'devnet', // 'mainnet-beta' | 'devnet' | 'testnet' | 'localnet'
 });
+```
 
-// Get or create connection for a cluster
-const connection = pool.get(currentCluster);
-const balance = await connection.getBalance(publicKey);
+### Custom RPC Endpoints
 
-// Clear specific connection when settings change
-pool.clear('solana:mainnet');
+```typescript
+import { getDefaultConfig } from '@solana/connector';
 
-// Get pool statistics
-const stats = pool.getStats();
-console.log(`Pool: ${stats.size}/${stats.maxSize}`);
-console.log(`Hit rate: ${(stats.hits / (stats.hits + stats.misses)) * 100}%`);
+const config = getDefaultConfig({
+    appName: 'My App',
+    clusters: [
+        {
+            id: 'solana:mainnet' as const,
+            label: 'Mainnet (Custom RPC)',
+            name: 'mainnet-beta' as const,
+            url: 'https://my-custom-rpc.com',
+        },
+        {
+            id: 'solana:devnet' as const,
+            label: 'Devnet',
+            name: 'devnet' as const,
+            url: 'https://api.devnet.solana.com',
+        },
+    ],
+});
 ```
 
-**Global pool** (simpler):
+### Mobile Wallet Adapter
 
 ```typescript
-import { getConnectionPool } from '@solana/connector/headless';
+import { getDefaultMobileConfig } from '@solana/connector/headless';
+
+const mobile = getDefaultMobileConfig({
+    appName: 'My App',
+    appUrl: 'https://myapp.com',
+});
 
-const pool = getConnectionPool();
-const connection = pool.get(cluster);
+<AppProvider connectorConfig={config} mobile={mobile}>
+    {children}
+</AppProvider>
 ```
 
-### Health Checks
+---
 
-Comprehensive diagnostics for debugging and monitoring.
+## Security Considerations
 
-```typescript
-import { useConnectorClient } from '@solana/connector';
+### Token Image Privacy
 
-function HealthMonitor() {
-  const client = useConnectorClient();
+When using `useTokens()` or `useTransactions()`, token metadata (including logo URLs) is fetched from external APIs. By default, these image URLs are returned directly, which means when your users' browsers fetch these images, the image host can see:
 
-  if (!client) return null;
+- User IP addresses
+- Request timing (when users viewed their tokens)
+- User agent and browser information
 
-  const health = client.getHealth();
+This could potentially be exploited by malicious token creators who set tracking URLs in their token metadata.
 
-  return (
-    <div>
-      <h3>Connector Health</h3>
-      <div>Initialized: {health.initialized ? '✓' : '✗'}</div>
-      <div>Wallet Standard: {health.walletStandardAvailable ? '✓' : '✗'}</div>
-      <div>Storage: {health.storageAvailable ? '✓' : '✗'}</div>
-      <div>Wallets Detected: {health.walletsDetected}</div>
+### Image Proxy Configuration
 
-      {health.errors.length > 0 && (
-        <div className="errors">
-          {health.errors.map(err => <div key={err}>{err}</div>)}
-        </div>
-      )}
-    </div>
-  );
-}
+To protect user privacy, you can configure an image proxy that fetches images on behalf of your users:
+
+```typescript
+const config = getDefaultConfig({
+    appName: 'My App',
+    imageProxy: '/_next/image?w=64&q=75&url=', // Next.js Image Optimization
+});
+```
+
+When `imageProxy` is set, all token image URLs returned by `useTokens()` and `useTransactions()` will be automatically transformed:
+
+```
+// Original URL from token metadata
+https://raw.githubusercontent.com/.../token-logo.png
+
+// Transformed URL (when imageProxy is set)
+/_next/image?w=64&q=75&url=https%3A%2F%2Fraw.githubusercontent.com%2F...%2Ftoken-logo.png
 ```
 
-### Wallet Adapter Compatibility
+### Common Proxy Options
 
-Drop-in replacement for libraries expecting @solana/wallet-adapter.
+| Service | Configuration |
+|---------|---------------|
+| **Next.js Image** | `imageProxy: '/_next/image?w=64&q=75&url='` |
+| **Cloudflare** | `imageProxy: '/cdn-cgi/image/width=64,quality=75/'` |
+| **imgproxy** | `imageProxy: 'https://imgproxy.example.com/insecure/fill/64/64/'` |
+| **Custom API** | `imageProxy: '/api/image-proxy?url='` |
+
+### Custom Proxy API Route (Next.js Example)
 
 ```typescript
-import { useTransactionSigner, useConnector } from '@solana/connector';
-import { createWalletAdapterCompat } from '@solana/connector/compat';
+// app/api/image-proxy/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import dns from 'dns/promises';
+
+// Allowlist of permitted domains for image fetching
+const ALLOWED_DOMAINS = [
+    'raw.githubusercontent.com',
+    'arweave.net',
+    'ipfs.io',
+    'cloudflare-ipfs.com',
+    'nftstorage.link',
+    // Add other trusted image domains as needed
+];
+
+// Check if an IP address falls within private/reserved ranges
+function isPrivateOrReservedIP(ip: string): boolean {
+    // IPv4 private/reserved ranges
+    const ipv4PrivateRanges = [
+        /^127\./, // 127.0.0.0/8 (loopback)
+        /^10\./, // 10.0.0.0/8 (private)
+        /^172\.(1[6-9]|2[0-9]|3[0-1])\./, // 172.16.0.0/12 (private)
+        /^192\.168\./, // 192.168.0.0/16 (private)
+        /^169\.254\./, // 169.254.0.0/16 (link-local/metadata)
+        /^0\./, // 0.0.0.0/8 (current network)
+        /^100\.(6[4-9]|[7-9][0-9]|1[0-1][0-9]|12[0-7])\./, // 100.64.0.0/10 (CGNAT)
+        /^192\.0\.0\./, // 192.0.0.0/24 (IETF protocol assignments)
+        /^192\.0\.2\./, // 192.0.2.0/24 (TEST-NET-1)
+        /^198\.51\.100\./, // 198.51.100.0/24 (TEST-NET-2)
+        /^203\.0\.113\./, // 203.0.113.0/24 (TEST-NET-3)
+        /^224\./, // 224.0.0.0/4 (multicast)
+        /^240\./, // 240.0.0.0/4 (reserved)
+        /^255\.255\.255\.255$/, // broadcast
+    ];
+
+    // IPv6 private/reserved ranges
+    const ipv6PrivatePatterns = [
+        /^::1$/, // loopback
+        /^fe80:/i, // link-local
+        /^fc00:/i, // unique local (fc00::/7)
+        /^fd/i, // unique local (fd00::/8)
+        /^::ffff:(127\.|10\.|172\.(1[6-9]|2[0-9]|3[0-1])\.|192\.168\.|169\.254\.)/i, // IPv4-mapped
+    ];
+
+    // Check IPv4
+    for (const range of ipv4PrivateRanges) {
+        if (range.test(ip)) return true;
+    }
+
+    // Check IPv6
+    for (const pattern of ipv6PrivatePatterns) {
+        if (pattern.test(ip)) return true;
+    }
 
-function JupiterIntegration() {
-  const { signer } = useTransactionSigner();
-  const { disconnect } = useConnector();
+    return false;
+}
 
-  // Create wallet-adapter compatible interface
-  const walletAdapter = createWalletAdapterCompat(signer, {
-    disconnect: async () => {
-      await disconnect();
-    },
-    onError: (error, operation) => {
-      console.error(`Wallet adapter error in ${operation}:`, error);
+// Validate and parse the URL
+function validateUrl(urlString: string): URL | null {
+    try {
+        const parsed = new URL(urlString);
+        // Only allow http and https protocols
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return null;
+        }
+        return parsed;
+    } catch {
+        return null;
     }
-  });
+}
 
-  // Use with Jupiter, Serum, or any wallet-adapter library
-  return <JupiterTerminal wallet={walletAdapter} />;
+// Check if hostname is in the allowlist
+function isAllowedDomain(hostname: string): boolean {
+    return ALLOWED_DOMAINS.some(
+        (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
+    );
 }
-```
 
-**Compatible with**:
+export async function GET(request: NextRequest) {
+    const urlParam = request.nextUrl.searchParams.get('url');
+    
+    // (1) Ensure URL exists and parses correctly with http/https
+    if (!urlParam) {
+        return new NextResponse('Missing URL parameter', { status: 400 });
+    }
 
-- Jupiter Aggregator
-- Serum DEX
-- Raydium
-- Marinade Finance
-- Any library expecting @solana/wallet-adapter
+    const parsedUrl = validateUrl(urlParam);
+    if (!parsedUrl) {
+        return new NextResponse('Invalid URL or protocol', { status: 400 });
+    }
+
+    // (2) Enforce allowlist of permitted domains
+    if (!isAllowedDomain(parsedUrl.hostname)) {
+        return new NextResponse('Domain not allowed', { status: 403 });
+    }
+
+    // (3) Resolve hostname and check for private/reserved IPs
+    try {
+        const addresses = await dns.resolve(parsedUrl.hostname);
+        for (const ip of addresses) {
+            if (isPrivateOrReservedIP(ip)) {
+                return new NextResponse('Resolved IP is not allowed', { status: 403 });
+            }
+        }
+    } catch {
+        return new NextResponse('Failed to resolve hostname', { status: 400 });
+    }
+
+    // (4) All checks passed - perform the fetch
+    try {
+        const response = await fetch(parsedUrl.toString());
+        const buffer = await response.arrayBuffer();
+        
+        return new NextResponse(buffer, {
+            headers: {
+                'Content-Type': response.headers.get('Content-Type') || 'image/png',
+                'Cache-Control': 'public, max-age=86400',
+            },
+        });
+    } catch {
+        return new NextResponse('Failed to fetch image', { status: 500 });
+    }
+}
+```
 
 ---
 
-## Configuration
+## CoinGecko API & Rate Limits
 
-### Basic Configuration
+The `useTokens()` hook fetches token prices from CoinGecko. CoinGecko has rate limits that may affect your application:
 
-```typescript
-import { getDefaultConfig } from '@solana/connector';
+### Rate Limits (as of 2024)
 
-const config = getDefaultConfig({
-    appName: 'My App', // Required
-    autoConnect: true, // Auto-reconnect (default: true)
-    network: 'mainnet-beta', // Initial network
-    enableMobile: true, // Mobile Wallet Adapter (default: true)
-    debug: false, // Debug logging
+| Tier | Rate Limit | API Key Required |
+|------|------------|------------------|
+| **Free (Public)** | 10-30 requests/minute | No |
+| **Demo** | 30 requests/minute | Yes (free) |
+| **Analyst** | 500 requests/minute | Yes (paid) |
+| **Pro** | 1000+ requests/minute | Yes (paid) |
 
-    // NEW: Custom error handler
-    onError: (error, errorInfo) => {
-        console.error('Connector error:', error);
-        errorTracker.captureException(error, errorInfo);
-    },
-});
-```
+### Handling Rate Limits
 
-### Network Selection
+ConnectorKit automatically handles rate limits with:
+- **Exponential backoff**: Retries with increasing delays
+- **Jitter**: Random delay added to prevent thundering herd
+- **Retry-After header**: Honors server-specified wait times
+- **Bounded timeout**: Won't block forever (default 30s max)
+
+### Adding a CoinGecko API Key
+
+For higher rate limits, add a free Demo API key from [CoinGecko](https://www.coingecko.com/en/api/pricing):
 
 ```typescript
 const config = getDefaultConfig({
     appName: 'My App',
-    network: 'devnet', // 'mainnet-beta' | 'devnet' | 'testnet' | 'localnet'
+    coingecko: {
+        apiKey: process.env.COINGECKO_API_KEY, // Demo or Pro API key
+        isPro: false, // Set to true for Pro API keys
+    },
 });
 ```
 
-### Custom Clusters
+### Advanced Configuration
 
 ```typescript
-import { getDefaultConfig, createSolanaMainnet } from '@solana/connector';
-
 const config = getDefaultConfig({
     appName: 'My App',
-    clusters: [
-        createSolanaMainnet({
-            endpoint: 'https://my-custom-rpc.com',
-        }),
-    ],
-    customClusters: [
-        // Add additional custom clusters
-    ],
+    coingecko: {
+        // API key for higher rate limits (optional)
+        apiKey: process.env.COINGECKO_API_KEY,
+        
+        // Set to true if using a Pro API key (default: false for Demo keys)
+        isPro: false,
+        
+        // Maximum retry attempts on 429 (default: 3)
+        maxRetries: 3,
+        
+        // Base delay for exponential backoff in ms (default: 1000)
+        baseDelay: 1000,
+        
+        // Maximum total timeout in ms (default: 30000)
+        maxTimeout: 30000,
+    },
 });
 ```
 
-### Mobile Wallet Adapter
+### Caching
 
-```typescript
-<ConnectorProvider
-  config={config}
-  mobile={{
-    appIdentity: {
-      name: 'My App',
-      uri: 'https://myapp.com',
-      icon: 'https://myapp.com/icon.png'
-    }
-  }}
->
-  <App />
-</ConnectorProvider>
-```
+Token prices are cached for 60 seconds to minimize API calls. The retry logic only applies to uncached token IDs, so frequently-viewed tokens won't trigger additional API calls.
 
 ---
 
@@ -675,7 +848,7 @@ const config = getDefaultConfig({
 
 ### Headless Client (Vue, Svelte, Vanilla JS)
 
-Use `ConnectorClient` for non-React frameworks.
+Use `ConnectorClient` for non-React frameworks:
 
 ```typescript
 import { ConnectorClient, getDefaultConfig } from '@solana/connector/headless';
@@ -695,15 +868,6 @@ const unsubscribe = client.subscribe(state => {
     console.log('State updated:', state);
 });
 
-// Subscribe to events (NEW!)
-const unsubEvents = client.on(event => {
-    console.log('Event:', event.type, event);
-});
-
-// Check health (NEW!)
-const health = client.getHealth();
-console.log('Health:', health);
-
 // Disconnect
 await client.disconnect();
 
@@ -711,44 +875,15 @@ await client.disconnect();
 client.destroy();
 ```
 
-### Unified Config (Armadura Integration)
-
-If you're using both ConnectorKit and Armadura:
-
-```typescript
-import { createConfig, AppProvider } from '@solana/connector';
-import { ArmaProvider } from '@armadura/sdk';
-
-const config = createConfig({
-  appName: 'My App',
-  network: 'mainnet',
-  rpcUrl: 'https://my-custom-rpc.com',
-  autoConnect: true
-});
-
-function App() {
-  return (
-    <AppProvider config={config.connectorConfig}>
-      <ArmaProvider
-        config={{
-          network: config.network,
-          rpcUrl: config.rpcUrl,
-          providers: [/* ... */]
-        }}
-        useConnector="auto"
-      >
-        {children}
-      </ArmaProvider>
-    </AppProvider>
-  );
-}
-```
+### Custom Storage (React Native, SSR)
 
-### Custom Storage
+Storage uses nanostores with built-in enhancements that are **automatically applied**:
 
-**Most users don't need to configure storage** - it works automatically with validation, error handling, and SSR fallback.
+- Validation (Solana address format checking)
+- Error handling (catches localStorage quota errors, private browsing)
+- SSR fallback (uses memory storage when localStorage unavailable)
 
-Only customize for:
+**Most users don't need to configure storage.** Only customize for:
 
 - React Native (custom storage backend)
 - Additional validation rules
@@ -759,7 +894,6 @@ import { getDefaultConfig, createEnhancedStorageWallet, EnhancedStorageAdapter }
 
 const config = getDefaultConfig({
     appName: 'My App',
-
     storage: {
         wallet: new EnhancedStorageAdapter(
             createEnhancedStorageWallet({
@@ -768,11 +902,11 @@ const config = getDefaultConfig({
                     return walletName !== null && walletName.length > 0;
                 },
                 onError: error => {
+                    // Custom error tracking
                     Sentry.captureException(error);
                 },
             }),
         ),
-        // account and cluster use defaults if not specified
     },
 });
 ```
@@ -785,7 +919,7 @@ const config = getDefaultConfig({
 
 ```typescript
 // Full library - includes React and headless
-import { ConnectorProvider, useConnector } from '@solana/connector';
+import { ConnectorProvider, useConnector, useAccount } from '@solana/connector';
 ```
 
 ### Headless Export (Framework Agnostic)
@@ -802,427 +936,58 @@ import { ConnectorClient, getDefaultConfig } from '@solana/connector/headless';
 import { useConnector, useAccount } from '@solana/connector/react';
 ```
 
-### Compatibility Layer (NEW!)
-
-```typescript
-// Wallet adapter compatibility bridge
-import { createWalletAdapterCompat } from '@solana/connector/compat';
-```
-
 ---
 
-## Testing
-
-The connector package includes a comprehensive test suite built with Vitest. All tests are located in `src/__tests__/` and co-located with source files.
-
-### Running Tests
-
-```bash
-# Run all tests
-pnpm test
-
-# Run tests in watch mode
-pnpm test:watch
-
-# Run tests with UI
-pnpm test:ui
-
-# Generate coverage report
-pnpm test:coverage
-```
-
-### Test Coverage
-
-The package maintains high test coverage:
-
-- **Lines**: 80%+
-- **Functions**: 80%+
-- **Branches**: 75%+
-- **Statements**: 80%+
-
-### Test Structure
-
-```
-src/
-├── lib/
-│   ├── core/
-│   │   ├── state-manager.ts
-│   │   └── state-manager.test.ts      # Unit tests
-│   └── connection/
-│       ├── connection-manager.ts
-│       └── connection-manager.test.ts # Unit tests
-├── hooks/
-│   ├── use-account.ts
-│   └── use-account.test.tsx           # React hook tests
-└── __tests__/
-    ├── setup.ts                       # Global test setup
-    ├── mocks/                         # Mock implementations
-    │   ├── wallet-standard-mock.ts    # Mock wallets
-    │   ├── storage-mock.ts            # Mock storage
-    │   └── window-mock.ts             # Mock browser APIs
-    ├── fixtures/                      # Test data
-    │   ├── wallets.ts                 # Wallet fixtures
-    │   ├── accounts.ts                # Account fixtures
-    │   └── transactions.ts            # Transaction fixtures
-    ├── utils/                         # Test helpers
-    │   ├── test-helpers.ts            # Common utilities
-    │   ├── react-helpers.tsx          # React test utils
-    │   └── wait-for-state.ts          # State helpers
-    └── integration/                   # Integration tests
-        └── connector-flow.test.ts     # Full workflows
-```
-
-### Writing Tests
-
-Example unit test:
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { StateManager } from './state-manager';
-
-describe('StateManager', () => {
-    it('should update state correctly', () => {
-        const manager = new StateManager(initialState);
-        manager.updateState({ connected: true });
-
-        expect(manager.getSnapshot().connected).toBe(true);
-    });
-});
-```
-
-Example React hook test:
-
-```typescript
-import { renderHook } from '@testing-library/react';
-import { useAccount } from './use-account';
-import { createHookWrapper } from '../__tests__/utils/react-helpers';
-
-describe('useAccount', () => {
-    it('should return account information', () => {
-        const { result } = renderHook(() => useAccount(), {
-            wrapper: createHookWrapper(),
-        });
-
-        expect(result.current.address).toBeDefined();
-    });
-});
-```
-
-### Test Utilities
-
-The package provides comprehensive test utilities:
-
-**Mock Wallets:**
-
-```typescript
-import { createMockPhantomWallet, createMockSolflareWallet } from '../mocks/wallet-standard-mock';
-
-const wallet = createMockPhantomWallet({
-    connectBehavior: 'success', // or 'error', 'timeout'
-});
-```
-
-**Test Fixtures:**
-
-```typescript
-import { createTestAccounts, TEST_ADDRESSES } from '../fixtures/accounts';
-import { createTestWallets } from '../fixtures/wallets';
-
-const accounts = createTestAccounts(3);
-const wallets = createTestWallets();
-```
-
-**Test Helpers:**
-
-```typescript
-import { waitForCondition, createEventCollector } from '../utils/test-helpers';
-
-// Wait for a condition
-await waitForCondition(() => state.connected, { timeout: 5000 });
-
-// Collect events
-const collector = createEventCollector();
-client.on(collector.collect);
-collector.assertEventEmitted('connected');
-```
-
-### Contributing Tests
+## API Reference
 
-All new features and bug fixes should include tests:
+### Hooks
 
-1. Create test file next to source file with `.test.ts` or `.test.tsx` extension
-2. Follow existing patterns in similar test files
-3. Ensure tests pass locally before submitting
-4. Maintain or improve coverage percentage
-
-For detailed testing guidelines, see [Testing Guide](src/__tests__/README.md).
-
----
-
-## Complete API Reference
+| Hook | Description | Returns |
+|------|-------------|---------|
+| `useConnector()` | Main wallet connection hook | `{ wallets, selectedWallet, accounts, connected, connecting, select, disconnect }` |
+| `useAccount()` | Account management hook | `{ address, formatted, copy, copied, accounts, selectAccount }` |
+| `useCluster()` | Network/cluster management hook | `{ cluster, clusters, setCluster, isMainnet, isDevnet, rpcUrl }` |
+| `useWalletInfo()` | Wallet metadata hook | `{ name, icon, wallet, connecting }` |
+| `useTransactionSigner()` | Legacy transaction signer (web3.js) | `{ signer, ready, address, capabilities }` |
+| `useKitTransactionSigner()` | Modern transaction signer (@solana/kit) | `{ signer, ready, address }` |
+| `useBalance()` | SOL balance hook | `{ solBalance, isLoading, refetch }` |
+| `useTokens()` | SPL tokens hook | `{ tokens, isLoading, refetch }` |
+| `useTransactions()` | Transaction history hook | `{ transactions, isLoading, refetch }` |
 
 ### Configuration Functions
 
-#### `getDefaultConfig(options)`
-
-```typescript
-const config = getDefaultConfig({
-  appName: string,                        // Required: App name
-  appUrl?: string,                        // App URL for metadata
-  autoConnect?: boolean,                  // Auto-reconnect (default: true)
-  debug?: boolean,                        // Debug logging
-  network?: 'mainnet' | 'mainnet-beta'    // Initial network (default: mainnet-beta)
-    | 'devnet' | 'testnet' | 'localnet',
-  enableMobile?: boolean,                 // Mobile Wallet Adapter (default: true)
-  storage?: ConnectorConfig['storage'],   // Custom storage adapters
-  clusters?: SolanaCluster[],             // Override default clusters
-  customClusters?: SolanaCluster[],       // Add custom clusters
-  persistClusterSelection?: boolean,      // Persist cluster (default: true)
-  enableErrorBoundary?: boolean,          // Error boundaries (default: true)
-  maxRetries?: number,                    // Retry attempts (default: 3)
-  onError?: (error, errorInfo) => void    // Error handler (NEW!)
-});
-```
-
-### Transaction Signing API (NEW!)
-
-#### `useTransactionSigner()`
-
-React hook for transaction operations.
-
-```typescript
-interface UseTransactionSignerReturn {
-    signer: TransactionSigner | null; // Signer instance
-    ready: boolean; // Whether signer is ready
-    address: string | null; // Current address
-    capabilities: TransactionSignerCapabilities; // What signer can do
-}
-```
-
-#### `createTransactionSigner(config)`
-
-Create a transaction signer (headless).
-
-```typescript
-import { createTransactionSigner } from '@solana/connector/headless';
-
-const signer = createTransactionSigner({
-    wallet: connectedWallet,
-    account: selectedAccount,
-    cluster: currentCluster, // Optional
-});
-```
-
-#### `TransactionSigner` Interface
-
-```typescript
-interface TransactionSigner {
-    readonly address: string;
-
-    signTransaction(tx: any): Promise<any>;
-    signAllTransactions(txs: any[]): Promise<any[]>;
-    signAndSendTransaction(tx: any, options?: SendOptions): Promise<string>;
-    signAndSendTransactions(txs: any[], options?: SendOptions): Promise<string[]>;
-    signMessage?(message: Uint8Array): Promise<Uint8Array>;
-
-    getCapabilities(): TransactionSignerCapabilities;
-}
-```
-
-### Event System API (NEW!)
-
-#### Event Types
-
-```typescript
-type ConnectorEvent =
-    | { type: 'wallet:connected'; wallet: string; account: string; timestamp: string }
-    | { type: 'wallet:disconnected'; timestamp: string }
-    | { type: 'cluster:changed'; cluster: string; previousCluster: string | null; timestamp: string }
-    | { type: 'wallets:detected'; count: number; timestamp: string }
-    | { type: 'connecting'; wallet: string; timestamp: string }
-    | { type: 'connection:failed'; wallet: string; error: string; timestamp: string }
-    | { type: 'error'; error: Error; context: string; timestamp: string };
-```
-
-#### Methods
-
-```typescript
-// Subscribe to events
-const unsubscribe = client.on(event => {
-    console.log('Event:', event.type, event);
-});
-
-// Unsubscribe
-client.off(listener);
-
-// Unsubscribe all
-client.offAll();
-```
-
-### Health Check API (NEW!)
-
-```typescript
-interface ConnectorHealth {
-    initialized: boolean;
-    walletStandardAvailable: boolean;
-    storageAvailable: boolean;
-    walletsDetected: number;
-    errors: string[];
-    connectionState: {
-        connected: boolean;
-        connecting: boolean;
-        hasSelectedWallet: boolean;
-        hasSelectedAccount: boolean;
-    };
-    timestamp: string;
-}
-
-// Get health status
-const health = client.getHealth();
-```
-
-### Connection Pool API (NEW!)
-
-```typescript
-class ConnectionPool {
-    get(cluster: SolanaCluster): ConnectionLike;
-    has(clusterId: string): boolean;
-    clear(clusterId: string): void;
-    clearAll(): void;
-    getStats(): ConnectionPoolStats;
-    resetStats(): void;
-}
-
-// Create pool
-const pool = createConnectionPool(options);
-
-// Get global pool
-const pool = getConnectionPool();
-```
-
-### Wallet Adapter Compat API (NEW!)
-
-```typescript
-// Create wallet-adapter compatible interface
-createWalletAdapterCompat(
-  signer: TransactionSigner | null,
-  options: {
-    disconnect: () => Promise<void>;
-    transformTransaction?: (tx: any) => any;
-    onError?: (error: Error, operation: string) => void;
-  }
-): WalletAdapterCompatible
-
-// React hook version
-useWalletAdapterCompat(
-  signer: TransactionSigner | null,
-  disconnect: () => Promise<void>,
-  options?: Omit<WalletAdapterCompatOptions, 'disconnect'>
-): WalletAdapterCompatible
-
-// Type guard
-isWalletAdapterCompatible(obj: any): obj is WalletAdapterCompatible
-```
-
-### Polyfill API (NEW!)
-
-```typescript
-import {
-    installPolyfills,
-    isPolyfillInstalled,
-    isCryptoAvailable,
-    getPolyfillStatus,
-} from '@solana/connector/headless';
-
-// Install browser polyfills (automatic in React provider)
-installPolyfills();
-
-// Check status
-const installed = isPolyfillInstalled();
-const cryptoAvailable = isCryptoAvailable();
-const status = getPolyfillStatus();
-```
+| Function | Description |
+|----------|-------------|
+| `getDefaultConfig(options)` | Create default connector configuration |
+| `getDefaultMobileConfig(options)` | Create mobile wallet adapter configuration |
+| `createConfig(options)` | Create unified config for ConnectorKit + Armadura |
 
 ### Utility Functions
 
-#### Formatting
+| Function | Description |
+|----------|-------------|
+| `formatAddress(address, options?)` | Format Solana address |
+| `formatSOL(lamports, options?)` | Format SOL amount |
+| `copyAddressToClipboard(address)` | Copy address to clipboard |
+| `getTransactionUrl(cluster, signature)` | Get Solana Explorer transaction URL |
+| `getAddressUrl(cluster, address)` | Get Solana Explorer address URL |
 
-```typescript
-import { formatSOL, formatAddress } from '@solana/connector';
-
-// Format SOL amounts
-formatSOL(1500000000, { decimals: 4 }); // "1.5000 SOL"
-
-// Format addresses
-formatAddress(address, { length: 6 }); // "5Gv8yU...8x3kF"
-
-// Lightweight versions (smaller bundle, no Intl)
-import { formatSOLSimple, formatAddressSimple } from '@solana/connector';
-```
-
-#### Clipboard
-
-```typescript
-import { copyAddressToClipboard, copyToClipboard } from '@solana/connector';
-
-await copyAddressToClipboard(address);
-await copyToClipboard(text);
-```
-
-#### Cluster Utilities
-
-```typescript
-import {
-    getClusterRpcUrl,
-    getClusterExplorerUrl,
-    getTransactionUrl,
-    getAddressUrl,
-    isMainnetCluster,
-    isDevnetCluster,
-} from '@solana/connector';
-
-const rpcUrl = getClusterRpcUrl(cluster);
-const explorerUrl = getClusterExplorerUrl(cluster);
-const txUrl = getTransactionUrl(cluster, signature);
-const addrUrl = getAddressUrl(cluster, address);
-```
+---
 
-### Types
+## Types
 
 ```typescript
 import type {
     // Configuration
     ConnectorConfig,
     DefaultConfigOptions,
-    ExtendedConnectorConfig,
     UnifiedConfig,
-    MobileWalletAdapterConfig,
 
     // State & Info
     ConnectorState,
     ConnectorSnapshot,
     WalletInfo,
     AccountInfo,
-    ConnectorHealth, // NEW!
-
-    // Events
-    ConnectorEvent, // NEW!
-    ConnectorEventListener, // NEW!
-
-    // Transaction Signing
-    TransactionSigner, // NEW!
-    TransactionSignerConfig, // NEW!
-    TransactionSignerCapabilities, // NEW!
-    SignedTransaction, // NEW!
-
-    // Connection Pooling
-    ConnectionLike, // NEW!
-    ConnectionPoolOptions, // NEW!
-    ConnectionPoolStats, // NEW!
-
-    // Wallet Adapter Compat
-    WalletAdapterCompatible, // NEW!
-    WalletAdapterCompatOptions, // NEW!
 
     // Wallet Standard
     Wallet,
@@ -1232,101 +997,17 @@ import type {
     SolanaCluster,
     SolanaClusterId,
 
-    // Storage
-    StorageAdapter,
-
     // Hook Returns
     UseClusterReturn,
     UseAccountReturn,
     UseWalletInfoReturn,
-    UseTransactionSignerReturn, // NEW!
-
-    // Errors
-    WalletError,
+    UseTransactionSignerReturn,
+    UseKitTransactionSignerReturn,
 } from '@solana/connector';
 ```
 
 ---
 
-## Performance
-
-### Bundle Size
-
-| Component            | Size (gzipped) | Tree-Shakeable     |
-| -------------------- | -------------- | ------------------ |
-| **Base Connector**   | ~45KB          | ✅                 |
-| + Polyfills          | +2KB           | ❌ (auto-included) |
-| + Transaction Signer | +3KB           | ✅                 |
-| + Connection Pool    | +1.5KB         | ✅                 |
-| + Debug Panel        | +2KB           | ✅ (dev-only)      |
-| + Event System       | +0.5KB         | ✅                 |
-| + Compat Layer       | +2KB           | ✅                 |
-
-**Total**: ~48-53KB for typical production usage
-
-### Runtime Performance
-
-- **40-60% fewer re-renders** via optimized state updates
-- **Connection pooling** reduces memory usage and initialization overhead
-- **Automatic tree-shaking** excludes unused features
-- **Debug panel** automatically excluded in production builds
-
----
-
-## Browser Compatibility
-
-Enhanced support for:
-
-- ✅ Chrome/Edge 90+
-- ✅ Firefox 88+
-- ✅ Safari 14+
-- ✅ iOS Safari 14+
-- ✅ Chrome Mobile 90+
-- ✅ Samsung Internet 15+
-
-Automatic polyfills ensure compatibility across all environments.
-
----
-
-## Migration from @solana/wallet-adapter
-
-Using the wallet-adapter compatibility bridge for gradual migration:
-
-```typescript
-// Before (wallet-adapter)
-import { useWallet } from '@solana/wallet-adapter-react';
-
-const { publicKey, sendTransaction } = useWallet();
-await sendTransaction(tx, connection);
-
-// After (connector-kit)
-import { useTransactionSigner } from '@solana/connector';
-
-const { signer } = useTransactionSigner();
-await signer.signAndSendTransaction(tx);
-
-// Or use compatibility bridge for existing integrations
-import { createWalletAdapterCompat } from '@solana/connector/compat';
-
-const walletAdapter = createWalletAdapterCompat(signer, { disconnect });
-// Pass walletAdapter to existing wallet-adapter code
-```
-
----
-
-## Examples
-
-Check out the [examples directory](../../examples/react) for:
-
-- **React Example** - Complete wallet connection UI with shadcn/ui
-- **Vite Example** - Lightweight setup with Vite
-- **Transaction Signing** - Full transaction demos
-- **Network Switching** - Cluster/network management
-- **Account Management** - Multi-account support
-- **Mobile Support** - Solana Mobile Wallet Adapter
-
----
-
 ## Development
 
 ### Commands
@@ -1353,9 +1034,6 @@ pnpm test
 # Test in watch mode
 pnpm test:watch
 
-# Test with UI
-pnpm test:ui
-
 # Coverage report
 pnpm test:coverage
 
@@ -1363,65 +1041,17 @@ pnpm test:coverage
 pnpm size
 ```
 
-### Project Structure
-
-```
-packages/connector/
-├── src/
-│   ├── lib/
-│   │   ├── core/              # Core functionality
-│   │   │   ├── state-manager.ts
-│   │   │   ├── event-emitter.ts
-│   │   │   └── debug-metrics.ts
-│   │   ├── connection/        # Connection management
-│   │   │   ├── connection-manager.ts
-│   │   │   └── connection-pool.ts
-│   │   ├── transaction/       # Transaction signing
-│   │   │   ├── transaction-signer.ts
-│   │   │   └── signer-factory.ts
-│   │   └── storage/           # Persistence layer
-│   │       └── enhanced-storage.ts
-│   ├── hooks/                 # React hooks
-│   │   ├── use-connector.ts
-│   │   ├── use-account.ts
-│   │   ├── use-cluster.ts
-│   │   └── use-transaction-signer.ts
-│   ├── components/            # React components
-│   │   └── debug-panel.tsx
-│   ├── compat/                # Wallet adapter compatibility
-│   │   └── wallet-adapter-compat.ts
-│   ├── __tests__/             # Test utilities
-│   │   ├── mocks/
-│   │   ├── fixtures/
-│   │   └── utils/
-│   └── index.ts               # Main exports
-├── tsconfig.json
-├── tsup.config.ts
-├── vitest.config.ts
-└── package.json
-```
-
-### Contributing
-
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Add tests for new functionality
-5. Ensure tests pass (`pnpm test`)
-6. Commit with conventional commits (`feat:`, `fix:`, `docs:`, etc.)
-7. Push to your fork and submit a pull request
-
-For detailed testing guidelines, see [Testing Guide](src/__tests__/README.md).
-
 ---
 
-## Community & Support
+## Examples
 
-- **Questions?** Ask on [Solana Stack Exchange](https://solana.stackexchange.com/) (use the `connectorkit` tag)
-- **Issues?** Report on [GitHub Issues](https://github.com/your-org/connectorkit/issues)
-- **Discussions?** Join [GitHub Discussions](https://github.com/your-org/connectorkit/discussions)
+Check out the [examples directory](../../examples/next-js) for complete working examples:
+
+- **Next.js Example** - Full-featured wallet connection UI with shadcn/ui
+- **Transaction Signing** - Modern and legacy transaction examples
+- **Network Switching** - Cluster/network management
+- **Account Management** - Multi-account support
+- **Mobile Support** - Solana Mobile Wallet Adapter
 
 ---
 
@@ -1439,22 +1069,6 @@ Compatible with all [Wallet Standard](https://github.com/wallet-standard/wallet-
 
 ---
 
-## Other Resources
-
-- [ConnectorKit Documentation](https://connectorkit.dev) - Full documentation site
-- [API Reference](#complete-api-reference) - Complete TypeScript API
-- [Examples](../../examples/react) - Working examples
-- [Wallet Standard Spec](https://github.com/wallet-standard/wallet-standard) - Protocol specification
-- [@solana/connector on NPM](https://www.npmjs.com/package/@solana/connector) - Package page
-
----
-
-## Source
-
-- [GitHub Repository](https://github.com/your-org/connectorkit)
-- [Examples Directory](../../examples)
-- [Package Directory](../../packages/connector)
-
-Built with ❤️ for the Solana ecosystem.
+## License
 
-Licensed under MIT. See [LICENSE](../../LICENSE) for details.
+MIT