@usebutr/core 0.5.0 → 1.1.0

package/dist/index.d.ts

@@ -17,172 +17,7 @@ type ChainBase = {
   reference: string;
 };
 //#endregion
-//#region src/storage/persistence.d.ts
-type MaybePromise<T> = T | Promise<T>;
-/** Low-level key/value driver. Sync on web (localStorage, MMKV),
- *  async on React Native (AsyncStorage). */
-type StorageDriver = {
-  getItem: (key: string) => MaybePromise<string | null>;
-  removeItem: (key: string) => MaybePromise<void>;
-  setItem: (key: string, value: string) => MaybePromise<void>;
-};
-type StoredPoolEntry = {
-  account: Account;
-  /** All known accounts on the wallet at last persist. Always contains
-   *  `account`. */
-  accounts: Array<Account>;
-  chainPlatform: ChainPlatform;
-  connectorId: string;
-  /** Wallet icon URL or data-URI captured at persist time. Lets the
-   *  shadow adapter render the same icon the live adapter will when
-   *  the store is seeded from a snapshot. Omitted when the adapter
-   *  itself has no icon. */
-  icon?: string;
-  /** Human-facing wallet name (e.g. "MetaMask") captured at persist
-   *  time. Required so the shadow adapter renders the same identity
-   *  the live adapter will; no "metamask" → "MetaMask" swap at the
-   *  hydration boundary. */
-  name: string;
-};
-type StoredPoolRecord = Partial<Record<string, StoredPoolEntry>>;
-type StoredSelectionRecord = Partial<Record<ChainPlatform, string>>;
-type WalletPersistence = {
-  clearAll: () => Promise<void>;
-  clearPool: () => Promise<void>;
-  getActiveConnectorId: () => Promise<string | null>;
-  getPool: () => Promise<StoredPoolRecord>;
-  getSelection: () => Promise<StoredSelectionRecord>;
-  isUserDisconnected: () => Promise<boolean>;
-  markUserDisconnected: (value: boolean) => Promise<void>;
-  removePoolEntry: (connectorId: string) => Promise<void>;
-  setActiveConnectorId: (connectorId: string | null) => Promise<void>;
-  setPool: (pool: Map<string, ConnectedWallet>) => Promise<void>;
-  setSelection: (selection: Map<ChainPlatform, string>) => Promise<void>;
-};
-//#endregion
-//#region src/storage/snapshot.d.ts
-/**
- * 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.
- */
-type WalletSnapshot = {
-  activeConnectorId: string | null;
-  pool: StoredPoolRecord;
-  selection: StoredSelectionRecord;
-};
-type CookieSource = Iterable<{
-  name: string;
-  value: string;
-}> | Iterable<[string, string]> | Readonly<Record<string, string>>;
-type SnapshotOptions = {
-  /**
-   * Same prefix passed to `WalletManagerProvider` / `WalletStorage`.
-   * Defaults to `"butr"` to match the library default.
-   */
-  keyPrefix?: string;
-};
-declare const EMPTY_SNAPSHOT: WalletSnapshot;
-/**
- * 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.
- */
-declare const readWalletSnapshot: (source: CookieSource, options?: SnapshotOptions) => WalletSnapshot;
-//#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`.
- */
-type ConnectionError = {
-  kind: "UserRejected";
-  message: string;
-} | {
-  kind: "RequestPending";
-  message: string;
-} | {
-  kind: "WalletLocked";
-  message: string;
-} | {
-  actualChain?: string;
-  expectedChain?: string;
-  kind: "ChainMismatch";
-  message: string;
-} | {
-  kind: "NotConnected";
-  message: string;
-} | {
-  kind: "Timeout";
-  message: string;
-} | {
-  cause?: unknown;
-  kind: "Unknown";
-  message: string;
-};
-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.
- */
-declare const mapConnectionError: (raw: unknown) => ConnectionError;
-//#endregion
-//#region src/types/wallet.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).
- */
-declare const CHAIN_PLATFORMS: readonly ["evm", "svm", "sui", "bitcoin", "polkadot"];
-type ChainPlatform = (typeof CHAIN_PLATFORMS)[number];
+//#region src/types/account.d.ts
 type Account = {
   chain: ChainBase;
   id: string;
@@ -206,42 +41,8 @@ type Balance = {
   /** 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
- *   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`.
- */
-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.).
- */
-type ConnectorEvent = {
-  account: Account;
-  accounts: Array<Account>;
-  type: "accountChanged";
-} | {
-  type: "disconnected";
-};
+//#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
@@ -296,6 +97,95 @@ type WalletCapabilities = {
    *  per-call `chain` input) when more than one chain is advertised. */
   switchChain: boolean;
 };
