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

package/src/canvas/comments-overlay.tsx

@@ -1,390 +1,204 @@
+import { isMentionPickerOpen } from '@tldraw/mentions'
+import { Fragment, ReactNode, useCallback, useEffect, useMemo, useRef } from 'react'
+import { EditorPortal, TLCommentThread, useEditor, useValue } from 'tldraw'
+import type { ClusterNode } from '../clustering/types'
+import { registerCommentAnchorLifecycle } from './anchor-lifecycle'
+import { ClusterBadge } from './cluster-badge'
+import { clusterFadeClassName } from './cluster-fade'
 import {
-	memo,
-	type CSSProperties,
-	type PointerEvent as ReactPointerEvent,
-	ReactNode,
-	useCallback,
-	useEffect,
-	useMemo,
-	useRef,
-	useState,
-} from 'react'
-import { createPortal } from 'react-dom'
-import {
-	type BoxModel,
-	createComment,
-	createCommentThread,
-	Editor,
-	getFirstCharacter,
-	react,
-	TLComment,
-	TLCommentId,
-	TLCommentThread,
-	TLRichText,
-	TldrawUiIcon,
-	useContainer,
-	useEditor,
-	usePassThroughMouseOverEvents,
-	usePassThroughWheelEvents,
-	useTranslation,
-	useValue,
-	VecLike,
-} from 'tldraw'
-import { computeClusterTable } from '../clustering/computeClusterTable'
-import { type ClusterRuntime, createClusterRuntime } from '../clustering/runtime'
-import type { ClusterNode, ClusterTable, MergeEvent } from '../clustering/types'
-import { CommentCard, CommentCardProps } from '../ui/comment-card'
-import { CommentComposer } from '../ui/comment-composer'
-import { EMPTY_COMMENT, isCommentEmpty } from '../ui/comment-extensions'
-import { CommentPin } from '../ui/comment-pin'
-import { CommentThread } from '../ui/comment-thread'
-import { CountBadge } from '../ui/count-badge'
-import { MentionMember } from '../ui/mention-list'
-import { isMentionPickerOpen } from '../ui/mention-suggestion'
-import { collectClusterLeaves } from './cluster-input'
-import { CommentBody } from './comment-body'
-import { UNKNOWN_AUTHOR } from './comment-render'
-import { getCommentRecord, putCommentRecords, removeCommentRecords } from './comment-store'
-import { PendingComment } from './comment-tool'
-import { useCommentThreads, useThreadComments } from './hooks'
+	CLUSTER_EXPAND_ZOOM_MS,
+	revealThreadPin,
+	useClusterModel,
+	zoomToClusterSplit,
+} from './cluster-model'
+import { getCommentRecord } from './comment-store'
+import { type CommentingContext } from './context'
+import { useCommentThreads } from './hooks'
 import { useCommentingEnabled } from './license'
-import {
-	type CommentingComponents,
-	type CommentingOptions,
-	getCommentingOptions,
-	useCommentingOptions,
-} from './options'
-import {
-	DEFAULT_REGION_COMMENT_OPTIONS,
-	RegionCommentOptions,
-	setRegionCommentOptions,
-} from './region-options'
+import { useCanComment, useCommentingOptions } from './options'
+import { PendingComposer } from './pending-composer'
+import { computePinStacks, isOpenStackKeyLive, pinStacksEqual } from './pin-stacking'
+import { RegionBox, RegionDraftBox } from './region-box'
 import {
 	commentsHidden,
-	commitCommentMutation,
+	openStackId,
 	openThreadId,
 	pendingComment,
-	regionDraft,
+	revealThreadRequest,
+	sidebarFilters,
 	toggleCommentsHidden,
 	usePendingComment,
 } from './state'
-import { anchorPagePoint, regionPinPoint, shapeAnchorAt } from './thread-state'
+import { ThreadPin } from './thread-pin'
+import { ThreadStackPin } from './thread-stack'
+
+/**
+ * The host wiring for {@link CanvasComments} — see {@link CommentingContext}, which the sidebar
+ * takes the same fields from.
+ *
+ * @public
+ */
+export type CanvasCommentsProps = CommentingContext
 
 /**
  * A ready-to-use comments layer for a tldraw canvas: pins each thread at its anchor, opens a
  * thread popover (with a reply composer) on click, and shows a composer where the comment tool
  * placed a new thread. Reads/writes comment records straight from `editor.store`.
  *
- * It's meant as the batteries-included default — every visible piece is a lever (the `CommentBody`
- * and `PinContent` slots on `CommentTool.configure({ components })`), and the pieces it composes
- * (`CommentPin`, `CommentThread`, `CommentComposer`, the hooks, the tool) are all exported, so a
- * consumer can rebuild this from parts instead.
- * @public
+ * It's the batteries-included default: every visible piece is a slot on
+ * `CommentTool.configure({ components })`, and the pieces it composes (`CommentPin`,
+ * `CommentThread`, `CommentComposer`, the hooks, the tool) are all exported, so a consumer can
+ * rebuild it from parts instead. The host wiring is the {@link CommentingContext}, which
+ * `CanvasCommentsSidebar` takes too.
+ *
+ * @public @react
  */
-export interface CanvasCommentsProps {
-	/** The signed-in user's id, or null for a read-only viewer. Only a signed-in user composes. */
-	currentUserId: string | null
-	/** Map an author id to a display name, or `undefined` when the id can't be named. */
-	resolveName(id: string): string | undefined
-	/** Called after any comment (a new thread's first comment, or a reply) is posted. */
-	onPostComment?(comment: TLComment): void
-	/** Whether a comment is unread for the current user (return true for unread). */
-	isCommentUnread?(commentId: TLCommentId): boolean
-	/**
-	 * Called for each unread comment shown to the user in an open thread popover, so hosts can
-	 * record a read receipt. Needs `isCommentUnread` to know what's unread.
-	 */
-	onCommentRead?(commentId: TLCommentId): void
-	/** Resolve the members matching an `@`-query in the composers (sync or async). */
-	getMentionSuggestions?(query: string): MentionMember[] | Promise<MentionMember[]>
-	/** Override a mention-picker row's content. */
-	renderMentionSuggestion?(member: MentionMember): ReactNode
-	/** Where imprecise shape pins sit — a normalized (0–1) spot within the shape. Default top-right. */
-	impreciseShapeAnchor?: { x: number; y: number }
-	/** Region comment behaviour. Region is off by default — omit this for click-only point/shape
-	 *  comments. Anything unset falls back to {@link DEFAULT_REGION_COMMENT_OPTIONS}. */
-	regionOptions?: Partial<RegionCommentOptions>
-}
-
-const stop = (e: { stopPropagation(): void }) => e.stopPropagation()
-
-const initialOf = (name: string): string => (getFirstCharacter(name.trim()) || '?').toUpperCase()
-const CLUSTER_FADE_MS = 150
-/** Duration of the click-a-badge zoom-to-split animation. */
-const CLUSTER_EXPAND_ZOOM_MS = 450
-
-/** The leading element for the placement composer — the comment pin's shape, but a pencil
- *  instead of an initial, marking an unsent draft. */
-const draftAvatar = (
-	<CommentPin>
-		<svg
-			viewBox="0 0 24 24"
-			width="15"
-			height="15"
-			fill="none"
-			stroke="currentColor"
-			strokeWidth="2"
-			strokeLinecap="round"
-			strokeLinejoin="round"
-			aria-hidden="true"
-		>
-			<path d="M12 20h9" />
-			<path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z" />
-		</svg>
-	</CommentPin>
-)
-
-function toCardProps(
-	comment: TLComment,
-	props: CanvasCommentsProps,
-	components: CommentingComponents
-): CommentCardProps {
-	const Body = components.CommentBody
-	// The `CommentBody` component slot overrides the built-in rich-text default (which resolves
-	// mention ids to names).
-	const body = Body ? (
-		<Body comment={comment} />
-	) : (
-		<CommentBody richText={comment.body} resolveName={props.resolveName} />
-	)
-	return {
-		author: props.resolveName(comment.authorId) ?? UNKNOWN_AUTHOR,
-		body,
-		date: new Date(comment.createdAt).toISOString(),
-		you: comment.authorId === props.currentUserId,
-		edited: comment.editedAt != null,
-	}
-}
-
-/** @public @react */
 export function CanvasComments(props: CanvasCommentsProps) {
-	// Gate the whole layer on the license before doing any work. The inner component holds all the
-	// other hooks, so mounting/unmounting it as the license resolves keeps hook order stable here.
+	// The inner component holds every other hook, so mounting it as the license resolves keeps hook
+	// order stable here.
 	const commentingEnabled = useCommentingEnabled()
 	if (!commentingEnabled) return null
 	return <CanvasCommentsLayer {...props} />
 }
 
