@tldraw/commenting 0.0.0-bootstrap → 5.3.0-canary.04044ed9e96d

package/src/clustering/computeClusterTable.test.ts

@@ -86,27 +86,27 @@ describe('computeClusterTable composition', () => {
 		}
 	})
 
-	it('resolves all defaults from an empty option set (Tc 40, Tu 60, eps 0.12, Dmax 120)', () => {
+	it('resolves all defaults from an empty option set (Tc 22, Tu 26.4, eps 0.7, Dmax 82.5)', () => {
 		const leaves = randomLeaves(30, 7)
 		const table = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
 		const expected = manualPipeline(leaves, {
-			Tc: 40,
-			Tu: 60,
-			eps: 0.12,
-			Dmax: 120,
+			Tc: 22,
+			Tu: 26.4,
+			eps: 0.7,
+			Dmax: 82.5,
 			...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)', () => {
+	it('derives Tu and Dmax from a caller-supplied Tc (Tu = 1.2·Tc, Dmax = 3.75·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,
+			Tu: 60,
+			eps: 0.7,
+			Dmax: 187.5,
 			...ZOOM_BOUNDS,
 		})
 		expect(tableShapes(table)).toEqual(expected.map(eventShape))
@@ -114,11 +114,12 @@ describe('computeClusterTable composition', () => {
 
 	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.
+		// default cap schedules them to merge at 5 (maxSplitZoom / (Tu/Tc) = 6 / 1.2) 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].zMerge).toBe(5)
 		expect(table.events[0].zSplit).toBe(6)
 	})
 
@@ -126,10 +127,10 @@ describe('computeClusterTable composition', () => {
 		const leaves = randomLeaves(30, 29)
 		const table = computeClusterTable(leaves, { Tu: 100, eps: 0, ...ZOOM_BOUNDS })
 		const expected = manualPipeline(leaves, {
-			Tc: 40,
+			Tc: 22,
 			Tu: 100,
 			eps: 0,
-			Dmax: 120,
+			Dmax: 82.5,
 			...ZOOM_BOUNDS,
 		})
 		expect(tableShapes(table)).toEqual(expected.map(eventShape))
@@ -193,9 +194,9 @@ describe('computeClusterTable validation', () => {
 		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, { Tu: 20, ...ZOOM_BOUNDS })).toThrow() // < default Tc 22
 		expect(() => computeClusterTable(leaves, { eps: -0.01, ...ZOOM_BOUNDS })).toThrow()
-		expect(() => computeClusterTable(leaves, { Dmax: 30, ...ZOOM_BOUNDS })).toThrow() // < default Tc 40
+		expect(() => computeClusterTable(leaves, { Dmax: 20, ...ZOOM_BOUNDS })).toThrow() // < default Tc 22
 		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()
@@ -226,8 +227,8 @@ describe('computeClusterTable end-to-end scenarios', () => {
 		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)
+		// events (centroid pricing): four pair births at zMerge 2.2 (zSplit 2.64), two
+		// quads at zMerge 1.1 (zSplit 1.32), the bridge at zMerge 0.55 (zSplit 0.66)
 		const seedAt = (zoom: number) => {
 			const rt = createClusterRuntime(table)
 			rt.seed(zoom)
@@ -235,12 +236,12 @@ describe('computeClusterTable end-to-end scenarios', () => {
 		}
 		// 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'])
+		// zoom 2: below the pair midpoints (√5.81 ≈ 2.41), above the quad midpoint (√1.45 ≈ 1.2)
+		expect(seedAt(2)).toEqual(['cluster:2:p1', 'cluster:2:p3', 'cluster:2:p5', 'cluster:2:p7'])
+		// zoom 1: quads merged, above the bridge midpoint (√0.363 ≈ 0.6)
+		expect(seedAt(1)).toEqual(['cluster:4:p1', 'cluster:4:p5'])
+		// zoom 0.5: below everything → one badge of 8
+		expect(seedAt(0.5)).toEqual(['cluster:8:p1'])
 	})
 
 	it('keeps far-apart groups exactly independent at eps = 0 (bridge pruned by minZoom)', () => {

package/src/clustering/computeClusterTable.ts

@@ -1,7 +1,13 @@
 import { mstEdges } from './mst'
 import { cappedReplay } from './replay'
 import { contract, finalize } from './schedule'
-import type { ClusterNode, ClusterOptions, ClusterTable, LeafInput } from './types'
+import type {
+	ClusterNode,
+	ClusterOptions,
+	ClusterTable,
+	LeafInput,
+	LeafScreenOffsets,
+} from './types'
 
 interface ResolvedClusterOptions {
 	Tc: number
@@ -13,10 +19,13 @@ interface ResolvedClusterOptions {
 	maxSplitZoom: number
 }
 
-/** @public */
+/** @internal */
 export function computeClusterTable(
 	leaves: readonly LeafInput[],
-	options: ClusterOptions
+	options: ClusterOptions,
+	// Render offsets for markers that draw off their anchor (imprecise pins), keyed by leaf id.
+	// Omitted or empty, the run is identical — output and code paths — to an offset-unaware one.
+	screenOffsets?: LeafScreenOffsets
 ): ClusterTable {
 	const opts = resolveOptions(options)
 	const leafNodes = leaves.map(leafToNode)
@@ -26,7 +35,7 @@ export function computeClusterTable(
 		return { events: [], leaves: leafNodes }
 	}
 
-	const raw = cappedReplay(leaves, edges, { Tc: opts.Tc, Dmax: opts.Dmax })
+	const raw = cappedReplay(leaves, edges, { Tc: opts.Tc, Dmax: opts.Dmax }, screenOffsets)
 	const contracted = contract(raw, opts.eps)
 	const events = finalize(contracted, {
 		Tc: opts.Tc,
@@ -40,10 +49,10 @@ export function computeClusterTable(
 }
 
 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 Tc = options.Tc ?? 22
+	const Tu = options.Tu ?? 1.2 * Tc
+	const eps = options.eps ?? 0.7
+	const Dmax = options.Dmax ?? 3.75 * Tc
 	const maxSplitZoom = options.maxSplitZoom ?? 6
 	const { minZoom, maxZoom } = options
 

package/src/clustering/replay.test.ts

@@ -51,7 +51,6 @@ function eventShapes(events: RawMergeEvent[]) {
 	return events.map(eventShape)
 }
 
-// --- Reference oracle -------------------------------------------------------
 // Direct transcription of contract clause 4 (CLUSTERING-STEPS.md step 2): at
 // each of the n−1 steps, evaluate every unfired MST edge's zEff against the
 // CURRENT clusters and fire the highest, tie-broken by the edge's normalized
@@ -181,8 +180,6 @@ function referenceReplay(
 	return events
 }
 
-// --- Shared invariant assertions --------------------------------------------
-
 function expectNonIncreasingZ(events: RawMergeEvent[]) {
 	for (let i = 1; i < events.length; i++) {
 		expect(events[i].z).toBeLessThanOrEqual(events[i - 1].z)
@@ -260,8 +257,6 @@ function expectCentroids(events: RawMergeEvent[], leaves: readonly LeafInput[])
 	}
 }
 
-// --- Fixtures ----------------------------------------------------------------
-
 describe('cappedReplay fixtures', () => {
 	it('exports the pinned D_FLOOR constant', () => {
 		expect(D_FLOOR).toBe(1e-9)
@@ -409,8 +404,6 @@ describe('cappedReplay fixtures', () => {
 	})
 })
 
-// --- Properties against the reference oracle ---------------------------------
-
 describe('cappedReplay vs reference simulator', () => {
 	const OPTION_SETS = [
 		{ Tc: 40, Dmax: 120 }, // default shape

package/src/clustering/replay.ts

@@ -1,17 +1,20 @@
-import type { ClusterNode, LeafInput, MstEdge, RawMergeEvent } from './types'
+import type { ClusterNode, LeafInput, LeafScreenOffsets, MstEdge, RawMergeEvent } from './types'
 
 export const D_FLOOR = 1e-9
 
 export function cappedReplay(
 	leaves: readonly LeafInput[],
 	edges: readonly MstEdge[],
-	opts: { Tc: number; Dmax: number }
+	opts: { Tc: number; Dmax: number },
+	// Render offsets for markers that draw off their anchor (imprecise pins). Omitted or empty,
+	// every code path below is the offset-unaware original — pricing, events, and floats alike.
+	screenOffsets?: LeafScreenOffsets
 ): RawMergeEvent[] {
 	validateOptions(opts)
 
 	if (edges.length === 0) return []
 
-	const clusters = new ClusterState(leaves)
+	const clusters = new ClusterState(leaves, screenOffsets)
 	const heap = new EdgeMaxHeap(edges, leaves)
 	// Edges incident to each current cluster root, for eager repricing: a merge
 	// moves the result's centroid, which can RAISE an incident edge's key (the
@@ -95,19 +98,64 @@ function zForRoots(
 	clusters: ClusterState,
 	opts: { Tc: number; Dmax: number }
 ): number {
-	if (edge.d < D_FLOOR) return Number.POSITIVE_INFINITY
-	// Badge-anchored gap pricing: clusters render as badges at their centroids,
-	// so the merge is priced by the distance between the rendered centers, not
-	// the nearest members. For leaves the two are identical; for clusters the
-	// centroid distance is larger, so groups merge later than their closest
-	// members would suggest — matching what the user actually sees.
-	// (Coincident CENTROIDS with non-coincident members leave the gap term
-	// Infinity and the fit term finite — the min stays finite, no special case.)
-	const gap = opts.Tc / clusters.centroidDistance(aRoot, bRoot)
+	// Null unless offset pricing is active AND this pair's mean render offsets differ. Every
+	// other pair — including every pair when no offsets were passed — takes the branch below,
+	// which is the offset-unaware pricing verbatim.
+	const off = clusters.offsetDelta(aRoot, bRoot)
+	if (off === null) {
+		if (edge.d < D_FLOOR) return Number.POSITIVE_INFINITY
+		// Badge-anchored gap pricing: clusters render as badges at their centroids,
+		// so the merge is priced by the distance between the rendered centers, not
+		// the nearest members. For leaves the two are identical; for clusters the
+		// centroid distance is larger, so groups merge later than their closest
+		// members would suggest — matching what the user actually sees.
+		// (Coincident CENTROIDS with non-coincident members leave the gap term
+		// Infinity and the fit term finite — the min stays finite, no special case.)
+		const gap = opts.Tc / clusters.centroidDistance(aRoot, bRoot)
+		const fit = opts.Dmax / clusters.unionBboxDiag(aRoot, bRoot)
+		return Math.min(gap, fit)
+	}
+
+	// Offset-aware gap pricing: these markers render at `z·centroid + meanOffset`, so their
+	// visual distance at zoom z is |z·ΔC + Δō| and the merge prices at its Tc crossing. When
+	// that distance never reaches Tc (the constant offsets hold the visuals apart harder than
+	// the anchors close), the pair prices at 0 — visually never mergeable, pruned by finalize's
+	// minZoom cut. No D_FLOOR fast path here: coincident anchors with differing offsets are a
+	// constant |Δō| apart on screen, which is exactly the ΔC = 0 case below.
+	const dc = clusters.centroidDelta(aRoot, bRoot)
+	if (dc.x === 0 && dc.y === 0) {
+		return Math.hypot(off.x, off.y) < opts.Tc ? Number.POSITIVE_INFINITY : 0
+	}
+	const gap = largestVisualCrossing(dc.x, dc.y, off.x, off.y, opts.Tc)
+	if (gap === null) return 0
 	const fit = opts.Dmax / clusters.unionBboxDiag(aRoot, bRoot)
 	return Math.min(gap, fit)
 }
 
+/**
+ * The largest positive root of `|z·ΔC + Δō| = level`, i.e. of
+ * `|ΔC|²·z² + 2(ΔC·Δō)·z + (|Δō|² − level²) = 0` — the zoom at which two offset markers are
+ * exactly `level` screen px apart, with the distance below the level for every smaller zoom
+ * (matching the "merged at z ≤ threshold" model; a lower second crossing, where opposed offsets
+ * push the visuals back above the level near z = 0, is deliberately collapsed). Null when the
+ * visual distance never reaches the level. Callers handle ΔC = 0 (constant distance) themselves.
+ */
+function largestVisualCrossing(
+	dcx: number,
+	dcy: number,
+	dox: number,
+	doy: number,
+	level: number
+): number | null {
+	const a = dcx * dcx + dcy * dcy
+	const b = 2 * (dcx * dox + dcy * doy)
+	const c = dox * dox + doy * doy - level * level
+	const disc = b * b - 4 * a * c
+	if (disc < 0) return null
+	const z = (-b + Math.sqrt(disc)) / (2 * a)
+	return z > 0 ? z : null
+}
+
 class ClusterState {
 	private readonly parent: Int32Array
 	private readonly minX: Float64Array
@@ -120,8 +168,13 @@ class ClusterState {
 	private readonly nodes: ClusterNode[]
 	private readonly memberLists: string[][]
 	private readonly minMemberIds: string[]
+	// Per-cluster sums of member render offsets (screen px), maintained like the centroid sums.
+	// Null when no offsets were passed — offsetDelta() then answers null unconditionally, which
+	// routes every pricing call down the offset-unaware path.
+	private readonly offsetX: Float64Array | null
+	private readonly offsetY: Float64Array | null
 
-	constructor(leaves: readonly LeafInput[]) {
+	constructor(leaves: readonly LeafInput[], screenOffsets?: LeafScreenOffsets) {
 		const n = leaves.length
 		this.parent = new Int32Array(n)
 		this.minX = new Float64Array(n)
@@ -135,6 +188,21 @@ class ClusterState {
 		this.memberLists = new Array(n)
 		this.minMemberIds = new Array(n)
 
+		if (screenOffsets !== undefined && screenOffsets.size > 0) {
+			this.offsetX = new Float64Array(n)
+			this.offsetY = new Float64Array(n)
+			for (let i = 0; i < n; i++) {
+				const offset = screenOffsets.get(leaves[i].id)
+				if (offset) {
+					this.offsetX[i] = offset.x
+					this.offsetY[i] = offset.y
+				}
+			}
+		} else {
+			this.offsetX = null
+			this.offsetY = null
+		}
+
 		for (let i = 0; i < n; i++) {
 			const leaf = leaves[i]
 			this.parent[i] = i
@@ -176,6 +244,24 @@ class ClusterState {
 		)
 	}
 
+	centroidDelta(aRoot: number, bRoot: number): { x: number; y: number } {
+		return {
+			x: this.centroidX[aRoot] - this.centroidX[bRoot],
+			y: this.centroidY[aRoot] - this.centroidY[bRoot],
+		}
+	}
+
+	/** The difference of the two clusters' mean render offsets (screen px), or null when it's
+	 *  zero — including always when no offsets were passed. Null routes pricing down the
+	 *  offset-unaware path. */
+	offsetDelta(aRoot: number, bRoot: number): { x: number; y: number } | null {
+		if (this.offsetX === null || this.offsetY === null) return null
+		const x = this.offsetX[aRoot] / this.counts[aRoot] - this.offsetX[bRoot] / this.counts[bRoot]
+		const y = this.offsetY[aRoot] / this.counts[aRoot] - this.offsetY[bRoot] / this.counts[bRoot]
+		if (x === 0 && y === 0) return null
+		return { x, y }
+	}
+
 	unionBboxDiag(aRoot: number, bRoot: number): number {
 		const minX = Math.min(this.minX[aRoot], this.minX[bRoot])
 		const minY = Math.min(this.minY[aRoot], this.minY[bRoot])
@@ -224,6 +310,10 @@ class ClusterState {
 		this.nodes[leftRoot] = result
 		this.memberLists[leftRoot] = members
 		this.minMemberIds[leftRoot] = members[0]
+		if (this.offsetX !== null && this.offsetY !== null) {
+			this.offsetX[leftRoot] += this.offsetX[rightRoot]
+			this.offsetY[leftRoot] += this.offsetY[rightRoot]
+		}
 
 		return { z, children: [left, right], result }
 	}
@@ -253,11 +343,29 @@ interface HeapEntry {
 
 class EdgeMaxHeap {
 	private readonly items: HeapEntry[] = []
-
-	constructor(
-		private readonly edges: readonly MstEdge[],
-		private readonly leaves: readonly LeafInput[]
-	) {}
+	// Per-edge normalized (lo, hi) id pair for the z tie-break, precomputed once so comparisons
+	// allocate nothing. With coincident anchors every edge prices to the same z (+Infinity), so
+	// the tie-break runs on nearly every comparison of a rebuild — allocating the pair there
+	// churned millions of short-lived tuples.
+	private readonly loIds: string[]
+	private readonly hiIds: string[]
+
+	constructor(edges: readonly MstEdge[], leaves: readonly LeafInput[]) {
+		const n = edges.length
+		this.loIds = new Array(n)
+		this.hiIds = new Array(n)
+		for (let i = 0; i < n; i++) {
+			const aId = leaves[edges[i].a].id
+			const bId = leaves[edges[i].b].id
+			if (aId < bId) {
+				this.loIds[i] = aId
+				this.hiIds[i] = bId
+			} else {
+				this.loIds[i] = bId
+				this.hiIds[i] = aId
+			}
+		}
+	}
 
 	peek(): HeapEntry | undefined {
 		return this.items[0]
@@ -282,7 +390,11 @@ class EdgeMaxHeap {
 	higherPriority(a: HeapEntry, b: HeapEntry): boolean {
 		if (a.z > b.z) return true
 		if (a.z < b.z) return false
-		return edgeIdPairLess(this.edges[a.edgeIndex], this.edges[b.edgeIndex], this.leaves)
+		// Tie-break on the normalized leaf-id pair, ascending.
+		const aLo = this.loIds[a.edgeIndex]
+		const bLo = this.loIds[b.edgeIndex]
+		if (aLo !== bLo) return aLo < bLo
+		return this.hiIds[a.edgeIndex] < this.hiIds[b.edgeIndex]
 	}
 
 	private siftUp(index: number) {
@@ -311,16 +423,3 @@ class EdgeMaxHeap {
 		}
 	}
 }
-
-function edgeIdPairLess(a: MstEdge, b: MstEdge, leaves: readonly LeafInput[]): boolean {
-	const [aLo, aHi] = normalizedEdgeIds(a, leaves)
-	const [bLo, bHi] = normalizedEdgeIds(b, leaves)
-	if (aLo !== bLo) return aLo < bLo
-	return aHi < bHi
-}
-
-function normalizedEdgeIds(edge: MstEdge, leaves: readonly LeafInput[]): [string, string] {
-	const aId = leaves[edge.a].id
-	const bId = leaves[edge.b].id
-	return aId < bId ? [aId, bId] : [bId, aId]
-}