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.

14.4 KB
Raw Blame
// <three-ws-agent> — embeddable custom element that renders a three.ws
// 3D avatar bound to the on-chain state of an AgenC task.
//
//   <script type="module" src="https://three.ws/agenc/embed.js"></script>
//   <three-ws-agent
//     src="/avatars/default.glb"
//     agenc-task="<TASK_PDA>"
//     agenc-cluster="devnet"
//     agenc-poll-ms="4000"
//     agenc-bridge="https://three.ws/api/agenc"
//   ></three-ws-agent>
//
// Attributes:
//   src              — GLB url for the avatar body (passed straight to model-viewer)
//   agenc-task       — base58 task PDA on AgenC (required to poll state)
//   agenc-cluster    — "devnet" | "mainnet" (default "devnet")
//   agenc-poll-ms    — polling interval; clamped [1500, 120000] (default 4000)
//   agenc-bridge     — base URL of the three.ws AgenC API (default "/api/agenc")
//   agenc-clips      — JSON map of {state: clipName} for state-driven animation,
//                       e.g. `{"In Progress":"working","Completed":"cheer"}`.
//                       Keys are AgenC's on-chain TaskState labels verbatim (see
//                       STATE_COLORS below); clips must exist in the GLB, and a
//                       missing clip is a no-op.
//   show-overlay     — when present, render a small state badge in the corner
//
// Events (CustomEvent, bubble=true):
//   agenc:state      : { taskPda, cluster, state, task, lifecycle, programId }
//                       on every poll where the task is found. The page can hook
//                       this to drive additional UI without reaching into the
//                       element. `programId` is the program the read actually ran
//                       against, so a host page can name it without hardcoding.
//   agenc:error      : { message, taskPda, cluster, retryInMs } on a 404, a
//                       bridge error, or a transport / parse failure. Polling
//                       continues with backoff; `retryInMs` is when.
//
// The element is dependency-free apart from <model-viewer>, which is loaded
// lazily from the npm CDN on first connect (the same source three.ws uses).

const MODEL_VIEWER_CDN = 'https://cdn.jsdelivr.net/npm/@google/[email protected]/dist/model-viewer.min.js';
// Served from three.ws rather than a public CDN: the decoder is a hard
// dependency of every compressed avatar, so it must have the same availability
// as the embed script itself.
function meshoptDecoderUrl() {
	// On a normal site import.meta.url is this script's own http(s) address, so
	// the decoder resolves same-origin. A copy that was inlined or loaded from a
	// blob: or data: URL has no origin to resolve against (new URL throws
	// "Invalid URL", and at module level that killed the whole embed before the
	// element could register), so that copy reads the decoder from three.ws.
	try {
		const base = new URL(import.meta.url);
		if (base.protocol === 'http:' || base.protocol === 'https:') {
			return new URL('/vendor/meshopt_decoder.js', base).href;
		}
	} catch {
		// no usable base URL; use the canonical origin below
	}
	return 'https://three.ws/vendor/meshopt_decoder.js';
}
const MESHOPT_DECODER_CDN = meshoptDecoderUrl();

// Register the EXT_meshopt_compression decoder with <model-viewer> before it
// begins loading. Server-baked avatars (the /api/avatars/<id>/glb lane and Forge
// output) emit EXT_meshopt_compression; model-viewer auto-wires Draco/KTX2 but
// leaves Meshopt unset, so without this the viewer throws
//   "THREE.GLTFLoader: setMeshoptDecoder must be called before loading
//    compressed files"
// and the avatar never renders. This is the same three-step race-proof pattern
// as public/model-viewer-meshopt.js, inlined here because embed.js is also the
// public snippet third parties paste onto their own sites (where a
// /model-viewer-meshopt.js path wouldn't resolve) and it injects the CDN script
// async — the interceptor must be installed before model-viewer is defined so an
// already-connected <three-ws-agent> can't win the race.
function applyMeshoptDecoder(ctor) {
	if (ctor && !ctor.meshoptDecoderLocation) {
		try {
			ctor.meshoptDecoderLocation = MESHOPT_DECODER_CDN;
		} catch (e) {
			/* property not writable in this build — nothing more we can do */
		}
	}
}