+//#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).
+ */
+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).
+ */
+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,
+ * });
+ */
+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`.
+ */
+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.).
+ */
+type ConnectorEvent = {
+  account: Account;
+  accounts: Array<Account>;
+  type: "accountChanged";
+} | {
+  type: "disconnected";
+};
 /**
  * Orchestration interface: what `butr` actually calls during the
  * connect / disconnect / hydrate flow. This is the contract `butr`
@@ -335,7 +225,15 @@ type Connector<P extends ChainPlatform = ChainPlatform> = {
   /** 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`. */
+   *  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. */
   icon?: string;
   /** Stable key: "metamask", "phantom", etc. Pool entries are keyed by this. */
   id: string;
@@ -358,6 +256,25 @@ type Connector<P extends ChainPlatform = ChainPlatform> = {
    *  themselves. */
   subscribe?: (listener: (event: ConnectorEvent) => void) => () => void;
 };
+type ConnectorMeta = {
+  /** Optional. Sync probe that reports whether the wallet is currently
+   *  available. Defaults to `"installed"` when omitted. Consumers call
+   *  this at render time to gate the "Connect" button. */
+  availability?: () => WalletAvailability;
+  chainPlatform: ChainPlatform;
+  /** Optional image URL or data URI for wallet selection UIs. Unlike
+   *  `Connector.icon`, this one is consumer-supplied and butr does not
+   *  sanitize it; run it through `sanitizeIcon` if the value came from
+   *  wallet metadata rather than your own assets. */
+  icon?: string;
+  id: string;
+  name: string;
+  /** Optional. Where to send users who don't have this wallet (download
+   *  page, app store link, etc.). */
+  url?: string;
+};
+//#endregion
+//#region src/types/wallet.d.ts
 /**
  * Methods every connected wallet supports regardless of chain. The
  * per-platform `Wallet` types extend this with their platform-specific
@@ -475,50 +392,230 @@ 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.
+ * 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".
+ */
+type WalletAdapter = EvmAdapter | SvmAdapter | SuiAdapter | BitcoinAdapter | PolkadotAdapter;
+type ConnectedWallet = {
+  /** 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]`. */
+  accounts: Array<Account>;
+  connector: WalletAdapter;
+};
+//#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.
+ */
+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.
+   */
+  fallback?: {
+    subscribe: (onAdapter: (adapter: WalletAdapter) => void, opts: {
+      hasAnyPrimaryAdapter: () => boolean;
+    }) => () => void;
+  };
+  /** Primary discovery subscription. */
+  subscribe: (onAdapter: (adapter: WalletAdapter) => void) => () => void;
+};
+//#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`.
+ */
+type ConnectionError = {
+  kind: "UserRejected";
+  message: string;
+} | {
+  kind: "RequestPending";
+  message: string;
+} | {
+  kind: "WalletLocked";
+  message: string;
+} | {
+  actualChain?: string;
+  expectedChain?: string;
+  kind: "ChainMismatch";
+  message: string;
+} | {
+  kind: "NotConnected";
+  message: string;
+} | {
+  kind: "Timeout";
+  message: string;
+} | {
+  cause?: unknown;
+  kind: "Unknown";
+  message: string;
+};
+type ConnectionErrorKind = ConnectionError["kind"];
+/**
+ * Normalise a thrown value into a `ConnectionError`.
  *
- * 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".
+ * 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.
  */
