@openzeppelin/ui-components 3.3.1 → 3.5.0

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { a as getValidationStateClasses, c as isDuplicateMapKey, d as INTEGER_HTML_PATTERN, f as INTEGER_INPUT_PATTERN, i as getErrorMessage, l as validateField, n as createValidationResult, o as handleValidationError, p as INTEGER_PATTERN, r as formatValidationError, s as hasFieldError, t as ErrorMessage, u as validateMapEntries } from "./ErrorMessage-BqOEJm84.mjs";
 import * as AccordionPrimitive from "@radix-ui/react-accordion";
 import { cva } from "class-variance-authority";
-import { AlertCircle, Calendar as Calendar$1, Check, CheckCircle, CheckCircle2, CheckIcon, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, Circle, ClipboardPaste, CloudOff, Copy, DollarSign, ExternalLink as ExternalLink$1, ExternalLinkIcon, Eye, EyeOff, File, FileText, GripVertical, Hash, Info, Loader2, Menu, MoreHorizontal, Network, Pencil, PencilLine, Plus, Search, Settings, Timer, Upload, X } from "lucide-react";
+import { AlertCircle, Calendar as Calendar$1, Check, CheckCircle, CheckCircle2, CheckIcon, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, Circle, ClipboardPaste, CloudOff, Copy, DollarSign, ExternalLink as ExternalLink$1, ExternalLinkIcon, Eye, EyeOff, File, FileText, GripVertical, Hash, Info, Loader2, Menu, MoreHorizontal, Network, Pencil, PencilLine, Plus, Search, Settings, Timer, TriangleAlert, Upload, X } from "lucide-react";
 import * as React$1 from "react";
 import React, { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { classifyAddressCandidates, cn, getDefaultValueForType, getHostedNetworkAvailabilityNoticeCopy, getInvalidUrlMessage, getServiceDisplayName, isNetworkAvailabilityPolicyActive, isValidUrl, parseDelimitedAddressInput, truncateMiddle, validateBytesSimple } from "@openzeppelin/ui-utils";
+import { classifyAddressCandidates, classifyAddressInput, cn, crossNetworkFallbackMessageNames, getDefaultValueForType, getFallbackNetworks, getHostedNetworkAvailabilityNoticeCopy, getInvalidUrlMessage, getServiceDisplayName, isChainScopeMismatch, isCrossNetworkFallback, isNetworkAvailabilityPolicyActive, isValidUrl, logger, nameResolutionChainScopeMismatchMessage, nameResolutionCrossNetworkFallbackMessage, nameResolutionMessageForCode, parseDelimitedAddressInput, truncateMiddle, validateBytesSimple } from "@openzeppelin/ui-utils";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 import { Slot, Slottable } from "@radix-ui/react-slot";
@@ -14,7 +14,7 @@ import { format } from "date-fns";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
-import { Controller, FormProvider, useFieldArray, useForm, useFormContext, useWatch } from "react-hook-form";
+import { Controller, FormProvider, useController, useFieldArray, useForm, useFormContext, useFormState, useWatch } from "react-hook-form";
 import * as LabelPrimitive from "@radix-ui/react-label";
 import * as ProgressPrimitive from "@radix-ui/react-progress";
 import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
@@ -26,7 +26,7 @@ import { Toaster as Toaster$1, toast } from "sonner";
 import { useTheme } from "next-themes";
 
 //#region src/version.ts
-const VERSION = "3.3.1";
+const VERSION = "3.5.0";
 
 //#endregion
 //#region src/components/ui/accordion.tsx
@@ -119,6 +119,50 @@ const TooltipContent = React$1.forwardRef(({ className, sideOffset = 4, ...props
 }) }));
 TooltipContent.displayName = TooltipPrimitive.Content.displayName;
 
+//#endregion
+//#region src/components/ui/address-display/address-avatar.tsx
+/**
+* Allowlist for name-owner-controlled avatar URLs at the render site.
+* Only `https:` and `data:image/*` pass; `http:` (mixed content), `javascript:`,
+* and other schemes are dropped. Does not rely on adapter sanitization.
+*/
+function isAllowedAvatarSrc(src) {
+	try {
+		const url = new URL(src);
+		if (url.protocol === "https:") return true;
+		if (url.protocol === "data:") return /^data:image\/[a-z0-9.+-]+/i.test(src);
+		return false;
+	} catch {
+		return false;
+	}
+}
+/**
+* @internal Avatar image for a resolved name, hiding itself on load error
+* (never a broken-image icon) — the name renders as a complete, avatar-less
+* row. Purely presentational; its only state is the per-instance load-error
+* flag (INV-121).
+*
+* The error state is keyed to the current `src` rather than a bare boolean,
+* so it resets automatically when `src` changes — a virtualized/reused list
+* row that scrolls to a new address re-attempts its avatar instead of staying
+* permanently hidden by a prior URL's failure (INV-59).
+*
+* @param props - {@link AddressAvatarProps}.
+* @returns The avatar `<img>`, or `null` when the load failed for this `src`.
+*/
+function AddressAvatar({ src, alt = "", variant = "fill", sizeClassName }) {
+	const [failedSrc, setFailedSrc] = React$1.useState(null);
+	if (!isAllowedAvatarSrc(src)) return null;
+	if (failedSrc === src) return null;
+	return /* @__PURE__ */ jsx("img", {
+		src,
+		alt,
+		className: cn("object-cover", sizeClassName ?? (variant === "fill" ? "absolute inset-0 h-full w-full rounded-none" : "h-4 w-4 shrink-0 rounded-full")),
+		referrerPolicy: "no-referrer",
+		onError: () => setFailedSrc(src)
+	});
+}
+
 //#endregion
 //#region src/components/ui/address-display/context.ts
 /**
@@ -127,6 +171,14 @@ TooltipContent.displayName = TooltipPrimitive.Content.displayName;
 * only components (required by React Fast Refresh).
 */
 const AddressLabelContext = createContext(null);
+/**
+* @internal Shared context instance consumed by AddressDisplay,
+* AddressNameProvider, and useAddressName. Sibling of AddressLabelContext
+* (SF-4 INV-122): carries a synchronous, value-only reverse-name resolver.
+* Defaults to `null` — no provider means no resolution and a byte-identical
+* zero-injection render (INV-54).
+*/
+const AddressNameContext = createContext(null);
 
 //#endregion
 //#region src/components/ui/address-display/address-display.tsx
@@ -143,16 +195,37 @@ function usePrefersHover() {
 	}, []), () => typeof window !== "undefined" && typeof window.matchMedia !== "undefined" ? window.matchMedia("(hover: hover)").matches : true, () => true);
 }
 /**
+* Strip C0/C1 controls, bidi embeds/isolates, and zero-width characters from a
+* verified name at the display seam. ENSIP-15 normalization remains the
+* adapter's job; this only removes invisible directionality/control glyphs so
+* a raw render cannot spoof adjacent UI (homoglyph confusables are out of scope).
+*/
+function sanitizeVerifiedNameForDisplay(name) {
+	return name.replace(/[\u0000-\u001F\u007F-\u009F\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u206F\uFEFF]/g, "");
+}
+/**
 * Displays a blockchain address with optional truncation, copy button,
-* explorer link, tooltip, and human-readable label.
+* explorer link, tooltip, human-readable label, and (when an already-resolved
+* record is injected) a forward-verified name + avatar.
 *
-* Labels are resolved in priority order:
+* Labels are resolved in priority order (INV-56):
 * 1. Explicit `label` prop
 * 2. `AddressLabelContext` resolver (via `AddressLabelProvider`)
-* 3. No label (renders address only, identical to previous behavior)
+* 3. Forward-verified resolved name (`resolvedName` prop, else
+*    `AddressNameContext` via `AddressNameProvider`) — a record with
+*    `forwardVerified: false` is suppressed to hex (INV-52, LOCKED)
+* 4. No label (renders address only, identical to previous behavior)
+*
+* The component is synchronous and capability-free (INV-121): it never
+* resolves anything itself — it reads injected values. Hex renders on first
+* commit; the name+avatar swap in when the react layer feeds an updated
+* record (progressive enhancement, INV-61). With no `resolvedName` and no
+* `AddressNameProvider`, output is byte-identical to the pre-enhancement
+* component (INV-54, LOCKED).
 *
-* Pass `disableLabel` to suppress context-based resolution (e.g. when the
-* surrounding UI already shows a name, such as a contract selector).
+* Pass `disableLabel` to render fully raw — it suppresses both the context
+* alias and any injected resolved name (e.g. when the surrounding UI already
+* shows a name, such as a contract selector).
 *
 * @example
 * ```tsx
@@ -179,18 +252,37 @@ function usePrefersHover() {
 * // Inline variant (no chip background) — useful inside wallet bars
 * <AddressDisplay address="0x742d35Cc..." variant="inline" showTooltip showCopyButton />
 *
+* // Reverse-resolved name + avatar via an injected value (react layer owns the async)
+* <AddressDisplay address="0x742d35Cc..." resolvedName={record} showCopyButton />
+*
+* // Or subtree-wide via context (rows stay plain <AddressDisplay/>)
+* <AddressNameProvider resolveAddressName={readFromResolutionCache}>
+*   <AddressDisplay address="0x742d35Cc..." />
+* </AddressNameProvider>
+*
 * // Truncate only when an alias/label is present (full address when unlabeled)
 * <AddressDisplay address="G..." truncateWhenLabeled />
 * ```
 */