-function CanvasCommentsLayer(props: CanvasCommentsProps) {
+function CanvasCommentsLayer(props: CommentingContext) {
 	const editor = useEditor()
 	const options = useCommentingOptions()
-	const container = useContainer()
-	// Merge the consumer's region options over the disabled defaults and publish them for this editor,
-	// so the comment tool (which has no props) reads the same per-instance config.
-	const regionOptions = useMemo(
-		() => ({ ...DEFAULT_REGION_COMMENT_OPTIONS, ...props.regionOptions }),
-		[props.regionOptions]
-	)
-	useEffect(() => setRegionCommentOptions(editor, regionOptions), [editor, regionOptions])
-	const layerRef = useRef<HTMLDivElement>(null)
-	// Over the pins and cluster badges, wheel and hover pass through to the canvas beneath (these
-	// events bubble up from the pointer-interactive markers to this layer root).
-	usePassThroughWheelEvents(layerRef)
-	usePassThroughMouseOverEvents(layerRef)
-	const deepLinkHandled = useRef(false)
-	const threads = useCommentThreads(editor)
+	const allThreads = useCommentThreads(editor)
 	const pending = usePendingComment()
-	const openId = useValue('open thread id', () => openThreadId.get(editor), [editor])
-	const impreciseShapeAnchor = props.impreciseShapeAnchor ?? options.impreciseShapeAnchor
-	// Threads whose anchor has moved (by any means — drag, nudge, align, undo, a collaborator)
-	// since the rendered clustering was built. They pop out of clustering and render as live pins,
-	// and only rejoin at the next zoom event, when everything re-clusters anyway.
-	const [movedThreadIds, setMovedThreadIds] = useState<ReadonlySet<string>>(EMPTY_SET)
-	const adoptOnRebuild = useRef(false)
-	const clusterLeaves = useValue(
-		'comment cluster leaves',
-		() =>
-			collectClusterLeaves(
-				editor,
-				threads.filter((thread) => !movedThreadIds.has(thread.id)),
-				openThreadId.get(editor),
-				impreciseShapeAnchor
-			),
-		[editor, threads, impreciseShapeAnchor, movedThreadIds]
-	)
-	const clusterZoomBounds = useValue(
-		'comment cluster zoom bounds',
-		() => getClusterZoomBounds(editor),
-		[editor]
-	)
-	const latestModel = useMemo(() => {
-		const table = computeClusterTable(clusterLeaves, clusterZoomBounds)
-		const runtime = createClusterRuntime(table)
-		runtime.seed(editor.getZoomLevel())
-		return { runtime, table }
-	}, [clusterLeaves, clusterZoomBounds, editor])
-	// Re-clustering only applies while zooming: a rebuilt model (thread added, moved, or closed)
-	// is held as `latestModel` and adopted on the next zoom change, so pins never re-flow into
-	// clusters under a static camera. Until adoption, threads the rendered model doesn't know
-	// about show as plain unclustered pins (`orphanThreads`). Exception: a rebuild that *removed*
-	// leaves (thread deleted or opened, page changed) is adopted immediately, so stale pins and
-	// badge counts never linger.
-	const [renderedModel, setRenderedModel] = useState(latestModel)
-	let clusterModel = renderedModel
-	if (
-		renderedModel !== latestModel &&
-		(adoptOnRebuild.current || hasRemovedLeaves(renderedModel.table, latestModel.table))
-	) {
-		adoptOnRebuild.current = false
-		// Carryover seed: events inside their hysteresis band inherit the outgoing partition's
-		// merged/unmerged state instead of the geometric-mean tiebreak, so untouched pins never
-		// snap together (or apart) just because the model was swapped. Idempotent, so safe to
-		// run during render.
-		latestModel.runtime.seedFrom(editor.getZoomLevel(), renderedModel.runtime.getVisible())
-		setRenderedModel(latestModel)
-		clusterModel = latestModel
-	}
-	// Pop-out detection: a leaf folded inside a badge can't follow its anchor (the badge position
-	// is baked into the model), so when its live position drifts from the baked one it ghosts.
-	// Marking it moved excludes it from the cluster input, which reads as a removal above and
-	// re-clusters the rest of its pile immediately; the pin itself renders live below.
-	const newlyMovedIds = findMovedClusteredLeafIds(clusterModel, latestModel)
-	if (newlyMovedIds.length > 0) {
-		// eslint-disable-next-line no-console
-		console.debug(`[comments] pins popped out of clustering: ${newlyMovedIds.join(', ')}`)
-		const next = new Set(movedThreadIds)
-		for (const id of newlyMovedIds) next.add(id)
-		setMovedThreadIds(next)
-	}
-	// Moved pins rejoin clustering on the next zoom-out motion: clear the set (so the rebuild
-	// includes them again) and adopt that rebuild immediately instead of deferring it. Zooming in
-	// never folds pins into clusters — merging is a zoom-out-only move, matching the runtime.
-	useEffect(() => {
-		if (movedThreadIds.size === 0) return
-		let lastZoom = editor.getZoomLevel()
-		return react('rejoin moved comment pins on zoom out', () => {
-			const zoom = editor.getZoomLevel()
-			const prevZoom = lastZoom
-			lastZoom = zoom
-			if (zoom >= prevZoom) return
-			adoptOnRebuild.current = true
-			setMovedThreadIds(EMPTY_SET)
-		})
-	}, [movedThreadIds, editor])
-	// Adopt a pending rebuild only on zoom-out motion: folding deferred additions into clusters is
-	// a merge, and merging only happens while zooming out. While zooming in, the stale table still
-	// splits correctly on its own (split thresholds are direction-safe by the hysteresis invariant).
+	const canComment = useCanComment(props.currentUserId)
+	// Nothing renders a pending comment when composing is blocked and there's no fallback slot, and
+	// the dismiss handlers live inside PendingComposer — so clear the atom rather than strand it.
+	const canRenderComposer = canComment || options.components.ComposerFallback != null
+	const showPendingComposer = pending != null && canRenderComposer
 	useEffect(() => {
-		if (clusterModel === latestModel) return
-		let lastZoom = editor.getZoomLevel()
-		return react('adopt pending cluster model on zoom out', () => {
-			const zoom = editor.getZoomLevel()
-			const prevZoom = lastZoom
-			lastZoom = zoom
-			if (zoom >= prevZoom) return
-			latestModel.runtime.seedFrom(zoom, clusterModel.runtime.getVisible())
-			setRenderedModel(latestModel)
-		})
-	}, [clusterModel, latestModel, editor])
-	const orphanThreads = useMemo(() => {
-		if (clusterModel === latestModel) return []
-		const renderedIds = new Set(clusterModel.table.leaves.map((leaf) => leaf.id))
-		const latestIds = new Set(latestModel.table.leaves.map((leaf) => leaf.id))
-		return threads.filter((thread) => latestIds.has(thread.id) && !renderedIds.has(thread.id))
-	}, [clusterModel, latestModel, threads])
-	const movedThreads = useMemo(
-		() => threads.filter((thread) => movedThreadIds.has(thread.id) && thread.id !== openId),
-		[threads, movedThreadIds, openId]
-	)
-	// Subscribe to the runtime cursor, not the raw zoom: onCamera runs on every zoom tick (two
-	// O(1) threshold checks against the event table) but returns the same integer until a merge
-	// or split event actually fires — so this component only re-renders on cluster changes, not
-	// on every camera frame.
-	const clusterCursor = useValue(
-		'comment cluster cursor',
-		() => {
-			clusterModel.runtime.onCamera(editor.getZoomLevel())
-			return clusterModel.runtime.k
-		},
-		[clusterModel, editor]
+		if (pending && !showPendingComposer) pendingComment.set(editor, null)
+	}, [editor, pending, showPendingComposer])
+	const openId = useValue('open thread id', () => openThreadId.get(editor), [editor])
+	// Matches the sidebar's `showResolved` filter. The open thread stays in — resolving from its own
+	// popover shouldn't make the pin vanish under it.
+	const showResolved = useValue('show resolved', () => sidebarFilters.get(editor).showResolved, [
+		editor,
+	])
+	const threads = useMemo(
+		() => allThreads.filter((t) => showResolved || t.resolved == null || t.id === openId),
+		[allThreads, showResolved, openId]
 	)
-	const visibleNodes = useMemo(() => {
-		const nodes = Array.from(clusterModel.runtime.getVisible().values())
-		// eslint-disable-next-line no-console
-		console.debug(
-			`[comments] cluster cursor k=${clusterCursor} → re-rendering ${nodes.length} visible nodes`
-		)
-		return nodes
-	}, [clusterModel, clusterCursor])
-	const fadeNodes = useFadeVisibleNodes(visibleNodes, clusterModel)
+	useEffect(() => registerCommentAnchorLifecycle(editor), [editor])
+	const {
+		model: clusterModel,
+		zoomBounds: clusterZoomBounds,
+		fadeNodes,
+		orphanThreads,
+		heldThreads,
+	} = useClusterModel(editor, threads, openId)
 	const threadsById = useMemo(
 		() => new Map<string, TLCommentThread>(threads.map((thread) => [thread.id, thread])),
 		[threads]
 	)
+	// Pins with the *same* anchor point coincide at every zoom, so they render as one count-badge
+	// stack. Keyed on page-space anchors, so camera moves never recompute this. Holding the map's
+	// identity while the grouping is unchanged keeps a reply from re-rendering every pin — but the
+	// map has no positions in it, so anything needing a stack's *point* must read the anchors itself.
+	const pinStacksRef = useRef<Map<string, readonly string[]>>(new Map())
+	const pinStacks = useValue(
+		'comment pin stacks',
+		() => {
+			const stacks = computePinStacks(editor, threads)
+			if (pinStacksEqual(pinStacksRef.current, stacks)) return pinStacksRef.current
+			pinStacksRef.current = stacks
+			return stacks
+		},
+		[editor, threads]
+	)
 	const openThread = openId ? threadsById.get(openId) : null
 	const hidden = useValue('comments hidden', () => commentsHidden.get(editor), [editor])
 
-	// Reset the transient UI state (open thread, half-placed comment) when this unmounts.
 	useEffect(() => {
 		return () => {
 			openThreadId.set(editor, null)
+			openStackId.set(editor, null)
 			pendingComment.set(editor, null)
+			revealThreadRequest.set(editor, null)
 		}
 	}, [editor])
 
-	// Open the thread named by a deep link (?comment=<thread or comment id>). If the thread is
-	// currently inside a cluster, zoom to the first split that reveals it before opening.
+	// Clear a stale open-stack key: only the stack's own mounted handlers clear it, so collapsing to
+	// a single pin strands it — and `useMarkerPreview` reads any non-null value as "a stack is open"
+	// and suppresses every hover preview. Kept while any live stack still sits at that key. Reads the
+	// anchors rather than keying off `pinStacks`, whose identity survives a stack moving as a whole.
+	const openStackKeyIsStale = useValue(
+		'open stack key stale',
+		() => {
+			const key = openStackId.get(editor)
+			if (!key) return false
+			return !isOpenStackKeyLive(editor, key, pinStacks, threadsById)
+		},
+		[editor, pinStacks, threadsById]
+	)
 	useEffect(() => {
-		if (deepLinkHandled.current) return
-		const id = new URLSearchParams(window.location.search).get('comment')
-		if (!id) {
-			deepLinkHandled.current = true
-			return
-		}
+		if (openStackKeyIsStale) openStackId.set(editor, null)
+	}, [editor, openStackKeyIsStale])
 
-		const record = getCommentRecord(editor, id)
-		if (!record) return
-
-		let thread: TLCommentThread | undefined
-		if (record.typeName === 'comment') {
-			thread = threadsById.get(record.threadId)
-		} else {
-			thread = record
-		}
-		if (!thread) return
+	// The requested thread, once it (and, for a comment id, its parent thread) has synced into the
+	// store; null while records are still arriving or when no request is pending.
+	const requestedRevealThread = useValue(
+		'requested reveal thread',
+		() => {
+			const id = revealThreadRequest.get(editor)
+			if (!id) return null
+			const record = getCommentRecord(editor, id)
+			if (!record) return null
+			const thread =
+				record.typeName === 'comment' ? getCommentRecord(editor, record.threadId) : record
+			return thread?.typeName === 'comment-thread' ? thread : null
+		},
+		[editor]
+	)
 
-		deepLinkHandled.current = true
-		revealDeepLinkedThread(
-			editor,
-			thread,
-			clusterModel.table,
-			clusterZoomBounds,
-			options,
-			impreciseShapeAnchor
-		)
-		openThreadId.set(editor, thread.id)
-	}, [clusterModel.table, clusterZoomBounds, editor, threadsById, impreciseShapeAnchor, options])
+	// Serve a pending reveal request, zooming to the first cluster split that reveals the pin if it's
+	// folded into a badge. Also unhides pins: the popover opens on the layer that hiding withholds.
+	useEffect(() => {
+		if (!requestedRevealThread) return
+		revealThreadRequest.set(editor, null)
+		commentsHidden.set(editor, false)
+		revealThreadPin(editor, requestedRevealThread, clusterModel.table, clusterZoomBounds, options)
+		openThreadId.set(editor, requestedRevealThread.id)
+	}, [requestedRevealThread, clusterModel.table, clusterZoomBounds, editor, options])
+
+	// Picking a thread out of a cluster's hover preview. `openThreadId` alone would work, but would
+	// cut straight there from the badge — zoom in first, the same move the badge's own click makes.
+	const revealClusteredThread = useCallback(
+		(thread: TLCommentThread) => {
+			revealThreadPin(
+				editor,
+				thread,
+				clusterModel.table,
+				clusterZoomBounds,
+				options,
+				CLUSTER_EXPAND_ZOOM_MS
+			)
+			openThreadId.set(editor, thread.id)
+		},
+		[clusterModel.table, clusterZoomBounds, editor, options]
+	)
 
