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.

31.7 KB
Raw Blame
// WebXR immersive-ar session controller.
//
// Reuses the element's existing Three.js renderer by enabling XR mode on start
// and restoring the RAF loop on end. Hit-test places the agent on tap.
//
// Half-body XR mode (collapse lower-body bones) is opt-in via the `halfBody`
// constructor option — only the demo page under /demos/halfbody passes it.
// The live AR button on the main viewer enters XR with the full body, exactly
// as it did before the half-body work was added.

import {
	CanvasTexture, CircleGeometry, Color, Group, Matrix4, Mesh, MeshBasicMaterial,
	PlaneGeometry, Quaternion, RingGeometry, Vector3,
} from 'three';

import {
	advancePulse, isXrVisible, nextTrackingState, reticleVisual, TRACKING_LOSS_FRAMES,
} from '../../packages/ar-studio/src/studio/anchor-lifecycle.js';
import { DepthOcclusion } from '../../packages/ar-studio/src/studio/depth-occlusion.js';
import { createPinchState, pinchEnd, pinchMove, pinchStart, touchDist } from '../../packages/ar-studio/src/studio/pinch.js';

/** prefers-reduced-motion: calm, static reticle/confirm states when set. */
function _prefersReducedMotion() {
	try {
		return typeof window !== 'undefined'
			&& !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
	} catch {
		return false;
	}
}

const LOWER_BODY_FRAGMENTS = [
	'upleg', 'leg', 'thigh', 'knee', 'shin', 'calf',
	'foot', 'toe', 'ankle',
];

function _normalizeBone(name) {
	return String(name || '')
		.toLowerCase()
		.replace(/^mixamorig:?_?/, '')
		.replace(/^cc_base_/, '')
		.replace(/^armature[:_|]/, '')
		.replace(/^rig[:_]/, '');
}

function _isLowerBody(name) {
	const norm = _normalizeBone(name);
	return LOWER_BODY_FRAGMENTS.some((f) => norm.includes(f));
}

