@tldraw/commenting 0.0.0-bootstrap → 5.3.0-canary.31036673d3f8

package/src/canvas/options.ts

@@ -4,8 +4,26 @@ import {
 	type TLComment,
 	type TLCommentThread,
 	type TLHistoryBatchOptions,
+	type TLShapeId,
+	type VecLike,
 	useEditor,
+	useValue,
 } from 'tldraw'
+import { isAllowedReactionEmoji, type EmojiPickerProps } from '../ui/emoji-picker'
+import { type ReactionTooltipProps } from '../ui/reaction'
+
+/**
+ * The gesture that's creating a shape anchor, passed to
+ * {@link CommentingOptions.shouldBePrecise}: the target shape, the page point of the release, and
+ * whether Alt was held.
+ *
+ * @public
+ */
+export interface ShapeCommentPrecisionContext {
+	readonly shapeId: TLShapeId
+	readonly point: VecLike
+	readonly altKey: boolean
+}
 
 /**
  * Component overrides for the batteries-included comments layer. Each slot replaces a built-in
@@ -20,12 +38,40 @@ export interface CommentingComponents {
 	PinContent?: ComponentType<{ thread: TLCommentThread; comments: TLComment[] }>
 	/** A sidebar row's preview. Replaces the plaintext default. */
 	ThreadPreview?: ComponentType<{ comment: TLComment }>
+	/**
+	 * A reaction's visual, given its token. The default renders the token string for the OS emoji
+	 * font to draw (so the token is the emoji glyph). Override this to render your own palette —
+	 * return an `<img>` for custom emoji, an SVG, or anything. The token is whatever your picker
+	 * emits and is what gets stored/synced; this only controls how it's drawn.
+	 */
+	ReactionContent?: ComponentType<{ token: string }>
+	/**
+	 * What the add-reaction button opens: the thing that produces a reaction token. Replaces the
+	 * default `<EmojiPicker>` grid. Pairs with `ReactionContent` (which draws whatever tokens this
+	 * emits) and with `isAllowedReaction` (which has to accept them).
+	 */
+	ReactionPalette?: ComponentType<EmojiPickerProps>
+	/**
+	 * The hover affordance naming who reacted with an emoji. It receives the reactors and the pill
+	 * (as `children`) and returns the whole thing — so it owns the tooltip, its box, size, shape, and
+	 * position. Replaces the default (`DefaultReactionTooltip`). For a simple wording change, translate
+	 * the `comments.reacted-*` strings instead; reach for this to change the structure — a different
+	 * box, avatars, a banner anywhere on screen.
+	 */
+	ReactionTooltip?: ComponentType<ReactionTooltipProps>
+	/** Shown where a composer would sit when the viewer can't compose (see
+	 *  {@link CommentingOptions.canComment} — a signed-out viewer, a viewer role, a host that
+	 *  turns commenting off). `context` says which surface is rendering it: the bottom of an open
+	 *  thread popover (`'thread'`) or the placement popover the comment tool opens (`'pending'`).
+	 *  Unset, those surfaces render nothing. */
+	ComposerFallback?: ComponentType<{ context: 'pending' | 'thread' }>
 }
 
 /**
  * Configuration for the commenting layer. Static config only — pass it once via
  * `CommentTool.configure({ ... })`, mirroring `ShapeUtil.configure`. Live, reactive values
- * (`currentUserId`, `resolveName`, read-status callbacks) stay as props on `<CanvasComments>`.
+ * (`currentUserId`, author resolution, read-status callbacks) are the `CommentingContext`, passed as
+ * props to each commenting surface.
  *
  * For defaults, see {@link defaultCommentingOptions}.
  *
@@ -55,16 +101,60 @@ export interface CommentingOptions {
 	// ── Feature toggles ──────────────────────────────────────────────────────────────────────
 	/** Fold nearby pins into count badges as the camera zooms out. */
 	readonly enableClustering: boolean
