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.

26.4 KB
Raw Blame
// Agora citizens — the living population of the Commons.
//
// Each citizen from /api/agora/citizens is rendered as an avatar standing in the
// City square: its real `avatarUrl` GLB, canonicalized + retargeted so the shared
// idle clip drives any rig, with a billboarded name + profession label above its
// head. This module owns the *crowd*: loading, pooling, the per-frame loop, and
// hit-testing. Selection state, the passport panel, and accessibility chrome live
// in src/agora/agora-world.js.
//
// Performance is the whole game (the DoD asks for 50 citizens at 60fps):
//   • Each unique avatar GLB is loaded ONCE and its idle/walk clips retargeted
//     ONCE (via AnimationManager). Every citizen wearing that GLB is a cheap
//     SkeletonUtils clone driven by a bare AnimationMixer reusing those bound
//     clips — N mixers, not N retargets. (Same proven pattern as src/club-crowd.js.)
//   • Clip JSON is fetched once and shared across every template.
//   • Concurrent GLB loads are capped so a 50-strong fleet doesn't open 50 sockets.
//   • A rig the canonical library can't drive still renders (the model is shown),
//     it just holds its authored pose instead of idling — never a T-pose void.

import {
	AnimationMixer, Box3, CanvasTexture, Group, Mesh, RingGeometry,
	MeshBasicMaterial, Sprite, SpriteMaterial, Vector3, DoubleSide, SRGBColorSpace,
} from 'three';
import { clone as cloneSkinnedScene } from 'three/addons/utils/SkeletonUtils.js';
import { gltfLoader } from '../loaders/gltf.js';
import { AnimationManager } from '../animation-manager.js';
import { loadManifest, getLocomotionDefs, resolveAvatarUrl, AVATAR_DEFAULT, CLIP_IDLE, CLIP_WALK } from '../game/avatar-rig.js';
import { log } from '../shared/log.js';
import { scaleToHeight, groundFeet } from '../shared/avatar-fit.js';

// Target on-screen height so wildly-scaled GLBs all read as people in the square.
const AVATAR_HEIGHT = 1.74;
// Cap simultaneous GLB fetch+parse so a big fleet loads progressively instead of
// saturating the network and stalling the first frame.
const MAX_CONCURRENT_LOADS = 4;

// How many citizens may wear their OWN avatar GLB.
//
// The square renders the 200 most recently active citizens and a community
// avatar runs 2.7 MB to 21 MB, so dressing all of them is close to a gigabyte of
// download. Measured before this cap: the first personal GLB landed 81 seconds
// in and 19 of 200 citizens were standing after four and a half minutes, with an
// empty plaza the whole time. Presence comes first now (everyone is placed on the
// shared default rig, one 748 KB load for the entire crowd) and the most recently
// active citizens upgrade to their own model as it streams in. Nobody is missing
// and nobody is invented; only fidelity arrives progressively. Phones and tablets
// take a smaller share of that budget, matching the per-model download ceiling
// src/game/avatar-rig.js already applies there.
const _coarsePointer = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
export const MAX_PERSONAL_AVATARS = _coarsePointer ? 8 : 24;
const FADE_IN_SEC = 0.55;
// Citizen locomotion (Task 06 claim-walk). A citizen strolls to the board to
// claim and on to a work spot; the economy layer drives this via walkTo().
const WALK_SPEED = 2.7;          // m/s
const TURN_RATE = 9;             // rad/s toward heading
const ARRIVE_EPS = 0.35;         // metres "close enough"
const CELEBRATE_SEC = 1.1;       // duration of the completion hop

// Profession → accent colour. Keys match the API's profession keys
// (api/agora/[action].js PROFESSIONS). Used for the label chip and selection ring
// so the labour market is legible at a glance. Unknown professions fall back to a
// neutral platform accent — open by design, never a hardcoded allowlist gate.
export const PROFESSION_COLORS = {
	fetcher: '#4ea1ff',
	sculptor: '#ff8a5c',
	scribe: '#9b8cff',
	cartographer: '#36d399',
	crier: '#ff6fae',
	appraiser: '#ffd166',
	verifier: '#5ce0d8',
	namekeeper: '#c0a6ff',
};
const NEUTRAL_ACCENT = '#9fb4cc';

