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.

10.3 KB
Raw Blame
/**
 * Hotspot Tour Widget — clickable points-of-interest layered over a 3D scene.
 *
 * Each hotspot is a `{ id, label, position: [x,y,z], body? }` from the widget
 * config. We render a numbered marker at the projected screen position of
 * every hotspot, update those positions per frame (so they track the camera),
 * and on click tween the camera toward the marker while a side panel reveals
 * the body text.
 *
 * Brand config (background, autoRotate, rotationSpeed, env) is applied by
 * app.js _applyWidgetConfig before this runs. We respect autoRotate but flip
 * it off while a hotspot is selected so the framing stays put.
 */

import { Vector3 } from 'three';

const POLL_INTERVAL_MS = 100;
const POLL_MAX_MS = 8000;
const FOCUS_DURATION_MS = 700;

/**
 * @param {import('../viewer.js').Viewer} viewer
 * @param {object} config  Hotspot-tour config (see widget-types.js).
 * @param {HTMLElement} container  Root container (usually document.body).
 * @param {{ onOpen?: (hotspot: object) => void }} [ctx]  Optional hooks; `onOpen`
 *   fires every time the visitor activates a marker (used by app.js to forward
 *   `widget:hotspot:open` to the host page).
 * @returns {Promise<{ destroy: () => void }>}
 */
export async function mountHotspotTour(viewer, config, container, ctx) {
	const hotspots = Array.isArray(config.hotspots) ? config.hotspots : [];
	const onOpen = typeof ctx?.onOpen === 'function' ? ctx.onOpen : null;
	const state = {
		destroyed: false,
		layer: null,
		panel: null,
		markers: [],
		tickHook: null,
		resizeHandler: null,
		selectedId: null,
		autoRotateBefore: viewer?.controls?.autoRotate || false,
		_proj: new Vector3(),
	};

	await _waitForReady(viewer);
	if (state.destroyed) return _controller(state);

	_injectStyles();
	state.layer = _renderLayer(container);
	state.panel = _renderPanel(container, () => _clearSelection(viewer, state));

	for (const h of hotspots) {
		if (!h || !Array.isArray(h.position) || h.position.length !== 3) continue;
		const marker = _renderMarker(state.layer, h, state.markers.length + 1, () => {
			_select(viewer, state, h);
			onOpen?.(h);
		});
		state.markers.push({ data: h, el: marker, world: new Vector3(...h.position) });
	}

	_updatePositions(viewer, state);

	state.tickHook = () => {
		if (state.destroyed) return;
		_updatePositions(viewer, state);
	};
	if (!viewer._afterAnimateHooks) viewer._afterAnimateHooks = [];
	viewer._afterAnimateHooks.push(state.tickHook);

	state.resizeHandler = () => _updatePositions(viewer, state);
	window.addEventListener('resize', state.resizeHandler);

	return _controller(state, () => {
		state.destroyed = true;
		if (state.tickHook && viewer._afterAnimateHooks) {
			const idx = viewer._afterAnimateHooks.indexOf(state.tickHook);
			if (idx !== -1) viewer._afterAnimateHooks.splice(idx, 1);
		}
		if (state.resizeHandler) {
			window.removeEventListener('resize', state.resizeHandler);
		}
		state.layer?.remove();
		state.panel?.remove();
		if (viewer?.controls) viewer.controls.autoRotate = state.autoRotateBefore;
	});
}

// ─── helpers ──────────────────────────────────────────────────────────────

function _controller(state, destroyFn) {
	return {
		destroy:
			destroyFn ||
			(() => {
				state.destroyed = true;
			}),
	};
}

function _waitForReady(viewer) {
	return new Promise((resolve) => {
		const started = Date.now();
		const poll = () => {
			if (viewer?.content && viewer.defaultCamera && viewer.controls) return resolve();
			if (Date.now() - started > POLL_MAX_MS) return resolve();
			setTimeout(poll, POLL_INTERVAL_MS);
		};
		poll();
	});
}