+	/**
+	 * Whether a user may hold several emoji reactions on one comment. `true` (the default) is the
+	 * Slack model: each emoji toggles independently. `false` is single-select: picking a new emoji
+	 * replaces the user's existing reaction. Note this is enforced client-side; the server accepts
+	 * per-emoji records either way.
+	 */
+	readonly allowMultipleReactions: boolean
+	/**
+	 * Whether a token may be added as a reaction. Defaults to {@link isAllowedReactionEmoji} against
+	 * the built-in emoji palette, which is what keeps a scripted client from writing junk `emoji`
+	 * values the picker would never offer. Override it alongside a custom `ReactionPalette` so the
+	 * tokens that palette emits get through. Removals aren't checked — a reaction carrying an
+	 * off-palette token must still be clearable.
+	 */
+	isAllowedReaction(token: string): boolean
+	/**
+	 * Whether dragging the comment tool out creates a region anchor — a comment attached to a
+	 * rectangular area of the page, drawn as a dashed box with the thread's pin on the corner the
+	 * drag released on. Off by default: comments attach to points and shapes only, and a drag just
+	 * trails the composer. A region reveals its box while the pointer is inside it, moves by its
+	 * pin, and resizes from its corners.
+	 */
+	readonly enableRegions: boolean
+
+	// ── Permissions ──────────────────────────────────────────────────────────────────────────
+	/**
+	 * Whether the viewer may participate in commenting: composing new threads and replies, editing
+	 * and deleting comments, resolving threads, and moving pins or regions. Composers render when
+	 * it returns true; when it returns false, the {@link CommentingComponents.ComposerFallback}
+	 * slot renders in their place (or nothing, if that slot is unset) and the action affordances
+	 * are hidden. Unset, participation is allowed exactly when `currentUserId` is set.
+	 *
+	 * Called during render via {@link useCanComment}, so reactive reads (signals) are tracked.
+	 * The comment tool itself stays registered and selectable — hosts that want its toolbar button
+	 * to do something else (e.g. open a sign-in dialog) can override the tool item's `onSelect`.
+	 * Note posting still requires a `currentUserId` to author the records, so a callback that
+	 * returns true for a signed-out viewer yields a composer whose send button stays disabled.
+	 */
+	readonly canComment:
+		| ((ctx: { editor: Editor; currentUserId: string | null }) => boolean)
+		| undefined
 
 	// ── Anchoring ────────────────────────────────────────────────────────────────────────────
 	/** Normalized (0–1) spot within a shape where imprecise shape pins sit. Default top-right. */
 	readonly impreciseShapeAnchor: { readonly x: number; readonly y: number }
-
-	// ── Clustering tuning ─────────────────────────────────────────────────────────────────────
-	/** Screen-pixel margin by which the viewport is inflated when culling cluster badges. */
-	readonly clusterCullMargin: number
-	/** How far past a cluster's split zoom to land when expanding it (1.05 = 5% overshoot). */
-	readonly clusterSplitZoomFactor: number
+	/**
+	 * Whether a comment landing on a shape anchors precisely — pinned to the exact clicked spot
+	 * within the shape — or imprecisely — pinned to the shape as a whole, rendered at
+	 * `impreciseShapeAnchor`. Called wherever a shape anchor is created (placing with the comment
+	 * tool, dropping a dragged pin onto a shape). Always precise by default. Return `false` for
+	 * shape-level anchoring, or decide from the context — the Alt key's state, or the shape itself,
+	 * e.g. precise only on notes. Governs new placements only; existing anchors render as stored.
+	 */
+	shouldBePrecise(editor: Editor, context: ShapeCommentPrecisionContext): boolean
 
 	// ── Components ────────────────────────────────────────────────────────────────────────────
 	/** Component overrides. See {@link CommentingComponents}. */
@@ -80,9 +170,12 @@ export const defaultCommentingOptions = {
 	history: 'ignore',
 	dragHistory: undefined,
 	enableClustering: true,
+	allowMultipleReactions: true,
+	isAllowedReaction: isAllowedReactionEmoji,
+	enableRegions: false,
+	canComment: undefined,
 	impreciseShapeAnchor: { x: 1, y: 0 },
-	clusterCullMargin: 120,
-	clusterSplitZoomFactor: 1.05,
+	shouldBePrecise: () => true,
 	components: {},
 } as const satisfies CommentingOptions
 
