@solana/kit-plugin-wallet 0.12.0 → 0.13.0

package/README.md

@@ -149,9 +149,9 @@ All wallet state is accessed via `client.wallet.getState()`, which returns a ref
     }
     ```
 
-- **`disconnect()`** — Disconnect the active wallet.
+- **`disconnect(wallet?)`** — Disconnects an authorized wallet. If `wallet` is not provided, disconnects the active wallet.
 
-- **`selectAccount(account)`** — Switch to a different account within an already-authorized wallet without reconnecting.
+- **`selectAccount(account)`** — Switch to a different account within any already-authorized wallet without reconnecting.
 
     ```ts
     client.wallet.selectAccount(accounts[0]);
@@ -169,11 +169,109 @@ All wallet state is accessed via `client.wallet.getState()`, which returns a ref
     const output = await client.wallet.signIn(selectedWallet, { domain: window.location.host });
     ```
 
+## React hooks
+
+The `@solana/kit-plugin-wallet/react` subpath exposes hooks for reading wallet state and driving wallet actions from React components. Install the optional peer dependencies (`react` and [`@solana/react`](https://www.npmjs.com/package/@solana/react)) and render your tree inside a `ClientProvider` whose client has a wallet plugin installed.
+
+The **state** hooks subscribe via `useSyncExternalStore`, each to a single slice of `WalletState`, so a component only re-renders when the slice it reads changes:
+
+| Hook                 | Returns                                                                          |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `useWalletStatus`    | The current `WalletStatus`.                                                      |
+| `useConnectedWallet` | The active connection (`{ account, signer, wallet }`) or null.                   |
+| `useWallets`         | The discovered wallets for the client's chain.                                   |
+| `useIsWalletReady`   | `false` while the initial warm-up is in progress (`'pending'`/`'reconnecting'`). |
+
+The **action** hooks wrap the async wallet actions with `useAction` from `@solana/react`, returning its result (`dispatch`, `dispatchAsync`, `data`, `error`, `status`, `isRunning`, `reset`, …). The hook manages the `AbortSignal` internally, so an in-flight call is aborted when a newer one is dispatched:
+
+| Hook               | Wraps                                                                     |
+| ------------------ | ------------------------------------------------------------------------- |
+| `useConnect`       | `client.wallet.connect` — `dispatch(wallet)`                              |
+| `useDisconnect`    | `client.wallet.disconnect` — `dispatch()`                                 |
+| `useSignIn`        | `client.wallet.signIn` — `dispatch(wallet, input)`                        |
+| `useSignMessage`   | `client.wallet.signMessage` — `dispatch(message)`                         |
+| `useSelectAccount` | `client.wallet.selectAccount` — returns the synchronous callback directly |
+
+```tsx
+import { useConnect, useConnectedWallet, useWallets, useWalletStatus } from '@solana/kit-plugin-wallet/react';
+
+function WalletButton() {
+    const status = useWalletStatus();
+    const wallets = useWallets();
+    const connected = useConnectedWallet();
+    const { dispatch: connect, isRunning } = useConnect();
+
+    if (status === 'pending') return null; // avoid flashing UI before auto-reconnect resolves
+
+    if (connected) return <p>Connected: {connected.account.address}</p>;
+
+    return wallets.map(wallet => (
+        <button key={wallet.name} disabled={isRunning} onClick={() => connect(wallet)}>
+            Connect {wallet.name}
+        </button>
+    ));
+}
+```
+
+### Gating UI on the initial warm-up
+
+A freshly built client runs a silent auto-reconnect on mount, briefly passing through `'pending'` and `'reconnecting'` before it settles. If you render wallet-dependent UI immediately, a persisted wallet flashes "disconnected" for a frame before it reconnects. `useIsWalletReady` reports `false` for the duration of that warm-up and `true` once it settles, so you can hold back the wallet-dependent parts while painting the rest of the app:
+
+```tsx
+import { useIsWalletReady, WalletReadyGate } from '@solana/kit-plugin-wallet/react';
+
+// Hide a whole subtree until the connection settles:
+function App() {
+    return (
+        <WalletReadyGate fallback={<Spinner />}>
+            <WalletDependentUI />
+        </WalletReadyGate>
+    );
+}
+
+// Or read the boolean directly for finer control (e.g. disabling a button):
+function ConnectButton() {
+    const isReady = useIsWalletReady();
+    return <button disabled={!isReady}>Connect</button>;
+}
+```
+
+`WalletReadyGate` is a thin wrapper over `useIsWalletReady`. Its props are shaped like React's `<Suspense fallback>`, but it is synchronous — it renders `fallback` directly off the reactive status rather than suspending, so it needs no `<Suspense>` ancestor. Both gate on the same warm-up set as `whenReady()` below, so they stay in sync — and like `whenReady()`, they ignore user-initiated `'connecting'` / `'disconnecting'`. To genuinely suspend a subtree, throw the Suspense-safe `whenReady()` promise from your own component instead.
+
+### Advanced: seamless client swaps with `whenReady()`
+
+> Most apps don't need this. It only matters if you **rebuild the client at runtime** — for example, to change chain — since each wallet plugin is bound to a single chain.
+
+Every freshly built client runs a silent auto-reconnect that briefly passes through the `'pending'` and `'reconnecting'` statuses. If you publish the new client as soon as you build it, the UI may flash that reconnecting state on every switch. `client.wallet.whenReady()` returns a promise that resolves once the status has left `'pending'` / `'reconnecting'`, so you can build the new client, wait for it to settle, and only then swap it in — keeping the previous client live until the new one is ready:
+
+```ts
+import { createClient } from '@solana/kit';
+import { walletSigner } from '@solana/kit-plugin-wallet';
+
+// On a chain switch, hold the previous client until the rebuilt one is ready:
+const next = createClient().use(walletSigner({ chain }));
+await next.wallet.whenReady();
+swapInClient(next); // publish `next`, then dispose the client it replaced
+```
+
+`whenReady()` deliberately does **not** wait for user-initiated `connect` / `disconnect` / `signIn` (those pass through `'connecting'` / `'disconnecting'`), so it only ever blocks on the initial warm-up — a normal connect stays interactive.
+
+Disposing a client mid-warm-up settles its status to `'disconnected'` and resolves any pending `whenReady()` promise — a superseded client never leaves an `await` hanging. Check `getState()` after awaiting if you need to tell a ready connection from a disposed (or never-connected) client.
+
 ## Framework integration
 
-The plugin exposes `subscribe` and `getState` for binding wallet state to any UI framework.
+The plugin exposes `subscribe` and `getState` for binding wallet state to any UI framework. To gate UI on the initial auto-reconnect warm-up without React, pass `getState().status` through `isWalletWarmingUp` — the same predicate that backs `whenReady()` and the [React readiness helpers](#gating-ui-on-the-initial-warm-up), so all three stay in sync:
+
+```ts
+import { isWalletWarmingUp } from '@solana/kit-plugin-wallet';
+
+client.wallet.subscribe(() => {
+    const { status } = client.wallet.getState();
+    setLoading(isWalletWarmingUp(status)); // true while 'pending' / 'reconnecting'
+});
+```
 
-**React** — use `useSyncExternalStore` for concurrent-mode-safe rendering:
+**React** — prefer the ready-made [React hooks](#react-hooks) above; they wrap the pattern below. To bind state manually (e.g. to read the whole snapshot at once), use `useSyncExternalStore` for concurrent-mode-safe rendering:
 
 ```tsx
 import { useSyncExternalStore } from 'react';

