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.

49.0 KB
Raw Blame
// /walk-embed — chrome-less, iframe-safe walking avatar
//
// Duplicated from src/walk.js so embeds can evolve independently without
// destabilizing the canonical /walk page. Differences vs /walk:
//   • No multiplayer (WalkNet) — embeds don't connect strangers to a room.
//   • No AR camera passthrough — embed hosts can't grant getUserMedia.
//   • No HUD card, no help text, no online pill.
//   • Reads ?bg, ?controls, ?autoplay, ?env, ?ground, ?orbit query params.
//   • postMessage's `walk:ready` on load and `walk:position` each tick.
//
// If you find yourself fixing the same bug here and in walk.js, consider
// extracting a shared controller — but until then duplication keeps the
// blast radius small.

import {
	AmbientLight,
	Box3,
	CircleGeometry,
	Timer,
	Color,
	DirectionalLight,
	Fog,
	Group,
	HemisphereLight,
	Mesh,
	MeshStandardMaterial,
	PerspectiveCamera,
	Plane,
	AnimationMixer,
	Raycaster,
	Scene,
	ShadowMaterial,
	Vector2,
	Vector3,
	WebGLRenderer,
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import nipplejs from 'nipplejs';
import { getMeshoptDecoder } from './viewer/internal.js';

import { AnimationManager } from './animation-manager.js';
import { log } from './shared/log.js';
import { applyCinematicDefaults, detectQualityTier, loadEnvironment } from './shared/cinematic-render.js';
import {
	OUTBOUND,
	installEmbedBridge,
} from './walk-embed-events.js';

const AVATAR_URL_DEFAULT = '/avatars/default.glb';

// ── Embed params ─────────────────────────────────────────────────────────
const params = new URLSearchParams(location.search);
const BG_PARAM = params.get('bg'); // '' or 'transparent' or '#rrggbb'
const CONTROLS = (params.get('controls') || 'joystick').toLowerCase(); // 'joystick' | 'keyboard' | 'none'
const AUTOPLAY = params.get('autoplay') === 'true' || params.get('autoplay') === '1';
const SHOW_GROUND = params.get('ground') !== 'false';
const ORBIT_ENABLED = params.get('orbit') !== 'false';
const ENV_PARAM = (params.get('env') || 'studio').toLowerCase();
// Walk pace multiplier baked into the embed URL (?speed=0.5…2). Mirrors the
// runtime walk:config { speed } so a standalone iframe carries its own pace
// without a host round-trip. Clamped to the same band the host command uses.
const SPEED_PARAM = (() => {
	const n = Number(params.get('speed'));
	if (!Number.isFinite(n)) return 1.0;
	return Math.min(3, Math.max(0.3, n));
})();
// Camera pull-in. The chase camera frames the avatar from `height * 1.95` back
// by default, which reads well full-bleed but leaves a lot of empty sky when the
// embed is squeezed into a small 4:3 window (the /console handheld screen). A
// host passes ?zoom=0.5..2 to scale that distance and eye height; 1 is the
// untouched default, below 1 pulls in.
const ZOOM_PARAM = (() => {
	const n = Number(params.get('zoom'));
	if (!Number.isFinite(n)) return 1.0;
	return Math.min(2, Math.max(0.5, n));
})();
// Attribution badge ships by default — the embed is the distribution channel, so
// every dropped avatar links home. `?badge=false` removes it (paid/whitelabel).
const SHOW_BADGE = params.get('badge') !== 'false' && params.get('badge') !== '0';
// Opt-in floating wave/jump buttons so a plain iframe visitor can trigger the
// gestures the postMessage contract already exposes to hosts.
const SHOW_GESTURE_UI = params.get('gestures') === 'true' || params.get('gestures') === '1';
// Tap/click the ground to send the avatar there — on by default for interactive
// control modes, off for non-interactive (controls=none) embeds and ?click=false.
const CLICK_TO_MOVE = params.get('click') !== 'false' && CONTROLS !== 'none';
// Honor the viewer's OS "reduce motion" setting: skip the autoplay circle-walk
// (the avatar settles to idle) so an embed never animates against their wishes.
const PREFERS_REDUCED_MOTION =
	typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
// Idle cursor-glance only on hover-capable (desktop) pointers — on touch there's
// no persistent cursor to glance toward and it would jitter.
const HAS_HOVER = typeof matchMedia === 'function' && matchMedia('(hover: hover) and (pointer: fine)').matches;

// Live-tracked state surfaced to the host via the typed contract. `currentAvatarId`
// is the public identifier hosts gave us (?avatar=<id|url>, else the ?agent=<id>
// whose avatar we resolved) or 'default'; never a resolved internal R2/CDN URL
// with credentials. `currentEnv` and `isReady` back the walk:ready handshake +
// walk:ping replies.
const AGENT_PARAM = params.get('agent');
let currentAvatarId = params.get('avatar') || (AGENT_PARAM ? `agent:${AGENT_PARAM}` : 'default');
let currentEnv = ENV_PARAM;
let isReady = false;

// Real, self-contained scene presets. Each preset retints the clear color,
// fog, ground disc, and the hemisphere/sun lights — no external HDRIs to
// fetch, so the embed stays a single iframe with no extra requests. An
// explicit ?bg= always overrides the preset's background (see applyEnvironment).
const ENVIRONMENTS = {
	studio: { bg: null,     ground: 0x202833, hemiSky: 0xbcd6ff, hemiGround: 0x202830, hemiInt: 0.6,  sun: 0xffffff, sunInt: 1.4, fog: null },
	void:   { bg: 0x08090b, ground: 0x101218, hemiSky: 0x3a4250, hemiGround: 0x0a0c0f, hemiInt: 0.5,  sun: 0xcdd6ff, sunInt: 1.1, fog: null },
	beach:  { bg: 0x86c5ff, ground: 0xe2c98a, hemiSky: 0xcfeaff, hemiGround: 0xb89968, hemiInt: 0.9,  sun: 0xfff2d6, sunInt: 1.7, fog: [0x86c5ff, 16, 44] },
	sunset: { bg: 0xff9d6e, ground: 0x4a3340, hemiSky: 0xffc59e, hemiGround: 0x2a1f33, hemiInt: 0.8,  sun: 0xffcaa0, sunInt: 1.6, fog: [0xff9d6e, 14, 42] },
	night:  { bg: 0x0a1020, ground: 0x141a28, hemiSky: 0x2a3a66, hemiGround: 0x05070d, hemiInt: 0.45, sun: 0x9fb4ff, sunInt: 0.8, fog: [0x0a1020, 16, 46] },
	grid:   { bg: 0x0d0f12, ground: 0x1a1f2a, hemiSky: 0x4a5a80, hemiGround: 0x0d0f12, hemiInt: 0.7,  sun: 0xffffff, sunInt: 1.3, fog: null },
};

// Hosts we'll load a raw ?avatar=<url> from. Same-origin is always allowed (the
// iframe is served from three.ws); these extra hosts cover the R2/CDN buckets and
// model providers three.ws itself stores avatars on. A ?avatar= URL pointing
// anywhere else is rejected and we fall back to the default avatar, so a hostile
// host can't make the embed fetch arbitrary third-party origins on its behalf.
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;

// Validate a raw ?avatar= URL. Same-origin (absolute or path-relative) always
// passes; cross-origin must be an allow-listed host AND look like a model file.
// Returns the loadable URL or null if it should be rejected.
function validateAvatarUrl(raw) {
	if (raw.startsWith('/')) return raw; // same-origin path — always safe
	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;
	const hostOk = AVATAR_HOST_ALLOWLIST.some((re) => re.test(u.hostname));
	if (!hostOk) return null;
	if (!GLB_PATH_RE.test(u.pathname)) return null;
	return u.href;
}

// Resolve a ?agent=<id> to that agent's GLB URL via the real agent record. The
// /api/agents/:id endpoint returns avatar_model_url (custom GLB) and avatar_id;
// we prefer the explicit model URL, fall back to the same-origin avatar GLB proxy
// (which streams bytes with permissive CORS so the embed works on any host), and
// finally to the baked mannequin so an agent is never bodiless.
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;
}

