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.

99.1 KB
Raw Blame
import * as THREE from 'three';
import WebGL from 'three/addons/capabilities/WebGL.js';
import { initWalletButton } from './wallet.js';
import { eagerConnectWallet } from './erc8004/agent-registry.js';
import { Viewer } from './viewer.js';
import { Editor } from './editor/index.js';
import { SimpleDropzone } from 'simple-dropzone';
import { Validator } from './validator.js';
import { Footer } from './components/footer';
import { startWidgetRpcServer } from './widget/rpc-server.js';
import { NichAgent } from './nich-agent.js';
import { ThoughtBubble } from './thought-bubble.js';
import { AvatarCreator } from './avatar-creator.js';
import { resolveURI, isDecentralizedURI } from './ipfs.js';
import { resolveDevR2Url } from './shared/dev-r2-proxy.js';
import { isSafeQueryModelUrl } from './shared/safe-model-url.js';
import { apiFetch } from './api.js';

// Resolve a model URL for loading: expand decentralized URIs (ipfs:/ar:) via the
// gateway, then route r2.dev assets through the dev /r2-proxy so cross-origin
// GLB fetches don't fail CORS on localhost / Codespaces. No-op in production.
function resolveModelUrl(url) {
	const expanded = isDecentralizedURI(url) ? resolveURI(url) : url;
	return resolveDevR2Url(expanded);
}
// The on-chain deployment agent — the guided flow for deploying 3D assets on
// Solana. The "Deploy on Solana" CTA in /app always routes here.
const ONCHAIN_DEPLOY_AGENT_ID = '67bf6e67-93bb-40c6-9a6b-91e921696248';
const ONCHAIN_DEPLOY_AGENT_URL = `/app?agent=${ONCHAIN_DEPLOY_AGENT_ID}`;
// Pull in the shared corner-stack (public/corner-stack.js) so the onboarding
// card flows with the other bottom-right widgets instead of overlapping them.
// Idempotent; the stack adopts the tagged card once it initialises.
function ensureCornerStack() {
	if (typeof document === 'undefined' || window.twsCornerStack) return;
	if (document.querySelector('script[src="/corner-stack.js"]')) return;
	const s = document.createElement('script');
	s.src = '/corner-stack.js';
	s.defer = true;
	(document.head || document.documentElement).appendChild(s);
}

import { saveRemoteGlbToAccount, getMe, readAuthHint } from './account.js';
import { getWidget } from './widgets.js';
import { mountAnimationGallery } from './widgets/animation-gallery.js';
import { mountTalkingAgent } from './widgets/talking-agent.js';
import { mountTurntable } from './widgets/turntable.js';
import { mountHotspotTour } from './widgets/hotspot-tour.js';
import { mountPumpfunFeed } from './widgets/pumpfun-feed.js';
import { mountKolTradesWidget } from './widgets/kol-trades.js';
import { mountLiveTradesCanvas } from './widgets/live-trades-canvas.js';
import { mountBondingCurve } from './widgets/bonding-curve.js';
import { mountPassport } from './widgets/passport.js';
import { ScreenshotModal } from './components/screenshot-modal.js';
import { NextLayout } from './next-layout.js';

// Agent system — the new primitive layer
import { protocol, ACTION_TYPES } from './agent-protocol.js';
import { AgentIdentity } from './agent-identity.js';
import { AgentSkills } from './agent-skills.js';
import { AgentAvatar } from './agent-avatar.js';
import { AgentHome } from './agent-home.js';
import { setSceneViewer } from './agent-skills-scene.js';

// Runtime — LLM brain, scene control, file-based memory, skill bundles
import { SceneController } from './runtime/scene.js';
import { Runtime } from './runtime/index.js';
import { Memory } from './memory/index.js';
import { SkillRegistry } from './skills/index.js';
import { log } from './shared/log.js';

window.THREE = THREE;
window.VIEWER = {};

// Build the /walk-embed URL for a saved walking-avatar widget from its config +
// avatar. The avatar is passed by id when we have one (the embed resolves it via
// the same-origin GLB proxy, which works cross-origin) and falls back to the
// public model URL for demo fixtures. Mirrors the studio's snippet builder.
function walkEmbedUrlForWidget(widget) {
	const cfg = widget.config || {};
	const av = widget.avatar || {};
	const avatarParam = av.id || av.model_url || '';
	const u = new URL('/walk-embed', location.origin);
	if (avatarParam) u.searchParams.set('avatar', avatarParam);
	u.searchParams.set('env', cfg.environment || 'studio');
	u.searchParams.set('controls', cfg.controls || 'joystick');
	if (cfg.autoplay) u.searchParams.set('autoplay', '1');
	if (cfg.bg) u.searchParams.set('bg', cfg.bg);
	if (typeof cfg.walkSpeed === 'number') u.searchParams.set('speed', String(cfg.walkSpeed));
	if (cfg.enableNarration) u.searchParams.set('narration', '1');
	return u.pathname + u.search;
}

function _blobToBase64(blob) {
	return new Promise((resolve, reject) => {
		const reader = new FileReader();
		reader.onload = () => {
			const s = reader.result;
			const comma = s.indexOf(',');
			resolve(comma >= 0 ? s.slice(comma + 1) : s);
		};
		reader.onerror = () => reject(reader.error);
		reader.readAsDataURL(blob);
	});
}

function _base64ToFile(b64, name, type) {
	const bin = atob(b64);
	const bytes = new Uint8Array(bin.length);
	for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
	return new File([bytes], name, { type });
}

function _fmtBytes(n) {
	if (!Number.isFinite(n) || n <= 0) return '0 B';
	const units = ['B', 'KB', 'MB', 'GB'];
	const i = Math.min(units.length - 1, Math.floor(Math.log(n) / Math.log(1024)));
	const v = n / Math.pow(1024, i);
	return `${v >= 10 || i === 0 ? Math.round(v) : v.toFixed(1)} ${units[i]}`;
}

/**
 * Parse an on-chain agent URL path. Accepts:
 *   /a/<chainId>/<agentId>                       (canonical — registry inferred)
 *   /a/<chainId>/<agentId>/embed                 (chromeless iframe variant)
 *   /a/<chainId>/<registry>/<agentId>            (explicit registry, for non-canonical deployments)
 *   /a/<chainId>/<registry>/<agentId>/embed
 *   /a/eip155:<chainId>:<registry>/<agentId>     (full CAIP)
 */
function parseOnchainPath(pathname) {
	// Strip trailing /embed (capturing) then peel remaining segments.
	const embedMatch = pathname.match(/^(\/a\/.+?)\/embed\/?$/);
	const embed = !!embedMatch;
	const base = embed ? embedMatch[1] : pathname;
	const m = base.match(/^\/a\/([^/]+)(?:\/([^/]+))?(?:\/([^/]+))?\/?$/);
	if (!m) return null;
	const [, a, b, c] = m;

	// /a/eip155:chainId:registry/<agentId>
	const caipMatch = a.match(/^eip155:(\d+):(0x[a-fA-F0-9]{40})$/);
	if (caipMatch && b && /^\d+$/.test(b) && !c) {
		return { chainId: Number(caipMatch[1]), registry: caipMatch[2], agentId: b, embed };
	}

	// /a/<chainId>/<registry>/<agentId>
	if (b && c && /^\d+$/.test(a) && /^0x[a-fA-F0-9]{40}$/.test(b) && /^\d+$/.test(c)) {
		return { chainId: Number(a), registry: b, agentId: c, embed };
	}

	// /a/<chainId>/<agentId> (canonical: registry inferred from REGISTRY_DEPLOYMENTS)
	if (b && !c && /^\d+$/.test(a) && /^\d+$/.test(b)) {
		return { chainId: Number(a), agentId: b, embed };
	}

	return null;
}

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

/** Parse #onchain=<chainId>:<agentId> for embed mode. */
function parseOnchainHash(value) {
	if (!value) return null;
	const m = String(value).match(/^(\d+):(\d+)$/);
	if (!m) return null;
	return { chainId: Number(m[1]), agentId: m[2] };
}

if (!(window.File && window.FileReader && window.FileList && window.Blob)) {
	log.error('The File APIs are not fully supported in this browser.');
} else if (!WebGL.isWebGL2Available()) {
	log.error('WebGL is not supported in this browser.');
}

