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

package/dist/index.d.mts

@@ -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
@@ -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. */
@@ -1844,8 +1921,34 @@ declare class Participant extends Destroyable implements CallParticipant {
   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. */
@@ -1868,6 +1971,7 @@ 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>;
   /**
    * Adjusts the **conference-only** microphone energy gate / sensitivity level
@@ -1908,6 +2012,12 @@ declare class Participant extends Destroyable implements CallParticipant {
   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>;
@@ -1950,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>;
@@ -1966,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>;
@@ -1974,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>;
@@ -2081,6 +2206,10 @@ interface CallParticipant {
   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;
@@ -3095,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;
@@ -3122,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;
@@ -3280,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';
@@ -3353,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. */
@@ -3423,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?;
@@ -3455,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;
@@ -3546,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. */
@@ -3563,6 +3841,14 @@ 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.
    */
@@ -3744,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
@@ -3977,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;
@@ -4076,10 +4371,30 @@ 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
@@ -4379,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. */
@@ -4620,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
@@ -4633,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.
    *
@@ -4737,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, EmbedTokenCredentialProvider, 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, 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 };
+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