@solana/connector 0.1.9 → 0.2.0

package/dist/{standard-shim-CT49DM5l.d.mts → standard-shim-CGB88PPO.d.mts}

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React, { ReactNode, Component, ErrorInfo } from 'react';
-import { w as TransactionActivity, x as TransactionActivityStatus } from './transaction-signer-T-KVQFi8.mjs';
-import { SolanaClusterId, SolanaCluster } from '@wallet-ui/core';
+import React, { ReactNode } from 'react';
+import * as _wallet_standard_base from '@wallet-standard/base';
 import { Wallet, WalletAccount, IdentifierArray } from '@wallet-standard/base';
+import { w as TransactionActivity, x as TransactionActivityStatus } from './transaction-signer-7NaYmP5w.mjs';
+import { SolanaClusterId, SolanaCluster } from '@wallet-ui/core';
 import { Address } from '@solana/addresses';
 import { Signature } from '@solana/keys';
 import { AuthorizationCache, ChainSelector, SolanaMobileWalletAdapterWallet } from '@solana-mobile/wallet-standard-mobile';
@@ -96,10 +97,33 @@ interface EnhancedStorageClusterOptions extends BaseEnhancedStorageOptions<Solan
     validClusters?: SolanaClusterId[];
 }
 /**
- * Options for wallet storage
+ * Options for wallet storage (legacy)
  */
 interface EnhancedStorageWalletOptions extends BaseEnhancedStorageOptions<string | undefined> {
 }
