Skip to content

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

147 KB
Raw Blame
// <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) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[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 };