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

package/src/clustering/runtime.test.ts

@@ -5,8 +5,6 @@ import { createClusterRuntime } from './runtime'
 import { contract, finalize } from './schedule'
 import { ClusterNode, ClusterTable, LeafInput, MergeEvent } from './types'
 
-// --- Synthetic builders --------------------------------------------------------
-
 function node(ids: string[], x = 0, y = 0): ClusterNode {
 	const members = ids.slice().sort()
 	return {
@@ -79,8 +77,6 @@ function microTraceTable(): ClusterTable {
 	}
 }
 
-// --- Fixtures -------------------------------------------------------------------
-
 describe('createClusterRuntime micro-trace (CLUSTERING.md §8.5)', () => {
 	it('walks the exact documented trace', () => {
 		const table = microTraceTable()
@@ -239,8 +235,6 @@ describe('createClusterRuntime edge cases', () => {
 	})
 })
 
-// --- Property tests against real pipeline tables --------------------------------
-
 function leaf(id: string, x: number, y: number): LeafInput {
 	return { id, point: { x, y } }
 }
@@ -460,6 +454,7 @@ describe('createClusterRuntime seedFrom (carryover seeding)', () => {
 			])
 		)
 		expect(rt.k).toBe(1)
+		expect(rt.getSuppressedCount()).toBe(0)
 		expect(visibleIds(rt)).toEqual(['cluster:3:a', 'd'])
 	})
 
@@ -477,7 +472,8 @@ describe('createClusterRuntime seedFrom (carryover seeding)', () => {
 				[D.id, D],
 			])
 		)
-		expect(rt.k).toBe(0)
+		expect(rt.k).toBe(1)
+		expect(rt.getSuppressedCount()).toBe(1)
 		expect(visibleIds(rt)).toEqual(['a', 'b', 'c', 'd'])
 	})
 