function _renderLayer(container) {
	const el = document.createElement('div');
	el.className = 'hotspot-layer';
	container.appendChild(el);
	return el;
}

function _renderMarker(layer, hotspot, ordinal, onClick) {
	const btn = document.createElement('button');
	btn.type = 'button';
	btn.className = 'hotspot-marker';
	btn.setAttribute('data-id', hotspot.id);
	btn.setAttribute('aria-label', hotspot.label);
	btn.title = hotspot.label;
	btn.innerHTML = `<span class="hotspot-marker-dot">${ordinal}</span><span class="hotspot-marker-label">${_escape(hotspot.label)}</span>`;
	btn.addEventListener('click', onClick);
	layer.appendChild(btn);
	return btn;
}

function _renderPanel(container, onClose) {
	const panel = document.createElement('aside');
	panel.className = 'hotspot-panel';
	panel.hidden = true;
	panel.innerHTML = `
		<button type="button" class="hotspot-panel-close" aria-label="Close">×</button>
		<h3 class="hotspot-panel-title"></h3>
		<p class="hotspot-panel-body"></p>
	`;
	panel.querySelector('.hotspot-panel-close').addEventListener('click', onClose);
	container.appendChild(panel);
	return panel;
}

function _select(viewer, state, hotspot) {
	state.selectedId = hotspot.id;

	if (viewer?.controls) viewer.controls.autoRotate = false;

	const target = new Vector3(...hotspot.position);
	const camPos = _focusPosition(viewer, target);
	if (typeof viewer._tweenCamera === 'function') {
		viewer._tweenCamera(camPos, target, FOCUS_DURATION_MS);
	} else if (viewer?.controls) {
		viewer.defaultCamera.position.copy(camPos);
		viewer.controls.target.copy(target);
		viewer.controls.update();
		viewer.invalidate?.();
	}

	state.panel.hidden = false;
	state.panel.querySelector('.hotspot-panel-title').textContent = hotspot.label;
	state.panel.querySelector('.hotspot-panel-body').textContent = hotspot.body || '';

	for (const m of state.markers) {
		m.el.classList.toggle('is-active', m.data.id === hotspot.id);
	}
}

function _clearSelection(viewer, state) {
	state.selectedId = null;
	state.panel.hidden = true;
	for (const m of state.markers) m.el.classList.remove('is-active');
	if (viewer?.controls) viewer.controls.autoRotate = state.autoRotateBefore;
}

// Pull the camera back along the line from the model centre through the
// hotspot, so the hotspot ends up roughly framed in the middle of the canvas.
function _focusPosition(viewer, hotspotPos) {
	const cam = viewer.defaultCamera;
	const center = viewer.controls?.target?.clone() || new Vector3();
	const dir = hotspotPos.clone().sub(center);
	const distFromCenter = Math.max(0.001, dir.length());
	dir.normalize();
	const camDist = cam.position.distanceTo(center);
	// Sit behind the hotspot at roughly the same orbit radius the user already had.
	return hotspotPos.clone().add(dir.multiplyScalar(Math.max(camDist - distFromCenter, 0.5)));
}

function _updatePositions(viewer, state) {
	if (!viewer?.defaultCamera || !viewer.renderer) return;
	const canvas = viewer.renderer.domElement;
	const rect = canvas.getBoundingClientRect();
	const cam = viewer.defaultCamera;

	for (const m of state.markers) {
		state._proj.copy(m.world).project(cam);
		const x = (state._proj.x * 0.5 + 0.5) * rect.width + rect.left;
		const y = (-state._proj.y * 0.5 + 0.5) * rect.height + rect.top;
		const inFront = state._proj.z < 1 && state._proj.z > -1;
		const inFrame =
			state._proj.x >= -1.05 &&
			state._proj.x <= 1.05 &&
			state._proj.y >= -1.05 &&
			state._proj.y <= 1.05;
		if (inFront && inFrame) {
			m.el.style.display = '';
			m.el.style.transform = `translate(${x}px, ${y}px)`;
		} else {
			m.el.style.display = 'none';
		}
	}
}

