@tldraw/commenting 5.3.0-next.d7d8ced023d5 → 5.3.0-next.df310c6196c0

package/src/canvas/cluster-badge.tsx

@@ -0,0 +1,133 @@
+import { memo, useMemo, useRef } from 'react'
+import {
+	Editor,
+	TLCommentThread,
+	useContainer,
+	usePassThroughWheelEvents,
+	useTranslation,
+	useValue,
+} from 'tldraw'
+import type { ClusterNode } from '../clustering/types'
+import { CountBadge } from '../ui/count-badge'
+import { forwardPointerEventToCanvas, isCanvasPanGesture } from './canvas-events'
+import { type CommentingContext } from './context'
+import { sortThreadsForPreview, ThreadPreview, useMarkerPreview } from './thread-preview'
+import { impreciseShapePinInset, isInInflatedViewport } from './thread-state'
+
+/**
+ * The count badge standing in for several threads folded together at the current zoom. Hovering it
+ * previews its threads as a list; clicking zooms to the zoom level at which the cluster splits.
+ *
+ * Memoized: cluster nodes and thread records are identity-stable while unchanged, so pins and
+ * badges skip re-rendering when the parent re-renders for reasons that don't concern them
+ * (leaf recomputes during shape drags, partition changes elsewhere). Camera tracking still
+ * works — each component subscribes to its own viewport position via signals, not via props.
+ */
+export const ClusterBadge = memo(function ClusterBadge({
+	editor,
+	node,
+	onExpand,
+	onSelectThread,
+	threadsById,
+	...props
+}: Pick<CommentingContext, 'currentUserId' | 'resolveAuthor'> & {
+	editor: Editor
+	node: ClusterNode
+	onExpand(node: ClusterNode): void
+	onSelectThread(thread: TLCommentThread): void
+	threadsById: ReadonlyMap<string, TLCommentThread>
+}) {
+	const container = useContainer()
+	const msg = useTranslation()
+	const badgeRef = useRef<HTMLButtonElement>(null)
+	const { previewShown, previewHandlers } = useMarkerPreview(editor, `cluster:${node.id}`)
+	// Wheel pass-through sits on the badge (never scrollable), not the layer root — see the
+	// note on the layer.
+	usePassThroughWheelEvents(badgeRef)
+	// The mean of the members' render offsets, in screen px. Imprecise members' pins draw tucked
+	// into their shape (see impreciseShapePinInset), and the merge thresholds are priced at those
+	// visual positions — so the badge draws at the centroid of the pins as drawn, which (screen
+	// mapping being affine) is the anchor centroid plus this mean. Camera-independent: its own
+	// computed so the per-frame point below only adds two numbers, and a cluster of precise
+	// members tracks nothing and adds zero.
+	const meanInset = useValue(
+		'cluster badge inset',
+		() => {
+			let x = 0
+			let y = 0
+			for (const id of node.members) {
+				const thread = threadsById.get(id)
+				if (!thread) continue
+				const inset = impreciseShapePinInset(editor, thread.anchor)
+				if (inset) {
+					x += inset.x
+					y += inset.y
+				}
+			}
+			return { x: x / node.count, y: y / node.count }
+		},
+		[editor, node, threadsById]
+	)
+	const point = useValue(
+		'cluster badge point',
+		() => {
+			const pagePoint = editor.pageToViewport(node.centroid)
+			if (!isInInflatedViewport(editor, pagePoint)) return null
+			return { x: pagePoint.x + meanInset.x, y: pagePoint.y + meanInset.y }
+		},
+		[editor, node, meanInset]
+	)
+
+	// `node.members` is sorted by id (the clustering table's ordering); the preview wants them in
+	// the order a reader would expect. Only computed while the preview is up.
+	const previewThreads = useMemo(() => {
+		if (!previewShown) return []
+		const threads: TLCommentThread[] = []
+		for (const id of node.members) {
+			const thread = threadsById.get(id)
+			if (thread) threads.push(thread)
+		}
+		return sortThreadsForPreview(threads)
+	}, [previewShown, node.members, threadsById])
+
+	if (!point) return null
+
+	return (
+		<>
+			<button
+				ref={badgeRef}
+				type="button"
+				className="tlui-cmt-button tlui-cmt-canvas-cluster"
+				style={{ left: point.x, top: point.y }}
+				aria-label={msg('comments.cluster-label').replace('{count}', String(node.count))}
+				onPointerDown={(e) => {
+					if (isCanvasPanGesture(editor, e)) {
+						forwardPointerEventToCanvas(container, e)
+						return
+					}
+					e.stopPropagation()
+				}}
+				onClick={(e) => {
+					e.stopPropagation()
+					onExpand(node)
+				}}
+				{...previewHandlers}
+				onFocus={previewHandlers.onPointerEnter}
+				onBlur={previewHandlers.onPointerLeave}
+			>
+				<CountBadge count={node.count} />
+			</button>
+			{previewShown && previewThreads.length > 0 && (
+				<ThreadPreview
+					editor={editor}
+					threads={previewThreads}
+					variant="list"
+					point={point}
+					onSelectThread={onSelectThread}
+					{...previewHandlers}
+					{...props}
+				/>
+			)}
+		</>
+	)
+})

