CONTEXT.md

Ubiquitous Language

Each entry: Term: definition. Avoid: words not to use for it.

Rooms & Conversations

• Room: server-side conversation container with shared state (name, type, settings). Avoid: Chat, conversation
• Subscription: a user's relationship to a Room, holding per-user state (unread count, favorite, muted, open); never a DDP Subscription. Avoid: Membership, room entry
• Room Membership: exactly one of:
  • Subscribed Room: Subscription exists, status not invited. Avoid: Joined room
  • Invited: Subscription exists, status invited, not yet accepted
  • Preview Mode: no Subscription; Room data comes from navigation params or a REST lookup; lasts until the user joins
  • Avoid: Joined flag, membership
• Channel: public Room (type 'c'). Avoid: Public room
• Group: private Room (type 'p'), invited members only. Avoid: Private room, private channel
• Direct Message: 1-on-1 private Room (type 'd'). Avoid: DM, PM, private message
• Thread: branched conversation spawned from one Message, identified by tmid. Avoid: Reply chain
• Discussion: a full Room spawned from a parent Room, identified by prid. Avoid: Sub-room, sub-channel
• Team: groups Channels and users; has one main Room. Avoid: Workspace (a different thing)
• Broadcast Room: only authorized users send; others can only Reply Broadcast (reply to an existing Message). Avoid: Broadcast channel / Broadcast reply

Messages

• Message: unit of communication in a Room (rid); _id, content in msg, parsed markdown in md. Avoid: Chat message, text
• Thread Message: Message with tmid. Avoid: Reply, thread reply
• Thread Parent: the Message its Thread Messages' tmid points at. Avoid: Thread root, parent message
• Attachment: media or structured data in a Message (image, video, audio, file, action buttons). Avoid: File, media
• Reaction: emoji response tracking which usernames reacted. Avoid: Emoji reaction
• Mention: @username reference that triggers notifications. Avoid: Tag, ping
• Draft Message: unsent composition on a Subscription or Thread (draftMessage). Avoid: Unsent message
• Snippet: saved excerpt from a Message

System Messages

Server-generated Messages carrying a t type field. Room-event and typed-event System Messages are separate rendering branches.

• System Message: umbrella for any t-bearing Message. Avoid: Event, notification
• Info Message: room event (joined, archived, role changed, muted), compact and non-interactive. Excludes the typed events below. Avoid: System event, event message
• Discussion-Created Message: t = 'discussion-created'; links to the new Discussion Room
• Call Message: t = 'jitsi_call_started' or t = 'videoconf'; records a Video Conference with a join affordance. Avoid: Video call message
• Encrypted Message: t = 'e2e', pending decryption (e2e !== 'done'); "Encrypted message" placeholder. Avoid: Pending E2E message

Content & Visibility States

• Ignored User: User the current user hid in one Room (room.ignored). Avoid: Muted user
• Ignored Message: Message by an Ignored User; "Message ignored" placeholder, revealed per-Message and ephemerally on tap. Avoid: Muted message
• Auto-Translate: per-Room setting translating other users' Messages. Avoid: Live translate
• Translated Message: Message shown via its auto-translated text. Avoid: Auto-translated message
• Blocks Message: body is Blocks from a Rocket.Chat App, rendered instead of markdown. Avoid: App message
• Message Preview: Message rendered outside its Room (search, pinned, share extension, notifications); no interactions, reactions, or thread context. Avoid: Preview row

Message Grouping

• Message Header: author block (avatar, name, timestamp) on the first Message of a run. Avoid: Title, byline
• Grouped Message: continues a same-author run within the Grouping Period, no Header. Avoid: Sequential, collapsed
• Grouping Period: max gap for same-author Messages to share a Header (Message_GroupingPeriod)
• Previous Message: the adjacent older Message; a Message's Header is derived from it (author, time, status, thread). Avoid: Prior message, neighbor

Message Status & Flags

Status (status) is the delivery lifecycle, exactly one at a time: Sent (0, avoid Delivered), Temp (1, local, unconfirmed; avoid Pending, sending), Error (2; avoid Failed).

Message Flags are independent of Status and of each other:

• Pinned: important for the whole Room, in the pinned list. Avoid: Bookmarked
• Starred: personal bookmark, visible only to that user. Avoid: Saved

Message Separators

• Date Separator: inline divider between Messages on different days. Avoid: Date divider
• Floating Date Separator: overlay with the topmost visible Message's date while scrolling. Avoid: Sticky date
• Unread Separator: between last read and first unread Message, anchored by Last Seen. Avoid: Unread divider

Message Loading

