@three-ws/x402-payment-modal 1.1.0 → 1.2.0

package/src/index.js

@@ -26,8 +26,9 @@
 //     action: 'Summarize',
 //   });
 //
-// The modal handles wallet connect (Phantom for Solana, window.ethereum for
-// Base/EVM USDC via EIP-3009), drives the 402 → sign → retry flow, optional
+// The modal handles wallet connect (Phantom/Solflare/Backpack/… for Solana,
+// EIP-6963 browser wallets for Base/EVM USDC via EIP-3009), drives the
+// 402 → sign → retry flow, optional
 // SIWX (Sign-In-With-X) re-entry, client-side spending caps, and shows the
 // result. Vanilla JS, no bundler required.
 //
@@ -36,12 +37,13 @@
 // is configurable via `configure({...})` or `data-*` attributes on the script
 // tag — see CONFIG / configure() below and docs/api-reference.md.
 
-const VERSION = '1.1.0';
+const VERSION = '1.2.0';
 
 // ─────────────────────────────────────────────────────────── configuration ───
 // All host-specific knobs live here so the modal runs unchanged on any site.
-// Defaults match the three.ws hosted instance; override with configure() or via
-// `data-*` attributes on the <script> tag (read once at load by readScriptConfig).
+// The defaults below settle a 402 from ANY origin with zero config; override with
+// configure() or via `data-*` attributes on the <script> tag (read once at load
+// by readScriptConfig).
 const CONFIG = {
 	// Origin that serves the Solana checkout endpoints
 	// (`/api/x402-checkout?action=prepare|encode`). `null` → resolve from this
@@ -51,22 +53,47 @@ const CONFIG = {
 	// Path of the checkout endpoint on `checkoutOrigin`. Override if you mount
 	// the server handler somewhere other than /api/x402-checkout.
 	checkoutPath: '/api/x402-checkout',
-	// Footer attribution shown in the modal.
-	brand: { name: 'three.ws', url: 'https://three.ws' },
+	// Footer attribution shown in the modal. Both fields default to null so no
+	// "Powered by" link renders until a host opts in via
+	// configure({ brand: { name, url } }).
+	brand: { name: null, url: null },
 	// Small text on the left of the footer.
 	footerNote: 'x402 · onchain settled',
 	// ERC-8021 builder-code self-attribution echoed back when the 402 challenge
-	// declares a builder-code extension. Set either field to '' to disable it.
-	builderCode: { wallet: '3d_agent', service: '3d_agent_modal' },
-	// CDN URLs for the crypto helpers loaded on demand (only when a Solana or an
-	// EVM sign-in payment is actually attempted). Repoint these at a self-hosted
-	// mirror to satisfy a strict Content-Security-Policy.
+	// declares a builder-code extension. Empty by default — no self-attribution
+	// unless a host opts in via configure({ builderCode: { wallet, service } }).
+	builderCode: { wallet: '', service: '' },
+	// Color scheme: 'auto' follows the OS; 'light'/'dark' force it.
+	theme: 'auto',
+	// Optional flat map of --x402-* design tokens for brand-matching at runtime.
+	cssVars: null,
+	// Primary CDN URLs for the crypto helpers loaded on demand (only when a Solana
+	// or EVM sign-in payment is actually attempted). Each is tried first, then the
+	// loader falls back across additional independent CDNs (see ESM_FALLBACKS) so a
+	// single CDN outage during a traffic spike can't break payments. Repoint these
+	// at a self-hosted mirror to satisfy a strict Content-Security-Policy — your URL
+	// is always tried first.
 	esm: {
 		solanaWeb3: 'https://esm.sh/@solana/web3.js@1.95.3?bundle',
 		nobleHashesSha3: 'https://esm.sh/@noble/hashes@1.4.0/sha3?bundle',
 	},
 };
 
+// Independent CDN fallbacks tried (in order, after the configured primary) if the
+// primary is slow or down. Three uncorrelated providers ≈ no single point of
+// failure for the dynamic crypto-helper import that the Solana path depends on.
+const ESM_FALLBACKS = {
+	solanaWeb3: [
+		'https://cdn.jsdelivr.net/npm/@solana/web3.js@1.95.3/+esm',
+		'https://cdn.skypack.dev/@solana/web3.js@1.95.3',
+	],
+	nobleHashesSha3: [
+		'https://cdn.jsdelivr.net/npm/@noble/hashes@1.4.0/sha3/+esm',
+		'https://cdn.skypack.dev/@noble/hashes@1.4.0/sha3',
+	],
+};
+const ESM_IMPORT_TIMEOUT_MS = 12_000;
+
 /**
  * Merge caller overrides into CONFIG. Shallow-merges the nested `brand`,
  * `builderCode`, and `esm` objects so you can override a single field. Call
@@ -76,12 +103,19 @@ const CONFIG = {
  */
 export function configure(opts = {}) {
 	if (!opts || typeof opts !== 'object') return CONFIG;
-	for (const key of ['checkoutOrigin', 'checkoutPath', 'footerNote']) {
+	// theme: 'light' | 'dark' | 'auto' — force the modal's color scheme regardless
+	// of the OS preference (auto = follow the OS, the default).
+	for (const key of ['checkoutOrigin', 'checkoutPath', 'footerNote', 'theme']) {
 		if (opts[key] !== undefined) CONFIG[key] = opts[key];
 	}
 	if (opts.brand && typeof opts.brand === 'object') Object.assign(CONFIG.brand, opts.brand);
 	if (opts.builderCode && typeof opts.builderCode === 'object') Object.assign(CONFIG.builderCode, opts.builderCode);
 	if (opts.esm && typeof opts.esm === 'object') Object.assign(CONFIG.esm, opts.esm);
+	// cssVars: a flat map of x402 design tokens to brand-match without CSS files,
+	// e.g. configure({ cssVars: { '--x402-accent': '#ff5c00', '--x402-radius': '8px' } }).
+	if (opts.cssVars && typeof opts.cssVars === 'object') {
+		CONFIG.cssVars = { ...(CONFIG.cssVars || {}), ...opts.cssVars };
+	}
 	return CONFIG;
 }
 
@@ -137,12 +171,11 @@ function normalizeAccept(accept) {
 // ─────────────────────────────────────────────── Well-known Solana tokens ────
 // Mints the modal recognizes on sight, so a 402 `accept` can omit
 // `extra.name`/`extra.decimals` and still render with the correct symbol,
-// decimals, and branding. Two settlement assets are first-class on Solana:
-//   • USDC — the universal dollar-stable rail.
-//   • THREE — the three.ws utility token. Holders can pay any x402 endpoint
-//     that opts into accepting it, right alongside USDC. See three.ws/three-token.
-// A merchant offers THREE simply by adding a Solana `accept` whose `asset` is
-// THREE_MINT (the server checkout transfers any SPL mint, so no extra wiring).
+// decimals, and branding. USDC is the always-on default settlement asset on
+// Solana — the universal dollar-stable rail. THREE is an optional opt-in SPL
+// token a merchant can accept alongside USDC: add a Solana `accept` whose
+// `asset` is THREE_MINT and the server checkout transfers it like any other
+// mint (no extra wiring). The modal works fully without ever touching THREE.
 export const USDC_MINT_SOLANA = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 export const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
 
@@ -334,10 +367,11 @@ function browserRollbackReservation(reservation) {
 }
 
 // ──────────────────────────────────────────── ERC-8021 builder-code echo ────
-// The server-side x402-spec.js enforces that any client-echoed builder-code
+// A server that supports ERC-8021 enforces that any client-echoed builder-code
 // `a` matches what the 402 challenge declared (anti-tamper). Builders/wallets
-// can append their own service code in `s` and set their wallet code `w`
-// — for our own demo modal we self-attribute `w: "3d_agent"` and `s: ["3d_agent_modal"]`.
+// can append their own service code in `s` and set their wallet code `w`. Both
+// are empty by default, so the modal echoes nothing extra; a host opts into
+// self-attribution via configure({ builderCode: { wallet, service } }).
 
 const BUILDER_CODE_KEY = 'builder-code';
 const BUILDER_CODE_PATTERN = /^[a-z0-9_]{1,32}$/;
@@ -456,7 +490,7 @@ function base58encode(bytes) {
 let _evmChecksum = null;
 async function loadEvmChecksum() {
 	if (_evmChecksum) return _evmChecksum;
-	const sha3 = await import(/* @vite-ignore */ CONFIG.esm.nobleHashesSha3);
+	const sha3 = await importWithFallback(CONFIG.esm.nobleHashesSha3, ESM_FALLBACKS.nobleHashesSha3, '@noble/hashes/sha3');
 	const keccak = sha3.keccak_256;
 	_evmChecksum = (addr) => {
 		const a = String(addr).toLowerCase().replace(/^0x/, '');
@@ -476,118 +510,218 @@ async function loadEvmChecksum() {
 // ───────────────────────────────────────────────────────────────── styles ────
 
 const STYLE_ID = 'x402-styles';
-const STYLES = `
-:root {
+// Full design-token surface. Hosts brand-match by setting any of these on
+// `.x402-overlay` (via configure({ cssVars }) or their own CSS) — no !important,
+// no specificity battles. Dark values are applied both by the OS preference and
+// by an explicit `.x402-theme-dark` class (configure({ theme })).
+const TOKENS_LIGHT = `
 	--x402-z: 2147483600;
+	--x402-font: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	--x402-mono: ui-monospace, "JetBrains Mono", "SF Mono", Menlo, monospace;
+	--x402-scrim: rgba(8, 10, 18, 0.55);
+	--x402-surface: #ffffff;
+	--x402-surface-2: #f7f8fa;
+	--x402-fg: #0f1116;
+	--x402-muted: #646b7a;
+	--x402-faint: #9aa1ad;
+	--x402-border: #ecedf1;
+	--x402-border-strong: #d8dce4;
+	--x402-accent: #635bff;
+	--x402-accent-hover: #524bdb;
+	--x402-accent-weak: #f2f1ff;
+	--x402-accent-fg: #ffffff;
+	--x402-success: #16a34a;
+	--x402-success-fg: #15803d;
+	--x402-success-bg: #f0fdf4;
+	--x402-success-border: #bbf7d0;
+	--x402-error: #dc2626;
+	--x402-error-fg: #b91c1c;
+	--x402-error-bg: #fef2f2;
+	--x402-error-border: #fecaca;
+	--x402-warn-fg: #b45309;
+	--x402-warn-bg: #fffbeb;
+	--x402-warn-border: #fde68a;
+	--x402-link: #524bdb;
+	--x402-radius: 18px;
+	--x402-radius-md: 12px;
+	--x402-radius-sm: 9px;
+	--x402-shadow: 0 24px 80px rgba(8, 10, 18, 0.28), 0 4px 16px rgba(8, 10, 18, 0.12);
+	--x402-btn-bg: #0f1116;
+	--x402-btn-fg: #ffffff;
+	--x402-btn-hover: #242833;
+	--x402-btn-shadow: 0 1px 2px rgba(8, 10, 18, 0.18), inset 0 1px 0 rgba(255, 255, 255, 0.12);
+`;
+const TOKENS_DARK = `
+	--x402-scrim: rgba(0, 0, 0, 0.62);
+	--x402-surface: #161616;
+	--x402-surface-2: #1d1d1d;
+	--x402-fg: #e6e8f0;
+	--x402-muted: #9aa1b4;
+	--x402-faint: #6b7088;
+	--x402-border: #2a2a2a;
+	--x402-border-strong: #3a3a40;
+	--x402-accent: #8b85ff;
+	--x402-accent-hover: #a29cff;
+	--x402-accent-weak: #1e1b3a;
+	--x402-accent-fg: #ffffff;
+	--x402-success: #22c55e;
+	--x402-success-fg: #4ade80;
+	--x402-success-bg: #0b1f17;
+	--x402-success-border: #14532d;
+	--x402-error: #ef4444;
+	--x402-error-fg: #fca5a5;
+	--x402-error-bg: #1f1416;
+	--x402-error-border: #7f1d1d;
+	--x402-warn-fg: #fcd34d;
+	--x402-warn-bg: #2a1d10;
+	--x402-warn-border: #78350f;
+	--x402-link: #a29cff;
+	--x402-shadow: 0 24px 80px rgba(0, 0, 0, 0.6);
+	--x402-btn-bg: #ffffff;
+	--x402-btn-fg: #0f1116;
+	--x402-btn-hover: #e7e9ee;
+	--x402-btn-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), inset 0 1px 0 rgba(255, 255, 255, 0.5);
+`;
+
+const STYLES = `
+.x402-overlay { ${TOKENS_LIGHT} }
+.x402-overlay.x402-theme-dark { ${TOKENS_DARK} }
+@media (prefers-color-scheme: dark) {
+	.x402-overlay:not(.x402-theme-light) { ${TOKENS_DARK} }
 }
 .x402-overlay {
 	position: fixed; inset: 0;
-	background: rgba(8, 10, 18, 0.55);
+	background: var(--x402-scrim);
 	backdrop-filter: blur(10px);
 	-webkit-backdrop-filter: blur(10px);
 	display: flex; align-items: center; justify-content: center;
 	z-index: var(--x402-z);
 	opacity: 0; transition: opacity 0.16s ease-out;
-	font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	font-family: var(--x402-font);
 	-webkit-font-smoothing: antialiased;
-	color: #0f0f0f;
+	color: var(--x402-fg);
 }
 .x402-overlay.x402-open { opacity: 1; }
 .x402-overlay * { box-sizing: border-box; }
+.x402-overlay :focus-visible {
+	outline: 2px solid var(--x402-accent);
+	outline-offset: 2px;
+}
 .x402-modal {
 	width: calc(100% - 32px); max-width: 420px;
-	background: #ffffff;
-	border-radius: 18px;
-	box-shadow: 0 24px 80px rgba(8, 10, 18, 0.28), 0 4px 16px rgba(8, 10, 18, 0.12);
+	background: var(--x402-surface);
+	border-radius: var(--x402-radius);
+	box-shadow: var(--x402-shadow);
 	overflow: hidden;
 	transform: translateY(8px) scale(0.985);
-	transition: transform 0.18s ease-out;
+	transition: transform 0.2s cubic-bezier(0.16, 1, 0.3, 1);
 	display: flex; flex-direction: column;
 	max-height: calc(100dvh - 32px);
 }
 .x402-overlay.x402-open .x402-modal { transform: translateY(0) scale(1); }
 .x402-head {
 	padding: 18px 20px 14px;
-	border-bottom: 1px solid #eef0f4;
+	border-bottom: 1px solid var(--x402-border);
 	display: flex; align-items: center; gap: 12px;
 }
-.x402-head .x402-merchant {
-	flex: 1; min-width: 0;
-}
+.x402-head .x402-merchant { flex: 1; min-width: 0; display: flex; align-items: center; gap: 10px; }
+.x402-head .x402-merchant-text { min-width: 0; }
+.x402-brand-logo { width: 30px; height: 30px; flex: 0 0 auto; border-radius: 8px; object-fit: cover; }
 .x402-merchant .x402-name {
-	font-size: 12px; color: #5a6378; font-weight: 600; letter-spacing: 0.02em; text-transform: uppercase;
+	font-size: 12px; color: var(--x402-muted); font-weight: 600; letter-spacing: 0.02em; text-transform: uppercase;
 	margin-bottom: 2px;
 }
 .x402-merchant .x402-action {
-	font-size: 17px; font-weight: 700; color: #0f0f0f;
+	font-size: 17px; font-weight: 700; color: var(--x402-fg);
 	white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
 	letter-spacing: -0.01em;
 }
 .x402-close {
-	width: 32px; height: 32px;
-	border-radius: 8px; border: none; background: #f3f4f7;
-	font-size: 16px; color: #5a6378; cursor: pointer;
+	width: 32px; height: 32px; flex: 0 0 auto;
+	border-radius: 8px; border: none; background: var(--x402-surface-2);
+	color: var(--x402-muted); cursor: pointer;
 	display: flex; align-items: center; justify-content: center;
-	transition: background 0.12s;
+	transition: background 0.12s, color 0.12s;
 }
-.x402-close:hover { background: #e7e9ee; color: #0f0f0f; }
+.x402-close:hover { background: var(--x402-border-strong); color: var(--x402-fg); }
+.x402-close svg { width: 14px; height: 14px; }
 
 .x402-price-row {
 	padding: 18px 20px;
-	display: flex; align-items: baseline; justify-content: space-between;
-	background: linear-gradient(180deg, #fafbfc 0%, #ffffff 100%);
-	border-bottom: 1px solid #eef0f4;
+	display: flex; align-items: baseline; justify-content: space-between; gap: 12px;
+	background: var(--x402-surface-2);
+	border-bottom: 1px solid var(--x402-border);
 }
+.x402-price-main { min-width: 0; }
 .x402-price {
-	font-size: 32px; font-weight: 700; letter-spacing: -0.02em; color: #0f0f0f;
+	font-size: 32px; font-weight: 700; letter-spacing: -0.02em; color: var(--x402-fg);
 	font-variant-numeric: tabular-nums;
 }
-.x402-price .x402-currency { font-size: 14px; color: #5a6378; font-weight: 600; margin-left: 6px; letter-spacing: 0; }
+.x402-price .x402-currency { font-size: 14px; color: var(--x402-muted); font-weight: 600; margin-left: 6px; letter-spacing: 0; }
+.x402-price-sub { font-size: 11px; color: var(--x402-muted); margin-top: 3px; font-weight: 500; }
 .x402-network {
-	font-size: 12px; color: #5a6378; font-weight: 500;
-	background: #f3f4f7; padding: 5px 10px; border-radius: 99px;
+	font-size: 12px; color: var(--x402-muted); font-weight: 500; flex: 0 0 auto;
+	background: var(--x402-surface); border: 1px solid var(--x402-border);
+	padding: 5px 10px; border-radius: 99px;
 	display: inline-flex; align-items: center; gap: 6px;
 }
 .x402-network::before {
 	content: ''; width: 6px; height: 6px; border-radius: 50%;
-	background: #22c55e;
+	background: var(--x402-success);
+	box-shadow: 0 0 0 0 var(--x402-success);
+	animation: x402-pulse 2s ease-out infinite;
+}
+@keyframes x402-pulse {
+	0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--x402-success) 55%, transparent); }
+	70% { box-shadow: 0 0 0 5px transparent; }
+	100% { box-shadow: 0 0 0 0 transparent; }
 }
 
 .x402-body {
-	padding: 16px 20px 18px;
+	padding: 16px 20px max(18px, env(safe-area-inset-bottom));
 	flex: 1 1 auto; overflow-y: auto;
 	display: flex; flex-direction: column; gap: 10px;
 }
+.x402-body > * { animation: x402-fade 0.16s ease-out both; }
+@keyframes x402-fade { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: none; } }
 .x402-step {
 	display: flex; gap: 12px; align-items: flex-start;
 	padding: 10px 0;
 }
-.x402-step + .x402-step { border-top: 1px solid #f3f4f7; }
+.x402-step + .x402-step { border-top: 1px solid var(--x402-border); }
 .x402-step-num {
 	width: 22px; height: 22px; flex: 0 0 auto;
-	border-radius: 50%; border: 1.5px solid #d0d4dd; background: #fff;
-	color: #5a6378;
+	border-radius: 50%; border: 1.5px solid var(--x402-border-strong); background: var(--x402-surface);
+	color: var(--x402-muted);
 	font-size: 11px; font-weight: 700;
 	display: flex; align-items: center; justify-content: center;
 }
 .x402-step.x402-active .x402-step-num {
-	border-color: #0a84ff; background: #0a84ff; color: #fff;
+	border-color: var(--x402-accent); background: var(--x402-accent); color: var(--x402-accent-fg);
 	animation: x402-spin 1.2s linear infinite;
 }
 .x402-step.x402-done .x402-step-num {
-	border-color: #22c55e; background: #22c55e; color: #fff;
+	border-color: var(--x402-success); background: var(--x402-success); color: #fff;
 }
 .x402-step.x402-error .x402-step-num {
-	border-color: #ef4444; background: #ef4444; color: #fff;
+	border-color: var(--x402-error); background: var(--x402-error); color: #fff;
 }
 @keyframes x402-spin {
-	from { box-shadow: 0 0 0 0 rgba(10, 132, 255, 0.4); }
-	to { box-shadow: 0 0 0 8px rgba(10, 132, 255, 0); }
+	from { box-shadow: 0 0 0 0 color-mix(in srgb, var(--x402-accent) 40%, transparent); }
+	to { box-shadow: 0 0 0 8px transparent; }
 }
 .x402-step-body { flex: 1; min-width: 0; }
-.x402-step-label { font-size: 14px; font-weight: 600; color: #0f0f0f; line-height: 1.35; }
-.x402-step-meta { font-size: 12px; color: #5a6378; margin-top: 2px; font-feature-settings: 'tnum' 1; }
-.x402-step.x402-error .x402-step-meta { color: #ef4444; }
+.x402-step-label { font-size: 14px; font-weight: 600; color: var(--x402-fg); line-height: 1.35; }
+.x402-step-meta { font-size: 12px; color: var(--x402-muted); margin-top: 2px; font-feature-settings: 'tnum' 1; }
+.x402-step.x402-error .x402-step-meta { color: var(--x402-error-fg); }
+
+.x402-skeleton {
+	border-radius: 6px;
+	background: linear-gradient(100deg, var(--x402-surface-2) 30%, var(--x402-border) 50%, var(--x402-surface-2) 70%);
+	background-size: 200% 100%;
+	animation: x402-shimmer 1.3s ease-in-out infinite;
+}
+@keyframes x402-shimmer { from { background-position: 200% 0; } to { background-position: -200% 0; } }
 
 .x402-wallet-buttons {
 	display: flex; flex-direction: column; gap: 8px;
@@ -595,26 +729,30 @@ const STYLES = `
 }
 .x402-wallet-btn {
 	width: 100%; padding: 13px 14px;
-	background: #ffffff; border: 1.5px solid #e2e5ec; border-radius: 11px;
-	font-size: 14px; font-weight: 600; color: #0f0f0f;
+	background: var(--x402-surface); border: 1.5px solid var(--x402-border-strong); border-radius: 11px;
+	font-size: 14px; font-weight: 600; color: var(--x402-fg);
 	cursor: pointer; font-family: inherit;
 	display: flex; align-items: center; gap: 12px;
 	transition: border-color 0.12s, background 0.12s, transform 0.05s;
 }
-.x402-wallet-btn:hover:not(:disabled) { border-color: #0a84ff; background: #f7faff; }
+.x402-wallet-btn:hover:not(:disabled) { border-color: var(--x402-accent); background: var(--x402-accent-weak); }
 .x402-wallet-btn:active:not(:disabled) { transform: translateY(1px); }
 .x402-wallet-btn:disabled { opacity: 0.45; cursor: not-allowed; }
 .x402-wallet-icon {
 	width: 28px; height: 28px; flex: 0 0 auto;
 	border-radius: 7px;
 	display: flex; align-items: center; justify-content: center;
-	font-size: 16px;
-	background: #f3f4f7;
+	background: var(--x402-surface-2); overflow: hidden;
 }
-.x402-wallet-icon.x402-phantom { background: linear-gradient(135deg, #ab9ff2, #534bb1); color: #fff; }
-.x402-wallet-icon.x402-metamask { background: linear-gradient(135deg, #f6851b, #e2761b); color: #fff; }
+.x402-wallet-icon svg, .x402-wallet-icon img { width: 18px; height: 18px; }
 .x402-wallet-name { flex: 1; text-align: left; }
-.x402-wallet-meta { font-size: 11px; color: #8a90a8; font-weight: 500; }
+.x402-wallet-meta { font-size: 11px; color: var(--x402-muted); font-weight: 500; }
+.x402-wallet-install {
+	font-size: 12px; color: var(--x402-muted); line-height: 1.5; text-align: center;
+	padding: 4px 0 2px;
+}
+.x402-wallet-install a { color: var(--x402-link); text-decoration: none; font-weight: 600; }
+.x402-wallet-install a:hover { text-decoration: underline; }
 
 .x402-token-row {
 	display: flex; gap: 8px; margin-bottom: 10px;
@@ -622,145 +760,230 @@ const STYLES = `
 .x402-token-pill {
 	flex: 1; min-width: 0; cursor: pointer; font-family: inherit;
 	padding: 9px 12px; border-radius: 10px;
-	background: #ffffff; border: 1.5px solid #e2e5ec;
+	background: var(--x402-surface); border: 1.5px solid var(--x402-border-strong);
 	display: flex; flex-direction: column; align-items: flex-start; gap: 2px;
-	transition: border-color 0.12s, background 0.12s, transform 0.05s;
+	transition: border-color 0.12s, background 0.12s, transform 0.05s, box-shadow 0.12s;
 }
-.x402-token-pill:hover { border-color: #c3c9d6; background: #f9fafc; }
+.x402-token-pill:hover { border-color: var(--x402-accent); background: var(--x402-accent-weak); }
 .x402-token-pill:active { transform: translateY(1px); }
-.x402-token-pill.x402-on { border-color: #0f0f0f; background: #f7faff; }
-.x402-token-sym { font-size: 13px; font-weight: 700; color: #0f0f0f; letter-spacing: -0.005em; }
-.x402-token-amt { font-size: 11px; color: #8a90a8; font-weight: 600; font-variant-numeric: tabular-nums; }
+.x402-token-pill.x402-on {
+	border-color: var(--x402-accent); background: var(--x402-accent-weak);
+	box-shadow: inset 0 0 0 1px var(--x402-accent);
+}
+.x402-token-sym { font-size: 13px; font-weight: 700; color: var(--x402-fg); letter-spacing: -0.005em; }
+.x402-token-amt { font-size: 11px; color: var(--x402-muted); font-weight: 600; font-variant-numeric: tabular-nums; }
 
 .x402-pay-btn {
 	width: 100%; padding: 14px 16px;
-	background: #0f0f0f; color: #fff; border: none;
-	border-radius: 12px;
+	background: var(--x402-btn-bg); color: var(--x402-btn-fg); border: none;
+	border-radius: var(--x402-radius-md);
 	font-size: 15px; font-weight: 700; font-family: inherit;
 	cursor: pointer; letter-spacing: -0.005em;
-	transition: background 0.12s, transform 0.05s;
+	box-shadow: var(--x402-btn-shadow);
+	transition: background 0.12s, transform 0.1s, box-shadow 0.12s;
 	margin-top: 4px;
 	display: flex; align-items: center; justify-content: center; gap: 8px;
 }
-.x402-pay-btn:hover:not(:disabled) { background: #1d1d1d; }
-.x402-pay-btn:active:not(:disabled) { transform: translateY(1px); }
-.x402-pay-btn:disabled { background: #c8ccd4; cursor: not-allowed; }
+.x402-pay-btn:hover:not(:disabled) { background: var(--x402-btn-hover); transform: translateY(-1px); }
+.x402-pay-btn:active:not(:disabled) { transform: translateY(0); }
+.x402-pay-btn:disabled { opacity: 0.5; cursor: not-allowed; box-shadow: none; }
 
 .x402-pay-secondary {
 	width: 100%; padding: 12px 14px;
-	background: #ffffff; color: #0f0f0f;
-	border: 1.5px solid #e2e5ec; border-radius: 11px;
+	background: var(--x402-surface); color: var(--x402-fg);
+	border: 1.5px solid var(--x402-border-strong); border-radius: 11px;
 	font-size: 14px; font-weight: 600; font-family: inherit;
 	cursor: pointer; letter-spacing: -0.005em;
 	margin-top: 6px;
 	transition: border-color 0.12s, background 0.12s, transform 0.05s;
 }
-.x402-pay-secondary:hover:not(:disabled) { border-color: #0a84ff; background: #f7faff; }
+.x402-pay-secondary:hover:not(:disabled) { border-color: var(--x402-accent); background: var(--x402-accent-weak); }
 .x402-pay-secondary:active:not(:disabled) { transform: translateY(1px); }
 
+.x402-trust {
+	font-size: 11.5px; color: var(--x402-muted); text-align: center;
+	margin-top: 10px; line-height: 1.45;
+	display: flex; align-items: center; justify-content: center; gap: 6px;
+}
+.x402-trust svg { width: 12px; height: 12px; flex: 0 0 auto; color: var(--x402-success); }
+
 .x402-siwx-hint {
-	font-size: 11px; color: #5a6378; text-align: center;
+	font-size: 11px; color: var(--x402-muted); text-align: center;
 	margin-top: 8px; line-height: 1.4;
 }
 .x402-siwx-fallback {
-	font-size: 12px; color: #b45309; line-height: 1.45;
+	font-size: 12px; color: var(--x402-warn-fg); line-height: 1.45;
 	padding: 8px 10px; border-radius: 8px;
-	background: #fffbeb; border: 1px solid #fde68a;
+	background: var(--x402-warn-bg); border: 1px solid var(--x402-warn-border);
 	margin-bottom: 6px;
 }
 
 .x402-error-box {
 	padding: 12px 14px; border-radius: 10px;
-	background: #fef2f2; border: 1px solid #fecaca; color: #b91c1c;
-	font-size: 13px; line-height: 1.45;
-	font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
+	background: var(--x402-error-bg); border: 1px solid var(--x402-error-border); color: var(--x402-error-fg);
+	font-size: 13.5px; line-height: 1.5;
 	word-break: break-word;
 }
-.x402-error-box strong { font-weight: 700; }
+.x402-error-box .x402-error-title { font-weight: 700; margin-bottom: 2px; }
+.x402-error-box .x402-error-detail { opacity: 0.85; font-size: 12.5px; }
 
 .x402-receipt {
-	padding: 14px 16px; border-radius: 12px;
-	background: linear-gradient(180deg, #f0fdf4 0%, #ffffff 100%);
-	border: 1px solid #bbf7d0;
+	padding: 16px; border-radius: var(--x402-radius-md);
+	background: var(--x402-success-bg);
+	border: 1px solid var(--x402-success-border);
+	animation: x402-pop 0.34s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+@keyframes x402-pop { from { opacity: 0; transform: scale(0.94); } to { opacity: 1; transform: scale(1); } }
+.x402-receipt-check {
+	width: 40px; height: 40px; margin: 2px auto 10px;
+	border-radius: 50%; background: var(--x402-success);
+	display: flex; align-items: center; justify-content: center;
+	animation: x402-check-pop 0.4s cubic-bezier(0.16, 1, 0.3, 1) 0.08s both;
 }
+.x402-receipt-check svg { width: 22px; height: 22px; color: #fff; }
+.x402-receipt-check svg path { stroke-dasharray: 24; stroke-dashoffset: 24; animation: x402-draw 0.4s ease-out 0.22s forwards; }
+@keyframes x402-check-pop { 0% { transform: scale(0); } 60% { transform: scale(1.12); } 100% { transform: scale(1); } }
+@keyframes x402-draw { to { stroke-dashoffset: 0; } }
 .x402-receipt-title {
-	font-size: 11px; font-weight: 700; color: #15803d;
-	text-transform: uppercase; letter-spacing: 0.06em;
-	margin-bottom: 8px;
-	display: flex; align-items: center; gap: 6px;
+	font-size: 15px; font-weight: 700; color: var(--x402-fg);
+	text-align: center; margin-bottom: 10px; letter-spacing: -0.01em;
 }
-.x402-receipt-title::before { content: '✓'; font-size: 14px; }
 .x402-receipt-row {
 	display: flex; justify-content: space-between; gap: 12px;
-	font-size: 12px; padding: 2px 0;
-	font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
+	font-size: 12px; padding: 3px 0;
+	font-family: var(--x402-mono);
 }
-.x402-receipt-row .x402-k { color: #5a6378; }
-.x402-receipt-row .x402-v { color: #0f0f0f; text-align: right; word-break: break-all; }
-.x402-receipt-row a { color: #0a84ff; text-decoration: none; }
+.x402-receipt-row .x402-k { color: var(--x402-muted); }
+.x402-receipt-row .x402-v { color: var(--x402-fg); text-align: right; word-break: break-all; }
+.x402-receipt-row a { color: var(--x402-link); text-decoration: none; }
 .x402-receipt-row a:hover { text-decoration: underline; }
 
 .x402-result {
 	padding: 12px 14px; border-radius: 10px;
-	background: #fafbfc; border: 1px solid #e2e5ec;
+	background: var(--x402-surface-2); border: 1px solid var(--x402-border);
 	max-height: 240px; overflow: auto;
-	font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
-	font-size: 12px; line-height: 1.5; color: #0f0f0f;
+	font-family: var(--x402-mono);
+	font-size: 12px; line-height: 1.5; color: var(--x402-fg);
 	white-space: pre-wrap; word-break: break-word;
 }
+.x402-result.x402-prose { font-family: var(--x402-font); font-size: 13.5px; line-height: 1.55; }
 
 .x402-foot {
-	padding: 10px 20px 14px;
-	border-top: 1px solid #eef0f4;
+	padding: 10px 20px max(14px, env(safe-area-inset-bottom));
+	border-top: 1px solid var(--x402-border);
 	display: flex; align-items: center; justify-content: space-between;
-	font-size: 11px; color: #8a90a8;
+	font-size: 11px; color: var(--x402-muted);
 }
-.x402-foot a { color: #5a6378; text-decoration: none; font-weight: 600; }
-.x402-foot a:hover { color: #0f0f0f; }
+.x402-foot a { color: var(--x402-muted); text-decoration: none; font-weight: 600; }
+.x402-foot a:hover { color: var(--x402-fg); }
 .x402-foot .x402-secure { display: flex; align-items: center; gap: 5px; }
-.x402-foot .x402-secure::before { content: '🔒'; font-size: 10px; }
+.x402-foot .x402-secure svg { width: 11px; height: 11px; }
 
-@media (max-width: 480px) {
-	.x402-modal { max-width: none; width: calc(100% - 16px); border-radius: 16px; }
-	.x402-price { font-size: 26px; }
+.x402-sr-only {
+	position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+	overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0;
 }
 
-@media (prefers-color-scheme: dark) {
-	.x402-overlay { color: #e6e8f0; }
-	.x402-modal { background: #161616; box-shadow: 0 24px 80px rgba(0, 0, 0, 0.6); }
-	.x402-head, .x402-price-row, .x402-foot { border-color: #272727; }
-	.x402-step + .x402-step { border-top-color: #272727; }
-	.x402-merchant .x402-name { color: #8a90a8; }
-	.x402-merchant .x402-action, .x402-price, .x402-step-label { color: #e6e8f0; }
-	.x402-step-meta { color: #8a90a8; }
-	.x402-close { background: #222222; color: #8a90a8; }
-	.x402-close:hover { background: #2e2e2e; color: #e6e8f0; }
-	.x402-price-row { background: linear-gradient(180deg, #1d1d1d 0%, #161616 100%); }
-	.x402-network { background: #222222; color: #b0b6cc; }
-	.x402-wallet-btn { background: #1d1d1d; border-color: #2e2e2e; color: #e6e8f0; }
-	.x402-wallet-btn:hover:not(:disabled) { background: #252525; border-color: #0a84ff; }
-	.x402-wallet-icon { background: #2e2e2e; }
-	.x402-wallet-meta { color: #6b7088; }
-	.x402-pay-btn { background: #ffffff; color: #0f0f0f; }
-	.x402-pay-btn:hover:not(:disabled) { background: #e7e9ee; }
-	.x402-pay-btn:disabled { background: #2e2e2e; color: #5a6378; }
-	.x402-pay-secondary { background: #1d1d1d; border-color: #2e2e2e; color: #e6e8f0; }
-	.x402-pay-secondary:hover:not(:disabled) { background: #252525; border-color: #0a84ff; }
-	.x402-siwx-hint { color: #8a90a8; }
-	.x402-siwx-fallback { background: #2a1d10; border-color: #78350f; color: #fcd34d; }
-	.x402-step-num { background: #161616; border-color: #2e2e2e; color: #8a90a8; }
-	.x402-result { background: #1d1d1d; border-color: #2e2e2e; color: #e6e8f0; }
-	.x402-receipt { background: linear-gradient(180deg, #0b1f17 0%, #161616 100%); border-color: #14532d; }
-	.x402-receipt-title { color: #4ade80; }
-	.x402-receipt-row .x402-k { color: #8a90a8; }
-	.x402-receipt-row .x402-v { color: #e6e8f0; }
-	.x402-receipt-row a { color: #60a5fa; }
-	.x402-error-box { background: #1f1416; border-color: #7f1d1d; color: #fca5a5; }
-	.x402-foot a { color: #b0b6cc; }
-	.x402-foot a:hover { color: #ffffff; }
+@media (max-width: 520px) {
+	.x402-overlay { align-items: flex-end; }
+	.x402-modal {
+		max-width: none; width: 100%;
+		border-radius: var(--x402-radius) var(--x402-radius) 0 0;
+		max-height: 92dvh;
+		transform: translateY(100%);
+	}
+	.x402-overlay.x402-open .x402-modal { transform: translateY(0); }
+	.x402-price { font-size: 28px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.x402-overlay, .x402-modal, .x402-body > *,
+	.x402-receipt, .x402-receipt-check, .x402-receipt-check svg path { animation: none !important; transition: none !important; }
+	.x402-step.x402-active .x402-step-num { animation: none; }
+	.x402-network::before { animation: none; }
+	.x402-receipt-check svg path { stroke-dashoffset: 0; }
 }
 `;
 
+// Crisp inline SVG iconography — emoji/letter placeholders render differently
+// per-OS and read as cheap; these inherit currentColor and stay sharp at any DPI.
+const ICONS = {
+	close: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18"/></svg>',
+	lock: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="5" y="11" width="14" height="9" rx="2"/><path d="M8 11V8a4 4 0 0 1 8 0v3"/></svg>',
+	check: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 13l4 4L19 7"/></svg>',
+	shield: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3l7 3v6c0 4.5-3 7.4-7 9-4-1.6-7-4.5-7-9V6z"/><path d="M9 12l2 2 4-4"/></svg>',
+	phantom: '<svg viewBox="0 0 24 24" aria-hidden="true"><rect width="24" height="24" rx="6" fill="#ab9ff2"/><path fill="#fff" d="M19 12.4c0 3.8-3.1 6.8-7 6.8-.6 0-1-.6-.7-1.1.2-.4 0-.9-.4-1.1-.4-.2-1 0-1.3.4-.5.7-1.3 1.1-2.2 1.1H6.7c-1.2 0-2.2-1-2.2-2.2v-1.7c0-4.1 3.4-7.4 7.5-7.4h-.1c3.9 0 7.1 2.6 7.1 5.9z"/><circle cx="9.4" cy="12.4" r="1" fill="#534bb1"/><circle cx="12.6" cy="12.4" r="1" fill="#534bb1"/></svg>',
+	wallet: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="6" width="18" height="13" rx="2.5"/><path d="M3 10h18"/><circle cx="16.5" cy="14" r="1.3" fill="currentColor" stroke="none"/></svg>',
+};
+
+// Human-readable headings for the failure step shown in the error box. Never
+// surface the internal step id ("authorize", "verify") to a buyer.
+const STEP_LABELS = {
+	discover: "Couldn't confirm the price",
+	connect: "Couldn't connect your wallet",
+	authorize: "Payment couldn't be authorized",
+	verify: "Payment couldn't be completed",
+};
+
+// ──────────────────────────────────────────────────── wallet discovery ────
+// Detect every injected Solana wallet, not just Phantom — Solflare/Backpack/Glow
+// users were dead-ended before. They share Phantom's connect/signTransaction/
+// signMessage shape, so each drops straight into runSolana. Returns
+// [{ kind:'solana', name, provider, icon }] in preference order.
+function discoverSolanaWallets() {
+	if (typeof window === 'undefined') return [];
+	const out = [];
+	const seen = new Set();
+	const add = (name, provider, icon) => {
+		if (!provider || typeof provider.signTransaction !== 'function' || seen.has(provider)) return;
+		seen.add(provider);
+		out.push({ kind: 'solana', name, provider, icon: icon || ICONS.wallet });
+	};
+	add('Phantom', window.phantom?.solana || (window.solana?.isPhantom ? window.solana : null), ICONS.phantom);
+	add('Solflare', window.solflare?.isSolflare ? window.solflare : null, ICONS.wallet);
+	add('Backpack', window.backpack?.isBackpack ? window.backpack : null, ICONS.wallet);
+	add('Glow', window.glowSolana || window.glow || null, ICONS.wallet);
+	add('Coinbase Wallet', window.coinbaseSolana || null, ICONS.wallet);
+	// A standards-compliant injected provider that isn't one of the above.
+	if (window.solana && !window.solana.isPhantom) add(window.solana.isSolflare ? 'Solflare' : 'Solana wallet', window.solana, ICONS.wallet);
+	return out;
+}
+
+// EIP-6963 multi-provider discovery so a user with several EVM wallets isn't
+// stuck with whoever won the window.ethereum race. Wallets that implement 6963
+// re-announce synchronously on request; we fall back to legacy window.ethereum
+// (and its .providers[] array) when none do.
+function discoverEvmWallets() {
+	if (typeof window === 'undefined' || typeof window.dispatchEvent !== 'function') return [];
+	const out = [];
+	const seen = new Set();
+	const add = (name, provider, icon) => {
+		if (!provider || seen.has(provider)) return;
+		seen.add(provider);
+		out.push({ kind: 'evm', name: name || 'Browser wallet', provider, icon: icon || ICONS.wallet });
+	};
+	const announced = [];
+	const onAnnounce = (e) => { if (e?.detail) announced.push(e.detail); };
+	window.addEventListener('eip6963:announceProvider', onAnnounce);
+	try { window.dispatchEvent(new Event('eip6963:requestProvider')); } catch { /* ignore */ }
+	window.removeEventListener('eip6963:announceProvider', onAnnounce);
+	for (const d of announced) add(d.info?.name, d.provider, d.info?.icon);
+	if (!out.length) {
+		const eth = window.ethereum;
+		const label = (p) => (p?.isMetaMask ? 'MetaMask' : p?.isCoinbaseWallet ? 'Coinbase Wallet' : 'Browser wallet');
+		if (Array.isArray(eth?.providers)) for (const p of eth.providers) add(label(p), p);
+		else if (eth) add(label(eth), eth);
+	}
+	return out;
+}
+
+// A wallet's icon is either an inline SVG string (our ICONS) or a data:/https
+// URL (EIP-6963 / Wallet-Standard supply these) — render accordingly.
+function walletIconHtml(icon) {
+	if (icon && /^(data:|https?:)/.test(icon)) return `<img src="${escapeHtml(icon)}" alt="" />`;
+	return icon || ICONS.wallet;
+}
+
 function injectStyles() {
 	if (document.getElementById(STYLE_ID)) return;
 	const el = document.createElement('style');
@@ -795,22 +1018,40 @@ class CheckoutModal {
 		injectStyles();
 		const overlay = document.createElement('div');
 		overlay.className = 'x402-overlay';
+		// Forced color scheme (configure({ theme })) overrides the OS preference.
+		if (CONFIG.theme === 'dark') overlay.classList.add('x402-theme-dark');
+		else if (CONFIG.theme === 'light') overlay.classList.add('x402-theme-light');
+		// Brand design-token overrides applied inline so they win without !important.
+		if (CONFIG.cssVars && typeof CONFIG.cssVars === 'object') {
+			for (const [k, v] of Object.entries(CONFIG.cssVars)) {
+				if (/^--x402-[a-z0-9-]+$/i.test(k)) overlay.style.setProperty(k, String(v));
+			}
+		}
+		const logo = CONFIG.brand?.logo
+			? `<img class="x402-brand-logo" src="${escapeHtml(CONFIG.brand.logo)}" alt="" />`
+			: '';
 		overlay.innerHTML = `
-			<div class="x402-modal" role="dialog" aria-modal="true" aria-label="x402 payment">
+			<div class="x402-modal" role="dialog" aria-modal="true" aria-labelledby="x402-act" aria-describedby="x402-price">
 				<div class="x402-head">
 					<div class="x402-merchant">
-						<div class="x402-name" data-merchant>${escapeHtml(this.opts.merchant || 'Payment')}</div>
-						<div class="x402-action" data-action>${escapeHtml(this.opts.action || 'Pay-per-call')}</div>
+						${logo}
+						<div class="x402-merchant-text">
+							<div class="x402-name" data-merchant>${escapeHtml(this.opts.merchant || 'Payment')}</div>
+							<div class="x402-action" id="x402-act" data-action>${escapeHtml(this.opts.action || 'Pay-per-call')}</div>
+						</div>
 					</div>
-					<button class="x402-close" data-close aria-label="Close">✕</button>
+					<button class="x402-close" data-close aria-label="Close payment">${ICONS.close}</button>
 				</div>
 				<div class="x402-price-row">
-					<div class="x402-price" data-price>—<span class="x402-currency"> USDC</span></div>
+					<div class="x402-price-main">
+						<div class="x402-price" id="x402-price" data-price>—<span class="x402-currency"> USDC</span></div>
+						<div class="x402-price-sub" data-price-sub></div>
+					</div>
 					<div class="x402-network" data-network>resolving…</div>
 				</div>
-				<div class="x402-body" data-body></div>
+				<div class="x402-body" data-body aria-live="polite"></div>
 				<div class="x402-foot">
-					<span class="x402-secure">${escapeHtml(CONFIG.footerNote)}</span>
+					<span class="x402-secure">${ICONS.lock}${escapeHtml(CONFIG.footerNote)}</span>
 					${CONFIG.brand?.name ? `<a href="${escapeHtml(CONFIG.brand.url || '#')}" target="_blank" rel="noopener">Powered by ${escapeHtml(CONFIG.brand.name)}</a>` : ''}
 				</div>
 			</div>
@@ -819,24 +1060,57 @@ class CheckoutModal {
 		this.overlay = overlay;
 		this.bodyEl = overlay.querySelector('[data-body]');
 		this.priceEl = overlay.querySelector('[data-price]');
+		this.priceSubEl = overlay.querySelector('[data-price-sub]');
 		this.networkEl = overlay.querySelector('[data-network]');
 		overlay.querySelector('[data-close]').addEventListener('click', () => this.close('cancelled'));
 		overlay.addEventListener('click', (e) => { if (e.target === overlay) this.close('cancelled'); });
-		this.onKey = (e) => { if (e.key === 'Escape') this.close('cancelled'); };
+		// Remember what had focus so we can restore it on close (a11y).
+		this.previouslyFocused = typeof document !== 'undefined' ? document.activeElement : null;
+		this.onKey = (e) => {
+			if (e.key === 'Escape') { this.close('cancelled'); return; }
+			if (e.key === 'Tab') this.trapTab(e);
+		};
 		document.addEventListener('keydown', this.onKey);
-		requestAnimationFrame(() => overlay.classList.add('x402-open'));
+		requestAnimationFrame(() => {
+			overlay.classList.add('x402-open');
+			this.focusFirst();
+		});
 		return new Promise((resolve, reject) => {
 			this.resolve = resolve;
 			this.reject = reject;
 		});
 	}
 
+	// All visible, enabled, focusable elements inside the modal, in DOM order.
+	focusables() {
+		if (!this.overlay) return [];
+		const sel = 'button:not([disabled]), [href], input:not([disabled]), select, textarea, [tabindex]:not([tabindex="-1"])';
+		return Array.from(this.overlay.querySelectorAll(sel)).filter((el) => el.offsetParent !== null);
+	}
+
+	focusFirst() {
+		const list = this.focusables();
+		(list.find((el) => !el.hasAttribute('data-close')) || list[0])?.focus?.();
+	}
+
+	// Keep Tab within the dialog — a modal must not leak focus to the page behind.
+	trapTab(e) {
+		const list = this.focusables();
+		if (!list.length) return;
+		const first = list[0];
+		const last = list[list.length - 1];
+		if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+		else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+	}
+
 	close(reason) {
 		if (this.disposed) return;
 		this.disposed = true;
 		document.removeEventListener('keydown', this.onKey);
 		this.overlay.classList.remove('x402-open');
 		setTimeout(() => this.overlay.remove(), 180);
+		// Restore focus to whatever triggered the modal.
+		this.previouslyFocused?.focus?.();
 		if (reason === 'cancelled' && this.reject) {
 			const err = new Error('cancelled');
 			err.code = 'cancelled';
@@ -872,8 +1146,13 @@ class CheckoutModal {
 	}
 
 	renderConnect() {
-		const phantomDetected = typeof window !== 'undefined' && (window.solana?.isPhantom || window.phantom?.solana);
-		const evmDetected = typeof window !== 'undefined' && window.ethereum;
+		// Detect ALL injected wallets, not just Phantom/window.ethereum.
+		const solanaWallets = discoverSolanaWallets();
+		const evmWallets = discoverEvmWallets();
+		this._solWallets = solanaWallets;
+		this._evmWallets = evmWallets;
+		const phantomDetected = solanaWallets.length > 0;
+		const evmDetected = evmWallets.length > 0;
 		const solanaList = listSolanaAccepts(this.challenge);
 		// Keep a valid selection: honour the buyer's prior pick if it's still on
 		// offer, otherwise fall back to the default (USDC-first).
@@ -904,10 +1183,12 @@ class CheckoutModal {
 		// fallback, which needs to explain itself. One-shot via autoConnectTried.
 		if (this.opts.autoConnect && !this.autoConnectTried && !this.siwxFallbackNotice) {
 			this.autoConnectTried = true;
-			const solanaViable = !!(solanaAccept && phantomDetected);
-			const evmViable = !!(evmAccept && evmDetected);
-			if (solanaViable && !evmViable) { this.runSolana(solanaAccept); return; }
-			if (evmViable && !solanaViable) { this.runEvm(evmAccept); return; }
+			// Only auto-connect when there's exactly one wallet to choose — otherwise
+			// the buyer must pick which one.
+			const solanaViable = solanaAccept && solanaWallets.length === 1;
+			const evmViable = evmAccept && evmWallets.length === 1;
+			if (solanaViable && !evmViable) { this.runSolana(solanaAccept, solanaWallets[0].provider); return; }
+			if (evmViable && !solanaViable) { this.runEvm(evmAccept, evmWallets[0].provider); return; }
 		}
 
 		// When the merchant offers more than one Solana token (e.g. USDC and
@@ -933,40 +1214,75 @@ class CheckoutModal {
 			const solMeta = solanaList.length > 1
 				? `${networkLabel(solanaAccept.network, solanaAccept)} · ${solInfo.symbol}`
 				: networkLabel(solanaAccept.network, solanaAccept);
-			buttons.push(`
-				<button class="x402-wallet-btn" data-wallet="phantom" ${phantomDetected ? '' : 'disabled'}>
-					<div class="x402-wallet-icon x402-phantom">P</div>
-					<span class="x402-wallet-name">${phantomDetected ? 'Phantom' : 'Phantom (not detected)'}</span>
-					<span class="x402-wallet-meta" data-sol-meta>${escapeHtml(solMeta)}</span>
-				</button>
-			`);
+			if (solanaWallets.length) {
+				solanaWallets.forEach((w, i) => buttons.push(`
+					<button class="x402-wallet-btn" data-wallet-kind="solana" data-wallet-idx="${i}">
+						<div class="x402-wallet-icon">${walletIconHtml(w.icon)}</div>
+						<span class="x402-wallet-name">${escapeHtml(w.name)}</span>
+						<span class="x402-wallet-meta"${i === 0 ? ' data-sol-meta' : ''}>${escapeHtml(solMeta)}</span>
+					</button>
+				`));
+			} else {
+				buttons.push(`
+					<button class="x402-wallet-btn" disabled>
+						<div class="x402-wallet-icon">${ICONS.phantom}</div>
+						<span class="x402-wallet-name">No Solana wallet detected</span>
+						<span class="x402-wallet-meta">${escapeHtml(solMeta)}</span>
+					</button>
+				`);
+			}
 		}
 		if (evmAccept) {
-			buttons.push(`
-				<button class="x402-wallet-btn" data-wallet="evm" ${evmDetected ? '' : 'disabled'}>
-					<div class="x402-wallet-icon x402-metamask">M</div>
-					<span class="x402-wallet-name">${evmDetected ? 'Browser wallet' : 'No EVM wallet detected'}</span>
-					<span class="x402-wallet-meta">${networkLabel(evmAccept.network, evmAccept)}</span>
-				</button>
-			`);
+			if (evmWallets.length) {
+				evmWallets.forEach((w, i) => buttons.push(`
+					<button class="x402-wallet-btn" data-wallet-kind="evm" data-wallet-idx="${i}">
+						<div class="x402-wallet-icon">${walletIconHtml(w.icon)}</div>
+						<span class="x402-wallet-name">${escapeHtml(w.name)}</span>
+						<span class="x402-wallet-meta">${escapeHtml(networkLabel(evmAccept.network, evmAccept))}</span>
+					</button>
+				`));
+			} else {
+				buttons.push(`
+					<button class="x402-wallet-btn" disabled>
+						<div class="x402-wallet-icon">${ICONS.wallet}</div>
+						<span class="x402-wallet-name">No EVM wallet detected</span>
+						<span class="x402-wallet-meta">${escapeHtml(networkLabel(evmAccept.network, evmAccept))}</span>
+					</button>
+				`);
+			}
 		}
+		// When nothing is installed, don't dead-end — point users to a wallet.
+		const installHelp = (!phantomDetected && !evmDetected)
+			? `<div class="x402-wallet-install">No wallet detected — install
+					${solanaAccept ? `<a href="https://phantom.app/download" target="_blank" rel="noopener">Phantom</a>` : ''}${solanaAccept && evmAccept ? ' or ' : ''}${evmAccept ? `<a href="https://metamask.io/download" target="_blank" rel="noopener">MetaMask</a>` : ''}
+					to continue.</div>`
+			: '';
 		const fallbackBox = this.siwxFallbackNotice
 			? `<div class="x402-siwx-fallback">${escapeHtml(this.siwxFallbackNotice)}</div>`
 			: '';
+		// True for the exact scheme: the signed authorization can only move the
+		// stated amount to the stated recipient — a strong, honest trust signal.
+		const trustInfo = tokenInfo(this.accept);
+		const trustAmt = formatAmount(this.accept.amount, trustInfo.decimals);
+		const trustLine = `<div class="x402-trust">${ICONS.shield}<span>You authorize exactly ${escapeHtml(trustAmt)} ${escapeHtml(trustInfo.symbol)} — nothing more can be charged.</span></div>`;
 		this.bodyEl.innerHTML = `
 			${this.renderSteps('connect', { discover: 'done' })}
 			${fallbackBox}
 			${tokenChooser}
 			<div class="x402-wallet-buttons">${buttons.join('')}</div>
+			${installHelp}
+			${(phantomDetected || evmDetected) ? trustLine : ''}
 		`;
+		requestAnimationFrame(() => this.focusFirst());
 		const onClick = (e) => {
-			const btn = e.target.closest('[data-wallet]');
+			const btn = e.target.closest('[data-wallet-kind]');
 			if (!btn || btn.disabled) return;
-			const wallet = btn.dataset.wallet;
-			if (wallet === 'phantom') this.runSolana(this.solanaAccept);
-			else if (wallet === 'evm') this.runEvm(evmAccept);
+			const kind = btn.dataset.walletKind;
+			const idx = Number(btn.dataset.walletIdx);
+			if (kind === 'solana') this.runSolana(this.solanaAccept, this._solWallets[idx]?.provider);
+			else if (kind === 'evm') this.runEvm(evmAccept, this._evmWallets[idx]?.provider);
 		};
-		this.bodyEl.querySelectorAll('[data-wallet]').forEach((b) => b.addEventListener('click', onClick));
+		this.bodyEl.querySelectorAll('[data-wallet-kind]').forEach((b) => b.addEventListener('click', onClick));
 
 		// Token chooser — switch the active Solana token in place: update the
 		// headline price and the Phantom button's token label without a re-render
@@ -1040,10 +1356,15 @@ class CheckoutModal {
 				[stepId]: 'error',
 				[`${stepId}_meta`]: 'failed',
 			})}
-			<div class="x402-error-box"><strong>${escapeHtml(stepId)}:</strong> ${escapeHtml(message)}</div>
+			<div class="x402-error-box">
+				<div class="x402-error-title">${escapeHtml(STEP_LABELS[stepId] || 'Something went wrong')}</div>
+				<div class="x402-error-detail">${escapeHtml(message)}</div>
+			</div>
 			<button class="x402-pay-btn" data-retry>Try again</button>
 		`;
-		this.bodyEl.querySelector('[data-retry]').addEventListener('click', () => this.start());
+		const retry = this.bodyEl.querySelector('[data-retry]');
+		retry.addEventListener('click', () => this.start());
+		requestAnimationFrame(() => retry.focus());
 	}
 
 	renderDone({ result, payment, siwx }) {
@@ -1053,7 +1374,8 @@ class CheckoutModal {
 			const addrShort = siwx.address ? `${siwx.address.slice(0, 8)}…${siwx.address.slice(-6)}` : '—';
 			receiptHtml = `
 				<div class="x402-receipt">
-					<div class="x402-receipt-title">Welcome back!</div>
+					<div class="x402-receipt-check">${ICONS.check}</div>
+					<div class="x402-receipt-title">Welcome back</div>
 					<div class="x402-receipt-row">
 						<span class="x402-k">network</span>
 						<span class="x402-v">${escapeHtml(networkLabel(siwx.network) || siwx.network || '—')}</span>
@@ -1073,7 +1395,8 @@ class CheckoutModal {
 			const txShort = payment?.transaction ? `${payment.transaction.slice(0, 8)}…${payment.transaction.slice(-6)}` : '—';
 			receiptHtml = `
 				<div class="x402-receipt">
-					<div class="x402-receipt-title">Payment confirmed!</div>
+					<div class="x402-receipt-check">${ICONS.check}</div>
+					<div class="x402-receipt-title">Payment confirmed</div>
 					<div class="x402-receipt-row">
 						<span class="x402-k">network</span>
 						<span class="x402-v">${escapeHtml(networkLabel(payment?.network) || '—')}</span>
@@ -1092,21 +1415,27 @@ class CheckoutModal {
 				</div>
 			`;
 		}
+		// A string result is human-readable content (a summary, an answer) — show it
+		// as prose, not in a monospace JSON box. Objects stay as formatted JSON.
+		const isProse = typeof result === 'string';
 		this.bodyEl.innerHTML = `
 			${receiptHtml}
-			<div class="x402-result">${escapeHtml(resultStr).slice(0, 4000)}</div>
+			<div class="x402-result${isProse ? ' x402-prose' : ''}">${escapeHtml(resultStr).slice(0, 4000)}</div>
 			<button class="x402-pay-btn" data-done>Done</button>
 		`;
-		this.bodyEl.querySelector('[data-done]').addEventListener('click', () => {
-			this.disposed = true;
-			document.removeEventListener('keydown', this.onKey);
-			this.overlay.classList.remove('x402-open');
-			setTimeout(() => this.overlay.remove(), 180);
-		});
+		const doneBtn = this.bodyEl.querySelector('[data-done]');
+		doneBtn.addEventListener('click', () => this.close('done'));
+		requestAnimationFrame(() => doneBtn.focus());
 	}
 
 	async start() {
 		this.bodyEl.innerHTML = this.renderSteps('discover');
+		// Shimmer skeletons for the price/network while we fetch the challenge.
+		this.priceEl.innerHTML = '<span class="x402-skeleton" style="display:inline-block;width:92px;height:26px;vertical-align:middle"></span>';
+		this.networkEl.innerHTML = '<span class="x402-skeleton" style="display:inline-block;width:58px;height:11px;border-radius:99px"></span>';
+		// Pre-warm the Solana web3 import now (while the user reads the modal and we
+		// fetch the challenge) so a slow CDN doesn't stall at sign time. Best-effort.
+		loadSolanaWeb3().catch(() => {});
 		try {
 			const challenge = await discoverChallenge(this.opts);
 			this.challenge = challenge;
@@ -1129,13 +1458,14 @@ class CheckoutModal {
 		}
 	}
 
-	async runSolana(accept) {
+	async runSolana(accept, providerArg) {
 		this.accept = accept;
 		this.setPrice(accept);
-		this.renderProgress('connect', { text: 'Opening Phantom…' });
+		const provider = providerArg || window.phantom?.solana || window.solana;
+		const walletName = provider?.isPhantom ? 'Phantom' : (this._solWallets?.find((w) => w.provider === provider)?.name || 'wallet');
+		this.renderProgress('connect', { text: `Opening ${walletName}…` });
 		try {
-			const provider = window.phantom?.solana || window.solana;
-			if (!provider) throw new Error('Phantom wallet not detected');
+			if (!provider) throw new Error('No Solana wallet detected');
 			const conn = await provider.connect();
 			const payerAddress = (conn?.publicKey || provider.publicKey)?.toString();
 			if (!payerAddress) throw new Error('Phantom did not return a public key');
@@ -1184,12 +1514,12 @@ class CheckoutModal {
 		}
 	}
 
-	async runEvm(accept) {
+	async runEvm(accept, providerArg) {
 		this.accept = accept;
 		this.setPrice(accept);
 		this.renderProgress('connect', { text: 'Opening browser wallet…' });
 		try {
-			const eth = window.ethereum;
+			const eth = providerArg || window.ethereum;
 			if (!eth) throw new Error('No EVM wallet detected');
 			const accounts = await eth.request({ method: 'eth_requestAccounts' });
 			const payerAddress = accounts?.[0];
@@ -1302,6 +1632,9 @@ class CheckoutModal {
 		this.renderProgress('verify', {
 			text: attempt ? 'Retrying after upstream throttle…' : 'Calling merchant endpoint…',
 		});
+		// One idempotency key for this payment's whole lifetime (all retries and any
+		// "Try again") so a re-sent X-PAYMENT settles at most once — no double charge.
+		if (!this.idempotencyKey) this.idempotencyKey = `x402-${randomHex(16)}`;
 		try {
 			const res = await fetch(this.opts.endpoint, {
 				method: this.opts.method || 'GET',
@@ -1309,6 +1642,8 @@ class CheckoutModal {
 					...(this.opts.headers || {}),
 					...(this.opts.body && !this.opts.headers?.['content-type'] ? { 'content-type': 'application/json' } : {}),
 					'X-PAYMENT': xPayment,
+					'Idempotency-Key': this.idempotencyKey,
+					'X-Idempotency-Key': this.idempotencyKey,
 				},
 				body: this.opts.body ? (typeof this.opts.body === 'string' ? this.opts.body : JSON.stringify(this.opts.body)) : undefined,
 			});
@@ -1586,12 +1921,35 @@ function randomHex(bytes) {
 	return Array.from(arr).map((b) => b.toString(16).padStart(2, '0')).join('');
 }
 
+// Try the configured primary URL, then each independent CDN fallback, racing
+// every attempt against a timeout so a hung CDN doesn't stall the payment — it
+// just moves on to the next. Returns the first module that imports; throws only
+// if every candidate fails.
+async function importWithFallback(primary, fallbacks, label) {
+	const seen = new Set();
+	const candidates = [primary, ...fallbacks].filter((u) => u && !seen.has(u) && seen.add(u));
+	let lastErr;
+	for (const url of candidates) {
+		try {
+			return await Promise.race([
+				import(/* @vite-ignore */ url),
+				new Promise((_, reject) =>
+					setTimeout(() => reject(new Error(`timed out loading ${label} from ${url}`)), ESM_IMPORT_TIMEOUT_MS),
+				),
+			]);
+		} catch (err) {
+			lastErr = err;
+		}
+	}
+	throw lastErr || new Error(`could not load ${label} from any CDN`);
+}
+
 let _solanaWeb3 = null;
 async function loadSolanaWeb3() {
 	if (_solanaWeb3) return _solanaWeb3;
-	// Dynamic import from esm.sh keeps the drop-in script tiny — Solana web3.js
-	// is only fetched when a Solana payment is actually attempted.
-	_solanaWeb3 = await import(/* @vite-ignore */ CONFIG.esm.solanaWeb3);
+	// Loaded on demand (only when a Solana payment is attempted) and cached. The
+	// fallback chain means one CDN being down doesn't break Solana checkout.
+	_solanaWeb3 = await importWithFallback(CONFIG.esm.solanaWeb3, ESM_FALLBACKS.solanaWeb3, '@solana/web3.js');
 	return _solanaWeb3;
 }