@openzeppelin/ui-react 1.2.0 → 2.0.1

package/dist/index.cjs

@@ -32,111 +32,159 @@ let react_jsx_runtime = require("react/jsx-runtime");
 let _openzeppelin_ui_components = require("@openzeppelin/ui-components");
 
 //#region src/version.ts
-const VERSION = "1.2.0";
+const VERSION = "2.0.1";
 
 //#endregion
 //#region src/hooks/AdapterContext.tsx
 /**
 * AdapterContext.tsx
 *
-* This file defines the React Context used for the adapter singleton pattern.
+* This file defines the React Context used for the runtime singleton pattern.
 * It provides types and the context definition, but the actual implementation
-* is in the AdapterProvider component.
+* is in the `RuntimeProvider` component.
 *
-* The adapter singleton pattern ensures that only one adapter instance exists
+* The runtime singleton pattern ensures that only one runtime instance exists
 * per network configuration, which is critical for consistent wallet connection
 * state across the application.
 */
 /**
-* The React Context that provides adapter registry access throughout the app
-* Components can access this through the useAdapterContext hook
+* The React Context that provides runtime registry access throughout the app.
+* Components can access this through the `useRuntimeContext` hook.
 */
-const AdapterContext = (0, react.createContext)(null);
+const RuntimeContext = (0, react.createContext)(null);
 
 //#endregion
 //#region src/hooks/AdapterProvider.tsx
 /**
-* AdapterProvider.tsx
+* RuntimeProvider.tsx
 *
-* This file implements the Adapter Provider component which manages a registry of
-* adapter instances. It's a key part of the adapter singleton pattern which ensures
-* that only one adapter instance exists per network configuration.
+* This file implements the Runtime Provider component which manages a registry of
+* runtime instances. It's a key part of the runtime singleton pattern which ensures
+* that only one runtime instance exists per network configuration.
 *
-* The adapter registry is shared across the application via React Context, allowing
-* components to access the same adapter instances and maintain consistent wallet
+* The runtime registry is shared across the application via React Context, allowing
+* components to access the same runtime instances and maintain consistent wallet
 * connection state.
 *
 * IMPORTANT: This implementation needs special care to avoid React state update errors
 * during component rendering. Direct state updates during render are not allowed, which
-* is why adapter loading is controlled carefully.
+* is why runtime loading is controlled carefully.
 */
 /**
-* Provider component that manages adapter instances centrally
-* to avoid creating multiple instances of the same adapter.
+* Provider component that manages runtime instances centrally
+* to avoid creating multiple instances of the same runtime.
 *
 * This component:
-* 1. Maintains a registry of adapter instances by network ID
-* 2. Tracks loading states for adapters being initialized
-* 3. Provides a function to get or load adapters for specific networks
-* 4. Ensures adapter instances are reused when possible
+* 1. Maintains a registry of runtime instances by network ID
+* 2. Tracks loading states for runtimes being initialized
+* 3. Provides a function to get or load runtimes for specific networks
+* 4. Ensures runtime instances are reused when possible
 */
