diff --git a/.changeset/tidy-steaks-care.md b/.changeset/tidy-steaks-care.md
new file mode 100644
index 0000000000..9b332066cd
--- /dev/null
+++ b/.changeset/tidy-steaks-care.md
@@ -0,0 +1,5 @@
+---
+'@viamrobotics/visualization': minor
+---
+
+Add object snapping to build-mode moves: key points, surfaces, ground plane, and surface alignment.
diff --git a/src/lib/components/SelectedTransformControls.svelte b/src/lib/components/SelectedTransformControls.svelte
index 56f844e935..25652cf3d1 100644
--- a/src/lib/components/SelectedTransformControls.svelte
+++ b/src/lib/components/SelectedTransformControls.svelte
@@ -3,7 +3,6 @@
 
 	import { T, useThrelte } from '@threlte/core'
 	import { TransformControls } from '@threlte/extras'
-	import { onDestroy } from 'svelte'
 	import { Group, Matrix4, Vector3 } from 'three'
 
 	import {
@@ -13,6 +12,7 @@
 		resizeBoundsObstacle,
 	} from '$lib/boundsObstacleInterior'
 	import { complexShapeOwner } from '$lib/complexShapeOwner'
+	import SnapIndicator from '$lib/components/SnapIndicator.svelte'
 	import { relations, traits, useQuery, useTrait } from '$lib/ecs'
 	import { FrameEditor } from '$lib/editing/FrameEditor'
 	import { shapeOffsetFromGizmo, withObstacleShapePatch } from '$lib/editing/obstacleShapeGizmo'
@@ -33,6 +33,7 @@
 		simpleObstacleShape,
 		withSimpleObstacleShape,
 	} from '$lib/simpleObstacleShape'
+	import { useObjectSnapDrag } from '$lib/snapping/useObjectSnapDrag.svelte'
 	import { isolateTransformControls } from '$lib/three/renderLayers'
 
 	const { invalidate } = useThrelte()
@@ -46,7 +47,13 @@
 	const selected = useQuery(traits.Selected)
 
 	const mode = $derived(settings.current.transformMode)
-	const snaps = $derived(transformSnaps(settings.current))
+	const objectSnap = useObjectSnapDrag()
+	const snaps = $derived(
+		transformSnaps({
+			...settings.current,
+			snapping: settings.current.snapping !== objectSnap.isInverted,
+		})
+	)
 	const isBuildMode = $derived(environment.current.mode === 'build')
 	const entity = $derived(selected.current[0])
 	const editable = useTrait(() => entity, traits.Editable)
@@ -110,6 +117,8 @@
 		}
 
 		target.decompose(anchor.position, anchor.quaternion, anchor.scale)
+		// An aligned move stages a turn, which would otherwise tilt the gizmo mid-drag.
+		if (objectSnap.isDragging) anchor.quaternion.copy(objectSnap.startOrientation)
 		anchor.updateMatrixWorld()
 		invalidate()
 	})
@@ -124,6 +133,15 @@
 
 		return mode
 	})
+	/** The orientation a drag stages: the gizmo's own, or during a move, the snap's. */
+	const stagedOrientation = (gizmo: Group) =>
+		activeMode === 'translate' && objectSnap.isDragging ? objectSnap.orientation : gizmo.quaternion
+
+	const stagesPosition = $derived(activeMode === 'translate')
+	// Align-to-surface turns the object during a move, so a move writes orientation too.
+	const stagesOrientation = $derived(
+		activeMode === 'rotate' || (activeMode === 'translate' && objectSnap.hasTurned)
+	)
 	const isSphereScale = $derived(
 		activeMode === 'scale' && (sphere.current !== undefined || obstacleShape?.type === 'sphere')
 	)
@@ -164,6 +182,7 @@
 		| { type: 'capsule'; r: number; l: number }
 		| undefined
 	let frameHistoryEntryOpen = false