function wireMeshoptDecoder() {
	if (typeof window === 'undefined' || !window.customElements) return;
	// 1. model-viewer already defined → set it synchronously.
	applyMeshoptDecoder(customElements.get('model-viewer'));
	// 2. Not yet defined → patch define() so the decoder is registered the moment
	//    the element is defined, before its first reactive update kicks off a load.
	if (!customElements.get('model-viewer') && !customElements.__meshoptDefinePatched) {
		customElements.__meshoptDefinePatched = true;
		const nativeDefine = customElements.define;
		customElements.define = function (name, ctor, options) {
			const result = nativeDefine.call(this, name, ctor, options);
			if (name === 'model-viewer') applyMeshoptDecoder(ctor);
			return result;
		};
	}
	// 3. Belt-and-suspenders fallback for any path where (1) and (2) both miss.
	customElements.whenDefined('model-viewer').then((resolved) => {
		applyMeshoptDecoder(resolved || customElements.get('model-viewer'));
	});
}

let modelViewerPromise = null;
function ensureModelViewer() {
	if (typeof window === 'undefined') return Promise.resolve();
	// Install the decoder interceptor before anything can define model-viewer,
	// even on the already-defined fast path below.
	wireMeshoptDecoder();
	if (customElements.get('model-viewer')) return Promise.resolve();
	if (modelViewerPromise) return modelViewerPromise;
	modelViewerPromise = new Promise((resolve, reject) => {
		const script = document.createElement('script');
		script.type = 'module';
		script.src = MODEL_VIEWER_CDN;
		script.onload = () => resolve();
		script.onerror = () => reject(new Error('failed to load model-viewer from ' + MODEL_VIEWER_CDN));
		document.head.appendChild(script);
	});
	return modelViewerPromise;
}

// AgenC's on-chain TaskState labels VERBATIM, as `/api/agenc/get-task` reports
// them (api/agenc/[action].js `taskStateLabel`), plus this element's own three
// transport states. The map used to key on "Claimed" and "Expired", which the
// chain has never emitted: a task in the real second state arrives as
// "In Progress" and matched nothing here, so the halo, the badge color and the
// agenc-clips switch all sat inert for the exact transition the embed exists to
// show. Keep this list and taskStateLabel in lockstep.
const STATE_COLORS = {
	Open: '#7af0c4',
	'In Progress': '#f0c47a',
	'Pending Validation': '#8ab4f8',
	Completed: '#7af0c4',
	Cancelled: '#f07a7a',
	Disputed: '#f07a7a',
	loading: '#8a8499',
	error: '#f07a7a',
	idle: '#8a8499',
};

class ThreewsAgentElement extends HTMLElement {
	static get observedAttributes() {
		return ['src', 'agenc-task', 'agenc-cluster', 'agenc-poll-ms', 'agenc-bridge', 'agenc-clips', 'show-overlay'];
	}

	constructor() {
		super();
		this._shadow = this.attachShadow({ mode: 'open' });
		this._pollTimer = null;
		this._requestId = 0;
		this._lastState = null;
		this._failures = 0;
	}

	connectedCallback() {
		this._render();
		ensureModelViewer().catch((err) => this._emit('agenc:error', { message: err.message }));
		this._restart();
	}

	disconnectedCallback() {
		clearTimeout(this._pollTimer);
		this._requestId += 1;
	}

	attributeChangedCallback(name, oldValue, newValue) {
		if (oldValue === newValue) return;
		if (name === 'src' && this._viewer) {
			this._viewer.setAttribute('src', newValue || '');
		}
		if (['agenc-task', 'agenc-cluster', 'agenc-poll-ms', 'agenc-bridge'].includes(name)) {
			this._restart();
		}
		if (name === 'show-overlay') {
			this._toggleOverlay();
		}
	}

