@usebutr/core 1.1.0 → 2.0.0

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,38 @@ 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;
 //#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 +134,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 +150,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 = {
@@ -293,12 +206,9 @@ type WalletBase = {
   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." */
+  /** `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: unknown, account?: Account) => Promise<string>;
   /** Submit a transaction targeting a specific chain. The optional
    *  callback fires after the connector has switched chain (consumers
@@ -306,15 +216,9 @@ type WalletBase = {
    *  specific exposed address (see `sendTx`). */
   sendTxToChain: (tx: unknown, 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 +231,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
@@ -363,24 +263,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: unknown, 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>;
 };
 /**
- * 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 +295,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 +312,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 +333,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";
@@ -499,17 +364,9 @@ type ConnectionError = {
 };
 type ConnectionErrorKind = ConnectionError["kind"];
 /**
- * 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;
 //#endregion
@@ -558,16 +415,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,48 +437,17 @@ 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<{
@@ -644,65 +463,35 @@ 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;
   /** Threshold for `onSlowConnect`, in milliseconds. Defaults to 5_000. */
@@ -715,55 +504,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 +514,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 +543,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,21 +553,9 @@ 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 {
   readonly code = "BUTR_RECONNECTING";
@@ -847,17 +564,9 @@ declare class ShadowConnectorError extends Error {
   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 +595,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 +621,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 +644,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 +670,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 +706,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 +739,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. */
@@ -1119,30 +766,9 @@ 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>;
@@ -1150,21 +776,9 @@ declare const createSignInFlow: (options: SignInFlowOptions) => {
 //#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 +788,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;