• Message Window: the range of Messages the Room view observes and renders (not what is synced). Avoid: Page, feed
• Live Tail: newest end of a Room's Messages. Avoid: Bottom, latest
• Live Window: Message Window ending at the Live Tail; the default; follows new Messages
• Anchored Window: Message Window around a Jump to Message target; does not follow new Messages
• Chunk: contiguous run of Messages synced locally, bracketed by Loader Rows where more exists. Avoid: Batch, page
• Gap: Messages on the server but not local, between Chunks; marked by a Loader Row. Avoid: Hole
• Loader Row: placeholder Message record marking a Gap; visible → server fetch. Avoid: Load-more, spinner row
• Older Loader: types MORE, PREVIOUS_CHUNK. Avoid: Load previous
• Newer Loader: type NEXT_CHUNK. Avoid: Load next
• Room History: older Messages fetched on demand (roomHistoryRequest, ROOM.HISTORY_REQUEST). Avoid: Message history
• Jump to Message: re-position the Room view onto a target Message, fetching a surrounding Chunk (loadSurroundingMessages) bracketed by Older/Newer Loaders. Avoid: Scroll to message

Timestamp Trust Boundary

• Server Timestamp: _updatedAt from a server response. Avoid: Timestamp (ambiguous)
• Device Timestamp: _updatedAt on a WatermelonDB row written by the device clock (offline/Temp/Error sends, push-inserted rows, normalizeMessage's _updatedAt || new Date() fallback). Never a cursor. Avoid: Timestamp (ambiguous)
• Last Open: Subscription fetch cursor (lastOpen column), the newest Server Timestamp received for the Room. Take it from the raw payload before normalizeMessage / buildMessage; never from a database row or Date.now(). Avoid: last open, last update
• Last Seen: read receipt (ls). Avoid: last read

A Last Open too low costs a re-fetch; too high and the server never delivers the change. Prefer the lower cursor. Using one column as both Last Open and Last Seen produced permanently invisible Messages.

Message Action & Position State

• Message Action State: the active Message Action and its target Message(s), or null. Owner: per-Room MessageActionStore; scope: that Room's Message rows and composer
• Message Action: exactly Quote (one or more Messages into the composer; avoid Multi-quote), Edit (one own Message; avoid Editing), or React (one Message, reaction picker; avoid Reacting). Selection lives inside it. Replying is not a Message Action
• Positional State: highlighted Message plus jump/scroll position, split across:
  • Jump orchestration: decide, resolve anchor, request. Owner: RoomView (useJumpToMessage)
  • Scroll and highlight execution: scroll and render highlight. Owner: the List component

Emojis

Reactions and the frequently used table store emoji by name, never glyph. An unresolvable name renders as literal :shortname:, so names are only ever added to the resolvable set. Dataset generation: emojis.

• Shortname: colon-wrapped :name: in Message text and a Reaction's emoji; the only form useShortnameToUnicode resolves. Avoid: Emoji code, emoji id
• Listed Name: the one Shortname per listed emoji the picker shows (emojisByCategory) and search returns. Avoid: Canonical name, primary
• Alias: another Shortname for the same emoji; searchable, answered with the Listed Name (water_wave finds ocean). Avoid: Synonym, alternate name
• Legacy Shortname: hand-maintained, absent from the dataset, resolved by fallback for older clients. Avoid: Deprecated name, old name
• Pinned Shortname: held at a previous release's glyph at generation time (scripts/pinned-shortnames.js) when upstream reassigns it. Avoid: Override, frozen name
• Custom Emoji: Workspace-uploaded image, stored by name plus extension. Avoid: Custom reaction, sticker

Users & Roles

• User: server identity with username, status, roles. Avoid: Account, profile
• Logged User: current session, auth token, preferences. Avoid: Current user, session
• Role: named permission group (owner, moderator, leader, guest). Avoid: Permission group
• Permission: named capability mapped to Roles. Avoid: Privilege, access right
• Active User: tracked via real-time presence. Avoid: Online user
• Member: User in a Room's membership list. Avoid: Participant
• User Status: Online (avoid Active), Away (idle; avoid Idle), Busy (do-not-disturb; avoid DND), Offline (avoid Disconnected)

Omnichannel / Livechat

• Omnichannel Room: type 'l', one Visitor with zero or one Agent. Avoid: Livechat room, support chat
• Visitor: external customer, identified by token. Avoid: Client, customer, end-user
• Agent: User handling Omnichannel, with statusLivechat; belongs to Departments. Avoid: Support agent, operator, rep
• Inquiry: queued request; becomes an Omnichannel Room when picked up. Avoid: Queue item, ticket
• Department: groups Agents for routing. Avoid: Team (ambiguous), group
• Omnichannel Source: widget, email, sms, app, api. Avoid: Channel origin
• Served By: the assigned Agent. Avoid: Assigned agent, handler
• On Hold: paused by the Agent. Avoid: Paused, suspended
• Transfer: move to another Agent or Department (code also says forwardRoom). Avoid: Forward, reassign, handoff
• Routing Config: per-server settings for Return to Queue and Inquiry visibility. Avoid: Livechat config, routing settings
• Return to Queue: Agent hands the Room back as an Inquiry. Avoid: Return inquiry, release chat

Encryption

• E2E Encryption: AES-SHA2, versions rc.v1.aes-sha2, rc.v2.aes-sha2. Avoid: Encryption, E2EE
• E2E Key: user's public/private key pair. Avoid: Crypto key
• OTR: Off-The-Record ephemeral two-user mode

Video & Voice

• Video Conference: call with status calling/started/expired/ended/declined; Direct Video Conference (1-on-1) or Group Video Conference (title, anonymous users). Avoid: Video call, meeting
• VOIP: phone-style call, separate from Video Conference (ICE servers, media streams). Avoid: Phone call, voice call
• Native Accept: incoming VOIP answered by CallKit (iOS) / Telecom (Android) before JS; native sends the REST accept, JS reconciles on launch via initial events. Avoid: JS accept, app accept
• Per-call DDP: short-lived native DDP client per incoming VOIP call, separate from the app DDP session. Avoid: Native socket, side socket
• Media Signal: typed event of @rocket.chat/media-signaling (offer, answer, ICE candidate, state update) over DDP stream-notify-user, replayable via REST media-calls.stateSignals. Avoid: Signal, RTC event
• Pending Hangup: in-memory call id recorded when End is tapped on an unhealthy WebSocket; the hangup Media Signal replays through the lib's transporter on the next post-login reconnect. Avoid: Hangup intent, deferred hangup

Workspace & Connection

• Workspace: a Rocket.Chat deployment (version, settings, enterprise modules). Avoid: Server (legacy), instance
• Workspace History: previously connected Workspaces. Avoid: Recent servers
• Meteor Connect: WebSocket to the Workspace's DDP endpoint. Avoid: Socket, connection
• Socket Health: whether that socket is alive; round trip when in doubt, reopen when dead. Avoid: Staleness (stale/gray/fresh), socket probe
• DDP Subscription: server-push feed opened by name and params (stream-room-messages, stream-notify-user); the SDK derives its id from them, so identical requests share one. Avoid: Stream, DDP stream, sub

Navigation & Layout

• Outside Stack: unauthenticated screens. Avoid: Auth stack, login flow
• Inside Stack: authenticated screens. Avoid: Main stack, app stack
• Chats Stack: room list, room view, room actions within Inside Stack
• Master-Detail: tablet two-pane layout. Avoid: Split view, two-pane
• Drawer Navigator: tabs Chats, Profile, Settings, Admin, Accessibility. Avoid: Sidebar, menu

Unread & Notification Indicators

Subscription fields: Unread (count; avoid Badge count), User Mentions (@mentioned me; avoid Personal mentions), Group Mentions (@all/@here; avoid Channel mentions), Tunread (Thread IDs with unread replies; avoid Thread unread), Alert (unread mentions or activity; avoid Notification flag).

Flagged ambiguities

• Server: legacy name for Workspace, still in code (server, serversHistory, selectServer). Use Workspace in prose, new names, and copy; renaming is a migration. "Server" as the remote side (server response, server clock) stays valid.
• Room types 'e2e' and 'thread' in the SubscriptionType enum are FIXME-marked flags, not room types.
• Account: means a User, which authenticates on a Workspace.
• Channel strictly means type 'c'.
• History: Workspace History vs Room History.
• Window: Message Window is the concrete Message range.
• lastOpen: the Last Open cursor, never "when the user last opened the room" and never a read receipt.
• Load more: say Older Loader or Newer Loader.
• Thread reply: isThreadReply is a rendering position (first Thread Message of a run shown in the parent Room, with the "in reply to" header); the data concept is Thread Message.
• Preview: Message Preview (isPreview) vs PreviewContent (compact Thread Message body in the parent Room).
• Muted: a moderator mute removes send permission (user-muted/mute_unmute System Messages); an Ignored User is a personal filter.
• Reply: Reply Broadcast or Thread navigation; neither is a Message Action.
• Shortname forms: in-app APIs pass the bare name (IEmoji, emojisByCategory and aliasesByEmojiName keys, DEFAULT_EMOJIS, searchEmojiNames, the frequently used table's content, the name setReaction sends). Message text, a Reaction's emoji, and shortnameToUnicodeMap keys are colon-wrapped. formatShortnameToUnicode matches only colon-wrapped: wrap bare names before resolving, strip stored ones before name lookup.
• Pinned: Message Flag vs Pinned Shortname; unrelated.
• Alias: an emoji Alias is a valid term, unlike the Avoid lists.
• Interaction: retired; say Message Action State.