@solana/kit-plugin-wallet 0.12.0 → 0.13.1

package/src/store.ts

@@ -1,4 +1,5 @@
 import {
+    type ReadonlyUint8Array,
     type SignatureBytes,
     SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE,
     SOLANA_ERROR__WALLET__NOT_CONNECTED,
@@ -26,6 +27,7 @@ import type { UiWallet, UiWalletAccount } from '@wallet-standard/ui';
 import { getWalletAccountFeature, getWalletFeature } from '@wallet-standard/ui-features';
 import { getOrCreateUiWalletForStandardWallet, getWalletForHandle } from '@wallet-standard/ui-registry';
 
+import { isWalletWarmingUp } from './status';
 import type {
     WalletActionOptions,
     WalletNamespace,
@@ -85,6 +87,7 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
                 Promise.reject(new SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED, { operation: 'signMessage' })),
             subscribe: () => () => {},
             subscribeSigner: () => () => {},
+            whenReady: () => Promise.resolve(),
             [Symbol.dispose]: () => {},
         };
     }
@@ -101,13 +104,22 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
 
     const listeners = new Set<() => void>();
     const signerListeners = new Set<() => void>();
-    let walletEventsCleanup: (() => void) | null = null;
+    // One `standard:events change` subscription per discovered wallet, keyed by
+    // name (the stable identity; the UiWallet handle regenerates on changes). The
+    // underlying subscription attaches to the raw wallet's events, so it survives
+    // handle regeneration — no need to resubscribe when a wallet's accounts change.
+    const walletEventSubscriptions = new Map<string, () => void>();
     let reconnectCleanup: (() => void) | null = null;
     let userHasSelected = false;
     let connectGeneration = 0;
     let disposed = false;
     // Wallet that is in the process of disconnecting, stored to guard against re-connecting to it if a future connect fails
     let disconnectingWalletName: string | null = null;
+    // Deferred backing `whenReady`. Created lazily while the status is transient
+    // (see `isWalletWarmingUp`) and resolved by `updateState` once the status
+    // settles, so `whenReady` can hand out a stable promise for the duration of
+    // one warm-up episode (required by React Suspense).
+    let readyDeferred: PromiseWithResolvers<void> | null = null;
 
     // Resolve storage: default to localStorage in browser, null to disable.
     // Merely *accessing* `localStorage` throws a `SecurityError` in sandboxed
@@ -155,6 +167,19 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
         const prev = state;
         state = { ...state, ...updates };
 
+        // Resolve `whenReady` the moment the status leaves the transient
+        // warm-up set. `readyDeferred` is only ever created while transient (in
+        // `whenReady`), so clearing it here lets the next transient episode arm
+        // a fresh one.
+        if (isWalletWarmingUp(prev.status) && !isWalletWarmingUp(state.status)) {
+            readyDeferred?.resolve();
+            readyDeferred = null;
+        }
+
+        if (state.wallets !== prev.wallets) {
+            syncWalletEventSubscriptions(state.wallets);
+        }
+
         // Signer subscribers (`subscribeToPayer` / `subscribeToIdentity`) fire
         // only when the observed signer changes.
         const signerChanged = observableSigner(state) !== observableSigner(prev);
@@ -175,6 +200,18 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
         }
     }
 
+    // Advanced: see the `whenReady` docblock on `WalletNamespace`. Returns a
+    // stable, already-resolved promise once the initial warm-up has settled;
+    // while transient, returns the same pending promise on every call so it is
+    // safe to throw for React Suspense.
+    function whenReady(): Promise<void> {
+        if (!isWalletWarmingUp(state.status)) {
+            return Promise.resolve();
+        }
+        readyDeferred ??= Promise.withResolvers<void>();
+        return readyDeferred.promise;
+    }
+
     // -- Signer creation ---------------------------------------------------
 
     function tryCreateSigner(account: UiWalletAccount): WalletSigner | null {
@@ -227,6 +264,29 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
         return next;
     }
 
