@tldraw/commenting 5.5.0-next.9665a55b2322 → 5.5.0-next.b6a9f7cd7be2

package/dist-esm/ui/reaction.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/ui/reaction.tsx"],
-  "sourcesContent": ["import { ComponentType, ReactNode } from 'react'\nimport { TldrawUiTooltip, useTranslation } from 'tldraw'\nimport { ReactionReactor } from './reactions'\n\n/** Render a reaction token to its visual \u2014 the emoji glyph by default. @public */\nexport type RenderReaction = (token: string) => ReactNode\n\n/** The default reaction renderer: emits the token string for the OS emoji font to draw. @public */\nexport function defaultRenderReaction(token: string): ReactNode {\n\treturn token\n}\n\n/** @public */\nexport interface ReactionProps {\n\temoji: string\n\tcount: number\n\tactive: boolean\n\t/** How to draw the emoji token. Defaults to the token string (OS emoji font). */\n\trenderReaction?: RenderReaction\n\t/** Who reacted with this emoji, in reaction order \u2014 shown when the pill is hovered. */\n\treactors: ReactionReactor[]\n\t/** Whether hovering shows the reactor list. Pass false to suppress it \u2014 e.g. while another\n\t *  popup menu on the comment is open. Defaults to true. */\n\tenableHoverList?: boolean\n\t/** The hover affordance for the pill, naming who reacted. It receives the reactors and the pill\n\t *  itself (as `children`) and returns the whole thing \u2014 so it owns the tooltip, its box, size,\n\t *  shape, and position, not just the text inside. Defaults to `DefaultReactionTooltip`, which\n\t *  hangs the built-in inline sentence below the pill. */\n\tReactionTooltip?: ComponentType<ReactionTooltipProps>\n\t/** Called when the pill is pressed \u2014 toggles the current user's reaction. */\n\tonClick?(): void\n}\n\n/**\n * A single emoji reaction pill with a count, highlighted when the user reacted. Hovering it shows a\n * tooltip naming who reacted (the current user included), when `enableHoverList` is set.\n * @public @react\n */\nexport function Reaction({\n\temoji,\n\tcount,\n\tactive,\n\treactors,\n\tenableHoverList = true,\n\trenderReaction = defaultRenderReaction,\n\tReactionTooltip = DefaultReactionTooltip,\n\tonClick,\n}: ReactionProps) {\n\t// An inert pill (no handler) is plain content, not a control \u2014 rendering it as a span keeps it\n\t// valid inside an anchor row (e.g. a notification list item) and out of the tab order.\n\tconst Tag = onClick ? 'button' : 'span'\n\tconst pill = (\n\t\t<Tag\n\t\t\tclassName={active ? 'tlui-cmt-reaction tlui-cmt-reaction--active' : 'tlui-cmt-reaction'}\n\t\t\t{...(onClick\n\t\t\t\t? { type: 'button' as const, 'aria-pressed': active, onClick }\n\t\t\t\t: { role: 'img' as const })}\n\t\t\t// The emoji alone announces as its unicode name (\"thumbs up\"); pairing it with the count\n\t\t\t// is what makes the pill's state legible to a screen reader. The inert span needs the\n\t\t\t// img role for the label to be announced at all.\n\t\t\taria-label={`${emoji} ${count}`}\n\t\t>\n\t\t\t<span className=\"tlui-cmt-reaction__emoji\">{renderReaction(emoji)}</span>\n\t\t\t<span className=\"tlui-cmt-reaction__count\">{count}</span>\n\t\t</Tag>\n\t)\n\n\t// A bare pill when hovering is suppressed, or when there's no one to name.\n\tif (!enableHoverList || reactors.length === 0) return pill\n\n\t// Hand the whole hover affordance to the tooltip component: it wraps the pill and owns how the\n\t// reactor list is presented.\n\treturn <ReactionTooltip reactors={reactors}>{pill}</ReactionTooltip>\n}\n\n/** @public */\nexport interface ReactionTooltipProps {\n\t/** Who reacted with this emoji, in reaction order. */\n\treactors: ReactionReactor[]\n\t/** The reaction pill to wrap. Anchor the hover affordance to this and render it. */\n\tchildren: ReactNode\n}\n\n/**\n * The default reactor tooltip: hangs the built-in inline sentence (`DefaultReactionTooltipContent`)\n * in a standard tooltip below the pill \u2014 the same tooltip the toolbar uses. Replace it via\n * `CommentingComponents.ReactionTooltip` to present the reactor list any other way (a different box,\n * avatars, a banner, anywhere on screen); it receives the pill as `children`.\n * @public @react\n */\nexport function DefaultReactionTooltip({ reactors, children }: ReactionTooltipProps) {\n\treturn (\n\t\t<TldrawUiTooltip side=\"bottom\" content={<DefaultReactionTooltipContent reactors={reactors} />}>\n\t\t\t{children}\n\t\t</TldrawUiTooltip>\n\t)\n}\n\n/**\n * The default reactor sentence naming who reacted \u2014 up to three names spelled out, then \"and N\n * others\" (e.g. \"You reacted\", \"You and Bo reacted\", \"You, Bo and Ada reacted\", \"You, Bo, Ada and 2\n * others reacted\"). The wording lives in the `comments.reacted-*` translation strings so each locale\n * controls the grammar. Exported so a custom `ReactionTooltip` can reuse it inside its own box.\n * @public @react\n */\nexport function DefaultReactionTooltipContent({ reactors }: { reactors: ReactionReactor[] }) {\n\tconst msg = useTranslation()\n\tconst names = reactors.map((reactor) =>\n\t\treactor.you ? msg('comments.mention-you') : reactor.name\n\t)\n\tconst [a, b, c] = names\n\tswitch (names.length) {\n\t\tcase 0:\n\t\t\treturn null\n\t\tcase 1:\n\t\t\treturn <>{msg('comments.reacted-1').replace('{a}', a)}</>\n\t\tcase 2:\n\t\t\treturn <>{msg('comments.reacted-2').replace('{a}', a).replace('{b}', b)}</>\n\t\tcase 3:\n\t\t\treturn <>{msg('comments.reacted-3').replace('{a}', a).replace('{b}', b).replace('{c}', c)}</>\n\t\tdefault: {\n\t\t\tconst others = names.length - 3\n\t\t\tconst template = others === 1 ? 'comments.reacted-more-one' : 'comments.reacted-more'\n\t\t\treturn (\n\t\t\t\t<>\n\t\t\t\t\t{msg(template)\n\t\t\t\t\t\t.replace('{a}', a)\n\t\t\t\t\t\t.replace('{b}', b)\n\t\t\t\t\t\t.replace('{c}', c)\n\t\t\t\t\t\t.replace('{count}', String(others))}\n\t\t\t\t</>\n\t\t\t)\n\t\t}\n\t}\n}\n"],
-  "mappings": "AAoDE,SA+DQ,UArDP,KAVD;AAnDF,SAAS,iBAAiB,sBAAsB;AAOzC,SAAS,sBAAsB,OAA0B;AAC/D,SAAO;AACR;AA4BO,SAAS,SAAS;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAkB;AAAA,EAClB,iBAAiB;AAAA,EACjB,kBAAkB;AAAA,EAClB;AACD,GAAkB;AAGjB,QAAM,MAAM,UAAU,WAAW;AACjC,QAAM,OACL;AAAA,IAAC;AAAA;AAAA,MACA,WAAW,SAAS,gDAAgD;AAAA,MACnE,GAAI,UACF,EAAE,MAAM,UAAmB,gBAAgB,QAAQ,QAAQ,IAC3D,EAAE,MAAM,MAAe;AAAA,MAI1B,cAAY,GAAG,KAAK,IAAI,KAAK;AAAA,MAE7B;AAAA,4BAAC,UAAK,WAAU,4BAA4B,yBAAe,KAAK,GAAE;AAAA,QAClE,oBAAC,UAAK,WAAU,4BAA4B,iBAAM;AAAA;AAAA;AAAA,EACnD;AAID,MAAI,CAAC,mBAAmB,SAAS,WAAW,EAAG,QAAO;AAItD,SAAO,oBAAC,mBAAgB,UAAqB,gBAAK;AACnD;AAiBO,SAAS,uBAAuB,EAAE,UAAU,SAAS,GAAyB;AACpF,SACC,oBAAC,mBAAgB,MAAK,UAAS,SAAS,oBAAC,iCAA8B,UAAoB,GACzF,UACF;AAEF;AASO,SAAS,8BAA8B,EAAE,SAAS,GAAoC;AAC5F,QAAM,MAAM,eAAe;AAC3B,QAAM,QAAQ,SAAS;AAAA,IAAI,CAAC,YAC3B,QAAQ,MAAM,IAAI,sBAAsB,IAAI,QAAQ;AAAA,EACrD;AACA,QAAM,CAAC,GAAG,GAAG,CAAC,IAAI;AAClB,UAAQ,MAAM,QAAQ;AAAA,IACrB,KAAK;AACJ,aAAO;AAAA,IACR,KAAK;AACJ,aAAO,gCAAG,cAAI,oBAAoB,EAAE,QAAQ,OAAO,CAAC,GAAE;AAAA,IACvD,KAAK;AACJ,aAAO,gCAAG,cAAI,oBAAoB,EAAE,QAAQ,OAAO,CAAC,EAAE,QAAQ,OAAO,CAAC,GAAE;AAAA,IACzE,KAAK;AACJ,aAAO,gCAAG,cAAI,oBAAoB,EAAE,QAAQ,OAAO,CAAC,EAAE,QAAQ,OAAO,CAAC,EAAE,QAAQ,OAAO,CAAC,GAAE;AAAA,IAC3F,SAAS;AACR,YAAM,SAAS,MAAM,SAAS;AAC9B,YAAM,WAAW,WAAW,IAAI,8BAA8B;AAC9D,aACC,gCACE,cAAI,QAAQ,EACX,QAAQ,OAAO,CAAC,EAChB,QAAQ,OAAO,CAAC,EAChB,QAAQ,OAAO,CAAC,EAChB,QAAQ,WAAW,OAAO,MAAM,CAAC,GACpC;AAAA,IAEF;AAAA,EACD;AACD;",
+  "sourcesContent": ["import { ComponentType, ReactNode } from 'react'\nimport { TldrawUiTooltip, useTranslation } from 'tldraw'\nimport { ReactionReactor } from './reactions'\n\n/** Render a reaction token to its visual \u2014 the emoji glyph by default. @public */\nexport type RenderReaction = (token: string) => ReactNode\n\n/** The default reaction renderer: emits the token string for the OS emoji font to draw. @public */\nexport function defaultRenderReaction(token: string): ReactNode {\n\treturn token\n}\n\n/** @public */\nexport interface ReactionProps {\n\temoji: string\n\tcount: number\n\tactive: boolean\n\t/** How to draw the emoji token. Defaults to the token string (OS emoji font). */\n\trenderReaction?: RenderReaction\n\t/** Who reacted with this emoji, in reaction order \u2014 shown when the pill is hovered. */\n\treactors: ReactionReactor[]\n\t/** Whether hovering shows the reactor list. Pass false to suppress it \u2014 e.g. while another\n\t *  popup menu on the comment is open. Defaults to true. */\n\tenableHoverList?: boolean\n\t/** The hover affordance for the pill, naming who reacted. It receives the reactors and the pill\n\t *  itself (as `children`) and returns the whole thing \u2014 so it owns the tooltip, its box, size,\n\t *  shape, and position, not just the text inside. Defaults to `DefaultReactionTooltip`, which\n\t *  hangs the built-in inline sentence below the pill. */\n\tReactionTooltip?: ComponentType<ReactionTooltipProps>\n\t/** Called when the pill is pressed \u2014 toggles the current user's reaction. */\n\tonClick?(): void\n}\n\n/**\n * A single emoji reaction pill with a count, highlighted when the user reacted. Hovering it shows a\n * tooltip naming who reacted (the current user included), when `enableHoverList` is set.\n * @public @react\n */\nexport function Reaction({\n\temoji,\n\tcount,\n\tactive,\n\treactors,\n\tenableHoverList = true,\n\trenderReaction = defaultRenderReaction,\n\tReactionTooltip = DefaultReactionTooltip,\n\tonClick,\n}: ReactionProps) {\n\t// An inert pill (no handler) is plain content, not a control \u2014 rendering it as a span keeps it\n\t// valid inside an anchor row (e.g. a notification list item) and out of the tab order.\n\tconst Tag = onClick ? 'button' : 'span'\n\tconst pill = (\n\t\t<Tag\n\t\t\tclassName={active ? 'tlui-cmt-reaction tlui-cmt-reaction--active' : 'tlui-cmt-reaction'}\n\t\t\t{...(onClick\n\t\t\t\t? { type: 'button' as const, 'aria-pressed': active, onClick }\n\t\t\t\t: { role: 'img' as const })}\n\t\t\t// The emoji alone announces as its unicode name (\"thumbs up\"); pairing it with the count\n\t\t\t// is what makes the pill's state legible to a screen reader. The inert span needs the\n\t\t\t// img role for the label to be announced at all.\n\t\t\taria-label={`${emoji} ${count}`}\n\t\t>\n\t\t\t<span className=\"tlui-cmt-reaction__emoji\">{renderReaction(emoji)}</span>\n\t\t\t<span className=\"tlui-cmt-reaction__count\">{count}</span>\n\t\t</Tag>\n\t)\n\n\t// A bare pill when hovering is suppressed, or when there's no one to name.\n\tif (!enableHoverList || reactors.length === 0) return pill\n\n\t// Hand the whole hover affordance to the tooltip component: it wraps the pill and owns how the\n\t// reactor list is presented.\n\treturn <ReactionTooltip reactors={reactors}>{pill}</ReactionTooltip>\n}\n\n/** @public */\nexport interface ReactionTooltipProps {\n\t/** Who reacted with this emoji, in reaction order. */\n\treactors: ReactionReactor[]\n\t/** The reaction pill to wrap. Anchor the hover affordance to this and render it. */\n\tchildren: ReactNode\n}\n\n/**\n * The default reactor tooltip: hangs the built-in inline sentence (`DefaultReactionTooltipContent`)\n * in a standard tooltip below the pill \u2014 the same tooltip the toolbar uses. Replace it via\n * `CommentingComponents.ReactionTooltip` to present the reactor list any other way (a different box,\n * avatars, a banner, anywhere on screen); it receives the pill as `children`.\n * @public @react\n */\nexport function DefaultReactionTooltip({ reactors, children }: ReactionTooltipProps) {\n\treturn (\n\t\t<TldrawUiTooltip side=\"bottom\" content={<DefaultReactionTooltipContent reactors={reactors} />}>\n\t\t\t{children}\n\t\t</TldrawUiTooltip>\n\t)\n}\n\n/**\n * The default reactor sentence naming who reacted \u2014 up to three names spelled out, then \"and N\n * others\" (e.g. \"You reacted\", \"You and Bo reacted\", \"You, Bo and Ada reacted\", \"You, Bo, Ada and 2\n * others reacted\"). The wording lives in the `comments.reacted-*` translation strings so each locale\n * controls the grammar. Exported so a custom `ReactionTooltip` can reuse it inside its own box.\n * @public @react\n */\nexport function DefaultReactionTooltipContent({ reactors }: { reactors: ReactionReactor[] }) {\n\tconst msg = useTranslation()\n\tconst names = reactors.map((reactor) =>\n\t\treactor.you ? msg('comments.mention-you') : reactor.name\n\t)\n\tif (names.length === 0) return null\n\tconst [a, b, c] = names\n\tconst others = names.length - 3\n\tconst key =\n\t\tnames.length <= 3\n\t\t\t? `comments.reacted-${names.length}`\n\t\t\t: others === 1\n\t\t\t\t? 'comments.reacted-more-one'\n\t\t\t\t: 'comments.reacted-more'\n\t// Single pass, so a substituted name containing a placeholder can't be re-substituted.\n\tconst vars: Record<string, string | undefined> = { a, b, c, count: String(others) }\n\treturn <>{msg(key).replace(/\\{(a|b|c|count)\\}/g, (_, k) => vars[k] ?? '')}</>\n}\n"],
+  "mappings": "AAoDE,SAqEM,UA3DL,KAVD;AAnDF,SAAS,iBAAiB,sBAAsB;AAOzC,SAAS,sBAAsB,OAA0B;AAC/D,SAAO;AACR;AA4BO,SAAS,SAAS;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAkB;AAAA,EAClB,iBAAiB;AAAA,EACjB,kBAAkB;AAAA,EAClB;AACD,GAAkB;AAGjB,QAAM,MAAM,UAAU,WAAW;AACjC,QAAM,OACL;AAAA,IAAC;AAAA;AAAA,MACA,WAAW,SAAS,gDAAgD;AAAA,MACnE,GAAI,UACF,EAAE,MAAM,UAAmB,gBAAgB,QAAQ,QAAQ,IAC3D,EAAE,MAAM,MAAe;AAAA,MAI1B,cAAY,GAAG,KAAK,IAAI,KAAK;AAAA,MAE7B;AAAA,4BAAC,UAAK,WAAU,4BAA4B,yBAAe,KAAK,GAAE;AAAA,QAClE,oBAAC,UAAK,WAAU,4BAA4B,iBAAM;AAAA;AAAA;AAAA,EACnD;AAID,MAAI,CAAC,mBAAmB,SAAS,WAAW,EAAG,QAAO;AAItD,SAAO,oBAAC,mBAAgB,UAAqB,gBAAK;AACnD;AAiBO,SAAS,uBAAuB,EAAE,UAAU,SAAS,GAAyB;AACpF,SACC,oBAAC,mBAAgB,MAAK,UAAS,SAAS,oBAAC,iCAA8B,UAAoB,GACzF,UACF;AAEF;AASO,SAAS,8BAA8B,EAAE,SAAS,GAAoC;AAC5F,QAAM,MAAM,eAAe;AAC3B,QAAM,QAAQ,SAAS;AAAA,IAAI,CAAC,YAC3B,QAAQ,MAAM,IAAI,sBAAsB,IAAI,QAAQ;AAAA,EACrD;AACA,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,QAAM,CAAC,GAAG,GAAG,CAAC,IAAI;AAClB,QAAM,SAAS,MAAM,SAAS;AAC9B,QAAM,MACL,MAAM,UAAU,IACb,oBAAoB,MAAM,MAAM,KAChC,WAAW,IACV,8BACA;AAEL,QAAM,OAA2C,EAAE,GAAG,GAAG,GAAG,OAAO,OAAO,MAAM,EAAE;AAClF,SAAO,gCAAG,cAAI,GAAG,EAAE,QAAQ,sBAAsB,CAAC,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,GAAE;AAC3E;",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/commenting",
   "description": "tldraw commenting UI components.",
