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
// <agent-3d> — the web component that ships the whole framework in one tag.
// See specs/EMBED_SPEC.md
import { Box3, Color, Vector3 } from 'three';
import { Viewer } from './viewer.js';
import { createVariantController } from './khr-variants.js';
import { buildBestEffortArUsdz } from './usdz-animated.js';
import { Runtime, skillAccessFromAgentDetail } from './runtime/index.js';
import { SkillPaymentModal, PaymentChip } from './payment-modal.js';
import { SceneController } from './runtime/scene.js';
import { SkillRegistry } from './skills/index.js';
import { Memory } from './memory/index.js';
import { loadManifest, fetchRelative } from './manifest.js';
import { uriCandidates } from './ipfs.js';
import { DEFAULT_AVATAR_GLB } from './shared/model-viewer-fallback.js';
import {
resolveAgentById,
resolveByAvatarId,
AgentResolveError,
} from './agent-resolver.js';
import { parseAgentRef, resolveOnchainAgent, toManifest } from './erc8004/resolver.js';
import { attachTradeReactions } from './pump/trade-reactions.js';
// BEGIN:EMBED_BRIDGES_IMPORT
import { EmbedActionBridge } from './embed-action-bridge.js';
import { protocol, ACTION_TYPES } from './agent-protocol.js';
import { AgentAvatar } from './agent-avatar.js';
// END:EMBED_BRIDGES_IMPORT
import { AgentNotifier } from './agent-notifier.js';
import { log } from './shared/log.js';
import {
apiOriginFromScriptURL,
resolveApiBase,
credentialsFor,
isPageOrigin,
} from './shared/embed-api-origin.js';
const MODES = ['inline', 'floating', 'section', 'fullscreen'];
// Zero-config free brain: routed through the we-pay `/api/llm/anthropic` proxy
// (src/runtime/providers.js), which resolves this id to OpenRouter's free tier.
// `brain="free"` gets any ad-hoc embed talking with no API key, no backend code,
// and no per-token cost to the embedder.
const FREE_BRAIN_MODEL = 'google/gemma-4-31b-it:free';
// ── WebGL context budget ────────────────────────────────────────────────
// Browsers cap the number of simultaneous WebGL contexts (~16 in Chrome).
// Each booted <agent-3d> holds one (two when axes are shown) for its whole
// lifetime, so a page with many avatars — a showcase grid, a marketplace, a
// long landing page — silently exhausts the budget. The browser then evicts
// the *oldest* context ("Too many active WebGL contexts. Oldest context will
// be lost.") and that avatar freezes or turns blank, with no way to recover
// while every other context stays alive.
//
// We cap the number of *live* viewers instead. When a new one boots over
// budget, the least-recently-visible offscreen viewer releases its context
// (full teardown → forceContextLoss) and re-arms its viewport observer, so it
// re-boots automatically the moment it scrolls back into view. Whatever the
// user is actually looking at is never evicted.
const MAX_LIVE_VIEWERS = (() => {
try {
const n = Number(typeof window !== 'undefined' ? window.AGENT3D_MAX_LIVE_VIEWERS : 0);
if (Number.isFinite(n) && n > 0) return Math.floor(n);
} catch {}
return 8;
})();
const _liveViewers = new Set();
const _nowMs = () =>
typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now();
function _trackLiveViewer(el) {
_liveViewers.add(el);
_enforceViewerBudget(el);
}
function _untrackLiveViewer(el) {
_liveViewers.delete(el);
}
// Standalone renderers elsewhere on the page (homepage avatar-drop, walk
// preview, footer bot, …) reserve slots via window.__agent3dReservedContexts
// (see webgl-budget.js). Subtract them so the page-wide total stays under the
// browser's ~16-context cap, never below one live viewer.
function _effectiveViewerBudget() {
let reserved = 0;
try {
const n = Number(typeof window !== 'undefined' ? window.__agent3dReservedContexts : 0);
if (Number.isFinite(n) && n > 0) reserved = Math.floor(n);
} catch {}
return Math.max(1, MAX_LIVE_VIEWERS - reserved);
}
function _enforceViewerBudget(justBooted) {
const budget = _effectiveViewerBudget();
if (_liveViewers.size <= budget) return;
const evictable = [];
for (const v of _liveViewers) {
if (v !== justBooted && v._isEvictable && v._isEvictable()) evictable.push(v);
}
// Least-recently-visible first.
evictable.sort((a, b) => (a._lastVisibleAt || 0) - (b._lastVisibleAt || 0));
let over = _liveViewers.size - budget;
for (const v of evictable) {
if (over <= 0) break;
v._releaseForBudget();
over--;
}
}
// Let standalone renderers trigger an eviction the moment they reserve a slot,
// instead of waiting for the next viewer to boot.
if (typeof window !== 'undefined') {
window.__agent3dEnforceBudget = () => {
try {
_enforceViewerBudget(null);
} catch {}
};
}
function _parsePx(val) {
const n = parseFloat(val);
return n > 0 && typeof val === 'string' && val.trim().endsWith('px') ? n : 0;
}
// The three.ws origin this script was served from. Cross-origin embeds send
// every API call here, never to the host page; see shared/embed-api-origin.js.
const _scriptOrigin = apiOriginFromScriptURL(import.meta.url);
const _pageOrigin = () => (typeof location !== 'undefined' ? location.origin : '');
function originAllowed(originUrl, policy, firstParty = []) {
if (!originUrl) return false;
let host;
try {
host = new URL(originUrl).hostname.toLowerCase();
} catch {
return false;
}
if (firstParty.some((fp) => host === fp || host.endsWith('.' + fp))) return true;
const hosts = policy?.origins?.hosts ?? [];
const mode = policy?.origins?.mode ?? 'allowlist';
const matches = hosts.some((h) => {
const lower = h.toLowerCase();
if (lower.startsWith('*.')) return host.endsWith(lower.slice(1)) && host !== lower.slice(2);
return host === lower;
});
return mode === 'allowlist' ? matches : !matches;
}
const BASE_STYLE = `
:host {
display: block;
position: relative;
width: 100%;
height: 480px;
--agent-bubble-radius: 16px;
--agent-accent: #3b82f6;
--agent-surface: rgba(17, 24, 39, 0.92);
--agent-on-surface: #f9fafb;
--agent-chat-font: system-ui, -apple-system, sans-serif;
--agent-mic-glow: #22c55e;
--agent-shadow: 0 20px 60px rgba(0,0,0,0.3);
--agent-bubble-bg: rgba(255, 255, 255, 0.95);
--agent-bubble-color: #1a1a2e;
--agent-bubble-shadow: 0 4px 24px rgba(0, 0, 0, 0.25);
--agent-bubble-font-size: 13px;
contain: layout style;
}
:host([mode="floating"]) {
position: fixed;
z-index: 2147483000;
width: var(--agent-width, 320px);
height: var(--agent-height, 420px);
border-radius: var(--agent-bubble-radius);
overflow: hidden;
box-shadow: var(--agent-shadow);
transition:
width 0.3s cubic-bezier(0.4, 0, 0.2, 1),
height 0.3s cubic-bezier(0.4, 0, 0.2, 1),
border-radius 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}
@media (prefers-reduced-motion: reduce) {
:host([mode="floating"]) { transition: none; }
}
/* Inline responsive: height follows width at a 3:4 portrait ratio */
:host([mode="inline"][data-responsive]) {
height: auto;
aspect-ratio: var(--agent-aspect, 3/4);
}
:host([mode="fullscreen"]) {
position: fixed;
inset: 0;
width: 100vw;
height: 100vh;
height: 100dvh;
z-index: 2147483000;
}
:host([hidden]) { display: none; }
.stage {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
transition: opacity 220ms ease-out;
}
/* Held while a freshly loaded body has no pose yet. The renderer paints the
rig the moment the GLB lands, which is its bind pose (a T-pose), and the
idle clip only takes over after it is fetched and retargeted. */
.stage.is-settling { opacity: 0; transition: none; }
.stage canvas { display: block; }
/* Pill tap target — shown when collapsed to pill on narrow viewports */
.pill-btn {
display: none;
position: absolute;
inset: 0;
width: 100%;
height: 100%;
background: none;
border: 0;
cursor: pointer;
border-radius: inherit;
z-index: 10;
}
/* Swipe-down handle visible when bottom-sheet is expanded */
.pill-drag {
display: none;
position: absolute;
top: 8px;
left: 50%;
transform: translateX(-50%);
width: 36px;
height: 4px;
border-radius: 2px;
background: rgba(255,255,255,0.25);
pointer-events: none;
z-index: 20;
}
.chrome {
position: absolute;
inset: 0;
display: flex;
flex-direction: column;
padding: 12px;
box-sizing: border-box;
gap: 0;
pointer-events: none;
}
.chrome > * { pointer-events: auto; }
.chat {
flex: 1;
display: flex;
flex-direction: column;
overflow-y: auto;
color: var(--agent-on-surface);
font: 14px/1.4 var(--agent-chat-font);
padding: 10px 12px;
scrollbar-width: thin;
scrollbar-color: rgba(255,255,255,0.1) transparent;
pointer-events: none;
}
.chat > * { pointer-events: auto; }
/* Transparent window in the chat — avatar canvas shows through here */
.avatar-anchor {
flex: 0 0 auto;
position: sticky;
bottom: 0;
pointer-events: none !important;
min-height: 260px;
margin-top: auto;
z-index: 1;
}
/* Thought bubble — appears above avatar's head while thinking */
.thought-bubble {
position: absolute;
top: 0;
left: 50%;
background: var(--agent-bubble-bg);
color: var(--agent-bubble-color);
border-radius: 20px;
padding: 8px 14px;
font: 600 var(--agent-bubble-font-size)/1 var(--agent-chat-font);
max-width: min(280px, 60%);
white-space: normal;
min-width: 80px;
min-height: 28px;
pointer-events: none;
opacity: 0;
transform: translateX(-50%) scale(0.85);
transform-origin: center bottom;
transition:
opacity 0.22s cubic-bezier(0.34, 1.56, 0.64, 1),
transform 0.22s cubic-bezier(0.34, 1.56, 0.64, 1);
box-shadow: var(--agent-bubble-shadow);
display: flex;
align-items: center;
gap: 5px;
z-index: 16;
}
.thought-bubble::after {
content: '';
position: absolute;
bottom: -8px;
top: auto;
left: 50%;
transform: translateX(-50%);
border-left: 8px solid transparent;
border-right: 8px solid transparent;
border-top: 8px solid var(--agent-bubble-bg);
border-bottom: none;
}
.thought-bubble[data-tail-dir="up"]::after {
bottom: auto;
top: -8px;
border-top: none;
border-bottom: 8px solid var(--agent-bubble-bg);
}
.thought-bubble[data-active="true"] { opacity: 1; transform: translateX(-50%) scale(1); }
.thought-bubble .text {
font: var(--agent-bubble-font-size)/1.4 var(--agent-chat-font);
color: var(--agent-bubble-color);
display: none;
}
.thought-bubble[data-streaming="true"] .text { display: block; }
.thought-bubble[data-streaming="true"] .dot { display: none; }
.thought-bubble .dot {
width: 6px;
height: 6px;
border-radius: 50%;
background: var(--agent-accent);
animation: thought-dot 1.4s ease-in-out infinite;
flex-shrink: 0;
}
.thought-bubble .dot:nth-child(2) { animation-delay: 0.2s; }
.thought-bubble .dot:nth-child(3) { animation-delay: 0.4s; }
@keyframes thought-dot {
0%, 60%, 100% { transform: translateY(0); opacity: 0.35; }
30% { transform: translateY(-4px); opacity: 1; }
}
@media (prefers-reduced-motion: reduce) {
.thought-bubble .dot { animation: none; opacity: 0.6; }
@keyframes thought-dot { to {} }
}
.thought-bubble[data-error="true"] {
background: rgba(239, 68, 68, 0.92);
color: #fff;
}
.thought-bubble[data-error="true"]::after {
border-top-color: rgba(239, 68, 68, 0.92);
}
.thought-bubble[data-error="true"][data-tail-dir="up"]::after {
border-bottom-color: rgba(239, 68, 68, 0.92);
border-top-color: transparent;
}
.msg {
margin: 6px 0;
padding: 8px 12px;
border-radius: 12px;
border-left: 3px solid transparent;
transition: border-color .2s;
background: var(--agent-surface);
backdrop-filter: blur(8px);
max-width: 85%;
}
.msg.user {
align-self: flex-end;
background: rgba(255, 255, 255, 0.1);
border-left: 0;
border-right: 3px solid var(--agent-accent);
}
.msg.assistant {
align-self: flex-start;
}
.msg.celebration { border-left-color: rgba(34,197,94,0.85); background: rgba(34,197,94,0.12); }
.msg.concern { border-left-color: rgba(239,68,68,0.85); background: rgba(239,68,68,0.06); }
.msg.curiosity { border-left-color: rgba(59,130,246,0.7); background: rgba(59,130,246,0.05); }
.msg .role { opacity: 0.55; font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; }
.msg .body { white-space: pre-wrap; }
.msg .body code { font-family: monospace; background: rgba(255,255,255,0.08); padding: 1px 4px; border-radius: 4px; font-size: 12px; }
.msg .body strong { font-weight: 700; }
.msg .body em { font-style: italic; opacity: 0.9; }
.msg.streaming .body::after { content: '▋'; opacity: 1; animation: blink-cursor 0.7s step-end infinite; margin-left: 2px; }
@keyframes blink-cursor { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
/* Suggestion chips when the conversation is empty */
.suggest-row { display: flex; flex-wrap: wrap; gap: 6px; padding: 8px 0 0; }
/* Composer: where a visitor types to the agent. Enter or the send button
submits; the mic appears only where speech input can actually work. */
.input-row {
display: flex;
align-items: center;
gap: 6px;
margin-top: 8px;
background: var(--agent-surface);
border: 1px solid rgba(255, 255, 255, 0.12);
border-radius: 999px;
padding: 4px 4px 4px 14px;
backdrop-filter: blur(12px);
-webkit-backdrop-filter: blur(12px);
flex: 0 0 auto;
transition: border-color 0.15s, box-shadow 0.15s, opacity 0.15s;
}
.input-row:hover { border-color: rgba(255, 255, 255, 0.22); }
.input-row:focus-within {
border-color: var(--agent-accent);
box-shadow: 0 0 0 3px color-mix(in srgb, var(--agent-accent) 30%, transparent);
}
.input-row[data-busy="true"] { opacity: 0.75; }
.input-row input {
flex: 1;
min-width: 0;
background: transparent;
border: 0;
color: var(--agent-on-surface);
font: 14px var(--agent-chat-font);
outline: none;
padding: 6px 0;
}
.input-row input::placeholder { color: color-mix(in srgb, var(--agent-on-surface) 55%, transparent); }
.input-row input:disabled { cursor: progress; }
.input-row input[data-state="thinking"] { opacity: 0.6; }
button.icon {
flex: 0 0 auto;
width: 36px;
height: 36px;
border-radius: 50%;
border: 0;
background: var(--agent-accent);
color: #fff;
cursor: pointer;
display: inline-flex;
align-items: center;
justify-content: center;
transition: transform 0.12s, filter 0.12s, box-shadow 0.15s, opacity 0.15s;
}
button.icon svg { width: 18px; height: 18px; }
button.icon:hover:not(:disabled) { filter: brightness(1.12); }
button.icon:active:not(:disabled) { transform: scale(0.94); }
button.icon:focus-visible { outline: 2px solid var(--agent-on-surface); outline-offset: 2px; }
button.icon:disabled { opacity: 0.45; cursor: default; }
button.icon.mic { background: rgba(255, 255, 255, 0.12); }
button.icon.mic[data-listening="true"] { box-shadow: 0 0 0 4px var(--agent-mic-glow); }
button.icon.mic[data-voice-state="listening"] { box-shadow: 0 0 0 4px #22c55e; }
button.icon.mic[data-voice-state="thinking"] { box-shadow: 0 0 0 4px #eab308; }
button.icon.mic[data-voice-state="speaking"] { box-shadow: 0 0 0 4px #3b82f6; }
@media (prefers-reduced-motion: reduce) {
.input-row, button.icon { transition: none; }
}
/* A chip carries its own ground. It used to be a 6% white wash, which is only
legible over something dark: on a host page with a light background the
near-white label disappeared. */
.suggest-chip { font: 600 11px/1 var(--agent-chat-font); color: var(--agent-on-surface); background: var(--agent-surface); border: 1px solid rgba(255,255,255,.14); padding: 6px 10px; border-radius: 999px; cursor: pointer; transition: all .12s; }
.suggest-chip:hover { background: rgba(38, 48, 70, 0.96); border-color: rgba(255,255,255,.26); }
.suggest-chip:focus-visible { outline: 2px solid var(--agent-accent); outline-offset: 2px; }
/* Tool-call indicator near the bottom of the canvas */
.tool-indicator { position: absolute; left: 50%; bottom: 96px; transform: translateX(-50%); display: none; align-items: center; gap: 8px; padding: 6px 12px; background: var(--agent-surface); color: var(--agent-on-surface); border-radius: 999px; font: 12px var(--agent-chat-font); backdrop-filter: blur(12px); pointer-events: none; opacity: 0; transition: opacity .15s; z-index: 3; }
.tool-indicator[data-active="true"] { display: inline-flex; opacity: 1; }
.tool-indicator .spin { width: 10px; height: 10px; border-radius: 50%; border: 2px solid rgba(255,255,255,.25); border-top-color: var(--agent-accent); animation: spin .9s linear infinite; }
@keyframes spin { to { transform: rotate(360deg); } }
/* Sticky alert banner (e.g. rug flag) */
.alert-banner { position: absolute; top: 12px; left: 12px; right: 12px; padding: 8px 12px; border-radius: 10px; font: 600 12px/1.4 var(--agent-chat-font); display: none; align-items: center; gap: 8px; backdrop-filter: blur(12px); z-index: 3; }
.alert-banner[data-active="true"] { display: flex; }
.alert-banner.warn { background: rgba(234,179,8,.15); color: #fde68a; border: 1px solid rgba(234,179,8,.4); }
.alert-banner.danger { background: rgba(239,68,68,.18); color: #fecaca; border: 1px solid rgba(239,68,68,.4); }
.alert-banner button { background: none; border: 0; color: inherit; font: 600 14px var(--agent-chat-font); cursor: pointer; padding: 0 4px; opacity: .7; }
.alert-banner button:hover { opacity: 1; }
/* Rich token card unfurl rendered inline in chat */
.token-card { margin: 6px 0; padding: 10px 12px; background: rgba(0,0,0,.25); border: 1px solid rgba(255,255,255,.08); border-radius: 10px; font: 12px var(--agent-chat-font); color: var(--agent-on-surface); }
.token-card.solana { border-left: 3px solid rgba(255,255,255,0.3); }
.token-card-header { display: flex; align-items: center; gap: 8px; }
.token-card-symbol { font: 700 14px var(--agent-chat-font); }
.token-card-name { opacity: .7; }
.token-card-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 6px 12px; margin-top: 8px; }
.token-card-stat { display: flex; flex-direction: column; gap: 2px; }
.token-card-stat .label { font: 600 9px/1 var(--agent-chat-font); letter-spacing: .06em; text-transform: uppercase; opacity: .5; }
.token-card-stat .value { font: 600 13px var(--agent-chat-font); font-variant-numeric: tabular-nums; }
.token-card-bar { margin-top: 8px; height: 6px; background: rgba(255,255,255,.08); border-radius: 999px; overflow: hidden; }
.token-card-bar .fill { height: 100%; background: linear-gradient(90deg, #3b82f6, rgba(255,255,255,0.7)); transition: width .4s; }
.token-card-bar .fill.danger { background: linear-gradient(90deg, #f59e0b, #ef4444); }
.token-card .flags { display: flex; flex-wrap: wrap; gap: 4px; margin-top: 6px; }
.token-card .flag { font: 600 9px/1 var(--agent-chat-font); letter-spacing: .04em; text-transform: uppercase; padding: 3px 6px; border-radius: 4px; background: rgba(239,68,68,.18); color: #fecaca; border: 1px solid rgba(239,68,68,.32); }
.poster {
position: absolute;
inset: 0;
background-size: contain;
background-position: center;
background-repeat: no-repeat;
transition: opacity 0.4s;
pointer-events: none;
}
/* Hotspot layer: see the <slot name="hotspot"> comment in _renderShell.
The layer itself never blocks orbit-drag/click-through; only a slotted
hotspot element (positioned by _updateHotspots) takes pointer events. */
.hotspot-layer {
position: absolute;
inset: 0;
overflow: hidden;
pointer-events: none;
}
.hotspot-layer ::slotted([slot="hotspot"]) {
position: absolute;
left: 0;
top: 0;
pointer-events: auto;
}
/* Loading state — an invisible status region while the GLB streams in. The
poster image (when supplied) fills the frame; otherwise the host sees
transparent until the avatar paints. No silhouette placeholder. Kept as a
non-visual role=status region for screen readers and the loading part. */
.loading {
position: absolute;
inset: 0;
pointer-events: none;
z-index: 4;
}
.error, .agent-3d-error {
position: absolute;
inset: 16px;
display: grid;
place-items: center;
color: var(--agent-on-surface);
background: var(--agent-surface);
border-radius: 12px;
padding: 16px;
font: 14px var(--agent-chat-font);
}
.error-card {
display: flex;
flex-direction: column;
align-items: center;
text-align: center;
gap: 8px;
max-width: 260px;
animation: agent-err-in 0.3s ease both;
}
@keyframes agent-err-in {
from { opacity: 0; transform: translateY(6px); }
to { opacity: 1; transform: none; }
}
@media (prefers-reduced-motion: reduce) {
.error-card { animation: none; }
}
.error-icon {
width: 36px;
height: 36px;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
background: rgba(127, 127, 127, 0.16);
color: var(--agent-on-surface);
opacity: 0.85;
}
.error-title {
font-size: 14px;
font-weight: 600;
line-height: 1.3;
}
.error-hint {
font-size: 12.5px;
line-height: 1.45;
opacity: 0.62;
}
/* Optional name plate overlay — toggled by the name-plate attribute. */
.name-plate {
position: absolute;
left: 12px;
bottom: 10px;
z-index: 2;
pointer-events: none;
font: 11px/1 var(--agent-chat-font);
letter-spacing: 0.04em;
color: rgba(255, 255, 255, 0.6);
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.6);
}
.name-plate:empty,
:host([name-plate="off"]) .name-plate { display: none; }
/* Chat mode: the composer owns the bottom edge, so the plate reads as a
header instead, and the conversation starts below it. */
:host(:not([data-bare])) .name-plate { top: 14px; bottom: auto; left: 16px; }
:host(:not([data-bare]):not([name-plate="off"])) .chat { padding-top: 26px; }
/* Background variants — set on :host so the canvas composites over them. */
:host([background="transparent"]) { background: transparent; }
:host([background="transparent"]) .thought-bubble {
border: 1px solid rgba(0, 0, 0, 0.08);
box-shadow: 0 4px 24px rgba(0, 0, 0, 0.18), 0 1px 3px rgba(0, 0, 0, 0.12);
}
/* The floating widget sits on top of a page we do not control, and its text is
light. With no background of its own it was white-on-cream on any light site,
so floating mode defaults to the dark surface. background="transparent" or
"light" still opt out. */
:host([mode="floating"]:not([background])) { background: #0b0d10; }
:host([background="dark"]) { background: #0b0d10; }
:host([background="light"]) { background: #f5f5f5; }
:host([background="light"]) .name-plate {
color: rgba(0, 0, 0, 0.55);
text-shadow: none;
}
:host([background="light"]) .thought-bubble {
background: rgba(30, 30, 50, 0.92);
color: #f9fafb;
}
:host([background="light"]) .thought-bubble::after {
border-top-color: rgba(30, 30, 50, 0.92);
}
:host([background="light"]) .thought-bubble[data-tail-dir="up"]::after {
border-bottom-color: rgba(30, 30, 50, 0.92);
}
:host([background="light"]) .thought-bubble .text {
color: #f9fafb;
}
:host([background="light"]) .thought-bubble .dot {
background: #f9fafb;
}
/* Transparent floating: remove box chrome so avatar composites over the page */
:host([mode="floating"][background="transparent"]) {
box-shadow: none;
border-radius: 0;
overflow: visible;
}
/* Pill expanded (bottom-sheet): offset chrome below swipe handle */
:host([aria-expanded="true"]) .chrome {
padding-top: 20px;
}
/* Drag handle — visible in floating mode, used to reposition the widget */
.drag-handle {
display: none;
position: absolute;
top: 0;
left: 0;
right: 0;
height: 24px;
cursor: grab;
z-index: 15;
touch-action: none;
}
.drag-handle:active { cursor: grabbing; }
.drag-handle::after {
content: '';
position: absolute;
top: 7px;
left: 50%;
transform: translateX(-50%);
width: 32px;
height: 3px;
border-radius: 2px;
background: rgba(255,255,255,0.3);
}
:host([mode="floating"]) .drag-handle { display: block; }
/* Bare avatar (the default) — reflected as data-bare by _reflectChromeState().
Hide the dat.GUI debug panel (incl. its color-picker hue strip) and the
axes gizmo so a plain <agent-3d> is the avatar and nothing else. */
:host([data-bare]) .gui-wrap { display: none !important; }
:host([data-bare]) .gui-toggle { display: none !important; }
:host([data-bare]) .axes { display: none !important; }
/* Kiosk mode: hide dat.GUI debug controls entirely */
:host([kiosk]) .gui-wrap { display: none !important; }
:host([kiosk]) .gui-toggle { display: none !important; }
/* Model-info overlay. src/model-info.js appends it to the viewer element, but
its CSS lives in the page stylesheet (public/style.css), which a shadow root
does not inherit. Unstyled it lays out as a STATIC block below the canvas:
it overflows the element's declared height by its own ~250px and, being
hit-testable, swallows every click on whatever the host page renders under
the embed. Restore the overlay positioning here, and hide it wherever the
other debug chrome is hidden. */
.model-info {
position: absolute;
bottom: 20px;
left: 20px;
z-index: 5;
pointer-events: none;
}
:host([data-bare]) .model-info { display: none !important; }
:host([kiosk]) .model-info { display: none !important; }
:host([viewer]) .model-info { display: none !important; }
/* Remove the dat.GUI color-picker hue strip globally — the saturation/value
field carries the picker; the vertical hue knob is suppressed in-shadow too. */
.dg .cr.color .selector .hue-field,
.dg .selector .hue-field { display: none !important; }
.dg .cr.color .selector .saturation-field,
.dg .selector .saturation-field { width: 100% !important; }
/* viewer mode: pure 3D canvas, no chat / input / avatar anchor / debug.
Use when embedding the avatar as decoration (landing pages, launchpads). */
:host([viewer]) .chrome { display: none !important; }
:host([viewer]) .gui-wrap { display: none !important; }
:host([viewer]) .gui-toggle { display: none !important; }
/* avatar-chat="off" — restore original bottom-row layout, hide avatar anchor */
:host([avatar-chat="off"]) .chrome {
inset: unset;
left: 12px;
right: 12px;
bottom: 12px;
flex-direction: row;
align-items: flex-end;
padding: 0;
gap: 8px;
}
:host([avatar-chat="off"]) .chat { flex: 1; max-height: 40%; }
:host([avatar-chat="off"]) .input-row { flex: 0 0 auto; }
:host([avatar-chat="off"]) .avatar-anchor { display: none; }
/* Floating mode layout fixes */
:host([mode="floating"]) .chrome {
padding: 14px;
padding-top: 28px; /* clear the 24px drag handle */
}
:host([mode="floating"]) .avatar-anchor {
min-height: 60px;
}
/* Section mode — constrain chat width on wide containers */
:host([mode="section"]) .chat {
max-width: 600px;
}
:host([mode="section"]) .input-row {
max-width: 600px;
}
/* Fullscreen mode — centre the chrome column on large monitors */
:host([mode="fullscreen"]) .chrome {
max-width: 800px;
width: 800px;
left: 0;
right: 0;
margin: 0 auto;
}
`;
class Agent3DElement extends HTMLElement {
static get observedAttributes() {
return [
'src',
'manifest',
'body',
'agent-id',
'avatar-id',
'api-base',
'mode',
'position',
'width',
'height',
'voice',
'api-key',
'key-proxy',
'responsive',
'background',
'name-plate',
'tracked-mint',
'avatar-chat',
'avatar-walk',
'chat',
'clip',
'framing',
'wallet',
'sign-language',
'sonar',
'poster',
'ar',
'ar-modes',
'ar-placement',
'ios-src',
'variant-name',
];
}
constructor() {
super();
this.attachShadow({ mode: 'open' });
this._viewer = null;
this._scene = null;
this._runtime = null;
this._memory = null;
this._skills = null;
this._avatar = null; // empathy + lipsync layer; attached after runtime mounts
this._spokenAudio = null; // caller-supplied clip driving speakAudio()
this._manifest = null;
this._mounted = false;
this._booting = false;
// Bumped on every teardown/reboot so a stale _wirePostLoadMedia() run
// (variant parsing, USDZ generation) from a previous boot can tell it
// has been superseded and stop touching this element.
this._bootToken = 0;
this._variantController = null;
this._generatedUsdzUrl = null;
this._bodyUrl = null;
this._hotspotLayerEl = null;
this._hotspotSlotEl = null;
this._listening = false;
this._pillActive = false;
this._mqNarrow = null;
this._mqNarrowHandler = null;
this._ro = null;
this._outsideTapHandler = null;
this._detachTradeReactions = null;
this._livekitVoice = null;
this._voiceClient = null;
this._notifier = null;
this._notifyWalkCleanup = null;
this._speakWalkCleanup = null;
this._thoughtBubbleEl = null;
this._bubbleBuffer = '';
this._bubbleRafPending = false;
this._bubbleClearTimer = null;
this._isWalking = false;
this._walkStopDebounce = null;
this._walkMovedX = false;
this._walkHomeX = 0;
this._streamingMsgEl = null;
this._streamingChatBuffer = '';
this._streamingChatRafPending = false;
this._chatAutoScroll = true;
this._pendingSay = null;
// WebGL context budget bookkeeping.
this._inViewport = false;
this._lastVisibleAt = 0;
this._sonar = null; // acoustic hand control, only once startSonar() is called
// Reduced-motion bookkeeping.
this._mqReduce = null;
this._mqReduceHandler = null;
}
connectedCallback() {
this._renderShell();
this._applyLayout();
this._setupResponsive();
this._observeViewport();
this._setupReducedMotion();
// Defer boot until visible unless `eager` attr is present.
// Skip boot entirely if no source — wait for src/manifest/body/agent-id
// to be set, which triggers reboot via attributeChangedCallback.
if (this.hasAttribute('eager') && this._hasSource()) this._boot();
}
_hasSource() {
return (
this.hasAttribute('src') ||
this.hasAttribute('manifest') ||
this.hasAttribute('body') ||
this.hasAttribute('agent-id') ||
this.hasAttribute('avatar-id')
);
}
// Chrome policy — the single source of truth for "is this a full chat agent
// or just a bare avatar?". Default is BARE: a plain <agent-3d> (or one given
// only a `body`/`src`) ships the transparent 3D avatar and nothing else — no
// chat, no input, no debug GUI, no name-plate.
//
// The conversational chrome is opt-in, switched on by either:
// • the explicit `chat` attribute — the documented opt-in field, or
// • binding to a published agent identity (`agent-id` / `manifest`), which
// inherently carries a brain + persona, so it talks by default.
//
// `kiosk` / `viewer` remain explicit "force bare" escapes that win over the
// agent-binding heuristic, for embeds that want a bound agent rendered as
// pure decoration.
_isChatMode() {
// Explicit `chat` always wins, in both directions. `chat` / `chat="on"`
// forces the chat shell; `chat="off"` (or false/0/no) forces a bare
// avatar even for a bound agent — the explicit opt-out so the minimal
// transparent avatar is reachable for every kind of source.
if (this.hasAttribute('chat')) {
return !/^(off|false|0|no)$/i.test((this.getAttribute('chat') || '').trim());
}
if (this.hasAttribute('kiosk') || this.hasAttribute('viewer')) return false;
if (this.hasAttribute('agent-id') || this.hasAttribute('manifest')) return true;
// An `src` pointing at a published agent (the `agent://` scheme) is a
// bound agent too — it chats. A plain GLB/HTTPS/IPFS `src` is just a body.
return /^agent:\/\//i.test(this.getAttribute('src') || '');
}
// The base every API request of this element is built on: the `api-base`
// attribute when set, else the three.ws origin this script came from. Never
// the host page's origin unless the page IS that origin. See
// shared/embed-api-origin.js for the full resolution order.
_apiBase() {
return resolveApiBase({
attr: this.getAttribute('api-base'),
scriptOrigin: _scriptOrigin,
pageOrigin: _pageOrigin(),
});
}
// True when this element's API base is the page's own origin, i.e. the
// visitor's three.ws session cookie belongs to its requests.
_apiIsPageOrigin() {
return isPageOrigin(this._apiBase(), _pageOrigin());
}
_apiCredentials() {
return credentialsFor(this._apiBase(), _pageOrigin());
}
// Reflect the resolved chrome mode onto the host as a read-only `data-bare`
// marker. CSS keys the debug-GUI/axes hiding off it, so the default bare
// avatar shows no controls even though it carries no `kiosk`/`viewer` attr.
_reflectChromeState() {
this.toggleAttribute('data-bare', !this._isChatMode());
}
// The memory mode for this boot. `remote` and `encrypted-ipfs` store through
// the owner's three.ws session; on another site that session cannot ride
// along, so they would read nothing and fail every write. Keep the
// conversation's memory in this browser instead, and say why once.
_memoryMode(manifest) {
const requested = this.getAttribute('memory') || manifest.memory?.mode || 'local';
if ((requested === 'remote' || requested === 'encrypted-ipfs') && !this._apiIsPageOrigin()) {
log.warn(
`[agent-3d] memory="${requested}" needs the owner's three.ws session, which is not ` +
'available on this site; using memory="local" for this embed.',
);
return 'local';
}
return requested;
}
// Tear down and rebuild the entire shadow shell, then reboot. Used when the
// chat↔bare mode flips at runtime, since the two modes render different
// chrome and _renderShell is otherwise idempotent.
_rebuildShell() {
this._teardown();
this.shadowRoot.replaceChildren();
// Null cached element refs so _renderShell recreates them from scratch.
this._loadingEl = null;
this._stageEl = null;
this._posterEl = null;
this._hotspotLayerEl = null;
this._hotspotSlotEl = null;
this._nameplateEl = null;
this._chatEl = null;
this._inputEl = null;
this._micEl = null;
this._avatarAnchorEl = null;
this._thoughtBubbleEl = null;
this._thoughtTextEl = null;
this._renderShell();
this._applyLayout();
if (this._hasSource()) this._boot();
}
disconnectedCallback() {
this._teardown();
this._cleanupReducedMotion();
if (this._walletMount) {
try {
this._walletMount.destroy();
} catch {
/* already gone */
}
this._walletMount = null;
this._walletAgentId = null;
}
}
// prefers-reduced-motion lives at the element level (survives budget-driven
// teardown/reboot), so a runtime flip of the OS setting re-applies playback:
// a held static pose ↔ live motion, without a reload.
_setupReducedMotion() {
if (this._mqReduce || typeof window === 'undefined' || !window.matchMedia) return;
this._mqReduce = window.matchMedia('(prefers-reduced-motion: reduce)');
this._mqReduceHandler = () => {
if (this._mounted && this._scene && !this._isChatMode()) {
this._startDecorationPlayback();
}
};
try {
this._mqReduce.addEventListener('change', this._mqReduceHandler);
} catch {}
}
_cleanupReducedMotion() {
try {
if (this._mqReduce && this._mqReduceHandler) {
this._mqReduce.removeEventListener('change', this._mqReduceHandler);
}
} catch {}
this._mqReduce = null;
this._mqReduceHandler = null;
}
_prefersReducedMotion() {
try {
return (
this._mqReduce?.matches ??
window.matchMedia('(prefers-reduced-motion: reduce)').matches
);
} catch {
return false;
}
}
attributeChangedCallback(name, oldVal, newVal) {
// Source attribute set on a not-yet-booted (eager but no source) element
// — boot now instead of rebooting.
if (
!this._mounted &&
!this._booting &&
this.isConnected &&
['src', 'manifest', 'body', 'agent-id', 'avatar-id'].includes(name) &&
newVal
) {
this._boot();
return;
}
if (!this._mounted) return;
if (['mode', 'position', 'width', 'height', 'responsive'].includes(name))
this._applyLayout();
if (name === 'background') this._applyBackground();
if (name === 'name-plate') this._applyNamePlate();
if (name === 'poster' && this._posterEl) {
this._posterEl.style.backgroundImage = newVal ? `url(${newVal})` : '';
}
if (name === 'variant-name') this._applyVariantName();
if (['ar', 'ar-modes', 'ar-placement', 'ios-src'].includes(name)) this._refreshAR();
if (name === 'tracked-mint') {
this._detachTradeReactions?.();
this._detachTradeReactions = newVal
? attachTradeReactions(this, { mint: newVal, origin: this._apiBase() })
: null;
}
if (name === 'avatar-walk' && newVal === 'off') {
this._stopWalkAnimation();
}
if (name === 'framing') {
this._viewer?.setFraming?.(newVal === 'portrait' ? 'portrait' : 'full');
}
// Acoustic hand control is capability-gated, never auto-started: opening a
// microphone and putting a 20 kHz tone into someone's room is the viewer's
// decision, so the attribute only permits startSonar(). Removing it, or
// setting it off, stops a session already running.
if (name === 'sonar' && !this._sonarAllowed()) this.stopSonar();
// ASL replies: any value except "off"/"false" enables signing.
if (name === 'sign-language') {
const on = newVal != null && newVal !== 'off' && newVal !== 'false';
this._avatar?.setSignLanguage?.(on);
}
// Re-cue decoration playback when the requested clip changes at runtime
// (loop-honoring + reduced-motion handled by _startDecorationPlayback).
if (name === 'clip' && !this._isChatMode()) {
this._startDecorationPlayback();
}
// Toggling `chat` at runtime flips the whole chrome — rebuild the shell.
if (name === 'chat') {
this._rebuildShell();
return;
}
if (['src', 'manifest', 'body', 'agent-id', 'avatar-id'].includes(name)) {
// Source change — reboot. If the change also crosses the chat↔bare
// boundary (e.g. an `agent-id`/`manifest` was added or removed), the
// shell builds different chrome, so do a full rebuild instead.
const wantsChat = this._isChatMode();
const hasChrome = !!this._chatEl;
if (wantsChat !== hasChrome) {
this._rebuildShell();
} else {
this._teardown();
this._boot();
}
}
}
_renderShell() {
// Reflect the resolved chrome mode onto the host so CSS can hide the
// debug GUI / axes for bare avatars (the default). Runs before the
// idempotency guard so a runtime mode flip always re-reflects.
this._reflectChromeState();
if (this._loadingEl) return;
const style = document.createElement('style');
style.textContent = BASE_STYLE;
this.shadowRoot.appendChild(style);
const stage = document.createElement('div');
stage.className = 'stage';
stage.part = 'stage';
this.shadowRoot.appendChild(stage);
this._stageEl = stage;
const poster = document.createElement('div');
poster.className = 'poster';
if (this.getAttribute('poster')) {
poster.style.backgroundImage = `url(${this.getAttribute('poster')})`;
}
// Hotspot layer: a <slot name="hotspot"> over the stage. Each assigned
// light-DOM child self-describes a world position (data-position, and
// optionally data-normal) that gets projected to screen space every
// frame, and an optional saved camera view (data-camera-orbit /
// data-camera-target) that fires on click. Inserted before the poster
// so the (DOM-order-stacked) poster still covers hotspots while loading.
const hotspotLayer = document.createElement('div');
hotspotLayer.className = 'hotspot-layer';
hotspotLayer.part = 'hotspot-layer';
const hotspotSlot = document.createElement('slot');
hotspotSlot.name = 'hotspot';
hotspotLayer.appendChild(hotspotSlot);
hotspotLayer.addEventListener('click', (e) => this._onHotspotClick(e));
this.shadowRoot.appendChild(hotspotLayer);
this._hotspotLayerEl = hotspotLayer;
this._hotspotSlotEl = hotspotSlot;
this.shadowRoot.appendChild(poster);
this._posterEl = poster;
const loading = document.createElement('div');
loading.className = 'loading';
loading.part = 'loading';
loading.setAttribute('role', 'status');
loading.setAttribute('aria-label', 'Loading avatar');
loading.hidden = true;
this.shadowRoot.appendChild(loading);
this._loadingEl = loading;
// Drag handle — floating mode only (CSS hides it otherwise)
const dragHandle = document.createElement('div');
dragHandle.className = 'drag-handle';
dragHandle.setAttribute('aria-hidden', 'true');
this.shadowRoot.appendChild(dragHandle);
this._dragHandleEl = dragHandle;
// Optional name-plate overlay. Hidden until a name is set on boot, and
// toggled off entirely when the host carries `name-plate="off"`. The CSS
// hides `.name-plate:empty`, so we don't have to manage `hidden` here.
const namePlate = document.createElement('div');
namePlate.className = 'name-plate';
namePlate.part = 'name-plate';
this.shadowRoot.appendChild(namePlate);
this._nameplateEl = namePlate;
// Pill button — tap/keyboard target when floating collapses to pill on narrow viewports
const pillBtn = document.createElement('button');
pillBtn.className = 'pill-btn';
pillBtn.setAttribute('aria-label', 'Open agent');
pillBtn.addEventListener('click', () => this._expandPill());
pillBtn.addEventListener('keydown', (e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
this._expandPill();
}
});
this.shadowRoot.appendChild(pillBtn);
this._pillBtn = pillBtn;
// Drag handle shown when bottom-sheet is expanded
const pillDrag = document.createElement('div');
pillDrag.className = 'pill-drag';
this.shadowRoot.appendChild(pillDrag);
this._pillDrag = pillDrag;
// Chat + input chrome — built only in chat mode. A bare avatar (the
// default) never builds it, so there is no chat box, input row, mic, or
// thought bubble: just the transparent 3D canvas.
if (this._isChatMode()) {
const chrome = document.createElement('div');
chrome.className = 'chrome';
chrome.part = 'chrome';
const chat = document.createElement('div');
chat.className = 'chat';
chat.part = 'chat';
chat.setAttribute('tabindex', '0');
chat.setAttribute('role', 'log');
chat.setAttribute('aria-live', 'polite');
chat.setAttribute('aria-label', 'Conversation');
// Avatar anchor — transparent window between chat and input;
// the Three.js canvas shows through here. Thought bubble lives inside.
const avatarAnchor = document.createElement('div');
avatarAnchor.className = 'avatar-anchor';
const thoughtBubble = document.createElement('div');
thoughtBubble.className = 'thought-bubble';
thoughtBubble.setAttribute('role', 'status');
thoughtBubble.setAttribute('aria-live', 'polite');
thoughtBubble.setAttribute('aria-label', 'Agent is thinking');
thoughtBubble.innerHTML =
'<span class="text"></span>' +
'<span class="dot"></span><span class="dot"></span><span class="dot"></span>';
avatarAnchor.appendChild(thoughtBubble);
chat.appendChild(avatarAnchor);
chrome.appendChild(chat);
chrome.appendChild(this._buildComposer());
this.shadowRoot.appendChild(chrome);
this._chatEl = chat;
this._avatarAnchorEl = avatarAnchor;
this._thoughtBubbleEl = thoughtBubble;
this._thoughtTextEl = thoughtBubble.querySelector('.text');
// Walk when the chat is scrolling — user-initiated or auto
chat.addEventListener(
'scroll',
() => {
if (
this.getAttribute('avatar-chat') !== 'off' &&
this.getAttribute('avatar-walk') !== 'off'
) {
this._onStreamChunk();
}
},
{ passive: true },
);
// Voice state ring — wired by VoiceClient when voice-server attr is set
this.addEventListener('voiceStateChange', (e) => {
if (!this._micEl) return;
const { state } = e.detail;
this._micEl.dataset.voiceState = state;
this._micEl.title =
state === 'idle' || !state ? 'Push to talk' : 'Voice active — click to stop';
if (this.getAttribute('avatar-chat') !== 'off') {
if (state === 'speaking' || state === 'thinking') {
this._onStreamChunk();
} else if (state === 'idle') {
this._stopWalkAnimation();
}
}
if (this._thoughtBubbleEl && this.getAttribute('avatar-chat') !== 'off') {
if (state === 'speaking') {
this._thoughtBubbleEl.dataset.active = 'true';
this._thoughtBubbleEl.dataset.streaming = 'false';
} else if (state === 'idle') {
this._clearThoughtBubble();
}
}
});
// Tool-call indicator ("Checking the chain…").
const toolInd = document.createElement('div');
toolInd.className = 'tool-indicator';
toolInd.part = 'tool-indicator';
toolInd.innerHTML = '<span class="spin"></span><span class="label">Working…</span>';
this.shadowRoot.appendChild(toolInd);
this._toolIndicatorEl = toolInd;
// Sticky alert banner (rug flags etc.).
const banner = document.createElement('div');
banner.className = 'alert-banner';
banner.part = 'alert-banner';
banner.innerHTML =
'<span class="msg-text"></span><button aria-label="Dismiss">×</button>';
banner.querySelector('button').addEventListener('click', () => {
banner.dataset.active = 'false';
});
this.shadowRoot.appendChild(banner);
this._alertBannerEl = banner;
// Suggestion chips visible while the chat is empty.
this._renderSuggestions();
}
// The agent's portable wallet — works in every mode, not just chat. Opt-in
// via the `wallet` attribute so a non-wallet embed pays zero cost. Mounts as
// soon as we know the agent id (now if `agent-id` is set, else after boot
// resolves the manifest).
this._mountWalletAffordance();
}
// Mount (or re-mount) the self-contained wallet chip into the shadow root. The
// embed is the VISITOR view by construction: the portable wallet only ever
// renders Tip + "open on three.ws" — never an owner control, which only a real
// three.ws session can unlock. Re-entrant: safe to call repeatedly; it no-ops
// once mounted for the current agent and re-mounts if the agent id changes.
_mountWalletAffordance() {
if (!this.hasAttribute('wallet') || !this.shadowRoot) return;
const agentId = this.getAttribute('agent-id') || this._manifest?.id?.agentId || '';
const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
agentId,
);
if (!isUuid) return; // wait for a real id; boot will call us again
if (this._walletAgentId === agentId && this._walletMount) return;
if (this._walletMount) {
try {
this._walletMount.destroy();
} catch {
/* already gone */
}
this._walletMount = null;
this._walletHostEl?.remove();
}
const host = document.createElement('div');
host.className = 'wallet-affordance';
host.part = 'wallet-affordance';
Object.assign(host.style, {
position: 'absolute',
left: '10px',
bottom: '10px',
zIndex: '14',
maxWidth: 'calc(100% - 20px)',
});
this.shadowRoot.appendChild(host);
this._walletHostEl = host;
this._walletAgentId = agentId;
const origin = this._apiBase();
const mode = (this.getAttribute('wallet') || '').trim().toLowerCase();
import('./shared/portable-wallet.js')
.then(({ mountPortableWallet }) => {
if (!host.isConnected || this._walletAgentId !== agentId) return;
this._walletMount = mountPortableWallet(host, {
agentId,
origin,
variant: mode === 'card' ? 'card' : 'chip',
tip: mode !== 'identity', // `wallet="identity"` = read-only chip, no tip flow
name: this._manifest?.name || this.getAttribute('name') || null,
});
})
.catch(() => {
/* optional affordance, never break the viewer */
});
}
// The chat composer: a text field, a send button, and (where the browser can
// hear) a push-to-talk mic. Without it chat mode had no way to type to the
// agent at all; the only inputs were the canned suggestion chips.
_buildComposer() {
const row = document.createElement('form');
row.className = 'input-row';
row.part = 'input-row';
row.setAttribute('aria-label', 'Message the agent');
const input = document.createElement('input');
input.type = 'text';
input.placeholder = 'Say something...';
input.autocomplete = 'off';
input.enterKeyHint = 'send';
input.maxLength = 2000;
input.setAttribute('aria-label', 'Message to agent');
input.part = 'input';
const send = document.createElement('button');
send.type = 'submit';
send.className = 'icon send';
send.title = 'Send';
send.setAttribute('aria-label', 'Send message');
send.innerHTML =
'<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
'<path d="M5 12h14"></path><path d="M13 6l6 6-6 6"></path></svg>';
row.addEventListener('submit', (e) => {
e.preventDefault();
const text = input.value.trim();
if (!text || input.disabled) return;
input.value = '';
this._onStreamChunk(); // immediate visual feedback before the LLM responds
this.say(text);
});
row.appendChild(input);
if (this._speechInputAvailable()) row.appendChild(this._createMicButton());
row.appendChild(send);
this._inputEl = input;
return row;
}
// Names the agent once it is known, so the field reads as a conversation
// with someone rather than a generic text box.
_composerPlaceholder() {
const name = (this._manifest?.name || '').trim();
return name && name !== 'Agent' ? `Message ${name}…` : 'Say something...';
}
_createMicButton() {
const mic = document.createElement('button');
mic.type = 'button';
mic.className = 'icon mic';
mic.title = 'Push to talk';
mic.setAttribute('aria-label', 'Push to talk');
mic.innerHTML =
'<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="3" width="6" height="11" rx="3"></rect>' +
'<path d="M5 11a7 7 0 0 0 14 0"></path><path d="M12 18v3"></path></svg>';
mic.addEventListener('click', () => this._toggleMic());
this._micEl = mic;
return mic;
}
// The composer is built before the manifest is known, so an agent whose STT
// runs on-device (manifest voice.stt.provider "whisper") gets its mic here,
// once the runtime exists. That is what gives Firefox and Safari visitors push
// to talk: they have no browser recognizer for _speechInputAvailable to find.
_ensureOnDeviceMic() {
if (this._micEl || !this._inputEl?.parentElement) return;
if (typeof this._runtime?.stt?.warm !== 'function') return;
this._inputEl.after(this._createMicButton());
}
// Reflect what the recognizer is doing on the mic, so a first-use model
// download or a slow decode reads as progress instead of a frozen button.
_renderSttStatus(status) {
const mic = this._micEl;
if (!mic) return;
const phase = status?.phase;
if (phase === 'loading-model') {
const pct = Number.isFinite(status.progress) ? ` ${Math.round(status.progress * 100)}%` : '';
mic.dataset.voiceState = 'thinking';
mic.title = `Loading the on-device speech model${pct}`;
} else if (phase === 'transcribing') {
mic.dataset.voiceState = 'thinking';
mic.title = 'Transcribing';
} else if (phase === 'listening') {
mic.dataset.voiceState = 'listening';
const dl = Number.isFinite(status.modelProgress)
? `, speech model ${Math.round(status.modelProgress * 100)}% downloaded`
: '';
mic.title = `Listening${dl}. Click to stop`;
} else {
delete mic.dataset.voiceState;
mic.title = 'Push to talk';
}
mic.setAttribute('aria-label', mic.title);
}
// Push-to-talk works through a voice server or the browser's own speech
// recognition. Where neither exists the mic would be a dead button.
_speechInputAvailable() {
if (this.getAttribute('voice-server')) return true;
if (typeof window === 'undefined') return false;
return Boolean(window.SpeechRecognition || window.webkitSpeechRecognition);
}
_renderSuggestions() {
if (!this._chatEl) return;
const existing = this._chatEl.querySelector('.suggest-row');
if (existing) existing.remove();
const row = document.createElement('div');
row.className = 'suggest-row';
const chips = this._suggestionChips();
for (const c of chips) {
const btn = document.createElement('button');
btn.className = 'suggest-chip';
btn.textContent = c.label;
btn.addEventListener('click', () => {
row.remove();
this.say(c.prompt);
});
row.appendChild(btn);
}
this._chatEl.appendChild(row);
}
_suggestionChips() {
// Tailor the chip set to which skills are installed; fall back to a
// generic greeting set otherwise. Skill names come from the manifest,
// not the registry, so this works even before runtime boot.
const installed = new Set(
(this._manifest?.skills || []).map((s) => {
if (typeof s === 'string') return s.replace(/\/$/, '').split('/').pop();
if (s?.id) return s.id;
if (s?.uri) return String(s.uri).replace(/\/$/, '').split('/').pop();
return '';
}),
);
const chips = [];
if (installed.has('pump-fun')) {
chips.push(
{
label: '🔥 Trending now',
prompt: 'What are the trending tokens on pump.fun right now?',
},
{ label: '👑 King of the hill', prompt: "Who's the king of the hill on pump.fun?" },
{ label: '🆕 New launches', prompt: 'Show me the newest pump.fun launches.' },
);
}
if (installed.has('dca')) {
chips.push({
label: '💸 Set up DCA',
prompt: 'Help me set up a weekly USDC → WETH DCA.',
});
}
if (chips.length === 0) {
chips.push(
{ label: '👋 Say hi', prompt: 'Hi! Who are you?' },
{ label: '🎬 Show your animations', prompt: 'What animations can you do?' },
);
}
return chips.slice(0, 4);
}
_isResponsive() {
// Default on; opt out with responsive="false"
return this.getAttribute('responsive') !== 'false';
}
_clampWidth(val) {
const px = _parsePx(val);
if (!px) return val;
const min = Math.round(Math.max(160, px * 0.65));
const vwPct = Math.round((px / 1440) * 100);
return `clamp(${min}px, ${vwPct}vw, ${px}px)`;
}
/**
* Apply the `background` attribute. Mirrors the iframe embed semantics so
* the snippet builder's options translate cleanly: 'transparent' → renderer
* clears with alpha=0 and the scene background is unset; 'dark' / 'light'
* are keyword shortcuts for canonical colors; any other value is treated as
* a literal CSS color (e.g. a hex from a custom color picker) so the scene
* composites over it. Painting goes through the viewer's public
* setBackgroundColor()/updateBackground() so clear-color, environment, and
* the cached THREE.Color stay in sync — the host element's CSS background is
* also set inline for the keyword-less case (the `:host([background="..."])`
* rules in BASE_STYLE only cover the keywords).
*
* Safe to call before the viewer exists — it no-ops in that case and is
* re-run automatically once `_boot()` constructs the viewer.
*/
_applyBackground() {
const v = this._viewer;
if (!v) return;
const mode = this.getAttribute('background') || 'transparent';
if (!v.scene) return;
if (mode === 'transparent') {
if (v.state) v.state.transparentBg = true;
v.scene.background = null;
v.renderer?.setClearAlpha?.(0);
this.style.removeProperty('background-color');
} else {
if (v.state) v.state.transparentBg = false;
v.renderer?.setClearAlpha?.(1);
// scene.background may be null (was transparent) — ensure a Color to mutate.
if (!v.scene.background || typeof v.scene.background.set !== 'function') {
v.scene.background = v.backgroundColor || new Color();
}
if (mode === 'dark') {
v.scene.background.set('#0b0d10');
this.style.backgroundColor = '#0b0d10';
} else if (mode === 'light') {
v.scene.background.set('#f5f5f5');
this.style.backgroundColor = '#f5f5f5';
} else {
v.scene.background.set(mode);
this.style.backgroundColor = mode;
}
}
v.invalidate?.();
}
/**
* Apply the `name-plate` attribute. Visibility is purely CSS-driven via
* `:host([name-plate="off"])`, so this method only needs to ensure the
* element exists in the shadow DOM (it does, see `_renderShell`).
*
* Kept as a separate method so attributeChangedCallback has a clear hook,
* and so future changes to plate position/style stay localised here.
*/
_applyNamePlate() {
// CSS handles visibility via the `name-plate="off"` host selector.
// Method exists so the attribute observer has a hook + future-proofing.
}
/** Update the plate text. Empty string hides the plate (`.name-plate:empty`). */
_setNamePlateText(name) {
if (!this._nameplateEl) return;
this._nameplateEl.textContent = name || '';
}
_clampHeight(val) {
const px = _parsePx(val);
if (!px) return val;
const min = Math.round(Math.max(200, px * 0.65));
const vhPct = Math.round((px / 900) * 100);
return `clamp(${min}px, ${vhPct}vh, ${px}px)`;
}
_applyLayout() {
const mode = this.getAttribute('mode') || 'inline';
if (!MODES.includes(mode)) return;
const responsive = this._isResponsive();
if (mode === 'floating') {
if (!this._pillActive) {
const pos = this.getAttribute('position') || 'bottom-right';
const offset = (this.getAttribute('offset') || '24px 24px').split(/\s+/);
const [vOff, hOff] = [offset[0], offset[1] || offset[0]];
this.style.top = this.style.bottom = this.style.left = this.style.right = '';
if (pos.includes('top')) this.style.top = vOff;
else this.style.bottom = vOff;
if (pos.includes('left')) this.style.left = hOff;
else if (pos.includes('right')) this.style.right = hOff;
else if (pos.includes('center')) {
this.style.left = '50%';
this.style.transform = 'translateX(-50%)';
}
}
const width = this.getAttribute('width') || '320px';
const height = this.getAttribute('height') || '420px';
this.style.setProperty('--agent-width', responsive ? this._clampWidth(width) : width);
this.style.setProperty(
'--agent-height',
responsive ? this._clampHeight(height) : height,
);
} else {
this.style.top =
this.style.bottom =
this.style.left =
this.style.right =
this.style.transform =
'';
const width = this.getAttribute('width');
const height = this.getAttribute('height');
if (mode === 'inline') {
if (width) this.style.width = responsive ? this._clampWidth(width) : width;
if (height) {
this.style.height = height;
this.removeAttribute('data-responsive');
} else if (responsive && width) {
// No explicit height: aspect-ratio preserves 3:4 portrait via CSS
this.style.height = '';
this.setAttribute('data-responsive', '');
}
}
if (width)
this.style.setProperty(
'--agent-width',
responsive ? this._clampWidth(width) : width,
);
if (height)
this.style.setProperty(
'--agent-height',
responsive ? this._clampHeight(height) : height,
);
}
}
_setupResponsive() {
const mode = this.getAttribute('mode') || 'inline';
// ResizeObserver on this — reacts to container changes without a viewport listener
if (mode === 'inline' && typeof ResizeObserver !== 'undefined') {
this._ro = new ResizeObserver(() => this._applyLayout());
this._ro.observe(this);
}
// matchMedia for floating pill collapse at narrow viewports
if (mode === 'floating' && this._isResponsive() && typeof window !== 'undefined') {
this._mqNarrow = window.matchMedia('(max-width: 479px)');
this._mqNarrowHandler = (e) => this._updatePillState(e.matches);
this._mqNarrow.addEventListener('change', this._mqNarrowHandler);
this._updatePillState(this._mqNarrow.matches);
}
// Free drag for floating mode
if (mode === 'floating') this._setupDrag();
// Swipe-down to close the bottom-sheet (CSS transitions handle the animation)
let touchStartY = 0;
this.shadowRoot.addEventListener(
'touchstart',
(e) => {
touchStartY = e.touches[0].clientY;
},
{ passive: true },
);
this.shadowRoot.addEventListener(
'touchend',
(e) => {
const dy = e.changedTouches[0].clientY - touchStartY;
if (dy > 60 && this._pillActive && this.getAttribute('aria-expanded') === 'true') {
this._collapsePill();
}
},
{ passive: true },
);
}
_setupDrag() {
if (!this._dragHandleEl) return;
let dragging = false;
let startX, startY, startLeft, startTop;
const onPointerMove = (e) => {
if (!dragging) return;
const dx = e.clientX - startX;
const dy = e.clientY - startY;
const w = this.offsetWidth;
const h = this.offsetHeight;
const newLeft = Math.max(0, Math.min(window.innerWidth - w, startLeft + dx));
const newTop = Math.max(0, Math.min(window.innerHeight - h, startTop + dy));
this.style.left = newLeft + 'px';
this.style.top = newTop + 'px';
};
const onPointerUp = () => {
if (!dragging) return;
dragging = false;
document.removeEventListener('pointermove', onPointerMove);
document.removeEventListener('pointerup', onPointerUp);
};
this._dragHandleEl.addEventListener('pointerdown', (e) => {
e.preventDefault();
dragging = true;
const rect = this.getBoundingClientRect();
startX = e.clientX;
startY = e.clientY;
startLeft = rect.left;
startTop = rect.top;
// Switch to top/left so drag math works correctly
this.style.right = '';
this.style.bottom = '';
this.style.left = startLeft + 'px';
this.style.top = startTop + 'px';
this.style.transform = '';
document.addEventListener('pointermove', onPointerMove);
document.addEventListener('pointerup', onPointerUp);
});
}
_updatePillState(narrow) {
if (narrow && !this._pillActive) {
this._pillActive = true;
this._collapsePill();
} else if (!narrow && this._pillActive) {
this._pillActive = false;
this._restoreFromPill();
}
}
_collapsePill() {
this.style.width = '56px';
this.style.height = '56px';
this.style.borderRadius = '50%';
this.setAttribute('aria-expanded', 'false');
this._pillBtn.style.display = 'block';
this._pillDrag.style.display = 'none';
const chrome = this.shadowRoot.querySelector('.chrome');
if (chrome) chrome.style.display = 'none';
this._stageEl.style.display = 'none';
if (this._outsideTapHandler) {
document.removeEventListener('pointerdown', this._outsideTapHandler);
this._outsideTapHandler = null;
}
}
_expandPill() {
if (!this._pillActive) return;
this.style.width = '100vw';
this.style.height = '70vh';
this.style.borderRadius = '16px 16px 0 0';
this.style.bottom = '0';
this.style.top = 'auto';
this.style.left = '0';
this.style.right = '0';
this.style.transform = 'none';
this.setAttribute('aria-expanded', 'true');
this._pillBtn.style.display = 'none';
this._pillDrag.style.display = 'block';
const chrome = this.shadowRoot.querySelector('.chrome');
if (chrome) chrome.style.display = '';
this._stageEl.style.display = '';
// Close on outside tap
this._outsideTapHandler = (e) => {
if (!e.composedPath().includes(this)) this._collapsePill();
};
setTimeout(() => document.addEventListener('pointerdown', this._outsideTapHandler), 0);
}
_restoreFromPill() {
this.removeAttribute('aria-expanded');
this._pillBtn.style.display = 'none';
this._pillDrag.style.display = 'none';
const chrome = this.shadowRoot.querySelector('.chrome');
if (chrome) chrome.style.display = '';
this._stageEl.style.display = '';
// Clear pill inline overrides, re-apply proper floating layout
this.style.width = this.style.height = this.style.borderRadius = '';
this.style.bottom =
this.style.top =
this.style.left =
this.style.right =
this.style.transform =
'';
this._applyLayout();
if (this._outsideTapHandler) {
document.removeEventListener('pointerdown', this._outsideTapHandler);
this._outsideTapHandler = null;
}
}
_observeViewport() {
if (this.hasAttribute('eager')) {
// Eager viewers boot immediately and are never released by the budget;
// treat them as permanently in-viewport so they sort to the top.
this._inViewport = true;
this._lastVisibleAt = _nowMs();
return;
}
if (typeof IntersectionObserver === 'undefined') {
this._inViewport = true;
this._boot();
return;
}
if (this._io) return;
// Persistent observer (not disconnected after first boot): it both lazily
// boots the viewer and tracks visibility so the context budget can evict
// the least-recently-visible offscreen viewer and re-boot it on return.
// The 300px margin gives lead time to boot before the avatar is on screen
// and damps thrash at the viewport edge.
this._io = new IntersectionObserver(
(entries) => {
const isVis = entries.some((e) => e.isIntersecting);
this._inViewport = isVis;
if (isVis) {
this._lastVisibleAt = _nowMs();
if (!this._mounted && !this._booting) this._boot();
}
},
{ rootMargin: '300px 0px' },
);
this._io.observe(this);
}
// Eligible for budget eviction only when offscreen and not holding live
// state a user would lose (voice, an open chat pill, an eager/keep-alive
// pin). Whatever is on screen or mid-conversation is always spared.
_isEvictable() {
return (
this._mounted &&
!this._inViewport &&
!this.hasAttribute('eager') &&
!this.hasAttribute('keep-alive') &&
!this._hasActiveSession()
);
}
_hasActiveSession() {
return !!(this._livekitVoice || this._voiceClient || this._listening || this._pillActive);
}
_releaseForBudget() {
if (!this._mounted) return;
this._teardown(); // disposes the viewer → frees the WebGL context(s)
this._io = null; // _teardown disconnected it; re-arm a fresh observer
this._observeViewport(); // re-boots automatically when scrolled back in
}
async _boot() {
if (this._booting || this._mounted) return;
this._bootToken++;
this._renderShell();
this._booting = true;
try {
this._loadingEl.hidden = false;
this._emit('agent:load-progress', { phase: 'manifest', pct: 0.1 });
const manifest = await this._resolveManifest();
this._manifest = manifest;
this._emit('agent:load-progress', { phase: 'manifest', pct: 0.3 });
// Hydrate instructions.md if referenced
if (
typeof manifest.brain?.instructions === 'string' &&
manifest.brain.instructions.endsWith('.md')
) {
const text = await fetchRelative(manifest, manifest.brain.instructions);
if (text) manifest.instructions = stripFrontmatter(text);
} else if (manifest.brain?.instructions) {
manifest.instructions = manifest.brain.instructions;
}
// Embed-policy surface + origin gate (fail-open on infra errors)
const _backendId = (() => {
const a = this.getAttribute('agent-id') || manifest.id?.agentId || '';
return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(a)
? a
: null;
})();
// Now that the manifest resolved the real agent id, the wallet affordance
// (if opted in via the `wallet` attribute) can hydrate against it.
this._mountWalletAffordance();
if (_backendId) {
try {
const _policyBase = this._apiBase();
const _pr = await fetch(
`${_policyBase}/api/agents/${_backendId}/embed-policy`,
{ credentials: 'omit' },
);
if (_pr.ok) {
const { policy } = await _pr.json();
if (policy) {
if (policy.surfaces?.script === false) {
this._fail(
'embed_denied_surface',
'This agent disallows the script-tag embed.',
);
return;
}
const _fp = ['three.ws', 'localhost'];
const _host = window.location.origin;
if (
!_host.startsWith('http://localhost') &&
!originAllowed(_host, policy, _fp)
) {
this._fail(
'embed_denied_origin',
`This agent isn't permitted on ${_host}.`,
);
return;
}
}
}
} catch (_e) {
log.warn('[agent-3d] embed-policy fetch failed; continuing', _e);
}
}
// Build Viewer
this._emit('agent:load-progress', { phase: 'body', pct: 0.45 });
// Bare avatars run the viewer in kiosk mode: GUI closed, camera snapped
// (no fly-in), and a lower DPR cap — the right profile for a lightweight
// decoration avatar. Chat agents get the full interactive viewer.
// The stage stays hidden until the body holds its first pose; see
// _startInitialPlayback.
this._stageEl.classList.add('is-settling');
const viewer = new Viewer(this._stageEl, {
// Never mount the editor's debug GUI or clip panel inside the
// element: their styles live in the site stylesheet, not here.
embed: true,
kiosk: !this._isChatMode(),
framing: this.getAttribute('framing') === 'portrait' ? 'portrait' : 'full',
});
this._viewer = viewer;
viewer._afterAnimateHooks = viewer._afterAnimateHooks || [];
viewer._afterAnimateHooks.push(() => this._updateBubblePosition());
viewer._afterAnimateHooks.push(() => this._updateHotspots());
// Apply the embed surface attributes (`background`, `name-plate`) now
// that the viewer exists. They are also re-applied on attribute change.
// A bare avatar carries no name-plate unless the embedder asks for one.
this._applyBackground();
this._setNamePlateText(this._isChatMode() ? manifest.name || '' : '');
if (this._inputEl) this._inputEl.placeholder = this._composerPlaceholder();
this._applyNamePlate();
// Fetch animation defs before viewer.load so _setupAnimationPanel
// can preload idle+walk during the model load.
const _animBase = this._apiBase();
try {
const _animRes = await fetch(`${_animBase}/animations/manifest.json`);
if (_animRes.ok) {
const _defs = await _animRes.json();
// Clip URLs in the manifest are root-relative (`/animations/clips/x.json`).
// Fetched verbatim they resolve against the *host page* origin, so when
// <agent-3d> is embedded cross-origin (e.g. on a partner's domain) every
// clip 404s. Rebase each onto the bundle's own origin — where the clips
// actually live, co-located with the manifest we just loaded — so gestures
// play anywhere the tag is dropped in.
if (Array.isArray(_defs)) {
for (const _d of _defs) {
if (_d && typeof _d.url === 'string') {
try {
_d.url = new URL(_d.url, _animBase).href;
} catch {}
}
}
}
viewer.setAnimationDefs(_defs);
}
} catch {}
// Every gateway that can serve this body, in order. A single baked-in
// gateway (ipfs.io rate-limits browsers routinely) used to leave a
// third-party embed with a name and no avatar and no way to recover.
const bodyCandidates = uriCandidates(manifest.body?.uri);
let loadedCandidate = null;
let loadedGltf = null;
let usedFallbackBody = false;
if (bodyCandidates.length) {
let bodyErr;
let loaded = false;
for (const candidate of bodyCandidates) {
try {
loadedGltf = await viewer.load(candidate, '', new Map());
loadedCandidate = candidate;
loaded = true;
break;
} catch (err) {
bodyErr = err;
if (candidate !== bodyCandidates[bodyCandidates.length - 1]) {
console.warn(
'[agent-3d] body load failed on %s, trying the next gateway',
candidate,
);
}
}
}
// Every gateway for the real body failed. The local default avatar
// (bundled, same-origin, no R2/IPFS dependency) gets one try before
// giving up outright, so an object-storage outage degrades to a
// placeholder body instead of a dead viewer. Skipped when the real
// body candidates already included the default (nothing new to try).
if (!loaded && !bodyCandidates.includes(DEFAULT_AVATAR_GLB)) {
try {
loadedGltf = await viewer.load(DEFAULT_AVATAR_GLB, '', new Map());
loadedCandidate = DEFAULT_AVATAR_GLB;
loaded = true;
usedFallbackBody = true;
console.warn(
'[agent-3d] body load failed on %s, falling back to the default avatar',
bodyCandidates[bodyCandidates.length - 1],
);
} catch {
// Fallback also failed; the original error is the useful one.
}
}
if (!loaded)
throw bodyErr || new Error('avatar body could not be loaded from any gateway');
if (usedFallbackBody) {
this._emit(
'agent:body-fallback',
{ uri: bodyCandidates[bodyCandidates.length - 1], fallbackUri: DEFAULT_AVATAR_GLB },
{ bubbles: true, composed: true },
);
}
// Ensure walk + idle are hot before the first brain:stream fires.
// setAnimationDefs above registered the defs; ensureLoaded now
// actually fetches the clips (or returns immediately if cached).
const _am = viewer.animationManager;
if (_am) {
await Promise.allSettled([_am.ensureLoaded('idle'), _am.ensureLoaded('walk')]);
}
// After the reveal tween completes, shift the orbital target upward
// so the avatar's upper body fills the chat shell's avatar-anchor
// window rather than the full canvas height. Chat mode only: a bare
// avatar has no anchor window, and the nudge tilted its camera up by
// 12% of the body height, which in any frame wider than 3:4 (where
// the height fit is tight) pushed the feet out of the bottom edge.
// Also skipped under `framing="portrait"`, where setContent already
// places the head-to-mid-thigh crop and an extra nudge would fight it.
if (this._isChatMode() && this.getAttribute('framing') !== 'portrait') {
const _v = viewer;
const _nudge = () => {
if (_v._cameraTweenRaf) {
requestAnimationFrame(_nudge);
return;
}
if (!_v.controls || !_v.content || _v._disposed) return;
const box = new Box3().setFromObject(_v.content);
const h = box.max.y - box.min.y;
const mid = (box.max.y + box.min.y) / 2;
_v.controls.target.set(0, mid + h * 0.12, 0);
_v.controls.update();
_v.invalidate();
};
requestAnimationFrame(_nudge);
}
}
if (loadedGltf && loadedCandidate) {
this._bodyUrl = loadedCandidate;
// Fire-and-forget: variant parsing and AR/USDZ generation are
// progressive enhancements that must never hold up agent:ready.
this._wirePostLoadMedia(loadedCandidate, loadedGltf, this._bootToken);
}
this._scene = new SceneController(viewer);
// Initial playback. Chat avatars idle-loop (then walk on stream); bare
// decoration avatars honor the `clip` attribute, the clip's manifest
// loop flag, and prefers-reduced-motion via _startDecorationPlayback.
// `bodyCandidates` is the loaded body's gateway list. This read used to
// name a variable that only exists in manifest.js, so every boot that
// reached this line threw "bodyURI is not defined" and the element
// showed its error overlay instead of the avatar. eslint knew (no-undef),
// but it was a warning, so nothing stopped it shipping.
if (bodyCandidates.length) await this._startInitialPlayback();
this._stageEl.classList.remove('is-settling');
// Memory
this._emit('agent:load-progress', { phase: 'memory', pct: 0.6 });
const memoryNamespace =
manifest.id?.agentId || this.getAttribute('memory-key') || manifest.name || 'anon';
this._memory = await Memory.load({
mode: this._memoryMode(manifest),
namespace: memoryNamespace,
manifestURI: manifest._baseURI + 'manifest.json',
fetchFn: fetch.bind(globalThis),
apiOrigin: this._apiBase(),
});
// Pull backend memories into the shared AgentMemory localStorage store
// before the first LLM turn so cross-device memory is present on init.
// Those memories are owner-only and read through the visitor's three.ws
// session, which only exists on three.ws itself: from any other site
// the request could only ever come back empty, so it is not made.
if (_backendId && this._apiIsPageOrigin()) {
const { AgentMemory } = await import('./agent-memory.js');
const syncMem = new AgentMemory(_backendId, {
backendSync: true,
apiOrigin: this._apiBase(),
});
await syncMem.pull(_backendId).catch(() => {});
}
// Skills
this._emit('agent:load-progress', { phase: 'skills', pct: 0.75 });
this._skills = new SkillRegistry({
trust: this.getAttribute('skill-trust') || 'owned-only',
ownerAddress: manifest.id?.owner,
// Bundles from the page itself or from the origin that served this
// library may run on the main thread; any other origin is sandboxed.
mainThreadOrigins: [_pageOrigin(), _scriptOrigin].filter(Boolean),
});
const skillList = manifest.skills || [];
for (const entry of skillList) {
// A string entry that points at a hosted bundle is a skill the owner
// accepted from the dashboard's Suggested skills list
// (/api/agents/:id/skill-candidates/:cid/bundle/). Other strings are
// built-in skill names, registered through AgentSkills.
const spec =
typeof entry === 'string' && /\/skill-candidates\/[^/]+\/bundle\/?$/.test(entry)
? { uri: entry.startsWith('/') ? `${this._apiBase()}${entry}` : entry }
: entry;
// Built-in skills (referenced by name only, no bundle URI) are
// registered through AgentSkills, not the remote SkillRegistry.
if (!spec || !spec.uri) continue;
try {
const skill = await this._skills.install(spec, {
bundleBase: manifest._baseURI,
});
this._emit('skill:loaded', { name: skill.name, uri: skill.uri });
} catch (e) {
log.warn('[agent-3d] skill load failed', spec, e);
}
}
// Runtime
this._emit('agent:load-progress', { phase: 'brain', pct: 0.9 });
const providerConfig = {
apiKey: this.getAttribute('api-key') || undefined,
proxyURL: this.getAttribute('key-proxy') || undefined,
agentId: _backendId || undefined,
apiOrigin: this._apiBase(),
};
// Fetch skill prices + purchased state so the runtime can gate paid skills.
// Failures here fall back to "all-allowed" — monetization is opt-in.
let _skillAccess;
if (_backendId) {
try {
// On somebody else's site our cookies are third-party and the public
// answer is all an embed can use, so only send them on our own origin.
const r = await fetch(`${this._apiBase()}/api/agents/${_backendId}/skill-access`, {
credentials: this._apiCredentials(),
});
if (r.ok) {
const a = (await r.json())?.data;
if (a && (a.skill_prices || a.purchased_skills)) {
_skillAccess = skillAccessFromAgentDetail(a);
}
}
} catch (e) {
log.warn('[agent-3d] skill-access fetch failed; defaulting to allow-all', e);
}
}
this._runtime = new Runtime({
manifest,
viewer: this._scene,
memory: this._memory,
skills: this._skills,
providerConfig,
agentId: _backendId || undefined,
skillAccess: _skillAccess,
});
this._ensureOnDeviceMic();
// ── Empathy + lipsync layer ───────────────────────────────────────
// AgentAvatar subscribes to the agent-protocol bus, runs the emotion
// blend on the viewer's per-frame hook, and drives viseme morphs from
// the live TTS AnalyserNode when audio plays. Without this the embed
// would render the mesh but show a dead face while speaking.
try {
const _identity = { id: manifest.id?.agentId || manifest.name || 'embed' };
this._avatar = new AgentAvatar(this._viewer, protocol, _identity);
this._avatar.attach();
// Per-agent gesture bindings from the manifest (meta.edits.animations
// on the record, `animationSlots` on the wire). Without this the
// override map was unreachable: every agent played the platform
// defaults no matter what its owner had saved.
const _slots = manifest.animationSlots || manifest.meta?.edits?.animations;
if (_slots && typeof _slots === 'object') this._avatar.setAnimationMap(_slots);
// Saved gesture routines, same path: on the wire as `choreographies`,
// on the record at meta.choreographies. Registering them here is what
// makes `el.playRoutine('welcome')` resolve by name.
const _routines = manifest.choreographies || manifest.meta?.choreographies;
if (Array.isArray(_routines)) this._avatar.setChoreographies(_routines);
this._applyPendingRoutine();
// Honor a sign-language attribute present at boot (the observer
// only covers post-mount changes).
const signAttr = this.getAttribute('sign-language');
if (signAttr != null && signAttr !== 'off' && signAttr !== 'false') {
this._avatar.setSignLanguage(true);
}
// Apply any mood set before the empathy layer existed so the avatar
// boots straight into its current resting expression.
if (this._pendingMood) {
this._avatar.setMood(this._pendingMood.valence, this._pendingMood.arousal, {
reducedMotion: this._pendingMood.reducedMotion,
});
}
if (this._runtime.tts) {
const tts = this._runtime.tts;
const avatar = this._avatar;
tts.onStart = () => {
if (tts.analyserNode) avatar.connectLipSync(tts.analyserNode);
};
tts.onEnd = () => {
avatar.disconnectLipSync();
};
}
} catch (e) {
// Empathy is non-essential — embed still works without it. Log so
// integrators can see the failure during development.
log.warn(
'[agent-3d] AgentAvatar attach failed; continuing without empathy/lipsync',
e,
);
this._avatar = null;
}
// Re-dispatch runtime events on the host
for (const ev of [
'brain:thinking',
'brain:stream',
'brain:message',
'skill:tool-start',
'skill:tool-called',
'skill:payment-required',
'voice:speech-start',
'voice:speech-end',
'voice:transcript',
'voice:listen-start',
'voice:listen-end',
'voice:stt-status',
'memory:write',
]) {
this._runtime.addEventListener(ev, (e) => {
this._emit(ev, e.detail, { bubbles: true, composed: true });
if (ev === 'brain:message') {
// Transfer sentiment from the most recent tool call to
// this assistant message so the bubble tints correctly.
const detail = { ...e.detail };
if (
detail.role === 'assistant' &&
detail.sentiment === undefined &&
this._lastToolSentiment !== undefined
) {
detail.sentiment = this._lastToolSentiment;
this._lastToolSentiment = undefined;
}
if (detail.role === 'assistant' && detail.content) {
protocol.emit({
type: ACTION_TYPES.SPEAK,
payload: { text: detail.content, sentiment: detail.sentiment ?? 0 },
});
}
if (detail.role === 'assistant') {
this._streamingMsgEl?.closest('.msg')?.remove();
this._streamingMsgEl = null;
this._streamingChatBuffer = '';
this._streamingChatRafPending = false;
this._clearThoughtBubble();
}
if (this._chatEl) this._renderMessage(detail);
}
if (ev === 'voice:listen-start') {
// The mic opened for this turn (generic STT loop in runtime/index.js).
// Route through the protocol bus so AgentAvatar's _onListenStart
// drives the same attentive gaze + backchannel nod cadence the
// LiveKit realtime voice path already triggers from its own VAD.
protocol.emit({ type: ACTION_TYPES.LISTEN_START, payload: {} });
}
if (ev === 'voice:listen-end') {
protocol.emit({ type: ACTION_TYPES.LISTEN_END, payload: {} });
}
if (ev === 'brain:stream') {
if (this._thoughtBubbleEl && this.getAttribute('avatar-chat') !== 'off') {
this._streamToBubble(e.detail?.chunk ?? '');
}
this._appendStreamChunkToChat(e.detail?.chunk ?? '');
this._onStreamChunk();
}
if (ev === 'brain:thinking') {
const isThinking = !!e.detail?.thinking;
this._setBusy(isThinking);
if (this._toolIndicatorEl) {
if (e.detail?.thinking) this._setToolIndicator('thinking');
else this._clearToolIndicator();
}
protocol.emit({
type: ACTION_TYPES.THINK,
payload: { thought: 'processing your message...' },
});
protocol.emit({
type: ACTION_TYPES.EMOTE,
payload: { trigger: 'patience', weight: 0.5 },
});
if (this._thoughtBubbleEl && this.getAttribute('avatar-chat') !== 'off') {
if (e.detail?.thinking) {
this._thoughtBubbleEl.dataset.active = 'true';
// Show "Thinking..." text immediately
this._thoughtBubbleEl.dataset.streaming = 'true';
if (this._thoughtTextEl)
this._thoughtTextEl.textContent = 'Thinking...';
} else {
this._clearThoughtBubble();
}
}
}
if (ev === 'skill:tool-start') {
this._onStreamChunk();
if (this._thoughtBubbleEl && this.getAttribute('avatar-chat') !== 'off') {
const label = this._toolIndicatorLabel(e.detail?.tool ?? '');
this._thoughtBubbleEl.dataset.active = 'true';
this._thoughtBubbleEl.dataset.streaming = 'true';
if (this._thoughtTextEl) this._thoughtTextEl.textContent = label;
}
}
if (ev === 'voice:speech-start') {
this._onStreamChunk();
if (this._thoughtBubbleEl && this.getAttribute('avatar-chat') !== 'off') {
const text = e.detail?.text || '';
this._streamToBubble('');
this._thoughtBubbleEl.dataset.streaming = 'true';
this._thoughtBubbleEl.dataset.active = 'true';
if (this._thoughtTextEl)
this._thoughtTextEl.textContent = text.slice(0, 80);
}
}
if (ev === 'voice:speech-end') {
this._stopWalkAnimation();
this._clearThoughtBubble();
}
if (ev === 'skill:tool-called') {
const { tool, result } = e.detail || {};
this._setToolIndicator(tool);
this._clearToolIndicator();
if (this._thoughtTextEl) this._thoughtTextEl.textContent = '';
if (this._thoughtBubbleEl)
this._thoughtBubbleEl.dataset.streaming = 'false';
if (typeof result?.sentiment === 'number') {
this._lastToolSentiment = result.sentiment;
}
this._renderToolCallCard({ tool, result });
}
});
}
this._mounted = true;
// Join the live-viewer set and evict an offscreen viewer if this boot
// pushed us over the WebGL context budget.
this._lastVisibleAt = _nowMs();
_trackLiveViewer(this);
// ── Skill payment ─────────────────────────────────────────────────
// When a paid skill is invoked, render an inline payment chip inside
// the chat thread (no blocking overlay) and narrate before/after via
// the agent protocol. Falls back to the full modal when there is no
// chat thread (e.g. avatar-only embed with avatar-chat="off").
if (_backendId && this.shadowRoot) {
const _payOpts = { apiOrigin: this._apiBase() };
this._paymentModal = new SkillPaymentModal(this.shadowRoot, _backendId, _payOpts);
this._paymentChip = new PaymentChip(_backendId, _payOpts);
let _paymentInFlight = false;
this._runtime.addEventListener('skill:payment-required', async (e) => {
if (_paymentInFlight) return;
_paymentInFlight = true;
const { skill = 'skill', price = {} } = e.detail || {};
const amountUsdc = (Number(price?.amount || 0) / 1e6).toFixed(2);
// Narrate in chat + avatar walk so the user understands what's happening
const preText = `To use the ${skill} skill I need a quick payment of $${amountUsdc} USDC. Approval card below.`;
this._renderMessage({ role: 'assistant', content: preText });
protocol.emit({
type: ACTION_TYPES.SPEAK,
payload: { text: preText, sentiment: 0 },
});
let purchased = false;
try {
if (this._chatEl) {
purchased = await this._paymentChip.show(this._chatEl, e.detail);
} else {
purchased = await this._paymentModal.show(e.detail);
}
} finally {
_paymentInFlight = false;
}
if (purchased) {
const doneText = 'Payment confirmed. Continuing...';
this._renderMessage({ role: 'assistant', content: doneText });
protocol.emit({
type: ACTION_TYPES.SPEAK,
payload: { text: doneText, sentiment: 0.4 },
});
// Refresh skillAccess so next call goes through without re-prompting.
try {
const r = await fetch(
`${this._apiBase()}/api/agents/${_backendId}/skill-access`,
{ credentials: this._apiCredentials() },
);
if (r.ok) {
const a = (await r.json())?.data;
if (a) {
this._runtime.skillAccess = skillAccessFromAgentDetail(a);
}
}
} catch {}
this._emit('skill:purchased', e.detail, {
bubbles: true,
composed: true,
});
}
});
}
this._notifier = new AgentNotifier(this, protocol);
this._notifier.attach();
// Walk during notification: enter frame (450ms) + message duration + exit frame (380ms)
const _notifyWalkHandler = ({ payload }) => {
if (this.getAttribute('avatar-chat') === 'off') return;
const duration = payload?.duration ?? 6000;
this._onStreamChunk();
clearTimeout(this._walkStopDebounce);
this._walkStopDebounce = setTimeout(
() => this._stopWalkAnimation(),
450 + duration + 380,
);
};
protocol.on(ACTION_TYPES.NOTIFY, _notifyWalkHandler);
this._notifyWalkCleanup = () => protocol.off(ACTION_TYPES.NOTIFY, _notifyWalkHandler);
const _speakWalkHandler = () => {
if (this.getAttribute('avatar-chat') === 'off') return;
this._onStreamChunk();
};
protocol.on(ACTION_TYPES.SPEAK, _speakWalkHandler);
this._speakWalkCleanup = () => protocol.off(ACTION_TYPES.SPEAK, _speakWalkHandler);
// LiveKit realtime voice — connect when voice="livekit" and agent-id is set
if (this.getAttribute('voice') === 'livekit' && _backendId) {
this._connectLiveKit(_backendId).catch((err) => {
log.warn('[agent-3d] LiveKit connect failed', err);
});
}
const _trackedMint = this.getAttribute('tracked-mint');
if (_trackedMint) {
this._detachTradeReactions = attachTradeReactions(this, {
mint: _trackedMint,
origin: this._apiBase(),
});
}
// BEGIN:EMBED_BRIDGES
if (window !== window.parent) {
this._embedBridge = new EmbedActionBridge({
protocol,
manifest: this._manifest,
window,
getClips: () => this._listAvailableClips(),
});
this._embedBridge.start();
// Push the initial clip list once the model + manifest are settled.
// The bridge queues this until the host subscribes; the chip strip on
// the parent page reads it from `op:'clips'` events without polling.
queueMicrotask(() => this._embedBridge?.emitClipsChanged());
}
// END:EMBED_BRIDGES
this._loadingEl.hidden = true;
if (!this._pillActive) this._posterEl.style.opacity = '0';
this._emit('agent:ready', { agent: this, manifest }, { bubbles: true, composed: true });
} catch (err) {
log.error('[agent-3d] boot failed', err);
this._loadingEl.hidden = true;
// Resolve errors should already have been caught and replaced with the
// default-avatar manifest in _resolveManifest. Anything reaching here is
// a deeper boot failure (e.g. the GLB or rig failed to load): chat mode
// shows the error card, a bare decoration avatar shows its poster (or
// stays transparent). Both also emit agent:error below.
this._showError(err);
this._emit(
'agent:error',
{ phase: 'boot', error: err },
{ bubbles: true, composed: true },
);
} finally {
this._stageEl?.classList.remove('is-settling');
this._booting = false;
}
}
// `brain="free"` resolves to the host-paid free model; any other value is
// passed through as a literal model id (paid Claude, a specific Groq/
// OpenRouter id, etc.); no attribute at all keeps the agent silent.
_brainConfig(instructionsAttr) {
const brainAttr = this.getAttribute('brain');
if (!brainAttr) return { provider: 'none' };
const model = brainAttr.trim().toLowerCase() === 'free' ? FREE_BRAIN_MODEL : brainAttr;
return {
provider: 'anthropic',
model,
instructions: instructionsAttr || 'You are an embodied three.ws.',
};
}
_defaultFallbackManifest() {
const instructionsAttr = this.getAttribute('instructions');
return {
spec: 'agent-manifest/0.1',
_baseURI: '',
name: this.getAttribute('name') || 'Agent',
body: { uri: DEFAULT_AVATAR_GLB, format: 'gltf-binary' },
brain: this._brainConfig(instructionsAttr),
voice: { tts: { provider: 'browser' }, stt: { provider: 'browser' } },
skills: [],
};
}
async _resolveManifest() {
const src = this.getAttribute('src');
const manifestAttr = this.getAttribute('manifest');
const body = this.getAttribute('body');
const agentIdAttr = this.getAttribute('agent-id');
const avatarIdAttr = this.getAttribute('avatar-id');
const chainIdAttr = this.getAttribute('chain-id');
const apiBase = this._apiBase();
if (avatarIdAttr && !src && !manifestAttr && !body && !agentIdAttr) {
try {
return await resolveByAvatarId(avatarIdAttr, { origin: apiBase });
} catch (err) {
log.warn('[agent-3d] avatar-id resolve failed, using default avatar:', err);
return this._defaultFallbackManifest();
}
}
if (src) {
if (agentIdAttr) log.warn('[agent-3d] both src and agent-id provided; using src');
// Plain .glb / .gltf URLs are bare bodies, not manifests — treat
// them as if `body=` had been set so users don't need to know the
// distinction.
if (/\.(glb|gltf)(\?|$)/i.test(src)) {
const instructionsAttr = this.getAttribute('instructions');
return {
spec: 'agent-manifest/0.1',
_baseURI: '',
name: this.getAttribute('name') || 'Agent',
body: { uri: src, format: 'gltf-binary' },
brain: this._brainConfig(instructionsAttr),
voice: { tts: { provider: 'browser' }, stt: { provider: 'browser' } },
skills: [],
};
}
return loadManifest(src, {
rpcURL: this.getAttribute('rpc-url'),
registry: this.getAttribute('registry'),
});
}
if (agentIdAttr) {
try {
// On-chain reference? Supported forms:
// agent-id="eip155:8453:0xabc...:42" full CAIP-10 + token
// agent-id="onchain:8453:42" shorthand, canonical registry
// agent-id="42" chain-id="8453" numeric id + explicit chain
// agent-id="agent://8453/42" agent URI
const caipInput = chainIdAttr
? {
chainId: Number(chainIdAttr),
agentId: agentIdAttr,
registry: this.getAttribute('registry') || undefined,
}
: agentIdAttr;
const ref = parseAgentRef(caipInput);
if (ref) {
const resolved = await resolveOnchainAgent(ref, { origin: apiBase });
if (resolved.error && !resolved.glbUrl)
throw new Error(`On-chain resolve failed: ${resolved.error}`);
return toManifest(resolved);
}
// Explicit manifest= wins over backend UUID resolution.
if (manifestAttr) return loadManifest(manifestAttr);
// The agent's public manifest, read from the API origin this script
// came from (never the host page's origin).
return await resolveAgentById(agentIdAttr, { origin: apiBase });
} catch (err) {
// Never let avatar rendering error out — fall back to default avatar.
log.warn('[agent-3d] agent resolve failed, using default avatar:', err);
return this._defaultFallbackManifest();
}
}
if (manifestAttr) return loadManifest(manifestAttr);
if (body) {
// Ad-hoc agent from a bare GLB
const instructionsAttr = this.getAttribute('instructions');
return {
spec: 'agent-manifest/0.1',
_baseURI: '',
name: this.getAttribute('name') || 'Agent',
body: { uri: body, format: 'gltf-binary' },
brain: this._brainConfig(instructionsAttr),
instructions: instructionsAttr || 'You are an embodied three.ws.',
voice: { tts: { provider: 'browser' }, stt: { provider: 'browser' } },
skills: (this.getAttribute('skills') || '')
.split(',')
.map((s) => s.trim())
.filter(Boolean)
.map((uri) => ({ uri })),
memory: { mode: this.getAttribute('memory') || 'local' },
tools: ['wave', 'lookAt', 'play_clip', 'setExpression', 'speak', 'remember'],
version: '0.1.0',
};
}
// No source provided — render the default avatar so the element never errors out.
return this._defaultFallbackManifest();
}
_renderMessage({ role, content, sentiment }) {
if (!this._chatEl) return;
if (!content) return;
// Hide the suggestion chips once a real conversation starts.
this._chatEl.querySelector('.suggest-row')?.remove();
const msg = document.createElement('div');
msg.className = 'msg';
const tone = this._sentimentTone(sentiment);
if (tone) msg.classList.add(tone);
msg.innerHTML = `<div class="role"></div><div class="body"></div>`;
msg.querySelector('.role').textContent = role;
msg.querySelector('.body').textContent = content;
if (this._avatarAnchorEl) {
this._chatEl.insertBefore(msg, this._avatarAnchorEl);
} else {
this._chatEl.appendChild(msg);
}
this._chatEl.scrollTop = this._chatEl.scrollHeight;
if (!this._isWalking && this.getAttribute('avatar-chat') !== 'off') {
this._onStreamChunk();
}
}
_sentimentTone(s) {
if (typeof s !== 'number') return null;
if (s > 0.3) return 'celebration';
if (s < -0.2) return 'concern';
if (s > 0.05) return 'curiosity';
return null;
}
_setToolIndicator(toolName) {
if (!this._toolIndicatorEl) return;
clearTimeout(this._toolIndicatorHideTimer);
const label = this._toolIndicatorLabel(toolName);
this._toolIndicatorEl.querySelector('.label').textContent = label;
this._toolIndicatorEl.dataset.active = 'true';
}
_clearToolIndicator() {
if (!this._toolIndicatorEl) return;
clearTimeout(this._toolIndicatorHideTimer);
this._toolIndicatorHideTimer = setTimeout(() => {
if (this._toolIndicatorEl) this._toolIndicatorEl.dataset.active = 'false';
}, 350);
}
_updateBubblePosition() {
if (!this._thoughtBubbleEl || !this._viewer) return;
const pos = this._viewer.getHeadScreenPosition?.();
if (!pos) return;
const anchorRect = this._avatarAnchorEl?.getBoundingClientRect();
const stageRect = this._stageEl?.getBoundingClientRect();
if (!anchorRect || !stageRect) return;
const relY = pos.y - (anchorRect.top - stageRect.top) - 60;
const clampedY = Math.max(8, relY);
this._thoughtBubbleEl.style.top = `${clampedY}px`;
this._thoughtBubbleEl.style.left = `${pos.x}px`;
this._thoughtBubbleEl.style.transform = 'translateX(-50%) scale(var(--bubble-scale, 1))';
const headRelY = pos.y - (anchorRect.top - stageRect.top);
const bubbleBottom = clampedY + this._thoughtBubbleEl.offsetHeight;
this._thoughtBubbleEl.dataset.tailDir = bubbleBottom < headRelY ? 'up' : 'down';
}
// --- Hotspots (slot="hotspot", data-position/data-normal, data-camera-orbit/data-camera-target) ---
_parseVec3(value) {
if (!value) return null;
const parts = value.trim().split(/\s+/).map(Number);
if (parts.length !== 3 || parts.some((n) => Number.isNaN(n))) return null;
return new Vector3(parts[0], parts[1], parts[2]);
}
_updateHotspots() {
const slot = this._hotspotSlotEl;
if (!slot || !this._viewer) return;
const elements = slot.assignedElements ? slot.assignedElements() : [];
for (const el of elements) {
const worldPos = this._parseVec3(el.dataset.position);
const screen = worldPos && this._viewer.projectToScreen(worldPos);
if (!screen) {
el.hidden = true;
continue;
}
el.hidden = screen.behindCamera;
el.style.transform = `translate(-50%, -50%) translate(${screen.x}px, ${screen.y}px)`;
}
}
// Saved-camera-view hotspots fly the orbit camera there on click/tap; a
// hotspot with no data-camera-orbit is a plain label/marker and does nothing.
_onHotspotClick(e) {
const target = e.target.closest?.('[data-camera-orbit]');
if (!target || !this._viewer) return;
const orbit = this._parseVec3(target.dataset.cameraOrbit);
if (!orbit) return;
const camTarget = this._parseVec3(target.dataset.cameraTarget) || new Vector3(0, 0, 0);
this._viewer.setCameraOrbit(orbit.x, orbit.y, orbit.z, camTarget);
}
// --- KHR_materials_variants ---
async _applyVariantName() {
if (!this._variantController) return;
const name = this.getAttribute('variant-name') || null;
const ok = await this._variantController.select(name);
this._viewer?.invalidate?.();
this._emit(
'agent:variant-changed',
{ name: this._variantController.current, requested: name, ok },
{ bubbles: true, composed: true },
);
}
async _setupVariants(bytes, gltf, token) {
let controller = null;
try {
controller = await createVariantController(bytes, gltf);
} catch (err) {
log.warn('[agent-3d] KHR_materials_variants parsing failed', err);
}
if (token !== this._bootToken) return;
this._variantController = controller;
if (!controller) return;
this._emit(
'agent:variants-ready',
{ names: controller.names.slice() },
{ bubbles: true, composed: true },
);
if (this.hasAttribute('variant-name')) await this._applyVariantName();
}
// --- AR (ar, ar-modes, ar-placement, ios-src) ---
async _fetchBodyBytes(url) {
const res = await fetch(url);
if (!res.ok) throw new Error(`glb fetch ${res.status}`);
return res.arrayBuffer();
}
async _setupAR(glbUrl, bytes, token) {
if (!this._viewer) return;
if (!this.hasAttribute('ar')) {
await this._viewer.setARTarget(null, null);
return;
}
const modes = (this.getAttribute('ar-modes') || 'webxr scene-viewer quick-look')
.trim()
.split(/\s+/)
.filter(Boolean);
const placement = this.getAttribute('ar-placement') === 'wall' ? 'wall' : 'floor';
let usdzUrl = this.getAttribute('ios-src') || null;
if (!usdzUrl && modes.includes('quick-look')) {
try {
const usdzBlob = await buildBestEffortArUsdz(new Blob([bytes]), {
onStatus: (message) => {
if (token !== this._bootToken) return;
this._emit('agent:ar-status', { message }, { bubbles: true, composed: true });
},
});
if (token !== this._bootToken) return;
usdzUrl = URL.createObjectURL(usdzBlob);
if (this._generatedUsdzUrl) URL.revokeObjectURL(this._generatedUsdzUrl);
this._generatedUsdzUrl = usdzUrl;
} catch (err) {
// Quick Look just stays unavailable; Scene Viewer / WebXR still work.
log.warn('[agent-3d] on-device USDZ generation failed', err);
}
}
if (token !== this._bootToken) return;
await this._viewer.setARTarget(glbUrl, usdzUrl, { modes, placement });
if (token !== this._bootToken) return;
this._emit(
'agent:ar-ready',
{ canActivateAR: this._viewer.canActivateAR },
{ bubbles: true, composed: true },
);
}
async _refreshAR() {
if (!this._mounted || !this._viewer) return;
if (!this.hasAttribute('ar')) {
await this._viewer.setARTarget(null, null);
return;
}
if (!this._bodyUrl) return;
const token = this._bootToken;
try {
const bytes = await this._fetchBodyBytes(this._bodyUrl);
if (token !== this._bootToken) return;
await this._setupAR(this._bodyUrl, bytes, token);
} catch (err) {
log.warn('[agent-3d] AR attribute refresh failed', err);
}
}
async _wirePostLoadMedia(glbUrl, gltf, token) {
let bytes;
try {
bytes = await this._fetchBodyBytes(glbUrl);
} catch (err) {
log.warn('[agent-3d] could not re-fetch body bytes for variants/AR', err);
return;
}
if (token !== this._bootToken) return;
await Promise.allSettled([
this._setupVariants(bytes, gltf, token),
this._setupAR(glbUrl, bytes, token),
]);
}
_appendStreamChunkToChat(chunk) {
if (!this._chatEl || !chunk) return;
if (!this._streamingMsgEl) {
this._chatEl.querySelector('.suggest-row')?.remove();
const msg = document.createElement('div');
msg.className = 'msg streaming';
msg.innerHTML = '<div class="role"></div><div class="body"></div>';
msg.querySelector('.role').textContent = 'assistant';
if (this._avatarAnchorEl) {
this._chatEl.insertBefore(msg, this._avatarAnchorEl);
} else {
this._chatEl.appendChild(msg);
}
this._streamingMsgEl = msg.querySelector('.body');
this._chatAutoScroll = true;
if (
!this._walkMovedX &&
this._scene?.viewer?.content &&
!window.matchMedia('(prefers-reduced-motion: reduce)').matches
) {
this._walkHomeX = this._scene.viewer.content.position.x;
this._walkMovedX = true;
this._scene.moveTo({ x: this._walkHomeX + 0.35 }, { duration: 900 });
}
}
const el = this._chatEl;
this._chatAutoScroll = el.scrollHeight - el.scrollTop - el.clientHeight < 40;
this._streamingChatBuffer = (this._streamingChatBuffer || '') + chunk;
if (!this._streamingChatRafPending) {
this._streamingChatRafPending = true;
requestAnimationFrame(() => {
this._streamingChatRafPending = false;
if (this._streamingMsgEl) {
this._streamingMsgEl.textContent = this._streamingChatBuffer;
if (this._chatAutoScroll) {
this._chatEl.scrollTop = this._chatEl.scrollHeight;
}
this._onStreamChunk();
}
});
}
}
_flushBubble() {
this._bubbleRafPending = false;
if (!this._thoughtTextEl) return;
let t = this._bubbleBuffer;
// Roll forward past completed sentences so the bubble feels live
const sentenceEnd = t.search(/[.!?]\s/);
if (sentenceEnd !== -1 && t.length > sentenceEnd + 2) {
this._bubbleBuffer = t.slice(sentenceEnd + 2);
t = this._bubbleBuffer;
}
// Show the tail of the current text — reads as live speech being typed
if (t.length > 80) {
const tail = t.slice(-70);
const wordBreak = tail.indexOf(' ');
t = '…' + (wordBreak !== -1 ? tail.slice(wordBreak + 1) : tail);
}
this._thoughtTextEl.textContent = t;
}
// Buffers chunk and flushes to DOM on the next animation frame (RAF-batched).
_streamToBubble(chunk) {
if (!this._thoughtBubbleEl || !this._thoughtTextEl) return;
// Trigger debounced walk animation on every chunk (safe — _onStreamChunk is debounced).
this._onStreamChunk();
this._thoughtBubbleEl.style.willChange = 'opacity, transform';
this._thoughtBubbleEl.dataset.active = 'true';
this._thoughtBubbleEl.dataset.streaming = 'true';
this._thoughtBubbleEl.setAttribute('aria-label', 'Agent is responding');
this._bubbleBuffer += chunk;
if (!this._bubbleRafPending) {
this._bubbleRafPending = true;
requestAnimationFrame(() => this._flushBubble());
}
}
// Hides bubble, clears buffer, and cancels any pending RAF/timer.
_clearThoughtBubble() {
this._bubbleBuffer = '';
this._bubbleRafPending = false;
clearTimeout(this._bubbleClearTimer);
this._bubbleClearTimer = setTimeout(() => {
if (!this._thoughtBubbleEl) return;
this._thoughtBubbleEl.setAttribute('aria-label', '');
this._thoughtBubbleEl.dataset.active = 'false';
this._thoughtBubbleEl.dataset.streaming = 'false';
this._thoughtBubbleEl.dataset.error = 'false';
if (this._thoughtTextEl) this._thoughtTextEl.textContent = '';
setTimeout(() => {
if (this._thoughtBubbleEl) this._thoughtBubbleEl.style.willChange = 'auto';
}, 300);
}, 80);
}
_showBubbleError(message = 'Something went wrong') {
if (!this._thoughtBubbleEl || this.getAttribute('avatar-chat') === 'off') return;
clearTimeout(this._bubbleClearTimer);
this._thoughtBubbleEl.dataset.active = 'true';
this._thoughtBubbleEl.dataset.streaming = 'true';
this._thoughtBubbleEl.dataset.error = 'true';
if (this._thoughtTextEl) this._thoughtTextEl.textContent = message;
this._bubbleClearTimer = setTimeout(() => {
this._thoughtBubbleEl.dataset.error = 'false';
this._clearThoughtBubble();
}, 3000);
}
// Disables/re-enables the input and updates placeholder during LLM turns.
_setBusy(busy) {
if (!this._inputEl) return;
this._inputEl.disabled = busy;
this._inputEl.dataset.state = busy ? 'thinking' : '';
const row = this._inputEl.closest('.input-row');
if (row) row.dataset.busy = busy ? 'true' : 'false';
this._inputEl.placeholder = busy ? 'Thinking…' : this._composerPlaceholder();
if (!busy && this.shadowRoot?.activeElement == null) {
this._inputEl.focus();
}
}
// Walk animation: debounced — keeps walking as long as chunks arrive within 600ms of each other.
_onStreamChunk() {
if (!this._scene || this.getAttribute('avatar-walk') === 'off') return;
const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (!this._isWalking && !prefersReduced) {
this._isWalking = true;
clearTimeout(this._gestureDoneIdle);
// fade_ms: 300ms idle→walk, 500ms walk→idle, 600ms debounce after last chunk
this._scene.playClipByName('walk', { loop: true, fade_ms: 300 });
// Keep the state-machine bookkeeping in sync — react/emote fired
// while walking will then correctly return to walk afterwards.
this._avatar?.fireAnimationEvent('walk');
}
clearTimeout(this._walkStopDebounce);
this._walkStopDebounce = setTimeout(() => this._stopWalkAnimation(), 600);
}
// Crossfade walk→idle; safe to call even if not currently walking.
_stopWalkAnimation() {
if (!this._isWalking) return;
this._isWalking = false;
clearTimeout(this._walkStopDebounce);
if (this._walkMovedX) {
this._walkMovedX = false;
this._scene?.moveTo({ x: this._walkHomeX }, { duration: 700 });
}
const am = this._viewer?.animationManager;
const currentClip = am?.currentName;
const isGesture = currentClip && currentClip !== 'walk' && currentClip !== 'idle';
if (!isGesture) {
this._scene?.playClipByName('idle', { loop: true, fade_ms: 500 });
this._avatar?.fireAnimationEvent('walk-end');
} else {
// Let the one-shot gesture finish; idle transition fires after gesture + fade-back (~2.5s)
clearTimeout(this._gestureDoneIdle);
this._gestureDoneIdle = setTimeout(() => {
if (!this._isWalking) {
this._scene?.playClipByName('idle', { loop: true, fade_ms: 500 });
this._avatar?.fireAnimationEvent('walk-end');
}
}, 2500);
}
}
_toolIndicatorLabel(toolName) {
const map = {
searchTokens: 'Searching pump.fun…',
getTokenDetails: 'Fetching token details…',
getBondingCurve: 'Reading bonding curve…',
getTokenTrades: 'Pulling recent trades…',
getTrendingTokens: 'Loading trending tokens…',
getNewTokens: 'Loading new launches…',
getGraduatedTokens: 'Loading graduated tokens…',
getKingOfTheHill: 'Crowning the king…',
getCreatorProfile: 'Auditing the creator…',
getTokenHolders: 'Inspecting holders…',
wave: 'Waving…',
remember: 'Saving to memory…',
play_clip: 'Playing animation…',
};
return map[toolName] || `Running ${toolName}…`;
}
_showAlertBanner({ level = 'warn', text } = {}) {
if (!this._alertBannerEl || !text) return;
this._alertBannerEl.classList.remove('warn', 'danger');
this._alertBannerEl.classList.add(level === 'danger' ? 'danger' : 'warn');
this._alertBannerEl.querySelector('.msg-text').textContent = text;
this._alertBannerEl.dataset.active = 'true';
}
_renderToolCallCard({ tool, result }) {
if (!this._chatEl || !result || result.ok === false) return;
const data = result.data ?? result;
const card = this._buildTokenCard(tool, data);
if (!card) return;
this._chatEl.querySelector('.suggest-row')?.remove();
this._chatEl.appendChild(card);
this._chatEl.scrollTop = this._chatEl.scrollHeight;
// Surface a sticky banner for clearly dangerous signals.
if (tool === 'getCreatorProfile') {
const flags = data?.rugFlags ?? data?.risk_flags ?? data?.flags ?? [];
const rugged = data?.rugCount ?? data?.rug_count ?? 0;
if (rugged > 0 || (Array.isArray(flags) && flags.length >= 2)) {
this._showAlertBanner({
level: 'danger',
text: `⚠️ Creator has ${flags.length || rugged} rug indicator${(flags.length || rugged) > 1 ? 's' : ''} — be cautious.`,
});
} else if (Array.isArray(flags) && flags.length === 1) {
this._showAlertBanner({
level: 'warn',
text: `One risk flag on this creator: ${flags[0]}`,
});
}
}
}
_buildTokenCard(tool, data) {
if (!data || typeof data !== 'object') return null;
const fmt = (n, opts = {}) => {
const v = Number(n);
if (!Number.isFinite(v)) return '—';
if (opts.usd) {
if (v >= 1e6) return `$${(v / 1e6).toFixed(2)}M`;
if (v >= 1e3) return `$${(v / 1e3).toFixed(1)}K`;
return `$${v.toFixed(2)}`;
}
if (opts.pct) return `${v.toFixed(1)}%`;
return v.toLocaleString();
};
const card = document.createElement('div');
card.className = 'token-card solana';
if (tool === 'getTokenDetails' || tool === 'getKingOfTheHill') {
const t = data.token || data;
const symbol = t.symbol || t.ticker || 'TOKEN';
const name = t.name || '';
const mcap = t.marketCapUsd ?? t.market_cap_usd ?? t.usd_market_cap;
const price = t.priceUsd ?? t.price_usd ?? t.usd_price;
const grad = t.graduationPercent ?? t.graduation_percent ?? t.progress;
card.innerHTML = `
<div class="token-card-header">
<span class="token-card-symbol">$${this._esc(symbol)}</span>
<span class="token-card-name">${this._esc(name)}</span>
</div>
<div class="token-card-grid">
<div class="token-card-stat"><div class="label">Market cap</div><div class="value">${fmt(mcap, { usd: true })}</div></div>
<div class="token-card-stat"><div class="label">Price</div><div class="value">${fmt(price, { usd: true })}</div></div>
</div>
${
Number.isFinite(Number(grad))
? `<div class="token-card-bar"><div class="fill" style="width:${Math.min(100, Math.max(0, Number(grad)))}%"></div></div>
<div class="token-card-stat" style="margin-top:4px"><div class="label">Graduation</div><div class="value">${fmt(grad, { pct: true })}</div></div>`
: ''
}
`;
return card;
}
if (tool === 'getBondingCurve') {
const grad = data.graduationPercent ?? data.graduation_percent ?? data.progress;
const reserves = data.solReserves ?? data.sol_reserves;
const tokenReserves = data.tokenReserves ?? data.token_reserves;
const danger = Number(grad) < 5;
card.innerHTML = `
<div class="token-card-header">
<span class="token-card-symbol">Bonding curve</span>
</div>
<div class="token-card-grid">
${reserves !== undefined ? `<div class="token-card-stat"><div class="label">SOL reserves</div><div class="value">${fmt(reserves)}</div></div>` : ''}
${tokenReserves !== undefined ? `<div class="token-card-stat"><div class="label">Token reserves</div><div class="value">${fmt(tokenReserves)}</div></div>` : ''}
</div>
${
Number.isFinite(Number(grad))
? `<div class="token-card-bar"><div class="fill ${danger ? 'danger' : ''}" style="width:${Math.min(100, Math.max(0, Number(grad)))}%"></div></div>
<div class="token-card-stat" style="margin-top:4px"><div class="label">Graduation</div><div class="value">${fmt(grad, { pct: true })}</div></div>`
: ''
}
`;
return card;
}
if (tool === 'getCreatorProfile') {
const flags = data.rugFlags ?? data.risk_flags ?? data.flags ?? [];
const tokenCount = data.tokenCount ?? data.token_count ?? data.tokens?.length;
const rugged = data.rugCount ?? data.rug_count ?? 0;
card.innerHTML = `
<div class="token-card-header">
<span class="token-card-symbol">Creator audit</span>
</div>
<div class="token-card-grid">
<div class="token-card-stat"><div class="label">Tokens launched</div><div class="value">${fmt(tokenCount)}</div></div>
<div class="token-card-stat"><div class="label">Rugs</div><div class="value">${fmt(rugged)}</div></div>
</div>
${
Array.isArray(flags) && flags.length
? `<div class="flags">${flags.map((f) => `<span class="flag">${this._esc(String(f))}</span>`).join('')}</div>`
: ''
}
`;
return card;
}
if (
tool === 'getTrendingTokens' ||
tool === 'getNewTokens' ||
tool === 'getGraduatedTokens'
) {
const list =
data.tokens || data.results || data.items || (Array.isArray(data) ? data : []);
if (!list.length) return null;
const top = list.slice(0, 5);
card.innerHTML = `
<div class="token-card-header">
<span class="token-card-symbol">${tool === 'getTrendingTokens' ? '🔥 Trending' : tool === 'getNewTokens' ? '🆕 New' : '🎓 Graduated'}</span>
</div>
<div style="margin-top:8px;display:flex;flex-direction:column;gap:4px">
${top
.map((t) => {
const sym = t.symbol || t.ticker || '?';
const mc = t.marketCapUsd ?? t.market_cap_usd ?? t.usd_market_cap;
return `<div style="display:flex;justify-content:space-between"><span>$${this._esc(sym)}</span><span style="font-variant-numeric:tabular-nums;opacity:.8">${fmt(mc, { usd: true })}</span></div>`;
})
.join('')}
</div>
`;
return card;
}
return null;
}
_esc(s) {
return String(s ?? '').replace(
/[&<>"]/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"' })[c],
);
}
// The single path every element event goes out through. Notifying the host is
// a boundary, not a control-flow step, so it must never be able to throw back
// into its caller.
//
// Two things make that a real risk. `new CustomEvent(...)` reads whichever
// global is bound at call time, so we construct from THIS element's own
// window instead. And _boot is fire-and-forget: an await inside it can settle
// after the host's document was replaced (an SPA remount, or a test runner
// tearing a DOM down between files), which leaves the element in one realm
// while its window object has been handed a foreign CustomEvent. dispatchEvent
// rejects that object as "not of type Event", and thrown from inside _boot's
// own catch it becomes an unhandled rejection: a handled boot failure reported
// as a crash. An element whose realm no longer accepts its events has nobody
// left to notify, so dropping the event is the whole correct response. Nothing
// else escapes here: a listener that throws is reported by the DOM itself and
// never propagates out of dispatchEvent.
_emit(type, detail, { bubbles = false, composed = false } = {}) {
const view = this.ownerDocument?.defaultView;
if (!view) return;
try {
this.dispatchEvent(new view.CustomEvent(type, { detail, bubbles, composed }));
} catch (err) {
log.debug('[agent-3d] dropped', type, 'event: host realm is gone', err);
}
}
_showError(err) {
// A boot that rejects after the host left the document (an SPA unmounting
// mid-load) has nothing to paint into, and the attempt throws from inside
// _boot's catch, turning a handled boot failure into an unhandled rejection.
// The agent:error event still fires either way.
if (!this.isConnected) return;
// Bare/decoration avatars degrade to the supplied poster (or stay
// transparent) rather than a chat-style error card — clean decoration,
// never a broken canvas. Chat agents get the card.
if (!this._isChatMode()) {
this._showDecorationFallback();
return;
}
const raw = (err && (err.message || String(err))) || '';
const isWebgl = /webgl|context/i.test(raw);
const title = isWebgl ? '3D preview unavailable' : "Couldn't load agent";
const hint = isWebgl
? "This browser or device couldn't start a 3D (WebGL) view."
: 'Something went wrong while loading. Please try again.';
const el = document.createElement('div');
el.className = 'error';
el.setAttribute('role', 'alert');
el.innerHTML = `
<div class="error-card">
<div class="error-icon" aria-hidden="true">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M2 12s3-7 10-7 10 7 10 7-3 7-10 7-10-7-10-7Z"/><circle cx="12" cy="12" r="3"/>
<line x1="3" y1="3" x2="21" y2="21"/>
</svg>
</div>
<div class="error-title"></div>
<div class="error-hint"></div>
</div>
`;
el.querySelector('.error-title').textContent = title;
el.querySelector('.error-hint').textContent = hint;
this.shadowRoot.appendChild(el);
}
_fail(code, message) {
this._loadingEl.hidden = true;
// Bare avatars report policy failures through the event only, with no
// visible error banner. Chat agents also render a banner below.
if (!this._isChatMode()) {
this._emit(
'agent:error',
{ phase: 'policy', error: { code, message } },
{ bubbles: true, composed: true },
);
return;
}
const el = document.createElement('div');
el.className = 'error';
el.textContent = message;
this.shadowRoot.appendChild(el);
this._emit(
'agent:error',
{ phase: 'policy', error: { code, message } },
{ bubbles: true, composed: true },
);
}
async _toggleMic() {
// The mic only exists in chat mode, and only where speech input works.
if (!this._micEl) return;
const voiceServer = this.getAttribute('voice-server');
if (voiceServer) {
await this._toggleVoiceClient(voiceServer);
return;
}
// Fallback: Web Speech API (no voice-server attribute)
if (!this._runtime) return;
if (this._listening) {
this._runtime.stt?.stop();
this._listening = false;
this._micEl.dataset.listening = 'false';
return;
}
this._listening = true;
this._micEl.dataset.listening = 'true';
try {
const text = await this._runtime.listen({ onStatus: (s) => this._renderSttStatus(s) });
if (text) this.say(text, { voice: true });
} catch (e) {
log.warn('[agent-3d] listen failed', e);
} finally {
this._listening = false;
this._micEl.dataset.listening = 'false';
this._renderSttStatus(null);
}
}
async _toggleVoiceClient(serverUrl) {
if (this._voiceClient) {
this._voiceClient.stop();
this._voiceClient = null;
return;
}
const { VoiceClient } = await import('./runtime/voice-client.js');
const agentId = this._manifest?.id?.agentId || this.getAttribute('agent-id') || null;
this._voiceClient = new VoiceClient({ serverUrl, element: this });
await this._voiceClient.start(agentId);
}
async _connectLiveKit(agentId) {
const resp = await fetch(`${this._apiBase()}/api/agents/${agentId}/livekit-token`, {
credentials: this._apiCredentials(),
});
if (!resp.ok) {
const body = await resp.json().catch(() => ({}));
log.warn('[agent-3d] livekit-token fetch failed', resp.status, body);
return;
}
const { token, serverUrl } = await resp.json();
const { LiveKitVoice } = await import('./runtime/livekit-voice.js');
const voice = new LiveKitVoice({ serverUrl, token, protocol });
this._livekitVoice = voice;
await voice.connect();
}
_teardown() {
// Invalidate any in-flight _wirePostLoadMedia() run from this boot.
this._bootToken++;
this._variantController = null;
this._bodyUrl = null;
if (this._generatedUsdzUrl) {
URL.revokeObjectURL(this._generatedUsdzUrl);
this._generatedUsdzUrl = null;
}
// A torn-down element must not leave a microphone open or a tone playing.
this.stopSonar();
_untrackLiveViewer(this);
try {
this._io?.disconnect();
} catch {}
this._io = null;
try {
this._ro?.disconnect();
} catch {}
try {
if (this._mqNarrow && this._mqNarrowHandler) {
this._mqNarrow.removeEventListener('change', this._mqNarrowHandler);
}
} catch {}
if (this._outsideTapHandler) {
document.removeEventListener('pointerdown', this._outsideTapHandler);
this._outsideTapHandler = null;
}
this._embedBridge?.stop();
this._embedBridge = null;
this._detachTradeReactions?.();
this._detachTradeReactions = null;
if (this._livekitVoice) {
this._livekitVoice.disconnect().catch(() => {});
this._livekitVoice = null;
}
if (this._voiceClient) {
this._voiceClient.stop();
this._voiceClient = null;
}
this._notifier?.detach();
this._notifier = null;
this._notifyWalkCleanup?.();
this._notifyWalkCleanup = null;
this._speakWalkCleanup?.();
this._speakWalkCleanup = null;
this._setBusy(false);
clearTimeout(this._walkStopDebounce);
this._walkStopDebounce = null;
this._isWalking = false;
this._walkMovedX = false;
this._bubbleBuffer = '';
this._bubbleRafPending = false;
clearTimeout(this._bubbleClearTimer);
this._bubbleClearTimer = null;
this._streamingMsgEl = null;
this._streamingChatBuffer = '';
this._streamingChatRafPending = false;
this._chatAutoScroll = true;
this._pendingSay = null;
try {
this._runtime?.cancel();
this._runtime?.destroy();
} catch {}
try {
this._stopSpokenAudio();
} catch {}
try {
// The speakAudio() graph outlives a single clip, so it has to be
// closed here or a torn-down embed leaks an AudioContext (browsers
// cap them per document, and the cap is low).
this._speakSource?.disconnect();
this._speakCtx?.close?.();
} catch {}
this._speakSource = this._speakAnalyser = this._speakCtx = null;
try {
this._avatar?.detach();
} catch {}
try {
this._viewer?.dispose?.();
} catch {}
this._mounted = false;
this._pillActive = false;
this._runtime =
this._viewer =
this._scene =
this._memory =
this._skills =
this._avatar =
null;
}
// --- Public JS API ---
/** True once an AR launch path (Quick Look, Scene Viewer, or WebXR) is ready on this device. Mirrors `<model-viewer>`. */
get canActivateAR() {
return !!this._viewer?.canActivateAR;
}
/** Launch AR via whichever path `canActivateAR` found. Mirrors `<model-viewer>`'s `activateAR()`. */
async activateAR() {
if (!this._mounted) await this._waitForReady();
return (await this._viewer?.activateAR?.()) ?? false;
}
/** Variant names declared by the loaded GLB's KHR_materials_variants data, or `[]` if it has none. */
get availableVariants() {
return this._variantController?.names.slice() ?? [];
}
get variantName() {
return this.getAttribute('variant-name') || null;
}
set variantName(name) {
if (name) this.setAttribute('variant-name', name);
else this.removeAttribute('variant-name');
}
say(text, opts = {}) {
if (this._pendingSay) {
this._pendingSay = { text, opts };
return;
}
this._pendingSay = { text, opts };
this._drainSayQueue();
}
async _drainSayQueue() {
while (this._pendingSay) {
const { text, opts } = this._pendingSay;
this._pendingSay = null;
try {
if (!this._runtime) await this._waitForReady();
this._onStreamChunk();
protocol.emit({ type: ACTION_TYPES.LOOK_AT, payload: { target: 'user' } });
protocol.emit({
type: ACTION_TYPES.EMOTE,
payload: { trigger: 'curiosity', weight: 0.6 },
});
protocol.emit({
type: ACTION_TYPES.THINK,
payload: { thought: 'processing your message...' },
});
protocol.emit({
type: ACTION_TYPES.EMOTE,
payload: { trigger: 'patience', weight: 0.5 },
});
await this._runtime.send(text, { voice: opts.voice ?? this.hasAttribute('voice') });
} catch (err) {
this._stopWalkAnimation();
const msg = err?.message?.includes('429')
? 'Too many requests — try again'
: err?.message?.includes('busy')
? 'Still thinking…'
: 'Connection error';
this._showBubbleError(msg);
this._setBusy(false);
protocol.emit({
type: ACTION_TYPES.EMOTE,
payload: { trigger: 'concern', weight: 0.8 },
});
this._emit(
'agent:error',
{ phase: 'send', error: err },
{ bubbles: true, composed: true },
);
}
}
}
// Play speak animation — tries 'talk', falls back to 'yes', then 'wave'.
speak(text, opts = {}) {
const duration = Math.max(1.5, (text?.split(' ').length ?? 3) * 0.3);
const sc = this._scene;
if (!sc) return;
sc.playAnimationByHint('talk', { duration }) ||
sc.playAnimationByHint('yes', { duration }) ||
sc.playAnimationByHint('wave', { duration });
}
/**
* Perform `text` in American Sign Language on the avatar, without sending it
* to a brain. Turns the engine on if the `sign-language` attribute has not
* already, and resolves with `{ signed, spelled }` (which words came from
* the lexicon and which were fingerspelled), or `null` when the loaded rig has no
* finger bones to sign with.
*
* @param {string} text
* @returns {Promise<{ signed: string[], spelled: string[] } | null>}
*/
async sign(text) {
if (!this._avatar) await this._waitForReady();
return this._avatar?.sign?.(text) ?? null;
}
/**
* Speak audio the caller supplies, with real viseme lipsync.
*
* The built-in voice pipeline already drives the mouth from its own TTS, but
* an embed that synthesises elsewhere (its own provider, a recorded clip, a
* cached line) had no way in: speak() only plays a talking gesture, and the
* analyser the lipsync layer reads was private. This wires the caller's audio
* through the same analyser, so the mouth follows the actual waveform rather
* than approximating it.
*
* Resolves when playback finishes. The mouth returns to neutral on end, on
* error, and on a second call that supersedes this one.
*
* @param {string|HTMLAudioElement} audio Audio URL (any format the browser
* plays) or an audio element you already control. A cross-origin URL must
* be CORS-readable, or the browser refuses to analyse it and only the
* amplitude-free talking gesture remains.
* @param {{ volume?: number }} [opts]
* @returns {Promise<void>}
*/
async speakAudio(audio, { volume = 1 } = {}) {
if (!audio) return;
if (!this._avatar) await this._waitForReady();
const el = typeof audio === 'string' ? Object.assign(new Audio(), { src: audio }) : audio;
el.crossOrigin = el.crossOrigin || 'anonymous';
el.volume = volume;
// A second call supersedes the first: stop the old clip and drop its
// analyser before the new one claims the avatar's mouth.
this._stopSpokenAudio();
const analyser = this._analyserFor(el);
if (analyser) this._avatar?.connectLipSync?.(analyser);
this._spokenAudio = el;
try {
await el.play();
await new Promise((resolve) => {
el.addEventListener('ended', resolve, { once: true });
el.addEventListener('error', resolve, { once: true });
});
} finally {
if (this._spokenAudio === el) this._stopSpokenAudio();
}
}
/** @private Stop caller-supplied audio and return the mouth to neutral. */
_stopSpokenAudio() {
const el = this._spokenAudio;
this._spokenAudio = null;
if (el) {
try {
el.pause();
} catch {}
}
this._avatar?.disconnectLipSync?.();
}
/**
* @private Build (once) the Web Audio graph the lipsync analyser reads.
* Mirrors src/runtime/speech.js `_setupAnalyser`: one context and one
* analyser for the element's lifetime, a fresh MediaElementSource per audio
* element (an element can only ever be captured once). Returns null when the
* browser refuses, in which case playback still works without visemes.
*/
_analyserFor(audioEl) {
const AC = window.AudioContext || window.webkitAudioContext;
if (!AC) return null;
try {
if (!this._speakCtx || this._speakCtx.state === 'closed') {
this._speakCtx = new AC();
this._speakAnalyser = this._speakCtx.createAnalyser();
this._speakAnalyser.fftSize = 256;
this._speakAnalyser.smoothingTimeConstant = 0.7;
this._speakAnalyser.connect(this._speakCtx.destination);
}
this._speakSource?.disconnect();
this._speakSource = this._speakCtx.createMediaElementSource(audioEl);
this._speakSource.connect(this._speakAnalyser);
this._speakCtx.resume().catch(() => {});
return this._speakAnalyser;
} catch {
// Autoplay policy, CORS, or an element already captured by another
// graph. Playback is unaffected; only the visemes are lost.
return null;
}
}
async ask(text, opts = {}) {
if (!this._runtime) await this._waitForReady();
this._onStreamChunk();
protocol.emit({ type: ACTION_TYPES.LOOK_AT, payload: { target: 'user' } });
protocol.emit({ type: ACTION_TYPES.EMOTE, payload: { trigger: 'curiosity', weight: 0.6 } });
protocol.emit({
type: ACTION_TYPES.THINK,
payload: { thought: 'processing your message...' },
});
protocol.emit({ type: ACTION_TYPES.EMOTE, payload: { trigger: 'patience', weight: 0.5 } });
try {
const reply = await this._runtime.send(text, {
voice: opts.voice ?? this.hasAttribute('voice'),
});
return reply?.text || '';
} catch (err) {
this._stopWalkAnimation();
this._clearThoughtBubble();
this._setBusy(false);
protocol.emit({
type: ACTION_TYPES.EMOTE,
payload: { trigger: 'concern', weight: 0.8 },
});
throw err;
}
}
clearConversation() {
this._runtime?.clearConversation();
}
/**
* Play a named emote. Tries a fallback hint chain before head-bobbing.
* Emote names: 'cheer', 'flinch', 'celebrate'
*/
playEmote(name, intensity = 1) {
const sc = this._scene;
if (!sc) return false;
const fallbacks = {
cheer: ['cheer', 'celebrate', 'wave'],
flinch: ['flinch', 'defeated', 'concern', 'shake'],
celebrate: ['celebrate', 'wave'],
};
for (const h of fallbacks[name] || [name]) {
if (sc.playAnimationByHint(h)) return true;
}
this._headBob(intensity);
return false;
}
_headBob(intensity = 1) {
const sc = this._scene;
if (!sc) return;
const bone = sc.getCanonicalBone('Head');
if (!bone) return;
const start = performance.now();
const origX = bone.rotation.x;
const tick = () => {
const t = (performance.now() - start) / 800;
if (t >= 1) {
bone.rotation.x = origX;
sc._removeHook(tick);
return;
}
bone.rotation.x = origX + 0.15 * intensity * Math.sin(t * Math.PI * 3);
sc.viewer.invalidate();
};
sc._addHook(tick);
}
/* ── acoustic hand control ─────────────────────────────────────────────
*
* The speakers emit a tone above hearing and the microphone reads how a hand
* bends it on the way back, so an embedded agent can be driven by hand with
* no camera. The sensing lives in src/sonar/ and is loaded only when a page
* actually calls startSonar(), so an embed that never uses it ships none of
* it. The full technique and its limits: docs/sonar.md.
*/
/** True when the host page has permitted acoustic control on this element. */
_sonarAllowed() {
const v = this.getAttribute('sonar');
return v != null && v !== 'off' && v !== 'false';
}
/** True while the microphone is open and gestures are being read. */
get sonarRunning() {
return Boolean(this._sonar?.running);
}
/**
* Start reading hand gestures. Requires the `sonar` attribute and a real user
* gesture behind the call, because it prompts for the microphone and puts a
* tone through the speakers.
*
* By default a sweep steps the agent through its gesture vocabulary, a push
* moves the camera in and a pull eases it back out, and a held lift turns the
* camera around the agent. Pass `mode` to choose which gesture is live: the
* three are not separable at the hardware level, so running all of them at
* once ('all') misreads more often.
*
* Every recognised gesture also fires a cancelable `sonar-gesture` event, so
* a host page can map them to its own behaviour instead:
* `el.addEventListener('sonar-gesture', (e) => { e.preventDefault(); ... })`.
*
* @param {{ mode?: 'swipe'|'push'|'lift'|'all', amplitude?: number, tone?: number }} [opts]
* @returns {Promise<boolean>} false when the attribute is absent or the
* browser cannot sense; rejects with a user-showable message on a denied
* or unavailable microphone.
*/
async startSonar(opts = {}) {
if (!this._sonarAllowed() || this.sonarRunning) return false;
const [{ SonarController, GESTURE_CAST }, { isSupported }] = await Promise.all([
import('./sonar/controller.js'),
import('./sonar/doppler.js'),
]);
if (!isSupported()) return false;
let index = 0;
const emit = (gesture, detail) =>
this.dispatchEvent(
new CustomEvent('sonar-gesture', {
detail: { gesture, ...detail },
bubbles: true,
composed: true,
cancelable: true,
}),
);
this._sonar = new SonarController({
mode: opts.mode,
amplitude: opts.amplitude,
tone: opts.tone,
onSwipe: (direction) => {
index = (index + direction + GESTURE_CAST.length) % GESTURE_CAST.length;
const slot = GESTURE_CAST[index];
if (emit('swipe', { direction, slot })) this._scene?.playAnimationByHint(slot);
},
onZoom: (action) => {
// +3 on the push, -1 per step of the paced return, 0 as it lands.
const factor = action > 0 ? 1 / 1.35 : action < 0 ? 1.1 : 1;
if (!emit('push', { action, factor })) return;
if (action === 0) this._scene?.viewer?.frameContent?.({ animate: true });
else this._scene?.viewer?.dollyBy?.(factor);
},
onTurn: (radians, velocity) => {
if (emit('lift', { radians, velocity })) this._scene?.viewer?.orbitBy?.(radians, 0);
},
onError: () => this.stopSonar(),
});
await this._sonar.start();
return true;
}
/** Silence the tone and release the microphone. Safe to call when idle. */
stopSonar() {
if (!this._sonar) return;
this._sonar.stop();
this._sonar = null;
}
async wave(opts) {
return this._scene?.playAnimationByHint('wave', opts);
}
async lookAt(target) {
return this._scene?.lookAt(target);
}
async play(name, opts) {
return this._scene?.playClipByName(name, opts);
}
/**
* Play a clip with the polished embed defaults, honoring the clip's manifest
* `loop` flag automatically: loop clips loop, one-shot clips play once and
* settle seamlessly into idle (no hard snap at the boundary). Respects
* `prefers-reduced-motion` by holding a clean static idle pose instead.
*
* This is the public entry point an embed should use for decorative playback
* — the host page no longer has to know which clips loop.
*
* @param {string} name
* @param {{ fade_ms?: number, userInitiated?: boolean }} [opts]
* `userInitiated` plays the motion even under prefers-reduced-motion — an
* explicit user gesture (e.g. clicking an animation pill) is allowed to
* animate; only ambient autoplay is suppressed.
*/
playClip(name, { fade_ms = 400, userInitiated = false } = {}) {
if (!userInitiated && this._prefersReducedMotion()) {
this._playStaticIdle();
return;
}
this._playDecorationClip(name, fade_ms);
}
/**
* The first pose a freshly loaded body takes, held off-screen until it has
* rendered. Nothing is playing yet, so the usual crossfade would blend the
* clip in from the bind pose and every avatar would open on a T-pose with its
* arms swinging down. The clip snaps in instead (fade 0), and the stage is
* revealed two frames later: microtasks (the cached clip's lazy-load await)
* always drain before a frame, the first frame ticks the mixer and paints the
* pose, and the second is composited. A rig that cannot take the clip is
* revealed all the same, on whatever pose the viewer gave it.
*
* @returns {Promise<void>}
*/
async _startInitialPlayback() {
if (this._isChatMode()) {
this._scene.playClipByName('idle', { loop: true, fade_ms: 0 });
} else {
// idle and walk were fetched during the load; a `clip` attribute naming
// anything else is fetched here, so the reveal waits for it too.
const clip = this.getAttribute('clip');
if (clip) await this._viewer?.animationManager?.ensureLoaded(clip);
this._startDecorationPlayback({ fade_ms: 0 });
}
this._viewer?.invalidate();
await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
}
/**
* Start playback for a bare/decoration avatar: honor the `clip` attribute
* (default idle), the clip's loop flag, and prefers-reduced-motion.
* @param {{ fade_ms?: number }} [opts] fade into the clip; 0 snaps, which is
* what the first pose after a load needs (see _startInitialPlayback).
*/
_startDecorationPlayback({ fade_ms = 400 } = {}) {
if (!this._scene) return;
if (this._prefersReducedMotion()) {
this._playStaticIdle();
return;
}
this._playDecorationClip(this.getAttribute('clip') || 'idle', fade_ms);
}
/**
* Play a clip, deciding loop-vs-one-shot from the animation manifest. One-shot
* clips settle into idle via crossfade so a small looping thumbnail never
* hard-snaps at the clip boundary.
* @param {string} name
* @param {number} fade_ms
*/
_playDecorationClip(name, fade_ms = 400) {
const am = this._viewer?.animationManager;
const def = (am?.getAnimationDefs?.() || []).find((d) => d?.name === name);
// Unknown clip (e.g. a clip baked into the GLB) → assume it loops cleanly.
const loops = def ? def.loop !== false : true;
if (loops) {
this._scene?.playClipByName(name, { loop: true, fade_ms });
} else if (am && typeof am.playOnce === 'function') {
// A snapped start (fade_ms 0) still settles back into idle with a
// real crossfade rather than a hard cut.
am.playOnce(name, { settleTo: 'idle', fade: (fade_ms || 400) / 1000, fadeIn: fade_ms / 1000 });
} else {
this._scene?.playClipByName(name, { loop: false, fade_ms });
}
}
/**
* Reduced-motion path: settle into a single clean idle pose and freeze it, so
* the avatar holds a natural stance with no looping motion — and the viewer's
* render loop can idle (no continuous GPU/CPU cost).
*/
async _playStaticIdle() {
const am = this._viewer?.animationManager;
if (!am) {
this._scene?.playClipByName('idle', { loop: false, fade_ms: 0 });
return;
}
try {
await am.crossfadeTo('idle', 0);
} catch {}
// Let one frame apply the idle pose, then freeze it.
const freeze = () => {
if (this._viewer?.animationManager !== am) return; // model swapped meanwhile
am.freeze();
this._viewer?.invalidate();
};
this._viewer?.invalidate();
requestAnimationFrame(() => requestAnimationFrame(freeze));
}
/**
* Quiet fallback for a bare/decoration avatar whose body failed to load:
* keep the poster if one was supplied, otherwise leave the frame transparent
* so it blends into the host page — never a placeholder silhouette.
*/
_showDecorationFallback() {
this._loadingEl && (this._loadingEl.hidden = true);
// A bare (chat-less) embed that can't paint stays transparent so it
// blends into the host page — unless a poster was supplied, in which
// case it stays visible as the decoration. No silhouette placeholder.
if (this.getAttribute('poster') && this._posterEl) {
this._posterEl.style.opacity = '1';
}
}
/**
* Combined animation list available to the loaded model.
*
* Mirrors the heuristic in `home-act2-viewer.listAvailableClips`:
* • If the GLB ships with 3+ non-idle baked clips (e.g. RobotExpressive),
* show only those — manifest clips are Mixamo-retargeted to the canonical
* Avaturn skeleton and won't bind to a foreign rig.
* • Otherwise (humanoid / Avaturn-compatible — CZ, Default, most user
* avatars), prefer manifest defs (rich label/icon/loop) and append any
* extra baked clips not already covered.
*
* Returned shape is host-friendly: `{ name, label, icon, loop, source }`.
* Empty array if no model loaded yet (host should re-request on `op:'clips'`).
*
* @returns {Array<{name:string, label:string, icon:string, loop:boolean, source:'glb'|'manifest'}>}
*/
_listAvailableClips() {
const sc = this._scene;
const am = this._viewer?.animationManager;
const baked = (sc?.clips || []).map((c) => c?.name).filter(Boolean);
const defs = am?.getAnimationDefs?.() || [];
const IDLE_RE = /idle/i;
const bakedNonIdle = baked.filter((n) => !IDLE_RE.test(n));
// Skeletal mismatch guard: if the GLB has its own rig+clips, manifest
// retargets won't apply — return baked-only.
if (bakedNonIdle.length >= 3) {
return baked.map((name) => ({
name,
label: name,
icon: '✨',
loop: true,
source: 'glb',
}));
}
const out = [];
const seen = new Set();
for (const def of defs) {
if (!def?.name || seen.has(def.name)) continue;
seen.add(def.name);
out.push({
name: def.name,
label: def.label || def.name,
icon: def.icon || '✨',
loop: def.loop !== false,
source: 'manifest',
});
}
for (const name of baked) {
if (seen.has(name)) continue;
seen.add(name);
out.push({ name, label: name, icon: '✨', loop: true, source: 'glb' });
}
return out;
}
/**
* Enable the inline avatar-in-chat layout.
* The avatar canvas is visible through a transparent window between the chat
* history and the input bar. The avatar walks during LLM streaming and shows
* a thought bubble with streaming text above its head.
* This is the default state. Call to re-enable after {@link disableAvatarChat}.
* @returns {void}
*/
enableAvatarChat() {
this.removeAttribute('avatar-chat');
}
/**
* Disable the inline avatar-in-chat layout and restore the original
* bottom-bar chat layout (messages left, input right, avatar in background).
* Walk animation and thought bubble will not fire while disabled.
* Equivalent to setting the `avatar-chat="off"` attribute.
* @returns {void}
*/
disableAvatarChat() {
this.setAttribute('avatar-chat', 'off');
this._stopWalkAnimation();
this._clearThoughtBubble();
}
/**
* Enable the walk animation during streaming and scrolling.
* This is the default state. Call to re-enable after {@link disableAvatarWalk}.
* @returns {void}
*/
enableAvatarWalk() {
this.removeAttribute('avatar-walk');
}
/**
* Disable the walk animation globally.
* The avatar will stay in its idle or empathy-layer animations even while
* streaming text or scrolling the chat.
* Equivalent to setting the `avatar-walk="off"` attribute.
* @returns {void}
*/
disableAvatarWalk() {
this.setAttribute('avatar-walk', 'off');
this._stopWalkAnimation();
}
async installSkill(uri) {
if (!this._skills) throw new Error('Agent not mounted');
return this._skills.install({ uri });
}
uninstallSkill(name) {
return this._skills?.uninstall(name);
}
get skills() {
return this._skills?.all() || [];
}
get memory() {
return this._memory;
}
get manifest() {
return this._manifest;
}
get runtime() {
return this._runtime;
}
setMode(mode) {
this.setAttribute('mode', mode);
}
setPosition(pos, offset) {
this.setAttribute('position', pos);
if (offset) this.setAttribute('offset', offset);
}
setSize(w, h) {
this.setAttribute('width', w);
this.setAttribute('height', h);
}
pause() {
this._runtime?.pause();
}
resume() {
/* viewer resumes via IntersectionObserver */
}
destroy() {
this._teardown();
}
/**
* Slide the avatar into frame, speak a message, then retreat.
* Queued — back-to-back calls wait for the previous to finish.
* @param {string} message
* @param {{ priority?: 'low'|'normal'|'high', duration?: number }} [opts]
*/
notify(message, { priority = 'normal', duration = 6000 } = {}) {
protocol.emit({ type: ACTION_TYPES.NOTIFY, payload: { message, priority, duration } });
}
/**
* Trigger an emotion stimulus on the running avatar(s) via the protocol bus.
* Trigger names match the avatar's emotion vocabulary:
* 'celebration' | 'concern' | 'curiosity' | 'empathy' | 'patience'
* Weight is clamped to [0, 1] by the avatar; defaults to 0.7.
* No-op if the agent hasn't booted yet.
*/
expressEmotion(trigger, weight = 0.7) {
if (!trigger) return false;
protocol.emit(ACTION_TYPES.EMOTE, {
trigger,
weight: Math.max(0, Math.min(1, Number(weight) || 0)),
agentId: this._manifest?.id?.agentId,
});
return true;
}
/**
* Set the avatar's sustained mood (Living Agents · Task 07). Drives the
* resting facial expression + posture continuously through the empathy layer.
* Stored so it still lands if the empathy layer attaches after this call.
* @param {number} valence -1..1
* @param {number} arousal 0..1
* @param {{reducedMotion?: boolean}} [opts]
*/
setMood(valence, arousal, opts = {}) {
this._pendingMood = { valence, arousal, reducedMotion: Boolean(opts.reducedMotion) };
this._avatar?.setMood(valence, arousal, { reducedMotion: this._pendingMood.reducedMotion });
return true;
}
/**
* Perform a gesture routine: a named sequence of gestures with per-step
* timing, composed at three.ws/choreograph. Pass the routine's id to play one
* the agent has saved, or a routine object to play one the host page owns.
*
* el.playRoutine('welcome');
* el.playRoutine({ name: 'Hi', steps: [{ slot: 'wave', hold: 2 }] });
*
* Queued until the empathy layer attaches, so it lands when called during
* boot rather than being dropped.
* @param {string|object} nameOrRoutine
* @param {{loop?:boolean}} [opts]
* @returns {boolean} false when the named routine does not exist
*/
playRoutine(nameOrRoutine, opts = {}) {
if (!this._avatar) {
this._pendingRoutine = { nameOrRoutine, opts };
// A routine requested before boot is a real request, not a no-op: report
// success and let `_applyPendingRoutine` deliver it.
this._waitForReady().then(() => this._applyPendingRoutine());
return true;
}
return this._avatar.playChoreography(nameOrRoutine, opts);
}
/** Stop a performing routine. */
stopRoutine() {
this._pendingRoutine = null;
this._avatar?.stopChoreography();
return true;
}
/** The routines this agent has saved, as normalized routine objects. */
getRoutines() {
return this._avatar?.getChoreographies() ?? [];
}
_applyPendingRoutine() {
const pending = this._pendingRoutine;
if (!pending || !this._avatar) return;
this._pendingRoutine = null;
this._avatar.playChoreography(pending.nameOrRoutine, pending.opts);
}
_waitForReady() {
if (this._mounted) return Promise.resolve();
return new Promise((resolve) => {
const on = () => {
this.removeEventListener('agent:ready', on);
resolve();
};
this.addEventListener('agent:ready', on);
if (!this._booting) this._boot();
});
}
}
function stripFrontmatter(text) {
const m = text.match(/^---\n[\s\S]*?\n---\n?([\s\S]*)$/);
return m ? m[1] : text;
}
if (!customElements.get('agent-3d')) {
customElements.define('agent-3d', Agent3DElement);
}
export { Agent3DElement };