@furious.luke/argus-js 0.3.1 → 0.5.0

package/dist/index.cjs

@@ -22,6 +22,7 @@ var src_exports = {};
 __export(src_exports, {
   Publisher: () => Publisher,
   captureCamera: () => captureCamera,
+  captureMicrophone: () => captureMicrophone,
   captureScreen: () => captureScreen
 });
 module.exports = __toCommonJS(src_exports);
@@ -53,11 +54,11 @@ var SignalingChannel = class _SignalingChannel {
     ws.onclose = () => ch.onClose?.();
     return ch;
   }
-  /** Sends a JSON message if the socket is open; a no-op otherwise. */
+  /** Sends a JSON message when the socket is open and reports whether it was sent. */
   send(msg) {
-    if (this.ws.readyState === WebSocket.OPEN) {
-      this.ws.send(JSON.stringify(msg));
-    }
+    if (this.ws.readyState !== WebSocket.OPEN) return false;
+    this.ws.send(JSON.stringify(msg));
+    return true;
   }
   /** Closes the underlying WebSocket. */
   close() {
@@ -73,30 +74,132 @@ function parseSignal(data) {
 }
 
 // src/publisher.ts
+function selectGatewayTURNURLs(advertised, policy = "all") {
+  if (policy === "all") return advertised;
+  const selected = advertised.filter((raw) => {
+    let parsed;
+    try {
+      parsed = new URL(raw);
+    } catch {
+      return false;
+    }
+    const transport = (parsed.searchParams.get("transport") ?? "").toLowerCase();
+    if (policy === "tls") {
+      return parsed.protocol.toLowerCase() === "turns:" && (transport === "" || transport === "tcp");
+    }
+    return parsed.protocol.toLowerCase() === "turn:" && (transport === "" || transport === "udp");
+  });
+  if (selected.length === 0) {
+    throw new Error(`gateway advertised no TURN URLs for required ${policy} transport`);
+  }
+  return selected;
+}
 var defaultSignalingReconnectTimeoutMs = 2e4;
+var defaultGatewayHandshakeTimeoutMs = 2e4;
+var defaultPeerConnectionTimeoutMs = 3e4;
+var initialGatewayAttemptTimeoutMs = 3e3;
 var signalingResumeAttemptTimeoutMs = 3e3;
 var signalingResumeMaxBackoffMs = 3e3;
 var senderRestartPauseMs = 100;
 var senderRecoveryWaitMs = 4e3;
 var iceRecoveryWaitMs = 8e3;
+var minimumNegotiationAnswerTimeoutMs = 15e3;
+var negotiationReconnectGraceMs = 5e3;
+var minimumIntentionalTrackEndRetentionMs = 35e3;
+var maxUserTextBytes = 4 * 1024;
+var maxRetainedICECandidates = 64;
+var ReportedPublisherError = class extends Error {
+  constructor(message, fatal = false) {
+    super(message);
+    this.fatal = fatal;
+  }
+  fatal;
+};
+var NegotiationTimeoutError = class extends Error {
+};
+var SenderRestoreError = class extends Error {
+};
+var PublisherStoppedError = class extends Error {
+};
 var Publisher = class {
   opts;
   sig = null;
   pc = null;
   hasAnswer = false;
   pendingRemoteCandidates = [];
-  localStream = null;
+  // Setting a local description starts ICE gathering. Candidates may therefore
+  // arrive before the corresponding offer has crossed the signaling socket.
+  // Hold them until sendOffer confirms that the offer was sent, then trickle
+  // them in order. This keeps startup fast without allowing candidate/offer
+  // reordering at the media server.
+  pendingLocalCandidates = [];
+  localCandidateOfferSent = false;
+  // WebSocket.send() only proves local queueing. Retain the current ICE
+  // generation so a replacement signaling socket can replay candidates whose
+  // delivery on the old socket was ambiguous.
+  retainedLocalCandidates = [];
+  retainedLocalCandidateKeys = /* @__PURE__ */ new Set();
+  localCandidateGeneration = null;
+  // Both peers replay after reconnect. Receiving the same candidate must be
+  // idempotent, whether it is still buffered behind an answer or already
+  // applied to the peer connection.
+  remoteCandidateKeys = /* @__PURE__ */ new Set();
+  remoteCandidateOrder = [];
+  remoteCandidateGeneration = null;
   readToken = null;
-  selectedGatewayURL = null;
+  gatewayURL = null;
+  lastReportedICEPath = null;
+  watchedICETransports = /* @__PURE__ */ new WeakSet();
   stopped = true;
+  // Every start/stop boundary advances lifecycleGeneration. Async work captures
+  // the generation it belongs to and may never mutate or terminate a later run.
+  lifecycleGeneration = 0;
+  runAbort = null;
+  peerConnectionTimer = null;
   reconnecting = false;
   reconnectGeneration = 0;
   resumeSocket = null;
-  recoveryGeneration = 0;
-  recoveringMedia = false;
-  recoveryRequired = false;
-  recoveryAction = null;
+  signalingWaiters = /* @__PURE__ */ new Set();
+  pendingOffer = null;
+  recoverySequence = 0;
+  recoveryStates = /* @__PURE__ */ new Map();
+  // ICE restart applies to the whole peer connection. Keep one attempt shared
+  // by every track currently recovering so simultaneous camera/screen stalls do
+  // not create duplicate ICE offers.
+  iceRestartSequence = 0;
+  iceRestartAttempt = null;
   trackEndHandlers = /* @__PURE__ */ new Map();
+  // published is the source of truth for the live video tracks and their logical
+  // types. It drives the track labels sent on every offer, per-track recovery
+  // reporting, and add/remove of individual tracks. At most one track per type is
+  // kept (publishing a second track of a type replaces the first).
+  published = /* @__PURE__ */ new Map();
+  publishedStreams = /* @__PURE__ */ new Map();
+  // Own the active sender for each logical type. Active source replacement uses
+  // replaceTrack on that sender. Unpublish removes the mapping because addTrack
+  // may later reuse any compatible inactive transceiver, not necessarily the one
+  // that previously carried the same logical type.
+  typeSenders = /* @__PURE__ */ new Map();
+  // intentionalTrackEnds holds physical track ids removed by publish/unpublish
+  // whose server-side `media_track_ended` has not yet arrived. Correlating by id
+  // keeps a delayed end for an old screen track from being mistaken for failure
+  // of a newly-published screen track.
+  intentionalTrackEnds = /* @__PURE__ */ new Map();
+  // negotiationChain serializes every offer/answer exchange, including recovery.
+  // User operations do not resolve until their answer is applied, so no caller
+  // or recovery timer can create a second offer while one is outstanding.
+  negotiationChain = Promise.resolve();
+  // pendingAnswer resolves the one in-flight negotiation once its matching answer
+  // arrives, or rejects it on timeout/teardown. All offers, including recovery,
+  // pass through negotiationChain, so this slot is never intentionally replaced.
+  pendingAnswer = null;
+  // negotiationSeq stamps each offer with a monotonically increasing id.
+  negotiationSeq = 0;
+  textChannel = null;
+  speechEnabled = false;
+  speechPending = false;
+  speechTransceiver = null;
+  microphoneTransceiver = null;
   constructor(opts) {
     this.opts = opts;
   }
@@ -104,96 +207,336 @@ var Publisher = class {
   get frameReadToken() {
     return this.readToken;
   }
+  /**
+   * The signaling gateway URL that won the initial race, or null before start.
+   * Relay this with frameReadToken so the application server can reach the same
+   * region for frame reads and change-notification subscriptions.
+   */
+  get selectedGatewayURL() {
+    return this.gatewayURL;
+  }
+  /** Requests the persistent outbound `speech` track. This is explicit user
+   * opt-in and renegotiates only once; the track remains silent between turns. */
+  async enableSpeech() {
+    if (this.speechEnabled) return;
+    await this.enqueueNegotiation(() => {
+      const pc = this.pc;
+      if (!pc || this.speechEnabled || this.speechPending) return false;
+      if (!this.speechTransceiver) {
+        this.speechTransceiver = pc.addTransceiver("audio", { direction: "recvonly" });
+      } else {
+        this.speechTransceiver.direction = "recvonly";
+      }
+      this.speechPending = true;
+      return {
+        commit: () => {
+          this.speechPending = false;
+          this.speechEnabled = true;
+        },
+        rollback: () => {
+          this.speechPending = false;
+        }
+      };
+    });
+  }
+  /** Sends typed input over the reliable ordered Argus text channel. */
+  sendUserText(messageId, text) {
+    if (!messageId || !text.trim()) throw new Error("messageId and text are required");
+    if (new TextEncoder().encode(text).byteLength > maxUserTextBytes) {
+      throw new Error("text must not exceed 4 KiB");
+    }
+    if (!this.textChannel || this.textChannel.readyState !== "open") {
+      throw new Error("Argus text channel is not open");
+    }
+    this.textChannel.send(JSON.stringify({ type: "user_text", message_id: messageId, text }));
+  }
   /**
    * Starts the publisher: races all gateways to find the fastest, completes
    * the two-phase handshake, creates the peer connection, and sends the SDP
    * offer. Resolves when the offer has been sent (not when ICE completes —
    * use onConnected for that).
+   *
+   * The stream's single video track is published under `type` (default `"camera"`),
+   * declared to the server so reads and change notifications can address them by
+   * type. Add or remove further tracks live with {@link Publisher.publish} and
+   * {@link Publisher.unpublish}.
+   */
+  async start(stream, type = "camera") {
+    const track = this.requireSingleVideoTrack(stream);
+    await this.startSession({ track, stream, type, watchForRecovery: true });
+  }
+  /**
+   * Starts the publisher with a microphone track and no video — a fully valid
+   * audio-only stream, the natural starting point for a voice agent. Exactly one
+   * audio track must be present in `stream`. Video can be added later with
+   * {@link Publisher.publish}; a stream carries at most one microphone track.
+   *
+   * Like {@link Publisher.start} it races the gateways, completes the handshake,
+   * and sends the offer; it resolves once the offer is sent. The microphone is not
+   * subject to the video recovery ladder — a mic that stops simply ends
+   * transcription for the stream.
+   */
+  async startAudioOnly(stream) {
+    const track = this.requireSingleAudioTrack(stream);
+    await this.startSession({ track, stream, type: "audio", watchForRecovery: false });
+  }
+  /**
+   * Starts a WebRTC session with only the ordered `argus.text` data channel.
+   * This is the natural entry point for a typed, text-only agent: it requests no
+   * camera or microphone permission and publishes no media. Camera, screen, or
+   * microphone tracks can be added later with {@link Publisher.publish} or
+   * {@link Publisher.publishMicrophone}; {@link Publisher.enableSpeech} can add
+   * the optional inbound speech track independently.
+   */
+  async startTextOnly() {
+    await this.startSession(null);
+  }
+  /**
+   * Shared startup for video, audio-only, and text-only entry points: race the
+   * gateways, build the peer connection and text channel, optionally add an
+   * initial media track, and send the first offer.
    */
-  async start(stream) {
+  async startSession(initialTrack) {
+    if (!this.stopped || this.pc || this.published.size > 0) {
+      throw new Error("publisher already started");
+    }
+    const trackKind = initialTrack ? initialTrack.type === "audio" ? "audio" : "video" : null;
+    const generation = ++this.lifecycleGeneration;
+    const runAbort = new AbortController();
+    this.runAbort = runAbort;
+    this.negotiationChain = Promise.resolve();
     this.stopped = false;
-    this.recoveryRequired = false;
-    this.localStream = stream;
-    this.watchStreamTracks(stream);
-    const { ws, readyInfo, gatewayURL } = await this.raceGateways();
-    this.selectedGatewayURL = gatewayURL;
-    if (readyInfo.read_token) {
-      this.readToken = readyInfo.read_token;
-    }
-    const iceServers = [...this.opts.iceServers ?? []];
-    if (readyInfo.turn_urls && readyInfo.turn_urls.length > 0) {
-      iceServers.push({
-        urls: readyInfo.turn_urls,
-        username: readyInfo.turn_username,
-        credential: readyInfo.turn_credential
-      });
+    this.recoveryStates.clear();
+    this.typeSenders.clear();
+    this.lastReportedICEPath = null;
+    this.watchedICETransports = /* @__PURE__ */ new WeakSet();
+    if (initialTrack) {
+      this.published.set(initialTrack.track, initialTrack.type);
+      this.publishedStreams.set(initialTrack.track, initialTrack.stream);
     }
-    this.pc = new RTCPeerConnection({ iceServers });
-    this.pc.onicecandidate = (ev) => {
-      if (!ev.candidate || !this.sig) return;
-      const c = ev.candidate;
-      this.sig.send({
-        type: "ice_candidate",
-        candidate: c.candidate,
-        sdp_mid: c.sdpMid ?? void 0,
-        sdp_mline_index: c.sdpMLineIndex ?? void 0,
-        username_fragment: c.usernameFragment ?? void 0
+    let startupWS = null;
+    try {
+      const { ws, readyInfo, gatewayURL } = await this.raceGateways(runAbort.signal);
+      startupWS = ws;
+      this.assertActiveRun(generation);
+      if (initialTrack && trackKind) this.requireLiveTrack(initialTrack.track, trackKind);
+      this.gatewayURL = gatewayURL;
+      if (readyInfo.read_token) {
+        this.readToken = readyInfo.read_token;
+      }
+      const iceServers = [...this.opts.iceServers ?? []];
+      const advertisedTURNURLs = readyInfo.turn_urls ?? [];
+      if (advertisedTURNURLs.length > 0 || this.opts.turnTransportPolicy !== void 0) {
+        const turnURLs = selectGatewayTURNURLs(
+          advertisedTURNURLs,
+          this.opts.turnTransportPolicy
+        );
+        if (turnURLs.length > 0) {
+          iceServers.push({
+            urls: turnURLs,
+            username: readyInfo.turn_username,
+            credential: readyInfo.turn_credential
+          });
+        }
+      }
+      const pc = new RTCPeerConnection({
+        iceServers,
+        iceTransportPolicy: this.opts.iceTransportPolicy
       });
-    };
-    this.pc.onconnectionstatechange = () => {
-      const state = this.pc?.connectionState;
-      if (state) this.opts.callbacks?.onConnectionStateChange?.(state);
-      if (state === "connected") this.opts.callbacks?.onConnected?.();
-    };
-    for (const track of stream.getTracks()) {
-      this.pc.addTrack(track, stream);
-    }
-    const offer = await this.pc.createOffer();
-    await this.pc.setLocalDescription(offer);
-    await this.gatherComplete();
-    const signaling = this.installSignaling(ws);
-    const local = this.pc.localDescription;
-    if (!local) throw new Error("local description missing after gather");
-    signaling.send({ type: "offer", sdp: local.sdp, sdp_type: "offer" });
-  }
-  /** Replaces the currently published stream with a new one. */
-  async replaceStream(stream) {
-    if (!this.pc) throw new Error("publisher not started");
-    this.cancelMediaRecovery();
-    this.recoveryRequired = false;
-    this.unwatchStreamTracks();
-    const senders = this.pc.getSenders();
-    for (const sender of senders) {
-      if (sender.track) {
-        this.pc.removeTrack(sender);
+      this.pc = pc;
+      this.textChannel = pc.createDataChannel("argus.text", { ordered: true });
+      this.textChannel.onmessage = (event) => this.handleTextMessage(event.data);
+      pc.ontrack = (event) => {
+        if (!this.isActiveRun(generation, pc) || event.track.kind !== "audio") return;
+        this.opts.callbacks?.onSpeechTrack?.(event.track, event.streams);
+      };
+      pc.onicecandidate = (ev) => {
+        if (!this.isActiveRun(generation, pc) || !ev.candidate) return;
+        this.handleLocalICECandidate(ev.candidate);
+      };
+      pc.onconnectionstatechange = () => {
+        if (!this.isActiveRun(generation, pc)) return;
+        const state = pc.connectionState;
+        if (state) this.opts.callbacks?.onConnectionStateChange?.(state);
+        if (state === "connected") {
+          this.clearPeerConnectionTimeout();
+          void this.reportSelectedICEPath(pc);
+          this.opts.callbacks?.onConnected?.();
+        } else if (state === "failed") {
+          this.clearPeerConnectionTimeout();
+          this.terminateWithError(new Error("WebRTC connection failed"), true, generation);
+        }
+      };
+      if (initialTrack) {
+        const sender = initialTrack.type === "audio" ? this.addMicrophoneTrack(pc, initialTrack.track, initialTrack.stream) : pc.addTrack(initialTrack.track, initialTrack.stream);
+        this.typeSenders.set(
+          initialTrack.type,
+          sender
+        );
       }
+      this.installSignaling(ws);
+      startupWS = null;
+      const offer = await pc.createOffer();
+      this.assertActiveRun(generation, pc);
+      if (initialTrack && trackKind) this.requireLiveTrack(initialTrack.track, trackKind);
+      this.beginLocalCandidateBatch();
+      await pc.setLocalDescription(offer);
+      this.assertActiveRun(generation, pc);
+      if (initialTrack && trackKind) this.requireLiveTrack(initialTrack.track, trackKind);
+      const local = pc.localDescription;
+      if (!local) throw new Error("local description missing");
+      const id = this.nextNegotiationId();
+      const { answered } = await this.sendOffer({
+        type: "offer",
+        sdp: local.sdp,
+        sdp_type: "offer",
+        negotiation_id: id,
+        tracks: this.buildTrackLabels(),
+        speech_enabled: this.speechEnabled || this.speechPending || void 0
+      });
+      this.releaseLocalCandidateBatch();
+      this.assertActiveRun(generation, pc);
+      this.armPeerConnectionTimeout(generation, pc);
+      if (initialTrack && trackKind) this.requireLiveTrack(initialTrack.track, trackKind);
+      if (initialTrack?.watchForRecovery) this.watchTrack(initialTrack.track);
+      else if (initialTrack) this.watchMicrophone(initialTrack.track);
+      const initial = answered.then(async (sdp) => {
+        this.assertActiveRun(generation, pc);
+        await pc.setRemoteDescription(
+          new RTCSessionDescription({ type: "answer", sdp })
+        );
+        this.assertActiveRun(generation, pc);
+        this.applyAnswered(pc);
+      });
+      this.negotiationChain = initial.catch((err) => {
+        if (this.isActiveRun(generation, pc)) {
+          const reported = err instanceof Error ? err : new Error(String(err));
+          const alreadyReported = err instanceof ReportedPublisherError && err.fatal;
+          this.terminateWithError(reported, !alreadyReported, generation);
+        }
+        throw err;
+      });
+      void this.negotiationChain.catch(() => {
+      });
+    } catch (err) {
+      startupWS?.close();
+      if (generation === this.lifecycleGeneration) this.stop();
+      throw err;
     }
-    for (const track of stream.getTracks()) {
-      this.pc.addTrack(track, stream);
-    }
-    this.localStream = stream;
-    this.watchStreamTracks(stream);
-    await this.renegotiate(false);
+  }
+  /**
+   * Adds the single video track from `stream` to the live session under `type`,
+   * renegotiating so the media server begins ingesting them. Use this to add a
+   * track after {@link Publisher.start} — for example to begin a screen share on
+   * top of a live camera.
+   *
+   * Exactly one video track must be present in `stream`. If a track of `type` is already
+   * live it is removed and replaced (a "screen" published while another "screen"
+   * is live supersedes it).
+   */
+  async publish(stream, type) {
+    if (!this.pc) throw new Error("publisher not started");
+    const track = this.requireSingleVideoTrack(stream);
+    await this.enqueueNegotiation(() => this.stagePublish(track, stream, type));
+  }
+  /**
+   * Removes the live track(s) of the given type, stops their local capture, and
+   * renegotiates so the media server ends ingestion for that track. A no-op if
+   * no track of that type is published.
+   */
+  async unpublish(type) {
+    if (!this.pc) throw new Error("publisher not started");
+    await this.enqueueNegotiation(() => {
+      if (this.tracksOfType(type).length === 0) {
+        return false;
+      }
+      return this.stageUnpublish(type);
+    });
+  }
+  /**
+   * Adds the microphone (audio) track from `stream` to the live session and
+   * renegotiates, so the media server begins transcribing it. Exactly one audio
+   * track must be present in `stream`. Publishing a microphone while one is
+   * already live replaces it.
+   *
+   * The audio track feeds server-side speech-to-text; its transcripts are
+   * delivered to the customer server over the change-notification subscription,
+   * not to the browser. Audio is not subject to the video recovery ladder — a
+   * mic that stops is simply removed.
+   */
+  async publishMicrophone(stream) {
+    if (!this.pc) throw new Error("publisher not started");
+    const track = this.requireSingleAudioTrack(stream);
+    await this.enqueueNegotiation(() => this.stagePublishAudio(track, stream));
+  }
+  /**
+   * Removes the live microphone track, stops its local capture, and
+   * renegotiates so the media server ends transcription. A no-op if no
+   * microphone is published.
+   */
+  async unpublishMicrophone() {
+    if (!this.pc) throw new Error("publisher not started");
+    await this.enqueueNegotiation(() => {
+      if (this.tracksOfType("audio").length === 0) return false;
+      return this.stageUnpublish("audio");
+    });
+  }
+  /**
+   * Replaces the published track of a single type with a new stream and
+   * renegotiates in place — e.g. to swap to a freshly reacquired screen share
+   * after {@link PublisherCallbacks.onRecoveryRequired}. Defaults to the
+   * `"camera"` type. This is a convenience over {@link Publisher.publish}, which
+   * it delegates to (publishing one track per type replaces any existing track
+   * of that type).
+   */
+  async replaceStream(stream, type = "camera") {
+    await this.publish(stream, type);
   }
   /** Stops publishing and tears down the peer connection. */
   stop() {
+    this.lifecycleGeneration++;
+    this.runAbort?.abort();
+    this.runAbort = null;
+    this.clearPeerConnectionTimeout();
     this.stopped = true;
-    this.cancelMediaRecovery();
+    this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
     this.reconnecting = false;
     this.resumeSocket?.close();
     this.resumeSocket = null;
     this.sig?.close();
     this.sig = null;
+    this.rejectSignalingWaiters(new Error("publisher stopped"));
     this.unwatchStreamTracks();
-    this.localStream?.getTracks().forEach((t) => t.stop());
-    this.localStream = null;
+    this.stopPublishedTracks();
+    this.clearIntentionalTrackEnds();
+    this.rejectPendingAnswer(new Error("publisher stopped"));
+    this.pendingOffer = null;
     this.pc?.close();
     this.pc = null;
+    this.textChannel = null;
+    this.speechEnabled = false;
+    this.speechPending = false;
+    this.speechTransceiver = null;
+    this.microphoneTransceiver = null;
+    this.typeSenders.clear();
     this.hasAnswer = false;
     this.pendingRemoteCandidates = [];
+    this.pendingLocalCandidates = [];
+    this.localCandidateOfferSent = false;
+    this.clearRetainedICECandidates();
     this.readToken = null;
-    this.selectedGatewayURL = null;
+    this.gatewayURL = null;
+    this.lastReportedICEPath = null;
+  }
+  // rejectPendingAnswer fails any in-flight negotiation so a queued
+  // publish()/unpublish() rejects promptly instead of hanging until timeout.
+  rejectPendingAnswer(err) {
+    const pending = this.pendingAnswer;
+    if (pending) {
+      this.pendingAnswer = null;
+      pending.reject(err);
+    }
   }
   /** Returns the current RTCPeerConnection, or null if not started. */
   get peerConnection() {
@@ -206,7 +549,7 @@ var Publisher = class {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  raceGateways() {
+  raceGateways(signal) {
     return new Promise((resolve, reject) => {
       const { gatewayURLs, token } = this.opts;
       if (gatewayURLs.length === 0) {
@@ -214,9 +557,21 @@ var Publisher = class {
         return;
       }
       const sockets = [];
+      const attemptTimers = /* @__PURE__ */ new Map();
       let settled = false;
+      let timeoutTimer = null;
+      const clearTimeoutTimer = () => {
+        if (timeoutTimer !== null) clearTimeout(timeoutTimer);
+        timeoutTimer = null;
+      };
+      const clearAttemptTimer = (socket) => {
+        const timer = attemptTimers.get(socket);
+        if (timer !== void 0) clearTimeout(timer);
+        attemptTimers.delete(socket);
+      };
       const closeAll = (except) => {
         for (const s of sockets) {
+          clearAttemptTimer(s);
           if (s !== except) {
             s.onmessage = null;
             s.onerror = null;
@@ -229,39 +584,107 @@ var Publisher = class {
         if (settled) return;
         if (sockets.every((s) => s.readyState === WebSocket.CLOSED || s.readyState === WebSocket.CLOSING)) {
           settled = true;
+          clearTimeoutTimer();
+          signal.removeEventListener("abort", abort);
           reject(new Error("all gateways failed to connect"));
         }
       };
-      for (const gatewayURL of gatewayURLs) {
+      const abort = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeoutTimer();
+        closeAll();
+        reject(new PublisherStoppedError("publisher stopped"));
+      };
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      signal.addEventListener("abort", abort, { once: true });
+      const timeoutMs = Math.max(
+        0,
+        this.opts.gatewayHandshakeTimeoutMs ?? defaultGatewayHandshakeTimeoutMs
+      );
+      timeoutTimer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", abort);
+        closeAll();
+        reject(new Error(`gateway handshake timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const openGateway = (gatewayURL) => {
+        if (settled) return;
         const u = new URL(gatewayURL);
         u.searchParams.set("token", token);
         const ws = new WebSocket(u.toString());
         sockets.push(ws);
         let accepted = false;
+        const attemptTimer = setTimeout(() => {
+          attemptTimers.delete(ws);
+          if (settled || accepted) return;
+          ws.onmessage = null;
+          ws.onerror = null;
+          ws.onclose = null;
+          ws.close();
+          try {
+            openGateway(gatewayURL);
+          } catch (err) {
+            settled = true;
+            clearTimeoutTimer();
+            signal.removeEventListener("abort", abort);
+            closeAll();
+            reject(err);
+          }
+        }, initialGatewayAttemptTimeoutMs);
+        attemptTimers.set(ws, attemptTimer);
         ws.onmessage = (ev) => {
           if (settled) return;
           try {
             const msg = JSON.parse(ev.data);
             if (!accepted && msg.type === "accepted") {
               accepted = true;
+              clearAttemptTimer(ws);
               ws.send(JSON.stringify({ type: "proceed" }));
             } else if (accepted && msg.type === "ready") {
               settled = true;
+              clearTimeoutTimer();
+              signal.removeEventListener("abort", abort);
               closeAll(ws);
               resolve({ ws, readyInfo: msg, gatewayURL });
             }
           } catch {
           }
         };
-        ws.onerror = () => checkAllFailed();
-        ws.onclose = () => checkAllFailed();
+        ws.onerror = () => {
+          clearAttemptTimer(ws);
+          checkAllFailed();
+        };
+        ws.onclose = () => {
+          clearAttemptTimer(ws);
+          checkAllFailed();
+        };
+      };
+      try {
+        for (const gatewayURL of gatewayURLs) {
+          openGateway(gatewayURL);
+        }
+      } catch (err) {
+        settled = true;
+        clearTimeoutTimer();
+        signal.removeEventListener("abort", abort);
+        closeAll();
+        reject(err);
       }
     });
   }
   installSignaling(ws) {
     const channel = SignalingChannel.wrap(ws);
+    const generation = this.lifecycleGeneration;
     this.sig = channel;
-    channel.onMessage = (msg) => this.handleSignal(msg);
+    channel.onMessage = (msg) => {
+      if (this.sig !== channel || !this.isActiveRun(generation)) return;
+      this.handleSignal(msg);
+    };
     channel.onClose = () => {
       if (this.sig !== channel || this.stopped) return;
       this.sig = null;
@@ -269,11 +692,85 @@ var Publisher = class {
     };
     channel.onError = () => {
     };
+    this.resolveSignalingWaiters(channel);
+    const pending = this.pendingOffer;
+    if (pending?.sent) {
+      try {
+        channel.send(pending.message);
+      } catch {
+      }
+    }
+    if (this.localCandidateOfferSent) {
+      for (const candidate of this.retainedLocalCandidates) {
+        try {
+          channel.send(candidate);
+        } catch {
+          break;
+        }
+      }
+    }
     return channel;
   }
+  awaitSignaling() {
+    if (this.sig) return Promise.resolve(this.sig);
+    if (this.stopped) return Promise.reject(new Error("publisher stopped"));
+    return new Promise((resolve, reject) => {
+      this.signalingWaiters.add({ resolve, reject });
+    });
+  }
+  resolveSignalingWaiters(channel) {
+    const waiters = [...this.signalingWaiters];
+    this.signalingWaiters.clear();
+    for (const waiter of waiters) waiter.resolve(channel);
+  }
+  rejectSignalingWaiters(err) {
+    const waiters = [...this.signalingWaiters];
+    this.signalingWaiters.clear();
+    for (const waiter of waiters) waiter.reject(err);
+  }
+  async sendWhenSignalingAvailable(msg) {
+    while (!this.stopped) {
+      const channel = await this.awaitSignaling();
+      try {
+        if (channel.send(msg)) return;
+      } catch {
+      }
+      if (this.sig === channel) {
+        this.sig = null;
+        void this.resumeSignaling();
+      }
+    }
+    throw new Error("publisher stopped");
+  }
+  async sendOffer(message) {
+    if (this.pendingOffer) {
+      throw new Error("another negotiation offer is already pending");
+    }
+    const pending = { message, sent: false };
+    this.pendingOffer = pending;
+    try {
+      await this.sendWhenSignalingAvailable(message);
+      pending.sent = true;
+      const id = message.negotiation_id;
+      if (!id) throw new Error("negotiation offer is missing an id");
+      const answered = this.awaitAnswer(id);
+      void answered.then(
+        () => {
+          if (this.pendingOffer === pending) this.pendingOffer = null;
+        },
+        () => {
+          if (this.pendingOffer === pending) this.pendingOffer = null;
+        }
+      );
+      return { answered };
+    } catch (err) {
+      if (this.pendingOffer === pending) this.pendingOffer = null;
+      throw err;
+    }
+  }
   async resumeSignaling() {
     if (this.reconnecting || this.stopped) return;
-    if (!this.selectedGatewayURL || !this.readToken) {
+    if (!this.gatewayURL || !this.readToken) {
       this.terminateWithError(new Error("signaling closed and cannot be resumed"));
       return;
     }
@@ -312,7 +809,7 @@ var Publisher = class {
   }
   openResumeSocket(timeoutMs) {
     return new Promise((resolve, reject) => {
-      const u = new URL(this.selectedGatewayURL);
+      const u = new URL(this.gatewayURL);
       u.searchParams.set("token", this.readToken);
       const ws = new WebSocket(u.toString());
       this.resumeSocket = ws;
@@ -346,47 +843,88 @@ var Publisher = class {
   wait(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  terminateWithError(err) {
+  isActiveRun(generation, pc) {
+    return generation === this.lifecycleGeneration && !this.stopped && !this.runAbort?.signal.aborted && (!pc || this.pc === pc);
+  }
+  assertActiveRun(generation, pc) {
+    if (!this.isActiveRun(generation, pc)) {
+      throw new PublisherStoppedError("publisher stopped");
+    }
+  }
+  armPeerConnectionTimeout(generation, pc) {
+    this.clearPeerConnectionTimeout();
+    if (pc.connectionState === "connected") return;
+    const timeoutMs = Math.max(
+      0,
+      this.opts.peerConnectionTimeoutMs ?? defaultPeerConnectionTimeoutMs
+    );
+    const timer = setTimeout(() => {
+      if (this.peerConnectionTimer !== timer) return;
+      this.peerConnectionTimer = null;
+      if (!this.isActiveRun(generation, pc) || pc.connectionState === "connected") return;
+      this.terminateWithError(
+        new Error(`WebRTC connection timed out after ${timeoutMs}ms`),
+        true,
+        generation
+      );
+    }, timeoutMs);
+    this.peerConnectionTimer = timer;
+  }
+  clearPeerConnectionTimeout() {
+    if (this.peerConnectionTimer !== null) clearTimeout(this.peerConnectionTimer);
+    this.peerConnectionTimer = null;
+  }
+  terminateWithError(err, notify = true, generation = this.lifecycleGeneration) {
+    if (generation !== this.lifecycleGeneration) return;
+    this.lifecycleGeneration++;
+    this.runAbort?.abort();
+    this.runAbort = null;
+    this.clearPeerConnectionTimeout();
     this.stopped = true;
-    this.cancelMediaRecovery();
+    this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
     this.resumeSocket?.close();
     this.resumeSocket = null;
     this.sig?.close();
     this.sig = null;
+    this.rejectSignalingWaiters(err);
     this.pc?.close();
     this.pc = null;
+    this.textChannel = null;
+    this.speechEnabled = false;
+    this.speechPending = false;
+    this.speechTransceiver = null;
+    this.microphoneTransceiver = null;
+    this.typeSenders.clear();
     this.unwatchStreamTracks();
-    this.localStream?.getTracks().forEach((track) => track.stop());
-    this.localStream = null;
+    this.stopPublishedTracks();
+    this.clearIntentionalTrackEnds();
+    this.rejectPendingAnswer(new Error("publisher terminated"));
+    this.pendingOffer = null;
     this.hasAnswer = false;
     this.pendingRemoteCandidates = [];
+    this.pendingLocalCandidates = [];
+    this.localCandidateOfferSent = false;
+    this.clearRetainedICECandidates();
     this.readToken = null;
-    this.selectedGatewayURL = null;
-    this.opts.callbacks?.onError?.(err);
+    this.gatewayURL = null;
+    this.lastReportedICEPath = null;
+    if (notify) this.opts.callbacks?.onError?.(err);
   }
   handleSignal(msg) {
     switch (msg.type) {
       case "answer": {
         if (!this.pc) return;
-        this.pc.setRemoteDescription(
-          new RTCSessionDescription({ type: "answer", sdp: msg.sdp })
-        ).then(() => {
-          this.hasAnswer = true;
-          for (const init of this.pendingRemoteCandidates) {
-            this.pc?.addIceCandidate(init).catch(() => {
-            });
-          }
-          this.pendingRemoteCandidates = [];
-        }).catch((err) => {
-          this.opts.callbacks?.onError?.(
-            new Error(`failed to set remote description: ${err}`)
-          );
-        });
+        const pending = this.pendingAnswer;
+        if (!pending) break;
+        if (msg.negotiation_id && msg.negotiation_id !== pending.id) break;
+        this.pendingAnswer = null;
+        pending.resolve(msg.sdp);
         break;
       }
       case "ice_candidate": {
         if (!this.pc) return;
+        if (!this.retainRemoteCandidate(msg)) return;
         const init = {
           candidate: msg.candidate,
           sdpMid: msg.sdp_mid ?? null,
@@ -404,8 +942,14 @@ var Publisher = class {
       case "connection_state": {
         break;
       }
-      case "media_stall":
       case "media_track_ended": {
+        if (msg.track === "audio") break;
+        if (this.consumeIntentionalTrackEnd(msg.track, msg.track_id)) break;
+        void this.beginMediaRecovery(msg.track);
+        break;
+      }
+      case "media_stall": {
+        if (msg.track === "audio") break;
         void this.beginMediaRecovery(msg.track);
         break;
       }
@@ -414,7 +958,18 @@ var Publisher = class {
         break;
       }
       case "error": {
-        this.opts.callbacks?.onError?.(new Error(msg.error));
+        const err = new ReportedPublisherError(msg.error, msg.fatal === true);
+        const pending = this.pendingAnswer;
+        let matchedPending = false;
+        if (pending && (!msg.negotiation_id || msg.negotiation_id === pending.id)) {
+          matchedPending = true;
+          this.pendingAnswer = null;
+          pending.reject(err);
+        }
+        if (err.fatal) this.opts.callbacks?.onError?.(err);
+        if (err.fatal && !matchedPending) {
+          this.terminateWithError(err, false);
+        }
         break;
       }
       case "resumed":
@@ -422,86 +977,482 @@ var Publisher = class {
     }
   }
   async beginMediaRecovery(trackType) {
-    if (this.stopped || this.recoveringMedia || this.recoveryRequired) return;
-    const tracks = this.localStream?.getVideoTracks() ?? [];
-    const liveTracks = tracks.filter((track) => track.readyState !== "ended");
+    const state = this.recoveryState(trackType);
+    if (this.stopped || state.recovering || state.required) return;
+    const liveTracks = this.tracksOfType(trackType).filter(
+      (track) => track.readyState !== "ended"
+    );
     if (liveTracks.length === 0) {
       this.failMediaRecovery(trackType, "capture_ended");
       return;
     }
-    this.recoveringMedia = true;
-    const generation = ++this.recoveryGeneration;
-    this.recoveryAction = "sender_restart";
+    state.recovering = true;
+    state.generation = ++this.recoverySequence;
+    const generation = state.generation;
+    state.action = "sender_restart";
     this.emitRecoveryTransition({ state: "recovering", track: trackType, action: "sender_restart" });
     this.sendRecoveryDiagnostic("recovery_started", trackType, "sender_restart");
-    await this.restartSenders(liveTracks, generation);
-    if (!this.isCurrentRecovery(generation)) return;
+    await this.restartSenders(trackType, liveTracks, generation);
+    if (!this.isCurrentRecovery(trackType, generation)) return;
     await this.wait(senderRecoveryWaitMs);
-    if (!this.isCurrentRecovery(generation)) return;
-    this.recoveryAction = "ice_restart";
+    if (!this.isCurrentRecovery(trackType, generation)) return;
+    state.action = "ice_restart";
     this.emitRecoveryTransition({ state: "recovering", track: trackType, action: "ice_restart" });
     this.sendRecoveryDiagnostic("recovery_retry", trackType, "ice_restart");
     try {
-      await this.renegotiate(true);
+      await this.sharedIceRestart();
     } catch {
     }
+    if (!this.isCurrentRecovery(trackType, generation)) return;
     await this.wait(iceRecoveryWaitMs);
-    if (!this.isCurrentRecovery(generation)) return;
+    if (!this.isCurrentRecovery(trackType, generation)) return;
     this.failMediaRecovery(trackType, "automatic_recovery_failed");
   }
-  async restartSenders(tracks, generation) {
-    const live = new Set(tracks);
-    const senders = this.pc?.getSenders().filter(
-      (sender) => sender.track && live.has(sender.track)
-    ) ?? [];
-    if (senders.length === 0) return;
-    const originals = senders.map((sender) => ({ sender, track: sender.track }));
+  async restartSenders(trackType, tracks, generation) {
+    const lifecycleGeneration = this.lifecycleGeneration;
     try {
-      await Promise.all(originals.map(({ sender }) => sender.replaceTrack(null)));
-      await this.wait(senderRestartPauseMs);
-      if (!this.isCurrentRecovery(generation)) return;
-      await Promise.all(originals.map(({ sender, track }) => sender.replaceTrack(track)));
-      await this.renegotiate(false);
-    } catch {
+      await this.enqueueNegotiation(async () => {
+        if (!this.isCurrentRecovery(trackType, generation)) return false;
+        const live = new Set(tracks);
+        const senders = this.pc?.getSenders().filter(
+          (sender) => sender.track && live.has(sender.track)
+        ) ?? [];
+        if (senders.length === 0) return false;
+        const originals = senders.map((sender) => ({ sender, track: sender.track }));
+        try {
+          await Promise.all(originals.map(({ sender }) => sender.replaceTrack(null)));
+          await this.wait(senderRestartPauseMs);
+          if (!this.isCurrentRecovery(trackType, generation)) return false;
+          await Promise.all(originals.map(({ sender, track }) => sender.replaceTrack(track)));
+          if (!this.isCurrentRecovery(trackType, generation)) return false;
+          return;
+        } finally {
+          const restored = await Promise.allSettled(originals.map(async ({ sender, track }) => {
+            if (sender.track === null && this.published.has(track) && track.readyState !== "ended") {
+              await sender.replaceTrack(track);
+            }
+          }));
+          if (restored.some((result) => result.status === "rejected")) {
+            throw new SenderRestoreError("failed to restore a detached media sender");
+          }
+        }
+      });
+    } catch (err) {
+      if (err instanceof SenderRestoreError && lifecycleGeneration === this.lifecycleGeneration && !this.stopped) {
+        this.terminateWithError(err, true, lifecycleGeneration);
+        return;
+      }
     }
   }
-  async renegotiate(iceRestart) {
+  /**
+   * Adds a recovery renegotiation to the same queue as user operations. The
+   * recovery ladder awaits its completion before starting the stage observation
+   * window. If recovery has completed by the time this reaches the head of the
+   * queue, it is skipped.
+   */
+  /** Returns the peer-wide ICE attempt shared by all active track recoveries. */
+  sharedIceRestart() {
+    if (this.iceRestartAttempt) return this.iceRestartAttempt.promise;
+    const id = ++this.iceRestartSequence;
+    const promise = this.enqueueNegotiation(
+      () => {
+        if (this.iceRestartAttempt?.id !== id || !this.hasActiveMediaRecovery()) return false;
+      },
+      { iceRestart: true }
+    );
+    const attempt = { id, promise };
+    this.iceRestartAttempt = attempt;
+    void promise.finally(() => {
+      if (this.iceRestartAttempt === attempt) this.iceRestartAttempt = null;
+    }).catch(() => {
+    });
+    return promise;
+  }
+  /**
+   * Serializes a renegotiation onto the shared chain: it waits for any prior
+   * negotiation to finish (its answer applied), sends a fresh offer, and resolves
+   * only once this offer's answer has been applied. This prevents overlapping
+   * offers and answers being applied to the wrong offer.
+   */
+  enqueueNegotiation(mutate, opts = {}) {
+    const generation = this.lifecycleGeneration;
+    const run = this.negotiationChain.catch(() => {
+    }).then(() => {
+      this.assertActiveRun(generation);
+      return this.negotiateOnce(mutate, opts, generation);
+    });
+    this.negotiationChain = run.catch(() => {
+    });
+    return run;
+  }
+  async negotiateOnce(mutate, opts, generation) {
     const pc = this.pc;
-    const signaling = this.sig;
-    if (!pc || !signaling) throw new Error("publisher signaling is unavailable");
-    if (iceRestart) pc.restartIce?.();
-    const offer = await pc.createOffer(iceRestart ? { iceRestart: true } : void 0);
-    await pc.setLocalDescription(offer);
-    await this.gatherComplete();
-    const local = pc.localDescription;
-    if (!local) throw new Error("local description missing");
-    this.hasAnswer = false;
+    if (!pc || !this.isActiveRun(generation, pc)) {
+      throw new PublisherStoppedError("publisher stopped");
+    }
+    if (!this.runAbort?.signal) throw new PublisherStoppedError("publisher stopped");
+    const previousHasAnswer = this.hasAnswer;
+    const previousRemoteCandidates = this.pendingRemoteCandidates;
+    const previousLocalCandidateOfferSent = this.localCandidateOfferSent;
+    const previousRetainedLocalCandidates = [...this.retainedLocalCandidates];
+    const previousRetainedLocalCandidateKeys = new Set(this.retainedLocalCandidateKeys);
+    const previousLocalCandidateGeneration = this.localCandidateGeneration;
+    await this.awaitSignaling();
+    this.assertActiveRun(generation, pc);
+    let change;
+    let localOfferSet = false;
+    let answerReceived = false;
+    try {
+      const result = await mutate();
+      this.assertActiveRun(generation, pc);
+      if (result === false) return;
+      if (result && typeof result === "object") change = result;
+      if (opts.iceRestart) pc.restartIce?.();
+      const offer = await pc.createOffer(opts.iceRestart ? { iceRestart: true } : void 0);
+      this.assertActiveRun(generation, pc);
+      this.beginLocalCandidateBatch();
+      await pc.setLocalDescription(offer);
+      localOfferSet = true;
+      this.assertActiveRun(generation, pc);
+      const local = pc.localDescription;
+      if (!local) throw new Error("local description missing");
+      this.hasAnswer = false;
+      this.pendingRemoteCandidates = [];
+      const id = this.nextNegotiationId();
+      const { answered } = await this.sendOffer({
+        type: "offer",
+        sdp: local.sdp,
+        sdp_type: "offer",
+        negotiation_id: id,
+        tracks: change?.labels ?? this.buildTrackLabels(),
+        speech_enabled: this.speechEnabled || this.speechPending || void 0
+      });
+      this.releaseLocalCandidateBatch();
+      const sdp = await answered;
+      this.assertActiveRun(generation, pc);
+      answerReceived = true;
+      await pc.setRemoteDescription(new RTCSessionDescription({ type: "answer", sdp }));
+      this.assertActiveRun(generation, pc);
+      this.applyAnswered(pc);
+      await change?.commit?.();
+    } catch (err) {
+      let rollbackFailed = false;
+      if (localOfferSet && this.pc === pc && pc.signalingState === "have-local-offer") {
+        try {
+          await pc.setLocalDescription({ type: "rollback" });
+        } catch {
+          rollbackFailed = true;
+        }
+      }
+      try {
+        await change?.rollback?.();
+      } catch {
+        rollbackFailed = true;
+      }
+      const ambiguous = rollbackFailed || answerReceived || err instanceof NegotiationTimeoutError || err instanceof SenderRestoreError || err instanceof ReportedPublisherError && err.fatal;
+      if (this.isActiveRun(generation, pc) && ambiguous) {
+        try {
+          await change?.discard?.();
+        } catch {
+        }
+        const failure = err instanceof Error ? err : new Error(String(err));
+        this.terminateWithError(
+          failure,
+          !(err instanceof ReportedPublisherError),
+          generation
+        );
+      } else if (this.isActiveRun(generation, pc)) {
+        const buffered = this.pendingRemoteCandidates;
+        this.hasAnswer = previousHasAnswer;
+        this.pendingRemoteCandidates = previousRemoteCandidates;
+        this.pendingLocalCandidates = [];
+        this.localCandidateOfferSent = previousLocalCandidateOfferSent;
+        this.retainedLocalCandidates = previousRetainedLocalCandidates;
+        this.retainedLocalCandidateKeys = previousRetainedLocalCandidateKeys;
+        this.localCandidateGeneration = previousLocalCandidateGeneration;
+        if (previousHasAnswer) {
+          for (const init of buffered) {
+            pc.addIceCandidate(init).catch(() => {
+            });
+          }
+        }
+      }
+      throw err;
+    }
+  }
+  /**
+   * Registers interest in the answer for the offer identified by `id` and returns
+   * a promise for its SDP. A second pending answer is an invariant violation: all
+   * offer creation, including recovery, must pass through negotiationChain.
+   */
+  nextNegotiationId() {
+    return `n${++this.negotiationSeq}`;
+  }
+  handleTextMessage(data) {
+    if (typeof data !== "string") return;
+    try {
+      const message = JSON.parse(data);
+      if (message.type === "assistant_text" && message.utterance_id && message.text) {
+        this.opts.callbacks?.onAssistantText?.({ utteranceId: message.utterance_id, text: message.text });
+      } else if ((message.type === "user_text_accepted" || message.type === "user_text_rejected") && message.message_id) {
+        this.opts.callbacks?.onUserTextResult?.({
+          messageId: message.message_id,
+          accepted: message.type === "user_text_accepted",
+          reason: message.reason
+        });
+      }
+    } catch {
+    }
+  }
+  awaitAnswer(id) {
+    if (this.pendingAnswer) {
+      return Promise.reject(new Error("another negotiation is already awaiting an answer"));
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.pendingAnswer?.id === id) {
+          this.pendingAnswer = null;
+          reject(new NegotiationTimeoutError("timed out waiting for renegotiation answer"));
+        }
+      }, this.negotiationAnswerTimeoutMs());
+      this.pendingAnswer = {
+        id,
+        resolve: (sdp) => {
+          clearTimeout(timer);
+          resolve(sdp);
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      };
+    });
+  }
+  negotiationAnswerTimeoutMs() {
+    const reconnectTimeout = this.opts.signalingReconnectTimeoutMs ?? defaultSignalingReconnectTimeoutMs;
+    return Math.max(
+      minimumNegotiationAnswerTimeoutMs,
+      Math.max(0, reconnectTimeout) + negotiationReconnectGraceMs
+    );
+  }
+  handleLocalICECandidate(candidate) {
+    const message = {
+      type: "ice_candidate",
+      candidate: candidate.candidate,
+      sdp_mid: candidate.sdpMid ?? void 0,
+      sdp_mline_index: candidate.sdpMLineIndex ?? void 0,
+      username_fragment: candidate.usernameFragment ?? void 0
+    };
+    if (!this.retainLocalCandidate(message)) return;
+    if (!this.localCandidateOfferSent) {
+      this.pendingLocalCandidates.push(message);
+      return;
+    }
+    void this.sendWhenSignalingAvailable(message).catch(() => {
+    });
+  }
+  candidateKey(candidate) {
+    return JSON.stringify([
+      candidate.candidate,
+      candidate.sdp_mid ?? null,
+      candidate.sdp_mline_index ?? null,
+      candidate.username_fragment ?? null
+    ]);
+  }
+  retainLocalCandidate(candidate) {
+    const generation = candidate.username_fragment;
+    if (generation) {
+      if (this.localCandidateGeneration && this.localCandidateGeneration !== generation) {
+        this.retainedLocalCandidates = [];
+        this.retainedLocalCandidateKeys.clear();
+      }
+      this.localCandidateGeneration = generation;
+    }
+    const key = this.candidateKey(candidate);
+    if (this.retainedLocalCandidateKeys.has(key)) return false;
+    if (this.retainedLocalCandidates.length === maxRetainedICECandidates) {
+      const evicted = this.retainedLocalCandidates.shift();
+      if (evicted) this.retainedLocalCandidateKeys.delete(this.candidateKey(evicted));
+    }
+    this.retainedLocalCandidates.push(candidate);
+    this.retainedLocalCandidateKeys.add(key);
+    return true;
+  }
+  retainRemoteCandidate(candidate) {
+    const generation = candidate.username_fragment;
+    if (generation) {
+      if (this.remoteCandidateGeneration && this.remoteCandidateGeneration !== generation) {
+        this.remoteCandidateKeys.clear();
+        this.remoteCandidateOrder = [];
+      }
+      this.remoteCandidateGeneration = generation;
+    }
+    const key = this.candidateKey(candidate);
+    if (this.remoteCandidateKeys.has(key)) return false;
+    if (this.remoteCandidateOrder.length === maxRetainedICECandidates) {
+      const evicted = this.remoteCandidateOrder.shift();
+      if (evicted) this.remoteCandidateKeys.delete(evicted);
+    }
+    this.remoteCandidateOrder.push(key);
+    this.remoteCandidateKeys.add(key);
+    return true;
+  }
+  clearRetainedICECandidates() {
+    this.retainedLocalCandidates = [];
+    this.retainedLocalCandidateKeys.clear();
+    this.localCandidateGeneration = null;
+    this.remoteCandidateKeys.clear();
+    this.remoteCandidateOrder = [];
+    this.remoteCandidateGeneration = null;
+  }
+  beginLocalCandidateBatch() {
+    this.localCandidateOfferSent = false;
+    this.pendingLocalCandidates = [];
+  }
+  releaseLocalCandidateBatch() {
+    this.localCandidateOfferSent = true;
+    const candidates = this.pendingLocalCandidates;
+    this.pendingLocalCandidates = [];
+    for (const candidate of candidates) {
+      void this.sendWhenSignalingAvailable(candidate).catch(() => {
+      });
+    }
+  }
+  // applyAnswered flushes ICE candidates buffered before the answer landed.
+  applyAnswered(pc) {
+    if (this.pc !== pc) return;
+    this.hasAnswer = true;
+    for (const init of this.pendingRemoteCandidates) {
+      pc.addIceCandidate(init).catch(() => {
+      });
+    }
     this.pendingRemoteCandidates = [];
-    signaling.send({ type: "offer", sdp: local.sdp, sdp_type: "offer" });
+    this.watchSelectedICEPairChanges(pc);
+    void this.reportSelectedICEPath(pc);
+  }
+  watchSelectedICEPairChanges(pc) {
+    try {
+      const dtlsTransports = [
+        pc.sctp?.transport,
+        ...pc.getSenders().map((sender) => sender.transport),
+        ...pc.getReceivers().map((receiver) => receiver.transport)
+      ];
+      for (const dtls of dtlsTransports) {
+        const ice = dtls?.iceTransport;
+        if (!ice || this.watchedICETransports.has(ice)) continue;
+        this.watchedICETransports.add(ice);
+        ice.addEventListener("selectedcandidatepairchange", () => {
+          void this.reportSelectedICEPath(pc);
+        });
+      }
+    } catch {
+    }
+  }
+  async reportSelectedICEPath(pc) {
+    if (this.pc !== pc || this.stopped) return;
+    let stats;
+    try {
+      stats = await pc.getStats();
+    } catch {
+      return;
+    }
+    if (this.pc !== pc || this.stopped) return;
+    let selectedPairID;
+    let selectedPair;
+    stats.forEach((report) => {
+      const value = report;
+      if (value.type === "transport" && typeof value.selectedCandidatePairId === "string") {
+        selectedPairID = value.selectedCandidatePairId;
+      }
+    });
+    if (selectedPairID) {
+      selectedPair = stats.get(selectedPairID);
+    }
+    if (!selectedPair) {
+      stats.forEach((report) => {
+        const value = report;
+        if (!selectedPair && value.type === "candidate-pair" && value.state === "succeeded" && value.nominated === true) {
+          selectedPair = value;
+        }
+      });
+    }
+    if (!selectedPair) return;
+    const localID = selectedPair.localCandidateId;
+    const remoteID = selectedPair.remoteCandidateId;
+    if (typeof localID !== "string") return;
+    const local = stats.get(localID);
+    const remote = typeof remoteID === "string" ? stats.get(remoteID) : void 0;
+    if (!local || typeof local.candidateType !== "string") return;
+    const message = {
+      type: "ice_path",
+      local_candidate_type: local.candidateType,
+      local_protocol: typeof local.protocol === "string" ? local.protocol : void 0,
+      remote_candidate_type: typeof remote?.candidateType === "string" ? remote.candidateType : void 0,
+      remote_protocol: typeof remote?.protocol === "string" ? remote.protocol : void 0,
+      relay_protocol: typeof local.relayProtocol === "string" ? local.relayProtocol : void 0,
+      turn_url: typeof local.url === "string" ? local.url : void 0
+    };
+    const fingerprint = JSON.stringify(message);
+    if (fingerprint === this.lastReportedICEPath) return;
+    this.lastReportedICEPath = fingerprint;
+    try {
+      await this.sendWhenSignalingAvailable(message);
+    } catch {
+      if (this.lastReportedICEPath === fingerprint) {
+        this.lastReportedICEPath = null;
+      }
+    }
   }
   completeMediaRecovery(trackType) {
-    if (!this.recoveringMedia) return;
-    const action = this.recoveryAction ?? void 0;
-    this.cancelMediaRecovery();
+    const state = this.recoveryStates.get(trackType);
+    if (!state?.recovering) return;
+    const action = state.action ?? void 0;
+    this.cancelMediaRecovery(trackType);
     this.emitRecoveryTransition({ state: "recovered", track: trackType, action });
   }
   failMediaRecovery(trackType, reason) {
-    if (this.stopped || this.recoveryRequired) return;
-    this.recoveryRequired = true;
-    const action = this.recoveryAction ?? void 0;
-    this.cancelMediaRecovery();
+    const state = this.recoveryState(trackType);
+    if (this.stopped || state.required) return;
+    state.required = true;
+    const action = state.action ?? void 0;
+    this.cancelMediaRecovery(trackType);
     const event = { state: "failed", track: trackType, action, reason };
     this.emitRecoveryTransition(event);
     this.opts.callbacks?.onRecoveryRequired?.(event);
     this.sendRecoveryDiagnostic("recovery_failed", trackType, action, reason);
   }
-  cancelMediaRecovery() {
-    this.recoveryGeneration++;
-    this.recoveringMedia = false;
-    this.recoveryAction = null;
+  recoveryState(trackType) {
+    let state = this.recoveryStates.get(trackType);
+    if (!state) {
+      state = { generation: 0, recovering: false, required: false, action: null };
+      this.recoveryStates.set(trackType, state);
+    }
+    return state;
+  }
+  cancelMediaRecovery(trackType) {
+    const state = this.recoveryState(trackType);
+    state.generation = ++this.recoverySequence;
+    state.recovering = false;
+    state.action = null;
+    this.clearSharedIceRestartIfIdle();
+  }
+  cancelAllMediaRecovery() {
+    for (const trackType of this.recoveryStates.keys()) {
+      this.cancelMediaRecovery(trackType);
+    }
+  }
+  isCurrentRecovery(trackType, generation) {
+    const state = this.recoveryStates.get(trackType);
+    return !this.stopped && !!state?.recovering && state.generation === generation;
   }
-  isCurrentRecovery(generation) {
-    return !this.stopped && this.recoveringMedia && generation === this.recoveryGeneration;
+  hasActiveMediaRecovery() {
+    for (const state of this.recoveryStates.values()) {
+      if (state.recovering) return true;
+    }
+    return false;
+  }
+  clearSharedIceRestartIfIdle() {
+    if (!this.hasActiveMediaRecovery()) this.iceRestartAttempt = null;
   }
   emitRecoveryTransition(event) {
     this.opts.callbacks?.onRecoveryStateChange?.(event);
@@ -509,39 +1460,354 @@ var Publisher = class {
   sendRecoveryDiagnostic(event, track, action, reason) {
     this.sig?.send({ type: "recovery_event", event, track, action, reason });
   }
-  watchStreamTracks(stream) {
-    for (const track of stream.getVideoTracks()) {
-      const handler = () => this.failMediaRecovery("screen", "capture_ended");
-      track.addEventListener("ended", handler);
-      this.trackEndHandlers.set(track, handler);
+  // -------------------------------------------------------------------------
+  // Published-track bookkeeping
+  // -------------------------------------------------------------------------
+  requireSingleVideoTrack(stream) {
+    const tracks = stream.getVideoTracks();
+    if (tracks.length !== 1) {
+      throw new Error(
+        `expected exactly one video track, received ${tracks.length}`
+      );
     }
+    this.requireLiveVideoTrack(tracks[0]);
+    return tracks[0];
   }
-  unwatchStreamTracks() {
-    for (const [track, handler] of this.trackEndHandlers) {
-      track.removeEventListener("ended", handler);
+  requireLiveVideoTrack(track) {
+    if (track.readyState === "ended") {
+      throw new Error("video track has already ended");
     }
-    this.trackEndHandlers.clear();
   }
-  /** Waits for ICE gathering to reach the "complete" state. */
-  gatherComplete() {
-    return new Promise((resolve) => {
-      const pc = this.pc;
-      if (!pc) {
-        resolve();
-        return;
+  requireLiveTrack(track, kind) {
+    if (track.readyState === "ended") {
+      throw new Error(`${kind} track has already ended`);
+    }
+  }
+  requireSingleAudioTrack(stream) {
+    const tracks = stream.getAudioTracks();
+    if (tracks.length !== 1) {
+      throw new Error(
+        `expected exactly one audio track, received ${tracks.length}`
+      );
+    }
+    if (tracks[0].readyState === "ended") {
+      throw new Error("audio track has already ended");
+    }
+    return tracks[0];
+  }
+  /**
+   * Stages the microphone track onto the peer connection. Unlike video, audio
+   * has no recovery ladder and no SSIM/frame semantics, so this simply adds (or
+   * replaces) the single audio sender and declares the updated labels.
+   */
+  async stagePublishAudio(track, stream) {
+    const pc = this.pc;
+    if (!pc) throw new Error("publisher not started");
+    if (track.readyState === "ended") throw new Error("audio track has already ended");
+    const type = "audio";
+    if (this.published.get(track) === type) return false;
+    const previous = this.tracksOfType(type).map((oldTrack) => ({
+      track: oldTrack,
+      stream: this.publishedStreams.get(oldTrack)
+    }));
+    const typeSender = this.typeSenders.get(type) ?? null;
+    let addedSender = null;
+    let replacedSender = null;
+    if (previous.length > 0) {
+      if (previous.length !== 1 || !typeSender || typeSender.track !== previous[0].track) {
+        throw new SenderRestoreError("published audio sender is unavailable");
       }
-      if (pc.iceGatheringState === "complete") {
-        resolve();
-        return;
+      replacedSender = typeSender;
+      await replacedSender.replaceTrack(track);
+    } else {
+      if (typeSender?.track) {
+        throw new SenderRestoreError("inactive audio sender still has a track");
       }
-      const handler = () => {
-        if (pc.iceGatheringState === "complete") {
-          pc.removeEventListener("icegatheringstatechange", handler);
-          resolve();
+      if (this.microphoneTransceiver && this.microphoneTransceiver.sender.track === null) {
+        addedSender = this.microphoneTransceiver.sender;
+        await addedSender.replaceTrack(track);
+        this.microphoneTransceiver.direction = "sendonly";
+      } else {
+        addedSender = this.addMicrophoneTrack(pc, track, stream);
+      }
+      this.typeSenders.set(type, addedSender);
+    }
+    return {
+      labels: this.labelsReplacingType(type, track),
+      commit: () => {
+        for (const { track: oldTrack } of previous) {
+          this.unwatchTrack(oldTrack);
+          this.published.delete(oldTrack);
+          this.publishedStreams.delete(oldTrack);
+          oldTrack.stop();
         }
-      };
-      pc.addEventListener("icegatheringstatechange", handler);
+        this.published.set(track, type);
+        this.publishedStreams.set(track, stream);
+        this.watchMicrophone(track);
+      },
+      rollback: async () => {
+        if (this.pc !== pc) return;
+        if (addedSender && pc.getSenders().includes(addedSender)) {
+          pc.removeTrack(addedSender);
+          if (typeSender) this.typeSenders.set(type, typeSender);
+          else this.typeSenders.delete(type);
+        }
+        if (replacedSender && previous.length > 0) {
+          const oldTrack = previous[0].track;
+          if (oldTrack.readyState !== "ended") {
+            await replacedSender.replaceTrack(oldTrack);
+          }
+        } else if (replacedSender) {
+          pc.removeTrack(replacedSender);
+        }
+      },
+      discard: () => track.stop()
+    };
+  }
+  /**
+   * Gives the microphone its own sendonly transceiver. addTrack() may reuse an
+   * existing compatible recvonly transceiver, which would collapse the
+   * microphone and assistant speech roles when speech was enabled first.
+   * addTransceiver() always creates a distinct m-line and its direction keeps
+   * the server's outbound speech sender on the dedicated speech transceiver.
+   */
+  addMicrophoneTrack(pc, track, stream) {
+    const transceiver = pc.addTransceiver(track, {
+      direction: "sendonly",
+      streams: [stream]
     });
+    this.microphoneTransceiver = transceiver;
+    return transceiver.sender;
+  }
+  /** Registers one physical video track under its logical type and source stream. */
+  registerTrack(track, stream, type) {
+    this.published.set(track, type);
+    this.publishedStreams.set(track, stream);
+    this.watchTrack(track);
+  }
+  /** The live video tracks currently published under the given type. */
+  tracksOfType(type) {
+    const out = [];
+    for (const [track, tt] of this.published) {
+      if (tt === type) out.push(track);
+    }
+    return out;
+  }
+  /** Builds the id → type label array declared to the server on every offer. */
+  buildTrackLabels() {
+    const labels = [];
+    for (const [track, type] of this.published) {
+      labels.push({ id: track.id, type });
+    }
+    return labels;
+  }
+  labelsReplacingType(type, replacement) {
+    const labels = [];
+    for (const [track, publishedType] of this.published) {
+      if (publishedType !== type) labels.push({ id: track.id, type: publishedType });
+    }
+    if (replacement) labels.push({ id: replacement.id, type });
+    return labels;
+  }
+  async stagePublish(track, stream, type) {
+    const pc = this.pc;
+    if (!pc) throw new Error("publisher not started");
+    this.requireLiveVideoTrack(track);
+    const alreadyPublishedAs = this.published.get(track);
+    if (alreadyPublishedAs === type) return false;
+    if (alreadyPublishedAs) {
+      throw new Error(`video track is already published as ${alreadyPublishedAs}`);
+    }
+    const previous = this.tracksOfType(type).map((oldTrack) => ({
+      track: oldTrack,
+      stream: this.publishedStreams.get(oldTrack)
+    }));
+    const typeSender = this.typeSenders.get(type) ?? null;
+    let addedSender = null;
+    let replacedSender = null;
+    if (previous.length > 0) {
+      if (previous.length !== 1 || !typeSender || typeSender.track !== previous[0].track) {
+        throw new SenderRestoreError(`published ${type} sender is unavailable`);
+      }
+      replacedSender = typeSender;
+      await replacedSender.replaceTrack(track);
+    } else {
+      if (typeSender?.track) {
+        throw new SenderRestoreError(`inactive ${type} sender still has a track`);
+      }
+      addedSender = pc.addTrack(track, stream);
+      this.typeSenders.set(type, addedSender);
+    }
+    return {
+      labels: this.labelsReplacingType(type, track),
+      commit: () => {
+        this.cancelMediaRecovery(type);
+        this.recoveryState(type).required = false;
+        for (const { track: oldTrack } of previous) {
+          this.unwatchTrack(oldTrack);
+          this.published.delete(oldTrack);
+          this.publishedStreams.delete(oldTrack);
+          oldTrack.stop();
+        }
+        this.registerTrack(track, stream, type);
+        if (track.readyState === "ended") {
+          this.failMediaRecovery(type, "capture_ended");
+        }
+      },
+      rollback: async () => {
+        if (this.pc !== pc) return;
+        if (addedSender && pc.getSenders().includes(addedSender)) {
+          pc.removeTrack(addedSender);
+          if (typeSender) this.typeSenders.set(type, typeSender);
+          else this.typeSenders.delete(type);
+        }
+        if (replacedSender && previous.length > 0) {
+          const oldTrack = previous[0].track;
+          if (oldTrack.readyState !== "ended") {
+            await replacedSender.replaceTrack(oldTrack);
+          }
+        } else if (replacedSender) {
+          pc.removeTrack(replacedSender);
+        }
+      },
+      discard: () => track.stop()
+    };
+  }
+  stageUnpublish(type) {
+    const pc = this.pc;
+    if (!pc) throw new Error("publisher not started");
+    const previous = this.tracksOfType(type).map((track) => ({
+      track,
+      stream: this.publishedStreams.get(track)
+    }));
+    const typeSender = this.typeSenders.get(type);
+    if (previous.length !== 1 || !typeSender || typeSender.track !== previous[0].track) {
+      throw new SenderRestoreError(`published ${type} sender is unavailable`);
+    }
+    for (const { track } of previous) this.expectIntentionalTrackEnd(track.id, type);
+    pc.removeTrack(typeSender);
+    return {
+      labels: this.labelsReplacingType(type),
+      commit: () => {
+        this.cancelMediaRecovery(type);
+        this.recoveryState(type).required = false;
+        this.typeSenders.delete(type);
+        for (const { track } of previous) {
+          this.unwatchTrack(track);
+          this.published.delete(track);
+          this.publishedStreams.delete(track);
+          track.stop();
+        }
+      },
+      rollback: () => {
+        if (this.pc !== pc) return;
+        this.forgetIntentionalTrackEnds(previous.map(({ track }) => track.id));
+        return Promise.all(previous.map(async ({ track }) => {
+          if (track.readyState === "ended") return;
+          await typeSender.replaceTrack(track);
+        })).then(() => void 0);
+      }
+    };
+  }
+  /** Stops every published local track and clears the published map. */
+  stopPublishedTracks() {
+    for (const track of this.published.keys()) {
+      track.stop();
+    }
+    this.published.clear();
+    this.publishedStreams.clear();
+  }
+  expectIntentionalTrackEnd(trackID, type) {
+    const prior = this.intentionalTrackEnds.get(trackID);
+    if (prior) clearTimeout(prior.timer);
+    const retentionMs = Math.max(
+      minimumIntentionalTrackEndRetentionMs,
+      this.negotiationAnswerTimeoutMs()
+    );
+    const timer = setTimeout(() => {
+      const current = this.intentionalTrackEnds.get(trackID);
+      if (current?.timer === timer) this.intentionalTrackEnds.delete(trackID);
+    }, retentionMs);
+    this.intentionalTrackEnds.set(trackID, { type, timer });
+  }
+  forgetIntentionalTrackEnds(trackIDs) {
+    for (const trackID of trackIDs) {
+      const expected = this.intentionalTrackEnds.get(trackID);
+      if (!expected) continue;
+      clearTimeout(expected.timer);
+      this.intentionalTrackEnds.delete(trackID);
+    }
+  }
+  consumeIntentionalTrackEnd(type, trackID) {
+    if (trackID) {
+      const expected = this.intentionalTrackEnds.get(trackID);
+      if (!expected || expected.type !== type) return false;
+      clearTimeout(expected.timer);
+      this.intentionalTrackEnds.delete(trackID);
+      return true;
+    }
+    for (const [id, expected] of this.intentionalTrackEnds) {
+      if (expected.type !== type) continue;
+      clearTimeout(expected.timer);
+      this.intentionalTrackEnds.delete(id);
+      return true;
+    }
+    return false;
+  }
+  clearIntentionalTrackEnds() {
+    for (const expected of this.intentionalTrackEnds.values()) {
+      clearTimeout(expected.timer);
+    }
+    this.intentionalTrackEnds.clear();
+  }
+  /**
+   * Watches a track's "ended" event so an involuntary capture stop (the user
+   * revokes a screen share, a device unplugs) reports as a recovery failure for
+   * that track's actual type. Intentional removals unwatch first.
+   */
+  watchTrack(track) {
+    if (this.trackEndHandlers.has(track)) return;
+    const handler = () => {
+      const type = this.published.get(track) ?? "camera";
+      this.failMediaRecovery(type, "capture_ended");
+    };
+    track.addEventListener("ended", handler);
+    this.trackEndHandlers.set(track, handler);
+  }
+  /**
+   * Watches a microphone only for lifecycle removal. An ended microphone is not
+   * recovered like video; it is negotiated away so the media server can flush
+   * the utterance and release transcription resources.
+   */
+  watchMicrophone(track) {
+    if (this.trackEndHandlers.has(track)) return;
+    const generation = this.lifecycleGeneration;
+    const handler = () => {
+      if (this.published.get(track) !== "audio") return;
+      void this.enqueueNegotiation(() => {
+        if (this.published.get(track) !== "audio") return false;
+        return this.stageUnpublish("audio");
+      }).catch((err) => {
+        if (!this.isActiveRun(generation)) return;
+        const failure = err instanceof Error ? err : new Error(String(err));
+        this.terminateWithError(failure, true, generation);
+      });
+    };
+    track.addEventListener("ended", handler);
+    this.trackEndHandlers.set(track, handler);
+    if (track.readyState === "ended") handler(new Event("ended"));
+  }
+  unwatchTrack(track) {
+    const handler = this.trackEndHandlers.get(track);
+    if (!handler) return;
+    track.removeEventListener("ended", handler);
+    this.trackEndHandlers.delete(track);
+  }
+  unwatchStreamTracks() {
+    for (const [track, handler] of this.trackEndHandlers) {
+      track.removeEventListener("ended", handler);
+    }
+    this.trackEndHandlers.clear();
   }
 };
 
@@ -569,10 +1835,23 @@ async function captureScreen(opts = {}) {
   const mediaDevices = opts.mediaDevices ?? navigator.mediaDevices;
   return mediaDevices.getDisplayMedia(constraints);
 }
+async function captureMicrophone(opts = {}) {
+  const constraints = {
+    audio: opts.audio ?? {
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true
+    },
+    video: false
+  };
+  const mediaDevices = opts.mediaDevices ?? navigator.mediaDevices;
+  return mediaDevices.getUserMedia(constraints);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Publisher,
   captureCamera,
+  captureMicrophone,
   captureScreen
 });
 //# sourceMappingURL=index.cjs.map