-	// Clicking a badge zooms to just past the zoom at which that cluster first unclusters,
-	// centered on its centroid. The event that created a visible cluster is the event that splits
-	// it, and (by the table's sort + monotone thresholds) it has the smallest zSplit of everything
-	// applied inside it — so its zSplit is exactly the first split within those comments. The
-	// animated zoom-in then drives the runtime cursor like any manual zoom, so the badge splits
-	// (and can be drilled into further) with no extra bookkeeping.
-	const zoomToClusterSplit = useCallback(
+	const expandCluster = useCallback(
 		(node: ClusterNode) => {
-			const event = clusterModel.table.events.find((e) => e.result.id === node.id)
-			if (!event || !Number.isFinite(event.zSplit)) return
-			const zoom = clamp(
-				event.zSplit * options.clusterSplitZoomFactor,
-				clusterZoomBounds.minZoom,
-				clusterZoomBounds.maxZoom
-			)
-			centerOnPointAtZoom(editor, node.centroid, zoom, CLUSTER_EXPAND_ZOOM_MS)
+			zoomToClusterSplit(editor, clusterModel.table, clusterZoomBounds, node)
 		},
-		[clusterModel, clusterZoomBounds, editor, options]
+		[clusterModel.table, clusterZoomBounds, editor]
 	)
 
-	// Escape collapses the open thread. Capture-phase + stopPropagation so it runs ahead of the
-	// editor (which would otherwise cancel the current tool or clear the selection). If a comment is
-	// being edited, let its own Escape handler exit edit mode first, keeping the thread open.
+	// Escape collapses the open thread. Capture-phase so it runs ahead of the editor, which would
+	// otherwise cancel the tool or clear the selection.
 	useEffect(() => {
 		const onKeyDown = (e: KeyboardEvent) => {
 			if (e.key !== 'Escape' || openThreadId.get(editor) === null) return
 			// The mention picker owns Escape while it's open — let it dismiss the roster alone.
 			if (isMentionPickerOpen()) return
 			const target = e.target as HTMLElement | null
-			if (target && target.closest('.cmt-editing')) return
+			if (target && target.closest('.tlui-cmt-editing')) return
 			openThreadId.set(editor, null)
 			e.preventDefault()
 			e.stopPropagation()
@@ -393,8 +207,8 @@ function CanvasCommentsLayer(props: CanvasCommentsProps) {
 		return () => document.removeEventListener('keydown', onKeyDown, true)
 	}, [editor])
 
-	// Shift+C toggles comment-pin visibility on the canvas (matching Figma). Skipped while typing so
-	// it never fires from inside a composer. Physical `KeyC` (layout-independent) with shift only.
+	// Shift+C toggles pin visibility. Physical `KeyC` so it's layout-independent, and skipped while
+	// typing so it never fires from inside a composer.
 	useEffect(() => {
 		const onKeyDown = (e: KeyboardEvent) => {
 			if (e.code !== 'KeyC' || !e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
@@ -407,1054 +221,123 @@ function CanvasCommentsLayer(props: CanvasCommentsProps) {
 		return () => document.removeEventListener('keydown', onKeyDown, true)
 	}, [editor])
 
-	// Hidden: the whole canvas layer (pins, open popover, pending composer) is withheld. The signal
-	// is read above so this component stays mounted and its shortcut/Escape effects keep running.
+	// The signal is read above so this stays mounted and its shortcut/Escape effects keep running.
 	if (hidden) return null
 
-	// Render into the container (above the panels' stacking context) so the pins and popovers
-	// live in the UI layer rather than being clipped by the canvas layer.
-	return createPortal(
-		<div ref={layerRef} className="cmt-canvas-layer">
-			{options.enableClustering ? (
-				<>
-					{fadeNodes.map(({ node, phase }) => {
-						let content: ReactNode
-						if (node.count === 1) {
-							const thread = threadsById.get(node.id)
-							if (!thread) return null
-							content = (
-								<ThreadPin
-									editor={editor}
-									thread={thread}
-									{...props}
-									regionOptions={regionOptions}
-								/>
-							)
-						} else {
-							content = <ClusterBadge editor={editor} node={node} onExpand={zoomToClusterSplit} />
-						}
-						return (
-							<div key={`cluster-fade:${node.id}`} className={clusterFadeClassName(phase)}>
-								{content}
-							</div>
-						)
-					})}
-					{orphanThreads.map((thread) => (
-						<ThreadPin
-							key={thread.id}
-							editor={editor}
-							thread={thread}
-							{...props}
-							regionOptions={regionOptions}
-						/>
-					))}
-					{movedThreads.map((thread) => (
-						<ThreadPin
-							key={thread.id}
-							editor={editor}
-							thread={thread}
-							{...props}
-							regionOptions={regionOptions}
-						/>
-					))}
-				</>
-			) : (
-				// Clustering off: every thread renders as its own live pin (each returns null when it's
-				// not on the current page or its anchor is missing). The open thread is excluded here and
-				// rendered once below, mirroring how the clustering path keeps it out of the cluster leaves —
-				// otherwise it would mount a second, stacked pin.
-				threads
-					.filter((thread) => thread.id !== openId)
-					.map((thread) => (
-						<ThreadPin
-							key={thread.id}
-							editor={editor}
-							thread={thread}
-							{...props}
-							regionOptions={regionOptions}
-						/>
-					))
-			)}
-			{openThread && (
-				<ThreadPin
-					key={`open:${openThread.id}`}
-					editor={editor}
-					thread={openThread}
-					{...props}
-					regionOptions={regionOptions}
-				/>
-			)}
-			<RegionDraftBox editor={editor} />
-			{/* Keep the region visible while composing — the drag draft is gone by now, and no thread
-			    exists yet, so the pending anchor is what shows the area under the open composer. */}
-			{pending?.anchor.type === 'region' && <RegionBox editor={editor} box={pending.anchor} />}
-			{pending && props.currentUserId && (
-				<PendingComposer editor={editor} pending={pending} {...props} />
-			)}
-		</div>,
-		container
-	)
-}
-
-const EMPTY_SET: ReadonlySet<string> = new Set()
-const MOVED_LEAF_EPSILON = 1e-6
-type ClusterFadePhase = 'entering' | 'present' | 'exiting'
-
-interface ClusterFadeNode {
-	node: ClusterNode
-	phase: ClusterFadePhase
-}
-
-function useFadeVisibleNodes(
-	nodes: readonly ClusterNode[],
-	resetKey: { runtime: ClusterRuntime; table: ClusterTable }
-): 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 = requestClusterFadeFrame(() => {
-			setFadeNodes((previous) =>
-				previous.map((item) => (item.phase === 'entering' ? { ...item, phase: 'present' } : item))
-			)
-		})
-		return () => cancelClusterFadeFrame(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
-}
-
-function requestClusterFadeFrame(callback: FrameRequestCallback): number {
-	if (typeof requestAnimationFrame === 'function') return requestAnimationFrame(callback)
-	return window.setTimeout(() => callback(0), 16)
-}
-
-function cancelClusterFadeFrame(frame: number) {
-	if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(frame)
-	else window.clearTimeout(frame)
-}
-
-function clusterFadeClassName(phase: ClusterFadePhase): string {
-	return `cmt-cluster-fade cmt-cluster-fade--${phase}`
-}
-
-/**
- * Leaves folded inside a badge whose live anchor no longer matches the position the rendered
- * model was built with. Visible (unclustered) leaf pins track their anchor live, so they can
- * stay deferred; a badge can't follow a member, so these must pop out of clustering.
- */
-function findMovedClusteredLeafIds(
-	rendered: { runtime: ClusterRuntime; table: ClusterTable },
-	latest: { table: ClusterTable }
-): string[] {
-	if (rendered.table === latest.table) return []
-	const visible = rendered.runtime.getVisible()
-	const latestById = new Map(latest.table.leaves.map((leaf) => [leaf.id, leaf]))
-	const moved: string[] = []
-	for (const leaf of rendered.table.leaves) {
-		if (visible.has(leaf.id)) continue
-		const current = latestById.get(leaf.id)
-		if (!current) continue
-		if (
-			Math.abs(current.centroid.x - leaf.centroid.x) > MOVED_LEAF_EPSILON ||
-			Math.abs(current.centroid.y - leaf.centroid.y) > MOVED_LEAF_EPSILON
-		) {
-			moved.push(leaf.id)
-		}
-	}
-	return moved
-}
-
-function hasRemovedLeaves(rendered: ClusterTable, latest: ClusterTable): boolean {
-	if (rendered.leaves.length === 0) return false
-	const latestIds = new Set(latest.leaves.map((leaf) => leaf.id))
-	return rendered.leaves.some((leaf) => !latestIds.has(leaf.id))
-}
-
-function getClusterZoomBounds(editor: Editor): { minZoom: number; maxZoom: number } {
-	const cameraOptions = editor.getCameraOptions()
-	const baseZoom = cameraOptions.constraints ? editor.getBaseZoom() : 1
-	const zoomSteps = cameraOptions.zoomSteps
-	return {
-		minZoom: zoomSteps[0] * baseZoom,
-		maxZoom: zoomSteps[zoomSteps.length - 1] * baseZoom,
+	// The node's pin-stack group when every member shares one — a stack standing on its own, which
+	// renders as a cascading count-badge list rather than a zoom-to-split cluster badge. The group
+	// can include an open or orphan member the node's own leaves omit.
+	const stackGroupOf = (node: ClusterNode): readonly string[] | null => {
+		const group = pinStacks.get(node.members[0])
+		if (!group) return null
+		return node.members.every((id) => group.includes(id)) ? group : null
 	}
-}
-
-function revealDeepLinkedThread(
-	editor: Editor,
-	thread: TLCommentThread,
-	table: ClusterTable,
-	zoomBounds: { minZoom: number; maxZoom: number },
-	options: CommentingOptions,
-	impreciseShapeAnchor: { x: number; y: number }
-) {
-	if (thread.pageId !== editor.getCurrentPageId()) {
-		editor.setCurrentPage(thread.pageId as any)
-	}
-
-	// Match where the rendered pin sits (resolved prop-or-option), so the camera centers on the pin.
-	const point = anchorPagePoint(editor, thread.anchor, impreciseShapeAnchor)
-	if (!point) return
 
-	// With clustering off the pin always renders individually, so skip the zoom-to-split (its cluster
-	// badge never exists) and just center on the pin.
+	// Which threads are on screen this render. A stack renders once, owned by its first on-screen
+	// member — members arrive by different paths, so ownership can't be decided per-path.
+	const renderedThreadIds = new Set<string>()
 	if (options.enableClustering) {
-		const parentEvent = findDirectParentEvent(table, thread.id)
-		if (
-			parentEvent &&
-			Number.isFinite(parentEvent.zSplit) &&
-			parentEvent.zSplit <= zoomBounds.maxZoom
-		) {
-			const zoom = clamp(
-				parentEvent.zSplit * options.clusterSplitZoomFactor,
-				zoomBounds.minZoom,
-				zoomBounds.maxZoom
-			)
-			centerOnPointAtZoom(editor, point, zoom)
-			return
+		for (const { node } of fadeNodes) {
+			if (node.count === 1) renderedThreadIds.add(node.id)
+			// A pure-stack node's members aren't count-1 leaves, so register them here for the owner
+			// logic to pick from.
+			else if (stackGroupOf(node)) for (const id of node.members) renderedThreadIds.add(id)
 		}
+		for (const thread of orphanThreads) renderedThreadIds.add(thread.id)
+		for (const thread of heldThreads) renderedThreadIds.add(thread.id)
+	} else {
+		for (const thread of threads) renderedThreadIds.add(thread.id)
 	}
-
-	editor.centerOnPoint(point, { animation: { duration: 200 } })
-}
-
-function findDirectParentEvent(table: ClusterTable, threadId: string): MergeEvent | undefined {
-	return table.events.find((event) => event.children.some((child) => child.id === threadId))
-}
-
-function centerOnPointAtZoom(
-	editor: Editor,
-	point: { x: number; y: number },
-	zoom: number,
-	duration = 200
-) {
-	const viewport = editor.getViewportScreenBounds()
-	editor.setCamera(
-		{
-			x: viewport.w / (2 * zoom) - point.x,
-			y: viewport.h / (2 * zoom) - point.y,
-			z: zoom,
-		},
-		{ animation: { duration } }
-	)
-}
-
-function clamp(value: number, min: number, max: number): number {
-	return Math.max(min, Math.min(max, value))
-}
-
-// 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.
-const ClusterBadge = memo(function ClusterBadge({
-	editor,
-	node,
-	onExpand,
-}: {
-	editor: Editor
-	node: ClusterNode
-	onExpand(node: ClusterNode): void
-}) {
-	const point = useValue(
-		'cluster badge point',
-		() => {
-			const pagePoint = editor.pageToViewport(node.centroid)
-			if (!isInInflatedViewport(editor, pagePoint)) return null
-			return pagePoint
-		},
-		[editor, node]
-	)
-
-	if (!point) return null
-
-	return (
-		<div
-			className="cmt-canvas-cluster"
-			style={{ left: point.x, top: point.y }}
-			onPointerDown={stop}
-			onClick={(e) => {
-				e.stopPropagation()
-				onExpand(node)
-			}}
-		>
-			<CountBadge count={node.count} />
-		</div>
-	)
-})
-
-function isInInflatedViewport(editor: Editor, point: { x: number; y: number }): boolean {
-	const viewport = editor.getViewportScreenBounds()
-	const margin = getCommentingOptions(editor).clusterCullMargin
-	return (
-		point.x >= -margin &&
-		point.y >= -margin &&
-		point.x <= viewport.w + margin &&
-		point.y <= viewport.h + margin
-	)
-}
-
-/** The open thread's popover, portaled above the UI panels. Over it, wheel and hover events pass
- *  through to the canvas (unless the popover is scrolling its own content), like tldraw's panels. */
-function ThreadPopover({
-	container,
-	style,
-	children,
-}: {
-	container: HTMLElement
-	style: CSSProperties
-	children: ReactNode
-}) {
-	const ref = useRef<HTMLDivElement>(null)
-	usePassThroughWheelEvents(ref)
-	usePassThroughMouseOverEvents(ref)
-	return createPortal(
-		<div ref={ref} className="cmt-canvas-popover" style={style} onPointerDown={stop}>
-			{children}
-		</div>,
-		container
-	)
-}
-
-/** A dashed rectangle over a region anchor's bounds, in viewport space. Sits in the canvas layer as
- *  a sibling of the pins. `pointer-events` stays off (canvas interaction passes through) unless
- *  `movable`, in which case dragging the body translates the region — previews live, commits on drop. */
-function RegionBox({
-	editor,
-	box,
-	movable,
-	onPreview,
-	onCommit,
-}: {
-	editor: Editor
-	box: BoxModel
-	movable?: boolean
-	onPreview?(bounds: BoxModel | null): void
-	onCommit?(bounds: BoxModel): void
-}) {
-	const rect = useValue(
-		'region rect',
-		() => {
-			// Position from the page→viewport top-left; screen size scales with zoom, page size doesn't.
-			const topLeft = editor.pageToViewport({ x: box.x, y: box.y })
-			const zoom = editor.getZoomLevel()
-			return { left: topLeft.x, top: topLeft.y, width: box.w * zoom, height: box.h * zoom }
-		},
-		[editor, box.x, box.y, box.w, box.h]
-	)
-	// The grab point and the box at grab time, captured so the drag translates by a stable delta even
-	// as the box prop reflows under the live preview.
-	const grabRef = useRef<{ page: VecLike; box: BoxModel } | null>(null)
-	const translated = (e: ReactPointerEvent<HTMLDivElement>): BoxModel => {
-		const g = grabRef.current!
-		const p = editor.screenToPage({ x: e.clientX, y: e.clientY })
-		return { ...g.box, x: g.box.x + (p.x - g.page.x), y: g.box.y + (p.y - g.page.y) }
-	}
-	const startMove = (e: ReactPointerEvent<HTMLDivElement>) => {
-		e.stopPropagation()
-		grabRef.current = { page: editor.screenToPage({ x: e.clientX, y: e.clientY }), box }
-		e.currentTarget.setPointerCapture(e.pointerId)
-	}
-	const onMove = (e: ReactPointerEvent<HTMLDivElement>) => {
-		if (grabRef.current) onPreview?.(translated(e))
-	}
-	const endMove = (e: ReactPointerEvent<HTMLDivElement>) => {
-		if (!grabRef.current) return
-		const bounds = translated(e)
-		grabRef.current = null
-		if (e.currentTarget.hasPointerCapture(e.pointerId))
-			e.currentTarget.releasePointerCapture(e.pointerId)
-		onCommit?.(bounds)
-	}
-	return (
-		<div
-			className={movable ? 'cmt-canvas-region cmt-canvas-region--movable' : 'cmt-canvas-region'}
-			style={rect}
-			onPointerDown={movable ? startMove : undefined}
-			onPointerMove={movable ? onMove : undefined}
-			onPointerUp={movable ? endMove : undefined}
-		/>
-	)
-}
-
-/** The live region being dragged out by the comment tool, or nothing when not dragging. */
-function RegionDraftBox({ editor }: { editor: Editor }) {
-	const box = useValue('region draft', () => regionDraft.get(editor), [editor])
-	if (!box) return null
-	return <RegionBox editor={editor} box={box} />
-}
-
-// A resize handle's normalized 0–1 spot on the box, and its cursor. An axis at 0.5 (a side midpoint)
-// is *not* controlled by that handle: corners resize both axes, edges resize only their own.
-interface RegionHandle {
-	x: number
-	y: number
-	cursor: string
-}
-
-// The four corners (both axes) and the four side midpoints (one axis each).
-const REGION_CORNERS: readonly RegionHandle[] = [
-	{ x: 0, y: 0, cursor: 'nwse-resize' },
-	{ x: 1, y: 0, cursor: 'nesw-resize' },
-	{ x: 0, y: 1, cursor: 'nesw-resize' },
-	{ x: 1, y: 1, cursor: 'nwse-resize' },
-]
-const REGION_EDGES: readonly RegionHandle[] = [
-	{ x: 0.5, y: 0, cursor: 'ns-resize' },
-	{ x: 1, y: 0.5, cursor: 'ew-resize' },
-	{ x: 0.5, y: 1, cursor: 'ns-resize' },
-	{ x: 0, y: 0.5, cursor: 'ew-resize' },
-]
-
-// Screen-space slack around a region's bounds within which its box and handles stay revealed, so
-// the handles (which sit on the edge) are comfortably reachable.
-const REGION_HANDLE_MARGIN_PX = 12
-
-/** Resize `box` by dragging `handle` to `cursor` (page coords). Each controlled axis spans from the
- *  handle's fixed opposite edge to the cursor (normalized, so dragging past it flips); an axis the
- *  handle doesn't control (a midpoint, at 0.5) keeps its original position and size. */
-function resizeRegion(box: BoxModel, handle: RegionHandle, cursor: VecLike): BoxModel {
-	const controlsX = handle.x !== 0.5
-	const controlsY = handle.y !== 0.5
-	const fixedX = box.x + (1 - handle.x) * box.w
-	const fixedY = box.y + (1 - handle.y) * box.h
-	return {
-		x: controlsX ? Math.min(fixedX, cursor.x) : box.x,
-		y: controlsY ? Math.min(fixedY, cursor.y) : box.y,
-		w: controlsX ? Math.abs(cursor.x - fixedX) : box.w,
-		h: controlsY ? Math.abs(cursor.y - fixedY) : box.h,
-	}
-}
-
-/** Draggable handles that resize a region — corners (both axes) or edges (one axis), per the resize
- *  option. Previews live, commits on release. */
-function RegionResizeHandles({
-	editor,
-	box,
-	handles,
-	onPreview,
-	onCommit,
-}: {
-	editor: Editor
-	box: BoxModel
-	handles: readonly RegionHandle[]
-	onPreview(bounds: BoxModel | null): void
-	onCommit(bounds: BoxModel): void
-}) {
-	// The box at pointer-down, captured so the box prop reflowing under the live preview doesn't move
-	// the fixed edges mid-drag.
-	const boxRef = useRef<BoxModel | null>(null)
-	const points = useValue(
-		'region handle points',
-		() =>
-			handles.map((h) => {
-				const p = editor.pageToViewport({ x: box.x + h.x * box.w, y: box.y + h.y * box.h })
-				return { ...h, key: `${h.x}-${h.y}`, left: p.x, top: p.y }
-			}),
-		[editor, box.x, box.y, box.w, box.h, handles]
-	)
-	const startResize = (e: ReactPointerEvent<HTMLDivElement>) => {
-		e.stopPropagation()
-		boxRef.current = box
-		e.currentTarget.setPointerCapture(e.pointerId)
-	}
-	const resizedTo = (h: RegionHandle, e: ReactPointerEvent<HTMLDivElement>): BoxModel =>
-		resizeRegion(boxRef.current!, h, editor.screenToPage({ x: e.clientX, y: e.clientY }))
-	const onResize = (h: RegionHandle) => (e: ReactPointerEvent<HTMLDivElement>) => {
-		if (boxRef.current) onPreview(resizedTo(h, e))
-	}
-	const endResize = (h: RegionHandle) => (e: ReactPointerEvent<HTMLDivElement>) => {
-		if (!boxRef.current) return
-		const bounds = resizedTo(h, e)
-		boxRef.current = null
-		if (e.currentTarget.hasPointerCapture(e.pointerId))
-			e.currentTarget.releasePointerCapture(e.pointerId)
-		onCommit(bounds)
-	}
-	return (
-		<>
-			{points.map((h) => (
-				<div
-					key={h.key}
-					className="cmt-canvas-region-handle"
-					style={{ left: h.left, top: h.top, cursor: h.cursor }}
-					onPointerDown={startResize}
-					onPointerMove={onResize(h)}
-					onPointerUp={endResize(h)}
-				/>
-			))}
-		</>
-	)
-}
-
-const ThreadPin = memo(function ThreadPin({
-	editor,
-	thread,
-	regionOptions,
-	...props
-}: Omit<CanvasCommentsProps, 'regionOptions'> & {
-	editor: Editor
-	thread: TLCommentThread
-	regionOptions: RegionCommentOptions
-}) {
-	const {
-		currentUserId,
-		resolveName,
-		onPostComment,
-		isCommentUnread,
-		onCommentRead,
-		getMentionSuggestions,
-		renderMentionSuggestion,
-	} = props
-	const options = useCommentingOptions()
-	const impreciseShapeAnchor = props.impreciseShapeAnchor ?? options.impreciseShapeAnchor
-	const container = useContainer()
-	const comments = useThreadComments(editor, thread.id)
-	const msg = useTranslation()
-	// Only one thread's popover is open at a time — shared across pins via the atom.
-	const open = useValue('thread open', () => openThreadId.get(editor) === thread.id, [
-		editor,
-		thread.id,
-	])
-	const [reply, setReply] = useState<TLRichText>(EMPTY_COMMENT)
-	const [editingId, setEditingId] = useState<string | null>(null)
-	const [editText, setEditText] = useState<TLRichText>(EMPTY_COMMENT)
-	// While dragging the marker, its page point overrides the anchor's; committed on drop.
-	const [dragPagePoint, setDragPagePoint] = useState<{ x: number; y: number } | null>(null)
-	// The live bounds while a corner handle is resizing the region, else null.
-	const [resizeBounds, setResizeBounds] = useState<BoxModel | null>(null)
-	// Whether the pin marker is hovered — only consulted by the 'pin-hover' reveal mode.
-	const [pinHovered, setPinHovered] = useState(false)
-	// The 'pointer' reveal mode: is the pointer within the region's bounds (plus a grab margin)?
-	// Driven by pointer position, not DOM hover, so moving from anywhere in the region out to a corner
-	// handle never loses the affordance — the box stays `pointer-events: none`.
-	const pointerInRegion = useValue(
-		'pointer in region',
-		() => {
-			if (thread.anchor.type !== 'region' || thread.pageId !== editor.getCurrentPageId())
-				return false
-			const m = REGION_HANDLE_MARGIN_PX / editor.getZoomLevel()
-			const p = editor.inputs.getCurrentPagePoint()
-			const a = thread.anchor
-			return p.x >= a.x - m && p.x <= a.x + a.w + m && p.y >= a.y - m && p.y <= a.y + a.h + m
-		},
-		[editor, thread.anchor, thread.pageId]
-	)
-	// A region's box and handles are revealed while open or mid-resize, plus — per the reveal mode —
-	// while the pointer is within the region ('pointer') or the pin is hovered ('pin-hover').
-	const revealed =
-		open ||
-		resizeBounds != null ||
-		(regionOptions.reveal === 'pointer' && pointerInRegion) ||
-		(regionOptions.reveal === 'pin-hover' && pinHovered)
-	// The resize handles: side midpoints ('edges'), or the corners other than the pin's ('corners').
-	const resizeHandles = useMemo(
-		() =>
-			regionOptions.resize === 'edges'
-				? REGION_EDGES
-				: REGION_CORNERS.filter(
-						(c) => c.x !== regionOptions.pinCorner.x || c.y !== regionOptions.pinCorner.y
-					),
-		[regionOptions.resize, regionOptions.pinCorner]
-	)
-	const dragRef = useRef<{ startX: number; startY: number; moved: boolean } | null>(null)
-	const markerRef = useRef<HTMLDivElement>(null)
-
-	// Clicking outside the open popover (and off its own pin) closes the thread — mirrors the
-	// pending composer's dismiss. Capture phase + a class check rather than stopPropagation, since the
-	// popover portals elsewhere in the DOM. The pin marker is excluded so its own click-to-toggle
-	// handles it instead of this closing then the toggle reopening.
-	useEffect(() => {
-		if (!open) return
-		const onPointerDown = (e: PointerEvent) => {
-			const target = e.target as HTMLElement | null
-			if (!target) return
-			if (target.closest('.cmt-canvas-popover')) return
-			const marker = markerRef.current
-			if (marker && marker.contains(target)) return
-			// A press on a region's resize handle or movable body edits this thread — don't dismiss it.
-			if (target.closest('.cmt-canvas-region-handle, .cmt-canvas-region--movable')) return
-			// A click inside a menu/popover layered above us (the sidebar's filter or overflow
-			// dropdown, or the composer's mention picker — all portaled elsewhere) belongs to that
-			// layer; defer to its own dismissal instead of closing the thread out from under it.
-			if (target.closest('.tlui-menu, [data-radix-popper-content-wrapper], .cmt-mention-popup'))
-				return
-			openThreadId.set(editor, null)
-		}
-		document.addEventListener('pointerdown', onPointerDown, true)
-		return () => document.removeEventListener('pointerdown', onPointerDown, true)
-	}, [open, editor])
-
-	const point = useValue(
-		'pin point',
-		() => {
-			if (thread.pageId !== editor.getCurrentPageId()) return null
-			const pagePoint = anchorPagePoint(editor, thread.anchor, impreciseShapeAnchor)
-			return pagePoint ? editor.pageToViewport(pagePoint) : null
-		},
-		[editor, thread.anchor, thread.pageId, impreciseShapeAnchor]
-	)
-	const visible = point !== null
-
-	// While the popover is open, every unread comment on display gets reported read — including
-	// replies that arrive while it stays open, since the effect re-runs as `comments` changes.
-	// The host's receipt write flips isCommentUnread to false, so re-runs find nothing to report.
-	useEffect(() => {
-		if (!open || !visible || !isCommentUnread || !onCommentRead) return
-		for (const comment of comments) {
-			if (isCommentUnread(comment.id)) {
-				onCommentRead(comment.id)
-			}
-		}
-	}, [open, visible, comments, isCommentUnread, onCommentRead])
-
-	if (!point) return null
-
-	const postReply = () => {
-		if (isCommentEmpty(reply) || !currentUserId) return
-		commitCommentMutation(editor, () => {
-			const comment = createComment({
-				threadId: thread.id,
-				pageId: thread.pageId,
-				authorId: currentUserId,
-				body: reply,
-			})
-			putCommentRecords(editor, [comment])
-			if (onPostComment) onPostComment(comment)
-		})
-		setReply(EMPTY_COMMENT)
-	}
-
-	const toggleResolve = () => {
-		if (!currentUserId) return
-		commitCommentMutation(editor, () => {
-			putCommentRecords(editor, [
-				{
-					...thread,
-					resolved: thread.resolved ? null : { at: Date.now(), by: currentUserId },
-				},
-			])
-		})
-	}
-
-	const deleteThread = () => {
-		openThreadId.set(editor, null)
-		commitCommentMutation(editor, () =>
-			removeCommentRecords(editor, [thread.id, ...comments.map((c) => c.id)])
-		)
-	}
-
-	const startEdit = (comment: TLComment) => {
-		setEditingId(comment.id)
-		setEditText(comment.body)
-	}
-
-	const saveEdit = () => {
-		const comment = comments.find((c) => c.id === editingId)
-		if (!comment || isCommentEmpty(editText)) return
-		commitCommentMutation(editor, () => {
-			putCommentRecords(editor, [{ ...comment, body: editText, editedAt: Date.now() }])
-		})
-		setEditingId(null)
-	}
-
-	// Swap a comment for a pre-filled composer while it's being edited; otherwise show the card,
-	// with an edit affordance on your own comments.
-	const renderComment = (card: CommentCardProps, index: number): ReactNode => {
-		const comment = comments[index]
-		if (editingId === comment.id) {
-			return (
-				<div
-					className="cmt-editing"
-					onKeyDown={(e) => {
-						if (e.key === 'Escape') {
-							setEditingId(null)
-							e.stopPropagation()
-						}
-					}}
-				>
-					<CommentComposer
-						author={card.author}
-						placeholder={msg('comments.edit-placeholder')}
-						value={editText}
-						onChange={setEditText}
-						onSubmit={saveEdit}
-						sendLabel={msg('comments.save')}
-						disabled={isCommentEmpty(editText)}
-						getMentionSuggestions={getMentionSuggestions}
-						renderMentionSuggestion={renderMentionSuggestion}
-						autoFocus
-					/>
-				</div>
-			)
+	if (openThread) renderedThreadIds.add(openThread.id)
+
+	// A coincident-stack member renders as the group's single count-badge stack (if it owns it)
+	// or not at all; everything else is an ordinary pin.
+	const renderThreadPin = (thread: TLCommentThread): ReactNode => {
+		const group = pinStacks.get(thread.id)
+		if (group) {
+			const owner = group.find((id) => renderedThreadIds.has(id))
+			if (owner !== thread.id) return null
+			const stackThreads = group
+				.map((id) => threadsById.get(id))
+				.filter((t): t is TLCommentThread => t !== undefined)
+			return <ThreadStackPin editor={editor} threads={stackThreads} {...props} />
 		}
-		return (
-			<CommentCard
-				{...card}
-				actions={
-					comment.authorId === currentUserId ? (
-						<button
-							className="cmt-thread__action"
-							title={msg('comments.edit')}
-							onClick={() => startEdit(comment)}
-						>
-							<TldrawUiIcon icon="dots-horizontal" label={msg('comments.edit')} small />
-						</button>
-					) : undefined
-				}
-			/>
-		)
-	}
-
-	const headerActions = (
-		<>
-			{currentUserId && (
-				<button
-					className="cmt-thread__action"
-					title={msg(thread.resolved ? 'comments.reopen' : 'comments.resolve')}
-					onClick={toggleResolve}
-				>
-					<TldrawUiIcon
-						icon="check"
-						label={msg(thread.resolved ? 'comments.reopen' : 'comments.resolve')}
-						small
-					/>
-				</button>
-			)}
-			{currentUserId && (
-				<button
-					className="cmt-thread__action"
-					title={msg('comments.delete')}
-					onClick={deleteThread}
-				>
-					<TldrawUiIcon icon="trash" label={msg('comments.delete')} small />
-				</button>
-			)}
-			<button
-				className="cmt-thread__action"
-				title={msg('comments.dismiss')}
-				onClick={() => openThreadId.set(editor, null)}
-			>
-				<TldrawUiIcon icon="cross-2" label={msg('comments.dismiss')} small />
-			</button>
-		</>
-	)
-
-	const PinContent = options.components.PinContent
-	// The `PinContent` component slot overrides the built-in author-initial default.
-	const pinContent = PinContent ? (
-		<PinContent thread={thread} comments={comments} />
-	) : (
-		initialOf(resolveName(thread.createdBy) ?? UNKNOWN_AUTHOR)
-	)
-
-	// Drag the marker to move the thread: its position is overridden locally while dragging, then
-	// re-anchored on drop. A point/shape thread re-anchors to whatever it's dropped on (a shape, else
-	// a point); a region thread translates, keeping its size. A pointer that barely moves is a click —
-	// toggle the popover.
-	// Which affordances move a region, per the option: 'pin' → pin only, 'body' → body only, 'both'.
-	const isRegion = thread.anchor.type === 'region'
-	const pinMovable = regionOptions.move !== 'body'
-	const bodyMovable = regionOptions.move !== 'pin'
-	const startDrag = (e: ReactPointerEvent<HTMLDivElement>) => {
-		e.stopPropagation()
-		dragRef.current = { startX: e.clientX, startY: e.clientY, moved: false }
-		e.currentTarget.setPointerCapture(e.pointerId)
-	}
-	const onDrag = (e: ReactPointerEvent<HTMLDivElement>) => {
-		const drag = dragRef.current
-		if (!drag) return
-		// A region that moves by its body ignores pin drags (the pin only toggles the thread).
-		if (isRegion && !pinMovable) return
-		if (!drag.moved && Math.hypot(e.clientX - drag.startX, e.clientY - drag.startY) < 4) return
-		drag.moved = true
-		setDragPagePoint(editor.screenToPage({ x: e.clientX, y: e.clientY }))
-	}
-	const endDrag = (e: ReactPointerEvent<HTMLDivElement>) => {
-		const drag = dragRef.current
-		dragRef.current = null
-		if (e.currentTarget.hasPointerCapture(e.pointerId)) {
-			e.currentTarget.releasePointerCapture(e.pointerId)
-		}
-		if (!drag) return
-		if (!drag.moved) {
-			openThreadId.set(editor, openThreadId.get(editor) === thread.id ? null : thread.id)
-			return
-		}
-		const pagePoint = editor.screenToPage({ x: e.clientX, y: e.clientY })
-		setDragPagePoint(null)
-		let anchor: TLCommentThread['anchor']
-		if (thread.anchor.type === 'region') {
-			// Translate so the pin (the region's pin corner) lands at the drop; size unchanged.
-			anchor = {
-				...thread.anchor,
-				x: pagePoint.x - regionOptions.pinCorner.x * thread.anchor.w,
-				y: pagePoint.y - regionOptions.pinCorner.y * thread.anchor.h,
-			}
-		} else {
-			const hit = editor.getShapeAtPoint(pagePoint, { hitInside: true })
-			anchor = hit
-				? shapeAnchorAt(editor, hit.id, pagePoint, e.altKey)
-				: { type: 'point', x: pagePoint.x, y: pagePoint.y }
-		}
-		commitCommentMutation(editor, () => putCommentRecords(editor, [{ ...thread, anchor }]), 'drag')
-	}
-
-	// The pin (and its popover) track the live edit: a resize moves it to the region's pin corner, a
-	// move to the drag point; otherwise it sits at the stored anchor's viewport point.
-	const livePinPage = resizeBounds
-		? regionPinPoint(resizeBounds, regionOptions.pinCorner)
-		: dragPagePoint
-	const renderPoint = livePinPage ? editor.pageToViewport(livePinPage) : point
-
-	// A region's live box bounds, by priority: a corner resize, else a pin-drag translation (the pin
-	// corner tracks the cursor), else the stored anchor. Undefined for non-region threads.
-	const regionAnchor = thread.anchor.type === 'region' ? thread.anchor : undefined
-	const movedRegion =
-		regionAnchor && dragPagePoint
-			? {
-					...regionAnchor,
-					x: dragPagePoint.x - regionOptions.pinCorner.x * regionAnchor.w,
-					y: dragPagePoint.y - regionOptions.pinCorner.y * regionAnchor.h,
-				}
-			: regionAnchor
-	const regionBoxBounds = resizeBounds ?? movedRegion
-	const commitResize = (bounds: BoxModel) => {
-		setResizeBounds(null)
-		editor.run(
-			() => putCommentRecords(editor, [{ ...thread, anchor: { type: 'region', ...bounds } }]),
-			{
-				history: 'ignore',
-			}
-		)
+		return <ThreadPin editor={editor} thread={thread} {...props} />
 	}
 
+	// Portalled rather than rendered into this component's slot: pins sit below the collaborator
+	// cursors and popovers above the UI panels, and no single canvas layer spans both. The portal
+	// also fixes where the layer lands among the container's children, keeping it behind the UI's
+	// skip link in the tab order.
 	return (
-		<>
-			{regionBoxBounds && (dragPagePoint || revealed) && (
-				<RegionBox
-					editor={editor}
-					box={regionBoxBounds}
-					movable={bodyMovable && !dragPagePoint}
-					onPreview={setResizeBounds}
-					onCommit={commitResize}
-				/>
-			)}
-			{regionBoxBounds && revealed && !dragPagePoint && regionOptions.resize !== 'none' && (
-				<RegionResizeHandles
-					editor={editor}
-					box={regionBoxBounds}
-					handles={resizeHandles}
-					onPreview={setResizeBounds}
-					onCommit={commitResize}
-				/>
-			)}
-			<div
-				className={open ? 'cmt-canvas-pin cmt-canvas-pin--open' : 'cmt-canvas-pin'}
-				style={{ left: renderPoint.x, top: renderPoint.y }}
-			>
-				<div
-					ref={markerRef}
-					className="cmt-canvas-pin__marker"
-					onPointerDown={startDrag}
-					onPointerMove={onDrag}
-					onPointerUp={endDrag}
-					onPointerEnter={() => setPinHovered(true)}
-					onPointerLeave={() => setPinHovered(false)}
-				>
-					<CommentPin resolved={thread.resolved != null} open={open}>
-						{pinContent}
-					</CommentPin>
-				</div>
-				{/* The popover portals up to the menus layer (above the UI panels) so it isn't clipped;
-			    the pin itself stays in the canvas-in-front layer, beneath the UI. */}
-				{open && (
-					<ThreadPopover
-						container={container}
-						style={{ left: renderPoint.x + 36, top: renderPoint.y - 28 }}
-					>
-						<CommentThread
-							header={msg('comments.thread-title')}
-							headerActions={headerActions}
-							renderComment={renderComment}
-							comments={comments.map((c) => toCardProps(c, props, options.components))}
-							resolvedBanner={
-								thread.resolved
-									? msg('comments.resolved-by').replace(
-											'{name}',
-											resolveName(thread.resolved.by) ?? UNKNOWN_AUTHOR
-										)
-									: undefined
-							}
-							composer={
-								currentUserId && !thread.resolved
-									? {
-											author: resolveName(currentUserId) ?? UNKNOWN_AUTHOR,
-											placeholder: msg('comments.reply-placeholder'),
-											sendLabel: msg('comments.send'),
-											value: reply,
-											onChange: setReply,
-											onSubmit: postReply,
-											disabled: isCommentEmpty(reply),
-											getMentionSuggestions,
-											renderMentionSuggestion,
-										}
-									: undefined
+		<EditorPortal>
+			{/* Wheel pass-through lives on each interactive element, not this root: the root spans the
+			    whole canvas, so a pin past its bottom/right edge inflates scrollHeight and the wheel
+			    hook's is-this-scrollable guard silently disables pass-through. */}
+			<div className="tlui-cmt-canvas-layer">
+				{options.enableClustering ? (
+					<>
+						{fadeNodes.map(({ node, phase }) => {
+							let content: ReactNode
+							const stackGroup = node.count > 1 ? stackGroupOf(node) : null
+							if (node.count === 1) {
+								const thread = threadsById.get(node.id)
+								if (!thread) return null
+								content = renderThreadPin(thread)
+							} else if (stackGroup) {
+								// Routed through the stack's owner so the open/orphan/held slots stay deduped:
+								// when the owner is one of them, that slot draws the stack and this draws nothing.
+								const owner = stackGroup.find((id) => renderedThreadIds.has(id))
+								content =
+									owner && node.members.includes(owner)
+										? renderThreadPin(threadsById.get(owner)!)
+										: null
+							} else {
+								content = (
+									<ClusterBadge
+										editor={editor}
+										node={node}
+										onExpand={expandCluster}
+										onSelectThread={revealClusteredThread}
+										threadsById={threadsById}
+										currentUserId={props.currentUserId}
+										resolveAuthor={props.resolveAuthor}
+									/>
+								)
 							}
-						/>
-					</ThreadPopover>
+							return (
+								<div key={`cluster-fade:${node.id}`} className={clusterFadeClassName(phase)}>
+									{content}
+								</div>
+							)
+						})}
+						{orphanThreads.map((thread) => (
+							<Fragment key={thread.id}>{renderThreadPin(thread)}</Fragment>
+						))}
+						{heldThreads.map((thread) => (
+							<Fragment key={thread.id}>{renderThreadPin(thread)}</Fragment>
+						))}
+					</>
+				) : (
+					// Clustering off: every thread renders its own pin. The open thread is excluded and
+					// rendered once below, or it would mount a second, stacked pin.
+					threads
+						.filter((thread) => thread.id !== openId)
+						.map((thread) => <Fragment key={thread.id}>{renderThreadPin(thread)}</Fragment>)
+				)}
+				{openThread && (
+					<Fragment key={`open:${openThread.id}`}>{renderThreadPin(openThread)}</Fragment>
+				)}
+				<RegionDraftBox editor={editor} />
+				{/* Keep the region visible while composing — the drag draft is gone by now, and no thread
+				    exists yet, so the pending anchor is what shows the area under the open composer. */}
+				{pending?.anchor.type === 'region' && showPendingComposer && (
+					<RegionBox editor={editor} box={pending.anchor} />
+				)}
+				{pending && showPendingComposer && (
+					<PendingComposer editor={editor} pending={pending} {...props} />
 				)}
 			</div>
-		</>
-	)
-})
-
-function PendingComposer({
-	editor,
-	pending,
-	currentUserId,
-	resolveName,
-	onPostComment,
-	getMentionSuggestions,
-	renderMentionSuggestion,
-}: CanvasCommentsProps & { editor: Editor; pending: PendingComment }) {
-	const [text, setText] = useState<TLRichText>(EMPTY_COMMENT)
-	const ref = useRef<HTMLDivElement>(null)
-	const msg = useTranslation()
-	const container = useContainer()
-	// Over this floating panel, scroll and hover reach the canvas (except where it scrolls itself).
-	usePassThroughWheelEvents(ref)
-	usePassThroughMouseOverEvents(ref)
-
-	const point = useValue('composer point', () => editor.pageToViewport(pending.point), [
-		editor,
-		pending.point,
-	])
-
-	// Dismiss on a click anywhere outside the composer (capture-phase, ahead of stopPropagation).
-	useEffect(() => {
-		const onPointerDown = (e: PointerEvent) => {
-			const el = ref.current
-			const target = e.target as HTMLElement | null
-			if (!el || !target) return
-			// A click in the composer, or in the mention picker it spawns (portaled elsewhere), is
-			// not "outside" — keep the draft open so the pick can insert.
-			if (el.contains(target) || target.closest('.cmt-mention-popup')) return
-			pendingComment.set(editor, null)
-		}
-		document.addEventListener('pointerdown', onPointerDown, true)
-		return () => document.removeEventListener('pointerdown', onPointerDown, true)
-	}, [editor])
-
-	const submit = () => {
-		if (isCommentEmpty(text) || !currentUserId) return
-		commitCommentMutation(editor, () => {
-			const pageId = editor.getCurrentPageId()
-			const thread = createCommentThread({
-				pageId,
-				anchor: pending.anchor,
-				createdBy: currentUserId,
-			})
-			const comment = createComment({
-				threadId: thread.id,
-				pageId,
-				authorId: currentUserId,
-				body: text,
-			})
-			putCommentRecords(editor, [thread, comment])
-			if (onPostComment) onPostComment(comment)
-		})
-		setText(EMPTY_COMMENT)
-		pendingComment.set(editor, null)
-	}
-
-	return createPortal(
-		<div
-			ref={ref}
-			className="cmt-canvas-composer"
-			style={{ left: point.x, top: point.y }}
-			onPointerDown={stop}
-			onKeyDown={(e) => {
-				if (e.key === 'Escape' && !isMentionPickerOpen()) pendingComment.set(editor, null)
-			}}
-		>
-			<CommentComposer
-				author={currentUserId ? (resolveName(currentUserId) ?? UNKNOWN_AUTHOR) : ''}
-				placeholder={msg('comments.add-placeholder')}
-				sendLabel={msg('comments.send')}
-				value={text}
-				onChange={setText}
-				onSubmit={submit}
-				disabled={isCommentEmpty(text)}
-				getMentionSuggestions={getMentionSuggestions}
-				renderMentionSuggestion={renderMentionSuggestion}
-				autoFocus
-				leading={draftAvatar}
-			/>
-		</div>,
-		container
+		</EditorPortal>
 	)
 }