@blocksdiy/react-common 1.70.2 → 1.71.0

package/dist/comments/layout.js

@@ -0,0 +1,83 @@
+import { useEffect, useState } from "react";
+import { isPickIgnored } from "./anchor.js";
+/**
+ * A counter that moves at most once per animation frame whenever the page may have moved: a
+ * scroll anywhere (capture phase, so scroll containers count), a window resize, a change to the
+ * app's DOM, or a reflow of the body (a panel opening beside the app moves everything with no DOM
+ * change and no window resize). Changes inside the comments' own UI don't count, so drawing pins
+ * never feeds itself.
+ *
+ * Positions are read from the DOM, which is not a React input: pass the tick to whatever reads them
+ * so it recomputes.
+ */
+export const usePageLayoutTick = (isActive) => {
+    const [tick, setTick] = useState(0);
+    useEffect(() => {
+        if (!isActive || typeof window === "undefined") {
+            return;
+        }
+        let frame = 0;
+        const schedule = () => {
+            if (!frame) {
+                frame = window.requestAnimationFrame(() => {
+                    frame = 0;
+                    setTick((value) => value + 1);
+                });
+            }
+        };
+        const mutations = new MutationObserver((records) => {
+            if (records.some((record) => !isPickIgnored(record.target))) {
+                schedule();
+            }
+        });
+        mutations.observe(document.body, { subtree: true, childList: true, characterData: true });
+        const resizes = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+        resizes?.observe(document.body);
+        document.addEventListener("scroll", schedule, true);
+        window.addEventListener("resize", schedule);
+        return () => {
+            window.cancelAnimationFrame(frame);
+            mutations.disconnect();
+            resizes?.disconnect();
+            document.removeEventListener("scroll", schedule, true);
+            window.removeEventListener("resize", schedule);
+        };
+    }, [isActive]);
+    return tick;
+};
+export const toRect = (rect) => ({
+    top: rect.top,
+    left: rect.left,
+    right: rect.right,
+    bottom: rect.bottom,
+});
+/** The overlap of two rects, or null when they don't overlap. */
+export const intersectRects = (a, b) => {
+    const top = Math.max(a.top, b.top);
+    const left = Math.max(a.left, b.left);
+    const right = Math.min(a.right, b.right);
+    const bottom = Math.min(a.bottom, b.bottom);
+    return right > left && bottom > top ? { top, left, right, bottom } : null;
+};
+/** The part of `rect` inside every clip (the viewport, each scrolling ancestor), or null. */
+export const visiblePart = (rect, clips) => {
+    let visible = rect.right > rect.left && rect.bottom > rect.top ? rect : null;
+    for (const clip of clips) {
+        if (!visible) {
+            return null;
+        }
+        visible = intersectRects(visible, clip);
+    }
+    return visible;
+};
+const clipsOverflow = (style) => /(auto|scroll|hidden|clip)/.test(`${style.overflow}${style.overflowX}${style.overflowY}`);
+/** The boxes that clip `element`: the viewport and every ancestor that clips its overflow. */
+export const clipRectsOf = (element) => {
+    const clips = [{ top: 0, left: 0, right: window.innerWidth, bottom: window.innerHeight }];
+    for (let ancestor = element.parentElement; ancestor && ancestor !== document.body; ancestor = ancestor.parentElement) {
+        if (clipsOverflow(window.getComputedStyle(ancestor))) {
+            clips.push(toRect(ancestor.getBoundingClientRect()));
+        }
+    }
+    return clips;
+};