+/**
+ * Persisted wallet state for vNext auto-connect.
+ * Stores connector ID instead of wallet name for stability.
+ */
+interface PersistedWalletState {
+    /** Storage format version for future migrations */
+    version: number;
+    /** Stable connector ID (e.g., 'wallet-standard:phantom') */
+    connectorId: string;
+    /** Last selected account address */
+    lastAccount?: string;
+    /** Whether auto-connect is enabled for this wallet */
+    autoConnect: boolean;
+    /** Timestamp of last connection */
+    lastConnected?: string;
+}
+/**
+ * Options for vNext wallet state storage
+ */
+interface EnhancedStorageWalletStateOptions extends BaseEnhancedStorageOptions<PersistedWalletState | null> {
+    /** Migration handler for legacy wallet name storage */
+    migrateLegacy?: (legacyWalletName: string) => string | null;
+}
 
 /**
  * Account-related types
@@ -117,6 +141,429 @@ interface AccountInfo {
     raw: WalletAccount;
 }
 
+/**
+ * WalletConnect configuration types
+ *
+ * Types for configuring WalletConnect integration with the connector.
+ * WalletConnect uses Solana JSON-RPC methods as documented at:
+ * https://docs.walletconnect.network/wallet-sdk/chain-support/solana
+ */
+/**
+ * WalletConnect app metadata
+ * Required for session establishment with mobile/desktop wallets
+ */
+interface WalletConnectMetadata {
+    /** Application name displayed to the user in the wallet */
+    name: string;
+    /** Brief description of the application */
+    description: string;
+    /** Application URL (used for verification) */
+    url: string;
+    /** Array of icon URLs for the application */
+    icons: string[];
+}
+/**
+ * Configuration for WalletConnect integration
+ *
+ * When enabled, ConnectorKit registers a virtual "WalletConnect" wallet
+ * into the Wallet Standard registry. This wallet proxies all signing
+ * operations through WalletConnect's Solana JSON-RPC methods.
+ *
+ * @example
+ * ```typescript
+ * const config = getDefaultConfig({
+ *   appName: 'My App',
+ *   walletConnect: {
+ *     enabled: true,
+ *     projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID!,
+ *     metadata: {
+ *       name: 'My App',
+ *       description: 'My Solana Application',
+ *       url: 'https://myapp.com',
+ *       icons: ['https://myapp.com/icon.png'],
+ *     },
+ *     onDisplayUri: (uri) => {
+ *       // Show QR code or deep link with this URI
+ *       console.log('WalletConnect URI:', uri);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface WalletConnectConfig {
+    /**
+     * Enable WalletConnect integration.
+     * When true, a "WalletConnect" wallet is registered in the Wallet Standard registry.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * WalletConnect Cloud project ID.
+     * Get one at https://cloud.walletconnect.com/
+     */
+    projectId: string;
+    /**
+     * Application metadata shown to users during connection.
+     */
+    metadata: WalletConnectMetadata;
+    /**
+     * Default Solana chain/cluster for WalletConnect sessions.
+     * Used as fallback if getCurrentChain is not provided.
+     * Uses ConnectorKit's cluster ID format.
+     * @default 'solana:mainnet'
+     */
+    defaultChain?: 'solana:mainnet' | 'solana:devnet' | 'solana:testnet';
+    /**
+     * Callback to get the current chain/cluster dynamically.
+     * When provided, this is called before each request to determine the chain.
+     * This allows WalletConnect to follow the app's cluster selection.
+     *
+     * @returns The current chain ID (e.g., 'solana:mainnet', 'solana:devnet')
+     */
+    getCurrentChain?: () => 'solana:mainnet' | 'solana:devnet' | 'solana:testnet';
+    /**
+     * Callback invoked when WalletConnect needs to display a connection URI.
+     * The app should render this as a QR code or use it for deep linking.
+     *
+     * If not provided, the URI will be logged to console in development.
+     *
+     * @param uri - The WalletConnect pairing URI (starts with "wc:")
+     */
+    onDisplayUri?: (uri: string) => void;
+    /**
+     * Callback invoked when a WalletConnect session is established.
+     */
+    onSessionEstablished?: () => void;
+    /**
+     * Callback invoked when a WalletConnect session is disconnected.
+     */
+    onSessionDisconnected?: () => void;
+    /**
+     * Optional relay URL override.
+     * @default 'wss://relay.walletconnect.org'
+     */
+    relayUrl?: string;
+}
+/**
+ * Internal transport interface for WalletConnect provider
+ * Used by the shim wallet to communicate with WalletConnect
+ */
+interface WalletConnectTransport {
+    /** Establish connection and create/restore session */
+    connect(): Promise<void>;
+    /** Disconnect the current session */
+    disconnect(): Promise<void>;
+    /** Send a JSON-RPC request to the connected wallet */
+    request<T = unknown>(args: {
+        method: string;
+        params: unknown;
+        chainId?: string;
+    }): Promise<T>;
+    /** Check if there's an active session */
+    isConnected(): boolean;
+    /** Get accounts from the current session namespaces (if available) */
+    getSessionAccounts(): string[];
+    /**
+     * Subscribe to session changes (account changes, session updates).
+     * Returns an unsubscribe function.
+     *
+     * @param listener - Called when session changes (new accounts, etc.)
+     * @returns Unsubscribe function
+     */
+    onSessionChanged?(listener: (accounts: string[]) => void): () => void;
+}
+/**
+ * WalletConnect Solana account response
+ * Response format from solana_getAccounts and solana_requestAccounts
+ */
+interface WalletConnectSolanaAccount {
+    /** Base58-encoded public key */
+    pubkey: string;
+}
+/**
+ * WalletConnect sign message params
+ * Parameters for solana_signMessage
+ */
+interface WalletConnectSignMessageParams {
+    /** Base58-encoded message bytes */
+    message: string;
+    /** Base58-encoded public key of the signer */
+    pubkey: string;
+}
+/**
+ * WalletConnect sign message result
+ * Response from solana_signMessage
+ */
+interface WalletConnectSignMessageResult {
+    /** Base58-encoded signature */
+    signature: string;
+}
+/**
+ * WalletConnect sign transaction params
+ * Parameters for solana_signTransaction
+ */
+interface WalletConnectSignTransactionParams {
+    /** Base64-encoded serialized transaction */
+    transaction: string;
+}
+/**
+ * WalletConnect sign transaction result
+ * Response from solana_signTransaction
+ */
+interface WalletConnectSignTransactionResult {
+    /** Base58-encoded signature */
+    signature: string;
+    /** Optional: Base64-encoded signed transaction (if wallet returns full tx) */
+    transaction?: string;
+}
+/**
+ * WalletConnect sign all transactions params
+ * Parameters for solana_signAllTransactions
+ */
+interface WalletConnectSignAllTransactionsParams {
+    /** Array of Base64-encoded serialized transactions */
+    transactions: string[];
+}
+/**
+ * WalletConnect sign all transactions result
+ * Response from solana_signAllTransactions
+ */
+interface WalletConnectSignAllTransactionsResult {
+    /** Array of Base64-encoded signed transactions */
+    transactions: string[];
+}
+/**
+ * WalletConnect sign and send transaction params
+ * Parameters for solana_signAndSendTransaction
+ */
+interface WalletConnectSignAndSendTransactionParams {
+    /** Base64-encoded serialized transaction */
+    transaction: string;
+    /** Optional send options */
+    sendOptions?: {
+        skipPreflight?: boolean;
+        preflightCommitment?: 'processed' | 'confirmed' | 'finalized' | 'recent' | 'single' | 'singleGossip' | 'root' | 'max';
+        maxRetries?: number;
+        minContextSlot?: number;
+    };
+}
+/**
+ * WalletConnect sign and send transaction result
+ * Response from solana_signAndSendTransaction
+ */
+interface WalletConnectSignAndSendTransactionResult {
+    /** Base58-encoded transaction signature (transaction ID) */
+    signature: string;
+}
+
+/**
+ * Wallet Session Types - Framework-kit-inspired connector/session abstraction
+ *
+ * Provides stable connector identity, explicit session management, and
+ * a clear status state machine for wallet connections.
+ */
+
+/**
+ * Branded string type for stable wallet connector identification.
+ * Format: `wallet-standard:{kebab-cased-wallet-name}` or `walletconnect`
+ *
+ * @example
+ * - 'wallet-standard:phantom'
+ * - 'wallet-standard:solflare'
+ * - 'walletconnect'
+ */
+type WalletConnectorId = string & {
+    readonly __brand: 'WalletConnectorId';
+};
+/**
+ * Create a connector ID from a wallet name
+ */
+declare function createConnectorId(walletName: string): WalletConnectorId;
+/**
+ * Check if a string is a valid WalletConnectorId
+ *
+ * Valid formats:
+ * - `wallet-standard:<adapter-name>` - Wallet Standard adapters (e.g., 'wallet-standard:phantom')
+ * - `walletconnect` - WalletConnect connector
+ * - `mwa:<adapter-name>` - Mobile Wallet Adapter (MWA) connectors for mobile wallets
+ *   (e.g., 'mwa:phantom')
+ *
+ * The 'mwa:' prefix identifies connectors using the Solana Mobile Wallet Adapter protocol,
+ * which enables communication with mobile wallet apps on iOS and Android devices.
+ */
+declare function isWalletConnectorId(value: string): value is WalletConnectorId;
+/**
+ * Extract the wallet name from a connector ID (for display purposes)
+ */
+declare function getWalletNameFromConnectorId(connectorId: WalletConnectorId): string;
+/**
+ * Serializable metadata about a wallet connector.
+ * This is what gets stored in state (not the Wallet itself).
+ */
+interface WalletConnectorMetadata {
+    /** Stable connector identifier */
+    id: WalletConnectorId;
+    /** Human-readable display name */
+    name: string;
+    /** Wallet icon (data URI or URL) */
+    icon: string;
+    /** Whether this connector is ready to connect */
+    ready: boolean;
+    /** Supported Solana chains (e.g., 'solana:mainnet', 'solana:devnet') */
+    chains: readonly string[];
+    /** Supported wallet standard features */
+    features: readonly string[];
+}
+/**
+ * Full wallet connector with methods (not stored in state, kept in registry)
+ */
+interface WalletConnector extends WalletConnectorMetadata {
+    /** The underlying Wallet Standard wallet (reference, not serialized) */
+    readonly wallet: Wallet;
+    /**
+     * Connect to the wallet
+     * @param options Connection options
+     * @returns Session with accounts
+     */
+    connect(options?: ConnectOptions): Promise<WalletSession>;
+    /**
+     * Disconnect from the wallet
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if this connector supports a specific feature
+     */
+    supportsFeature(feature: string): boolean;
+}
+/**
+ * Options for connecting to a wallet
+ */
+interface ConnectOptions {
+    /**
+     * Attempt silent connection without user prompt.
+     * If the wallet has previously authorized this app, it may connect
+     * without showing a popup.
+     * @default false
+     */
+    silent?: boolean;
+    /**
+     * If silent connection fails, allow falling back to interactive connection.
+     * @default true (when silent is true)
+     */
+    allowInteractiveFallback?: boolean;
+    /**
+     * Preferred account address to select after connection.
+     * If not available, the first account will be selected.
+     */
+    preferredAccount?: Address;
+}
+/**
+ * Account information within a session
+ */
+interface SessionAccount {
+    /** Account address */
+    address: Address;
+    /** Display label (if provided by wallet) */
+    label?: string;
+    /** Wallet standard account reference */
+    readonly account: WalletAccount;
+}
+/**
+ * Active wallet session with signing capabilities.
+ * Created after successful connection.
+ */
+interface WalletSession {
+    /** Connector that created this session */
+    connectorId: WalletConnectorId;
+    /** All available accounts in this session */
+    accounts: SessionAccount[];
+    /** Currently selected account */
+    selectedAccount: SessionAccount;
+    /**
+     * Subscribe to account changes within the session.
+     * Returns unsubscribe function.
+     */
+    onAccountsChanged(listener: (accounts: SessionAccount[]) => void): () => void;
+    /**
+     * Select a different account within the session
+     */
+    selectAccount(address: Address): void;
+}
+/**
+ * Disconnected state - no wallet connected
+ */
+interface WalletStatusDisconnected {
+    status: 'disconnected';
+}
+/**
+ * Connecting state - connection in progress
+ */
+interface WalletStatusConnecting {
+    status: 'connecting';
+    /** Connector being connected to */
+    connectorId: WalletConnectorId;
+}
+/**
+ * Connected state - wallet successfully connected
+ */
+interface WalletStatusConnected {
+    status: 'connected';
+    /** Active session */
+    session: WalletSession;
+}
+/**
+ * Error state - connection or session error
+ */
+interface WalletStatusError {
+    status: 'error';
+    /** Error that occurred */
+    error: Error;
+    /** Connector that failed (if known) */
+    connectorId?: WalletConnectorId;
+    /** Whether this error is recoverable */
+    recoverable: boolean;
+}
+/**
+ * Union of all wallet status states.
+ * Use discriminated union pattern for type narrowing.
+ *
+ * @example
+ * ```ts
+ * if (wallet.status === 'connected') {
+ *   // TypeScript knows wallet.session exists
+ *   console.log(wallet.session.selectedAccount.address);
+ * }
+ * ```
+ */
+type WalletStatus = WalletStatusDisconnected | WalletStatusConnecting | WalletStatusConnected | WalletStatusError;
+declare function isDisconnected(status: WalletStatus): status is WalletStatusDisconnected;
+declare function isConnecting(status: WalletStatus): status is WalletStatusConnecting;
+declare function isConnected(status: WalletStatus): status is WalletStatusConnected;
+declare function isStatusError(status: WalletStatus): status is WalletStatusError;
+/**
+ * @deprecated Use isStatusError instead. This alias is kept for backward compatibility.
+ */
+declare const isWalletStatusError: typeof isStatusError;
+/**
+ * Initial disconnected wallet status
+ */
+declare const INITIAL_WALLET_STATUS: WalletStatusDisconnected;
+/**
+ * Extract legacy-style state from WalletStatus.
+ * Useful for backwards compatibility during migration.
+ *
+ * @deprecated Use the new WalletStatus discriminated union directly
+ */
+declare function toLegacyWalletState(wallet: WalletStatus): {
+    connected: boolean;
+    connecting: boolean;
+    selectedAccount: Address | null;
+    accounts: Array<{
+        address: Address;
+        label?: string;
+    }>;
+};
+
 /**
  * CoinGecko API configuration for price fetching.
  *
@@ -163,11 +610,46 @@ interface CoinGeckoConfig {
  * Core connector state
  */
 interface ConnectorState {
+    /**
+     * Wallet connection status using state machine pattern.
+     * This is the primary way to check wallet state in vNext.
+     *
+     * @example
+     * ```ts
+     * if (state.wallet.status === 'connected') {
+     *   console.log(state.wallet.session.selectedAccount.address);
+     * }
+     * ```
+     */
+    wallet: WalletStatus;
+    /**
+     * Available wallet connectors with metadata (serializable).
+     * Use ConnectorClient methods to actually connect.
+     */
+    connectors: WalletConnectorMetadata[];
+    /**
+     * @deprecated Use `state.connectors` instead. This includes legacy WalletInfo.
+     */
     wallets: WalletInfo[];
+    /**
+     * @deprecated Use `state.wallet.status === 'connected' && state.wallet.session` instead.
+     */
     selectedWallet: Wallet | null;
+    /**
+     * @deprecated Use `state.wallet.status === 'connected'` instead.
+     */
     connected: boolean;
+    /**
+     * @deprecated Use `state.wallet.status === 'connecting'` instead.
+     */
     connecting: boolean;
+    /**
+     * @deprecated Use `state.wallet.status === 'connected' && state.wallet.session.accounts` instead.
+     */
     accounts: AccountInfo[];
+    /**
+     * @deprecated Use `state.wallet.status === 'connected' && state.wallet.session.selectedAccount.address` instead.
+     */
     selectedAccount: Address | null;
     cluster: SolanaCluster | null;
     clusters: SolanaCluster[];
@@ -212,6 +694,12 @@ interface ConnectorConfig {
      * Configure API key for higher rate limits and retry behavior for 429 responses.
      */
     coingecko?: CoinGeckoConfig;
+    /**
+     * WalletConnect configuration for connecting via QR code / deep link.
+     * When enabled, a "WalletConnect" wallet is registered in the Wallet Standard registry.
+     * @see https://docs.walletconnect.network/wallet-sdk/chain-support/solana
+     */
+    walletConnect?: WalletConnectConfig;
 }
 /**
  * Health check information for connector diagnostics
@@ -363,9 +851,38 @@ declare class ConnectorClient {
     private healthMonitor;
     private initialized;
     private config;
+    private walletConnectRegistration;
     constructor(config?: ConnectorConfig);
     private initialize;
+    /**
+     * Initialize WalletConnect integration
+     * Dynamically imports and registers the WalletConnect wallet
+     */
+    private initializeWalletConnect;
+    /**
+     * Connect to a wallet using its stable connector ID.
+     * This is the recommended way to connect in vNext.
+     *
+     * @param connectorId - Stable connector identifier
+     * @param options - Connection options (silent mode, preferred account, etc.)
+     */
+    connectWallet(connectorId: WalletConnectorId, options?: ConnectOptions): Promise<void>;
+    /**
+     * Disconnect the current wallet session.
+     * This is the vNext equivalent of disconnect().
+     */
+    disconnectWallet(): Promise<void>;
+    /**
+     * Get a connector by its ID (for advanced use cases).
+     */
+    getConnector(connectorId: WalletConnectorId): _wallet_standard_base.Wallet | undefined;
+    /**
+     * @deprecated Use `connectWallet(connectorId)` instead.
+     */
     select(walletName: string): Promise<void>;
+    /**
+     * @deprecated Use `disconnectWallet()` instead.
+     */
     disconnect(): Promise<void>;
     selectAccount(address: string): Promise<void>;
     setCluster(clusterId: SolanaClusterId): Promise<void>;
@@ -441,6 +958,62 @@ interface DefaultConfigOptions {
      * @see https://docs.coingecko.com/reference/introduction for rate limit details
      */
     coingecko?: CoinGeckoConfig;
+    /**
+     * WalletConnect configuration for connecting via QR code / deep link.
+     * When enabled, a "WalletConnect" wallet appears in the wallet list.
+     *
+     * Can be:
+     * - `true` to enable with auto-detected project ID from NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID env var
+     * - An object with optional overrides (projectId, metadata, etc.)
+     * - `undefined` or `false` to disable
+     *
+     * When using `true` or minimal config, the following are auto-configured:
+     * - `projectId`: Read from NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID
+     * - `metadata.name`: Uses appName
+     * - `metadata.url`: Uses appUrl or window.location.origin
+     * - `metadata.description`: Auto-generated from appName
+     * - `metadata.icons`: Uses appUrl/icon.svg
+     * - `getCurrentChain`: Auto-reads from cluster storage
+     * - `onDisplayUri/onSessionEstablished/onSessionDisconnected`: Auto-wired by AppProvider
+     *
+     * @example
+     * ```ts
+     * // Simplest - just enable it (reads project ID from env)
+     * getDefaultConfig({ appName: 'My App', walletConnect: true })
+     *
+     * // With explicit project ID
+     * getDefaultConfig({
+     *   appName: 'My App',
+     *   walletConnect: { projectId: 'my-project-id' }
+     * })
+     * ```
+     *
+     * @see https://docs.walletconnect.network/wallet-sdk/chain-support/solana
+     */
+    walletConnect?: boolean | SimplifiedWalletConnectConfig;
+}
+/**
+ * Simplified WalletConnect configuration
+ * Most fields are auto-generated from appName/appUrl if not provided
+ */
+interface SimplifiedWalletConnectConfig {
+    /**
+     * WalletConnect Cloud project ID.
+     * If not provided, reads from NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID env var.
+     */
+    projectId?: string;
+    /**
+     * Optional metadata overrides. Merged with auto-generated metadata.
+     */
+    metadata?: Partial<WalletConnectConfig['metadata']>;
+    /**
+     * Default chain. Defaults to 'solana:mainnet'.
+     */
+    defaultChain?: WalletConnectConfig['defaultChain'];
+    /**
+     * Optional relay URL override.
+     */
+    relayUrl?: string;
 }
 /** Extended ConnectorConfig with app metadata */
 interface ExtendedConnectorConfig extends ConnectorConfig {
@@ -499,7 +1072,17 @@ declare function getDefaultMobileConfig(options: {
     cluster: "devnet" | "mainnet" | "testnet" | "mainnet-beta";
 };
 
-/** Configuration for registerMwa - defined locally as the package doesn't export this type */
+/**
+ * Mobile Wallet Adapter Configuration Types
+ *
+ * These types are shared between headless and React implementations.
+ * They do NOT import React or any TSX modules.
+ */
+
+/**
+ * Internal configuration used by registerMwa.
+ * Defined here as the package doesn't export this type.
+ */
 interface RegisterMwaConfig {
     appIdentity: {
         name: string;
@@ -512,28 +1095,70 @@ interface RegisterMwaConfig {
     remoteHostAuthority?: string;
     onWalletNotFound: (mobileWalletAdapter: SolanaMobileWalletAdapterWallet) => Promise<void>;
 }
-declare global {
-    interface Window {
-        __connectorClient?: ConnectorClient;
-    }
-}
-type ConnectorSnapshot = ReturnType<ConnectorClient['getSnapshot']> & {
-    select: (walletName: string) => Promise<void>;
-    disconnect: () => Promise<void>;
-    selectAccount: (address: string) => Promise<void>;
-};
+/**
+ * Configuration options for Mobile Wallet Adapter integration.
+ * Used to configure mobile wallet support in ConnectorProvider.
+ */
 interface MobileWalletAdapterConfig {
+    /** Application identity shown to users during authorization */
     appIdentity: {
+        /** Display name of the application */
         name: string;
+        /** URI of the application (optional) */
         uri?: string;
+        /** Icon URL of the application (optional) */
         icon?: string;
     };
+    /** Remote host authority for remote connections (optional) */
     remoteHostAuthority?: string;
+    /** Solana chains to support (defaults to mainnet, devnet, testnet) */
     chains?: RegisterMwaConfig['chains'];
+    /** Authorization cache implementation (optional, uses default if not provided) */
     authorizationCache?: AuthorizationCache;
+    /** Chain selector implementation (optional, uses default if not provided) */
     chainSelector?: ChainSelector;
+    /** Handler called when wallet app is not found (optional, uses default if not provided) */
     onWalletNotFound?: (wallet: SolanaMobileWalletAdapterWallet) => Promise<void>;
 }
+
+declare global {
+    interface Window {
+        __connectorClient?: ConnectorClient;
+    }
+}
+type ConnectorSnapshot = ReturnType<ConnectorClient['getSnapshot']> & {
+    /** @deprecated Use `connectWallet(connectorId)` instead */
+    select: (walletName: string) => Promise<void>;
+    /** @deprecated Use `disconnectWallet()` instead */
+    disconnect: () => Promise<void>;
+    selectAccount: (address: string) => Promise<void>;
+    /** WalletConnect URI for QR code display (null when not connecting via WalletConnect) */
+    walletConnectUri: string | null;
+    /** Clear the WalletConnect URI (call when modal closes or connection completes) */
+    clearWalletConnectUri: () => void;
+    /** Connect to a wallet by connector ID (vNext) */
+    connectWallet: (connectorId: WalletConnectorId, options?: ConnectOptions) => Promise<void>;
+    /** Disconnect the current wallet session (vNext) */
+    disconnectWallet: () => Promise<void>;
+    /** Full wallet status object (discriminated union) */
+    walletStatus: WalletStatus;
+    /** Whether a wallet is connected */
+    isConnected: boolean;
+    /** Whether a wallet connection is in progress */
+    isConnecting: boolean;
+    /** Whether an error occurred */
+    isError: boolean;
+    /** Error object if status is 'error', otherwise null */
+    walletError: Error | null;
+    /** Currently selected account address (null if not connected) */
+    account: Address | null;
+    /** All available accounts in the session (empty if not connected) */
+    sessionAccounts: SessionAccount[];
+    /** Connected connector ID (null if not connected) */
+    connectorId: WalletConnectorId | null;
+    /** Resolved connector metadata for the connected wallet (null if not connected) */
+    connector: WalletConnectorMetadata | null;
+};
 declare function ConnectorProvider({ children, config, mobile, }: {
     children: ReactNode;
     config?: ExtendedConnectorConfig;
@@ -542,48 +1167,44 @@ declare function ConnectorProvider({ children, config, mobile, }: {
 declare function useConnector(): ConnectorSnapshot;
 declare function useConnectorClient(): ConnectorClient | null;
 
-declare enum WalletErrorType {
-    CONNECTION_FAILED = "CONNECTION_FAILED",
-    TRANSACTION_FAILED = "TRANSACTION_FAILED",
-    NETWORK_ERROR = "NETWORK_ERROR",
-    WALLET_NOT_FOUND = "WALLET_NOT_FOUND",
-    USER_REJECTED = "USER_REJECTED",
-    INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
-    UNKNOWN_ERROR = "UNKNOWN_ERROR"
-}
+/**
+ * Wallet Error Types - Framework-agnostic error definitions
+ *
+ * These types are shared between headless and React implementations.
+ * They do NOT import React or any TSX modules.
+ */
+/**
+ * Error types specific to wallet connections.
+ * Used by error boundaries and headless error handling.
+ */
+declare const WalletErrorType: {
+    readonly CONNECTION_FAILED: "CONNECTION_FAILED";
+    readonly TRANSACTION_FAILED: "TRANSACTION_FAILED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly WALLET_NOT_FOUND: "WALLET_NOT_FOUND";
+    readonly USER_REJECTED: "USER_REJECTED";
+    readonly INSUFFICIENT_FUNDS: "INSUFFICIENT_FUNDS";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+type WalletErrorType = (typeof WalletErrorType)[keyof typeof WalletErrorType];
+/**
+ * Extended error interface for wallet-specific errors.
+ * Extends the standard Error with wallet context.
+ */
 interface WalletError extends Error {
     type: WalletErrorType;
     recoverable: boolean;
     context?: Record<string, unknown>;
     retryAction?: () => Promise<void>;
 }
-interface ErrorBoundaryState {
-    hasError: boolean;
-    error: Error | null;
-    errorInfo: ErrorInfo | null;
-    errorId: string;
-    retryCount: number;
-}
-interface ErrorBoundaryProps {
-    children: ReactNode;
-    fallback?: (error: WalletError, retry: () => void) => ReactNode;
-    onError?: (error: Error, errorInfo: ErrorInfo) => void;
-    maxRetries?: number;
-    enableRecovery?: boolean;
-}
-declare class ConnectorErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
-    private retryTimeouts;
-    constructor(props: ErrorBoundaryProps);
-    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
-    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
-    componentWillUnmount(): void;
-    retry: () => void;
-    render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
-}
-declare function withErrorBoundary<P extends object>(Component: React.ComponentType<P>, errorBoundaryProps?: Omit<ErrorBoundaryProps, 'children'>): {
-    (props: P): react_jsx_runtime.JSX.Element;
-    displayName: string;
-};
+/**
+ * Type guard to check if an error is a WalletError
+ */
+declare function isWalletError(error: unknown): error is WalletError;
+/**
+ * Create a WalletError from a standard Error
+ */
+declare function createWalletError(error: Error, type: WalletErrorType, recoverable: boolean, context?: Record<string, unknown>): WalletError;
 
 /**
  * @solana/connector - Cluster utilities
@@ -953,4 +1574,4 @@ declare const ready: Promise<void>;
  */
 declare function getWalletsRegistry(): WalletsRegistry;
 
-export { getClusterExplorerUrl as $, type AccountInfo as A, type CoinGeckoConfig as B, ConnectorProvider as C, type DefaultConfigOptions as D, type ExtendedConnectorConfig as E, type ConnectorHealth as F, type ConnectorDebugMetrics as G, type ConnectorDebugState as H, type ConnectorEvent as I, type ConnectorEventListener as J, type StorageAdapter as K, type Listener as L, type MobileWalletAdapterConfig as M, type StorageOptions as N, type EnhancedStorageAccountOptions as O, type EnhancedStorageClusterOptions as P, type EnhancedStorageWalletOptions as Q, ClipboardErrorType as R, type SolanaClusterMoniker as S, type ClipboardResult as T, type CopyOptions as U, isClipboardAvailable as V, type WalletInfo as W, copyToClipboard as X, copyAddressToClipboard as Y, copySignatureToClipboard as Z, getClusterRpcUrl as _, useConnectorClient as a, getTransactionUrl as a0, getAddressUrl as a1, getTokenUrl as a2, getBlockUrl as a3, isMainnetCluster as a4, isDevnetCluster as a5, isTestnetCluster as a6, isLocalCluster as a7, getClusterName as a8, getClusterType as a9, getClusterChainId as aa, getChainIdForWalletStandard as ab, ConnectorErrorBoundary as b, type ConnectorSnapshot as c, type ConnectorConfig as d, type ConnectorState as e, type WalletStandardWallet as f, type WalletStandardAccount as g, type ClusterType as h, ConnectorClient as i, getDefaultConfig as j, getDefaultMobileConfig as k, getWalletsRegistry as l, WalletErrorType as m, type WalletError as n, getPublicSolanaRpcUrl as o, createSolanaClient as p, type ModifiedClusterUrl as q, ready as r, type SolanaClient as s, type CreateSolanaClientArgs as t, useConnector as u, type WalletName as v, withErrorBoundary as w, type AccountAddress as x, isWalletName as y, isAccountAddress as z };
+export { type WalletConnectMetadata as $, type AccountInfo as A, isWalletStatusError as B, ConnectorProvider as C, type DefaultConfigOptions as D, type ExtendedConnectorConfig as E, toLegacyWalletState as F, type WalletConnector as G, type WalletStatusDisconnected as H, INITIAL_WALLET_STATUS as I, type WalletStatusConnecting as J, type WalletStatusConnected as K, type WalletStatusError as L, type MobileWalletAdapterConfig as M, WalletErrorType as N, isWalletError as O, createWalletError as P, type WalletError as Q, type RegisterMwaConfig as R, type SimplifiedWalletConnectConfig as S, getPublicSolanaRpcUrl as T, createSolanaClient as U, type SolanaClusterMoniker as V, type WalletInfo as W, type ModifiedClusterUrl as X, type SolanaClient as Y, type CreateSolanaClientArgs as Z, type WalletConnectConfig as _, useConnectorClient as a, type WalletConnectTransport as a0, type WalletName as a1, type AccountAddress as a2, isWalletName as a3, isAccountAddress as a4, type CoinGeckoConfig as a5, type ConnectorHealth as a6, type ConnectorDebugMetrics as a7, type ConnectorDebugState as a8, type Listener as a9, getClusterExplorerUrl as aA, getTransactionUrl as aB, getAddressUrl as aC, getTokenUrl as aD, getBlockUrl as aE, isMainnetCluster as aF, isDevnetCluster as aG, isTestnetCluster as aH, isLocalCluster as aI, getClusterName as aJ, getClusterType as aK, getClusterChainId as aL, getChainIdForWalletStandard as aM, type ConnectorEvent as aa, type ConnectorEventListener as ab, type StorageAdapter as ac, type StorageOptions as ad, type EnhancedStorageAccountOptions as ae, type EnhancedStorageClusterOptions as af, type EnhancedStorageWalletOptions as ag, type EnhancedStorageWalletStateOptions as ah, type PersistedWalletState as ai, type WalletConnectSolanaAccount as aj, type WalletConnectSignMessageParams as ak, type WalletConnectSignMessageResult as al, type WalletConnectSignTransactionParams as am, type WalletConnectSignTransactionResult as an, type WalletConnectSignAllTransactionsParams as ao, type WalletConnectSignAllTransactionsResult as ap, type WalletConnectSignAndSendTransactionParams as aq, type WalletConnectSignAndSendTransactionResult as ar, ClipboardErrorType as as, type ClipboardResult as at, type CopyOptions as au, isClipboardAvailable as av, copyToClipboard as aw, copyAddressToClipboard as ax, copySignatureToClipboard as ay, getClusterRpcUrl as az, getDefaultMobileConfig as b, type ConnectorSnapshot as c, type ConnectorConfig as d, type ConnectorState as e, type WalletStandardWallet as f, getDefaultConfig as g, type WalletStandardAccount as h, type WalletConnectorId as i, type WalletConnectorMetadata as j, type WalletSession as k, type WalletStatus as l, type SessionAccount as m, type ConnectOptions as n, createConnectorId as o, isWalletConnectorId as p, isConnected as q, isConnecting as r, isDisconnected as s, type ClusterType as t, useConnector as u, ConnectorClient as v, getWalletsRegistry as w, ready as x, getWalletNameFromConnectorId as y, isStatusError as z };