@usebutr/core 0.4.1 → 0.5.0

package/dist/index.js

@@ -1,24 +1,25 @@
 import { createStore } from "zustand/vanilla";
+import { z } from "zod";
 
 //#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
+* Use this in apps that target one or two chain platforms; importing
 * only those packages keeps unused chain registries out of the bundle.
 * Apps that want every chain reach for `CHAINS_BY_PLATFORM` from
 * `@usebutr/wallets` instead.
 *
 * @example
-* // EVM-only app — Solana/Sui/Bitcoin tables never enter the bundle
+* // EVM-only app: Solana/Sui/Bitcoin tables never enter the bundle
 * import { EVM_CHAINS_LIST } from "@usebutr/evm";
 * import { buildChainsByPlatform } from "@usebutr/core";
 *
 * const chains = buildChainsByPlatform({ evm: EVM_CHAINS_LIST });
 *
 * @example
-* // Multi-chain app — pull from each package the app actually uses
+* // Multi-chain app: pull from each package the app actually uses
 * import { EVM_CHAINS_LIST } from "@usebutr/evm";
 * import { SVM_CHAINS_LIST } from "@usebutr/svm";
 *
@@ -44,7 +45,7 @@ const buildChainsByPlatform = (partial) => ({
 *  - butr's own `Error("Connection timeout")` (from the 90s connect timeout)
 *  - butr's own `Error("Failed to get account")` (from the connect flow)
 *  - EIP-1193 numeric `code` properties (`4001` → UserRejected,
-*    `-32002` → RequestPending, `4100`/`4900`/`4901` → NotConnected —
+*    `-32002` → RequestPending, `4100`/`4900`/`4901` → NotConnected:
 *    unauthorized / disconnected from all-or-one chains)
 *  - common message substrings: "user rejected" / "user denied",
 *    "locked", "chain", etc.
@@ -62,7 +63,7 @@ const mapConnectionError = (raw) => {
 			kind: "NotConnected",
 			message
 		};
-		const code = raw.code;
+		const code = "code" in raw ? raw.code : void 0;
 		if (code === 4001) return {
 			kind: "UserRejected",
 			message
@@ -120,6 +121,18 @@ const CHAIN_PLATFORMS = [
 	"bitcoin",
 	"polkadot"
 ];
+/**
+* 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).
+*/
+const buildAccount = (address, chain) => ({
+	chain,
+	id: `${chain.id}:${address}`,
+	walletAddress: address
+});
 
 //#endregion
 //#region src/wallet-source.ts
@@ -132,6 +145,134 @@ const CHAIN_PLATFORMS = [
 */
 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`.
+*/
+var ShadowConnectorError = class extends Error {
+	code = "BUTR_RECONNECTING";
+	connectorId;
+	method;
+	constructor(method, connectorId) {
+		super(`[butr] ${method} called on shadow connector "${connectorId}". Wait for silent reconnect to complete (check reconnectingIds.has(id) before calling).`);
+		this.name = "ShadowConnectorError";
+		this.connectorId = connectorId;
+		this.method = method;
+	}
+};
+const ALL_FALSE_CAPABILITIES = Object.freeze({
+	getBalance: false,
+	getTransactionReceipt: false,
+	requestAccounts: false,
+	sendTransaction: false,
+	signIn: false,
+	signMessage: false,
+	signTransaction: false,
+	subscribe: false,
+	switchAccount: false,
+	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.
+*/
+const createShadowAdapter = (entry) => {
+	const id = entry.connectorId;
+	const name = entry.name;
+	const icon = entry.icon;
+	const reject = (method) => Promise.reject(new ShadowConnectorError(method, id));
+	const base = {
+		capabilities: ALL_FALSE_CAPABILITIES,
+		connect: () => reject("connect"),
+		disconnect: () => reject("disconnect"),
+		getAccount: () => reject("getAccount"),
+		getBalance: () => reject("getBalance"),
+		getSigner: () => reject("getSigner"),
+		getTransactionReceipt: () => reject("getTransactionReceipt"),
+		icon,
+		id,
+		name,
+		sendTx: () => reject("sendTx"),
+		sendTxToChain: () => reject("sendTxToChain"),
+		signMessage: () => reject("signMessage"),
+		switchChain: () => reject("switchChain")
+	};
+	switch (entry.chainPlatform) {
+		case "bitcoin": return {
+			...base,
+			chainPlatform: "bitcoin"
+		};
+		case "evm": return {
+			...base,
+			chainPlatform: "evm"
+		};
+		case "sui": return {
+			...base,
+			chainPlatform: "sui"
+		};
+		case "svm": return {
+			...base,
+			chainPlatform: "svm"
+		};
+		case "polkadot": return {
+			...base,
+			chainPlatform: "polkadot"
+		};
+		default:
+			entry.chainPlatform;
+			throw new Error(`[butr] unknown chainPlatform: ${entry.chainPlatform}`);
+	}
+};
+/**
+* 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).
+*/
+const isShadowAdapter = (adapter) => {
+	return Object.values(adapter.capabilities).every((flag) => !flag);
+};
+
 //#endregion
 //#region src/logger.ts
 const logWarn = (...args) => {
@@ -166,7 +307,7 @@ const createMemoryStorageDriver = () => {
 };
 const createWebStorageDriver = (kind) => {
 	if (!hasWebStorage(kind)) return createMemoryStorageDriver();
-	const storage = globalThis[kind];
+	const storage = kind === "localStorage" ? globalThis.localStorage : globalThis.sessionStorage;
 	return {
 		getItem(key) {
 			try {
@@ -198,41 +339,36 @@ const createBrowserStorageDriver = () => ({
 });
 
 //#endregion
-//#region src/storage/wallet-storage.ts
-const VALID_CHAIN_PLATFORMS$1 = new Set(CHAIN_PLATFORMS);
-const isValidAccount$1 = (value) => {
-	if (!value || typeof value !== "object") return false;
-	const account = value;
-	if (typeof account.walletAddress !== "string" || typeof account.id !== "string") return false;
-	if (!account.chain || typeof account.chain !== "object") return false;
-	return true;
-};
-/**
-* Structural validator for a serialized pool entry.
-*
-* Used in two directions:
-*  - On read (`getPool`): malformed entries from storage are warned
-*    and dropped — legacy / cross-tab corruption shouldn't crash the
-*    consumer.
-*  - On write (`setPool`): the runtime's reducer state is the source
-*    of truth, and a malformed write would indicate a programming
-*    error inside butr. Throw rather than silently corrupt storage.
-*
-* Same validator either way — keeping the two paths symmetric means
-* "what's storable" is a single fact.
-*/
-const isValidPoolEntry$1 = (key, value) => {
-	if (!value || typeof value !== "object") return false;
-	const entry = value;
-	if (typeof entry.connectorId !== "string" || entry.connectorId !== key) return false;
-	if (typeof entry.chainPlatform !== "string") return false;
-	if (!VALID_CHAIN_PLATFORMS$1.has(entry.chainPlatform)) return false;
-	if (typeof entry.name !== "string" || entry.name.length === 0) return false;
-	if (entry.icon !== void 0 && typeof entry.icon !== "string") return false;
-	if (!isValidAccount$1(entry.account)) return false;
-	if (!Array.isArray(entry.accounts) || !entry.accounts.every(isValidAccount$1)) return false;
-	return true;
+//#region src/storage/validation.ts
+const chainPlatformSchema = z.enum(CHAIN_PLATFORMS);
+const chainSchema = z.looseObject({
+	id: z.string(),
+	name: z.string(),
+	namespace: z.string(),
+	reference: z.string()
+});
+const accountSchema = z.looseObject({
+	chain: chainSchema,
+	id: z.string(),
+	walletAddress: z.string()
+});
+const storedPoolEntrySchema = z.looseObject({
+	account: accountSchema,
+	accounts: z.array(accountSchema),
+	chainPlatform: chainPlatformSchema,
+	connectorId: z.string(),
+	icon: z.string().optional(),
+	name: z.string().min(1)
+});
+const recordSchema = z.record(z.string(), z.unknown());
+const parseStoredPoolEntry = (key, value) => {
+	const parsed = storedPoolEntrySchema.safeParse(value);
+	if (!parsed.success || parsed.data.connectorId !== key) return null;
+	return parsed.data;
 };
+
+//#endregion
+//#region src/storage/wallet-storage.ts
 var WalletStorage = class {
 	poolKey;
 	selectionKey;
@@ -246,7 +382,7 @@ var WalletStorage = class {
 	* this, two simultaneous `setPool` calls both read the pre-write
 	* state, each merge their own entries, and whichever finishes last
 	* overwrites the other's additions. Reads (`getPool`) don't enter
-	* the queue — they observe whatever's currently in the driver.
+	* the queue; they observe whatever's currently in the driver.
 	*/
 	poolMutationQueue = Promise.resolve();
 	constructor(config) {
@@ -282,15 +418,19 @@ var WalletStorage = class {
 	async getPool() {
 		try {
 			const stored = await this.persistent.getItem(this.poolKey);
-			if (!stored) return {};
-			const parsed = JSON.parse(stored);
-			if (!parsed || typeof parsed !== "object") {
+			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, value] of Object.entries(parsed)) if (isValidPoolEntry$1(key, value)) result[key] = value;
-			else logWarn(`[butr] dropping invalid pool entry for ${key}`);
+			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;
 		} catch (error) {
 			logWarn("[butr] failed to parse pool from storage:", error);
@@ -302,14 +442,14 @@ var WalletStorage = class {
 	* Upsert the in-memory pool into storage. Additive: entries in
 	* `pool` are written; entries already in storage that aren't in
 	* `pool` are kept. The in-memory pool reflects "what's live right
-	* now", not "the complete list of remembered connections" — a
+	* now", not "the complete list of remembered connections"; a
 	* silent reconnect that fails on reload leaves the entry out of
 	* the pool but the saved entry stays so the next load can retry.
 	* Use `removePoolEntry` for explicit eviction (the user clicked
 	* Disconnect) and `clearAll` for a full wipe (reset).
 	*/
-	setPool(pool) {
-		return this.serializePoolMutation(async () => {
+	async setPool(pool) {
+		await this.serializePoolMutation(async () => {
 			try {
 				const serializable = { ...await this.getPool() };
 				for (const [connectorId, wallet] of pool) {
@@ -321,7 +461,7 @@ var WalletStorage = class {
 						icon: wallet.connector.icon,
 						name: wallet.connector.name
 					};
-					if (!isValidPoolEntry$1(connectorId, entry)) throw new Error(`[butr] refusing to persist invalid pool entry for ${connectorId}`);
+					if (parseStoredPoolEntry(connectorId, entry) === null) throw new Error(`[butr] refusing to persist invalid pool entry for ${connectorId}`);
 					serializable[connectorId] = entry;
 				}
 				await this.persistent.setItem(this.poolKey, JSON.stringify(serializable));
@@ -330,8 +470,8 @@ var WalletStorage = class {
 			}
 		});
 	}
-	removePoolEntry(connectorId) {
-		return this.serializePoolMutation(async () => {
+	async removePoolEntry(connectorId) {
+		await this.serializePoolMutation(async () => {
 			try {
 				const stored = await this.getPool();
 				if (stored[connectorId]) {
@@ -343,19 +483,23 @@ var WalletStorage = class {
 			}
 		});
 	}
-	clearPool() {
-		return this.serializePoolMutation(async () => {
+	async clearPool() {
+		await this.serializePoolMutation(async () => {
 			await this.persistent.removeItem(this.poolKey);
 		});
 	}
 	async getSelection() {
 		try {
 			const stored = await this.persistent.getItem(this.selectionKey);
-			if (!stored) return {};
-			const parsed = JSON.parse(stored);
-			if (!parsed || typeof parsed !== "object") return {};
+			if (stored === null || stored === "") return {};
+			const value = JSON.parse(stored);
+			const parsed = recordSchema.safeParse(value);
+			if (!parsed.success) return {};
 			const result = {};
-			for (const [key, value] of Object.entries(parsed)) if (VALID_CHAIN_PLATFORMS$1.has(key) && typeof value === "string" && value.length > 0) result[key] = value;
+			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] failed to parse selection from storage:", error);
@@ -374,7 +518,7 @@ var WalletStorage = class {
 	async getActiveConnectorId() {
 		try {
 			const value = await this.persistent.getItem(this.activeKey);
-			return value && value.length > 0 ? value : null;
+			return value !== null && value.length > 0 ? value : null;
 		} catch {
 			return null;
 		}
@@ -462,6 +606,8 @@ const createConnectorLifecycle = (handlers) => {
 
 //#endregion
 //#region src/store/hydration.ts
+const VALID_CHAIN_PLATFORMS$1 = new Set(CHAIN_PLATFORMS);
+const isChainPlatform$1 = (value) => VALID_CHAIN_PLATFORMS$1.has(value);
 /** Pick the right `accounts` list: fresh from the connector if it
 *  exposes `getAccounts`, otherwise the persisted list, otherwise just
 *  the active account. */
@@ -476,7 +622,7 @@ const resolveHydratedAccounts = async (connector, storedAccounts, fallbackAccoun
 const restoreOneEntry = async (connectorId, entry, connector) => {
 	try {
 		await connector.connect({ silent: true });
-		const accountToUse = await connector.getAccount() || entry.account;
+		const accountToUse = await connector.getAccount() ?? entry.account;
 		return {
 			connectorId,
 			entry: {
@@ -538,13 +684,13 @@ const createHydrationCoordinator = (storage, createConnector) => {
 				});
 			}
 			const selection = /* @__PURE__ */ new Map();
-			for (const [platform, connectorId] of Object.entries(storedSelection)) if (connectorId && pool.has(connectorId)) selection.set(platform, connectorId);
+			for (const [platform, connectorId] of Object.entries(storedSelection)) if (isChainPlatform$1(platform) && connectorId !== void 0 && pool.has(connectorId)) selection.set(platform, connectorId);
 			for (const [connectorId, wallet] of pool) {
 				const platform = wallet.connector.chainPlatform;
 				if (!selection.has(platform)) selection.set(platform, connectorId);
 			}
 			let activeConnectorId = null;
-			if (storedActive && pool.has(storedActive)) activeConnectorId = storedActive;
+			if (storedActive !== null && pool.has(storedActive)) activeConnectorId = storedActive;
 			else if (pool.size > 0) activeConnectorId = pool.keys().next().value ?? null;
 			return {
 				activeConnectorId,
@@ -586,8 +732,8 @@ const reducer = (state, event) => {
 			const selection = new Map(state.selection);
 			for (const [platform, id] of event.selection) selection.set(platform, id);
 			let activeConnectorId = null;
-			if (event.activeConnectorId && pool.has(event.activeConnectorId)) activeConnectorId = event.activeConnectorId;
-			else if (state.activeConnectorId && pool.has(state.activeConnectorId)) activeConnectorId = state.activeConnectorId;
+			if (event.activeConnectorId !== null && pool.has(event.activeConnectorId)) activeConnectorId = event.activeConnectorId;
+			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) {
@@ -655,7 +801,7 @@ const reducer = (state, event) => {
 			if (newSelection.get(platform) === event.connectorId) {
 				newSelection.delete(platform);
 				const fallback = findConnectorForPlatform(newPool, platform);
-				if (fallback) newSelection.set(platform, fallback);
+				if (fallback !== void 0) newSelection.set(platform, fallback);
 			}
 			const firstId = newPool.keys().next();
 			const activeConnectorId = state.activeConnectorId === event.connectorId ? firstId.value ?? null : state.activeConnectorId;
@@ -731,118 +877,6 @@ const reducer = (state, event) => {
 	}
 };
 
-//#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`.
-*/
-var ShadowConnectorError = class extends Error {
-	code = "BUTR_RECONNECTING";
-	connectorId;
-	method;
-	constructor(method, connectorId) {
-		super(`[butr] ${method} called on shadow connector "${connectorId}" — wait for silent reconnect to complete (check reconnectingIds.has(id) before calling).`);
-		this.name = "ShadowConnectorError";
-		this.connectorId = connectorId;
-		this.method = method;
-	}
-};
-const ALL_FALSE_CAPABILITIES = Object.freeze({
-	getBalance: false,
-	getTransactionReceipt: false,
-	requestAccounts: false,
-	sendTransaction: false,
-	signIn: false,
-	signMessage: false,
-	signTransaction: false,
-	subscribe: false,
-	switchAccount: false,
-	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.
-*/
-const createShadowAdapter = (entry) => {
-	const id = entry.connectorId;
-	const name = entry.name;
-	const icon = entry.icon;
-	const reject = (method) => Promise.reject(new ShadowConnectorError(method, id));
-	const base = {
-		capabilities: ALL_FALSE_CAPABILITIES,
-		connect: () => reject("connect"),
-		disconnect: () => reject("disconnect"),
-		getAccount: () => reject("getAccount"),
-		getBalance: () => reject("getBalance"),
-		getSigner: () => reject("getSigner"),
-		getTransactionReceipt: () => reject("getTransactionReceipt"),
-		icon,
-		id,
-		name,
-		sendTx: () => reject("sendTx"),
-		sendTxToChain: () => reject("sendTxToChain"),
-		signMessage: () => reject("signMessage"),
-		switchChain: () => reject("switchChain")
-	};
-	switch (entry.chainPlatform) {
-		case "bitcoin": return {
-			...base,
-			chainPlatform: "bitcoin"
-		};
-		case "evm": return {
-			...base,
-			chainPlatform: "evm"
-		};
-		case "sui": return {
-			...base,
-			chainPlatform: "sui"
-		};
-		case "svm": return {
-			...base,
-			chainPlatform: "svm"
-		};
-		case "polkadot": return {
-			...base,
-			chainPlatform: "polkadot"
-		};
-		default:
-			entry.chainPlatform;
-			throw new Error(`[butr] unknown chainPlatform: ${entry.chainPlatform}`);
-	}
-};
-
 //#endregion
 //#region src/store/wallet-store-helpers.ts
 /** Run an async operation fire-and-forget, calling onError if it throws. */
@@ -856,13 +890,15 @@ const run = async (fn, onError) => {
 
 //#endregion
 //#region src/store/wallet-store.ts
+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
+* synchronously: the consumer's first render sees the persisted
 * state in the live store, not undefined.
 */
 const seedStateFromSnapshot = (snapshot) => {
@@ -879,8 +915,8 @@ const seedStateFromSnapshot = (snapshot) => {
 		reconnectingIds.add(connectorId);
 	}
 	const selection = /* @__PURE__ */ new Map();
-	for (const [platform, connectorId] of Object.entries(snapshot.selection)) if (connectorId && pool.has(connectorId)) selection.set(platform, connectorId);
-	const activeConnectorId = snapshot.activeConnectorId && pool.has(snapshot.activeConnectorId) ? snapshot.activeConnectorId : pool.keys().next().value ?? null;
+	for (const [platform, connectorId] of Object.entries(snapshot.selection)) if (isChainPlatform(platform) && connectorId !== void 0 && pool.has(connectorId)) selection.set(platform, connectorId);
+	const activeConnectorId = snapshot.activeConnectorId !== null && pool.has(snapshot.activeConnectorId) ? snapshot.activeConnectorId : pool.keys().next().value ?? null;
 	return {
 		...initialState,
 		activeConnectorId,
@@ -894,8 +930,8 @@ const CONNECT_TIMEOUT_MS = 9e4;
 const DEFAULT_SLOW_CONNECT_THRESHOLD_MS = 5e3;
 const normaliseAddress = (addr) => addr.toLowerCase();
 const createWalletStore = (config) => {
-	const storageKeyPrefix = config.storageKeyPrefix || "butr";
-	const storage = config.storage || new WalletStorage({ keyPrefix: storageKeyPrefix });
+	const storageKeyPrefix = config.storageKeyPrefix === void 0 || config.storageKeyPrefix === "" ? "butr" : config.storageKeyPrefix;
+	const storage = config.storage ?? new WalletStorage({ keyPrefix: storageKeyPrefix });
 	const reportStorageError = (context) => (error) => {
 		if (config.onStorageError) {
 			try {
@@ -956,7 +992,7 @@ const createWalletStore = (config) => {
 						logWarn("[butr] onSlowConnect threw:", cbError);
 					}
 				}, slowThreshold) : null;
-				let connectTimeoutId = null;
+				let connectTimeoutId;
 				try {
 					const connectPromise = connector.connect();
 					connectPromise.catch(() => {});
@@ -1002,10 +1038,10 @@ const createWalletStore = (config) => {
 					} catch (cbError) {
 						logWarn("[butr] onConnectError threw:", cbError);
 					}
-					onError?.(error);
+					onError?.(error instanceof Error ? error : new Error(String(error)));
 					throw error;
 				} finally {
-					if (connectTimeoutId) clearTimeout(connectTimeoutId);
+					clearTimeout(connectTimeoutId);
 					if (slowTimer) clearTimeout(slowTimer);
 				}
 			},
@@ -1042,7 +1078,9 @@ const createWalletStore = (config) => {
 				});
 				for (const [connectorId, wallet] of result.pool) lifecycle.attach(connectorId, wallet.connector);
 				await Promise.all([persistSelection(), persistActive()]);
-				for (const id of hydration.pendingIds()) run(() => get().tryRestoreFromPending(id), (e) => logWarn(`[butr] late restore rejected for ${id}:`, e));
+				for (const id of hydration.pendingIds()) run(() => get().tryRestoreFromPending(id), (e) => {
+					logWarn(`[butr] late restore rejected for ${id}:`, e);
+				});
 				if (config.onHydrated) try {
 					config.onHydrated({
 						dropped: result.dropped,
@@ -1173,7 +1211,7 @@ const readCookies = () => {
 };
 const buildCookieString = (name, value, options, expired = false) => {
 	const parts = [`${name}=${encode(value)}`, `Path=${options.path ?? "/"}`];
-	if (options.domain) parts.push(`Domain=${options.domain}`);
+	if (options.domain !== void 0 && options.domain !== "") parts.push(`Domain=${options.domain}`);
 	if (expired) parts.push("Max-Age=0");
 	else {
 		const maxAge = options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
@@ -1185,11 +1223,11 @@ const buildCookieString = (name, value, options, expired = false) => {
 };
 const toCookieMap$1 = (input) => {
 	if (!input) return null;
-	if (typeof input[Symbol.iterator] === "function") return new Map(input);
+	if (Symbol.iterator in input) return new Map(input);
 	return new Map(Object.entries(input));
 };
 /**
-* Cookie-backed storage driver. Reads/writes `document.cookie` —
+* Cookie-backed storage driver. Reads/writes `document.cookie`;
 * server-readable, survives reloads, scoped per `domain`/`path`.
 *
 * **When to use this:** SSR apps that need to know who's connected
@@ -1203,13 +1241,13 @@ const toCookieMap$1 = (input) => {
 * **Trade-offs vs `localStorage`:** cookies travel with every
 * request, so they cost bytes on the wire. Keep the storage key
 * prefix short, and prefer this driver for the `persistent` slot
-* only — the `session` slot can stay in `sessionStorage` (which
+* only: the `session` slot can stay in `sessionStorage` (which
 * cookies can't natively model anyway).
 *
 * **Server-side writes are no-ops.** Emitting `Set-Cookie` requires
 * access to the framework's response object, which a storage driver
 * shouldn't reach into. The store doesn't mutate persisted state
-* during the SSR pass anyway — writes only fire after client mount,
+* during the SSR pass anyway; writes only fire after client mount,
 * once `document.cookie` is reachable.
 */
 const createCookieStorageDriver = (options = {}) => {
@@ -1245,14 +1283,13 @@ const createCookieStorageDriver = (options = {}) => {
 
 //#endregion
 //#region src/storage/snapshot.ts
-const VALID_CHAIN_PLATFORMS = new Set(CHAIN_PLATFORMS);
 const EMPTY_SNAPSHOT = Object.freeze({
 	activeConnectorId: null,
 	pool: Object.freeze({}),
 	selection: Object.freeze({})
 });
 const toCookieMap = (input) => {
-	if (typeof input[Symbol.iterator] !== "function") return new Map(Object.entries(input));
+	if (!(Symbol.iterator in input)) return new Map(Object.entries(input));
 	const out = /* @__PURE__ */ new Map();
 	for (const entry of input) {
 		if (Array.isArray(entry)) {
@@ -1260,37 +1297,22 @@ const toCookieMap = (input) => {
 			if (typeof name === "string" && typeof value === "string") out.set(name, value);
 			continue;
 		}
-		if (entry && typeof entry === "object" && "name" in entry && "value" in entry && typeof entry.name === "string" && typeof entry.value === "string") out.set(entry.name, entry.value);
+		if (typeof entry.name === "string" && typeof entry.value === "string") out.set(entry.name, entry.value);
 	}
 	return out;
 };
-const isValidAccount = (value) => {
-	if (!value || typeof value !== "object") return false;
-	const account = value;
-	if (typeof account.walletAddress !== "string" || typeof account.id !== "string") return false;
-	if (!account.chain || typeof account.chain !== "object") return false;
-	return true;
-};
-const isValidPoolEntry = (key, value) => {
-	if (!value || typeof value !== "object") return false;
-	const entry = value;
-	if (typeof entry.connectorId !== "string" || entry.connectorId !== key) return false;
-	if (typeof entry.chainPlatform !== "string") return false;
-	if (!VALID_CHAIN_PLATFORMS.has(entry.chainPlatform)) return false;
-	if (typeof entry.name !== "string" || entry.name.length === 0) return false;
-	if (entry.icon !== void 0 && typeof entry.icon !== "string") return false;
-	if (!isValidAccount(entry.account)) return false;
-	if (!Array.isArray(entry.accounts) || !entry.accounts.every(isValidAccount)) return false;
-	return true;
-};
 const parsePool = (raw) => {
-	if (!raw) return {};
+	if (raw === void 0 || raw === "") return {};
 	try {
-		const parsed = JSON.parse(raw);
-		if (!parsed || typeof parsed !== "object") return {};
+		const value = JSON.parse(raw);
+		const parsed = recordSchema.safeParse(value);
+		if (!parsed.success) return {};
 		const result = {};
-		for (const [key, value] of Object.entries(parsed)) if (isValidPoolEntry(key, value)) result[key] = value;
-		else logWarn(`[butr] readWalletSnapshot: dropping invalid pool entry for ${key}`);
+		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);
@@ -1298,12 +1320,16 @@ const parsePool = (raw) => {
 	}
 };
 const parseSelection = (raw) => {
-	if (!raw) return {};
+	if (raw === void 0 || raw === "") return {};
 	try {
-		const parsed = JSON.parse(raw);
-		if (!parsed || typeof parsed !== "object") return {};
+		const value = JSON.parse(raw);
+		const parsed = recordSchema.safeParse(value);
+		if (!parsed.success) return {};
 		const result = {};
-		for (const [key, value] of Object.entries(parsed)) if (VALID_CHAIN_PLATFORMS.has(key) && typeof value === "string" && value.length > 0) result[key] = value;
+		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);
@@ -1313,7 +1339,7 @@ const parseSelection = (raw) => {
 /**
 * Parse a cookie source into a server-safe `WalletSnapshot`.
 *
-* Pure, sync, no `document`, no React — runnable in any environment
+* Pure, sync, no `document`, no React; runnable in any environment
 * (Server Component, route handler, edge middleware, even client
 * code). Pair with `createCookieStorageDriver({ initialCookies })`
 * and `<WalletManagerProvider initialSnapshot={…} />` to render a
@@ -1324,7 +1350,7 @@ const parseSelection = (raw) => {
 * the wallet, switched accounts, or disconnected in another tab, the
 * client-side hydration will reconcile reality and the live store
 * will diverge from the snapshot. Treat the snapshot as an
-* *optimistic* shell — accurate enough to avoid a paint flicker,
+* *optimistic* shell; accurate enough to avoid a paint flicker,
 * authoritative only after `useIsHydrated()` is true.
 *
 * **Inputs.** Accepts the three shapes Next.js / Express / Hono /
@@ -1334,17 +1360,17 @@ const parseSelection = (raw) => {
 *  - An iterable of `[name, value]` tuples
 *
 * Malformed entries are dropped with a `logWarn` (same policy as
-* `WalletStorage.getPool`) — a cross-tab corruption shouldn't crash
+* `WalletStorage.getPool`); a cross-tab corruption shouldn't crash
 * the server render.
 */
 const readWalletSnapshot = (source, options = {}) => {
-	const keyPrefix = options.keyPrefix || "butr";
+	const keyPrefix = options.keyPrefix === void 0 || options.keyPrefix === "" ? "butr" : 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`);
 	let activeConnectorId = null;
-	if (rawActive && rawActive.length > 0 && pool[rawActive]) activeConnectorId = rawActive;
+	if (rawActive !== void 0 && rawActive.length > 0 && pool[rawActive] !== void 0) activeConnectorId = rawActive;
 	else {
 		const firstKey = Object.keys(pool)[0];
 		if (firstKey) activeConnectorId = firstKey;
@@ -1360,19 +1386,25 @@ const readWalletSnapshot = (source, options = {}) => {
 //#region src/wallet-equal.ts
 /**
 * Two wallet snapshots are equivalent for selector purposes iff they
-* share connectorId, active account address, and active account chain
-* id. Used by `useStoreWithEqualityFn` consumers (active-wallet,
-* selected-wallet, useWalletEntry) to suppress spurious re-renders
-* when the underlying Map churns but the resolved entry hasn't changed.
+* share the same adapter instance, active account address, and active
+* account chain id. Used by `useStoreWithEqualityFn` consumers
+* (active-wallet, selected-wallet, useWalletEntry) to suppress spurious
+* re-renders when the underlying Map churns but the resolved entry
+* hasn't changed.
+*
+* The adapter is compared by reference, not by `connector.id`: hydration
+* replaces a shadow adapter with the live one under an unchanged id and
+* address, so an id comparison reports "equal" and leaves consumers
+* holding a placeholder whose every method throws ShadowConnectorError.
 *
-* Hoisted to its own module so the equivalence rule lives in one place
-* — if we ever extend the snapshot (e.g. to consider `accounts.length`),
+* Hoisted to its own module so the equivalence rule lives in one place;
+* if we ever extend the snapshot (e.g. to consider `accounts.length`),
 * every selector hook picks up the new rule for free.
 */
 const walletEqual = (a, b) => {
 	if (a === b) return true;
 	if (!a || !b) return false;
-	return a.connector.id === b.connector.id && a.account.walletAddress === b.account.walletAddress && a.account.chain.id === b.account.chain.id;
+	return a.connector === b.connector && a.account.walletAddress === b.account.walletAddress && a.account.chain.id === b.account.chain.id;
 };
 
 //#endregion
@@ -1380,7 +1412,7 @@ const walletEqual = (a, b) => {
 /**
 * Normalize a wallet-announced icon string.
 *
-* Wallets announce their icon through external metadata — EIP-6963
+* Wallets announce their icon through external metadata; EIP-6963
 * `providerInfo.icon`, Wallet Standard `wallet.icon`. That value is
 * not under butr's control, and some wallets ship data-URI icons with
 * surrounding whitespace (a newline left over from a pretty-printed
@@ -1389,7 +1421,7 @@ const walletEqual = (a, b) => {
 *
 * Trims surrounding whitespace and treats an all-whitespace (or empty)
 * icon as absent, so consumers get either a usable string or
-* `undefined` — never a blank or malformed one. `undefined` passes
+* `undefined`: never a blank or malformed one. `undefined` passes
 * through untouched.
 */
 const sanitizeIcon = (icon) => {
@@ -1416,7 +1448,7 @@ const sanitizeIcon = (icon) => {
 * - {@link bytesToHexPrefixed} returns `0x`-prefixed hex (EVM, Polkadot).
 * - {@link hexToBytes} tolerantly strips an optional `0x` (all callers).
 */
-/** Bare lowercase hex — no `0x` prefix (Bitcoin, Ledger). */
+/** Bare lowercase hex, no `0x` prefix (Bitcoin, Ledger). */
 const bytesToHex = (bytes) => {
 	let hex = "";
 	for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
@@ -1458,5 +1490,5 @@ const bytesToBase64 = (bytes) => {
 };
 
 //#endregion
-export { CHAIN_PLATFORMS, EMPTY_SNAPSHOT, WalletStorage, base64ToBytes, buildChainsByPlatform, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createWalletSource, createWalletStore, hexToBytes, logError, logWarn, mapConnectionError, readWalletSnapshot, sanitizeIcon, walletEqual };
+export { CHAIN_PLATFORMS, EMPTY_SNAPSHOT, ShadowConnectorError, WalletStorage, base64ToBytes, buildAccount, buildChainsByPlatform, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createWalletSource, createWalletStore, hexToBytes, isShadowAdapter, logError, logWarn, mapConnectionError, readWalletSnapshot, sanitizeIcon, walletEqual };
 //# sourceMappingURL=index.js.map