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.

40.7 KB
Raw Blame
// Walk Companion — a persistent 3D avatar that walks and talks over your pages.
// =============================================================================
// A small avatar idles in the corner of every page, turns to follow the cursor,
// waves when you navigate, and greets you with a page-aware line. Click it and
// it detaches into the full-page Playground. An avatar picker lets each visitor
// choose who walks with them, from a diverse roster, and hot-swaps the rig live.
//
// This module is side-effect free on import: call `createWalkCompanion(config)`
// to get a controller, then `.bootstrap()` (or `.enable()`) to mount. That keeps
// it safe to `import` from a bundler while still supporting the app's
// inject-on-demand delivery.

import {
	AmbientLight,
	Box3,
	Timer,
	DirectionalLight,
	Group,
	HemisphereLight,
	PerspectiveCamera,
	Scene,
	Vector3,
	WebGLRenderer,
} from 'three';
import { reserveWebGLContext, releaseWebGLContext } from './internal/budget.js';
import { log } from './internal/log.js';
import {
	lsGet,
	lsSet,
	ssGet,
	ssSet,
	ssDel,
	prefersReducedMotion,
	webglSupported,
	clamp,
} from './internal/storage.js';
import { loadWalkAvatar } from './internal/load-avatar.js';
import { LookAtController } from './internal/runtime.js';
import { createAvatarPicker } from './picker.js';
import { resolveConfig, resolveAvatarEntry } from './config.js';

const CANVAS_W = 200;
const CANVAS_H = 280;
// Identifies this widget's claim on the corner in window.twsCornerStack.
const CORNER_RESERVE_KEY = 'walk-companion';
const CURSOR_IDLE_MS = 450; // cursor still longer than this → stop walking
const GAZE_IDLE_MS = 4000; // cursor still longer than this → gaze drifts back to the clip
const GAZE_PX_PER_M = 260; // page pixels per scene metre when aiming the head at the cursor
const BUBBLE_HOLD_MS = 5200; // default speech-bubble dwell before it retracts
// An announced message the companion was summoned for retreats this long after
// its bubble does, so the visitor sees the avatar acknowledge and walk off
// rather than vanish mid-sentence.
const ANNOUNCE_RETREAT_MS = 700;

function isExcludedRoute(config) {
	if (typeof window === 'undefined') return true;
	if (window.top !== window.self) return true; // never inside an iframe/embed
	const path = location.pathname.replace(/\/$/, '') || '/';
	return config.excludedRoutes.some((p) => path === p || path.startsWith(p + '/'));
}

// ── Default page-context greeting (overridable via config.greeting) ───────────
function defaultGreeting(path) {
	if (path === '/pricing' || path === '/x-pricing')
		return 'Picking a plan? I can point you to the popular one.';
	if (path === '/features') return 'Tap any feature card to see it in action.';
	if (path.startsWith('/agent') || path.startsWith('/a/') || path.startsWith('/marketplace')) {
		const name = pageSubjectName();
		return name ? `Say hi to ${name}!` : 'Browse agents — I’ll tag along.';
	}
	if (path === '/' || path.startsWith('/home')) return 'Hey! I’m your guide. I’ll walk with you.';
	return 'I’ll walk along while you explore.';
}

function pageSubjectName() {
	const el = document.querySelector('[data-agent-name], .agent-name, h1');
	const txt = el?.textContent?.trim();
	if (!txt || txt.length > 40) return null;
	return txt;
}

function contextTargetEl() {
	const path = location.pathname.replace(/\/$/, '') || '/';
	if (path === '/pricing' || path === '/x-pricing') {
		return document.querySelector(
			'[data-recommended], .pricing-card.is-featured, .plan.is-popular, .pricing-card--popular',
		);
	}
	if (path === '/features') return document.querySelector('.feature-card, [data-feature]');
	return null;
}

// ── The companion instance ───────────────────────────────────────────────────
class WalkCompanion {
	constructor(config, owner) {
		this.config = config;
		this.owner = owner; // the factory control object (for playground hand-off)
		this.mounted = false;
		this.host = null;
		this.renderer = null;
		this.scene = null;
		this.camera = null;
		this.rig = null;
		this.model = null;
		this.controller = null;
		this.clock = null;
		this._raf = 0;
		this._reduced = prefersReducedMotion();
		this._currentEntry = null;
		this._picker = null;

		this._cursorX = window.innerWidth * 0.5;
		this._cursorY = window.innerHeight * 0.5;
		this._cursorMovedAt = 0;
		// Bubble arbitration: what is on screen now and until when (see say()).
		this._bubblePriority = 0;
		this._bubbleUntil = 0;
		this._yaw = 0;
		this._targetYaw = 0;
		this._lookAt = null;
		this._gazeTarget = new Vector3();
		// Touch devices have no hovering cursor to follow, so the companion would
		// sit frozen in idle. On a coarse pointer it wanders on its own instead —
		// switched off the moment a real (fine) pointer moves it.
		this._autonomous =
			typeof matchMedia === 'function' ? !matchMedia('(pointer: fine)').matches : false;
		this._autoWalking = false;
		this._autoUntil = 0;
		this._onPointerMove = this._onPointerMove.bind(this);
		this._onLinkClick = this._onLinkClick.bind(this);
		this._onVisibility = this._onVisibility.bind(this);
		this._onPageHide = this._onPageHide.bind(this);
		this._tick = this._tick.bind(this);
		this._syncCornerReserve = this._syncCornerReserve.bind(this);
	}