	_emit(type, detail) {
		this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
	}

	_pollMs() {
		const raw = parseInt(this.getAttribute('agenc-poll-ms') || '4000', 10);
		if (!Number.isFinite(raw)) return 4000;
		return Math.max(1500, Math.min(raw, 120000));
	}

	_cluster() {
		const c = (this.getAttribute('agenc-cluster') || 'devnet').toLowerCase();
		return c === 'mainnet' ? 'mainnet' : 'devnet';
	}

	_bridge() {
		return (this.getAttribute('agenc-bridge') || '/api/agenc').replace(/\/+$/, '');
	}

	_clipsMap() {
		const raw = this.getAttribute('agenc-clips');
		if (!raw) return null;
		try {
			const parsed = JSON.parse(raw);
			return parsed && typeof parsed === 'object' ? parsed : null;
		} catch {
			return null;
		}
	}

	_render() {
		this._shadow.innerHTML = `
			<style>
				:host { display: block; position: relative; width: 100%; height: 100%; min-height: 240px; background: transparent; }
				.viewer { position: relative; width: 100%; height: 100%; border-radius: inherit; overflow: hidden; }
				model-viewer { width: 100%; height: 100%; --poster-color: transparent; background: transparent; }
				.pulse {
					position: absolute; inset: 0; pointer-events: none;
					mix-blend-mode: screen;
					opacity: 0;
					transition: opacity 0.3s, background 0.3s;
				}
				:host([data-state="Open"]) .pulse {
					background: radial-gradient(circle at 50% 70%, #7af0c4 0%, transparent 55%);
					opacity: 0.18;
				}
				:host([data-state="In Progress"]) .pulse {
					background: radial-gradient(circle at 50% 70%, #f0c47a 0%, transparent 55%);
					opacity: 0.28;
					animation: pulse 2.4s ease-in-out infinite;
				}
				:host([data-state="Pending Validation"]) .pulse {
					background: radial-gradient(circle at 50% 70%, #8ab4f8 0%, transparent 55%);
					opacity: 0.26;
				}
				:host([data-state="Completed"]) .pulse {
					background: radial-gradient(circle at 50% 70%, #7af0c4 0%, transparent 55%);
					opacity: 0.36;
				}
				:host([data-state="Cancelled"]) .pulse,
				:host([data-state="Disputed"]) .pulse {
					background: radial-gradient(circle at 50% 70%, #f07a7a 0%, transparent 55%);
					opacity: 0.24;
				}
				@keyframes pulse {
					0%, 100% { opacity: 0.16; }
					50% { opacity: 0.36; }
				}
				@media (prefers-reduced-motion: reduce) {
					:host([data-state="In Progress"]) .pulse { animation: none; }
				}
				.overlay {
					position: absolute;
					left: 12px;
					bottom: 12px;
					font: 600 11px/1 -apple-system, BlinkMacSystemFont, 'Inter', system-ui, sans-serif;
					letter-spacing: 0.06em;
					text-transform: uppercase;
					color: #ececec;
					background: rgba(0, 0, 0, 0.6);
					border: 1px solid rgba(255, 255, 255, 0.12);
					padding: 5px 10px;
					border-radius: 999px;
					transition: color 0.2s, border-color 0.2s;
					display: none;
				}
				.overlay.show { display: inline-block; }
			</style>
			<div class="viewer">
				<model-viewer auto-rotate camera-controls environment-image="neutral"
					interaction-prompt="none"
					exposure="1" shadow-intensity="0.6"
					reveal="auto"></model-viewer>
				<div class="pulse"></div>
				<div class="overlay">idle</div>
			</div>
		`;
		this._viewer = this._shadow.querySelector('model-viewer');
		this._overlay = this._shadow.querySelector('.overlay');
		if (this.hasAttribute('src')) this._viewer.setAttribute('src', this.getAttribute('src'));
		this._toggleOverlay();
		this._setState(this.getAttribute('agenc-task') ? 'loading' : 'idle');
	}