// Resolve the avatar to load from the embed params. Precedence: explicit
// ?avatar= (raw URL or avatar id) wins; otherwise ?agent=<id> resolves to that
// agent's GLB; otherwise the default avatar. Any failure logs and falls back to
// the default so the embed always renders a walking body.
async function resolveAvatarUrl() {
	const id = params.get('avatar');
	if (id) {
		// A direct GLB/VRM URL or site path loads as-is (validated) — this is how
		// Forge/Scan hand a just-generated model into the embed editor
		// (?avatar=<glb url>), the same passthrough the /play worlds use
		// (src/game/avatar-rig.js).
		if (/^https?:\/\//i.test(id) || id.startsWith('/')) {
			const safe = validateAvatarUrl(id);
			if (safe) return safe;
			log.warn('[walk-embed] rejected ?avatar= URL (origin/host not allowed):', id);
			return AVATAR_URL_DEFAULT;
		}
		// Bare avatar id: go through the same-origin GLB proxy (api/avatars/[id]/glb)
		// instead of the metadata JSON. The proxy streams the bytes with
		// `Access-Control-Allow-Origin: *` so hosts on any origin can iframe this
		// page. Fetching the JSON first would just give us back the raw R2 URL,
		// which R2 only allows from the three.ws origin and breaks the moment the
		// embed is dropped onto a third-party site.
		return `/api/avatars/${encodeURIComponent(id)}/glb`;
	}
	if (AGENT_PARAM) {
		try {
			return await resolveAgentAvatarUrl(AGENT_PARAM);
		} catch (err) {
			log.warn('[walk-embed] agent avatar resolve failed, using default:', err?.message || err);
			return AVATAR_URL_DEFAULT;
		}
	}
	return AVATAR_URL_DEFAULT;
}

const ANIMATIONS_MANIFEST_URL = '/animations/manifest.json';
const CLIP_IDLE = 'idle';
const CLIP_WALK = 'av-walk-feminine';
const CLIP_RUN = 'av-walk-feminine'; // no separate run clip; timeScale handles pace difference
// One-shot gesture clips, driven by the `walk:gesture` host command. Mapped to
// real manifest clip names; playOnce settles back to idle when each finishes.
const GESTURE_CLIPS = { wave: 'wave', jump: 'av-superhero-jump' };
// Clip names the embed must have resident for locomotion + gestures.
const REQUIRED_CLIPS = new Set([CLIP_IDLE, CLIP_WALK, CLIP_RUN, ...Object.values(GESTURE_CLIPS)]);

const WALK_SPEED = 1.6;
const RUN_SPEED = 4.0;
const NATURAL_WALK_SPEED = 1.5;
const NATURAL_RUN_SPEED = 3.4;
const TURN_LERP = 0.18;
const CAM_LERP = 0.12;
const LEAN_WALK_RAD = 0.05;
const LEAN_RUN_RAD = 0.13;
const LEAN_LERP = 0.12;
const CAM_OFFSET = new Vector3(0, 1.85, 3.6);
const CAM_LOOK_OFFSET = new Vector3(0, 1.1, 0);
const GROUND_RADIUS = 12;
// Idle cursor-glance: max body turn toward the cursor (radians) and how quickly
// the avatar eases toward it — slow enough to read as "noticing," not twitchy.
const GLANCE_MAX_RAD = 0.42;
const GLANCE_LERP = 0.045;

// ── DOM ───────────────────────────────────────────────────────────────────
const stage = document.getElementById('walk-stage');
const canvas = document.getElementById('walk-canvas');
const joystickEl = document.getElementById('walk-joystick');
const statusEl = document.getElementById('walk-status');
const posterEl = document.getElementById('walk-poster');
const hintEl = document.getElementById('walk-hint');
const hintTextEl = document.getElementById('walk-hint-text');
const gesturesEl = document.getElementById('walk-gestures');
const badgeEl = document.getElementById('walk-badge');

stage.dataset.controls = CONTROLS;
stage.dataset.gestures = String(SHOW_GESTURE_UI);
if (!SHOW_BADGE && badgeEl) badgeEl.remove();
if (!SHOW_GESTURE_UI && gesturesEl) gesturesEl.remove();

// Apply background. Default is transparent so the host page shows through.
// `?bg=#101820` paints a solid color; `?bg=transparent` is explicit no-op.
if (BG_PARAM && BG_PARAM !== 'transparent') {
	document.body.style.background = BG_PARAM;
	stage.style.background = BG_PARAM;
}

function setStatus(text, { error = false, sticky = false } = {}) {
	if (!statusEl) return;
	statusEl.textContent = text;
	statusEl.classList.toggle('is-error', error);
	statusEl.classList.remove('is-hidden');
	if (!sticky) {
		clearTimeout(setStatus._t);
		setStatus._t = setTimeout(() => statusEl.classList.add('is-hidden'), 2200);
	}
}

