@tribe-nest/forge 3.60.0 → 3.63.0

package/src/ui/headless/community/countries.ts

@@ -0,0 +1,123 @@
+/**
+ * Countries for the member directory and map: every ISO 3166-1 alpha-2 code a
+ * member may pick, a name for it in the viewer's language (through
+ * `Intl.DisplayNames`, so no name list ships), and an approximate centre per
+ * country for placing a dot on the member globe.
+ *
+ * The centres began as the admin analytics globe's table
+ * (apps/admin/.../analytics/-components/country-centroids.ts), which Forge
+ * cannot import, extended to most countries. They place a country-level dot and
+ * nothing finer: members choose a country, never a location. A country missing
+ * a centre still lists in the directory, it just has no dot.
+ */
+
+/** Every ISO 3166-1 alpha-2 code, as a member can choose one. */
+// prettier-ignore
+export const COUNTRY_CODES: readonly string[] = [
+  "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ",
+  "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS",
+  "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN",
+  "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE",
+  "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF",
+  "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM",
+  "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM",
+  "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC",
+  "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK",
+  "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA",
+  "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG",
+  "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW",
+  "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS",
+  "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO",
+  "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI",
+  "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW",
+];
+
+/** Approximate centre of each country, alpha-2 to [latitude, longitude]. */
+// prettier-ignore
+export const COUNTRY_CENTROIDS: Readonly<Record<string, readonly [number, number]>> = {
+  AD: [42.5, 1.6], AE: [23.4, 53.8], AF: [33.9, 67.7], AG: [17.1, -61.8], AL: [41.2, 20.2],
+  AM: [40.1, 45.0], AO: [-11.2, 17.9], AR: [-38.4, -63.6], AT: [47.5, 14.6], AU: [-25.3, 133.8],
+  AZ: [40.1, 47.6], BA: [43.9, 17.7], BB: [13.2, -59.5], BD: [23.7, 90.4], BE: [50.5, 4.5],
+  BF: [12.2, -1.6], BG: [42.7, 25.5], BH: [26.0, 50.6], BI: [-3.4, 29.9], BJ: [9.3, 2.3],
+  BN: [4.5, 114.7], BO: [-16.3, -63.6], BR: [-14.2, -51.9], BS: [25.0, -77.4], BT: [27.5, 90.4],
+  BW: [-22.3, 24.7], BY: [53.7, 27.9], BZ: [17.2, -88.5], CA: [56.1, -106.3], CD: [-4.0, 21.8],
+  CF: [6.6, 20.9], CG: [-0.2, 15.8], CH: [46.8, 8.2], CI: [7.5, -5.5], CL: [-35.7, -71.5],
+  CM: [7.4, 12.4], CN: [35.9, 104.2], CO: [4.6, -74.3], CR: [9.7, -83.8], CU: [21.5, -77.8],
+  CV: [16.0, -24.0], CY: [35.1, 33.4], CZ: [49.8, 15.5], DE: [51.2, 10.5], DJ: [11.8, 42.6],
+  DK: [56.3, 9.5], DM: [15.4, -61.4], DO: [18.7, -70.2], DZ: [28.0, 1.7], EC: [-1.8, -78.2],
+  EE: [58.6, 25.0], EG: [26.8, 30.8], ER: [15.2, 39.8], ES: [40.5, -3.7], ET: [9.1, 40.5],
+  FI: [61.9, 25.7], FJ: [-17.7, 178.1], FR: [46.2, 2.2], GA: [-0.8, 11.6], GB: [55.4, -3.4],
+  GD: [12.1, -61.7], GE: [42.3, 43.4], GH: [7.9, -1.0], GL: [71.7, -42.6], GM: [13.4, -15.3],
+  GN: [9.9, -9.7], GQ: [1.7, 10.3], GR: [39.1, 21.8], GT: [15.8, -90.2], GW: [11.8, -15.2],
+  GY: [4.9, -58.9], HK: [22.3, 114.2], HN: [15.2, -86.2], HR: [45.1, 15.2], HT: [18.97, -72.3],
+  HU: [47.2, 19.5], ID: [-0.8, 113.9], IE: [53.4, -8.2], IL: [31.0, 34.9], IN: [20.6, 79.0],
+  IQ: [33.2, 43.7], IR: [32.4, 53.7], IS: [65.0, -19.0], IT: [41.9, 12.6], JM: [18.1, -77.3],
+  JO: [30.6, 36.2], JP: [36.2, 138.3], KE: [-0.02, 37.9], KG: [41.2, 74.8], KH: [12.6, 104.99],
+  KM: [-11.9, 43.9], KN: [17.4, -62.8], KP: [40.3, 127.5], KR: [35.9, 127.8], KW: [29.3, 47.5],
+  KZ: [48.0, 66.9], LA: [19.9, 102.5], LB: [33.9, 35.9], LC: [13.9, -60.98], LI: [47.2, 9.6],
+  LK: [7.9, 80.8], LR: [6.4, -9.4], LS: [-29.6, 28.2], LT: [55.2, 23.9], LU: [49.8, 6.1],
+  LV: [56.9, 24.6], LY: [26.3, 17.2], MA: [31.8, -7.1], MC: [43.7, 7.4], MD: [47.4, 28.4],
+  ME: [42.7, 19.4], MG: [-18.8, 46.9], MK: [41.6, 21.7], ML: [17.6, -4.0], MM: [21.9, 95.96],
+  MN: [46.9, 103.8], MO: [22.2, 113.5], MR: [21.0, -10.9], MT: [35.9, 14.4], MU: [-20.3, 57.6],
+  MV: [3.2, 73.2], MW: [-13.3, 34.3], MX: [23.6, -102.6], MY: [4.2, 101.9], MZ: [-18.7, 35.5],
+  NA: [-22.9, 18.5], NE: [17.6, 8.1], NG: [9.1, 8.7], NI: [12.9, -85.2], NL: [52.1, 5.3],
+  NO: [60.5, 8.5], NP: [28.4, 84.1], NZ: [-40.9, 174.9], OM: [21.5, 55.9], PA: [8.5, -80.8],
+  PE: [-9.2, -75.0], PG: [-6.3, 143.96], PH: [12.9, 121.8], PK: [30.4, 69.3], PL: [51.9, 19.1],
+  PR: [18.2, -66.6], PS: [31.95, 35.2], PT: [39.4, -8.2], PY: [-23.4, -58.4], QA: [25.4, 51.2],
+  RO: [45.9, 25.0], RS: [44.0, 21.0], RU: [61.5, 105.3], RW: [-1.9, 29.9], SA: [23.9, 45.1],
+  SB: [-9.6, 160.2], SC: [-4.7, 55.5], SD: [12.9, 30.2], SE: [60.1, 18.6], SG: [1.35, 103.8],
+  SI: [46.2, 15.0], SK: [48.7, 19.7], SL: [8.5, -11.8], SM: [43.9, 12.5], SN: [14.5, -14.5],
+  SO: [5.2, 46.2], SR: [3.9, -56.0], SS: [6.9, 31.3], SV: [13.8, -88.9], SY: [34.8, 39.0],
+  SZ: [-26.5, 31.5], TD: [15.5, 18.7], TG: [8.6, 0.8], TH: [15.9, 100.99], TJ: [38.9, 71.3],
+  TL: [-8.9, 125.7], TM: [38.97, 59.6], TN: [33.9, 9.5], TO: [-21.2, -175.2], TR: [38.96, 35.2],
+  TT: [10.7, -61.2], TW: [23.7, 121.0], TZ: [-6.4, 34.9], UA: [48.4, 31.2], UG: [1.4, 32.3],
+  US: [37.1, -95.7], UY: [-32.5, -55.8], UZ: [41.4, 64.6], VC: [13.3, -61.2], VE: [6.4, -66.6],
+  VN: [14.1, 108.3], VU: [-15.4, 166.96], WS: [-13.8, -172.1], YE: [15.6, 48.5], ZA: [-30.6, 22.9],
+  ZM: [-13.1, 27.8], ZW: [-19.0, 29.2],
+};
+
+/** True for a two-letter code this list knows. */
+export function isCountryCode(code: unknown): code is string {
+  return typeof code === "string" && COUNTRY_CODES.includes(code.toUpperCase());
+}
+
+const displayNamesCache = new Map<string, Intl.DisplayNames | null>();
+
+function displayNames(locale: string): Intl.DisplayNames | null {
+  if (!displayNamesCache.has(locale)) {
+    let names: Intl.DisplayNames | null = null;
+    try {
+      names =
+        typeof Intl !== "undefined" && "DisplayNames" in Intl
+          ? new Intl.DisplayNames([locale], { type: "region" })
+          : null;
+    } catch {
+      names = null;
+    }
+    displayNamesCache.set(locale, names);
+  }
+  return displayNamesCache.get(locale) ?? null;
+}
+
+/**
+ * A country's name in `locale` ("DE" is "Germany" in English, "Deutschland"
+ * in German). Falls back to the code where the runtime has no names, and to
+ * null for no code at all.
+ */
+export function countryName(code: string | null | undefined, locale = "en"): string | null {
+  if (!code) return null;
+  const upper = code.toUpperCase();
+  try {
+    return displayNames(locale)?.of(upper) ?? upper;
+  } catch {
+    return upper;
+  }
+}
+
+/** Every country as a select option, sorted by its name in `locale`. */
+export function countryOptions(locale = "en"): { code: string; name: string }[] {
+  const collator = new Intl.Collator(locale);
+  return COUNTRY_CODES.map((code) => ({ code, name: countryName(code, locale) ?? code })).sort((a, b) =>
+    collator.compare(a.name, b.name),
+  );
+}