package/dist/index.browser.cjs

@@ -8,7 +8,10 @@ var features = require('@wallet-standard/features');
 var uiFeatures = require('@wallet-standard/ui-features');
 var uiRegistry = require('@wallet-standard/ui-registry');
 
-// src/wallet.ts
+// src/status.ts
+function isWalletWarmingUp(status) {
+  return status === "pending" || status === "reconnecting";
+}
 function createWalletStore(config) {
   let state = {
     account: null,
@@ -19,12 +22,13 @@ function createWalletStore(config) {
   };
   const listeners = /* @__PURE__ */ new Set();
   const signerListeners = /* @__PURE__ */ new Set();
-  let walletEventsCleanup = null;
+  const walletEventSubscriptions = /* @__PURE__ */ new Map();
   let reconnectCleanup = null;
   let userHasSelected = false;
   let connectGeneration = 0;
   let disposed = false;
   let disconnectingWalletName = null;
+  let readyDeferred = null;
   function resolveDefaultStorage() {
     try {
       return localStorage;
@@ -52,6 +56,13 @@ function createWalletStore(config) {
   function updateState(updates) {
     const prev = state;
     state = { ...state, ...updates };
+    if (isWalletWarmingUp(prev.status) && !isWalletWarmingUp(state.status)) {
+      readyDeferred?.resolve();
+      readyDeferred = null;
+    }
+    if (state.wallets !== prev.wallets) {
+      syncWalletEventSubscriptions(state.wallets);
+    }
     const signerChanged = observableSigner(state) !== observableSigner(prev);
     if (state.connectedWallet !== prev.connectedWallet || state.account !== prev.account || state.status !== prev.status || state.signer !== prev.signer || state.wallets !== prev.wallets) {
       snapshot = deriveSnapshot(state);
@@ -61,6 +72,13 @@ function createWalletStore(config) {
       signerListeners.forEach((l) => l());
     }
   }
+  function whenReady() {
+    if (!isWalletWarmingUp(state.status)) {
+      return Promise.resolve();
+    }
+    readyDeferred ??= Promise.withResolvers();
+    return readyDeferred.promise;
+  }
   function tryCreateSigner(account) {
     try {
       return walletAccountSigner.createSignerFromWalletAccount(account, config.chain);
@@ -86,6 +104,20 @@ function createWalletStore(config) {
     }
     return next;
   }
+  function syncWalletEventSubscriptions(wallets) {
+    const names = new Set(wallets.map((w) => w.name));
+    for (const [name, cleanup] of walletEventSubscriptions) {
+      if (!names.has(name)) {
+        cleanup();
+        walletEventSubscriptions.delete(name);
+      }
+    }
+    for (const w of wallets) {
+      if (!walletEventSubscriptions.has(w.name)) {
+        walletEventSubscriptions.set(w.name, subscribeToWalletEvents(w));
+      }
+    }
+  }
   function isWalletStillAvailable(uiWallet) {
     return buildWalletList().some((w) => w.name === uiWallet.name);
   }
@@ -97,8 +129,6 @@ function createWalletStore(config) {
     const newWallets = reconcileWalletList();
     const updates = { wallets: newWallets };
     if (state.connectedWallet && !newWallets.some((w) => w.name === state.connectedWallet.name)) {
-      walletEventsCleanup?.();
-      walletEventsCleanup = null;
       updates.connectedWallet = null;
       updates.account = null;
       updates.signer = null;
@@ -111,16 +141,17 @@ function createWalletStore(config) {
     reconnectCleanup?.();
     reconnectCleanup = null;
   }
-  function resubscribeToWalletEvents(uiWallet) {
-    walletEventsCleanup?.();
-    walletEventsCleanup = subscribeToWalletEvents(uiWallet);
-  }
   function setConnected(account, wallet, options) {
     if (disposed) return;
     const signer = tryCreateSigner(account);
-    resubscribeToWalletEvents(wallet);
     disconnectingWalletName = null;
-    updateState({ account, connectedWallet: wallet, signer, status: "connected" });
+    updateState({
+      account,
+      connectedWallet: wallet,
+      signer,
+      status: "connected",
+      wallets: reconcileWalletList()
+    });
     if (options?.persist !== false) {
       persistAccount(account, wallet);
     }
@@ -138,8 +169,14 @@ function createWalletStore(config) {
       uiWallet,
       features.StandardEvents
     );
+    const walletName = uiWallet.name;
     return eventsFeature.on("change", () => {
-      const refreshed = refreshUiWallet(uiWallet);
+      const newWallets = reconcileWalletList();
+      if (!state.connectedWallet || state.connectedWallet.name !== walletName) {
+        updateState({ wallets: newWallets });
+        return;
+      }
+      const refreshed = refreshUiWallet(state.connectedWallet);
       if (!filterWallet(refreshed)) {
         disconnectLocally();
         return;
@@ -149,7 +186,7 @@ function createWalletStore(config) {
         disconnectLocally();
         return;
       }
-      updateState({ connectedWallet: refreshed, wallets: reconcileWalletList(), ...result });
+      updateState({ connectedWallet: refreshed, wallets: newWallets, ...result });
       if (result.account) {
         persistAccount(result.account, refreshed);
       }
@@ -199,9 +236,10 @@ function createWalletStore(config) {
       throw error;
     }
   }
-  async function disconnect(options) {
+  async function disconnect(wallet, options) {
     options?.abortSignal?.throwIfAborted();
-    if (!state.connectedWallet) {
+    const target = wallet ?? state.connectedWallet;
+    if (!target) {
       userHasSelected = true;
       cancelReconnect();
       connectGeneration++;
@@ -209,27 +247,52 @@ function createWalletStore(config) {
       clearPersistedAccount();
       return;
     }
-    const currentWallet = state.connectedWallet;
-    const generation = ++connectGeneration;
-    disconnectingWalletName = currentWallet.name;
-    updateState({ status: "disconnecting" });
-    try {
-      if (currentWallet.features.includes(features.StandardDisconnect)) {
-        const disconnectFeature = uiFeatures.getWalletFeature(
-          currentWallet,
-          features.StandardDisconnect
-        );
-        await disconnectFeature.disconnect();
+    const isActive = state.connectedWallet != null && state.connectedWallet.name === target.name;
+    if (isActive) {
+      const currentWallet = state.connectedWallet;
+      const generation = ++connectGeneration;
+      disconnectingWalletName = currentWallet.name;
+      updateState({ status: "disconnecting" });
+      try {
+        if (currentWallet.features.includes(features.StandardDisconnect)) {
+          const disconnectFeature = uiFeatures.getWalletFeature(
+            currentWallet,
+            features.StandardDisconnect
+          );
+          await disconnectFeature.disconnect();
+        }
+      } finally {
+        if (generation === connectGeneration) {
+          disconnectLocally();
+        }
       }
+      return;
+    }
+    if (!isWalletStillAvailable(target)) {
+      return;
+    }
+    const refreshedTarget = refreshUiWallet(target);
+    if (!refreshedTarget.features.includes(features.StandardDisconnect)) {
+      return;
+    }
+    const prevDisconnecting = disconnectingWalletName;
+    disconnectingWalletName = refreshedTarget.name;
+    try {
+      const disconnectFeature = uiFeatures.getWalletFeature(
+        refreshedTarget,
+        features.StandardDisconnect
+      );
+      await disconnectFeature.disconnect();
     } finally {
-      if (generation === connectGeneration) {
-        disconnectLocally();
+      if (disconnectingWalletName === refreshedTarget.name) {
+        disconnectingWalletName = prevDisconnecting;
+      }
+      if (!disposed) {
+        updateState({ wallets: reconcileWalletList() });
       }
     }
   }
   function disconnectLocally() {
-    walletEventsCleanup?.();
-    walletEventsCleanup = null;
     disconnectingWalletName = null;
     updateState({
       account: null,
@@ -255,13 +318,25 @@ function createWalletStore(config) {
     }
   }
   function selectAccount(account) {
-    if (!state.connectedWallet) {
-      throw new kit.SolanaError(kit.SOLANA_ERROR__WALLET__NOT_CONNECTED, { operation: "selectAccount" });
+    let owner;
+    try {
+      owner = uiRegistry.getOrCreateUiWalletForStandardWallet(uiRegistry.getWalletForHandle(account));
+    } catch {
+      throw new kit.SolanaError(kit.SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE, {
+        account: account.address,
+        operation: "selectAccount"
+      });
     }
-    if (state.connectedWallet.name === disconnectingWalletName) {
+    if (!isWalletStillAvailable(owner)) {
+      throw new kit.SolanaError(kit.SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE, {
+        account: account.address,
+        operation: "selectAccount"
+      });
+    }
+    if (owner.name === disconnectingWalletName) {
       throw new kit.SolanaError(kit.SOLANA_ERROR__WALLET__NOT_CONNECTED, { operation: "selectAccount" });
     }
-    const refreshed = refreshUiWallet(state.connectedWallet);
+    const refreshed = refreshUiWallet(owner);
     const selectedAccount = refreshed.accounts.find((a) => a.address === account.address);
     if (!selectedAccount) {
       throw new kit.SolanaError(kit.SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE, {
@@ -466,16 +541,22 @@ function createWalletStore(config) {
         signerListeners.delete(listener);
       };
     },
+    whenReady,
     [Symbol.dispose]: () => {
       disposed = true;
       connectGeneration++;
       unsubRegister();
       unsubUnregister();
-      walletEventsCleanup?.();
-      walletEventsCleanup = null;
+      for (const cleanup of walletEventSubscriptions.values()) {
+        cleanup();
+      }
+      walletEventSubscriptions.clear();
       cancelReconnect();
       listeners.clear();
       signerListeners.clear();
+      if (isWalletWarmingUp(state.status)) {
+        updateState({ status: "disconnected" });
+      }
     }
   };
 }
@@ -484,7 +565,9 @@ function createWalletStore(config) {
 function defineSignerGetter(additions, property, store) {
   Object.defineProperty(additions, property, {
     configurable: true,
-    enumerable: true,
+    // Non-enumerable on purpose: this getter throws when no signer is connected, so we
+    // don't want things like Object.entries to read it.
+    enumerable: false,
     get() {
       const state = store.getState();
       if (!state.connected) {
@@ -530,6 +613,7 @@ function walletWithoutSigner(config) {
   return createPlugin(config, []);
 }
 
+exports.isWalletWarmingUp = isWalletWarmingUp;
 exports.walletIdentity = walletIdentity;
 exports.walletPayer = walletPayer;
 exports.walletSigner = walletSigner;