-function AdapterProvider({ children, resolveAdapter }) {
-	const [adapterRegistry, setAdapterRegistry] = (0, react.useState)({});
+function RuntimeProvider({ children, resolveRuntime }) {
+	const [runtimeRegistry, setRuntimeRegistry] = (0, react.useState)({});
 	const [loadingNetworks, setLoadingNetworks] = (0, react.useState)(/* @__PURE__ */ new Set());
+	const runtimeRegistryRef = (0, react.useRef)(runtimeRegistry);
+	const failedNetworksRef = (0, react.useRef)(/* @__PURE__ */ new Set());
 	(0, react.useEffect)(() => {
-		const adapterCount = Object.keys(adapterRegistry).length;
-		if (adapterCount > 0) _openzeppelin_ui_utils.logger.info("AdapterProvider", `Registry contains ${adapterCount} adapters:`, {
-			networkIds: Object.keys(adapterRegistry),
+		runtimeRegistryRef.current = runtimeRegistry;
+	}, [runtimeRegistry]);
+	(0, react.useEffect)(() => {
+		failedNetworksRef.current = /* @__PURE__ */ new Set();
+	}, [resolveRuntime]);
+	(0, react.useEffect)(() => {
+		return () => {
+			Object.values(runtimeRegistryRef.current).forEach((runtime) => {
+				runtime.dispose();
+			});
+		};
+	}, []);
+	(0, react.useEffect)(() => {
+		const runtimeCount = Object.keys(runtimeRegistry).length;
+		if (runtimeCount > 0) _openzeppelin_ui_utils.logger.info("RuntimeProvider", `Registry contains ${runtimeCount} runtimes:`, {
+			networkIds: Object.keys(runtimeRegistry),
 			loadingCount: loadingNetworks.size,
 			loadingNetworkIds: Array.from(loadingNetworks)
 		});
-	}, [adapterRegistry, loadingNetworks]);
+	}, [runtimeRegistry, loadingNetworks]);
+	/**
+	* Evicts a runtime from the registry by network ID and disposes it.
+	* This is the safe counterpart to `getRuntimeForNetwork`: callers should only
+	* release a runtime after they have already promoted its replacement.
+	*
+	* Disposal is deferred to the next macrotask so React's commit phase
+	* (including development-mode prop diffing) can finish reading the old
+	* runtime's properties without hitting the RuntimeDisposedError proxy trap.
+	*/
+	const releaseRuntime = (0, react.useCallback)((networkId) => {
+		const runtime = runtimeRegistryRef.current[networkId];
+		if (!runtime) return;
+		_openzeppelin_ui_utils.logger.info("RuntimeProvider", `Releasing runtime for network ${networkId}`);
+		setRuntimeRegistry((prev) => {
+			const next = { ...prev };
+			delete next[networkId];
+			return next;
+		});
+		setTimeout(() => {
+			try {
+				runtime.dispose();
+			} catch (error) {
+				_openzeppelin_ui_utils.logger.error("RuntimeProvider", `Error disposing runtime for network ${networkId}:`, error);
+			}
+		}, 0);
+	}, []);
 	/**
-	* Function to get or create an adapter for a network
+	* Function to get or create a runtime for a network
 	*
-	* IMPORTANT: The actual adapter loading is handled in the useConfiguredAdapterSingleton hook
-	* to avoid React state updates during render, which would cause errors.
+	* IMPORTANT: Runtime loading is coordinated carefully to avoid React state updates
+	* during render, which would cause errors.
 	*
 	* This function:
-	* 1. Returns existing adapters immediately if available
-	* 2. Reports loading state for adapters being initialized
-	* 3. Initiates adapter loading when needed
+	* 1. Returns existing runtimes immediately if available
+	* 2. Reports loading state for runtimes being initialized
+	* 3. Initiates runtime loading when needed
 	*/
-	const getAdapterForNetwork = (0, react.useCallback)((networkConfig) => {
+	const getRuntimeForNetwork = (0, react.useCallback)((networkConfig) => {
 		if (!networkConfig) return {
-			adapter: null,
+			runtime: null,
 			isLoading: false
 		};
 		const networkId = networkConfig.id;
-		_openzeppelin_ui_utils.logger.debug("AdapterProvider", `Adapter requested for network ${networkId}`);
-		if (adapterRegistry[networkId]) {
-			_openzeppelin_ui_utils.logger.debug("AdapterProvider", `Using existing adapter for network ${networkId}`);
+		_openzeppelin_ui_utils.logger.debug("RuntimeProvider", `Runtime requested for network ${networkId}`);
+		if (runtimeRegistry[networkId]) {
+			_openzeppelin_ui_utils.logger.debug("RuntimeProvider", `Using existing runtime for network ${networkId}`);
 			return {
-				adapter: adapterRegistry[networkId],
+				runtime: runtimeRegistry[networkId],
 				isLoading: false
 			};
 		}
 		if (loadingNetworks.has(networkId)) {
-			_openzeppelin_ui_utils.logger.debug("AdapterProvider", `Adapter for network ${networkId} is currently loading`);
+			_openzeppelin_ui_utils.logger.debug("RuntimeProvider", `Runtime for network ${networkId} is currently loading`);
 			return {
-				adapter: null,
+				runtime: null,
 				isLoading: true
 			};
 		}
+		if (failedNetworksRef.current.has(networkId)) {
+			_openzeppelin_ui_utils.logger.debug("RuntimeProvider", `Runtime for network ${networkId} previously failed; skipping retry`);
+			return {
+				runtime: null,
+				isLoading: false
+			};
+		}
 		setLoadingNetworks((prev) => {
 			const newSet = new Set(prev);
 			newSet.add(networkId);
 			return newSet;
 		});
-		_openzeppelin_ui_utils.logger.info("AdapterProvider", `Starting adapter initialization for network ${networkId} (${networkConfig.name})`);
-		resolveAdapter(networkConfig).then((adapter) => {
-			_openzeppelin_ui_utils.logger.info("AdapterProvider", `Adapter for network ${networkId} loaded successfully`, {
-				type: adapter.constructor.name,
-				objectId: Object.prototype.toString.call(adapter)
+		_openzeppelin_ui_utils.logger.info("RuntimeProvider", `Starting runtime initialization for network ${networkId} (${networkConfig.name})`);
+		resolveRuntime(networkConfig).then((runtime) => {
+			_openzeppelin_ui_utils.logger.info("RuntimeProvider", `Runtime for network ${networkId} loaded successfully`, {
+				type: runtime.constructor.name,
+				objectId: Object.prototype.toString.call(runtime)
 			});
-			setAdapterRegistry((prev) => ({
+			setRuntimeRegistry((prev) => ({
 				...prev,
-				[networkId]: adapter
+				[networkId]: runtime
 			}));
 			setLoadingNetworks((prev) => {
 				const newSet = new Set(prev);
@@ -144,7 +192,8 @@ function AdapterProvider({ children, resolveAdapter }) {
 				return newSet;
 			});
 		}).catch((error) => {
-			_openzeppelin_ui_utils.logger.error("AdapterProvider", `Error loading adapter for network ${networkId}:`, error);
+			_openzeppelin_ui_utils.logger.error("RuntimeProvider", `Error loading runtime for network ${networkId}:`, error);
+			failedNetworksRef.current.add(networkId);
 			setLoadingNetworks((prev) => {
 				const newSet = new Set(prev);
 				newSet.delete(networkId);
@@ -152,16 +201,19 @@ function AdapterProvider({ children, resolveAdapter }) {
 			});
 		});
 		return {
-			adapter: null,
+			runtime: null,
 			isLoading: true
 		};
 	}, [
-		adapterRegistry,
+		runtimeRegistry,
 		loadingNetworks,
-		resolveAdapter
+		resolveRuntime
 	]);
-	const contextValue = (0, react.useMemo)(() => ({ getAdapterForNetwork }), [getAdapterForNetwork]);
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AdapterContext.Provider, {
+	const contextValue = (0, react.useMemo)(() => ({
+		getRuntimeForNetwork,
+		releaseRuntime
+	}), [getRuntimeForNetwork, releaseRuntime]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RuntimeContext.Provider, {
 		value: contextValue,
 		children
 	});
@@ -179,7 +231,7 @@ function AdapterProvider({ children, resolveAdapter }) {
 * consuming package's bundle. This creates MULTIPLE instances of this module:
 *
 * 1. The app's direct import → packages/react/dist/index.js
-* 2. The adapter's inlined copy → .vite/deps/@openzeppelin_ui-builder-adapter-evm.js
+* 2. The adapter package's inlined copy → .vite/deps/@openzeppelin_adapter_evm.js
 *
 * Since React contexts use referential identity, these two module instances have
 * DIFFERENT context objects. When the adapter's components call useWalletState(),
@@ -241,54 +293,88 @@ function useWalletState() {
 /**
 * useAdapterContext.ts
 *
-* This file provides a hook to access the AdapterContext throughout the application.
-* It's a critical part of the adapter singleton pattern, allowing components to
-* access the centralized adapter registry.
+* This file provides a hook to access the runtime context throughout the application.
+* It's a critical part of the runtime singleton pattern, allowing components to
+* access the centralized runtime registry.
 *
-* The adapter singleton pattern ensures:
-* - Only one adapter instance exists per network
+* The runtime singleton pattern ensures:
+* - Only one runtime instance exists per network
 * - Wallet connection state is consistent across the app
-* - Better performance by eliminating redundant adapter initialization
+* - Better performance by eliminating redundant runtime initialization
 */
 /**
-* Hook to access the adapter context
+* Hook to access the runtime context
 *
-* This hook provides access to the getAdapterForNetwork function which
-* retrieves or creates adapter instances from the singleton registry.
+* This hook provides access to the `getRuntimeForNetwork` function which
+* retrieves or creates runtime instances from the singleton registry.
 *
-* Components should typically use useConfiguredAdapterSingleton instead
+* Components should typically use the higher-level wallet/runtime hooks instead
 * of this hook directly, as it handles React state update timing properly.
 *
-* @throws Error if used outside of an AdapterProvider context
-* @returns The adapter context value
+* @throws Error if used outside of a RuntimeProvider context
+* @returns The runtime context value
 */
-function useAdapterContext() {
-	const context = (0, react.useContext)(AdapterContext);
-	if (!context) throw new Error("useAdapterContext must be used within an AdapterProvider");
+function useRuntimeContext() {
+	const context = (0, react.useContext)(RuntimeContext);
+	if (!context) throw new Error("useRuntimeContext must be used within a RuntimeProvider");
 	return context;
 }
 
+//#endregion
+//#region src/hooks/walletSessionRegistry.ts
+/**
+* Returns the cached wallet session for an ecosystem, if present.
+*
+* @param registry - Current internal wallet session registry.
+* @param ecosystem - Ecosystem key to resolve.
+* @returns The cached session entry or `null` when the ecosystem has not been configured yet.
+*/
+function getWalletSession(registry, ecosystem) {
+	if (!ecosystem) return null;
+	return registry[ecosystem] ?? null;
+}
+/**
+* Inserts or replaces the cached wallet session for a single ecosystem.
+*
+* @param registry - Current internal wallet session registry.
+* @param session - Session entry to cache.
+* @returns A new registry object containing the upserted ecosystem session.
+*/
+function upsertWalletSession(registry, session) {
+	return {
+		...registry,
+		[session.ecosystem]: session
+	};
+}
+
 //#endregion
 //#region src/hooks/WalletStateProvider.tsx
 /**
-* Configures the adapter's UI kit and returns the UI provider component and hooks.
+* Configures the runtime's UI kit capability and returns the ecosystem session artifacts.
 */
-async function configureAdapterUiKit(adapter, loadConfigModule, programmaticOverrides = {}) {
+async function configureRuntimeUiKit(runtime, loadConfigModule, programmaticOverrides = {}) {
+	const uiKit = runtime.uiKit;
+	if (!uiKit) return {
+		providerComponent: null,
+		hooks: null
+	};
 	try {
-		if (typeof adapter.configureUiKit === "function") {
-			_openzeppelin_ui_utils.logger.info("[WSP configureAdapterUiKit] Calling configureUiKit for adapter:", adapter?.networkConfig?.id);
-			await adapter.configureUiKit(programmaticOverrides, { loadUiKitNativeConfig: loadConfigModule });
-			_openzeppelin_ui_utils.logger.info("[WSP configureAdapterUiKit] configureUiKit completed for adapter:", adapter?.networkConfig?.id);
+		const hasUiKitOverride = Object.keys(programmaticOverrides).length > 0;
+		if (typeof uiKit.configureUiKit === "function") {
+			const nextUiKitConfig = { ...programmaticOverrides };
+			_openzeppelin_ui_utils.logger.info("[WSP configureRuntimeUiKit]", hasUiKitOverride ? `Applying explicit UI kit overrides for runtime: ${runtime.networkConfig.id}` : `Initializing runtime UI kit from adapter/app defaults for runtime: ${runtime.networkConfig.id}`);
+			await uiKit.configureUiKit(nextUiKitConfig, { loadUiKitNativeConfig: loadConfigModule });
+			_openzeppelin_ui_utils.logger.info("[WSP configureRuntimeUiKit] configureUiKit completed for runtime:", runtime.networkConfig.id);
 		}
-		const providerComponent = adapter.getEcosystemReactUiContextProvider?.() || null;
-		const hooks = adapter.getEcosystemReactHooks?.() || null;
-		_openzeppelin_ui_utils.logger.info("[WSP configureAdapterUiKit]", "UI provider and hooks retrieved successfully.");
+		const providerComponent = uiKit.getEcosystemReactUiContextProvider?.() || null;
+		const hooks = uiKit.getEcosystemReactHooks?.() || null;
+		_openzeppelin_ui_utils.logger.info("[WSP configureRuntimeUiKit]", "UI provider and hooks retrieved successfully.");
 		return {
 			providerComponent,
 			hooks
 		};
 	} catch (error) {
-		_openzeppelin_ui_utils.logger.error("[WSP configureAdapterUiKit]", "Error during adapter UI setup:", error);
+		_openzeppelin_ui_utils.logger.error("[WSP configureRuntimeUiKit]", "Error during runtime UI setup:", error);
 		throw error;
 	}
 }
@@ -298,26 +384,28 @@ async function configureAdapterUiKit(adapter, loadConfigModule, programmaticOver
 * It is responsible for:
 * 1. Managing the globally selected active network ID (`activeNetworkId`).
 * 2. Deriving the full `NetworkConfig` object (`activeNetworkConfig`) for the active network.
-* 3. Fetching and providing the corresponding `ContractAdapter` instance (`activeAdapter`) for the active network,
-*    leveraging the `AdapterProvider` to ensure adapter singletons.
-* 4. Storing and providing the `EcosystemSpecificReactHooks` (`walletFacadeHooks`) from the active adapter.
-* 5. Rendering the adapter-specific UI context provider (e.g., WagmiProvider for EVM) around its children,
-*    which is essential for the facade hooks to function correctly.
+* 3. Fetching and providing the corresponding `EcosystemRuntime` (`activeRuntime`) for the active network,
+*    leveraging the `RuntimeProvider` to ensure runtime singletons.
+* 4. Caching ecosystem-scoped wallet session artifacts (provider roots and facade hooks)
+*    independently from the network-scoped runtime.
+* 5. Rendering the active ecosystem wallet provider (e.g., WagmiProvider for EVM) around its
+*    children, which is essential for the facade hooks to function correctly.
 * 6. Providing a function (`setActiveNetworkId`) to change the globally active network.
 *
 * Consumers use the `useWalletState()` hook to access this global state.
-* It should be placed high in the component tree, inside an `<AdapterProvider>`.
+* It should be placed high in the component tree, inside a `<RuntimeProvider>`.
 */
 function WalletStateProvider({ children, initialNetworkId = null, getNetworkConfigById, loadConfigModule }) {
 	const [currentGlobalNetworkId, setCurrentGlobalNetworkIdState] = (0, react.useState)(initialNetworkId);
 	const [currentGlobalNetworkConfig, setCurrentGlobalNetworkConfig] = (0, react.useState)(null);
-	const [globalActiveAdapter, setGlobalActiveAdapter] = (0, react.useState)(null);
-	const [isGlobalAdapterLoading, setIsGlobalAdapterLoading] = (0, react.useState)(false);
-	const [walletFacadeHooks, setWalletFacadeHooks] = (0, react.useState)(null);
-	const [AdapterUiContextProviderToRender, setAdapterUiContextProviderToRender] = (0, react.useState)(null);
+	const [globalActiveRuntime, setGlobalActiveRuntime] = (0, react.useState)(null);
+	const [isGlobalRuntimeLoading, setIsGlobalRuntimeLoading] = (0, react.useState)(false);
+	const [walletSessionRegistry, setWalletSessionRegistry] = (0, react.useState)({});
+	const [activeWalletSessionEcosystem, setActiveWalletSessionEcosystem] = (0, react.useState)(null);
 	const [uiKitConfigVersion, setUiKitConfigVersion] = (0, react.useState)(0);
 	const [programmaticUiKitConfig, setProgrammaticUiKitConfig] = (0, react.useState)(void 0);
-	const { getAdapterForNetwork } = useAdapterContext();
+	const { getRuntimeForNetwork, releaseRuntime } = useRuntimeContext();
+	const promotedNetworkIdRef = (0, react.useRef)(null);
 	(0, react.useEffect)(() => {
 		const abortController = new AbortController();
 		async function fetchNetworkConfig() {
@@ -340,98 +428,115 @@ function WalletStateProvider({ children, initialNetworkId = null, getNetworkConf
 	}, [currentGlobalNetworkId, getNetworkConfigById]);
 	(0, react.useEffect)(() => {
 		const abortController = new AbortController();
-		async function loadAdapterAndConfigureUi() {
+		async function loadRuntimeAndConfigureUi() {
 			if (!currentGlobalNetworkConfig) {
 				if (!abortController.signal.aborted) {
-					setGlobalActiveAdapter(null);
-					setIsGlobalAdapterLoading(false);
-					setAdapterUiContextProviderToRender(null);
-					setWalletFacadeHooks(null);
+					const prevNetworkId = promotedNetworkIdRef.current;
+					setGlobalActiveRuntime(null);
+					setIsGlobalRuntimeLoading(false);
+					setActiveWalletSessionEcosystem(null);
+					if (prevNetworkId) {
+						releaseRuntime(prevNetworkId);
+						promotedNetworkIdRef.current = null;
+					}
 				}
 				return;
 			}
-			const { adapter: newAdapter, isLoading: newIsLoading } = getAdapterForNetwork(currentGlobalNetworkConfig);
+			const { runtime: newRuntime, isLoading: newIsLoading } = getRuntimeForNetwork(currentGlobalNetworkConfig);
 			if (abortController.signal.aborted) return;
-			setIsGlobalAdapterLoading(newIsLoading);
-			if (newAdapter && !newIsLoading) try {
-				const { providerComponent, hooks } = await configureAdapterUiKit(newAdapter, loadConfigModule, programmaticUiKitConfig);
+			setIsGlobalRuntimeLoading(newIsLoading);
+			if (newRuntime && !newIsLoading) try {
+				const { providerComponent, hooks } = await configureRuntimeUiKit(newRuntime, loadConfigModule, programmaticUiKitConfig);
 				if (!abortController.signal.aborted) {
-					setAdapterUiContextProviderToRender(() => providerComponent);
-					setWalletFacadeHooks(hooks);
-					setGlobalActiveAdapter(newAdapter);
+					const ecosystem = newRuntime.networkConfig.ecosystem;
+					const prevNetworkId = promotedNetworkIdRef.current;
+					const nextNetworkId = newRuntime.networkConfig.id;
+					setWalletSessionRegistry((prevRegistry) => upsertWalletSession(prevRegistry, {
+						ecosystem,
+						lastConfiguredNetworkId: nextNetworkId,
+						providerComponent,
+						hooks
+					}));
+					setGlobalActiveRuntime(newRuntime);
+					setActiveWalletSessionEcosystem(ecosystem);
+					promotedNetworkIdRef.current = nextNetworkId;
+					if (prevNetworkId && prevNetworkId !== nextNetworkId) releaseRuntime(prevNetworkId);
 				}
 			} catch (error) {
-				if (!abortController.signal.aborted) {
-					_openzeppelin_ui_utils.logger.error("[WSP loadAdapterAndConfigureUi]", "Error during adapter UI setup:", error);
-					setAdapterUiContextProviderToRender(null);
-					setWalletFacadeHooks(null);
-				}
+				if (!abortController.signal.aborted) _openzeppelin_ui_utils.logger.error("[WSP loadRuntimeAndConfigureUi]", "Error during runtime UI setup:", error);
 			}
-			else if (!newAdapter && !newIsLoading) {
+			else if (!newRuntime && !newIsLoading) {
 				if (!abortController.signal.aborted) {
-					setAdapterUiContextProviderToRender(null);
-					setWalletFacadeHooks(null);
-					setGlobalActiveAdapter(null);
+					const prevNetworkId = promotedNetworkIdRef.current;
+					setGlobalActiveRuntime(null);
+					setActiveWalletSessionEcosystem(null);
+					if (prevNetworkId) {
+						releaseRuntime(prevNetworkId);
+						promotedNetworkIdRef.current = null;
+					}
 				}
 			}
 		}
-		loadAdapterAndConfigureUi();
+		loadRuntimeAndConfigureUi();
 		return () => abortController.abort();
 	}, [
 		currentGlobalNetworkConfig,
-		getAdapterForNetwork,
+		getRuntimeForNetwork,
+		releaseRuntime,
 		loadConfigModule,
 		uiKitConfigVersion,
 		programmaticUiKitConfig
 	]);
 	/**
 	* Callback to set the globally active network ID.
-	* Also clears dependent states (config, adapter, hooks) if the network ID is cleared.
+	* Also clears dependent states if the network ID is cleared.
 	*/
 	const setActiveNetworkIdCallback = (0, react.useCallback)((networkId) => {
 		_openzeppelin_ui_utils.logger.info("WalletStateProvider", `Setting global network ID to: ${networkId}`);
 		setCurrentGlobalNetworkIdState(networkId);
 		if (!networkId) {
 			setCurrentGlobalNetworkConfig(null);
-			setGlobalActiveAdapter(null);
-			setIsGlobalAdapterLoading(false);
-			setWalletFacadeHooks(null);
+			setGlobalActiveRuntime(null);
+			setIsGlobalRuntimeLoading(false);
+			setActiveWalletSessionEcosystem(null);
 		}
 	}, []);
 	/**
-	* Callback to explicitly trigger a re-configuration of the active adapter's UI kit.
+	* Callback to explicitly trigger a re-configuration of the active runtime's UI kit.
 	* This is useful when a UI kit setting changes (e.g., via a wizard) without a network change.
 	*/
-	const reconfigureActiveAdapterUiKit = (0, react.useCallback)((uiKitConfig) => {
+	const reconfigureActiveUiKit = (0, react.useCallback)((uiKitConfig) => {
 		_openzeppelin_ui_utils.logger.info("WalletStateProvider", "Explicitly triggering UI kit re-configuration by bumping version.", uiKitConfig);
 		setProgrammaticUiKitConfig(uiKitConfig);
 		setUiKitConfigVersion((v) => v + 1);
 	}, [setProgrammaticUiKitConfig, setUiKitConfigVersion]);
+	const activeWalletSession = (0, react.useMemo)(() => getWalletSession(walletSessionRegistry, activeWalletSessionEcosystem), [walletSessionRegistry, activeWalletSessionEcosystem]);
+	const walletFacadeHooks = activeWalletSession?.hooks ?? null;
 	const contextValue = (0, react.useMemo)(() => ({
 		activeNetworkId: currentGlobalNetworkId,
 		setActiveNetworkId: setActiveNetworkIdCallback,
 		activeNetworkConfig: currentGlobalNetworkConfig,
-		activeAdapter: globalActiveAdapter,
-		isAdapterLoading: isGlobalAdapterLoading,
+		activeRuntime: globalActiveRuntime,
+		isRuntimeLoading: isGlobalRuntimeLoading,
 		walletFacadeHooks,
-		reconfigureActiveAdapterUiKit
+		reconfigureActiveUiKit
 	}), [
 		currentGlobalNetworkId,
 		setActiveNetworkIdCallback,
 		currentGlobalNetworkConfig,
-		globalActiveAdapter,
-		isGlobalAdapterLoading,
+		globalActiveRuntime,
+		isGlobalRuntimeLoading,
 		walletFacadeHooks,
-		reconfigureActiveAdapterUiKit
+		reconfigureActiveUiKit
 	]);
-	const ActualProviderToRender = AdapterUiContextProviderToRender;
+	const ActualProviderToRender = activeWalletSession?.providerComponent ?? null;
 	let childrenToRender;
 	if (ActualProviderToRender) {
-		const key = `${globalActiveAdapter?.networkConfig?.ecosystem || "unknown"}-${globalActiveAdapter?.networkConfig?.id || "unknown"}`;
-		_openzeppelin_ui_utils.logger.info("[WSP RENDER]", "Rendering adapter-provided UI context provider:", ActualProviderToRender.displayName || ActualProviderToRender.name || "UnknownComponent", "with key:", key);
+		const key = activeWalletSessionEcosystem || "unknown";
+		_openzeppelin_ui_utils.logger.debug("[WSP RENDER]", "Rendering runtime-provided UI context provider:", ActualProviderToRender.displayName || ActualProviderToRender.name || "UnknownComponent", "with key:", key);
 		childrenToRender = /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ActualProviderToRender, { children }, key);
 	} else {
-		_openzeppelin_ui_utils.logger.info("[WSP RENDER]", "No adapter UI context provider to render. Rendering direct children.");
+		_openzeppelin_ui_utils.logger.debug("[WSP RENDER]", "No runtime UI context provider to render. Rendering direct children.");
 		childrenToRender = children;
 	}
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WalletStateContext.Provider, {
@@ -575,14 +680,14 @@ const useAnalytics = () => {
 //#endregion
 //#region src/hooks/useWalletComponents.ts
 /**
-* Hook that provides direct access to wallet UI components from the active adapter.
+* Hook that provides direct access to wallet UI components from the active runtime.
 *
 * Use this hook when you need full control over the layout and composition of
 * wallet components. For standard layouts, prefer using `WalletConnectionUI`
 * with its props forwarding capabilities.
 *
-* @returns The wallet components object, or null if no adapter is active or
-*          the adapter doesn't provide wallet components.
+* @returns The wallet components object, or null if no runtime is active or
+*          the runtime doesn't provide wallet components.
 *
 * @example
 * ```tsx
@@ -617,10 +722,11 @@ const useAnalytics = () => {
 * ```
 */
 function useWalletComponents() {
-	const { activeAdapter } = useWalletState();
-	if (!activeAdapter || typeof activeAdapter.getEcosystemWalletComponents !== "function") return null;
+	const { activeNetworkConfig, activeRuntime, isRuntimeLoading } = useWalletState();
+	const activeUiKit = activeRuntime?.uiKit;
+	if (!!(isRuntimeLoading && activeRuntime?.networkConfig?.ecosystem && activeNetworkConfig?.ecosystem && activeRuntime.networkConfig.ecosystem !== activeNetworkConfig.ecosystem) || !activeUiKit || typeof activeUiKit.getEcosystemWalletComponents !== "function") return null;
 	try {
-		return activeAdapter.getEcosystemWalletComponents() ?? null;
+		return activeUiKit.getEcosystemWalletComponents() ?? null;
 	} catch {
 		return null;
 	}
@@ -630,6 +736,10 @@ function useWalletComponents() {
 //#region src/hooks/useDerivedAccountStatus.ts
 const defaultAccountStatus = {
 	isConnected: false,
+	isConnecting: false,
+	isDisconnected: true,
+	isReconnecting: false,
+	status: "disconnected",
 	address: void 0,
 	chainId: void 0
 };
@@ -644,6 +754,10 @@ function useDerivedAccountStatus() {
 	const accountHookOutput = walletFacadeHooks?.useAccount ? walletFacadeHooks.useAccount() : void 0;
 	if ((0, _openzeppelin_ui_utils.isRecordWithProperties)(accountHookOutput)) return {
 		isConnected: "isConnected" in accountHookOutput && typeof accountHookOutput.isConnected === "boolean" ? accountHookOutput.isConnected : defaultAccountStatus.isConnected,
+		isConnecting: "isConnecting" in accountHookOutput && typeof accountHookOutput.isConnecting === "boolean" ? accountHookOutput.isConnecting : defaultAccountStatus.isConnecting,
+		isDisconnected: "isDisconnected" in accountHookOutput && typeof accountHookOutput.isDisconnected === "boolean" ? accountHookOutput.isDisconnected : defaultAccountStatus.isDisconnected,
+		isReconnecting: "isReconnecting" in accountHookOutput && typeof accountHookOutput.isReconnecting === "boolean" ? accountHookOutput.isReconnecting : defaultAccountStatus.isReconnecting,
+		status: "status" in accountHookOutput && typeof accountHookOutput.status === "string" ? accountHookOutput.status : defaultAccountStatus.status,
 		address: "address" in accountHookOutput && typeof accountHookOutput.address === "string" ? accountHookOutput.address : defaultAccountStatus.address,
 		chainId: "chainId" in accountHookOutput && typeof accountHookOutput.chainId === "number" ? accountHookOutput.chainId : defaultAccountStatus.chainId
 	};
@@ -762,21 +876,21 @@ function useDerivedDisconnect() {
 * This hook detects that scenario and invokes a callback to re-queue the network switch.
 *
 * @param selectedNetworkConfigId - Currently selected network in the app
-* @param selectedAdapter - Currently active adapter instance
+* @param selectedCapability - Currently active wallet capability instance
 * @param networkToSwitchTo - Current network switch queue state (null if no switch pending)
 * @param onRequeueSwitch - Callback invoked when a network switch should be re-queued
 */
-function useWalletReconnectionHandler(selectedNetworkConfigId, selectedAdapter, networkToSwitchTo, onRequeueSwitch) {
+function useWalletReconnectionHandler(selectedNetworkConfigId, selectedCapability, networkToSwitchTo, onRequeueSwitch) {
 	const { isConnected, chainId: walletChainId } = useDerivedAccountStatus();
 	const prevConnectedRef = (0, react.useRef)(isConnected);
 	(0, react.useEffect)(() => {
 		const isReconnection = !prevConnectedRef.current && isConnected;
 		prevConnectedRef.current = isConnected;
-		if (!isReconnection || !selectedNetworkConfigId || !selectedAdapter) return;
+		if (!isReconnection || !selectedNetworkConfigId || !selectedCapability) return;
 		if (networkToSwitchTo === selectedNetworkConfigId) return;
-		const adapterConfig = selectedAdapter.networkConfig;
-		if (!("chainId" in adapterConfig) || !walletChainId) return;
-		const targetChainId = Number(adapterConfig.chainId);
+		const selectedNetworkConfig = selectedCapability.networkConfig;
+		if (!("chainId" in selectedNetworkConfig) || !walletChainId) return;
+		const targetChainId = Number(selectedNetworkConfig.chainId);
 		if (walletChainId !== targetChainId) {
 			_openzeppelin_ui_utils.logger.info("useWalletReconnectionHandler", `Wallet reconnected with chain ${walletChainId}, but selected network requires ${targetChainId}. Re-queueing switch.`);
 			onRequeueSwitch(selectedNetworkConfigId);
@@ -785,7 +899,7 @@ function useWalletReconnectionHandler(selectedNetworkConfigId, selectedAdapter,
 		isConnected,
 		walletChainId,
 		selectedNetworkConfigId,
-		selectedAdapter,
+		selectedCapability,
 		networkToSwitchTo,
 		onRequeueSwitch
 	]);
@@ -817,37 +931,20 @@ function useWalletReconnectionHandler(selectedNetworkConfigId, selectedAdapter,
 */
 const WalletConnectionUI = ({ className, connectButtonProps, accountDisplayProps, networkSwitcherProps }) => {
 	const [isError, setIsError] = (0, react.useState)(false);
-	const { activeAdapter, walletFacadeHooks } = useWalletState();
-	(0, react.useEffect)(() => {
-		_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] State from useWalletState:", {
-			adapterId: activeAdapter?.networkConfig.id,
-			hasFacadeHooks: !!walletFacadeHooks
-		});
-	}, [activeAdapter, walletFacadeHooks]);
+	const { activeNetworkConfig, activeRuntime, isRuntimeLoading } = useWalletState();
+	const activeUiKit = activeRuntime?.uiKit;
+	if (!!(isRuntimeLoading && activeRuntime?.networkConfig?.ecosystem && activeNetworkConfig?.ecosystem && activeRuntime.networkConfig.ecosystem !== activeNetworkConfig.ecosystem)) return null;
 	const walletComponents = (() => {
-		if (!activeAdapter || typeof activeAdapter.getEcosystemWalletComponents !== "function") {
-			_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] No activeAdapter or getEcosystemWalletComponents method, returning null.");
-			return null;
-		}
+		if (!activeUiKit || typeof activeUiKit.getEcosystemWalletComponents !== "function") return null;
 		try {
-			const components = activeAdapter.getEcosystemWalletComponents();
-			_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] walletComponents from adapter:", components);
-			return components;
+			return activeUiKit.getEcosystemWalletComponents();
 		} catch (error) {
-			_openzeppelin_ui_utils.logger.error("WalletConnectionUI", "[Debug] Error getting wallet components:", error);
+			_openzeppelin_ui_utils.logger.error("WalletConnectionUI", "Error getting wallet components:", error);
 			setIsError(true);
 			return null;
 		}
 	})();
-	if (!walletComponents) {
-		_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "[Debug] getEcosystemWalletComponents returned null/undefined, rendering null.");
-		return null;
-	}
-	_openzeppelin_ui_utils.logger.debug("WalletConnectionUI", "Rendering wallet components:", {
-		hasConnectButton: !!walletComponents.ConnectButton,
-		hasAccountDisplay: !!walletComponents.AccountDisplay,
-		hasNetworkSwitcher: !!walletComponents.NetworkSwitcher
-	});
+	if (!walletComponents) return null;
 	const { ConnectButton, AccountDisplay, NetworkSwitcher } = walletComponents;
 	if (isError) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		className: (0, _openzeppelin_ui_utils.cn)("flex items-center gap-4", className),
@@ -875,18 +972,8 @@ const WalletConnectionUI = ({ className, connectButtonProps, accountDisplayProps
 * Uses useWalletState to get its data.
 */
 const WalletConnectionHeader = () => {
-	const { isAdapterLoading, activeAdapter } = useWalletState();
-	(0, react.useEffect)(() => {
-		_openzeppelin_ui_utils.logger.debug("WalletConnectionHeader", "[Debug] State from useWalletState:", {
-			adapterPresent: !!activeAdapter,
-			adapterNetwork: activeAdapter?.networkConfig.id,
-			isLoading: isAdapterLoading
-		});
-	}, [activeAdapter, isAdapterLoading]);
-	if (isAdapterLoading) {
-		_openzeppelin_ui_utils.logger.debug("WalletConnectionHeader", "[Debug] Adapter loading, showing skeleton.");
-		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: "h-9 w-28 animate-pulse rounded bg-muted" });
-	}
+	const { isRuntimeLoading } = useWalletState();
+	if (isRuntimeLoading) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: "h-9 w-28 animate-pulse rounded bg-muted" });
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(WalletConnectionUI, {});
 };
 
@@ -906,7 +993,7 @@ const WalletConnectionHeader = () => {
 * - Tracks switch attempts to prevent duplicate operations
 * - Provides completion callback for parent components to handle state cleanup
 */
-const NetworkSwitchManager = ({ adapter, targetNetworkId, onNetworkSwitchComplete }) => {
+const NetworkSwitchManager = ({ wallet, networkCatalog, targetNetworkId, onNetworkSwitchComplete }) => {
 	const isMountedRef = (0, react.useRef)(true);
 	const [hasAttemptedSwitch, setHasAttemptedSwitch] = (0, react.useState)(false);
 	const { isConnected, chainId: currentChainIdFromHook } = useDerivedAccountStatus();
@@ -923,7 +1010,7 @@ const NetworkSwitchManager = ({ adapter, targetNetworkId, onNetworkSwitchComplet
 	(0, react.useEffect)(() => {
 		_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", "State Update:", {
 			target: targetNetworkId,
-			adapterNetwork: adapter.networkConfig.id,
+			walletNetwork: wallet.networkConfig.id,
 			isSwitching: isSwitchingNetworkViaHook,
 			hookError: !!switchNetworkError,
 			canExec: !!execSwitchNetwork,
@@ -932,7 +1019,7 @@ const NetworkSwitchManager = ({ adapter, targetNetworkId, onNetworkSwitchComplet
 			attempted: hasAttemptedSwitch
 		});
 	}, [
-		adapter,
+		wallet,
 		targetNetworkId,
 		isSwitchingNetworkViaHook,
 		switchNetworkError,
@@ -959,19 +1046,23 @@ const NetworkSwitchManager = ({ adapter, targetNetworkId, onNetworkSwitchComplet
 			_openzeppelin_ui_utils.logger.info("NetworkSwitchManager", "Previous switch attempt concluded. Deferring to completion effect.");
 			return;
 		}
-		if (adapter.networkConfig.id !== targetNetworkId) {
-			completeOperation(`CRITICAL: Adapter (${adapter.networkConfig.id}) vs Target (${targetNetworkId}) mismatch. Operation halted.`, { notifyComplete: false });
+		if (!networkCatalog.getNetworks().find((network) => network.id === targetNetworkId)) {
+			completeOperation(`Target network ${targetNetworkId} is not present in the network catalog.`, { notifyComplete: false });
+			return;
+		}
+		if (wallet.networkConfig.id !== targetNetworkId) {
+			completeOperation(`CRITICAL: Wallet capability (${wallet.networkConfig.id}) vs Target (${targetNetworkId}) mismatch. Operation halted.`, { notifyComplete: false });
 			return;
 		}
 		if (!isConnected) {
 			completeOperation("Wallet not connected (derived status). Awaiting connection.", { notifyComplete: false });
 			return;
 		}
-		if (!("chainId" in adapter.networkConfig)) {
+		if (!("chainId" in wallet.networkConfig)) {
 			completeOperation("Network does not support chain switching (non-EVM). Operation complete (no-op).");
 			return;
 		}
-		const targetChainToBeSwitchedTo = Number(adapter.networkConfig.chainId);
+		const targetChainToBeSwitchedTo = Number(wallet.networkConfig.chainId);
 		if (currentChainIdFromHook === targetChainToBeSwitchedTo) {
 			completeOperation("Already on correct chain (derived status). Operation complete.");
 			return;
@@ -988,7 +1079,8 @@ const NetworkSwitchManager = ({ adapter, targetNetworkId, onNetworkSwitchComplet
 		const timeoutId = setTimeout(performSwitchActual, 100);
 		return () => clearTimeout(timeoutId);
 	}, [
-		adapter,
+		wallet,
+		networkCatalog,
 		targetNetworkId,
 		execSwitchNetwork,
 		isSwitchingNetworkViaHook,
@@ -1020,23 +1112,23 @@ const NetworkSwitchManager = ({ adapter, targetNetworkId, onNetworkSwitchComplet
 };
 
 //#endregion
-exports.AdapterContext = AdapterContext;
-exports.AdapterProvider = AdapterProvider;
 exports.AnalyticsContext = AnalyticsContext;
 exports.AnalyticsProvider = AnalyticsProvider;
 exports.NetworkSwitchManager = NetworkSwitchManager;
+exports.RuntimeContext = RuntimeContext;
+exports.RuntimeProvider = RuntimeProvider;
 exports.VERSION = VERSION;
 exports.WalletConnectionHeader = WalletConnectionHeader;
 exports.WalletConnectionUI = WalletConnectionUI;
 exports.WalletStateContext = WalletStateContext;
 exports.WalletStateProvider = WalletStateProvider;
-exports.useAdapterContext = useAdapterContext;
 exports.useAnalytics = useAnalytics;
 exports.useDerivedAccountStatus = useDerivedAccountStatus;
 exports.useDerivedChainInfo = useDerivedChainInfo;
 exports.useDerivedConnectStatus = useDerivedConnectStatus;
 exports.useDerivedDisconnect = useDerivedDisconnect;
 exports.useDerivedSwitchChainStatus = useDerivedSwitchChainStatus;
+exports.useRuntimeContext = useRuntimeContext;
 exports.useWalletComponents = useWalletComponents;
 exports.useWalletReconnectionHandler = useWalletReconnectionHandler;
 exports.useWalletState = useWalletState;