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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Unified wallet connect controller + button factory.
*
* Usage (Vite-bundled apps):
* import { createConnectWalletButton } from './wallet/connect-button.js';
* const ctrl = createConnectWalletButton(mountEl, { onSuccess: (data) => ... });
*/
import { BrowserProvider } from 'ethers';
import { STATES, initialState, reduce } from './state.js';
import { eagerConnectWallet, getWalletState } from '../erc8004/agent-registry.js';
import { trapFocus } from '../shared/focus-trap.js';
/** Chain IDs that match known ERC-8004 registry deployments. */
const DEFAULT_CHAIN_IDS = [1, 8453, 10, 42161, 11155111, 84532];
const CHAIN_NAMES = {
1: 'Mainnet',
8453: 'Base',
10: 'Optimism',
42161: 'Arbitrum One',
11155111: 'Sepolia',
84532: 'Base Sepolia',
};
const ASYNC_STATES = new Set([
STATES.DETECTING,
STATES.REQUESTING_ACCOUNTS,
STATES.SIGNING,
STATES.VERIFYING,
]);
// window.ethereum.request() has no network-layer timeout — a dead or
// reconnecting extension background port can leave the promise permanently
// unsettled, stranding the button in its connecting state forever.
function withTimeout(promise, ms, message) {
let timer;
const timeout = new Promise((_, reject) => {
timer = setTimeout(() => reject(new Error(message)), ms);
});
return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}
/**
* Build the EIP-4361 SIWE message string.
* Format must match the parser in api/auth/siwe/verify.js exactly.
*
* @param {string} address checksummed Ethereum address
* @param {number} chainId
* @param {string} nonce
* @param {{ domain: string, uri: string, issuedAt: string, expirationTime: string }} ctx
* @returns {string}
*/
function defaultMessageBuilder(address, chainId, nonce, { domain, uri, issuedAt, expirationTime }) {
return [
`${domain} wants you to sign in with your Ethereum account:`,
address,
'',
'Sign in to three.ws. This does not cost anything and proves wallet ownership. By signing, you agree to the Terms of Service (https://three.ws/legal/tos) and Privacy Policy (https://three.ws/legal/privacy).',
'',
`URI: ${uri}`,
'Version: 1',
`Chain ID: ${chainId}`,
`Nonce: ${nonce}`,
`Issued At: ${issuedAt}`,
`Expiration Time: ${expirationTime}`,
].join('\n');
}
/**
* Headless state machine for wallet connect / SIWE.
* Emits `change` CustomEvents on state transitions.
*
* @fires ConnectWalletController#change
*/
export class ConnectWalletController extends EventTarget {
/** @type {import('./state.js').ConnectState} */
#s;
#opts;
#onAccountsChanged;
#onChainChanged;
/** Active raw EIP-1193 provider (window.ethereum or WalletConnect). */
#activeProvider = null;
/** WalletConnect provider instance, kept separately for listener cleanup. */
#wcProvider = null;
/** 'browser' | 'walletconnect' | null — set on successful connect, used for error retry. */
#lastConnectMethod = null;
/**
* @param {{
* allowedChainIds?: number[],
* nonceUrl?: string,
* verifyUrl?: string,
* messageBuilder?: Function,
* onSuccess?: Function,
* autoDetect?: boolean,
* labels?: Record<string, string>,
* wcProjectId?: string,
* }} [opts]
*/
constructor(opts = {}) {
super();
this.#opts = {
allowedChainIds: DEFAULT_CHAIN_IDS,
nonceUrl: '/api/auth/siwe/nonce',
verifyUrl: '/api/auth/siwe/verify',
messageBuilder: defaultMessageBuilder,
onSuccess: null,
autoDetect: false,
labels: {},
wcProjectId: null,
...opts,
};
this.#s = initialState();
this.#onAccountsChanged = (accounts) =>
this.#dispatch({ type: 'ACCOUNTS_CHANGED', accounts });
this.#onChainChanged = (chainIdHex) => {
const chainId = parseInt(chainIdHex, 16);
this.#dispatch({ type: 'CHAIN_CHANGED', chainId });
if (!this.#opts.allowedChainIds.includes(chainId)) {
this.#dispatch({ type: 'WRONG_CHAIN' });
} else if (this.#s.status === STATES.WRONG_CHAIN) {
this.#dispatch({ type: 'CHAIN_OK' });
}
};
if (window.ethereum) {
window.ethereum.on('accountsChanged', this.#onAccountsChanged);
window.ethereum.on('chainChanged', this.#onChainChanged);
}
// Hydrate from any already-resolved silent reconnect (fired during app
// boot). If the shared registry has a connected address, jump straight
// to CONNECTED so the button renders the address instead of "Connect
// wallet" on first paint. If not yet resolved, attempt the silent path
// here too (idempotent — no popup).
this.#tryEagerHydrate();
}
async #tryEagerHydrate() {
const existing = getWalletState();
if (existing.address && existing.chainId) {
this.#dispatch({
type: 'ACCOUNTS_RESOLVED',
address: existing.address,
chainId: existing.chainId,
});
if (!this.#opts.allowedChainIds.includes(existing.chainId)) {
this.#dispatch({ type: 'WRONG_CHAIN' });
}
return;
}
const eager = await eagerConnectWallet();
if (eager) {
this.#dispatch({
type: 'ACCOUNTS_RESOLVED',
address: eager.address,
chainId: eager.chainId,
});
if (!this.#opts.allowedChainIds.includes(eager.chainId)) {
this.#dispatch({ type: 'WRONG_CHAIN' });
}
return;
}
// Restore an existing WalletConnect session without opening the modal.
if (this.#opts.wcProjectId) {
try {
const { initWCProvider } = await import('./wc-provider.js');
const wc = await initWCProvider({
projectId: this.#opts.wcProjectId,
chains: this.#opts.allowedChainIds.filter((id) => id > 0).slice(0, 1),
optionalChains: this.#opts.allowedChainIds.filter((id) => id > 0).slice(1),
});
if (wc.accounts?.length) {
wc.on('accountsChanged', this.#onAccountsChanged);
wc.on('chainChanged', this.#onChainChanged);
this.#wcProvider = wc;
this.#activeProvider = wc;
this.#lastConnectMethod = 'walletconnect';
this.#dispatch({
type: 'ACCOUNTS_RESOLVED',
address: wc.accounts[0],
chainId: wc.chainId,
});
if (!this.#opts.allowedChainIds.includes(wc.chainId)) {
this.#dispatch({ type: 'WRONG_CHAIN' });
}
}
} catch {
// No stored WC session — nothing to restore.
}
}
}
get state() {
return this.#s.status;
}
get address() {
return this.#s.address;
}
get chainId() {
return this.#s.chainId;
}
get error() {
return this.#s.error;
}
get lastConnectMethod() {
return this.#lastConnectMethod;
}
/** @param {{ type: string, [k: string]: any }} action */
#dispatch(action) {
const next = reduce(this.#s, action);
if (next === this.#s) return;
this.#s = next;
this.dispatchEvent(new CustomEvent('change', { detail: { ...next } }));
}
/** Initiate the connect flow from `idle`. Idempotent if already past idle. */
async connect() {
if (this.#s.status !== STATES.IDLE) return;
this.#dispatch({ type: 'CONNECT' });
if (!window.ethereum) {
this.#dispatch({ type: 'NO_PROVIDER' });
return;
}
this.#dispatch({ type: 'HAS_PROVIDER' });
try {
const provider = new BrowserProvider(window.ethereum);
await withTimeout(
provider.send('eth_requestAccounts', []),
60_000,
'Wallet connection timed out. Check your wallet extension and try again.',
);
const signer = await provider.getSigner();
const address = await signer.getAddress();
const network = await provider.getNetwork();
const chainId = Number(network.chainId);
this.#activeProvider = window.ethereum;
this.#lastConnectMethod = 'browser';
this.#dispatch({ type: 'ACCOUNTS_RESOLVED', address, chainId });
if (!this.#opts.allowedChainIds.includes(chainId)) {
this.#dispatch({ type: 'WRONG_CHAIN' });
await this.#trySwitchChain(provider);
}
} catch (e) {
this.#dispatch({ type: 'ERROR', error: e instanceof Error ? e : new Error(String(e)) });
}
}
/** Initiate connect via WalletConnect (opens QR modal). */
async connectWalletConnect() {
if (this.#s.status !== STATES.IDLE) return;
if (!this.#opts.wcProjectId) return;
this.#dispatch({ type: 'CONNECT' });
this.#dispatch({ type: 'HAS_PROVIDER' });
try {
const { initWCProvider } = await import('./wc-provider.js');
const wc = await initWCProvider({
projectId: this.#opts.wcProjectId,
chains: this.#opts.allowedChainIds.filter((id) => id > 0).slice(0, 1),
optionalChains: this.#opts.allowedChainIds.filter((id) => id > 0).slice(1),
});
wc.on('accountsChanged', this.#onAccountsChanged);
wc.on('chainChanged', this.#onChainChanged);
this.#wcProvider = wc;
this.#activeProvider = wc;
this.#lastConnectMethod = 'walletconnect';
await wc.connect();
const provider = new BrowserProvider(wc);
const signer = await provider.getSigner();
const address = await signer.getAddress();
const network = await provider.getNetwork();
const chainId = Number(network.chainId);
this.#dispatch({ type: 'ACCOUNTS_RESOLVED', address, chainId });
if (!this.#opts.allowedChainIds.includes(chainId)) {
this.#dispatch({ type: 'WRONG_CHAIN' });
await this.#trySwitchChain(provider);
}
} catch (e) {
this.#dispatch({ type: 'ERROR', error: e instanceof Error ? e : new Error(String(e)) });
}
}
/** Attempt to switch to the first allowed chain via wallet_switchEthereumChain. */
async #trySwitchChain(provider) {
const target = this.#opts.allowedChainIds[0];
const hex = '0x' + target.toString(16);
try {
await provider.send('wallet_switchEthereumChain', [{ chainId: hex }]);
// chainChanged event fires and handles the CHAIN_OK dispatch.
} catch (e) {
if (e?.code === 4902) {
this.#dispatch({
type: 'ERROR',
error: new Error(
`Chain ${CHAIN_NAMES[target] || target} is not in your wallet. Add it manually.`,
),
});
} else if (e?.code !== 4001) {
// 4001 = user rejected — surface as error; other codes are bugs
this.#dispatch({
type: 'ERROR',
error: e instanceof Error ? e : new Error(String(e)),
});
}
}
}
/** Sign a SIWE message and verify with the backend. Call from `connected` state. */
async signAndVerify() {
if (this.#s.status !== STATES.CONNECTED && this.#s.status !== STATES.WRONG_CHAIN) return;
this.#dispatch({ type: 'SIGN' });
try {
const provider = new BrowserProvider(this.#activeProvider || window.ethereum);
const signer = await provider.getSigner();
const address = await signer.getAddress();
const nonceRes = await fetch(this.#opts.nonceUrl, { credentials: 'include' });
if (!nonceRes.ok) throw new Error('Failed to get nonce');
const { nonce, csrf, domain: serverDomain, uri: serverUri } = await nonceRes.json();
// Prefer server-issued domain/uri so dev frontends proxying /api/*
// to a different origin still produce messages that match the
// upstream's domain check.
const domain = serverDomain || location.host;
const uri = serverUri || location.origin;
const issuedAt = new Date().toISOString();
const expirationTime = new Date(Date.now() + 5 * 60 * 1000).toISOString();
const message = this.#opts.messageBuilder(address, this.#s.chainId, nonce, {
domain,
uri,
issuedAt,
expirationTime,
});
const signature = await signer.signMessage(message);
this.#dispatch({ type: 'SIGNATURE_OBTAINED' });
const verifyRes = await fetch(this.#opts.verifyUrl, {
method: 'POST',
credentials: 'include',
headers: { 'content-type': 'application/json', 'x-csrf-token': csrf },
// tosAccepted: the signed statement carries the agreement; the flag
// tells the server to stamp acceptance on the user record.
body: JSON.stringify({ message, signature, tosAccepted: true }),
});
const data = await verifyRes.json();
if (!verifyRes.ok) throw new Error(data.error_description || 'Verification failed');
this.#dispatch({ type: 'SUCCESS' });
if (this.#opts.onSuccess) this.#opts.onSuccess(data);
} catch (e) {
this.#dispatch({ type: 'ERROR', error: e instanceof Error ? e : new Error(String(e)) });
}
}
/** Return to `idle` state, clearing any error. */
reset() {
this.#dispatch({ type: 'RESET' });
}
/** Remove all event listeners. Call when unmounting in SPA contexts. */
dispose() {
if (window.ethereum) {
window.ethereum.removeListener('accountsChanged', this.#onAccountsChanged);
window.ethereum.removeListener('chainChanged', this.#onChainChanged);
}
if (this.#wcProvider) {
this.#wcProvider.removeListener('accountsChanged', this.#onAccountsChanged);
this.#wcProvider.removeListener('chainChanged', this.#onChainChanged);
this.#wcProvider = null;
}
this.#activeProvider = null;
}
}
/**
* Live connect buttons, tracked so we can dispose controllers whose mount
* element has left the DOM. Without this, each SPA navigation that re-mounts
* the button on a fresh element leaks two `window.ethereum` listeners, which
* eventually trips MetaMask's MaxListenersExceededWarning (warns at 10+).
* @type {Set<{ ctrl: ConnectWalletController, mountEl: HTMLElement }>}
*/
const _liveButtons = new Set();
/** Dispose controllers whose mount element is no longer in the document. */
function disposeDetachedButtons() {
for (const rec of _liveButtons) {
if (!rec.mountEl.isConnected) {
rec.ctrl.dispose();
_liveButtons.delete(rec);
}
}
}
let _pickerStylesInjected = false;
function ensurePickerStyles() {
if (_pickerStylesInjected) return;
_pickerStylesInjected = true;
const s = document.createElement('style');
s.textContent = `
.cwb-picker {
position: fixed;
background: #18181b;
border: 1px solid #2d2d32;
border-radius: 10px;
box-shadow: 0 8px 32px rgba(0,0,0,0.5);
overflow: hidden;
min-width: 200px;
z-index: 9999;
}
.cwb-pick-item {
display: flex;
align-items: center;
gap: 10px;
width: 100%;
padding: 13px 16px;
background: none;
border: none;
color: #f4f4f5;
font-size: 14px;
font-family: inherit;
cursor: pointer;
text-align: left;
transition: background 0.12s;
white-space: nowrap;
}
.cwb-pick-item:hover { background: rgba(255,255,255,0.07); }
.cwb-pick-item:focus-visible { outline: 2px solid #34d399; outline-offset: -2px; background: rgba(255,255,255,0.07); }
.cwb-pick-item + .cwb-pick-item { border-top: 1px solid #2d2d32; }
.cwb-pick-icon {
display: inline-flex;
align-items: center;
justify-content: center;
width: 24px;
height: 24px;
border-radius: 6px;
flex-shrink: 0;
}
`;
document.head.appendChild(s);
}
function showWalletPicker(anchorEl, onBrowser, onWC) {
document.querySelector('.cwb-picker')?.remove();
ensurePickerStyles();
const picker = document.createElement('div');
picker.className = 'cwb-picker';
picker.setAttribute('role', 'dialog');
picker.setAttribute('aria-modal', 'true');
picker.setAttribute('aria-label', 'Choose a wallet to connect');
const mmBtn = document.createElement('button');
mmBtn.type = 'button';
mmBtn.className = 'cwb-pick-item';
mmBtn.innerHTML = `
<svg class="cwb-pick-icon" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="24" height="24" rx="6" fill="#E8831D"/>
<path d="M20 4L13.3 8.9l1.24-2.93L20 4z" fill="#E2761B" stroke="#E2761B" stroke-width=".1"/>
<path d="M4 4l6.64 5-1.18-3L4 4z" fill="#E4761B" stroke="#E4761B" stroke-width=".1"/>
</svg>
Browser wallet`;
const wcBtn = document.createElement('button');
wcBtn.type = 'button';
wcBtn.className = 'cwb-pick-item';
wcBtn.innerHTML = `
<svg class="cwb-pick-icon" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="24" height="24" rx="6" fill="#3B99FC"/>
<path d="M7.5 9.5c2.5-2.5 6.5-2.5 9 0l.3.3a.3.3 0 010 .42l-1.03 1.03a.15.15 0 01-.21 0l-.41-.42c-1.74-1.74-4.56-1.74-6.3 0l-.44.44a.15.15 0 01-.21 0L7.17 10.24a.3.3 0 010-.42L7.5 9.5zm11.13 2.12l.92.92a.3.3 0 010 .42l-4.14 4.14a.3.3 0 01-.42 0l-2.94-2.94a.08.08 0 00-.1 0l-2.94 2.94a.3.3 0 01-.42 0L5.45 13a.3.3 0 010-.42l.92-.92a.3.3 0 01.42 0l2.94 2.94c.03.03.08.03.1 0l2.94-2.94a.3.3 0 01.42 0l2.94 2.94c.03.03.08.03.1 0l2.94-2.94a.3.3 0 01.42 0z" fill="white"/>
</svg>
WalletConnect`;
picker.appendChild(mmBtn);
picker.appendChild(wcBtn);
document.body.appendChild(picker);
const rect = anchorEl.getBoundingClientRect();
picker.style.top = `${rect.bottom + 6}px`;
picker.style.left = `${rect.left}px`;
// W3AG 2.1.2: the page behind the chooser is inert, Tab cycles between the
// two options, Escape closes it, and focus returns to the Connect button.
let trap = null;
const closePicker = (restoreFocus = true) => {
document.removeEventListener('click', onOutside);
trap?.release(restoreFocus);
trap = null;
picker.remove();
};
const onOutside = (e) => {
if (!picker.contains(e.target) && e.target !== anchorEl) closePicker();
};
mmBtn.onclick = (e) => { e.stopPropagation(); closePicker(false); onBrowser(); };
wcBtn.onclick = (e) => { e.stopPropagation(); closePicker(false); onWC(); };
trap = trapFocus(picker, { onEscape: () => closePicker(), returnTo: anchorEl });
setTimeout(() => document.addEventListener('click', onOutside), 0);
}
const LABEL_DEFAULTS = {
idle: 'Connect wallet',
detecting: 'Detecting…',
no_provider: 'Install MetaMask',
requesting_accounts: 'Check your wallet…',
signing: 'Sign in your wallet…',
verifying: 'Verifying…',
success: 'Signed in',
error: 'Retry',
};
/**
* Mount a wallet connect button into `mountEl`.
* The element's contents are replaced with a single `<button class="cwb-btn">`.
*
* @param {HTMLElement} mountEl
* @param {{
* allowedChainIds?: number[],
* nonceUrl?: string,
* verifyUrl?: string,
* messageBuilder?: Function,
* onSuccess?: Function,
* labels?: Record<string, string>,
* wcProjectId?: string,
* }} [opts]
* @returns {ConnectWalletController}
*/
export function createConnectWalletButton(mountEl, opts = {}) {
// Dispose any previous controller on this mount point (handles HMR remounts)
// and sweep controllers whose mount element has left the DOM (SPA navigations)
// so their window.ethereum listeners can't accumulate.
if (mountEl._cwbCtrl) {
mountEl._cwbCtrl.dispose();
for (const rec of _liveButtons) {
if (rec.ctrl === mountEl._cwbCtrl) _liveButtons.delete(rec);
}
}
disposeDetachedButtons();
const labels = { ...LABEL_DEFAULTS, ...(opts.labels || {}) };
const allowedChainIds = opts.allowedChainIds || DEFAULT_CHAIN_IDS;
const wcProjectId = opts.wcProjectId || import.meta.env?.VITE_WALLETCONNECT_PROJECT_ID || null;
const ctrl = new ConnectWalletController({ ...opts, allowedChainIds, wcProjectId });
mountEl._cwbCtrl = ctrl;
_liveButtons.add({ ctrl, mountEl });
const btn = document.createElement('button');
btn.type = 'button';
btn.className = 'cwb-btn';
function render(detail) {
const s = detail.status;
btn.setAttribute('data-state', s);
btn.disabled = ASYNC_STATES.has(s) || s === STATES.SUCCESS;
btn.setAttribute('aria-busy', ASYNC_STATES.has(s) ? 'true' : 'false');
if (s === STATES.CONNECTED || s === STATES.WRONG_CHAIN) {
const addr = detail.address || '';
const short = addr ? addr.slice(0, 6) + '…' + addr.slice(-4) : '';
const chainName = CHAIN_NAMES[detail.chainId] || `Chain ${detail.chainId}`;
btn.textContent =
s === STATES.WRONG_CHAIN
? `Switch to ${CHAIN_NAMES[allowedChainIds[0]] || 'Mainnet'}`
: `${short} · ${chainName}`;
} else if (s === STATES.ERROR) {
btn.textContent = labels.error;
} else if (s === STATES.NO_PROVIDER && wcProjectId) {
btn.textContent = labels.idle || 'Connect wallet';
} else {
btn.textContent = labels[s] || s;
}
}
function updateClickHandler(status) {
btn.onclick = null;
if (status === STATES.NO_PROVIDER) {
if (wcProjectId) {
btn.onclick = () => ctrl.connectWalletConnect();
} else {
btn.onclick = () => window.open('https://metamask.io', '_blank', 'noopener');
}
} else if (status === STATES.CONNECTED) {
btn.onclick = () => ctrl.signAndVerify();
} else if (status === STATES.WRONG_CHAIN) {
btn.onclick = () => ctrl.connect();
} else if (status === STATES.ERROR) {
btn.onclick = () => {
ctrl.reset();
if (ctrl.lastConnectMethod === 'walletconnect') {
ctrl.connectWalletConnect();
} else {
ctrl.connect();
}
};
} else if (status === STATES.IDLE) {
if (wcProjectId) {
btn.onclick = window.ethereum
? () => showWalletPicker(btn, () => ctrl.connect(), () => ctrl.connectWalletConnect())
: () => ctrl.connectWalletConnect();
} else {
btn.onclick = () => ctrl.connect();
}
}
}
ctrl.addEventListener('change', (e) => {
render(e.detail);
updateClickHandler(e.detail.status);
});
// Initial render from current state.
render({ status: ctrl.state, address: ctrl.address, chainId: ctrl.chainId, error: ctrl.error });
updateClickHandler(ctrl.state);
mountEl.innerHTML = '';
mountEl.appendChild(btn);
return ctrl;
}