@yggy-tech/graphraum 0.28.0 → 0.34.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Box3, CanvasTexture, Color, InstancedBufferAttribute, InstancedMesh, MOUSE, Matrix4, MeshBasicMaterial, OrthographicCamera, PerspectiveCamera, Plane, PlaneGeometry, Raycaster, RepeatWrapping, SRGBColorSpace, Scene, ShaderMaterial, SphereGeometry, Texture, Vector2, Vector3, WebGLRenderer } from "three";
+import { AdditiveBlending, Box3, CanvasTexture, Color, InstancedBufferAttribute, InstancedMesh, MOUSE, Matrix4, MeshBasicMaterial, NormalBlending, OrthographicCamera, PerspectiveCamera, Plane, PlaneGeometry, Raycaster, RepeatWrapping, SRGBColorSpace, Scene, ShaderMaterial, SphereGeometry, TOUCH, Texture, Vector2, Vector3, WebGLRenderer } from "three";
 import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 //#region src/node-axes.ts
 function assertPositiveFinite(value, axis, nodeId) {
@@ -100,7 +100,12 @@ function containsNodePoint(shape, x, y) {
 //#region src/edge-endpoint-attach.ts
 const DEFAULT_ENDPOINT_ATTACH = "boundary";
 const DEFAULT_ENDPOINT_CLEARANCE = .75;
-function isInsideOutline(outline, worldX, worldY, center) {
+/**
+* Distance from the node center to its outline (stroke included) along a unit heading in the
+* billboard plane, in world units. Every shape fits its `[-1, 1]` box, so the box diagonal bounds
+* the search.
+*/
+function outlineRadius(outline, headingX, headingY) {
 	const { height, width } = resolveNodeAxes({
 		height: outline.height,
 		size: outline.size,
@@ -109,14 +114,28 @@ function isInsideOutline(outline, worldX, worldY, center) {
 	const stroke = Math.max(0, outline.strokeWidth ?? 0);
 	const halfWidth = width + stroke;
 	const halfHeight = height + stroke;
-	if (halfWidth <= 0 || halfHeight <= 0) return false;
-	return containsNodePoint(outline.shape, (worldX - center.x) / halfWidth, (worldY - center.y) / halfHeight);
+	let low = 0;
+	let high = Math.hypot(halfWidth, halfHeight);
+	for (let step = 0; step < 24; step += 1) {
+		const mid = (low + high) / 2;
+		if (containsNodePoint(outline.shape, headingX * mid / halfWidth, headingY * mid / halfHeight)) low = mid;
+		else high = mid;
+	}
+	return low;
 }
 /**
 * Walk from the node center toward the far point and stop on the outline,
 * then pull back by `clearance` so the stroke is not stabbed.
+*
+* In `2d` the outline lies in the xy plane, so only the xy part of the chord counts. In `3d` the
+* billboard faces the camera, so the edge stops one outline radius from the center along the 3D
+* segment. The radius is measured along the chord's world xy heading (or +x when the chord is
+* parallel to z), not along its on-screen heading. For circles the radius is the same in every
+* direction, so the projected end lies on the outline or inside it (where the node covers the
+* edge) from every view. Other shapes are approximate in 3D: an elongated or angular node can end
+* inside its outline or short of it, depending on the camera.
 */
-function attachPointOnOutline(center, far, outline, clearance = DEFAULT_ENDPOINT_CLEARANCE) {
+function attachPointOnOutline(center, far, outline, clearance = DEFAULT_ENDPOINT_CLEARANCE, mode = "2d") {
 	const dx = far.x - center.x;
 	const dy = far.y - center.y;
 	const dz = (far.z ?? 0) - (center.z ?? 0);
@@ -126,15 +145,12 @@ function attachPointOnOutline(center, far, outline, clearance = DEFAULT_ENDPOINT
 		y: center.y,
 		z: center.z ?? 0
 	};
-	let low = 0;
-	let high = 1;
-	for (let step = 0; step < 24; step += 1) {
-		const mid = (low + high) / 2;
-		if (isInsideOutline(outline, center.x + dx * mid, center.y + dy * mid, center)) low = mid;
-		else high = mid;
-	}
+	const planar = Math.hypot(dx, dy);
+	const reach = mode === "3d" ? length : planar;
+	const radius = planar < 1e-6 ? outlineRadius(outline, 1, 0) : outlineRadius(outline, dx / planar, dy / planar);
+	const outlineT = reach < 1e-6 ? 1 : Math.min(1, radius / reach);
 	const clearanceT = Math.min(Math.max(clearance, 0) / length, .45);
-	const t = Math.max(0, low - clearanceT);
+	const t = Math.max(0, outlineT - clearanceT);
 	return {
 		x: center.x + dx * t,
 		y: center.y + dy * t,
@@ -156,8 +172,8 @@ function trimEdgeEndpoints(input) {
 		}
 	};
 	const clearance = input.clearance ?? .75;
-	const source = attachPointOnOutline(input.source, input.target, input.sourceOutline, clearance);
-	const target = attachPointOnOutline(input.target, input.source, input.targetOutline, clearance);
+	const source = attachPointOnOutline(input.source, input.target, input.sourceOutline, clearance, input.mode);
+	const target = attachPointOnOutline(input.target, input.source, input.targetOutline, clearance, input.mode);
 	const ox = input.target.x - input.source.x;
 	const oy = input.target.y - input.source.y;
 	const oz = (input.target.z ?? 0) - (input.source.z ?? 0);
@@ -245,6 +261,7 @@ function encodeEdgeStyle(style) {
 //#region src/force-layout.ts
 const DEFAULT_FORCE_SETTINGS = {
 	centerAttraction: .002,
+	clusterStrength: .02,
 	damping: .82,
 	linkDistance: 24,
 	repulsion: 400,
@@ -253,6 +270,7 @@ const DEFAULT_FORCE_SETTINGS = {
 function normalizeForceSettings(settings = DEFAULT_FORCE_SETTINGS) {
 	return {
 		centerAttraction: Math.max(0, Math.min(.05, settings.centerAttraction)),
+		clusterStrength: Math.max(0, Math.min(.1, settings.clusterStrength ?? DEFAULT_FORCE_SETTINGS.clusterStrength)),
 		damping: Math.max(.1, Math.min(.99, settings.damping)),
 		linkDistance: Math.max(1, Math.min(500, settings.linkDistance)),
 		repulsion: Math.max(0, Math.min(5e3, settings.repulsion)),
@@ -311,6 +329,60 @@ function random(seed) {
 	value = Math.imul(value ^ value >>> 13, 3266489909);
 	return ((value ^ value >>> 16) >>> 0) / 4294967296;
 }
+function assertClusterCount(clusters, expected, subject) {
+	if (clusters.length !== expected) throw new Error(`Cluster index count (${clusters.length}) must match ${subject} (${expected}).`);
+}
+/**
+* Live simulations index per-cluster scratch arrays by id, so ids must be dense: below the node count.
+* Validate before allocating anything.
+*/
+function assertDenseClusterIds(clusters, totalNodeCount) {
+	for (const cluster of clusters) if (cluster >= totalNodeCount) throw new Error(`Cluster index ${cluster} exceeds the node count ${totalNodeCount}; use dense ids starting at 0.`);
+}
+function clusterCountOf(clusters) {
+	let clusterCount = 0;
+	for (const cluster of clusters) clusterCount = Math.max(clusterCount, cluster + 1);
+	return clusterCount;
+}
+/**
+* Seeds nodes around cluster centres: centres come from a force layout of the inter-cluster graph
+* and each node is scattered around its centre. Shared by the one-shot and live clustered layouts.
+*/
+function clusteredInitialPositions(request) {
+	const clusterCount = clusterCountOf(request.clusters);
+	const clusterEdges = new Uint32Array(request.edges.length);
+	let edgeCursor = 0;
+	for (let index = 0; index < request.edges.length; index += 2) {
+		const source = request.clusters[request.edges[index] ?? 0];
+		const target = request.clusters[request.edges[index + 1] ?? 0];
+		if (source === void 0 || target === void 0 || source === target) continue;
+		clusterEdges[edgeCursor++] = source;
+		clusterEdges[edgeCursor++] = target;
+	}
+	const centers = computeForcePositions({
+		dimensions: request.dimensions,
+		edges: clusterEdges.subarray(0, edgeCursor),
+		nodeCount: clusterCount,
+		settings: request.settings
+	});
+	const clusterSizes = new Uint32Array(clusterCount);
+	for (const cluster of request.clusters) clusterSizes[cluster] += 1;
+	const positions = new Float32Array(request.nodeCount * 3);
+	for (let index = 0; index < request.nodeCount; index += 1) {
+		const offset = index * 3;
+		const cluster = request.clusters[index] ?? 0;
+		const center = cluster * 3;
+		const radius = Math.sqrt(clusterSizes[cluster] ?? 1) * Math.sqrt(random(index * 4 + 2)) * 2;
+		const angle = random(index * 4 + 1) * Math.PI * 2;
+		positions[offset] = (centers[center] ?? 0) * 12 + Math.cos(angle) * radius;
+		positions[offset + 1] = (centers[center + 1] ?? 0) * 12 + Math.sin(angle) * radius;
+		if (request.dimensions === 3) {
+			const zDirection = random(index * 4 + 3) * 2 - 1;
+			positions[offset + 2] = (centers[center + 2] ?? 0) * 12 + zDirection * radius;
+		}
+	}
+	return positions;
+}
 function createForceSimulation(request) {
 	const settings = normalizeForceSettings(request.settings);
 	let nodeCount = request.nodeCount;
@@ -319,10 +391,41 @@ function createForceSimulation(request) {
 	const edgeCount = edges.length / 2;
 	let linkDistances = normalizePerEdgeArray("linkDistances", request.linkDistances, edgeCount, clampLinkDistance);
 	let springStrengths = normalizePerEdgeArray("springStrengths", request.springStrengths, edgeCount, clampSpringStrength);
-	let positions = initialPositions(request);
+	let clusters = null;
+	if (request.clusters) {
+		assertClusterCount(request.clusters, request.nodeCount, "node count");
+		assertDenseClusterIds(request.clusters, request.nodeCount);
+		clusters = new Uint32Array(request.clusters);
+	}
+	let positions = clusters ? clusteredInitialPositions({
+		...request,
+		clusters
+	}) : initialPositions(request);
 	let velocities = new Float32Array(positions.length);
 	let forces = new Float32Array(positions.length);
 	let iteration = 0;
+	let clusterCount = clusters ? clusterCountOf(clusters) : 0;
+	let clusterCentroids = new Float64Array(clusterCount * 3);
+	let clusterSizes = new Uint32Array(clusterCount);
+	/** Mean position per cluster in O(N): no per-node allocation. */
+	function updateClusterCentroids(activeClusters) {
+		clusterCentroids.fill(0);
+		clusterSizes.fill(0);
+		for (let index = 0; index < nodeCount; index += 1) {
+			const cluster = activeClusters[index] ?? 0;
+			const offset = index * 3;
+			const centroid = cluster * 3;
+			clusterSizes[cluster] += 1;
+			clusterCentroids[centroid] += positions[offset] ?? 0;
+			clusterCentroids[centroid + 1] += positions[offset + 1] ?? 0;
+			if (request.dimensions === 3) clusterCentroids[centroid + 2] += positions[offset + 2] ?? 0;
+		}
+		for (let cluster = 0; cluster < clusterCount; cluster += 1) {
+			const size = clusterSizes[cluster] ?? 0;
+			if (size === 0) continue;
+			for (let axis = 0; axis < request.dimensions; axis += 1) clusterCentroids[cluster * 3 + axis] /= size;
+		}
+	}
 	return {
 		get nodeCount() {
 			return nodeCount;
@@ -333,10 +436,20 @@ function createForceSimulation(request) {
 		get positions() {
 			return positions;
 		},
-		/** Add nodes while preserving every existing position and velocity. */
-		addNodes(count, initial) {
+		/**
+		* Add nodes while preserving every existing position and velocity. A simulation created with
+		* `clusters` requires one cluster index per added node (a new id starts a new cluster); a
+		* simulation created without clusters rejects them.
+		*/
+		addNodes(count, initial, addedClusters) {
 			if (!Number.isSafeInteger(count) || count < 1) throw new Error("Node count must be a positive integer.");
 			if (initial && initial.length !== count * 3) throw new Error("Initial positions must contain one XYZ triplet per added node.");
+			if (clusters && !addedClusters) throw new Error("This simulation was created with clusters: addNodes() requires a clusters array.");
+			if (!clusters && addedClusters) throw new Error("This simulation was created without clusters: addNodes() cannot take a clusters array.");
+			if (addedClusters) {
+				assertClusterCount(addedClusters, count, "added node count");
+				assertDenseClusterIds(addedClusters, nodeCount + count);
+			}
 			const start = nodeCount;
 			const nextPositions = new Float32Array((nodeCount + count) * 3);
 			nextPositions.set(positions);
@@ -352,6 +465,24 @@ function createForceSimulation(request) {
 				});
 				nextPositions.set(added, positions.length);
 			}
+			let nextClusters = clusters;
+			let nextClusterCount = clusterCount;
+			let nextCentroids = clusterCentroids;
+			let nextSizes = clusterSizes;
+			if (clusters && addedClusters) {
+				nextClusters = new Uint32Array(nodeCount + count);
+				nextClusters.set(clusters);
+				nextClusters.set(addedClusters, nodeCount);
+				nextClusterCount = Math.max(clusterCount, clusterCountOf(addedClusters));
+				if (nextClusterCount !== clusterCount) {
+					nextCentroids = new Float64Array(nextClusterCount * 3);
+					nextSizes = new Uint32Array(nextClusterCount);
+				}
+			}
+			clusters = nextClusters;
+			clusterCount = nextClusterCount;
+			clusterCentroids = nextCentroids;
+			clusterSizes = nextSizes;
 			positions = nextPositions;
 			velocities = nextVelocities;
 			forces = nextForces;
@@ -383,11 +514,18 @@ function createForceSimulation(request) {
 		step(alpha) {
 			if (nodeCount === 0) return;
 			forces.fill(0);
+			const pullClusters = clusters && settings.clusterStrength > 0 ? clusters : null;
+			const clusterPull = settings.clusterStrength * alpha;
+			if (pullClusters) updateClusterCentroids(pullClusters);
 			for (let index = 0; index < nodeCount; index += 1) {
 				const offset = index * 3;
 				forces[offset] = -(positions[offset] ?? 0) * settings.centerAttraction * alpha;
 				forces[offset + 1] = -(positions[offset + 1] ?? 0) * settings.centerAttraction * alpha;
 				forces[offset + 2] = request.dimensions === 3 ? -(positions[offset + 2] ?? 0) * settings.centerAttraction * alpha : 0;
+				if (pullClusters) {
+					const centroid = (pullClusters[index] ?? 0) * 3;
+					for (let axis = 0; axis < request.dimensions; axis += 1) forces[offset + axis] += ((clusterCentroids[centroid + axis] ?? 0) - (positions[offset + axis] ?? 0)) * clusterPull;
+				}
 				for (let sample = 0; sample < 8; sample += 1) {
 					const targetIndex = Math.floor(random(index * 97 + sample * 17 + iteration * 13) * nodeCount);
 					if (targetIndex === index) continue;
@@ -469,41 +607,8 @@ function computeForcePositions(request) {
 	return simulation.positions;
 }
 function computeClusteredForcePositions(request) {
-	if (request.clusters.length !== request.nodeCount) throw new Error("Cluster index count must match node count.");
-	let clusterCount = 0;
-	for (const cluster of request.clusters) clusterCount = Math.max(clusterCount, cluster + 1);
-	const clusterEdges = new Uint32Array(request.edges.length);
-	let edgeCursor = 0;
-	for (let index = 0; index < request.edges.length; index += 2) {
-		const source = request.clusters[request.edges[index] ?? 0];
-		const target = request.clusters[request.edges[index + 1] ?? 0];
-		if (source === void 0 || target === void 0 || source === target) continue;
-		clusterEdges[edgeCursor++] = source;
-		clusterEdges[edgeCursor++] = target;
-	}
-	const centers = computeForcePositions({
-		dimensions: request.dimensions,
-		edges: clusterEdges.subarray(0, edgeCursor),
-		nodeCount: clusterCount,
-		settings: request.settings
-	});
-	const clusterSizes = new Uint32Array(clusterCount);
-	for (const cluster of request.clusters) clusterSizes[cluster] += 1;
-	const positions = new Float32Array(request.nodeCount * 3);
-	for (let index = 0; index < request.nodeCount; index += 1) {
-		const offset = index * 3;
-		const cluster = request.clusters[index] ?? 0;
-		const center = cluster * 3;
-		const radius = Math.sqrt(clusterSizes[cluster] ?? 1) * Math.sqrt(random(index * 4 + 2)) * 2;
-		const angle = random(index * 4 + 1) * Math.PI * 2;
-		positions[offset] = (centers[center] ?? 0) * 12 + Math.cos(angle) * radius;
-		positions[offset + 1] = (centers[center + 1] ?? 0) * 12 + Math.sin(angle) * radius;
-		if (request.dimensions === 3) {
-			const zDirection = random(index * 4 + 3) * 2 - 1;
-			positions[offset + 2] = (centers[center + 2] ?? 0) * 12 + zDirection * radius;
-		}
-	}
-	return positions;
+	assertClusterCount(request.clusters, request.nodeCount, "node count");
+	return clusteredInitialPositions(request);
 }
 //#endregion
 //#region src/graphology.ts
@@ -570,6 +675,188 @@ function bindGraphology(renderer, graph) {
 		graph.off("edgesCleared", schedule);
 	};
 }
+/** Longest frame step the orbit applies, so a throttled or backgrounded tab does not jump on return. */
+const AUTO_ORBIT_MAX_DELTA_SECONDS = .1;
+const AUTO_ORBIT_OFF = {
+	enabled: false,
+	hidden: false,
+	interacting: false,
+	offscreen: false
+};
+function resolveAutoOrbitOptions(options) {
+	const speed = options.speed ?? .07;
+	const resumeAfterMs = options.resumeAfterMs ?? 3e3;
+	if (!Number.isFinite(speed) || speed <= 0 || speed > 2) throw new Error(`Auto-orbit speed must be a finite number above 0 and at most 2 radians per second; received ${speed}.`);
+	if (!Number.isFinite(resumeAfterMs) || resumeAfterMs < 0) throw new Error(`Auto-orbit resumeAfterMs must be a non-negative finite number of milliseconds; received ${resumeAfterMs}.`);
+	return {
+		speed,
+		resumeAfterMs
+	};
+}
+function nextAutoOrbitState(state, event) {
+	if (event.type === "enable") return state.enabled ? {
+		...state,
+		hidden: event.hidden
+	} : {
+		...AUTO_ORBIT_OFF,
+		enabled: true,
+		hidden: event.hidden
+	};
+	if (!state.enabled) return state;
+	switch (event.type) {
+		case "disable": return AUTO_ORBIT_OFF;
+		case "interaction": return {
+			...state,
+			interacting: true
+		};
+		case "idle": return {
+			...state,
+			interacting: false
+		};
+		case "visibility": return {
+			...state,
+			hidden: event.hidden
+		};
+		case "intersection": return {
+			...state,
+			offscreen: event.offscreen
+		};
+	}
+}
+function autoOrbitStatus(state) {
+	if (!state.enabled) return "off";
+	return state.hidden || state.interacting || state.offscreen ? "paused" : "active";
+}
+/** Seconds between two animation-frame timestamps, zero on the first frame, clamped to `[0, AUTO_ORBIT_MAX_DELTA_SECONDS]`. */
+function autoOrbitDeltaSeconds(previousMs, nowMs) {
+	if (previousMs === null) return 0;
+	return Math.min(Math.max((nowMs - previousMs) / 1e3, 0), AUTO_ORBIT_MAX_DELTA_SECONDS);
+}
+/**
+* OrbitControls (three r185) rotates `(2π / 60) * autoRotateSpeed * deltaTime` radians when
+* `update(deltaTime)` receives seconds (and a fixed per-call step without it). Inverting that
+* gives an `autoRotateSpeed` for which `update(dtSeconds)` turns exactly `radiansPerSecond`,
+* independent of frame rate.
+*/
+function autoRotateSpeedFor(radiansPerSecond) {
+	return radiansPerSecond * 60 / (2 * Math.PI);
+}
+//#endregion
+//#region src/auto-orbit-loop.ts
+/**
+* Owns the auto-orbit frame loop and the browser signals that stop it. The loop exists only
+* while the orbit is active: pointer, wheel and key input pause it until `resumeAfterMs` of
+* idle, and a hidden document or an off-screen element stop it until they change back.
+* Decisions come from the pure state in `auto-orbit.ts`; this class only wires DOM events,
+* the resume timer and `requestAnimationFrame`. Interaction comes from the controls' `start`
+* and `end` events, so multi-touch and lost pointer capture end the pause only once the last
+* pointer lifts. DOM overlays above the canvas do not reach the controls and do not pause it.
+*/
+var AutoOrbitLoop = class {
+	element;
+	interactions;
+	resumeAfterMs;
+	step;
+	state;
+	frame = null;
+	lastFrameMs = null;
+	resumeTimer = null;
+	observer;
+	constructor(element, interactions, resumeAfterMs, step) {
+		this.element = element;
+		this.interactions = interactions;
+		this.resumeAfterMs = resumeAfterMs;
+		this.step = step;
+		this.state = nextAutoOrbitState(AUTO_ORBIT_OFF, {
+			type: "enable",
+			hidden: element.ownerDocument.hidden
+		});
+		interactions.addEventListener("start", this.handleInteractionStart);
+		interactions.addEventListener("end", this.handleInteractionEnd);
+		element.ownerDocument.addEventListener("visibilitychange", this.handleVisibilityChange);
+		this.observer = typeof IntersectionObserver === "undefined" ? null : new IntersectionObserver(this.handleIntersection);
+		this.observer?.observe(element);
+		this.sync();
+	}
+	get status() {
+		return autoOrbitStatus(this.state);
+	}
+	setResumeAfterMs(resumeAfterMs) {
+		this.resumeAfterMs = resumeAfterMs;
+	}
+	dispose() {
+		this.interactions.removeEventListener("start", this.handleInteractionStart);
+		this.interactions.removeEventListener("end", this.handleInteractionEnd);
+		this.element.ownerDocument.removeEventListener("visibilitychange", this.handleVisibilityChange);
+		this.observer?.disconnect();
+		this.clearResumeTimer();
+		this.dispatch({ type: "disable" });
+	}
+	dispatch(event) {
+		this.state = nextAutoOrbitState(this.state, event);
+		this.sync();
+	}
+	/** Starts the frame loop when the orbit becomes active and cancels it otherwise. */
+	sync() {
+		const active = this.status === "active";
+		if (active && this.frame === null) {
+			this.lastFrameMs = null;
+			this.frame = requestAnimationFrame(this.tick);
+		} else if (!active && this.frame !== null) {
+			cancelAnimationFrame(this.frame);
+			this.frame = null;
+		}
+	}
+	tick = (nowMs) => {
+		this.frame = null;
+		const deltaSeconds = autoOrbitDeltaSeconds(this.lastFrameMs, nowMs);
+		this.lastFrameMs = nowMs;
+		try {
+			this.step(deltaSeconds);
+		} catch (error) {
+			this.dispose();
+			throw error;
+		}
+		if (this.frame === null && this.status === "active") this.frame = requestAnimationFrame(this.tick);
+	};
+	armResumeTimer() {
+		this.clearResumeTimer();
+		this.resumeTimer = setTimeout(() => {
+			this.resumeTimer = null;
+			this.dispatch({ type: "idle" });
+		}, this.resumeAfterMs);
+	}
+	clearResumeTimer() {
+		if (this.resumeTimer === null) return;
+		clearTimeout(this.resumeTimer);
+		this.resumeTimer = null;
+	}
+	/**
+	* A drag, pinch or wheel step pauses the orbit; `end` restarts the idle countdown. `start` arms
+	* it too, so a swallowed pointerup cannot pause the orbit forever. Resuming mid-drag is harmless:
+	* OrbitControls (r185) applies autoRotate in `update()` only while its state is NONE.
+	*/
+	handleInteractionStart = () => {
+		this.dispatch({ type: "interaction" });
+		this.armResumeTimer();
+	};
+	handleInteractionEnd = () => {
+		if (this.state.interacting) this.armResumeTimer();
+	};
+	handleVisibilityChange = () => {
+		this.dispatch({
+			type: "visibility",
+			hidden: this.element.ownerDocument.hidden
+		});
+	};
+	handleIntersection = (entries) => {
+		const entry = entries.at(-1);
+		if (entry) this.dispatch({
+			type: "intersection",
+			offscreen: !entry.isIntersecting
+		});
+	};
+};
 //#endregion
 //#region src/camera-aspect.ts
 /** Canvas aspect used by perspective cameras. Never 0. */
@@ -580,6 +867,170 @@ function containerAspect(width, height) {
 function applyPerspectiveContainerAspect(camera, width, height) {
 	camera.aspect = containerAspect(width, height);
 }
+function resolveFlyToOptions(options) {
+	const durationMs = options.durationMs ?? 1200;
+	const distanceScale = options.distanceScale ?? 1;
+	if (!Number.isFinite(durationMs) || durationMs < 0) throw new Error(`flyTo durationMs must be a non-negative finite number of milliseconds; received ${durationMs}.`);
+	if (!Number.isFinite(distanceScale) || distanceScale <= 0) throw new Error(`flyTo distanceScale must be a finite number above 0; received ${distanceScale}.`);
+	return {
+		distanceScale,
+		durationMs
+	};
+}
+/** Cubic ease-in-out on `[0, 1]`: slow start, slow arrival, symmetric around 0.5. */
+function easeInOutCubic(t) {
+	return t < .5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+}
+/** Linear progress of a flight, clamped to `[0, 1]`; a zero duration is already done. */
+function flightProgress(elapsedMs, durationMs) {
+	if (durationMs <= 0) return 1;
+	return Math.min(Math.max(elapsedMs / durationMs, 0), 1);
+}
+/**
+* Interpolates a positive scale (camera distance, orthographic zoom) geometrically, so each
+* step zooms by the same factor and a long zoom does not rush its last part. Exact at both ends.
+*/
+function interpolateScale(from, to, t) {
+	if (t <= 0) return from;
+	if (t >= 1) return to;
+	return from * (to / from) ** t;
+}
+//#endregion
+//#region src/theme.ts
+/** Dark canvas: Ink Black, Turf Green, Porcelain. */
+const graphraumThemeDark = Object.freeze({
+	background: "#040f0f",
+	dimmedEdge: "#315a51",
+	dimmedEdgeOpacity: .25,
+	dimmedNode: "#315a51",
+	edge: "#226f54",
+	edgeOpacity: .55,
+	edgeWidth: 1.5,
+	endpointAttach: "boundary",
+	focusedNode: "#73c7a5",
+	hoveredNode: "#e4a853",
+	node: "#226f54",
+	nodeStroke: "#fcfffc",
+	selectedEdge: "#fcfffc",
+	selectedNode: "#fcfffc"
+});
+/** Light canvas: Porcelain field with Turf marks and Ink selection. */
+const graphraumThemeLight = Object.freeze({
+	background: "#fcfffc",
+	dimmedEdge: "#9bb5ac",
+	dimmedEdgeOpacity: .35,
+	dimmedNode: "#9bb5ac",
+	edge: "#226f54",
+	edgeOpacity: .65,
+	edgeWidth: 1.5,
+	endpointAttach: "boundary",
+	focusedNode: "#1a5c45",
+	hoveredNode: "#c47a1a",
+	node: "#226f54",
+	nodeStroke: "#040f0f",
+	selectedEdge: "#040f0f",
+	selectedNode: "#040f0f"
+});
+const graphraumThemes = Object.freeze({
+	dark: graphraumThemeDark,
+	light: graphraumThemeLight
+});
+/** Alias of {@link graphraumThemeDark} for backward compatibility. */
+const graphraumTheme = graphraumThemeDark;
+function resolveGraphraumTheme(input, base = graphraumThemeDark) {
+	if (input === void 0) return { ...base };
+	if (typeof input === "string") {
+		const preset = graphraumThemes[input];
+		if (!preset) throw new Error(`Unknown graphraum theme "${input}". Use "dark" or "light".`);
+		return { ...preset };
+	}
+	return assertGraphraumTheme({
+		...base,
+		...input
+	});
+}
+function assertGraphraumTheme(theme) {
+	const opacity = theme.dimmedEdgeOpacity;
+	if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) throw new Error(`Theme dimmedEdgeOpacity must be a finite number between 0 and 1, received ${opacity}.`);
+	return theme;
+}
+/** Collapse `"transparent"` onto `null` so callers have one transparent sentinel. */
+function normalizeGraphraumBackground(background) {
+	return background === "transparent" ? null : background;
+}
+function isTransparentGraphraumBackground(background) {
+	return normalizeGraphraumBackground(background) === null;
+}
+/** Halo radius as a multiple of the node's half-extent at `glow: 1`. */
+const GLOW_RADIUS_SCALE = 3.4;
+/** Halo opacity multiplier under normal blending, so a light background shows a soft tint. */
+const GLOW_NORMAL_OPACITY_SCALE = .6;
+function assertNodeGlow(nodeId, glow) {
+	if (glow !== void 0 && (!Number.isFinite(glow) || glow < 0 || glow > 1)) throw new Error(`Node "${nodeId}" glow must be a finite number between 0 and 1`);
+}
+/**
+* Halo radius in world units: `extent × (1 + (GLOW_RADIUS_SCALE − 1) × glow)`, where `extent` is
+* the node's half-extent `max(width, height)`. Glow 0 collapses the halo under the node; glow 1
+* reaches 3.4× the node extent.
+*/
+function glowHaloRadius(extent, glow) {
+	return extent * (1 + (GLOW_RADIUS_SCALE - 1) * glow);
+}
+/** Peak halo opacity at the node center; the shader fades it radially to 0 at the halo radius. */
+function glowHaloOpacity(glow) {
+	return glow;
+}
+/** Keeps `current` while it fits, otherwise grows to the next power of two capped at `maximum`. */
+function glowBufferCapacity(required, current, maximum) {
+	if (required <= current) return current;
+	let capacity = Math.max(current, 1);
+	while (capacity < required) capacity *= 2;
+	return Math.min(capacity, maximum);
+}
+function createGlowSelection() {
+	return {
+		count: 0,
+		indices: /* @__PURE__ */ new Uint32Array(0)
+	};
+}
+/**
+* Selects visible nodes with `glow > 0` into `selection`, highest glow first and ties by node
+* index, capped at {@link GLOW_MAX_INSTANCES}. Selects nothing in the density LOD tier. Reuses
+* the selection buffer and grows it geometrically; allocates no per-node objects.
+*/
+function selectGlowNodes(visibleNodeIndices, glowAt, densityLod, selection) {
+	selection.count = 0;
+	if (densityLod) return selection;
+	let candidates = 0;
+	for (const nodeIndex of visibleNodeIndices) {
+		if (!(glowAt(nodeIndex) > 0)) continue;
+		if (candidates === selection.indices.length) {
+			const grown = new Uint32Array(glowBufferCapacity(candidates + 1, candidates, Number.POSITIVE_INFINITY));
+			grown.set(selection.indices);
+			selection.indices = grown;
+		}
+		selection.indices[candidates] = nodeIndex;
+		candidates += 1;
+	}
+	selection.indices.subarray(0, candidates).sort((a, b) => glowAt(b) - glowAt(a) || a - b);
+	selection.count = Math.min(candidates, 256);
+	return selection;
+}
+/**
+* Additive light reads on dark backgrounds but saturates to nothing on light ones. A solid
+* background whose relative luminance (linear sRGB, 0.2126 R + 0.7152 G + 0.0722 B) reaches
+* {@link GLOW_LIGHT_BACKGROUND_LUMINANCE} uses normal blending; transparent and pattern
+* backgrounds keep additive blending because their brightness is unknown.
+*/
+function glowBlendModeFor(background) {
+	const normalized = normalizeGraphraumBackground(background);
+	if (normalized === null || typeof normalized === "object") return "additive";
+	const { b, g, r } = new Color(normalized);
+	return .2126 * r + .7152 * g + .0722 * b >= .5 ? "normal" : "additive";
+}
+function glowOpacityScale(mode) {
+	return mode === "normal" ? GLOW_NORMAL_OPACITY_SCALE : 1;
+}
 //#endregion
 //#region src/compile-graph.ts
 function assertFinitePosition(nodeId, axis, value) {
@@ -632,6 +1083,7 @@ function compileNodeVisual(id, visual) {
 	assertPositiveFiniteVisual(id, "width", visual.width);
 	assertPositiveFiniteVisual(id, "height", visual.height);
 	assertNonNegativeFiniteVisual(id, "strokeWidth", visual.strokeWidth);
+	assertNodeGlow(id, visual.glow);
 	if (visual.shape !== void 0) assertNodeShape(id, visual.shape);
 	return Object.freeze({ ...visual });
 }
@@ -653,6 +1105,7 @@ function compileGraph(data, visuals) {
 		const encoding = visuals?.node?.(node);
 		const visual = compileNodeVisual(node.id, encoding?.visual ?? {
 			color: node.color,
+			glow: node.glow,
 			height: node.height,
 			shape: node.shape,
 			size: node.size,
@@ -838,6 +1291,32 @@ function sampleEdgePath(input) {
 	return points;
 }
 //#endregion
+//#region src/edge-state.ts
+/**
+* Single source of truth for an edge instance's color and opacity. Full packing and the
+* incremental state repaint both call it, so both paths write identical instance colors.
+*/
+function resolveEdgePaint(edgeIndex, visual, defaults, tier, edgeStates) {
+	const opacity = tier === "overview" ? defaults.opacity : visual.opacity ?? defaults.opacity;
+	const state = edgeStates?.stateOf(edgeIndex) ?? null;
+	if (edgeStates && state === "selected") return {
+		color: edgeStates.selectedColor,
+		opacity
+	};
+	if (edgeStates && state === "dimmed") return {
+		color: edgeStates.dimmedColor,
+		opacity: Math.min(opacity, edgeStates.dimmedOpacity)
+	};
+	return {
+		color: visual.color ?? defaults.color,
+		opacity
+	};
+}
+/** IDs present in exactly one of the two sets. */
+function changedIds(current, next) {
+	return [...[...current].filter((id) => !next.has(id)), ...[...next].filter((id) => !current.has(id))];
+}
+//#endregion
 //#region src/edge-materialize.ts
 function packEdgeInstances(input) {
 	const segments = [];
@@ -862,6 +1341,7 @@ function packEdgeInstances(input) {
 			const trimmed = trimEdgeEndpoints({
 				attach,
 				clearance,
+				mode: input.mode,
 				source: {
 					x: x1,
 					y: y1,
@@ -882,9 +1362,8 @@ function packEdgeInstances(input) {
 			y2 = trimmed.target.y;
 			z2 = trimmed.target.z ?? 0;
 		}
-		const color = visual.color ?? input.defaults.color;
+		const { color, opacity } = resolveEdgePaint(edgeIndex, visual, input.defaults, input.tier, input.edgeStates);
 		const width = input.tier === "overview" ? input.defaults.width : visual.width ?? input.defaults.width;
-		const opacity = input.tier === "overview" ? input.defaults.opacity : visual.opacity ?? input.defaults.opacity;
 		const style = input.tier === "overview" ? "solid" : visual.style ?? "solid";
 		const points = sampleEdgePath({
 			path: visual.path,
@@ -996,8 +1475,19 @@ function pickClosestEdgeIndex(point, segments) {
 	return nearestEdgeIndex;
 }
 //#endregion
+//#region src/shader-output.ts
+/**
+* Encodes `gl_FragColor.rgb` from the linear working space into the renderer's output color space:
+* sRGB on the canvas (so a `#8a9096` theme color draws as `#8a9096`), unchanged on linear render
+* targets. Alpha is left untouched, so anti-aliased coverage and blending are unaffected.
+*
+* Append once to every display fragment shader, after its final `gl_FragColor` assignment.
+* Requires a `ShaderMaterial` (not `RawShaderMaterial`), whose prefix defines `linearToOutputTexel`.
+*/
+const OUTPUT_COLOR_SPACE_FRAGMENT = "#include <colorspace_fragment>";
+//#endregion
 //#region src/edge-rendering.ts
-const vertexShader$1 = `
+const vertexShader$2 = `
 attribute float instanceKind;
 attribute vec3 instanceEndA;
 attribute vec3 instanceEndB;
@@ -1048,7 +1538,7 @@ void main() {
 	gl_Position = projectionMatrix * viewPosition;
 }
 `;
-const fragmentShader$1 = `
+const fragmentShader$2 = `
 varying vec4 edgeColor;
 varying float edgeKind;
 varying float edgeStyle;
@@ -1072,6 +1562,7 @@ void main() {
 	}
 	if (edgeColor.a <= 0.0) discard;
 	gl_FragColor = edgeColor;
+	${OUTPUT_COLOR_SPACE_FRAGMENT}
 }
 `;
 function createEdgeGeometry(capacity) {
@@ -1084,13 +1575,13 @@ function createEdgeGeometry(capacity) {
 	geometry.setAttribute("instanceStyle", new InstancedBufferAttribute(new Float32Array(capacity), 1));
 	return geometry;
 }
-function createEdgeMaterial(depthTest) {
+function createEdgeMaterial() {
 	return new ShaderMaterial({
-		depthTest,
-		depthWrite: depthTest,
-		fragmentShader: fragmentShader$1,
+		depthTest: false,
+		depthWrite: false,
+		fragmentShader: fragmentShader$2,
 		transparent: true,
-		vertexShader: vertexShader$1
+		vertexShader: vertexShader$2
 	});
 }
 function getInstancedAttribute(geometry, name) {
@@ -1108,8 +1599,7 @@ function writeEdgeSegmentInstance(geometry, slot, segment) {
 	kind.setX(slot, 0);
 	endA.setXYZ(slot, segment.x1, segment.y1, segment.z1);
 	endB.setXYZ(slot, segment.x2, segment.y2, segment.z2);
-	const rgb = new Color(segment.color);
-	color.setXYZW(slot, rgb.r, rgb.g, rgb.b, segment.opacity);
+	writeEdgeColorSlots(color, slot, 1, segment);
 	width.setX(slot, segment.width);
 	style.setX(slot, encodeEdgeStyle(segment.style));
 }
@@ -1123,11 +1613,15 @@ function writeEdgeMarkerInstance(geometry, slot, marker) {
 	kind.setX(slot, 1);
 	endA.setXYZ(slot, marker.x, marker.y, marker.z);
 	endB.setXYZ(slot, marker.x + marker.dx, marker.y + marker.dy, marker.z + marker.dz);
-	const rgb = new Color(marker.color);
-	color.setXYZW(slot, rgb.r, rgb.g, rgb.b, marker.opacity);
+	writeEdgeColorSlots(color, slot, 1, marker);
 	width.setX(slot, marker.size);
 	style.setX(slot, 0);
 }
+/** Writes one color and opacity into `count` consecutive instance slots starting at `start`. */
+function writeEdgeColorSlots(color, start, count, paint) {
+	const rgb = new Color(paint.color);
+	for (let slot = start; slot < start + count; slot += 1) color.setXYZW(slot, rgb.r, rgb.g, rgb.b, paint.opacity);
+}
 //#endregion
 //#region src/edge-viewport-patch.ts
 const EDGE_INSTANCE_ATTRIBUTES$1 = [
@@ -1188,6 +1682,8 @@ function patchVisibleEdgeInstances(geometry, input, pickableSegments) {
 			tier: input.tier,
 			endpointAttach: input.endpointAttach,
 			edgeNodeIndices: input.edgeNodeIndices,
+			edgeStates: input.edgeStates,
+			mode: input.mode,
 			nodeOutlines: input.nodeOutlines
 		});
 		if (packed.segments.length !== layout.segmentCount || packed.markers.length !== layout.markerCount) return {
@@ -1225,7 +1721,6 @@ function patchVisibleEdgeInstances(geometry, input, pickableSegments) {
 	};
 	for (const name of EDGE_INSTANCE_ATTRIBUTES$1) {
 		const attribute = geometry.getAttribute(name);
-		attribute.clearUpdateRanges();
 		attribute.addUpdateRange(dirtySlotStart * attribute.itemSize, (dirtySlotEnd - dirtySlotStart + 1) * attribute.itemSize);
 		attribute.needsUpdate = true;
 	}
@@ -1236,14 +1731,146 @@ function patchVisibleEdgeInstances(geometry, input, pickableSegments) {
 		pickableSegments: nextPickable
 	};
 }
+/**
+* Repaints the color and opacity of visible edges whose host state changed. Slot layout,
+* geometry, and picking stay untouched, so only the changed `instanceColor` ranges upload.
+* Edges without visible slots are skipped; the next materialize paints them from the same state.
+*/
+function patchVisibleEdgePaint(geometry, input) {
+	const visible = [...input.changedEdgeIndices].flatMap((edgeIndex) => {
+		const layout = input.layouts.get(edgeIndex);
+		return layout ? [{
+			edgeIndex,
+			layout
+		}] : [];
+	});
+	if (!visible.every(({ layout }) => layout.segmentStart + layout.segmentCount <= input.instanceCount && layout.markerStart + layout.markerCount <= input.instanceCount)) return {
+		ok: false,
+		patchedSlots: 0
+	};
+	const color = getInstancedAttribute(geometry, "instanceColor");
+	let patchedSlots = 0;
+	for (const { edgeIndex, layout } of visible) {
+		const paint = resolveEdgePaint(edgeIndex, input.edgeVisuals[edgeIndex] ?? {}, input.defaults, input.tier, input.edgeStates);
+		for (const [start, count] of [[layout.segmentStart, layout.segmentCount], [layout.markerStart, layout.markerCount]]) {
+			if (count === 0) continue;
+			writeEdgeColorSlots(color, start, count, paint);
+			color.addUpdateRange(start * color.itemSize, count * color.itemSize);
+			patchedSlots += count;
+		}
+	}
+	if (patchedSlots > 0) color.needsUpdate = true;
+	return {
+		ok: true,
+		patchedSlots
+	};
+}
+//#endregion
+//#region src/fit-3d.ts
+/** Newton steps on a piecewise-linear function before falling back to the plane-space centre. */
+const MAX_CENTERING_STEPS = 32;
+/**
+* The closest front-view camera that frames every node. Throws without nodes. `maxCenteringSteps`
+* exists so tests can exercise the fallback.
+*/
+function fitPerspective(frame, nodes, maxCenteringSteps = MAX_CENTERING_STEPS) {
+	if (nodes.count === 0) throw new Error("fitPerspective needs at least one node");
+	const tanY = Math.tan(frame.fovDegrees * Math.PI / 360) * frame.fill;
+	const tanX = tanY * frame.aspect;
+	const node = {
+		halfHeight: 0,
+		halfWidth: 0,
+		x: 0,
+		y: 0,
+		z: 0
+	};
+	let right = Number.NEGATIVE_INFINITY;
+	let left = Number.NEGATIVE_INFINITY;
+	let top = Number.NEGATIVE_INFINITY;
+	let bottom = Number.NEGATIVE_INFINITY;
+	let minZ = Number.POSITIVE_INFINITY;
+	let maxZ = Number.NEGATIVE_INFINITY;
+	for (let index = 0; index < nodes.count; index += 1) {
+		nodes.read(index, node);
+		right = Math.max(right, node.x + node.halfWidth + tanX * node.z);
+		left = Math.max(left, -node.x + node.halfWidth + tanX * node.z);
+		top = Math.max(top, node.y + node.halfHeight + tanY * node.z);
+		bottom = Math.max(bottom, -node.y + node.halfHeight + tanY * node.z);
+		minZ = Math.min(minZ, node.z);
+		maxZ = Math.max(maxZ, node.z);
+	}
+	const cameraZX = (right + left) / (2 * tanX);
+	const cameraZY = (top + bottom) / (2 * tanY);
+	const cameraZ = Math.max(cameraZX, cameraZY);
+	let x = (right - left) / 2;
+	let y = (top - bottom) / 2;
+	if (cameraZX < cameraZY) x = centerOnScreen(nodes, node, "x", cameraZ, x, maxCenteringSteps);
+	else if (cameraZY < cameraZX) y = centerOnScreen(nodes, node, "y", cameraZ, y, maxCenteringSteps);
+	const target = {
+		x,
+		y,
+		z: (minZ + maxZ) / 2
+	};
+	const distance = cameraZ - target.z;
+	const nearestDepth = cameraZ - maxZ;
+	return {
+		cameraZ,
+		near: Math.min(Math.max(distance / 1e4, .1), nearestDepth / 2),
+		far: distance * 10,
+		target
+	};
+}
+/**
+* Centre on the looser axis that makes the farthest screen reach equal on both sides.
+*
+* With depth `d = cameraZ - z`, a centre `c` keeps every node within screen reach `r` when
+* `max(p + h - r * d) <= c <= min(p - h + r * d)`. The gap between those bounds is convex and
+* decreasing in `r`, so Newton steps from `r = 0` rise monotonically to the smallest feasible
+* reach. `planeCenter` already fits, so it is the answer if the steps do not settle.
+*/
+function centerOnScreen(nodes, node, axis, cameraZ, planeCenter, maxSteps) {
+	let reach = 0;
+	for (let step = 0; step < maxSteps; step += 1) {
+		let low = Number.NEGATIVE_INFINITY;
+		let high = Number.POSITIVE_INFINITY;
+		let lowValue = 0;
+		let lowDepth = 0;
+		let highValue = 0;
+		let highDepth = 0;
+		for (let index = 0; index < nodes.count; index += 1) {
+			nodes.read(index, node);
+			const position = axis === "x" ? node.x : node.y;
+			const half = axis === "x" ? node.halfWidth : node.halfHeight;
+			const depth = cameraZ - node.z;
+			const lowBound = position + half - reach * depth;
+			const highBound = position - half + reach * depth;
+			if (lowBound > low) {
+				low = lowBound;
+				lowValue = position + half;
+				lowDepth = depth;
+			}
+			if (highBound < high) {
+				high = highBound;
+				highValue = position - half;
+				highDepth = depth;
+			}
+		}
+		if (low <= high) return (low + high) / 2;
+		const next = (lowValue - highValue) / (lowDepth + highDepth);
+		if (next <= reach) return (low + high) / 2;
+		reach = next;
+	}
+	return planeCenter;
+}
 //#endregion
 //#region src/instance-color-ranges.ts
 /**
 * Marks RGB update ranges for visible instance slots.
+* Keeps earlier ranges that have not been uploaded yet (a viewport materialize in the same frame);
+* three.js merges and clears ranges on upload.
 * Returns how many slots were marked.
 */
 function markInstanceColorSlots(attribute, slots) {
-	attribute.clearUpdateRanges();
 	let count = 0;
 	for (const slot of slots) {
 		if (!Number.isSafeInteger(slot) || slot < 0) continue;
@@ -1275,6 +1902,7 @@ function prepareLayoutPositions(nodes, nodeIndices, layout) {
 		for (const [axis, value] of Object.entries(position)) if (!Number.isFinite(value)) throw new Error(`Layout node "${id}" has a non-finite ${axis} position`);
 		return {
 			colorChanged: false,
+			glowChanged: false,
 			index: nodeIndex,
 			next: {
 				...current,
@@ -1287,6 +1915,145 @@ function prepareLayoutPositions(nodes, nodeIndices, layout) {
 		};
 	});
 }
+const vertexShader$1 = `
+attribute float instanceGlowOpacity;
+varying vec3 glowColor;
+varying vec2 glowPoint;
+varying float glowOpacity;
+
+void main() {
+	glowColor = instanceColor;
+	glowPoint = position.xy;
+	glowOpacity = instanceGlowOpacity;
+	vec4 center = modelViewMatrix * instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+	center.xy += position.xy * length(instanceMatrix[0].xyz);
+	gl_Position = projectionMatrix * center;
+}
+`;
+const fragmentShader$1 = `
+uniform float opacityScale;
+varying vec3 glowColor;
+varying vec2 glowPoint;
+varying float glowOpacity;
+
+void main() {
+	float distanceFromCenter = length(glowPoint);
+	if (distanceFromCenter >= 1.0) discard;
+	float falloff = 1.0 - distanceFromCenter;
+	gl_FragColor = vec4(glowColor, falloff * falloff * glowOpacity * opacityScale);
+	${OUTPUT_COLOR_SPACE_FRAGMENT}
+}
+`;
+function applyBlendMode(material, mode) {
+	material.blending = mode === "normal" ? NormalBlending : AdditiveBlending;
+	const opacityScale = material.uniforms.opacityScale;
+	if (opacityScale) opacityScale.value = glowOpacityScale(mode);
+	material.needsUpdate = true;
+}
+function createNodeGlowMaterial(mode) {
+	const material = new ShaderMaterial({
+		depthTest: false,
+		depthWrite: false,
+		fragmentShader: fragmentShader$1,
+		transparent: true,
+		uniforms: { opacityScale: { value: 1 } },
+		vertexShader: vertexShader$1
+	});
+	applyBlendMode(material, mode);
+	return material;
+}
+function createGlowMesh(capacity, mode) {
+	const geometry = new PlaneGeometry(2, 2);
+	geometry.setAttribute("instanceGlowOpacity", new InstancedBufferAttribute(new Float32Array(capacity), 1));
+	const mesh = new InstancedMesh(geometry, createNodeGlowMaterial(mode), capacity);
+	mesh.instanceColor = new InstancedBufferAttribute(new Float32Array(capacity * 3), 3);
+	mesh.name = "graphraum-node-glow";
+	mesh.frustumCulled = false;
+	mesh.renderOrder = -2;
+	return mesh;
+}
+/**
+* Opt-in batched halo pass: one additive instanced mesh, created lazily on the first glowing
+* node and hidden while no halo is selected, so graphs without glow keep two draw calls.
+*/
+var NodeGlowLayer = class {
+	scene;
+	selection = createGlowSelection();
+	target = {
+		color: new Color(),
+		extent: 0,
+		glow: 0,
+		x: 0,
+		y: 0,
+		z: 0
+	};
+	matrix = new Matrix4();
+	mesh = null;
+	blendMode = "additive";
+	constructor(scene) {
+		this.scene = scene;
+	}
+	/** Additive on dark or unknown backgrounds, normal on light solid ones; see `glowBlendModeFor`. */
+	setBlending(mode) {
+		if (mode === this.blendMode) return;
+		this.blendMode = mode;
+		if (this.mesh) applyBlendMode(this.mesh.material, mode);
+	}
+	/** Halo instances in the current frame. */
+	get count() {
+		return this.mesh?.visible ? this.mesh.count : 0;
+	}
+	/** Reselects glowing visible nodes and rewrites every halo instance. */
+	sync(visibleNodeIndices, glowAt, densityLod, describe) {
+		selectGlowNodes(visibleNodeIndices, glowAt, densityLod, this.selection);
+		if (this.selection.count > 0) this.ensureCapacity(this.selection.count);
+		this.rewrite(describe);
+	}
+	/** Rewrites positions, radii, opacities, and colors of the current selection in place. */
+	rewrite(describe) {
+		const mesh = this.mesh;
+		if (!mesh) return;
+		const opacity = mesh.geometry.getAttribute("instanceGlowOpacity");
+		let slot = 0;
+		for (let index = 0; index < this.selection.count; index += 1) {
+			const nodeIndex = this.selection.indices[index];
+			if (nodeIndex === void 0 || !describe(nodeIndex, this.target)) continue;
+			const { color, extent, glow, x, y, z } = this.target;
+			const radius = glowHaloRadius(extent, glow);
+			this.matrix.makeScale(radius, radius, radius).setPosition(x, y, z);
+			mesh.setMatrixAt(slot, this.matrix);
+			mesh.setColorAt(slot, color);
+			opacity.setX(slot, glowHaloOpacity(glow));
+			slot += 1;
+		}
+		mesh.count = slot;
+		mesh.visible = slot > 0;
+		mesh.instanceMatrix.needsUpdate = true;
+		if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
+		opacity.needsUpdate = true;
+	}
+	/** Releases the GPU mesh; the layer stays reusable and recreates it on the next glowing node. */
+	dispose() {
+		this.selection.count = 0;
+		this.releaseMesh();
+	}
+	releaseMesh() {
+		if (!this.mesh) return;
+		this.scene.remove(this.mesh);
+		this.mesh.geometry.dispose();
+		this.mesh.material.dispose();
+		this.mesh.dispose();
+		this.mesh = null;
+	}
+	ensureCapacity(required) {
+		const current = this.mesh?.instanceMatrix.count ?? 0;
+		const capacity = glowBufferCapacity(required, current, 256);
+		if (this.mesh && capacity === current) return;
+		this.releaseMesh();
+		this.mesh = createGlowMesh(capacity, this.blendMode);
+		this.scene.add(this.mesh);
+	}
+};
 //#endregion
 //#region src/node-rendering.ts
 const vertexShader = `
@@ -1399,6 +2166,7 @@ void main() {
 		fillColor = mix(nodeStrokeColor, nodeColor, strokeToFill);
 	}
 	gl_FragColor = vec4(fillColor, outerAlpha);
+	${OUTPUT_COLOR_SPACE_FRAGMENT}
 }
 `;
 function createNodeGeometry(capacity) {
@@ -1476,6 +2244,7 @@ function assertValidNode(node) {
 	});
 	if (node.strokeWidth !== void 0 && (!Number.isFinite(node.strokeWidth) || node.strokeWidth < 0)) throw new Error(`Node "${node.id}" must have a finite non-negative strokeWidth`);
 	if (node.shape !== void 0) assertNodeShape(node.id, node.shape);
+	assertNodeGlow(node.id, node.glow);
 }
 /** Validates a complete update batch before the renderer mutates CPU or GPU state. */
 function prepareNodeUpdates(nodes, nodeIndices, updates) {
@@ -1490,6 +2259,7 @@ function prepareNodeUpdates(nodes, nodeIndices, updates) {
 		const next = {
 			...current,
 			...Object.hasOwn(update, "color") ? { color: update.color } : {},
+			...Object.hasOwn(update, "glow") ? { glow: update.glow } : {},
 			...update.position ? { position: { ...update.position } } : {},
 			...Object.hasOwn(update, "shape") ? { shape: update.shape } : {},
 			...Object.hasOwn(update, "size") ? { size: update.size } : {},
@@ -1501,6 +2271,7 @@ function prepareNodeUpdates(nodes, nodeIndices, updates) {
 		assertValidNode(next);
 		return {
 			colorChanged: Object.hasOwn(update, "color"),
+			glowChanged: Object.hasOwn(update, "glow"),
 			index,
 			next,
 			positionChanged: update.position !== void 0,
@@ -1511,6 +2282,22 @@ function prepareNodeUpdates(nodes, nodeIndices, updates) {
 	});
 }
 //#endregion
+//#region src/orbit-controls-mode.ts
+/**
+* Sets the controls for a 2D or 3D view. 2D turns rotation off, so one finger and the left
+* mouse button pan instead. One finger must not stay on ROTATE: when a pinch ends with one finger
+* still down, OrbitControls (r185) re-reads `touches.ONE`, returns early for a disabled rotate and
+* keeps the two-finger state, and the next move reads the lifted finger's position and throws.
+*/
+function configureControlsForMode(controls, mode) {
+	controls.enableRotate = mode === "3d";
+	if (mode === "2d") {
+		controls.minZoom = .01;
+		controls.mouseButtons.LEFT = MOUSE.PAN;
+		controls.touches.ONE = TOUCH.PAN;
+	}
+}
+//#endregion
 //#region src/label-budget.ts
 /** Picks visible label ids by importance within a hard DOM budget. */
 function selectBudgetedLabelIds({ candidates, maxLabels }) {
@@ -1895,63 +2682,6 @@ var SpatialGrid2D = class {
 	}
 };
 //#endregion
-//#region src/theme.ts
-/** Dark canvas: Ink Black, Turf Green, Porcelain. */
-const graphraumThemeDark = Object.freeze({
-	background: "#040f0f",
-	dimmedNode: "#315a51",
-	edge: "#226f54",
-	edgeOpacity: .55,
-	edgeWidth: 1.5,
-	endpointAttach: "boundary",
-	focusedNode: "#73c7a5",
-	hoveredNode: "#e4a853",
-	node: "#226f54",
-	nodeStroke: "#fcfffc",
-	selectedEdge: "#fcfffc",
-	selectedNode: "#fcfffc"
-});
-/** Light canvas: Porcelain field with Turf marks and Ink selection. */
-const graphraumThemeLight = Object.freeze({
-	background: "#fcfffc",
-	dimmedNode: "#9bb5ac",
-	edge: "#226f54",
-	edgeOpacity: .65,
-	edgeWidth: 1.5,
-	endpointAttach: "boundary",
-	focusedNode: "#1a5c45",
-	hoveredNode: "#c47a1a",
-	node: "#226f54",
-	nodeStroke: "#040f0f",
-	selectedEdge: "#040f0f",
-	selectedNode: "#040f0f"
-});
-const graphraumThemes = Object.freeze({
-	dark: graphraumThemeDark,
-	light: graphraumThemeLight
-});
-/** Alias of {@link graphraumThemeDark} for backward compatibility. */
-const graphraumTheme = graphraumThemeDark;
-function resolveGraphraumTheme(input, base = graphraumThemeDark) {
-	if (input === void 0) return { ...base };
-	if (typeof input === "string") {
-		const preset = graphraumThemes[input];
-		if (!preset) throw new Error(`Unknown graphraum theme "${input}". Use "dark" or "light".`);
-		return { ...preset };
-	}
-	return {
-		...base,
-		...input
-	};
-}
-/** Collapse `"transparent"` onto `null` so callers have one transparent sentinel. */
-function normalizeGraphraumBackground(background) {
-	return background === "transparent" ? null : background;
-}
-function isTransparentGraphraumBackground(background) {
-	return normalizeGraphraumBackground(background) === null;
-}
-//#endregion
 //#region src/viewport-lod.ts
 /** Single source of truth for the density/overview/detail tier reported in diagnostics and used to drive edge LOD packing. */
 function resolveLodLevel(densityLodActive, edgeCandidateCount, visibleEdgeSegmentCount) {
@@ -1981,9 +2711,20 @@ function shouldUseDensityLod(candidateCount, maximum, active) {
 //#region src/graphraum.ts
 /** Importance boost so selected nodes stay labeled when autoLabels budgets the overlay. */
 const SELECTED_LABEL_IMPORTANCE_BOOST = 1e3;
+/** The 3D fit leaves 4% of the tighter canvas axis free on each side, e.g. for edge labels. */
+const PERSPECTIVE_FIT_FILL = .92;
+function prefersReducedMotion() {
+	return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
 function disposeMaterial(material) {
 	for (const item of Array.isArray(material) ? material : [material]) item.dispose();
 }
+/** Canvas input that cancels a running `flyTo`, so people take over the camera at once. */
+const FLIGHT_CANCEL_EVENTS = [
+	"keydown",
+	"pointerdown",
+	"wheel"
+];
 const EDGE_INSTANCE_ATTRIBUTES = [
 	"instanceKind",
 	"instanceEndA",
@@ -2027,12 +2768,19 @@ var Graphraum = class {
 	nodeMesh = null;
 	nodePickMesh = null;
 	edgeMesh = null;
+	glowLayer = new NodeGlowLayer(this.scene);
+	hasGlowNodes = false;
 	nodeCapacity = 0;
 	edgeCapacity = 0;
 	markerCapacity = 0;
 	edgeInstanceCapacity = 0;
 	selectedNodeIds = /* @__PURE__ */ new Set();
 	selectedEdgeIds = /* @__PURE__ */ new Set();
+	dimmedEdgeIds = /* @__PURE__ */ new Set();
+	edgeIndexCache = {
+		edges: [],
+		indices: /* @__PURE__ */ new Map()
+	};
 	hoveredNodeIds = /* @__PURE__ */ new Set();
 	focusedNodeIds = /* @__PURE__ */ new Set();
 	dimmedNodeIds = /* @__PURE__ */ new Set();
@@ -2053,6 +2801,12 @@ var Graphraum = class {
 	edgeSegmentCapacity = 0;
 	mode;
 	frameRequest = null;
+	autoOrbit = null;
+	flight = null;
+	flightDirection = new Vector3();
+	/** True only during the orbit's own `controls.update(dt)`; see `handleViewChange`. */
+	orbitUpdating = false;
+	destroyed = false;
 	cpuFrameMilliseconds = 0;
 	gpuFrameMilliseconds = null;
 	gpuTimer = null;
@@ -2092,6 +2846,7 @@ var Graphraum = class {
 		this.container.append(this.renderer.domElement);
 		this.renderer.domElement.addEventListener("pointermove", this.handlePointerMove);
 		this.renderer.domElement.addEventListener("pointerleave", this.handlePointerLeave);
+		for (const type of FLIGHT_CANCEL_EVENTS) this.renderer.domElement.addEventListener(type, this.cancelFlight);
 		this.camera = this.createCamera();
 		this.controls = this.createControls();
 		this.resizeObserver = new ResizeObserver(() => this.resize());
@@ -2148,6 +2903,7 @@ var Graphraum = class {
 			}))
 		};
 		this.nodeIds = compiled.nodeIds;
+		this.hasGlowNodes = this.data.nodes.some(hasNodeGlow);
 		this.nodeIndices = new Map(compiled.nodeIndices);
 		this.edgeNodeIndices = compiled.edgeNodeIndices;
 		this.canonicalEdgePositions = compiled.edgePositions;
@@ -2157,12 +2913,11 @@ var Graphraum = class {
 		this.spatialGrid2d = new SpatialGrid2D();
 		for (const [index, node] of this.data.nodes.entries()) this.spatialGrid2d.set(index, node);
 		const liveNodeIds = new Set(this.nodeIds);
-		const liveEdgeIds = new Set(this.data.edges.map((edge) => edge.id));
 		this.selectedNodeIds = new Set([...this.selectedNodeIds].filter((id) => liveNodeIds.has(id)));
 		this.hoveredNodeIds = new Set([...this.hoveredNodeIds].filter((id) => liveNodeIds.has(id)));
 		this.focusedNodeIds = new Set([...this.focusedNodeIds].filter((id) => liveNodeIds.has(id)));
 		this.dimmedNodeIds = new Set([...this.dimmedNodeIds].filter((id) => liveNodeIds.has(id)));
-		this.selectedEdgeIds = new Set([...this.selectedEdgeIds].filter((id) => liveEdgeIds.has(id)));
+		this.pruneEdgeStates();
 		this.materializeViewport();
 		this.requestRender();
 	}
@@ -2226,6 +2981,7 @@ var Graphraum = class {
 			edges: nextEdges
 		};
 		this.nodeIds = nextNodes.map((node) => node.id);
+		this.hasGlowNodes = nextNodes.some(hasNodeGlow);
 		this.nodeIndices = nextNodeIndices;
 		this.edgeNodeIndices = nextEdgeIndices;
 		this.canonicalEdgePositions = nextEdgePositions;
@@ -2255,6 +3011,7 @@ var Graphraum = class {
 			}))
 		};
 		this.nodeIds = compiled.nodeIds;
+		this.hasGlowNodes = this.data.nodes.some(hasNodeGlow);
 		this.nodeIndices = new Map(compiled.nodeIndices);
 		this.edgeNodeIndices = compiled.edgeNodeIndices;
 		this.canonicalEdgePositions = compiled.edgePositions;
@@ -2263,11 +3020,12 @@ var Graphraum = class {
 		this.edgePresentations = new Map(compiled.edgePresentations);
 		this.spatialGrid2d = new SpatialGrid2D();
 		for (const [index, node] of this.data.nodes.entries()) this.spatialGrid2d.set(index, node);
+		this.pruneEdgeStates();
 		this.nodeCapacity = Math.min(this.maxVisibleNodes, nextCapacity(data.nodes.length));
 		const nodeCapacity = this.nodeCapacity;
 		const nodeMesh = new InstancedMesh(createNodeGeometry(nodeCapacity), createNodeMaterial(this.mode === "3d"), nodeCapacity);
 		allocateNodeInstanceColors(nodeMesh, nodeCapacity);
-		nodeMesh.renderOrder = this.mode === "2d" ? 1 : 0;
+		nodeMesh.renderOrder = 1;
 		this.nodeMesh = nodeMesh;
 		this.scene.add(nodeMesh);
 		const nodePickMesh = new InstancedMesh(new SphereGeometry(1, 8, 6), new MeshBasicMaterial(), nodeCapacity);
@@ -2277,9 +3035,9 @@ var Graphraum = class {
 		this.edgeSegmentCapacity = capacities.segmentCapacity;
 		this.markerCapacity = capacities.markerCapacity;
 		this.edgeInstanceCapacity = capacities.edgeInstanceCapacity;
-		const edgeMesh = new InstancedMesh(createEdgeGeometry(this.edgeInstanceCapacity), createEdgeMaterial(this.mode === "3d"), this.edgeInstanceCapacity);
+		const edgeMesh = new InstancedMesh(createEdgeGeometry(this.edgeInstanceCapacity), createEdgeMaterial(), this.edgeInstanceCapacity);
 		edgeMesh.frustumCulled = false;
-		edgeMesh.renderOrder = this.mode === "2d" ? -1 : 0;
+		edgeMesh.renderOrder = -1;
 		this.edgeMesh = edgeMesh;
 		this.scene.add(edgeMesh);
 		if (fitView) this.fitView();
@@ -2376,6 +3134,8 @@ var Graphraum = class {
 			}
 		}
 		if (this.densityLodActive && prepared.some((update) => update.positionChanged || update.sizeChanged)) visibilityChanged = true;
+		const glowChanged = prepared.some((update) => update.glowChanged);
+		if (glowChanged) this.hasGlowNodes = nodes.some(hasNodeGlow);
 		this.data = {
 			...this.data,
 			nodes
@@ -2394,6 +3154,8 @@ var Graphraum = class {
 		}
 		if (prepared.some((update) => update.colorChanged) && nodeMesh.instanceColor) nodeMesh.instanceColor.needsUpdate = true;
 		if (prepared.some((update) => update.shapeChanged)) nodeShape.needsUpdate = true;
+		if (glowChanged) this.syncGlow();
+		else if (prepared.some((update) => update.positionChanged || update.sizeChanged || update.colorChanged)) this.glowLayer.rewrite(this.describeGlowNode);
 		if (prepared.some((update) => update.strokeChanged)) {
 			nodeStrokeWidth.needsUpdate = true;
 			nodeStrokeColor.needsUpdate = true;
@@ -2405,10 +3167,6 @@ var Graphraum = class {
 		if (!this.edgeMesh || changedEdgeIndices.length === 0) return true;
 		const worldPerPixel = this.worldUnitsPerPixel();
 		const minHitSlop = Math.max(4 * worldPerPixel, this.theme.edgeWidth * worldPerPixel);
-		const edgeVisuals = this.data.edges.map((edge) => this.selectedEdgeIds.has(edge.id) ? {
-			...edge,
-			color: this.theme.selectedEdge
-		} : edge);
 		const result = patchVisibleEdgeInstances(this.edgeMesh.geometry, {
 			changedEdgeIndices,
 			defaults: {
@@ -2417,11 +3175,13 @@ var Graphraum = class {
 				width: this.theme.edgeWidth
 			},
 			edgeNodeIndices: this.edgeNodeIndices,
-			edgeVisuals,
+			edgeStates: this.edgeStateStyling(),
+			edgeVisuals: this.data.edges,
 			endpointAttach: this.theme.endpointAttach,
 			endpointPositions: this.canonicalEdgePositions,
 			layouts: this.visibleEdgeLayouts,
 			minHitSlop,
+			mode: this.mode,
 			nodeOutlines: this.data.nodes.map((node) => ({
 				height: node.height,
 				shape: node.shape,
@@ -2439,12 +3199,80 @@ var Graphraum = class {
 	setSelection(nodeIds) {
 		this.setNodeState("selected", nodeIds);
 	}
-	/** Highlights edges without changing node selection or source graph data. */
+	/**
+	* Highlights edges without changing node selection or source graph data. Unknown IDs are ignored.
+	* Only the instance colors of edges whose selection changed are rewritten and uploaded.
+	*/
 	setEdgeSelection(edgeIds) {
-		this.selectedEdgeIds = new Set(edgeIds);
-		this.materializeViewport();
+		const next = this.knownEdgeIds(edgeIds);
+		const changed = changedIds(this.selectedEdgeIds, next);
+		this.selectedEdgeIds = next;
+		this.repaintEdgeStates(changed);
+	}
+	/**
+	* Applies an application-owned edge state without changing source graph data. `dimmed` uses
+	* `theme.dimmedEdge` / `theme.dimmedEdgeOpacity`; selected edges stay selected. Unknown IDs are ignored.
+	*/
+	setEdgeState(state, edgeIds) {
+		if (state !== "dimmed") throw new Error(`Unknown edge state "${String(state)}". Use "dimmed".`);
+		const next = this.knownEdgeIds(edgeIds);
+		const changed = changedIds(this.dimmedEdgeIds, next);
+		this.dimmedEdgeIds = next;
+		this.repaintEdgeStates(changed);
+	}
+	knownEdgeIds(edgeIds) {
+		const indices = this.edgeIndicesById();
+		return new Set([...edgeIds].filter((id) => indices.has(id)));
+	}
+	/**
+	* Visible slots, LOD tier, and geometry only change through materialize or endpoint patches,
+	* which keep `visibleEdgeLayouts` current, so a state change repaints in place. If a layout no
+	* longer fits the drawn instances, that invariant broke: fall back to a full materialize.
+	*/
+	repaintEdgeStates(changedEdgeIds) {
+		if (!this.edgeMesh || changedEdgeIds.length === 0) return;
+		const indices = this.edgeIndicesById();
+		if (!patchVisibleEdgePaint(this.edgeMesh.geometry, {
+			changedEdgeIndices: changedEdgeIds.flatMap((id) => indices.get(id) ?? []),
+			defaults: {
+				color: this.theme.edge,
+				opacity: this.theme.edgeOpacity
+			},
+			edgeStates: this.edgeStateStyling(),
+			edgeVisuals: this.data.edges,
+			instanceCount: this.edgeMesh.count,
+			layouts: this.visibleEdgeLayouts,
+			tier: this.lastEdgeLodTier
+		}).ok) this.materializeViewport();
 		this.requestRender();
 	}
+	edgeStateStyling() {
+		return {
+			dimmedColor: this.theme.dimmedEdge,
+			dimmedOpacity: this.theme.dimmedEdgeOpacity,
+			selectedColor: this.theme.selectedEdge,
+			stateOf: (edgeIndex) => {
+				const id = this.data.edges[edgeIndex]?.id;
+				if (id === void 0) return null;
+				if (this.selectedEdgeIds.has(id)) return "selected";
+				return this.dimmedEdgeIds.has(id) ? "dimmed" : null;
+			}
+		};
+	}
+	/** Edge ID to compiled index, rebuilt only when the edge list is replaced. */
+	edgeIndicesById() {
+		if (this.edgeIndexCache.edges !== this.data.edges) this.edgeIndexCache = {
+			edges: this.data.edges,
+			indices: new Map(this.data.edges.map((edge, index) => [edge.id, index]))
+		};
+		return this.edgeIndexCache.indices;
+	}
+	/** Drops edge states whose edges left the graph. */
+	pruneEdgeStates() {
+		const indices = this.edgeIndicesById();
+		this.selectedEdgeIds = new Set([...this.selectedEdgeIds].filter((id) => indices.has(id)));
+		this.dimmedEdgeIds = new Set([...this.dimmedEdgeIds].filter((id) => indices.has(id)));
+	}
 	/** Applies an application-owned visual state without changing source graph data. */
 	setNodeState(state, nodeIds) {
 		const nextSelection = new Set(nodeIds);
@@ -2481,6 +3309,8 @@ var Graphraum = class {
 	}
 	setMode(mode) {
 		if (mode === this.mode) return;
+		this.cancelFlight();
+		this.stopAutoOrbit();
 		this.mode = mode;
 		this.controls.removeEventListener("change", this.handleViewChange);
 		this.controls.dispose();
@@ -2490,19 +3320,30 @@ var Graphraum = class {
 			this.nodeMesh.material.depthTest = mode === "3d";
 			this.nodeMesh.material.depthWrite = mode === "3d";
 			this.nodeMesh.material.needsUpdate = true;
-			this.nodeMesh.renderOrder = mode === "2d" ? 1 : 0;
-		}
-		if (this.edgeMesh && !Array.isArray(this.edgeMesh.material)) {
-			this.edgeMesh.material.depthTest = mode === "3d";
-			this.edgeMesh.material.depthWrite = mode === "3d";
-			this.edgeMesh.material.needsUpdate = true;
-			this.edgeMesh.renderOrder = mode === "2d" ? -1 : 0;
 		}
 		this.fitView();
 	}
 	getMode() {
 		return this.mode;
 	}
+	/**
+	* Slowly orbits the 3D camera around its target until called with `false`. The orbit pauses while
+	* the camera controls handle a drag, pinch or wheel step and resumes after `resumeAfterMs` of idle;
+	* it also stops while the document is hidden or the canvas is off screen. While it is active a
+	* frame loop renders every frame (no viewport rematerialization), so check `prefers-reduced-motion`
+	* before enabling it. Throws in 2D mode; `setMode("2d")` turns it off. Does nothing after `destroy()`.
+	*/
+	setAutoOrbit(options) {
+		if (options === false || this.destroyed) {
+			this.stopAutoOrbit();
+			return;
+		}
+		if (this.mode !== "3d") throw new Error("Auto-orbit requires 3D mode. Call setMode(\"3d\") before setAutoOrbit(options).");
+		const { resumeAfterMs, speed } = resolveAutoOrbitOptions(options);
+		this.controls.autoRotateSpeed = autoRotateSpeedFor(speed);
+		if (this.autoOrbit && this.autoOrbit.status !== "off") this.autoOrbit.setResumeAfterMs(resumeAfterMs);
+		else this.autoOrbit = new AutoOrbitLoop(this.renderer.domElement, this.controls, resumeAfterMs, this.stepAutoOrbit);
+	}
 	getNodePresentation(nodeId) {
 		return this.nodePresentations.get(nodeId) ?? null;
 	}
@@ -2595,6 +3436,7 @@ var Graphraum = class {
 	getDiagnostics() {
 		return {
 			aggregatedNodeClusters: this.densityLodActive ? this.visibleNodeCount : 0,
+			autoOrbit: this.autoOrbit?.status ?? "off",
 			cpuFrameMilliseconds: this.cpuFrameMilliseconds,
 			gpuFrameMilliseconds: this.gpuFrameMilliseconds,
 			gpuDrawCalls: this.renderer.info.render.calls,
@@ -2602,6 +3444,7 @@ var Graphraum = class {
 			gpuTextures: this.renderer.info.memory.textures,
 			lodLevel: resolveLodLevel(this.densityLodActive, this.visibleEdgeCandidateCount, this.visibleEdgeCount),
 			pickingStrategy: this.mode === "2d" ? "spatial-grid-2d" : "raycaster-3d",
+			dimmedEdges: this.dimmedEdgeIds.size,
 			selectedEdges: this.selectedEdgeIds.size,
 			selectedNodes: this.selectedNodeIds.size,
 			totalEdges: this.data.edges.length,
@@ -2610,6 +3453,7 @@ var Graphraum = class {
 			visibleEdgeMarkers: this.visibleEdgeMarkerCount,
 			visibleEdgeSegments: this.visibleEdgeSegmentCount,
 			visibleEdges: this.visibleEdgeCount,
+			visibleGlowNodes: this.glowLayer.count,
 			visibleNodes: this.visibleNodeCount,
 			visibleNodeCandidates: this.visibleNodeCandidateCount
 		};
@@ -2636,52 +3480,207 @@ var Graphraum = class {
 			id: edgeId
 		} : null;
 	}
-	fitView() {
+	/** Frames every node, or only `nodeIds`; unknown ids are ignored and no match frames all nodes. Cancels a running `flyTo`. */
+	fitView(options) {
+		this.cancelFlight();
 		if (!this.nodeMesh || this.data.nodes.length === 0) {
 			this.requestRender();
 			return;
 		}
-		const bounds = new Box3();
-		const minimum = new Vector3();
-		const maximum = new Vector3();
-		for (const node of this.data.nodes) {
-			const { height, width } = resolveNodeAxes({
-				height: node.height,
-				nodeId: node.id,
-				size: node.size,
-				width: node.width
-			});
-			const radius = Math.max(width, height);
-			const z = node.position.z ?? 0;
-			bounds.expandByPoint(minimum.set(node.position.x - radius, node.position.y - radius, z - radius));
-			bounds.expandByPoint(maximum.set(node.position.x + radius, node.position.y + radius, z + radius));
-		}
-		const center = bounds.getCenter(new Vector3());
-		const size = bounds.getSize(new Vector3());
+		const subset = this.nodesWithIds(options?.nodeIds);
+		const nodes = subset.length > 0 ? subset : this.data.nodes;
 		const width = Math.max(this.container.clientWidth, 1);
 		const height = Math.max(this.container.clientHeight, 1);
-		const aspect = width / height;
 		if (this.camera instanceof OrthographicCamera) {
-			const visibleHeight = Math.max(size.y, size.x / aspect, 1) * 1.15;
-			this.camera.left = -visibleHeight * aspect / 2;
-			this.camera.right = visibleHeight * aspect / 2;
-			this.camera.top = visibleHeight / 2;
-			this.camera.bottom = -visibleHeight / 2;
-			this.camera.position.set(center.x, center.y, center.z + Math.max(size.z, 1e3));
+			const aspect = width / height;
+			const fit = orthographicFit(aspect, nodes);
+			setOrthographicFrustum(this.camera, aspect, fit.visibleHeight);
+			this.camera.position.set(fit.center.x, fit.center.y, fit.cameraZ);
+			this.camera.lookAt(fit.center);
+			this.controls.target.copy(fit.center);
 		} else {
-			applyPerspectiveContainerAspect(this.camera, width, height);
-			const distance = Math.max(size.length() / 2, 1) / Math.sin(this.camera.fov * Math.PI / 360);
-			this.camera.position.set(center.x, center.y, center.z + distance * 1.15);
-			this.camera.near = Math.max(distance / 1e4, .1);
-			this.camera.far = distance * 10;
+			const fit = this.perspectiveFit(this.camera, width, height, nodes);
+			this.camera.near = fit.near;
+			this.camera.far = fit.far;
+			this.camera.position.set(fit.target.x, fit.target.y, fit.cameraZ);
+			this.controls.target.set(fit.target.x, fit.target.y, fit.target.z);
+			this.camera.lookAt(this.controls.target);
 		}
-		this.camera.lookAt(center);
 		this.camera.updateProjectionMatrix();
-		this.controls.target.copy(center);
 		this.controls.update();
 		this.materializeViewport();
 		this.requestRender();
 	}
+	/**
+	* Animates the camera to frame `nodeIds` as `fitView({ nodeIds })` would, with an ease-in-out
+	* over `durationMs`. In 3D the camera and the orbit target move together and keep the current
+	* view direction, so a running auto-orbit carries on around the new target, at the fitted
+	* distance times `distanceScale`. In 2D it pans and zooms. Resolves `true` on arrival and
+	* `false` when cancelled by canvas pointer, wheel or key input, another `flyTo`, `fitView`,
+	* `setData`, `setMode`, a 2D resize or `destroy()`. Unknown IDs are ignored; when none match,
+	* or after `destroy()`, it resolves `false` without moving. With `prefers-reduced-motion:
+	* reduce` or a zero duration it jumps. Throws for an invalid duration or distance scale.
+	*/
+	flyTo(options) {
+		const { distanceScale, durationMs } = resolveFlyToOptions(options);
+		this.cancelFlight();
+		if (this.destroyed || !this.nodeMesh) return Promise.resolve(false);
+		const nodes = this.nodesWithIds(options.nodeIds);
+		if (nodes.length === 0) return Promise.resolve(false);
+		const width = Math.max(this.container.clientWidth, 1);
+		const height = Math.max(this.container.clientHeight, 1);
+		const flight = this.camera instanceof OrthographicCamera ? this.planOrthographicFlight(this.camera, width / height, nodes, distanceScale) : this.planPerspectiveFlight(this.camera, width, height, nodes, distanceScale);
+		if (durationMs === 0 || prefersReducedMotion()) {
+			flight.step(1);
+			flight.arrive();
+			this.requestRender();
+			return Promise.resolve(true);
+		}
+		return new Promise((resolve) => {
+			this.flight = {
+				...flight,
+				durationMs,
+				resolve,
+				startMs: null
+			};
+			this.requestRender();
+		});
+	}
+	/** Nodes whose id is in `nodeIds`, in graph order; every node when `nodeIds` is omitted. */
+	nodesWithIds(nodeIds) {
+		if (!nodeIds) return this.data.nodes;
+		const wanted = new Set(nodeIds);
+		return this.data.nodes.filter((node) => wanted.has(node.id));
+	}
+	/** The closest front-view camera that frames `nodes` (issue #124); applies the container aspect. */
+	perspectiveFit(camera, width, height, nodes) {
+		applyPerspectiveContainerAspect(camera, width, height);
+		return fitPerspective({
+			aspect: camera.aspect,
+			fill: PERSPECTIVE_FIT_FILL,
+			fovDegrees: camera.fov
+		}, {
+			count: nodes.length,
+			read(index, out) {
+				const node = nodes[index];
+				const axes = resolveNodeAxes({
+					height: node.height,
+					nodeId: node.id,
+					size: node.size,
+					width: node.width
+				});
+				out.x = node.position.x;
+				out.y = node.position.y;
+				out.z = node.position.z ?? 0;
+				const extent = Math.max(axes.width, axes.height);
+				const glow = node.glow ?? 0;
+				const halo = glow > 0 ? glowHaloRadius(extent, glow) : 0;
+				out.halfWidth = Math.max(axes.width, halo);
+				out.halfHeight = Math.max(axes.height, halo);
+			}
+		});
+	}
+	/**
+	* A 3D flight keeps the view direction it reads from the camera every frame, so an orbit step
+	* between frames turns the flight with it. The destination distance is the front-view fit
+	* distance; near and far span both ends while flying, and the far plane at arrival still holds
+	* the whole graph so the rest of it stays visible around the framed nodes.
+	*/
+	planPerspectiveFlight(camera, width, height, nodes, distanceScale) {
+		const fit = this.perspectiveFit(camera, width, height, nodes);
+		const fromTarget = this.controls.target.clone();
+		const toTarget = new Vector3(fit.target.x, fit.target.y, fit.target.z);
+		const fromDistance = Math.max(camera.position.distanceTo(fromTarget), Number.EPSILON);
+		const toDistance = (fit.cameraZ - fit.target.z) * distanceScale;
+		const near = fit.near * Math.min(distanceScale, 1);
+		const far = Math.max(fit.far * distanceScale, (toDistance + this.graphRadiusAround(toTarget)) * 1.1);
+		camera.near = Math.min(camera.near, near);
+		camera.far = Math.max(camera.far, far);
+		camera.updateProjectionMatrix();
+		return {
+			arrive: () => {
+				camera.near = near;
+				camera.far = far;
+				camera.updateProjectionMatrix();
+				this.materializeViewport();
+			},
+			step: (eased) => {
+				const direction = this.flightDirection.subVectors(camera.position, this.controls.target);
+				if (direction.lengthSq() === 0) direction.set(0, 0, 1);
+				direction.normalize();
+				this.controls.target.lerpVectors(fromTarget, toTarget, eased);
+				camera.position.copy(this.controls.target).addScaledVector(direction, interpolateScale(fromDistance, toDistance, eased));
+				camera.lookAt(this.controls.target);
+			}
+		};
+	}
+	/**
+	* A 2D flight switches to the destination frustum up front with a zoom that keeps the current
+	* view, then pans and eases the zoom back to 1, so it lands exactly on the fitted frustum.
+	*/
+	planOrthographicFlight(camera, aspect, nodes, distanceScale) {
+		const fit = orthographicFit(aspect, nodes);
+		const fromVisibleHeight = (camera.top - camera.bottom) / camera.zoom;
+		const toVisibleHeight = fit.visibleHeight * distanceScale;
+		setOrthographicFrustum(camera, aspect, toVisibleHeight);
+		const fromZoom = toVisibleHeight / fromVisibleHeight;
+		camera.zoom = fromZoom;
+		camera.updateProjectionMatrix();
+		const fromPosition = camera.position.clone();
+		const toPosition = new Vector3(fit.center.x, fit.center.y, fit.cameraZ);
+		const fromTarget = this.controls.target.clone();
+		return {
+			arrive: () => this.materializeViewport(),
+			step: (eased) => {
+				camera.zoom = interpolateScale(fromZoom, 1, eased);
+				camera.position.lerpVectors(fromPosition, toPosition, eased);
+				this.controls.target.lerpVectors(fromTarget, fit.center, eased);
+				camera.updateProjectionMatrix();
+			}
+		};
+	}
+	/** Largest distance from `center` to any node's far edge. */
+	graphRadiusAround(center) {
+		let radius = 0;
+		for (const node of this.data.nodes) {
+			const axes = resolveNodeAxes({
+				height: node.height,
+				nodeId: node.id,
+				size: node.size,
+				width: node.width
+			});
+			const distance = Math.hypot(node.position.x - center.x, node.position.y - center.y, (node.position.z ?? 0) - center.z);
+			radius = Math.max(radius, distance + Math.max(axes.width, axes.height));
+		}
+		return radius;
+	}
+	/** Steps a running flight to the frame time; settles and resolves it at the end. */
+	advanceFlight(nowMs) {
+		const flight = this.flight;
+		if (!flight) return;
+		flight.startMs ??= nowMs;
+		const progress = flightProgress(nowMs - flight.startMs, flight.durationMs);
+		try {
+			flight.step(easeInOutCubic(progress));
+			if (progress < 1) {
+				if (this.mode === "2d") this.materializeViewport();
+				this.requestRender();
+				return;
+			}
+			this.flight = null;
+			flight.arrive();
+		} catch (error) {
+			this.cancelFlight();
+			throw error;
+		}
+		flight.resolve(true);
+	}
+	cancelFlight = () => {
+		const flight = this.flight;
+		if (!flight) return;
+		this.flight = null;
+		flight.resolve(false);
+	};
 	setTheme(theme) {
 		this.theme = typeof theme === "string" ? resolveGraphraumTheme(theme) : resolveGraphraumTheme(theme, this.theme);
 		this.applyBackground();
@@ -2706,9 +3705,13 @@ var Graphraum = class {
 		this.requestRender();
 	}
 	destroy() {
+		this.destroyed = true;
+		this.cancelFlight();
+		this.stopAutoOrbit();
 		this.resizeObserver.disconnect();
 		this.renderer.domElement.removeEventListener("pointermove", this.handlePointerMove);
 		this.renderer.domElement.removeEventListener("pointerleave", this.handlePointerLeave);
+		for (const type of FLIGHT_CANCEL_EVENTS) this.renderer.domElement.removeEventListener(type, this.cancelFlight);
 		this.controls.removeEventListener("change", this.handleViewChange);
 		this.controls.dispose();
 		if (this.frameRequest !== null) cancelAnimationFrame(this.frameRequest);
@@ -2720,22 +3723,63 @@ var Graphraum = class {
 	}
 	requestRender = () => {
 		if (this.frameRequest !== null) return;
-		this.frameRequest = requestAnimationFrame(() => {
+		this.frameRequest = requestAnimationFrame((nowMs) => {
 			this.frameRequest = null;
-			this.readGpuTimers();
-			const timer = this.gpuTimer;
-			const query = timer?.context.createQuery() ?? null;
-			if (timer && query) timer.context.beginQuery(timer.extension.TIME_ELAPSED_EXT, query);
-			const startedAt = performance.now();
-			this.renderer.render(this.scene, this.camera);
-			this.cpuFrameMilliseconds = performance.now() - startedAt;
-			if (timer && query) {
-				timer.context.endQuery(timer.extension.TIME_ELAPSED_EXT);
-				timer.pending.push(query);
-			}
-			for (const listener of this.viewListeners) listener();
+			this.advanceFlight(nowMs);
+			this.renderFrame();
 		});
 	};
+	/** Renders a pending frame now instead of on the next animation frame. */
+	flushRender() {
+		if (this.frameRequest === null) return;
+		cancelAnimationFrame(this.frameRequest);
+		this.frameRequest = null;
+		this.renderFrame();
+	}
+	renderFrame() {
+		this.readGpuTimers();
+		const timer = this.gpuTimer;
+		const query = timer?.context.createQuery() ?? null;
+		if (timer && query) timer.context.beginQuery(timer.extension.TIME_ELAPSED_EXT, query);
+		const startedAt = performance.now();
+		this.renderer.render(this.scene, this.camera);
+		this.cpuFrameMilliseconds = performance.now() - startedAt;
+		if (timer && query) {
+			timer.context.endQuery(timer.extension.TIME_ELAPSED_EXT);
+			timer.pending.push(query);
+		}
+		for (const listener of this.viewListeners) listener();
+	}
+	stopAutoOrbit() {
+		this.autoOrbit?.dispose();
+		this.autoOrbit = null;
+	}
+	/**
+	* One orbit frame. `autoRotate` is on only for this `update(dt)` call: OrbitControls also calls
+	* `update()` without a delta from wheel and key handlers and `fitView`, which would otherwise add
+	* a fixed per-call rotation. A moved camera emits `change` (a render request only, see
+	* `handleViewChange`); flushing that request renders this frame instead of the next one. During
+	* a `flyTo` the orbit still turns the camera but leaves the pending frame to the flight, which
+	* steps from the turned direction before it renders. A
+	* throwing update, render or view listener turns the orbit off rather than leaving it enabled
+	* without a loop.
+	*/
+	stepAutoOrbit = (deltaSeconds) => {
+		try {
+			this.controls.autoRotate = true;
+			this.orbitUpdating = true;
+			try {
+				this.controls.update(deltaSeconds);
+			} finally {
+				this.controls.autoRotate = false;
+				this.orbitUpdating = false;
+			}
+			if (this.flight === null) this.flushRender();
+		} catch (error) {
+			this.stopAutoOrbit();
+			throw error;
+		}
+	};
 	readGpuTimers() {
 		const timer = this.gpuTimer;
 		if (!timer) return;
@@ -2747,8 +3791,15 @@ var Graphraum = class {
 			timer.context.deleteQuery(query);
 		}
 	}
+	/**
+	* Orbit frames skip materialization. In 3D the packed instances do not depend on camera
+	* orientation: there is no viewport culling, density LOD and edge tiers follow counts only,
+	* and the one orientation-dependent value (`worldUnitsPerPixel`, for edge hit slop) is used
+	* only by 2D picking. 3D picking raycasts the instances and screen positions are projected per
+	* call, so an orbit frame needs only a render, whose view listeners still run every frame.
+	*/
 	handleViewChange = () => {
-		this.materializeViewport();
+		if (!this.orbitUpdating) this.materializeViewport();
 		this.requestRender();
 	};
 	createCamera() {
@@ -2758,12 +3809,8 @@ var Graphraum = class {
 	createControls() {
 		const controls = new OrbitControls(this.camera, this.renderer.domElement);
 		controls.enableDamping = false;
-		controls.enableRotate = this.mode === "3d";
 		controls.screenSpacePanning = true;
-		if (this.mode === "2d") {
-			controls.minZoom = .01;
-			controls.mouseButtons.LEFT = MOUSE.PAN;
-		}
+		configureControlsForMode(controls, this.mode);
 		controls.addEventListener("change", this.handleViewChange);
 		return controls;
 	}
@@ -2854,7 +3901,35 @@ var Graphraum = class {
 			slots.push(slot);
 		}
 		markInstanceColorSlots(this.nodeMesh.instanceColor, slots);
+		this.glowLayer.rewrite(this.describeGlowNode);
 	}
+	/** Rebuilds the opt-in halo pass; graphs without glow release it and skip the visible scan. */
+	syncGlow() {
+		if (!this.hasGlowNodes) {
+			this.glowLayer.dispose();
+			return;
+		}
+		this.glowLayer.setBlending(glowBlendModeFor(this.theme.background));
+		this.glowLayer.sync(this.visibleNodeIndices, this.glowAt, this.densityLodActive, this.describeGlowNode);
+	}
+	glowAt = (nodeIndex) => this.data.nodes[nodeIndex]?.glow ?? 0;
+	describeGlowNode = (nodeIndex, target) => {
+		const node = this.data.nodes[nodeIndex];
+		if (!node) return false;
+		const { height, width } = resolveNodeAxes({
+			height: node.height,
+			nodeId: node.id,
+			size: node.size,
+			width: node.width
+		});
+		target.color.copy(this.getNodeColor(node));
+		target.extent = Math.max(width, height);
+		target.glow = node.glow ?? 0;
+		target.x = node.position.x;
+		target.y = node.position.y;
+		target.z = node.position.z ?? 0;
+		return true;
+	};
 	getNodeStateIds(state) {
 		switch (state) {
 			case "dimmed": return this.dimmedNodeIds;
@@ -3000,10 +4075,8 @@ var Graphraum = class {
 		const worldPerPixel = this.worldUnitsPerPixel();
 		const packed = packEdgeInstances({
 			edgeIndices: visibleEdgeIndices,
-			edgeVisuals: this.data.edges.map((edge) => this.selectedEdgeIds.has(edge.id) ? {
-				...edge,
-				color: this.theme.selectedEdge
-			} : edge),
+			edgeStates: this.edgeStateStyling(),
+			edgeVisuals: this.data.edges,
 			endpointPositions: this.canonicalEdgePositions,
 			defaults: {
 				color: this.theme.edge,
@@ -3014,6 +4087,7 @@ var Graphraum = class {
 			maxSegments: this.edgeSegmentCapacity,
 			endpointAttach: this.theme.endpointAttach,
 			edgeNodeIndices: this.edgeNodeIndices,
+			mode: this.mode,
 			nodeOutlines: this.data.nodes.map((node) => ({
 				height: node.height,
 				shape: node.shape,
@@ -3063,6 +4137,7 @@ var Graphraum = class {
 		this.visibleEdgeSegmentCount = segmentCount;
 		this.visibleEdgeCount = distinctEdges.size;
 		this.visibleEdgeMarkerCount = packed.markers.length;
+		this.syncGlow();
 	}
 	materializeNodes(indices, bounds) {
 		if (!this.densityLodActive || !bounds) return indices.slice(0, this.maxVisibleNodes).flatMap((index) => {
@@ -3124,6 +4199,7 @@ var Graphraum = class {
 		return [...clusters.values()].slice(0, this.maxVisibleNodes);
 	}
 	disposeGraphObjects() {
+		this.glowLayer.dispose();
 		this.pickableEdgeSegments = [];
 		this.visibleEdgeSegmentEdgeIndices = [];
 		this.visibleEdgeLayouts = /* @__PURE__ */ new Map();
@@ -3146,6 +4222,42 @@ var Graphraum = class {
 		}
 	}
 };
+/** The 2D fit: the nodes' padded bounds, framed with 15% slack on the tighter axis. */
+function orthographicFit(aspect, nodes) {
+	const bounds = new Box3();
+	const minimum = new Vector3();
+	const maximum = new Vector3();
+	for (const node of nodes) {
+		const { height, width } = resolveNodeAxes({
+			height: node.height,
+			nodeId: node.id,
+			size: node.size,
+			width: node.width
+		});
+		const radius = Math.max(width, height);
+		const z = node.position.z ?? 0;
+		bounds.expandByPoint(minimum.set(node.position.x - radius, node.position.y - radius, z - radius));
+		bounds.expandByPoint(maximum.set(node.position.x + radius, node.position.y + radius, z + radius));
+	}
+	const center = bounds.getCenter(new Vector3());
+	const size = bounds.getSize(new Vector3());
+	return {
+		cameraZ: center.z + Math.max(size.z, 1e3),
+		center,
+		visibleHeight: Math.max(size.y, size.x / aspect, 1) * 1.15
+	};
+}
+/** Sets a frustum that shows `visibleHeight` world units at zoom 1 and resets the zoom. */
+function setOrthographicFrustum(camera, aspect, visibleHeight) {
+	camera.left = -visibleHeight * aspect / 2;
+	camera.right = visibleHeight * aspect / 2;
+	camera.top = visibleHeight / 2;
+	camera.bottom = -visibleHeight / 2;
+	camera.zoom = 1;
+}
+function hasNodeGlow(node) {
+	return (node.glow ?? 0) > 0;
+}
 function nextCapacity(length) {
 	let capacity = 1;
 	while (capacity < length) capacity *= 2;