@openzeppelin/ui-react 3.0.1 → 3.2.0

package/dist/index.cjs

@@ -29,10 +29,11 @@ let react = require("react");
 react = __toESM(react);
 let _openzeppelin_ui_utils = require("@openzeppelin/ui-utils");
 let react_jsx_runtime = require("react/jsx-runtime");
+let _tanstack_react_query = require("@tanstack/react-query");
 let _openzeppelin_ui_components = require("@openzeppelin/ui-components");
 
 //#region src/version.ts
-const VERSION = "3.0.1";
+const VERSION = "3.2.0";
 
 //#endregion
 //#region src/hooks/AdapterContext.tsx
@@ -85,11 +86,31 @@ function RuntimeProvider({ children, resolveRuntime }) {
 	const [loadingNetworks, setLoadingNetworks] = (0, react.useState)(/* @__PURE__ */ new Set());
 	const runtimeRegistryRef = (0, react.useRef)(runtimeRegistry);
 	const failedNetworksRef = (0, react.useRef)(/* @__PURE__ */ new Set());
+	const resolverGenerationRef = (0, react.useRef)(0);
+	const resolverInitializedRef = (0, react.useRef)(false);
 	(0, react.useEffect)(() => {
 		runtimeRegistryRef.current = runtimeRegistry;
 	}, [runtimeRegistry]);
 	(0, react.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) {
+						_openzeppelin_ui_utils.logger.error("RuntimeProvider", "Error disposing runtime during registry flush:", error);
+					}
+				});
+			}, 0);
+		}
 	}, [resolveRuntime]);
 	(0, react.useEffect)(() => {
 		return () => {
@@ -177,7 +198,23 @@ function RuntimeProvider({ children, resolveRuntime }) {
 			return newSet;
 		});
 		_openzeppelin_ui_utils.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) {
+						_openzeppelin_ui_utils.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;
+			}
 			_openzeppelin_ui_utils.logger.info("RuntimeProvider", `Runtime for network ${networkId} loaded successfully`, {
 				type: runtime.constructor.name,
 				objectId: Object.prototype.toString.call(runtime)
@@ -192,6 +229,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;
+			}
 			_openzeppelin_ui_utils.logger.error("RuntimeProvider", `Error loading runtime for network ${networkId}:`, error);
 			failedNetworksRef.current.add(networkId);
 			setLoadingNetworks((prev) => {
@@ -272,12 +317,12 @@ const WALLET_STATE_CONTEXT_KEY = Symbol.for("@openzeppelin/ui-react/WalletStateC
 * 4. For React contexts specifically, having the same context object is what matters,
 *    and this pattern guarantees that after initialization
 */
-function getOrCreateSharedContext() {
+function getOrCreateSharedContext$1() {
 	const global = globalThis;
 	if (!global[WALLET_STATE_CONTEXT_KEY]) global[WALLET_STATE_CONTEXT_KEY] = (0, react.createContext)(void 0);
 	return global[WALLET_STATE_CONTEXT_KEY];
 }
-const WalletStateContext = getOrCreateSharedContext();
+const WalletStateContext = getOrCreateSharedContext$1();
 /**
 * Hook to access wallet state from WalletStateProvider.
 * @throws Error if used outside of WalletStateProvider
@@ -905,6 +950,625 @@ function useWalletReconnectionHandler(selectedNetworkConfigId, selectedCapabilit
 	]);
 }
 
+//#endregion
+//#region src/hooks/nameResolution/resolutionConfig.ts
+/**
+* Default resolution config. Values sit within the spec's "seconds-to-minutes"
+* caching guidance; forward debounce is 300ms (typed char-by-char), reverse is 0.
+*/
+const DEFAULT_CONFIG = {
+	staleTimeMs: 6e4,
+	gcTimeMs: 3e5,
+	forwardDebounceMs: 300,
+	reverseDebounceMs: 0,
+	transientRetryCount: 2
+};
+/** 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;
+* `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 runtimeInstanceId   - Active runtime instance discriminator (`0` when absent).
+* @returns A readonly tuple suitable for a TanStack Query `queryKey`.
+*/
+function buildResolutionKey(namespace, networkId, normalizedInput, runtimeInstanceId = 0) {
+	return [
+		RESOLUTION_KEY_PREFIX,
+		namespace,
+		networkId,
+		normalizedInput,
+		runtimeInstanceId
+	];
+}
+/**
+* Whether a resolution error is transient (worth retrying) versus a definitive,
+* stable answer (INV-47). Exhaustive over SF-1's closed error union with no
+* `default`: adding a new error code to `@openzeppelin/ui-types` will fail to
+* compile here until it is classified — deliberately coupling SF-2 to SF-1 INV-7.
+*
+* @param error - A typed {@link NameResolutionError}.
+* @returns `true` for transient failures (timeout / gateway / adapter), `false`
+*   for definitive negatives and unsupported-network answers.
+*/
+function isTransientError(error) {
+	switch (error.code) {
+		case "RESOLUTION_TIMEOUT":
+		case "EXTERNAL_GATEWAY_ERROR":
+		case "ADAPTER_ERROR": return true;
+		case "NAME_NOT_FOUND":
+		case "ADDRESS_NOT_FOUND":
+		case "UNSUPPORTED_NAME":
+		case "UNSUPPORTED_NETWORK": return false;
+	}
+}
+/**
+* Construct a QueryClient tuned for name resolution: ambient refetch triggers are
+* disabled at the client level (INV-41) so a resolved value never silently
+* changes under the user on window focus or network reconnect.
+*/
+function createResolutionQueryClient() {
+	return new _tanstack_react_query.QueryClient({ defaultOptions: { queries: {
+		refetchOnWindowFocus: false,
+		refetchOnReconnect: false
+	} } });
+}
+/**
+* Process-global key for the default resolution QueryClient. Uses `Symbol.for`
+* so every duplicated module instance (Vite pre-bundling, npm-installed adapters)
+* shares ONE client — the same cross-bundle-singleton pattern as
+* `WalletStateContext`. This is what makes the cache shared with zero wiring
+* (SC-001) and enables cross-instance dedup / warm-cache reuse (INV-33 / INV-37 / INV-48).
+*/
+const DEFAULT_CLIENT_KEY = Symbol.for("@openzeppelin/ui-react/NameResolutionQueryClient");
+/**
+* Lazily create (exactly once) and return the process-global resolution
+* QueryClient used when no `NameResolutionProvider` is mounted (INV-48).
+*
+* @returns The shared default resolution QueryClient (stable across calls).
+*/
+function getDefaultResolutionQueryClient() {
+	const globalScope = globalThis;
+	if (!globalScope[DEFAULT_CLIENT_KEY]) globalScope[DEFAULT_CLIENT_KEY] = createResolutionQueryClient();
+	return globalScope[DEFAULT_CLIENT_KEY];
+}
+
+//#endregion
+//#region src/hooks/nameResolution/NameResolutionContext.ts
+/**
+* Process-global key for the context object. Uses `Symbol.for` so all duplicated
+* module instances share ONE React context — the same cross-bundle-singleton
+* pattern as `WalletStateContext` (bundler pre-bundling / npm-installed adapters).
+*/
+const CONTEXT_KEY = Symbol.for("@openzeppelin/ui-react/NameResolutionContext");
+function getOrCreateSharedContext() {
+	const globalScope = globalThis;
+	if (!globalScope[CONTEXT_KEY]) globalScope[CONTEXT_KEY] = (0, react.createContext)(null);
+	return globalScope[CONTEXT_KEY];
+}
+/**
+* React context for resolution. `null` default triggers the module-singleton
+* fallback in {@link useNameResolutionContext} — no Provider is required (INV-48).
+*/
+const NameResolutionContext = getOrCreateSharedContext();
+/**
+* Stable fallback value used when no Provider is mounted. Cached per module so the
+* returned reference is referentially stable across renders (INV-38); it wraps the
+* process-global default client, so caches are still shared even across bundles.
+*/
+let fallbackValue;
+function getFallbackContextValue() {
+	if (!fallbackValue) fallbackValue = {
+		queryClient: getDefaultResolutionQueryClient(),
+		config: DEFAULT_CONFIG
+	};
+	return fallbackValue;
+}
+/**
+* Read the resolution context, falling back to the zero-wiring default (global
+* singleton client + {@link DEFAULT_CONFIG}) when no `NameResolutionProvider` is
+* mounted (INV-48). Never throws for a missing provider.
+*
+* @returns The active {@link NameResolutionContextValue}.
+*/
+function useNameResolutionContext() {
+	return (0, react.useContext)(NameResolutionContext) ?? getFallbackContextValue();
+}
+
+//#endregion
+//#region src/hooks/nameResolution/resolutionState.ts
+/**
+* Internal error used to bridge SF-1's `ok: false` results (and defensively-caught
+* adapter throws) into TanStack Query's thrown-error channel, carrying the typed
+* {@link NameResolutionError} through so the mapping step can surface it unchanged
+* (INV-43). Never leaks past the hook boundary.
+*/
+var ResolutionQueryError = class extends Error {
+	resolutionError;
+	/** @param resolutionError - The typed error to carry through react-query. */
+	constructor(resolutionError) {
+		super(`name resolution failed: ${resolutionError.code}`);
+		this.name = "ResolutionQueryError";
+		this.resolutionError = resolutionError;
+	}
+};
+/**
+* Convert any value from react-query's error channel into a typed, closed-union
+* {@link NameResolutionError} (INV-43). A {@link ResolutionQueryError} is
+* unwrapped verbatim; anything else (a react-query internal error) is mapped to
+* `ADAPTER_ERROR` so no untyped throw reaches a component.
+*
+* @param error - The raw `query.error` value (`unknown`).
+* @returns A typed error drawn only from SF-1's closed union.
+*/
+function toNameResolutionError(error) {
+	if (error instanceof ResolutionQueryError) return error.resolutionError;
+	return {
+		code: "ADAPTER_ERROR",
+		message: error instanceof Error ? error.message : String(error),
+		cause: error
+	};
+}
+/**
+* Map a settled query's state to exactly one non-gate {@link EngineResult} arm
+* (INV-42, INV-44). The `input` echoed here is the debounced value the query was
+* keyed on, so `data`/`error` are always paired with the input that produced them
+* (INV-24). Success without data degrades to `loading` rather than a resolved arm
+* missing its payload.
+*
+* @param input - The debounced, normalized input keying this query.
+* @param query - The settled query state.
+* @param retry - Bound `refetch` for the `error` arm (INV-34).
+* @returns The `resolved`, `error`, or `loading` arm.
+*/
+function mapSettledQuery(input, query, retry) {
+	if (query.isSuccess && query.data !== void 0) return {
+		status: "resolved",
+		input,
+		data: query.data
+	};
+	if (query.isError) return {
+		status: "error",
+		input,
+		error: toNameResolutionError(query.error),
+		retry
+	};
+	return {
+		status: "loading",
+		input
+	};
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useResolutionEngine.ts
+const LOG_SCOPE = "useResolutionEngine";
+/** No-op retry for synthesized errors that never entered the query path (INV-45). */
+const NOOP_RETRY = () => {};
+/**
+* Shared engine behind `useResolveName` / `useResolveAddress`. Owns input
+* normalization, debouncing, the `useQuery` wiring (explicit-client form), the
+* capability-absence gate, and the mapping to a direction-agnostic
+* {@link EngineResult}. Not exported from the package.
+*/
+function useResolutionEngine(params) {
+	const { input, namespace, debounceMs, enabled, shouldAttempt, getMethod } = params;
+	const walletState = (0, react.useContext)(WalletStateContext);
+	const activeRuntime = walletState?.activeRuntime ?? null;
+	const activeNetworkId = walletState?.activeNetworkId ?? null;
+	const isRuntimeLoading = walletState?.isRuntimeLoading ?? false;
+	const { queryClient, config } = useNameResolutionContext();
+	const trimmedLive = (input ?? "").trim();
+	const normalizedLive = trimmedLive.toLowerCase();
+	const [debouncedTrimmed, setDebouncedTrimmed] = (0, react.useState)(trimmedLive);
+	const seededRef = (0, react.useRef)(false);
+	(0, react.useEffect)(() => {
+		if (!seededRef.current) {
+			seededRef.current = true;
+			return;
+		}
+		if (debounceMs <= 0) {
+			setDebouncedTrimmed(trimmedLive);
+			return;
+		}
+		const timer = setTimeout(() => setDebouncedTrimmed(trimmedLive), debounceMs);
+		return () => clearTimeout(timer);
+	}, [trimmedLive, debounceMs]);
+	const effectiveTrimmed = debounceMs <= 0 ? trimmedLive : debouncedTrimmed;
+	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 = (0, _tanstack_react_query.useQuery)({
+		queryKey: buildResolutionKey(namespace, networkId, normalizedKey, runtimeInstanceId),
+		queryFn: async () => {
+			if (!method) throw new ResolutionQueryError({
+				code: "ADAPTER_ERROR",
+				message: "resolution method unexpectedly missing"
+			});
+			const adapterArg = namespace === "addr" ? effectiveTrimmed : normalizedKey;
+			let result;
+			try {
+				result = await method(adapterArg);
+			} catch (cause) {
+				_openzeppelin_ui_utils.logger.warn(LOG_SCOPE, "resolution method threw instead of returning ok:false", 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;
+		},
+		enabled: queryEnabled,
+		staleTime: config.staleTimeMs,
+		gcTime: config.gcTimeMs,
+		refetchOnWindowFocus: false,
+		refetchOnReconnect: false,
+		retry: (failureCount, error) => (error instanceof ResolutionQueryError ? isTransientError(error.resolutionError) : true) && failureCount < config.transientRetryCount
+	}, queryClient);
+	if (!enabled) return { status: "idle" };
+	if (trimmedLive === "") return { status: "idle" };
+	if (capability) {
+		if (!liveAttemptable) return { status: "idle" };
+		if (!method) return unsupportedNetwork(normalizedLive, networkId);
+		if (normalizedKey !== normalizedLive) return {
+			status: "debouncing",
+			input: normalizedLive
+		};
+	} else {
+		if (isRuntimeLoading) return {
+			status: "loading",
+			input: normalizedLive
+		};
+		return unsupportedNetwork(normalizedLive, networkId);
+	}
+	const retry = () => {
+		query.refetch();
+	};
+	return mapSettledQuery(normalizedKey, query, retry);
+}
+/**
+* Synthesize an `UNSUPPORTED_NETWORK` error arm without touching react-query
+* (INV-45). Drawn from SF-1's closed union so it is indistinguishable from an
+* adapter-returned `UNSUPPORTED_NETWORK`; `networkId` may be `''` (INV-49). Retry
+* is a no-op — there is no query to refetch.
+*/
+function unsupportedNetwork(input, networkId) {
+	return {
+		status: "error",
+		input,
+		error: {
+			code: "UNSUPPORTED_NETWORK",
+			networkId
+		},
+		retry: NOOP_RETRY
+	};
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useResolveName.ts
+/**
+* Forward-resolve a name to an address. Soft-reads the active runtime from
+* `WalletStateContext` (never throws when no provider is mounted — degrades to
+* idle / UNSUPPORTED_NETWORK) and calls `runtime.nameResolution?.resolveName`.
+* Debounces `name`, caches per (network, name) via the owned QueryClient, and is
+* protected against out-of-order responses (distinct inputs → distinct query keys).
+*
+* Returns a discriminated union keyed on `status`; it never throws for expected
+* failures (they surface in the `error` arm) and never pairs a name with a
+* different name's resolved address (INV-24).
+*
+* @param name    - The name to resolve. `null` / empty / a value failing the
+*   adapter's `isValidName` yields `status: 'idle'` (never `error`).
+* @param options - `debounceMs` / `enabled` overrides.
+* @returns The current {@link UseResolveNameResult}.
+*/
+function useResolveName(name, options) {
+	const { config } = useNameResolutionContext();
+	return toNameResult(useResolutionEngine({
+		input: name,
+		namespace: "name",
+		debounceMs: options?.debounceMs ?? config.forwardDebounceMs,
+		enabled: options?.enabled ?? true,
+		shouldAttempt: (cap, normalized) => cap.isValidName(normalized),
+		getMethod: (cap) => cap.resolveName
+	}));
+}
+/**
+* Remap the engine's generic `input` to `name` (INV-24: keyed off the debounced
+* input carried in the engine result, not the live prop). Exhaustive over the
+* union so a new status cannot silently fall through (INV-23 / INV-42).
+*/
+function toNameResult(engine) {
+	switch (engine.status) {
+		case "idle": return { status: "idle" };
+		case "debouncing": return {
+			status: "debouncing",
+			name: engine.input
+		};
+		case "loading": return {
+			status: "loading",
+			name: engine.input
+		};
+		case "resolved": return {
+			status: "resolved",
+			name: engine.input,
+			data: engine.data
+		};
+		case "error": return {
+			status: "error",
+			name: engine.input,
+			error: engine.error,
+			retry: engine.retry
+		};
+	}
+}
+
+//#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
+	}));
+}
+/**
+* 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) {
+	switch (engine.status) {
+		case "idle": return { status: "idle" };
+		case "debouncing":
+		case "loading": return {
+			status: "loading",
+			address: engine.input
+		};
+		case "resolved": return {
+			status: "resolved",
+			address: engine.input,
+			data: engine.data
+		};
+		case "error": return {
+			status: "error",
+			address: engine.input,
+			error: engine.error,
+			retry: engine.retry
+		};
+	}
+}
+
+//#endregion
+//#region src/hooks/nameResolution/NameResolutionProvider.tsx
+/**
+* Optional provider that overrides resolution config and/or the QueryClient for
+* its subtree. It does NOT render a `QueryClientProvider`: the client is passed
+* explicitly to `useQuery` (INV-48), so no ambient react-query provider is needed.
+*
+* Config is merged field-by-field over {@link DEFAULT_CONFIG} (INV-30), and the
+* context value is memoized so a Provider re-render does not cascade to every hook
+* (INV-38).
+*/
+function NameResolutionProvider({ children, config, queryClient }) {
+	const value = (0, react.useMemo)(() => ({
+		queryClient: queryClient ?? getDefaultResolutionQueryClient(),
+		config: {
+			...DEFAULT_CONFIG,
+			...config
+		}
+	}), [queryClient, config]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(NameResolutionContext.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+//#region src/hooks/nameResolution/useRuntimeNameResolver.ts
+/**
+* Stable empty resolver returned when no runtime / capability is available.
+* No methods ⇒ the consuming field treats a typed name as unsupported and
+* surfaces `UNSUPPORTED_NETWORK` (INV-119) while hex behavior stays legacy.
+*/
+const EMPTY_RESOLVER = {};
+/**
+* Project the active runtime's `NameResolutionCapability` into the injected
+* {@link NameResolver} seam consumed by `@openzeppelin/ui-components` (SF-3, D3).
+* Mounted ambiently by the renderer:
+*
+* ```tsx
+* <NameResolverProvider {...useRuntimeNameResolver()}>{form}</NameResolverProvider>
+* ```
+*
+* 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
+* resolved through the field and the same name resolved by a bare
+* `useResolveName` hit the SAME cache entry: shared cache, dedupe, and
+* 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 active runtime, or runtime without the capability → empty resolver.
+* - Capability without `resolveName` → `isValidName` only; forward unsupported.
+*
+* When the capability is present but the network itself is unsupported, the
+* adapter's `resolveName` resolves `{ ok: false, error: UNSUPPORTED_NETWORK }`
+* and that result passes through unchanged.
+*
+* @returns A referentially stable {@link NameResolver} for the active runtime.
+*/
+function useRuntimeNameResolver() {
+	const walletState = (0, react.useContext)(WalletStateContext);
+	const { queryClient, config } = useNameResolutionContext();
+	const activeRuntime = walletState?.activeRuntime ?? null;
+	const capability = activeRuntime?.nameResolution;
+	const networkId = walletState?.activeNetworkId ?? "";
+	const runtimeInstanceId = getRuntimeInstanceId(activeRuntime);
+	return (0, react.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, 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
+		};
+	}, [
+		capability,
+		queryClient,
+		config,
+		networkId,
+		runtimeInstanceId
+	]);
+}
+
+//#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 (0, react.useMemo)(() => createResolveRuntime(ecosystemDefinition, {
+		profile,
+		options: {
+			...uiKit !== void 0 ? { uiKit } : {},
+			...enableMainnetL1MissFallback === true ? { nameResolution: { enableMainnetL1MissFallback: true } } : {}
+		}
+	}), [
+		ecosystemDefinition,
+		profile,
+		uiKit,
+		enableMainnetL1MissFallback
+	]);
+}
+
 //#endregion
 //#region src/components/WalletConnectionUI.tsx
 /**
@@ -1114,6 +1778,10 @@ const NetworkSwitchManager = ({ wallet, networkCatalog, targetNetworkId, onNetwo
 //#endregion
 exports.AnalyticsContext = AnalyticsContext;
 exports.AnalyticsProvider = AnalyticsProvider;
+exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
+exports.DEFAULT_RUNTIME_CREATION_CONFIG = DEFAULT_RUNTIME_CREATION_CONFIG;
+exports.NameResolutionContext = NameResolutionContext;
+exports.NameResolutionProvider = NameResolutionProvider;
 exports.NetworkSwitchManager = NetworkSwitchManager;
 exports.RuntimeContext = RuntimeContext;
 exports.RuntimeProvider = RuntimeProvider;
@@ -1122,13 +1790,20 @@ exports.WalletConnectionHeader = WalletConnectionHeader;
 exports.WalletConnectionUI = WalletConnectionUI;
 exports.WalletStateContext = WalletStateContext;
 exports.WalletStateProvider = WalletStateProvider;
+exports.createResolveRuntime = createResolveRuntime;
+exports.isMainnetL1MissFallbackEnabled = isMainnetL1MissFallbackEnabled;
 exports.useAnalytics = useAnalytics;
 exports.useDerivedAccountStatus = useDerivedAccountStatus;
 exports.useDerivedChainInfo = useDerivedChainInfo;
 exports.useDerivedConnectStatus = useDerivedConnectStatus;
 exports.useDerivedDisconnect = useDerivedDisconnect;
 exports.useDerivedSwitchChainStatus = useDerivedSwitchChainStatus;
+exports.useNameResolutionContext = useNameResolutionContext;
+exports.useResolveAddress = useResolveAddress;
+exports.useResolveName = useResolveName;
+exports.useResolveRuntime = useResolveRuntime;
 exports.useRuntimeContext = useRuntimeContext;
+exports.useRuntimeNameResolver = useRuntimeNameResolver;
 exports.useWalletComponents = useWalletComponents;
 exports.useWalletReconnectionHandler = useWalletReconnectionHandler;
 exports.useWalletState = useWalletState;