@yggy-tech/graphraum 0.35.0 → 0.37.0

package/dist/index.js

@@ -1,4 +1,4 @@
-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 { AdditiveBlending, Box3, BufferGeometry, CanvasTexture, Color, DepthTexture, Float32BufferAttribute, GLSL3, InstancedBufferAttribute, InstancedMesh, MOUSE, Matrix4, Mesh, MeshBasicMaterial, NoBlending, NormalBlending, OrthographicCamera, PerspectiveCamera, Plane, PlaneGeometry, Raycaster, RepeatWrapping, SRGBColorSpace, Scene, ShaderMaterial, SphereGeometry, TOUCH, Texture, UnsignedByteType, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 //#region src/node-axes.ts
 function assertPositiveFinite(value, axis, nodeId) {
@@ -904,6 +904,63 @@ function interpolateScale(from, to, t) {
 	return from * (to / from) ** t;
 }
 //#endregion
+//#region src/camera-state.ts
+/**
+* Checks a camera state before it touches the camera: an object of the graph's mode with finite
+* numbers, a positive visible height in 2D, and a position apart from the target in 3D. The state
+* is usually parsed JSON, so nothing about its shape is taken on trust.
+*/
+function validateCameraState(state, mode) {
+	if (typeof state !== "object" || state === null) throw new Error("A camera state must be an object returned by getCameraState().");
+	const stateMode = state.mode;
+	if (stateMode !== "2d" && stateMode !== "3d") throw new Error(`A camera state needs mode "2d" or "3d"; received ${JSON.stringify(stateMode)}.`);
+	if (state.mode !== mode) throw new Error(`Cannot apply a ${state.mode} camera state to a graph in ${mode} mode; call setMode("${state.mode}") first.`);
+	if (state.mode === "2d") {
+		const x = finite(state.center?.x, "center.x");
+		const y = finite(state.center?.y, "center.y");
+		const visibleHeight = finite(state.visibleHeight, "visibleHeight");
+		if (visibleHeight <= 0) throw new Error(`Camera state visibleHeight must be above 0; received ${visibleHeight}.`);
+		return {
+			center: {
+				x,
+				y
+			},
+			mode: "2d",
+			visibleHeight
+		};
+	}
+	const position = point3d(state.position, "position");
+	const target = point3d(state.target, "target");
+	if (position.x === target.x && position.y === target.y && position.z === target.z) throw new Error("Camera state position and target must differ.");
+	return {
+		mode: "3d",
+		position,
+		target
+	};
+}
+function point3d(value, name) {
+	return {
+		x: finite(value?.x, `${name}.x`),
+		y: finite(value?.y, `${name}.y`),
+		z: finite(value?.z, `${name}.z`)
+	};
+}
+function finite(value, name) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`Camera state ${name} must be a finite number; received ${String(value)}.`);
+	return value;
+}
+/**
+* Clip planes for a perspective camera `distance` from its target with the graph reaching
+* `graphRadius` around it: the far plane holds the whole graph with the slack a fit leaves for
+* zooming out, and the near plane stays close enough not to cut nodes in front of the camera.
+*/
+function perspectiveClipRange(distance, graphRadius) {
+	return {
+		far: Math.max(distance * 10, (distance + graphRadius) * 1.1),
+		near: Math.min(Math.max(distance / 1e4, .1), distance / 2)
+	};
+}
+//#endregion
 //#region src/theme.ts
 /** Dark canvas: Ink Black, Turf Green, Porcelain. */
 const graphraumThemeDark = Object.freeze({
@@ -1203,6 +1260,501 @@ function isAppendOnlyDataPatch(patch) {
 	return (patch.removedNodeIds?.length ?? 0) === 0 && (patch.removedEdgeIds?.length ?? 0) === 0;
 }
 //#endregion
+//#region src/depth-of-field.ts
+const DEPTH_OF_FIELD_DEFAULTS = {
+	enabled: false,
+	farDistance: Number.POSITIVE_INFINITY,
+	focus: "selection",
+	maxBlur: 12,
+	minBlur: 0,
+	nearDistance: 0,
+	strength: .5,
+	transition: {
+		durationMs: 400,
+		easing: "easeInOut"
+	}
+};
+const EASINGS = {
+	easeIn: (t) => t * t * t,
+	easeInOut: easeInOutCubic,
+	easeOut: (t) => 1 - (1 - t) ** 3,
+	linear: (t) => t
+};
+function resolveEasing(easing) {
+	return typeof easing === "function" ? easing : EASINGS[easing];
+}
+function isEasing(value) {
+	return typeof value === "function" || typeof value === "string" && Object.hasOwn(EASINGS, value);
+}
+function isNonNegativeNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+/** Validates `options` and merges them onto `base`. Throws an actionable error for invalid values. */
+function resolveDepthOfFieldOptions(options, base = DEPTH_OF_FIELD_DEFAULTS) {
+	if (typeof options !== "object" || options === null) throw new Error("Depth of field options must be an object, e.g. { enabled: true, strength: 0.5 }.");
+	if (options.transition !== void 0 && (typeof options.transition !== "object" || options.transition === null)) throw new Error("Depth of field transition must be an object, e.g. { durationMs: 400, easing: \"easeInOut\" }.");
+	const resolved = {
+		enabled: options.enabled ?? base.enabled,
+		farDistance: options.farDistance ?? base.farDistance,
+		focus: options.focus ?? base.focus,
+		maxBlur: options.maxBlur ?? base.maxBlur,
+		minBlur: options.minBlur ?? base.minBlur,
+		nearDistance: options.nearDistance ?? base.nearDistance,
+		strength: options.strength ?? base.strength,
+		transition: {
+			durationMs: options.transition?.durationMs ?? base.transition.durationMs,
+			easing: options.transition?.easing ?? base.transition.easing
+		}
+	};
+	const { enabled, farDistance, focus, maxBlur, minBlur, nearDistance, strength, transition } = resolved;
+	if (typeof enabled !== "boolean") throw new Error(`Depth of field enabled must be a boolean; received ${String(enabled)}.`);
+	if (!isNonNegativeNumber(strength) || strength > 1) throw new Error(`Depth of field strength must be a number from 0 to 1; received ${String(strength)}.`);
+	if (focus !== "selection" && (typeof focus !== "number" || !Number.isFinite(focus) || focus <= 0)) throw new Error(`Depth of field focus must be "selection" or a camera distance above 0 in world units; received ${String(focus)}.`);
+	if (!isNonNegativeNumber(maxBlur) || !isNonNegativeNumber(minBlur) || minBlur > maxBlur) throw new Error(`Depth of field minBlur and maxBlur must be non-negative CSS pixel radii with minBlur <= maxBlur; received ${String(minBlur)} and ${String(maxBlur)}.`);
+	if (!isNonNegativeNumber(nearDistance) || typeof farDistance !== "number" || Number.isNaN(farDistance) || farDistance <= nearDistance) throw new Error(`Depth of field nearDistance must be a non-negative world distance below farDistance; received ${String(nearDistance)} and ${String(farDistance)}.`);
+	if (!isNonNegativeNumber(transition.durationMs)) throw new Error(`Depth of field transition durationMs must be a non-negative finite number of milliseconds; received ${String(transition.durationMs)}.`);
+	if (!isEasing(transition.easing)) throw new Error(`Depth of field transition easing must be "linear", "easeIn", "easeOut", "easeInOut" or a function; received ${String(transition.easing)}.`);
+	return resolved;
+}
+/**
+* How much of `strength` applies when the focus is `focusDistance` from the camera: 1 up to
+* `nearDistance`, easing to 0 at `farDistance`, so a zoomed-out overview stays sharp.
+*/
+function distanceFade(focusDistance, nearDistance, farDistance) {
+	if (focusDistance <= nearDistance) return 1;
+	if (focusDistance >= farDistance) return 0;
+	const t = (focusDistance - nearDistance) / (farDistance - nearDistance);
+	return 1 - t * t * (3 - 2 * t);
+}
+/** Distance in front of the camera along its view axis, from a column-major view matrix (`matrixWorldInverse`). */
+function viewDistance(point, viewMatrix) {
+	const m = (index) => viewMatrix[index] ?? 0;
+	return -(m(2) * point.x + m(6) * point.y + m(10) * point.z + m(14));
+}
+/** Mean position of `points`, or null when there are none. */
+function meanPoint(points) {
+	let count = 0;
+	const sum = {
+		x: 0,
+		y: 0,
+		z: 0
+	};
+	for (const point of points) {
+		count += 1;
+		sum.x += point.x;
+		sum.y += point.y;
+		sum.z += point.z;
+	}
+	return count === 0 ? null : {
+		x: sum.x / count,
+		y: sum.y / count,
+		z: sum.z / count
+	};
+}
+/**
+* A scalar animated toward a target. Retargeting starts from the value shown last, so an interrupted
+* transition continues smoothly instead of restarting. Each retarget returns a promise that resolves
+* `true` when the value arrives and `false` when another retarget or `cancel` replaces it.
+*/
+var Tween = class {
+	from;
+	to;
+	value;
+	startMs = null;
+	durationMs = 0;
+	easing = EASINGS.linear;
+	settle = null;
+	constructor(value) {
+		this.from = value;
+		this.to = value;
+		this.value = value;
+	}
+	get target() {
+		return this.to;
+	}
+	get settled() {
+		return this.settle === null && this.value === this.to;
+	}
+	retarget(to, durationMs, easing) {
+		this.settle?.(false);
+		this.settle = null;
+		this.from = this.value;
+		this.to = to;
+		this.startMs = null;
+		this.durationMs = durationMs;
+		this.easing = easing;
+		if (durationMs === 0 || this.from === to) {
+			this.value = to;
+			return Promise.resolve(true);
+		}
+		return new Promise((resolve) => {
+			this.settle = resolve;
+		});
+	}
+	/** Value at `nowMs`; the first sample after a retarget starts its clock. */
+	sample(nowMs) {
+		if (this.settle === null) return this.value;
+		this.startMs ??= nowMs;
+		const progress = flightProgress(nowMs - this.startMs, this.durationMs);
+		this.value = progress >= 1 ? this.to : this.from + (this.to - this.from) * this.easing(progress);
+		if (progress >= 1) this.finish(true);
+		return this.value;
+	}
+	/** Arrives at the target now, e.g. for reduced motion or when nothing renders the frames. */
+	jump() {
+		this.value = this.to;
+		this.finish(true);
+	}
+	cancel() {
+		this.finish(false);
+	}
+	finish(arrived) {
+		const settle = this.settle;
+		this.settle = null;
+		settle?.(arrived);
+	}
+};
+/**
+* Animates the focus between selections. The focus is a world point rather than a depth, so its
+* distance is re-measured from the camera every frame and the selected nodes stay sharp while the
+* camera orbits, pans or zooms; only a selection change animates. With no target the blur fades out
+* around the last focus point. A retarget mid-transition continues from the focus shown last.
+*/
+var DepthOfFieldFocus = class {
+	transition = null;
+	lastAmount = 0;
+	lastPoint = null;
+	/** Starts a transition from the focus shown in the last frame, e.g. after a selection change. */
+	retarget(durationMs, easing) {
+		this.transition = {
+			durationMs,
+			easing,
+			fromAmount: this.lastAmount,
+			fromPoint: this.lastAmount > 0 ? this.lastPoint : null,
+			startMs: null
+		};
+	}
+	/** Focus for the frame at `nowMs`. `jump` (reduced motion) skips the animation. */
+	evaluate(nowMs, target, jump) {
+		const transition = this.transition;
+		const toAmount = target ? 1 : 0;
+		let eased = 1;
+		let progress = 1;
+		if (transition && !jump && transition.durationMs > 0) {
+			transition.startMs ??= nowMs;
+			progress = flightProgress(nowMs - transition.startMs, transition.durationMs);
+			eased = progress >= 1 ? 1 : transition.easing(progress);
+		}
+		const fromAmount = transition?.fromAmount ?? toAmount;
+		const fromPoint = transition?.fromPoint ?? null;
+		const amount = fromAmount + (toAmount - fromAmount) * eased;
+		const point = target ? fromPoint ? lerpPoint(fromPoint, target, eased) : target : fromPoint ?? this.lastPoint;
+		const settled = progress >= 1;
+		if (settled) this.transition = null;
+		this.lastAmount = amount;
+		this.lastPoint = point;
+		return {
+			amount,
+			point,
+			settled
+		};
+	}
+};
+function lerpPoint(from, to, t) {
+	return {
+		x: from.x + (to.x - from.x) * t,
+		y: from.y + (to.y - from.y) * t,
+		z: from.z + (to.z - from.z) * t
+	};
+}
+//#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/depth-of-field-pass.ts
+/** Layer the edge mesh joins so the edge depth pass can draw it alone. Picking raycasts layer 0. */
+const EDGE_DEPTH_LAYER = 1;
+/** Disk taps around the centre of each half-resolution blur texel. */
+const BLUR_TAPS = 48;
+const vertexShader$3 = `
+varying vec2 vUv;
+
+void main() {
+	vUv = uv;
+	gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+const blurRadiusChunk = `
+#include <packing>
+uniform sampler2D nodeDepth;
+uniform sampler2D edgeDepth;
+uniform ivec2 depthSize;
+uniform float cameraNear;
+uniform float cameraFar;
+uniform float focusDistance;
+uniform float aperture;
+uniform float minBlur;
+uniform float maxBlur;
+
+float surfaceDistance(ivec2 pixel) {
+	pixel = clamp(pixel, ivec2(0), depthSize - 1);
+	float depth = texelFetch(nodeDepth, pixel, 0).x;
+	if (depth >= 1.0) depth = texelFetch(edgeDepth, pixel, 0).x;
+	return -perspectiveDepthToViewZ(depth, cameraNear, cameraFar);
+}
+
+float radiusAt(float surface) {
+	float radius = aperture * abs(surface - focusDistance) / max(surface, 1e-6);
+	return radius < minBlur ? 0.0 : min(radius, maxBlur);
+}
+
+float blurRadius(ivec2 pixel) {
+	return radiusAt(surfaceDistance(pixel));
+}
+`;
+const blurFragmentShader = `
+${blurRadiusChunk}
+uniform sampler2D colorTexture;
+layout(location = 0) out highp vec4 blurColor;
+layout(location = 1) out highp vec4 nearColor;
+
+const float GOLDEN_ANGLE = 2.39996323;
+
+void main() {
+	ivec2 base = ivec2(gl_FragCoord.xy) * 2;
+	float centreSurface = surfaceDistance(base);
+	vec4 sum = texelFetch(colorTexture, base, 0);
+	float total = 1.0;
+	vec4 near = vec4(0.0);
+	// Interleaved gradient noise turns the spiral's fixed tap pattern into fine noise that the
+	// composite's bilinear upsample smooths, instead of hatching along blurred edges.
+	float rotation = 6.28318531 * fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));
+	for (int index = 0; index < ${BLUR_TAPS}; index++) {
+		float distanceFromCentre = sqrt((float(index) + 0.5) / ${BLUR_TAPS}.0) * maxBlur;
+		float angle = float(index) * GOLDEN_ANGLE + rotation;
+		ivec2 pixel = clamp(base + ivec2(floor(vec2(cos(angle), sin(angle)) * distanceFromCentre + 0.5)), ivec2(0), depthSize - 1);
+		float surface = surfaceDistance(pixel);
+		float radius = radiusAt(surface);
+		float weight = clamp(radius - distanceFromCentre + 1.0, 0.0, 1.0);
+		vec4 color = texelFetch(colorTexture, pixel, 0);
+		sum += color * weight;
+		total += weight;
+		if (surface < focusDistance && surface < centreSurface) {
+			near += color * weight * (maxBlur * maxBlur / max(radius * radius, 1.0));
+		}
+	}
+	blurColor = sum / total;
+	near /= ${BLUR_TAPS}.0;
+	nearColor = near.a > 1.0 ? near / near.a : near;
+}
+`;
+const compositeFragmentShader = `
+${blurRadiusChunk}
+uniform sampler2D sharpTexture;
+uniform sampler2D blurTexture;
+uniform sampler2D nearTexture;
+varying vec2 vUv;
+
+void main() {
+	ivec2 pixel = ivec2(gl_FragCoord.xy);
+	vec4 near = texture2D(nearTexture, vUv);
+	vec4 sharp = texelFetch(sharpTexture, pixel, 0);
+	sharp = near + sharp * (1.0 - near.a);
+	vec4 blurred = texture2D(blurTexture, vUv);
+	gl_FragColor = mix(sharp, blurred, smoothstep(0.5, 2.0, blurRadius(pixel)));
+	${OUTPUT_COLOR_SPACE_FRAGMENT}
+}
+`;
+function blurUniforms() {
+	return {
+		cameraFar: { value: 1 },
+		aperture: { value: 0 },
+		cameraNear: { value: .1 },
+		depthSize: { value: new Vector2() },
+		edgeDepth: { value: null },
+		focusDistance: { value: 1 },
+		maxBlur: { value: 0 },
+		minBlur: { value: 0 },
+		nodeDepth: { value: null }
+	};
+}
+function fullscreenMaterial(fragmentShader, uniforms, glslVersion = null) {
+	return new ShaderMaterial({
+		blending: NoBlending,
+		depthTest: false,
+		depthWrite: false,
+		fragmentShader,
+		glslVersion,
+		uniforms,
+		vertexShader: vertexShader$3
+	});
+}
+/** One triangle that covers the viewport. */
+function fullscreenTriangle() {
+	const geometry = new BufferGeometry();
+	geometry.setAttribute("position", new Float32BufferAttribute([
+		-1,
+		-1,
+		0,
+		3,
+		-1,
+		0,
+		-1,
+		3,
+		0
+	], 3));
+	geometry.setAttribute("uv", new Float32BufferAttribute([
+		0,
+		0,
+		2,
+		0,
+		0,
+		2
+	], 2));
+	return geometry;
+}
+/**
+* Renders the scene into a target, the edges into a depth-only target, blurs at half resolution and
+* composites onto the canvas: three extra draw calls per frame while it runs.
+* Created only while depth of field has something to blur; `dispose` releases every GPU resource.
+*/
+var DepthOfFieldPass = class {
+	sceneTarget;
+	edgeDepthTarget;
+	blurTarget;
+	blurMaterial = fullscreenMaterial(blurFragmentShader, {
+		...blurUniforms(),
+		colorTexture: { value: null }
+	}, GLSL3);
+	compositeMaterial = fullscreenMaterial(compositeFragmentShader, {
+		...blurUniforms(),
+		blurTexture: { value: null },
+		nearTexture: { value: null },
+		sharpTexture: { value: null }
+	});
+	quad = new Mesh(fullscreenTriangle(), this.blurMaterial);
+	quadScene = new Scene().add(this.quad);
+	quadCamera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+	size = new Vector2();
+	/** Depth of field needs WebGL 2 for depth textures and sRGB render targets. */
+	static isSupported(renderer) {
+		return typeof WebGL2RenderingContext !== "undefined" && renderer.getContext() instanceof WebGL2RenderingContext;
+	}
+	constructor(antialias) {
+		const color = {
+			colorSpace: SRGBColorSpace,
+			type: UnsignedByteType
+		};
+		this.sceneTarget = new WebGLRenderTarget(1, 1, {
+			...color,
+			depthTexture: new DepthTexture(1, 1),
+			samples: antialias ? 4 : 0
+		});
+		this.edgeDepthTarget = new WebGLRenderTarget(1, 1, { depthTexture: new DepthTexture(1, 1) });
+		this.blurTarget = new WebGLRenderTarget(1, 1, {
+			...color,
+			count: 2
+		});
+		this.quad.frustumCulled = false;
+	}
+	render(renderer, scene, camera, edgeMesh, frame) {
+		const { x: width, y: height } = renderer.getDrawingBufferSize(this.size);
+		this.setSize(width, height);
+		const previousTarget = renderer.getRenderTarget();
+		renderer.setRenderTarget(this.sceneTarget);
+		renderer.render(scene, camera);
+		this.renderEdgeDepth(renderer, scene, camera, edgeMesh);
+		const shared = {
+			aperture: frame.aperturePixels,
+			cameraFar: camera.far,
+			cameraNear: camera.near,
+			depthSize: this.size,
+			edgeDepth: this.edgeDepthTarget.depthTexture,
+			focusDistance: frame.focusDistance,
+			maxBlur: frame.maxBlurPixels,
+			minBlur: frame.minBlurPixels,
+			nodeDepth: this.sceneTarget.depthTexture
+		};
+		this.quad.material = this.blurMaterial;
+		this.setUniforms(this.blurMaterial, {
+			...shared,
+			colorTexture: this.sceneTarget.texture
+		});
+		this.drawQuad(renderer, this.blurTarget);
+		this.quad.material = this.compositeMaterial;
+		this.setUniforms(this.compositeMaterial, {
+			...shared,
+			blurTexture: this.blurTarget.textures[0],
+			nearTexture: this.blurTarget.textures[1],
+			sharpTexture: this.sceneTarget.texture
+		});
+		this.drawQuad(renderer, previousTarget);
+	}
+	dispose() {
+		this.sceneTarget.depthTexture?.dispose();
+		this.sceneTarget.dispose();
+		this.edgeDepthTarget.depthTexture?.dispose();
+		this.edgeDepthTarget.dispose();
+		this.blurTarget.dispose();
+		this.blurMaterial.dispose();
+		this.compositeMaterial.dispose();
+		this.quad.geometry.dispose();
+	}
+	/** Draws the edges alone with depth writes on and colour writes off, then restores their material. */
+	renderEdgeDepth(renderer, scene, camera, edgeMesh) {
+		renderer.setRenderTarget(this.edgeDepthTarget);
+		if (!edgeMesh || edgeMesh.count === 0 || Array.isArray(edgeMesh.material)) {
+			renderer.clear();
+			return;
+		}
+		const material = edgeMesh.material;
+		const { colorWrite, depthTest, depthWrite } = material;
+		const layerMask = camera.layers.mask;
+		const background = scene.background;
+		edgeMesh.layers.enable(EDGE_DEPTH_LAYER);
+		material.colorWrite = false;
+		material.depthTest = true;
+		material.depthWrite = true;
+		camera.layers.set(EDGE_DEPTH_LAYER);
+		scene.background = null;
+		try {
+			renderer.render(scene, camera);
+		} finally {
+			material.colorWrite = colorWrite;
+			material.depthTest = depthTest;
+			material.depthWrite = depthWrite;
+			camera.layers.mask = layerMask;
+			scene.background = background;
+		}
+	}
+	drawQuad(renderer, target) {
+		renderer.setRenderTarget(target);
+		renderer.render(this.quadScene, this.quadCamera);
+	}
+	setUniforms(material, values) {
+		for (const [name, value] of Object.entries(values)) {
+			const uniform = material.uniforms[name];
+			if (uniform) uniform.value = value;
+		}
+	}
+	setSize(width, height) {
+		if (this.sceneTarget.width === width && this.sceneTarget.height === height) return;
+		this.sceneTarget.setSize(width, height);
+		this.edgeDepthTarget.setSize(width, height);
+		const halfWidth = Math.max(1, Math.ceil(width / 2));
+		const halfHeight = Math.max(1, Math.ceil(height / 2));
+		this.blurTarget.setSize(halfWidth, halfHeight);
+	}
+};
+//#endregion
 //#region src/edge-paths.ts
 const AUTO_OFFSET_FRACTION = .18;
 function segmentCountForPath(path, tier) {
@@ -1492,17 +2044,6 @@ 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$2 = `
 attribute float instanceKind;
