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.

39.4 KB
Raw Blame
/**
 * The live 3D home.
 *
 * Geometry comes from `scene-model.js`, which is pure and testable; this file
 * owns Three.js, the render loop and the transitions. The split matters: the
 * layout of a real house is asserted in a unit test with no GPU, and everything
 * here is about how a change LOOKS when it arrives.
 *
 * Three properties are non-negotiable, and each one has code that exists only
 * to hold it:
 *
 *   * A real light changing in Home Assistant reaches the screen inside one
 *     animation frame of the event arriving. `applyModel` retargets in place
 *     from a diff, so a burst of a hundred entities touches a hundred numbers
 *     and rebuilds nothing.
 *   * Nothing pops. Every visual quantity is a spring toward a target, damped
 *     framerate-independently, so a light comes up rather than snapping on.
 *   * The house never empties. A dropped socket desaturates the scene and shows
 *     its age; the last known state stays on screen, because a person watching
 *     their home should see it go grey, not watch it vanish.
 */

import {
	AmbientLight,
	BoxGeometry,
	CanvasTexture,
	Color,
	CylinderGeometry,
	ConeGeometry,
	Group,
	HemisphereLight,
	LinearFilter,
	Mesh,
	MeshBasicMaterial,
	MeshStandardMaterial,
	PerspectiveCamera,
	PlaneGeometry,
	PointLight,
	Raycaster,
	Scene,
	SphereGeometry,
	Sprite,
	SpriteMaterial,
	Vector2,
	Vector3,
	WebGLRenderer,
} from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
import { createFrameGovernor, FPS_ACTIVE, FPS_IDLE, FPS_SAVER, getPowerSaver, onPowerSaverChange, trackWindowFocus } from '../shared/frame-governor.js';
import { diffScene } from './scene-model.js';

/** Real point lights cost shader time per fragment; emissive glow does not. */
const MAX_ROOM_LIGHTS = 12;

/** Damping half-life in seconds. Fast enough to feel instant, slow enough to read. */
const EASE = 0.09;

const GREY = new Color(0x6a7080);
const WARM = new Color(0xff8a3d);
const COOL = new Color(0x4fc3f7);

const SURFACE = 0x11131c;
const WALL = 0x2b3042;
const SECURE = 0x2fbf71;
const OPEN = 0xe0a33a;
const ALERT = 0xe05a4a;

/**
 * Geometry is shared across every object of a kind: one BoxGeometry serves
 * every wall plate in the house. Materials are per object, because colour is
 * per object, and they are disposed with the object.
 */
function sharedGeometry() {
	return {
		slab: new BoxGeometry(1, 1, 1),
		panel: new BoxGeometry(1, 1, 1),
		bulb: new SphereGeometry(0.15, 16, 12),
		blade: new BoxGeometry(0.62, 0.02, 0.1),
		puck: new CylinderGeometry(0.19, 0.19, 0.09, 18),
		post: new CylinderGeometry(0.07, 0.07, 0.86, 10),
		cone: new ConeGeometry(0.11, 0.24, 10),
		ring: new CylinderGeometry(0.17, 0.17, 0.05, 20),
		plane: new PlaneGeometry(1, 1),
	};
}

/** A thin outline around a room's footprint, as one geometry. */
function roomEdge(w, d) {
	const parts = [];
	for (const [sx, sz, px, pz] of [
		[w + 0.12, 0.12, 0, -d / 2],
		[w + 0.12, 0.12, 0, d / 2],
		[0.12, d + 0.12, -w / 2, 0],
		[0.12, d + 0.12, w / 2, 0],
	]) {
		const box = new BoxGeometry(sx, 0.05, sz);
		box.translate(px, 0.02, pz);
		parts.push(box);
	}
	const merged = mergeGeometries(parts, false);
	for (const part of parts) part.dispose();
	return merged;
}

/** A thin bright lip along the top of a room's four walls, as one geometry. */
function roomRim(w, d) {
	const h = 0.92;
	const parts = [];
	for (const [sx, sz, px, pz] of [
		[w, 0.05, 0, -d / 2],
		[w, 0.05, 0, d / 2],
		[0.05, d, -w / 2, 0],
		[0.05, d, w / 2, 0],
	]) {
		const box = new BoxGeometry(sx, 0.035, sz);
		box.translate(px, h, pz);
		parts.push(box);
	}
	const merged = mergeGeometries(parts, false);
	for (const part of parts) part.dispose();
	return merged;
}

/** The four waist-high walls of a room, as one geometry. */
function roomShell(w, d) {
	const h = 0.92;
	const parts = [];
	for (const [sx, sz, px, pz] of [
		[w, 0.06, 0, -d / 2],
		[w, 0.06, 0, d / 2],
		[0.06, d, -w / 2, 0],
		[0.06, d, w / 2, 0],
	]) {
		const box = new BoxGeometry(sx, h, sz);
		box.translate(px, h / 2, pz);
		parts.push(box);
	}
	const merged = mergeGeometries(parts, false);
	for (const part of parts) part.dispose();
	return merged;
}

/** The "this device is not answering" marker, built only when one is. */
function addMissingMarker(node) {
	const marker = new Sprite(new SpriteMaterial({ color: 0xe05a4a, transparent: true, opacity: 0, depthWrite: false, depthTest: false }));
	marker.scale.set(0.34, 0.34, 1);
	marker.position.y = 0.42;
	node.add(marker);
	return marker;
}