	/**
	 * Tell the host page's corner stack how much of the bottom-right corner this
	 * companion occupies, so its cards ("Getting started", feature discovery)
	 * stack above the avatar instead of underneath it.
	 *
	 * Measured from computed style rather than getBoundingClientRect(): the host
	 * animates in with a translateY, and a rect read mid-transition would report
	 * a short-changed height that the stack would then settle into.
	 *
	 * Optional by design. The SDK ships standalone, so a page without the corner
	 * stack simply skips this.
	 */
	_syncCornerReserve() {
		const stack = typeof window !== 'undefined' ? window.twsCornerStack : null;
		if (!stack || typeof stack.reserve !== 'function' || !this.host) return;
		const cs = getComputedStyle(this.host);
		const bottom = parseFloat(cs.bottom) || 0;
		const height = parseFloat(cs.height) || 0;
		if (height <= 0) return;
		// Width as well as height: on a phone the stack goes full-width, and a
		// lift tall enough to clear the companion would strand its chips in the
		// middle of the page. With the width declared, the stack can step aside
		// and stay at the bottom instead.
		const right = parseFloat(cs.right) || 0;
		const width = parseFloat(cs.width) || 0;
		stack.reserve(CORNER_RESERVE_KEY, {
			height: bottom + height,
			width: width > 0 ? right + width : 0,
			// The host is a bottom-anchored fixed box, which is exactly the shape
			// the stack's dock probe looks for. Handing it over means the claim is
			// counted once (here) instead of twice, which is what used to lift the
			// stack into the middle of a phone screen.
			el: this.host,
		});
	}

	/**
	 * Mount the corner companion.
	 * @param {{greet?: boolean}} [opts] `greet: false` skips the page greeting
	 *   and the follow-up invite bubble, used when the companion is summoned to
	 *   deliver a specific message (see the control object's `announce`), where a
	 *   greeting would talk over it.
	 */
	async mount({ greet = true } = {}) {
		if (this.mounted || isExcludedRoute(this.config)) return;
		if (!webglSupported()) return;
		this.mounted = true;

		this._buildDom();
		try {
			await this._buildScene();
		} catch (err) {
			log.warn('companion failed to load avatar:', err?.message || err);
			this._teardownScene();
			this._showError();
			return;
		}

		this.host?.classList.remove('is-loading');
		this._restoreState();
		this._bindEvents();
		if (greet) this._greetForRoute();
		else this._orientToContext();
		this.clock = new Timer();
		this._raf = requestAnimationFrame(this._tick);
	}

	unmount() {
		if (!this.mounted) return;
		this.mounted = false;
		cancelAnimationFrame(this._raf);
		this._raf = 0;
		window.removeEventListener('pointermove', this._onPointerMove);
		document.removeEventListener('click', this._onLinkClick, true);
		document.removeEventListener('visibilitychange', this._onVisibility);
		window.removeEventListener('pagehide', this._onPageHide);
		clearTimeout(this._inviteTimer);
		clearTimeout(this._orientTimer);
		clearTimeout(this._bubbleTimer);
		this._picker?.destroy();
		this._picker = null;
		this._teardownScene();
		window.removeEventListener('resize', this._syncCornerReserve);
		window.removeEventListener('tws-corner-stack:ready', this._syncCornerReserve);
		window.twsCornerStack?.release?.(CORNER_RESERVE_KEY);
		if (this.host && this.host.parentNode) this.host.parentNode.removeChild(this.host);
		this.host = null;
	}

	// ── DOM / styles ──────────────────────────────────────────────────────────
	_buildDom() {
		ensureStyles();
		const host = document.createElement('div');
		host.className = 'walk-companion is-loading';
		host.setAttribute('role', 'complementary');
		host.setAttribute('aria-label', 'Walk companion');
		const pickerBtn = this.config.enablePicker
			? `<button type="button" class="walk-companion-swap" data-walk-picker-toggle aria-label="Choose a different avatar" title="Choose avatar">⇄</button>`
			: '';
		host.innerHTML = `
			<button type="button" class="walk-companion-close" aria-label="Dismiss walk companion" title="Dismiss">×</button>
			${pickerBtn}
			<div class="walk-companion__skel" aria-hidden="true"></div>
			<div class="walk-companion-bubble" role="status" aria-live="polite" aria-atomic="true" hidden></div>
			<canvas class="walk-companion-canvas" width="${CANVAS_W}" height="${CANVAS_H}" role="button" tabindex="0" aria-label="Walk companion avatar: activate to let it walk around the page"></canvas>
		`;
		document.body.appendChild(host);
		this.host = host;
		this.canvas = host.querySelector('.walk-companion-canvas');
		this.bubble = host.querySelector('.walk-companion-bubble');
		host.querySelector('.walk-companion-close').addEventListener('click', (e) => {
			e.stopPropagation();
			this.owner.disable();
		});
		host.querySelector('.walk-companion-swap')?.addEventListener('click', (e) => {
			e.stopPropagation();
			this.openPicker();
		});
		// Clicking the avatar detaches it into Playground mode.
		const detach = () => this.owner._detachToPlayground(this);
		this.canvas.addEventListener('click', detach);
		this.canvas.addEventListener('keydown', (e) => {
			if (e.key !== 'Enter' && e.key !== ' ') return;
			e.preventDefault();
			detach();
		});
		requestAnimationFrame(() => host.classList.add('is-in'));
		// Claim the corner before anything else settles there, and re-measure on
		// resize: the narrow-viewport rule shrinks the companion to 148x208.
		// Bound here rather than in _bindEvents() so the claim survives the
		// avatar-failed-to-load path, where the host stays on the page.
		this._syncCornerReserve();
		window.addEventListener('resize', this._syncCornerReserve);
		// If the corner stack has not booted yet, claim the corner the moment it
		// does. Without this the companion could win the load race and silently
		// keep no reservation at all.
		window.addEventListener('tws-corner-stack:ready', this._syncCornerReserve);
	}

