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

package/dist-esm/index.d.mts

@@ -1,14 +1,26 @@
+import { Avatar } from '@tldraw/mentions';
+import { AvatarProps } from '@tldraw/mentions';
+import { CommentAuthor } from '@tldraw/mentions';
 import { ComponentType } from 'react';
+import { createMentionSuggestion } from '@tldraw/mentions';
 import { Editor } from 'tldraw';
 import { EditorAtom } from 'tldraw';
+import { filterMentionMembers } from '@tldraw/mentions';
 import { JSX } from 'react/jsx-runtime';
-import type { MentionNodeAttrs } from '@tiptap/extension-mention';
+import { Mention } from '@tldraw/mentions';
+import { MentionList } from '@tldraw/mentions';
+import { MentionListProps } from '@tldraw/mentions';
+import { MentionMember } from '@tldraw/mentions';
+import { MentionProps } from '@tldraw/mentions';
+import { MentionSuggestionOptions } from '@tldraw/mentions';
+import { MouseEvent as MouseEvent_2 } from 'react';
 import { ReactNode } from 'react';
 import { StateNode } from 'tldraw';
-import type { SuggestionOptions } from '@tiptap/suggestion';
 import { TLComment } from 'tldraw';
 import { TLCommentAnchor } from 'tldraw';
 import { TLCommentId } from 'tldraw';
+import { TLCommentReaction } from 'tldraw';
+import { TLCommentReactionId } from 'tldraw';
 import { TLCommentThread } from 'tldraw';
 import { TLCommentThreadId } from 'tldraw';
 import { TLHistoryBatchOptions } from 'tldraw';
@@ -19,193 +31,86 @@ import { TLUiOverrides } from 'tldraw';
 import { VecLike } from 'tldraw';
 
 /**
- * Where a thread's pin sits on the page, for each anchor kind. Null hides the pin. For imprecise
- * shape anchors the pin uses `impreciseShapeAnchor` (a normalized 0–1 spot, top-right by default)
- * rather than the stored `x`/`y`.
+ * Where a thread's pin sits on the page, for each anchor kind. Null hides the pin. Imprecise shape
+ * anchors use {@link CommentingOptions.impreciseShapeAnchor} rather than the stored `x`/`y`.
+ *
+ * A shape anchor's `x`/`y` are normalized within the shape's bounds and resolved through its page
+ * transform, so the pin rides rotation instead of being left behind in the bounding box.
  * @public
  */
-export declare function anchorPagePoint(editor: Editor, anchor: TLCommentAnchor, impreciseShapeAnchor?: {
-    x: number;
-    y: number;
-}): {
+export declare function anchorPagePoint(editor: Editor, anchor: TLCommentAnchor): {
     x: number;
     y: number;
 } | null;
 
-/** A commenter's avatar — their image if provided, otherwise a single-initial coloured circle.
- * @public @react */
-export declare function Avatar({ name, color, image }: AvatarProps): JSX.Element;
+export { Avatar }
 
-/** @public */
-export declare 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;
-}
+export { AvatarProps }
 
-/** A comment's metadata line: author name, relative time, and an edited marker. @public @react */
+/**
+ * A comment's metadata line: author name, relative time, and an edited marker. Hovering the time
+ * shows the full date and time in a tooltip.
+ * @public @react
+ */
 export declare function Byline({ author, date, edited }: BylineProps): JSX.Element;
 
 /** @public */
 export declare interface BylineProps {
-    author: string;
+    author: CommentAuthor;
     /** ISO datetime; formatted to relative time by the component. */
     date: string;
     /** Shows an "edited" marker when the comment has been edited. */
     edited?: boolean;
 }
 
-/** @public @react */
-export declare function CanvasComments(props: CanvasCommentsProps): JSX.Element | null;
-
 /**
  * A ready-to-use comments layer for a tldraw canvas: pins each thread at its anchor, opens a
  * thread popover (with a reply composer) on click, and shows a composer where the comment tool
  * placed a new thread. Reads/writes comment records straight from `editor.store`.
  *
- * It's meant as the batteries-included default — every visible piece is a lever (the `CommentBody`
- * and `PinContent` slots on `CommentTool.configure({ components })`), and the pieces it composes
- * (`CommentPin`, `CommentThread`, `CommentComposer`, the hooks, the tool) are all exported, so a
- * consumer can rebuild this from parts instead.
+ * It's the batteries-included default: every visible piece is a slot on
+ * `CommentTool.configure({ components })`, and the pieces it composes (`CommentPin`,
+ * `CommentThread`, `CommentComposer`, the hooks, the tool) are all exported, so a consumer can
+ * rebuild it from parts instead. The host wiring is the {@link CommentingContext}, which
+ * `CanvasCommentsSidebar` takes too.
+ *
+ * @public @react
+ */
+export declare function CanvasComments(props: CanvasCommentsProps): JSX.Element | null;
+
+/**
+ * The host wiring for {@link CanvasComments} — see {@link CommentingContext}, which the sidebar
+ * takes the same fields from.
+ *
  * @public
  */
-export declare interface CanvasCommentsProps {
-    /** The signed-in user's id, or null for a read-only viewer. Only a signed-in user composes. */
-    currentUserId: null | string;
-    /** Map an author id to a display name, or `undefined` when the id can't be named. */
-    resolveName(id: string): string | undefined;
-    /** Called after any comment (a new thread's first comment, or a reply) is posted. */
-    onPostComment?(comment: TLComment): void;
-    /** Whether a comment is unread for the current user (return true for unread). */
-    isCommentUnread?(commentId: TLCommentId): boolean;
-    /**
-     * Called for each unread comment shown to the user in an open thread popover, so hosts can
-     * record a read receipt. Needs `isCommentUnread` to know what's unread.
-     */
-    onCommentRead?(commentId: TLCommentId): void;
-    /** Resolve the members matching an `@`-query in the composers (sync or async). */
-    getMentionSuggestions?(query: string): MentionMember[] | Promise<MentionMember[]>;
-    /** Override a mention-picker row's content. */
-    renderMentionSuggestion?(member: MentionMember): ReactNode;
-    /** Where imprecise shape pins sit — a normalized (0–1) spot within the shape. Default top-right. */
-    impreciseShapeAnchor?: {
-        x: number;
-        y: number;
-    };
-    /** Region comment behaviour. Region is off by default — omit this for click-only point/shape
-     *  comments. Anything unset falls back to {@link DEFAULT_REGION_COMMENT_OPTIONS}. */
-    regionOptions?: Partial<RegionCommentOptions>;
-}
+export declare type CanvasCommentsProps = CommentingContext;
 
 /**
- * A comments list panel for the current page, shown while the comment tool is active. Clicking a
- * thread brings its pin into view and opens it. Batteries-included over the store (a sibling to
- * `CanvasComments`); `CommentsList` is exported for a differently-placed or always-on list.
+ * A comments list panel for the current page, shown while {@link commentsSidebarOpen} is set (e.g.
+ * toggled by a button). Clicking a thread brings its pin into view and opens it. Batteries-included
+ * over the store (a sibling to `CanvasComments`); `CommentsList` is exported for a differently-placed
+ * or always-on list.
  * @public @react
  */
 export declare function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps): JSX.Element | null;
 
-/** @public */
-export declare interface CanvasCommentsSidebarProps {
-    /** Map an author id to a display name, or `undefined` when the id can't be named. */
-    resolveName(id: string): string | undefined;
-    /** The signed-in user's id. Enables the "only your threads" filter when present. */
-    currentUserId?: string;
-    /**
-     * Whether a comment is unread for the current user (return true for unread). Enables the
-     * "only unread" filter when present.
-     */
-    isCommentUnread?(commentId: TLCommentId): boolean;
-    /** Tool ids that show the sidebar. Defaults to the comment tool. */
-    tools?: string[];
+/**
+ * The host wiring for {@link CanvasCommentsSidebar}: the {@link CommentingContext} fields it reads,
+ * plus the panel's own slots. A non-null `currentUserId` enables the "only your threads" filter, and
+ * an `isCommentUnread` the "only unread" one. `CanvasComments` takes the same fields, so a host
+ * mounting both can spread one object into each.
+ *
+ * @public
+ */
+export declare interface CanvasCommentsSidebarProps extends Pick<CommentingContext, 'currentUserId' | 'getThreadHref' | 'isCommentUnread' | 'resolveAuthor'> {
     /** Header above the list. */
     header?: ReactNode;
     /** Shown when the page has no threads. */
     empty?: ReactNode;
-    /** Where imprecise shape pins sit, so navigation centres on the same spot. Default top-right. */
-    impreciseShapeAnchor?: {
-        x: number;
-        y: number;
-    };
-}
-
-/**
- * A cluster in the merge tree: a leaf (one thread) or a merged group.
- * @public
- */
-export declare 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[];
-}
-
-/** @public */
-export declare 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;
 }
 
