@tldraw/commenting 0.0.0-bootstrap → 5.3.0-canary.31036673d3f8

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';
@@ -20,46 +32,35 @@ 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`.
+ * shape anchors the pin uses the editor's {@link CommentingOptions.impreciseShapeAnchor} (a
+ * normalized 0–1 spot, top-right by default) rather than the stored `x`/`y`.
+ *
+ * A shape anchor's `x`/`y` are normalized within the shape's own bounds and resolved through the
+ * shape's page transform, so the pin rides every part of that transform — rotating the shape
+ * carries the pin around with it instead of leaving it 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 */
 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
@@ -69,143 +70,48 @@ export declare function CanvasComments(props: CanvasCommentsProps): JSX.Element
  * 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.
+ *
+ * The host wiring — who the viewer is, how ids become names, read status, mentions — is the
+ * {@link CommentingContext}, which `CanvasCommentsSidebar` takes too, so a host mounting both can
+ * build it once and spread it into each.
+ *
+ * @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 +129,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 +144,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 +155,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 +167,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 +200,88 @@ export declare interface CommentingComponents {
     ThreadPreview?: ComponentType<{
         comment: TLComment;
     }>;
+    /**
+     * A reaction's visual, given its token. The default renders the token string for the OS emoji
+     * font to draw (so the token is the emoji glyph). Override this to render your own palette —
+     * return an `<img>` for custom emoji, an SVG, or anything. The token is whatever your picker
+     * emits and is what gets stored/synced; this only controls how it's drawn.
+     */
+    ReactionContent?: ComponentType<{
+        token: string;
+    }>;
+    /**
+     * What the add-reaction button opens: the thing that produces a reaction token. Replaces the
+     * default `<EmojiPicker>` grid. Pairs with `ReactionContent` (which draws whatever tokens this
+     * emits) and with `isAllowedReaction` (which has to accept them).
+     */
+    ReactionPalette?: ComponentType<EmojiPickerProps>;
+    /**
+     * The hover affordance naming who reacted with an emoji. It receives the reactors and the pill
+     * (as `children`) and returns the whole thing — so it owns the tooltip, its box, size, shape, and
+     * position. Replaces the default (`DefaultReactionTooltip`). For a simple wording change, translate
+     * the `comments.reacted-*` strings instead; reach for this to change the structure — a different
+     * box, avatars, a banner anywhere on screen.
+     */
+    ReactionTooltip?: ComponentType<ReactionTooltipProps>;
+    /** Shown where a composer would sit when the viewer can't compose (see
+     *  {@link CommentingOptions.canComment} — a signed-out viewer, a viewer role, a host that
+     *  turns commenting off). `context` says which surface is rendering it: the bottom of an open
+     *  thread popover (`'thread'`) or the placement popover the comment tool opens (`'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 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;
+    /**
+     * 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}.
  *
@@ -321,15 +308,60 @@ 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} against
+     * the built-in emoji palette, which is what keeps a scripted client from writing junk `emoji`
+     * values the picker would never offer. Override it alongside a custom `ReactionPalette` so the
+     * tokens that palette emits get through. Removals aren't checked — a reaction carrying an
+     * off-palette token 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 of the page, drawn as a dashed box with the thread's pin on the corner the
+     * drag released on. Off by default: comments attach to points and shapes only, and a drag just
+     * trails the composer. A region reveals its box while the pointer is inside it, moves by its
+     * pin, and resizes from its corners.
+     */
+    readonly enableRegions: boolean;
+    /**
+     * Whether the viewer may participate in commenting: composing new threads and replies, editing
+     * and deleting comments, resolving threads, and moving pins or regions. Composers render when
+     * it returns true; when it returns false, the {@link CommentingComponents.ComposerFallback}
+     * slot renders in their place (or nothing, if that slot is unset) and the action affordances
+     * are hidden. Unset, participation is allowed exactly when `currentUserId` is set.
+     *
+     * Called during render via {@link useCanComment}, so reactive reads (signals) are tracked.
+     * The comment tool itself stays registered and selectable — hosts that want its toolbar button
+     * to do something else (e.g. open a sign-in dialog) can override the tool item's `onSelect`.
+     * Note posting still requires a `currentUserId` to author the records, so a callback that
+     * returns true for a signed-out viewer yields a composer whose send button stays disabled.
+     */
+    readonly canComment: ((ctx: {
+        currentUserId: null | string;
+        editor: Editor;
+    }) => 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 anchors precisely — pinned to the exact clicked spot
+     * within the shape — or imprecisely — pinned to the shape as a whole, rendered at
+     * `impreciseShapeAnchor`. Called wherever a shape anchor is created (placing with the comment
+     * tool, dropping a dragged pin onto a shape). Always precise by default. Return `false` for
+     * shape-level anchoring, or decide from the context — the Alt key's state, or the shape itself,
+     * e.g. precise only on notes. Governs new placements only; existing anchors render as stored.
+     */
+    shouldBePrecise(editor: Editor, context: ShapeCommentPrecisionContext): boolean;
     /** Component overrides. See {@link CommentingComponents}. */
     readonly components: CommentingComponents;
 }
