@usebutr/core 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -4,12 +4,16 @@
  * 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.
+ * via structural typing; butr never inspects beyond these 4 fields.
  */
 type ChainBase = {
-  /** CAIP-2 identifier, e.g. "eip155:1", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" */id: string; /** Human-readable name, e.g. "Ethereum", "Solana" */
-  name: string; /** CAIP-2 namespace, e.g. "eip155", "solana" */
-  namespace: string; /** CAIP-2 reference, e.g. "1", "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" */
+  /** CAIP-2 identifier, e.g. "eip155:1", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" */
+  id: string;
+  /** Human-readable name, e.g. "Ethereum", "Solana" */
+  name: string;
+  /** CAIP-2 namespace, e.g. "eip155", "solana" */
+  namespace: string;
+  /** CAIP-2 reference, e.g. "1", "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" */
   reference: string;
 };
 //#endregion
@@ -36,7 +40,7 @@ type StoredPoolEntry = {
   icon?: string;
   /** Human-facing wallet name (e.g. "MetaMask") captured at persist
    *  time. Required so the shadow adapter renders the same identity
-   *  the live adapter will — no "metamask" → "MetaMask" swap at the
+   *  the live adapter will; no "metamask" → "MetaMask" swap at the
    *  hydration boundary. */
   name: string;
 };
@@ -58,7 +62,7 @@ type WalletPersistence = {
 //#endregion
 //#region src/storage/snapshot.d.ts
 /**
- * Server-safe view of a butr-persisted session — everything you can
+ * 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`.
  *
@@ -89,7 +93,7 @@ declare const EMPTY_SNAPSHOT: WalletSnapshot;
 /**
  * Parse a cookie source into a server-safe `WalletSnapshot`.
  *
- * Pure, sync, no `document`, no React — runnable in any environment
+ * 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
@@ -100,7 +104,7 @@ declare const EMPTY_SNAPSHOT: WalletSnapshot;
  * 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,
+ * *optimistic* shell; accurate enough to avoid a paint flicker,
  * authoritative only after `useIsHydrated()` is true.
  *
  * **Inputs.** Accepts the three shapes Next.js / Express / Hono /
@@ -110,7 +114,7 @@ declare const EMPTY_SNAPSHOT: WalletSnapshot;
  *  - 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
+ * `WalletStorage.getPool`); a cross-tab corruption shouldn't crash
  * the server render.
  */
 declare const readWalletSnapshot: (source: CookieSource, options?: SnapshotOptions) => WalletSnapshot;
@@ -161,7 +165,7 @@ type ConnectionErrorKind = ConnectionError["kind"];
  *  - 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 —
+ *    `-32002` → RequestPending, `4100`/`4900`/`4901` → NotConnected:
  *    unauthorized / disconnected from all-or-one chains)
  *  - common message substrings: "user rejected" / "user denied",
  *    "locked", "chain", etc.
@@ -184,19 +188,31 @@ type Account = {
   id: string;
   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).
+ */
+declare const buildAccount: (address: string, chain: ChainBase) => Account;
 type Balance = {
-  /** Token decimals (e.g. 9 for SOL, 18 for ETH) */decimals: number; /** Human-readable string, trimmed of trailing zeros */
-  formatted: string; /** Token symbol (e.g. "SOL", "ETH") */
-  symbol: string; /** Raw integer amount */
+  /** Token decimals (e.g. 9 for SOL, 18 for ETH) */
+  decimals: number;
+  /** Human-readable string, trimmed of trailing zeros */
+  formatted: string;
+  /** Token symbol (e.g. "SOL", "ETH") */
+  symbol: string;
+  /** Raw integer amount */
   value: bigint;
 };
 /**
  * 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
+ * - `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
+ * - `not-installed`: the wallet isn't reachable. Consumers typically render
  *   a "download" affordance pointing at `meta.url`.
  */
 type WalletAvailability = "installed" | "loadable" | "not-installed";
