Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

115 KB
Raw Blame
// x402.js — drop-in payment modal for any x402 paid endpoint.
//
// Merchants add one line to their site:
//
//   <script type="module" src="https://three.ws/x402.js"></script>
//
// Then any element with `data-x402-endpoint` opens a payment modal on click:
//
//   <button
//     data-x402-endpoint="https://example.com/api/paid/summarize"
//     data-x402-method="POST"
//     data-x402-body='{"text":"hello"}'
//     data-x402-merchant="Acme"
//     data-x402-action="Summarize"
//   >Pay & Run</button>
//
// On completion the element receives an `x402:result` CustomEvent whose detail
// is { ok, result, payment, response }. On error: `x402:error` with { error }.
//
// You can also call programmatically:
//
//   const out = await window.X402.pay({
//     endpoint: '/api/paid/summarize',
//     body: { text: 'hello' },
//     merchant: 'Acme',
//     action: 'Summarize',
//     networks: ['solana'], // optional allowlist — force a Solana-only checkout
//   });
//
// The modal handles wallet connect (Phantom for Solana, window.ethereum for
// Base USDC via EIP-3009), drives the 402 → sign → retry flow, and shows the
// result. Vanilla JS, no bundler required.
//
// Signed-in three.ws users additionally see their AGENTS' own custodial wallets
// as payment methods: picking one settles the payment entirely server-side via
// POST /api/x402-pay (owner-authenticated, CSRF-gated, per-agent spend caps),
// with no browser wallet popup. On third-party merchant embeds the session cookie
// never travels cross-origin, so that option simply doesn't render.

const VERSION = '0.2.0';

// Real-funds gate: before the first payment, the user must sign the three.ws
// real-funds agreements (three.ws/legal/agreements). Loaded lazily and
// failure-tolerant on purpose: this modal is a drop-in embed on merchant sites,
// and a payment must never brick because the gate module 404'd or was blocked.
// If risk-ack.js can't load, degrade to a native confirm() with the same core
// wording, remembered for the page session.
let _riskAckSessionOk = false;

async function ensureRiskAckSafe(context) {
	try {
		// Resolved relative to this module's URL, so merchant-site embeds load it
		// from the three.ws origin, not the host page's.
		const m = await import(new URL('./risk-ack.js', import.meta.url).href);
		return await m.ensureRiskAck({ context });
	} catch (err) {
		console.error('[x402] risk-ack unavailable, degrading to confirm()', err);
		if (_riskAckSessionOk) return true;
		try {
			_riskAckSessionOk = globalThis.confirm?.(
				'Real funds: sign the agreements\n\n' +
				'three.ws is experimental technology. By pressing OK you agree to the Terms of Service (three.ws/legal/tos), ' +
				'the Risk Disclosure (three.ws/legal/risk), and the Agent Wallet Agreement (three.ws/legal/agent-wallet). ' +
				'You confirm you are 18 or older and accept that funds can be lost completely for any reason, nothing is ' +
				'insured, and three.ws is not responsible for any loss.\n\n' +
				'Press OK to accept, or Cancel to stop.',
			) === true;
		} catch {
			_riskAckSessionOk = false;
		}
		return _riskAckSessionOk;
	}
}

// SIWX ("Sign-In-With-X" / CAIP-122) lets a wallet that has already paid for
// an endpoint re-enter it by signing a challenge instead of paying again. The
// server advertises support by including `extensions['sign-in-with-x']` in the
// 402 body; clients submit signed proofs via the `SIGN-IN-WITH-X` header. The
// architecture came from the siwx campaign plan, retired from prompts/ once
// shipped; see git history for the original.
const SIWX_HEADER = 'SIGN-IN-WITH-X';
const SIWX_EXTENSION_KEY = 'sign-in-with-x';

const ORIGIN = (() => {
	// Resolve the origin that hosts this script — used as the API origin for
	// the prepare/encode helpers. Falls back to the merchant origin in same-
	// origin mode.
	try {
		const script = document.currentScript;
		if (script?.src) return new URL(script.src).origin;
		const found = document.querySelector('script[src*="/x402.js"]');
		if (found?.src) return new URL(found.src).origin;
	} catch (_) {}
	return location.origin;
})();

// USDC EIP-3009 typed-data sig works against Base USDC at this address. The
// domain `version` must match the on-chain `EIP712_DOMAIN_SEPARATOR_VERSION`
// of the deployed USDC implementation — Base USDC is at version "2".
const EVM_NETWORKS = {
	'eip155:8453': { chainId: 8453, name: 'Base', explorer: 'https://basescan.org/tx/' },
	'eip155:84532': { chainId: 84532, name: 'Base Sepolia', explorer: 'https://sepolia.basescan.org/tx/' },
	'eip155:42161': { chainId: 42161, name: 'Arbitrum', explorer: 'https://arbiscan.io/tx/' },
	'eip155:10': { chainId: 10, name: 'Optimism', explorer: 'https://optimistic.etherscan.io/tx/' },
};

// Normalize a single 402 `accept` entry to the shape the modal speaks
// internally. The x402 spec's canonical atomic-price field is
// `maxAmountRequired`; some merchants (and our own server) emit `amount`. We
// read `amount` everywhere downstream (price display, cap check, prepare/encode
// POST body, EIP-3009 signing), so coerce here once at ingestion. Without this,
// a spec-compliant merchant yields `accept.amount === undefined` → "NaN USDC"
// in the modal and an `accept.amount: Required` 400 from /api/x402-checkout.
function normalizeAccept(accept) {
	if (!accept || typeof accept !== 'object') return accept;
	const amount = accept.amount ?? accept.maxAmountRequired;
	return amount != null && accept.amount == null ? { ...accept, amount: String(amount) } : accept;
}

function isSolanaNetwork(net) {
	return typeof net === 'string' && (net === 'solana' || net.startsWith('solana:'));
}
function isEvmNetwork(net) {
	return typeof net === 'string' && net.startsWith('eip155:');
}

/** Display symbol for an accept's asset, normalizing the long USDC name. */
function assetSymbol(accept) {
	return String(accept?.extra?.name || 'USDC').replace(/^USD Coin$/, 'USDC');
}

/**
 * Every Solana accept the challenge offers, one per distinct asset mint and in
 * advertised order (so the server's preferred token stays first / default).
 *
 * A resource may price itself in several tokens on the same network: three.ws
 * advertises USDC and $THREE on every paid endpoint. The modal used to take the
 * first Solana accept and offer no way to reach the rest, so a second token was
 * advertised in the 402 but unpayable in the browser.
 */
function solanaAcceptsOf(challenge) {
	const seen = new Set();
	const out = [];
	for (const accept of challenge?.accepts || []) {
		if (!isSolanaNetwork(accept.network)) continue;
		const key = accept.asset || assetSymbol(accept);
		if (seen.has(key)) continue;
		seen.add(key);
		out.push(accept);
	}
	return out;
}

// Resolve the active injected Solana wallet provider. Priority mirrors
// src/onchain/adapters/solana.js so the drop-in modal recognizes the SAME
// wallets the rest of three.ws does — most importantly the platform's own
// embedded wallet (the Seeker/Saga MWA bridge), which injects with
// isThreeWs=true / isPhantom=false. An isPhantom-only check left those users
// staring at a disabled "Phantom (not detected)" button: the modal opened but
// there was no way to pay (e.g. tipping a club dancer).
export function detectSolanaProvider() {
	if (typeof window === 'undefined') return null;
	if (window.threeWsWallet?.isThreeWs) return window.threeWsWallet;
	if (window.solana?.isThreeWs) return window.solana;
	if (window.phantom?.solana?.isPhantom) return window.phantom.solana;
	if (window.solana?.isPhantom) return window.solana;
	if (window.backpack?.solana) return window.backpack.solana;
	if (window.solflare?.isSolflare) return window.solflare;
	return null;
}

// Human-readable name for whichever Solana provider is connected, so progress
// copy and the wallet button say "three.ws Wallet" / "Backpack" instead of
// always claiming "Phantom".
export function solanaWalletLabel(provider) {
	if (provider?.isThreeWs) return 'three.ws Wallet';
	if (provider?.isPhantom) return 'Phantom';
	if (provider?.isBackpack) return 'Backpack';
	if (provider?.isSolflare) return 'Solflare';
	return 'Solana wallet';
}

// ── Agent-wallet payment method ──────────────────────────────────────────────
// A signed-in user's agents each hold a custodial Solana wallet server-side
// (agent_identities.meta), and POST /api/x402-pay pays an x402 endpoint from
// that wallet with ownership auth, a single-use CSRF token, and the per-agent
// spend policy enforced before any funds move. The picker lists those agents
// next to the injected browser wallets so an agent holding USDC can buy
// without Phantom ever opening.

let _agentWalletsCache = null; // { at: epoch-ms, list }; invalidated after a payment
const AGENT_WALLETS_TTL_MS = 30_000;

async function fetchAgentWallets() {
	if (_agentWalletsCache && Date.now() - _agentWalletsCache.at < AGENT_WALLETS_TTL_MS) {
		return _agentWalletsCache.list;
	}
	try {
		const res = await fetch(`${ORIGIN}/api/x402-pay?agents=1`, { credentials: 'include' });
		if (!res.ok) return null; // signed out (401) or unavailable: option not offered
		const data = await res.json();
		const list = (Array.isArray(data?.agents) ? data.agents : [])
			.filter((a) => a && a.solana_address)
			.sort((a, b) => (Number(b.usdc) || 0) - (Number(a.usdc) || 0));
		_agentWalletsCache = { at: Date.now(), list };
		return list;
	} catch (_) {
		return null;
	}
}

// Single-use CSRF token for the settle call (api/_lib/csrf.js burns tokens on
// first use, so one is fetched per payment, never cached).
async function fetchCsrfToken() {
	try {
		const res = await fetch(`${ORIGIN}/api/csrf-token`, { credentials: 'include' });
		if (!res.ok) return null;
		const j = await res.json().catch(() => null);
		return j?.data?.token || null;
	} catch (_) {
		return null;
	}
}

// POST /api/x402-pay as SSE and pump lifecycle events ('challenge' | 'built' |
// 'settled' | 'result' | 'error') to onEvent. Resolves the final result
// envelope; throws an Error carrying `.code` / `.envelope` on failure. Mirrors
// src/agent-x402-pay.js payX402Stream, inlined because this drop-in script
// cannot import bundled app modules.
async function payFromAgentWallet({ agentId, url, method, body, serviceLabel, csrfToken }, onEvent = () => {}) {
	const res = await fetch(`${ORIGIN}/api/x402-pay`, {
		method: 'POST',
		credentials: 'include',
		headers: {
			'content-type': 'application/json',
			accept: 'text/event-stream',
			...(csrfToken ? { 'x-csrf-token': csrfToken } : {}),
		},
		body: JSON.stringify({ agentId, url, method, body, service_label: serviceLabel, stream: true }),
	});
	// A non-stream error (auth, rate limit, validation) comes back as JSON, not SSE.
	const ctype = res.headers.get('content-type') || '';
	if (!res.ok && !ctype.includes('text/event-stream')) {
		const data = await res.json().catch(() => ({}));
		const err = new Error(data?.error_description || data?.error || `payment failed (${res.status})`);
		err.code = data?.code || data?.error;
		err.status = res.status;
		throw err;
	}
	if (!res.body) throw new Error('payment stream unavailable');

	const reader = res.body.getReader();
	const decoder = new TextDecoder();
	let buffer = '';
	let result = null;
	let failure = null;
	const dispatchEvent = (event, raw) => {
		let data = null;
		try { data = raw ? JSON.parse(raw) : null; } catch { data = null; }
		if (event === 'result') result = data;
		if (event === 'error') failure = data;
		try { onEvent(event, data); } catch (_) { /* a UI handler throwing must not break the pump */ }
	};
	for (;;) {
		const { value, done } = await reader.read();
		if (done) break;
		buffer += decoder.decode(value, { stream: true });
		let sep;
		while ((sep = buffer.indexOf('\n\n')) >= 0) {
			const frame = buffer.slice(0, sep);
			buffer = buffer.slice(sep + 2);
			let event = 'message';
			let data = '';
			for (const line of frame.split('\n')) {
				if (line.startsWith('event:')) event = line.slice(6).trim();
				else if (line.startsWith('data:')) data += line.slice(5).trim();
			}
			if (data || event !== 'message') dispatchEvent(event, data);
		}
	}
	if (failure) {
		const err = new Error(failure.error_description || failure.error || 'payment failed');
		err.code = failure.code;
		err.envelope = failure;
		throw err;
	}
	if (!result) throw new Error('payment ended without a result');
	return result;
}

