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.

12.0 KB
Raw Blame
// Pure floor-anchor math (src/irl/floor-anchor.js).
//
// The contract these tests pin is the WebXR write path: when you tap to place an
// agent on the floor, the anchored local pose must convert to a GPS pin that
// reloads where you tapped — for you and for every other viewer. A sign error
// here (the classic: storing +z as north instead of −z) ships silently and lands
// every saved anchor on the wrong side of the room. So we assert the projection
// round-trips through room-anchor's geoToLocal, the yaw extraction is right at
// every cardinal, and height/source ride through untouched. Pure math, no DOM /
// Three.js / clock — mirrors tests/irl-room-anchor.test.js.

import { describe, it, expect } from 'vitest';

import { yawDegFromQuat, anchorPoseToPin, roomRelFromGeo, roomPlacementFromHit } from '../src/irl/floor-anchor.js';
import { geoToLocal, agentWorldPosition, roomOriginWorld } from '../src/irl/room-anchor.js';

const ORIGIN = { lat: 37.7749, lng: -122.4194 }; // arbitrary; math is origin-relative
const near = (a, b, eps = 1e-6) => Math.abs(a - b) <= eps;

// A yaw about world-Y by `deg` degrees, encoded as a quaternion [x,y,z,w].
// yawDegFromQuat reads the same clockwise-from-−Z convention savePin stores, so a
// quaternion built as a +Y rotation of θ must read back as θ.
const yawQuat = (deg) => {
	const half = (deg * Math.PI) / 180 / 2;
	return [0, Math.sin(half), 0, Math.cos(half)];
};

describe('yawDegFromQuat', () => {
	it('the identity quaternion is 0° yaw', () => {
		expect(yawDegFromQuat(0, 0, 0, 1)).toBe(0);
	});

	it('cardinal yaw quaternions read back as 90 / 180 / 270', () => {
		expect(near(yawDegFromQuat(...yawQuat(90)), 90)).toBe(true);
		expect(near(Math.abs(yawDegFromQuat(...yawQuat(180))), 180)).toBe(true); // ±180 are the same heading
		// 270° comes back as −90° in the raw atan2 range; the persist path normalises it.
		expect(near(yawDegFromQuat(...yawQuat(270)), -90)).toBe(true);
	});

	it('a wider sweep round-trips through anchorPoseToPin into [0,360)', () => {
		for (const deg of [0, 45, 90, 135, 180, 225, 270, 315, 359]) {
			const { heading } = anchorPoseToPin({
				originLat: ORIGIN.lat, originLng: ORIGIN.lng,
				x: 0, y: 0, z: 0, quat: yawQuat(deg),
			});
			expect(heading).toBeGreaterThanOrEqual(0);
			expect(heading).toBeLessThan(360);
			expect(near(heading, deg, 1)).toBe(true); // rounded to whole degrees
		}
	});
});

describe('anchorPoseToPin', () => {
	const QUAT = yawQuat(0);

	it('a pose +2 m east / +3 m north of the origin round-trips back to (2, 3)', () => {
		// Local frame: +X = east, world north = −Z, so 3 m north is z = −3.
		const pin = anchorPoseToPin({
			originLat: ORIGIN.lat, originLng: ORIGIN.lng,
			x: 2, y: 0, z: -3, quat: QUAT,
		});
		const back = geoToLocal(ORIGIN.lat, ORIGIN.lng, pin.lat, pin.lng);
		expect(near(back.east, 2, 1e-3)).toBe(true);
		expect(near(back.north, 3, 1e-3)).toBe(true);
	});

	it('the sign of z is north-negated (catches the +z mistake)', () => {
		// Walking the agent to +z (south) must DECREASE latitude, not increase it.
		const south = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 0, y: 0, z: 5, quat: QUAT });
		const north = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 0, y: 0, z: -5, quat: QUAT });
		expect(south.lat).toBeLessThan(ORIGIN.lat);
		expect(north.lat).toBeGreaterThan(ORIGIN.lat);
		// +x is east → longitude increases.
		const east = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 5, y: 0, z: 0, quat: QUAT });
		expect(east.lng).toBeGreaterThan(ORIGIN.lng);
	});

	it('heightM passes through unchanged (negative = below eye level)', () => {
		const below = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 0, y: -1.4, z: 0, quat: QUAT });
		expect(below.heightM).toBe(-1.4);
		const above = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 0, y: 0.6, z: 0, quat: QUAT });
		expect(above.heightM).toBe(0.6);
	});

	it('quat passes through untouched and source is webxr', () => {
		const q = yawQuat(47);
		const pin = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 1, y: 0, z: 1, quat: q });
		expect(pin.quat).toBe(q);
		expect(pin.source).toBe('webxr');
	});
});

