feat(video-conf): show who is in a call as faces, not as a number

"2 people in the call" answers a worse question than three avatars do. What
decides whether to walk into a call is *who* is already in it.

`CallParticipants` draws a face for each of the people it is given and turns
whatever is left over into a "+N" shaped and sized like one more avatar, so a row
reads as a group of people rather than as faces followed by a statistic. The whole
count stays as the group's label — for anyone who cannot see the avatars, and
because "+2" means nothing without a total.

Two surfaces, one component:

- the sidebar list, under a `Participants` label, from `participants` on the
  joinable payload. The server caps that at three, since a call in a busy channel
  would otherwise send a roster to draw three avatars.
- the preflight when joining, under a "Participants in the call" label and five at
  a time — a screen has more room than a row. These come from the call window's own
  copy of the members, so nothing extra travels for them.

`participants` returns to the joinable payload, and `CallParticipants` to the tree;
both were cut from the first release in 12ce0c2, which recorded the design for
exactly this.

The joinable fixture now carries participants, and the spec asserts the cap, that
the payload carries nothing beyond what a face needs, and that people who were
invited but never turned up get no face.

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

Author: rodrigok

apps/meteor/client/components/CallParticipants.spec.tsx

@@ -0,0 +1,38 @@
+import { mockAppRoot } from '@rocket.chat/mock-providers';
+import { render, screen } from '@testing-library/react';
+
+import CallParticipants from './CallParticipants';
+
+const person = (username: string) => ({ _id: username, username });
+
+const renderParticipants = (props: Parameters<typeof CallParticipants>[0]) =>
+	render(<CallParticipants {...props} />, { wrapper: mockAppRoot().withJohnDoe().build() });
+
+// Faces say *who* is in the call, which is usually what decides whether to join. The count alone never did.
+it('shows a face for each of the people it was given', () => {
+	const { container } = renderParticipants({ people: [person('alice'), person('bob')], total: 2 });
+
+	expect(container.querySelectorAll('img')).toHaveLength(2);
+	expect(screen.queryByText(/^\+/)).not.toBeInTheDocument();
+});
+
+// Only a few travel with the call, so whatever is left over is a number at the end of the row.
+it('counts off the ones it has no room for', () => {
+	renderParticipants({ people: [person('alice'), person('bob'), person('carol')], total: 12 });
+
+	expect(screen.getByText('+9')).toBeInTheDocument();
+});
+
+it('still says how many there are, for anyone who cannot see the faces', () => {
+	renderParticipants({ people: [person('alice')], total: 4 });
+
+	expect(screen.getByTitle('__count__people_in_the_call')).toBeInTheDocument();
+});
+
+// An older server, or a call whose members did not travel with it.
+it('falls back to the number when there are no faces to show', () => {
+	const { container } = renderParticipants({ people: [], total: 3 });
+
+	expect(screen.getByText('__count__people_in_the_call')).toBeInTheDocument();
+	expect(container.querySelectorAll('img')).toHaveLength(0);
+});

apps/meteor/client/components/CallParticipants.tsx