package/dist/comments/mentions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mentions in a comment body. Stored, a person is `@[42]` and an agent `@[agent:SupportAgent]`;
+ * in the composer both read as `@Name`. The server parses the stored tokens and never trusts a list
+ * the client sends.
+ */
+export type Mention = {
+    kind: "user";
+    userId: number;
+    name: string;
+} | {
+    kind: "agent";
+    agentId: string;
+    name: string;
+};
+/** Names for the ids a body mentions: the thread's people, the app's agents. */
+export interface MentionNames {
+    users: ReadonlyMap<number, string>;
+    agents: ReadonlyMap<string, string>;
+}
+export declare const mentionToken: (mention: Mention) => string;
+/** The `@query` being typed at the caret, if any: an `@` at a word start, no line break after it. */
+export declare const mentionQueryAt: (text: string, caret: number) => {
+    start: number;
+    query: string;
+} | null;
+/** Whether a mention candidate matches what was typed after `@`: its name contains it, or its email starts with it. */
+export declare const matchesMentionQuery: (candidate: {
+    name: string;
+    email?: string | null;
+}, query: string) => boolean;
+export declare const initials: (name: string) => string;
+//# sourceMappingURL=mentions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.d.ts","sourceRoot":"","sources":["../../src/comments/mentions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAExH,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,KAAG,MACkC,CAAC;AAEnF,qGAAqG;AACrG,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAW/F,CAAC;AAEF,uHAAuH;AACvH,eAAO,MAAM,mBAAmB,GAAI,WAAW;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,OAAO,MAAM,KAAG,OAKvG,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,MAMpB,CAAC"}

package/dist/comments/mentions.js

@@ -0,0 +1,30 @@
+/**
+ * Mentions in a comment body. Stored, a person is `@[42]` and an agent `@[agent:SupportAgent]`;
+ * in the composer both read as `@Name`. The server parses the stored tokens and never trusts a list
+ * the client sends.
+ */
+export const mentionToken = (mention) => mention.kind === "user" ? `@[${mention.userId}]` : `@[agent:${mention.agentId}]`;
+/** The `@query` being typed at the caret, if any: an `@` at a word start, no line break after it. */
+export const mentionQueryAt = (text, caret) => {
+    const before = text.slice(0, caret);
+    const at = before.lastIndexOf("@");
+    if (at < 0 || (at > 0 && !/\s/.test(before[at - 1]))) {
+        return null;
+    }
+    const query = before.slice(at + 1);
+    if (query.length > 30 || /[\n@]/.test(query) || /\s{2}/.test(query)) {
+        return null;
+    }
+    return { start: at, query };
+};
+/** Whether a mention candidate matches what was typed after `@`: its name contains it, or its email starts with it. */
+export const matchesMentionQuery = (candidate, query) => {
+    const needle = query.trim().toLowerCase();
+    return (!needle || candidate.name.toLowerCase().includes(needle) || (candidate.email ?? "").toLowerCase().startsWith(needle));
+};
+export const initials = (name) => name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0].toUpperCase())
+    .join("") || "?";

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