-  "version": "5.5.0-next.9665a55b2322",
+  "version": "5.5.0-next.b6a9f7cd7be2",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -46,12 +46,12 @@
     "lint": "yarn run -T tsx ../../internal/scripts/lint.ts"
   },
   "devDependencies": {
-    "@tldraw/driver": "5.5.0-next.9665a55b2322",
+    "@tldraw/driver": "5.5.0-next.b6a9f7cd7be2",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
-    "vitest": "^4.1.7"
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.2.1",
@@ -64,9 +64,9 @@
     "@tiptap/core": "^3.12.1",
     "@tiptap/pm": "^3.12.1",
     "@tiptap/react": "^3.12.1",
-    "@tldraw/mentions": "5.5.0-next.9665a55b2322",
-    "@tldraw/utils": "5.5.0-next.9665a55b2322",
-    "tldraw": "5.5.0-next.9665a55b2322"
+    "@tldraw/mentions": "5.5.0-next.b6a9f7cd7be2",
+    "@tldraw/utils": "5.5.0-next.b6a9f7cd7be2",
+    "tldraw": "5.5.0-next.b6a9f7cd7be2"
   },
   "module": "dist-esm/index.mjs",
   "source": "src/index.ts",

package/src/canvas/anchor-lifecycle.ts

@@ -1,7 +1,7 @@
 import { WeakCache } from '@tldraw/utils'
 import { Editor, TLCommentAnchor, TLCommentThread, TLPageId, TLShapeId, VecLike } from 'tldraw'
 import { commitCommentMutation } from './comment-mutations'
