mediasfu-shared 1.0.6 → 1.1.0

package/dist/methods/utils/headless/roomActions.d.ts

@@ -0,0 +1,88 @@
+import { HeadlessOptions } from './headlessTypes';
+export interface HeadlessActionResult {
+    ok: boolean;
+    /** Empty when `ok`; otherwise a short, user-safe explanation. */
+    error: string;
+}
+export interface LeaveRoomOptions extends HeadlessOptions {
+    /** Ban the member on the way out. Requires host privileges. */
+    ban?: boolean;
+    /** Whether a host exit should end the room for everyone. Defaults to true. */
+    endRoomOnHostExit?: boolean;
+}
+export type LeaveRoomType = (options: LeaveRoomOptions) => Promise<HeadlessActionResult>;
+/**
+ * Leave the room from a headless surface.
+ *
+ * Without this you have to pull `socket`, `localSocket`, `member` and `roomName`
+ * off the bag yourself and hand them to `confirmExit` — four chances to pass a
+ * stale value, and a silent no-op when you do.
+ *
+ * Never throws: a failed exit comes back as `{ ok: false, error }` so a Leave
+ * button can report why rather than appearing to work.
+ *
+ * @example
+ * ```ts
+ * import { leaveRoom } from 'mediasfu-shared';
+ *
+ * const result = await leaveRoom({
+ *   parameters: parameterStore.getCurrent(),
+ *   endRoomOnHostExit: false,
+ * });
+ * if (!result.ok) setNotice(result.error);
+ * ```
+ */
+export declare function leaveRoom({ parameters, ban, endRoomOnHostExit, }: LeaveRoomOptions): Promise<HeadlessActionResult>;
+export interface SendChatMessageOptions extends HeadlessOptions {
+    message: string;
+    /** Specific recipients. Empty (default) sends to the group. */
+    receivers?: string[];
+    /** Send to everyone. Defaults to true when `receivers` is empty. */
+    group?: boolean;
+}
+export type SendChatMessageType = (options: SendChatMessageOptions) => Promise<HeadlessActionResult>;
+/**
+ * Send a chat message from a headless surface.
+ *
+ * `sendMessage` takes eleven fields that all have to be lifted off the bag in
+ * the right combination; this resolves them for you, including the
+ * `localSocket`-before-`socket` preference the SDK uses for chat.
+ *
+ * @example
+ * ```ts
+ * import { sendChatMessage } from 'mediasfu-shared';
+ *
+ * await sendChatMessage({ parameters, message: 'Hello everyone' });
+ * await sendChatMessage({ parameters, message: 'Just you', receivers: ['Paul'] });
+ * ```
+ */
+export declare function sendChatMessage({ parameters, message, receivers, group, }: SendChatMessageOptions): Promise<HeadlessActionResult>;
+export interface RunMediaControlOptions extends HeadlessOptions {
+    /** Which control to run. */
+    control: 'clickAudio' | 'clickVideo' | 'clickScreenShare' | 'switchAudio' | 'switchVideo' | 'switchVideoAlt';
+    /** Extra arguments, e.g. `{ audioPreference: deviceId }` for `switchAudio`. */
+    extra?: Record<string, any>;
+}
+export type RunMediaControlType = (options: RunMediaControlOptions) => Promise<HeadlessActionResult>;
+/**
+ * Invoke a media control safely from a headless surface.
+ *
+ * Gates on {@link getRoomReadiness} first — firing `clickVideo` before the
+ * transport exists fails silently and looks like a dead button — then resolves
+ * the control off the current bag rather than a snapshot the caller captured
+ * earlier.
+ *
+ * @example
+ * ```ts
+ * import { runMediaControl } from 'mediasfu-shared';
+ *
+ * await runMediaControl({ parameters, control: 'clickVideo' });
+ * await runMediaControl({
+ *   parameters,
+ *   control: 'switchVideo',
+ *   extra: { videoPreference: deviceId },
+ * });
+ * ```
+ */
+export declare function runMediaControl({ parameters, control, extra, }: RunMediaControlOptions): Promise<HeadlessActionResult>;
+//# sourceMappingURL=roomActions.d.ts.map