	_showError() {
		if (this.host && this.host.parentNode) this.host.parentNode.removeChild(this.host);
		this.host = null;
		this.mounted = false;
	}

	// ── Three.js scene ────────────────────────────────────────────────────────
	async _buildScene() {
		const renderer = new WebGLRenderer({ canvas: this.canvas, alpha: true, antialias: true });
		renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5));
		renderer.setSize(CANVAS_W, CANVAS_H, false);
		this.renderer = renderer;
		reserveWebGLContext();

		const scene = new Scene();
		this.scene = scene;
		scene.add(new AmbientLight(0xffffff, 0.85));
		const hemi = new HemisphereLight(0xbcd6ff, 0x202830, 0.7);
		hemi.position.set(0, 4, 0);
		scene.add(hemi);
		const sun = new DirectionalLight(0xffffff, 1.6);
		sun.position.set(2, 5, 4);
		scene.add(sun);

		const camera = new PerspectiveCamera(40, CANVAS_W / CANVAS_H, 0.05, 100);
		this.camera = camera;

		const rig = new Group();
		scene.add(rig);
		this.rig = rig;

		const entry = this._resolveEntry();
		await this._loadInto(entry);
	}

	_resolveEntry() {
		const param =
			typeof location !== 'undefined'
				? new URLSearchParams(location.search).get('avatar')
				: null;
		if (param) lsSet(this.config.keys.avatar, param);
		const id = param || lsGet(this.config.keys.avatar) || this.config.defaultAvatarId;
		return resolveAvatarEntry(id, this.config);
	}

	async _loadInto(entry) {
		const fallback = resolveAvatarEntry(this.config.defaultAvatarId, this.config);
		const {
			model,
			controller,
			entry: active,
		} = await loadWalkAvatar(entry, {
			assetBase: this.config.assetBase,
			apiBase: this.config.apiBase,
			manifestUrl: this.config.manifestUrl,
			fallbackEntry: fallback,
		});
		this.model = model;
		this.controller = controller;
		this._currentEntry = active;
		this._frame(model, this.rig, this.camera);
	}

	// Center on X/Z, drop feet to the floor, frame the camera on the full body.
	_frame(model, rig, camera) {
		const box = new Box3().setFromObject(model);
		const size = box.getSize(new Vector3());
		const center = box.getCenter(new Vector3());
		model.position.x -= center.x;
		model.position.z -= center.z;
		model.position.y -= box.min.y;
		rig.add(model);

		const height = Math.max(0.6, size.y);
		camera.position.set(0, height * 0.62, height * 2.25);
		camera.lookAt(0, height * 0.52, 0);
		this._height = height;

		// Procedural cursor gaze (config-gated, humanoid rigs only): the head
		// turns to follow the visitor's pointer on top of whatever clip plays.
		// A rig with no mappable head reports enabled=false and stays null, so
		// embedded props (robot, fox) keep their baked motion untouched. Rebuilt
		// here on every load so an avatar swap re-resolves its own bones.
		this._lookAt = null;
		if (this.config.lookAt && !this._reduced) {
			const lookAt = new LookAtController(model);
			if (lookAt.enabled) this._lookAt = lookAt;
		}
	}

	// ── Live avatar swap (from the picker) ────────────────────────────────────
	/**
	 * @param {string|object} idOrEntry roster id, or a roster-shaped entry.
	 * @param {object} [opts]
	 * @param {boolean} [opts.persist=true] remember the choice for next page.
	 *   A guest delivery (announce({ avatar })) swaps without persisting, so the
	 *   visitor's own companion is still theirs after the message is over.
	 * @param {boolean} [opts.chatter=true] say the "Switching…" / "Say hi" lines.
	 */
	async setAvatar(idOrEntry, { persist = true, chatter = true } = {}) {
		const entry =
			typeof idOrEntry === 'string' ? resolveAvatarEntry(idOrEntry, this.config) : idOrEntry;
		if (!entry) return;
		if (persist) lsSet(this.config.keys.avatar, entry.id);
		if (persist) this._picker?.setCurrent(entry.id);
		if (!this.mounted || !this.rig) return; // will apply on next mount
		if (chatter) this._say('Switching…');
		try {
			const fallback = resolveAvatarEntry(this.config.defaultAvatarId, this.config);
			const {
				model,
				controller,
				entry: active,
			} = await loadWalkAvatar(entry, {
				assetBase: this.config.assetBase,
				apiBase: this.config.apiBase,
				manifestUrl: this.config.manifestUrl,
				fallbackEntry: fallback,
			});
			if (!this.mounted) {
				disposeObject(model);
				controller.dispose?.();
				return;
			}
			if (this.model) {
				this.rig.remove(this.model);
				disposeObject(this.model);
			}
			this.controller?.dispose();
			this._yaw = 0;
			this._targetYaw = 0;
			this.rig.rotation.y = 0;
			this.model = model;
			this.controller = controller;
			this._currentEntry = active;
			this._frame(model, this.rig, this.camera);
			if (chatter) this._say(`Say hi to ${active.name}!`);
		} catch (err) {
			log.warn('avatar swap failed:', err?.message || err);
			if (chatter) this._say('Couldn’t load that one. Try another.');
		}
	}

	openPicker() {
		if (!this.config.enablePicker) return;
		if (!this._picker) {
			this._picker = createAvatarPicker({
				avatars: this.config.avatars,
				currentId: this._currentEntry?.id || this.config.defaultAvatarId,
				assetBase: this.config.assetBase,
				docsUrl: this.config.docsUrl,
				anchor: { right: 16, bottom: CANVAS_H + 28 },
				onSelect: (entry) => this.setAvatar(entry),
			});
		}
		this._picker.toggle();
	}

	_teardownScene() {
		try {
			this.controller?.dispose();
		} catch {
			/* non-fatal */
		}
		this.controller = null;
		this.model = null;
		this._lookAt = null;
		if (this.scene) {
			this.scene.traverse((n) => {
				if (n.isMesh) disposeMesh(n);
			});
		}
		this.scene = null;
		if (this.renderer) {
			this.renderer.dispose();
			this.renderer.forceContextLoss?.();
			this.renderer = null;
			releaseWebGLContext();
		}
	}

	// ── Events ────────────────────────────────────────────────────────────────
	_bindEvents() {
		window.addEventListener('pointermove', this._onPointerMove, { passive: true });
		document.addEventListener('click', this._onLinkClick, true);
		document.addEventListener('visibilitychange', this._onVisibility);
		window.addEventListener('pagehide', this._onPageHide);
	}

	_onPointerMove(e) {
		// A genuine fine pointer (mouse/trackpad/stylus) takes over cursor-follow;
		// touch-drag (pointerType 'touch') leaves the autonomous wander in charge.
		if (e.pointerType && e.pointerType !== 'touch') this._autonomous = false;
		this._cursorX = e.clientX;
		this._cursorY = e.clientY;
		this._cursorMovedAt = performance.now();
	}

	_onLinkClick(e) {
		const a = e.target.closest?.('a[href]');
		if (!a) return;
		if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey) return;
		const href = a.getAttribute('href');
		if (!href || href.startsWith('#')) return;
		if (a.target && a.target !== '_self') return;
		let url;
		try {
			url = new URL(href, location.href);
		} catch {
			return;
		}
		if (url.origin !== location.origin) return;
		if (url.pathname === location.pathname) return;
		this.controller?.playWave();
		ssSet(this.config.keys.greet, '1');
	}

	_onVisibility() {
		if (document.hidden) {
			cancelAnimationFrame(this._raf);
			this._raf = 0;
		} else if (this.mounted && !this._raf) {
			this.clock?.update();
			this._raf = requestAnimationFrame(this._tick);
		}
	}

	_onPageHide() {
		this._persistState();
	}

	// ── Greeting / speech bubble ──────────────────────────────────────────────
	_greetForRoute() {
		const arrivedByNav = ssGet(this.config.keys.greet) === '1';
		ssDel(this.config.keys.greet);
		if (arrivedByNav) this.controller?.playWave();
		this._orientToContext();
		const path = location.pathname.replace(/\/$/, '') || '/';
		const greet = (this.config.greeting && this.config.greeting(path)) ?? defaultGreeting(path);
		this._say(greet);
		if (ssGet(this.config.keys.invited) !== '1') {
			ssSet(this.config.keys.invited, '1');
			clearTimeout(this._inviteTimer);
			this._inviteTimer = setTimeout(() => {
				if (this.mounted)
					this._say(this._autonomous ? 'Tap me to walk the whole page →' : 'Click me to walk the whole page →');
			}, 5600);
		}
	}

	_orientToContext() {
		const el = contextTargetEl();
		if (!el) return;
		const rect = el.getBoundingClientRect();
		const elCenterX = rect.left + rect.width / 2;
		const hostRect = this.host.getBoundingClientRect();
		const hostCenterX = hostRect.left + hostRect.width / 2;
		this._targetYaw = clamp((elCenterX - hostCenterX) / window.innerWidth, -0.6, 0.6);
		this._orientLock = true;
		clearTimeout(this._orientTimer);
		this._orientTimer = setTimeout(() => {
			this._orientLock = false;
		}, 4000);
	}

	_say(text) {
		this.say(text);
	}

	/**
	 * Show a speech bubble over the companion.
	 *
	 * The greeting flow calls this with no options (5.2s, plain text). Callers
	 * that deliver something the visitor may want to act on pass `actions`:
	 * up to two links/buttons rendered under the line, which also switches the
	 * bubble to pointer-events:auto so they are clickable.
	 *
	 * @param {string} text
	 * @param {object} [opts]
	 * @param {number} [opts.hold=5200] ms before the bubble retracts; 0 keeps it
	 *   up until the next say()/hideBubble().
	 * @param {'neutral'|'alert'} [opts.tone='neutral'] 'alert' tints the bubble.
	 * @param {Array<{label:string, href?:string, title?:string, onClick?:Function}>} [opts.actions]
	 * @param {number} [opts.priority=0] higher wins: a line at a lower priority
	 *   is dropped while a higher-priority one is still showing. Deliveries
	 *   (announce) speak at 1, ambient chatter at 0.
	 * @returns {boolean} false when there is no bubble to render into.
	 */
	say(text, { hold = BUBBLE_HOLD_MS, tone = 'neutral', actions = null, priority = 0 } = {}) {
		if (!this.bubble || !text) return false;
		// The companion has more than one voice: the page greeting, the invite
		// nudge, the identity introduction, and a delivered message all reach for
		// the same bubble. A lower-priority line must never overwrite a delivery
		// while it is still on screen, whichever fires first.
		if (priority < this._bubblePriority && Date.now() < this._bubbleUntil) return false;
		const bubble = this.bubble;
		clearTimeout(this._bubbleTimer);
		bubble.textContent = '';

		const line = document.createElement('span');
		line.className = 'walk-companion-bubble-line';
		line.textContent = text;
		bubble.appendChild(line);

		const rendered = (actions || []).filter((a) => a && a.label).slice(0, 2);
		if (rendered.length) {
			const row = document.createElement('span');
			row.className = 'walk-companion-bubble-actions';
			for (const action of rendered) {
				// An href makes it a real link (middle-click, copy, keyboard);
				// otherwise it is a button so it never navigates by accident.
				const el = document.createElement(action.href ? 'a' : 'button');
				el.className = 'walk-companion-bubble-action';
				el.textContent = action.label;
				// A two-word pill is all that fits beside an avatar, so the full
				// intent lives on the accessible name and the tooltip.
				if (action.title) {
					el.title = action.title;
					el.setAttribute('aria-label', action.title);
				}
				if (action.href) el.href = action.href;
				else el.type = 'button';
				if (typeof action.onClick === 'function') {
					el.addEventListener('click', (e) => {
						e.stopPropagation();
						action.onClick(e);
					});
				}
				row.appendChild(el);
			}
			bubble.appendChild(row);
		}

		bubble.classList.toggle('is-alert', tone === 'alert');
		bubble.classList.toggle('has-actions', rendered.length > 0);
		bubble.hidden = false;
		bubble.classList.add('is-in');
		this._bubblePriority = priority;
		this._bubbleUntil = hold > 0 ? Date.now() + hold : Number.MAX_SAFE_INTEGER;
		if (hold > 0) this._bubbleTimer = setTimeout(() => this.hideBubble(), hold);
		return true;
	}

	/** Retract the speech bubble now. */
	hideBubble() {
		clearTimeout(this._bubbleTimer);
		this._bubblePriority = 0;
		this._bubbleUntil = 0;
		if (!this.bubble) return;
		const bubble = this.bubble;
		bubble.classList.remove('is-in');
		setTimeout(() => {
			// A newer say() may have re-opened it while this retraction ran.
			if (bubble && !bubble.classList.contains('is-in')) bubble.hidden = true;
		}, 300);
	}

	// ── Persistence ───────────────────────────────────────────────────────────
	_persistState() {
		if (!this.controller) return;
		lsSet(this.config.keys.state, JSON.stringify({ yaw: this._yaw }));
	}

	_restoreState() {
		try {
			const raw = lsGet(this.config.keys.state);
			if (!raw) return;
			const s = JSON.parse(raw);
			if (typeof s.yaw === 'number') {
				this._yaw = s.yaw;
				this._targetYaw = s.yaw;
			}
		} catch {
			/* corrupt state — ignore */
		}
	}

	// ── Render loop ───────────────────────────────────────────────────────────
	_tick() {
		if (!this.mounted) return;
		this.clock.update();
		const dt = Math.min(this.clock.getDelta(), 0.05);

		const now = performance.now();
		const movingRecently = now - this._cursorMovedAt < CURSOR_IDLE_MS;
		if (this._autonomous) {
			if (!this._reduced && !this._orientLock && now >= this._autoUntil) {
				this._autoWalking = !this._autoWalking;
				if (this._autoWalking) {
					// Stroll toward a fresh heading, then pause and face it.
					this._targetYaw = clamp(Math.random() * 1.2 - 0.6, -0.6, 0.6);
					this._autoUntil = now + 1800 + Math.random() * 2200;
				} else {
					this._autoUntil = now + 900 + Math.random() * 1600;
				}
			}
		} else if (!this._reduced && !this._orientLock) {
			const rel = (this._cursorX - window.innerWidth / 2) / (window.innerWidth / 2);
			this._targetYaw = clamp(rel * 0.7, -0.7, 0.7);
		}
		const turning = Math.abs(this._targetYaw - this._yaw) > 0.04;
		const walkCue = this._autonomous ? this._autoWalking : movingRecently;
		const shouldWalk = !this._reduced && (walkCue || turning);
		this.controller?.setState(shouldWalk ? 'walk' : 'idle');

		this._yaw += (this._targetYaw - this._yaw) * 0.12;
		if (this.rig) this.rig.rotation.y = this._yaw;

		this.controller?.update(dt);
		this._updateGaze(now, dt);
		this.renderer.render(this.scene, this.camera);
		this._raf = requestAnimationFrame(this._tick);
	}

	// Head tracking: map the page cursor into a scene-space point in front of
	// the avatar and let the IK layer chase it. Runs AFTER controller.update()
	// (the mixer tick) per the procedural-layer contract. When the cursor has
	// been still for a while, or there is no fine pointer at all, the target
	// clears and the gaze fades back to the clip's own head motion.
	_updateGaze(now, dt) {
		if (!this._lookAt) return;
		const cursorLive = !this._autonomous && now - this._cursorMovedAt < GAZE_IDLE_MS;
		if (cursorLive && this.host) {
			const rect = this.host.getBoundingClientRect();
			const dx = this._cursorX - (rect.left + rect.width / 2);
			const dy = this._cursorY - (rect.top + rect.height * 0.35);
			const h = this._height || 1.6;
			this._gazeTarget.set(
				dx / GAZE_PX_PER_M,
				h * 0.85 - dy / GAZE_PX_PER_M,
				h * 2,
			);
			this._lookAt.setTarget(this._gazeTarget);
		} else {
			this._lookAt.setTarget(null);
		}
		this._lookAt.update(dt);
	}
}

