Add presence indicators and a manual "appear offline" override (#36)

Every avatar in the app (chat messages, room member list, your own
avatar in the top bar/profile, the admin user list, the room-invite
search) now shows a green/red presence dot. Also adds a global
"Appear offline" toggle in the account menu, letting a user lurk in a
room undetected -- it overrides the real connection state everywhere,
not per-room.

Backend: new GlobalPresence (backend/app/ws/global_presence.py), a
cross-instance Redis-backed connection tracker parallel to the
existing per-room Presence, incremented/decremented on WS connect/
disconnect. A new users.appear_offline column (migration
f0f6e494454a) always wins over actual connection state when computing
displayed status. RoomMemberRead gained a computed `status` field;
add_member/change_member_role/list_room_members all compute it via a
shared _member_status() helper. Connect/disconnect and profile
updates (display_name, avatar, appear_offline) all broadcast
member_updated to every room the user belongs to, reusing the
broadcast infrastructure from the earlier avatar-staleness fix, so
chat surfaces update live with no new WS envelope type needed. A new
GET /api/users/online gives the admin list and user-search a snapshot
(deliberately not live -- see backend/app/routers/users.py) for
surfaces where "accurate as of page load" is good enough.

Frontend: UserAvatar renders an optional status dot; every call site
threads status/appear_offline through from whichever data source it
already has (room members, the current user, or the new online-ids
snapshot for admin/search).

4 new backend tests (backend/tests/test_presence.py); existing
broadcast-adjacent WS tests updated to tolerate the new member_updated
noise on connect. Verified end-to-end in the browser with two real
users: presence dot flips live on connect/disconnect via the existing
room-broadcast channel, and the lurk toggle correctly forces offline
while still connected.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/app/main.py

@@ -15,6 +15,7 @@ from app.routers import admin, auth, bots, health, push, rooms, signup, uploads,
 from app.ws.broadcaster import Broadcaster
 from app.ws.chat import router as ws_router
 from app.ws.connection_manager import ConnectionManager
+from app.ws.global_presence import GlobalPresence
 from app.ws.presence import Presence
 
 # backend/app/main.py -> backend/ -> repo root -- matches both the local
@@ -68,6 +69,7 @@ def create_app() -> FastAPI:
     app.state.connection_manager = ConnectionManager()
     app.state.redis = Redis.from_url(settings.redis_url, decode_responses=True)
     app.state.presence = Presence(app.state.redis)
+    app.state.global_presence = GlobalPresence(app.state.redis)
     app.state.broadcaster = Broadcaster(app.state.redis, app.state.connection_manager)
 
     app.include_router(health.router)

backend/app/models/user.py

@@ -21,6 +21,10 @@ class User(Base):
     theme: Mapped[str | None] = mapped_column(String(20))
     avatar_filename: Mapped[str | None] = mapped_column(String(64))
     avatar_content_type: Mapped[str | None] = mapped_column(String(50))
+    # Manual override for the presence indicator -- when set, this user
+    # always shows as offline to everyone regardless of actual connection
+    # state (a "lurk" mode), independent of any individual room.
+    appear_offline: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false", nullable=False)
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), nullable=False
     )

backend/app/routers/auth.py