@@ -109,3 +202,34 @@ export function useCommentingOptions(): CommentingOptions {
 	const editor = useEditor()
 	return useMemo(() => getCommentingOptions(editor), [editor])
 }
+
+/**
+ * Whether the viewer may participate in commenting, per {@link CommentingOptions.canComment}
+ * (defaulting to `currentUserId != null` when unset). Where this is false, composers give way to
+ * the {@link CommentingComponents.ComposerFallback} slot and action affordances are hidden.
+ *
+ * This is a plain, untracked read — a `canComment` callback that reads signals is not observed.
+ * In React, use {@link useCanComment} instead.
+ *
+ * @public
+ */
+export function getCanComment(editor: Editor, currentUserId: string | null | undefined): boolean {
+	const { canComment } = getCommentingOptions(editor)
+	return canComment
+		? canComment({ editor, currentUserId: currentUserId ?? null })
+		: currentUserId != null
+}
+
+/**
+ * Reactive React hook for {@link getCanComment}: a `canComment` callback that reads signals
+ * re-evaluates when they change.
+ *
+ * @public
+ */
+export function useCanComment(currentUserId: string | null | undefined): boolean {
+	const editor = useEditor()
+	return useValue('can comment', () => getCanComment(editor, currentUserId), [
+		editor,
+		currentUserId,
+	])
+}

package/src/canvas/pin-stacking.test.ts

@@ -0,0 +1,114 @@
+import { Box, Mat, type Editor, type TLCommentAnchor, type TLCommentThread } from 'tldraw'
+import { describe, expect, it } from 'vitest'
+import { computePinStacks } from './pin-stacking'
+
+const CURRENT_PAGE = 'page:one'
+const OTHER_PAGE = 'page:two'
+
+function thread(
+	id: string,
+	anchor: TLCommentAnchor,
+	opts: { pageId?: string; createdAt?: number } = {}
+): TLCommentThread {
+	return {
+		id,
+		typeName: 'comment-thread',
+		pageId: opts.pageId ?? CURRENT_PAGE,
+		anchor,
+		createdBy: 'user:1',
+		createdAt: opts.createdAt ?? 0,
+		resolved: null,
+		meta: {},
+	} as unknown as TLCommentThread
+}
+
+/**
+ * Unrotated shapes: local geometry sized by the box, placed by a translate-only page transform.
+ * No comment tool registered, so the commenting options `anchorPagePoint` reads are the defaults.
+ */
+function stubEditor(
+	shapes: Record<string, { minX: number; minY: number; maxX: number; maxY: number }> = {}
+): Editor {
+	const shapeId = (shape: string | { id: string }) => (typeof shape === 'string' ? shape : shape.id)
+	return {
+		getCurrentPageId: () => CURRENT_PAGE,
+		getStateDescendant: () => undefined,
+		getShape: (id: string) => (shapes[id] ? { id } : undefined),
+		getShapeGeometry: (shape: string | { id: string }) => {
+			const bounds = shapes[shapeId(shape)]
+			return { bounds: new Box(0, 0, bounds.maxX - bounds.minX, bounds.maxY - bounds.minY) }
+		},
+		getShapePageTransform: (shape: string | { id: string }) => {
+			const bounds = shapes[shapeId(shape)]
+			return bounds ? Mat.Translate(bounds.minX, bounds.minY) : undefined
+		},
+	} as unknown as Editor
+}
+
+const SHAPE = { 'shape:a': { minX: 0, minY: 0, maxX: 200, maxY: 100 } }
+
+function impreciseAnchor(shapeId: string): TLCommentAnchor {
+	return { type: 'shape', shapeId, x: 0.2, y: 0.9, isPrecise: false } as TLCommentAnchor
+}
+
+describe('computePinStacks', () => {
+	it('groups coincident imprecise pins on one shape, oldest first', () => {
+		const stacks = computePinStacks(stubEditor(SHAPE), [
+			thread('t2', impreciseAnchor('shape:a'), { createdAt: 20 }),
+			thread('t1', impreciseAnchor('shape:a'), { createdAt: 10 }),
+		])
+		expect(stacks.get('t1')).toEqual(['t1', 't2'])
+		expect(stacks.get('t2')).toEqual(['t1', 't2'])
+	})
+
+	it('leaves separated pins ungrouped', () => {
+		const stacks = computePinStacks(stubEditor(), [
+			thread('t1', { type: 'point', x: 0, y: 0 }),
+			thread('t2', { type: 'point', x: 50, y: 0 }),
+		])
+		expect(stacks.size).toBe(0)
+	})
+
+	it('groups coincident point anchors', () => {
+		const stacks = computePinStacks(stubEditor(), [
+			thread('t1', { type: 'point', x: 5, y: 5 }, { createdAt: 1 }),
+			thread('t2', { type: 'point', x: 5, y: 5 }, { createdAt: 2 }),
+			thread('t3', { type: 'point', x: 5, y: 5 }, { createdAt: 3 }),
+		])
+		expect(stacks.get('t2')).toEqual(['t1', 't2', 't3'])
+	})
+
+	it('breaks creation-time ties by id so ordering is deterministic', () => {
+		const stacks = computePinStacks(stubEditor(), [
+			thread('t2', { type: 'point', x: 5, y: 5 }, { createdAt: 1 }),
+			thread('t1', { type: 'point', x: 5, y: 5 }, { createdAt: 1 }),
+		])
+		expect(stacks.get('t1')).toEqual(['t1', 't2'])
+	})
+
+	it('ignores threads on other pages and unresolvable anchors', () => {
+		const stacks = computePinStacks(stubEditor(SHAPE), [
+			thread('t1', impreciseAnchor('shape:a')),
+			thread('t2', impreciseAnchor('shape:a'), { pageId: OTHER_PAGE }),
+			thread('t3', impreciseAnchor('shape:gone')),
+		])
+		expect(stacks.size).toBe(0)
+	})
+
+	it('does not group a precise pin sitting away from a coincident pair', () => {
+		const precise: TLCommentAnchor = {
+			type: 'shape',
+			shapeId: 'shape:a',
+			x: 0.5,
+			y: 0.5,
+			isPrecise: true,
+		} as TLCommentAnchor
+		const stacks = computePinStacks(stubEditor(SHAPE), [
+			thread('t1', impreciseAnchor('shape:a'), { createdAt: 1 }),
+			thread('t2', impreciseAnchor('shape:a'), { createdAt: 2 }),
+			thread('t3', precise),
+		])
+		expect(stacks.get('t1')).toEqual(['t1', 't2'])
+		expect(stacks.has('t3')).toBe(false)
+	})
+})

