@tldraw/commenting 0.0.0-bootstrap

package/src/canvas/thread-state.ts

@@ -0,0 +1,91 @@
+import { BoxModel, Editor, TLCommentAnchor, TLCommentThread, TLShapeId, VecLike } from 'tldraw'
+import { getRegionCommentOptions } from './region-options'
+import { openThreadId } from './state'
+
+/** Where an imprecise shape comment sits by default: the shape's top-right corner. Overridable. @public */
+export const DEFAULT_IMPRECISE_SHAPE_ANCHOR = { x: 1, y: 0 }
+
+/** The default corner a region's pin and composer sit on, as a normalized 0–1 offset (bottom-right).
+ *  Overridable per editor via region options; pin position, composer placement, region move, and
+ *  which corner has no resize handle all derive from the chosen corner. */
+export const REGION_PIN_CORNER: VecLike = { x: 1, y: 1 }
+
+/** The page point of a region's pin corner. */
+export function regionPinPoint(region: BoxModel, corner: VecLike = REGION_PIN_CORNER): VecLike {
+	return {
+		x: region.x + corner.x * region.w,
+		y: region.y + corner.y * region.h,
+	}
+}
+
+/**
+ * Where a thread's pin sits on the page, for each anchor kind. Null hides the pin. For imprecise
+ * shape anchors the pin uses `impreciseShapeAnchor` (a normalized 0–1 spot, top-right by default)
+ * rather than the stored `x`/`y`.
+ * @public
+ */
+export function anchorPagePoint(
+	editor: Editor,
+	anchor: TLCommentAnchor,
+	impreciseShapeAnchor: { x: number; y: number } = DEFAULT_IMPRECISE_SHAPE_ANCHOR
+): { x: number; y: number } | null {
+	switch (anchor.type) {
+		case 'shape': {
+			const bounds = editor.getShapePageBounds(anchor.shapeId as TLShapeId)
+			if (!bounds) return null
+			// Precise pins sit at their stored x/y; imprecise ones at the consumer's default spot.
+			const { x, y } = anchor.isPrecise ? anchor : impreciseShapeAnchor
+			return { x: bounds.minX + x * bounds.w, y: bounds.minY + y * bounds.h }
+		}
+		case 'text-range': {
+			const bounds = editor.getShapePageBounds(anchor.shapeId as TLShapeId)
+			if (!bounds) return null
+			return { x: bounds.maxX, y: bounds.minY }
+		}
+		case 'point':
+			return { x: anchor.x, y: anchor.y }
+		case 'region':
+			return regionPinPoint(anchor, getRegionCommentOptions(editor).pinCorner)
+		case 'page':
+			return null
+	}
+}
+
+/**
+ * A shape anchor for a page point. `x`/`y` are the point's normalized (0–1) offset within the
+ * shape's page bounds, remembered either way. When `precise` (Alt held) the pin sits at exactly
+ * `x`/`y`; otherwise it sits at the consumer's imprecise default (top-right out of the box).
+ * @public
+ */
+export function shapeAnchorAt(
+	editor: Editor,
+	shapeId: TLShapeId,
+	page: { x: number; y: number },
+	precise: boolean
+): TLCommentAnchor {
+	const bounds = editor.getShapePageBounds(shapeId)
+	if (!bounds || bounds.w === 0 || bounds.h === 0) {
+		return { type: 'shape', shapeId, x: 0.5, y: 0.5, isPrecise: precise }
+	}
+	return {
+		type: 'shape',
+		shapeId,
+		x: (page.x - bounds.minX) / bounds.w,
+		y: (page.y - bounds.minY) / bounds.h,
+		isPrecise: precise,
+	}
+}
+
+/** Open a thread and bring it into view — switch to its page if needed, then center its pin. @public */
+export function focusThread(
+	editor: Editor,
+	thread: TLCommentThread,
+	impreciseShapeAnchor?: { x: number; y: number }
+): void {
+	if (thread.pageId !== editor.getCurrentPageId()) {
+		editor.setCurrentPage(thread.pageId as any)
+	}
+	openThreadId.set(editor, thread.id)
+	const point = anchorPagePoint(editor, thread.anchor, impreciseShapeAnchor)
+	if (point) editor.centerOnPoint(point, { animation: { duration: 200 } })
+}