-/** @public */
-export declare interface ClusterRuntime {
-    /** Events[0..k) are active. Exposed for tests and debugging. */
-    readonly k: number;
-    /** Reset state from scratch for the given zoom (cold start / after rebuild). */
-    seed(zoom: number): void;
-    /**
-     * Reset state for the given zoom, carrying hysteresis state over from a previous partition
-     * (the visible map of the model being replaced). Threshold-forced events ignore history:
-     * zoom \<= zMerge is always active, zoom \>= zSplit always inactive. An event inside its band
-     * is active iff its members were merged together in `previous`; a band event with no history
-     * (e.g. introduced by the rebuild) stays inactive until the next zoom-out crosses its zMerge.
-     * Active events must form a prefix of the table, so classification stops at the first
-     * inactive event; later band-active events conservatively resolve to split.
-     */
-    seedFrom(zoom: number, previous: ReadonlyMap<string, ClusterNode>): void;
-    /** Advance/retreat the cursor for a camera change. No-op if zoom sits inside all bands. */
-    onCamera(zoom: number): void;
-    /** The current partition: cluster id → node. Do not mutate. */
-    getVisible(): ReadonlyMap<string, ClusterNode>;
-}
-
-/**
- * The precomputed clustering schedule for one page's comments.
- * @public
- */
-export declare 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 declare function collectClusterLeaves(editor: Editor, threads: readonly TLCommentThread[], openThreadId: null | string, impreciseShapeAnchor?: {
-    x: number;
-    y: number;
-}): LeafInput[];
+export { CommentAuthor }
 
 /**
  * Renders a comment's rich-text body read-only through the limited comment extension set (no
@@ -223,13 +128,13 @@ export declare interface CommentBodyProps {
 }
 
 /** A single comment: Avatar, Byline, and a body slot the consumer renders. @public @react */
-export declare function CommentCard({ author, body, date, you, edited, actions }: CommentCardProps): JSX.Element;
+export declare function CommentCard({ author, body, date, you, edited, actions, footer }: CommentCardProps): JSX.Element;
 
 /** @public */
 export declare 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. */
+    author: CommentAuthor;
+    /** The rendered comment body. The card doesn't dictate a format — pass a `<CommentBody>`
+     *  for a comment's rich text, or any node of your own. */
     body: ReactNode;
     /** ISO datetime; formatted to relative time by the component. */
     date: string;
@@ -238,6 +143,8 @@ export declare interface CommentCardProps {
     edited?: boolean;
     /** Hover-revealed controls at the card's top-right (e.g. an edit affordance). */
     actions?: ReactNode;
+    /** Content under the body, aligned with it rather than the avatar (e.g. a `<Reactions>` row). */
+    footer?: ReactNode;
 }
 
 /**
@@ -247,11 +154,11 @@ export declare interface CommentCardProps {
  * floating toolbar. Presentational by default; pass value/onChange/onSubmit to drive it as a form.
  * @public @react
  */
