@openzeppelin/ui-utils 1.0.0

package/dist/index.cjs

@@ -0,0 +1,2167 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let clsx = require("clsx");
+let tailwind_merge = require("tailwind-merge");
+let uuid = require("uuid");
+let validator = require("validator");
+validator = __toESM(validator);
+
+//#region src/contractInputs.ts
+/**
+* Returns names of adapter-declared required inputs that are missing/empty in values.
+*/
+function getMissingRequiredContractInputs(adapter, values) {
+	try {
+		const required = (adapter.getContractDefinitionInputs ? adapter.getContractDefinitionInputs() : []).filter((field) => {
+			return field?.validation?.required === true;
+		});
+		const missing = [];
+		for (const field of required) {
+			const key = field.name || field.id || "";
+			const raw = values[key];
+			if (raw == null) {
+				missing.push(key);
+				continue;
+			}
+			if (typeof raw === "string" && raw.trim().length === 0) missing.push(key);
+		}
+		return missing;
+	} catch {
+		return [];
+	}
+}
+/**
+* True if any adapter-declared required inputs are missing/empty.
+*/
+function hasMissingRequiredContractInputs(adapter, values) {
+	if (!adapter) return false;
+	return getMissingRequiredContractInputs(adapter, values).length > 0;
+}
+
+//#endregion
+//#region src/requiredInputs.ts
+function normalizeSnapshotValue(value) {
+	if (value instanceof File) return {
+		name: value.name,
+		size: value.size,
+		lastModified: value.lastModified
+	};
+	if (typeof value === "string") return value.trim();
+	if (value === void 0) return null;
+	return value;
+}
+function extractRequiredFields(adapter) {
+	if (!adapter || typeof adapter.getContractDefinitionInputs !== "function") return [];
+	try {
+		return (adapter.getContractDefinitionInputs() || []).filter((field) => field.validation?.required);
+	} catch {
+		return [];
+	}
+}
+/**
+* Builds a snapshot of required form input values.
+* @param adapter - Contract adapter to get field definitions from
+* @param formValues - Current form values
+* @returns Snapshot of required field values, or null if no required fields
+*/
+function buildRequiredInputSnapshot(adapter, formValues) {
+	if (!formValues) return null;
+	const requiredFields = extractRequiredFields(adapter);
+	if (requiredFields.length === 0) return null;
+	const snapshot = {};
+	const values = formValues;
+	for (const field of requiredFields) {
+		const key = field.name || field.id;
+		if (!key) continue;
+		snapshot[key] = normalizeSnapshotValue(values[key]);
+	}
+	return Object.keys(snapshot).length > 0 ? snapshot : null;
+}
+/**
+* Compares two required input snapshots for equality.
+* @param a - First snapshot to compare
+* @param b - Second snapshot to compare
+* @returns True if snapshots are equal, false otherwise
+*/
+function requiredSnapshotsEqual(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	const keysA = Object.keys(a).sort();
+	const keysB = Object.keys(b).sort();
+	if (keysA.length !== keysB.length) return false;
+	for (let i = 0; i < keysA.length; i += 1) {
+		if (keysA[i] !== keysB[i]) return false;
+		const valueA = a[keysA[i]];
+		const valueB = b[keysA[i]];
+		if (typeof valueA === "object" && valueA !== null && typeof valueB === "object" && valueB !== null) {
+			if (JSON.stringify(valueA) !== JSON.stringify(valueB)) return false;
+		} else if (valueA !== valueB) return false;
+	}
+	return true;
+}
+
+//#endregion
+//#region src/addressNormalization.ts
+/**
+* Normalizes a contract address by trimming whitespace and converting to lowercase.
+* This is useful for case-insensitive and whitespace-insensitive address comparison.
+*
+* @param address - The address to normalize (string, null, or undefined)
+* @returns The normalized address string, or empty string if input is falsy
+*
+* @example
+* ```ts
+* normalizeAddress('  0xABC123  ') // Returns '0xabc123'
+* normalizeAddress('0xDEF456') // Returns '0xdef456'
+* normalizeAddress(null) // Returns ''
+* normalizeAddress(undefined) // Returns ''
+* ```
+*/
+function normalizeAddress(address) {
+	if (typeof address === "string") return address.trim().toLowerCase();
+	return "";
+}
+/**
+* Compares two addresses after normalization.
+* Returns true if both addresses normalize to the same value.
+*
+* @param address1 - First address to compare
+* @param address2 - Second address to compare
+* @returns True if addresses are equal after normalization
+*
+* @example
+* ```ts
+* addressesEqual('  0xABC  ', '0xabc') // Returns true
+* addressesEqual('0xDEF', '0xABC') // Returns false
+* addressesEqual(null, '') // Returns true
+* ```
+*/
+function addressesEqual(address1, address2) {
+	return normalizeAddress(address1) === normalizeAddress(address2);
+}
+
+//#endregion
+//#region src/logger.ts
+var Logger = class Logger {
+	static instance;
+	options = {
+		enabled: getDefaultLoggerEnabled(),
+		level: "debug"
+	};
+	constructor() {}
+	static getInstance() {
+		if (!Logger.instance) Logger.instance = new Logger();
+		return Logger.instance;
+	}
+	configure(options) {
+		this.options = {
+			...this.options,
+			...options
+		};
+	}
+	shouldLog(level) {
+		if (!this.options.enabled) return false;
+		const levels = [
+			"debug",
+			"info",
+			"warn",
+			"error"
+		];
+		const configuredLevelIndex = levels.indexOf(this.options.level);
+		return levels.indexOf(level) >= configuredLevelIndex;
+	}
+	formatMessage(level, system, message) {
+		return `[${level.toUpperCase()}][${system}] ${message}`;
+	}
+	debug(system, message, ...args) {
+		if (this.shouldLog("debug")) console.log(this.formatMessage("debug", system, message), ...args);
+	}
+	info(system, message, ...args) {
+		if (this.shouldLog("info")) console.log(this.formatMessage("info", system, message), ...args);
+	}
+	warn(system, message, ...args) {
+		if (this.shouldLog("warn")) console.warn(this.formatMessage("warn", system, message), ...args);
+	}
+	error(system, message, ...args) {
+		if (this.shouldLog("error")) console.error(this.formatMessage("error", system, message), ...args);
+	}
+};
+const logger = Logger.getInstance();
+/**
+* Determine whether logging should be enabled by default.
+*
+* - In Vite/browser contexts, use `import.meta.env.DEV`.
+* - In Node/tsup contexts, use `process.env.NODE_ENV`.
+*
+* Defaults to disabled outside development to avoid runtime overhead and noise.
+*/
+function getDefaultLoggerEnabled() {
+	try {
+		const viteEnv = {}.env;
+		if (viteEnv) {
+			const exportEnv = String(viteEnv.VITE_EXPORT_ENV || "").toLowerCase();
+			if (exportEnv === "staging" || exportEnv === "production") return false;
+			if (typeof viteEnv.DEV === "boolean") return viteEnv.DEV;
+		}
+	} catch {}
+	if (typeof process !== "undefined" && typeof process.env !== "undefined") {
+		const exportEnv = String(process.env.VITE_EXPORT_ENV || "").toLowerCase();
+		if (exportEnv === "staging" || exportEnv === "production") return false;
+		const nodeEnv = process.env.NODE_ENV;
+		return nodeEnv === "development" || nodeEnv === "test";
+	}
+	return false;
+}
+
+//#endregion
+//#region src/AppConfigService.ts
+const VITE_ENV_PREFIX = "VITE_APP_CFG_";
+const LOG_SYSTEM = "AppConfigService";
+/**
+* AppConfigService
+*
+* Responsible for loading, merging, and providing access to the application's
+* runtime configuration (`AppRuntimeConfig`).
+*/
+var AppConfigService = class {
+	config;
+	isInitialized = false;
+	/**
+	* Creates a new AppConfigService with default configuration.
+	*/
+	constructor() {
+		this.config = {
+			networkServiceConfigs: {},
+			globalServiceConfigs: {},
+			rpcEndpoints: {},
+			indexerEndpoints: {},
+			featureFlags: {},
+			defaultLanguage: "en"
+		};
+		logger.info(LOG_SYSTEM, "Service initialized with default configuration.");
+	}
+	loadFromViteEnvironment(envSource) {
+		logger.debug(LOG_SYSTEM, "BEGIN loadFromViteEnvironment. envSource received:", envSource ? JSON.stringify(envSource) : "undefined");
+		if (typeof envSource === "undefined") {
+			logger.warn(LOG_SYSTEM, "Vite environment object (envSource) was undefined. Skipping Vite env load.");
+			return;
+		}
+		const env = envSource;
+		const loadedNetworkServiceConfigs = {};
+		const loadedGlobalServiceConfigs = {};
+		const loadedRpcEndpoints = {};
+		const loadedIndexerEndpoints = {};
+		const loadedFeatureFlags = {};
+		for (const key in env) if (Object.prototype.hasOwnProperty.call(env, key) && env[key] !== void 0) {
+			const value = String(env[key]);
+			if (key.startsWith(`${VITE_ENV_PREFIX}API_KEY_`)) {
+				const serviceIdentifier = key.substring(`${VITE_ENV_PREFIX}API_KEY_`.length).toLowerCase().replace(/_/g, "-");
+				if (!loadedNetworkServiceConfigs[serviceIdentifier]) loadedNetworkServiceConfigs[serviceIdentifier] = {};
+				loadedNetworkServiceConfigs[serviceIdentifier].apiKey = value;
+			} else if (key.startsWith(`${VITE_ENV_PREFIX}SERVICE_`)) {
+				const fullSuffix = key.substring(`${VITE_ENV_PREFIX}SERVICE_`.length);
+				const firstUnderscoreIndex = fullSuffix.indexOf("_");
+				if (firstUnderscoreIndex > 0 && firstUnderscoreIndex < fullSuffix.length - 1) {
+					const serviceName = fullSuffix.substring(0, firstUnderscoreIndex).toLowerCase();
+					const paramName = fullSuffix.substring(firstUnderscoreIndex + 1).toLowerCase().replace(/_([a-z])/g, (g) => g[1].toUpperCase());
+					if (serviceName && paramName) {
+						if (!loadedGlobalServiceConfigs[serviceName]) loadedGlobalServiceConfigs[serviceName] = {};
+						loadedGlobalServiceConfigs[serviceName][paramName] = value;
+						logger.debug(LOG_SYSTEM, `Parsed service: '${serviceName}', param: '${paramName}', value: '${value}' from key: ${key}`);
+					} else logger.warn(LOG_SYSTEM, `Could not effectively parse service/param from key: ${key}`);
+				} else logger.warn(LOG_SYSTEM, `Could not determine service and param from key (missing underscore separator): ${key}`);
+			} else if (key === `${VITE_ENV_PREFIX}WALLETCONNECT_PROJECT_ID`) {
+				if (!loadedGlobalServiceConfigs.walletconnect) loadedGlobalServiceConfigs.walletconnect = {};
+				loadedGlobalServiceConfigs.walletconnect.projectId = value;
+				logger.debug(LOG_SYSTEM, `Parsed WalletConnect Project ID directly from key: ${key}, value: ${value}`);
+			} else if (key.startsWith(`${VITE_ENV_PREFIX}RPC_ENDPOINT_`)) {
+				const networkId = key.substring(`${VITE_ENV_PREFIX}RPC_ENDPOINT_`.length).toLowerCase().replace(/_/g, "-");
+				if (networkId) {
+					loadedRpcEndpoints[networkId] = value;
+					logger.debug(LOG_SYSTEM, `Loaded RPC override for ${networkId}: ${value}`);
+				}
+			} else if (key.startsWith(`${VITE_ENV_PREFIX}INDEXER_ENDPOINT_`)) {
+				const networkId = key.substring(`${VITE_ENV_PREFIX}INDEXER_ENDPOINT_`.length).toLowerCase().replace(/_/g, "-");
+				if (networkId) {
+					loadedIndexerEndpoints[networkId] = value;
+					logger.debug(LOG_SYSTEM, `Loaded indexer endpoint for ${networkId}: ${value}`);
+				}
+			} else if (key.startsWith(`${VITE_ENV_PREFIX}FEATURE_FLAG_`)) {
+				const flagName = key.substring(`${VITE_ENV_PREFIX}FEATURE_FLAG_`.length).toLowerCase();
+				loadedFeatureFlags[flagName] = value.toLowerCase() === "true";
+			} else if (key === `${VITE_ENV_PREFIX}DEFAULT_LANGUAGE`) this.config.defaultLanguage = value;
+		}
+		this.config.networkServiceConfigs = {
+			...this.config.networkServiceConfigs,
+			...loadedNetworkServiceConfigs
+		};
+		if (Object.keys(loadedGlobalServiceConfigs).length > 0) {
+			if (!this.config.globalServiceConfigs) this.config.globalServiceConfigs = {};
+			for (const serviceKeyInLoaded in loadedGlobalServiceConfigs) if (Object.prototype.hasOwnProperty.call(loadedGlobalServiceConfigs, serviceKeyInLoaded)) this.config.globalServiceConfigs[serviceKeyInLoaded] = {
+				...this.config.globalServiceConfigs[serviceKeyInLoaded] || {},
+				...loadedGlobalServiceConfigs[serviceKeyInLoaded]
+			};
+		}
+		if (Object.keys(loadedRpcEndpoints).length > 0) {
+			if (!this.config.rpcEndpoints) this.config.rpcEndpoints = {};
+			for (const networkKey in loadedRpcEndpoints) if (Object.prototype.hasOwnProperty.call(loadedRpcEndpoints, networkKey)) this.config.rpcEndpoints[networkKey] = loadedRpcEndpoints[networkKey];
+		}
+		if (Object.keys(loadedIndexerEndpoints).length > 0) {
+			if (!this.config.indexerEndpoints) this.config.indexerEndpoints = {};
+			for (const networkKey in loadedIndexerEndpoints) if (Object.prototype.hasOwnProperty.call(loadedIndexerEndpoints, networkKey)) this.config.indexerEndpoints[networkKey] = loadedIndexerEndpoints[networkKey];
+		}
+		this.config.featureFlags = {
+			...this.config.featureFlags,
+			...loadedFeatureFlags
+		};
+		logger.info(LOG_SYSTEM, "Resolved globalServiceConfigs after Vite env processing:", this.config.globalServiceConfigs ? JSON.stringify(this.config.globalServiceConfigs) : "undefined");
+		logger.info(LOG_SYSTEM, "Resolved rpcEndpoints after Vite env processing:", this.config.rpcEndpoints ? JSON.stringify(this.config.rpcEndpoints) : "undefined");
+		logger.info(LOG_SYSTEM, "Configuration loaded/merged from provided Vite environment variables.");
+	}
+	async loadFromJson(filePath = "/app.config.json") {
+		try {
+			const response = await fetch(filePath);
+			if (!response.ok) {
+				if (response.status === 404) logger.info(LOG_SYSTEM, `Optional configuration file not found at ${filePath}. Skipping.`);
+				else logger.warn(LOG_SYSTEM, `Failed to fetch config from ${filePath}: ${response.status} ${response.statusText}`);
+				return;
+			}
+			const externalConfig = await response.json();
+			if (externalConfig.networkServiceConfigs) {
+				if (!this.config.networkServiceConfigs) this.config.networkServiceConfigs = {};
+				for (const key in externalConfig.networkServiceConfigs) if (Object.prototype.hasOwnProperty.call(externalConfig.networkServiceConfigs, key)) this.config.networkServiceConfigs[key] = {
+					...this.config.networkServiceConfigs[key] || {},
+					...externalConfig.networkServiceConfigs[key]
+				};
+			}
+			if (externalConfig.globalServiceConfigs) {
+				if (!this.config.globalServiceConfigs) this.config.globalServiceConfigs = {};
+				for (const serviceKey in externalConfig.globalServiceConfigs) if (Object.prototype.hasOwnProperty.call(externalConfig.globalServiceConfigs, serviceKey)) this.config.globalServiceConfigs[serviceKey] = {
+					...this.config.globalServiceConfigs[serviceKey] || {},
+					...externalConfig.globalServiceConfigs[serviceKey]
+				};
+			}
+			if (externalConfig.rpcEndpoints) {
+				if (!this.config.rpcEndpoints) this.config.rpcEndpoints = {};
+				for (const networkKey in externalConfig.rpcEndpoints) if (Object.prototype.hasOwnProperty.call(externalConfig.rpcEndpoints, networkKey)) this.config.rpcEndpoints[networkKey] = externalConfig.rpcEndpoints[networkKey];
+			}
+			if (externalConfig.indexerEndpoints) {
+				if (!this.config.indexerEndpoints) this.config.indexerEndpoints = {};
+				for (const networkKey in externalConfig.indexerEndpoints) if (Object.prototype.hasOwnProperty.call(externalConfig.indexerEndpoints, networkKey)) this.config.indexerEndpoints[networkKey] = externalConfig.indexerEndpoints[networkKey];
+			}
+			if (externalConfig.featureFlags) this.config.featureFlags = {
+				...this.config.featureFlags || {},
+				...externalConfig.featureFlags
+			};
+			if (typeof externalConfig.defaultLanguage === "string") this.config.defaultLanguage = externalConfig.defaultLanguage;
+			logger.info(LOG_SYSTEM, `Configuration loaded/merged from ${filePath}`);
+		} catch (error) {
+			logger.error(LOG_SYSTEM, `Error loading or parsing config from ${filePath}:`, error);
+		}
+	}
+	/**
+	* Initializes the service by loading configuration from the specified strategies.
+	* @param strategies - Array of configuration loading strategies to apply
+	*/
+	async initialize(strategies) {
+		logger.info(LOG_SYSTEM, "Initialization sequence started with strategies:", strategies);
+		for (const strategy of strategies) if (strategy.type === "viteEnv") this.loadFromViteEnvironment(strategy.env);
+		else if (strategy.type === "json") await this.loadFromJson(strategy.path);
+		this.isInitialized = true;
+		logger.info(LOG_SYSTEM, "Initialization complete.");
+	}
+	/**
+	* Gets the API key for a specific explorer service.
+	* @param serviceIdentifier - The service identifier
+	* @returns The API key if configured, undefined otherwise
+	*/
+	getExplorerApiKey(serviceIdentifier) {
+		if (!this.isInitialized) logger.warn(LOG_SYSTEM, "getExplorerApiKey called before initialization.");
+		return this.config.networkServiceConfigs?.[serviceIdentifier]?.apiKey;
+	}
+	/**
+	* Gets the configuration for a global service.
+	* @param serviceName - The name of the service
+	* @returns The service configuration if found, undefined otherwise
+	*/
+	getGlobalServiceConfig(serviceName) {
+		if (!this.isInitialized) logger.warn(LOG_SYSTEM, "getGlobalServiceConfig called before initialization.");
+		return this.config.globalServiceConfigs?.[serviceName];
+	}
+	/**
+	* Checks if a feature flag is enabled.
+	* @param flagName - The name of the feature flag
+	* @returns True if the feature is enabled, false otherwise
+	*/
+	isFeatureEnabled(flagName) {
+		if (!this.isInitialized) logger.warn(LOG_SYSTEM, "isFeatureEnabled called before initialization.");
+		return this.config.featureFlags?.[flagName.toLowerCase()] ?? false;
+	}
+	/**
+	* Gets a global service parameter value.
+	* @param serviceName The name of the service
+	* @param paramName The name of the parameter
+	* @returns The parameter value (can be any type including objects, arrays) or undefined if not found
+	*/
+	getGlobalServiceParam(serviceName, paramName) {
+		if (!this.isInitialized) {
+			logger.warn(LOG_SYSTEM, "getGlobalServiceParam called before initialization.");
+			return;
+		}
+		return (this.config.globalServiceConfigs?.[serviceName.toLowerCase()])?.[paramName];
+	}
+	/**
+	* Gets the RPC endpoint override for a specific network.
+	* @param networkId - The network identifier
+	* @returns The RPC endpoint configuration if found, undefined otherwise
+	*/
+	getRpcEndpointOverride(networkId) {
+		if (!this.isInitialized) logger.warn(LOG_SYSTEM, "getRpcEndpointOverride called before initialization.");
+		return this.config.rpcEndpoints?.[networkId];
+	}
+	/**
+	* Get the indexer endpoint override for a specific network.
+	* Indexer endpoints are used for querying historical blockchain data.
+	* @param networkId The network identifier (e.g., 'stellar-testnet')
+	* @returns The indexer endpoint configuration, or undefined if not configured
+	*/
+	getIndexerEndpointOverride(networkId) {
+		if (!this.isInitialized) logger.warn(LOG_SYSTEM, "getIndexerEndpointOverride called before initialization.");
+		return this.config.indexerEndpoints?.[networkId];
+	}
+	/**
+	* Returns the entire configuration object.
+	* Primarily for debugging or for parts of the app that need a broader view.
+	* Use specific getters like `getExplorerApiKey` or `isFeatureEnabled` where possible.
+	*/
+	getConfig() {
+		return this.config;
+	}
+	/**
+	* Gets a nested configuration object with type safety.
+	*
+	* This is a helper method to safely access complex nested configuration objects
+	* with proper TypeScript type checking.
+	*
+	* @param serviceName The name of the service (e.g., 'walletui')
+	* @param paramName The parameter name that contains the nested object (e.g., 'config')
+	*                  Pass an empty string to get the entire service configuration.
+	* @returns The typed nested configuration object or undefined if not found
+	*
+	* @example
+	* // Get a typed UI kit configuration:
+	* const uiConfig = appConfigService.getTypedNestedConfig<UiKitConfiguration>('walletui', 'config');
+	* if (uiConfig) {
+	*   console.log(uiConfig.kitName); // Properly typed
+	* }
+	*
+	* // Get entire service configuration:
+	* const allAnalytics = appConfigService.getTypedNestedConfig<AnalyticsConfig>('analytics', '');
+	*/
+	getTypedNestedConfig(serviceName, paramName) {
+		if (!this.isInitialized) {
+			logger.warn(LOG_SYSTEM, "getTypedNestedConfig called before initialization.");
+			return;
+		}
+		try {
+			if (paramName === "") {
+				const serviceConfig = this.config.globalServiceConfigs?.[serviceName.toLowerCase()];
+				if (serviceConfig && typeof serviceConfig === "object") return serviceConfig;
+				return;
+			}
+			const param = this.getGlobalServiceParam(serviceName, paramName);
+			if (param && typeof param === "object") return param;
+			return;
+		} catch (error) {
+			logger.warn(LOG_SYSTEM, `Error accessing nested configuration for ${serviceName}.${paramName}:`, error);
+			return;
+		}
+	}
+	/**
+	* Checks if a nested configuration exists and has a specific property.
+	*
+	* @param serviceName The name of the service
+	* @param paramName The parameter name containing the nested object
+	* @param propName The property name to check for
+	* @returns True if the property exists in the nested configuration
+	*
+	* @example
+	* if (appConfigService.hasNestedConfigProperty('walletui', 'config', 'showInjectedConnector')) {
+	*   // Do something when the property exists
+	* }
+	*/
+	hasNestedConfigProperty(serviceName, paramName, propName) {
+		const nestedConfig = this.getTypedNestedConfig(serviceName, paramName);
+		return nestedConfig !== void 0 && Object.prototype.hasOwnProperty.call(nestedConfig, propName);
+	}
+	/**
+	* Gets wallet UI configuration for a specific ecosystem.
+	* Uses ecosystem-namespaced format with optional default fallback.
+	*
+	* @param ecosystemId The ecosystem ID (e.g., 'stellar', 'evm', 'solana')
+	* @returns The wallet UI configuration for the ecosystem, or undefined
+	*
+	* @example
+	* Configuration format:
+	* {
+	*   "globalServiceConfigs": {
+	*     "walletui": {
+	*       "stellar": { "kitName": "stellar-wallets-kit", "kitConfig": {} },
+	*       "evm": { "kitName": "rainbowkit", "kitConfig": {} },
+	*       "default": { "kitName": "custom", "kitConfig": {} }
+	*     }
+	*   }
+	* }
+	* const stellarConfig = appConfigService.getWalletUIConfig('stellar');
+	*/
+	getWalletUIConfig(ecosystemId) {
+		if (!this.isInitialized) {
+			logger.warn(LOG_SYSTEM, "getWalletUIConfig called before initialization.");
+			return;
+		}
+		try {
+			const walletUIService = this.config.globalServiceConfigs?.walletui;
+			if (!walletUIService) return;
+			if (ecosystemId && walletUIService[ecosystemId] && typeof walletUIService[ecosystemId] === "object") {
+				logger.debug(LOG_SYSTEM, `Found ecosystem-specific wallet UI config for ${ecosystemId}`);
+				return walletUIService[ecosystemId];
+			}
+			if (walletUIService.default && typeof walletUIService.default === "object") {
+				logger.debug(LOG_SYSTEM, `Using default wallet UI config for ecosystem ${ecosystemId}`);
+				return walletUIService.default;
+			}
+			return;
+		} catch (error) {
+			logger.warn(LOG_SYSTEM, `Error accessing wallet UI configuration for ecosystem ${ecosystemId}:`, error);
+			return;
+		}
+	}
+};
+const appConfigService = new AppConfigService();
+
+//#endregion
+//#region src/UserRpcConfigService.ts
+/**
+* Service for managing user-configured RPC endpoints.
+* Stores RPC configurations in localStorage for persistence across sessions.
+*/
+var UserRpcConfigService = class {
+	static STORAGE_PREFIX = "tfb_rpc_config_";
+	static eventListeners = /* @__PURE__ */ new Map();
+	/**
+	* Emits an RPC configuration event to all registered listeners
+	*/
+	static emitEvent(event) {
+		const listeners = this.eventListeners.get(event.networkId) || /* @__PURE__ */ new Set();
+		const globalListeners = this.eventListeners.get("*") || /* @__PURE__ */ new Set();
+		[...listeners, ...globalListeners].forEach((listener) => {
+			try {
+				listener(event);
+			} catch (error) {
+				logger.error("UserRpcConfigService", "Error in event listener:", error);
+			}
+		});
+	}
+	/**
+	* Subscribes to RPC configuration changes for a specific network or all networks
+	* @param networkId The network identifier or '*' for all networks
+	* @param listener The callback to invoke when RPC config changes
+	* @returns Unsubscribe function
+	*/
+	static subscribe(networkId, listener) {
+		if (!this.eventListeners.has(networkId)) this.eventListeners.set(networkId, /* @__PURE__ */ new Set());
+		this.eventListeners.get(networkId).add(listener);
+		return () => {
+			const listeners = this.eventListeners.get(networkId);
+			if (listeners) {
+				listeners.delete(listener);
+				if (listeners.size === 0) this.eventListeners.delete(networkId);
+			}
+		};
+	}
+	/**
+	* Saves a user RPC configuration for a specific network.
+	* @param networkId The network identifier
+	* @param config The RPC configuration to save
+	*/
+	static saveUserRpcConfig(networkId, config) {
+		try {
+			const storageKey = `${this.STORAGE_PREFIX}${networkId}`;
+			localStorage.setItem(storageKey, JSON.stringify(config));
+			logger.info("UserRpcConfigService", `Saved RPC config for network ${networkId}`);
+			this.emitEvent({
+				type: "rpc-config-changed",
+				networkId,
+				config
+			});
+		} catch (error) {
+			logger.error("UserRpcConfigService", "Failed to save RPC config:", error);
+		}
+	}
+	/**
+	* Retrieves a user RPC configuration for a specific network.
+	* @param networkId The network identifier
+	* @returns The stored configuration or null if not found
+	*/
+	static getUserRpcConfig(networkId) {
+		try {
+			const storageKey = `${this.STORAGE_PREFIX}${networkId}`;
+			const stored = localStorage.getItem(storageKey);
+			if (!stored) return null;
+			const config = JSON.parse(stored);
+			logger.info("UserRpcConfigService", `Retrieved RPC config for network ${networkId}`);
+			return config;
+		} catch (error) {
+			logger.error("UserRpcConfigService", "Failed to retrieve RPC config:", error);
+			return null;
+		}
+	}
+	/**
+	* Clears a user RPC configuration for a specific network.
+	* @param networkId The network identifier
+	*/
+	static clearUserRpcConfig(networkId) {
+		try {
+			const storageKey = `${this.STORAGE_PREFIX}${networkId}`;
+			localStorage.removeItem(storageKey);
+			logger.info("UserRpcConfigService", `Cleared RPC config for network ${networkId}`);
+			this.emitEvent({
+				type: "rpc-config-cleared",
+				networkId
+			});
+		} catch (error) {
+			logger.error("UserRpcConfigService", "Failed to clear RPC config:", error);
+		}
+	}
+	/**
+	* Clears all user RPC configurations.
+	*/
+	static clearAllUserRpcConfigs() {
+		try {
+			const keysToRemove = [];
+			for (let i = 0; i < localStorage.length; i++) {
+				const key = localStorage.key(i);
+				if (key?.startsWith(this.STORAGE_PREFIX)) keysToRemove.push(key);
+			}
+			keysToRemove.forEach((key) => localStorage.removeItem(key));
+			logger.info("UserRpcConfigService", `Cleared ${keysToRemove.length} RPC configs`);
+		} catch (error) {
+			logger.error("UserRpcConfigService", "Failed to clear all RPC configs:", error);
+		}
+	}
+};
+const userRpcConfigService = UserRpcConfigService;
+
+//#endregion
+//#region src/UserExplorerConfigService.ts
+/**
+* Service for managing user-configured block explorer endpoints and API keys.
+* Stores explorer configurations in localStorage for persistence across sessions.
+*/
+var UserExplorerConfigService = class {
+	static STORAGE_PREFIX = "tfb_explorer_config_";
+	static eventListeners = /* @__PURE__ */ new Map();
+	/**
+	* Emits an explorer configuration event to all registered listeners
+	*/
+	static emitEvent(event) {
+		const listeners = this.eventListeners.get(event.networkId) || /* @__PURE__ */ new Set();
+		const globalListeners = this.eventListeners.get("*") || /* @__PURE__ */ new Set();
+		[...listeners, ...globalListeners].forEach((listener) => {
+			try {
+				listener(event);
+			} catch (error) {
+				logger.error("UserExplorerConfigService", "Error in event listener:", error);
+			}
+		});
+	}
+	/**
+	* Subscribes to explorer configuration changes for a specific network or all networks
+	* @param networkId The network identifier or '*' for all networks
+	* @param listener The callback to invoke when explorer config changes
+	* @returns Unsubscribe function
+	*/
+	static subscribe(networkId, listener) {
+		if (!this.eventListeners.has(networkId)) this.eventListeners.set(networkId, /* @__PURE__ */ new Set());
+		this.eventListeners.get(networkId).add(listener);
+		return () => {
+			const listeners = this.eventListeners.get(networkId);
+			if (listeners) {
+				listeners.delete(listener);
+				if (listeners.size === 0) this.eventListeners.delete(networkId);
+			}
+		};
+	}
+	/**
+	* Saves a user explorer configuration for a specific network.
+	* @param networkId The network identifier
+	* @param config The explorer configuration to save
+	*/
+	static saveUserExplorerConfig(networkId, config) {
+		try {
+			const storageKey = `${this.STORAGE_PREFIX}${networkId}`;
+			localStorage.setItem(storageKey, JSON.stringify(config));
+			logger.info("UserExplorerConfigService", `Saved explorer config for network ${networkId}`);
+			this.emitEvent({
+				type: "explorer-config-changed",
+				networkId,
+				config
+			});
+		} catch (error) {
+			logger.error("UserExplorerConfigService", "Failed to save explorer config:", error);
+		}
+	}
+	/**
+	* Retrieves a user explorer configuration for a specific network.
+	* First checks for global settings, then falls back to network-specific settings.
+	* @param networkId The network identifier
+	* @returns The stored configuration or null if not found
+	*/
+	static getUserExplorerConfig(networkId) {
+		try {
+			const globalKey = `${this.STORAGE_PREFIX}__global__`;
+			const globalStored = localStorage.getItem(globalKey);
+			if (globalStored) {
+				const globalConfig = JSON.parse(globalStored);
+				if (globalConfig.applyToAllNetworks) {
+					logger.info("UserExplorerConfigService", `Using global explorer config for network ${networkId}`);
+					return globalConfig;
+				}
+			}
+			const storageKey = `${this.STORAGE_PREFIX}${networkId}`;
+			const stored = localStorage.getItem(storageKey);
+			if (!stored) return null;
+			const config = JSON.parse(stored);
+			logger.info("UserExplorerConfigService", `Retrieved explorer config for network ${networkId}`);
+			return config;
+		} catch (error) {
+			logger.error("UserExplorerConfigService", "Failed to retrieve explorer config:", error);
+			return null;
+		}
+	}
+	/**
+	* Clears a user explorer configuration for a specific network.
+	* @param networkId The network identifier
+	*/
+	static clearUserExplorerConfig(networkId) {
+		try {
+			const storageKey = `${this.STORAGE_PREFIX}${networkId}`;
+			localStorage.removeItem(storageKey);
+			logger.info("UserExplorerConfigService", `Cleared explorer config for network ${networkId}`);
+			this.emitEvent({
+				type: "explorer-config-cleared",
+				networkId
+			});
+		} catch (error) {
+			logger.error("UserExplorerConfigService", "Failed to clear explorer config:", error);
+		}
+	}
+	/**
+	* Clears all user explorer configurations.
+	*/
+	static clearAllUserExplorerConfigs() {
+		try {
+			const keysToRemove = [];
+			for (let i = 0; i < localStorage.length; i++) {
+				const key = localStorage.key(i);
+				if (key?.startsWith(this.STORAGE_PREFIX)) keysToRemove.push(key);
+			}
+			keysToRemove.forEach((key) => {
+				const networkId = key.substring(this.STORAGE_PREFIX.length);
+				localStorage.removeItem(key);
+				this.emitEvent({
+					type: "explorer-config-cleared",
+					networkId
+				});
+			});
+			logger.info("UserExplorerConfigService", `Cleared ${keysToRemove.length} explorer configs`);
+		} catch (error) {
+			logger.error("UserExplorerConfigService", "Failed to clear all explorer configs:", error);
+		}
+	}
+	/**
+	* Gets all network IDs that have explorer configurations.
+	* @returns Array of network IDs
+	*/
+	static getConfiguredNetworkIds() {
+		try {
+			const networkIds = [];
+			for (let i = 0; i < localStorage.length; i++) {
+				const key = localStorage.key(i);
+				if (key?.startsWith(this.STORAGE_PREFIX)) {
+					const networkId = key.substring(this.STORAGE_PREFIX.length);
+					if (networkId !== "__global__") networkIds.push(networkId);
+				}
+			}
+			return networkIds;
+		} catch (error) {
+			logger.error("UserExplorerConfigService", "Failed to get configured network IDs:", error);
+			return [];
+		}
+	}
+};
+const userExplorerConfigService = UserExplorerConfigService;
+
+//#endregion
+//#region src/UserNetworkServiceConfigService.ts
+/**
+* Service for managing user-defined network service configurations.
+*
+* This service provides a generic, chain-agnostic way to store and retrieve
+* per-network, per-service user configurations.
+*
+* Configurations are stored in localStorage with the key format:
+* `tfb_service_config_{serviceId}__{networkId}`
+*
+* @example
+* ```typescript
+* // Save RPC configuration for Sepolia
+* userNetworkServiceConfigService.save('ethereum-sepolia', 'rpc', {
+*   rpcUrl: 'https://sepolia.infura.io/v3/your-key'
+* });
+*
+* // Retrieve configuration
+* const config = userNetworkServiceConfigService.get('ethereum-sepolia', 'rpc');
+*
+* // Subscribe to changes
+* const unsubscribe = userNetworkServiceConfigService.subscribe(
+*   'ethereum-sepolia',
+*   'rpc',
+*   (event) => {
+*     console.log('Config changed:', event.config);
+*   }
+* );
+* ```
+*
+* @class UserNetworkServiceConfigService
+*/
+var UserNetworkServiceConfigService = class {
+	static STORAGE_PREFIX = "tfb_service_config_";
+	static listeners = /* @__PURE__ */ new Map();
+	/**
+	* Generates a localStorage key for a network-service combination.
+	*
+	* @private
+	* @param networkId - The network ID
+	* @param serviceId - The service ID
+	* @returns The storage key string
+	*/
+	static key(networkId, serviceId) {
+		return `${this.STORAGE_PREFIX}${serviceId}__${networkId}`;
+	}
+	/**
+	* Subscribes to configuration change events for a specific network and/or service.
+	*
+	* Use '*' as a wildcard to listen to all networks or all services.
+	* The listener will be called whenever a matching configuration changes or is cleared.
+	*
+	* @param networkId - Network ID to listen to, or '*' for all networks
+	* @param serviceId - Service ID to listen to, or '*' for all services
+	* @param listener - Callback function to invoke when matching events occur
+	* @returns Unsubscribe function to remove the listener
+	*
+	* @example
+	* ```typescript
+	* // Listen to all RPC config changes across all networks
+	* const unsubscribe = userNetworkServiceConfigService.subscribe('*', 'rpc', (event) => {
+	*   console.log(`${event.networkId} RPC config changed`);
+	* });
+	*
+	* // Later, unsubscribe
+	* unsubscribe();
+	* ```
+	*/
+	static subscribe(networkId, serviceId, listener) {
+		const k = `${networkId}:${serviceId}`;
+		if (!this.listeners.has(k)) this.listeners.set(k, /* @__PURE__ */ new Set());
+		this.listeners.get(k).add(listener);
+		return () => {
+			const set = this.listeners.get(k);
+			if (set) {
+				set.delete(listener);
+				if (set.size === 0) this.listeners.delete(k);
+			}
+		};
+	}
+	/**
+	* Emits an event to all matching subscribers.
+	* Subscribers are matched based on exact network/service IDs or wildcards.
+	*
+	* @private
+	* @param event - The event to emit
+	*/
+	static emit(event) {
+		const targets = [
+			`${event.networkId}:${event.serviceId}`,
+			`${event.networkId}:*`,
+			`*:${event.serviceId}`,
+			`*:*`
+		];
+		for (const k of targets) {
+			const set = this.listeners.get(k);
+			if (!set) continue;
+			for (const fn of set) try {
+				fn(event);
+			} catch (e) {
+				logger.error("UserNetworkServiceConfigService", "Error in event listener:", e);
+			}
+		}
+	}
+	/**
+	* Saves a service configuration for a specific network.
+	*
+	* The configuration is stored in localStorage and all matching subscribers
+	* are notified via a 'service-config-changed' event.
+	*
+	* @param networkId - The network ID (e.g., 'ethereum-sepolia')
+	* @param serviceId - The service ID (e.g., 'rpc', 'explorer', 'contract-definitions')
+	* @param config - The configuration object to save
+	*
+	* @example
+	* ```typescript
+	* userNetworkServiceConfigService.save('ethereum-sepolia', 'rpc', {
+	*   rpcUrl: 'https://sepolia.infura.io/v3/your-key'
+	* });
+	* ```
+	*/
+	static save(networkId, serviceId, config) {
+		try {
+			localStorage.setItem(this.key(networkId, serviceId), JSON.stringify(config));
+			logger.info("UserNetworkServiceConfigService", `Saved config for ${serviceId} on network ${networkId}`);
+			this.emit({
+				type: "service-config-changed",
+				networkId,
+				serviceId,
+				config
+			});
+		} catch (e) {
+			logger.error("UserNetworkServiceConfigService", "Failed to save config:", e);
+		}
+	}
+	/**
+	* Retrieves a saved service configuration for a specific network.
+	*
+	* @param networkId - The network ID (e.g., 'ethereum-sepolia')
+	* @param serviceId - The service ID (e.g., 'rpc', 'explorer', 'contract-definitions')
+	* @returns The configuration object, or null if not found or if retrieval fails
+	*
+	* @example
+	* ```typescript
+	* const config = userNetworkServiceConfigService.get('ethereum-sepolia', 'rpc');
+	* if (config) {
+	*   console.log('RPC URL:', config.rpcUrl);
+	* }
+	* ```
+	*/
+	static get(networkId, serviceId) {
+		try {
+			const raw = localStorage.getItem(this.key(networkId, serviceId));
+			return raw ? JSON.parse(raw) : null;
+		} catch (e) {
+			logger.error("UserNetworkServiceConfigService", "Failed to retrieve config:", e);
+			return null;
+		}
+	}
+	/**
+	* Clears a saved service configuration for a specific network.
+	*
+	* Removes the configuration from localStorage and notifies all matching subscribers
+	* via a 'service-config-cleared' event.
+	*
+	* @param networkId - The network ID (e.g., 'ethereum-sepolia')
+	* @param serviceId - The service ID (e.g., 'rpc', 'explorer', 'contract-definitions')
+	*
+	* @example
+	* ```typescript
+	* userNetworkServiceConfigService.clear('ethereum-sepolia', 'rpc');
+	* ```
+	*/
+	static clear(networkId, serviceId) {
+		try {
+			localStorage.removeItem(this.key(networkId, serviceId));
+			logger.info("UserNetworkServiceConfigService", `Cleared config for ${serviceId} on network ${networkId}`);
+			this.emit({
+				type: "service-config-cleared",
+				networkId,
+				serviceId
+			});
+		} catch (e) {
+			logger.error("UserNetworkServiceConfigService", "Failed to clear config:", e);
+		}
+	}
+};
+/**
+* Singleton instance of UserNetworkServiceConfigService.
+* This is the preferred way to access the service.
+*
+* @example
+* ```typescript
+* import { userNetworkServiceConfigService } from '@openzeppelin/ui-utils';
+*
+* userNetworkServiceConfigService.save('ethereum-sepolia', 'rpc', { rpcUrl: '...' });
+* ```
+*/
+const userNetworkServiceConfigService = UserNetworkServiceConfigService;
+
+//#endregion
+//#region src/fieldDefaults.ts
+/**
+* Get a default value for a field type.
+* This is a chain-agnostic utility that provides appropriate default values
+* based on the UI field type.
+*
+* @param fieldType - The UI field type
+* @returns The appropriate default value for that field type
+*/
+function getDefaultValueForType(fieldType) {
+	switch (fieldType) {
+		case "checkbox": return false;
+		case "number":
+		case "amount": return 0;
+		case "array": return [];
+		case "object": return {};
+		case "array-object": return [];
+		case "map": return [];
+		case "blockchain-address":
+		case "bigint":
+		case "text":
+		case "textarea":
+		case "bytes":
+		case "email":
+		case "password":
+		case "select":
+		case "radio":
+		case "date":
+		case "hidden":
+		default: return "";
+	}
+}
+
+//#endregion
+//#region src/fieldValidation.ts
+/**
+* Enhances field validation with numeric bounds based on parameter type.
+* Only applies bounds if they are not already set in the validation object.
+*
+* @param validation - Existing validation rules (may be undefined)
+* @param parameterType - The blockchain parameter type (e.g., 'uint32', 'U32', 'Uint<0..255>')
+* @param boundsMap - Chain-specific map of type names to min/max bounds
+* @returns Enhanced validation object with numeric bounds applied
+*
+* @example
+* ```typescript
+* const stellarBounds = { U32: { min: 0, max: 4_294_967_295 } };
+* const validation = enhanceNumericValidation(undefined, 'U32', stellarBounds);
+* // Returns: { min: 0, max: 4_294_967_295 }
+* ```
+*/
+function enhanceNumericValidation(validation, parameterType, boundsMap) {
+	const result = { ...validation ?? {} };
+	const bounds = boundsMap[parameterType];
+	if (!bounds) return result;
+	if (bounds.min !== void 0 && result.min === void 0) result.min = bounds.min;
+	if (bounds.max !== void 0 && result.max === void 0) result.max = bounds.max;
+	return result;
+}
+
+//#endregion
+//#region src/typeguards.ts
+/**
+* Type guard to check if a value is a non-null object (Record<string, unknown>).
+* Useful for safely accessing properties on an 'unknown' type after this check.
+* @param value - The value to check.
+* @returns True if the value is a non-null object, false otherwise.
+*/
+function isRecordWithProperties(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Type guard to check if a value is a plain object (not an array, not null).
+* This is useful for distinguishing between objects and arrays, since arrays are technically objects in JavaScript.
+* @param value - The value to check.
+* @returns True if the value is a plain object (not array, not null), false otherwise.
+*/
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+//#endregion
+//#region src/cn.ts
+/**
+* Combines class names using clsx and tailwind-merge.
+* @param inputs - Class values to combine
+* @returns Merged class name string
+*/
+function cn(...inputs) {
+	return (0, tailwind_merge.twMerge)((0, clsx.clsx)(inputs));
+}
+
+//#endregion
+//#region src/formatting.ts
+/**
+* String and date formatting utility functions
+* These utilities help with common formatting operations
+*/
+/**
+* Truncates a string (like an Ethereum address) in the middle
+* @param str The string to truncate
+* @param startChars Number of characters to show at the beginning
+* @param endChars Number of characters to show at the end
+* @returns The truncated string with ellipsis in the middle
+*/
+function truncateMiddle(str, startChars = 6, endChars = 4) {
+	if (!str) return "";
+	if (str.length <= startChars + endChars) return str;
+	return `${str.substring(0, startChars)}...${str.substring(str.length - endChars)}`;
+}
+/**
+* Formats a timestamp as a relative time string (e.g., "2h ago", "just now")
+* @param date The date to format
+* @returns A human-readable relative time string
+*/
+function formatTimestamp(date) {
+	const diffMs = (/* @__PURE__ */ new Date()).getTime() - date.getTime();
+	const diffMinutes = Math.floor(diffMs / (1e3 * 60));
+	const diffHours = Math.floor(diffMs / (1e3 * 60 * 60));
+	const diffDays = Math.floor(diffMs / (1e3 * 60 * 60 * 24));
+	if (diffMinutes < 1) return "just now";
+	if (diffMinutes < 60) return `${diffMinutes}m ago`;
+	if (diffHours < 24) return `${diffHours}h ago`;
+	if (diffDays < 7) return `${diffDays}d ago`;
+	return date.toLocaleDateString();
+}
+/**
+* Detects whether a string contains hex-encoded or base64-encoded binary data.
+* Useful for auto-detecting the encoding format of user inputs across blockchain adapters.
+*
+* @param value - The string to analyze
+* @returns 'hex' if the string appears to be hexadecimal, 'base64' if it appears to be base64
+*
+* @example
+* ```typescript
+* detectBytesEncoding("48656c6c6f") // → 'hex'
+* detectBytesEncoding("SGVsbG8=") // → 'base64'
+* detectBytesEncoding("0x48656c6c6f") // → 'hex' (after stripping 0x prefix)
+* ```
+*/
+function detectBytesEncoding(value) {
+	const trimmed = value?.trim() ?? "";
+	const without0x = trimmed.startsWith("0x") || trimmed.startsWith("0X") ? trimmed.slice(2) : trimmed;
+	const hexRegex = /^[0-9a-fA-F]+$/;
+	const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+	if (hexRegex.test(without0x) && without0x.length > 0 && without0x.length % 2 === 0) return "hex";
+	if (base64Regex.test(trimmed) && trimmed.length % 4 === 0) try {
+		const decoded = atob(trimmed);
+		if (btoa(decoded).replace(/=+$/, "") === trimmed.replace(/=+$/, "")) return "base64";
+	} catch {}
+	return "hex";
+}
+
+//#endregion
+//#region src/generateId.ts
+/**
+* General utility functions, which are not specific to any blockchain
+* It's important to keep these functions as simple as possible and avoid any
+* dependencies from other packages.
+*/
+/**
+* Generates a unique ID for form fields, components, etc.
+* Uses crypto.getRandomValues() for browser-compatible random ID generation.
+*
+* @param prefix Optional prefix to add before the UUID
+* @returns A string ID that is guaranteed to be unique
+*/
+function generateId(prefix) {
+	const uuid$1 = (0, uuid.v4)();
+	return prefix ? `${prefix}_${uuid$1}` : uuid$1;
+}
+
+//#endregion
+//#region src/validators.ts
+/**
+* URL validation utilities
+*/
+/**
+* Validates if a string is a valid URL (supports http, https, and ftp protocols).
+* Relies solely on the URL constructor for validation.
+*
+* @param urlString - The string to validate
+* @returns True if the URL is valid, false otherwise
+*/
+function isValidUrl(urlString) {
+	if (!urlString || typeof urlString !== "string") return false;
+	try {
+		new URL(urlString);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Gets a user-friendly error message for invalid URLs.
+*
+* @returns Standard error message for invalid URLs
+*/
+function getInvalidUrlMessage() {
+	return "Please enter a valid URL (e.g., https://example.com)";
+}
+
+//#endregion
+//#region src/async.ts
+/**
+* Utility to add delay between operations
+* @param ms - Milliseconds to delay
+* @returns Promise that resolves after the specified delay
+*/
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Executes operations in batches with rate limiting to prevent API overload
+* @param operations - Array of functions that return promises
+* @param batchSize - Number of operations to execute in parallel per batch (default: 2)
+* @param delayMs - Delay in milliseconds between batches (default: 100)
+* @returns Promise that resolves to an array of results from all operations
+*/
+async function rateLimitedBatch(operations, batchSize = 2, delayMs = 100) {
+	const results = [];
+	for (let i = 0; i < operations.length; i += batchSize) {
+		const batch = operations.slice(i, i + batchSize);
+		const batchResults = await Promise.all(batch.map((operation) => operation()));
+		results.push(...batchResults);
+		if (i + batchSize < operations.length) await delay(delayMs);
+	}
+	return results;
+}
+/**
+* Wraps a promise with a timeout. Rejects with a descriptive Error after timeoutMs.
+*
+* @param promise The promise to wrap
+* @param timeoutMs Timeout in milliseconds
+* @param label Optional label to include in the timeout error message
+*/
+function withTimeout(promise, timeoutMs, label) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error(`${label ?? "operation"} timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}).catch((err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+/**
+* Default concurrency limit for parallel operations.
+* Set to a reasonable value that balances performance and service limits.
+*/
+const DEFAULT_CONCURRENCY_LIMIT = 10;
+/**
+* Execute an array of promise-returning functions with a concurrency limit.
+*
+* Uses a worker pool approach that maintains up to `limit` concurrent operations.
+* As soon as one operation completes, the next one starts immediately, maximizing
+* throughput while respecting the concurrency limit.
+*
+* Results are returned in the same order as the input tasks, regardless of
+* completion order.
+*
+* @param tasks Array of functions that return promises
+* @param limit Maximum number of concurrent executions (default: 10)
+* @returns Promise resolving to array of results in same order as input tasks
+*
+* @example
+* ```typescript
+* // Fetch 100 role members with max 10 concurrent RPC requests
+* const tasks = memberIndices.map((index) => () => getRoleMember(contract, role, index));
+* const members = await promiseAllWithLimit(tasks, 10);
+* ```
+*/
+async function promiseAllWithLimit(tasks, limit = DEFAULT_CONCURRENCY_LIMIT) {
+	if (tasks.length === 0) return [];
+	if (limit >= tasks.length) return Promise.all(tasks.map((task) => task()));
+	const results = new Array(tasks.length);
+	let currentIndex = 0;
+	async function worker() {
+		while (currentIndex < tasks.length) {
+			const index = currentIndex++;
+			const task = tasks[index];
+			results[index] = await task();
+		}
+	}
+	const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => worker());
+	await Promise.all(workers);
+	return results;
+}
+/**
+* Execute an array of promise-returning functions with a concurrency limit,
+* settling all promises (similar to Promise.allSettled but with concurrency control).
+*
+* Unlike promiseAllWithLimit, this function does not fail fast on errors.
+* All tasks will be executed regardless of individual failures.
+*
+* @param tasks Array of functions that return promises
+* @param limit Maximum number of concurrent executions (default: 10)
+* @returns Promise resolving to array of settled results in same order as input tasks
+*
+* @example
+* ```typescript
+* const tasks = items.map((item) => () => fetchItem(item.id));
+* const results = await promiseAllSettledWithLimit(tasks, 10);
+*
+* for (const result of results) {
+*   if (result.status === 'fulfilled') {
+*     console.log('Success:', result.value);
+*   } else {
+*     console.log('Failed:', result.reason);
+*   }
+* }
+* ```
+*/
+async function promiseAllSettledWithLimit(tasks, limit = DEFAULT_CONCURRENCY_LIMIT) {
+	if (tasks.length === 0) return [];
+	if (limit >= tasks.length) return Promise.allSettled(tasks.map((task) => task()));
+	const results = new Array(tasks.length);
+	let currentIndex = 0;
+	async function worker() {
+		while (currentIndex < tasks.length) {
+			const index = currentIndex++;
+			const task = tasks[index];
+			try {
+				results[index] = {
+					status: "fulfilled",
+					value: await task()
+				};
+			} catch (reason) {
+				results[index] = {
+					status: "rejected",
+					reason
+				};
+			}
+		}
+	}
+	const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => worker());
+	await Promise.all(workers);
+	return results;
+}
+
+//#endregion
+//#region src/hash.ts
+/**
+* Simple browser-compatible hash utilities
+* These functions provide deterministic hashing for content comparison
+* and are not intended for cryptographic purposes.
+*/
+/**
+* Creates a simple hash from a string using a non-cryptographic algorithm
+* Suitable for content comparison, caching keys, and quick fingerprinting
+*
+* @param str - The string to hash
+* @returns A hexadecimal hash string (always positive)
+*
+* @example
+* ```typescript
+* const hash1 = simpleHash('{"name": "test"}');
+* const hash2 = simpleHash('{"name": "test"}');
+* console.log(hash1 === hash2); // true - deterministic
+* ```
+*/
+function simpleHash(str) {
+	let hash = 0;
+	for (let i = 0; i < str.length; i++) {
+		const char = str.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	return Math.abs(hash).toString(16);
+}
+
+//#endregion
+//#region src/bytesValidation.ts
+/**
+* Validates bytes input using the established validator.js library.
+*
+* This function provides comprehensive validation for blockchain bytes data including:
+* - Hex encoding validation (with optional 0x prefix)
+* - Base64 encoding validation
+* - Byte length validation
+* - Format detection
+*
+* @param value - The input string to validate
+* @param options - Validation options
+* @returns Validation result with details
+*
+* @example
+* ```typescript
+* validateBytes('48656c6c6f') // → { isValid: true, detectedFormat: 'hex', byteSize: 5 }
+* validateBytes('SGVsbG8=') // → { isValid: true, detectedFormat: 'base64', byteSize: 5 }
+* validateBytes('invalid') // → { isValid: false, error: '...' }
+* ```
+*/
+function validateBytes(value, options = {}) {
+	const { acceptedFormats = "both", maxBytes, allowHexPrefix = true } = options;
+	if (!value || value.trim() === "") return {
+		isValid: true,
+		cleanedValue: "",
+		byteSize: 0
+	};
+	const cleanValue = value.trim().replace(/\s+/g, "");
+	const hasHexPrefix = cleanValue.startsWith("0x");
+	const withoutPrefix = hasHexPrefix ? cleanValue.slice(2) : cleanValue;
+	if (withoutPrefix === "") return {
+		isValid: false,
+		error: "Bytes value cannot be empty",
+		cleanedValue: cleanValue
+	};
+	let detectedFormat = null;
+	let byteSize = 0;
+	if (validator.default.isHexadecimal(withoutPrefix)) {
+		detectedFormat = "hex";
+		if (withoutPrefix.length % 2 !== 0) return {
+			isValid: false,
+			error: "Hex string must have even number of characters",
+			cleanedValue: cleanValue,
+			detectedFormat
+		};
+		byteSize = withoutPrefix.length / 2;
+	} else if (validator.default.isBase64(withoutPrefix)) {
+		detectedFormat = "base64";
+		try {
+			byteSize = atob(withoutPrefix).length;
+		} catch {
+			return {
+				isValid: false,
+				error: "Invalid base64 encoding",
+				cleanedValue: cleanValue
+			};
+		}
+	}
+	if (!detectedFormat) return {
+		isValid: false,
+		error: "Invalid format. Expected hex or base64 encoding",
+		cleanedValue: cleanValue
+	};
+	if (acceptedFormats !== "both") {
+		if (acceptedFormats === "hex" && detectedFormat !== "hex") return {
+			isValid: false,
+			error: "Only hex format is accepted for this field",
+			cleanedValue: cleanValue,
+			detectedFormat
+		};
+		if (acceptedFormats === "base64" && detectedFormat !== "base64") return {
+			isValid: false,
+			error: "Only base64 format is accepted for this field",
+			cleanedValue: cleanValue,
+			detectedFormat
+		};
+	}
+	if (detectedFormat === "hex" && hasHexPrefix && !allowHexPrefix) return {
+		isValid: false,
+		error: "0x prefix not allowed for this field",
+		cleanedValue: cleanValue,
+		detectedFormat
+	};
+	if (maxBytes && byteSize > maxBytes) return {
+		isValid: false,
+		error: `Maximum ${maxBytes} bytes allowed (${detectedFormat === "hex" ? `${maxBytes * 2} hex characters` : `${maxBytes} bytes`})`,
+		cleanedValue: cleanValue,
+		detectedFormat,
+		byteSize
+	};
+	return {
+		isValid: true,
+		cleanedValue: cleanValue,
+		detectedFormat,
+		byteSize
+	};
+}
+/**
+* Simple validation function that returns boolean or error string
+* (for compatibility with existing React Hook Form validation)
+*
+* @param value - The input string to validate
+* @param options - Validation options
+* @returns true if valid, error string if invalid
+*/
+function validateBytesSimple(value, options = {}) {
+	const result = validateBytes(value, options);
+	return result.isValid ? true : result.error || "Invalid bytes format";
+}
+/**
+* Extracts the size from a Bytes<N> type string, or returns undefined for dynamic Uint8Array
+*
+* @param type - Type string (e.g., "Bytes<32>", "Uint8Array", "bytes")
+* @returns Size in bytes if fixed-size, undefined if dynamic
+*
+* @example
+* ```typescript
+* getBytesSize('Bytes<32>') // → 32
+* getBytesSize('Bytes<64>') // → 64
+* getBytesSize('Uint8Array') // → undefined
+* getBytesSize('bytes') // → undefined
+* ```
+*/
+function getBytesSize(type) {
+	const match = type.match(/^Bytes<(\d+)>$/i);
+	if (match) return Number.parseInt(match[1], 10);
+}
+
+//#endregion
+//#region src/bytesConversion.ts
+/**
+* Cross-platform bytes conversion utilities that work in both browser and Node.js
+* without requiring Buffer polyfills.
+*/
+/**
+* Convert a hex string to Uint8Array using native browser APIs
+* @param hex - Hex string (with or without 0x prefix)
+* @returns Uint8Array representation
+*/
+function hexToBytes(hex) {
+	const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
+	if (cleanHex.length % 2 !== 0) throw new Error("Hex string must have even length");
+	if (!/^[0-9a-fA-F]*$/.test(cleanHex)) throw new Error("Invalid hex characters in string");
+	const bytes = new Uint8Array(cleanHex.length / 2);
+	for (let i = 0; i < cleanHex.length; i += 2) bytes[i / 2] = parseInt(cleanHex.substring(i, i + 2), 16);
+	return bytes;
+}
+/**
+* Convert a base64 string to Uint8Array using native browser APIs
+* Handles data URLs by stripping the prefix
+* @param base64 - Base64 encoded string (with optional data URL prefix)
+* @returns Uint8Array representation
+*/
+function base64ToBytes(base64) {
+	const cleaned = base64.includes(",") ? base64.split(",")[1] : base64;
+	const binaryString = atob(cleaned);
+	const len = binaryString.length;
+	const bytes = new Uint8Array(len);
+	for (let i = 0; i < len; i++) bytes[i] = binaryString.charCodeAt(i);
+	return bytes;
+}
+/**
+* Convert Uint8Array to hex string
+* @param bytes - Uint8Array to convert
+* @param withPrefix - Whether to include '0x' prefix
+* @returns Hex string representation
+*/
+function bytesToHex(bytes, withPrefix = false) {
+	const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+	return withPrefix ? `0x${hex}` : hex;
+}
+/**
+* Convert string to bytes based on detected encoding (hex or base64)
+* @param value - The string value to convert
+* @param encoding - The detected encoding type
+* @returns Uint8Array representation
+*/
+function stringToBytes(value, encoding) {
+	switch (encoding) {
+		case "hex": return hexToBytes(value);
+		case "base64": return base64ToBytes(value);
+		default: throw new Error(`Unsupported encoding: ${encoding}. Supported encodings: hex, base64`);
+	}
+}
+
+//#endregion
+//#region src/environment.ts
+/**
+* Utility functions for environment detection
+*/
+/**
+* Check if the application is running in development or test environment
+* @returns True if NODE_ENV is 'development' or 'test'
+*/
+function isDevelopmentOrTestEnvironment() {
+	return process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test";
+}
+/**
+* Check if the application is running in production environment
+* @returns True if NODE_ENV is 'production'
+*/
+function isProductionEnvironment() {
+	return process.env.NODE_ENV === "production";
+}
+
+//#endregion
+//#region src/RouterService.ts
+/**
+* Default implementation that relies on the browser Location API.
+* The builder app can replace this with a router-bound implementation if needed.
+*/
+var BrowserRouterService = class {
+	currentLocation() {
+		if (typeof window === "undefined") return "";
+		return window.location.href;
+	}
+	getParam(name) {
+		if (typeof window === "undefined") return null;
+		return new URLSearchParams(window.location.search).get(name);
+	}
+	navigate(path) {
+		if (typeof window === "undefined") return;
+		if (path.startsWith("http://") || path.startsWith("https://")) window.location.assign(path);
+		else {
+			const url = new URL(path, window.location.origin);
+			window.history.pushState({}, "", url.toString());
+			window.dispatchEvent(new PopStateEvent("popstate"));
+		}
+	}
+};
+/**
+* Singleton instance for global consumption.
+*/
+const routerService = new BrowserRouterService();
+
+//#endregion
+//#region src/AnalyticsService.ts
+/**
+* Google Analytics service for tracking user interactions.
+* Manages Google Analytics initialization and event tracking.
+* Only active when the analytics_enabled feature flag is true.
+*
+* This is a generic service that provides core analytics functionality.
+* App-specific tracking methods should be implemented in app-level hooks
+* that use the generic `trackEvent` method.
+*
+* @example
+* ```typescript
+* // Initialize analytics (typically done once at app startup)
+* AnalyticsService.initialize('G-XXXXXXXXXX');
+*
+* // Track a custom event
+* AnalyticsService.trackEvent('button_clicked', { button_name: 'submit' });
+*
+* // Track page view
+* AnalyticsService.trackPageView('Dashboard', '/dashboard');
+* ```
+*/
+var AnalyticsService = class {
+	static initialized = false;
+	/**
+	* Initialize Google Analytics
+	* @param tagId - Google Analytics tag ID (e.g., G-N3DZK5FCT1)
+	*/
+	static initialize(tagId) {
+		if (!tagId) {
+			logger.warn("AnalyticsService", "No tag ID provided");
+			return;
+		}
+		if (!this.isEnabled()) {
+			logger.info("AnalyticsService", "Analytics is disabled via feature flag");
+			return;
+		}
+		if (this.initialized) {
+			logger.info("AnalyticsService", "Already initialized");
+			return;
+		}
+		try {
+			this.loadGtagScript(tagId);
+			this.initializeGtag(tagId);
+			this.initialized = true;
+			logger.info("AnalyticsService", "Initialized successfully");
+		} catch (error) {
+			logger.error("AnalyticsService", "Failed to initialize:", error);
+		}
+	}
+	/**
+	* Check if analytics is enabled via feature flag
+	*/
+	static isEnabled() {
+		return appConfigService.isFeatureEnabled("analytics_enabled");
+	}
+	/**
+	* Reset the analytics service state (primarily for testing)
+	*/
+	static reset() {
+		this.initialized = false;
+	}
+	/**
+	* Generic event tracking method.
+	* Use this to track any custom event with arbitrary parameters.
+	*
+	* @param eventName - Name of the event (e.g., 'button_clicked', 'form_submitted')
+	* @param parameters - Key-value pairs of event parameters
+	*
+	* @example
+	* ```typescript
+	* AnalyticsService.trackEvent('ecosystem_selected', { ecosystem: 'evm' });
+	* AnalyticsService.trackEvent('wizard_step', { step_number: 2, step_name: 'configure' });
+	* ```
+	*/
+	static trackEvent(eventName, parameters) {
+		if (!this.isEnabled()) return;
+		try {
+			if (typeof window.gtag === "function") window.gtag("event", eventName, parameters);
+			else logger.warn("AnalyticsService", "gtag is not available");
+		} catch (error) {
+			logger.error("AnalyticsService", `Failed to track event '${eventName}':`, error);
+		}
+	}
+	/**
+	* Track page view event.
+	* Common event shared across all apps.
+	*
+	* @param pageName - Human-readable name of the page
+	* @param pagePath - URL path of the page
+	*
+	* @example
+	* ```typescript
+	* AnalyticsService.trackPageView('Dashboard', '/dashboard');
+	* ```
+	*/
+	static trackPageView(pageName, pagePath) {
+		this.trackEvent("page_view", {
+			page_title: pageName,
+			page_path: pagePath
+		});
+	}
+	/**
+	* Track network selection event.
+	* Common event shared across all apps that involve network selection.
+	*
+	* @param networkId - Selected network ID
+	* @param ecosystem - Ecosystem the network belongs to (e.g., 'evm', 'stellar')
+	*
+	* @example
+	* ```typescript
+	* AnalyticsService.trackNetworkSelection('ethereum-mainnet', 'evm');
+	* ```
+	*/
+	static trackNetworkSelection(networkId, ecosystem) {
+		this.trackEvent("network_selected", {
+			network_id: networkId,
+			ecosystem
+		});
+	}
+	/**
+	* Load the Google Analytics gtag script
+	* @private
+	*/
+	static loadGtagScript(tagId) {
+		if (document.querySelector(`script[src*="gtag/js?id=${tagId}"]`)) return;
+		if (!window.dataLayer) window.dataLayer = [];
+		window.gtag = window.gtag || function gtag() {
+			window.dataLayer.push(arguments);
+		};
+		const script = document.createElement("script");
+		script.async = true;
+		script.src = `https://www.googletagmanager.com/gtag/js?id=${tagId}`;
+		document.head.appendChild(script);
+	}
+	/**
+	* Initialize gtag with configuration
+	* @private
+	*/
+	static initializeGtag(tagId) {
+		if (typeof window.gtag === "function") {
+			window.gtag("js", /* @__PURE__ */ new Date());
+			window.gtag("config", tagId);
+		}
+	}
+};
+
+//#endregion
+//#region src/deepLink.ts
+/**
+* Parses URL query parameters into a key-value object.
+* @returns Object containing all URL query parameters
+*/
+function parseDeepLink() {
+	const params = new URLSearchParams(window.location.search);
+	const result = {};
+	params.forEach((value, key) => {
+		result[key] = value;
+	});
+	return result;
+}
+/**
+* Gets the forced service from deep link parameters.
+* @param params - Deep link parameters object
+* @returns Service name if specified, null otherwise
+*/
+function getForcedService(params) {
+	return params.service ?? null;
+}
+/**
+* Computes the effective provider preference based on priority order.
+* @param input - Configuration object with provider options
+* @returns The effective provider and its source
+*/
+function computeEffectiveProviderPreference(input) {
+	if (input.forcedService && input.forcedService.length > 0) return {
+		effectiveProvider: input.forcedService,
+		source: "urlForced"
+	};
+	if (input.uiSelection && input.uiSelection.length > 0) return {
+		effectiveProvider: input.uiSelection,
+		source: "ui"
+	};
+	if (input.appDefault && input.appDefault.length > 0) return {
+		effectiveProvider: input.appDefault,
+		source: "appConfig"
+	};
+	return {
+		effectiveProvider: input.adapterDefaultOrder[0],
+		source: "adapterDefault"
+	};
+}
+
+//#endregion
+//#region src/sanitize.ts
+/**
+* Minimal HTML sanitizer for client-side rendering of adapter-provided notes.
+*
+* - Strips <script>/<style> blocks and closing tags
+* - Removes inline event handlers (on*)
+* - Neutralizes javascript: URLs in href/src
+* - Whitelists a small set of tags: a,b,strong,i,em,code,br,ul,ol,li,p
+*
+* This utility is intentionally small and dependency-free. If we decide to
+* allow richer HTML, we can swap this implementation with a vetted library
+* (e.g., DOMPurify) behind the same function signature.
+*/
+function sanitizeHtml(html) {
+	if (!html) return "";
+	let out = html.replace(/<\/(?:script|style)>/gi, "").replace(/<(?:script|style)[\s\S]*?>[\s\S]*?<\/(?:script|style)>/gi, "");
+	out = out.replace(/\son[a-z]+\s*=\s*"[^"]*"/gi, "");
+	out = out.replace(/\son[a-z]+\s*=\s*'[^']*'/gi, "");
+	out = out.replace(/\son[a-z]+\s*=\s*[^\s>]+/gi, "");
+	out = out.replace(/(href|src)\s*=\s*"javascript:[^"]*"/gi, "$1=\"#\"");
+	out = out.replace(/(href|src)\s*=\s*'javascript:[^']*'/gi, "$1=\"#\"");
+	out = out.replace(/<(?!\/?(?:a|b|strong|i|em|code|br|ul|ol|li|p)\b)[^>]*>/gi, "");
+	return out;
+}
+
+//#endregion
+//#region src/access/snapshot.ts
+/**
+* Validates an access snapshot structure
+* @param snapshot The snapshot to validate
+* @returns True if valid, false otherwise
+*/
+function validateSnapshot(snapshot) {
+	if (!snapshot || typeof snapshot !== "object") return false;
+	if (!Array.isArray(snapshot.roles)) return false;
+	const roleIds = /* @__PURE__ */ new Set();
+	for (const roleAssignment of snapshot.roles) {
+		if (!roleAssignment || typeof roleAssignment !== "object") return false;
+		if (!roleAssignment.role || typeof roleAssignment.role !== "object") return false;
+		const roleId = roleAssignment.role.id;
+		if (!roleId || typeof roleId !== "string" || roleId.trim() === "") return false;
+		if (roleIds.has(roleId)) return false;
+		roleIds.add(roleId);
+		if (!Array.isArray(roleAssignment.members)) return false;
+		const memberSet = /* @__PURE__ */ new Set();
+		for (const member of roleAssignment.members) {
+			if (typeof member !== "string" || member.trim() === "") return false;
+			if (memberSet.has(member)) return false;
+			memberSet.add(member);
+		}
+	}
+	if (snapshot.ownership !== void 0) {
+		if (!snapshot.ownership || typeof snapshot.ownership !== "object") return false;
+		if (snapshot.ownership.owner !== null && (typeof snapshot.ownership.owner !== "string" || snapshot.ownership.owner.trim() === "")) return false;
+	}
+	return true;
+}
+/**
+* Serializes an access snapshot to JSON string
+* @param snapshot The snapshot to serialize
+* @returns JSON string representation
+* @throws Error if snapshot is invalid
+*/
+function serializeSnapshot(snapshot) {
+	if (!validateSnapshot(snapshot)) throw new Error("Invalid snapshot structure");
+	return JSON.stringify(snapshot, null, 2);
+}
+/**
+* Deserializes a JSON string to an access snapshot
+* @param json The JSON string to deserialize
+* @returns Access snapshot object
+* @throws Error if JSON is invalid or snapshot structure is invalid
+*/
+function deserializeSnapshot(json) {
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch (error) {
+		throw new Error(`Invalid JSON: ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+	if (!validateSnapshot(parsed)) throw new Error("Invalid snapshot structure after deserialization");
+	return parsed;
+}
+/**
+* Creates an empty snapshot
+* @returns Empty snapshot with no roles and no ownership
+*/
+function createEmptySnapshot() {
+	return { roles: [] };
+}
+/**
+* Finds a role assignment by role ID
+* @param snapshot The snapshot to search
+* @param roleId The role ID to find
+* @returns The role assignment if found, undefined otherwise
+*/
+function findRoleAssignment(snapshot, roleId) {
+	return snapshot.roles.find((assignment) => assignment.role.id === roleId);
+}
+/**
+* Checks if a snapshot has any roles
+* @param snapshot The snapshot to check
+* @returns True if snapshot has at least one role assignment
+*/
+function hasRoles(snapshot) {
+	return snapshot.roles.length > 0;
+}
+/**
+* Checks if a snapshot has ownership information
+* @param snapshot The snapshot to check
+* @returns True if snapshot has ownership information
+*/
+function hasOwnership(snapshot) {
+	return snapshot.ownership !== void 0 && snapshot.ownership !== null;
+}
+/**
+* Gets the total number of role members across all roles
+* @param snapshot The snapshot to count
+* @returns Total number of unique members across all roles
+*/
+function getTotalMemberCount(snapshot) {
+	const allMembers = /* @__PURE__ */ new Set();
+	for (const roleAssignment of snapshot.roles) for (const member of roleAssignment.members) allMembers.add(member);
+	return allMembers.size;
+}
+/**
+* Gets all unique members across all roles
+* @param snapshot The snapshot to extract members from
+* @returns Array of unique member addresses
+*/
+function getAllMembers(snapshot) {
+	const allMembers = /* @__PURE__ */ new Set();
+	for (const roleAssignment of snapshot.roles) for (const member of roleAssignment.members) allMembers.add(member);
+	return Array.from(allMembers);
+}
+/**
+* Compares two snapshots and returns differences
+* @param snapshot1 First snapshot
+* @param snapshot2 Second snapshot
+* @returns Object describing differences
+*/
+function compareSnapshots(snapshot1, snapshot2) {
+	const rolesAdded = [];
+	const rolesRemoved = [];
+	const rolesModified = [];
+	const roleMap1 = /* @__PURE__ */ new Map();
+	const roleMap2 = /* @__PURE__ */ new Map();
+	for (const assignment of snapshot1.roles) roleMap1.set(assignment.role.id, assignment);
+	for (const assignment of snapshot2.roles) roleMap2.set(assignment.role.id, assignment);
+	for (const [roleId, assignment] of roleMap2) if (!roleMap1.has(roleId)) rolesAdded.push(assignment);
+	for (const [roleId, assignment] of roleMap1) if (!roleMap2.has(roleId)) rolesRemoved.push(assignment);
+	for (const [roleId, assignment1] of roleMap1) {
+		const assignment2 = roleMap2.get(roleId);
+		if (assignment2) {
+			const members1 = new Set(assignment1.members);
+			const members2 = new Set(assignment2.members);
+			const membersAdded = assignment2.members.filter((m) => !members1.has(m));
+			const membersRemoved = assignment1.members.filter((m) => !members2.has(m));
+			if (membersAdded.length > 0 || membersRemoved.length > 0) rolesModified.push({
+				role: assignment1.role,
+				membersAdded,
+				membersRemoved
+			});
+		}
+	}
+	return {
+		rolesAdded,
+		rolesRemoved,
+		rolesModified,
+		ownershipChanged: snapshot1.ownership?.owner !== snapshot2.ownership?.owner
+	};
+}
+
+//#endregion
+//#region src/access/errors.ts
+/**
+* Type guard to check if an error is an AccessControlError
+*
+* @param error The error to check
+* @returns True if the error has the AccessControlError structure
+*
+* @example
+* ```typescript
+* try {
+*   await service.grantRole(...);
+* } catch (error) {
+*   if (isAccessControlError(error)) {
+*     console.log('Access control error:', error.contractAddress);
+*   }
+* }
+* ```
+*/
+function isAccessControlError(error) {
+	return error instanceof Error && "contractAddress" in error && (typeof error.contractAddress === "string" || error.contractAddress === void 0);
+}
+/**
+* Helper to safely extract error message from unknown error type
+*
+* @param error The error to extract message from
+* @returns The error message string
+*
+* @example
+* ```typescript
+* try {
+*   await someOperation();
+* } catch (error) {
+*   const message = getErrorMessage(error);
+*   logger.error('Operation failed:', message);
+* }
+* ```
+*/
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+/**
+* Helper to create a user-friendly error message with full context
+*
+* This function formats an AccessControlError into a readable multi-line message
+* that includes all relevant context (contract address, roles, operations, etc.).
+*
+* @param error The AccessControlError to format
+* @returns Formatted error message string with all context
+*
+* @example
+* ```typescript
+* import { PermissionDenied } from '@openzeppelin/ui-types';
+* import { formatAccessControlError } from '@openzeppelin/ui-utils';
+*
+* try {
+*   await service.grantRole(...);
+* } catch (error) {
+*   if (error instanceof PermissionDenied) {
+*     const formatted = formatAccessControlError(error);
+*     showErrorToUser(formatted);
+*   }
+* }
+* ```
+*
+* Output format:
+* ```
+* [ErrorName] Error message
+* Contract: 0x123...
+* [Additional context based on error type]
+* ```
+*/
+function formatAccessControlError(error) {
+	let message = `[${error.name}] ${error.message}`;
+	if (error.contractAddress) message += `\nContract: ${error.contractAddress}`;
+	const errorWithProperties = error;
+	if (error.name === "PermissionDenied") {
+		if (errorWithProperties.requiredRole) message += `\nRequired Role: ${errorWithProperties.requiredRole}`;
+		if (errorWithProperties.callerAddress) message += `\nCaller: ${errorWithProperties.callerAddress}`;
+	} else if (error.name === "IndexerUnavailable") {
+		if (errorWithProperties.networkId) message += `\nNetwork: ${errorWithProperties.networkId}`;
+		if (errorWithProperties.endpointUrl) message += `\nEndpoint: ${errorWithProperties.endpointUrl}`;
+	} else if (error.name === "ConfigurationInvalid") {
+		if (errorWithProperties.configField) message += `\nInvalid Field: ${errorWithProperties.configField}`;
+		if (errorWithProperties.providedValue !== void 0) message += `\nProvided Value: ${JSON.stringify(errorWithProperties.providedValue)}`;
+	} else if (error.name === "OperationFailed") {
+		if (errorWithProperties.operation) message += `\nOperation: ${errorWithProperties.operation}`;
+		if (errorWithProperties.cause) message += `\nCause: ${errorWithProperties.cause.message}`;
+	} else if (error.name === "UnsupportedContractFeatures") {
+		if (errorWithProperties.missingFeatures && Array.isArray(errorWithProperties.missingFeatures)) message += `\nMissing Features: ${errorWithProperties.missingFeatures.join(", ")}`;
+	}
+	return message;
+}
+
+//#endregion
+exports.AnalyticsService = AnalyticsService;
+exports.AppConfigService = AppConfigService;
+exports.DEFAULT_CONCURRENCY_LIMIT = DEFAULT_CONCURRENCY_LIMIT;
+exports.UserExplorerConfigService = UserExplorerConfigService;
+exports.UserNetworkServiceConfigService = UserNetworkServiceConfigService;
+exports.UserRpcConfigService = UserRpcConfigService;
+exports.addressesEqual = addressesEqual;
+exports.appConfigService = appConfigService;
+exports.base64ToBytes = base64ToBytes;
+exports.buildRequiredInputSnapshot = buildRequiredInputSnapshot;
+exports.bytesToHex = bytesToHex;
+exports.cn = cn;
+exports.compareSnapshots = compareSnapshots;
+exports.computeEffectiveProviderPreference = computeEffectiveProviderPreference;
+exports.createEmptySnapshot = createEmptySnapshot;
+exports.delay = delay;
+exports.deserializeSnapshot = deserializeSnapshot;
+exports.detectBytesEncoding = detectBytesEncoding;
+exports.enhanceNumericValidation = enhanceNumericValidation;
+exports.findRoleAssignment = findRoleAssignment;
+exports.formatAccessControlError = formatAccessControlError;
+exports.formatTimestamp = formatTimestamp;
+exports.generateId = generateId;
+exports.getAllMembers = getAllMembers;
+exports.getBytesSize = getBytesSize;
+exports.getDefaultValueForType = getDefaultValueForType;
+exports.getErrorMessage = getErrorMessage;
+exports.getForcedService = getForcedService;
+exports.getInvalidUrlMessage = getInvalidUrlMessage;
+exports.getMissingRequiredContractInputs = getMissingRequiredContractInputs;
+exports.getTotalMemberCount = getTotalMemberCount;
+exports.hasMissingRequiredContractInputs = hasMissingRequiredContractInputs;
+exports.hasOwnership = hasOwnership;
+exports.hasRoles = hasRoles;
+exports.hexToBytes = hexToBytes;
+exports.isAccessControlError = isAccessControlError;
+exports.isDevelopmentOrTestEnvironment = isDevelopmentOrTestEnvironment;
+exports.isPlainObject = isPlainObject;
+exports.isProductionEnvironment = isProductionEnvironment;
+exports.isRecordWithProperties = isRecordWithProperties;
+exports.isValidUrl = isValidUrl;
+exports.logger = logger;
+exports.normalizeAddress = normalizeAddress;
+exports.parseDeepLink = parseDeepLink;
+exports.promiseAllSettledWithLimit = promiseAllSettledWithLimit;
+exports.promiseAllWithLimit = promiseAllWithLimit;
+exports.rateLimitedBatch = rateLimitedBatch;
+exports.requiredSnapshotsEqual = requiredSnapshotsEqual;
+exports.routerService = routerService;
+exports.sanitizeHtml = sanitizeHtml;
+exports.serializeSnapshot = serializeSnapshot;
+exports.simpleHash = simpleHash;
+exports.stringToBytes = stringToBytes;
+exports.truncateMiddle = truncateMiddle;
+exports.userExplorerConfigService = userExplorerConfigService;
+exports.userNetworkServiceConfigService = userNetworkServiceConfigService;
+exports.userRpcConfigService = userRpcConfigService;
+exports.validateBytes = validateBytes;
+exports.validateBytesSimple = validateBytesSimple;
+exports.validateSnapshot = validateSnapshot;
+exports.withTimeout = withTimeout;
+//# sourceMappingURL=index.cjs.map