// Compute the buyer-facing donation for a Solana `accept` under a merchant's
// giving config (charity split + round-up). Returns null when nothing applies:
// giving off, cause wallet on a different chain than this checkout, or a zero
// total. The donation settles in the SAME mint + transaction as the payment, so
// the cause wallet must be a Solana address. Pure integer math on atomics.
export function computeGiving(giving, accept) {
	if (!giving || !isSolanaNetwork(accept?.network)) return null;
	if (giving.charity_chain && giving.charity_chain !== 'solana') return null;
	const to = giving.charity_address;
	if (!to || !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(to)) return null;
	let base;
	try { base = BigInt(accept.amount); } catch { return null; }
	if (base <= 0n) return null;
	let charityCut = 0n;
	if (giving.charity_enabled && Number(giving.charity_bps) > 0) {
		charityCut = (base * BigInt(Math.round(Number(giving.charity_bps)))) / 10000n;
	}
	let roundupCut = 0n;
	if (giving.roundup_enabled && giving.roundup_to_atomics) {
		let nearest = 0n;
		try { nearest = BigInt(giving.roundup_to_atomics); } catch { nearest = 0n; }
		if (nearest > 0n) {
			const rem = base % nearest;
			if (rem > 0n) roundupCut = nearest - rem;
		}
	}
	const total = charityCut + roundupCut;
	if (total <= 0n) return null;
	const decimals = Number(accept.extra?.decimals ?? 6);
	const sym = (accept.extra?.name || 'USDC').replace(/^USD Coin$/, 'USDC');
	return {
		to,
		amount: total.toString(),
		charity: charityCut.toString(),
		roundup: roundupCut.toString(),
		total: (base + total).toString(),
		name: giving.charity_name || 'a good cause',
		decimals,
		sym,
	};
}
// The modal only signs EIP-3009 transferWithAuthorization for EVM. When the
// server publishes both an EIP-3009 entry and a Permit2 sibling (the
// gas-sponsoring path used by @x402/evm SDK clients), we must pick the
// EIP-3009 one — signing typed-data against the Permit2 entry would build a
// payload the facilitator rejects. The sibling carries
// `extra.assetTransferMethod === 'permit2'`; the legacy entry omits it.
function isEip3009Accept(accept) {
	if (!isEvmNetwork(accept?.network)) return false;
	const method = accept?.extra?.assetTransferMethod;
	return !method || method === 'eip3009';
}
// Opt-in allowlist (opts.networks). When a caller restricts which networks the
// modal may offer (e.g. ['solana'] to force a Solana-only checkout), drop every
// accept outside the allowlist before the picker renders. Families: 'solana' /
// 'svm' match any solana:* network, 'evm' matches any eip155:*, or pass an exact
// CAIP id like 'eip155:8453'. If the filter would empty the list we keep the
// original accepts so a misconfigured allowlist never breaks a live checkout.
function filterAcceptsByNetwork(challenge, networks) {
	if (!challenge || !Array.isArray(challenge.accepts) || !Array.isArray(networks) || !networks.length) return challenge;
	const want = networks.map((n) => String(n).toLowerCase());
	const allowed = (net) => want.some((w) => {
		if (w === 'solana' || w === 'svm') return isSolanaNetwork(net);
		if (w === 'evm') return isEvmNetwork(net);
		return typeof net === 'string' && net.toLowerCase() === w;
	});
	const kept = challenge.accepts.filter((a) => a && allowed(a.network));
	return kept.length ? { ...challenge, accepts: kept } : challenge;
}
function networkLabel(net, accept) {
	if (isSolanaNetwork(net)) return 'Solana';
	const meta = EVM_NETWORKS[net];
	return meta?.name || accept?.extra?.name || net;
}
function explorerUrl(net, tx) {
	if (!tx) return null;
	if (isSolanaNetwork(net)) return `https://solscan.io/tx/${tx}`;
	const meta = EVM_NETWORKS[net];
	return meta ? `${meta.explorer}${tx}` : null;
}

function formatAmount(rawAtomics, decimals = 6) {
	const n = Number(rawAtomics) / 10 ** decimals;
	if (n < 0.01) return n.toFixed(6).replace(/0+$/, '').replace(/\.$/, '');
	if (n < 1) return n.toFixed(4).replace(/0+$/, '').replace(/\.$/, '');
	return n.toFixed(2);
}

// Block-explorer link for a wallet ADDRESS (not a tx) — used by the
// insufficient-funds state so the buyer can inspect/top up their own wallet.
function addressExplorerUrl(net, addr) {
	if (!addr) return null;
	if (isSolanaNetwork(net)) return `https://solscan.io/account/${addr}`;
	const base = EVM_NETWORKS[net]?.explorer; // e.g. https://basescan.org/tx/
	return base ? `${base.replace(/tx\/?$/, '')}address/${addr}` : null;
}

// ── Pre-flight balance guard (UX, not security) ──────────────────────────────
// Spares the buyer from signing a transaction that can only fail at settle.
// Fail-open: a balance that can't be read (flaky RPC / provider quirk) returns
// null and the payment proceeds unchanged — only a POSITIVE shortfall blocks.
function solanaRpcUrl() {
	const meta = typeof document !== 'undefined' && document.querySelector('meta[name="solana-rpc-url"]');
	if (meta?.content) return meta.content;
	if (typeof window !== 'undefined' && window.SOLANA_RPC_URL) return window.SOLANA_RPC_URL;
	// Last resort: the /api/solana-rpc proxy co-deployed with this script, which
	// fails over across Helius → Alchemy → dRPC → five keyless public lanes, so the
	// balance read survives any single provider (an expired Helius plan included)
	// being down. Resolved from this module's own serving origin, NOT a hardcoded
	// host: as a third-party embed the script is loaded from three.ws (resolves to
	// three.ws); as the first-party app on a preview/dev/tunnel origin it resolves
	// same-origin, so the read never trips that origin's CORS allowlist.
	return scriptOrigin() + '/api/solana-rpc';
}

// Origin that served this module — where its same-deployment /api proxy lives.
function scriptOrigin() {
	try {
		const o = new URL(import.meta.url).origin;
		if (o && o !== 'null') return o;
	} catch {}
	if (typeof location !== 'undefined' && location.origin && location.origin !== 'null') {
		return location.origin;
	}
	return 'https://three.ws';
}
async function readSolanaBalanceAtomic(owner, mint) {
	try {
		const res = await fetch(solanaRpcUrl(), {
			method: 'POST',
			headers: { 'content-type': 'application/json' },
			body: JSON.stringify({
				jsonrpc: '2.0', id: 1, method: 'getTokenAccountsByOwner',
				params: [owner, { mint }, { encoding: 'jsonParsed' }],
			}),
		});
		if (!res.ok) return null;
		const data = await res.json();
		let total = 0n;
		for (const acc of data?.result?.value || []) {
			const amt = acc?.account?.data?.parsed?.info?.tokenAmount?.amount;
			if (amt != null) total += BigInt(amt);
		}
		return total;
	} catch (_) { return null; }
}
async function readEvmBalanceAtomic(provider, token, owner) {
	try {
		const data = '0x70a08231' + String(owner).toLowerCase().replace(/^0x/, '').padStart(64, '0');
		const hex = await provider.request({ method: 'eth_call', params: [{ to: token, data }, 'latest'] });
		if (!hex || hex === '0x') return null;
		return BigInt(hex);
	} catch (_) { return null; }
}
// Throws a structured insufficient-funds error (code + .insufficient) when a
// balance is positively read and short; resolves otherwise.
async function assertBalance({ accept, owner, provider }) {
	const required = BigInt(accept.amount);
	let balance = null;
	if (isSolanaNetwork(accept.network)) balance = await readSolanaBalanceAtomic(owner, accept.asset);
	else if (provider) balance = await readEvmBalanceAtomic(provider, accept.asset, owner);
	if (balance === null || balance >= required) return;
	const decimals = Number(accept.extra?.decimals ?? 6);
	const symbol = accept.extra?.name || 'USDC';
	const shortfall = required - balance;
	const err = new Error(
		`Not enough ${symbol} — you need ${formatAmount(required, decimals)} ${symbol} but your wallet holds ${formatAmount(balance, decimals)} ${symbol}.`,
	);
	err.code = 'insufficient_funds';
	err.insufficient = {
		symbol, network: accept.network, owner,
		required: formatAmount(required, decimals),
		balance: formatAmount(balance, decimals),
		shortfall: formatAmount(shortfall, decimals),
	};
	throw err;
}

function b64encode(obj) {
	const json = JSON.stringify(obj);
	if (typeof Buffer !== 'undefined') return Buffer.from(json, 'utf8').toString('base64');
	return btoa(unescape(encodeURIComponent(json)));
}
function b64decode(str) {
	if (!str) return null;
	try {
		const bin = typeof Buffer !== 'undefined' ? Buffer.from(str, 'base64').toString('utf8') : decodeURIComponent(escape(atob(str)));
		return JSON.parse(bin);
	} catch (_) {
		return null;
	}
}

// ──────────────────────────────────────────── Spending caps (USE-22) ────────
// Persists per-wallet spend in localStorage so reload-survivable caps work
// in a pure-browser context. Keys are bucketed by UTC hour and UTC day so
// the sliding windows reset cleanly at midnight UTC for the daily case.
// All amounts are stored as base-10 BigInt strings of micro-USD; stablecoin
// payments (USDC, USDT, DAI) flow through as-is since their atomics are
// already 6-decimal USD-pegged.

const SPEND_LS_PREFIX = 'x402.spend.';
const STABLE_NAMES = new Set([
	'usdc', 'usd coin', 'usdt', 'tether', 'binance-peg usd coin', 'dai',
]);

function spendBuckets(timestamp = Date.now()) {
	const hour = Math.floor(timestamp / 3_600_000);
	const day = Math.floor(timestamp / 86_400_000);
	return { hour, day };
}

function spendKey(address, kind, bucket) {
	return `${SPEND_LS_PREFIX}${kind}.${address.toLowerCase()}.${bucket}`;
}

function readSpend(address, kind, bucket) {
	try {
		const raw = localStorage.getItem(spendKey(address, kind, bucket));
		if (!raw) return 0n;
		return BigInt(raw);
	} catch {
		return 0n;
	}
}

function writeSpend(address, kind, bucket, value) {
	try {
		localStorage.setItem(spendKey(address, kind, bucket), value.toString());
	} catch {
		// localStorage full / disabled — caps degrade to per-call only.
	}
}

function toMicroUsdBrowser(amount, accept) {
	const atomic = BigInt(amount);
	const decimals = Number(accept?.extra?.decimals ?? 6);
	const name = String(accept?.extra?.name || '').toLowerCase();
	if (STABLE_NAMES.has(name)) {
		if (decimals === 6) return atomic;
		if (decimals > 6) return atomic / 10n ** BigInt(decimals - 6);
		return atomic * 10n ** BigInt(6 - decimals);
	}
	// Non-stable in the browser modal: we don't fetch live prices to keep the
	// drop-in script dependency-free. Cap enforcement for non-stable assets
	// must be done server-side via x402-spending-cap.js.
	return atomic;
}

// Check the configured caps and, if admitted, reserve the spend in
// localStorage. Returns { abort: boolean, reason?, reservation? }.
// Reservation has { address, microUsd, buckets } so rollback can undo.
function browserEnforceCap({ accept, caps, address }) {
	if (!caps || !address) return { abort: false };
	const microUsd = toMicroUsdBrowser(accept.amount, accept);
	const maxPerCall = caps.maxPerCall != null ? BigInt(caps.maxPerCall) : null;
	const maxPerHour = caps.maxPerHour != null ? BigInt(caps.maxPerHour) : null;
	const maxPerDay = caps.maxPerDay != null ? BigInt(caps.maxPerDay) : null;
	if (maxPerCall != null && microUsd > maxPerCall) {
		return {
			abort: true,
			reason: `Per-call cap exceeded (${microUsd} > ${maxPerCall} µUSD)`,
		};
	}
	const buckets = spendBuckets();
	const hourTotal = readSpend(address, 'hr', buckets.hour) + microUsd;
	const dayTotal = readSpend(address, 'day', buckets.day) + microUsd;
	if (maxPerHour != null && hourTotal > maxPerHour) {
		return { abort: true, reason: `Hourly cap exceeded (${hourTotal} > ${maxPerHour} µUSD)` };
	}
	if (maxPerDay != null && dayTotal > maxPerDay) {
		return { abort: true, reason: `Daily cap exceeded (${dayTotal} > ${maxPerDay} µUSD)` };
	}
	writeSpend(address, 'hr', buckets.hour, hourTotal);
	writeSpend(address, 'day', buckets.day, dayTotal);
	return { abort: false, reservation: { address, microUsd, buckets } };
}

function browserRollbackReservation(reservation) {
	if (!reservation) return;
	const { address, microUsd, buckets } = reservation;
	const hourCurrent = readSpend(address, 'hr', buckets.hour);
	const dayCurrent = readSpend(address, 'day', buckets.day);
	const hourNext = hourCurrent - microUsd;
	const dayNext = dayCurrent - microUsd;
	writeSpend(address, 'hr', buckets.hour, hourNext < 0n ? 0n : hourNext);
	writeSpend(address, 'day', buckets.day, dayNext < 0n ? 0n : dayNext);
}

// ──────────────────────────────────────────── ERC-8021 builder-code echo ────
// The server-side x402-spec.js 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"]`.

const BUILDER_CODE_KEY = 'builder-code';
const BUILDER_CODE_PATTERN = /^[a-z0-9_]{1,32}$/;
const OUR_WALLET_CODE = '3d_agent';
const OUR_SERVICE_CODE = '3d_agent_modal';

function buildBuilderCodeEcho(challenge) {
	const ext = challenge?.extensions?.[BUILDER_CODE_KEY];
	const declaredA = ext?.info?.a;
	if (!declaredA || !BUILDER_CODE_PATTERN.test(declaredA)) return null;
	const out = { a: declaredA };
	if (BUILDER_CODE_PATTERN.test(OUR_SERVICE_CODE)) out.s = [OUR_SERVICE_CODE];
	if (BUILDER_CODE_PATTERN.test(OUR_WALLET_CODE)) out.w = OUR_WALLET_CODE;
	return out;
}

// ─────────────────────────────────────────────────────────── SIWX helpers ────

function extractSiwxExtension(body) {
	const ext = body?.extensions?.[SIWX_EXTENSION_KEY];
	if (!ext || !ext.info || !Array.isArray(ext.supportedChains) || !ext.supportedChains.length) return null;
	return ext;
}

// Returns { chain, kind: 'evm' | 'solana' } or null. `chain` is the matching
// entry from `ext.supportedChains` whose signature type matches the wallet kind.
function pickSiwxChain(ext, walletKind) {
	for (const chain of ext.supportedChains) {
		if (walletKind === 'evm' && chain.type === 'eip191') return { chain, kind: 'evm' };
		if (walletKind === 'solana' && chain.type === 'ed25519') return { chain, kind: 'solana' };
	}
	return null;
}

