@tribe-nest/forge 3.59.0 → 3.61.0

package/src/data/queries/useCommunity.ts

@@ -1,6 +1,15 @@
-import { useInfiniteQuery, useMutation, useQuery, useQueryClient, type QueryClient } from "@tanstack/react-query";
-import { useForge } from "../../provider/ForgeProvider";
+import { useEffect, useState } from "react";
+import {
+  keepPreviousData,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type QueryClient,
+} from "@tanstack/react-query";
+import { useCommunityScope } from "../../contexts/CommunityContext";
 import { useChatSocket } from "./useChat";
+import type { CommunityAgentAuthor } from "./useCommunityAgent";
 
 // ── Types (mirror apps/backend/src/routes/public/community + models) ─────────
 
@@ -17,7 +26,7 @@ export interface CommunitySpace {
   order: number;
   archivedAt: string | null;
   createdAt: string;
-  /** Gating tiers — empty array = open to every member. */
+  /** Gating tiers: empty array = open to every member. */
   tiers: { id: string; name: string }[];
   /** Only present on the member list query. */
   postCount?: number | null;
@@ -25,6 +34,14 @@ export interface CommunitySpace {
   memberCount?: number | null;
   /** Whether the current member has joined this space (new-post notifications). */
   isJoined?: boolean;
+  /** The level a member needs to read this space (1 = no level needed). */
+  minLevel?: number;
+  /**
+   * On the member list: the space is above the member's level. It is listed so
+   * they can see what their next level opens, but its feed stays closed (the
+   * server refuses it too).
+   */
+  levelLocked?: boolean;
 }
 
 /** One roster row (GET /public/community/spaces/:id/members). */
@@ -80,7 +97,8 @@ export interface CommunityPost {
   id: string;
   profileId: string;
   spaceId: string;
-  authorAccountId: string;
+  /** Null when the community AI wrote it (`agentAuthor` is then set). */
+  authorAccountId: string | null;
   title: string | null;
   /** Lexical editor state (JSON). Render with <CommunityRichText/>. */
   body: unknown;
@@ -92,22 +110,119 @@ export interface CommunityPost {
   lastActivityAt: string | null;
   createdAt: string;
   author: CommunityAuthor | null;
+  /** The community AI, when it wrote this post. `author` is then null. Absent on older servers. */
+  agentAuthor?: CommunityAgentAuthor | null;
   media: CommunityMediaItem[];
   reactions?: ReactionSummary[];
+  /**
+   * Moderation state. Only an author sees their own pending post; everyone else
+   * sees published posts only. Absent on rows from older servers: treat as published.
+   */
+  status?: CommunityContentStatus;
+  /** Why a post was held (`approval_new_member`, `approval_all`, `keyword:<word>`), or why it was rejected. */
+  moderationReason?: string | null;
+  /** Set in the cache when a moderator removes the post in this session, so the undo stays in place. */
+  archivedAt?: string | null;
+  /**
+   * The post's poll, as this viewer sees it, or null when it has none. Absent
+   * on a post that arrived over the realtime socket (see `CommunityPollView`).
+   */
+  poll?: CommunityPollView | null;
+  /**
+   * A card for the first link in the post, or null. Filled in the background
+   * shortly after the post is published, so a new post has none at first.
+   * Absent on rows from older servers.
+   */
+  linkPreview?: CommunityLinkPreview | null;
+}
+
+/** A link card on a post (community parity §6.2). */
+export interface CommunityLinkPreview {
+  url: string;
+  kind: "link" | "video";
+  provider: "youtube" | "vimeo" | "loom" | null;
+  siteName: string | null;
+  title: string | null;
+  description: string | null;
+  imageUrl: string | null;
+  /** The player address, for a video. Render only through `safeEmbedUrl`. */
+  embedUrl: string | null;
+}
+
+// ── Polls (community parity §6.1) ────────────────────────────────────────────
+
+/** When a poll's counts are shown: at once, once the member voted, or once it closed. */
+export type CommunityPollResultsVisibility = "always" | "after_vote" | "after_close";
+
+export const COMMUNITY_POLL_RESULTS_VISIBILITY: readonly CommunityPollResultsVisibility[] = [
+  "always",
+  "after_vote",
+  "after_close",
+];
+
+export interface CommunityPollOption {
+  id: string;
+  label: string;
+  position: number;
+  /** Null while this viewer may not see results yet. */
+  votes: number | null;
+}
+
+/** A post's poll as the viewer sees it. The post title is its question. */
+export interface CommunityPollView {
+  id: string;
+  multipleChoice: boolean;
+  closesAt: string | null;
+  closed: boolean;
+  resultsVisibility: CommunityPollResultsVisibility;
+  /** Whether this viewer may see the counts now. */
+  resultsVisible: boolean;
+  /** Distinct members who voted. Null while results are hidden. */
+  totalVoters: number | null;
+  /** The option ids this viewer chose. Empty when they have not voted. */
+  myVotes: string[];
+  options: CommunityPollOption[];
+}
+
+/** The poll part of the create-post body. The question travels as the post `title`. */
+export interface CommunityPollInput {
+  options: string[];
+  multipleChoice?: boolean;
+  /** ISO date, in the future. */
+  closesAt?: string | null;
+  resultsVisibility?: CommunityPollResultsVisibility;
+}
+
+/** Where a post or reply stands in moderation. */
+export type CommunityContentStatus = "published" | "pending" | "rejected";
+
+/** True when a post or reply is waiting for a moderator (only its author ever sees it). */
+export function isCommunityContentPending(
+  item: { status?: CommunityContentStatus | string | null } | null | undefined,
+): boolean {
+  return item?.status === "pending";
 }
 
 export interface CommunityReply {
   id: string;
   postId: string;
   parentReplyId: string | null;
-  authorAccountId: string;
+  /** Null when the community AI wrote it (`agentAuthor` is then set). */
+  authorAccountId: string | null;
   body: unknown;
   bodyText: string | null;
   reactionCount: number;
   createdAt: string;
   author: CommunityAuthor | null;
+  /** The community AI, when this reply is its answer. `author` is then null. */
+  agentAuthor?: CommunityAgentAuthor | null;
   media: CommunityMediaItem[];
   reactions?: ReactionSummary[];
+  /** See `CommunityPost.status`. */
+  status?: CommunityContentStatus;
+  moderationReason?: string | null;
+  /** Set in the cache when a moderator removes the reply in this session. */
+  archivedAt?: string | null;
 }
 
 /** Attachment input shape the community create endpoints accept. */
@@ -136,6 +251,20 @@ export interface CommunityMemberProfile {
   createdAt: string;
   firstName: string | null;
   lastName: string | null;
+  /**
+   * Only on `/me`: whether this member moderates THIS community (the moderator
+   * role here, or an owner/admin of the profile). Display only; the server
+   * checks again on every moderation call.
+   */
+  canModerate?: boolean;
+  /** Listed in the member directory (default true). */
+  showInDirectory?: boolean;
+  /** Counted on the member map, by country only (default false). */
+  showOnMap?: boolean;
+  /** Free text, display only. */
+  city?: string | null;
+  /** ISO 3166-1 alpha-2, or null. */
+  countryCode?: string | null;
   recentPosts?: {
     id: string;
     spaceId: string;
@@ -158,17 +287,30 @@ export interface CommunityMemberProfile {
 
 export type CommunityDigestCadence = "off" | "inapp_only" | "hourly" | "daily";
 
-export type CommunityNotificationType = "mention" | "reply" | "reaction" | "new_post" | "mod";
+export type CommunityNotificationType = "mention" | "reply" | "reaction" | "new_post" | "mod" | "level_up";
 
 export interface CommunityNotificationItem {
   id: string;
   profileId: string;
   accountId: string;
   type: CommunityNotificationType | string;
-  entityType: "community_post" | "community_reply" | string | null;
+  entityType: "community_post" | "community_reply" | "community" | string | null;
   entityId: string | null;
   readAt: string | null;
   createdAt: string;
+  /**
+   * Extra detail for some types. A `mod` notice about a post or reply carries
+   * the moderation outcome; a `mod` notice about the community (a mute) has none.
+   */
+  data?: CommunityNotificationData | null;
+}
+
+export interface CommunityNotificationData {
+  outcome?: "approved" | "rejected";
+  reason?: string | null;
+  /** On a `level_up`: the level the member reached. */
+  level?: number;
+  [key: string]: unknown;
 }
 
 export interface CommunityLeaderboardEntry {
@@ -234,35 +376,40 @@ export function communityMemberName(
 }
 
 // Query keys are exported so the realtime layer (and creators) can patch the
-// same caches the data hooks populate — mirrors chatKeys in useChat.ts.
+// same caches the data hooks populate: mirrors chatKeys in useChat.ts.
 export const communityKeys = {
-  spaces: (profileId?: string) => ["public-community-spaces", profileId] as const,
+  // Scoped by COMMUNITY, not profile: a profile runs several, and one cache
+  // entry per profile would show community A's spaces inside community B.
+  spaces: (communityId?: string) => ["public-community-spaces", communityId] as const,
   spaceMembers: (spaceId?: string) => ["public-community-space-members", spaceId] as const,
   posts: (spaceId?: string) => ["public-community-posts", spaceId] as const,
   post: (postId?: string) => ["public-community-post", postId] as const,
   replies: (postId?: string) => ["public-community-replies", postId] as const,
-  myProfile: (profileId?: string) => ["public-community-my-profile", profileId] as const,
-  member: (profileId?: string, accountId?: string) => ["public-community-member", profileId, accountId] as const,
-  notifications: (profileId?: string, unreadOnly?: boolean) =>
-    ["public-community-notifications", profileId, unreadOnly] as const,
-  unread: (profileId?: string) => ["public-community-unread", profileId] as const,
-  leaderboard: (profileId?: string, period?: string) => ["public-community-leaderboard", profileId, period] as const,
-  search: (profileId?: string, q?: string, spaceId?: string) =>
-    ["public-community-search", profileId, q, spaceId ?? null] as const,
+  myProfile: (communityId?: string) => ["public-community-my-profile", communityId] as const,
+  member: (communityId?: string, accountId?: string) => ["public-community-member", communityId, accountId] as const,
+  notifications: (communityId?: string, unreadOnly?: boolean) =>
+    ["public-community-notifications", communityId, unreadOnly] as const,
+  unread: (communityId?: string) => ["public-community-unread", communityId] as const,
+  leaderboard: (communityId?: string, period?: string) => ["public-community-leaderboard", communityId, period] as const,
+  search: (communityId?: string, q?: string, spaceId?: string) =>
+    ["public-community-search", communityId, q, spaceId ?? null] as const,
+  moderationQueue: (communityId?: string) => ["public-community-moderation-queue", communityId] as const,
+  moderationLog: (communityId?: string, page?: number) =>
+    ["public-community-moderation-log", communityId, page] as const,
 };
 
 // ── Data hooks ───────────────────────────────────────────────────────────────
 
 /** Spaces the current member can access (GET /public/community/spaces). */
 export function useCommunitySpaces() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunitySpaces()");
   return useQuery<CommunitySpace[]>({
-    queryKey: communityKeys.spaces(profileId),
+    queryKey: communityKeys.spaces(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/community/spaces", { params: { profileId } });
+      const res = await client.get("/public/community/spaces", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
@@ -274,30 +421,30 @@ export interface SpaceMembershipResult {
 /** Patch one space's isJoined/memberCount inside the spaces list cache. */
 export function setSpaceMembership(
   queryClient: QueryClient,
-  profileId: string | undefined,
+  communityId: string | undefined,
   spaceId: string,
   membership: SpaceMembershipResult,
 ) {
-  queryClient.setQueryData(communityKeys.spaces(profileId), (old: CommunitySpace[] | undefined) =>
+  queryClient.setQueryData(communityKeys.spaces(communityId), (old: CommunitySpace[] | undefined) =>
     old?.map((s) => (s.id === spaceId ? { ...s, ...membership } : s)),
   );
 }
 
 /**
  * Join a space (POST /public/community/spaces/:id/join). Tiers still govern
- * who can access a space — joining opts into new-post notifications/digests
+ * who can access a space: joining opts into new-post notifications/digests
  * and the roster. Interacting (post/reply/react) auto-joins server-side.
  */
 export function useJoinCommunitySpace() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useJoinCommunitySpace()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (spaceId: string) => {
-      const res = await client.post(`/public/community/spaces/${spaceId}/join`, { profileId });
+      const res = await client.post(`/public/community/spaces/${spaceId}/join`, { profileId, communityId });
       return { ...(res.data as SpaceMembershipResult), spaceId };
     },
     onSuccess: ({ spaceId, ...membership }) => {
-      setSpaceMembership(queryClient, profileId, spaceId, membership);
+      setSpaceMembership(queryClient, communityId, spaceId, membership);
       queryClient.invalidateQueries({ queryKey: communityKeys.spaceMembers(spaceId) });
     },
   });
@@ -305,15 +452,15 @@ export function useJoinCommunitySpace() {
 
 /** Leave a space (POST /public/community/spaces/:id/leave). Always explicit. */
 export function useLeaveCommunitySpace() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useLeaveCommunitySpace()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (spaceId: string) => {
-      const res = await client.post(`/public/community/spaces/${spaceId}/leave`, { profileId });
+      const res = await client.post(`/public/community/spaces/${spaceId}/leave`, { profileId, communityId });
       return { ...(res.data as SpaceMembershipResult), spaceId };
     },
     onSuccess: ({ spaceId, ...membership }) => {
-      setSpaceMembership(queryClient, profileId, spaceId, membership);
+      setSpaceMembership(queryClient, communityId, spaceId, membership);
       queryClient.invalidateQueries({ queryKey: communityKeys.spaceMembers(spaceId) });
     },
   });
@@ -321,98 +468,135 @@ export function useLeaveCommunitySpace() {
 
 /** Paginated joined-member roster for a space. */
 export function useCommunitySpaceMembers(spaceId?: string, limit = 50) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunitySpaceMembers()");
   return useInfiniteQuery<CommunitySpaceMembersPage>({
     queryKey: communityKeys.spaceMembers(spaceId),
     queryFn: async ({ pageParam = 1 }) => {
       const res = await client.get(`/public/community/spaces/${spaceId}/members`, {
-        params: { profileId, page: pageParam, limit },
+        params: { profileId, communityId, page: pageParam, limit },
       });
       return res.data;
     },
     initialPageParam: 1,
     getNextPageParam: (lastPage) => (lastPage.hasNextPage ? lastPage.page + 1 : undefined),
-    enabled: !!spaceId && !!client && !!profileId,
+    enabled: !!spaceId && !!client && !!profileId && !!communityId,
   });
 }
 
 /** Paginated posts for a space, pinned first then most recent activity. */
 export function useCommunitySpacePosts(spaceId?: string, limit = 20) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunitySpacePosts()");
   return useInfiniteQuery<CommunityPostsPage>({
     queryKey: communityKeys.posts(spaceId),
     queryFn: async ({ pageParam = 1 }) => {
       const res = await client.get(`/public/community/spaces/${spaceId}/posts`, {
-        params: { profileId, page: pageParam, limit },
+        params: { profileId, communityId, page: pageParam, limit },
       });
       return res.data;
     },
     initialPageParam: 1,
     getNextPageParam: (lastPage) => (lastPage.hasNextPage ? lastPage.page + 1 : undefined),
-    enabled: !!spaceId && !!client && !!profileId,
+    enabled: !!spaceId && !!client && !!profileId && !!communityId,
   });
 }
 
 /**
  * A single post (GET /public/community/posts/:id). The endpoint also returns a
- * replies page — we request the minimum (limit=1) and let the dedicated
+ * replies page: we request the minimum (limit=1) and let the dedicated
  * replies hook own pagination, so both caches stay simple.
  */
 export function useCommunityPost(postId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunityPost()");
   return useQuery<CommunityPost>({
     queryKey: communityKeys.post(postId),
     queryFn: async () => {
       const res = await client.get(`/public/community/posts/${postId}`, {
-        params: { profileId, page: 1, limit: 1 },
+        params: { profileId, communityId, page: 1, limit: 1 },
       });
       return res.data.post;
     },
-    enabled: !!postId && !!client && !!profileId,
+    enabled: !!postId && !!client && !!profileId && !!communityId,
   });
 }
 
 /**
  * Flat, chronological reply pages for a post (GET /public/community/posts/:id/replies).
- * `parentReplyId` is included on every row — assemble the tree with
+ * `parentReplyId` is included on every row: assemble the tree with
  * `buildReplyTree` (data nesting is unlimited; the 3-level display cap is a UI concern).
  */
 export function useCommunityReplies(postId?: string, limit = 100) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunityReplies()");
   return useInfiniteQuery<CommunityRepliesPage>({
     queryKey: communityKeys.replies(postId),
     queryFn: async ({ pageParam = 1 }) => {
       const res = await client.get(`/public/community/posts/${postId}/replies`, {
-        params: { profileId, page: pageParam, limit },
+        params: { profileId, communityId, page: pageParam, limit },
       });
       return res.data;
     },
     initialPageParam: 1,
     getNextPageParam: (lastPage) => (lastPage.hasNextPage ? lastPage.page + 1 : undefined),
-    enabled: !!postId && !!client && !!profileId,
+    enabled: !!postId && !!client && !!profileId && !!communityId,
   });
 }
 
 export interface CreateCommunityPostInput {
   title?: string;
-  /** Lexical editor state — build one from plain text with `buildLexicalState`. */
+  /** Lexical editor state: build one from plain text with `buildLexicalState`. */
   body: unknown;
   attachments?: CommunityAttachmentInput[];
   mentionedAccountIds?: string[];
+  /** Attach a poll. `title` is then its question, and required. */
+  poll?: CommunityPollInput;
 }
 
 /** Create a post in a space (POST /public/community/spaces/:id/posts). */
 export function useCreateCommunityPost(spaceId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCreateCommunityPost()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (input: CreateCommunityPostInput) => {
-      const res = await client.post(`/public/community/spaces/${spaceId}/posts`, { profileId, ...input });
+      const res = await client.post(`/public/community/spaces/${spaceId}/posts`, { profileId, communityId, ...input });
       return res.data as CommunityPost;
     },
     onSuccess: (post) => {
       prependPostToFeed(queryClient, spaceId, post);
-      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(profileId) });
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(communityId) });
+    },
+  });
+}
+
+export interface VoteCommunityPollInput {
+  postId: string;
+  /**
+   * The member's WHOLE answer: it replaces any earlier vote. An empty list
+   * withdraws the vote.
+   */
+  optionIds: string[];
+  /** Cache hint: the feed the post sits in. Omitted, every loaded feed is patched. */
+  spaceId?: string;
+}
+
+/**
+ * Vote on a post's poll (POST /public/community/posts/:id/poll/vote). Answers
+ * the updated poll, which lands in the feed and post caches. The server answers
+ * 409 once the poll has closed, 400 for an option that is not on it (or several
+ * on a single-choice poll), and 403 to a muted member or one without access.
+ */
+export function useVoteCommunityPoll() {
+  const { client, profileId, communityId } = useCommunityScope("useVoteCommunityPoll()");
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: VoteCommunityPollInput) => {
+      const res = await client.post(`/public/community/posts/${input.postId}/poll/vote`, {
+        profileId,
+        communityId,
+        optionIds: input.optionIds,
+      });
+      return { poll: res.data as CommunityPollView, input };
+    },
+    onSuccess: ({ poll, input }) => {
+      setPostPoll(queryClient, { postId: input.postId, spaceId: input.spaceId }, poll);
     },
   });
 }