@@ -512,7 +508,9 @@ describe('createClusterRuntime seedFrom (carryover seeding)', () => {
 		const table = microTraceTable()
 		const rt = createClusterRuntime(table)
 		rt.seedFrom(5, new Map())
-		expect(rt.k).toBe(0)
+		expect(rt.k).toBe(1)
+		expect(rt.getSuppressedCount()).toBe(1)
+		expect(visibleIds(rt)).toEqual(['a', 'b', 'c', 'd'])
 		const partial = node(['a', 'b'], 5, 0)
 		rt.seedFrom(
 			5,
@@ -522,7 +520,9 @@ describe('createClusterRuntime seedFrom (carryover seeding)', () => {
 				[D.id, D],
 			])
 		)
-		expect(rt.k).toBe(0)
+		expect(rt.k).toBe(1)
+		expect(rt.getSuppressedCount()).toBe(1)
+		expect(visibleIds(rt)).toEqual(['a', 'b', 'c', 'd'])
 	})
 
 	it('membership in a superset cluster counts as merged', () => {
@@ -534,10 +534,58 @@ describe('createClusterRuntime seedFrom (carryover seeding)', () => {
 		expect(visibleIds(rt)).toEqual(['cluster:4:a'])
 	})
 
-	it('classification stops at the first inactive event (prefix cut is conservative)', () => {
-		// Two independent band events at zoom 4.5. The first is split in history, the
-		// second merged — but active events must be a prefix, so the second resolves
-		// to split (conservative: never merges anything history did not sanction).
+	it('carries over mixed band states exactly (split before merged in table order)', () => {
+		// Two independent band events at zoom 4.5: the earlier-sorted one split in history,
+		// the later one merged. The old prefix cut forced the second to split (the mass-split
+		// bug); with suppression the carryover is exact — each keeps its own state.
+		const AB = node(['a', 'b'], 5, 0)
+		const CD = node(['c', 'd'], 105, 0)
+		const table: ClusterTable = {
+			events: [mev(4, 6, [A, B], AB), mev(3, 5, [C, D], CD)],
+			leaves: [A, B, C, D],
+		}
+		const rt = createClusterRuntime(table)
+		rt.seedFrom(
+			4.5,
+			new Map([
+				[A.id, A],
+				[B.id, B],
+				[CD.id, CD],
+			])
+		)
+		expect(rt.k).toBe(2)
+		expect(rt.getSuppressedCount()).toBe(1)
+		expect(visibleIds(rt)).toEqual(['a', 'b', 'cluster:2:c'])
+	})
+
+	it('a suppressed event merges (heals) when a zoom-out crosses its own zMerge', () => {
+		const AB = node(['a', 'b'], 5, 0)
+		const CD = node(['c', 'd'], 105, 0)
+		const table: ClusterTable = {
+			events: [mev(4, 6, [A, B], AB), mev(3, 5, [C, D], CD)],
+			leaves: [A, B, C, D],
+		}
+		const rt = createClusterRuntime(table)
+		rt.seedFrom(
+			4.5,
+			new Map([
+				[A.id, A],
+				[B.id, B],
+				[CD.id, CD],
+			])
+		)
+		const versionBefore = rt.version
+		rt.onCamera(4.4) // still inside AB's band: nothing happens
+		expect(rt.version).toBe(versionBefore)
+		rt.onCamera(3.9) // below AB's zMerge (4): the held-out merge fires at its own threshold
+		expect(rt.version).toBeGreaterThan(versionBefore)
+		expect(rt.k).toBe(2)
+		expect(rt.getSuppressedCount()).toBe(0)
+		expect(visibleIds(rt)).toEqual(['cluster:2:a', 'cluster:2:c'])
+		expectPostconditions(rt, table, 3.9)
+	})
+
+	it('the split walk retreats past a suppressed event without corrupting the partition', () => {
 		const AB = node(['a', 'b'], 5, 0)
 		const CD = node(['c', 'd'], 105, 0)
 		const table: ClusterTable = {
@@ -553,8 +601,52 @@ describe('createClusterRuntime seedFrom (carryover seeding)', () => {
 				[CD.id, CD],
 			])
 		)
+		rt.onCamera(5.5) // past CD's zSplit (5): CD splits; suppressed AB stays put
+		expect(rt.k).toBe(1)
+		expect(rt.getSuppressedCount()).toBe(1)
+		expect(visibleIds(rt)).toEqual(['a', 'b', 'c', 'd'])
+		rt.onCamera(6.5) // past AB's zSplit (6): retreat past the suppressed (never-applied) event
 		expect(rt.k).toBe(0)
+		expect(rt.getSuppressedCount()).toBe(0)
 		expect(visibleIds(rt)).toEqual(['a', 'b', 'c', 'd'])
+		rt.onCamera(3.9) // zoom back out: normal cursor walk from a clean state
+		expect(rt.k).toBe(1)
+		expect(visibleIds(rt)).toEqual(['c', 'cluster:2:a', 'd'])
+		expectPostconditions(rt, table, 3.9)
+	})
+
+	it('heals a suppressed event whose result a later event consumes, in one zoom-out jump', () => {
+		// E1 consumes E0's result, so a single jump past both thresholds must apply E0 first.
+		// Applying E1 first would no-op its delete of the never-applied ABC and then re-add ABC
+		// on top of ABCD, covering a, b and c twice.
+		const ABC = node(['a', 'b', 'c'], 10, 0)
+		const ABCD = node(['a', 'b', 'c', 'd'], 32.5, 0)
+		const table: ClusterTable = {
+			events: [mev(4, 6, [A, B, C], ABC), mev(1, 1.5, [ABC, D], ABCD)],
+			leaves: [A, B, C, D],
+		}
+		const rt = createClusterRuntime(table)
+		// previous partition: everything split apart, so E0 seeds suppressed inside its band
+		rt.seedFrom(
+			5,
+			new Map([
+				[A.id, A],
+				[B.id, B],
+				[C.id, C],
+				[D.id, D],
+			])
+		)
+		expect(rt.getSuppressedCount()).toBe(1)
+
+		rt.onCamera(0.9) // one jump past E0's zMerge (4) and E1's zMerge (1)
+
+		expect(rt.getSuppressedCount()).toBe(0)
+		expect(rt.k).toBe(2)
+		expect(visibleIds(rt)).toEqual(['cluster:4:a'])
+		// conservation: every leaf is covered exactly once
+		const members = [...rt.getVisible().values()].flatMap((n) => n.members)
+		expect(members.slice().sort()).toEqual(['a', 'b', 'c', 'd'])
+		expectPostconditions(rt, table, 0.9)
 	})
 
 	it('seedFrom followed by onCamera at the same zoom is a no-op', () => {
@@ -594,3 +686,165 @@ describe('createClusterRuntime seedFrom (carryover seeding)', () => {
 		expect(() => rt.seedFrom(NaN, new Map())).toThrow()
 	})
 })
+
+describe('createClusterRuntime detachLeaf (local partition edits)', () => {
+	it('shrinks the containing badge in place: members, count, centroid', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4) // P = a+b+c visible, d separate
+		const versionBefore = rt.version
+		rt.detachLeaf('a')
+		expect(rt.version).toBeGreaterThan(versionBefore)
+		expect(rt.getDetachedCount()).toBe(1)
+		const patchedP = rt.getVisible().get(P.id)!
+		expect(patchedP.members).toEqual(['b', 'c'])
+		expect(patchedP.count).toBe(2)
+		// centroid recomputed from the remaining leaves: B (10,0), C (20,0)
+		expect(patchedP.centroid).toEqual({ x: 15, y: 0 })
+		// keeps the structural id so cursor events keep addressing it
+		expect(patchedP.id).toBe(P.id)
+		// everything else untouched
+		expect(rt.getVisible().get('d')).toEqual(D)
+		expect(rt.getVisible().size).toBe(2)
+	})
+
+	it('is idempotent and ignores unknown ids', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4)
+		rt.detachLeaf('a')
+		const version = rt.version
+		rt.detachLeaf('a')
+		rt.detachLeaf('nonexistent')
+		expect(rt.version).toBe(version)
+		expect(rt.getDetachedCount()).toBe(1)
+	})
+
+	it('collapses a badge to its surviving leaf, and to nothing', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4)
+		rt.detachLeaf('a')
+		rt.detachLeaf('b')
+		// P = {a,b,c} minus a,b → the leaf node c, keyed by its own id
+		expect(rt.getVisible().get('c')).toEqual(C)
+		expect(rt.getVisible().has(P.id)).toBe(false)
+		rt.detachLeaf('c')
+		expect(visibleIds(rt)).toEqual(['d'])
+	})
+
+	it('removes a leaf that is visible as its own pin', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(8) // everything split
+		rt.detachLeaf('a')
+		expect(visibleIds(rt)).toEqual(['b', 'c', 'd'])
+	})
+
+	it('zoom walks stay correct while patches are active (split)', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4)
+		rt.detachLeaf('a')
+		rt.onCamera(6.5) // past P's zSplit (6): structural split of a+b+c
+		expect(rt.k).toBe(0)
+		// resolved view: a stays gone, b/c/d as pins — the split itself changed nothing for a
+		expect(visibleIds(rt)).toEqual(['b', 'c', 'd'])
+	})
+
+	it('zoom walks stay correct while patches are active (merge)', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4)
+		rt.detachLeaf('a')
+		rt.onCamera(0.9) // below E1's zMerge (1): P+D merge into Q
+		expect(rt.k).toBe(2)
+		const patchedQ = rt.getVisible().get(Q.id)!
+		expect(patchedQ.members).toEqual(['b', 'c', 'd'])
+		expect(patchedQ.count).toBe(3)
+		// mean of B (10,0), C (20,0), D (100,0)
+		expect(patchedQ.centroid.x).toBeCloseTo(130 / 3)
+		expect(rt.getVisible().size).toBe(1)
+	})
+
+	it('seed and seedFrom clear detaches', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4)
+		rt.detachLeaf('a')
+		rt.seed(4)
+		expect(rt.getDetachedCount()).toBe(0)
+		expect(rt.getVisible().get(P.id)).toEqual(P)
+		rt.detachLeaf('a')
+		rt.seedFrom(
+			4,
+			new Map([
+				[P.id, P],
+				[D.id, D],
+			])
+		)
+		expect(rt.getDetachedCount()).toBe(0)
+		expect(rt.getVisible().get(P.id)).toEqual(P)
+	})
+
+	it('detachLeaves batches a whole set into one version bump', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4) // P = a+b+c visible, d separate
+		const versionBefore = rt.version
+		rt.detachLeaves(['a', 'b'])
+		expect(rt.version).toBe(versionBefore + 1)
+		expect(rt.getDetachedCount()).toBe(2)
+		// P = {a,b,c} minus a,b → the leaf node c, keyed by its own id
+		expect(rt.getVisible().get('c')).toEqual(C)
+		expect(rt.getVisible().has(P.id)).toBe(false)
+		expect(visibleIds(rt)).toEqual(['c', 'd'])
+	})
+
+	it('detachLeaves matches the equivalent one-at-a-time detaches', () => {
+		const makeDetached = (detach: (rt: ReturnType<typeof createClusterRuntime>) => void) => {
+			const rt = createClusterRuntime(microTraceTable())
+			rt.seed(4)
+			detach(rt)
+			return rt
+		}
+		const batched = makeDetached((rt) => rt.detachLeaves(['a', 'd']))
+		const oneByOne = makeDetached((rt) => {
+			rt.detachLeaf('a')
+			rt.detachLeaf('d')
+		})
+		expect(visibleIds(batched)).toEqual(visibleIds(oneByOne))
+		for (const id of visibleIds(batched)) {
+			expect(batched.getVisible().get(id)).toEqual(oneByOne.getVisible().get(id))
+		}
+	})
+
+	it('detachLeaves skips unknown and already-detached ids, and no-ops on an empty batch', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4)
+		rt.detachLeaf('a')
+		const version = rt.version
+		const visible = rt.getVisible()
+		rt.detachLeaves([])
+		rt.detachLeaves(['a', 'nonexistent'])
+		expect(rt.version).toBe(version)
+		expect(rt.getDetachedCount()).toBe(1)
+		expect(rt.getVisible()).toBe(visible)
+		// a mixed batch still applies the new id in a single bump
+		rt.detachLeaves(['a', 'b', 'nonexistent'])
+		expect(rt.version).toBe(version + 1)
+		expect(rt.getDetachedCount()).toBe(2)
+	})
+
+	it('getVisible returns a stable reference until the partition changes', () => {
+		const table = microTraceTable()
+		const rt = createClusterRuntime(table)
+		rt.seed(4)
+		rt.detachLeaf('a')
+		const first = rt.getVisible()
+		expect(rt.getVisible()).toBe(first)
+		rt.detachLeaf('b')
+		expect(rt.getVisible()).not.toBe(first)
+	})
+})

