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

package/src/canvas/comment-mutations.ts

@@ -16,14 +16,11 @@ import { openThreadId } from './state'
 /**
  * Every write to a comment record, and the undo/redo policy governing them.
  *
- * This file layers bottom-up: {@link commitCommentMutation} resolves the history mode,
- * {@link putCommentRecords} and {@link removeCommentRecords} are the typed writes that run under
- * it, and the verbs below are those writes plus the one rule each carries — a timestamp to stamp, a
- * shape to put the `resolved` field in, or the soft-delete protocol. The built-in thread view calls
- * exactly these verbs, so a UI of your own behaves the same as the one in the box.
- *
- * Every verb takes the record it acts on, but treats it as the identity of what to change rather
- * than as the value to write back — see {@link readLatest}.
+ * The file layers bottom-up: {@link commitCommentMutation} resolves the history mode and hands its
+ * callback a writer, {@link putCommentRecords} and {@link removeCommentRecords} are the typed
+ * writes that run under it, and the verbs below are those writes plus the one rule each carries.
+ * Every verb takes the record it acts on as the identity of what to change, not the value to write
+ * back — see {@link readLatest}.
  *
  * Posting carries no such rule, so it isn't a verb here: build the records with
  * `createCommentThread`/`createComment` and write them with {@link putCommentRecords}.
@@ -42,6 +39,13 @@ import { openThreadId } from './state'
  */
 export type CommentMutationKind = 'delete' | 'drag' | 'mutation'
 
