# Room Presence Feature

## Overview
Display user avatars for members currently active in each room, shown next to the room name in the room list sidebar.

## Current Implementation Status

### Existing Backend (Convex)
- `convex/presence.ts` already provides presence tracking
- `userPresence` table tracks user location with `spaceId` and `roomId`
- `getActiveInRoom` query returns users active in a specific room (within last 5 minutes)
- Presence updates happen via `update` mutation with status: "online" | "idle" | "offline"

### Current Frontend Usage
- `app/space/[id]/page.tsx` updates presence when room changes (line 224-228)
- Members list in right sidebar shows presence indicators (green/yellow/gray dots)

## New Feature: Room Presence Avatars

### Requirements
1. Show avatars of active users next to each room name in the left sidebar
2. Overlap avatars to save space (each successive avatar slightly behind)
3. Show only first 3-4 avatars, then display count (e.g., "+5")
4. On hover, expand to show more avatars or all users in tooltip

### Implementation Plan

#### 1. AvatarStack Component (`components/AvatarStack.tsx`)
Reusable component for displaying overlapping avatars:
- Takes array of user objects with avatar/name
- Props: `users`, `maxVisible` (default 3), `size` (default "sm")
- Overlapping effect via negative margin-left
- Shows count badge for overflow
- Optional: Hover state to expand or tooltip

#### 2. Update Room List (`app/space/[id]/page.tsx`)
- Query active presence for each room using `api.presence.getActiveInRoom`
- Render `AvatarStack` component next to room name
- Keep room name and # symbol visible
- Responsive layout to handle overflow

#### 3. Styling Considerations
- Avatar sizes: small (20px-24px) to fit in room list item
- Z-index stacking for overlap effect
- Border on avatars to separate from background
- Hover state for expansion/tooltip
- Dark mode support

## Technical Notes

### Performance
- Presence queries are reactive via Convex subscriptions
- Each room triggers separate query - acceptable for reasonable room counts (<50)
- Consider pagination or virtualization for large room lists

### Edge Cases
- Empty room (no active users) - show no avatars
- Single user - show one avatar without overlap
- User without avatar - show initial letter in colored circle (already implemented pattern)

## Design Mockup (Text)
```
Rooms
─────────────────────
# general    [👤👤👤]
# music      [👤👤+3]
# off-topic  [👤]
# dev        (empty)
```

With overlap:
```
# general    [👤][👤][👤]
                └──┴──┘
              (overlapping)
```

## Files Created/Modified

### New Files
- ✅ `components/AvatarStack.tsx` - Reusable avatar overlap component with configurable size
- ✅ `components/RoomListItem.tsx` - Individual room list item with presence query
- ✅ `PRESENCE.md` - This documentation file

### Modified Files
- ✅ `app/space/[id]/page.tsx` - Updated to use RoomListItem component

## Implementation Details

### AvatarStack Component
- Accepts `users` array with avatar/name/email fields
- `maxVisible` prop (default: 3) controls how many avatars to show before "+N"
- `size` prop: "xs" (20px), "sm" (24px), "md" (32px)
- Each avatar overlaps with -8px left margin and stacked z-index
- Shows user initials in gradient circle when no avatar image
- White/gray border for separation from background
- Hover title shows full name

### RoomListItem Component
- Queries `api.presence.getActiveInRoom` for each room independently
- Maps presence data to user objects compatible with AvatarStack
- **Prioritizes user profile avatars** (`profile.avatar`) over auth table images (`user.image`)
- Uses profile display names when available, falling back to auth user names
- Filters out empty user IDs
- Reactive updates via Convex subscriptions
- Shows "xs" size avatars to fit in compact room list

### Backend Changes
- Updated `convex/presence.ts` `getActiveInRoom` query to fetch user profiles
- Now returns presence objects with both `user` and `profile` fields
- Profile includes custom `avatar` field uploaded by users

## Future Enhancements
- Click avatar to @mention user
- Hover to see full names
- Show "typing" indicators
- Different icons for room leaders
- Activity indicators (speaking, creating, etc.)