package/src/clustering/runtime.ts

@@ -1,28 +1,49 @@
 import type { ClusterNode, ClusterTable, MergeEvent } from './types'
 
-/** @public */
+/** @internal */
 export interface ClusterRuntime {
-	/** Events[0..k) are active. Exposed for tests and debugging. */
+	/** Events[0..k) are in the cursor (applied unless suppressed). Exposed for tests/debugging. */
 	readonly k: number
-	/** Reset state from scratch for the given zoom (cold start / after rebuild). */
+	/**
+	 * Increments whenever the displayed partition changes. Subscribe to this, not `k`: detaches
+	 * and suppressed-event healing change the partition without moving the cursor.
+	 */
+	readonly version: number
+	/** Number of suppressed band events currently inside the cursor. Exposed for tests. */
+	getSuppressedCount(): number
+	/** Number of leaves currently detached from the displayed partition. Exposed for tests. */
+	getDetachedCount(): number
+	/** Reset state from scratch for the given zoom (cold start / after rebuild). Clears detaches. */
 	seed(zoom: number): void
 	/**
-	 * Reset state for the given zoom, carrying hysteresis state over from a previous partition
-	 * (the visible map of the model being replaced). Threshold-forced events ignore history:
-	 * zoom \<= zMerge is always active, zoom \>= zSplit always inactive. An event inside its band
-	 * is active iff its members were merged together in `previous`; a band event with no history
-	 * (e.g. introduced by the rebuild) stays inactive until the next zoom-out crosses its zMerge.
-	 * Active events must form a prefix of the table, so classification stops at the first
-	 * inactive event; later band-active events conservatively resolve to split.
+	 * Reset state for the given zoom, carrying hysteresis state over from a previous partition.
+	 * Threshold-forced events ignore history: zoom \<= zMerge is always merged, zoom \>= zSplit always
+	 * split. An event inside its band keeps its previous state; one that was unmerged (or has no
+	 * history) stays suppressed inside the cursor until a zoom-out crosses its own zMerge. Carryover is
+	 * exact — no group changes state because of the swap alone. Clears detaches.
 	 */
 	seedFrom(zoom: number, previous: ReadonlyMap<string, ClusterNode>): void
 	/** Advance/retreat the cursor for a camera change. No-op if zoom sits inside all bands. */
 	onCamera(zoom: number): void
-	/** The current partition: cluster id → node. Do not mutate. */
+	/**
+	 * Remove one leaf from the displayed partition without touching the event table. Local by
+	 * construction: only the nodes containing the leaf change, so a deletion, pop-out, or thread-open
+	 * never re-flows the rest of the document. The table's thresholds around the detached leaf go
+	 * stale; the caller is expected to adopt a corrected rebuild (with seedFrom) at the next zoom-out.
+	 * Unknown or already-detached ids are no-ops.
+	 */
+	detachLeaf(leafId: string): void
+	/**
+	 * Batch form of {@link ClusterRuntime.detachLeaf}: detach every given leaf with a single
+	 * patch rebuild and a single version bump. Ids that are unknown or already detached are
+	 * skipped; if nothing new detaches, nothing changes.
+	 */
+	detachLeaves(leafIds: Iterable<string>): void
+	/** The displayed partition: cluster id → node, with detaches applied. Do not mutate. */
 	getVisible(): ReadonlyMap<string, ClusterNode>
 }
 