-type WalletAdapter = EvmAdapter | SvmAdapter | SuiAdapter | BitcoinAdapter | PolkadotAdapter;
-/** Deprecated. Use one of the per-platform `*Wallet` types or
- *  `WalletBase`. Retained as an alias so existing names resolve. */
-type Wallet = WalletBase;
-type ConnectedWallet = {
-  /** Currently-active account on this wallet. */
+declare const mapConnectionError: (raw: unknown) => ConnectionError;
+//#endregion
+//#region src/storage/persistence.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/** Low-level key/value driver. Sync on web (localStorage, MMKV),
+ *  async on React Native (AsyncStorage). */
+type StorageDriver = {
+  getItem: (key: string) => MaybePromise<string | null>;
+  removeItem: (key: string) => MaybePromise<void>;
+  setItem: (key: string, value: string) => MaybePromise<void>;
+};
+type StoredPoolEntry = {
   account: Account;
-  /** All 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]`. */
+  /** All known accounts on the wallet at last persist. Always contains
+   *  `account`. */
   accounts: Array<Account>;
-  connector: WalletAdapter;
-};
-type ConnectorMeta = {
-  /** Optional. Sync probe that reports whether the wallet is currently
-   *  available. Defaults to `"installed"` when omitted. Consumers call
-   *  this at render time to gate the "Connect" button. */
-  availability?: () => WalletAvailability;
   chainPlatform: ChainPlatform;
-  /** Optional image URL or data URI for wallet selection UIs. */
+  connectorId: string;
+  /** Wallet icon URL or data-URI captured at persist time. Lets the
+   *  shadow adapter render the same icon the live adapter will when
+   *  the store is seeded from a snapshot. Omitted when the adapter
+   *  itself has no icon. */
   icon?: string;
-  id: string;
+  /** Human-facing wallet name (e.g. "MetaMask") captured at persist
+   *  time. Required so the shadow adapter renders the same identity
+   *  the live adapter will; no "metamask" → "MetaMask" swap at the
+   *  hydration boundary. */
   name: string;
-  /** Optional. Where to send users who don't have this wallet (download
-   *  page, app store link, etc.). */
-  url?: string;
 };
+type StoredPoolRecord = Partial<Record<string, StoredPoolEntry>>;
+type StoredSelectionRecord = Partial<Record<ChainPlatform, string>>;
+type WalletPersistence = {
+  clearAll: () => Promise<void>;
+  clearPool: () => Promise<void>;
+  getActiveConnectorId: () => Promise<string | null>;
+  getPool: () => Promise<StoredPoolRecord>;
+  getSelection: () => Promise<StoredSelectionRecord>;
+  isUserDisconnected: () => Promise<boolean>;
+  markUserDisconnected: (value: boolean) => Promise<void>;
+  removePoolEntry: (connectorId: string) => Promise<void>;
+  setActiveConnectorId: (connectorId: string | null) => Promise<void>;
+  setPool: (pool: Map<string, ConnectedWallet>) => Promise<void>;
+  setSelection: (selection: Map<ChainPlatform, string>) => Promise<void>;
+};
+//#endregion
+//#region src/storage/snapshot.d.ts
+/**
+ * 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.
+ */
+type WalletSnapshot = {
+  activeConnectorId: string | null;
+  pool: StoredPoolRecord;
+  selection: StoredSelectionRecord;
+};
+type CookieSource = Iterable<{
+  name: string;
+  value: string;
+}> | Iterable<[string, string]> | Readonly<Record<string, string>>;
+type SnapshotOptions = {
+  /**
+   * Same prefix passed to `WalletManagerProvider` / `WalletStorage`.
+   * Defaults to `"butr"` to match the library default.
+   */
+  keyPrefix?: string;
+};
+declare const EMPTY_SNAPSHOT: WalletSnapshot;
+/**
+ * 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.
+ */
+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:
@@ -616,86 +713,6 @@ type WalletManagerConfig = {
   storageKeyPrefix?: string;
 };
 //#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).
- */
-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,
- * });
- */
-declare const buildChainsByPlatform: (partial: Partial<ChainsByPlatform>) => ChainsByPlatform;
-//#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. 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.
- */
-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.
-   */
-  fallback?: {
-    subscribe: (onAdapter: (adapter: WalletAdapter) => void, opts: {
-      hasAnyPrimaryAdapter: () => boolean;
-    }) => () => void;
-  };
-  /** Stable platform identifier. Used by the aggregator for keying. */
-  platform: ChainPlatform;
-  /** Primary discovery subscription. */
-  subscribe: (onAdapter: (adapter: WalletAdapter) => void) => () => void;
-};
-//#endregion
 //#region src/types/signer.d.ts
 /**
  * Per-platform signer type registry.
@@ -1013,6 +1030,124 @@ type WalletStore = ReturnType<typeof createWalletStore>;
 type WalletStoreState = ExtractState<WalletStore>;
 declare const createWalletStore: (config: WalletManagerConfig) => import("zustand/vanilla").StoreApi<State & RuntimeMembers>;
 //#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.
+ */
+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.
+ */
+type SignInResult = {
+  account: Account;
+  /** The message handed to the wallet. Absent on the SIWS path, where the
+   *  wallet composes the message itself. */
+  message?: string;
+  nonce: string;
+  signature: Uint8Array;
+  /** Base64 of `signature`. */
+  signatureBase64: string;
+  signedMessage: Uint8Array;
+  /** Base64 of `signedMessage`; verify against this. */
+  signedMessageBase64: string;
+  wallet: ConnectedWallet;
+};
+type SignInMessageContext = {
+  account: Account;
+  nonce: string;
+  wallet: ConnectedWallet;
+};
+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.
+   */
+  buildMessage?: (ctx: SignInMessageContext) => string;
+  /** Fetch a single-use nonce from your backend. */
+  getNonce: (ctx: {
+    account: Account;
+    wallet: ConnectedWallet;
+  }) => Promise<string>;
+  /**
+   * Skip the Sign In With Solana path even on wallets that advertise it,
+   * forcing every platform down the same `signMessage` route. Useful when
+   * one backend verifier has to handle every chain identically.
+   */
+  preferSignMessage?: boolean;
+  /** Hand the signed result to your backend. Throw to fail the flow. */
+  verify: (result: SignInResult) => Promise<void>;
+};
+/** Thrown before any wallet interaction when the wallet can't sign at
+ *  all. Distinct from a rejection: nothing was asked of the user, so UI
+ *  should say "this wallet can't sign in" rather than "you declined". */
+declare class SignInUnsupportedError extends Error {
+  readonly connectorId: string;
+  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.
+ */
+declare const createSignInFlow: (options: SignInFlowOptions) => {
+  signIn: (wallet: ConnectedWallet, account?: Account) => Promise<SignInResult>;
+};
+//#endregion
 //#region src/wallet-equal.d.ts
 /**
  * Two wallet snapshots are equivalent for selector purposes iff they
@@ -1052,6 +1187,11 @@ declare const logError: (...args: ReadonlyArray<unknown>) => void;
  * 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.
  */
 declare const sanitizeIcon: (icon: string | undefined) => string | undefined;
 //#endregion
@@ -1089,6 +1229,15 @@ declare const hexToBytes: (hex: string) => Uint8Array;
 declare const base64ToBytes: (b64: string) => Uint8Array;
 /** Cross-platform `Uint8Array` → base64. */
 declare const bytesToBase64: (bytes: Uint8Array) => string;
+/**
+ * `Uint8Array` → base58 (Solana addresses and signatures). Leading zero
+ * bytes are significant in base58 and survive the BigInt round-trip only
+ * because they're re-prefixed as `1`s afterwards.
+ */
+declare const bytesToBase58: (bytes: Uint8Array) => string;
+/** Decode base58 into raw bytes. Throws on characters outside the alphabet
+ *  rather than silently dropping them. */
+declare const base58ToBytes: (input: string) => Uint8Array;
 //#endregion
-export { type Account, type Balance, type BitcoinAdapter, type BitcoinWallet, type BrowserStorageDrivers, CHAIN_PLATFORMS, type ChainBase, type ChainPlatform, type ChainsByPlatform, type ConnectedWallet, type ConnectionError, type ConnectionErrorKind, type ConnectionStatus, type Connector, type ConnectorEvent, type ConnectorMeta, type CookieDriverOptions, type CookieSource, EMPTY_SNAPSHOT, type EvmAdapter, type EvmWallet, type HydrationOutcome, type InitialCookies, type MaybePromise, type PlatformDiscoverer, type PolkadotAdapter, type PolkadotWallet, ShadowConnectorError, type 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 };
+export { type Account, type Balance, type BitcoinAdapter, type BitcoinWallet, type BrowserStorageDrivers, CHAIN_PLATFORMS, type ChainBase, type ChainPlatform, type ChainsByPlatform, type ConnectedWallet, type ConnectionError, type ConnectionErrorKind, type ConnectionStatus, type Connector, type ConnectorEvent, type ConnectorMeta, type CookieDriverOptions, type CookieSource, EMPTY_SNAPSHOT, type EvmAdapter, type EvmWallet, type HydrationOutcome, type InitialCookies, type MaybePromise, type PlatformDiscoverer, type PolkadotAdapter, type PolkadotWallet, ShadowConnectorError, type SignInFlowOptions, type SignInMessageContext, type SignInResult, SignInUnsupportedError, type SignerForPlatform, type SignerOf, type SnapshotOptions, type StorageDriver, type StoredPoolEntry, type StoredPoolRecord, type StoredSelectionRecord, type SuiAdapter, type SuiWallet, type SvmAdapter, type SvmWallet, type WalletAdapter, type WalletAvailability, type WalletBase, type WalletCapabilities, type WalletManagerConfig, type WalletPersistence, type WalletSnapshot, type WalletSource, WalletStorage, type WalletStore, type WalletStoreState, base58ToBytes, base64ToBytes, buildAccount, buildChainsByPlatform, bytesToBase58, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createSignInFlow, createWalletSource, createWalletStore, groupByPlatform, hexToBytes, isShadowAdapter, logError, logWarn, mapConnectionError, readWalletSnapshot, sanitizeIcon, walletEqual };
 //# sourceMappingURL=index.d.ts.map