-function AddressDisplay({ address, truncate: truncateProp, truncateWhenLabeled = false, untruncateOnHover = false, startChars = 6, endChars = 4, showCopyButton = false, showCopyButtonOnHover = false, explorerUrl, label: labelProp, onLabelEdit: onLabelEditProp, networkId, disableLabel = false, showTooltip = false, variant = "chip", className, onPointerEnter, onPointerLeave, onMouseEnter, onMouseLeave, onClick, ...props }) {
+function AddressDisplay({ address, truncate: truncateProp, truncateWhenLabeled = false, untruncateOnHover = false, startChars = 6, endChars = 4, showCopyButton = false, showCopyButtonOnHover = false, explorerUrl, label: labelProp, onLabelEdit: onLabelEditProp, networkId, disableLabel = false, showTooltip = false, variant = "chip", avatar, avatarVariant = "fill", resolvedName, showCrossNetworkFallbackDisclaimer = true, className, onPointerEnter, onPointerLeave, onMouseEnter, onMouseLeave, onClick, ...props }) {
 	const [copied, setCopied] = React$1.useState(false);
 	const [isHovered, setIsHovered] = React$1.useState(false);
 	const copyTimeoutRef = React$1.useRef(null);
 	const prefersHover = usePrefersHover();
 	const resolver = React$1.useContext(AddressLabelContext);
+	const nameResolver = React$1.useContext(AddressNameContext);
 	const resolvedLabel = disableLabel ? void 0 : labelProp ?? resolver?.resolveLabel(address, networkId);
-	const effectiveTruncate = truncateProp !== void 0 ? truncateProp : truncateWhenLabeled ? Boolean(resolvedLabel) : true;
+	const record = disableLabel ? void 0 : resolvedName ?? nameResolver?.resolveAddressName(address, networkId);
+	const ensName = record?.forwardVerified === true ? sanitizeVerifiedNameForDisplay(record.name) : void 0;
+	const effectiveLabel = resolvedLabel ?? ensName;
+	const showFallbackNote = showCrossNetworkFallbackDisclaimer && ensName !== void 0 && effectiveLabel === ensName && record !== void 0 && isCrossNetworkFallback(record.provenance);
+	const fallbackNote = (() => {
+		if (!showFallbackNote) return void 0;
+		const networks = getFallbackNetworks(record.provenance);
+		if (networks === void 0) return void 0;
+		return nameResolutionCrossNetworkFallbackMessage(networks, crossNetworkFallbackMessageNames(networks, nameResolver?.resolveNetworkLabel));
+	})();
+	const effectiveTruncate = truncateProp !== void 0 ? truncateProp : truncateWhenLabeled ? Boolean(effectiveLabel) : true;
 	const contextEditHandler = React$1.useCallback(() => {
 		resolver?.onEditLabel?.(address, networkId);
 	}, [
@@ -264,6 +356,17 @@ function AddressDisplay({ address, truncate: truncateProp, truncateWhenLabeled =
 			children: /* @__PURE__ */ jsx(Pencil, { className: "h-3.5 w-3.5" })
 		})
 	] });
+	const ensAvatarUrl = ensName !== void 0 && resolvedLabel === void 0 ? record?.avatarUrl : void 0;
+	const effectiveAvatar = avatar ?? (ensAvatarUrl ? /* @__PURE__ */ jsx(AddressAvatar, {
+		src: ensAvatarUrl,
+		variant: avatarVariant
+	}) : void 0);
+	const isFillAvatar = avatarVariant === "fill" && Boolean(effectiveAvatar);
+	const fillAvatarChipClassName = isFillAvatar && isChip ? "overflow-hidden" : void 0;
+	const avatarSlot = effectiveAvatar ? /* @__PURE__ */ jsx("span", {
+		className: cn("flex shrink-0", isFillAvatar ? cn("relative w-9 self-stretch overflow-hidden mr-2", isChip && "-my-1 -ml-2") : "mr-1.5 items-center"),
+		children: effectiveAvatar
+	}) : null;
 	const shouldShowTooltip = showTooltip && effectiveTruncate;
 	const wrapWithTooltip = (content) => {
 		if (!shouldShowTooltip) return content;
@@ -278,33 +381,63 @@ function AddressDisplay({ address, truncate: truncateProp, truncateWhenLabeled =
 			})] })
 		});
 	};
-	if (resolvedLabel) return wrapWithTooltip(/* @__PURE__ */ jsxs("div", {
-		className: cn("group inline-flex max-w-full min-w-0 flex-col", isChip && "rounded-md bg-slate-100 px-2 py-1", "text-xs text-slate-700", expandInteractionClassName, className),
-		onPointerEnter: handlePointerEnter,
-		onPointerLeave: handlePointerLeave,
-		onClick: handleUntruncateClick,
-		...props,
-		children: [/* @__PURE__ */ jsx("span", {
-			className: "truncate font-sans font-medium text-slate-900 leading-snug",
-			children: resolvedLabel
+	if (effectiveLabel) {
+		const labelColumn = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("span", {
+			className: "inline-flex min-w-0 max-w-full items-center gap-1",
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "truncate font-sans font-medium text-slate-900 leading-snug",
+				children: effectiveLabel
+			}), fallbackNote && showCrossNetworkFallbackDisclaimer ? /* @__PURE__ */ jsx(TooltipProvider, {
+				delayDuration: 300,
+				children: /* @__PURE__ */ jsxs(Tooltip, { children: [/* @__PURE__ */ jsx(TooltipTrigger, {
+					asChild: true,
+					children: /* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "inline-flex shrink-0 rounded-sm text-amber-500 outline-none focus-visible:ring-2 focus-visible:ring-amber-500/50",
+						"aria-label": fallbackNote,
+						children: /* @__PURE__ */ jsx(TriangleAlert, {
+							className: "h-3 w-3",
+							"aria-hidden": true
+						})
+					})
+				}), /* @__PURE__ */ jsx(TooltipContent, {
+					className: "max-w-xs font-sans text-xs font-normal normal-case",
+					children: fallbackNote
+				})] })
+			}) : null]
 		}), /* @__PURE__ */ jsxs("div", {
 			className: "flex min-w-0 items-center font-mono text-[10px] text-slate-400 leading-snug",
 			children: [/* @__PURE__ */ jsx("span", {
 				className: addressTextClassName,
 				children: displayAddress
 			}), actionButtons]
-		})]
-	}));
+		})] });
+		return wrapWithTooltip(/* @__PURE__ */ jsx("div", {
+			className: cn("group inline-flex max-w-full min-w-0", effectiveAvatar ? "items-center" : "flex-col", isChip && "rounded-md bg-slate-100 px-2 py-1", fillAvatarChipClassName, "text-xs text-slate-700", expandInteractionClassName, className),
+			onPointerEnter: handlePointerEnter,
+			onPointerLeave: handlePointerLeave,
+			onClick: handleUntruncateClick,
+			...props,
+			children: effectiveAvatar ? /* @__PURE__ */ jsxs(Fragment, { children: [avatarSlot, /* @__PURE__ */ jsx("div", {
+				className: "inline-flex min-w-0 flex-col",
+				children: labelColumn
+			})] }) : labelColumn
+		}));
+	}
 	return wrapWithTooltip(/* @__PURE__ */ jsxs("div", {
-		className: cn("group inline-flex max-w-full min-w-0 items-center", isChip && "rounded-md bg-slate-100 px-2 py-1", "text-xs font-mono text-slate-700", expandInteractionClassName, className),
+		className: cn("group inline-flex max-w-full min-w-0 items-center", isChip && "rounded-md bg-slate-100 px-2 py-1", fillAvatarChipClassName, "text-xs font-mono text-slate-700", expandInteractionClassName, className),
 		onPointerEnter: handlePointerEnter,
 		onPointerLeave: handlePointerLeave,
 		onClick: handleUntruncateClick,
 		...props,
-		children: [/* @__PURE__ */ jsx("span", {
-			className: addressTextClassName,
-			children: displayAddress
-		}), actionButtons]
+		children: [
+			avatarSlot,
+			/* @__PURE__ */ jsx("span", {
+				className: addressTextClassName,
+				children: displayAddress
+			}),
+			actionButtons
+		]
 	}));
 }
 
@@ -402,6 +535,82 @@ function useAddressLabel(address, networkId) {
 	};
 }
 
