@blocksdiy/react-common 1.71.0 → 1.71.1

package/dist/comments/anchor.d.ts

@@ -66,9 +66,31 @@ export declare const anchorQuote: (anchor: CommentAnchor) => string | undefined;
 export declare const componentNameOf: (devName: string | null | undefined) => string | undefined;
 /** The component an anchor's element is (`componentNameOf`), when it has a name. */
 export declare const anchorComponentName: (anchor: CommentAnchor) => string | undefined;
+/** The kinds of text-less element a thread can name in plain words (the words are the UI's). */
+export type AnchorElementKind = "image" | "icon" | "video" | "field" | "button" | "link";
+/** What a thread is about, as its header names it; see `anchorSubject`. */
+export type AnchorSubject = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "component";
+    name: string;
+} | {
+    kind: "element";
+    element: AnchorElementKind;
+} | {
+    kind: "page";
+    routePath: string;
+};
+/**
+ * What an anchor is about, never a tag: its words (the highlighted text, else the element's text,
+ * however long: the UI cuts it), else its component's name, else the kind of a common text-less
+ * element (an image, an icon, a video, a field, a button, a link), else its page.
+ */
+export declare const anchorSubject: (anchor: CommentAnchor) => AnchorSubject;
 /**
  * A short name for what an anchor points at, never a tag: its quote, else its element's text,
- * clipped, else its component's name, else its page.
+ * clipped, else its component's name, else its page (`anchorSubject`, an element's kind aside).
  */
 export declare const anchorLabel: (anchor: CommentAnchor) => string;
 //# sourceMappingURL=anchor.d.ts.map

package/dist/comments/anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../src/comments/anchor.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAElB,KAAK,iBAAiB,EACvB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,cAAc,qBAAqB,CAAC;AACjD,gFAAgF;AAChF,eAAO,MAAM,eAAe,sBAAsB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAQ/D,2DAA2D;AAC3D,eAAO,MAAM,MAAM,GAAI,SAAS,WAAW,WAA8D,CAAC;AAO1G;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,iBAAiB,GAAG,SAMzF,CAAC;AAyBF,6DAA6D;AAC7D,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,GAAG,IAAI,KAAG,OAGjD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,GAAG,IAAI,KAAG,WAAW,GAAG,IAS5D,CAAC;AAmCF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,aAgDH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAsED,iGAAiG;AACjG,eAAO,MAAM,qBAAqB,GAAI,QAAQ,aAAa,EAAE,OAAM,UAAqB,KAAG,OAAO,GAAG,IACjC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,aAAa,KAAG,cAcrD,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,SAAS,GAAI,QAAQ,aAAa,EAAE,SAAS,WAAW,KAAG,cAavE,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,KAAG,MAAM,GAAG,SAM5D,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,SACrB,CAAC;AAE1D,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,KAAG,MAAM,GAAG,SAC3B,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,KAAG,MAMnD,CAAC"}
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../src/comments/anchor.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAElB,KAAK,iBAAiB,EACvB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,cAAc,qBAAqB,CAAC;AACjD,gFAAgF;AAChF,eAAO,MAAM,eAAe,sBAAsB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAQ/D,2DAA2D;AAC3D,eAAO,MAAM,MAAM,GAAI,SAAS,WAAW,WAA8D,CAAC;AAO1G;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,iBAAiB,GAAG,SAMzF,CAAC;AAyBF,6DAA6D;AAC7D,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,GAAG,IAAI,KAAG,OAGjD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,GAAG,IAAI,KAAG,WAAW,GAAG,IAS5D,CAAC;AAmCF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,aAgDH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA6ED,iGAAiG;AACjG,eAAO,MAAM,qBAAqB,GAAI,QAAQ,aAAa,EAAE,OAAM,UAAqB,KAAG,OAAO,GAAG,IACjC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,aAAa,KAAG,cA2CrD,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,SAAS,GAAI,QAAQ,aAAa,EAAE,SAAS,WAAW,KAAG,cAavE,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,KAAG,MAAM,GAAG,SAM5D,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,SACrB,CAAC;AAE1D,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,KAAG,MAAM,GAAG,SAC3B,CAAC;AAE3C,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAgBzF,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,aAAa,KAAG,aAYrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,KAAG,MAOnD,CAAC"}

package/dist/comments/anchor.js

@@ -214,6 +214,12 @@ const findTextRange = (element, text) => {
     }
     return null;
 };