export function professionColor(profession) {
	return PROFESSION_COLORS[String(profession || '').toLowerCase()] || NEUTRAL_ACCENT;
}

// Display labels for the profession keys the API emits (lowercase). Falls back to
// a capitalised key so an unmapped/new profession still reads cleanly: open by
// design, never a hardcoded gate. Lives beside the colour map so a profession's
// name and its accent can never disagree.
export const PROFESSION_LABELS = {
	fetcher: 'Fetcher', sculptor: 'Sculptor', scribe: 'Scribe',
	cartographer: 'Cartographer', crier: 'Crier', appraiser: 'Appraiser',
	verifier: 'Verifier', namekeeper: 'Namekeeper',
};
export function professionLabelFor(profession) {
	const key = String(profession || '').toLowerCase();
	if (PROFESSION_LABELS[key]) return PROFESSION_LABELS[key];
	if (!key) return 'Citizen';
	return key.charAt(0).toUpperCase() + key.slice(1);
}

// The craft a citizen is *known for*, as a profession key.
//
// A citizen carries two profession fields and they mean different things:
// `profession` is the primary craft the world seeds and the job board hires on,
// while `professions` is the decoded AgenC capability bitmap (everything it is
// allowed to claim). Every citizen is granted the fetcher bit because an x402
// service call is the one craft anyone can do (workers/agora-citizens/roster.js),
// so `professions[0]` is *always* Fetcher and says nothing about who this is.
// Reading it as the citizen's craft labelled all 200 citizens "FETCHER" while
// their accent colour showed the real primary. Primary first, bitmap only as the
// fallback, so name, chip and colour always agree.
export function primaryProfessionKey(citizen) {
	return citizen?.profession || citizen?.professions?.[0]?.key || null;
}

/** The citizen's craft as display text ("Appraiser"), never an empty chip. */
export function citizenProfessionLabel(citizen) {
	const key = primaryProfessionKey(citizen);
	if (key) return professionLabelFor(key);
	// No primary key: honour a label the API already formatted before giving up.
	return citizen?.professions?.[0]?.label || 'Citizen';
}

const _box = new Box3();
const _v = new Vector3();

// Build a crisp, high-DPI billboard label: bold name over a profession chip.
// Returns a Sprite that always faces the camera (sizeAttenuation on, so distant
// labels recede naturally). Drawn on a transparent rounded panel for contrast
// against both bright sky and dark buildings. Exported so the player mode's
// remote humans (player-mode.js) wear the exact same nameplate as citizens.
export function buildLabelSprite(name, profession, accent) {
	const dpr = Math.min(window.devicePixelRatio || 1, 2);
	const padX = 22, nameSize = 34, profSize = 22, gap = 8;
	const font = (px, w) => `${w} ${px}px Inter, system-ui, sans-serif`;

	// Clamp a pathologically long display name so its billboard can't dominate the
	// square (the 3D sprite has no CSS ellipsis to fall back on). Truncate to a
	// sane width with an ellipsis; the full name still shows in the passport.
	const MAX_NAME = 24;
	const raw = String(name ?? 'Citizen');
	const shown = raw.length > MAX_NAME ? `${raw.slice(0, MAX_NAME - 1)}…` : raw;

	const measure = document.createElement('canvas').getContext('2d');
	measure.font = font(nameSize, 700);
	const nameW = measure.measureText(shown).width;
	const profText = (profession || 'Citizen').toUpperCase();
	measure.font = font(profSize, 600);
	const profW = measure.measureText(profText).width;

	const w = Math.ceil(Math.max(nameW, profW + 26) + padX * 2);
	const h = Math.ceil(nameSize + gap + profSize + 30);

	const c = document.createElement('canvas');
	c.width = Math.ceil(w * dpr);
	c.height = Math.ceil(h * dpr);
	const ctx = c.getContext('2d');
	ctx.scale(dpr, dpr);

	// Rounded translucent panel.
	const r = 12;
	ctx.fillStyle = 'rgba(8, 10, 14, 0.74)';
	ctx.strokeStyle = 'rgba(255,255,255,0.10)';
	ctx.lineWidth = 1;
	roundRect(ctx, 1, 1, w - 2, h - 2, r);
	ctx.fill();
	ctx.stroke();

	// Name (clamped — the canvas was sized for `shown`, so draw `shown` or a long
	// name would hard-clip at the canvas edge with no ellipsis).
	ctx.textBaseline = 'top';
	ctx.fillStyle = '#ffffff';
	ctx.font = font(nameSize, 700);
	ctx.fillText(shown, padX, 13);

	// Profession chip: accent dot + label.
	const py = 13 + nameSize + gap;
	ctx.fillStyle = accent;
	ctx.beginPath();
	ctx.arc(padX + 6, py + profSize / 2, 5, 0, Math.PI * 2);
	ctx.fill();
	ctx.fillStyle = 'rgba(255,255,255,0.78)';
	ctx.font = font(profSize, 600);
	ctx.fillText(profText, padX + 20, py + 1);

	const tex = new CanvasTexture(c);
	tex.colorSpace = SRGBColorSpace;
	tex.needsUpdate = true;
	const mat = new SpriteMaterial({ map: tex, transparent: true, depthTest: true, depthWrite: false });
	const sprite = new Sprite(mat);
	// World height of the label ~0.42m; width preserves the canvas aspect.
	const worldH = 0.46;
	sprite.scale.set(worldH * (w / h), worldH, 1);
	sprite.renderOrder = 2;
	sprite.userData.isLabel = true;
	return sprite;
}

