@blocksdiy/react-common 1.70.2 → 1.71.0

package/dist/comments/threads-store.js

@@ -0,0 +1,286 @@
+import { websocketsService } from "@blocksdiy/blocks-client-api/websocketService";
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { CommentsRequestError } from "./api.js";
+import { CommentRealtimeEventTypes, } from "./types.js";
+/**
+ * The comment threads of one page of an app, kept current: the page's threads, the open thread's
+ * comments, and the people who can be mentioned. Every change another tab makes, and every step of
+ * an agent's reply (this tab's mention included), arrives as an ids-only `COMMENTS_CHANGED` ping,
+ * and the store refetches that thread by id, which applies who may see it (a 404 removes it).
+ * Writes return the thread as the server saved it; either way a thread is replaced by id, and an
+ * answer that crossed a newer one is read again rather than set the thread back.
+ */
+/** A page with more threads than this shows the newest ones. */
+export const MAX_THREADS_PER_PAGE = 500;
+/** Pings arriving together are refetched together. */
+export const LIVE_BATCH_MS = 150;
+const EMPTY = {
+    status: "idle",
+    threads: [],
+    details: new Map(),
+    threadLoads: new Map(),
+    mentionableUsers: [],
+};
+/** A thread's summary: everything but what only an opened thread carries. */
+const summaryOf = ({ resolvedByUserId: _resolvedByUserId, resolvedByAgentId: _resolvedByAgentId, resolvedAt: _resolvedAt, comments: _comments, ...summary }) => summary;
+const byNewest = (a, b) => b.lastActivityAt.localeCompare(a.lastActivityAt) || b.id - a.id;
+export class CommentThreadsStore {
+    options;
+    snapshot = EMPTY;
+    listeners = new Set();
+    routePath = null;
+    /** Bumps on every route change: an answer for an older route is dropped. */
+    generation = 0;
+    stopPings = null;
+    pendingIds = new Set();
+    batchTimer = null;
+    /** Answers taken in so far; `takenAt` holds the count as of each thread's latest one. */
+    taken = 0;
+    takenAt = new Map();
+    setTimer;
+    clearTimer;
+    constructor(options) {
+        this.options = options;
+        this.setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+        this.clearTimer = options.clearTimer ?? ((id) => clearTimeout(id));
+    }
+    getSnapshot = () => this.snapshot;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    /** Shows the threads of `routePath` (null: none, and stop listening). */
+    async setRoute(routePath) {
+        if (routePath === this.routePath) {
+            return;
+        }
+        this.routePath = routePath;
+        const generation = ++this.generation;
+        this.cancelBatch();
+        if (routePath === null) {
+            this.stopPings?.();
+            this.stopPings = null;
+            this.set(EMPTY);
+            return;
+        }
+        this.stopPings ??= this.options.subscribe((payload) => this.onPing(payload));
+        this.set({ ...EMPTY, status: "loading", mentionableUsers: this.snapshot.mentionableUsers });
+        try {
+            const [threads, users] = await Promise.all([
+                this.loadAll(routePath),
+                this.snapshot.mentionableUsers.length
+                    ? Promise.resolve(this.snapshot.mentionableUsers)
+                    : this.options.api.mentionableUsers().then(({ users }) => users),
+            ]);
+            if (generation === this.generation) {
+                // Threads that arrived while the list loaded (a ping, this tab's own write) are newer than
+                // the list's copy of them: they win, and their loaded comments stay.
+                const arrived = this.snapshot.threads;
+                const arrivedIds = new Set(arrived.map((thread) => thread.id));
+                this.set({
+                    status: "ready",
+                    // The list comes newest first, and what arrived meanwhile is newer still.
+                    threads: [...arrived, ...threads.filter((thread) => !arrivedIds.has(thread.id))],
+                    details: this.snapshot.details,
+                    threadLoads: this.snapshot.threadLoads,
+                    mentionableUsers: users,
+                });
+            }
+        }
+        catch {
+            if (generation === this.generation) {
+                this.set({ ...this.snapshot, status: "error" });
+            }
+        }
+    }
+    /**
+     * Loads a thread's comments (when it is opened). Until they are in, `threadLoads` says where it
+     * stands; a thread already loaded stays shown while it is read again.
+     */
+    async loadThread(threadId) {
+        const generation = this.generation;
+        this.setLoad(threadId, "loading");
+        const thread = await this.refetch(threadId);
+        if (!thread && generation === this.generation && this.snapshot.threadLoads.get(threadId) === "loading") {
+            this.setLoad(threadId, "failed");
+        }
+        return thread;
+    }
+    createThread(anchor, body) {
+        return this.write(() => this.options.api.createThread({ anchor, body }));
+    }
+    addComment(threadId, body) {
+        return this.write(() => this.options.api.addComment(threadId, body));
+    }
+    updateComment(commentId, body) {
+        return this.write(() => this.options.api.updateComment(commentId, body));
+    }
+    /**
+     * Deletes one of the reader's comments. Null when it was the thread's last (no person's or agent's
+     * left): the thread is gone, and goes from the store as a 404 takes it (`not_found`).
+     */
+    async deleteComment(commentId) {
+        // The thread it is in, known before the answer: an answer with no thread doesn't name it.
+        const threadId = [...this.snapshot.details.values()].find((thread) => thread.comments.some((comment) => comment.id === commentId))?.id;
+        const generation = this.generation;
+        const thread = await this.write(() => this.options.api.deleteComment(commentId));
+        if (!thread && threadId !== undefined && generation === this.generation) {
+            this.remove(threadId);
+            this.setLoad(threadId, "not_found");
+        }
+        return thread;
+    }
+    setResolved(threadId, resolved) {
+        const api = this.options.api;
+        return this.write(() => (resolved ? api.resolveThread(threadId) : api.reopenThread(threadId)));
+    }
+    dispose() {
+        this.cancelBatch();
+        this.stopPings?.();
+        this.stopPings = null;
+        // A remount (React StrictMode in dev) sets the route again: it must load and listen anew.
+        this.routePath = null;
+        this.generation += 1;
+    }
+    async loadAll(routePath) {
+        const threads = [];
+        let cursor;
+        do {
+            const page = await this.options.api.listThreads(routePath, { cursor });
+            threads.push(...page.threads);
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor && threads.length < MAX_THREADS_PER_PAGE);
+        return threads.slice(0, MAX_THREADS_PER_PAGE);
+    }
+    onPing(payload) {
+        if (payload.appId !== this.options.appId || this.routePath === null) {
+            return;
+        }
+        this.pendingIds.add(payload.threadId);
+        this.batchTimer ??= this.setTimer(() => {
+            this.batchTimer = null;
+            const ids = [...this.pendingIds];
+            this.pendingIds.clear();
+            ids.forEach((id) => void this.refetch(id));
+        }, LIVE_BATCH_MS);
+    }
+    cancelBatch() {
+        if (this.batchTimer !== null) {
+            this.clearTimer(this.batchTimer);
+            this.batchTimer = null;
+        }
+        this.pendingIds.clear();
+    }
+    /*
+     * One rule for every answer, a read's or a write's: when the thread took another answer after this
+     * request was sent, this one may be the older of the two, so it is not taken; the thread is read
+     * again instead (a read sent now holds both) and that answer is taken. Once: steady pings can't
+     * make it loop.
+     */
+    /** Whether the thread took an answer after a request sent at `sentAt` (a count of answers taken). */
+    isCrossed(threadId, sentAt) {
+        return (this.takenAt.get(threadId) ?? 0) > sentAt;
+    }
+    /**
+     * Reads a thread and takes in the answer, by the rule above (`mayRetry` false: this is the read
+     * again, taken as it is). A 404 removes the thread. Returns the thread as the store has it now.
+     */
+    async refetch(threadId, mayRetry = true) {
+        const generation = this.generation;
+        const sentAt = this.taken;
+        let thread;
+        try {
+            thread = await this.options.api.getThread(threadId);
+        }
+        catch (error) {
+            if (error instanceof CommentsRequestError && error.status === 404 && generation === this.generation) {
+                this.remove(threadId);
+                this.setLoad(threadId, "not_found");
+            }
+            return null;
+        }
+        if (generation !== this.generation) {
+            return thread;
+        }
+        if (mayRetry && this.isCrossed(threadId, sentAt)) {
+            // Should the read again fail, the newer answer the thread took stays.
+            return (await this.refetch(threadId, false)) ?? this.snapshot.details.get(threadId) ?? null;
+        }
+        return this.apply(thread);
+    }
+    /**
+     * Sends a write and takes in its answer, by the rule above. Should reading the thread again fail,
+     * the write's answer is taken all the same, unless the thread is gone: the person's own change
+     * must show, and their tab gets no ping for it.
+     */
+    async write(send) {
+        const sentAt = this.taken;
+        const thread = await send();
+        // No thread in the answer: the caller says what became of it.
+        if (!thread) {
+            return thread;
+        }
+        if (this.isCrossed(thread.id, sentAt)) {
+            const reread = await this.refetch(thread.id, false);
+            if (reread || !this.snapshot.details.has(thread.id)) {
+                return (reread ?? thread);
+            }
+        }
+        return this.apply(thread);
+    }
+    /** Takes in a thread as the server returned it. A thread of another page is kept out of the list. */
+    apply(thread) {
+        this.takenAt.set(thread.id, ++this.taken);
+        const details = new Map(this.snapshot.details);
+        details.set(thread.id, thread);
+        const others = this.snapshot.threads.filter((existing) => existing.id !== thread.id);
+        const threads = thread.routePath === this.routePath ? [summaryOf(thread), ...others].sort(byNewest) : others;
+        const threadLoads = new Map(this.snapshot.threadLoads);
+        threadLoads.delete(thread.id);
+        this.set({ ...this.snapshot, threads, details, threadLoads });
+        return thread;
+    }
+    setLoad(threadId, state) {
+        const threadLoads = new Map(this.snapshot.threadLoads);
+        threadLoads.set(threadId, state);
+        this.set({ ...this.snapshot, threadLoads });
+    }
+    remove(threadId) {
+        // A removal is an answer too: an older read landing after it is crossed, and reads again.
+        this.takenAt.set(threadId, ++this.taken);
+        const details = new Map(this.snapshot.details);
+        details.delete(threadId);
+        this.set({
+            ...this.snapshot,
+            threads: this.snapshot.threads.filter((thread) => thread.id !== threadId),
+            details,
+        });
+    }
+    set(snapshot) {
+        this.snapshot = snapshot;
+        this.listeners.forEach((listener) => listener());
+    }
+}
+/** Subscribes through the SDK's websocket connection (the app channel the app already joined). */
+export const subscribeWithWebsockets = (service) => (appId) => (onPing) => {
+    const callback = async (data) => onPing(data);
+    service.listen(CommentRealtimeEventTypes.COMMENTS_CHANGED, callback, { filter: { appId } });
+    return () => service.unlisten(CommentRealtimeEventTypes.COMMENTS_CHANGED, callback);
+};
+/** The app's comment pings, on the websocket connection the SDK opened for the app. */
+export const commentPingsFor = (appId) => subscribeWithWebsockets(websocketsService)(appId);
+/**
+ * The threads of the current page while `isActive` (comment mode on): nothing is loaded and nothing
+ * listened to otherwise.
+ */
+export const useCommentThreads = ({ api, appId, subscribe, routePath, isActive, }) => {
+    const store = useMemo(() => new CommentThreadsStore({ api, appId, subscribe }), [api, appId, subscribe]);
+    useEffect(() => () => store.dispose(), [store]);
+    useEffect(() => {
+        void store.setRoute(isActive ? routePath : null);
+    }, [store, isActive, routePath]);
+    const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    return { store, snapshot };
+};

