# Profiles

Click someone anywhere in the lobby and their profile card opens, the way it
does in Discord. This page covers the card, the full profile, the image
viewer, the API behind them and the privacy and permission rules they follow.

- [Where the card opens](#where-the-card-opens)
- [What the card shows](#what-the-card-shows)
- [What you can do from it](#what-you-can-do-from-it)
- [The full profile](#the-full-profile)
- [The image viewer](#the-image-viewer)
- [The profile API](#the-profile-api)
- [Profile fields](#profile-fields)
- [Mentions](#mentions)
- [Live updates](#live-updates)
- [Privacy](#privacy)
- [Permissions: `viewerCan`](#permissions-viewercan)
- [Accessibility](#accessibility)
- [For developers](#for-developers)
- [Not done yet](#not-done-yet)

## Where the card opens

| Place | How |
|---|---|
| Member list | Click a row. The card gets the row's live status. |
| Chat | Click the author's avatar or name, or a mention chip (`@Ada`) in a message. Bots, webhooks and apps have their own badges and no card. |
| Voice roster | Left-click a participant (shown with their photo). Right-click and the "⋮" button still open the moderator menu. |
| Direct messages | Click the header (avatar and name), or an author's avatar or name. |
| Your account block | Click your avatar to open your own card. Click your name to open the status menu, as before. |

Only one card is open at a time. Clicking another person switches the card,
and clicking the same person again closes it. A click anywhere else closes it
too.

A mention in a message opens the card of the member it names; see
[Mentions](#mentions).

## What the card shows

From top to bottom:

- **Banner.** The member's banner. Without one, a band in their profile
  colour ([Profile fields](#profile-fields)); without that, the main colour of
  their avatar. The colour is sampled from the image on a small canvas. If
  that fails, the band takes the colour of their highest coloured role, then
  the theme accent (`--lf-user-accent`). Only same-origin avatars are sampled:
  an external image would taint the canvas.
- **Avatar** with a status dot. The dot shows the status the member chose:
  Online, Idle, Do Not Disturb, or Offline. When you look at your own card,
  Offline reads Invisible, because that is what you picked. Being in voice is
  shown separately, as an "In voice" badge.
- **Names**, Discord's way: the name this community sees (the nickname, if
  there is one) in large type, and the account's own name under it when a
  nickname replaces it. Under the names, `@handle · pronouns` when the member
  set them. Then a Guest badge, a crown for the community owner, and the
  custom status as a speech bubble. A profile colour also draws a thin ring at
  the edge of the photo.
- **About me**: the bio, or "No bio yet.".
- **Member since**: when the LobbyForge account was created and when they
  joined this community. Both dates are in the viewer's language
  (`Intl.DateTimeFormat`).
- **Roles**: chips with each role's colour dot or icon, highest first,
  without `@everyone`.
- **Mutual communities**: the count and the first few icons. This section
  appears only when you share a community other than this one, so on a
  single-community self-host it does not appear.
- **Volume**: your local volume for this member, while they are in voice.
- **Message @name**, and a **View full profile** link.

The card opens at once with what the lobby already rendered: name, avatar,
bio, status text and roles. Then it fills in from the profile API, with grey
placeholders for the parts still loading.

- **Status and "In voice"** come from the opener only when it knows them
  live. The member list knows the live status, and the voice room knows who
  is in it. Every other opener takes both from the API, because the page's
  own copy is stale.
- **Cache.** Answers are cached per (community, member) for the browser
  session. The cache belongs to one viewer: it empties when someone else
  signs in on the same tab.
- **Refreshing.** A cached answer shows at once. If it is older than 30
  seconds, the card asks again in the background. It always asks again for
  your own card, since you may have just edited it.
- **After a change** made through the card (roles, a timeout, a block), that
  one profile reloads.
- **The member list follows.** Every fresh answer from the profile API
  (not one read from the cache) hands the member's roles to the lobby's
  member list, which is otherwise the page render's. A role added or removed
  in the card moves the member to the right role heading, with the right
  name colour, at once, instead of on the next page load
  (`memberRoles` in `ProfileCardProvider`).

## What you can do from it

Every action goes through a route that already existed. The card only shows
what [`viewerCan`](#permissions-viewercan) allows, and the route checks
everything again.

| Action | Route | Shown when |
|---|---|---|
| Message @name: type, press Enter | `POST /api/dm`, then `POST /api/dm/{id}/messages`. The conversation then opens in the centre column, titled with the account's name like the DM list. | `viewerCan.message`: not yourself, and not someone you blocked. If they blocked you, the DM route refuses with "You can't message this member." |
| Copy user ID | — | always |
| Block / Unblock | `POST /api/settings/me/blocks`, `DELETE …/{userId}` (BlockListProvider) | not yourself |
| Add role (+), remove role (×) | `PUT /api/servers/{id}/members/{userId}/role` with the whole new set, `@everyone` kept | `viewerCan.manageRoles`, and only the roles listed |
| Timeout / Remove timeout | `PUT /api/servers/{id}/members/{userId}/timeout` | `viewerCan.timeout` |
| Kick | `DELETE /api/servers/{id}/members/{userId}` | `viewerCan.kick` |
| Ban, with an optional reason | `POST /api/servers/{id}/bans` | `viewerCan.ban` |
| Server mute / unmute | `POST /api/servers/{id}/channels/{ch}/members/{userId}/voice/mute` | `viewerCan.serverMute`, while the member is in your voice room |
| Edit profile | link to `/settings/profile` | your own card |
| Set your status | the voice provider's presence status | your own card |

Timeout, Kick and Ban ask first. A timeout can last 60 seconds, 5 or 10
minutes, 1 hour, 1 day or 1 week. The admin Members page has no timeout
control, so these are Discord's own lengths, all under the route's 28-day
cap. The ban reason is optional and up to 512 characters, like the admin
page's prompt. A refusal shows inside the dialog, or under the roles, in the
viewer's language. The message comes from the route's `code`
(`insufficient_rank`, `actor_timed_out`, `target_is_owner`, …), never from its
English `error` (`lib/profile-action-errors.ts`). The kick, ban, role and
timeout routes give their own refusals a code too (`unauthenticated`,
`server_not_found`, `invalid_request`, `already_banned`, `role_above_actor`,
`ungrantable_permissions`, …); the admin Members page says them the same way. A member who is kicked or
banned leaves the member list at once, and a short notice says so.

Because the role route replaces the whole set, the card reads the member's
roles fresh right before each change and applies the edit to that set. A set
built from an answer cached minutes ago would quietly undo a role that
another moderator, or the admin Members page, gave in the meantime.

## The full profile

"View full profile" (or the mutual communities row) opens a larger modal with:

- the banner and avatar (both open the image viewer);
- the names, the status and the custom status;
- **About**: the bio, Member since and Roles, with the same role controls as
  the card;
- **N mutual communities**: each community with its icon and name. Each one
  is a link to `/lobby?server={id}`, and the current one is marked "This
  community".

The "⋯" menu holds the same actions as the card's. Arrow keys, Home and End
move between the tabs.

## The image viewer

`components/ImageLightbox.tsx` is a shared, generic viewer. Profiles use it
for avatars and banners, and chat image attachments can use it later.

- It shows the image centred on a dimmed backdrop, up to about 80 vmin, with
  a short zoom-in. There is no animation under `prefers-reduced-motion` or
  the app's own reduced-motion setting (`.lf-zoom-in` in `globals.css`).
- Escape, a click on the backdrop, or the X closes it. Focus stays inside and
  then returns to the avatar or banner that opened it.
- The image's alt text says whose avatar or banner it is.
- "Open original" opens the same-origin image URL in a new tab.

## The profile API

```
GET /api/servers/{serverId}/members/{userId}/profile
```

The route uses `withApiSecurity`, needs a session and is limited to 120
requests a minute. The answer has `Cache-Control: no-store`.

```jsonc
{
  "profile": {
    "userId": "…",
    "displayName": "Ace",                 // nickname, else the account's name
    "globalDisplayName": "Alice",
    "nickname": "Ace",                    // or null
    "avatarUrl": "/api/users/…/avatar?v=…", // versioned URL, or null
    "bannerUrl": "/api/users/…/banner?v=…", // versioned URL, or null
    "isGuest": false,
    "username": "ace",                    // the handle, or null — shown like a name
    "statusText": "Building",             // custom status, or null
    "bio": "…",                           // or null
    "pronouns": "she/her",                // or null (unset, or withheld when limited)
    "accentColor": "#5865f2",             // profile colour, or null (unset, or withheld when limited)
    "presence": "idle",                   // online | idle | dnd | offline, or null
    "inVoice": false,                     // in a voice room of this community the viewer can see
    "roles": [{ "id": "…", "name": "Mods", "color": "#ff8800", "icon": "shield", "position": 10, "displaySeparately": true }],
    "memberSince": "2026-02-03T04:05:06.000Z",      // or null
    "accountCreatedAt": "2025-01-02T03:04:05.000Z", // or null
    "mutualServers": [{ "id": "…", "name": "…", "iconUrl": null }],
    "mutualServerCount": 2,
    "blockedByMe": false,
    "limited": false,          // details withheld: a hidden profile, or a block either way (which, is not said)
    "isOwner": false,          // the member owns this community
    "timedOutUntil": null      // ISO time, only for viewers who may time the member out
  },
  "viewerCan": {
    "isSelf": false,
    "message": true,
    "kick": false, "ban": false, "timeout": false, "serverMute": false,
    "manageRoles": false,
    "assignableRoles": [],     // roles the viewer may add, highest first
    "removableRoleIds": [],    // roles the viewer may remove
    "currentRoleIds": []       // every role held, @everyone included (the role PUT replaces the set)
  }
}
```

**Access.** The viewer must be the owner or a current member of the server,
and the subject must be a current member: a live account, a live server, and
no active ban (a membership row that outlived a ban does not count). If any
of this fails, or the ids are malformed, the answer is the same 404. The route
can't be used to find out who belongs where.

- **Roles** are the ones the member holds in this server: the join table plus
  the legacy primary role, highest first, without `@everyone` and without
  their permissions. `displaySeparately` says whether online holders get
  their own heading in the member list.
- **Presence** goes through the same projection as `GET /api/presence`
  (`applyPresencePrivacy`). A hidden online status, a heartbeat older than 90
  seconds, no heartbeat at all, or the Invisible choice all read as
  `offline`. If Redis is down, presence also reads `offline`, not an error.
- **In voice** follows the member list's rule. The member must be in a voice
  or stage channel of this community that the viewer can see, with a status
  the viewer may see. A role-gated room the viewer can't see counts as not
  in voice.
- **Mutual communities** are the communities both people currently belong to,
  on a live server, where neither has an active ban. There is no list for
  your own profile. The answer names up to 50 of them, and the count covers
  all of them. Icons are passed only as https URLs, never as data URLs. The
  viewer is a member of every community listed, so the list reveals nothing
  new.

The database half lives in `packages/db/src/queries/memberProfiles.ts`:
`getMemberProfileRecord` and `listMutualServers`.

## Profile fields

Migration 0050 adds three columns to `users`, edited in Settings → Profile
and shown on the card. All three are nullable: every account from before
0050, and every guest, simply has none.

| Field | Rules | Shown |
|---|---|---|
| **Handle** (`username`) | 2–32 of `a-z 0-9 _ .`, stored lowercase, unique (a unique constraint plus a format CHECK). No leading, trailing or doubled dot. Reserved: `everyone`, `here`, `admin`, `administrator`, `moderator`, `mod`, `owner`, `system`, `lobbyforge`, `support`, `staff`, `bot`, `webhook`. Guests can't take one. | `@handle` under the names, always (a name, like the display name). Typed in chat it is a mention. |
| **Pronouns** | Free text, at most 40 characters, no control characters, whitespace collapsed. | Next to the handle — withheld like the bio. |
| **Profile colour** (`accent_color`) | `#rrggbb`, stored lowercase (a CHECK). Twelve swatches, any colour from the picker, or Automatic. | The card's band without a banner, and the ring around the photo — withheld like the bio. |

The settings page checks a handle while you type: the format rules at once,
then `GET /api/users/me/username?name=…` after a short pause (60 a minute;
handles are visible to fellow members anyway). The page shows a preview of
the band, the photo ring, the name and `@handle · pronouns`.

`PATCH /api/users/me/profile` takes `username`, `pronouns` and `accentColor`
next to the old fields (`null` or an empty string clears one). Refusals carry
a code the page translates: `username_too_short`, `username_too_long`,
`username_characters`, `username_dots`, `username_reserved`,
`username_guest` (403), `username_taken` (409), `pronouns_too_long`,
`pronouns_characters`, `accent_color_invalid`, `invalid_profile`.

**Community nicknames.** Settings → Profile → "Server-specific" lists every
community the account is in and edits the nickname of the one picked; the
profile card's "Edit profile" opens it on the card's community
(`/settings/profile?server=…`). `PATCH /api/users/me/server-profile` takes
`serverId` and checks the membership (`409 no_community` otherwise). Before,
the nickname always went to the account's newest community, whatever lobby it
was set from.

## Mentions

A message's text stays plain (`hi @Ada Lovelace`), so bots, notifications and
older clients read it as before. Who a mention names is kept beside it, in
`metadata.mentions`: `[{ "userId": "…", "text": "Ada Lovelace" }]`, where
`text` is what follows the `@`. Only the server writes it
(security-review AUTHZ-008 still refuses client metadata):

- the composer sends `mentions: [userId…]` — the members picked from the `@`
  list whose name is still in the text;
- the messages route (post and edit) keeps a pick only if it is a current
  member whose nickname, account name or handle stands as `@…` in the text,
  and adds every typed `@handle` of a current member
  (`lib/message-mentions-server.ts`). One entry per member and spelling: a
  member picked as `@Ada Lovelace` and also typed as `@ada_l` is two chips
  (and still one notification). An edit keeps the earlier mentions whose
  names are still there. At most 20.

The lobby turns each stored `@text` into a chip that opens that member's card,
marks `@everyone` / `@here`, and highlights a message that names the viewer
(or pings everyone) with an amber bar, as Discord does. The `@` list matches a
handle too, and folds case the viewer's way (Turkish `İ`/`I`).

**Notifications.** Each member a new message names hears it on their own feed
(`user:{uid}`, `{ type: "mention", serverId, channelId, messageId,
fromUserId }`, `lib/mention-notify.ts`) — only if they may read that channel,
never the author, never someone who blocked the author, and with no text. The
channel list gives that channel a red badge with the count until it is
opened, and a hidden tab gets a desktop notification. Settings →
Notifications now does what it says: "Unread badge" turns the badges on or
off, "Suppress while in voice" keeps a voice room quiet, and the sound choice
plays the page's own chime, a soft pop, or nothing (`lib/notification-prefs.ts`).

## Live updates

The lobby's member rows used to be the page render's: someone who joined, a
new name or avatar, roles handed out by somebody else — all waited for a
reload. They now arrive live.

- **`members:{serverId}`** is a new gateway topic (any member may subscribe;
  a kick, ban or role change re-checks it). Its events say WHO changed, never
  what, and the gateway forwards nothing but these three shapes
  (`apps/ws-gateway/src/member-events.ts`):
  - `members-changed { userIds }` — joined, or their profile, nickname,
    roles or timeout changed;
  - `members-removed { userIds }` — left, kicked or banned;
  - `roles-changed` — a role's name, colour, icon, grouping or order changed,
    or a role was deleted.
- `lib/member-bus.ts` publishes them from every route that changes those
  things (join paths, kick and leave, ban, timeout, role assignment, role
  edit and delete, nickname, and the account's own profile, avatar and banner
  — which reach every community it belongs to).
- `LiveMembersProvider` re-reads exactly the named rows from
  `GET /api/servers/{id}/lobby-members?ids=…` (projected for the viewer like
  the page render; owner or member only; up to 100 ids; `missing` lists those
  no longer members), or everyone after `roles-changed` or when the topic
  goes live. The member list, the profile card (an open card re-reads), chat
  author names, the mention list and the voice roster all read these rows;
  status stays the presence feed's.
- **DMs.** A DM message also tells both participants' feeds
  (`{ type: "dm_activity", channelId, fromUserId }`, no text). The sidebar's
  DM list re-reads `GET /api/dm`, so a conversation someone else started
  appears, and one that is not open gets an unread dot until it is opened.
  The dot does not depend on catching the event: each read after the first
  compares with the one before, and a conversation that moved with the other
  person's message newest (`lastMessageFromOther` in the answer) is marked
  too — one that arrived while the socket was down, for instance.
- **Going live.** The gateway keeps no backlog and replays nothing, so a
  change made between the page render and the subscription — or while the
  socket was down — never arrives as an event. Every live surface (member
  rows, the DM list, an open channel or DM, an activity) passes `onLive` to
  `RealtimeClient.subscribe`: it is called when the gateway confirms the topic
  on a socket (the first time, and after every reconnect) and at once for a
  subscriber joining a topic that is already live, and the surface re-reads
  what it shows then. A rename made a moment after another member opened the
  lobby used to stay stale on their screen until a reload.

## Privacy

The route uses the lobby's own projection: `canViewProfile` and
`projectMemberProfile` in `lib/profile-privacy.ts`, the same functions that
build the member list. Nothing the lobby would hide comes through the API.

| | Full profile | Hidden profile (`profileVisibility` shuts the viewer out) | They blocked you | You blocked them |
|---|---|---|---|---|
| Names, handle, Guest tag, roles, owner crown | yes | yes | yes | yes |
| Avatar | yes | no | no | if the privacy setting allows (the block list's rule, `projectBlockedUser`) |
| Banner, bio, custom status, pronouns, profile colour | yes | no | no | no |
| Member since, account created | yes | no | no | no |
| Mutual communities | yes | no | no | no |
| Presence, in voice | per presence privacy | per presence privacy | per presence privacy | no (like the presence feed) |
| Message @name | yes | yes | yes (the DM route refuses) | no |
| `limited` | false | true | true | true |

- The viewer always shares this server with the member, so "Server members"
  passes. "Nobody" shuts out everyone but the member themselves. Owners and
  moderators get no bypass, the same as the member list.
- A block hides the payload in both directions.
- A member who blocked you gets exactly the answer a hidden profile gets, so
  the card is no way to find out you were blocked. `blockedByMe` is only
  your own block, which your block list already shows.
- **Two places still give a block away**, and this change does not add a
  third:
  - the DM route answers a different refusal in each direction;
  - the member list still shows the avatar and bio of someone who blocked
    you, because the lobby projects privacy, not blocks.

  Closing these is a next step.
- A block doesn't change what a moderator may do. `viewerCan` is about the
  viewer's rights, not the member's data.

## Permissions: `viewerCan`

`lib/member-capabilities.ts` works out `viewerCan` with the same rules as the
moderation gate, `authorizeModerationTarget` in `lib/member-authorization.ts`.
The gate now imports its permission map and rank comparison from this module,
so the two can't drift apart.

1. The viewer must be a member, or the owner.
2. The viewer needs the action's permission: Kick Members, Ban Members,
   Moderate Members (timeout), Manage Roles, or Mute Members (server mute).
   The owner holds every permission.
3. A timed-out viewer may do nothing. This never applies to the owner.
4. No one may act on themselves, and no one may act on the owner.
5. The owner may act on anyone else. Everyone else must rank strictly above
   the member: equal rank can't act on equal rank.

Role assignment adds the role route's own rules. A non-owner may hand out
only roles strictly below their highest role, and only roles whose
permissions they could grant themselves. Nobody but the owner can grant
`administrator` (`lib/role-grant-policy.ts`). `@everyone` is never offered
and never removed.

## Accessibility

- The card is a dialog named "{name} profile". Focus moves into it when it
  opens, stays inside on Tab and Shift+Tab, and returns to whatever opened it
  when you close it with Escape or the X (`lib/use-focus-trap.ts`). Escape
  closes the card even when focus is somewhere else, unless another dialog
  or menu has it. Until the card is placed it is only transparent, never
  `visibility: hidden`, so it can take focus as soon as it opens.
- The full profile, the image viewer and the confirmations are modal dialogs
  with the same focus handling. Escape closes only the topmost one. In the
  "⋯" menu and the role list, Escape closes only that menu or list.
- Every action works from the keyboard. The menus use arrow keys, Home and
  End, and the role list also uses Enter. The chat avatar is a second way to
  the same card as the author's name, so it is left out of the tab order and
  hidden from screen readers.
- Status is never shown by colour alone: the dot has a label, and the name
  block says the status in words.

## For developers

| File | What |
|---|---|
| `apps/web/app/api/servers/[id]/members/[userId]/profile/route.ts` | the API |
| `packages/db/src/queries/memberProfiles.ts` | one member's record, mutual communities |
| `apps/web/lib/member-capabilities.ts` | `viewerCan`, shared with the moderation gate |
| `apps/web/lib/member-profile.ts` | response types, the session cache, merging seed and answer |
| `apps/web/app/lobby/ProfileCardProvider.tsx` | the lobby's one card, `useProfileCard()`, `ProfileTrigger` |
| `apps/web/components/modals/UserProfilePopover.tsx` | the card |
| `apps/web/components/modals/FullProfileModal.tsx` | the full profile |
| `apps/web/components/modals/profile/*` | shared pieces, the "⋯" menu, the confirmations, the actions |
| `apps/web/components/ImageLightbox.tsx` | the image viewer |
| `apps/web/lib/profile-accent.ts` | the banner band's colour |
| `apps/web/lib/profile-fields.ts` | handle, pronouns and colour rules (page and route) |
| `apps/web/lib/mentions.ts`, `lib/message-mentions-server.ts`, `lib/mention-notify.ts` | mention parsing, resolution, notifications |
| `apps/web/lib/member-bus.ts`, `app/lobby/LiveMembersProvider.tsx` | live member rows |
| `apps/web/app/api/servers/[id]/lobby-members/route.ts` | member rows for the live lobby |
| `apps/ws-gateway/src/member-events.ts` | what a `members:` subscriber may receive |

To make a new place open the card, wrap the person in
`<ProfileTrigger userId={…} seed={{ displayName }}>`. Outside the live lobby
(no provider) it renders the same content without the button.

Tests:

- `app/api/servers/[id]/members/[userId]/profile/__tests__/profile.test.ts`:
  access, privacy, blocks, presence and `viewerCan`;
- `lib/__tests__/member-capabilities.test.ts`: `mayModerate` against the real
  gate over every combination of facts;
- `packages/db/src/__tests__/member-profiles*.test.ts`: unit tests, plus an
  integration test that runs with `TEST_DATABASE_URL`;
- `components/modals/__tests__/UserProfilePopover.test.tsx`,
  `components/__tests__/ImageLightbox.test.tsx` and
  `app/lobby/__tests__/ProfileCard.test.tsx`;
- `e2e/profile-card.spec.ts`, which runs against the compose stack.

## Not done yet

- **Unread marks for every message.** Channels show a badge for mentions of
  the viewer; a mark for any new message needs a per-viewer "channel
  activity" feed that respects channel visibility. The old dot (lit for a
  channel merely opened in the last seconds) is gone.
- **Mentions in DMs, from bots, of roles; `@everyone` notifications.** Member
  mentions in community channels only; an edit that adds a mention does not
  notify (Discord doesn't either).
- **Image viewer for chat attachments.** The viewer is generic; chat has no
  image attachments to open yet.
- **A DM with someone who is not in this community** opens a card with just
  the name and avatar from the DM. The profile API is per community.
- **The two other places that give a block away**: the DM route's two
  refusals, and the member list's profile fields (see [Privacy](#privacy)).
- **A role-set precondition.** The role route has no `expectedRoleIds` check
  (answering 409 on a mismatch). The card works around this by reading the set
  fresh before each change, but two changes at the very same moment could
  still race.