@usebutr/core 1.1.0 → 2.0.1

package/dist/index.d.ts

@@ -1,10 +1,7 @@
 //#region src/types/chain.d.ts
 /**
- * Minimal chain shape that butr needs to function.
- * Follows the CAIP-2 chain identifier standard.
- *
- * Consumers extend this with app-specific fields (logos, block explorers, etc.)
- * via structural typing; butr never inspects beyond these 4 fields.
+ * CAIP-2 shaped. butr never reads past these four fields, so consumers
+ * can extend the type structurally with logos, explorers and the like.
  */
 type ChainBase = {
   /** CAIP-2 identifier, e.g. "eip155:1", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" */
@@ -24,11 +21,9 @@ type Account = {
   walletAddress: string;
 };
 /**
- * Build butr's `Account` shape from a wallet address and a resolved
- * `ChainBase`. The composite id (`<chain>:<address>`) is what the
- * reducer uses to compare accounts across refreshes, so every adapter
- * must build accounts through this helper (or keep the format
- * byte-identical).
+ * The reducer compares accounts by the composite `<chain>:<address>`
+ * id, so every adapter must build accounts here or reproduce that
+ * format byte for byte.
  */
 declare const buildAccount: (address: string, chain: ChainBase) => Account;
 type Balance = {
@@ -44,24 +39,9 @@ type Balance = {
 //#endregion
 //#region src/types/capabilities.d.ts
 /**
- * Capability flags describing what an adapter can actually do at
- * runtime. Populated by each adapter (the auto-built ones derive
- * these from the underlying protocol's feature advertisements;
- * hand-rolled adapters declare them explicitly). Consumers branch on
- * these to gate UI affordances:
- *
- * ```tsx
- * {wallet.connector.capabilities.requestAccounts ? (
- *   <button onClick={() => requestAccounts(wallet.connector.id)}>
- *     Request more accounts
- *   </button>
- * ) : null}
- * ```
- *
- * Each flag means "can this work right now," not "is the method
- * defined": `signMessage: false` means calling `signMessage()` would
- * reject; `switchChain: false` means switching is a no-op regardless
- * of which chain is passed.
+ * 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). */
@@ -100,84 +80,44 @@ type WalletCapabilities = {
 //#endregion
 //#region src/types/platform.d.ts
 /**
- * Canonical list of supported chain platforms. The single runtime source
- * of truth: `ChainPlatform` is derived from it, and storage validators
- * build their allowlists from it, so the type and the runtime checks can
- * never drift (a missing platform here was why Polkadot connections failed
- * to persist).
+ * Single runtime source of truth: `ChainPlatform` and the storage
+ * validators' allowlists both derive from it. Omitting a platform here
+ * silently stops its connections from persisting.
  */
 declare const CHAIN_PLATFORMS: readonly ["evm", "svm", "sui", "bitcoin", "polkadot"];
 type ChainPlatform = (typeof CHAIN_PLATFORMS)[number];
 //#endregion
 //#region src/types/chains-by-platform.d.ts
 /**
- * Map of every chain platform to the list of chains the consumer wants
- * to expose to its UI (chain switcher, picker, etc).
- *
- * The platform key set is fixed by `ChainPlatform`. The value is the
- * chain list; empty when the consumer doesn't want to support that
- * platform's chains in this view. This is the only type that callers
- * write down; the values come from per-platform packages
- * (`EVM_CHAINS_LIST`, `SVM_CHAINS_LIST`, etc).
+ * 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.
  */
 type ChainsByPlatform = Readonly<Record<ChainPlatform, ReadonlyArray<ChainBase>>>;
 /**
- * Build a fully-populated `ChainsByPlatform` from a partial. Platforms
- * the consumer doesn't specify default to an empty list.
- *
- * Use this in apps that target one or two chain platforms; importing
- * only those packages keeps unused chain registries out of the bundle.
- * Apps that want every chain reach for `CHAINS_BY_PLATFORM` from
- * `@usebutr/wallets` instead.
- *
- * @example
- * // EVM-only app: Solana/Sui/Bitcoin tables never enter the bundle
- * import { EVM_CHAINS_LIST } from "@usebutr/evm";
- * import { buildChainsByPlatform } from "@usebutr/core";
- *
- * const chains = buildChainsByPlatform({ evm: EVM_CHAINS_LIST });
- *
- * @example
- * // Multi-chain app: pull from each package the app actually uses
- * import { EVM_CHAINS_LIST } from "@usebutr/evm";
- * import { SVM_CHAINS_LIST } from "@usebutr/svm";
- *
- * const chains = buildChainsByPlatform({
- *   evm: EVM_CHAINS_LIST,
- *   svm: SVM_CHAINS_LIST,
- * });
+ * 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>) => ChainsByPlatform;
+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
 /**
- * Whether a wallet is currently usable from the user's environment.
- *
- * - `installed`: the wallet is available and `connect()` can be called.
- * - `loadable`: the wallet's SDK can be loaded on demand (e.g. WalletConnect
- *   modal that pops a QR code without requiring a browser extension).
- * - `not-installed`: the wallet isn't reachable. Consumers typically render
- *   a "download" affordance pointing at `meta.url`.
+ * 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";
 /**
- * Events a connector can emit while connected. butr's runtime subscribes
- * via `Connector.subscribe?` after a successful `connect()` and dispatches
- * the equivalent reducer event:
- *
- * - `accountChanged` carries both the new active `account` AND the full
- *   `accounts` array the wallet currently exposes. The runtime mirrors
- *   that list verbatim into the pool entry. This handles two cases
- *   uniformly:
- *     - Multi-account wallets (MetaMask, Rabby, Brave): the user adds or
- *       removes accounts from the dapp's permission set; the array grows
- *       or shrinks to match.
- *     - Single-account-exposure wallets (Phantom EVM/SVM, MetaMask Snap):
- *       only the active account is ever in `accounts`; switching swaps it
- *       in place rather than appending.
- *   Also covers chain switches; the new chain lives inside `account.chain`.
- * - `disconnected` → `DISCONNECTED` (wallet has gone away externally:
- *   user locked it, removed the extension, etc.).
+ * `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`.
  */
 type ConnectorEvent = {
   account: Account;
@@ -200,16 +140,10 @@ type Connector<P extends ChainPlatform = ChainPlatform> = {
    *  use one of the per-platform adapter types (`EvmAdapter`,
    *  `SvmAdapter`, etc). */
   chainPlatform: P;
-  /** Begin a connection request. Resolves when the wallet is connected,
-   *  rejects on user cancellation or other error.
-   *
-   *  `opts.silent` requests a non-interactive reconnect to
-   *  already-authorized accounts; butr's mount-time hydration passes it
-   *  so a reload restores wallets without re-prompting (Wallet Standard
-   *  `standard:connect`'s `silent` input; the `eth_accounts` read on
-   *  EIP-1193). Adapters that can't reconnect without a prompt should
-   *  reject when `silent` is set rather than show UI; hydration treats
-   *  the rejection as a clean restore failure. */
+  /** `opts.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?: {
     silent?: boolean;
   }) => Promise<void>;
@@ -222,38 +156,23 @@ type Connector<P extends ChainPlatform = ChainPlatform> = {
    *  show many accounts at once (MetaMask with multiple imports). If
    *  omitted, butr defaults to `[await getAccount()]`. */
   getAccounts?: () => Promise<Array<Account>>;
-  /** Optional. Wallet logo as a URL or data URI. Adapters built via butr's
-   *  auto-discovery (EIP-6963, Wallet Standard) populate this from the
-   *  wallet's announced metadata; hand-rolled adapters can leave it
-   *  unset and supply icons separately via `ConnectorMeta`.
-   *
-   *  **Already sanitized on discovered adapters.** Discovery runs
-   *  `sanitizeIcon` at construction, so the value is either a trimmed,
-   *  non-empty string or `undefined`: never blank, never whitespace-led.
-   *  Render it directly, including into strict consumers like
-   *  `next/image`. No second `sanitizeIcon` call and no `icon !== ""`
-   *  guard is needed. Hand-rolled adapters set this field themselves and
-   *  own the guarantee. */
+  /** 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. */
   icon?: string;
   /** Stable key: "metamask", "phantom", etc. Pool entries are keyed by this. */
   id: string;
   /** Human name: "MetaMask", "Phantom", etc. UI-facing only. */
   name: string;
-  /** Optional. Ask the wallet to open its account-selection UI so the
-   *  user can expose additional accounts to this app. Implemented on
-   *  EIP-6963 wallets via `wallet_requestPermissions`; Wallet Standard
-   *  wallets generally leave this unset because the user enables more
-   *  accounts directly in the extension. Resolution doesn't include the
-   *  new accounts; call `getAccounts()` (or use butr's
-   *  `useRequestAccounts` hook, which refreshes the pool entry for
-   *  you). */
+  /** 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. */
   requestAccounts?: () => Promise<void>;
-  /** Optional. Subscribe to wallet-side events (account swap, network swap,
-   *  external disconnect). butr's runtime calls this after a successful
-   *  `connect()`, and uses the returned function to unsubscribe on
-   *  disconnect / reset. Bridges native wallet events into the reducer so
-   *  consumers don't have to wire `accountsChanged` / `chainChanged`
-   *  themselves. */
+  /** Bridges native wallet events (`accountsChanged`, `chainChanged`, …)
+   *  into the reducer. Only `ConnectorLifecycle` may call this, and it
+   *  guarantees at most one live subscription per connector. */
   subscribe?: (listener: (event: ConnectorEvent) => void) => () => void;
 };
 type ConnectorMeta = {
@@ -275,6 +194,17 @@ type ConnectorMeta = {
 };
 //#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
@@ -288,33 +218,24 @@ type WalletBase = {
   /** 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.). */
-  getSigner: () => Promise<unknown>;
+  getSigner: () => Promise<WalletSigner>;
   /** Look up the status of a previously-submitted transaction. */
   getTransactionReceipt: (tx: string) => Promise<{
     status: "Success" | "Error" | "Pending";
   }>;
-  /** Submit a transaction on the wallet's currently-active chain.
-   *  Pass an `account` from `ConnectedWallet.accounts` to route the
-   *  transaction through a specific exposed address instead of the
-   *  wallet's currently-active one. EVM wallets honour this via
-   *  `tx.from`; Wallet Standard wallets via the feature's `account`
-   *  input. Omit for "use whichever the wallet picks." */
-  sendTx: (tx: unknown, account?: Account) => Promise<string>;
+  /** `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: unknown, targetChainId: string, account?: Account, cb?: () => void) => Promise<string>;
+  sendTxToChain: (tx: TransactionInput, targetChainId: string, account?: Account, cb?: () => void) => Promise<string>;
   /**
-   * Sign a message and return both the signature and the bytes the wallet
-   * actually signed. Solana Wallet Standard wallets may prefix or re-encode
-   * the message internally; verifiers must check the signature against
-   * `signedMessage`, not the input bytes. EVM wallets echo the input.
-   *
-   * Pass an `account` to sign with a specific exposed address. EIP-1193
-   * routes it through `personal_sign`'s address param; Wallet Standard
-   * uses the feature's `account` input. Both support per-call signing
-   * without changing the wallet's active account.
+   * 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.
    */
   signMessage: (msg: Uint8Array, account?: Account) => Promise<{
     signature: Uint8Array;
@@ -327,19 +248,15 @@ type WalletBase = {
   switchChain: (chain: ChainBase) => Promise<void>;
 };
 /**
- * EVM wallet surface. No `signIn` (Sign-In-With-Ethereum is an app-level
- * concern in this library, not a protocol method). No `signTransaction`:
- * EVM wallets sign-and-send via `eth_sendTransaction`; sign-only EVM
- * flows aren't exposed through this surface.
+ * 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;
 /**
- * Solana wallet surface. Adds:
- *  - `signIn`: Sign-In-With-Solana (`solana:signIn`). Optional;
- *    `capabilities.signIn` gates availability at runtime.
- *  - `signTransaction`: sign-only path for wallets that advertise
- *    `solana:signTransaction` but not `solana:signAndSendTransaction`.
- *    Optional; `capabilities.signTransaction` gates availability.
+ * 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
@@ -347,7 +264,7 @@ type SvmWallet = WalletBase & {
    *  consumer can verify server-side. `input` is the SIWS message fields
    *  (domain, statement, nonce, …); pass `{}` or omit for wallet
    *  defaults. */
-  signIn?: (input?: Record<string, unknown>) => Promise<{
+  signIn?: (input?: SignInInput) => Promise<{
     account: Account;
     signature: Uint8Array;
     signedMessage: Uint8Array;
@@ -355,7 +272,7 @@ type SvmWallet = WalletBase & {
   /** 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: unknown, account?: Account) => Promise<Uint8Array>;
+  signTransaction?: (tx: TransactionInput, account?: Account) => Promise<Uint8Array>;
 };
 /**
  * Sui wallet surface. Adds optional `signTransaction` for the
@@ -363,24 +280,27 @@ type SvmWallet = WalletBase & {
  * consumer via `@mysten/sui`'s SuiClient.
  */
 type SuiWallet = WalletBase & {
-  signTransaction?: (tx: unknown, account?: Account) => Promise<Uint8Array>;
+  /** 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<{
+    bytes: Uint8Array;
+    signature: Uint8Array;
+  }>;
 };
 /**
- * Bitcoin wallet surface. `signTransaction` here is `bitcoin:signPsbt`
- * (sign-only PSBT path). Consumers pass `psbt.toBuffer()` bytes; the
- * wallet returns the signed PSBT bytes for the consumer to finalise /
- * broadcast through their own Esplora / Electrum client.
+ * `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: unknown, account?: Account) => Promise<Uint8Array>;
+  signTransaction?: (tx: TransactionInput, account?: Account) => Promise<Uint8Array>;
 };
 /**
- * Polkadot/Substrate wallet surface. No standalone `signTransaction`:
- * building an extrinsic needs chain metadata (an RPC round-trip butr
- * doesn't ship), so transaction signing happens through the
- * `getSigner()` handoff; the consumer builds and submits with the
- * wallet's signer (e.g. polkadot-api). Message signing works via the
- * injected `signer.signRaw`. Same shape as `EvmWallet`.
+ * 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
@@ -392,22 +312,9 @@ type SuiAdapter = Connector<"sui"> & SuiWallet;
 type BitcoinAdapter = Connector<"bitcoin"> & BitcoinWallet;
 type PolkadotAdapter = Connector<"polkadot"> & PolkadotWallet;
 /**
- * Full adapter interface; discriminated union by `chainPlatform`.
- *
- * Narrow on `wallet.connector.chainPlatform === "svm"` (etc.) to gain
- * access to platform-specific methods like `signIn` (SVM) or
- * `signTransaction` (SVM / Sui / Bitcoin). Calling those methods on a
- * non-narrowed `WalletAdapter` is a TypeScript error; that's the
- * point. The discriminant carries the type-level fact "this method
- * doesn't exist on EVM" so consumers can't accidentally branch on
- * `capabilities.signIn` and call a method that EVM adapters don't
- * implement.
- *
- * Runtime gating via `capabilities` still matters for the methods that
- * are OPTIONAL within a platform (a Solana wallet might or might not
- * advertise `solana:signTransaction`). Capabilities narrow "wallet
- * supports this feature"; the discriminated union narrows "this
- * platform has this concept at all".
+ * 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.
  */
 type WalletAdapter = EvmAdapter | SvmAdapter | SuiAdapter | BitcoinAdapter | PolkadotAdapter;
 type ConnectedWallet = {
@@ -422,33 +329,15 @@ type ConnectedWallet = {
 //#endregion
 //#region src/types/discoverer.d.ts
 /**
- * Self-describing discovery descriptor for a single chain platform.
- *
- * Each platform package (`@usebutr/evm`, `@usebutr/svm`, `@usebutr/sui`,
- * `@usebutr/bitcoin`) exports one of these. The aggregator package
- * (`@usebutr/wallets`) composes them into `autoDiscovery()` without
- * needing to know per-platform defaults; the descriptor owns them.
- *
- * Adding a new chain platform means writing a `PlatformDiscoverer`
- * inside the new package and adding one import to the aggregator's
- * registry, which is keyed by `ChainPlatform`. The aggregator's logic
- * doesn't need to grow.
- *
- * Two parts:
- *  - `subscribe`: the primary discovery channel (EIP-6963 / Wallet
- *    Standard / etc).
- *  - `fallback`: optional. The legacy-injected channel that should
- *    only emit if the primary channel hasn't produced an adapter for
- *    the same browser session by the settle deadline. `@usebutr/evm`
- *    has one (window.ethereum); `@usebutr/bitcoin` has one
- *    (window.unisat / sats-connect / window.btc); SVM and Sui don't.
+ * Each platform package exports exactly one; `@usebutr/wallets` composes
+ * them via a registry keyed by `ChainPlatform`, so a new chain adds a
+ * descriptor and a registry entry, not aggregator logic.
  */
 type PlatformDiscoverer = {
   /**
-   * Optional legacy-injected fallback. Subscribes only when consumers
-   * haven't disabled it. The hook receives `hasAnyPrimaryAdapter` so
-   * the fallback can defer to standards-based discovery when an adapter
-   * for the same wallet has already announced through the primary path.
+   * Legacy-injected channel (window.ethereum, window.unisat, …). Must
+   * consult `hasAnyPrimaryAdapter` and stay quiet when standards-based
+   * discovery already announced the same wallet, or it double-lists.
    */
   fallback?: {
     subscribe: (onAdapter: (adapter: WalletAdapter) => void, opts: {
@@ -461,16 +350,9 @@ type PlatformDiscoverer = {
 //#endregion
 //#region src/types/errors.d.ts
 /**
- * Tagged union of normalised connection errors.
- *
- * butr maps thrown values from connectors (which vary across wallet SDKs:
- * MetaMask uses EIP-1193 codes, Phantom throws stringly-typed errors,
- * embedded SDKs throw their own classes) into a small set of UX-meaningful
- * variants. Consumers branch on `kind` instead of regexing message strings.
- *
- * `message` is always present and human-readable. `cause` preserves the
- * original thrown value so callers can inspect raw connector errors when
- * the variant is `Unknown`.
+ * 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";
@@ -493,25 +375,21 @@ type ConnectionError = {
   kind: "Timeout";
   message: string;
 } | {
-  cause?: unknown;
+  cause?: ErrorCause;
   kind: "Unknown";
   message: string;
 };
 type ConnectionErrorKind = ConnectionError["kind"];
+type ErrorCause = Error | string;
+type CodedError = Error & {
+  code: number | string;
+};
 /**
- * Normalise a thrown value into a `ConnectionError`.
- *
- * Recognises:
- *  - butr's own `Error("Connection timeout")` (from the 90s connect timeout)
- *  - butr's own `Error("Failed to get account")` (from the connect flow)
- *  - EIP-1193 numeric `code` properties (`4001` → UserRejected,
- *    `-32002` → RequestPending, `4100`/`4900`/`4901` → NotConnected:
- *    unauthorized / disconnected from all-or-one chains)
- *  - common message substrings: "user rejected" / "user denied",
- *    "locked", "chain", etc.
- *  - anything else → `Unknown` with `cause` set to the original value.
+ * 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.
  */
-declare const mapConnectionError: (raw: unknown) => ConnectionError;
+declare const mapConnectionError: (raw: ErrorCause) => ConnectionError;
 //#endregion
 //#region src/storage/persistence.d.ts
 type MaybePromise<T> = T | Promise<T>;
@@ -558,16 +436,9 @@ type WalletPersistence = {
 //#endregion
 //#region src/storage/snapshot.d.ts
 /**
- * Server-safe view of a butr-persisted session; everything you can
- * know about a user's connected wallets from the cookie payload alone,
- * without instantiating a `Connector`.
- *
- * Notably absent: the `Connector` instance. A wallet extension exists
- * only in the browser, so a server render can know *which* wallet was
- * connected and *what address* it held, but cannot dispatch
- * `signMessage`/`sendTransaction` on it. Splitting display from action
- * along this seam keeps the impossibility expressed in the types
- * rather than hidden inside a runtime check.
+ * 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;
@@ -587,53 +458,22 @@ type SnapshotOptions = {
 };
 declare const EMPTY_SNAPSHOT: WalletSnapshot;
 /**
- * Parse a cookie source into a server-safe `WalletSnapshot`.
- *
- * Pure, sync, no `document`, no React; runnable in any environment
- * (Server Component, route handler, edge middleware, even client
- * code). Pair with `createCookieStorageDriver({ initialCookies })`
- * and `<WalletManagerProvider initialSnapshot={…} />` to render a
- * connected shell server-side without a hydration flash.
- *
- * **Stale-snapshot semantics.** The snapshot reflects whatever the
- * browser most recently persisted. If the user has since uninstalled
- * the wallet, switched accounts, or disconnected in another tab, the
- * client-side hydration will reconcile reality and the live store
- * will diverge from the snapshot. Treat the snapshot as an
- * *optimistic* shell; accurate enough to avoid a paint flicker,
- * authoritative only after `useIsHydrated()` is true.
- *
- * **Inputs.** Accepts the three shapes Next.js / Express / Hono /
- * generic-Node cookie code naturally produces:
- *  - A plain object: `{ "butr-pool": "{...}", … }`
- *  - An array of `{ name, value }` (Next.js' `cookies().getAll()`)
- *  - An iterable of `[name, value]` tuples
- *
- * Malformed entries are dropped with a `logWarn` (same policy as
- * `WalletStorage.getPool`); a cross-tab corruption shouldn't crash
- * the server render.
+ * 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/types/manager.d.ts
 /**
- * Outcome of butr's mount-time hydration pass. Passed to
- * `WalletManagerConfig.onHydrated`. Three buckets:
- *
- *  - `restoredIds`: wallets that came back fully. Their pool entries
- *    are live and consumers can use them immediately.
- *  - `pendingIds`: wallets whose adapter wasn't registered yet
- *    (auto-discovery's async warmup). The runtime retries each one
- *    when discovery announces a matching id, so most of these will
- *    restore within a few hundred ms of mount.
- *  - `dropped`: wallets whose restore actually failed (connector
- *    threw mid-flight). These have been removed from storage; consumer
- *    UX can surface "Couldn't reconnect Phantom; connect again."
+ * `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.
  */
 type HydrationOutcome = {
   dropped: Array<{
     connectorId: string;
-    reason: unknown;
+    reason: ErrorCause;
   }>;
   pendingIds: Array<string>;
   restoredIds: Array<string>;
@@ -644,67 +484,37 @@ type WalletManagerConfig = {
   /** Function to instantiate a connector by ID */
   createConnector: (id: string) => WalletAdapter | null;
   /**
-   * Seed the store synchronously with persisted wallet state; typically
-   * the return value of `readWalletSnapshot(cookies, { keyPrefix })`
-   * called from a Server Component. When provided:
-   *  - `pool` is populated with `ConnectedWallet` entries whose
-   *    `connector` is a shadow adapter (see `createShadowAdapter`):
-   *    identity-only, all capabilities `false`, methods throw
-   *    `ShadowConnectorError` if called.
-   *  - `activeConnectorId` and `selection` are set from the snapshot.
-   *  - `isHydrated` flips `true` immediately on construction.
-   *  - Every seeded id appears in `reconnectingIds`; the background
-   *    silent-reconnect pass removes the id and replaces the pool
-   *    entry with a live adapter on success, or drops the entry on
-   *    failure.
-   *
-   * Pre-hydration UI renders from the snapshot's data (address,
-   * accounts, chain, name, icon) without a flash. Action affordances
-   * (sign, send) are naturally gated by the shadow's all-false
-   * capabilities, or consumers can branch on `reconnectingIds`.
+   * 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;
   /**
-   * Called after a connection attempt fails (user rejected, wallet
-   * locked, chain mismatch, timeout, …). Receives the normalised
-   * `ConnectionError` plus the id of the connector that was being
-   * connected. Useful for piping into observability tooling
-   * (Sentry, OTel) without each consumer wiring `try/catch`s around
-   * `connectWallet` themselves.
+   * Fires for every failed attempt (rejection, locked wallet, timeout,
+   * …), so observability can hook here instead of wrapping every
+   * `connectWallet` call.
    */
   onConnectError?: (error: ConnectionError, connectorId: string) => void;
   /** Called after a wallet is disconnected */
   onDisconnect?: (chainPlatform: ChainPlatform) => void;
-  /**
-   * Called once after butr's mount-time hydration finishes. Receives a
-   * `HydrationOutcome` summarising which stored wallets were restored,
-   * which are pending an adapter announcement, and which failed.
-   * Useful for surfacing "Phantom couldn't be reconnected; try
-   * again" UX or piping a metric to telemetry.
-   */
+  /** Fires once, after the mount-time hydration pass. */
   onHydrated?: (outcome: HydrationOutcome) => void;
   /** Called after all wallets are reset (e.g., to clear auth tokens) */
   onReset?: () => void | Promise<void>;
   /**
-   * Called when a connect attempt takes longer than
-   * `slowConnectThresholdMs` (default 5_000) but hasn't yet resolved
-   * or rejected. Fires at most once per connect attempt. Useful for
-   * surfacing a "still trying, check your wallet" hint in the UI or
-   * piping a slow-path metric to telemetry.
+   * Fires at most once per attempt, once it passes
+   * `slowConnectThresholdMs` without settling. The attempt keeps
+   * running; this is a hint, not a timeout.
    */
   onSlowConnect?: (connectorId: string) => void;
   /**
-   * Called when a storage write fails. butr's persistence layer is
-   * fire-and-forget by design (any individual write can fail without
-   * breaking butr's reducer state), but the consumer might still want
-   * to know; quota-exceeded errors, IndexedDB shutdown, cross-tab
-   * conflicts, cookie size limits. `context` is a short string
-   * describing which write failed (e.g. `"failed to persist pool"`).
-   * The default behaviour when no callback is set is `console.warn`.
+   * 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: unknown, context: string) => void;
+  onStorageError?: (error: ErrorCause, context: string) => void;
   /** Threshold for `onSlowConnect`, in milliseconds. Defaults to 5_000. */
   slowConnectThresholdMs?: number;
   /** Optional custom persistence implementation (e.g., cookie-backed) */
@@ -715,55 +525,9 @@ type WalletManagerConfig = {
 //#endregion
 //#region src/types/signer.d.ts
 /**
- * Per-platform signer type registry.
- *
- * `Connector.getSigner()` returns `Promise<unknown>` because the actual
- * signer shape lives in the platform-specific packages: `@usebutr/evm`
- * returns an EIP-1193 provider, `@usebutr/svm` returns a Wallet
- * Standard wallet, `@usebutr/sui` returns the same Wallet Standard
- * wallet narrowed to Sui features, `@usebutr/bitcoin` returns either a
- * Wallet Standard wallet or an injected provider depending on which
- * adapter discovered it.
- *
- * Consumers cast the `unknown` to whichever signer their integration
- * library expects. This registry exists so the cast target is sourced
- * from one place; when a platform package renames its signer type,
- * consumer code keeps working through the registry without an explicit
- * patch.
- *
- * **How to extend.** Each platform package declares a module-augmentation
- * block that adds its key to this interface. For example,
- * `@usebutr/evm` ships:
- *
- * ```ts
- * declare module "@usebutr/core" {
- *   interface SignerForPlatform {
- *     evm: Eip1193Provider;
- *   }
- * }
- * ```
- *
- * Consumers that import the EVM package get the typed entry for free;
- * the augmentation is transitive through TypeScript's structural
- * declaration merging.
- *
- * **Usage.**
- *
- * ```ts
- * import type { SignerForPlatform } from "@usebutr/core";
- *
- * const signer = (await wallet.connector.getSigner()) as SignerForPlatform["evm"];
- * ```
- *
- * The cast is still there: `getSigner` itself stays type-erased to
- * keep the cross-package boundary loose, but the cast target lives in
- * one canonical place.
- *
- * **Why not make `getSigner` generic.** Generic-on-platform `getSigner`
- * would require `Connector` to be a discriminated union by
- * `chainPlatform`, which is a public-API breaking change held for a
- * future major release. The registry is the small step you can take
- * today; the union is the larger step that makes the cast obsolete.
+ * 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. */
@@ -771,34 +535,24 @@ type SignerOf<P extends keyof SignerForPlatform> = SignerForPlatform[P];
 //#endregion
 //#region src/wallet-source.d.ts
 /**
- * A discovery seam. Implementations call `onAdapter(adapter)` each time
- * they find a wallet and return an unsubscribe handle. `@usebutr/wallets`
- * composes EVM + SVM into a single `WalletSource`; third parties can
- * implement this type without depending on `@usebutr/wallets`.
+ * 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;
 };
 /**
- * Wrap a bare `subscribe` function (the exact shape of
- * `discoverEvmAdapters` / `discoverSvmAdapters`) into a `WalletSource`,
- * so an EVM-only app can do
- * `createWalletSource(discoverEvmAdapters)` without importing anything
- * protocol-bearing beyond `@usebutr/evm`.
+ * 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;
 //#endregion
 //#region src/store/reducer.d.ts
 /**
- * Public connection-status enum. `state.connectionStatus` in the
- * reducer only takes the first four values ("idle" | "connecting" |
- * "success" | "error"); those track the user-initiated connect
- * attempt. The fifth value, `"reconnecting"`, is *derived* by
- * `useConnectionStatus` when the active wallet is still backed by a
- * shadow adapter (its id is in `state.reconnectingIds`). The
- * derivation lives in the React selector so the reducer can stay a
- * narrow state machine while the public API matches wagmi's
- * vocabulary.
+ * 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 = {
@@ -810,13 +564,9 @@ type State = {
   isUserDisconnected: boolean;
   pool: Map<string, ConnectedWallet>;
   /**
-   * Connector IDs whose pool entry is currently backed by a shadow
-   * adapter: created from `WalletManagerConfig.initialState` and
-   * waiting for the live adapter to be announced (via discovery) and
-   * the silent reconnect to succeed. The set shrinks as entries
-   * upgrade (`HYDRATED` / `CONNECT_SUCCEEDED` clear matching ids) or
-   * drop (`DISCONNECTED` / `RESET`). Empty for stores constructed
-   * without `initialState`.
+   * Ids still backed by a shadow adapter from `initialState`. Empty
+   * without `initialState`; shrinks on `HYDRATED` / `CONNECT_SUCCEEDED`
+   * and on `DISCONNECTED` / `RESET`.
    */
   reconnectingIds: ReadonlySet<string>;
   selection: Map<ChainPlatform, string>;
@@ -824,40 +574,20 @@ type State = {
 //#endregion
 //#region src/store/shadow-adapter.d.ts
 /**
- * Error thrown when a method is called on a shadow adapter; the
- * placeholder `WalletAdapter` that the store seeds into the pool when
- * an `initialState` is provided (e.g. from a server-rendered cookie
- * snapshot). Shadow adapters carry the identity and account data of a
- * previously-connected wallet, but the live wallet extension hasn't
- * been verified yet; the silent reconnect happens asynchronously
- * after mount.
- *
- * UI code that gates affordances on `wallet.connector.capabilities.*`
- * never reaches a shadow method (capabilities are all `false`). Code
- * that calls through anyway hits this typed error, which is the
- * correct loud failure: the consumer ignored the capability gate.
- *
- * Consumers wanting to wait out the reconnecting window should branch
- * on whether `connectorId` is in `state.reconnectingIds`.
+ * 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.
  */
-declare class ShadowConnectorError extends Error {
+declare class ShadowConnectorError extends Error implements CodedError {
   readonly code = "BUTR_RECONNECTING";
   readonly connectorId: string;
   readonly method: string;
   constructor(method: string, connectorId: string);
 }
 /**
- * Type guard. Returns true when an adapter is a placeholder created
- * by `createShadowAdapter`. Useful for the hydration coordinator
- * (which needs to know which pool entries still need upgrading) and
- * for consumers writing wagmi-style "is this connection verified yet"
- * checks without subscribing to `reconnectingIds` directly.
- *
- * Detection is structural: a shadow has all capabilities set to false.
- * Live adapters always advertise at least one capability (every wallet
- * surface includes `getBalance`, `signMessage`, `switchChain` as
- * required methods, and adapter constructors set their flags
- * accordingly).
+ * Structural detection: relies on every live adapter advertising at
+ * least one capability, since `getBalance`, `signMessage` and
+ * `switchChain` are required on all wallet surfaces.
  */
 declare const isShadowAdapter: (adapter: WalletAdapter) => boolean;
 //#endregion
@@ -886,22 +616,13 @@ type CookieDriverOptions = {
    */
   domain?: string;
   /**
-   * Snapshot of cookies for the SSR pass; typically the result of
-   * Next.js' `cookies()` (from `next/headers`) or a parsed
-   * `req.headers.cookie`. Used only when `document` is unavailable.
-   *
-   * When provided, `getItem` reads from this snapshot during the
-   * server render so the store sees the same persisted state the
-   * client will see after hydration. Writes remain no-ops on the
-   * server: emitting `Set-Cookie` has to be done by the framework
-   * layer that owns the response.
+   * Server-side cookie snapshot (Next.js' `cookies()`, a parsed
+   * `req.headers.cookie`, …) read only when `document` is unavailable,
+   * so the SSR pass sees the state the client will hydrate with.
    */
   initialCookies?: InitialCookies;
   /**
-   * Lifetime in seconds. Defaults to 30 days. Pass `undefined`
-   * (the default) for "until the session ends", but note that
-   * butr persists wallet state across sessions, so a finite
-   * max-age is usually what consumers want.
+   * Lifetime in seconds. Defaults to 30 days.
    */
   maxAgeSeconds?: number;
   /**
@@ -921,34 +642,16 @@ type CookieDriverOptions = {
   secure?: boolean;
 };
 /**
- * Cookie-backed storage driver. Reads/writes `document.cookie`;
- * server-readable, survives reloads, scoped per `domain`/`path`.
- *
- * **When to use this:** SSR apps that need to know who's connected
- * during the server render (so they can stream the connected-wallet
- * UI without a client-side hydration flicker). Pass `initialCookies`
- * from a server-side cookie source (e.g. `cookies()` in Next.js'
- * `next/headers`, or a parsed `req.headers.cookie`) and the same
- * driver will serve those values during the server render and switch
- * to `document.cookie` once it mounts in the browser.
- *
- * **Trade-offs vs `localStorage`:** cookies travel with every
- * request, so they cost bytes on the wire. Keep the storage key
- * prefix short, and prefer this driver for the `persistent` slot
- * only: the `session` slot can stay in `sessionStorage` (which
- * cookies can't natively model anyway).
- *
- * **Server-side writes are no-ops.** Emitting `Set-Cookie` requires
- * access to the framework's response object, which a storage driver
- * shouldn't reach into. The store doesn't mutate persisted state
- * during the SSR pass anyway; writes only fire after client mount,
- * once `document.cookie` is reachable.
+ * Server-side writes are no-ops: `Set-Cookie` needs the framework's
+ * response object. Cookies ride every request, so use this driver for
+ * the `persistent` slot only and leave `session` on `sessionStorage`.
  */
 declare const createCookieStorageDriver: (options?: CookieDriverOptions) => StorageDriver;
 //#endregion
 //#region src/storage/wallet-storage.d.ts
 type StorageConfig = {
-  keyPrefix: string;
+  /** Defaults to `"butr"`, matching `readWalletSnapshot`. */
+  keyPrefix?: string;
   /** Survives app restart. Defaults to localStorage on web. */
   persistent?: StorageDriver;
   /** Cleared on session end. Defaults to sessionStorage on web. */
@@ -962,27 +665,22 @@ declare class WalletStorage implements WalletPersistence {
   private readonly persistent;
   private readonly session;
   /**
-   * Serializes pool-key mutations so concurrent fire-and-forget
-   * writes can't interleave their read-modify-write phases. Without
-   * this, two simultaneous `setPool` calls both read the pre-write
-   * state, each merge their own entries, and whichever finishes last
-   * overwrites the other's additions. Reads (`getPool`) don't enter
-   * the queue; they observe whatever's currently in the driver.
+   * 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>;
   /**
-   * Upsert the in-memory pool into storage. Additive: entries in
-   * `pool` are written; entries already in storage that aren't in
-   * `pool` are kept. The in-memory pool reflects "what's live right
-   * now", not "the complete list of remembered connections"; a
-   * silent reconnect that fails on reload leaves the entry out of
-   * the pool but the saved entry stays so the next load can retry.
-   * Use `removePoolEntry` for explicit eviction (the user clicked
-   * Disconnect) and `clearAll` for a full wipe (reset).
+   * 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>;
@@ -993,12 +691,9 @@ declare class WalletStorage implements WalletPersistence {
   setActiveConnectorId(connectorId: string | null): Promise<void>;
   clearAll(): Promise<void>;
   /**
-   * Disconnect-intent tracking.
-   *
-   * Lives in the session driver: survives component remounts (unlike refs)
-   * but clears when the session ends (unlike the persistent driver).
-   * Prevents auto-connect from firing immediately after a manual disconnect,
-   * while still allowing auto-connect on fresh sessions.
+   * 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>;
@@ -1032,38 +727,17 @@ declare const createWalletStore: (config: WalletManagerConfig) => import("zustan
 //#endregion
 //#region src/group-by-platform.d.ts
 /**
- * Bucket a flat list into per-platform groups.
- *
- * A multi-chain wallet announces one adapter per platform it speaks, so
- * discovery hands back a flat list where a single brand appears several
- * times. Any app targeting more than one chain has to bucket that list
- * before rendering, and hand-rolled versions drift: butr's own demos
- * carried a copy that reimplemented `CHAIN_PLATFORMS` as a local
- * ordering constant.
- *
- * Keys are inserted in `CHAIN_PLATFORMS` order and platforms with no
- * members are omitted, so the result is directly iterable for rendering
- * (`[...groups]`) as well as addressable for lookup (`groups.get("evm")`)
- * without a further emptiness filter.
- *
- * `getPlatform` exists because the discriminant sits at a different depth
- * depending on the input: a discovered `WalletAdapter` carries
- * `chainPlatform` at the top level, a pool entry nests it under
- * `connector`. React consumers should reach for
- * `useDiscoveredWalletsByPlatform` / `useConnectedWalletsByPlatform`
- * instead, which bind the accessor for them.
+ * A multi-chain wallet announces one adapter per platform, so brands
+ * repeat in the flat list. Keys follow `CHAIN_PLATFORMS` order and empty
+ * platforms are omitted, so `[...groups]` needs no emptiness filter.
  */
 declare const groupByPlatform: <T>(items: ReadonlyArray<T>, getPlatform: (item: T) => ChainPlatform) => Map<ChainPlatform, Array<T>>;
 //#endregion
 //#region src/sign-in/sign-in-flow.d.ts
 /**
- * What the wallet produced, encoded for transport. Both byte fields are
- * base64 because that is what survives `JSON.stringify` intact; the raw
- * `Uint8Array`s are kept alongside for callers verifying in-process.
- *
- * Verify against `signedMessage`, not `message`. Solana Wallet Standard
- * wallets may prefix or re-encode what they sign, so the bytes that carry
- * the signature are the wallet's, not yours.
+ * Verify against `signedMessage`, not `message`: Solana Wallet Standard
+ * wallets may prefix or re-encode what they sign. Base64 mirrors exist
+ * because `Uint8Array` does not survive `JSON.stringify`.
  */
 type SignInResult = {
   account: Account;
@@ -1086,15 +760,9 @@ type SignInMessageContext = {
 };
 type SignInFlowOptions = {
   /**
-   * Compose the message to sign. Defaults to a plain
-   * `<address> signs in. Nonce: <nonce>` line.
-   *
-   * butr deliberately does not ship a wire format here: a message a
-   * server must parse is an authentication spec, and SIWE / SIWS already
-   * fill that role. Pass the formatter your backend expects.
-   *
-   * Unused on the SIWS path, where the wallet composes the message from
-   * the input fields.
+   * butr ships no wire format: a server-parsed message is an auth spec,
+   * and SIWE / SIWS already fill that role. Pass what your backend
+   * expects. Unused on the SIWS path, where the wallet composes it.
    */
   buildMessage?: (ctx: SignInMessageContext) => string;
   /** Fetch a single-use nonce from your backend. */
@@ -1111,6 +779,9 @@ type SignInFlowOptions = {
   /** Hand the signed result to your backend. Throw to fail the flow. */
   verify: (result: SignInResult) => Promise<void>;
 };
+type SignInFlow = {
+  signIn: (wallet: ConnectedWallet, account?: Account) => Promise<SignInResult>;
+};
 /** Thrown before any wallet interaction when the wallet can't sign at
  *  all. Distinct from a rejection: nothing was asked of the user, so UI
  *  should say "this wallet can't sign in" rather than "you declined". */
@@ -1119,52 +790,17 @@ declare class SignInUnsupportedError extends Error {
   constructor(connectorId: string);
 }
 /**
- * Build a reusable sign-in flow: nonce, capability gate, signature,
- * encoding, verification.
- *
- * Every wallet-auth app writes this same sequence, and the parts that
- * are easy to get wrong are the ones that aren't about the app: which
- * capability flag gates the attempt, whether a Solana wallet should take
- * the SIWS path instead, and which bytes to base64 for the server (the
- * wallet's `signedMessage`, not the input). This owns those; you own the
- * nonce endpoint, the message format, and the verifier.
- *
- * ```ts
- * const { signIn } = createSignInFlow({
- *   getNonce: () => fetch("/api/nonce").then((r) => r.text()),
- *   verify: (result) =>
- *     fetch("/api/verify", { body: JSON.stringify(result), method: "POST" }).then(() => {}),
- * });
- *
- * await signIn(wallet);
- * ```
- *
- * Solana wallets advertising `solana:signIn` take the SIWS path
- * automatically, so `result.signedMessage` holds the wallet-composed
- * SIWS statement and `result.message` is absent. Set
- * `preferSignMessage` to opt out.
+ * Solana wallets advertising `solana:signIn` take the SIWS path, so
+ * `result.signedMessage` holds the wallet-composed statement and
+ * `result.message` is absent. `preferSignMessage` opts out.
  */
-declare const createSignInFlow: (options: SignInFlowOptions) => {
-  signIn: (wallet: ConnectedWallet, account?: Account) => Promise<SignInResult>;
-};
+declare const createSignInFlow: (options: SignInFlowOptions) => SignInFlow;
 //#endregion
 //#region src/wallet-equal.d.ts
 /**
- * Two wallet snapshots are equivalent for selector purposes iff they
- * share the same adapter instance, active account address, and active
- * account chain id. Used by `useStoreWithEqualityFn` consumers
- * (active-wallet, selected-wallet, useWalletEntry) to suppress spurious
- * re-renders when the underlying Map churns but the resolved entry
- * hasn't changed.
- *
- * The adapter is compared by reference, not by `connector.id`: hydration
- * replaces a shadow adapter with the live one under an unchanged id and
- * address, so an id comparison reports "equal" and leaves consumers
- * holding a placeholder whose every method throws ShadowConnectorError.
- *
- * Hoisted to its own module so the equivalence rule lives in one place;
- * if we ever extend the snapshot (e.g. to consider `accounts.length`),
- * every selector hook picks up the new rule for free.
+ * 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.
  */
 declare const walletEqual: (a: ConnectedWallet | undefined, b: ConnectedWallet | undefined) => boolean;
 //#endregion
@@ -1174,43 +810,17 @@ declare const logError: (...args: ReadonlyArray<unknown>) => void;
 //#endregion
 //#region src/sanitize-icon.d.ts
 /**
- * Normalize a wallet-announced icon string.
- *
- * Wallets announce their icon through external metadata; EIP-6963
- * `providerInfo.icon`, Wallet Standard `wallet.icon`. That value is
- * not under butr's control, and some wallets ship data-URI icons with
- * surrounding whitespace (a newline left over from a pretty-printed
- * manifest). Strict consumers reject it: Next.js's `<Image>` throws
- * because `src` must not start with a control character.
- *
- * Trims surrounding whitespace and treats an all-whitespace (or empty)
- * icon as absent, so consumers get either a usable string or
- * `undefined`: never a blank or malformed one. `undefined` passes
- * through untouched.
- *
- * **Discovery already applies this.** Every adapter butr discovers has
- * had its icon sanitized at construction, so `Connector.icon` is safe to
- * render as-is. Reach for this helper only when building adapter or
- * `ConnectorMeta` metadata yourself from a source butr didn't produce.
+ * Some wallets announce data-URI icons wrapped in whitespace, which
+ * makes Next.js `<Image>` throw on a leading control character.
+ * Discovery already applies this; only hand-built metadata needs it.
  */
 declare const sanitizeIcon: (icon: string | undefined) => string | undefined;
 //#endregion
 //#region src/encoding/bytes.d.ts
 /**
- * Shared byte-encoding helpers for the connector packages.
- *
- * These functions sit directly on the signing/address path of every
- * chain. They used to be hand-reimplemented in ~10 connector files; a
- * single tested module removes the drift surface (a `padStart` omission
- * or base64 variant mismatch corrupts signatures/addresses for one chain
- * only, and the divergence is invisible because the copies look "the
- * same").
- *
- * Hex prefixing diverges across chains, so the module exposes **explicit
- * variants** rather than one function:
- * - {@link bytesToHex} returns bare hex (Bitcoin, Ledger).
- * - {@link bytesToHexPrefixed} returns `0x`-prefixed hex (EVM, Polkadot).
- * - {@link hexToBytes} tolerantly strips an optional `0x` (all callers).
+ * Hex prefixing diverges by chain (bare for Bitcoin and Ledger, `0x` for
+ * EVM and Polkadot), so the variants stay explicit: these sit on the
+ * signing path, where a silent mismatch corrupts one chain's signatures.
  */
 /** Bare lowercase hex, no `0x` prefix (Bitcoin, Ledger). */
 declare const bytesToHex: (bytes: Uint8Array) => string;
@@ -1239,5 +849,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 SignInMessageContext, type SignInResult, SignInUnsupportedError, type SignerForPlatform, type SignerOf, type SnapshotOptions, type StorageDriver, type StoredPoolEntry, type StoredPoolRecord, type StoredSelectionRecord, type SuiAdapter, type SuiWallet, type SvmAdapter, type SvmWallet, type WalletAdapter, type WalletAvailability, type WalletBase, type WalletCapabilities, type WalletManagerConfig, type WalletPersistence, 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 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 };
 //# sourceMappingURL=index.d.ts.map