	_toggleOverlay() {
		if (!this._overlay) return;
		const show = this.hasAttribute('show-overlay');
		this._overlay.classList.toggle('show', show);
	}

	_setState(state) {
		if (this._lastState === state) return;
		this._lastState = state;
		this.setAttribute('data-state', state);
		if (this._overlay) {
			this._overlay.textContent = state;
			this._overlay.style.color = STATE_COLORS[state] || '#ececec';
			this._overlay.style.borderColor = (STATE_COLORS[state] || '#ffffff20') + '88';
		}
		// State-driven animation: if the user supplied an agenc-clips map and the
		// clip exists in the loaded GLB, switch the active animation; otherwise
		// silently fall back to whatever clip is already playing.
		const clipMap = this._clipsMap();
		if (this._viewer && clipMap && clipMap[state]) {
			const desired = String(clipMap[state]);
			const available = this._viewer.availableAnimations || [];
			if (!available.length || available.includes(desired)) {
				this._viewer.setAttribute('animation-name', desired);
				try {
					this._viewer.play({ repetitions: state === 'Completed' ? 1 : Infinity });
				} catch {
					// model-viewer.play may not be ready yet — non-fatal
				}
			}
		}
	}

	_restart() {
		clearTimeout(this._pollTimer);
		this._requestId += 1;
		this._failures = 0;
		const taskPda = this.getAttribute('agenc-task');
		if (!taskPda) {
			this._setState('idle');
			return;
		}
		this._setState('loading');
		const myReq = this._requestId;
		this._poll(taskPda, myReq);
	}

	// Back off after consecutive failures instead of re-asking at the full poll
	// rate forever. A mistyped address 404s permanently, and the flat retry made
	// that one typo a request every 4s for as long as the tab stayed open. Doubles
	// per failure, capped at a minute; a single success resets it.
	_retryDelay() {
		const base = this._pollMs();
		if (!this._failures) return base;
		return Math.min(base * 2 ** Math.min(this._failures, 4), 60000);
	}

	_fail(message) {
		this._failures += 1;
		this._setState('error');
		this._emit('agenc:error', { message, taskPda: this.getAttribute('agenc-task'), cluster: this._cluster(), retryInMs: this._retryDelay() });
	}

	async _poll(taskPda, requestId) {
		const cluster = this._cluster();
		const bridge = this._bridge();
		const url = `${bridge}/get-task?taskPda=${encodeURIComponent(taskPda)}&cluster=${cluster}&lifecycle=1`;
		try {
			const r = await fetch(url, { headers: { accept: 'application/json' } });
			if (requestId !== this._requestId) return;
			if (!r.ok && r.status !== 404) {
				this._fail(`bridge ${r.status}`);
				return;
			}
			const payload = await r.json();
			if (!payload.ok || !payload.task) {
				this._fail(payload.error || 'not_found');
				return;
			}
			this._failures = 0;
			this._setState(payload.task.state);
			this._emit('agenc:state', {
				taskPda,
				cluster,
				state: payload.task.state,
				task: payload.task,
				lifecycle: payload.lifecycle,
				programId: payload.programId ?? null,
			});
		} catch (err) {
			if (requestId !== this._requestId) return;
			this._fail(err.message || String(err));
		} finally {
			if (requestId === this._requestId) {
				this._pollTimer = setTimeout(() => this._poll(taskPda, requestId), this._retryDelay());
			}
		}
	}
}

if (typeof customElements !== 'undefined' && !customElements.get('three-ws-agent')) {
	customElements.define('three-ws-agent', ThreewsAgentElement);
}

export { ThreewsAgentElement };