@@ -0,0 +1,76 @@
+import { type Rect } from "./layout.js";
+import { type TextPoint } from "./text-pick.js";
+import type { CommentAnchor } from "./types.js";
+/**
+ * Pointing at something on the page: what comment mode and the agent chat's pointer share. While
+ * active, hovering outlines the element under the pointer and a click (or the first tap on a touch
+ * screen) picks it, with any text selected inside it as the quote. Nothing in the app reacts to
+ * that click: no link opens, no handler runs. UI marked with `PICK_IGNORE_ATTRIBUTE` (the comments'
+ * own, the chat) is neither picked nor blocked.
+ *
+ * Over text, the pointer is a text cursor on the word under it, and a drag points at just the text
+ * it covers — never past the row it started in — picking its element with that text as the quote,
+ * on buttons and links too (the picker's own range, not the browser's selection). A press without
+ * a drag still picks the whole element.
+ */
+export interface PagePick {
+    anchor: CommentAnchor;
+    element: HTMLElement;
+}
+export interface UsePagePickOptions {
+    isActive: boolean;
+    /** The page's pathname, stored on the anchor. */
+    routePath: string;
+    onPick: (pick: PagePick) => void;
+    /** Esc while pointing. */
+    onCancel?: () => void;
+}
+/** Pointing at text: the word under the pointer, or the text a drag covers. */
+export interface PagePickText {
+    range: Range;
+    /** The caret position under the pointer; null while dragging. */
+    caret: TextPoint | null;
+    isSelecting: boolean;
+}
+export interface PagePickHover {
+    element: HTMLElement;
+    rect: Rect;
+    /** What the element is called, as its pick would be (`pickLabel`): its text, else its component's name, else the page. */
+    label: string;
+    /** Over text: what to tint (on screen, clipped) and where the caret bar goes. */
+    text?: {
+        rects: Rect[];
+        caret: {
+            x: number;
+            top: number;
+            bottom: number;
+        } | null;
+        isSelecting: boolean;
+    };
+}
+/**
+ * What the hover label shows for an element: what picking it would be labelled (`anchorLabel`) —
+ * its text, else its component's name, else the page; never its tag.
+ */
+export declare const pickLabel: (element: HTMLElement, routePath: string) => string;
+export interface PagePickListeners {
+    /** The page's pathname at the moment of the pick. */
+    routePath: () => string;
+    onPick: (pick: PagePick) => void;
+    onCancel: () => void;
+    /** The element the pointer is over (null when it left the page or is over ignored UI). */
+    onHover: (element: HTMLElement | null) => void;
+    /** The text the pointer is on, or a drag covers; null off text. */
+    onText?: (text: PagePickText | null) => void;
+}
+/** How the picker finds text under the pointer: the browser's caret, unless a test gives its own. */
+export interface PagePickTextLookup {
+    /** The text position under the pointer, only when it is on a word. */
+    textPointAt: (x: number, y: number) => TextPoint | null;
+    /** The nearest text position, wherever the pointer is (where a drag ends). */
+    caretAt: (x: number, y: number) => TextPoint | null;
+}
+/** Starts listening on `doc` for a pick; returns the stop. What `usePagePick` runs while active. */
+export declare const listenForPagePick: (doc: Document, listeners: PagePickListeners, lookup?: PagePickTextLookup) => (() => void);
+export declare const usePagePick: ({ isActive, routePath, onPick, onCancel }: UsePagePickOptions) => PagePickHover | null;
+//# sourceMappingURL=page-pick.d.ts.map

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

@@ -0,0 +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"}

package/dist/comments/page-pick.js

