@tldraw/commenting 0.0.0-bootstrap

package/src/clustering/schedule.ts

@@ -0,0 +1,184 @@
+import type { ClusterNode, ContractedEvent, MergeEvent, RawMergeEvent } from './types'
+
+export function contract(raw: readonly RawMergeEvent[], eps: number): ContractedEvent[] {
+	if (!Number.isFinite(eps) || eps < 0) {
+		throw new Error('eps must be finite and greater than or equal to 0')
+	}
+
+	const out: ContractedEvent[] = []
+	let i = 0
+	while (i < raw.length) {
+		const anchor = raw[i].z
+		let j = i
+		while (j + 1 < raw.length && raw[j + 1].z >= anchor / (1 + eps)) {
+			j++
+		}
+
+		const chains = contractWindow(raw.slice(i, j + 1), anchor)
+		out.push(...chains)
+		i = j + 1
+	}
+
+	return out
+}
+
+export function finalize(
+	events: readonly ContractedEvent[],
+	opts: { Tc: number; Tu: number; minZoom: number; maxZoom: number; maxSplitZoom: number }
+): MergeEvent[] {
+	validateFinalizeOptions(opts)
+
+	const r = opts.Tu / opts.Tc
+	// Every cluster must have split by maxSplitZoom, however close (or coincident) its members.
+	// Capping zMerge at maxSplitZoom / r keeps the whole band below the cap, preserving
+	// zSplit > zMerge and the table's sort order (min with a constant is order-preserving).
+	const zMergeCap = opts.maxSplitZoom / r
+	const out: MergeEvent[] = []
+	for (const event of events) {
+		const zMerge = Math.min(event.zMerge, zMergeCap)
+		if (zMerge < opts.minZoom) break
+		let zSplit = zMerge * r
+		if (zMerge < opts.maxZoom) {
+			zSplit = Math.min(zSplit, opts.maxZoom)
+		}
+		out.push({
+			zMerge,
+			zSplit,
+			children: event.children,
+			result: event.result,
+		})
+	}
+	return out
+}
+
+function contractWindow(events: readonly RawMergeEvent[], zMerge: number): ContractedEvent[] {
+	const uf = new ComponentUnionFind(events.length)
+	const resultToIndex = new Map<string, number>()
+	for (let i = 0; i < events.length; i++) {
+		resultToIndex.set(events[i].result.id, i)
+	}
+
+	for (let i = 0; i < events.length; i++) {
+		for (const child of events[i].children) {
+			const producer = resultToIndex.get(child.id)
+			if (producer !== undefined) {
+				uf.union(i, producer)
+			}
+		}
+	}
+
+	const byRoot = new Map<number, number[]>()
+	for (let i = 0; i < events.length; i++) {
+		const root = uf.find(i)
+		const list = byRoot.get(root)
+		if (list) {
+			list.push(i)
+		} else {
+			byRoot.set(root, [i])
+		}
+	}
+
+	return Array.from(byRoot.values())
+		.map((indices) => contractChain(events, indices, zMerge))
+		.sort((a, b) => compareNodesByMinMember(a.result, b.result))
+}
+
+function contractChain(
+	events: readonly RawMergeEvent[],
+	indices: readonly number[],
+	zMerge: number
+): ContractedEvent {
+	const produced = new Set<string>()
+	const consumedProduced = new Set<string>()
+	for (const index of indices) {
+		produced.add(events[index].result.id)
+	}
+	for (const index of indices) {
+		for (const child of events[index].children) {
+			if (produced.has(child.id)) consumedProduced.add(child.id)
+		}
+	}
+
+	const childrenById = new Map<string, ClusterNode>()
+	for (const index of indices) {
+		for (const child of events[index].children) {
+			if (!produced.has(child.id)) childrenById.set(child.id, child)
+		}
+	}
+
+	let result: ClusterNode | undefined
+	for (const index of indices) {
+		const candidate = events[index].result
+		if (!consumedProduced.has(candidate.id)) {
+			if (!result || compareNodesByMinMember(candidate, result) < 0) result = candidate
+		}
+	}
+
+	return {
+		zMerge,
+		children: Array.from(childrenById.values()).sort(compareNodesByMinMember),
+		result: result!,
+	}
+}
+
+function validateFinalizeOptions(opts: {
+	Tc: number
+	Tu: number
+	minZoom: number
+	maxZoom: number
+	maxSplitZoom: number
+}) {
+	if (!Number.isFinite(opts.maxSplitZoom) || opts.maxSplitZoom <= 0) {
+		throw new Error('maxSplitZoom must be finite and greater than 0')
+	}
+	if (!Number.isFinite(opts.Tc) || opts.Tc <= 0) {
+		throw new Error('Tc must be finite and greater than 0')
+	}
+	if (!Number.isFinite(opts.Tu) || opts.Tu <= opts.Tc) {
+		throw new Error('Tu must be finite and greater than Tc')
+	}
+	if (!Number.isFinite(opts.minZoom) || opts.minZoom <= 0) {
+		throw new Error('minZoom must be finite and greater than 0')
+	}
+	if (!Number.isFinite(opts.maxZoom) || opts.maxZoom <= opts.minZoom) {
+		throw new Error('maxZoom must be finite and greater than minZoom')
+	}
+}
+
+function compareNodesByMinMember(a: ClusterNode, b: ClusterNode): number {
+	const aMin = a.members[0]
+	const bMin = b.members[0]
+	if (aMin < bMin) return -1
+	if (aMin > bMin) return 1
+	return 0
+}
+
+class ComponentUnionFind {
+	private readonly parent: Int32Array
+
+	constructor(n: number) {
+		this.parent = new Int32Array(n)
+		for (let i = 0; i < n; i++) {
+			this.parent[i] = i
+		}
+	}
+
+	find(index: number): number {
+		let root = index
+		while (this.parent[root] !== root) {
+			root = this.parent[root]
+		}
+		while (this.parent[index] !== index) {
+			const next = this.parent[index]
+			this.parent[index] = root
+			index = next
+		}
+		return root
+	}
+
+	union(a: number, b: number) {
+		const rootA = this.find(a)
+		const rootB = this.find(b)
+		if (rootA !== rootB) this.parent[rootB] = rootA
+	}
+}