export class WebXRSession {
	/**
	 * @param {object} viewer  Object exposing { renderer, scene, content, controls,
	 *   activeCamera, animationManager, mixer, prevTime, _rafId, _afterAnimateHooks,
	 *   _needsRender, _updateRenderLoop } — see src/xr.js for the canonical shim.
	 * @param {object} [opts]
	 * @param {Function} [opts.onEnd]      Called after the XR session ends + restores.
	 * @param {boolean}  [opts.halfBody]   Collapse lower-body bones (demo mode).
	 * @param {Function} [opts.onAnchored] Called once on first tap with the anchored
	 *   local-space pose `{ position: Vector3, quaternion: Quaternion }` and a
	 *   `{ degraded }` flag (degraded = no real XRAnchor; placement may drift).
	 * @param {Function} [opts.onHit]      Called with `true`/`false` as the hit-test
	 *   reticle gains/loses a surface — drives the "point at the floor" searching state.
	 * @param {Function} [opts.onTracking] Called with `true`/`false` as the device
	 *   regains/loses its fix on the room — drives the "move to a brighter spot" hint.
	 * @param {Function} [opts.onVisibility] Called with `true`/`false` as the session
	 *   is foregrounded/backgrounded (lock, incoming call, app switch).
	 * @param {Element}  [opts.domOverlayRoot] Element to surface as the WebXR
	 *   `dom-overlay` root (in-session hint + exit affordance). Optional.
	 * @param {Function} [opts.onScale] Called with the new uniform scale as a
	 *   two-finger pinch resizes the agent (and once more with the settled value
	 *   when the pinch ends, flagged `{ final: true }`). Pinch-to-resize needs a
	 *   dom-overlay root (touches are only observable through it) — without one
	 *   the gesture is quietly unavailable, exactly as before.
	 */
	constructor(viewer, { onEnd, halfBody = false, onAnchored, onHit, onTracking, onVisibility, domOverlayRoot, onScale } = {}) {
		this._viewer = viewer;
		this._halfBody = halfBody;
		this._onEnd = onEnd;
		this._onAnchored = onAnchored;
		this._onHit = onHit;
		this._onTracking = onTracking;
		this._onVisibility = onVisibility;
		this._domOverlayRoot = domOverlayRoot ?? null;
		this._onScale = onScale;
		/** Pinch-to-resize state (pure math in ./pinch-scale.js). */
		this._pinch = createPinchState();
		/** Wall-clock of the last pinch end — a tap right after a pinch is the
		 * second finger lifting, not a placement intent. -Infinity means "never":
		 * 0 would swallow real taps while performance.now() is still under the
		 * 350ms suppression window (young clocks: fresh workers, tests). */
		this._pinchEndedAt = -Infinity;
		/** Content scale captured at session start, restored on exit. */
		this._savedScale = null;
		this._handleTouchStart = this._handleTouchStart.bind(this);
		this._handleTouchMove = this._handleTouchMove.bind(this);
		this._handleTouchEnd = this._handleTouchEnd.bind(this);
		this._handleBeforeSelect = this._handleBeforeSelect.bind(this);
		this._session = null;
		this._hitTestSource = null;
		this._localSpace = null;
		this._anchored = false;
		/** Tracking-health state machine (transition-only "lost"/"recovered"). */
		this._trackingState = { misses: 0, lost: false };
		/** True while the session is backgrounded/blurred — skips non-essential work. */
		this._paused = false;
		/** Idempotency latch so an OS-initiated end and our own end() can't double-clean. */
		this._ended = false;
		/** @type {XRAnchor|null} Real world anchor created on tap (feature-detected). */
		this._anchor = null;
		/** @type {DepthOcclusion|null} Real-world occluder; null unless the session
		 * negotiated depth-sensing (feature-detected after start). */
		this._depthOcclusion = null;
		/** @type {XRHitTestResult|null} Most recent hit, used to create the anchor. */
		this._latestHit = null;
		/** Tap-moment hit pose, captured for persistence the instant the user taps. */
		this._latestHitMatrix = new Matrix4();
		this._hasHit = false;
		/** True once any surface has been found — keeps the reticle visible (dim,
		 * "searching") through brief hit dropouts instead of flickering off. */
		this._hadHit = false;
		/** @type {import('three').Group|null} Reticle group (ring + inner dot). */
		this._reticle = null;
		/** @type {import('three').Mesh|null} */
		this._reticleRing = null;
		/** @type {import('three').Mesh|null} Inner dot that fills in on lock. */
		this._reticleDot = null;
		/** @type {import('three').Mesh|null} One-shot confirm "pulse-out" ring. */
		this._pulseRing = null;
		/** @type {import('three').Mesh|null} Soft contact shadow grounding the avatar. */
		this._shadow = null;
		/** @type {import('three').CanvasTexture|null} Radial-gradient shadow map. */
		this._shadowTex = null;
		/** Eased 0→1 reticle lock amount (searching → locked); lerped each frame. */
		this._hitAmount = 0;
		/** Reused reticle-visual buffer — no per-frame allocation. */
		this._rv = { scale: 1, opacity: 0.9, dot: 0, colorMix: 0 };
		/** Reused confirm-pulse state; `active` gates the one-shot animation. */
		this._pulse = { t: 0, scale: 1, opacity: 0, done: false, active: false };
		/** Searching/locked reticle colours, lerped into the ring material in place. */
		this._dimColor = new Color(0x7a6cf0);
		this._lockColor = new Color(0xc4b5fd);
		this._reducedMotion = false;
		this._userPosition = new Vector3();
		this._savedBg = null;
		this._savedPos = null;
		this._savedRot = null;
		/** @type {Array<{ bone: import('three').Bone, scale: Vector3 }>} */
		this._halfBodyBones = [];
		this._handleEnd = this._handleEnd.bind(this);
		this._handleSelect = this._handleSelect.bind(this);
		this._handleVisibilityChange = this._handleVisibilityChange.bind(this);
	}

	static async isSupported() {
		try {
			return !!(navigator.xr && (await navigator.xr.isSessionSupported('immersive-ar')));
		} catch {
			return false;
		}
	}