package/src/canvas/pin-stacking.ts

@@ -0,0 +1,57 @@
+import type { Editor, TLCommentThread } from 'tldraw'
+import { anchorPagePoint } from './thread-state'
+
+/** Two anchors within this page-space distance (per axis) share a stack. Identical imprecise
+ *  anchors on one shape resolve to the same point exactly; the tolerance only absorbs float noise. */
+const PIN_STACK_QUANTUM = 0.1
+
+/**
+ * The key a page point stacks under. Threads sharing a key are coincident. Stable identity for a
+ * stack itself: it survives losing any member (the survivors keep the same key), unlike keying by
+ * a particular thread id, so open-stack state stays put when the stack's oldest thread is deleted.
+ */
+export function pinStackKey(point: { x: number; y: number }): string {
+	return `${Math.round(point.x / PIN_STACK_QUANTUM)}:${Math.round(point.y / PIN_STACK_QUANTUM)}`
+}
+
+/**
+ * Group threads whose pins land on the same page point — coincident pins (typically several
+ * imprecise comments on one shape) that zooming can never separate. The overlay renders each
+ * group as a single count-badge pin that opens the threads as a list. Every member id maps to
+ * its group's ordered member ids (oldest first); threads without an entry pin individually.
+ *
+ * Keyed by page-space anchor point, not screen position, so the result only changes when threads
+ * or their anchors move — never on camera moves.
+ * @internal
+ */
+export function computePinStacks(
+	editor: Editor,
+	threads: readonly TLCommentThread[]
+): Map<string, readonly string[]> {
+	const pageId = editor.getCurrentPageId()
+	const groups = new Map<string, TLCommentThread[]>()
+
+	for (const thread of threads) {
+		if (thread.pageId !== pageId) continue
+		const point = anchorPagePoint(editor, thread.anchor)
+		if (!point) continue
+		const key = pinStackKey(point)
+		const group = groups.get(key)
+		if (group) {
+			group.push(thread)
+		} else {
+			groups.set(key, [thread])
+		}
+	}
+
+	const stacks = new Map<string, readonly string[]>()
+	for (const group of groups.values()) {
+		if (group.length < 2) continue
+		group.sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : 1))
+		const ids = group.map((thread) => thread.id)
+		for (const id of ids) {
+			stacks.set(id, ids)
+		}
+	}
+	return stacks
+}