package/src/clustering/types.ts

@@ -0,0 +1,102 @@
+import type { VecLike } from 'tldraw'
+
+/**
+ * One comment thread's pin, already resolved to a page-space anchor point.
+ * @public
+ */
+export interface LeafInput {
+	/** Unique. Thread id. Uniqueness is a precondition — throw on duplicates. */
+	id: string
+	/** Page-space coordinates. Must be finite — throw on NaN/Infinity. */
+	point: VecLike
+}
+
+/** An edge of the Euclidean MST over the leaf anchor points. */
+export interface MstEdge {
+	/** Index into the input leaves array. Normalized: leaves[a].id < leaves[b].id (lexicographic). */
+	a: number
+	/** Index into the input leaves array. */
+	b: number
+	/** Exact Euclidean page-space distance between the two anchors. May be 0 (coincident). */
+	d: number
+}
+
+/**
+ * A cluster in the merge tree: a leaf (one thread) or a merged group.
+ * @public
+ */
+export interface ClusterNode {
+	/** Leaves: the thread id verbatim. Merged nodes: `cluster:${count}:${minMemberId}`. */
+	id: string
+	/** Page space; count-weighted mean of all member leaf anchors. */
+	centroid: VecLike
+	/** Number of member leaves. Leaves = 1. */
+	count: number
+	/** All member thread ids, sorted lexicographically ascending. */
+	members: string[]
+}
+
+/** One merge produced by the capped replay, before contraction. */
+export interface RawMergeEvent {
+	/** Effective merge threshold zEff = min(Tc/d, Dmax/unionBboxDiag). +Infinity for coincident anchors. */
+	z: number
+	/** The two clusters consumed, ordered by ascending min-member id. */
+	children: [ClusterNode, ClusterNode]
+	/** The cluster produced. */
+	result: ClusterNode
+}
+
+/** A merge event after contraction: possibly multi-way, before hysteresis. */
+export interface ContractedEvent {
+	/** Fires (merges) when zoom <= zMerge. May be +Infinity. */
+	zMerge: number
+	/** Clusters consumed — 2 or more, ordered by ascending min-member id. */
+	children: ClusterNode[]
+	/** Cluster produced. */
+	result: ClusterNode
+}
+
+/**
+ * A finalized merge event, ready for the runtime.
+ * @public
+ */
+export interface MergeEvent {
+	zMerge: number
+	/** Reverses (splits) when zoom \>= zSplit. Always \> zMerge. May be +Infinity. */
+	zSplit: number
+	children: ClusterNode[]
+	result: ClusterNode
+}
+
+/**
+ * The precomputed clustering schedule for one page's comments.
+ * @public
+ */
+export interface ClusterTable {
+	/** Sorted non-increasing by zMerge; satisfies the invariants of CLUSTERING.md §7.6. */
+	events: readonly MergeEvent[]
+	/** One node per input leaf, in input order. */
+	leaves: readonly ClusterNode[]
+}
+
+/** @public */
+export interface ClusterOptions {
+	/** Cluster (merge) distance, screen px. Default 40. */
+	Tc?: number
+	/** Uncluster (split) distance, screen px. Must be \> Tc. Default 1.5 · Tc. */
+	Tu?: number
+	/** Contraction window ratio. Default 0.12. */
+	eps?: number
+	/** Max cluster screen extent at birth, screen px. Must be \>= Tc. Default 3 · Tc. */
+	Dmax?: number
+	/** Camera zoom bounds — pass the editor's camera constraints. Required. */
+	minZoom: number
+	maxZoom: number
+	/**
+	 * Zoom by which every cluster has split, no matter how close its members are — including
+	 * coincident anchors, which otherwise never split. Merge thresholds are capped at
+	 * `maxSplitZoom / (Tu/Tc)` so the hysteresis band keeps its shape below the cap.
+	 * Default 6 (600%).
+	 */
+	maxSplitZoom?: number
+}