@@ -0,0 +1,267 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { anchorLabel, captureAnchor, isPickIgnored, pickTarget, textOf } from "./anchor.js";
+import { clipRectsOf, toRect, usePageLayoutTick, visiblePart } from "./layout.js";
+import { caretFromPoint, caretRectAt, clampToRoot, DRAG_THRESHOLD_PX, dragRootOf, rangeBetween, textPointAt, wordRangeAt, } from "./text-pick.js";
+/**
+ * What the hover label shows for an element: what picking it would be labelled (`anchorLabel`) —
+ * its text, else its component's name, else the page; never its tag.
+ */
+export const pickLabel = (element, routePath) => anchorLabel({
+    v: 1,
+    routePath,
+    element: {
+        devName: element.getAttribute("data-dev-name") ?? undefined,
+        textSnapshot: textOf(element) || undefined,
+    },
+});
+/** The page's text selection, if any: `captureAnchor` quotes it when it is inside the picked element. */
+const selectedRange = () => {
+    const selection = typeof window.getSelection === "function" ? window.getSelection() : null;
+    return selection && selection.rangeCount > 0 ? selection.getRangeAt(0) : null;
+};
+/** Stops the app hearing a press that is part of picking; leaves native text selection alone. */
+const swallow = (event) => {
+    if (!isPickIgnored(event.target)) {
+        event.stopPropagation();
+    }
+};
+/**
+ * The pickers listening now, oldest first. Comment mode and the chat's pointer can both be on:
+ * only the one started last hears the page, and the earlier one resumes when it stops.
+ */
+const listeningPicks = [];
+/** Starts listening on `doc` for a pick; returns the stop. What `usePagePick` runs while active. */
+export const listenForPagePick = (doc, listeners, lookup = {
+    textPointAt: (x, y) => textPointAt(doc, x, y),
+    caretAt: (x, y) => caretFromPoint(doc, x, y),
+}) => {
+    const self = {};
+    listeningPicks.push(self);
+    const isPaused = () => listeningPicks[listeningPicks.length - 1] !== self;
+    // A press on text, until its release: where it started, what it may cover, what it covers.
+    let drag = null;
+    // The click a drag's release makes: the drag already picked.
+    let isSwallowingClick = false;
+    // What was last reported: a move that changes nothing reports nothing (no re-render per pixel).
+    let shown = [null, 0, null, 0];
+    const showText = (text) => {
+        const next = text
+            ? text.isSelecting
+                ? [text.range.startContainer, text.range.startOffset, text.range.endContainer, text.range.endOffset]
+                : [text.caret?.node ?? null, text.caret?.offset ?? 0, null, -1]
+            : [null, 0, null, 0];
+        if (next.every((value, index) => value === shown[index])) {
+            return;
+        }
+        shown = next;
+        listeners.onText?.(text);
+    };
+    const pick = (element, range, event) => listeners.onPick({
+        element,
+        anchor: captureAnchor({
+            routePath: listeners.routePath(),
+            element,
+            range,
+            clientX: event.clientX,
+            clientY: event.clientY,
+        }),
+    });
+    /** A collapsed range at a text position: where a drag starts, the caret between words. */
+    const rangeAt = (point) => {
+        const range = doc.createRange();
+        range.setStart(point.node, point.offset);
+        return range;
+    };
+    const onOver = (event) => {
+        listeners.onHover(isPaused() ? null : pickTarget(event.target));
+    };
+    const onOut = (event) => {
+        if (!event.relatedTarget && !drag) {
+            listeners.onHover(null);
+            showText(null);
+        }
+    };
+    const onMove = (event) => {
+        if (drag) {
+            if (!drag.isMoved && Math.hypot(event.clientX - drag.x, event.clientY - drag.y) < DRAG_THRESHOLD_PX) {
+                return;
+            }
+            drag.isMoved = true;
+            const end = lookup.caretAt(event.clientX, event.clientY);
+            if (end) {
+                drag.range = rangeBetween(doc, drag.start, clampToRoot(drag.root, end));
+            }
+            showText({ range: drag.range, caret: null, isSelecting: true });
+            return;
+        }
+        if (isPaused() || isPickIgnored(event.target)) {
+            showText(null);
+            return;
+        }
+        const point = lookup.textPointAt(event.clientX, event.clientY);
+        if (!point) {
+            showText(null);
+            return;
+        }
+        // Between words: the caret alone, nothing tinted.
+        showText({ range: wordRangeAt(doc, point) ?? rangeAt(point), caret: point, isSelecting: false });
+    };
+    const onPress = (event) => {
+        isSwallowingClick = false;
+        if (isPaused() || event.button !== 0 || isPickIgnored(event.target)) {
+            return;
+        }
+        const point = lookup.textPointAt(event.clientX, event.clientY);
+        const root = point ? dragRootOf(point.node) : null;
+        if (!point || !root) {
+            return;
+        }
+        // The picker's own range, not a native selection (which buttons and links don't make).
+        event.preventDefault();
+        drag = { root, start: point, x: event.clientX, y: event.clientY, isMoved: false, range: rangeAt(point) };
+    };
+    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;
+        drag = null;
+        if (!finished?.isMoved) {
+            // A press without a drag: the click that follows picks the element.
+            return;
+        }
+        event.stopPropagation();
+        showText(null);
+        const { range, root } = finished;
+        if (range.collapsed || !range.toString().trim()) {
+            return;
+        }
+        const target = pickTarget(range.commonAncestorContainer);
+        isSwallowingClick = true;
+        pick(target && root.contains(target) ? target : root, range, event);
+    };
+    const onClick = (event) => {
+        if (isPaused()) {
+            isSwallowingClick = false;
+            return;
+        }
+        if (isSwallowingClick) {
+            isSwallowingClick = false;
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        const target = pickTarget(event.target);
+        if (!target) {
+            return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        pick(target, selectedRange(), event);
+    };
+    const onKeyDown = (event) => {
+        if (event.key === "Escape" && !isPaused() && !isPickIgnored(event.target)) {
+            event.stopPropagation();
+            if (drag) {
+                // Esc mid-drag drops the drag, not the mode, and the click its release makes picks nothing.
+                drag = null;
+                isSwallowingClick = true;
+                showText(null);
+                return;
+            }
+            listeners.onCancel();
+        }
+    };
+    // Menus and drags often act on press, not click: the app doesn't hear those either.
+    const presses = ["pointerdown", "mousedown", "touchstart"];
+    doc.addEventListener("mouseover", onOver);
+    doc.addEventListener("mouseout", onOut);
+    doc.addEventListener("mousemove", onMove, true);
+    doc.addEventListener("mousedown", onPress, true);
+    doc.addEventListener("mouseup", onRelease, true);
+    doc.addEventListener("click", onClick, true);
+    presses.forEach((type) => doc.addEventListener(type, swallow, true));
+    doc.addEventListener("keydown", onKeyDown, true);
+    return () => {
+        const index = listeningPicks.indexOf(self);
+        if (index >= 0) {
+            listeningPicks.splice(index, 1);
+        }
+        doc.removeEventListener("mouseover", onOver);
+        doc.removeEventListener("mouseout", onOut);
+        doc.removeEventListener("mousemove", onMove, true);
+        doc.removeEventListener("mousedown", onPress, true);
+        doc.removeEventListener("mouseup", onRelease, true);
+        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.
+            const swallowClick = (event) => {
+                event.preventDefault();
+                event.stopPropagation();
+            };
+            doc.addEventListener("click", swallowClick, { capture: true, once: true });
+            setTimeout(() => doc.removeEventListener("click", swallowClick, true), 0);
+            isSwallowingClick = false;
+        }
+    };
+};
+/** A text pick's tint and caret, on screen: each line's box, clipped by what scrolls it. */
+const textGeometry = (text) => {
+    const container = text.range.commonAncestorContainer;
+    const element = container instanceof Element ? container : container.parentElement;
+    const clips = element ? clipRectsOf(element) : [];
+    const rects = Array.from(text.range.getClientRects())
+        .map((rect) => visiblePart(toRect(rect), clips))
+        .filter((rect) => rect !== null && rect.right > rect.left);
+    const doc = element?.ownerDocument ?? document;
+    return { rects, caret: text.caret ? caretRectAt(doc, text.caret) : null, isSelecting: text.isSelecting };
+};
+export const usePagePick = ({ isActive, routePath, onPick, onCancel }) => {
+    // Not for the React Compiler (app-render compiles this module): the memo's input is the page's
+    // layout, read through `tick`, which the compiler would drop from the deps as unused.
+    "use no memo";
+    const [hovered, setHovered] = useState(null);
+    const [text, setText] = useState(null);
+    const latest = useRef({ routePath, onPick, onCancel });
+    useEffect(() => {
+        latest.current = { routePath, onPick, onCancel };
+    });
+    useEffect(() => {
+        if (!isActive || typeof document === "undefined") {
+            return;
+        }
+        const stop = listenForPagePick(document, {
+            routePath: () => latest.current.routePath,
+            onPick: (pick) => latest.current.onPick(pick),
+            onCancel: () => latest.current.onCancel?.(),
+            onHover: setHovered,
+            onText: setText,
+        });
+        return () => {
+            stop();
+            setHovered(null);
+            setText(null);
+        };
+    }, [isActive]);
+    // Per element, not per layout tick: reading a large element's text isn't free.
+    const label = useMemo(() => (hovered ? pickLabel(hovered, routePath) : ""), [hovered, routePath]);
+    const tick = usePageLayoutTick(isActive && hovered !== null);
+    return useMemo(() => {
+        void tick;
+        if (!isActive || !hovered?.isConnected) {
+            return null;
+        }
+        return {
+            element: hovered,
+            rect: toRect(hovered.getBoundingClientRect()),
+            label,
+            ...(text ? { text: textGeometry(text) } : {}),
+        };
+    }, [hovered, isActive, label, text, tick]);
+};