function roundRect(ctx, x, y, w, h, r) {
	ctx.beginPath();
	ctx.moveTo(x + r, y);
	ctx.arcTo(x + w, y, x + w, y + h, r);
	ctx.arcTo(x + w, y + h, x, y + h, r);
	ctx.arcTo(x, y + h, x, y, r);
	ctx.arcTo(x, y, x + w, y, r);
	ctx.closePath();
}

export class CitizenPopulation {
	/**
	 * @param {object} opts
	 * @param {import('three').WebGLRenderer} opts.renderer
	 * @param {import('three').Scene} opts.scene
	 * @param {boolean} [opts.reducedMotion] honor prefers-reduced-motion (no fade/idle motion)
	 */
	constructor({ renderer, scene, reducedMotion = false }) {
		this.scene = scene;
		this.reducedMotion = reducedMotion;
		this.loader = gltfLoader(renderer);

		this.root = new Group();
		this.root.name = 'agora-citizens';
		scene.add(this.root);

		this.instances = [];          // { citizen, group, model, mixer, label, materials, fade, height }
		this._byId = new Map();       // citizen.id → instance
		this._templates = new Map();  // url → Promise<{ scene, clips, drivable }>
		this._clipJson = null;        // Promise<Map<name, clipJson>>
		this._loadSlots = 0;
		this._loadQueue = [];
		this._disposed = false;

		// A single reusable selection ring, parented to the highlighted citizen.
		this._ring = this._buildRing();
		this._ring.visible = false;
		scene.add(this._ring);
		this._selectedId = null;
	}

	_buildRing() {
		const geo = new RingGeometry(0.5, 0.62, 48);
		geo.rotateX(-Math.PI / 2);
		const mat = new MeshBasicMaterial({ color: 0xffffff, transparent: true, opacity: 0.85, side: DoubleSide, depthWrite: false });
		const ring = new Mesh(geo, mat);
		ring.renderOrder = 1;
		ring.name = 'agora-selection-ring';
		return ring;
	}

	// Fetch idle + walk clip JSON once, shared across every template.
	_ensureClips() {
		if (this._clipJson) return this._clipJson;
		this._clipJson = (async () => {
			await loadManifest();
			const defs = getLocomotionDefs();
			const map = new Map();
			await Promise.all(defs.map(async (d) => {
				try {
					const r = await fetch(d.url, { cache: 'force-cache' });
					if (r.ok) map.set(d.name, await r.json());
				} catch (err) {
					log.warn(`[agora] clip "${d.name}" fetch failed`, err?.message);
				}
			}));
			return map;
		})();
		return this._clipJson;
	}

	// Throttle concurrent GLB loads. Resolves when a slot frees up.
	_acquireSlot() {
		if (this._loadSlots < MAX_CONCURRENT_LOADS) {
			this._loadSlots++;
			return Promise.resolve();
		}
		return new Promise((resolve) => this._loadQueue.push(resolve));
	}
	_releaseSlot() {
		this._loadSlots--;
		const next = this._loadQueue.shift();
		if (next) { this._loadSlots++; next(); }
	}

