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.

36.2 KB
Raw Blame
// AnatomyViewer: renders a normalized anatomy spec as an interactive
// isometric engineering illustration.
//
// Each part instance is a chain of three groups. The repeat group holds the
// radial or linear copy transform. The pivot holds the spec position,
// rotation and scale plus the explode offset. The motion group is recomputed
// every frame from the part's spin, oscillate, crank and pulse motions, and
// holds the fill mesh (shaded surface, hidden-line occluder, pick target), the
// fat edge lines, child parts (which inherit the motion) and attached effects.
//
// The viewer owns the WebGL canvas and a label overlay. All other UI lives in
// runtime.js and talks to the viewer through the public methods below.

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
import { buildShape } from './shapes.js';
import { buildEffect, buildFlow } from './effects.js';

const DEG = Math.PI / 180;
const TAU = Math.PI * 2;
const AXIS_VEC = { x: new THREE.Vector3(1, 0, 0), y: new THREE.Vector3(0, 1, 0), z: new THREE.Vector3(0, 0, 1) };
const ISO_DIR = new THREE.Vector3(1, 0.82, 1).normalize();
// A spec can ask for 220 parts x 96 repeats; the viewer stops building
// instances past this so a pathological spec cannot freeze the tab.
const MAX_INSTANCES = 2400;
const MAX_EFFECT_INSTANCES = 96;
const DIM = 0.12;

const PALETTE = ['#4f8dff', '#ff8a3d', '#2fbf9b', '#c46cff', '#f2c14e', '#ff5d73', '#5cc8ff', '#8fd14f', '#b08968', '#9aa5b1'];

const THEMES = {
	dark: { bg: '#0b0e14', grid: '#1d2433', gridCenter: '#2a3448', accent: '#5eb0ff', ink: '#ffffff', inkMix: 0.4, fillMix: 0.42 },
	light: { bg: '#f5f6f8', grid: '#dfe3ea', gridCenter: '#c9d0db', accent: '#1f6fff', ink: '#0d1220', inkMix: 0.6, fillMix: 0 },
};

/**
 * The axis a spec's opening cutaway should use. A cut perpendicular to a
 * machine's long axis only shows one slice of it, so when the requested axis
 * is clearly the longest one, the request is read as "open it lengthwise" and
 * the cut moves to a short axis, preferring a side cut (z, then x) over a top
 * one. Any other request is honoured as written.
 */
export function openingSection(axis, size) {
	if (!axis || !size) return axis || null;
	const len = size[axis];
	const others = ['x', 'y', 'z'].filter((a) => a !== axis);
	if (!(len > 0) || others.some((a) => !(len >= size[a] * 1.6))) return axis;
	return ['z', 'x', 'y'].find((a) => a !== axis);
}

function hashIndex(s, n) {
	let h = 0;
	for (const ch of String(s)) h = (Math.imul(h, 31) + ch.charCodeAt(0)) | 0;
	return Math.abs(h) % n;
}