@@ -215,7 +231,7 @@ type WalletAvailability = "installed" | "loadable" | "not-installed";
  *     - 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`.
+ *   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.).
  */
@@ -247,15 +263,17 @@ type ConnectorEvent = {
  * of which chain is passed.
  */
 type WalletCapabilities = {
-  /** `getBalance` returns a real on-chain value (vs. a 0n placeholder). */getBalance: boolean; /** `getTransactionReceipt` returns a real RPC response. */
+  /** `getBalance` returns a real on-chain value (vs. a 0n placeholder). */
+  getBalance: boolean;
+  /** `getTransactionReceipt` returns a real RPC response. */
   getTransactionReceipt: boolean;
-  /** Calling `requestAccounts` will actually do something — either
+  /** Calling `requestAccounts` will actually do something: either
    *  prompt the user (EIP-2255) or refresh the exposed list. */
   requestAccounts: boolean;
   /** `sendTx` / `sendTxToChain` will work. False for SVM wallets that
    *  don't advertise `solana:signAndSendTransaction`. */
   sendTransaction: boolean;
-  /** `signIn` works — Sign In With Solana (`solana:signIn`). True only
+  /** `signIn` works: Sign In With Solana (`solana:signIn`). True only
    *  for SVM wallets advertising the feature. */
   signIn: boolean;
   /** `signMessage` will work. False for SVM wallets that don't
@@ -266,10 +284,11 @@ type WalletCapabilities = {
    *  wallets advertising `solana:signTransaction`; butr ships no RPC so
    *  it can't broadcast the result itself. EVM/hardware adapters leave
    *  this `false` (no `signTransaction` method). */
-  signTransaction: boolean; /** Wallet emits account/chain change events that butr can bridge. */
+  signTransaction: boolean;
+  /** Wallet emits account/chain change events that butr can bridge. */
   subscribe: boolean;
-  /** `switchAccount` is real. Almost always `false` for auto adapters
-   *  — neither protocol exposes silent account switch. Hand-rolled
+  /** `switchAccount` is real. Almost always `false` for auto adapters;
+   *  neither protocol exposes silent account switch. Hand-rolled
    *  adapters with custom transports may set it `true`. */
   switchAccount: boolean;
   /** `switchChain` routes subsequent calls through the new chain. EVM:
@@ -278,12 +297,12 @@ type WalletCapabilities = {
   switchChain: boolean;
 };
 /**
- * Orchestration interface — what `butr` actually calls during the
+ * Orchestration interface: what `butr` actually calls during the
  * connect / disconnect / hydrate flow. This is the contract `butr`
  * cares about; everything else on `WalletAdapter` is consumer-facing.
  */
 type Connector<P extends ChainPlatform = ChainPlatform> = {
-  /** Runtime capability flags — see `WalletCapabilities`. Read these
+  /** Runtime capability flags; see `WalletCapabilities`. Read these
    *  to gate UI affordances rather than probing for method existence. */
   capabilities: WalletCapabilities;
   /** Discriminant: which chain platform this adapter speaks. Generic
@@ -295,7 +314,7 @@ type Connector<P extends ChainPlatform = ChainPlatform> = {
    *  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
+   *  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
@@ -303,7 +322,8 @@ type Connector<P extends ChainPlatform = ChainPlatform> = {
    *  the rejection as a clean restore failure. */
   connect: (opts?: {
     silent?: boolean;
-  }) => Promise<void>; /** Optional teardown. butr calls this on disconnect, error recovery, and reset. */
+  }) => Promise<void>;
+  /** Optional teardown. butr calls this on disconnect, error recovery, and reset. */
   disconnect?: () => Promise<void>;
   /** Read the currently-active account. butr uses this to populate the pool
    *  after a successful `connect()` and during hydration. */
@@ -316,15 +336,17 @@ type Connector<P extends ChainPlatform = ChainPlatform> = {
    *  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`. */
-  icon?: string; /** Stable key: "metamask", "phantom", etc. Pool entries are keyed by this. */
-  id: string; /** Human name: "MetaMask", "Phantom", etc. UI-facing only. */
+  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
+   *  new accounts; call `getAccounts()` (or use butr's
    *  `useRequestAccounts` hook, which refreshes the pool entry for
    *  you). */
   requestAccounts?: () => Promise<void>;
