@furious.luke/argus-js 0.5.5 → 0.5.6

package/dist/index.d.cts

@@ -131,6 +131,19 @@ interface PublisherCallbacks {
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
     onSpeechTrack?: (track: MediaStreamTrack, streams: readonly MediaStream[]) => void;
+    /**
+     * Called for every periodic connection-stats sample while connected — the raw
+     * feed behind {@link onConnectionQualityChange}. Fires at
+     * {@link PublisherOptions.connectionStatsIntervalMs}.
+     */
+    onConnectionStats?: (sample: ConnectionStatsSample) => void;
+    /**
+     * Called when the derived connection-quality level changes (including the
+     * first assessment after connecting). Downgrades are debounced; upgrades fire
+     * immediately. Use this to react to a degrading network — e.g. warn the user
+     * or drop a secondary track.
+     */
+    onConnectionQualityChange?: (quality: ConnectionQuality) => void;
 }
 interface AssistantTextEvent {
     utteranceId: string;
@@ -144,6 +157,86 @@ interface UserTextResultEvent {
     accepted: boolean;
     reason?: string;
 }
+/**
+ * A coarse assessment of the uplink to the media server, derived from periodic
+ * WebRTC stats. Ordered worst-last by severity: `"good"` is a healthy
+ * connection, `"critical"` is barely usable.
+ */
+type ConnectionQualityLevel = "good" | "fair" | "poor" | "critical";
+/**
+ * One periodic sample of the outbound connection's health, taken from
+ * `RTCPeerConnection.getStats()`. Packet loss and send bitrate are windowed over
+ * the interval since the previous sample (the first sample covers the session so
+ * far); the rest are point-in-time readings. A field is `null` when the browser
+ * did not report the underlying stat for this sample.
+ */
+interface ConnectionStatsSample {
+    /** Monotonic clock timestamp (ms) when the sample was taken. */
+    timestamp: number;
+    /**
+     * Fraction of outbound RTP packets lost, in `0..1` — the primary quality
+     * signal. A traffic-weighted mean of each stream's loss fraction: a stream uses
+     * its remote `fractionLost` (its loss ratio over the last RTCP report interval)
+     * when present, otherwise its windowed
+     * `Δpacketslost / Δ(packetsSent - retransmittedPacketsSent)`. Both kinds of
+     * stream are combined, so a lossy stream is never dropped for lacking
+     * `fractionLost`.
+     */
+    lossRatio: number;
+    /** Round-trip time in milliseconds, or `null` if unknown. */
+    rttMs: number | null;
+    /** Inter-arrival jitter in milliseconds, or `null` if unknown. */
+    jitterMs: number | null;
+    /** ICE-estimated available outgoing bitrate in bits/sec, or `null` if unknown. */
+    availableOutgoingBitrate: number | null;
+    /** Actual send bitrate over the interval in bits/sec, or `null` if unknown. */
+    sendBitrate: number | null;
+    /**
+     * Why the encoder is limiting quality: `"none"`, `"cpu"`, `"bandwidth"`, or
+     * `"other"`. `null` when no video is being sent. `"bandwidth"` is treated as a
+     * degradation signal by the default classifier.
+     */
+    qualityLimitationReason: string | null;
+    /** Cumulative NACKs received on outbound media, or `null` if unknown. */
+    nackCount: number | null;
+    /** Cumulative PLIs received on outbound media, or `null` if unknown. */
+    pliCount: number | null;
+}
+/**
+ * A committed connection-quality assessment, delivered to
+ * {@link PublisherCallbacks.onConnectionQualityChange} whenever the level
+ * changes. `sample` is the reading that triggered the transition.
+ */
+interface ConnectionQuality {
+    level: ConnectionQualityLevel;
+    sample: ConnectionStatsSample;
+}
+/**
+ * Thresholds mapping a {@link ConnectionStatsSample} to a
+ * {@link ConnectionQualityLevel}. Packet loss is the primary axis; RTT and
+ * jitter can only push the assessment to a worse level, never a better one, and
+ * a `"bandwidth"` encoder limitation forces at least `"fair"`. Any subset may be
+ * overridden via {@link PublisherOptions.connectionQualityThresholds}; the rest
+ * keep their defaults.
+ */
+interface ConnectionQualityThresholds {
+    /** Loss ratio (`0..1`) at or above which quality is at least `"fair"`. Default `0.02`. */
+    fairLossRatio: number;
+    /** Loss ratio at or above which quality is at least `"poor"`. Default `0.05`. */
+    poorLossRatio: number;
+    /** Loss ratio at or above which quality is `"critical"`. Default `0.12`. */
+    criticalLossRatio: number;
+    /** RTT (ms) at or above which quality is at least `"fair"`. Default `300`. */
+    fairRttMs: number;
+    /** RTT (ms) at or above which quality is at least `"poor"`. Default `600`. */
+    poorRttMs: number;
+    /** RTT (ms) at or above which quality is `"critical"`. Default `1000`. */
+    criticalRttMs: number;
+    /** Jitter (ms) at or above which quality is at least `"fair"`. Default `50`. */
+    fairJitterMs: number;
+    /** Jitter (ms) at or above which quality is at least `"poor"`. Default `150`. */
+    poorJitterMs: number;
+}
 type PublisherRecoveryState = "recovering" | "recovered" | "failed";
 type PublisherRecoveryAction = "sender_restart" | "ice_restart";
 type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
@@ -232,6 +325,24 @@ interface PublisherOptions {
     preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
+    /**
+     * How often, in milliseconds, to poll `RTCPeerConnection.getStats()` for
+     * connection-quality assessment once connected. Defaults to 2000. Set to 0 to
+     * disable stats polling entirely — neither {@link PublisherCallbacks.onConnectionStats}
+     * nor {@link PublisherCallbacks.onConnectionQualityChange} will fire.
+     */
+    connectionStatsIntervalMs?: number;
+    /**
+     * Overrides for the connection-quality classification thresholds. Any omitted
+     * field keeps its default. See {@link ConnectionQualityThresholds}.
+     */
+    connectionQualityThresholds?: Partial<ConnectionQualityThresholds>;
+    /**
+     * Number of consecutive worse-than-current samples required before a quality
+     * downgrade is committed, damping transient blips. Improvements are reported
+     * on the first better sample. Defaults to 2; values below 1 are treated as 1.
+     */
+    connectionQualityDebounceSamples?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -277,6 +388,11 @@ declare class Publisher {
     private gatewayURL;
     private lastReportedICEPath;
     private watchedICETransports;
+    private connectionStatsTimer;
+    private statsSampleInFlight;
+    private lastStatsSample;
+    private currentQualityLevel;
+    private qualityDowngradeStreak;
     private stopped;
     private lifecycleGeneration;
     private runAbort;
@@ -459,6 +575,13 @@ declare class Publisher {
     private releaseLocalCandidateBatch;
     private applyAnswered;
     private watchSelectedICEPairChanges;
+    private startConnectionStatsLoop;
+    private stopConnectionStatsLoop;
+    private sampleConnectionQuality;
+    private buildStatsSample;
+    private resolveQualityThresholds;
+    private classifyQuality;
+    private updateConnectionQuality;
     private reportSelectedICEPath;
     private completeMediaRecovery;
     private failMediaRecovery;
@@ -688,4 +811,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };
+export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };

package/dist/index.d.ts

@@ -131,6 +131,19 @@ interface PublisherCallbacks {
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
     onSpeechTrack?: (track: MediaStreamTrack, streams: readonly MediaStream[]) => void;
+    /**
+     * Called for every periodic connection-stats sample while connected — the raw
+     * feed behind {@link onConnectionQualityChange}. Fires at
+     * {@link PublisherOptions.connectionStatsIntervalMs}.
+     */
+    onConnectionStats?: (sample: ConnectionStatsSample) => void;
+    /**
+     * Called when the derived connection-quality level changes (including the
+     * first assessment after connecting). Downgrades are debounced; upgrades fire
+     * immediately. Use this to react to a degrading network — e.g. warn the user
+     * or drop a secondary track.
+     */
+    onConnectionQualityChange?: (quality: ConnectionQuality) => void;
 }
 interface AssistantTextEvent {
     utteranceId: string;
@@ -144,6 +157,86 @@ interface UserTextResultEvent {
     accepted: boolean;
     reason?: string;
 }
+/**
+ * A coarse assessment of the uplink to the media server, derived from periodic
+ * WebRTC stats. Ordered worst-last by severity: `"good"` is a healthy
+ * connection, `"critical"` is barely usable.
+ */
+type ConnectionQualityLevel = "good" | "fair" | "poor" | "critical";
+/**
+ * One periodic sample of the outbound connection's health, taken from
+ * `RTCPeerConnection.getStats()`. Packet loss and send bitrate are windowed over
+ * the interval since the previous sample (the first sample covers the session so
+ * far); the rest are point-in-time readings. A field is `null` when the browser
+ * did not report the underlying stat for this sample.
+ */
+interface ConnectionStatsSample {
+    /** Monotonic clock timestamp (ms) when the sample was taken. */
+    timestamp: number;
+    /**
+     * Fraction of outbound RTP packets lost, in `0..1` — the primary quality
+     * signal. A traffic-weighted mean of each stream's loss fraction: a stream uses
+     * its remote `fractionLost` (its loss ratio over the last RTCP report interval)
+     * when present, otherwise its windowed
+     * `Δpacketslost / Δ(packetsSent - retransmittedPacketsSent)`. Both kinds of
+     * stream are combined, so a lossy stream is never dropped for lacking
+     * `fractionLost`.
+     */
+    lossRatio: number;
+    /** Round-trip time in milliseconds, or `null` if unknown. */
+    rttMs: number | null;
+    /** Inter-arrival jitter in milliseconds, or `null` if unknown. */
+    jitterMs: number | null;
+    /** ICE-estimated available outgoing bitrate in bits/sec, or `null` if unknown. */
+    availableOutgoingBitrate: number | null;
+    /** Actual send bitrate over the interval in bits/sec, or `null` if unknown. */
+    sendBitrate: number | null;
+    /**
+     * Why the encoder is limiting quality: `"none"`, `"cpu"`, `"bandwidth"`, or
+     * `"other"`. `null` when no video is being sent. `"bandwidth"` is treated as a
+     * degradation signal by the default classifier.
+     */
+    qualityLimitationReason: string | null;
+    /** Cumulative NACKs received on outbound media, or `null` if unknown. */
+    nackCount: number | null;
+    /** Cumulative PLIs received on outbound media, or `null` if unknown. */
+    pliCount: number | null;
+}
+/**
+ * A committed connection-quality assessment, delivered to
+ * {@link PublisherCallbacks.onConnectionQualityChange} whenever the level
+ * changes. `sample` is the reading that triggered the transition.
+ */
+interface ConnectionQuality {
+    level: ConnectionQualityLevel;
+    sample: ConnectionStatsSample;
+}
+/**
+ * Thresholds mapping a {@link ConnectionStatsSample} to a
+ * {@link ConnectionQualityLevel}. Packet loss is the primary axis; RTT and
+ * jitter can only push the assessment to a worse level, never a better one, and
+ * a `"bandwidth"` encoder limitation forces at least `"fair"`. Any subset may be
+ * overridden via {@link PublisherOptions.connectionQualityThresholds}; the rest
+ * keep their defaults.
+ */
+interface ConnectionQualityThresholds {
+    /** Loss ratio (`0..1`) at or above which quality is at least `"fair"`. Default `0.02`. */
+    fairLossRatio: number;
+    /** Loss ratio at or above which quality is at least `"poor"`. Default `0.05`. */
+    poorLossRatio: number;
+    /** Loss ratio at or above which quality is `"critical"`. Default `0.12`. */
+    criticalLossRatio: number;
+    /** RTT (ms) at or above which quality is at least `"fair"`. Default `300`. */
+    fairRttMs: number;
+    /** RTT (ms) at or above which quality is at least `"poor"`. Default `600`. */
+    poorRttMs: number;
+    /** RTT (ms) at or above which quality is `"critical"`. Default `1000`. */
+    criticalRttMs: number;
+    /** Jitter (ms) at or above which quality is at least `"fair"`. Default `50`. */
+    fairJitterMs: number;
+    /** Jitter (ms) at or above which quality is at least `"poor"`. Default `150`. */
+    poorJitterMs: number;
+}
 type PublisherRecoveryState = "recovering" | "recovered" | "failed";
 type PublisherRecoveryAction = "sender_restart" | "ice_restart";
 type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
@@ -232,6 +325,24 @@ interface PublisherOptions {
     preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
+    /**
+     * How often, in milliseconds, to poll `RTCPeerConnection.getStats()` for
+     * connection-quality assessment once connected. Defaults to 2000. Set to 0 to
+     * disable stats polling entirely — neither {@link PublisherCallbacks.onConnectionStats}
+     * nor {@link PublisherCallbacks.onConnectionQualityChange} will fire.
+     */
+    connectionStatsIntervalMs?: number;
+    /**
+     * Overrides for the connection-quality classification thresholds. Any omitted
+     * field keeps its default. See {@link ConnectionQualityThresholds}.
+     */
+    connectionQualityThresholds?: Partial<ConnectionQualityThresholds>;
+    /**
+     * Number of consecutive worse-than-current samples required before a quality
+     * downgrade is committed, damping transient blips. Improvements are reported
+     * on the first better sample. Defaults to 2; values below 1 are treated as 1.
+     */
+    connectionQualityDebounceSamples?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -277,6 +388,11 @@ declare class Publisher {
     private gatewayURL;
     private lastReportedICEPath;
     private watchedICETransports;
+    private connectionStatsTimer;
+    private statsSampleInFlight;
+    private lastStatsSample;
+    private currentQualityLevel;
+    private qualityDowngradeStreak;
     private stopped;
     private lifecycleGeneration;
     private runAbort;
@@ -459,6 +575,13 @@ declare class Publisher {
     private releaseLocalCandidateBatch;
     private applyAnswered;
     private watchSelectedICEPairChanges;
+    private startConnectionStatsLoop;
+    private stopConnectionStatsLoop;
+    private sampleConnectionQuality;
+    private buildStatsSample;
+    private resolveQualityThresholds;
+    private classifyQuality;
+    private updateConnectionQuality;
     private reportSelectedICEPath;
     private completeMediaRecovery;
     private failMediaRecovery;
@@ -688,4 +811,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };
+export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };

package/dist/index.js

@@ -65,6 +65,28 @@ function selectGatewayTURNURLs(advertised, policy = "all") {
   }
   return selected;
 }
+var qualityLevels = ["good", "fair", "poor", "critical"];
+function qualitySeverity(level) {
+  return qualityLevels.indexOf(level);
+}
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+var limitationSeverity = { none: 0, other: 1, cpu: 2, bandwidth: 3 };
+function worseLimitation(current, next) {
+  if (current === null) return next;
+  return (limitationSeverity[next] ?? 1) > (limitationSeverity[current] ?? 1) ? next : current;
+}
+function findNominatedCandidatePair(stats) {
+  let found;
+  stats.forEach((report) => {
+    const value = report;
+    if (!found && value.type === "candidate-pair" && value.state === "succeeded" && value.nominated === true) {
+      found = value;
+    }
+  });
+  return found;
+}
 var defaultSignalingReconnectTimeoutMs = 2e4;
 var defaultGatewayHandshakeTimeoutMs = 2e4;
 var defaultPeerConnectionTimeoutMs = 3e4;
@@ -85,6 +107,18 @@ var negotiationReconnectGraceMs = 5e3;
 var minimumIntentionalTrackEndRetentionMs = 35e3;
 var maxUserTextBytes = 4 * 1024;
 var maxRetainedICECandidates = 64;
+var defaultConnectionStatsIntervalMs = 2e3;
+var defaultConnectionQualityDebounceSamples = 2;
+var defaultConnectionQualityThresholds = {
+  fairLossRatio: 0.02,
+  poorLossRatio: 0.05,
+  criticalLossRatio: 0.12,
+  fairRttMs: 300,
+  poorRttMs: 600,
+  criticalRttMs: 1e3,
+  fairJitterMs: 50,
+  poorJitterMs: 150
+};
 var ReportedPublisherError = class extends Error {
   constructor(message, fatal = false) {
     super(message);
@@ -127,6 +161,17 @@ var Publisher = class {
   gatewayURL = null;
   lastReportedICEPath = null;
   watchedICETransports = /* @__PURE__ */ new WeakSet();
+  // Periodic getStats() polling for connection-quality assessment. The timer runs
+  // only while connected; lastStatsSample anchors the windowed loss/bitrate deltas
+  // (loss is tracked per outbound SSRC so it can be paired to the remote's report),
+  // and currentQualityLevel/qualityDowngradeStreak drive the debounced classifier.
+  connectionStatsTimer = null;
+  // Guards against overlapping getStats() calls: if one outlives the interval,
+  // ticks are skipped until it resolves so samples never complete out of order.
+  statsSampleInFlight = false;
+  lastStatsSample = null;
+  currentQualityLevel = null;
+  qualityDowngradeStreak = 0;
   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.
@@ -339,10 +384,13 @@ var Publisher = class {
         if (state === "connected") {
           this.clearPeerConnectionTimeout();
           void this.reportSelectedICEPath(pc);
+          this.startConnectionStatsLoop(generation, pc);
           this.opts.callbacks?.onConnected?.();
         } else if (state === "failed") {
           this.clearPeerConnectionTimeout();
           this.terminateWithError(new Error("WebRTC connection failed"), true, generation);
+        } else {
+          this.stopConnectionStatsLoop();
         }
       };
       if (initialTrack) {
@@ -477,6 +525,7 @@ var Publisher = class {
     this.runAbort?.abort();
     this.runAbort = null;
     this.clearPeerConnectionTimeout();
+    this.stopConnectionStatsLoop();
     this.stopped = true;
     this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
@@ -965,6 +1014,7 @@ var Publisher = class {
     this.runAbort?.abort();
     this.runAbort = null;
     this.clearPeerConnectionTimeout();
+    this.stopConnectionStatsLoop();
     this.stopped = true;
     this.cancelAllMediaRecovery();
     this.reconnectGeneration++;
@@ -1435,6 +1485,249 @@ var Publisher = class {
     } catch {
     }
   }
+  // startConnectionStatsLoop begins periodic getStats() sampling once the peer
+  // connection is connected. It is a no-op when polling is disabled or no
+  // consumer is listening, and it re-baselines on each call so a reconnect after
+  // an ICE restart starts a fresh quality assessment.
+  startConnectionStatsLoop(generation, pc) {
+    const intervalMs = Math.max(
+      0,
+      this.opts.connectionStatsIntervalMs ?? defaultConnectionStatsIntervalMs
+    );
+    const listening = !!this.opts.callbacks?.onConnectionStats || !!this.opts.callbacks?.onConnectionQualityChange;
+    if (intervalMs === 0 || !listening) return;
+    this.stopConnectionStatsLoop();
+    const timer = setInterval(() => {
+      if (this.connectionStatsTimer !== timer) return;
+      if (!this.isActiveRun(generation, pc)) {
+        this.stopConnectionStatsLoop();
+        return;
+      }
+      if (this.statsSampleInFlight) return;
+      this.statsSampleInFlight = true;
+      void this.sampleConnectionQuality(generation, pc, timer);
+    }, intervalMs);
+    this.connectionStatsTimer = timer;
+  }
+  stopConnectionStatsLoop() {
+    if (this.connectionStatsTimer !== null) clearInterval(this.connectionStatsTimer);
+    this.connectionStatsTimer = null;
+    this.statsSampleInFlight = false;
+    this.lastStatsSample = null;
+    this.currentQualityLevel = null;
+    this.qualityDowngradeStreak = 0;
+  }
+  async sampleConnectionQuality(generation, pc, timer) {
+    let stats = null;
+    try {
+      stats = await pc.getStats();
+    } catch {
+    }
+    if (this.connectionStatsTimer !== timer) return;
+    this.statsSampleInFlight = false;
+    if (!stats || !this.isActiveRun(generation, pc) || pc.connectionState !== "connected") {
+      return;
+    }
+    const sample = this.buildStatsSample(stats);
+    this.opts.callbacks?.onConnectionStats?.(sample);
+    if (this.connectionStatsTimer !== timer || !this.isActiveRun(generation, pc) || pc.connectionState !== "connected") {
+      return;
+    }
+    this.updateConnectionQuality(sample);
+  }
+  // buildStatsSample derives one sample from a getStats() report. Loss is a mean of
+  // per-stream loss fractions weighted by each stream's packets sent this window, so
+  // every stream carrying traffic contributes. A stream uses its remote fractionLost
+  // when present — the remote's loss ratio over its RR interval, self-aligned and
+  // excluding retransmissions (which ride a separate SSRC); dividing the remote's
+  // Δ(packetsLost) by the local Δ(packetsSent) would instead misalign an RTCP-timed
+  // numerator with a continuously-updated denominator — and otherwise falls back to
+  // its own windowed Δ(packetsLost) / Δ(distinct media packets sent), a denominator
+  // that excludes retransmissions (packetsSent - retransmittedPacketsSent). Mixing the
+  // two per stream keeps a lossy stream from being dropped when a sibling has fractionLost.
+  //
+  // Deltas are taken only over outbound stats-object ids present in BOTH this and the
+  // previous sample. A track replace/unpublish (or a recycled SSRC) deletes the old
+  // stats object and creates a new one with a new id; counting a vanished stream's
+  // missing tail, or a fresh object's cumulative total as an interval delta, would
+  // corrupt loss. Excluding the symmetric difference baselines new objects (they count
+  // from their next sample) and drops departed ones, so continuous streams still measure
+  // loss even when an SSRC number is reused across distinct stats objects.
+  buildStatsSample(stats) {
+    const timestamp = nowMs();
+    let nackCount = 0;
+    let pliCount = 0;
+    let haveOutbound = false;
+    let haveOutboundVideo = false;
+    let rttSeconds = null;
+    let jitterSeconds = null;
+    let limitationReason = null;
+    let selectedPairID;
+    let transportBytes = null;
+    const streams = /* @__PURE__ */ new Map();
+    const ssrcToId = /* @__PURE__ */ new Map();
+    stats.forEach((report) => {
+      const value = report;
+      switch (value.type) {
+        case "outbound-rtp": {
+          haveOutbound = true;
+          if (value.kind === "video") haveOutboundVideo = true;
+          const ssrc = typeof value.ssrc === "number" ? value.ssrc : NaN;
+          const sent = typeof value.packetsSent === "number" ? value.packetsSent : 0;
+          const retransmitted = typeof value.retransmittedPacketsSent === "number" ? value.retransmittedPacketsSent : 0;
+          const bytesSent = typeof value.bytesSent === "number" ? value.bytesSent : 0;
+          if (typeof value.nackCount === "number") nackCount += value.nackCount;
+          if (typeof value.pliCount === "number") pliCount += value.pliCount;
+          if (typeof value.qualityLimitationReason === "string") {
+            limitationReason = worseLimitation(limitationReason, value.qualityLimitationReason);
+          }
+          if (typeof value.id === "string") {
+            const expected = Math.max(0, sent - retransmitted);
+            streams.set(value.id, { expected, lost: null, fractionLost: null, bytesSent });
+            if (!Number.isNaN(ssrc)) ssrcToId.set(ssrc, value.id);
+          }
+          break;
+        }
+        case "remote-inbound-rtp": {
+          if (typeof value.roundTripTime === "number") {
+            rttSeconds = Math.max(rttSeconds ?? 0, value.roundTripTime);
+          }
+          if (typeof value.jitter === "number") {
+            jitterSeconds = Math.max(jitterSeconds ?? 0, value.jitter);
+          }
+          break;
+        }
+        case "transport": {
+          if (typeof value.selectedCandidatePairId === "string") {
+            selectedPairID = value.selectedCandidatePairId;
+          }
+          if (typeof value.bytesSent === "number") {
+            transportBytes = (transportBytes ?? 0) + value.bytesSent;
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    });
+    stats.forEach((report) => {
+      const value = report;
+      if (value.type !== "remote-inbound-rtp") return;
+      const outboundId = typeof value.localId === "string" && streams.has(value.localId) ? value.localId : typeof value.ssrc === "number" ? ssrcToId.get(value.ssrc) : void 0;
+      if (outboundId === void 0) return;
+      const stream = streams.get(outboundId);
+      if (!stream) return;
+      const lost = typeof value.packetsLost === "number" ? value.packetsLost : 0;
+      stream.lost = (stream.lost ?? 0) + lost;
+      if (typeof value.fractionLost === "number" && Number.isFinite(value.fractionLost)) {
+        stream.fractionLost = Math.min(1, Math.max(0, value.fractionLost));
+      }
+    });
+    const pair = (selectedPairID ? stats.get(selectedPairID) : void 0) ?? findNominatedCandidatePair(stats);
+    const availableOutgoingBitrate = pair && typeof pair.availableOutgoingBitrate === "number" ? pair.availableOutgoingBitrate : null;
+    if (rttSeconds === null && pair && typeof pair.currentRoundTripTime === "number") {
+      rttSeconds = pair.currentRoundTripTime;
+    }
+    const prev = this.lastStatsSample;
+    let weightedFractionSum = 0;
+    let weightSum = 0;
+    let intersectionBytesDelta = 0;
+    let hadStreamOverlap = false;
+    streams.forEach((current, id) => {
+      const before = prev?.streams.get(id);
+      if (!before) return;
+      hadStreamOverlap = true;
+      intersectionBytesDelta += Math.max(0, current.bytesSent - before.bytesSent);
+      const deltaExpected = Math.max(0, current.expected - before.expected);
+      if (deltaExpected <= 0) return;
+      let fraction = null;
+      if (current.fractionLost !== null) {
+        fraction = current.fractionLost;
+      } else if (current.lost !== null && before.lost !== null) {
+        fraction = Math.min(1, Math.max(0, current.lost - before.lost) / deltaExpected);
+      }
+      if (fraction === null) return;
+      weightedFractionSum += fraction * deltaExpected;
+      weightSum += deltaExpected;
+    });
+    const deltaSeconds = prev ? (timestamp - prev.timestamp) / 1e3 : 0;
+    this.lastStatsSample = { timestamp, transportBytes, streams };
+    const lossRatio = weightSum > 0 ? Math.min(1, weightedFractionSum / weightSum) : 0;
+    let sendBitrate = null;
+    if (prev && deltaSeconds > 0) {
+      if (transportBytes !== null && prev.transportBytes !== null) {
+        sendBitrate = Math.max(0, transportBytes - prev.transportBytes) * 8 / deltaSeconds;
+      } else if (hadStreamOverlap) {
+        sendBitrate = intersectionBytesDelta * 8 / deltaSeconds;
+      }
+    }
+    return {
+      timestamp,
+      lossRatio,
+      rttMs: rttSeconds !== null ? rttSeconds * 1e3 : null,
+      jitterMs: jitterSeconds !== null ? jitterSeconds * 1e3 : null,
+      availableOutgoingBitrate,
+      sendBitrate,
+      qualityLimitationReason: haveOutboundVideo ? limitationReason ?? "none" : null,
+      nackCount: haveOutbound ? nackCount : null,
+      pliCount: haveOutbound ? pliCount : null
+    };
+  }
+  resolveQualityThresholds() {
+    return { ...defaultConnectionQualityThresholds, ...this.opts.connectionQualityThresholds ?? {} };
+  }
+  // classifyQuality maps a sample to a level. Loss is the primary axis; RTT,
+  // jitter, and a bandwidth-limited encoder can only raise severity.
+  classifyQuality(sample) {
+    const t = this.resolveQualityThresholds();
+    let severity = 0;
+    if (sample.lossRatio >= t.criticalLossRatio) severity = Math.max(severity, 3);
+    else if (sample.lossRatio >= t.poorLossRatio) severity = Math.max(severity, 2);
+    else if (sample.lossRatio >= t.fairLossRatio) severity = Math.max(severity, 1);
+    if (sample.rttMs !== null) {
+      if (sample.rttMs >= t.criticalRttMs) severity = Math.max(severity, 3);
+      else if (sample.rttMs >= t.poorRttMs) severity = Math.max(severity, 2);
+      else if (sample.rttMs >= t.fairRttMs) severity = Math.max(severity, 1);
+    }
+    if (sample.jitterMs !== null) {
+      if (sample.jitterMs >= t.poorJitterMs) severity = Math.max(severity, 2);
+      else if (sample.jitterMs >= t.fairJitterMs) severity = Math.max(severity, 1);
+    }
+    if (sample.qualityLimitationReason === "bandwidth") severity = Math.max(severity, 1);
+    return qualityLevels[severity];
+  }
+  // updateConnectionQuality commits level transitions with hysteresis: an
+  // improvement is reported on the first better sample, while a degradation must
+  // persist for connectionQualityDebounceSamples consecutive samples to commit,
+  // so a single blip does not flap the reported level.
+  updateConnectionQuality(sample) {
+    const candidate = this.classifyQuality(sample);
+    const current = this.currentQualityLevel;
+    if (current === null || candidate === current) {
+      this.qualityDowngradeStreak = 0;
+      if (candidate !== current) {
+        this.currentQualityLevel = candidate;
+        this.opts.callbacks?.onConnectionQualityChange?.({ level: candidate, sample });
+      }
+      return;
+    }
+    if (qualitySeverity(candidate) < qualitySeverity(current)) {
+      this.qualityDowngradeStreak = 0;
+      this.currentQualityLevel = candidate;
+      this.opts.callbacks?.onConnectionQualityChange?.({ level: candidate, sample });
+      return;
+    }
+    const needed = Math.max(
+      1,
+      this.opts.connectionQualityDebounceSamples ?? defaultConnectionQualityDebounceSamples
+    );
+    this.qualityDowngradeStreak += 1;
+    if (this.qualityDowngradeStreak >= needed) {
+      this.qualityDowngradeStreak = 0;
+      this.currentQualityLevel = candidate;
+      this.opts.callbacks?.onConnectionQualityChange?.({ level: candidate, sample });
+    }
+  }
   async reportSelectedICEPath(pc) {
     if (this.pc !== pc || this.stopped) return;
     let stats;