// Build the CAIP-122 message string. The server rebuilds the same string from
// payload fields when verifying — any line-by-line drift makes the recovered
// signer mismatch payload.address and the signature is rejected.
//
// EVM path mirrors EIP-4361 / siwe library's prepareMessage (chain ref =
// numeric chainId extracted from "eip155:<n>"). Solana path mirrors SIWS
// (chain ref = genesis hash extracted from "solana:<ref>"). Optional fields
// are omitted entirely when absent from server info.
function buildSiwxMessage(info, chain, address) {
	const isEvm = chain.type === 'eip191';
	const accountHeader = isEvm
		? `${info.domain} wants you to sign in with your Ethereum account:`
		: `${info.domain} wants you to sign in with your Solana account:`;
	const [, chainTail = ''] = String(chain.chainId).split(':');
	const chainRef = isEvm ? String(parseInt(chainTail, 10)) : chainTail;

	const lines = [accountHeader, address, ''];
	if (info.statement) {
		lines.push(info.statement, '');
	} else if (isEvm) {
		// siwe's prepareMessage() reserves the statement block even when the
		// statement is absent, emitting an extra blank line (header, address,
		// "", "", URI). SIWS's formatter does not. The server rebuilds the EVM
		// message via siwe before recovering the signer, so omit-statement EVM
		// must carry the same extra blank or the recovered address mismatches.
		lines.push('');
	}
	lines.push(`URI: ${info.uri}`);
	lines.push(`Version: ${info.version || '1'}`);
	lines.push(`Chain ID: ${chainRef}`);
	lines.push(`Nonce: ${info.nonce}`);
	lines.push(`Issued At: ${info.issuedAt}`);
	if (info.expirationTime) lines.push(`Expiration Time: ${info.expirationTime}`);
	if (info.notBefore) lines.push(`Not Before: ${info.notBefore}`);
	if (info.requestId !== undefined && info.requestId !== null) lines.push(`Request ID: ${info.requestId}`);
	if (Array.isArray(info.resources) && info.resources.length) {
		lines.push('Resources:');
		for (const r of info.resources) lines.push(`- ${r}`);
	}
	return lines.join('\n');
}

// Base64-encoded JSON per x402 v2 spec (CHANGELOG-v2.md line 335). CAIP-122
// fields are all ASCII/Latin-1, so the unescape+encodeURIComponent dance
// matches what btoa expects without garbling unicode (none is sent anyway).
function encodeSiwxHeaderValue(payload) {
	const json = JSON.stringify(payload);
	if (typeof Buffer !== 'undefined') return Buffer.from(json, 'utf8').toString('base64');
	return btoa(unescape(encodeURIComponent(json)));
}

// Base58 (Bitcoin alphabet) — Solana's encoding for both addresses and
// signatures. Inlined here to avoid pulling in a bundler dependency; this
// matches what `bs58` does on the server side (api/_lib/siws.js).
const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
function base58encode(bytes) {
	if (!bytes || bytes.length === 0) return '';
	let leadingZeros = 0;
	while (leadingZeros < bytes.length && bytes[leadingZeros] === 0) leadingZeros++;
	let n = 0n;
	for (let i = 0; i < bytes.length; i++) n = (n << 8n) | BigInt(bytes[i]);
	let out = '';
	while (n > 0n) {
		out = BASE58_ALPHABET[Number(n % 58n)] + out;
		n /= 58n;
	}
	for (let i = 0; i < leadingZeros; i++) out = BASE58_ALPHABET[0] + out;
	return out;
}

// EIP-55 checksum the address before signing. MetaMask returns addresses in
// lowercase via eth_requestAccounts, but the server rebuilds the SIWE message
// with a checksummed address (siwe library's prepareMessage always upgrades
// case via getAddress). If we sign a lowercase-address message and send the
// lowercase address in the payload, the server's recovered signer (from the
// checksummed-address message it builds) differs from payload.address and
// verification fails. So checksum here, then use the same string everywhere.
//
// Keccak-256 lives in @noble/hashes which the server already uses
// (api/_lib/siws.js -> @noble/curves). Pulled in dynamically only when SIWX EVM
// sign-in is actually attempted, mirroring loadSolanaWeb3.
let _evmChecksum = null;
async function loadEvmChecksum() {
	if (_evmChecksum) return _evmChecksum;
	// Same mirror chain as the Solana loader: sign-in must not hinge on one CDN.
	const { loadModule } = await import('./load-module.js');
	const sha3 = await loadModule('https://esm.sh/@noble/[email protected]/sha3?bundle');
	const keccak = sha3.keccak_256;
	_evmChecksum = (addr) => {
		const a = String(addr).toLowerCase().replace(/^0x/, '');
		if (!/^[0-9a-f]{40}$/.test(a)) throw new Error(`invalid EVM address: ${addr}`);
		const hashBytes = keccak(new TextEncoder().encode(a));
		let hex = '';
		for (let i = 0; i < hashBytes.length; i++) hex += hashBytes[i].toString(16).padStart(2, '0');
		let out = '0x';
		for (let i = 0; i < 40; i++) {
			out += parseInt(hex[i], 16) >= 8 ? a[i].toUpperCase() : a[i];
		}
		return out;
	};
	return _evmChecksum;
}

// ───────────────────────────────────────────────────────────────── styles ────

const STYLE_ID = 'x402-styles';
const STYLES = `
:root {
	--x402-z: 2147483600;
}
.x402-overlay {
	position: fixed; inset: 0;
	background: rgba(8, 10, 18, 0.55);
	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;
	-webkit-font-smoothing: antialiased;
	color: #0f0f0f;
}
.x402-overlay.x402-open { opacity: 1; }
.x402-overlay * { box-sizing: border-box; }
.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);
	overflow: hidden;
	transform: translateY(8px) scale(0.985);
	transition: transform 0.18s ease-out;
	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;
	display: flex; align-items: center; gap: 12px;
}
.x402-head .x402-merchant {
	flex: 1; min-width: 0;
}
.x402-merchant .x402-name {
	font-size: 12px; color: #5a6378; 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;
	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;
	display: flex; align-items: center; justify-content: center;
	transition: background 0.12s;
}
.x402-close:hover { background: #e7e9ee; color: #0f0f0f; }

.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;
}
.x402-price {
	font-size: 32px; font-weight: 700; letter-spacing: -0.02em; color: #0f0f0f;
	font-variant-numeric: tabular-nums;
}
.x402-price .x402-currency { font-size: 14px; color: #5a6378; font-weight: 600; margin-left: 6px; letter-spacing: 0; }
.x402-network {
	font-size: 12px; color: #5a6378; font-weight: 500;
	background: #f3f4f7; 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;
}

.x402-body {
	padding: 16px 20px 18px;
	flex: 1 1 auto; overflow-y: auto;
	display: flex; flex-direction: column; gap: 10px;
}
.x402-step {
	display: flex; gap: 12px; align-items: flex-start;
	padding: 10px 0;
}
.x402-step + .x402-step { border-top: 1px solid #f3f4f7; }
.x402-step-num {
	width: 22px; height: 22px; flex: 0 0 auto;
	border-radius: 50%; border: 1.5px solid #d0d4dd; background: #fff;
	color: #5a6378;
	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;
	animation: x402-spin 1.2s linear infinite;
}
.x402-step.x402-done .x402-step-num {
	border-color: #22c55e; background: #22c55e; color: #fff;
}
.x402-step.x402-error .x402-step-num {
	border-color: #ef4444; background: #ef4444; 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); }
}
.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-wallet-buttons {
	display: flex; flex-direction: column; gap: 8px;
	margin-top: 4px;
}
.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;
	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: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;
}
.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.x402-agent { background: linear-gradient(135deg, #22c55e, #0ea5e9); color: #fff; }
.x402-wallet-name { flex: 1; text-align: left; }
.x402-wallet-sub { display: block; font-size: 11px; color: #8a90a8; font-weight: 500; margin-top: 1px; }
.x402-wallet-meta { font-size: 11px; color: #8a90a8; font-weight: 500; }
.x402-wallet-group-label {
	font-size: 11px; font-weight: 700; color: #8a90a8;
	text-transform: uppercase; letter-spacing: 0.06em;
	margin: 4px 0 0;
}

/* Token chooser: shown only when one network advertises the same resource in
   more than one asset (e.g. USDC and $THREE on Solana). Without it the modal
   silently settled the first accept and a second advertised token was
   unreachable no matter what the buyer held. */
.x402-token-choice {
	display: flex; gap: 6px; margin: 0 0 10px;
}
.x402-token-btn {
	flex: 1 1 0; min-width: 0; padding: 8px 10px;
	background: #ffffff; border: 1.5px solid #e2e5ec; border-radius: 10px;
	font-family: inherit; cursor: pointer; text-align: center;
	transition: border-color 0.12s, background 0.12s, transform 0.05s;
}
.x402-token-btn:hover:not(:disabled) { border-color: #0a84ff; background: #f7faff; }
.x402-token-btn:active:not(:disabled) { transform: translateY(1px); }
.x402-token-btn[aria-checked="true"] { border-color: #0a84ff; background: #f0f7ff; }
.x402-token-btn:focus-visible { outline: 2px solid #0a84ff; outline-offset: 2px; }
.x402-token-sym {
	display: block; font-size: 13px; font-weight: 700; color: #0f0f0f;
	overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
}
.x402-token-amt {
	display: block; font-size: 11px; font-weight: 500; color: #8a90a8;
	margin-top: 1px; font-feature-settings: 'tnum' 1;
	overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
}

.x402-pay-btn {
	width: 100%; padding: 14px 16px;
	background: #0f0f0f; color: #fff; border: none;
	border-radius: 12px;
	font-size: 15px; font-weight: 700; font-family: inherit;
	cursor: pointer; letter-spacing: -0.005em;
	transition: background 0.12s, transform 0.05s;
	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-secondary {
	width: 100%; padding: 12px 14px;
	background: #ffffff; color: #0f0f0f;
	border: 1.5px solid #e2e5ec; 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:active:not(:disabled) { transform: translateY(1px); }

.x402-siwx-hint {
	font-size: 11px; color: #5a6378; text-align: center;
	margin-top: 8px; line-height: 1.4;
}

.x402-insuff-title { font-size: 16px; font-weight: 700; color: #0f0f0f; letter-spacing: -0.01em; }
.x402-insuff-sub { font-size: 13px; color: #5a6378; margin-top: 4px; line-height: 1.45; }
.x402-insuff-actions { display: flex; gap: 8px; margin-top: 12px; }
.x402-insuff-actions > * { flex: 1; }
.x402-mini-btn {
	padding: 9px 12px; background: #ffffff; color: #0f0f0f;
	border: 1.5px solid #e2e5ec; border-radius: 10px;
	font-size: 13px; font-weight: 600; font-family: inherit;
	cursor: pointer; text-align: center; text-decoration: none;
	display: inline-flex; align-items: center; justify-content: center;
	transition: border-color 0.12s, background 0.12s;
}
.x402-mini-btn:hover { border-color: #0a84ff; background: #f7faff; text-decoration: none; }
.x402-mini-btn:focus-visible { outline: 2px solid #0a84ff; outline-offset: 2px; }

.x402-payee { font-size: 12px; color: #8a90a8; text-align: center; margin: 0 0 10px; }
.x402-payee-addr { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; color: #0a84ff; text-decoration: none; border-bottom: 1px dotted rgba(10,132,255,0.4); }
.x402-payee-addr:hover { border-bottom-style: solid; text-decoration: none; }
.x402-payee-addr:focus-visible { outline: 2px solid #0a84ff; outline-offset: 2px; border-radius: 2px; }
.x402-trust { font-size: 11px; color: #8a90a8; text-align: center; margin-top: 12px; line-height: 1.45; }

/* Keyboard focus indicator on every interactive control in the money modal. */
.x402-overlay button:focus-visible,
.x402-overlay a:focus-visible,
.x402-overlay input:focus-visible,
.x402-overlay [tabindex]:focus-visible {
	outline: 2px solid #0a84ff;
	outline-offset: 2px;
	border-radius: 8px;
}
.x402-modal:focus { outline: none; }
.x402-siwx-fallback {
	font-size: 12px; color: #b45309; line-height: 1.45;
	padding: 8px 10px; border-radius: 8px;
	background: #fffbeb; border: 1px solid #fde68a;
	margin-bottom: 6px;
}

.x402-giving {
	display: flex; align-items: flex-start; gap: 10px;
	padding: 11px 12px; margin-bottom: 10px;
	border-radius: 11px; border: 1px solid #bbf7d0;
	background: linear-gradient(180deg, #f0fdf4 0%, #ffffff 100%);
	cursor: pointer; user-select: none;
	transition: border-color 0.12s, background 0.12s;
}
.x402-giving:hover { border-color: #86efac; }
.x402-giving input { position: absolute; opacity: 0; width: 0; height: 0; }
.x402-giving-box {
	flex: 0 0 auto; width: 18px; height: 18px; margin-top: 1px;
	border-radius: 5px; border: 1.5px solid #86efac; background: #fff;
	display: flex; align-items: center; justify-content: center;
	color: #fff; font-size: 12px; line-height: 1; transition: background 0.12s, border-color 0.12s;
}
.x402-giving input:checked + .x402-giving-box { background: #16a34a; border-color: #16a34a; }
.x402-giving input:checked + .x402-giving-box::after { content: '✓'; }
.x402-giving input:focus-visible + .x402-giving-box { box-shadow: 0 0 0 3px rgba(22,163,74,0.25); }
.x402-giving-text { flex: 1 1 auto; min-width: 0; }
.x402-giving-title { font-size: 13px; font-weight: 700; color: #15803d; line-height: 1.3; }
.x402-giving-sub { font-size: 11.5px; color: #5a6378; margin-top: 2px; line-height: 1.4; font-feature-settings: 'tnum' 1; }
.x402-giving-amt { font-weight: 700; color: #0f0f0f; }

.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;
	word-break: break-word;
}
.x402-error-box strong { font-weight: 700; }

.x402-receipt {
	padding: 14px 16px; border-radius: 12px;
	background: linear-gradient(180deg, #f0fdf4 0%, #ffffff 100%);
	border: 1px solid #bbf7d0;
}
.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;
}
.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;
}
.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 a:hover { text-decoration: underline; }

.x402-result {
	padding: 12px 14px; border-radius: 10px;
	background: #fafbfc; border: 1px solid #e2e5ec;
	max-height: 240px; overflow: auto;
	font-family: ui-monospace, "JetBrains Mono", Menlo, monospace;
	font-size: 12px; line-height: 1.5; color: #0f0f0f;
	white-space: pre-wrap; word-break: break-word;
}

.x402-foot {
	padding: 10px 20px 14px;
	border-top: 1px solid #eef0f4;
	display: flex; align-items: center; justify-content: space-between;
	font-size: 11px; color: #8a90a8;
}
.x402-foot a { color: #5a6378; text-decoration: none; font-weight: 600; }
.x402-foot a:hover { color: #0f0f0f; }
.x402-foot .x402-secure { display: flex; align-items: center; gap: 5px; }
.x402-foot .x402-secure::before { content: '🔒'; font-size: 10px; }

@media (max-width: 480px) {
	.x402-modal { max-width: none; width: calc(100% - 16px); border-radius: 16px; }
	.x402-price { font-size: 26px; }
}

@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-wallet-sub { color: #6b7088; }
	.x402-wallet-group-label { color: #6b7088; }
	.x402-token-btn { background: #1d1d1d; border-color: #2e2e2e; }
	.x402-token-btn:hover:not(:disabled) { background: #252525; border-color: #0a84ff; }
	.x402-token-btn[aria-checked="true"] { background: #10243a; border-color: #0a84ff; }
	.x402-token-sym { color: #e6e8f0; }
	.x402-token-amt { 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; }
}
`;

