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.

37.7 KB
Raw Blame
// ── ibm-galaxy.js ───────────────────────────────────────────────────────────
// The IBM Granite Agent Galaxy: an explorable 3D constellation where every
// three.ws agent is a star positioned by its IBM Granite embedding. Agents that
// mean similar things sit near each other; k-means themes (named by Granite)
// colour the clusters; natural-language search embeds the query on Granite and
// flies the camera to whatever the words actually mean.
//
// Data comes from /api/ibm/galaxy (GET = layout, POST = semantic search). There
// is no client-side mock: when watsonx is unconfigured or there are too few
// agents, the page shows a designed, honest state instead of inventing stars.

import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
import { log } from './shared/log.js';

const RADIUS = 100; // matches the server's projection half-width

// ── DOM ──────────────────────────────────────────────────────────────────────
const $ = (id) => document.getElementById(id);
const canvas = $('scene');
const els = {
	searchWrap: $('searchWrap'), searchBox: $('searchBox'), searchInput: $('searchInput'),
	searchClear: $('searchClear'), searchHint: $('searchHint'), results: $('results'),
	legend: $('legend'), legendRows: $('legendRows'), legendFoot: $('legendFoot'),
	legendMobile: $('legendMobile'), legendMobileRows: $('legendMobileRows'),
	legendToggle: $('legendToggle'),
	stats: $('stats'), tooltip: $('tooltip'), clusterLabels: $('clusterLabels'),
	panel: $('panel'), panelHead: $('panelHead'), panelBody: $('panelBody'), panelClose: $('panelClose'),
	loading: $('loadingState'), empty: $('emptyState'), unavailable: $('unavailableState'),
	error: $('errorState'), errorMsg: $('errorMsg'), emptyTitle: $('emptyTitle'), emptyMsg: $('emptyMsg'),
	unavailableMsg: $('unavailableMsg'), loadSteps: $('loadSteps'), retryBtn: $('retryBtn'),
	resetView: $('resetView'), hudHint: $('hudHint'), tourBtn: $('tourBtn'),
	shortcutsOverlay: $('shortcutsOverlay'), shortcutsBtn: $('shortcutsBtn'), shortcutsClose: $('shortcutsClose'),
};

// ── State ─────────────────────────────────────────────────────────────────────
const state = {
	data: null,            // galaxy payload
	agents: [],            // [{...agent, vec3:THREE.Vector3}]
	clusters: [],
	byId: new Map(),
	hovered: -1,
	selected: -1,
	isolatedCluster: null, // legend isolation
	searchActive: false,
	lastResults: [],
};

// ── Three.js core ─────────────────────────────────────────────────────────────
let renderer, scene, camera, controls, raycaster, points, geometry, material, starfield;
let aDim, aHi, aSize, positions, colors; // attribute backing arrays
const pointer = new THREE.Vector2(-2, -2);
let pointerDown = null; // {x,y} to distinguish click from drag
let rafPending = false; // coalesce hover raycasts to one per frame
const _pointerClient = { x: 0, y: 0 }; // latest cursor position for tooltip placement
const fly = { active: false, camFrom: new THREE.Vector3(), camTo: new THREE.Vector3(), tgtFrom: new THREE.Vector3(), tgtTo: new THREE.Vector3(), t: 0, dur: 1 };
let idleTimer = 0;
const clock = new THREE.Timer();
const EXAMPLES = [
	'a witty crypto trading assistant',
	'helpful customer support agent',
	'a creative storyteller for kids',
	'on-chain data analyst',
	'a calm meditation guide',
];

function initThree() {
	renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false, powerPreference: 'high-performance' });
	renderer.setClearColor(0x05070d, 1);
	renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
	renderer.setSize(window.innerWidth, window.innerHeight, false);

	scene = new THREE.Scene();
	scene.fog = new THREE.FogExp2(0x05070d, 0.0016);

	camera = new THREE.PerspectiveCamera(55, window.innerWidth / window.innerHeight, 0.1, 4000);
	camera.position.set(0, 48, RADIUS * 2.7);

	controls = new OrbitControls(camera, renderer.domElement);
	controls.enableDamping = true;
	controls.dampingFactor = 0.08;
	controls.rotateSpeed = 0.6;
	controls.minDistance = 30;
	controls.maxDistance = RADIUS * 6;
	controls.autoRotate = true;
	controls.autoRotateSpeed = 0.35;
	controls.target.set(0, 0, 0);
	controls.addEventListener('start', () => { controls.autoRotate = false; idleTimer = 0; if (tour.active) stopTour(); });

	raycaster = new THREE.Raycaster();
	raycaster.params.Points.threshold = 3.2;

	buildStarfield();
	window.addEventListener('resize', onResize, { passive: true });
	renderer.domElement.addEventListener('pointermove', onPointerMove, { passive: true });
	renderer.domElement.addEventListener('pointerdown', (e) => { pointerDown = { x: e.clientX, y: e.clientY }; });
	renderer.domElement.addEventListener('pointerup', onPointerUp);
	renderer.domElement.addEventListener('pointerleave', () => { setHover(-1); });
	renderer.setAnimationLoop(animate);
}