// ── Shared disposal helpers ───────────────────────────────────────────────────
function disposeMesh(n) {
	n.geometry?.dispose?.();
	const mats = Array.isArray(n.material) ? n.material : [n.material];
	mats.forEach((m) => {
		if (!m) return;
		for (const v of Object.values(m)) if (v && v.isTexture) v.dispose();
		m.dispose?.();
	});
}
function disposeObject(obj) {
	obj?.traverse?.((n) => {
		if (n.isMesh) disposeMesh(n);
	});
}

// ── Scoped styles (injected once) ─────────────────────────────────────────────
let _stylesInjected = false;
function ensureStyles() {
	if (_stylesInjected) return;
	_stylesInjected = true;
	const style = document.createElement('style');
	style.id = 'walk-companion-style';
	style.textContent = `
.walk-companion{position:fixed;right:16px;bottom:16px;width:${CANVAS_W}px;height:${CANVAS_H}px;z-index:2147483000;pointer-events:none;opacity:0;transform:translateY(12px);transition:opacity .35s ease,transform .35s ease;-webkit-user-select:none;user-select:none}
.walk-companion.is-in{opacity:1;transform:translateY(0)}
.walk-companion-canvas{position:absolute;inset:0;width:100%;height:100%;z-index:1;pointer-events:auto;cursor:pointer;touch-action:pan-y;filter:drop-shadow(0 18px 22px rgba(0,0,0,.32))}
.walk-companion__skel{position:absolute;left:50%;bottom:8%;z-index:0;width:46%;height:70%;transform:translateX(-50%);border-radius:46% 46% 40% 40%/55% 55% 45% 45%;overflow:hidden;opacity:0;transition:opacity .25s ease;pointer-events:none;background:linear-gradient(180deg,rgba(122,162,255,.18),rgba(18,20,28,.10))}
.walk-companion.is-loading .walk-companion__skel{opacity:1}
.walk-companion-canvas:focus-visible{outline:2px solid var(--accent,#7c9cff);outline-offset:-4px;border-radius:12px}
.walk-companion.is-loading .walk-companion-canvas{opacity:0}
.walk-companion__skel::after{content:'';position:absolute;inset:0;background:linear-gradient(110deg,transparent 18%,rgba(255,255,255,.22) 46%,transparent 72%);transform:translateX(-120%);animation:walk-companion-shimmer 1.2s ease-in-out infinite}
.walk-companion-close,.walk-companion-swap{position:absolute;top:2px;z-index:3;width:22px;height:22px;border:none;border-radius:50%;background:rgba(12,14,20,.55);color:#fff;font-size:14px;line-height:1;cursor:pointer;pointer-events:auto;opacity:0;transition:opacity .2s ease,background .2s ease;display:grid;place-items:center;padding:0}
.walk-companion-close{right:2px;font-size:15px}
.walk-companion-swap{right:28px}
.walk-companion:hover .walk-companion-close,.walk-companion:focus-within .walk-companion-close,.walk-companion:hover .walk-companion-swap,.walk-companion:focus-within .walk-companion-swap{opacity:1}
.walk-companion-close:hover{background:rgba(220,60,60,.85)}
.walk-companion-swap:hover{background:rgba(122,162,255,.85)}
.walk-companion-close:focus-visible,.walk-companion-swap:focus-visible{outline:2px solid #7aa2ff;outline-offset:2px;opacity:1}
.walk-companion-bubble{position:absolute;left:50%;bottom:calc(100% - 38px);z-index:2;transform:translateX(-50%) translateY(6px);box-sizing:border-box;max-width:min(216px,calc(100vw - 16px));width:max-content;background:rgba(18,20,28,.94);color:#f2f4f8;font:500 12.5px/1.4 system-ui,-apple-system,'Segoe UI',sans-serif;padding:8px 11px;border-radius:12px;border:1px solid rgba(255,255,255,.1);box-shadow:0 10px 28px rgba(0,0,0,.35);pointer-events:none;opacity:0;transition:opacity .3s ease,transform .3s ease;text-align:center}
.walk-companion-bubble.is-in{opacity:1;transform:translateX(-50%) translateY(0)}
.walk-companion-bubble.is-alert{background:rgba(20,18,32,.96);border-color:rgba(122,162,255,.5);box-shadow:0 10px 28px rgba(0,0,0,.45),0 0 0 1px rgba(122,162,255,.18)}
.walk-companion-bubble.is-alert::after{border-top-color:rgba(20,18,32,.96)}
.walk-companion-bubble.has-actions{pointer-events:auto;z-index:4}
/* z-index 4 puts an actionable bubble ABOVE the chrome control row (z-index 3).
   Without it the controls sit over the bubble's own buttons and swallow the
   click: the buttons render, highlight on hover, and do nothing. Only bubbles
   that HAVE actions are raised, so a plain caption never covers the close or
   swap controls. */
.walk-companion-bubble-line{display:block}
.walk-companion-bubble-actions{display:flex;gap:6px;justify-content:center;flex-wrap:wrap;margin-top:7px}
.walk-companion-bubble-action{appearance:none;border:1px solid rgba(255,255,255,.16);background:rgba(255,255,255,.06);color:#dbe6ff;font:600 11.5px/1 system-ui,-apple-system,'Segoe UI',sans-serif;padding:5px 9px;border-radius:999px;cursor:pointer;text-decoration:none;transition:background .15s ease,border-color .15s ease,color .15s ease}
.walk-companion-bubble-action:hover{background:rgba(122,162,255,.22);border-color:rgba(122,162,255,.55);color:#fff}
.walk-companion-bubble-action:active{background:rgba(122,162,255,.34)}
.walk-companion-bubble-action:focus-visible{outline:2px solid #7aa2ff;outline-offset:2px}
@media (pointer:coarse){.walk-companion-bubble-action{padding:9px 12px;font-size:12.5px}}
.walk-companion-bubble::after{content:'';position:absolute;left:50%;top:100%;transform:translateX(-50%);border:6px solid transparent;border-top-color:rgba(18,20,28,.94)}
@media (max-width:520px){.walk-companion{width:148px;height:208px;right:10px;bottom:10px}.walk-companion-bubble{font-size:11.5px;max-width:min(156px,calc(100vw - 12px))}}
@media (pointer:coarse){.walk-companion-close,.walk-companion-swap{opacity:1;width:44px;height:44px;top:-7px;border:9px solid transparent;background-clip:padding-box}.walk-companion-close{right:-7px}.walk-companion-swap{right:23px}}
@keyframes walk-companion-shimmer{to{transform:translateX(120%)}}
@media (prefers-reduced-motion:reduce){.walk-companion,.walk-companion-bubble{transition:none}.walk-companion__skel::after{animation:none;opacity:.5}}
`;
	document.head.appendChild(style);
}

