@usebutr/core 2.0.1 → 3.0.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { StoreApi } from "zustand/vanilla";
 //#region src/types/chain.d.ts
 /**
  * CAIP-2 shaped. butr never reads past these four fields, so consumers
@@ -6,13 +7,19 @@
 type ChainBase = {
   /** CAIP-2 identifier, e.g. "eip155:1", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" */
   id: string;
-  /** Human-readable name, e.g. "Ethereum", "Solana" */
+  /** Human-readable chain name, e.g. "Ethereum". Never the wallet's name. */
   name: string;
   /** CAIP-2 namespace, e.g. "eip155", "solana" */
   namespace: string;
   /** CAIP-2 reference, e.g. "1", "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" */
   reference: string;
 };
+/**
+ * Wallets report bare CAIP-2 ids, so the display name comes from a chain
+ * registry. A chain outside `known` keeps its id as its name rather than
+ * borrowing the wallet's.
+ */
+declare const resolveChain: (id: string, known?: ReadonlyArray<ChainBase>) => ChainBase;
 //#endregion
 //#region src/types/account.d.ts
 type Account = {
@@ -37,47 +44,6 @@ type Balance = {
   value: bigint;
 };
 //#endregion
-//#region src/types/capabilities.d.ts
-/**
- * Each flag means "can this work right now", not "is the method
- * defined": `signMessage: false` means the call would reject,
- * `switchChain: false` means switching is a no-op for every chain.
- */
-type WalletCapabilities = {
-  /** `getBalance` returns a real on-chain value (vs. a 0n placeholder). */
-  getBalance: boolean;
-  /** `getTransactionReceipt` returns a real RPC response. */
-  getTransactionReceipt: boolean;
-  /** Calling `requestAccounts` will actually do something: either
-   *  prompt the user (EIP-2255) or refresh the exposed list. */
-  requestAccounts: boolean;
-  /** `sendTx` / `sendTxToChain` will work. False for SVM wallets that
-   *  don't advertise `solana:signAndSendTransaction`. */
-  sendTransaction: boolean;
-  /** `signIn` works: Sign In With Solana (`solana:signIn`). True only
-   *  for SVM wallets advertising the feature. */
-  signIn: boolean;
-  /** `signMessage` will work. False for SVM wallets that don't
-   *  advertise `solana:signMessage`. */
-  signMessage: boolean;
-  /** `signTransaction` returns a signed-but-unbroadcast transaction the
-   *  consumer submits with their own RPC client. True only for SVM
-   *  wallets advertising `solana:signTransaction`; butr ships no RPC so
-   *  it can't broadcast the result itself. EVM/hardware adapters leave
-   *  this `false` (no `signTransaction` method). */
-  signTransaction: boolean;
-  /** Wallet emits account/chain change events that butr can bridge. */
-  subscribe: boolean;
-  /** `switchAccount` is real. Almost always `false` for auto adapters;
-   *  neither protocol exposes silent account switch. Hand-rolled
-   *  adapters with custom transports may set it `true`. */
-  switchAccount: boolean;
-  /** `switchChain` routes subsequent calls through the new chain. EVM:
-   *  true via `wallet_switchEthereumChain`. SVM: true (local state +
-   *  per-call `chain` input) when more than one chain is advertised. */
-  switchChain: boolean;
-};
-//#endregion
 //#region src/types/platform.d.ts
 /**
  * Single runtime source of truth: `ChainPlatform` and the storage
@@ -86,246 +52,267 @@ type WalletCapabilities = {
  */
 declare const CHAIN_PLATFORMS: readonly ["evm", "svm", "sui", "bitcoin", "polkadot"];
 type ChainPlatform = (typeof CHAIN_PLATFORMS)[number];
+declare const isChainPlatform: (value: string) => value is ChainPlatform;
 //#endregion
 //#region src/types/chains-by-platform.d.ts
-/**
- * Values come from the per-platform packages (`EVM_CHAINS_LIST`,
- * `SVM_CHAINS_LIST`, …); an empty list opts that platform out of the
- * consumer's chain UI.
- */
+/** An empty list opts that platform out of the consumer's chain UI. */
 type ChainsByPlatform = Readonly<Record<ChainPlatform, ReadonlyArray<ChainBase>>>;
-/**
- * Naming only the platforms an app targets keeps the other packages'
- * chain registries out of its bundle. Apps that want all of them import
- * `CHAINS_BY_PLATFORM` from `@usebutr/wallets`.
- */
-declare const buildChainsByPlatform: (partial: Partial<ChainsByPlatform>) => {
-  bitcoin: readonly ChainBase[];
-  evm: readonly ChainBase[];
-  polkadot: readonly ChainBase[];
-  sui: readonly ChainBase[];
-  svm: readonly ChainBase[];
-};
 //#endregion
 //#region src/types/connector.d.ts
 /**
- * Gate Connect on `installed` or `loadable`: a `loadable` wallet has no
- * extension yet still connects (WalletConnect's QR modal). Only
- * `not-installed` should degrade to a download link at `meta.url`.
- */
-type WalletAvailability = "installed" | "loadable" | "not-installed";
-/**
- * `accountChanged` must carry every account the wallet still exposes,
- * not just the new active one: the runtime mirrors the array verbatim
- * into the pool entry. Chain switches arrive as `account.chain`.
+ * `accounts` carries every account the wallet still exposes, active first;
+ * the runtime mirrors it verbatim into the pool entry. Chain switches
+ * arrive as a changed `account.chain`. An empty list is `disconnected`.
  */
 type ConnectorEvent = {
-  account: Account;
-  accounts: Array<Account>;
-  type: "accountChanged";
+  accounts: ReadonlyArray<Account>;
+  type: "accountsChanged";
 } | {
   type: "disconnected";
 };
 /**
- * Orchestration interface: what `butr` actually calls during the
- * connect / disconnect / hydrate flow. This is the contract `butr`
- * cares about; everything else on `WalletAdapter` is consumer-facing.
+ * What butr itself calls during connect, disconnect and hydration. Optional
+ * members are defined only when they work for this wallet, so presence is
+ * the capability check.
  */
 type Connector<P extends ChainPlatform = ChainPlatform> = {
-  /** Runtime capability flags; see `WalletCapabilities`. Read these
-   *  to gate UI affordances rather than probing for method existence. */
-  capabilities: WalletCapabilities;
-  /** Discriminant: which chain platform this adapter speaks. Generic
-   *  parameter `P` narrows this to a specific platform when consumers
-   *  use one of the per-platform adapter types (`EvmAdapter`,
-   *  `SvmAdapter`, etc). */
+  /** Discriminant: which chain platform this adapter speaks. */
   chainPlatform: P;
-  /** `opts.silent` is hydration's non-interactive reconnect (Wallet
+  /** `options.silent` is hydration's non-interactive reconnect (Wallet
    *  Standard `standard:connect` silent input, `eth_accounts` on
    *  EIP-1193). An adapter that cannot honour it must reject instead of
    *  prompting; hydration reads that as a clean restore failure. */
-  connect: (opts?: {
+  connect: (options?: {
     silent?: boolean;
   }) => Promise<void>;
-  /** Optional teardown. butr calls this on disconnect, error recovery, and reset. */
+  /** Teardown. butr calls it on disconnect, failed connects and reset. */
   disconnect?: () => Promise<void>;
-  /** Read the currently-active account. butr uses this to populate the pool
-   *  after a successful `connect()` and during hydration. */
-  getAccount: () => Promise<Account | null>;
-  /** Optional. List every account the wallet exposes. Some browser wallets
-   *  show many accounts at once (MetaMask with multiple imports). If
-   *  omitted, butr defaults to `[await getAccount()]`. */
-  getAccounts?: () => Promise<Array<Account>>;
+  /** Every account the wallet exposes, active account first. Empty when
+   *  the wallet is not connected. */
+  getAccounts: () => Promise<ReadonlyArray<Account>>;
   /** Discovery runs `sanitizeIcon` at construction, so on discovered
-   *  adapters this is a trimmed non-empty string or `undefined`: render
-   *  it straight into `next/image` with no re-sanitizing and no
-   *  `icon !== ""` guard. Hand-rolled adapters own that guarantee. */
+   *  adapters this is a trimmed non-empty string or `undefined`. Hand-rolled
+   *  adapters own that guarantee. */
   icon?: string;
-  /** Stable key: "metamask", "phantom", etc. Pool entries are keyed by this. */
+  /** Stable key: "io.metamask", "wallet-standard:svm-phantom", etc. Pool
+   *  entries are keyed by this. */
   id: string;
   /** Human name: "MetaMask", "Phantom", etc. UI-facing only. */
   name: string;
   /** Opens the wallet's account-selection UI (`wallet_requestPermissions`
-   *  on EIP-6963; usually unset on Wallet Standard). Resolution does not
-   *  carry the new accounts: follow it with `getAccounts()`, or use the
-   *  `useRequestAccounts` hook which refreshes the pool entry. */
+   *  on EIP-1193). Resolution does not carry the new accounts; the
+   *  manager's `requestAccounts` action refreshes the pool entry. */
   requestAccounts?: () => Promise<void>;
-  /** Bridges native wallet events (`accountsChanged`, `chainChanged`, …)
-   *  into the reducer. Only `ConnectorLifecycle` may call this, and it
-   *  guarantees at most one live subscription per connector. */
+  /** Bridges native wallet events into the reducer. Only the manager's
+   *  connector lifecycle calls this, at most once per live connector. */
   subscribe?: (listener: (event: ConnectorEvent) => void) => () => void;
 };
-type ConnectorMeta = {
-  /** Optional. Sync probe that reports whether the wallet is currently
-   *  available. Defaults to `"installed"` when omitted. Consumers call
-   *  this at render time to gate the "Connect" button. */
-  availability?: () => WalletAvailability;
+//#endregion
+//#region src/storage/persistence.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/** Low-level key/value driver. Sync on web (localStorage, MMKV),
+ *  async on React Native (AsyncStorage). */
+type StorageDriver = {
+  getItem: (key: string) => MaybePromise<string | null>;
+  removeItem: (key: string) => MaybePromise<void>;
+  setItem: (key: string, value: string) => MaybePromise<void>;
+};
+/** Everything needed to render a connection before its adapter exists:
+ *  the shadow adapter shows this identity until silent reconnect lands. */
+type StoredPoolEntry = {
+  account: Account;
+  accounts: ReadonlyArray<Account>;
   chainPlatform: ChainPlatform;
-  /** Optional image URL or data URI for wallet selection UIs. Unlike
-   *  `Connector.icon`, this one is consumer-supplied and butr does not
-   *  sanitize it; run it through `sanitizeIcon` if the value came from
-   *  wallet metadata rather than your own assets. */
+  connectorId: string;
   icon?: string;
-  id: string;
   name: string;
-  /** Optional. Where to send users who don't have this wallet (download
-   *  page, app store link, etc.). */
-  url?: string;
 };
+type StoredPoolRecord = Partial<Record<string, StoredPoolEntry>>;
+type StoredSelectionRecord = Partial<Record<ChainPlatform, string>>;
+/**
+ * Carries no `Connector` by design: a wallet extension exists only in the
+ * browser, so a server render can name the wallet and its address but can
+ * never dispatch on it.
+ */
+type WalletSnapshot = {
+  activeConnectorId: string | null;
+  pool: StoredPoolRecord;
+  selection: StoredSelectionRecord;
+};
+type PersistedWalletState = WalletSnapshot & {
+  /** Session-scoped: a manual disconnect suppresses auto-connect for this
+   *  session, not forever. */
+  isUserDisconnected: boolean;
+};
+/**
+ * `save` receives the whole derived state after every change, so an
+ * implementation never merges or diffs. A `load` rejection is reported
+ * through `onStorageError` and treated as empty storage.
+ */
+type WalletPersistence = {
+  load: () => Promise<PersistedWalletState>;
+  save: (state: PersistedWalletState) => Promise<void>;
+};
+//#endregion
+//#region src/types/signer.d.ts
+/**
+ * Filled by each transport package through module augmentation, e.g.
+ * `interface WalletSignerRegistry { eip1193: { provider: Eip1193Provider } }`.
+ * Keyed by transport, not platform: EVM through a Ledger is not EIP-1193.
+ */
+interface WalletSignerRegistry {}
+/** Narrow with `switch (signer.kind)`; each branch is fully typed. */
+type WalletSigner = { [K in keyof WalletSignerRegistry]: {
+  kind: K;
+} & WalletSignerRegistry[K]; }[keyof WalletSignerRegistry];
+type WalletSignerKind = WalletSigner["kind"];
+type WalletSignerOf<K extends WalletSignerKind> = Extract<WalletSigner, {
+  kind: K;
+}>;
 //#endregion
 //#region src/types/wallet.d.ts
 type SignInInput = {
   readonly [key: string]: SignInValue;
 };
 type SignInValue = boolean | number | string | null | ReadonlyArray<SignInValue> | SignInInput;
-type TransactionObject = {
-  readonly [key: string]: TransactionValue | undefined;
-};
-type TransactionMethod = (...args: ReadonlyArray<never>) => Promise<string>;
-type TransactionValue = bigint | boolean | number | string | null | Uint8Array | ReadonlyArray<TransactionValue> | TransactionObject | TransactionMethod;
-type TransactionInput = TransactionObject | string | Uint8Array;
-type WalletSigner = object;
-/**
- * Methods every connected wallet supports regardless of chain. The
- * per-platform `Wallet` types extend this with their platform-specific
- * methods (`signIn` for SVM, `signTransaction` for sign-only paths).
- */
-type WalletBase = {
-  /** Read a token balance. `mint` is optional; the connector decides
-   *  what "no mint" means for its chain (native ETH on EVM, native SOL
-   *  on Solana, etc.). */
-  getBalance: (mint?: string) => Promise<Balance>;
-  /** Returns a chain-specific signer. Consumers cast to the concrete
-   *  type via the `SignerForPlatform` registry (or directly to the
-   *  library shape they wrap: `WalletClient` on viem, etc.). */
+type SignedMessage = {
+  signature: Uint8Array;
+  signedMessage: Uint8Array;
+};
+type TransactionReceipt = {
+  status: "Error" | "Pending" | "Success";
+};
+/** Acts as `account`, which must be one the wallet exposes; an unknown one
+ *  rejects rather than signing with another. Omitted, the wallet uses its own
+ *  active account, so pass `wallet.account` to honour `setAccount`. */
+type AccountOptions = {
+  account?: Account;
+};
+/**
+ * `chain` targets this one transaction. Wallet Standard routes it per call;
+ * an EVM wallet has one global network, so it switches first; a transport
+ * that can do neither rejects when `chain` is not its current chain.
+ */
+type TransactionOptions = AccountOptions & {
+  chain?: ChainBase;
+};
+/** `token` is chain-specific: an ERC-20 contract address on EVM. Omit it for
+ *  the native asset. */
+type BalanceOptions = AccountOptions & {
+  token?: string;
+};
+/**
+ * Presence is the capability check: an adapter defines an optional method
+ * only when calling it can succeed for this wallet, and never ships a
+ * placeholder (a zero balance, a receipt that stays pending).
+ */
+type WalletBase<Tx> = {
+  getBalance?: (options?: BalanceOptions) => Promise<Balance>;
+  /** Narrow with `switch (signer.kind)`; see `WalletSignerRegistry`. */
   getSigner: () => Promise<WalletSigner>;
-  /** Look up the status of a previously-submitted transaction. */
-  getTransactionReceipt: (tx: string) => Promise<{
-    status: "Success" | "Error" | "Pending";
-  }>;
-  /** `account` routes through a specific exposed address (EVM via
-   *  `tx.from`, Wallet Standard via the feature's `account` input);
-   *  omitting it lets the wallet pick. */
-  sendTx: (tx: TransactionInput, account?: Account) => Promise<string>;
-  /** Submit a transaction targeting a specific chain. The optional
-   *  callback fires after the connector has switched chain (consumers
-   *  use this to re-enable UI). Pass an `account` to route through a
-   *  specific exposed address (see `sendTx`). */
-  sendTxToChain: (tx: TransactionInput, targetChainId: string, account?: Account, cb?: () => void) => Promise<string>;
+  getTransactionReceipt?: (hash: string) => Promise<TransactionReceipt>;
+  /** Signs and broadcasts; resolves the transaction hash or signature. */
+  sendTx?: (tx: Tx, options?: TransactionOptions) => Promise<string>;
   /**
-   * Verify against `signedMessage`, not the input: Solana Wallet
-   * Standard wallets may prefix or re-encode it. `account` signs with a
-   * specific address without changing the wallet's active one.
+   * Verify against `signedMessage`, not the input: Solana Wallet Standard
+   * wallets may prefix or re-encode it.
    */
-  signMessage: (msg: Uint8Array, account?: Account) => Promise<{
-    signature: Uint8Array;
-    signedMessage: Uint8Array;
-  }>;
-  /** Switch to a different account on the same wallet (some wallets
-   *  expose multiple accounts simultaneously). */
-  switchAccount?: (address: string) => Promise<void>;
-  /** Switch the wallet's active chain. */
-  switchChain: (chain: ChainBase) => Promise<void>;
-};
-/**
- * No `signIn` (SIWE is app-level here, not a protocol method) and no
- * `signTransaction`: EVM wallets sign and send in one step through
- * `eth_sendTransaction`.
- */
-type EvmWallet = WalletBase;
-/**
- * Both additions are optional at runtime; gate them on
- * `capabilities.signIn` / `capabilities.signTransaction`, which mirror
- * what the wallet actually advertises.
- */
-type SvmWallet = WalletBase & {
-  /** Sign In With Solana (SIWS, `solana:signIn`). Authenticates the user
-   *  and returns the connected account plus the signed statement so the
-   *  consumer can verify server-side. `input` is the SIWS message fields
-   *  (domain, statement, nonce, …); pass `{}` or omit for wallet
-   *  defaults. */
-  signIn?: (input?: SignInInput) => Promise<{
-    account: Account;
-    signature: Uint8Array;
-    signedMessage: Uint8Array;
-  }>;
-  /** Sign a Solana transaction WITHOUT broadcasting it. butr ships no
-   *  RPC, so the consumer broadcasts the returned bytes via
-   *  `@solana/kit` / `@solana/web3.js` / etc. */
-  signTransaction?: (tx: TransactionInput, account?: Account) => Promise<Uint8Array>;
-};
-/**
- * Sui wallet surface. Adds optional `signTransaction` for the
- * `sui:signTransaction` (sign-only) feature; broadcast is on the
- * consumer via `@mysten/sui`'s SuiClient.
- */
-type SuiWallet = WalletBase & {
-  /** Sign a Sui transaction WITHOUT executing it. Returns BOTH halves the
-   *  chain requires: `SuiClient.executeTransactionBlock` needs
-   *  `{ transactionBlock, signature }`, so a bare `Uint8Array` cannot express
-   *  the result and a consumer holding one cannot tell which half they have. */
-  signTransaction?: (tx: TransactionInput, account?: Account) => Promise<{
+  signMessage?: (message: Uint8Array, options?: AccountOptions) => Promise<SignedMessage>;
+  /** Moves the wallet (or butr's view of it) to `chain`. Rejects for a
+   *  chain outside this adapter's namespace or not advertised by the wallet. */
+  switchChain?: (chain: ChainBase) => Promise<void>;
+};
+type EvmTransactionValue = bigint | boolean | number | string | null | ReadonlyArray<EvmTransactionValue> | {
+  readonly [key: string]: EvmTransactionValue | undefined;
+};
+/** An `eth_sendTransaction` request. `bigint` quantities are encoded as hex. */
+type EvmTransactionRequest = Readonly<Record<string, EvmTransactionValue | undefined>>;
+/** A `@mysten/sui` `Transaction` (anything with `toJSON()`), its JSON string,
+ *  or BCS bytes. */
+type SuiTransactionInput = string | Uint8Array | {
+  toJSON: () => Promise<string>;
+};
+/** `amount` in satoshis. */
+type BitcoinTransfer = {
+  amount: bigint;
+  recipient: string;
+};
+type SignInOutput = {
+  account: Account;
+  signature: Uint8Array;
+  signedMessage: Uint8Array;
+};
+/** No `signIn` (SIWE is app-level) and no `signTransaction`: EVM wallets sign
+ *  and send in one step through `eth_sendTransaction`. */
+type EvmWallet = WalletBase<EvmTransactionRequest>;
+type SvmWallet = WalletBase<Uint8Array> & {
+  /** Sign In With Solana (`solana:signIn`). `input` holds the SIWS message
+   *  fields (domain, statement, nonce, …). */
+  signIn?: (input?: SignInInput) => Promise<SignInOutput>;
+  /** Signs a serialized transaction without broadcasting it and resolves the
+   *  full signed transaction, ready for your own RPC client. */
+  signTransaction?: (tx: Uint8Array, options?: TransactionOptions) => Promise<Uint8Array>;
+};
+type SuiWallet = WalletBase<SuiTransactionInput> & {
+  /** Signs without executing. `SuiClient.executeTransactionBlock` needs both
+   *  halves, so the result carries the transaction bytes and the signature. */
+  signTransaction?: (tx: SuiTransactionInput, options?: TransactionOptions) => Promise<{
     bytes: Uint8Array;
     signature: Uint8Array;
   }>;
 };
-/**
- * `signTransaction` is `bitcoin:signPsbt`: pass `psbt.toBuffer()` bytes
- * and get signed PSBT bytes back, to finalise and broadcast through
- * your own Esplora or Electrum client.
- */
-type BitcoinWallet = WalletBase & {
-  signTransaction?: (tx: TransactionInput, account?: Account) => Promise<Uint8Array>;
+type BitcoinWallet = WalletBase<BitcoinTransfer> & {
+  /** `bitcoin:signPsbt`: PSBT bytes in (`psbt.toBuffer()`), signed PSBT bytes
+   *  out, to finalise and broadcast through your own Esplora or Electrum
+   *  client. */
+  signTransaction?: (psbt: Uint8Array, options?: TransactionOptions) => Promise<Uint8Array>;
 };
-/**
- * No standalone `signTransaction`: building an extrinsic needs chain
- * metadata over RPC, which butr does not ship, so transaction signing
- * goes through the `getSigner()` handoff.
- */
-type PolkadotWallet = WalletBase;
-/** Per-platform full adapter shapes: `Connector` + the platform's
- *  `Wallet` surface. These are the discriminated-union variants of
- *  `WalletAdapter`. */
+/** Building an extrinsic needs chain metadata over RPC, which butr does not
+ *  ship, so transactions go through the `getSigner()` handoff. */
+type PolkadotWallet = Omit<WalletBase<never>, "sendTx">;
 type EvmAdapter = Connector<"evm"> & EvmWallet;
 type SvmAdapter = Connector<"svm"> & SvmWallet;
 type SuiAdapter = Connector<"sui"> & SuiWallet;
 type BitcoinAdapter = Connector<"bitcoin"> & BitcoinWallet;
 type PolkadotAdapter = Connector<"polkadot"> & PolkadotWallet;
-/**
- * The union narrows "this platform has the concept at all"; the
- * `capabilities` flags narrow "this wallet supports it right now".
- * Both gates are needed, and neither substitutes for the other.
- */
+/** Narrow on `chainPlatform` to reach a platform's own methods and
+ *  transaction type. */
 type WalletAdapter = EvmAdapter | SvmAdapter | SuiAdapter | BitcoinAdapter | PolkadotAdapter;
-type ConnectedWallet = {
-  /** Currently-active account on this wallet. */
+type AdapterByPlatform = {
+  bitcoin: BitcoinAdapter;
+  evm: EvmAdapter;
+  polkadot: PolkadotAdapter;
+  sui: SuiAdapter;
+  svm: SvmAdapter;
+};
+type WalletAdapterFor<P extends ChainPlatform> = Extract<WalletAdapter, {
+  chainPlatform: P;
+}>;
+type ConnectedWallet<P extends ChainPlatform = ChainPlatform> = {
+  /** The active account; always one of `accounts`. */
   account: Account;
-  /** All accounts known on this wallet at the time of connect/refresh.
-   *  Always contains at least `account`. Populated from `getAccounts()`
-   *  if the connector implements it; otherwise `[account]`. */
-  accounts: Array<Account>;
-  connector: WalletAdapter;
-};
+  /** Every account the wallet exposed at the last connect or refresh. */
+  accounts: ReadonlyArray<Account>;
+  /** An indexed access rather than `WalletAdapterFor`, so TypeScript measures
+   *  `P` covariant and `ConnectedWallet<"evm">` stays a `ConnectedWallet`. */
+  connector: AdapterByPlatform[P];
+};
+/** Narrows a pool entry to one platform, e.g. before calling its `sendTx`. */
+declare const isPlatformWallet: <P extends ChainPlatform>(wallet: ConnectedWallet, platform: P) => wallet is ConnectedWallet<P>;
+//#endregion
+//#region src/wallet-source.d.ts
+/**
+ * The discovery seam: a function that announces adapters and returns its
+ * unsubscribe. Every `discover*Adapters` export already has this shape, so
+ * it goes into `sources` as-is.
+ */
+type WalletSource = (onAdapter: (adapter: WalletAdapter) => void) => () => void;
+/**
+ * For adapters that are built rather than discovered: WalletConnect, Ledger,
+ * hand-rolled ones. Takes one adapter or several, or a promise of either; a
+ * rejected promise is logged and contributes nothing.
+ */
+declare const fromAdapters: (adapters: MaybePromise<WalletAdapter | Iterable<WalletAdapter>>) => WalletSource;
 //#endregion
 //#region src/types/discoverer.d.ts
 /**
@@ -340,256 +327,306 @@ type PlatformDiscoverer = {
    * discovery already announced the same wallet, or it double-lists.
    */
   fallback?: {
-    subscribe: (onAdapter: (adapter: WalletAdapter) => void, opts: {
+    subscribe: (onAdapter: (adapter: WalletAdapter) => void, options: {
       hasAnyPrimaryAdapter: () => boolean;
     }) => () => void;
   };
   /** Primary discovery subscription. */
-  subscribe: (onAdapter: (adapter: WalletAdapter) => void) => () => void;
+  subscribe: WalletSource;
 };
 //#endregion
 //#region src/types/errors.d.ts
 /**
  * Wallet SDKs disagree on error shape (EIP-1193 codes, bare strings,
  * bespoke classes), so consumers branch on `kind` rather than regexing
- * messages. `cause` keeps the original value for the `Unknown` case.
- */
-type ConnectionError = {
-  kind: "UserRejected";
-  message: string;
-} | {
-  kind: "RequestPending";
-  message: string;
-} | {
-  kind: "WalletLocked";
-  message: string;
-} | {
-  actualChain?: string;
-  expectedChain?: string;
-  kind: "ChainMismatch";
-  message: string;
-} | {
-  kind: "NotConnected";
-  message: string;
-} | {
-  kind: "Timeout";
-  message: string;
-} | {
-  cause?: ErrorCause;
-  kind: "Unknown";
-  message: string;
-};
-type ConnectionErrorKind = ConnectionError["kind"];
-type ErrorCause = Error | string;
-type CodedError = Error & {
-  code: number | string;
-};
-/**
- * EIP-1193 codes: `4001` rejected, `-32002` pending, `4100`/`4900`/`4901`
- * unauthorized or disconnected. Message-substring matching is the last
- * resort for SDKs that ship no codes at all.
+ * messages. `cause` keeps the original value.
  */
-declare const mapConnectionError: (raw: ErrorCause) => ConnectionError;
-//#endregion
-//#region src/storage/persistence.d.ts
-type MaybePromise<T> = T | Promise<T>;
-/** Low-level key/value driver. Sync on web (localStorage, MMKV),
- *  async on React Native (AsyncStorage). */
-type StorageDriver = {
-  getItem: (key: string) => MaybePromise<string | null>;
-  removeItem: (key: string) => MaybePromise<void>;
-  setItem: (key: string, value: string) => MaybePromise<void>;
-};
-type StoredPoolEntry = {
-  account: Account;
-  /** All known accounts on the wallet at last persist. Always contains
-   *  `account`. */
-  accounts: Array<Account>;
-  chainPlatform: ChainPlatform;
-  connectorId: string;
-  /** Wallet icon URL or data-URI captured at persist time. Lets the
-   *  shadow adapter render the same icon the live adapter will when
-   *  the store is seeded from a snapshot. Omitted when the adapter
-   *  itself has no icon. */
-  icon?: string;
-  /** Human-facing wallet name (e.g. "MetaMask") captured at persist
-   *  time. Required so the shadow adapter renders the same identity
-   *  the live adapter will; no "metamask" → "MetaMask" swap at the
-   *  hydration boundary. */
-  name: string;
-};
-type StoredPoolRecord = Partial<Record<string, StoredPoolEntry>>;
-type StoredSelectionRecord = Partial<Record<ChainPlatform, string>>;
-type WalletPersistence = {
-  clearAll: () => Promise<void>;
-  clearPool: () => Promise<void>;
-  getActiveConnectorId: () => Promise<string | null>;
-  getPool: () => Promise<StoredPoolRecord>;
-  getSelection: () => Promise<StoredSelectionRecord>;
-  isUserDisconnected: () => Promise<boolean>;
-  markUserDisconnected: (value: boolean) => Promise<void>;
-  removePoolEntry: (connectorId: string) => Promise<void>;
-  setActiveConnectorId: (connectorId: string | null) => Promise<void>;
-  setPool: (pool: Map<string, ConnectedWallet>) => Promise<void>;
-  setSelection: (selection: Map<ChainPlatform, string>) => Promise<void>;
-};
-//#endregion
-//#region src/storage/snapshot.d.ts
-/**
- * Carries no `Connector` by design: a wallet extension exists only in
- * the browser, so a server render can name the wallet and its address
- * but can never dispatch on it.
- */
-type WalletSnapshot = {
-  activeConnectorId: string | null;
-  pool: StoredPoolRecord;
-  selection: StoredSelectionRecord;
-};
-type CookieSource = Iterable<{
-  name: string;
-  value: string;
-}> | Iterable<[string, string]> | Readonly<Record<string, string>>;
-type SnapshotOptions = {
-  /**
-   * Same prefix passed to `WalletManagerProvider` / `WalletStorage`.
-   * Defaults to `"butr"` to match the library default.
-   */
-  keyPrefix?: string;
-};
-declare const EMPTY_SNAPSHOT: WalletSnapshot;
-/**
- * Optimistic: only what the browser last persisted, so an uninstall or
- * other-tab disconnect makes it stale. Authoritative once the entry
- * leaves `reconnectingIds`; `isHydrated` is true from render one.
- */
-declare const readWalletSnapshot: (source: CookieSource, options?: SnapshotOptions) => WalletSnapshot;
+type ConnectionErrorKind = "ChainMismatch" | "NotConnected" | "RequestPending" | "Timeout" | "Unknown" | "UserRejected" | "WalletLocked" | "WalletNotFound";
+declare class ConnectionError extends Error {
+  readonly kind: ConnectionErrorKind;
+  constructor(kind: ConnectionErrorKind, message: string, options?: ErrorOptions);
+}
+/** The one boundary where a thrown value of unknown shape becomes typed. */
+declare const toConnectionError: (cause: unknown) => ConnectionError;
 //#endregion
 //#region src/types/manager.d.ts
 /**
- * `pendingIds` are not failures: discovery announces those adapters
- * asynchronously and the runtime retries them, usually within a few
- * hundred ms. Only `dropped` entries have been removed from storage.
+ * `pendingIds` are not failures: their adapters have not been announced yet,
+ * and the manager restores them the moment they are. Only `dropped` entries
+ * failed their silent reconnect; they stay persisted for the next load.
  */
 type HydrationOutcome = {
-  dropped: Array<{
+  dropped: ReadonlyArray<{
     connectorId: string;
-    reason: ErrorCause;
+    reason: ConnectionError;
   }>;
-  pendingIds: Array<string>;
-  restoredIds: Array<string>;
+  pendingIds: ReadonlyArray<string>;
+  restoredIds: ReadonlyArray<string>;
 };
+/**
+ * Read once, when the manager is created. Define it at module scope; the
+ * callbacks never see later values.
+ */
 type WalletManagerConfig = {
-  /** Available connector metadata */
-  connectors: Array<ConnectorMeta>;
-  /** Function to instantiate a connector by ID */
-  createConnector: (id: string) => WalletAdapter | null;
-  /**
-   * Seeds the pool with shadow adapters and flips `isHydrated` true on
-   * construction, so identity renders without a flash but every seeded
-   * id sits in `reconnectingIds` until silent reconnect verifies it.
-   */
-  initialState?: WalletSnapshot;
-  /** Called after a wallet is successfully connected */
-  onConnect?: (wallet: ConnectedWallet) => void;
-  /**
-   * Fires for every failed attempt (rejection, locked wallet, timeout,
-   * …), so observability can hook here instead of wrapping every
-   * `connectWallet` call.
-   */
+  /** Fires whenever a wallet goes live: a user `connect` (`reconnected:
+   *  false`) or a silent restore of a persisted connection (`true`). */
+  onConnect?: (wallet: ConnectedWallet, context: {
+    reconnected: boolean;
+  }) => void;
+  /** Fires for every failed attempt, so observability hooks here instead of
+   *  wrapping every `connect` call. */
   onConnectError?: (error: ConnectionError, connectorId: string) => void;
-  /** Called after a wallet is disconnected */
-  onDisconnect?: (chainPlatform: ChainPlatform) => void;
-  /** Fires once, after the mount-time hydration pass. */
+  /** `byUser` is false when the wallet itself ended the session (locked,
+   *  extension removed, relay session expired). */
+  onDisconnect?: (wallet: ConnectedWallet, context: {
+    byUser: boolean;
+  }) => void;
+  /** Fires once, after the start-up hydration pass. */
   onHydrated?: (outcome: HydrationOutcome) => void;
-  /** Called after all wallets are reset (e.g., to clear auth tokens) */
-  onReset?: () => void | Promise<void>;
-  /**
-   * Fires at most once per attempt, once it passes
-   * `slowConnectThresholdMs` without settling. The attempt keeps
-   * running; this is a hint, not a timeout.
-   */
+  /** Fires at most once per attempt, once it passes `slowConnectThresholdMs`
+   *  without settling. A hint, not a timeout. */
   onSlowConnect?: (connectorId: string) => void;
-  /**
-   * Persistence is fire-and-forget: a failed write (quota, cookie size,
-   * cross-tab conflict) never breaks reducer state, it only surfaces
-   * here. Defaults to `console.warn`.
-   */
-  onStorageError?: (error: ErrorCause, context: string) => void;
+  /** Persistence is fire-and-forget: a failed write never breaks state, it
+   *  only surfaces here. Defaults to `console.warn`. */
+  onStorageError?: (error: Error) => void;
   /** Threshold for `onSlowConnect`, in milliseconds. Defaults to 5_000. */
   slowConnectThresholdMs?: number;
-  /** Optional custom persistence implementation (e.g., cookie-backed) */
+  /** Where adapters come from: `autoDiscovery()`, any `discover*Adapters`
+   *  export, or `fromAdapters(…)` for WalletConnect, Ledger and hand-rolled
+   *  adapters. The first adapter announced for an id wins. */
+  sources?: ReadonlyArray<WalletSource>;
+  /** Replaces the default localStorage + sessionStorage persistence. */
   storage?: WalletPersistence;
-  /** Storage key prefix for localStorage */
+  /** Key prefix for the default persistence. Ignored when `storage` is set;
+   *  pass the same value to `readWalletSnapshot`. */
   storageKeyPrefix?: string;
 };
 //#endregion
-//#region src/types/signer.d.ts
-/**
- * Canonical cast target for `getSigner()`'s `unknown`, which stays
- * type-erased to keep the cross-package boundary loose. Platform
- * packages add their key by augmenting this interface.
- */
-interface SignerForPlatform {}
-/** Convenience alias for narrowing a single platform's signer type. */
-type SignerOf<P extends keyof SignerForPlatform> = SignerForPlatform[P];
-//#endregion
-//#region src/wallet-source.d.ts
-/**
- * The discovery seam: implementable by third parties without depending
- * on `@usebutr/wallets`, which itself just composes the per-platform
- * sources into one.
- */
-type WalletSource = {
-  subscribe: (onAdapter: (adapter: WalletAdapter) => void) => () => void;
+//#region src/chains.d.ts
+/** Common EVM chains. `switchChain` accepts any `ChainBase`, so a chain
+ *  missing here still works; it is just named by its CAIP-2 id. */
+declare const EVM_CHAINS: {
+  readonly arbitrum: {
+    readonly id: "eip155:42161";
+    readonly name: "Arbitrum One";
+    readonly namespace: "eip155";
+    readonly reference: "42161";
+  };
+  readonly base: {
+    readonly id: "eip155:8453";
+    readonly name: "Base";
+    readonly namespace: "eip155";
+    readonly reference: "8453";
+  };
+  readonly bsc: {
+    readonly id: "eip155:56";
+    readonly name: "BNB Smart Chain";
+    readonly namespace: "eip155";
+    readonly reference: "56";
+  };
+  readonly ethereum: {
+    readonly id: "eip155:1";
+    readonly name: "Ethereum";
+    readonly namespace: "eip155";
+    readonly reference: "1";
+  };
+  readonly optimism: {
+    readonly id: "eip155:10";
+    readonly name: "Optimism";
+    readonly namespace: "eip155";
+    readonly reference: "10";
+  };
+  readonly polygon: {
+    readonly id: "eip155:137";
+    readonly name: "Polygon";
+    readonly namespace: "eip155";
+    readonly reference: "137";
+  };
+  readonly sepolia: {
+    readonly id: "eip155:11155111";
+    readonly name: "Sepolia";
+    readonly namespace: "eip155";
+    readonly reference: "11155111";
+  };
 };
-/**
- * Takes the exact shape of `discoverEvmAdapters` and friends, so a
- * single-platform app keeps `@usebutr/wallets` out of its bundle.
- */
-declare const createWalletSource: (subscribe: (onAdapter: (adapter: WalletAdapter) => void) => () => void) => WalletSource;
+declare const SVM_CHAINS: {
+  readonly devnet: {
+    readonly id: "solana:devnet";
+    readonly name: "Solana Devnet";
+    readonly namespace: "solana";
+    readonly reference: "devnet";
+  };
+  readonly mainnet: {
+    readonly id: "solana:mainnet";
+    readonly name: "Solana Mainnet";
+    readonly namespace: "solana";
+    readonly reference: "mainnet";
+  };
+  readonly testnet: {
+    readonly id: "solana:testnet";
+    readonly name: "Solana Testnet";
+    readonly namespace: "solana";
+    readonly reference: "testnet";
+  };
+};
+declare const SUI_CHAINS: {
+  readonly devnet: {
+    readonly id: "sui:devnet";
+    readonly name: "Sui Devnet";
+    readonly namespace: "sui";
+    readonly reference: "devnet";
+  };
+  readonly localnet: {
+    readonly id: "sui:localnet";
+    readonly name: "Sui Localnet";
+    readonly namespace: "sui";
+    readonly reference: "localnet";
+  };
+  readonly mainnet: {
+    readonly id: "sui:mainnet";
+    readonly name: "Sui Mainnet";
+    readonly namespace: "sui";
+    readonly reference: "mainnet";
+  };
+  readonly testnet: {
+    readonly id: "sui:testnet";
+    readonly name: "Sui Testnet";
+    readonly namespace: "sui";
+    readonly reference: "testnet";
+  };
+};
+/** CAIP-2 Bitcoin references are the first 16 bytes of each network's
+ *  genesis block hash, which is what wallets advertise in `wallet.chains`. */
+declare const BITCOIN_CHAINS: {
+  readonly mainnet: {
+    readonly id: "bip122:000000000019d6689c085ae165831e93";
+    readonly name: "Bitcoin";
+    readonly namespace: "bip122";
+    readonly reference: "000000000019d6689c085ae165831e93";
+  };
+  readonly signet: {
+    readonly id: "bip122:00000008819873e925422c1ff0f99f7c";
+    readonly name: "Bitcoin Signet";
+    readonly namespace: "bip122";
+    readonly reference: "00000008819873e925422c1ff0f99f7c";
+  };
+  readonly testnet: {
+    readonly id: "bip122:000000000933ea01ad0ee984209779ba";
+    readonly name: "Bitcoin Testnet";
+    readonly namespace: "bip122";
+    readonly reference: "000000000933ea01ad0ee984209779ba";
+  };
+  readonly testnet4: {
+    readonly id: "bip122:00000000da84f2bafbbc53dee25a72ae";
+    readonly name: "Bitcoin Testnet4";
+    readonly namespace: "bip122";
+    readonly reference: "00000000da84f2bafbbc53dee25a72ae";
+  };
+};
+declare const POLKADOT_CHAINS: {
+  readonly kusama: {
+    readonly id: "polkadot:b0a8d493285c2df73290dfb7e61f870f";
+    readonly name: "Kusama";
+    readonly namespace: "polkadot";
+    readonly reference: "b0a8d493285c2df73290dfb7e61f870f";
+  };
+  readonly paseo: {
+    readonly id: "polkadot:77afd6190f1554ad45fd0d31aee62aac";
+    readonly name: "Paseo";
+    readonly namespace: "polkadot";
+    readonly reference: "77afd6190f1554ad45fd0d31aee62aac";
+  };
+  readonly polkadot: {
+    readonly id: "polkadot:91b171bb158e2d3848fa23a9f1c25182";
+    readonly name: "Polkadot";
+    readonly namespace: "polkadot";
+    readonly reference: "91b171bb158e2d3848fa23a9f1c25182";
+  };
+  readonly westend: {
+    readonly id: "polkadot:e143f23803ac50e8f6f8e62695d1ce9e";
+    readonly name: "Westend";
+    readonly namespace: "polkadot";
+    readonly reference: "e143f23803ac50e8f6f8e62695d1ce9e";
+  };
+};
+declare const EVM_CHAINS_LIST: ReadonlyArray<ChainBase>;
+declare const SVM_CHAINS_LIST: ReadonlyArray<ChainBase>;
+declare const SUI_CHAINS_LIST: ReadonlyArray<ChainBase>;
+declare const BITCOIN_CHAINS_LIST: ReadonlyArray<ChainBase>;
+declare const POLKADOT_CHAINS_LIST: ReadonlyArray<ChainBase>;
+/** Every registry as a list, keyed by platform: the shape chain pickers want. */
+declare const CHAINS_BY_PLATFORM: ChainsByPlatform;
 //#endregion
 //#region src/store/reducer.d.ts
-/**
- * The reducer never writes `"reconnecting"`; `useConnectionStatus`
- * derives it from `reconnectingIds` so the state machine stays narrow
- * while the public vocabulary matches wagmi's.
- */
-type ConnectionStatus = "idle" | "connecting" | "success" | "error" | "reconnecting";
-type State = {
+/** Status of the latest `connect` attempt, not of the connection itself;
+ *  `useConnectionStatus` derives the latter. */
+type ConnectStatus = "idle" | "connecting" | "success" | "error";
+type WalletState = {
   activeConnectorId: string | null;
+  /** Every adapter the sources announced, in announcement order. */
+  adapters: ReadonlyArray<WalletAdapter>;
   connectingConnectorId: string | null;
   connectionError: ConnectionError | null;
-  connectionStatus: ConnectionStatus;
-  isHydrated: boolean;
-  isUserDisconnected: boolean;
-  pool: Map<string, ConnectedWallet>;
+  connectionStatus: ConnectStatus;
   /**
-   * Ids still backed by a shadow adapter from `initialState`. Empty
-   * without `initialState`; shrinks on `HYDRATED` / `CONNECT_SUCCEEDED`
-   * and on `DISCONNECTED` / `RESET`.
+   * Persisted connections that are not live: awaiting their adapter, failed
+   * their silent reconnect, or ended by the wallet rather than the user.
+   * They stay persisted so the next load retries them.
    */
+  dormant: ReadonlyMap<string, StoredPoolEntry>;
+  isHydrated: boolean;
+  isUserDisconnected: boolean;
+  pool: ReadonlyMap<string, ConnectedWallet>;
+  /** Pool ids still backed by a shadow adapter seeded from `initialState`. */
   reconnectingIds: ReadonlySet<string>;
-  selection: Map<ChainPlatform, string>;
+  /** Which pool entry serves each platform present in the pool. */
+  selection: ReadonlyMap<ChainPlatform, string>;
 };
 //#endregion
 //#region src/store/shadow-adapter.d.ts
 /**
- * Loud failure for consumers that called a wallet method without gating
- * on `capabilities.*` (all `false` here) or `reconnectingIds`, before
- * silent reconnect swapped in the live adapter.
+ * Thrown by the three required methods of a shadow adapter. Every optional
+ * method is simply absent, so only code that skipped the `reconnectingIds`
+ * check and called `connect`, `getAccounts` or `getSigner` sees this.
  */
-declare class ShadowConnectorError extends Error implements CodedError {
-  readonly code = "BUTR_RECONNECTING";
+declare class ShadowConnectorError extends Error {
   readonly connectorId: string;
   readonly method: string;
   constructor(method: string, connectorId: string);
 }
+//#endregion
+//#region src/store/wallet-manager.d.ts
+type WalletManager = Pick<StoreApi<WalletState>, "getInitialState" | "getState" | "subscribe"> & {
+  /** Clears `connectionError` and returns `connectionStatus` to idle. */
+  clearConnectionError: () => void;
+  /** Resolves the connected wallet; rejects with a `ConnectionError`. */
+  connect: (connectorId: string) => Promise<ConnectedWallet>;
+  disconnect: (connectorId: string) => void;
+  /** Disconnects every wallet and forgets every persisted connection. */
+  disconnectAll: () => void;
+  /** Opens the wallet's account picker, then refreshes the pool entry. A no-op
+   *  for wallets without `requestAccounts`. */
+  requestAccounts: (connectorId: string) => Promise<void>;
+  /** Selects an exposed account without changing its chain or the account
+   *  list. Unknown wallets and accounts are ignored. */
+  setAccount: (connectorId: string, account: Account) => void;
+  setActive: (connectorId: string) => void;
+  setSelection: (chainPlatform: ChainPlatform, connectorId: string) => void;
+  /**
+   * Subscribes the sources, hydrates persisted connections (once per
+   * manager) and bridges wallet events. The returned function undoes all of
+   * it except hydration, so a StrictMode remount is safe.
+   */
+  start: () => () => void;
+};
 /**
- * Structural detection: relies on every live adapter advertising at
- * least one capability, since `getBalance`, `signMessage` and
- * `switchChain` are required on all wallet surfaces.
+ * Framework-free: React binds it through `WalletManagerProvider`, anything
+ * else calls `start()` itself. Creating one has no side effects, so it is
+ * safe during a server render.
  */
-declare const isShadowAdapter: (adapter: WalletAdapter) => boolean;
+declare const createWalletManager: (config?: WalletManagerConfig, options?: {
+  initialState?: WalletSnapshot;
+}) => WalletManager;
 //#endregion
 //#region src/storage/browser-storage-driver.d.ts
 type BrowserStorageDrivers = {
@@ -648,8 +685,28 @@ type CookieDriverOptions = {
  */
 declare const createCookieStorageDriver: (options?: CookieDriverOptions) => StorageDriver;
 //#endregion
+//#region src/storage/snapshot.d.ts
+type CookieSource = Iterable<{
+  name: string;
+  value: string;
+}> | Iterable<[string, string]> | Readonly<Record<string, string>>;
+type SnapshotOptions = {
+  /**
+   * Same prefix passed as `storageKeyPrefix` / to `createWalletStorage`.
+   * Defaults to `"butr"` to match the library default.
+   */
+  keyPrefix?: string;
+};
+declare const EMPTY_SNAPSHOT: WalletSnapshot;
+/**
+ * Optimistic: only what the browser last persisted, so an uninstall or
+ * other-tab disconnect makes it stale. Authoritative once the entry
+ * leaves `reconnectingIds`; `isHydrated` is true from render one.
+ */
+declare const readWalletSnapshot: (source: CookieSource, options?: SnapshotOptions) => WalletSnapshot;
+//#endregion
 //#region src/storage/wallet-storage.d.ts
-type StorageConfig = {
+type WalletStorageOptions = {
   /** Defaults to `"butr"`, matching `readWalletSnapshot`. */
   keyPrefix?: string;
   /** Survives app restart. Defaults to localStorage on web. */
@@ -657,73 +714,12 @@ type StorageConfig = {
   /** Cleared on session end. Defaults to sessionStorage on web. */
   session?: StorageDriver;
 };
-declare class WalletStorage implements WalletPersistence {
-  private readonly poolKey;
-  private readonly selectionKey;
-  private readonly activeKey;
-  private readonly userDisconnectedKey;
-  private readonly persistent;
-  private readonly session;
-  /**
-   * Serializes pool read-modify-writes; without it concurrent `setPool`
-   * calls drop each other's entries. Not reentrant, so a queued mutation
-   * must read via `readPool`: `getPool` re-enters and deadlocks it.
-   */
-  private poolMutationQueue;
-  constructor(config: StorageConfig);
-  /** Chain `fn` after the in-flight pool mutation. */
-  private serializePoolMutation;
-  /** Read and decode the pool without touching the mutation queue. Safe to
-   *  call from inside a queued mutation, unlike `getPool`. */
-  private readPool;
-  getPool(): Promise<StoredPoolRecord>;
-  /**
-   * Additive on purpose: a failed silent reconnect drops the entry from
-   * the live pool, and it must survive to be retried next load.
-   * Eviction goes through `removePoolEntry` or `clearAll`.
-   */
-  setPool(pool: Map<string, ConnectedWallet>): Promise<void>;
-  removePoolEntry(connectorId: string): Promise<void>;
-  clearPool(): Promise<void>;
-  getSelection(): Promise<StoredSelectionRecord>;
-  setSelection(selection: Map<ChainPlatform, string>): Promise<void>;
-  getActiveConnectorId(): Promise<string | null>;
-  setActiveConnectorId(connectorId: string | null): Promise<void>;
-  clearAll(): Promise<void>;
-  /**
-   * Kept in the session driver so it survives remounts (unlike a ref)
-   * yet clears at session end (unlike the persistent driver): a manual
-   * disconnect must suppress auto-connect now, not forever.
-   */
-  isUserDisconnected(): Promise<boolean>;
-  markUserDisconnected(value: boolean): Promise<void>;
-}
-//#endregion
-//#region src/store/wallet-store.d.ts
-type ExtractState<S> = S extends {
-  getState: () => infer T;
-} ? T : never;
-type RuntimeMembers = {
-  _config: WalletManagerConfig;
-  _storage: WalletPersistence;
-  connectWallet: (connectorId: string, onSuccess?: (wallet: ConnectedWallet) => void, onError?: (error: Error) => void) => Promise<void>;
-  disconnectWallet: (connectorId: string) => void;
-  getConnectorInstance: (id: string) => ReturnType<WalletManagerConfig["createConnector"]>;
-  hydrateWallets: () => Promise<void>;
-  refreshWallet: (connectorId: string) => void;
-  requestAccounts: (connectorId: string) => Promise<void>;
-  reset: () => void;
-  resetConnectionStatus: () => void;
-  setActiveConnector: (connectorId: string | null) => void;
-  setConnectionError: (error: ConnectionError | null) => void;
-  setSelection: (chainPlatform: ChainPlatform, connectorId: string | null) => void;
-  setUserDisconnected: (value: boolean) => void;
-  tryRestoreFromPending: (connectorId: string) => Promise<void>;
-  updateWalletAccount: (connectorId: string, account: Account) => void;
-};
-type WalletStore = ReturnType<typeof createWalletStore>;
-type WalletStoreState = ExtractState<WalletStore>;
-declare const createWalletStore: (config: WalletManagerConfig) => import("zustand/vanilla").StoreApi<State & RuntimeMembers>;
+/**
+ * Pool, selection and active id go to the persistent driver, the disconnect
+ * intent to the session driver. Unchanged keys are not rewritten, so a
+ * cookie-backed driver does not re-send every cookie on each save.
+ */
+declare const createWalletStorage: (options?: WalletStorageOptions) => WalletPersistence;
 //#endregion
 //#region src/group-by-platform.d.ts
 /**
@@ -797,10 +793,12 @@ declare class SignInUnsupportedError extends Error {
 declare const createSignInFlow: (options: SignInFlowOptions) => SignInFlow;
 //#endregion
 //#region src/wallet-equal.d.ts
+/** Account ids are canonical (`buildAccount`), so identity is the id. */
+declare const accountsEqual: (a: ReadonlyArray<Account>, b: ReadonlyArray<Account>) => boolean;
 /**
  * The adapter is compared by reference, not `connector.id`: hydration
  * swaps a shadow adapter for the live one under an unchanged id, and an
- * id check would strand consumers on the throwing placeholder.
+ * id check would strand consumers on the placeholder.
  */
 declare const walletEqual: (a: ConnectedWallet | undefined, b: ConnectedWallet | undefined) => boolean;
 //#endregion
@@ -849,5 +847,5 @@ declare const bytesToBase58: (bytes: Uint8Array) => string;
  *  rather than silently dropping them. */
 declare const base58ToBytes: (input: string) => Uint8Array;
 //#endregion
-export { type Account, type Balance, type BitcoinAdapter, type BitcoinWallet, type BrowserStorageDrivers, CHAIN_PLATFORMS, type ChainBase, type ChainPlatform, type ChainsByPlatform, type ConnectedWallet, type ConnectionError, type ConnectionErrorKind, type ConnectionStatus, type Connector, type ConnectorEvent, type ConnectorMeta, type CookieDriverOptions, type CookieSource, EMPTY_SNAPSHOT, type EvmAdapter, type EvmWallet, type HydrationOutcome, type InitialCookies, type MaybePromise, type PlatformDiscoverer, type PolkadotAdapter, type PolkadotWallet, ShadowConnectorError, type SignInFlowOptions, type SignInInput, type SignInMessageContext, type SignInResult, SignInUnsupportedError, type SignInValue, type SignerForPlatform, type SignerOf, type SnapshotOptions, type StorageDriver, type StoredPoolEntry, type StoredPoolRecord, type StoredSelectionRecord, type SuiAdapter, type SuiWallet, type SvmAdapter, type SvmWallet, type TransactionInput, type TransactionMethod, type TransactionObject, type TransactionValue, type WalletAdapter, type WalletAvailability, type WalletBase, type WalletCapabilities, type WalletManagerConfig, type WalletPersistence, type WalletSigner, type WalletSnapshot, type WalletSource, WalletStorage, type WalletStore, type WalletStoreState, base58ToBytes, base64ToBytes, buildAccount, buildChainsByPlatform, bytesToBase58, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createSignInFlow, createWalletSource, createWalletStore, groupByPlatform, hexToBytes, isShadowAdapter, logError, logWarn, mapConnectionError, readWalletSnapshot, sanitizeIcon, walletEqual };
+export { type Account, type AccountOptions, BITCOIN_CHAINS, BITCOIN_CHAINS_LIST, type Balance, type BalanceOptions, type BitcoinAdapter, type BitcoinTransfer, type BitcoinWallet, type BrowserStorageDrivers, CHAINS_BY_PLATFORM, CHAIN_PLATFORMS, type ChainBase, type ChainPlatform, type ChainsByPlatform, type ConnectStatus, type ConnectedWallet, ConnectionError, type ConnectionErrorKind, type Connector, type ConnectorEvent, type CookieDriverOptions, type CookieSource, EMPTY_SNAPSHOT, EVM_CHAINS, EVM_CHAINS_LIST, type EvmAdapter, type EvmTransactionRequest, type EvmTransactionValue, type EvmWallet, type HydrationOutcome, type InitialCookies, type MaybePromise, POLKADOT_CHAINS, POLKADOT_CHAINS_LIST, type PersistedWalletState, type PlatformDiscoverer, type PolkadotAdapter, type PolkadotWallet, SUI_CHAINS, SUI_CHAINS_LIST, SVM_CHAINS, SVM_CHAINS_LIST, ShadowConnectorError, type SignInFlowOptions, type SignInInput, type SignInMessageContext, type SignInOutput, type SignInResult, SignInUnsupportedError, type SignInValue, type SignedMessage, type SnapshotOptions, type StorageDriver, type StoredPoolEntry, type StoredPoolRecord, type StoredSelectionRecord, type SuiAdapter, type SuiTransactionInput, type SuiWallet, type SvmAdapter, type SvmWallet, type TransactionOptions, type TransactionReceipt, type WalletAdapter, type WalletAdapterFor, type WalletBase, type WalletManager, type WalletManagerConfig, type WalletPersistence, type WalletSigner, type WalletSignerKind, type WalletSignerOf, type WalletSignerRegistry, type WalletSnapshot, type WalletSource, type WalletState, type WalletStorageOptions, accountsEqual, base58ToBytes, base64ToBytes, buildAccount, bytesToBase58, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createSignInFlow, createWalletManager, createWalletStorage, fromAdapters, groupByPlatform, hexToBytes, isChainPlatform, isPlatformWallet, logError, logWarn, readWalletSnapshot, resolveChain, sanitizeIcon, toConnectionError, walletEqual };
 //# sourceMappingURL=index.d.ts.map