package/dist/methods/utils/headless/roomActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roomActions.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/roomActions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAsB,MAAM,iBAAiB,CAAC;AAItE,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;CACf;AAcD,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,+DAA+D;IAC/D,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,EAC9B,UAAU,EACV,GAAW,EACX,iBAAwB,GACzB,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAyBlD;AAED,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,sBAAsB,KAC5B,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,EACpC,UAAU,EACV,OAAO,EACP,SAAc,EACd,KAAK,GACN,EAAE,sBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiCxD;AAED,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,4BAA4B;IAC5B,OAAO,EACH,YAAY,GACZ,YAAY,GACZ,kBAAkB,GAClB,aAAa,GACb,aAAa,GACb,gBAAgB,CAAC;IACrB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC7B;AAED,MAAM,MAAM,mBAAmB,GAAG,CAChC,OAAO,EAAE,sBAAsB,KAC5B,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,CAAC,EACpC,UAAU,EACV,OAAO,EACP,KAAK,GACN,EAAE,sBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkCxD"}

package/dist/methods/utils/headless/sessionControls.d.ts

@@ -0,0 +1,159 @@
+import { HeadlessOptions } from './headlessTypes';
+import { HeadlessActionResult } from './roomActions';
+export interface SwitchDeviceOptions extends HeadlessOptions {
+    /** `deviceId` from `listMediaDevices()`. */
+    deviceId: string;
+}
+export type SwitchCameraType = (options: SwitchDeviceOptions) => Promise<HeadlessActionResult>;
+/**
+ * Switch to a different camera.
+ *
+ * Pairs with `listMediaDevices()` / `getSelectedDevices()`, which could
+ * previously only report devices with no way to act on them.
+ *
+ * Goes through the SDK's own `switchUserVideo`, so the producer track is
+ * replaced on the existing transport — remote viewers see the new camera
+ * without the call renegotiating — and host restrictions still apply. A refusal
+ * (blocked by the host, audio-only event) is returned as `ok: false` with the
+ * reason rather than resolving silently.
+ *
+ * @example
+ * ```ts
+ * const { video } = await listMediaDevices();
+ * await switchCamera({ parameters, deviceId: video[1].deviceId });
+ * ```
+ */
+export declare function switchCamera({ parameters, deviceId, }: SwitchDeviceOptions): Promise<HeadlessActionResult>;
+/**
+ * Flip between the front and rear cameras.
+ *
+ * This toggles — the SDK's `switchVideoAlt` swaps whichever facing mode is
+ * current and takes no target, so there is no way to ask for "front"
+ * specifically. Use `switchCamera` with a deviceId when you need to land on a
+ * particular camera; use this on mobile, where device ids are unstable across
+ * sessions but the flip gesture is what users expect.
+ */
+export declare function flipCamera({ parameters }: HeadlessOptions): Promise<HeadlessActionResult>;
+export type SwitchMicrophoneType = (options: SwitchDeviceOptions) => Promise<HeadlessActionResult>;
+/** Switch to a different microphone. The audio counterpart of `switchCamera`. */
+export declare function switchMicrophone({ parameters, deviceId, }: SwitchDeviceOptions): Promise<HeadlessActionResult>;
+/** 'allow' — anyone may; 'approval' — must ask the host; 'disallow' — nobody may. */
+export type RoomPolicyValue = 'allow' | 'approval' | 'disallow';
+export interface SetRoomMediaPolicyOptions extends HeadlessOptions {
+    audio?: RoomPolicyValue;
+    video?: RoomPolicyValue;
+    screenshare?: RoomPolicyValue;
+    chat?: RoomPolicyValue;
+}
+/**
+ * Set what participants are allowed to do — the room-wide policy behind the
+ * SDK's settings modal.
+ *
+ * This is the *rule*, not a one-off action: `setParticipantMedia` (moderation)
+ * turns one person's camera off now, whereas `video: 'approval'` here means
+ * everyone must ask before turning one on. `getMediaPermissions()` reads the
+ * same four values back.
+ *
+ * Host only. Any value left undefined keeps its current setting.
+ *
+ * @example
+ * ```ts
+ * await setRoomMediaPolicy({ parameters, audio: 'approval', screenshare: 'disallow' });
+ * ```
+ */
+export declare function setRoomMediaPolicy({ parameters, audio, video, screenshare, chat, }: SetRoomMediaPolicyOptions): Promise<HeadlessActionResult>;
+export interface ChatMessage {
+    sender: string;
+    message: string;
+    timestamp: string;
+    /** Recipients — empty/[] means it went to everyone. */
+    receivers: string[];
+    /** True when this is a direct message rather than a room-wide one. */
+    direct: boolean;
+    /** True when the local user sent it. */
+    mine: boolean;
+}
+export interface GetChatMessagesOptions extends HeadlessOptions {
+    /** 'all' (default), 'group' for room-wide only, or 'direct' for DMs only. */
+    scope?: 'all' | 'group' | 'direct';
+    /** Only messages exchanged with this person. Implies direct messages. */
+    withPerson?: string;
+}
+/**
+ * Read the chat.
+ *
+ * `sendChatMessage` existed with no way to read replies, so a headless surface
+ * could talk but not listen. Direct messages are flagged and filterable, since
+ * rendering a DM in the room-wide thread leaks it to the wrong audience.
+ *
+ * Call from `onMediaChanged` or a render to get the current list.
+ */
+export declare function getChatMessages({ parameters, scope, withPerson, }: GetChatMessagesOptions): ChatMessage[];
+export interface PendingApprovals {
+    /** People held in the waiting room. */
+    waiting: {
+        name: string;
+        id: string;
+    }[];
+    /** Requests to unmute, turn a camera on, share, or chat. */
+    requests: {
+        id: string;
+        name: string;
+        icon: string;
+        username: string;
+    }[];
+    /** Total items needing a host decision. */
+    total: number;
+}
+/**
+ * Everything currently awaiting a host decision.
+ *
+ * `respondToWaitingParticipant` and `respondToParticipantRequest` could act on
+ * these but nothing could list them, so a headless host had no way to know a
+ * decision was pending. Badge `total` and render the two lists.
+ */
+export declare function getPendingApprovals({ parameters }: HeadlessOptions): PendingApprovals;
+export interface SessionTimer {
+    /** Elapsed wall time, formatted by the SDK (e.g. "12:04"). */
+    elapsed: string;
+    /**
+     * True while the server is asking whether you are still there — see
+     * `getPresenceCheck`, which you must answer or be disconnected.
+     */
+    presenceCheckPending: boolean;
+}
+/**
+ * How long the session has been running.
+ *
+ * Deliberately does not report "time remaining": the server sends that on the
+ * `meetingTimeRemaining` event, which the SDK forwards straight to `showAlert`
+ * without storing it. There is no field to read, and inventing one from the
+ * last alert would be a guess. Watch `showAlert` if you need the warning.
+ */
+export declare function getSessionTimer({ parameters }: HeadlessOptions): SessionTimer;
+export interface PresenceCheck {
+    /** True while the "are you still there?" check is waiting on an answer. */
+    pending: boolean;
+}
+/**
+ * Whether the server is currently asking if you are still there.
+ *
+ * **This matters more headlessly than it looks.** On an idle room the server
+ * emits `meetingStillThere`, and the SDK opens a modal that counts down and
+ * then emits `disconnectUser`. With `returnUI={false}` that modal is still
+ * mounted — inside a root collapsed to 0×0 — so the countdown runs invisibly
+ * and the session is dropped with nothing shown and nothing to click.
+ *
+ * Poll this (from `onMediaChanged`, or a timer) and call `confirmStillHere`
+ * to stay in the room.
+ */
+export declare function getPresenceCheck({ parameters }: HeadlessOptions): PresenceCheck;
+/**
+ * Answer the "are you still there?" check and stay in the room.
+ *
+ * Closing the check is the whole answer — the SDK only disconnects on the
+ * countdown expiring, so cancelling it is what keeps the session alive. Safe to
+ * call when nothing is pending.
+ */
+export declare function confirmStillHere({ parameters }: HeadlessOptions): HeadlessActionResult;
+//# sourceMappingURL=sessionControls.d.ts.map