/**
 * Resolve the avatar id for a bootstrap path that never mounts the corner
 * companion (the `?walk=play` deep link and the playground drop-in resume).
 *
 * `setAvatar()`/the picker persist the visitor's choice via `config.keys.avatar`,
 * but the playground launch paths read that key directly and never looked at
 * the query string, so `?walk=play&avatar=fox` silently loaded the stored (or
 * default) avatar instead of `fox`. This gives `?avatar=` precedence and
 * persists it, the same way picking an avatar in the UI would.
 *
 * @param {object} config resolved config (for its storage keys)
 * @param {URLSearchParams} params the current query string
 * @returns {string|null} the avatar id to launch with, or null for the default
 */
export function deepLinkAvatarId(config, params) {
	const param = params.get('avatar');
	if (param) lsSet(config.keys.avatar, param);
	return param || lsGet(config.keys.avatar) || null;
}

// ── Factory + control object ──────────────────────────────────────────────────
/**
 * Create a Walk Companion controller. Side-effect free: nothing mounts until
 * `enable()` or `bootstrap()` is called.
 * @param {object} [opts] see config.js / README for the full option set
 */
export function createWalkCompanion(opts = {}) {
	const config = resolveConfig(opts);
	let instance = null;
	let pgWired = false;

	const isEnabled = () => lsGet(config.keys.enabled) === '1';

	function emitChange() {
		try {
			window.dispatchEvent(
				new CustomEvent('walk-companion:change', { detail: { enabled: isEnabled() } }),
			);
		} catch {
			/* non-fatal */
		}
	}

	const control = {
		config,
		get instance() {
			return instance;
		},
		isEnabled,
		enable() {
			lsSet(config.keys.enabled, '1');
			if (!instance) instance = new WalkCompanion(config, control);
			instance.mount();
			emitChange();
		},
		disable() {
			lsSet(config.keys.enabled, '0');
			if (instance) instance.unmount();
			emitChange();
		},
		toggle() {
			if (isEnabled()) control.disable();
			else control.enable();
		},
		setAvatar(idOrEntry) {
			lsSet(config.keys.avatar, typeof idOrEntry === 'string' ? idOrEntry : idOrEntry?.id);
			if (instance) instance.setAvatar(idOrEntry);
		},
		openPicker() {
			instance?.openPicker();
		},

		/**
		 * Deliver a message in person.
		 *
		 * If the companion is already on screen it turns to the visitor, plays a
		 * gesture and says the line. If it is not (the visitor never turned it on,
		 * or closed it), it is summoned silently for this one message and walks
		 * off again afterwards, without flipping the persisted enabled flag, so
		 * "off" stays off once the message is delivered.
		 *
		 * @param {string} message the line to speak. Rendered as text, never HTML.
		 * @param {object} [opts]
		 * @param {number} [opts.hold=7000] ms the bubble stays up.
		 * @param {'neutral'|'alert'} [opts.tone='alert']
		 * @param {string} [opts.emote='wave'] gesture played on arrival; falls back
		 *   to a wave on rigs that don't carry it.
		 * @param {Array<{label:string, href?:string, onClick?:Function}>} [opts.actions]
		 * @param {string|object} [opts.avatar] deliver as somebody else: a roster
		 *   id, or an entry from `makeGuestAvatarEntry(glbUrl, { name })`. The
		 *   swap is not persisted and the visitor's own avatar comes back once
		 *   the message is over, which is what lets a message from a contact be
		 *   delivered by that contact's own body.
		 * @returns {Promise<boolean>} false when no avatar could be shown (route
		 *   excluded, no WebGL, inside an iframe) so the caller can fall back to
		 *   its own UI. True once the message is on screen.
		 */
		async announce(message, { hold = 7000, tone = 'alert', emote = 'wave', actions, avatar = null } = {}) {
			if (!message) return false;
			const summoned = !instance?.mounted;
			// Transient only when the visitor has not turned the companion on: an
			// enabled-but-unmounted companion (excluded route, playground) stays
			// mounted afterwards exactly as if it had mounted normally.
			const transient = summoned && !isEnabled();
			if (summoned) {
				if (!instance) instance = new WalkCompanion(config, control);
				await instance.mount({ greet: false });
				if (!instance.mounted) return false;
			}
			const inst = instance;

			// Guest delivery: whoever the message is from arrives in their own
			// body, and the visitor's companion is restored afterwards. A swap
			// that fails leaves the current avatar in place and the line is
			// still delivered, so a missing GLB never costs the message.
			let restore = null;
			if (avatar) {
				const guest = typeof avatar === 'string' ? resolveAvatarEntry(avatar, config) : avatar;
				const currentId = inst._currentEntry?.id || lsGet(config.keys.avatar) || config.defaultAvatarId;
				if (guest && guest.id !== currentId) {
					restore = inst._currentEntry || resolveAvatarEntry(currentId, config);
					await inst.setAvatar(guest, { persist: false, chatter: false });
				}
			}

			try {
				if (!inst.controller?.playEmote?.(emote)) inst.controller?.playWave?.();
			} catch {
				/* rig without emotes: the bubble still carries the message */
			}
			inst.say(message, { hold, tone, actions, priority: 1 });

			const settle = async () => {
				await new Promise((r) => setTimeout(r, hold + ANNOUNCE_RETREAT_MS));
				if (instance !== inst || !inst.mounted) return;
				if (restore) await inst.setAvatar(restore, { persist: false, chatter: false });
				// The visitor may have turned the companion on (or swapped
				// instances) while it was delivering; never yank it away then.
				if (transient && !isEnabled() && instance === inst && inst.mounted) inst.unmount();
			};
			// A persistent companion returns as soon as the line is up; only a
			// summoned-for-this-message one waits for its own retreat.
			if (!transient) {
				if (restore) settle();
				return true;
			}
			await settle();
			return true;
		},

		// Re-mount the corner companion when the playground exits.
		_wirePlaygroundReturn() {
			if (pgWired) return;
			pgWired = true;
			window.addEventListener('walk-playground:exit', () => {
				if (isEnabled()) {
					if (!instance) instance = new WalkCompanion(config, control);
					instance.mount();
				}
			});
		},

		async _detachToPlayground(companion) {
			control._wirePlaygroundReturn();
			let startScreen = null;
			try {
				const r = companion.host.getBoundingClientRect();
				startScreen = { x: r.left + r.width / 2, y: r.top + r.height * 0.86 };
			} catch {
				/* fall back to centered spawn */
			}
			const avatarId = companion._currentEntry?.id || lsGet(config.keys.avatar) || null;
			if (instance) instance.unmount(); // free the corner WebGL context first
			try {
				const mod = await import('./playground.js');
				mod.launchPlayground({ avatarId, startScreen, config });
			} catch (err) {
				log.warn('playground failed to load:', err?.message || err);
				if (isEnabled()) {
					if (!instance) instance = new WalkCompanion(config, control);
					instance.mount();
				}
			}
		},

		async _tryDropIn(avatarId = null) {
			try {
				const mod = await import('./playground.js');
				if (!mod.consumeDropIn(config)) return false;
				control._wirePlaygroundReturn();
				mod.launchPlayground({
					avatarId: avatarId || lsGet(config.keys.avatar) || null,
					dropIn: true,
					config,
				});
				return true;
			} catch (err) {
				log.warn('drop-in failed:', err?.message || err);
				return false;
			}
		},

		// Replicates the app's auto-mount + deep-link behaviour. Safe to call once
		// on load; reads ?walk= and the saved enabled flag.
		bootstrap() {
			if (typeof window === 'undefined') return;
			const params = new URLSearchParams(location.search);
			const walk = params.get('walk');
			if (walk === '0') {
				control.disable();
			} else if (walk === 'play') {
				const avatarId = deepLinkAvatarId(config, params);
				lsSet(config.keys.enabled, '1');
				import('./playground.js')
					.then((mod) => {
						control._wirePlaygroundReturn();
						mod.launchPlayground({ avatarId, config });
					})
					.catch((err) => {
						log.warn('playground deep-link failed:', err?.message || err);
						control.enable();
					});
			} else if (walk === '1' || isEnabled()) {
				control._tryDropIn(deepLinkAvatarId(config, params)).then((dropped) => {
					if (!dropped) control.enable();
				});
			}
		},
	};

	return control;
}