@usebutr/core 0.4.2 → 1.0.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`
@@ -358,6 +248,22 @@ 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. */
+  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
@@ -458,67 +364,247 @@ 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`.
- */
-type PolkadotWallet = WalletBase;
-/** Per-platform full adapter shapes: `Connector` + the platform's
- *  `Wallet` surface. These are the discriminated-union variants of
- *  `WalletAdapter`. */
-type EvmAdapter = Connector<"evm"> & EvmWallet;
-type SvmAdapter = Connector<"svm"> & SvmWallet;
-type SuiAdapter = Connector<"sui"> & SuiWallet;
-type BitcoinAdapter = Connector<"bitcoin"> & BitcoinWallet;
-type PolkadotAdapter = Connector<"polkadot"> & PolkadotWallet;
-/**
- * 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.
+ * 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`.
+ */
+type PolkadotWallet = WalletBase;
+/** Per-platform full adapter shapes: `Connector` + the platform's
+ *  `Wallet` surface. These are the discriminated-union variants of
+ *  `WalletAdapter`. */
+type EvmAdapter = Connector<"evm"> & EvmWallet;
+type SvmAdapter = Connector<"svm"> & SvmWallet;
+type SuiAdapter = Connector<"sui"> & SuiWallet;
+type BitcoinAdapter = Connector<"bitcoin"> & BitcoinWallet;
+type PolkadotAdapter = Connector<"polkadot"> & PolkadotWallet;
+/**
+ * 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 +702,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.
@@ -805,6 +811,45 @@ type State = {
   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);
+}
+/**
+ * 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). */
@@ -977,10 +1022,16 @@ 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`),
@@ -1044,6 +1095,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, 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, 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 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, createWalletSource, createWalletStore, hexToBytes, isShadowAdapter, logError, logWarn, mapConnectionError, readWalletSnapshot, sanitizeIcon, walletEqual };
 //# sourceMappingURL=index.d.ts.map