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

package/src/clustering/screen-offsets.test.ts

@@ -0,0 +1,171 @@
+import type { VecLike } from 'tldraw'
+import { describe, expect, it } from 'vitest'
+import { computeClusterTable } from './computeClusterTable'
+import type { LeafInput } from './types'
+
+function leaf(id: string, x: number, y: number): LeafInput {
+	return { id, point: { x, y } }
+}
+
+function mulberry32(seed: number): () => number {
+	let a = seed >>> 0
+	return () => {
+		a = (a + 0x6d2b79f5) >>> 0
+		let t = a
+		t = Math.imul(t ^ (t >>> 15), t | 1)
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+function randomLeaves(n: number, seed: number, scale = 1000): LeafInput[] {
+	const rand = mulberry32(seed)
+	return Array.from({ length: n }, (_, i) => leaf(`leaf-${i}`, rand() * scale, rand() * scale))
+}
+
+const ZOOM_BOUNDS = { minZoom: 0.05, maxZoom: 8 }
+// eps 0 keeps every merge as its own solo event, so the exact thresholds under test aren't
+// snapped to a contraction window's anchor.
+const EXACT_OPTS = { Tc: 22, Tu: 26.4, eps: 0, Dmax: 82.5, ...ZOOM_BOUNDS }
+
+function offsets(entries: Record<string, VecLike>): Map<string, VecLike> {
+	return new Map(Object.entries(entries))
+}
+
+describe('computeClusterTable without screen offsets (the guarantee)', () => {
+	it('is deep-equal across omitted, undefined, and empty offset arguments', () => {
+		for (const seed of [3, 21]) {
+			const leaves = randomLeaves(40, seed)
+			const plain = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+			expect(computeClusterTable(leaves, { ...ZOOM_BOUNDS }, undefined)).toEqual(plain)
+			expect(computeClusterTable(leaves, { ...ZOOM_BOUNDS }, new Map())).toEqual(plain)
+		}
+	})
+
+	it('is deep-equal when every leaf carries the same offset (Δō is always zero)', () => {
+		const leaves = randomLeaves(30, 11)
+		const uniform = new Map(leaves.map((l) => [l.id, { x: -20, y: 20 }]))
+		expect(computeClusterTable(leaves, { ...ZOOM_BOUNDS }, uniform)).toEqual(
+			computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+		)
+	})
+
+	it('never emits a zSplit override on the offset-free path', () => {
+		const table = computeClusterTable(randomLeaves(20, 5), { ...ZOOM_BOUNDS }, new Map())
+		for (const event of table.events) {
+			// finalize always derives ratio splits when no override was carried
+			expect(event.zSplit).toBeCloseTo(event.zMerge * 1.2, 10)
+		}
+	})
+})
+
+describe('offset-aware pricing', () => {
+	const A = leaf('a', 0, 0)
+	const B = leaf('b', 100, 0)
+
+	it('merges earlier when the insets point toward each other, at the exact visual crossing', () => {
+		// Visual positions: a at 100·0·z + 20, b at 100z − 20 → distance |100z − 40|. Tc = 22
+		// crosses at z = 0.62 (raw anchors would say 0.22); the split derives from the Tu/Tc
+		// ratio, as for every event.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: 20, y: 0 }, b: { x: -20, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBeCloseTo(0.62, 10)
+		expect(table.events[0].zSplit).toBeCloseTo(0.62 * 1.2, 10)
+	})
+
+	it('merges later when the insets point apart, at the exact visual crossing', () => {
+		// Distance 100z + 10: Tc at z = 0.12 (raw: 0.22); ratio split at 0.144.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: -5, y: 0 }, b: { x: 5, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBeCloseTo(0.12, 10)
+		expect(table.events[0].zSplit).toBeCloseTo(0.144, 10)
+	})
+
+	it('never merges a pair whose visual distance never reaches Tc', () => {
+		// Distance 100z + 40 ≥ 40 > Tc at every zoom: priced 0 and pruned by the minZoom cut.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: -20, y: 0 }, b: { x: 20, y: 0 } })
+		)
+		expect(table.events).toEqual([])
+	})
+
+	it('still applies the Dmax fit cap to a corrected merge', () => {
+		// Exaggerated inward offsets put the Tc crossing at z = 1.42, above the spread cap
+		// Dmax/diag = 82.5/100 = 0.825, so the cap wins the min.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: 60, y: 0 }, b: { x: -60, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBeCloseTo(0.825, 10)
+		expect(table.events[0].zSplit).toBeCloseTo(0.825 * 1.2, 10)
+	})
+
+	it('treats coincident anchors with differing offsets as a constant visual distance', () => {
+		// Same anchor point, one pin tucked: constant 20px apart < Tc → merged at every zoom,
+		// entering the same maxSplitZoom band as a coincident pair (zMerge 6/1.2 = 5, zSplit 6).
+		const table = computeClusterTable(
+			[leaf('a', 50, 50), leaf('b', 50, 50)],
+			{ ...EXACT_OPTS, maxSplitZoom: 6 },
+			offsets({ a: { x: 20, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBe(5)
+		expect(table.events[0].zSplit).toBe(6)
+	})
+
+	it("dilutes a cluster's mean offset as precise members fold in", () => {
+		// a (tucked 20px) and b (precise) share an anchor: constant 20px apart, always merged.
+		// Their cluster's mean offset is (10, 0); against precise c 100 units right the visual
+		// distance is |100z − 10| → Tc at z = 0.32 — half the lone pin's correction.
+		const table = computeClusterTable(
+			[leaf('a', 0, 0), leaf('b', 0, 0), leaf('c', 100, 0)],
+			EXACT_OPTS,
+			offsets({ a: { x: 20, y: 0 } })
+		)
+		expect(table.events).toHaveLength(2)
+		const outer = table.events.find((e) => e.result.count === 3)!
+		expect(outer.zMerge).toBeCloseTo(0.32, 10)
+		expect(outer.zSplit).toBeCloseTo(0.32 * 1.2, 10)
+	})
+})
+
+describe('table ordering with offsets', () => {
+	it('keeps zMerge and zSplit non-increasing (splits are always ratio-derived)', () => {
+		// Mixed offset and plain leaves at varied spacings: every split is zMerge · (Tu/Tc), so
+		// both threshold sequences inherit the table's non-increasing order — the invariant the
+		// runtime's prefix cursor, split walk, and seed bisection rely on.
+		const leaves = [
+			leaf('a', 0, 0),
+			leaf('b', 100, 0),
+			leaf('c', 130, 0),
+			leaf('d', 400, 0),
+			leaf('e', 470, 0),
+			leaf('f', 1000, 300),
+		]
+		const table = computeClusterTable(
+			leaves,
+			EXACT_OPTS,
+			offsets({ a: { x: -20, y: 0 }, b: { x: 14, y: 0 }, d: { x: 20, y: 14 } })
+		)
+		expect(table.events.length).toBeGreaterThan(2)
+		for (let i = 1; i < table.events.length; i++) {
+			expect(table.events[i].zMerge).toBeLessThanOrEqual(table.events[i - 1].zMerge)
+			expect(table.events[i].zSplit).toBeLessThanOrEqual(table.events[i - 1].zSplit)
+		}
+		for (const event of table.events) {
+			expect(event.zSplit).toBeCloseTo(event.zMerge * 1.2, 10)
+		}
+	})
+})

package/src/clustering/types.ts

@@ -11,6 +11,16 @@ export interface LeafInput {
 	point: VecLike
 }
 
+/**
+ * Constant screen-px render offsets for markers that don't draw exactly on their anchor —
+ * imprecise shape pins, which tuck ~20px into their shape. Keyed by leaf id; leaves absent from
+ * the map render on their anchor. A marker's visual position at zoom z is `z · point + offset`.
+ * Passed as the optional third argument to `computeClusterTable`; when omitted or empty the
+ * algorithm's behavior (and output) is identical to an offset-unaware run.
+ * @internal
+ */
+export type LeafScreenOffsets = ReadonlyMap<string, VecLike>
+
 /** An edge of the Euclidean MST over the leaf anchor points. */
 export interface MstEdge {
 	/** Index into the input leaves array. Normalized: leaves[a].id < leaves[b].id (lexicographic). */

package/src/index.ts

@@ -23,13 +23,15 @@ export { CountBadge, type CountBadgeProps } from './ui/count-badge'
 export { CommentPin, type CommentPinProps } from './ui/comment-pin'
 export { CommentThread, type CommentThreadProps } from './ui/comment-thread'
 export {
+	CommentListItem,
 	CommentsList,
 	isOpenInNewTabClick,
 	type CommentListItemProps,
+	type CommentListItemRenderProps,
 	type CommentsListProps,
 } from './ui/comments-list'
 export { EmptyState, type EmptyStateProps } from './ui/empty-state'
-export { formatRelativeTime } from './ui/format-time'
+export { formatFullDateTime, formatRelativeTime } from './ui/format-time'
 export {
 	DEFAULT_REACTION_EMOJI,
 	EmojiPicker,
@@ -73,6 +75,7 @@ export {
 	type CommentReactionPickerProps,
 	CommentReactions,
 	type CommentReactionsProps,
+	type ReactionSummaryInput,
 	summarizeReactions,
 	toggleCommentReaction,
 	useCommentReactions,
@@ -94,16 +97,26 @@ export { CanvasComments, type CanvasCommentsProps } from './canvas/comments-over
 export {
 	type CommentingComponents,
 	type CommentingOptions,
+	type CommentModification,
+	type CommentModificationContext,
+	defaultCanModifyComment,
 	defaultCommentingOptions,
 	getCanComment,
+	getCanModifyComment,
 	getCommentingOptions,
 	type ShapeCommentPrecisionContext,
 	useCanComment,
+	useCanModifyComment,
 	useCommentingOptions,
 } from './canvas/options'
 export { CommentsOverflowMenu } from './canvas/comments-overflow-menu'
 export { CommentsVisibilityToggle } from './canvas/comments-visibility-toggle'
-export { CanvasCommentsSidebar, type CanvasCommentsSidebarProps } from './canvas/comments-sidebar'
+export {
+	CanvasCommentsSidebar,
+	sortSidebarRows,
+	type CanvasCommentsSidebarProps,
+	type SidebarRow,
+} from './canvas/comments-sidebar'
 export { useComments, useCommentThreads, useThreadComments } from './canvas/hooks'
 export { useCommentingEnabled } from './canvas/license'
 export { richTextToPlaintext } from './canvas/rich-text'

package/src/ui/byline.tsx

@@ -1,5 +1,6 @@
 import { Avatar, type CommentAuthor } from '@tldraw/mentions'
-import { formatRelativeTime } from './format-time'
+import { TldrawUiTooltip, useCurrentTranslation } from 'tldraw'
+import { formatFullDateTime, formatRelativeTime } from './format-time'
 
 /** @public */
 export interface BylineProps {
@@ -10,16 +11,25 @@ export interface BylineProps {
 	edited?: boolean
 }
 
-/** A comment's metadata line: author name, relative time, and an edited marker. @public @react */
+/**
+ * A comment's metadata line: author name, relative time, and an edited marker. Hovering the time
+ * shows the full date and time in a tooltip.
+ * @public @react
+ */
 export function Byline({ author, date, edited }: BylineProps) {
+	// The relative time is the one piece of a byline that isn't the host's data, so it follows the
+	// same translation context as every other string in the UI rather than a prop of its own.
+	const { locale } = useCurrentTranslation()
 	return (
 		<div className="tlui-cmt-head">
 			<Avatar author={author} />
 			<span className="tlui-cmt-author">{author.name}</span>
-			<span className="tlui-cmt-time">
-				{formatRelativeTime(date)}
-				{edited && <span className="tlui-cmt-edited"> · edited</span>}
-			</span>
+			<TldrawUiTooltip content={formatFullDateTime(date, locale)}>
+				<span className="tlui-cmt-time">
+					{formatRelativeTime(date, locale)}
+					{edited && <span className="tlui-cmt-edited"> · edited</span>}
+				</span>
+			</TldrawUiTooltip>
 		</div>
 	)
 }

package/src/ui/comment-composer.tsx

@@ -66,12 +66,10 @@ export function CommentComposer({
 	renderMentionSuggestion,
 }: CommentComposerProps) {
 	const interactive = !!onChange || !!onSubmit
-	// The canvas editor the composer lives in, if any — lets the mention popup track the camera. Null
-	// when the composer is used outside a tldraw editor (e.g. an isolated demo).
+	// Lets the mention popup track the camera. Null outside a tldraw editor.
 	const tlEditor = useMaybeEditor()
 
-	// Callbacks are read through refs so the editor instance doesn't need to be recreated when they
-	// change identity between renders.
+	// Read through refs so the editor isn't recreated when callback identity changes.
 	const onChangeRef = useRef(onChange)
 	onChangeRef.current = onChange
 	const onSubmitRef = useRef(onSubmit)
@@ -94,17 +92,16 @@ export function CommentComposer({
 	const inputWrapRef = useRef<HTMLDivElement>(null)
 	const mirrorRef = useRef<HTMLDivElement>(null)
 
-	// Measure whether the content still fits on one line beside the send button. The mirror is a
-	// hidden, nowrap clone of the editor's rendered content, so marks and mention chips measure at
-	// their true width. A small dead zone between the expand and collapse thresholds keeps the
-	// layout from flapping while typing at the boundary.
+	// Measure whether the content still fits on one line beside the send button, against a hidden
+	// nowrap clone so marks and mention chips measure at their true width. The gap between the
+	// expand and collapse thresholds is a dead zone, so the layout can't flap at the boundary.
 	const remeasure = () => {
 		const wrap = inputWrapRef.current
 		const mirror = mirrorRef.current
 		const editor = editorRef.current
 		if (!wrap || !mirror || !editor) return
-		// Empty always fits — and measuring before TipTap's DOM has laid out reads zero widths,
-		// which would flash the expanded layout for a frame on mount.
+		// Empty always fits — and measuring before TipTap has laid out reads zero widths, flashing
+		// the expanded layout for a frame on mount.
 		if (editor.isEmpty) {
 			if (expandedRef.current) setExpanded(false)
 			return
@@ -123,11 +120,8 @@ export function CommentComposer({
 		if (!send || !input) return
 		mirror.innerHTML = input.innerHTML
 		const textWidth = mirror.offsetWidth
-		// The single-line space the input has beside the send button: the wrap's *content* box
-		// (clientWidth minus its own horizontal padding — the text wraps there, not at clientWidth),
-		// less the button plus the field's 6px gap when already expanded (the wrap then spans the
-		// full field). Without subtracting the padding, a padded wrap wraps to a second line ~padding
-		// px before expansion fires, so the input grows a line and then snaps to the expanded layout.
+		// Measured against the wrap's *content* box: text wraps at clientWidth minus padding, so
+		// without subtracting it the input grows a line before expansion fires and then snaps.
 		const wrapStyle = getComputedStyle(wrap)
 		const wrapPadX = parseFloat(wrapStyle.paddingLeft) + parseFloat(wrapStyle.paddingRight)
 		const collapsedAvailable =
@@ -141,34 +135,22 @@ export function CommentComposer({
 	const remeasureRef = useRef(remeasure)
 	remeasureRef.current = remeasure
 
-	// The editor instance, reachable from `handleKeyDown` (which is created before `useEditor`
-	// returns). Updated on every render so the ref never points at a stale editor.
+	// Reachable from `handleKeyDown`, which is created before `useEditor` returns.
 	const editorRef = useRef<ReturnType<typeof useEditor>>(null)
 
-	// Set while we replay Enter through the keymaps for a Shift+Enter newline: `commands.enter()`
-	// re-dispatches Enter through `handleKeyDown`, and without this guard our own handler would catch
-	// that synthetic Enter and submit instead.
+	// `commands.enter()` re-dispatches through `handleKeyDown`; without this guard our own handler
+	// would catch the synthetic Enter and submit.
 	const replayingEnter = useRef(false)
 
-	// Enter and Cmd/Ctrl+Enter submit the comment; Shift+Enter inserts a new line for the occasional
-	// multi-line comment. This is handled through `editorProps.handleKeyDown` (below) rather than a
-	// keyboard-shortcut extension: ProseMirror runs `handleKeyDown` before every keymap plugin, so it
-	// can tell Shift+Enter apart from Enter — an `Enter` keymap binding also fires on Shift/Cmd+Enter
-	// and would otherwise swallow the newline.
-
-	// The suggestion plugin is built once (the editor is recreated only on `interactive`) and runs
-	// outside React, so it must read the mention callbacks through refs — like onChange/onSubmit —
-	// or it queries the roster present at mount forever, never seeing a member who loads or joins
-	// later. Whether mentions (and a custom picker row) are wired at all is fixed at mount; only the
-	// callbacks themselves are live.
+	// The suggestion plugin is built once and runs outside React, so it reads the mention callbacks
+	// through refs — otherwise it queries the roster present at mount forever, never seeing a member
+	// who joins later. Whether mentions are wired at all is fixed at mount; the callbacks are live.
 	const mentionsEnabled = !!getMentionSuggestions
 	const hasCustomRow = !!renderMentionSuggestion
 	const extensions = useMemo(() => {
 		const list = [...commentTipTapExtensions]
-		// Always register the mention node so an existing body that contains a mention keeps it on
-		// edit (an unregistered node would be stripped by ProseMirror when the content loads). The `@`
-		// picker itself only turns on when the host provides a resolver; otherwise the node is present
-		// but its trigger is disabled.
+		// The mention node is always registered, or ProseMirror strips existing mentions when an
+		// edited body loads. Only the `@` trigger is gated on the host providing a resolver.
 		if (mentionsEnabled) {
 			const resolveSuggestions = (query: string) => getMentionSuggestionsRef.current?.(query) ?? []
 			const renderRow = hasCustomRow
@@ -193,9 +175,8 @@ export function CommentComposer({
 			extensions,
 			content: (value ?? EMPTY_COMMENT) as JSONContent,
 			editable: interactive,
-			// tldraw's default extensions add their own TextDirection extension (so it can be
-			// overridden), so disable TipTap's core one to avoid a duplicate-extension warning —
-			// mirrors RichTextArea's setup.
+			// tldraw ships its own TextDirection extension, so TipTap's core one would warn about a
+			// duplicate. Mirrors RichTextArea's setup.
 			enableCoreExtensions: { textDirection: false },
 			textDirection: 'auto',
 			editorProps: {
@@ -210,8 +191,8 @@ export function CommentComposer({
 				handleKeyDown: (_view, event) => {
 					// Let the keymaps handle the synthetic Enter we replay for a Shift+Enter newline.
 					if (replayingEnter.current) return false
-					// Up in an empty composer hands off to the host (edit the comment above). With
-					// content, Up stays cursor movement; with the mention picker open, it navigates it.
+					// Up in an empty composer hands off to the host. With content it stays cursor
+					// movement, and with the picker open it navigates the roster.
 					if (event.key === 'ArrowUp' && !event.isComposing) {
 						if (
 							onArrowUpWhenEmptyRef.current &&
@@ -226,12 +207,10 @@ export function CommentComposer({
 					if (event.key !== 'Enter' || event.isComposing) return false
 					// While the @-mention picker is open, Enter selects the highlighted member — defer.
 					if (isMentionPickerOpen()) return false
-					// Shift+Enter inserts a new line. Replay a plain Enter through the keymaps (guarded so
-					// we don't re-enter and submit) to reuse the editor's list-aware Enter handling — a new
-					// list item in a list, a new paragraph otherwise. tldraw doesn't do soft breaks.
+					// Shift+Enter inserts a new line by replaying a plain Enter through the keymaps, reusing
+					// the editor's list-aware handling. tldraw doesn't do soft breaks.
 					if (event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey) {
-						// An empty field has nothing to break onto — swallow the keypress so it doesn't
-						// open the comment with a stray leading blank line.
+						// An empty field would open the comment with a stray leading blank line.
 						if (editorRef.current?.isEmpty) return true
 						replayingEnter.current = true
 						try {
@@ -248,8 +227,7 @@ export function CommentComposer({
 			},
 			onUpdate: ({ editor }) => {
 				setIsEmpty(editor.isEmpty)
-				// Same-value state sets don't re-render, so measure here — the editor's DOM is
-				// already updated when onUpdate fires.
+				// Same-value state sets don't re-render, and the DOM is already updated here.
 				remeasureRef.current()
 				onChangeRef.current?.(editor.getJSON() as TLRichText)
 			},
@@ -281,28 +259,6 @@ export function CommentComposer({
 		return () => cancelAnimationFrame(raf)
 	}, [autoFocus, editor])
 
-	// tldraw's pass-through-wheel hook (on the floating composer's wrapper) forwards a wheel to the
-	// canvas unless ITS element is scrollable — but the scrollable element is this input, not that
-	// wrapper, so an overflowing input never scrolled: the wheel panned the canvas instead. Catch the
-	// wheel on the wrap first (a native listener here fires before the wrapper's, deeper in the tree)
-	// and stop it while the input can still scroll that way; at the scroll boundary let it through so
-	// the canvas still zooms.
-	useEffect(() => {
-		const wrap = inputWrapRef.current
-		if (!wrap) return
-		const onWheel = (e: WheelEvent) => {
-			const input = wrap.querySelector<HTMLElement>('.tlui-cmt-input')
-			if (!input || input.scrollHeight <= input.clientHeight) return
-			const atTop = input.scrollTop <= 0
-			const atBottom = input.scrollTop >= input.scrollHeight - input.clientHeight - 1
-			if ((e.deltaY < 0 && !atTop) || (e.deltaY > 0 && !atBottom)) {
-				e.stopPropagation()
-			}
-		}
-		wrap.addEventListener('wheel', onWheel)
-		return () => wrap.removeEventListener('wheel', onWheel)
-	}, [])
-
 	// The whole field behaves like the text input: clicking its empty area (the padding, or the
 	// space beside/below a short line) focuses the editor rather than only the text glyphs being
 	// clickable. The input (caret placement) and the send button keep their own click handling.

package/src/ui/comment-pin.tsx

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react'
+import { PinCheckIcon } from './icons'
 
 /** @public */
 export interface CommentPinProps {
@@ -10,22 +11,8 @@ export interface CommentPinProps {
 	open?: boolean
 }
 
-/* An inline check, not a text glyph — the '✓' character sits off-baseline and varies by font. */
-const resolvedCheck = (
-	<svg
-		viewBox="0 0 24 24"
-		width="15"
-		height="15"
-		fill="none"
-		stroke="currentColor"
-		strokeWidth="2.5"
-		strokeLinecap="round"
-		strokeLinejoin="round"
-		aria-hidden="true"
-	>
-		<path d="M4 12.5l5 5L20 6.5" />
-	</svg>
-)
+/* Decorative — the pin's accessible name lives on whatever wraps it. */
+const resolvedCheck = <PinCheckIcon />
 
 /** A canvas comment marker: shows its `children` (or a check when resolved). Purely
  * presentational — it reflects open/resolved state via CSS; wrap it to make it clickable.

package/src/ui/comments-list.tsx

@@ -1,7 +1,9 @@
 import { Avatar, type CommentAuthor } from '@tldraw/mentions'
-import { MouseEvent, ReactNode } from 'react'
+import { Fragment, MouseEvent, ReactNode } from 'react'
 import { useTranslation } from 'tldraw'
 import { Byline } from './byline'
+import { CheckIcon } from './icons'
+import { Reactions, type ReactionSummary } from './reactions'
 import { replyCountLabel } from './reply-count'
 
 /** @public */
@@ -19,6 +21,9 @@ export interface CommentListItemProps {
 	count?: number
 	/** Whether this thread is the open one. */
 	selected?: boolean
+	/** Tallied reactions for the row (a thread's, or a single comment's when the row is one
+	 *  comment), shown as inert pills under the preview. Omit to hide. */
+	reactions?: ReactionSummary[]
 	/**
 	 * Link target for the item. When set, the row renders as an anchor so browser affordances
 	 * (ctrl/cmd-click, middle-click) open it in a new tab; a plain click still calls `onSelect`.
@@ -26,6 +31,20 @@ export interface CommentListItemProps {
 	href?: string
 }
 
+/**
+ * What a row is rendered with: the item, plus the list-level wiring it needs to be interactive.
+ * A custom row gets the same props the default `<CommentListItem>` does, so it can wrap the
+ * default rather than reimplement it.
+ *
+ * @public
+ */
+export interface CommentListItemRenderProps extends CommentListItemProps {
+	/** Label for a resolved thread's marker on its row. */
+	resolvedLabel?: string
+	/** Called with the thread id when the row is chosen. */
+	onSelect?(id: string): void
+}
+
 /** @public */
 export interface CommentsListProps {
 	items: CommentListItemProps[]
@@ -39,8 +58,12 @@ export interface CommentsListProps {
 	empty?: ReactNode
 	/** Label for a resolved thread's marker on its row. Defaults to "Resolved". */
 	resolvedLabel?: string
-	/** Override how each item renders. Defaults to `<CommentListItem>`. */
-	renderItem?(item: CommentListItemProps): ReactNode
+	/**
+	 * Override how each item renders. Defaults to `<CommentListItem>`, which is exported — so a
+	 * row that only adds something can spread these props into it rather than start over. The list
+	 * supplies the key, so a custom row doesn't need one.
+	 */
+	renderItem?(props: CommentListItemRenderProps): ReactNode
 }
 
 /**
@@ -70,25 +93,25 @@ export function CommentsList({
 				<div className="tlui-cmt-list__empty">{empty}</div>
 			) : (
 				<div className="tlui-cmt-list__items">
-					{items.map((item) =>
-						renderItem ? (
-							renderItem(item)
+					{items.map((item) => {
+						const props: CommentListItemRenderProps = { ...item, resolvedLabel, onSelect }
+						// A custom row is wrapped rather than keyed directly: it's the consumer's element,
+						// and requiring them to remember a key is the kind of thing that only shows up as a
+						// console warning in someone else's app.
+						return renderItem ? (
+							<Fragment key={item.id}>{renderItem(props)}</Fragment>
 						) : (
-							<CommentListItem
-								key={item.id}
-								{...item}
-								resolvedLabel={resolvedLabel}
-								onSelect={onSelect}
-							/>
+							<CommentListItem key={item.id} {...props} />
 						)
-					)}
+					})}
 				</div>
 			)}
 		</div>
 	)
 }
 
-function CommentListItem({
+/** One thread's row in a {@link CommentsList}. @public @react */
+export function CommentListItem({
 	id,
 	author,
 	preview,
@@ -97,10 +120,11 @@ function CommentListItem({
 	page,
 	count,
 	selected,
+	reactions,
 	href,
 	resolvedLabel = 'Resolved',
 	onSelect,
-}: CommentListItemProps & { resolvedLabel?: string; onSelect?(id: string): void }) {
+}: CommentListItemRenderProps) {
 	const msg = useTranslation()
 	const handleClick = (e: MouseEvent) => {
 		if (href && isOpenInNewTabClick(e)) return
@@ -123,6 +147,7 @@ function CommentListItem({
 			<div className="tlui-cmt-list__item-body">
 				<Byline author={author} date={date} />
 				<div className="tlui-cmt-list__item-preview">{preview}</div>
+				{reactions && <Reactions reactions={reactions} canReact={false} enableHoverList={false} />}
 				{(resolved || page !== undefined || replies) && (
 					<div className="tlui-cmt-list__item-meta">
 						{resolved && (
@@ -147,17 +172,3 @@ function CommentListItem({
 export function isOpenInNewTabClick(e: MouseEvent) {
 	return e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0
 }
-
-function CheckIcon() {
-	return (
-		<svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
-			<path
-				d="M2.5 6.2 4.7 8.4 9.5 3.6"
-				stroke="currentColor"
-				strokeWidth="1.5"
-				strokeLinecap="round"
-				strokeLinejoin="round"
-			/>
-		</svg>
-	)
-}