@@ -0,0 +1,72 @@
+import type { IUser } from '@rocket.chat/core-typings';
+import { Box } from '@rocket.chat/fuselage';
+import { UserAvatar } from '@rocket.chat/ui-avatar';
+import { useTranslation } from 'react-i18next';
+
+type CallParticipantsProps = {
+	/** A few of the people in the call — whoever is to get a face. Capped by `CALL_FACES_SHOWN`. */
+	people: (Pick<IUser, '_id'> & Partial<Pick<IUser, 'username'>>)[];
+	/** How many are in the call altogether, which is what the "+N" is worked out from. */
+	total: number;
+	/** Avatar size, since a sidebar row and a full screen don't want the same one. */
+	size?: 'x18' | 'x24';
+};
+
+/**
+ * Who is already in a call, as faces rather than a number.
+ *
+ * Faces say *who* is in there, which is usually what decides whether to walk in; a count never did. Only a few of
+ * them are shown, so whatever is left over becomes a "+N" at the end — shaped and sized like one more avatar, so
+ * the row reads as a group of people rather than as faces followed by a statistic.
+ *
+ * The count is still there as the group's label, both for anyone who cannot see the avatars and because "+2" only
+ * means something next to a total.
+ */
+const CallParticipants = ({ people, total, size = 'x18' }: CallParticipantsProps) => {
+	const { t } = useTranslation();
+
+	const label = t('__count__people_in_the_call', { count: total });
+
+	// Nothing to show faces from — an older server, or a call whose members didn't travel with it.
+	if (!people.length) {
+		return (
+			<Box fontScale='micro' color='hint'>
+				{label}
+			</Box>
+		);
+	}
+
+	const remaining = total - people.length;
+
+	return (
+		<Box display='flex' alignItems='center' aria-label={label} title={label}>
+			{people.map(({ _id, username }, index) => (
+				// Overlapped a little, so a row of faces reads as one group rather than a list.
+				<Box key={_id} marginInlineStart={index === 0 ? 0 : -4}>
+					<UserAvatar username={username ?? ''} size={size} />
+				</Box>
+			))}
+			{remaining > 0 && (
+				// One more avatar in the row, carrying a number instead of a face. It keeps the avatar's shape and
+				// size but is allowed to grow with its digits, since a call can hold a lot of people.
+				<Box
+					marginInlineStart={-4}
+					minWidth={size}
+					height={size}
+					paddingInline={4}
+					display='flex'
+					alignItems='center'
+					justifyContent='center'
+					borderRadius='x4'
+					backgroundColor='surface-neutral'
+					color='hint'
+					fontScale='micro'
+				>
+					{`+${remaining}`}
+				</Box>
+			)}
+		</Box>
+	);
+};
+
+export default CallParticipants;

apps/meteor/client/components/OngoingCalls/CallSummary.tsx