package/src/clustering/computeClusterTable.test.ts

@@ -0,0 +1,299 @@
+import { describe, expect, it } from 'vitest'
+import { computeClusterTable } from './computeClusterTable'
+import { mstEdges } from './mst'
+import { cappedReplay } from './replay'
+import { createClusterRuntime } from './runtime'
+import { contract, finalize } from './schedule'
+import { ClusterTable, LeafInput, MergeEvent } from './types'
+
+function leaf(id: string, x: number, y: number): LeafInput {
+	return { id, point: { x, y } }
+}
+
+function mulberry32(seed: number): () => number {
+	let a = seed >>> 0
+	return () => {
+		a = (a + 0x6d2b79f5) >>> 0
+		let t = a
+		t = Math.imul(t ^ (t >>> 15), t | 1)
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+function shuffled<T>(items: readonly T[], rand: () => number): T[] {
+	const out = items.slice()
+	for (let i = out.length - 1; i > 0; i--) {
+		const j = Math.floor(rand() * (i + 1))
+		;[out[i], out[j]] = [out[j], out[i]]
+	}
+	return out
+}
+
+function randomLeaves(n: number, seed: number, scale = 1000): LeafInput[] {
+	const rand = mulberry32(seed)
+	return Array.from({ length: n }, (_, i) => leaf(`leaf-${i}`, rand() * scale, rand() * scale))
+}
+
+/** The pipeline composed by hand — computeClusterTable must match it exactly. */
+function manualPipeline(
+	leaves: readonly LeafInput[],
+	opts: {
+		Tc: number
+		Tu: number
+		eps: number
+		Dmax: number
+		minZoom: number
+		maxZoom: number
+		maxSplitZoom?: number
+	}
+): MergeEvent[] {
+	const raw = cappedReplay(leaves, mstEdges(leaves), { Tc: opts.Tc, Dmax: opts.Dmax })
+	return finalize(contract(raw, opts.eps), {
+		Tc: opts.Tc,
+		Tu: opts.Tu,
+		minZoom: opts.minZoom,
+		maxZoom: opts.maxZoom,
+		maxSplitZoom: opts.maxSplitZoom ?? 6,
+	})
+}
+
+function eventShape(ev: MergeEvent) {
+	return {
+		zMerge: ev.zMerge,
+		zSplit: ev.zSplit,
+		children: ev.children.map((c) => c.id),
+		result: ev.result.id,
+		members: ev.result.members,
+	}
+}
+
+function tableShapes(table: ClusterTable) {
+	return table.events.map(eventShape)
+}
+
+const ZOOM_BOUNDS = { minZoom: 0.05, maxZoom: 8 }
+
+describe('computeClusterTable composition', () => {
+	it('equals the hand-composed pipeline with all options explicit', () => {
+		const opts = { Tc: 40, Tu: 60, eps: 0.12, Dmax: 120, ...ZOOM_BOUNDS }
+		for (const seed of [1, 42]) {
+			for (const n of [2, 10, 60]) {
+				const leaves = randomLeaves(n, seed * 19 + n)
+				const table = computeClusterTable(leaves, opts)
+				expect(tableShapes(table)).toEqual(manualPipeline(leaves, opts).map(eventShape))
+			}
+		}
+	})
+
+	it('resolves all defaults from an empty option set (Tc 40, Tu 60, eps 0.12, Dmax 120)', () => {
+		const leaves = randomLeaves(30, 7)
+		const table = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+		const expected = manualPipeline(leaves, {
+			Tc: 40,
+			Tu: 60,
+			eps: 0.12,
+			Dmax: 120,
+			...ZOOM_BOUNDS,
+		})
+		expect(tableShapes(table)).toEqual(expected.map(eventShape))
+	})
+
+	it('derives Tu and Dmax from a caller-supplied Tc (Tu = 1.5·Tc, Dmax = 3·Tc)', () => {
+		const leaves = randomLeaves(30, 13)
+		const table = computeClusterTable(leaves, { Tc: 50, ...ZOOM_BOUNDS })
+		const expected = manualPipeline(leaves, {
+			Tc: 50,
+			Tu: 75,
+			eps: 0.12,
+			Dmax: 150,
+			...ZOOM_BOUNDS,
+		})
+		expect(tableShapes(table)).toEqual(expected.map(eventShape))
+	})
+
+	it('caps coincident pairs at the default maxSplitZoom of 6 (600%)', () => {
+		// Two threads at the same point: raw merge zoom is Infinity (never split), but the
+		// default cap schedules them to merge at 4 and split at 6 like any ultra-tight pair.
+		const leaves = [leaf('a', 50, 50), leaf('b', 50, 50)]
+		const table = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBe(4)
+		expect(table.events[0].zSplit).toBe(6)
+	})
+
+	it('honors partial overrides without disturbing the other defaults', () => {
+		const leaves = randomLeaves(30, 29)
+		const table = computeClusterTable(leaves, { Tu: 100, eps: 0, ...ZOOM_BOUNDS })
+		const expected = manualPipeline(leaves, {
+			Tc: 40,
+			Tu: 100,
+			eps: 0,
+			Dmax: 120,
+			...ZOOM_BOUNDS,
+		})
+		expect(tableShapes(table)).toEqual(expected.map(eventShape))
+	})
+})
+
+describe('computeClusterTable leaves output', () => {
+	it('returns leaf nodes in input order with exact leaf shape', () => {
+		const leaves = [leaf('z-last', 5, 6), leaf('a-first', 1, 2), leaf('m-mid', 3, 4)]
+		const table = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+		expect(table.leaves).toEqual([
+			{ id: 'z-last', centroid: { x: 5, y: 6 }, count: 1, members: ['z-last'] },
+			{ id: 'a-first', centroid: { x: 1, y: 2 }, count: 1, members: ['a-first'] },
+			{ id: 'm-mid', centroid: { x: 3, y: 4 }, count: 1, members: ['m-mid'] },
+		])
+	})
+
+	it('handles n = 0 and n = 1 (empty events, leaves still produced)', () => {
+		expect(computeClusterTable([], { ...ZOOM_BOUNDS })).toEqual({ events: [], leaves: [] })
+		const table = computeClusterTable([leaf('only', 9, 9)], { ...ZOOM_BOUNDS })
+		expect(table.events).toEqual([])
+		expect(table.leaves).toEqual([
+			{ id: 'only', centroid: { x: 9, y: 9 }, count: 1, members: ['only'] },
+		])
+	})
+
+	it('is usable directly by the runtime (n = 1 and n = 0 tables)', () => {
+		const table = computeClusterTable([leaf('only', 9, 9)], { ...ZOOM_BOUNDS })
+		const rt = createClusterRuntime(table)
+		rt.seed(1)
+		rt.onCamera(0.1)
+		expect([...rt.getVisible().keys()]).toEqual(['only'])
+	})
+})
+
+describe('computeClusterTable determinism', () => {
+	it('is invariant under input permutation, events as id-keyed structures', () => {
+		const base = randomLeaves(50, 23)
+		const expected = tableShapes(computeClusterTable(base, { ...ZOOM_BOUNDS }))
+		for (const shuffleSeed of [5, 17]) {
+			const perm = shuffled(base, mulberry32(shuffleSeed))
+			const table = computeClusterTable(perm, { ...ZOOM_BOUNDS })
+			expect(tableShapes(table)).toEqual(expected)
+			// leaves follow the (new) input order
+			expect(table.leaves.map((l) => l.id)).toEqual(perm.map((l) => l.id))
+		}
+	})
+
+	it('returns identical output for repeated calls', () => {
+		const leaves = randomLeaves(20, 3)
+		expect(computeClusterTable(leaves, { ...ZOOM_BOUNDS })).toEqual(
+			computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+		)
+	})
+})
+
+describe('computeClusterTable validation', () => {
+	const leaves = [leaf('a', 0, 0), leaf('b', 10, 0)]
+
+	it('rejects every invalid option combination', () => {
+		expect(() => computeClusterTable(leaves, { Tc: 0, ...ZOOM_BOUNDS })).toThrow()
+		expect(() => computeClusterTable(leaves, { Tc: -5, ...ZOOM_BOUNDS })).toThrow()
+		expect(() => computeClusterTable(leaves, { Tc: 40, Tu: 40, ...ZOOM_BOUNDS })).toThrow()
+		expect(() => computeClusterTable(leaves, { Tu: 30, ...ZOOM_BOUNDS })).toThrow() // < default Tc 40
+		expect(() => computeClusterTable(leaves, { eps: -0.01, ...ZOOM_BOUNDS })).toThrow()
+		expect(() => computeClusterTable(leaves, { Dmax: 30, ...ZOOM_BOUNDS })).toThrow() // < default Tc 40
+		expect(() => computeClusterTable(leaves, { Tc: 50, Dmax: 40, ...ZOOM_BOUNDS })).toThrow()
+		expect(() => computeClusterTable(leaves, { minZoom: 0, maxZoom: 8 })).toThrow()
+		expect(() => computeClusterTable(leaves, { minZoom: 8, maxZoom: 8 })).toThrow()
+		expect(() => computeClusterTable(leaves, { minZoom: 9, maxZoom: 8 })).toThrow()
+		expect(() => computeClusterTable(leaves, { minZoom: 0.05, maxZoom: NaN })).toThrow()
+		expect(() => computeClusterTable(leaves, { minZoom: 0.05, maxZoom: Infinity })).toThrow()
+		expect(() => computeClusterTable(leaves, { eps: NaN, ...ZOOM_BOUNDS })).toThrow()
+		expect(() => computeClusterTable(leaves, { Tc: NaN, ...ZOOM_BOUNDS })).toThrow()
+	})
+
+	it('validates even when there is nothing to cluster', () => {
+		expect(() => computeClusterTable([], { minZoom: 0, maxZoom: 8 })).toThrow()
+		expect(() => computeClusterTable([leaf('x', 0, 0)], { Tc: -1, ...ZOOM_BOUNDS })).toThrow()
+	})
+
+	it('propagates input errors from the MST stage', () => {
+		expect(() =>
+			computeClusterTable([leaf('dup', 0, 0), leaf('dup', 1, 1)], { ...ZOOM_BOUNDS })
+		).toThrow(/dup/)
+		expect(() =>
+			computeClusterTable([leaf('ok', 0, 0), leaf('bad', NaN, 0)], { ...ZOOM_BOUNDS })
+		).toThrow(/bad/)
+	})
+})
+
+describe('computeClusterTable end-to-end scenarios', () => {
+	it('produces the appendix A.2 zoom bands for the 8-pin chain, via the runtime', () => {
+		const leaves = Array.from({ length: 8 }, (_, i) => leaf(`p${i + 1}`, i * 10, 0))
+		const table = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+
+		// events (centroid pricing): four pair births at zMerge 4 (zSplit 6), two
+		// quads at zMerge 2 (zSplit 3), the bridge at zMerge 1 (zSplit 1.5)
+		const seedAt = (zoom: number) => {
+			const rt = createClusterRuntime(table)
+			rt.seed(zoom)
+			return [...rt.getVisible().keys()].sort()
+		}
+		// zoom 8: above every band midpoint → 8 separate pins
+		expect(seedAt(8)).toEqual(['p1', 'p2', 'p3', 'p4', 'p5', 'p6', 'p7', 'p8'])
+		// zoom 3: below the pair midpoints (√24 ≈ 4.9), above the quad midpoint (√6 ≈ 2.45)
+		expect(seedAt(3)).toEqual(['cluster:2:p1', 'cluster:2:p3', 'cluster:2:p5', 'cluster:2:p7'])
+		// zoom 2: quads merged, above the bridge midpoint (√1.5 ≈ 1.22)
+		expect(seedAt(2)).toEqual(['cluster:4:p1', 'cluster:4:p5'])
+		// zoom 1: below everything → one badge of 8
+		expect(seedAt(1)).toEqual(['cluster:8:p1'])
+	})
+
+	it('keeps far-apart groups exactly independent at eps = 0 (bridge pruned by minZoom)', () => {
+		// Two groups 10,000 page units apart: the bridging merge would fire at
+		// z ≈ 40/10000 = 0.004 < minZoom → pruned. With eps = 0 no contraction
+		// window can couple the groups, so the combined table is exactly the two
+		// solo tables' events merged in threshold order.
+		const groupA = randomLeaves(12, 5, 300)
+		const groupB = randomLeaves(12, 9, 300).map((l) => ({
+			id: `far-${l.id}`,
+			point: { x: l.point.x + 10000, y: l.point.y },
+		}))
+		const opts = { eps: 0, ...ZOOM_BOUNDS }
+
+		const combined = tableShapes(computeClusterTable([...groupA, ...groupB], opts))
+		const soloA = tableShapes(computeClusterTable(groupA, opts))
+		const soloB = tableShapes(computeClusterTable(groupB, opts))
+
+		const merged = [...soloA, ...soloB].sort((a, b) => b.zMerge - a.zMerge)
+		expect(combined.map((e) => e.result).sort()).toEqual(merged.map((e) => e.result).sort())
+		expect(combined).toHaveLength(soloA.length + soloB.length)
+
+		// no event ever mixes members across the gap
+		for (const ev of combined) {
+			const far = ev.members.filter((m) => m.startsWith('far-')).length
+			expect(far === 0 || far === ev.members.length).toBe(true)
+		}
+	})
+
+	it('keeps group memberships unmixed at default eps too (thresholds may synchronize)', () => {
+		// Global contraction windows may pull the two groups' thresholds together
+		// (synchronized firing is by design) but must never fuse their clusters.
+		const groupA = randomLeaves(10, 55, 300)
+		const groupB = randomLeaves(10, 66, 300).map((l) => ({
+			id: `far-${l.id}`,
+			point: { x: l.point.x + 10000, y: l.point.y },
+		}))
+		const combined = computeClusterTable([...groupA, ...groupB], { ...ZOOM_BOUNDS })
+		for (const ev of combined.events) {
+			const far = ev.result.members.filter((m) => m.startsWith('far-')).length
+			expect(far === 0 || far === ev.result.members.length).toBe(true)
+		}
+	})
+})
+
+describe('computeClusterTable performance', () => {
+	it('builds 2,000 leaves well within budget', () => {
+		const leaves = randomLeaves(2000, 2026)
+		const start = performance.now()
+		const table = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+		const elapsed = performance.now() - start
+		expect(table.leaves).toHaveLength(2000)
+		// generous bound to stay non-flaky on slow CI
+		expect(elapsed).toBeLessThan(2500)
+	})
+})

package/src/clustering/computeClusterTable.ts

@@ -0,0 +1,82 @@
+import { mstEdges } from './mst'
+import { cappedReplay } from './replay'
+import { contract, finalize } from './schedule'
+import type { ClusterNode, ClusterOptions, ClusterTable, LeafInput } from './types'
+
+interface ResolvedClusterOptions {
+	Tc: number
+	Tu: number
+	eps: number
+	Dmax: number
+	minZoom: number
+	maxZoom: number
+	maxSplitZoom: number
+}
+
+/** @public */
+export function computeClusterTable(
+	leaves: readonly LeafInput[],
+	options: ClusterOptions
+): ClusterTable {
+	const opts = resolveOptions(options)
+	const leafNodes = leaves.map(leafToNode)
+	const edges = mstEdges(leaves)
+
+	if (leaves.length < 2) {
+		return { events: [], leaves: leafNodes }
+	}
+
+	const raw = cappedReplay(leaves, edges, { Tc: opts.Tc, Dmax: opts.Dmax })
+	const contracted = contract(raw, opts.eps)
+	const events = finalize(contracted, {
+		Tc: opts.Tc,
+		Tu: opts.Tu,
+		minZoom: opts.minZoom,
+		maxZoom: opts.maxZoom,
+		maxSplitZoom: opts.maxSplitZoom,
+	})
+
+	return { events, leaves: leafNodes }
+}
+
+function resolveOptions(options: ClusterOptions): ResolvedClusterOptions {
+	const Tc = options.Tc ?? 40
+	const Tu = options.Tu ?? 1.5 * Tc
+	const eps = options.eps ?? 0.12
+	const Dmax = options.Dmax ?? 3 * Tc
+	const maxSplitZoom = options.maxSplitZoom ?? 6
+	const { minZoom, maxZoom } = options
+
+	if (!Number.isFinite(Tc) || Tc <= 0) {
+		throw new Error('Tc must be finite and greater than 0')
+	}
+	if (!Number.isFinite(Tu) || Tu <= Tc) {
+		throw new Error('Tu must be finite and greater than Tc')
+	}
+	if (!Number.isFinite(eps) || eps < 0) {
+		throw new Error('eps must be finite and greater than or equal to 0')
+	}
+	if (!Number.isFinite(Dmax) || Dmax < Tc) {
+		throw new Error('Dmax must be finite and greater than or equal to Tc')
+	}
+	if (!Number.isFinite(minZoom) || minZoom <= 0) {
+		throw new Error('minZoom must be finite and greater than 0')
+	}
+	if (!Number.isFinite(maxZoom) || maxZoom <= minZoom) {
+		throw new Error('maxZoom must be finite and greater than minZoom')
+	}
+	if (!Number.isFinite(maxSplitZoom) || maxSplitZoom <= 0) {
+		throw new Error('maxSplitZoom must be finite and greater than 0')
+	}
+
+	return { Tc, Tu, eps, Dmax, minZoom, maxZoom, maxSplitZoom }
+}
+
+function leafToNode(leaf: LeafInput): ClusterNode {
+	return {
+		id: leaf.id,
+		centroid: { x: leaf.point.x, y: leaf.point.y },
+		count: 1,
+		members: [leaf.id],
+	}
+}

package/src/clustering/locality.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest'
+import { computeClusterTable } from './computeClusterTable'
+import { createClusterRuntime } from './runtime'
+import { ClusterTable, LeafInput, MergeEvent } from './types'
+
+// The locality contract the overlay's rendering relies on (CLUSTERING.md §8.4):
+// a visible cluster's members never sit farther than (1+eps)·r·Dmax screen px
+// from its centroid, so culling with that margin never hides a badge whose
+// member anchors are on screen. The bound stacks all three mechanisms:
+//   cap        — zEff·pageDiag ≤ Dmax at every raw merge
+//   contraction— fusing to the window anchor overshoots by ≤ (1+eps)
+//   hysteresis — a merged cluster survives up to zSplit = r·zMerge
+// and uses the FULL extent, not half: a count-weighted centroid of a skewed
+// cluster (many pins on one side, one far out) can sit a full extent from its
+// farthest member.
+
+function leaf(id: string, x: number, y: number): LeafInput {
+	return { id, point: { x, y } }
+}
+
+function mulberry32(seed: number): () => number {
+	let a = seed >>> 0
+	return () => {
+		a = (a + 0x6d2b79f5) >>> 0
+		let t = a
+		t = Math.imul(t ^ (t >>> 15), t | 1)
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+function randomLeaves(n: number, seed: number, scale = 1000): LeafInput[] {
+	const rand = mulberry32(seed)
+	return Array.from({ length: n }, (_, i) => leaf(`leaf-${i}`, rand() * scale, rand() * scale))
+}
+
+const OPTS = { Tc: 40, Tu: 60, eps: 0.12, Dmax: 120, minZoom: 0.05, maxZoom: 8, maxSplitZoom: 1e9 }
+const R = OPTS.Tu / OPTS.Tc
+const SLACK = 1 + 1e-9
+
+function pointsOf(leaves: readonly LeafInput[]): Map<string, { x: number; y: number }> {
+	return new Map(leaves.map((l) => [l.id, l.point]))
+}
+
+/** Bbox diagonal of a member set, recomputed from the original leaf anchors. */
+function memberDiag(
+	members: readonly string[],
+	pts: Map<string, { x: number; y: number }>
+): number {
+	let minX = Infinity
+	let minY = Infinity
+	let maxX = -Infinity
+	let maxY = -Infinity
+	for (const id of members) {
+		const p = pts.get(id)!
+		minX = Math.min(minX, p.x)
+		minY = Math.min(minY, p.y)
+		maxX = Math.max(maxX, p.x)
+		maxY = Math.max(maxY, p.y)
+	}
+	return Math.hypot(maxX - minX, maxY - minY)
+}
+
+function zoomWalk(steps: number, seed: number): number[] {
+	const rand = mulberry32(seed)
+	const lnMin = Math.log(OPTS.minZoom)
+	const lnMax = Math.log(OPTS.maxZoom)
+	let ln = (lnMin + lnMax) / 2
+	const walk: number[] = []
+	for (let i = 0; i < steps; i++) {
+		const r = rand()
+		if (r < 0.15) ln = lnMin + rand() * (lnMax - lnMin)
+		else ln = Math.min(lnMax, Math.max(lnMin, ln + (rand() - 0.5) * 0.4))
+		walk.push(Math.exp(ln))
+	}
+	return walk
+}
+
+describe('locality bounds (the culling contract)', () => {
+	it('bounds every finite event at birth: zMerge · pageDiag(result) ≤ (1+eps) · Dmax', () => {
+		for (const seed of [3, 42, 77]) {
+			const leaves = randomLeaves(50, seed)
+			const table = computeClusterTable(leaves, OPTS)
+			const pts = pointsOf(leaves)
+			for (const ev of table.events) {
+				if (!Number.isFinite(ev.zMerge)) continue
+				const diag = memberDiag(ev.result.members, pts)
+				expect(ev.zMerge * diag).toBeLessThanOrEqual((1 + OPTS.eps) * OPTS.Dmax * SLACK)
+			}
+		}
+	})
+
+	it('bounds every VISIBLE cluster during random zoom walks: member-to-centroid ≤ (1+eps)·r·Dmax screen px', () => {
+		const margin = (1 + OPTS.eps) * R * OPTS.Dmax * SLACK
+		for (const seed of [5, 21]) {
+			const leaves = randomLeaves(40, seed * 7)
+			const table = computeClusterTable(leaves, OPTS)
+			const pts = pointsOf(leaves)
+			const rt = createClusterRuntime(table)
+			const walk = zoomWalk(200, seed)
+			rt.seed(walk[0])
+			for (const zoom of walk) {
+				rt.onCamera(zoom)
+				for (const cluster of rt.getVisible().values()) {
+					if (cluster.count === 1) continue
+					for (const id of cluster.members) {
+						const p = pts.get(id)!
+						const dist = Math.hypot(p.x - cluster.centroid.x, p.y - cluster.centroid.y)
+						expect(zoom * dist).toBeLessThanOrEqual(margin)
+					}
+				}
+			}
+		}
+	})
+
+	it('exercises the skewed-centroid worst case (many pins one side, one far out)', () => {
+		// 9 pins tightly packed at the origin plus one at distance 35: the
+		// count-weighted centroid sits near the pack, so the far member is almost
+		// a FULL extent away — the case that breaks a Dmax/2-style margin.
+		const leaves = [
+			...Array.from({ length: 9 }, (_, i) => leaf(`pack-${i}`, (i % 3) * 2, Math.floor(i / 3) * 2)),
+			leaf('far', 39, 2),
+		]
+		const table = computeClusterTable(leaves, OPTS)
+		const pts = pointsOf(leaves)
+		const full = table.events.find((ev) => ev.result.count === 10)
+		expect(full).toBeDefined()
+		// the far member really is beyond half the extent from the centroid…
+		const diag = memberDiag(full!.result.members, pts)
+		const p = pts.get('far')!
+		const dist = Math.hypot(p.x - full!.result.centroid.x, p.y - full!.result.centroid.y)
+		expect(dist).toBeGreaterThan(diag / 2)
+		// …and still within the full-extent bound at any zoom the cluster survives
+		expect(full!.zSplit * dist).toBeLessThanOrEqual((1 + OPTS.eps) * R * OPTS.Dmax * SLACK)
+	})
+})
+
+describe('move lifecycle (pick up = delete, drop = insert — CLUSTERING.md §9.2)', () => {
+	function tableShapes(table: ClusterTable) {
+		return table.events.map((ev: MergeEvent) => ({
+			zMerge: ev.zMerge,
+			zSplit: ev.zSplit,
+			children: ev.children.map((c) => c.id),
+			result: ev.result.id,
+		}))
+	}
+
+	it('drop-then-rebuild equals a fresh build of the final positions', () => {
+		const before = randomLeaves(20, 11)
+		// pick up leaf-5 (delete)…
+		const during = before.filter((l) => l.id !== 'leaf-5')
+		// …drop it somewhere else (insert at the end — array order differs from a
+		// fresh build, which must not matter)
+		const after = [...during, leaf('leaf-5', 777, 333)]
+		const fresh = before.map((l) => (l.id === 'leaf-5' ? leaf('leaf-5', 777, 333) : l))
+
+		expect(tableShapes(computeClusterTable(after, OPTS))).toEqual(
+			tableShapes(computeClusterTable(fresh, OPTS))
+		)
+	})
+
+	it('the mid-drag table is simply the table without the picked-up comment', () => {
+		const before = randomLeaves(12, 13)
+		const during = before.filter((l) => l.id !== 'leaf-3')
+		const table = computeClusterTable(during, OPTS)
+		expect(table.leaves.some((l) => l.id === 'leaf-3')).toBe(false)
+		for (const ev of table.events) {
+			expect(ev.result.members).not.toContain('leaf-3')
+		}
+	})
+
+	it('re-seeding after the rebuild matches seeding the fresh table directly', () => {
+		const before = randomLeaves(20, 17)
+		const after = [...before.filter((l) => l.id !== 'leaf-5'), leaf('leaf-5', 777, 333)]
+		const rebuilt = createClusterRuntime(computeClusterTable(after, OPTS))
+		const freshRt = createClusterRuntime(createFreshTableSameShape(after))
+		for (const zoom of [0.1, 0.5, 1, 2, 4, 7.9]) {
+			rebuilt.seed(zoom)
+			freshRt.seed(zoom)
+			expect([...rebuilt.getVisible().keys()].sort()).toEqual(
+				[...freshRt.getVisible().keys()].sort()
+			)
+		}
+
+		function createFreshTableSameShape(leaves: LeafInput[]): ClusterTable {
+			return computeClusterTable(leaves.slice().reverse(), OPTS)
+		}
+	})
+})