@tribe-nest/forge 3.60.0 → 3.63.0

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

@@ -0,0 +1,175 @@
+import { useEffect, useMemo, useState } from "react";
+import {
+  useCommunityDirectory,
+  useCommunityMemberMap,
+  type CommunityDirectoryMember,
+  type CommunityDirectoryRole,
+  type CommunityDirectorySort,
+  type CommunityMemberMapCountry,
+} from "../../../data/queries/useCommunityMembers";
+import { COUNTRY_CENTROIDS, countryName } from "./countries";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+export const DIRECTORY_SORTS: readonly CommunityDirectorySort[] = ["active", "points", "newest", "name"];
+export const DIRECTORY_LEVELS: readonly number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+/** One dot on the member globe: a country, where it is, and how many members. */
+export interface MemberGlobePoint {
+  countryCode: string;
+  latitude: number;
+  longitude: number;
+  members: number;
+}
+
+/** A dot as the globe library draws it. */
+export interface MemberGlobeMarker {
+  location: [number, number];
+  size: number;
+}
+
+/**
+ * The member map's countries, cleaned: codes upper-cased, repeats merged,
+ * empty and malformed rows dropped, biggest first. Every country is here,
+ * including one the globe has no centre for, so the list under the globe
+ * leaves nobody out.
+ */
+export function memberMapCountries(rows: CommunityMemberMapCountry[] | undefined): CommunityMemberMapCountry[] {
+  const merged = new Map<string, number>();
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const code = typeof row.countryCode === "string" ? row.countryCode.trim().toUpperCase() : "";
+    const members = Number(row.members) || 0;
+    if (!/^[A-Z]{2}$/.test(code) || members <= 0) continue;
+    merged.set(code, (merged.get(code) ?? 0) + members);
+  }
+  return [...merged.entries()]
+    .map(([countryCode, members]) => ({ countryCode, members }))
+    .sort((a, b) => b.members - a.members || a.countryCode.localeCompare(b.countryCode));
+}
+
+/**
+ * The member map's countries as globe dots, placed at each country's centre.
+ * A country with no known centre has no dot (it still lists, through
+ * `memberMapCountries`). Biggest first.
+ */
+export function memberGlobePoints(rows: CommunityMemberMapCountry[] | undefined): MemberGlobePoint[] {
+  const points: MemberGlobePoint[] = [];
+  for (const { countryCode, members } of memberMapCountries(rows)) {
+    const centre = COUNTRY_CENTROIDS[countryCode];
+    if (centre) points.push({ countryCode, latitude: centre[0], longitude: centre[1], members });
+  }
+  return points;
+}
+
+/**
+ * Dot sizes by the square root of each country's share of the biggest, so one
+ * large country does not hide the rest: 0.03 for the smallest to 0.12 for the
+ * biggest.
+ */
+export function memberGlobeMarkers(points: MemberGlobePoint[]): MemberGlobeMarker[] {
+  const max = Math.max(1, ...points.map((p) => p.members));
+  return points.map((p) => ({ location: [p.latitude, p.longitude], size: 0.03 + 0.09 * Math.sqrt(p.members / max) }));
+}
+
+/** cobe's rotation that brings a place to the front. */
+export function globeAnglesFor(latitude: number, longitude: number): [number, number] {
+  return [Math.PI - ((longitude * Math.PI) / 180 - Math.PI / 2), (latitude * Math.PI) / 180];
+}
+
+/** "Berlin, Germany", "Germany", "Berlin", or null: where a member says they are. */
+export function memberLocationLabel(
+  member: Pick<CommunityDirectoryMember, "city" | "countryCode">,
+  locale = "en",
+): string | null {
+  const city = member.city?.trim() || null;
+  const country = countryName(member.countryCode, locale);
+  if (city && country) return `${city}, ${country}`;
+  return city ?? country;
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+/** How long the search box settles before the directory is asked. */
+export const DIRECTORY_SEARCH_DEBOUNCE_MS = 300;
+
+export type CommunityMembersView = "list" | "map";
+
+export interface UseCommunityMemberDirectoryOptions {
+  /** Cards per page. Default 24. */
+  pageSize?: number;
+  initialView?: CommunityMembersView;
+}
+
+/**
+ * Headless member directory for the surrounding community: the search (sent
+ * once typing settles), role and level filters, sort, paging, and the list or
+ * map view. Changing any filter goes back to page 1. The map's data loads only
+ * once the map is shown.
+ */
+export function useCommunityMemberDirectory(opts: UseCommunityMemberDirectoryOptions = {}) {
+  const [search, setSearch] = useState("");
+  const [q, setQ] = useState("");
+  const [role, setRoleState] = useState<CommunityDirectoryRole | null>(null);
+  const [minLevel, setMinLevelState] = useState<number | null>(null);
+  const [sort, setSortState] = useState<CommunityDirectorySort>("active");
+  const [page, setPage] = useState(1);
+  const [view, setView] = useState<CommunityMembersView>(opts.initialView ?? "list");
+
+  useEffect(() => {
+    const id = setTimeout(() => {
+      setQ(search.trim());
+      setPage(1);
+    }, DIRECTORY_SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(id);
+  }, [search]);
+
+  const directory = useCommunityDirectory({ q, role, minLevel, sort, page, limit: opts.pageSize });
+  const map = useCommunityMemberMap({ enabled: view === "map" });
+  const countries = useMemo(() => memberMapCountries(map.data), [map.data]);
+  const points = useMemo(() => memberGlobePoints(map.data), [map.data]);
+
+  const resetting =
+    <T>(set: (value: T) => void) =>
+    (value: T) => {
+      set(value);
+      setPage(1);
+    };
+
+  return {
+    // Filters
+    search,
+    setSearch,
+    role,
+    setRole: resetting(setRoleState),
+    minLevel,
+    setMinLevel: resetting(setMinLevelState),
+    sort,
+    setSort: resetting(setSortState),
+    /** Any filter other than the default order is on. */
+    filtered: !!q || !!role || !!minLevel,
+    // Results
+    members: directory.data?.data ?? [],
+    total: directory.data?.total ?? 0,
+    page,
+    hasNextPage: !!directory.data?.hasNextPage,
+    hasPreviousPage: page > 1,
+    nextPage: () => setPage((p) => p + 1),
+    previousPage: () => setPage((p) => Math.max(1, p - 1)),
+    isLoading: directory.isLoading,
+    /** True while a new page or filter is loading behind the current results. */
+    isRefreshing: directory.isFetching && !directory.isLoading,
+    isError: directory.isError,
+    /** 403: the viewer is not a member of this community. */
+    forbidden: (directory.error as { response?: { status?: number } } | null)?.response?.status === 403,
+    // Map
+    view,
+    setView,
+    /** Globe dots: countries with a known centre. */
+    mapPoints: points,
+    /** Every country with members on the map, for the list. */
+    mapCountries: countries,
+    mapMembers: countries.reduce((n, c) => n + c.members, 0),
+    mapLoading: view === "map" && map.isLoading,
+    mapError: map.isError,
+  };
+}

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

@@ -0,0 +1,300 @@
+import { useContext, useMemo, useState } from "react";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import {
+  useCommunityCanModerate,
+  useMyCommunityProfile,
+  type CommunityNotificationItem,
+  type CommunityPost,
+  type CommunityReply,
+} from "../../../data/queries/useCommunity";
+import {
+  useCommunityModerationLog,
+  useCommunityModerationQueue,
+  useModerateCommunityPost,
+  useModerateCommunityReply,
+  useMuteCommunityMember,
+  useResolveCommunityReport,
+  type CommunityModerationLogEntry,
+  type CommunityPendingPost,
+  type CommunityPendingReply,
+  type CommunityPostModerationAction,
+} from "../../../data/queries/useCommunityModeration";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+/** Why something was held, in a shape a renderer can put into words. */
+export type CommunityHoldReason =
+  | { kind: "new_member" }
+  | { kind: "all_posts" }
+  | { kind: "keyword"; word: string }
+  | { kind: "other"; raw: string }
+  | null;
+
+/**
+ * Read a held post's `moderationReason`: `approval_new_member`,
+ * `approval_all` or `keyword:<word>`. Anything else is passed through as
+ * `other`, so a reason a newer server adds still shows rather than vanishing.
+ */
+export function describeHoldReason(reason: string | null | undefined): CommunityHoldReason {
+  if (!reason) return null;
+  if (reason === "approval_new_member") return { kind: "new_member" };
+  if (reason === "approval_all") return { kind: "all_posts" };
+  if (reason.startsWith("keyword:")) return { kind: "keyword", word: reason.slice("keyword:".length) };
+  return { kind: "other", raw: reason };
+}
+
+/** The mute lengths a moderator can pick on the site, in days. */
+export const COMMUNITY_MUTE_DAYS = [1, 7, 30] as const;
+export type CommunityMuteDays = (typeof COMMUNITY_MUTE_DAYS)[number];
+
+/** The ISO time a mute of `days` started at `now` ends. */
+export function communityMuteUntil(days: number, now: Date = new Date()): string {
+  return new Date(now.getTime() + days * 24 * 60 * 60 * 1000).toISOString();
+}
+
+/** The server's message on a failed call, when it sent one. */
+export function moderationErrorMessage(err: unknown): string | null {
+  const message = (err as { response?: { data?: { message?: unknown } } })?.response?.data?.message;
+  return typeof message === "string" && message.trim() ? message : null;
+}
+
+/** A moderation outcome notice about the member's own post or reply. */
+export interface CommunityModerationOutcome {
+  outcome: "approved" | "rejected";
+  subject: "post" | "reply";
+  reason: string | null;
+}
+
+/**
+ * The moderation outcome a `mod` notification carries, or null for any other
+ * notification. A `mod` notice about the community itself (a mute) carries no
+ * outcome and stays null, so it keeps rendering as it always has.
+ */
+export function describeModerationNotification(
+  n: { type: string; entityType: string | null; data?: unknown } | null | undefined,
+): CommunityModerationOutcome | null {
+  if (!n || n.type !== "mod") return null;
+  const subject = n.entityType === "community_post" ? "post" : n.entityType === "community_reply" ? "reply" : null;
+  const data = (n.data && typeof n.data === "object" ? n.data : {}) as NonNullable<CommunityNotificationItem["data"]>;
+  const outcome = data.outcome;
+  if (!subject || (outcome !== "approved" && outcome !== "rejected")) return null;
+  const reason = typeof data.reason === "string" && data.reason.trim() ? data.reason.trim() : null;
+  return { outcome, subject, reason };
+}
+
+/** What a log entry can be undone to, when it can. */
+export interface CommunityLogRestoreTarget {
+  type: "post" | "reply";
+  id: string;
+}
+
+/**
+ * Which log entries still offer "Restore": a removal (or a report resolved by
+ * hiding the content) of a post or reply that no NEWER entry on the page has
+ * already restored. The log is newest first. An entry whose restore is on an
+ * older page may still show the button; restoring twice is harmless.
+ */
+export function restorableLogEntries(entries: CommunityModerationLogEntry[]): Map<string, CommunityLogRestoreTarget> {
+  const out = new Map<string, CommunityLogRestoreTarget>();
+  const restoredAfter = new Set<string>();
+  for (const entry of entries) {
+    if (!entry.entityId) continue;
+    const type =
+      entry.entityType === "community_post" ? "post" : entry.entityType === "community_reply" ? "reply" : null;
+    if (!type) continue;
+    const key = `${type}:${entry.entityId}`;
+    if (entry.action === "restore") {
+      restoredAfter.add(key);
+      continue;
+    }
+    if ((entry.action === "remove" || entry.action === "report_resolved_hidden") && !restoredAfter.has(key)) {
+      out.set(entry.id, { type, id: entry.entityId });
+      // An older removal of the same thing is already covered by this one.
+      restoredAfter.add(key);
+    }
+  }
+  return out;
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+/**
+ * Whether the viewer is signed in. Read without `usePublicAuth()` so the
+ * moderation tools render (as nothing) outside an auth provider rather than
+ * throwing: a post card is useful in places no one is signed in.
+ */
+function useViewerId(): string | null {
+  return useContext(PublicAuthContext)?.user?.id ?? null;
+}
+
+function useIsSignedIn() {
+  return !!useViewerId();
+}
+
+type Outcome = Promise<boolean>;
+
+/**
+ * Headless moderator actions for the inline menu on a post or reply: pin,
+ * lock, remove (with an optional reason) and restore, plus muting the author
+ * for a while. `canModerate` is false for everyone but a moderator of THIS
+ * community (or an owner/admin), and every action resolves `false` with
+ * `error` set when the server refuses. Bans are not here: only an admin bans.
+ */
+export function useCommunityModeratorActions() {
+  const viewerId = useViewerId();
+  const canModerate = useCommunityCanModerate(!!viewerId);
+  const postMutation = useModerateCommunityPost();
+  const replyMutation = useModerateCommunityReply();
+  const muteMutation = useMuteCommunityMember();
+  const [error, setError] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+
+  const run = async (call: () => Promise<unknown>): Outcome => {
+    setError(null);
+    setFailed(false);
+    try {
+      await call();
+      return true;
+    } catch (err) {
+      setError(moderationErrorMessage(err));
+      setFailed(true);
+      return false;
+    }
+  };
+
+  const post = (action: CommunityPostModerationAction) => (target: Pick<CommunityPost, "id">, reason?: string) =>
+    run(() => postMutation.mutateAsync({ postId: target.id, action, reason }));
+
+  return {
+    canModerate,
+    /** The signed-in member, so a renderer can leave "mute" off their own content. */
+    currentAccountId: viewerId,
+    isPending: postMutation.isPending || replyMutation.isPending || muteMutation.isPending,
+    /** The server's message for the last failed action, when it sent one. */
+    error,
+    /** The last action failed (with or without a message from the server). */
+    failed,
+    clearError: () => {
+      setError(null);
+      setFailed(false);
+    },
+    pinPost: post("pin"),
+    unpinPost: post("unpin"),
+    lockPost: post("lock"),
+    unlockPost: post("unlock"),
+    removePost: post("remove"),
+    restorePost: post("restore"),
+    removeReply: (reply: Pick<CommunityReply, "id" | "postId">, reason?: string) =>
+      run(() => replyMutation.mutateAsync({ replyId: reply.id, postId: reply.postId, action: "remove", reason })),
+    restoreReply: (reply: Pick<CommunityReply, "id" | "postId">) =>
+      run(() => replyMutation.mutateAsync({ replyId: reply.id, postId: reply.postId, action: "restore" })),
+    /** Mute a member in this community for `days` from now. */
+    muteMember: (accountId: string, days: CommunityMuteDays) =>
+      run(() => muteMutation.mutateAsync({ accountId, mutedUntil: communityMuteUntil(days) })),
+    unmuteMember: (accountId: string) => run(() => muteMutation.mutateAsync({ accountId, mutedUntil: null })),
+  };
+}
+
+export type CommunityReportResolution = "resolve" | "resolve_and_hide" | "dismiss";
+
+export interface UseCommunityModerationOptions {
+  /** Log page size. Default 20. */
+  logPageSize?: number;
+}
+
+/**
+ * Headless Moderation tab: the open reports, the posts and replies held for
+ * approval, and the moderation log (paged), with every action on them. Loads
+ * nothing until the viewer is known to moderate this community. `busyId` is the
+ * row an action is running on, so a renderer can disable just that row.
+ */
+export function useCommunityModeration(opts: UseCommunityModerationOptions = {}) {
+  const signedIn = useIsSignedIn();
+  const me = useMyCommunityProfile(signedIn);
+  const canModerate = signedIn && !!me.data?.canModerate;
+  const [logPage, setLogPage] = useState(1);
+  const queue = useCommunityModerationQueue(canModerate);
+  const log = useCommunityModerationLog(logPage, opts.logPageSize ?? 20, canModerate);
+
+  const resolve = useResolveCommunityReport();
+  const postMutation = useModerateCommunityPost();
+  const replyMutation = useModerateCommunityReply();
+
+  const [busyId, setBusyId] = useState<string | null>(null);
+  const [error, setError] = useState<{ id: string; message: string | null } | null>(null);
+
+  const run = async (id: string, call: () => Promise<unknown>): Outcome => {
+    setBusyId(id);
+    setError(null);
+    try {
+      await call();
+      return true;
+    } catch (err) {
+      setError({ id, message: moderationErrorMessage(err) });
+      return false;
+    } finally {
+      setBusyId(null);
+    }
+  };
+
+  const logEntries = useMemo(() => log.data?.data ?? [], [log.data]);
+  const restorable = useMemo(() => restorableLogEntries(logEntries), [logEntries]);
+
+  return {
+    canModerate,
+    /** Still finding out whether the viewer moderates this community. */
+    isChecking: signedIn && me.isLoading,
+    /** The queue's first load. */
+    isLoading: canModerate && queue.isLoading,
+    reports: queue.data?.reports.data ?? [],
+    reportsTotal: queue.data?.reports.total ?? 0,
+    pendingPosts: queue.data?.pending.posts ?? [],
+    pendingReplies: queue.data?.pending.replies ?? [],
+    queueError: queue.isError,
+    busyId,
+    /** The last failed action: which row, and the server's message when it sent one. */
+    error,
+    clearError: () => setError(null),
+
+    resolveReport: (reportId: string, resolution: CommunityReportResolution) =>
+      run(reportId, () =>
+        resolve.mutateAsync({
+          reportId,
+          action: resolution === "dismiss" ? "dismissed" : "resolved",
+          hideContent: resolution === "resolve_and_hide",
+        }),
+      ),
+    approvePost: (item: Pick<CommunityPendingPost, "id">) =>
+      run(item.id, () => postMutation.mutateAsync({ postId: item.id, action: "approve" })),
+    rejectPost: (item: Pick<CommunityPendingPost, "id">, reason?: string) =>
+      run(item.id, () => postMutation.mutateAsync({ postId: item.id, action: "reject", reason })),
+    approveReply: (item: Pick<CommunityPendingReply, "id" | "postId">) =>
+      run(item.id, () => replyMutation.mutateAsync({ replyId: item.id, postId: item.postId, action: "approve" })),
+    rejectReply: (item: Pick<CommunityPendingReply, "id" | "postId">, reason?: string) =>
+      run(item.id, () =>
+        replyMutation.mutateAsync({ replyId: item.id, postId: item.postId, action: "reject", reason }),
+      ),
+
+    log: {
+      entries: logEntries,
+      page: logPage,
+      total: log.data?.total ?? 0,
+      hasNextPage: !!log.data?.hasNextPage,
+      hasPreviousPage: logPage > 1,
+      isLoading: canModerate && log.isLoading,
+      nextPage: () => setLogPage((p) => p + 1),
+      previousPage: () => setLogPage((p) => Math.max(1, p - 1)),
+      /** Entries that can still be undone, by entry id. */
+      restorable,
+      restore: (entry: CommunityModerationLogEntry) => {
+        const target = restorable.get(entry.id);
+        if (!target) return Promise.resolve(false);
+        return run(entry.id, () =>
+          target.type === "post"
+            ? postMutation.mutateAsync({ postId: target.id, action: "restore" })
+            : replyMutation.mutateAsync({ replyId: target.id, action: "restore" }),
+        );
+      },
+    },
+  };
+}

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

@@ -2,6 +2,7 @@ import { useEffect, useMemo } from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import {
+  applyCommunityContentHeld,
   applyReactionDelta,
   bumpFeedReplyCount,
   prependPostToFeed,
@@ -12,10 +13,12 @@ import {
   useJoinCommunitySpace,
   useLeaveCommunitySpace,
   useToggleCommunityReaction,
+  type CommunityContentHeldEvent,
   type CommunityPost,
   type CommunityReactionEvent,
   type CommunityReply,
 } from "../../../data/queries/useCommunity";
+import { useCommunityAgentThinking } from "./useCommunityAgent";
 
 /**
  * Headless space feed: the space (from the gated spaces list), its paginated
@@ -25,7 +28,7 @@ import {
  *
  * The single primitive a creator needs to rebuild a space feed page.
  *
- * `idOrSlug` accepts either a space uuid or its per-profile slug — the space is
+ * `idOrSlug` accepts either a space uuid or its per-profile slug: the space is
  * resolved from the gated spaces list by id OR slug, so slug-addressed deep
  * links load the right space without a separate lookup.
  */
@@ -39,9 +42,12 @@ export function useCommunitySpaceFeed(idOrSlug?: string) {
     [spaces, idOrSlug],
   );
   // Downstream hooks (posts, realtime room, create) are keyed by the canonical
-  // space uuid — only wire them up once the space resolves from the list, so a
+  // space uuid, so only wire them up once the space resolves from the list, so a
   // slug-addressed link never leaks a slug into a uuid-keyed request/room.
-  const spaceId = space?.id;
+  // A space above the member's level is listed but closed: nothing is asked
+  // for it (the server would refuse), and no realtime room is joined.
+  const levelLocked = !!space?.levelLocked;
+  const spaceId = levelLocked ? undefined : space?.id;
 
   const {
     data: postPages,
@@ -80,6 +86,10 @@ export function useCommunitySpaceFeed(idOrSlug?: string) {
       if (data.event === "communityReaction" && data.data?.entityId && data.data?.accountId !== user?.id) {
         applyReactionDelta(queryClient, data.data as CommunityReactionEvent);
       }
+      // Auto-moderation sent it back to the approval queue: out of the open feed.
+      if (data.event === "communityContentHeld" && data.data?.spaceId === spaceId) {
+        applyCommunityContentHeld(queryClient, data.data as unknown as CommunityContentHeldEvent, user?.id);
+      }
     };
     socket.on("message", onMessage);
     return () => {
@@ -87,6 +97,9 @@ export function useCommunitySpaceFeed(idOrSlug?: string) {
     };
   }, [socket, spaceId, queryClient, user?.id]);
 
+  // The community AI answering a post in this space (cleared by the answer).
+  const agentThinking = useCommunityAgentThinking(socket);
+
   // Join/leave the space room (mirrors chatJoinChannel).
   useEffect(() => {
     if (!spaceId || !socket) return;
@@ -108,7 +121,12 @@ export function useCommunitySpaceFeed(idOrSlug?: string) {
     fetchNextPage,
     hasMore: !!hasNextPage && !isFetchingNextPage,
     currentAccountId: user?.id,
-    // Belonging — tiers govern access, join governs new-post notifications.
+    /** Whether the community AI is writing an answer under this post right now. */
+    isAgentThinking: agentThinking.isThinking,
+    /** The space is above the member's level: show it locked, not its feed. */
+    levelLocked,
+    minLevel: space?.minLevel ?? 1,
+    // Belonging: tiers govern access, join governs new-post notifications.
     isJoined: space?.isJoined ?? false,
     memberCount: space?.memberCount ?? null,
     joinPending: joinSpace.isPending || leaveSpace.isPending,

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

@@ -2,6 +2,7 @@ import { useEffect, useMemo } from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import {
+  applyCommunityContentHeld,
   appendReplyToThread,
   applyReactionDelta,
   useCommunityPost,
@@ -9,15 +10,17 @@ import {
   useCommunitySocket,
   useCreateCommunityReply,
   useToggleCommunityReaction,
+  type CommunityContentHeldEvent,
   type CommunityReactionEvent,
   type CommunityReply,
   type ReactableEntityType,
 } from "../../../data/queries/useCommunity";
 import { buildReplyTree } from "./replyTree";
+import { useCommunityAgentThinking } from "./useCommunityAgent";
 
 /**
  * Headless post thread: the post, its full reply tree (assembled from the flat
- * pages — data nesting is unlimited, display capping is the renderer's job),
+ * pages: data nesting is unlimited, display capping is the renderer's job),
  * realtime reply/reaction updates via the post's space room, plus reply and
  * toggle-reaction actions.
  */
@@ -52,13 +55,18 @@ export function useCommunityThread(postId?: string) {
       data?: { spaceId?: string; postId?: string; reply?: CommunityReply } & Partial<CommunityReactionEvent>;
     }) => {
       if (data.event === "communityNewReply" && data.data?.postId === postId && data.data?.reply) {
-        // Skip own replies — the mutation already appended them.
-        if (data.data.reply.authorAccountId === user?.id) return;
+        // Skip own replies: the mutation already appended them. An answer from
+        // the community AI has no account, so it is never skipped.
+        if (user?.id && data.data.reply.authorAccountId === user.id) return;
         appendReplyToThread(queryClient, postId, data.data.reply);
       }
       if (data.event === "communityReaction" && data.data?.entityId && data.data?.accountId !== user?.id) {
         applyReactionDelta(queryClient, data.data as CommunityReactionEvent, { postId });
       }
+      // Auto-moderation held this post, or a reply in it: out of the open thread.
+      if (data.event === "communityContentHeld" && data.data?.postId === postId) {
+        applyCommunityContentHeld(queryClient, data.data as unknown as CommunityContentHeldEvent, user?.id);
+      }
     };
     socket.on("message", onMessage);
     return () => {
@@ -66,6 +74,9 @@ export function useCommunityThread(postId?: string) {
     };
   }, [socket, postId, queryClient, user?.id]);
 
+  // The community AI writing an answer in this thread (cleared by the answer).
+  const agentThinking = useCommunityAgentThinking(socket, (id) => id === postId);
+
   useEffect(() => {
     if (!spaceId || !socket) return;
     const join = () => socket.emit("communityJoinSpace", { spaceId });
@@ -87,6 +98,8 @@ export function useCommunityThread(postId?: string) {
     fetchNextPage,
     hasMore: !!hasNextPage && !isFetchingNextPage,
     currentAccountId: user?.id,
+    /** Whether the community AI is writing an answer in this thread right now. */
+    agentThinking: !!postId && agentThinking.isThinking(postId),
     // Actions
     createReply,
     react: (entityType: Extract<ReactableEntityType, "community_post" | "community_reply">, entityId: string, emoji: string) =>

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

@@ -7,10 +7,16 @@ import {
 import { buildLexicalState, mentionsInText, type MentionRef } from "./lexical";
 
 export interface MentionSuggestion {
+  /** The member's account. Empty for the community AI, which has none. */
   accountId: string;
   name: string;
   avatarUrl: string | null;
   level: number;
+  /**
+   * Set when this suggestion is the community AI rather than a member. It is
+   * listed first and inserts an agent mention (`agentId`, never `accountId`).
+   */
+  agentId?: string | null;
 }
 
 /**
@@ -24,7 +30,17 @@ export function useMentionComposer(initialText = "") {
   const [text, setText] = useState(initialText);
   const [caret, setCaret] = useState(initialText.length);
   const [trackedMentions, setTrackedMentions] = useState<MentionRef[]>([]);
-  const { data: directory = [] } = useCommunityMentionDirectory();
+
+  /** The active "@query" token immediately before the caret, if any. */
+  const activeToken = useMemo(() => {
+    const upToCaret = text.slice(0, caret);
+    const match = /(^|\s)@([^\s@]{0,40})$/.exec(upToCaret);
+    if (!match) return null;
+    return { query: match[2], start: caret - match[2].length - 1 };
+  }, [text, caret]);
+
+  // Searched on the server as the member types; nothing is asked for without an @token.
+  const { data: directory = [] } = useCommunityMentionDirectory(activeToken?.query);
 
   const members: MentionSuggestion[] = useMemo(
     () =>
@@ -37,14 +53,6 @@ export function useMentionComposer(initialText = "") {
     [directory],
   );
 
-  /** The active "@query" token immediately before the caret, if any. */
-  const activeToken = useMemo(() => {
-    const upToCaret = text.slice(0, caret);
-    const match = /(^|\s)@([^\s@]{0,40})$/.exec(upToCaret);
-    if (!match) return null;
-    return { query: match[2], start: caret - match[2].length - 1 };
-  }, [text, caret]);
-
   const suggestions: MentionSuggestion[] = useMemo(() => {
     if (!activeToken) return [];
     const q = activeToken.query.toLowerCase();