package/dist/comments/pick-message.d.ts

@@ -0,0 +1,11 @@
+import type { ComposerMessageMeta } from "../utils/composer-message.js";
+import { type CommentAnchor } from "./types.js";
+/** The text part a pick sends: the marker line, then the place described for the agent. */
+export declare const pagePickText: (anchor: CommentAnchor) => string;
+/** Arms the composer with a pick. */
+export declare const pagePickComposerMeta: (anchor: CommentAnchor) => ComposerMessageMeta;
+/** The pill's label for a sent or armed pick's text part, or null when the part isn't one. */
+export declare const parsePagePickPart: (text: string) => string | null;
+/** The label of the pick the composer is armed with, or null. */
+export declare const pagePickOf: (meta: ComposerMessageMeta | null | undefined) => string | null;
+//# sourceMappingURL=pick-message.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pick-message.d.ts","sourceRoot":"","sources":["../../src/comments/pick-message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAAE,KAAK,aAAa,EAA0B,MAAM,SAAS,CAAC;AAiBrE,2FAA2F;AAC3F,eAAO,MAAM,YAAY,GAAI,QAAQ,aAAa,KAAG,MAC+B,CAAC;AAErF,qCAAqC;AACrC,eAAO,MAAM,oBAAoB,GAAI,QAAQ,aAAa,KAAG,mBAE3D,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,IAMzD,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,UAAU,GAAI,MAAM,mBAAmB,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,IAGlF,CAAC"}