package/src/ui/headless/community/index.ts

@@ -1,4 +1,4 @@
-// Community headless primitives. NOTE: this is a lane-local aggregator — the
+// Community headless primitives. NOTE: this is a lane-local aggregator. The
 // integrator re-exports it from `ui/headless/index.ts` (`export * from "./community"`).
 export {
   buildLexicalState,
@@ -18,3 +18,83 @@ export { useRichMentionComposer, type RichCommand } from "./useRichMentionCompos
 export { serializeRichToLexical, collectMentions, isRichEmpty } from "./richLexical";
 export { useCommunitySpaceFeed } from "./useCommunitySpaceFeed";
 export { useCommunityThread } from "./useCommunityThread";
+export {
+  useCommunityAgentThinking,
+  useChatAgentThinking,
+  useCommunityAgentAnswerFeedback,
+  useCommunityCatchUp,
+  linkifyText,
+  useCommunityAgentAnswerRatings,
+  chatThinkingKey,
+  AGENT_THINKING_TIMEOUT_MS,
+  CATCH_ME_UP_MIN_REPLIES,
+  type LinkifiedSegment,
+} from "./useCommunityAgent";
+export {
+  COUNTRY_CODES,
+  COUNTRY_CENTROIDS,
+  countryName,
+  countryOptions,
+  isCountryCode,
+} from "./countries";
+export {
+  useCommunityMemberDirectory,
+  memberGlobePoints,
+  memberMapCountries,
+  memberGlobeMarkers,
+  memberLocationLabel,
+  globeAnglesFor,
+  DIRECTORY_SORTS,
+  DIRECTORY_LEVELS,
+  DIRECTORY_SEARCH_DEBOUNCE_MS,
+  type MemberGlobePoint,
+  type MemberGlobeMarker,
+  type CommunityMembersView,
+  type UseCommunityMemberDirectoryOptions,
+} from "./useCommunityMembers";
+export {
+  useCommunityModeration,
+  useCommunityModeratorActions,
+  describeHoldReason,
+  describeModerationNotification,
+  restorableLogEntries,
+  communityMuteUntil,
+  moderationErrorMessage,
+  COMMUNITY_MUTE_DAYS,
+  type CommunityHoldReason,
+  type CommunityMuteDays,
+  type CommunityModerationOutcome,
+  type CommunityLogRestoreTarget,
+  type CommunityReportResolution,
+  type UseCommunityModerationOptions,
+} from "./useCommunityModeration";
+export {
+  useCommunityPoll,
+  useCommunityPollDraft,
+  validatePollDraft,
+  buildPollPayload,
+  emptyPollDraft,
+  parsePollCloseTime,
+  pollOptionPercent,
+  pollHiddenReason,
+  pollVoteErrorCode,
+  sameAnswer,
+  COMMUNITY_POLL_LIMITS,
+  type CommunityPollDraft,
+  type CommunityPollDraftErrors,
+  type CommunityPollQuestionError,
+  type CommunityPollOptionError,
+  type CommunityPollOptionsError,
+  type CommunityPollClosesError,
+  type CommunityPollHiddenReason,
+  type CommunityPollVoteError,
+} from "./communityPoll";
+export {
+  COMMUNITY_EMBED_ORIGINS,
+  safeHttpUrl,
+  safeEmbedUrl,
+  linkPreviewHost,
+  linkPreviewDisplay,
+  autoplayEmbedUrl,
+  type LinkPreviewDisplay,
+} from "./linkPreview";

package/src/ui/headless/community/linkPreview.ts

@@ -0,0 +1,71 @@
+import type { CommunityLinkPreview } from "../../../data/queries/useCommunity";
+
+/**
+ * Link cards on community posts (community parity §6.2). The server puts the
+ * first link of a post on it as a card, shortly after it is published. These
+ * helpers decide what of that card is safe to render: an http(s) link only,
+ * and a video player only from the three privacy-respecting embed origins the
+ * server itself builds. Anything else falls back to a plain link card, and a
+ * preview with no safe link renders nothing at all.
+ */
+
+/** The only origins a post's video may play from. */
+export const COMMUNITY_EMBED_ORIGINS: readonly string[] = [
+  "https://www.youtube-nocookie.com",
+  "https://player.vimeo.com",
+  "https://www.loom.com",
+];
+
+/** The address, when it is an absolute http(s) URL. */
+export function safeHttpUrl(value: unknown): string | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value.trim());
+    return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The video's player address, when the preview is a video from an allowed origin. */
+export function safeEmbedUrl(preview: Pick<CommunityLinkPreview, "kind" | "embedUrl"> | null | undefined): string | null {
+  if (!preview || preview.kind !== "video" || typeof preview.embedUrl !== "string") return null;
+  try {
+    const url = new URL(preview.embedUrl);
+    return url.protocol === "https:" && COMMUNITY_EMBED_ORIGINS.includes(url.origin) ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** "example.com": the host without `www.`, for a card with no site name. */
+export function linkPreviewHost(value: string | null | undefined): string | null {
+  const href = safeHttpUrl(value);
+  if (!href) return null;
+  return new URL(href).hostname.replace(/^www\./, "") || null;
+}
+
+/** How a post's preview renders: a video facade, a link card, or nothing. */
+export type LinkPreviewDisplay =
+  | { kind: "video"; href: string; embedUrl: string; imageUrl: string | null }
+  | { kind: "card"; href: string; imageUrl: string | null }
+  | null;
+
+export function linkPreviewDisplay(preview: CommunityLinkPreview | null | undefined): LinkPreviewDisplay {
+  if (!preview) return null;
+  const href = safeHttpUrl(preview.url);
+  if (!href) return null;
+  const imageUrl = safeHttpUrl(preview.imageUrl);
+  const embedUrl = safeEmbedUrl(preview);
+  return embedUrl ? { kind: "video", href, embedUrl, imageUrl } : { kind: "card", href, imageUrl };
+}
+
+/**
+ * The player address with autoplay on, used once the member has pressed play,
+ * so one click starts the video rather than showing a second play button.
+ */
+export function autoplayEmbedUrl(embedUrl: string): string {
+  const url = new URL(embedUrl);
+  url.searchParams.set("autoplay", "1");
+  return url.toString();
+}

package/src/ui/headless/community/richLexical.ts

@@ -1,7 +1,7 @@
 // DOM → Lexical-state serializer for the rich community composer. The
 // contentEditable div is the source of truth; here we walk its DOM and emit the
 // exact Lexical JSON shapes CommunityRichText renders and the create-post API
-// stores — WITHOUT pulling the Lexical runtime into forge. Mirrors the node
+// stores, WITHOUT pulling the Lexical runtime into forge. Mirrors the node
 // shapes in ./lexical.ts (buildLexicalState) so plain-text and rich content
 // round-trip through the same renderer.
 
@@ -41,6 +41,23 @@ const mentionNode = (accountId: string, name: string): LexicalNodeJson => ({
   style: "",
 });
 
+/**
+ * A mention of the community AI. It carries `agentId` and NO account field: the
+ * backend reads an account from `accountId | id | mentionId`, and the agent has
+ * no account, so it would otherwise be read as a member mention.
+ */
+const agentMentionNode = (agentId: string, name: string): LexicalNodeJson => ({
+  type: "mention",
+  version: 1,
+  agentId,
+  mentionName: name,
+  text: `@${name}`,
+  detail: 0,
+  format: 0,
+  mode: "segmented",
+  style: "",
+});
+
 const linebreakNode = (): LexicalNodeJson => ({ type: "linebreak", version: 1 });
 
 const linkNode = (url: string, children: LexicalNodeJson[]): LexicalNodeJson => ({
@@ -177,6 +194,14 @@ function serializeInline(nodes: NodeListOf<ChildNode> | ChildNode[], inherited:
       return;
     }
 
+    // The community AI's chip: a non-editable span carrying the agent id.
+    const agentId = node.getAttribute("data-agent-id");
+    if (agentId) {
+      const name = (node.getAttribute("data-mention-name") ?? node.textContent ?? "").replace(/^@/, "");
+      push(agentMentionNode(agentId, name));
+      return;
+    }
+
     // Mention chip: a non-editable span carrying the account id.
     const accountId = node.getAttribute("data-account-id");
     if (accountId) {
@@ -309,6 +334,6 @@ export function collectMentions(root: HTMLElement): MentionRef[] {
 
 /** Whether the editor holds any real content (text or a mention chip). */
 export function isRichEmpty(root: HTMLElement): boolean {
-  if (root.querySelector("[data-account-id]")) return false;
+  if (root.querySelector("[data-account-id], [data-agent-id]")) return false;
   return (root.textContent ?? "").trim().length === 0;
 }

package/src/ui/headless/community/useCommunityAgent.ts

@@ -0,0 +1,285 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { Socket } from "socket.io-client";
+import {
+  communityAgentSummaryError,
+  useCommunityAgentFeedback,
+  useCommunityAgentRatings,
+  useCommunityAgentSummary,
+  type CommunityAgentFeedbackEntity,
+  type CommunityAgentFeedbackValue,
+  type CommunityAgentSummary,
+  type CommunityAgentSummaryError,
+} from "../../../data/queries/useCommunityAgent";
+import type { CommunityReply } from "../../../data/queries/useCommunity";
+import type { ChatMessage } from "../../../data/queries/useChat";
+
+/**
+ * How long a "thinking" indicator may stand without its `done`. The answer job
+ * always sends `done`, but a dropped socket would otherwise leave the
+ * indicator up for ever.
+ */
+export const AGENT_THINKING_TIMEOUT_MS = 120_000;
+
+/** The reply count from which a thread offers "Catch me up". */
+export const CATCH_ME_UP_MIN_REPLIES = 10;
+
+// ── Linkified text ───────────────────────────────────────────────────────────
+
+export type LinkifiedSegment = { kind: "text"; text: string } | { kind: "link"; text: string; url: string };
+
+/**
+ * A titled link, `[Title](https://...)`, or a bare http(s) address. The titled
+ * form is how the agent writes its sources; bare addresses are kept for
+ * answers written before it, and for addresses inside the answer itself.
+ */
+const LINK_RE = /\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)|https?:\/\/[^\s<>"')\]]+/g;
+/** Punctuation that ends a sentence rather than the address. */
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+
+/**
+ * Split plain text into text and http(s) link segments. The agent writes its
+ * answers as plain text with a "Sources:" list of titled links; this is what
+ * makes them clickable without trusting any markup. Only http(s) addresses
+ * ever become links. Pure.
+ */
+export function linkifyText(text: string): LinkifiedSegment[] {
+  const out: LinkifiedSegment[] = [];
+  let last = 0;
+  for (const match of text.matchAll(LINK_RE)) {
+    const start = match.index ?? 0;
+    if (start > last) out.push({ kind: "text", text: text.slice(last, start) });
+    if (match[1] !== undefined && match[2] !== undefined) {
+      out.push({ kind: "link", text: match[1], url: match[2] });
+      last = start + match[0].length;
+      continue;
+    }
+    let url = match[0];
+    const trailing = TRAILING_PUNCTUATION.exec(url)?.[0] ?? "";
+    if (trailing) url = url.slice(0, -trailing.length);
+    out.push({ kind: "link", text: url, url });
+    last = start + url.length;
+  }
+  if (last < text.length) out.push({ kind: "text", text: text.slice(last) });
+  return out;
+}
+
+// ── Who asked ────────────────────────────────────────────────────────────────
+
+/**
+ * The viewer's ratings on the AI answers in one visible list, and with them
+ * who is offered thumbs at all: the read returns ONLY the answers this account
+ * asked for, so an answer is ratable exactly when its id came back. Pass the
+ * ids of the agent's answers in the list; nothing is asked for when there
+ * are none, when signed out, or when the AI is off.
+ */
+export function useCommunityAgentAnswerRatings(entityType: CommunityAgentFeedbackEntity, answerIds: string[]) {
+  const { data } = useCommunityAgentRatings(entityType, answerIds);
+  const byId = useMemo(() => new Map((data ?? []).map((row) => [row.entityId, row.feedback])), [data]);
+  return {
+    /** The viewer asked this question, so they may rate the answer. */
+    canRate: (entityId: string) => byId.has(entityId),
+    /** Their saved rating, or null. */
+    ratingOf: (entityId: string): 1 | -1 | null => byId.get(entityId) ?? null,
+  };
+}
+
+// ── Thinking ────────────────────────────────────────────────────────────────
+
+interface SocketEnvelope {
+  event?: string;
+  data?: Record<string, unknown> & {
+    postId?: string;
+    state?: string;
+    reply?: CommunityReply;
+    channelId?: string;
+    parentMessageId?: string | null;
+    message?: ChatMessage;
+  };
+}
+
+/** A set of keys that each clear themselves after `AGENT_THINKING_TIMEOUT_MS`. */
+function useExpiringSet() {
+  const [keys, setKeys] = useState<ReadonlySet<string>>(() => new Set());
+  const timers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+  const remove = useCallback((key: string) => {
+    const timer = timers.current.get(key);
+    if (timer) clearTimeout(timer);
+    timers.current.delete(key);
+    setKeys((prev) => {
+      if (!prev.has(key)) return prev;
+      const next = new Set(prev);
+      next.delete(key);
+      return next;
+    });
+  }, []);
+
+  const add = useCallback(
+    (key: string) => {
+      const timer = timers.current.get(key);
+      if (timer) clearTimeout(timer);
+      timers.current.set(
+        key,
+        setTimeout(() => remove(key), AGENT_THINKING_TIMEOUT_MS),
+      );
+      setKeys((prev) => (prev.has(key) ? prev : new Set(prev).add(key)));
+    },
+    [remove],
+  );
+
+  useEffect(() => {
+    const map = timers.current;
+    return () => {
+      map.forEach((timer) => clearTimeout(timer));
+      map.clear();
+    };
+  }, []);
+
+  return { keys, add, remove };
+}
+
+/**
+ * Which posts the community AI is answering right now, from the space room's
+ * `communityAgentThinking` events (the room is joined by the feed or thread
+ * hook). An entry clears on `done`, when the answer itself arrives as a
+ * `communityNewReply`, or after `AGENT_THINKING_TIMEOUT_MS`.
+ *
+ * `accepts` limits it to the posts the caller shows (one post in a thread).
+ */
+export function useCommunityAgentThinking(socket: Socket | null, accepts?: (postId: string) => boolean) {
+  const { keys, add, remove } = useExpiringSet();
+  const acceptsRef = useRef(accepts);
+  acceptsRef.current = accepts;
+
+  useEffect(() => {
+    if (!socket) return;
+    const onMessage = (envelope: SocketEnvelope) => {
+      const postId = envelope.data?.postId;
+      if (!postId || (acceptsRef.current && !acceptsRef.current(postId))) return;
+      if (envelope.event === "communityAgentThinking") {
+        if (envelope.data?.state === "thinking") add(postId);
+        else remove(postId);
+      }
+      if (envelope.event === "communityNewReply" && envelope.data?.reply?.agentAuthor) remove(postId);
+    };
+    socket.on("message", onMessage);
+    return () => {
+      socket.off("message", onMessage);
+    };
+  }, [socket, add, remove]);
+
+  return {
+    thinkingPostIds: keys,
+    isThinking: (postId: string) => keys.has(postId),
+  };
+}
+
+/** The key one chat thinking indicator lives under: the thread, or the channel itself. */
+export const chatThinkingKey = (channelId: string, parentMessageId: string | null | undefined) =>
+  `${channelId}:${parentMessageId ?? ""}`;
+
+/**
+ * Where the community AI is answering in chat, from `chatAgentThinking` on the
+ * channel rooms the chat joined. A channel answer goes in the tagging
+ * message's thread (`parentMessageId` set); a DM answer goes in the DM itself
+ * (`parentMessageId` null). Clears on `done`, on the agent's message arriving,
+ * or after `AGENT_THINKING_TIMEOUT_MS`.
+ */
+export function useChatAgentThinking(socket: Socket | null) {
+  const { keys, add, remove } = useExpiringSet();
+
+  useEffect(() => {
+    if (!socket) return;
+    const onMessage = (envelope: SocketEnvelope) => {
+      const channelId = envelope.data?.channelId;
+      if (!channelId) return;
+      if (envelope.event === "chatAgentThinking") {
+        const key = chatThinkingKey(channelId, envelope.data?.parentMessageId ?? null);
+        if (envelope.data?.state === "thinking") add(key);
+        else remove(key);
+      }
+      const message = envelope.data?.message;
+      if (envelope.event === "chatNewMessage" && message?.senderAgentId) {
+        remove(chatThinkingKey(channelId, message.parentMessageId ?? null));
+      }
+    };
+    socket.on("message", onMessage);
+    return () => {
+      socket.off("message", onMessage);
+    };
+  }, [socket, add, remove]);
+
+  return {
+    isThinking: (channelId: string | null | undefined, parentMessageId: string | null | undefined) =>
+      !!channelId && keys.has(chatThinkingKey(channelId, parentMessageId ?? null)),
+  };
+}
+
+// ── Feedback ─────────────────────────────────────────────────────────────────
+
+/**
+ * Thumbs up / down on one AI answer, optimistic. `saved` is the rating the
+ * ratings read hydrated, so the thumbs survive a reload; a press shows at once,
+ * and a success lands in the ratings cache. Choosing the active thumb again
+ * clears it. A failed rating rolls back; a 404 (not the member who asked, a
+ * safety net now the ratings read decides who sees the control) hides it.
+ */
+export function useCommunityAgentAnswerFeedback(
+  entityType: CommunityAgentFeedbackEntity,
+  entityId: string,
+  saved: 1 | -1 | null = null,
+) {
+  const mutation = useCommunityAgentFeedback();
+  // `undefined` = follow the saved rating; set while a press is in flight or failed back.
+  const [local, setLocal] = useState<1 | -1 | null | undefined>(undefined);
+  const [hidden, setHidden] = useState(false);
+  const value = local !== undefined ? local : saved;
+
+  const rate = useCallback(
+    (thumb: 1 | -1) => {
+      const previous = value;
+      const next: CommunityAgentFeedbackValue = previous === thumb ? 0 : thumb;
+      setLocal(next === 0 ? null : next);
+      mutation.mutate(
+        { entityType, entityId, value: next },
+        {
+          onError: (error) => {
+            setLocal(previous);
+            if ((error as { response?: { status?: number } })?.response?.status === 404) setHidden(true);
+          },
+        },
+      );
+    },
+    [value, mutation, entityType, entityId],
+  );
+
+  return { value, hidden, rate, isPending: mutation.isPending };
+}
+
+// ── Catch me up ──────────────────────────────────────────────────────────────
+
+/**
+ * "Catch me up" on a long thread: ask, then show the private summary until the
+ * member dismisses it. `error` is `daily_limit` (409), `unavailable` (400: too
+ * short, or the AI cannot answer now) or `failed`.
+ */
+export function useCommunityCatchUp(postId?: string) {
+  const mutation = useCommunityAgentSummary(postId);
+  const [summary, setSummary] = useState<CommunityAgentSummary | null>(null);
+  const [error, setError] = useState<CommunityAgentSummaryError | null>(null);
+
+  const ask = useCallback(() => {
+    setError(null);
+    mutation.mutate(undefined, {
+      onSuccess: (data) => setSummary(data),
+      onError: (e) => setError(communityAgentSummaryError(e)),
+    });
+  }, [mutation]);
+
+  const dismiss = useCallback(() => {
+    setSummary(null);
+    setError(null);
+  }, []);
+
+  return { summary, error, ask, dismiss, isPending: mutation.isPending };
+}