	async start() {
		const viewer = this._viewer;
		const renderer = viewer.renderer;

		// Must be set before requestSession
		renderer.xr.enabled = true;

		// `anchors` lets us bind the agent to a real XRAnchor (no drift); it is
		// optional so devices without it still run on hit-test-follow. `dom-overlay`
		// surfaces the in-session hint + exit affordance when a root is supplied.
		// `depth-sensing` (optional) unlocks real-world occlusion — the agent hides
		// behind couches/doorways/people; we prefer the gpu-optimized luminance-alpha
		// path three.js can turn into an occluder, and degrade silently otherwise.
		const sessionInit = {
			requiredFeatures: ['hit-test'],
			optionalFeatures: ['anchors', 'local-floor', 'depth-sensing'],
			depthSensing: {
				usagePreference: ['gpu-optimized', 'cpu-optimized'],
				dataFormatPreference: ['luminance-alpha', 'float32'],
			},
		};
		if (this._domOverlayRoot) {
			sessionInit.optionalFeatures.push('dom-overlay');
			sessionInit.domOverlay = { root: this._domOverlayRoot };
		}

		const session = await navigator.xr.requestSession('immersive-ar', sessionInit);
		this._session = session;
		// Fresh session: clear the lifecycle latches a prior run may have left set.
		this._ended = false;
		this._paused = false;
		this._trackingState = { misses: 0, lost: false };
		// An OS-initiated end (user locks the phone, takes a call, swipes the app
		// away) fires 'end' just like our exit button — both land in _handleEnd, so
		// restoration is identical and idempotent no matter who ended the session.
		session.addEventListener('end', this._handleEnd);
		// 'select' fires on controller trigger or screen tap
		session.addEventListener('select', this._handleSelect);
		// Backgrounding/blurring pauses non-essential work and surfaces a resume hint.
		session.addEventListener('visibilitychange', this._handleVisibilityChange);

		await renderer.xr.setSession(session);

		this._localSpace = await session.requestReferenceSpace('local');
		const viewerSpace = await session.requestReferenceSpace('viewer');
		this._hitTestSource = await session.requestHitTestSource({ space: viewerSpace });

		// Real-world occlusion: only stand up the depth path when the live session
		// actually negotiated `depth-sensing`. On every other device this stays null
		// and the tick never touches depth — identical pre-occlusion behavior.
		this._depthOcclusion = DepthOcclusion.sessionHasDepth(session)
			? new DepthOcclusion(renderer)
			: null;

		// Re-read the OS motion preference per session so a mid-use settings change
		// is honoured on the next entry; gates the reticle pulse and confirm beat.
		this._reducedMotion = _prefersReducedMotion();
		this._hadHit = false;
		this._hitAmount = 0;
		this._pulse.active = false;

		// Floor reticle — a thin ring laid flat (geometry rotated into the XZ plane
		// so the hit pose's up-normal keeps it on the surface). Hidden until a hit.
		// A soft contact shadow grounds the avatar; a pulse ring fires on commit.
		this._buildReticle();
		this._buildShadow();
		this._buildPulseRing();

		// Transparent background — device camera provides the pass-through
		this._savedBg = viewer.scene.background;
		viewer.scene.background = null;
		renderer.setClearColor(0x000000, 0);

		// Save agent content transform for clean restoration on exit
		const content = viewer.content;
		this._savedPos = content?.position.clone() ?? null;
		this._savedRot = content?.rotation.clone() ?? null;
		this._savedScale = content?.scale.clone() ?? null;

		// Pinch-to-resize rides the dom-overlay: during immersive-ar, screen touches
		// are only observable as DOM events on the overlay root. Two fingers resize
		// the agent; `beforexrselect` suppresses the placement tap while (and just
		// after) a pinch so the second finger can't accidentally place/anchor.
		if (this._domOverlayRoot) {
			const root = this._domOverlayRoot;
			root.addEventListener('touchstart', this._handleTouchStart, { passive: true });
			root.addEventListener('touchmove', this._handleTouchMove, { passive: true });
			root.addEventListener('touchend', this._handleTouchEnd, { passive: true });
			root.addEventListener('touchcancel', this._handleTouchEnd, { passive: true });
			root.addEventListener('beforexrselect', this._handleBeforeSelect);
		}

		// Half-body mode is opt-in. The live AR button never sets it; only the
		// /demos/halfbody preview passes halfBody:true.
		if (this._halfBody) this._enterHalfBody();

		// Hand the render loop to the XR system (replaces RAF)
		if (viewer._rafId !== null) {
			cancelAnimationFrame(viewer._rafId);
			viewer._rafId = null;
		}
		viewer.controls.enabled = false;

		renderer.setAnimationLoop((time, frame) => this._tick(time, frame));
	}

