feat: wallet configuration, availability detection, and @stacks/connect 8.2.5 (#2)

* feat: update @stacks/connect to 8.2.5 and leverage WalletConnect.initializeProvider

Pin @stacks/connect to 8.2.5 (from ^8.2.2) picking up bundle size
improvements, provider regression fixes, and the new initializeProvider API.
Pre-initialize WalletConnect only when the user connects with it or when
restoring a wallet-connect session from localStorage.

Closes #1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: add changeset for @stacks/connect update

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use stable primitive dep for session restore effect

Depend on walletConnect?.projectId instead of the walletConnect object
to prevent the effect from re-running on every parent render when the
prop is passed inline.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(example): disable buttons for unavailable wallets

Disable wallet buttons when the extension is not installed, and disable
wallet-connect when no WalletConnect config is provided.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add useAvailableWallets hook

Expose available wallets from the provider context, accounting for both
extension installation and WalletConnect configuration. Consumers no
longer need to manually check wallet availability.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add wallets prop to StacksWalletProvider

Allow consumers to configure which wallets they want to support via a
wallets prop. When omitted, all supported wallets are available.
availableWallets is now the intersection of configured wallets and
installed wallets, with wallet-connect requiring a projectId.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: runtime guard for wallet-connect without projectId

Throw on mount if wallet-connect is in the wallets array but no
walletConnect.projectId was provided. Also wire up the example app
to read WalletConnect project ID from VITE_WALLETCONNECT_PROJECT_ID.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add reset to clear stuck connecting state

When a wallet modal is dismissed without completing (e.g. WalletConnect),
the request promise may never settle, leaving the UI stuck on
"Connecting...". Expose reset via useConnect so consumers can reset the
connection state, matching wagmi's convention.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: update changeset to minor with full scope

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: replace useAvailableWallets with useWallets returning WalletInfo[]

Return all configured wallets with an `available` flag instead of only
available ones. Consumers can now show all wallets and disable
unavailable ones. Also removes `connectors` from useConnect in favor
of useWallets.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: update READMEs with new wallet API

Update Quick Start and API docs to reflect useWallets, wallets prop,
reset, and removal of connectors from useConnect.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: stale connect after reset, WC double-init race, and strict mode guard

- Move runtime guard from render body to useEffect (React Strict Mode safe)
- Add generation counter ref so reset() invalidates in-flight connect() promises
- Guard concurrent WalletConnect.initializeProvider calls with wcInitRef

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add note about OKX popup close not rejecting

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: satoshai-dev

.changeset/update-stacks-connect.md

@@ -0,0 +1,21 @@
+---
+"@satoshai/kit": minor
+---
+
+Update @stacks/connect to 8.2.5 (pinned) and leverage WalletConnect.initializeProvider for faster wallet-connect connections and session restores.
+
+New features:
+- `useWallets` hook — returns configured wallets with `available` flag (installed + configured check)
+- `wallets` prop on `StacksWalletProvider` — configure which wallets to support
+- `reset` on `useConnect` — clear stuck connecting state when wallet modals are dismissed
+- `WalletInfo` type exported for consumers
+- Runtime guard: throws if `wallet-connect` is in `wallets` without a `walletConnect.projectId`
+
+Fixes:
+- Moved runtime guard from render body to `useEffect` (React Strict Mode safe)
+- `reset()` now invalidates in-flight `connect()` promises via generation counter (prevents stale state)
+- Guard against concurrent `WalletConnect.initializeProvider` calls between session restore and connect
+
+Breaking:
+- Removed `useAvailableWallets` (replaced by `useWallets`)
+- Removed `connectors` from `useConnect` (replaced by `useWallets`)

README.md

@@ -10,6 +10,7 @@ Typesafe Stacks wallet & contract interaction library for React. Wagmi-inspired
 
 - **`StacksWalletProvider`** — React context provider for wallet state
 - **`useConnect` / `useDisconnect`** — Connect and disconnect wallets
+- **`useWallets`** — Configured wallets with availability status
 - **`useAddress`** — Access connected wallet address and status
 - **`useSignMessage`** — Sign arbitrary messages
 - **`useWriteContract`** — Call smart contracts with post-conditions
@@ -25,7 +26,7 @@ pnpm add @satoshai/kit @stacks/transactions react react-dom
 ## Quick Start
 
 ```tsx
-import { StacksWalletProvider, useConnect, useAddress, useDisconnect } from '@satoshai/kit';
+import { StacksWalletProvider, useConnect, useWallets, useAddress, useDisconnect } from '@satoshai/kit';
 
 function App() {
   return (
@@ -36,7 +37,8 @@ function App() {
 }
 
 function Wallet() {
-  const { connect, connectors } = useConnect();
+  const { connect, reset, isPending } = useConnect();
+  const { wallets } = useWallets();
   const { address, isConnected } = useAddress();
   const { disconnect } = useDisconnect();
 
@@ -51,9 +53,10 @@ function Wallet() {
 
   return (
     <div>
-      {connectors.map((wallet) => (
-        <button key={wallet} onClick={() => connect(wallet)}>
-          {wallet}
+      {isPending && <button onClick={reset}>Cancel</button>}
+      {wallets.map(({ id, available }) => (
+        <button key={id} onClick={() => connect(id)} disabled={!available || isPending}>
+          {id}
         </button>
       ))}
     </div>

examples/vite-react/.env.example

@@ -0,0 +1 @@
+VITE_WALLETCONNECT_PROJECT_ID=

examples/vite-react/src/app.tsx

@@ -4,12 +4,16 @@ import {
     useConnect,
     useDisconnect,
     useBnsName,
-    SUPPORTED_STACKS_WALLETS,
+    useWallets,
 } from '@satoshai/kit';
 
+const wcProjectId = import.meta.env.VITE_WALLETCONNECT_PROJECT_ID as string | undefined;
+
 export const App = () => {
     return (
-        <StacksWalletProvider>
+        <StacksWalletProvider
+            walletConnect={wcProjectId ? { projectId: wcProjectId } : undefined}
+        >
             <div style={{ fontFamily: 'system-ui', padding: '2rem' }}>
                 <h1>@satoshai/kit Example</h1>
                 <Wallet />
@@ -19,10 +23,11 @@ export const App = () => {
 };
 
 const Wallet = () => {
-    const { connect, isPending } = useConnect();
+    const { connect, reset, isPending } = useConnect();
     const { address, isConnected } = useAddress();
     const { disconnect } = useDisconnect();
     const { bnsName, isLoading: isBnsLoading } = useBnsName(address);
+    const { wallets } = useWallets();
 
     if (isConnected) {
         return (
@@ -46,15 +51,20 @@ const Wallet = () => {
     return (
         <div>
             <h2>Connect a Wallet</h2>
-            {isPending && <p>Connecting...</p>}
+            {isPending && (
+                <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+                    <p>Connecting...</p>
+                    <button onClick={reset}>Cancel</button>
+                </div>
+            )}
             <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', maxWidth: '300px' }}>
-                {SUPPORTED_STACKS_WALLETS.map((wallet) => (
+                {wallets.map(({ id, available }) => (
                     <button
-                        key={wallet}
-                        onClick={() => connect(wallet)}
-                        disabled={isPending}
+                        key={id}
+                        onClick={() => connect(id)}
+                        disabled={isPending || !available}
                     >
-                        {wallet}
+                        {id}{!available ? ' (not available)' : ''}
                     </button>
                 ))}
             </div>

packages/kit/README.md

@@ -6,6 +6,7 @@ Typesafe Stacks wallet & contract interaction library for React. Wagmi-inspired
 
 - **`StacksWalletProvider`** — React context provider for wallet state
 - **`useConnect` / `useDisconnect`** — Connect and disconnect wallets
+- **`useWallets`** — Configured wallets with availability status
 - **`useAddress`** — Access connected wallet address and status
 - **`useSignMessage`** — Sign arbitrary messages
 - **`useWriteContract`** — Call smart contracts with post-conditions
@@ -22,7 +23,7 @@ pnpm add @satoshai/kit @stacks/transactions react react-dom
 ## Quick Start
 
 ```tsx
-import { StacksWalletProvider, useConnect, useAddress, useDisconnect } from '@satoshai/kit';
+import { StacksWalletProvider, useConnect, useWallets, useAddress, useDisconnect } from '@satoshai/kit';
 
 function App() {
   return (
@@ -33,7 +34,8 @@ function App() {
 }
 
 function Wallet() {
-  const { connect, connectors } = useConnect();
+  const { connect, reset, isPending } = useConnect();
+  const { wallets } = useWallets();
   const { address, isConnected } = useAddress();
   const { disconnect } = useDisconnect();
 
@@ -48,9 +50,10 @@ function Wallet() {
 
   return (
     <div>
-      {connectors.map((wallet) => (
-        <button key={wallet} onClick={() => connect(wallet)}>
-          {wallet}
+      {isPending && <button onClick={reset}>Cancel</button>}
+      {wallets.map(({ id, available }) => (
+        <button key={id} onClick={() => connect(id)} disabled={!available || isPending}>
+          {id}
         </button>
       ))}
     </div>
@@ -66,28 +69,52 @@ Wrap your app to provide wallet context to all hooks.
 
 ```tsx
 <StacksWalletProvider
-  walletConnect={{ projectId: '...' }}  // optional — enables WalletConnect
-  onConnect={(provider, address) => {}}  // optional
-  onAddressChange={(newAddress) => {}}   // optional — Xverse account switching
-  onDisconnect={() => {}}                // optional
+  wallets={['xverse', 'leather', 'wallet-connect']}  // optional — defaults to all supported
+  walletConnect={{ projectId: '...' }}                 // optional — enables WalletConnect
+  onConnect={(provider, address) => {}}                // optional
+  onAddressChange={(newAddress) => {}}                 // optional — Xverse account switching
+  onDisconnect={() => {}}                              // optional
 >
   {children}
 </StacksWalletProvider>
 ```
 
+> If `wallets` includes `'wallet-connect'`, you must provide `walletConnect.projectId` or the provider will throw at mount.
+
 ### `useConnect()`
 
 ```ts
-const { connect, connectors, isPending } = useConnect();
+const { connect, reset, isPending } = useConnect();
 
-// connectors = ['xverse', 'leather', 'okx', 'asigna', 'fordefi', 'wallet-connect']
 await connect('xverse');
 await connect('leather', {
   onSuccess: (address, provider) => {},
   onError: (error) => {},
 });
+
+// Reset stuck connecting state (e.g. when a wallet modal is dismissed)
+reset();
 ```
 
+> **Note:** Some wallets (e.g. OKX) never reject the connection promise when the user closes the popup. Use `reset()` to clear the pending state in those cases.
+
+### `useWallets()`
+
+Returns all configured wallets with their availability status.
+
+```ts
+const { wallets } = useWallets();
+// [{ id: 'xverse', available: true }, { id: 'leather', available: false }, ...]
+
+{wallets.map(({ id, available }) => (
+  <button key={id} onClick={() => connect(id)} disabled={!available}>
+    {id}
+  </button>
+))}
+```
+
+A wallet is `available` when its browser extension is installed. For `wallet-connect`, it's `available` when a `walletConnect.projectId` is provided to the provider.
+
 ### `useDisconnect()`
 
 ```ts

packages/kit/package.json

@@ -32,7 +32,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@stacks/connect": "^8.2.2",
+    "@stacks/connect": "8.2.5",
     "bns-v2-sdk": "^2.1.0"
   },
   "peerDependencies": {

packages/kit/src/hooks/use-connect.ts

@@ -2,19 +2,18 @@
 
 import { useMemo } from "react";
 
-import { SUPPORTED_STACKS_WALLETS } from "../constants/wallets";
 import { useStacksWalletContext } from "../provider/stacks-wallet-provider";
 
 export const useConnect = () => {
-  const { connect, status } = useStacksWalletContext();
+  const { connect, reset, status } = useStacksWalletContext();
 
   const value = useMemo(
     () => ({
       connect,
-      connectors: SUPPORTED_STACKS_WALLETS,
+      reset,
       isPending: status === "connecting",
     }),
-    [connect, status]
+    [connect, reset, status]
   );
 
   return value;

packages/kit/src/hooks/use-wallets.ts

@@ -0,0 +1,11 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { useStacksWalletContext } from '../provider/stacks-wallet-provider';
+
+export const useWallets = () => {
+    const { wallets } = useStacksWalletContext();
+
+    return useMemo(() => ({ wallets }), [wallets]);
+};

packages/kit/src/index.ts

@@ -18,12 +18,14 @@ export {
     type PostConditionConfig,
 } from './hooks/use-write-contract/use-write-contract';
 export { useBnsName } from './hooks/use-bns-name';
+export { useWallets } from './hooks/use-wallets';
 
 // Types
 export type {
     WalletState,
     WalletContextValue,
     WalletConnectMetadata,
+    WalletInfo,
     StacksChain,
     ConnectOptions,
 } from './provider/stacks-wallet-provider.types';