@openzeppelin/ui-react 3.1.0 → 3.3.0

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { QueryClient, useQuery } from "@tanstack/react-query";
 import { Button } from "@openzeppelin/ui-components";
 
 //#region src/version.ts
-const VERSION = "3.1.0";
+const VERSION = "3.3.0";
 
 //#endregion
 //#region src/hooks/AdapterContext.tsx
@@ -58,11 +58,31 @@ function RuntimeProvider({ children, resolveRuntime }) {
 	const [loadingNetworks, setLoadingNetworks] = useState(/* @__PURE__ */ new Set());
 	const runtimeRegistryRef = useRef(runtimeRegistry);
 	const failedNetworksRef = useRef(/* @__PURE__ */ new Set());
+	const resolverGenerationRef = useRef(0);
+	const resolverInitializedRef = useRef(false);
 	useEffect(() => {
 		runtimeRegistryRef.current = runtimeRegistry;
 	}, [runtimeRegistry]);
 	useEffect(() => {
+		if (resolverInitializedRef.current) resolverGenerationRef.current += 1;
+		else resolverInitializedRef.current = true;
+		const registry = runtimeRegistryRef.current;
+		const runtimes = Object.values(registry);
+		const hadCachedRuntimes = runtimes.length > 0;
 		failedNetworksRef.current = /* @__PURE__ */ new Set();
+		setLoadingNetworks(/* @__PURE__ */ new Set());
+		if (hadCachedRuntimes) {
+			setRuntimeRegistry({});
+			setTimeout(() => {
+				runtimes.forEach((runtime) => {
+					try {
+						runtime.dispose();
+					} catch (error) {
+						logger.error("RuntimeProvider", "Error disposing runtime during registry flush:", error);
+					}
+				});
+			}, 0);
+		}
 	}, [resolveRuntime]);
 	useEffect(() => {
 		return () => {
@@ -150,7 +170,23 @@ function RuntimeProvider({ children, resolveRuntime }) {
 			return newSet;
 		});
 		logger.info("RuntimeProvider", `Starting runtime initialization for network ${networkId} (${networkConfig.name})`);
+		const generation = resolverGenerationRef.current;
 		resolveRuntime(networkConfig).then((runtime) => {
+			if (generation !== resolverGenerationRef.current) {
+				setTimeout(() => {
+					try {
+						runtime.dispose();
+					} catch (error) {
+						logger.error("RuntimeProvider", `Error disposing stale runtime for network ${networkId}:`, error);
+					}
+				}, 0);
+				setLoadingNetworks((prev) => {
+					const newSet = new Set(prev);
+					newSet.delete(networkId);
+					return newSet;
+				});
+				return;
+			}
 			logger.info("RuntimeProvider", `Runtime for network ${networkId} loaded successfully`, {
 				type: runtime.constructor.name,
 				objectId: Object.prototype.toString.call(runtime)
@@ -165,6 +201,14 @@ function RuntimeProvider({ children, resolveRuntime }) {
 				return newSet;
 			});
 		}).catch((error) => {
+			if (generation !== resolverGenerationRef.current) {
+				setLoadingNetworks((prev) => {
+					const newSet = new Set(prev);
+					newSet.delete(networkId);
+					return newSet;
+				});
+				return;
+			}
 			logger.error("RuntimeProvider", `Error loading runtime for network ${networkId}:`, error);
 			failedNetworksRef.current.add(networkId);
 			setLoadingNetworks((prev) => {
@@ -893,22 +937,42 @@ const DEFAULT_CONFIG = {
 };
 /** Stable prefix for every resolution cache key — namespaces this package's keys. */
 const RESOLUTION_KEY_PREFIX = "oz-name-resolution";
+const runtimeInstanceIds = /* @__PURE__ */ new WeakMap();
+let nextRuntimeInstanceId = 1;
+/**
+* Assign a stable, serializable id to each {@link EcosystemRuntime} object identity.
+* A disposed-and-recreated runtime (e.g. SF-4 opt-in toggle after INV-218 flush) gets
+* a new id so resolution cache keys miss and results refresh (INV-230).
+*/
+function getRuntimeInstanceId(runtime) {
+	if (!runtime) return 0;
+	let id = runtimeInstanceIds.get(runtime);
+	if (id === void 0) {
+		id = nextRuntimeInstanceId;
+		nextRuntimeInstanceId += 1;
+		runtimeInstanceIds.set(runtime, id);
+	}
+	return id;
+}
 /**
 * Build a network-scoped, namespace-separated cache key (INV-40). A name resolves
 * differently per network and provenance can be chain-scoped, so `networkId` is
-* part of the key; `namespace` keeps forward and reverse lookups disjoint.
+* part of the key; `namespace` keeps forward and reverse lookups disjoint;
+* `runtimeInstanceId` scopes entries to the active capability instance (INV-230).
 *
-* @param namespace       - `'name'` (forward) or `'addr'` (reverse).
-* @param networkId       - Active network id (`''` when no network is selected).
-* @param normalizedInput - Trimmed + lowercased input (INV-26).
+* @param namespace           - `'name'` (forward) or `'addr'` (reverse).
+* @param networkId           - Active network id (`''` when no network is selected).
+* @param normalizedInput     - Trimmed + lowercased input (INV-26).
+* @param runtimeInstanceId   - Active runtime instance discriminator (`0` when absent).
 * @returns A readonly tuple suitable for a TanStack Query `queryKey`.
 */
-function buildResolutionKey(namespace, networkId, normalizedInput) {
+function buildResolutionKey(namespace, networkId, normalizedInput, runtimeInstanceId = 0) {
 	return [
 		RESOLUTION_KEY_PREFIX,
 		namespace,
 		networkId,
-		normalizedInput
+		normalizedInput,
+		runtimeInstanceId
 	];
 }
 /**
@@ -1081,11 +1145,11 @@ const NOOP_RETRY = () => {};
 * {@link EngineResult}. Not exported from the package.
 */
 function useResolutionEngine(params) {
-	const { input, namespace, debounceMs, enabled, shouldAttempt, getMethod } = params;
+	const { input, namespace, debounceMs, enabled, shouldAttempt, getMethod, runtimeSource } = params;
 	const walletState = useContext(WalletStateContext);
-	const activeRuntime = walletState?.activeRuntime ?? null;
-	const activeNetworkId = walletState?.activeNetworkId ?? null;
-	const isRuntimeLoading = walletState?.isRuntimeLoading ?? false;
+	const activeRuntime = runtimeSource ? runtimeSource.runtime : walletState?.activeRuntime ?? null;
+	const activeNetworkId = runtimeSource ? runtimeSource.networkId : walletState?.activeNetworkId ?? null;
+	const isRuntimeLoading = runtimeSource ? runtimeSource.isRuntimeLoading : walletState?.isRuntimeLoading ?? false;
 	const { queryClient, config } = useNameResolutionContext();
 	const trimmedLive = (input ?? "").trim();
 	const normalizedLive = trimmedLive.toLowerCase();
@@ -1107,12 +1171,13 @@ function useResolutionEngine(params) {
 	const normalizedKey = effectiveTrimmed.toLowerCase();
 	const capability = activeRuntime?.nameResolution;
 	const networkId = activeNetworkId ?? "";
+	const runtimeInstanceId = getRuntimeInstanceId(activeRuntime);
 	const method = capability ? getMethod(capability) : void 0;
 	const liveAttemptable = capability ? shouldAttempt(capability, normalizedLive) : false;
 	const keyAttemptable = capability ? shouldAttempt(capability, normalizedKey) : false;
 	const queryEnabled = enabled && trimmedLive !== "" && capability != null && method != null && normalizedKey !== "" && keyAttemptable;
 	const query = useQuery({
-		queryKey: buildResolutionKey(namespace, networkId, normalizedKey),
+		queryKey: buildResolutionKey(namespace, networkId, normalizedKey, runtimeInstanceId),
 		queryFn: async () => {
 			if (!method) throw new ResolutionQueryError({
 				code: "ADAPTER_ERROR",
@@ -1239,40 +1304,13 @@ function toNameResult(engine) {
 }
 
 //#endregion
-//#region src/hooks/nameResolution/useResolveAddress.ts
-/**
-* Reverse-resolve an address to a name. Soft-reads the active runtime from
-* `WalletStateContext` (never throws when no provider is mounted — degrades to
-* idle / UNSUPPORTED_NETWORK) and calls `runtime.nameResolution?.resolveAddress`.
-* Caches per (network, address) via the owned QueryClient. Not debounced by
-* default — addresses are pasted, not typed char-by-char.
-*
-* Applies no client-side address-shape check (INV-32): resolution is attempted on
-* any non-empty input and malformed addresses are rejected via the adapter's typed
-* error union. Address-shape validation is SF-3's concern.
-*
-* @param address - The address to reverse-resolve. `null` / empty yields
-*   `status: 'idle'`.
-* @param options - `debounceMs` / `enabled` overrides.
-* @returns The current {@link UseResolveAddressResult}.
-*/
-function useResolveAddress(address, options) {
-	const { config } = useNameResolutionContext();
-	return toAddressResult(useResolutionEngine({
-		input: address,
-		namespace: "addr",
-		debounceMs: options?.debounceMs ?? config.reverseDebounceMs,
-		enabled: options?.enabled ?? true,
-		shouldAttempt: () => true,
-		getMethod: (cap) => cap.resolveAddress
-	}));
-}
+//#region src/hooks/nameResolution/mapAddressEngineResult.ts
 /**
 * Remap the engine's generic `input` to `address` (INV-24). A `debouncing` arm —
 * only reachable when a caller passes a non-zero reverse `debounceMs` — collapses
 * to `loading` so {@link UseResolveAddressResult} keeps no `debouncing` variant.
 */
-function toAddressResult(engine) {
+function mapAddressEngineResult(engine) {
 	switch (engine.status) {
 		case "idle": return { status: "idle" };
 		case "debouncing":
@@ -1294,6 +1332,71 @@ function toAddressResult(engine) {
 	}
 }
 
+//#endregion
+//#region src/hooks/nameResolution/useNetworkRuntimeSource.ts
+/**
+* Soft-reads {@link RuntimeContext} (never throws) and requests the registry
+* runtime for `network`. Call during render so loading state updates propagate.
+*
+* Does not mutate {@link WalletStateProvider}'s active network — wallet-global
+* runtime is never consulted when a scoped network is supplied (INV-154).
+*/
+function useNetworkRuntimeSource(network) {
+	const runtimeContext = useContext(RuntimeContext);
+	if (!network) return {
+		runtime: null,
+		networkId: "",
+		isRuntimeLoading: false
+	};
+	if (!runtimeContext) return {
+		runtime: null,
+		networkId: network.id,
+		isRuntimeLoading: false
+	};
+	const { runtime, isLoading } = runtimeContext.getRuntimeForNetwork(network);
+	return {
+		runtime,
+		networkId: network.id,
+		isRuntimeLoading: isLoading
+	};
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useResolveAddress.ts
+/**
+* Reverse-resolve an address to a name. Soft-reads the active runtime from
+* `WalletStateContext` (never throws when no provider is mounted — degrades to
+* idle / UNSUPPORTED_NETWORK) and calls `runtime.nameResolution?.resolveAddress`.
+* Pass `options.network` to scope resolution to a specific network without
+* changing the wallet's active network. Caches per (network, address) via the
+* owned QueryClient. Not debounced by default — addresses are pasted, not
+* typed char-by-char.
+*
+* Applies no client-side address-shape check (INV-32): resolution is attempted on
+* any non-empty input and malformed addresses are rejected via the adapter's typed
+* error union. Address-shape validation is SF-3's concern.
+*
+* @param address - The address to reverse-resolve. `null` / empty yields
+*   `status: 'idle'`.
+* @param options - `debounceMs` / `enabled` / `network` overrides.
+* @returns The current {@link UseResolveAddressResult}.
+*/
+function useResolveAddress(address, options) {
+	const { config } = useNameResolutionContext();
+	const debounceMs = options?.debounceMs ?? config.reverseDebounceMs;
+	const enabled = options?.enabled ?? true;
+	const networkSource = useNetworkRuntimeSource(options?.network ?? null);
+	return mapAddressEngineResult(useResolutionEngine({
+		input: address,
+		namespace: "addr",
+		debounceMs,
+		enabled,
+		shouldAttempt: () => true,
+		getMethod: (cap) => cap.resolveAddress,
+		runtimeSource: options?.network != null ? networkSource : void 0
+	}));
+}
+
 //#endregion
 //#region src/hooks/nameResolution/NameResolutionProvider.tsx
 /**
@@ -1319,6 +1422,54 @@ function NameResolutionProvider({ children, config, queryClient }) {
 	});
 }
 
+//#endregion
+//#region src/hooks/nameResolution/createNameResolver.ts
+const EMPTY_RESOLVER$1 = {};
+/**
+* Projects a {@link NameResolutionCapability} into the SF-3 {@link NameResolver}
+* seam with SF-2 cache-key parity (INV-119).
+*/
+function createNameResolverFromCapability(capability, networkId, runtimeInstanceId, queryClient, config) {
+	if (!capability) return EMPTY_RESOLVER$1;
+	const resolveNameMethod = capability.resolveName;
+	return {
+		isValidName: (name) => capability.isValidName(name),
+		resolveName: resolveNameMethod ? async (name) => {
+			const normalized = name.trim().toLowerCase();
+			try {
+				return {
+					ok: true,
+					value: await queryClient.fetchQuery({
+						queryKey: buildResolutionKey("name", networkId, normalized, runtimeInstanceId),
+						queryFn: async () => {
+							let result;
+							try {
+								result = await resolveNameMethod(normalized);
+							} catch (cause) {
+								throw new ResolutionQueryError({
+									code: "ADAPTER_ERROR",
+									message: cause instanceof Error ? cause.message : String(cause),
+									cause
+								});
+							}
+							if (!result.ok) throw new ResolutionQueryError(result.error);
+							return result.value;
+						},
+						staleTime: config.staleTimeMs,
+						gcTime: config.gcTimeMs,
+						retry: (failureCount, error) => (error instanceof ResolutionQueryError ? isTransientError(error.resolutionError) : true) && failureCount < config.transientRetryCount
+					})
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: toNameResolutionError(error)
+				};
+			}
+		} : void 0
+	};
+}
+
 //#endregion
 //#region src/hooks/nameResolution/useRuntimeNameResolver.ts
 /**
@@ -1328,7 +1479,7 @@ function NameResolutionProvider({ children, config, queryClient }) {
 */
 const EMPTY_RESOLVER = {};
 /**
-* Project the active runtime's `NameResolutionCapability` into the injected
+* Project a runtime's `NameResolutionCapability` into the injected
 * {@link NameResolver} seam consumed by `@openzeppelin/ui-components` (SF-3, D3).
 * Mounted ambiently by the renderer:
 *
@@ -1336,6 +1487,10 @@ const EMPTY_RESOLVER = {};
 * <NameResolverProvider {...useRuntimeNameResolver()}>{form}</NameResolverProvider>
 * ```
 *
+* Pass `scopedNetwork` to resolve against a specific network via
+* {@link RuntimeProvider}'s registry without changing {@link WalletStateProvider}'s
+* active network (e.g. address-book Add Alias dropdown).
+*
 * Each imperative call is backed by SF-2's **owned** resolution `QueryClient`
 * via `fetchQuery`, reusing SF-2's exact query-key convention
 * (`buildResolutionKey('name', networkId, normalizedName)`) — so a name
@@ -1344,9 +1499,10 @@ const EMPTY_RESOLVER = {};
 * out-of-order safety, never a parallel cache (INV-119).
 *
 * Degradation, in order (all method-omission, never a throw):
-* - No `WalletStateProvider` mounted → empty resolver. The context is read
-*   directly (not via `useWalletState()`, which throws) so the ambient
-*   renderer mount stays safe for wallet-less usage.
+* - No `WalletStateProvider` mounted (wallet path) or no `RuntimeProvider`
+*   (network path) → empty resolver. The context is read directly (not via
+*   `useWalletState()`, which throws) so the ambient renderer mount stays safe
+*   for wallet-less usage.
 * - No active runtime, or runtime without the capability → empty resolver.
 * - Capability without `resolveName` → `isValidName` only; forward unsupported.
 *
@@ -1356,55 +1512,111 @@ const EMPTY_RESOLVER = {};
 *
 * @returns A referentially stable {@link NameResolver} for the active runtime.
 */
-function useRuntimeNameResolver() {
+function useRuntimeNameResolver(scopedNetwork) {
 	const walletState = useContext(WalletStateContext);
 	const { queryClient, config } = useNameResolutionContext();
-	const capability = walletState?.activeRuntime?.nameResolution;
-	const networkId = walletState?.activeNetworkId ?? "";
+	const networkSource = useNetworkRuntimeSource(scopedNetwork ?? null);
+	const useNetworkScoped = scopedNetwork != null;
+	const activeRuntime = useNetworkScoped ? networkSource.runtime : walletState?.activeRuntime ?? null;
+	const capability = activeRuntime?.nameResolution;
+	const networkId = useNetworkScoped ? networkSource.networkId : walletState?.activeNetworkId ?? "";
+	const runtimeInstanceId = getRuntimeInstanceId(activeRuntime);
 	return useMemo(() => {
 		if (!capability) return EMPTY_RESOLVER;
-		const resolveNameMethod = capability.resolveName;
-		return {
-			isValidName: (name) => capability.isValidName(name),
-			resolveName: resolveNameMethod ? async (name) => {
-				const normalized = name.trim().toLowerCase();
-				try {
-					return {
-						ok: true,
-						value: await queryClient.fetchQuery({
-							queryKey: buildResolutionKey("name", networkId, normalized),
-							queryFn: async () => {
-								let result;
-								try {
-									result = await resolveNameMethod(normalized);
-								} catch (cause) {
-									throw new ResolutionQueryError({
-										code: "ADAPTER_ERROR",
-										message: cause instanceof Error ? cause.message : String(cause),
-										cause
-									});
-								}
-								if (!result.ok) throw new ResolutionQueryError(result.error);
-								return result.value;
-							},
-							staleTime: config.staleTimeMs,
-							gcTime: config.gcTimeMs,
-							retry: (failureCount, error) => (error instanceof ResolutionQueryError ? isTransientError(error.resolutionError) : true) && failureCount < config.transientRetryCount
-						})
-					};
-				} catch (error) {
-					return {
-						ok: false,
-						error: toNameResolutionError(error)
-					};
-				}
-			} : void 0
-		};
+		return createNameResolverFromCapability(capability, networkId, runtimeInstanceId, queryClient, config);
 	}, [
 		capability,
+		networkId,
+		runtimeInstanceId,
 		queryClient,
 		config,
-		networkId
+		useNetworkScoped ? networkSource.isRuntimeLoading : walletState?.isRuntimeLoading ?? false
+	]);
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useNetworkNameResolver.ts
+/**
+* @deprecated Pass the network to {@link useRuntimeNameResolver} instead.
+*/
+function useNetworkNameResolver(network) {
+	return useRuntimeNameResolver(network ?? void 0);
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useNetworkResolveAddress.ts
+/**
+* @deprecated Pass `network` in {@link UseResolveAddressOptions} to {@link useResolveAddress}.
+*/
+function useNetworkResolveAddress(address, network, options) {
+	return useResolveAddress(address, network != null ? {
+		...options,
+		network
+	} : options);
+}
+
+//#endregion
+//#region src/hooks/runtime/runtimeCreationConfig.ts
+/** Safe default: miss-fallback OFF; no uiKit override. INV-204 */
+const DEFAULT_RUNTIME_CREATION_CONFIG = {};
+/**
+* Normalizes the opt-in flag to the adapter's strict-enable contract.
+* UIKit uses this at the threading boundary so `false` and `undefined` never
+* emit `enableMainnetL1MissFallback: false` into adapter options (absent = OFF).
+*/
+function isMainnetL1MissFallbackEnabled(options) {
+	return options?.enableMainnetL1MissFallback === true;
+}
+/**
+* Builds the `createRuntime` options bag for adapter threading.
+* When OFF, `nameResolution` is omitted (INV-207). When ON, spreads only
+* `{ enableMainnetL1MissFallback: true }` (INV-208).
+*/
+function buildCreateRuntimeOptions(options) {
+	return {
+		...options?.uiKit !== void 0 ? { uiKit: options.uiKit } : {},
+		...isMainnetL1MissFallbackEnabled(options?.nameResolution) ? { nameResolution: { enableMainnetL1MissFallback: true } } : {}
+	};
+}
+
+//#endregion
+//#region src/hooks/runtime/createResolveRuntime.ts
+/**
+* Build a `resolveRuntime` callback for {@link RuntimeProvider} that forwards
+* `CreateRuntimeOptions` to `ecosystemDefinition.createRuntime`.
+*
+* Does not cache — {@link RuntimeProvider} owns the per-network singleton registry.
+*/
+function createResolveRuntime(ecosystemDefinition, params) {
+	const { profile, options } = params;
+	const mergedOptions = buildCreateRuntimeOptions(options);
+	return (networkConfig) => Promise.resolve(ecosystemDefinition.createRuntime(profile, networkConfig, mergedOptions));
+}
+
+//#endregion
+//#region src/hooks/runtime/useResolveRuntime.ts
+/**
+* Memoized {@link createResolveRuntime} for React apps. Recompute when
+* `ecosystemDefinition`, `profile`, or opt-in posture change (INV-217, INV-222).
+*
+* Changing the returned function identity MUST trigger runtime registry flush
+* in {@link RuntimeProvider} (INV-218).
+*/
+function useResolveRuntime(ecosystemDefinition, params) {
+	const { profile, options } = params;
+	const uiKit = options?.uiKit;
+	const enableMainnetL1MissFallback = options?.nameResolution?.enableMainnetL1MissFallback;
+	return useMemo(() => createResolveRuntime(ecosystemDefinition, {
+		profile,
+		options: {
+			...uiKit !== void 0 ? { uiKit } : {},
+			...enableMainnetL1MissFallback === true ? { nameResolution: { enableMainnetL1MissFallback: true } } : {}
+		}
+	}), [
+		ecosystemDefinition,
+		profile,
+		uiKit,
+		enableMainnetL1MissFallback
 	]);
 }
 
@@ -1615,5 +1827,5 @@ const NetworkSwitchManager = ({ wallet, networkCatalog, targetNetworkId, onNetwo
 };
 
 //#endregion
-export { AnalyticsContext, AnalyticsProvider, DEFAULT_CONFIG, NameResolutionContext, NameResolutionProvider, NetworkSwitchManager, RuntimeContext, RuntimeProvider, VERSION, WalletConnectionHeader, WalletConnectionUI, WalletStateContext, WalletStateProvider, useAnalytics, useDerivedAccountStatus, useDerivedChainInfo, useDerivedConnectStatus, useDerivedDisconnect, useDerivedSwitchChainStatus, useNameResolutionContext, useResolveAddress, useResolveName, useRuntimeContext, useRuntimeNameResolver, useWalletComponents, useWalletReconnectionHandler, useWalletState };
+export { AnalyticsContext, AnalyticsProvider, DEFAULT_CONFIG, DEFAULT_RUNTIME_CREATION_CONFIG, NameResolutionContext, NameResolutionProvider, NetworkSwitchManager, RuntimeContext, RuntimeProvider, VERSION, WalletConnectionHeader, WalletConnectionUI, WalletStateContext, WalletStateProvider, createResolveRuntime, isMainnetL1MissFallbackEnabled, useAnalytics, useDerivedAccountStatus, useDerivedChainInfo, useDerivedConnectStatus, useDerivedDisconnect, useDerivedSwitchChainStatus, useNameResolutionContext, useNetworkNameResolver, useNetworkResolveAddress, useResolveAddress, useResolveName, useResolveRuntime, useRuntimeContext, useRuntimeNameResolver, useWalletComponents, useWalletReconnectionHandler, useWalletState };
 //# sourceMappingURL=index.mjs.map