package/src/canvas/sidebar-filters.ts

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

package/src/canvas/state.ts

@@ -1,13 +1,5 @@
-import {
-	EditorAtom,
-	type BoxModel,
-	type Editor,
-	type TLHistoryBatchOptions,
-	useEditor,
-	useValue,
-} from 'tldraw'
+import { EditorAtom, type BoxModel, type Editor, useEditor, useValue } from 'tldraw'
 import type { PendingComment } from './comment-tool'
-import { getCommentingOptions } from './options'
 import { DEFAULT_SIDEBAR_FILTERS, type SidebarFilters } from './sidebar-filters'
 
 /**
@@ -21,10 +13,77 @@ import { DEFAULT_SIDEBAR_FILTERS, type SidebarFilters } from './sidebar-filters'
  * @public */
 export const openThreadId = new EditorAtom<string | null>('openThreadId', () => null)
 
+/** The coincident-pin stack whose thread list is showing (keyed by its oldest member's thread
+ * id), or null. Editor state rather than component state: the stack pin remounts when its owning
+ * render path changes (e.g. a member thread opens), and the open list must survive that.
+ * @internal */
+export const openStackId = new EditorAtom<string | null>('openStackId', () => null)
+
 /** The comment currently being placed (composer open, not yet posted), or null.
- * @public */
+ * @internal */
 export const pendingComment = new EditorAtom<PendingComment | null>('pendingComment', () => null)
 
+/**
+ * A pending request to reveal a thread: a thread or comment id to open and bring into view, or
+ * null when none is pending. Written by {@link revealThread}; served and cleared by
+ * `CanvasComments`, which owns the wait for the records to sync in and the cluster-aware reveal.
+ * @internal
+ */
+export const revealThreadRequest = new EditorAtom<string | null>('revealThreadRequest', () => null)
+
+/**
+ * Open a thread and bring it into view, given a thread id or the id of any comment in it. Use it
+ * to jump to a thread from outside the canvas — a notification, a deep link, your own list.
+ *
+ * The request is served by `CanvasComments`, so it works before the records have arrived: the
+ * layer waits for them to sync in, switches pages if it needs to, unhides pins, zooms in far
+ * enough to split the thread out of any cluster it's folded into, and then opens it. That also
+ * means nothing happens if `CanvasComments` isn't mounted.
+ *
+ * To open a thread you already hold and skip the wait, see {@link focusThread}.
+ *
+ * @example
+ * ```ts
+ * revealThread(editor, new URLSearchParams(location.search).get('comment')!)
+ * ```
+ *
+ * @public
+ */
+export function revealThread(editor: Editor, threadOrCommentId: string): void {
+	revealThreadRequest.set(editor, threadOrCommentId)
+}
+
+/**
+ * The id passed to the most recent {@link revealThread} call that `CanvasComments` hasn't served
+ * yet, or null when there's nothing outstanding. A request also clears when `CanvasComments`
+ * unmounts, since nothing is left to serve it.
+ *
+ * This is a plain, untracked read. In React, use {@link useRevealThreadPending} — but reach for
+ * this one inside a timer or callback that needs the value as of *now* rather than as of the
+ * render it closed over.
+ *
+ * @public
+ */
+export function getRevealThreadPending(editor: Editor): string | null {
+	return revealThreadRequest.get(editor)
+}
+
+/**
+ * Reactive React hook for {@link getRevealThreadPending}.
+ *
+ * Use it to notice a reveal that never lands — most often a deep link to a comment that has since
+ * been deleted. Give it a grace period before you act: a request also sits here while its records
+ * are still syncing in, which is the normal case on a cold load. Re-check with
+ * {@link getRevealThreadPending} when the grace period elapses, since the request can clear inside
+ * it without this hook's value having caught up yet.
+ *
+ * @public
+ */
+export function useRevealThreadPending(): string | null {
+	const editor = useEditor()
+	return useValue('pending reveal thread', () => getRevealThreadPending(editor), [editor])
+}
+
 /** The region rectangle being dragged out right now (page coords), or null when not dragging. The
  *  comment tool writes it on each move; the overlay reads it to draw the live dashed box. */
 export const regionDraft = new EditorAtom<BoxModel | null>('regionDraft', () => null)