@@ -348,8 +370,9 @@ type WalletBase = {
   getBalance: (mint?: string) => Promise<Balance>;
   /** Returns a chain-specific signer. Consumers cast to the concrete
    *  type via the `SignerForPlatform` registry (or directly to the
-   *  library shape they wrap — `WalletClient` on viem, etc.). */
-  getSigner: () => Promise<unknown>; /** Look up the status of a previously-submitted transaction. */
+   *  library shape they wrap: `WalletClient` on viem, etc.). */
+  getSigner: () => Promise<unknown>;
+  /** Look up the status of a previously-submitted transaction. */
   getTransactionReceipt: (tx: string) => Promise<{
     status: "Success" | "Error" | "Pending";
   }>;
@@ -382,21 +405,22 @@ type WalletBase = {
   }>;
   /** Switch to a different account on the same wallet (some wallets
    *  expose multiple accounts simultaneously). */
-  switchAccount?: (address: string) => Promise<void>; /** Switch the wallet's active chain. */
+  switchAccount?: (address: string) => Promise<void>;
+  /** Switch the wallet's active chain. */
   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
+ * 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.
  */
 type EvmWallet = WalletBase;
 /**
  * Solana wallet surface. Adds:
- *  - `signIn` — Sign-In-With-Solana (`solana:signIn`). Optional;
+ *  - `signIn`: Sign-In-With-Solana (`solana:signIn`). Optional;
  *    `capabilities.signIn` gates availability at runtime.
- *  - `signTransaction` — sign-only path for wallets that advertise
+ *  - `signTransaction`: sign-only path for wallets that advertise
  *    `solana:signTransaction` but not `solana:signAndSendTransaction`.
  *    Optional; `capabilities.signTransaction` gates availability.
  */