package/src/canvas/cluster-fade.ts

@@ -0,0 +1,102 @@
+import { useEffect, useRef, useState } from 'react'
+import type { ClusterNode } from '../clustering/types'
+
+const CLUSTER_FADE_MS = 150
+
+export type ClusterFadePhase = 'entering' | 'present' | 'exiting'
+
+export interface ClusterFadeNode {
+	node: ClusterNode
+	phase: ClusterFadePhase
+}
+
+/**
+ * Cross-fades the visible cluster nodes as the partition changes: a node that appears starts
+ * `entering` and flips to `present` on the next frame, and one that leaves is kept as `exiting`
+ * until the CSS transition has run. `resetKey` is compared by identity — a new cluster model
+ * replaces the whole world, so its nodes snap to `present` instead of animating.
+ */
+export function useFadeVisibleNodes(
+	nodes: readonly ClusterNode[],
+	resetKey: object
+): ClusterFadeNode[] {
+	const resetKeyRef = useRef(resetKey)
+	const didReset = resetKeyRef.current !== resetKey
+	if (didReset) {
+		resetKeyRef.current = resetKey
+	}
+
+	const [fadeNodes, setFadeNodes] = useState<ClusterFadeNode[]>(() => toPresentFadeNodes(nodes))
+	const renderedNodes = didReset ? toPresentFadeNodes(nodes) : fadeNodes
+
+	useEffect(() => {
+		setFadeNodes(toPresentFadeNodes(nodes))
+		// Resets only on a new model (resetKey); node-list changes within the same model are
+		// handled by the reconcile effect below, which fades entries in/out instead of snapping.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [resetKey])
+
+	useEffect(() => {
+		if (didReset) return
+		setFadeNodes((previous) => reconcileFadeNodes(previous, nodes))
+	}, [didReset, nodes])
+
+	const hasEntering = renderedNodes.some((item) => item.phase === 'entering')
+	useEffect(() => {
+		if (!hasEntering) return
+		const frame = requestAnimationFrame(() => {
+			setFadeNodes((previous) =>
+				previous.map((item) => (item.phase === 'entering' ? { ...item, phase: 'present' } : item))
+			)
+		})
+		return () => cancelAnimationFrame(frame)
+	}, [hasEntering, renderedNodes])
+
+	const hasExiting = renderedNodes.some((item) => item.phase === 'exiting')
+	useEffect(() => {
+		if (!hasExiting) return
+		const timeout = window.setTimeout(() => {
+			setFadeNodes((previous) => previous.filter((item) => item.phase !== 'exiting'))
+		}, CLUSTER_FADE_MS)
+		return () => window.clearTimeout(timeout)
+	}, [hasExiting, renderedNodes])
+
+	return renderedNodes
+}
+
+function toPresentFadeNodes(nodes: readonly ClusterNode[]): ClusterFadeNode[] {
+	return nodes.map((node) => ({ node, phase: 'present' }))
+}
+
+function reconcileFadeNodes(
+	previous: readonly ClusterFadeNode[],
+	nextNodes: readonly ClusterNode[]
+): ClusterFadeNode[] {
+	const previousById = new Map(previous.map((item) => [item.node.id, item]))
+	const nextIds = new Set(nextNodes.map((node) => node.id))
+	const next: ClusterFadeNode[] = []
+
+	for (const node of nextNodes) {
+		const previousItem = previousById.get(node.id)
+		next.push({
+			node,
+			phase:
+				previousItem && previousItem.phase !== 'exiting'
+					? previousItem.phase
+					: previousItem
+						? 'present'
+						: 'entering',
+		})
+	}
+
+	for (const item of previous) {
+		if (nextIds.has(item.node.id)) continue
+		next.push(item.phase === 'exiting' ? item : { ...item, phase: 'exiting' })
+	}
+
+	return next
+}
+
+export function clusterFadeClassName(phase: ClusterFadePhase): string {
+	return `tlui-cmt-cluster-fade tlui-cmt-cluster-fade--${phase}`
+}

package/src/canvas/cluster-input.test.ts

@@ -3,7 +3,13 @@ import { describe, expect, it } from 'vitest'
 // This import is red until step 6's filter module is implemented — that is
 // intentional. Implement `cluster-input.ts` per CLUSTERING-STEPS.md step 6
 // until this suite passes, without modifying this file.
-import { collectClusterLeaves } from './cluster-input'
+import type { LeafInput, LeafScreenOffsets } from '../clustering/types'
+import {
+	type ClusterInput,
+	clusterInputEqual,
+	clusterInputIdsEqual,
+	collectClusterLeaves,
+} from './cluster-input'
 import { defaultCommentingOptions, type CommentingOptions } from './options'
 
 const CURRENT_PAGE = 'page:one'
@@ -67,7 +73,7 @@ describe('collectClusterLeaves anchor resolution', () => {
 			stubEditor(),
 			[thread('t1', { type: 'point', x: 12, y: 34 })],
 			null
-		)
+		).leaves
 		expect(leaves).toEqual([{ id: 't1', point: { x: 12, y: 34 } }])
 	})
 