// ── Loading poster ──────────────────────────────────────────────────────────
// Fades the silhouette out once the first avatar frame is ready, then removes it
// so it never intercepts pointer events or stays in the a11y tree.
function hidePoster() {
	if (!posterEl) return;
	posterEl.classList.add('is-hidden');
	setTimeout(() => posterEl.remove(), 500);
}

// ── Control hint ────────────────────────────────────────────────────────────
// A one-time discovery affordance: most visitors never realize an embedded
// avatar is interactive. We show a per-control-mode hint after load and dismiss
// it on the first real input (or after a timeout) so it never nags.
let hintDismissed = CONTROLS === 'none'; // non-interactive embeds get no hint
function maybeShowHint() {
	if (hintDismissed || !hintEl || !hintTextEl) return;
	const move = CONTROLS === 'joystick' ? 'Joystick or WASD to move' : 'WASD / arrows to move';
	const tap = CLICK_TO_MOVE ? ' · tap the ground to walk there' : '';
	hintTextEl.textContent = `${move} · drag to look${tap}`;
	hintEl.classList.add('is-visible');
	clearTimeout(maybeShowHint._t);
	maybeShowHint._t = setTimeout(dismissHint, 6000);
}
function dismissHint() {
	if (hintDismissed) return;
	hintDismissed = true;
	clearTimeout(maybeShowHint._t);
	if (hintEl) {
		hintEl.classList.remove('is-visible');
		setTimeout(() => hintEl.remove(), 400);
	}
}

// ── Outbound event bus → installEmbedBridge (src/walk-embed-events.js) ──────
// The runtime never touches postMessage itself. It fires typed lifecycle events
// on this tiny in-process bus; the embed bridge (installed from
// pages/walk-embed.html) subscribes via runtime.on() and is the single place
// that validates origins, shapes the envelope, and posts to window.parent. This
// keeps the wire contract in one module and guarantees no internal state leaks
// out by accident — only the fields the bridge forwards ever cross the boundary.
const _listeners = new Map();
function busOn(event, cb) {
	if (!_listeners.has(event)) _listeners.set(event, new Set());
	_listeners.get(event).add(cb);
	return () => _listeners.get(event)?.delete(cb);
}
function emit(type, payload = {}) {
	const set = _listeners.get(type);
	if (!set) return;
	for (const cb of set) {
		try { cb(payload); } catch {}
	}
}

// ── Renderer / scene ──────────────────────────────────────────────────────
const renderer = new WebGLRenderer({ canvas, antialias: true, alpha: true });
renderer.setSize(window.innerWidth, window.innerHeight, false);
const HAS_SOLID_BG = !!(BG_PARAM && BG_PARAM !== 'transparent');
// Paint the actual bg color (not opaque black) so ?bg=#101820 renders the
// requested color. Transparent embeds keep alpha 0 so the host shows through.
renderer.setClearColor(HAS_SOLID_BG ? new Color(BG_PARAM) : 0x000000, HAS_SOLID_BG ? 1 : 0);
// Filmic tone mapping + correct sRGB output + soft VSM shadows: the shared bar
// every viewer on the platform now matches (src/shared/cinematic-render.js).
const qualityTier = detectQualityTier();
applyCinematicDefaults(renderer, { tier: qualityTier });

const scene = new Scene();

// Real outdoor-sky HDRI IBL: walking scenes read better under an outdoor
// preset than the studio default. Falls back to a procedural environment on
// fetch failure or mobile tier.
loadEnvironment(renderer, scene, qualityTier === 'mobile' ? null : 'outdoor');

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.4);
sun.position.set(4, 8, 6);
sun.castShadow = true;
sun.shadow.mapSize.set(1024, 1024);
sun.shadow.camera.near = 0.5;
sun.shadow.camera.far = 30;
sun.shadow.camera.left = -8;
sun.shadow.camera.right = 8;
sun.shadow.camera.top = 8;
sun.shadow.camera.bottom = -8;
sun.shadow.bias = -0.0005;
scene.add(sun);

// Ground disc — visible by default; ?ground=false swaps it for a shadow
// catcher so the avatar floats on the host page's background.
const groundOpaque = new Mesh(
	new CircleGeometry(GROUND_RADIUS, 64),
	new MeshStandardMaterial({ color: 0x202833, roughness: 0.95, metalness: 0.0 }),
);
groundOpaque.rotation.x = -Math.PI / 2;
groundOpaque.receiveShadow = true;
groundOpaque.visible = SHOW_GROUND;
scene.add(groundOpaque);

const groundShadowCatcher = new Mesh(
	new CircleGeometry(GROUND_RADIUS, 64),
	new ShadowMaterial({ opacity: 0.32 }),
);
groundShadowCatcher.rotation.x = -Math.PI / 2;
groundShadowCatcher.receiveShadow = true;
groundShadowCatcher.visible = !SHOW_GROUND;
scene.add(groundShadowCatcher);

// Apply a scene preset. An explicit ?bg= wins over the preset background so
// transparent/custom embeds keep working; otherwise the preset paints the
// clear color and matching fog. Live-swappable via the `walk:setEnv` message.
function applyEnvironment(id) {
	const env = ENVIRONMENTS[id] || ENVIRONMENTS.studio;
	if (BG_PARAM && BG_PARAM !== 'transparent') {
		renderer.setClearColor(new Color(BG_PARAM), 1);
	} else if (env.bg == null) {
		renderer.setClearColor(0x000000, 0); // transparent — host page shows through
	} else {
		renderer.setClearColor(new Color(env.bg), 1);
		document.body.style.background = `#${env.bg.toString(16).padStart(6, '0')}`;
	}
	scene.fog = env.fog ? new Fog(env.fog[0], env.fog[1], env.fog[2]) : null;
	groundOpaque.material.color.setHex(env.ground);
	hemi.color.setHex(env.hemiSky);
	hemi.groundColor.setHex(env.hemiGround);
	hemi.intensity = env.hemiInt;
	sun.color.setHex(env.sun);
	sun.intensity = env.sunInt;
}
applyEnvironment(ENV_PARAM);

const camera = new PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.05, 200);
const avatarRig = new Group();
scene.add(avatarRig);

const camDesired = new Vector3();
const camLookTarget = new Vector3();
const camLookCurrent = new Vector3();

let cameraYaw = 0;
let cameraPitch = 0.05;
const PITCH_MIN = -0.6;
const PITCH_MAX = 0.7;