// ── Render-back yaw precision (irl-floor-anchor task 02) ─────────────────────
// The viewer derives facing from the stored anchor_quat (full float) rather than
// the rounded anchor_yaw_deg, so a non-axis placement reloads at the EXACT tap
// angle for every viewer. These tests pin that the float survives the persist →
// render-back round-trip — the justification for keeping anchor_quat a live column
// instead of a dead field. pinYawRad in src/irl.js applies this same
// yawDegFromQuat(...pin.anchor_quat) on the read path.
describe('anchor_quat precision survives the persist → render-back round-trip', () => {
	// What the renderer does with a stored pin: read yaw straight off anchor_quat,
	// normalised to [0,360) exactly as pinYawRad / spawnNearbyPin reads it back.
	const renderBackYaw = (quat) => (((yawDegFromQuat(...quat) % 360) + 360) % 360);

	it('a fractional, non-axis yaw (137.4°) reloads within <0.5°', () => {
		const TAP = 137.4; // deliberately off every cardinal AND not a whole degree
		const pin = anchorPoseToPin({
			originLat: ORIGIN.lat, originLng: ORIGIN.lng,
			x: 0, y: 0, z: 0, quat: yawQuat(TAP),
		});
		// The render-back source (anchor_quat) keeps the fractional angle…
		expect(Math.abs(renderBackYaw(pin.quat) - TAP)).toBeLessThan(0.5);
		// …while the rounded heading column has already discarded the .4° tail. This
		// gap is the whole reason render-back prefers the quat.
		expect(pin.heading).toBe(137);
		expect(Math.abs(pin.heading - TAP)).toBeGreaterThan(0.3);
	});

	it('a fine sweep of off-axis tap angles each reload within <0.5°', () => {
		for (const TAP of [12.7, 47.6, 99.1, 137.4, 211.95, 268.3, 314.85, 359.6]) {
			const pin = anchorPoseToPin({
				originLat: ORIGIN.lat, originLng: ORIGIN.lng,
				x: 0, y: 0, z: 0, quat: yawQuat(TAP),
			});
			const back = renderBackYaw(pin.quat);
			// Compare on the circle so 359.6° vs 0.x° wraps cleanly.
			const delta = Math.min(Math.abs(back - TAP), 360 - Math.abs(back - TAP));
			expect(delta).toBeLessThan(0.5);
		}
	});

	it('the quat-derived yaw beats the integer column for a sub-degree placement', () => {
		// Two taps that the integer anchor_yaw_deg cannot tell apart (both round to
		// 90°) stay distinct through the quat — proving the column carries real signal.
		const a = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 0, y: 0, z: 0, quat: yawQuat(90.3) });
		const b = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 0, y: 0, z: 0, quat: yawQuat(89.7) });
		expect(a.heading).toBe(b.heading); // 90 === 90 — the rounded column collapses them
		expect(renderBackYaw(a.quat)).not.toBe(renderBackYaw(b.quat)); // the quat does not
		expect(renderBackYaw(a.quat) - renderBackYaw(b.quat)).toBeCloseTo(0.6, 5);
	});
});

// ── WebXR → room frame (R3) ──────────────────────────────────────────────────
// A floor hit must land in the SHARED room frame, not a standalone GPS pin, so a
// WebXR-placed agent renders identically for every viewer. These pin the two new
// write-path conversions: roomRelFromGeo (lat/lng → exact room offset, used by the
// calibrate/refine PATCH) and roomPlacementFromHit (XR hit pose → room placement).
describe('roomRelFromGeo', () => {
	const QUAT = yawQuat(0);

	it('inverts anchorPoseToPin: a point 2 m E / 3 m N of the origin → rel (2, 3)', () => {
		const pin = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 2, y: 0, z: -3, quat: QUAT });
		const rel = roomRelFromGeo({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, lat: pin.lat, lng: pin.lng });
		expect(near(rel.relEast, 2, 1e-3)).toBe(true);
		expect(near(rel.relNorth, 3, 1e-3)).toBe(true);
	});

	it('a rotated room (originYawDeg) round-trips back through agentWorldPosition', () => {
		// Store an offset in a 30°-rotated room, then render it from the origin: the
		// world position must match the un-rotated true-north offset the point implies.
		const originYawDeg = 30;
		const trueEast = 4, trueNorth = -1; // arbitrary true-north metres from origin
		const { lat, lng } = anchorPoseToPin({
			originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: trueEast, y: 0, z: trueNorth, quat: QUAT,
		}); // note z passed as north here is +trueNorth → world north is −z, see below
		const rel = roomRelFromGeo({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, originYawDeg, lat, lng });
		// Re-render from the origin (viewer ON the origin → originWorld = {0,0}).
		const world = agentWorldPosition({ originWorld: { x: 0, z: 0 }, relEast: rel.relEast, relNorth: rel.relNorth, originYawDeg });
		// anchorPoseToPin treated z as the SOUTH axis (north = −z), so the stored point
		// is trueEast east and −trueNorth north; agentWorldPosition must reproduce that.
		expect(near(world.x, trueEast, 1e-3)).toBe(true);
		expect(near(world.z, trueNorth, 1e-3)).toBe(true);
	});
});