@@ -424,19 +608,19 @@ export interface CreateCommunityReplyInput {
   mentionedAccountIds?: string[];
 }
 
-/** Reply to a post — optionally nested under another reply. */
+/** Reply to a post: optionally nested under another reply. */
 export function useCreateCommunityReply(postId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCreateCommunityReply()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (input: CreateCommunityReplyInput) => {
-      const res = await client.post(`/public/community/posts/${postId}/replies`, { profileId, ...input });
+      const res = await client.post(`/public/community/posts/${postId}/replies`, { profileId, communityId, ...input });
       return res.data as CommunityReply;
     },
     onSuccess: (reply) => {
       appendReplyToThread(queryClient, postId, reply);
       // Replying implicitly joins the post's space server-side.
-      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(profileId) });
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(communityId) });
     },
   });
 }
@@ -452,7 +636,7 @@ export interface ToggleReactionResult {
 
 /** Toggle an emoji reaction (POST /public/community/:entityType/:id/react). */
 export function useToggleCommunityReaction() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useToggleCommunityReaction()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (input: {
@@ -465,6 +649,7 @@ export function useToggleCommunityReaction() {
     }) => {
       const res = await client.post(`/public/community/${input.entityType}/${input.entityId}/react`, {
         profileId,
+        communityId,
         emoji: input.emoji,
       });
       return { ...(res.data as ToggleReactionResult), input };
@@ -472,14 +657,14 @@ export function useToggleCommunityReaction() {
     onSuccess: ({ reactions, input }) => {
       setReactionSummary(queryClient, input, reactions);
       // Adding a reaction implicitly joins the space server-side.
-      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(profileId) });
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(communityId) });
     },
   });
 }
 
 /** Report a post or reply to the moderators. */
 export function useReportCommunityContent() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useReportCommunityContent()");
   return useMutation({
     mutationFn: async (input: {
       entityId: string;
@@ -488,6 +673,7 @@ export function useReportCommunityContent() {
     }) => {
       const res = await client.post(`/public/community/posts/${input.entityId}/report`, {
         profileId,
+        communityId,
         entityType: input.entityType,
         reason: input.reason,
       });
@@ -496,22 +682,33 @@ export function useReportCommunityContent() {
   });
 }
 
-/** The member's own community profile — created on first read (GET /public/community/me). */
+/** The member's own community profile: created on first read (GET /public/community/me). */
 export function useMyCommunityProfile(enabled = true) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useMyCommunityProfile()");
   return useQuery<CommunityMemberProfile>({
-    queryKey: communityKeys.myProfile(profileId),
+    queryKey: communityKeys.myProfile(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/community/me", { params: { profileId } });
+      const res = await client.get("/public/community/me", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: enabled && !!profileId && !!client,
+    enabled: enabled && !!profileId && !!communityId && !!client,
   });
 }
 
+/**
+ * Whether the signed-in member moderates THIS community (`canModerate` on
+ * `/me`), for showing the moderation tools. Display only: every moderation
+ * call is checked again by the server. Reads the same cache entry as
+ * `useMyCommunityProfile`, and stays false (with no request) until `enabled`.
+ */
+export function useCommunityCanModerate(enabled = true): boolean {
+  const { data } = useMyCommunityProfile(enabled);
+  return enabled && !!data?.canModerate;
+}
+
 /** Update display name / bio / avatar / digest cadence (PUT /public/community/me). */
 export function useUpdateMyCommunityProfile() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useUpdateMyCommunityProfile()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (input: {
@@ -519,128 +716,174 @@ export function useUpdateMyCommunityProfile() {
       bio?: string | null;
       avatarUrl?: string | null;
       digestCadence?: CommunityDigestCadence;
+      showInDirectory?: boolean;
+      showOnMap?: boolean;
+      city?: string | null;
+      countryCode?: string | null;
     }) => {
-      const res = await client.put("/public/community/me", { profileId, ...input });
+      const res = await client.put("/public/community/me", { profileId, communityId, ...input });
       return res.data as CommunityMemberProfile;
     },
     onSuccess: (profile) => {
-      queryClient.setQueryData(communityKeys.myProfile(profileId), profile);
-      queryClient.invalidateQueries({ queryKey: communityKeys.member(profileId, profile?.accountId) });
+      // Merged, not replaced: `/me` carries fields the PUT answer may not
+      // (`canModerate`), and dropping them would hide the moderator's tools.
+      queryClient.setQueryData(communityKeys.myProfile(communityId), (old: CommunityMemberProfile | undefined) =>
+        old ? { ...old, ...profile } : profile,
+      );
+      queryClient.invalidateQueries({ queryKey: communityKeys.member(communityId, profile?.accountId) });
+      // Directory and map visibility may have changed.
+      queryClient.invalidateQueries({ queryKey: ["public-community-directory", communityId] });
+      queryClient.invalidateQueries({ queryKey: ["public-community-member-map", communityId] });
     },
   });
 }
 
 /** Another member's profile + recent activity (filtered to spaces you can read). */
 export function useCommunityMemberProfile(accountId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunityMemberProfile()");
   return useQuery<CommunityMemberProfile>({
-    queryKey: communityKeys.member(profileId, accountId),
+    queryKey: communityKeys.member(communityId, accountId),
     queryFn: async () => {
-      const res = await client.get(`/public/community/profile/${accountId}`, { params: { profileId } });
+      const res = await client.get(`/public/community/profile/${accountId}`, { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!accountId && !!profileId && !!client,
+    enabled: !!accountId && !!profileId && !!communityId && !!client,
   });
 }
 
 /** In-app inbox (GET /public/community/notifications). Returns { data, unreadCount }. */
 export function useCommunityNotifications({ unreadOnly = false, limit = 50 } = {}) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunityNotifications()");
   return useQuery<{ data: CommunityNotificationItem[]; unreadCount: number }>({
-    queryKey: communityKeys.notifications(profileId, unreadOnly),
+    queryKey: communityKeys.notifications(communityId, unreadOnly),
     queryFn: async () => {
       const res = await client.get("/public/community/notifications", {
-        params: { profileId, page: 1, limit, unreadOnly },
+        params: { profileId, communityId, page: 1, limit, unreadOnly },
       });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
 /** Unread count for the bell, polled every 30s (same cadence as chat unread counts). */
 export function useCommunityUnreadCount(enabled = true) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunityUnreadCount()");
   return useQuery<number>({
-    queryKey: communityKeys.unread(profileId),
+    queryKey: communityKeys.unread(communityId),
     queryFn: async () => {
       const res = await client.get("/public/community/notifications", {
-        params: { profileId, page: 1, limit: 1, unreadOnly: true },
+        params: { profileId, communityId, page: 1, limit: 1, unreadOnly: true },
       });
       return res.data.unreadCount as number;
     },
-    enabled: enabled && !!profileId && !!client,
+    enabled: enabled && !!profileId && !!communityId && !!client,
     refetchInterval: 30000,
   });
 }
 
-/** Mark notifications read — omit ids to mark ALL unread as read. */
+/** Mark notifications read: omit ids to mark ALL unread as read. */
 export function useMarkCommunityNotificationsRead() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useMarkCommunityNotificationsRead()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (ids?: string[]) => {
-      await client.post("/public/community/notifications/mark-read", { profileId, ids });
+      await client.post("/public/community/notifications/mark-read", { profileId, communityId, ids });
     },
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ["public-community-notifications"] });
-      queryClient.invalidateQueries({ queryKey: communityKeys.unread(profileId) });
+      queryClient.invalidateQueries({ queryKey: communityKeys.unread(communityId) });
     },
   });
 }
 
 /** Points leaderboard (GET /public/community/leaderboard?period=all|7|30). */
 export function useCommunityLeaderboard(period: CommunityLeaderboardPeriod = "all", limit = 20) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunityLeaderboard()");
   return useQuery<CommunityLeaderboardEntry[]>({
-    queryKey: communityKeys.leaderboard(profileId, period),
+    queryKey: communityKeys.leaderboard(communityId, period),
     queryFn: async () => {
-      const res = await client.get("/public/community/leaderboard", { params: { profileId, period, limit } });
+      const res = await client.get("/public/community/leaderboard", { params: { profileId, communityId, period, limit } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
+/** How long the typed @query settles before the member search runs. */
+export const MENTION_SEARCH_DEBOUNCE_MS = 150;
+
 /**
- * Member directory for @mention autocomplete. There is no dedicated public
- * member-search endpoint yet, so this reads the all-time leaderboard at its max
- * page size (100) — every community_profiles row ranked by points — and filters
- * client-side.
+ * The member search behind @mention: the typed text as `q` (left out when
+ * blank, so a bare "@" lists the most active members), ten results, most
+ * recently active first.
  */
-export function useCommunityMentionDirectory() {
-  const { client, profileId } = useForge();
+export function mentionDirectoryParams(q: string | null | undefined): Record<string, string | number> {
+  const trimmed = (q ?? "").trim().slice(0, 80);
+  return { ...(trimmed ? { q: trimmed } : {}), limit: 10, sort: "active" };
+}
+
+/**
+ * Members for @mention autocomplete, searched on the server as the member
+ * types (GET /public/community/members), so every current member can be
+ * mentioned, not just the hundred with the most points. Pass the text after
+ * the "@"; pass `undefined` while no @token is active and nothing is asked
+ * for. Rows come back in the leaderboard entry shape the composers read.
+ */
+export function useCommunityMentionDirectory(query?: string | null) {
+  const { client, profileId, communityId } = useCommunityScope("useCommunityMentionDirectory()");
+  const active = query !== undefined && query !== null;
+  // null while no @token is open. The first text after "@" is searched at
+  // once; typing after that settles first, so a request goes per pause.
+  const [settled, setSettled] = useState<string | null>(null);
+  useEffect(() => {
+    if (!active) {
+      setSettled(null);
+      return;
+    }
+    const id = setTimeout(() => setSettled(query ?? ""), MENTION_SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(id);
+  }, [query, active]);
+  const params = mentionDirectoryParams(settled ?? query);
   return useQuery<CommunityLeaderboardEntry[]>({
-    queryKey: communityKeys.leaderboard(profileId, "mention-directory"),
+    queryKey: ["public-community-mention-search", communityId, params] as const,
     queryFn: async () => {
-      const res = await client.get("/public/community/leaderboard", {
-        params: { profileId, period: "all", limit: 100 },
-      });
-      return res.data;
+      const res = await client.get("/public/community/members", { params: { profileId, communityId, ...params } });
+      const rows = (res.data?.data ?? []) as Array<CommunityLeaderboardEntry & { points?: number }>;
+      return rows.map((m) => ({
+        accountId: m.accountId,
+        displayName: m.displayName,
+        avatarUrl: m.avatarUrl,
+        points: m.points ?? 0,
+        level: m.level,
+        firstName: m.firstName,
+        lastName: m.lastName,
+      }));
     },
-    enabled: !!profileId && !!client,
-    staleTime: 60_000,
+    placeholderData: keepPreviousData,
+    enabled: active && !!profileId && !!communityId && !!client,
+    staleTime: 30_000,
   });
 }
 
 /**
  * FTS over posts + replies (min 2 chars). Scopes to spaces the member can read;
- * pass `spaceId` (a space uuid OR its per-profile slug) to scope to one space —
+ * pass `spaceId` (a space uuid OR its per-profile slug) to scope to one space:
  * scoping can only narrow, never widen, access. Backward-compatible: called with
  * just a query it searches every accessible space (prior behavior).
  */
 export function useCommunitySearch(q: string, spaceId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCommunitySearch()");
   const trimmed = q.trim();
   return useQuery<CommunitySearchResults>({
-    queryKey: communityKeys.search(profileId, trimmed, spaceId),
+    queryKey: communityKeys.search(communityId, trimmed, spaceId),
     queryFn: async () => {
       const res = await client.get("/public/community/search", {
-        params: { profileId, q: trimmed, page: 1, limit: 20, ...(spaceId ? { spaceId } : {}) },
+        params: { profileId, communityId, q: trimmed, page: 1, limit: 20, ...(spaceId ? { spaceId } : {}) },
       });
       return res.data;
     },
-    enabled: trimmed.length >= 2 && !!profileId && !!client,
+    enabled: trimmed.length >= 2 && !!profileId && !!communityId && !!client,
   });
 }
 
@@ -714,6 +957,32 @@ export function bumpFeedReplyCount(queryClient: QueryClient, spaceId: string | u
   });
 }
 
+/**
+ * Put a post's updated poll into every cache that renders the post: its feed
+ * (the one named, or every loaded feed when none is) and the single-post read.
+ */
+export function setPostPoll(
+  queryClient: QueryClient,
+  target: { postId: string; spaceId?: string },
+  poll: CommunityPollView | null,
+) {
+  const patchFeed = (old: any) => {
+    if (!old?.pages?.length) return old;
+    return {
+      ...old,
+      pages: old.pages.map((page: any) => ({
+        ...page,
+        data: page.data.map((p: CommunityPost) => (p.id === target.postId ? { ...p, poll } : p)),
+      })),
+    };
+  };
+  if (target.spaceId) queryClient.setQueryData(communityKeys.posts(target.spaceId), patchFeed);
+  else queryClient.setQueriesData({ queryKey: ["public-community-posts"] }, patchFeed);
+  queryClient.setQueryData(communityKeys.post(target.postId), (old: CommunityPost | undefined) =>
+    old ? { ...old, poll } : old,
+  );
+}
+
 /** Replace an entity's reaction summary in every cache that renders it. */
 export function setReactionSummary(
   queryClient: QueryClient,
@@ -792,3 +1061,82 @@ export function applyReactionDelta(
     });
   }
 }
+
+/** The `communityContentHeld` socket payload: auto-moderation sent it back to the approval queue. */
+export interface CommunityContentHeldEvent {
+  spaceId: string;
+  entityType: "community_post" | "community_reply";
+  postId: string | null;
+  replyId: string | null;
+}
+
+/**
+ * Take a post or reply that was just held for approval out of the open feeds
+ * and threads. Everyone else loses it at once; its author keeps it, marked as
+ * waiting for approval, exactly as the server shows them their own held work.
+ * An open post that is held for a reader who is not its author becomes `null`,
+ * which the thread renders as unavailable.
+ */
+export function applyCommunityContentHeld(
+  queryClient: QueryClient,
+  event: CommunityContentHeldEvent,
+  viewerAccountId: string | null | undefined,
+) {
+  const mine = (authorAccountId: string | null | undefined) => !!viewerAccountId && authorAccountId === viewerAccountId;
+  const asPending = <T extends { status?: CommunityContentStatus }>(item: T): T => ({ ...item, status: "pending" });
+
+  if (event.entityType === "community_post" && event.postId) {
+    const postId = event.postId;
+    queryClient.setQueryData(communityKeys.posts(event.spaceId), (old: any) => {
+      if (!old?.pages?.length) return old;
+      return {
+        ...old,
+        pages: old.pages.map((page: any) => {
+          const had = page.data.some((p: CommunityPost) => p.id === postId);
+          if (!had) return page;
+          const data = page.data.flatMap((p: CommunityPost) =>
+            p.id !== postId ? [p] : mine(p.authorAccountId) ? [asPending(p)] : [],
+          );
+          return { ...page, data, total: Math.max(0, page.total - (page.data.length - data.length)) };
+        }),
+      };
+    });
+    queryClient.setQueryData(communityKeys.post(postId), (old: CommunityPost | null | undefined) =>
+      old ? (mine(old.authorAccountId) ? asPending(old) : null) : old,
+    );
+    return;
+  }
+
+  if (event.entityType === "community_reply" && event.postId && event.replyId) {
+    const { postId, replyId } = event;
+    let removed = false;
+    queryClient.setQueryData(communityKeys.replies(postId), (old: any) => {
+      if (!old?.pages?.length) return old;
+      return {
+        ...old,
+        pages: old.pages.map((page: any) => {
+          if (!page.data.some((r: CommunityReply) => r.id === replyId)) return page;
+          const data = page.data.flatMap((r: CommunityReply) =>
+            r.id !== replyId ? [r] : mine(r.authorAccountId) ? [asPending(r)] : [],
+          );
+          if (data.length < page.data.length) removed = true;
+          return { ...page, data, total: Math.max(0, page.total - (page.data.length - data.length)) };
+        }),
+      };
+    });
+    if (removed) {
+      const drop = (p: CommunityPost) => ({ ...p, replyCount: Math.max(0, (p.replyCount ?? 0) - 1) });
+      queryClient.setQueryData(communityKeys.post(postId), (old: CommunityPost | null | undefined) => (old ? drop(old) : old));
+      queryClient.setQueryData(communityKeys.posts(event.spaceId), (old: any) => {
+        if (!old?.pages?.length) return old;
+        return {
+          ...old,
+          pages: old.pages.map((page: any) => ({
+            ...page,
+            data: page.data.map((p: CommunityPost) => (p.id === postId ? drop(p) : p)),
+          })),
+        };
+      });
+    }
+  }
+}