// Faint, slowly-drifting background stars for depth — purely decorative.
function buildStarfield() {
	const N = 1600;
	const g = new THREE.BufferGeometry();
	const pos = new Float32Array(N * 3);
	for (let i = 0; i < N; i++) {
		const r = 600 + Math.pow(Math.random(), 0.5) * 1400;
		const theta = Math.random() * Math.PI * 2;
		const phi = Math.acos(2 * Math.random() - 1);
		pos[i * 3] = r * Math.sin(phi) * Math.cos(theta);
		pos[i * 3 + 1] = r * Math.sin(phi) * Math.sin(theta);
		pos[i * 3 + 2] = r * Math.cos(phi);
	}
	g.setAttribute('position', new THREE.BufferAttribute(pos, 3));
	const m = new THREE.PointsMaterial({ color: 0x66708a, size: 1.6, sizeAttenuation: true, transparent: true, opacity: 0.55, depthWrite: false });
	starfield = new THREE.Points(g, m);
	scene.add(starfield);
}

// ── Star shader (glowing, twinkling, dimmable, highlightable) ─────────────────
const VERT = `
	attribute float aSize;
	attribute float aDim;
	attribute float aHi;
	varying vec3 vColor;
	varying float vDim;
	varying float vHi;
	uniform float uPixelRatio;
	uniform float uTime;
	void main() {
		vColor = color;
		vDim = aDim;
		vHi = aHi;
		vec4 mv = modelViewMatrix * vec4(position, 1.0);
		float tw = 0.85 + 0.15 * sin(uTime * 1.6 + position.x * 0.4 + position.y * 0.7);
		float size = aSize * (1.0 + aHi * 1.6) * tw;
		gl_PointSize = size * uPixelRatio * (320.0 / -mv.z);
		gl_Position = projectionMatrix * mv;
	}
`;
const FRAG = `
	varying vec3 vColor;
	varying float vDim;
	varying float vHi;
	void main() {
		vec2 uv = gl_PointCoord - vec2(0.5);
		float d = length(uv);
		if (d > 0.5) discard;
		float core = smoothstep(0.5, 0.0, d);
		float glow = pow(core, 1.7);
		float alpha = glow * vDim;
		vec3 col = mix(vColor, vec3(1.0), vHi * 0.45 + glow * 0.18);
		gl_FragColor = vec4(col * (0.55 + 0.9 * glow), alpha);
	}
`;

function buildPoints() {
	if (points) { scene.remove(points); geometry.dispose(); material.dispose(); }
	const n = state.agents.length;
	positions = new Float32Array(n * 3);
	colors = new Float32Array(n * 3);
	aSize = new Float32Array(n);
	aDim = new Float32Array(n);
	aHi = new Float32Array(n);
	const col = new THREE.Color();
	for (let i = 0; i < n; i++) {
		const a = state.agents[i];
		positions[i * 3] = a.x; positions[i * 3 + 1] = a.y; positions[i * 3 + 2] = a.z;
		col.set(a.color);
		colors[i * 3] = col.r; colors[i * 3 + 1] = col.g; colors[i * 3 + 2] = col.b;
		// Deterministic mild size variation for life (seeded by id char codes).
		const seed = (a.id.charCodeAt(0) + a.id.charCodeAt(a.id.length - 1)) % 10;
		aSize[i] = 20 + seed * 0.9;
		aDim[i] = 1; aHi[i] = 0;
	}
	geometry = new THREE.BufferGeometry();
	geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
	geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
	geometry.setAttribute('aSize', new THREE.BufferAttribute(aSize, 1));
	geometry.setAttribute('aDim', new THREE.BufferAttribute(aDim, 1));
	geometry.setAttribute('aHi', new THREE.BufferAttribute(aHi, 1));
	material = new THREE.ShaderMaterial({
		uniforms: { uPixelRatio: { value: renderer.getPixelRatio() }, uTime: { value: 0 } },
		vertexShader: VERT, fragmentShader: FRAG,
		transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, vertexColors: true,
	});
	points = new THREE.Points(geometry, material);
	scene.add(points);
}

// ── Animation loop ────────────────────────────────────────────────────────────
function animate() {
	clock.update();
	const dt = clock.getDelta();
	const t = clock.getElapsed();
	if (material) material.uniforms.uTime.value = t;
	if (starfield) starfield.rotation.y += dt * 0.006;

	// Idle → resume gentle auto-rotate after a few seconds of no interaction.
	if (!controls.autoRotate && !fly.active) {
		idleTimer += dt;
		if (idleTimer > 4) controls.autoRotate = true;
	}

	if (fly.active) {
		fly.t += dt / fly.dur;
		const k = fly.t >= 1 ? 1 : easeInOut(fly.t);
		camera.position.lerpVectors(fly.camFrom, fly.camTo, k);
		controls.target.lerpVectors(fly.tgtFrom, fly.tgtTo, k);
		if (fly.t >= 1) fly.active = false;
	}

	controls.update();
	updateClusterLabels();
	renderer.render(scene, camera);
}