function injectStyles() {
	if (document.getElementById(STYLE_ID)) return;
	const el = document.createElement('style');
	el.id = STYLE_ID;
	el.textContent = STYLES;
	document.head.appendChild(el);
}

// ───────────────────────────────────────────────────────────── modal class ───

class CheckoutModal {
	constructor(opts) {
		this.opts = opts;
		this.steps = [
			{ id: 'discover', label: 'Confirming price' },
			{ id: 'connect', label: 'Connect wallet' },
			{ id: 'authorize', label: 'Authorize payment' },
			{ id: 'verify', label: 'Verify & complete' },
		];
		this.activeNetwork = null;
		this.payerAddress = null;
		this.accept = null;
		this.challenge = null;
		this.disposed = false;
		// One-shot guard for opts.autoConnect: we only auto-open the wallet on the
		// first connect render, so an error that drops the user back to this step
		// shows the manual picker instead of re-launching the wallet in a loop.
		this.autoConnectTried = false;
	}

	mount() {
		injectStyles();
		const overlay = document.createElement('div');
		overlay.className = 'x402-overlay';
		overlay.innerHTML = `
			<div class="x402-modal" role="dialog" aria-modal="true" aria-label="x402 payment" tabindex="-1">
				<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>
					</div>
					<button class="x402-close" data-close aria-label="Close payment">✕</button>
				</div>
				<div class="x402-price-row">
					<div class="x402-price" data-price>—<span class="x402-currency"> USDC</span></div>
					<div class="x402-network" data-network>resolving…</div>
				</div>
				<div class="x402-body" data-body role="status" aria-live="polite"></div>
				<div class="x402-foot">
					<span class="x402-secure">x402 · onchain settled</span>
					<a href="https://three.ws" target="_blank" rel="noopener">Powered by three.ws</a>
				</div>
			</div>
		`;
		// Remember what to restore focus to when the modal closes.
		this.previouslyFocused =
			typeof document !== 'undefined' && document.activeElement instanceof HTMLElement
				? document.activeElement
				: null;
		document.body.appendChild(overlay);
		this.overlay = overlay;
		this.modalEl = overlay.querySelector('.x402-modal');
		this.bodyEl = overlay.querySelector('[data-body]');
		this.priceEl = overlay.querySelector('[data-price]');
		this.networkEl = overlay.querySelector('[data-network]');
		// Make the rest of the page inert to AT + tab order while the money modal is
		// open, so focus can't wander behind it mid-payment. Restored in close().
		this._inerted = [];
		for (const child of Array.from(document.body.children)) {
			if (child !== overlay && !child.hasAttribute('inert')) {
				child.setAttribute('inert', '');
				child.setAttribute('aria-hidden', 'true');
				this._inerted.push(child);
			}
		}
		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'); return; }
			if (e.key === 'Tab') this._trapTab(e);
		};
		document.addEventListener('keydown', this.onKey);
		requestAnimationFrame(() => {
			overlay.classList.add('x402-open');
			this._focusFirst();
		});
		return new Promise((resolve, reject) => {
			this.resolve = resolve;
			this.reject = reject;
		});
	}

	// All tabbable elements currently visible inside the modal.
	_focusable() {
		if (!this.modalEl) return [];
		return Array.from(
			this.modalEl.querySelectorAll(
				'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
			),
		).filter((el) => el.offsetParent !== null || el === document.activeElement);
	}

	// On open (and after re-renders the caller cares about) land focus on the
	// primary action — wallet/retry/pay button — rather than the ✕, so keyboard
	// users reach the thing they came to do first.
	_focusFirst() {
		if (!this.modalEl) return;
		const primary = this.modalEl.querySelector(
			'[data-agent-wallet]:not([disabled]), [data-wallet]:not([disabled]), [data-retry], .x402-pay-btn:not([disabled])',
		);
		(primary || this._focusable()[0] || this.modalEl).focus();
	}

	// Cycle Tab / Shift+Tab within the modal; pull stray focus back inside.
	_trapTab(e) {
		const f = this._focusable();
		if (!f.length) { e.preventDefault(); this.modalEl.focus(); return; }
		const first = f[0];
		const last = f[f.length - 1];
		const active = document.activeElement;
		const inside = this.modalEl.contains(active);
		if (e.shiftKey) {
			if (active === first || !inside) { e.preventDefault(); last.focus(); }
		} else if (active === last || !inside) {
			e.preventDefault();
			first.focus();
		}
	}

	close(reason) {
		if (this.disposed) return;
		this.disposed = true;
		document.removeEventListener('keydown', this.onKey);
		// Un-inert the rest of the page and restore focus to the trigger.
		if (this._inerted) {
			for (const el of this._inerted) {
				el.removeAttribute('inert');
				el.removeAttribute('aria-hidden');
			}
			this._inerted = null;
		}
		if (this.previouslyFocused && typeof this.previouslyFocused.focus === 'function') {
			try { this.previouslyFocused.focus(); } catch (_) { /* element gone — ignore */ }
		}
		this.overlay.classList.remove('x402-open');
		setTimeout(() => this.overlay.remove(), 180);
		if (reason === 'cancelled' && this.reject) {
			const err = new Error('cancelled');
			err.code = 'cancelled';
			this.reject(err);
		}
	}

	renderSteps(activeId, status = {}) {
		const html = this.steps
			.map((s) => {
				const state = status[s.id] || (s.id === activeId ? 'active' : 'idle');
				const cls = state === 'active' ? 'x402-active' : state === 'done' ? 'x402-done' : state === 'error' ? 'x402-error' : '';
				const meta = status[`${s.id}_meta`] || '';
				const sym = state === 'done' ? '✓' : state === 'error' ? '!' : s.id === activeId && state === 'active' ? ' ' : (this.steps.findIndex((x) => x.id === s.id) + 1);
				return `<div class="x402-step ${cls}">
					<div class="x402-step-num">${sym}</div>
					<div class="x402-step-body">
						<div class="x402-step-label">${s.label}</div>
						${meta ? `<div class="x402-step-meta">${escapeHtml(meta)}</div>` : ''}
					</div>
				</div>`;
			})
			.join('');
		return html;
	}

	// Buyer-facing charity / round-up opt-in. Default-checked; toggling updates
	// `this.includeDonation`, which runSolana reads when assembling the tx. The
	// donation rides the same signed transaction, so the buyer pays once.
	renderGivingBox(g) {
		const donation = formatAmount(g.amount, g.decimals);
		const total = formatAmount(g.total, g.decimals);
		const parts = [];
		if (g.charity !== '0') parts.push(`${formatAmount(g.charity, g.decimals)} ${g.sym} donation`);
		if (g.roundup !== '0') parts.push(`${formatAmount(g.roundup, g.decimals)} ${g.sym} round-up`);
		const detail = parts.join(' + ');
		return `
			<label class="x402-giving">
				<input type="checkbox" data-giving ${this.includeDonation ? 'checked' : ''} />
				<span class="x402-giving-box"></span>
				<span class="x402-giving-text">
					<span class="x402-giving-title">Add <span class="x402-giving-amt">${donation} ${g.sym}</span> for ${escapeHtml(g.name)}</span>
					<span class="x402-giving-sub">${detail ? escapeHtml(detail) + ' · ' : ''}you'd pay ${total} ${g.sym} total, settled in one transaction</span>
				</span>
			</label>
		`;
	}

	setPrice(accept) {
		const decimals = accept.extra?.decimals ?? 6;
		const amount = formatAmount(accept.amount, decimals);
		const sym = assetSymbol(accept);
		this.priceEl.innerHTML = `${amount}<span class="x402-currency"> ${escapeHtml(sym)}</span>`;
		this.networkEl.textContent = networkLabel(accept.network, accept);
	}

	/**
	 * The Solana accept the buyer is currently paying with: their explicit token
	 * choice when they made one, otherwise the first token the server advertised.
	 */
	pickedSolanaAccept() {
		// Derive lazily too: renderConnect is reachable from retry paths that may
		// not have gone through start() on this challenge object.
		if (!this.solanaAccepts) this.solanaAccepts = solanaAcceptsOf(this.challenge);
		const list = this.solanaAccepts;
		if (!list.length) return undefined;
		const picked = this.solanaAssetKey
			? list.find((a) => (a.asset || assetSymbol(a)) === this.solanaAssetKey)
			: null;
		return picked || list[0];
	}

	/**
	 * Token chooser for a resource priced in more than one Solana asset. Renders
	 * nothing for the single-token case, so the common checkout is unchanged.
	 */
	renderTokenChoice() {
		const list = this.solanaAccepts || [];
		if (list.length < 2) return '';
		const active = this.pickedSolanaAccept();
		const options = list.map((accept) => {
			const key = accept.asset || assetSymbol(accept);
			const sym = assetSymbol(accept);
			const amount = formatAmount(accept.amount, accept.extra?.decimals ?? 6);
			const on = accept === active;
			return `
				<button class="x402-token-btn" role="radio" aria-checked="${on ? 'true' : 'false'}"
					data-token="${escapeHtml(key)}" title="${escapeHtml(`Pay ${amount} ${sym}`)}">
					<span class="x402-token-sym">${escapeHtml(sym)}</span>
					<span class="x402-token-amt">${escapeHtml(amount)}</span>
				</button>
			`;
		}).join('');
		return `<div class="x402-token-choice" role="radiogroup" aria-label="Pay with">${options}</div>`;
	}

	renderConnect() {
		this.currentView = 'connect';
		const solanaProvider = detectSolanaProvider();
		const phantomDetected = !!solanaProvider;
		const evmDetected = typeof window !== 'undefined' && window.ethereum;
		const solanaAccept = this.pickedSolanaAccept();
		const evmAccept = this.challenge?.accepts.find(isEip3009Accept);
		// Keep the header price in step with the chosen token.
		if (solanaAccept) { this.accept = solanaAccept; this.setPrice(solanaAccept); }

		// Charity / round-up giving — only when the merchant configured it and the
		// cause wallet is reachable on this Solana checkout. Default-included, but
		// always rendered with an opt-out so the buyer consents before signing.
		this.solanaGiving = solanaAccept ? computeGiving(this.opts.giving, solanaAccept) : null;
		if (this.includeDonation === undefined) this.includeDonation = true;
		this.givingShown = false;

		// SIWX-first path: when the 402 advertises sign-in-with-x AND we have a
		// compatible wallet, lead with "Sign in with wallet" (primary) and
		// demote pay to a secondary action. payFlowOverride is set true when
		// the user explicitly chooses to pay (either by clicking the secondary
		// button, or after a 401/402 siwx_not_paid retry told us this wallet
		// hasn't actually paid for this resource yet).
		if (this.siwx && !this.payFlowOverride) {
			const siwxSolana = phantomDetected ? pickSiwxChain(this.siwx, 'solana') : null;
			const siwxEvm = evmDetected ? pickSiwxChain(this.siwx, 'evm') : null;
			if (siwxSolana || siwxEvm) {
				this.renderSiwxChoice({ siwxSolana, siwxEvm });
				return;
			}
		}

		// autoConnect (opt-in via opts.autoConnect): when the caller knows the
		// user is wallet-ready and shouldn't have to pick, skip the picker and go
		// straight to the signature — but only when exactly one supported wallet
		// is actually detected. Zero wallets (must install) or two (must choose)
		// still fall through to the picker, as does the SIWX "you haven't paid"
		// fallback, which needs to explain itself. One-shot via autoConnectTried.
		// A multi-token resource always shows the picker at least once: skipping
		// straight to the signature would silently commit the buyer to the first
		// advertised token and hide the fact that the other one is payable at all.
		// Once they pick, the choice is explicit and autoConnect is moot.
		const mustChooseToken = (this.solanaAccepts?.length || 0) > 1 && !this.solanaAssetKey;
		if (this.opts.autoConnect && !this.autoConnectTried && !this.siwxFallbackNotice && !mustChooseToken) {
			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; }
		}

		const buttons = [];
		if (solanaAccept) {
			buttons.push(`
				<button class="x402-wallet-btn" data-wallet="phantom" ${phantomDetected ? '' : 'disabled'}>
					<div class="x402-wallet-icon x402-phantom">${solanaProvider?.isThreeWs ? '3' : 'P'}</div>
					<span class="x402-wallet-name">${phantomDetected ? solanaWalletLabel(solanaProvider) : 'No Solana wallet detected'}</span>
					<span class="x402-wallet-meta">${escapeHtml(networkLabel(solanaAccept.network, solanaAccept))}</span>
				</button>
			`);
		}

		// Agent custodial wallets: server-signed, no popup. Offered only when the
		// Solana accept charges USDC, matching the server-side mint pin in
		// api/x402-pay (it refuses to sign any other SPL asset from an agent key).
		const agentButtons = [];
		const agentSym = solanaAccept ? assetSymbol(solanaAccept) : 'USDC';
		const hasAgents = Array.isArray(this.agentWallets) && this.agentWallets.length > 0;
		// Say WHY the agent wallets went away when the buyer switches to a token
		// they cannot sign, instead of letting the list silently disappear.
		const agentNote = hasAgents && solanaAccept && agentSym !== 'USDC'
			? `<div class="x402-trust">Your agent wallets pay in USDC only: switch to USDC to use them, or pay ${escapeHtml(agentSym)} from a browser wallet.</div>`
			: '';
		if (solanaAccept && agentSym === 'USDC' && hasAgents) {
			const decimals = Number(solanaAccept.extra?.decimals ?? 6);
			const priceUsdc = Number(solanaAccept.amount) / 10 ** decimals;
			for (const agent of this.agentWallets.slice(0, 4)) {
				const known = typeof agent.usdc === 'number';
				const short = known && agent.usdc < priceUsdc;
				agentButtons.push(`
					<button class="x402-wallet-btn" data-agent-wallet="${escapeHtml(agent.id)}" ${short ? 'disabled' : ''}>
						<div class="x402-wallet-icon x402-agent">${escapeHtml((agent.name || 'A').slice(0, 1).toUpperCase())}</div>
						<span class="x402-wallet-name">${escapeHtml(agent.name || 'Agent')}<span class="x402-wallet-sub">agent wallet · pays without a popup</span></span>
						<span class="x402-wallet-meta">${known ? `${agent.usdc.toFixed(2)} USDC${short ? ' · short' : ''}` : 'USDC'}</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">${escapeHtml(networkLabel(evmAccept.network, evmAccept))}</span>
				</button>
			`);
		}
		const fallbackBox = this.siwxFallbackNotice
			? `<div class="x402-siwx-fallback">${escapeHtml(this.siwxFallbackNotice)}</div>`
			: '';
		const givingBox = this.solanaGiving ? this.renderGivingBox(this.solanaGiving) : '';
		this.givingShown = !!this.solanaGiving;
		// Trust signal: show WHO the buyer is paying (on-chain recipient) before they
		// pick a wallet. The primary accept's payTo; link to the address explorer.
		const payeeAccept = this.accept || solanaAccept || evmAccept;
		const payTo = payeeAccept?.payTo;
		const payeeUrl = payTo ? addressExplorerUrl(payeeAccept.network, payTo) : null;
		const payeeShort = payTo ? `${payTo.slice(0, 6)}…${payTo.slice(-4)}` : '';
		const payeeBox = payTo
			? `<div class="x402-payee">Pays to ${
					payeeUrl
						? `<a class="x402-payee-addr" href="${payeeUrl}" target="_blank" rel="noopener" title="${escapeHtml(payTo)}">${escapeHtml(payeeShort)} ↗</a>`
						: `<span class="x402-payee-addr">${escapeHtml(payeeShort)}</span>`
				}</div>`
			: '';
		const walletList = agentButtons.length
			? `<div class="x402-wallet-group-label">Your agents</div>${agentButtons.join('')}` +
				(buttons.length ? `<div class="x402-wallet-group-label">Browser wallets</div>${buttons.join('')}` : '')
			: buttons.join('');
		const trustLine = agentButtons.length
			? 'Agent wallets pay from their own balance under your spend limits, with no popup. Browser wallets ask you to approve in the wallet. Settled on-chain either way.'
			: 'You approve the payment in your own wallet — funds move only when the service runs, settled on-chain.';
		this.bodyEl.innerHTML = `
			${this.renderSteps('connect', { discover: 'done' })}
			${payeeBox}
			${fallbackBox}
			${this.renderTokenChoice()}
			${givingBox}
			<div class="x402-wallet-buttons">${walletList}</div>
			${agentNote}
			<div class="x402-trust">${trustLine}</div>
		`;
		const giveEl = this.bodyEl.querySelector('[data-giving]');
		if (giveEl) giveEl.addEventListener('change', (e) => { this.includeDonation = !!e.target.checked; });
		// Token chooser: re-render so the price row, the giving box (its round-up
		// is denominated in the paying asset) and the agent-wallet list all follow
		// the newly chosen token.
		this.bodyEl.querySelectorAll('[data-token]').forEach((b) => {
			b.addEventListener('click', () => {
				const key = b.dataset.token;
				if (this.solanaAssetKey === key) return;
				this.solanaAssetKey = key;
				this.renderConnect();
				// Keep focus on the token the buyer just chose. Matched by walking
				// the fresh buttons rather than by selector: a mint is caller-shaped
				// text, so building a selector out of it needs escaping the modal
				// should not depend on.
				const again = [...this.bodyEl.querySelectorAll('[data-token]')]
					.find((el) => el.dataset.token === key);
				try { again?.focus(); } catch { /* focus is best-effort */ }
			});
		});
		const onClick = (e) => {
			const btn = e.target.closest('[data-wallet]');
			if (!btn || btn.disabled) return;
			const wallet = btn.dataset.wallet;
			if (wallet === 'phantom') this.runSolana(solanaAccept);
			else if (wallet === 'evm') this.runEvm(evmAccept);
		};
		this.bodyEl.querySelectorAll('[data-wallet]').forEach((b) => b.addEventListener('click', onClick));
		const onAgentClick = (e) => {
			const btn = e.target.closest('[data-agent-wallet]');
			if (!btn || btn.disabled) return;
			const agent = (this.agentWallets || []).find((a) => String(a.id) === btn.dataset.agentWallet);
			if (agent) this.runAgentWallet(solanaAccept, agent);
		};
		this.bodyEl.querySelectorAll('[data-agent-wallet]').forEach((b) => b.addEventListener('click', onAgentClick));
	}

	renderSiwxChoice({ siwxSolana, siwxEvm }) {
		this.currentView = 'siwx';
		const priceText = formatAmount(this.accept.amount, this.accept.extra?.decimals ?? 6);
		// One primary button — internally we pick the wallet kind that matches
		// the supported SIWX chains AND the detected wallets. Phantom wins ties
		// to match the existing modal's default preference.
		const siwxTarget = siwxSolana
			? { kind: 'solana', chain: siwxSolana.chain }
			: { kind: 'evm', chain: siwxEvm.chain };
		const siwxLabel = siwxTarget.kind === 'solana'
			? `Sign in with ${solanaWalletLabel(detectSolanaProvider())}`
			: 'Sign in with wallet';
		this.bodyEl.innerHTML = `
			${this.renderSteps('connect', { discover: 'done' })}
			<button class="x402-pay-btn" data-action="siwx">${siwxLabel}</button>
			<button class="x402-pay-secondary" data-action="pay">Pay ${priceText} ${escapeHtml(assetSymbol(this.accept))} instead</button>
			<div class="x402-siwx-hint">Already paid for this once? Sign in to re-enter without paying again.</div>
		`;
		const siwxBtn = this.bodyEl.querySelector('[data-action="siwx"]');
		const payBtn = this.bodyEl.querySelector('[data-action="pay"]');
		siwxBtn.addEventListener('click', () => {
			if (siwxTarget.kind === 'solana') this.runSiwxSolana(siwxTarget.chain);
			else this.runSiwxEvm(siwxTarget.chain);
		});
		payBtn.addEventListener('click', () => {
			this.payFlowOverride = true;
			this.renderConnect();
		});
		// Focus the primary SIWX button for keyboard accessibility.
		requestAnimationFrame(() => siwxBtn.focus());
	}

	renderProgress(activeId, meta = {}) {
		this.currentView = 'progress';
		this.bodyEl.innerHTML = this.renderSteps(activeId, {
			discover: 'done',
			connect: 'done',
			...(activeId === 'verify' ? { authorize: 'done' } : {}),
			[`${activeId}_meta`]: meta.text || '',
			...meta.statuses,
		});
	}

	// `retryable: false` is for failures the same click cannot change, such as a
	// service that refuses browser requests outright. Offering "Try again" there
	// reads as "this nearly worked" and sends the buyer round a loop that has no
	// exit, so the button is left out instead.
	renderError(stepId, message, { retryable = true } = {}) {
		this.currentView = 'error';
		this.bodyEl.innerHTML = `
			${this.renderSteps(stepId, {
				...(stepId !== 'discover' ? { discover: 'done' } : {}),
				...(stepId === 'authorize' || stepId === 'verify' ? { connect: 'done' } : {}),
				...(stepId === 'verify' ? { authorize: 'done' } : {}),
				[stepId]: 'error',
				[`${stepId}_meta`]: 'failed',
			})}
			<div class="x402-error-box"><strong>${escapeHtml(stepId)}:</strong> ${escapeHtml(message)}</div>
			${retryable ? '<button class="x402-pay-btn" data-retry>Try again</button>' : ''}
		`;
		this.bodyEl.querySelector('[data-retry]')?.addEventListener('click', () => this.start());
	}

	// Dedicated, actionable state for the most common payment failure: the wallet
	// can't cover the price. Shows needed / balance / shortfall, the connected
	// wallet (copy + explorer), and a retry that re-runs once the buyer tops up.
	renderInsufficientFunds(info) {
		this.currentView = 'insufficient';
		const addr = info.owner || '';
		const addrShort = addr ? `${addr.slice(0, 6)}…${addr.slice(-4)}` : '—';
		const viewUrl = addressExplorerUrl(info.network, addr);
		const netLabel = networkLabel(info.network);
		const sym = escapeHtml(info.symbol);
		this.bodyEl.innerHTML = `
			${this.renderSteps('authorize', {
				discover: 'done',
				connect: 'done',
				authorize: 'error',
				authorize_meta: 'insufficient funds',
			})}
			<div class="x402-insuff-title">Not enough ${sym}</div>
			<div class="x402-insuff-sub">Add ${sym} to your wallet on ${escapeHtml(netLabel)}, then try again — nothing was charged.</div>
			<div class="x402-receipt" style="margin-top:12px">
				<div class="x402-receipt-row"><span class="x402-k">needed</span><span class="x402-v">${escapeHtml(info.required)} ${sym}</span></div>
				<div class="x402-receipt-row"><span class="x402-k">your balance</span><span class="x402-v">${escapeHtml(info.balance)} ${sym}</span></div>
				<div class="x402-receipt-row"><span class="x402-k">short by</span><span class="x402-v" style="color:#e5484d;font-weight:700">${escapeHtml(info.shortfall)} ${sym}</span></div>
				<div class="x402-receipt-row"><span class="x402-k">wallet</span><span class="x402-v">${escapeHtml(addrShort)}</span></div>
			</div>
			<div class="x402-insuff-actions">
				<button class="x402-mini-btn" data-copy type="button" aria-label="Copy wallet address">Copy address</button>
				${viewUrl ? `<a class="x402-mini-btn" href="${viewUrl}" target="_blank" rel="noopener">View wallet ↗</a>` : ''}
			</div>
			<button class="x402-pay-btn" data-retry style="margin-top:10px">I've added funds — try again</button>
		`;
		const copyBtn = this.bodyEl.querySelector('[data-copy]');
		if (copyBtn) {
			copyBtn.addEventListener('click', async () => {
				try {
					await navigator.clipboard.writeText(addr);
					copyBtn.textContent = 'Copied ✓';
					setTimeout(() => {
						copyBtn.textContent = 'Copy address';
					}, 1500);
				} catch (_) {
					/* clipboard blocked — non-fatal */
				}
			});
		}
		this.bodyEl.querySelector('[data-retry]').addEventListener('click', () => this.start());
	}

	renderDone({ result, payment, siwx }) {
		this.currentView = 'done';
		const resultStr = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
		let receiptHtml;
		if (siwx) {
			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-row">
						<span class="x402-k">network</span>
						<span class="x402-v">${escapeHtml(networkLabel(siwx.network) || siwx.network || '—')}</span>
					</div>
					<div class="x402-receipt-row">
						<span class="x402-k">wallet</span>
						<span class="x402-v">${escapeHtml(addrShort)}</span>
					</div>
					<div class="x402-receipt-row">
						<span class="x402-k">paid</span>
						<span class="x402-v">previously · re-entered free</span>
					</div>
				</div>
			`;
		} else {
			const explorer = explorerUrl(payment?.network, payment?.transaction);
			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-row">
						<span class="x402-k">network</span>
						<span class="x402-v">${escapeHtml(networkLabel(payment?.network) || '—')}</span>
					</div>
					<div class="x402-receipt-row">
						<span class="x402-k">payer</span>
						<span class="x402-v">${escapeHtml(payment?.payer ? `${payment.payer.slice(0, 8)}…${payment.payer.slice(-6)}` : '—')}</span>
					</div>
					${
						payment?.transaction
							? `<div class="x402-receipt-row"><span class="x402-k">tx</span><span class="x402-v">${
									explorer ? `<a href="${escapeHtml(explorer)}" target="_blank" rel="noopener">${escapeHtml(txShort)} ↗</a>` : escapeHtml(txShort)
								}</span></div>`
							: ''
					}
				</div>
			`;
		}
		this.bodyEl.innerHTML = `
			${receiptHtml}
			<div class="x402-result">${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);
		});
	}

	async start() {
		this.bodyEl.innerHTML = this.renderSteps('discover');
		try {
			const challenge = await discoverChallenge(this.opts);
			this.challenge = filterAcceptsByNetwork(challenge, this.opts.networks);
			this.siwx = extractSiwxExtension(challenge);
			this.payFlowOverride = false;
			this.siwxFallbackNotice = null;
			// Solana-first platform default: select the Solana accept by default
			// whenever one is offered, regardless of which wallet is detected —
			// renderConnect() still shows both wallet buttons (Solana listed
			// first), so EVM users simply click the EVM option. Falls back to the
			// first EIP-3009 EVM entry (skipping Permit2 siblings the modal can't
			// sign for), then the first accept.
			// A resource can price itself in several Solana tokens (USDC and
			// $THREE). Default to the first advertised one and let renderConnect
			// offer the rest through the token chooser.
			this.solanaAccepts = solanaAcceptsOf(challenge);
			this.solanaAssetKey = null;
			const solana = this.pickedSolanaAccept();
			const evm = challenge.accepts.find(isEip3009Accept);
			this.accept = solana || evm || challenge.accepts[0];
			this.setPrice(this.accept);
			// Agent wallets settle Solana USDC only (api/x402-pay pins the mint), so
			// only look them up when this checkout offers that rail. The fetch runs in
			// the background and injects the extra buttons into the picker when it
			// lands; the browser-wallet buttons never wait on it.
			if (solana) {
				if (this.agentWallets === undefined) this.agentWallets = null;
				fetchAgentWallets().then((list) => {
					if (this.disposed) return;
					this.agentWallets = Array.isArray(list) && list.length ? list : null;
					if (this.agentWallets && this.currentView === 'connect') this.renderConnect();
				});
			}
			this.renderConnect();
		} catch (err) {
			this.renderError('discover', err.message || String(err), { retryable: err?.code !== 'cors_blocked' });
		}
	}

	async runSolana(accept) {
		if (!(await ensureRiskAckSafe('x402-pay'))) { this.close('cancelled'); return; }
		this.accept = accept;
		this.setPrice(accept);
		const provider = detectSolanaProvider();
		const walletName = solanaWalletLabel(provider);
		this.renderProgress('connect', { text: `Opening ${walletName}…` });
		try {
			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(`${walletName} did not return a public key`);
			this.payerAddress = payerAddress;
			const capCheck = browserEnforceCap({
				accept,
				caps: this.opts.caps,
				address: payerAddress,
			});
			if (capCheck.abort) {
				this.renderError('authorize', capCheck.reason);
				return;
			}
			this.spendReservation = capCheck.reservation || null;
			this.renderProgress('authorize', { text: 'Checking your balance…' });
			await assertBalance({ accept, owner: payerAddress });
			this.renderProgress('authorize', { text: `Building Solana payment for ${payerAddress.slice(0, 6)}…${payerAddress.slice(-4)}` });

			// Only attach the donation when the buyer actually saw and kept the
			// opt-in (givingShown) — never silently in autoConnect mode.
			const tips =
				this.givingShown && this.includeDonation && this.solanaGiving
					? [{ to: this.solanaGiving.to, amount: this.solanaGiving.amount }]
					: undefined;
			const prep = await postJson(`${ORIGIN}/api/x402-checkout?action=prepare`, {
				accept,
				buyer: payerAddress,
				...(tips ? { tips } : {}),
			});
			// Normally three.ws sponsors the Solana fee, so the buyer's SOL is
			// untouched and the wallet popup is the whole story. When the sponsor
			// cannot cover it the endpoint hands back a self-pay transaction, and
			// the buyer's own SOL pays the fee. Say that before they approve rather
			// than letting a wallet popup be the first time they find out.
			this.renderProgress('authorize', {
				text: prep.self_pay
					? `Confirm in ${walletName}: you cover the network fee on this one`
					: `Confirm in ${walletName}…`,
			});
			const txBytes = base64ToUint8Array(prep.tx_base64);
			// The wallet returns a fully-signed VersionedTransaction with the buyer's
			// signature added. The facilitator's fee-payer signature is added by
			// PayAI during /settle.
			const SolanaWeb3 = await loadSolanaWeb3();
			// Wallets with auto priority fees or "transaction protection" (Phantom,
			// Solflare) rewrite a transaction before signing. The facilitator settles
			// a rewritten tx fine as long as the rewrite only touches ComputeBudget
			// instructions or the blockhash: it re-validates shape, recipient,
			// amount, and fee caps server-side on every settle. Anything else (guard
			// programs, a changed transfer, a swapped fee payer) it deterministically
			// rejects, so those become an immediate, named explanation here instead
			// of a silent 402-retry loop. Snapshot the message bytes before the
			// wallet touches the object (some wallets mutate in place); the deep
			// classification re-reads the prepared tx from the original bytes.
			const preparedMsg = SolanaWeb3.VersionedTransaction.deserialize(txBytes).message.serialize();
			const signed = await signPreparedSolanaTx({
				provider,
				address: payerAddress,
				network: accept.network,
				txBytes,
				SolanaWeb3,
			});
			const signedMsg = signed?.message?.serialize?.();
			if (signedMsg && !bytesEqual(preparedMsg, signedMsg)) {
				const prepared = SolanaWeb3.VersionedTransaction.deserialize(txBytes);
				const veto = classifyWalletTxMutation(prepared, signed);
				if (veto) {
					throw new Error(
						`${walletName} rewrote the payment transaction before signing (${veto}), so it can no longer settle. Nothing was sent or charged. Turn off transaction modification in the wallet settings, or pay with a different Solana wallet.`,
					);
				}
			}
			const signedB64 = uint8ArrayToBase64(signed.serialize());

			const builderCodeBlock = buildBuilderCodeEcho(this.challenge);
			const enc = await postJson(`${ORIGIN}/api/x402-checkout?action=encode`, {
				accept,
				signed_tx_base64: signedB64,
				resource_url: new URL(this.opts.endpoint, location.href).href,
				...(builderCodeBlock ? { builder_code: builderCodeBlock } : {}),
			});

			await this.executePaid(enc.x_payment);
		} catch (err) {
			if (this.spendReservation) {
				browserRollbackReservation(this.spendReservation);
				this.spendReservation = null;
			}
			if (err?.code === 'insufficient_funds') {
				this.renderInsufficientFunds(err.insufficient);
				return;
			}
			this.renderError(this.payerAddress ? 'authorize' : 'connect', friendlyError(err));
		}
	}

	// Pay from an agent's custodial wallet: the whole build/sign/settle happens
	// server-side in /api/x402-pay under the agent's spend policy, streamed back
	// as SSE so the step timeline stays live. No wallet popup at any point.
	async runAgentWallet(accept, agent) {
		if (!(await ensureRiskAckSafe('x402-pay'))) { this.close('cancelled'); return; }
		this.accept = accept;
		this.setPrice(accept);
		this.payerAddress = agent.solana_address;
		const agentName = agent.name || 'agent';
		const decimals = Number(accept.extra?.decimals ?? 6);
		const priceUsdc = Number(accept.amount) / 10 ** decimals;
		try {
			// Pre-flight shortfall guard from the balance the picker already loaded;
			// same UX contract as assertBalance, no extra RPC read. The server
			// re-checks everything authoritatively before signing.
			if (typeof agent.usdc === 'number' && agent.usdc < priceUsdc) {
				const err = new Error('insufficient funds');
				err.code = 'insufficient_funds';
				err.insufficient = {
					symbol: 'USDC',
					network: accept.network,
					owner: agent.solana_address,
					required: formatAmount(accept.amount, decimals),
					balance: agent.usdc.toFixed(2),
					shortfall: (priceUsdc - agent.usdc).toFixed(2),
				};
				throw err;
			}
			this.renderProgress('connect', { text: `Using ${agentName}'s wallet…` });
			const csrfToken = await fetchCsrfToken();
			if (!csrfToken) {
				throw new Error('Your three.ws session has expired. Sign in again to pay from an agent wallet.');
			}
			this.renderProgress('authorize', { text: `Paying ${formatAmount(accept.amount, decimals)} USDC from ${agentName}'s wallet…` });
			const final = await payFromAgentWallet(
				{
					agentId: agent.id,
					url: new URL(this.opts.endpoint, location.href).href,
					method: this.opts.method || 'GET',
					body: this.opts.body,
					serviceLabel: this.opts.merchant || null,
					csrfToken,
				},
				(event, data) => {
					if (this.disposed) return;
					if (event === 'built') {
						this.renderProgress('authorize', { text: 'Payment signed by the agent wallet…' });
					} else if (event === 'settled') {
						this.renderProgress('verify', {
							text: data?.tx ? `Settled on-chain · ${String(data.tx).slice(0, 8)}…` : 'Settling on-chain…',
						});
					}
				},
			);
			_agentWalletsCache = null; // the balance just changed; the next picker rereads it
			const payment = {
				transaction: final?.payment?.tx || null,
				network: final?.payment?.network || accept.network,
				payer: final?.payment?.payer || agent.solana_address,
			};
			this.resolve?.({
				ok: true,
				result: final?.result,
				payment,
				agent: { id: agent.id, name: agent.name || null },
				response: { status: 200, headers: {} },
			});
			if (this.opts.autoClose) this.close('done');
			else this.renderDone({ result: final?.result, payment });
		} catch (err) {
			if (err?.code === 'insufficient_funds') {
				this.renderInsufficientFunds(err.insufficient);
				return;
			}
			// Spend-policy refusals arrive with the server's own explanation
			// (daily cap, per-call cap, frozen wallet): surface them verbatim.
			this.renderError('authorize', friendlyError(err));
		}
	}

	async runEvm(accept) {
		if (!(await ensureRiskAckSafe('x402-pay'))) { this.close('cancelled'); return; }
		this.accept = accept;
		this.setPrice(accept);
		this.renderProgress('connect', { text: 'Opening browser wallet…' });
		try {
			const eth = window.ethereum;
			if (!eth) throw new Error('No EVM wallet detected');
			const accounts = await eth.request({ method: 'eth_requestAccounts' });
			const payerAddress = accounts?.[0];
			if (!payerAddress) throw new Error('Wallet did not return an account');
			this.payerAddress = payerAddress;
			const capCheck = browserEnforceCap({
				accept,
				caps: this.opts.caps,
				address: payerAddress,
			});
			if (capCheck.abort) {
				this.renderError('authorize', capCheck.reason);
				return;
			}
			this.spendReservation = capCheck.reservation || null;

			const meta = EVM_NETWORKS[accept.network];
			if (!meta) throw new Error(`Unknown EVM network ${accept.network}`);
			// Switch chain if needed.
			const currentChainHex = await eth.request({ method: 'eth_chainId' });
			const desiredChainHex = '0x' + meta.chainId.toString(16);
			if (currentChainHex !== desiredChainHex) {
				this.renderProgress('connect', { text: `Switch wallet to ${meta.name}…` });
				try {
					await eth.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: desiredChainHex }] });
				} catch (e) {
					throw new Error(`Wallet is on ${currentChainHex}; please switch to ${meta.name} (${desiredChainHex}) and retry`);
				}
			}

			this.renderProgress('authorize', { text: 'Checking your balance…' });
			await assertBalance({ accept, owner: payerAddress, provider: eth });
			this.renderProgress('authorize', { text: `Authorize ${formatAmount(accept.amount)} USDC…` });

			// EIP-3009 transferWithAuthorization typed-data signature.
			// validAfter / validBefore use unix seconds; nonce is a random 32-byte hex.
			const validAfter = 0;
			const validBefore = Math.floor(Date.now() / 1000) + (accept.maxTimeoutSeconds || 600);
			const nonce = '0x' + randomHex(32);
			const domain = {
				name: accept.extra?.name || 'USD Coin',
				version: accept.extra?.version || '2',
				chainId: meta.chainId,
				verifyingContract: accept.asset,
			};
			const types = {
				EIP712Domain: [
					{ name: 'name', type: 'string' },
					{ name: 'version', type: 'string' },
					{ name: 'chainId', type: 'uint256' },
					{ name: 'verifyingContract', type: 'address' },
				],
				TransferWithAuthorization: [
					{ name: 'from', type: 'address' },
					{ name: 'to', type: 'address' },
					{ name: 'value', type: 'uint256' },
					{ name: 'validAfter', type: 'uint256' },
					{ name: 'validBefore', type: 'uint256' },
					{ name: 'nonce', type: 'bytes32' },
				],
			};
			const message = {
				from: payerAddress,
				to: accept.payTo,
				value: accept.amount,
				validAfter,
				validBefore,
				nonce,
			};
			const typedData = {
				primaryType: 'TransferWithAuthorization',
				types,
				domain,
				message,
			};
			const signature = await eth.request({
				method: 'eth_signTypedData_v4',
				params: [payerAddress, JSON.stringify(typedData)],
			});

			const paymentPayload = {
				x402Version: 2,
				scheme: 'exact',
				network: accept.network,
				resource: { url: this.opts.endpoint, mimeType: 'application/json' },
				accepted: accept,
				payload: {
					signature,
					// CDP facilitator /verify requires the EIP-3009 time bounds as
					// decimal strings, not JSON numbers — a numeric validAfter/
					// validBefore is rejected with "'paymentPayload' is invalid".
					// The signature is unaffected: uint256 0 and "0" encode identically.
					authorization: { from: payerAddress, to: accept.payTo, value: accept.amount, validAfter: String(validAfter), validBefore: String(validBefore), nonce },
				},
			};
			const builderCodeBlock = buildBuilderCodeEcho(this.challenge);
			if (builderCodeBlock) {
				paymentPayload.extensions = { 'builder-code': builderCodeBlock };
			}
			const xPayment = b64encode(paymentPayload);
			await this.executePaid(xPayment);
		} catch (err) {
			if (this.spendReservation) {
				browserRollbackReservation(this.spendReservation);
				this.spendReservation = null;
			}
			if (err?.code === 'insufficient_funds') {
				this.renderInsufficientFunds(err.insufficient);
				return;
			}
			this.renderError(this.payerAddress ? 'authorize' : 'connect', friendlyError(err));
		}
	}

	async executePaid(xPayment, attempt = 0) {
		this.renderProgress('verify', {
			text: attempt ? 'Retrying after upstream throttle…' : 'Calling merchant endpoint…',
		});
		try {
			const res = await fetch(this.opts.endpoint, {
				method: this.opts.method || 'GET',
				headers: {
					...(this.opts.headers || {}),
					...(this.opts.body && !this.opts.headers?.['content-type'] ? { 'content-type': 'application/json' } : {}),
					'X-PAYMENT': xPayment,
				},
				body: this.opts.body ? (typeof this.opts.body === 'string' ? this.opts.body : JSON.stringify(this.opts.body)) : undefined,
			});
			const ct = res.headers.get('content-type') || '';
			const text = await res.text();
			let result;
			if (ct.includes('json')) {
				try {
					result = JSON.parse(text);
				} catch {
					result = text;
				}
			} else {
				result = text;
			}
			if (!res.ok) {
				// A 429 here is a transient upstream throttle (e.g. the generator's
				// create-prediction rate limit). The payment is signed but NOT yet
				// settled — the merchant runs the work before settling — so the same
				// X-PAYMENT can be safely re-sent once the window resets, with no risk
				// of a double charge. Auto-retry a couple of times, respecting the
				// server's Retry-After, before surfacing the manual "Try again".
				if (res.status === 429 && attempt < MAX_THROTTLE_RETRIES) {
					await this.waitForThrottle(retryAfterSeconds(res, result));
					return this.executePaid(xPayment, attempt + 1);
				}
				const msg = (result && typeof result === 'object' && (result.error_description || result.error)) || `HTTP ${res.status}`;
				throw new Error(msg);
			}
			const settleHeader = res.headers.get('x-payment-response');
			const payment = b64decode(settleHeader) || {};
			this.spendReservation = null;
			this.resolve?.({ ok: true, result, payment, response: { status: res.status, headers: headersToObject(res.headers) } });
			// autoClose (opt-in): a programmatic caller (e.g. the club door) renders
			// its own success beat over the unlocked content, so the modal must get
			// out of the way the instant payment settles instead of parking on a
			// manual "Done" screen that would cover what the caller just revealed.
			if (this.opts.autoClose) this.close('done');
			else this.renderDone({ result, payment });
		} catch (err) {
			if (this.spendReservation) {
				browserRollbackReservation(this.spendReservation);
				this.spendReservation = null;
			}
			this.renderError('verify', friendlyError(err));
		}
	}

	// Hold the verify step on a live countdown while an upstream throttle resets,
	// then return so the caller re-sends the same signed payment. The reservation
	// is deliberately left intact — this is the same payment, not a new one — so
	// no rollback runs between attempts.
	async waitForThrottle(seconds) {
		const total = Math.max(1, Math.min(30, Math.round(seconds) || 6));
		for (let left = total; left > 0; left--) {
			this.renderProgress('verify', { text: `Generator is busy — retrying in ${left}s…` });
			await new Promise((r) => setTimeout(r, 1000));
		}
		this.renderProgress('verify', { text: 'Retrying…' });
	}

	async runSiwxEvm(chain) {
		this.renderProgress('connect', { text: 'Opening browser wallet…' });
		try {
			const eth = window.ethereum;
			if (!eth) throw new Error('No EVM wallet detected');
			const accounts = await eth.request({ method: 'eth_requestAccounts' });
			const rawAddress = accounts?.[0];
			if (!rawAddress) throw new Error('Wallet did not return an account');
			const checksum = await loadEvmChecksum();
			const address = checksum(rawAddress);
			this.payerAddress = address;
			this.renderProgress('authorize', { text: `Sign sign-in message as ${address.slice(0, 6)}…${address.slice(-4)}` });

			const message = buildSiwxMessage(this.siwx.info, chain, address);
			const signature = await eth.request({
				method: 'personal_sign',
				params: [message, address],
			});

			const info = this.siwx.info;
			const payload = {
				domain: info.domain,
				address,
				...(info.statement ? { statement: info.statement } : {}),
				uri: info.uri,
				version: info.version || '1',
				chainId: chain.chainId,
				type: 'eip191',
				nonce: info.nonce,
				issuedAt: info.issuedAt,
				...(info.expirationTime ? { expirationTime: info.expirationTime } : {}),
				...(info.notBefore ? { notBefore: info.notBefore } : {}),
				...(info.requestId !== undefined && info.requestId !== null ? { requestId: info.requestId } : {}),
				...(Array.isArray(info.resources) ? { resources: info.resources } : {}),
				signatureScheme: 'eip191',
				signature,
			};
			await this.executeSiwx(payload, chain.chainId);
		} catch (err) {
			this.renderError(this.payerAddress ? 'authorize' : 'connect', friendlyError(err));
		}
	}

	async runSiwxSolana(chain) {
		const provider = detectSolanaProvider();
		const walletName = solanaWalletLabel(provider);
		this.renderProgress('connect', { text: `Opening ${walletName}…` });
		try {
			if (!provider) throw new Error('No Solana wallet detected');
			const conn = await provider.connect();
			const pubkey = conn?.publicKey || provider.publicKey;
			const address = pubkey?.toString();
			if (!address) throw new Error(`${walletName} did not return a public key`);
			this.payerAddress = address;
			this.renderProgress('authorize', { text: `Sign sign-in message as ${address.slice(0, 6)}…${address.slice(-4)}` });

			const message = buildSiwxMessage(this.siwx.info, chain, address);
			const encoded = new TextEncoder().encode(message);
			const signed = await provider.signMessage(encoded, 'utf8');
			const sigBytes = signed?.signature instanceof Uint8Array ? signed.signature : new Uint8Array(signed?.signature || signed);
			if (!sigBytes || !sigBytes.length) throw new Error(`${walletName} did not return a signature`);
			const signature = base58encode(sigBytes);

			const info = this.siwx.info;
			const payload = {
				domain: info.domain,
				address,
				...(info.statement ? { statement: info.statement } : {}),
				uri: info.uri,
				version: info.version || '1',
				chainId: chain.chainId,
				type: 'ed25519',
				nonce: info.nonce,
				issuedAt: info.issuedAt,
				...(info.expirationTime ? { expirationTime: info.expirationTime } : {}),
				...(info.notBefore ? { notBefore: info.notBefore } : {}),
				...(info.requestId !== undefined && info.requestId !== null ? { requestId: info.requestId } : {}),
				...(Array.isArray(info.resources) ? { resources: info.resources } : {}),
				signatureScheme: 'siws',
				signature,
			};
			await this.executeSiwx(payload, chain.chainId);
		} catch (err) {
			this.renderError(this.payerAddress ? 'authorize' : 'connect', friendlyError(err));
		}
	}

	async executeSiwx(payload, chainId) {
		this.renderProgress('verify', { text: 'Verifying sign-in…' });
		const headerValue = encodeSiwxHeaderValue(payload);
		let res;
		try {
			res = await fetch(this.opts.endpoint, {
				method: this.opts.method || 'GET',
				headers: {
					...(this.opts.headers || {}),
					...(this.opts.body && !this.opts.headers?.['content-type'] ? { 'content-type': 'application/json' } : {}),
					[SIWX_HEADER]: headerValue,
				},
				body: this.opts.body ? (typeof this.opts.body === 'string' ? this.opts.body : JSON.stringify(this.opts.body)) : undefined,
			});
		} catch (err) {
			this.renderError('verify', friendlyError(err));
			return;
		}

		if (res.status === 200) {
			const ct = res.headers.get('content-type') || '';
			const text = await res.text();
			let result;
			if (ct.includes('json')) {
				try { result = JSON.parse(text); } catch { result = text; }
			} else {
				result = text;
			}
			const siwx = { address: payload.address, network: chainId };
			this.resolve?.({
				ok: true,
				result,
				siwx,
				response: { status: res.status, headers: headersToObject(res.headers) },
			});
			// See the paid path: a programmatic caller dismisses the modal itself.
			if (this.opts.autoClose) this.close('done');
			else this.renderDone({ result, siwx });
			return;
		}

		if (res.status === 401 || res.status === 402) {
			// Most likely: signature verified but this wallet hasn't actually
			// paid for the resource yet. Drop the SIWX offering and fall back
			// to the normal payment flow with a one-line notice.
			let parsed = null;
			try { parsed = await res.clone().json(); } catch (_) {}
			const code = parsed?.code || parsed?.error;
			this.siwx = null;
			this.payerAddress = null;
			this.payFlowOverride = false;
			this.siwxFallbackNotice = code === 'siwx_not_paid' || res.status === 402
				? "You haven't paid for this yet — pay now to unlock re-entry."
				: 'Sign-in not accepted — please pay to continue.';
			// Re-render the wallet picker. If we had collected the 402 challenge
			// already, this just re-runs renderConnect; otherwise we re-discover.
			if (!this.challenge || !Array.isArray(this.challenge.accepts) || !this.challenge.accepts.length) {
				this.start();
			} else {
				this.renderConnect();
			}
			return;
		}

		const text = await res.text().catch(() => '');
		this.renderError('verify', `SIWX retry failed: HTTP ${res.status}${text ? ` · ${text.slice(0, 120)}` : ''}`);
	}
}