+    // Reconcile the per-wallet event subscriptions against the current wallet set:
+    // subscribe wallets that just appeared, unsubscribe those that left. Called
+    // whenever `state.wallets` changes reference. Subscribing fires nothing, so
+    // this never causes re-render churn. `wallets` is the already-filtered visible
+    // list, so wallets excluded by chain/feature/`config.filter` are intentionally
+    // never subscribed — a `register` / `unregister` event reconciles them in or
+    // out of the list (and thus in or out of this map) when their eligibility
+    // changes.
+    function syncWalletEventSubscriptions(wallets: readonly UiWallet[]): void {
+        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));
+            }
+        }
+    }
+
     // True if a wallet matching `uiWallet` (by name) is currently registered and
     // passes the filter. Used to re-check membership after an awaited connect /
     // sign-in / silent reconnect resolves: the wallet may have unregistered (or
@@ -253,8 +313,6 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
 
         // If the connected wallet was unregistered, disconnect locally.
         if (state.connectedWallet && !newWallets.some(w => w.name === state.connectedWallet!.name)) {
-            walletEventsCleanup?.();
-            walletEventsCleanup = null;
             updates.connectedWallet = null;
             updates.account = null;
             updates.signer = null;
@@ -272,11 +330,6 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
         reconnectCleanup = null;
     }
 