package/src/index.ts

@@ -0,0 +1,96 @@
+import { registerTldrawLibraryVersion } from '@tldraw/utils'
+
+// Presentational commenting components. These are tldraw-independent and can be used to build
+// custom commenting UI.
+export { Avatar, type AvatarProps } from './ui/avatar'
+export { Byline, type BylineProps } from './ui/byline'
+export { CommentCard, type CommentCardProps } from './ui/comment-card'
+export { CommentComposer, type CommentComposerProps } from './ui/comment-composer'
+export { CountBadge, type CountBadgeProps } from './ui/count-badge'
+export { CommentPin, type CommentPinProps } from './ui/comment-pin'
+export { CommentText, type CommentTextProps } from './ui/comment-text'
+export { CommentThread, type CommentThreadProps } from './ui/comment-thread'
+export { CommentsList, type CommentListItemProps, type CommentsListProps } from './ui/comments-list'
+export { EmptyState, type EmptyStateProps } from './ui/empty-state'
+export { formatRelativeTime } from './ui/format-time'
+export { Mention, type MentionProps } from './ui/mention'
+export { MentionList, type MentionListProps, type MentionMember } from './ui/mention-list'
+export {
+	createMentionSuggestion,
+	filterMentionMembers,
+	type MentionSuggestionOptions,
+} from './ui/mention-suggestion'
+export { Reaction, type ReactionProps } from './ui/reaction'
+export { Reactions } from './ui/reactions'
+export { renderMarkdown } from './ui/render-markdown'
+export { SendButton, type SendButtonProps } from './ui/send-button'
+
+// The tldraw-coupled commenting layer: the comment tool, reactive hooks over the comment
+// records, a rich-text body renderer, and a batteries-included <CanvasComments> overlay. Pairs
+// with the presentational components above.
+export { CommentBody, type CommentBodyProps } from './canvas/comment-body'
+export {
+	CommentTool,
+	commentToolOverrides,
+	commentTools,
+	type PendingComment,
+} from './canvas/comment-tool'
+export { collectClusterLeaves } from './canvas/cluster-input'
+export { computeClusterTable } from './clustering/computeClusterTable'
+export {
+	getCommentRecord,
+	getComments,
+	getCommentThreads,
+	putCommentRecords,
+	removeCommentRecords,
+	type TLCommentRecord,
+} from './canvas/comment-store'
+export { createClusterRuntime, type ClusterRuntime } from './clustering/runtime'
+export type {
+	ClusterNode,
+	ClusterOptions,
+	ClusterTable,
+	LeafInput,
+	MergeEvent,
+} from './clustering/types'
+export { CommentsFilterMenu, type CommentsFilterMenuProps } from './canvas/comments-filter-menu'
+export { CommentsMenuItem } from './canvas/comments-menu-item'
+export { CanvasComments, type CanvasCommentsProps } from './canvas/comments-overlay'
+export {
+	type CommentingComponents,
+	type CommentingOptions,
+	defaultCommentingOptions,
+	getCommentingOptions,
+	useCommentingOptions,
+} from './canvas/options'
+export { CommentsOverflowMenu } from './canvas/comments-overflow-menu'
+export { CanvasCommentsSidebar, type CanvasCommentsSidebarProps } from './canvas/comments-sidebar'
+export { useComments, useCommentThreads, useThreadComments } from './canvas/hooks'
+export { useCommentingEnabled } from './canvas/license'
+export { DEFAULT_REGION_COMMENT_OPTIONS, type RegionCommentOptions } from './canvas/region-options'
+export { richTextToPlaintext } from './canvas/rich-text'
+export { DEFAULT_SIDEBAR_FILTERS, type SidebarFilters } from './canvas/sidebar-filters'
+export {
+	commentsHidden,
+	commitCommentMutation,
+	openThreadId,
+	pendingComment,
+	sidebarFilters,
+	toggleCommentsHidden,
+	useCommentsHidden,
+	useOpenThreadId,
+	usePendingComment,
+	useSidebarFilters,
+} from './canvas/state'
+export {
+	anchorPagePoint,
+	DEFAULT_IMPRECISE_SHAPE_ANCHOR,
+	focusThread,
+	shapeAnchorAt,
+} from './canvas/thread-state'
+
+registerTldrawLibraryVersion(
+	(globalThis as any).TLDRAW_LIBRARY_NAME,
+	(globalThis as any).TLDRAW_LIBRARY_VERSION,
+	(globalThis as any).TLDRAW_LIBRARY_MODULES
+)

