@usebutr/core 0.4.0 → 0.4.2

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
@@ -166,7 +179,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 +211,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 +254,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 +290,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 +314,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 +333,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 +342,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 +355,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 +390,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 +478,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 +494,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 +556,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 +604,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 +673,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;
@@ -734,12 +752,12 @@ const reducer = (state, event) => {
 //#endregion
 //#region src/store/shadow-adapter.ts
 /**
-* Error thrown when a method is called on a shadow adapter — the
+* 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
+* been verified yet; the silent reconnect happens asynchronously
 * after mount.
 *
 * UI code that gates affordances on `wallet.connector.capabilities.*`
@@ -780,7 +798,7 @@ const ALL_FALSE_CAPABILITIES = Object.freeze({
 * 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
+* (`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.
 *
@@ -856,13 +874,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 +899,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 +914,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 +976,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 +1022,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 +1062,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,
@@ -1141,7 +1163,8 @@ const createWalletStore = (config) => {
 					id: `${newChain.id}:${normaliseAddress(a.walletAddress)}`,
 					walletAddress: a.walletAddress
 				});
-				refreshPoolEntry(connectorId, remapped.some((a) => normaliseAddress(a.walletAddress) === normaliseAddress(account.walletAddress)) ? remapped : [...remapped, account], account);
+				const accounts = remapped.some((a) => normaliseAddress(a.walletAddress) === normaliseAddress(account.walletAddress)) ? remapped : [...remapped, account];
+				refreshPoolEntry(connectorId, accounts, account);
 			}
 		};
 	});
@@ -1172,7 +1195,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;
@@ -1184,11 +1207,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
@@ -1202,13 +1225,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 = {}) => {
@@ -1244,14 +1267,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)) {
@@ -1259,37 +1281,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);
@@ -1297,12 +1304,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);
@@ -1312,7 +1323,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
@@ -1323,7 +1334,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 /
@@ -1333,17 +1344,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;
@@ -1364,8 +1375,8 @@ const readWalletSnapshot = (source, options = {}) => {
 * selected-wallet, useWalletEntry) to suppress spurious re-renders
 * when the underlying Map churns but the resolved entry hasn't changed.
 *
-* 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) => {
@@ -1379,7 +1390,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
@@ -1388,7 +1399,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) => {
@@ -1415,7 +1426,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");
@@ -1457,5 +1468,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, WalletStorage, base64ToBytes, buildAccount, buildChainsByPlatform, bytesToBase64, bytesToHex, bytesToHexPrefixed, createBrowserStorageDriver, createCookieStorageDriver, createMemoryStorageDriver, createWalletSource, createWalletStore, hexToBytes, logError, logWarn, mapConnectionError, readWalletSnapshot, sanitizeIcon, walletEqual };
 //# sourceMappingURL=index.js.map