@tldraw/commenting 5.3.0-next.d7d8ced023d5 → 5.3.0-next.dec36c5c2930

package/dist-esm/index.d.mts

@@ -31,13 +31,11 @@ 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 the editor's {@link CommentingOptions.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 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.
+ * 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): {
@@ -49,7 +47,11 @@ export { Avatar }
 
 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 */
@@ -66,14 +68,11 @@ export declare interface BylineProps {
  * 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.
- *
- * 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.
+ * 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
  */
@@ -200,34 +199,49 @@ 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 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.
+     * 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: 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).
+     * 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. 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.
+     * 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} — 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. */
+    /**
+     * 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';
     }>;
@@ -261,10 +275,11 @@ export declare interface CommentingContext {
     /** 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.
+     * 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.
      */
-    onCommentRead?(commentId: TLCommentId): void;
+    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. */
@@ -294,11 +309,9 @@ export declare interface CommentingContext {
  */
 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'];
     /**
@@ -316,56 +329,77 @@ export declare interface CommentingOptions {
      */
     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.
+     * 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 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.
+     * 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 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.
+     * 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 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.
+     * 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;
     };
     /**
-     * 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.
+     * 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;
@@ -381,6 +415,9 @@ 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`.
@@ -388,6 +425,51 @@ export declare interface CommentListItemProps {
     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 */
@@ -404,9 +486,8 @@ export declare interface CommentPinProps {
 }
 
 /**
- * The add-reaction button for one comment. Belongs with the comment card's hover actions (under
- * the ⋯ button) rather than in the reaction row, so opening it doesn't chase the row as reactions
- * are added.
+ * The add-reaction button for one comment. Belongs with the comment card's hover actions rather
+ * than in the reaction row, so opening it doesn't chase the row as reactions are added.
  * @public @react
  */
 export declare function CommentReactionPicker({ comment, currentUserId, emoji }: CommentReactionPickerProps): JSX.Element | null;
@@ -433,7 +514,7 @@ export declare interface CommentReactionsProps {
     /** 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. */
+    /** Names a reactor id for the hover list. Ids it can't name fall back to a generic "Someone". */
     resolveName?(userId: string): string | undefined;
 }
 