@@ -404,7 +428,7 @@ type SvmWallet = WalletBase & {
   /** Sign In With Solana (SIWS, `solana:signIn`). Authenticates the user
    *  and returns the connected account plus the signed statement so the
    *  consumer can verify server-side. `input` is the SIWS message fields
-   *  (domain, statement, nonce, …) — pass `{}` or omit for wallet
+   *  (domain, statement, nonce, …); pass `{}` or omit for wallet
    *  defaults. */
   signIn?: (input?: Record<string, unknown>) => Promise<{
     account: Account;
@@ -437,12 +461,12 @@ type BitcoinWallet = WalletBase & {
  * 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
+ * `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`.
  */
 type PolkadotWallet = WalletBase;
-/** Per-platform full adapter shapes — `Connector` + the platform's
+/** Per-platform full adapter shapes: `Connector` + the platform's
  *  `Wallet` surface. These are the discriminated-union variants of
  *  `WalletAdapter`. */
 type EvmAdapter = Connector<"evm"> & EvmWallet;
@@ -451,12 +475,12 @@ type SuiAdapter = Connector<"sui"> & SuiWallet;
 type BitcoinAdapter = Connector<"bitcoin"> & BitcoinWallet;
 type PolkadotAdapter = Connector<"polkadot"> & PolkadotWallet;
 /**
- * Full adapter interface — discriminated union by `chainPlatform`.
+ * 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
+ * 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
@@ -473,7 +497,8 @@ type WalletAdapter = EvmAdapter | SvmAdapter | SuiAdapter | BitcoinAdapter | Pol
  *  `WalletBase`. Retained as an alias so existing names resolve. */
 type Wallet = WalletBase;
 type ConnectedWallet = {
-  /** Currently-active account on this wallet. */account: Account;
+  /** Currently-active account on this wallet. */
+  account: Account;
   /** All accounts known on this wallet at the time of connect/refresh.
    *  Always contains at least `account`. Populated from `getAccounts()`
    *  if the connector implements it; otherwise `[account]`. */
@@ -485,7 +510,8 @@ type ConnectorMeta = {
    *  available. Defaults to `"installed"` when omitted. Consumers call
    *  this at render time to gate the "Connect" button. */
   availability?: () => WalletAvailability;
-  chainPlatform: ChainPlatform; /** Optional image URL or data URI for wallet selection UIs. */
+  chainPlatform: ChainPlatform;
+  /** Optional image URL or data URI for wallet selection UIs. */
   icon?: string;
   id: string;
   name: string;
@@ -497,15 +523,15 @@ type ConnectorMeta = {
  * Outcome of butr's mount-time hydration pass. Passed to
  * `WalletManagerConfig.onHydrated`. Three buckets:
  *
- *  - `restoredIds` — wallets that came back fully. Their pool entries
+ *  - `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
+ *  - `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
+ *  - `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."
+ *    UX can surface "Couldn't reconnect Phantom; connect again."
  */
 type HydrationOutcome = {
   dropped: Array<{
@@ -516,10 +542,12 @@ type HydrationOutcome = {
   restoredIds: Array<string>;
 };
 type WalletManagerConfig = {
-  /** Available connector metadata */connectors: Array<ConnectorMeta>; /** Function to instantiate a connector by ID */
+  /** Available connector metadata */
+  connectors: Array<ConnectorMeta>;
+  /** Function to instantiate a connector by ID */
   createConnector: (id: string) => WalletAdapter | null;
   /**
-   * Seed the store synchronously with persisted wallet state — typically
+   * 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
@@ -536,9 +564,10 @@ type WalletManagerConfig = {
    * 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`.
+   * capabilities, or consumers can branch on `reconnectingIds`.
    */
-  initialState?: WalletSnapshot; /** Called after a wallet is successfully connected */
+  initialState?: WalletSnapshot;
+  /** Called after a wallet is successfully connected */
   onConnect?: (wallet: ConnectedWallet) => void;
   /**
    * Called after a connection attempt fails (user rejected, wallet
@@ -548,22 +577,24 @@ type WalletManagerConfig = {
    * (Sentry, OTel) without each consumer wiring `try/catch`s around
    * `connectWallet` themselves.
    */
-  onConnectError?: (error: ConnectionError, connectorId: string) => void; /** Called after a wallet is disconnected */
+  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
+   * Useful for surfacing "Phantom couldn't be reconnected; try
    * again" UX or piping a metric to telemetry.
    */
-  onHydrated?: (outcome: HydrationOutcome) => void; /** Called after all wallets are reset (e.g., to clear auth tokens) */
+  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
+   * surfacing a "still trying, check your wallet" hint in the UI or
    * piping a slow-path metric to telemetry.
    */
   onSlowConnect?: (connectorId: string) => void;
@@ -571,14 +602,17 @@ type WalletManagerConfig = {
    * 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
+   * 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`.
    */
-  onStorageError?: (error: unknown, context: string) => void; /** Threshold for `onSlowConnect`, in milliseconds. Defaults to 5_000. */
-  slowConnectThresholdMs?: number; /** Optional custom persistence implementation (e.g., cookie-backed) */
-  storage?: WalletPersistence; /** Storage key prefix for localStorage */
+  onStorageError?: (error: unknown, context: string) => void;
+  /** Threshold for `onSlowConnect`, in milliseconds. Defaults to 5_000. */
+  slowConnectThresholdMs?: number;
+  /** Optional custom persistence implementation (e.g., cookie-backed) */
+  storage?: WalletPersistence;
+  /** Storage key prefix for localStorage */
   storageKeyPrefix?: string;
 };
 //#endregion
@@ -588,7 +622,7 @@ type WalletManagerConfig = {
  * 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
+ * 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).
@@ -598,20 +632,20 @@ 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
+ * 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
+ * // 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
+ * // 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";
  *
@@ -629,16 +663,16 @@ declare const buildChainsByPlatform: (partial: Partial<ChainsByPlatform>) => Cha
  * 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.
+ * 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. The aggregator's logic doesn't need to grow.
  *
  * Two parts:
- *  - `subscribe` — the primary discovery channel (EIP-6963 / Wallet
+ *  - `subscribe`: the primary discovery channel (EIP-6963 / Wallet
  *    Standard / etc).
- *  - `fallback` — optional. The legacy-injected channel that should
+ *  - `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
@@ -655,8 +689,10 @@ type PlatformDiscoverer = {
     subscribe: (onAdapter: (adapter: WalletAdapter) => void, opts: {
       hasAnyPrimaryAdapter: () => boolean;
     }) => () => void;
-  }; /** Stable platform identifier. Used by the aggregator for keying. */
-  platform: ChainPlatform; /** Primary discovery subscription. */
+  };
+  /** Stable platform identifier. Used by the aggregator for keying. */
+  platform: ChainPlatform;
+  /** Primary discovery subscription. */
   subscribe: (onAdapter: (adapter: WalletAdapter) => void) => () => void;
 };
 //#endregion
@@ -665,7 +701,7 @@ type PlatformDiscoverer = {
  * Per-platform signer type registry.
  *
  * `Connector.getSigner()` returns `Promise<unknown>` because the actual
- * signer shape lives in the platform-specific packages — `@usebutr/evm`
+ * 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
@@ -674,7 +710,7 @@ type PlatformDiscoverer = {
  *
  * 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,
+ * from one place; when a platform package renames its signer type,
  * consumer code keeps working through the registry without an explicit
  * patch.
  *
@@ -702,8 +738,8 @@ type PlatformDiscoverer = {
  * 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
+ * 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`
@@ -739,7 +775,7 @@ declare const createWalletSource: (subscribe: (onAdapter: (adapter: WalletAdapte
 /**
  * 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
+ * "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
@@ -758,7 +794,7 @@ type State = {
   pool: Map<string, ConnectedWallet>;
   /**
    * Connector IDs whose pool entry is currently backed by a shadow
-   * adapter — created from `WalletManagerConfig.initialState` and
+   * 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
@@ -768,14 +804,51 @@ type State = {
   reconnectingIds: ReadonlySet<string>;
   selection: Map<ChainPlatform, string>;
 };
+//#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`.
+ */
+declare class ShadowConnectorError extends Error {
+  readonly code = "BUTR_RECONNECTING";
+  readonly connectorId: string;
+  readonly method: string;
+  constructor(method: string, connectorId: string);
+}
 /**
- * Lifecycle events: hydration, full reset, and the explicit
- * user-disconnected flag the runtime sets to suppress eager reconnect.
+ * 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).
  */
+declare const isShadowAdapter: (adapter: WalletAdapter) => boolean;
 //#endregion
 //#region src/storage/browser-storage-driver.d.ts
 type BrowserStorageDrivers = {
-  /** Survives app restart (localStorage on web, AsyncStorage/MMKV on RN). */persistent: StorageDriver; /** Cleared when the app session ends (sessionStorage on web, in-memory on RN). */
+  /** Survives app restart (localStorage on web, AsyncStorage/MMKV on RN). */
+  persistent: StorageDriver;
+  /** Cleared when the app session ends (sessionStorage on web, in-memory on RN). */
   session: StorageDriver;
 };
 declare const createMemoryStorageDriver: () => StorageDriver;
@@ -796,20 +869,20 @@ type CookieDriverOptions = {
    */
   domain?: string;
   /**
-   * Snapshot of cookies for the SSR pass — typically the result of
+   * 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
+   * server: emitting `Set-Cookie` has to be done by the framework
    * layer that owns the response.
    */
   initialCookies?: InitialCookies;
   /**
    * Lifetime in seconds. Defaults to 30 days. Pass `undefined`
-   * (the default) for "until the session ends" — but note that
+   * (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.
    */
@@ -819,7 +892,7 @@ type CookieDriverOptions = {
    */
   path?: string;
   /**
-   * `SameSite` attribute. Defaults to `"lax"` — restrictive enough
+   * `SameSite` attribute. Defaults to `"lax"`; restrictive enough
    * to avoid CSRF on cross-origin POSTs, permissive enough for
    * top-level navigations.
    */
@@ -831,7 +904,7 @@ type CookieDriverOptions = {
   secure?: boolean;
 };
 /**
- * Cookie-backed storage driver. Reads/writes `document.cookie` —
+ * 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
@@ -845,37 +918,39 @@ type CookieDriverOptions = {
  * **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
+ * 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,
+ * during the SSR pass anyway; writes only fire after client mount,
  * once `document.cookie` is reachable.
  */
 declare const createCookieStorageDriver: (options?: CookieDriverOptions) => StorageDriver;
 //#endregion
 //#region src/storage/wallet-storage.d.ts
 type StorageConfig = {
-  keyPrefix: string; /** Survives app restart. Defaults to localStorage on web. */
-  persistent?: StorageDriver; /** Cleared on session end. Defaults to sessionStorage on web. */
+  keyPrefix: string;
+  /** Survives app restart. Defaults to localStorage on web. */
+  persistent?: StorageDriver;
+  /** Cleared on session end. Defaults to sessionStorage on web. */
   session?: StorageDriver;
 };
 declare class WalletStorage implements WalletPersistence {
-  private poolKey;
-  private selectionKey;
-  private activeKey;
-  private userDisconnectedKey;
-  private persistent;
-  private session;
+  private readonly poolKey;
+  private readonly selectionKey;
+  private readonly activeKey;
+  private readonly userDisconnectedKey;
+  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.
+   * the queue; they observe whatever's currently in the driver.
    */
   private poolMutationQueue;
   constructor(config: StorageConfig);
@@ -886,7 +961,7 @@ declare class WalletStorage implements WalletPersistence {
    * 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
+   * 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
@@ -941,13 +1016,19 @@ declare const createWalletStore: (config: WalletManagerConfig) => import("zustan
 //#region src/wallet-equal.d.ts
 /**
  * Two wallet snapshots are equivalent for selector purposes iff they
- * share connectorId, 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.
+ * 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`),
+ * 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.
  */
 declare const walletEqual: (a: ConnectedWallet | undefined, b: ConnectedWallet | undefined) => boolean;
@@ -960,7 +1041,7 @@ declare const logError: (...args: ReadonlyArray<unknown>) => void;
 /**
  * Normalize a wallet-announced icon string.
  *
- * Wallets announce their icon through external metadata — EIP-6963
+ * 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
@@ -969,7 +1050,7 @@ declare const logError: (...args: ReadonlyArray<unknown>) => void;
  *
  * 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
+ * `undefined`: never a blank or malformed one. `undefined` passes
  * through untouched.
  */
 declare const sanitizeIcon: (icon: string | undefined) => string | undefined;
@@ -991,7 +1072,7 @@ declare const sanitizeIcon: (icon: string | undefined) => string | undefined;
  * - {@link bytesToHexPrefixed} returns `0x`-prefixed hex (EVM, Polkadot).
  * - {@link hexToBytes} tolerantly strips an optional `0x` (all callers).
  */
-/** Bare lowercase hex — no `0x` prefix (Bitcoin, Ledger). */
+/** Bare lowercase hex, no `0x` prefix (Bitcoin, Ledger). */
 declare const bytesToHex: (bytes: Uint8Array) => string;
 /** `0x`-prefixed lowercase hex (EVM, Polkadot). */
 declare const bytesToHexPrefixed: (bytes: Uint8Array) => string;
@@ -1009,5 +1090,5 @@ declare const base64ToBytes: (b64: string) => Uint8Array;
 /** Cross-platform `Uint8Array` → base64. */
 declare const bytesToBase64: (bytes: Uint8Array) => string;
 //#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, type SignerForPlatform, type SignerOf, type SnapshotOptions, type StorageDriver, type StoredPoolEntry, type StoredPoolRecord, type StoredSelectionRecord, type SuiAdapter, type SuiWallet, type SvmAdapter, type SvmWallet, type Wallet, type WalletAdapter, type WalletAvailability, type WalletBase, type WalletCapabilities, type WalletManagerConfig, type WalletPersistence, type WalletSnapshot, type WalletSource, WalletStorage, type WalletStore, type WalletStoreState, base64ToBytes, buildChainsByPlatform, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createWalletSource, createWalletStore, hexToBytes, 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 SignerForPlatform, type SignerOf, type SnapshotOptions, type StorageDriver, type StoredPoolEntry, type StoredPoolRecord, type StoredSelectionRecord, type SuiAdapter, type SuiWallet, type SvmAdapter, type SvmWallet, type Wallet, type WalletAdapter, type WalletAvailability, type WalletBase, type WalletCapabilities, type WalletManagerConfig, type WalletPersistence, type WalletSnapshot, type WalletSource, WalletStorage, type WalletStore, type WalletStoreState, base64ToBytes, buildAccount, buildChainsByPlatform, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createWalletSource, createWalletStore, hexToBytes, isShadowAdapter, logError, logWarn, mapConnectionError, readWalletSnapshot, sanitizeIcon, walletEqual };
 //# sourceMappingURL=index.d.ts.map