diff --git a/.changeset/cuddly-sails-attend.md b/.changeset/cuddly-sails-attend.md
new file mode 100644
index 000000000..013a2eb37
--- /dev/null
+++ b/.changeset/cuddly-sails-attend.md
@@ -0,0 +1,5 @@
+---
+"@viamrobotics/motion-tools": patch
+---
+
+Feat: force directed graph labels
diff --git a/eslint.config.js b/eslint.config.js
index dd2bd68b0..b5ffbec77 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -123,6 +123,7 @@ export default defineConfig(
 			'unicorn/prefer-add-event-listener': 'off',
 			'unicorn/prefer-blob-reading-methods': 'off',
 			'unicorn/prefer-code-point': 'off',
+			'unicorn/prefer-modern-math-apis': 'off',
 			'unicorn/prefer-string-replace-all': 'error',
 			'unicorn/prefer-switch': 'off',
 			'unicorn/prefer-top-level-await': 'off',
diff --git a/package.json b/package.json
index c3bcbd53a..2c7f92ed2 100644
--- a/package.json
+++ b/package.json
@@ -67,6 +67,7 @@
 		"@threlte/rapier": "3.4.1",
 		"@threlte/xr": "1.6.0",
 		"@types/bun": "1.2.21",
+		"@types/d3-force": "^3.0.10",
 		"@types/earcut": "^3.0.0",
 		"@types/lodash-es": "4.17.12",
 		"@types/node": "^25.6.0",
@@ -209,6 +210,7 @@
 	"dependencies": {
 		"@bufbuild/protobuf": "1.10.1",
 		"@neodrag/svelte": "^2.3.3",
+		"d3-force": "^3.0.0",
 		"filtrex": "^3.1.0",
 		"koota": "0.6.5",
 		"lodash-es": "4.18.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a947c765f..ee000199e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21,6 +21,9 @@ importers:
       '@zag-js/dialog':
         specifier: '>=1.31'
         version: 1.32.0
+      d3-force:
+        specifier: ^3.0.0
+        version: 3.0.0
       filtrex:
         specifier: ^3.1.0
         version: 3.1.0
@@ -121,6 +124,9 @@ importers:
       '@types/bun':
         specifier: 1.2.21
         version: 1.2.21(@types/react@19.2.2)
+      '@types/d3-force':
+        specifier: ^3.0.10
+        version: 3.0.10
       '@types/earcut':
         specifier: ^3.0.0
         version: 3.0.0
@@ -1787,6 +1793,9 @@ packages:
   '@types/cookie@0.6.0':
     resolution: {integrity: sha512-4Kh9a6B2bQciAhf7FSuMRRkUWecJgJu9nPnx3yzpsfXX/c50REIqpHY4C82bXP90qrLtXtkDxTZosYO3UpOwlA==}
 
+  '@types/d3-force@3.0.10':
+    resolution: {integrity: sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==}
+
   '@types/deep-eql@4.0.2':
     resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
 
@@ -2458,6 +2467,22 @@ packages:
   csstype@3.2.3:
     resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
 
+  d3-dispatch@3.0.1:
+    resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
+    engines: {node: '>=12'}
+
+  d3-force@3.0.0:
+    resolution: {integrity: sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==}
+    engines: {node: '>=12'}
+
+  d3-quadtree@3.0.1:
+    resolution: {integrity: sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==}
+    engines: {node: '>=12'}
+
+  d3-timer@3.0.1:
+    resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
+    engines: {node: '>=12'}
+
   data-urls@5.0.0:
     resolution: {integrity: sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg==}
     engines: {node: '>=18'}
@@ -5858,6 +5883,8 @@ snapshots:
 
   '@types/cookie@0.6.0': {}
 
+  '@types/d3-force@3.0.10': {}
+
   '@types/deep-eql@4.0.2': {}
 
   '@types/earcut@3.0.0': {}
@@ -6750,6 +6777,18 @@ snapshots:
 
   csstype@3.2.3: {}
 
+  d3-dispatch@3.0.1: {}
+
+  d3-force@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-timer: 3.0.1
+
+  d3-quadtree@3.0.1: {}
+
+  d3-timer@3.0.1: {}
+
   data-urls@5.0.0:
     dependencies:
       whatwg-mimetype: 4.0.0
diff --git a/src/lib/components/Entities/Entities.svelte b/src/lib/components/Entities/Entities.svelte
index 55108e44e..95ae41608 100644
--- a/src/lib/components/Entities/Entities.svelte
+++ b/src/lib/components/Entities/Entities.svelte
@@ -2,12 +2,13 @@
 	import { Not, Or } from 'koota'
 
 	import { traits, useQuery } from '$lib/ecs'
+	import { useSettings } from '$lib/hooks/useSettings.svelte'
 
 	import Arrows from './Arrows/ArrowGroups.svelte'
 	import Frame from './Frame.svelte'
 	import Geometry from './Geometry.svelte'
 	import GLTF from './GLTF.svelte'
-	import Label from './Label.svelte'
+	import Labels from './Labels.svelte'
 	import Line from './Line.svelte'
 	import Points from './Points.svelte'
 	import Pose from './Pose.svelte'
@@ -60,56 +61,48 @@
 	const points = useQuery(traits.Points)
 	const lines = useQuery(traits.LinePositions)
 	const gltfs = useQuery(traits.GLTF)
+
+	const settings = useSettings()
+
+	const enableLabels = $derived(settings.current.enableLabels)
 </script>
 
 {#each machineFramesEntities.current as entity (entity)}
 	<Pose {entity}>
-		<Frame {entity}>
-			<Label text={entity.get(traits.Name)} />
-		</Frame>
+		<Frame {entity} />
 	</Pose>
 {/each}
 
 {#each resourceGeometriesEntities.current as entity (entity)}
-	<Geometry {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</Geometry>
+	<Geometry {entity} />
 {/each}
 
 {#each worldStateEntities.current as entity (entity)}
-	<Frame {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</Frame>
+	<Frame {entity} />
 {/each}
 
 {#each drawServiceEntities.current as entity (entity)}
-	<Frame {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</Frame>
+	<Frame {entity} />
 {/each}
 
 {#each meshEntities.current as entity (entity)}
-	<Frame {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</Frame>
+	<Frame {entity} />
 {/each}
 
 {#each points.current as entity (entity)}
-	<Points {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</Points>
+	<Points {entity} />
 {/each}
 
 {#each lines.current as entity (entity)}
-	<Line {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</Line>
+	<Line {entity} />
 {/each}
 
 {#each gltfs.current as entity (entity)}
-	<GLTF {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</GLTF>
+	<GLTF {entity} />
 {/each}
 
 <Arrows />
+
+{#if enableLabels}
+	<Labels />
+{/if}
diff --git a/src/lib/components/Entities/Label.svelte b/src/lib/components/Entities/Label.svelte
index 6f67362c8..beac19830 100644
--- a/src/lib/components/Entities/Label.svelte
+++ b/src/lib/components/Entities/Label.svelte
@@ -1,25 +1,91 @@
 <script lang="ts">
+	import type { Entity } from 'koota'
+
+	import { useThrelte } from '@threlte/core'
 	import { HTML } from '@threlte/extras'
+	import { untrack } from 'svelte'
+	import { Group } from 'three'
+
+	import { traits, useTag, useTrait } from '$lib/ecs'
 
-	import { useSettings } from '$lib/hooks/useSettings.svelte'
+	import { labels } from './labelLayout/labelStore.svelte'
 
 	interface Props {
-		text?: string
+		entity: Entity
 	}
 
-	let { text }: Props = $props()
+	let { entity }: Props = $props()
+
+	const { invalidate } = useThrelte()
+
+	const matrix = useTrait(() => entity, traits.WorldMatrix)
+	const name = useTrait(() => entity, traits.Name)
+	const color = useTrait(() => entity, traits.Color)
+	const selected = useTag(() => entity, traits.Selected)
+
+	let element = $state.raw<HTMLElement>()
+
+	$effect(() => {
+		const el = element
+
+		if (!el) return
+
+		return untrack(() => {
+			labels.add(el)
+			return () => labels.remove(el)
+		})
+	})
+
+	// Re-measure when the label text changes (its width drives slot geometry).
+	$effect(() => {
+		if (name.current) {
+			untrack(() => labels.touch())
+		}
+	})
 
-	const settings = useSettings()
+	let ref = $state<Group>()
 
-	const labels = $derived(settings.current.enableLabels)
+	$effect(() => {
+		if (matrix.current && ref) {
+			ref.matrix.copy(matrix.current)
+			ref.updateMatrixWorld()
+			invalidate()
+		}
+	})
 </script>
 
-{#if labels && text}
-	<HTML
-		center
-		zIndexRange={[3, 0]}
-		class="border-gray-7 border bg-white px-2 py-1 text-xs"
+<HTML
+	center
+	zIndexRange={[3, 0]}
+	matrixAutoUpdate={false}
+	bind:ref
+>
+	<div
+		class="label relative h-0 w-0"
+		bind:this={element}
 	>
-		{text}
-	</HTML>
-{/if}
+		<svg class="link pointer-events-none absolute top-0 left-0 overflow-visible">
+			<line class="stroke-gray-9 stroke-1" />
+		</svg>
+		<div
+			class="dot border-gray-9 pointer-events-none absolute -top-1 -left-0 z-1 h-2 w-2 -translate-1/2 rounded-full border"
+		></div>
+		<button
+			class={[
+				'border-gray-9 text absolute z-2 border px-2 py-1 text-xs text-nowrap',
+				{
+					'bg-gray-9 text-white': selected.current,
+					'bg-white': !selected.current,
+				},
+			]}
+			style={color.current
+				? `border-color-left: rgb(${color.current.r}, ${color.current.g}, ${color.current.b})`
+				: undefined}
+			onclick={() => {
+				entity.add(traits.Selected)
+			}}
+		>
+			{name.current}
+		</button>
+	</div>
+</HTML>
diff --git a/src/lib/components/Entities/Labels.svelte b/src/lib/components/Entities/Labels.svelte
new file mode 100644
index 000000000..a35a69711
--- /dev/null
+++ b/src/lib/components/Entities/Labels.svelte
@@ -0,0 +1,36 @@
+<script lang="ts">
+	import { useTask, useThrelte } from '@threlte/core'
+
+	import { traits, useQuery } from '$lib/ecs'
+
+	import Label from './Label.svelte'
+	import { createLabelLayout } from './labelLayout/createLabelLayout'
+	import { labels } from './labelLayout/labelStore.svelte'
+
+	const { camera, invalidate, size } = useThrelte()
+
+	const entities = useQuery(traits.Name)
+
+	const layout = createLabelLayout({ camera, size, invalidate, labels })
+
+	// Wake the on-demand render loop when labels are added/removed or their text
+	// changes, so the engine re-solves even while the camera is still. Reading
+	// `version` registers the reactive dependency.
+	$effect(() => {
+		if (labels.version >= 0) invalidate()
+	})
+
+	// `autoInvalidate: false` — the engine drives its own invalidation (camera
+	// motion, the version effect above, and while animating), so the task can run
+	// without pinning the on-demand Canvas to render every frame.
+	useTask(
+		(delta) => {
+			layout.frame(delta)
+		},
+		{ autoInvalidate: false }
+	)
+</script>
+
+{#each entities.current as entity (entity)}
+	<Label {entity} />
+{/each}
diff --git a/src/lib/components/Entities/labelLayout/__tests__/geometry.spec.ts b/src/lib/components/Entities/labelLayout/__tests__/geometry.spec.ts
new file mode 100644
index 000000000..ad67e5129
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/__tests__/geometry.spec.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Rect, Segment } from '../types'
+
+import {
+	overlapAreaFrac,
+	rectCircleOverlap,
+	rectsOverlap,
+	segmentRectPenetration,
+	segmentsCross,
+} from '../geometry'
+
+const rect = (cx: number, cy: number, hw: number, hh: number): Rect => ({ cx, cy, hw, hh })
+const seg = (x1: number, y1: number, x2: number, y2: number): Segment => ({ x1, y1, x2, y2 })
+
+describe('rectsOverlap', () => {
+	it('detects overlap and respects padding', () => {
+		expect(rectsOverlap(rect(0, 0, 2, 2), rect(3, 0, 2, 2))).toBe(true)
+		expect(rectsOverlap(rect(0, 0, 2, 2), rect(5, 0, 2, 2))).toBe(false)
+		expect(rectsOverlap(rect(0, 0, 2, 2), rect(5, 0, 2, 2), 2)).toBe(true)
+	})
+})
+
+describe('overlapAreaFrac', () => {
+	it('is 0 when disjoint and 1 when one contains the other', () => {
+		expect(overlapAreaFrac(rect(0, 0, 2, 2), rect(10, 0, 2, 2))).toBe(0)
+		expect(overlapAreaFrac(rect(0, 0, 5, 5), rect(0, 0, 1, 1))).toBeCloseTo(1)
+	})
+})
+
+describe('segmentRectPenetration', () => {
+	const r = rect(0, 0, 2, 2)
+
+	it('is 0 when the segment misses the rect', () => {
+		expect(segmentRectPenetration(seg(-10, -10, -8, -10), r)).toBe(0)
+	})
+
+	it('is 1 when the segment is fully inside', () => {
+		expect(segmentRectPenetration(seg(-1, 0, 1, 0), r)).toBeCloseTo(1)
+	})
+
+	it('is the clipped fraction when crossing through', () => {
+		// 20px segment, 4px (x in [-2,2]) inside → 0.2.
+		expect(segmentRectPenetration(seg(-10, 0, 10, 0), r)).toBeCloseTo(0.2)
+	})
+
+	it('is positive from an endpoint inside the rect', () => {
+		expect(segmentRectPenetration(seg(0, 0, 20, 0), r)).toBeGreaterThan(0)
+	})
+})
+
+describe('segmentsCross', () => {
+	it('detects a proper crossing', () => {
+		expect(segmentsCross(seg(0, 0, 2, 2), seg(0, 2, 2, 0))).toBe(true)
+	})
+
+	it('excludes shared endpoints and parallel lines', () => {
+		expect(segmentsCross(seg(0, 0, 2, 2), seg(0, 0, 2, -2))).toBe(false)
+		expect(segmentsCross(seg(0, 0, 2, 0), seg(0, 1, 2, 1))).toBe(false)
+	})
+})
+
+describe('rectCircleOverlap', () => {
+	const r = rect(0, 0, 2, 2)
+
+	it('is 0 when the circle is clear of the rect', () => {
+		expect(rectCircleOverlap(r, 5, 0, 1)).toBe(0)
+	})
+
+	it('is the penetration depth when the circle reaches in', () => {
+		expect(rectCircleOverlap(r, 2.5, 0, 1)).toBeCloseTo(0.5)
+	})
+})
diff --git a/src/lib/components/Entities/labelLayout/__tests__/slots.spec.ts b/src/lib/components/Entities/labelLayout/__tests__/slots.spec.ts
new file mode 100644
index 000000000..9036a2d4f
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/__tests__/slots.spec.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+
+import { rectCircleOverlap } from '../geometry'
+import { generateSlots, hashString } from '../slots'
+import { defaultSolverConfig, type LabelNode } from '../types'
+
+function node(w: number, h: number, dotR: number, id = 'label'): LabelNode {
+	return { w, h, dotR, idHash: hashString(id) } as unknown as LabelNode
+}
+
+describe('hashString', () => {
+	it('is deterministic and unsigned', () => {
+		expect(hashString('frame-a')).toBe(hashString('frame-a'))
+		expect(hashString('frame-a')).not.toBe(hashString('frame-b'))
+		expect(hashString('x')).toBeGreaterThanOrEqual(0)
+	})
+})
+
+describe('generateSlots', () => {
+	const config = defaultSolverConfig
+
+	it('produces angles × rings slots, more when crowded', () => {
+		const sparse = generateSlots(node(40, 16, 4), false, config)
+		expect(sparse.length).toBe(config.anglesPerRing * config.ringRadii.length)
+
+		const crowded = generateSlots(node(40, 16, 4), true, config)
+		expect(crowded.length).toBe(config.anglesPerRing * 2 * config.ringRadiiCrowded.length)
+	})
+
+	it('sorts slots ascending by baseCost', () => {
+		const slots = generateSlots(node(40, 16, 4), false, config)
+		for (let i = 1; i < slots.length; i++) {
+			expect(slots[i].baseCost).toBeGreaterThanOrEqual(slots[i - 1].baseCost)
+		}
+	})
+
+	it('never lets a box overlap its own dot at any angle', () => {
+		// Slots are dot-relative, so the dot sits at the origin.
+		for (const [w, h, dotR] of [
+			[40, 16, 4],
+			[80, 12, 3],
+			[10, 10, 6],
+		]) {
+			for (const crowded of [false, true]) {
+				for (const s of generateSlots(node(w, h, dotR), crowded, config)) {
+					const box = { cx: s.dx, cy: s.dy, hw: w / 2, hh: h / 2 }
+					expect(rectCircleOverlap(box, 0, 0, dotR)).toBe(0)
+				}
+			}
+		}
+	})
+})
diff --git a/src/lib/components/Entities/labelLayout/__tests__/solve.spec.ts b/src/lib/components/Entities/labelLayout/__tests__/solve.spec.ts
new file mode 100644
index 000000000..5362cacde
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/__tests__/solve.spec.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest'
+
+import { rectsOverlap, segmentRectPenetration } from '../geometry'
+import { generateSlots, hashString } from '../slots'
+import { solve } from '../solve'
+import { defaultSolverConfig, type LabelNode, type Rect, type Segment } from '../types'
+
+const config = defaultSolverConfig
+
+function makeNode(id: string, ax: number, ay: number, w = 30, h = 14, dotR = 3): LabelNode {
+	const node: LabelNode = {
+		id,
+		idHash: hashString(id),
+		ax,
+		ay,
+		dotR,
+		w,
+		h,
+		scale: 1,
+		cssDotW: 8,
+		dotLocalX: 0,
+		dotLocalY: 0,
+		slots: [],
+		geomKey: '',
+		crowded: false,
+		slotIndex: 0,
+		prevSlotIndex: 0,
+		cx: ax,
+		cy: ay,
+		tx: 0,
+		ty: 0,
+		settled: false,
+		conflict: 0,
+		locked: false,
+		centroidX: ax,
+		centroidY: ay,
+		prevAx: Number.NaN,
+		prevAy: Number.NaN,
+		neighbors: [],
+		labelEl: null as unknown as HTMLElement,
+		textEl: null as unknown as HTMLElement,
+		dotEl: null as unknown as HTMLElement,
+		lineEl: null as unknown as SVGLineElement,
+	}
+	node.slots = generateSlots(node, false, config)
+	return node
+}
+
+/** Wire up a closed scene: every node neighbors every other, shared centroid. */
+function link(nodes: LabelNode[]) {
+	let sx = 0
+	let sy = 0
+	for (const n of nodes) {
+		sx += n.ax
+		sy += n.ay
+	}
+	const cx = sx / nodes.length
+	const cy = sy / nodes.length
+	for (const n of nodes) {
+		n.neighbors = nodes.filter((other) => other !== n)
+		n.centroidX = cx
+		n.centroidY = cy
+	}
+}
+
+function leader(n: LabelNode): Segment {
+	return { x1: n.ax, y1: n.ay, x2: n.tx, y2: n.ty }
+}
+
+function paddedBox(n: LabelNode): Rect {
+	return {
+		cx: n.tx,
+		cy: n.ty,
+		hw: n.w / 2 + config.labelPadding / 2,
+		hh: n.h / 2 + config.labelPadding / 2,
+	}
+}
+
+function box(n: LabelNode): Rect {
+	return { cx: n.tx, cy: n.ty, hw: n.w / 2, hh: n.h / 2 }
+}
+
+describe('solve', () => {
+	it('leaves a lone label at a valid slot with no conflict', () => {
+		const n = makeNode('solo', 100, 100)
+		solve([n], config, new Int16Array(1))
+		expect(n.slotIndex).toBeGreaterThanOrEqual(0)
+		expect(n.slotIndex).toBeLessThan(n.slots.length)
+		expect(n.conflict).toBe(0)
+	})
+
+	it('produces no leader-under-box crossings for a feasible row of labels', () => {
+		const nodes = [makeNode('a', 0, 0), makeNode('b', 70, 0), makeNode('c', 140, 0)]
+		link(nodes)
+		solve(nodes, config, new Int16Array(nodes.length))
+
+		for (const a of nodes) {
+			for (const b of nodes) {
+				if (a === b) continue
+				expect(segmentRectPenetration(leader(a), paddedBox(b))).toBe(0)
+			}
+		}
+	})
+
+	it('drives leader-under-box crossings to zero for a feasible cluster', () => {
+		// A 2D cluster with room to fan outward — the hard #1 requirement must hold,
+		// and (post objective-alignment fix) resolvable crossings must not be left
+		// locked in favour of a tidier-but-conflicting slot.
+		const nodes = [
+			makeNode('a', 0, 0),
+			makeNode('b', 130, 0),
+			makeNode('c', 0, 120),
+			makeNode('d', 130, 120),
+			makeNode('e', 65, 60),
+			makeNode('f', 240, 60),
+		]
+		link(nodes)
+		solve(nodes, config, new Int16Array(nodes.length))
+
+		for (const a of nodes) {
+			for (const b of nodes) {
+				if (a === b) continue
+				expect(segmentRectPenetration(leader(a), paddedBox(b))).toBe(0)
+			}
+		}
+	})
+
+	it('separates label boxes that would otherwise overlap', () => {
+		const nodes = [makeNode('a', 0, 0), makeNode('b', 20, 0), makeNode('c', 40, 0)]
+		link(nodes)
+		solve(nodes, config, new Int16Array(nodes.length))
+
+		for (let i = 0; i < nodes.length; i++) {
+			for (let j = i + 1; j < nodes.length; j++) {
+				expect(rectsOverlap(box(nodes[i]), box(nodes[j]), config.labelPadding)).toBe(false)
+			}
+		}
+	})
+
+	it('is deterministic across identical fresh solves', () => {
+		const build = () => {
+			const nodes = [makeNode('a', 0, 0), makeNode('b', 60, 10), makeNode('c', 30, 55)]
+			link(nodes)
+			solve(nodes, config, new Int16Array(nodes.length))
+			return nodes.map((n) => n.slotIndex)
+		}
+		expect(build()).toEqual(build())
+	})
+})
diff --git a/src/lib/components/Entities/labelLayout/applyTeleports.ts b/src/lib/components/Entities/labelLayout/applyTeleports.ts
new file mode 100644
index 000000000..bc0010369
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/applyTeleports.ts
@@ -0,0 +1,49 @@
+/**
+ * Post-solve teleport handling: decides which nodes snap to their solved target
+ * this frame versus ease toward it. A big camera jump (large median anchor
+ * displacement) or a brand-new node (no prior anchor) places labels in their
+ * final spot rather than gliding across the screen; everything else eases.
+ * Always rolls each node's prevAx/prevAy forward for the next solve's comparison.
+ */
+
+import type { LabelNode, SolverConfig } from './types'
+
+/** The radius of a node's outermost slot (0 if it has none). */
+const maxSlotRadius = (node: LabelNode): number => {
+	const last = node.slots.at(-1)
+	return last ? last.radius : 0
+}
+
+export const applyTeleports = (
+	nodes: LabelNode[],
+	width: number,
+	height: number,
+	config: SolverConfig
+): void => {
+	const diag = Math.hypot(width, height)
+	const displacements: number[] = []
+	for (const node of nodes) {
+		if (!Number.isNaN(node.prevAx)) {
+			displacements.push(Math.hypot(node.ax - node.prevAx, node.ay - node.prevAy))
+		}
+	}
+	let snapAll = displacements.length === 0
+	if (!snapAll) {
+		displacements.sort((a, b) => a - b)
+		const median = displacements[displacements.length >> 1]
+		if (median > config.teleportFrac * diag) snapAll = true
+	}
+
+	for (const node of nodes) {
+		const ownJump =
+			!Number.isNaN(node.prevAx) &&
+			Math.hypot(node.ax - node.prevAx, node.ay - node.prevAy) > maxSlotRadius(node) * 3
+		if (snapAll || ownJump) {
+			node.cx = node.tx
+			node.cy = node.ty
+			node.settled = true
+		}
+		node.prevAx = node.ax
+		node.prevAy = node.ay
+	}
+}
diff --git a/src/lib/components/Entities/labelLayout/buildNeighborhood.ts b/src/lib/components/Entities/labelLayout/buildNeighborhood.ts
new file mode 100644
index 000000000..49f88f593
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/buildNeighborhood.ts
@@ -0,0 +1,34 @@
+/**
+ * Builds each node's pruned, symmetric interaction set for one solve. The cell
+ * size is chosen so any two labels whose boxes could possibly interact share or
+ * border a cell, so the 3x3 query around each node finds every candidate.
+ */
+
+import type { SpatialHash } from './spatialHash'
+import type { LabelNode, SolverConfig } from './types'
+
+export const buildNeighborhood = (
+	grid: SpatialHash,
+	nodes: LabelNode[],
+	config: SolverConfig
+): void => {
+	const maxRingMult = Math.max(...config.ringRadiiCrowded)
+
+	// Cell size so any two labels whose boxes could interact share/border a cell.
+	let cell = 1
+	for (const node of nodes) {
+		const halfDiag = Math.hypot(node.w / 2, node.h / 2)
+		const support = Math.max(node.w, node.h) / 2
+		const outer = (support + node.dotR + config.dotPadding) * maxRingMult
+		cell = Math.max(cell, 2 * (halfDiag + outer))
+	}
+	grid.build(nodes, cell)
+
+	// Symmetric neighbourhoods so the solver's incremental bookkeeping stays exact.
+	for (const node of nodes) node.neighbors = grid.queryNeighbors(node, config.maxNeighbors)
+	for (const a of nodes) {
+		for (const b of a.neighbors) {
+			if (!b.neighbors.includes(a)) b.neighbors.push(a)
+		}
+	}
+}
diff --git a/src/lib/components/Entities/labelLayout/cameraHash.ts b/src/lib/components/Entities/labelLayout/cameraHash.ts
new file mode 100644
index 000000000..6ee38c2ec
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/cameraHash.ts
@@ -0,0 +1,29 @@
+/**
+ * A cheap, exact change-signal for the camera. Hashing the view + projection
+ * matrices (as raw float bits) plus the viewport size catches every pan, orbit,
+ * dolly, zoom, resize, and perspective/orthographic swap with no epsilon to tune.
+ * Computed every frame; the layout only re-solves when the hash changes.
+ */
+
+import type { Camera } from 'three'
+
+const f32 = new Float32Array(1)
+const i32 = new Int32Array(f32.buffer)
+
+function bits(value: number): number {
+	f32[0] = value
+	return i32[0]
+}
+
+export function cameraMatrixHash(camera: Camera, width: number, height: number): number {
+	camera.updateMatrixWorld()
+	const view = camera.matrixWorldInverse.elements
+	const proj = camera.projectionMatrix.elements
+
+	let h = 2166136261 >>> 0
+	for (let i = 0; i < 16; i++) h = Math.imul(h ^ bits(view[i]), 16777619) >>> 0
+	for (let i = 0; i < 16; i++) h = Math.imul(h ^ bits(proj[i]), 16777619) >>> 0
+	h = Math.imul(h ^ bits(width), 16777619) >>> 0
+	h = Math.imul(h ^ bits(height), 16777619) >>> 0
+	return h >>> 0
+}
diff --git a/src/lib/components/Entities/labelLayout/cost.ts b/src/lib/components/Entities/labelLayout/cost.ts
new file mode 100644
index 000000000..b4b11b302
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/cost.ts
@@ -0,0 +1,152 @@
+/**
+ * Cost function for a candidate label placement. Lower is better.
+ *
+ * The hierarchy `lineBox >> boxDot > boxBox > lineLine >> stick > spread > len`
+ * is near-lexicographic: a single leader passing under another label always
+ * outranks fixing every overlap a node could have against its <=24 neighbors,
+ * so the optimizer eliminates crossings first (the user's top priority), then
+ * dot coverage, then box overlaps, then tidies the radial fan.
+ */
+
+import type { LabelNode, Rect, Segment, SolverConfig } from './types'
+
+import {
+	overlapAreaFrac,
+	rectCircleOverlap,
+	rectsOverlap,
+	segmentRectPenetration,
+	segmentsCross,
+} from './geometry'
+
+export const W = {
+	/** DOMINANT — a leader passing under ANOTHER label's box. Requirement #1. */
+	lineBox: 1000,
+	/** Our box covering another node's dot. Worse than a box overlap. Requirement #4. */
+	boxDot: 200,
+	/** Two label boxes overlapping. Requirement #2. */
+	boxBox: 120,
+	/** Two leaders crossing — thin lines, mild. Supports the radial fan. */
+	lineLine: 60,
+	/** Sticky bonus for staying on the previous slot (anti flip-flop). Requirement #6. */
+	stick: 35,
+	/** Penalty when a slot's angle nearly coincides with a neighbor's leader angle. */
+	spread: 15,
+	/** Outward-fan preference: cheaper to point away from the local cluster. Requirement #3. */
+	radial: 0.8,
+	/** Leader length — keep labels close to their dot. Small. */
+	len: 0.6,
+}
+
+/** Slot angles closer than this (radians, ~18deg) are penalised for an even fan. */
+const SPREAD_ANGLE = 0.314
+
+// Reused scratch — the solver is single-threaded and never re-enters evalConflict.
+const boxA: Rect = { cx: 0, cy: 0, hw: 0, hh: 0 }
+const boxB: Rect = { cx: 0, cy: 0, hw: 0, hh: 0 }
+const boxPad: Rect = { cx: 0, cy: 0, hw: 0, hh: 0 }
+const segA: Segment = { x1: 0, y1: 0, x2: 0, y2: 0 }
+const segB: Segment = { x1: 0, y1: 0, x2: 0, y2: 0 }
+
+/**
+ * The geometric "bad" terms only (leader-under-box, box-over-dot, box-box,
+ * leader-leader, angular spread) for placing `node` at slot `si` against its
+ * committed neighbors. This is the local-search objective AND its termination
+ * guard — exactly 0 when the node has no crossings/overlaps. The solver both
+ * selects and accepts moves on this value so it can never lock a node at a
+ * placement whose conflict another available slot would reduce.
+ */
+export function evalConflict(
+	node: LabelNode,
+	si: number,
+	neighbors: LabelNode[],
+	config: SolverConfig
+): number {
+	const s = node.slots[si]
+	const cx = node.ax + s.dx
+	const cy = node.ay + s.dy
+
+	boxA.cx = cx
+	boxA.cy = cy
+	boxA.hw = node.w / 2
+	boxA.hh = node.h / 2
+	segA.x1 = node.ax
+	segA.y1 = node.ay
+	segA.x2 = cx
+	segA.y2 = cy
+
+	const halfPad = config.labelPadding / 2
+	let cost = 0
+
+	for (let t = 0; t < neighbors.length; t++) {
+		const m = neighbors[t]
+		const ms = m.slots[m.slotIndex]
+		const mx = m.ax + ms.dx
+		const my = m.ay + ms.dy
+
+		boxB.cx = mx
+		boxB.cy = my
+		boxB.hw = m.w / 2
+		boxB.hh = m.h / 2
+		segB.x1 = m.ax
+		segB.y1 = m.ay
+		segB.x2 = mx
+		segB.y2 = my
+
+		// Our leader under their box (expanded so a grazing line still reads as a crossing).
+		boxPad.cx = mx
+		boxPad.cy = my
+		boxPad.hw = m.w / 2 + halfPad
+		boxPad.hh = m.h / 2 + halfPad
+		const p1 = segmentRectPenetration(segA, boxPad)
+		if (p1 > 0) cost += W.lineBox * p1
+
+		// Their leader under our box.
+		boxPad.cx = cx
+		boxPad.cy = cy
+		boxPad.hw = node.w / 2 + halfPad
+		boxPad.hh = node.h / 2 + halfPad
+		const p2 = segmentRectPenetration(segB, boxPad)
+		if (p2 > 0) cost += W.lineBox * p2
+
+		// Our box covering their dot.
+		const dotClearance = m.dotR + config.dotPadding
+		const d = rectCircleOverlap(boxA, m.ax, m.ay, dotClearance)
+		if (d > 0) cost += W.boxDot * (d / dotClearance)
+
+		// Box-box overlap (binary dominates; area term provides a separation gradient).
+		if (rectsOverlap(boxA, boxB, config.labelPadding)) {
+			cost += W.boxBox + 2 * overlapAreaFrac(boxA, boxB)
+		}
+
+		// Leader-leader crossing.
+		if (segmentsCross(segA, segB)) cost += W.lineLine
+
+		// Angular spread for an even fan.
+		let dd = Math.abs(s.angle - ms.angle)
+		if (dd > Math.PI) dd = 2 * Math.PI - dd
+		if (dd < SPREAD_ANGLE) cost += W.spread
+	}
+
+	return cost
+}
+
+/**
+ * Conflict-independent "tidiness" of a slot: short leaders, pointing away from
+ * the local cluster centroid (radial fan-out), with a bonus for staying put.
+ * Used only as a tie-break among slots of equal conflict, never to override a
+ * conflict reduction.
+ */
+export function placementBias(node: LabelNode, si: number): number {
+	const s = node.slots[si]
+	let cost = W.len * s.radius
+
+	const cax = node.centroidX - node.ax
+	const cay = node.centroidY - node.ay
+	const cl = Math.sqrt(cax * cax + cay * cay) || 1
+	const align = (Math.cos(s.angle) * -cax + Math.sin(s.angle) * -cay) / cl
+	cost += W.radial * (1 - align) * s.radius
+
+	if (si === node.prevSlotIndex) cost -= W.stick
+
+	return cost
+}
diff --git a/src/lib/components/Entities/labelLayout/createLabelLayout.ts b/src/lib/components/Entities/labelLayout/createLabelLayout.ts
new file mode 100644
index 000000000..646d951e7
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/createLabelLayout.ts
@@ -0,0 +1,224 @@
+/**
+ * The label layout engine. Owns node lifecycle and the per-frame pipeline:
+ * a cheap dirty gate, then (only when dirty) measure → build neighbourhood →
+ * warm-start → solve → handle teleports, and every animating frame ease toward
+ * the solved targets and write them to the DOM. It idles (no work, no
+ * invalidate) once the camera is still and every label has settled.
+ */
+
+import type { Camera } from 'three'
+
+import type { LabelStore } from './labelStore.svelte'
+
+import { applyTeleports } from './applyTeleports'
+import { buildNeighborhood } from './buildNeighborhood'
+import { cameraMatrixHash } from './cameraHash'
+import { measureNode } from './measure'
+import { generateSlots, hashString } from './slots'
+import { solve } from './solve'
+import { SpatialHash } from './spatialHash'
+import { defaultSolverConfig, type LabelNode, type SolverConfig } from './types'
+import { lerpStep, writeBack } from './writeBack'
+
+export interface LayoutDeps {
+	camera: { current: Camera }
+	size: { current: { width: number; height: number } }
+	invalidate: () => void
+	labels: LabelStore
+	config?: Partial<SolverConfig>
+}
+
+/** Clamp the frame delta so a long idle gap can't make the ease overshoot. */
+const MAX_DELTA = 0.05
+
+/** Frames to keep retrying a failed measure after a real change before giving up (idle). */
+const MAX_RETRY = 4
+
+export function createLabelLayout(deps: LayoutDeps) {
+	const config: SolverConfig = { ...defaultSolverConfig, ...deps.config }
+
+	const nodesByLabel = new WeakMap<HTMLElement, LabelNode>()
+	const grid = new SpatialHash()
+
+	let activeNodes: LabelNode[] = []
+	let bestSnap = new Int16Array(0)
+
+	let lastCamHash = -1
+	let lastSetVersion = -1
+	let pendingRetry = false
+	let retryBudget = 0
+	let animating = false
+
+	function ensureNode(labelEl: HTMLElement): LabelNode | null {
+		const existing = nodesByLabel.get(labelEl)
+		if (existing) return existing
+
+		const textEl = labelEl.querySelector<HTMLElement>('.text')
+		const dotEl = labelEl.querySelector<HTMLElement>('.dot')
+		const lineEl = labelEl.querySelector<SVGLineElement>('.link line')
+		if (!textEl || !dotEl || !lineEl) return null
+
+		textEl.style.willChange = 'transform'
+
+		const id = crypto.randomUUID()
+		const node: LabelNode = {
+			id,
+			idHash: hashString(id),
+			ax: 0,
+			ay: 0,
+			dotR: 0,
+			w: 0,
+			h: 0,
+			scale: 1,
+			cssDotW: 0,
+			dotLocalX: Number.NaN,
+			dotLocalY: Number.NaN,
+			slots: [],
+			geomKey: '',
+			crowded: false,
+			slotIndex: -1,
+			prevSlotIndex: -1,
+			cx: Number.NaN,
+			cy: Number.NaN,
+			tx: 0,
+			ty: 0,
+			settled: false,
+			conflict: 0,
+			locked: false,
+			centroidX: 0,
+			centroidY: 0,
+			prevAx: Number.NaN,
+			prevAy: Number.NaN,
+			neighbors: [],
+			labelEl,
+			textEl,
+			dotEl,
+			lineEl,
+		}
+		nodesByLabel.set(labelEl, node)
+		return node
+	}
+
+	function geomKey(node: LabelNode): string {
+		return `${Math.round(node.w)}_${Math.round(node.h)}_${Math.round(node.dotR)}`
+	}
+
+	function nearestSlot(node: LabelNode): number {
+		let best = 0
+		let bestDist = Number.POSITIVE_INFINITY
+		for (let i = 0; i < node.slots.length; i++) {
+			const sx = node.ax + node.slots[i].dx
+			const sy = node.ay + node.slots[i].dy
+			const d = (sx - node.cx) ** 2 + (sy - node.cy) ** 2
+			if (d < bestDist) {
+				bestDist = d
+				best = i
+			}
+		}
+		return best
+	}
+
+	function solveLayout(width: number, height: number) {
+		pendingRetry = false
+		activeNodes = []
+
+		for (const el of deps.labels.current) {
+			// Skip detached or hidden islands (e.g. <HTML> sets display:none when an
+			// entity is behind the camera) without arming a retry — they have no
+			// client rects, and treating them as "not ready" would pin the
+			// on-demand loop re-solving every frame.
+			if (!el.isConnected || el.getClientRects().length === 0) continue
+			const node = ensureNode(el)
+			if (!node) {
+				pendingRetry = true
+				continue
+			}
+			if (measureNode(node)) activeNodes.push(node)
+			else pendingRetry = true
+		}
+
+		const nodes = activeNodes
+		const n = nodes.length
+		if (n === 0) return
+
+		buildNeighborhood(grid, nodes, config)
+
+		// Crowding (post-symmetrisation) drives adaptive slot density.
+		for (const node of nodes) {
+			const crowded = node.neighbors.length > config.crowdedThreshold
+			const key = geomKey(node)
+			if (key !== node.geomKey || crowded !== node.crowded) {
+				node.slots = generateSlots(node, crowded, config)
+				node.geomKey = key
+				node.crowded = crowded
+				node.slotIndex = -1
+			}
+		}
+
+		// Local cluster centroid for the outward-fan term.
+		for (const node of nodes) {
+			let sx = node.ax
+			let sy = node.ay
+			for (const m of node.neighbors) {
+				sx += m.ax
+				sy += m.ay
+			}
+			const count = node.neighbors.length + 1
+			node.centroidX = sx / count
+			node.centroidY = sy / count
+		}
+
+		// Warm-start: fresh nodes start near their dot, then snap onto the lattice.
+		for (const node of nodes) {
+			if (Number.isNaN(node.cx)) {
+				node.cx = node.ax + (node.w / 2 + node.dotR + config.dotPadding)
+				node.cy = node.ay
+			}
+			if (node.slotIndex < 0 || node.slotIndex >= node.slots.length) {
+				node.slotIndex = nearestSlot(node)
+			}
+		}
+
+		if (bestSnap.length < n) bestSnap = new Int16Array(n)
+		solve(nodes, config, bestSnap)
+
+		// A big camera jump (or a brand-new node) snaps labels to their solved
+		// target; everything else eases there from its current position.
+		applyTeleports(nodes, width, height, config)
+	}
+
+	function frame(delta: number) {
+		const { width, height } = deps.size.current
+		const camHash = cameraMatrixHash(deps.camera.current, width, height)
+		const setVersion = deps.labels.version
+
+		// A real change (camera/label-set) re-arms the retry window; pendingRetry can
+		// then drive a few more solves for genuinely-transient unmeasurable labels
+		// (first paint) without spinning forever on a persistently-unmeasurable one.
+		const changed = camHash !== lastCamHash || setVersion !== lastSetVersion
+		if (changed) retryBudget = MAX_RETRY
+		const retrying = pendingRetry && retryBudget > 0 && !changed
+		if (retrying) retryBudget--
+		const dirty = changed || retrying
+
+		if (dirty) {
+			solveLayout(width, height)
+			lastCamHash = camHash
+			lastSetVersion = setVersion
+		}
+
+		if (!dirty && !animating) return
+
+		const dt = Math.min(delta, MAX_DELTA)
+		let moving = false
+		for (const node of activeNodes) {
+			if (lerpStep(node, dt, config.settleEps)) moving = true
+			writeBack(node)
+		}
+		animating = moving
+
+		deps.invalidate()
+	}
+
+	return { frame }
+}
diff --git a/src/lib/components/Entities/labelLayout/geometry.ts b/src/lib/components/Entities/labelLayout/geometry.ts
new file mode 100644
index 000000000..9cccc6e46
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/geometry.ts
@@ -0,0 +1,136 @@
+/**
+ * Pure 2D geometry primitives used by the label layout cost function.
+ *
+ * Rectangles are center + half-extents; segments are flat coordinates. None of
+ * these allocate, so they are safe to call inside the solver's hot loop.
+ */
+
+import type { Rect, Segment } from './types'
+
+export function rectsOverlap(a: Rect, b: Rect, pad = 0): boolean {
+	return Math.abs(a.cx - b.cx) < a.hw + b.hw + pad && Math.abs(a.cy - b.cy) < a.hh + b.hh + pad
+}
+
+/** Fraction of the smaller rectangle's area covered by the intersection, 0..1. */
+export function overlapAreaFrac(a: Rect, b: Rect): number {
+	const ox = Math.min(a.cx + a.hw, b.cx + b.hw) - Math.max(a.cx - a.hw, b.cx - b.hw)
+	if (ox <= 0) return 0
+	const oy = Math.min(a.cy + a.hh, b.cy + b.hh) - Math.max(a.cy - a.hh, b.cy - b.hh)
+	if (oy <= 0) return 0
+	return (ox * oy) / Math.min(4 * a.hw * a.hh, 4 * b.hw * b.hh)
+}
+
+/**
+ * Liang-Barsky clip of a segment against a rectangle.
+ * Returns the clipped length as a fraction of the full segment (0..1), or -1 if
+ * the segment misses the rectangle entirely.
+ */
+function clipFraction(s: Segment, r: Rect): number {
+	const minX = r.cx - r.hw
+	const maxX = r.cx + r.hw
+	const minY = r.cy - r.hh
+	const maxY = r.cy + r.hh
+	const dx = s.x2 - s.x1
+	const dy = s.y2 - s.y1
+
+	let t0 = 0
+	let t1 = 1
+	let p: number
+	let q: number
+	let t: number
+
+	// Four clip edges, inlined to avoid per-call allocation in the hot loop.
+	// Each edge is a (p, q) pair; the point is inside when p*t <= q holds.
+	p = -dx
+	q = s.x1 - minX
+	if (p === 0) {
+		if (q < 0) return -1
+	} else {
+		t = q / p
+		if (p < 0) {
+			if (t > t1) return -1
+			if (t > t0) t0 = t
+		} else {
+			if (t < t0) return -1
+			if (t < t1) t1 = t
+		}
+	}
+
+	p = dx
+	q = maxX - s.x1
+	if (p === 0) {
+		if (q < 0) return -1
+	} else {
+		t = q / p
+		if (p < 0) {
+			if (t > t1) return -1
+			if (t > t0) t0 = t
+		} else {
+			if (t < t0) return -1
+			if (t < t1) t1 = t
+		}
+	}
+
+	p = -dy
+	q = s.y1 - minY
+	if (p === 0) {
+		if (q < 0) return -1
+	} else {
+		t = q / p
+		if (p < 0) {
+			if (t > t1) return -1
+			if (t > t0) t0 = t
+		} else {
+			if (t < t0) return -1
+			if (t < t1) t1 = t
+		}
+	}
+
+	p = dy
+	q = maxY - s.y1
+	if (p === 0) {
+		if (q < 0) return -1
+	} else {
+		t = q / p
+		if (p < 0) {
+			if (t > t1) return -1
+			if (t > t0) t0 = t
+		} else {
+			if (t < t0) return -1
+			if (t < t1) t1 = t
+		}
+	}
+
+	return t0 <= t1 ? t1 - t0 : -1
+}
+
+/**
+ * Continuous penetration: how much of the segment lies inside the rectangle,
+ * as a fraction of segment length (0 = disjoint, 1 = fully inside). Gives the
+ * optimizer a gradient that the boolean test lacks.
+ */
+export function segmentRectPenetration(s: Segment, r: Rect): number {
+	const f = clipFraction(s, r)
+	return Math.max(f, 0)
+}
+
+function ccw(ax: number, ay: number, bx: number, by: number, px: number, py: number): number {
+	return (bx - ax) * (py - ay) - (by - ay) * (px - ax)
+}
+
+/** Proper crossing of two segments (shared endpoints / collinear touching excluded). */
+export function segmentsCross(a: Segment, b: Segment): boolean {
+	const d1 = ccw(b.x1, b.y1, b.x2, b.y2, a.x1, a.y1)
+	const d2 = ccw(b.x1, b.y1, b.x2, b.y2, a.x2, a.y2)
+	const d3 = ccw(a.x1, a.y1, a.x2, a.y2, b.x1, b.y1)
+	const d4 = ccw(a.x1, a.y1, a.x2, a.y2, b.x2, b.y2)
+	return d1 > 0 !== d2 > 0 && d3 > 0 !== d4 > 0
+}
+
+/** Penetration depth (viewport px) of a circle into a rectangle, 0 if disjoint. */
+export function rectCircleOverlap(r: Rect, cx: number, cy: number, rad: number): number {
+	const nx = Math.max(Math.abs(cx - r.cx) - r.hw, 0)
+	const ny = Math.max(Math.abs(cy - r.cy) - r.hh, 0)
+	const d = Math.sqrt(nx * nx + ny * ny)
+	return Math.max(rad - d, 0)
+}
diff --git a/src/lib/components/Entities/labelLayout/labelStore.svelte.ts b/src/lib/components/Entities/labelLayout/labelStore.svelte.ts
new file mode 100644
index 000000000..2d659b5d8
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/labelStore.svelte.ts
@@ -0,0 +1,32 @@
+/**
+ * Registry of live label root elements (`.label`) shared between the per-entity
+ * `Label.svelte` components (which add/remove themselves) and the layout engine
+ * (which reads them each solve).
+ *
+ * `version` is bumped on every structural or text change so the engine can cheaply
+ * detect that a re-solve is needed without diffing the DOM.
+ */
+export class LabelStore {
+	current = $state<HTMLElement[]>([])
+	version = $state(0)
+
+	add(element: HTMLElement) {
+		this.current.push(element)
+		this.version += 1
+	}
+
+	remove(element: HTMLElement) {
+		const index = this.current.indexOf(element)
+		if (index !== -1) {
+			this.current.splice(index, 1)
+			this.version += 1
+		}
+	}
+
+	/** Signal that a label's text (and therefore its measured size) may have changed. */
+	touch() {
+		this.version += 1
+	}
+}
+
+export const labels = new LabelStore()
diff --git a/src/lib/components/Entities/labelLayout/measure.ts b/src/lib/components/Entities/labelLayout/measure.ts
new file mode 100644
index 000000000..99937e07a
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/measure.ts
@@ -0,0 +1,50 @@
+/**
+ * Reads a label's on-screen geometry from the DOM. This is the only place that
+ * forces layout (getBoundingClientRect / getComputedStyle), and the engine calls
+ * it for every node in one batch at the top of a solve — all reads before any
+ * writes — so the per-frame read/write thrash of the old engine is gone.
+ */
+
+import type { LabelNode } from './types'
+
+/** CSS size of the dot (`.dot` is Tailwind `h-2 w-2` = 8px); used only as a scale fallback. */
+const DOT_CSS_FALLBACK = 8
+
+/**
+ * Refresh `node`'s anchor, size, and scale from the DOM.
+ * Returns false if the label isn't measurable yet (detached or not laid out),
+ * in which case the caller skips it this solve and retries.
+ */
+export function measureNode(node: LabelNode): boolean {
+	if (!node.labelEl.isConnected) return false
+
+	const dot = node.dotEl.getBoundingClientRect()
+	const text = node.textEl.getBoundingClientRect()
+	if (dot.width === 0 || text.width === 0) return false
+
+	const dotCenterX = dot.left + dot.width / 2
+	const dotCenterY = dot.top + dot.height / 2
+
+	node.ax = dotCenterX
+	node.ay = dotCenterY
+	node.dotR = dot.width / 2
+	node.w = text.width
+	node.h = text.height
+
+	if (node.cssDotW === 0) {
+		node.cssDotW = Number.parseFloat(getComputedStyle(node.dotEl).width) || DOT_CSS_FALLBACK
+	}
+	const s = dot.width / node.cssDotW
+	node.scale = Number.isFinite(s) && s > 1e-4 ? s : 1
+
+	// The dot's center relative to the island origin (the 0x0 `.label` box placed
+	// at the projected 3D point) is a fixed CSS layout offset — measure it once so
+	// the leader line starts at the dot wherever the dot's CSS positions it.
+	if (Number.isNaN(node.dotLocalX)) {
+		const island = node.labelEl.getBoundingClientRect()
+		node.dotLocalX = (dotCenterX - island.left) / node.scale
+		node.dotLocalY = (dotCenterY - island.top) / node.scale
+	}
+
+	return true
+}
diff --git a/src/lib/components/Entities/labelLayout/slots.ts b/src/lib/components/Entities/labelLayout/slots.ts
new file mode 100644
index 000000000..2866da44b
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/slots.ts
@@ -0,0 +1,56 @@
+/**
+ * Candidate slot generation: concentric rings of radial directions around a dot.
+ *
+ * The inner radius per angle uses the AABB support function (tighter than a
+ * uniform half-diagonal, so cardinal placements sit closer), guaranteeing a
+ * node's own dot never enters its own box at any angle.
+ */
+
+import type { LabelNode, Slot, SolverConfig } from './types'
+
+import { W } from './cost'
+
+export const generateSlots = (node: LabelNode, crowded: boolean, config: SolverConfig): Slot[] => {
+	const angles = crowded ? config.anglesPerRing * 2 : config.anglesPerRing
+	const rings = crowded ? config.ringRadiiCrowded : config.ringRadii
+
+	// Deterministic per-node phase so neighbouring dots don't expose identical angles.
+	const phase = ((node.idHash % angles) / angles) * ((2 * Math.PI) / angles)
+
+	const halfW = node.w / 2
+	const halfH = node.h / 2
+	const slots: Slot[] = []
+
+	for (let ring = 0; ring < rings.length; ring++) {
+		// Half-step stagger on odd rings so leaders interleave instead of stacking.
+		const stagger = ring % 2 ? Math.PI / angles : 0
+		for (let k = 0; k < angles; k++) {
+			const angle = phase + stagger + (k / angles) * 2 * Math.PI
+			const ct = Math.cos(angle)
+			const st = Math.sin(angle)
+			const support = Math.abs(ct) * halfW + Math.abs(st) * halfH
+			const radius = (support + node.dotR + config.dotPadding) * rings[ring]
+			slots.push({
+				dx: ct * radius,
+				dy: st * radius,
+				angle,
+				radius,
+				ring,
+				baseCost: W.len * radius,
+			})
+		}
+	}
+
+	slots.sort((a, b) => a.baseCost - b.baseCost)
+	return slots
+}
+
+/** FNV-1a hash of a string → unsigned 32-bit. */
+export const hashString = (s: string): number => {
+	let h = 2166136261
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i)
+		h = Math.imul(h, 16777619)
+	}
+	return h >>> 0
+}
diff --git a/src/lib/components/Entities/labelLayout/solve.ts b/src/lib/components/Entities/labelLayout/solve.ts
new file mode 100644
index 000000000..2906d3595
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/solve.ts
@@ -0,0 +1,112 @@
+/**
+ * Deterministic slot assignment via priority-ordered conflict-graph local search.
+ *
+ * Warm-started from each node's previously committed slot (set by the engine
+ * before this runs), it repeatedly moves the worst-conflict node to its lowest
+ * cost slot, re-scoring only the affected neighbourhood, until no node has a
+ * conflict or the move budget is spent. A best-total snapshot is restored at the
+ * end so a re-solve can never regress below where it started.
+ */
+import type { LabelNode, SolverConfig } from './types'
+
+import { evalConflict, placementBias, W } from './cost'
+
+/** Conflicts below this are treated as resolved (floating-point slack). */
+const RESOLVED = 0.5
+
+/**
+ * The slot that minimizes conflict (crossings/overlaps), breaking ties by the
+ * tidiness bias. Selection and the caller's acceptance gate share the conflict
+ * objective, so a node is never locked at a placement another slot would
+ * improve. The baseCost early-out applies only once conflict is already
+ * resolved — while a node still conflicts, every slot is considered.
+ */
+const bestSlot = (node: LabelNode, config: SolverConfig): { index: number; conflict: number } => {
+	const neighbors = node.neighbors
+	let index = node.slotIndex
+	let conflict = evalConflict(node, node.slotIndex, neighbors, config)
+	let bias = placementBias(node, node.slotIndex)
+
+	for (let s = 0; s < node.slots.length; s++) {
+		if (s === node.slotIndex) continue
+		// Slots are sorted ascending by baseCost; once conflict is resolved only
+		// tidiness remains, so no farther slot can beat the incumbent's bias.
+		if (conflict <= RESOLVED && node.slots[s].baseCost - W.stick >= bias) break
+		const c = evalConflict(node, s, neighbors, config)
+		const b = placementBias(node, s)
+		if (c < conflict - 1e-6 || (c <= conflict + 1e-6 && b < bias)) {
+			index = s
+			conflict = c
+			bias = b
+		}
+	}
+
+	return { index, conflict }
+}
+
+export const solve = (nodes: LabelNode[], config: SolverConfig, bestSnap: Int16Array): void => {
+	const n = nodes.length
+	if (n === 0) return
+
+	for (const node of nodes) node.prevSlotIndex = node.slotIndex
+
+	const order = nodes.toSorted(
+		(a, b) => b.w * b.h - a.w * a.h || a.slots.length - b.slots.length || a.idHash - b.idHash
+	)
+
+	let total = 0
+	for (let i = 0; i < n; i++) {
+		const node = nodes[i]
+		node.conflict = evalConflict(node, node.slotIndex, node.neighbors, config)
+		node.locked = false
+		total += node.conflict
+	}
+
+	let bestE = total
+	for (let i = 0; i < n; i++) bestSnap[i] = nodes[i].slotIndex
+
+	let budget = config.polishBudget
+	while (budget > 0) {
+		let worst: LabelNode | undefined
+		let worstConflict = RESOLVED
+		for (let i = 0; i < n; i++) {
+			const node = order[i]
+			if (!node.locked && node.conflict > worstConflict) {
+				worstConflict = node.conflict
+				worst = node
+			}
+		}
+		if (!worst) break
+
+		const result = bestSlot(worst, config)
+		if (result.index !== worst.slotIndex && result.conflict < worst.conflict - RESOLVED) {
+			total += result.conflict - worst.conflict
+			worst.slotIndex = result.index
+			worst.conflict = result.conflict
+			budget--
+
+			// Moving `worst` changes the pairwise cost of its neighbors only.
+			for (const m of worst.neighbors) {
+				const before = m.conflict
+				m.conflict = evalConflict(m, m.slotIndex, m.neighbors, config)
+				total += m.conflict - before
+				m.locked = false
+			}
+
+			if (total < bestE) {
+				bestE = total
+				for (let i = 0; i < n; i++) bestSnap[i] = nodes[i].slotIndex
+			}
+		} else {
+			worst.locked = true
+		}
+	}
+
+	for (let i = 0; i < n; i++) {
+		const node = nodes[i]
+		node.slotIndex = bestSnap[i]
+		const slot = node.slots[node.slotIndex]
+		node.tx = node.ax + slot.dx
+		node.ty = node.ay + slot.dy
+	}
+}
diff --git a/src/lib/components/Entities/labelLayout/spatialHash.ts b/src/lib/components/Entities/labelLayout/spatialHash.ts
new file mode 100644
index 000000000..1bb7508dd
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/spatialHash.ts
@@ -0,0 +1,58 @@
+/**
+ * Uniform grid over label anchors, used to prune the O(n^2) cost evaluation to a
+ * bounded neighborhood. The cell size is chosen so any two labels whose boxes
+ * could possibly interact share or border a cell, so scanning the 3x3 block
+ * around a node finds every candidate.
+ */
+
+import type { LabelNode } from './types'
+
+const KEY_OFFSET = 2048
+const KEY_STRIDE = 4096
+
+export class SpatialHash {
+	private cell = 1
+	private readonly buckets = new Map<number, LabelNode[]>()
+
+	private static key(gx: number, gy: number): number {
+		return (gx + KEY_OFFSET) * KEY_STRIDE + (gy + KEY_OFFSET)
+	}
+
+	build(nodes: LabelNode[], cell: number) {
+		this.cell = Math.max(cell, 1)
+		this.buckets.clear()
+		for (const node of nodes) {
+			const k = SpatialHash.key(Math.floor(node.ax / this.cell), Math.floor(node.ay / this.cell))
+			const bucket = this.buckets.get(k)
+			if (bucket) bucket.push(node)
+			else this.buckets.set(k, [node])
+		}
+	}
+
+	/** Nearest `max` nodes (by anchor distance) in the 3x3 cell block around `node`, excluding itself. */
+	queryNeighbors(node: LabelNode, max: number): LabelNode[] {
+		const gx = Math.floor(node.ax / this.cell)
+		const gy = Math.floor(node.ay / this.cell)
+		const found: LabelNode[] = []
+
+		for (let ox = -1; ox <= 1; ox++) {
+			for (let oy = -1; oy <= 1; oy++) {
+				const bucket = this.buckets.get(SpatialHash.key(gx + ox, gy + oy))
+				if (!bucket) continue
+				for (const other of bucket) {
+					if (other !== node) found.push(other)
+				}
+			}
+		}
+
+		if (found.length <= max) return found
+
+		found.sort((a, b) => {
+			const da = (a.ax - node.ax) ** 2 + (a.ay - node.ay) ** 2
+			const db = (b.ax - node.ax) ** 2 + (b.ay - node.ay) ** 2
+			return da - db
+		})
+		found.length = max
+		return found
+	}
+}
diff --git a/src/lib/components/Entities/labelLayout/types.ts b/src/lib/components/Entities/labelLayout/types.ts
new file mode 100644
index 000000000..fc95d001a
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/types.ts
@@ -0,0 +1,137 @@
+/**
+ * Shared types for the label layout engine.
+ *
+ * All spatial fields are in viewport pixels (one shared screen-space for every
+ * label) except where noted. Slots store dot-relative offsets so a camera pan
+ * never invalidates them.
+ */
+
+/** Axis-aligned rectangle as center + half-extents (viewport px). */
+export interface Rect {
+	cx: number
+	cy: number
+	hw: number
+	hh: number
+}
+
+/** Line segment (viewport px). */
+export interface Segment {
+	x1: number
+	y1: number
+	x2: number
+	y2: number
+}
+
+/** A candidate placement for a label box, expressed as the box-center offset from the dot. */
+export interface Slot {
+	/** Box-center offset from the dot, viewport px. */
+	dx: number
+	dy: number
+	/** Direction of the slot from the dot, radians. */
+	angle: number
+	/** Distance from the dot to the box center, viewport px. */
+	radius: number
+	/** Ring index (0 = innermost). */
+	ring: number
+	/** Length-only cost (`W.len * radius`); slots are sorted ascending by this for early-out. */
+	baseCost: number
+}
+
+export interface LabelNode {
+	/** Stable per-element id, assigned once. */
+	id: string
+	/** FNV hash of `id`, used for deterministic tie-breaks and per-node slot phase. */
+	idHash: number
+
+	// Anchor = projected dot center (viewport px), refreshed each solve.
+	ax: number
+	ay: number
+	dotR: number
+
+	// Box full size (viewport px), refreshed each solve.
+	w: number
+	h: number
+
+	/** Per-island CSS scale (screenPx / localPx). */
+	scale: number
+	/** Cached computed CSS width of the dot (local px); read once. */
+	cssDotW: number
+	/** Dot center relative to the island origin, island-local px. Fixed CSS offset, measured once (NaN until then). */
+	dotLocalX: number
+	dotLocalY: number
+
+	slots: Slot[]
+	/** Hash of the box/dot geometry; slots regenerate only when this or `crowded` changes. */
+	geomKey: string
+	crowded: boolean
+
+	/** Committed slot (target). -1 before first placement. */
+	slotIndex: number
+	/** Slot committed by the previous solve, for stickiness. */
+	prevSlotIndex: number
+
+	// Animated box center (what writeBack consumes; seeds the next solve).
+	cx: number
+	cy: number
+	// Target box center for the current solve.
+	tx: number
+	ty: number
+	settled: boolean
+
+	/** Conflict cost of the current slot — the local-search loop key. */
+	conflict: number
+	/** Locked at a local optimum for the current solve. */
+	locked: boolean
+
+	/** Local cluster centroid (self + neighbors) for the outward-fan term. */
+	centroidX: number
+	centroidY: number
+
+	/** Anchor at the previous solve, for teleport detection. NaN before first solve. */
+	prevAx: number
+	prevAy: number
+
+	/** Pruned interaction set for the current solve (symmetric). */
+	neighbors: LabelNode[]
+
+	labelEl: HTMLElement
+	textEl: HTMLElement
+	dotEl: HTMLElement
+	lineEl: SVGLineElement
+}
+
+export interface SolverConfig {
+	/** Label-label clearance (viewport px). */
+	labelPadding: number
+	/** Dot clearance (viewport px). */
+	dotPadding: number
+	/** Candidate angles per ring (doubled for crowded nodes). */
+	anglesPerRing: number
+	/** Ring radius multipliers for sparse nodes. */
+	ringRadii: number[]
+	/** Ring radius multipliers for crowded nodes (more escape room). */
+	ringRadiiCrowded: number[]
+	/** Max accepted local-search moves per solve. */
+	polishBudget: number
+	/** Max neighbors considered per node (caps cost in dense clusters). */
+	maxNeighbors: number
+	/** Distance (viewport px) under which a box is considered arrived. */
+	settleEps: number
+	/** Neighbor count above which a node is "crowded". */
+	crowdedThreshold: number
+	/** Fraction of the viewport diagonal that counts as a camera teleport. */
+	teleportFrac: number
+}
+
+export const defaultSolverConfig: SolverConfig = {
+	labelPadding: 6,
+	dotPadding: 6,
+	anglesPerRing: 12,
+	ringRadii: [1, 1.55, 2.2],
+	ringRadiiCrowded: [1, 1.45, 1.95, 2.6],
+	polishBudget: 240,
+	maxNeighbors: 24,
+	settleEps: 0.4,
+	crowdedThreshold: 8,
+	teleportFrac: 0.5,
+}
diff --git a/src/lib/components/Entities/labelLayout/writeBack.ts b/src/lib/components/Entities/labelLayout/writeBack.ts
new file mode 100644
index 000000000..0cc661d03
--- /dev/null
+++ b/src/lib/components/Entities/labelLayout/writeBack.ts
@@ -0,0 +1,58 @@
+/**
+ * Per-frame animation and DOM write-back. The solver produces a target box
+ * center; the animated center eases toward it (framerate-independent), and the
+ * eased position is written to the label as a scale-corrected local transform
+ * plus leader-line endpoints — the same coordinate handling the old engine used.
+ */
+
+import type { LabelNode } from './types'
+
+/** Easing time constant (seconds): ~3-4 frames to arrive at 60fps. */
+const TAU = 0.08
+
+/**
+ * Ease `node`'s animated center toward its target. Returns true while still
+ * moving, false once arrived (and snapped). `delta` is seconds, pre-clamped by
+ * the engine so a long idle gap can't produce an overshoot.
+ */
+export function lerpStep(node: LabelNode, delta: number, settleEps: number): boolean {
+	const dx = node.tx - node.cx
+	const dy = node.ty - node.cy
+	if (dx * dx + dy * dy <= settleEps * settleEps) {
+		node.cx = node.tx
+		node.cy = node.ty
+		node.settled = true
+		return false
+	}
+	const alpha = 1 - Math.exp(-delta / TAU)
+	node.cx += dx * alpha
+	node.cy += dy * alpha
+	node.settled = false
+	return true
+}
+
+/**
+ * Write the eased position to the DOM. The label island is positioned at the dot
+ * by Threlte's <HTML>, so we work in island-local px: convert the viewport-space
+ * offset by the island's CSS scale, place the text box, and draw the leader from
+ * the dot's island-local position to the box center.
+ */
+export const writeBack = (node: LabelNode): void => {
+	const inv = 1 / node.scale
+	// Box-center offset from the dot, in island-local px.
+	const dx = (node.cx - node.ax) * inv
+	const dy = (node.cy - node.ay) * inv
+	const wL = node.w * inv
+	const hL = node.h * inv
+
+	// The dot may not sit at the island origin, so anchor everything at the dot's
+	// measured local position rather than assuming (0, 0).
+	const ox = node.dotLocalX
+	const oy = node.dotLocalY
+
+	node.textEl.style.transform = `translate(${ox + dx - wL / 2}px, ${oy + dy - hL / 2}px)`
+	node.lineEl.setAttribute('x1', `${ox}`)
+	node.lineEl.setAttribute('y1', `${oy}`)
+	node.lineEl.setAttribute('x2', `${ox + dx}`)
+	node.lineEl.setAttribute('y2', `${oy + dy}`)
+}