@usebutr/core 1.1.0 → 2.0.0

package/dist/index.js

@@ -3,11 +3,9 @@ import { z } from "zod";
 
 //#region src/types/account.ts
 /**
-* Build butr's `Account` shape from a wallet address and a resolved
-* `ChainBase`. The composite id (`<chain>:<address>`) is what the
-* reducer uses to compare accounts across refreshes, so every adapter
-* must build accounts through this helper (or keep the format
-* byte-identical).
+* The reducer compares accounts by the composite `<chain>:<address>`
+* id, so every adapter must build accounts here or reproduce that
+* format byte for byte.
 */
 const buildAccount = (address, chain) => ({
 	chain,
@@ -18,30 +16,9 @@ const buildAccount = (address, chain) => ({
 //#endregion
 //#region src/types/chains-by-platform.ts
 /**
-* Build a fully-populated `ChainsByPlatform` from a partial. Platforms
-* the consumer doesn't specify default to an empty list.
-*
-* Use this in apps that target one or two chain platforms; importing
-* only those packages keeps unused chain registries out of the bundle.
-* Apps that want every chain reach for `CHAINS_BY_PLATFORM` from
-* `@usebutr/wallets` instead.
-*
-* @example
-* // EVM-only app: Solana/Sui/Bitcoin tables never enter the bundle
-* import { EVM_CHAINS_LIST } from "@usebutr/evm";
-* import { buildChainsByPlatform } from "@usebutr/core";
-*
-* const chains = buildChainsByPlatform({ evm: EVM_CHAINS_LIST });
-*
-* @example
-* // Multi-chain app: pull from each package the app actually uses
-* import { EVM_CHAINS_LIST } from "@usebutr/evm";
-* import { SVM_CHAINS_LIST } from "@usebutr/svm";
-*
-* const chains = buildChainsByPlatform({
-*   evm: EVM_CHAINS_LIST,
-*   svm: SVM_CHAINS_LIST,
-* });
+* Naming only the platforms an app targets keeps the other packages'
+* chain registries out of its bundle. Apps that want all of them import
+* `CHAINS_BY_PLATFORM` from `@usebutr/wallets`.
 */
 const buildChainsByPlatform = (partial) => ({
 	bitcoin: partial.bitcoin ?? [],
@@ -54,17 +31,9 @@ const buildChainsByPlatform = (partial) => ({
 //#endregion
 //#region src/types/errors.ts
 /**
-* Normalise a thrown value into a `ConnectionError`.
-*
-* Recognises:
-*  - butr's own `Error("Connection timeout")` (from the 90s connect timeout)
-*  - butr's own `Error("Failed to get account")` (from the connect flow)
-*  - EIP-1193 numeric `code` properties (`4001` → UserRejected,
-*    `-32002` → RequestPending, `4100`/`4900`/`4901` → NotConnected:
-*    unauthorized / disconnected from all-or-one chains)
-*  - common message substrings: "user rejected" / "user denied",
-*    "locked", "chain", etc.
-*  - anything else → `Unknown` with `cause` set to the original value.
+* EIP-1193 codes: `4001` rejected, `-32002` pending, `4100`/`4900`/`4901`
+* unauthorized or disconnected. Message-substring matching is the last
+* resort for SDKs that ship no codes at all.
 */
 const mapConnectionError = (raw) => {
 	if (raw instanceof Error) {
@@ -123,11 +92,9 @@ const mapConnectionError = (raw) => {
 //#endregion
 //#region src/types/platform.ts
 /**
-* Canonical list of supported chain platforms. The single runtime source
-* of truth: `ChainPlatform` is derived from it, and storage validators
-* build their allowlists from it, so the type and the runtime checks can
-* never drift (a missing platform here was why Polkadot connections failed
-* to persist).
+* Single runtime source of truth: `ChainPlatform` and the storage
+* validators' allowlists both derive from it. Omitting a platform here
+* silently stops its connections from persisting.
 */
 const CHAIN_PLATFORMS = [
 	"evm",
@@ -140,32 +107,17 @@ const CHAIN_PLATFORMS = [
 //#endregion
 //#region src/wallet-source.ts
 /**
-* Wrap a bare `subscribe` function (the exact shape of
-* `discoverEvmAdapters` / `discoverSvmAdapters`) into a `WalletSource`,
-* so an EVM-only app can do
-* `createWalletSource(discoverEvmAdapters)` without importing anything
-* protocol-bearing beyond `@usebutr/evm`.
+* Takes the exact shape of `discoverEvmAdapters` and friends, so a
+* single-platform app keeps `@usebutr/wallets` out of its bundle.
 */
 const createWalletSource = (subscribe) => ({ subscribe });
 
 //#endregion
 //#region src/store/shadow-adapter.ts
 /**
-* Error thrown when a method is called on a shadow adapter; the
-* placeholder `WalletAdapter` that the store seeds into the pool when
-* an `initialState` is provided (e.g. from a server-rendered cookie
-* snapshot). Shadow adapters carry the identity and account data of a
-* previously-connected wallet, but the live wallet extension hasn't
-* been verified yet; the silent reconnect happens asynchronously
-* after mount.
-*
-* UI code that gates affordances on `wallet.connector.capabilities.*`
-* never reaches a shadow method (capabilities are all `false`). Code
-* that calls through anyway hits this typed error, which is the
-* correct loud failure: the consumer ignored the capability gate.
-*
-* Consumers wanting to wait out the reconnecting window should branch
-* on whether `connectorId` is in `state.reconnectingIds`.
+* Loud failure for consumers that called a wallet method without gating
+* on `capabilities.*` (all `false` here) or `reconnectingIds`, before
+* silent reconnect swapped in the live adapter.
 */
 var ShadowConnectorError = class extends Error {
 	code = "BUTR_RECONNECTING";
@@ -191,26 +143,9 @@ const ALL_FALSE_CAPABILITIES = Object.freeze({
 	switchChain: false
 });
 /**
-* Builds a placeholder `WalletAdapter` from a persisted pool entry.
-*
-* Used by `createWalletStore` when `WalletManagerConfig.initialState`
-* is provided: each stored entry becomes a `ConnectedWallet` whose
-* `connector` is one of these. The store flips `isHydrated` true
-* synchronously and exposes the data through the usual hooks
-* (`useActiveWallet`, `useConnectedWallets`, …), but the connector
-* can't actually talk to a wallet yet, so its capabilities are all
-* `false` and its methods throw `ShadowConnectorError` if called.
-*
-* The hydration coordinator's silent-reconnect pass upgrades each
-* shadow to a live `WalletAdapter` by calling `createConnector(id)`
-* (which only succeeds once the live adapter has been announced via
-* discovery or registered explicitly) and replacing the pool entry.
-* On success the connector id is removed from `reconnectingIds`; on
-* failure the entry is dropped from the pool and storage.
-*
-* The entry's `name` is required (the storage validator rejects
-* entries without it); `icon` is optional only because some live
-* adapters genuinely have no icon to begin with.
+* Lets `createWalletStore` flip `isHydrated` synchronously from
+* `initialState`; the hydration coordinator later swaps each shadow for
+* a live adapter, or drops the entry from pool and storage.
 */
 const createShadowAdapter = (entry) => {
 	const id = entry.connectorId;
@@ -260,17 +195,9 @@ const createShadowAdapter = (entry) => {
 	}
 };
 /**
-* Type guard. Returns true when an adapter is a placeholder created
-* by `createShadowAdapter`. Useful for the hydration coordinator
-* (which needs to know which pool entries still need upgrading) and
-* for consumers writing wagmi-style "is this connection verified yet"
-* checks without subscribing to `reconnectingIds` directly.
-*
-* Detection is structural: a shadow has all capabilities set to false.
-* Live adapters always advertise at least one capability (every wallet
-* surface includes `getBalance`, `signMessage`, `switchChain` as
-* required methods, and adapter constructors set their flags
-* accordingly).
+* Structural detection: relies on every live adapter advertising at
+* least one capability, since `getBalance`, `signMessage` and
+* `switchChain` are required on all wallet surfaces.
 */
 const isShadowAdapter = (adapter) => {
 	return Object.values(adapter.capabilities).every((flag) => !flag);
@@ -369,6 +296,64 @@ const parseStoredPoolEntry = (key, value) => {
 	if (!parsed.success || parsed.data.connectorId !== key) return null;
 	return parsed.data;
 };
+const DEFAULT_KEY_PREFIX = "butr";
+/**
+* `WalletStorage` writes these and `readWalletSnapshot` reads them from
+* a cookie jar; any divergence desyncs the SSR-seeded render from the
+* client that rehydrates it, the failure ADR 0003 exists to prevent.
+*/
+const storageKeys = (keyPrefix) => {
+	const prefix = keyPrefix === void 0 || keyPrefix === "" ? DEFAULT_KEY_PREFIX : keyPrefix;
+	return {
+		active: `${prefix}-active`,
+		pool: `${prefix}-pool`,
+		selection: `${prefix}-selection`,
+		userDisconnected: `${prefix}-user-disconnected`
+	};
+};
+/**
+* Never repairs or throws: one corrupt entry must not take down a whole
+* session, and `readWalletSnapshot` may run on a server with no cookie
+* jar to write the eviction to.
+*/
+const decodePool = (raw, label = "[butr]") => {
+	if (raw === null || raw === void 0 || raw === "") return {};
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch (error) {
+		logWarn(`${label} failed to parse pool from storage:`, error);
+		return {};
+	}
+	const parsed = recordSchema.safeParse(value);
+	if (!parsed.success) return {};
+	const result = {};
+	for (const [key, entryValue] of Object.entries(parsed.data)) {
+		const entry = parseStoredPoolEntry(key, entryValue);
+		if (entry === null) logWarn(`${label} dropping invalid pool entry for ${key}`);
+		else result[key] = entry;
+	}
+	return result;
+};
+/** Decode a persisted selection payload. Same contract as `decodePool`. */
+const decodeSelection = (raw, label = "[butr]") => {
+	if (raw === null || raw === void 0 || raw === "") return {};
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch (error) {
+		logWarn(`${label} failed to parse selection from storage:`, error);
+		return {};
+	}
+	const parsed = recordSchema.safeParse(value);
+	if (!parsed.success) return {};
+	const result = {};
+	for (const [key, selectionValue] of Object.entries(parsed.data)) {
+		const platform = chainPlatformSchema.safeParse(key);
+		if (platform.success && typeof selectionValue === "string" && selectionValue.length > 0) result[platform.data] = selectionValue;
+	}
+	return result;
+};
 
 //#endregion
 //#region src/storage/wallet-storage.ts
@@ -380,19 +365,17 @@ var WalletStorage = class {
 	persistent;
 	session;
 	/**
-	* Serializes pool-key mutations so concurrent fire-and-forget
-	* writes can't interleave their read-modify-write phases. Without
-	* this, two simultaneous `setPool` calls both read the pre-write
-	* state, each merge their own entries, and whichever finishes last
-	* overwrites the other's additions. Reads (`getPool`) don't enter
-	* the queue; they observe whatever's currently in the driver.
+	* Serializes pool read-modify-writes; without it concurrent `setPool`
+	* calls drop each other's entries. Not reentrant, so a queued mutation
+	* must read via `readPool`: `getPool` re-enters and deadlocks it.
 	*/
 	poolMutationQueue = Promise.resolve();
 	constructor(config) {
-		this.poolKey = `${config.keyPrefix}-pool`;
-		this.selectionKey = `${config.keyPrefix}-selection`;
-		this.activeKey = `${config.keyPrefix}-active`;
-		this.userDisconnectedKey = `${config.keyPrefix}-user-disconnected`;
+		const keys = storageKeys(config.keyPrefix);
+		this.poolKey = keys.pool;
+		this.selectionKey = keys.selection;
+		this.activeKey = keys.active;
+		this.userDisconnectedKey = keys.userDisconnected;
 		if (config.persistent && config.session) {
 			this.persistent = config.persistent;
 			this.session = config.session;
@@ -418,43 +401,48 @@ var WalletStorage = class {
 			resolve();
 		}
 	}
-	async getPool() {
+	/** Read and decode the pool without touching the mutation queue. Safe to
+	*  call from inside a queued mutation, unlike `getPool`. */
+	async readPool() {
+		let stored;
 		try {
-			const stored = await this.persistent.getItem(this.poolKey);
-			if (stored === null || stored === "") return {};
-			const value = JSON.parse(stored);
-			const parsed = recordSchema.safeParse(value);
-			if (!parsed.success) {
-				await this.clearPool();
-				return {};
-			}
-			const result = {};
-			for (const [key, entryValue] of Object.entries(parsed.data)) {
-				const entry = parseStoredPoolEntry(key, entryValue);
-				if (entry === null) logWarn(`[butr] dropping invalid pool entry for ${key}`);
-				else result[key] = entry;
-			}
-			return result;
+			stored = await this.persistent.getItem(this.poolKey);
 		} catch (error) {
-			logWarn("[butr] failed to parse pool from storage:", error);
-			await this.clearPool();
-			return {};
+			logWarn("[butr] failed to read pool from storage:", error);
+			return {
+				corrupt: false,
+				decoded: {}
+			};
 		}
+		if (stored === null || stored === "") return {
+			corrupt: false,
+			decoded: {}
+		};
+		const decoded = decodePool(stored);
+		return {
+			corrupt: Object.keys(decoded).length === 0,
+			decoded
+		};
+	}
+	async getPool() {
+		const { corrupt, decoded } = await this.readPool();
+		if (corrupt) try {
+			await this.persistent.removeItem(this.poolKey);
+		} catch (error) {
+			logWarn("[butr] failed to clear corrupt pool:", error);
+		}
+		return decoded;
 	}
 	/**
-	* Upsert the in-memory pool into storage. Additive: entries in
-	* `pool` are written; entries already in storage that aren't in
-	* `pool` are kept. The in-memory pool reflects "what's live right
-	* now", not "the complete list of remembered connections"; a
-	* silent reconnect that fails on reload leaves the entry out of
-	* the pool but the saved entry stays so the next load can retry.
-	* Use `removePoolEntry` for explicit eviction (the user clicked
-	* Disconnect) and `clearAll` for a full wipe (reset).
+	* Additive on purpose: a failed silent reconnect drops the entry from
+	* the live pool, and it must survive to be retried next load.
+	* Eviction goes through `removePoolEntry` or `clearAll`.
 	*/
 	async setPool(pool) {
 		await this.serializePoolMutation(async () => {
 			try {
-				const serializable = { ...await this.getPool() };
+				const { decoded: existing } = await this.readPool();
+				const serializable = { ...existing };
 				for (const [connectorId, wallet] of pool) {
 					const entry = {
 						account: wallet.account,
@@ -476,7 +464,7 @@ var WalletStorage = class {
 	async removePoolEntry(connectorId) {
 		await this.serializePoolMutation(async () => {
 			try {
-				const stored = await this.getPool();
+				const { decoded: stored } = await this.readPool();
 				if (stored[connectorId]) {
 					const { [connectorId]: _, ...remaining } = stored;
 					await this.persistent.setItem(this.poolKey, JSON.stringify(remaining));
@@ -493,19 +481,9 @@ var WalletStorage = class {
 	}
 	async getSelection() {
 		try {
-			const stored = await this.persistent.getItem(this.selectionKey);
-			if (stored === null || stored === "") return {};
-			const value = JSON.parse(stored);
-			const parsed = recordSchema.safeParse(value);
-			if (!parsed.success) return {};
-			const result = {};
-			for (const [key, selectionValue] of Object.entries(parsed.data)) {
-				const platform = chainPlatformSchema.safeParse(key);
-				if (platform.success && typeof selectionValue === "string" && selectionValue.length > 0) result[platform.data] = selectionValue;
-			}
-			return result;
+			return decodeSelection(await this.persistent.getItem(this.selectionKey));
 		} catch (error) {
-			logWarn("[butr] failed to parse selection from storage:", error);
+			logWarn("[butr] failed to read selection from storage:", error);
 			return {};
 		}
 	}
@@ -541,12 +519,9 @@ var WalletStorage = class {
 		]);
 	}
 	/**
-	* Disconnect-intent tracking.
-	*
-	* Lives in the session driver: survives component remounts (unlike refs)
-	* but clears when the session ends (unlike the persistent driver).
-	* Prevents auto-connect from firing immediately after a manual disconnect,
-	* while still allowing auto-connect on fresh sessions.
+	* Kept in the session driver so it survives remounts (unlike a ref)
+	* yet clears at session end (unlike the persistent driver): a manual
+	* disconnect must suppress auto-connect now, not forever.
 	*/
 	async isUserDisconnected() {
 		try {
@@ -730,6 +705,7 @@ const reducer = (state, event) => {
 		case "HYDRATED": {
 			const pool = new Map(state.pool);
 			for (const [id, entry] of event.pool) pool.set(id, entry);
+			for (const id of event.dropped) pool.delete(id);
 			const selection = new Map(state.selection);
 			for (const [platform, id] of event.selection) selection.set(platform, id);
 			let activeConnectorId = null;
@@ -737,11 +713,18 @@ const reducer = (state, event) => {
 			else if (state.activeConnectorId !== null && pool.has(state.activeConnectorId)) activeConnectorId = state.activeConnectorId;
 			else if (pool.size > 0) activeConnectorId = pool.keys().next().value ?? null;
 			let nextReconnecting = state.reconnectingIds;
-			if (state.reconnectingIds.size > 0 && event.pool.size > 0) {
+			if (state.reconnectingIds.size > 0) {
 				const next = new Set(state.reconnectingIds);
 				for (const id of event.pool.keys()) next.delete(id);
+				for (const id of event.dropped) next.delete(id);
 				if (next.size !== state.reconnectingIds.size) nextReconnecting = next;
 			}
+			const selectionAfterDrop = new Map(selection);
+			for (const [platform, id] of selectionAfterDrop) if (!pool.has(id)) {
+				selectionAfterDrop.delete(platform);
+				const fallback = findConnectorForPlatform(pool, platform);
+				if (fallback !== void 0) selectionAfterDrop.set(platform, fallback);
+			}
 			return {
 				...state,
 				activeConnectorId,
@@ -749,7 +732,7 @@ const reducer = (state, event) => {
 				isUserDisconnected: event.isUserDisconnected,
 				pool,
 				reconnectingIds: nextReconnecting,
-				selection
+				selection: selectionAfterDrop
 			};
 		}
 		case "USER_DISCONNECTED_SET": return {
@@ -770,6 +753,7 @@ const reducer = (state, event) => {
 				...state,
 				activeConnectorId: connectorId,
 				connectingConnectorId: null,
+				connectionError: null,
 				connectionStatus: "success",
 				pool: existing.connector === entry.connector ? state.pool : new Map([...state.pool, [connectorId, entry]]),
 				reconnectingIds: nextReconnecting
@@ -780,18 +764,34 @@ const reducer = (state, event) => {
 				...state,
 				activeConnectorId: connectorId,
 				connectingConnectorId: null,
+				connectionError: null,
 				connectionStatus: "success",
 				pool: newPool,
 				reconnectingIds: nextReconnecting,
 				selection: newSelection
 			};
 		}
-		case "CONNECT_FAILED": return {
-			...state,
-			connectingConnectorId: null,
-			connectionError: event.error,
-			connectionStatus: "error"
-		};
+		case "ENTRY_RESTORED": {
+			const { connectorId, entry } = event;
+			const nextReconnecting = state.reconnectingIds.has(connectorId) ? new Set([...state.reconnectingIds].filter((id) => id !== connectorId)) : state.reconnectingIds;
+			const platform = entry.connector.chainPlatform;
+			const selection = state.selection.has(platform) ? state.selection : new Map([...state.selection, [platform, connectorId]]);
+			return {
+				...state,
+				activeConnectorId: state.activeConnectorId ?? connectorId,
+				pool: new Map([...state.pool, [connectorId, entry]]),
+				reconnectingIds: nextReconnecting,
+				selection
+			};
+		}
+		case "CONNECT_FAILED":
+			if (state.connectingConnectorId !== event.connectorId) return state;
+			return {
+				...state,
+				connectingConnectorId: null,
+				connectionError: event.error,
+				connectionStatus: "error"
+			};
 		case "DISCONNECTED": {
 			const wallet = state.pool.get(event.connectorId);
 			if (!wallet) return state;
@@ -894,13 +894,9 @@ const run = async (fn, onError) => {
 const VALID_CHAIN_PLATFORMS = new Set(CHAIN_PLATFORMS);
 const isChainPlatform = (value) => VALID_CHAIN_PLATFORMS.has(value);
 /**
-* Build a synchronously-populated `State` from `config.initialState`.
-* Each pool entry becomes a `ConnectedWallet` whose `connector` is a
-* shadow adapter; every connector id enters `reconnectingIds` so
-* consumers can branch on "is this connection verified" without
-* waiting for the async silent reconnect. `isHydrated` flips true
-* synchronously: the consumer's first render sees the persisted
-* state in the live store, not undefined.
+* `isHydrated` is true from the first render on this path, so
+* `reconnectingIds` (not `isHydrated`) is the "is this connection
+* verified" signal until silent reconnect lands.
 */
 const seedStateFromSnapshot = (snapshot) => {
 	const pool = /* @__PURE__ */ new Map();
@@ -931,8 +927,7 @@ const CONNECT_TIMEOUT_MS = 9e4;
 const DEFAULT_SLOW_CONNECT_THRESHOLD_MS = 5e3;
 const normaliseAddress = (addr) => addr.toLowerCase();
 const createWalletStore = (config) => {
-	const storageKeyPrefix = config.storageKeyPrefix === void 0 || config.storageKeyPrefix === "" ? "butr" : config.storageKeyPrefix;
-	const storage = config.storage ?? new WalletStorage({ keyPrefix: storageKeyPrefix });
+	const storage = config.storage ?? new WalletStorage({ keyPrefix: config.storageKeyPrefix });
 	const reportStorageError = (context) => (error) => {
 		if (config.onStorageError) {
 			try {
@@ -966,6 +961,8 @@ const createWalletStore = (config) => {
 				refreshPoolEntry(connectorId, [...accounts], active);
 			},
 			onDisconnected: (connectorId, chainPlatform) => {
+				const wallet = get().pool.get(connectorId);
+				if (wallet) run(() => wallet.connector.disconnect?.() ?? Promise.resolve(), logError);
 				dispatch({
 					connectorId,
 					type: "DISCONNECTED"
@@ -1026,6 +1023,7 @@ const createWalletStore = (config) => {
 				} catch (error) {
 					const normalised = mapConnectionError(error);
 					dispatch({
+						connectorId,
 						error: normalised,
 						type: "CONNECT_FAILED"
 					});
@@ -1072,6 +1070,7 @@ const createWalletStore = (config) => {
 				const result = await hydration.hydrate();
 				dispatch({
 					activeConnectorId: result.activeConnectorId,
+					dropped: result.dropped.map((d) => d.connectorId),
 					isUserDisconnected: result.isUserDisconnected,
 					pool: result.pool,
 					selection: result.selection,
@@ -1161,7 +1160,7 @@ const createWalletStore = (config) => {
 				dispatch({
 					connectorId,
 					entry: outcome.entry,
-					type: "CONNECT_SUCCEEDED"
+					type: "ENTRY_RESTORED"
 				});
 				lifecycle.attach(connectorId, outcome.entry.connector);
 				await Promise.all([
@@ -1228,28 +1227,9 @@ const toCookieMap$1 = (input) => {
 	return new Map(Object.entries(input));
 };
 /**
-* Cookie-backed storage driver. Reads/writes `document.cookie`;
-* server-readable, survives reloads, scoped per `domain`/`path`.
-*
-* **When to use this:** SSR apps that need to know who's connected
-* during the server render (so they can stream the connected-wallet
-* UI without a client-side hydration flicker). Pass `initialCookies`
-* from a server-side cookie source (e.g. `cookies()` in Next.js'
-* `next/headers`, or a parsed `req.headers.cookie`) and the same
-* driver will serve those values during the server render and switch
-* to `document.cookie` once it mounts in the browser.
-*
-* **Trade-offs vs `localStorage`:** cookies travel with every
-* request, so they cost bytes on the wire. Keep the storage key
-* prefix short, and prefer this driver for the `persistent` slot
-* only: the `session` slot can stay in `sessionStorage` (which
-* cookies can't natively model anyway).
-*
-* **Server-side writes are no-ops.** Emitting `Set-Cookie` requires
-* access to the framework's response object, which a storage driver
-* shouldn't reach into. The store doesn't mutate persisted state
-* during the SSR pass anyway; writes only fire after client mount,
-* once `document.cookie` is reachable.
+* Server-side writes are no-ops: `Set-Cookie` needs the framework's
+* response object. Cookies ride every request, so use this driver for
+* the `persistent` slot only and leave `session` on `sessionStorage`.
 */
 const createCookieStorageDriver = (options = {}) => {
 	const seeded = toCookieMap$1(options.initialCookies);
@@ -1302,74 +1282,18 @@ const toCookieMap = (input) => {
 	}
 	return out;
 };
-const parsePool = (raw) => {
-	if (raw === void 0 || raw === "") return {};
-	try {
-		const value = JSON.parse(raw);
-		const parsed = recordSchema.safeParse(value);
-		if (!parsed.success) return {};
-		const result = {};
-		for (const [key, entryValue] of Object.entries(parsed.data)) {
-			const entry = parseStoredPoolEntry(key, entryValue);
-			if (entry === null) logWarn(`[butr] readWalletSnapshot: dropping invalid pool entry for ${key}`);
-			else result[key] = entry;
-		}
-		return result;
-	} catch (error) {
-		logWarn("[butr] readWalletSnapshot: failed to parse pool cookie:", error);
-		return {};
-	}
-};
-const parseSelection = (raw) => {
-	if (raw === void 0 || raw === "") return {};
-	try {
-		const value = JSON.parse(raw);
-		const parsed = recordSchema.safeParse(value);
-		if (!parsed.success) return {};
-		const result = {};
-		for (const [key, selectionValue] of Object.entries(parsed.data)) {
-			const platform = chainPlatformSchema.safeParse(key);
-			if (platform.success && typeof selectionValue === "string" && selectionValue.length > 0) result[platform.data] = selectionValue;
-		}
-		return result;
-	} catch (error) {
-		logWarn("[butr] readWalletSnapshot: failed to parse selection cookie:", error);
-		return {};
-	}
-};
+const SNAPSHOT_LABEL = "[butr] readWalletSnapshot:";
 /**
-* Parse a cookie source into a server-safe `WalletSnapshot`.
-*
-* Pure, sync, no `document`, no React; runnable in any environment
-* (Server Component, route handler, edge middleware, even client
-* code). Pair with `createCookieStorageDriver({ initialCookies })`
-* and `<WalletManagerProvider initialSnapshot={…} />` to render a
-* connected shell server-side without a hydration flash.
-*
-* **Stale-snapshot semantics.** The snapshot reflects whatever the
-* browser most recently persisted. If the user has since uninstalled
-* the wallet, switched accounts, or disconnected in another tab, the
-* client-side hydration will reconcile reality and the live store
-* will diverge from the snapshot. Treat the snapshot as an
-* *optimistic* shell; accurate enough to avoid a paint flicker,
-* authoritative only after `useIsHydrated()` is true.
-*
-* **Inputs.** Accepts the three shapes Next.js / Express / Hono /
-* generic-Node cookie code naturally produces:
-*  - A plain object: `{ "butr-pool": "{...}", … }`
-*  - An array of `{ name, value }` (Next.js' `cookies().getAll()`)
-*  - An iterable of `[name, value]` tuples
-*
-* Malformed entries are dropped with a `logWarn` (same policy as
-* `WalletStorage.getPool`); a cross-tab corruption shouldn't crash
-* the server render.
+* Optimistic: only what the browser last persisted, so an uninstall or
+* other-tab disconnect makes it stale. Authoritative once the entry
+* leaves `reconnectingIds`; `isHydrated` is true from render one.
 */
 const readWalletSnapshot = (source, options = {}) => {
-	const keyPrefix = options.keyPrefix === void 0 || options.keyPrefix === "" ? "butr" : options.keyPrefix;
+	const keys = storageKeys(options.keyPrefix);
 	const cookies = toCookieMap(source);
-	const pool = parsePool(cookies.get(`${keyPrefix}-pool`));
-	const selection = parseSelection(cookies.get(`${keyPrefix}-selection`));
-	const rawActive = cookies.get(`${keyPrefix}-active`);
+	const pool = decodePool(cookies.get(keys.pool), SNAPSHOT_LABEL);
+	const selection = decodeSelection(cookies.get(keys.selection), SNAPSHOT_LABEL);
+	const rawActive = cookies.get(keys.active);
 	let activeConnectorId = null;
 	if (rawActive !== void 0 && rawActive.length > 0 && pool[rawActive] !== void 0) activeConnectorId = rawActive;
 	else {
@@ -1386,26 +1310,9 @@ const readWalletSnapshot = (source, options = {}) => {
 //#endregion
 //#region src/group-by-platform.ts
 /**
-* Bucket a flat list into per-platform groups.
-*
-* A multi-chain wallet announces one adapter per platform it speaks, so
-* discovery hands back a flat list where a single brand appears several
-* times. Any app targeting more than one chain has to bucket that list
-* before rendering, and hand-rolled versions drift: butr's own demos
-* carried a copy that reimplemented `CHAIN_PLATFORMS` as a local
-* ordering constant.
-*
-* Keys are inserted in `CHAIN_PLATFORMS` order and platforms with no
-* members are omitted, so the result is directly iterable for rendering
-* (`[...groups]`) as well as addressable for lookup (`groups.get("evm")`)
-* without a further emptiness filter.
-*
-* `getPlatform` exists because the discriminant sits at a different depth
-* depending on the input: a discovered `WalletAdapter` carries
-* `chainPlatform` at the top level, a pool entry nests it under
-* `connector`. React consumers should reach for
-* `useDiscoveredWalletsByPlatform` / `useConnectedWalletsByPlatform`
-* instead, which bind the accessor for them.
+* A multi-chain wallet announces one adapter per platform, so brands
+* repeat in the flat list. Keys follow `CHAIN_PLATFORMS` order and empty
+* platforms are omitted, so `[...groups]` needs no emptiness filter.
 */
 const groupByPlatform = (items, getPlatform) => {
 	const buckets = /* @__PURE__ */ new Map();
@@ -1426,20 +1333,9 @@ const groupByPlatform = (items, getPlatform) => {
 //#endregion
 //#region src/encoding/bytes.ts
 /**
-* Shared byte-encoding helpers for the connector packages.
-*
-* These functions sit directly on the signing/address path of every
-* chain. They used to be hand-reimplemented in ~10 connector files; a
-* single tested module removes the drift surface (a `padStart` omission
-* or base64 variant mismatch corrupts signatures/addresses for one chain
-* only, and the divergence is invisible because the copies look "the
-* same").
-*
-* Hex prefixing diverges across chains, so the module exposes **explicit
-* variants** rather than one function:
-* - {@link bytesToHex} returns bare hex (Bitcoin, Ledger).
-* - {@link bytesToHexPrefixed} returns `0x`-prefixed hex (EVM, Polkadot).
-* - {@link hexToBytes} tolerantly strips an optional `0x` (all callers).
+* Hex prefixing diverges by chain (bare for Bitcoin and Ledger, `0x` for
+* EVM and Polkadot), so the variants stay explicit: these sit on the
+* signing path, where a silent mismatch corrupts one chain's signatures.
 */
 /** Bitcoin/Solana alphabet; omits the visually ambiguous `0`, `O`, `I`, `l`. */
 const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
@@ -1543,30 +1439,9 @@ var SignInUnsupportedError = class extends Error {
 };
 const defaultBuildMessage = ({ account, nonce }) => `${account.walletAddress} signs in.\nNonce: ${nonce}`;
 /**
-* Build a reusable sign-in flow: nonce, capability gate, signature,
-* encoding, verification.
-*
-* Every wallet-auth app writes this same sequence, and the parts that
-* are easy to get wrong are the ones that aren't about the app: which
-* capability flag gates the attempt, whether a Solana wallet should take
-* the SIWS path instead, and which bytes to base64 for the server (the
-* wallet's `signedMessage`, not the input). This owns those; you own the
-* nonce endpoint, the message format, and the verifier.
-*
-* ```ts
-* const { signIn } = createSignInFlow({
-*   getNonce: () => fetch("/api/nonce").then((r) => r.text()),
-*   verify: (result) =>
-*     fetch("/api/verify", { body: JSON.stringify(result), method: "POST" }).then(() => {}),
-* });
-*
-* await signIn(wallet);
-* ```
-*
-* Solana wallets advertising `solana:signIn` take the SIWS path
-* automatically, so `result.signedMessage` holds the wallet-composed
-* SIWS statement and `result.message` is absent. Set
-* `preferSignMessage` to opt out.
+* Solana wallets advertising `solana:signIn` take the SIWS path, so
+* `result.signedMessage` holds the wallet-composed statement and
+* `result.message` is absent. `preferSignMessage` opts out.
 */
 const createSignInFlow = (options) => {
 	const buildMessage = options.buildMessage ?? defaultBuildMessage;
@@ -1617,21 +1492,9 @@ const createSignInFlow = (options) => {
 //#endregion
 //#region src/wallet-equal.ts
 /**
-* Two wallet snapshots are equivalent for selector purposes iff they
-* share the same adapter instance, active account address, and active
-* account chain id. Used by `useStoreWithEqualityFn` consumers
-* (active-wallet, selected-wallet, useWalletEntry) to suppress spurious
-* re-renders when the underlying Map churns but the resolved entry
-* hasn't changed.
-*
-* The adapter is compared by reference, not by `connector.id`: hydration
-* replaces a shadow adapter with the live one under an unchanged id and
-* address, so an id comparison reports "equal" and leaves consumers
-* holding a placeholder whose every method throws ShadowConnectorError.
-*
-* Hoisted to its own module so the equivalence rule lives in one place;
-* if we ever extend the snapshot (e.g. to consider `accounts.length`),
-* every selector hook picks up the new rule for free.
+* The adapter is compared by reference, not `connector.id`: hydration
+* swaps a shadow adapter for the live one under an unchanged id, and an
+* id check would strand consumers on the throwing placeholder.
 */
 const walletEqual = (a, b) => {
 	if (a === b) return true;
@@ -1642,24 +1505,9 @@ const walletEqual = (a, b) => {
 //#endregion
 //#region src/sanitize-icon.ts
 /**
-* Normalize a wallet-announced icon string.
-*
-* Wallets announce their icon through external metadata; EIP-6963
-* `providerInfo.icon`, Wallet Standard `wallet.icon`. That value is
-* not under butr's control, and some wallets ship data-URI icons with
-* surrounding whitespace (a newline left over from a pretty-printed
-* manifest). Strict consumers reject it: Next.js's `<Image>` throws
-* because `src` must not start with a control character.
-*
-* Trims surrounding whitespace and treats an all-whitespace (or empty)
-* icon as absent, so consumers get either a usable string or
-* `undefined`: never a blank or malformed one. `undefined` passes
-* through untouched.
-*
-* **Discovery already applies this.** Every adapter butr discovers has
-* had its icon sanitized at construction, so `Connector.icon` is safe to
-* render as-is. Reach for this helper only when building adapter or
-* `ConnectorMeta` metadata yourself from a source butr didn't produce.
+* Some wallets announce data-URI icons wrapped in whitespace, which
+* makes Next.js `<Image>` throw on a leading control character.
+* Discovery already applies this; only hand-built metadata needs it.
 */
 const sanitizeIcon = (icon) => {
 	if (icon === void 0) return;