function applyCameraImmediate() {
	const offset = CAM_OFFSET.clone();
	offset.applyAxisAngle(new Vector3(1, 0, 0), -cameraPitch);
	offset.applyAxisAngle(new Vector3(0, 1, 0), cameraYaw);
	camDesired.copy(avatarRig.position).add(offset);
	camera.position.copy(camDesired);
	camLookTarget.copy(avatarRig.position).add(CAM_LOOK_OFFSET);
	camLookCurrent.copy(camLookTarget);
	camera.lookAt(camLookCurrent);
}
applyCameraImmediate();

// ── Drag-to-orbit ─────────────────────────────────────────────────────────
// Skipped entirely when ?orbit=false (e.g. the SDK uses it for autoplay-only
// floating avatars where stray pointer drags would just look broken).
if (ORBIT_ENABLED) {
	let dragging = false;
	let lastX = 0, lastY = 0;
	let downId = -1;

	canvas.addEventListener('pointerdown', (e) => {
		const jRect = joystickEl.getBoundingClientRect();
		const overJoystick = CONTROLS === 'joystick' && (
			e.clientX >= jRect.left && e.clientX <= jRect.right &&
			e.clientY >= jRect.top  && e.clientY <= jRect.bottom
		);
		if (overJoystick) return;

		dragging = true;
		downId = e.pointerId;
		lastX = e.clientX;
		lastY = e.clientY;
		canvas.setPointerCapture?.(e.pointerId);
	});
	const onMove = (e) => {
		if (!dragging || e.pointerId !== downId) return;
		const dx = e.clientX - lastX;
		const dy = e.clientY - lastY;
		lastX = e.clientX;
		lastY = e.clientY;
		cameraYaw -= dx * 0.005;
		cameraPitch = Math.max(PITCH_MIN, Math.min(PITCH_MAX, cameraPitch - dy * 0.0035));
	};
	const onUp = (e) => {
		if (e.pointerId !== downId) return;
		dragging = false;
		downId = -1;
		try { canvas.releasePointerCapture?.(e.pointerId); } catch {}
	};
	canvas.addEventListener('pointermove', onMove);
	canvas.addEventListener('pointerup', onUp);
	canvas.addEventListener('pointercancel', onUp);
}

// ── Idle cursor-glance ──────────────────────────────────────────────────────
// On hover-capable devices, track the cursor's horizontal position over the
// canvas and feed it to the idle-glance target so a standing avatar turns toward
// the visitor. Skipped under reduced-motion and on touch (no persistent cursor).
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; // [-1, 1]
		input.glance.targetYaw = -ndcX * GLANCE_MAX_RAD;
		input.glance.active = true;
	});
	canvas.addEventListener('pointerleave', () => { input.glance.active = false; });
}

// ── Input state ───────────────────────────────────────────────────────────
const input = {
	keys: { forward: 0, back: 0, left: 0, right: 0, run: false },
	joy: { x: 0, y: 0, active: false },
	autoplay: { active: false, t: 0 },
	// Programmatic vector, set by the `walk:move` host command (analog form).
	// Persists until the host sends move {x:0,y:0} or any live input overrides it.
	cmd: { x: 0, y: 0, run: false, active: false },
	// Scripted discrete move ({ dir, meters }) — walks a fixed distance then stops.
	// `remaining` counts down in metres each frame; `vx/vy` is the unit heading.
	scripted: { remaining: 0, vx: 0, vy: 0, run: false },
	// Seek target from `walk:goto` — drive toward a world (x,z) then stop within
	// GOTO_ARRIVE_EPSILON. Cleared by any live input or a new command.
	seek: { active: false, x: 0, z: 0, run: false },
	// Idle cursor-glance: the avatar gently turns its body toward the pointer when
	// standing still, so a hovered embed feels like it noticed you. `targetYaw` is
	// the desired heading (radians) derived from the cursor's horizontal position;
	// `active` is true only while the pointer is over the canvas on a hover device.
	glance: { active: false, targetYaw: 0 },
	_speedMultiplier: SPEED_PARAM,
};

const GOTO_ARRIVE_EPSILON = 0.18; // metres — close enough to "arrived"

// Map a discrete direction to a camera-relative input vector. forward/back use
// the y axis (joystick up = forward), left/right the x axis — same convention
// readMoveInput already resolves against the camera heading.
const DIR_VECTORS = {
	forward: { vx: 0, vy: 1 },
	back: { vx: 0, vy: -1 },
	left: { vx: -1, vy: 0 },
	right: { vx: 1, vy: 0 },
};

if (CONTROLS === 'keyboard' || CONTROLS === 'joystick') {
	window.addEventListener('keydown', (e) => {
		switch (e.code) {
			case 'KeyW': case 'ArrowUp':    input.keys.forward = 1; break;
			case 'KeyS': case 'ArrowDown':  input.keys.back = 1; break;
			case 'KeyA': case 'ArrowLeft':  input.keys.left = 1; break;
			case 'KeyD': case 'ArrowRight': input.keys.right = 1; break;
			case 'ShiftLeft': case 'ShiftRight': input.keys.run = true; break;
			default: return;
		}
		dismissHint();
	});
	window.addEventListener('keyup', (e) => {
		switch (e.code) {
			case 'KeyW': case 'ArrowUp':    input.keys.forward = 0; break;
			case 'KeyS': case 'ArrowDown':  input.keys.back = 0; break;
			case 'KeyA': case 'ArrowLeft':  input.keys.left = 0; break;
			case 'KeyD': case 'ArrowRight': input.keys.right = 0; break;
			case 'ShiftLeft': case 'ShiftRight': input.keys.run = false; break;
		}
	});
}

if (CONTROLS === 'joystick') {
	const joystick = nipplejs.create({
		zone: joystickEl,
		mode: 'static',
		position: { left: '50%', top: '50%' },
		size: 110,
		color: 'rgba(255,255,255,0.85)',
		restOpacity: 0.6,
	});
	joystick.on('move', (evt) => {
		// nipplejs v1 passes a single { type, target, data } event object.
		const data = evt?.data;
		if (data?.vector) {
			// data.vector is the proportional stick displacement, already in
			// [-1, 1] per axis (magnitude ≤ 1); y positive = pushed up = forward.
			input.joy.x = data.vector.x;
			input.joy.y = data.vector.y;
			input.joy.active = Math.hypot(data.vector.x, data.vector.y) > 0.05;
			if (input.joy.active) dismissHint();
		}
	});
	joystick.on('end', () => {
		input.joy.x = 0;
		input.joy.y = 0;
		input.joy.active = false;
	});
}

