@tldraw/commenting 0.0.0-bootstrap

package/src/canvas/comments-sidebar.tsx

@@ -0,0 +1,184 @@
+import { ReactNode, useRef } from 'react'
+import { createPortal } from 'react-dom'
+import {
+	TLComment,
+	TLCommentId,
+	useContainer,
+	useEditor,
+	usePassThroughMouseOverEvents,
+	useTranslation,
+	useValue,
+} from 'tldraw'
+import { CommentListItemProps, CommentsList } from '../ui/comments-list'
+import { UNKNOWN_AUTHOR } from './comment-render'
+import { CommentsFilterMenu } from './comments-filter-menu'
+import { CommentsOverflowMenu } from './comments-overflow-menu'
+import { useComments, useCommentThreads } from './hooks'
+import { useCommentingEnabled } from './license'
+import { useCommentingOptions } from './options'
+import { richTextToPlaintext } from './rich-text'
+import { openThreadId, sidebarFilters } from './state'
+import { focusThread } from './thread-state'
+
+/** @public */
+export interface CanvasCommentsSidebarProps {
+	/** Map an author id to a display name, or `undefined` when the id can't be named. */
+	resolveName(id: string): string | undefined
+	/** The signed-in user's id. Enables the "only your threads" filter when present. */
+	currentUserId?: string
+	/**
+	 * Whether a comment is unread for the current user (return true for unread). Enables the
+	 * "only unread" filter when present.
+	 */
+	isCommentUnread?(commentId: TLCommentId): boolean
+	/** Tool ids that show the sidebar. Defaults to the comment tool. */
+	tools?: string[]
+	/** Header above the list. */
+	header?: ReactNode
+	/** Shown when the page has no threads. */
+	empty?: ReactNode
+	/** Where imprecise shape pins sit, so navigation centres on the same spot. Default top-right. */
+	impreciseShapeAnchor?: { x: number; y: number }
+}
+
+/**
+ * A comments list panel for the current page, shown while the comment tool is active. Clicking a
+ * thread brings its pin into view and opens it. Batteries-included over the store (a sibling to
+ * `CanvasComments`); `CommentsList` is exported for a differently-placed or always-on list.
+ * @public @react
+ */
+export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
+	const {
+		resolveName,
+		currentUserId,
+		isCommentUnread,
+		tools,
+		header,
+		empty,
+		impreciseShapeAnchor,
+	} = props
+	const editor = useEditor()
+	const options = useCommentingOptions()
+	const sidebarTools = tools ?? ['comment']
+	const container = useContainer()
+	const commentingEnabled = useCommentingEnabled()
+	const msg = useTranslation()
+	const threads = useCommentThreads(editor)
+	const comments = useComments(editor)
+	const currentPageId = useValue('page id', () => editor.getCurrentPageId(), [editor])
+	const activeTool = useValue('tool id', () => editor.getCurrentToolId(), [editor])
+	const openId = useValue('open thread', () => openThreadId.get(editor), [editor])
+	const filters = useValue('sidebar filters', () => sidebarFilters.get(editor), [editor])
+	const pageNames = useValue(
+		'page names',
+		() => new Map(editor.getPages().map((page) => [page.id, page.name])),
+		[editor]
+	)
+
+	if (!commentingEnabled || !sidebarTools.includes(activeTool)) return null
+
+	// Group comments by thread (they arrive oldest-first, so [0] is each thread's first comment).
+	const byThread = new Map<string, TLComment[]>()
+	for (const comment of comments) {
+		const list = byThread.get(comment.threadId) ?? []
+		list.push(comment)
+		byThread.set(comment.threadId, list)
+	}
+
+	// Page scoping is treated as scoping, not a filter: an empty page reads "no comments yet",
+	// while a list emptied by the toggles below reads "nothing matches your filters".
+	const pageThreads = threads.filter(
+		(thread) => !filters.onlyCurrentPage || thread.pageId === currentPageId
+	)
+
+	const items: CommentListItemProps[] = pageThreads
+		.filter((thread) => filters.showResolved || thread.resolved == null)
+		// "Only mine" is ignored without a known user — otherwise a persisted onlyMine=true would
+		// empty the list for a signed-out viewer, with the (hidden) toggle giving no way to clear it.
+		.filter(
+			(thread) =>
+				!filters.onlyMine || currentUserId === undefined || thread.createdBy === currentUserId
+		)
+		// "Only unread" is likewise ignored without a read-status source.
+		.filter(
+			(thread) =>
+				!filters.onlyUnread ||
+				isCommentUnread === undefined ||
+				(byThread.get(thread.id) ?? []).some((c) => isCommentUnread(c.id))
+		)
+		.map((thread) => {
+			const threadComments = byThread.get(thread.id) ?? []
+			const first = threadComments[0]
+			let preview: ReactNode = ''
+			// The `ThreadPreview` component slot overrides the built-in plaintext default.
+			const ThreadPreview = options.components.ThreadPreview
+			if (first) {
+				preview = ThreadPreview ? (
+					<ThreadPreview comment={first} />
+				) : (
+					richTextToPlaintext(first.body, resolveName)
+				)
+			}
+			return {
+				id: thread.id,
+				author: resolveName(thread.createdBy) ?? UNKNOWN_AUTHOR,
+				preview,
+				date: new Date((first ?? thread).createdAt).toISOString(),
+				resolved: thread.resolved != null,
+				page: pageNames.get(thread.pageId),
+				count: threadComments.length,
+				selected: openId === thread.id,
+			}
+		})
+		// unresolved first, then most-recent first
+		.sort((a, b) => {
+			if (!!a.resolved !== !!b.resolved) return a.resolved ? 1 : -1
+			return b.date.localeCompare(a.date)
+		})
+
+	const focus = (id: string) => {
+		const thread = threads.find((t) => t.id === id)
+		// Resolve prop-or-option like the overlay pins do, so sidebar navigation centers on the same
+		// spot the pin renders at when the anchor is configured via `CommentTool.configure`.
+		if (thread) focusThread(editor, thread, impreciseShapeAnchor ?? options.impreciseShapeAnchor)
+	}
+
+	return (
+		<SidebarPanel container={container}>
+			<CommentsList
+				items={items}
+				header={header ?? msg('comments.title')}
+				headerAction={
+					<div className="cmt-list__header-actions">
+						<CommentsFilterMenu
+							canFilterByAuthor={currentUserId !== undefined}
+							canFilterByUnread={isCommentUnread !== undefined}
+						/>
+						<CommentsOverflowMenu />
+					</div>
+				}
+				empty={
+					items.length === 0 && pageThreads.length > 0
+						? msg('comments.empty-filtered')
+						: (empty ?? msg('comments.empty'))
+				}
+				resolvedLabel={msg('comments.resolved')}
+				onSelect={focus}
+			/>
+		</SidebarPanel>
+	)
+}
+
+/** 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="cmt-canvas-sidebar">
+			{children}
+		</div>,
+		container
+	)
+}

package/src/canvas/hooks.ts

@@ -0,0 +1,28 @@
+import { Editor, TLComment, TLCommentThread, TLCommentThreadId, useValue } from 'tldraw'
+import { getComments, getCommentThreads } from './comment-store'
+
+/** All comment threads in the store, reactively. @public */
+export function useCommentThreads(editor: Editor): TLCommentThread[] {
+	return useValue('comment threads', () => getCommentThreads(editor), [editor])
+}
+
+/** A thread's comments, oldest first, reactively. @public */
+export function useThreadComments(editor: Editor, threadId: TLCommentThreadId): TLComment[] {
+	return useValue(
+		'thread comments',
+		() =>
+			getComments(editor)
+				.filter((c) => c.threadId === threadId)
+				.sort((a, b) => a.createdAt - b.createdAt),
+		[editor, threadId]
+	)
+}
+
+/** Every comment in the store, oldest first, reactively. Group by `threadId` for per-thread lists. @public */
+export function useComments(editor: Editor): TLComment[] {
+	return useValue(
+		'all comments',
+		() => getComments(editor).sort((a, b) => a.createdAt - b.createdAt),
+		[editor]
+	)
+}

