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

package/src/canvas/comments-sidebar.tsx

@@ -1,14 +1,13 @@
-import { ReactNode, useCallback, useRef } from 'react'
-import { createPortal } from 'react-dom'
+import { ReactNode, useCallback } from 'react'
 import {
+	EditorPortal,
 	TLComment,
-	useContainer,
+	TLCommentThread,
 	useEditor,
-	usePassThroughMouseOverEvents,
 	useTranslation,
 	useValue,
 } from 'tldraw'
-import { CommentListItemProps, CommentsList } from '../ui/comments-list'
+import { CommentListItemProps, CommentListItemRenderProps, CommentsList } from '../ui/comments-list'
 import { UNKNOWN_COMMENT_AUTHOR } from './comment-render'
 import { CommentsFilterMenu } from './comments-filter-menu'
 import { CommentsVisibilityToggle } from './comments-visibility-toggle'
@@ -51,7 +50,6 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 	const resolveName = useCallback((id: string) => resolveAuthor(id)?.name, [resolveAuthor])
 	const editor = useEditor()
 	const options = useCommentingOptions()
-	const container = useContainer()
 	const commentingEnabled = useCommentingEnabled()
 	const msg = useTranslation()
 	const threads = useCommentThreads(editor)
@@ -139,8 +137,28 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 		if (thread) focusThread(editor, thread)
 	}
 
+	// The `ThreadRow` component slot overrides the built-in row. It gets the thread record alongside
+	// the summarized row, so host state on `thread.meta` is in reach without a second lookup. Indexed
+	// once rather than scanned per row — this runs for every row on every render of the panel.
+	const ThreadRow = options.components.ThreadRow
+	const renderItem = ThreadRow
+		? (() => {
+				// Keyed by plain string: a row's id comes back as one, not as a branded thread id.
+				const threadsById = new Map<string, TLCommentThread>(
+					threads.map((thread) => [thread.id, thread])
+				)
+				return (rowProps: CommentListItemRenderProps) => {
+					const thread = threadsById.get(rowProps.id)
+					// Can't happen — the items are built from these threads — but a row with no thread has
+					// nothing to render, and the slot's contract says the record is there.
+					if (!thread) return null
+					return <ThreadRow {...rowProps} thread={thread} />
+				}
+			})()
+		: undefined
+
 	return (
-		<SidebarPanel container={container}>
+		<SidebarPanel>
 			<CommentsList
 				items={items}
 				header={header ?? msg('comments.title')}
@@ -160,13 +178,14 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 				}
 				resolvedLabel={msg('comments.resolved')}
 				onSelect={focus}
+				renderItem={renderItem}
 			/>
 		</SidebarPanel>
 	)
 }
 
