Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// /assistant-frame — the assistant widget's iframe surface.
//
// Loaded by public/assistant/v1.js inside a floating panel on third-party
// sites (or standalone for testing). One standing 3D avatar + a composer with
// two modes:
// • Chat — messages go to an LLM (free platform chain via /api/chat, or
// the visitor's own Groq/OpenRouter key straight from the
// browser) and the reply streams into a speech bubble above the
// avatar's head, optionally spoken aloud.
// • Speak — the avatar repeats exactly what you typed: speech bubble +
// Web Speech API audio + talking animation. No model involved.
//
// Query params (every one validated in src/assistant-widget-core.js):
// ?avatar=<id|url> | ?agent=<id> which body to load
// ?bg=transparent|#hex|<preset>|gradient:#a,#b[,angle]
// ?mode=chat|speak|both default both (segmented control)
// ?accent=#hex ?name= ?greeting= ?context= ?voice=false ?badge=false
// ?targetOrigin=<origin> pins outbound postMessage
//
// Duplicated stage plumbing from src/walk-embed.js on purpose — embeds evolve
// independently so a fix here can't destabilize /walk-embed (same reasoning
// as the header of that file).
import {
AmbientLight,
Box3,
CircleGeometry,
Color,
DirectionalLight,
HemisphereLight,
Mesh,
PCFShadowMap,
PerspectiveCamera,
PMREMGenerator,
Scene,
ShadowMaterial,
Timer,
Vector3,
WebGLRenderer,
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
import { getMeshoptDecoder } from './viewer/internal.js';
import { AnimationManager } from './animation-manager.js';
import { log } from './shared/log.js';
import {
parseBackground,
normalizeMode,
normalizeLane,
sanitizeAccent,
estimateSpeechMs,
BYOK_DEFAULT_MODELS,
BYOK_ENDPOINTS,
} from './assistant-widget-core.js';
const AVATAR_URL_DEFAULT = '/avatars/default.glb';
const ANIMATIONS_MANIFEST_URL = '/animations/manifest.json';
const CLIP_IDLE = 'idle';
const CLIP_TALK = 'av-vtubing';
const CLIP_GREET = 'wave';
const REQUIRED_CLIPS = new Set([CLIP_IDLE, CLIP_TALK, CLIP_GREET]);
const CHANNEL = 'three-assistant';
const PROTOCOL_VERSION = 1;
const STORAGE_KEY = 'threeAssistant.settings.v1';
const MAX_HISTORY_TURNS = 10; // ×2 messages — matches /api/chat's history max of 20
// ── Params ────────────────────────────────────────────────────────────────
const params = new URLSearchParams(location.search);
const BG = parseBackground(params.get('bg'));
const MODE = normalizeMode(params.get('mode'));
const ACCENT = sanitizeAccent(params.get('accent'));
const NAME = (params.get('name') || 'Assistant').slice(0, 60);
const GREETING = (params.get('greeting') || '').slice(0, 200);
const CONTEXT = (params.get('context') || '').slice(0, 500);
const VOICE_DEFAULT = params.get('voice') !== 'false' && params.get('voice') !== '0';
const SHOW_BADGE = params.get('badge') !== 'false' && params.get('badge') !== '0';
const TARGET_ORIGIN = params.get('targetOrigin') || '*';
const AGENT_PARAM = params.get('agent');
const PREFERS_REDUCED_MOTION =
typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
const HAS_HOVER =
typeof matchMedia === 'function' && matchMedia('(hover: hover) and (pointer: fine)').matches;
// ── DOM ───────────────────────────────────────────────────────────────────
const rootEl = document.getElementById('assistant-root');
const stageEl = document.getElementById('assistant-stage');
const canvas = document.getElementById('assistant-canvas');
const posterEl = document.getElementById('assistant-poster');
const bubbleEl = document.getElementById('assistant-bubble');
const bubbleTextEl = bubbleEl.querySelector('.bubble-text');
const badgeEl = document.getElementById('assistant-badge');
const statusEl = document.getElementById('assistant-status');
const titleLabelEl = document.querySelector('#assistant-title .label');
const voiceBtn = document.getElementById('assistant-voice-btn');
const settingsBtn = document.getElementById('assistant-settings-btn');
const closeBtn = document.getElementById('assistant-close-btn');
const modesEl = document.getElementById('assistant-modes');
const inputEl = document.getElementById('assistant-input');
const sendBtn = document.getElementById('assistant-send');
const hintTextEl = document.getElementById('assistant-hint-text');
const lanePillEl = document.getElementById('assistant-lane-pill');
const settingsEl = document.getElementById('assistant-settings');
const settingsCloseBtn = document.getElementById('assistant-settings-close');
const byokFieldsEl = document.getElementById('assistant-byok-fields');
const byokKeyEl = document.getElementById('assistant-byok-key');
const byokModelEl = document.getElementById('assistant-byok-model');
const voiceSelectEl = document.getElementById('assistant-voice-select');
// ── Chrome from params ────────────────────────────────────────────────────
document.documentElement.style.setProperty('--accent', ACCENT);
titleLabelEl.textContent = NAME;
if (BG.css) document.body.style.background = BG.css;
if (!SHOW_BADGE) badgeEl.remove();
rootEl.dataset.modeSwitch = String(MODE === 'both');
let activeMode = MODE === 'speak' ? 'speak' : 'chat';
function applyModeChrome() {
for (const btn of modesEl.querySelectorAll('.mode-btn')) {
btn.setAttribute('aria-pressed', String(btn.dataset.mode === activeMode));
}
if (activeMode === 'speak') {
inputEl.placeholder = 'Type something for me to say...';
hintTextEl.textContent = 'I repeat exactly what you type, out loud.';
} else {
inputEl.placeholder = 'Type a question...';
hintTextEl.textContent = CONTEXT ? `Ask anything about ${NAME}.` : 'Ask anything.';
}
lanePillEl.hidden = activeMode === 'speak';
}
// ── Settings (persisted per-browser, never sent to the host page) ─────────
function loadSettings() {
try {
const raw = localStorage.getItem(STORAGE_KEY);
if (!raw) return {};
const parsed = JSON.parse(raw);
return parsed && typeof parsed === 'object' ? parsed : {};
} catch {
return {};
}
}
function saveSettings() {
try {
localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
} catch {
/* private mode / storage disabled — settings just don't persist */
}
}
const settings = loadSettings();
settings.lane = normalizeLane(settings.lane);
settings.keys = settings.keys && typeof settings.keys === 'object' ? settings.keys : {};
settings.models = settings.models && typeof settings.models === 'object' ? settings.models : {};
let voiceEnabled = typeof settings.voiceEnabled === 'boolean' ? settings.voiceEnabled : VOICE_DEFAULT;
function laneReady(lane) {
return lane === 'free' || Boolean(settings.keys[lane]);
}
function effectiveLane() {
return laneReady(settings.lane) ? settings.lane : 'free';
}
function applyLaneChrome() {
const lane = effectiveLane();
lanePillEl.textContent = lane === 'free' ? 'free' : `byok:${lane}`;
for (const radio of settingsEl.querySelectorAll('input[name="assistant-lane"]')) {
radio.checked = radio.value === settings.lane;
}
const byok = settings.lane !== 'free';
byokFieldsEl.classList.toggle('is-visible', byok);
if (byok) {
byokKeyEl.value = settings.keys[settings.lane] || '';
byokModelEl.value = settings.models[settings.lane] || BYOK_DEFAULT_MODELS[settings.lane];
byokKeyEl.placeholder = settings.lane === 'groq' ? 'gsk_...' : 'sk-or-...';
}
}
function applyVoiceChrome() {
voiceBtn.setAttribute('aria-pressed', String(voiceEnabled));
voiceBtn.title = voiceEnabled ? 'Voice on' : 'Voice off';
}
// ── Status pill ───────────────────────────────────────────────────────────
function setStatus(text, { error = false, sticky = false } = {}) {
statusEl.textContent = text;
statusEl.classList.toggle('is-error', error);
statusEl.classList.remove('is-hidden');
clearTimeout(setStatus._t);
if (!sticky) setStatus._t = setTimeout(() => statusEl.classList.add('is-hidden'), 2600);
}
// ── postMessage bridge ────────────────────────────────────────────────────
function post(type, payload = {}) {
if (window.parent === window) return;
try {
window.parent.postMessage({ channel: CHANNEL, v: PROTOCOL_VERSION, type, payload }, TARGET_ORIGIN);
} catch {
/* host gone mid-navigation */
}
}
window.addEventListener('message', (event) => {
const msg = event.data;
if (!msg || typeof msg !== 'object' || msg.channel !== CHANNEL) return;
if (msg.type === 'say') {
const text = String(msg.payload?.text || '').slice(0, 600);
if (text) speakLine(text);
} else if (msg.type === 'setMode') {
const mode = normalizeMode(msg.payload?.mode);
if (MODE === 'both' && (mode === 'chat' || mode === 'speak')) {
activeMode = mode;
applyModeChrome();
}
}
});
// ── Avatar resolution (same allowlist contract as walk-embed) ─────────────
const AVATAR_HOST_ALLOWLIST = [
/^([a-z0-9-]+\.)*three\.ws$/i,
/^([a-z0-9-]+\.)*r2\.cloudflarestorage\.com$/i,
/^([a-z0-9-]+\.)*r2\.dev$/i,
/(^|\.)readyplayer\.me$/i,
/(^|\.)models\.readyplayer\.me$/i,
];
const GLB_PATH_RE = /\.(glb|gltf|vrm)(\?|#|$)/i;
function validateAvatarUrl(raw) {
if (raw.startsWith('/')) return raw;
let u;
try {
u = new URL(raw, location.origin);
} catch {
return null;
}
if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
if (u.origin === location.origin) return u.href;
if (!AVATAR_HOST_ALLOWLIST.some((re) => re.test(u.hostname))) return null;
if (!GLB_PATH_RE.test(u.pathname)) return null;
return u.href;
}
async function resolveAgentAvatarUrl(agentId) {
const r = await fetch(`/api/agents/${encodeURIComponent(agentId)}`, {
headers: { accept: 'application/json' },
});
if (!r.ok) throw new Error(`HTTP ${r.status} resolving agent avatar`);
const body = await r.json();
const rec = body?.agent || body;
const direct = rec?.avatar_model_url || rec?.avatar_glb_url || rec?.glb_url;
if (typeof direct === 'string' && GLB_PATH_RE.test(direct)) {
return validateAvatarUrl(direct) || `/api/avatars/${encodeURIComponent(rec.avatar_id)}/glb`;
}
if (rec?.avatar_id) return `/api/avatars/${encodeURIComponent(rec.avatar_id)}/glb`;
return AVATAR_URL_DEFAULT;
}
async function resolveAvatarUrl() {
const id = params.get('avatar');
if (id) {
if (/^https?:\/\//i.test(id) || id.startsWith('/')) {
const safe = validateAvatarUrl(id);
if (safe) return safe;
log.warn('[assistant-frame] rejected ?avatar= URL (origin/host not allowed):', id);
return AVATAR_URL_DEFAULT;
}
return `/api/avatars/${encodeURIComponent(id)}/glb`;
}
if (AGENT_PARAM) {
try {
return await resolveAgentAvatarUrl(AGENT_PARAM);
} catch (err) {
log.warn('[assistant-frame] agent avatar resolve failed, using default:', err?.message || err);
return AVATAR_URL_DEFAULT;
}
}
return AVATAR_URL_DEFAULT;
}
// ── Renderer / scene ──────────────────────────────────────────────────────
const renderer = new WebGLRenderer({ canvas, antialias: true, alpha: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
if (BG.kind === 'solid') renderer.setClearColor(new Color(BG.css), 1);
else renderer.setClearColor(0x000000, 0); // transparent + gradient: body paints, canvas stays clear
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = PCFShadowMap;
const scene = new Scene();
const pmrem = new PMREMGenerator(renderer);
scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
scene.add(new AmbientLight(0xffffff, 0.55));
const hemi = new HemisphereLight(0xbcd6ff, 0x202830, 0.6);
hemi.position.set(0, 5, 0);
scene.add(hemi);
const sun = new DirectionalLight(0xffffff, 1.35);
sun.position.set(3, 7, 5);
sun.castShadow = true;
sun.shadow.mapSize.set(1024, 1024);
sun.shadow.camera.near = 0.5;
sun.shadow.camera.far = 25;
sun.shadow.camera.left = -4;
sun.shadow.camera.right = 4;
sun.shadow.camera.top = 4;
sun.shadow.camera.bottom = -4;
sun.shadow.bias = -0.0005;
scene.add(sun);
// Soft shadow blob grounds the avatar on any host background (look2.png).
const shadowCatcher = new Mesh(new CircleGeometry(1.6, 48), new ShadowMaterial({ opacity: 0.3 }));
shadowCatcher.rotation.x = -Math.PI / 2;
shadowCatcher.receiveShadow = true;
scene.add(shadowCatcher);
const camera = new PerspectiveCamera(38, 1, 0.05, 100);
function sizeToStage() {
const w = stageEl.clientWidth || 1;
const h = stageEl.clientHeight || 1;
renderer.setSize(w, h, false);
camera.aspect = w / h;
camera.updateProjectionMatrix();
}
new ResizeObserver(sizeToStage).observe(stageEl);
sizeToStage();
// ── Avatar + animation ────────────────────────────────────────────────────
const animationManager = new AnimationManager();
let avatar = null;
let avatarHeight = 1.7;
let avatarYaw = 0;
let glance = { active: false, targetYaw: 0 };
const headAnchor = new Vector3();
const GLANCE_MAX_RAD = 0.35;
const GLANCE_LERP = 0.045;
let _loaderPromise = null;
function getAvatarLoader() {
if (!_loaderPromise) {
_loaderPromise = getMeshoptDecoder().then((decoder) => {
const loader = new GLTFLoader();
loader.setMeshoptDecoder(decoder);
return loader;
});
}
return _loaderPromise;
}
function frameAvatar() {
camera.position.set(0, avatarHeight * 0.92, avatarHeight * 2.05);
camera.lookAt(0, avatarHeight * 0.55, 0);
}
async function loadAvatar() {
const requestedUrl = await resolveAvatarUrl();
const loader = await getAvatarLoader();
let gltf;
let usedFallback = false;
try {
gltf = await loader.loadAsync(requestedUrl);
} catch (err) {
if (requestedUrl === AVATAR_URL_DEFAULT) throw err;
log.warn('[assistant-frame] avatar load failed, falling back to default:', err?.message || err);
usedFallback = true;
gltf = await loader.loadAsync(AVATAR_URL_DEFAULT);
}
avatar = gltf.scene;
avatar.traverse((n) => {
if (n.isMesh) {
n.castShadow = true;
n.receiveShadow = false;
if (n.material && 'envMapIntensity' in n.material) n.material.envMapIntensity = 0.85;
}
});
const box = new Box3().setFromObject(avatar);
avatar.position.y -= box.min.y;
avatarHeight = Math.max(0.5, box.max.y - box.min.y);
scene.add(avatar);
frameAvatar();
animationManager.attach(avatar);
const manifest = await fetch(ANIMATIONS_MANIFEST_URL, { cache: 'force-cache' }).then((r) => {
if (!r.ok) throw new Error(`HTTP ${r.status} fetching animation manifest`);
return r.json();
});
const needed = manifest.filter((d) => REQUIRED_CLIPS.has(d.name));
if (!needed.some((d) => d.name === CLIP_IDLE)) {
throw new Error('Animation manifest missing idle clip');
}
animationManager.setAnimationDefs(needed);
await animationManager.loadAll();
await animationManager.crossfadeTo(CLIP_IDLE, 0.0);
if (!PREFERS_REDUCED_MOTION && animationManager.supportsCanonicalClips?.() !== false) {
animationManager.playOnce(CLIP_GREET, { settleTo: CLIP_IDLE, fade: 0.2 });
}
if (usedFallback) setStatus("couldn't load that avatar — showing the default", { sticky: true });
return usedFallback;
}
let talking = false;
function setTalking(on) {
if (talking === on || !avatar) return;
talking = on;
if (animationManager.supportsCanonicalClips?.() === false) return;
animationManager.crossfadeTo(on ? CLIP_TALK : CLIP_IDLE, 0.3);
}
// Idle cursor-glance so the avatar notices the visitor (desktop only).
if (HAS_HOVER && !PREFERS_REDUCED_MOTION) {
canvas.addEventListener('pointermove', (e) => {
if (e.pointerType && e.pointerType !== 'mouse') return;
const rect = canvas.getBoundingClientRect();
if (!rect.width) return;
const ndcX = ((e.clientX - rect.left) / rect.width) * 2 - 1;
glance.targetYaw = -ndcX * GLANCE_MAX_RAD;
glance.active = true;
});
canvas.addEventListener('pointerleave', () => {
glance.active = false;
});
}
// ── Speech bubble ─────────────────────────────────────────────────────────
let bubbleHideTimer = 0;
function showBubble(text, { streaming = false, thinking = false, error = false, holdMs = 0 } = {}) {
clearTimeout(bubbleHideTimer);
bubbleTextEl.textContent = text;
bubbleEl.classList.toggle('is-streaming', streaming && !thinking);
bubbleEl.classList.toggle('is-thinking', thinking);
bubbleEl.classList.toggle('is-error', error);
bubbleEl.classList.add('is-visible');
if (holdMs > 0) bubbleHideTimer = setTimeout(hideBubble, holdMs);
}
function hideBubble() {
clearTimeout(bubbleHideTimer);
bubbleEl.classList.remove('is-visible', 'is-streaming', 'is-thinking');
}
function positionBubble() {
if (!avatar || !bubbleEl.classList.contains('is-visible')) return;
headAnchor.set(0, avatarHeight + 0.12, 0).applyMatrix4(avatar.matrixWorld);
headAnchor.project(camera);
const w = stageEl.clientWidth;
const h = stageEl.clientHeight;
const x = ((headAnchor.x + 1) / 2) * w;
const y = ((1 - headAnchor.y) / 2) * h;
const half = bubbleEl.offsetWidth / 2 + 8;
bubbleEl.style.left = `${Math.min(Math.max(x, half), w - half)}px`;
bubbleEl.style.top = `${Math.max(y - 14, bubbleEl.offsetHeight + 10)}px`;
}
// ── Web Speech TTS ────────────────────────────────────────────────────────
const hasTTS = typeof window !== 'undefined' && 'speechSynthesis' in window;
let voices = [];
let currentUtterance = null;
let speechGuardTimer = 0;
function loadVoices() {
if (!hasTTS) return;
voices = window.speechSynthesis.getVoices() || [];
const previous = settings.voiceName || '';
while (voiceSelectEl.options.length > 1) voiceSelectEl.remove(1);
for (const v of voices) {
const opt = document.createElement('option');
opt.value = v.name;
opt.textContent = `${v.name} (${v.lang})`;
voiceSelectEl.appendChild(opt);
}
voiceSelectEl.value = previous && voices.some((v) => v.name === previous) ? previous : '';
}
if (hasTTS) {
loadVoices();
window.speechSynthesis.addEventListener?.('voiceschanged', loadVoices);
}
function pickVoice() {
if (!voices.length) loadVoices();
if (settings.voiceName) {
const v = voices.find((x) => x.name === settings.voiceName);
if (v) return v;
}
return voices.find((v) => v.localService && v.lang?.startsWith('en')) || voices[0] || null;
}
function stopSpeaking() {
clearTimeout(speechGuardTimer);
if (hasTTS) window.speechSynthesis.cancel();
currentUtterance = null;
setTalking(false);
}
/**
* Speak `text` aloud (bubble is managed by the caller). Resolves when audio
* ends. Muted or TTS-less browsers resolve after the estimated read time so
* the talking animation and bubble still track the "speech".
*/
function speakAloud(text) {
stopSpeaking();
setTalking(true);
post('speak:start', { text });
return new Promise((resolve) => {
const finish = () => {
clearTimeout(speechGuardTimer);
if (currentUtterance === utter) currentUtterance = null;
setTalking(false);
post('speak:end', {});
resolve();
};
let utter = null;
if (hasTTS && voiceEnabled) {
utter = new SpeechSynthesisUtterance(text);
const v = pickVoice();
if (v) {
utter.voice = v;
utter.lang = v.lang;
}
utter.onend = finish;
utter.onerror = (e) => {
if (e?.error && !/interrupt|cancel/i.test(e.error)) {
log.warn('[assistant-frame] speech synthesis error:', e.error);
}
finish();
};
currentUtterance = utter;
// Safety net for engines that never fire onend (flaky on mobile).
speechGuardTimer = setTimeout(finish, estimateSpeechMs(text) + 2500);
try {
window.speechSynthesis.speak(utter);
return;
} catch (err) {
log.warn('[assistant-frame] speechSynthesis.speak failed:', err?.message || err);
}
}
// No TTS / muted: hold the talking animation for the estimated duration.
speechGuardTimer = setTimeout(finish, estimateSpeechMs(text));
});
}
/** Speak-mode line (also the postMessage `say` handler): bubble + audio. */
async function speakLine(text) {
showBubble(text);
await speakAloud(text);
bubbleHideTimer = setTimeout(hideBubble, 1200);
}
// ── Chat ──────────────────────────────────────────────────────────────────
const history = [];
let busy = false;
function systemPrompt() {
const lines = [
`You are ${NAME}, a friendly 3D avatar assistant embedded on a website.`,
'Answer in plain conversational text — no markdown, no lists, no code blocks.',
'Keep replies under 80 words unless the visitor asks for depth.',
];
if (CONTEXT) lines.push(`About this website: ${CONTEXT}`);
return lines.join('\n');
}
function pushHistory(role, content) {
history.push({ role, content });
while (history.length > MAX_HISTORY_TURNS * 2) history.shift();
}
/**
* Turn an /api/chat failure into a line the visitor can act on.
*
* The route already explains itself (`error_description`, plus `retry_after`
* seconds when the free provider chain is saturated), so surface that instead
* of a bare status code, and name the escape hatch the widget actually has:
* the visitor's own Groq or OpenRouter key, set in the settings panel.
*/
async function chatErrorMessage(res) {
let description = '';
let retryAfter = 0;
try {
const body = await res.json();
description = String(body?.error_description || '').trim();
retryAfter = Number(body?.retry_after) || 0;
} catch {
description = '';
}
if (res.status === 429 || res.status === 503) {
const wait = retryAfter ? `Try again in ${retryAfter}s` : 'Try again in a moment';
return `${description || 'The free chat lane is busy right now.'} ${wait}, or add your own Groq or OpenRouter key under Settings.`;
}
return description || `Chat failed (HTTP ${res.status}).`;
}
// A chat turn (request plus the whole stream) that has not finished by now is
// abandoned, so the thinking bubble can never sit forever on a wedged upstream.
const CHAT_DEADLINE_MS = 60_000;
/**
* Run one chat turn under the deadline: `fn` receives an AbortSignal to pass to
* fetch (aborting the fetch also ends its body reader), and an abort surfaces
* as a readable error on the existing bubble path.
*/
async function withChatDeadline(fn) {
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), CHAT_DEADLINE_MS);
try {
return await fn(ctrl.signal);
} catch (err) {
if (ctrl.signal.aborted || err?.name === 'AbortError') {
throw new Error('The reply took longer than 60 seconds. Try again, or switch lanes under Settings.');
}
throw err;
} finally {
clearTimeout(timer);
}
}
/** Stream a reply from /api/chat (platform free chain). */
function chatFree(message, onChunk) {
return withChatDeadline((signal) => chatFreeStream(message, onChunk, signal));
}
async function chatFreeStream(message, onChunk, signal) {
const res = await fetch('/api/chat', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ message, history: history.slice(0, -1), system_prompt: systemPrompt() }),
signal,
});
if (!res.ok || !res.body) throw new Error(await chatErrorMessage(res));
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
let accumulated = '';
let finalReply = '';
let streamError = '';
for (;;) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
let sep;
while ((sep = buffer.indexOf('\n\n')) !== -1) {
const frame = buffer.slice(0, sep);
buffer = buffer.slice(sep + 2);
const line = frame.split('\n').find((l) => l.startsWith('data:'));
if (!line) continue;
let evt;
try {
evt = JSON.parse(line.slice(5).trim());
} catch {
continue;
}
if (evt.type === 'chunk' && typeof evt.text === 'string') {
accumulated += evt.text;
onChunk(accumulated);
} else if (evt.type === 'done') {
finalReply = (evt.reply || accumulated || '').trim();
} else if (evt.type === 'error') {
streamError = evt.message || 'stream error';
}
}
}
if (streamError && !finalReply && !accumulated) throw new Error(streamError);
return (finalReply || accumulated).trim();
}
/** Stream a reply straight from the visitor's own provider (BYOK). */
function chatByok(lane, message, onChunk) {
return withChatDeadline((signal) => chatByokStream(lane, message, onChunk, signal));
}
async function chatByokStream(lane, message, onChunk, signal) {
const key = settings.keys[lane];
const model = settings.models[lane] || BYOK_DEFAULT_MODELS[lane];
const messages = [
{ role: 'system', content: systemPrompt() },
...history.slice(0, -1),
{ role: 'user', content: message },
];
const headers = { 'content-type': 'application/json', authorization: `Bearer ${key}` };
if (lane === 'openrouter') {
headers['HTTP-Referer'] = 'https://three.ws';
headers['X-Title'] = 'three.ws assistant widget';
}
const res = await fetch(BYOK_ENDPOINTS[lane], {
method: 'POST',
headers,
body: JSON.stringify({ model, messages, stream: true, max_tokens: 1024 }),
signal,
});
if (!res.ok || !res.body) {
if (res.status === 401 || res.status === 403) {
throw new Error(`Your ${lane} key was rejected — check it in settings.`);
}
if (res.status === 429) throw new Error(`${lane} rate limit hit — give it a moment.`);
throw new Error(`Chat failed (HTTP ${res.status}).`);
}
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
let accumulated = '';
for (;;) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
let nl;
while ((nl = buffer.indexOf('\n')) !== -1) {
const line = buffer.slice(0, nl).trim();
buffer = buffer.slice(nl + 1);
if (!line.startsWith('data:')) continue;
const payload = line.slice(5).trim();
if (payload === '[DONE]') continue;
let evt;
try {
evt = JSON.parse(payload);
} catch {
continue;
}
const delta = evt?.choices?.[0]?.delta?.content;
if (typeof delta === 'string' && delta) {
accumulated += delta;
onChunk(accumulated);
}
}
}
return accumulated.trim();
}
async function handleChat(message) {
pushHistory('user', message);
showBubble('', { thinking: true });
setTalking(true);
const lane = effectiveLane();
try {
const onChunk = (text) => showBubble(text, { streaming: true });
const reply = lane === 'free' ? await chatFree(message, onChunk) : await chatByok(lane, message, onChunk);
if (!reply) throw new Error('The model returned an empty reply — try again.');
pushHistory('assistant', reply);
post('message', { role: 'assistant', content: reply });
showBubble(reply);
if (voiceEnabled) {
await speakAloud(reply);
bubbleHideTimer = setTimeout(hideBubble, 6000);
} else {
setTalking(false);
bubbleHideTimer = setTimeout(hideBubble, Math.max(6000, estimateSpeechMs(reply)));
}
} catch (err) {
history.pop(); // failed turn doesn't poison the next one
setTalking(false);
// Hold an error as long as it takes to read: the at-capacity line names a
// wait and a settings escape hatch, and blinking away at 6s loses both.
const text = err?.message || 'Something went wrong, try again.';
showBubble(text, { error: true, holdMs: Math.max(6000, estimateSpeechMs(text)) });
}
}
// ── Composer wiring ───────────────────────────────────────────────────────
function autoGrow() {
inputEl.style.height = 'auto';
inputEl.style.height = `${Math.min(inputEl.scrollHeight, 96)}px`;
}
inputEl.addEventListener('input', autoGrow);
async function submit() {
const text = inputEl.value.trim();
if (!text || busy) return;
inputEl.value = '';
autoGrow();
busy = true;
sendBtn.disabled = true;
try {
post('message', { role: 'user', content: text, mode: activeMode });
if (activeMode === 'speak') await speakLine(text);
else await handleChat(text);
} finally {
busy = false;
sendBtn.disabled = false;
inputEl.focus();
}
}
sendBtn.addEventListener('click', submit);
inputEl.addEventListener('keydown', (e) => {
if (e.key === 'Enter' && !e.shiftKey) {
e.preventDefault();
submit();
}
});
for (const btn of modesEl.querySelectorAll('.mode-btn')) {
btn.addEventListener('click', () => {
if (activeMode === btn.dataset.mode) return;
activeMode = btn.dataset.mode;
stopSpeaking();
hideBubble();
applyModeChrome();
inputEl.focus();
});
}
voiceBtn.addEventListener('click', () => {
voiceEnabled = !voiceEnabled;
if (!voiceEnabled) stopSpeaking();
settings.voiceEnabled = voiceEnabled;
saveSettings();
applyVoiceChrome();
setStatus(voiceEnabled ? 'voice on' : 'voice off');
});
closeBtn.addEventListener('click', () => post('close', {}));
window.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
if (settingsEl.classList.contains('is-open')) toggleSettings(false);
else post('close', {});
}
});
// ── Settings wiring ───────────────────────────────────────────────────────
function toggleSettings(open) {
const willOpen = open ?? !settingsEl.classList.contains('is-open');
settingsEl.classList.toggle('is-open', willOpen);
settingsBtn.setAttribute('aria-expanded', String(willOpen));
if (willOpen) applyLaneChrome();
}
settingsBtn.addEventListener('click', () => toggleSettings());
settingsCloseBtn.addEventListener('click', () => toggleSettings(false));
for (const radio of settingsEl.querySelectorAll('input[name="assistant-lane"]')) {
radio.addEventListener('change', () => {
settings.lane = normalizeLane(radio.value);
saveSettings();
applyLaneChrome();
});
}
byokKeyEl.addEventListener('input', () => {
if (settings.lane === 'free') return;
settings.keys[settings.lane] = byokKeyEl.value.trim();
saveSettings();
lanePillEl.textContent = effectiveLane() === 'free' ? 'free' : `byok:${effectiveLane()}`;
});
byokModelEl.addEventListener('input', () => {
if (settings.lane === 'free') return;
settings.models[settings.lane] = byokModelEl.value.trim();
saveSettings();
});
voiceSelectEl.addEventListener('change', () => {
settings.voiceName = voiceSelectEl.value;
saveSettings();
});
// ── Render loop with visibility gating ────────────────────────────────────
const clock = new Timer();
let loopRunning = false;
let rafHandle = 0;
let canRender = false;
let onScreen = true;
function tick() {
clock.update();
const dt = Math.min(clock.getDelta(), 0.05);
if (avatar && HAS_HOVER && !PREFERS_REDUCED_MOTION) {
const targetYaw = glance.active ? glance.targetYaw : 0;
let diff = ((targetYaw - avatarYaw + Math.PI) % (Math.PI * 2)) - Math.PI;
if (diff < -Math.PI) diff += Math.PI * 2;
avatarYaw += diff * GLANCE_LERP;
avatar.rotation.y = avatarYaw;
}
animationManager.update(dt);
positionBubble();
renderer.render(scene, camera);
if (loopRunning) rafHandle = requestAnimationFrame(tick);
}
function startLoop() {
if (loopRunning || !canRender) return;
loopRunning = true;
clock.update();
rafHandle = requestAnimationFrame(tick);
}
function stopLoop() {
loopRunning = false;
if (rafHandle) {
cancelAnimationFrame(rafHandle);
rafHandle = 0;
}
}
function syncLoop() {
if (canRender && onScreen && !document.hidden) startLoop();
else stopLoop();
}
document.addEventListener('visibilitychange', syncLoop);
if (typeof IntersectionObserver === 'function') {
const io = new IntersectionObserver((entries) => {
onScreen = entries.some((en) => en.isIntersecting);
syncLoop();
}, { threshold: 0 });
io.observe(stageEl);
}
function hidePoster() {
posterEl.classList.add('is-hidden');
setTimeout(() => posterEl.remove(), 500);
}
// ── Boot ──────────────────────────────────────────────────────────────────
applyModeChrome();
applyLaneChrome();
applyVoiceChrome();
loadAvatar()
.then((usedFallback) => {
canRender = true;
syncLoop();
hidePoster();
post('ready', { mode: activeMode, fallback: usedFallback });
const greeting =
GREETING ||
(MODE === 'speak'
? "Type below and I'll say it out loud."
: `Hi! I'm ${NAME} — ask me anything.`);
showBubble(greeting, { holdMs: 7000 });
inputEl.focus();
})
.catch((err) => {
log.error('[assistant-frame] failed to load avatar:', err);
hidePoster();
canRender = true;
syncLoop();
setStatus(`failed to load avatar: ${err?.message ?? err}`, { error: true, sticky: true });
post('error', { code: 'avatar_load_failed', message: String(err?.message || err) });
});