@@ -36,6 +95,15 @@ export const regionDraft = new EditorAtom<BoxModel | null>('regionDraft', () =>
  */
 export const commentsHidden = new EditorAtom<boolean>('commentsHidden', () => false)
 
+/**
+ * Whether the comments sidebar (the thread list) is open. Driven by an explicit control — a button
+ * next to Share on dotcom — rather than by which tool is active, so browsing threads is separate
+ * from placing them. The comment tool additionally closes it on enter, keeping placement
+ * canvas-focused.
+ * @public
+ */
+export const commentsSidebarOpen = new EditorAtom<boolean>('commentsSidebarOpen', () => false)
+
 /** Which threads the comments sidebar shows.
  * @public */
 export const sidebarFilters = new EditorAtom<SidebarFilters>(
@@ -49,6 +117,12 @@ export function toggleCommentsHidden(editor: Editor): void {
 	commentsHidden.update(editor, (hidden) => !hidden)
 }
 
+/** Open or close the comments sidebar for an editor.
+ * @public */
+export function toggleCommentsSidebar(editor: Editor): void {
+	commentsSidebarOpen.update(editor, (open) => !open)
+}
+
 /** React hook for the open thread id.
  * @public */
 export function useOpenThreadId(): string | null {
@@ -57,7 +131,7 @@ export function useOpenThreadId(): string | null {
 }
 
 /** React hook for the pending (being-placed) comment.
- * @public */
+ * @internal */
 export function usePendingComment(): PendingComment | null {
 	const editor = useEditor()
 	return useValue('pending comment', () => pendingComment.get(editor), [editor])
@@ -70,33 +144,16 @@ export function useCommentsHidden(): boolean {
 	return useValue('comments hidden', () => commentsHidden.get(editor), [editor])
 }
 
+/** React hook for whether the comments sidebar is open.
+ * @public */
+export function useCommentsSidebarOpen(): boolean {
+	const editor = useEditor()
+	return useValue('comments sidebar open', () => commentsSidebarOpen.get(editor), [editor])
+}
+
 /** React hook for the current sidebar filters.
  * @public */
 export function useSidebarFilters(): SidebarFilters {
 	const editor = useEditor()
 	return useValue('sidebar filters', () => sidebarFilters.get(editor), [editor])
 }
-
-/**
- * Commit a comment mutation with the configured undo/redo behavior. All comment writes go through
- * here so the {@link CommentingOptions.history} option (and {@link CommentingOptions.dragHistory}
- * for pin re-anchors) governs whether they land on the undo stack. Defaults to `'ignore'`.
- * @public
- */
-export function commitCommentMutation<T>(
-	editor: Editor,
-	fn: () => T,
-	kind: 'mutation' | 'drag' = 'mutation'
-): T {
-	const options = getCommentingOptions(editor)
-	const history: TLHistoryBatchOptions['history'] =
-		kind === 'drag' ? (options.dragHistory ?? options.history) : options.history
-	let result: T
-	editor.run(
-		() => {
-			result = fn()
-		},
-		{ history }
-	)
-	return result!
-}

package/src/canvas/thread-preview.test.ts

@@ -0,0 +1,91 @@
+import type { TLComment, TLCommentThread } from 'tldraw'
+import { describe, expect, it } from 'vitest'
+import { selectPreviewCards, sortThreadsForPreview } from './thread-preview'
+
+function thread(id: string, createdAt: number): TLCommentThread {
+	return {
+		id,
+		typeName: 'comment-thread',
+		pageId: 'page:one',
+		anchor: { type: 'point', x: 0, y: 0 },
+		createdBy: 'user:1',
+		createdAt,
+		resolved: null,
+		meta: {},
+	} as unknown as TLCommentThread
+}
+
+function comment(threadId: string): TLComment {
+	return { id: `comment:${threadId}`, typeName: 'comment', threadId } as unknown as TLComment
+}
+
+/** Stands in for the store lookup: only the named threads have their opening comment yet. */
+function arrived(...threadIds: string[]) {
+	return (t: TLCommentThread) => (threadIds.includes(t.id) ? comment(t.id) : undefined)
+}
+
+describe('sortThreadsForPreview', () => {
+	it('orders threads oldest first', () => {
+		const sorted = sortThreadsForPreview([thread('t2', 20), thread('t1', 10), thread('t3', 30)])
+		expect(sorted.map((t) => t.id)).toEqual(['t1', 't2', 't3'])
+	})
+
+	it('breaks creation-time ties by id, matching the stack ordering', () => {
+		const sorted = sortThreadsForPreview([thread('t3', 5), thread('t1', 5), thread('t2', 5)])
+		expect(sorted.map((t) => t.id)).toEqual(['t1', 't2', 't3'])
+	})
+
+	// A cluster hands over `node.members`, which the clustering table sorts by id — the preview has
+	// to re-sort rather than inherit that order, or a cluster would read newest-first at random.
+	it('reorders an id-sorted cluster membership by creation time', () => {
+		const sorted = sortThreadsForPreview([thread('t1', 300), thread('t2', 200), thread('t3', 100)])
+		expect(sorted.map((t) => t.id)).toEqual(['t3', 't2', 't1'])
+	})
+
+	it('does not mutate the input', () => {
+		const input = [thread('t2', 20), thread('t1', 10)]
+		sortThreadsForPreview(input)
+		expect(input.map((t) => t.id)).toEqual(['t2', 't1'])
+	})
+})
+
+describe('selectPreviewCards', () => {
+	it('pairs each thread with its opening comment', () => {
+		const threads = [thread('t1', 10), thread('t2', 20)]
+		const { cards, overflow } = selectPreviewCards(threads, arrived('t1', 't2'))
+		expect(cards.map((c) => [c.thread.id, c.first.id])).toEqual([
+			['t1', 'comment:t1'],
+			['t2', 'comment:t2'],
+		])
+		expect(overflow).toBe(0)
+	})
+
+	// A thread record can sync ahead of its first comment. It has nothing to show, and rendering it
+	// anyway would paint a blank card — or, for a single-pin preview, a blank panel.
+	it('drops threads whose opening comment has not arrived', () => {
+		const threads = [thread('t1', 10), thread('t2', 20), thread('t3', 30)]
+		const { cards } = selectPreviewCards(threads, arrived('t1', 't3'))
+		expect(cards.map((c) => c.thread.id)).toEqual(['t1', 't3'])
+	})
+
+	it('reports nothing to show when no comment has arrived', () => {
+		const { cards, overflow } = selectPreviewCards([thread('t1', 10)], arrived())
+		expect(cards).toEqual([])
+		expect(overflow).toBe(0)
+	})
+
+	it('caps the cards and counts the rest as overflow', () => {
+		const threads = ['t1', 't2', 't3', 't4'].map((id, i) => thread(id, i))
+		const { cards, overflow } = selectPreviewCards(threads, arrived('t1', 't2', 't3', 't4'), 2)
+		expect(cards.map((c) => c.thread.id)).toEqual(['t1', 't2'])
+		expect(overflow).toBe(2)
+	})
+
+	// "+N more" should promise N readable threads, so unarrived ones can't pad the count.
+	it('excludes unarrived threads from the overflow tally', () => {
+		const threads = ['t1', 't2', 't3', 't4'].map((id, i) => thread(id, i))
+		const { cards, overflow } = selectPreviewCards(threads, arrived('t1', 't2', 't3'), 2)
+		expect(cards.map((c) => c.thread.id)).toEqual(['t1', 't2'])
+		expect(overflow).toBe(1)
+	})
+})