// ── Avatar loading + animations ──────────────────────────────────────────
const animationManager = new AnimationManager();
let avatar = null;
let avatarYaw = 0;
let avatarLean = 0;
let currentMotion = 'idle';

// The default avatar (and most three.ws avatars) ship with
// EXT_meshopt_compression, so the loader must have the meshopt decoder wired
// before it can parse a single bufferView — otherwise GLTFLoader throws
// "setMeshoptDecoder must be called before loading compressed files". Build the
// loader once and share it across the initial load and live avatar swaps.
let _loaderPromise = null;
function getAvatarLoader() {
	if (!_loaderPromise) {
		_loaderPromise = getMeshoptDecoder().then((decoder) => {
			const loader = new GLTFLoader();
			loader.setMeshoptDecoder(decoder);
			return loader;
		});
	}
	return _loaderPromise;
}

async function loadAvatar() {
	setStatus('loading avatar…', { sticky: true });

	const requestedUrl = await resolveAvatarUrl();
	const loader = await getAvatarLoader();

	// Honor the contract that the embed ALWAYS renders a walking body: if the
	// requested avatar can't be fetched (deleted/expired id, a private avatar an
	// anonymous host can't read, a typo'd id → 404, or a transient network
	// failure) we fall back to the default avatar instead of leaving the host
	// with an empty, all-black stage. The failure is still reported to the host
	// over the typed bridge, and a legible status tells the viewer what happened.
	let gltf;
	let usedFallback = false;
	try {
		gltf = await loader.loadAsync(requestedUrl);
	} catch (err) {
		if (requestedUrl === AVATAR_URL_DEFAULT) throw err; // default itself failed — let boot's catch surface it
		log.warn('[walk-embed] avatar load failed, falling back to default:', err?.message || err);
		emit(OUTBOUND.ERROR, {
			code: 'avatar_load_failed',
			message: String(err?.message || err),
			fallback: true,
		});
		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);
	const minY = box.min.y;
	avatar.position.y -= minY;

	avatarRig.add(avatar);

	const height = Math.max(0.5, box.max.y - box.min.y);
	CAM_OFFSET.set(0, height * 1.05 * ZOOM_PARAM, height * 1.95 * ZOOM_PARAM);
	CAM_LOOK_OFFSET.set(0, height * 0.6, 0);
	applyCameraImmediate();

	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) || !needed.some((d) => d.name === CLIP_WALK)) {
		throw new Error('Animation manifest missing idle/walking clips');
	}
	animationManager.setAnimationDefs(needed);
	await animationManager.loadAll();

	await animationManager.crossfadeTo(CLIP_IDLE, 0.0);
	currentMotion = 'idle';

	if (AUTOPLAY && !PREFERS_REDUCED_MOTION) {
		input.autoplay.active = true;
		input.autoplay.t = 0;
	}

	if (usedFallback) {
		setStatus("couldn't load that avatar — showing the default", { sticky: true });
	} else {
		setStatus('walk it');
	}
	hidePoster();
	maybeShowHint();
	isReady = true;
	emit(OUTBOUND.READY, { avatarId: currentAvatarId, env: currentEnv, fallback: usedFallback });
}

// ── Resize ────────────────────────────────────────────────────────────────
function resize() {
	const w = window.innerWidth;
	const h = window.innerHeight;
	renderer.setSize(w, h, false);
	camera.aspect = w / h;
	camera.updateProjectionMatrix();
}
window.addEventListener('resize', resize);
window.addEventListener('orientationchange', resize);

// ── Main loop ─────────────────────────────────────────────────────────────
const clock = new Timer();
const moveWorld = new Vector3();
const moveForward = new Vector3();
const moveRight = new Vector3();
const upY = new Vector3(0, 1, 0);

// A human grabbing the controls (or a fresh command) cancels every form of
// programmatic drive so they never fight for the avatar.
function cancelProgrammatic() {
	input.scripted.remaining = 0;
	input.cmd.active = false;
	input.seek.active = false;
}

function readMoveInput(dt) {
	// Live input always wins and cancels any programmatic drive so a human can
	// grab control mid-script.
	if (input.joy.active) { cancelProgrammatic(); return { ix: input.joy.x, iy: input.joy.y, run: false }; }
	if (CONTROLS !== 'none') {
		const ix = input.keys.right - input.keys.left;
		const iy = input.keys.forward - input.keys.back;
		if (ix || iy) { cancelProgrammatic(); return { ix, iy, run: input.keys.run }; }
	}
	// Seek to a world (x,z) from walk:goto. Steer in world space, then express
	// the world heading in the camera-relative basis the loop consumes so the
	// avatar walks straight to the point regardless of camera orbit.
	if (input.seek.active && avatar) {
		const dx = input.seek.x - avatarRig.position.x;
		const dz = input.seek.z - avatarRig.position.z;
		const dist = Math.hypot(dx, dz);
		if (dist <= GOTO_ARRIVE_EPSILON) {
			input.seek.active = false;
			return { ix: 0, iy: 0 };
		}
		moveForward.copy(camLookCurrent).sub(camera.position);
		moveForward.y = 0;
		if (moveForward.lengthSq() < 1e-6) moveForward.set(0, 0, -1);
		else moveForward.normalize();
		moveRight.crossVectors(moveForward, upY).normalize();
		const ndx = dx / dist, ndz = dz / dist;
		// Decompose the world unit heading onto the camera basis: iy along
		// forward, ix along right.
		const iy = moveForward.x * ndx + moveForward.z * ndz;
		const ix = moveRight.x * ndx + moveRight.z * ndz;
		// Ease the final stretch so we settle instead of overshooting.
		const gain = Math.min(1, dist / 0.6);
		return { ix: ix * gain, iy: iy * gain, run: input.seek.run };
	}
	// Scripted discrete move: walk a fixed distance then stop. Decrement by the
	// per-frame distance the loop will actually travel (speed × dt) so `meters`
	// maps to real world distance regardless of frame rate.
	if (input.scripted.remaining > 0) {
		const pace = (input.scripted.run ? RUN_SPEED : WALK_SPEED) * (input._speedMultiplier || 1.0);
		input.scripted.remaining = Math.max(0, input.scripted.remaining - pace * dt);
		return { ix: input.scripted.vx, iy: input.scripted.vy, run: input.scripted.run };
	}
	// Held analog vector from `walk:move`.
	if (input.cmd.active) return { ix: input.cmd.x, iy: input.cmd.y, run: input.cmd.run };
	if (input.autoplay.active) {
		// Lazy "walk in a slow circle" pattern — readable, non-distracting,
		// and keeps the avatar within the visible ground disc no matter how
		// long the page sits idle. Period ~16s, radius ramps in over 1s so
		// the avatar starts from rest instead of snapping into motion.
		input.autoplay.t += dt;
		const ramp = Math.min(1, input.autoplay.t / 1.0);
		const angle = input.autoplay.t * (Math.PI * 2 / 16);
		return { ix: Math.cos(angle) * 0.6 * ramp, iy: Math.sin(angle) * 0.6 * ramp };
	}
	return { ix: 0, iy: 0 };
}