package/dist/comments/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The wire shapes and values of in-app comments, as the activity service sends and takes them.
+ *
+ * A copy of `@blockscom/common`'s `types/comments/comments-api.ts`: this package is public and does
+ * not depend on that one. A spec here (`test/comments/wire-contract.spec.ts`) keeps the two the
+ * same: change both.
+ */
+/** The text that was highlighted, with a little context on each side (W3C TextQuoteSelector). */
+export interface CommentAnchorText {
+    exact: string;
+    prefix: string;
+    suffix: string;
+}
+/**
+ * The element a comment points at. No single id survives an edit to the app (`data-dev-id` is
+ * `file:line:col`), so the anchor keeps several signals and the client tries them in order.
+ */
+export interface CommentAnchorElement {
+    /** `data-dev-id` when the comment was made: exact while the code hasn't moved. */
+    devId?: string;
+    /** `data-dev-path`: the source file the element is rendered from. */
+    devPath?: string;
+    /** `data-dev-name`: the JSX element or component name. */
+    devName?: string;
+    /** Which match it was among the root's elements with the same `devPath` + `devName`. */
+    ordinal?: number;
+    /** A CSS path from the anchor root (the row's element, or the body): the last resort. */
+    domPath?: string;
+    tagName?: string;
+    /** The element's text when the comment was made (whitespace collapsed, capped). */
+    textSnapshot?: string;
+}
+/** The data row the element shows, when the app marks it (`itemAnchorProps` → `data-blocks-item`). */
+export interface CommentAnchorItem {
+    /** The table as the app's code names it (`<Name>Entity.tableBlockId`). */
+    tableBlockId: string;
+    itemId: string;
+    /** The column the picked element shows, when the app tagged it (`fieldAnchorProps`). */
+    field?: string;
+}
+/** Where a thread lives inside the app. Stored as the client sent it; resolved on every render. */
+export interface CommentAnchor {
+    v: 1;
+    /** The page's pathname, e.g. `/orders/123`: no query, no hash. Threads are listed per pathname. */
+    routePath: string;
+    item?: CommentAnchorItem;
+    element?: CommentAnchorElement;
+    text?: CommentAnchorText;
+    /** Where in the element the comment was dropped, as fractions of its box (0..1). */
+    point?: {
+        x: number;
+        y: number;
+    };
+}
+export type CommentThreadStatus = "open" | "resolved";
+/**
+ * An agent's reply to a comment that mentioned it. The first three states are open: at most one
+ * open reply exists per thread, agent and person who asked.
+ *
+ * - `working`: the agent is on it (a progress line in the body when it sent one).
+ * - `needs_input`: the agent asked the person a question, answered in the thread.
+ * - `waiting_in_chat`: the run paused on an approval or a question, answered in the agent's chat.
+ * - `done`: the answer is in the body.
+ * - `failed`: the agent could not finish (its reason in the body when it gave one).
+ */
+export type CommentAgentReplyState = "working" | "needs_input" | "waiting_in_chat" | "done" | "failed";
+export declare const OPEN_AGENT_REPLY_STATES: readonly CommentAgentReplyState[];
+/** A `working` reply with no update for this long reads as `failed`: its run was lost. */
+export declare const AGENT_REPLY_STALE_AFTER_MS: number;
+export type CommentAuthorDto = {
+    type: "user";
+    userId: number;
+} | {
+    type: "agent";
+    agentId: string;
+    requestedByUserId: number;
+};
+export interface CommentAgentReplyDto {
+    state: CommentAgentReplyState;
+    /**
+     * The agent's conversation for this thread with the person who asked (`author.requestedByUserId`):
+     * present for everyone who sees the reply. Everyone may read it; only the asker writes in it.
+     */
+    agentChatThreadId?: string;
+}
+/**
+ * A comment's conversation with an agent (`comment-<threadId>-u<askerUserId>`, as activity and
+ * wf-actions-py mint it) read back: the comment thread it is about and the person who asked. Null
+ * for any other chat thread id.
+ */
+export declare const parseCommentAgentChatThreadId: (chatThreadId: string | null | undefined) => {
+    threadId: number;
+    askerUserId: number;
+} | null;
+export interface CommentDto {
+    id: number;
+    threadId: number;
+    author: CommentAuthorDto;
+    /**
+     * Plain text. A person is mentioned as `@[<userId>]`, an agent as `@[agent:<agentId>]`. Empty
+     * when deleted.
+     */
+    body: string;
+    mentionedUserIds: number[];
+    mentionedAgentIds: string[];
+    /** Present on an agent's reply. */
+    agentReply?: CommentAgentReplyDto;
+    createdAt: string;
+    editedAt: string | null;
+    deleted: boolean;
+}
+/** Someone with a comment in a thread: a person or an agent. */
+export type CommentParticipantDto = {
+    type: "user";
+    userId: number;
+} | {
+    type: "agent";
+    agentId: string;
+};
+export interface CommentThreadSummaryDto {
+    id: number;
+    appId: string;
+    routePath: string;
+    anchor: CommentAnchor;
+    status: CommentThreadStatus;
+    createdByUserId: number;
+    createdAt: string;
+    lastActivityAt: string;
+    commentCount: number;
+    /** The agent working on the thread right now (a `working` reply, not one waiting on a person): the pin's spinner. */
+    workingAgentId: string | null;
+    /** Everyone with a comment in the thread, by their first comment: the starter first. */
+    participants: CommentParticipantDto[];
+}
+export interface CommentThreadDto extends CommentThreadSummaryDto {
+    resolvedByUserId: number | null;
+    resolvedByAgentId: string | null;
+    resolvedAt: string | null;
+    /** Oldest first; the newest `COMMENT_THREAD_MAX_COMMENTS`. */
+    comments: CommentDto[];
+}
+export interface CommentThreadsPageDto {
+    threads: CommentThreadSummaryDto[];
+    /** Pass back as `cursor` for the next page; `null` on the last one. */
+    nextCursor: string | null;
+}
+/** Someone the caller can mention: an active member of the account who can open the app. */
+export interface MentionableUserDto {
+    userId: number;
+    name: string;
+    email: string | null;
+    profileImageUrl: string | null;
+}
+export interface MentionableUsersDto {
+    users: MentionableUserDto[];
+}
+/** Limits, shared by the API's validation and the composer. */
+export declare const COMMENT_BODY_MAX_LENGTH = 5000;
+export declare const COMMENT_ANCHOR_TEXT_MAX_LENGTH = 1000;
+export declare const COMMENT_ANCHOR_CONTEXT_MAX_LENGTH = 64;
+/** A tagged column's name (`CommentAnchorItem.field`). */
+export declare const COMMENT_ANCHOR_FIELD_MAX_LENGTH = 255;
+export declare const COMMENT_ROUTE_PATH_MAX_LENGTH = 512;
+export declare const COMMENT_MAX_USER_MENTIONS = 20;
+export declare const COMMENT_MAX_AGENT_MENTIONS = 3;
+export declare const COMMENT_THREADS_PAGE_SIZE = 100;
+export declare const COMMENT_THREAD_MAX_COMMENTS = 200;
+/** A person mentioned in a body: `@[42]`. */
+export declare const COMMENT_USER_MENTION_PATTERN: RegExp;
+/** An agent mentioned in a body: `@[agent:SupportAgent]` (the agent block's name). */
+export declare const COMMENT_AGENT_MENTION_PATTERN: RegExp;
+/** The people and agents a body mentions, deduplicated, in order of first mention. */
+export declare const parseCommentMentions: (body: string) => {
+    userIds: number[];
+    agentIds: string[];
+};
+/** Pusher events activity sends on `private-app-<appId>`. */
+export declare enum CommentRealtimeEventTypes {
+    COMMENTS_CHANGED = "COMMENTS_CHANGED"
+}
+export type CommentsChangedReason = "thread_created" | "created" | "edited" | "deleted" | "resolved" | "reopened" | "agent_reply";
+/**
+ * `COMMENTS_CHANGED`: a thread changed. Ids only, never text or the page: Pusher is not where
+ * customer content goes (HIPAA), and an installed app's channel is shared by every account that
+ * installed it. Clients refetch the thread by id, which applies who may see it.
+ */
+export interface CommentsChangedPayload {
+    /** Comments are per account: a client ignores pings for an account it is not signed into. */
+    accountId: number;
+    appId: string;
+    threadId: number;
+    reason: CommentsChangedReason;
+    commentId?: number;
+}
+/** Notification `source`s for comments. */
+export declare const COMMENT_NOTIFICATION_SOURCES: {
+    readonly mention: "comments.mention";
+    readonly reply: "comments.reply";
+    readonly agentReply: "comments.agent-reply";
+};
+/** The reply handler key of comment notifications: a reply typed into one is posted in its thread. */
+export declare const COMMENT_REPLY_HANDLER_KEY = "comments.reply";
+/** The query parameter that opens a thread when the app loads (notification links). */
+export declare const COMMENT_THREAD_QUERY_PARAM = "comment";
+/**
+ * What the agent is told about the place a comment (or a pick from the chat) points at. The same
+ * words wherever the agent hears it from: react-common has a twin, and a spec keeps them equal.
+ */
+export declare const describeAnchorForAgent: (anchor: CommentAnchor) => string;
+/**
+ * A comment's message in an agent's chat: one leading line naming the comment, then its text.
+ * activity writes it when a comment starts or continues an agent's turn; the chat reads it to
+ * show the message as the comment it is (what it is on, a link back to the thread). The agent
+ * reads the line too.
+ *
+ *   [Comment #7 on “Q4 invoice” · /tasks/board]
+ *   @Ron why is this late?
+ */
+export interface CommentChatMessage {
+    threadId: number;
+    /** What the comment is on, short (`commentSubjectOf`). */
+    label: string;
+    /** The page the thread is on. */
+    routePath: string;
+    text: string;
+}
+/** What a comment is on, in a few words: its quote, else its element's text or name, else its page. */
+export declare const commentSubjectOf: (anchor: CommentAnchor) => string;
+export declare const commentChatText: (message: CommentChatMessage) => string;
+/** A chat message's text as the comment it carries, or null when it isn't one. */
+export declare const parseCommentChatPart: (text: string) => CommentChatMessage | null;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/comments/types.js

