@phantom/react-sdk 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -41,7 +41,7 @@ function App() {
   return (
     <PhantomProvider
       config={{
-        providerType: "injected", // Uses Phantom browser extension
+        providers: ["injected"], // Only allow Phantom browser extension
         addressTypes: [AddressType.solana, AddressType.ethereum],
       }}
     >
@@ -52,11 +52,11 @@ function App() {
 
 function WalletComponent() {
   const { connect, isConnecting } = useConnect();
-  const solana = useSolana();
-  const ethereum = useEthereum();
+  const { solana } = useSolana();
+  const { ethereum } = useEthereum();
 
   const handleConnect = async () => {
-    const { addresses } = await connect();
+    const { addresses } = await connect({ provider: "injected" });
     console.log("Connected addresses:", addresses);
   };
 
@@ -83,7 +83,7 @@ function WalletComponent() {
 }
 ```
 
-### Embedded Wallet Setup
+### Multiple Authentication Methods
 
 ```tsx
 import { PhantomProvider } from "@phantom/react-sdk";
@@ -93,8 +93,8 @@ function App() {
   return (
     <PhantomProvider
       config={{
-        providerType: "embedded",
-        appId: "your-app-id", // Get your app ID from phantom.com/portal
+        providers: ["google", "apple", "phantom", "injected"], // Allow all auth methods
+        appId: "your-app-id", // Get your app ID from phantom.com/portal (required for embedded providers)
         addressTypes: [AddressType.solana, AddressType.ethereum],
       }}
     >
@@ -104,6 +104,354 @@ function App() {
 }
 ```
 
+## Connection Modal
+
+The SDK includes a built-in connection modal UI that provides a user-friendly interface for connecting to Phantom. The modal supports multiple connection methods (Google, Apple, Phantom Login, browser extension) and handles all connection logic automatically.
+
+### Using the Modal
+
+To use the modal, pass a `theme` prop to `PhantomProvider` and use the `useModal()` hook to control visibility:
+
+```tsx
+import { PhantomProvider, useModal, darkTheme, usePhantom } from "@phantom/react-sdk";
+import { AddressType } from "@phantom/browser-sdk";
+
+function App() {
+  return (
+    <PhantomProvider
+      config={{
+        providers: ["google", "apple", "phantom", "injected"],
+        appId: "your-app-id",
+        addressTypes: [AddressType.solana, AddressType.ethereum],
+      }}
+      theme={darkTheme}
+      appIcon="https://your-app.com/icon.png"
+      appName="Your App Name"
+    >
+      <WalletComponent />
+    </PhantomProvider>
+  );
+}
+
+function WalletComponent() {
+  const { open, close, isOpened } = useModal();
+  const { isConnected, user } = usePhantom();
+
+  if (isConnected) {
+    return (
+      <div>
+        <p>Connected as {user?.email || "Unknown"}</p>
+      </div>
+    );
+  }
+
+  return <button onClick={open}>Connect Wallet</button>;
+}
+```
+
+**Modal Features:**
+
+- **Multiple Auth Providers**: Google, Apple, Phantom Login, browser extension
+- **Automatic Provider Detection**: Shows browser extension option when Phantom is installed
+- **Mobile Support**: Displays deeplink option for Phantom mobile app on mobile devices
+- **Error Handling**: Clear error messages displayed in the modal
+- **Loading States**: Visual feedback during connection attempts
+- **Responsive Design**: Optimized for both mobile and desktop
+
+### useModal Hook
+
+Control the connection modal visibility:
+
+```tsx
+import { useModal } from "@phantom/react-sdk";
+
+function ConnectButton() {
+  const { open, close, isOpened } = useModal();
+
+  return (
+    <div>
+      <button onClick={open}>Open Modal</button>
+      <button onClick={close}>Close Modal</button>
+      <p>Modal is {isOpened ? "open" : "closed"}</p>
+    </div>
+  );
+}
+```
+
+**Returns:**
+
+- `open()` - Function to open the modal
+- `close()` - Function to close the modal
+- `isOpened` - Boolean indicating if modal is currently visible
+
+### ConnectButton Component
+
+A ready-to-use button component that handles the complete connection flow. When disconnected, it shows a "Connect Wallet" button that opens the connection modal. When connected, it displays the truncated wallet address and opens the wallet management modal on click.
+
+```tsx
+import { ConnectButton, AddressType } from "@phantom/react-sdk";
+
+function Header() {
+  return (
+    <div>
+      {/* Default: Shows first available address */}
+      <ConnectButton />
+
+      {/* Show specific address type */}
+      <ConnectButton addressType={AddressType.solana} />
+      <ConnectButton addressType={AddressType.ethereum} />
+
+      {/* Full width button */}
+      <ConnectButton fullWidth />
+    </div>
+  );
+}
+```
+
+**Props:**
+
+- `addressType?: AddressType` - Specify which address type to display when connected (e.g., `AddressType.solana`, `AddressType.ethereum`). If not specified, shows the first available address.
+- `fullWidth?: boolean` - Whether the button should take full width of its container. Default: `false`
+
+**Features:**
+
+- **When disconnected**: Opens connection modal with auth provider options (Google, Apple, Phantom Login, browser extension)
+- **When connected**: Displays truncated address (e.g., "5Gv8r2...k3Hn") and opens wallet management modal on click
+- **Wallet modal**: Shows all connected addresses and provides a disconnect button
+- Uses theme styling for consistent appearance
+- Fully clickable in both states
+
+### ConnectBox Component
+
+An inline embedded component that displays the connection UI directly in your page layout (without a modal backdrop). Perfect for auth callback pages or when you want a more integrated connection experience. The component automatically handles all connection states including loading, error, and success during the auth callback flow.
+
+```tsx
+import { ConnectBox } from "@phantom/react-sdk";
+
+function AuthCallbackPage() {
+  return (
+    <div>
+      <h1>Connecting to Phantom...</h1>
+      <ConnectBox />
+    </div>
+  );
+}
+```
+
+**Props:**
+
+- `maxWidth?: string | number` - Maximum width of the box. Can be a string (e.g., `"500px"`) or number (e.g., `500`). Default: `"350px"`
+- `transparent?: boolean` - When `true`, removes background, border, and shadow for a transparent appearance. Default: `false`
+- `appIcon?: string` - URL to your app icon (optional, can also be set via `PhantomProvider`)
+- `appName?: string` - Your app name (optional, can also be set via `PhantomProvider`)
+
+**Usage Examples:**
+
+```tsx
+import { ConnectBox } from "@phantom/react-sdk";
+
+// Default usage
+<ConnectBox />
+
+// Custom width
+<ConnectBox maxWidth="500px" />
+
+// Transparent (no background/border)
+<ConnectBox transparent />
+
+// Custom width with transparent
+<ConnectBox maxWidth={600} transparent />
+```
+
+**Features:**
+
+- **Inline embedded**: Renders directly in page flow (not as a floating modal)
+- **Auto state management**: Automatically shows connection/login UI when disconnected, wallet info when connected
+- **Auth callback support**: Handles loading and error states during OAuth callback flows
+- **No close button**: Designed for embedded use cases where users shouldn't dismiss the UI
+- **Theme-aware**: Uses your configured theme for consistent styling
+- **Responsive**: Adapts to mobile and desktop layouts
+
+**Use Cases:**
+
+- Auth callback pages (e.g., `/auth/callback`) where users return from OAuth providers
+- Embedded wallet connection flows in your app's layout
+- Custom connection pages where you want full control over the page design
+
+### Handling Auth Callback Pages
+
+When using embedded authentication providers (Google, Apple, Phantom Login, etc.), users are redirected to your app's callback URL after authentication. The SDK automatically handles the callback and completes the connection. Here's how to build a callback page if you're not using `ConnectBox`:
+
+**Basic Auth Callback Page:**
+
+```tsx
+import { usePhantom, useConnect, useAccounts } from "@phantom/react-sdk";
+import { useNavigate } from "react-router-dom"; // or your router
+
+function AuthCallbackPage() {
+  const navigate = useNavigate();
+  const { isConnected } = usePhantom();
+  const { isConnecting, error: connectError } = useConnect();
+  const addresses = useAccounts();
+
+  const handleGoHome = () => {
+    navigate("/");
+  };
+
+  // Loading state - SDK is processing the callback
+  if (isConnecting) {
+    return (
+      <div>
+        <h1>Connecting to wallet...</h1>
+        <p>Please wait while we complete your authentication.</p>
+      </div>
+    );
+  }
+
+  // Success state - connection completed
+  if (isConnected && addresses && addresses.length > 0) {
+    return (
+      <div>
+        <h1>Authentication Successful</h1>
+        <p>You are now connected to your wallet.</p>
+        <div>
+          <h2>Addresses:</h2>
+          {addresses.map((addr, index) => (
+            <div key={index}>
+              <strong>{addr.addressType}:</strong> {addr.address}
+            </div>
+          ))}
+        </div>
+        <button onClick={handleGoHome}>Go to Main App</button>
+      </div>
+    );
+  }
+
+  // Error state - connection failed
+  if (connectError) {
+    return (
+      <div>
+        <h1>Authentication Failed</h1>
+        <p>{connectError.message || "An unknown error occurred during authentication."}</p>
+        <div>
+          <button onClick={handleGoHome}>Go to Main App</button>
+        </div>
+      </div>
+    );
+  }
+
+  // Default state (shouldn't normally reach here)
+  return (
+    <div>
+      <h1>Processing authentication...</h1>
+    </div>
+  );
+}
+```
+
+**Key Points:**
+
+- The SDK's `autoConnect()` automatically processes the callback URL parameters when the page loads
+- Use `useConnect()` to access `isConnecting` and `error` states during the callback flow
+- Use `usePhantom()` to check `isConnected` status
+- Use `useAccounts()` to get connected wallet addresses
+- The connection state will automatically update as the SDK processes the callback
+- You can monitor `connectError` to handle authentication failures
+
+**Router Setup:**
+
+Make sure your callback route is configured in your router:
+
+```tsx
+import { Routes, Route } from "react-router-dom";
+import { PhantomProvider } from "@phantom/react-sdk";
+
+function App() {
+  return (
+    <PhantomProvider config={config} theme={darkTheme}>
+      <Routes>
+        <Route path="/auth/callback" element={<AuthCallbackPage />} />
+        <Route path="/" element={<MainApp />} />
+      </Routes>
+    </PhantomProvider>
+  );
+}
+```
+
+**Note:** For a simpler implementation, consider using the `ConnectBox` component which handles all these states automatically.
+
+## Theming
+
+Customize the modal appearance by passing a theme object to the `PhantomProvider`. The SDK includes two built-in themes: `darkTheme` (default) and `lightTheme`.
+
+### Using Built-in Themes
+
+```tsx
+import { PhantomProvider, darkTheme, lightTheme } from "@phantom/react-sdk";
+
+// Use dark theme (default)
+<PhantomProvider config={config} theme={darkTheme}>
+  <App />
+</PhantomProvider>
+
+// Use light theme
+<PhantomProvider config={config} theme={lightTheme}>
+  <App />
+</PhantomProvider>
+```
+
+### Custom Theme
+
+You can pass a partial theme object to customize specific properties:
+
+```tsx
+import { PhantomProvider } from "@phantom/react-sdk";
+
+const customTheme = {
+  background: "#1a1a1a",
+  text: "#ffffff",
+  secondary: "#98979C",
+  brand: "#ab9ff2",
+  error: "#ff4444",
+  success: "#00ff00",
+  borderRadius: "16px",
+  overlay: "rgba(0, 0, 0, 0.8)",
+};
+
+<PhantomProvider config={config} theme={customTheme} appIcon="https://your-app.com/icon.png" appName="Your App">
+  <App />
+</PhantomProvider>;
+```
+
+### Theme Properties
+
+| Property       | Type     | Description                                               |
+| -------------- | -------- | --------------------------------------------------------- |
+| `background`   | `string` | Background color for modal                                |
+| `text`         | `string` | Primary text color                                        |
+| `secondary`    | `string` | Secondary color for text, borders, dividers (must be hex) |
+| `brand`        | `string` | Brand/primary action color                                |
+| `error`        | `string` | Error state color                                         |
+| `success`      | `string` | Success state color                                       |
+| `borderRadius` | `string` | Border radius for buttons and modal                       |
+| `overlay`      | `string` | Overlay background color (with opacity)                   |
+
+**Note:** The `secondary` color must be a hex color value (e.g., `#98979C`) as it's used to derive auxiliary colors with opacity.
+
+### Accessing Theme in Custom Components
+
+If you need to access the current theme in your own components, use the `useTheme()` hook:
+
+```tsx
+import { useTheme } from "@phantom/react-sdk";
+
+function CustomComponent() {
+  const theme = useTheme();
+
+  return <div style={{ backgroundColor: theme.background, color: theme.text }}>Themed content</div>;
+}
+```
+
 ## Connection Flow
 
 The React SDK follows a clear connection pattern:
@@ -115,12 +463,12 @@ The React SDK follows a clear connection pattern:
 ```tsx
 function WalletExample() {
   const { connect } = useConnect();
-  const solana = useSolana();
-  const ethereum = useEthereum();
+  const { solana } = useSolana();
+  const { ethereum } = useEthereum();
 
-  // 1. Connect first
+  // 1. Connect first (provider parameter is required)
   const handleConnect = async () => {
-    await connect();
+    await connect({ provider: "injected" });
   };
 
   // 2. Then use chain-specific operations
@@ -136,39 +484,94 @@ function WalletExample() {
 
 ### Connection Options
 
-For embedded user-wallets, you can specify authentication providers:
+The `connect()` method requires a `provider` parameter and automatically switches between providers based on the authentication method you specify:
 
 ```tsx
 const { connect } = useConnect();
 
-// Default: Show provider selection screen
-await connect();
+// Connect with injected provider (Phantom extension)
+// Automatically switches to injected provider if not already using it
+await connect({
+  provider: "injected",
+});
+
+// Connect with Google authentication (embedded provider)
+// Automatically switches to embedded provider if not already using it
+await connect({
+  provider: "google",
+});
+
+// Connect with Apple authentication (embedded provider)
+// Automatically switches to embedded provider if not already using it
+await connect({
+  provider: "apple",
+});
 
-// Google authentication (skips provider selection)
+// Connect with Phantom authentication (embedded provider)
+// Uses Phantom extension or mobile app for authentication
+// Automatically switches to embedded provider if not already using it
 await connect({
-  authOptions: {
-    provider: "google",
-  },
+  provider: "phantom",
 });
 
-// Apple authentication (skips provider selection)
+// Connect with JWT authentication (embedded provider)
 await connect({
-  authOptions: {
-    provider: "apple",
-  },
+  provider: "jwt",
+  jwtToken: "your-jwt-token",
 });
 ```
 
-## Provider Types
+## SDK Initialization
+
+The SDK provides an `isLoading` state to track when initialization and autoconnect are in progress. This is useful for showing loading states before your app is ready.
+
+```tsx
+import { useConnect, usePhantom } from "@phantom/react-sdk";
+
+function App() {
+  const { isLoading } = usePhantom();
+  const { connect } = useConnect();
+
+  // Show loading state while SDK initializes
+  if (isLoading) {
+    return (
+      <div>
+        <h1>Initializing Phantom SDK...</h1>
+        <p>Please wait...</p>
+      </div>
+    );
+  }
+
+  // SDK is ready
+  return (
+    <div>
+      <h1>Welcome!</h1>
+      <button onClick={() => connect({ provider: "injected" })}>Connect Wallet</button>
+    </div>
+  );
+}
+```
+
+## Authentication Providers
+
+The SDK supports multiple authentication providers that you configure via the `providers` array:
+
+### Available Providers
+
+- **`"injected"`** - Phantom browser extension
+- **`"google"`** - Google OAuth
+- **`"apple"`** - Apple ID
+- **`"phantom"`** - Phantom Login
+- **`"deeplink"`** - Deeplink to Phantom mobile app (only renders on mobile devices)
 
-### Injected Provider
+### Configuration Examples
 
-Uses the Phantom browser extension installed by the user.
+**Browser Extension Only**
 
 ```tsx
 <PhantomProvider
   config={{
-    providerType: "injected",
+    providers: ["injected"], // Only allow browser extension
     addressTypes: [AddressType.solana, AddressType.ethereum],
   }}
 >
@@ -176,11 +579,39 @@ Uses the Phantom browser extension installed by the user.
 </PhantomProvider>
 ```
 
-### Embedded Provider
+**Multiple Authentication Methods**
 
-Creates non-custodial wallets embedded in your application.
+```tsx
+<PhantomProvider
+  config={{
+    providers: ["google", "apple", "phantom", "injected", "deeplink"], // Allow all methods
+    appId: "your-app-id", // Required for embedded providers
+    addressTypes: [AddressType.solana, AddressType.ethereum],
+  }}
+>
+  <YourApp />
+</PhantomProvider>
+```
+
+**Mobile Deeplink Support**
 
-#### User Wallet
+The `"deeplink"` provider enables a button that opens the Phantom mobile app on mobile devices. This button only appears on mobile devices when the Phantom browser extension is not installed. When clicked, it redirects users to the Phantom mobile app to complete authentication.
+
+```tsx
+<PhantomProvider
+  config={{
+    providers: ["google", "apple", "phantom", "deeplink"], // Include deeplink for mobile support
+    appId: "your-app-id", // Required for deeplink
+    addressTypes: [AddressType.solana, AddressType.ethereum],
+  }}
+>
+  <YourApp />
+</PhantomProvider>
+```
+
+### Embedded Wallet Type
+
+When using embedded providers (google, apple, phantom, etc.), you can specify the wallet type using `embeddedWalletType`. The default is `"user-wallet"`:
 
 - **Uses Phantom authentication** - user logs in with existing account
 - **Potentially funded** - brings existing wallet balance
@@ -189,16 +620,16 @@ Creates non-custodial wallets embedded in your application.
 ```tsx
 <PhantomProvider
   config={{
-    providerType: "embedded",
+    providers: ["google", "apple", "phantom"],
     appId: "your-app-id",
     addressTypes: [AddressType.solana, AddressType.ethereum],
+    embeddedWalletType: "user-wallet", // default, can be omitted
   }}
 >
   <YourApp />
 </PhantomProvider>
 ```
 
-
 ## Available Hooks
 
 ### Core Connection Hooks
@@ -211,17 +642,22 @@ Connect to wallet:
 import { useConnect } from "@phantom/react-sdk";
 
 function ConnectButton() {
-  const { connect, isConnecting, error } = useConnect();
+  const { connect, isConnecting, isLoading, error } = useConnect();
 
   const handleConnect = async () => {
     try {
-      const { walletId, addresses } = await connect();
+      const { addresses } = await connect({ provider: "injected" });
       console.log("Connected addresses:", addresses);
     } catch (err) {
       console.error("Failed to connect:", err);
     }
   };
 
+  // Wait for SDK to finish initializing before showing connect button
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
   return (
     <button onClick={handleConnect} disabled={isConnecting}>
       {isConnecting ? "Connecting..." : "Connect Wallet"}
@@ -305,6 +741,29 @@ function ExtensionStatus() {
 }
 ```
 
+#### useIsPhantomLoginAvailable
+
+Check if Phantom Login is available (requires extension installed and `phantom_login` feature support):
+
+```tsx
+import { useIsPhantomLoginAvailable } from "@phantom/react-sdk";
+
+function PhantomLoginButton() {
+  const { isLoading, isAvailable } = useIsPhantomLoginAvailable();
+  const { connect } = useConnect();
+
+  if (isLoading) {
+    return <div>Checking Phantom Login availability...</div>;
+  }
+
+  if (!isAvailable) {
+    return null; // Don't show button if Phantom Login is not available
+  }
+
+  return <button onClick={() => connect({ provider: "phantom" })}>Login with Phantom</button>;
+}
+```
+
 ### Chain-Specific Hooks
 
 #### useSolana
@@ -316,7 +775,12 @@ import { useSolana } from "@phantom/react-sdk";
 import { VersionedTransaction, TransactionMessage, SystemProgram, PublicKey, Connection } from "@solana/web3.js";
 
 function SolanaOperations() {
-  const solana = useSolana();
+  const { solana, isAvailable } = useSolana();
+
+  // Check if Solana is available before using it
+  if (!isAvailable) {
+    return <div>Solana is not available for the current wallet</div>;
+  }
 
   const signMessage = async () => {
     const signature = await solana.signMessage("Hello Solana!");
@@ -371,7 +835,19 @@ function SolanaOperations() {
 - `switchNetwork(network)` - Switch between mainnet/devnet
 - `getPublicKey()` - Get current public key
 - `isConnected` - Connection status
-- `isAvailable` - Provider availability
+- `isAvailable` - Provider availability (see note below)
+
+**Note on `isAvailable`:**
+
+The `isAvailable` property indicates whether the Solana chain is available for the currently connected wallet:
+
+- **For embedded wallets** (Google, Apple, Phantom Login, etc.): `isAvailable` will be `true` for all networks configured in your `addressTypes` array, as embedded wallets support all configured networks.
+
+- **For Phantom injected wallet**: `isAvailable` will be `true` for all networks configured in your `addressTypes` array, as Phantom supports multiple networks.
+
+- **For other injected wallets** (discovered via Wallet Standard or EIP-6963): `isAvailable` depends on which networks the specific wallet supports. For example, if you connect to a wallet that only supports Ethereum, `isAvailable` will be `false` for Solana even if Solana is in your `addressTypes` configuration.
+
+Always check `isAvailable` before attempting to use chain-specific methods when working with injected wallets that may not support all networks.
 
 #### useEthereum
 
@@ -381,7 +857,12 @@ Hook for Ethereum chain operations:
 import { useEthereum } from "@phantom/react-sdk";
 
 function EthereumOperations() {
-  const ethereum = useEthereum();
+  const { ethereum, isAvailable } = useEthereum();
+
+  // Check if Ethereum is available before using it
+  if (!isAvailable) {
+    return <div>Ethereum is not available for the current wallet</div>;
+  }
 
   const signPersonalMessage = async () => {
     const accounts = await ethereum.getAccounts();
@@ -466,11 +947,71 @@ function EthereumOperations() {
 - `signTypedData(typedData)` - Sign EIP-712 typed data
 - `signTransaction(transaction)` - Sign transaction without sending
 - `sendTransaction(transaction)` - Sign and send transaction
-- `switchChain(chainId)` - Switch chains
+- `switchChain(chainId)` - Switch chains (accepts chain ID as number or a hex string)
 - `getChainId()` - Get current chain ID
 - `getAccounts()` - Get connected accounts
 - `isConnected` - Connection status
-- `isAvailable` - Provider availability
+- `isAvailable` - Provider availability (see note below)
+
+**Note on `isAvailable`:**
+
+The `isAvailable` property indicates whether the Ethereum chain is available for the currently connected wallet:
+
+- **For embedded wallets** (Google, Apple, Phantom Login, etc.): `isAvailable` will be `true` for all networks configured in your `addressTypes` array, as embedded wallets support all configured networks.
+
+- **For Phantom injected wallet**: `isAvailable` will be `true` for all networks configured in your `addressTypes` array, as Phantom supports multiple networks.
+
+- **For other injected wallets** (discovered via Wallet Standard or EIP-6963): `isAvailable` depends on which networks the specific wallet supports. For example, if you connect to a wallet that only supports Solana, `isAvailable` will be `false` for Ethereum even if Ethereum is in your `addressTypes` configuration.
+
+Always check `isAvailable` before attempting to use chain-specific methods when working with injected wallets that may not support all networks.
+
+**Supported EVM Networks:**
+
+| Network          | Chain ID   | Usage                            |
+| ---------------- | ---------- | -------------------------------- |
+| Ethereum Mainnet | `1`        | `ethereum.switchChain(1)`        |
+| Ethereum Sepolia | `11155111` | `ethereum.switchChain(11155111)` |
+| Polygon Mainnet  | `137`      | `ethereum.switchChain(137)`      |
+| Polygon Amoy     | `80002`    | `ethereum.switchChain(80002)`    |
+| Base Mainnet     | `8453`     | `ethereum.switchChain(8453)`     |
+| Base Sepolia     | `84532`    | `ethereum.switchChain(84532)`    |
+| Arbitrum One     | `42161`    | `ethereum.switchChain(42161)`    |
+| Arbitrum Sepolia | `421614`   | `ethereum.switchChain(421614)`   |
+| Monad Mainnet    | `143`      | `ethereum.switchChain(143)`      |
+| Monad Testnet    | `10143`    | `ethereum.switchChain(10143)`    |
+
+### Wallet Discovery Hook
+
+#### useDiscoveredWallets
+
+Hook to get discovered injected wallets with automatic loading and error states. Discovers wallets using Wallet Standard (Solana) and EIP-6963 (Ethereum) standards.
+
+```tsx
+import { useDiscoveredWallets } from "@phantom/react-sdk";
+
+function WalletSelector() {
+  const { wallets, isLoading, error, refetch } = useDiscoveredWallets();
+
+  // wallets: InjectedWalletInfo[] - Array of discovered wallets
+  // isLoading: boolean - Loading state during discovery
+  // error: Error | null - Error state if discovery fails
+  // refetch: () => Promise<void> - Function to manually trigger discovery
+}
+```
+
+**Returns:**
+
+- `wallets: InjectedWalletInfo[]` - Array of discovered wallet information
+- `isLoading: boolean` - `true` while discovery is in progress
+- `error: Error | null` - Error object if discovery fails, `null` otherwise
+- `refetch: () => Promise<void>` - Async function to manually refresh the wallet list
+
+**Behavior:**
+
+- Automatically fetches discovered wallets when the SDK becomes available
+- If no wallets are found in the registry, triggers async `discoverWallets()` to discover them
+- Wallets are filtered based on the `addressTypes` configured in `PhantomProvider`
+- Phantom wallet is automatically included if available
 
 ### Auto-Confirm Hook (Injected Provider Only)
 
@@ -614,7 +1155,7 @@ import { VersionedTransaction, TransactionMessage, SystemProgram, PublicKey, Con
 import { useSolana } from "@phantom/react-sdk";
 
 function SolanaExample() {
-  const solana = useSolana();
+  const { solana } = useSolana();
 
   const sendTransaction = async () => {
     // Get recent blockhash
@@ -662,7 +1203,7 @@ import {
 import { useSolana } from "@phantom/react-sdk";
 
 function SolanaKitExample() {
-  const solana = useSolana();
+  const { solana } = useSolana();
 
   const sendTransaction = async () => {
     const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
@@ -693,7 +1234,7 @@ import { parseEther, parseGwei, encodeFunctionData } from "viem";
 import { useEthereum } from "@phantom/react-sdk";
 
 function EthereumExample() {
-  const ethereum = useEthereum();
+  const { ethereum } = useEthereum();
 
   const sendEth = async () => {
     const result = await ethereum.sendTransaction({
@@ -733,36 +1274,45 @@ function EthereumExample() {
 
 Quick reference of all available hooks:
 
-| Hook                      | Purpose                                 | Returns                                             |
-| ------------------------- | --------------------------------------- | --------------------------------------------------- |
-| `useConnect`              | Connect to wallet                       | `{ connect, isConnecting, error }`                  |
-| `useAccounts`             | Get wallet addresses                    | `WalletAddress[]` or `null`                         |
-| `useIsExtensionInstalled` | Check extension status                  | `{ isLoading, isInstalled }`                        |
-| `useDisconnect`           | Disconnect from wallet                  | `{ disconnect, isDisconnecting }`                   |
-| `useAutoConfirm`          | Auto-confirm management (injected only) | `{ enable, disable, status, supportedChains, ... }` |
-| `useSolana`               | Solana chain operations                 | `{ signMessage, signAndSendTransaction, ... }`      |
-| `useEthereum`             | Ethereum chain operations               | `{ signPersonalMessage, sendTransaction, ... }`     |
-| `usePhantom`              | Get provider context                    | `{ isConnected, isReady }`                          |
+| Hook                         | Purpose                                 | Returns                                             |
+| ---------------------------- | --------------------------------------- | --------------------------------------------------- |
+| `useConnect`                 | Connect to wallet                       | `{ connect, isConnecting, error }`                  |
+| `useModal`                   | Control connection modal                | `{ open, close, isOpened }`                         |
+| `useAccounts`                | Get wallet addresses                    | `WalletAddress[]` or `null`                         |
+| `useIsExtensionInstalled`    | Check extension status                  | `{ isLoading, isInstalled }`                        |
+| `useIsPhantomLoginAvailable` | Check Phantom Login availability        | `{ isLoading, isAvailable }`                        |
+| `useDisconnect`              | Disconnect from wallet                  | `{ disconnect, isDisconnecting }`                   |
+| `useAutoConfirm`             | Auto-confirm management (injected only) | `{ enable, disable, status, supportedChains, ... }` |
+| `useDiscoveredWallets`       | Get discovered injected wallets         | `{ wallets, isLoading, error, refetch }`            |
+| `useSolana`                  | Solana chain operations                 | `{ signMessage, signAndSendTransaction, ... }`      |
+| `useEthereum`                | Ethereum chain operations               | `{ signPersonalMessage, sendTransaction, ... }`     |
+| `useTheme`                   | Access current theme                    | `PhantomTheme`                                      |
+| `usePhantom`                 | Get provider context                    | `{ isConnected, isReady }`                          |
 
 ## Configuration Reference
 
 ```typescript
 interface PhantomSDKConfig {
-  providerType: "injected" | "embedded";
+  // List of allowed authentication providers (REQUIRED)
+  providers: AuthProviderType[]; // e.g., ["google", "apple", "phantom", "injected"]
+
   addressTypes?: [AddressType, ...AddressType[]]; // Networks to enable (e.g., [AddressType.solana])
 
-  // Required for embedded provider only
-  appId: string; // Your app ID from phantom.com/portal (required for embedded provider)
-  
+  // Required when using embedded providers (google, apple, phantom)
+  appId?: string; // Your app ID from phantom.com/portal
+
   // Optional configuration
   apiBaseUrl?: string; // Phantom API base URL (optional, has default)
   authOptions?: {
     authUrl?: string; // Custom auth URL (optional, defaults to "https://connect.phantom.app/login")
     redirectUrl?: string; // Custom redirect URL after authentication (optional)
   };
-  embeddedWalletType?: "user-wallet"; // Wallet type (optional, defaults to "user-wallet", currently the only supported type)
-  autoConnect?: boolean; // Auto-connect to existing session on SDK instantiation (optional, defaults to true for embedded, false for injected)
+  embeddedWalletType?: "user-wallet"; // Wallet type (optional, defaults to "user-wallet")
+  autoConnect?: boolean; // Auto-connect to existing session (default: true when embedded providers used)
 }
+
+// Valid provider types
+type AuthProviderType = "google" | "apple" | "phantom" | "injected";
 ```
 
 ## Debug Configuration
@@ -792,8 +1342,9 @@ function App() {
 
   // SDK configuration - static, won't change when debug settings change
   const config: PhantomSDKConfig = {
-    providerType: "embedded",
+    providers: ["google", "apple", "phantom"],
     appId: "your-app-id",
+    addressTypes: [AddressType.solana, AddressType.ethereum],
     // ... other config
   };