	_tick(time, frame) {
		const viewer = this._viewer;
		const renderer = viewer.renderer;

		const dt = viewer.prevTime ? (time - viewer.prevTime) / 1000 : 0.016;
		viewer.prevTime = time;

		// Paused (app backgrounded, incoming call, screen locked): hold the agent
		// still and skip animation, hit-testing, and tracking checks so nothing
		// drifts or burns cycles. Submit a frame so the compositor stays happy, then
		// wait for visibilitychange → resume. No work, no console noise.
		if (this._paused) {
			renderer.render(viewer.scene, viewer.activeCamera);
			return;
		}

		// Tracking health: a frame with no viewer pose means the device has lost its
		// fix on the room (low light, blank wall, fast motion). Run it through the
		// transition-only state machine so the host hears "lost"/"recovered" once,
		// not every frame, and hide the reticle the moment we're lost.
		if (frame && this._localSpace) {
			const hasPose = !!frame.getViewerPose(this._localSpace);
			const t = nextTrackingState(this._trackingState, hasPose, TRACKING_LOSS_FRAMES);
			this._trackingState = t.state;
			if (t.changed) this._setTracking(!t.lost);
		}

		if (viewer.mixer) viewer.mixer.update(dt);
		viewer.animationManager.update(dt);

		// Empathy layer and any other per-frame hooks continue uninterrupted
		if (viewer._afterAnimateHooks) {
			for (const hook of viewer._afterAnimateHooks) hook(dt);
		}

		// Track user head position from the XR camera — used by lookAt('user')
		const xrCam = renderer.xr.getCamera();
		if (xrCam) this._userPosition.setFromMatrixPosition(xrCam.matrixWorld);

		// Before anchoring: the reticle (and a content preview) track the floor the
		// phone is pointed at. After a tap, a real XRAnchor takes over (below).
		if (!this._anchored && frame && this._hitTestSource) {
			const hits = frame.getHitTestResults(this._hitTestSource);
			const pose = hits.length > 0 ? hits[0].getPose(this._localSpace) : null;
			if (pose) {
				this._latestHit = hits[0];
				this._latestHitMatrix.fromArray(pose.transform.matrix);
				this._hadHit = true;
				if (this._reticle) {
					this._reticle.visible = true;
					this._reticle.position.setFromMatrixPosition(this._latestHitMatrix);
					this._reticle.quaternion.setFromRotationMatrix(this._latestHitMatrix);
				}
				this._placeShadow(this._latestHitMatrix);
				if (viewer.content) {
					viewer.content.position.setFromMatrixPosition(this._latestHitMatrix);
				}
				this._setHit(true);
			} else {
				this._latestHit = null;
				// Don't blink the reticle off on a one-frame hit dropout: once a surface
				// has been seen, hold it at the last spot in the dim "searching" look
				// (driven by _hitAmount → 0) so re-acquiring reads as calm, not broken.
				// Only the very first sweep — before any hit — shows no reticle at all.
				// But never resurrect it while tracking is lost: _setTracking hid it this
				// same tick precisely so the user can't tap a stale reticle, and the hit
				// block must not undo that. Dropout-tolerance applies only when tracked.
				const keep = this._hadHit && !this._trackingState.lost;
				if (this._reticle) this._reticle.visible = keep;
				if (this._shadow) this._shadow.visible = keep;
				this._setHit(false);
			}
		}

		// Anchored: drive content from the live anchor pose every frame so it stays
		// glued to the real world as the camera moves (position only — the agent's
		// own orientation/scale are preserved). A null anchor (createAnchor missing)
		// leaves content frozen at the tap point — degraded hit-follow, never broken.
		if (this._anchor && frame) {
			const pose = frame.getPose(this._anchor.anchorSpace, this._localSpace);
			if (pose && viewer.content) {
				const p = pose.transform.position;
				viewer.content.position.set(p.x, p.y, p.z);
				if (this._shadow) this._shadow.position.set(p.x, p.y, p.z);
			}
		}

		// Reticle look (searching ↔ locked) + the one-shot confirm pulse-out ring.
		// Both read existing state into reused buffers, so no per-frame allocation.
		this._updateReticleVisual(time, dt);
		this._updatePulse(dt);

		// Configure the real-world occluder the first frame depth data is ready; a
		// no-op (single boolean check) on every frame after, and never present at
		// all when the session has no depth-sensing. Must run before the render so
		// three's depth quad writes real-world depth before the agent is rasterized.
		this._depthOcclusion?.update();

		renderer.render(viewer.scene, viewer.activeCamera);
	}