+interface CommentMutationWriter {
+	put(records: TLCommentRecord[]): void
+	remove(ids: (TLCommentId | TLCommentReactionId | TLCommentThreadId)[]): void
+}
+
+const activeCommentMutations = new WeakMap<Editor, { history: TLHistoryBatchOptions['history'] }>()
+
 /** The undo/redo mode a write of the given kind runs under. See {@link CommentMutationKind}. */
 function historyModeFor(
 	options: CommentingOptions,
@@ -61,71 +65,92 @@ function historyModeFor(
  * Commit a comment mutation with the configured undo/redo behavior, so the
  * {@link CommentingOptions.history} option governs whether it lands on the undo stack. Defaults to
  * `'ignore'`. See {@link CommentMutationKind} for what each kind resolves to.
+ *
+ * `editor.run`'s history option isn't additive — a nested run overwrites the enclosing mode — so
+ * constituent records go through the callback's writer instead of opening a commit of their own,
+ * which would quietly make a `drag` write non-undoable.
+ *
+ * Commits that nest are only a problem when they resolve to different modes, and then neither is
+ * the right one to keep, so it throws. Matching modes have to nest: a store side effect runs inside
+ * the write that triggered it, with no "after the commit" to defer to. (A `store.listen` handler
+ * normally flushes on a later frame, so its writes open a commit of their own, but a synchronous
+ * flush — as under test — lands it inside too.)
  * @internal
  */
 export function commitCommentMutation<T>(
 	editor: Editor,
-	fn: () => T,
+	fn: (writer: CommentMutationWriter) => T,
 	kind: CommentMutationKind = 'mutation'
 ): T {
 	const history = historyModeFor(getCommentingOptions(editor), kind)
-	let result: T
-	editor.run(
-		() => {
-			result = fn()
-		},
-		{ history }
-	)
-	return result!
-}
-
-/**
- * Write records without opening a commit, for call sites that already sit inside one.
- *
- * `editor.run`'s history option isn't additive — a nested run overwrites the enclosing mode for its
- * own scope — so a {@link putCommentRecords} call inside a commit would discard the mode its caller
- * chose. A pin drag committed as `drag` under `dragHistory: 'record'` would land back on
- * `history: 'ignore'` and quietly stop being undoable. Inside a commit, write with this.
- *
- * @internal
- */
-export function putRecordsInCommit(editor: Editor, records: TLCommentRecord[]): void {
-	editor.store.put(records as unknown as TLRecord[])
-}
+	const enclosing = activeCommentMutations.get(editor)
+	if (enclosing && enclosing.history !== history) {
+		throw new Error(
+			`A comment mutation that records history as '${history}' can't run inside one recording it as '${enclosing.history}': one of the two modes would be silently discarded. Use the provided writer for constituent records, or run this operation after the enclosing one has committed.`
+		)
+	}
 
-/** {@link putRecordsInCommit}'s counterpart for removals. @internal */
-export function removeRecordsInCommit(
-	editor: Editor,
-	ids: (TLCommentId | TLCommentReactionId | TLCommentThreadId)[]
-): void {
-	editor.store.remove(ids as unknown as TLRecord['id'][])
+	activeCommentMutations.set(editor, { history })
+	try {
+		let result: T
+		editor.run(
+			() => {
+				let isWriterActive = true
+				const assertWriterActive = () => {
+					if (!isWriterActive) {
+						throw new Error(
+							'A comment mutation writer cannot be used after its commit has finished.'
+						)
+					}
+				}
+				try {
+					result = fn({
+						put: (records) => {
+							assertWriterActive()
+							editor.store.put(records as unknown as TLRecord[])
+						},
+						remove: (ids) => {
+							assertWriterActive()
+							editor.store.remove(ids as unknown as TLRecord['id'][])
+						},
+					})
+				} finally {
+					isWriterActive = false
+				}
+			},
+			{ history }
+		)
+		return result!
+	} finally {
+		if (enclosing) {
+			activeCommentMutations.set(editor, enclosing)
+		} else {
+			activeCommentMutations.delete(editor)
+		}
+	}
 }
 
 /**
- * Write comment records to the store, under the configured
- * {@link CommentingOptions.history} behavior — so a record you write lands on the undo stack (or
- * doesn't) exactly like one the built-in UI writes. Defaults to `'ignore'`.
+ * Write comment records to the store, under the configured {@link CommentingOptions.history}
+ * behavior. Defaults to `'ignore'`.
  *
- * Use it to seed or import threads, and to save an edit. To delete, prefer
- * {@link deleteComment} and {@link deleteThread} over {@link removeCommentRecords}: comments are
- * soft-deleted, and a synced server rejects the hard delete.
+ * Use it to seed or import threads, and to save an edit. To delete, prefer {@link deleteComment}
+ * and {@link deleteThread}: comments are soft-deleted, and a synced server rejects the hard delete.
  *
  * @public
  */
 export function putCommentRecords(editor: Editor, records: TLCommentRecord[]): void {
-	commitCommentMutation(editor, () => putRecordsInCommit(editor, records))
+	commitCommentMutation(editor, ({ put }) => put(records))
 }
 
 /**
  * Remove comment records from the store by id, under the configured
  * {@link CommentingOptions.history} behavior.
  *
- * This is a hard delete, which is rarely what you want for a comment or a thread: the built-in UI
- * soft-deletes them ({@link deleteComment}, {@link deleteThread}) so the server can prune the
- * records — including reactions, which belong to whoever left them rather than to the deleter. A
- * server that enforces per-record permissions will veto a hard delete outright. Reach for this on
- * a local, unsynced comment store, or to drop a reaction (which is a hard delete — see
- * {@link toggleCommentReaction}).
+ * This is a hard delete, which is rarely what you want: the built-in UI soft-deletes
+ * ({@link deleteComment}, {@link deleteThread}) so the server can prune the records, and a server
+ * enforcing per-record permissions vetoes a hard delete outright. Reach for this on a local,
+ * unsynced store, or to drop a reaction (see {@link toggleCommentReaction}).
  *
  * @public
  */
@@ -133,24 +158,19 @@ export function removeCommentRecords(
 	editor: Editor,
 	ids: (TLCommentId | TLCommentReactionId | TLCommentThreadId)[]
 ): void {
-	commitCommentMutation(editor, () => removeRecordsInCommit(editor, ids))
+	commitCommentMutation(editor, ({ remove }) => remove(ids))
 }
 
 /**
  * The record as the store currently holds it, or `undefined` if it isn't there any more.
  *
- * A verb is handed a record, but that record is a snapshot of whenever its caller got hold of one,
- * and a comment record moves underneath it. A thread's `anchor` and `pageId` are rewritten without
- * anyone touching the thread: deleting a pinned shape converts the anchor to a point, reparenting
- * one rehomes the thread to another page, a pin drag re-anchors it. Writing the caller's snapshot
- * back would put those fields as they were and sync the revert out to everyone.
- *
- * `put` is also an upsert, so a record a remote delete has already removed would come back — with
- * `isDeleted: false` on an edit or a resolve. That's the multiplayer surprise the schema warns
- * about (see `TLComment`), reached by a route the history option doesn't cover.
+ * A verb is handed a record, but that record is a snapshot and comment records move underneath it:
+ * deleting a pinned shape converts the anchor to a point, reparenting rehomes the thread, a drag
+ * re-anchors it. Writing the caller's snapshot back would revert those fields for everyone. `put`
+ * is also an upsert, so a record a remote delete already removed would come back.
  *
  * So a verb reads what it's changing rather than trusting what it was given, and a record that's
- * gone is a no-op: whatever the change was, there's nothing left for it to apply to.
+ * gone is a no-op.
  */
 function readLatest<T extends TLComment | TLCommentThread>(
 	editor: Editor,
@@ -162,15 +182,13 @@ function readLatest<T extends TLComment | TLCommentThread>(
 }
 
 /**
- * Replace a comment's body and stamp it as edited, which is what renders the "(edited)" marker on
- * its byline.
- *
- * Editing is the author's to do. The built-in UI only offers it on your own comments, and a server
- * that enforces per-record permissions rejects anyone else's edit.
+ * Replace a comment's body and stamp it as edited, which renders the "(edited)" marker on its
+ * byline. Editing is the author's to do by default ({@link CommentingOptions.canModifyComment}),
+ * and a server enforcing per-record permissions rejects anyone else's. Widening one end without the
+ * other leaves an edit that's offered and then rejected, so widen both.
  *
- * The `comment` you pass says which comment to edit; the body lands on the version the store
- * currently holds, so a copy you've held on to can't revert a change made since it, and can't
- * re-create a comment that's already been removed — editing one of those does nothing.
+ * The body lands on the version the store currently holds, so a stale copy can't revert a later
+ * change or re-create a removed comment — editing one of those does nothing.
  *
  * @example
  * ```ts
@@ -180,10 +198,10 @@ function readLatest<T extends TLComment | TLCommentThread>(
  * @public
  */
 export function editComment(editor: Editor, comment: TLComment, body: TLRichText): void {
-	commitCommentMutation(editor, () => {
+	commitCommentMutation(editor, ({ put }) => {
 		const current = readLatest(editor, comment)
 		if (!current) return
-		putRecordsInCommit(editor, [{ ...current, body, editedAt: Date.now() }])
+		put([{ ...current, body, editedAt: Date.now() }])
 	})
 }
 
@@ -191,16 +209,16 @@ export function editComment(editor: Editor, comment: TLComment, body: TLRichText
  * Mark a thread resolved, stamping who resolved it and when. Resolved threads keep their pin (a
  * checked one) and are hidden from the sidebar until its "show resolved" filter is on.
  *
- * Only the resolution is written: the rest of the thread is read fresh, so resolving with a stale
- * copy in hand won't drag a pin back to where it used to be. A no-op on a thread that's gone.
+ * Only the resolution is written — the rest of the thread is read fresh, so a stale copy can't drag
+ * a pin back. A no-op on a thread that's gone.
  *
  * @public
  */
 export function resolveThread(editor: Editor, thread: TLCommentThread, userId: string): void {
-	commitCommentMutation(editor, () => {
+	commitCommentMutation(editor, ({ put }) => {
 		const current = readLatest(editor, thread)
 		if (!current) return
-		putRecordsInCommit(editor, [{ ...current, resolved: { at: Date.now(), by: userId } }])
+		put([{ ...current, resolved: { at: Date.now(), by: userId } }])
 	})
 }
 
@@ -211,50 +229,45 @@ export function resolveThread(editor: Editor, thread: TLCommentThread, userId: s
  * @public
  */
 export function reopenThread(editor: Editor, thread: TLCommentThread): void {
-	commitCommentMutation(editor, () => {
+	commitCommentMutation(editor, ({ put }) => {
 		const current = readLatest(editor, thread)
 		if (!current) return
-		putRecordsInCommit(editor, [{ ...current, resolved: null }])
+		put([{ ...current, resolved: null }])
 	})
 }
 
 /**
  * Delete a comment.
  *
- * This is a soft delete: it sets the record's `isDeleted` flag rather than removing it, and the
- * server prunes the comment and its reactions once the flag is persisted. That way no client ever
- * removes records it doesn't own — a reaction belongs to whoever left it — and a server enforcing
- * per-record permissions has a write it can check rather than a deletion it can only refuse.
- * Deleting is the author's to do; the built-in UI only offers it on your own comments.
+ * This is a soft delete: it sets `isDeleted` rather than removing the record, and the server prunes
+ * the comment and its reactions once the flag is persisted — so no client removes records it
+ * doesn't own, and a server enforcing per-record permissions has a write it can check.
  *
- * The write is never undoable, whatever {@link CommentingOptions.history} says: the flag is
- * write-once server-side, so an undo clearing it would be vetoed and rebased rather than bring the
- * comment back.
+ * Deleting is the author's to do by default; {@link CommentingOptions.canModifyComment} widens
+ * that, as does its counterpart on the server.
  *
- * Deleting a thread's last comment leaves the thread with no surface — an empty thread renders
- * nothing — and closes it if it's open. The thread record is left for the server to prune, since
- * the deleter may not be its creator.
+ * Never undoable, whatever {@link CommentingOptions.history} says: the flag is write-once
+ * server-side, so an undo clearing it would be vetoed rather than bring the comment back.
  *
- * A comment that's already deleted, or already pruned, is a no-op.
+ * Deleting a thread's last comment closes it and leaves the thread record for the server to prune,
+ * since the deleter may not be its creator. An already-deleted comment is a no-op.
  *
  * @public
  */
 export function deleteComment(editor: Editor, comment: TLComment): void {
 	commitCommentMutation(
 		editor,
-		() => {
+		({ put }) => {
 			const current = readLatest(editor, comment)
-			// Deleting twice — a double activation, a handler firing on a copy taken before the first
-			// delete — is nothing to do rather than something to redo. The check below counts the
-			// comment being deleted among the live ones, so it only reads as "the last one" while
-			// this delete is the one taking it away.
+			// Deleting twice is nothing to do rather than something to redo. The check below counts this
+			// comment among the live ones, so it only reads as "the last one" while this delete takes it away.
 			if (!current || current.isDeleted) return
 			const isLastInThread =
 				getLiveComments(editor).filter((c) => c.threadId === current.threadId).length <= 1
 			if (isLastInThread && openThreadId.get(editor) === current.threadId) {
 				openThreadId.set(editor, null)
 			}
-			putRecordsInCommit(editor, [{ ...current, isDeleted: true }])
+			put([{ ...current, isDeleted: true }])
 		},
 		'delete'
 	)
@@ -263,25 +276,23 @@ export function deleteComment(editor: Editor, comment: TLComment): void {
 /**
  * Delete a thread and, with it, the whole conversation.
  *
- * A soft delete on the same model as {@link deleteComment}: the flag goes on the thread record and
- * the server prunes the thread, its comments, and their reactions once it's persisted. Deleting a
- * thread is its creator's to do — a server enforcing per-record permissions vetoes anyone else —
- * and the write is never undoable.
- *
- * Closes the thread if it's the open one. A thread that's already pruned is a no-op.
+ * A soft delete on the same model as {@link deleteComment}: the server prunes the thread, its
+ * comments, and their reactions once the flag is persisted. Deleting a thread is its creator's to
+ * do by default ({@link CommentingOptions.canModifyComment}), and the write is never undoable.
+ * Closes the thread if it's the open one; a pruned thread is a no-op.
  *
  * @public
  */
 export function deleteThread(editor: Editor, thread: TLCommentThread): void {
 	commitCommentMutation(
 		editor,
-		() => {
+		({ put }) => {
 			const current = readLatest(editor, thread)
 			if (!current) return
 			if (openThreadId.get(editor) === current.id) {
 				openThreadId.set(editor, null)
 			}
-			putRecordsInCommit(editor, [{ ...current, isDeleted: true }])
+			put([{ ...current, isDeleted: true }])
 		},
 		'delete'
 	)

package/src/canvas/comment-reactions.test.ts

@@ -87,6 +87,28 @@ describe('summarizeReactions', () => {
 	})
 })
 
+describe('summarizeReactions input', () => {
+	// the notifications panel tallies rows synced from the app database, which carry only the
+	// fields the tally needs — full TLCommentReaction records must not be required
+	it('accepts minimal rows with only userId, emoji, and createdAt', () => {
+		const rows = [
+			{ userId: 'user1', emoji: '👍', createdAt: 100 },
+			{ userId: 'user2', emoji: '👍', createdAt: 200 },
+		]
+		expect(summarizeReactions(rows, 'user1')).toEqual([
+			{
+				emoji: '👍',
+				count: 2,
+				active: true,
+				reactors: [
+					{ name: 'Someone', you: true },
+					{ name: 'Someone', you: false },
+				],
+			},
+		])
+	})
+})
+
 describe('createCommentReactionId', () => {
 	// the id is what makes reaction identity structural: re-picking the same emoji addresses the
 	// same record (toggle off), while a different emoji is its own record (independent)

package/src/canvas/comment-reactions.tsx

@@ -11,11 +11,7 @@ import {
 import { RenderReaction } from '../ui/reaction'
 import { ReactionPicker } from '../ui/reaction-picker'
 import { Reactions, ReactionSummary } from '../ui/reactions'
-import {
-	commitCommentMutation,
-	putRecordsInCommit,
-	removeRecordsInCommit,
-} from './comment-mutations'
+import { commitCommentMutation } from './comment-mutations'
 import { UNKNOWN_AUTHOR } from './comment-render'
 import { getCommentReactions } from './comment-store'
 import { getCommentingOptions, useCommentingOptions } from './options'
@@ -40,16 +36,28 @@ export function useCommentReactions(
 }
 
 /**
- * Tally a comment's reactions into an entry per emoji, ordered by when that emoji was first used
- * so the row stays stable as later reactions arrive. `active` marks the emoji the current user
- * reacted with (the pills render those highlighted), and `reactors` lists who reacted with it, in
- * reaction order, for the hover list. `resolveName` names each reactor; an id it can't name falls
- * back to the id itself.
+ * The reaction fields {@link summarizeReactions} needs — a structural subset of
+ * {@link tldraw#TLCommentReaction}, so tallies can also be built from rows synced outside the
+ * editor store.
+ *
+ * @public
+ */
+export interface ReactionSummaryInput {
+	userId: string
+	emoji: string
+	createdAt: number
+}
+
+/**
+ * Tally a comment's reactions into an entry per emoji, ordered by when that emoji was first used so
+ * the row stays stable as later reactions arrive. `active` marks the current user's emoji and
+ * `reactors` lists who reacted, in reaction order. `resolveName` names each reactor; an id it can't
+ * name falls back to a generic "Someone", never the raw user id.
  *
  * @public
  */
 export function summarizeReactions(
-	reactions: TLCommentReaction[],
+	reactions: readonly ReactionSummaryInput[],
 	currentUserId?: string | null,
 	resolveName?: (userId: string) => string | undefined
 ): ReactionSummary[] {
@@ -89,14 +97,12 @@ export function summarizeReactions(
 /**
  * Toggle one user's reaction with a given emoji on a comment.
  *
- * Each reaction is its own record keyed by (comment, user, emoji), so this only ever touches that
- * one user's own records — two people reacting at once never conflict. Behaviour depends on the
- * `allowMultipleReactions` option:
+ * Each reaction is its own record keyed by (comment, user, emoji), so this only touches that user's
+ * own records and two people reacting at once never conflict. Behaviour depends on
+ * `allowMultipleReactions`:
  *
- * - **multiple** (default): the emoji toggles independently — add it if absent, remove it if
- *   present, leaving the user's other reactions alone.
- * - **single**: picking a new emoji first removes the user's existing reaction(s) on the comment,
- *   then adds this one (a replace); picking the one they already have removes it.
+ * - **multiple** (default): the emoji toggles independently, leaving other reactions alone.
+ * - **single**: a new emoji replaces the user's existing reaction; the same one removes it.
  *
  * @public
  */
@@ -116,19 +122,16 @@ export function toggleCommentReaction(
 	// Only a token the configured palette allows may be added. Removals always go through — if a
 	// reaction somehow carries an off-palette token, the user must still be able to clear it.
 	if (!removing && !isAllowedReaction(emoji)) return
-	commitCommentMutation(editor, () => {
+	commitCommentMutation(editor, ({ put, remove }) => {
 		if (removing) {
-			removeRecordsInCommit(editor, [targetId])
+			remove([targetId])
 			return
 		}
 		// Single-select: a new emoji replaces the user's existing reaction(s) on this comment.
 		if (!allowMultipleReactions && mine.length > 0) {
-			removeRecordsInCommit(
-				editor,
-				mine.map((reaction) => reaction.id)
-			)
+			remove(mine.map((reaction) => reaction.id))
 		}
-		putRecordsInCommit(editor, [
+		put([
 			createCommentReaction({
 				commentId: comment.id,
 				threadId: comment.threadId,
@@ -147,14 +150,13 @@ export interface CommentReactionsProps {
 	/** The reacting user. Null/omitted gives a read-only row (signed out): counts show, but the
 	 *  pills don't toggle. */
 	currentUserId?: string | null
-	/** Names a reactor id for the hover list. Ids it can't name fall back to the id. */
+	/** Names a reactor id for the hover list. Ids it can't name fall back to a generic "Someone". */
 	resolveName?(userId: string): string | undefined
 }
 
 /**
- * Adapts the `ReactionContent` component override (if any) into a `renderReaction` function for the
- * presentational reaction components. Returns undefined when no override is set, so they fall back
- * to the default (the token string, drawn by the OS emoji font).
+ * Adapts the `ReactionContent` override into a `renderReaction` function for the presentational
+ * components. Undefined when no override is set, so they fall back to drawing the token string.
  */
 function useReactionRenderer(): RenderReaction | undefined {
 	const { components } = useCommentingOptions()
@@ -210,9 +212,8 @@ export interface CommentReactionPickerProps {
 }
 
 /**
- * The add-reaction button for one comment. Belongs with the comment card's hover actions (under
- * the ⋯ button) rather than in the reaction row, so opening it doesn't chase the row as reactions
- * are added.
+ * The add-reaction button for one comment. Belongs with the comment card's hover actions rather
+ * than in the reaction row, so opening it doesn't chase the row as reactions are added.
  * @public @react
  */
 export function CommentReactionPicker({

package/src/canvas/comment-render.ts

@@ -1,6 +1,6 @@
-import { generateHTML, generateText, JSONContent } from '@tiptap/core'
+import { generateText, JSONContent } from '@tiptap/core'
 import { type CommentAuthor, createMentionExtension } from '@tldraw/mentions'
-import { TLRichText } from 'tldraw'
+import { renderHtmlFromRichTextWithExtensions, TLRichText } from 'tldraw'
 import { commentTipTapExtensions, isCommentEmpty } from '../ui/comment-extensions'
 
 /**
@@ -44,9 +44,9 @@ const htmlCache = new WeakMap<TLRichText, string>()
 
 /**
  * Render a comment body to HTML through the limited comment extension set (no headings), so a body
- * always renders with comment formatting regardless of the host editor's rich-text config. Mirrors
- * tldraw's `renderHtmlFromRichText`, including the empty-paragraph fix that keeps blank lines from
- * collapsing. `resolveName` maps a member id to its current name for any @mentions.
+ * always renders with comment formatting regardless of the host editor's rich-text config. Renders
+ * through tldraw's shared helper, so it gets the same empty-paragraph fix that keeps blank lines
+ * from collapsing. `resolveName` maps a member id to its current name for any @mentions.
  */
 export function renderCommentHtml(
 	richText: TLRichText,
@@ -60,9 +60,9 @@ export function renderCommentHtml(
 	const extensions = mentions
 		? [...commentTipTapExtensions, createMentionExtension({ resolveName })]
 		: commentTipTapExtensions
-	const html = generateHTML(demoteHeadings(richText as JSONContent), extensions).replaceAll(
-		'<p dir="auto"></p>',
-		'<p><br /></p>'
+	const html = renderHtmlFromRichTextWithExtensions(
+		demoteHeadings(richText as JSONContent) as TLRichText,
+		extensions
 	)
 	if (!mentions) htmlCache.set(richText, html)
 	return html

package/src/canvas/comment-store.ts

@@ -3,15 +3,13 @@ import { Editor, TLComment, TLCommentReaction, TLCommentThread, TLRecord } from
 /**
  * Typed reads of comment records on the editor store.
  *
- * Comment threads and comments live on the editor's local store so the canvas can render them
- * reactively, but they are opt-in records that aren't part of the `TLRecord` union (they ride the
- * sync server's object-store lane on the wire — see `TLCommentThread`). `editor.store` is therefore
- * statically typed `Store<TLRecord>` and doesn't know about them, so every access has to reinterpret
- * the type. These helpers own that reinterpretation — an `unknown` hop to exactly the type the store
- * expects, so the rest of each call stays checked — behind one boundary, and keep call sites typed.
+ * Comment records live on the editor's local store so the canvas can render them reactively, but
+ * they're opt-in and aren't part of the `TLRecord` union — so `editor.store` is statically typed
+ * `Store<TLRecord>` and every access has to reinterpret the type. These helpers own that
+ * reinterpretation behind one boundary and keep call sites typed.
  *
- * Writes do the same reinterpretation, but they also answer to the undo/redo policy, so they live
- * with the rest of the write path in `comment-mutations.ts`.
+ * Writes do the same, but also answer to the undo/redo policy, so they live in
+ * `comment-mutations.ts`.
  */
 
 /**
@@ -36,9 +34,8 @@ export function getCommentRecord(editor: Editor, id: string): TLCommentRecord |
 }
 
 /**
- * Every comment thread in the store, **including soft-deleted ones** and ones left empty by their
- * last comment's delete — records that are still present but awaiting the server's prune, and that
- * nothing renders. For the set the UI shows, use {@link getLiveCommentThreads}.
+ * Every comment thread in the store, **including soft-deleted and emptied ones** awaiting the
+ * server's prune, which nothing renders. For the set the UI shows, use {@link getLiveCommentThreads}.
  *
  * Non-reactive; wrap in `useValue`, or use `useCommentThreads`, to react.
  * @public
@@ -62,8 +59,7 @@ export function getComments(editor: Editor): TLComment[] {
 
 /**
  * The comments that should render: not soft-deleted. A deleted record lingers in the store until
- * the server prunes it, so this — not {@link getComments} — is what a count or a list of your own
- * should be built from.
+ * the server prunes it, so build counts and lists from this rather than {@link getComments}.
  *
  * Non-reactive; the reactive equivalent is `useComments` (which also sorts oldest first).
  * @public
@@ -73,10 +69,9 @@ export function getLiveComments(editor: Editor): TLComment[] {
 }
 
 /**
- * The comment threads that should render (pins, sidebar): live — not soft-deleted — and still
- * holding at least one live comment. A soft-deleted thread or comment is awaiting the server's
- * prune, as is a thread emptied by its last comment's delete; until the prune lands, the emptied
- * thread record lingers with no surface.
+ * The comment threads that should render (pins, sidebar): not soft-deleted, and still holding at
+ * least one live comment. A thread emptied by its last comment's delete lingers with no surface
+ * until the server's prune lands.
  *
  * Non-reactive; the reactive equivalent is `useCommentThreads`.
  * @public