function resolveTheme(pref) {
	if (pref === 'dark' || pref === 'light') return pref;
	const attr = document.documentElement.getAttribute('data-theme');
	if (attr === 'dark' || attr === 'light') return attr;
	return window.matchMedia?.('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
}

export class AnatomyViewer {
	/**
	 * @param {HTMLElement} container  element the canvas and labels mount into
	 * @param {object} [opts]
	 * @param {'auto'|'dark'|'light'} [opts.theme]
	 * @param {(id: string|null, ev?: PointerEvent) => void} [opts.onHover]
	 * @param {(id: string|null) => void} [opts.onSelect]
	 */
	constructor(container, opts = {}) {
		this.container = container;
		this.opts = opts;
		this.themePref = opts.theme || 'auto';
		this.themeName = resolveTheme(this.themePref);

		this.renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: false, powerPreference: 'high-performance' });
		// Adaptive resolution: the ceiling is the screen's own ratio, and a GPU
		// that cannot hold the frame rate gets fewer pixels instead of a stutter.
		this.maxPixelRatio = Math.min(window.devicePixelRatio || 1, 2);
		this.pixelRatio = this.maxPixelRatio;
		this.frameCost = 1 / 60;
		this.frameSamples = 0;
		this.renderer.setPixelRatio(this.pixelRatio);
		this.renderer.localClippingEnabled = true;
		this.renderer.toneMapping = THREE.NeutralToneMapping;
		this.renderer.outputColorSpace = THREE.SRGBColorSpace;
		this.canvas = this.renderer.domElement;
		this.canvas.className = 'anx-canvas';
		this.canvas.setAttribute('aria-label', 'Interactive 3D machine view. Drag to rotate, scroll to zoom.');
		this.canvas.setAttribute('role', 'img');
		container.appendChild(this.canvas);

		this.labelLayer = document.createElement('div');
		this.labelLayer.className = 'anx-labels';
		this.labelLayer.setAttribute('aria-hidden', 'true');
		container.appendChild(this.labelLayer);

		this.scene = new THREE.Scene();
		const pmrem = new THREE.PMREMGenerator(this.renderer);
		this.envTexture = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
		pmrem.dispose();
		this.scene.environment = this.envTexture;
		this.scene.environmentIntensity = 0.75;
		this.key = new THREE.DirectionalLight('#ffffff', 1.4);
		this.key.position.set(4, 9, 6);
		this.scene.add(this.key, new THREE.HemisphereLight('#ffffff', '#445066', 0.55));

		this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.01, 1000);
		this.controls = new OrbitControls(this.camera, this.canvas);
		this.controls.enableDamping = true;
		this.controls.dampingFactor = 0.09;
		this.controls.zoomToCursor = true;
		this.controls.minZoom = 0.25;
		this.controls.maxZoom = 12;
		this.controls.addEventListener('start', () => {
			this.tween = null;
			this.autoRotateUntil = 0;
		});

		this.root = new THREE.Group();
		this.scene.add(this.root);
		this.grid = null;

		this.clipPlane = new THREE.Plane(new THREE.Vector3(0, 0, -1), 0);
		this.lineMaterials = new Set();
		this.geomCache = new Map();
		this.state = { playing: true, speed: 1, explode: 0, section: null, sectionPos: 0.5, xray: false, labels: true };
		this.focus = null;
		this.hoverId = null;
		this.selectedId = null;
		this.hidden = new Set();
		this.time = 0;
		this.radius = 1;
		this.tween = null;
		this.dirty = true;
		this.visible = true;
		this.raycaster = new THREE.Raycaster();
		this.pointer = new THREE.Vector2();
		this.pendingPick = null;

		this.reset();
		this.bindEvents();
		this.applyTheme();
		this.resize();
		this.timer = new THREE.Timer();
		this.renderer.setAnimationLoop(() => this.tick());
	}

	// ---------------------------------------------------------------- build

	reset() {
		this.parts = new Map(); // id -> { spec, mats, instances: [{pivot, motion, fill, edges}], children: [] }
		this.motionNodes = [];
		this.effects = [];
		this.flows = [];
		this.pickables = [];
		this.labelParts = [];
		this.instanceCount = 0;
		this.effectCount = 0;
	}

	clearScene() {
		for (const e of [...this.effects, ...this.flows]) {
			e.object.removeFromParent();
			e.dispose();
		}
		for (const p of this.parts.values()) {
			p.mats.fill.dispose();
			p.mats.edge.dispose();
			p.mats.back?.dispose();
			this.lineMaterials.delete(p.mats.edge);
		}
		for (const m of this.lineMaterials) m.dispose();
		this.lineMaterials.clear();
		this.root.clear();
		this.labelLayer.replaceChildren();
		this.reset();
	}

	/**
	 * Render a spec. `progressive` keeps the camera where it is and eases it
	 * to the new framing, for specs that grow while they stream in.
	 */
	load(spec, { progressive = false } = {}) {
		this.spec = spec;
		this.clearScene();
		const byId = new Map(spec.parts.map((p) => [p.id, p]));
		const childrenOf = new Map();
		for (const p of spec.parts) {
			const key = p.parent && byId.has(p.parent) ? p.parent : null;
			if (!childrenOf.has(key)) childrenOf.set(key, []);
			childrenOf.get(key).push(p);
		}
		this.childrenOf = childrenOf;
		const groups = [...new Set(spec.parts.map((p) => p.group).filter(Boolean))];
		for (const p of spec.parts) {
			const base = p.color || PALETTE[(p.group ? groups.indexOf(p.group) : hashIndex(p.id, PALETTE.length)) % PALETTE.length];
			this.parts.set(p.id, { spec: p, color: new THREE.Color(base), mats: this.makeMaterials(p), instances: [], effectAnchors: [] });
		}
		for (const p of childrenOf.get(null) || []) this.buildPart(p, this.root);

		const effectsByParent = new Map();
		for (const e of spec.effects) {
			const k = e.parent && this.parts.has(e.parent) ? e.parent : null;
			if (!effectsByParent.has(k)) effectsByParent.set(k, []);
			effectsByParent.get(k).push(e);
		}
		const ctx = { lineMaterial: (o) => this.makeLineMaterial(o) };
		for (const [parentId, list] of effectsByParent) {
			const anchors = parentId ? this.parts.get(parentId).instances.map((i) => i.motion) : [this.root];
			for (const eff of list) {
				for (const anchor of anchors) {
					if (this.effectCount >= MAX_EFFECT_INSTANCES) break;
					const built = buildEffect(eff, ctx);
					if (!built) continue;
					built.id = eff.id;
					anchor.add(built.object);
					this.effects.push(built);
					this.effectCount++;
				}
			}
		}
		for (const flow of spec.flows) {
			const built = buildFlow(flow, ctx);
			built.id = flow.id;
			this.root.add(built.object);
			this.flows.push(built);
		}
		// Shapes no longer in the spec free their geometry; shapes that are
		// still there (the common case while a spec streams in) are reused.
		for (const key of [...this.geomCache.keys()]) if (!this.geomCacheUsed?.has(key)) this.disposeGeom(key);
		this.geomCacheUsed = null;

		this.pickLabelParts();
		this.computeExplodeDirections();
		this.applyMotion(0);
		this.frameModel(progressive);
		this.applySection();
		this.applyExplode();
		this.refreshLooks();
		this.dirty = true;
		return { instances: this.instanceCount, truncated: this.instanceCount >= MAX_INSTANCES };
	}

	getGeometry(shape) {
		const key = JSON.stringify(shape);
		this.geomCacheUsed ??= new Set();
		this.geomCacheUsed.add(key);
		let g = this.geomCache.get(key);
		if (!g) {
			const { fill, lines } = buildShape(shape);
			fill.computeBoundingBox();
			fill.computeBoundingSphere();
			const lineGeom = new LineSegmentsGeometry();
			lineGeom.setPositions(lines);
			g = { fill, lineGeom, center: fill.boundingBox.getCenter(new THREE.Vector3()) };
			this.geomCache.set(key, g);
		}
		return g;
	}

	disposeGeom(key) {
		const g = this.geomCache.get(key);
		if (!g) return;
		g.fill.dispose();
		g.lineGeom.dispose();
		this.geomCache.delete(key);
	}

	makeLineMaterial({ color = '#ffffff', width = 1.2, dashed = false, dashSize = 0.1, gapSize = 0.05, transparent = false, opacity = 1 } = {}) {
		const m = new LineMaterial({ color: new THREE.Color(color), linewidth: width, dashed, dashSize, gapSize, transparent, opacity, worldUnits: false });
		m.resolution.set(this.width || 1, this.height || 1);
		this.lineMaterials.add(m);
		return m;
	}

	makeMaterials() {
		const fill = new THREE.MeshStandardMaterial({
			color: '#888888',
			metalness: 0.25,
			roughness: 0.55,
			side: THREE.DoubleSide,
			polygonOffset: true,
			polygonOffsetFactor: 1,
			polygonOffsetUnits: 1,
		});
		const edge = this.makeLineMaterial({ width: 1.25 });
		return { fill, edge, back: null, key: '' };
	}

	buildPart(part, parent) {
		const entry = this.parts.get(part.id);
		const rep = part.repeat;
		const count = rep ? rep.count : 1;
		for (let k = 0; k < count; k++) {
			if (this.instanceCount >= MAX_INSTANCES) return;
			this.instanceCount++;
			const repeatNode = new THREE.Group();
			if (rep?.mode === 'radial') {
				const span = rep.angle >= 360 ? (rep.angle / count) * k : count > 1 ? (rep.angle / (count - 1)) * k : 0;
				repeatNode.quaternion.setFromAxisAngle(AXIS_VEC[rep.axis], span * DEG);
			} else if (rep?.mode === 'linear') {
				repeatNode.position.set(rep.offset[0] * k, rep.offset[1] * k, rep.offset[2] * k);
			}
			const pivot = new THREE.Group();
			pivot.position.fromArray(part.position);
			pivot.rotation.set(part.rotation[0] * DEG, part.rotation[1] * DEG, part.rotation[2] * DEG);
			pivot.scale.fromArray(part.scale);
			pivot.userData.base = pivot.position.clone();
			const motion = new THREE.Group();
			motion.userData.motions = part.motion;
			const geom = this.getGeometry(part.shape);
			const fill = new THREE.Mesh(geom.fill, entry.mats.fill);
			fill.userData.partId = part.id;
			const edges = new LineSegments2(geom.lineGeom, entry.mats.edge);
			edges.userData.partId = part.id;
			edges.renderOrder = 2;
			motion.add(fill, edges);
			pivot.add(motion);
			repeatNode.add(pivot);
			parent.add(repeatNode);
			if (part.motion.length) this.motionNodes.push(motion);
			this.pickables.push(fill);
			entry.instances.push({ repeatNode, pivot, motion, fill, edges, center: geom.center });
			for (const child of this.childrenOf.get(part.id) || []) this.buildPart(child, motion);
		}
	}

	pickLabelParts() {
		const explicit = this.spec.parts.filter((p) => p.label === true);
		const pool = explicit.length ? explicit : (this.childrenOf.get(null) || []).filter((p) => p.label !== false).slice(0, 18);
		this.labelParts = pool.map((p) => {
			const el = document.createElement('div');
			el.className = 'anx-label';
			el.textContent = p.name;
			el.dataset.part = p.id;
			this.labelLayer.appendChild(el);
			return { id: p.id, el, w: 0, h: 0 };
		});
		this.labelExtra = new Map();
	}

	// --------------------------------------------------------------- motion

	applyMotion(t) {
		const q = new THREE.Quaternion();
		for (const node of this.motionNodes) {
			node.position.set(0, 0, 0);
			node.quaternion.identity();
			node.scale.set(1, 1, 1);
			for (const m of node.userData.motions) {
				const ph = (m.phase || 0) * DEG;
				if (m.type === 'spin') {
					q.setFromAxisAngle(AXIS_VEC[m.axis], TAU * m.speed * t + ph);
					node.quaternion.multiply(q);
				} else if (m.type === 'oscillate') {
					const s = Math.sin(TAU * m.frequency * t + ph);
					if (m.kind === 'rotate') {
						q.setFromAxisAngle(AXIS_VEC[m.axis], m.amplitude * DEG * s);
						node.quaternion.multiply(q);
					} else {
						node.position.addScaledVector(AXIS_VEC[m.axis], m.amplitude * s);
					}
				} else if (m.type === 'crank') {
					// Slider-crank: piston travel for crank radius r and rod
					// length l, centred so it swings between +r and -r.
					const th = TAU * m.speed * t + ph;
					const r = m.radius;
					const l = m.rod;
					const sin = Math.sin(th);
					const x = r * Math.cos(th) + Math.sqrt(Math.max(l * l - r * r * sin * sin, 0)) - l;
					node.position.addScaledVector(AXIS_VEC[m.axis], x);
				} else if (m.type === 'pulse') {
					node.scale.multiplyScalar(1 + m.amplitude * Math.sin(TAU * m.frequency * t + ph));
				}
			}
		}
	}

	// -------------------------------------------------------------- explode

	computeExplodeDirections() {
		this.root.updateMatrixWorld(true);
		const box = new THREE.Box3();
		for (const f of this.pickables) box.expandByObject(f);
		const center = box.isEmpty() ? new THREE.Vector3() : box.getCenter(new THREE.Vector3());
		const size = box.isEmpty() ? 1 : box.getSize(new THREE.Vector3()).length() / 2;
		const tops = this.childrenOf.get(null) || [];
		const fallback = new THREE.Vector3(0, 1, 0);
		for (const p of this.spec.parts) {
			const entry = this.parts.get(p.id);
			for (const inst of entry.instances) {
				if (p.explode) {
					inst.pivot.userData.explodeDir = new THREE.Vector3().fromArray(p.explode);
					continue;
				}
				if (!tops.includes(p)) {
					inst.pivot.userData.explodeDir = null;
					continue;
				}
				// Top-level parts fly outward from the model centre, scaled by
				// how far they already sit from it so the assembly order holds.
				const c = inst.fill.localToWorld(inst.center.clone());
				const d = c.sub(center);
				const len = d.length();
				const dir = len > size * 0.02 ? d.divideScalar(len) : fallback.clone();
				const parentQ = inst.pivot.parent.getWorldQuaternion(new THREE.Quaternion()).invert();
				dir.applyQuaternion(parentQ).multiplyScalar(size * 0.35 + len * 0.9);
				inst.pivot.userData.explodeDir = dir;
			}
		}
	}

	applyExplode() {
		const k = this.state.explode;
		for (const entry of this.parts.values()) {
			for (const inst of entry.instances) {
				const dir = inst.pivot.userData.explodeDir;
				inst.pivot.position.copy(inst.pivot.userData.base);
				if (dir && k > 0) inst.pivot.position.addScaledVector(dir, k);
			}
		}
		this.dirty = true;
	}

	// -------------------------------------------------------------- framing

	modelBox(ids = null) {
		this.root.updateMatrixWorld(true);
		const box = new THREE.Box3();
		const tmp = new THREE.Box3();
		const want = ids ? this.expandIds(ids) : null;
		for (const f of this.pickables) {
			if (want && !want.has(f.userData.partId)) continue;
			if (this.hidden.has(f.userData.partId)) continue;
			if (!f.geometry.boundingBox) f.geometry.computeBoundingBox();
			tmp.copy(f.geometry.boundingBox).applyMatrix4(f.matrixWorld);
			box.union(tmp);
		}
		if (ids) {
			for (const e of [...this.effects, ...this.flows]) if (ids.includes(e.id)) box.expandByObject(e.object);
		}
		return box;
	}

	frameModel(progressive) {
		this.root.position.set(0, 0, 0);
		const box = this.modelBox();
		if (box.isEmpty()) return;
		const center = box.getCenter(new THREE.Vector3());
		this.root.position.copy(center).negate();
		const size = box.getSize(new THREE.Vector3());
		this.radius = Math.max(size.length() / 2, 0.05);
		this.modelSize = size;
		this.modelMin = box.min.clone().sub(center);
		this.updateGrid();
		this.updateFrustum();
		const dist = this.radius * 6;
		this.camera.near = 0.01;
		this.camera.far = dist * 4;
		if (!progressive || !this.framed) {
			this.controls.target.set(0, 0, 0);
			this.camera.position.copy(ISO_DIR).multiplyScalar(dist);
			this.camera.zoom = this.fitZoom(ISO_DIR);
			this.camera.updateProjectionMatrix();
			this.controls.update();
			this.framed = true;
		} else {
			this.tween = { target: new THREE.Vector3(), zoom: this.fitZoom(ISO_DIR) };
		}
		this.camera.updateProjectionMatrix();
	}

	updateGrid() {
		if (this.grid) {
			this.grid.removeFromParent();
			this.grid.geometry.dispose();
			this.grid.material.dispose();
		}
		const extent = Math.max(this.modelSize.x, this.modelSize.z) * 1.8 + this.radius * 0.5;
		const step = 10 ** Math.floor(Math.log10(extent / 12));
		const divisions = Math.min(200, Math.max(4, Math.round(extent / step)));
		const t = THEMES[this.themeName];
		this.grid = new THREE.GridHelper(divisions * step, divisions, t.gridCenter, t.grid);
		this.grid.material.transparent = true;
		this.grid.material.opacity = 0.9;
		this.grid.material.depthWrite = false;
		this.grid.position.y = this.modelMin.y - this.radius * 0.04;
		this.grid.renderOrder = -1;
		this.scene.add(this.grid);
	}

	/**
	 * Zoom that fills the stage with the model as seen from `dir`. The frustum
	 * fits the bounding sphere so any rotation stays in frame; a long, thin
	 * machine seen side-on covers a fraction of that sphere, so the opening
	 * zoom fits its box's projected silhouette instead.
	 */
	fitZoom(dir, box = this.fitBox(), max = 3, target = new THREE.Vector3()) {
		if (!box || box.isEmpty()) return 1;
		const view = dir.clone().normalize();
		const right = new THREE.Vector3().crossVectors(new THREE.Vector3(0, 1, 0), view);
		if (right.lengthSq() < 1e-6) right.set(1, 0, 0);
		right.normalize();
		const up = new THREE.Vector3().crossVectors(view, right).normalize();
		let w = 0;
		let v = 0;
		const corner = new THREE.Vector3();
		for (const x of [box.min.x, box.max.x]) for (const y of [box.min.y, box.max.y]) for (const z of [box.min.z, box.max.z]) {
			corner.set(x, y, z).sub(target);
			w = Math.max(w, Math.abs(corner.dot(right)));
			v = Math.max(v, Math.abs(corner.dot(up)));
		}
		if (w < 1e-6 && v < 1e-6) return 1;
		const fit = Math.min(this.camera.right / Math.max(w * 1.1, 1e-6), this.camera.top / Math.max(v * 1.18, 1e-6));
		return THREE.MathUtils.clamp(fit, 1, max);
	}

	/** The whole picture for the opening shot: every visible part plus the effects and flows. */
	fitBox() {
		const box = this.modelBox();
		if (box.isEmpty()) return box;
		const tmp = new THREE.Box3();
		for (const e of [...this.effects, ...this.flows]) {
			tmp.setFromObject(e.object);
			if (!tmp.isEmpty()) box.union(tmp);
		}
		return box;
	}

	updateFrustum() {
		const aspect = (this.width || 1) / (this.height || 1);
		const half = this.radius * 1.12;
		const fitW = aspect >= 1 ? half * aspect : half;
		const fitH = aspect >= 1 ? half : half / aspect;
		this.camera.left = -fitW;
		this.camera.right = fitW;
		this.camera.top = fitH;
		this.camera.bottom = -fitH;
		this.camera.updateProjectionMatrix();
	}

	/** Ease the camera to frame a set of parts, or the whole model when ids is empty. */
	focusOn(ids) {
		if (!ids?.length) {
			this.tween = { target: new THREE.Vector3(), zoom: this.fitZoom(this.camera.position.clone().sub(this.controls.target)) };
			return;
		}
		const box = this.modelBox(ids);
		if (box.isEmpty()) return;
		const c = box.getCenter(new THREE.Vector3());
		box.expandByVector(new THREE.Vector3().setScalar(this.radius * 0.06));
		const zoom = this.fitZoom(this.camera.position.clone().sub(this.controls.target), box, 5, c) * 0.8;
		this.tween = { target: c, zoom };
	}

	resetView() {
		const dist = this.radius * 6;
		this.tween = null;
		this.controls.target.set(0, 0, 0);
		this.camera.position.copy(ISO_DIR).multiplyScalar(dist);
		this.camera.zoom = this.fitZoom(ISO_DIR);
		this.camera.updateProjectionMatrix();
		this.controls.update();
		this.dirty = true;
	}

	/** Snap to an orthographic view: 'iso', 'front', 'side', 'top'. */
	setView(name) {
		const dirs = { iso: ISO_DIR, front: new THREE.Vector3(0, 0, 1), side: new THREE.Vector3(1, 0, 0), top: new THREE.Vector3(0, 1, 0.0001) };
		const dir = (dirs[name] || ISO_DIR).clone().normalize();
		this.camera.position.copy(this.controls.target).addScaledVector(dir, this.radius * 6);
		this.camera.zoom = this.fitZoom(dir, this.fitBox(), 3, this.controls.target);
		this.camera.updateProjectionMatrix();
		this.controls.update();
		this.dirty = true;
	}

	// ---------------------------------------------------------------- looks

	expandIds(ids) {
		const out = new Set();
		const visit = (id) => {
			if (out.has(id)) return;
			out.add(id);
			for (const c of this.childrenOf?.get(id) || []) visit(c.id);
		};
		for (const id of ids) visit(id);
		return out;
	}

	refreshLooks() {
		const focusSet = this.focus ? this.expandIds(this.focus) : null;
		this.focusSet = focusSet;
		const t = THEMES[this.themeName];
		const bg = new THREE.Color(t.bg);
		const ink = new THREE.Color(t.ink);
		const accent = new THREE.Color(t.accent);
		for (const [id, entry] of this.parts) {
			const p = entry.spec;
			const dimmed = focusSet ? !focusSet.has(id) : false;
			const hovered = this.hoverId === id;
			const selected = this.selectedId === id;
			const hidden = this.hidden.has(id);
			const { fill, edge } = entry.mats;
			let style = p.style;
			if (this.state.xray && style === 'solid') style = 'xray';

			let opacity = 1;
			let transparent = false;
			let depthWrite = true;
			let colorWrite = true;
			if (style === 'glass') {
				opacity = 0.2;
				transparent = true;
				depthWrite = false;
			} else if (style === 'ghost') {
				opacity = 0.06;
				transparent = true;
				depthWrite = false;
			} else if (style === 'xray') {
				opacity = 0.1;
				transparent = true;
				depthWrite = false;
			} else if (style === 'wire') {
				colorWrite = false;
				depthWrite = false;
			}
			if (dimmed && colorWrite) {
				opacity = Math.min(opacity, 0.05);
				transparent = true;
				depthWrite = false;
			}
			fill.color.copy(entry.color).lerp(bg, t.fillMix);
			fill.opacity = opacity;
			fill.emissive.copy(entry.color).multiplyScalar(p.glow * 0.9);
			if (selected) fill.emissive.lerp(accent, 0.35);
			const key = `${transparent}|${depthWrite}|${colorWrite}`;
			if (key !== entry.mats.key) {
				fill.transparent = transparent;
				fill.depthWrite = depthWrite;
				fill.colorWrite = colorWrite;
				fill.needsUpdate = true;
				entry.mats.key = key;
			}

			const edgeColor = entry.color.clone().lerp(ink, t.inkMix);
			if (p.glow > 0 && this.themeName === 'dark') edgeColor.lerp(new THREE.Color('#ffffff'), p.glow * 0.3);
			edge.color.copy(hovered || selected ? accent : edgeColor);
			let edgeOpacity = style === 'ghost' ? 0.35 : style === 'glass' ? 0.85 : style === 'xray' ? 0.75 : 1;
			if (dimmed) edgeOpacity *= 0.16;
			edge.opacity = edgeOpacity;
			if (edge.transparent !== edgeOpacity < 1) {
				edge.transparent = edgeOpacity < 1;
				edge.needsUpdate = true;
			}
			edge.linewidth = hovered ? 2.6 : selected ? 2.2 : style === 'ghost' ? 1 : 1.25;
			for (const inst of entry.instances) {
				inst.fill.visible = !hidden;
				inst.edges.visible = !hidden;
				inst.fill.renderOrder = transparent ? 1 : 0;
			}
		}
		const effectDim = (id) => (focusSet && !focusSet.has(id) ? DIM : 1);
		for (const e of this.effects) e.setDim(effectDim(e.id));
		for (const f of this.flows) f.setDim(effectDim(f.id));
		this.dirty = true;
	}

	setFocus(ids) {
		this.focus = ids?.length ? ids : null;
		this.refreshLooks();
		this.focusOn(this.focus);
	}

	setHover(id) {
		if (this.hoverId === id) return;
		this.hoverId = id;
		this.canvas.style.cursor = id ? 'pointer' : '';
		this.refreshLooks();
	}

	setSelected(id) {
		this.selectedId = id;
		this.refreshLooks();
	}

	setPartVisible(id, visible) {
		if (visible) this.hidden.delete(id);
		else this.hidden.add(id);
		this.refreshLooks();
	}

	setXray(on) {
		this.state.xray = Boolean(on);
		this.refreshLooks();
	}

	setLabels(on) {
		this.state.labels = Boolean(on);
		this.labelLayer.hidden = !on;
		this.dirty = true;
	}

	setPlaying(on) {
		this.state.playing = Boolean(on);
		this.dirty = true;
	}

	setSpeed(s) {
		this.state.speed = s;
	}

	setExplode(k) {
		this.state.explode = THREE.MathUtils.clamp(k, 0, 1);
		this.applyExplode();
	}

	/** Cut the model with a plane normal to `axis` at `pos` (0..1 across the model). */
	setSection(axis, pos = this.state.sectionPos) {
		this.state.section = axis || null;
		this.state.sectionPos = THREE.MathUtils.clamp(pos, 0, 1);
		this.applySection();
	}

	applySection() {
		const axis = this.state.section;
		const planes = axis ? [this.clipPlane] : null;
		if (axis) {
			const half = (this.modelSize?.[axis] || 1) / 2;
			const c = -half * 1.02 + this.state.sectionPos * half * 2.04;
			this.clipPlane.normal.copy(AXIS_VEC[axis]).negate();
			this.clipPlane.constant = c;
		}
		for (const entry of this.parts.values()) {
			const { fill, edge } = entry.mats;
			const had = Boolean(fill.clippingPlanes?.length);
			fill.clippingPlanes = planes;
			edge.clippingPlanes = planes;
			if (had !== Boolean(planes)) {
				fill.needsUpdate = true;
				edge.needsUpdate = true;
			}
			if (axis) this.ensureCaps(entry);
			for (const inst of entry.instances) if (inst.back) inst.back.visible = Boolean(axis) && !this.hidden.has(entry.spec.id) && entry.spec.style === 'solid';
		}
		this.dirty = true;
	}

	// Section caps: back faces drawn in a flat cut colour read as solid
	// material where the plane slices through a closed part.
	ensureCaps(entry) {
		if (!entry.mats.back) {
			entry.mats.back = new THREE.MeshBasicMaterial({ side: THREE.BackSide, clippingPlanes: [this.clipPlane] });
		}
		entry.mats.back.color.copy(entry.color).lerp(new THREE.Color(THEMES[this.themeName].bg), 0.55);
		for (const inst of entry.instances) {
			if (inst.back) continue;
			inst.back = new THREE.Mesh(inst.fill.geometry, entry.mats.back);
			inst.back.raycast = () => {};
			inst.fill.parent.add(inst.back);
		}
	}

	// ---------------------------------------------------------------- theme

	setTheme(pref) {
		this.themePref = pref;
		this.applyTheme();
	}

	applyTheme() {
		this.themeName = resolveTheme(this.themePref);
		const t = THEMES[this.themeName];
		this.scene.background = new THREE.Color(t.bg);
		(this.container.closest('.anx') || this.container).dataset.anxTheme = this.themeName;
		if (this.modelSize) this.updateGrid();
		for (const entry of this.parts.values()) if (entry.mats.back) entry.mats.back.color.copy(entry.color).lerp(new THREE.Color(t.bg), 0.55);
		this.refreshLooks();
	}

	// --------------------------------------------------------------- events

	bindEvents() {
		this.onResize = () => this.resize();
		this.resizeObserver = new ResizeObserver(this.onResize);
		this.resizeObserver.observe(this.container);
		this.visObserver = new IntersectionObserver((entries) => {
			this.visible = entries.some((e) => e.isIntersecting);
		});
		this.visObserver.observe(this.container);
		this.themeObserver = new MutationObserver(() => {
			if (this.themePref === 'auto') this.applyTheme();
		});
		this.themeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });

		let down = null;
		this.onPointerDown = (e) => {
			down = { x: e.clientX, y: e.clientY };
		};
		this.onPointerMove = (e) => {
			if (e.buttons) return;
			this.pendingPick = { x: e.clientX, y: e.clientY, ev: e };
		};
		this.onPointerUp = (e) => {
			if (!down || Math.hypot(e.clientX - down.x, e.clientY - down.y) > 5) return;
			down = null;
			const id = this.pick(e.clientX, e.clientY);
			this.opts.onSelect?.(id);
		};
		this.onPointerLeave = () => {
			this.pendingPick = null;
			this.setHover(null);
			this.opts.onHover?.(null);
		};
		this.canvas.addEventListener('pointerdown', this.onPointerDown);
		this.canvas.addEventListener('pointermove', this.onPointerMove);
		this.canvas.addEventListener('pointerup', this.onPointerUp);
		this.canvas.addEventListener('pointerleave', this.onPointerLeave);
	}

	pick(clientX, clientY) {
		const rect = this.canvas.getBoundingClientRect();
		this.pointer.set(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
		this.raycaster.setFromCamera(this.pointer, this.camera);
		const hits = this.raycaster.intersectObjects(this.pickables, false);
		const clip = this.state.section ? this.clipPlane : null;
		for (const h of hits) {
			const id = h.object.userData.partId;
			if (!h.object.visible || this.hidden.has(id)) continue;
			if (clip && clip.distanceToPoint(h.point) < 0) continue;
			if (this.focusSet && !this.focusSet.has(id)) continue;
			return id;
		}
		return null;
	}

	resize() {
		const r = this.container.getBoundingClientRect();
		this.width = Math.max(1, Math.round(r.width));
		this.height = Math.max(1, Math.round(r.height));
		this.renderer.setSize(this.width, this.height, false);
		this.canvas.style.width = '100%';
		this.canvas.style.height = '100%';
		for (const m of this.lineMaterials) m.resolution.set(this.width, this.height);
		this.updateFrustum();
		this.dirty = true;
	}

	// ----------------------------------------------------------------- loop

	tick() {
		this.timer.update();
		const raw = this.timer.getDelta();
		const dt = Math.min(raw, 0.1);
		if (!this.visible || document.hidden) {
			this.frameSamples = 0;
			return;
		}
		if (this.pendingPick) {
			const { x, y, ev } = this.pendingPick;
			this.pendingPick = null;
			const id = this.pick(x, y);
			if (id !== this.hoverId) {
				this.setHover(id);
			}
			this.opts.onHover?.(id, ev);
		}
		if (this.tween) {
			const k = 1 - Math.exp(-dt * 7);
			this.controls.target.lerp(this.tween.target, k);
			const offset = this.camera.position.clone().sub(this.controls.target).normalize().multiplyScalar(this.radius * 6);
			this.camera.position.copy(this.controls.target).add(offset);
			this.camera.zoom += (this.tween.zoom - this.camera.zoom) * k;
			this.camera.updateProjectionMatrix();
			if (this.controls.target.distanceTo(this.tween.target) < this.radius * 1e-3 && Math.abs(this.camera.zoom - this.tween.zoom) < 1e-3) this.tween = null;
			this.dirty = true;
		}
		const moved = this.controls.update();
		if (moved) this.dirty = true;
		const animating = this.state.playing && this.state.speed > 0;
		if (animating) {
			this.time += dt * this.state.speed * (this.spec?.view?.speed ?? 1);
			this.applyMotion(this.time);
		}
		if (!animating && !this.dirty) return;

		const frame = {
			dark: this.themeName === 'dark',
			pixelScale: (this.renderer.getPixelRatio() * this.height * this.camera.zoom) / (this.camera.top - this.camera.bottom),
		};
		const effectDt = animating ? dt * this.state.speed : 0;
		for (const e of this.effects) e.update(this.time, effectDt, frame);
		for (const f of this.flows) f.update(this.time, effectDt, frame);
		this.renderer.render(this.scene, this.camera);
		if (this.state.labels) this.updateLabels();
		this.dirty = false;
		if (animating) this.adaptResolution(raw);
		this.opts.onFrame?.();
	}

	/**
	 * Track the smoothed frame time while the machine animates. Sustained slow
	 * frames step the pixel ratio down; sustained headroom steps it back up to
	 * the screen's ratio. Steps are spaced out so the image never flickers.
	 */
	adaptResolution(dt) {
		if (dt <= 0 || dt > 10) return;
		this.frameCost += (dt - this.frameCost) * 0.1;
		this.frameSamples++;
		if (this.frameSamples < 30) return;
		let next = this.pixelRatio;
		if (this.frameCost > 1 / 30) next = Math.max(0.5, this.pixelRatio * 0.75);
		else if (this.frameCost < 1 / 70) next = Math.min(this.maxPixelRatio, this.pixelRatio / 0.75);
		if (Math.abs(next - this.pixelRatio) < 0.01) return;
		this.pixelRatio = next;
		this.frameSamples = 0;
		this.renderer.setPixelRatio(next);
		this.renderer.setSize(this.width, this.height, false);
		this.dirty = true;
	}

	/** Project label anchors to screen and hide the ones that would overlap. */
	updateLabels() {
		const placed = [];
		const v = new THREE.Vector3();
		const order = [...this.labelParts].sort((a, b) => {
			const pa = a.id === this.selectedId || a.id === this.hoverId || this.focusSet?.has(a.id) ? 0 : 1;
			const pb = b.id === this.selectedId || b.id === this.hoverId || this.focusSet?.has(b.id) ? 0 : 1;
			return pa - pb;
		});
		for (const label of order) {
			const entry = this.parts.get(label.id);
			const inst = entry?.instances[0];
			const show = inst && !this.hidden.has(label.id) && (!this.focusSet || this.focusSet.has(label.id));
			if (!show) {
				label.el.hidden = true;
				continue;
			}
			v.copy(inst.center);
			inst.fill.localToWorld(v);
			v.project(this.camera);
			const x = (v.x * 0.5 + 0.5) * this.width;
			const y = (-v.y * 0.5 + 0.5) * this.height;
			if (!label.w) {
				label.el.hidden = false;
				label.w = label.el.offsetWidth;
				label.h = label.el.offsetHeight;
			}
			const rect = { l: x - label.w / 2, t: y - label.h - 10, r: x + label.w / 2, b: y - 10 };
			const offscreen = rect.l < 0 || rect.r > this.width || rect.t < 0 || y > this.height;
			const overlaps = placed.some((p) => !(rect.r + 4 < p.l || rect.l - 4 > p.r || rect.b + 2 < p.t || rect.t - 2 > p.b));
			if (offscreen || overlaps) {
				label.el.hidden = true;
				continue;
			}
			placed.push(rect);
			label.el.hidden = false;
			label.el.style.transform = `translate(${Math.round(rect.l)}px, ${Math.round(rect.t)}px)`;
			label.el.classList.toggle('is-active', label.id === this.hoverId || label.id === this.selectedId);
		}
	}

	/** Screen position of a part's first instance, for tooltips. */
	screenPoint(id) {
		const inst = this.parts.get(id)?.instances[0];
		if (!inst) return null;
		const v = inst.center.clone();
		inst.fill.localToWorld(v);
		v.project(this.camera);
		return { x: (v.x * 0.5 + 0.5) * this.width, y: (-v.y * 0.5 + 0.5) * this.height };
	}

	/** PNG of the current frame at 2x device resolution. */
	async screenshot() {
		const prev = this.renderer.getPixelRatio();
		this.renderer.setPixelRatio(Math.min(this.maxPixelRatio * 2, 3));
		this.renderer.setSize(this.width, this.height, false);
		const frame = { dark: this.themeName === 'dark', pixelScale: (this.renderer.getPixelRatio() * this.height * this.camera.zoom) / (this.camera.top - this.camera.bottom) };
		for (const e of this.effects) e.update(this.time, 0, frame);
		for (const f of this.flows) f.update(this.time, 0, frame);
		this.renderer.render(this.scene, this.camera);
		const blob = await new Promise((resolve) => this.canvas.toBlob(resolve, 'image/png'));
		this.renderer.setPixelRatio(prev);
		this.renderer.setSize(this.width, this.height, false);
		this.dirty = true;
		return blob;
	}

	dispose() {
		this.renderer.setAnimationLoop(null);
		this.timer.dispose();
		this.resizeObserver.disconnect();
		this.visObserver.disconnect();
		this.themeObserver.disconnect();
		this.canvas.removeEventListener('pointerdown', this.onPointerDown);
		this.canvas.removeEventListener('pointermove', this.onPointerMove);
		this.canvas.removeEventListener('pointerup', this.onPointerUp);
		this.canvas.removeEventListener('pointerleave', this.onPointerLeave);
		this.clearScene();
		for (const key of [...this.geomCache.keys()]) this.disposeGeom(key);
		if (this.grid) {
			this.grid.geometry.dispose();
			this.grid.material.dispose();
		}
		this.envTexture.dispose();
		this.controls.dispose();
		this.renderer.dispose();
		this.canvas.remove();
		this.labelLayer.remove();
	}
}