@@ -76,7 +82,7 @@ describe('collectClusterLeaves anchor resolution', () => {
 			stubEditor(),
 			[thread('t1', { type: 'region', x: 10, y: 20, w: 30, h: 40 })],
 			null
-		)
+		).leaves
 		expect(leaves).toEqual([{ id: 't1', point: { x: 40, y: 60 } }])
 	})
 
@@ -88,7 +94,7 @@ describe('collectClusterLeaves anchor resolution', () => {
 			editor,
 			[thread('t1', { type: 'shape', shapeId: 'shape:a' as any, x: 0, y: 0, isPrecise: false })],
 			null
-		)
+		).leaves
 		expect(leaves).toEqual([{ id: 't1', point: { x: 100, y: 5 } }])
 	})
 
@@ -114,7 +120,7 @@ describe('collectClusterLeaves anchor resolution', () => {
 				isPrecise: true,
 			}),
 		]
-		const leaves = collectClusterLeaves(editor, threads, null)
+		const leaves = collectClusterLeaves(editor, threads, null).leaves
 		expect(leaves).toEqual([
 			{ id: 'imprecise', point: { x: 50, y: 50 } },
 			{ id: 'precise', point: { x: 50, y: 25 } },
@@ -135,7 +141,7 @@ describe('collectClusterLeaves anchor resolution', () => {
 				thread('kept', { type: 'point', x: 1, y: 2 }),
 			],
 			null
-		)
+		).leaves
 		expect(leafIds(leaves)).toEqual(['kept'])
 	})
 
@@ -144,7 +150,7 @@ describe('collectClusterLeaves anchor resolution', () => {
 			stubEditor(),
 			[thread('pageThread', { type: 'page' }), thread('kept', { type: 'point', x: 1, y: 2 })],
 			null
-		)
+		).leaves
 		expect(leafIds(leaves)).toEqual(['kept'])
 	})
 })
@@ -158,7 +164,7 @@ describe('collectClusterLeaves filtering', () => {
 				thread('elsewhere', { type: 'point', x: 0, y: 0 }, { pageId: OTHER_PAGE }),
 			],
 			null
-		)
+		).leaves
 		expect(leafIds(leaves)).toEqual(['here'])
 	})
 