@@ -3,6 +3,8 @@ import { Box, Icon } from '@rocket.chat/fuselage';
 import type { ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 
+import CallParticipants from '../CallParticipants';
+
 type CallSummaryProps = {
 	call: JoinableVideoConference;
 	/** Ringing calls say so in red; the rest are just calls. */
@@ -27,8 +29,13 @@ const CallSummary = ({ call, ringing, children }: CallSummaryProps) => {
 				<Box fontScale='p2b' color='default' withTruncatedText>
 					{call.name}
 				</Box>
-				<Box fontScale='micro' color='hint'>
-					{t('__count__people_in_the_call', { count: call.usersCount })}
+				{/* Named as well as shown: under a call's title, a bare row of faces is a row of faces of nobody in
+				    particular until you know it is the people already in there. */}
+				<Box display='flex' alignItems='center' style={{ gap: 4 }}>
+					<Box fontScale='micro' color='hint' flexShrink={0}>
+						{t('Participants')}
+					</Box>
+					<CallParticipants people={call.participants} total={call.usersCount} />
 				</Box>
 			</Box>
 			{children}

apps/meteor/client/components/OngoingCalls/OngoingCalls.spec.tsx

@@ -143,8 +143,9 @@ describe('a call that is ringing', () => {
 
 		expect(await screen.findByText('Alice')).toBeInTheDocument();
 		expect(screen.getByText('Incoming_call')).toBeInTheDocument();
-		// The ringing item says the same thing about itself as the calls below: how many are in there.
-		expect(screen.getByText('__count__people_in_the_call')).toBeInTheDocument();
+		// The ringing item says the same thing about itself as the calls below: who is in there, named and shown.
+		expect(screen.getByText('Participants')).toBeInTheDocument();
+		expect(screen.getByTitle('__count__people_in_the_call')).toBeInTheDocument();
 	});
 
 	it('says how many are incoming when there is more than one', async () => {

apps/meteor/client/views/conference/ConferenceEmbeddedPage.tsx

@@ -14,6 +14,7 @@ import ConferenceIframe from './ConferenceIframe';
 import ConferencePageError from './ConferencePageError';
 import ConferencePreflight from './ConferencePreflight';
 import ConferenceUnauthorizedPage from './ConferenceUnauthorizedPage';
+import { PREFLIGHT_FACES_SHOWN } from '../../../lib/videoConference/constants';
 import PageLoading from '../root/PageLoading';
 import CallBar from './components/CallBar/CallBar';
 import CallBarAction from './components/CallBar/CallBarAction';
@@ -109,8 +110,9 @@ const ConferenceEmbeddedPage = ({ callId }: ConferenceEmbeddedPageProps) => {
 	const { showUnread, unreadCount, unreadVariant, unreadTitle } = useUnreadDisplay(subscription ?? emptyUnreadData);
 	const unread = !chatVisible && showUnread ? unreadCount.total : 0;
 
-	// How many people are actually in the call, which is the number worth glancing at.
-	const presentCount = call.members.filter(isInVideoConference).length;
+	// Who is actually in the call — the faces worth glancing at, and how many there are altogether.
+	const present = useMemo(() => call.members.filter(isInVideoConference), [call.members]);
+	const presentCount = present.length;
 
 	// Where the call puts its own controls — see `actionsContainer`. Created up front rather than captured from
 	// a ref, so it is non-null on the very first render: a ref would still be empty then, and the call would
@@ -197,6 +199,9 @@ const ConferenceEmbeddedPage = ({ callId }: ConferenceEmbeddedPageProps) => {
 				action={call.placing ? 'start' : 'join'}
 				isDirect={call.canRing}
 				canName={call.canRename}
+				// The same faces the sidebar showed on the way here, from this window's own copy of the members —
+				// a screen has room for more of them than a row does.
+				participants={{ people: present.slice(0, PREFLIGHT_FACES_SHOWN), total: presentCount }}
 				capabilities={call.capabilities}
 				onConfirm={(preferences, name) => conference.join({ state: preferences, name })}
 				onCancel={leaveNow}

apps/meteor/client/views/conference/ConferencePreflight.spec.tsx

@@ -83,6 +83,28 @@ it('can be walked away from', async () => {
 	expect(onConfirm).not.toHaveBeenCalled();
 });
 
+// The other half of what this screen is asking: not only how you will arrive, but who is already in there.
+describe('who is already in the call', () => {
+	const people = ['alice', 'bob', 'carol', 'dave', 'erin'].map((username) => ({ _id: username, username }));
+
+	it('shows their faces when joining, under a label saying what they are', async () => {
+		const { container } = renderPreflight({ action: 'join', participants: { people, total: 8 } });
+
+		expect(await screen.findByText('Participants_in_the_call')).toBeInTheDocument();
+		expect(container.querySelectorAll('img')).toHaveLength(5);
+		expect(screen.getByText('+3')).toBeInTheDocument();
+	});
+
+	// Nobody is in a call that hasn't started, so there is nothing to show and no space to leave for it.
+	it('shows nothing when starting a call', async () => {
+		renderPreflight({ action: 'start', participants: { people, total: 8 } });
+
+		await screen.findByRole('button', { name: 'Start_call' });
+		expect(screen.queryByText('Participants_in_the_call')).not.toBeInTheDocument();
+		expect(screen.queryByTitle('__count__people_in_the_call')).not.toBeInTheDocument();
+	});
+});
+
 describe('naming the call', () => {
 	it('is not offered to everyone', async () => {
 		renderPreflight();

apps/meteor/client/views/conference/ConferencePreflight.tsx

@@ -1,6 +1,7 @@
 import type { VideoConferenceCapabilities } from '@rocket.chat/core-typings';
 import { Box, Button, ButtonGroup, Field, FieldRow, Icon, TextInput } from '@rocket.chat/fuselage';
 import { useBreakpoints } from '@rocket.chat/fuselage-hooks';
+import type { ComponentProps } from 'react';
 import { useCallback, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
@@ -9,6 +10,7 @@ import CallDeviceToggle from './CallDeviceToggle';
 import { useCallDevicePreview } from './hooks/useCallDevicePreview';
 import type { CallPreferences } from './hooks/useCallPreferences';
 import { useCallPreferences } from './hooks/useCallPreferences';
+import CallParticipants from '../../components/CallParticipants';
 
 type ConferencePreflightProps = {
 	/** What the call is called, or would be: its own name, or the room it belongs to. */
@@ -24,6 +26,11 @@ type ConferencePreflightProps = {
 	canName: boolean;
 	/** What to offer as the name. Defaults to what the call is called, which is right for one that already exists. */
 	defaultName?: string;
+	/**
+	 * Who is already in the call, as faces. Only meaningful for a join — nobody is in a call that hasn't started —
+	 * and it is the same thing the sidebar shows about the call, which is what the reader saw on their way here.
+	 */
+	participants?: ComponentProps<typeof CallParticipants>;
 	capabilities: VideoConferenceCapabilities;
 	onConfirm: (preferences: CallPreferences, name: string) => void;
 	onCancel: () => void;
@@ -52,6 +59,7 @@ const ConferencePreflight = ({
 	isDirect,
 	canName,
 	defaultName,
+	participants,
 	capabilities,
 	onConfirm,
 	onCancel,
@@ -248,6 +256,21 @@ const ConferencePreflight = ({
 				</Box>
 			)}
 
+			{/* Who is in there already, which is the other half of what the reader is deciding: the call has a name
+			    above and people in it here. Faces rather than a count, and the same ones the sidebar showed them. */}
+			{action === 'join' && participants && (
+				<Box marginBlockStart={16} display='flex' flexDirection='column' alignItems='center'>
+					{/* Said in words as well as in faces: a row of avatars is only obvious once you already know what
+					    it is a row of, and the count alone lives in the group's label where nothing reads it aloud. */}
+					<Box fontScale='c1' color='hint'>
+						{t('Participants_in_the_call')}
+					</Box>
+					<Box marginBlockStart={8}>
+						<CallParticipants {...participants} size='x24' />
+					</Box>
+				</Box>
+			)}
+
 			{/* Nobody's phone is ringing yet — going in is what rings it, and saying so is what makes the wait
 			    afterwards make sense. */}
 			{action === 'start' && isDirect && (

apps/meteor/client/views/conference/testFixtures.ts

@@ -15,6 +15,11 @@ export const buildJoinableCall = (
 	name: `Call ${overrides.callId}`,
 	createdAt: new Date('2026-08-03T10:00:00.000Z'),
 	usersCount: 2,
+	// As many faces as `usersCount` says are in it, so a fixture doesn't accidentally claim a "+N".
+	participants: [
+		{ _id: 'one', username: 'one', name: 'One' },
+		{ _id: 'two', username: 'two', name: 'Two' },
+	],
 	joined: false,
 	declined: false,
 	...overrides,

apps/meteor/lib/videoConference/constants.ts

@@ -6,6 +6,20 @@ export const availabilityErrors = {
 	NO_APP: 'no-videoconf-provider-app',
 };
 
+/**
+ * How many of the people in a call are shown as faces in the sidebar list before the rest become a "+N".
+ *
+ * Shared with the server, which slices the joinable payload to it: sending more would be sending a roster nobody
+ * draws. Three is what fits beside a call's name in a sidebar row without pushing it out.
+ */
+export const CALL_FACES_SHOWN = 3;
+
+/**
+ * The same, on the preflight — a screen rather than a row, so it has room for more of them before the count takes
+ * over. The people come from the call window's own copy of the members, so nothing has to travel for these.
+ */
+export const PREFLIGHT_FACES_SHOWN = 5;
+
 /** Whether this many recipients is a set worth ringing. See `VIDEO_CONF_RINGING_LIMIT` for why there is a cap. */
 export const shouldRingVideoConference = (recipientCount: number): boolean =>
 	recipientCount > 0 && recipientCount <= VIDEO_CONF_RINGING_LIMIT;

apps/meteor/server/services/video-conference/service.ts

@@ -54,7 +54,7 @@ import {
 } from '../../../lib/videoConference/callHistory';
 import { resolveChatAccessMode } from '../../../lib/videoConference/chatAccess';
 import { conferenceNameFor } from '../../../lib/videoConference/conferenceName';
-import { availabilityErrors, shouldRingVideoConference } from '../../../lib/videoConference/constants';
+import { availabilityErrors, CALL_FACES_SHOWN, shouldRingVideoConference } from '../../../lib/videoConference/constants';
 import { isUnaskedConferenceMember } from '../../../lib/videoConference/memberStatus';
 import { expiredPresenceLeases, INFERRED_LEAVE_REASONS } from '../../../lib/videoConference/presence';
 import { readSecondaryPreferred } from '../../database/readSecondaryPreferred';
@@ -1432,6 +1432,9 @@ export class VideoConfService extends ServiceClassInternal implements IVideoConf
 					name: conferenceNameFor(call, uid, subscription?.fname || subscription?.name) || (await this.getRoomName(call.rid)),
 					createdAt: call.createdAt,
 					usersCount: present.length,
+					// A few of them travel with the call so the list can show faces. Capped here rather than at the
+					// reader, because a call in a busy channel would otherwise send a roster to draw three avatars.
+					participants: present.slice(0, CALL_FACES_SHOWN).map(({ _id, username, name }) => ({ _id, username, name })),
 					joined: !!member && isInVideoConference(member),
 					declined: !!member?.declined,
 					// Whether that ring is still live is the reader's to decide, so the moment is what travels.