+//#endregion
+//#region src/components/ui/address-display/address-name-context.tsx
+/**
+* Address Name Context
+*
+* Provides a React context for surfacing already-resolved reverse name
+* records (`ResolvedName`) for blockchain addresses. When an
+* `AddressNameProvider` is mounted, every `AddressDisplay` in the subtree
+* reads its record synchronously — no call-site changes — and renders the
+* name/avatar only when the record is forward-verified (INV-52).
+*
+* Structural mirror of `AddressLabelProvider` (INV-122): synchronous,
+* value-only, no-op by default. The resolver implementation lives in the
+* react/renderer layer, which bridges async resolution state into this
+* synchronous read; this file stays capability-free (INV-121).
+*
+* @example
+* ```tsx
+* import { AddressNameProvider } from '@openzeppelin/ui-components';
+*
+* <AddressNameProvider resolveAddressName={readFromResolutionCache}>
+*   <TxHistory />  {// rows are plain <AddressDisplay/> — verified names fill in }
+* </AddressNameProvider>
+* ```
+*/
+/**
+* Provides reverse-name resolution to all `AddressDisplay` instances in the
+* subtree. `resolveAddressName` MUST be synchronous — it is called during
+* render (INV-122). A resolver that returns `undefined` for an address is
+* behaviorally identical to mounting no provider (INV-54).
+*
+* @param props - Resolver function and children
+*/
+function AddressNameProvider({ children, resolveAddressName, resolveNetworkLabel }) {
+	const value = React$1.useMemo(() => ({
+		resolveAddressName,
+		resolveNetworkLabel
+	}), [resolveAddressName, resolveNetworkLabel]);
+	return /* @__PURE__ */ jsx(AddressNameContext.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+//#region src/components/ui/address-display/use-address-name.ts
+/**
+* Convenience hook for reading a reverse name record from the nearest
+* `AddressNameProvider`.
+*
+* Kept in its own file so that `address-name-context.tsx` exports only
+* components (required by React Fast Refresh) — mirrors `use-address-label.ts`.
+*/
+/**
+* Reads the `AddressNameContext` for one address, synchronously (INV-122).
+* Returns `{ record: undefined }` when no provider is mounted — never throws,
+* never suspends. Note the record is returned verbatim: callers rendering a
+* name from it must apply the same `forwardVerified === true` gate that
+* `AddressDisplay` applies (INV-52).
+*
+* @param address - The blockchain address to reverse-resolve
+* @param networkId - Optional network identifier scoping the lookup
+* @returns The current best-known record for the address
+*
+* @example
+* ```tsx
+* function EnsBadge({ address }: { address: string }) {
+*   const { record } = useAddressName(address);
+*   return record?.forwardVerified ? <Badge>{record.name}</Badge> : null;
+* }
+* ```
+*/
+function useAddressName(address, networkId) {
+	return { record: React$1.useContext(AddressNameContext)?.resolveAddressName(address, networkId) };
+}
+
 //#endregion
 //#region src/components/ui/alert.tsx
 const alertVariants = cva("relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground", {
@@ -2539,6 +2748,43 @@ function WizardLayout(props) {
 	});
 }
 
+//#endregion
+//#region src/components/fields/address-suggestion/AddressSuggestionList.tsx
+/**
+* Render the suggestion dropdown. Returns `null` when there are no suggestions
+* (the consuming field also gates on `hasSuggestions`, so this is a safety net).
+*
+* @param props - {@link AddressSuggestionListProps}.
+*/
+function AddressSuggestionList({ id, suggestions, highlightedIndex, onSelect, onHighlight }) {
+	if (suggestions.length === 0) return null;
+	return /* @__PURE__ */ jsx("div", {
+		id: `${id}-suggestions`,
+		className: cn("absolute z-50 mt-1 w-full rounded-md border border-border bg-popover shadow-md", "max-h-48 overflow-auto"),
+		role: "listbox",
+		children: suggestions.map((s, i) => /* @__PURE__ */ jsxs("button", {
+			id: `${id}-suggestion-${i}`,
+			type: "button",
+			role: "option",
+			"aria-selected": i === highlightedIndex,
+			className: cn("flex w-full flex-col px-3 py-2 text-left text-sm", "hover:bg-selected/10", i === highlightedIndex && "bg-selected/10"),
+			onMouseDown: (e) => {
+				e.preventDefault();
+				onSelect(s);
+			},
+			onMouseEnter: () => onHighlight(i),
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "font-medium",
+				children: s.label
+			}), /* @__PURE__ */ jsx("span", {
+				className: "truncate font-mono text-xs text-muted-foreground",
+				children: s.value
+			})]
+		}, `${s.value}-${s.description ?? i}`))
+	});
+}
+AddressSuggestionList.displayName = "AddressSuggestionList";
+
 //#endregion
 //#region src/components/fields/address-suggestion/context.ts
 /**
@@ -2548,6 +2794,372 @@ function WizardLayout(props) {
 */
 const AddressSuggestionContext = createContext(null);
 