	// Load a unique GLB once → reusable retargeted idle/walk clips bound to this
	// rig's node names (identical across every SkeletonUtils.clone).
	_template(url) {
		if (this._templates.has(url)) return this._templates.get(url);
		const p = (async () => {
			const clipJson = await this._ensureClips();
			await this._acquireSlot();
			let gltf;
			try {
				gltf = await this.loader.loadAsync(url);
			} finally {
				this._releaseSlot();
			}
			const sceneRoot = gltf.scene;
			sceneRoot.traverse((n) => {
				if (!n.isMesh) return;
				n.castShadow = true;
				n.receiveShadow = false;
			});
			// Retarget against a throwaway clone so the cached template stays pristine.
			const ref = cloneSkinnedScene(sceneRoot);
			const mgr = new AnimationManager();
			mgr.attach(ref, { avatarUrl: url });
			const clips = new Map();
			if (mgr.supportsCanonicalClips()) {
				for (const [name, json] of clipJson) {
					mgr.injectClip(name, json, { loop: true });
					const clip = mgr.actions.get(name)?.getClip?.();
					if (clip) clips.set(name, clip);
				}
			}
			mgr.detach();
			return { scene: sceneRoot, clips, drivable: clips.size > 0 };
		})().catch((err) => {
			log.warn('[agora] template load failed', url, err?.message);
			return { scene: null, clips: new Map(), drivable: false };
		});
		this._templates.set(url, p);
		return p;
	}

	/**
	 * Add one citizen to the world at (x, z) facing roughly toward the plaza
	 * centre. Returns the instance (or null if even the shared rig couldn't be
	 * loaded). Safe to call concurrently for the whole fleet; loads are pooled
	 * internally.
	 *
	 * The citizen stands up on the shared default rig, which is one small GLB for
	 * the entire crowd, so the square is populated in seconds. When `personal` is
	 * set and the citizen carries its own avatar, that model streams in behind the
	 * scenes and replaces the placeholder in place (see MAX_PERSONAL_AVATARS).
	 *
	 * @param {object} citizen   shaped citizen from /api/agora/citizens
	 * @param {{x:number,z:number}} pos
	 * @param {{personal?:boolean}} [opts] load this citizen's own avatar GLB too
	 */
	async add(citizen, pos, { personal = true } = {}) {
		if (this._disposed || this._byId.has(citizen.id)) return null;
		const tpl = await this._template(AVATAR_DEFAULT);
		if (this._disposed || this._byId.has(citizen.id)) return null;
		if (!tpl?.scene) return null;

		const built = this._buildModel(tpl);

		const group = new Group();
		group.name = `citizen-${citizen.id}`;
		group.add(built.model);
		group.position.set(pos.x, 0, pos.z);
		// Face the plaza centre with a little jitter so the crowd feels gathered,
		// not regimented. atan2(x,z) points the +Z-forward avatar toward origin.
		const baseYaw = Math.atan2(-pos.x, -pos.z);
		group.rotation.y = baseYaw + (hashJitter(citizen.id) - 0.5) * 0.8;
		group.userData.citizenId = citizen.id;
		this.root.add(group);

		const accent = professionColor(primaryProfessionKey(citizen));
		const label = buildLabelSprite(citizen.displayName || 'Citizen', citizenProfessionLabel(citizen), accent);
		label.position.set(0, built.height + 0.3, 0);
		group.add(label);

		const inst = {
			citizen, group, model: built.model, mixer: null, label,
			materials: built.materials, fade: null, height: built.height, baseYaw,
			// Locomotion + economy state (Task 06).
			idleClip: tpl.clips.get(CLIP_IDLE) || [...tpl.clips.values()][0] || null,
			walkClip: tpl.clips.get(CLIP_WALK) || null,
			idleAction: null, walkAction: null,
			motion: 'idle', walkTarget: null, onArrive: null, heading: group.rotation.y,
			busy: false, busyRing: null, busyT: 0, celebrateT: null,
			// The citizen's own avatar, once it has replaced the shared rig. Keeps a
			// re-run of loadCitizens from re-loading a model already worn.
			wearing: AVATAR_DEFAULT,
		};
		this._startIdle(inst);
		this._beginFade(inst);
		this.instances.push(inst);
		this._byId.set(citizen.id, inst);
		this._tagPickable(inst);

		if (personal && citizen.avatarUrl) this._wearOwnAvatar(inst, String(citizen.avatarUrl));
		return inst;
	}