@@ -167,10 +173,13 @@ describe('collectClusterLeaves filtering', () => {
 			thread('open', { type: 'point', x: 0, y: 0 }),
 			thread('closed', { type: 'point', x: 10, y: 0 }),
 		]
-		expect(leafIds(collectClusterLeaves(stubEditor(), threads, 'open'))).toEqual(['closed'])
-		expect(leafIds(collectClusterLeaves(stubEditor(), threads, null))).toEqual(['closed', 'open'])
+		expect(leafIds(collectClusterLeaves(stubEditor(), threads, 'open').leaves)).toEqual(['closed'])
+		expect(leafIds(collectClusterLeaves(stubEditor(), threads, null).leaves)).toEqual([
+			'closed',
+			'open',
+		])
 		// an id that matches no thread excludes nothing
-		expect(leafIds(collectClusterLeaves(stubEditor(), threads, 'unknown'))).toEqual([
+		expect(leafIds(collectClusterLeaves(stubEditor(), threads, 'unknown').leaves)).toEqual([
 			'closed',
 			'open',
 		])
@@ -184,12 +193,12 @@ describe('collectClusterLeaves filtering', () => {
 				thread('unresolved', { type: 'point', x: 10, y: 0 }),
 			],
 			null
-		)
+		).leaves
 		expect(leafIds(leaves)).toEqual(['resolved', 'unresolved'])
 	})
 
 	it('returns [] for no threads', () => {
-		expect(collectClusterLeaves(stubEditor(), [], null)).toEqual([])
+		expect(collectClusterLeaves(stubEditor(), [], null).leaves).toEqual([])
 	})
 
 	it('applies every rule at once on a mixed set', () => {
@@ -218,7 +227,7 @@ describe('collectClusterLeaves filtering', () => {
 			thread('openOne', { type: 'point', x: 3, y: 3 }),
 			thread('resolvedOne', { type: 'point', x: 4, y: 4 }, { resolved: true }),
 		]
-		const leaves = collectClusterLeaves(editor, threads, 'openOne')
+		const leaves = collectClusterLeaves(editor, threads, 'openOne').leaves
 		expect(leafIds(leaves)).toEqual(['onShape', 'point', 'region', 'resolvedOne'])
 	})
 
@@ -229,3 +238,128 @@ describe('collectClusterLeaves filtering', () => {
 		expect(JSON.parse(JSON.stringify(threads))).toEqual(snapshot)
 	})
 })
