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

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,8 +1,17 @@
-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 { defaultCommentingOptions, getCommentingOptions, type CommentingOptions } from './options'
-import { commitCommentMutation, openThreadId, pendingComment } from './state'
+import {
+	defaultCanModifyComment,
+	defaultCommentingOptions,
+	getCanComment,
+	getCanModifyComment,
+	getCommentingOptions,
+	type CommentingOptions,
+	type CommentModificationContext,
+} from './options'
+import { openThreadId, pendingComment } from './state'
 
 // The StateNode constructor doesn't call any editor methods, so a bare stub is enough to
 // instantiate a configured tool and read its merged options.
@@ -78,6 +87,169 @@ describe('getCommentingOptions', () => {
 	})
 })
 
+describe('getCanComment', () => {
+	it('defaults to requiring a current user', () => {
+		const { editor } = stubEditor(defaultCommentingOptions)
+		expect(getCanComment(editor, 'alice')).toBe(true)
+		expect(getCanComment(editor, null)).toBe(false)
+		expect(getCanComment(editor, undefined)).toBe(false)
+	})
+
+	it('normalizes an undefined viewer to null for the callback', () => {
+		const calls: Array<string | null> = []
+		const { editor } = stubEditor({
+			...defaultCommentingOptions,
+			canComment: (ctx) => {
+				calls.push(ctx.currentUserId)
+				return false
+			},
+		})
+		getCanComment(editor, undefined)
+		expect(calls).toEqual([null])
+	})
+
+	it('delegates to the canComment callback, passing the editor and viewer', () => {
+		const calls: Array<{ editor: Editor; currentUserId: string | null }> = []
+		const { editor } = stubEditor({
+			...defaultCommentingOptions,
+			canComment: (ctx) => {
+				calls.push(ctx)
+				return ctx.currentUserId === 'alice'
+			},
+		})
+		expect(getCanComment(editor, 'alice')).toBe(true)
+		expect(getCanComment(editor, 'bob')).toBe(false)
+		expect(calls).toEqual([
+			{ editor, currentUserId: 'alice' },
+			{ editor, currentUserId: 'bob' },
+		])
+	})
+
+	it('lets the callback fully replace the signed-in default', () => {
+		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', () => {
 	it('uses options.history for a mutation and returns the callback result', () => {
 		const { editor, runCalls } = stubEditor({

package/src/canvas/options.ts

@@ -4,8 +4,52 @@ import {
 	type TLComment,
 	type TLCommentThread,
 	type TLHistoryBatchOptions,
+	type TLShapeId,
+	type VecLike,
 	useEditor,
+	useValue,
 } from 'tldraw'
+import { type CommentListItemRenderProps } from '../ui/comments-list'
+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
+}
+
+/**
+ * A commenting write that belongs to someone in particular, and the record it targets — the
+ * argument to {@link CommentingOptions.canModifyComment}.
+ *
+ * Resolving, reopening, reacting, and moving a pin aren't here: none of them is anyone's in
+ * particular, so {@link CommentingOptions.canComment} is the only gate on them.
+ *
+ * @public
+ */
+export type CommentModification =
+	| { readonly action: 'edit-comment'; readonly comment: TLComment }
+	| { readonly action: 'delete-comment'; readonly comment: TLComment }
+	| { readonly action: 'delete-thread'; readonly thread: TLCommentThread }
+
+/**
+ * The argument to {@link CommentingOptions.canModifyComment}: which write, against which record,
+ * and by whom.
+ *
+ * @public
+ */
+export type CommentModificationContext = {
+	readonly editor: Editor
+	readonly currentUserId: string | null
+} & CommentModification
 
 /**
  * Component overrides for the batteries-included comments layer. Each slot replaces a built-in
@@ -20,12 +64,50 @@ export interface CommentingComponents {
 	PinContent?: ComponentType<{ thread: TLCommentThread; comments: TLComment[] }>
 	/** A sidebar row's preview. Replaces the plaintext default. */
 	ThreadPreview?: ComponentType<{ comment: TLComment }>
+	/**
+	 * A whole sidebar row. Replaces the default `<CommentListItem>`, which is exported — so a row
+	 * that only adds an unread dot or a status chip can spread these props into it. Use
+	 * `ThreadPreview` instead when only the preview text is changing.
+	 */
+	ThreadRow?: ComponentType<CommentListItemRenderProps & { thread: TLCommentThread }>
+	/**
+	 * Extra controls in an open thread's header, added ahead of the built-in resolve and dismiss
+	 * buttons rather than replacing them. "Copy link" is already built in whenever the host supplies
+	 * `getThreadHref`.
+	 */
+	ThreadActions?: ComponentType<{ thread: TLCommentThread; comments: TLComment[] }>
+	/**
+	 * A reaction's visual, given its token. The default renders the token string for the OS emoji
+	 * font. Override to draw a custom palette — an `<img>`, an SVG, anything. The token is what gets
+	 * stored and synced; this only controls how it's drawn.
+	 */
+	ReactionContent?: ComponentType<{ token: string }>
+	/**
+	 * What the add-reaction button opens. Replaces the default `<EmojiPicker>` grid. Pairs with
+	 * `ReactionContent` (which draws the tokens this emits) and `isAllowedReaction` (which must
+	 * accept them).
+	 */
+	ReactionPalette?: ComponentType<EmojiPickerProps>
+	/**
+	 * The hover affordance naming who reacted with an emoji. Receives the reactors and the pill (as
+	 * `children`) and owns the whole thing — box, size, shape, position. For a wording change,
+	 * translate the `comments.reacted-*` strings instead.
+	 */
+	ReactionTooltip?: ComponentType<ReactionTooltipProps>
+	/**
+	 * Shown where a composer would sit when the viewer can't compose (see
+	 * {@link CommentingOptions.canComment}). `context` is the surface rendering it: an open thread
+	 * popover (`'thread'`) or the comment tool's placement popover (`'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}.
  *
@@ -37,13 +119,11 @@ export interface CommentingComponents {
  * @public
  */
 export interface CommentingOptions {
-	// ── History / undo ───────────────────────────────────────────────────────────────────────
+	// History / undo
 	/**
-	 * How comment mutations (post, reply, edit, resolve, delete) interact with the editor undo
-	 * stack. Defaults to `'ignore'` — comments are deliberately not undoable (see `TLComment`).
-	 * `'record'` is a multiplayer footgun: undoing a delete resurrects a thread a collaborator
-	 * already removed, and undoing a resolve/edit reverts their newer state. Safe only single-player
-	 * or on a non-synced local comment store.
+	 * How comment mutations interact with the editor undo stack. Defaults to `'ignore'` — comments
+	 * are deliberately not undoable (see `TLComment`). `'record'` is a multiplayer footgun: undoing
+	 * a delete resurrects a thread a collaborator already removed. Safe only single-player.
 	 */
 	readonly history: TLHistoryBatchOptions['history']
 	/**
@@ -52,21 +132,83 @@ export interface CommentingOptions {
 	 */
 	readonly dragHistory: TLHistoryBatchOptions['history'] | undefined
 
-	// ── Feature toggles ──────────────────────────────────────────────────────────────────────
+	// 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}, which
+	 * keeps a scripted client from writing junk values the picker would never offer. Override
+	 * alongside a custom `ReactionPalette`. Removals aren't checked — an off-palette reaction 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, drawn as a dashed box with the pin on the corner the drag released on. Off
+	 * by default, where comments attach to points and shapes only and a drag trails the composer.
+	 */
+	readonly enableRegions: boolean
+
+	// Permissions
+	/**
+	 * Whether the viewer may participate in commenting: composing, editing, deleting, resolving, and
+	 * moving pins. When false, {@link CommentingComponents.ComposerFallback} renders in the
+	 * composer's place and action affordances are hidden. Unset, participation is allowed exactly
+	 * when `currentUserId` is set.
+	 *
+	 * Called during render via {@link useCanComment}, so signal reads are tracked. Posting still
+	 * needs a `currentUserId`, so returning true for a signed-out viewer yields a composer whose
+	 * send button stays disabled. A callback that throws is logged and read as false, rather than
+	 * taking the comments layer down with it.
+	 */
+	readonly canComment:
+		| ((ctx: { editor: Editor; currentUserId: string | null }) => boolean)
+		| undefined
+	/**
+	 * Whether the viewer may make a particular write against a particular record: editing or
+	 * deleting a comment, or deleting a thread. Unset, each is its record's owner's to make
+	 * ({@link defaultCanModifyComment}) — you edit and delete your own comments, and delete threads
+	 * you started. Override it to widen that (a workspace admin or moderator who may remove
+	 * anyone's comment) or to narrow it (no edits after an hour). Where it returns false the
+	 * affordance isn't rendered.
+	 *
+	 * Checked after {@link CommentingOptions.canComment}, which gates commenting as a whole: a
+	 * viewer who may not participate gets no action affordances at all, whatever this returns.
+	 *
+	 * Called during render via {@link useCanModifyComment}, so reactive reads (signals) are tracked.
+	 * A callback that throws is logged and read as false: an affordance is withheld rather than the
+	 * comments layer lost, and a denial is what a server enforcing the same rule would have said.
+	 *
+	 * @example
+	 * ```tsx
+	 * CommentTool.configure({
+	 * 	canModifyComment: (ctx) =>
+	 * 		// Moderators may delete anything; everything else stays the owner's to do.
+	 * 		(ctx.action !== 'edit-comment' && isModerator(ctx.currentUserId)) ||
+	 * 		defaultCanModifyComment(ctx),
+	 * })
+	 * ```
+	 */
+	readonly canModifyComment: ((ctx: CommentModificationContext) => boolean) | undefined
 
-	// ── Anchoring ────────────────────────────────────────────────────────────────────────────
+	// Anchoring
 	/** Normalized (0–1) spot within a shape where imprecise shape pins sit. Default top-right. */
 	readonly impreciseShapeAnchor: { readonly x: number; readonly y: number }
+	/**
+	 * Whether a comment landing on a shape pins to the exact clicked spot, or to the shape as a
+	 * whole (rendered at `impreciseShapeAnchor`). Always precise by default; return `false`, or
+	 * decide from the context. Governs new placements only — existing anchors render as stored.
+	 */
+	shouldBePrecise(editor: Editor, context: ShapeCommentPrecisionContext): boolean
 
-	// ── Clustering tuning ─────────────────────────────────────────────────────────────────────
-	/** Screen-pixel margin by which the viewport is inflated when culling cluster badges. */
-	readonly clusterCullMargin: number
-	/** How far past a cluster's split zoom to land when expanding it (1.05 = 5% overshoot). */
-	readonly clusterSplitZoomFactor: number
-
-	// ── Components ────────────────────────────────────────────────────────────────────────────
+	// Components
 	/** Component overrides. See {@link CommentingComponents}. */
 	readonly components: CommentingComponents
 }
@@ -80,9 +222,13 @@ export const defaultCommentingOptions = {
 	history: 'ignore',
 	dragHistory: undefined,
 	enableClustering: true,
+	allowMultipleReactions: true,
+	isAllowedReaction: isAllowedReactionEmoji,
+	enableRegions: false,
+	canComment: undefined,
+	canModifyComment: undefined,
 	impreciseShapeAnchor: { x: 1, y: 0 },
-	clusterCullMargin: 120,
-	clusterSplitZoomFactor: 1.05,
+	shouldBePrecise: () => true,
 	components: {},
 } as const satisfies CommentingOptions
 
@@ -109,3 +255,115 @@ export function useCommentingOptions(): CommentingOptions {
 	const editor = useEditor()
 	return useMemo(() => getCommentingOptions(editor), [editor])
 }
+
+/**
+ * Ask a host's permission callback, denying the write if it throws.
+ *
+ * These are called during render, so an exception in one would take the comments layer down with
+ * the answer. Denying costs an affordance, which is what a `false` would have cost anyway, and it
+ * can't offer a write a server enforcing the same rule would then reject.
+ */
+function permits(option: string, check: () => boolean): boolean {
+	try {
+		return check()
+	} catch (error) {
+		console.error(`[tldraw] \`${option}\` threw, so the write is denied:`, error)
+		return false
+	}
+}
+
+/**
+ * Whether the viewer may participate in commenting, per {@link CommentingOptions.canComment}
+ * (defaulting to `currentUserId != null` when unset). A callback that throws denies.
+ *
+ * This is a plain, untracked read — in React, use {@link useCanComment} instead.
+ *
+ * @public
+ */
+export function getCanComment(editor: Editor, currentUserId: string | null | undefined): boolean {
+	const { canComment } = getCommentingOptions(editor)
+	if (!canComment) return currentUserId != null
+	return permits('canComment', () => canComment({ editor, currentUserId: 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,
+	])
+}
+
+/**
+ * The default {@link CommentingOptions.canModifyComment}: a write is its record's owner's to make —
+ * a comment's author edits and deletes it, a thread's creator deletes the thread — and a viewer
+ * with no identity may make none of them.
+ *
+ * Exported so a callback can widen the default rather than restate it:
+ * `(ctx) => isModerator(ctx.currentUserId) || defaultCanModifyComment(ctx)`.
+ *
+ * @public
+ */
+export function defaultCanModifyComment(ctx: CommentModificationContext): boolean {
+	const { currentUserId } = ctx
+	if (!currentUserId) return false
+	const owner = ctx.action === 'delete-thread' ? ctx.thread.createdBy : ctx.comment.authorId
+	return owner === currentUserId
+}
+
+/**
+ * Whether the viewer may make a given write against a given record, per
+ * {@link CommentingOptions.canModifyComment} (defaulting to {@link defaultCanModifyComment} when
+ * unset). Where this is false the affordance isn't rendered.
+ *
+ * This is the per-record rule alone: the built-in UI additionally requires
+ * {@link CommentingOptions.canComment}, since a viewer who may not participate gets no action
+ * affordances at all.
+ *
+ * A plain, untracked read — a `canModifyComment` callback that reads signals is not observed. In
+ * React, use {@link useCanModifyComment} instead.
+ *
+ * @public
+ */
+export function getCanModifyComment(
+	editor: Editor,
+	currentUserId: string | null | undefined,
+	modification: CommentModification
+): boolean {
+	const { canModifyComment } = getCommentingOptions(editor)
+	const ctx: CommentModificationContext = {
+		editor,
+		currentUserId: currentUserId ?? null,
+		...modification,
+	}
+	if (!canModifyComment) return defaultCanModifyComment(ctx)
+	return permits('canModifyComment', () => canModifyComment(ctx))
+}
+
+/**
+ * Reactive React hook for {@link getCanModifyComment}: a `canModifyComment` callback that reads
+ * signals re-evaluates when they change.
+ *
+ * @public
+ */
+export function useCanModifyComment(
+	currentUserId: string | null | undefined,
+	modification: CommentModification
+): boolean {
+	const editor = useEditor()
+	// Comment records are immutable, so the record itself is what changes when the thing being
+	// checked changes — `modification` is a fresh object on every render and can't be a dep.
+	const record =
+		modification.action === 'delete-thread' ? modification.thread : modification.comment
+	return useValue(
+		'can modify comment',
+		() => getCanModifyComment(editor, currentUserId, modification),
+		[editor, currentUserId, modification.action, record]
+	)
+}