	// Clone a template into a per-instance model: scaled to human height, feet on
	// the ground, and with its own materials so one citizen's fade-in never bleeds
	// across everyone else sharing that GLB (geometry and textures stay shared).
	_buildModel(tpl) {
		const model = cloneSkinnedScene(tpl.scene);
		scaleToHeight(model, AVATAR_HEIGHT);
		groundFeet(model);

		const materials = [];
		model.traverse((n) => {
			if (!n.isMesh || !n.material) return;
			const mats = Array.isArray(n.material) ? n.material : [n.material];
			const cloned = mats.map((m) => {
				const c = m.clone();
				c.transparent = true;
				c.depthWrite = true;
				return c;
			});
			n.material = Array.isArray(n.material) ? cloned : cloned[0];
			materials.push(...cloned);
		});

		_box.setFromObject(model, true);
		const height = Number.isFinite(_box.max.y) ? _box.max.y : AVATAR_HEIGHT;
		return { model, materials, height };
	}

	// Pickable meshes carry a back-reference so a raycast hit resolves to the id.
	_tagPickable(inst) {
		inst.model.traverse((n) => { if (n.isMesh) n.userData.citizenId = inst.citizen.id; });
	}

	// Start this citizen's idle loop on its current model, desynced by id so the
	// crowd doesn't breathe in lockstep. Reduced motion holds a calm authored pose
	// instead of looping.
	_startIdle(inst) {
		if (!inst.idleClip) return;
		inst.mixer = new AnimationMixer(inst.model);
		inst.idleAction = inst.mixer.clipAction(inst.idleClip);
		if (this.reducedMotion) {
			inst.idleAction.play();
			inst.mixer.update(0);
			inst.idleAction.paused = true;
			return;
		}
		inst.idleAction.time = hashJitter(inst.citizen.id + 'x') * (inst.idleClip.duration || 1);
		inst.idleAction.play();
	}

	// Fade a freshly built model up from transparent. Reduced motion skips it and
	// the citizen is simply there.
	_beginFade(inst) {
		inst.fade = this.reducedMotion ? null : { t: 0 };
		for (const m of inst.materials) m.opacity = this.reducedMotion ? 1 : 0;
	}

	// Load the citizen's own avatar and swap it in when it lands. Fire-and-forget:
	// a failure leaves the citizen on the shared rig, which is a complete, correct
	// world, never an error state and never a missing person.
	async _wearOwnAvatar(inst, rawUrl) {
		const url = await resolveAvatarUrl(rawUrl);
		if (!url || url === AVATAR_DEFAULT) return;
		const tpl = await this._template(url);
		if (this._disposed || !tpl?.scene) return;
		// The world may have been rebuilt (or this citizen removed) across the load.
		if (this._byId.get(inst.citizen.id) !== inst) return;
		this._swapModel(inst, tpl);
		inst.wearing = url;
	}

	// Swap a standing citizen onto a different model without disturbing where it
	// stands, which way it faces, or what it is doing: the new rig inherits the
	// current motion, so a citizen mid-walk to the job board keeps walking.
	_swapModel(inst, tpl) {
		const built = this._buildModel(tpl);
		const motion = inst.motion;

		inst.mixer?.stopAllAction();
		inst.group.remove(inst.model);
		for (const m of inst.materials) m.dispose?.();

		inst.group.add(built.model);
		// A celebrate hop lifts the model, not the group; the new one starts level.
		built.model.position.y = 0;
		inst.celebrateT = null;
		inst.model = built.model;
		inst.materials = built.materials;
		inst.height = built.height;
		inst.label.position.set(0, built.height + 0.3, 0);

		inst.idleClip = tpl.clips.get(CLIP_IDLE) || [...tpl.clips.values()][0] || null;
		inst.walkClip = tpl.clips.get(CLIP_WALK) || null;
		inst.mixer = null;
		inst.idleAction = null;
		inst.walkAction = null;
		this._startIdle(inst);
		// Re-assert the motion on the new mixer (_playMotion no-ops on a match).
		inst.motion = null;
		this._playMotion(inst, motion);

		this._tagPickable(inst);
		this._beginFade(inst);
	}