+//#endregion
+//#region src/components/fields/address-suggestion/useAddressSuggestionField.ts
+/**
+* Headless suggestion-dropdown behavior for address fields.
+*
+* Extracted from `AddressField`'s inline dropdown logic (SF-3, D9) into one
+* reusable headless hook the base `AddressField` consumes — no divergence, no
+* regression (INV-72). It owns:
+*   - `AddressSuggestionContext` resolution (explicit `suggestions` prop overrides),
+*   - the `MAX_SUGGESTIONS` (5) cap on context-resolved lists,
+*   - the 200 ms suggestion debounce,
+*   - keyboard highlight state with wrapping ArrowUp / ArrowDown navigation,
+*   - click-outside-to-close.
+*
+* It is capability-free and chain-agnostic — nothing about ENS or any chain
+* leaks into `@openzeppelin/ui-components`. The consuming field owns the RHF
+* value write on selection and the Enter / Escape input handlers; this hook
+* exposes the state and primitives they need.
+*
+* Distinct from the pre-existing convenience hook `useAddressSuggestions(query,
+* networkId)`, which resolves a raw suggestion list from context with no
+* debounce / cap / keyboard state — that hook is unchanged and still exported.
+*
+* @see INV-72 (suggestion-dropdown behavior preserved with zero regression; SF-5 depends)
+* @see INV-94 (legacy a11y + suggestion keyboard contract preserved verbatim)
+*/
+/** Suggestion debounce window (ms). Matches the legacy `AddressField`. */
+const DEBOUNCE_MS = 200;
+/** Cap on context-resolved suggestions. Explicit arrays are rendered as-is. */
+const MAX_SUGGESTIONS = 5;
+/**
+* Headless address-suggestion dropdown behavior. See the module docstring for
+* the full behavior contract.
+*
+* @param args - {@link UseAddressSuggestionFieldArgs}.
+* @returns {@link UseAddressSuggestionFieldResult}.
+*/
+function useAddressSuggestionField({ inputValue, suggestions: suggestionsProp, networkId }) {
+	const contextResolver = useContext(AddressSuggestionContext);
+	const containerRef = useRef(null);
+	const [debouncedQuery, setDebouncedQuery] = useState("");
+	const [showSuggestions, setShowSuggestions] = useState(false);
+	const [highlightedIndex, setHighlightedIndex] = useState(-1);
+	useEffect(() => {
+		if (!inputValue.trim()) {
+			setDebouncedQuery("");
+			return;
+		}
+		const timer = setTimeout(() => setDebouncedQuery(inputValue), DEBOUNCE_MS);
+		return () => clearTimeout(timer);
+	}, [inputValue]);
+	const suggestionsDisabled = suggestionsProp === false;
+	const resolvedSuggestions = useMemo(() => {
+		if (suggestionsDisabled) return [];
+		if (Array.isArray(suggestionsProp)) return suggestionsProp;
+		if (!contextResolver || !debouncedQuery.trim()) return [];
+		return contextResolver.resolveSuggestions(debouncedQuery, networkId).slice(0, MAX_SUGGESTIONS);
+	}, [
+		suggestionsDisabled,
+		suggestionsProp,
+		contextResolver,
+		debouncedQuery,
+		networkId
+	]);
+	const hasSuggestions = showSuggestions && resolvedSuggestions.length > 0;
+	useEffect(() => {
+		let active = true;
+		const handleClickOutside = (e) => {
+			if (active && containerRef.current && !containerRef.current.contains(e.target)) setShowSuggestions(false);
+		};
+		document.addEventListener("mousedown", handleClickOutside);
+		return () => {
+			active = false;
+			document.removeEventListener("mousedown", handleClickOutside);
+		};
+	}, []);
+	const onContainerKeyDown = useCallback((e) => {
+		if (!hasSuggestions) return;
+		if (e.key === "ArrowDown") {
+			e.preventDefault();
+			setHighlightedIndex((prev) => prev < resolvedSuggestions.length - 1 ? prev + 1 : 0);
+		} else if (e.key === "ArrowUp") {
+			e.preventDefault();
+			setHighlightedIndex((prev) => prev > 0 ? prev - 1 : resolvedSuggestions.length - 1);
+		}
+	}, [hasSuggestions, resolvedSuggestions.length]);
+	const onInputChange = useCallback((value) => {
+		setShowSuggestions(value.length > 0);
+		setHighlightedIndex(-1);
+	}, []);
+	return {
+		containerRef,
+		resolvedSuggestions,
+		hasSuggestions,
+		highlightedIndex,
+		suggestionsDisabled,
+		setHighlightedIndex,
+		closeSuggestions: useCallback(() => {
+			setShowSuggestions(false);
+			setHighlightedIndex(-1);
+		}, []),
+		onInputChange,
+		onContainerKeyDown
+	};
+}
+
+//#endregion
+//#region src/components/fields/name-resolution/useInjectedNameResolution.ts
+/**
+* Injected name-resolution machine (SF-3).
+*
+* A thin, capability-free async machine that `AddressField` consumes: given a
+* typed input and the injected `resolveName`, it debounces, dispatches, tracks
+* status, and applies the out-of-order name-drop guard (INV-117). It is the
+* component-boundary analogue of SF-2's `useResolveName`, with all hard
+* mechanics (cache, dedupe, retries, UNSUPPORTED synthesis) deliberately left
+* behind the injected function — this hook does ONLY debounce + status
+* derivation + the funds guards.
+*
+* The machine holds no resolved-hex cache of its own (INV-85): its single
+* `settled` record is valid only while it matches the current debounced input,
+* the current resolver function identity, and the current retry attempt — any
+* mismatch derives `loading`, never a stale `resolved`.
+*
+* Resolver-identity-churn backstop (INV-123/124/125). The dispatch effect keys
+* on the injected `resolveName` function identity, so an unstable (non-memoized)
+* integrator resolver re-fires it on every render. To keep that from becoming an
+* unbounded RPC loop (rate-ban + cost + funds-path DoS), the machine caps
+* dispatches per resolution intent — the pair (normalized debounced input × retry
+* attempt) — at {@link MAX_DISPATCHES_PER_INTENT}, regardless of render count and
+* regardless of how many times `resolveName` identity changes under that intent.
+* The budget resets only on intent change (a new typed name, or `retry()`) or when
+* the field leaves the active name-resolution path (clear / disable). It does
+* *not* reset on `settled.source` mismatch: that would let two settling sources
+* flap and refill the counter (settling churn), silently defeating INV-123. A
+* genuine network swap still re-dispatches within the shared intent budget
+* (INV-119 / acceptance #5) because a single identity change costs one unit.
+* Clear→retype of the same name gets a fresh budget via the leave-path reset, so
+* it cannot accumulate toward the cap across cycles and then strand a later swap.
+* A churning identity that exhausts the budget emits a one-shot, development-only
+* warning (INV-124) and degrades to the safe gated state (bounded RPC, RHF value
+* `''`, submit gated, never a wrong hex, never a throw — INV-125). This backstop
+* is entirely internal: no signature, param, or return-type change; `AddressField`
+* consumes the machine unchanged.
+*/
+/**
+* Default debounce window (ms) for typed names — mirrors SF-2's
+* `forwardDebounceMs` default so the field and the bare hook feel identical.
+*/
+const NAME_RESOLUTION_DEBOUNCE_MS = 300;
+/**
+* Cap on resolver dispatches per resolution intent — the pair (normalized
+* debounced input × retry attempt) — regardless of how many times the field
+* re-renders or how many times `resolveName` identity changes under that intent
+* (INV-123). Chosen to sit comfortably above the dispatches a single displayed
+* input legitimately incurs (1 initial call + any human-initiated genuine network
+* swaps of that same name, each ≤1 unit — INV-119) and far below per-render
+* identity churn (hundreds/sec): a user does not switch networks eight times
+* while one unedited name sits in the field, whereas churn blows past eight
+* within milliseconds. The budget resets when the intent changes or when the
+* field leaves the name-resolution path (clear / disable) — never on
+* `settled.source` mismatch, so settling-source oscillation cannot refill it.
+*/
+const MAX_DISPATCHES_PER_INTENT = 8;
+/**
+* Debounce + dispatch + status derivation over an injected `resolveName`.
+*
+* Guarantees:
+* - INV-83: no call unless `enabled` (name-candidate + injected method), and
+*   never for a debounced copy that lags the current normalized input.
+* - INV-117: a settled result whose requested name ≠ the current debounced
+*   input is discarded (last-write-wins at the component boundary).
+* - INV-87: a rejecting resolver (contract violation) is mapped to a typed
+*   `ADAPTER_ERROR` — nothing throws into the render tree.
+* - INV-123: resolver dispatches are bounded per resolution intent (normalized
+*   debounced input × retry attempt) at {@link MAX_DISPATCHES_PER_INTENT},
+*   regardless of render count or resolver-identity oscillation; the budget
+*   resets on intent change or when leaving the name-resolution path — never on
+*   `settled.source` mismatch; `retry()` never consumes an existing budget.
+* - INV-124: an identity-churning resolver that exhausts the budget triggers a
+*   one-shot, development-only `logger.warn` (silent in production).
+* - INV-125: under sustained churn the field stays in the safe gated state — the
+*   perpetually-changing identity keeps failing the `settled.source` check, so
+*   the machine derives `loading`, never `resolved`; combined with INV-87 it
+*   never throws and never writes a hex.
+* - No `setState` after unmount: every dispatch is cancelled on cleanup.
+*
+* @param params - {@link UseInjectedNameResolutionParams}
+* @returns The current {@link InjectedNameResolutionResult}.
+*/
+function useInjectedNameResolution({ input, enabled, resolveName, debounceMs = NAME_RESOLUTION_DEBOUNCE_MS }) {
+	const normalized = input.trim().toLowerCase();
+	const [debounced, setDebounced] = useState(normalized);
+	const seededRef = useRef(false);
+	useEffect(() => {
+		if (!seededRef.current) {
+			seededRef.current = true;
+			return;
+		}
+		if (debounceMs <= 0) {
+			setDebounced(normalized);
+			return;
+		}
+		const timer = setTimeout(() => setDebounced(normalized), debounceMs);
+		return () => clearTimeout(timer);
+	}, [normalized, debounceMs]);
+	const [attempt, setAttempt] = useState(0);
+	const [settled, setSettled] = useState(null);
+	const currentTargetRef = useRef("");
+	currentTargetRef.current = enabled && resolveName ? debounced : "";
+	const intentKeyRef = useRef("");
+	const dispatchCountRef = useRef(0);
+	const churnWarnedRef = useRef(false);
+	const warnOnceOnChurn = useCallback(() => {
+		if (process.env.NODE_ENV === "production" || churnWarnedRef.current) return;
+		churnWarnedRef.current = true;
+		logger.warn("AddressField", "The injected name resolver changes identity on every render, so inline name resolution was bounded to prevent an unbounded RPC loop. Memoize the resolver (e.g. wrap it in useMemo, or use useRuntimeNameResolver from @openzeppelin/ui-react) so its function identity is stable across renders. See the ens-address-input integration guide.");
+	}, []);
+	useEffect(() => {
+		if (!enabled || !resolveName || debounced === "") {
+			intentKeyRef.current = "";
+			dispatchCountRef.current = 0;
+			return;
+		}
+		if (debounced !== normalized) return;
+		const intentKey = `${debounced}\u0000${attempt}`;
+		if (intentKeyRef.current !== intentKey) {
+			intentKeyRef.current = intentKey;
+			dispatchCountRef.current = 0;
+		}
+		if (dispatchCountRef.current >= MAX_DISPATCHES_PER_INTENT) {
+			warnOnceOnChurn();
+			return;
+		}
+		dispatchCountRef.current += 1;
+		let cancelled = false;
+		const requestedName = debounced;
+		const requestedAttempt = attempt;
+		const source = resolveName;
+		const settle = (result) => {
+			if (cancelled) return;
+			if (requestedName !== currentTargetRef.current) return;
+			setSettled({
+				name: requestedName,
+				result,
+				source,
+				attempt: requestedAttempt
+			});
+		};
+		source(requestedName).then(settle, (cause) => {
+			settle({
+				ok: false,
+				error: {
+					code: "ADAPTER_ERROR",
+					message: cause instanceof Error ? cause.message : String(cause),
+					cause
+				}
+			});
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		enabled,
+		resolveName,
+		debounced,
+		normalized,
+		attempt,
+		warnOnceOnChurn
+	]);
+	const retry = useCallback(() => {
+		setAttempt((current) => current + 1);
+	}, []);
+	if (!enabled || !resolveName || normalized === "") return { status: "idle" };
+	if (debounced !== normalized) return {
+		status: "debouncing",
+		name: normalized
+	};
+	if (settled !== null && settled.name === debounced && settled.source === resolveName && settled.attempt === attempt) {
+		if (settled.result.ok) return {
+			status: "resolved",
+			name: settled.name,
+			data: settled.result.value
+		};
+		return {
+			status: "error",
+			name: settled.name,
+			error: settled.result.error,
+			retry
+		};
+	}
+	return {
+		status: "loading",
+		name: normalized
+	};
+}
+
+//#endregion
+//#region src/components/fields/name-resolution/context.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 `@openzeppelin/ui-react`'s `NameResolutionContext` /
+* `WalletStateContext` (bundler pre-bundling / npm-installed consumers).
+*/
+const CONTEXT_KEY = Symbol.for("@openzeppelin/ui-components/NameResolverContext");
+function getOrCreateSharedContext() {
+	const globalScope = globalThis;
+	if (!globalScope[CONTEXT_KEY]) globalScope[CONTEXT_KEY] = createContext(null);
+	return globalScope[CONTEXT_KEY];
+}
+/**
+* @internal Shared context instance consumed by both AddressField and
+* NameResolverProvider (INV-118). Kept in its own file so component files
+* export only components (required by React Fast Refresh).
+*
+* `null` means no provider is mounted — every ENS branch in `AddressField` is
+* then dead code and the field is byte-identical to its pre-ENS behavior
+* (INV-82).
+*/
+const NameResolverContext = getOrCreateSharedContext();
+
+//#endregion
+//#region src/components/fields/name-resolution/useNameResolver.ts
+/**
+* Read the injected resolver context. Returns `null` when no
+* `NameResolverProvider` is mounted — the consuming field must then treat
+* every ENS branch as dead code (INV-82).
+*
+* @returns The extended context value, or `null` when no provider is mounted.
+*/
+function useNameResolver() {
+	return useContext(NameResolverContext);
+}
+
+//#endregion
+//#region src/components/fields/name-resolution/useResolvingAnnouncerCopy.ts
+/** Default escalation threshold for long-latency resolves (INV-129/130). */
+const RESOLVING_ANNOUNCER_ESCALATE_AFTER_MS = 3e3;
+const PHASE_1_COPY = "Resolving…";
+const PHASE_2_COPY = "Still resolving…";
+/**
+* Returns the announcer string for debouncing/loading arms.
+* Phase 1: "Resolving…" (SF-3 default, unchanged for first N ms).
+* Phase 2: "Still resolving…" after threshold — reduces frozen perception
+* during CCIP-scale latency without naming gateway/CCIP/v2.
+*/
+function useResolvingAnnouncerCopy({ isPending, escalateAfterMs = RESOLVING_ANNOUNCER_ESCALATE_AFTER_MS }) {
+	const [escalated, setEscalated] = useState(false);
+	useEffect(() => {
+		if (!isPending) {
+			setEscalated(false);
+			return;
+		}
+		setEscalated(false);
+		const timeoutId = window.setTimeout(() => {
+			setEscalated(true);
+		}, escalateAfterMs);
+		return () => {
+			window.clearTimeout(timeoutId);
+		};
+	}, [isPending, escalateAfterMs]);
+	if (!isPending) return PHASE_1_COPY;
+	return escalated ? PHASE_2_COPY : PHASE_1_COPY;
+}
+
 //#endregion
 //#region src/components/fields/utils/accessibility.ts
 /**
@@ -2739,8 +3351,26 @@ function getWidthClasses(width) {
 
 //#endregion
 //#region src/components/fields/AddressField.tsx
-const DEBOUNCE_MS = 200;
-const MAX_SUGGESTIONS = 5;
+/**
+* Non-user-facing gate string returned by the sync validator while a typed name
+* is resolving, so `formState.isValid` is `false` even for an optional field
+* (INV-84). The visible message comes from the aria-live region, never this string.
+*/
+const NAME_RESOLUTION_PENDING_GATE = "__ens_name_resolution_pending__";
+/** Codes for which a `retry()` affordance is offered — transient only (INV-90). */
+const TRANSIENT_ERROR_CODES = new Set([
+	"RESOLUTION_TIMEOUT",
+	"EXTERNAL_GATEWAY_ERROR",
+	"ADAPTER_ERROR"
+]);
+/**
+* Normalize a typed name for the resolved-write match guard: trim then lowercase,
+* mirroring the SF-2 engine (whose echoed `result.name` is already normalized).
+* Comparing the raw typed value would spuriously fail on case/whitespace (INV-79).
+*/
+function normalizeResolvedName(value) {
+	return value.trim().toLowerCase();
+}
 /**
 * Address input field component specifically designed for blockchain addresses via React Hook Form integration.
 *
@@ -2768,19 +3398,36 @@ const MAX_SUGGESTIONS = 5;
 *    Pass `suggestions={false}` to opt out when a provider is mounted.
 *
 * The suggestion dropdown includes built-in debouncing, keyboard navigation (Arrow keys,
-* Enter, Escape), click-outside dismissal, and ARIA listbox semantics.
+* Enter, Escape), click-outside dismissal, and ARIA listbox semantics — all provided by
+* the shared headless `useAddressSuggestionField` hook + `AddressSuggestionList`.
+*
+* **Inline name resolution (SF-3, opt-in via context).** When a
+* `NameResolverProvider` is mounted, the field also accepts a name (e.g.
+* `alice.eth`): the name is resolved inline through the injected `resolveName`
+* and the RHF form value becomes the resolved hex — never the name, never a
+* silently-coerced value. The correctness spine is a shadow-state model:
+* the `<input>` always shows the typed string (`inputValue`, INV-69); the RHF
+* value is `''` for every unresolved name state so submit stays gated with no
+* async validator (INV-75); the single name→hex write fires only on
+* `resolved` + normalized name-match (INV-79/80). With **no** provider mounted
+* every resolution branch below is dead code and the field is byte-identical
+* to its pre-ENS behavior (INV-82 — the LOCKED backward-compat guarantee).
+* The component stays capability-free: it never reads a runtime or wallet
+* state; everything arrives through the injected context (INV-118).
 */
-function AddressField({ id, label, placeholder, helperText, control, name, width = "full", validation, addressing, readOnly, suggestions: suggestionsProp, onSuggestionSelect }) {
+function AddressField({ id, label, placeholder, helperText, control, name, width = "full", validation, addressing, readOnly, suggestions: suggestionsProp, onSuggestionSelect, onResolvedNameChange, showCrossNetworkFallbackDisclaimer = true }) {
 	const isRequired = !!validation?.required;
 	const errorId = `${id}-error`;
 	const descriptionId = `${id}-description`;
-	const contextResolver = useContext(AddressSuggestionContext);
-	const containerRef = useRef(null);
+	const resolutionRegionId = `${id}-resolution`;
+	const resolver = useNameResolver();
+	const resolveName = resolver?.resolveName;
+	const isValidName = resolver?.isValidName;
+	const activeNetworkId = resolver?.activeNetworkId;
+	const activeNetworkName = resolver?.activeNetworkName;
+	const resolveNetworkLabel = resolver?.resolveNetworkLabel;
 	const lastSetValueRef = useRef("");
 	const [inputValue, setInputValue] = useState("");
-	const [debouncedQuery, setDebouncedQuery] = useState("");
-	const [showSuggestions, setShowSuggestions] = useState(false);
-	const [highlightedIndex, setHighlightedIndex] = useState(-1);
 	const watchedFieldValue = useWatch({
 		control,
 		name
@@ -2792,173 +3439,277 @@ function AddressField({ id, label, placeholder, helperText, control, name, width
 			setInputValue(currentFieldValue);
 		}
 	}, [watchedFieldValue]);
+	const isValidAddress = useMemo(() => addressing ? (v) => addressing.isValidAddress(v) : void 0, [addressing]);
+	const classification = useMemo(() => classifyAddressInput(inputValue, {
+		isValidAddress,
+		isValidName
+	}), [
+		inputValue,
+		isValidAddress,
+		isValidName
+	]);
+	const resolverActive = resolver !== null && classification === "name-candidate";
+	const nameEnabled = resolverActive && resolveName != null;
+	const forwardUnsupported = resolverActive && resolveName == null;
+	const resolution = useInjectedNameResolution({
+		input: inputValue,
+		enabled: nameEnabled,
+		resolveName
+	});
+	const chainScopeBlocked = resolution.status === "resolved" && isChainScopeMismatch(resolution.data.provenance, activeNetworkId);
+	const resolvingAnnouncerCopy = useResolvingAnnouncerCopy({ isPending: !forwardUnsupported && (resolution.status === "debouncing" || resolution.status === "loading") });
+	const resolverPresentRef = useRef(false);
+	const classificationRef = useRef("empty");
+	const statusRef = useRef("idle");
+	const resolvedNameRef = useRef(void 0);
+	const chainScopeBlockedRef = useRef(false);
+	const validationRef = useRef(validation);
+	const addressingRef = useRef(addressing);
+	resolverPresentRef.current = resolver !== null;
+	classificationRef.current = classification;
+	statusRef.current = resolution.status;
+	resolvedNameRef.current = resolution.status === "resolved" ? resolution.name : void 0;
+	chainScopeBlockedRef.current = chainScopeBlocked;
+	validationRef.current = validation;
+	addressingRef.current = addressing;
+	const { field, fieldState } = useController({
+		control,
+		name,
+		rules: { validate: useCallback((value) => {
+			if (resolverPresentRef.current && classificationRef.current === "name-candidate" && (statusRef.current !== "resolved" || chainScopeBlockedRef.current)) return NAME_RESOLUTION_PENDING_GATE;
+			if (value === void 0 || value === null || value === "") return validationRef.current?.required ? "This field is required" : true;
+			const standardValidationResult = validateField(value, validationRef.current);
+			if (standardValidationResult !== true) return standardValidationResult;
+			if (addressingRef.current && typeof value === "string") {
+				if (!addressingRef.current.isValidAddress(value)) return "Invalid address format for the selected chain";
+			}
+			return true;
+		}, []) },
+		disabled: readOnly
+	});
+	const fieldOnChange = field.onChange;
+	const gateFormState = useFormState({
+		control,
+		disabled: resolver === null
+	});
+	const observedIsValid = resolver !== null && gateFormState.isValid;
+	const pendingNameGate = resolver !== null && classification === "name-candidate" && (resolution.status !== "resolved" || chainScopeBlocked);
 	useEffect(() => {
-		if (!inputValue.trim()) {
-			setDebouncedQuery("");
-			return;
+		if (pendingNameGate && observedIsValid) control.setError(name, {
+			type: "validate",
+			message: NAME_RESOLUTION_PENDING_GATE
+		});
+	}, [
+		pendingNameGate,
+		observedIsValid,
+		control,
+		name
+	]);
+	const resolvedAddress = resolution.status === "resolved" ? resolution.data.address : void 0;
+	const resolvedName = resolution.status === "resolved" ? resolution.name : void 0;
+	const isResolvedNameMatch = resolvedName !== void 0 && normalizeResolvedName(inputValue) === resolvedName;
+	useEffect(() => {
+		if (isResolvedNameMatch && resolvedAddress !== void 0 && !chainScopeBlocked) {
+			lastSetValueRef.current = resolvedAddress;
+			fieldOnChange(resolvedAddress);
 		}
-		const timer = setTimeout(() => setDebouncedQuery(inputValue), DEBOUNCE_MS);
-		return () => clearTimeout(timer);
-	}, [inputValue]);
-	const suggestionsDisabled = suggestionsProp === false;
-	const resolvedSuggestions = useMemo(() => {
-		if (suggestionsDisabled) return [];
-		if (Array.isArray(suggestionsProp)) return suggestionsProp;
-		if (!contextResolver || !debouncedQuery.trim()) return [];
-		return contextResolver.resolveSuggestions(debouncedQuery).slice(0, MAX_SUGGESTIONS);
 	}, [
-		suggestionsDisabled,
-		suggestionsProp,
-		contextResolver,
-		debouncedQuery
+		isResolvedNameMatch,
+		resolvedAddress,
+		chainScopeBlocked,
+		fieldOnChange
 	]);
-	const hasSuggestions = showSuggestions && resolvedSuggestions.length > 0;
+	const matchedName = isResolvedNameMatch ? resolvedName : void 0;
 	useEffect(() => {
-		let active = true;
-		const handleClickOutside = (e) => {
-			if (active && containerRef.current && !containerRef.current.contains(e.target)) setShowSuggestions(false);
-		};
-		document.addEventListener("mousedown", handleClickOutside);
-		return () => {
-			active = false;
-			document.removeEventListener("mousedown", handleClickOutside);
-		};
-	}, []);
-	const handleSuggestionKeyDown = useCallback((e) => {
-		if (!hasSuggestions) return;
-		if (e.key === "ArrowDown") {
-			e.preventDefault();
-			setHighlightedIndex((prev) => prev < resolvedSuggestions.length - 1 ? prev + 1 : 0);
-		} else if (e.key === "ArrowUp") {
+		onResolvedNameChange?.(matchedName);
+	}, [matchedName, onResolvedNameChange]);
+	const { containerRef, resolvedSuggestions, hasSuggestions, highlightedIndex, suggestionsDisabled, setHighlightedIndex, closeSuggestions, onInputChange, onContainerKeyDown } = useAddressSuggestionField({
+		inputValue,
+		suggestions: suggestionsProp
+	});
+	/**
+	* The single site for the typed/raw write (the name→hex write lives in the
+	* effect above). With no resolver this is the legacy write, verbatim (INV-82);
+	* with a resolver, only the `name-candidate` classification diverges:
+	*  - hex / malformed / empty → the raw value (legacy sync validate applies)
+	*  - name-candidate → `''` — gates submit and synchronously invalidates any
+	*    prior resolved hex before re-resolution (INV-75 / INV-81)
+	*/
+	const commitTypedValue = useCallback((value) => {
+		setInputValue(value);
+		if (!resolverPresentRef.current) {
+			lastSetValueRef.current = value;
+			fieldOnChange(value);
+			return;
+		}
+		const c = classifyAddressInput(value, {
+			isValidAddress,
+			isValidName
+		});
+		classificationRef.current = c;
+		if (c === "name-candidate") {
+			const normalized = normalizeResolvedName(value);
+			if (statusRef.current === "resolved" && resolvedNameRef.current === normalized && !chainScopeBlockedRef.current) return;
+			statusRef.current = "debouncing";
+			lastSetValueRef.current = "";
+			fieldOnChange("");
+		} else {
+			lastSetValueRef.current = value;
+			fieldOnChange(value);
+		}
+	}, [
+		fieldOnChange,
+		isValidAddress,
+		isValidName
+	]);
+	const handleInputChange = (e) => {
+		commitTypedValue(e.target.value);
+		onInputChange(e.target.value);
+	};
+	const applySuggestion = (suggestion) => {
+		commitTypedValue(suggestion.value);
+		onSuggestionSelect?.(suggestion);
+		closeSuggestions();
+	};
+	const handleKeyDown = (e) => {
+		if (hasSuggestions && e.key === "Enter" && highlightedIndex >= 0) {
 			e.preventDefault();
-			setHighlightedIndex((prev) => prev > 0 ? prev - 1 : resolvedSuggestions.length - 1);
+			applySuggestion(resolvedSuggestions[highlightedIndex]);
+			return;
 		}
-	}, [hasSuggestions, resolvedSuggestions.length]);
+		if (e.key === "Escape") {
+			if (hasSuggestions) {
+				closeSuggestions();
+				return;
+			}
+			handleEscapeKey(commitTypedValue, inputValue)(e);
+		}
+	};
+	const hasError = !!fieldState.error;
+	const isPendingGate = fieldState.error?.message === NAME_RESOLUTION_PENDING_GATE;
+	const hasRealError = hasError && !isPendingGate;
+	const shouldShowError = hasRealError && fieldState.isTouched;
+	const validationClasses = getValidationStateClasses(hasRealError ? fieldState.error : void 0, isPendingGate ? false : fieldState.isTouched);
+	const patternErrorMessage = validation?.pattern && typeof validation.pattern === "object" && "message" in validation.pattern ? validation.pattern.message : void 0;
+	const accessibilityProps = getAccessibilityProps({
+		id,
+		hasError: hasRealError,
+		isRequired,
+		hasHelperText: !!helperText
+	});
+	const renderOutcome = () => {
+		if (forwardUnsupported) return /* @__PURE__ */ jsx("span", {
+			role: "alert",
+			className: "text-destructive text-sm",
+			children: nameResolutionMessageForCode("UNSUPPORTED_NETWORK")
+		});
+		switch (resolution.status) {
+			case "idle": return null;
+			case "debouncing":
+			case "loading": return /* @__PURE__ */ jsx("span", {
+				className: "text-muted-foreground text-sm",
+				children: resolvingAnnouncerCopy
+			});
+			case "resolved":
+				if (chainScopeBlocked) return /* @__PURE__ */ jsx("span", {
+					role: "alert",
+					className: "text-destructive text-sm",
+					children: nameResolutionChainScopeMismatchMessage({ activeNetworkName })
+				});
+				const fallbackNetworks = showCrossNetworkFallbackDisclaimer && isCrossNetworkFallback(resolution.data.provenance) ? getFallbackNetworks(resolution.data.provenance) : void 0;
+				const fallbackMessage = fallbackNetworks && nameResolutionCrossNetworkFallbackMessage(fallbackNetworks, crossNetworkFallbackMessageNames(fallbackNetworks, resolveNetworkLabel));
+				return /* @__PURE__ */ jsxs("span", {
+					className: "text-sm",
+					children: [/* @__PURE__ */ jsxs("span", { children: ["Resolved to ", /* @__PURE__ */ jsx("code", {
+						className: "font-mono",
+						children: resolution.data.address
+					})] }), fallbackMessage ? /* @__PURE__ */ jsx("span", {
+						className: "mt-1 block text-muted-foreground text-xs",
+						role: "note",
+						children: fallbackMessage
+					}) : null]
+				});
+			case "error": {
+				const networkName = resolution.error.code === "UNSUPPORTED_NETWORK" ? resolution.error.networkId || void 0 : void 0;
+				const message = nameResolutionMessageForCode(resolution.error.code, { networkName });
+				const isTransient = TRANSIENT_ERROR_CODES.has(resolution.error.code);
+				const retry = resolution.retry;
+				return /* @__PURE__ */ jsxs("span", {
+					role: "alert",
+					className: "text-destructive text-sm",
+					children: [message, isTransient ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "ml-2 underline",
+						onClick: retry,
+						children: "Retry"
+					}) : null]
+				});
+			}
+		}
+	};
 	return /* @__PURE__ */ jsxs("div", {
 		className: `flex flex-col gap-2 ${width === "full" ? "w-full" : width === "half" ? "w-1/2" : "w-1/3"}`,
-		children: [label && /* @__PURE__ */ jsxs(Label, {
-			htmlFor: id,
-			children: [
-				label,
-				" ",
-				isRequired && /* @__PURE__ */ jsx("span", {
-					className: "text-destructive",
-					children: "*"
-				})
-			]
-		}), /* @__PURE__ */ jsx(Controller, {
-			control,
-			name,
-			rules: { validate: (value) => {
-				if (value === void 0 || value === null || value === "") return validation?.required ? "This field is required" : true;
-				const standardValidationResult = validateField(value, validation);
-				if (standardValidationResult !== true) return standardValidationResult;
-				if (addressing && typeof value === "string") {
-					if (!addressing.isValidAddress(value)) return "Invalid address format for the selected chain";
-				}
-				return true;
-			} },
-			disabled: readOnly,
-			render: ({ fieldState: { error, isTouched }, field }) => {
-				const hasError = !!error;
-				const shouldShowError = hasError && isTouched;
-				const validationClasses = getValidationStateClasses(error, isTouched);
-				const patternErrorMessage = validation?.pattern && typeof validation.pattern === "object" && "message" in validation.pattern ? validation.pattern.message : void 0;
-				const handleInputChange = (e) => {
-					const value = e.target.value;
-					field.onChange(value);
-					lastSetValueRef.current = value;
-					setInputValue(value);
-					setShowSuggestions(value.length > 0);
-					setHighlightedIndex(-1);
-				};
-				const applySuggestion = (suggestion) => {
-					field.onChange(suggestion.value);
-					onSuggestionSelect?.(suggestion);
-					lastSetValueRef.current = suggestion.value;
-					setInputValue(suggestion.value);
-					setShowSuggestions(false);
-					setHighlightedIndex(-1);
-				};
-				const handleKeyDown = (e) => {
-					if (hasSuggestions && e.key === "Enter" && highlightedIndex >= 0) {
-						e.preventDefault();
-						applySuggestion(resolvedSuggestions[highlightedIndex]);
-						return;
-					}
-					if (e.key === "Escape") {
-						if (hasSuggestions) {
-							setShowSuggestions(false);
-							return;
-						}
-						handleEscapeKey(field.onChange, field.value)(e);
-					}
-				};
-				const accessibilityProps = getAccessibilityProps({
-					id,
-					hasError,
-					isRequired,
-					hasHelperText: !!helperText
-				});
-				return /* @__PURE__ */ jsxs(Fragment, { children: [
-					/* @__PURE__ */ jsxs("div", {
-						ref: containerRef,
-						className: "relative",
-						onKeyDown: handleSuggestionKeyDown,
-						children: [/* @__PURE__ */ jsx(Input, {
-							...field,
-							id,
-							placeholder: placeholder || "0x...",
-							className: validationClasses,
-							onChange: handleInputChange,
-							onKeyDown: handleKeyDown,
-							"data-slot": "input",
-							value: field.value ?? "",
-							...accessibilityProps,
-							"aria-describedby": `${helperText ? descriptionId : ""} ${hasError ? errorId : ""}`,
-							"aria-expanded": hasSuggestions,
-							"aria-autocomplete": suggestionsDisabled ? void 0 : "list",
-							"aria-controls": hasSuggestions ? `${id}-suggestions` : void 0,
-							"aria-activedescendant": hasSuggestions && highlightedIndex >= 0 ? `${id}-suggestion-${highlightedIndex}` : void 0,
-							disabled: readOnly
-						}), hasSuggestions && /* @__PURE__ */ jsx("div", {
-							id: `${id}-suggestions`,
-							className: cn("absolute z-50 mt-1 w-full rounded-md border border-border bg-popover shadow-md", "max-h-48 overflow-auto"),
-							role: "listbox",
-							children: resolvedSuggestions.map((s, i) => /* @__PURE__ */ jsxs("button", {
-								id: `${id}-suggestion-${i}`,
-								type: "button",
-								role: "option",
-								"aria-selected": i === highlightedIndex,
-								className: cn("flex w-full flex-col px-3 py-2 text-left text-sm", "hover:bg-selected/10", i === highlightedIndex && "bg-selected/10"),
-								onMouseDown: (e) => {
-									e.preventDefault();
-									applySuggestion(s);
-								},
-								onMouseEnter: () => setHighlightedIndex(i),
-								children: [/* @__PURE__ */ jsx("span", {
-									className: "font-medium",
-									children: s.label
-								}), /* @__PURE__ */ jsx("span", {
-									className: "truncate font-mono text-xs text-muted-foreground",
-									children: s.value
-								})]
-							}, `${s.value}-${s.description ?? i}`))
-						})]
-					}),
-					helperText && /* @__PURE__ */ jsx("div", {
-						id: descriptionId,
-						className: "text-muted-foreground text-sm",
-						children: helperText
-					}),
-					/* @__PURE__ */ jsx(ErrorMessage, {
-						error,
-						id: errorId,
-						message: shouldShowError ? error?.message || patternErrorMessage : void 0
+		children: [
+			label && /* @__PURE__ */ jsxs(Label, {
+				htmlFor: id,
+				children: [
+					label,
+					" ",
+					isRequired && /* @__PURE__ */ jsx("span", {
+						className: "text-destructive",
+						children: "*"
 					})
-				] });
-			}
-		})]
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				ref: containerRef,
+				className: "relative",
+				onKeyDown: onContainerKeyDown,
+				children: [/* @__PURE__ */ jsx(Input, {
+					...field,
+					id,
+					placeholder: placeholder || (resolver !== null ? "0x... or name" : "0x..."),
+					className: validationClasses,
+					onChange: handleInputChange,
+					onKeyDown: handleKeyDown,
+					"data-slot": "input",
+					value: inputValue,
+					...accessibilityProps,
+					"aria-describedby": resolver === null ? `${helperText ? descriptionId : ""} ${hasRealError ? errorId : ""}` : [
+						helperText ? descriptionId : "",
+						hasRealError ? errorId : "",
+						resolutionRegionId
+					].filter(Boolean).join(" ") || void 0,
+					"aria-expanded": hasSuggestions,
+					"aria-autocomplete": suggestionsDisabled ? void 0 : "list",
+					"aria-controls": hasSuggestions ? `${id}-suggestions` : void 0,
+					"aria-activedescendant": hasSuggestions && highlightedIndex >= 0 ? `${id}-suggestion-${highlightedIndex}` : void 0,
+					disabled: readOnly
+				}), hasSuggestions && /* @__PURE__ */ jsx(AddressSuggestionList, {
+					id,
+					suggestions: resolvedSuggestions,
+					highlightedIndex,
+					onSelect: applySuggestion,
+					onHighlight: setHighlightedIndex
+				})]
+			}),
+			helperText && /* @__PURE__ */ jsx("div", {
+				id: descriptionId,
+				className: "text-muted-foreground text-sm",
+				children: helperText
+			}),
+			/* @__PURE__ */ jsx(ErrorMessage, {
+				error: hasRealError ? fieldState.error : void 0,
+				id: errorId,
+				message: shouldShowError ? fieldState.error?.message || patternErrorMessage : void 0
+			}),
+			resolver !== null && /* @__PURE__ */ jsx("div", {
+				id: resolutionRegionId,
+				"aria-live": "polite",
+				className: "min-h-5",
+				children: renderOutcome()
+			})
+		]
 	});
 }
 AddressField.displayName = "AddressField";
@@ -3498,6 +4249,84 @@ function useAddressSuggestions(query, networkId) {
 	]) };
 }
 
+//#endregion
+//#region src/components/fields/name-resolution/name-resolver-context.tsx
+/**
+* Name Resolver Context (SF-3)
+*
+* Provides a React context for forward name resolution (name → address).
+* When a `NameResolverProvider` is mounted, every `AddressField` in the
+* subtree resolves typed names inline through the injected `resolveName`
+* and submits the resolved hex — never the name (SC-004).
+*
+* The provider is deliberately **dumb** (INV-118): it memoizes the injected
+* functions into the context value and nothing else — no hook state, no
+* capability, no chain dependency. The smart runtime wiring lives upstream in
+* `@openzeppelin/ui-react` (`useRuntimeNameResolver`), which an app or the
+* renderer mounts ambiently:
+*
+* @example
+* ```tsx
+* import { NameResolverProvider } from '@openzeppelin/ui-components';
+* import { useRuntimeNameResolver } from '@openzeppelin/ui-react';
+*
+* function FormRoot() {
+*   const resolver = useRuntimeNameResolver();
+*   return (
+*     <NameResolverProvider {...resolver}>
+*       <MyForm />
+*     </NameResolverProvider>
+*   );
+* }
+* ```
+*/
+/**
+* Provides forward name resolution to all `AddressField` instances in the
+* subtree (zero call-site wiring, SC-001). Both functions are optional: an
+* absent `resolveName` means forward resolution is unsupported and a typed
+* name surfaces `UNSUPPORTED_NETWORK` (INV-119 / SC-006).
+*
+* ## Stable resolver identity (integrator contract)
+*
+* The injected resolver **must be referentially stable across renders** —
+* memoize it (e.g. `useMemo`) or use `useRuntimeNameResolver` from
+* `@openzeppelin/ui-react`, which is stable by construction. A resolver whose
+* function identity changes on every render (e.g. a fresh inline function) is a
+* misconfiguration: the field keys inline resolution on that identity, so a
+* churning identity would otherwise re-dispatch on every render — an unbounded
+* RPC loop on a funds path.
+*
+* The base component **detects and withstands** this (it is not merely a caveat):
+* dispatch is bounded per resolution intent so a churning resolver can never drive
+* an unbounded loop (INV-123), a one-shot development-only warning names the
+* misconfiguration (INV-124), and the field degrades to a **safe gated state**
+* (empty value, submit blocked — never a wrong address, never a throw; INV-125)
+* until the resolver is memoized. A **genuine** resolver/network swap — a single
+* identity change for a given input — is still honored and re-resolves within
+* budget (INV-119). The bound is a backstop; the contract is a stable identity.
+*
+* @param props - Injected resolver functions and children
+*/
+function NameResolverProvider({ children, isValidName, resolveName, activeNetworkId, activeNetworkName, resolveNetworkLabel }) {
+	const value = React$1.useMemo(() => ({
+		isValidName,
+		resolveName,
+		activeNetworkId,
+		activeNetworkName,
+		resolveNetworkLabel
+	}), [
+		isValidName,
+		resolveName,
+		activeNetworkId,
+		activeNetworkName,
+		resolveNetworkLabel
+	]);
+	return /* @__PURE__ */ jsx(NameResolverContext.Provider, {
+		value,
+		children
+	});
+}
+
 //#endregion
 //#region src/components/fields/AmountField.tsx
 /**
@@ -6226,7 +7055,7 @@ SelectGroupedField.displayName = "SelectGroupedField";
 * - Full accessibility support with ARIA attributes
 * - Keyboard navigation
 */
-function TextField({ id, label, placeholder, helperText, control, name, width = "full", validation, readOnly }) {
+function TextField({ id, label, placeholder, helperText, control, name, width = "full", validation, readOnly, onUserEdit }) {
 	const isRequired = !!validation?.required;
 	const errorId = `${id}-error`;
 	const descriptionId = `${id}-description`;
@@ -6262,9 +7091,13 @@ function TextField({ id, label, placeholder, helperText, control, name, width =
 				const handleInputChange = (e) => {
 					const value = e.target.value;
 					field.onChange(value);
+					onUserEdit?.(value);
 				};
 				const handleKeyDown = (e) => {
-					if (e.key === "Escape") handleEscapeKey(field.onChange, field.value)(e);
+					if (e.key === "Escape") handleEscapeKey((value) => {
+						field.onChange(value);
+						onUserEdit?.(value);
+					}, field.value)(e);
 				};
 				const accessibilityProps = getAccessibilityProps({
 					id,
@@ -6797,5 +7630,5 @@ const Toaster = ({ ...props }) => {
 };
 
 //#endregion
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AddressDisplay, AddressField, AddressLabelProvider, AddressListField, AddressSuggestionProvider, Alert, AlertDescription, AlertTitle, AmountField, ArrayField, ArrayObjectField, Banner, BaseField, BigIntField, BooleanField, Button, BytesField, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, DEFAULT_ADDRESS_LIST_FIELD_LABELS, DateRangePicker, DateTimeField, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EcosystemDropdown, EcosystemIcon, EmptyState, EnumField, ErrorMessage, ExternalLink, FileUploadField, Footer, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Header, INTEGER_HTML_PATTERN, INTEGER_INPUT_PATTERN, INTEGER_PATTERN, Input, Label, LoadingButton, MapEntryRow, MapField, MidnightIcon, NetworkAvailabilityNotice, NetworkErrorNotificationProvider, NetworkIcon, NetworkSelector, NetworkServiceErrorBanner, NetworkStatusBadge, NumberField, ObjectField, OverflowMenu, PasswordField, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, RadioField, RadioGroup, RadioGroupItem, RelayerDetailsCard, Select, SelectContent, SelectField, SelectGroup, SelectGroupedField, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, SidebarButton, SidebarGroup, SidebarLayout, SidebarSection, Tabs, TabsContent, TabsList, TabsTrigger, TextAreaField, TextField, Textarea, Toaster, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UrlField, VERSION, ViewContractStateButton, WizardLayout, WizardNavigation, WizardStepper, buildAddressListPreviewSummary, buttonVariants, computeChildTouched, createFocusManager, createValidationResult, formatAddressBulkSummary, formatValidationError, getAccessibilityProps, getDescribedById, getErrorMessage, getValidationStateClasses, getWidthClasses, handleEscapeKey, handleKeyboardEvent, handleNumericKeys, handleToggleKeys, handleValidationError, hasFieldError, isDuplicateMapKey, resolveAddressListFieldLabels, useAddressLabel, useAddressSuggestions, useDuplicateKeyIndexes, useMapFieldSync, useNetworkErrorAwareAdapter, useNetworkErrorReporter, useNetworkErrors, validateField, validateMapEntries, validateMapStructure };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AddressDisplay, AddressField, AddressLabelProvider, AddressListField, AddressNameProvider, AddressSuggestionList, AddressSuggestionProvider, Alert, AlertDescription, AlertTitle, AmountField, ArrayField, ArrayObjectField, Banner, BaseField, BigIntField, BooleanField, Button, BytesField, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, DEFAULT_ADDRESS_LIST_FIELD_LABELS, DateRangePicker, DateTimeField, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EcosystemDropdown, EcosystemIcon, EmptyState, EnumField, ErrorMessage, ExternalLink, FileUploadField, Footer, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Header, INTEGER_HTML_PATTERN, INTEGER_INPUT_PATTERN, INTEGER_PATTERN, Input, Label, LoadingButton, MapEntryRow, MapField, MidnightIcon, NAME_RESOLUTION_DEBOUNCE_MS, NameResolverContext, NameResolverProvider, NetworkAvailabilityNotice, NetworkErrorNotificationProvider, NetworkIcon, NetworkSelector, NetworkServiceErrorBanner, NetworkStatusBadge, NumberField, ObjectField, OverflowMenu, PasswordField, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, RadioField, RadioGroup, RadioGroupItem, RelayerDetailsCard, Select, SelectContent, SelectField, SelectGroup, SelectGroupedField, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, SidebarButton, SidebarGroup, SidebarLayout, SidebarSection, Tabs, TabsContent, TabsList, TabsTrigger, TextAreaField, TextField, Textarea, Toaster, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UrlField, VERSION, ViewContractStateButton, WizardLayout, WizardNavigation, WizardStepper, buildAddressListPreviewSummary, buttonVariants, computeChildTouched, createFocusManager, createValidationResult, formatAddressBulkSummary, formatValidationError, getAccessibilityProps, getDescribedById, getErrorMessage, getValidationStateClasses, getWidthClasses, handleEscapeKey, handleKeyboardEvent, handleNumericKeys, handleToggleKeys, handleValidationError, hasFieldError, isDuplicateMapKey, resolveAddressListFieldLabels, useAddressLabel, useAddressName, useAddressSuggestionField, useAddressSuggestions, useDuplicateKeyIndexes, useInjectedNameResolution, useMapFieldSync, useNameResolver, useNetworkErrorAwareAdapter, useNetworkErrorReporter, useNetworkErrors, validateField, validateMapEntries, validateMapStructure };
 //# sourceMappingURL=index.mjs.map