package/dist/comments/pick-message.js

@@ -0,0 +1,33 @@
+import { anchorLabel } from "./anchor.js";
+import { describeAnchorForAgent } from "./types.js";
+/**
+ * Pointing at something from the agent chat (BLK-1636): the pick rides with the next message as
+ * one leading text part — a first line the chat shows as a pill (`[Pointing at: <label>]`), then
+ * what the agent is told about the place, in the same words a comment gives it. Nothing is saved
+ * and no pin is made. The composer has one meta slot: a pick replaces armed feedback and back.
+ */
+const PREFIX = "[Pointing at: ";
+/**
+ * The label as the marker line carries it: as written, on one line. A "]" inside is safe — the
+ * readers find the line's end by "]\n", and the label holds no line break.
+ */
+const markerLabel = (label) => label.replace(/[\r\n]+/g, " ");
+/** The text part a pick sends: the marker line, then the place described for the agent. */
+export const pagePickText = (anchor) => `${PREFIX}${markerLabel(anchorLabel(anchor))}]\n${describeAnchorForAgent(anchor)}`;
+/** Arms the composer with a pick. */
+export const pagePickComposerMeta = (anchor) => ({
+    leadingParts: [{ type: "text", text: pagePickText(anchor) }],
+});
+/** The pill's label for a sent or armed pick's text part, or null when the part isn't one. */
+export const parsePagePickPart = (text) => {
+    if (!text.startsWith(PREFIX)) {
+        return null;
+    }
+    const end = text.indexOf("]\n", PREFIX.length);
+    return end < 0 ? null : text.slice(PREFIX.length, end);
+};
+/** The label of the pick the composer is armed with, or null. */
+export const pagePickOf = (meta) => {
+    const first = meta?.leadingParts?.[0]?.text;
+    return meta && !meta.name && first ? parsePagePickPart(first) : null;
+};

package/dist/comments/pins.d.ts