-/** @public */
+/** @internal */
 export function createClusterRuntime(table: ClusterTable): ClusterRuntime {
 	return new ClusterRuntimeImpl(table)
 }
@@ -30,21 +51,48 @@ export function createClusterRuntime(table: ClusterTable): ClusterRuntime {
 class ClusterRuntimeImpl implements ClusterRuntime {
 	// mutable internally; readonly through the ClusterRuntime interface
 	k = 0
+	version = 0
+	// Structural partition: exactly leaves + applied events, never patched. The cursor invariants
+	// live here, untouched by detaches — resolution to the displayed partition happens at read
+	// time in getVisible().
 	private visible = new Map<string, ClusterNode>()
 	private seeded = false
+	// Indices (< k) of band events held unmerged by seedFrom carryover. The single cursor can only
+	// express "merged up to here", but a carried-over partition can be "merged except these". Self-
+	// draining: an entry leaves via onCamera when the zoom crosses its zMerge or its zSplit.
+	private suppressed = new Set<number>()
+	// Leaves removed from the displayed partition (deleted / popped out / opened). Patches map
+	// each structural node containing a detached leaf to its displayed replacement (or null to
+	// drop it). Rebuilt from the detached set; cleared by seed/seedFrom.
+	private detached = new Set<string>()
+	private patched = new Map<string, ClusterNode | null>()
+	private leafById: Map<string, ClusterNode> | null = null
+	private resolvedCache: { version: number; map: Map<string, ClusterNode> } | null = null
 
 	constructor(private readonly table: ClusterTable) {
 		this.resetVisible()
 	}
 
+	getSuppressedCount(): number {
+		return this.suppressed.size
+	}
+
+	getDetachedCount(): number {
+		return this.detached.size
+	}
+
 	seed(zoom: number): void {
 		validateZoom(zoom)
 		this.k = seedCount(this.table.events, zoom)
+		this.suppressed.clear()
+		this.detached.clear()
+		this.patched.clear()
 		this.resetVisible()
 		for (let i = 0; i < this.k; i++) {
 			applyEvent(this.visible, this.table.events[i])
 		}
 		this.seeded = true
+		this.version++
 	}
 
 	seedFrom(zoom: number, previous: ReadonlyMap<string, ClusterNode>): void {
@@ -56,21 +104,32 @@ class ClusterRuntimeImpl implements ClusterRuntime {
 			}
 		}
 
+		// Cut the cursor purely on split thresholds. zSplit is non-increasing down the table, so
+		// everything past the first mandatory split (zoom >= zSplit) is also mandatorily split —
+		// this cut can never conflict with an event that should be merged.
 		const events = this.table.events
 		let k = 0
-		while (k < events.length) {
-			const event = events[k]
-			if (zoom >= event.zSplit) break
-			if (zoom > event.zMerge && !wasMergedTogether(event.result.members, ownerByMember)) break
+		while (k < events.length && zoom < events[k].zSplit) {
 			k++
 		}
 
 		this.k = k
+		this.suppressed.clear()
+		this.detached.clear()
+		this.patched.clear()
 		this.resetVisible()
 		for (let i = 0; i < k; i++) {
-			applyEvent(this.visible, events[i])
+			const event = events[i]
+			if (zoom > event.zMerge && !wasMergedTogether(event.result.members, ownerByMember)) {
+				// In its band and previously unmerged: keep it unmerged, as an exception inside the cursor.
+				// Dependency-safe, since an applied event can never consume a suppressed result.
+				this.suppressed.add(i)
+			} else {
+				applyEvent(this.visible, event)
+			}
 		}
 		this.seeded = true
+		this.version++
 	}
 
 	onCamera(zoom: number): void {
@@ -79,18 +138,116 @@ class ClusterRuntimeImpl implements ClusterRuntime {
 			throw new Error('Cluster runtime must be seeded before onCamera')
 		}
 
+		let changed = false
+		// Heal suppressed events at their own merge threshold BEFORE the merge walk, so a zoom-out past
+		// zMerge merges a held-out band event as if it had still been ahead of the cursor. Healing must come
+		// first: one zoom jump can cross both a suppressed event and an event consuming its result, and
+		// applying the consumer first would double-count the producer's leaves. Iterated live — deleting only
+		// the entry being visited is safe, and Set iteration still yields the rest in insertion order.
+		if (this.suppressed.size > 0) {
+			for (const i of this.suppressed) {
+				if (zoom <= this.table.events[i].zMerge) {
+					this.suppressed.delete(i)
+					applyEvent(this.visible, this.table.events[i])
+					changed = true
+				}
+			}
+		}
 		while (this.k < this.table.events.length && zoom <= this.table.events[this.k].zMerge) {
 			applyEvent(this.visible, this.table.events[this.k])
 			this.k++
+			changed = true
 		}
 		while (this.k > 0 && zoom >= this.table.events[this.k - 1].zSplit) {
 			this.k--
-			unapplyEvent(this.visible, this.table.events[this.k])
+			// A suppressed event was never applied — retreating past it is bookkeeping only.
+			if (!this.suppressed.delete(this.k)) {
+				unapplyEvent(this.visible, this.table.events[this.k])
+				changed = true
+			}
+		}
+		if (changed) this.version++
+	}
+
+	detachLeaf(leafId: string): void {
+		this.detachLeaves([leafId])
+	}
+
+	detachLeaves(leafIds: Iterable<string>): void {
+		const leafById = this.getLeafById()
+		let changed = false
+		for (const leafId of leafIds) {
+			if (this.detached.has(leafId)) continue
+			if (!leafById.has(leafId)) continue
+			this.detached.add(leafId)
+			changed = true
 		}
+		if (!changed) return
+		this.rebuildPatches()
+		this.version++
 	}
 
 	getVisible(): ReadonlyMap<string, ClusterNode> {
-		return this.visible
+		if (this.resolvedCache && this.resolvedCache.version === this.version) {
+			return this.resolvedCache.map
+		}
+		let map: Map<string, ClusterNode>
+		if (this.patched.size === 0) {
+			map = this.visible
+		} else {
+			map = new Map()
+			for (const node of this.visible.values()) {
+				const resolved = this.patched.has(node.id) ? this.patched.get(node.id)! : node
+				if (resolved) map.set(resolved.id, resolved)
+			}
+		}
+		this.resolvedCache = { version: this.version, map }
+		return map
+	}
+
+	private getLeafById(): Map<string, ClusterNode> {
+		if (!this.leafById) {
+			this.leafById = new Map(this.table.leaves.map((leaf) => [leaf.id, leaf]))
+		}
+		return this.leafById
+	}
+
+	/** Recompute the patch map from the detached set. A node is patched iff it contains a detached
+	 *  member; the patch drops those members and recomputes count/centroid, collapsing to the surviving
+	 *  leaf at count 1 and to nothing at count 0. Patched nodes keep their structural id. */
+	private rebuildPatches() {
+		this.patched.clear()
+		const leafById = this.getLeafById()
+		for (const id of this.detached) {
+			this.patched.set(id, null)
+		}
+		const patch = (node: ClusterNode) => {
+			if (node.members.length === 1 || !node.members.some((m) => this.detached.has(m))) return
+			const members = node.members.filter((m) => !this.detached.has(m))
+			if (members.length === 0) {
+				this.patched.set(node.id, null)
+			} else if (members.length === 1) {
+				this.patched.set(node.id, leafById.get(members[0])!)
+			} else {
+				let x = 0
+				let y = 0
+				for (const m of members) {
+					const leaf = leafById.get(m)!
+					x += leaf.centroid.x
+					y += leaf.centroid.y
+				}
+				this.patched.set(node.id, {
+					id: node.id,
+					centroid: { x: x / members.length, y: y / members.length },
+					count: members.length,
+					members,
+				})
+			}
+		}
+		for (const event of this.table.events) {
+			patch(event.result)
+			for (const child of event.children) patch(child)
+		}
 	}
 
 	private resetVisible() {

package/src/clustering/schedule.test.ts

@@ -7,7 +7,6 @@ import { cappedReplay } from './replay'
 import { contract, finalize } from './schedule'
 import { ClusterNode, ContractedEvent, LeafInput, MergeEvent, RawMergeEvent } from './types'
 
-// --- Synthetic builders -------------------------------------------------------
 // `contract` is specified over plain RawMergeEvent[] input precisely so it can
 // be tested with hand-built events, without running the replay.
 
@@ -55,8 +54,6 @@ const F = node(['f'])
 const X = node(['x'])
 const Y = node(['y'])
 
-// --- contract: fixtures -------------------------------------------------------
-
 describe('contract fixtures', () => {
 	it('returns [] for empty input', () => {
 		expect(contract([], 0.12)).toEqual([])
@@ -210,8 +207,6 @@ describe('contract validation and purity', () => {
 	})
 })
 
-// --- finalize: fixtures --------------------------------------------------------
-
 const FIN_OPTS = { Tc: 40, Tu: 60, minZoom: 0.1, maxZoom: 8, maxSplitZoom: 1e9 } // r = 1.5
 
 function contracted(zMerge: number, children: ClusterNode[], result: ClusterNode): ContractedEvent {
@@ -322,7 +317,6 @@ describe('finalize fixtures', () => {
 	})
 })
 
-// --- Composed pipeline properties ---------------------------------------------
 // finalize(contract(cappedReplay(mstEdges(leaves)))) must satisfy every table
 // invariant of CLUSTERING.md §7.6.