// ───────────────────────────────────────────────────────── helpers ──────────

function escapeHtml(s) {
	return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
}

function headersToObject(headers) {
	const out = {};
	headers.forEach((v, k) => (out[k] = v));
	return out;
}

// How many times executePaid silently re-sends a signed payment after a 429
// throttle before falling back to the manual "Try again". The payment isn't
// settled until the merchant call succeeds, so re-sending can't double-charge.
const MAX_THROTTLE_RETRIES = 2;

// Seconds to wait before re-sending after a 429. Prefers the standard
// Retry-After header, then the body's `retry_after` hint, then a sane default.
function retryAfterSeconds(res, result, fallback = 6) {
	const header = Number.parseInt(res.headers.get('retry-after') || '', 10);
	if (Number.isFinite(header) && header > 0) return header;
	const body = result && typeof result === 'object' ? Number(result.retry_after) : NaN;
	if (Number.isFinite(body) && body > 0) return body;
	return fallback;
}

function friendlyError(err) {
	const msg = err?.shortMessage || err?.message || String(err);
	// Trim ethers/viem long stacks, Phantom's RPC-error verbosity.
	// Only a wallet's own refusal counts as a cancel: EIP-1193 code 4001, ethers'
	// ACTION_REJECTED, or the phrasing wallets use for it. A bare /reject/ also
	// matched the merchant's "payment rejected: <reason>", so a server-side verify
	// failure was shown as the buyer cancelling a transaction they had just signed.
	if (
		err?.code === 4001 ||
		err?.code === 'ACTION_REJECTED' ||
		/user (rejected|denied|cancell?ed|declined)|(rejected|denied|cancell?ed) by (the )?user|^(transaction|request|signature) (was )?(rejected|declined|cancell?ed)/i.test(msg)
	) {
		return 'cancelled in wallet';
	}
	// Some wallets refuse to open their approval window at all and answer with
	// their own wording ("The app's signature request cannot be shown due to
	// invalid formatting"). Shown raw it reads as a fault in the buyer's payment.
	// Nothing was signed, so nothing was charged: say that, and what to try.
	if (/signature request cannot be shown|cannot be (shown|displayed) due to/i.test(msg)) {
		return 'Your wallet could not display this payment request, so nothing was signed or charged. Unlock or update the wallet and retry, or pay with the other token.';
	}
	// Upstream throttles (e.g. a generator's create-prediction rate limit) often
	// arrive as raw provider text that names the merchant's internal billing or
	// credit state. Never relay that to the buyer: the payment isn't settled until
	// the merchant call succeeds, so a clean, retryable message is both safer and
	// more accurate than echoing the upstream's account internals.
	if (/throttl|rate.?limit|too many requests|less than \$|in credit|\b429\b/i.test(msg)) {
		return 'The service is briefly busy and your payment was not taken — retry in a few seconds.';
	}
	// The Solana and EVM-sign-in paths dynamic-import a library from a CDN, now
	// across three mirrors. All three failing means a strict host Content-Security-
	// Policy is blocking them (one unreachable CDN no longer gets this far), and
	// the raw "Failed to fetch dynamically imported module" is opaque. The
	// Base/EIP-3009 payment path has no such dependency, so steer the buyer there.
	if (/dynamically imported module|esm\.sh|jsdelivr|unpkg|module script failed|module_unavailable/i.test(msg)) {
		return 'A component this wallet path needs (loaded from a CDN) was blocked, usually by a strict host security policy. Pay with MetaMask on Base instead; it needs no third-party code.';
	}
	return msg.slice(0, 240);
}

