@sodax/wallet-sdk-react 1.5.6-beta → 2.0.0-rc.1

package/ai-exported/integration/ai-rules.md

@@ -0,0 +1,136 @@
+# AI Rules — Fresh Integration
+
+You are integrating `@sodax/wallet-sdk-react` into a user's React app for the first time. Follow this protocol exactly.
+
+---
+
+## Workflow (do these in order)
+
+### 1. Survey the project
+
+Before changing anything, gather context:
+
+```bash
+# Framework — Next.js (App Router or Pages)? Vite? CRA?
+cat <user>/package.json | grep -E '"next|"vite|"react-scripts'
+
+# React version — must be >= 19
+cat <user>/package.json | grep '"react"'
+
+# React Query already installed?
+cat <user>/package.json | grep '"@tanstack/react-query'
+
+# Existing wallet libraries that may conflict
+grep -l "wagmi\|@solana/wallet-adapter\|@mysten/dapp-kit" <user>/package.json
+```
+
+**If React < 19**, stop and tell the user — this package requires React 19.
+
+**If wagmi / @solana/wallet-adapter / @mysten/dapp-kit are already direct dependencies**, stop and ask the user — this package mounts those internally; running both will cause duplicate provider context errors.
+
+### 2. Always start with `setup.md`
+
+Read [`recipes/setup.md`](./recipes/setup.md) and apply it. **Do not skip ahead** — every subsequent recipe assumes `SodaxWalletProvider` is already mounted.
+
+### 3. Pick exactly one connect UX
+
+Connect UX is **either / or**, not additive:
+
+- [`recipes/connect-button.md`](./recipes/connect-button.md) — pick this when the app needs to connect one chain at a time, and the UX is a single button per chain.
+- [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md) — pick this when the app needs a chain-picker → connector-picker modal, or when one wallet should connect multiple chains in sequence.
+
+Ask the user which UX they want before applying. If unsure, default to `connect-button.md` (simpler).
+
+### 4. Add advanced features as separate steps
+
+Only after the connect UX works should you add:
+
+- Sign-message flows ([`recipes/sign-message.md`](./recipes/sign-message.md))
+- Bridge to `@sodax/sdk` calls ([`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md))
+- Switch active EVM network ([`recipes/switch-chain.md`](./recipes/switch-chain.md))
+- Chain & wallet detection patterns ([`recipes/chain-detection.md`](./recipes/chain-detection.md))
+- WalletConnect ([`recipes/walletconnect-setup.md`](./recipes/walletconnect-setup.md))
+- Batch connect / disconnect ([`recipes/batch-operations.md`](./recipes/batch-operations.md))
+
+Each is independent — apply only what the user asked for.
+
+### Copy-paste templates
+
+If the user wants a full working starter file rather than narrative steps, point them at [`examples/`](./examples/):
+
+- `01-minimal-evm.tsx` — provider + 1 connect button
+- `02-multi-chain-modal.tsx` — full headless modal
+- `03-nextjs-app-router.tsx` — Next.js 15 SSR setup
+- `04-walletconnect-setup.tsx` — WalletConnect setup (optional single-wallet filter)
+
+Always combine with the narrative recipe — examples are skeletons, recipes explain why each piece exists.
+
+---
+
+## DO
+
+- **DO** put `SodaxWalletProvider` at the app root, inside `QueryClientProvider`. Order matters.
+- **DO** include only the chain slots the user actually needs in `walletConfig`. Each slot mounts a real React provider — unused slots waste bundle size.
+- **DO** use the chain-typed hooks: `useXAccount({ xChainType: 'EVM' })`, not `useXAccount({ xChainId: someId })` unless the user specifically needs per-chain-id resolution.
+- **DO** gate UI on `useConnectedChains().status === 'ready'` whenever you render based on connection state — prevents hydration flicker on Next.js.
+- **DO** use the headless primitives (`useWalletModal`, `useChainGroups`) and let the user style the UI. Do not hand-roll a hidden chain registry.
+- **DO** if Next.js, set `EVM.ssr: true` in `walletConfig`.
+
+---
+
+## DO NOT
+
+- **DO NOT** import from `@sodax/wallet-sdk-react/xchains/<chain>` unless you specifically need a concrete class (e.g. `instanceof XverseXConnector`). Default to barrel imports.
+- **DO NOT** instantiate `XService` or `XConnector` subclasses manually — `SodaxWalletProvider` does this via the chain registry.
+- **DO NOT** call `useXConnect` outside a React component / custom hook.
+- **DO NOT** read from `useXWalletStore` directly. Use the public hooks. The store shape is internal.
+- **DO NOT** stack multiple `SodaxWalletProvider` instances. One per app.
+- **DO NOT** pass changing config references on every render — `SodaxWalletProvider` freezes config on first render. To swap config at runtime, remount with a new `key`.
+- **DO NOT** mock `useXConnect` / `useXAccount` in tests by stubbing the store. Use the real provider with a test config.
+
+---
+
+## Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| User asks for a chain not in the [chain support list](./reference/chain-support.md) | Adding a new chain requires package-level changes (see `../../CLAUDE.md`), not user-app integration. |
+| User wants to use `@sodax/sdk` for swaps / lending / etc. | This package only handles wallet connectivity. Direct user to also install `@sodax/dapp-kit`. |
+| User wants Server Components to use `useXAccount` directly | Hooks are client-only. Must wrap consumer in `'use client'`. |
+| User mentions Next.js Pages Router | Setup differs slightly — confirm before applying App Router defaults. |
+| User asks "how do I connect wallet X" but the connector isn't built in | Check [`reference/connectors.md`](./reference/connectors.md). If absent, the connector doesn't exist yet — flag as out of scope. |
+| User wants custom chains (e.g. EVM testnet not in the default list) | `EVM.chains` accepts custom chain configs, but ChainKey enum is fixed. Confirm before extending. |
+
+---
+
+## Verification protocol (after every recipe)
+
+```bash
+# 1. Type check passes
+pnpm checkTs
+
+# 2. Provider is mounted exactly once
+grep -rn "SodaxWalletProvider" <user-src>           # expect one match
+
+# 3. QueryClientProvider wraps SodaxWalletProvider
+# (manual — open the provider file, confirm nesting order)
+
+# 4. Connect/disconnect works in dev
+# (manual — start dev server, click connect, verify localStorage has `xwagmi-store` key after success)
+```
+
+If steps 1–3 pass and the user confirms step 4, the recipe is done.
+
+---
+
+## Done criteria
+
+The integration is complete when:
+
+- [ ] `pnpm checkTs` exits clean.
+- [ ] `SodaxWalletProvider` is mounted at the app root with the user's chosen `walletConfig`.
+- [ ] `QueryClientProvider` wraps `SodaxWalletProvider`.
+- [ ] At least one connect UX (button or modal) is wired and works in the user's dev environment.
+- [ ] If using `@sodax/sdk` features: `useWalletProvider` is used to bridge to SDK calls (see `recipes/setup.md` § "Pair with `@sodax/sdk`").
+
+Do not declare integration done before all of the above are true.

package/ai-exported/integration/architecture.md

@@ -0,0 +1,181 @@
+# Architecture — Mental Model
+
+This file explains **why** `@sodax/wallet-sdk-react` is shaped the way it is. Read it once before applying recipes — knowing the model lets you handle ambiguous user code without inventing migrations.
+
+If you are looking for "how do I do X", go to [`recipes/`](./recipes/). This file is purely conceptual.
+
+---
+
+## The shape of the package
+
+`@sodax/wallet-sdk-react` is a **uniform React layer over heterogeneous chain wallet libraries**. Each chain family ships a different React adapter (wagmi, `@solana/wallet-adapter-react`, `@mysten/dapp-kit`) or no React adapter at all (Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). The package wraps all nine families behind one set of hooks so consumer code does not branch on chain family.
+
+Two abstractions make this work:
+
+- **`XConnector`** — represents a *wallet* on a *chain family* (e.g. MetaMask on EVM, Phantom on Solana, Xverse on Bitcoin). Knows how to `connect()`, `disconnect()`, expose `id` / `name` / `icon` / `isInstalled`.
+- **`XService`** — represents a *chain family* (one per `ChainType`). Holds the list of available connectors, the current active connection, and exposes a chain-family-specific `IXxxWalletProvider` once connected.
+
+Hooks always operate on `XService` / `XConnector` — never directly on a chain library's primitives. Consumers do not import `useAccount` from wagmi; they call `useXAccount({ xChainType: 'EVM' })` and get back a uniform `XAccount` shape.
+
+---
+
+## The provider mount tree
+
+`<SodaxWalletProvider config={...}>` mounts only the chain-type slots present in `config`. The internal nesting order is fixed:
+
+```
+<WalletConfigProvider value={frozenConfig}>
+  <EvmProvider config={config.EVM}>           ← only if EVM slot present (mounts wagmi.WagmiProvider)
+    <SuiProvider config={config.SUI}>          ← only if SUI slot present (mounts dapp-kit providers)
+      <SolanaProvider config={config.SOLANA}>  ← only if SOLANA slot present (mounts solana-wallet-adapter)
+        {children}
+      </SolanaProvider>
+    </SuiProvider>
+  </EvmProvider>
+</WalletConfigProvider>
+```
+
+Three things to internalize:
+
+1. **Slot opt-in is real.** Omitting `config.SOLANA` means `@solana/wallet-adapter-react` is **not** in the React tree at all — zero runtime cost, smaller bundle. `useXConnectors({ xChainType: 'SOLANA' })` returns `[]` and logs a one-time warning. Apps that only use EVM should pass only `{ EVM: {...} }`.
+2. **Provider-managed vs registered chains.** EVM/Solana/Sui have native React adapters and need a provider tree node. Bitcoin/Stellar/ICON/Injective/NEAR/Stacks register their `XService` at mount time via `useInitChainServices` — no provider node, no React context for the underlying SDK.
+3. **`QueryClientProvider` must wrap `<SodaxWalletProvider>`.** v2 does *not* mount a `QueryClient` internally (v1 did). `useXConnect`, `useXSignMessage`, batch hooks all depend on React Query — without an outer `QueryClientProvider` they throw at runtime, not at type-check.
+
+---
+
+## Config is captured once
+
+`<SodaxWalletProvider config>` freezes `config` with `useRef` on first render. Subsequent renders with a new reference have **no effect**. Reasons:
+
+- **Wagmi config-object identity matters.** wagmi reconnects if the config object identity changes; reactive configs caused reconnect storms in v1.
+- **Predictable startup.** Apps should compose chain config once at module scope, not derive it dynamically from props.
+
+To swap config at runtime, remount with a new `key`:
+
+```tsx
+<SodaxWalletProvider key={configVersion} config={walletConfig}>
+  {children}
+</SodaxWalletProvider>
+```
+
+This is the only supported way to change config — there is no `setConfig` API.
+
+---
+
+## State: Zustand store + adapter sync
+
+The package keeps connection state in a Zustand store keyed by `ChainType`. The store hook **is not exported** — consumers read state through public hooks (`useXAccount`, `useXService`, `useWalletProvider`, …), each of which subscribes to the relevant slice internally. The shape below is informational only:
+
+```ts
+// internal shape — do NOT import
+{
+  xServices:     Partial<Record<ChainType, IXService>>,
+  xConnections:  Partial<Record<ChainType, XConnection>>,
+  // …plus internal mutations
+}
+```
+
+Two things matter to consumers:
+
+1. **Provider-managed chains sync state from the adapter.** EVM/Solana/Sui each have a `<Hydrator>` that watches its native adapter (wagmi `useAccount`, etc.) and writes the active connection into `xConnections`. Hooks read from the Zustand store, so they see one consistent view across all chains.
+2. **Persistence: `xwagmi-store` localStorage key, kept stable from v1.** Renaming would log out every existing user. Hydration runs lazily — the first render after refresh has `xConnections = {}` even if storage has data. Hooks expose this via `useConnectedChains().status === 'ready'` — gate UI on that to avoid hydration flicker on Next.js.
+
+You should **not** read the store directly. Use the public hooks. The store hook itself is not exported from v2 — see [`reference/api-surface.md`](./reference/api-surface.md) § "Not exported".
+
+---
+
+## Wallet discovery (EIP-6963 + custom)
+
+For EVM, available wallets are discovered via [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) — browser extensions broadcast their metadata and `useXConnectors({ xChainType: 'EVM' })` builds the list at runtime. No hardcoded wallet registry; new wallets installed by the user appear without an SDK update.
+
+Other chains ship a curated connector list (Bitcoin: Xverse / Unisat / OKX, Sui: dapp-kit's standard connectors, Solana: wallet-adapter's standard connectors, etc.). For each connector, `isInstalled` reflects whether the underlying extension/wallet is detected. `sortConnectors(list, { preferred })` puts installed connectors first — call it once in your render path; the result is stable per render.
+
+---
+
+## Chain identifiers — `xChainType` vs `xChainId`
+
+Two parallel addressing schemes:
+
+- **`xChainType: ChainType`** — family-level (`'EVM'`, `'SOLANA'`, `'BITCOIN'`, …). 9 values total.
+- **`xChainId: SpokeChainKey`** — chain-specific key from `@sodax/types` (`ChainKeys.ETHEREUM_MAINNET`, `ChainKeys.BSC_MAINNET`, …). 20 values today.
+
+Hooks that accept both enforce **exactly one** at runtime *and* at the type level. Passing both, neither, or `undefined` for both throws.
+
+```ts
+useXAccount({ xChainType: 'EVM' });                              // ✅ family-level
+useXAccount({ xChainId: ChainKeys.BSC_MAINNET });                // ✅ key-level
+useXAccount({ xChainType: 'EVM', xChainId: ChainKeys.BSC });     // ❌ throws
+useXAccount({});                                                 // ❌ throws
+```
+
+When to pick which:
+
+- **Use `xChainType`** for family-level reads (e.g. "is the user connected to *any* EVM chain?"). One connection covers every configured EVM network.
+- **Use `xChainId`** when you need the narrowest TypeScript inference (e.g. `useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET })` returns `IEvmWalletProvider | undefined`, not the broader `IWalletProvider`).
+
+The chain-id form is required when handing off to `@sodax/sdk` — SDK calls take a chain-narrowed wallet provider.
+
+---
+
+## EVM is one connection across every configured EVM network
+
+A subtle but important model choice: wagmi treats every configured EVM chain as one connector session. v2 reflects this directly — `useChainGroups()` collapses EVM into a single row, and `useXAccount({ xChainType: 'EVM' })` returns the same `address` regardless of which chain the user is currently on.
+
+Consequences:
+
+- **No per-EVM-network connect/disconnect UI.** "Connect to Ethereum" and "Connect to BSC" are the same operation.
+- **Switching networks does not re-connect.** `useEvmSwitchChain({ xChainId })` calls wagmi's `switchChain` and fires the `chainChanged` EIP-1193 event. The connector stays connected.
+- **`useEvmSwitchChain` owns the "wrong network" comparison.** Pass the *expected* `xChainId`; the hook returns `{ isWrongChain, handleSwitchChain }`. Don't recompute this in UI code.
+- **Injective + MetaMask special case.** `useEvmSwitchChain` auto-switches to Ethereum mainnet when the user connects to Injective via MetaMask (Injective has a separate native chain but uses MetaMask's EVM signing for some flows). Transparent to consumers.
+
+Other chain families do **not** have this single-connection model — Bitcoin connects to one address per connector, Solana to one wallet, etc.
+
+---
+
+## Bridging to `@sodax/sdk`
+
+The `IXxxWalletProvider` interface is the contract between this package and `@sodax/sdk`. Consumers call `useWalletProvider({ xChainId })` to get a chain-narrowed provider, then pass it to SDK methods:
+
+```ts
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { useSwap } from '@sodax/dapp-kit';
+import { ChainKeys } from '@sodax/types';
+
+const evm = useWalletProvider({ xChainId: ChainKeys.ETHEREUM_MAINNET });
+// evm: IEvmWalletProvider | undefined
+
+const swap = useSwap();
+if (evm) await swap.mutateAsync({ ..., walletProvider: evm });
+```
+
+The wallet provider is `undefined` until the user is connected on that chain family. SDK calls should always guard on `!= undefined`. See [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md) for the full pattern.
+
+---
+
+## What lives where (file-system tour)
+
+```
+src/
+├── SodaxWalletProvider.tsx     # Root provider — mounts slots conditionally
+├── core/                       # XService + XConnector abstract base classes
+├── context/                    # WalletConfigContext (frozen config injection)
+├── hooks/                      # All public `useXxx` hooks (read-only)
+├── actions/                    # Imperative helpers (getXService, getXChainType)
+├── utils/                      # sortConnectors, walletRpcConfig, isNativeToken
+├── types/                      # Public types — config, interfaces, chainActions
+├── providers/                  # Per-chain-type React provider implementations
+└── xchains/<chain>/            # Per-chain XService + XConnector implementations
+    │                           # Sub-path import: '@sodax/wallet-sdk-react/xchains/<chain>'
+    └── ...                     # Auto-discovered by tsup; not re-exported from barrel
+```
+
+Adding a new chain = create `src/xchains/<chain>/index.ts`. tsup picks it up automatically; the package barrel does not need editing.
+
+---
+
+## Things that look weird until you know why
+
+- **`useXAccount` returns an object with `address: undefined` when disconnected**, not `undefined` itself. Avoids `account?.address` chains everywhere.
+- **`useXConnect` resolves to `undefined` for provider-managed chains** (EVM/Solana/Sui). The mutation kicks off the adapter's connect flow; the address arrives via the adapter's state, not the mutation result. Read it via `useXAccount` after the mutation lands.
+- **`useEvmSwitchChain` returns `{ isWrongChain: false, handleSwitchChain: noop }` if EVM is not in `walletConfig`.** Same shape, no-op behavior — so UI code does not need to branch on "is EVM enabled".
+- **Concrete chain classes are not on the barrel.** `XverseXConnector`, `EvmXService`, etc. live behind `@sodax/wallet-sdk-react/xchains/<chain>`. Default to barrel imports; opt into deep imports only when you need `instanceof` or to extend a class.

package/ai-exported/integration/examples/01-minimal-evm.tsx

@@ -0,0 +1,75 @@
+/**
+ * Minimal EVM setup — provider + single connect button.
+ * Smallest working integration of @sodax/wallet-sdk-react.
+ *
+ * Run: drop this file in a Vite/CRA app, render <App /> at the root.
+ */
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  SodaxWalletProvider,
+  type SodaxWalletConfig,
+  useXAccount,
+  useXConnect,
+  useXConnectors,
+  useXDisconnect,
+} from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+// Module-level constants — never recreate these inside a component.
+const queryClient = new QueryClient();
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: false,
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
+    },
+  },
+};
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <SodaxWalletProvider config={walletConfig}>
+        <ConnectButton />
+      </SodaxWalletProvider>
+    </QueryClientProvider>
+  );
+}
+
+function ConnectButton() {
+  const connectors = useXConnectors({ xChainType: 'EVM' });
+  const { mutateAsync: connect, isPending } = useXConnect();
+  const account = useXAccount({ xChainType: 'EVM' });
+  const disconnect = useXDisconnect();
+
+  if (account.address) {
+    return (
+      <div>
+        <code>{account.address}</code>
+        <button type="button" onClick={() => disconnect({ xChainType: 'EVM' })}>
+          Disconnect
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {connectors.map((connector) => (
+        <button
+          type="button"
+          key={connector.id}
+          onClick={() => connect(connector).catch(() => {})}
+          disabled={isPending || !connector.isInstalled}
+        >
+          {connector.name}
+          {!connector.isInstalled && ' (not installed)'}
+        </button>
+      ))}
+    </div>
+  );
+}

package/ai-exported/integration/examples/02-multi-chain-modal.tsx

@@ -0,0 +1,169 @@
+/**
+ * Multi-chain headless wallet modal.
+ * Renders chain picker → wallet picker → connecting → success/error using `useWalletModal`.
+ *
+ * UI uses native <dialog> — replace with shadcn/Radix/your dialog primitive.
+ */
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  SodaxWalletProvider,
+  type SodaxWalletConfig,
+  useWalletModal,
+  useChainGroups,
+  useXConnectors,
+  sortConnectors,
+  type IXConnector,
+} from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+import { ChainKeys } from '@sodax/types';
+
+const queryClient = new QueryClient();
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+    },
+  },
+  SOLANA: {
+    chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://api.mainnet-beta.solana.com' } },
+  },
+  SUI: { network: 'mainnet' },
+  BITCOIN: {},
+  ICON: {
+    chains: { [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' } },
+  },
+};
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <SodaxWalletProvider config={walletConfig}>
+        <WalletModalRoot />
+      </SodaxWalletProvider>
+    </QueryClientProvider>
+  );
+}
+
+function WalletModalRoot() {
+  const modal = useWalletModal({
+    onConnected: (chainType, account) => {
+      console.log('connected', chainType, account.address);
+    },
+  });
+
+  switch (modal.state.kind) {
+    case 'closed':
+      return (
+        <button type="button" onClick={modal.open}>
+          Connect Wallet
+        </button>
+      );
+
+    case 'chainSelect':
+      return <ChainPicker onPick={modal.selectChain} onClose={modal.close} />;
+
+    case 'walletSelect':
+      return (
+        <WalletPicker
+          chainType={modal.state.chainType}
+          onPick={modal.selectWallet}
+          onBack={modal.back}
+          onClose={modal.close}
+        />
+      );
+
+    case 'connecting':
+      // Hide modal while wagmi's QR modal owns the screen for WalletConnect
+      if (modal.state.connector.id === 'walletConnect') return null;
+      return (
+        <Dialog onClose={modal.close}>
+          <p>Approve in {modal.state.connector.name}…</p>
+          <button type="button" onClick={modal.back}>
+            Cancel
+          </button>
+        </Dialog>
+      );
+
+    case 'error':
+      return (
+        <Dialog onClose={modal.close}>
+          <p>Error: {modal.state.error.message}</p>
+          {!modal.state.connector.isInstalled && modal.state.connector.installUrl && (
+            <a href={modal.state.connector.installUrl} target="_blank" rel="noreferrer">
+              Install {modal.state.connector.name}
+            </a>
+          )}
+          <button type="button" onClick={modal.retry}>
+            Retry
+          </button>
+          <button type="button" onClick={modal.back}>
+            Pick another wallet
+          </button>
+        </Dialog>
+      );
+
+    case 'success':
+      // onConnected fired; close the modal
+      queueMicrotask(modal.close);
+      return null;
+
+    default:
+      return null;
+  }
+}
+
+function ChainPicker({ onPick, onClose }: { onPick: (c: ChainType) => void; onClose: () => void }) {
+  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'SUI', 'BITCOIN', 'ICON'] });
+  return (
+    <Dialog onClose={onClose}>
+      <h2>Select a chain</h2>
+      {groups.map(group => (
+        <button type="button" key={group.chainType} onClick={() => onPick(group.chainType)}>
+          <span>{group.displayName}</span>
+          {group.isConnected && ' ✓'}
+        </button>
+      ))}
+    </Dialog>
+  );
+}
+
+const PREFERRED = ['hana', 'metamask', 'phantom'] as const;
+
+function WalletPicker({
+  chainType,
+  onPick,
+  onBack,
+  onClose,
+}: {
+  chainType: ChainType;
+  onPick: (c: IXConnector) => void;
+  onBack: () => void;
+  onClose: () => void;
+}) {
+  const connectors = sortConnectors(useXConnectors({ xChainType: chainType }), { preferred: PREFERRED });
+  return (
+    <Dialog onClose={onClose}>
+      <button type="button" onClick={onBack}>
+        ← Back
+      </button>
+      <h2>Connect to {chainType}</h2>
+      {connectors.map(connector => (
+        <button type="button" key={connector.id} onClick={() => onPick(connector)} disabled={!connector.isInstalled}>
+          {connector.name}
+          {!connector.isInstalled && ' (not installed)'}
+        </button>
+      ))}
+    </Dialog>
+  );
+}
+
+function Dialog({ children, onClose }: { children: React.ReactNode; onClose: () => void }) {
+  return (
+    <dialog open onClose={onClose} style={{ padding: 16 }}>
+      {children}
+    </dialog>
+  );
+}

package/ai-exported/integration/examples/03-nextjs-app-router.tsx

@@ -0,0 +1,99 @@
+/**
+ * Next.js 15 App Router setup with SSR-safe hydration.
+ *
+ * This file shows three separate files merged into one for reference. In your
+ * project, split them into the matching paths:
+ *
+ *   app/
+ *   ├── layout.tsx     ← server component (RootLayout below — make it the file's `export default`)
+ *   ├── providers.tsx  ← client component (Providers below — needs `'use client'` at top of file)
+ *   └── page.tsx       ← client component (Home below — needs `'use client'` at top of file)
+ *
+ * Key SSR points:
+ * - `EVM.ssr: true` enables wagmi cookie-based hydration.
+ * - `'use client'` on every component that calls a hook from this package.
+ * - QueryClient as a module constant — one client per app, never recreated.
+ * - SodaxWalletProvider config also a module constant — frozen on first render.
+ *
+ * NOTE: this combined file uses named exports only so it lints clean. Each of
+ * `RootLayout`, `Providers`, and `Home` should be the `export default` of its
+ * own file in your real project.
+ */
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { SodaxWalletProvider, type SodaxWalletConfig, useConnectedChains } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+import type { ReactNode } from 'react';
+
+// ============================================================
+// app/providers.tsx — client component
+// (top of file: `'use client';`)
+// ============================================================
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 60 * 1000 },
+  },
+});
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true, // ← required for Next.js — enables wagmi cookies hydration
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
+    },
+  },
+};
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+    </QueryClientProvider>
+  );
+}
+
+// ============================================================
+// app/layout.tsx — server component
+// (no `'use client'`; in your real file, change `export function` to `export default function`)
+// ============================================================
+
+export function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+
+// ============================================================
+// app/page.tsx — client component (because we use a hook)
+// (top of file: `'use client';`; change `export function` to `export default function`)
+// ============================================================
+
+export function Home() {
+  // Gate UI on hydration to prevent reload flicker
+  const { chains, status } = useConnectedChains();
+
+  if (status === 'loading') {
+    return <p>Loading…</p>;
+  }
+
+  if (chains.length === 0) {
+    return <p>No wallets connected</p>;
+  }
+
+  return (
+    <ul>
+      {chains.map((c) => (
+        <li key={c.chainType}>
+          {c.chainType}: <code>{c.account.address}</code>
+        </li>
+      ))}
+    </ul>
+  );
+}