@@ -85,11 +85,13 @@ async def update_profile(
         current_user.display_name = display_name or None
     if "theme" in updates:
         current_user.theme = updates["theme"]
+    if "appear_offline" in updates:
+        current_user.appear_offline = updates["appear_offline"]
     await db.commit()
     await db.refresh(current_user)
     # theme is private to this user, not shown to anyone else -- only
     # broadcast when something other members would actually see changed.
-    if "display_name" in updates:
+    if "display_name" in updates or "appear_offline" in updates:
         await broadcast_member_updated(db, request.app.state.broadcaster, current_user.id)
     return current_user
 

backend/app/routers/rooms.py

@@ -201,14 +201,24 @@ async def leave_room_endpoint(
         raise HTTPException(status_code=404, detail="Not a member of this room")
 
 
+def _member_status(user: User, online_ids: set[uuid.UUID]) -> str:
+    # appear_offline always wins, regardless of actual connection -- that's
+    # the whole point of the override (lurking in a room undetected).
+    return "offline" if user.appear_offline or user.id not in online_ids else "online"
+
+
 @router.get("/{room_id}/members", response_model=list[RoomMemberRead])
 async def list_room_members_endpoint(
+    request: Request,
     room_id: uuid.UUID,
     current_user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     await require_room_member(room_id, current_user, db)
     memberships = await list_room_members(db, room_id)
+    online_ids = await request.app.state.global_presence.online_user_ids(
+        [m.user_id for m in memberships]
+    )
     return [
         RoomMemberRead(
             user_id=m.user_id,
@@ -217,6 +227,7 @@ async def list_room_members_endpoint(
             avatar_filename=m.user.avatar_filename,
             role=m.role,
             joined_at=m.joined_at,
+            status=_member_status(m.user, online_ids),
         )
         for m in memberships
     ]
@@ -244,6 +255,7 @@ async def remove_member_endpoint(
 
 @router.patch("/{room_id}/members/{user_id}", response_model=RoomMemberRead)
 async def change_member_role_endpoint(
+    request: Request,
     room_id: uuid.UUID,
     user_id: uuid.UUID,
     data: RoomMemberRoleUpdate,
@@ -259,6 +271,7 @@ async def change_member_role_endpoint(
         raise HTTPException(
             status_code=400, detail="Use transfer-ownership to change the room owner"
         )
+    online_ids = await request.app.state.global_presence.online_user_ids([membership.user_id])
     return RoomMemberRead(
         user_id=membership.user_id,
         username=membership.user.username,
@@ -266,6 +279,7 @@ async def change_member_role_endpoint(
         avatar_filename=membership.user.avatar_filename,
         role=membership.role,
         joined_at=membership.joined_at,
+        status=_member_status(membership.user, online_ids),
     )
 
 
@@ -468,6 +482,7 @@ async def add_member_endpoint(
     except AlreadyMemberError:
         raise HTTPException(status_code=409, detail="That user is already a member")
     await broadcast_room_added(request.app.state.broadcaster, data.user_id, room)
+    online_ids = await request.app.state.global_presence.online_user_ids([membership.user_id])
     return RoomMemberRead(
         user_id=membership.user_id,
         username=membership.user.username,
@@ -475,6 +490,7 @@ async def add_member_endpoint(
         avatar_filename=membership.user.avatar_filename,
         role=membership.role,
         joined_at=membership.joined_at,
+        status=_member_status(membership.user, online_ids),
     )
 
 

backend/app/routers/users.py

@@ -1,6 +1,6 @@
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import FileResponse
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -27,6 +27,25 @@ async def list_users_directory_endpoint(
     return list(result.scalars().all())
 
 
+@router.get("/online", response_model=list[uuid.UUID])
+async def list_online_users_endpoint(
+    request: Request,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> list[uuid.UUID]:
+    """A snapshot, not a live feed -- deliberately simpler than the presence
+    dot in chat (which updates live via the existing room-broadcast
+    machinery). Used by surfaces where "accurate as of page load" is good
+    enough: the admin user list and the room-invite user search."""
+    raw_online_ids = await request.app.state.global_presence.all_online_user_ids()
+    if not raw_online_ids:
+        return []
+    result = await db.execute(
+        select(User.id).where(User.id.in_(raw_online_ids), User.appear_offline.is_(False))
+    )
+    return [row[0] for row in result.all()]
+
+
 @router.get("/{user_id}/avatar")
 async def get_user_avatar_endpoint(
     user_id: uuid.UUID,

backend/app/schemas/room.py

@@ -1,5 +1,6 @@
 import uuid
 from datetime import datetime
+from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -43,6 +44,10 @@ class RoomMemberRead(BaseModel):
     avatar_filename: str | None
     role: RoomRole
     joined_at: datetime
+    # "offline" whenever the user has set appear_offline, regardless of
+    # actual connection -- computed by the router (needs GlobalPresence),
+    # not derivable from the model alone.
+    status: Literal["online", "offline"]
 
 
 class RoomMemberAdd(BaseModel):

backend/app/schemas/user.py

@@ -22,17 +22,20 @@ class UserRead(BaseModel):
     display_name: str | None
     theme: str | None
     avatar_filename: str | None
+    appear_offline: bool
     created_at: datetime
 
 
 class ProfileUpdate(BaseModel):
-    # Both fields are independently optional-and-settable -- the router
-    # only applies keys actually present in the request body
+    # Each field is independently optional-and-settable -- the router only
+    # applies keys actually present in the request body
     # (model_dump(exclude_unset=True)), so a call that only wants to change
-    # the theme doesn't clobber display_name back to None, and vice versa.
+    # the theme doesn't clobber display_name (or appear_offline) back to
+    # their defaults, and vice versa.
     display_name: str | None = Field(default=None, max_length=50)
     # Kept in sync with frontend/src/styles/themes.css's theme blocks.
     theme: Literal["dark", "light", "midnight", "sunset"] | None = Field(default=None)
+    appear_offline: bool | None = Field(default=None)
 
 
 class UserDirectoryRead(BaseModel):

backend/app/ws/chat.py

@@ -9,6 +9,7 @@ from app.database import get_db
 from app.models import ApiToken, Message, MessageFile, MessageImage, RoomMembership, User
 from app.services.bot_service import resolve_token
 from app.services.message_events import (
+    broadcast_member_updated,
     broadcast_message_update,
     broadcast_new_message,
     broadcast_reaction_update,
@@ -76,9 +77,17 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
     await websocket.accept()
     manager = websocket.app.state.connection_manager
     presence = websocket.app.state.presence
+    global_presence = websocket.app.state.global_presence
     broadcaster = websocket.app.state.broadcaster
     joined_rooms: set[uuid.UUID] = set()
     manager.register_user(user.id, websocket)
+    # Only broadcast on a genuine offline->online transition (this user's
+    # first open connection), not for every extra tab -- broadcast_member_
+    # updated tells every room this user's in to refresh, which would be
+    # wasted churn on a transition that didn't actually change anything
+    # visible.
+    if await global_presence.connect(user.id):
+        await broadcast_member_updated(db, broadcaster, user.id)
 
     try:
         while True:
@@ -229,3 +238,5 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
         manager.unregister_user(user.id, websocket)
         for room_id in joined_rooms:
             await presence.leave(room_id, user.id)
+        if await global_presence.disconnect(user.id):
+            await broadcast_member_updated(db, broadcaster, user.id)

backend/app/ws/global_presence.py

@@ -0,0 +1,51 @@
+import uuid
+
+from redis.asyncio import Redis
+
+
+class GlobalPresence:
+    """Cross-instance "does this user have the app open at all right now,"
+    independent of which (if any) room they currently have open -- backing
+    the online/offline presence dot shown wherever a user's avatar renders.
+    A single Redis hash (field = user_id, value = connection refcount),
+    parallel to but separate from Presence's per-room hashes.
+
+    Refcounted for the same reason as Presence: multiple tabs/instances for
+    one user shouldn't flip them offline until the last connection closes.
+    """
+
+    def __init__(self, redis: Redis) -> None:
+        self._redis = redis
+
+    def _key(self) -> str:
+        return "presence:global"
+
+    async def connect(self, user_id: uuid.UUID) -> bool:
+        """Returns True iff this was the user's first open connection --
+        a genuine offline->online transition worth telling anyone about."""
+        count = await self._redis.hincrby(self._key(), str(user_id), 1)
+        return count == 1
+
+    async def disconnect(self, user_id: uuid.UUID) -> bool:
+        """Returns True iff this was the user's last open connection -- a
+        genuine online->offline transition."""
+        key = self._key()
+        field = str(user_id)
+        remaining = await self._redis.hincrby(key, field, -1)
+        if remaining <= 0:
+            await self._redis.hdel(key, field)
+            return True
+        return False
+
+    async def is_online(self, user_id: uuid.UUID) -> bool:
+        return await self._redis.hexists(self._key(), str(user_id))
+
+    async def online_user_ids(self, user_ids: list[uuid.UUID]) -> set[uuid.UUID]:
+        if not user_ids:
+            return set()
+        values = await self._redis.hmget(self._key(), [str(u) for u in user_ids])
+        return {uid for uid, v in zip(user_ids, values) if v is not None}
+
+    async def all_online_user_ids(self) -> set[uuid.UUID]:
+        fields = await self._redis.hkeys(self._key())
+        return {uuid.UUID(f) for f in fields}