function base64ToUint8Array(b64) {
	if (typeof Buffer !== 'undefined') return new Uint8Array(Buffer.from(b64, 'base64'));
	const bin = atob(b64);
	const arr = new Uint8Array(bin.length);
	for (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i);
	return arr;
}
function uint8ArrayToBase64(arr) {
	if (typeof Buffer !== 'undefined') return Buffer.from(arr).toString('base64');
	let bin = '';
	for (let i = 0; i < arr.length; i++) bin += String.fromCharCode(arr[i]);
	return btoa(bin);
}
function bytesEqual(a, b) {
	if (a.length !== b.length) return false;
	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
	return true;
}

// Wallet-rewrite classifier for the Solana checkout. The self-hosted
// facilitator's validateRingTransaction in api/_lib/x402/self-facilitator.js
// accepts any ComputeBudget instruction set within its fee caps and never pins
// the blockhash to what /prepare issued, so a wallet that only injects or
// retunes priority-fee instructions (Phantom and Solflare both do) still
// produces a settleable payment. It also accepts Lighthouse guard instructions,
// the balance assertions Phantom's transaction protection injects by default,
// up to a small ceiling and only while they leave a sponsoring fee payer alone.
// What it hard-rejects is any other change: other foreign programs, a modified
// transfer, or a swapped fee payer. Mirror exactly that line here.
const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
const LIGHTHOUSE_PROGRAM = 'L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95';
const MAX_LIGHTHOUSE_INSTRUCTIONS = 3;