	// ── Pinch-to-resize ────────────────────────────────────────────────────────
	// Raw touch geometry → the pure pinch state machine → a uniform scale on the
	// content group (and its contact shadow, so the grounding grows with it).

	_handleTouchStart(e) {
		if (e.touches.length !== 2) return;
		const base = this._viewer.content?.scale?.x ?? 1;
		pinchStart(this._pinch, touchDist(e.touches), base);
	}

	_handleTouchMove(e) {
		if (!this._pinch.active || e.touches.length !== 2) return;
		const s = pinchMove(this._pinch, touchDist(e.touches));
		if (s == null) return;
		this._applyContentScale(s);
		this._onScale?.(s, { final: false });
	}

	_handleTouchEnd() {
		const s = pinchEnd(this._pinch);
		if (s == null) return;
		this._pinchEndedAt = performance.now();
		this._onScale?.(s, { final: true });
	}

	// While a pinch is live (or a beat after it ends), the tap must not place —
	// the "tap" is just the second finger. Cancels the upcoming XR select event.
	_handleBeforeSelect(e) {
		if (this._pinch.active || performance.now() - this._pinchEndedAt < 350) {
			e.preventDefault();
		}
	}

	_applyContentScale(s) {
		const content = this._viewer.content;
		if (!content) return;
		content.scale.setScalar(s);
		// The contact shadow grounds the agent — grow it with the body so a
		// statue-sized avatar doesn't stand on a coin-sized shadow.
		if (this._shadow) this._shadow.scale.setScalar(s);
	}

	// First tap anchors the agent at the current hit-test position. Creates a real
	// XRAnchor when the device supports it (survives the small tracking corrections
	// a raw hit pose does not); falls back to frozen hit-follow otherwise.
	async _handleSelect() {
		if (this._anchored || !this._latestHit) return;
		// Belt-and-braces with _handleBeforeSelect: some browsers deliver the select
		// anyway — a pinch (or its trailing finger-lift) is never a placement.
		if (this._pinch.active || performance.now() - this._pinchEndedAt < 350) return;
		this._anchored = true;
		// Capture the tap-moment pose now — before the anchor's own drift correction
		// nudges it — so the persisted GPS pin matches where the user actually tapped.
		const anchorPose = this._readAnchorPose();
		// The commit beat: a one-shot pulse-out ring from the tap point + a short
		// haptic tick. The reticle retires (the spot is taken); the contact shadow
		// stays to keep the agent grounded. Reduced motion drops the visual pulse but
		// keeps the haptic — the confirmation still lands, just calmly.
		this._fireConfirmPulse();
		try { navigator.vibrate?.(15); } catch {}
		if (this._reticle) this._reticle.visible = false;
		if (this._shadow) this._shadow.visible = true;
		this._setHit(false);
		try {
			this._anchor = (await this._latestHit.createAnchor?.()) ?? null;
		} catch {
			// Anchor creation can reject on devices that advertise but can't honour
			// the feature — fall back to the frozen tap pose rather than failing.
			this._anchor = null;
		}
		// Disclose a degraded placement: with no real XRAnchor the agent is frozen
		// at the tap pose and may drift. We still persist the pin; we just stop
		// pretending it's rock-solid so the host can say so honestly.
		this._onAnchored?.(anchorPose, { degraded: this._anchor === null });
	}