-export declare function CommentComposer({ author, placeholder, value, onChange, onSubmit, sendLabel, disabled, autoFocus, leading, getMentionSuggestions, renderMentionSuggestion }: CommentComposerProps): JSX.Element;
+export declare function CommentComposer({ author, placeholder, value, onChange, onSubmit, sendLabel, onArrowUpWhenEmpty, disabled, autoFocus, leading, getMentionSuggestions, renderMentionSuggestion }: CommentComposerProps): JSX.Element;
 
 /** @public */
 export declare interface CommentComposerProps {
-    author: string;
+    author: CommentAuthor;
     placeholder: string;
     /** Controlled rich-text value. Omit for the presentational (display-only) composer. */
     value?: TLRichText;
@@ -259,6 +166,9 @@ export declare interface CommentComposerProps {
     /** Called on Send click or Enter. When set, the composer is interactive. */
     onSubmit?(): void;
     sendLabel?: string;
+    /** Called when Up is pressed in an empty composer — e.g. to start editing the comment above,
+     *  the way chat apps edit your last message. With content in the field, Up moves the cursor. */
+    onArrowUpWhenEmpty?(): void;
     disabled?: boolean;
     autoFocus?: boolean;
     /** The leading element before the field. Defaults to the author's avatar. */
@@ -289,12 +199,104 @@ export declare interface CommentingComponents {
     ThreadPreview?: ComponentType<{
         comment: TLComment;
     }>;
+    /**
+     * A whole sidebar row. Replaces the default `<CommentListItem>`, which is exported — so a row
+     * that only adds an unread dot or a status chip can spread these props into it. Use
+     * `ThreadPreview` instead when only the preview text is changing.
+     */
+    ThreadRow?: ComponentType<CommentListItemRenderProps & {
+        thread: TLCommentThread;
+    }>;
+    /**
+     * Extra controls in an open thread's header, added ahead of the built-in resolve and dismiss
+     * buttons rather than replacing them. "Copy link" is already built in whenever the host supplies
+     * `getThreadHref`.
+     */
+    ThreadActions?: ComponentType<{
+        comments: TLComment[];
+        thread: TLCommentThread;
+    }>;
+    /**
+     * A reaction's visual, given its token. The default renders the token string for the OS emoji
+     * font. Override to draw a custom palette — an `<img>`, an SVG, anything. The token is what gets
+     * stored and synced; this only controls how it's drawn.
+     */
+    ReactionContent?: ComponentType<{
+        token: string;
+    }>;
+    /**
+     * What the add-reaction button opens. Replaces the default `<EmojiPicker>` grid. Pairs with
+     * `ReactionContent` (which draws the tokens this emits) and `isAllowedReaction` (which must
+     * accept them).
+     */
+    ReactionPalette?: ComponentType<EmojiPickerProps>;
+    /**
+     * The hover affordance naming who reacted with an emoji. Receives the reactors and the pill (as
+     * `children`) and owns the whole thing — box, size, shape, position. For a wording change,
+     * translate the `comments.reacted-*` strings instead.
+     */
+    ReactionTooltip?: ComponentType<ReactionTooltipProps>;
+    /**
+     * Shown where a composer would sit when the viewer can't compose (see
+     * {@link CommentingOptions.canComment}). `context` is the surface rendering it: an open thread
+     * popover (`'thread'`) or the comment tool's placement popover (`'pending'`). Unset, those
+     * surfaces render nothing.
+     */
+    ComposerFallback?: ComponentType<{
+        context: 'pending' | 'thread';
+    }>;
+}
+
+/**
+ * The live, host-supplied half of commenting: who the viewer is, how author ids become names, read
+ * status, and the mention roster. (The static half is {@link CommentingOptions}, configured once on
+ * the tool.)
+ *
+ * Every commenting surface reads the same set, so a host mounting more than one — `CanvasComments`
+ * and `CanvasCommentsSidebar`, say — can build it once and spread it into each rather than
+ * repeating the props:
+ *
+ * ```tsx
+ * const commenting: CommentingContext = { currentUserId, resolveAuthor, isCommentUnread }
+ *
+ * <CanvasComments {...commenting} />
+ * <CanvasCommentsSidebar {...commenting} />
+ * ```
+ *
+ * @public
+ */
+export declare interface CommentingContext {
+    /** The signed-in user's id, or null for a read-only viewer. Only a signed-in user composes. */
+    currentUserId: null | string;
+    /** Map an author id to their display info, or `undefined` when the id can't be resolved. */
+    resolveAuthor(id: string): CommentAuthor | undefined;
+    /** Called after any comment (a new thread's first comment, or a reply) is posted. */
+    onPostComment?(comment: TLComment): void;
+    /** Whether a comment is unread for the current user (return true for unread). */
+    isCommentUnread?(commentId: TLCommentId): boolean;
+    /**
+     * Called with every unread comment shown to the user in an open thread popover, batched per
+     * report, so hosts can record read receipts without a write per comment. Needs
+     * `isCommentUnread` to know what's unread.
+     */
+    onCommentsRead?(commentIds: TLCommentId[]): void;
+    /** Resolve the members matching an `@`-query in the composers (sync or async). */
+    getMentionSuggestions?(query: string): MentionMember[] | Promise<MentionMember[]>;
+    /** Override a mention-picker row's content. */
+    renderMentionSuggestion?(member: MentionMember): ReactNode;
+    /**
+     * The host's URL for a thread, so surfaces can link to it — e.g. the sidebar's rows render as
+     * anchors when this is present, letting ctrl/cmd-click and middle-click open the thread in a
+     * new tab (a plain click still selects the thread in place; the href isn't followed).
+     */
+    getThreadHref?(threadId: TLCommentThreadId): string | undefined;
 }
 
 /**
  * Configuration for the commenting layer. Static config only — pass it once via
  * `CommentTool.configure({ ... })`, mirroring `ShapeUtil.configure`. Live, reactive values
- * (`currentUserId`, `resolveName`, read-status callbacks) stay as props on `<CanvasComments>`.
+ * (`currentUserId`, author resolution, read-status callbacks) are the `CommentingContext`, passed as
+ * props to each commenting surface.
  *
  * For defaults, see {@link defaultCommentingOptions}.
  *
@@ -307,11 +309,9 @@ export declare interface CommentingComponents {
  */
 export declare interface CommentingOptions {
     /**
-     * How comment mutations (post, reply, edit, resolve, delete) interact with the editor undo
-     * stack. Defaults to `'ignore'` — comments are deliberately not undoable (see `TLComment`).
-     * `'record'` is a multiplayer footgun: undoing a delete resurrects a thread a collaborator
-     * already removed, and undoing a resolve/edit reverts their newer state. Safe only single-player
-     * or on a non-synced local comment store.
+     * How comment mutations interact with the editor undo stack. Defaults to `'ignore'` — comments
+     * are deliberately not undoable (see `TLComment`). `'record'` is a multiplayer footgun: undoing
+     * a delete resurrects a thread a collaborator already removed. Safe only single-player.
      */
     readonly history: TLHistoryBatchOptions['history'];
     /**
@@ -321,23 +321,89 @@ export declare interface CommentingOptions {
     readonly dragHistory: TLHistoryBatchOptions['history'] | undefined;
     /** Fold nearby pins into count badges as the camera zooms out. */
     readonly enableClustering: boolean;
+    /**
+     * Whether a user may hold several emoji reactions on one comment. `true` (the default) is the
+     * Slack model: each emoji toggles independently. `false` is single-select: picking a new emoji
+     * replaces the user's existing reaction. Note this is enforced client-side; the server accepts
+     * per-emoji records either way.
+     */
+    readonly allowMultipleReactions: boolean;
+    /**
+     * Whether a token may be added as a reaction. Defaults to {@link isAllowedReactionEmoji}, which
+     * keeps a scripted client from writing junk values the picker would never offer. Override
+     * alongside a custom `ReactionPalette`. Removals aren't checked — an off-palette reaction must
+     * still be clearable.
+     */
+    isAllowedReaction(token: string): boolean;
+    /**
+     * Whether dragging the comment tool out creates a region anchor — a comment attached to a
+     * rectangular area, drawn as a dashed box with the pin on the corner the drag released on. Off
+     * by default, where comments attach to points and shapes only and a drag trails the composer.
+     */
+    readonly enableRegions: boolean;
+    /**
+     * Whether the viewer may participate in commenting: composing, editing, deleting, resolving, and
+     * moving pins. When false, {@link CommentingComponents.ComposerFallback} renders in the
+     * composer's place and action affordances are hidden. Unset, participation is allowed exactly
+     * when `currentUserId` is set.
+     *
+     * Called during render via {@link useCanComment}, so signal reads are tracked. Posting still
+     * needs a `currentUserId`, so returning true for a signed-out viewer yields a composer whose
+     * send button stays disabled. A callback that throws is logged and read as false, rather than
+     * taking the comments layer down with it.
+     */
+    readonly canComment: ((ctx: {
+        currentUserId: null | string;
+        editor: Editor;
+    }) => boolean) | undefined;
+    /**
+     * Whether the viewer may make a particular write against a particular record: editing or
+     * deleting a comment, or deleting a thread. Unset, each is its record's owner's to make
+     * ({@link defaultCanModifyComment}) — you edit and delete your own comments, and delete threads
+     * you started. Override it to widen that (a workspace admin or moderator who may remove
+     * anyone's comment) or to narrow it (no edits after an hour). Where it returns false the
+     * affordance isn't rendered.
+     *
+     * Checked after {@link CommentingOptions.canComment}, which gates commenting as a whole: a
+     * viewer who may not participate gets no action affordances at all, whatever this returns.
+     *
+     * Called during render via {@link useCanModifyComment}, so reactive reads (signals) are tracked.
+     * A callback that throws is logged and read as false: an affordance is withheld rather than the
+     * comments layer lost, and a denial is what a server enforcing the same rule would have said.
+     *
+     * @example
+     * ```tsx
+     * CommentTool.configure({
+     * 	canModifyComment: (ctx) =>
+     * 		// Moderators may delete anything; everything else stays the owner's to do.
+     * 		(ctx.action !== 'edit-comment' && isModerator(ctx.currentUserId)) ||
+     * 		defaultCanModifyComment(ctx),
+     * })
+     * ```
+     */
+    readonly canModifyComment: ((ctx: CommentModificationContext) => boolean) | undefined;
     /** Normalized (0–1) spot within a shape where imprecise shape pins sit. Default top-right. */
     readonly impreciseShapeAnchor: {
         readonly x: number;
         readonly y: number;
     };
-    /** Screen-pixel margin by which the viewport is inflated when culling cluster badges. */
-    readonly clusterCullMargin: number;
-    /** How far past a cluster's split zoom to land when expanding it (1.05 = 5% overshoot). */
-    readonly clusterSplitZoomFactor: number;
+    /**
+     * Whether a comment landing on a shape pins to the exact clicked spot, or to the shape as a
+     * whole (rendered at `impreciseShapeAnchor`). Always precise by default; return `false`, or
+     * decide from the context. Governs new placements only — existing anchors render as stored.
+     */
+    shouldBePrecise(editor: Editor, context: ShapeCommentPrecisionContext): boolean;
     /** Component overrides. See {@link CommentingComponents}. */
     readonly components: CommentingComponents;
 }
 
+/** One thread's row in a {@link CommentsList}. @public @react */
+export declare function CommentListItem({ id, author, preview, date, resolved, page, count, selected, reactions, href, resolvedLabel, onSelect }: CommentListItemRenderProps): JSX.Element;
+
 /** @public */
 export declare interface CommentListItemProps {
     id: string;
-    author: string;
+    author: CommentAuthor;
     /** A short preview of the thread — e.g. the first comment's body. */
     preview: ReactNode;
     /** ISO datetime of the thread's first comment. */
@@ -349,8 +415,61 @@ export declare interface CommentListItemProps {
     count?: number;
     /** Whether this thread is the open one. */
     selected?: boolean;
+    /** Tallied reactions for the row (a thread's, or a single comment's when the row is one
+     *  comment), shown as inert pills under the preview. Omit to hide. */
+    reactions?: ReactionSummary[];
+    /**
+     * Link target for the item. When set, the row renders as an anchor so browser affordances
+     * (ctrl/cmd-click, middle-click) open it in a new tab; a plain click still calls `onSelect`.
+     */
+    href?: string;
 }
 
+/**
+ * What a row is rendered with: the item, plus the list-level wiring it needs to be interactive.
+ * A custom row gets the same props the default `<CommentListItem>` does, so it can wrap the
+ * default rather than reimplement it.
+ *
+ * @public
+ */
+export declare interface CommentListItemRenderProps extends CommentListItemProps {
+    /** Label for a resolved thread's marker on its row. */
+    resolvedLabel?: string;
+    /** Called with the thread id when the row is chosen. */
+    onSelect?(id: string): void;
+}
+
+/**
+ * A commenting write that belongs to someone in particular, and the record it targets — the
+ * argument to {@link CommentingOptions.canModifyComment}.
+ *
+ * Resolving, reopening, reacting, and moving a pin aren't here: none of them is anyone's in
+ * particular, so {@link CommentingOptions.canComment} is the only gate on them.
+ *
+ * @public
+ */
+export declare type CommentModification = {
+    readonly action: 'delete-comment';
+    readonly comment: TLComment;
+} | {
+    readonly action: 'delete-thread';
+    readonly thread: TLCommentThread;
+} | {
+    readonly action: 'edit-comment';
+    readonly comment: TLComment;
+};
+
+/**
+ * The argument to {@link CommentingOptions.canModifyComment}: which write, against which record,
+ * and by whom.
+ *
+ * @public
+ */
+export declare type CommentModificationContext = {
+    readonly currentUserId: null | string;
+    readonly editor: Editor;
+} & CommentModification;
+
 /** A canvas comment marker: shows its `children` (or a check when resolved). Purely
  * presentational — it reflects open/resolved state via CSS; wrap it to make it clickable.
  * @public @react */
@@ -366,6 +485,39 @@ export declare interface CommentPinProps {
     open?: boolean;
 }
 
+/**
+ * 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 declare function CommentReactionPicker({ comment, currentUserId, emoji }: CommentReactionPickerProps): JSX.Element | null;
+
+/** @public */
+export declare interface CommentReactionPickerProps {
+    comment: TLComment;
+    /** The reacting user. Null/omitted renders nothing — there's nobody to react as. */
+    currentUserId?: null | string;
+    /** The emoji the picker offers. Defaults to `DEFAULT_REACTION_EMOJI`. */
+    emoji?: string[];
+}
+
+/**
+ * The tallied reaction row under one comment. Pair with `CommentReactionPicker`, which is what
+ * adds a reaction.
+ * @public @react
+ */
+export declare function CommentReactions({ comment, currentUserId, resolveName }: CommentReactionsProps): JSX.Element;
+
+/** @public */
+export declare interface CommentReactionsProps {
+    comment: TLComment;
+    /** The reacting user. Null/omitted gives a read-only row (signed out): counts show, but the
+     *  pills don't toggle. */
+    currentUserId?: null | string;
+    /** Names a reactor id for the hover list. Ids it can't name fall back to a generic "Someone". */
+    resolveName?(userId: string): string | undefined;
+}
+
 /** The funnel dropdown in the sidebar header: toggles for which threads the list shows.
  * @public @react */
 export declare function CommentsFilterMenu({ canFilterByAuthor, canFilterByUnread }: CommentsFilterMenuProps): JSX.Element;
@@ -406,8 +558,12 @@ export declare interface CommentsListProps {
     empty?: ReactNode;
     /** Label for a resolved thread's marker on its row. Defaults to "Resolved". */
     resolvedLabel?: string;
-    /** Override how each item renders. Defaults to `<CommentListItem>`. */
-    renderItem?(item: CommentListItemProps): ReactNode;
+    /**
+     * Override how each item renders. Defaults to `<CommentListItem>`, which is exported — so a
+     * row that only adds something can spread these props into it rather than start over. The list
+     * supplies the key, so a custom row doesn't need one.
+     */
+    renderItem?(props: CommentListItemRenderProps): ReactNode;
 }
 
 /**
@@ -424,14 +580,17 @@ export declare function CommentsMenuItem(): JSX.Element;
  * @public @react */
 export declare function CommentsOverflowMenu(): JSX.Element;
 
-/** A comment's body, rendered as markdown (bold, italic, code, links, lists). @public @react */
-export declare function CommentText({ text }: CommentTextProps): JSX.Element;
+/**
+ * Whether the comments sidebar (the thread list) is open. Driven by an explicit control rather than
+ * by which tool is active, so browsing threads is separate from placing them.
+ * @public
+ */
+export declare const commentsSidebarOpen: EditorAtom<boolean>;
 
-/** @public */
-export declare interface CommentTextProps {
-    /** Rich text body, authored as markdown. */
-    text: string;
-}
+/** The sidebar header's show/hide toggle for comment pins — an eye that closes while comments
+ *  are hidden. The same state as the Shift+C shortcut.
+ * @public @react */
+export declare function CommentsVisibilityToggle(): JSX.Element;
 
 /**
  * A comment thread: an optional header, an optional resolved banner, the comments, and an
@@ -439,7 +598,7 @@ export declare interface CommentTextProps {
  * composer's handlers; how each comment renders is overridable via `renderComment`.
  * @public @react
  */
-export declare function CommentThread({ comments, header, headerActions, resolvedBanner, composer, renderComment }: CommentThreadProps): JSX.Element;
+export declare function CommentThread({ comments, header, headerActions, resolvedBanner, composer, footer, renderComment }: CommentThreadProps): JSX.Element;
 
 /** @public */
 export declare interface CommentThreadProps {
@@ -453,14 +612,18 @@ export declare interface CommentThreadProps {
     resolvedBanner?: ReactNode;
     /** Reply composer props. Omit for a read-only thread (no composer). */
     composer?: CommentComposerProps;
+    /** Shown at the bottom of the thread (e.g. a sign-in prompt when there's no composer). When
+     *  both are set, the footer renders after the composer. */
+    footer?: ReactNode;
     /** Override how each comment renders. Defaults to `<CommentCard>`. */
     renderComment?(comment: CommentCardProps, index: number): ReactNode;
 }
 
 /**
- * The comment tool. A click starts a point/shape thread (the pin tracks the shape it lands on);
- * dragging out a rectangle starts a region thread anchored to that area. Placement only opens a
- * composer (via `pendingComment`); the records are created when the comment is posted.
+ * The comment tool. Pressing down opens the comment composer at the pointer and it follows until
+ * release — like placing a sticky note — settling on a point, or on a shape when released over one.
+ * With region comments enabled, dragging past the threshold draws a region rectangle instead.
+ * Placement only opens a composer; the records are created when the comment is posted.
  * @public
  */
 export declare class CommentTool extends StateNode {
@@ -486,81 +649,172 @@ export declare class CommentTool extends StateNode {
      */
     options: CommentingOptions;
     onEnter(): void;
+    onExit(): void;
     onCancel(): void;
 }
 
 /** Registers the comment tool in the UI (icon, label, shortcut). Compose into your overrides.
- *  Once registered, tldraw's `DefaultToolbarContent` shows the comment button next to the eraser.
+ *  Once registered, tldraw's `DefaultQuickActionsContent` shows the comment button.
  * @public */
 export declare const commentToolOverrides: TLUiOverrides;
 
 /** @public */
 export declare const commentTools: typeof CommentTool[];
 
-/**
- * Commit a comment mutation with the configured undo/redo behavior. All comment writes go through
- * here so the {@link CommentingOptions.history} option (and {@link CommentingOptions.dragHistory}
- * for pin re-anchors) governs whether they land on the undo stack. Defaults to `'ignore'`.
- * @public
- */
-export declare function commitCommentMutation<T>(editor: Editor, fn: () => T, kind?: 'drag' | 'mutation'): T;
-
-/** @public */
-export declare function computeClusterTable(leaves: readonly LeafInput[], options: ClusterOptions): ClusterTable;
-
 /** @public @react */
-export declare function CountBadge({ count }: CountBadgeProps): JSX.Element;
+export declare function CountBadge({ count, open }: CountBadgeProps): JSX.Element;
 
 /** @public */
 export declare interface CountBadgeProps {
     count: number;
+    /** The badge's list is showing — shows the active/selected indicator state, as an open pin does. */
+    open?: boolean;
 }
 
-/** @public */
-export declare function createClusterRuntime(table: ClusterTable): ClusterRuntime;
+export { createMentionSuggestion }
 
 /**
- * Build the TipTap `suggestion` config for the comment \@-picker. `getSuggestions(query)` is the
- * host's resolver — it returns the members matching the query (sync or async); the SDK owns neither
- * the roster nor the filtering. The plugin runs outside React, so `render` mounts `MentionPopup` via
- * a `ReactRenderer`, forwards navigation keys through the popup's imperative handle, and lets it call
- * `command` to insert.
+ * The reaction emoji palette: the small, opinionated set the picker offers *and* the set a
+ * reaction is allowed to use. It's deliberately short — a quick affordance under a comment, not a
+ * full emoji keyboard — and it's the single source of truth for "which emoji may a reaction
+ * carry". A reaction's `emoji` field is a free-form `string`, so this palette is what keeps it to
+ * real, offered emoji; check membership with {@link isAllowedReactionEmoji}. Pass a custom `emoji`
+ * array to `ReactionPicker` to offer a different set — validate against that same set if you do.
+ *
  * @public
  */
-export declare function createMentionSuggestion(getSuggestions: (query: string) => MentionMember[] | Promise<MentionMember[]>, options?: MentionSuggestionOptions): Omit<SuggestionOptions<MentionMember, MentionNodeAttrs>, 'editor'>;
-
-/** Where an imprecise shape comment sits by default: the shape's top-right corner. Overridable. @public */
-export declare const DEFAULT_IMPRECISE_SHAPE_ANCHOR: {
-    x: number;
-    y: number;
-};
+export declare const DEFAULT_REACTION_EMOJI: string[];
 
-/** The out-of-the-box region config: disabled, and — when a consumer enables it — the current
- *  bottom-right / pointer-reveal / pin-move / corner-resize behaviour.
+/** The out-of-the-box view: every page's threads, resolved ones hidden until asked for.
  * @public */
-export declare const DEFAULT_REGION_COMMENT_OPTIONS: RegionCommentOptions;
-
-/** @public */
 export declare const DEFAULT_SIDEBAR_FILTERS: SidebarFilters;
 
+/**
+ * The default {@link CommentingOptions.canModifyComment}: a write is its record's owner's to make —
+ * a comment's author edits and deletes it, a thread's creator deletes the thread — and a viewer
+ * with no identity may make none of them.
+ *
+ * Exported so a callback can widen the default rather than restate it:
+ * `(ctx) => isModerator(ctx.currentUserId) || defaultCanModifyComment(ctx)`.
+ *
+ * @public
+ */
+export declare function defaultCanModifyComment(ctx: CommentModificationContext): boolean;
+
 /**
  * The default {@link CommentingOptions}. Override via `CommentTool.configure({ ... })`.
  *
  * @public
  */
 export declare const defaultCommentingOptions: {
-    readonly clusterCullMargin: 120;
-    readonly clusterSplitZoomFactor: 1.05;
+    readonly allowMultipleReactions: true;
+    readonly canComment: undefined;
+    readonly canModifyComment: undefined;
     readonly components: {};
     readonly dragHistory: undefined;
     readonly enableClustering: true;
+    readonly enableRegions: false;
     readonly history: "ignore";
     readonly impreciseShapeAnchor: {
         readonly x: 1;
         readonly y: 0;
     };
+    readonly isAllowedReaction: typeof isAllowedReactionEmoji;
+    readonly shouldBePrecise: () => true;
 };
 
+/**
+ * The default reactor tooltip: hangs the built-in inline sentence (`DefaultReactionTooltipContent`)
+ * in a standard tooltip below the pill — the same tooltip the toolbar uses. Replace it via
+ * `CommentingComponents.ReactionTooltip` to present the reactor list any other way (a different box,
+ * avatars, a banner, anywhere on screen); it receives the pill as `children`.
+ * @public @react
+ */
+export declare function DefaultReactionTooltip({ reactors, children }: ReactionTooltipProps): JSX.Element;
+
+/**
+ * The default reactor sentence naming who reacted — up to three names spelled out, then "and N
+ * others" (e.g. "You reacted", "You and Bo reacted", "You, Bo and Ada reacted", "You, Bo, Ada and 2
+ * others reacted"). The wording lives in the `comments.reacted-*` translation strings so each locale
+ * controls the grammar. Exported so a custom `ReactionTooltip` can reuse it inside its own box.
+ * @public @react
+ */
+export declare function DefaultReactionTooltipContent({ reactors }: {
+    reactors: ReactionReactor[];
+}): JSX.Element | null;
+
+/** The default reaction renderer: emits the token string for the OS emoji font to draw. @public */
+export declare function defaultRenderReaction(token: string): ReactNode;
+
+/**
+ * Delete a comment.
+ *
+ * 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.
+ *
+ * Deleting is the author's to do by default; {@link CommentingOptions.canModifyComment} widens
+ * that, as does its counterpart on the server.
+ *
+ * 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.
+ *
+ * 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 declare 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 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 declare function deleteThread(editor: Editor, thread: TLCommentThread): void;
+
+/**
+ * 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 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
+ * editComment(editor, comment, toRichText('Actually, make it dashed'))
+ * ```
+ *
+ * @public
+ */
+export declare function editComment(editor: Editor, comment: TLComment, body: TLRichText): void;
+
+/**
+ * A grid of emoji to react with. Presentational and unpositioned — the host owns placement and
+ * dismissal; `ReactionPicker` renders it in a dropdown under the add-reaction button.
+ * @public @react
+ */
+export declare function EmojiPicker({ emoji, selected, onSelect, renderReaction }: EmojiPickerProps): JSX.Element;
+
+/** @public */
+export declare interface EmojiPickerProps {
+    /** The emoji to offer. Defaults to `DEFAULT_REACTION_EMOJI`. */
+    emoji?: string[];
+    /** Emoji the current user has already reacted with; shown as pressed. */
+    selected?: string[];
+    /** Called when an emoji is chosen. */
+    onSelect?(emoji: string): void;
+    /** How to draw each emoji token. Defaults to the token string (OS emoji font). */
+    renderReaction?: RenderReaction;
+}
+
 /** The empty state shown when a thread has no comments yet. @public @react */
 export declare function EmptyState({ message }: EmptyStateProps): JSX.Element;
 
@@ -569,23 +823,51 @@ export declare interface EmptyStateProps {
     message: string;
 }
 
-/** Members whose name contains the query (case-insensitive), capped to the popup's length.
- * @public */
-export declare function filterMentionMembers(members: MentionMember[], query: string): MentionMember[];
+export { filterMentionMembers }
 
 /** Open a thread and bring it into view — switch to its page if needed, then center its pin. @public */
-export declare function focusThread(editor: Editor, thread: TLCommentThread, impreciseShapeAnchor?: {
-    x: number;
-    y: number;
-}): void;
+export declare function focusThread(editor: Editor, thread: TLCommentThread): void;
+
+/**
+ * Format an ISO datetime as a full date and time ("Tuesday, July 22, 2025 at 4:44 PM").
+ * Locale-aware via Intl.DateTimeFormat.
+ * @public
+ */
+export declare function formatFullDateTime(iso: string, locale?: string): string;
 
 /**
- * Format an ISO datetime as relative time ("2 hours ago", "yesterday", "last week").
+ * Format an ISO datetime as short relative time ("2 hr. ago", "yesterday", "last wk.").
  * Locale-aware via Intl.RelativeTimeFormat.
  * @public
  */
 export declare function formatRelativeTime(iso: string, locale?: string): string;
 
+/**
+ * Whether the viewer may participate in commenting, per {@link CommentingOptions.canComment}
+ * (defaulting to `currentUserId != null` when unset). A callback that throws denies.
+ *
+ * This is a plain, untracked read — in React, use {@link useCanComment} instead.
+ *
+ * @public
+ */
+export declare function getCanComment(editor: Editor, currentUserId: null | string | undefined): boolean;
+
+/**
+ * Whether the viewer may make a given write against a given record, per
+ * {@link CommentingOptions.canModifyComment} (defaulting to {@link defaultCanModifyComment} when
+ * unset). Where this is false the affordance isn't rendered.
+ *
+ * This is the per-record rule alone: the built-in UI additionally requires
+ * {@link CommentingOptions.canComment}, since a viewer who may not participate gets no action
+ * affordances at all.
+ *
+ * A plain, untracked read — a `canModifyComment` callback that reads signals is not observed. In
+ * React, use {@link useCanModifyComment} instead.
+ *
+ * @public
+ */
+export declare function getCanModifyComment(editor: Editor, currentUserId: null | string | undefined, modification: CommentModification): boolean;
+
 /**
  * The merged {@link CommentingOptions} for an editor, read off the registered comment tool (which
  * carries them via `CommentTool.configure`). Falls back to {@link defaultCommentingOptions} when
@@ -596,161 +878,322 @@ export declare function formatRelativeTime(iso: string, locale?: string): string
  */
 export declare function getCommentingOptions(editor: Editor): CommentingOptions;
 
+/** All comment reactions currently in the store (non-reactive; wrap in `useValue` to react). @public */
+export declare function getCommentReactions(editor: Editor): TLCommentReaction[];
+
 /** Read one comment record by id, or `undefined` if the id isn't a present comment record. @public */
 export declare function getCommentRecord(editor: Editor, id: string): TLCommentRecord | undefined;
 
-/** All comments currently in the store (non-reactive; wrap in `useValue` to react). @public */
+/**
+ * Every comment in the store, **including soft-deleted ones** awaiting the server's prune. For the
+ * set the UI shows, use {@link getLiveComments}.
+ *
+ * Non-reactive; wrap in `useValue`, or use `useComments`, to react.
+ * @public
+ */
 export declare function getComments(editor: Editor): TLComment[];
 
-/** All comment threads currently in the store (non-reactive; wrap in `useValue` to react). @public */
+/**
+ * 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
+ */
 export declare function getCommentThreads(editor: Editor): TLCommentThread[];
 
 /**
- * One comment thread's pin, already resolved to a page-space anchor point.
+ * The comments that should render: not soft-deleted. A deleted record lingers in the store until
+ * 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
  */
-export declare 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 \@-mention pill for referencing a person in a comment. @public @react */
-export declare function Mention({ name }: MentionProps): JSX.Element;
+export declare function getLiveComments(editor: Editor): TLComment[];
 
 /**
- * The \@-mention member picker: a popover list of people to mention, shown as the user types after
- * `@`. Presentational — the composer's suggestion plugin owns resolution, keyboard navigation, and
- * placement, and drives this with the host-resolved `members` and the highlighted `activeIndex`.
- * @public @react
+ * 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
  */
-export declare function MentionList({ members, activeIndex, onSelect, emptyLabel, renderMember }: MentionListProps): JSX.Element;
-
-/** @public */
-export declare interface MentionListProps {
-    /** Members to choose from — already resolved for the current query by the host. */
-    members: MentionMember[];
-    /** Index of the highlighted row, driven by the composer's keyboard navigation. */
-    activeIndex?: number;
-    /** Called when a member is chosen (click, or Enter on the active row). */
-    onSelect?(member: MentionMember): void;
-    /** Shown when no member matches the query. Defaults to a translated "No matches". */
-    emptyLabel?: string;
-    /** Override a row's content (inside the selectable button). Defaults to avatar + name (+ secondary). */
-    renderMember?(member: MentionMember): ReactNode;
-}
+export declare function getLiveCommentThreads(editor: Editor): TLCommentThread[];
 
-/** A person the composer's \@-mention picker can offer. @public */
-export declare interface MentionMember {
-    id: string;
-    name: string;
-    /** Avatar image URL. Falls back to a coloured initial when omitted. */
-    avatar?: string;
-    /** Avatar background colour, used when there's no `avatar` image. */
-    color?: string;
-    /** A secondary line under the name — e.g. an email or handle. Omit for a single-line row. */
-    secondary?: string;
-    /** Marks the current user; shown as a "(You)" suffix after the name. */
-    you?: boolean;
-    /** Hosts may carry extra fields; a custom `renderMember` can read them. */
-    [key: string]: unknown;
-}
-
-/** @public */
-export declare interface MentionProps {
-    name: string;
-}
+/**
+ * The id passed to the most recent {@link revealThread} call that `CanvasComments` hasn't served
+ * yet, or null. A request also clears when `CanvasComments` unmounts.
+ *
+ * This is a plain, untracked read — in React, use {@link useRevealThreadPending}, unless you need
+ * the value as of *now* rather than as of the render you closed over.
+ *
+ * @public
+ */
+export declare function getRevealThreadPending(editor: Editor): null | string;
 
-/** @public */
-export declare interface MentionSuggestionOptions {
-    /** Override a member row's content in the picker. Defaults to avatar + name (+ secondary). */
-    renderMember?(member: MentionMember): ReactNode;
-    /**
-     * The tldraw editor the composer lives in. When provided, the popup re-anchors reactively as the
-     * canvas camera moves (the composer rides it) instead of polling every frame. Omit off-canvas.
-     */
-    editor?: null | Editor;
-}
+/**
+ * Whether `emoji` belongs to a reaction palette (defaults to {@link DEFAULT_REACTION_EMOJI}). Use
+ * it to reject arbitrary strings before writing a reaction, so a scripted client can't spam a
+ * comment with junk `emoji` values that the picker would never offer. Pass a custom `palette` to
+ * match a customized picker.
+ *
+ * @public
+ */
+export declare function isAllowedReactionEmoji(emoji: string, palette?: readonly string[]): boolean;
 
 /**
- * A finalized merge event, ready for the runtime.
+ * Whether a click should be left to the browser's link handling (new tab, new window, or download).
  * @public
  */
-export declare interface MergeEvent {
-    zMerge: number;
-    /** Reverses (splits) when zoom \>= zSplit. Always \> zMerge. May be +Infinity. */
-    zSplit: number;
-    children: ClusterNode[];
-    result: ClusterNode;
-}
+export declare function isOpenInNewTabClick(e: MouseEvent_2): boolean;
+
+export { Mention }
+
+export { MentionList }
+
+export { MentionListProps }
+
+export { MentionMember }
+
+export { MentionProps }
+
+export { MentionSuggestionOptions }
 
 /** The id of the one open thread (only one popover is open at a time), or null when all closed.
  * @public */
 export declare const openThreadId: EditorAtom<null | string>;
 
-/** A comment being placed but not yet posted: where its composer sits and what it will anchor
- *  to. Shared between the tool (which sets it on click) and the overlay (which renders the
- *  composer). Null when nothing is being placed. The atom itself lives in `./state`
- *  ({@link pendingComment}), scoped per editor.
- * @public */
-export declare interface PendingComment {
-    anchor: TLCommentAnchor;
-    /** Page point where the composer opens (the click location, or a region's pin corner). */
-    point: VecLike;
-}
+/**
+ * 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}: comments are soft-deleted, and a synced server rejects the hard delete.
+ *
+ * @public
+ */
+export declare function putCommentRecords(editor: Editor, records: TLCommentRecord[]): void;
 
-/** The comment currently being placed (composer open, not yet posted), or null.
- * @public */
-export declare const pendingComment: EditorAtom<null | PendingComment>;
+/**
+ * A single emoji reaction pill with a count, highlighted when the user reacted. Hovering it shows a
+ * tooltip naming who reacted (the current user included), when `enableHoverList` is set.
+ * @public @react
+ */
+export declare function Reaction({ emoji, count, active, reactors, enableHoverList, renderReaction, ReactionTooltip, onClick }: ReactionProps): JSX.Element;
 
-/** Write comment records to the store. @public */
-export declare function putCommentRecords(editor: Editor, records: TLCommentRecord[]): void;
+/**
+ * The add-reaction affordance: a smiley button that opens an emoji grid.
+ *
+ * Anchored to its own button rather than to the reactions row, so the menu keeps its position as
+ * reactions are added and the row reflows.
+ *
+ * Picking an emoji dismisses the grid — adding and removing alike, since either way the picker has
+ * done its job — and hands focus back to the trigger.
+ * @public @react
+ */
+export declare function ReactionPicker({ emoji, selected, onSelect, renderReaction, palette: Palette, menuId, className }: ReactionPickerProps): JSX.Element;
 
-/** A single emoji reaction pill with a count, highlighted when the user reacted. @public @react */
-export declare function Reaction({ emoji, count, active }: ReactionProps): JSX.Element;
+/** @public */
+export declare interface ReactionPickerProps {
+    /** The emoji to offer. Defaults to `DEFAULT_REACTION_EMOJI`. */
+    emoji?: string[];
+    /** Emoji the current user has already reacted with; shown as pressed in the grid. */
+    selected?: string[];
+    /** Called when an emoji is chosen. */
+    onSelect?(emoji: string): void;
+    /** How to draw each emoji token. Defaults to the token string (OS emoji font). */
+    renderReaction?: RenderReaction;
+    /**
+     * What the button opens — the thing that produces a token. Defaults to `EmojiPicker`, the grid of
+     * emoji. Swap it for any component taking the same props to offer something else entirely (the
+     * drawn reactions example replaces it with a canvas you draw in); the props are passed straight
+     * through either way.
+     */
+    palette?: ComponentType<EmojiPickerProps>;
+    /**
+     * Identifies the menu in tldraw's global menu registry, which keys open/closed state by id.
+     * A thread renders one picker per comment, so this must differ per comment — sharing an id
+     * makes every picker in the thread open at once. Defaults to a per-instance generated id;
+     * pass one only for a stabler, more debuggable value.
+     */
+    menuId?: string;
+    /** Class for the trigger button. Defaults to the card-action style, matching the ⋯ button. */
+    className?: string;
+}
 
 /** @public */
 export declare interface ReactionProps {
     emoji: string;
     count: number;
     active: boolean;
+    /** How to draw the emoji token. Defaults to the token string (OS emoji font). */
+    renderReaction?: RenderReaction;
+    /** Who reacted with this emoji, in reaction order — shown when the pill is hovered. */
+    reactors: ReactionReactor[];
+    /** Whether hovering shows the reactor list. Pass false to suppress it — e.g. while another
+     *  popup menu on the comment is open. Defaults to true. */
+    enableHoverList?: boolean;
+    /** The hover affordance for the pill, naming who reacted. It receives the reactors and the pill
+     *  itself (as `children`) and returns the whole thing — so it owns the tooltip, its box, size,
+     *  shape, and position, not just the text inside. Defaults to `DefaultReactionTooltip`, which
+     *  hangs the built-in inline sentence below the pill. */
+    ReactionTooltip?: ComponentType<ReactionTooltipProps>;
+    /** Called when the pill is pressed — toggles the current user's reaction. */
+    onClick?(): void;
+}
+
+/** One person who reacted with a given emoji, for the hover list. @public */
+export declare interface ReactionReactor {
+    /** Display name of the person who reacted. */
+    name: string;
+    /** True for the current user. */
+    you: boolean;
+}
+
+/**
+ * The row of tallied reactions under a comment. Presentational — the host supplies the summaries
+ * and owns what toggling does. Hovering a pill lists who reacted (see `Reaction`).
+ *
+ * The add-reaction affordance is a separate component (`ReactionPicker`) so it can live outside
+ * this row — on a comment card it sits with the card's hover actions, which keeps its position
+ * fixed as reactions are added here.
+ * @public @react
+ */
+export declare function Reactions({ reactions, onToggle, canReact, enableHoverList, renderReaction, ReactionTooltip }: ReactionsProps): JSX.Element | null;
+
+/** @public */
+export declare interface ReactionsProps {
+    /** The comment's reactions, grouped by emoji. Empty renders nothing. */
+    reactions: ReactionSummary[];
+    /** Toggles the current user's reaction for an emoji. */
+    onToggle?(emoji: string): void;
+    /** Whether the current user may react. False makes the pills inert (e.g. a signed-out
+     *  viewer, or a read-only thread) while still showing counts. */
+    canReact?: boolean;
+    /** Whether hovering a pill shows its reactor list. Pass false to suppress it — e.g. while
+     *  another popup menu on the comment is open. Defaults to true. */
+    enableHoverList?: boolean;
+    /** How to draw each emoji token. Defaults to the token string (OS emoji font). */
+    renderReaction?: RenderReaction;
+    /** The tooltip naming who reacted, shown when a pill is hovered. Defaults to an inline sentence
+     *  (`DefaultReactionTooltip`). Swap it to render the reactor list however you like. */
+    ReactionTooltip?: ComponentType<ReactionTooltipProps>;
 }
 
-/** The row of reactions under a comment, plus an add-reaction button. @public @react */
-export declare function Reactions(): JSX.Element;
+/** One emoji's reactions on a comment, already tallied. @public */
+export declare interface ReactionSummary {
+    emoji: string;
+    /** How many people reacted with this emoji. */
+    count: number;
+    /** True when the current user is one of them — renders the pill highlighted. */
+    active: boolean;
+    /** Who reacted with this emoji, in reaction order — shown in the hover list. */
+    reactors: ReactionReactor[];
+}
 
 /**
- * The configurable dimensions of region comments — a design surface for prototyping the interaction
- * before settling it. Region is **off by default**, so a consumer that leaves it unset keeps plain
- * click-only point/shape commenting. Set it per editor through `<CanvasComments regionOptions>`.
+ * 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 declare interface RegionCommentOptions {
-    /** Whether dragging the comment tool out creates a region anchor. Off → click-only. */
-    enabled: boolean;
-    /** Which corner the pin and composer sit on, as a normalized 0–1 offset. Default bottom-right. */
-    pinCorner: VecLike;
-    /** When the dashed box and its handles reveal: while the pointer is within the region, while the
-     *  pin is hovered, or only while the thread is open. */
-    reveal: 'open' | 'pin-hover' | 'pointer';
-    /** How a region is moved: dragging its pin, dragging its body, or either. */
-    move: 'body' | 'both' | 'pin';
-    /** The resize affordance: corner handles, edge handles, or none. */
-    resize: 'corners' | 'edges' | 'none';
+export declare interface ReactionSummaryInput {
+    userId: string;
+    emoji: string;
+    createdAt: number;
 }
 
-/** Remove comment records from the store by id. @public */
-export declare function removeCommentRecords(editor: Editor, ids: (TLCommentId | TLCommentThreadId)[]): void;
+/** @public */
+export declare interface ReactionTooltipProps {
+    /** Who reacted with this emoji, in reaction order. */
+    reactors: ReactionReactor[];
+    /** The reaction pill to wrap. Anchor the hover affordance to this and render it. */
+    children: ReactNode;
+}
 
 /**
- * Minimal markdown for comment bodies: paragraphs, line breaks, bullet lists, and
- * inline **bold**, *italic*, `code`, and [links](url). Not a full CommonMark parser —
- * just the markdown people actually write in comments. Renders React elements only —
- * never raw HTML — so there's no HTML-injection surface.
+ * Keep shape-anchored threads alive across their shape's lifecycle:
+ *
+ * - When the shape is deleted, the thread converts to a `point` anchor where its pin last sat, so
+ *   the conversation outlives the shape instead of becoming invisible.
+ * - When the shape moves to another page, the thread follows: its `pageId` and each comment's
+ *   denormalized `pageId` update, and the anchor keeps riding the shape.
+ * - When a deleted shape comes back, the thread re-attaches — unless its pin was manually moved in
+ *   the meantime, in which case the manual placement wins.
+ *
+ * A page move is `deleteShapes` + re-create with preserved ids inside one `editor.run`, but each
+ * store write is its own operation, so "this shape is being moved" is never observable as a single
+ * event. The handlers therefore cooperate across operations: `beforeDelete` snapshots where each
+ * affected pin sits, the operation-complete pass converts threads whose shape is really gone, and
+ * `afterCreate` plus that same pass restore the anchor once the store has settled. Undo/redo of a
+ * move replays as a `parentId` update, so `afterChange` re-homes threads on cross-page reparents —
+ * including threads anchored to descendants, which move without change events of their own.
+ *
+ * Remote changes are ignored: the client that performed the operation runs this same maintenance
+ * and syncs the result. Writes honour the {@link CommentingOptions.history} option.
+ *
+ * Registered by `CanvasComments` on mount; parts-built consumers can call this directly. Returns a
+ * cleanup function that unregisters all handlers.
+ *
  * @public
  */
-export declare function renderMarkdown(text: string): ReactNode;
+export declare function registerCommentAnchorLifecycle(editor: Editor): () => void;
+
+/**
+ * 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: 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
+ */
+export declare function removeCommentRecords(editor: Editor, ids: (TLCommentId | TLCommentReactionId | TLCommentThreadId)[]): void;
+
+/** Render a reaction token to its visual — the emoji glyph by default. @public */
+export declare type RenderReaction = (token: string) => ReactNode;
+
+/**
+ * Reopen a resolved thread, clearing the resolution. A no-op on a thread that isn't resolved, and
+ * on one that's gone. Like {@link resolveThread}, it touches only the resolution.
+ *
+ * @public
+ */
+export declare function reopenThread(editor: Editor, thread: TLCommentThread): void;
+
+/**
+ * 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 a stale copy can't drag
+ * a pin back. A no-op on a thread that's gone.
+ *
+ * @public
+ */
+export declare function resolveThread(editor: Editor, thread: TLCommentThread, userId: string): void;
+
+/**
+ * Open a thread and bring it into view, given a thread id or the id of any comment in it. Use it to
+ * jump to a thread from outside the canvas — a notification, a deep link, your own list.
+ *
+ * The request is served by `CanvasComments`, so it works before the records have arrived: the layer
+ * waits for them, switches pages, unhides pins, and zooms far enough to split the thread out of any
+ * cluster. That also means nothing happens if `CanvasComments` isn't mounted.
+ *
+ * To open a thread you already hold and skip the wait, see {@link focusThread}.
+ *
+ * @example
+ * ```ts
+ * revealThread(editor, new URLSearchParams(location.search).get('comment')!)
+ * ```
+ *
+ * @public
+ */
+export declare function revealThread(editor: Editor, threadOrCommentId: string): void;
 
 /**
  * Flatten a rich-text comment body to plaintext through the limited comment extension set,
@@ -760,11 +1203,12 @@ export declare function renderMarkdown(text: string): ReactNode;
  */
 export declare function richTextToPlaintext(body: TLRichText, resolveName?: (id: string) => string | undefined): string;
 
-/** The button that posts a comment. @public @react */
+/** The button that posts a comment — an up arrow. @public @react */
 export declare function SendButton({ label, disabled, onClick }: SendButtonProps): JSX.Element;
 
 /** @public */
 export declare interface SendButtonProps {
+    /** The button's accessible name (e.g. "Send"). Shown as an up-arrow icon, so this is its label. */
     label: string;
     disabled?: boolean;
     onClick?(): void;
@@ -772,8 +1216,9 @@ export declare interface SendButtonProps {
 
 /**
  * A shape anchor for a page point. `x`/`y` are the point's normalized (0–1) offset within the
- * shape's page bounds, remembered either way. When `precise` (Alt held) the pin sits at exactly
- * `x`/`y`; otherwise it sits at the consumer's imprecise default (top-right out of the box).
+ * shape's own bounds, taken in the shape's own space, so a pin on a rotated shape records the spot
+ * it was dropped on. Remembered either way: when `precise` the pin sits at exactly `x`/`y`,
+ * otherwise at the consumer's imprecise default.
  * @public
  */
 export declare function shapeAnchorAt(editor: Editor, shapeId: TLShapeId, page: {
@@ -781,6 +1226,19 @@ export declare function shapeAnchorAt(editor: Editor, shapeId: TLShapeId, page:
     y: number;
 }, precise: boolean): TLCommentAnchor;
 
+/**
+ * The gesture that's creating a shape anchor, passed to
+ * {@link CommentingOptions.shouldBePrecise}: the target shape, the page point of the release, and
+ * whether Alt was held.
+ *
+ * @public
+ */
+export declare interface ShapeCommentPrecisionContext {
+    readonly shapeId: TLShapeId;
+    readonly point: VecLike;
+    readonly altKey: boolean;
+}
+
 /**
  * Which threads the comments sidebar shows. Held as an editor-scoped signal (the `sidebarFilters`
  * `EditorAtom` in `./state`) rather than component state so it survives the sidebar
@@ -803,23 +1261,91 @@ export declare interface SidebarFilters {
  * @public */
 export declare const sidebarFilters: EditorAtom<SidebarFilters>;
 
+/** A list row paired with the sort key that isn't part of what the row displays. @public */
+export declare interface SidebarRow {
+    item: CommentListItemProps;
+    /** When the thread's most recent comment was posted — what the list orders by. */
+    lastActivity: number;
+}
+
+/**
+ * Order the list: unresolved threads first, then by most recent activity, id as a stable tiebreak.
+ * Recency is the thread's *latest* comment, not its first, so a thread someone just replied to rises
+ * to the top instead of staying wherever it was started. (The row still shows the thread's opening
+ * comment and its date — that's what identifies the thread; only the ordering follows the replies.)
+ *
+ * Exported so a hand-built list can match the sidebar's ordering instead of re-deriving it.
+ *
+ * @public
+ */
+export declare function sortSidebarRows(rows: readonly SidebarRow[]): readonly SidebarRow[];
+
+/**
+ * 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 declare function summarizeReactions(reactions: readonly ReactionSummaryInput[], currentUserId?: null | string, resolveName?: (userId: string) => string | undefined): ReactionSummary[];
+
+/**
+ * Typed reads of comment records on the editor store.
+ *
+ * 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, but also answer to the undo/redo policy, so they live in
+ * `comment-mutations.ts`.
+ */
+/**
+ * A record that lives in a comment thread: the thread itself, one of its messages, or a reaction
+ * to one of those messages.
+ * @public
+ */
+export declare type TLCommentRecord = TLComment | TLCommentReaction | TLCommentThread;
+
 /**
- * Typed access to comment records on the editor store.
+ * 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 touches that user's
+ * own records and two people reacting at once never conflict. Behaviour depends on
+ * `allowMultipleReactions`:
+ *
+ * - **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.
  *
- * 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.
+ * @public
  */
-/** A record that lives in a comment thread: the thread itself or one of its messages. @public */
-export declare type TLCommentRecord = TLComment | TLCommentThread;
+export declare function toggleCommentReaction(editor: Editor, comment: TLComment, userId: string, emoji: string, now?: number): void;
 
 /** Toggle comment-pin visibility for an editor.
  * @public */
 export declare function toggleCommentsHidden(editor: Editor): void;
 
+/** Open or close the comments sidebar for an editor.
+ * @public */
+export declare function toggleCommentsSidebar(editor: Editor): void;
+
+/**
+ * Reactive React hook for {@link getCanComment}: a `canComment` callback that reads signals
+ * re-evaluates when they change.
+ *
+ * @public
+ */
+export declare function useCanComment(currentUserId: null | string | undefined): boolean;
+
+/**
+ * Reactive React hook for {@link getCanModifyComment}: a `canModifyComment` callback that reads
+ * signals re-evaluates when they change.
+ *
+ * @public
+ */
+export declare function useCanModifyComment(currentUserId: null | string | undefined, modification: CommentModification): boolean;
+
 /**
  * Whether commenting is licensed for this editor. Enabled in development; in production it requires
  * a tldraw license that includes the commenting feature (or the collaboration umbrella that grants
@@ -827,7 +1353,7 @@ export declare function toggleCommentsHidden(editor: Editor): void;
  * pending, so gated UI stays hidden until the license is confirmed.
  *
  * The built-in commenting components (`CanvasComments`, `CanvasCommentsSidebar`, and the comment
- * tool's toolbar button) gate on this. Use it to gate any custom commenting UI the same way.
+ * tool's Quick Action) gate on this. Use it to gate any custom commenting UI the same way.
  * @public
  */
 export declare function useCommentingEnabled(): boolean;
@@ -840,29 +1366,54 @@ export declare function useCommentingEnabled(): boolean;
  */
 export declare function useCommentingOptions(): CommentingOptions;
 
-/** Every comment in the store, oldest first, reactively. Group by `threadId` for per-thread lists. @public */
+/**
+ * One comment's reactions, oldest first, reactively.
+ *
+ * @public
+ */
+export declare function useCommentReactions(editor: Editor, commentId: TLComment['id']): TLCommentReaction[];
+
+/** Every live comment in the store ({@link getLiveComments}), oldest first, reactively. Group by
+ *  `threadId` for per-thread lists. @public */
 export declare function useComments(editor: Editor): TLComment[];
 
 /** React hook for whether comment pins are hidden.
  * @public */
 export declare function useCommentsHidden(): boolean;
 
-/** All comment threads in the store, reactively. @public */
+/** React hook for whether the comments sidebar is open.
+ * @public */
+export declare function useCommentsSidebarOpen(): boolean;
+
+/**
+ * The comment threads that should render (pins, sidebar), reactively — the live set described by
+ * {@link getLiveCommentThreads}. Use `getCommentThreads` for the unfiltered set, including
+ * soft-deleted threads awaiting the server's prune.
+ *
+ * @public
+ */
 export declare function useCommentThreads(editor: Editor): TLCommentThread[];
 
 /** React hook for the open thread id.
  * @public */
 export declare function useOpenThreadId(): null | string;
 
-/** React hook for the pending (being-placed) comment.
- * @public */
-export declare function usePendingComment(): null | PendingComment;
+/**
+ * Reactive React hook for {@link getRevealThreadPending}.
+ *
+ * Use it to notice a reveal that never lands — usually a deep link to a deleted comment. Give it a
+ * grace period first, since a request also sits here while its records sync in, and re-check with
+ * {@link getRevealThreadPending} when it elapses.
+ *
+ * @public
+ */
+export declare function useRevealThreadPending(): null | string;
 
 /** React hook for the current sidebar filters.
  * @public */
 export declare function useSidebarFilters(): SidebarFilters;
 
-/** A thread's comments, oldest first, reactively. @public */
+/** A thread's live comments, oldest first, reactively. @public */
 export declare function useThreadComments(editor: Editor, threadId: TLCommentThreadId): TLComment[];
 
 export { }