let lastBroadcastX = 0;
let lastBroadcastZ = 0;
let lastBroadcastAt = 0;
const BROADCAST_EPSILON = 0.02; // metres — skip duplicate post messages
const BROADCAST_INTERVAL_MS = 100; // walk:position fires at ≤10 Hz per the contract

function round3(n) {
	return Math.round(n * 1000) / 1000;
}

function tick() {
	clock.update();
	const dt = Math.min(clock.getDelta(), 0.05);

	const { ix, iy } = readMoveInput(dt);
	const mag = Math.min(1, Math.hypot(ix, iy));

	const wantRun = mag > 0.9 || input.keys.run;
	const speed = mag * (wantRun ? RUN_SPEED : WALK_SPEED) * (input._speedMultiplier || 1.0);

	if (mag > 0.01 && avatar) {
		moveForward.copy(camLookCurrent).sub(camera.position);
		moveForward.y = 0;
		if (moveForward.lengthSq() < 1e-6) moveForward.set(0, 0, -1);
		else moveForward.normalize();
		moveRight.crossVectors(moveForward, upY).normalize();

		moveWorld.set(0, 0, 0)
			.addScaledVector(moveForward, iy / Math.max(mag, 1e-6))
			.addScaledVector(moveRight, ix / Math.max(mag, 1e-6))
			.normalize()
			.multiplyScalar(speed * dt);

		avatarRig.position.add(moveWorld);

		const r = Math.hypot(avatarRig.position.x, avatarRig.position.z);
		const max = GROUND_RADIUS - 0.5;
		if (r > max) {
			const k = max / r;
			avatarRig.position.x *= k;
			avatarRig.position.z *= k;
		}

		const wantYaw = Math.atan2(moveWorld.x, moveWorld.z);
		avatarYaw = lerpAngle(avatarYaw, wantYaw, TURN_LERP);
		avatarRig.quaternion.setFromAxisAngle(upY, avatarYaw);

		const want = wantRun ? 'run' : 'walk';
		if (currentMotion !== want) {
			currentMotion = want;
			animationManager.crossfadeTo(want === 'run' ? CLIP_RUN : CLIP_WALK, 0.18);
		}
	} else if (currentMotion !== 'idle' && avatar) {
		currentMotion = 'idle';
		animationManager.crossfadeTo(CLIP_IDLE, 0.25);
	}

	// Idle cursor-glance: while standing still, ease the body toward facing the
	// viewer (yaw 0), offset toward the cursor when it's over the canvas. Only the
	// idle state touches yaw here — locomotion above owns it while moving.
	if (mag <= 0.01 && avatar && HAS_HOVER && !PREFERS_REDUCED_MOTION) {
		const targetYaw = input.glance.active ? input.glance.targetYaw : 0;
		avatarYaw = lerpAngle(avatarYaw, targetYaw, GLANCE_LERP);
		avatarRig.quaternion.setFromAxisAngle(upY, avatarYaw);
	}

	if (animationManager.mixer) {
		let ts = 1.0;
		if (currentMotion === 'walk') {
			ts = Math.max(0.45, speed / NATURAL_WALK_SPEED);
		} else if (currentMotion === 'run') {
			ts = Math.max(0.6, speed / NATURAL_RUN_SPEED);
		}
		animationManager.mixer.timeScale = ts;
	}

	const targetLean = currentMotion === 'run'
		? LEAN_RUN_RAD * mag
		: currentMotion === 'walk'
			? LEAN_WALK_RAD * mag
			: 0;
	avatarLean += (targetLean - avatarLean) * LEAN_LERP;
	if (avatar) avatar.rotation.x = avatarLean;

	const offset = CAM_OFFSET.clone();
	offset.applyAxisAngle(new Vector3(1, 0, 0), -cameraPitch);
	offset.applyAxisAngle(upY, cameraYaw);
	camDesired.copy(avatarRig.position).add(offset);
	camera.position.lerp(camDesired, CAM_LERP);

	camLookTarget.copy(avatarRig.position).add(CAM_LOOK_OFFSET);
	camLookCurrent.lerp(camLookTarget, CAM_LERP);
	camera.lookAt(camLookCurrent);

	animationManager.update(dt);

	const now = performance.now();
	if (
		avatar &&
		now - lastBroadcastAt >= BROADCAST_INTERVAL_MS && (
			Math.abs(avatarRig.position.x - lastBroadcastX) > BROADCAST_EPSILON ||
			Math.abs(avatarRig.position.z - lastBroadcastZ) > BROADCAST_EPSILON
		)
	) {
		lastBroadcastAt = now;
		lastBroadcastX = avatarRig.position.x;
		lastBroadcastZ = avatarRig.position.z;
		emit(OUTBOUND.POSITION, {
			x: round3(avatarRig.position.x),
			z: round3(avatarRig.position.z),
			heading: round3(avatarYaw),
		});
	}

	renderer.render(scene, camera);
	if (loopRunning) rafHandle = requestAnimationFrame(tick);
}

function lerpAngle(a, b, t) {
	let diff = ((b - a + Math.PI) % (Math.PI * 2)) - Math.PI;
	if (diff < -Math.PI) diff += Math.PI * 2;
	return a + diff * t;
}