// Resolve a v0 message's instructions to index-independent form so the
// comparison survives the wallet reordering or appending account keys.
function resolveNonBudgetInstructions(message) {
	const keys = message.staticAccountKeys.map((k) => k.toBase58());
	return message.compiledInstructions
		.map((ix) => ({
			program: keys[ix.programIdIndex],
			accounts: ix.accountKeyIndexes.map((i) => keys[i]),
			data: ix.data,
		}))
		.filter((ix) => ix.program !== COMPUTE_BUDGET_PROGRAM);
}

// Why the facilitator would refuse the wallet's guard instructions, or null when
// it accepts them. A second required signature means a sponsor pays the fee, and
// a guard that names the sponsor's account could charge it.
function guardInstructionVeto(message, guardIxs) {
	if (guardIxs.length > MAX_LIGHTHOUSE_INSTRUCTIONS) {
		return `it added ${guardIxs.length} guard instructions, more than a payment may carry`;
	}
	const sponsored = message.header.numRequiredSignatures > 1;
	const feePayer = message.staticAccountKeys[0]?.toBase58();
	if (sponsored && guardIxs.some((ix) => ix.accounts.includes(feePayer))) {
		return 'it added a guard instruction that touches the fee sponsor account';
	}
	return null;
}

// Decide whether a wallet's pre-signing rewrite of the prepared transaction is
// benign (ComputeBudget/blockhash only → returns null, proceed to settle) or
// blocking (returns a short human-readable reason for the checkout error).
// Never throws on an odd wallet-returned object: unverifiable means blocking,
// since the facilitator would reject what we cannot vouch for.
export function classifyWalletTxMutation(preparedTx, signedTx) {
	try {
		const prepared = preparedTx.message;
		const signed = signedTx.message;
		const preparedFeePayer = prepared.staticAccountKeys[0]?.toBase58();
		const signedFeePayer = signed.staticAccountKeys[0]?.toBase58();
		if (preparedFeePayer !== signedFeePayer) {
			return 'it changed the transaction fee payer';
		}
		const preparedIxs = resolveNonBudgetInstructions(prepared);
		const signedAll = resolveNonBudgetInstructions(signed);
		const guardVeto = guardInstructionVeto(
			signed,
			signedAll.filter((ix) => ix.program === LIGHTHOUSE_PROGRAM),
		);
		if (guardVeto) return guardVeto;
		const signedIxs = signedAll.filter((ix) => ix.program !== LIGHTHOUSE_PROGRAM);
		if (signedIxs.length !== preparedIxs.length) {
			const preparedPrograms = new Set(preparedIxs.map((ix) => ix.program));
			const added = signedIxs.find((ix) => !preparedPrograms.has(ix.program));
			return added
				? `it injected instructions from program ${added.program}`
				: 'it added or removed payment instructions';
		}
		for (let i = 0; i < preparedIxs.length; i++) {
			const a = preparedIxs[i];
			const b = signedIxs[i];
			if (
				a.program !== b.program ||
				a.accounts.length !== b.accounts.length ||
				a.accounts.some((key, j) => key !== b.accounts[j]) ||
				!bytesEqual(a.data, b.data)
			) {
				return 'it changed the payment instructions';
			}
		}
		return null;
	} catch {
		return 'the rewrite could not be verified';
	}
}
function randomHex(bytes) {
	const arr = new Uint8Array(bytes);
	crypto.getRandomValues(arr);
	return Array.from(arr).map((b) => b.toString(16).padStart(2, '0')).join('');
}

