@openmarket/rooms-client 0.4.2 → 0.5.1

package/dist/agent/sidebar-model.d.ts

@@ -22,6 +22,9 @@ export interface SidebarRoom {
     headSeq: number | null;
     lastReadSeq: number | null;
     unread: number;
+    /** Unread mention count from the latest read-state snapshot: the server's
+     *  number verbatim, 0 when the snapshot carried none for this room. */
+    mentionUnread: number;
     joined: boolean;
     /** Topics dial from room meta. Absent reads as "allowed" since the
      *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
@@ -40,6 +43,13 @@ export interface SidebarSnapshot {
     dms: SidebarDm[];
     popular: SidebarRoom[];
     globalReplyUnread: number;
+    /** Per-room unread mention counts exactly as the server sent them in the
+     *  latest read-state snapshot: sparse (zero-count rooms absent) and
+     *  global (rooms outside the current listings may appear). Empty when the
+     *  snapshot carried none; a fresh snapshot replaces it wholesale. */
+    mentionCounts: Record<string, number>;
+    /** User-wide unread mention total from the same snapshot. */
+    mentionTotal: number;
     fetchedAt: number;
 }
 export declare const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot;
@@ -48,10 +58,22 @@ export declare function computeRoomUnread(input: {
     headSeq: number | null;
     lastReadSeq: number | null;
 }): number;
