@tldraw/commenting 5.3.0-next.2fa9c61a8de6 → 5.3.0-next.7654e7ac2a02

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
 }