/**
 * @param {HTMLElement} container
 * @param {object} [options]
 * @param {(entityId: string|null, object: object|null) => void} [options.onSelect]
 * @param {(roomId: string) => void} [options.onFocusRoom]
 * @param {() => void} [options.onFirstFrame]
 */
export function createHomeScene(container, options = {}) {
	const renderer = new WebGLRenderer({ antialias: true, alpha: true, powerPreference: 'high-performance' });
	renderer.setClearColor(0x000000, 0);
	// A phone at devicePixelRatio 3 renders nine times the fragments of a
	// desktop for a scene nobody looks at that closely. 2 is the point past
	// which the extra pixels stop being visible and start costing frames.
	renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
	container.appendChild(renderer.domElement);
	renderer.domElement.setAttribute('aria-hidden', 'true');
	renderer.domElement.style.display = 'block';
	renderer.domElement.style.width = '100%';
	renderer.domElement.style.height = '100%';
	renderer.domElement.style.touchAction = 'none';

	const scene = new Scene();
	const camera = new PerspectiveCamera(46, 1, 0.1, 400);
	const controls = new OrbitControls(camera, renderer.domElement);
	// Reassigned by the reduced-motion watcher below, which cannot run before
	// the controls exist.
	controls.enableDamping = true;
	controls.dampingFactor = 0.08;
	controls.maxPolarAngle = Math.PI * 0.49;
	controls.minDistance = 4;
	controls.maxDistance = 140;

	scene.add(new AmbientLight(0xffffff, 0.16));
	const sky = new HemisphereLight(0x8fa6ff, 0x0b0d14, 0.34);
	scene.add(sky);

	const geo = sharedGeometry();
	const world = new Group();
	scene.add(world);
	/** One slab per floor, under its rooms: the level a room is standing on. */
	const slabs = new Group();
	world.add(slabs);

	/** @type {Map<string, object>} entityId to its live object record */
	const objects = new Map();
	/** @type {Map<string, object>} roomId to its live room record */
	const rooms = new Map();
	const slabMaterial = new MeshStandardMaterial({ color: 0x0c0d13, roughness: 1, metalness: 0 });
	const spare = { color: new Color(), target: new Color(), v: new Vector3(), toward: new Vector3(), forward: new Vector3() };

	let model = null;
	// The body the agent wears. Null until the visitor's own agent resolves, and
	// the default body stands in meanwhile rather than nobody standing there.
	let avatarUrl = options.avatarUrl || null;
	let stale = false;
	let staleAmount = 0;
	let acting = null;
	let actingUntil = 0;
	let selected = null;
	let agent = null;
	let disposed = false;
	let firstFrameSent = false;
	let frames = 0;
	let fpsWindowStart = 0;
	let fps = 0;
	// Split on purpose. Under a software rasterizer (headless CI, a locked-down
	// browser) `render` dominates and says nothing about the scene's own cost, so
	// the update work is timed separately and both numbers are reported.
	let updateMs = 0;
	let renderMs = 0;
	const lastCameraPosition = new Vector3();

	const raycaster = new Raycaster();
	const pointer = new Vector2();
	const governor = createFrameGovernor();
	const focus = trackWindowFocus();
	// A house is a live readout, so reduced motion cannot mean a frozen scene:
	// the values still update, they just stop travelling to their new state.
	// Every damped quantity snaps, and OrbitControls stops coasting after a
	// drag, which is the motion a vestibular trigger actually notices.
	const motionQuery =
		typeof matchMedia === 'function' ? matchMedia('(prefers-reduced-motion: reduce)') : null;
	let reduceMotion = Boolean(motionQuery?.matches);
	controls.enableDamping = !reduceMotion;
	motionQuery?.addEventListener?.('change', (event) => {
		reduceMotion = event.matches;
		controls.enableDamping = !reduceMotion;
	});
	let powerSaver = getPowerSaver();
	const stopPowerSaver = onPowerSaverChange((on) => {
		powerSaver = on;
	});

	// ── structure ─────────────────────────────────────────────────────────────

	/** Rebuild the house. Called when the set of rooms or entities changes. */
	function setModel(next) {
		const structural = !model || structureKey(model) !== structureKey(next);
		if (!structural) return applyModel(next);
		clearWorld();
		model = next;
		buildSlabs(next);
		for (const room of next.rooms) rooms.set(room.id, buildRoom(room));
		frameCamera(next);
		placeAgent(next.agent);
		applyModel(next, { snap: true });
	}

	/**
	 * Retarget every changed value in place. This is the hot path: it must not
	 * allocate a mesh, a material or an array proportional to the update.
	 */
	function applyModel(next, { snap = false } = {}) {
		const previous = model;
		model = next;
		const delta = previous ? diffScene(previous, next) : null;

		for (const room of next.rooms) {
			const record = rooms.get(room.id);
			if (!record) continue;
			record.source = room;
			record.targetIntensity = room.light.intensity;
			record.targetColor.set(room.light.hex);
			record.targetSecure = room.security ? (room.security.secure ? 0 : 1) : 0;
			if (record.labelText !== labelFor(room)) {
				record.labelText = labelFor(room);
				paintLabel(record);
			}
			if (snap) {
				record.intensity = record.targetIntensity;
				record.color.copy(record.targetColor);
				record.secure = record.targetSecure;
				commitRoom(record);
			}
		}

		const touched = delta ? [...delta.changed, ...delta.added] : allObjects(next);
		for (const object of touched) {
			const record = objects.get(object.entityId);
			if (!record) continue;
			record.source = object;
			record.targetActivity = object.activity;
			record.targetAvailable = object.available ? 1 : 0;
			if (snap) {
				record.activity = record.targetActivity;
				record.availability = record.targetAvailable;
				commitObject(record);
			}
		}
	}

	/** Only these change the geometry; everything else is a value on a mesh. */
	function structureKey(m) {
		return m.rooms.map((r) => `${r.id}:${r.x},${r.y},${r.z}:${r.objects.map((o) => o.entityId).join(',')}`).join('|');
	}

	function allObjects(m) {
		const out = [];
		for (const room of m.rooms) out.push(...room.objects);
		return out;
	}

	/**
	 * A dark slab under each floor's rooms. Two rooms floating at different
	 * heights read as two rooms; two rooms on visible levels read as a house.
	 */
	function buildSlabs(m) {
		for (const floor of m.floors) {
			const boxes = m.rooms.filter((r) => r.floorId === floor.id);
			if (!boxes.length) continue;
			let minX = Infinity;
			let maxX = -Infinity;
			let minZ = Infinity;
			let maxZ = -Infinity;
			for (const room of boxes) {
				minX = Math.min(minX, room.x - room.w / 2);
				maxX = Math.max(maxX, room.x + room.w / 2);
				minZ = Math.min(minZ, room.z - room.d / 2);
				maxZ = Math.max(maxZ, room.z + room.d / 2);
			}
			const pad = 1.1;
			const slab = new Mesh(geo.slab, slabMaterial);
			slab.scale.set(maxX - minX + pad * 2, 0.22, maxZ - minZ + pad * 2);
			slab.position.set((minX + maxX) / 2, floor.y - 0.24, (minZ + maxZ) / 2);
			slabs.add(slab);
		}
	}

	function buildRoom(room) {
		const group = new Group();
		group.position.set(room.x, room.y, room.z);
		world.add(group);

		const floorMat = new MeshStandardMaterial({ color: SURFACE, roughness: 0.92, metalness: 0.02, emissive: new Color(0x000000) });
		const floor = new Mesh(geo.slab, floorMat);
		floor.scale.set(room.w, 0.12, room.d);
		floor.position.y = -0.06;
		floor.userData.roomId = room.id;
		group.add(floor);

		// A bright lip along the top of the walls. Without it a room reads as a
		// coloured rectangle on a black field; with it, it reads as a room you are
		// looking down into, which is the whole illusion.
		const rimMat = new MeshBasicMaterial({ color: 0xffffff, transparent: true, opacity: 0.1 });
		const rim = new Mesh(roomRim(room.w, room.d), rimMat);
		group.add(rim);

		// Waist-high walls, translucent. Full-height walls would hide the room's
		// contents from every angle an orbiting camera can reach, and a dollhouse
		// you cannot see into is a box.
		//
		// All four are ONE geometry. As separate meshes they were four draw calls
		// per room, which is four hundred in a hundred-room house for a shape that
		// never moves relative to its room.
		const wallMat = new MeshStandardMaterial({ color: WALL, roughness: 0.75, metalness: 0.05, transparent: true, opacity: 0.34 });
		const wallGeo = roomShell(room.w, room.d);
		const walls = new Mesh(wallGeo, wallMat);
		group.add(walls);

		// The security tell: a LINE around the room's foot that goes amber the
		// moment something in it is unlocked or open. Readable from across the
		// room without reading a single label, which is the whole point.
		//
		// It was a scaled box, which is a filled sheet over the whole floor, so
		// every secure room in the house was carpeted in green and no light
		// underneath it could be seen. An outline says the same thing and shows
		// the room.
		const edgeMat = new MeshBasicMaterial({ color: SECURE, transparent: true, opacity: 0 });
		const edge = new Mesh(roomEdge(room.w, room.d), edgeMat);
		group.add(edge);

		const light = new PointLight(0xffffff, 0, room.w * 2.6, 1.7);
		light.position.set(0, room.h * 0.72, 0);
		const usesLight = rooms.size < MAX_ROOM_LIGHTS;
		if (usesLight) group.add(light);

		const label = makeLabel();
		label.position.set(0, room.h + 1.05, 0);
		group.add(label);

		const record = {
			id: room.id,
			source: room,
			group,
			floorMat,
			rimMat,
			rimGeo: rim.geometry,
			wallMat,
			edgeMat,
			edgeGeo: edge.geometry,
			light: usesLight ? light : null,
			label,
			wallGeo,
			labelText: '',
			color: new Color(room.light.hex),
			targetColor: new Color(room.light.hex),
			intensity: 0,
			targetIntensity: room.light.intensity,
			secure: 0,
			targetSecure: 0,
			highlight: 0,
		};
		record.labelText = labelFor(room);
		paintLabel(record);

		for (const object of room.objects) objects.set(object.entityId, buildObject(object, group, room));
		return record;
	}

	function buildObject(object, group, room) {
		const node = new Group();
		node.position.set(object.x, object.y, object.z);
		node.rotation.y = object.rotation;
		group.add(node);

		const material = new MeshStandardMaterial({
			color: 0x6f7690,
			roughness: 0.55,
			metalness: 0.15,
			emissive: new Color(0x000000),
			transparent: true,
			opacity: 1,
		});
		const record = {
			entityId: object.entityId,
			roomId: room.id,
			source: object,
			node,
			material,
			parts: [],
			activity: 0,
			targetActivity: object.activity,
			availability: 1,
			targetAvailable: object.available ? 1 : 0,
			select: 0,
		};

		switch (object.kind) {
			case 'lamp': {
				const bulb = new Mesh(geo.bulb, material);
				bulb.userData.entityId = object.entityId;
				node.add(bulb);
				const stem = new Mesh(geo.post, new MeshStandardMaterial({ color: 0x3a3f52, roughness: 0.8 }));
				stem.scale.y = 0.42;
				stem.position.y = 0.33;
				node.add(stem);
				record.parts.push(stem.material);
				const halo = new Sprite(new SpriteMaterial({ color: 0xffffff, transparent: true, opacity: 0, depthWrite: false }));
				halo.scale.set(2.1, 2.1, 1);
				node.add(halo);
				record.halo = halo;
				break;
			}
			case 'fan': {
				const hub = new Mesh(geo.puck, material);
				hub.scale.set(0.6, 0.6, 0.6);
				hub.userData.entityId = object.entityId;
				node.add(hub);
				const rotor = new Group();
				for (let i = 0; i < 3; i += 1) {
					const blade = new Mesh(geo.blade, material);
					blade.rotation.y = (i * Math.PI * 2) / 3;
					blade.position.y = -0.04;
					rotor.add(blade);
				}
				node.add(rotor);
				record.rotor = rotor;
				break;
			}
			case 'lock': {
				const body = new Mesh(geo.panel, material);
				body.scale.set(0.2, 0.3, 0.1);
				body.userData.entityId = object.entityId;
				node.add(body);
				const shackle = new Mesh(geo.ring, material);
				shackle.scale.set(0.62, 0.9, 0.62);
				shackle.position.y = 0.2;
				node.add(shackle);
				record.shackle = shackle;
				break;
			}
			case 'door':
			case 'window': {
				const frame = new Mesh(geo.panel, new MeshStandardMaterial({ color: 0x394059, roughness: 0.8, transparent: true, opacity: 0.6 }));
				const wide = object.kind === 'door' ? 1.05 : 0.92;
				frame.scale.set(wide, object.kind === 'door' ? 1.9 : 1.1, 0.06);
				frame.position.y = object.kind === 'door' ? 0.35 : 0.1;
				node.add(frame);
				record.parts.push(frame.material);
				const leaf = new Mesh(geo.panel, material);
				leaf.scale.set(wide * 0.94, (object.kind === 'door' ? 1.9 : 1.1) * 0.94, 0.04);
				leaf.position.set(0, frame.position.y, 0.03);
				leaf.userData.entityId = object.entityId;
				node.add(leaf);
				record.leaf = leaf;
				record.leafSpan = wide * 0.94;
				record.leafHeight = (object.kind === 'door' ? 1.9 : 1.1) * 0.94;
				record.leafY = frame.position.y;
				break;
			}
			case 'thermostat': {
				const post = new Mesh(geo.post, new MeshStandardMaterial({ color: 0x3a3f52, roughness: 0.8 }));
				post.scale.y = 0.72;
				post.position.y = 0.31;
				node.add(post);
				record.parts.push(post.material);
				const dial = new Mesh(geo.ring, material);
				dial.rotation.x = Math.PI / 2;
				dial.position.y = 0.68;
				dial.scale.set(1.1, 1, 1.1);
				dial.userData.entityId = object.entityId;
				node.add(dial);
				break;
			}
			case 'screen': {
				const panel = new Mesh(geo.panel, material);
				panel.scale.set(0.92, 0.52, 0.05);
				panel.userData.entityId = object.entityId;
				node.add(panel);
				break;
			}
			case 'camera': {
				const lens = new Mesh(geo.cone, material);
				lens.rotation.x = Math.PI / 2;
				lens.userData.entityId = object.entityId;
				node.add(lens);
				break;
			}
			case 'alarm': {
				const box = new Mesh(geo.panel, material);
				box.scale.set(0.3, 0.42, 0.08);
				box.userData.entityId = object.entityId;
				node.add(box);
				break;
			}
			case 'puck': {
				const disc = new Mesh(geo.puck, material);
				disc.scale.set(1.5, 1, 1.5);
				disc.position.y = 0.05;
				disc.userData.entityId = object.entityId;
				node.add(disc);
				break;
			}
			default: {
				const plate = new Mesh(geo.panel, material);
				plate.scale.set(0.22, 0.22, 0.05);
				plate.userData.entityId = object.entityId;
				node.add(plate);
			}
		}

		commitObject(record);
		return record;
	}

	// ── per-frame values ──────────────────────────────────────────────────────

	function commitRoom(record) {
		const room = record.source;
		const dim = 1 - staleAmount * 0.72;
		spare.color.copy(record.color);
		if (staleAmount > 0) spare.color.lerp(GREY, staleAmount * 0.85);

		if (record.light) {
			record.light.color.copy(spare.color);
			// The point light does the work. Emissive on the slab was doing it
			// instead, which flattened every lit room into one saturated rectangle.
			record.light.intensity = record.intensity * 6.5 * dim;
		}
		record.floorMat.emissive.copy(spare.color).multiplyScalar(record.intensity * 0.09 * dim);
		record.floorMat.color.setHex(SURFACE).lerp(spare.color, Math.min(0.1, record.intensity * 0.08));
		record.wallMat.opacity = 0.3 + record.intensity * 0.1 + record.highlight * 0.24;
		// A dark room still has to be a visible room, so the rim has a real floor.
		record.rimMat.opacity = (0.17 + record.intensity * 0.13 + record.highlight * 0.35) * (1 - staleAmount * 0.5);

		const alarmed = record.secure;
		record.edgeMat.color.setHex(alarmed > 0.5 ? OPEN : SECURE);
		record.edgeMat.opacity = (room.security ? 0.3 + alarmed * 0.65 : 0) + record.highlight * 0.4;
		// Faded by distance so a house seen from far away is a house, not a list
		// of names. The focused room keeps its label at any range.
		const far = record.group.position.distanceTo(camera.position);
		const near = record.id === model?.focusRoomId ? 1 : clamp01(1.6 - far / 34);
		record.label.material.opacity = 0.92 * near * (1 - staleAmount * 0.4);
		record.label.visible = near > 0.02;
	}

	function commitObject(record) {
		const object = record.source;
		const room = rooms.get(record.roomId);
		const on = record.activity;
		const available = record.availability;
		const dim = 1 - staleAmount * 0.7;

		spare.target.setHex(0x6f7690);
		let emissiveStrength = 0;

		switch (object.kind) {
			case 'lamp': {
				const roomColor = room ? room.color : spare.color.setHex(0xffe0b0);
				spare.target.copy(roomColor);
				emissiveStrength = on * 1.5;
				if (record.halo) record.halo.material.opacity = on * 0.4 * dim * available;
				if (record.halo) record.halo.material.color.copy(roomColor);
				break;
			}
			case 'lock': {
				spare.target.setHex(on > 0.5 ? ALERT : SECURE);
				emissiveStrength = on > 0.5 ? 0.85 : 0.22;
				if (record.shackle) record.shackle.position.y = 0.2 + on * 0.12;
				break;
			}
			case 'door':
			case 'window': {
				spare.target.setHex(on > 0.02 ? OPEN : 0x5a6178);
				emissiveStrength = on * 0.5;
				if (record.leaf) {
					// Openness is a real position: a cover at 40% is 40% open, not a
					// colour change standing in for one.
					record.leaf.scale.x = Math.max(0.02, record.leafSpan * (1 - on * 0.94));
					record.leaf.position.x = -(record.leafSpan * on * 0.47);
				}
				break;
			}
			case 'thermostat': {
				const tint = room?.source?.climate?.tint ?? 0;
				spare.target.setHex(0x4f88d8).lerp(WARM, Math.max(0, tint)).lerp(COOL, Math.max(0, -tint));
				emissiveStrength = on * 0.7;
				break;
			}
			case 'screen':
				spare.target.setHex(0x8fa6ff);
				emissiveStrength = on * 1.15;
				break;
			case 'alarm':
				spare.target.setHex(on > 0.5 ? ALERT : 0x5a6178);
				emissiveStrength = on * 0.9;
				break;
			case 'camera':
				spare.target.setHex(0x7c5cff);
				emissiveStrength = 0.3;
				break;
			case 'fan':
				spare.target.setHex(on > 0.5 ? 0x8fa6ff : 0x6f7690);
				emissiveStrength = on * 0.4;
				break;
			default:
				spare.target.setHex(on > 0.5 ? 0x8fa6ff : 0x6f7690);
				emissiveStrength = on * 0.6;
		}

		if (staleAmount > 0) spare.target.lerp(GREY, staleAmount * 0.85);
		record.material.color.copy(spare.target);
		record.material.emissive.copy(spare.target).multiplyScalar(emissiveStrength * dim * available);
		// Unreachable reads as a ghost of itself plus a live marker, so "the lamp
		// is off" and "the lamp is gone" can never look the same.
		record.material.opacity = 0.24 + available * 0.76;
		for (const part of record.parts) part.opacity = 0.3 + available * 0.7;
		// A device Home Assistant cannot reach is drawn, never omitted: a thing
		// that vanished from a house is information, and hiding it is how a scene
		// tells a comfortable lie. The marker is built the first time a device
		// actually goes missing, so a healthy house pays nothing for it.
		if (available < 0.999 && !record.missing) record.missing = addMissingMarker(record.node);
		if (record.missing) record.missing.material.opacity = (1 - available) * 0.9;
		record.node.scale.setScalar(1 + record.select * 0.18);
	}

	// ── loop ──────────────────────────────────────────────────────────────────

	function clamp01(n) {
		return Math.min(1, Math.max(0, n));
	}

	function damp(current, target, dt) {
		// Reduced motion arrives, it does not travel. Returning the target is
		// what turns every transition in the scene off at once, because every
		// animated quantity in the loop (intensity, highlight, security, the
		// stale desaturation) goes through this one function.
		if (reduceMotion) return target;
		// Framerate-independent exponential approach: the same visual speed at
		// 30 fps and at 144.
		return current + (target - current) * (1 - Math.exp(-dt / EASE));
	}

	let last = 0;
	let raf = 0;
	let staleMoving = false;
	function tick(now) {
		if (disposed) return;
		raf = requestAnimationFrame(tick);
		// A wall display is the real deployment: an unfocused tab and a
		// power-saver phone both step down to 30, and the governor keeps the
		// average honest on a 120Hz panel instead of quantizing it to 40.
		const cap = powerSaver ? FPS_SAVER : focus.focused ? FPS_ACTIVE : FPS_IDLE;
		if (!governor.shouldRun(now, cap)) return;
		const dt = last ? Math.min(0.1, (now - last) / 1000) : 0.016;
		last = now;

		const updateStart = performance.now();
		// Label opacity is a function of camera distance, so rooms recommit while
		// the camera is moving and stay untouched the moment it settles.
		const cameraMoved = !lastCameraPosition.equals(camera.position);
		if (cameraMoved) lastCameraPosition.copy(camera.position);
		const staleTarget = stale ? 1 : 0;
		staleMoving = Math.abs(staleAmount - staleTarget) > 0.002;
		staleAmount = damp(staleAmount, staleTarget, dt);
		if (acting && now > actingUntil) acting = null;

		for (const record of rooms.values()) {
			const wasHighlight = record.highlight;
			record.highlight = damp(record.highlight, acting?.roomId === record.id ? 1 : 0, dt);
			const before = record.intensity;
			record.intensity = damp(record.intensity, record.targetIntensity, dt);
			record.secure = damp(record.secure, record.targetSecure, dt);
			const moved =
				Math.abs(before - record.intensity) > 0.0005 ||
				Math.abs(wasHighlight - record.highlight) > 0.001 ||
				cameraMoved;
			if (moved || !record.color.equals(record.targetColor) || staleMoving) {
				record.color.lerp(record.targetColor, reduceMotion ? 1 : 1 - Math.exp(-dt / EASE));
				commitRoom(record);
			}
		}

		for (const record of objects.values()) {
			const before = record.activity;
			record.activity = damp(record.activity, record.targetActivity, dt);
			record.availability = damp(record.availability, record.targetAvailable, dt);
			const wanted = selected === record.entityId ? 1 : 0;
			const beforeSelect = record.select;
			record.select = damp(record.select, wanted, dt);
			if (record.rotor && record.activity > 0.02) record.rotor.rotation.y += dt * (2 + record.activity * 16);
			if (
				Math.abs(before - record.activity) > 0.0008 ||
				Math.abs(beforeSelect - record.select) > 0.002 ||
				Math.abs(record.availability - record.targetAvailable) > 0.002 ||
				staleMoving
			) {
				commitObject(record);
			}
		}

		if (agent) agent.update(dt, now);
		controls.update();
		const renderStart = performance.now();
		updateMs = renderStart - updateStart;
		renderer.render(scene, camera);
		renderMs = performance.now() - renderStart;

		frames += 1;
		if (!fpsWindowStart) fpsWindowStart = now;
		if (now - fpsWindowStart >= 1000) {
			fps = Math.round((frames * 1000) / (now - fpsWindowStart));
			frames = 0;
			fpsWindowStart = now;
		}
		if (!firstFrameSent) {
			firstFrameSent = true;
			options.onFirstFrame?.();
		}
	}

	// ── camera, agent, labels, picking ────────────────────────────────────────

	function frameCamera(m) {
		const b = m.bounds;
		const cx = (b.minX + b.maxX) / 2;
		const cz = (b.minZ + b.maxZ) / 2;
		const span = Math.max(b.width, b.depth, 8);
		controls.target.set(cx, b.maxY * 0.34, cz);
		camera.position.set(cx + span * 0.58, b.maxY * 0.6 + span * 0.72, cz + span * 0.94);
		camera.updateProjectionMatrix();
		controls.update();
	}

	/**
	 * Move the camera onto a room.
	 *
	 * Deliberately silent: this is the ANSWER to a focus request, not a new one.
	 * Firing `onFocusRoom` from here meant the page's own handler called back
	 * into it and the two recursed until the stack ran out, which is exactly what
	 * clicking a room in the rail did.
	 */
	function focusRoom(roomId) {
		const record = rooms.get(roomId);
		if (!record || !model) return;
		const room = record.source;
		controls.target.set(room.x, room.y + 1.1, room.z);
		const distance = Math.max(room.w, room.d) * 1.9;
		camera.position.set(room.x + distance * 0.55, room.y + distance * 0.72, room.z + distance);
		controls.update();
	}

	function makeLabel() {
		const canvas = document.createElement('canvas');
		canvas.width = 512;
		canvas.height = 128;
		const texture = new CanvasTexture(canvas);
		texture.minFilter = LinearFilter;
		// Depth test off, distance fade on. Testing depth clipped a label wherever
		// it crossed the room in front of it, which read as truncated text; the
		// distance fade is what actually stops a dozen labels stacking up.
		const sprite = new Sprite(new SpriteMaterial({ map: texture, transparent: true, depthWrite: false, depthTest: false }));
		sprite.scale.set(3.4, 0.85, 1);
		sprite.userData.canvas = canvas;
		sprite.userData.texture = texture;
		return sprite;
	}

	function labelFor(room) {
		const bits = [room.name];
		if (room.climate) bits.push(room.climate.label);
		if (room.light.total) bits.push(`${room.light.count}/${room.light.total} lit`);
		return bits.join('   ');
	}

	function paintLabel(record) {
		const canvas = record.label.userData.canvas;
		const ctx = canvas.getContext('2d');
		ctx.clearRect(0, 0, canvas.width, canvas.height);
		ctx.textAlign = 'center';
		ctx.textBaseline = 'middle';
		// Fit the text to the canvas rather than letting it run off the edge. A
		// room called "Living Room" with a temperature and a light count is wider
		// than 512px at 46px, and the overflow read as a truncated room name.
		let size = 46;
		ctx.font = `600 ${size}px "Inter", system-ui, sans-serif`;
		while (size > 22 && ctx.measureText(record.labelText).width > canvas.width - 72) {
			size -= 2;
			ctx.font = `600 ${size}px "Inter", system-ui, sans-serif`;
		}
		ctx.fillStyle = 'rgba(8, 9, 14, 0.72)';
		const width = Math.min(canvas.width - 8, ctx.measureText(record.labelText).width + 56);
		roundRect(ctx, (canvas.width - width) / 2, 26, width, 76, 22);
		ctx.fill();
		ctx.fillStyle = '#eef1ff';
		ctx.fillText(record.labelText, canvas.width / 2, 64);
		record.label.userData.texture.needsUpdate = true;
	}

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

	function placeAgent(stand) {
		if (!stand) return;
		if (!agent) {
			agent = createAgentBody(scene, renderer, avatarUrl);
		}
		agent.moveTo(stand.x, stand.y, stand.z, stand.facing);
	}

	function onPointerDown(event) {
		const rect = renderer.domElement.getBoundingClientRect();
		pointer.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
		pointer.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
		raycaster.setFromCamera(pointer, camera);
		const hits = raycaster.intersectObjects(world.children, true);
		for (const hit of hits) {
			const entityId = hit.object.userData.entityId;
			if (entityId) {
				selected = entityId;
				options.onSelect?.(entityId, objects.get(entityId)?.source || null);
				return;
			}
			const roomId = hit.object.userData.roomId;
			if (roomId) {
				selected = null;
				options.onSelect?.(null, null);
				options.onFocusRoom?.(roomId);
				return;
			}
		}
		selected = null;
		options.onSelect?.(null, null);
	}
	renderer.domElement.addEventListener('pointerdown', onPointerDown);

	function resize() {
		const w = container.clientWidth || 1;
		const h = container.clientHeight || 1;
		renderer.setSize(w, h, false);
		camera.aspect = w / h;
		camera.updateProjectionMatrix();
	}
	const observer = new ResizeObserver(resize);
	observer.observe(container);
	resize();
	raf = requestAnimationFrame(tick);

	function clearWorld() {
		for (const record of objects.values()) {
			record.material.dispose();
			for (const part of record.parts) part.dispose();
			record.halo?.material.dispose();
			record.missing?.material.dispose();
		}
		objects.clear();
		for (const record of rooms.values()) {
			record.floorMat.dispose();
			record.rimMat.dispose();
			record.rimGeo.dispose();
			record.edgeGeo.dispose();
			record.wallMat.dispose();
			record.wallGeo.dispose();
			record.edgeMat.dispose();
			record.label.material.map?.dispose();
			record.label.material.dispose();
		}
		rooms.clear();
		slabs.clear();
		world.clear();
		world.add(slabs);
	}

	return {
		setModel,
		focusRoom,
		select(entityId) {
			selected = entityId;
		},
		setStale(next) {
			stale = Boolean(next);
		},
		/** Highlight the room an action is happening in, for a short beat. */
		/**
		 * Put the visitor's own agent in the house, or swap it for another one.
		 * Resolving that record is a round trip the house must never wait on, so
		 * it arrives here after the first frame rather than gating it.
		 */
		setAvatarUrl(next) {
			const url = next || null;
			if (url === avatarUrl) return;
			avatarUrl = url;
			agent?.setAvatarUrl(url);
		},
		setActing(next, holdMs = 2600) {
			acting = next;
			actingUntil = performance.now() + holdMs;
			if (next?.roomId) agent?.moveToRoom(rooms.get(next.roomId)?.source);
			agent?.act();
		},
		/**
		 * Where an entity currently sits on screen, so the confirmation can be
		 * pinned to the door it would open rather than to a corner of the page.
		 * @returns {{ x: number, y: number, visible: boolean }|null}
		 */
		project(entityId) {
			const record = objects.get(entityId);
			if (!record) return null;
			record.node.getWorldPosition(spare.v);
			spare.v.y += 0.5;
			spare.toward.copy(spare.v).sub(camera.position);
			camera.getWorldDirection(spare.forward);
			const behind = spare.toward.dot(spare.forward) <= 0;
			spare.v.project(camera);
			const rect = renderer.domElement.getBoundingClientRect();
			return {
				x: ((spare.v.x + 1) / 2) * rect.width,
				y: ((1 - spare.v.y) / 2) * rect.height,
				visible: !behind && Math.abs(spare.v.x) <= 1.05 && Math.abs(spare.v.y) <= 1.05,
			};
		},
		stats() {
			return {
				fps,
				updateMs: Math.round(updateMs * 100) / 100,
				renderMs: Math.round(renderMs * 100) / 100,
				objects: objects.size,
				rooms: rooms.size,
				drawCalls: renderer.info.render.calls,
				geometries: renderer.info.memory.geometries,
				textures: renderer.info.memory.textures,
				// Reported, not inferred. `prefers-reduced-motion` turns off both
				// the camera's coasting and the damping that walks a light to its
				// new brightness, and neither is visible from outside the closure:
				// a test could only watch pixels and guess. These two are the
				// setting as the renderer actually applied it, which is the thing
				// worth asserting, and they cost nothing to read.
				reduceMotion,
				damping: controls.enableDamping,
			};
		},
		dispose() {
			if (disposed) return;
			disposed = true;
			cancelAnimationFrame(raf);
			stopPowerSaver();
			observer.disconnect();
			renderer.domElement.removeEventListener('pointerdown', onPointerDown);
			clearWorld();
			agent?.dispose();
			slabMaterial.dispose();
			for (const value of Object.values(geo)) value.dispose();
			controls.dispose();
			renderer.dispose();
			renderer.domElement.remove();
		},
	};
}

