@yggy-tech/graphraum 0.34.1 → 0.36.0

package/dist/index.d.ts

@@ -72,6 +72,40 @@ interface GraphraumData<NodeAttributes = undefined, EdgeAttributes = undefined>
   nodes: readonly GraphraumNode<NodeAttributes>[];
   edges: readonly GraphraumEdge<EdgeAttributes>[];
 }
+interface GraphraumSetDataOptions {
+  /**
+   * Fit the camera to the new data (default `true`). `false` replaces the data and leaves the camera
+   * where it is, for hosts that pass a full snapshot on every change. On a graph that never had a
+   * fit the camera keeps its initial pose, so call `fitView()` once after the first data.
+   */
+  fit?: boolean;
+}
+interface GraphraumCameraPoint3d {
+  x: number;
+  y: number;
+  z: number;
+}
+/**
+ * A 2D view: where the camera looks and how much of the world it shows from top to bottom. The
+ * visible width follows the canvas aspect, so a state read on one canvas size fits another.
+ */
+interface GraphraumCameraState2d {
+  center: {
+    x: number;
+    y: number;
+  };
+  mode: "2d";
+  /** World units from the top to the bottom edge of the canvas, with the current zoom applied. */
+  visibleHeight: number;
+}
+/** A 3D view: the camera position and the point it orbits and looks at. */
+interface GraphraumCameraState3d {
+  mode: "3d";
+  position: GraphraumCameraPoint3d;
+  target: GraphraumCameraPoint3d;
+}
+/** The camera pose as plain JSON, for saving a view and restoring it with `setCameraState()`. */
+type GraphraumCameraState = GraphraumCameraState2d | GraphraumCameraState3d;
 interface GraphraumDataPatch<NodeAttributes = undefined, EdgeAttributes = undefined> {
   addedNodes?: readonly GraphraumNode<NodeAttributes>[];
   addedEdges?: readonly GraphraumEdge<EdgeAttributes>[];
@@ -232,8 +266,60 @@ type GraphraumPickHit = {
   kind: "node";
   id: string;
 };
+/** `linear`, cubic `easeIn` / `easeOut` / `easeInOut`, or a function from progress 0..1 to eased 0..1. */
+type GraphraumEasing = "easeIn" | "easeInOut" | "easeOut" | "linear" | ((t: number) => number);
+/** How depth of field animates focus moves and blur fades. */
+interface GraphraumDepthOfFieldTransition {
+  /** Default 400; 0 jumps. `prefers-reduced-motion: reduce` always jumps. */
+  durationMs?: number;
+  /** Default `"easeInOut"`. */
+  easing?: GraphraumEasing;
+}
+/**
+ * Opt-in 3D depth of field. The focal plane follows the selection, so selected nodes stay sharp and
+ * the rest of the graph blurs with its distance from them, in front and behind, like a thin lens:
+ * the closer the camera is to the focus, the shallower the depth of field. A no-op in 2D. See
+ * `Graphraum.setDepthOfField`.
+ */
+interface GraphraumDepthOfFieldOptions {
+  /** Default `false`. While disabled no extra passes or render targets exist. Toggling fades the blur. */
+  enabled?: boolean;
+  /**
+   * `"selection"` (default) focuses the mean position of the selected nodes and fades the blur out
+   * when nothing is selected. A number fixes the focal plane at that camera distance in world units.
+   */
+  focus?: "selection" | number;
+  /**
+   * Aperture, 0..1, default 0.5. A surface blurs by `strength * 24 * |d - f| / d` CSS pixels, where
+   * `d` is its camera distance and `f` the focal distance, clamped to `maxBlur`.
+   */
+  strength?: number;
+  /** Largest blur radius in CSS pixels. Default 12. */
+  maxBlur?: number;
+  /** Blur radii below this many CSS pixels render sharp, which widens the in-focus band. Default 0. */
+  minBlur?: number;
+  /** Camera-to-focus distance in world units up to which `strength` applies fully. Default 0. */
+  nearDistance?: number;
+  /** Camera-to-focus distance in world units at which the blur has faded out. Default `Infinity` (no fade). */
+  farDistance?: number;
+  /** Animation for focus moves between selections and for blur fades. */
+  transition?: GraphraumDepthOfFieldTransition;
+}
+/** Options for one `Graphraum.setDepthOfField` call. */
+interface GraphraumDepthOfFieldUpdate {
+  /** Default `true`: fade the blur to the new strength over the transition. `false` jumps. */
+  animate?: boolean;
+}
+/**
+ * `off`: disabled. `inactive`: enabled with nothing to blur (2D mode, or no selection with
+ * `focus: "selection"`), so frames render directly. `active`: the last frame ran the blur passes.
+ * `unsupported`: enabled, but the WebGL context cannot run it, so frames render directly.
+ */
+type GraphraumDepthOfFieldStatus = "active" | "inactive" | "off" | "unsupported";
 interface GraphraumOptions<NodeAttributes = undefined, EdgeAttributes = undefined> {
   antialias?: boolean;
+  /** Opt-in 3D depth of field; off by default. Change it later with `setDepthOfField`. */
+  depthOfField?: GraphraumDepthOfFieldOptions;
   maxVisibleEdges?: number;
   maxVisibleNodes?: number;
   maxPixelRatio?: number;
@@ -266,6 +352,7 @@ interface GraphraumDiagnostics {
   aggregatedNodeClusters: number;
   autoOrbit: GraphraumAutoOrbitStatus;
   cpuFrameMilliseconds: number;
+  depthOfField: GraphraumDepthOfFieldStatus;
   gpuFrameMilliseconds: number | null;
   gpuDrawCalls: number;
   gpuGeometries: number;
@@ -524,14 +611,24 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   /** True only during the orbit's own `controls.update(dt)`; see `handleViewChange`. */
   private orbitUpdating;
   private destroyed;
+  private canvasWidth;
+  private canvasHeight;
   private cpuFrameMilliseconds;
   private gpuFrameMilliseconds;
   private gpuTimer;
   private readonly viewListeners;
   private readonly focusListeners;
   private lastHoveredNodeId;
+  private readonly antialias;
+  private depthOfField;
+  private readonly depthOfFieldFocus;
+  /** Strength actually applied: fades toward `strength` while enabled and toward 0 when disabled. */
+  private readonly depthOfFieldStrength;
+  private depthOfFieldPass;
+  private depthOfFieldStatus;
   constructor(container: HTMLElement, options?: GraphraumOptions<NodeAttributes, EdgeAttributes>);
-  setData(data: GraphraumData<NodeAttributes, EdgeAttributes>): void;
+  /** Replaces the whole graph. Fits the camera unless `options.fit` is `false`. */
+  setData(data: GraphraumData<NodeAttributes, EdgeAttributes>, options?: GraphraumSetDataOptions): void;
   /** Merge a topology patch without fitting or resetting the current camera. */
   applyDataPatch(patch: GraphraumDataPatch<NodeAttributes, EdgeAttributes>): void;
   private canAppendDataPatch;
@@ -587,6 +684,19 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
    * before enabling it. Throws in 2D mode; `setMode("2d")` turns it off. Does nothing after `destroy()`.
    */
   setAutoOrbit(options: GraphraumAutoOrbitOptions | false): void;
+  /**
+   * 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: GraphraumDepthOfFieldOptions, update?: GraphraumDepthOfFieldUpdate): Promise<boolean>;
+  private depthOfFieldTargetStrength;
   getNodePresentation(nodeId: string): CompiledGraphraumPresentation | null;
   /** Returns canvas-relative screen coordinates for a node, or null when the node does not exist. */
   getNodeScreenPosition(nodeId: string): GraphraumScreenPosition | null;
@@ -635,6 +745,20 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
    * reduce` or a zero duration it jumps. Throws for an invalid duration or distance scale.
    */
   flyTo(options: GraphraumFlyToOptions): Promise<boolean>;
+  /**
+   * 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(): GraphraumCameraState;
+  /**
+   * 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: GraphraumCameraState): void;
   /** Nodes whose id is in `nodeIds`, in graph order; every node when `nodeIds` is omitted. */
   private nodesWithIds;
   /** The closest front-view camera that frames `nodes` (issue #124); applies the container aspect. */
@@ -664,6 +788,14 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   /** Renders a pending frame now instead of on the next animation frame. */
   private flushRender;
   private renderFrame;
+  /**
+   * 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.
+   */
+  private prepareDepthOfField;
+  /** Mean world position of the selected nodes, read every frame so a running layout keeps them in focus. */
+  private selectionFocusPoint;
+  private disposeDepthOfFieldPass;
   private stopAutoOrbit;
   /**
    * One orbit frame. `autoRotate` is on only for this `update(dt)` call: OrbitControls also calls
@@ -851,4 +983,4 @@ declare function isTransparentGraphraumBackground(background: GraphraumBackgroun
 /** Defines typed, serializable graph visuals without coupling application data to the render loop. */
 declare function defineVisuals<NodeAttributes = undefined, EdgeAttributes = undefined>(visuals: GraphraumVisualMapper<NodeAttributes, EdgeAttributes>): GraphraumVisualMapper<NodeAttributes, EdgeAttributes>;
 //#endregion
-export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDiagnostics, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };
+export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumCameraPoint3d, type GraphraumCameraState, type GraphraumCameraState2d, type GraphraumCameraState3d, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDepthOfFieldOptions, type GraphraumDepthOfFieldStatus, type GraphraumDepthOfFieldTransition, type GraphraumDepthOfFieldUpdate, type GraphraumDiagnostics, type GraphraumEasing, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumSetDataOptions, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };

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;
@@ -2756,6 +3297,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 +3379,21 @@ 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();
 	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 +3406,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();
@@ -2882,8 +3439,11 @@ var Graphraum = class {
 		this.resizeObserver.observe(container);
 		this.resize();
 	}
-	setData(data) {
-		this.replaceData(data, true);
+	/** Replaces the whole graph. Fits the camera unless `options.fit` is `false`. */
+	setData(data, options = {}) {
+		const { fit = true } = options;
+		if (typeof fit !== "boolean") throw new Error("setData option fit must be a boolean.");
+		this.replaceData(data, fit);
 	}
 	/** Merge a topology patch without fitting or resetting the current camera. */
 	applyDataPatch(patch) {
@@ -3309,6 +3869,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();
@@ -3373,6 +3937,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;
 	}
@@ -3467,6 +4058,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,
@@ -3575,6 +4167,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;
@@ -3722,11 +4379,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;
 		}
@@ -3746,6 +4406,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();
@@ -3771,7 +4433,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);
@@ -3779,6 +4450,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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yggy-tech/graphraum",
-	"version": "0.34.1",
+	"version": "0.36.0",
 	"description": "yggy's WebGL engine for interactive graphs in 2D and 3D",
 	"type": "module",
 	"license": "Apache-2.0",