@tldraw/commenting 0.0.0-bootstrap → 5.3.0-internal.1640468db8fd

package/src/canvas/comments-sidebar.tsx

@@ -1,4 +1,4 @@
-import { ReactNode, useRef } from 'react'
+import { ReactNode, useCallback, useRef } from 'react'
 import { createPortal } from 'react-dom'
 import {
 	TLComment,
@@ -9,21 +9,22 @@ import {
 	useTranslation,
 	useValue,
 } from 'tldraw'
+import { CommentAuthor } from '../ui/comment-author'
 import { CommentListItemProps, CommentsList } from '../ui/comments-list'
-import { UNKNOWN_AUTHOR } from './comment-render'
+import { UNKNOWN_COMMENT_AUTHOR } from './comment-render'
 import { CommentsFilterMenu } from './comments-filter-menu'
-import { CommentsOverflowMenu } from './comments-overflow-menu'
+import { CommentsVisibilityToggle } from './comments-visibility-toggle'
 import { useComments, useCommentThreads } from './hooks'
 import { useCommentingEnabled } from './license'
 import { useCommentingOptions } from './options'
 import { richTextToPlaintext } from './rich-text'
-import { openThreadId, sidebarFilters } from './state'
+import { commentsSidebarOpen, openThreadId, sidebarFilters } from './state'
 import { focusThread } from './thread-state'
 
 /** @public */
 export interface CanvasCommentsSidebarProps {
-	/** Map an author id to a display name, or `undefined` when the id can't be named. */
-	resolveName(id: string): string | undefined
+	/** Map an author id to their display info, or `undefined` when the id can't be resolved. */
+	resolveAuthor(id: string): CommentAuthor | undefined
 	/** The signed-in user's id. Enables the "only your threads" filter when present. */
 	currentUserId?: string
 	/**
@@ -31,8 +32,6 @@ export interface CanvasCommentsSidebarProps {
 	 * "only unread" filter when present.
 	 */
 	isCommentUnread?(commentId: TLCommentId): boolean
-	/** Tool ids that show the sidebar. Defaults to the comment tool. */
-	tools?: string[]
 	/** Header above the list. */
 	header?: ReactNode
 	/** Shown when the page has no threads. */
@@ -42,31 +41,26 @@ export interface CanvasCommentsSidebarProps {
 }
 
 /**
- * A comments list panel for the current page, shown while the comment tool is active. Clicking a
- * thread brings its pin into view and opens it. Batteries-included over the store (a sibling to
- * `CanvasComments`); `CommentsList` is exported for a differently-placed or always-on list.
+ * A comments list panel for the current page, shown while {@link commentsSidebarOpen} is set (e.g.
+ * toggled by a button). Clicking a thread brings its pin into view and opens it. Batteries-included
+ * over the store (a sibling to `CanvasComments`); `CommentsList` is exported for a differently-placed
+ * or always-on list.
  * @public @react
  */
 export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
-	const {
-		resolveName,
-		currentUserId,
-		isCommentUnread,
-		tools,
-		header,
-		empty,
-		impreciseShapeAnchor,
-	} = props
+	const { resolveAuthor, currentUserId, isCommentUnread, header, empty, impreciseShapeAnchor } =
+		props
+	// Name-only view of the resolver, for the plaintext previews (which resolve @-mentions).
+	const resolveName = useCallback((id: string) => resolveAuthor(id)?.name, [resolveAuthor])
 	const editor = useEditor()
 	const options = useCommentingOptions()
-	const sidebarTools = tools ?? ['comment']
 	const container = useContainer()
 	const commentingEnabled = useCommentingEnabled()
 	const msg = useTranslation()
 	const threads = useCommentThreads(editor)
 	const comments = useComments(editor)
 	const currentPageId = useValue('page id', () => editor.getCurrentPageId(), [editor])
-	const activeTool = useValue('tool id', () => editor.getCurrentToolId(), [editor])
+	const open = useValue('sidebar open', () => commentsSidebarOpen.get(editor), [editor])
 	const openId = useValue('open thread', () => openThreadId.get(editor), [editor])
 	const filters = useValue('sidebar filters', () => sidebarFilters.get(editor), [editor])
 	const pageNames = useValue(
@@ -75,7 +69,7 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 		[editor]
 	)
 
-	if (!commentingEnabled || !sidebarTools.includes(activeTool)) return null
+	if (!commentingEnabled || !open) return null
 
 	// Group comments by thread (they arrive oldest-first, so [0] is each thread's first comment).
 	const byThread = new Map<string, TLComment[]>()
@@ -121,11 +115,16 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 			}
 			return {
 				id: thread.id,
-				author: resolveName(thread.createdBy) ?? UNKNOWN_AUTHOR,
+				author: resolveAuthor(thread.createdBy) ?? UNKNOWN_COMMENT_AUTHOR,
 				preview,
 				date: new Date((first ?? thread).createdAt).toISOString(),
 				resolved: thread.resolved != null,
-				page: pageNames.get(thread.pageId),
+				// The page label only earns its place when it adds information: multiple pages
+				// exist, and the thread is somewhere other than where you already are.
+				page:
+					pageNames.size > 1 && thread.pageId !== currentPageId
+						? pageNames.get(thread.pageId)
+						: undefined,
 				count: threadComments.length,
 				selected: openId === thread.id,
 			}
@@ -149,12 +148,12 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 				items={items}
 				header={header ?? msg('comments.title')}
 				headerAction={
-					<div className="cmt-list__header-actions">
+					<div className="tlui-cmt-list__header-actions">
 						<CommentsFilterMenu
 							canFilterByAuthor={currentUserId !== undefined}
 							canFilterByUnread={isCommentUnread !== undefined}
 						/>
-						<CommentsOverflowMenu />
+						<CommentsVisibilityToggle />
 					</div>
 				}
 				empty={
@@ -176,7 +175,7 @@ function SidebarPanel({ container, children }: { container: HTMLElement; childre
 	const ref = useRef<HTMLDivElement>(null)
 	usePassThroughMouseOverEvents(ref)
 	return createPortal(
-		<div ref={ref} className="cmt-canvas-sidebar">
+		<div ref={ref} className="tlui-cmt-canvas-sidebar" onContextMenu={(e) => e.stopPropagation()}>
 			{children}
 		</div>,
 		container

package/src/canvas/comments-visibility-toggle.tsx

@@ -0,0 +1,50 @@
+import { useEditor, useTranslation, useValue } from 'tldraw'
+import { TooltipButton } from '../ui/tooltip-button'
+import { commentsHidden, toggleCommentsHidden } from './state'
+
+/** The sidebar header's show/hide toggle for comment pins — an eye that closes while comments
+ *  are hidden. The same state as the Shift+C shortcut.
+ * @public @react */
+export function CommentsVisibilityToggle() {
+	const editor = useEditor()
+	const msg = useTranslation()
+	const hidden = useValue('comments hidden', () => commentsHidden.get(editor), [editor])
+	const label = hidden ? msg('comments.show') : msg('comments.hide')
+
+	return (
+		<TooltipButton
+			tooltip={label}
+			className="tlui-cmt-header-btn"
+			aria-pressed={hidden}
+			onClick={() => toggleCommentsHidden(editor)}
+		>
+			{hidden ? <EyeClosedIcon /> : <EyeOpenIcon />}
+		</TooltipButton>
+	)
+}
+
+function EyeOpenIcon() {
+	return (
+		<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+			<path
+				d="M7.5 11C4.80285 11 2.52952 9.62184 1.09622 7.50001C2.52952 5.37816 4.80285 4 7.5 4C10.1971 4 12.4705 5.37816 13.9038 7.5C12.4705 9.62183 10.1971 11 7.5 11ZM7.5 3C4.30786 3 1.65639 4.70638 0.0760002 7.23501C-0.0253338 7.39715 -0.0253334 7.60288 0.0760014 7.76501C1.65639 10.2936 4.30786 12 7.5 12C10.6921 12 13.3436 10.2936 14.924 7.76501C15.0253 7.60288 15.0253 7.39715 14.924 7.23501C13.3436 4.70638 10.6921 3 7.5 3ZM7.5 9.5C8.60457 9.5 9.5 8.60457 9.5 7.5C9.5 6.39543 8.60457 5.5 7.5 5.5C6.39543 5.5 5.5 6.39543 5.5 7.5C5.5 8.60457 6.39543 9.5 7.5 9.5Z"
+				fill="currentColor"
+				fillRule="evenodd"
+				clipRule="evenodd"
+			/>
+		</svg>
+	)
+}
+
+function EyeClosedIcon() {
+	return (
+		<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+			<path
+				d="M14.7649 6.07596C14.9991 6.22231 15.0703 6.53079 14.9239 6.76495C14.4849 7.46743 13.9632 8.10645 13.3702 8.66305L14.5712 9.86406C14.7664 10.0593 14.7664 10.3759 14.5712 10.5712C14.3759 10.7664 14.0593 10.7664 13.8641 10.5712L12.6011 9.30817C11.805 9.90283 10.9089 10.3621 9.93375 10.651L10.383 12.3277C10.4544 12.5944 10.2961 12.8685 10.0294 12.94C9.76267 13.0115 9.4885 12.8532 9.41704 12.5865L8.95917 10.8775C8.48743 10.958 8.00036 11 7.50001 11C6.99965 11 6.51257 10.958 6.04082 10.8775L5.58299 12.5864C5.51153 12.8532 5.23737 13.0115 4.97064 12.94C4.7039 12.8686 4.5456 12.5944 4.61706 12.3277L5.06625 10.651C4.09111 10.3621 3.19503 9.90282 2.39889 9.30815L1.1359 10.5712C0.940638 10.7664 0.624058 10.7664 0.428798 10.5712C0.233537 10.3759 0.233537 10.0593 0.428798 9.86405L1.62982 8.66303C1.03682 8.10643 0.515113 7.46742 0.0760677 6.76495C-0.0702867 6.53079 0.000898544 6.22231 0.235065 6.07596C0.469231 5.9296 0.777703 6.00079 0.924058 6.23496C1.40354 7.00213 1.989 7.68057 2.66233 8.2427C2.67315 8.25096 2.6837 8.25972 2.69397 8.26898C4.00897 9.35527 5.65537 10 7.50001 10C10.3078 10 12.6564 8.5063 14.076 6.23495C14.2223 6.00079 14.5308 5.9296 14.7649 6.07596Z"
+				fill="currentColor"
+				fillRule="evenodd"
+				clipRule="evenodd"
+			/>
+		</svg>
+	)
+}

package/src/canvas/options.ts

@@ -4,9 +4,24 @@ import {
 	type TLComment,
 	type TLCommentThread,
 	type TLHistoryBatchOptions,
+	type TLShapeId,
+	type VecLike,
 	useEditor,
 } from 'tldraw'
 
+/**
+ * The gesture that's creating a shape anchor, passed to
+ * {@link CommentingOptions.shouldBePrecise}: the target shape, the page point of the release, and
+ * whether Alt was held.
+ *
+ * @public
+ */
+export interface ShapeCommentPrecisionContext {
+	readonly shapeId: TLShapeId
+	readonly point: VecLike
+	readonly altKey: boolean
+}
+
 /**
  * Component overrides for the batteries-included comments layer. Each slot replaces a built-in
  * piece; leave a slot unset to keep its default.
@@ -59,6 +74,15 @@ export interface CommentingOptions {
 	// ── Anchoring ────────────────────────────────────────────────────────────────────────────
 	/** Normalized (0–1) spot within a shape where imprecise shape pins sit. Default top-right. */
 	readonly impreciseShapeAnchor: { readonly x: number; readonly y: number }
+	/**
+	 * Whether a comment landing on a shape anchors precisely — pinned to the exact clicked spot
+	 * within the shape — or imprecisely — pinned to the shape as a whole, rendered at
+	 * `impreciseShapeAnchor`. Called wherever a shape anchor is created (placing with the comment
+	 * tool, dropping a dragged pin onto a shape). Always precise by default. Return `false` for
+	 * shape-level anchoring, or decide from the context — the Alt key's state, or the shape itself,
+	 * e.g. precise only on notes. Governs new placements only; existing anchors render as stored.
+	 */
+	shouldBePrecise(editor: Editor, context: ShapeCommentPrecisionContext): boolean
 
 	// ── Clustering tuning ─────────────────────────────────────────────────────────────────────
 	/** Screen-pixel margin by which the viewport is inflated when culling cluster badges. */
@@ -81,6 +105,7 @@ export const defaultCommentingOptions = {
 	dragHistory: undefined,
 	enableClustering: true,
 	impreciseShapeAnchor: { x: 1, y: 0 },
+	shouldBePrecise: () => true,
 	clusterCullMargin: 120,
 	clusterSplitZoomFactor: 1.05,
 	components: {},

package/src/canvas/sidebar-filters.ts

@@ -16,10 +16,11 @@ export interface SidebarFilters {
 	onlyCurrentPage: boolean
 }
 
-/** @public */
+/** The out-of-the-box view: every page's threads, resolved ones hidden until asked for.
+ * @public */
 export const DEFAULT_SIDEBAR_FILTERS: SidebarFilters = {
-	showResolved: true,
+	showResolved: false,
 	onlyMine: false,
 	onlyUnread: false,
-	onlyCurrentPage: true,
+	onlyCurrentPage: false,
 }

package/src/canvas/state.ts

@@ -36,6 +36,15 @@ export const regionDraft = new EditorAtom<BoxModel | null>('regionDraft', () =>
  */
 export const commentsHidden = new EditorAtom<boolean>('commentsHidden', () => false)
 
+/**
+ * Whether the comments sidebar (the thread list) is open. Driven by an explicit control — a button
+ * next to Share on dotcom — rather than by which tool is active, so browsing threads is separate
+ * from placing them. The comment tool additionally closes it on enter, keeping placement
+ * canvas-focused.
+ * @public
+ */
+export const commentsSidebarOpen = new EditorAtom<boolean>('commentsSidebarOpen', () => false)
+
 /** Which threads the comments sidebar shows.
  * @public */
 export const sidebarFilters = new EditorAtom<SidebarFilters>(
@@ -49,6 +58,12 @@ export function toggleCommentsHidden(editor: Editor): void {
 	commentsHidden.update(editor, (hidden) => !hidden)
 }
 
+/** Open or close the comments sidebar for an editor.
+ * @public */
+export function toggleCommentsSidebar(editor: Editor): void {
+	commentsSidebarOpen.update(editor, (open) => !open)
+}
+
 /** React hook for the open thread id.
  * @public */
 export function useOpenThreadId(): string | null {
@@ -70,6 +85,13 @@ export function useCommentsHidden(): boolean {
 	return useValue('comments hidden', () => commentsHidden.get(editor), [editor])
 }
 
+/** React hook for whether the comments sidebar is open.
+ * @public */
+export function useCommentsSidebarOpen(): boolean {
+	const editor = useEditor()
+	return useValue('comments sidebar open', () => commentsSidebarOpen.get(editor), [editor])
+}
+
 /** React hook for the current sidebar filters.
  * @public */
 export function useSidebarFilters(): SidebarFilters {

package/src/canvas/thread-state.ts

@@ -10,6 +10,18 @@ export const DEFAULT_IMPRECISE_SHAPE_ANCHOR = { x: 1, y: 0 }
  *  which corner has no resize handle all derive from the chosen corner. */
 export const REGION_PIN_CORNER: VecLike = { x: 1, y: 1 }
 
+/** A region anchor's pin corner: the corner its creating drag released on, when recorded, else
+ *  the editor's configured default. @public */
+export function regionAnchorPinCorner(
+	editor: Editor,
+	anchor: Extract<TLCommentAnchor, { type: 'region' }>
+): VecLike {
+	if (anchor.pinX !== undefined && anchor.pinY !== undefined) {
+		return { x: anchor.pinX, y: anchor.pinY }
+	}
+	return getRegionCommentOptions(editor).pinCorner
+}
+
 /** The page point of a region's pin corner. */
 export function regionPinPoint(region: BoxModel, corner: VecLike = REGION_PIN_CORNER): VecLike {
 	return {
@@ -45,7 +57,7 @@ export function anchorPagePoint(
 		case 'point':
 			return { x: anchor.x, y: anchor.y }
 		case 'region':
-			return regionPinPoint(anchor, getRegionCommentOptions(editor).pinCorner)
+			return regionPinPoint(anchor, regionAnchorPinCorner(editor, anchor))
 		case 'page':
 			return null
 	}
@@ -53,8 +65,9 @@ export function anchorPagePoint(
 
 /**
  * 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).
+ * shape's page bounds, remembered either way. When `precise` the pin sits at exactly `x`/`y`;
+ * otherwise it sits at the consumer's imprecise default (top-right out of the box). Placement
+ * gestures get `precise` from the `shouldBePrecise` commenting option (always precise, by default).
  * @public
  */
 export function shapeAnchorAt(

package/src/clustering/runtime.test.ts

@@ -460,6 +460,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 +478,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 +514,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 +526,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 +540,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 +607,18 @@ 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('seedFrom followed by onCamera at the same zoom is a no-op', () => {
@@ -594,3 +658,115 @@ 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('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)
+	})
+})