package/src/canvas/license.ts

@@ -0,0 +1,15 @@
+import { useLicenseContext, useLicenseFeatureFlag } from 'tldraw'
+
+/**
+ * Whether commenting is licensed for this editor. Enabled in development; in production it requires
+ * a tldraw license that includes the commenting feature (or the collaboration umbrella that grants
+ * it). Reactive: re-reads when license validation resolves, and returns `false` while validation is
+ * 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.
+ * @public
+ */
+export function useCommentingEnabled(): boolean {
+	return useLicenseFeatureFlag(useLicenseContext(), 'commenting')
+}

package/src/canvas/options.test.ts

@@ -0,0 +1,127 @@
+import type { Editor } from 'tldraw'
+import { describe, expect, it } from 'vitest'
+import { CommentTool } from './comment-tool'
+import { defaultCommentingOptions, getCommentingOptions, type CommentingOptions } from './options'
+import { commitCommentMutation, 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.
+function optionsOf(Tool: typeof CommentTool): CommentingOptions {
+	return new Tool({} as Editor).options
+}
+
+describe('CommentTool.configure', () => {
+	it('returns default options when unconfigured', () => {
+		expect(new CommentTool({} as Editor).options).toEqual(defaultCommentingOptions)
+	})
+
+	it('merges overrides over the defaults', () => {
+		const Tool = CommentTool.configure({ history: 'record', enableClustering: false })
+		expect(optionsOf(Tool)).toEqual({
+			...defaultCommentingOptions,
+			history: 'record',
+			enableClustering: false,
+		})
+	})
+
+	it('layers chained configure calls', () => {
+		const Tool = CommentTool.configure({ history: 'record' }).configure({ enableClustering: false })
+		expect(optionsOf(Tool)).toEqual({
+			...defaultCommentingOptions,
+			history: 'record',
+			enableClustering: false,
+		})
+	})
+
+	it('layers component slots across chained configure calls', () => {
+		const CommentBody = () => null
+		const PinContent = () => null
+		const Tool = CommentTool.configure({ components: { CommentBody } }).configure({
+			components: { PinContent },
+		})
+		// The second call's slot is added without dropping the first call's slot.
+		expect(optionsOf(Tool).components).toEqual({ CommentBody, PinContent })
+	})
+
+	it('does not mutate the base tool or the defaults', () => {
+		CommentTool.configure({ history: 'record' })
+		expect(new CommentTool({} as Editor).options).toEqual(defaultCommentingOptions)
+		expect(defaultCommentingOptions.history).toBe('ignore')
+	})
+})
+
+// A minimal editor stub: getCommentingOptions reads the comment tool's `options` off
+// getStateDescendant, and commitCommentMutation forwards to run().
+function stubEditor(options: CommentingOptions) {
+	const runCalls: Array<{ history: unknown }> = []
+	const editor = {
+		getStateDescendant: () => ({ options }),
+		run: (fn: () => void, opts: { history: unknown }) => {
+			runCalls.push(opts)
+			fn()
+			return editor
+		},
+	} as unknown as Editor
+	return { editor, runCalls }
+}
+
+describe('getCommentingOptions', () => {
+	it('reads the tool options off the editor', () => {
+		const options = { ...defaultCommentingOptions, history: 'record' } as CommentingOptions
+		const { editor } = stubEditor(options)
+		expect(getCommentingOptions(editor)).toBe(options)
+	})
+
+	it('falls back to defaults when the comment tool is absent', () => {
+		const editor = { getStateDescendant: () => undefined } as unknown as Editor
+		expect(getCommentingOptions(editor)).toBe(defaultCommentingOptions)
+	})
+})
+
+describe('commitCommentMutation', () => {
+	it('uses options.history for a mutation and returns the callback result', () => {
+		const { editor, runCalls } = stubEditor({
+			...defaultCommentingOptions,
+			history: 'record',
+		} as CommentingOptions)
+		const result = commitCommentMutation(editor, () => 42)
+		expect(result).toBe(42)
+		expect(runCalls).toEqual([{ history: 'record' }])
+	})
+
+	it('uses dragHistory for a drag, falling back to history when unset', () => {
+		const withDrag = stubEditor({
+			...defaultCommentingOptions,
+			history: 'ignore',
+			dragHistory: 'record',
+		} as CommentingOptions)
+		commitCommentMutation(withDrag.editor, () => undefined, 'drag')
+		expect(withDrag.runCalls).toEqual([{ history: 'record' }])
+
+		const noDrag = stubEditor({
+			...defaultCommentingOptions,
+			history: 'ignore',
+			dragHistory: undefined,
+		} as CommentingOptions)
+		commitCommentMutation(noDrag.editor, () => undefined, 'drag')
+		expect(noDrag.runCalls).toEqual([{ history: 'ignore' }])
+	})
+})
+
+describe('editor-scoped transient state', () => {
+	it('keeps open-thread state independent per editor (multi-editor guard)', () => {
+		const a = {} as Editor
+		const b = {} as Editor
+		openThreadId.set(a, 'thread:1')
+		expect(openThreadId.get(a)).toBe('thread:1')
+		expect(openThreadId.get(b)).toBe(null)
+	})
+
+	it('keeps pending-comment state independent per editor', () => {
+		const a = {} as Editor
+		const b = {} as Editor
+		pendingComment.set(a, { anchor: { type: 'page' }, point: { x: 0, y: 0 } })
+		expect(pendingComment.get(a)).not.toBe(null)
+		expect(pendingComment.get(b)).toBe(null)
+	})
+})

package/src/canvas/options.ts

@@ -0,0 +1,111 @@
+import { useMemo, type ComponentType } from 'react'
+import {
+	type Editor,
+	type TLComment,
+	type TLCommentThread,
+	type TLHistoryBatchOptions,
+	useEditor,
+} from 'tldraw'
+
+/**
+ * Component overrides for the batteries-included comments layer. Each slot replaces a built-in
+ * piece; leave a slot unset to keep its default.
+ *
+ * @public
+ */
+export interface CommentingComponents {
+	/** A comment's body. Replaces the default rich-text `<CommentBody>`. */
+	CommentBody?: ComponentType<{ comment: TLComment }>
+	/** A pin's inner content. Replaces the author-initial default. */
+	PinContent?: ComponentType<{ thread: TLCommentThread; comments: TLComment[] }>
+	/** A sidebar row's preview. Replaces the plaintext default. */
+	ThreadPreview?: ComponentType<{ comment: TLComment }>
+}
+
+/**
+ * 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>`.
+ *
+ * For defaults, see {@link defaultCommentingOptions}.
+ *
+ * @example
+ * ```tsx
+ * <Tldraw tools={[CommentTool.configure({ history: 'ignore', enableClustering: false })]} />
+ * ```
+ *
+ * @public
+ */
+export interface CommentingOptions {
+	// ── 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.
+	 */
+	readonly history: TLHistoryBatchOptions['history']
+	/**
+	 * History mode for the pin drag-to-move re-anchor specifically. Unlike posts/edits this is a
+	 * spatial edit that may reasonably be undoable alongside a shape move. Defaults to `history`.
+	 */
+	readonly dragHistory: TLHistoryBatchOptions['history'] | undefined
+
+	// ── Feature toggles ──────────────────────────────────────────────────────────────────────
+	/** Fold nearby pins into count badges as the camera zooms out. */
+	readonly enableClustering: boolean
+
+	// ── 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
+
+	// ── Components ────────────────────────────────────────────────────────────────────────────
+	/** Component overrides. See {@link CommentingComponents}. */
+	readonly components: CommentingComponents
+}
+
+/**
+ * The default {@link CommentingOptions}. Override via `CommentTool.configure({ ... })`.
+ *
+ * @public
+ */
+export const defaultCommentingOptions = {
+	history: 'ignore',
+	dragHistory: undefined,
+	enableClustering: true,
+	impreciseShapeAnchor: { x: 1, y: 0 },
+	clusterCullMargin: 120,
+	clusterSplitZoomFactor: 1.05,
+	components: {},
+} as const satisfies CommentingOptions
+
+/**
+ * The merged {@link CommentingOptions} for an editor, read off the registered comment tool (which
+ * carries them via `CommentTool.configure`). Falls back to {@link defaultCommentingOptions} when
+ * the comment tool isn't registered. Usable from anywhere with an `Editor` — including the tool's
+ * own state, which has no React context.
+ *
+ * @public
+ */
+export function getCommentingOptions(editor: Editor): CommentingOptions {
+	const tool = editor.getStateDescendant('comment') as { options?: CommentingOptions } | undefined
+	return tool?.options ?? defaultCommentingOptions
+}
+
+/**
+ * React hook for {@link getCommentingOptions}. Options are fixed per editor (set at tool
+ * registration), so this doesn't need to be reactive.
+ *
+ * @public
+ */
+export function useCommentingOptions(): CommentingOptions {
+	const editor = useEditor()
+	return useMemo(() => getCommentingOptions(editor), [editor])
+}

package/src/canvas/region-options.ts

@@ -0,0 +1,57 @@
+import { atom, Atom, Editor, VecLike } from 'tldraw'
+
+/**
+ * The configurable dimensions of region comments — a design surface for prototyping the interaction
+ * before settling it. Region is **off by default**, so a consumer that leaves it unset keeps plain
+ * click-only point/shape commenting. Set it per editor through `<CanvasComments regionOptions>`.
+ * @public
+ */
+export interface RegionCommentOptions {
+	/** Whether dragging the comment tool out creates a region anchor. Off → click-only. */
+	enabled: boolean
+	/** Which corner the pin and composer sit on, as a normalized 0–1 offset. Default bottom-right. */
+	pinCorner: VecLike
+	/** When the dashed box and its handles reveal: while the pointer is within the region, while the
+	 *  pin is hovered, or only while the thread is open. */
+	reveal: 'pointer' | 'pin-hover' | 'open'
+	/** How a region is moved: dragging its pin, dragging its body, or either. */
+	move: 'pin' | 'body' | 'both'
+	/** The resize affordance: corner handles, edge handles, or none. */
+	resize: 'corners' | 'edges' | 'none'
+}
+
+/** The out-of-the-box region config: disabled, and — when a consumer enables it — the current
+ *  bottom-right / pointer-reveal / pin-move / corner-resize behaviour.
+ * @public */
+export const DEFAULT_REGION_COMMENT_OPTIONS: RegionCommentOptions = {
+	enabled: false,
+	pinCorner: { x: 1, y: 1 },
+	reveal: 'pointer',
+	move: 'pin',
+	resize: 'corners',
+}
+
+// Per-editor region config. The overlay publishes its merged `regionOptions` here so the comment
+// tool — which has no props of its own — can read the same per-instance config at interaction time.
+// Held in an atom so reactive readers (e.g. `anchorPagePoint`, called inside `useValue`) recompute
+// when the config changes; a plain map read wouldn't, leaving the pin at the stale default corner.
+const byEditor = new WeakMap<Editor, Atom<RegionCommentOptions>>()
+
+function getEditorAtom(editor: Editor): Atom<RegionCommentOptions> {
+	let a = byEditor.get(editor)
+	if (!a) {
+		a = atom('regionCommentOptions', DEFAULT_REGION_COMMENT_OPTIONS)
+		byEditor.set(editor, a)
+	}
+	return a
+}
+
+/** Publish an editor's region config (called by the overlay from its `regionOptions` prop). */
+export function setRegionCommentOptions(editor: Editor, options: RegionCommentOptions): void {
+	getEditorAtom(editor).set(options)
+}
+
+/** The editor's region config, or the disabled default when none was set. */
+export function getRegionCommentOptions(editor: Editor): RegionCommentOptions {
+	return getEditorAtom(editor).get()
+}

package/src/canvas/rich-text.ts

@@ -0,0 +1,15 @@
+import { TLRichText } from 'tldraw'
+import { renderCommentPlaintext } from './comment-render'
+
+/**
+ * Flatten a rich-text comment body to plaintext through the limited comment extension set,
+ * separating paragraphs and list items with newlines. A convenience for consumers rendering bodies
+ * as plain text (e.g. the sidebar preview); richer rendering can read the `TLRichText` directly.
+ * @public
+ */
+export function richTextToPlaintext(
+	body: TLRichText,
+	resolveName?: (id: string) => string | undefined
+): string {
+	return renderCommentPlaintext(body, resolveName)
+}

package/src/canvas/sidebar-filters.ts

@@ -0,0 +1,25 @@
+/**
+ * Which threads the comments sidebar shows. Held as an editor-scoped signal (the `sidebarFilters`
+ * `EditorAtom` in `./state`) rather than component state so it survives the sidebar
+ * unmounting when the comment tool deactivates — a user's "hide resolved" choice shouldn't reset
+ * every time they leave the tool.
+ * @public
+ */
+export interface SidebarFilters {
+	/** Include resolved threads. */
+	showResolved: boolean
+	/** Only threads the current user started. Ignored when there's no current user. */
+	onlyMine: boolean
+	/** Only threads with unread comments. Ignored when the host provides no read status. */
+	onlyUnread: boolean
+	/** Only threads on the current page. Off = every page's threads, each labelled. */
+	onlyCurrentPage: boolean
+}
+
+/** @public */
+export const DEFAULT_SIDEBAR_FILTERS: SidebarFilters = {
+	showResolved: true,
+	onlyMine: false,
+	onlyUnread: false,
+	onlyCurrentPage: true,
+}

package/src/canvas/state.ts

@@ -0,0 +1,102 @@
+import {
+	EditorAtom,
+	type BoxModel,
+	type Editor,
+	type TLHistoryBatchOptions,
+	useEditor,
+	useValue,
+} from 'tldraw'
+import type { PendingComment } from './comment-tool'
+import { getCommentingOptions } from './options'
+import { DEFAULT_SIDEBAR_FILTERS, type SidebarFilters } from './sidebar-filters'
+
+/**
+ * Transient commenting UI state, scoped per editor via {@link EditorAtom}. Editor-scoping (rather
+ * than module-global atoms) keeps two editors on one page — or an editor and a second instance —
+ * from sharing open-thread, visibility, and filter state. Reachable from both React (`useEditor()`)
+ * and the comment tool (`this.editor`).
+ */
+
+/** The id of the one open thread (only one popover is open at a time), or null when all closed.
+ * @public */
+export const openThreadId = new EditorAtom<string | null>('openThreadId', () => null)
+
+/** The comment currently being placed (composer open, not yet posted), or null.
+ * @public */
+export const pendingComment = new EditorAtom<PendingComment | null>('pendingComment', () => null)
+
+/** 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)
+
+/**
+ * Whether comment pins are hidden on the canvas. Governs the on-canvas layer (pins + open popover)
+ * only — the sidebar is unaffected.
+ * @public
+ */
+export const commentsHidden = new EditorAtom<boolean>('commentsHidden', () => false)
+
+/** Which threads the comments sidebar shows.
+ * @public */
+export const sidebarFilters = new EditorAtom<SidebarFilters>(
+	'sidebarFilters',
+	() => DEFAULT_SIDEBAR_FILTERS
+)
+
+/** Toggle comment-pin visibility for an editor.
+ * @public */
+export function toggleCommentsHidden(editor: Editor): void {
+	commentsHidden.update(editor, (hidden) => !hidden)
+}
+
+/** React hook for the open thread id.
+ * @public */
+export function useOpenThreadId(): string | null {
+	const editor = useEditor()
+	return useValue('open thread id', () => openThreadId.get(editor), [editor])
+}
+
+/** React hook for the pending (being-placed) comment.
+ * @public */
+export function usePendingComment(): PendingComment | null {
+	const editor = useEditor()
+	return useValue('pending comment', () => pendingComment.get(editor), [editor])
+}
+
+/** React hook for whether comment pins are hidden.
+ * @public */
+export function useCommentsHidden(): boolean {
+	const editor = useEditor()
+	return useValue('comments hidden', () => commentsHidden.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!
+}