class App {
	/**
	 * @param  {Element} el
	 * @param  {Location} location
	 */
	constructor(el, location) {
		const hash = location.hash
			? Object.fromEntries(new URLSearchParams(location.hash.replace(/^#/, '')))
			: {};
		const qp = new URLSearchParams(location.search);
		// agentQuery: from ?agent= query param → editing mode (main UI with save-back)
		// agentHash:  from #agent= hash → legacy embed mode
		const agentQuery = qp.get('agent') || '';
		const agentHash = hash.agent || '';

		// On-chain CAIP-style route: /a/<chainId>/<agentId> [ /<registry> optional ]
		// Parses to { chainId, agentId, registry? } when matched. Renders the agent's
		// 3D avatar by resolving its registration file → `avatar` service endpoint.
		const onchain = parseOnchainPath(location.pathname) || parseOnchainHash(hash.onchain);

		// /a/<uuid>?embed=1 — chromeless chat embed for non-on-chain agents.
		// Distinct from kiosk: NichAgent is still mounted so visitors can chat.
		const _pathSegs = location.pathname.split('/').filter(Boolean);
		const _chatEmbedId = (
			_pathSegs[0] === 'a' &&
			_pathSegs.length === 2 &&
			!onchain &&
			qp.get('embed') === '1'
		) ? _pathSegs[1] : null;

		this.options = {
			kiosk: Boolean(hash.kiosk) || !!(onchain && onchain.embed),
			embedChat: !!_chatEmbedId, // /a/<uuid>?embed=1 chat embed mode
			model: hash.model || '',
			type: hash.type || '',
			preset: hash.preset || '',
			cameraPosition: hash.cameraPosition ? hash.cameraPosition.split(',').map(Number) : null,
			brain: hash.brain || 'none',
			proxyURL: hash.proxyURL || '',
			agent: agentHash, // hash-based agent keeps legacy embed behaviour
			agentEdit: agentQuery, // query-param agent → editing surface
			widget: hash.widget || '',
			deploy: hash.deploy !== undefined || location.pathname === '/deploy',
			onchain, // { chainId, agentId, registry? } | null
			showcase: location.pathname === '/showcase' || location.pathname === '/showcase/',
			// pending=1 signals a post-login save round-trip
			pending: qp.get('pending') === '1',
			// avatarSession: selfie pipeline passes a session URL here after processing photos
			avatarSession: hash.avatarSession ? decodeURIComponent(hash.avatarSession) : '',
			// Per-embed overrides (appended to iframe URL by Studio embed modal
			// and the public /widgets gallery customizer).
			noAnimations: Boolean(hash.noAnimations),
			noChat: Boolean(hash.noChat),
			noControls: Boolean(hash.noControls),
			avatarChatOff: hash['avatar-chat'] === 'off',
			// Live-customizer overrides — applied on top of the saved widget config.
			// Hash form is %23-encoded for color values (e.g. accent=%2300ff88).
			overrideAccent: hash.accent ? decodeURIComponent(hash.accent) : '',
			overrideBg: hash.bg ? decodeURIComponent(hash.bg) : '',
			overrideMint: hash.mint ? decodeURIComponent(hash.mint) : '',
			overrideKind: hash.kind || '',
			overrideMinTier: hash.minTier || '',
		};

		// Slim /widget shell — see pages/widget.html. The shell hides every
		// owner-mode surface and the viewer is the only thing on screen.
		// Several setup steps below (wallet reconnect, dropzone, selfie pipeline,
		// auth check, layout switch) are pure dead weight in that surface, so
		// we short-circuit them when the shell flag is present.
		this._widgetShell = Boolean(window.__WIDGET_SHELL);

		// Fire-and-forget silent wallet reconnect. Cheap (single `eth_accounts`
		// RPC), never throws, never prompts. If the user has previously authorized
		// the site, this populates the shared signer before any wallet UI mounts.
		// Skip in the slim widget shell — embeds don't need wallet state.
		if (!this._widgetShell) eagerConnectWallet();

		this.el = el;
		this.viewer = null;
		this.editor = null;
		this._previewMounted = false;
		this.viewerEl = null;
		this.spinnerEl = el.querySelector('.spinner');
		this.dropEl = el.querySelector('.wrap');
		this.inputEl = el.querySelector('#file-input');
		this.viewerContainerEl = el.querySelector('#viewer-container');
		this.validator = new Validator(el);

		// ── Agent System ──────────────────────────────────────────────────────
		this.identity = new AgentIdentity({ autoLoad: true });
		this.skills = null; // initialised after identity loads
		this.avatar = null; // initialised after viewer + content load
		this.agentHome = null;
		this.sceneCtrl = null; // SceneController — created when viewer is ready
		this.runtime = null; // LLM Runtime — created after identity + memory load
		this.fileMemory = null; // file-based Memory for LLM context
		this.skillRegistry = null; // external skill bundle loader

		// Wire validator results into the protocol
		this._hookValidator();

		// Viewer status overlay (loading / error UI) tied to LOAD_START / LOAD_END.
		this._wireViewerStatus();

		this._editingAgentId = this.options.agentEdit || null;

		// In the slim widget shell there's no dropzone, no selfie pipeline UI,
		// no sign-in link, no layout switch buttons. Skip those entirely so
		// we don't waste cycles attaching listeners + a network round-trip
		// (getMe) for an iframe that only renders a 3D canvas.
		// _applyViewerMode still runs — it sets `data-viewer-mode="embed"`
		// which CSS uses to hide ambient chrome on shared pages.
		if (!this._widgetShell) {
			this.createDropzone();
			this.setupAvatarCreator();
			if (this.options.avatarSession) {
				this.avatarCreator.open(this.options.avatarSession);
			}
		}
		this.hideSpinner();
		this._applyViewerMode();
		if (!this._widgetShell) {
			this._setupLayoutSwitch();
			this._setupNextLayout();
			this._updateSignInLink();
			this._setupSaveToAccount();
			this._setupMakeWidgetButton();
			this._setupScreenshotButton();
			this.screenshotModal = new ScreenshotModal(this.el);
		}

		const options = this.options;

		if (options.kiosk || options.embedChat) {
			// In the slim widget shell there's no <header> in the DOM —
			// hide defensively only if it exists (legacy /app#kiosk=true URLs
			// and /a/<uuid>?embed=1 chat embeds).
			const headerEl = document.querySelector('header');
			if (headerEl) headerEl.style.display = 'none';
			const footerEl = document.querySelector('footer');
			if (footerEl) footerEl.style.display = 'none';
		}

		// Check for deploy (ERC-8004 mint) page. We still load the default
		// avatar in the background so `_currentModelUrl` is populated for the
		// RegisterUI pre-fill — it reflects the viewer's current model.
		// Honor `?model=<url>` passed from the /app deploy button so an
		// unsaved viewer model still flows through instead of falling to CZ.
		if (options.deploy) {
			const rawQpModel = new URLSearchParams(location.search).get('model') || '';
			// Only honor a query-param model URL from a trusted asset source; an
			// arbitrary attacker URL falls through to the default avatar.
			const qpModel = isSafeQueryModelUrl(rawQpModel) ? rawQpModel : '';
			const model = options.model || qpModel || '/avatars/cz.glb';
			this.view(resolveModelUrl(model), '', new Map())
				.catch(() => {})
				.finally(() => this._showDeployPage());
			this._initAgentSystem();
			return;
		}

		// /showcase — browsable marketplace of every indexed three.ws.
		if (options.showcase) {
			this._showShowcasePage();
			this._initAgentSystem();
			return;
		}

		// /a/<chainId>/<agentId> — resolve an on-chain agent to its 3D avatar.
		if (options.onchain) {
			this._loadOnChainAgent(options.onchain).catch((err) => {
				log.warn('[3d-agent] on-chain agent load failed', err);
				this._showViewerError("Couldn't load this agent.", () => this._retryAgentLoad());
			});
			this._initAgentSystem();
			return;
		}

		// Load a specific agent by ID: /#agent=<uuid> (embed mode)
		if (options.agent) {
			this._loadAgent(options.agent).catch((err) => {
				log.warn('[3d-agent] agent load failed', err);
				this._showViewerError("Couldn't load this agent.", () => this._retryAgentLoad());
			});
			return;
		}

		// /a/<uuid>?embed=1 — chromeless chat embed. Load the named agent;
		// NichAgent will initialize because kiosk is false.
		if (_chatEmbedId) {
			this._loadAgent(_chatEmbedId).catch((err) => {
				log.warn('[3d-agent] chat-embed agent load failed', err);
				this._showViewerError("Couldn't load this agent.", () => this._retryAgentLoad());
			});
			return;
		}

		// Load a saved widget by ID: /widget#widget=<wdgt_...> (slim shell,
		// canonical) or legacy /app#widget=<wdgt_...> (full SPA, still works).
		if (options.widget) {
			this._loadWidget(options.widget).catch((err) => {
				log.warn('[3d-agent] widget load failed', err);
				this._showViewerError("Couldn't load this widget.", () => this._retryAgentLoad());
			});
			this._initAgentSystem();
			this._initWidgetBridge();
			return;
		}

		// Editing an existing agent: ?agent=<uuid> (authenticated editing surface)
		if (options.agentEdit) {
			this._loadAgentForEdit(options.agentEdit).catch((err) => {
				// Defensive: _loadAgentForEdit handles its own failures and
				// always mounts the viewer up-front, but a truly unexpected
				// throw shouldn't leave the user with no UI to act on.
				log.warn('[3d-agent] agent-edit load failed', err);
				this._showViewerError("Couldn't load this agent.", () => this._retryAgentLoad());
				if (!this.viewer) this._maybeResumeOrLoad(this.options);
				if (!this._agentSystemBooted) this._initAgentSystem();
			});
		} else {
			// Resume a stashed editor session (post-login round-trip), else
			// load the model named in the URL or fall back to the CZ avatar.
			this._maybeResumeOrLoad(options);
		}

		// After sign-in redirect, check for a pending_save stash.
		if (options.pending) {
			this._maybePendingSave();
		}

		// Boot the agent system once identity is ready. When agentEdit is set,
		// _loadAgentForEdit calls _initAgentSystem itself after loading the
		// correct identity, so skip the early call to avoid a double-mount.
		if (!options.agentEdit) {
			this._initAgentSystem();
		}

		// Studio preview iframes use postMessage to live-update brand config.
		this._initWidgetBridge();

		// JSON-RPC 2.0 server for parents that want to drive the widget
		// programmatically (camera moves, animation playback, screenshots).
		// Always on — only the legacy bridge handlers had widget-scope checks,
		// because RPC is opt-in by the message envelope (jsonrpc: '2.0').
		startWidgetRpcServer(this);
	}

	/**
	 * If the URL carries ?resume=<token>, restore the stashed editor session
	 * (load source + replay edits + optionally auto-open Publish). Otherwise
	 * load the model from #model= or the default CZ avatar.
	 */
	async _maybeResumeOrLoad(options) {
		const params = new URLSearchParams(location.search);
		const resumeToken = params.get('resume');

		if (resumeToken) {
			try {
				const { restoreSession, clearStash } = await import('./editor/edit-persistence.js');
				const stashed = await restoreSession(resumeToken);
				if (stashed) {
					if (stashed.source.url) {
						await this.view(stashed.source.url, '', new Map());
					} else if (stashed.source.file) {
						const f = stashed.source.file;
						await this.load(new Map([[f.name, f]]));
					}

					if (this.editor && this.editor.session) {
						this.editor.session.restoreEdits(stashed.edits);
						// Panels snapshotted the original material values before
						// restoreEdits mutated them — rebuild so the GUI mirrors
						// the restored state.
						this.editor.materialEditor?.rebuild?.();
						this.editor.textureInspector?.rebuild?.();
						this.editor.sceneExplorer?.rebuild?.();
					}

					if (params.get('publish') === '1') {
						this.editor?._openPublishModal?.();
					}

					await clearStash(resumeToken);

					const clean = new URL(location.href);
					clean.searchParams.delete('resume');
					clean.searchParams.delete('publish');
					history.replaceState(null, '', clean.toString());
					return;
				}
			} catch (err) {
				log.warn('[3d-agent] resume failed', err);
			}
		}

		const model = options.model || '/avatars/cz.glb';
		const resolvedModel = resolveModelUrl(model);
		const isDefaultCz = !options.model;
		const loadModel = () => this.view(resolvedModel, '', new Map());
		// Always terminate the load promise. The widget/kiosk path passes a remote
		// model URL (e.g. an R2 draft GLB) that can 404 or fail the network fetch —
		// without a .catch the rejection escaped as an "unhandledrejection: Load
		// failed", reported through [client-error] but leaving the viewer on a blank
		// frame. Show the same designed error/retry state the agent paths use.
		Promise.resolve(loadModel())
			.then(() => {
				if (isDefaultCz) this._playDefaultLandingClip('taunt');
			})
			.catch((err) => {
				log.warn('[3d-agent] model load failed', err);
				this._showViewerError("Couldn't load this model.", () => loadModel());
			});
	}

	/**
	 * After the default CZ avatar loads on /app, stop the baked-in idle clip
	 * (which fights the manifest animations on the same skeleton and looks
	 * glitchy) and crossfade into a manifest clip once it's ready.
	 * @param {string} clipName
	 */
	_playDefaultLandingClip(clipName) {
		const viewer = this.viewer;
		if (!viewer) return;
		if (viewer.mixer) viewer.mixer.stopAllAction();
		const am = viewer.animationManager;
		if (!am) return;
		const start = performance.now();
		const tryPlay = () => {
			if (!this.viewer || this.viewer !== viewer) return;
			if (viewer.mixer) viewer.mixer.stopAllAction();
			const defs = am.getAnimationDefs();
			const hasDef = defs.some((d) => d.name === clipName);
			if (hasDef) {
				am.crossfadeTo(clipName).catch(() => {});
				return;
			}
			if (performance.now() - start > 8000) return;
			setTimeout(tryPlay, 200);
		};
		tryPlay();
	}

	// ── Agent System Init ─────────────────────────────────────────────────────

	async _initAgentSystem() {
		if (this._agentSystemBooted) return;
		this._agentSystemBooted = true;
		try {
			// Wait for identity to resolve (uses local storage immediately, backend async)
			await this.identity.load();

			// Skills need identity + memory
			this.skills = new AgentSkills(protocol, this.identity.memory);

			// File-based memory for LLM context injection
			this.fileMemory = await Memory.load({
				mode: 'local',
				namespace: this.identity.id,
			});

			// External skill bundle loader (empty initially — skills load on demand)
			this.skillRegistry = new SkillRegistry({ trust: 'owned-only' });

			// LLM Runtime — the agent's brain. Defaults to 'none' provider
			// (NichAgent pattern matching). Configure with #brain=anthropic&proxyURL=...
			this.runtime = new Runtime({
				manifest: {
					name: this.identity.name || 'Agent',
					instructions: [
						`You are ${this.identity.name || 'Agent'}, an AI agent embedded in a 3D model viewer at three.ws.`,
						'You can control the 3D scene, remember things, and help users with their 3D work.',
						'Be concise, clear, and helpful. You are present and embodied — act like it.',
					].join(' '),
					brain: {
						provider: this.options.brain,
						proxyURL: this.options.proxyURL || undefined,
					},
					tools: ['wave', 'lookAt', 'play_clip', 'setExpression', 'speak', 'remember'],
				},
				viewer: this.sceneCtrl, // null until viewer loads
				memory: this.fileMemory,
				skills: this.skillRegistry,
			});

			// Bridge Runtime assistant messages to the protocol bus
			this.runtime.addEventListener('brain:message', (e) => {
				if (e.detail.role === 'assistant' && e.detail.content) {
					protocol.emit({
						type: ACTION_TYPES.SPEAK,
						payload: { text: e.detail.content, sentiment: 0 },
						agentId: this.identity.id,
					});
				}
			});

			this.runtime.addEventListener('brain:action', (e) => {
				if (this.viewer && e.detail.tool_name === 'setCameraTarget') {
					this.viewer.setCameraTarget(e.detail.tool_input.boneName);
				}
			});

			// Expose agent on window for debugging
			window.VIEWER.agent_protocol = protocol;
			window.VIEWER.agent_identity = this.identity;
			window.VIEWER.agent_skills = this.skills;
			window.VIEWER.agent_runtime = this.runtime;

			// Announce presence
			protocol.emit({
				type: ACTION_TYPES.PRESENCE,
				payload: { status: 'online', agentId: this.identity.id },
				agentId: this.identity.id,
			});

			// Render the agent home panel (identity card + timeline). Idempotent —
			// if a previous boot already rendered, tear it down before re-mounting
			// so we never stack multiple cards in the sidebar.
			// Skip entirely in kiosk/embed — the panel belongs to owner/edit views.
			const homeEl = document.getElementById('agent-home-container');
			if (homeEl && !this.options.kiosk) {
				if (this.agentHome) this.agentHome.destroy();
				homeEl.innerHTML = '';
				this.agentHome = new AgentHome(homeEl, this.identity, protocol, this.avatar, {
					skills: this.agent_skills || window.VIEWER?.agent_skills,
					memory: this.agent_memory || window.VIEWER?.agent_memory,
				});
				await this.agentHome.render();
			}

			// Boot the voice/chat agent with skills and runtime wired in.
			// Skip in widget-embed mode — each widget type mounts its own UI
			// (talking-agent uses its own embedded NichAgent; others need no chat).
			// Also skip in any kiosk surface (slim /widget shell, public embed
			// snippets) so the "Agent" pill doesn't leak across an iframe
			// boundary that's meant to be branded by the embedder.
			// Skip on the /deploy wizard and /showcase grid too — those replace
			// the viewer with a full-page surface, so a floating chat toggle
			// would just overlap the form/marketplace with nothing to talk to.
			if (
				!this.options.widget &&
				!this.options.kiosk &&
				!this._widgetShell &&
				!this.options.deploy &&
				!this.options.showcase
			) {
				this._initNichAgent();
			}

			// Log all significant actions to identity history (fire-and-forget)
			protocol.on('*', (action) => {
				if (
					[
						ACTION_TYPES.SPEAK,
						ACTION_TYPES.REMEMBER,
						ACTION_TYPES.SIGN,
						ACTION_TYPES.SKILL_DONE,
						ACTION_TYPES.VALIDATE,
						ACTION_TYPES.LOAD_END,
					].includes(action.type)
				) {
					this.identity.recordAction(action);
				}
			});
		} catch (err) {
			log.warn('[3d-agent] Agent system init failed:', err.message);
		}
	}

	_applyViewerMode() {
		const { kiosk, widget, agent, deploy, showcase, embedChat } = this.options;
		let mode = 'main';
		if (kiosk || widget || agent || embedChat) mode = 'embed';
		else if (deploy) mode = 'deploy';
		else if (showcase) mode = 'explore';
		document.body.dataset.viewerMode = mode;
		if (mode === 'main') {
			// Only use 'pending' (hide gate, hide sidebar) when we have a stored 'true' hint —
			// i.e. the user was last seen logged in and may still be. For everyone else (no hint
			// or a 'false' hint) show the auth gate immediately so it never appears after the
			// CZ model renders (which is instant when the GLB is cached from the homepage).
			document.body.dataset.authed = readAuthHint() === 'true' ? 'pending' : 'false';
		}
		this._applyViewerLayout();
	}

	_applyViewerLayout() {
		let stored = null;
		try {
			stored = localStorage.getItem('3dagent:viewer-layout');
		} catch {
			/* ignore — storage may be unavailable in private mode */
		}
		const layout = stored === 'next' ? 'next' : 'classic';
		document.body.dataset.layout = layout;
	}

	_setupNextLayout() {
		// Skip in embed/widget/kiosk/deploy contexts — Next chrome is owner-only.
		if (document.body.dataset.viewerMode !== 'main') return;
		this._nextLayout = new NextLayout(this);
		this._nextLayout.mount();
	}

	_setupLayoutSwitch() {
		const root = document.getElementById('layout-switch');
		if (!root) return;
		if (document.body.dataset.viewerMode !== 'main') return;
		root.hidden = false;

		const buttons = Array.from(root.querySelectorAll('[data-layout-value]'));
		const sync = () => {
			const current = document.body.dataset.layout || 'classic';
			for (const btn of buttons) {
				const active = btn.dataset.layoutValue === current;
				btn.setAttribute('aria-pressed', String(active));
				btn.classList.toggle('layout-switch__btn--active', active);
			}
		};
		sync();

		for (const btn of buttons) {
			btn.addEventListener('click', () => {
				const value = btn.dataset.layoutValue === 'next' ? 'next' : 'classic';
				if (document.body.dataset.layout === value) return;
				document.body.dataset.layout = value;
				try {
					localStorage.setItem('3dagent:viewer-layout', value);
				} catch {
					/* ignore */
				}
				sync();
			});
		}
	}

	async _updateSignInLink() {
		const link = document.getElementById('nav-sign-in');
		try {
			const user = await getMe();
			if (link && user) link.classList.add('signed-in');
			if (user) this._initUserMenu(user);
			if (document.body.dataset.viewerMode === 'main') {
				document.body.dataset.authed = user ? 'true' : 'false';
			}
		} catch {
			if (document.body.dataset.viewerMode === 'main') {
				document.body.dataset.authed = 'false';
			}
		}
	}

	_initUserMenu(user) {
		const wrap = document.getElementById('nav-user-wrap');
		const btn = document.getElementById('nav-user-btn');
		const menu = document.getElementById('nav-user-menu');
		const label = document.getElementById('nav-user-label');
		const profileLink = document.getElementById('nav-my-profile-link');
		const signOutBtn = document.getElementById('nav-sign-out-btn');
		if (!wrap || !btn || !menu) return;

		// A full email is 30+ characters and pushed the whole header cluster off
		// the right edge of a phone. Show the handle (or the address's local
		// part) and keep the full identity in the button's tooltip.
		if (label) {
			const short = user.username || user.display_name || user.email?.split('@')[0] || 'Account';
			label.textContent = short;
			const full = user.email || user.username || short;
			btn.title = full;
			// The label is hidden on phones (see app-next.css), so the identity
			// has to reach assistive tech through the button itself.
			btn.setAttribute('aria-label', `Account: ${full}`);
		}
		if (profileLink && user.address) profileLink.href = `/u/${user.address}`;

		wrap.hidden = false;

		const closeMenu = ({ restoreFocus = false } = {}) => {
			if (menu.hidden) return;
			menu.hidden = true;
			btn.setAttribute('aria-expanded', 'false');
			if (restoreFocus) btn.focus();
		};

		btn.addEventListener('click', (e) => {
			e.stopPropagation();
			const open = menu.hidden === false;
			menu.hidden = open;
			btn.setAttribute('aria-expanded', String(!open));
			// Move focus to the first menu item when opening via keyboard/click
			// so keyboard users land inside the menu they just expanded.
			if (!open) {
				const first = menu.querySelector('a, button');
				if (first) requestAnimationFrame(() => first.focus());
			}
		});

		document.addEventListener('click', () => closeMenu());

		// Escape closes the menu and returns focus to the trigger.
		document.addEventListener('keydown', (e) => {
			if (e.key === 'Escape') closeMenu({ restoreFocus: true });
		});

		menu.addEventListener('click', (e) => e.stopPropagation());

		if (signOutBtn) {
			signOutBtn.addEventListener('click', () => {
				fetch('/api/auth/logout', { method: 'POST', credentials: 'include' })
					.finally(() => {
						try {
							localStorage.removeItem('3dagent:auth-hint');
						} catch {
							/* ignore */
						}
						location.href = '/';
					})
					// `.finally` re-throws a network rejection; swallow it so a
					// failed logout request never surfaces as an unhandled
					// rejection (the user is navigated home regardless).
					.catch(() => {});
			});
		}
	}

	_refreshMakeWidgetButton() {
		const btn = document.getElementById('make-widget-btn');
		if (!btn) return;
		const url = this._currentModelUrl;
		if (!url && !this._hasLocalGlb) {
			btn.hidden = true;
			return;
		}
		if (url) {
			btn.href = `/studio?model=${encodeURIComponent(url)}`;
		}
		btn.hidden = false;
	}

	_refreshSaveToAccountButton() {
		const btn = document.getElementById('save-to-account-btn');
		if (!btn) return;
		const hasModel = this._currentModelUrl || this._hasLocalGlb;
		btn.hidden = !hasModel;
	}

	_refreshOpenInComposerButton() {
		const btn = document.getElementById('open-in-composer-btn');
		if (!btn) return;
		const url = this._currentModelUrl;
		if (url) {
			btn.href = `/compose?glb=${encodeURIComponent(url)}`;
			btn.hidden = false;
		} else {
			btn.hidden = true;
		}
	}

	// Surface the deploy CTA next to the public-profile link in /app. It always
	// reads "Deploy on Solana" and hands the user to the on-chain deployment
	// agent — the guided flow for putting 3D assets on Solana — never to a bare
	// block-explorer wallet page, which dead-ends the user.
	_refreshDeployButton(agentId) {
		const btn = document.getElementById('deploy-onchain-btn');
		if (!btn || !agentId) return;

		const label = btn.querySelector('[data-state-label]');
		btn.classList.remove('is-deployed');
		btn.removeAttribute('target');
		btn.removeAttribute('rel');
		if (label) label.textContent = 'Deploy on Solana';
		btn.setAttribute('aria-label', 'Deploy this 3D asset on Solana');
		btn.setAttribute('title', 'Deploy on Solana — guided on-chain deployment for 3D assets');
		btn.href = ONCHAIN_DEPLOY_AGENT_URL;
		// On the deployment agent's own page the CTA would link to itself — hide it.
		btn.hidden = agentId === ONCHAIN_DEPLOY_AGENT_ID;
	}

	_setupSaveToAccount() {
		const btn = document.getElementById('save-to-account-btn');
		if (!btn) return;
		btn.addEventListener('click', (e) => {
			e.preventDefault();
			this._triggerSaveToAccount();
		});
	}

	_setupMakeWidgetButton() {
		// No auth gate — /studio handles anonymous users gracefully.
	}

	_setupScreenshotButton() {
		const btn = document.getElementById('screenshot-btn');
		if (!btn) return;
		btn.addEventListener('click', async (e) => {
			e.preventDefault();
			if (this.viewer) {
				const blob = await this.viewer.captureScreenshot();
				if (blob) {
					this.screenshotModal.show(blob);
				}
			}
		});
	}

	async _triggerSaveToAccount() {
		const user = await getMe();
		if (!user) {
			await this._stashAndRedirectToLogin();
			return;
		}
		await this._performSave(user);
	}

	async _stashAndRedirectToLogin() {
		const btn = document.getElementById('save-to-account-btn');
		if (btn) {
			btn.setAttribute('disabled', '');
			const label = btn.querySelector('span');
			if (label) label.textContent = 'Preparing…';
		}

		const stash = {
			glbUrl: this._currentModelUrl || null,
			fileName: this._currentLocalFile?.name || null,
			fileB64: null,
			returnTo: '/app',
			agentId: this._editingAgentId || null,
			ts: Date.now(),
		};

		// Local file drops can't be re-hydrated from a blob URL after reload.
		// Encode as base64 and stash — sessionStorage quota is ~5MB, so this
		// fails gracefully for oversized GLBs (user re-drops after sign-in).
		if (this._currentLocalFile) {
			try {
				stash.fileB64 = await _blobToBase64(this._currentLocalFile);
				stash.contentType = this._currentLocalFile.type || 'model/gltf-binary';
			} catch {
				/* fall through without file data */
			}
		}

		try {
			sessionStorage.setItem('pending_save', JSON.stringify(stash));
		} catch {
			// Quota exceeded — drop the file payload and retry with just metadata
			delete stash.fileB64;
			try {
				sessionStorage.setItem('pending_save', JSON.stringify(stash));
			} catch {
				/* storage disabled — proceed without stash */
			}
		}
		location.href = '/login?next=' + encodeURIComponent('/app?pending=1');
	}

	async _performSave(user) {
		if (!user) return;
		const btn = document.getElementById('save-to-account-btn');
		if (btn) {
			btn.setAttribute('disabled', '');
			const label = btn.querySelector('span');
			if (label) label.textContent = 'Saving…';
		}
		try {
			let avatarId;
			const source = this._currentLocalFile || this._currentModelUrl;
			if (!source) {
				// Nothing to save — reset UI and bail
				if (btn) {
					btn.removeAttribute('disabled');
					const label = btn.querySelector('span');
					if (label) label.textContent = 'Save to account';
				}
				return;
			}
			const avatar = await saveRemoteGlbToAccount(source, {
				source: this._currentLocalFile ? 'upload' : 'import',
				name: this._currentLocalFile?.name,
				source_meta: this._currentLocalFile
					? { original_filename: this._currentLocalFile.name }
					: undefined,
			});
			avatarId = avatar.id;

			if (this._editingAgentId) {
				// Update existing agent's avatar
				if (avatarId) {
					await apiFetch(`/api/agents/${this._editingAgentId}`, {
						method: 'PUT',
						credentials: 'include',
						headers: { 'content-type': 'application/json' },
						body: JSON.stringify({ avatar_id: avatarId }),
					});
				}
				location.href = `/agents/${this._editingAgentId}`;
			} else {
				// Create a new agent linked to the uploaded avatar
				const res = await fetch('/api/agents/me', {
					method: 'GET',
					credentials: 'include',
				});
				const data = res.ok ? await res.json() : null;
				let agentId = data?.agent?.id;

				if (!agentId) {
					const created = await apiFetch('/api/agents', {
						method: 'POST',
						credentials: 'include',
						headers: { 'content-type': 'application/json' },
						body: JSON.stringify({ name: 'My Agent' }),
					});
					const createdData = created.ok ? await created.json() : null;
					agentId = createdData?.agent?.id;
				}

				if (agentId && avatarId) {
					await apiFetch(`/api/agents/${agentId}`, {
						method: 'PUT',
						credentials: 'include',
						headers: { 'content-type': 'application/json' },
						body: JSON.stringify({ avatar_id: avatarId }),
					});
				}

				if (agentId) {
					location.href = `/agents/${agentId}`;
				} else {
					this._flashSaved({ name: 'your account' });
					if (btn) {
						btn.removeAttribute('disabled');
						const label = btn.querySelector('span');
						if (label) label.textContent = 'Save to account';
					}
				}
			}
		} catch (err) {
			log.warn('[3d-agent] save failed:', err.message);
			if (btn) {
				btn.removeAttribute('disabled');
				const label = btn.querySelector('span');
				if (label) label.textContent = 'Save to account';
			}
		}
	}

	async _maybePendingSave() {
		let stash;
		try {
			const raw = sessionStorage.getItem('pending_save');
			if (!raw) return;
			stash = JSON.parse(raw);
		} catch {
			return;
		}

		// Stale stashes (older than 1 hour) are discarded — the user likely
		// abandoned the sign-in flow and we shouldn't silently replay old work.
		if (!stash || !stash.ts || Date.now() - stash.ts > 60 * 60 * 1000) {
			sessionStorage.removeItem('pending_save');
			return;
		}

		const user = await getMe();
		if (!user) return; // still not authed — leave stash intact

		sessionStorage.removeItem('pending_save');

		// Restore the editing context from the stash
		if (stash.agentId) this._editingAgentId = stash.agentId;

		// Re-hydrate the model: local file (base64) takes priority over remote URL
		if (stash.fileB64 && stash.fileName) {
			const file = _base64ToFile(
				stash.fileB64,
				stash.fileName,
				stash.contentType || 'model/gltf-binary',
			);
			await this.load(new Map([[stash.fileName, file]]));
		} else if (stash.glbUrl && stash.glbUrl !== this._currentModelUrl) {
			await this.view(stash.glbUrl, '', new Map());
		}

		// Strip ?pending from URL before saving
		const clean = new URL(location.href);
		clean.searchParams.delete('pending');
		history.replaceState(null, '', clean.toString());

		await this._performSave(user);
	}

	async _loadAgent(agentId) {
		this.identity = new AgentIdentity({ agentId, autoLoad: false });
		await this.identity.load();

		let glbUrl = '/avatars/cz.glb';
		this._currentUsdzUrl = null;
		this._currentHalfbodyUrl = null;
		if (this.identity.avatarId) {
			try {
				const resp = await fetch(`/api/avatars/${this.identity.avatarId}`, {
					credentials: 'include',
				});
				if (resp.ok) {
					const { avatar } = await resp.json();
					if (avatar?.url) glbUrl = avatar.url;
					this._currentUsdzUrl = avatar?.usdz_url || null;
					this._currentHalfbodyUrl = avatar?.halfbody_url || null;
				}
			} catch {
				/* fall through to default */
			}
		}

		this.view(glbUrl, '', new Map());
		this._initAgentSystem();
	}

	async _loadAgentForEdit(agentId) {
		// Reset onboarding gate so a retry can re-fire it once the GLB actually
		// loads. The localStorage gate inside _maybeShowOnboarding still
		// guarantees once-per-agent in steady state.
		this._onboardingFired = false;

		// Mount the canvas up-front so the loading/error overlay has a parent
		// and the page layout never collapses around an empty container.
		if (!this.viewer && !this.createViewer()) return; // WebGL fallback shown

		// Surface a loading state immediately — the identity name lookup
		// below may take a moment, and the user shouldn't see an empty stage.
		this._showViewerLoading('Loading your avatar…');

		// Swap this.identity to the agent being edited so AgentHome (and the
		// Solana wallet card) render for *this* agent rather than the viewer's
		// default identity.
		this.identity = new AgentIdentity({ agentId, autoLoad: false });
		try {
			await this.identity.load();
		} catch {
			/* fall through; identity getter still returns _agentId */
		}

		// Refresh the loading label now that we know the agent's name.
		if (this.identity?.name) {
			this._showViewerLoading(`Loading ${this.identity.name}…`);
		}

		// Fetch the agent record and resolve its GLB URL.
		let glbUrl = null;
		let fetchFailed = false;
		let thumbnailUrl = null;
		this._currentUsdzUrl = null;
		this._currentHalfbodyUrl = null;
		this._currentAvatarId = null;
		this._currentAvatarGlbUrl = null;
		this._avatarNeedsThumbnail = false;
		try {
			const resp = await fetch(`/api/agents/${agentId}`, { credentials: 'include' });
			if (resp.ok) {
				const { agent } = await resp.json();
				if (agent?.avatar_id) {
					const avatarResp = await fetch(`/api/avatars/${agent.avatar_id}`, {
						credentials: 'include',
					});
					if (avatarResp.ok) {
						const { avatar } = await avatarResp.json();
						if (avatar?.url) glbUrl = avatar.url;
						this._currentUsdzUrl = avatar?.usdz_url || null;
						this._currentHalfbodyUrl = avatar?.halfbody_url || null;
						this._currentAvatarId = avatar?.id || null;
						this._currentAvatarGlbUrl = avatar?.url || null;
						thumbnailUrl = avatar?.thumbnail_url || null;
						// Flag for the LOAD_END(success) listener to capture
						// and upload a thumbnail once the avatar is rendered.
						this._avatarNeedsThumbnail = !thumbnailUrl && !!glbUrl;
					} else {
						fetchFailed = true;
					}
				}
			} else {
				fetchFailed = true;
			}
		} catch {
			fetchFailed = true;
		}

		// Show the thumbnail as a poster behind the canvas so a 4-5 MB GLB
		// stream isn't a black void. Crossfades out on LOAD_END(success).
		if (thumbnailUrl) this._showPoster(thumbnailUrl);

		// Three outcomes:
		//   1. GLB URL found       → load it. Success/error overlay is driven
		//      by the LOAD_END protocol listener.
		//   2. Agent has no avatar → load the default CZ avatar so the editor
		//      is usable; no error overlay (this is a legitimate state).
		//   3. Agent fetch failed  → show error overlay with Retry. Still
		//      load the default CZ so the editor canvas isn't empty.
		if (glbUrl) {
			this.view(glbUrl, '', new Map());
		} else if (fetchFailed) {
			// Don't trigger a fallback load — its LOAD_START would clobber
			// the error overlay. The renderer is already mounted from
			// createViewer() above; the user sees the error message on top
			// of an empty 3D scene, which honestly reflects the state.
			this._showViewerError("Couldn't load your avatar.", () => this._retryAgentLoad());
		} else {
			// Agent has no avatar attached yet — load the default so the
			// editor is usable. LOAD_END will hide the overlay normally.
			this._maybeResumeOrLoad(this.options);
		}

		// Restore + auto-save per-agent scene preferences (background, env,
		// exposure, auto-rotate) so the editor feels like coming back to
		// "your studio" rather than a generic default each time.
		if (this.viewer && this.viewer.attachScenePrefs) {
			this.viewer.attachScenePrefs(agentId);
		}

		const publicLink = document.getElementById('view-public-profile-btn');
		if (publicLink) {
			publicLink.href = `/agents/${agentId}`;
			publicLink.hidden = false;
		}

		this._refreshDeployButton(agentId);

		// Onboarding is fired from the LOAD_END(success) listener so the
		// "ready" popup only appears once the avatar is actually on screen.

		this._initAgentSystem();
		this._initWidgetBridge();
	}

	// First-time orientation overlay for a freshly created (or freshly loaded)
	// agent. Localstorage-keyed per agent so it never reappears once dismissed.
	_maybeShowOnboarding(agentId) {
		if (typeof window === 'undefined' || !agentId) return;
		// Only the main viewer has a 3D stage to onboard. On page modes
		// (/deploy, /explore, embeds) the fixed card just covers content.
		if ((document.body?.dataset.viewerMode || 'main') !== 'main') return;
		const key = `3dagent:onboarded:${agentId}`;
		try {
			if (localStorage.getItem(key)) return;
		} catch {
			return;
		}

		const banner = document.getElementById('agent-onboarding');
		if (!banner) return;

		const closeBtn = document.getElementById('agent-onboarding-close');
		const deployLink = document.getElementById('agent-onboarding-deploy');
		const shareLink = document.getElementById('agent-onboarding-share');

		if (deployLink) deployLink.href = `/deploy?agent=${agentId}`;
		if (shareLink) shareLink.href = `/agents/${agentId}`;

		// Remember what had focus so we can restore it when the dialog closes.
		const prevFocus = document.activeElement;

		const dismiss = ({ restoreFocus = false } = {}) => {
			banner.hidden = true;
			banner.removeEventListener('keydown', onKeydown);
			try {
				localStorage.setItem(key, '1');
			} catch {}
			if (restoreFocus && prevFocus && typeof prevFocus.focus === 'function') {
				prevFocus.focus();
			}
		};

		// Escape closes the orientation dialog and restores focus to the trigger.
		const onKeydown = (e) => {
			if (e.key === 'Escape') {
				e.preventDefault();
				dismiss({ restoreFocus: true });
			}
		};
		banner.addEventListener('keydown', onKeydown);

		if (closeBtn) closeBtn.addEventListener('click', () => dismiss({ restoreFocus: true }));
		// Auto-dismiss when the user clicks any of the CTAs — they've engaged.
		[deployLink, shareLink].forEach((el) => {
			if (el) el.addEventListener('click', () => dismiss());
		});

		// Flow into the shared corner-stack so the card sits above the
		// getting-started pill instead of overlapping it. If the stack isn't ready
		// yet, anchor the card to <body> and tag it so the stack adopts it on
		// load; ensureCornerStack() pulls the module in if nothing else has.
		banner.setAttribute('data-corner-priority', '20');
		if (window.twsCornerStack) {
			window.twsCornerStack.mount(banner);
		} else {
			document.body.appendChild(banner);
			ensureCornerStack();
		}
		banner.hidden = false;
		// Move focus into the dialog so keyboard/screen-reader users are taken
		// to the freshly-revealed orientation message.
		if (closeBtn) requestAnimationFrame(() => closeBtn.focus());
	}

	async _loadWidget(widgetId) {
		let widget;
		try {
			widget = await getWidget(widgetId);
		} catch (err) {
			this._showWidgetError(`Widget not found: ${widgetId}`);
			return;
		}
		window.VIEWER.widget = widget;

		// Fire-and-forget view beacon for analytics. Skip three cases:
		//   • owner previews (Studio + dashboard pass &preview=1) — creator
		//     QA cycles shouldn't pollute stats
		//   • script-embed iframes (embed.js passes &embedded=1) — embed.js
		//     fires its own visibility-triggered beacon, this would double-count
		//   • the host page already counted (no flag) — direct visits to
		//     /w/:id or /app#widget=… always fire here
		try {
			const qs = new URLSearchParams(location.search);
			const hash = new URLSearchParams((location.hash || '#').slice(1));
			const isPreview = qs.get('preview') === '1' || hash.get('preview') === '1';
			const fromEmbed = hash.get('embedded') === '1';
			if (!isPreview && !fromEmbed) {
				const url = `/api/widgets/${encodeURIComponent(widgetId)}/view`;
				if (navigator.sendBeacon) {
					navigator.sendBeacon(url, new Blob([''], { type: 'text/plain' }));
				} else {
					fetch(url, {
						method: 'POST',
						keepalive: true,
						credentials: 'omit',
						mode: 'no-cors',
					});
				}
			}
		} catch {
			/* best-effort */
		}

		// The walking avatar isn't a turntable-viewer widget — it lives in the
		// chrome-less /walk-embed iframe with its own scene + controls. The slim
		// /widget shell (and the /w/:id share page that hands off to it) redirect
		// here so a saved walking-avatar widget renders its real runtime instead
		// of an empty viewer. The view beacon above has already fired.
		if (widget.type === 'walking-avatar') {
			location.replace(walkEmbedUrlForWidget(widget));
			return;
		}

		const cfg = { ...(widget.config || {}) };
		const modelUrl = widget.avatar?.model_url || '/avatars/cz.glb';

		// Apply per-embed URL overrides (set by Studio embed modal checkboxes).
		if (this.options.noAnimations) cfg.showClipPicker = false;
		if (this.options.noChat) cfg._noChat = true;
		if (this.options.noControls) cfg.showControls = false;
		if (this.options.avatarChatOff) cfg.avatarChatOff = true;

		// Live-customizer hash overrides (validated lightly — bad input is ignored).
		const HEX = /^#[0-9a-fA-F]{3,8}$/;
		if (this.options.overrideAccent && HEX.test(this.options.overrideAccent)) {
			cfg.accent = this.options.overrideAccent;
		}
		if (this.options.overrideBg && HEX.test(this.options.overrideBg)) {
			cfg.background = this.options.overrideBg;
			cfg.bg = this.options.overrideBg;
		}
		if (this.options.overrideMint) cfg.mint = this.options.overrideMint;
		if (
			this.options.overrideKind &&
			['all', 'claims', 'graduations'].includes(this.options.overrideKind)
		) {
			cfg.kind = this.options.overrideKind;
		}
		if (
			this.options.overrideMinTier &&
			['', 'notable', 'influencer', 'mega'].includes(this.options.overrideMinTier)
		) {
			cfg.minTier = this.options.overrideMinTier;
		}

		// Apply config to options BEFORE creating the viewer so first frame is right.
		if (Array.isArray(cfg.cameraPosition) && cfg.cameraPosition.length === 3) {
			this.options.cameraPosition = cfg.cameraPosition;
		}
		if (cfg.envPreset && cfg.envPreset !== 'none') {
			this.options.preset = cfg.envPreset;
		}

		// Kiosk + showControls drive the chrome.
		if (cfg.showControls === false || this.options.kiosk) {
			document.querySelector('header')?.style.setProperty('display', 'none');
		}

		const resolved = resolveModelUrl(modelUrl);
		this.view(resolved, '', new Map());

		// Apply post-create brand bits once viewer exists.
		queueMicrotask(() => this._applyWidgetConfig(cfg));

		// Type-specific mount (runs after viewer + content come up).
		queueMicrotask(() => this._mountWidgetByType(widget.type, cfg, widget.id));

		// Caption overlay — render once, simple.
		if (cfg.caption) this._renderWidgetCaption(cfg.caption);

		// Notify parent (script embed / Studio) that we're up.
		this._postToParent({ type: 'widget:ready', id: widget.id, widgetType: widget.type });
	}

	async _mountWidgetByType(type, cfg, widgetId) {
		try {
			if (type === 'animation-gallery') {
				const container = document.body;
				const ctl = await mountAnimationGallery(this.viewer, cfg, container);
				this._widgetController = ctl;
			} else if (type === 'talking-agent' && !cfg._noChat) {
				const ctl = await mountTalkingAgent(this.viewer, cfg, document.body, {
					widgetId,
					getSceneCtrl: () => this.sceneCtrl || window.VIEWER?.scene_ctrl || null,
					protocol,
					identity: this.identity,
					onMessage: (turn) => {
						this._postToParent({
							type: 'widget:chat:message',
							id: widgetId,
							role: turn.role,
							content: turn.content,
						});
					},
				});
				this._widgetController = ctl;
			} else if (type === 'turntable') {
				const ctl = await mountTurntable(this.viewer, cfg);
				this._widgetController = ctl;
			} else if (type === 'hotspot-tour') {
				const ctl = await mountHotspotTour(this.viewer, cfg, document.body, {
					onOpen: (hotspot) => {
						this._postToParent({
							type: 'widget:hotspot:open',
							id: hotspot?.id ?? null,
							label: hotspot?.label ?? null,
							widgetId,
						});
					},
				});
				this._widgetController = ctl;
			} else if (type === 'pumpfun-feed') {
				const ctl = await mountPumpfunFeed(this.viewer, cfg, document.body, { protocol });
				this._widgetController = ctl;
			} else if (type === 'kol-trades') {
				const host = document.createElement('div');
				host.className = 'kol-trades-host';
				host.style.cssText =
					'position:absolute;top:16px;right:16px;width:min(360px,calc(100% - 32px));max-height:calc(100% - 32px);overflow-y:auto;background:rgba(14,14,22,0.86);backdrop-filter:blur(6px);border:1px solid rgba(255,255,255,0.08);border-radius:12px;padding:8px 10px;z-index:5';
				document.body.appendChild(host);
				const inner = mountKolTradesWidget(host, {
					mint: cfg.mint,
					limit: cfg.limit,
					refreshMs: cfg.refreshMs,
				});
				this._widgetController = {
					destroy() {
						inner?.destroy?.();
						host.remove();
					},
				};
			} else if (type === 'live-trades-canvas') {
				const ctl = mountLiveTradesCanvas(document.body, {
					mint: cfg.mint,
					chain: cfg.chain,
					bg: cfg.bg || cfg.background,
					minUsd: cfg.minUsd,
				});
				this._widgetController = ctl;
			} else if (type === 'bonding-curve') {
				const host = document.createElement('div');
				host.className = 'bonding-curve-host';
				host.style.cssText =
					'position:absolute;inset:0;display:grid;place-items:center;padding:24px;z-index:5;pointer-events:none;box-sizing:border-box';
				document.body.appendChild(host);
				const inner = mountBondingCurve(host, {
					mint: cfg.mint,
					network: cfg.network,
					refreshMs: cfg.refreshMs,
					showUsd: cfg.showUsd,
					accent: cfg.accent,
					showPoweredBy: cfg.showPoweredBy,
				});
				this._widgetController = {
					destroy() {
						inner?.destroy?.();
						host.remove();
					},
				};
			} else if (type === 'passport') {
				const ctl = await mountPassport(this.viewer, cfg, document.body, widgetId);
				this._widgetController = ctl;
			}
		} catch (e) {
			log.warn('[widget] mount failed', type, e?.message);
		}
	}

	_applyWidgetConfig(cfg) {
		if (!this.viewer) return;
		try {
			if (cfg.background) this.viewer.setBackgroundColor(cfg.background);
			if (cfg.accent) {
				document.documentElement.style.setProperty('--accent', cfg.accent);
				const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(cfg.accent);
				if (m) {
					document.documentElement.style.setProperty(
						'--accent-soft',
						`rgba(${parseInt(m[1], 16)},${parseInt(m[2], 16)},${parseInt(m[3], 16)},0.18)`,
					);
				}
			}
			if (typeof cfg.autoRotate === 'boolean' && this.viewer.controls) {
				this.viewer.controls.autoRotate = cfg.autoRotate;
				if (typeof cfg.rotationSpeed === 'number') {
					this.viewer.controls.autoRotateSpeed = cfg.rotationSpeed;
				}
			}
			if (cfg.envPreset && this.viewer.setEnvironment) {
				this.viewer.setEnvironment(cfg.envPreset);
			}
		} catch (e) {
			log.warn('[widget] applyConfig failed', e?.message);
		}
	}

	_renderWidgetCaption(text) {
		let el = document.getElementById('widget-caption');
		if (!el) {
			el = document.createElement('div');
			el.id = 'widget-caption';
			el.style.cssText =
				'position:fixed;left:50%;bottom:20px;transform:translateX(-50%);padding:8px 18px;background:rgba(0,0,0,0.55);color:#fff;font-family:Inter,system-ui,sans-serif;font-size:14px;border-radius:999px;backdrop-filter:blur(8px);z-index:5;pointer-events:none;max-width:90vw;text-align:center';
			document.body.appendChild(el);
		}
		el.textContent = text;
	}

	_showWidgetError(message) {
		const el = document.createElement('div');
		el.style.cssText =
			'position:fixed;inset:0;display:grid;place-items:center;background:#0a0a0a;color:#e0e0e0;font-family:Inter,system-ui,sans-serif;text-align:center;padding:2rem;z-index:9999';
		el.setAttribute('role', 'alert');
		el.innerHTML = `<div><h2 style="font-weight:300;margin:0 0 0.5rem">Widget unavailable</h2><p style="opacity:0.7;margin:0">${message.replace(/[<>&"]/g, '')}</p><p style="margin-top:1.5rem"><a href="/" style="color:#ffffff">Open viewer</a> · <a href="/widgets" style="color:#ffffff">Browse gallery</a></p></div>`;
		document.body.appendChild(el);
	}

	_initWidgetBridge() {
		// MintScene bridge: { id, action, input } envelope from any parent frame.
		// Handles exportGLB and takeScreenshot (returning base64 data to caller).
		window.addEventListener('message', (event) => {
			const data = event.data;
			if (
				!data ||
				typeof data !== 'object' ||
				typeof data.id !== 'string' ||
				typeof data.action !== 'string'
			)
				return;
			// Only handle our specific action verbs to avoid intercepting unrelated messages.
			if (data.action !== 'exportGLB' && data.action !== 'takeScreenshot') return;
			if (!event.origin || event.origin === 'null') return;
			if (!this._parentOrigin) this._parentOrigin = event.origin;
			const replyOrigin = event.origin;
			const replyTo = event.source || window.parent;
			const reply = (result, err) => {
				try {
					replyTo.postMessage(
						err ? { id: data.id, error: err } : { id: data.id, result },
						replyOrigin,
					);
				} catch (_) {}
			};
			const viewer = this.viewer || window.VIEWER?.app?.viewer;
			if (!viewer) return reply(null, 'viewer not ready');
			if (data.action === 'takeScreenshot') {
				try {
					viewer.renderer.render(viewer.scene, viewer.activeCamera);
					const dataUrl = viewer.renderer.domElement.toDataURL('image/png');
					reply(dataUrl.replace('data:image/png;base64,', ''));
				} catch (e) {
					reply(null, e.message);
				}
				return;
			}
			if (data.action === 'exportGLB') {
				const scene = viewer.scene;
				const content = viewer.content;
				if (!content) return reply(null, 'no model loaded');
				import('three/addons/exporters/GLTFExporter.js')
					.then(({ GLTFExporter }) => {
						const exporter = new GLTFExporter();
						exporter.parse(
							content,
							(result) => {
								const bytes =
									result instanceof ArrayBuffer ? result : result.buffer;
								let binary = '';
								const arr = new Uint8Array(bytes);
								for (let i = 0; i < arr.length; i++)
									binary += String.fromCharCode(arr[i]);
								reply(btoa(binary));
							},
							(err) => {
								reply(null, String(err?.message || err));
							},
							{ binary: true },
						);
					})
					.catch((e) => {
						reply(null, 'GLTFExporter load failed: ' + e.message);
					});
				return;
			}
		});

		// Studio sends live config updates without a full reload. Also handles
		// runtime commands (play_clip, wave) for parent-driven embeds.
		window.addEventListener('message', (event) => {
			if (event.origin !== location.origin) return;
			const data = event.data;
			if (!data || typeof data !== 'object') return;

			if (data.type === 'widget:config' && data.config) {
				this._applyWidgetConfig(data.config);
				if (typeof data.config.caption === 'string') {
					this._renderWidgetCaption(data.config.caption);
				}
				// Preview mode (#model= + type=): mount widget runtime on first config message.
				if (this.options.type && !this._previewMounted) {
					this._previewMounted = true;
					this._mountWidgetByType(this.options.type, data.config, null).catch(() => {});
				}
				return;
			}

			if (data.type === 'widget:command' && data.command) {
				this._handleWidgetCommand(data.command, data.args || {});
			}

			// Forward pumpfun-feed focus changes from the parent frame to the
			// mounted widget overlay (which listens on document.body).
			if (data.type === 'pumpfun-feed:focus-mint') {
				document.body.dispatchEvent(
					new CustomEvent('pumpfun-feed:focus-mint', {
						detail: { mint: data.mint || null },
						bubbles: true,
					}),
				);
			}
			if (data.type === 'pumpfun-feed:set-narrate') {
				document.body.dispatchEvent(
					new CustomEvent('pumpfun-feed:set-narrate', {
						detail: { on: !!data.on },
						bubbles: true,
					}),
				);
			}
			if (data.type === 'pumpfun-feed:set-mood') {
				document.body.dispatchEvent(
					new CustomEvent('pumpfun-feed:set-mood', {
						detail: { mood: data.mood },
						bubbles: true,
					}),
				);
			}

			// Host-page reaction bridge: when the parent /pumpfun.html page
			// observes a feed event, it can ask the avatar to emote/dance
			// without having to mount the full widget overlay.
			if (data.type === 'pumpfun-feed:react' && data.reaction) {
				try {
					const proto = window.VIEWER?.agent_protocol || protocol;
					const r = data.reaction;
					if (proto && r.emote) proto.emit({ type: 'emote', payload: r.emote });
					if (proto && r.lookAt)
						proto.emit({ type: 'look-at', payload: { target: r.lookAt } });
					if (proto && r.gesture) proto.emit({ type: 'gesture', payload: r.gesture });
					if (proto && r.speak && data.speak !== false) {
						proto.emit({ type: 'speak', payload: r.speak });
					}
				} catch {}
			}
		});
	}

	_handleWidgetCommand(command, args) {
		const sceneCtrl = this.sceneCtrl || window.VIEWER?.scene_ctrl;
		if (!sceneCtrl) return;
		try {
			switch (command) {
				case 'play_clip':
					sceneCtrl.playClipByName?.(args.name);
					break;
				case 'lookAt':
					sceneCtrl.lookAt?.(args.target);
					break;
				case 'setExpression':
					sceneCtrl.setExpression?.(args.name, args.weight);
					break;
			}
		} catch (e) {
			log.warn('[widget] command failed', command, e?.message);
		}
	}

	_postToParent(msg) {
		if (!window.parent || window.parent === window) return;
		if (!this._parentOrigin) {
			try {
				if (document.referrer) this._parentOrigin = new URL(document.referrer).origin;
			} catch {}
		}
		if (!this._parentOrigin) {
			log.warn('[widget] parent origin unknown; dropping', msg?.type);
			return;
		}
		window.parent.postMessage(msg, this._parentOrigin);
	}

	_initNichAgent() {
		const bubble = this.viewer ? new ThoughtBubble(this.viewer) : null;
		const agent = new NichAgent(
			document.body,
			protocol,
			this.skills,
			this.identity,
			this.runtime,
			{ thoughtBubble: bubble },
		);
		window.VIEWER.agent = agent;
		// Greet on first open
		agent.onFirstOpen = () => {
			this.skills.perform('greet', {}, { identity: this.identity });
		};
	}

	// ── Viewer setup + Avatar attachment ────────────────────────────────────

	/**
	 * Sets up the view manager.
	 * @return {Viewer}
	 */
	createViewer() {
		if (this.viewer) this.viewer.dispose();
		this.viewerEl = this.viewerContainerEl;
		// A GPU/driver without an available WebGL context (headless browser, a
		// blocked context, or the per-tab context budget exhausted) makes the
		// Viewer constructor throw "Error creating WebGL context". Catch it and
		// show a designed fallback instead of letting it bubble as an unhandled
		// rejection that leaves the stage blank.
		try {
			this.viewer = new Viewer(this.viewerEl, this.options);
		} catch (err) {
			log.error('[3d-agent] WebGL viewer init failed:', err);
			this.viewer = null;
			this._showWebglUnavailable();
			return null;
		}
		initWalletButton();

		if (!this.options.kiosk) {
			this.editor = new Editor(this.viewer);
			this.editor.attach();
			window.VIEWER.editor = this.editor;
		}
		window.VIEWER.viewer = this.viewer;
		return this.viewer;
	}

	// Cheap, cached probe for WebGL support so we can show the fallback BEFORE
	// constructing the (expensive) Viewer on devices that plainly can't render.
	_webglAvailable() {
		if (typeof this._webglOk === 'boolean') return this._webglOk;
		let ok = false;
		try {
			const canvas = document.createElement('canvas');
			const gl =
				canvas.getContext('webgl2') ||
				canvas.getContext('webgl') ||
				canvas.getContext('experimental-webgl');
			ok = !!(window.WebGLRenderingContext && gl && typeof gl.getParameter === 'function');
			// Release the probe context immediately so it never counts against the
			// browser's per-tab WebGL context budget.
			const lose = gl && gl.getExtension && gl.getExtension('WEBGL_lose_context');
			if (lose) lose.loseContext();
		} catch {
			ok = false;
		}
		this._webglOk = ok;
		return ok;
	}

	// ── Dropzone ─────────────────────────────────────────────────────────────

	createDropzone() {
		const dropCtrl = new SimpleDropzone(this.dropEl, this.inputEl);
		dropCtrl.on('drop', ({ files }) => this.load(files));
		dropCtrl.on('dropstart', () => this.showSpinner());
		dropCtrl.on('droperror', () => this.hideSpinner());

		// Reflect drag state on <body> so the dropzone bar can highlight.
		let dragDepth = 0;
		const wrap = this.dropEl;
		wrap.addEventListener('dragenter', (e) => {
			if (!e.dataTransfer || !Array.from(e.dataTransfer.types || []).includes('Files'))
				return;
			dragDepth += 1;
			document.body.classList.add('is-dragover');
		});
		wrap.addEventListener('dragleave', () => {
			dragDepth = Math.max(0, dragDepth - 1);
			if (dragDepth === 0) document.body.classList.remove('is-dragover');
		});
		wrap.addEventListener('drop', () => {
			dragDepth = 0;
			document.body.classList.remove('is-dragover');
		});
	}

	// ── Avatar Creator ────────────────────────────────────────────────────────

	setupAvatarCreator() {
		this.avatarCreator = new AvatarCreator(document.body, async (glbSource) => {
			this.view(glbSource, '', new Map());
			try {
				const avatar = await saveRemoteGlbToAccount(glbSource, {
					source: 'avaturn',
					source_meta: { provider: 'avaturn' },
				});
				this._flashSaved(avatar);
			} catch (err) {
				if (err.code !== 'not_signed_in') {
					log.warn('[3d-agent] save to account failed:', err.message);
				}
			}
		});
	}

	// ── File Loading ──────────────────────────────────────────────────────────

	/**
	 * @param  {Map<string, File>} fileMap
	 */
	load(fileMap) {
		let rootFile, rootPath;
		Array.from(fileMap).forEach(([path, file]) => {
			if (file.name.match(/\.(gltf|glb)$/)) {
				rootFile = file;
				rootPath = path.replace(file.name, '');
			}
		});

		if (!rootFile) {
			// No model in the dropped/selected set — show the designed error and
			// stop. Falling through to view() would hand `undefined` to
			// URL.createObjectURL ("Overload resolution failed") and throw an
			// uncaught TypeError that pages the ops channel.
			//
			// onError alone is console-only, so a user who dropped a .txt or a
			// texture folder saw nothing happen at all. Retrying the same bad file
			// is pointless; the recovery is to pick a different one, so re-open the
			// picker and leave the stage clear rather than flashing a fake load.
			// Warn, not error: picking the wrong file is ordinary user input, and
			// the overlay below is now the surface that reports it.
			this.hideSpinner();
			log.warn('[3d-agent] no .gltf or .glb asset in selection');
			this._showViewerError(
				'No .gltf or .glb file in that drop. Pick a model file to view it.',
				() => this.inputEl?.click(),
				{ actionLabel: 'Choose a file', keepOpenUntilLoad: true },
			);
			return;
		}

		return this.view(rootFile, rootPath, fileMap);
	}

	/**
	 * @param  {File|string} rootFile
	 * @param  {string} rootPath
	 * @param  {Map<string, File>} fileMap
	 */
	view(rootFile, rootPath, fileMap) {
		// Bail to the designed fallback before touching the viewer on devices with
		// no WebGL — otherwise the constructor throws and the stage stays blank.
		if (!this.viewer && !this._webglAvailable()) {
			this._showWebglUnavailable();
			return;
		}
		if (this.viewer) this.viewer.clear();

		const viewer = this.viewer || this.createViewer();
		if (!viewer) return; // WebGL init failed — fallback already shown
		const fileURL = typeof rootFile === 'string' ? rootFile : URL.createObjectURL(rootFile);

		this._currentModelUrl = typeof rootFile === 'string' ? rootFile : null;
		this._hasLocalGlb = typeof rootFile !== 'string';
		this._currentLocalFile = typeof rootFile !== 'string' ? rootFile : null;
		// Replay handle for the error overlay. Anonymous visitors on /app have no
		// agent to re-fetch, so without this a failed load left a dead-end card with
		// no way back. Replaying the same arguments is safe for a dropped File too:
		// view() mints a fresh object URL, so cleanup()'s revoke doesn't strand it.
		this._retryLastView = () => this.view(rootFile, rootPath, fileMap);
		this._refreshMakeWidgetButton();
		this._refreshSaveToAccountButton();
		this._refreshOpenInComposerButton();

		// Emit load start
		protocol.emit({
			type: ACTION_TYPES.LOAD_START,
			payload: { url: typeof rootFile === 'string' ? rootFile : rootFile.name },
			agentId: this.identity?.id || 'default',
		});

		const cleanup = () => {
			this.hideSpinner();
			if (typeof rootFile === 'object') URL.revokeObjectURL(fileURL);
		};

		return viewer
			.load(fileURL, rootPath, fileMap, (xhr) => {
				// Emit download progress. `total` is 0 when Content-Length
				// is missing (blob URLs, some CDNs) — the overlay falls back
				// to an indeterminate spinner in that case.
				const total = xhr?.total > 0 ? xhr.total : 0;
				const loaded = xhr?.loaded || 0;
				protocol.emit({
					type: ACTION_TYPES.LOAD_PROGRESS,
					payload: { loaded, total, indeterminate: total === 0 },
					agentId: this.identity?.id || 'default',
				});
			})
			.catch((e) => {
				// Emit load error
				protocol.emit({
					type: ACTION_TYPES.LOAD_END,
					payload: { error: e?.message || String(e), errorObj: e },
					agentId: this.identity?.id || 'default',
				});
				this.onError(e);
			})
			.then((gltf) => {
				if (!gltf) return;

				// Emit load success
				protocol.emit({
					type: ACTION_TYPES.LOAD_END,
					payload: { success: true },
					agentId: this.identity?.id || 'default',
				});

				// Attach the avatar empathy system to the newly loaded content
				this._attachAvatar(viewer);

				// Notify the editor of the new model so it can rebuild panels
				if (this.editor) {
					const isString = typeof rootFile === 'string';
					this.editor.onContentChanged({
						url: isString ? rootFile : null,
						file: isString ? null : rootFile,
						name: isString ? rootFile.split('/').pop().split('?')[0] : rootFile.name,
					});
				}

				// Configure external animations (Mixamo-style) for skinned models
				this._configureAnimations(viewer);

				// Update AR button target. iOS Quick Look uses the USDZ companion
				// when present; Android/WebXR fall back to the GLB URL. Both come
				// from the avatar record fetched before view() (_currentUsdzUrl).
				if (viewer.setARTarget) {
					const glbUrl = typeof rootFile === 'string' ? fileURL : null;
					viewer.setARTarget(glbUrl, this._currentUsdzUrl || null);
				}

				if (!this.options.kiosk) {
					this.validator.validate(fileURL, rootPath, fileMap, gltf);
				}
				cleanup();
			});
	}

	/** Attach (or reattach) the AgentAvatar to the viewer after content loads */
	_attachAvatar(viewer) {
		if (this.avatar) this.avatar.detach();
		this.avatar = new AgentAvatar(viewer, protocol, this.identity);
		this.avatar.attach();

		// This agent's own gesture bindings (meta.edits.animations, written by
		// PUT /api/agents/:id/animations with animationSlots). Nothing used to
		// apply them, so the override map documented since the slot system landed
		// had no effect anywhere.
		const slotOverrides = this.identity?.meta?.edits?.animations;
		if (slotOverrides && typeof slotOverrides === 'object') {
			this.avatar.setAnimationMap(slotOverrides);
		}

		// Create (or replace) the SceneController for agent scene operations
		this.sceneCtrl = new SceneController(viewer);
		if (this.runtime) this.runtime.viewer = this.sceneCtrl;

		// Update agent-home with the live avatar reference
		if (this.agentHome) this.agentHome.avatar = this.avatar;

		window.VIEWER.agent_avatar = this.avatar;
		window.VIEWER.scene_ctrl = this.sceneCtrl;

		// Let the skills system access the viewer
		if (this.skills) {
			window.VIEWER.agent_skills = this.skills;
		}

		// Wire ElevenLabs frequency-based lipsync to the avatar.
		// onStart fires when audio is actually playing (analyserNode already wired).
		// BrowserTTS has no analyserNode, so it skips connectLipSync and continues
		// using the text-based startLipsync path already in speech.js.
		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();
			};
		}
	}

	/**
	 * Configure Mixamo-style external animations for the viewer.
	 * Looks for animation GLBs in /animations/ and registers them.
	 * Each GLB should contain a single animation clip exported from Mixamo
	 * (downloaded as GLB with "Without Skin" checked).
	 */
	_configureAnimations(viewer) {
		// Check if model has a skeleton
		let hasSkeleton = false;
		if (viewer.content) {
			viewer.content.traverse((node) => {
				if (node.isSkinnedMesh) hasSkeleton = true;
			});
		}
		if (!hasSkeleton) return;

		// Check for ?anim= URL param: play a specific animation (manifest name or API id)
		const _animParam = new URLSearchParams(location.search).get('anim');

		// Fetch the animation manifest
		fetch('/animations/manifest.json')
			.then((r) => {
				if (!r.ok) throw new Error('No animation manifest');
				return r.json();
			})
			.then((manifest) => {
				if (Array.isArray(manifest) && manifest.length > 0) {
					viewer.setAnimationDefs(manifest);
					if (_animParam) {
						// API id (UUID) → load from API; manifest name → normal path
						const isApiId = /^[0-9a-f-]{36}$/i.test(_animParam);
						if (isApiId) {
							viewer.playAnimationById(_animParam).catch(() => {});
						} else {
							viewer.animationManager.crossfadeTo(_animParam).catch(() => {});
						}
					}
				}
			})
			.catch(() => {
				// No manifest — use sensible defaults if files exist
				const defaults = [
					{ name: 'idle', url: '/animations/idle.glb', label: 'Idle' },
					{ name: 'walking', url: '/animations/walking.glb', label: 'Walking' },
					{ name: 'running', url: '/animations/running.glb', label: 'Running' },
					{ name: 'waving', url: '/animations/waving.glb', label: 'Waving' },
					{ name: 'dancing', url: '/animations/dancing.glb', label: 'Dancing' },
					{ name: 'sitting', url: '/animations/sitting.glb', label: 'Sitting' },
					{ name: 'jumping', url: '/animations/jumping.glb', label: 'Jumping' },
				];

				// Probe which files actually exist (HEAD requests)
				Promise.all(
					defaults.map((def) =>
						fetch(def.url, { method: 'HEAD' })
							.then((r) => (r.ok ? def : null))
							.catch(() => null),
					),
				)
					.then((results) => {
						const available = results.filter(Boolean);
						if (available.length > 0) {
							viewer.setAnimationDefs(available);
						}
						// Play API animation even when the manifest is absent.
						if (_animParam && /^[0-9a-f-]{36}$/i.test(_animParam)) {
							viewer.playAnimationById(_animParam).catch(() => {});
						}
					})
					.catch(() => {});
			});
	}

	// ── Validator hook ────────────────────────────────────────────────────────

	_hookValidator() {
		// In the slim widget shell the validator overlay never renders (the
		// `.validate()` call is gated on `!options.kiosk`), so a tree-wide
		// MutationObserver here is pure CPU waste. Skip it entirely in that
		// surface — saves a 60Hz-ish observer on the embedder's parent paint.
		if (this._widgetShell) return;

		// Intercept the validator toggle DOM node to emit validation results
		const observer = new MutationObserver(() => {
			const el = document.querySelector('.validator-toggle');
			if (!el) return;

			const errors = parseInt(el.dataset.errors || '0', 10);
			const warnings = parseInt(el.dataset.warnings || '0', 10);
			const hints = parseInt(el.dataset.hints || '0', 10);

			protocol.emit({
				type: ACTION_TYPES.VALIDATE,
				payload: { errors, warnings, hints },
				agentId: this.identity?.id || 'default',
			});
		});
		observer.observe(document.body, { childList: true, subtree: true, attributes: true });
	}

	// ── Viewer status overlay ────────────────────────────────────────────────
	// Reflects load state inside #viewer-container so the user never sees a
	// black canvas with no explanation. Wired to the protocol load events,
	// not the spinner — so it stays honest even when the load fails silently.

	_wireViewerStatus() {
		protocol.on(ACTION_TYPES.LOAD_START, () => {
			const name = this._editingAgentId ? this.identity?.name : null;
			this._showViewerLoading(
				this._editingAgentId ? `Loading ${name || 'your avatar'}…` : 'Loading model…',
			);
		});

		protocol.on(ACTION_TYPES.LOAD_PROGRESS, (action) => {
			const { loaded = 0, total = 0, indeterminate = false } = action?.payload || {};
			this._updateLoadProgress(loaded, total, indeterminate);
		});

		protocol.on(ACTION_TYPES.LOAD_END, (action) => {
			const success = action?.payload?.success === true;
			if (success) {
				this._fadeOutPoster();
				this._hideViewerStatus();
				// Signal the slim /widget shell that the canvas has pixels.
				// The shell starts the body invisible to avoid chrome/canvas
				// FOUC bleeding into the parent iframe; flips to visible on
				// this event.
				if (!this._firstFrameSignalled) {
					this._firstFrameSignalled = true;
					try {
						window.dispatchEvent(new CustomEvent('three-ws:first-frame'));
					} catch {
						/* CustomEvent ctor missing only on retired browsers — ignore */
					}
				}
				// Fire the first-time-onboarding popup only after the GLB is
				// actually visible on the canvas — otherwise the "ready"
				// label lies during a slow or failing load.
				if (this._editingAgentId && !this._onboardingFired) {
					this._onboardingFired = true;
					this._maybeShowOnboarding(this._editingAgentId);
				}
				// Backfill a thumbnail for this agent's avatar if it doesn't
				// have one — captures the freshly-rendered canvas to PNG and
				// uploads it so the next visit shows a poster instead of a
				// black screen during the multi-MB GLB stream.
				if (this._editingAgentId && this._avatarNeedsThumbnail) {
					this._avatarNeedsThumbnail = false;
					this._captureAndUploadThumbnail().catch((err) =>
						log.warn('[3d-agent] thumbnail upload failed', err),
					);
				}
			} else {
				const err = action?.payload?.errorObj;
				const msg = this._classifyLoadError(err, action?.payload?.error);
				this._showViewerError(
					msg,
					this._editingAgentId
						? () => this._retryAgentLoad()
						: this._retryLastView || null,
				);
				// Notify the host page that the GLB failed — paired with the
				// `widget:ready` event so script-tag embeds can show their own
				// fallback or retry UI instead of staring at a blank iframe.
				this._postToParent({
					type: 'widget:load:error',
					id: this.options?.widget || null,
					url: this._currentModelUrl || null,
					error: msg,
				});
			}
		});
	}

	// Map a thrown load error into a clear, actionable message. Three.js
	// surfaces XHR errors as ProgressEvent or Error, so we inspect the
	// message string plus the underlying request when present.
	_classifyLoadError(err, msgFallback) {
		const text = String(err?.message || msgFallback || '');
		const status = err?.target?.status ?? err?.status ?? null;
		if (status === 404 || /\b404\b/.test(text)) {
			return 'Avatar file not found. It may have been moved or deleted.';
		}
		if (status === 403 || /\b403\b/.test(text)) {
			return "You don't have permission to view this avatar.";
		}
		if (status && status >= 500) {
			return 'Avatar storage is unavailable right now. Try again shortly.';
		}
		if (/Failed to fetch|NetworkError|net::|ERR_INTERNET_DISCONNECTED/i.test(text)) {
			return 'Network error. Check your connection and try again.';
		}
		if (/JSON|parse|invalid|magic|version|chunk|corrupt/i.test(text)) {
			return "This avatar file looks corrupted and couldn't be decoded.";
		}
		return this._editingAgentId ? "Couldn't load your avatar." : "Couldn't load the model.";
	}

	_ensureViewerStatusEl() {
		if (this._viewerStatusEl) return this._viewerStatusEl;
		const el = document.createElement('div');
		el.className = 'viewer-status';
		el.hidden = true;
		this.viewerContainerEl.appendChild(el);
		this._viewerStatusEl = el;
		return el;
	}

	_showViewerLoading(label) {
		const el = this._ensureViewerStatusEl();
		el.dataset.state = 'loading';
		el.innerHTML = `
			<div class="viewer-status__card" role="status" aria-live="polite">
				<div class="viewer-status__spinner" aria-hidden="true"></div>
				<div class="viewer-status__label" data-label>${escHtml(label)}</div>
				<div class="viewer-status__progress" data-progress hidden>
					<div class="viewer-status__progress-track">
						<div class="viewer-status__progress-fill" data-progress-fill
							role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"
							style="width:0%"></div>
					</div>
					<div class="viewer-status__progress-meta" data-progress-meta></div>
				</div>
			</div>
		`;
		el.hidden = false;
	}

	// Update bytes/percent. Called from the LOAD_PROGRESS listener — only
	// reveals the progress bar once we know the total (Content-Length),
	// otherwise the indeterminate spinner stays solo.
	_updateLoadProgress(loaded, total, indeterminate) {
		const el = this._viewerStatusEl;
		if (!el || el.dataset.state !== 'loading') return;
		const progressEl = el.querySelector('[data-progress]');
		if (!progressEl) return;
		if (indeterminate || !total) {
			progressEl.hidden = true;
			return;
		}
		const pct = Math.min(100, Math.max(0, Math.round((loaded / total) * 100)));
		const fill = el.querySelector('[data-progress-fill]');
		const meta = el.querySelector('[data-progress-meta]');
		if (fill) {
			fill.style.width = pct + '%';
			fill.setAttribute('aria-valuenow', String(pct));
		}
		if (meta) meta.textContent = `${pct}% · ${_fmtBytes(loaded)} / ${_fmtBytes(total)}`;
		progressEl.hidden = false;
	}

	/**
	 * @param {string} label     What went wrong, in the user's terms.
	 * @param {?Function} onAction  Recovery to run when the button is pressed.
	 * @param {{ actionLabel?: string, busyLabel?: string }} [opts]
	 *   Wording for actions that aren't a plain retry of the same load, e.g.
	 *   re-opening the file picker after an unusable drop.
	 */
	_showViewerError(label, onAction, opts = {}) {
		const actionLabel = opts.actionLabel || 'Retry';
		const busyLabel = opts.busyLabel || 'Retrying…';
		const el = this._ensureViewerStatusEl();
		el.dataset.state = 'error';
		el.innerHTML = `
			<div class="viewer-status__card viewer-status__card--error" role="alert">
				<div class="viewer-status__icon" aria-hidden="true">!</div>
				<div class="viewer-status__label" data-label>${escHtml(label)}</div>
				${onAction ? `<button class="viewer-status__btn" type="button" data-retry>${escHtml(actionLabel)}</button>` : ''}
			</div>
		`;
		el.hidden = false;
		if (onAction) {
			el.querySelector('[data-retry]')?.addEventListener('click', () => {
				if (opts.keepOpenUntilLoad) this._hideViewerStatus();
				else this._showViewerLoading(busyLabel);
				Promise.resolve(onAction()).catch(() => {});
			});
		}
	}

	// Designed fallback when the device can't give us a WebGL context. Unlike a
	// transient load error, this is a capability gap — so we explain it plainly,
	// offer a reload (which frees contexts and recovers the budget-exhaustion
	// case), and link to the lightweight 2D experience instead of a bare retry.
	_showWebglUnavailable() {
		const el = this._ensureViewerStatusEl();
		el.dataset.state = 'webgl';
		el.innerHTML = `
			<div class="viewer-status__card viewer-status__card--notice" role="alert">
				<div class="viewer-status__icon viewer-status__icon--info" 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="viewer-status__title">3D preview unavailable</div>
				<div class="viewer-status__hint">This browser or device couldn't start a 3D
					(WebGL) view. Try reloading, or open three.ws on a device with hardware
					graphics enabled.</div>
				<button class="viewer-status__btn" type="button" data-reload>Reload</button>
			</div>
		`;
		el.hidden = false;
		el.querySelector('[data-reload]')?.addEventListener('click', () => {
			window.location.reload();
		});
	}

	_hideViewerStatus() {
		if (!this._viewerStatusEl) return;
		this._viewerStatusEl.hidden = true;
		this._viewerStatusEl.dataset.state = '';
	}

	// ── Poster image (model-viewer–style) ───────────────────────────────────
	// Renders the avatar's thumbnail behind the WebGL canvas while the GLB
	// streams in, then fades out on LOAD_END(success). For 4-5MB avatars on
	// a slow connection this turns 5+ seconds of black void into 5 seconds
	// of "your avatar, just not interactive yet."

	_showPoster(url) {
		if (!url) return;
		this._fadeOutPoster(); // remove any previous
		const img = document.createElement('img');
		img.className = 'viewer-poster';
		img.alt = '';
		img.setAttribute('aria-hidden', 'true');
		img.src = url;
		// Insert UNDER the WebGL canvas so the canvas paints over it. The
		// canvas is transparent by default until content renders, so the
		// poster shows through.
		this.viewerContainerEl.insertBefore(img, this.viewerContainerEl.firstChild);
		this._posterEl = img;
	}

	_fadeOutPoster() {
		if (!this._posterEl) return;
		const el = this._posterEl;
		this._posterEl = null;
		el.classList.add('viewer-poster--fading');
		setTimeout(() => el.remove(), 600);
	}

	// ── Auto-thumbnail capture ──────────────────────────────────────────────
	// Renders the avatar's GLB offscreen to a 512² PNG in the thumbnail rest
	// pose and POSTs it to /api/avatars/thumbnail. Reading the live viewer's
	// canvas instead raced the idle clip (a capture before it started showed the
	// bind-pose T-pose) and could read back a blank buffer, since the viewer's
	// renderer does not preserve its drawing buffer. Fire-and-forget: the only
	// consequence of failure is that the next page load runs through this again.

	async _captureAndUploadThumbnail() {
		const avatarId = this._currentAvatarId;
		const glbUrl = this._currentAvatarGlbUrl;
		if (!avatarId || !glbUrl) return;

		const glbRes = await fetch(glbUrl);
		if (!glbRes.ok) throw new Error(`thumbnail source fetch failed: ${glbRes.status}`);
		const { glbFileToThumbnail } = await import('./erc8004/thumbnail.js');
		const blob = await glbFileToThumbnail(await glbRes.blob(), { size: 512 });
		const dataUrl = await _blobToBase64(blob);

		const resp = await fetch('/api/avatars/thumbnail', {
			method: 'POST',
			credentials: 'include',
			headers: { 'content-type': 'application/json' },
			body: JSON.stringify({
				avatar_id: avatarId,
				png_base64: `data:image/png;base64,${dataUrl}`,
			}),
		});
		if (!resp.ok) {
			throw new Error(`thumbnail upload HTTP ${resp.status}`);
		}
	}

	async _retryAgentLoad() {
		if (!this._editingAgentId) return;
		await this._loadAgentForEdit(this._editingAgentId);
	}

	// ── UI Helpers ────────────────────────────────────────────────────────────

	_flashSaved(avatar) {
		const el = document.createElement('div');
		el.className = 'save-toast';
		el.innerHTML = `Saved to your account · <a href="/dashboard/#avatars">${escHtml(avatar.name)}</a>`;
		document.body.appendChild(el);
		setTimeout(() => el.remove(), 5000);
	}

	/**
	 * @param  {Error} error
	 */
	onError(error) {
		// The viewer-status overlay (driven by LOAD_END payload) is the
		// user-facing error surface now — see _classifyLoadError above.
		// onError is kept as a console-only fallback for diagnostics.
		log.error('[3d-agent] load error:', error);
	}

	/**
	 * Resolve an on-chain ERC-8004 agent to its 3D avatar and render it.
	 * Public — works for anyone, no wallet required.
	 *
	 * @param {{ chainId: number, agentId: string, registry?: string }} onchain
	 */
	async _loadOnChainAgent(onchain) {
		try {
			const [
				{ getAgentOnchain, fetchAgentMetadata, findAvatar3D },
				{ REGISTRY_DEPLOYMENTS },
			] = await Promise.all([import('./erc8004/queries.js'), import('./erc8004/abi.js')]);

			if (!REGISTRY_DEPLOYMENTS[onchain.chainId]) {
				this._showOnChainError(`Unsupported chain: ${onchain.chainId}`);
				return;
			}

			const { uri } = await getAgentOnchain({
				chainId: onchain.chainId,
				agentId: onchain.agentId,
				ethProvider: window.ethereum,
			});
			if (!uri) {
				this._showOnChainError(`Agent #${onchain.agentId} has no agentURI set.`);
				return;
			}

			const meta = await fetchAgentMetadata(uri);
			if (!meta.ok) {
				this._showOnChainError(`Could not fetch registration JSON: ${meta.error}`);
				return;
			}

			this._onchainMetadata = meta.data;
			this._updateOnChainCard(onchain, meta.data);

			const glbUri = findAvatar3D(meta.data);
			if (!glbUri) {
				this._showOnChainError(
					`Agent #${onchain.agentId} has no 3D avatar — no <code>avatar</code> service entry and <code>image</code> is not a GLB.`,
				);
				return;
			}

			const resolvedGlb = resolveModelUrl(glbUri);
			await this.view(resolvedGlb, '', new Map());
		} catch (err) {
			log.warn('[3d-agent] on-chain load failed:', err);
			this._showOnChainError(err.message || String(err));
		}
	}

	_showOnChainError(msg) {
		this._updateOnChainCard(this.options.onchain, null, msg);
		this.dropEl?.classList.add('hidden');
	}

	/**
	 * Render a small info card overlaying the viewer so users know whose agent
	 * they're looking at. Hidden in kiosk mode.
	 */
	_updateOnChainCard(onchain, metadata, errorMsg = '') {
		if (this.options.kiosk) return;
		let card = this.el.querySelector('.onchain-card');
		if (!card) {
			card = document.createElement('div');
			card.className = 'onchain-card';
			this.el.appendChild(card);
		}
		const chainLabel = `chainId ${onchain.chainId}`;
		if (errorMsg) {
			card.innerHTML = `<div class="onchain-card__err">⚠ ${escHtml(errorMsg)}</div>
				<div class="onchain-card__sub">Agent #${escHtml(onchain.agentId)} · ${escHtml(chainLabel)}</div>`;
			return;
		}
		const name = metadata?.name ? String(metadata.name) : `Agent #${onchain.agentId}`;
		const desc = metadata?.description ? String(metadata.description) : '';
		card.innerHTML = `
			<div class="onchain-card__name">${escHtml(name)}</div>
			<div class="onchain-card__sub">#${escHtml(onchain.agentId)} · ${escHtml(chainLabel)}</div>
			${desc ? `<div class="onchain-card__desc">${escHtml(desc)}</div>` : ''}
		`;
	}

	// The app shell carries the three.ws wordmark as the document's <h1>, which is
	// right for the viewer route where nothing else names the page. A page mode
	// (/showcase, /deploy) renders its own real heading, so the wordmark becomes a
	// second <h1> and a screen reader is handed two competing page titles. Demote
	// it to a plain element, preserving its markup, classes and i18n binding, so
	// the page's own heading is the only <h1> in the document.
	_demoteBrandHeadingForPageMode() {
		const brand = document.querySelector('header h1');
		if (!brand) return;
		const div = document.createElement('div');
		for (const attr of brand.attributes) div.setAttribute(attr.name, attr.value);
		div.classList.add('brand-wordmark');
		while (brand.firstChild) div.appendChild(brand.firstChild);
		brand.replaceWith(div);
	}

	async _showShowcasePage() {
		try {
			const main = this.el.querySelector('main.wrap') || this.el;
			this.dropEl?.classList.add('hidden');
			const dropzone = this.el.querySelector('.dropzone');
			if (dropzone) dropzone.style.display = 'none';
			if (this.viewerContainerEl) this.viewerContainerEl.style.display = 'none';
			const authGate = this.el.querySelector('#auth-gate');
			if (authGate) authGate.style.display = 'none';
			const presence = this.el.querySelector('.agent-presence-sidebar');
			if (presence) presence.style.display = 'none';

			this._demoteBrandHeadingForPageMode();

			const page = document.createElement('section');
			page.className = 'showcase-page';
			main.appendChild(page);

			// Same upgrade /deploy performs. The legacy footer is a flex row that
			// measures ~413px, so on a 320px phone it was the one thing dragging the
			// document into a horizontal scroll while the directory itself fitted.
			this._upgradeToHorizonFooter();

			const { renderShowcasePage } = await import('./erc8004/showcase.js');
			renderShowcasePage(page);
		} catch (err) {
			log.error('[3d-agent] showcase page load failed', err);
		}
	}

	async _showDeployPage() {
		// Render /deploy as a normal page inside the app.html shell (header +
		// footer stay visible). We hide the viewer + dropzone + auth gate and
		// replace them with the ERC-8004 wizard, pre-filled from the user's
		// current avatar so Step 5 flows from Steps 1–4.
		//
		// Deep-link support: `/deploy?avatar=<id>` pre-fills from a previously
		// saved avatar (dashboard "Deploy on-chain" per row). That prefill
		// overrides the viewer's current model.
		try {
			const main = this.el.querySelector('main.wrap') || this.el;
			this.dropEl?.classList.add('hidden');
			const dropzone = this.el.querySelector('.dropzone');
			if (dropzone) dropzone.style.display = 'none';
			if (this.viewerContainerEl) this.viewerContainerEl.style.display = 'none';
			const authGate = this.el.querySelector('#auth-gate');
			if (authGate) authGate.style.display = 'none';
			const presence = this.el.querySelector('.agent-presence-sidebar');
			if (presence) presence.style.display = 'none';
			// The fixed onboarding card ("Your agent is ready") would otherwise
			// float over the deploy Live Preview panel — it has no purpose here.
			const onboarding = this.el.querySelector('#agent-onboarding');
			if (onboarding) onboarding.hidden = true;

			this._demoteBrandHeadingForPageMode();

			const page = document.createElement('section');
			page.className = 'deploy-page';
			main.appendChild(page);

			this._upgradeToHorizonFooter();

			const initial = await this._resolveDeployInitial();

			const { RegisterUI } = await import('./erc8004/register-ui.js');
			new RegisterUI(
				page,
				(result) => {
					log.info('[ERC-8004] Agent registered:', result);
				},
				{ mode: 'page', initial, viewer: this.viewer, avatarId: initial.avatarId },
			);
		} catch (err) {
			log.error('[3d-agent] deploy page load failed', err);
		}
	}

	/**
	 * Resolve the initial state passed to RegisterUI. Honors:
	 *   ?avatar=<id>       — fetch a saved avatar from the backend
	 *   ?name=             — prefill identity name
	 *   ?description=      — prefill description
	 *   ?image=            — prefill image URL
	 *   ?network=          — preselect chain (mainnet-beta/devnet/base/bsc/…)
	 * Avatar lookup wins over the viewer's current model when both exist;
	 * direct query params override either as last-step "manual" entries.
	 */
	async _resolveDeployInitial() {
		const qp = new URLSearchParams(location.search);
		const avatarId = qp.get('avatar');
		const qpName = qp.get('name') || '';
		const qpDesc = qp.get('description') || '';
		const qpImage = qp.get('image') || '';
		const qpNetwork = qp.get('network') || '';
		const qpModel = qp.get('model') || '';
		const base = { glbUrl: qpModel || this._currentModelUrl || '' };
		let resolved = base;
		if (avatarId) {
			try {
				const res = await fetch(`/api/avatars/${encodeURIComponent(avatarId)}`, {
					credentials: 'include',
				});
				if (!res.ok) throw new Error(`HTTP ${res.status}`);
				const { avatar } = await res.json();
				if (!avatar) throw new Error('empty avatar payload');
				resolved = {
					name: avatar.name || '',
					description: avatar.description || '',
					imageUrl: avatar.thumbnail_url || '',
					glbUrl: avatar.url || avatar.model_url || '',
				};
			} catch (err) {
				log.warn('[deploy] avatar prefill failed; falling back to viewer model', err);
			}
		}
		return {
			...resolved,
			name: qpName || resolved.name || '',
			description: qpDesc || resolved.description || '',
			imageUrl: qpImage || resolved.imageUrl || '',
			network: qpNetwork || '',
			avatarId: avatarId || null,
		};
	}

	_upgradeToHorizonFooter() {
		const existing = document.querySelector('footer');
		if (!existing) return;
		existing.outerHTML = `<footer class="h-footer h-footer-horizon">
			<div class="h-footer-glow-line" aria-hidden="true"></div>
			<div class="h-footer-floor" aria-hidden="true"></div>
			<div class="h-footer-haze" aria-hidden="true"></div>
			<div class="h-footer-watermark" aria-hidden="true">three.ws</div>
			<div class="h-footer-inner">
				<div class="h-footer-brand-col">
					<div class="h-footer-brand">
						<span class="wordmark-dot" aria-hidden="true"></span>
						<span>three.ws</span>
					</div>
					<p class="h-footer-tagline">Give your AI a body.</p>
				</div>
				<nav class="h-footer-links" aria-label="Footer">
					<a href="https://github.com/nirholas/three.ws" target="_blank" rel="noopener">GitHub</a>
					<a href="/create">Create</a>
					<a href="/studio">Studio</a>
					<a href="/widgets">Widgets</a>
					<a href="/discover">Discover</a>
					<a href="/docs">Docs</a>
					<a href="https://eips.ethereum.org/EIPS/eip-8004" target="_blank" rel="noopener">ERC-8004</a>
				</nav>
			</div>
			<div class="h-footer-bottom">
				<p class="h-footer-legal">© 2026 three.ws — All rights reserved.</p>
				<div class="h-footer-badges">
					<span class="h-footer-badge" aria-label="System status">
						<span class="h-footer-status-dot" aria-hidden="true"></span>
						<span>All systems normal</span>
					</span>
					<a class="h-footer-badge" href="https://github.com/nirholas/three.ws" target="_blank" rel="noopener" aria-label="View source on GitHub">
						<svg viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
						<span>Open source</span>
					</a>
				</div>
			</div>
		</footer>`;
	}

	showSpinner() {
		this.spinnerEl.style.display = '';
	}
	hideSpinner() {
		this.spinnerEl.style.display = 'none';
	}
}

// The slim /widget shell (pages/widget.html) sets `window.__WIDGET_SHELL`
// before this module parses, signalling that no site chrome should be
// injected. Without this guard the marketing footer flashes inside every
// embed iframe before kiosk JS hides it.
if (!window.__WIDGET_SHELL) {
	document.body.innerHTML += Footer();
} else {
	// Tell the shell that the bundle has started executing. The shell uses
	// this to arm its 6s "still no first frame" fallback — without it, an
	// interaction-mode widget would fire the fallback during idle and break
	// the play-to-load promise.
	try {
		window.dispatchEvent(new CustomEvent('three-ws:boot-started'));
	} catch {
		/* CustomEvent ctor missing only on retired browsers — ignore */
	}
}

function _bootApp() {
	const app = new App(document.body, location);
	window.VIEWER.app = app;
	log.info('[three.ws] Debugging data exported as `window.VIEWER`.');
}
// The slim /widget shell injects this script after DOMContentLoaded (the
// reveal state machine dynamically appends it), so a plain
// `addEventListener('DOMContentLoaded')` would attach a listener that never
// fires. Cover both timings.
if (document.readyState === 'loading') {
	document.addEventListener('DOMContentLoaded', _bootApp);
} else {
	_bootApp();
}