@@ -1952,6 +2493,231 @@ function prepareLayoutPositions(nodes, nodeIndices, layout) {
 		};
 	});
 }
+/**
+* Drags one node with the pointer. A press on a node arms a gesture; once the pointer leaves the
+* click tolerance (a finger must rest on the node first) the node follows it until release.
+* Camera controls are switched off for the gesture and restored when it ends, so a press that stays
+* a click behaves as before. Escape, a cancelled pointer or lost pointer capture put the node back.
+*/
+var NodeDragController = class {
+	host;
+	holdMs;
+	enabled = false;
+	gesture = null;
+	unlisten;
+	unlistenKeys = null;
+	constructor(host, holdMs = 350) {
+		this.host = host;
+		this.holdMs = holdMs;
+		this.unlisten = [
+			listen(host.element, "pointerdown", this.handleDown, { capture: true }),
+			listen(host.element, "pointermove", this.handleMove),
+			listen(host.element, "pointerup", this.handleUp),
+			listen(host.element, "pointercancel", this.handleCancel),
+			listen(host.element, "lostpointercapture", this.handleCancel)
+		];
+	}
+	/** True from the first drag step until the node is dropped or the drag is cancelled. */
+	get active() {
+		return this.gesture?.phase === "dragging";
+	}
+	setEnabled(enabled) {
+		if (!enabled) this.cancel({ restore: true });
+		this.enabled = enabled;
+	}
+	/** Ends a running gesture as cancelled. `restore` puts the node back where it was grabbed. */
+	cancel({ restore }) {
+		const gesture = this.gesture;
+		if (!gesture) return;
+		if (gesture.phase === "dragging") {
+			const restored = restore && this.host.nodePosition(gesture.nodeId) !== null;
+			if (restored) this.host.moveNode(gesture.nodeId, gesture.origin);
+			this.finish(gesture);
+			this.host.emit({
+				nodeId: gesture.nodeId,
+				phase: "cancel",
+				position: restored ? gesture.origin : gesture.last
+			});
+			return;
+		}
+		this.finish(gesture);
+	}
+	dispose() {
+		this.cancel({ restore: false });
+		this.enabled = false;
+		for (const stop of this.unlisten) stop();
+	}
+	handleDown = (event) => {
+		if (!this.enabled || this.gesture || event.button !== 0 || !this.host.canStart()) return;
+		const nodeId = this.host.pickNode(event.clientX, event.clientY);
+		if (nodeId === null) return;
+		const origin = this.host.nodePosition(nodeId);
+		if (!origin) return;
+		const surface = this.host.createSurface(origin);
+		const grabbed = surface?.(event.clientX, event.clientY);
+		if (!surface || !grabbed) return;
+		const touch = event.pointerType === "touch";
+		const gesture = {
+			controlsHeld: false,
+			holdTimer: null,
+			last: origin,
+			nodeId,
+			offset: {
+				x: origin.x - grabbed.x,
+				y: origin.y - grabbed.y,
+				z: (origin.z ?? 0) - (grabbed.z ?? 0)
+			},
+			origin,
+			phase: "pressed",
+			pointerId: event.pointerId,
+			startX: event.clientX,
+			startY: event.clientY,
+			surface,
+			touch
+		};
+		this.gesture = gesture;
+		this.unlistenKeys = listen(this.host.document, "keydown", this.handleKey);
+		if (touch) {
+			gesture.holdTimer = setTimeout(() => this.beginDrag(gesture), this.holdMs);
+			return;
+		}
+		this.holdControls(gesture);
+		capture(this.host.element, event.pointerId);
+	};
+	handleMove = (event) => {
+		const gesture = this.gesture;
+		if (!gesture || event.pointerId !== gesture.pointerId) return;
+		if (gesture.phase === "pressed") {
+			if (Math.hypot(event.clientX - gesture.startX, event.clientY - gesture.startY) <= 5) return;
+			if (gesture.touch) {
+				this.finish(gesture);
+				return;
+			}
+			this.beginDrag(gesture);
+		}
+		this.follow(gesture, event.clientX, event.clientY);
+	};
+	handleUp = (event) => {
+		const gesture = this.gesture;
+		if (!gesture || event.pointerId !== gesture.pointerId) return;
+		this.finish(gesture);
+		if (gesture.phase === "dragging") this.host.emit({
+			nodeId: gesture.nodeId,
+			phase: "end",
+			position: gesture.last
+		});
+	};
+	handleCancel = (event) => {
+		if (this.gesture && event.pointerId === this.gesture.pointerId) this.cancel({ restore: true });
+	};
+	handleKey = (event) => {
+		if (event.key === "Escape") this.cancel({ restore: true });
+	};
+	beginDrag(gesture) {
+		if (this.gesture !== gesture || gesture.phase === "dragging") return;
+		gesture.phase = "dragging";
+		clearHold(gesture);
+		this.holdControls(gesture);
+		if (gesture.touch) capture(this.host.element, gesture.pointerId);
+		this.host.emit({
+			nodeId: gesture.nodeId,
+			phase: "start",
+			position: gesture.origin
+		});
+	}
+	follow(gesture, clientX, clientY) {
+		if (!this.host.nodePosition(gesture.nodeId)) {
+			this.cancel({ restore: false });
+			return;
+		}
+		const point = gesture.surface(clientX, clientY);
+		if (!point) return;
+		const z = point.z === void 0 ? gesture.origin.z : point.z + gesture.offset.z;
+		const position = {
+			x: point.x + gesture.offset.x,
+			y: point.y + gesture.offset.y,
+			...z === void 0 ? {} : { z }
+		};
+		gesture.last = position;
+		this.host.moveNode(gesture.nodeId, position);
+		this.host.emit({
+			nodeId: gesture.nodeId,
+			phase: "move",
+			position
+		});
+	}
+	holdControls(gesture) {
+		if (gesture.controlsHeld) return;
+		gesture.controlsHeld = true;
+		this.host.setControlsEnabled(false);
+	}
+	/** Drops the gesture and everything it held: timer, pointer capture, key listener, camera controls. */
+	finish(gesture) {
+		if (this.gesture !== gesture) return;
+		this.gesture = null;
+		clearHold(gesture);
+		this.unlistenKeys?.();
+		this.unlistenKeys = null;
+		release(this.host.element, gesture.pointerId);
+		if (gesture.controlsHeld) this.host.setControlsEnabled(true);
+	}
+};
+/** Typed `addEventListener` for the pointer and key events this module handles; returns the unsubscribe. */
+function listen(target, type, handler, options) {
+	const listener = handler;
+	target.addEventListener(type, listener, options);
+	return () => target.removeEventListener(type, listener, options);
+}
+function clearHold(gesture) {
+	if (gesture.holdTimer === null) return;
+	clearTimeout(gesture.holdTimer);
+	gesture.holdTimer = null;
+}
+function capture(element, pointerId) {
+	try {
+		element.setPointerCapture(pointerId);
+	} catch {}
+}
+function release(element, pointerId) {
+	try {
+		element.releasePointerCapture(pointerId);
+	} catch {}
+}
+//#endregion
+//#region src/node-drag-surface.ts
+/**
+* Where the pointer is in world space on the plane a dragged node moves in. 2D unprojects onto the
+* view plane and reports no depth. 3D intersects the pointer ray with a plane through the anchor
+* that faces the camera as it was at the press, so the node keeps its depth and follows the pointer
+* across the screen. Returns `null` for an empty canvas, and from the surface when the ray misses.
+*/
+function createNodeDragSurface({ anchor, bounds, camera, raycaster }) {
+	const initial = bounds();
+	if (initial.width === 0 || initial.height === 0) return null;
+	const ndc = new Vector2();
+	const toNdc = (clientX, clientY) => {
+		const { height, left, top, width } = bounds();
+		return ndc.set((clientX - left) / width * 2 - 1, -((clientY - top) / height) * 2 + 1);
+	};
+	if (camera.type === "OrthographicCamera") return (clientX, clientY) => {
+		const point = toNdc(clientX, clientY);
+		const world = new Vector3(point.x, point.y, 0).unproject(camera);
+		return {
+			x: world.x,
+			y: world.y
+		};
+	};
+	const plane = new Plane().setFromNormalAndCoplanarPoint(camera.getWorldDirection(new Vector3()), new Vector3(anchor.x, anchor.y, anchor.z ?? 0));
+	const hit = new Vector3();
+	return (clientX, clientY) => {
+		raycaster.setFromCamera(toNdc(clientX, clientY), camera);
+		return raycaster.ray.intersectPlane(plane, hit) ? {
+			x: hit.x,
+			y: hit.y,
+			z: hit.z
+		} : null;
+	};
+}
 const vertexShader$1 = `
 attribute float instanceGlowOpacity;
 varying vec3 glowColor;
@@ -2756,6 +3522,8 @@ function prefersReducedMotion() {
 function disposeMaterial(material) {
 	for (const item of Array.isArray(material) ? material : [material]) item.dispose();
 }
+/** One warning per page when a context cannot run depth of field; diagnostics report it per instance. */
+let warnedDepthOfFieldUnsupported = false;
 /** Canvas input that cancels a running `flyTo`, so people take over the camera at once. */
 const FLIGHT_CANCEL_EVENTS = [
 	"keydown",
@@ -2836,12 +3604,23 @@ var Graphraum = class {
 	/** True only during the orbit's own `controls.update(dt)`; see `handleViewChange`. */
 	orbitUpdating = false;
 	destroyed = false;
+	canvasWidth = 0;
+	canvasHeight = 0;
 	cpuFrameMilliseconds = 0;
 	gpuFrameMilliseconds = null;
 	gpuTimer = null;
 	viewListeners = /* @__PURE__ */ new Set();
 	focusListeners = /* @__PURE__ */ new Set();
+	nodeDragListeners = /* @__PURE__ */ new Set();
+	nodeDrag;
 	lastHoveredNodeId = null;
+	antialias;
+	depthOfField = DEPTH_OF_FIELD_DEFAULTS;
+	depthOfFieldFocus = new DepthOfFieldFocus();
+	/** Strength actually applied: fades toward `strength` while enabled and toward 0 when disabled. */
+	depthOfFieldStrength = new Tween(0);
+	depthOfFieldPass = null;
+	depthOfFieldStatus = "off";
 	constructor(container, options = {}) {
 		this.container = container;
 		this.mode = options.mode ?? "2d";
@@ -2854,8 +3633,13 @@ var Graphraum = class {
 		if (!Number.isSafeInteger(this.maxVisibleNodes) || this.maxVisibleNodes < 1) throw new Error("Maximum visible nodes must be a positive integer.");
 		if (!Number.isFinite(this.viewportOverscan) || this.viewportOverscan < 0) throw new Error("Viewport overscan must be a non-negative finite number.");
 		this.theme = resolveGraphraumTheme(options.theme);
+		if (options.depthOfField !== void 0) {
+			this.depthOfField = resolveDepthOfFieldOptions(options.depthOfField);
+			this.depthOfFieldStrength.retarget(this.depthOfFieldTargetStrength(), 0, resolveEasing("linear"));
+		}
+		this.antialias = options.antialias ?? false;
 		this.renderer = new WebGLRenderer({
-			antialias: options.antialias ?? false,
+			antialias: this.antialias,
 			alpha: true
 		});
 		this.applyBackground();
@@ -2876,6 +3660,7 @@ var Graphraum = class {
 		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.nodeDrag = new NodeDragController(this.createNodeDragHost());
 		this.camera = this.createCamera();
 		this.controls = this.createControls();
 		this.resizeObserver = new ResizeObserver(() => this.resize());
@@ -3029,6 +3814,7 @@ var Graphraum = class {
 		this.requestRender();
 	}
 	replaceData(data, fitView) {
+		this.nodeDrag.cancel({ restore: false });
 		const compiled = compileGraph(data, this.visuals);
 		this.disposeGraphObjects();
 		this.data = {
@@ -3312,6 +4098,10 @@ var Graphraum = class {
 		const changedNodeIds = new Set([...currentSelection, ...nextSelection].filter((nodeId) => currentSelection.has(nodeId) !== nextSelection.has(nodeId)));
 		if (changedNodeIds.size === 0) return;
 		this.setNodeStateIds(state, nextSelection);
+		if (state === "selected" && this.depthOfField.enabled) {
+			const { durationMs, easing } = this.depthOfField.transition;
+			this.depthOfFieldFocus.retarget(durationMs, resolveEasing(easing));
+		}
 		this.applySelectionColors(changedNodeIds);
 		this.requestRender();
 		if (state === "selected" || state === "hovered") this.notifyFocusChange();
@@ -3342,6 +4132,7 @@ var Graphraum = class {
 	setMode(mode) {
 		if (mode === this.mode) return;
 		this.cancelFlight();
+		this.nodeDrag.cancel({ restore: true });
 		this.stopAutoOrbit();
 		this.mode = mode;
 		this.controls.removeEventListener("change", this.handleViewChange);
@@ -3376,6 +4167,33 @@ var Graphraum = class {
 		if (this.autoOrbit && this.autoOrbit.status !== "off") this.autoOrbit.setResumeAfterMs(resumeAfterMs);
 		else this.autoOrbit = new AutoOrbitLoop(this.renderer.domElement, this.controls, resumeAfterMs, this.stepAutoOrbit);
 	}
+	/**
+	* Updates 3D depth of field; omitted fields keep their current values. Enabling, disabling and a
+	* new `strength` fade the blur over `transition` unless `update.animate` is `false`; a change
+	* during a fade continues from the blur shown last. With `focus: "selection"` the focal plane
+	* follows the mean position of the selected nodes, re-measured from the camera every frame, and
+	* moves over `transition` when the selection changes; with nothing selected the blur fades out.
+	* `prefers-reduced-motion: reduce` jumps. Resolves `true` when the blur reaches the new strength
+	* and `false` when a later call or `destroy()` interrupts the fade. While it blurs each frame adds
+	* three draw calls; disabled, or with nothing to blur, it costs nothing. A no-op in 2D. Picking
+	* and DOM overlays are unaffected. Throws for invalid values.
+	*/
+	setDepthOfField(options, update = {}) {
+		const animate = update.animate ?? true;
+		if (typeof animate !== "boolean") throw new Error(`setDepthOfField option animate must be a boolean; received ${String(animate)}.`);
+		const previous = this.depthOfField;
+		this.depthOfField = resolveDepthOfFieldOptions(options, previous);
+		if (this.destroyed) return Promise.resolve(false);
+		const { durationMs, easing } = this.depthOfField.transition;
+		if (this.depthOfField.enabled && !previous.enabled) this.depthOfFieldFocus.retarget(0, resolveEasing(easing));
+		const fadeMs = animate && !prefersReducedMotion() ? durationMs : 0;
+		const done = this.depthOfFieldStrength.retarget(this.depthOfFieldTargetStrength(), fadeMs, resolveEasing(easing));
+		this.requestRender();
+		return done;
+	}
+	depthOfFieldTargetStrength() {
+		return this.depthOfField.enabled ? this.depthOfField.strength : 0;
+	}
 	getNodePresentation(nodeId) {
 		return this.nodePresentations.get(nodeId) ?? null;
 	}
@@ -3442,6 +4260,51 @@ var Graphraum = class {
 		listener();
 		return () => this.viewListeners.delete(listener);
 	}
+	/**
+	* Turns node dragging on or off (default off). A drag starts when the pointer moves past a small
+	* tolerance after a press on a node (a finger must rest on the node first, so a swipe still pans
+	* the camera), moves the node on a plane facing the camera, and ends on release. Escape or a
+	* cancelled pointer put the node back. Not available while the density LOD shows clusters.
+	*/
+	setNodeDrag(options) {
+		if (typeof options?.enabled !== "boolean") throw new Error("setNodeDrag option enabled must be a boolean.");
+		this.nodeDrag.setEnabled(options.enabled);
+	}
+	/** Subscribes to node drag steps (`start`, `move`, `end`, `cancel`). Returns an unsubscribe function. */
+	onNodeDrag(listener) {
+		this.nodeDragListeners.add(listener);
+		return () => this.nodeDragListeners.delete(listener);
+	}
+	createNodeDragHost() {
+		const element = this.renderer.domElement;
+		return {
+			canStart: () => !this.destroyed && this.nodeMesh !== null && !this.densityLodActive,
+			createSurface: (anchor) => createNodeDragSurface({
+				anchor,
+				bounds: () => element.getBoundingClientRect(),
+				camera: this.camera,
+				raycaster: this.raycaster
+			}),
+			document: element.ownerDocument,
+			element,
+			emit: (event) => {
+				for (const listener of this.nodeDragListeners) listener(event);
+			},
+			moveNode: (nodeId, position) => this.updateNodes([{
+				id: nodeId,
+				position
+			}]),
+			nodePosition: (nodeId) => {
+				const index = this.nodeIndices.get(nodeId);
+				const node = index === void 0 ? void 0 : this.data.nodes[index];
+				return node ? { ...node.position } : null;
+			},
+			pickNode: (clientX, clientY) => this.pickNode(clientX, clientY),
+			setControlsEnabled: (enabled) => {
+				this.controls.enabled = enabled;
+			}
+		};
+	}
 	/** Subscribes to selection and hover changes that affect overlay focus chrome. */
 	onFocusChange(listener) {
 		this.focusListeners.add(listener);
@@ -3452,6 +4315,7 @@ var Graphraum = class {
 		for (const listener of this.focusListeners) listener();
 	}
 	handlePointerMove = (event) => {
+		if (this.nodeDrag.active) return;
 		const nodeId = this.pickNode(event.clientX, event.clientY);
 		if (nodeId === this.lastHoveredNodeId) return;
 		this.lastHoveredNodeId = nodeId;
@@ -3470,6 +4334,7 @@ var Graphraum = class {
 			aggregatedNodeClusters: this.densityLodActive ? this.visibleNodeCount : 0,
 			autoOrbit: this.autoOrbit?.status ?? "off",
 			cpuFrameMilliseconds: this.cpuFrameMilliseconds,
+			depthOfField: this.depthOfFieldStatus,
 			gpuFrameMilliseconds: this.gpuFrameMilliseconds,
 			gpuDrawCalls: this.renderer.info.render.calls,
 			gpuGeometries: this.renderer.info.memory.geometries,
@@ -3578,6 +4443,71 @@ var Graphraum = class {
 			this.requestRender();
 		});
 	}
+	/**
+	* The camera pose as plain JSON. 2D reports the centre and the world height the canvas shows; 3D
+	* reports the camera position and the point it orbits. Pass it to `setCameraState()` to return
+	* to the same view, for example after reloading a saved one.
+	*/
+	getCameraState() {
+		const camera = this.camera;
+		if (camera instanceof OrthographicCamera) return {
+			center: {
+				x: camera.position.x,
+				y: camera.position.y
+			},
+			mode: "2d",
+			visibleHeight: (camera.top - camera.bottom) / camera.zoom
+		};
+		const { target } = this.controls;
+		return {
+			mode: "3d",
+			position: {
+				x: camera.position.x,
+				y: camera.position.y,
+				z: camera.position.z
+			},
+			target: {
+				x: target.x,
+				y: target.y,
+				z: target.z
+			}
+		};
+	}
+	/**
+	* Puts the camera on a pose from `getCameraState()` at once, without fitting or animating, and
+	* cancels a running `flyTo`. Throws for a state of the other mode (switch with `setMode()` first)
+	* or with a non-finite number. 2D keeps the saved height and takes the width from the canvas, so a
+	* view saved on one canvas size fits another. 3D derives the clip planes from the pose so the whole
+	* graph stays in view. Apply it after the canvas has its size: a 2D resize to a new size refits.
+	*/
+	setCameraState(state) {
+		const next = validateCameraState(state, this.mode);
+		this.cancelFlight();
+		const camera = this.camera;
+		const width = Math.max(this.container.clientWidth, 1);
+		const height = Math.max(this.container.clientHeight, 1);
+		if (next.mode === "2d" && camera instanceof OrthographicCamera) {
+			setOrthographicFrustum(camera, width / height, next.visibleHeight);
+			camera.position.set(next.center.x, next.center.y, camera.position.z);
+			this.controls.target.set(next.center.x, next.center.y, this.controls.target.z);
+			camera.lookAt(this.controls.target);
+			camera.updateProjectionMatrix();
+			this.controls.update();
+			this.materializeViewport();
+		} else if (next.mode === "3d" && camera instanceof PerspectiveCamera) {
+			const target = new Vector3(next.target.x, next.target.y, next.target.z);
+			camera.position.set(next.position.x, next.position.y, next.position.z);
+			this.controls.target.copy(target);
+			camera.lookAt(target);
+			applyPerspectiveContainerAspect(camera, width, height);
+			const clip = perspectiveClipRange(camera.position.distanceTo(target), this.graphRadiusAround(target));
+			camera.near = clip.near;
+			camera.far = clip.far;
+			camera.updateProjectionMatrix();
+			this.controls.update();
+		}
+		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;
@@ -3725,11 +4655,14 @@ var Graphraum = class {
 	resize() {
 		const width = Math.max(this.container.clientWidth, 1);
 		const height = Math.max(this.container.clientHeight, 1);
+		const sizeChanged = this.canvasWidth !== width || this.canvasHeight !== height;
+		this.canvasWidth = width;
+		this.canvasHeight = height;
 		this.renderer.setSize(width, height, false);
 		if (this.camera instanceof PerspectiveCamera) {
 			applyPerspectiveContainerAspect(this.camera, width, height);
 			this.camera.updateProjectionMatrix();
-		} else if (this.camera instanceof OrthographicCamera) {
+		} else if (this.camera instanceof OrthographicCamera && sizeChanged) {
 			this.fitView();
 			return;
 		}
@@ -3739,6 +4672,7 @@ var Graphraum = class {
 	destroy() {
 		this.destroyed = true;
 		this.cancelFlight();
+		this.nodeDrag.dispose();
 		this.stopAutoOrbit();
 		this.resizeObserver.disconnect();
 		this.renderer.domElement.removeEventListener("pointermove", this.handlePointerMove);
@@ -3749,6 +4683,8 @@ var Graphraum = class {
 		if (this.frameRequest !== null) cancelAnimationFrame(this.frameRequest);
 		if (this.gpuTimer) for (const query of this.gpuTimer.pending) this.gpuTimer.context.deleteQuery(query);
 		this.disposeBackgroundTexture();
+		this.depthOfFieldStrength.cancel();
+		this.disposeDepthOfFieldPass();
 		this.disposeGraphObjects();
 		this.renderer.dispose();
 		this.renderer.domElement.remove();
@@ -3774,7 +4710,16 @@ var Graphraum = class {
 		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);
+		const depthOfField = this.prepareDepthOfField(startedAt);
+		if (depthOfField && this.depthOfFieldPass && this.camera instanceof PerspectiveCamera) {
+			this.renderer.info.autoReset = false;
+			this.renderer.info.reset();
+			try {
+				this.depthOfFieldPass.render(this.renderer, this.scene, this.camera, this.edgeMesh, depthOfField);
+			} finally {
+				this.renderer.info.autoReset = true;
+			}
+		} else this.renderer.render(this.scene, this.camera);
 		this.cpuFrameMilliseconds = performance.now() - startedAt;
 		if (timer && query) {
 			timer.context.endQuery(timer.extension.TIME_ELAPSED_EXT);
@@ -3782,6 +4727,81 @@ var Graphraum = class {
 		}
 		for (const listener of this.viewListeners) listener();
 	}
+	/**
+	* Decides whether this frame blurs and records why in the diagnostics status. Returns null to
+	* render directly. Requests another frame while a fade or focus move runs; both end on their own.
+	*/
+	prepareDepthOfField(nowMs) {
+		const options = this.depthOfField;
+		const strengthTween = this.depthOfFieldStrength;
+		if (!options.enabled && strengthTween.settled) {
+			this.depthOfFieldStatus = "off";
+			this.disposeDepthOfFieldPass();
+			return null;
+		}
+		if (!(this.camera instanceof PerspectiveCamera)) {
+			strengthTween.jump();
+			this.depthOfFieldStatus = options.enabled ? "inactive" : "off";
+			this.disposeDepthOfFieldPass();
+			return null;
+		}
+		if (!DepthOfFieldPass.isSupported(this.renderer)) {
+			strengthTween.jump();
+			this.depthOfFieldStatus = options.enabled ? "unsupported" : "off";
+			if (options.enabled && !warnedDepthOfFieldUnsupported) {
+				warnedDepthOfFieldUnsupported = true;
+				console.warn("graphraum: depth of field needs a WebGL 2 context and is turned off for this canvas. getDiagnostics().depthOfField reports \"unsupported\".");
+			}
+			return null;
+		}
+		const strength = strengthTween.sample(nowMs);
+		if (!strengthTween.settled) this.requestRender();
+		this.camera.updateMatrixWorld();
+		let focusDistance = typeof options.focus === "number" ? options.focus : null;
+		let amount = 1;
+		if (options.focus === "selection") {
+			const focus = this.depthOfFieldFocus.evaluate(nowMs, this.selectionFocusPoint(), prefersReducedMotion());
+			if (!focus.settled) this.requestRender();
+			amount = focus.amount;
+			if (focus.point) focusDistance = viewDistance(focus.point, this.camera.matrixWorldInverse.elements);
+		}
+		if (focusDistance === null) {
+			this.depthOfFieldStatus = options.enabled ? "inactive" : "off";
+			return null;
+		}
+		focusDistance = Math.max(focusDistance, this.camera.near);
+		const pixelRatio = this.renderer.getPixelRatio();
+		const aperturePixels = strength * amount * distanceFade(focusDistance, options.nearDistance, options.farDistance) * 24 * pixelRatio;
+		const maxBlurPixels = options.maxBlur * pixelRatio;
+		if (aperturePixels < .25 || maxBlurPixels < .25) {
+			this.depthOfFieldStatus = options.enabled ? "inactive" : "off";
+			return null;
+		}
+		this.depthOfFieldPass ??= new DepthOfFieldPass(this.antialias);
+		this.depthOfFieldStatus = "active";
+		return {
+			aperturePixels,
+			focusDistance,
+			maxBlurPixels,
+			minBlurPixels: options.minBlur * pixelRatio
+		};
+	}
+	/** Mean world position of the selected nodes, read every frame so a running layout keeps them in focus. */
+	selectionFocusPoint() {
+		return meanPoint([...this.selectedNodeIds].flatMap((id) => {
+			const index = this.nodeIndices.get(id);
+			const node = index === void 0 ? void 0 : this.data.nodes[index];
+			return node ? [{
+				x: node.position.x,
+				y: node.position.y,
+				z: node.position.z ?? 0
+			}] : [];
+		}));
+	}
+	disposeDepthOfFieldPass() {
+		this.depthOfFieldPass?.dispose();
+		this.depthOfFieldPass = null;
+	}
 	stopAutoOrbit() {
 		this.autoOrbit?.dispose();
 		this.autoOrbit = null;
@@ -3797,6 +4817,7 @@ var Graphraum = class {
 	* without a loop.
 	*/
 	stepAutoOrbit = (deltaSeconds) => {
+		if (this.nodeDrag.active) return;
 		try {
 			this.controls.autoRotate = true;
 			this.orbitUpdating = true;