@stream-io/video-client 1.59.0 → 1.60.0

package/src/sorting/__tests__/presets.test.ts

@@ -1,8 +1,54 @@
 import { describe, expect, it } from 'vitest';
 import * as TestData from './participant-data';
-import { VisibilityState } from '../../types';
-import { paginatedLayoutSortPreset } from '../presets';
-import { TrackType } from '../../gen/video/sfu/models/models';
+import { StreamVideoParticipant, VisibilityState } from '../../types';
+import { Comparator } from '../comparator';
+import {
+  defaultSortPreset,
+  livestreamOrAudioRoomSortPreset,
+  paginatedLayoutSortPreset,
+  speakerLayoutSortPreset,
+} from '../presets';
+import {
+  ParticipantSource,
+  TrackType,
+} from '../../gen/video/sfu/models/models';
+
+const participant = (
+  name: string,
+  publishedTracks: TrackType[],
+  visibility: VisibilityState = VisibilityState.VISIBLE,
+  overrides: Partial<StreamVideoParticipant> = {},
+): StreamVideoParticipant =>
+  ({
+    name,
+    userId: name,
+    sessionId: name,
+    roles: ['user'],
+    publishedTracks,
+    trackLookupPrefix: name,
+    isSpeaking: false,
+    isDominantSpeaker: false,
+    audioLevel: 0,
+    image: '',
+    source: ParticipantSource.WEBRTC_UNSPECIFIED,
+    viewportVisibilityState: {
+      videoTrack: visibility,
+      screenShareTrack: visibility,
+    },
+    ...overrides,
+  }) as StreamVideoParticipant;
+
+const names = (ps: StreamVideoParticipant[]) => ps.map((p) => p.name);
+
+// every preset that prioritizes publishing participants over passive ones
+const presets: [string, Comparator<StreamVideoParticipant>][] = [
+  ['defaultSortPreset', defaultSortPreset],
+  ['speakerLayoutSortPreset', speakerLayoutSortPreset],
+  ['livestreamOrAudioRoomSortPreset', livestreamOrAudioRoomSortPreset],
+];
+
+const { UNKNOWN, VISIBLE, INVISIBLE } = VisibilityState;
+const { AUDIO, VIDEO, SCREEN_SHARE } = TrackType;
 
 describe('presets', () => {
   it('paginatedLayoutSortPreset', () => {
@@ -60,4 +106,143 @@ describe('presets', () => {
       ]
     `);
   });
+
+  // In SpeakerLayout the viewport is the participants bar, so the spotlight
+  // tile is never observed and stays UNKNOWN. Regression test for a passive
+  // participant holding the spotlight over a participant publishing video.
+  it.each(presets)(
+    '%s keeps passive participants out of the spotlight',
+    (_, preset) => {
+      const ps = [
+        participant('passive-viewer', [], UNKNOWN),
+        participant('host', [VIDEO]),
+        participant('local-viewer', [], VISIBLE, { isLocalParticipant: true }),
+      ];
+
+      expect(names(ps.sort(preset))).toEqual([
+        'host',
+        'passive-viewer',
+        'local-viewer',
+      ]);
+    },
+  );
+
+  it.each(presets)(
+    '%s promotes a rejoined publisher appended last',
+    (_, preset) => {
+      const ps = [
+        participant('v1', [], UNKNOWN),
+        participant('v2', []),
+        participant('v3', []),
+      ].sort(preset);
+      // a rejoining participant is appended to the end of the list
+      ps.push(participant('host', [AUDIO, VIDEO], UNKNOWN));
+
+      expect(names(ps.sort(preset))).toEqual(['host', 'v1', 'v2', 'v3']);
+    },
+  );
+
+  it.each(presets)(
+    '%s ranks passive participants below publishing ones regardless of visibility',
+    (_, preset) => {
+      const passive = [
+        participant('p1', [], UNKNOWN),
+        participant('p2', [], VISIBLE),
+        participant('p3', [], INVISIBLE),
+      ];
+      const publishing = [
+        participant('a1', [VIDEO], UNKNOWN),
+        participant('a2', [AUDIO], VISIBLE),
+        participant('a3', [AUDIO, VIDEO], INVISIBLE),
+      ];
+
+      for (const a of passive) {
+        for (const b of publishing) {
+          expect(preset(a, b)).toBe(1);
+          expect(preset(b, a)).toBe(-1);
+        }
+      }
+    },
+  );
+
+  // `publishing` ignores the track type, so a participant keeps its rank while
+  // it still publishes something. In speakerLayoutSortPreset the gated
+  // comparators cannot override this, because the gate only opens on INVISIBLE.
+  it.each<[string, TrackType[]]>([
+    ['camera and microphone on', [AUDIO, VIDEO]],
+    ['the microphone muted', [VIDEO]],
+    ['the camera turned off', [AUDIO]],
+  ])(
+    'speakerLayoutSortPreset keeps the spotlight with %s',
+    (_, spotlightTracks) => {
+      const ps = [
+        participant('spotlight', spotlightTracks, UNKNOWN),
+        participant('bar', [AUDIO, VIDEO]),
+      ];
+
+      expect(names(ps.sort(speakerLayoutSortPreset))).toEqual([
+        'spotlight',
+        'bar',
+      ]);
+    },
+  );
+
+  it('speakerLayoutSortPreset drops a spotlight that stops publishing', () => {
+    const ps = [
+      participant('spotlight', [], UNKNOWN),
+      participant('bar', [AUDIO, VIDEO]),
+    ];
+
+    expect(names(ps.sort(speakerLayoutSortPreset))).toEqual([
+      'bar',
+      'spotlight',
+    ]);
+  });
+
+  // livestreamOrAudioRoomSortPreset gates on INVISIBLE *or* UNKNOWN, so an
+  // unobserved spotlight tile stays comparable by audio and video state. This
+  // predates the `publishing` comparator, which only breaks ties between a
+  // publishing and a non-publishing participant.
+  it('livestreamOrAudioRoomSortPreset still re-ranks publishers by track state', () => {
+    const ps = [
+      participant('spotlight', [VIDEO], UNKNOWN),
+      participant('bar', [AUDIO, VIDEO]),
+    ];
+
+    expect(names(ps.sort(livestreamOrAudioRoomSortPreset))).toEqual([
+      'bar',
+      'spotlight',
+    ]);
+  });
+
+  it.each<[string, TrackType[], Partial<StreamVideoParticipant>]>([
+    ['a pinned participant', [], { pin: { isLocalPin: true, pinnedAt: 1 } }],
+    ['a presenter', [SCREEN_SHARE], {}],
+    ['the dominant speaker', [AUDIO], { isDominantSpeaker: true }],
+  ])(
+    'speakerLayoutSortPreset ranks %s above a publishing participant',
+    (_, tracks, overrides) => {
+      const ps = [
+        participant('publisher', [AUDIO, VIDEO], UNKNOWN),
+        participant('contender', tracks, VISIBLE, overrides),
+      ];
+
+      expect(names(ps.sort(speakerLayoutSortPreset))).toEqual([
+        'contender',
+        'publisher',
+      ]);
+    },
+  );
+
+  it('livestreamOrAudioRoomSortPreset still uses role as a tie breaker between publishers', () => {
+    const ps = [
+      participant('viewer', [AUDIO, VIDEO]),
+      participant('host', [AUDIO, VIDEO], UNKNOWN, { roles: ['host'] }),
+    ];
+
+    expect(names(ps.sort(livestreamOrAudioRoomSortPreset))).toEqual([
+      'host',
+      'viewer',
+    ]);
+  });
 });

package/src/sorting/__tests__/sorting.test.ts

@@ -1,11 +1,16 @@
 import { describe, expect, it } from 'vitest';
-import { ParticipantSource } from '../../gen/video/sfu/models/models';
+import {
+  ParticipantSource,
+  TrackType,
+} from '../../gen/video/sfu/models/models';
+import { StreamVideoParticipant } from '../../types';
 import {
   combineComparators,
   Comparator,
   conditional,
   dominantSpeaker,
   pinned,
+  publishing,
   publishingAudio,
   publishingVideo,
   screenSharing,
@@ -37,6 +42,22 @@ describe('Sorting', () => {
     expect(sorted.map((p) => p.name)).toEqual(['F', 'D', 'B', 'A', 'E', 'C']);
   });
 
+  it('publishing', () => {
+    const { AUDIO, VIDEO, SCREEN_SHARE } = TrackType;
+    const p = (publishedTracks: TrackType[]) =>
+      ({ publishedTracks }) as StreamVideoParticipant;
+
+    // publishing anything ranks above publishing nothing
+    expect(publishing(p([AUDIO]), p([]))).toEqual(-1);
+    expect(publishing(p([SCREEN_SHARE]), p([]))).toEqual(-1);
+    expect(publishing(p([]), p([VIDEO]))).toEqual(1);
+
+    // the track type is irrelevant, so device toggles do not change the rank
+    expect(publishing(p([AUDIO, VIDEO]), p([AUDIO]))).toEqual(0);
+    expect(publishing(p([VIDEO]), p([AUDIO]))).toEqual(0);
+    expect(publishing(p([]), p([]))).toEqual(0);
+  });
+
   it('conditional comparator', () => {
     const byValue: Comparator<number> = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
     const input = [2, 3, 1];

package/src/sorting/participants.ts

@@ -73,6 +73,26 @@ export const publishingAudio: Comparator<StreamVideoParticipant> = (a, b) => {
   return 0;
 };
 
+/**
+ * A comparator which prioritizes participants who are publishing any track
+ * over participants who are not publishing at all.
+ *
+ * Unlike `publishingVideo` and `publishingAudio`, this comparator does not
+ * distinguish between track types. Muting the microphone or turning off the
+ * camera does not change a participant's rank as long as they still publish
+ * something, which keeps the ordering stable across ordinary device toggles.
+ *
+ * @param a the first participant.
+ * @param b the second participant.
+ */
+export const publishing: Comparator<StreamVideoParticipant> = (a, b) => {
+  const hasA = a.publishedTracks.length > 0;
+  const hasB = b.publishedTracks.length > 0;
+  if (hasA && !hasB) return -1;
+  if (!hasA && hasB) return 1;
+  return 0;
+};
+
 /**
  * A comparator which prioritizes participants who are pinned.
  *

package/src/sorting/presets.ts

@@ -4,6 +4,7 @@ import { ParticipantSource } from '../gen/video/sfu/models/models';
 import {
   dominantSpeaker,
   pinned,
+  publishing,
   publishingAudio,
   publishingVideo,
   reactionType,
@@ -51,6 +52,7 @@ const withVideoIngressSource = withParticipantSource(
 export const defaultSortPreset = combineComparators(
   screenSharing,
   pinned,
+  publishing,
   ifInvisibleBy(
     combineComparators(
       dominantSpeaker,
@@ -69,6 +71,7 @@ export const speakerLayoutSortPreset = combineComparators(
   screenSharing,
   pinned,
   dominantSpeaker,
+  publishing,
   ifInvisibleBy(
     combineComparators(
       speaking,
@@ -102,6 +105,7 @@ export const paginatedLayoutSortPreset = combineComparators(
  * The sorting preset for livestreams and audio rooms.
  */
 export const livestreamOrAudioRoomSortPreset = combineComparators(
+  publishing,
   ifInvisibleOrUnknownBy(
     combineComparators(
       dominantSpeaker,

package/src/stats/__tests__/utils.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { getStreamClientId } from '../utils';
+import { SdkType } from '../../gen/video/sfu/models/models';
+
+describe('getStreamClientId', () => {
+  const sdk = (type: SdkType) => ({
+    type,
+    major: '1',
+    minor: '43',
+    patch: '1',
+  });
+
+  it('names the React SDK', () => {
+    expect(getStreamClientId(sdk(SdkType.REACT))).toBe(
+      'stream-video-react-v1.43.1',
+    );
+  });
+
+  it('names the React Native SDK', () => {
+    expect(getStreamClientId(sdk(SdkType.REACT_NATIVE))).toBe(
+      'stream-video-react-native-v1.43.1',
+    );
+  });
+
+  it('falls back to the plain JS client for every other SDK type', () => {
+    expect(getStreamClientId(sdk(SdkType.PLAIN_JAVASCRIPT))).toBe(
+      'stream-video-js-v1.43.1',
+    );
+    expect(getStreamClientId(undefined)).toBe(
+      'stream-video-js-v0.0.0-development',
+    );
+  });
+});

package/src/stats/utils.ts

@@ -51,3 +51,18 @@ export const getSdkName = (sdk: Sdk | undefined) => {
 export const getSdkVersion = (sdk: Sdk | undefined) => {
   return sdk ? `${sdk.major}.${sdk.minor}.${sdk.patch}` : '0.0.0-development';
 };
+
+/**
+ * Returns the identifier the SFU receives in the `X-Stream-Client` header,
+ * e.g. `stream-video-react-v1.43.1`. Matches the format the coordinator
+ * already gets through the client's user agent.
+ */
+export const getStreamClientId = (sdk: Sdk | undefined) => {
+  const sdkPlatforms: Partial<Record<SdkType, string>> = {
+    [SdkType.REACT]: 'react',
+    [SdkType.REACT_NATIVE]: 'react-native',
+  };
+
+  const platform = (sdk && sdkPlatforms[sdk.type]) || 'js';
+  return `stream-video-${platform}-v${getSdkVersion(sdk)}`;
+};

package/src/store/CallState.ts

@@ -37,6 +37,7 @@ import {
   CallSessionParticipantLeftEvent,
   CallSessionResponse,
   CallSettingsResponse,
+  GetCallRingStateResponse,
   ClosedCaptionEvent,
   EgressResponse,
   MemberResponse,
@@ -1352,6 +1353,30 @@ export class CallState {
     this.setCurrentValue(this.thumbnailsSubject, call.thumbnails);
   };
 
+  /**
+   * Merges a polled ring state into the current session. Only the ring fields
+   * are touched: the endpoint does not return the session roster.
+   *
+   * @internal
+   *
+   * @param ringState the ring state as returned by the coordinator.
+   */
+  updateFromRingState = (ringState: GetCallRingStateResponse) => {
+    this.setCurrentValue(this.sessionSubject, (session) => {
+      if (!session || session.id !== ringState.session_id) return session;
+      return {
+        ...session,
+        accepted_by: ringState.accepted_by,
+        rejected_by: ringState.rejected_by,
+        missed_by: ringState.missed_by,
+        ended_at: ringState.session_ended_at ?? session.ended_at,
+      };
+    });
+    if (ringState.call_ended_at) {
+      this.setEndedAt(new Date(ringState.call_ended_at));
+    }
+  };
+
   /**
    * Updates the call state with the data received from the SFU server.
    *

package/src/store/__tests__/CallState.test.ts

@@ -24,6 +24,7 @@ import {
   CallAcceptedEvent,
   CallEndedEvent,
   CallUpdatedEvent,
+  type GetCallRingStateResponse,
   MemberResponse,
   OwnCapability,
 } from '../../gen/coordinator';
@@ -266,8 +267,8 @@ describe('CallState', () => {
           "E",
           "F",
           "A",
-          "C",
           "D",
+          "C",
         ]
       `);
 
@@ -288,8 +289,8 @@ describe('CallState', () => {
           "E",
           "F",
           "A",
-          "C",
           "D",
+          "C",
         ]
       `);
     });
@@ -1474,4 +1475,62 @@ describe('CallState', () => {
       expect(state['closedCaptionsTasks'].size).toBe(0);
     });
   });
+
+  describe('updateFromRingState', () => {
+    const ringState = fromPartial<GetCallRingStateResponse>({
+      session_id: 'session-1',
+      accepted_by: { bob: '2026-08-24T10:00:04Z' },
+      rejected_by: { carol: '2026-08-24T10:00:09Z' },
+      missed_by: { dave: '2026-08-24T10:00:35Z' },
+    });
+
+    const withSession = (id: string) => {
+      const state = new CallState();
+      state['sessionSubject'].next(
+        fromPartial({
+          id,
+          accepted_by: {},
+          rejected_by: {},
+          missed_by: {},
+          participants: [fromPartial({ user_session_id: 'p1' })],
+        }),
+      );
+      return state;
+    };
+
+    it('merges the ring maps into the current session', () => {
+      const state = withSession('session-1');
+      state.updateFromRingState(ringState);
+
+      expect(state.session?.accepted_by).toEqual(ringState.accepted_by);
+      expect(state.session?.rejected_by).toEqual(ringState.rejected_by);
+      expect(state.session?.missed_by).toEqual(ringState.missed_by);
+    });
+
+    it('leaves the session roster untouched', () => {
+      const state = withSession('session-1');
+      state.updateFromRingState(ringState);
+
+      expect(state.session?.participants).toHaveLength(1);
+    });
+
+    it('ignores a ring state that belongs to another session', () => {
+      const state = withSession('session-2');
+      state.updateFromRingState(ringState);
+
+      expect(state.session?.accepted_by).toEqual({});
+    });
+
+    it('applies the end timestamps', () => {
+      const state = withSession('session-1');
+      state.updateFromRingState({
+        ...ringState,
+        session_ended_at: '2026-08-24T10:01:00Z',
+        call_ended_at: '2026-08-24T10:01:00Z',
+      });
+
+      expect(state.session?.ended_at).toBe('2026-08-24T10:01:00Z');
+      expect(state.endedAt).toEqual(new Date('2026-08-24T10:01:00Z'));
+    });
+  });
 });