	/** Advance idle loops + fade-ins + locomotion. Cheap: one mixer.update per citizen. */
	update(dt) {
		for (const inst of this.instances) {
			this._advanceMotion(inst, dt);
			if (!this.reducedMotion) inst.mixer?.update(dt);
			if (inst.fade) {
				inst.fade.t += dt;
				const k = Math.min(1, inst.fade.t / FADE_IN_SEC);
				const eased = k * (2 - k); // ease-out
				for (const m of inst.materials) m.opacity = eased;
				if (k >= 1) {
					for (const m of inst.materials) { m.transparent = false; }
					inst.fade = null;
				}
			}
		}
	}

	// ── Locomotion + economy state (Task 06) ──────────────────────────────────
	// Drive one citizen toward a target; on arrival fire its callback. Reduced
	// motion places it instantly (no travelling motion), per the DoD.
	_advanceMotion(inst, dt) {
		// Busy ring. Under reduced motion it holds a steady presence (no throbbing
		// opacity, no scale pulse) — a Busy citizen still reads as busy without the
		// animation the DoD says to suppress. Reads reducedMotion live so an OS
		// toggle mid-session takes effect.
		if (inst.busyRing) {
			let target;
			if (!inst.busy) target = 0;
			else if (this.reducedMotion) target = 0.6;
			else target = 0.55 + 0.25 * Math.sin((inst.busyT += dt) * 3.2);
			inst.busyRing.material.opacity += (target - inst.busyRing.material.opacity) * Math.min(1, dt * 6);
			inst.busyRing.position.set(inst.group.position.x, 0.03, inst.group.position.z);
			if (inst.busy && !this.reducedMotion) {
				inst.busyRing.scale.setScalar(1 + 0.06 * Math.sin(inst.busyT * 3.2));
			} else if (inst.busyRing.scale.x !== 1) {
				inst.busyRing.scale.setScalar(1);
			}
		}

		// Completion celebrate — a short, tasteful hop (skipped under reduced motion).
		if (inst.celebrateT != null) {
			inst.celebrateT += dt;
			const p = inst.celebrateT / CELEBRATE_SEC;
			if (p >= 1) { inst.celebrateT = null; inst.model.position.y = 0; }
			else { inst.model.position.y = Math.sin(p * Math.PI) * 0.32; }
		}

		// Walk toward the active target.
		if (inst.walkTarget) {
			const g = inst.group.position;
			const tx = inst.walkTarget.x, tz = inst.walkTarget.z;
			const dx = tx - g.x, dz = tz - g.z;
			const dist = Math.hypot(dx, dz);
			if (dist <= ARRIVE_EPS) {
				const cb = inst.onArrive;
				inst.walkTarget = null; inst.onArrive = null;
				this._playMotion(inst, 'idle');
				if (cb) cb();
			} else {
				const step = Math.min(dist, WALK_SPEED * dt);
				g.x += (dx / dist) * step;
				g.z += (dz / dist) * step;
				inst.heading = Math.atan2(dx, dz);
				this._playMotion(inst, 'walk');
				let diff = inst.heading - inst.group.rotation.y;
				while (diff > Math.PI) diff -= Math.PI * 2;
				while (diff < -Math.PI) diff += Math.PI * 2;
				inst.group.rotation.y += diff * Math.min(1, dt * TURN_RATE);
			}
		}
	}

	// Crossfade a citizen between its idle and walk clips. No-op for rigs the
	// canonical clips can't drive (the model still translates — never a T-pose).
	_playMotion(inst, motion) {
		if (inst.motion === motion || !inst.mixer || this.reducedMotion) { inst.motion = motion; return; }
		inst.motion = motion;
		if (motion === 'walk' && inst.walkClip) {
			if (!inst.walkAction) inst.walkAction = inst.mixer.clipAction(inst.walkClip);
			inst.walkAction.reset().fadeIn(0.2).play();
			inst.idleAction?.fadeOut(0.2);
		} else {
			inst.idleAction?.reset().fadeIn(0.2).play();
			inst.walkAction?.fadeOut(0.2);
		}
	}

	_buildBusyRing(accent) {
		const geo = new RingGeometry(0.46, 0.6, 40);
		geo.rotateX(-Math.PI / 2);
		const mat = new MeshBasicMaterial({ color: accent, transparent: true, opacity: 0, side: DoubleSide, depthWrite: false });
		const ring = new Mesh(geo, mat);
		ring.renderOrder = 1;
		this.scene.add(ring);
		return ring;
	}

