@tldraw/commenting 0.0.0-bootstrap

package/dist-cjs/index.d.ts

@@ -0,0 +1,868 @@
+import { ComponentType } from 'react';
+import { Editor } from 'tldraw';
+import { EditorAtom } from 'tldraw';
+import { JSX } from 'react/jsx-runtime';
+import type { MentionNodeAttrs } from '@tiptap/extension-mention';
+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 { TLCommentThread } from 'tldraw';
+import { TLCommentThreadId } from 'tldraw';
+import { TLHistoryBatchOptions } from 'tldraw';
+import { TLRichText } from 'tldraw';
+import { TLShapeId } from 'tldraw';
+import { TLStateNodeConstructor } from 'tldraw';
+import { TLUiOverrides } from 'tldraw';
+import { VecLike } from 'tldraw';
+
+/**
+ * Where a thread's pin sits on the page, for each anchor kind. Null hides the pin. For imprecise
+ * shape anchors the pin uses `impreciseShapeAnchor` (a normalized 0–1 spot, top-right by default)
+ * rather than the stored `x`/`y`.
+ * @public
+ */
+export declare function anchorPagePoint(editor: Editor, anchor: TLCommentAnchor, impreciseShapeAnchor?: {
+    x: number;
+    y: number;
+}): {
+    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;
+
+/** @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;
+}
+
+/** 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;
+    /** ISO datetime; formatted to relative time by the component. */
+    date: string;
+    /** Shows an "edited" marker when the comment has been edited. */
+    edited?: boolean;
+}
+
+/** @public @react */
+export declare function CanvasComments(props: CanvasCommentsProps): JSX.Element | null;
+
+/**
+ * A ready-to-use comments layer for a tldraw canvas: pins each thread at its anchor, opens a
+ * thread popover (with a reply composer) on click, and shows a composer where the comment tool
+ * placed a new thread. Reads/writes comment records straight from `editor.store`.
+ *
+ * It's meant as the batteries-included default — every visible piece is a lever (the `CommentBody`
+ * and `PinContent` slots on `CommentTool.configure({ components })`), and the pieces it composes
+ * (`CommentPin`, `CommentThread`, `CommentComposer`, the hooks, the tool) are all exported, so a
+ * consumer can rebuild this from parts instead.
+ * @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>;
+}
+
+/**
+ * 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.
+ * @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[];
+    /** 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[];
+
+/**
+ * Renders a comment's rich-text body read-only through the limited comment extension set (no
+ * headings), so formatting (bold, links, lists, highlight) is preserved rather than flattened, and
+ * headings can never render. Use this as the `body` of a `CommentCard` on a canvas.
+ * @public @react
+ */
+export declare function CommentBody({ richText, resolveName }: CommentBodyProps): JSX.Element;
+
+/** @public */
+export declare interface CommentBodyProps {
+    richText: TLRichText;
+    /** Maps a member id to its current display name, so \@mentions show the live name. */
+    resolveName?(id: string): string | undefined;
+}
+
+/** 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;
+
+/** @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. */
+    body: ReactNode;
+    /** ISO datetime; formatted to relative time by the component. */
+    date: string;
+    you: boolean;
+    /** Whether the comment has been edited (shows an "edited" marker). */
+    edited?: boolean;
+    /** Hover-revealed controls at the card's top-right (e.g. an edit affordance). */
+    actions?: ReactNode;
+}
+
+/**
+ * The input for writing a comment: a TipTap rich-text editor restricted to the comment extension
+ * set (bold, italic, lists, links, code, highlight — no headings), with a Send button. Formatting
+ * is applied through markdown and keyboard shortcuts (e.g. `**bold**`, `- `, Cmd+B); there's no
+ * 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;
+
+/** @public */
+export declare interface CommentComposerProps {
+    author: string;
+    placeholder: string;
+    /** Controlled rich-text value. Omit for the presentational (display-only) composer. */
+    value?: TLRichText;
+    onChange?(value: TLRichText): void;
+    /** Called on Send click or Enter. When set, the composer is interactive. */
+    onSubmit?(): void;
+    sendLabel?: string;
+    disabled?: boolean;
+    autoFocus?: boolean;
+    /** The leading element before the field. Defaults to the author's avatar. */
+    leading?: ReactNode;
+    /** Resolve the members matching an `@`-query (sync or async). Provide to enable mentions. */
+    getMentionSuggestions?(query: string): MentionMember[] | Promise<MentionMember[]>;
+    /** Override a picker row's content. Defaults to avatar + name (+ secondary). */
+    renderMentionSuggestion?(member: MentionMember): ReactNode;
+}
+
+/**
+ * Component overrides for the batteries-included comments layer. Each slot replaces a built-in
+ * piece; leave a slot unset to keep its default.
+ *
+ * @public
+ */
+export declare interface CommentingComponents {
+    /** A comment's body. Replaces the default rich-text `<CommentBody>`. */
+    CommentBody?: ComponentType<{
+        comment: TLComment;
+    }>;
+    /** A pin's inner content. Replaces the author-initial default. */
+    PinContent?: ComponentType<{
+        comments: TLComment[];
+        thread: TLCommentThread;
+    }>;
+    /** A sidebar row's preview. Replaces the plaintext default. */
+    ThreadPreview?: ComponentType<{
+        comment: TLComment;
+    }>;
+}
+
+/**
+ * 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>`.
+ *
+ * For defaults, see {@link defaultCommentingOptions}.
+ *
+ * @example
+ * ```tsx
+ * <Tldraw tools={[CommentTool.configure({ history: 'ignore', enableClustering: false })]} />
+ * ```
+ *
+ * @public
+ */
+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.
+     */
+    readonly history: TLHistoryBatchOptions['history'];
+    /**
+     * History mode for the pin drag-to-move re-anchor specifically. Unlike posts/edits this is a
+     * spatial edit that may reasonably be undoable alongside a shape move. Defaults to `history`.
+     */
+    readonly dragHistory: TLHistoryBatchOptions['history'] | undefined;
+    /** Fold nearby pins into count badges as the camera zooms out. */
+    readonly enableClustering: boolean;
+    /** 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;
+    /** Component overrides. See {@link CommentingComponents}. */
+    readonly components: CommentingComponents;
+}
+
+/** @public */
+export declare interface CommentListItemProps {
+    id: string;
+    author: string;
+    /** A short preview of the thread — e.g. the first comment's body. */
+    preview: ReactNode;
+    /** ISO datetime of the thread's first comment. */
+    date: string;
+    resolved?: boolean;
+    /** Name of the page the thread lives on, shown as a small label. Omit to hide. */
+    page?: string;
+    /** Total comments in the thread. */
+    count?: number;
+    /** Whether this thread is the open one. */
+    selected?: boolean;
+}
+
+/** 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 */
+export declare function CommentPin({ children, resolved, open }: CommentPinProps): JSX.Element;
+
+/** @public */
+export declare interface CommentPinProps {
+    /** What the pin shows when unresolved — a number, an author initial, an <Avatar>, etc.
+     *  Left as a lever so consumers aren't locked into a count. */
+    children?: ReactNode;
+    resolved?: boolean;
+    /** The pin's thread is open — shows the active/selected indicator state. */
+    open?: boolean;
+}
+
+/** 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;
+
+/** @public */
+export declare interface CommentsFilterMenuProps {
+    /** Whether to offer the "only your threads" toggle (needs a known current user). */
+    canFilterByAuthor?: boolean;
+    /** Whether to offer the "only unread" toggle (needs a read-status source). */
+    canFilterByUnread?: boolean;
+}
+
+/**
+ * Whether comment pins are hidden on the canvas. Governs the on-canvas layer (pins + open popover)
+ * only — the sidebar is unaffected.
+ * @public
+ */
+export declare const commentsHidden: EditorAtom<boolean>;
+
+/**
+ * A scrollable list of comment threads — each an avatar, byline, and a one-line preview.
+ * Presentational: you supply the items (already summarised) and an `onSelect` handler; the canvas
+ * `CanvasCommentsSidebar` wires it to the store, but a consumer can build their own list from this.
+ * @public @react
+ */
+export declare function CommentsList({ items, onSelect, header, headerAction, empty, resolvedLabel, renderItem }: CommentsListProps): JSX.Element;
+
+/** @public */
+export declare interface CommentsListProps {
+    items: CommentListItemProps[];
+    /** Called with a thread id when an item is chosen. */
+    onSelect?(id: string): void;
+    /** Shown above the list (e.g. "Comments"). Omit for none. */
+    header?: ReactNode;
+    /** Rendered at the right of the header row — e.g. a filter menu. */
+    headerAction?: ReactNode;
+    /** Shown in place of the list when there are no threads. */
+    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;
+}
+
+/**
+ * A checkbox menu item for a "View" menu that shows/hides comment pins on the canvas — checked
+ * when comments are visible, like tldraw's own grid/snap toggles. Reads and toggles the shared
+ * {@link commentsHidden} signal, so it stays in sync with the Shift+C shortcut and the sidebar
+ * control. Drop it into whichever menu your app owns.
+ * @public @react
+ */
+export declare function CommentsMenuItem(): JSX.Element;
+
+/** The overflow (⋯) dropdown in the sidebar header. For now it holds the hide/show-comments
+ *  toggle; it's the home for later comment-wide controls (notifications, mark all as read).
+ * @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;
+
+/** @public */
+export declare interface CommentTextProps {
+    /** Rich text body, authored as markdown. */
+    text: string;
+}
+
+/**
+ * A comment thread: an optional header, an optional resolved banner, the comments, and an
+ * optional reply composer. Presentational — you supply the comments (as card props) and the
+ * 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;
+
+/** @public */
+export declare interface CommentThreadProps {
+    /** The thread's comments, already adapted to card props (oldest first). */
+    comments: CommentCardProps[];
+    /** Optional header, e.g. "Thread". Omit for no header. */
+    header?: ReactNode;
+    /** Action controls shown at the right of the header (resolve, delete, dismiss…). */
+    headerActions?: ReactNode;
+    /** When set, shows a banner above the comments (e.g. "Resolved by Jess"). */
+    resolvedBanner?: ReactNode;
+    /** Reply composer props. Omit for a read-only thread (no composer). */
+    composer?: CommentComposerProps;
+    /** 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.
+ * @public
+ */
+export declare class CommentTool extends StateNode {
+    static id: string;
+    static initial: string;
+    static children(): TLStateNodeConstructor[];
+    /**
+     * Configure this tool's {@link CommentTool.options | `options`}, returning a configured subclass
+     * to register via `tools`. Mirrors `ShapeUtil.configure`. Layers over any prior `configure`, so
+     * calls can be chained.
+     *
+     * @example
+     * ```tsx
+     * <Tldraw tools={[CommentTool.configure({ history: 'ignore', enableClustering: false })]} />
+     * ```
+     */
+    static configure<T extends TLStateNodeConstructor>(this: T, options: T extends new (...args: any[]) => {
+        options: infer Options;
+    } ? Partial<Options> : never): T;
+    /**
+     * The merged commenting options for this editor. Read from anywhere via
+     * {@link getCommentingOptions}. Override with {@link CommentTool.configure}.
+     */
+    options: CommentingOptions;
+    onEnter(): void;
+    onCancel(): void;
+}
+
+/** Registers the comment tool in the UI (icon, label, shortcut). Compose into your overrides.
+ *  Once registered, tldraw's `DefaultToolbarContent` shows the comment button next to the eraser.
+ * @public */
+export declare const commentToolOverrides: TLUiOverrides;
+
+/** @public */
+export declare const commentTools: typeof CommentTool[];
+
+/**
+ * Commit a comment mutation with the configured undo/redo behavior. All comment writes go through
+ * here so the {@link CommentingOptions.history} option (and {@link CommentingOptions.dragHistory}
+ * for pin re-anchors) governs whether they land on the undo stack. Defaults to `'ignore'`.
+ * @public
+ */
+export declare function commitCommentMutation<T>(editor: Editor, fn: () => T, kind?: 'drag' | 'mutation'): T;
+
+/** @public */
+export declare function computeClusterTable(leaves: readonly LeafInput[], options: ClusterOptions): ClusterTable;
+
+/** @public @react */
+export declare function CountBadge({ count }: CountBadgeProps): JSX.Element;
+
+/** @public */
+export declare interface CountBadgeProps {
+    count: number;
+}
+
+/** @public */
+export declare function createClusterRuntime(table: ClusterTable): ClusterRuntime;
+
+/**
+ * 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.
+ * @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;
+};
+
+/** 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.
+ * @public */
+export declare const DEFAULT_REGION_COMMENT_OPTIONS: RegionCommentOptions;
+
+/** @public */
+export declare const DEFAULT_SIDEBAR_FILTERS: SidebarFilters;
+
+/**
+ * The default {@link CommentingOptions}. Override via `CommentTool.configure({ ... })`.
+ *
+ * @public
+ */
+export declare const defaultCommentingOptions: {
+    readonly clusterCullMargin: 120;
+    readonly clusterSplitZoomFactor: 1.05;
+    readonly components: {};
+    readonly dragHistory: undefined;
+    readonly enableClustering: true;
+    readonly history: "ignore";
+    readonly impreciseShapeAnchor: {
+        readonly x: 1;
+        readonly y: 0;
+    };
+};
+
+/** The empty state shown when a thread has no comments yet. @public @react */
+export declare function EmptyState({ message }: EmptyStateProps): JSX.Element;
+
+/** @public */
+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[];
+
+/** 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;
+
+/**
+ * Format an ISO datetime as relative time ("2 hours ago", "yesterday", "last week").
+ * Locale-aware via Intl.RelativeTimeFormat.
+ * @public
+ */
+export declare function formatRelativeTime(iso: string, locale?: string): string;
+
+/**
+ * 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
+ * the comment tool isn't registered. Usable from anywhere with an `Editor` — including the tool's
+ * own state, which has no React context.
+ *
+ * @public
+ */
+export declare function getCommentingOptions(editor: Editor): CommentingOptions;
+
+/** 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 */
+export declare function getComments(editor: Editor): TLComment[];
+
+/** All comment threads currently in the store (non-reactive; wrap in `useValue` to react). @public */
+export declare function getCommentThreads(editor: Editor): TLCommentThread[];
+
+/**
+ * One comment thread's pin, already resolved to a page-space anchor point.
+ * @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;
+
+/**
+ * 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
+ */
+export declare function MentionList({ members, activeIndex, onSelect, emptyLabel, renderMember }: MentionListProps): JSX.Element;
+
+/** @public */
+export declare interface MentionListProps {
+    /** Members to choose from — already resolved for the current query by the host. */
+    members: MentionMember[];
+    /** Index of the highlighted row, driven by the composer's keyboard navigation. */
+    activeIndex?: number;
+    /** Called when a member is chosen (click, or Enter on the active row). */
+    onSelect?(member: MentionMember): void;
+    /** Shown when no member matches the query. Defaults to a translated "No matches". */
+    emptyLabel?: string;
+    /** Override a row's content (inside the selectable button). Defaults to avatar + name (+ secondary). */
+    renderMember?(member: MentionMember): ReactNode;
+}
+
+/** 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;
+}
+
+/** @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;
+}
+
+/**
+ * A finalized merge event, ready for the runtime.
+ * @public
+ */
+export declare interface MergeEvent {
+    zMerge: number;
+    /** Reverses (splits) when zoom \>= zSplit. Always \> zMerge. May be +Infinity. */
+    zSplit: number;
+    children: ClusterNode[];
+    result: ClusterNode;
+}
+
+/** 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;
+}
+
+/** The comment currently being placed (composer open, not yet posted), or null.
+ * @public */
+export declare const pendingComment: EditorAtom<null | PendingComment>;
+
+/** Write comment records to the store. @public */
+export declare function putCommentRecords(editor: Editor, records: TLCommentRecord[]): void;
+
+/** 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 ReactionProps {
+    emoji: string;
+    count: number;
+    active: boolean;
+}
+
+/** The row of reactions under a comment, plus an add-reaction button. @public @react */
+export declare function Reactions(): JSX.Element;
+
+/**
+ * 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>`.
+ * @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';
+}
+
+/** Remove comment records from the store by id. @public */
+export declare function removeCommentRecords(editor: Editor, ids: (TLCommentId | TLCommentThreadId)[]): void;
+
+/**
+ * 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.
+ * @public
+ */
+export declare function renderMarkdown(text: string): ReactNode;
+
+/**
+ * Flatten a rich-text comment body to plaintext through the limited comment extension set,
+ * separating paragraphs and list items with newlines. A convenience for consumers rendering bodies
+ * as plain text (e.g. the sidebar preview); richer rendering can read the `TLRichText` directly.
+ * @public
+ */
+export declare function richTextToPlaintext(body: TLRichText, resolveName?: (id: string) => string | undefined): string;
+
+/** The button that posts a comment. @public @react */
+export declare function SendButton({ label, disabled, onClick }: SendButtonProps): JSX.Element;
+
+/** @public */
+export declare interface SendButtonProps {
+    label: string;
+    disabled?: boolean;
+    onClick?(): void;
+}
+
+/**
+ * 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).
+ * @public
+ */
+export declare function shapeAnchorAt(editor: Editor, shapeId: TLShapeId, page: {
+    x: number;
+    y: number;
+}, precise: boolean): TLCommentAnchor;
+
+/**
+ * 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
+ * unmounting when the comment tool deactivates — a user's "hide resolved" choice shouldn't reset
+ * every time they leave the tool.
+ * @public
+ */
+export declare interface SidebarFilters {
+    /** Include resolved threads. */
+    showResolved: boolean;
+    /** Only threads the current user started. Ignored when there's no current user. */
+    onlyMine: boolean;
+    /** Only threads with unread comments. Ignored when the host provides no read status. */
+    onlyUnread: boolean;
+    /** Only threads on the current page. Off = every page's threads, each labelled. */
+    onlyCurrentPage: boolean;
+}
+
+/** Which threads the comments sidebar shows.
+ * @public */
+export declare const sidebarFilters: EditorAtom<SidebarFilters>;
+
+/**
+ * Typed access to 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.
+ */
+/** A record that lives in a comment thread: the thread itself or one of its messages. @public */
+export declare type TLCommentRecord = TLComment | TLCommentThread;
+
+/** Toggle comment-pin visibility for an editor.
+ * @public */
+export declare function toggleCommentsHidden(editor: Editor): void;
+
+/**
+ * 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
+ * it). Reactive: re-reads when license validation resolves, and returns `false` while validation is
+ * 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.
+ * @public
+ */
+export declare function useCommentingEnabled(): boolean;
+
+/**
+ * React hook for {@link getCommentingOptions}. Options are fixed per editor (set at tool
+ * registration), so this doesn't need to be reactive.
+ *
+ * @public
+ */
+export declare function useCommentingOptions(): CommentingOptions;
+
+/** Every comment in the store, 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 */
+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;
+
+/** React hook for the current sidebar filters.
+ * @public */
+export declare function useSidebarFilters(): SidebarFilters;
+
+/** A thread's comments, oldest first, reactively. @public */
+export declare function useThreadComments(editor: Editor, threadId: TLCommentThreadId): TLComment[];
+
+export { }