+/** A READ_STATE reply that carries the additive mention decorations beside
+ *  the cursor map (RoomReadStatePayload satisfies this shape). Old
+ *  fetchReadState implementations returning the bare cursor Record keep
+ *  working; mention fields then read as zero. */
+export interface SidebarReadState {
+    readState: Record<string, number>;
+    mentionCounts?: Record<string, number> | undefined;
+    mentionTotal?: number | undefined;
+}
 export declare function buildSidebarSnapshot(input: {
     rooms: RoomMeta[];
     spaces: RoomSpace[];
     readState: Record<string, number>;
+    /** Server numbers pass through verbatim; merge policy is the caller's. */
+    mentionCounts?: Record<string, number> | undefined;
+    mentionTotal?: number | undefined;
     dms: SidebarDm[];
     globalReplyUnread: number;
     joinedUnread: (roomName: string) => number | null;
@@ -60,7 +82,9 @@ export declare function buildSidebarSnapshot(input: {
 export interface SidebarModelDeps {
     fetchRooms: () => Promise<RoomMeta[]>;
     fetchSpaces: () => Promise<RoomSpace[]>;
-    fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+    /** Either the bare cursor Record (the 0.2.0 shape) or a SidebarReadState
+     *  whose mention decorations feed the snapshot's mention fields. */
+    fetchReadState: (roomNames: string[]) => Promise<Record<string, number> | SidebarReadState>;
     fetchDms: () => Promise<SidebarDm[]>;
     fetchGlobalReplyUnread: () => Promise<number>;
     joinedUnread: (roomName: string) => number | null;
@@ -74,6 +98,9 @@ export declare class SidebarModel {
     constructor(deps: SidebarModelDeps);
     snapshot(): SidebarSnapshot;
     onUpdate(listener: () => void): () => void;
+    /** Apply a same-user realtime DM counter without refetching the full room
+     *  directory. Username is the stable DM key used by the sidebar model. */
+    applyDmUnread(username: string, unread: number): void;
     /**
      * Post-mutation refresh: if a poll-triggered load is already in flight it
      * may predate the caller's writes, so wait it out and load AGAIN. Readers

package/dist/agent/sidebar-model.js

@@ -4,6 +4,8 @@ export const EMPTY_SIDEBAR_SNAPSHOT = {
     dms: [],
     popular: [],
     globalReplyUnread: 0,
+    mentionCounts: {},
+    mentionTotal: 0,
     fetchedAt: 0,
 };
 const POPULAR_MAX = 6;
@@ -34,6 +36,11 @@ export function buildSidebarSnapshot(input) {
             headSeq,
             lastReadSeq,
             unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+            // Own-key guard like the readState read above: rooms named after
+            // Object.prototype members must read 0 from a sparse map, not NaN.
+            mentionUnread: Math.max(0, input.mentionCounts && Object.hasOwn(input.mentionCounts, name)
+                ? (input.mentionCounts[name] ?? 0)
+                : 0),
             // Joined = an open context OR a server read cursor (you only get a
             // cursor by having been in the room). This is what decides whether a
             // room lives in your channel tree or in the POPULAR discovery shelf.
@@ -92,9 +99,30 @@ export function buildSidebarSnapshot(input) {
         dms: input.dms,
         popular,
         globalReplyUnread: Math.max(0, input.globalReplyUnread),
+        mentionCounts: input.mentionCounts ?? {},
+        mentionTotal: Math.max(0, input.mentionTotal ?? 0),
         fetchedAt: input.now,
     };
 }
+/** A bare cursor Record maps room name to seq (numbers only), so an object
+ *  under the "readState" key can only be the snapshot shape, even for a
+ *  room literally named "readState" (its cursor would be a number). */
+function normalizeSidebarReadState(reply) {
+    const nested = reply.readState;
+    if (typeof nested === "object" && nested !== null) {
+        const snapshot = reply;
+        return {
+            readState: snapshot.readState,
+            mentionCounts: snapshot.mentionCounts,
+            mentionTotal: snapshot.mentionTotal,
+        };
+    }
+    return {
+        readState: reply,
+        mentionCounts: undefined,
+        mentionTotal: undefined,
+    };
+}
 export class SidebarModel {
     deps;
     snapshotValue = EMPTY_SIDEBAR_SNAPSHOT;
@@ -112,6 +140,34 @@ export class SidebarModel {
             this.listeners.delete(listener);
         };
     }
+    /** Apply a same-user realtime DM counter without refetching the full room
+     *  directory. Username is the stable DM key used by the sidebar model. */
+    applyDmUnread(username, unread) {
+        const key = normalizeDmUsername(username);
+        if (!key)
+            return;
+        const normalizedUnread = Number.isFinite(unread) ? Math.max(0, Math.floor(unread)) : 0;
+        let found = false;
+        let changed = false;
+        const next = this.snapshotValue.dms.map((dm) => {
+            if (normalizeDmUsername(dm.username) !== key)
+                return dm;
+            found = true;
+            if (dm.unread === normalizedUnread)
+                return dm;
+            changed = true;
+            return { ...dm, unread: normalizedUnread };
+        });
+        if (!found && normalizedUnread > 0) {
+            next.push({ username: username.replace(/^@+/, ""), unread: normalizedUnread });
+            changed = true;
+        }
+        if (!changed)
+            return;
+        this.snapshotValue = { ...this.snapshotValue, dms: next };
+        for (const listener of this.listeners)
+            listener();
+    }
     /**
      * Post-mutation refresh: if a poll-triggered load is already in flight it
      * may predate the caller's writes, so wait it out and load AGAIN. Readers
@@ -146,13 +202,16 @@ export class SidebarModel {
             this.deps.fetchDms().catch(() => []),
             this.deps.fetchGlobalReplyUnread().catch(() => 0),
         ]);
-        const readState = await this.deps
+        const readStateReply = await this.deps
             .fetchReadState(rooms.map((room) => room.name))
             .catch(() => ({}));
+        const { readState, mentionCounts, mentionTotal } = normalizeSidebarReadState(readStateReply);
         return buildSidebarSnapshot({
             rooms,
             spaces,
             readState,
+            mentionCounts,
+            mentionTotal,
             dms,
             globalReplyUnread,
             joinedUnread: this.deps.joinedUnread,
@@ -160,3 +219,6 @@ export class SidebarModel {
         });
     }
 }
+function normalizeDmUsername(username) {
+    return username.trim().replace(/^@+/, "").toLowerCase();
+}

package/dist/client.d.ts

@@ -242,6 +242,9 @@ export { workspaceRoomName } from "./names.js";
 export declare function listRooms(config: RoomClientConfig, request?: RoomListRequest): Promise<RoomListResult>;
 export declare function createRoom(config: RoomClientConfig, request: RoomCreateRequest): Promise<RoomCreateResult>;
 export declare function inviteRoom(config: RoomClientConfig, request: RoomInviteRequest): Promise<RoomInviteResult>;
+/** Invite over an already-authenticated socket. Long-lived GUI/TUI sessions
+ * use this path so a one-shot invite cannot create a second connection. */
+export declare function inviteRoomOnClient(client: RoomWsClient, request: RoomInviteRequest, timeoutMs?: number): Promise<RoomInvitedPayload>;
 export declare function removeRoomMember(config: RoomClientConfig, request: RoomRemoveMemberRequest): Promise<RoomRemoveMemberResult>;
 export declare function reportRoomTarget(config: RoomClientConfig, request: RoomReportRequest): Promise<RoomReportResult>;
 export declare function muteRoomMember(config: RoomClientConfig, request: RoomMuteRequest): Promise<RoomMuteResult>;

package/dist/client.js

@@ -101,9 +101,7 @@ async function createRoomViaWebSocket(config, request) {
 export async function inviteRoom(config, request) {
     // `@user` and `user` are the same person: strip the typing syntax once,
     // before either transport (the relay resolves the bare name).
-    const normalized = request.username
-        ? { ...request, username: request.username.trim().replace(/^@+/, "") }
-        : request;
+    const normalized = normalizeRoomInviteRequest(request);
     if (!config.webSocketCtor) {
         try {
             return await inviteRoomViaHttp(config, normalized);
@@ -119,24 +117,35 @@ async function inviteRoomViaWebSocket(config, request) {
     const client = new RoomWsClient(config);
     try {
         const auth = await client.connect();
-        const requestId = randomUUID();
-        client.send({
-            type: RoomClientMessageType.INVITE,
-            payload: {
-                requestId,
-                room: request.room,
-                ...(request.username ? { username: request.username } : {}),
-                ...(request.userId ? { userId: request.userId } : {}),
-            },
-            timestamp: Date.now(),
-        });
-        const invited = await client.waitFor(RoomServerMessageType.ROOM_INVITED, (msg) => msg.payload.requestId === requestId, undefined, requestId);
-        return { auth, invite: invited.payload };
+        return { auth, invite: await inviteRoomOnClient(client, request) };
     }
     finally {
         client.close();
     }
 }
+/** Invite over an already-authenticated socket. Long-lived GUI/TUI sessions
+ * use this path so a one-shot invite cannot create a second connection. */
+export async function inviteRoomOnClient(client, request, timeoutMs) {
+    const normalized = normalizeRoomInviteRequest(request);
+    const requestId = randomUUID();
+    client.send({
+        type: RoomClientMessageType.INVITE,
+        payload: {
+            requestId,
+            room: normalized.room,
+            ...(normalized.username ? { username: normalized.username } : {}),
+            ...(normalized.userId ? { userId: normalized.userId } : {}),
+        },
+        timestamp: Date.now(),
+    });
+    const invited = await client.waitFor(RoomServerMessageType.ROOM_INVITED, (msg) => msg.payload.requestId === requestId, timeoutMs, requestId);
+    return invited.payload;
+}
+function normalizeRoomInviteRequest(request) {
+    return request.username
+        ? { ...request, username: request.username.trim().replace(/^@+/, "") }
+        : request;
+}
 export async function removeRoomMember(config, request) {
     if (!config.webSocketCtor) {
         try {

package/dist/shared/rooms-protocol.d.ts

@@ -330,6 +330,16 @@ export interface RoomReadStatePayload {
      *  Present when the store surfaces it and on ROOM_SET_ATTENTION acks
      *  (which reply READ_STATE scoped to the one room, readState empty). */
     attention?: Record<string, RoomTopicAttention> | undefined;
+    /** Unread mention counts by room, server-computed from the notify
+     *  worker's ROOM_MENTION rows so badges survive reload and clear through
+     *  the ack path. Unlike readState/attention the map is SPARSE AND
+     *  GLOBAL: every room with a nonzero count appears (requested or not),
+     *  zero-count rooms are absent. Missing on servers older than the
+     *  mentions-completion store. */
+    mentionCounts?: Record<string, number> | undefined;
+    /** User-wide unread mention total (drives the app badge). Rides beside
+     *  mentionCounts; missing on older servers. */
+    mentionTotal?: number | undefined;
     requestId?: string | undefined;
 }
 export interface RoomSearchResultsPayload {

package/dist/social-client.d.ts

@@ -1,5 +1,5 @@
-import type { RoomDmConversation, RoomDmHistory, RoomDmSendResult, RoomDmUnreadConversation, RoomDoc, RoomDocAttribution, RoomDocChanges, RoomDocConflictHead, RoomDocEditingLease, RoomDocProvenance, RoomDocRevision, RoomDocRunRevertResult, RoomDocWriteResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequests, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomSocialConfig, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSuggestion, RoomSuggestionRequest } from "./social-types.js";
-export type { RoomAttachment, RoomDmConversation, RoomDmHistory, RoomDmMessage, RoomDmParticipant, RoomDmSendResult, RoomDmUnreadConversation, RoomDocAttribution, RoomDocEditingLease, RoomDocMergeRegion, RoomDocRevisionSource, RoomDocRunRevertResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequest, RoomFriendRequests, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomReplyInboxItem, RoomSocialConfig, RoomSpaceRestoreAction, RoomSpaceRestoreActionKind, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSpaceRestoreSummary, RoomSuggestion, RoomSuggestionIntent, RoomSuggestionRequest, RoomSuggestionSource, } from "./social-types.js";
+import type { RoomDmConversation, RoomDmHistory, RoomDmSendResult, RoomDmUnreadConversation, RoomDoc, RoomDocAttribution, RoomDocChanges, RoomDocConflictHead, RoomDocEditingLease, RoomDocProvenance, RoomDocRevision, RoomDocRunRevertResult, RoomDocWriteResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequests, RoomNotificationInboxResult, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomSocialConfig, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSuggestion, RoomSuggestionRequest } from "./social-types.js";
+export type { RoomAttachment, RoomDmConversation, RoomDmHistory, RoomDmMessage, RoomDmParticipant, RoomDmSendResult, RoomDmUnreadConversation, RoomDocAttribution, RoomDocEditingLease, RoomDocMergeRegion, RoomDocRevisionSource, RoomDocRunRevertResult, RoomFollow, RoomFollowResult, RoomFriend, RoomFriendRequest, RoomFriendRequests, RoomNotificationInboxItem, RoomNotificationInboxResult, RoomNotificationKind, RoomNotificationMessageData, RoomPublicProfile, RoomRepliesReadResult, RoomRepliesResult, RoomReplyInboxItem, RoomSocialConfig, RoomSpaceRestoreAction, RoomSpaceRestoreActionKind, RoomSpaceRestorePlan, RoomSpaceRestoreReceipt, RoomSpaceRestoreSummary, RoomSuggestion, RoomSuggestionIntent, RoomSuggestionRequest, RoomSuggestionSource, } from "./social-types.js";
 /** Largest per-file size any tier accepts (plus tier). The server enforces
  *  the per-tier caps (free 10MB/file, plus 25MB/file) and daily quotas; this
  *  constant only pre-flights uploads no tier could ever accept. */
@@ -330,6 +330,12 @@ export declare function listRoomChannelMembers(config: RoomSocialConfig, roomId:
 export declare function removeSpaceMember(config: RoomSocialConfig, spaceId: string, targetUserId: string): Promise<{
     removed?: boolean;
 }>;
+/** Leave a server as the authenticated caller. This is deliberately separate
+ * from the manager-only member-removal route so clients never send their own
+ * userId as authorization data. */
+export declare function leaveSpace(config: RoomSocialConfig, spaceId: string): Promise<{
+    left?: boolean;
+}>;
 export declare function changeSpaceMemberRole(config: RoomSocialConfig, spaceId: string, targetUserId: string, role: "admin" | "librarian" | "member"): Promise<RoomSpaceMember>;
 /** Set (string) or clear (null) a member's per-space nickname; the store validates and enforces uniqueness. */
 export declare function setSpaceMemberNickname(config: RoomSocialConfig, spaceId: string, targetUserId: string, nickname: string | null): Promise<RoomSpaceMember>;
@@ -362,6 +368,24 @@ export declare function markRoomRepliesRead(config: RoomSocialConfig, options?:
     room?: string;
     before?: string | Date;
 }): Promise<RoomRepliesReadResult>;
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export declare function listRoomNotifications(config: RoomSocialConfig, options?: {
+    limit?: number | undefined;
+    /** Feed a page's lastCursor back here (explicit undefined reads as
+     *  "first page", so `page.lastCursor ?? undefined` composes under
+     *  exactOptionalPropertyTypes). */
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    unread?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<RoomNotificationInboxResult>;
 export declare function suggestRooms(config: RoomSocialConfig, request: RoomSuggestionRequest, options?: {
     signal?: AbortSignal;
 }): Promise<RoomSuggestion[]>;

package/dist/social-client.js

@@ -500,6 +500,14 @@ export async function listRoomChannelMembers(config, roomId, options = {}) {
 export async function removeSpaceMember(config, spaceId, targetUserId) {
     return socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/members/${encodeURIComponent(targetUserId)}`, { method: "DELETE" });
 }
+/** Leave a server as the authenticated caller. This is deliberately separate
+ * from the manager-only member-removal route so clients never send their own
+ * userId as authorization data. */
+export async function leaveSpace(config, spaceId) {
+    return socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/membership`, {
+        method: "DELETE",
+    });
+}
 export async function changeSpaceMemberRole(config, spaceId, targetUserId, role) {
     const result = await socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/members/${encodeURIComponent(targetUserId)}/role`, { method: "PATCH", body: { role } });
     return result.member;
@@ -584,6 +592,35 @@ export async function markRoomRepliesRead(config, options = {}) {
     });
     return { markedRead: result.markedRead ?? 0 };
 }
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export async function listRoomNotifications(config, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    if (options.cursor !== undefined)
+        params.set("cursor", options.cursor);
+    if (options.cursorId !== undefined)
+        params.set("cursorId", options.cursorId);
+    if (options.unread !== undefined)
+        params.set("unread", String(options.unread));
+    const init = {};
+    if (options.signal)
+        init.signal = options.signal;
+    const result = await socialRequest(config, `/users/notifications${params.size ? `?${params.toString()}` : ""}`, init);
+    return {
+        notifications: result.notifications ?? [],
+        hasMore: result.hasMore ?? false,
+        lastCursor: result.lastCursor ?? null,
+        lastCursorId: result.lastCursorId ?? null,
+    };
+}
 export async function suggestRooms(config, request, options = {}) {
     const init = {
         method: "POST",

package/dist/social-types.d.ts

@@ -171,6 +171,44 @@ export interface RoomRepliesResult {
 export interface RoomRepliesReadResult {
     markedRead: number;
 }
+/** The room kinds the chat notification inbox returns (the store's
+ *  ROOM_INBOX_NOTIFICATION_TYPES). ROOM_FOLLOW rows stay out of the inbox:
+ *  follow is a push channel, not a badge source. */
+export type RoomNotificationKind = "ROOM_MENTION" | "ROOM_REPLY" | "ROOM_DM" | "ROOM_KEYWORD";
+/** Shared room payload on a notification row, wire names verbatim from the
+ *  store's notification schema (room_message_data). `preview` follows the
+ *  push body rules (140 chars, empty for sealed content); `hash` is the
+ *  client deep link. */
+export interface RoomNotificationMessageData {
+    kind: "dm" | "mention" | "reply" | "follow" | "keyword";
+    room_id?: string;
+    room_name?: string;
+    space_id?: string;
+    conversation_id?: string;
+    seq?: number;
+    from_handle: string;
+    preview: string;
+    hash: string;
+}
+/** One chat notification inbox row: the store's explicit field pick
+ *  (snake_case wire names, dates as ISO strings, room_message_data only
+ *  when the row carries one). */
+export interface RoomNotificationInboxItem {
+    id: string;
+    type: RoomNotificationKind;
+    created_at: string;
+    read_at: string | null;
+    room_message_data?: RoomNotificationMessageData;
+}
+/** A newest-first inbox page plus the composite cursor naming the last row
+ *  returned; feed lastCursor and lastCursorId back together to request the
+ *  next page. Both are null on an empty page. */
+export interface RoomNotificationInboxResult {
+    notifications: RoomNotificationInboxItem[];
+    hasMore: boolean;
+    lastCursor: string | null;
+    lastCursorId: string | null;
+}
 /** A living markdown doc scoped to a space (head state; content on demand). */
 export interface RoomDoc {
     docId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmarket/rooms-client",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "OM Rooms protocol client: wire types, WebSocket + REST clients, and chat view-models. Browser-safe (no node:/bun: imports).",
   "type": "module",
   "license": "Apache-2.0",

package/src/agent/sidebar-model.ts

@@ -23,6 +23,9 @@ export interface SidebarRoom {
   headSeq: number | null;
   lastReadSeq: number | null;
   unread: number;
+  /** Unread mention count from the latest read-state snapshot: the server's
+   *  number verbatim, 0 when the snapshot carried none for this room. */
+  mentionUnread: number;
   joined: boolean;
   /** Topics dial from room meta. Absent reads as "allowed" since the
    *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
@@ -40,6 +43,13 @@ export interface SidebarSnapshot {
   dms: SidebarDm[];
   popular: SidebarRoom[];
   globalReplyUnread: number;
+  /** Per-room unread mention counts exactly as the server sent them in the
+   *  latest read-state snapshot: sparse (zero-count rooms absent) and
+   *  global (rooms outside the current listings may appear). Empty when the
+   *  snapshot carried none; a fresh snapshot replaces it wholesale. */
+  mentionCounts: Record<string, number>;
+  /** User-wide unread mention total from the same snapshot. */
+  mentionTotal: number;
   fetchedAt: number;
 }
 
@@ -49,6 +59,8 @@ export const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot = {
   dms: [],
   popular: [],
   globalReplyUnread: 0,
+  mentionCounts: {},
+  mentionTotal: 0,
   fetchedAt: 0,
 };
 
@@ -65,10 +77,23 @@ export function computeRoomUnread(input: {
   return Math.max(0, input.headSeq - input.lastReadSeq);
 }
 
+/** A READ_STATE reply that carries the additive mention decorations beside
+ *  the cursor map (RoomReadStatePayload satisfies this shape). Old
+ *  fetchReadState implementations returning the bare cursor Record keep
+ *  working; mention fields then read as zero. */
+export interface SidebarReadState {
+  readState: Record<string, number>;
+  mentionCounts?: Record<string, number> | undefined;
+  mentionTotal?: number | undefined;
+}
+
 export function buildSidebarSnapshot(input: {
   rooms: RoomMeta[];
   spaces: RoomSpace[];
   readState: Record<string, number>;
+  /** Server numbers pass through verbatim; merge policy is the caller's. */
+  mentionCounts?: Record<string, number> | undefined;
+  mentionTotal?: number | undefined;
   dms: SidebarDm[];
   globalReplyUnread: number;
   joinedUnread: (roomName: string) => number | null;
@@ -91,6 +116,14 @@ export function buildSidebarSnapshot(input: {
       headSeq,
       lastReadSeq,
       unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+      // Own-key guard like the readState read above: rooms named after
+      // Object.prototype members must read 0 from a sparse map, not NaN.
+      mentionUnread: Math.max(
+        0,
+        input.mentionCounts && Object.hasOwn(input.mentionCounts, name)
+          ? (input.mentionCounts[name] ?? 0)
+          : 0,
+      ),
       // Joined = an open context OR a server read cursor (you only get a
       // cursor by having been in the room). This is what decides whether a
       // room lives in your channel tree or in the POPULAR discovery shelf.
@@ -154,6 +187,8 @@ export function buildSidebarSnapshot(input: {
     dms: input.dms,
     popular,
     globalReplyUnread: Math.max(0, input.globalReplyUnread),
+    mentionCounts: input.mentionCounts ?? {},
+    mentionTotal: Math.max(0, input.mentionTotal ?? 0),
     fetchedAt: input.now,
   };
 }
@@ -161,13 +196,39 @@ export function buildSidebarSnapshot(input: {
 export interface SidebarModelDeps {
   fetchRooms: () => Promise<RoomMeta[]>;
   fetchSpaces: () => Promise<RoomSpace[]>;
-  fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+  /** Either the bare cursor Record (the 0.2.0 shape) or a SidebarReadState
+   *  whose mention decorations feed the snapshot's mention fields. */
+  fetchReadState: (roomNames: string[]) => Promise<Record<string, number> | SidebarReadState>;
   fetchDms: () => Promise<SidebarDm[]>;
   fetchGlobalReplyUnread: () => Promise<number>;
   joinedUnread: (roomName: string) => number | null;
   now?: () => number;
 }
 
+/** A bare cursor Record maps room name to seq (numbers only), so an object
+ *  under the "readState" key can only be the snapshot shape, even for a
+ *  room literally named "readState" (its cursor would be a number). */
+function normalizeSidebarReadState(reply: Record<string, number> | SidebarReadState): {
+  readState: Record<string, number>;
+  mentionCounts: Record<string, number> | undefined;
+  mentionTotal: number | undefined;
+} {
+  const nested = (reply as SidebarReadState).readState;
+  if (typeof nested === "object" && nested !== null) {
+    const snapshot = reply as SidebarReadState;
+    return {
+      readState: snapshot.readState,
+      mentionCounts: snapshot.mentionCounts,
+      mentionTotal: snapshot.mentionTotal,
+    };
+  }
+  return {
+    readState: reply as Record<string, number>,
+    mentionCounts: undefined,
+    mentionTotal: undefined,
+  };
+}
+
 export class SidebarModel {
   private snapshotValue: SidebarSnapshot = EMPTY_SIDEBAR_SNAPSHOT;
   private inflight: Promise<SidebarSnapshot> | null = null;
@@ -186,6 +247,30 @@ export class SidebarModel {
     };
   }
 
+  /** Apply a same-user realtime DM counter without refetching the full room
+   *  directory. Username is the stable DM key used by the sidebar model. */
+  applyDmUnread(username: string, unread: number): void {
+    const key = normalizeDmUsername(username);
+    if (!key) return;
+    const normalizedUnread = Number.isFinite(unread) ? Math.max(0, Math.floor(unread)) : 0;
+    let found = false;
+    let changed = false;
+    const next = this.snapshotValue.dms.map((dm) => {
+      if (normalizeDmUsername(dm.username) !== key) return dm;
+      found = true;
+      if (dm.unread === normalizedUnread) return dm;
+      changed = true;
+      return { ...dm, unread: normalizedUnread };
+    });
+    if (!found && normalizedUnread > 0) {
+      next.push({ username: username.replace(/^@+/, ""), unread: normalizedUnread });
+      changed = true;
+    }
+    if (!changed) return;
+    this.snapshotValue = { ...this.snapshotValue, dms: next };
+    for (const listener of this.listeners) listener();
+  }
+
   /**
    * Post-mutation refresh: if a poll-triggered load is already in flight it
    * may predate the caller's writes, so wait it out and load AGAIN. Readers
@@ -219,13 +304,16 @@ export class SidebarModel {
       this.deps.fetchDms().catch(() => [] as SidebarDm[]),
       this.deps.fetchGlobalReplyUnread().catch(() => 0),
     ]);
-    const readState = await this.deps
+    const readStateReply = await this.deps
       .fetchReadState(rooms.map((room) => room.name))
       .catch(() => ({}) as Record<string, number>);
+    const { readState, mentionCounts, mentionTotal } = normalizeSidebarReadState(readStateReply);
     return buildSidebarSnapshot({
       rooms,
       spaces,
       readState,
+      mentionCounts,
+      mentionTotal,
       dms,
       globalReplyUnread,
       joinedUnread: this.deps.joinedUnread,
@@ -233,3 +321,7 @@ export class SidebarModel {
     });
   }
 }
+
+function normalizeDmUsername(username: string): string {
+  return username.trim().replace(/^@+/, "").toLowerCase();
+}

package/src/client.ts

@@ -443,9 +443,7 @@ export async function inviteRoom(
 ): Promise<RoomInviteResult> {
   // `@user` and `user` are the same person: strip the typing syntax once,
   // before either transport (the relay resolves the bare name).
-  const normalized: RoomInviteRequest = request.username
-    ? { ...request, username: request.username.trim().replace(/^@+/, "") }
-    : request;
+  const normalized = normalizeRoomInviteRequest(request);
   if (!config.webSocketCtor) {
     try {
       return await inviteRoomViaHttp(config, normalized);
@@ -463,29 +461,46 @@ async function inviteRoomViaWebSocket(
   const client = new RoomWsClient(config);
   try {
     const auth = await client.connect();
-    const requestId = randomUUID();
-    client.send({
-      type: RoomClientMessageType.INVITE,
-      payload: {
-        requestId,
-        room: request.room,
-        ...(request.username ? { username: request.username } : {}),
-        ...(request.userId ? { userId: request.userId } : {}),
-      },
-      timestamp: Date.now(),
-    });
-    const invited = await client.waitFor(
-      RoomServerMessageType.ROOM_INVITED,
-      (msg) => msg.payload.requestId === requestId,
-      undefined,
-      requestId,
-    );
-    return { auth, invite: invited.payload };
+    return { auth, invite: await inviteRoomOnClient(client, request) };
   } finally {
     client.close();
   }
 }
 
+/** Invite over an already-authenticated socket. Long-lived GUI/TUI sessions
+ * use this path so a one-shot invite cannot create a second connection. */
+export async function inviteRoomOnClient(
+  client: RoomWsClient,
+  request: RoomInviteRequest,
+  timeoutMs?: number,
+): Promise<RoomInvitedPayload> {
+  const normalized = normalizeRoomInviteRequest(request);
+  const requestId = randomUUID();
+  client.send({
+    type: RoomClientMessageType.INVITE,
+    payload: {
+      requestId,
+      room: normalized.room,
+      ...(normalized.username ? { username: normalized.username } : {}),
+      ...(normalized.userId ? { userId: normalized.userId } : {}),
+    },
+    timestamp: Date.now(),
+  });
+  const invited = await client.waitFor(
+    RoomServerMessageType.ROOM_INVITED,
+    (msg) => msg.payload.requestId === requestId,
+    timeoutMs,
+    requestId,
+  );
+  return invited.payload;
+}
+
+function normalizeRoomInviteRequest(request: RoomInviteRequest): RoomInviteRequest {
+  return request.username
+    ? { ...request, username: request.username.trim().replace(/^@+/, "") }
+    : request;
+}
+
 export async function removeRoomMember(
   config: RoomClientConfig,
   request: RoomRemoveMemberRequest,

package/src/shared/rooms-protocol.ts

@@ -370,6 +370,16 @@ export interface RoomReadStatePayload {
    *  Present when the store surfaces it and on ROOM_SET_ATTENTION acks
    *  (which reply READ_STATE scoped to the one room, readState empty). */
   attention?: Record<string, RoomTopicAttention> | undefined;
+  /** Unread mention counts by room, server-computed from the notify
+   *  worker's ROOM_MENTION rows so badges survive reload and clear through
+   *  the ack path. Unlike readState/attention the map is SPARSE AND
+   *  GLOBAL: every room with a nonzero count appears (requested or not),
+   *  zero-count rooms are absent. Missing on servers older than the
+   *  mentions-completion store. */
+  mentionCounts?: Record<string, number> | undefined;
+  /** User-wide unread mention total (drives the app badge). Rides beside
+   *  mentionCounts; missing on older servers. */
+  mentionTotal?: number | undefined;
   requestId?: string | undefined;
 }
 

package/src/social-client.ts

@@ -18,6 +18,7 @@ import type {
   RoomFollowResult,
   RoomFriend,
   RoomFriendRequests,
+  RoomNotificationInboxResult,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
@@ -46,6 +47,10 @@ export type {
   RoomFriend,
   RoomFriendRequest,
   RoomFriendRequests,
+  RoomNotificationInboxItem,
+  RoomNotificationInboxResult,
+  RoomNotificationKind,
+  RoomNotificationMessageData,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
@@ -1044,6 +1049,18 @@ export async function removeSpaceMember(
   );
 }
 
+/** Leave a server as the authenticated caller. This is deliberately separate
+ * from the manager-only member-removal route so clients never send their own
+ * userId as authorization data. */
+export async function leaveSpace(
+  config: RoomSocialConfig,
+  spaceId: string,
+): Promise<{ left?: boolean }> {
+  return socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/membership`, {
+    method: "DELETE",
+  });
+}
+
 export async function changeSpaceMemberRole(
   config: RoomSocialConfig,
   spaceId: string,
@@ -1185,6 +1202,47 @@ export async function markRoomRepliesRead(
   return { markedRead: result.markedRead ?? 0 };
 }
 
+/**
+ * The chat-scoped notification inbox (GET /users/notifications): the durable
+ * rows behind mention/reply/dm/keyword pushes, newest first, room kinds only.
+ * Voucher-reachable like the rest of the chat surface (the bearer token may
+ * be an API key or a chat voucher). Pagination is the composite cursor: pass
+ * the previous page's lastCursor and lastCursorId back TOGETHER (the store
+ * rejects one without the other); unread=true filters to unread rows.
+ */
+export async function listRoomNotifications(
+  config: RoomSocialConfig,
+  options: {
+    limit?: number | undefined;
+    /** Feed a page's lastCursor back here (explicit undefined reads as
+     *  "first page", so `page.lastCursor ?? undefined` composes under
+     *  exactOptionalPropertyTypes). */
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    unread?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+  } = {},
+): Promise<RoomNotificationInboxResult> {
+  const params = new URLSearchParams();
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  if (options.cursor !== undefined) params.set("cursor", options.cursor);
+  if (options.cursorId !== undefined) params.set("cursorId", options.cursorId);
+  if (options.unread !== undefined) params.set("unread", String(options.unread));
+  const init: { signal?: AbortSignal } = {};
+  if (options.signal) init.signal = options.signal;
+  const result = await socialRequest<Partial<RoomNotificationInboxResult>>(
+    config,
+    `/users/notifications${params.size ? `?${params.toString()}` : ""}`,
+    init,
+  );
+  return {
+    notifications: result.notifications ?? [],
+    hasMore: result.hasMore ?? false,
+    lastCursor: result.lastCursor ?? null,
+    lastCursorId: result.lastCursorId ?? null,
+  };
+}
+
 export async function suggestRooms(
   config: RoomSocialConfig,
   request: RoomSuggestionRequest,

package/src/social-types.ts

@@ -192,6 +192,48 @@ export interface RoomRepliesReadResult {
   markedRead: number;
 }
 
+/** The room kinds the chat notification inbox returns (the store's
+ *  ROOM_INBOX_NOTIFICATION_TYPES). ROOM_FOLLOW rows stay out of the inbox:
+ *  follow is a push channel, not a badge source. */
+export type RoomNotificationKind = "ROOM_MENTION" | "ROOM_REPLY" | "ROOM_DM" | "ROOM_KEYWORD";
+
+/** Shared room payload on a notification row, wire names verbatim from the
+ *  store's notification schema (room_message_data). `preview` follows the
+ *  push body rules (140 chars, empty for sealed content); `hash` is the
+ *  client deep link. */
+export interface RoomNotificationMessageData {
+  kind: "dm" | "mention" | "reply" | "follow" | "keyword";
+  room_id?: string;
+  room_name?: string;
+  space_id?: string;
+  conversation_id?: string;
+  seq?: number;
+  from_handle: string;
+  preview: string;
+  hash: string;
+}
+
+/** One chat notification inbox row: the store's explicit field pick
+ *  (snake_case wire names, dates as ISO strings, room_message_data only
+ *  when the row carries one). */
+export interface RoomNotificationInboxItem {
+  id: string;
+  type: RoomNotificationKind;
+  created_at: string;
+  read_at: string | null;
+  room_message_data?: RoomNotificationMessageData;
+}
+
+/** A newest-first inbox page plus the composite cursor naming the last row
+ *  returned; feed lastCursor and lastCursorId back together to request the
+ *  next page. Both are null on an empty page. */
+export interface RoomNotificationInboxResult {
+  notifications: RoomNotificationInboxItem[];
+  hasMore: boolean;
+  lastCursor: string | null;
+  lastCursorId: string | null;
+}
+
 /** A living markdown doc scoped to a space (head state; content on demand). */
 export interface RoomDoc {
   docId: string;