	// Build the floor reticle: a flat ring + an inner dot, both pre-rotated into the
	// XZ plane so the hit pose (Y = surface normal) lays them on the surface. The
	// group is oriented to the hit each frame; _updateReticleVisual animates the
	// searching↔locked look (dim/breathing → bright/filled) off the eased lock
	// amount, so this only establishes geometry — no per-frame branching here.
	_buildReticle() {
		const group = new Group();
		group.renderOrder = 999; // draw over the passthrough + agent
		group.visible = false;

		const ringGeo = new RingGeometry(0.08, 0.11, 40).rotateX(-Math.PI / 2);
		const ringMat = new MeshBasicMaterial({
			color: this._dimColor.clone(), transparent: true, opacity: 0.6, depthTest: false,
		});
		const ring = new Mesh(ringGeo, ringMat);
		ring.renderOrder = 999;

		// Inner dot: invisible while searching, fades in as the surface locks so
		// "ready to place" reads at a glance. Lifted a hair so it never z-fights the
		// ring on the exact same plane.
		const dotGeo = new CircleGeometry(0.032, 32).rotateX(-Math.PI / 2).translate(0, 0.001, 0);
		const dotMat = new MeshBasicMaterial({
			color: this._lockColor.clone(), transparent: true, opacity: 0, depthTest: false,
		});
		const dot = new Mesh(dotGeo, dotMat);
		dot.renderOrder = 1000;

		group.add(ring, dot);
		this._reticle = group;
		this._reticleRing = ring;
		this._reticleDot = dot;
		this._viewer.scene.add(group);
	}

	// Soft contact shadow — a single transparent plane with a radial-gradient map
	// (no real shadow map). Grounds the avatar so it sits *on* the floor instead of
	// floating; follows the reticle pre-tap and the anchor after. Lifted a few mm
	// along the surface normal so it never z-fights the real floor that the depth
	// occluder stamps — which also makes it correctly hidden by closer real geometry.
	_buildShadow() {
		const size = 128;
		let tex = null;
		try {
			const cnv = document.createElement('canvas');
			cnv.width = cnv.height = size;
			const ctx = cnv.getContext('2d');
			const g = ctx.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
			g.addColorStop(0, 'rgba(0,0,0,0.42)');
			g.addColorStop(0.55, 'rgba(0,0,0,0.20)');
			g.addColorStop(1, 'rgba(0,0,0,0)');
			ctx.fillStyle = g;
			ctx.fillRect(0, 0, size, size);
			tex = new CanvasTexture(cnv);
		} catch {
			tex = null; // no DOM canvas (shouldn't happen in-session) → tinted disc fallback
		}
		const geo = new PlaneGeometry(0.6, 0.6).rotateX(-Math.PI / 2).translate(0, 0.004, 0);
		const mat = new MeshBasicMaterial({
			map: tex, color: tex ? 0xffffff : 0x000000, transparent: true,
			opacity: 0.9, depthWrite: false,
		});
		const mesh = new Mesh(geo, mat);
		mesh.renderOrder = 1; // beneath the reticle, above the passthrough
		mesh.visible = false;
		this._shadow = mesh;
		this._shadowTex = tex;
		this._viewer.scene.add(mesh);
	}

	// One-shot "pulse-out" ring fired on a successful anchor (the visible half of
	// the confirm beat). Separate from the reticle so it can keep animating after
	// the reticle retires. Hidden until _fireConfirmPulse arms it.
	_buildPulseRing() {
		const geo = new RingGeometry(0.10, 0.13, 40).rotateX(-Math.PI / 2);
		const mat = new MeshBasicMaterial({
			color: this._lockColor.clone(), transparent: true, opacity: 0, depthTest: false,
		});
		const ring = new Mesh(geo, mat);
		ring.renderOrder = 1001; // above the reticle
		ring.visible = false;
		this._pulseRing = ring;
		this._viewer.scene.add(ring);
	}

	// Lay the contact shadow flat on a hit (or anchor) pose and reveal it.
	_placeShadow(matrix) {
		if (!this._shadow) return;
		this._shadow.position.setFromMatrixPosition(matrix);
		this._shadow.quaternion.setFromRotationMatrix(matrix);
		this._shadow.visible = true;
	}

	// Arm the confirm pulse at the tap point. Reduced motion skips the visual beat
	// (the haptic + ✓ copy still confirm); otherwise the ring expands and fades via
	// _updatePulse. No allocation — the pulse state object is reused.
	_fireConfirmPulse() {
		if (this._reducedMotion || !this._pulseRing) return;
		this._pulseRing.position.setFromMatrixPosition(this._latestHitMatrix);
		this._pulseRing.quaternion.setFromRotationMatrix(this._latestHitMatrix);
		this._pulse.t = 0;
		this._pulse.active = true;
		this._pulseRing.visible = true;
	}