@@ -337,7 +369,7 @@ export declare interface CommentingOptions {
 /** @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,6 +381,11 @@ export declare interface CommentListItemProps {
     count?: number;
     /** Whether this thread is the open one. */
     selected?: boolean;
+    /**
+     * 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;
 }
 
 /** A canvas comment marker: shows its `children` (or a check when resolved). Purely
@@ -366,6 +403,40 @@ export declare interface CommentPinProps {
     open?: boolean;
 }
 
+/**
+ * The add-reaction button for one comment. Belongs with the comment card's hover actions (under
+ * the ⋯ button) rather than in the reaction row, so opening it doesn't chase the row as reactions
+ * are added.
+ * @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 the id. */
+    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;
@@ -424,14 +495,19 @@ 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 — a button
+ * next to Share on dotcom — rather than by which tool is active, so browsing threads is separate
+ * from placing them. The comment tool additionally closes it on enter, keeping placement
+ * canvas-focused.
+ * @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 +515,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 +529,19 @@ 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 immediately at the pointer, and it
+ * follows the pointer 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 instead
+ * draws a region rectangle.) Placement only opens a composer (via `pendingComment`); the records
+ * are created when the comment is posted.
  * @public
  */
 export declare class CommentTool extends StateNode {
@@ -486,6 +567,7 @@ export declare class CommentTool extends StateNode {
      */
     options: CommentingOptions;
     onEnter(): void;
+    onExit(): void;
     onCancel(): void;
 }
 
@@ -497,50 +579,32 @@ 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;
 
 /**
@@ -549,18 +613,120 @@ export declare const DEFAULT_SIDEBAR_FILTERS: SidebarFilters;
  * @public
  */
 export declare const defaultCommentingOptions: {
-    readonly clusterCullMargin: 120;
-    readonly clusterSplitZoomFactor: 1.05;
+    readonly allowMultipleReactions: true;
+    readonly canComment: 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 the record's `isDeleted` flag rather than removing it, and the
+ * server prunes the comment and its reactions once the flag is persisted. That way no client ever
+ * removes records it doesn't own — a reaction belongs to whoever left it — and a server enforcing
+ * per-record permissions has a write it can check rather than a deletion it can only refuse.
+ * Deleting is the author's to do; the built-in UI only offers it on your own comments.
+ *
+ * The write is never undoable, whatever {@link CommentingOptions.history} says: the flag is
+ * write-once server-side, so an undo clearing it would be vetoed and rebased rather than bring the
+ * comment back.
+ *
+ * Deleting a thread's last comment leaves the thread with no surface — an empty thread renders
+ * nothing — and closes it if it's open. The thread record is left for the server to prune, since
+ * the deleter may not be its creator.
+ *
+ * A comment that's already deleted, or already pruned, 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 flag goes on the thread record and
+ * the server prunes the thread, its comments, and their reactions once it's persisted. Deleting a
+ * thread is its creator's to do — a server enforcing per-record permissions vetoes anyone else —
+ * and the write is never undoable.
+ *
+ * Closes the thread if it's the open one. A thread that's already pruned is a no-op.
+ *
+ * @public
+ */
+export declare function deleteThread(editor: Editor, thread: TLCommentThread): void;
+
+/**
+ * Replace a comment's body and stamp it as edited, which is what renders the "(edited)" marker on
+ * its byline.
+ *
+ * Editing is the author's to do. The built-in UI only offers it on your own comments, and a server
+ * that enforces per-record permissions rejects anyone else's edit.
+ *
+ * The `comment` you pass says which comment to edit; the body lands on the version the store
+ * currently holds, so a copy you've held on to can't revert a change made since it, and can't
+ * re-create a comment that's already been removed — editing one of those does nothing.
+ *
+ * @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 +735,30 @@ 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 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). Where this is false, composers give way to
+ * the {@link CommentingComponents.ComposerFallback} slot and action affordances are hidden.
+ *
+ * This is a plain, untracked read — a `canComment` callback that reads signals is not observed.
+ * In React, use {@link useCanComment} instead.
+ *
+ * @public
+ */
+export declare function getCanComment(editor: Editor, currentUserId: null | string | undefined): 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 +769,328 @@ 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 ones** and ones left empty by their
+ * last comment's delete — records that are still present but awaiting the server's prune, and that
+ * nothing renders. For the set the UI shows, use {@link getLiveCommentThreads}.
+ *
+ * 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 this — not {@link getComments} — is what a count or a list of your own
+ * should be built from.
+ *
+ * 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): live — not soft-deleted — and still
+ * holding at least one live comment. A soft-deleted thread or comment is awaiting the server's
+ * prune, as is a thread emptied by its last comment's delete; until the prune lands, the emptied
+ * thread record lingers with no surface.
+ *
+ * Non-reactive; the reactive equivalent is `useCommentThreads`.
+ * @public
  */
-export declare function MentionList({ members, activeIndex, onSelect, emptyLabel, renderMember }: MentionListProps): JSX.Element;
+export declare function getLiveCommentThreads(editor: Editor): TLCommentThread[];
 
-/** @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;
-}
-
-/** 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 when there's nothing outstanding. A request also clears when `CanvasComments`
+ * unmounts, since nothing is left to serve it.
+ *
+ * This is a plain, untracked read. In React, use {@link useRevealThreadPending} — but reach for
+ * this one inside a timer or callback that needs the value as of *now* rather than as of the
+ * render it 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 — so a record you write lands on the undo stack (or
+ * doesn't) exactly like one the built-in UI writes. Defaults to `'ignore'`.
+ *
+ * Use it to seed or import threads, and to save an edit. To delete, prefer
+ * {@link deleteComment} and {@link deleteThread} over {@link removeCommentRecords}: comments are
+ * soft-deleted, and a synced server rejects the hard delete.
+ *
+ * @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>;
+}
+
+/** 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 row of reactions under a comment, plus an add-reaction button. @public @react */
-export declare function Reactions(): JSX.Element;
+/** @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;
+}
 
 /**
- * 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>`.
+ * Keep shape-anchored threads alive across their shape's lifecycle:
+ *
+ * - When the shape is deleted, the thread converts to a `point` anchor at the spot its pin last
+ *   occupied, so the conversation outlives the shape instead of becoming invisible (a missing
+ *   shape has no bounds, which hides the pin).
+ * - When the shape moves to another page, the thread follows: its `pageId` and each comment's
+ *   denormalized `pageId` update to the shape's new page, and the anchor keeps riding the shape.
+ * - When a deleted shape comes back (a page move re-creates it with its id preserved; undoing a
+ *   delete restores it), 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 at no single moment does "this shape is being moved"
+ * exist as an observable event. The handlers therefore cooperate across operations:
+ * `beforeDelete` snapshots where each affected pin sits (every record is still in the store at
+ * that point, so page bounds resolve even for children of a deleted frame); the
+ * operation-complete pass converts threads whose shape is really gone, remembering the original
+ * anchor; `afterCreate` notes a reappeared shape id, and the operation-complete pass restores
+ * the anchor once the store has settled (creation order within an operation is arbitrary, so a
+ * fresh shape may not resolve an ancestor page mid-operation). Undo/redo of a move
+ * replays as a `parentId` update (remove + add of one id squash to an update in the history
+ * diff), so an `afterChange` handler re-homes threads on cross-page reparents — including
+ * threads anchored to descendants, which move with their parent without change events of their
+ * own.
+ *
+ * Remote changes are ignored: the client that performed the operation runs this same
+ * maintenance and syncs the resulting thread updates. Writes honour the
+ * {@link CommentingOptions.history} option, so the consumer decides whether they're undoable.
+ *
+ * Registered by `CanvasComments` on mount; parts-built consumers can call this directly.
+ * Returns a cleanup function that unregisters all handlers.
+ *
  * @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 function registerCommentAnchorLifecycle(editor: Editor): () => void;
 
-/** Remove comment records from the store by id. @public */
-export declare function removeCommentRecords(editor: Editor, ids: (TLCommentId | TLCommentThreadId)[]): 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 for a comment or a thread: the built-in UI
+ * soft-deletes them ({@link deleteComment}, {@link deleteThread}) so the server can prune the
+ * records — including reactions, which belong to whoever left them rather than to the deleter. A
+ * server that enforces per-record permissions will veto a hard delete outright. Reach for this on
+ * a local, unsynced comment store, or to drop a reaction (which is a hard delete — see
+ * {@link toggleCommentReaction}).
+ *
+ * @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;
 
 /**
- * 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.
+ * 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 resolving with a stale
+ * copy in hand won't drag a pin back to where it used to be. A no-op on a thread that's gone.
+ *
+ * @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 to sync in, switches pages if it needs to, unhides pins, zooms in far
+ * enough to split the thread out of any cluster it's folded into, and then opens it. 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 renderMarkdown(text: string): ReactNode;
+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 +1100,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 +1113,11 @@ 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 placed on a rotated shape records
+ * the spot it was dropped on rather than a spot in the bounding box. Remembered either way: when
+ * `precise` the pin sits at exactly `x`/`y`; otherwise it sits at the consumer's imprecise default
+ * (top-right out of the box). Placement gestures get `precise` from the `shouldBePrecise`
+ * commenting option (always precise, by default).
  * @public
  */
 export declare function shapeAnchorAt(editor: Editor, shapeId: TLShapeId, page: {
@@ -781,6 +1125,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
@@ -804,7 +1161,18 @@ export declare interface SidebarFilters {
 export declare const sidebarFilters: EditorAtom<SidebarFilters>;
 
 /**
- * Typed access to comment records on the editor store.
+ * Tally a comment's reactions into an entry per emoji, ordered by when that emoji was first used
+ * so the row stays stable as later reactions arrive. `active` marks the emoji the current user
+ * reacted with (the pills render those highlighted), and `reactors` lists who reacted with it, in
+ * reaction order, for the hover list. `resolveName` names each reactor; an id it can't name falls
+ * back to the id itself.
+ *
+ * @public
+ */
+export declare function summarizeReactions(reactions: TLCommentReaction[], currentUserId?: null | string, resolveName?: (userId: string) => string | undefined): ReactionSummary[];
+
+/**
+ * Typed reads of comment records on the editor store.
  *
  * Comment threads and comments live on the editor's local store so the canvas can render them
  * reactively, but they are opt-in records that aren't part of the `TLRecord` union (they ride the
@@ -812,14 +1180,49 @@ export declare const sidebarFilters: EditorAtom<SidebarFilters>;
  * 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.
+ *
+ * Writes do the same reinterpretation, but they also answer to the undo/redo policy, so they live
+ * with the rest of the write path in `comment-mutations.ts`.
  */
-/** A record that lives in a comment thread: the thread itself or one of its messages. @public */
-export declare type TLCommentRecord = TLComment | TLCommentThread;
+/**
+ * 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;
+
+/**
+ * Toggle one user's reaction with a given emoji on a comment.
+ *
+ * Each reaction is its own record keyed by (comment, user, emoji), so this only ever touches that
+ * one user's own records — two people reacting at once never conflict. Behaviour depends on the
+ * `allowMultipleReactions` option:
+ *
+ * - **multiple** (default): the emoji toggles independently — add it if absent, remove it if
+ *   present, leaving the user's other reactions alone.
+ * - **single**: picking a new emoji first removes the user's existing reaction(s) on the comment,
+ *   then adds this one (a replace); picking the one they already have removes it.
+ *
+ * @public
+ */
+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;
+
 /**
  * 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
@@ -840,29 +1243,56 @@ 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 — most often a deep link to a comment that has since
+ * been deleted. Give it a grace period before you act: a request also sits here while its records
+ * are still syncing in, which is the normal case on a cold load. Re-check with
+ * {@link getRevealThreadPending} when the grace period elapses, since the request can clear inside
+ * it without this hook's value having caught up yet.
+ *
+ * @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 { }