-import { getCommentRecord, getComments, getCommentThreads, TLCommentRecord } from './comment-store'
+import { getComments, getCommentThread, getCommentThreads, TLCommentRecord } from './comment-store'
 import { anchorPagePoint, impreciseShapePinInset } from './thread-state'
 
 type ShapeAnchor = Extract<TLCommentAnchor, { type: 'shape' }>
@@ -108,9 +108,8 @@ export function registerCommentAnchorLifecycle(editor: Editor): () => void {
 			if (editor.getShape(shapeId)) continue
 			for (const [threadId, point] of threadPoints) {
 				if (!point) continue
-				const thread = getCommentRecord(editor, threadId)
-				if (!thread || thread.typeName !== 'comment-thread') continue
-				if (!isAnchoredToShape(thread, shapeId)) continue
+				const thread = getCommentThread(editor, threadId)
+				if (!thread || !isAnchoredToShape(thread, shapeId)) continue
 				let converted = convertedByShape.get(shapeId)
 				if (!converted) {
 					converted = []
@@ -130,8 +129,8 @@ export function registerCommentAnchorLifecycle(editor: Editor): () => void {
 
 			const pageId = editor.getAncestorPageId(shape)
 			for (const { threadId, anchor, point } of converted) {
-				const thread = getCommentRecord(editor, threadId)
-				if (!thread || thread.typeName !== 'comment-thread') continue
+				const thread = getCommentThread(editor, threadId)
+				if (!thread) continue
 				// Re-attach only threads still sitting exactly where the conversion left them — a
 				// pin moved since then was placed deliberately, and that placement wins.
 				const current = thread.anchor

package/src/canvas/cluster-fade.ts

@@ -78,14 +78,14 @@ function reconcileFadeNodes(
 
 	for (const node of nextNodes) {
 		const previousItem = previousById.get(node.id)
+		// A node that was fading out and came back snaps to present rather than re-entering.
 		next.push({
 			node,
-			phase:
-				previousItem && previousItem.phase !== 'exiting'
-					? previousItem.phase
-					: previousItem
-						? 'present'
-						: 'entering',
+			phase: !previousItem
+				? 'entering'
+				: previousItem.phase === 'exiting'
+					? 'present'
+					: previousItem.phase,
 		})
 	}
 

package/src/canvas/cluster-model.ts

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
-import { Editor, react, TLCommentThread, useValue } from 'tldraw'
+import { clamp, Editor, react, TLCommentThread, useValue } from 'tldraw'
 import { computeClusterTable } from '../clustering/computeClusterTable'
 import { type ClusterRuntime, createClusterRuntime } from '../clustering/runtime'
 import type { ClusterNode, ClusterTable, MergeEvent } from '../clustering/types'
@@ -169,11 +169,14 @@ export function useClusterModel(
 		for (const id of newlyMovedIds) next.add(id)
 		setHeldThreadIds(next)
 	}
+	const latestLeafIds = useMemo(
+		() => new Set(latestModel.table.leaves.map((leaf) => leaf.id)),
+		[latestModel]
+	)
 	// Local partition maintenance — the only non-zoom visual change. Any displayed leaf that has left the
 	// cluster input is detached from its badge in place; the corrected rebuild already sits in latestModel
 	// awaiting the next zoom-out. When the two models match, the leaf sets are identical, so skip the scan.
 	if (clusterModel !== latestModel) {
-		const latestLeafIds = new Set(latestModel.table.leaves.map((leaf) => leaf.id))
 		const removedLeafIds: string[] = []
 		for (const leaf of clusterModel.table.leaves) {
 			if (!latestLeafIds.has(leaf.id)) {
@@ -188,12 +191,7 @@ export function useClusterModel(
 	// never folds pins into clusters — merging is a zoom-out-only move, matching the runtime.
 	useEffect(() => {
 		if (heldThreadIds.size === 0) return
-		let lastZoom = editor.getZoomLevel()
-		return react('rejoin moved comment pins on zoom out', () => {
-			const zoom = editor.getZoomLevel()
-			const prevZoom = lastZoom
-			lastZoom = zoom
-			if (zoom >= prevZoom) return
+		return reactOnZoomOut(editor, 'rejoin moved comment pins on zoom out', () => {
 			adoptOnRebuild.current = true
 			setHeldThreadIds(EMPTY_SET)
 		})
@@ -203,12 +201,7 @@ export function useClusterModel(
 	// splits correctly on its own (split thresholds are direction-safe by the hysteresis invariant).
 	useEffect(() => {
 		if (clusterModel === latestModel) return
-		let lastZoom = editor.getZoomLevel()
-		return react('adopt pending cluster model on zoom out', () => {
-			const zoom = editor.getZoomLevel()
-			const prevZoom = lastZoom
-			lastZoom = zoom
-			if (zoom >= prevZoom) return
+		return reactOnZoomOut(editor, 'adopt pending cluster model on zoom out', (zoom) => {
 			latestModel.runtime.seedFrom(zoom, clusterModel.runtime.getVisible())
 			setRenderedModel(latestModel)
 		})
@@ -223,11 +216,10 @@ export function useClusterModel(
 		for (const node of clusterModel.runtime.getVisible().values()) {
 			for (const member of node.members) displayed.add(member)
 		}
-		const latestIds = new Set(latestModel.table.leaves.map((leaf) => leaf.id))
-		return threads.filter((thread) => latestIds.has(thread.id) && !displayed.has(thread.id))
+		return threads.filter((thread) => latestLeafIds.has(thread.id) && !displayed.has(thread.id))
 		// The runtime mutates its partition in place; partitionVersion is its change stamp.
 		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [clusterModel, latestModel, threads, partitionVersion])
+	}, [clusterModel, latestModel, latestLeafIds, threads, partitionVersion])
 	const heldThreads = useMemo(
 		() => threads.filter((thread) => heldThreadIds.has(thread.id) && thread.id !== openId),
 		[threads, heldThreadIds, openId]
@@ -259,6 +251,17 @@ export function useClusterModel(
 	}
 }
 
+/** Run `onZoomOut` on each zoom change that decreased the zoom, starting from the current level. */
+function reactOnZoomOut(editor: Editor, name: string, onZoomOut: (zoom: number) => void) {
+	let lastZoom = editor.getZoomLevel()
+	return react(name, () => {
+		const zoom = editor.getZoomLevel()
+		const prevZoom = lastZoom
+		lastZoom = zoom
+		if (zoom < prevZoom) onZoomOut(zoom)
+	})
+}
+
 /**
  * Whether a position-only input change (ids equal, same order) moved a leaf folded inside a badge
  * of the rendered partition — the one move the mid-drag freeze must let through.
@@ -358,12 +361,7 @@ export function revealThreadPin(
 			Number.isFinite(parentEvent.zSplit) &&
 			parentEvent.zSplit <= zoomBounds.maxZoom
 		) {
-			const zoom = clamp(
-				parentEvent.zSplit * CLUSTER_SPLIT_ZOOM_FACTOR,
-				zoomBounds.minZoom,
-				zoomBounds.maxZoom
-			)
-			centerOnPointAtZoom(editor, point, zoom, duration)
+			centerOnPointAtZoom(editor, point, splitZoom(parentEvent, zoomBounds), duration)
 			return
 		}
 	}
@@ -386,12 +384,12 @@ export function zoomToClusterSplit(
 ) {
 	const event = table.events.find((e) => e.result.id === node.id)
 	if (!event || !Number.isFinite(event.zSplit)) return
-	const zoom = clamp(
-		event.zSplit * CLUSTER_SPLIT_ZOOM_FACTOR,
-		zoomBounds.minZoom,
-		zoomBounds.maxZoom
-	)
-	centerOnPointAtZoom(editor, node.centroid, zoom, CLUSTER_EXPAND_ZOOM_MS)
+	centerOnPointAtZoom(editor, node.centroid, splitZoom(event, zoomBounds), CLUSTER_EXPAND_ZOOM_MS)
+}
+
+/** The zoom to land on to see a merge event's cluster just after it splits. */
+function splitZoom(event: MergeEvent, zoomBounds: ClusterZoomBounds): number {
+	return clamp(event.zSplit * CLUSTER_SPLIT_ZOOM_FACTOR, zoomBounds.minZoom, zoomBounds.maxZoom)
 }
 
 function findDirectParentEvent(table: ClusterTable, threadId: string): MergeEvent | undefined {
@@ -416,7 +414,3 @@ function centerOnPointAtZoom(
 		{ animation: { duration } }
 	)
 }
-
-function clamp(value: number, min: number, max: number): number {
-	return Math.max(min, Math.min(max, value))
-}

package/src/canvas/comment-render.ts

@@ -1,4 +1,4 @@
-import { generateText, JSONContent } from '@tiptap/core'
+import { type Extensions, generateText, JSONContent } from '@tiptap/core'
 import { type CommentAuthor, createMentionExtension } from '@tldraw/mentions'
 import { renderHtmlFromRichTextWithExtensions, TLRichText } from 'tldraw'
 import { commentTipTapExtensions, isCommentEmpty } from '../ui/comment-extensions'
@@ -41,34 +41,46 @@ function hasMention(node: JSONContent): boolean {
 }
 
 const htmlCache = new WeakMap<TLRichText, string>()
+const textCache = 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. 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.
+ * Render a body through the comment extension set, memoized by body identity in `cache` unless the
+ * body carries a mention (see {@link hasMention}), in which case the mention extension resolving
+ * `resolveName` is added and nothing is cached.
  */
-export function renderCommentHtml(
+function renderWithCommentExtensions(
+	cache: WeakMap<TLRichText, string>,
 	richText: TLRichText,
-	resolveName?: (id: string) => string | undefined
+	resolveName: ((id: string) => string | undefined) | undefined,
+	render: (doc: JSONContent, extensions: Extensions) => string
 ): string {
 	const mentions = hasMention(richText as JSONContent)
 	if (!mentions) {
-		const cached = htmlCache.get(richText)
+		const cached = cache.get(richText)
 		if (cached !== undefined) return cached
 	}
 	const extensions = mentions
 		? [...commentTipTapExtensions, createMentionExtension({ resolveName })]
 		: commentTipTapExtensions
-	const html = renderHtmlFromRichTextWithExtensions(
-		demoteHeadings(richText as JSONContent) as TLRichText,
-		extensions
-	)
-	if (!mentions) htmlCache.set(richText, html)
-	return html
+	const result = render(demoteHeadings(richText as JSONContent), extensions)
+	if (!mentions) cache.set(richText, result)
+	return result
 }
 
-const textCache = 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. 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,
+	resolveName?: (id: string) => string | undefined
+): string {
+	return renderWithCommentExtensions(htmlCache, richText, resolveName, (doc, extensions) =>
+		renderHtmlFromRichTextWithExtensions(doc as TLRichText, extensions)
+	)
+}
 
 /**
  * Flatten a comment body to plaintext through the limited comment extension set — paragraphs and
@@ -80,17 +92,7 @@ export function renderCommentPlaintext(
 	resolveName?: (id: string) => string | undefined
 ): string {
 	if (isCommentEmpty(richText)) return ''
-	const mentions = hasMention(richText as JSONContent)
-	if (!mentions) {
-		const cached = textCache.get(richText)
-		if (cached !== undefined) return cached
-	}
-	const extensions = mentions
-		? [...commentTipTapExtensions, createMentionExtension({ resolveName })]
-		: commentTipTapExtensions
-	const text = generateText(demoteHeadings(richText as JSONContent), extensions, {
-		blockSeparator: '\n',
-	})
-	if (!mentions) textCache.set(richText, text)
-	return text
+	return renderWithCommentExtensions(textCache, richText, resolveName, (doc, extensions) =>
+		generateText(doc, extensions, { blockSeparator: '\n' })
+	)
 }

package/src/canvas/comment-store.ts

@@ -33,6 +33,12 @@ export function getCommentRecord(editor: Editor, id: string): TLCommentRecord |
 	return undefined
 }
 
+/** Read one comment thread by id, or `undefined` if the id isn't a present thread. @internal */
+export function getCommentThread(editor: Editor, id: string): TLCommentThread | undefined {
+	const record = getCommentRecord(editor, id)
+	return record?.typeName === 'comment-thread' ? record : undefined
+}
+
 /**
  * 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}.
@@ -41,8 +47,7 @@ export function getCommentRecord(editor: Editor, id: string): TLCommentRecord |
  * @public
  */
 export function getCommentThreads(editor: Editor): TLCommentThread[] {
-	const typeName = 'comment-thread' as TLRecord['typeName']
-	return editor.store.query.records(typeName).get() as unknown as TLCommentThread[]
+	return queryCommentRecords<TLCommentThread>(editor, 'comment-thread')
 }
 
 /**
@@ -53,8 +58,7 @@ export function getCommentThreads(editor: Editor): TLCommentThread[] {
  * @public
  */
 export function getComments(editor: Editor): TLComment[] {
-	const typeName = 'comment' as TLRecord['typeName']
-	return editor.store.query.records(typeName).get() as unknown as TLComment[]
+	return queryCommentRecords<TLComment>(editor, 'comment')
 }
 
 /**
@@ -85,6 +89,12 @@ export function getLiveCommentThreads(editor: Editor): TLCommentThread[] {
 
 /** All comment reactions currently in the store (non-reactive; wrap in `useValue` to react). @public */
 export function getCommentReactions(editor: Editor): TLCommentReaction[] {
-	const typeName = 'comment-reaction' as TLRecord['typeName']
-	return editor.store.query.records(typeName).get() as unknown as TLCommentReaction[]
+	return queryCommentRecords<TLCommentReaction>(editor, 'comment-reaction')
+}
+
+function queryCommentRecords<T extends TLCommentRecord>(
+	editor: Editor,
+	typeName: T['typeName']
+): T[] {
+	return editor.store.query.records(typeName as TLRecord['typeName']).get() as unknown as T[]
 }

package/src/canvas/comments-overlay.tsx

@@ -11,7 +11,7 @@ import {
 	useClusterModel,
 	zoomToClusterSplit,
 } from './cluster-model'
-import { getCommentRecord } from './comment-store'
+import { getCommentRecord, getCommentThread } from './comment-store'
 import { type CommentingContext } from './context'
 import { useCommentThreads } from './hooks'
 import { useCommentingEnabled } from './license'
@@ -172,37 +172,36 @@ function CanvasCommentsLayer(props: CommentingContext) {
 			const record = getCommentRecord(editor, id)
 			if (!record) return null
 			const thread =
-				record.typeName === 'comment' ? getCommentRecord(editor, record.threadId) : record
+				record.typeName === 'comment' ? getCommentThread(editor, record.threadId) : record
 			return thread?.typeName === 'comment-thread' ? thread : null
 		},
 		[editor]
 	)
 
-	// Serve a pending reveal request, zooming to the first cluster split that reveals the pin if it's
-	// folded into a badge. Also unhides pins: the popover opens on the layer that hiding withholds.
+	// Bring a thread's pin into view (zooming to the first cluster split that unfolds it if it's
+	// folded into a badge) and open it.
+	const revealAndOpenThread = useCallback(
+		(thread: TLCommentThread, duration?: number) => {
+			revealThreadPin(editor, thread, clusterModel.table, clusterZoomBounds, options, duration)
+			openThreadId.set(editor, thread.id)
+		},
+		[clusterModel.table, clusterZoomBounds, editor, options]
+	)
+
+	// Serve a pending reveal request. Also unhides pins: the popover opens on the layer that hiding
+	// withholds.
 	useEffect(() => {
 		if (!requestedRevealThread) return
 		revealThreadRequest.set(editor, null)
 		commentsHidden.set(editor, false)
-		revealThreadPin(editor, requestedRevealThread, clusterModel.table, clusterZoomBounds, options)
-		openThreadId.set(editor, requestedRevealThread.id)
-	}, [requestedRevealThread, clusterModel.table, clusterZoomBounds, editor, options])
+		revealAndOpenThread(requestedRevealThread)
+	}, [requestedRevealThread, revealAndOpenThread, editor])
 
 	// Picking a thread out of a cluster's hover preview. `openThreadId` alone would work, but would
 	// cut straight there from the badge — zoom in first, the same move the badge's own click makes.
 	const revealClusteredThread = useCallback(
-		(thread: TLCommentThread) => {
-			revealThreadPin(
-				editor,
-				thread,
-				clusterModel.table,
-				clusterZoomBounds,
-				options,
-				CLUSTER_EXPAND_ZOOM_MS
-			)
-			openThreadId.set(editor, thread.id)
-		},
-		[clusterModel.table, clusterZoomBounds, editor, options]
+		(thread: TLCommentThread) => revealAndOpenThread(thread, CLUSTER_EXPAND_ZOOM_MS),
+		[revealAndOpenThread]
 	)
 
 	const expandCluster = useCallback(

package/src/canvas/comments-sidebar.tsx

@@ -1,18 +1,11 @@
 import { ReactNode, useCallback } from 'react'
-import {
-	EditorPortal,
-	TLComment,
-	TLCommentThread,
-	useEditor,
-	useTranslation,
-	useValue,
-} from 'tldraw'
+import { EditorPortal, TLCommentThread, useEditor, useTranslation, useValue } from 'tldraw'
 import { CommentListItemProps, CommentListItemRenderProps, CommentsList } from '../ui/comments-list'
 import { UNKNOWN_COMMENT_AUTHOR } from './comment-render'
 import { CommentsFilterMenu } from './comments-filter-menu'
 import { CommentsVisibilityToggle } from './comments-visibility-toggle'
 import { type CommentingContext } from './context'
-import { useComments, useCommentThreads } from './hooks'
+import { getCommentsByThread, useCommentThreads } from './hooks'
 import { useCommentingEnabled } from './license'
 import { useCommentingOptions } from './options'
 import { richTextToPlaintext } from './rich-text'
@@ -53,7 +46,7 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 	const commentingEnabled = useCommentingEnabled()
 	const msg = useTranslation()
 	const threads = useCommentThreads(editor)
-	const comments = useComments(editor)
+	const byThread = useValue('comments by thread', () => getCommentsByThread(editor).get(), [editor])
 	const currentPageId = useValue('page id', () => editor.getCurrentPageId(), [editor])
 	const open = useValue('sidebar open', () => commentsSidebarOpen.get(editor), [editor])
 	const openId = useValue('open thread', () => openThreadId.get(editor), [editor])
@@ -66,14 +59,6 @@ export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps) {
 
 	if (!commentingEnabled || !open) 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(

package/src/canvas/hooks.ts

@@ -30,7 +30,7 @@ export function useCommentThreads(editor: Editor): TLCommentThread[] {
  */
 const commentsByThread = new WeakCache<Editor, Computed<Map<TLCommentThreadId, TLComment[]>>>()
 
-/** Exported for tests; use {@link useThreadComments} to consume. @internal */
+/** Live comments grouped by thread id, cached per editor. @internal */
 export function getCommentsByThread(editor: Editor) {
 	return commentsByThread.get(editor, () =>
 		computed('comments by thread', (prev) => {

package/src/canvas/thread-pin.tsx

@@ -33,6 +33,7 @@ import { openThreadId } from './state'
 import { ThreadPreview, useMarkerPreview } from './thread-preview'
 import {
 	anchorPagePoint,
+	anchorViewportPoint,
 	commentTargetShapeAt,
 	impreciseShapePinInset,
 	isBoxInInflatedViewport,
@@ -40,6 +41,7 @@ import {
 	REGION_PIN_CORNER,
 	regionAnchorPinCorner,
 	regionPinPoint,
+	regionWithPinAt,
 	shapeAnchorAt,
 } from './thread-state'
 import { POPOVER_OFFSET, ThreadPopover, ThreadView } from './thread-view'
@@ -107,7 +109,7 @@ export const ThreadPin = memo(function ThreadPin({
 	// A region resizes from its corners — every corner but the pin's own, which the pin owns.
 	const resizeHandles = useMemo(
 		() => REGION_CORNERS.filter((c) => c.x !== pinCorner.x || c.y !== pinCorner.y),
-		[pinCorner]
+		[pinCorner.x, pinCorner.y]
 	)
 	const dragRef = useRef<{
 		startX: number
@@ -165,13 +167,8 @@ export const ThreadPin = memo(function ThreadPin({
 		'pin point',
 		() => {
 			if (thread.pageId !== editor.getCurrentPageId()) return null
-			const pagePoint = anchorPagePoint(editor, thread.anchor)
-			if (!pagePoint) return null
-			const viewportPoint = editor.pageToViewport(pagePoint)
-			const inset = impreciseShapePinInset(editor, thread.anchor)
-			const point = inset
-				? { x: viewportPoint.x + inset.x, y: viewportPoint.y + inset.y }
-				: viewportPoint
+			const point = anchorViewportPoint(editor, thread.anchor)
+			if (!point) return null
 			// Off-screen pins (plus a pre-mount margin) unmount rather than re-render every camera frame. A
 			// region thread stays mounted while any part of its box is on screen, since the box renders here too.
 			if (!exemptFromCull) {
@@ -187,6 +184,9 @@ export const ThreadPin = memo(function ThreadPin({
 	)
 	if (!point) return null
 
+	const toggleOpen = () =>
+		openThreadId.set(editor, openThreadId.get(editor) === thread.id ? null : thread.id)
+
 	const PinContent = options.components.PinContent
 	const threadAuthor = resolveAuthor(thread.createdBy)
 	const pinContent = PinContent ? (
@@ -247,28 +247,28 @@ export const ThreadPin = memo(function ThreadPin({
 			editor.setHintingShapes(hit ? [hit.id] : [])
 		}
 	}
-	// A cancelled pointer (touch gesture takeover, browser interruption) aborts the drag outright:
-	// no re-anchor commit, no click-toggle — the pin snaps back and the hint clears.
-	const cancelDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
+	// Release capture and take the drag record; null when no drag was in progress.
+	const takeDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
 		const drag = dragRef.current
 		dragRef.current = null
 		if (e.currentTarget.hasPointerCapture(e.pointerId)) {
 			e.currentTarget.releasePointerCapture(e.pointerId)
 		}
-		if (!drag) return
+		return drag
+	}
+	// A cancelled pointer (touch gesture takeover, browser interruption) aborts the drag outright:
+	// no re-anchor commit, no click-toggle — the pin snaps back and the hint clears.
+	const cancelDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
+		if (!takeDrag(e)) return
 		setDragPagePoint(null)
 		editor.setHintingShapes([])
 	}
 	const endDrag = (e: ReactPointerEvent<HTMLButtonElement>) => {
-		const drag = dragRef.current
-		dragRef.current = null
-		if (e.currentTarget.hasPointerCapture(e.pointerId)) {
-			e.currentTarget.releasePointerCapture(e.pointerId)
-		}
+		const drag = takeDrag(e)
 		if (!drag) return
 		editor.setHintingShapes([])
 		if (!drag.moved) {
-			openThreadId.set(editor, openThreadId.get(editor) === thread.id ? null : thread.id)
+			toggleOpen()
 			return
 		}
 		const cursorPage = editor.screenToPage({ x: e.clientX, y: e.clientY })
@@ -276,12 +276,7 @@ export const ThreadPin = memo(function ThreadPin({
 		setDragPagePoint(null)
 		let anchor: TLCommentThread['anchor']
 		if (thread.anchor.type === 'region') {
-			// Translate so the pin (the region's pin corner) lands at the drop; size unchanged.
-			anchor = {
-				...thread.anchor,
-				x: pagePoint.x - pinCorner.x * thread.anchor.w,
-				y: pagePoint.y - pinCorner.y * thread.anchor.h,
-			}
+			anchor = regionWithPinAt(thread.anchor, pinCorner, pagePoint)
 		} else {
 			const hit = commentTargetShapeAt(editor, pagePoint)
 			anchor = hit
@@ -316,11 +311,7 @@ export const ThreadPin = memo(function ThreadPin({
 	const regionAnchor = thread.anchor.type === 'region' ? thread.anchor : undefined
 	const movedRegion =
 		regionAnchor && dragPagePoint
-			? {
-					...regionAnchor,
-					x: dragPagePoint.x - pinCorner.x * regionAnchor.w,
-					y: dragPagePoint.y - pinCorner.y * regionAnchor.h,
-				}
+			? regionWithPinAt(regionAnchor, pinCorner, dragPagePoint)
 			: regionAnchor
 	const regionBoxBounds = resizeBounds ?? movedRegion
 	const commitResize = (bounds: BoxModel) => {
@@ -374,8 +365,7 @@ export const ThreadPin = memo(function ThreadPin({
 					// from a drag), so only take keyboard-synthesised clicks here — those report
 					// `detail === 0` — or the thread would toggle twice per mouse click.
 					onClick={(e) => {
-						if (e.detail !== 0) return
-						openThreadId.set(editor, openThreadId.get(editor) === thread.id ? null : thread.id)
+						if (e.detail === 0) toggleOpen()
 					}}
 					onPointerEnter={previewHandlers.onPointerEnter}
 					onPointerLeave={previewHandlers.onPointerLeave}