package/dist/methods/utils/headless/sessionControls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionControls.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/sessionControls.ts"],"names":[],"mappings":"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"}

package/dist/methods/utils/headless/sessionExtras.d.ts

@@ -0,0 +1,291 @@
+import { HeadlessOptions } from './headlessTypes';
+export interface RecordingNotice {
+    /** The SDK's current recording notice, or '' when there is none. */
+    message: string;
+    /** Formatted elapsed time as the SDK reports it (e.g. "00:12:04"). */
+    elapsed: string;
+    /** Elapsed seconds. */
+    elapsedSeconds: number;
+    /** True while pause/resume is permitted (the SDK enforces a cooldown). */
+    canPauseResume: boolean;
+    /** Pauses used so far. */
+    pausesUsed: number;
+    /** Pauses allowed for the active media type; 0 when unpublished. */
+    pauseLimit: number;
+    /** True when the pause allowance is exhausted. */
+    pauseLimitReached: boolean;
+}
+export type GetRecordingNoticeType = (options: HeadlessOptions) => RecordingNotice;
+/**
+ * The user-facing side of recording: the notice, the timer, and the pause
+ * allowance.
+ *
+ * Pause limits are per media type — `recordingAudioPausesLimit` vs
+ * `recordingVideoPausesLimit` — and the SDK picks by `recordingMediaOptions`.
+ * Reading the wrong one reports the wrong allowance, which is why this is a
+ * helper rather than a field read. Complements `getRecordingState`, which
+ * covers only the start/pause/resume/stop status.
+ */
+export declare function getRecordingNotice({ parameters }: HeadlessOptions): RecordingNotice;
+export interface RecordingCapabilities {
+    /** Recording audio at all. */
+    audio: boolean;
+    /** Recording video at all. */
+    video: boolean;
+    /** Recording every participant, not just the active speaker. */
+    allParticipants: boolean;
+    /** Recording every participant's video. */
+    videoParticipants: boolean;
+    /** Adding an HLS output. */
+    hls: boolean;
+    /** Max people included in an audio recording; 0 when unpublished. */
+    audioPeopleLimit: number;
+    /** Max people included in a video recording; 0 when unpublished. */
+    videoPeopleLimit: number;
+}
+export type GetRecordingCapabilitiesType = (options: HeadlessOptions) => RecordingCapabilities;
+/**
+ * What this room's plan actually permits recording.
+ *
+ * These are entitlement flags the server publishes per room, so a UI should
+ * gate on them rather than offering options the room will refuse.
+ */
+export declare function getRecordingCapabilities({ parameters, }: HeadlessOptions): RecordingCapabilities;
+export interface TranslationPreference {
+    /** Language applied to every speaker, or null when unset. */
+    globalLanguage: string | null;
+    /** Per-speaker overrides, keyed by speaker id. */
+    perSpeaker: {
+        speakerId: string;
+        language: string | null;
+        wantOriginal: boolean;
+    }[];
+}
+export interface TranslationState extends TranslationPreference {
+    /** True when any translation is currently being consumed. */
+    active: boolean;
+    /** Languages the room currently has translation producers for. */
+    availableLanguages: string[];
+}
+export type GetTranslationStateType = (options: HeadlessOptions) => TranslationState;
+/**
+ * What the listener is currently hearing, and what is on offer.
+ *
+ * `listenerTranslationPreferences.perSpeaker` is a `Map` on the bag, which does
+ * not survive serialisation or spread; this returns a plain array so it can be
+ * rendered and compared normally. Translation audio itself already reaches the
+ * user through `getAudioGridComponents`, which folds in `translationStreams`.
+ */
+export declare function getTranslationState({ parameters }: HeadlessOptions): TranslationState;
+export interface SetTranslationPreferenceOptions extends HeadlessOptions {
+    /** Language for every speaker. `null` restores the original audio. */
+    language?: string | null;
+    /** Limit the change to one speaker. */
+    speakerId?: string;
+    /** Explicitly prefer the untranslated audio for this speaker. */
+    wantOriginal?: boolean;
+}
+export type SetTranslationPreferenceType = (options: SetTranslationPreferenceOptions) => {
+    ok: boolean;
+    error: string;
+};
+/**
+ * Choose a translation language, globally or for one speaker.
+ *
+ * Delegates to the SDK's `updateListenerTranslationPreferences`, which is what
+ * syncs the choice to the server for routing and billing — setting the bag's
+ * fields directly would change local state without telling the server.
+ */
+export declare function setTranslationPreference({ parameters, language, speakerId, wantOriginal, }: SetTranslationPreferenceOptions): {
+    ok: boolean;
+    error: string;
+};
+export interface FocusModeState {
+    /** True while focus mode is active. */
+    active: boolean;
+    /** Participants permitted to speak/appear while focus mode is on. */
+    panelists: {
+        name: string;
+        [key: string]: any;
+    }[];
+    /** True when the local user is one of them. */
+    selfIsPanelist: boolean;
+    /** True when focus mode silences non-panelist microphones. */
+    mutesMicrophones: boolean;
+    /** True when focus mode blocks non-panelist cameras. */
+    mutesCameras: boolean;
+}
+export type GetFocusModeStateType = (options: HeadlessOptions) => FocusModeState;
+/**
+ * Focus-mode ("only panelists") state.
+ *
+ * The field is `muteOthersCamera`, not `muteOthersVideo` — worth stating,
+ * because the neighbouring flag is `muteOthersMic` and the asymmetry invites a
+ * wrong guess. {@link getMediaPermissions} already applies these rules to the
+ * local user; this exposes the room-level picture for a roster UI.
+ */
+export declare function getFocusModeState({ parameters }: HeadlessOptions): FocusModeState;
+export interface VirtualBackgroundState {
+    /** True when a processed (background-applied) stream is being published. */
+    active: boolean;
+    /** The processed stream, when one exists. */
+    stream: MediaStream | null;
+    /** The background currently applied, if the SDK reports one. */
+    appliedBackground: any;
+    /** The image the user selected, if any. */
+    selectedImage: string | null;
+}
+export type GetVirtualBackgroundStateType = (options: HeadlessOptions) => VirtualBackgroundState;
+/**
+ * Read-only virtual-background state.
+ *
+ * **You do not need this to render the right self-view.**
+ * `getLocalVideoStream` already returns the processed `virtualStream` whenever
+ * `keepBackground` is on, and the raw camera otherwise — the same rule the SDK's
+ * own grid uses. Rendering `localStreamVideo` directly is what shows a user
+ * their *unprocessed* background, so prefer the helper and ignore this.
+ *
+ * This exists for UI that needs to *describe* the state ("Background on"), not
+ * to choose a stream.
+ *
+ * Known gap: applying or clearing a background is still modal-driven in the SDK
+ * (`isBackgroundModalVisible` / `autoClickBackground`), so a `returnUI={false}`
+ * surface cannot currently turn a background on by itself. Reading works
+ * headlessly; controlling does not.
+ */
+export declare function getVirtualBackgroundState({ parameters, }: HeadlessOptions): VirtualBackgroundState;
+export interface SetParticipantPlaybackOptions extends HeadlessOptions {
+    /** Participant display name. */
+    name?: string;
+    /** Producer id, when you already hold one. */
+    producerId?: string;
+    /** Which of their tracks to affect. Defaults to both. */
+    kind?: 'audio' | 'video' | 'all';
+    /** True to stop receiving, false to resume. */
+    paused: boolean;
+}
+export type SetParticipantPlaybackType = (options: SetParticipantPlaybackOptions) => Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+/**
+ * Stop or resume playing one participant's media **for you only**.
+ *
+ * This is a local, per-viewer control — "don't play this person to me right
+ * now". It pauses the mediasoup consumer, so the server stops sending that
+ * track to you: it saves bandwidth as well as silencing them, and it is
+ * invisible to everyone else. It is NOT moderation — the participant keeps
+ * publishing and other people keep receiving. Use `setParticipantMedia` from
+ * the moderation module to actually stop someone's media for the room.
+ *
+ * Note this is deliberately not `resumePauseStreams`, which the SDK drives from
+ * the active-speaker layout (`dispActiveNames`) and will happily undo a manual
+ * choice on its next pass. This targets the consumer directly.
+ *
+ * @example
+ * ```ts
+ * // Stop hearing and seeing Paul locally
+ * await setParticipantPlayback({ parameters, name: 'Paul', paused: true });
+ * // Just their audio
+ * await setParticipantPlayback({ parameters, name: 'Paul', kind: 'audio', paused: true });
+ * ```
+ */
+export declare function setParticipantPlayback({ parameters, name, producerId, kind, paused, }: SetParticipantPlaybackOptions): Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+export type BreakoutParticipantRef = {
+    name: string;
+    breakRoom: number;
+};
+export interface SetBreakoutRoomsOptions extends HeadlessOptions {
+    /** Room composition: index in the outer array is the room number. */
+    rooms: BreakoutParticipantRef[][];
+    /** What happens to people who join later. Defaults to the room's setting. */
+    newParticipantAction?: string;
+}
+export type SetBreakoutRoomsType = (options: SetBreakoutRoomsOptions) => Promise<{
+    ok: boolean;
+    error: string;
+}>;
+/**
+ * Publish a full breakout-room composition.
+ *
+ * The SDK models breakout rooms as an array of arrays — outer index is the room
+ * number, inner entries are `{ name, breakRoom }`. Adding, removing, or moving
+ * someone is therefore just editing that array and re-emitting it; there is no
+ * per-participant verb. `startBreakout` opens them, `updateBreakout` amends a
+ * running set, and the SDK picks by whether they are already started.
+ *
+ * Prefer {@link assignParticipantToBreakoutRoom} for single-person changes.
+ */
+export declare function setBreakoutRooms({ parameters, rooms, newParticipantAction, }: SetBreakoutRoomsOptions): Promise<{
+    ok: boolean;
+    error: string;
+}>;
+export interface AssignParticipantToBreakoutRoomOptions extends HeadlessOptions {
+    /** Participant display name. */
+    name: string;
+    /** Destination room index, or `null` to remove them from breakout rooms. */
+    room: number | null;
+    newParticipantAction?: string;
+}
+export type AssignParticipantToBreakoutRoomType = (options: AssignParticipantToBreakoutRoomOptions) => Promise<{
+    ok: boolean;
+    error: string;
+}>;
+/**
+ * Add, move, or remove one participant, without rebuilding the whole array.
+ *
+ * Covers all three cases the composition array makes awkward by hand:
+ * `room: 1` adds them to room 1 (or moves them there from wherever they are),
+ * `room: null` removes them from breakout rooms entirely. Empty trailing rooms
+ * are preserved, because room numbers are positional and collapsing them would
+ * silently renumber everyone else.
+ *
+ * @example
+ * ```ts
+ * await assignParticipantToBreakoutRoom({ parameters, name: 'Ada', room: 0 }); // add
+ * await assignParticipantToBreakoutRoom({ parameters, name: 'Ada', room: 1 }); // move 0 -> 1
+ * await assignParticipantToBreakoutRoom({ parameters, name: 'Ada', room: null }); // remove
+ * ```
+ */
+export declare function assignParticipantToBreakoutRoom({ parameters, name, room, newParticipantAction, }: AssignParticipantToBreakoutRoomOptions): Promise<{
+    ok: boolean;
+    error: string;
+}>;
+export type StopBreakoutRoomsType = (options: HeadlessOptions) => Promise<{
+    ok: boolean;
+    error: string;
+}>;
+/** Close every breakout room and return everyone to the main room. */
+export declare function stopBreakoutRooms({ parameters, }: HeadlessOptions): Promise<{
+    ok: boolean;
+    error: string;
+}>;
+export type ReapplyLocalPlaybackType = (options: HeadlessOptions) => Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+/**
+ * Re-assert every local playback choice.
+ *
+ * Call this whenever media changes — `onMediaChanged` is the natural place. The
+ * SDK layout pass resumes consumers it believes should be visible, which would
+ * otherwise silently undo "do not play this person to me" the moment the active
+ * speaker changes. Without this the feature appears to work and then quietly
+ * stops working, which is worse than not having it.
+ *
+ * A no-op when nothing is locally paused.
+ */
+export declare function reapplyLocalPlayback({ parameters, }: HeadlessOptions): Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+/** Producer ids currently muted for this viewer only. */
+export declare function getLocallyPausedProducerIds(): string[];
+//# sourceMappingURL=sessionExtras.d.ts.map

package/dist/methods/utils/headless/sessionExtras.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionExtras.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/sessionExtras.ts"],"names":[],"mappings":"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"}