function easeInOut(x) { return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2; }

// ── Cluster labels projected to screen ────────────────────────────────────────
const labelEls = [];
function buildClusterLabels() {
	els.clusterLabels.innerHTML = '';
	labelEls.length = 0;
	for (const c of state.clusters) {
		if (!c.size) continue;
		const el = document.createElement('div');
		el.className = 'clabel';
		el.textContent = c.label;
		el.style.color = c.color;
		el.style.borderColor = hexA(c.color, 0.4);
		labelEls.push({ el, c, v: new THREE.Vector3(c.x, c.y, c.z) });
		els.clusterLabels.appendChild(el);
	}
}
const _proj = new THREE.Vector3();
function updateClusterLabels() {
	if (!labelEls.length) return;
	const w = window.innerWidth, h = window.innerHeight;
	for (const { el, c, v } of labelEls) {
		_proj.copy(v).project(camera);
		const visible = _proj.z < 1 && (state.isolatedCluster === null || state.isolatedCluster === c.id) && !state.searchActive;
		if (!visible) { el.style.opacity = '0'; continue; }
		const x = (_proj.x * 0.5 + 0.5) * w;
		const y = (-_proj.y * 0.5 + 0.5) * h;
		el.style.left = x + 'px';
		el.style.top = y + 'px';
		el.style.opacity = '0.92';
	}
}

// ── Hover & selection ─────────────────────────────────────────────────────────
function onPointerMove(e) {
	pointer.x = (e.clientX / window.innerWidth) * 2 - 1;
	pointer.y = -(e.clientY / window.innerHeight) * 2 + 1;
	_pointerClient.x = e.clientX;
	_pointerClient.y = e.clientY;
	// Pointermove fires far more often than the display refreshes; coalesce the
	// raycast + tooltip work to one pass per frame via a rAF flag.
	if (!rafPending) {
		rafPending = true;
		requestAnimationFrame(updateHover);
	}
}

function updateHover() {
	rafPending = false;
	if (!points) return;
	raycaster.setFromCamera(pointer, camera);
	const hits = raycaster.intersectObject(points);
	const idx = pickVisible(hits);
	setHover(idx);
	if (idx >= 0) positionTooltip(_pointerClient.x, _pointerClient.y, idx);
}

// Nearest hit that isn't dimmed away by isolation/search.
function pickVisible(hits) {
	for (const hit of hits) {
		const i = hit.index;
		if (aDim[i] > 0.5) return i;
	}
	return -1;
}

function setHover(idx) {
	if (idx === state.hovered) return;
	if (state.hovered >= 0 && state.hovered !== state.selected) aHi[state.hovered] = 0;
	state.hovered = idx;
	if (idx >= 0) {
		aHi[idx] = Math.max(aHi[idx], 0.8);
		canvas.style.cursor = 'pointer';
		els.tooltip.classList.add('show');
	} else {
		canvas.style.cursor = 'grab';
		els.tooltip.classList.remove('show');
	}
	geometry.attributes.aHi.needsUpdate = true;
}

function positionTooltip(px, py, idx) {
	const a = state.agents[idx];
	const c = state.clusters[a.cluster];
	const match = state.searchActive && a._score != null ? `<div class="tt-match">${Math.round(a._score * 100)}% match</div>` : '';
	els.tooltip.innerHTML =
		`<div class="tt-theme" style="color:${c?.color || '#fff'}">${escapeHtml(c?.label || 'Agent')}</div>` +
		`<div class="tt-name">${escapeHtml(a.name)}</div>` +
		(a.description ? `<div class="tt-desc">${escapeHtml(a.description)}</div>` : '') + match;
	const tw = 280, gap = 16;
	let x = px + gap, y = py + gap;
	if (x + tw > window.innerWidth) x = px - tw - gap;
	if (y + 120 > window.innerHeight) y = py - 120 - gap;
	els.tooltip.style.left = Math.max(8, x) + 'px';
	els.tooltip.style.top = Math.max(8, y) + 'px';
}

function onPointerUp(e) {
	if (!pointerDown) return;
	const moved = Math.abs(e.clientX - pointerDown.x) + Math.abs(e.clientY - pointerDown.y);
	pointerDown = null;
	if (moved > 6) return; // a drag, not a click
	if (!points) return;
	raycaster.setFromCamera(pointer, camera);
	const idx = pickVisible(raycaster.intersectObject(points));
	if (idx >= 0) selectAgent(idx, true);
}

// ── Camera fly-to ─────────────────────────────────────────────────────────────
function flyTo(target, distance = 70) {
	controls.autoRotate = false;
	idleTimer = -3; // hold off auto-rotate a little longer after a fly
	const dir = new THREE.Vector3().subVectors(camera.position, controls.target).normalize();
	fly.camFrom.copy(camera.position);
	fly.tgtFrom.copy(controls.target);
	fly.tgtTo.copy(target);
	fly.camTo.copy(target).addScaledVector(dir, distance);
	fly.t = 0; fly.dur = 1.05; fly.active = true;
}