package/src/ui/avatar.tsx

@@ -0,0 +1,31 @@
+import { getFirstCharacter } from 'tldraw'
+
+/** @public */
+export interface AvatarProps {
+	name: string
+	/** Background colour, used when there's no `image`. Falls back to the default avatar tint. */
+	color?: string
+	/** Avatar image URL. When set, shows the image instead of the coloured initial. */
+	image?: string
+}
+
+function initial(name: string) {
+	return (getFirstCharacter(name.trim()) || '?').toUpperCase()
+}
+
+/** A commenter's avatar — their image if provided, otherwise a single-initial coloured circle.
+ * @public @react */
+export function Avatar({ name, color, image }: AvatarProps) {
+	if (image) {
+		return <img className="cmt-avatar cmt-avatar--image" src={image} alt="" aria-hidden="true" />
+	}
+	return (
+		<div
+			className="cmt-avatar"
+			aria-hidden="true"
+			style={color ? { backgroundColor: color } : undefined}
+		>
+			{initial(name)}
+		</div>
+	)
+}

package/src/ui/byline.tsx

@@ -0,0 +1,23 @@
+import { formatRelativeTime } from './format-time'
+
+/** @public */
+export interface BylineProps {
+	author: string
+	/** ISO datetime; formatted to relative time by the component. */
+	date: string
+	/** Shows an "edited" marker when the comment has been edited. */
+	edited?: boolean
+}
+
+/** A comment's metadata line: author name, relative time, and an edited marker. @public @react */
+export function Byline({ author, date, edited }: BylineProps) {
+	return (
+		<div className="cmt-head">
+			<span className="cmt-author">{author}</span>
+			<span className="cmt-time">
+				{formatRelativeTime(date)}
+				{edited && <span className="cmt-edited"> · edited</span>}
+			</span>
+		</div>
+	)
+}

package/src/ui/comment-card.tsx

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react'
+import { Avatar } from './avatar'
+import { Byline } from './byline'
+
+/** @public */
+export interface CommentCardProps {
+	author: string
+	/** The rendered comment body. The card doesn't dictate a format — pass a `<CommentText>`
+	 *  for markdown, a rich-text render, or any node. */
+	body: ReactNode
+	/** ISO datetime; formatted to relative time by the component. */
+	date: string
+	you: boolean
+	/** Whether the comment has been edited (shows an "edited" marker). */
+	edited?: boolean
+	/** Hover-revealed controls at the card's top-right (e.g. an edit affordance). */
+	actions?: ReactNode
+}
+
+/** A single comment: Avatar, Byline, and a body slot the consumer renders. @public @react */
+export function CommentCard({ author, body, date, you, edited, actions }: CommentCardProps) {
+	return (
+		<div className={you ? 'cmt-card cmt-card--you' : 'cmt-card'}>
+			<Avatar name={author} />
+			<div className="cmt-body">
+				<Byline author={author} date={date} edited={edited} />
+				{body}
+			</div>
+			{actions !== undefined && <div className="cmt-card__actions">{actions}</div>}
+		</div>
+	)
+}

package/src/ui/comment-composer.tsx