describe('roomPlacementFromHit', () => {
	const QUAT = yawQuat(0);

	it('a hit placed by a viewer standing ON the origin re-renders at the same spot', () => {
		// Viewer == origin: a hit 2 m east / 3 m north (z = −3) of them must store as
		// rel (2, 3) and render back to world (2, 0, −3) for that same viewer.
		const p = roomPlacementFromHit({
			originLat: ORIGIN.lat, originLng: ORIGIN.lng,
			viewerLat: ORIGIN.lat, viewerLng: ORIGIN.lng,
			x: 2, y: -1.4, z: -3, quat: QUAT,
		});
		expect(near(p.relEast, 2, 1e-6)).toBe(true);
		expect(near(p.relNorth, 3, 1e-6)).toBe(true);
		const world = agentWorldPosition({ originWorld: { x: 0, z: 0 }, relEast: p.relEast, relNorth: p.relNorth });
		expect(near(world.x, 2, 1e-6)).toBe(true);
		expect(near(world.z, -3, 1e-6)).toBe(true);
		expect(p.heightM).toBe(-1.4); // real floor height rides through
		expect(p.source).toBe('webxr');
	});

	it('folds in the placer offset: an off-origin viewer’s hit lands where they aimed', () => {
		// The placer stands 5 m east of the origin and drops an agent 2 m north of
		// themselves. Rendered for that same placer (viewer at world 0), the agent must
		// sit at their local hit (x=0, z=−2) — proving the GPS offset is folded in.
		const viewer = geoToLocal(ORIGIN.lat, ORIGIN.lng, 0, 0); // unused; build viewer geo below
		void viewer;
		const east5 = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x: 5, y: 0, z: 0, quat: QUAT });
		const p = roomPlacementFromHit({
			originLat: ORIGIN.lat, originLng: ORIGIN.lng,
			viewerLat: east5.lat, viewerLng: east5.lng,
			x: 0, y: -1.4, z: -2, quat: QUAT,
		});
		// Stored offset is from the ORIGIN: 5 m east, 2 m north.
		expect(near(p.relEast, 5, 1e-3)).toBe(true);
		expect(near(p.relNorth, 2, 1e-3)).toBe(true);
		// Render for the placer (who is 5 m east of origin): agent lands at their hit.
		const originWorld = roomOriginWorld(east5.lat, east5.lng, ORIGIN.lat, ORIGIN.lng);
		const world = agentWorldPosition({ originWorld, relEast: p.relEast, relNorth: p.relNorth });
		expect(near(world.x, 0, 1e-3)).toBe(true);
		expect(near(world.z, -2, 1e-3)).toBe(true);
	});

	it('heading comes from the surface quat, normalised to [0,360)', () => {
		const p = roomPlacementFromHit({
			originLat: ORIGIN.lat, originLng: ORIGIN.lng,
			viewerLat: ORIGIN.lat, viewerLng: ORIGIN.lng,
			x: 0, y: 0, z: 0, quat: yawQuat(270),
		});
		expect(p.relYawDeg).toBe(270); // −90° from atan2, normalised
	});
});

describe('round-trip property: anchorPoseToPin then geoToLocal is identity', () => {
	it('survives within 1e-6 for assorted offsets', () => {
		for (const [x, z] of [[0, 0], [2, -3], [-4, 1], [12, 12], [-7.5, -2.25], [0.1, -0.1]]) {
			const pin = anchorPoseToPin({ originLat: ORIGIN.lat, originLng: ORIGIN.lng, x, y: 0, z, quat: yawQuat(0) });
			const back = geoToLocal(ORIGIN.lat, ORIGIN.lng, pin.lat, pin.lng);
			expect(near(back.east, x, 1e-6)).toBe(true);   // east = +x
			expect(near(back.north, -z, 1e-6)).toBe(true); // north = −z
		}
	});
});