+
+describe('collectClusterLeaves screen offsets', () => {
+	it('is undefined when every pin renders on its anchor', () => {
+		const editor = stubEditor({ 'shape:a': { minX: 0, minY: 0, maxX: 100, maxY: 50 } })
+		const threads = [
+			thread('point', { type: 'point', x: 1, y: 2 }),
+			thread('region', { type: 'region', x: 0, y: 0, w: 5, h: 5 }),
+			thread('precise', {
+				type: 'shape',
+				shapeId: 'shape:a' as any,
+				x: 0.5,
+				y: 0.5,
+				isPrecise: true,
+			}),
+		]
+		expect(collectClusterLeaves(editor, threads, null).screenOffsets).toBeUndefined()
+	})
+
+	it('maps imprecise leaves to their pin inset, and only those', () => {
+		const editor = stubEditor({ 'shape:a': { minX: 0, minY: 0, maxX: 100, maxY: 50 } })
+		const threads = [
+			thread('imprecise', {
+				type: 'shape',
+				shapeId: 'shape:a' as any,
+				x: 0,
+				y: 0,
+				isPrecise: false,
+			}),
+			thread('point', { type: 'point', x: 1, y: 2 }),
+		]
+		const { screenOffsets } = collectClusterLeaves(editor, threads, null)
+		// Default top-right anchor spot: the pin tucks left and down into the shape.
+		expect(screenOffsets).toEqual(new Map([['imprecise', { x: -20, y: 20 }]]))
+	})
+
+	it('excludes threads that produced no leaf', () => {
+		const editor = stubEditor({}) // shape does not resolve
+		const threads = [
+			thread('gone', { type: 'shape', shapeId: 'shape:x' as any, x: 0, y: 0, isPrecise: false }),
+		]
+		const input = collectClusterLeaves(editor, threads, null)
+		expect(input.leaves).toEqual([])
+		expect(input.screenOffsets).toBeUndefined()
+	})
+})
+
+// These two gate the O(N²) rebuild in `useClusterModel`. Both compare the leaves positionally, so
+// the order cases below are what pin the gate to `collectClusterLeaves` walking threads in order.
+const leaf = (id: string, x: number, y: number) => ({ id, point: { x, y } })
+const input = (leaves: LeafInput[], screenOffsets?: LeafScreenOffsets): ClusterInput => ({
+	leaves,
+	screenOffsets,
+})
+
+describe('clusterInputEqual', () => {
+	it('accepts the same leaves at the same positions, whatever the identity', () => {
+		const a = input([leaf('t1', 0, 0), leaf('t2', 10, 20)])
+		expect(clusterInputEqual(a, a)).toBe(true)
+		expect(clusterInputEqual(a, input([leaf('t1', 0, 0), leaf('t2', 10, 20)]))).toBe(true)
+		expect(clusterInputEqual(input([]), input([]))).toBe(true)
+	})
+
+	it('rejects a position change — a moved pin must rebuild the table', () => {
+		expect(clusterInputEqual(input([leaf('t1', 0, 0)]), input([leaf('t1', 0, 0.5)]))).toBe(false)
+		expect(clusterInputEqual(input([leaf('t1', 0, 0)]), input([leaf('t1', 0.5, 0)]))).toBe(false)
+	})
+
+	it('rejects an added, removed, renamed, or reordered leaf', () => {
+		const one = input([leaf('t1', 0, 0)])
+		const two = input([leaf('t1', 0, 0), leaf('t2', 1, 1)])
+		expect(clusterInputEqual(one, two)).toBe(false)
+		expect(clusterInputEqual(two, one)).toBe(false)
+		expect(clusterInputEqual(one, input([leaf('t2', 0, 0)]))).toBe(false)
+		expect(clusterInputEqual(two, input([leaf('t2', 1, 1), leaf('t1', 0, 0)]))).toBe(false)
+	})
+
+	it('rejects an offset change, which prices the same leaves differently', () => {
+		const leaves = [leaf('t1', 0, 0)]
+		const offsets = (x: number) => new Map([['t1', { x, y: 20 }]])
+		expect(clusterInputEqual(input(leaves, offsets(-20)), input(leaves, offsets(-20)))).toBe(true)
+		expect(clusterInputEqual(input(leaves, offsets(-20)), input(leaves, offsets(20)))).toBe(false)
+		// gaining or losing offsets entirely (a pin's precision changed)
+		expect(clusterInputEqual(input(leaves), input(leaves, offsets(-20)))).toBe(false)
+		expect(clusterInputEqual(input(leaves, offsets(-20)), input(leaves))).toBe(false)
+	})
+})
+
+describe('clusterInputIdsEqual', () => {
+	it('ignores positions and offset vectors — this is what defers the rebuild mid-drag', () => {
+		expect(clusterInputIdsEqual(input([leaf('t1', 0, 0)]), input([leaf('t1', 999, 999)]))).toBe(
+			true
+		)
+		// rotating mid-drag turns the inset; deferred like the anchor move it comes with
+		expect(
+			clusterInputIdsEqual(
+				input([leaf('t1', 0, 0)], new Map([['t1', { x: -20, y: 20 }]])),
+				input([leaf('t1', 5, 5)], new Map([['t1', { x: 20, y: -20 }]]))
+			)
+		).toBe(true)
+	})
+
+	it('still rejects an added or removed thread, so those rebuild even mid-drag', () => {
+		const one = input([leaf('t1', 0, 0)])
+		const two = input([leaf('t1', 0, 0), leaf('t2', 1, 1)])
+		expect(clusterInputIdsEqual(one, two)).toBe(false)
+		expect(clusterInputIdsEqual(two, one)).toBe(false)
+		expect(clusterInputIdsEqual(one, input([leaf('t2', 0, 0)]))).toBe(false)
+	})
+
+	it('still rejects a leaf that gained or lost its offset — a precision change, not a gesture', () => {
+		const leaves = [leaf('t1', 0, 0)]
+		expect(
+			clusterInputIdsEqual(input(leaves), input(leaves, new Map([['t1', { x: -20, y: 20 }]])))
+		).toBe(false)
+	})
+
+	it('rejects a reorder', () => {
+		expect(
+			clusterInputIdsEqual(
+				input([leaf('t1', 0, 0), leaf('t2', 1, 1)]),
+				input([leaf('t2', 1, 1), leaf('t1', 0, 0)])
+			)
+		).toBe(false)
+	})
+})

package/src/canvas/cluster-input.ts