/** The body every house falls back to when the visitor has no avatar of their own. */
const DEFAULT_BODY = '/avatars/default.glb';

/**
 * The agent's body, standing in the house.
 *
 * It is the VISITOR'S OWN agent whenever they have one: the same avatar the
 * walk world, `/play` and the voice satellite show, resolved through the
 * canonical active-agent record and swapped live when they switch agents in
 * another tab. Somebody who has not made one yet, or whose avatar is private
 * and therefore has no readable model URL, gets the platform's default body
 * rather than an empty room.
 *
 * Either way it is driven by the canonical clip library, so a rig that animates
 * anywhere on three.ws animates here. A rig that cannot be skeleton-driven, or
 * a load that fails outright, falls back to a lit capsule: the house stays
 * fully usable, it just loses the face.
 */
function createAgentBody(scene, renderer, avatarUrl = null) {
	const root = new Group();
	scene.add(root);
	let anim = null;
	let body = null;
	let disposed = false;
	/** Guards against a slow first avatar landing after a faster second one. */
	let loadToken = 0;
	const target = new Vector3();
	let bob = 0;
	let gesture = 0;
	let placeholder = null;

	const glow = new PointLight(0x8fa6ff, 1.4, 6, 2);
	glow.position.y = 1.2;
	root.add(glow);

	placeholder = new Mesh(
		new CylinderGeometry(0.26, 0.3, 1.5, 12),
		new MeshStandardMaterial({ color: 0x2a2444, roughness: 0.5, metalness: 0.3, emissive: 0x7c5cff, emissiveIntensity: 0.45 }),
	);
	placeholder.position.y = 0.75;
	root.add(placeholder);

	/** Drop the body currently standing here, with its GPU resources. */
	function clearBody() {
		anim?.dispose?.();
		anim = null;
		if (!body) return;
		root.remove(body);
		body.traverse((node) => {
			if (!node.isMesh) return;
			node.geometry?.dispose?.();
			for (const material of Array.isArray(node.material) ? node.material : [node.material]) {
				if (!material) continue;
				for (const value of Object.values(material)) {
					if (value?.isTexture) value.dispose();
				}
				material.dispose?.();
			}
		});
		body = null;
	}

	/**
	 * Load one avatar. Falls back to the platform body once when a personal one
	 * cannot be fetched or decoded, which is the ordinary case for an avatar
	 * whose owner made it private after pointing a wall display at this house.
	 */
	async function load(url) {
		const token = (loadToken += 1);
		const wanted = url || DEFAULT_BODY;
		try {
			const [{ gltfLoader }, { AnimationManager }] = await Promise.all([
				import('../loaders/gltf.js'),
				import('../animation-manager.js'),
			]);
			const gltf = await new Promise((resolve, reject) => gltfLoader(renderer).load(wanted, resolve, undefined, reject));
			if (disposed || token !== loadToken) return;
			clearBody();
			const model = gltf.scene;
			model.traverse((node) => {
				if (node.isMesh) node.frustumCulled = false;
			});
			root.add(model);
			body = model;
			placeholder.visible = false;
			anim = new AnimationManager();
			anim.attach(model, { avatarUrl: wanted });
			anim.relaxUndrivenArms?.();
			const defs = await fetch('/animations/manifest.json').then((r) => (r.ok ? r.json() : []));
			if (disposed || token !== loadToken) return;
			if (Array.isArray(defs) && defs.length && anim.supportsCanonicalClips?.() !== false) {
				anim.setAnimationDefs(defs);
				if (await anim.ensureLoaded('idle')) await anim.crossfadeTo('idle', 0);
			}
		} catch {
			if (disposed || token !== loadToken) return;
			// One retry, on the body we ship and serve ourselves. Beyond that the
			// capsule is already standing and the house does not need the body.
			if (wanted !== DEFAULT_BODY) await load(DEFAULT_BODY);
		}
	}

	load(avatarUrl);

	return {
		/**
		 * Show a different avatar without rebuilding the house. Called when the
		 * visitor switches agents, in this tab or another one.
		 */
		setAvatarUrl(next) {
			load(next);
		},
		moveTo(x, y, z, facing) {
			target.set(x, y, z);
			root.position.copy(target);
			root.rotation.y = facing;
		},
		moveToRoom(room) {
			if (!room) return;
			this.moveTo(room.x - room.w * 0.22, room.y, room.z + room.d * 0.2, 0);
		},
		/** A short lift as the agent performs an action, so it is clearly the actor. */
		act() {
			gesture = 1;
		},
		update(dt) {
			bob += dt;
			gesture = Math.max(0, gesture - dt * 0.8);
			root.position.y = target.y + Math.sin(bob * 1.6) * 0.012 + gesture * 0.14;
			glow.intensity = 1.1 + Math.sin(bob * 2.2) * 0.2 + gesture * 1.6;
			anim?.update?.(dt);
		},
		dispose() {
			disposed = true;
			clearBody();
			scene.remove(root);
			placeholder?.geometry.dispose();
			placeholder?.material.dispose();
		},
	};
}