	// Per-frame reticle look. Eases the lock amount toward the live hit state and
	// maps it (+ a slow breathing phase) to scale/opacity/dot/colour via the pure,
	// unit-tested reticleVisual(). Writes straight onto materials with a reused
	// buffer and in-place colour lerp — zero per-frame allocation.
	_updateReticleVisual(time, dt) {
		const group = this._reticle;
		if (!group || !group.visible) return;
		const target = this._hasHit ? 1 : 0;
		// Snap toward lock a touch faster than it relaxes toward searching, so the
		// "locked" beat feels crisp while losing the surface feels gentle.
		const rate = Math.min(1, dt * (target > this._hitAmount ? 16 : 9));
		this._hitAmount += (target - this._hitAmount) * rate;
		const breathe = this._reducedMotion ? 0 : Math.sin(time * 0.0019) * 0.5 + 0.5;
		reticleVisual(this._rv, this._hitAmount, breathe, this._reducedMotion);
		group.scale.setScalar(this._rv.scale);
		const ringMat = this._reticleRing.material;
		ringMat.opacity = this._rv.opacity;
		ringMat.color.lerpColors(this._dimColor, this._lockColor, this._rv.colorMix);
		this._reticleDot.material.opacity = this._rv.dot * 0.95;
	}

	// Advance the one-shot confirm pulse, if armed. Expands + fades the ring via the
	// pure advancePulse(), then retires it. No-op (and no allocation) once done.
	_updatePulse(dt) {
		if (!this._pulse.active || !this._pulseRing) return;
		advancePulse(this._pulse, dt);
		this._pulseRing.scale.setScalar(this._pulse.scale);
		this._pulseRing.material.opacity = this._pulse.opacity;
		if (this._pulse.done) {
			this._pulse.active = false;
			this._pulseRing.visible = false;
		}
	}

	_disposeReticle() {
		if (!this._reticle) return;
		this._viewer.scene.remove(this._reticle);
		for (const child of [this._reticleRing, this._reticleDot]) {
			child?.geometry?.dispose();
			child?.material?.dispose();
		}
		this._reticle = null;
		this._reticleRing = null;
		this._reticleDot = null;
	}

	_disposeShadow() {
		if (this._shadow) {
			this._viewer.scene.remove(this._shadow);
			this._shadow.geometry?.dispose();
			this._shadow.material?.dispose();
			this._shadow = null;
		}
		this._shadowTex?.dispose();
		this._shadowTex = null;
	}

	_disposePulseRing() {
		if (!this._pulseRing) return;
		this._viewer.scene.remove(this._pulseRing);
		this._pulseRing.geometry?.dispose();
		this._pulseRing.material?.dispose();
		this._pulseRing = null;
		this._pulse.active = false;
	}

	// Notify the host only on transitions (searching ↔ surface found), not per frame.
	_setHit(has) {
		if (has === this._hasHit) return;
		this._hasHit = has;
		this._onHit?.(has);
	}

	// Tracking lost/recovered. On loss, hide the reticle (and its contact shadow)
	// so the user never taps a stale one; the host surfaces a recoverable "move to a
	// brighter spot" hint. A returning surface re-shows both on the next hit frame.
	_setTracking(ok) {
		if (!ok) {
			if (this._reticle) this._reticle.visible = false;
			if (!this._anchored && this._shadow) this._shadow.visible = false;
		}
		this._onTracking?.(ok);
	}

	// Foreground/background transition. Pause non-essential work while hidden and
	// hand the host a hint; resume cleanly when foregrounded. An OS that ends the
	// session instead of merely hiding it lands in _handleEnd, not here.
	_handleVisibilityChange() {
		const visible = isXrVisible(this._session?.visibilityState);
		this._paused = !visible;
		if (!visible) {
			if (this._reticle) this._reticle.visible = false;
			if (!this._anchored && this._shadow) this._shadow.visible = false;
		}
		this._onVisibility?.(visible);
	}

	// Decompose the captured tap-moment hit matrix into a local-space pose the host
	// converts to a GPS pin (metres from the session origin → lat/lng + floor height).
	_readAnchorPose() {
		const position = new Vector3();
		const quaternion = new Quaternion();
		const scale = new Vector3();
		this._latestHitMatrix.decompose(position, quaternion, scale);
		return { position, quaternion };
	}