@@ -0,0 +1,72 @@
+import { type AnchorState, resolveAnchor } from "./anchor.js";
+import { type Rect } from "./layout.js";
+import type { CommentAnchor } from "./types.js";
+/**
+ * Where each thread's pin goes on the page as it is now. Never stored: worked out from the anchor
+ * every time the page moves, so a pin follows its element across screen sizes, re-sorted lists and
+ * scrolling.
+ */
+/** How far a pin keeps from the viewport's edges. */
+export declare const PIN_EDGE_MARGIN = 12;
+export interface PinPoint {
+    x: number;
+    y: number;
+}
+/**
+ * The pin's point, in viewport coordinates.
+ * - A quote: the end of its last line.
+ * - An element: where it was clicked, scaled to the element's box now; else its top-right corner.
+ */
+export declare const pinPoint: (target: {
+    kind: "quote";
+    lastLine: Rect;
+} | {
+    kind: "element";
+    rect: Rect;
+    point?: {
+        x: number;
+        y: number;
+    };
+}) => PinPoint;
+/** `point` kept `margin` inside the viewport. */
+export declare const keepInViewport: (point: PinPoint, viewport: {
+    width: number;
+    height: number;
+}, margin?: number) => {
+    x: number;
+    y: number;
+};
+export interface PinGroup<T> {
+    key: string;
+    point: PinPoint;
+    items: T[];
+}
+/** Pins on the same element become one group, at the first one's point (items in input order). */
+export declare const groupPins: <T>(pins: readonly {
+    key: string;
+    point: PinPoint;
+    item: T;
+}[]) => PinGroup<T>[];
+export interface ThreadLayout {
+    state: AnchorState;
+    element: HTMLElement | null;
+    /** Where the pin goes; null when there is nothing on screen to pin to (scrolled away, covered, missing). */
+    point: PinPoint | null;
+    /** Threads with the same key point at the same element. */
+    groupKey: string | null;
+    /** What the anchored text says now, when it changed. */
+    currentText?: string;
+}
+/**
+ * The comments' own layer (pins, threads) marks its root with this attribute: what it draws over an
+ * element doesn't hide the element. Other ignored UI (the agent chat's panel) does.
+ */
+export declare const COMMENTS_LAYER_ATTRIBUTE = "data-blocks-comments-layer";
+/** Lays out one anchor whose element is known. */
+export declare const layoutAnchor: (anchor: CommentAnchor, resolved: ReturnType<typeof resolveAnchor>) => ThreadLayout;
+/** Where each thread is on the page now, re-measured at most once per frame while `isActive`. */
+export declare const useCommentPins: (anchors: readonly {
+    id: string | number;
+    anchor: CommentAnchor;
+}[], isActive: boolean) => ReadonlyMap<string | number, ThreadLayout>;
+//# sourceMappingURL=pins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../../src/comments/pins.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAoC,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7F,OAAO,EAAe,KAAK,IAAI,EAA0C,MAAM,UAAU,CAAC;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;GAIG;AAEH,qDAAqD;AACrD,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GACnB,QAAQ;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAC5G,QAYF,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,cAAc,GACzB,OAAO,QAAQ,EACf,UAAU;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3C,eAAwB;;;CAIxB,CAAC;AAEH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ;AAED,kGAAkG;AAClG,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,MAAM,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,EAAE,KAAG,QAAQ,CAAC,CAAC,CAAC,EAWpG,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,4GAA4G;IAC5G,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID;;;GAGG;AACH,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAmBrE,kDAAkD;AAClD,eAAO,MAAM,YAAY,GAAI,QAAQ,aAAa,EAAE,UAAU,UAAU,CAAC,OAAO,aAAa,CAAC,KAAG,YAsBhG,CAAC;AAkBF,iGAAiG;AACjG,eAAO,MAAM,cAAc,GACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,EAAE,EAClE,UAAU,OAAO,KAChB,WAAW,CAAC,MAAM,GAAG,MAAM,EAAE,YAAY,CAgB3C,CAAC"}