@@ -1,15 +1,29 @@
-import type { Editor, TLCommentThread } from 'tldraw'
-import type { LeafInput } from '../clustering/types'
-import { anchorPagePoint } from './thread-state'
+import type { Editor, TLCommentThread, VecLike } from 'tldraw'
+import type { LeafInput, LeafScreenOffsets } from '../clustering/types'
+import { anchorPagePoint, impreciseShapePinInset } from './thread-state'
+
+/** The clustering input for the current page's pinned threads. @internal */
+export interface ClusterInput {
+	/** One leaf per pinned thread, at its anchor page point. */
+	leaves: LeafInput[]
+	/**
+	 * The render offsets of the imprecise pins among the leaves — those draw tucked into their
+	 * shape by a constant screen-px inset rather than on their anchor, and the clustering prices
+	 * their merges at the visual positions. Undefined when every pin renders on its anchor,
+	 * which guarantees a byte-identical offset-unaware clustering run.
+	 */
+	screenOffsets: LeafScreenOffsets | undefined
+}
 
 /** The cluster leaves for the threads pinned on the current page. @internal */
 export function collectClusterLeaves(
 	editor: Editor,
 	threads: readonly TLCommentThread[],
 	openThreadId: string | null
-): LeafInput[] {
+): ClusterInput {
 	const pageId = editor.getCurrentPageId()
 	const leaves: LeafInput[] = []
+	let screenOffsets: Map<string, VecLike> | undefined
 
 	for (const thread of threads) {
 		if (thread.id === openThreadId) continue
@@ -22,7 +36,80 @@ export function collectClusterLeaves(
 			id: thread.id,
 			point: { x: point.x, y: point.y },
 		})
+
+		const inset = impreciseShapePinInset(editor, thread.anchor)
+		if (inset) (screenOffsets ??= new Map()).set(thread.id, inset)
 	}
 
-	return leaves
+	return { leaves, screenOffsets }
+}
+
+/**
+ * Value equality over everything `computeClusterTable` reads. Keeps the input's identity stable
+ * across recomputes that changed nothing, so the O(N²) rebuild only runs when it has to.
+ * @internal
+ */
+export function clusterInputEqual(a: ClusterInput, b: ClusterInput): boolean {
+	if (a === b) return true
+	return (
+		clusterLeavesEqual(a.leaves, b.leaves) && screenOffsetsEqual(a.screenOffsets, b.screenOffsets)
+	)
+}
+
+/**
+ * The same, ignoring everything positional — anchor points and offset vectors alike. The mid-drag
+ * gate: a move defers, but a thread added, removed, or changed precision still rebuilds.
+ * @internal
+ */
+export function clusterInputIdsEqual(a: ClusterInput, b: ClusterInput): boolean {
+	if (a === b) return true
+	return (
+		clusterLeafIdsEqual(a.leaves, b.leaves) &&
+		screenOffsetIdsEqual(a.screenOffsets, b.screenOffsets)
+	)
+}
+
+function screenOffsetsEqual(a: LeafScreenOffsets | undefined, b: LeafScreenOffsets | undefined) {
+	if (a === b) return true
+	if (!a || !b) return false
+	if (a.size !== b.size) return false
+	for (const [id, offset] of b) {
+		const prev = a.get(id)
+		if (!prev || prev.x !== offset.x || prev.y !== offset.y) return false
+	}
+	return true
+}
+
+/** Which leaves carry an offset, ignoring the vectors: a leaf gains or loses one by changing
+ *  precision, which is a record change rather than a gesture. */
+function screenOffsetIdsEqual(a: LeafScreenOffsets | undefined, b: LeafScreenOffsets | undefined) {
+	if (a === b) return true
+	if (!a || !b) return false
+	if (a.size !== b.size) return false
+	for (const id of b.keys()) {
+		if (!a.has(id)) return false
+	}
+	return true
+}
+
+/** Whether two leaf lists have the same threads at the same positions, in the same order. */
+function clusterLeavesEqual(a: readonly LeafInput[], b: readonly LeafInput[]): boolean {
+	if (a === b) return true
+	if (a.length !== b.length) return false
+	for (let i = 0; i < a.length; i++) {
+		const la = a[i]
+		const lb = b[i]
+		if (la.id !== lb.id || la.point.x !== lb.point.x || la.point.y !== lb.point.y) return false
+	}
+	return true
+}
+
+/** Whether two leaf lists contain the same thread ids in the same order, ignoring positions. */
+function clusterLeafIdsEqual(a: readonly LeafInput[], b: readonly LeafInput[]): boolean {
+	if (a === b) return true
+	if (a.length !== b.length) return false
+	for (let i = 0; i < a.length; i++) {
+		if (a[i].id !== b[i].id) return false
+	}
+	return true
 }

