@signalwire/js 4.0.0-beta.11 → 4.0.0-beta.13

package/dist/index.d.mts

@@ -84,7 +84,7 @@ type WebSocketAdapter = new (url: string | URL, protocols?: string | string[]) =
  * At least one of `token` or `authorizationState` must be provided.
  */
 interface SDKCredential {
-  /** JWT subscriber access token (SAT). */
+  /** JWT user access token (SAT). */
   token?: string;
   /** Pre-authorized session state (alternative to token). */
   authorizationState?: string;
@@ -134,8 +134,25 @@ interface AuthenticateContext {
  * - Setting `expiry_at` when the credential has a known expiration so the SDK can schedule refresh.
  * - Handling errors and never leaking sensitive data through error messages.
  *
- * The SDK owns the credential lifecycle: it calls `authenticate` once during initialization
- * and, if `refresh` is provided and `expiry_at` is set, schedules automatic refresh before expiry.
+ * ## Refresh precedence
+ *
+ * The SDK selects exactly one refresh mechanism per session, evaluated at connect
+ * time (and re-evaluated on reconnect):
+ *
+ * | `refresh` provided | SAT carries `sat:refresh` scope | Active mechanism                     |
+ * | ------------------ | -------------------------------- | ------------------------------------ |
+ * | yes                | yes                              | Client Bound SAT (DPoP, internal)    |
+ * | yes                | no                               | Developer-provided `refresh()`       |
+ * | no                 | yes                              | Client Bound SAT (DPoP, internal)    |
+ * | no                 | no                               | None — session ends at `expiry_at`   |
+ *
+ * When the SDK falls back to the developer-provided `refresh()` because the SAT
+ * lacked `sat:refresh` scope, a `credential_refresh_fallback` event is emitted on
+ * `SignalWire.warnings$` so application code can observe the transition.
+ *
+ * Mint a SAT via `POST /api/fabric/subscribers/tokens` with `fingerprint` and
+ * `scope: ["sat:refresh"]` (both currently optional on that endpoint) to enable
+ * the Client Bound SAT path; otherwise provide `refresh()` here.
  */
 interface CredentialProvider {
   /**
@@ -146,6 +163,8 @@ interface CredentialProvider {
    * - Reject (throw) on failure — this will cause client initialization to fail.
    * - When `context.fingerprint` is provided, forward it to the server-side token
    *   endpoint with `scope: "sat:refresh"` to enable automatic token refresh.
+   *   Ignoring `context.fingerprint` causes the SDK to fall back to `refresh()`
+   *   (if provided) or end the session at expiry.
    *
    * SDK behavior:
    * - Awaits this method before establishing the WebSocket connection.
@@ -160,14 +179,12 @@ interface CredentialProvider {
    * - Reject (throw) if refresh is not possible — the SDK will stop the refresh schedule.
    *
    * SDK behavior:
-   * - Only called when `expiry_at` was set on the previous credential.
+   * - Only called when `expiry_at` was set on the previous credential AND the
+   *   SAT does not carry `sat:refresh` scope (otherwise the SDK refreshes
+   *   internally via Client Bound SAT). See the precedence table above.
    * - Scheduled automatically before expiry; implementors do not need to manage timing.
    * - On rejection, the refresh schedule stops and the session continues with the
    *   current credentials until they expire.
-   * - When not provided and the SAT includes a `sat:refresh` scope, the SDK
-   *   automatically refreshes via Client Bound SAT (DPoP) without developer intervention.
-   * - When not provided and no refresh scope is present, the SDK uses the initial
-   *   credentials for the entire session lifetime.
    */
   refresh?: () => Promise<SDKCredential>;
 }
@@ -325,6 +342,12 @@ interface MediaOptions {
   receiveAudio?: boolean;
   /** Whether to receive remote video. */
   receiveVideo?: boolean;
+  /**
+   * When local media can't be acquired (permission denied or device
+   * unavailable), continue the call in receive-only mode instead of failing.
+   * Defaults to `true`. Ignored when the call is not set to receive any media.
+   */
+  fallbackToReceiveOnly?: boolean;
 }
 //#endregion
 //#region src/containers/PreferencesContainer.d.ts
@@ -520,7 +543,7 @@ interface HTTPRequestControllerOptions {
   retryDelayMax?: number;
   requestTimeout?: number;
 }
-declare class HTTPRequestController {
+declare class HTTPRequestController extends Destroyable {
   private baseURL;
   private readonly getCredential;
   private static readonly defaultMaxRetries;
@@ -626,57 +649,57 @@ interface SATClaims {
   expires_at?: number;
 }
 //#endregion
-//#region src/core/types/subscriber.types.d.ts
-/** Raw subscriber profile response from the SignalWire Fabric API. */
-interface GetSubscriberInfoResponse {
-  /** Unique subscriber identifier. */
+//#region src/core/types/user.types.d.ts
+/** Raw user profile response from the SignalWire Fabric API. */
+interface GetUserInfoResponse {
+  /** Unique user identifier. */
   id: string;
-  /** Subscriber's email address. */
+  /** User's email address. */
   email: string;
-  /** Subscriber's first name. */
+  /** User's first name. */
   first_name?: string;
-  /** Subscriber's last name. */
+  /** User's last name. */
   last_name?: string;
-  /** Subscriber's display name. */
+  /** User's display name. */
   display_name?: string;
-  /** Subscriber's job title. */
+  /** User's job title. */
   job_title?: string;
-  /** Subscriber's time zone offset. */
+  /** User's time zone offset. */
   time_zone?: number;
-  /** Subscriber's country. */
+  /** User's country. */
   country?: string;
-  /** Subscriber's region or state. */
+  /** User's region or state. */
   region?: string;
-  /** Subscriber's company name. */
+  /** User's company name. */
   company_name?: string;
   /** Key for push notification delivery. */
   push_notification_key: string;
-  /** Application-level settings for this subscriber. */
+  /** Application-level settings for this user. */
   app_settings?: {
     /** Display name configured at the application level. */
     display_name: string;
-    /** Permission scopes granted to this subscriber. */
+    /** Permission scopes granted to this user. */
     scopes: string[];
   };
-  /** Fabric addresses associated with this subscriber. */
+  /** Fabric addresses associated with this user. */
   fabric_addresses: GetAddressResponse[];
   /** Filtered SAT claims (scope, cnf, expires_at) returned when the token has special capabilities. */
   sat_claims?: SATClaims;
 }
 //#endregion
-//#region src/core/entities/Subscriber.d.ts
-/** Subscriber online presence state. */
-type SubscriberPresence = 'online' | 'offline' | 'busy';
+//#region src/core/entities/User.d.ts
+/** User online presence state. */
+type UserPresence = 'online' | 'offline' | 'busy';
 /**
- * Authenticated subscriber profile.
+ * Authenticated user profile.
  *
  * Fetched automatically when a {@link SignalWire} connects.
  * Contains identity, contact, and organization details.
  */
-declare class Subscriber extends Fetchable<GetSubscriberInfoResponse> {
-  /** Unique subscriber identifier. */
+declare class User extends Fetchable<GetUserInfoResponse> {
+  /** Unique user identifier. */
   id: string;
-  /** Subscriber email address. */
+  /** User email address. */
   email: string;
   /** First name. */
   firstName?: string;
@@ -701,12 +724,12 @@ declare class Subscriber extends Fetchable<GetSubscriberInfoResponse> {
     displayName: string;
     scopes: string[];
   };
-  /** Fabric addresses associated with this subscriber. */
+  /** Fabric addresses associated with this user. */
   addresses: GetAddressResponse[];
   /** Filtered SAT claims when the token has special capabilities (e.g., refresh scope). */
   satClaims?: SATClaims;
   constructor(http: HTTPRequestController);
-  protected populateInstance(data: GetSubscriberInfoResponse): void;
+  protected populateInstance(data: GetUserInfoResponse): void;
 }
 //#endregion
 //#region src/core/types/call.types.d.ts
@@ -795,7 +818,7 @@ interface Member {
   member_id: string;
   call_id: string;
   name: string;
-  type: 'member' | 'screen';
+  type: 'member' | 'screen' | 'device' | (string & {});
   parent_id?: string;
   requested_position?: string;
   handraised: boolean;
@@ -803,17 +826,17 @@ interface Member {
   audio_muted: boolean;
   video_muted: boolean;
   deaf: boolean;
-  input_volume: number;
-  output_volume: number;
-  input_sensitivity: number;
+  input_volume?: number;
+  output_volume?: number;
+  input_sensitivity?: number;
   echo_cancellation: boolean;
   auto_gain: boolean;
   noise_suppression: boolean;
   lowbitrate: boolean;
   denoise: boolean;
-  talking: boolean;
-  isAudience: boolean;
-  meta: Record<string, unknown>;
+  talking?: boolean;
+  isAudience?: boolean;
+  meta?: Record<string, unknown>;
   subscriber_id: string;
   address_id: string;
   updated?: string[];
@@ -935,6 +958,15 @@ interface RoomUpdatedPayload {
   room_id: string;
   room_session_id: string;
 }
+/**
+ * Describes the peer (remote) call referenced from a call.state event.
+ *
+ * Mirrors the backend (relay.c) `peer` shape.
+ */
+interface CallStateRelatedCall {
+  call_id?: string;
+  node_id?: string;
+}
 interface CallStatePayload {
   call_id: string;
   node_id: string;
@@ -942,10 +974,19 @@ interface CallStatePayload {
   call_state: SignalingCallStates;
   direction: CallDirection;
   device: CallDevice;
-  start_time: number;
-  answer_time: number;
-  end_time: number;
+  /**
+   * Epoch timestamps for the call lifecycle. Optional because pre-answer
+   * states (e.g. `created`, `ringing`) do not have an `answer_time`/`end_time`
+   * and the backend reports them as `0` or omits them.
+   */
+  start_time?: number;
+  answer_time?: number;
+  end_time?: number;
   room_session_id: string;
+  /** The peer (remote) call this call is connected to, if any. */
+  peer?: CallStateRelatedCall;
+  /** Application-defined tag associated with the call. */
+  tag?: string;
 }
 interface CallPlayPayload {
   control_id: string;
@@ -1132,6 +1173,14 @@ declare class CallCreateError extends Error {
   direction: 'inbound' | 'outbound';
   constructor(message: string, error?: unknown, direction?: 'inbound' | 'outbound', options?: ErrorOptions);
 }
+declare class CallNotReadyError extends Error {
+  callId: string;
+  constructor(callId: string, options?: ErrorOptions);
+}
+declare class ParticipantNotReadyError extends Error {
+  memberId: string;
+  constructor(memberId: string, options?: ErrorOptions);
+}
 declare class VertoPongError extends Error {
   originalError: unknown;
   constructor(originalError: unknown);
@@ -1151,6 +1200,32 @@ declare class MediaTrackError extends Error {
   originalError: unknown;
   constructor(operation: string, kind: string, originalError: unknown);
 }
+/**
+ * Failure to acquire local media (camera, microphone, or screen capture)
+ * via `getUserMedia`/`getDisplayMedia`.
+ *
+ * Non-fatal by default: screenshare and additional-device failures never
+ * end the call, and main-connection failures degrade to receive-only when
+ * possible. The wrapping site sets `fatal` to `true` only when the call
+ * cannot continue (receive-only fallback disabled or no receive intent).
+ */
+declare class MediaAccessError extends Error {
+  /** The SDK operation that failed, e.g. `'acquireLocalMedia'`, `'startScreenShare'`, `'addInputDevice'`. */
+  operation: string;
+  /** The media being acquired: `'audio' | 'video' | 'audiovideo' | 'screen'`. */
+  media: string;
+  /** The raw `getUserMedia`/`getDisplayMedia` error (typically a `DOMException`). */
+  originalError: unknown;
+  /** Whether this failure terminates the call. */
+  readonly fatal: boolean;
+  constructor(/** The SDK operation that failed, e.g. `'acquireLocalMedia'`, `'startScreenShare'`, `'addInputDevice'`. */
+  operation: string, /** The media being acquired: `'audio' | 'video' | 'audiovideo' | 'screen'`. */
+  media: string, /** The raw `getUserMedia`/`getDisplayMedia` error (typically a `DOMException`). */
+  originalError: unknown, /** Whether this failure terminates the call. */
+  fatal?: boolean);
+  /** True when the underlying failure is a permission denial (user or policy). */
+  get denied(): boolean;
+}
 declare class DPoPInitError extends Error {
   originalError: unknown;
   constructor(originalError: unknown, message?: string);
@@ -1491,6 +1566,8 @@ interface MemberCapabilities {
   readonly meta: boolean;
   readonly remove: boolean;
   readonly audioFlags: boolean;
+  readonly denoise: boolean;
+  readonly lowbitrate: boolean;
 }
 /**
  * Call-level capabilities state
@@ -1720,12 +1797,12 @@ type ParticipantState = Member & {
  * the local participant with additional device control.
  */
 declare class Participant extends Destroyable implements CallParticipant {
-  protected executeMethod: ExecuteMethod;
+  private callExecuteMethod;
   protected deviceController: DeviceController;
   /** Unique member ID of this participant. */
   readonly id: string;
   private _state$;
-  constructor(id: string, executeMethod: ExecuteMethod, deviceController: DeviceController);
+  constructor(id: string, callExecuteMethod: ExecuteMethod, deviceController: DeviceController);
   /** @internal */
   upnext(data: Partial<ParticipantState>): void;
   /** Observable of the participant's display name. */
@@ -1742,11 +1819,31 @@ declare class Participant extends Destroyable implements CallParticipant {
   get videoMuted$(): Observable<boolean | undefined>;
   /** Observable indicating whether the participant is deafened. */
   get deaf$(): Observable<boolean | undefined>;
-  /** Observable of the participant's microphone input volume. */
+  /**
+   * Observable of the participant's **server-side** microphone input volume
+   * as reported by the mix engine. This is gain applied on the bridged audio
+   * leg (FreeSWITCH channel read volume), NOT the local browser mic. For a
+   * local PC mic control, see {@link Call.setLocalMicrophoneGain}.
+   *
+   * @see {@link setAudioInputVolume}
+   */
   get inputVolume$(): Observable<number | undefined>;
-  /** Observable of the participant's speaker output volume. */
+  /**
+   * Observable of the participant's **server-side** speaker output volume as
+   * reported by the mix engine (FreeSWITCH channel write volume). NOT the
+   * local HTML `<audio>` element volume — set that on your own element.
+   *
+   * @see {@link setAudioOutputVolume}
+   */
   get outputVolume$(): Observable<number | undefined>;
-  /** Observable of the microphone input sensitivity level. */
+  /**
+   * Observable of the **conference-only** microphone energy/gate sensitivity
+   * level for this member. Routes through the conferencing mix engine and has
+   * no effect on 1:1 WebRTC calls. Populated from `member.updated` events for
+   * conference members.
+   *
+   * @see {@link setAudioInputSensitivity}
+   */
   get inputSensitivity$(): Observable<number | undefined>;
   /** Observable indicating whether echo cancellation is enabled. */
   get echoCancellation$(): Observable<boolean | undefined>;
@@ -1760,8 +1857,8 @@ declare class Participant extends Destroyable implements CallParticipant {
   get denoise$(): Observable<boolean | undefined>;
   /** Observable of custom metadata for this participant. */
   get meta$(): Observable<Record<string, unknown> | undefined>;
-  /** Observable of the participant's subscriber ID. */
-  get subscriberId$(): Observable<string | undefined>;
+  /** Observable of the participant's user ID. */
+  get userId$(): Observable<string | undefined>;
   /** Observable of the participant's address ID. */
   get addressId$(): Observable<string | undefined>;
   /** Observable of the server node ID for this participant. */
@@ -1790,11 +1887,21 @@ declare class Participant extends Destroyable implements CallParticipant {
   get videoMuted(): boolean;
   /** Whether the participant is deafened (incoming audio muted). */
   get deaf(): boolean;
-  /** Current microphone input volume level, or `undefined` if not set. */
+  /**
+   * Current **server-side** microphone input volume as reported by the mix
+   * engine, or `undefined` if not set. Not the local PC mic — see
+   * {@link Call.setLocalMicrophoneGain} for browser-side control.
+   */
   get inputVolume(): number | undefined;
-  /** Current speaker output volume level, or `undefined` if not set. */
+  /**
+   * Current **server-side** speaker output volume from the mix engine, or
+   * `undefined` if not set. Not the local `<audio>` element volume.
+   */
   get outputVolume(): number | undefined;
-  /** Current microphone input sensitivity level, or `undefined` if not set. */
+  /**
+   * Current **conference-only** microphone sensitivity/gate level, or
+   * `undefined` if not set. Applies only to conference members.
+   */
   get inputSensitivity(): number | undefined;
   /** Whether echo cancellation is enabled. */
   get echoCancellation(): boolean;
@@ -1808,14 +1915,40 @@ declare class Participant extends Destroyable implements CallParticipant {
   get denoise(): boolean;
   /** Custom metadata for this participant, or `undefined` if not set. */
   get meta(): Record<string, unknown> | undefined;
-  /** Subscriber ID of this participant, or `undefined` if not available. */
-  get subscriberId(): string | undefined;
+  /** User ID of this participant, or `undefined` if not available. */
+  get userId(): string | undefined;
   /** Address ID of this participant, or `undefined` if not available. */
   get addressId(): string | undefined;
   /** Server node ID for this participant, or `undefined` if not available. */
   get nodeId(): string | undefined;
+  /** Call ID for this participant's leg, or `undefined` if not available. */
+  get callId(): string | undefined;
   /** @internal */
   get value(): Partial<Member>;
+  /**
+   * Target triple for member RPCs, built from the participant's own state.
+   * The backend locates the member's session by the target `call_id`/`node_id`,
+   * so this must always be the participant's own call context — never the
+   * local call's id (issue #19400).
+   *
+   * Reading it doubles as a readiness probe: it throws until the first full
+   * member event (`member.joined`/`member.updated` or the `call.joined`
+   * roster) arrives, and never regresses afterwards.
+   *
+   * @throws {ParticipantNotReadyError} If the member state has not been
+   * received yet (e.g. a participant first seen via `member.talking`) — an
+   * empty call context can never address the member, so fail fast instead of
+   * sending a doomed RPC.
+   */
+  get target(): MemberTarget;
+  /**
+   * Executes a member RPC against this participant, injecting its own
+   * {@link target} as the target.
+   *
+   * @throws {ParticipantNotReadyError} Via {@link target}, when the
+   * member state has not been received yet.
+   */
+  protected executeMethod(method: string, args: Record<string, unknown>): Promise<JSONRPCResponse>;
   /** Toggles the deafened state (mutes/unmutes incoming audio). */
   toggleDeaf(): Promise<void>;
   /** Toggles the hand-raised state. */
@@ -1838,21 +1971,53 @@ declare class Participant extends Destroyable implements CallParticipant {
   toggleAudioInputAutoGain(): Promise<void>;
   /** Toggles noise suppression on the audio input. */
   toggleNoiseSuppression(): Promise<void>;
+  /** Toggles low-bitrate mode for this participant's media. */
   toggleLowbitrate(): Promise<void>;
-  /** Sets the microphone input sensitivity level. */
+  /**
+   * Adjusts the **conference-only** microphone energy gate / sensitivity level
+   * for this member. Routes through the conferencing mix engine
+   * (`signalwire.conferencing member.set_input_sensitivity`) and has no effect
+   * on 1:1 WebRTC calls — for those, use browser audio constraints via
+   * {@link Call.setNoiseSuppression} / {@link Call.setAutoGainControl}.
+   *
+   * This is **not** a local PC mic gain control; it only changes how the
+   * server-side mixer decides to open the mic gate on this participant.
+   *
+   * @param value - Sensitivity level as understood by the conference engine
+   *   (integer, larger values are more sensitive).
+   */
   setAudioInputSensitivity(value: number): Promise<void>;
   /**
-   * Sets the microphone input volume level.
+   * Sets the **server-side** microphone volume on this participant's bridged
+   * call leg. Applies a multiplier to the audio flowing through the mix
+   * engine (FreeSWITCH channel read volume) — changes what other participants
+   * hear, not what the local browser captures.
+   *
+   * For local PC mic gain, use {@link Call.setLocalMicrophoneGain} instead.
+   *
    * @param value - Volume level (0-100).
    */
   setAudioInputVolume(value: number): Promise<void>;
   /**
-   * Sets the speaker output volume level.
+   * Sets the **server-side** speaker volume on this participant's bridged call
+   * leg (FreeSWITCH channel write volume) — what this participant hears from
+   * the mix before it reaches their client.
+   *
+   * For local playback volume (the `<audio>` element the consumer attaches
+   * `remoteStream` to), set `audioElement.volume` directly in the consumer's
+   * code.
+   *
    * @param value - Volume level (0-100).
    */
   setAudioOutputVolume(value: number): Promise<void>;
   /**
    * Sets the participant's position in the video layout.
+   *
+   * Requires the `member.position` capability. The gateway requires a
+   * `targets` array of `{ target, position }` entries (issue #19400). A
+   * resolved promise does not guarantee a visible change: the backend silently
+   * returns `200` (no-op) for non-conference targets.
+   *
    * @param value - The {@link VideoPosition} to assign (e.g. `'auto'`, `'reserved-0'`).
    */
   setPosition(value: VideoPosition): Promise<void>;
@@ -1895,7 +2060,7 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
    */
   private _studioAudio$;
   /** @internal */
-  constructor(id: string, executeMethod: ExecuteMethod, vertoManager: VertoManager, deviceController: DeviceController);
+  constructor(id: string, callExecuteMethod: ExecuteMethod, vertoManager: VertoManager, deviceController: DeviceController);
   destroy(): void;
   /** Observable indicating whether studio audio (raw/unprocessed audio) mode is enabled. */
   get studioAudio$(): Observable<boolean>;
@@ -1911,7 +2076,15 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
    * Sets echoCancellation, noiseSuppression, and autoGainControl to true.
    */
   disableStudioAudio(): Promise<void>;
-  /** Starts sharing the local screen. */
+  /**
+   * Starts sharing the local screen.
+   *
+   * The call is unaffected when acquisition fails.
+   *
+   * @throws The raw `getDisplayMedia` error. A dismissed picker or a
+   * permission denial rejects with a `NotAllowedError` `DOMException` —
+   * inspect `error.name` to tell benign cancels apart from real failures.
+   */
   startScreenShare(): Promise<void>;
   /** Observable of the current screen share status. */
   get screenShareStatus$(): Observable<ScreenShareStatus>;
@@ -1919,7 +2092,14 @@ declare class SelfParticipant extends Participant implements CallSelfParticipant
   get screenShareStatus(): ScreenShareStatus;
   /** Stops the current screen share. */
   stopScreenShare(): Promise<void>;
-  /** Adds an additional media input device to the call. */
+  /**
+   * Adds an additional media input device to the call.
+   *
+   * The call is unaffected when acquisition fails.
+   *
+   * @throws The raw `getUserMedia` error (e.g. `NotAllowedError` on
+   * permission denial) — inspect `error.name` to decide how to react.
+   */
   addAdditionalDevice(options: MediaOptions): Promise<void>;
   /** Removes an additional media input device by ID. */
   removeAdditionalDevice(id: string): Promise<void>;
@@ -2002,7 +2182,7 @@ interface CallParticipant {
   readonly lowbitrate$: Observable<boolean | undefined>;
   readonly denoise$: Observable<boolean | undefined>;
   readonly meta$: Observable<Record<string, unknown> | undefined>;
-  readonly subscriberId$: Observable<string | undefined>;
+  readonly userId$: Observable<string | undefined>;
   readonly addressId$: Observable<string | undefined>;
   readonly nodeId$: Observable<string | undefined>;
   readonly isTalking$: Observable<boolean | undefined>;
@@ -2023,9 +2203,13 @@ interface CallParticipant {
   readonly lowbitrate: boolean;
   readonly denoise: boolean;
   readonly meta: Record<string, unknown> | undefined;
-  readonly subscriberId: string | undefined;
+  readonly userId: string | undefined;
   readonly addressId: string | undefined;
   readonly nodeId: string | undefined;
+  readonly callId: string | undefined;
+  /** The member's own RPC target triple. Throws `ParticipantNotReadyError`
+   *  until the member's call context has been received. */
+  readonly target: MemberTarget;
   readonly isTalking: boolean;
   readonly position: LayoutLayer | undefined;
   readonly isAudience: boolean;
@@ -2107,7 +2291,12 @@ interface CallAddress {
 type CallStatus = 'new' | 'trying' | 'ringing' | 'connecting' | 'connected' | 'recovering' | 'disconnecting' | 'disconnected' | 'failed' | 'destroyed';
 /** Configuration options for creating a call. */
 interface CallOptions extends MediaOptions {
-  /** Target server node ID. */
+  /**
+   * Optional. Hint to the cluster about which node should host this call.
+   * Used by reattach to pin to the original node; on fresh dials acts as a
+   * steering preference (the server may ignore for placement reasons).
+   * Leave undefined for normal load-balanced placement.
+   */
   readonly nodeId?: string;
   /** Pre-assigned call ID (used for reattach). */
   readonly callId?: string;
@@ -2168,6 +2357,9 @@ interface Call extends CallState {
   readonly self$: Observable<CallSelfParticipant | null>;
   readonly self: CallSelfParticipant | null;
   readonly to?: string;
+  readonly toName?: string;
+  readonly from?: string;
+  readonly fromName?: string;
   readonly direction: CallDirection;
   readonly layouts$: Observable<string[]>;
   readonly layouts: string[];
@@ -2225,9 +2417,6 @@ interface Call extends CallState {
  */
 interface CallManager extends Call {
   readonly options: CallOptions;
-  readonly fromName?: string;
-  readonly from?: string;
-  readonly toName?: string;
   readonly selfId$: Observable<string | null>;
   readonly selfId: string | null;
   readonly nodeId$: Observable<string | null>;
@@ -2497,11 +2686,19 @@ declare class AttachManager {
   private readonly reconnectCallsTimeout;
   private attachKey;
   private session;
+  private writeQueue;
   constructor(storage: StorageManager, deviceController: DeviceController, reconnectCallsTimeout: number, attachKey: string);
   detachAll(): Promise<void>;
   setSession(session: OutboundCallProvider): void;
   private readAttached;
   private writeAttached;
+  /**
+   * Serialize a read-modify-write operation against the attached-calls
+   * storage. The mutator receives the current state and returns the new
+   * state. Concurrent calls queue behind the in-flight one so writes never
+   * interleave.
+   */
+  private mutate;
   attach(call: AttachableCall): Promise<void>;
   detach(call: AttachableCall): Promise<void>;
   flush(): Promise<void>;
@@ -2527,10 +2724,15 @@ declare class AttachManager {
    */
   buildCallOptions(attachment: Attachment): CallOptions;
   /**
-   * Consume stored attachment data for a pending call (used by session-level
-   * verto.attach handler as a future path when server supports it).
+   * Look up stored attachment data for a call id and return CallOptions
+   * suitable for rehydrating a reattached call. Returns undefined when no
+   * matching entry exists in storage.
+   *
+   * Used by the session-level verto.attach handler when the server pushes
+   * an attach event for a call the client doesn't have an object for yet
+   * (e.g. after a reload).
    */
-  consumePendingAttachment(_callId: string): CallOptions | undefined;
+  consumePendingAttachment(callId: string): Promise<CallOptions | undefined>;
   private detachExpired;
 }
 //#endregion
@@ -2826,14 +3028,14 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
   private _authState$;
   /** Sticky flag — once true, stays true for the session lifetime. */
   private _wasClientBound;
-  private _subscriberInfo$;
+  private _userInfo$;
   private _calls$;
   private _iceServers$;
   constructor(getCredential: () => SDKCredential, transport: TransportManager, storage: StorageManager, authorizationStateKey: string, deviceController: DeviceController, attachManager: AttachManager, webRTCApiProvider: WebRTCApiProvider, dpopManager?: CryptoController | undefined, networkChange$?: Observable<NetworkChangeEvent>);
   get incomingCalls$(): Observable<Call[]>;
   get incomingCalls(): Call[];
-  get subscriberInfo$(): Observable<Address | null>;
-  get subscriberInfo(): Address | null;
+  get userInfo$(): Observable<Address | null>;
+  get userInfo(): Address | null;
   get calls$(): Observable<Call[]>;
   get calls(): Call[];
   get iceServers(): RTCIceServer[] | undefined;
@@ -3022,7 +3224,34 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
   private get authentication();
   connect(): Promise<void>;
   private handleAuthenticationError;
+  /**
+   * Clear the resume state (authorization_state + protocol) only.
+   *
+   * This is the stale-auth-state recovery helper used by handleAuthError:
+   * the server rejected a reconnect, so the resume state is discarded and a
+   * fresh connect follows. Attach records are deliberately preserved — the
+   * session lives on through the reconnect and reattachCalls() needs the
+   * stored call references afterwards. Do NOT add detachAll() here.
+   *
+   * For public teardown (disconnect/destroy), use {@link teardownSessionState}
+   * instead, which clears the attach records as well.
+   */
   cleanupStoredConnectionParams(): Promise<void>;
+  /**
+   * Public-teardown helper for disconnect()/destroy(). Clears the resume
+   * state (authorization_state + protocol) AND the attach records as one
+   * atomic unit.
+   *
+   * The two stores are coupled: the backend only honors attach records
+   * within the session identified by the resume state, so ending the
+   * session must clear both. Clearing one without the other strands records
+   * no future session can honor (disconnect) or revives a session the
+   * developer explicitly ended (destroy).
+   *
+   * Distinct from {@link cleanupStoredConnectionParams}, which keeps the
+   * attach records for the stale-auth-state recovery path.
+   */
+  teardownSessionState(): Promise<void>;
   protected updateAuthState(authorization_state: string): Promise<void>;
   reauthenticate(token: string, dpopToken?: string, options?: {
     clientBound?: boolean;
@@ -3049,6 +3278,12 @@ declare class ClientSessionWrapper implements SessionState {
   constructor(clientSessionManager: ClientSessionManager);
   get authenticated$(): Observable<boolean>;
   get authenticated(): boolean;
+  /**
+   * Whether the session is using a Client Bound SAT (DPoP). Sticky — set
+   * when the binding is established or restored from a resumed session's
+   * server authorization.
+   */
+  get clientBound(): boolean;
   get signalingEvent$(): Observable<(Omit<{
     event_type: "webrtc.message";
     event_channel: EventChannel;
@@ -3207,6 +3442,60 @@ declare class ClientSessionWrapper implements SessionState {
   get calls(): Call[];
 }
 //#endregion
+//#region src/core/types/warnings.types.d.ts
+/**
+ * Non-fatal warning emitted via {@link SignalWire.warnings$ | client.warnings$}.
+ *
+ * Use to detect SDK behaviors that affect session liveness or developer-facing
+ * contracts but do not warrant disconnection. Discriminated by `code`.
+ *
+ * Existing consumers of `errors$` are NOT notified — `warnings$` is a separate
+ * channel so application code can react to warnings without triggering
+ * error-handling code paths (e.g., disconnect cascades, user-facing toasts).
+ */
+type SDKWarning = CredentialRefreshFallbackWarning | CredentialNoRefreshHandlerWarning;
+/**
+ * Diagnostic detail for {@link CredentialRefreshFallbackWarning}. Stable
+ * values, but treat unknown strings as "fell back for an unspecified cause" —
+ * do not branch on this value for control flow. New values may be added in
+ * future releases.
+ */
+type CredentialRefreshFallbackReason = 'no-scope' | 'no-dpop-support' | 'endpoint-failed' | 'activation-timeout' | (string & {});
+/**
+ * Emitted when the SDK falls back to the developer-provided
+ * {@link CredentialProvider.refresh} because the Client Bound SAT path
+ * could not take over.
+ *
+ * Common causes:
+ * - The minted SAT lacks `sat:refresh` scope (`reason: 'no-scope'`).
+ * - The `/devices/token` exchange failed transiently (`reason: 'endpoint-failed'`).
+ *
+ * Subscribe to this warning to detect:
+ * - SDKs running with plain SATs that rely on developer-managed refresh
+ * - Deployments expected to use bound tokens that silently downgraded to bearer
+ *   (a security-relevant signal for fleet observability)
+ */
+interface CredentialRefreshFallbackWarning {
+  code: 'credential_refresh_fallback';
+  source: 'CredentialProvider';
+  reason: CredentialRefreshFallbackReason;
+  message: string;
+}
+/**
+ * Emitted when a credential has an `expiry_at` but the provider supplies no
+ * `refresh()` handler. The session will terminate at expiry with no fallback.
+ *
+ * Implementors who want long-lived sessions must provide a `refresh()` handler
+ * or mint tokens with the `sat:refresh` scope (Client Bound SAT path).
+ */
+interface CredentialNoRefreshHandlerWarning {
+  code: 'credential_no_refresh_handler';
+  source: 'CredentialProvider';
+  message: string;
+  /** Token expiry timestamp (epoch milliseconds). */
+  expiresAt: number;
+}
+//#endregion
 //#region src/utils/logger.d.ts
 /** Log level names supported by the SDK. */
 type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
@@ -3221,11 +3510,30 @@ interface SDKLogger {
   debug(...args: unknown[]): void;
   trace(...args: unknown[]): void;
 }
+/** Options for WebSocket traffic logging. */
+interface WsTrafficOptions {
+  type: 'send' | 'recv' | 'http';
+  /** Parsed object or raw string — will be JSON.stringify'd for display if an object. */
+  payload: unknown;
+}
+/**
+ * Options for WebSocket traffic logging using raw strings.
+ * The string is only parsed when logging is enabled, avoiding
+ * unnecessary JSON.parse on every message.
+ */
+interface WsTrafficRawOptions {
+  type: 'send' | 'recv';
+  raw: string;
+}
 /** Debug options that control verbose SDK logging. */
 interface DebugOptions {
   /** Log all WebSocket send/recv traffic to the console. */
   logWsTraffic?: boolean;
 }
+/** Extended logger with SDK-internal helpers (wsTraffic). */
+interface InternalSDKLogger extends SDKLogger {
+  wsTraffic: (options: WsTrafficOptions | WsTrafficRawOptions) => void;
+}
 /** Replace the built-in logger with a custom implementation. Pass `null` to restore defaults. */
 declare const setLogger: (logger: SDKLogger | null) => void;
 /** Configure debug options (e.g., `{ logWsTraffic: true }`). */
@@ -3235,13 +3543,14 @@ declare const setDebugOptions: (options: DebugOptions | null) => void;
  * Has no effect when a custom logger is set via `setLogger()`.
  */
 declare const setLogLevel: (level: LogLevel) => void;
+declare const getLogger: () => InternalSDKLogger;
 //#endregion
 //#region src/clients/SignalWire.d.ts
 /** Options for constructing a {@link SignalWire}. */
 interface SignalWireOptions {
   /** Skip automatic WebSocket connection on construction. */
   skipConnection?: boolean;
-  /** Skip automatic subscriber registration on construction. */
+  /** Skip automatic user registration on construction. */
   skipRegister?: boolean;
   /** Skip monitoring media device changes. */
   skipDeviceMonitoring?: boolean;
@@ -3260,8 +3569,12 @@ interface SignalWireOptions {
    * When `false` (default), session data lives in `sessionStorage` and is
    * lost on reload.
    *
-   * Call {@link SignalWire.destroy | destroy()} to clear all persisted state
-   * (explicit logout).
+   * Both {@link SignalWire.disconnect | disconnect()} and
+   * {@link SignalWire.destroy | destroy()} end the session and clear the
+   * persisted resume state and attach records; credentials and device
+   * preferences survive. Use `resetToDefaults()` for a full wipe, or
+   * `unregister()` to temporarily stop receiving inbound calls while keeping
+   * the session alive.
    */
   persistSession?: boolean;
   /** Custom storage implementation for persistence. */
@@ -3298,6 +3611,12 @@ interface DialOptions extends MediaOptions {
   stereo?: boolean;
   /** Optional node ID for routing the call */
   nodeId?: string;
+  /**
+   * Custom variables sent with the Verto invite. Merged with
+   * `client.preferences.userVariables` and any query-string variables on the
+   * destination URI; values here take precedence.
+   */
+  userVariables?: Record<string, unknown>;
 }
 /**
  * Main entry point for the SignalWire Browser SDK.
@@ -3314,7 +3633,7 @@ interface DialOptions extends MediaOptions {
 declare class SignalWire extends Destroyable implements DeviceController {
   /** Global SDK preferences (timeouts, ICE config, media defaults). */
   preferences: ClientPreferences;
-  private _subscriber$;
+  private _user$;
   private _directory$;
   private _transport;
   private _clientSession;
@@ -3324,10 +3643,10 @@ declare class SignalWire extends Destroyable implements DeviceController {
   private _isConnected$;
   private _isRegistered$;
   private _errors$;
+  private _warnings$;
   private _options;
-  private _refreshTimerId?;
   private _dpopManager?;
-  private _deviceTokenManager?;
+  private _refreshCoordinator?;
   private _credentialProvider?;
   private _deps;
   private _networkMonitor?;
@@ -3356,11 +3675,58 @@ declare class SignalWire extends Destroyable implements DeviceController {
   private resolveCredentials;
   private validateCredentials;
   /**
-   * Schedules credential refresh with exponential backoff retry on failure.
-   * On success, resets attempt counter and schedules the next refresh.
-   * After exhausting retries, emits TokenRefreshError and disconnects.
+   * Reauthenticate the currently-open session with a freshly obtained
+   * credential so the new token takes effect on the live socket immediately —
+   * not just on the next reconnect. No-op when the session is not
+   * connected/authenticated or the credential carries no token (e.g. an
+   * authorization-state-only refresh). Non-fatal: reauth failures surface on
+   * `errors$` without aborting the refresh that triggered this.
+   */
+  private reauthenticateLiveSession;
+  /**
+   * One-shot recovery for a live session that failed with a recoverable auth
+   * error (`-32002`/`-32003`) because its token went stale — e.g. a refresh
+   * timer that was throttled while the tab was backgrounded.
+   *
+   * Two steps, first that succeeds wins:
+   *   1. Reauthenticate with the in-memory token (a fresh DPoP proof is
+   *      generated automatically). Heals a session whose token was already
+   *      refreshed by the coordinator but never applied to the open socket,
+   *      and a client-bound session whose server-side auth merely drifted.
+   *   2. Re-mint via the developer provider's `refresh()` and reauthenticate.
+   *      Skipped for client-bound sessions (the DeviceTokenManager owns their
+   *      refresh; re-minting a base SAT here would drop the DPoP binding).
+   *
+   * @param allowRemint - Whether step 2 (provider re-mint) may run. Callers
+   *   pass `false` for non-auth failures so a transient network error never
+   *   escalates to a token re-mint; step 1 (in-memory reauth) always runs.
+   * @returns `true` if the session was reauthenticated, `false` otherwise.
+   */
+  private recoverStaleCredential;
+  /**
+   * Re-mint a credential via `provider.refresh()`, routed through the
+   * coordinator's shared in-flight guard so concurrent re-mint paths (a
+   * scheduled/resume refresh, -32003 recovery, and reconnect) never fire a
+   * second `provider.refresh()` in parallel — which rotating one-time-use
+   * refresh tokens reject. Falls back to a direct call only if the coordinator
+   * has not been constructed yet.
+   */
+  private remintCredential;
+  /**
+   * Re-mint credentials before a fresh (re)connect (`onBeforeReconnect` hook).
+   * The session invokes this only when it is client-bound OR the in-memory
+   * token is expired. The re-mint mechanism depends on the binding:
+   *   - Client-bound: `authenticate()` with the DPoP fingerprint to obtain a
+   *     fresh base SAT the upcoming reconnect can re-bind (the
+   *     DeviceTokenManager re-activates afterwards).
+   *   - Unbound: the developer's non-interactive `refresh()` handler.
+   *     `authenticate()` is deliberately NOT used here — it may be interactive
+   *     (a login prompt) and must not fire on a background reconnect.
+   *
+   * Rejects on failure so the session aborts the reconnect rather than
+   * replaying a stale token.
    */
-  private scheduleCredentialRefresh;
+  private refreshCredentialForReconnect;
   /** Persist credential to localStorage when persistSession is enabled. */
   private persistCredential;
   private init;
@@ -3404,19 +3770,19 @@ declare class SignalWire extends Destroyable implements DeviceController {
    */
   connect(): Promise<void>;
   /**
-   * Observable that emits the {@link Subscriber} profile once fetched,
+   * Observable that emits the {@link User} profile once fetched,
    * or `undefined` before authentication completes.
    *
    * @example
    * ```ts
-   * client.subscriber$.subscribe(sub => {
-   *   if (sub) console.log('Logged in as', sub.email);
+   * client.user$.subscribe(u => {
+   *   if (u) console.log('Logged in as', u.email);
    * });
    * ```
    */
-  get subscriber$(): Observable<Subscriber | undefined>;
-  /** Current subscriber snapshot, or `undefined` if not yet authenticated. */
-  get subscriber(): Subscriber | undefined;
+  get user$(): Observable<User | undefined>;
+  /** Current user snapshot, or `undefined` if not yet authenticated. */
+  get user(): User | undefined;
   /**
    * Observable that emits the {@link Directory} instance once the client is connected,
    * or `undefined` while disconnected. Subscribe to this to safely wait for the directory
@@ -3435,9 +3801,9 @@ declare class SignalWire extends Destroyable implements DeviceController {
    * Prefer {@link directory$} when you need to react to the directory becoming available.
    */
   get directory(): Directory | undefined;
-  /** Observable that emits when the subscriber registration state changes. */
+  /** Observable that emits when the user registration state changes. */
   get isRegistered$(): Observable<boolean>;
-  /** Whether the subscriber is currently registered. */
+  /** Whether the user is currently registered. */
   get isRegistered(): boolean;
   /** Whether the client is currently connected. */
   get isConnected(): boolean;
@@ -3447,6 +3813,17 @@ declare class SignalWire extends Destroyable implements DeviceController {
   get ready$(): Observable<boolean>;
   /** Observable stream of errors from transport, authentication, and devices. */
   get errors$(): Observable<Error>;
+  /**
+   * Observable stream of non-fatal SDK warnings.
+   *
+   * Subscribe to detect SDK behaviors that affect session liveness or developer-facing
+   * contracts but do not warrant disconnection — e.g., a fallback from Client Bound SAT
+   * refresh to the developer-provided `refresh()` because the SAT lacks `sat:refresh`
+   * scope. Discriminated by `code`.
+   *
+   * Independent from {@link errors$}: existing error consumers are not notified.
+   */
+  get warnings$(): Observable<SDKWarning>;
   /** Platform WebRTC capabilities detected at construction time. */
   get platformCapabilities(): PlatformCapabilities;
   /** Observable that emits when the SDK auto-switches a device. */
@@ -3464,13 +3841,26 @@ declare class SignalWire extends Destroyable implements DeviceController {
   /**
    * Disconnects the WebSocket and tears down the current session.
    *
+   * Ends the session identified by the protocol and clears its persisted
+   * resume state (`authorization_state` + protocol) and attach records
+   * together — a later {@link connect} with the same credentials starts a
+   * fresh session and cannot reattach to the ended session's calls.
+   * Credentials and device preferences are preserved. To temporarily stop
+   * receiving inbound calls while keeping the session alive, use
+   * `unregister()` instead.
+   *
    * The client can be reconnected by calling {@link connect} again,
    * which creates a fresh transport and session.
    */
   disconnect(): Promise<void>;
+  /**
+   * Tear down the current transport / session / attach manager. Safe to call
+   * when nothing has been initialized yet (e.g. first connect()).
+   */
+  private teardownTransportAndSession;
   private waitAuthentication;
   /**
-   * Registers the subscriber as online to receive inbound calls and events.
+   * Registers the user as online to receive inbound calls and events.
    *
    * Waits for authentication to complete before sending the registration.
    * If the initial attempt fails, reauthentication is attempted automatically.
@@ -3479,7 +3869,7 @@ declare class SignalWire extends Destroyable implements DeviceController {
    */
   register(): Promise<void>;
   /**
-   * Unregisters the subscriber, going offline for inbound calls.
+   * Unregisters the user, going offline for inbound calls.
    *
    * The WebSocket connection remains open; use {@link disconnect} to fully close it.
    */
@@ -3568,6 +3958,21 @@ declare class SignalWire extends Destroyable implements DeviceController {
   selectVideoInputDevice(device: MediaDeviceInfo | null): void;
   /** Sets the preferred audio output device. */
   selectAudioOutputDevice(device: MediaDeviceInfo | null): void;
+  /**
+   * Apply the currently selected audio output device to an HTMLMediaElement
+   * (e.g. the `<audio>` or `<video>` element the consumer attached the
+   * remote stream to). Uses `HTMLMediaElement.setSinkId` under the hood.
+   * Returns a `Promise<boolean>`: `true` if the sink was applied,
+   * `false` if the browser doesn't support `setSinkId` or no device is
+   * selected.
+   *
+   * @example
+   * ```ts
+   * audioEl.srcObject = call.remoteStream;
+   * await client.applySelectedAudioOutputDevice(audioEl);
+   * ```
+   */
+  applySelectedAudioOutputDevice(element: HTMLMediaElement): Promise<boolean>;
   /** Starts monitoring for media device changes (connect/disconnect). */
   enableDeviceMonitoring(): void;
   /** Stops monitoring for media device changes. */
@@ -3625,7 +4030,15 @@ declare class SignalWire extends Destroyable implements DeviceController {
    * attached call IDs, and all SDK storage keys, then re-enumerates devices.
    */
   resetToDefaults(): Promise<void>;
-  /** Destroys the client, clearing timers and releasing all resources. */
+  /**
+   * Destroys the client, clearing timers and releasing all resources.
+   *
+   * Intentionally destroying the client ends its session: the resume state
+   * (`authorization_state` + protocol) and the attach records are both
+   * cleared. Credentials and device preferences are preserved — use
+   * {@link resetToDefaults} for a full wipe. To temporarily stop receiving
+   * inbound calls while keeping the session alive, use `unregister()`.
+   */
   destroy(): void;
 }
 //#endregion
@@ -3668,6 +4081,126 @@ declare class StaticCredentialProvider implements CredentialProvider {
   authenticate(): Promise<SDKCredential>;
 }
 //#endregion
+//#region src/dependencies/EmbedTokenCredentialProvider.d.ts
+/** Credential provider that exchanges an embed token for a SAT via the host's token endpoint. */
+declare class EmbedTokenCredentialProvider implements CredentialProvider {
+  private host;
+  private embedToken;
+  constructor(host: string, embedToken: string);
+  private fetchSAT;
+  authenticate(): Promise<{
+    token: string;
+    expiry_at: number;
+  }>;
+  refresh(): Promise<{
+    token: string;
+    expiry_at: number;
+  }>;
+}
+//#endregion
+//#region src/controllers/LocalAudioPipeline.d.ts
+/**
+ * Options for {@link LocalAudioPipeline}.
+ */
+interface LocalAudioPipelineOptions {
+  /** Factory for AudioContext — override for tests. Defaults to `new AudioContext()`. */
+  audioContextFactory?: () => AudioContext;
+  /** Initial gain (0..2, where 1 is unity). Defaults to 1. */
+  initialGain?: number;
+  /** RMS level [0..1] above which speaking$ emits true. Defaults to {@link VAD_THRESHOLD}. */
+  speakingThreshold?: number;
+  /**
+   * Milliseconds of silence below the threshold before speaking$ flips back to
+   * false. Prevents flicker on normal speech gaps. Defaults to {@link VAD_HOLD_MS}.
+   */
+  speakingHoldMs?: number;
+  /** Polling interval for level$. Defaults to {@link AUDIO_LEVEL_POLL_INTERVAL_MS}. */
+  pollIntervalMs?: number;
+}
+/**
+ * Web Audio pipeline for the local microphone stream.
+ *
+ * Wraps the raw mic `MediaStreamTrack` in a graph of:
+ *
+ * ```
+ *   MediaStreamAudioSourceNode  →  GainNode  →  AnalyserNode  →  MediaStreamAudioDestinationNode
+ * ```
+ *
+ * The {@link outputTrack} from the destination node is what callers should
+ * attach to the `RTCRtpSender` in place of the raw mic track. The same
+ * destination track is reused across input changes (device switch, mute /
+ * unmute track replacement) so the sender reference stays stable — only the
+ * source end of the graph is rebuilt.
+ *
+ * The pipeline owns a single {@link AudioContext}. Callers must invoke
+ * {@link destroy} to release it when the call ends.
+ */
+declare class LocalAudioPipeline extends Destroyable {
+  private readonly _audioContext;
+  private readonly _gainNode;
+  private readonly _analyser;
+  private readonly _destination;
+  private readonly _analyserBuffer;
+  private readonly _speakingThreshold;
+  private readonly _speakingHoldMs;
+  private readonly _pollIntervalMs;
+  private _inputSource;
+  private _inputStream;
+  private _lastSpokeAt;
+  private _gain$;
+  /** 1 when audio should pass through, 0 when silenced by PTT. */
+  private _pttMultiplier;
+  constructor(options?: LocalAudioPipelineOptions);
+  /** Observable of the current gain value (0..2). */
+  get gain$(): Observable<number>;
+  /** Current gain value (0..2). */
+  get gain(): number;
+  /**
+   * Processed output track to attach to the RTCRtpSender. Stable reference
+   * across input changes, so `sender.replaceTrack(pipeline.outputTrack)` only
+   * needs to be called once.
+   */
+  get outputTrack(): MediaStreamTrack;
+  /**
+   * Root-mean-square audio level of the input signal, 0..1. Emits on a fixed
+   * interval (~30fps by default).
+   */
+  get level$(): Observable<number>;
+  /**
+   * Boolean VAD derived from {@link level$}. True while level ≥ threshold or
+   * during the hold window after the last frame that crossed the threshold.
+   */
+  get speaking$(): Observable<boolean>;
+  /**
+   * Set gain multiplier applied to the input signal. 0 = silence,
+   * 1 = unity, 2 = 2x. Values are clamped to [0, 2]. The effective gain on
+   * the graph also respects the current PTT state.
+   */
+  setGain(value: number): void;
+  /**
+   * Silence the graph when `active = false`, otherwise restore the configured
+   * gain. Use this from a PTT handler: released → `false`, held → `true`.
+   * Orthogonal to {@link setGain} — once PTT returns to active, the last
+   * configured gain reappears.
+   */
+  setPTTActive(active: boolean): void;
+  private applyEffectiveGain;
+  /**
+   * Wire a new raw mic track as the pipeline's input. Replaces any previous
+   * input source and reconnects the graph so {@link outputTrack} continues
+   * to emit the processed audio. Pass `null` to disconnect the input (the
+   * output track stays alive but emits silence).
+   *
+   * Also resumes the underlying AudioContext on attach — Chrome creates it
+   * in a suspended state and the graph won't process (the destination
+   * track emits silence) until resume() succeeds.
+   */
+  setInputTrack(track: MediaStreamTrack | null): void;
+  destroy(): void;
+  private computeLevel;
+  private evaluateSpeaking;
+}
+//#endregion
 //#region src/controllers/RTCPeerConnectionController.d.ts
 interface RTCPeerConnectionControllerOptions extends MediaOptions {
   callId?: string;
@@ -3728,6 +4261,7 @@ declare class RTCPeerConnectionController extends Destroyable {
   private _remoteDescription$;
   private _remoteStream$;
   private _remoteOfferMediaDirections;
+  private _localAudioPipeline;
   constructor(options?: RTCPeerConnectionControllerOptionsPartial, remoteSessionDescription?: string, deviceController?: DeviceController);
   private get iceGatheringController();
   private get shouldEmitLocalDescription();
@@ -3737,6 +4271,7 @@ declare class RTCPeerConnectionController extends Destroyable {
   stopTrackSender(kind: 'audio' | 'video' | 'both', options?: {
     updateTransceiverDirection: boolean;
   }): void;
+  private stopRawAudioInputForPipeline;
   get isNegotiating$(): Observable<boolean>;
   get isNegotiating(): boolean;
   updateMediaDevicesOptions(options: MediaOptions): void;
@@ -3815,7 +4350,6 @@ declare class RTCPeerConnectionController extends Destroyable {
    */
   private setupEventListeners;
   private negotiationEnded;
-  restarIce(): void;
   /**
    * Trigger an ICE restart through the existing negotiation pipeline.
    *
@@ -3837,10 +4371,41 @@ declare class RTCPeerConnectionController extends Destroyable {
    */
   private setupTrackHandling;
   private setupLocalTracks;
+  /** True for a main connection with no local media to send. */
+  private hasNoLocalMediaToSend;
+  /** The media kinds this connection wants to send: 'audiovideo' | 'video' | 'audio'. */
+  private get requestedMediaKinds();
+  /**
+   * Handle a local media acquisition failure with a typed, semantically
+   * accurate MediaAccessError created at the acquisition site:
+   * - Auxiliary connections (screenshare / additional-device) throw a
+   *   non-fatal error — VertoManager surfaces it and the call is unaffected.
+   * - The main connection degrades to receive-only when allowed (default),
+   *   otherwise fails with a fatal error.
+   */
+  private handleLocalMediaFailure;
+  /**
+   * Negotiate receive-only m-lines when there are no local tracks to send.
+   * Only offer-type connections add transceivers — answer-type connections
+   * reuse the transceivers created from the remote offer.
+   */
+  private setupReceiveOnlyTransceivers;
   private getUserMedia;
   private getDisplayMedia;
   private setupRemoteTracks;
   restoreTrackSender(kind: 'audio' | 'video' | 'both'): Promise<void>;
+  private restoreRawAudioInputForPipeline;
+  /**
+   * Return the lazily-created {@link LocalAudioPipeline}, constructing it on
+   * first access. On creation the current audio sender's track is routed
+   * through the pipeline (input → gain → analyser → destination) and the
+   * sender is switched to emit the processed track. Returns `null` when no
+   * audio sender exists yet (pre-negotiation).
+   */
+  ensureLocalAudioPipeline(): LocalAudioPipeline | null;
+  /** The active LocalAudioPipeline, or null if it hasn't been created yet. */
+  get localAudioPipeline(): LocalAudioPipeline | null;
+  private applyLocalAudioPipelineToSender;
   /**
    * Add a local media track to the peer connection.
    * @param track - The MediaStreamTrack to add
@@ -3911,6 +4476,10 @@ interface WebRTCVerto extends VertoManager {
   requestIceRestartAll?: (relayOnly?: boolean) => Promise<void>;
   /** Request keyframes on all video-receiving legs (skips send-only screen share). */
   requestKeyframeAll?: () => void;
+  /** Lazily create (or return) the local audio pipeline for the main peer connection. */
+  ensureLocalAudioPipeline(): LocalAudioPipeline | null;
+  /** Current local audio pipeline, or null if it has not been created yet. */
+  readonly localAudioPipeline: LocalAudioPipeline | null;
 }
 //#endregion
 //#region src/managers/CallEventsManager.d.ts
@@ -4058,6 +4627,8 @@ declare class WebRTCCall extends Destroyable implements CallManager {
   private _bandwidthConstrained$;
   private _mediaParamsUpdated$;
   private _customSubscriptions;
+  private _pushToTalkEnabled;
+  private _remoteAudioMeter;
   constructor(clientSession: ClientSession, options: CallOptions, initialization: CallInitialization, address?: Address | undefined);
   /** Observable stream of errors from media, signaling, and peer connection layers. */
   get errors$(): Observable<CallError>;
@@ -4123,14 +4694,27 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    *
    * Constructs call context (node_id, call_id, member_id) and sends the RPC request.
    *
-   * @param target - Target member ID string, or a {@link MemberTarget} object.
+   * @param target - Target {@link MemberTarget} triple, or the local member's
+   *   ID string for self-operations (any other string is rejected — a bare
+   *   member id cannot carry the remote member's own call context).
    * @param method - Verto method name (e.g. `'call.mute'`, `'call.member.remove'`).
    * @param args - Parameters for the RPC method.
    * @returns The RPC response.
+   * @throws {CallNotReadyError} If the call has no self member context yet.
+   * @throws {InvalidParams} If a string target is not the local member's ID.
    * @throws {JSONRPCError} If the RPC call returns an error.
    */
   executeMethod<T extends JSONRPCResponse = JSONRPCResponse>(target: string | MemberTarget, method: string, args: Record<string, unknown>): Promise<T>;
-  private buildMethodParams;
+  /**
+   * The local leg's member triple — sent as `self` in every member RPC
+   * envelope, and as the `target` of call-scoped self-operations (e.g. lock,
+   * layout).
+   *
+   * @throws {CallNotReadyError} Before `call.joined` delivers the self member
+   * context (`selfId`/`nodeId`) — an RPC without it cannot be routed, so fail
+   * fast instead of sending a doomed request.
+   */
+  private get callSelf();
   /** Observable of the current call status (e.g. `'ringing'`, `'connected'`). */
   get status$(): Observable<CallStatus>;
   /** Observable of the participants list, emits on join/leave/update. */
@@ -4221,6 +4805,16 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    * Called from within the status subscription to wire stats and recovery.
    */
   private initResilienceSubsystems;
+  /**
+   * Wait for the underlying RTCPeerConnection to reach 'connected' after
+   * triggering an ICE restart. Resolves true on success, false on failure
+   * or if the state doesn't transition within the configured timeout.
+   *
+   * Polls connectionState directly because the recovery manager already
+   * wraps this call in its own withTimeout(); a separate listener-based
+   * implementation would race the outer timeout in subtle ways.
+   */
+  private waitForPeerConnectionConnected;
   /**
    * @internal Stop and destroy resilience subsystems (on disconnect/destroy).
    * Clears references so they can be re-created on reconnect.
@@ -4354,11 +4948,27 @@ declare class WebRTCCall extends Destroyable implements CallManager {
   /** Observable that emits `true` when answered, `false` when rejected. */
   get answered$(): Observable<boolean>;
   /**
-   * Sets the call layout and participant positions.
+   * Sets the call layout and, optionally, individual participant positions.
+   *
+   * The gateway `call.layout.set` DTO has **no** `positions` member, so when
+   * `positions` is provided this method issues a `call.member.position.set`
+   * request per member (via {@link Participant.setPosition}, which keys each
+   * position by that member's own call context) alongside `call.layout.set`
+   * (issue #19400, Flag #6).
+   *
+   * **These operations are NOT atomic.** The layout is applied first, then each
+   * member position sequentially, so members may briefly flash into their
+   * default slots before being moved to the requested positions. Targeted
+   * members are validated upfront, though: when any of them has no
+   * {@link Participant.target | member call context} yet, the whole call
+   * rejects before any request is sent and the layout is left unchanged.
    *
    * @param layout - Layout name (must be one of {@link layouts}).
-   * @param positions - Map of member IDs to {@link VideoPosition} values.
+   * @param positions - Optional map of member IDs to {@link VideoPosition} values.
+   *   When omitted or empty, only the layout is changed.
    * @throws {InvalidParams} If the layout is not in the available {@link layouts}.
+   * @throws {ParticipantNotReadyError} If a targeted member's call context has
+   *   not been received yet — thrown before any request is sent.
    *
    * @example
    * ```ts
@@ -4367,7 +4977,7 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    * });
    * ```
    */
-  setLayout(layout: string, positions: Record<string, VideoPosition>): Promise<void>;
+  setLayout(layout: string, positions?: Record<string, VideoPosition>): Promise<void>;
   /**
    * Transfers the call to another destination.
    *
@@ -4375,12 +4985,86 @@ declare class WebRTCCall extends Destroyable implements CallManager {
    * @see {@link status$} to observe the transfer progress.
    */
   transfer(options: TransferOptions): Promise<void>;
+  /**
+   * Set the local microphone gain as a percentage applied before transmission.
+   *
+   *   - `0`   = silent
+   *   - `100` = unity (no change, default)
+   *   - `200` = 2× digital boost (max; expect clipping / noise amplification)
+   *
+   * Values are clamped to [0, 200]. Engages the local audio pipeline on
+   * first use (one-time cost).
+   *
+   * Note: this is a **digital** multiplier applied in a Web Audio GainNode
+   * between your mic track and the RTCRtpSender — it does not change the
+   * physical mic's hardware sensitivity. Browsers' autoGainControl can
+   * fight the setting; call {@link setAutoGainControl}(false) for
+   * predictable behaviour.
+   *
+   * @param value - Gain percentage (0..200; 100 = unity).
+   */
+  setLocalMicrophoneGain(value: number): void;
+  /** Observable of the current local microphone gain (0..200, where 100 = unity). */
+  get localMicrophoneGain$(): Observable<number>;
+  /**
+   * Observable of the RMS audio level of the local microphone, 0..1.
+   * Emits at ~30fps while a mic track is active. Engages the local audio
+   * pipeline on first subscription.
+   */
+  get localAudioLevel$(): Observable<number>;
+  /**
+   * Observable that is `true` while the local participant is speaking
+   * (RMS level above the VAD threshold, with hold time to avoid flicker).
+   */
+  get localSpeaking$(): Observable<boolean>;
+  /**
+   * Enable push-to-talk: while {@link setPushToTalkActive} has been called
+   * with `false`, the microphone gain is forced to 0; calling
+   * {@link setPushToTalkActive} with `true` restores the configured gain.
+   * Use this instead of mute/unmute for instant talk/silence transitions
+   * because it doesn't rebuild the track.
+   *
+   * This method installs the pipeline but does not attach any keyboard
+   * listener — consumers bind the key themselves and call
+   * {@link setPushToTalkActive} on keydown/keyup.
+   */
+  enablePushToTalk(): void;
+  /** Disable push-to-talk; mic gain returns to the configured value. */
+  disablePushToTalk(): void;
+  /**
+   * While push-to-talk is enabled, sets the talk state. `true` = transmitting,
+   * `false` = silent. No-op if push-to-talk has not been enabled.
+   */
+  setPushToTalkActive(active: boolean): void;
+  /**
+   * Toggle echo cancellation on the local mic at runtime. Applied via
+   * `track.applyConstraints`; browsers that don't honour runtime constraints
+   * (notably iOS Safari) fall back to re-acquiring the track with the new
+   * constraint set and plumbing the replacement through the local audio
+   * pipeline if one is active.
+   */
+  setEchoCancellation(enabled: boolean): Promise<void>;
+  /** Toggle browser noise suppression on the local mic at runtime. */
+  setNoiseSuppression(enabled: boolean): Promise<void>;
+  /** Toggle browser automatic gain control on the local mic at runtime. */
+  setAutoGainControl(enabled: boolean): Promise<void>;
+  /**
+   * Observable of the aggregate remote audio level, 0..1 RMS. The server
+   * delivers a single mixed audio stream for all remote participants — this
+   * meter reports that mix. Per-participant audio is not available client-side.
+   *
+   * Engages a shared AudioContext on first subscription (cheap — one
+   * AnalyserNode, no GainNode, no destination) so it does not affect the
+   * caller's audio element playback.
+   */
+  get remoteAudioLevel$(): Observable<number>;
   /** Destroys the call, releasing all resources and subscriptions. */
   destroy(): void;
   /**
    * @internal Send a verto.subscribe message to add an event type to the
-   * server's subscription list for this call. Best-effort — failures are
-   * logged but don't prevent the filtered observable from being returned.
+   * server's subscription list for this call. Returns the underlying RPC
+   * promise so callers can decide whether to cache the observable on success
+   * or retry on failure.
    */
   private _sendVertoSubscribe;
 }
@@ -4397,5 +5081,5 @@ declare const version: string;
  */
 declare const ready: boolean;
 //#endregion
-export { Address, type AddressHistory, type AudioConstraintsEvent, type AuthenticateContext, type Call, type CallAddress, type CallCapabilitiesState, CallCreateError, type CallDiagnosticSummary, type CallDirection, type CallError, type CallErrorKind, type NetworkIssue as CallNetworkIssue, type NetworkIssue, type NetworkMetrics as CallNetworkMetrics, type NetworkMetrics, type CallOptions, type CallParticipant, type CallSelfParticipant, type CallState, type CallStatus, type Capability, ClientPreferences, CollectionFetchError, type ConstraintFallbackEvent, type CredentialProvider, DPoPInitError, type DebugOptions, type DeviceController, type DeviceRecoveryEvent, DeviceTokenError, type DiagnosticEvent, type DialOptions, type Directory, type ExecuteMethod, InvalidCredentialsError, type JSONRPCErrorResponse, type JSONRPCRequest, type JSONRPCResponse, type JSONRPCSuccessResponse, type LayoutLayer, type LogLevel, type MediaDirection, type MediaDirections, type MediaOptions, type MediaParamsEvent, MediaTrackError, type MemberCapabilities, MessageParseError, type NodeSocketAdapter, type OnOffCapability, OverconstrainedFallbackError, Participant, type PendingRPCOptions, type PermissionResult, type PlatformCapabilities, PreflightError, type PreflightOptions, type PreflightResult, type QualityLevel, RecoveryError, type RecoveryEvent, type RecoveryState, type ResilienceCallStatus, type SATClaims, type SDKCredential, type SDKLogger, type ScreenShareStatus, type SelectDeviceOptions, SelfCapabilities, SelfParticipant, type SessionDiagnostics, type SessionState, SignalWire, type SignalWireOptions, StaticCredentialProvider, type Storage, type StoredDevicePreference, Subscriber, type SubscriberPresence, type TextMessage, TokenRefreshError, type TransferOptions, UnexpectedError, VertoPongError, type VideoPosition, type WebRTCApiProvider, WebRTCCall, type WebRTCMediaDevices, type WebSocketAdapter, embeddableCall, isSelfParticipant, ready, setDebugOptions, setLogLevel, setLogger, version };
+export { Address, type AddressHistory, type AudioConstraintsEvent, type AuthenticateContext, type Call, type CallAddress, type CallCapabilitiesState, CallCreateError, type CallDiagnosticSummary, type CallDirection, type CallError, type CallErrorKind, type NetworkIssue as CallNetworkIssue, type NetworkIssue, type NetworkMetrics as CallNetworkMetrics, type NetworkMetrics, CallNotReadyError, type CallOptions, type CallParticipant, type CallSelfParticipant, type CallState, type CallStatus, type Capability, ClientPreferences, CollectionFetchError, type ConstraintFallbackEvent, type CredentialNoRefreshHandlerWarning, type CredentialProvider, type CredentialRefreshFallbackReason, type CredentialRefreshFallbackWarning, DPoPInitError, type DebugOptions, type DeviceController, type DeviceRecoveryEvent, DeviceTokenError, type DiagnosticEvent, type DialOptions, type Directory, EmbedTokenCredentialProvider, type ExecuteMethod, InvalidCredentialsError, type JSONRPCErrorResponse, type JSONRPCRequest, type JSONRPCResponse, type JSONRPCSuccessResponse, type LayoutLayer, type LogLevel, MediaAccessError, type MediaDirection, type MediaDirections, type MediaOptions, type MediaParamsEvent, MediaTrackError, type MemberCapabilities, MessageParseError, type NodeSocketAdapter, type OnOffCapability, OverconstrainedFallbackError, Participant, ParticipantNotReadyError, type PendingRPCOptions, type PermissionResult, type PlatformCapabilities, PreflightError, type PreflightOptions, type PreflightResult, type QualityLevel, RecoveryError, type RecoveryEvent, type RecoveryState, type ResilienceCallStatus, type SATClaims, type SDKCredential, type SDKLogger, type SDKWarning, type ScreenShareStatus, type SelectDeviceOptions, SelfCapabilities, SelfParticipant, type SessionDiagnostics, type SessionState, SignalWire, type SignalWireOptions, StaticCredentialProvider, type Storage, type StoredDevicePreference, type TextMessage, TokenRefreshError, type TransferOptions, UnexpectedError, User, type UserPresence, VertoPongError, type VideoPosition, type WebRTCApiProvider, WebRTCCall, type WebRTCMediaDevices, type WebSocketAdapter, embeddableCall, getLogger, isSelfParticipant, ready, setDebugOptions, setLogLevel, setLogger, version };
 //# sourceMappingURL=index.d.mts.map