-    function resubscribeToWalletEvents(uiWallet: UiWallet): void {
-        walletEventsCleanup?.();
-        walletEventsCleanup = subscribeToWalletEvents(uiWallet);
-    }
-
     function setConnected(account: UiWalletAccount, wallet: UiWallet, options?: { persist?: boolean }): void {
         // The store may have been disposed while a connect / sign-in / silent
         // reconnect awaited. The `connectGeneration` guard at each call site
@@ -287,9 +340,23 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
         // itself connected.
         if (disposed) return;
         const signer = tryCreateSigner(account);
-        resubscribeToWalletEvents(wallet);
         disconnectingWalletName = null;
-        updateState({ account, connectedWallet: wallet, signer, status: 'connected' });
+        // Reconcile `wallets` alongside the connection: `connect`/`signIn`/silent
+        // reconnect authorize accounts on the underlying wallet, which regenerates
+        // its registry handle. Without rebuilding the list here, `getState().wallets`
+        // would keep the pre-connect handle (empty `.accounts`) until an unrelated
+        // `standard:events change` happened to fire — so consumers reading the
+        // just-connected wallet from `wallets` (e.g. rendering its authorized
+        // accounts) would see it as unconnected. `reconcileWalletList` returns the
+        // existing reference when the visible set is unchanged, keeping the snapshot
+        // churn-free when connect didn't actually add accounts.
+        updateState({
+            account,
+            connectedWallet: wallet,
+            signer,
+            status: 'connected',
+            wallets: reconcileWalletList(),
+        });
         if (options?.persist !== false) {
             persistAccount(account, wallet);
         }
@@ -304,45 +371,43 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
         if (!uiWallet.features.includes(StandardEvents)) {
             return () => {};
         }
-
         const eventsFeature = getWalletFeature(
             uiWallet,
             StandardEvents,
         ) as StandardEventsFeature[typeof StandardEvents];
-
-        // The handler ignores the changed-property flags (`accounts`, `chains`,
-        // `features`) and instead reconciles the active account against the
-        // refreshed wallet. The signer is derived entirely from the account's
-        // features and chains, and the wallet-ui registry regenerates the
-        // account reference precisely when one of those changes — so the
-        // account reference is the single source of truth for whether the
-        // signer is affected, regardless of which flag the wallet sets.
+        const walletName = uiWallet.name;
+
+        // The handler intentionally ignores the changed-property flags
+        // (`accounts`, `chains`, `features`) the wallet passes and instead
+        // reconciles against the refreshed wallet. The signer is derived
+        // entirely from the active account's features and chains, and the
+        // wallet-ui registry regenerates the account reference precisely when
+        // one of those changes — so the account reference, not the flags, is
+        // the single source of truth for whether the signer is affected. Branch
+        // on the reconciled state below, never on `properties`.
         return eventsFeature.on('change', () => {
-            const refreshed = refreshUiWallet(uiWallet);
+            // Refresh the discovered list so this wallet's (and any others') accounts
+            // are current; `updateState` re-syncs subscriptions for added/removed wallets.
+            const newWallets = reconcileWalletList();
+
+            // Non-active wallet: reflect its new account/feature state in the list only.
+            if (!state.connectedWallet || state.connectedWallet.name !== walletName) {
+                updateState({ wallets: newWallets });
+                return;
+            }
 
-            // If the wallet no longer passes the filter (e.g. it dropped the
-            // configured chain or a required feature), disconnect.
+            // Active wallet: the original reconcile logic, unchanged.
+            const refreshed = refreshUiWallet(state.connectedWallet);
             if (!filterWallet(refreshed)) {
                 disconnectLocally();
                 return;
             }
-
             const result = reconcileActiveAccount(refreshed);
             if (result === null) {
                 disconnectLocally();
                 return;
             }
-
-            // `connectedWallet` is always refreshed so consumers reading
-            // `getState().connected.wallet` see current metadata; the signer
-            // (in `result`) only churns when the active account changed, which
-            // keeps the snapshot referentially stable on no-op change events.
-            // `wallets` is reconciled too: the registry regenerates the wallet
-            // handle on a change, so without this the list entry would keep the
-            // stale handle (`wallets[i] !== connected.wallet`). `reconcileWalletList`
-            // returns the existing reference on a no-op, preserving that stability.
-            updateState({ connectedWallet: refreshed, wallets: reconcileWalletList(), ...result });
-
+            updateState({ connectedWallet: refreshed, wallets: newWallets, ...result });
             if (result.account) {
                 persistAccount(result.account, refreshed);
             }
@@ -441,17 +506,14 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
         }
     }
 
-    async function disconnect(options?: WalletActionOptions): Promise<void> {
+    async function disconnect(wallet?: UiWallet, options?: WalletActionOptions): Promise<void> {
         options?.abortSignal?.throwIfAborted();
 
-        // No connected wallet, but an auto-reconnect may still be in flight:
-        // during 'reconnecting' a silent reconnect or the late-registration
-        // listener can complete and connect, overriding this explicit
-        // disconnect. Record the user's intent so auto-connect won't re-arm,
-        // tear down the late-registration listener, and bump the generation so
-        // any in-flight connect/signIn/silent-reconnect bails at its guard
-        // instead of resuming.
-        if (!state.connectedWallet) {
+        const target = wallet ?? state.connectedWallet;
+
+        // Nothing to disconnect (no arg, nothing active): cancel any pending reconnect, and
+        // supersede in-flight attempts.
+        if (!target) {
             userHasSelected = true;
             cancelReconnect();
             connectGeneration++;
@@ -460,39 +522,68 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
             return;
         }
 
-        const currentWallet = state.connectedWallet;
-        // Bump the generation so this disconnect supersedes any connect/signIn
-        // that was already in flight (its prompt opened before the user chose to
-        // disconnect): that attempt captured an earlier generation, so it will
-        // bail at its guard rather than establishing a connection the user has
-        // since dismissed. Mirrors the not-connected branch above — newest action
-        // wins. A connect/signIn started *after* this disconnect bumps the
-        // generation again, so the `finally` guard skips `disconnectLocally` and
-        // leaves the newer connection intact.
-        const generation = ++connectGeneration;
-        // Mark this wallet as disconnecting
-        disconnectingWalletName = currentWallet.name;
-        updateState({ status: 'disconnecting' });
+        const isActive = state.connectedWallet != null && state.connectedWallet.name === target.name;
 
-        try {
-            if (currentWallet.features.includes(StandardDisconnect)) {
-                const disconnectFeature = getWalletFeature(
-                    currentWallet,
-                    StandardDisconnect,
-                ) as StandardDisconnectFeature[typeof StandardDisconnect];
-                await disconnectFeature.disconnect();
+        if (isActive) {
+            const currentWallet = state.connectedWallet!;
+            // Bump generation so this disconnect supersedes any in-flight connect/signIn.
+            const generation = ++connectGeneration;
+            disconnectingWalletName = currentWallet.name;
+            updateState({ status: 'disconnecting' });
+            try {
+                if (currentWallet.features.includes(StandardDisconnect)) {
+                    const disconnectFeature = getWalletFeature(
+                        currentWallet,
+                        StandardDisconnect,
+                    ) as StandardDisconnectFeature[typeof StandardDisconnect];
+                    await disconnectFeature.disconnect();
+                }
+            } finally {
+                if (generation === connectGeneration) {
+                    disconnectLocally();
+                }
             }
+            return;
+        }
+
+        // targeted disconnect but wallet gone: leave the active connection, status,
+        // and persisted key untouched.
+        if (!isWalletStillAvailable(target)) {
+            return; // already gone / not authorized — forgiving no-op
+        }
+        const refreshedTarget = refreshUiWallet(target);
+        if (!refreshedTarget.features.includes(StandardDisconnect)) {
+            return; // can't deauthorize without standard:disconnect — no-op
+        }
+        // Guard against a concurrent select/connect into this wallet for the await;
+        // restore the prior marker afterward (it may belong to an active disconnect).
+        const prevDisconnecting = disconnectingWalletName;
+        disconnectingWalletName = refreshedTarget.name;
+        try {
+            const disconnectFeature = getWalletFeature(
+                refreshedTarget,
+                StandardDisconnect,
+            ) as StandardDisconnectFeature[typeof StandardDisconnect];
+            await disconnectFeature.disconnect();
         } finally {
-            // Only clean up if no new connect/signIn started while we were awaiting.
-            if (generation === connectGeneration) {
-                disconnectLocally();
+            if (disconnectingWalletName === refreshedTarget.name) {
+                disconnectingWalletName = prevDisconnecting;
+            }
+            // Reflect the now-empty accounts immediately — but only if the store
+            // is still live. If it was disposed while `standard:disconnect`
+            // awaited, the disposer has already torn down every wallet-event
+            // subscription and cleared the map; deauthorizing the target
+            // regenerated its handle, so `reconcileWalletList` returns a fresh
+            // array, and letting `updateState` run here would re-invoke
+            // `syncWalletEventSubscriptions` and re-subscribe every wallet into
+            // the cleared map — listeners the disposer can no longer clean up.
+            if (!disposed) {
+                updateState({ wallets: reconcileWalletList() });
             }
         }
     }
 
     function disconnectLocally(): void {
-        walletEventsCleanup?.();
-        walletEventsCleanup = null;
         disconnectingWalletName = null;
 
         updateState({
@@ -532,14 +623,34 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
     }
 
     function selectAccount(account: UiWalletAccount): void {
-        if (!state.connectedWallet) {
-            throw new SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED, { operation: 'selectAccount' });
+        // Derive the owning wallet from the account handle. `getWalletForHandle`
+        // keys a WeakMap on handle identity, so this is unambiguous even when the
+        // same address is authorized in two wallets. A stale/unregistered handle
+        // throws — surface it as ACCOUNT_NOT_AVAILABLE.
+        let owner: UiWallet;
+        try {
+            owner = getOrCreateUiWalletForStandardWallet(getWalletForHandle(account));
+        } catch {
+            throw new SolanaError(SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE, {
+                account: account.address,
+                operation: 'selectAccount',
+            });
+        }
+
+        // The owner must be currently authorized (discovered + passes the filter).
+        if (!isWalletStillAvailable(owner)) {
+            throw new SolanaError(SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE, {
+                account: account.address,
+                operation: 'selectAccount',
+            });
         }
-        // Reject if this wallet is disconnecting
-        if (state.connectedWallet.name === disconnectingWalletName) {
+
+        // Reject selecting into a wallet that is mid-disconnect.
+        if (owner.name === disconnectingWalletName) {
             throw new SolanaError(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 SolanaError(SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE, {
@@ -547,16 +658,20 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
                 operation: 'selectAccount',
             });
         }
+
         userHasSelected = true;
-        // Bump the generation so this selection supersedes any in-flight
-        // connect/signIn
+        // Supersede any in-flight connect/signIn.
         ++connectGeneration;
-        // Change status back to `connected` if something in-flight changed it
-        // But skip recreating the signer if account is the same as before
+
+        // No-op fast path: the same account is already active.
         if (selectedAccount === state.account && refreshed === state.connectedWallet) {
             updateState({ status: 'connected' });
             return;
         }
+
+        // Switch the active connection (owner may differ from the current one). The
+        // previously-active wallet is left authorized — we never disconnect it. Its
+        // event subscription persists, so switching back stays live.
         const signer = tryCreateSigner(selectedAccount);
         updateState({ account: selectedAccount, connectedWallet: refreshed, signer, status: 'connected' });
         persistAccount(selectedAccount, refreshed);
@@ -564,7 +679,7 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
 
     // -- Message signing ---------------------------------------------------
 
-    async function signMessage(message: Uint8Array, options?: WalletActionOptions): Promise<SignatureBytes> {
+    async function signMessage(message: ReadonlyUint8Array, options?: WalletActionOptions): Promise<SignatureBytes> {
         options?.abortSignal?.throwIfAborted();
         const { connectedWallet, account } = state;
         if (!connectedWallet || !account) {
@@ -581,7 +696,9 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
             account,
             SolanaSignMessage,
         ) as SolanaSignMessageFeature[typeof SolanaSignMessage];
-        const [output] = await signMessageFeature.signMessage({ account, message });
+        // The wallet-standard `SolanaSignMessageInput.message` is a mutable `Uint8Array`; signing
+        // only reads the bytes, so coerce the read-only input at this single boundary.
+        const [output] = await signMessageFeature.signMessage({ account, message: message as Uint8Array });
         return output.signature as SignatureBytes;
     }
 
@@ -842,6 +959,7 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
                 signerListeners.delete(listener);
             };
         },
+        whenReady,
         [Symbol.dispose]: () => {
             // Invalidate any in-flight connect/signIn/silent-reconnect so they
             // bail instead of resuming after disposal (which would re-subscribe
@@ -853,11 +971,20 @@ export function createWalletStore(config: WalletPluginConfig): WalletStore {
             connectGeneration++;
             unsubRegister();
             unsubUnregister();
-            walletEventsCleanup?.();
-            walletEventsCleanup = null;
+            for (const cleanup of walletEventSubscriptions.values()) {
+                cleanup();
+            }
+            walletEventSubscriptions.clear();
             cancelReconnect();
             listeners.clear();
             signerListeners.clear();
+            // A store disposed mid-warm-up will never finish warming up, so
+            // settle the status to 'disconnected'.
+            // Runs after the listener sets are cleared, so no one is notified of
+            // the final transition.
+            if (isWalletWarmingUp(state.status)) {
+                updateState({ status: 'disconnected' });
+            }
         },
     };
 }

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { MessageSigner, SignatureBytes, TransactionSigner } from '@solana/kit';
+import type { MessageSigner, ReadonlyUint8Array, SignatureBytes, TransactionSigner } from '@solana/kit';
 import type { SolanaChain } from '@solana/wallet-standard-chains';
 import type { SolanaSignInInput, SolanaSignInOutput } from '@solana/wallet-standard-features';
 import type { IdentifierString } from '@wallet-standard/base';
@@ -244,13 +244,19 @@ export type WalletNamespace = {
     connect: (wallet: UiWallet, options?: WalletActionOptions) => Promise<readonly UiWalletAccount[]>;
 
     /**
-     * Disconnect the active wallet. Calls `standard:disconnect` if supported.
+     * Disconnect a wallet. Calls `standard:disconnect` if supported.
+     *
+     * `wallet` defaults to the active wallet. Passing a non-active, currently
+     * authorized wallet deauthorizes it (calling `standard:disconnect` if
+     * supported) while leaving the active connection untouched. A `wallet`
+     * that doesn't support `standard:disconnect`, or one that is already
+     * unauthorized/unregistered, is a forgiving no-op.
      *
      * @throws `options.abortSignal.reason` if the signal is already aborted
      *   when the action is called. Aborts after the wallet call has been
      *   dispatched do not take effect.
      */
-    disconnect: (options?: WalletActionOptions) => Promise<void>;
+    disconnect: (wallet?: UiWallet, options?: WalletActionOptions) => Promise<void>;
 
     // -- State --
     /**
@@ -263,13 +269,19 @@ export type WalletNamespace = {
     getState: () => WalletState;
 
     /**
-     * Switch to a different account within the connected wallet. Creates and
-     * caches a new signer for the selected account.
+     * Select an account, creating and caching a new signer for it.
+     *
+     * The account may belong to any currently authorized wallet, not only the
+     * active one. When it belongs to a different authorized wallet, the active
+     * connection switches to that wallet synchronously (no prompt), leaving the
+     * previously active wallet authorized. If the store is currently 'disconnected',
+     * this allows transitioning to 'connected' synchronously.
      *
-     * @throws `SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED)` if no wallet is
-     *   connected, or the connected wallet is currently disconnecting.
      * @throws `SolanaError(SOLANA_ERROR__WALLET__ACCOUNT_NOT_AVAILABLE)` if the
-     *   specified account is not among the connected wallet's accounts.
+     *   account's handle cannot be resolved to a currently authorized wallet, or
+     *   the account is not among that wallet's accounts.
+     * @throws `SolanaError(SOLANA_ERROR__WALLET__NOT_CONNECTED)` if the account's
+     *   wallet is currently disconnecting.
      */
     selectAccount: (account: UiWalletAccount) => void;
 
@@ -321,7 +333,7 @@ export type WalletNamespace = {
      *   when the action is called. Aborts after the wallet call has been
      *   dispatched do not take effect.
      */
-    signMessage: (message: Uint8Array, options?: WalletActionOptions) => Promise<SignatureBytes>;
+    signMessage: (message: ReadonlyUint8Array, options?: WalletActionOptions) => Promise<SignatureBytes>;
 
     /**
      * Subscribe to any wallet state change. Compatible with React's
@@ -335,6 +347,43 @@ export type WalletNamespace = {
      * ```
      */
     subscribe: (listener: () => void) => () => void;
+
+    /**
+     * **Advanced.** Resolves once the initial connection attempt has settled —
+     * i.e. {@link getState}'s `status` is no longer `'pending'` or
+     * `'reconnecting'`.
+     *
+     * You only need this if your app **rebuilds the client at runtime** (for
+     * example, to change chain). Each freshly built client runs a silent
+     * auto-reconnect that briefly passes through `'pending'`/`'reconnecting'`;
+     * awaiting this lets you hold the previous UI until the new client is ready
+     * instead of flashing a "reconnecting" state on every swap. Most apps never
+     * call it — subscribe to `status` with {@link subscribe} instead.
+     *
+     * Does **not** wait for user-initiated `connect`/`disconnect`/`signIn`
+     * (those pass through `'connecting'`/`'disconnecting'`, which count as
+     * ready), so a normal connect never makes this block. While transient it
+     * returns the **same** promise reference on every call, so successive
+     * awaits during one warm-up share a single settlement.
+     *
+     * Disposing the client mid-warm-up settles the status to `'disconnected'`,
+     * so a pending `whenReady()` resolves rather than hanging. Check
+     * {@link getState} after awaiting if you need to distinguish a ready
+     * connection from a disposed (or never-connected) client.
+     *
+     * @returns A promise that resolves with no value once the wallet is past its
+     *   initial `'pending'`/`'reconnecting'` warm-up. Already resolved when the
+     *   status is not transient.
+     *
+     * @example
+     * ```ts
+     * // On a chain switch, hold the old UI until the rebuilt client is ready:
+     * const next = createClient().use(walletSigner({ chain }));
+     * await next.wallet.whenReady();
+     * setClient(next);
+     * ```
+     */
+    whenReady: () => Promise<void>;
 };
 
 /**

package/src/wallet.ts

@@ -22,7 +22,9 @@ function defineSignerGetter(
 ): void {
     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) {