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
/**
* The Living Avatar — the agent's wallet-reactive IDENTITY layer (the nameplate).
*
* Where wallet-aura.js (the glow) answers "how funded does this agent LOOK," this
* module answers "WHO is this agent, on chain." It renders the avatar's license
* plate: the agent name, its vanity-highlighted public address, and a tier glyph
* that reads the SAME wealth bucket the aura paints — anchored to the avatar so you
* can look at a character and read its financial life at a glance.
*
* One source of truth, composed not reinvented:
* • identity (address, vanity prefix/suffix, rarity, owner, deep links) comes from
* getWalletStatus() in agent-wallet-chip.js — the platform's one normalizer;
* • the vanity-highlighted address uses that module's one highlightAddress();
* • the tier + accent come from wallet-networth.js (tierForUsd/computeWalletVisual),
* the same tier math the 2D and 3D auras use;
* • live tier + the pulse-on-earn ride agent-wealth-state.js's cached custody read,
* so the nameplate and the aura share ONE request per agent and never disagree.
*
* Three fidelities, same data:
* • mountNameplate() — a DOM overlay plate anchored to a hero / card avatar;
* • applyWorldNameplate() — a cheap, pooled enrichment of a world's floating name
* label (tier dot + vanity mark via CSS, survives the
* renderer's per-frame textContent updates);
* • resolveLivingAvatar() — the pure descriptor both renderers (and Tasks 04/05)
* consume: { tier, holdsThree, vanity, address, … }.
*
* Honest by construction: a real $0 wallet shows a clean plate with no tier glyph
* (an owner sees a "fund to light it up" nudge); an RPC failure silently falls back
* to the identity-only plate, never a broken effect. No precise dollar value is ever
* floated over an avatar — only the bucketed tier. $THREE is the only coin named.
*/
import { getWalletStatus, highlightAddress, ensureWalletChipStyles } from './agent-wallet-chip.js';
import { tierForUsd, computeWalletVisual } from './wallet-networth.js';
import { fetchWealthState, computeWealthDynamics } from './agent-wealth-state.js';
import { normalizePrefs } from './agent-networth.js';
const STYLE_ID = 'tws-living-avatar-styles';
const REDUCED_MOTION =
typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
function esc(s) {
return String(s == null ? '' : s).replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
function agentIdOf(agent) {
if (!agent) return null;
if (typeof agent === 'string') return agent;
return agent.agent_id || agent.agentId || agent.id || null;
}
// ── pure descriptor ───────────────────────────────────────────────────────────
/**
* Resolve an agent record (+ optional real wallet figures) into the normalized
* Living-Avatar descriptor every renderer consumes. Pure and synchronous — pass a
* known `usd`/`holdsThree` to get the tier filled in, omit them for the loading
* (identity-only) descriptor. Tier math and identity are NOT reimplemented here:
* they compose getWalletStatus + tierForUsd/computeWalletVisual.
*
* @param {object|string} agent any supported agent/avatar record (or just an id)
* @param {object} [opts]
* @param {number} [opts.usd] real total portfolio USD (undefined → tier unknown)
* @param {boolean} [opts.holdsThree] real $THREE holding (drives the brand accent)
* @param {boolean} [opts.isOwner] server-resolved ownership for the viewer
* @returns {{
* agentId, address, name, avatarUrl, prefix, suffix, isVanity, rarity,
* explorerUrl, hubUrl, ownerName, isOwner, hasWallet,
* tier, tierLabel, level, accent, glow, dormant, holdsThree, hasTier
* }}
*/
export function resolveLivingAvatar(agent, opts = {}) {
const status = typeof agent === 'string' ? null : getWalletStatus(agent);
const usd = opts.usd;
const hasTier = Number.isFinite(usd);
const holdsThree = !!opts.holdsThree;
const visual = hasTier
? computeWalletVisual({ usdTotal: usd, mix: holdsThree ? { three: 1 } : { sol: 1 }, hasThree: holdsThree })
: null;
const tier = hasTier ? tierForUsd(usd) : null;
if (!status) {
const id = agentIdOf(agent);
const name = typeof agent === 'object'
? agent?.name || agent?.display_name || agent?.agent_name || null
: null;
return {
agentId: id, address: null, name, avatarUrl: null,
prefix: null, suffix: null, isVanity: false, rarity: null,
explorerUrl: null, hubUrl: id ? `/agents/${id}/wallet` : null,
ownerName: null, isOwner: !!opts.isOwner, hasWallet: false,
tier: tier?.key || null, tierLabel: tier?.label || null, level: tier?.level ?? null,
accent: visual?.accent || 'var(--wallet-accent,#c4b5fd)',
glow: visual?.glow || 'var(--wallet-glow,rgba(139,92,246,.45))',
dormant: hasTier ? !!visual?.dormant : true,
holdsThree, hasTier,
};
}
return {
agentId: status.agentId, address: status.address, name: status.name, avatarUrl: status.avatarUrl,
prefix: status.prefix, suffix: status.suffix, isVanity: status.isVanity, rarity: status.rarity,
explorerUrl: status.explorerUrl, hubUrl: status.hubUrl, ownerName: status.ownerName,
isOwner: !!opts.isOwner, hasWallet: true,
tier: tier?.key || null, tierLabel: tier?.label || null, level: tier?.level ?? null,
accent: visual?.accent || 'var(--wallet-accent,#c4b5fd)',
glow: visual?.glow || 'var(--wallet-glow,rgba(139,92,246,.45))',
dormant: hasTier ? !!visual?.dormant : false,
holdsThree, hasTier,
};
}
// ── styles ──────────────────────────────────────────────────────────────────
function ensureStyles() {
if (typeof document === 'undefined' || document.getElementById(STYLE_ID)) return;
const s = document.createElement('style');
s.id = STYLE_ID;
s.textContent = `
.la-plate{position:absolute;z-index:6;left:50%;bottom:10px;transform:translateX(-50%);
display:inline-flex;align-items:center;gap:7px;max-width:calc(100% - 16px);
padding:5px 9px;border-radius:999px;pointer-events:auto;
font:600 12px/1 var(--font-body,Inter,system-ui,-apple-system,"Segoe UI",sans-serif);
color:var(--ink,#e8e8e8);background:var(--surface-2,rgba(18,18,22,.82));
border:1px solid var(--wallet-stroke,rgba(139,92,246,.3));
box-shadow:0 6px 22px rgba(0,0,0,.4);backdrop-filter:blur(var(--blur-md,12px));
--la-accent:var(--wallet-accent,#c4b5fd);--la-glow:var(--wallet-glow,rgba(139,92,246,.45));
opacity:0;transition:opacity .35s var(--ease-standard,ease),transform .25s var(--ease-standard,ease),border-color .25s ease,box-shadow .3s ease;}
.la-plate[data-pos="top"]{bottom:auto;top:10px;}
.la-plate[data-ready="1"]{opacity:1;}
.la-plate[data-vanity="1"]{border-color:var(--wallet-stroke-strong,rgba(139,92,246,.5));}
.la-plate[data-three="1"]{border-color:color-mix(in srgb,var(--la-accent) 60%,#f0c46e 40%);}
.la-plate:hover,.la-plate:focus-within{border-color:var(--wallet-stroke-strong,rgba(139,92,246,.55));box-shadow:0 8px 28px rgba(0,0,0,.5),0 0 0 1px var(--la-glow);}
.la-plate:focus-visible{outline:2px solid var(--la-glow);outline-offset:2px;}
.la-glyph{width:9px;height:9px;border-radius:50%;flex:none;position:relative;
background:var(--la-accent);box-shadow:0 0 7px var(--la-glow);transition:background .4s ease,box-shadow .4s ease;}
.la-plate[data-tier="dormant"] .la-glyph,.la-plate[data-tierless="1"] .la-glyph{background:var(--ink-faint,rgba(255,255,255,.32));box-shadow:none;}
.la-glyph-sk{background:linear-gradient(90deg,rgba(255,255,255,.1),rgba(255,255,255,.28),rgba(255,255,255,.1));
background-size:200% 100%;animation:la-sk 1.1s ease-in-out infinite;box-shadow:none;}
@keyframes la-sk{0%{background-position:200% 0}100%{background-position:-200% 0}}
.la-name{font-weight:700;color:var(--ink-bright,#fff);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:140px;}
.la-addr{font-family:var(--font-mono,ui-monospace,SFMono-Regular,Menlo,monospace);font-size:11px;letter-spacing:.01em;
color:var(--wallet-accent,#c4b5fd);display:inline-flex;gap:1px;align-items:center;border-left:1px solid var(--wallet-stroke,rgba(139,92,246,.28));padding-left:7px;}
.la-addr .twc-hi{color:var(--ink-bright,#fff);font-weight:700;}
.la-addr .twc-dots{opacity:.5;}
.la-three{font-size:9px;font-weight:800;letter-spacing:.03em;text-transform:uppercase;flex:none;
color:#1a1206;background:linear-gradient(135deg,#f0c46e,#e0a94a);padding:2px 6px;border-radius:999px;line-height:1.3;}
.la-expand{display:inline-flex;align-items:center;gap:5px;max-width:0;overflow:hidden;opacity:0;
transition:max-width .28s var(--ease-standard,ease),opacity .2s ease;}
.la-plate:hover .la-expand,.la-plate:focus-within .la-expand{max-width:120px;opacity:1;}
.la-act{appearance:none;background:none;border:none;padding:0 2px;margin:0;cursor:pointer;color:inherit;opacity:.7;
display:inline-flex;align-items:center;transition:opacity .15s ease,transform .12s ease;}
.la-act:hover{opacity:1;}
.la-act:active{transform:scale(.9);}
.la-act:focus-visible{outline:2px solid var(--la-glow);outline-offset:2px;border-radius:4px;}
.la-act svg{width:13px;height:13px;}
.la-copied{color:var(--success,#4ade80)!important;}
.la-tip{font:700 10px/1 var(--font-body,Inter,system-ui);color:var(--wallet-accent-strong,#a78bfa);
border-left:1px solid var(--wallet-stroke,rgba(139,92,246,.28));padding-left:7px;white-space:nowrap;
appearance:none;background:none;border-top:none;border-right:none;border-bottom:none;cursor:pointer;transition:color .15s ease;}
.la-tip:hover{color:var(--ink-bright,#fff);}
.la-tip:focus-visible{outline:2px solid var(--la-glow);outline-offset:2px;border-radius:4px;}
.la-fund{font:700 10px/1 var(--font-body,Inter,system-ui);color:var(--wallet-accent-strong,#a78bfa);
border-left:1px solid var(--wallet-stroke,rgba(139,92,246,.28));padding-left:7px;white-space:nowrap;text-decoration:none;transition:color .15s ease;}
.la-fund:hover{color:var(--ink-bright,#fff);}
.la-plate.la-pulse{animation:la-pulse 1.2s var(--ease-standard,ease-out);}
@keyframes la-pulse{0%{box-shadow:0 6px 22px rgba(0,0,0,.4),0 0 0 0 var(--la-glow);}
30%{box-shadow:0 6px 22px rgba(0,0,0,.4),0 0 0 8px color-mix(in srgb,var(--la-glow) 0%,transparent);}
100%{box-shadow:0 6px 22px rgba(0,0,0,.4),0 0 0 0 transparent;}}
.la-plate[data-lod="card"]{padding:3px 7px;gap:5px;font-size:11px;bottom:6px;}
.la-plate[data-lod="card"] .la-name{max-width:90px;}
.la-plate[data-lod="card"] .la-addr,.la-plate[data-lod="card"] .la-expand{display:none;}
/* ── world label enrichment (CSS-only, survives renderer textContent updates) ── */
.walk-remote-label.la-world-label{--la-tier:var(--ink-faint,rgba(255,255,255,.4));}
.walk-remote-label.la-world-label::before{content:"";display:inline-block;width:7px;height:7px;border-radius:50%;
margin-right:6px;vertical-align:middle;background:var(--la-tier);box-shadow:0 0 6px var(--la-tier);}
.walk-remote-label[data-la-tier="dormant"]::before,.walk-remote-label.la-world-label:not([data-la-tier])::before{box-shadow:none;opacity:.6;}
.walk-remote-label[data-la-vanity]::after{content:"✦";margin-left:5px;color:var(--wallet-accent,#c4b5fd);font-weight:700;vertical-align:middle;}
.walk-remote-label.la-world-three{border-color:color-mix(in srgb,var(--wallet-accent,#c4b5fd) 55%,#f0c46e 45%)!important;}
@media (prefers-reduced-motion: reduce){
.la-plate,.la-glyph,.la-expand{transition:none;}
.la-glyph-sk{animation:none;}
.la-plate.la-pulse{animation:none;}
}`;
(document.head || document.documentElement).appendChild(s);
}
const COPY_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
const LINK_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg>';
const GEAR_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1Z"/></svg>';
async function copyToClipboard(addr, btn) {
if (!addr || typeof navigator === 'undefined' || !navigator.clipboard) return;
try {
await navigator.clipboard.writeText(addr);
if (!btn) return;
const prev = btn.innerHTML;
btn.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="20 6 9 17 4 12"/></svg>';
btn.classList.add('la-copied');
setTimeout(() => { btn.innerHTML = prev; btn.classList.remove('la-copied'); }, 1400);
} catch { /* clipboard denied — address still legible on the plate */ }
}
// ── overlay nameplate (hero / card) ───────────────────────────────────────────
/**
* Mount the Living-Avatar nameplate as a DOM overlay anchored to a container that
* holds an avatar (a <model-viewer> stage, a portrait wrap, a card thumb). Renders
* identity (name + vanity address) immediately from the record, then hydrates the
* tier glyph + role-appropriate actions from the real wallet — never blocking the
* avatar's first paint on wallet data.
*
* @param {HTMLElement} container
* @param {object} agent any supported agent/avatar record
* @param {object} [opts]
* @param {'mainnet'|'devnet'} [opts.network='mainnet']
* @param {'top'|'bottom'} [opts.position='bottom']
* @param {'full'|'card'} [opts.lod='full'] card LOD hides the address/expand for dense thumbs
* @param {boolean} [opts.isOwner=false] initial owner hint (reconciled with the server read)
* @param {boolean} [opts.live=true] keep the tier glyph current + pulse on real earnings
* @returns {{ el, update(state), setTier(usd,holdsThree), setPrefs(prefs), pulse(), destroy() }|null}
*/
export function mountNameplate(container, agent, opts = {}) {
if (!container || typeof document === 'undefined') return null;
ensureWalletChipStyles();
ensureStyles();
const network = opts.network === 'devnet' ? 'devnet' : 'mainnet';
const lod = opts.lod === 'card' ? 'card' : 'full';
const position = opts.position === 'top' ? 'top' : 'bottom';
const agentId = agentIdOf(agent);
const cs = getComputedStyle(container);
if (cs.position === 'static') container.style.position = 'relative';
let descriptor = resolveLivingAvatar(agent, { isOwner: !!opts.isOwner });
// No wallet at all and no name → nothing meaningful to anchor; bail cleanly.
if (!descriptor.hasWallet && !descriptor.name) return null;
const plate = document.createElement('div');
plate.className = 'la-plate';
plate.dataset.pos = position;
plate.dataset.lod = lod;
plate.dataset.tierless = '1';
plate.setAttribute('tabindex', '0');
plate.setAttribute('role', 'group');
let prefs = null;
let isOwner = !!opts.isOwner;
let lastTipAt = null;
let lastUsd = null;
let primed = false;
function render() {
const showAddr = descriptor.hasWallet && lod === 'full' && !(prefs && prefs.nameplate?.address === false);
const showTier = !(prefs && (prefs.reactivity === 'off' || prefs.signals?.aura === false || prefs.nameplate?.tier === false));
const vanity = descriptor.isVanity;
const three = descriptor.holdsThree && showTier;
plate.style.setProperty('--la-accent', descriptor.accent);
plate.style.setProperty('--la-glow', descriptor.glow);
plate.dataset.tier = descriptor.tier || 'dormant';
plate.dataset.vanity = vanity ? '1' : '0';
plate.dataset.three = three ? '1' : '0';
// Tier glyph: a skeleton dot until the first read, then the real bucket (or
// removed when the wallet is honestly empty). Never a precise dollar value.
const tierState = !descriptor.hasTier ? 'sk' : descriptor.dormant || !showTier ? 'off' : 'on';
plate.dataset.tierless = tierState === 'on' ? '0' : '1';
const glyphCls = tierState === 'sk' ? 'la-glyph la-glyph-sk' : 'la-glyph';
const glyphTitle = tierState === 'sk'
? 'Reading wallet…'
: tierState === 'off'
? (descriptor.hasWallet ? 'Dormant wallet' : 'Wallet provisioning')
: `${descriptor.tierLabel} tier · funded`;
const addrHTML = showAddr
? `<span class="la-addr" aria-label="Wallet address ${esc(descriptor.address)}">${highlightAddress(descriptor.address, descriptor.prefix, descriptor.suffix, { head: 4, tail: 4 })}</span>`
: '';
const threeTag = three
? '<span class="la-three" title="Holds $THREE — the platform coin">$THREE</span>'
: '';
// Expand-on-hover: full-address copy + explorer (visitor-safe, read-only).
const expand = descriptor.hasWallet && lod === 'full'
? `<span class="la-expand">` +
`<button type="button" class="la-act" data-la-copy title="Copy address" aria-label="Copy wallet address">${COPY_SVG}</button>` +
`<a class="la-act" href="${esc(descriptor.explorerUrl)}" target="_blank" rel="noopener noreferrer" title="View on Solscan" aria-label="View wallet on Solscan">${LINK_SVG}</a>` +
`</span>`
: '';
// Role action: owner → tune how the agent presents (opens the presence panel);
// non-owner → tip the agent; a fresh empty wallet nudges its owner to fund it.
let action = '';
if (isOwner) {
if (descriptor.hasWallet && descriptor.dormant && descriptor.hasTier) {
action = descriptor.hubUrl
? `<a class="la-fund" href="${esc(descriptor.hubUrl)}#deposit" title="Fund this agent to light it up">⚡ Fund</a>`
: '';
} else if (lod === 'full') {
action = `<button type="button" class="la-act" data-la-settings title="Tune how your agent presents" aria-label="Nameplate display settings">${GEAR_SVG}</button>`;
}
} else if (descriptor.hasWallet) {
action = `<button type="button" class="la-tip" data-la-tip title="Tip ${esc(descriptor.name || 'this agent')}">◎ Tip</button>`;
}
plate.innerHTML =
`<span class="${glyphCls}" aria-hidden="true" title="${esc(glyphTitle)}"></span>` +
`<span class="la-name">${esc(descriptor.name || 'Agent')}</span>` +
threeTag + addrHTML + expand + action;
plate.setAttribute('aria-label',
`${descriptor.name || 'Agent'}${descriptor.hasWallet ? `, wallet ${descriptor.address}` : ''}` +
`${tierState === 'on' ? `, ${descriptor.tierLabel} tier` : ''}${three ? ', holds $THREE' : ''}`);
wire();
}
function wire() {
const copyBtn = plate.querySelector('[data-la-copy]');
if (copyBtn) copyBtn.addEventListener('click', (e) => { e.preventDefault(); e.stopPropagation(); copyToClipboard(descriptor.address, copyBtn); });
const tip = plate.querySelector('[data-la-tip]');
if (tip) tip.addEventListener('click', async (e) => {
e.preventDefault(); e.stopPropagation();
try {
const { openTipModal } = await import('./agent-tip-modal.js');
openTipModal({
id: descriptor.agentId, solana_address: descriptor.address,
name: descriptor.name || 'this agent', avatar_thumbnail_url: descriptor.avatarUrl || '',
meta: { payments: { accepted_tokens: (agent?.meta?.payments?.accepted_tokens || agent?.payments?.accepted_tokens || []) } },
});
} catch { /* address still copyable from the expanded plate */ }
});
const gear = plate.querySelector('[data-la-settings]');
if (gear) gear.addEventListener('click', (e) => { e.preventDefault(); e.stopPropagation(); openOwnerSettings(); });
}
// Owner settings affordance: reveal the presence panel (the owner's control
// centre for how the agent presents itself). Scroll the nearest one into view
// and flash it; broadcast an event so a page can open a collapsed panel; fall
// back to the wallet hub so the affordance is never a dead end.
function openOwnerSettings() {
if (agentId) window.dispatchEvent(new CustomEvent('tws:open-presence', { detail: { agentId } }));
const panel = document.querySelector('.nwp');
if (panel) {
panel.scrollIntoView({ behavior: REDUCED_MOTION ? 'auto' : 'smooth', block: 'center' });
panel.animate?.(
[{ boxShadow: '0 0 0 0 rgba(139,92,246,.6)' }, { boxShadow: '0 0 0 6px rgba(139,92,246,0)' }],
{ duration: 1000, easing: 'ease-out' },
);
return;
}
if (descriptor.hubUrl) window.location.href = `${descriptor.hubUrl}#presence`;
}
function setTier(usd, holdsThree) {
descriptor = resolveLivingAvatar(agent, { usd, holdsThree, isOwner });
render();
}
function setPrefs(p) {
prefs = p ? normalizePrefs(p) : null;
render();
}
function pulse() {
if (REDUCED_MOTION || !plate.isConnected) return;
if (prefs && (prefs.reactivity === 'off' || prefs.signals?.events === false)) return;
plate.classList.remove('la-pulse');
void plate.offsetWidth; // restart the animation
plate.classList.add('la-pulse');
setTimeout(() => plate.classList.remove('la-pulse'), 1300);
}
function update(state) {
if (!state || !state.ok) return;
if (typeof state.isOwner === 'boolean') isOwner = state.isOwner;
if (state.prefs) prefs = normalizePrefs(state.prefs);
descriptor = resolveLivingAvatar(agent, { usd: state.balanceUsd, holdsThree: state.holdsThree, isOwner });
render();
// A real new tip or a real balance increase fires one tasteful glint — only
// after the first (priming) read so landing on the page never replays an old
// event. The dynamics gate keeps a flat wallet from ever pulsing.
const dyn = computeWealthDynamics(state);
const tipAdvanced = state.lastTipAt && state.lastTipAt !== lastTipAt;
const grew = lastUsd != null && state.balanceUsd > lastUsd + 1e-6;
if (primed && (tipAdvanced || (grew && dyn.trend !== 'down'))) pulse();
lastTipAt = state.lastTipAt;
lastUsd = state.balanceUsd;
primed = true;
}
container.appendChild(plate);
render();
requestAnimationFrame(() => { plate.dataset.ready = '1'; });
// Apply the owner's nameplate/reactivity prefs the instant they're saved in the
// presence panel (it broadcasts), so a toggle is reflected without waiting for
// the next poll. Scoped to this agent.
const onPrefs = (e) => { if (e?.detail?.agentId === agentId && e.detail.prefs) setPrefs(e.detail.prefs); };
window.addEventListener('tws:networth-prefs', onPrefs);
// Live tier + pulse: a visibility-gated poll of the cached custody read. Uses the
// shared 60s client cache (fresh:false) so on a hero page it rides the aura's
// poll for zero extra requests, and self-hydrates anywhere the aura isn't mounted.
let stop = () => {};
if (opts.live !== false && agentId) {
let timer = 0;
let stopped = false;
let visible = true;
const io = typeof IntersectionObserver === 'function'
? new IntersectionObserver((es) => { visible = es.some((e) => e.isIntersecting); }, { threshold: 0.01 })
: null;
if (io) io.observe(container);
const tick = async () => {
if (stopped) return;
if (visible && (typeof document === 'undefined' || document.visibilityState === 'visible')) {
try { update(await fetchWealthState(agentId, { network })); } catch { /* hold last real look */ }
}
if (!stopped) timer = setTimeout(tick, 30_000);
};
tick();
stop = () => { stopped = true; if (timer) clearTimeout(timer); try { io?.disconnect(); } catch { /* noop */ } };
}
return {
el: plate,
update, setTier, setPrefs, pulse,
destroy() { stop(); window.removeEventListener('tws:networth-prefs', onPrefs); plate.remove(); },
};
}
// ── world label enrichment (pooled, CSS-only) ─────────────────────────────────
const _embedCache = new Map(); // agentId -> Promise<embed|null> (dedupes across all labels)
function fetchEmbed(agentId, network) {
const key = `${agentId}:${network}`;
if (_embedCache.has(key)) return _embedCache.get(key);
const p = fetch(`/api/agents/wallet-embed?id=${encodeURIComponent(agentId)}&network=${encodeURIComponent(network)}`, {
headers: { accept: 'application/json' },
})
.then((r) => (r.ok ? r.json() : null))
.then((j) => j?.data || null)
.catch(() => null);
_embedCache.set(key, p);
return p;
}
/**
* Enrich a world's floating name label (e.g. walk.js's `.walk-remote-label`) with
* the agent's wealth tier + vanity, so a crowded plaza is instantly legible — you
* can see who's funded and who's vanity without walking up to each one. Drives the
* label's tier dot + vanity mark through CSS pseudo-elements and data attributes,
* which SURVIVE the renderer's per-frame `textContent = name` updates (no child
* nodes to clobber). One cached, deduped wallet-embed read per agent across all
* labels — no per-frame work, no per-label request storm. Visitor view only: it
* reads the public embed and shows the bucketed tier, never a dollar value.
*
* @param {HTMLElement} label the floating label element
* @param {string} agentId the piloted agent's UUID
* @param {object} [opts] { network }
* @returns {{ destroy: () => void }}
*/
export function applyWorldNameplate(label, agentId, opts = {}) {
if (!label || !agentId || typeof document === 'undefined') return { destroy() {} };
ensureStyles();
const network = opts.network === 'devnet' ? 'devnet' : 'mainnet';
let destroyed = false;
fetchEmbed(agentId, network).then((embed) => {
if (destroyed || !embed || !embed.address) return;
label.classList.add('la-world-label');
const usd = Number(embed.balanceUsd);
if (Number.isFinite(usd)) {
const tier = tierForUsd(usd);
const vis = computeWalletVisual({ usdTotal: usd, mix: Number(embed.three) > 0 ? { three: 1 } : { sol: 1 }, hasThree: Number(embed.three) > 0 });
label.dataset.laTier = tier.key;
label.style.setProperty('--la-tier', tier.level > 0 ? vis.accent : 'var(--ink-faint,rgba(255,255,255,.4))');
}
if (Number(embed.three) > 0) label.classList.add('la-world-three');
const v = embed.vanity;
if (v && (v.prefix || v.suffix)) label.dataset.laVanity = String(v.prefix || v.suffix);
// Accessible, non-doxxing hover summary (tier bucket + vanity, never a $ value).
const bucket = Number.isFinite(usd) ? tierForUsd(usd) : null;
const bits = [embed.name || ''];
if (bucket && bucket.level > 0) bits.push(`${bucket.label} tier`);
if (Number(embed.three) > 0) bits.push('holds $THREE');
if (v && (v.prefix || v.suffix)) bits.push('vanity address');
label.title = bits.filter(Boolean).join(' · ');
});
return {
destroy() {
destroyed = true;
label.classList.remove('la-world-label', 'la-world-three');
delete label.dataset.laTier;
delete label.dataset.laVanity;
label.style.removeProperty('--la-tier');
},
};
}
if (typeof window !== 'undefined') {
window.twsLivingAvatar = { resolveLivingAvatar, mountNameplate, applyWorldNameplate };
}