@@ -477,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;
 }
 
 /**
@@ -496,10 +581,8 @@ export declare function CommentsMenuItem(): JSX.Element;
 export declare function CommentsOverflowMenu(): 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.
+ * 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>;
@@ -537,11 +620,12 @@ export declare interface CommentThreadProps {
 }
 
 /**
- * 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.
+ * 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. The tool
+ * stays active while the composer is open — posting returns to select, and clicking elsewhere
+ * re-places the composer.
  * @public
  */
 export declare class CommentTool extends StateNode {
@@ -572,7 +656,7 @@ export declare class CommentTool extends StateNode {
 }
 
 /** 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;
 
@@ -607,6 +691,18 @@ export declare const DEFAULT_REACTION_EMOJI: string[];
  * @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({ ... })`.
  *
@@ -615,6 +711,7 @@ export declare const DEFAULT_SIDEBAR_FILTERS: SidebarFilters;
 export declare const defaultCommentingOptions: {
     readonly allowMultipleReactions: true;
     readonly canComment: undefined;
+    readonly canModifyComment: undefined;
     readonly components: {};
     readonly dragHistory: undefined;
     readonly enableClustering: true;
@@ -654,21 +751,18 @@ 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.
+ * This is a soft delete: it sets `isDeleted` rather than removing the record, and the server prunes
+ * the comment and its reactions once the flag is persisted — so no client removes records it
+ * doesn't own, and a server enforcing per-record permissions has a write it can check.
  *
- * The write is never undoable, whatever {@link CommentingOptions.history} says: the flag is
- * write-once server-side, so an undo clearing it would be vetoed and rebased rather than bring the
- * comment back.
+ * Deleting is the author's to do by default; {@link CommentingOptions.canModifyComment} widens
+ * that, as does its counterpart on the server.
  *
- * Deleting a thread's last comment leaves the thread with no surface — an empty thread renders
- * nothing — and closes it if it's open. The thread record is left for the server to prune, since
- * the deleter may not be its creator.
+ * Never undoable, whatever {@link CommentingOptions.history} says: the flag is write-once
+ * server-side, so an undo clearing it would be vetoed rather than bring the comment back.
  *
- * A comment that's already deleted, or already pruned, is a no-op.
+ * Deleting a thread's last comment closes it and leaves the thread record for the server to prune,
+ * since the deleter may not be its creator. An already-deleted comment is a no-op.
  *
  * @public
  */
@@ -677,27 +771,23 @@ 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.
+ * 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 is what renders the "(edited)" marker on
- * its byline.
+ * 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.
  *
- * 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.
+ * 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
@@ -741,7 +831,14 @@ export { filterMentionMembers }
 export declare function focusThread(editor: Editor, thread: TLCommentThread): void;
 
 /**
- * Format an ISO datetime as short relative time ("2 hr. ago", "yesterday", "last wk.").
+ * 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 compact relative time ("2h ago", "yesterday", "last wk.").
  * Locale-aware via Intl.RelativeTimeFormat.
  * @public
  */
@@ -749,16 +846,30 @@ 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.
+ * (defaulting to `currentUserId != null` when unset). A callback that throws denies.
  *
- * This is a plain, untracked read — a `canComment` callback that reads signals is not observed.
- * In React, use {@link useCanComment} instead.
+ * 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
@@ -785,9 +896,8 @@ export declare function getCommentRecord(editor: Editor, id: string): TLCommentR
 export declare function getComments(editor: Editor): TLComment[];
 
 /**
- * Every comment thread in the store, **including soft-deleted ones** and ones left empty by their
- * last comment's delete — records that are still present but awaiting the server's prune, and that
- * nothing renders. For the set the UI shows, use {@link getLiveCommentThreads}.
+ * Every comment thread in the store, **including soft-deleted and emptied ones** awaiting the
+ * server's prune, which nothing renders. For the set the UI shows, use {@link getLiveCommentThreads}.
  *
  * Non-reactive; wrap in `useValue`, or use `useCommentThreads`, to react.
  * @public
@@ -796,8 +906,7 @@ export declare function getCommentThreads(editor: Editor): TLCommentThread[];
 
 /**
  * The comments that should render: not soft-deleted. A deleted record lingers in the store until
- * the server prunes it, so this — not {@link getComments} — is what a count or a list of your own
- * should be built from.
+ * the server prunes it, so build counts and lists from this rather than {@link getComments}.
  *
  * Non-reactive; the reactive equivalent is `useComments` (which also sorts oldest first).
  * @public
@@ -805,10 +914,9 @@ export declare function getCommentThreads(editor: Editor): TLCommentThread[];
 export declare function getLiveComments(editor: Editor): TLComment[];
 
 /**
- * The comment threads that should render (pins, sidebar): live — not soft-deleted — and still
- * holding at least one live comment. A soft-deleted thread or comment is awaiting the server's
- * prune, as is a thread emptied by its last comment's delete; until the prune lands, the emptied
- * thread record lingers with no surface.
+ * The comment threads that should render (pins, sidebar): not soft-deleted, and still holding at
+ * least one live comment. A thread emptied by its last comment's delete lingers with no surface
+ * until the server's prune lands.
  *
  * Non-reactive; the reactive equivalent is `useCommentThreads`.
  * @public
@@ -817,12 +925,10 @@ export declare function getLiveCommentThreads(editor: Editor): TLCommentThread[]
 
 /**
  * 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.
+ * yet, or null. A request also clears when `CanvasComments` unmounts.
  *
- * 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.
+ * 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
  */
@@ -861,13 +967,11 @@ export { MentionSuggestionOptions }
 export declare const openThreadId: EditorAtom<null | string>;
 
 /**
- * Write comment records to the store, under the configured
- * {@link CommentingOptions.history} behavior — so a record you write lands on the undo stack (or
- * doesn't) exactly like one the built-in UI writes. Defaults to `'ignore'`.
+ * Write comment records to the store, under the configured {@link CommentingOptions.history}
+ * behavior. Defaults to `'ignore'`.
  *
- * Use it to seed or import threads, and to save an edit. To delete, prefer
- * {@link deleteComment} and {@link deleteThread} over {@link removeCommentRecords}: comments are
- * soft-deleted, and a synced server rejects the hard delete.
+ * Use it to seed or import threads, and to save an edit. To delete, prefer {@link deleteComment}
+ * and {@link deleteThread}: comments are soft-deleted, and a synced server rejects the hard delete.
  *
  * @public
  */
@@ -990,6 +1094,19 @@ export declare interface ReactionSummary {
     reactors: ReactionReactor[];
 }
 
+/**
+ * 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 ReactionSummaryInput {
+    userId: string;
+    emoji: string;
+    createdAt: number;
+}
+
 /** @public */
 export declare interface ReactionTooltipProps {
     /** Who reacted with this emoji, in reaction order. */
@@ -1001,35 +1118,26 @@ export declare interface ReactionTooltipProps {
 /**
  * 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 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 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.
+ *   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 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.
+ * 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
  */
@@ -1039,12 +1147,10 @@ export declare function registerCommentAnchorLifecycle(editor: Editor): () => vo
  * Remove comment records from the store by id, under the configured
  * {@link CommentingOptions.history} behavior.
  *
- * This is a hard delete, which is rarely what you want for a comment or a thread: the built-in UI
- * soft-deletes them ({@link deleteComment}, {@link deleteThread}) so the server can prune the
- * records — including reactions, which belong to whoever left them rather than to the deleter. A
- * server that enforces per-record permissions will veto a hard delete outright. Reach for this on
- * a local, unsynced comment store, or to drop a reaction (which is a hard delete — see
- * {@link toggleCommentReaction}).
+ * This is a hard delete, which is rarely what you want: the built-in UI soft-deletes
+ * ({@link deleteComment}, {@link deleteThread}) so the server can prune the records, and a server
+ * enforcing per-record permissions vetoes a hard delete outright. Reach for this on a local,
+ * unsynced store, or to drop a reaction (see {@link toggleCommentReaction}).
  *
  * @public
  */
@@ -1065,21 +1171,20 @@ export declare function reopenThread(editor: Editor, thread: TLCommentThread): v
  * Mark a thread resolved, stamping who resolved it and when. Resolved threads keep their pin (a
  * checked one) and are hidden from the sidebar until its "show resolved" filter is on.
  *
- * Only the resolution is written: the rest of the thread is read fresh, so resolving with a stale
- * copy in hand won't drag a pin back to where it used to be. A no-op on a thread that's gone.
+ * Only the resolution is written — the rest of the thread is read fresh, so a stale copy can't drag
+ * a pin back. A no-op on a thread that's gone.
  *
  * @public
  */
 export 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.
+ * 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.
+ * 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}.
  *
@@ -1113,11 +1218,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 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).
+ * 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: {
@@ -1160,29 +1263,45 @@ 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;
+}
+
 /**
- * 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.
+ * 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 summarizeReactions(reactions: TLCommentReaction[], currentUserId?: null | string, resolveName?: (userId: string) => string | undefined): ReactionSummary[];
+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 threads and comments live on the editor's local store so the canvas can render them
- * reactively, but they are opt-in records that aren't part of the `TLRecord` union (they ride the
- * sync server's object-store lane on the wire — see `TLCommentThread`). `editor.store` is therefore
- * statically typed `Store<TLRecord>` and doesn't know about them, so every access has to reinterpret
- * the type. These helpers own that reinterpretation — an `unknown` hop to exactly the type the store
- * expects, so the rest of each call stays checked — behind one boundary, and keep call sites typed.
+ * Comment records live on the editor's local store so the canvas can render them reactively, but
+ * they're opt-in and aren't part of the `TLRecord` union — so `editor.store` is statically typed
+ * `Store<TLRecord>` and every access has to reinterpret the type. These helpers own that
+ * reinterpretation behind one boundary and keep call sites typed.
  *
- * Writes do the same reinterpretation, but they also answer to the undo/redo policy, so they live
- * with the rest of the write path in `comment-mutations.ts`.
+ * Writes do the same, but also answer to the undo/redo policy, so they live in
+ * `comment-mutations.ts`.
  */
 /**
  * A record that lives in a comment thread: the thread itself, one of its messages, or a reaction
@@ -1194,14 +1313,12 @@ export declare type TLCommentRecord = TLComment | TLCommentReaction | TLCommentT
 /**
  * Toggle one user's reaction with a given emoji on a comment.
  *
- * Each reaction is its own record keyed by (comment, user, emoji), so this only ever touches that
- * one user's own records — two people reacting at once never conflict. Behaviour depends on the
- * `allowMultipleReactions` option:
+ * Each reaction is its own record keyed by (comment, user, emoji), so this only touches that user's
+ * own records and two people reacting at once never conflict. Behaviour depends on
+ * `allowMultipleReactions`:
  *
- * - **multiple** (default): the emoji toggles independently — add it if absent, remove it if
- *   present, leaving the user's other reactions alone.
- * - **single**: picking a new emoji first removes the user's existing reaction(s) on the comment,
- *   then adds this one (a replace); picking the one they already have removes it.
+ * - **multiple** (default): the emoji toggles independently, leaving other reactions alone.
+ * - **single**: a new emoji replaces the user's existing reaction; the same one removes it.
  *
  * @public
  */
@@ -1223,6 +1340,14 @@ export declare function toggleCommentsSidebar(editor: Editor): void;
  */
 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
@@ -1230,7 +1355,7 @@ export declare function useCanComment(currentUserId: null | string | undefined):
  * 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;
@@ -1278,11 +1403,9 @@ export declare function useOpenThreadId(): null | string;
 /**
  * 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.
+ * 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
  */