@@ -0,0 +1,109 @@
+/**
+ * The wire shapes and values of in-app comments, as the activity service sends and takes them.
+ *
+ * A copy of `@blockscom/common`'s `types/comments/comments-api.ts`: this package is public and does
+ * not depend on that one. A spec here (`test/comments/wire-contract.spec.ts`) keeps the two the
+ * same: change both.
+ */
+export const OPEN_AGENT_REPLY_STATES = ["working", "needs_input", "waiting_in_chat"];
+/** A `working` reply with no update for this long reads as `failed`: its run was lost. */
+export const AGENT_REPLY_STALE_AFTER_MS = 30 * 60 * 1000;
+const COMMENT_AGENT_CHAT_THREAD_PATTERN = /^comment-(\d{1,15})-u(\d{1,15})$/;
+/**
+ * A comment's conversation with an agent (`comment-<threadId>-u<askerUserId>`, as activity and
+ * wf-actions-py mint it) read back: the comment thread it is about and the person who asked. Null
+ * for any other chat thread id.
+ */
+export const parseCommentAgentChatThreadId = (chatThreadId) => {
+    const match = chatThreadId ? COMMENT_AGENT_CHAT_THREAD_PATTERN.exec(chatThreadId) : null;
+    return match ? { threadId: Number(match[1]), askerUserId: Number(match[2]) } : null;
+};
+/** Limits, shared by the API's validation and the composer. */
+export const COMMENT_BODY_MAX_LENGTH = 5_000;
+export const COMMENT_ANCHOR_TEXT_MAX_LENGTH = 1_000;
+export const COMMENT_ANCHOR_CONTEXT_MAX_LENGTH = 64;
+/** A tagged column's name (`CommentAnchorItem.field`). */
+export const COMMENT_ANCHOR_FIELD_MAX_LENGTH = 255;
+export const COMMENT_ROUTE_PATH_MAX_LENGTH = 512;
+export const COMMENT_MAX_USER_MENTIONS = 20;
+export const COMMENT_MAX_AGENT_MENTIONS = 3;
+export const COMMENT_THREADS_PAGE_SIZE = 100;
+export const COMMENT_THREAD_MAX_COMMENTS = 200;
+/** A person mentioned in a body: `@[42]`. */
+export const COMMENT_USER_MENTION_PATTERN = /@\[(\d{1,12})\]/g;
+/** An agent mentioned in a body: `@[agent:SupportAgent]` (the agent block's name). */
+export const COMMENT_AGENT_MENTION_PATTERN = /@\[agent:([^\]\n]{1,255})\]/g;
+/** The people and agents a body mentions, deduplicated, in order of first mention. */
+export const parseCommentMentions = (body) => {
+    const userIds = new Set();
+    const agentIds = new Set();
+    for (const match of body.matchAll(COMMENT_USER_MENTION_PATTERN)) {
+        userIds.add(Number(match[1]));
+    }
+    for (const match of body.matchAll(COMMENT_AGENT_MENTION_PATTERN)) {
+        agentIds.add(match[1]);
+    }
+    return { userIds: [...userIds], agentIds: [...agentIds] };
+};
+/** Pusher events activity sends on `private-app-<appId>`. */
+export var CommentRealtimeEventTypes;
+(function (CommentRealtimeEventTypes) {
+    CommentRealtimeEventTypes["COMMENTS_CHANGED"] = "COMMENTS_CHANGED";
+})(CommentRealtimeEventTypes || (CommentRealtimeEventTypes = {}));
+/** Notification `source`s for comments. */
+export const COMMENT_NOTIFICATION_SOURCES = {
+    mention: "comments.mention",
+    reply: "comments.reply",
+    agentReply: "comments.agent-reply",
+};
+/** The reply handler key of comment notifications: a reply typed into one is posted in its thread. */
+export const COMMENT_REPLY_HANDLER_KEY = "comments.reply";
+/** The query parameter that opens a thread when the app loads (notification links). */
+export const COMMENT_THREAD_QUERY_PARAM = "comment";
+const AGENT_TEXT_MAX = 300;
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max)}…` : text);
+/**
+ * What the agent is told about the place a comment (or a pick from the chat) points at. The same
+ * words wherever the agent hears it from: react-common has a twin, and a spec keeps them equal.
+ */
+export const describeAnchorForAgent = (anchor) => {
+    const lines = [`Page: ${anchor.routePath}`];
+    const element = anchor.element;
+    if (element?.devName || element?.tagName) {
+        const name = element.devName ?? element.tagName.toLowerCase();
+        lines.push(element.textSnapshot ? `Element: ${name} ("${clip(element.textSnapshot, AGENT_TEXT_MAX)}")` : `Element: ${name}`);
+    }
+    if (anchor.text?.exact) {
+        lines.push(`Quoted text: "${clip(anchor.text.exact, AGENT_TEXT_MAX)}"`);
+    }
+    if (anchor.item) {
+        lines.push(`Table: ${anchor.item.tableBlockId}`, `Row id: ${anchor.item.itemId}`);
+        if (anchor.item.field) {
+            lines.push(`Field: ${anchor.item.field}`);
+        }
+        lines.push("The table and row id name that record: read or update it with your data tools.");
+    }
+    return lines.join("\n");
+};
+const COMMENT_CHAT_LABEL_MAX = 80;
+const COMMENT_CHAT_PATTERN = /^\[Comment #(\d{1,20}) on “([^”\n]*)” · ([^\]\n]*)\]\n/;
+/** What a comment is on, in a few words: its quote, else its element's text or name, else its page. */
+export const commentSubjectOf = (anchor) => anchor.text?.exact || anchor.element?.textSnapshot || anchor.element?.devName || anchor.routePath;
+export const commentChatText = (message) => {
+    const label = clip(message.label.replace(/\s+/g, " ").replace(/”/g, "'").trim(), COMMENT_CHAT_LABEL_MAX);
+    const routePath = message.routePath.replace(/[\]\r\n]/g, "");
+    return `[Comment #${message.threadId} on “${label}” · ${routePath}]\n${message.text}`;
+};
+/** A chat message's text as the comment it carries, or null when it isn't one. */
+export const parseCommentChatPart = (text) => {
+    const match = COMMENT_CHAT_PATTERN.exec(text);
+    if (!match) {
+        return null;
+    }
+    return {
+        threadId: Number(match[1]),
+        label: match[2],
+        routePath: match[3],
+        text: text.slice(match[0].length),
+    };
+};