@@ -0,0 +1,179 @@
+import { Extension, JSONContent } from '@tiptap/core'
+import { EditorContent, useEditor } from '@tiptap/react'
+import { ReactNode, useEffect, useMemo, useRef, useState } from 'react'
+import { isEqual, TLRichText, useMaybeEditor } from 'tldraw'
+import { Avatar } from './avatar'
+import { commentTipTapExtensions, EMPTY_COMMENT, isCommentEmpty } from './comment-extensions'
+import { commentMention } from './comment-mention'
+import { MentionMember } from './mention-list'
+import { createMentionSuggestion, isMentionPickerOpen } from './mention-suggestion'
+import { SendButton } from './send-button'
+
+/** @public */
+export interface CommentComposerProps {
+	author: string
+	placeholder: string
+	/** Controlled rich-text value. Omit for the presentational (display-only) composer. */
+	value?: TLRichText
+	onChange?(value: TLRichText): void
+	/** Called on Send click or Enter. When set, the composer is interactive. */
+	onSubmit?(): void
+	sendLabel?: string
+	disabled?: boolean
+	autoFocus?: boolean
+	/** The leading element before the field. Defaults to the author's avatar. */
+	leading?: ReactNode
+	/** Resolve the members matching an `@`-query (sync or async). Provide to enable mentions. */
+	getMentionSuggestions?(query: string): MentionMember[] | Promise<MentionMember[]>
+	/** Override a picker row's content. Defaults to avatar + name (+ secondary). */
+	renderMentionSuggestion?(member: MentionMember): ReactNode
+}
+
+/**
+ * The input for writing a comment: a TipTap rich-text editor restricted to the comment extension
+ * set (bold, italic, lists, links, code, highlight — no headings), with a Send button. Formatting
+ * is applied through markdown and keyboard shortcuts (e.g. `**bold**`, `- `, Cmd+B); there's no
+ * floating toolbar. Presentational by default; pass value/onChange/onSubmit to drive it as a form.
+ * @public @react
+ */
+export function CommentComposer({
+	author,
+	placeholder,
+	value,
+	onChange,
+	onSubmit,
+	sendLabel = 'Send',
+	disabled,
+	autoFocus,
+	leading,
+	getMentionSuggestions,
+	renderMentionSuggestion,
+}: CommentComposerProps) {
+	const interactive = !!onChange || !!onSubmit
+	// The canvas editor the composer lives in, if any — lets the mention popup track the camera. Null
+	// when the composer is used outside a tldraw editor (e.g. an isolated demo).
+	const tlEditor = useMaybeEditor()
+
+	// Callbacks are read through refs so the editor instance doesn't need to be recreated when they
+	// change identity between renders.
+	const onChangeRef = useRef(onChange)
+	onChangeRef.current = onChange
+	const onSubmitRef = useRef(onSubmit)
+	onSubmitRef.current = onSubmit
+	const disabledRef = useRef(disabled)
+	disabledRef.current = disabled
+	const getMentionSuggestionsRef = useRef(getMentionSuggestions)
+	getMentionSuggestionsRef.current = getMentionSuggestions
+	const renderMentionSuggestionRef = useRef(renderMentionSuggestion)
+	renderMentionSuggestionRef.current = renderMentionSuggestion
+
+	const [isEmpty, setIsEmpty] = useState(() => !value || isCommentEmpty(value))
+
+	// Enter submits the comment. Shift+Enter (and Cmd/Ctrl+Enter) keep their default behavior — a
+	// new line — for the occasional multi-line comment.
+	const submitExtension = useMemo(
+		() =>
+			Extension.create({
+				name: 'commentComposerSubmit',
+				priority: 1000,
+				addKeyboardShortcuts() {
+					return {
+						Enter: () => {
+							// While the @-mention picker is open, Enter selects the highlighted member.
+							// This extension outranks the mention plugin (priority 1000), so defer to the
+							// picker here or Enter would submit before the member could be inserted.
+							if (isMentionPickerOpen()) return false
+							if (!disabledRef.current) onSubmitRef.current?.()
+							return true
+						},
+					}
+				},
+			}),
+		[]
+	)
+
+	// The suggestion plugin is built once (the editor is recreated only on `interactive`) and runs
+	// outside React, so it must read the mention callbacks through refs — like onChange/onSubmit —
+	// or it queries the roster present at mount forever, never seeing a member who loads or joins
+	// later. Whether mentions (and a custom picker row) are wired at all is fixed at mount; only the
+	// callbacks themselves are live.
+	const mentionsEnabled = !!getMentionSuggestions
+	const hasCustomRow = !!renderMentionSuggestion
+	const extensions = useMemo(() => {
+		const list = [...commentTipTapExtensions, submitExtension]
+		// Always register the mention node so an existing body that contains a mention keeps it on
+		// edit (an unregistered node would be stripped by ProseMirror when the content loads). The `@`
+		// picker itself only turns on when the host provides a resolver; otherwise the node is present
+		// but its trigger is disabled.
+		if (mentionsEnabled) {
+			const resolveSuggestions = (query: string) => getMentionSuggestionsRef.current?.(query) ?? []
+			const renderRow = hasCustomRow
+				? (member: MentionMember) => renderMentionSuggestionRef.current?.(member)
+				: undefined
+			list.push(
+				commentMention({
+					suggestion: createMentionSuggestion(resolveSuggestions, {
+						renderMember: renderRow,
+						editor: tlEditor,
+					}),
+				})
+			)
+		} else {
+			list.push(commentMention({ suggestion: { char: '@', allow: () => false } }))
+		}
+		return list
+	}, [submitExtension, mentionsEnabled, hasCustomRow, tlEditor])
+
+	const editor = useEditor(
+		{
+			extensions,
+			content: (value ?? EMPTY_COMMENT) as JSONContent,
+			editable: interactive,
+			// tldraw's default extensions add their own TextDirection extension (so it can be
+			// overridden), so disable TipTap's core one to avoid a duplicate-extension warning —
+			// mirrors RichTextArea's setup.
+			enableCoreExtensions: { textDirection: false },
+			textDirection: 'auto',
+			editorProps: { attributes: { class: 'cmt-input' } },
+			onUpdate: ({ editor }) => {
+				setIsEmpty(editor.isEmpty)
+				onChangeRef.current?.(editor.getJSON() as TLRichText)
+			},
+		},
+		[interactive]
+	)
+
+	// Sync controlled resets (e.g. the parent clearing to EMPTY_COMMENT after posting) into the
+	// editor without echoing back the value the editor itself just emitted.
+	useEffect(() => {
+		if (!editor || value === undefined) return
+		if (isEqual(editor.getJSON(), value)) return
+		editor.commands.setContent(value as JSONContent)
+		setIsEmpty(editor.isEmpty)
+	}, [editor, value])
+
+	// Focus on the next frame rather than via TipTap's autofocus: the composer often mounts from a
+	// canvas pointer event whose default focus handling would otherwise steal it back.
+	useEffect(() => {
+		if (!autoFocus || !editor) return
+		const raf = requestAnimationFrame(() => editor.commands.focus('end'))
+		return () => cancelAnimationFrame(raf)
+	}, [autoFocus, editor])
+
+	return (
+		<div className="cmt-composer">
+			{leading ?? <Avatar name={author} />}
+			<div className="cmt-composer__field">
+				<div className="cmt-composer__input-wrap">
+					<EditorContent editor={editor} />
+					{isEmpty && (
+						<div className="cmt-input__placeholder" aria-hidden="true">
+							{placeholder}
+						</div>
+					)}
+				</div>
+				{interactive && <SendButton label={sendLabel} onClick={onSubmit} disabled={disabled} />}
+			</div>
+		</div>
+	)
+}

package/src/ui/comment-extensions.ts

@@ -0,0 +1,25 @@
+import { getTipTapDefaultExtensions, TLRichText, toRichText } from 'tldraw'
+
+/**
+ * tldraw's default rich-text extension set, minus headings — the deliberately limited set used for
+ * both the comment composer and comment display. Comments support paragraphs, bold, italic, lists,
+ * links, code, and highlight, but not headings. Built from tldraw's shared factory so the config
+ * stays in lockstep with the text shape's defaults rather than drifting from a copy.
+ */
+export const commentTipTapExtensions = getTipTapDefaultExtensions({ heading: false })
+
+/** An empty comment document — the seed value for a fresh composer and its post-submit reset. */
+export const EMPTY_COMMENT: TLRichText = toRichText('')
+
+/**
+ * Whether a rich-text comment body has no text. Mirrors tldraw's private `isEmptyRichText`: an
+ * empty doc can be encoded as an empty `content` array or a single empty paragraph.
+ */
+export function isCommentEmpty(richText: TLRichText): boolean {
+	if (richText.content.length === 0) return true
+	if (richText.content.length === 1) {
+		const node = richText.content[0] as any
+		if (!node.content || node.content.length === 0) return true
+	}
+	return false
+}