+/** Whether `element` is inside the row's tag of a column other than `field` (untagged: unknown, so no). */
+const showsAnotherField = (element, row, field) => {
+    const tagged = element.closest(`[${FIELD_ATTRIBUTE}]`);
+    const shown = tagged && row.contains(tagged) ? tagged.getAttribute(FIELD_ATTRIBUTE) : null;
+    return !!shown && shown.slice(0, COMMENT_ANCHOR_FIELD_MAX_LENGTH) !== field;
+};
 /** The row's element an anchor names, or null when it has none or the row is not on the page. */
 export const findAnchorItemElement = (anchor, root = document) => anchor.item ? root.querySelector(itemSelector(anchor.item)) : null;
 /**
@@ -229,11 +235,40 @@ export const resolveAnchor = (anchor) => {
         }
         root = itemElement;
     }
-    const element = findElement(anchor, root) ?? (anchor.item ? root : null);
-    if (!element) {
+    const found = findElement(anchor, root);
+    // Another view of the row can have an element from the same source at the same place that
+    // shows another column: not the one the comment was on.
+    const element = found && anchor.item?.field && showsAnotherField(found, root, anchor.item.field) ? null : found;
+    if (element) {
+        return checkText(anchor, element);
+    }
+    if (!anchor.item) {
         return MISSING;
     }
-    return checkText(anchor, element);
+    // The row is on the page without the element the comment was on: the row's own element, or
+    // another view of the same rows (a board's card, a list's line). The thread stays with its row.
+    const row = root;
+    const inner = anchor.element;
+    if (inner?.ordinal === undefined && !inner?.domPath) {
+        return checkText(anchor, row);
+    }
+    // On the column it was about, when this view tags it; else on the part of the row that says
+    // what the comment was about (the innermost such element); else on the row, out of date.
+    const field = anchor.item.field
+        ? row.querySelector(`[${FIELD_ATTRIBUTE}="${escape(anchor.item.field)}"]`)
+        : null;
+    if (field) {
+        return checkText(anchor, field);
+    }
+    const snapshot = inner?.textSnapshot;
+    if (!anchor.text && snapshot) {
+        const saying = Array.from(row.querySelectorAll("*")).filter((part) => textOf(part) === snapshot);
+        const innermost = saying[saying.length - 1];
+        if (innermost) {
+            return { state: "anchored", element: innermost, range: null };
+        }
+    }
+    return checkText(anchor, row);
 };
 /** Whether `element` still says what the anchor was about. */
 export const checkText = (anchor, element) => {
@@ -266,14 +301,46 @@ const LABEL_MAX = 40;
 export const componentNameOf = (devName) => devName && /^[A-Z]/.test(devName) ? devName : undefined;
 /** The component an anchor's element is (`componentNameOf`), when it has a name. */
 export const anchorComponentName = (anchor) => componentNameOf(anchor.element?.devName);
+/** Tags (HTML ones stored in capitals, SVG ones as written, so compared in capitals) by kind. */
+const ELEMENT_KINDS = new Map([
+    ["IMG", "image"],
+    ["PICTURE", "image"],
+    ["CANVAS", "image"],
+    ["SVG", "icon"],
+    ["VIDEO", "video"],
+    ["INPUT", "field"],
+    ["TEXTAREA", "field"],
+    ["SELECT", "field"],
+    ["BUTTON", "button"],
+    ["A", "link"],
+]);
 /**
- * A short name for what an anchor points at, never a tag: its quote, else its element's text,
- * clipped, else its component's name, else its page.
+ * What an anchor is about, never a tag: its words (the highlighted text, else the element's text,
+ * however long: the UI cuts it), else its component's name, else the kind of a common text-less
+ * element (an image, an icon, a video, a field, a button, a link), else its page.
  */
-export const anchorLabel = (anchor) => {
+export const anchorSubject = (anchor) => {
     const text = anchorQuote(anchor) ?? anchor.element?.textSnapshot;
     if (text) {
+        return { kind: "text", text };
+    }
+    const name = anchorComponentName(anchor);
+    if (name) {
+        return { kind: "component", name };
+    }
+    const tag = anchor.element?.tagName?.toUpperCase();
+    const element = tag ? ELEMENT_KINDS.get(tag) : undefined;
+    return element ? { kind: "element", element } : { kind: "page", routePath: anchor.routePath };
+};
+/**
+ * A short name for what an anchor points at, never a tag: its quote, else its element's text,
+ * clipped, else its component's name, else its page (`anchorSubject`, an element's kind aside).
+ */
+export const anchorLabel = (anchor) => {
+    const subject = anchorSubject(anchor);
+    if (subject.kind === "text") {
+        const { text } = subject;
         return text.length > LABEL_MAX ? `${text.slice(0, LABEL_MAX - 1)}…` : text;
     }
-    return anchorComponentName(anchor) ?? anchor.routePath;
+    return subject.kind === "component" ? subject.name : anchor.routePath;
 };

package/dist/comments/comment-mode.d.ts

@@ -11,6 +11,7 @@
  *
  * The app can also open one thread itself (a comment's link in the agent chat): `openCommentThread`
  * asks the host for comment mode, as its Comment button would, and the surface goes to the thread.
+ * Only where the platform offers comments (`CommentOptions.isOffered`): not in its builder.
  */
 /**
  * What the app's comments show, as the platform's Comment button sets it. `mentionableAgents`: the
@@ -21,6 +22,13 @@ export interface CommentOptions {
     /** Pins of resolved threads and outdated ones (their text changed) show too. */
     showResolved: boolean;
     mentionableAgents?: readonly string[];
+    /**
+     * Whether the platform offers comments here (its `app-comments` flag on, the app having the
+     * comments component, and not in its builder): when `false` no thread opens from inside the app,
+     * so its links back to one hide. Absent means offered: a platform from before the field sends
+     * none, and an app-render from before it ignores it.
+     */
+    isOffered?: boolean;
 }
 export declare const DEFAULT_COMMENT_OPTIONS: CommentOptions;
 /** A thread to open in the app: on its page, scrolled to, open. */
@@ -46,14 +54,17 @@ export interface CommentModeStore {
     exit(): void;
     /** The host: hears when the app turned comment mode off itself. */
     onExit(listener: () => void): () => void;
-    /** The host: what the comments show (resolved and outdated pins, the agents to mention). */
+    /** The host: what the comments show (resolved and outdated pins, agents to mention) and if they're offered. */
     setOptions(options: CommentOptions): void;
     options(): CommentOptions;
     /** The app's surface: opens the threads asked for while the returned function hasn't been called. */
     handleOpenThread(handler: (request: CommentThreadOpenRequest) => void): () => void;
     /** The host: hears the app ask for comment mode (to show a thread it opens). */
     onRequestOn(listener: () => void): () => void;
-    /** Whether a thread can be opened from inside the app: a host listens and a surface opens it. */
+    /**
+     * Whether a thread can be opened from inside the app: the host offers comments here (the options'
+     * `isOffered` isn't `false`), listens, and a surface opens it.
+     */
     canOpenThread(): boolean;
     /** The app: asks the host for comment mode and the surface for the thread. False when it can't here. */
     openThread(request: CommentThreadOpenRequest): boolean;
@@ -65,17 +76,24 @@ export declare const commentMode: CommentModeStore;
 export declare const setCommentMode: (isOn: boolean) => Promise<boolean>;
 /** The host: hears when the app turned comment mode off itself. Returns the unsubscribe. */
 export declare const onCommentModeExit: (listener: () => void) => (() => void);
-/** The host: what the app's comments show (the Comment button's options). */
+/** The host: what the app's comments show (the Comment button's options), and whether they're offered. */
 export declare const setCommentOptions: (next: CommentOptions) => void;
 /** The host: hears the app ask for comment mode. Returns the unsubscribe. */
 export declare const onCommentModeRequest: (listener: () => void) => (() => void);
 /**
  * The app (the agent chat's comment message): opens a thread — its page, comment mode on, the
- * thread open. False when it can't here: outside the platform, or without the comments component.
+ * thread open. False when it can't here: outside the platform, where it doesn't offer comments (its
+ * builder), or without the comments component.
  */
 export declare const openCommentThread: (request: CommentThreadOpenRequest, store?: CommentModeStore) => boolean;
 /** Whether `openCommentThread` can open a thread here: the link back to it shows only then. */
 export declare const canOpenCommentThread: (store?: CommentModeStore) => boolean;
+/**
+ * `canOpenCommentThread`, kept current: the link back to a thread re-renders when the host stops
+ * offering comments (its builder) or offers them again, rather than staying until something else
+ * renders it.
+ */
+export declare const useCanOpenCommentThread: (store?: CommentModeStore) => boolean;
 export interface UseCommentsSurfaceOptions {
     /**
      * Opens a thread `openCommentThread` asked for: navigate to its page with the thread's link

package/dist/comments/comment-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comment-mode.d.ts","sourceRoot":"","sources":["../../src/comments/comment-mode.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"comment-mode.d.ts","sourceRoot":"","sources":["../../src/comments/comment-mode.ts"],"names":[],"mappings":"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"}

package/dist/comments/comment-mode.js

@@ -1,6 +1,8 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 export const DEFAULT_COMMENT_OPTIONS = { showResolved: false };
-const sameOptions = (a, b) => a.showResolved === b.showResolved && a.mentionableAgents?.join("\n") === b.mentionableAgents?.join("\n");
+const sameOptions = (a, b) => a.showResolved === b.showResolved &&
+    a.mentionableAgents?.join("\n") === b.mentionableAgents?.join("\n") &&
+    a.isOffered === b.isOffered;
 /** How long turning comment mode on waits for a comments surface to mount. */
 export const COMMENT_MODE_CLAIM_TIMEOUT_MS = 5000;
 const defaultTimers = {
@@ -17,7 +19,7 @@ export const createCommentModeStore = (timers = defaultTimers) => {
     let openThreadHandler = null;
     const requestOnListeners = new Set();
     const emit = () => listeners.forEach((listener) => listener());
-    const canOpenThread = () => requestOnListeners.size > 0 && openThreadHandler !== null;
+    const canOpenThread = () => options.isOffered !== false && requestOnListeners.size > 0 && openThreadHandler !== null;
     const settlePending = (claimed) => {
         if (pending) {
             timers.clearTimeout(pending.timer);
@@ -99,17 +101,25 @@ export const createCommentModeStore = (timers = defaultTimers) => {
             }
         },
         options: () => options,
+        // Both decide `canOpenThread`: its subscribers hear each change.
         handleOpenThread(handler) {
             openThreadHandler = handler;
+            emit();
             return () => {
                 if (openThreadHandler === handler) {
                     openThreadHandler = null;
+                    emit();
                 }
             };
         },
         onRequestOn(listener) {
             requestOnListeners.add(listener);
-            return () => requestOnListeners.delete(listener);
+            emit();
+            return () => {
+                if (requestOnListeners.delete(listener)) {
+                    emit();
+                }
+            };
         },
         canOpenThread,
         openThread(request) {
@@ -128,17 +138,24 @@ export const commentMode = createCommentModeStore();
 export const setCommentMode = (isOn) => commentMode.set(isOn);
 /** The host: hears when the app turned comment mode off itself. Returns the unsubscribe. */
 export const onCommentModeExit = (listener) => commentMode.onExit(listener);
-/** The host: what the app's comments show (the Comment button's options). */
+/** The host: what the app's comments show (the Comment button's options), and whether they're offered. */
 export const setCommentOptions = (next) => commentMode.setOptions(next);
 /** The host: hears the app ask for comment mode. Returns the unsubscribe. */
 export const onCommentModeRequest = (listener) => commentMode.onRequestOn(listener);
 /**
  * The app (the agent chat's comment message): opens a thread — its page, comment mode on, the
- * thread open. False when it can't here: outside the platform, or without the comments component.
+ * thread open. False when it can't here: outside the platform, where it doesn't offer comments (its
+ * builder), or without the comments component.
  */
 export const openCommentThread = (request, store = commentMode) => store.openThread(request);
 /** Whether `openCommentThread` can open a thread here: the link back to it shows only then. */
 export const canOpenCommentThread = (store = commentMode) => store.canOpenThread();
+/**
+ * `canOpenCommentThread`, kept current: the link back to a thread re-renders when the host stops
+ * offering comments (its builder) or offers them again, rather than staying until something else
+ * renders it.
+ */
+export const useCanOpenCommentThread = (store = commentMode) => useSyncExternalStore(store.subscribe, store.canOpenThread, () => false);
 /**
  * The app's comments surface: registers itself while mounted and reads the mode. `exit` turns it off
  * from inside the app and tells the host. It opens the threads the app asks for (a comment's link in

package/dist/comments/index.d.ts

@@ -1,11 +1,17 @@
 export * from "./types.js";
-export { ITEM_ATTRIBUTE, FIELD_ATTRIBUTE, PICK_IGNORE_ATTRIBUTE, anchorQuote, anchorComponentName, type AnchorState, } from "./anchor.js";
+export { ITEM_ATTRIBUTE, FIELD_ATTRIBUTE, PICK_IGNORE_ATTRIBUTE, anchorQuote, anchorComponentName, anchorSubject, type AnchorElementKind, type AnchorState, type AnchorSubject, } from "./anchor.js";
 export { initials, type Mention, type MentionNames } from "./mentions.js";
 export { toRect, type Rect } from "./layout.js";
-export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, groupPins, useCommentPins, type PinPoint, type PinGroup, type ThreadLayout, } from "./pins.js";
+export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, pickPlacement, groupPins, useCommentPins, type PinPoint, type PinGroup, type ThreadLayout, } from "./pins.js";
+export { participantKey, pinParticipants, pinWidth, panelPosition, cornerPoint, panelSide, type PanelSide, type PanelPositionOptions, type PlacementViewport, } from "./pin-view.js";
+export { menuKeyTarget, type MenuPosition } from "./menu.js";
+export { COMMENT_MENU_ATTRIBUTE, useCommentMenu, type CommentMenuState, type UseCommentMenuOptions, } from "./use-comment-menu.js";
+export { isOnScreen, openCommentResponse, type OpenCommentResponse } from "./open-comment.js";
+export { useHeld } from "./use-held.js";
+export { useThreadScroll } from "./use-thread-scroll.js";
 export { usePagePick, type PagePick, type PagePickHover, type UsePagePickOptions } from "./page-pick.js";
 export { createCommentsApi, type CommentsApi, type CreateCommentsApiOptions } from "./api.js";
-export { setCommentMode, onCommentModeExit, setCommentOptions, onCommentModeRequest, openCommentThread, canOpenCommentThread, useCommentsSurface, type CommentThreadOpenRequest, type CommentOptions, type UseCommentsSurfaceOptions, } from "./comment-mode.js";
+export { setCommentMode, onCommentModeExit, setCommentOptions, onCommentModeRequest, openCommentThread, canOpenCommentThread, useCanOpenCommentThread, useCommentsSurface, type CommentThreadOpenRequest, type CommentOptions, type UseCommentsSurfaceOptions, } from "./comment-mode.js";
 export { commentPingsFor, useCommentThreads, type CommentThreadsStore, type CommentThreadsSnapshot, type CommentThreadLoadState, type SubscribeToCommentPings, } from "./threads-store.js";
 export { useCommentAgents, useRegisterCommentAgents, type CommentAgent, type CommentAgentsSnapshot, type OpenCommentAgentThread, } from "./comment-agents.js";
 export { pagePickComposerMeta, parsePagePickPart, pagePickOf } from "./pick-message.js";

package/dist/comments/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/comments/index.ts"],"names":[],"mappings":"AAMA,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,KAAK,WAAW,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EACL,wBAAwB,EACxB,QAAQ,EACR,SAAS,EACT,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtG,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,wBAAwB,EAAE,MAAM,OAAO,CAAC;AAC3F,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,yBAAyB,GAC/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,yBAAyB,GAC/B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/comments/index.ts"],"names":[],"mappings":"AAMA,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EACL,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,SAAS,EACT,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,cAAc,EACd,eAAe,EACf,QAAQ,EACR,aAAa,EACb,WAAW,EACX,SAAS,EACT,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtG,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,wBAAwB,EAAE,MAAM,OAAO,CAAC;AAC3F,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,yBAAyB,GAC/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,yBAAyB,GAC/B,MAAM,YAAY,CAAC"}

package/dist/comments/index.js

@@ -4,13 +4,19 @@
 // never remove, rename or change the meaning of one. It exports what the registry items and
 // app-render use (and the types their signatures show); add an export when an item needs one.
 export * from "./types.js";
-export { ITEM_ATTRIBUTE, FIELD_ATTRIBUTE, PICK_IGNORE_ATTRIBUTE, anchorQuote, anchorComponentName, } from "./anchor.js";
+export { ITEM_ATTRIBUTE, FIELD_ATTRIBUTE, PICK_IGNORE_ATTRIBUTE, anchorQuote, anchorComponentName, anchorSubject, } from "./anchor.js";
 export { initials } from "./mentions.js";
 export { toRect } from "./layout.js";
-export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, groupPins, useCommentPins, } from "./pins.js";
+export { COMMENTS_LAYER_ATTRIBUTE, pinPoint, pickPlacement, groupPins, useCommentPins, } from "./pins.js";
+export { participantKey, pinParticipants, pinWidth, panelPosition, cornerPoint, panelSide, } from "./pin-view.js";
+export { menuKeyTarget } from "./menu.js";
+export { COMMENT_MENU_ATTRIBUTE, useCommentMenu, } from "./use-comment-menu.js";
+export { isOnScreen, openCommentResponse } from "./open-comment.js";
+export { useHeld } from "./use-held.js";
+export { useThreadScroll } from "./use-thread-scroll.js";
 export { usePagePick } from "./page-pick.js";
 export { createCommentsApi } from "./api.js";
-export { setCommentMode, onCommentModeExit, setCommentOptions, onCommentModeRequest, openCommentThread, canOpenCommentThread, useCommentsSurface, } from "./comment-mode.js";
+export { setCommentMode, onCommentModeExit, setCommentOptions, onCommentModeRequest, openCommentThread, canOpenCommentThread, useCanOpenCommentThread, useCommentsSurface, } from "./comment-mode.js";
 export { commentPingsFor, useCommentThreads, } from "./threads-store.js";
 export { useCommentAgents, useRegisterCommentAgents, } from "./comment-agents.js";
 export { pagePickComposerMeta, parsePagePickPart, pagePickOf } from "./pick-message.js";

package/dist/comments/menu.d.ts

@@ -0,0 +1,33 @@
+import type { Rect } from "./layout.js";
+/**
+ * The item a key moves focus to in a menu of `count` items whose item `index` has focus (-1: none):
+ * ↓ and ↑ the next and the previous, wrapping round, Home and End the first and the last; null for
+ * any other key, which the menu leaves alone.
+ */
+export declare const menuKeyTarget: (key: string, index: number, count: number) => number | null;
+/** Where a menu fixed in the window goes: one of `left`/`right`, one of `top`/`bottom`, and its tallest. */
+export interface MenuPosition {
+    side: "bottom" | "top";
+    /** From the window's top (`bottom`) or its bottom (`top`). */
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+    /** The room it has on that side: taller than this, it scrolls. */
+    maxHeight: number;
+}
+/**
+ * Where a menu `height` tall opens beside its trigger (in window coordinates): below it when it
+ * fits there, else above when it fits there or there is more room above (a composer at the bottom
+ * of the window, a sheet on a phone), else below; never taller than the room on its side. Its start
+ * edge lines up with the trigger's start (a picker) or its end edge with the trigger's end (a ⋯),
+ * as the page reads (`isRtl`), from the window's own edges.
+ */
+export declare const menuPosition: (trigger: Rect, { height, align, isRtl, viewportWidth, viewportHeight, }: {
+    height: number;
+    align: "start" | "end";
+    isRtl: boolean;
+    viewportWidth: number;
+    viewportHeight: number;
+}) => MenuPosition;
+//# sourceMappingURL=menu.d.ts.map

package/dist/comments/menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu.d.ts","sourceRoot":"","sources":["../../src/comments/menu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAQrC;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MAAM,GAAG,IAgBlF,CAAC;AAMF,4GAA4G;AAC5G,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC;IACvB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,IAAI,EACb,0DAMG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,KAC3G,YAUF,CAAC"}

package/dist/comments/menu.js

@@ -0,0 +1,47 @@
+/*
+ * What the comments' own menus share: which item a key moves to (a comment's ⋯, the composer's
+ * agent picker, a grouped pin's chooser), and where a menu button's menu opens beside its trigger
+ * (the ⋯ and the picker). Pure: the caller passes the window. `useCommentMenu` puts them to work.
+ */
+/**
+ * The item a key moves focus to in a menu of `count` items whose item `index` has focus (-1: none):
+ * ↓ and ↑ the next and the previous, wrapping round, Home and End the first and the last; null for
+ * any other key, which the menu leaves alone.
+ */
+export const menuKeyTarget = (key, index, count) => {
+    if (count <= 0) {
+        return null;
+    }
+    switch (key) {
+        case "ArrowDown":
+            return (index + 1) % count;
+        case "ArrowUp":
+            return index < 0 ? count - 1 : (index - 1 + count) % count;
+        case "Home":
+            return 0;
+        case "End":
+            return count - 1;
+        default:
+            return null;
+    }
+};
+/** The gap between a menu and its trigger, and how far a menu keeps from the window's edge. */
+const MENU_GAP = 4;
+const MENU_EDGE = 8;
+/**
+ * Where a menu `height` tall opens beside its trigger (in window coordinates): below it when it
+ * fits there, else above when it fits there or there is more room above (a composer at the bottom
+ * of the window, a sheet on a phone), else below; never taller than the room on its side. Its start
+ * edge lines up with the trigger's start (a picker) or its end edge with the trigger's end (a ⋯),
+ * as the page reads (`isRtl`), from the window's own edges.
+ */
+export const menuPosition = (trigger, { height, align, isRtl, viewportWidth, viewportHeight, }) => {
+    const roomBelow = viewportHeight - trigger.bottom - MENU_GAP;
+    const roomAbove = trigger.top - MENU_GAP;
+    const vertical = height < roomBelow || (height > roomAbove && roomBelow >= roomAbove)
+        ? { side: "bottom", top: trigger.bottom + MENU_GAP, maxHeight: Math.max(0, roomBelow - MENU_EDGE) }
+        : { side: "top", bottom: viewportHeight - trigger.top + MENU_GAP, maxHeight: Math.max(0, roomAbove - MENU_EDGE) };
+    return (align === "start") !== isRtl
+        ? { ...vertical, left: trigger.left }
+        : { ...vertical, right: viewportWidth - trigger.right };
+};

package/dist/comments/open-comment.d.ts

@@ -0,0 +1,28 @@
+import { type Rect } from "./layout.js";
+/**
+ * - `close`: close it.
+ * - `refocus`: keep it, with focus back in its composer (a click while it holds something unsent).
+ * - `return`: take the page back to it and focus its composer; it is out of sight with something
+ *   unsent. Tried once: when a return has had its chance (its scroll has ended) and the panel is
+ *   still out of sight (its element has no box, or scrolling can't reveal it), the click or Esc
+ *   closes it instead, as Esc does in sight, so nobody is held by a panel they can't see. While the
+ *   return is still under way, another click or Esc answers `return` again: nothing is lost.
+ * - `pass`: it is out of sight with nothing unsent: the click or Esc acts as if nothing were open
+ *   (a click starts a new comment, Esc ends comment mode), and it closes with that.
+ */
+export type OpenCommentResponse = "close" | "refocus" | "return" | "pass";
+export declare const openCommentResponse: ({ input, isOnScreen, hasUnsent, hasReturnFailed, }: {
+    input: "click" | "escape";
+    /** Whether any of its panel is in the window and drawn (`isOnScreen`). */
+    isOnScreen: boolean;
+    /** Whether its composer holds something that would be sent. */
+    hasUnsent: boolean;
+    /** A `return` was answered, its scroll has had time to end, and the panel hasn't been in sight since. */
+    hasReturnFailed?: boolean;
+}) => OpenCommentResponse;
+/** Whether any of `rect` (null: not drawn) is in the window; an empty box is not. */
+export declare const isOnScreen: (rect: Rect | null, viewport: {
+    width: number;
+    height: number;
+}) => boolean;
+//# sourceMappingURL=open-comment.d.ts.map

package/dist/comments/open-comment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-comment.d.ts","sourceRoot":"","sources":["../../src/comments/open-comment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AASrD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1E,eAAO,MAAM,mBAAmB,GAAI,oDAKjC;IACD,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,yGAAyG;IACzG,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,KAAG,mBAKH,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,GAAG,IAAI,EAAE,UAAU;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAG,OACW,CAAC"}

package/dist/comments/open-comment.js

@@ -0,0 +1,9 @@
+import { intersectRects } from "./layout.js";
+export const openCommentResponse = ({ input, isOnScreen, hasUnsent, hasReturnFailed = false, }) => {
+    if (!isOnScreen) {
+        return !hasUnsent ? "pass" : hasReturnFailed ? "close" : "return";
+    }
+    return input === "click" && hasUnsent ? "refocus" : "close";
+};
+/** Whether any of `rect` (null: not drawn) is in the window; an empty box is not. */
+export const isOnScreen = (rect, viewport) => !!rect && !!intersectRects(rect, { top: 0, left: 0, right: viewport.width, bottom: viewport.height });

package/dist/comments/page-pick.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page-pick.d.ts","sourceRoot":"","sources":["../../src/comments/page-pick.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,IAAI,EAA0C,MAAM,UAAU,CAAC;AAC1F,OAAO,EAOL,KAAK,SAAS,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,0HAA0H;IAC1H,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,IAAI,EAAE,CAAC;QACd,KAAK,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QACzD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,WAAW,EAAE,WAAW,MAAM,KAAG,MAQhE,CAAC;AAeL,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,0FAA0F;IAC1F,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9C;AAED,qGAAqG;AACrG,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;IACxD,8EAA8E;IAC9E,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;CACrD;AAQD,oGAAoG;AACpG,eAAO,MAAM,iBAAiB,GAC5B,KAAK,QAAQ,EACb,WAAW,iBAAiB,EAC5B,SAAQ,kBAGP,KACA,CAAC,MAAM,IAAI,CAmLb,CAAC;AAcF,eAAO,MAAM,WAAW,GAAI,2CAA2C,kBAAkB,KAAG,aAAa,GAAG,IA4C3G,CAAC"}
+{"version":3,"file":"page-pick.d.ts","sourceRoot":"","sources":["../../src/comments/page-pick.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,IAAI,EAA0C,MAAM,UAAU,CAAC;AAC1F,OAAO,EAOL,KAAK,SAAS,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,0HAA0H;IAC1H,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,IAAI,EAAE,CAAC;QACd,KAAK,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QACzD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,WAAW,EAAE,WAAW,MAAM,KAAG,MAQhE,CAAC;AAeL,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,0FAA0F;IAC1F,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9C;AAED,qGAAqG;AACrG,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;IACxD,8EAA8E;IAC9E,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;CACrD;AAQD,oGAAoG;AACpG,eAAO,MAAM,iBAAiB,GAC5B,KAAK,QAAQ,EACb,WAAW,iBAAiB,EAC5B,SAAQ,kBAGP,KACA,CAAC,MAAM,IAAI,CAkMb,CAAC;AAcF,eAAO,MAAM,WAAW,GAAI,2CAA2C,kBAAkB,KAAG,aAAa,GAAG,IA4C3G,CAAC"}

package/dist/comments/page-pick.js

@@ -108,7 +108,14 @@ export const listenForPagePick = (doc, listeners, lookup = {
     };
     const onPress = (event) => {
         isSwallowingClick = false;
-        if (isPaused() || event.button !== 0 || isPickIgnored(event.target)) {
+        if (isPaused()) {
+            // The picker in front takes this press. Should it stop before the click the press ends in
+            // (a drag's pick, Esc during a drag), that click is still part of its pointing, not a pick
+            // of this one's.
+            isSwallowingClick = event.button === 0 && !isPickIgnored(event.target);
+            return;
+        }
+        if (event.button !== 0 || isPickIgnored(event.target)) {
             return;
         }
         const point = lookup.textPointAt(event.clientX, event.clientY);
@@ -122,9 +129,6 @@ export const listenForPagePick = (doc, listeners, lookup = {
     };
     const onRelease = (event) => {
         if (isPaused()) {
-            // The picker in front may pick on this release (a drag) and stop before the click it makes:
-            // that click is part of its pick, not a pick of this one's.
-            isSwallowingClick = !isPickIgnored(event.target);
             return;
         }
         const finished = drag;
@@ -198,16 +202,28 @@ export const listenForPagePick = (doc, listeners, lookup = {
         doc.removeEventListener("click", onClick, true);
         presses.forEach((type) => doc.removeEventListener(type, swallow, true));
         doc.removeEventListener("keydown", onKeyDown, true);
-        if (isSwallowingClick) {
-            // Stopped by its own drag's pick (the chat's pointer ends on a pick): the click that release
-            // makes comes right after, and still isn't the app's. Only that click: gone a moment later.
+        // The click a release makes comes right after it, and still isn't the app's when the press
+        // was part of picking. Only that click: the listener is gone a moment later.
+        const swallowNextClick = () => {
             const swallowClick = (event) => {
                 event.preventDefault();
                 event.stopPropagation();
             };
             doc.addEventListener("click", swallowClick, { capture: true, once: true });
             setTimeout(() => doc.removeEventListener("click", swallowClick, true), 0);
+        };
+        if (isSwallowingClick) {
+            // Stopped by its own drag's pick (the chat's pointer ends on a pick), before the click.
             isSwallowingClick = false;
+            swallowNextClick();
+        }
+        else if (drag) {
+            // Stopped during a press (Esc ends the chat's pointing mid-drag): the click comes after the
+            // release. A new press first means that release never came here: nothing to swallow.
+            const forget = () => doc.removeEventListener("mouseup", swallowNextClick, true);
+            doc.addEventListener("mouseup", swallowNextClick, { capture: true, once: true });
+            doc.addEventListener("mousedown", forget, { capture: true, once: true });
+            drag = null;
         }
     };
 };