-/** A list row paired with the sort key that isn't part of what the row displays. */
-interface SidebarRow {
+/** A list row paired with the sort key that isn't part of what the row displays. @public */
+export interface SidebarRow {
 	item: CommentListItemProps
 	/** When the thread's most recent comment was posted — what the list orders by. */
 	lastActivity: number
@@ -177,6 +196,10 @@ interface SidebarRow {
  * Recency is the thread's *latest* comment, not its first, so a thread someone just replied to rises
  * to the top instead of staying wherever it was started. (The row still shows the thread's opening
  * comment and its date — that's what identifies the thread; only the ordering follows the replies.)
+ *
+ * Exported so a hand-built list can match the sidebar's ordering instead of re-deriving it.
+ *
+ * @public
  */
 export function sortSidebarRows(rows: readonly SidebarRow[]): readonly SidebarRow[] {
 	return [...rows].sort(
@@ -188,15 +211,13 @@ export function sortSidebarRows(rows: readonly SidebarRow[]): readonly SidebarRo
 }
 
 /** The sidebar surface, portaled into the container. It scrolls its own list, so — unlike tldraw's
- *  wheel-transparent panels — a wheel over it doesn't pan the canvas. Hover still passes through so
- *  shapes beneath it stay interactive. */
-function SidebarPanel({ container, children }: { container: HTMLElement; children: ReactNode }) {
-	const ref = useRef<HTMLDivElement>(null)
-	usePassThroughMouseOverEvents(ref)
-	return createPortal(
-		<div ref={ref} className="tlui-cmt-canvas-sidebar" onContextMenu={(e) => e.stopPropagation()}>
-			{children}
-		</div>,
-		container
+ *  wheel-transparent panels — a wheel over it doesn't pan the canvas. */
+function SidebarPanel({ children }: { children: ReactNode }) {
+	return (
+		<EditorPortal>
+			<div className="tlui-cmt-canvas-sidebar" onContextMenu={(e) => e.stopPropagation()}>
+				{children}
+			</div>
+		</EditorPortal>
 	)
 }

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

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

package/src/canvas/context.ts

@@ -30,10 +30,11 @@ export interface CommentingContext {
 	/** 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.
+	 * Called with every unread comment shown to the user in an open thread popover, batched per
+	 * report, so hosts can record read receipts without a write per comment. Needs
+	 * `isCommentUnread` to know what's unread.
 	 */
-	onCommentRead?(commentId: TLCommentId): void
+	onCommentsRead?(commentIds: 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. */

package/src/canvas/hooks.test.ts

@@ -0,0 +1,94 @@
+import {
+	commentSchemaRecords,
+	createComment,
+	createCommentThread,
+	createTLSchema,
+	createTLStore,
+	defaultBindingUtils,
+	defaultShapeUtils,
+	defaultTools,
+	Editor,
+	toRichText,
+} from 'tldraw'
+import { afterEach, describe, expect, it } from 'vitest'
+import { putCommentRecords } from './comment-mutations'
+import { getCommentsByThread } from './hooks'
+
+let editors: Editor[] = []
+
+afterEach(() => {
+	for (const editor of editors) editor.dispose()
+	editors = []
+})
+
+function makeEditor(): Editor {
+	const editor = new Editor({
+		store: createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
+		shapeUtils: defaultShapeUtils,
+		bindingUtils: defaultBindingUtils,
+		tools: defaultTools,
+		getContainer: () => document.body,
+	})
+	editors.push(editor)
+	return editor
+}
+
+function makeThreadWithComment(editor: Editor, text: string) {
+	const pageId = editor.getCurrentPageId()
+	const thread = createCommentThread({
+		pageId,
+		anchor: { type: 'point', x: 0, y: 0 },
+		createdBy: 'user1',
+	})
+	const comment = createComment({
+		threadId: thread.id,
+		pageId,
+		authorId: 'user1',
+		body: toRichText(text),
+	})
+	return { thread, comment }
+}
+
+describe('getCommentsByThread', () => {
+	it('groups live comments by thread, oldest first', () => {
+		const editor = makeEditor()
+		const { thread, comment } = makeThreadWithComment(editor, 'first')
+		const reply = createComment({
+			threadId: thread.id,
+			pageId: editor.getCurrentPageId(),
+			authorId: 'user2',
+			body: toRichText('second'),
+			now: comment.createdAt + 1,
+		})
+		// Inserted newest-first to prove the grouping sorts by createdAt rather than store order.
+		putCommentRecords(editor, [thread, reply, comment])
+		expect(getCommentsByThread(editor).get().get(thread.id)).toEqual([comment, reply])
+	})
+
+	it("reuses a thread's array when another thread's comments change", () => {
+		const editor = makeEditor()
+		const a = makeThreadWithComment(editor, 'thread a')
+		const b = makeThreadWithComment(editor, 'thread b')
+		putCommentRecords(editor, [a.thread, a.comment, b.thread, b.comment])
+
+		const byThread = getCommentsByThread(editor)
+		const before = byThread.get()
+
+		const replyToB = createComment({
+			threadId: b.thread.id,
+			pageId: editor.getCurrentPageId(),
+			authorId: 'user2',
+			body: toRichText('reply'),
+			now: b.comment.createdAt + 1,
+		})
+		putCommentRecords(editor, [replyToB])
+		const after = byThread.get()
+
+		expect(after).not.toBe(before)
+		// The unchanged thread keeps its exact array, so its subscribers don't re-render...
+		expect(after.get(a.thread.id)).toBe(before.get(a.thread.id))
+		// ...while the changed thread gets a fresh one with the reply in place.
+		expect(after.get(b.thread.id)).not.toBe(before.get(b.thread.id))
+		expect(after.get(b.thread.id)).toEqual([b.comment, replyToB])
+	})
+})

package/src/canvas/hooks.ts

@@ -2,6 +2,7 @@ import {
 	computed,
 	Computed,
 	Editor,
+	isUninitialized,
 	TLComment,
 	TLCommentThread,
 	TLCommentThreadId,
@@ -29,17 +30,30 @@ export function useCommentThreads(editor: Editor): TLCommentThread[] {
  */
 const commentsByThread = new WeakCache<Editor, Computed<Map<TLCommentThreadId, TLComment[]>>>()
 
-function getCommentsByThread(editor: Editor) {
+/** Exported for tests; use {@link useThreadComments} to consume. @internal */
+export function getCommentsByThread(editor: Editor) {
 	return commentsByThread.get(editor, () =>
-		computed('comments by thread', () => {
+		computed('comments by thread', (prev) => {
 			const byThread = new Map<TLCommentThreadId, TLComment[]>()
 			for (const comment of getLiveComments(editor)) {
 				const existing = byThread.get(comment.threadId)
 				if (existing) existing.push(comment)
 				else byThread.set(comment.threadId, [comment])
 			}
-			for (const comments of byThread.values()) {
+			for (const [threadId, comments] of byThread) {
 				comments.sort((a, b) => a.createdAt - b.createdAt)
+				// Reuse the previous per-thread array when that thread's comment list is unchanged
+				// (record identities are stable while unchanged), so `useThreadComments` subscribers
+				// on other threads don't re-render when one thread gains a reply.
+				if (isUninitialized(prev)) continue
+				const prevComments = prev.get(threadId)
+				if (
+					prevComments &&
+					prevComments.length === comments.length &&
+					comments.every((comment, i) => prevComments[i] === comment)
+				) {
+					byThread.set(threadId, prevComments)
+				}
 			}
 			return byThread
 		})

package/src/canvas/license.ts

@@ -7,7 +7,7 @@ import { useLicenseContext, useLicenseFeatureFlag } from 'tldraw'
  * pending, so gated UI stays hidden until the license is confirmed.
  *
  * The built-in commenting components (`CanvasComments`, `CanvasCommentsSidebar`, and the comment
- * tool's toolbar button) gate on this. Use it to gate any custom commenting UI the same way.
+ * tool's Quick Action) gate on this. Use it to gate any custom commenting UI the same way.
  * @public
  */
 export function useCommentingEnabled(): boolean {

package/src/canvas/mobile-placement.ts

@@ -0,0 +1,115 @@
+import { RefObject, useCallback, useLayoutEffect, useRef, useState } from 'react'
+import { PORTRAIT_BREAKPOINT, useBreakpoint, useContainer } from 'tldraw'
+import { getVisibleViewport } from '../ui/visual-viewport'
+
+/**
+ * Mobile mode for the commenting surfaces — the same breakpoint gate as tldraw's mobile toolbar and
+ * style panel (which also honors `forceMobile` on `<Tldraw>`). The commenting layer can mount
+ * without tldraw's default UI (`hideUi`, custom UI), where the breakpoint provider is absent and
+ * `useBreakpoint` throws; fall back to desktop there, matching the pre-mobile rendering those hosts
+ * always had.
+ */
+export function useIsMobileCommenting(): boolean {
+	let breakpoint: number
+	try {
+		// The call is unconditional — the try only guards the provider's absence, not hook order.
+		// oxlint-disable-next-line react-hooks/rules-of-hooks
+		breakpoint = useBreakpoint()
+	} catch {
+		return false
+	}
+	return breakpoint < PORTRAIT_BREAKPOINT.TABLET_SM
+}
+
+const VIEWPORT_MARGIN = 8
+
+/**
+ * Keep a canvas-anchored panel — the pending composer or an open thread popover — within the
+ * visible viewport on mobile. The software keyboard shrinks the *visual* viewport while leaving the
+ * layout viewport (and CSS `dvh`) untouched, so a panel placed at a fixed offset from its pin can
+ * end up behind the keyboard. On mobile this clamps the panel's top-left into the visible box so it
+ * stays on-screen above the keyboard. Desktop is untouched: when `enabled` is false the base point
+ * is returned unchanged, tracking the camera exactly as before.
+ *
+ * `base` is the panel's desired top-left in container-relative viewport coordinates (what the call
+ * site would otherwise write straight into `left`/`top`).
+ */
+export function useMobilePlacement(
+	ref: RefObject<HTMLElement | null>,
+	base: { x: number; y: number },
+	enabled: boolean
+): { left: number; top: number } {
+	const container = useContainer()
+	// Destructured so the effects below depend on the two numbers rather than the object, which the
+	// call sites build fresh on every render.
+	const { x: baseX, y: baseY } = base
+	const [placed, setPlaced] = useState<{ left: number; top: number }>(() => ({
+		left: baseX,
+		top: baseY,
+	}))
+	// The camera moves `base` every frame while panning. Reading it from a ref keeps `update` stable
+	// across those frames, so the observers below are set up once per panel rather than being torn
+	// down and rebuilt each frame.
+	const baseRef = useRef({ x: baseX, y: baseY })
+
+	const update = useCallback(() => {
+		if (!enabled) return
+		const el = ref.current
+		if (!el) return
+		const win = container.ownerDocument.defaultView ?? window
+		const { x, y } = baseRef.current
+
+		// Panel coordinates are container-relative; the visual viewport is window-relative.
+		const cRect = container.getBoundingClientRect()
+		const vp = getVisibleViewport(win)
+		const top = vp.top - cRect.top + VIEWPORT_MARGIN
+		const bottom = vp.bottom - cRect.top - VIEWPORT_MARGIN
+		const left = vp.left - cRect.left + VIEWPORT_MARGIN
+		const right = vp.right - cRect.left - VIEWPORT_MARGIN
+
+		const w = el.offsetWidth
+		const h = el.offsetHeight
+
+		const nextLeft = Math.max(left, Math.min(x, right - w))
+		// The keyboard only ever covers space from the bottom, so it can pull the panel up (when its
+		// bottom would be hidden) but must never push it down below its natural spot. `y` is the
+		// floor: any spurious rise in `top` (e.g. iOS scrolling the page to reveal a focused input)
+		// is capped here, so a panel that already clears the keyboard doesn't move at all.
+		const nextTop = Math.min(y, Math.max(top, bottom - h))
+		setPlaced((prev) =>
+			prev.left === nextLeft && prev.top === nextTop ? prev : { left: nextLeft, top: nextTop }
+		)
+	}, [container, ref, enabled])
+
+	// Re-place as the camera moves the panel's base point.
+	useLayoutEffect(() => {
+		baseRef.current = { x: baseX, y: baseY }
+		update()
+	}, [baseX, baseY, update])
+
+	// Re-place when the panel grows (replies, edits), when the visual viewport changes (keyboard,
+	// pinch-zoom), or when the window resizes.
+	useLayoutEffect(() => {
+		if (!enabled) return
+		const el = ref.current
+		if (!el) return
+		const win = container.ownerDocument.defaultView ?? window
+		const ro = new ResizeObserver(update)
+		ro.observe(el)
+		const vv = win.visualViewport
+		vv?.addEventListener('resize', update)
+		vv?.addEventListener('scroll', update)
+		win.addEventListener('resize', update)
+		return () => {
+			ro.disconnect()
+			vv?.removeEventListener('resize', update)
+			vv?.removeEventListener('scroll', update)
+			win.removeEventListener('resize', update)
+		}
+	}, [container, ref, enabled, update])
+
+	// Desktop keeps its fixed placement, recomputed each render so it tracks the pin as the camera
+	// moves.
+	if (!enabled) return { left: baseX, top: baseY }
+	return placed
+}

package/src/canvas/options.test.ts

@@ -1,12 +1,15 @@
-import type { Editor } from 'tldraw'
-import { describe, expect, it } from 'vitest'
+import { createComment, createCommentThread, toRichText, type Editor, type TLPageId } from 'tldraw'
+import { describe, expect, it, vi } from 'vitest'
 import { commitCommentMutation } from './comment-mutations'
 import { CommentTool } from './comment-tool'
 import {
+	defaultCanModifyComment,
 	defaultCommentingOptions,
 	getCanComment,
+	getCanModifyComment,
 	getCommentingOptions,
 	type CommentingOptions,
+	type CommentModificationContext,
 } from './options'
 import { openThreadId, pendingComment } from './state'
 
@@ -126,6 +129,125 @@ describe('getCanComment', () => {
 		const { editor } = stubEditor({ ...defaultCommentingOptions, canComment: () => true })
 		expect(getCanComment(editor, null)).toBe(true)
 	})
+
+	// This is read during render, so a throwing host rule would take the comments layer with it.
+	it('denies rather than throws when the callback throws', () => {
+		const onError = vi.spyOn(console, 'error').mockImplementation(() => {})
+		const { editor } = stubEditor({
+			...defaultCommentingOptions,
+			canComment: () => {
+				throw new Error('lookup failed')
+			},
+		})
+		expect(getCanComment(editor, 'alice')).toBe(false)
+		expect(onError).toHaveBeenCalled()
+		onError.mockRestore()
+	})
+})
+
+// Plain records for the permission checks — the factories are pure, so no store is involved.
+const PAGE_ID = 'page:test' as TLPageId
+
+function makeThread(createdBy: string) {
+	return createCommentThread({
+		pageId: PAGE_ID,
+		anchor: { type: 'point', x: 0, y: 0 },
+		createdBy,
+	})
+}
+
+function makeComment(authorId: string) {
+	return createComment({
+		threadId: makeThread(authorId).id,
+		pageId: PAGE_ID,
+		authorId,
+		body: toRichText('hello'),
+	})
+}
+
+describe('getCanModifyComment', () => {
+	it('defaults to the record owner: the comment author edits and deletes', () => {
+		const { editor } = stubEditor(defaultCommentingOptions)
+		const comment = makeComment('alice')
+		expect(getCanModifyComment(editor, 'alice', { action: 'edit-comment', comment })).toBe(true)
+		expect(getCanModifyComment(editor, 'alice', { action: 'delete-comment', comment })).toBe(true)
+		expect(getCanModifyComment(editor, 'bob', { action: 'edit-comment', comment })).toBe(false)
+		expect(getCanModifyComment(editor, 'bob', { action: 'delete-comment', comment })).toBe(false)
+	})
+
+	it('defaults to the thread creator for a thread delete', () => {
+		const { editor } = stubEditor(defaultCommentingOptions)
+		const thread = makeThread('alice')
+		expect(getCanModifyComment(editor, 'alice', { action: 'delete-thread', thread })).toBe(true)
+		expect(getCanModifyComment(editor, 'bob', { action: 'delete-thread', thread })).toBe(false)
+	})
+
+	it('withholds everything from a viewer with no identity', () => {
+		const { editor } = stubEditor(defaultCommentingOptions)
+		const comment = makeComment('alice')
+		const thread = makeThread('alice')
+		expect(getCanModifyComment(editor, null, { action: 'edit-comment', comment })).toBe(false)
+		expect(getCanModifyComment(editor, undefined, { action: 'delete-comment', comment })).toBe(
+			false
+		)
+		expect(getCanModifyComment(editor, null, { action: 'delete-thread', thread })).toBe(false)
+	})
+
+	it('passes the editor, the viewer, and the targeted write to the callback', () => {
+		const calls: CommentModificationContext[] = []
+		const { editor } = stubEditor({
+			...defaultCommentingOptions,
+			canModifyComment: (ctx) => {
+				calls.push(ctx)
+				return true
+			},
+		})
+		const comment = makeComment('alice')
+		getCanModifyComment(editor, undefined, { action: 'delete-comment', comment })
+		// An undefined viewer normalizes to null, as it does for `canComment`.
+		expect(calls).toEqual([{ editor, currentUserId: null, action: 'delete-comment', comment }])
+	})
+
+	it("lets a callback widen the default: a moderator deleting anyone's comment", () => {
+		const { editor } = stubEditor({
+			...defaultCommentingOptions,
+			canModifyComment: (ctx) =>
+				(ctx.action !== 'edit-comment' && ctx.currentUserId === 'mod') ||
+				defaultCanModifyComment(ctx),
+		})
+		const comment = makeComment('alice')
+		const thread = makeThread('alice')
+		expect(getCanModifyComment(editor, 'mod', { action: 'delete-comment', comment })).toBe(true)
+		expect(getCanModifyComment(editor, 'mod', { action: 'delete-thread', thread })).toBe(true)
+		// Widening deletion doesn't hand the moderator anyone else's edit affordance.
+		expect(getCanModifyComment(editor, 'mod', { action: 'edit-comment', comment })).toBe(false)
+		// The author keeps their own affordances.
+		expect(getCanModifyComment(editor, 'alice', { action: 'edit-comment', comment })).toBe(true)
+		// Everyone else still gets nothing.
+		expect(getCanModifyComment(editor, 'bob', { action: 'delete-comment', comment })).toBe(false)
+	})
+
+	it('lets a callback narrow the default', () => {
+		const { editor } = stubEditor({ ...defaultCommentingOptions, canModifyComment: () => false })
+		const comment = makeComment('alice')
+		expect(getCanModifyComment(editor, 'alice', { action: 'edit-comment', comment })).toBe(false)
+	})
+
+	// A throw withholds the affordance rather than the whole layer, and never offers a write a
+	// server enforcing the same rule would reject anyway.
+	it('denies rather than throws when the callback throws', () => {
+		const onError = vi.spyOn(console, 'error').mockImplementation(() => {})
+		const { editor } = stubEditor({
+			...defaultCommentingOptions,
+			canModifyComment: () => {
+				throw new Error('lookup failed')
+			},
+		})
+		const comment = makeComment('alice')
+		expect(getCanModifyComment(editor, 'alice', { action: 'edit-comment', comment })).toBe(false)
+		expect(onError).toHaveBeenCalled()
+		onError.mockRestore()
+	})
 })
 
 describe('commitCommentMutation', () => {