let _solanaWeb3 = null;
async function loadSolanaWeb3() {
	if (_solanaWeb3) return _solanaWeb3;
	// Dynamic import keeps the drop-in script tiny: Solana web3.js is only
	// fetched when a Solana payment is actually attempted. The shared loader
	// tries esm.sh, then jsdelivr and unpkg for the same version, each under a
	// deadline, so a single blocked CDN can no longer take the paywall down.
	const { loadModule } = await import('./load-module.js');
	try {
		_solanaWeb3 = await loadModule('https://esm.sh/@solana/[email protected]?bundle');
	} catch (err) {
		if (err?.code === 'module_unavailable') {
			throw new Error(
				'The Solana wallet component could not be loaded (' + err.hosts.join(', ') + ' unreachable or blocked by this page\'s security policy). Pay with a Base wallet instead; that path needs no third-party code.',
			);
		}
		throw err;
	}
	return _solanaWeb3;
}

// Wallet Standard chain id for a CAIP-2 Solana network.
const SOLANA_DEVNET_GENESIS = 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
function walletStandardChain(network) {
	return String(network || '').includes(SOLANA_DEVNET_GENESIS) ? 'solana:devnet' : 'solana:mainnet';
}

// The Wallet Standard account that owns the connected address and can sign a
// v0 transaction from raw bytes, or null. The registry library is small and
// only fetched on a Solana checkout; a wallet that registers nothing (the
// Seeker MWA bridge) or a blocked CDN simply means the injected provider signs.
async function findStandardSigner(address) {
	try {
		const { loadModule } = await import('./load-module.js');
		const { getWallets } = await loadModule('https://esm.sh/@wallet-standard/[email protected]?bundle');
		for (const wallet of getWallets().get()) {
			const feature = wallet?.features?.['solana:signTransaction'];
			const versions = feature?.supportedTransactionVersions;
			if (!feature?.signTransaction || (versions && !versions.includes(0))) continue;
			const account = wallet.accounts?.find((a) => a.address === address);
			if (account) return { feature, account };
		}
	} catch {
		return null;
	}
	return null;
}

function isWalletRefusal(err) {
	return friendlyError(err) === 'cancelled in wallet';
}

// Have the buyer's wallet sign the prepared payment transaction.
//
// Phantom refused the club cover with "The app's signature request cannot be
// shown due to invalid formatting" even though the prepared bytes decode as a
// well-formed v0 transferChecked. The legacy provider.signTransaction(tx) hands
// the wallet a VersionedTransaction built by our CDN copy of web3.js, which the
// wallet re-serializes through its own; the Wallet Standard feature takes the
// exact bytes /prepare built, so nothing is lost in that handoff. It goes first,
// and the injected provider is the fallback for wallets without the standard or
// when the standard path fails for any reason other than the buyer declining.
export async function signPreparedSolanaTx({ provider, address, network, txBytes, SolanaWeb3 }) {
	const standard = provider?.isThreeWs ? null : await findStandardSigner(address);
	if (standard) {
		try {
			const [result] = await standard.feature.signTransaction({
				account: standard.account,
				transaction: txBytes,
				chain: walletStandardChain(network),
			});
			if (result?.signedTransaction) {
				return SolanaWeb3.VersionedTransaction.deserialize(result.signedTransaction);
			}
		} catch (err) {
			if (isWalletRefusal(err)) throw err;
			console.warn('[x402] Wallet Standard signing failed, retrying through the injected provider', err);
		}
	}
	return provider.signTransaction(SolanaWeb3.VersionedTransaction.deserialize(txBytes));
}

async function postJson(url, body) {
	const res = await fetch(url, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify(body),
	});
	const text = await res.text();
	let data;
	try {
		data = JSON.parse(text);
	} catch {
		data = { error: 'parse_error', error_description: text.slice(0, 200) };
	}
	if (!res.ok) {
		const err = new Error(data.error_description || data.error || `HTTP ${res.status}`);
		err.status = res.status;
		err.data = data;
		throw err;
	}
	return data;
}

// A same-origin endpoint can never be refused by CORS, so a rejected fetch there
// really is a connectivity problem. Anything else is a different host answering.
function isCrossOrigin(endpoint) {
	try {
		return new URL(endpoint, location.href).origin !== location.origin;
	} catch {
		return false;
	}
}

// Probe the merchant endpoint with a benign request to extract the 402 challenge.
// Accepts HTTP 402 (standard x402) or HTTP 401 with a `payment-required` header
// (MCP 2025-06-18 spec, which uses 401 for resource-server authorization challenges).
async function discoverChallenge(opts) {
	const headers = { ...(opts.headers || {}) };
	const init = {
		method: opts.method || 'GET',
		headers,
		body: opts.body ? (typeof opts.body === 'string' ? opts.body : JSON.stringify(opts.body)) : undefined,
	};
	if (init.body && !headers['content-type']) headers['content-type'] = 'application/json';
	let res;
	try {
		res = await fetch(opts.endpoint, init);
	} catch (err) {
		// fetch() rejects with a bare "Failed to fetch" for an offline client, a
		// blocked request, and a CORS refusal alike. Say what the buyer can act on
		// rather than surfacing the browser's own wording as the checkout's error.
		// Telling a buyer to check their connection when the service simply does
		// not allow browser calls sends them to retry a button that can never
		// work, so separate the two cases by where the endpoint lives.
		if (isCrossOrigin(opts.endpoint)) {
			throw Object.assign(
				new Error(`${new URL(opts.endpoint, location.href).host} does not allow browser requests (its response carries no CORS headers), so its price cannot be confirmed from this page. Call it from a server, an agent, or the x402 CLI instead.`),
				{ code: 'cors_blocked' },
			);
		}
		throw new Error(`Could not reach the service to confirm its price (${err?.message || 'network error'}). Check your connection and try again.`);
	}

	// MCP 2025-06-18 endpoints return 401 with the full x402 challenge in the
	// `payment-required` header (base64-JSON). Accept that alongside standard 402.
	const prHeader = res.headers.get('payment-required');
	const is401WithChallenge = res.status === 401 && !!prHeader;

	if (res.status !== 402 && !is401WithChallenge) {
		// Endpoint isn't paid (200) or isn't an x402 endpoint at all. In either
		// case, surface a clear error — accidentally pointing the modal at a
		// free endpoint should not silently succeed.
		const txt = await res.text();
		// A paid endpoint that cannot settle right now answers 503
		// settlement_unavailable (the sponsor wallet is under its SOL floor, or
		// the fee budget is spent). That is a temporary funding gap on our side,
		// not a broken link or a buyer mistake, so say so in a sentence instead
		// of pasting a JSON envelope at someone trying to walk through a door.
		let parsed = null;
		try { parsed = JSON.parse(txt); } catch { /* not JSON: fall through */ }
		if (res.status === 503 || parsed?.error === 'settlement_unavailable') {
			const err = new Error(
				'Payments are temporarily paused while we top up the wallet that settles them. ' +
				'Nothing was charged. Try again shortly.',
			);
			err.code = 'settlement_unavailable';
			err.retryable = true;
			throw err;
		}
		throw new Error(`Endpoint did not return 402 (got ${res.status}). Body: ${txt.slice(0, 120)}`);
	}

	// For 401+header, decode directly — the full envelope is in the header.
	// For 402, read body first and fall back to header if body is minimal.
	let body = is401WithChallenge ? b64decode(prHeader) : await res.json().catch(() => null);
	if (!body || !Array.isArray(body.accepts) || !body.accepts.length) {
		// send402 (api/_lib/x402-spec.js) only emits `{error}` in the body and
		// puts the full v2 PaymentRequired envelope (accepts + extensions) in
		// the base64-JSON PAYMENT-REQUIRED header. b64decode returns already-
		// parsed JSON, so use its result directly.
		const decoded = b64decode(prHeader);
		if (decoded && Array.isArray(decoded.accepts) && decoded.accepts.length) {
			body = decoded;
		}
	}
	if (!body || !Array.isArray(body.accepts) || !body.accepts.length) {
		throw new Error('Endpoint returned 402 but no `accepts` array could be found in body or header');
	}
	return body;
}

// ───────────────────────────────────────────────────────── public api ───────

// A caller that supplies a request body but no method means POST: fetch() throws
// a TypeError ("Request with GET/HEAD method cannot have body") the moment a body
// is paired with the GET default, which kills the flow at the discovery step
// before the endpoint is ever contacted. The data-attribute binding below already
// infers the method this way; pay() has to agree, because a programmatic caller
// passing { endpoint, body } is the most natural way to reach a paid POST route.
function normalizeOpts(opts) {
	if (opts.method) return opts;
	return { ...opts, method: opts.body ? 'POST' : 'GET' };
}

export async function pay(opts) {
	if (!opts?.endpoint) throw new Error('X402.pay: endpoint is required');
	const modal = new CheckoutModal(normalizeOpts(opts));
	const result = modal.mount();
	// kick off the discovery on next tick so the modal animates in first.
	queueMicrotask(() => modal.start());
	return result;
}

function bindElement(el) {
	if (el.dataset.x402Bound === '1') return;
	el.dataset.x402Bound = '1';
	el.addEventListener('click', async (e) => {
		e.preventDefault();
		const opts = readOptsFrom(el);
		try {
			const out = await pay(opts);
			if (out?.siwx) {
				el.dispatchEvent(new CustomEvent('x402:siwx-signed', { detail: out.siwx, bubbles: true }));
			}
			el.dispatchEvent(new CustomEvent('x402:result', { detail: out, bubbles: true }));
		} catch (err) {
			if (err?.code === 'cancelled') return;
			el.dispatchEvent(new CustomEvent('x402:error', { detail: { error: err?.message || String(err) }, bubbles: true }));
		}
	});
}

function readOptsFrom(el) {
	const ds = el.dataset;
	let body = ds.x402Body;
	if (body) {
		try { body = JSON.parse(body); } catch { /* keep as string */ }
	}
	let headers = ds.x402Headers;
	if (headers) {
		try { headers = JSON.parse(headers); } catch { headers = undefined; }
	}
	return {
		endpoint: ds.x402Endpoint,
		method: ds.x402Method || (body ? 'POST' : 'GET'),
		body,
		headers,
		merchant: ds.x402Merchant,
		action: ds.x402Action || el.textContent?.trim().slice(0, 60),
	};
}

export function init() {
	if (typeof document === 'undefined') return;
	document.querySelectorAll('[data-x402-endpoint]').forEach(bindElement);
}

// Auto-init on DOMContentLoaded, plus on demand.
if (typeof document !== 'undefined') {
	if (document.readyState === 'loading') {
		document.addEventListener('DOMContentLoaded', init, { once: true });
	} else {
		init();
	}
	// Re-scan when merchants dynamically inject buttons.
	const mo = new MutationObserver(() => init());
	mo.observe(document.documentElement, { childList: true, subtree: true });
}

// Expose to merchants' inline scripts.
if (typeof window !== 'undefined') {
	window.X402 = Object.freeze({ pay, init, version: VERSION });
}