package/dist/hooks/agent-conversation-context.d.ts

@@ -10,9 +10,20 @@ export interface AgentConversationContextValue {
     isDraft: boolean;
     /** The index under `filters`; its `renameThread` also keeps the open conversation's remembered title current. */
     threads: UseAgentThreadsResult;
-    /** The open conversation's row: listed, else the last listed, else a stand-in (`isStandIn`). */
+    /**
+     * The open conversation's row: listed, else the last listed, else a stand-in (`isStandIn`), which
+     * shows the conversation's own title and status once they are read (`shownConversationRow`).
+     */
     row: AgentThreadItem;
     isStandIn: boolean;
+    /**
+     * The open conversation's own read is done and the server has no row for it that this reader
+     * may see (a 404): someone else's comment conversation the reader can't see, or — briefly — a
+     * conversation just started whose row hasn't landed. A host tells the two apart (react-common's
+     * `parseCommentAgentChatThreadId`) before saying the conversation isn't available. False for a
+     * draft and while the read is in flight.
+     */
+    isConversationMissing: boolean;
     filters: AgentThreadFilters;
     setFilters: (filters: AgentThreadFilters) => void;
     hasActiveFilters: boolean;

package/dist/hooks/agent-conversation-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-conversation-context.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-conversation-context.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,SAAS,EAAwB,MAAM,OAAO,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAmB,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE/G,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAEnF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,iHAAiH;IACjH,OAAO,EAAE,qBAAqB,CAAC;IAC/B,gGAAgG;IAChG,GAAG,EAAE,eAAe,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,UAAU,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAClD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uFAAuF;IACvF,iBAAiB,EAAE,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;CACpE;AAID,MAAM,WAAW,8BAA+B,SAAQ,IAAI,CAC1D,sBAAsB,EACtB,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CACvD;IACC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,qBAAqB,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,OAAO,EACP,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,QAAQ,GACT,EAAE,8BAA8B,+BAyBhC;AAED,MAAM,MAAM,oCAAoC,GAAG,8BAA8B,CAAC;AAKlF;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,OAAO,EACP,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,oCAAoC,+BAetC;AA2CD,eAAO,MAAM,2BAA2B,QAAO,6BAQ9C,CAAC"}
+{"version":3,"file":"agent-conversation-context.d.ts","sourceRoot":"","sources":["../../src/hooks/agent-conversation-context.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,SAAS,EAAwB,MAAM,OAAO,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAGzB,KAAK,0BAA0B,EAChC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAmB,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE/G,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAMnF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,iHAAiH;IACjH,OAAO,EAAE,qBAAqB,CAAC;IAC/B;;;OAGG;IACH,GAAG,EAAE,eAAe,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,qBAAqB,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,UAAU,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAClD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uFAAuF;IACvF,iBAAiB,EAAE,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;CACpE;AAID,MAAM,WAAW,8BAA+B,SAAQ,IAAI,CAC1D,sBAAsB,EACtB,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CACvD;IACC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,oBAAoB,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,qBAAqB,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,OAAO,EACP,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,QAAQ,GACT,EAAE,8BAA8B,+BA+BhC;AAED,MAAM,MAAM,oCAAoC,GAAG,8BAA8B,CAAC;AAKlF;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,OAAO,EACP,YAAY,EACZ,OAAO,EACP,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE,oCAAoC,+BAgBtC;AAiDD,eAAO,MAAM,2BAA2B,QAAO,6BAQ9C,CAAC"}