// ── Imperative runtime handle (consumed by installEmbedBridge) ─────────────
// Every method receives values the bridge has already validated, clamped, and
// bounded against the walk-embed-events contract — so the runtime trusts them
// and just applies them to the real avatar/controls. The bridge is the only
// thing that talks postMessage; the runtime only knows about its scene.
const runtime = {
	on: busOn,
	getReady() {
		return isReady ? { avatarId: currentAvatarId, env: currentEnv } : null;
	},
	// Walk to a world (x, z) then stop. Steered each frame in readMoveInput.
	goto(x, z) {
		cancelProgrammatic();
		const dist = Math.hypot(x - avatarRig.position.x, z - avatarRig.position.z);
		input.seek.active = true;
		input.seek.x = x;
		input.seek.z = z;
		input.seek.run = dist > 4; // jog to far targets, walk to near ones
		input.autoplay.active = false;
	},
	// Held analog vector / discrete nudge from walk:move.
	move(payload) {
		cancelProgrammatic();
		input.autoplay.active = false;
		if (typeof payload.dir === 'string') {
			const v = DIR_VECTORS[payload.dir];
			if (!v) return;
			input.scripted.vx = v.vx;
			input.scripted.vy = v.vy;
			input.scripted.run = false;
			input.scripted.remaining = payload.meters;
		} else {
			input.cmd.x = payload.x;
			input.cmd.y = payload.y;
			input.cmd.run = !!payload.run;
			input.cmd.active = Math.hypot(payload.x, payload.y) > 0.01;
		}
	},
	// One-shot gestures (wave/jump) play over locomotion then settle to idle.
	// Locomotion gestures (idle/walk/run) drive the autoplay loop the same way
	// the legacy walk:setMotion command did.
	gesture(g) {
		if (g === 'wave' || g === 'jump') {
			const clip = GESTURE_CLIPS[g];
			if (clip && animationManager.supportsCanonicalClips?.() !== false) {
				animationManager.playOnce(clip, { settleTo: CLIP_IDLE, fade: 0.18 });
			}
			emit(OUTBOUND.GESTURE, { gesture: g });
			return;
		}
		if (g === 'walk' || g === 'run') {
			input.autoplay.active = true;
			input.autoplay.t = 0;
		} else if (g === 'idle') {
			input.autoplay.active = false;
			input.cmd.active = false;
			input.seek.active = false;
			input.scripted.remaining = 0;
		}
		emit(OUTBOUND.GESTURE, { gesture: g });
	},
	// Show a speech bubble; `voice` is forwarded to the host echo as a hint (the
	// embed renders text, the host owns any TTS). durationMs sets the auto-hide.
	say(text, voice, durationMs) {
		const ms = showSpeechBubble(text, durationMs);
		emit(OUTBOUND.SPEAK, { text, voice, durationMs: ms });
	},
	setEnv(env) {
		applyEnvironment(env);
		currentEnv = env;
		emit(OUTBOUND.ENVIRONMENT, { env });
	},
	async setAvatar(avatarId) {
		try {
			const url = /^https?:\/\//i.test(avatarId) || avatarId.startsWith('/')
				? avatarId
				: `/api/avatars/${encodeURIComponent(avatarId)}/glb`;
			const loader = await getAvatarLoader();
			const gltf = await loader.loadAsync(url);
			if (avatar) avatarRig.remove(avatar);
			avatar = gltf.scene;
			avatar.traverse((n) => {
				if (n.isMesh) {
					n.castShadow = true;
					if (n.material && 'envMapIntensity' in n.material) n.material.envMapIntensity = 0.85;
				}
			});
			const box = new Box3().setFromObject(avatar);
			avatar.position.y -= box.min.y;
			avatarRig.add(avatar);
			const height = Math.max(0.5, box.max.y - box.min.y);
			CAM_OFFSET.set(0, height * 1.05 * ZOOM_PARAM, height * 1.95 * ZOOM_PARAM);
			CAM_LOOK_OFFSET.set(0, height * 0.6, 0);
			applyCameraImmediate();
			animationManager.attach(avatar);
			await animationManager.crossfadeTo(CLIP_IDLE, 0.0);
			currentMotion = 'idle';
			currentAvatarId = avatarId;
			emit(OUTBOUND.AVATAR_CHANGED, { avatarId });
		} catch (err) {
			emit(OUTBOUND.ERROR, { code: 'avatar_load_failed', message: String(err?.message || err) });
		}
	},
	config({ speed, bg, controls } = {}) {
		if (typeof speed === 'number') input._speedMultiplier = speed;
		if (typeof bg === 'string') applyBackground(bg);
		if (typeof controls === 'string') applyControls(controls);
	},
	reset() {
		cancelProgrammatic();
		input.autoplay.active = false;
		avatarRig.position.set(0, 0, 0);
		avatarYaw = 0;
		avatarRig.quaternion.setFromAxisAngle(upY, 0);
		hideSpeechBubble();
		applyCameraImmediate();
	},
};

// Expose the handle so installEmbedBridge (and integration tests) can drive the
// runtime without importing it. Public methods only — no scene internals.
window.__walkEmbed = runtime;

// ── Click / tap to walk ─────────────────────────────────────────────────────
// Raycast a tap on the canvas onto the ground plane (y=0) and send the avatar
// there via the same goto seek the host postMessage contract uses. This makes
// the most intuitive control discoverable to a visitor who'd never read docs.
// A tap is distinguished from an orbit drag (movement threshold) and a hold.
const _raycaster = new Raycaster();
const _groundPlane = new Plane(new Vector3(0, 1, 0), 0);
const _ndc = new Vector2();
const _hit = new Vector3();

function groundPointAt(clientX, clientY) {
	const rect = canvas.getBoundingClientRect();
	if (!rect.width || !rect.height) return null;
	_ndc.x = ((clientX - rect.left) / rect.width) * 2 - 1;
	_ndc.y = -((clientY - rect.top) / rect.height) * 2 + 1;
	_raycaster.setFromCamera(_ndc, camera);
	return _raycaster.ray.intersectPlane(_groundPlane, _hit);
}

if (CLICK_TO_MOVE) {
	let downX = 0, downY = 0, downT = 0, tracking = false;
	canvas.addEventListener('pointerdown', (e) => {
		// A tap starting over the joystick belongs to the joystick, not a goto.
		const jr = joystickEl.getBoundingClientRect();
		const overJoystick = CONTROLS === 'joystick' &&
			e.clientX >= jr.left && e.clientX <= jr.right &&
			e.clientY >= jr.top && e.clientY <= jr.bottom;
		if (overJoystick) { tracking = false; return; }
		downX = e.clientX; downY = e.clientY; downT = performance.now(); tracking = true;
	});
	canvas.addEventListener('pointerup', (e) => {
		if (!tracking) return;
		tracking = false;
		// A drag (orbit) or a hold isn't a click-to-walk.
		if (Math.hypot(e.clientX - downX, e.clientY - downY) > 6) return;
		if (performance.now() - downT > 400) return;
		const p = groundPointAt(e.clientX, e.clientY);
		if (!p) return;
		// Keep the target inside the walkable disc so the avatar never seeks a
		// point it would be clamped away from anyway.
		const r = Math.hypot(p.x, p.z);
		const max = GROUND_RADIUS - 0.5;
		let x = p.x, z = p.z;
		if (r > max) { const k = max / r; x *= k; z *= k; }
		runtime.goto(x, z);
		dismissHint();
	});
}