function resetView() {
	flyTo(new THREE.Vector3(0, 0, 0), RADIUS * 2.7);
	fly.camTo.set(0, 48, RADIUS * 2.7);
}

// ── Detail panel ──────────────────────────────────────────────────────────────
function selectAgent(idx, doFly) {
	if (state.selected >= 0) aHi[state.selected] = 0;
	state.selected = idx;
	aHi[idx] = 1;
	geometry.attributes.aHi.needsUpdate = true;
	const a = state.agents[idx];
	const c = state.clusters[a.cluster];
	if (doFly) flyTo(new THREE.Vector3(a.x, a.y, a.z), 60);

	const neighbors = semanticNeighbors(a, 5);
	drawLinks(idx, neighbors);
	setUrlParam('agent', a.id);

	const color = c?.color || '#78a9ff';
	els.panelHead.innerHTML =
		`<div class="p-avatar-row">` +
		avatarMarkup(a, 'p-avatar') +
		`<div class="p-meta">` +
		`<div class="p-theme" style="color:${color}"><span class="swatch" style="background:${color}"></span>${escapeHtml(c?.label || 'Agent')}</div>` +
		`<div class="p-name">${escapeHtml(a.name)}</div>` +
		`</div></div>`;

	const hasGraniteScores = neighbors.length && neighbors[0].score != null;
	const nbMarkup = neighbors.map((nb) => {
		const na = nb.agent;
		const pct = nb.score != null ? Math.round(nb.score * 100) : null;
		const barWidth = pct != null ? Math.round(scoreToBrightness(nb.score) * 100) : 0;
		const scoreHtml = pct != null
			? `<div class="nb-score-row"><div class="nb-bar"><i style="width:${barWidth}%"></i></div><span class="nb-pct">${pct}%</span></div>`
			: `<div class="nb-score-row"><span style="font-size:10px;color:var(--muted2)">${escapeHtml(state.clusters[na.cluster]?.label || '')}</span></div>`;
		return `<div class="nb" data-idx="${nb.idx}">${avatarMarkup(na, 'nb-av')}` +
			`<div class="nb-meta"><div class="nb-name">${escapeHtml(na.name)}</div>${scoreHtml}</div></div>`;
	}).join('');

	const graniteTag = hasGraniteScores ? '<span class="granite-tag">· Granite cosine</span>' : '';
	els.panelBody.innerHTML =
		`<div class="p-desc">${escapeHtml(a.description || 'No description provided.')}</div>` +
		(neighbors.length ? `<div class="p-section neighbors"><h4>Nearest in meaning ${graniteTag}</h4>${nbMarkup}</div>` : '') +
		`<div class="p-actions">` +
		`<a class="p-cta" href="${escapeAttr(a.url)}">Open agent</a>` +
		`<button class="p-copy-link" title="Copy shareable link">` +
		`<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>` +
		`Copy link</button>` +
		`</div>`;

	els.panelBody.querySelectorAll('.nb').forEach((row) => {
		row.addEventListener('click', () => selectAgent(Number(row.dataset.idx), true));
	});
	const copyBtn = els.panelBody.querySelector('.p-copy-link');
	if (copyBtn) {
		copyBtn.addEventListener('click', () => {
			const url = new URL(window.location.href);
			url.searchParams.set('agent', a.id);
			navigator.clipboard.writeText(url.toString()).then(() => {
				copyBtn.classList.add('copied');
				copyBtn.textContent = 'Copied!';
				setTimeout(() => { copyBtn.classList.remove('copied'); copyBtn.innerHTML = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>Copy link`; }, 2000);
			}).catch(() => {
				// Fallback: select the URL so user can copy manually.
				const inp = document.createElement('input');
				inp.value = url.toString();
				document.body.appendChild(inp);
				inp.select();
				document.execCommand('copy');
				inp.remove();
			});
		});
	}

	els.panel.classList.add('open');
	els.panel.setAttribute('aria-hidden', 'false');
}

function closePanel() {
	els.panel.classList.remove('open');
	els.panel.setAttribute('aria-hidden', 'true');
	if (state.selected >= 0 && state.selected !== state.hovered) aHi[state.selected] = 0;
	state.selected = -1;
	geometry.attributes.aHi.needsUpdate = true;
	clearLinks();
	setUrlParam('agent', null);
}

// Semantic neighbours: prefer the server's Granite-cosine ranking (true meaning),
// falling back to 3D proximity only if the payload predates that field.
function semanticNeighbors(agent, k) {
	if (Array.isArray(agent.neighbors) && agent.neighbors.length) {
		return agent.neighbors.slice(0, k).map((nb) => {
			const na = state.byId.get(nb.id);
			return na ? { agent: na, idx: state.agents.indexOf(na), score: nb.score } : null;
		}).filter(Boolean);
	}
	return nearestNeighbors3D(state.agents.indexOf(agent), k).map((nb) => ({ agent: state.agents[nb.idx], idx: nb.idx, score: null }));
}

// Fallback nearest neighbours by 3D distance — the proximity the eye sees.
function nearestNeighbors3D(idx, k) {
	const a = state.agents[idx];
	const out = [];
	for (let i = 0; i < state.agents.length; i++) {
		if (i === idx) continue;
		const b = state.agents[i];
		const d = (a.x - b.x) ** 2 + (a.y - b.y) ** 2 + (a.z - b.z) ** 2;
		out.push({ idx: i, d });
	}
	out.sort((p, q) => p.d - q.d);
	return out.slice(0, k);
}

// ── Constellation links ───────────────────────────────────────────────────────
// Faint glowing lines from the selected agent to its semantic neighbours —
// literally drawing the constellation the embedding implies.
let linkLines = null;
function clearLinks() {
	if (linkLines) { scene.remove(linkLines); linkLines.geometry.dispose(); linkLines.material.dispose(); linkLines = null; }
}
function drawLinks(idx, neighbors) {
	clearLinks();
	if (!neighbors.length) return;
	const a = state.agents[idx];
	const col = new THREE.Color(a.color);
	const pos = [];
	const colors = [];
	for (const nb of neighbors) {
		const b = nb.agent;
		pos.push(a.x, a.y, a.z, b.x, b.y, b.z);
		// Brighter near the selected end, dimmer at the neighbour end.
		colors.push(col.r, col.g, col.b, col.r * 0.5, col.g * 0.5, col.b * 0.5);
	}
	const g = new THREE.BufferGeometry();
	g.setAttribute('position', new THREE.BufferAttribute(new Float32Array(pos), 3));
	g.setAttribute('color', new THREE.BufferAttribute(new Float32Array(colors), 3));
	const m = new THREE.LineBasicMaterial({ vertexColors: true, transparent: true, opacity: 0.55, blending: THREE.AdditiveBlending, depthWrite: false });
	linkLines = new THREE.LineSegments(g, m);
	scene.add(linkLines);
}

// ── Legend ────────────────────────────────────────────────────────────────────
function buildLegend() {
	const buildRows = (container, onclick) => {
		container.innerHTML = '';
		for (const c of state.clusters) {
			if (!c.size) continue;
			const row = document.createElement('div');
			row.className = 'row';
			row.innerHTML = `<span class="swatch" style="background:${c.color};color:${c.color}"></span>` +
				`<span class="name">${escapeHtml(c.label)}</span><span class="cnt">${c.size}</span>`;
			row.addEventListener('click', () => { onclick?.(); toggleIsolate(c.id); });
			row.dataset.cluster = c.id;
			container.appendChild(row);
		}
	};
	buildRows(els.legendRows, null);
	if (els.legendMobileRows) buildRows(els.legendMobileRows, closeMobileLegend);

	const src = state.clusters.filter((c) => c.labelSource === 'granite').length;
	if (els.legendFoot) els.legendFoot.textContent = `${state.data.meta.clusterCount} themes · ${src} named by Granite. Click to isolate.`;
	els.legend.style.display = 'block';

	// Mobile toggle button — only shown when legend is CSS-hidden (<640px).
	if (els.legendToggle) els.legendToggle.style.display = '';
	if (els.legendMobile) { els.legendMobile.style.display = 'none'; els.legendMobile.hidden = true; }
}

function closeMobileLegend() {
	if (!els.legendMobile) return;
	els.legendMobile.style.display = 'none';
	els.legendMobile.hidden = true;
}

function toggleIsolate(clusterId) {
	stopTour();
	state.isolatedCluster = state.isolatedCluster === clusterId ? null : clusterId;
	if (state.searchActive) clearSearch();
	applyVisibility();
	// When isolating a theme, fly to its centroid so the user actually sees it.
	if (state.isolatedCluster !== null) {
		const c = state.clusters[clusterId];
		if (c) flyTo(new THREE.Vector3(c.x, c.y, c.z), 95);
	}
	[els.legendRows, els.legendMobileRows].forEach((container) => {
		if (!container) return;
		container.querySelectorAll('.row').forEach((row) => {
			const isMuted = state.isolatedCluster !== null && Number(row.dataset.cluster) !== state.isolatedCluster;
			row.classList.toggle('muted', isMuted);
		});
	});
}

// Recompute per-star dimming from isolation + search state.
function applyVisibility() {
	for (let i = 0; i < state.agents.length; i++) {
		const a = state.agents[i];
		let dim = 1;
		if (state.isolatedCluster !== null && a.cluster !== state.isolatedCluster) dim = 0.12;
		if (state.searchActive) dim = a._score != null ? 0.35 + 0.65 * scoreToBrightness(a._score) : 0.08;
		aDim[i] = dim;
	}
	geometry.attributes.aDim.needsUpdate = true;
}

function scoreToBrightness(score) {
	// Stretch the typical cosine range (~0.2–0.6) to 0–1 for visual contrast.
	return Math.max(0, Math.min(1, (score - 0.18) / 0.42));
}

// ── Guided tour ───────────────────────────────────────────────────────────────
// Hands-free fly-through of every Granite-named theme — great for an unattended
// demo loop. Each step isolates a theme, flies to its centroid, and surfaces its
// label; any user interaction stops it.
const tour = { active: false, i: 0, timer: 0 };
function toggleTour() { tour.active ? stopTour() : startTour(); }
function startTour() {
	const themed = state.clusters.filter((c) => c.size);
	if (themed.length < 2) return;
	if (state.searchActive) clearSearch();
	if (els.panel.classList.contains('open')) closePanel();
	tour.active = true; tour.i = 0;
	els.tourBtn.classList.add('active');
	flashHudHint('Guided tour — touring the themes Granite named. Interact to stop.');
	tourStep(themed);
	tour.timer = setInterval(() => tourStep(themed), 4800);
}
function tourStep(themed) {
	const c = themed[tour.i % themed.length];
	tour.i++;
	state.isolatedCluster = c.id;
	applyVisibility();
	[els.legendRows, els.legendMobileRows].forEach((ct) => ct?.querySelectorAll('.row').forEach((r) => r.classList.toggle('muted', Number(r.dataset.cluster) !== c.id)));
	flyTo(new THREE.Vector3(c.x, c.y, c.z), 95);
}
function stopTour() {
	if (!tour.active) return;
	tour.active = false;
	clearInterval(tour.timer);
	els.tourBtn.classList.remove('active');
	state.isolatedCluster = null;
	applyVisibility();
	[els.legendRows, els.legendMobileRows].forEach((ct) => ct?.querySelectorAll('.row').forEach((r) => r.classList.remove('muted')));
}

// ── Stats ─────────────────────────────────────────────────────────────────────
function buildStats() {
	const m = state.data.meta;
	const stat = (v, k, u = '') => `<div class="stat"><div class="v">${v}${u ? `<span class="u">${u}</span>` : ''}</div><div class="k">${k}</div></div>`;
	els.stats.innerHTML =
		stat(m.count, 'Agents') +
		stat(m.dims || '—', 'Granite dims') +
		stat(m.clusterCount, 'Themes') +
		stat('3D', 'Projection');
	els.stats.style.display = 'flex';
	els.stats.title = `Embedded with ${m.model} on IBM watsonx.ai`;
}

// ── Search ────────────────────────────────────────────────────────────────────
let searchTimer = 0;
function wireSearch() {
	els.searchInput.addEventListener('input', () => {
		els.searchClear.style.display = els.searchInput.value ? 'block' : 'none';
		clearTimeout(searchTimer);
		const q = els.searchInput.value.trim();
		if (!q) { clearSearch(); return; }
		searchTimer = setTimeout(() => runSearch(q), 420);
	});
	els.searchInput.addEventListener('keydown', (e) => {
		if (e.key === 'Enter') { clearTimeout(searchTimer); const q = els.searchInput.value.trim(); if (q) runSearch(q); }
		if (e.key === 'Escape') { els.searchInput.value = ''; clearSearch(); els.searchInput.blur(); }
	});
	els.searchClear.addEventListener('click', () => { els.searchInput.value = ''; els.searchClear.style.display = 'none'; clearSearch(); els.searchInput.focus(); });

	els.searchHint.innerHTML = EXAMPLES.map((e) => `<button class="chip">${escapeHtml(e)}</button>`).join('');
	els.searchHint.querySelectorAll('.chip').forEach((chip) => {
		chip.addEventListener('click', () => { els.searchInput.value = chip.textContent; els.searchClear.style.display = 'block'; runSearch(chip.textContent); });
	});
}

async function runSearch(query) {
	stopTour();
	setUrlParam('q', query);
	setUrlParam('agent', null);
	els.searchBox.classList.add('searching');
	try {
		const res = await fetch('/api/ibm/galaxy', {
			method: 'POST',
			headers: { 'content-type': 'application/json' },
			body: JSON.stringify({ query }),
		});
		if (!res.ok) throw new Error(`search ${res.status}`);
		const data = await res.json();
		applySearchResults(query, data);
	} catch (err) {
		log.error('[galaxy] search failed', err);
		els.results.innerHTML = `<div class="r-head"><span>Search unavailable right now.</span></div>`;
		els.results.classList.add('show');
	} finally {
		els.searchBox.classList.remove('searching');
	}
}

function applySearchResults(query, data) {
	state.searchActive = true;
	state.isolatedCluster = null;
	els.legendRows.querySelectorAll('.row').forEach((r) => r.classList.remove('muted'));
	const scores = new Map((data.results || []).map((r) => [r.id, r.score]));
	for (const a of state.agents) a._score = scores.has(a.id) ? scores.get(a.id) : null;
	applyVisibility();
	renderResults(query, data.results || []);

	// Clear all search highlights before applying the new best result.
	aHi.fill(0);
	state.selected = -1;
	geometry.attributes.aHi.needsUpdate = true;

	const best = data.best && state.byId.get(data.best.id);
	if (best) {
		const idx = state.agents.indexOf(best);
		flyTo(new THREE.Vector3(best.x, best.y, best.z), 64);
		if (idx >= 0) { aHi[idx] = 1; geometry.attributes.aHi.needsUpdate = true; }
	}
}

function renderResults(query, results) {
	if (!results.length) {
		els.results.innerHTML = `<div class="r-head"><span>No semantic matches for “${escapeHtml(query)}”.</span></div>`;
		els.results.classList.add('show');
		return;
	}
	const top = results.slice(0, 8);
	const rows = top.map((r, i) => {
		const a = state.byId.get(r.id);
		if (!a) return '';
		const pct = Math.round(scoreToBrightness(r.score) * 100);
		return `<div class="ritem${i === 0 ? ' active' : ''}" data-id="${escapeAttr(r.id)}">` +
			avatarMarkup(a, 'r-av') +
			`<span class="r-name">${escapeHtml(a.name)}</span>` +
			`<span class="r-bar"><i style="width:${pct}%"></i></span>` +
			`<span class="r-score">${Math.round(r.score * 100)}%</span></div>`;
	}).join('');
	els.results.innerHTML = `<div class="r-head"><span>Ranked by <b>Granite</b> semantic similarity</span><span>${results.length} matched</span></div>${rows}`;
	els.results.classList.add('show');
	els.results.querySelectorAll('.ritem').forEach((row) => {
		row.addEventListener('click', () => {
			const a = state.byId.get(row.dataset.id);
			if (a) selectAgent(state.agents.indexOf(a), true);
		});
	});
}

function clearSearch() {
	state.searchActive = false;
	for (const a of state.agents) a._score = null;
	els.results.classList.remove('show');
	applyVisibility();
	setUrlParam('q', null);
}

// ── Markup helpers ────────────────────────────────────────────────────────────
function avatarMarkup(a, cls) {
	if (a.image) return `<img class="${cls}" src="${escapeAttr(a.image)}" alt="" loading="lazy" data-fallback="element" data-fallback-class="${cls} placeholder" data-fallback-text="${escapeAttr((a.name[0] || '?').toUpperCase())}" />`;
	return `<div class="${cls} placeholder">${escapeHtml((a.name[0] || '?').toUpperCase())}</div>`;
}
function escapeHtml(s) { return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])); }
// Reflect view state into the URL so a selected agent / active search is a
// shareable link (no history spam — replaceState).
function setUrlParam(key, val) {
	try {
		const url = new URL(window.location.href);
		if (val == null || val === '') url.searchParams.delete(key);
		else url.searchParams.set(key, val);
		window.history.replaceState(null, '', url);
	} catch { /* older browsers without URL/replaceState — non-fatal */ }
}
function escapeAttr(s) { return escapeHtml(s); }
function hexA(hex, a) {
	const h = hex.replace('#', '');
	const n = parseInt(h.length === 3 ? h.split('').map((x) => x + x).join('') : h, 16);
	return `rgba(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255},${a})`;
}

// ── State machine for overlays ────────────────────────────────────────────────
function showOnly(el) {
	for (const o of [els.loading, els.empty, els.unavailable, els.error]) o.classList.toggle('show', o === el);
	const name = el === els.loading ? 'loading' : el === els.empty ? 'empty'
		: el === els.unavailable ? 'unavailable' : el === els.error ? 'error' : 'scene';
	document.body.dataset.galaxyState = name;
}
function setLoadStep(step) {
	els.loadSteps.querySelectorAll('.o-step').forEach((s) => {
		const n = Number(s.dataset.step);
		s.classList.toggle('done', n < step);
		s.classList.toggle('active', n === step);
	});
}

// ── Boot ──────────────────────────────────────────────────────────────────────
async function load() {
	showOnly(els.loading);
	setLoadStep(1); // request in flight → Granite is embedding + projecting server-side
	let data;
	try {
		const res = await fetch('/api/ibm/galaxy');
		if (!res.ok) throw new Error(`galaxy ${res.status}`);
		data = await res.json();
	} catch (err) {
		log.error('[galaxy] load failed', err);
		els.errorMsg.textContent = 'Something went wrong reaching the galaxy service. Check your connection and try again.';
		showOnly(els.error);
		return;
	}

	if (!data.available) {
		if (data.reason === 'watsonx_not_configured') {
			if (data.message) els.unavailableMsg.textContent = data.message;
			showOnly(els.unavailable);
		} else {
			showOnly(els.empty);
		}
		return;
	}
	if (!data.agents || data.agents.length < 2) {
		const reason = data.meta?.reason;
		els.emptyTitle.textContent = reason === 'too_few_agents' ? 'Not enough agents yet' : 'No agents to map yet';
		els.emptyMsg.textContent = reason === 'too_few_agents'
			? 'A galaxy needs at least a couple of public agents to map relationships. Create one and it joins the constellation.'
			: 'The galaxy lights up once public agents exist. Create one and it joins the constellation on the next rebuild.';
		showOnly(els.empty);
		return;
	}

	setLoadStep(3); // rendering
	state.data = data;
	state.clusters = data.clusters;
	state.agents = data.agents.map((a) => ({ ...a, color: data.clusters[a.cluster]?.color || '#78a9ff', _score: null }));
	state.byId = new Map(state.agents.map((a) => [a.id, a]));

	buildPoints();
	buildClusterLabels();
	buildLegend();
	buildStats();
	els.searchWrap.style.display = 'block';

	// Reveal the scene.
	showOnly(null);
	els.loading.classList.remove('show');
	flashHudHint(`Drag to orbit · scroll to zoom · click a star to explore · press <b>/</b> to search`);
	applyDeepLink();

	document.body.dataset.galaxyState = 'ready';
	// Read-only introspection handle for support/debugging a 3D scene that can't
	// be inspected from pixels alone (headless WebGL renders nothing screenshotable).
	window.__ibmGalaxy = {
		state,
		scene,
		camera,
		points: () => points,
		starCount: () => (points ? points.geometry.attributes.position.count : 0),
		rendererInfo: () => renderer.info.render,
		linkCount: () => (linkLines ? linkLines.geometry.attributes.position.count / 2 : 0),
		tourActive: () => tour.active,
	};
}

function flashHudHint(html) {
	els.hudHint.innerHTML = html;
	els.hudHint.classList.add('show');
	setTimeout(() => els.hudHint.classList.remove('show'), 6500);
}

// Honour a shareable URL: ?agent=<id> selects + flies to a star, ?q=<text>
// runs a semantic search. Lets a demo link open straight to the right view.
function applyDeepLink() {
	try {
		const params = new URLSearchParams(window.location.search);
		const agentId = params.get('agent');
		const q = params.get('q');
		if (agentId && state.byId.has(agentId)) {
			selectAgent(state.agents.indexOf(state.byId.get(agentId)), true);
		} else if (q) {
			els.searchInput.value = q;
			els.searchClear.style.display = 'block';
			runSearch(q);
		}
	} catch { /* malformed URL — ignore */ }
}

function onResize() {
	camera.aspect = window.innerWidth / window.innerHeight;
	camera.updateProjectionMatrix();
	renderer.setSize(window.innerWidth, window.innerHeight, false);
	if (material) material.uniforms.uPixelRatio.value = renderer.getPixelRatio();
}

function wireGlobalUI() {
	els.panelClose.addEventListener('click', closePanel);
	els.resetView.addEventListener('click', () => {
		stopTour(); resetView(); state.isolatedCluster = null;
		if (state.searchActive) clearSearch(); applyVisibility();
		[els.legendRows, els.legendMobileRows].forEach((c) => c?.querySelectorAll('.row').forEach((r) => r.classList.remove('muted')));
	});
	els.tourBtn.addEventListener('click', toggleTour);
	els.retryBtn.addEventListener('click', () => load());

	// Mobile legend toggle.
	if (els.legendToggle) {
		els.legendToggle.addEventListener('click', () => {
			if (!els.legendMobile) return;
			const open = !els.legendMobile.hidden;
			els.legendMobile.style.display = open ? 'none' : 'block';
			els.legendMobile.hidden = open;
		});
	}

	// Keyboard shortcuts overlay.
	const openShortcuts = () => { els.shortcutsOverlay.classList.add('show'); };
	const closeShortcuts = () => { els.shortcutsOverlay.classList.remove('show'); };
	if (els.shortcutsBtn) els.shortcutsBtn.addEventListener('click', openShortcuts);
	if (els.shortcutsClose) els.shortcutsClose.addEventListener('click', closeShortcuts);
	els.shortcutsOverlay?.addEventListener('click', (e) => { if (e.target === els.shortcutsOverlay) closeShortcuts(); });

	window.addEventListener('keydown', (e) => {
		const inInput = document.activeElement === els.searchInput;
		if (e.key === '/' && !inInput) { e.preventDefault(); els.searchInput.focus(); }
		else if (e.key === 'Escape') {
			if (els.shortcutsOverlay.classList.contains('show')) { closeShortcuts(); return; }
			if (els.legendMobile && !els.legendMobile.hidden) { closeMobileLegend(); return; }
			if (els.panel.classList.contains('open')) { closePanel(); return; }
			if (state.searchActive) { els.searchInput.value = ''; clearSearch(); return; }
		}
		else if ((e.key === 'r' || e.key === 'R') && !inInput) { els.resetView.click(); }
		else if ((e.key === 't' || e.key === 'T') && !inInput) toggleTour();
		else if (e.key === '?' && !inInput) openShortcuts();
	});
}

// WebGL capability guard — show the error state rather than a blank canvas.
function hasWebGL() {
	try {
		const c = document.createElement('canvas');
		return !!(window.WebGLRenderingContext && (c.getContext('webgl2') || c.getContext('webgl')));
	} catch { return false; }
}

if (!hasWebGL()) {
	els.errorMsg.textContent = 'This browser or device does not support WebGL, which the Agent Galaxy needs to render.';
	showOnly(els.error);
} else {
	initThree();
	wireSearch();
	wireGlobalUI();
	load();
}