package/src/canvas/cluster-model.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { createClusterRuntime } from '../clustering/runtime'
+import type { ClusterNode, ClusterTable, LeafInput } from '../clustering/types'
+import type { ClusterInput } from './cluster-input'
+import { anyFoldedLeafMoved, type ClusterModel } from './cluster-model'
+
+function node(ids: string[], x = 0, y = 0): ClusterNode {
+	const members = ids.slice().sort()
+	return {
+		id: members.length === 1 ? members[0] : `cluster:${members.length}:${members[0]}`,
+		centroid: { x, y },
+		count: members.length,
+		members,
+	}
+}
+
+/** t1 and t2 fold into one badge below zoom 1; t3 sits far away and never merges. */
+const TABLE: ClusterTable = {
+	leaves: [node(['t1'], 0, 0), node(['t2'], 10, 0), node(['t3'], 5000, 0)],
+	events: [
+		{
+			zMerge: 1,
+			zSplit: 2,
+			children: [node(['t1']), node(['t2'])],
+			result: node(['t1', 't2'], 5, 0),
+		},
+	],
+}
+
+/** The rendered partition at `zoom`: below 1 the badge is up, above 2 every pin stands alone. */
+function rendered(zoom: number): ClusterModel {
+	const runtime = createClusterRuntime(TABLE)
+	runtime.seed(zoom)
+	return { runtime, table: TABLE }
+}
+
+const leaf = (id: string, x: number, y: number): LeafInput => ({ id, point: { x, y } })
+const input = (leaves: LeafInput[]): ClusterInput => ({ leaves, screenOffsets: undefined })
+
+const AT_REST = [leaf('t1', 0, 0), leaf('t2', 10, 0), leaf('t3', 5000, 0)]
+
+describe('anyFoldedLeafMoved', () => {
+	it('breaks the freeze when a leaf folded into a badge moves', () => {
+		const model = rendered(0.5)
+		expect([...model.runtime.getVisible().keys()].sort()).toEqual(['cluster:2:t1', 't3'])
+		const next = input([leaf('t1', 40, 0), leaf('t2', 10, 0), leaf('t3', 5000, 0)])
+		expect(anyFoldedLeafMoved(input(AT_REST), next, model)).toBe(true)
+	})
+
+	it('holds the freeze when a visible leaf moves — its pin already rides its anchor', () => {
+		const next = input([leaf('t1', 0, 0), leaf('t2', 10, 0), leaf('t3', 5040, 0)])
+		expect(anyFoldedLeafMoved(input(AT_REST), next, rendered(0.5))).toBe(false)
+		// and with the badge split, the same move of a former badge member is visible too
+		const split = input([leaf('t1', 40, 0), leaf('t2', 10, 0), leaf('t3', 5000, 0)])
+		expect(anyFoldedLeafMoved(input(AT_REST), split, rendered(3))).toBe(false)
+	})
+
+	it('holds the freeze when an orphan moves — it is not in the rendered partition to pop out of', () => {
+		// t4 was added since the last adopted rebuild: it is in the input but not in the rendered
+		// table, so it renders as a plain live pin and no pop-out can ever hold it. Counting it as
+		// folded would rebuild on every pointermove for the rest of the drag.
+		const atRest = [...AT_REST, leaf('t4', 20, 0)]
+		const next = input([...AT_REST, leaf('t4', 60, 0)])
+		expect(anyFoldedLeafMoved(input(atRest), next, rendered(0.5))).toBe(false)
+	})
+
+	it('holds the freeze when a detached leaf moves — it left the badge already', () => {
+		const model = rendered(0.5)
+		model.runtime.detachLeaves(['t1'])
+		expect(
+			anyFoldedLeafMoved(input(AT_REST), input([leaf('t1', 40, 0), ...AT_REST.slice(1)]), model)
+		).toBe(false)
+	})
+
+	it('holds the freeze when nothing moved', () => {
+		expect(anyFoldedLeafMoved(input(AT_REST), input([...AT_REST]), rendered(0.5))).toBe(false)
+	})
+
+	it('holds the freeze with no rendered model yet', () => {
+		const next = input([leaf('t1', 40, 0), leaf('t2', 10, 0), leaf('t3', 5000, 0)])
+		expect(anyFoldedLeafMoved(input(AT_REST), next, null)).toBe(false)
+	})
+
+	it('holds the freeze on mismatched inputs rather than reading past the end', () => {
+		const next = input([leaf('t1', 40, 0), leaf('t2', 10, 0)])
+		expect(anyFoldedLeafMoved(input(AT_REST), next, rendered(0.5))).toBe(false)
+	})
+})