// ── Gesture buttons (opt-in) ────────────────────────────────────────────────
// Wire the floating wave/jump buttons (rendered only when ?gestures=true) to the
// same gesture path the host contract drives.
if (SHOW_GESTURE_UI && gesturesEl) {
	gesturesEl.querySelectorAll('.walk-gesture-btn').forEach((btn) => {
		btn.addEventListener('click', () => {
			const g = btn.dataset.gesture;
			if (g) { runtime.gesture(g); dismissHint(); }
		});
	});
}

// Apply a runtime background override (walk:config { bg }). 'transparent' lets
// the host page show through; a hex/rgb paints a solid clear color.
function applyBackground(bg) {
	if (!bg || bg === 'transparent') {
		renderer.setClearColor(0x000000, 0);
		document.body.style.background = 'transparent';
		stage.style.background = 'transparent';
		return;
	}
	try {
		renderer.setClearColor(new Color(bg), 1);
		document.body.style.background = bg;
		stage.style.background = bg;
	} catch {}
}

// Swap control scheme at runtime (walk:config { controls }). Only toggles the
// joystick visibility + clears live key/joy state; keyboard listeners stay
// installed and simply go unused when controls are 'none'.
function applyControls(mode) {
	stage.dataset.controls = mode;
	if (mode === 'none') {
		input.keys.forward = input.keys.back = input.keys.left = input.keys.right = 0;
		input.keys.run = false;
		input.joy.x = input.joy.y = 0;
		input.joy.active = false;
	}
}

// Install the postMessage bridge — origin allow-list and target origin come
// from the embed URL so a security-conscious host can pin them.
installEmbedBridge(runtime, {
	allowedOrigins: params.get('allowOrigins')?.split(',').map((s) => s.trim()).filter(Boolean) || '*',
	targetOrigin: params.get('targetOrigin') || '*',
});

// ── Speech bubble (DOM overlay) ───────────────────────────────────────────
// Shows the narration text above the avatar. The text lives in a dedicated
// inner element clamped to 3 lines (-webkit-line-clamp) so long sections wrap
// and truncate cleanly; the pointer triangle is a separate sibling so it never
// participates in the clamp. Authoritative hide is walk:narrateEnd (audio
// ended); the timer is only a fallback if that message is ever lost.
let bubbleEl = null;
let bubbleTextEl = null;
let bubbleHideTimer = null;

function ensureBubble() {
	if (bubbleEl) return bubbleEl;
	bubbleEl = document.createElement('div');
	bubbleEl.setAttribute('role', 'status');
	bubbleEl.setAttribute('aria-live', 'polite');
	bubbleEl.style.cssText = `
		position: fixed;
		left: 50%;
		bottom: 180px;
		transform: translateX(-50%);
		max-width: 280px;
		background: rgba(10,10,10,0.88);
		color: #fafafa;
		font-family: Inter, system-ui, sans-serif;
		font-size: 13px;
		line-height: 1.45;
		padding: 10px 14px;
		border-radius: 14px;
		border: 1px solid rgba(255,255,255,0.12);
		backdrop-filter: blur(12px);
		-webkit-backdrop-filter: blur(12px);
		pointer-events: none;
		z-index: 10;
		opacity: 0;
		transition: opacity 0.25s ease;
	`;

	bubbleTextEl = document.createElement('div');
	bubbleTextEl.style.cssText = `
		display: -webkit-box;
		-webkit-box-orient: vertical;
		-webkit-line-clamp: 3;
		line-clamp: 3;
		overflow: hidden;
		word-break: break-word;
	`;
	bubbleEl.appendChild(bubbleTextEl);

	// Pointer triangle — sibling of the clamped text so it's never counted.
	const tri = document.createElement('div');
	tri.style.cssText = `
		position: absolute;
		bottom: -7px;
		left: 50%;
		transform: translateX(-50%);
		width: 0;
		height: 0;
		border-left: 7px solid transparent;
		border-right: 7px solid transparent;
		border-top: 7px solid rgba(10,10,10,0.88);
	`;
	bubbleEl.appendChild(tri);
	document.body.appendChild(bubbleEl);
	return bubbleEl;
}

// Returns the resolved visible duration (ms) so the host's walk:speak echo can
// report exactly how long the bubble will stay up.
function showSpeechBubble(text, durationMs) {
	clearTimeout(bubbleHideTimer);
	ensureBubble();
	bubbleTextEl.textContent = text.slice(0, 280);
	bubbleEl.style.opacity = '1';
	// Explicit durationMs wins; otherwise estimate from reading time.
	const ms = durationMs && durationMs > 0 ? durationMs : Math.max(2500, text.length * 55);
	bubbleHideTimer = setTimeout(hideSpeechBubble, ms);
	return ms;
}

function hideSpeechBubble() {
	if (bubbleEl) bubbleEl.style.opacity = '0';
}

// ── Render-loop visibility gating ───────────────────────────────────────────
// Stop the rAF loop (and all WebGL work) whenever the embed is scrolled off the
// host viewport or its tab is hidden, then resume seamlessly when it returns —
// the per-frame dt cap (Math.min(getDelta(), 0.05)) absorbs the paused gap so
// the avatar never teleports. Without this an embed on a long page keeps burning
// GPU/battery while completely invisible.
let loopRunning = false;
let rafHandle = 0;
let canRender = false; // true once boot has a scene worth drawing
let onScreen = true;

function startLoop() {
	if (loopRunning || !canRender) return;
	loopRunning = true;
	clock.update(); // reset the delta baseline so the first frame's dt is small
	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(stage);
}

// ── Boot ──────────────────────────────────────────────────────────────────
loadAvatar()
	.then(() => {
		canRender = true;
		syncLoop();
	})
	.catch((err) => {
		log.error('[walk-embed] failed to load avatar:', err);
		if (statusEl) {
			statusEl.textContent = `failed to load avatar: ${err?.message ?? err}`;
			statusEl.classList.add('is-error');
			statusEl.classList.remove('is-hidden');
		}
		hidePoster();
		emit(OUTBOUND.ERROR, { code: 'avatar_load_failed', message: String(err?.message || err) });
		canRender = true;
		syncLoop();
	});