	/** Route a citizen to a world target; onArrive fires once when reached. */
	walkTo(id, target, onArrive) {
		const inst = this._byId.get(id);
		if (!inst || !target) return;
		const tx = Number(target.x), tz = Number(target.z);
		if (!Number.isFinite(tx) || !Number.isFinite(tz)) return;
		if (this.reducedMotion) {
			// No travelling motion under reduced motion — place + settle.
			inst.group.position.x = tx; inst.group.position.z = tz;
			inst.walkTarget = null;
			if (onArrive) onArrive();
			return;
		}
		inst.walkTarget = { x: tx, z: tz };
		inst.onArrive = typeof onArrive === 'function' ? onArrive : null;
	}

	/** Reflect an economy status — Busy shows a glowing profession-coloured ring. */
	setStatus(id, status) {
		const inst = this._byId.get(id);
		if (!inst) return;
		inst.busy = status === 'Busy';
		if (inst.busy && !inst.busyRing) {
			const accent = professionColor(primaryProfessionKey(inst.citizen));
			inst.busyRing = this._buildBusyRing(accent);
		}
	}

	/** A short completion celebrate (a tasteful hop). No-op under reduced motion. */
	celebrate(id) {
		const inst = this._byId.get(id);
		if (!inst || this.reducedMotion) return;
		inst.celebrateT = 0;
	}

	/** Resolve a citizen by display name (pulse.recent carries names, not ids). */
	findByName(name) {
		if (!name) return null;
		const inst = this.instances.find((i) => i.citizen.displayName === name);
		if (!inst) return null;
		return { id: inst.citizen.id, position: this.worldPosition(inst.citizen.id) };
	}

	/**
	 * Hit-test pickable avatars. Returns the citizen id under the ray, or null.
	 * @param {import('three').Raycaster} raycaster
	 */
	pick(raycaster) {
		const hits = raycaster.intersectObjects(this.root.children, true);
		for (const h of hits) {
			let o = h.object;
			while (o) {
				if (o.userData?.citizenId) return o.userData.citizenId;
				o = o.parent;
			}
		}
		return null;
	}

	/** Move + show the selection ring under a citizen (null clears it). */
	highlight(id) {
		this._selectedId = id;
		const inst = id ? this._byId.get(id) : null;
		if (!inst) { this._ring.visible = false; return; }
		inst.group.getWorldPosition(_v);
		this._ring.position.set(_v.x, 0.02, _v.z);
		const accent = professionColor(primaryProfessionKey(inst.citizen));
		this._ring.material.color.set(accent);
		this._ring.visible = true;
	}

	get selectedId() { return this._selectedId; }

	getInstance(id) { return this._byId.get(id) || null; }

	/** World position of a citizen (for framing the camera). Null if unknown. */
	worldPosition(id) {
		const inst = this._byId.get(id);
		if (!inst) return null;
		inst.group.getWorldPosition(_v);
		return _v.clone();
	}

	get count() { return this.instances.length; }

	dispose() {
		this._disposed = true;
		for (const inst of this.instances) {
			inst.mixer?.stopAllAction();
			for (const m of inst.materials) m.dispose?.();
			inst.label.material.map?.dispose?.();
			inst.label.material.dispose?.();
			if (inst.busyRing) {
				inst.busyRing.geometry.dispose();
				inst.busyRing.material.dispose();
				this.scene.remove(inst.busyRing);
			}
			inst.group.parent?.remove(inst.group);
		}
		this.instances = [];
		this._byId.clear();
		this._ring.geometry.dispose();
		this._ring.material.dispose();
		this.scene.remove(this._ring);
		this.scene.remove(this.root);
		this._templates.clear();
	}
}

// Deterministic per-id jitter in [0,1) — keeps facing/desync stable across
// reloads (no Math.random, so the same citizen always stands the same way).
function hashJitter(seed) {
	const s = String(seed);
	let h = 2166136261;
	for (let i = 0; i < s.length; i++) {
		h ^= s.charCodeAt(i);
		h = Math.imul(h, 16777619);
	}
	return ((h >>> 0) % 100000) / 100000;
}