+	let isGizmoDragging = false
 	let controls = $state.raw<ThreeTransformControls>()
 
 	$effect(() => {
@@ -182,7 +201,29 @@
 		frameHistoryEntryOpen = false
 	}
 
-	onDestroy(endFrameHistoryEntry)
+	const releaseGizmo = () => {
+		if (!isGizmoDragging) return
+		isGizmoDragging = false
+		transformControls.setActive(false)
+	}
+
+	// The gizmo can unmount mid-drag, on a mode hotkey or the entity hiding, and then never sees
+	// the pointer up. Close the history entry and release the camera with it, or undo stays blocked
+	// behind the open entry and the camera stays parked.
+	$effect(() => {
+		if (!transforming || !entity) return
+		return () => {
+			endFrameHistoryEntry()
+			releaseGizmo()
+		}
+	})
+
+	// Same unmount, plus a switch out of translate mid-drag. End the snap drag with them, or the
+	// next drag starts from a stale one.
+	$effect(() => {
+		if (!transforming || activeMode !== 'translate' || !entity) return
+		return () => objectSnap.end()
+	})
 
 	const captureScaleStart = () => {
 		if (!entity || activeMode !== 'scale') {
@@ -244,31 +285,34 @@
 		const world = worldMatrix.current
 		if (!ref || !world) return
 
-		tempShapeWorld.compose(ref.position, ref.quaternion, UNIT_SCALE)
+		tempShapeWorld.compose(ref.position, stagedOrientation(ref), UNIT_SCALE)
 		const offset = shapeOffsetFromGizmo(world, tempShapeWorld)
 
-		if (activeMode === 'translate') {
-			patchComplexShape({ translation: { x: offset.x, y: offset.y, z: offset.z } })
-		} else {
-			patchComplexShape({
+		patchComplexShape({
+			...(stagesPosition && { translation: { x: offset.x, y: offset.y, z: offset.z } }),
+			...(stagesOrientation && {
 				orientation: {
 					type: 'ov_degrees',
 					value: { x: offset.oX, y: offset.oY, z: offset.oZ, th: offset.theta },
 				},
-			})
-		}
+			}),
+		})
 	}
 
 	const onMouseDown = () => {
 		captureScaleStart()
 		beginFrameHistoryEntry()
+		if (activeMode === 'translate' && entity && ref) objectSnap.begin(entity, ref)
 
+		isGizmoDragging = true
 		transformControls.setActive(true)
 	}
 
 	const onChange = () => {
 		if (!ref || !entity || !activeMode) return
 
+		if (activeMode === 'translate' && controls?.axis) objectSnap.apply(ref, controls.axis)
+
 		if (activeMode === 'translate' || activeMode === 'rotate') {
 			if (shapeOwner) {
 				stageComplexShapeTransform()
@@ -337,7 +381,8 @@
 
 	const onMouseUp = () => {
 		scaleStart = undefined
-		transformControls.setActive(false)
+		objectSnap.end()
+		releaseGizmo()
 		endFrameHistoryEntry()
 	}
 
@@ -355,7 +400,7 @@
 	const computeLocalDragTarget = (out: Matrix4) => {
 		if (!ref || !entity) return
 
-		out.makeRotationFromQuaternion(ref.quaternion)
+		out.makeRotationFromQuaternion(stagedOrientation(ref))
 		out.setPosition(ref.position)
 
 		const parentWorld = entity.targetFor(relations.ChildOf)?.get(traits.WorldMatrix)
@@ -383,20 +428,15 @@
 		const config = configMatrix.current
 
 		if (!live || !config) {
-			if (activeMode === 'translate') {
-				frameEditor.setPose(entity, {
-					x: refPose.x,
-					y: refPose.y,
-					z: refPose.z,
-				})
-			} else if (activeMode === 'rotate') {
-				frameEditor.setPose(entity, {
+			frameEditor.setPose(entity, {
+				...(stagesPosition && { x: refPose.x, y: refPose.y, z: refPose.z }),
+				...(stagesOrientation && {
 					oX: refPose.oX,
 					oY: refPose.oY,
 					oZ: refPose.oZ,
 					theta: refPose.theta,
-				})
-			}
+				}),
+			})
 			return
 		}
 
@@ -424,11 +464,12 @@
 		tempPose.setFromMatrix4(matrix)
 		refPose.setFromMatrix4(tempRefMatrix)
 
-		if (activeMode === 'translate') {
+		if (stagesPosition) {
 			tempPose.x = refPose.x
 			tempPose.y = refPose.y
 			tempPose.z = refPose.z
-		} else {
+		}
+		if (stagesOrientation) {
 			tempPose.oX = refPose.oX
 			tempPose.oY = refPose.oY
 			tempPose.oZ = refPose.oZ
@@ -461,4 +502,8 @@
 			onmouseUp={onMouseUp}
 		/>
 	{/key}
+
+	{#if objectSnap.indicator}
+		<SnapIndicator indicator={objectSnap.indicator} />
+	{/if}
 {/if}
diff --git a/src/lib/components/SnapIndicator.svelte b/src/lib/components/SnapIndicator.svelte
new file mode 100644
index 0000000000..871e664ed7
--- /dev/null
+++ b/src/lib/components/SnapIndicator.svelte
@@ -0,0 +1,60 @@
+<script lang="ts">
+	import { T } from '@threlte/core'
+	import { HTML, MeshLineGeometry, MeshLineMaterial } from '@threlte/extras'
+	import { Vector3 } from 'three'
+
+	import type { SnapIndicator } from '$lib/snapping/snapQuery'
+
+	interface Props {
+		indicator: SnapIndicator
+	}
+
+	const { indicator }: Props = $props()
+
+	// Long enough to read the surface's tilt at a glance, short enough to stay out of the way.
+	const NORMAL_LENGTH_M = 0.1
+
+	const normalLine = $derived(
+		indicator.kind === 'surface'
+			? [
+					indicator.point,
+					new Vector3().copy(indicator.point).addScaledVector(indicator.normal, NORMAL_LENGTH_M),
+				]
+			: undefined
+	)
+</script>
+
+<T.Group position={indicator.point.toArray()}>
+	<!-- `HTML` hands its own wrapper only `class` and `style`, so the decorative dot is a child that can carry `aria-hidden`. -->
+	<HTML
+		center
+		zIndexRange={[3, 0]}
+		class="pointer-events-none"
+	>
+		<span
+			aria-hidden="true"
+			class={[
+				'block h-3 w-3 rounded-full border-2 border-black/70',
+				indicator.kind === 'surface' && 'bg-black/70',
+			]}
+		></span>
+	</HTML>
+</T.Group>
+
+{#if normalLine}
+	<T.Mesh
+		raycast={() => null}
+		bvh={{ enabled: false }}
+		renderOrder={1}
+	>
+		<MeshLineGeometry points={normalLine} />
+		<MeshLineMaterial
+			width={2.5}
+			depthTest={false}
+			color="black"
+			opacity={0.7}
+			attenuate={false}
+			transparent
+		/>
+	</T.Mesh>
+{/if}
diff --git a/src/lib/hooks/__tests__/transformSnaps.spec.ts b/src/lib/hooks/__tests__/transformSnaps.spec.ts
index 6823f4ea93..af27a620eb 100644
--- a/src/lib/hooks/__tests__/transformSnaps.spec.ts
+++ b/src/lib/hooks/__tests__/transformSnaps.spec.ts
@@ -2,7 +2,13 @@ import { describe, expect, it } from 'vitest'
 
 import { transformSnaps } from '../transformSnaps'
 
-const snapSettings = { snapping: true, snapTranslate: 0.25, snapRotate: 90, snapScale: 0.1 }
+const snapSettings = {
+	snapping: true,
+	snapIncrement: true,
+	snapTranslate: 0.25,
+	snapRotate: 90,
+	snapScale: 0.1,
+}
 
 describe('transformSnaps', () => {
 	it('passes a move step through in the metres the gizmo snaps in', () => {
@@ -25,6 +31,14 @@ describe('transformSnaps', () => {
 		})
 	})
 
+	it('snaps nothing while increment snapping is off', () => {
+		expect(transformSnaps({ ...snapSettings, snapIncrement: false })).toEqual({
+			translation: null,
+			rotation: null,
+			scale: null,
+		})
+	})
+
 	it('leaves an axis free when its step is 0', () => {
 		expect(transformSnaps({ ...snapSettings, snapTranslate: 0 }).translation).toBeNull()
 	})
diff --git a/src/lib/hooks/transformSnaps.ts b/src/lib/hooks/transformSnaps.ts
index 1c9ab24a97..0fa34c98d3 100644
--- a/src/lib/hooks/transformSnaps.ts
+++ b/src/lib/hooks/transformSnaps.ts
@@ -10,14 +10,17 @@ export interface TransformSnaps {
 }
 
 /**
- * The snap steps to hand a Three.js transform gizmo. Snapping off, or a step of 0,
- * leaves that axis free.
+ * The snap steps to hand a Three.js transform gizmo. Snapping off, increment snapping off, or a
+ * step of 0 leaves that axis free.
  */
 export const transformSnaps = (
-	settings: Pick<Settings, 'snapping' | 'snapTranslate' | 'snapRotate' | 'snapScale'>
+	settings: Pick<
+		Settings,
+		'snapping' | 'snapIncrement' | 'snapTranslate' | 'snapRotate' | 'snapScale'
+	>
 ): TransformSnaps => {
 	const snap = (value: number, convert: (v: number) => number = (v) => v) =>
-		settings.snapping && value > 0 ? convert(value) : null
+		settings.snapping && settings.snapIncrement && value > 0 ? convert(value) : null
 
 	return {
 		translation: snap(settings.snapTranslate),
diff --git a/src/lib/hooks/useSettings.svelte.ts b/src/lib/hooks/useSettings.svelte.ts
index 9fa37015cf..9878c35a6e 100644
--- a/src/lib/hooks/useSettings.svelte.ts
+++ b/src/lib/hooks/useSettings.svelte.ts
@@ -29,7 +29,16 @@ export interface Settings {
 	disabledCameras: Record<string, boolean>
 	disabledVisionServices: Record<string, boolean>
 
+	/** The master switch. The four flags below choose what snaps while it is on. */
 	snapping: boolean
+	/** Step moves, turns, and resizes by `snapTranslate`, `snapRotate`, and `snapScale`. */
+	snapIncrement: boolean
+	/** Snap moves to the key points and surfaces of other geometries. */
+	snapObjects: boolean
+	/** Treat the ground, z = 0, as a surface to snap to. Applies with `snapObjects`. */
+	snapGroundPlane: boolean
+	/** Tilt a surface-snapped object so its +Z follows the surface. Applies with `snapObjects`. */
+	snapAlignRotation: boolean
 	/** Move snap step, in metres. Unlike pose fields, it never reaches a Viam API, so it skips mm. */
 	snapTranslate: number
 	snapRotate: number
@@ -124,6 +133,10 @@ const defaults = (): Settings => ({
 	disabledVisionServices: {},
 
 	snapping: false,
+	snapIncrement: true,
+	snapObjects: false,
+	snapGroundPlane: false,
+	snapAlignRotation: false,
 	snapTranslate: 0.1,
 	snapRotate: 7.5,
 	snapScale: 0.1,
diff --git a/src/lib/plugins/BuildFrames/TransformDashboard.svelte b/src/lib/plugins/BuildFrames/TransformDashboard.svelte
index f9d29ea1b8..a7a0c52b5e 100644
--- a/src/lib/plugins/BuildFrames/TransformDashboard.svelte
+++ b/src/lib/plugins/BuildFrames/TransformDashboard.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { Slider } from 'svelte-tweakpane-ui'
+	import { Checkbox, Separator, Slider } from 'svelte-tweakpane-ui'
 
 	import Button from '$lib/components/overlay/dashboard/Button.svelte'
 	import DropdownPane from '$lib/components/overlay/dashboard/DropdownPane.svelte'
@@ -84,9 +84,14 @@
 				active={settings.current.snapping}
 				description="Snapping settings"
 			>
+				<Checkbox
+					label="Increment"
+					bind:value={settings.current.snapIncrement}
+				/>
 				<!-- Units live in the labels: tweakpane parses typed text as a bare number, so a unit in the value would make every typed edit revert. -->
 				<Slider
 					label="Move (m)"
+					disabled={!settings.current.snapIncrement}
 					min={0}
 					step={0.01}
 					value={settings.current.snapTranslate}
@@ -98,6 +103,7 @@
 				/>
 				<Slider
 					label="Rotate (°)"
+					disabled={!settings.current.snapIncrement}
 					min={0}
 					step={0.5}
 					value={settings.current.snapRotate}
@@ -109,6 +115,7 @@
 				/>
 				<Slider
 					label="Scale"
+					disabled={!settings.current.snapIncrement}
 					min={0}
 					step={0.01}
 					value={settings.current.snapScale}
@@ -118,6 +125,21 @@
 						}
 					}}
 				/>
+				<Separator />
+				<Checkbox
+					label="Objects"
+					bind:value={settings.current.snapObjects}
+				/>
+				<Checkbox
+					label="Ground plane"
+					disabled={!settings.current.snapObjects}
+					bind:value={settings.current.snapGroundPlane}
+				/>
+				<Checkbox
+					label="Align rotation"
+					disabled={!settings.current.snapObjects}
+					bind:value={settings.current.snapAlignRotation}
+				/>
 			</DropdownPane>
 		</fieldset>
 
diff --git a/src/lib/snapping/__tests__/__fixtures__/snapFixtures.ts b/src/lib/snapping/__tests__/__fixtures__/snapFixtures.ts
new file mode 100644
index 0000000000..4bf0885632
--- /dev/null
+++ b/src/lib/snapping/__tests__/__fixtures__/snapFixtures.ts
@@ -0,0 +1,45 @@
+import { Matrix4, Quaternion, Ray, Vector2, Vector3 } from 'three'
+
+import type { SnapShape } from '../../snapShape'
+
+import { type SnapQuery } from '../../snapQuery'
+
+/** Canvas pixels per metre in the top-down view the snap specs look through. */
+export const PIXELS_PER_METRE = 100
+
+export const box = (x: number, y: number, z: number): SnapShape => ({
+	kind: 'box',
+	halfSize: new Vector3(x / 2, y / 2, z / 2),
+})
+
+export const placed = (x: number, y: number, z: number, orientation = new Quaternion()) =>
+	new Matrix4().compose(new Vector3(x, y, z), orientation, new Vector3(1, 1, 1))
+
+/** The camera height the top-down view looks down from. */
+const CAMERA_Z = 10
+
+/**
+ * A query seen from straight above: rays drop from `CAMERA_Z`, and a world point lands at its x
+ * and y scaled to pixels.
+ */
+export const topDownQuery = (
+	cursor: { x: number; y: number },
+	overrides: Partial<SnapQuery>
+): SnapQuery => ({
+	position: new Vector3(),
+	orientation: new Quaternion(),
+	dragged: [],
+	targets: [],
+	constraint: { kind: 'free' },
+	ray: new Ray(new Vector3(cursor.x, cursor.y, CAMERA_Z), new Vector3(0, 0, -1)),
+	cursor: new Vector2(cursor.x, cursor.y).multiplyScalar(PIXELS_PER_METRE),
+	toScreen: (point, out) => {
+		out.set(point.x, point.y).multiplyScalar(PIXELS_PER_METRE)
+		return true
+	},
+	rayThrough: (point, out) =>
+		out.set(new Vector3(point.x, point.y, CAMERA_Z), new Vector3(0, 0, -1)),
+	groundPlane: false,
+	alignRotation: false,
+	...overrides,
+})
diff --git a/src/lib/snapping/__tests__/alignUpToNormal.spec.ts b/src/lib/snapping/__tests__/alignUpToNormal.spec.ts
new file mode 100644
index 0000000000..25f42cf4ca
--- /dev/null
+++ b/src/lib/snapping/__tests__/alignUpToNormal.spec.ts
@@ -0,0 +1,29 @@
+import { Quaternion, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { alignUpToNormal } from '../alignUpToNormal'
+
+describe('alignUpToNormal', () => {
+	it('points +Z along the normal', () => {
+		const normal = new Vector3(1, 0, 1).normalize()
+		const aligned = alignUpToNormal(new Quaternion(), normal, new Quaternion())
+
+		expect(new Vector3(0, 0, 1).applyQuaternion(aligned).distanceTo(normal)).toBeCloseTo(0)
+	})
+
+	it('keeps the heading about a normal that is already up', () => {
+		const heading = new Quaternion().setFromAxisAngle(new Vector3(0, 0, 1), 0.7)
+		const aligned = alignUpToNormal(heading, new Vector3(0, 0, 1), new Quaternion())
+
+		expect(aligned.angleTo(heading)).toBeCloseTo(0)
+	})
+
+	it('keeps +X level when tilting toward Y', () => {
+		const normal = new Vector3(0, -1, 1).normalize()
+		const aligned = alignUpToNormal(new Quaternion(), normal, new Quaternion())
+
+		expect(
+			new Vector3(1, 0, 0).applyQuaternion(aligned).distanceTo(new Vector3(1, 0, 0))
+		).toBeCloseTo(0)
+	})
+})
diff --git a/src/lib/snapping/__tests__/dragConstraint.spec.ts b/src/lib/snapping/__tests__/dragConstraint.spec.ts
new file mode 100644
index 0000000000..156bdbf9b0
--- /dev/null
+++ b/src/lib/snapping/__tests__/dragConstraint.spec.ts
@@ -0,0 +1,54 @@
+import { Quaternion, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { constrainDelta, dragConstraintFor } from '../dragConstraint'
+
+const quarterTurnZ = new Quaternion().setFromAxisAngle(new Vector3(0, 0, 1), Math.PI / 2)
+
+describe('dragConstraintFor', () => {
+	it('treats the centre handle as free', () => {
+		expect(dragConstraintFor('XYZ', 'local', quarterTurnZ)).toEqual({ kind: 'free' })
+	})
+
+	it('reads a single letter as an axis in world space', () => {
+		expect(dragConstraintFor('X', 'world', quarterTurnZ)).toEqual({
+			kind: 'axis',
+			direction: new Vector3(1, 0, 0),
+		})
+	})
+
+	it('turns a local axis with the gizmo', () => {
+		const constraint = dragConstraintFor('X', 'local', quarterTurnZ)
+
+		expect(
+			constraint.kind === 'axis' && constraint.direction.distanceTo(new Vector3(0, 1, 0))
+		).toBeCloseTo(0)
+	})
+
+	it('reads two letters as the plane normal to the missing one', () => {
+		expect(dragConstraintFor('XY', 'world', new Quaternion())).toEqual({
+			kind: 'plane',
+			normal: new Vector3(0, 0, 1),
+		})
+	})
+})
+
+describe('constrainDelta', () => {
+	it('keeps only the part along an axis', () => {
+		const delta = constrainDelta(new Vector3(1, 2, 3), {
+			kind: 'axis',
+			direction: new Vector3(0, 1, 0),
+		})
+
+		expect(delta).toEqual(new Vector3(0, 2, 0))
+	})
+
+	it('drops the part across a plane', () => {
+		const delta = constrainDelta(new Vector3(1, 2, 3), {
+			kind: 'plane',
+			normal: new Vector3(0, 0, 1),
+		})
+
+		expect(delta).toEqual(new Vector3(1, 2, 0))
+	})
+})
diff --git a/src/lib/snapping/__tests__/geometryKeyPoints.spec.ts b/src/lib/snapping/__tests__/geometryKeyPoints.spec.ts
new file mode 100644
index 0000000000..2eec22ca1d
--- /dev/null
+++ b/src/lib/snapping/__tests__/geometryKeyPoints.spec.ts
@@ -0,0 +1,52 @@
+import { Box3, BoxGeometry, Matrix4, Quaternion, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { geometryKeyPoints } from '../geometryKeyPoints'
+import { box, placed } from './__fixtures__/snapFixtures'
+
+const contains = (points: Vector3[], expected: Vector3) =>
+	points.some((point) => point.distanceTo(expected) < 1e-9)
+
+describe('geometryKeyPoints', () => {
+	it('gives a box its 8 corners, 12 edge midpoints, and 6 face centres', () => {
+		const points = geometryKeyPoints(box(2, 2, 2), new Matrix4())
+
+		expect(points).toHaveLength(26)
+		expect(contains(points, new Vector3(1, 1, 1))).toBe(true)
+		expect(contains(points, new Vector3(1, 0, -1))).toBe(true)
+		expect(contains(points, new Vector3(0, 0, 1))).toBe(true)
+		expect(contains(points, new Vector3(0, 0, 0))).toBe(false)
+	})
+
+	it('turns the +Y face centre to face −X under a quarter turn about Z', () => {
+		const quarterTurn = new Quaternion().setFromAxisAngle(new Vector3(0, 0, 1), Math.PI / 2)
+		const points = geometryKeyPoints(box(2, 4, 2), placed(10, 0, 0, quarterTurn))
+
+		expect(contains(points, new Vector3(8, 0, 0))).toBe(true)
+	})
+
+	it('gives a mesh the points of its bounds, wherever those sit', () => {
+		const geometry = new BoxGeometry(2, 2, 2).translate(5, 0, 0)
+		geometry.computeBoundingBox()
+		const bounds = geometry.boundingBox ?? new Box3()
+
+		const points = geometryKeyPoints({ kind: 'mesh', geometry, bounds }, new Matrix4())
+
+		expect(contains(points, new Vector3(6, 1, 1))).toBe(true)
+		expect(contains(points, new Vector3(4, 0, 0))).toBe(true)
+	})
+
+	it('gives a sphere its centre alone', () => {
+		const points = geometryKeyPoints({ kind: 'sphere', radius: 1 }, placed(1, 2, 3))
+
+		expect(points).toEqual([new Vector3(1, 2, 3)])
+	})
+
+	it('gives a capsule its centre and the ends of its axis', () => {
+		const points = geometryKeyPoints({ kind: 'capsule', radius: 0.5, length: 4 }, new Matrix4())
+
+		expect(points).toHaveLength(3)
+		expect(contains(points, new Vector3(0, 0, 2))).toBe(true)
+		expect(contains(points, new Vector3(0, 0, -2))).toBe(true)
+	})
+})
diff --git a/src/lib/snapping/__tests__/isVisibleTurn.spec.ts b/src/lib/snapping/__tests__/isVisibleTurn.spec.ts
new file mode 100644
index 0000000000..9f1f047c0a
--- /dev/null
+++ b/src/lib/snapping/__tests__/isVisibleTurn.spec.ts
@@ -0,0 +1,26 @@
+import { Quaternion, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { alignUpToNormal } from '../alignUpToNormal'
+import { isVisibleTurn } from '../isVisibleTurn'
+
+const UP = new Vector3(0, 0, 1)
+const headings = Array.from({ length: 2000 }, (_, index) =>
+	new Quaternion().setFromAxisAngle(UP, (index / 2000) * Math.PI * 2)
+)
+
+describe('isVisibleTurn', () => {
+	it('ignores the rounding left by aligning a level object to the ground at any heading', () => {
+		const turnedHeadings = headings.filter((heading) =>
+			isVisibleTurn(heading, alignUpToNormal(heading, UP, new Quaternion()))
+		)
+
+		expect(turnedHeadings).toEqual([])
+	})
+
+	it('counts a one-degree tilt as a turn', () => {
+		const tilt = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), Math.PI / 180)
+
+		expect(isVisibleTurn(new Quaternion(), tilt)).toBe(true)
+	})
+})
diff --git a/src/lib/snapping/__tests__/pointSnap.spec.ts b/src/lib/snapping/__tests__/pointSnap.spec.ts
new file mode 100644
index 0000000000..177123ad06
--- /dev/null
+++ b/src/lib/snapping/__tests__/pointSnap.spec.ts
@@ -0,0 +1,105 @@
+import { Matrix4, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { pointSnap, SNAP_RADIUS_PX } from '../pointSnap'
+import { box, PIXELS_PER_METRE, placed, topDownQuery } from './__fixtures__/snapFixtures'
+
+const target = { shape: box(2, 2, 2), matrix: placed(5, 0, 1) }
+const draggedCube = { shape: box(2, 2, 2), anchorToGeometry: new Matrix4() }
+
+describe('pointSnap', () => {
+	it('lands the dragged corner nearest the target corner on it', () => {
+		const result = pointSnap(
+			topDownQuery(
+				{ x: 4, y: 1 },
+				{ position: new Vector3(2.9, 1.9, 1), dragged: [draggedCube], targets: [target] }
+			)
+		)
+
+		expect(
+			result?.position.distanceTo(new Vector3(3, 2, 1)),
+			'the dragged (3.9, 0.9, 2) corner should land on the target (4, 1, 2) corner'
+		).toBeCloseTo(0)
+		expect(result?.indicator).toEqual({ kind: 'point', point: new Vector3(4, 1, 2) })
+	})
+
+	it('picks the point nearer the camera of two that overlap on screen', () => {
+		const result = pointSnap(
+			topDownQuery({ x: 4, y: 1 }, { position: new Vector3(4, 1, 0.5), targets: [target] })
+		)
+
+		expect(result?.indicator).toEqual({ kind: 'point', point: new Vector3(4, 1, 2) })
+	})
+
+	it('skips a key point hidden behind the surface under the cursor', () => {
+		const lid = { shape: box(4, 4, 1), matrix: placed(5, 0, 3) }
+		const result = pointSnap(
+			topDownQuery({ x: 4, y: 1 }, { position: new Vector3(), targets: [target, lid] })
+		)
+
+		expect(result).toBeNull()
+	})
+
+	it('skips a key point below the ground when the ground plane is on', () => {
+		const buried = { shape: box(2, 2, 2), matrix: placed(5, 0, -2) }
+		const result = pointSnap(
+			topDownQuery(
+				{ x: 4, y: 1 },
+				{ position: new Vector3(), targets: [buried], groundPlane: true }
+			)
+		)
+
+		expect(result).toBeNull()
+	})
+
+	it('still snaps to a corner of the box whose surface its own sight line grazes', () => {
+		const result = pointSnap(
+			topDownQuery({ x: 6, y: -1 }, { position: new Vector3(), targets: [target] })
+		)
+
+		expect(result?.indicator).toEqual({ kind: 'point', point: new Vector3(6, -1, 2) })
+	})
+
+	it('sets cubes flush side by side when edge midpoints meet', () => {
+		const result = pointSnap(
+			topDownQuery(
+				{ x: 4, y: 0 },
+				{ position: new Vector3(2.9, 0.1, 1.1), dragged: [draggedCube], targets: [target] }
+			)
+		)
+
+		expect(result?.position.distanceTo(new Vector3(3, 0, 1))).toBeCloseTo(0)
+	})
+
+	it('snaps a frame without geometry by its origin', () => {
+		const result = pointSnap(
+			topDownQuery({ x: 4, y: 1 }, { position: new Vector3(3.9, 1.1, 2), targets: [target] })
+		)
+
+		expect(result?.position.distanceTo(new Vector3(4, 1, 2))).toBeCloseTo(0)
+	})
+
+	it('ignores a key point beyond the snap radius', () => {
+		const offset = (SNAP_RADIUS_PX + 1) / PIXELS_PER_METRE
+		const result = pointSnap(
+			topDownQuery({ x: 4 + offset, y: 1 }, { position: new Vector3(), targets: [target] })
+		)
+
+		expect(result).toBeNull()
+	})
+
+	it('moves only along a constrained axis', () => {
+		const result = pointSnap(
+			topDownQuery(
+				{ x: 4, y: 1 },
+				{
+					position: new Vector3(3.5, 0, 0),
+					targets: [target],
+					constraint: { kind: 'axis', direction: new Vector3(1, 0, 0) },
+				}
+			)
+		)
+
+		expect(result?.position.distanceTo(new Vector3(4, 0, 0))).toBeCloseTo(0)
+	})
+})
diff --git a/src/lib/snapping/__tests__/raycastSnapShape.spec.ts b/src/lib/snapping/__tests__/raycastSnapShape.spec.ts
new file mode 100644
index 0000000000..7ab5123125
--- /dev/null
+++ b/src/lib/snapping/__tests__/raycastSnapShape.spec.ts
@@ -0,0 +1,115 @@
+import { Box3, BoxGeometry, Matrix4, Quaternion, Ray, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { raycastSnapShape } from '../raycastSnapShape'
+import { box, placed } from './__fixtures__/snapFixtures'
+
+const fromAbove = (x: number, y: number) => new Ray(new Vector3(x, y, 10), new Vector3(0, 0, -1))
+const fromPlusX = (y: number, z: number) => new Ray(new Vector3(10, y, z), new Vector3(-1, 0, 0))
+
+const expectVector = (actual: Vector3 | undefined, expected: Vector3) => {
+	expect(actual?.distanceTo(expected)).toBeCloseTo(0)
+}
+
+describe('raycastSnapShape', () => {
+	it('hits the top face of a box placed in the world', () => {
+		const hit = raycastSnapShape(fromAbove(5.2, 0), box(2, 2, 2), placed(5, 0, 1))
+
+		expectVector(hit?.point, new Vector3(5.2, 0, 2))
+		expectVector(hit?.normal, new Vector3(0, 0, 1))
+		expect(hit?.distance).toBeCloseTo(8)
+	})
+
+	it('reports the tilted normal of a rotated box', () => {
+		const roll = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), Math.PI / 6)
+		const hit = raycastSnapShape(fromAbove(0, 0), box(4, 4, 2), placed(0, 0, 0, roll))
+
+		expectVector(hit?.normal, new Vector3(0, 0, 1).applyQuaternion(roll))
+	})
+
+	it('faces a flat box back toward the ray', () => {
+		const hit = raycastSnapShape(fromAbove(0.5, 0), box(2, 2, 0), new Matrix4())
+
+		expectVector(hit?.point, new Vector3(0.5, 0, 0))
+		expectVector(hit?.normal, new Vector3(0, 0, 1))
+	})
+
+	it('faces a flat box back toward every slanted ray, not where rounding lands the hit', () => {
+		const slantedRays = Array.from({ length: 200 }, (_, index) => {
+			const angle = (index / 200) * Math.PI * 2
+			const direction = new Vector3(Math.cos(angle) * 0.3, Math.sin(angle) * 0.7, -1).normalize()
+			return new Ray(new Vector3(0.1, -0.2, 0).addScaledVector(direction, -10), direction)
+		})
+
+		const downwardNormals = slantedRays
+			.map((ray) => raycastSnapShape(ray, box(2, 2, 0), new Matrix4())?.normal)
+			.filter((normal) => normal?.z !== 1)
+
+		expect(downwardNormals).toEqual([])
+	})
+
+	it('misses a box the ray passes beside', () => {
+		expect(raycastSnapShape(fromAbove(3, 0), box(2, 2, 2), new Matrix4())).toBeNull()
+	})
+
+	it('ignores a box behind the ray', () => {
+		const ray = new Ray(new Vector3(0, 0, -5), new Vector3(0, 0, -1))
+
+		expect(raycastSnapShape(ray, box(2, 2, 2), new Matrix4())).toBeNull()
+	})
+
+	it('hits a sphere on its curve, not its bounds', () => {
+		const hit = raycastSnapShape(fromAbove(0.6, 0), { kind: 'sphere', radius: 1 }, new Matrix4())
+
+		expectVector(hit?.point, new Vector3(0.6, 0, 0.8))
+		expectVector(hit?.normal, new Vector3(0.6, 0, 0.8))
+	})
+
+	it('hits the rounded tip of a standing capsule', () => {
+		const hit = raycastSnapShape(
+			fromAbove(0, 0),
+			{ kind: 'capsule', radius: 0.5, length: 4 },
+			new Matrix4()
+		)
+
+		expectVector(hit?.point, new Vector3(0, 0, 2))
+	})
+
+	it('hits the wall of a standing capsule from the side', () => {
+		const hit = raycastSnapShape(
+			fromPlusX(0, 1),
+			{ kind: 'capsule', radius: 0.5, length: 4 },
+			new Matrix4()
+		)
+
+		expectVector(hit?.point, new Vector3(0.5, 0, 1))
+		expectVector(hit?.normal, new Vector3(1, 0, 0))
+	})
+
+	it('hits the flat cap of a cylinder and its wall', () => {
+		const cylinder = { kind: 'cylinder', radius: 0.5, length: 2 } as const
+
+		const cap = raycastSnapShape(fromAbove(0.2, 0), cylinder, new Matrix4())
+		expectVector(cap?.point, new Vector3(0.2, 0, 1))
+		expectVector(cap?.normal, new Vector3(0, 0, 1))
+
+		const wall = raycastSnapShape(fromPlusX(0, 0.5), cylinder, new Matrix4())
+		expectVector(wall?.point, new Vector3(0.5, 0, 0.5))
+		expectVector(wall?.normal, new Vector3(1, 0, 0))
+	})
+
+	it('hits a mesh triangle and reports its outward normal', () => {
+		const geometry = new BoxGeometry(2, 2, 2)
+		geometry.computeBoundingBox()
+		const bounds = geometry.boundingBox ?? new Box3()
+
+		const hit = raycastSnapShape(
+			fromAbove(0.3, 0.3),
+			{ kind: 'mesh', geometry, bounds },
+			placed(0, 0, 1)
+		)
+
+		expectVector(hit?.point, new Vector3(0.3, 0.3, 2))
+		expectVector(hit?.normal, new Vector3(0, 0, 1))
+	})
+})
diff --git a/src/lib/snapping/__tests__/supportDistance.spec.ts b/src/lib/snapping/__tests__/supportDistance.spec.ts
new file mode 100644
index 0000000000..7159c3532c
--- /dev/null
+++ b/src/lib/snapping/__tests__/supportDistance.spec.ts
@@ -0,0 +1,45 @@
+import { Box3, BoxGeometry, Matrix4, Quaternion, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { supportDistance } from '../supportDistance'
+import { box, placed } from './__fixtures__/snapFixtures'
+
+const DOWN = new Vector3(0, 0, -1)
+const tiltedAboutX = (radians: number) =>
+	placed(0, 0, 0, new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), radians))
+
+describe('supportDistance', () => {
+	it('reaches a level box down by half its height', () => {
+		expect(supportDistance(box(2, 4, 6), new Matrix4(), DOWN)).toBeCloseTo(3)
+	})
+
+	it('reaches a box rolled 45° down to its lowest edge', () => {
+		expect(supportDistance(box(2, 2, 2), tiltedAboutX(Math.PI / 4), DOWN)).toBeCloseTo(Math.SQRT2)
+	})
+
+	it('reaches a sphere by its radius in every direction', () => {
+		expect(supportDistance({ kind: 'sphere', radius: 0.3 }, tiltedAboutX(1), DOWN)).toBe(0.3)
+	})
+
+	it('reaches a standing capsule down to its tip, and a lying one by its radius', () => {
+		const capsule = { kind: 'capsule', radius: 0.5, length: 4 } as const
+
+		expect(supportDistance(capsule, new Matrix4(), DOWN)).toBeCloseTo(2)
+		expect(supportDistance(capsule, tiltedAboutX(Math.PI / 2), DOWN)).toBeCloseTo(0.5)
+	})
+
+	it('reaches a lying cylinder by its radius', () => {
+		const cylinder = { kind: 'cylinder', radius: 0.5, length: 4 } as const
+
+		expect(supportDistance(cylinder, new Matrix4(), DOWN)).toBeCloseTo(2)
+		expect(supportDistance(cylinder, tiltedAboutX(Math.PI / 2), DOWN)).toBeCloseTo(0.5)
+	})
+
+	it('counts a mesh whose bounds sit above its origin as reaching up, not down', () => {
+		const geometry = new BoxGeometry(2, 2, 2).translate(0, 0, 3)
+		geometry.computeBoundingBox()
+		const bounds = geometry.boundingBox ?? new Box3()
+
+		expect(supportDistance({ kind: 'mesh', geometry, bounds }, new Matrix4(), DOWN)).toBeCloseTo(-2)
+	})
+})
diff --git a/src/lib/snapping/__tests__/surfaceSnap.spec.ts b/src/lib/snapping/__tests__/surfaceSnap.spec.ts
new file mode 100644
index 0000000000..847fafc17a
--- /dev/null
+++ b/src/lib/snapping/__tests__/surfaceSnap.spec.ts
@@ -0,0 +1,122 @@
+import { Matrix4, Quaternion, Vector3 } from 'three'
+import { describe, expect, it } from 'vitest'
+
+import { surfaceSnap } from '../surfaceSnap'
+import { box, placed, topDownQuery } from './__fixtures__/snapFixtures'
+
+const table = { shape: box(4, 4, 1), matrix: placed(0, 0, 0.5) }
+const draggedCube = { shape: box(1, 1, 1), anchorToGeometry: new Matrix4() }
+
+describe('surfaceSnap', () => {
+	it('sets a dragged cube on the surface under the cursor', () => {
+		const result = surfaceSnap(
+			topDownQuery(
+				{ x: 1, y: 0.5 },
+				{ position: new Vector3(3, 3, 3), dragged: [draggedCube], targets: [table] }
+			)
+		)
+
+		expect(result?.position.distanceTo(new Vector3(1, 0.5, 1.5))).toBeCloseTo(0)
+		expect(result?.indicator.kind).toBe('surface')
+	})
+
+	it('sets the geometry down, not the frame origin, when the geometry hangs below its frame', () => {
+		const offsetCube = { shape: box(1, 1, 1), anchorToGeometry: placed(0, 0, -0.25) }
+		const result = surfaceSnap(
+			topDownQuery(
+				{ x: 0, y: 0 },
+				{ position: new Vector3(), dragged: [offsetCube], targets: [table] }
+			)
+		)
+
+		expect(result?.position.z).toBeCloseTo(1.75)
+	})
+
+	it('sets down whichever dragged geometry reaches lowest', () => {
+		const lowerCube = { shape: box(1, 1, 1), anchorToGeometry: placed(0, 0, -1) }
+		const result = surfaceSnap(
+			topDownQuery(
+				{ x: 0, y: 0 },
+				{ position: new Vector3(), dragged: [draggedCube, lowerCube], targets: [table] }
+			)
+		)
+
+		expect(result?.position.z).toBeCloseTo(2.5)
+	})
+
+	it('does nothing for a frame without geometry', () => {
+		const result = surfaceSnap(topDownQuery({ x: 0, y: 0 }, { targets: [table] }))
+
+		expect(result).toBeNull()
+	})
+
+	it('sets the cube on the ground only when the ground plane is on', () => {
+		const query = { position: new Vector3(9, 9, 9), dragged: [draggedCube] }
+
+		expect(surfaceSnap(topDownQuery({ x: 5, y: 5 }, query))).toBeNull()
+
+		const result = surfaceSnap(topDownQuery({ x: 5, y: 5 }, { ...query, groundPlane: true }))
+		expect(result?.position.distanceTo(new Vector3(5, 5, 0.5))).toBeCloseTo(0)
+	})
+
+	it('prefers a target over the ground beneath it', () => {
+		const result = surfaceSnap(
+			topDownQuery({ x: 0, y: 0 }, { dragged: [draggedCube], targets: [table], groundPlane: true })
+		)
+
+		expect(result?.position.z).toBeCloseTo(1.5)
+	})
+
+	it('tilts the cube onto a slanted surface when aligning', () => {
+		const slope = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), Math.PI / 6)
+		const ramp = { shape: box(10, 10, 1), matrix: placed(0, 0, 0, slope) }
+		const result = surfaceSnap(
+			topDownQuery({ x: 0, y: 0 }, { dragged: [draggedCube], targets: [ramp], alignRotation: true })
+		)
+
+		const up = new Vector3(0, 0, 1).applyQuaternion(result?.orientation ?? new Quaternion())
+		expect(up.distanceTo(new Vector3(0, 0, 1).applyQuaternion(slope))).toBeCloseTo(0)
+	})
+
+	it('keeps the drag orientation when not aligning', () => {
+		const slope = new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), Math.PI / 6)
+		const ramp = { shape: box(10, 10, 1), matrix: placed(0, 0, 0, slope) }
+		const result = surfaceSnap(
+			topDownQuery({ x: 0, y: 0 }, { dragged: [draggedCube], targets: [ramp] })
+		)
+
+		expect(result?.orientation.angleTo(new Quaternion())).toBeCloseTo(0)
+	})
+
+	it('drops along a vertical axis constraint without moving sideways', () => {
+		const result = surfaceSnap(
+			topDownQuery(
+				{ x: 1, y: 1 },
+				{
+					position: new Vector3(0.8, 1.2, 4),
+					dragged: [draggedCube],
+					targets: [table],
+					constraint: { kind: 'axis', direction: new Vector3(0, 0, 1) },
+				}
+			)
+		)
+
+		expect(result?.position.distanceTo(new Vector3(0.8, 1.2, 1.5))).toBeCloseTo(0)
+	})
+
+	it('does not snap when the constraint cannot move toward the surface', () => {
+		const result = surfaceSnap(
+			topDownQuery(
+				{ x: 0, y: 0 },
+				{
+					position: new Vector3(0, 0, 4),
+					dragged: [draggedCube],
+					targets: [table],
+					constraint: { kind: 'plane', normal: new Vector3(0, 0, 1) },
+				}
+			)
+		)
+
+		expect(result).toBeNull()
+	})
+})
diff --git a/src/lib/snapping/alignUpToNormal.ts b/src/lib/snapping/alignUpToNormal.ts
new file mode 100644
index 0000000000..93fd4d5fc6
--- /dev/null
+++ b/src/lib/snapping/alignUpToNormal.ts
@@ -0,0 +1,20 @@
+import { Quaternion, Vector3 } from 'three'
+
+const up = new Vector3()
+const tilt = new Quaternion()
+
+/**
+ * Tilts an orientation so its +Z points along `normal`, by the smallest rotation that does it.
+ * Heading about the normal is kept, so a box set on a slanted shelf keeps facing the way it faced.
+ *
+ * @param normal A unit vector in world space.
+ */
+export const alignUpToNormal = (
+	start: Quaternion,
+	normal: Vector3,
+	out: Quaternion
+): Quaternion => {
+	up.set(0, 0, 1).applyQuaternion(start)
+	tilt.setFromUnitVectors(up, normal)
+	return out.multiplyQuaternions(tilt, start)
+}
diff --git a/src/lib/snapping/dragConstraint.ts b/src/lib/snapping/dragConstraint.ts
new file mode 100644
index 0000000000..4e789199bd
--- /dev/null
+++ b/src/lib/snapping/dragConstraint.ts
@@ -0,0 +1,66 @@
+import { type Quaternion, Vector3 } from 'three'
+
+/**
+ * The directions a translate drag may move in: anywhere, along one axis, or within one plane.
+ * Directions are unit vectors in world space.
+ */
+export type DragConstraint =
+	| { kind: 'free' }
+	| { kind: 'axis'; direction: Vector3 }
+	| { kind: 'plane'; normal: Vector3 }
+
+const AXIS_LETTERS = ['X', 'Y', 'Z'] as const
+
+const AXIS_VECTORS = {
+	X: new Vector3(1, 0, 0),
+	Y: new Vector3(0, 1, 0),
+	Z: new Vector3(0, 0, 1),
+} as const
+
+/**
+ * The constraint behind a `TransformControls` translate handle.
+ *
+ * @param axis The handle being dragged, as `TransformControls.axis` names it: `'X'`, `'XY'`, `'XYZ'`.
+ * @param orientation The gizmo's orientation at drag start, used when `space` is `'local'`.
+ */
+export const dragConstraintFor = (
+	axis: string,
+	space: 'local' | 'world',
+	orientation: Quaternion
+): DragConstraint => {
+	const present = AXIS_LETTERS.filter((letter) => axis.includes(letter))
+	const missing = AXIS_LETTERS.filter((letter) => !axis.includes(letter))
+	const orient = (vector: Vector3) =>
+		space === 'local' ? vector.applyQuaternion(orientation) : vector
+
+	const [only] = present
+	if (present.length === 1 && only) {
+		return { kind: 'axis', direction: orient(AXIS_VECTORS[only].clone()) }
+	}
+
+	const [planeNormal] = missing
+	if (missing.length === 1 && planeNormal) {
+		return { kind: 'plane', normal: orient(AXIS_VECTORS[planeNormal].clone()) }
+	}
+
+	// The centre handle moves in the camera plane, in world space, whatever `space` says.
+	return { kind: 'free' }
+}
+
+/** Drops the part of `delta` the constraint forbids, in place. */
+export const constrainDelta = (delta: Vector3, constraint: DragConstraint): Vector3 => {
+	switch (constraint.kind) {
+		case 'free': {
+			return delta
+		}
+		case 'axis': {
+			return delta.projectOnVector(constraint.direction)
+		}
+		case 'plane': {
+			return delta.projectOnPlane(constraint.normal)
+		}
+		default: {
+			return constraint satisfies never
+		}
+	}
+}
diff --git a/src/lib/snapping/geometryKeyPoints.ts b/src/lib/snapping/geometryKeyPoints.ts
new file mode 100644
index 0000000000..50d4d09e93
--- /dev/null
+++ b/src/lib/snapping/geometryKeyPoints.ts
@@ -0,0 +1,66 @@
+import { type Matrix4, Vector3 } from 'three'
+
+import type { SnapShape } from './snapShape'
+
+const boxCenter = new Vector3()
+const boxHalfSize = new Vector3()
+
+/**
+ * Every corner, edge midpoint, and face centre of a box: the 26 sign combinations of its
+ * half-size, leaving out the all-zero centre.
+ */
+const pushBoxPoints = (center: Vector3, halfSize: Vector3, out: Vector3[]) => {
+	for (const x of [-1, 0, 1]) {
+		for (const y of [-1, 0, 1]) {
+			for (const z of [-1, 0, 1]) {
+				if (x === 0 && y === 0 && z === 0) continue
+				out.push(new Vector3(x * halfSize.x, y * halfSize.y, z * halfSize.z).add(center))
+			}
+		}
+	}
+}
+
+/** The centre, and the two ends of the shape's +Z axis. */
+const pushAxisPoints = (halfLength: number, out: Vector3[]) => {
+	out.push(new Vector3(), new Vector3(0, 0, halfLength), new Vector3(0, 0, -halfLength))
+}
+
+/**
+ * A geometry's snap points in world space. A box, or a mesh through its local bounds, gives its
+ * corners, edge midpoints, and face centres. A sphere gives its centre. A capsule or cylinder gives
+ * its centre and the two ends of its axis.
+ *
+ * @param matrix The geometry's local-to-world transform.
+ */
+export const geometryKeyPoints = (shape: SnapShape, matrix: Matrix4): Vector3[] => {
+	const points: Vector3[] = []
+
+	switch (shape.kind) {
+		case 'box': {
+			pushBoxPoints(boxCenter.set(0, 0, 0), shape.halfSize, points)
+			break
+		}
+		case 'mesh': {
+			shape.bounds.getCenter(boxCenter)
+			shape.bounds.getSize(boxHalfSize).multiplyScalar(0.5)
+			pushBoxPoints(boxCenter, boxHalfSize, points)
+			break
+		}
+		case 'sphere': {
+			points.push(new Vector3())
+			break
+		}
+		case 'capsule':
+		case 'cylinder': {
+			pushAxisPoints(shape.length / 2, points)
+			break
+		}
+		default: {
+			shape satisfies never
+		}
+	}
+
+	for (const point of points) point.applyMatrix4(matrix)
+
+	return points
+}
diff --git a/src/lib/snapping/isVisibleTurn.ts b/src/lib/snapping/isVisibleTurn.ts
new file mode 100644
index 0000000000..d574392f5b
--- /dev/null
+++ b/src/lib/snapping/isVisibleTurn.ts
@@ -0,0 +1,10 @@
+import type { Quaternion } from 'three'
+
+// Re-deriving an unchanged orientation leaves the quaternion dot product a rounding error short
+// of 1, which `angleTo`'s acos magnifies to up to about 1e-7 rad. A real turn onto a surface is
+// orders of magnitude past this.
+const MIN_TURN_RADIANS = 1e-5
+
+/** Whether `to` is turned from `from` by more than rounding noise. */
+export const isVisibleTurn = (from: Quaternion, to: Quaternion): boolean =>
+	from.angleTo(to) > MIN_TURN_RADIANS
diff --git a/src/lib/snapping/nearestSurfaceHit.ts b/src/lib/snapping/nearestSurfaceHit.ts
new file mode 100644
index 0000000000..76254b0d5e
--- /dev/null
+++ b/src/lib/snapping/nearestSurfaceHit.ts
@@ -0,0 +1,36 @@
+import { Plane, type Ray, Vector3 } from 'three'
+
+import type { SnapTarget } from './snapQuery'
+
+import { raycastSnapShape, type SnapHit } from './raycastSnapShape'
+
+const GROUND_PLANE = new Plane(new Vector3(0, 0, 1), 0)
+
+const groundHit = (ray: Ray): SnapHit | null => {
+	// Only from above. Seen from below, the ground is not a surface anything rests on.
+	if (ray.direction.z >= 0) return null
+
+	const point = ray.intersectPlane(GROUND_PLANE, new Vector3())
+	if (!point) return null
+
+	return { point, normal: new Vector3(0, 0, 1), distance: point.distanceTo(ray.origin) }
+}
+
+/**
+ * The first surface a ray meets among the targets, and the ground when `groundPlane` is set.
+ * Returns `null` when it meets none.
+ */
+export const nearestSurfaceHit = (
+	ray: Ray,
+	targets: SnapTarget[],
+	groundPlane: boolean
+): SnapHit | null => {
+	let nearest = groundPlane ? groundHit(ray) : null
+
+	for (const target of targets) {
+		const hit = raycastSnapShape(ray, target.shape, target.matrix)
+		if (hit && (!nearest || hit.distance < nearest.distance)) nearest = hit
+	}
+
+	return nearest
+}
diff --git a/src/lib/snapping/pointSnap.ts b/src/lib/snapping/pointSnap.ts
new file mode 100644
index 0000000000..e6f8ff3289
--- /dev/null
+++ b/src/lib/snapping/pointSnap.ts
@@ -0,0 +1,99 @@
+import { Matrix4, Ray, Vector2, Vector3 } from 'three'
+
+import type { SnapQuery, SnapResult } from './snapQuery'
+
+import { constrainDelta } from './dragConstraint'
+import { geometryKeyPoints } from './geometryKeyPoints'
+import { nearestSurfaceHit } from './nearestSurfaceHit'
+
+/** How close the cursor has to come to a key point, in canvas pixels, for it to catch. */
+export const SNAP_RADIUS_PX = 12
+
+const UNIT_SCALE = new Vector3(1, 1, 1)
+const screenPoint = new Vector2()
+const geometryMatrix = new Matrix4()
+const sightLine = new Ray()
+const toPoint = new Vector3()
+
+// Points this close together on screen read as one spot to the user, so depth decides between them.
+const SCREEN_TIE_PX = 0.5
+
+// A key point sits on its own geometry's surface, so the sight line to it can meet that surface a
+// hair before the point. Only a surface further in front than this hides it.
+const OCCLUSION_TOLERANCE_M = 0.001
+
+/** Whether a surface stands between the camera and `point`, so the user cannot see it. */
+const isHidden = (query: SnapQuery, point: Vector3): boolean => {
+	query.rayThrough(point, sightLine)
+	const pointDistance = toPoint.copy(point).sub(sightLine.origin).dot(sightLine.direction)
+	const hit = nearestSurfaceHit(sightLine, query.targets, query.groundPlane)
+	return hit !== null && hit.distance < pointDistance - OCCLUSION_TOLERANCE_M
+}
+
+/**
+ * The visible target key point nearest the cursor on screen, within {@link SNAP_RADIUS_PX}. A point
+ * behind a surface is skipped, since the user is pointing at the surface, not through it. Of points
+ * that overlap on screen, the one nearer the camera wins.
+ */
+const nearestTargetPoint = (query: SnapQuery): Vector3 | undefined => {
+	let nearest: Vector3 | undefined
+	let nearestPixels = SNAP_RADIUS_PX
+	let nearestDepth = Infinity
+
+	for (const target of query.targets) {
+		for (const point of geometryKeyPoints(target.shape, target.matrix)) {
+			if (!query.toScreen(point, screenPoint)) continue
+
+			const pixels = screenPoint.distanceTo(query.cursor)
+			if (pixels > SNAP_RADIUS_PX) continue
+
+			const depth = point.distanceTo(query.ray.origin)
+			const isTie = nearest !== undefined && Math.abs(pixels - nearestPixels) <= SCREEN_TIE_PX
+			if (isTie ? depth >= nearestDepth : pixels > nearestPixels) continue
+			// Last, since it casts a ray against every target. Few points get this far.
+			if (isHidden(query, point)) continue
+
+			nearest = point
+			nearestPixels = pixels
+			nearestDepth = depth
+		}
+	}
+
+	return nearest
+}
+
+/** The dragged geometries' key points at the gizmo's position, or its origin when it has none. */
+const sourcePoints = (query: SnapQuery): Vector3[] => {
+	if (query.dragged.length === 0) return [query.position.clone()]
+
+	return query.dragged.flatMap(({ shape, anchorToGeometry }) => {
+		geometryMatrix.compose(query.position, query.orientation, UNIT_SCALE).multiply(anchorToGeometry)
+		return geometryKeyPoints(shape, geometryMatrix)
+	})
+}
+
+/**
+ * Lands the dragged entity's nearest key point on the target key point under the cursor. Returns
+ * `null` when no target point is within reach.
+ */
+export const pointSnap = (query: SnapQuery): SnapResult | null => {
+	const target = nearestTargetPoint(query)
+	if (!target) return null
+
+	let source = query.position
+	let sourceDistance = Infinity
+	for (const point of sourcePoints(query)) {
+		const distance = point.distanceTo(target)
+		if (distance >= sourceDistance) continue
+		source = point
+		sourceDistance = distance
+	}
+
+	const delta = constrainDelta(target.clone().sub(source), query.constraint)
+
+	return {
+		position: query.position.clone().add(delta),
+		orientation: query.orientation.clone(),
+		indicator: { kind: 'point', point: target },
+	}
+}
diff --git a/src/lib/snapping/raycastSnapShape.ts b/src/lib/snapping/raycastSnapShape.ts
new file mode 100644
index 0000000000..b76b4f5786
--- /dev/null
+++ b/src/lib/snapping/raycastSnapShape.ts
@@ -0,0 +1,182 @@
+import { Box3, type BufferGeometry, DoubleSide, Matrix4, Plane, Ray, Sphere, Vector3 } from 'three'
+import { MeshBVH } from 'three-mesh-bvh'
+
+import type { SnapShape } from './snapShape'
+
+/** Where a ray meets a geometry's surface, in world space. */
+export interface SnapHit {
+	point: Vector3
+	/** The outward surface normal at `point`, unit length. */
+	normal: Vector3
+	/** Distance from the ray's origin to `point`. */
+	distance: number
+}
+
+/** The nearest hit found so far on one shape, in the shape's local frame. */
+interface LocalHit {
+	distance: number
+	point: Vector3
+	normal: Vector3
+}
+
+const inverse = new Matrix4()
+const localRay = new Ray()
+const candidate = new Vector3()
+const offset = new Vector3()
+const scratchBox = new Box3()
+const scratchSphere = new Sphere()
+const capPlane = new Plane()
+
+// Built on first hit-test and kept with the geometry. `indirect` leaves the rendered geometry's
+// index untouched, since a BVH otherwise reorders it.
+const meshBvhs = new WeakMap<BufferGeometry, MeshBVH>()
+
+const bvhFor = (geometry: BufferGeometry): MeshBVH => {
+	let bvh = meshBvhs.get(geometry)
+	if (!bvh) {
+		bvh = new MeshBVH(geometry, { indirect: true })
+		meshBvhs.set(geometry, bvh)
+	}
+	return bvh
+}
+
+/**
+ * Records `candidate` as the hit when it lies ahead of the ray and nearer than the current one.
+ * Returns whether it was recorded, so the caller knows to set the normal.
+ */
+const recordIfNearer = (ray: Ray, hit: LocalHit): boolean => {
+	const distance = offset.copy(candidate).sub(ray.origin).dot(ray.direction)
+	if (distance < 0 || distance >= hit.distance) return false
+
+	hit.distance = distance
+	hit.point.copy(candidate)
+	return true
+}
+
+const hitBox = (ray: Ray, halfSize: Vector3, hit: LocalHit) => {
+	scratchBox.min.copy(halfSize).negate()
+	scratchBox.max.copy(halfSize)
+	if (!ray.intersectBox(scratchBox, candidate) || !recordIfNearer(ray, hit)) return
+
+	// The face is the axis where the hit sits closest to the box's extent. Gaps, not ratios, so a
+	// box sized 0 on one axis, which the scale gizmo allows, still picks that axis.
+	const gapX = halfSize.x - Math.abs(candidate.x)
+	const gapY = halfSize.y - Math.abs(candidate.y)
+	const gapZ = halfSize.z - Math.abs(candidate.z)
+	if (gapX <= gapY && gapX <= gapZ) {
+		hit.normal.set(faceSign(candidate.x, halfSize.x, ray.direction.x), 0, 0)
+	} else if (gapY <= gapZ) {
+		hit.normal.set(0, faceSign(candidate.y, halfSize.y, ray.direction.y), 0)
+	} else {
+		hit.normal.set(0, 0, faceSign(candidate.z, halfSize.z, ray.direction.z))
+	}
+}
+
+/**
+ * Which way a box face points along one axis. A box flat on that axis has both faces at 0, and a
+ * slanted ray lands a rounding error either side of it, so a flat face points back at the ray.
+ */
+const faceSign = (coordinate: number, halfSize: number, direction: number): number =>
+	halfSize === 0 ? -Math.sign(direction) : Math.sign(coordinate)
+
+/** A sphere centred on the local +Z axis at `centerZ`. */
+const hitSphere = (ray: Ray, centerZ: number, radius: number, hit: LocalHit) => {
+	scratchSphere.center.set(0, 0, centerZ)
+	scratchSphere.radius = radius
+	if (!ray.intersectSphere(scratchSphere, candidate) || !recordIfNearer(ray, hit)) return
+
+	hit.normal.copy(candidate).sub(scratchSphere.center).normalize()
+}
+
+/** The side wall of a cylinder about +Z, between `±halfLength`. */
+const hitCylinderWall = (ray: Ray, radius: number, halfLength: number, hit: LocalHit) => {
+	const { origin, direction } = ray
+	const a = direction.x * direction.x + direction.y * direction.y
+	// A ray parallel to the axis never crosses the wall.
+	if (a < Number.EPSILON) return
+
+	const b = 2 * (origin.x * direction.x + origin.y * direction.y)
+	const c = origin.x * origin.x + origin.y * origin.y - radius * radius
+	const discriminant = b * b - 4 * a * c
+	if (discriminant < 0) return
+
+	ray.at((-b - Math.sqrt(discriminant)) / (2 * a), candidate)
+	if (Math.abs(candidate.z) > halfLength || !recordIfNearer(ray, hit)) return
+
+	hit.normal.set(candidate.x, candidate.y, 0).normalize()
+}
+
+/** A flat disc at `capZ`, facing away from the cylinder's centre. */
+const hitCylinderCap = (ray: Ray, radius: number, capZ: number, hit: LocalHit) => {
+	capPlane.normal.set(0, 0, Math.sign(capZ))
+	capPlane.constant = -Math.abs(capZ)
+	if (!ray.intersectPlane(capPlane, candidate)) return
+	if (candidate.x * candidate.x + candidate.y * candidate.y > radius * radius) return
+	if (!recordIfNearer(ray, hit)) return
+
+	hit.normal.copy(capPlane.normal)
+}
+
+const hitMesh = (ray: Ray, geometry: BufferGeometry, hit: LocalHit) => {
+	const intersection = bvhFor(geometry).raycastFirst(ray, DoubleSide)
+	if (!intersection?.face) return
+
+	candidate.copy(intersection.point)
+	if (!recordIfNearer(ray, hit)) return
+
+	hit.normal.copy(intersection.face.normal)
+	// A double-sided hit can land on a back face, whose stored normal points along the ray.
+	if (hit.normal.dot(ray.direction) > 0) hit.normal.negate()
+}
+
+const hitShape = (ray: Ray, shape: SnapShape, hit: LocalHit) => {
+	switch (shape.kind) {
+		case 'box': {
+			hitBox(ray, shape.halfSize, hit)
+			return
+		}
+		case 'sphere': {
+			hitSphere(ray, 0, shape.radius, hit)
+			return
+		}
+		case 'capsule': {
+			const segmentHalfLength = Math.max(0, shape.length / 2 - shape.radius)
+			hitCylinderWall(ray, shape.radius, segmentHalfLength, hit)
+			hitSphere(ray, segmentHalfLength, shape.radius, hit)
+			hitSphere(ray, -segmentHalfLength, shape.radius, hit)
+			return
+		}
+		case 'cylinder': {
+			const halfLength = shape.length / 2
+			hitCylinderWall(ray, shape.radius, halfLength, hit)
+			hitCylinderCap(ray, shape.radius, halfLength, hit)
+			hitCylinderCap(ray, shape.radius, -halfLength, hit)
+			return
+		}
+		case 'mesh': {
+			hitMesh(ray, shape.geometry, hit)
+			return
+		}
+		default: {
+			shape satisfies never
+		}
+	}
+}
+
+/**
+ * Where a world-space ray first meets a geometry's surface, or `null` when it misses.
+ *
+ * @param matrix The geometry's local-to-world transform, without scale.
+ */
+export const raycastSnapShape = (ray: Ray, shape: SnapShape, matrix: Matrix4): SnapHit | null => {
+	localRay.copy(ray).applyMatrix4(inverse.copy(matrix).invert())
+	localRay.direction.normalize()
+
+	const hit: LocalHit = { distance: Infinity, point: new Vector3(), normal: new Vector3() }
+	hitShape(localRay, shape, hit)
+	if (hit.distance === Infinity) return null
+
+	const point = hit.point.applyMatrix4(matrix)
+	const normal = hit.normal.transformDirection(matrix)
+	return { point, normal, distance: point.distanceTo(ray.origin) }
+}
diff --git a/src/lib/snapping/resolveSnap.ts b/src/lib/snapping/resolveSnap.ts
new file mode 100644
index 0000000000..d4f0829c72
--- /dev/null
+++ b/src/lib/snapping/resolveSnap.ts
@@ -0,0 +1,12 @@
+import type { SnapQuery, SnapResult } from './snapQuery'
+
+import { pointSnap } from './pointSnap'
+import { surfaceSnap } from './surfaceSnap'
+
+/**
+ * Where one pointer move of a translate drag snaps to. A key point within reach of the cursor wins
+ * over the surface under it. Returns `null` when neither applies, which leaves the gizmo's own
+ * position, increment snap included, in place.
+ */
+export const resolveSnap = (query: SnapQuery): SnapResult | null =>
+	pointSnap(query) ?? surfaceSnap(query)
diff --git a/src/lib/snapping/snapQuery.ts b/src/lib/snapping/snapQuery.ts
new file mode 100644
index 0000000000..31f0d0c6da
--- /dev/null
+++ b/src/lib/snapping/snapQuery.ts
@@ -0,0 +1,58 @@
+import type { Matrix4, Quaternion, Ray, Vector2, Vector3 } from 'three'
+
+import type { DragConstraint } from './dragConstraint'
+import type { SnapShape } from './snapShape'
+
+/** A geometry the drag can snap to. */
+export interface SnapTarget {
+	shape: SnapShape
+	/** The geometry's local-to-world transform, without scale. */
+	matrix: Matrix4
+}
+
+/** One geometry that moves with the drag, placed relative to the gizmo. */
+export interface DraggedGeometry {
+	shape: SnapShape
+	/** The geometry's transform relative to the gizmo anchor. */
+	anchorToGeometry: Matrix4
+}
+
+/** One pointer move of a translate drag. */
+export interface SnapQuery {
+	/** Where the gizmo put the anchor, before any object snap. */
+	position: Vector3
+	/** The anchor's orientation when the drag began. */
+	orientation: Quaternion
+	/**
+	 * The geometries that move with the drag: the entity's own and its descendants'. Empty for a
+	 * frame with none, which snaps by its origin alone.
+	 */
+	dragged: DraggedGeometry[]
+	targets: SnapTarget[]
+	constraint: DragConstraint
+	/** The world-space ray under the cursor. */
+	ray: Ray
+	/** The cursor, in canvas pixels. */
+	cursor: Vector2
+	/**
+	 * Projects a world point to canvas pixels into `out`. Returns `false` for a point behind the
+	 * camera.
+	 */
+	toScreen: (point: Vector3, out: Vector2) => boolean
+	/** Sets `out` to the camera's ray through the pixel `point` projects to. */
+	rayThrough: (point: Vector3, out: Ray) => Ray
+	groundPlane: boolean
+	alignRotation: boolean
+}
+
+/** What the scene draws to show where a snap landed. */
+export type SnapIndicator =
+	| { kind: 'point'; point: Vector3 }
+	| { kind: 'surface'; point: Vector3; normal: Vector3 }
+
+/** A snapped anchor pose. */
+export interface SnapResult {
+	position: Vector3
+	orientation: Quaternion
+	indicator: SnapIndicator
+}
diff --git a/src/lib/snapping/snapScene.ts b/src/lib/snapping/snapScene.ts
new file mode 100644
index 0000000000..66bcbf11ff
--- /dev/null
+++ b/src/lib/snapping/snapScene.ts
@@ -0,0 +1,66 @@
+import type { Entity, World } from 'koota'
+
+import { Matrix4 } from 'three'
+
+import { composeMeshMatrix } from '$lib/components/Entities/composeMeshMatrix'
+import { relations, traits } from '$lib/ecs'
+
+import type { DraggedGeometry, SnapTarget } from './snapQuery'
+
+import { type SnapShape, snapShapeOf } from './snapShape'
+
+/** A geometry the drag can snap to. Its pose is read fresh on every pointer move. */
+export interface SnapTargetEntity {
+	entity: Entity
+	shape: SnapShape
+}
+
+/** What a translate drag snaps with and against, gathered once when the drag starts. */
+export interface SnapScene {
+	targets: SnapTargetEntity[]
+	dragged: DraggedGeometry[]
+}
+
+const collectSubtree = (world: World, root: Entity, out: Set<Entity>): Set<Entity> => {
+	out.add(root)
+	for (const child of world.query(relations.ChildOf(root))) collectSubtree(world, child, out)
+	return out
+}
+
+/**
+ * Splits the world's geometries for a drag of `dragged`. The entity and its descendants move
+ * together, so their geometries are what snaps. Every other visible geometry is a target.
+ *
+ * @param anchor The gizmo anchor's world transform at drag start. Each dragged geometry is stored
+ * relative to it.
+ */
+export const snapSceneFor = (world: World, dragged: Entity, anchor: Matrix4): SnapScene => {
+	const moving = collectSubtree(world, dragged, new Set())
+	const anchorInverse = new Matrix4().copy(anchor).invert()
+	const scene: SnapScene = { targets: [], dragged: [] }
+
+	for (const entity of world.query(traits.WorldMatrix)) {
+		const shape = snapShapeOf(entity)
+		if (!shape) continue
+
+		if (moving.has(entity)) {
+			const anchorToGeometry = new Matrix4()
+			// `WorldMatrix × Center`: where every geometry kind renders, not only meshes.
+			if (!composeMeshMatrix(entity, anchorToGeometry)) continue
+			scene.dragged.push({ shape, anchorToGeometry: anchorToGeometry.premultiply(anchorInverse) })
+			continue
+		}
+
+		if (entity.has(traits.Invisible) || entity.has(traits.InheritedInvisible)) continue
+		scene.targets.push({ entity, shape })
+	}
+
+	return scene
+}
+
+/** The targets posed where they stand now. A target whose pose has gone is dropped. */
+export const posedTargets = (targets: SnapTargetEntity[]): SnapTarget[] =>
+	targets.flatMap(({ entity, shape }) => {
+		const matrix = new Matrix4()
+		return composeMeshMatrix(entity, matrix) ? [{ shape, matrix }] : []
+	})
diff --git a/src/lib/snapping/snapShape.ts b/src/lib/snapping/snapShape.ts
new file mode 100644
index 0000000000..9835f692bb
--- /dev/null
+++ b/src/lib/snapping/snapShape.ts
@@ -0,0 +1,53 @@
+import type { Entity } from 'koota'
+
+import { Box3, BufferGeometry, Vector3 } from 'three'
+
+import { traits } from '$lib/ecs'
+
+const MM_TO_M = 0.001
+
+/**
+ * A geometry's shape in its own frame, in metres, centred on that frame's origin. A mesh keeps
+ * its local bounds, which need not be centred.
+ */
+export type SnapShape =
+	| { kind: 'box'; halfSize: Vector3 }
+	| { kind: 'sphere'; radius: number }
+	| { kind: 'capsule'; radius: number; length: number }
+	| { kind: 'cylinder'; radius: number; length: number }
+	| { kind: 'mesh'; geometry: BufferGeometry; bounds: Box3 }
+
+/** The snap shape of an entity's geometry trait, or `undefined` when it has none. */
+export const snapShapeOf = (entity: Entity): SnapShape | undefined => {
+	const box = entity.get(traits.Box)
+	if (box) {
+		return {
+			kind: 'box',
+			halfSize: new Vector3(box.x, box.y, box.z).multiplyScalar(MM_TO_M / 2),
+		}
+	}
+
+	const sphere = entity.get(traits.Sphere)
+	if (sphere) return { kind: 'sphere', radius: sphere.r * MM_TO_M }
+
+	const capsule = entity.get(traits.Capsule)
+	if (capsule) {
+		return { kind: 'capsule', radius: capsule.r * MM_TO_M, length: capsule.l * MM_TO_M }
+	}
+
+	const cylinder = entity.get(traits.Cylinder)
+	if (cylinder) {
+		return { kind: 'cylinder', radius: cylinder.r * MM_TO_M, length: cylinder.l * MM_TO_M }
+	}
+
+	// A point cloud also stores its points as a `BufferGeometry`, but it has no surface.
+	if (entity.has(traits.Points)) return
+
+	const geometry = entity.get(traits.BufferGeometry)
+	if (!geometry || (geometry.getAttribute('position')?.count ?? 0) === 0) return
+
+	if (geometry.boundingBox === null) geometry.computeBoundingBox()
+	if (geometry.boundingBox === null) return
+
+	return { kind: 'mesh', geometry, bounds: geometry.boundingBox }
+}
diff --git a/src/lib/snapping/supportDistance.ts b/src/lib/snapping/supportDistance.ts
new file mode 100644
index 0000000000..7bafe930a1
--- /dev/null
+++ b/src/lib/snapping/supportDistance.ts
@@ -0,0 +1,57 @@
+import { type Matrix4, Vector3 } from 'three'
+
+import type { SnapShape } from './snapShape'
+
+const axisX = new Vector3()
+const axisY = new Vector3()
+const axisZ = new Vector3()
+const localCenter = new Vector3()
+const halfSize = new Vector3()
+
+/** Reads the basis that `supportDistance` extracted into `axisX`, `axisY`, `axisZ`. */
+const boxSupport = (half: Vector3, direction: Vector3): number =>
+	half.x * Math.abs(axisX.dot(direction)) +
+	half.y * Math.abs(axisY.dot(direction)) +
+	half.z * Math.abs(axisZ.dot(direction))
+
+/**
+ * How far a geometry reaches from its origin in `direction`: the largest `(p − origin) · direction`
+ * over every point `p` of the shape. Setting a shape down on a plane with normal `n` puts its
+ * origin `supportDistance(shape, matrix, −n)` above that plane.
+ *
+ * @param matrix The geometry's local-to-world transform, without scale.
+ * @param direction A unit vector in world space.
+ */
+export const supportDistance = (shape: SnapShape, matrix: Matrix4, direction: Vector3): number => {
+	matrix.extractBasis(axisX, axisY, axisZ)
+
+	switch (shape.kind) {
+		case 'box': {
+			return boxSupport(shape.halfSize, direction)
+		}
+		case 'mesh': {
+			shape.bounds.getCenter(localCenter)
+			shape.bounds.getSize(halfSize).multiplyScalar(0.5)
+			const centerReach =
+				localCenter.x * axisX.dot(direction) +
+				localCenter.y * axisY.dot(direction) +
+				localCenter.z * axisZ.dot(direction)
+			return centerReach + boxSupport(halfSize, direction)
+		}
+		case 'sphere': {
+			return shape.radius
+		}
+		case 'capsule': {
+			const segmentHalfLength = Math.max(0, shape.length / 2 - shape.radius)
+			return segmentHalfLength * Math.abs(axisZ.dot(direction)) + shape.radius
+		}
+		case 'cylinder': {
+			const alongAxis = Math.abs(axisZ.dot(direction))
+			const acrossAxis = Math.sqrt(Math.max(0, 1 - alongAxis * alongAxis))
+			return (shape.length / 2) * alongAxis + shape.radius * acrossAxis
+		}
+		default: {
+			return shape satisfies never
+		}
+	}
+}
diff --git a/src/lib/snapping/surfaceSnap.ts b/src/lib/snapping/surfaceSnap.ts
new file mode 100644
index 0000000000..7bf545a0b4
--- /dev/null
+++ b/src/lib/snapping/surfaceSnap.ts
@@ -0,0 +1,70 @@
+import { Matrix4, Quaternion, Vector3 } from 'three'
+
+import type { SnapQuery, SnapResult } from './snapQuery'
+
+import { alignUpToNormal } from './alignUpToNormal'
+import { constrainDelta } from './dragConstraint'
+import { nearestSurfaceHit } from './nearestSurfaceHit'
+import { supportDistance } from './supportDistance'
+
+// Below this, the constraint leaves almost none of the surface normal to move along, so reaching
+// the surface would fling the object far down the axis.
+const MIN_NORMAL_ALIGNMENT = 0.1
+
+const UNIT_SCALE = new Vector3(1, 1, 1)
+const geometryMatrix = new Matrix4()
+const geometryOrigin = new Vector3()
+const downward = new Vector3()
+
+/** How far the dragged geometries reach from the anchor in `direction`, taken together. */
+const reachFromAnchor = (query: SnapQuery, orientation: Quaternion, direction: Vector3): number => {
+	let reach = -Infinity
+
+	for (const { shape, anchorToGeometry } of query.dragged) {
+		geometryMatrix.compose(query.position, orientation, UNIT_SCALE).multiply(anchorToGeometry)
+		const originReach = geometryOrigin
+			.setFromMatrixPosition(geometryMatrix)
+			.sub(query.position)
+			.dot(direction)
+		reach = Math.max(reach, originReach + supportDistance(shape, geometryMatrix, direction))
+	}
+
+	return reach
+}
+
+/**
+ * Sets the dragged geometry down on the surface under the cursor, touching it without sinking in.
+ * Returns `null` when the entity has no geometry, the cursor is over no surface, or the drag
+ * constraint cannot move toward the surface.
+ */
+export const surfaceSnap = (query: SnapQuery): SnapResult | null => {
+	if (query.dragged.length === 0) return null
+
+	const hit = nearestSurfaceHit(query.ray, query.targets, query.groundPlane)
+	if (!hit) return null
+
+	const orientation = query.alignRotation
+		? alignUpToNormal(query.orientation, hit.normal, new Quaternion())
+		: query.orientation.clone()
+
+	const reach = reachFromAnchor(query, orientation, downward.copy(hit.normal).negate())
+	// How far the lowest point sits above the surface plane. Negative means sunk in.
+	const clearance = query.position.clone().sub(hit.point).dot(hit.normal) - reach
+
+	let delta: Vector3
+	if (query.constraint.kind === 'free') {
+		// Free drags land over the hit point, so the object follows the cursor across the surface.
+		delta = hit.point.clone().addScaledVector(hit.normal, reach).sub(query.position)
+	} else {
+		const direction = constrainDelta(hit.normal.clone(), query.constraint)
+		if (direction.length() < MIN_NORMAL_ALIGNMENT) return null
+		direction.normalize()
+		delta = direction.multiplyScalar(-clearance / direction.dot(hit.normal))
+	}
+
+	return {
+		position: query.position.clone().add(delta),
+		orientation,
+		indicator: { kind: 'surface', point: hit.point, normal: hit.normal },
+	}
+}
diff --git a/src/lib/snapping/useObjectSnapDrag.svelte.ts b/src/lib/snapping/useObjectSnapDrag.svelte.ts
new file mode 100644
index 0000000000..7b3b4ef9ba
--- /dev/null
+++ b/src/lib/snapping/useObjectSnapDrag.svelte.ts
@@ -0,0 +1,173 @@
+import type { Entity } from 'koota'
+
+import { useThrelte } from '@threlte/core'
+import { Matrix4, type Object3D, Quaternion, type Ray, Raycaster, Vector2, Vector3 } from 'three'
+
+import { useWorld } from '$lib/ecs'
+import { useSettings } from '$lib/hooks/useSettings.svelte'
+
+import { dragConstraintFor } from './dragConstraint'
+import { isVisibleTurn } from './isVisibleTurn'
+import { resolveSnap } from './resolveSnap'
+import { type SnapIndicator } from './snapQuery'
+import { posedTargets, type SnapScene, snapSceneFor } from './snapScene'
+
+const UNIT_SCALE = new Vector3(1, 1, 1)
+
+/** Object snapping for one translate gizmo, from pointer down to pointer up. */
+export interface ObjectSnapDrag {
+	/** Whether Ctrl or ⌘ is held mid-drag, flipping the snapping master switch. */
+	readonly isInverted: boolean
+	/** Where the current snap landed, for the scene to mark. */
+	readonly indicator: SnapIndicator | undefined
+	/**
+	 * Whether this drag has turned the object onto a surface. From then on staging writes
+	 * orientation, including the turn back when the object leaves the surface.
+	 */
+	readonly hasTurned: boolean
+	/** Whether a drag is between `begin` and `end`. */
+	readonly isDragging: boolean
+	/**
+	 * The anchor's orientation at `begin`. The anchor has to keep it for the whole drag, because
+	 * `TransformControls` in local space measures each move against the anchor's current
+	 * orientation but applies it along the one it had at pointer down.
+	 */
+	readonly startOrientation: Quaternion
+	/** The orientation to stage for the current move: the surface's under align, or the start's. */
+	readonly orientation: Quaternion
+	/** Gathers what the drag of `entity` snaps with and against. Call on pointer down. */
+	begin: (entity: Entity, anchor: Object3D) => void
+	/**
+	 * Moves `anchor`, already placed by the gizmo, onto the snap under the cursor. Leaves it where
+	 * it is when nothing is in reach. Never turns it. A turn lands in `orientation` instead.
+	 *
+	 * @param axis The gizmo handle being dragged, `TransformControls.axis`.
+	 */
+	apply: (anchor: Object3D, axis: string) => void
+	end: () => void
+}
+
+/**
+ * Object snapping for a translate gizmo: the key points and surfaces of other geometries, per the
+ * snap settings. Tracks the cursor itself, since `TransformControls` keeps its pointer private.
+ */
+export const useObjectSnapDrag = (): ObjectSnapDrag => {
+	const { camera, renderer } = useThrelte()
+	const world = useWorld()
+	const settings = useSettings()
+
+	let isInverted = $state(false)
+	let isDragging = $state(false)
+	let hasTurned = $state(false)
+	let indicator = $state.raw<SnapIndicator>()
+	let scene: SnapScene | undefined
+
+	const startOrientation = new Quaternion()
+	const orientation = new Quaternion()
+	const cursorPixels = new Vector2()
+	const cursorNdc = new Vector2()
+	const raycaster = new Raycaster()
+	const sightRaycaster = new Raycaster()
+	const projected = new Vector3()
+	const projectedNdc = new Vector2()
+	const anchorMatrix = new Matrix4()
+
+	const isSnappingObjects = () =>
+		settings.current.snapping !== isInverted && settings.current.snapObjects
+
+	const trackPointer = (event: PointerEvent) => {
+		const rect = renderer.domElement.getBoundingClientRect()
+		cursorPixels.set(event.clientX - rect.left, event.clientY - rect.top)
+		cursorNdc.set((cursorPixels.x / rect.width) * 2 - 1, 1 - (cursorPixels.y / rect.height) * 2)
+		if (scene) isInverted = event.ctrlKey || event.metaKey
+	}
+
+	// Capture phase, so the cursor is current before `TransformControls` handles the same move
+	// and fires the change that reads it.
+	$effect(() => {
+		window.addEventListener('pointermove', trackPointer, { capture: true })
+		return () => window.removeEventListener('pointermove', trackPointer, { capture: true })
+	})
+
+	const toScreen = (point: Vector3, out: Vector2): boolean => {
+		projected.copy(point).project(camera.current)
+		// Past the far plane, which is also where a perspective camera sends points behind it.
+		if (projected.z > 1) return false
+
+		const { clientWidth, clientHeight } = renderer.domElement
+		out.set(((projected.x + 1) / 2) * clientWidth, ((1 - projected.y) / 2) * clientHeight)
+		return true
+	}
+
+	// Through the point's pixel rather than from the camera's position, so an orthographic camera,
+	// whose rays are parallel, gets the right sight line too.
+	const rayThrough = (point: Vector3, out: Ray): Ray => {
+		projected.copy(point).project(camera.current)
+		sightRaycaster.setFromCamera(projectedNdc.set(projected.x, projected.y), camera.current)
+		return out.copy(sightRaycaster.ray)
+	}
+
+	return {
+		get isInverted() {
+			return isInverted
+		},
+		get indicator() {
+			return indicator
+		},
+		get hasTurned() {
+			return hasTurned
+		},
+		get isDragging() {
+			return isDragging
+		},
+		startOrientation,
+		orientation,
+		begin: (entity, anchor) => {
+			isDragging = true
+			hasTurned = false
+			startOrientation.copy(anchor.quaternion)
+			orientation.copy(startOrientation)
+			anchorMatrix.compose(anchor.position, anchor.quaternion, UNIT_SCALE)
+			scene = snapSceneFor(world, entity, anchorMatrix)
+		},
+		apply: (anchor, axis) => {
+			indicator = undefined
+			orientation.copy(startOrientation)
+			if (!scene) return
+
+			if (isSnappingObjects()) {
+				raycaster.setFromCamera(cursorNdc, camera.current)
+				const result = resolveSnap({
+					position: anchor.position.clone(),
+					orientation: startOrientation,
+					dragged: scene.dragged,
+					targets: posedTargets(scene.targets),
+					constraint: dragConstraintFor(axis, settings.current.transformSpace, startOrientation),
+					ray: raycaster.ray,
+					cursor: cursorPixels,
+					toScreen,
+					rayThrough,
+					groundPlane: settings.current.snapGroundPlane,
+					alignRotation: settings.current.snapAlignRotation,
+				})
+
+				if (result) {
+					anchor.position.copy(result.position)
+					orientation.copy(result.orientation)
+					// Staging an unturned orientation would only write rounding noise into the config.
+					if (isVisibleTurn(startOrientation, orientation)) hasTurned = true
+					indicator = result.indicator
+				}
+			}
+
+			anchor.updateMatrixWorld()
+		},
+		end: () => {
+			isDragging = false
+			hasTurned = false
+			scene = undefined
+			indicator = undefined
+			isInverted = false
+		},
+	}
+}