	// Returns the current XR camera (user head) position for lookAt('user')
	getUserPosition() {
		return this._userPosition.clone();
	}

	async end() {
		if (this._session) {
			try {
				await this._session.end();
			} catch {}
			// _handleEnd fires from the 'end' event
		}
	}

	_handleEnd() {
		// Idempotent: the 'end' event and a direct end() can both reach here, and an
		// OS-initiated end must restore exactly once — same path as the exit button.
		if (this._ended) return;
		this._ended = true;

		const viewer = this._viewer;
		const renderer = viewer.renderer;

		// Stop listening before tearing down so a late visibilitychange during
		// teardown can't re-pause a session that's already gone.
		this._session?.removeEventListener('visibilitychange', this._handleVisibilityChange);
		if (this._domOverlayRoot) {
			const root = this._domOverlayRoot;
			root.removeEventListener('touchstart', this._handleTouchStart);
			root.removeEventListener('touchmove', this._handleTouchMove);
			root.removeEventListener('touchend', this._handleTouchEnd);
			root.removeEventListener('touchcancel', this._handleTouchEnd);
			root.removeEventListener('beforexrselect', this._handleBeforeSelect);
		}
		this._pinch = createPinchState();
		this._pinchEndedAt = -Infinity;

		renderer.setAnimationLoop(null);
		renderer.xr.enabled = false;

		if (this._hitTestSource) {
			try {
				this._hitTestSource.cancel();
			} catch {}
			this._hitTestSource = null;
		}
		this._disposeReticle();
		this._disposeShadow();
		this._disposePulseRing();
		// Detach + free the depth occluder (no-op when it was never attached).
		this._depthOcclusion?.dispose();
		this._depthOcclusion = null;
		this._session = null;
		this._anchored = false;
		this._anchor = null;
		this._latestHit = null;
		this._hasHit = false;
		this._hadHit = false;
		this._hitAmount = 0;
		this._paused = false;
		this._trackingState = { misses: 0, lost: false };

		// Restore background
		viewer.scene.background = this._savedBg;
		renderer.setClearColor(0x000000, 1);

		// Restore agent content to its pre-AR transform (a pinch-resized scale is
		// persisted on the pin, not carried back into the non-AR view).
		if (viewer.content && this._savedPos) viewer.content.position.copy(this._savedPos);
		if (viewer.content && this._savedRot) viewer.content.rotation.copy(this._savedRot);
		if (viewer.content && this._savedScale) viewer.content.scale.copy(this._savedScale);

		// Restore full-body bone scales captured at XR start (no-op when halfBody
		// mode was never entered — _halfBodyBones is empty).
		this._exitHalfBody();

		viewer.controls.enabled = true;
		viewer._needsRender = true;
		viewer._updateRenderLoop();

		this._onEnd?.();
	}

	// ── Half-body mode ────────────────────────────────────────────────────────

	_enterHalfBody() {
		const content = this._viewer.content;
		if (!content) return;
		this._halfBodyBones = [];

		content.traverse((obj) => {
			if (!obj.isSkinnedMesh || !obj.skeleton) return;
			for (const bone of obj.skeleton.bones || []) {
				if (!_isLowerBody(bone.name)) continue;
				// Each bone may appear in multiple meshes; only record it once.
				if (this._halfBodyBones.some((b) => b.bone === bone)) continue;
				this._halfBodyBones.push({ bone, scale: bone.scale.clone() });
				bone.scale.set(0.0001, 0.0001, 0.0001);
			}
		});
		// Skeleton matrices need a fresh update so the zero-scale propagates
		// to every dependent vertex on the next render.
		content.traverse((obj) => {
			if (obj.isSkinnedMesh && obj.skeleton) obj.skeleton.update();
		});
	}

	_exitHalfBody() {
		for (const { bone, scale } of this._halfBodyBones) {
			bone.scale.copy(scale);
		}
		this._halfBodyBones = [];
		const content = this._viewer.content;
		if (content) {
			content.traverse((obj) => {
				if (obj.isSkinnedMesh && obj.skeleton) obj.skeleton.update();
			});
		}
	}
}