function _escape(s) {
	return String(s ?? '').replace(
		/[&<>"']/g,
		(c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
	);
}

let _stylesInjected = false;
function _injectStyles() {
	if (_stylesInjected) return;
	_stylesInjected = true;
	const style = document.createElement('style');
	style.textContent = `
		.hotspot-layer {
			position: fixed;
			inset: 0;
			pointer-events: none;
			z-index: 4;
		}
		.hotspot-marker {
			position: absolute;
			top: 0;
			left: 0;
			transform: translate(-9999px, -9999px);
			margin: -22px 0 0 -22px;
			background: rgba(10, 10, 10, 0.7);
			color: #fff;
			border: 1px solid rgba(255, 255, 255, 0.18);
			border-radius: 999px;
			padding: 0 12px 0 0;
			font: 500 13px/1 Inter, system-ui, sans-serif;
			display: inline-flex;
			align-items: center;
			gap: 8px;
			cursor: pointer;
			pointer-events: auto;
			backdrop-filter: blur(8px);
			box-shadow: 0 4px 14px rgba(0, 0, 0, 0.35);
			transition: background-color 120ms ease, transform 60ms linear;
			max-width: 220px;
			white-space: nowrap;
			overflow: hidden;
			min-height: 44px;
		}
		.hotspot-marker:hover,
		.hotspot-marker.is-active {
			background: rgba(255, 255, 255, 0.85);
			border-color: rgba(255, 255, 255, 0.4);
		}
		.hotspot-marker-dot {
			display: grid;
			place-items: center;
			width: 44px;
			height: 44px;
			border-radius: 999px;
			background: rgba(255, 255, 255, 0.9);
			color: #fff;
			font-weight: 600;
			font-size: 13px;
			flex: 0 0 auto;
		}
		.hotspot-marker.is-active .hotspot-marker-dot {
			background: #fff;
			color: #ffffff;
		}
		.hotspot-marker-label {
			text-overflow: ellipsis;
			overflow: hidden;
		}
		.hotspot-panel {
			position: fixed;
			right: 16px;
			top: 16px;
			width: 280px;
			max-height: calc(100dvh - 32px);
			background: rgba(10, 10, 10, 0.88);
			color: #e0e0e0;
			border: 1px solid rgba(255, 255, 255, 0.08);
			border-radius: 12px;
			padding: 16px 18px 18px;
			z-index: 6;
			font: 14px/1.5 Inter, system-ui, sans-serif;
			backdrop-filter: blur(12px);
			box-shadow: 0 8px 32px rgba(0, 0, 0, 0.45);
		}
		.hotspot-panel[hidden] { display: none; }
		.hotspot-panel-close {
			position: absolute;
			top: 0;
			right: 0;
			width: 44px;
			height: 44px;
			display: flex;
			align-items: center;
			justify-content: center;
			background: transparent;
			border: 0;
			color: rgba(255, 255, 255, 0.6);
			font-size: 22px;
			line-height: 1;
			cursor: pointer;
			border-radius: 0 12px 0 8px;
		}
		.hotspot-panel-close:hover { color: #fff; background: rgba(255,255,255,0.06); }
		.hotspot-panel-title {
			margin: 0 44px 8px 0;
			font-size: 15px;
			font-weight: 600;
			color: #fff;
		}
		.hotspot-panel-body {
			margin: 0;
			color: rgba(255, 255, 255, 0.78);
			white-space: pre-wrap;
		}
		@media (max-width: 520px) {
			.hotspot-panel {
				right: 8px;
				left: 8px;
				top: auto;
				bottom: max(8px, env(safe-area-inset-bottom, 8px));
				width: auto;
				max-height: 40dvh;
				overflow-y: auto;
				padding-bottom: max(18px, env(safe-area-inset-bottom, 18px));
			}
			.hotspot-marker { max-width: 160px; }
		}
	`;
	document.head.appendChild(style);
}