@unboundcx/video-sdk-client 2.0.0 → 2.0.1

package/managers/QualityMonitor.js

@@ -0,0 +1,845 @@
+// Per-participant adaptive quality monitor. Subscribes to StatsCollector
+// `onStats` cycles (~1 Hz) and runs three independent rolling-window state
+// machines:
+//
+//   outbound  — what we're encoding & sending. Driven by Chrome's
+//               qualityLimitationReason + availableOutgoingBitrate.
+//               Acts by silently capping our outgoing simulcast layers
+//               via RTCRtpSender.setParameters.
+//
+//   network   — our path to the SFU. Driven by RTT and packet loss
+//               (both send + recv sides). Acts by warning the user
+//               and, if severe, capping outbound + suggesting actions.
+//
+//   inbound   — what we're receiving from each remote peer. Driven by
+//               freezeCount/totalFreezesDuration deltas on inbound
+//               video tracks. Acts by asking the server to deliver a
+//               lower simulcast layer for that specific producer.
+//
+// All emissions go through `emit(level, reason, detail)` so the host app
+// can render a single coherent UX (toast, tile badge, etc) without
+// having to understand the underlying signals.
+//
+// Thresholds are public + tunable so the host app or server can override
+// them per-tenant if it ever wants to.
+
+// Reaction-time thresholds. Tuned to feel ~Meet/Zoom-fast on real bad
+// connections while staying noise-resistant against momentary blips.
+// Stats arrive every ~1s so the *Ms numbers translate roughly to
+// "this many seconds of sustained badness before action". See
+// quality-monitor-thresholds.test.js for the user-visible reaction
+// times these collectively produce.
+const DEFAULTS = {
+  // SignalState gates — outer gate per level transition. Tuned to be
+  // patient: a blip that clears within ~20s isn't worth telling the
+  // user about; below that we let the SDK adapt invisibly.
+  warnSustainedMs: 20000,
+  critSustainedMs: 35000,
+  // network thresholds (round trip)
+  rttWarnMs: 300,
+  rttCritMs: 500,
+  // loss thresholds (fraction, 0–1)
+  lossWarnRatio: 0.02,
+  lossCritRatio: 0.05,
+  // Available-outgoing-bitrate floors (Mbps). A throttled uplink often
+  // shows no RTT spike and no loss — Chrome's BWE just collapses and
+  // the encoder backs off cleanly. We treat that as a network problem
+  // because, from the user's POV, it is one. The warn floor is set
+  // below the bandwidth needed for the mid simulcast layer: Chrome
+  // routinely dips toward 1Mbps during BWE probes on healthy networks,
+  // so a higher floor would fire on normal behavior.
+  availMbpsWarn: 0.6,
+  availMbpsCrit: 0.3,
+  // Fraction of the last sample window the encoder spent bandwidth-
+  // constrained (qLdBandwidth delta / sample interval). > warn → severity 1;
+  // > crit → severity 2. Threshold matches encoder constraint check
+  // (0.7) — both want "sustained throughout the window," not blips.
+  encoderBwLimitedWarnRatio: 0.7,
+  encoderBwLimitedCritRatio: 0.9,
+  // encoder pressure inner gates (severity bump 1 / 2). Tuned to be
+  // patient — a single Chrome BWE backoff under simulcast easily
+  // registers a brief constrained window even on healthy networks.
+  encoderConstrainedMs: 6000,
+  encoderSevereConstrainedMs: 20000,
+  // receiver freezes — accumulator delta over the rolling window
+  freezeDurationDegradedMs: 3000,
+  freezeDurationSevereMs: 10000,
+  // auto-disable-camera suggestion — both outbound + network critical
+  // for this long before we surface the prompt. We never actually
+  // disable the camera automatically; the banner offers a one-click
+  // "Disable camera" button and a "Keep on" dismiss.
+  autoDisableCameraMs: 15000,
+  // Time the suggestion banner stays open before auto-dismissing
+  // (matches the "if user is distracted, just clear the prompt and
+  // try again later" UX of Meet).
+  autoDisableGraceMs: 10000,
+  // anti-flap
+  recoveryHoldMs: 15000,
+  toastCooldownMs: 60000,
+};
+
+const LEVELS = ["healthy", "warning", "critical"];
+
+function now() {
+  return Date.now();
+}
+
+// Rolling time-bucketed state machine. We track entries of {ts, severity}
+// and decide the current level by looking at how long the worst severity
+// has been sustained.
+class SignalState {
+  constructor(name, thresholds) {
+    this.name = name;
+    this.thresholds = thresholds;
+    this.level = "healthy";
+    this.levelSince = now();
+    this.recoveryStartedAt = null;
+    this.lastToastAt = 0;
+  }
+
+  // severity = 0 (good) | 1 (bad) | 2 (very bad)
+  observe(severity, sustainedMs) {
+    const t = now();
+    const targetLevel =
+      severity === 2 && sustainedMs >= this.thresholds.critSustainedMs
+        ? "critical"
+        : severity >= 1 && sustainedMs >= this.thresholds.warnSustainedMs
+          ? "warning"
+          : "healthy";
+
+    if (targetLevel === this.level) {
+      this.recoveryStartedAt = null;
+      return null;
+    }
+    // upward transitions go immediately; downward transitions require a
+    // sustained recovery hold to avoid flapping.
+    if (LEVELS.indexOf(targetLevel) > LEVELS.indexOf(this.level)) {
+      this.level = targetLevel;
+      this.levelSince = t;
+      this.recoveryStartedAt = null;
+      return targetLevel;
+    }
+    if (!this.recoveryStartedAt) this.recoveryStartedAt = t;
+    if (t - this.recoveryStartedAt >= this.thresholds.recoveryHoldMs) {
+      this.level = targetLevel;
+      this.levelSince = t;
+      this.recoveryStartedAt = null;
+      return targetLevel;
+    }
+    return null;
+  }
+
+  // Per-LEVEL cooldown: a critical event must be allowed even if a
+  // recent warning was just toasted. We track the last-toast time per
+  // level so a crit transition fires its own toast immediately.
+  shouldToast(level = 'warning') {
+    const t = now();
+    this._lastToastByLevel = this._lastToastByLevel || {};
+    const last = this._lastToastByLevel[level] || 0;
+    if (t - last < this.thresholds.toastCooldownMs) return false;
+    this._lastToastByLevel[level] = t;
+    return true;
+  }
+}
+
+export class QualityMonitor {
+  // host: { statsCollector, mediasoupManager, connectionManager,
+  //         onQualityEvent }
+  //   onQualityEvent(evt): {kind, level, reason, action, detail}
+  //     kinds:
+  //       'outbound'  — our own encoder/network state
+  //       'inbound'   — a specific remote peer's stream into us
+  //       'network'   — our path to SFU
+  //       'autoDisableCamera' — countdown / cancelled / disabled
+  constructor({
+    statsCollector,
+    mediasoupManager,
+    onQualityEvent,
+    getRemotePeerCount,
+    thresholds,
+  }) {
+    this.statsCollector = statsCollector;
+    this.mediasoupManager = mediasoupManager;
+    this.onQualityEvent = onQualityEvent || (() => {});
+    // Solo gate. When this returns 0, we skip evaluation: with no
+    // remote consumers the SFU isn't pulling our media, so encoder /
+    // BWE pressure isn't a real user-facing problem and would
+    // mis-fire toasts/banners on an empty room (e.g. host waiting).
+    this.getRemotePeerCount =
+      typeof getRemotePeerCount === 'function' ? getRemotePeerCount : () => 1;
+    this.thresholds = { ...DEFAULTS, ...(thresholds || {}) };
+
+    this.outbound = new SignalState("outbound", this.thresholds);
+    this.network = new SignalState("network", this.thresholds);
+    // inbound state is per-peer; we lazily create one per producerParticipantId
+    this.inboundByPeer = new Map();
+
+    // for sustained-condition detection
+    this._encoderBadSince = null;
+    this._netBadSince = null;
+    this._allCriticalSince = null;
+    this._autoDisableCountdownTimer = null;
+
+    // running totals from prior samples so we can compute deltas
+    this._lastQLd = { cpu: 0, bandwidth: 0, other: 0 };
+    this._lastSendSampleTs = 0;
+    // Most recent encoder-bandwidth-limited ratio (0–1) computed in
+    // _evalOutbound and consumed by _evalNetwork on the same sample.
+    this._lastEncoderBwLimitedRatio = 0;
+    this._freezeBaselineByPeer = new Map();
+
+    this._capState = { outboundCapped: false, byPeerLow: new Set() };
+
+    // Debug ring buffer — last 100 samples + last 50 emitted events. Used
+    // by the in-app debug modal (Ctrl+Shift+Q) so we can copy the full
+    // monitor state without waiting for a toast.
+    this._debugSamples = [];
+    this._debugEvents = [];
+    this._debugMax = 100;
+    this._lastSampleAt = { send: 0, recv: 0 };
+  }
+
+  start() {
+    if (!this.statsCollector) {
+      this._log(`start :: no statsCollector — monitor inactive`);
+      return;
+    }
+    // Use the SDK-internal callback slot so the host app's
+    // setStatsCallback() doesn't clobber us. (Earlier we used the public
+    // slot, which the meet UI overwrote — silently breaking detection
+    // because the monitor never received another sample.)
+    if (typeof this.statsCollector.addInternalCallback === 'function') {
+      this._unsubscribe = this.statsCollector.addInternalCallback((data) =>
+        this._onSample(data),
+      );
+    } else {
+      // Older SDK without addInternalCallback — fall back to chaining.
+      this._prevCb = this.statsCollector.onStatsCallback;
+      this.statsCollector.setStatsCallback((data) => {
+        try {
+          if (this._prevCb) this._prevCb(data);
+        } catch (_e) {}
+        this._onSample(data);
+      });
+    }
+    this._log(`started :: thresholds ${JSON.stringify(this.thresholds)}`);
+  }
+
+  stop() {
+    if (typeof this._unsubscribe === 'function') {
+      this._unsubscribe();
+      this._unsubscribe = null;
+    } else if (this.statsCollector && this._prevCb !== undefined) {
+      this.statsCollector.setStatsCallback(this._prevCb);
+    }
+    if (this._autoDisableCountdownTimer) {
+      clearTimeout(this._autoDisableCountdownTimer);
+      this._autoDisableCountdownTimer = null;
+    }
+  }
+
+  // ---------- per-sample evaluation ----------
+
+  _onSample(data) {
+    if (!data) return;
+    // Solo gate. With no remote peers, our media isn't being consumed
+    // and encoder/BWE numbers don't reflect a real problem. Reset all
+    // sustained-bad timers so the moment a peer joins we measure
+    // fresh — otherwise the first post-join sample would inherit
+    // accumulated "bad" time from the solo period and could
+    // immediately trip the auto-disable banner.
+    if (this.getRemotePeerCount() === 0) {
+      this._encoderBadSince = null;
+      this._netBadSince = null;
+      this._allCriticalSince = null;
+      if (this._autoDisableCountdownTimer) {
+        clearTimeout(this._autoDisableCountdownTimer);
+        this._autoDisableCountdownTimer = null;
+      }
+      // Hold all three state machines at healthy so any in-flight
+      // pending.autoDisableCamera banner on the UI is cleared via the
+      // 'cancelCountdown' event the next eval would emit. We do this
+      // by forcing the outbound machine back to healthy if it isn't,
+      // which the existing _evalAutoDisableCamera path will pick up
+      // — but since we're skipping eval here, just clear the UI
+      // signal directly through an explicit event if a banner was up.
+      if (this.outbound.level !== 'healthy' || this.network.level !== 'healthy') {
+        this.outbound.level = 'healthy';
+        this.outbound.levelSince = now();
+        this.network.level = 'healthy';
+        this.network.levelSince = now();
+        this._emit({
+          kind: 'autoDisableCamera',
+          level: 'healthy',
+          reason: 'no_remote_peers',
+          action: 'cancelCountdown',
+        });
+      }
+      return;
+    }
+    // Ring-buffer minimal sample for the debug modal. We only keep the
+    // numbers we actually evaluate — full client payload is too big.
+    try {
+      const summary = {
+        ts: now(),
+        dir: data.transportType,
+        rttMs: Number(data?.network?.roundTripTime || 0) * 1000,
+        availMbps: Number(data?.network?.availableOutgoingBitrate || 0) / 1e6,
+        videoLossPct: Number(data?.video?.packetLossPercentage || 0),
+        audioLossPct: Number(data?.audio?.packetLossPercentage || 0),
+        qLdCpu: Number(data?.video?.qLdCpu || 0),
+        qLdBandwidth: Number(data?.video?.qLdBandwidth || 0),
+        fps: Number(data?.video?.framesPerSecond || 0),
+        w: Number(data?.video?.frameWidth || 0),
+        h: Number(data?.video?.frameHeight || 0),
+        connScore: Number(data?.connectionQuality?.finalScore || 0),
+        audioMos: Number(data?.audio?.mos || 0),
+        videoMos: Number(data?.video?.mos || 0),
+      };
+      this._lastSampleAt[data.transportType] = summary.ts;
+      this._debugSamples.push(summary);
+      if (this._debugSamples.length > this._debugMax)
+        this._debugSamples.shift();
+    } catch (_e) {}
+
+    if (data.transportType === "send") {
+      this._evalOutbound(data);
+      this._evalNetwork(data);
+    } else if (data.transportType === "recv") {
+      this._evalInbound(data);
+    }
+    this._evalAutoDisableCamera();
+  }
+
+  // Outbound: encoder pressure.
+  _evalOutbound(data) {
+    const t = now();
+    const v = data.video || {};
+    // qLdBandwidth / qLdCpu are CUMULATIVE seconds. Compare to previous
+    // sample to see if the encoder spent any of the last ~1s constrained.
+    const cpu = Number(v.qLdCpu) || 0;
+    const bw = Number(v.qLdBandwidth) || 0;
+    const dCpu = Math.max(0, cpu - (this._lastQLd.cpu || 0));
+    const dBw = Math.max(0, bw - (this._lastQLd.bandwidth || 0));
+    // Sample-window ratio: how much of the last sample interval the
+    // encoder spent bandwidth-limited. Used by _evalNetwork to detect
+    // throttled uplinks (where RTT/loss stay clean but BWE collapsed).
+    const sampleIntervalSec = this._lastSendSampleTs
+      ? Math.max(0.5, (t - this._lastSendSampleTs) / 1000)
+      : 1;
+    this._lastSendSampleTs = t;
+    this._lastEncoderBwLimitedRatio = Math.min(1, dBw / sampleIntervalSec);
+    this._lastQLd = { cpu, bandwidth: bw, other: Number(v.qLdOther) || 0 };
+
+    // If the encoder spent >70% of the last sample window constrained
+    // on CPU or bandwidth, that sample counts as "bad". A lower
+    // threshold trips on routine BWE probes / momentary backoffs that
+    // are part of normal simulcast operation on healthy networks.
+    const constrainedNow = dCpu + dBw > 0.7;
+    if (constrainedNow) {
+      if (!this._encoderBadSince) this._encoderBadSince = t;
+    } else {
+      this._encoderBadSince = null;
+    }
+    const sustainedMs = this._encoderBadSince ? t - this._encoderBadSince : 0;
+    const severity = constrainedNow
+      ? sustainedMs >= this.thresholds.encoderSevereConstrainedMs
+        ? 2
+        : sustainedMs >= this.thresholds.encoderConstrainedMs
+          ? 1
+          : 0
+      : 0;
+    const transitioned = this.outbound.observe(severity, sustainedMs);
+    if (!transitioned) return;
+
+    if (transitioned === "warning") {
+      // Silent cap to mid-layer. No toast — Meet/Zoom do this invisibly.
+      this._capOutbound("mid", "encoder pressure (sustained)");
+      this._emit({
+        kind: "outbound",
+        level: "warning",
+        reason: dCpu > dBw ? "cpu" : "bandwidth",
+        action: "silentCapMid",
+      });
+    } else if (transitioned === "critical") {
+      this._capOutbound("low", "encoder severely constrained");
+      if (this.outbound.shouldToast("critical")) {
+        this._emit({
+          kind: "outbound",
+          level: "critical",
+          reason: dCpu > dBw ? "cpu" : "bandwidth",
+          action: "capLowAndToast",
+          message:
+            dCpu > dBw
+              ? "Your device is struggling. We have reduced your video quality."
+              : "Your upload bandwidth is low. We have reduced your video quality.",
+        });
+      }
+    } else if (transitioned === "healthy") {
+      this._uncapOutbound("encoder recovered");
+      this._emit({
+        kind: "outbound",
+        level: "healthy",
+        reason: "recovered",
+        action: "uncap",
+      });
+    }
+  }
+
+  // Network: our path-to-SFU health. RTT + send/recv loss.
+  _evalNetwork(data) {
+    const t = now();
+    const rttMs = (Number(data?.network?.roundTripTime) || 0) * 1000;
+    const sendLoss = (Number(data?.audio?.packetLossPercentage) || 0) / 100;
+    const videoLoss = (Number(data?.video?.packetLossPercentage) || 0) / 100;
+    const recvAudioLoss =
+      (Number(data?.recvAvg?.audio?.packetLostPercentage) || 0) / 100;
+    const recvVideoLoss =
+      (Number(data?.recvAvg?.video?.packetLostPercentage) || 0) / 100;
+    const maxLoss = Math.max(sendLoss, videoLoss, recvAudioLoss, recvVideoLoss);
+    // Bandwidth-pressure inputs. A throttled uplink usually shows up here
+    // before it shows up as RTT/loss: availableOutgoingBitrate collapses
+    // and the encoder reports sustained qualityLimitationReason=bandwidth.
+    const availMbps =
+      (Number(data?.network?.availableOutgoingBitrate) || 0) / 1e6;
+    const bwLimitedRatio = this._lastEncoderBwLimitedRatio || 0;
+
+    const rttLossSeverity =
+      rttMs >= this.thresholds.rttCritMs ||
+      maxLoss >= this.thresholds.lossCritRatio
+        ? 2
+        : rttMs >= this.thresholds.rttWarnMs ||
+            maxLoss >= this.thresholds.lossWarnRatio
+          ? 1
+          : 0;
+    // Only count availMbps once we've seen a real reading (>0); some
+    // browsers report 0 transiently at session start.
+    const bandwidthSeverity =
+      availMbps > 0 && availMbps <= this.thresholds.availMbpsCrit
+        ? 2
+        : bwLimitedRatio >= this.thresholds.encoderBwLimitedCritRatio
+          ? 2
+          : availMbps > 0 && availMbps <= this.thresholds.availMbpsWarn
+            ? 1
+            : bwLimitedRatio >= this.thresholds.encoderBwLimitedWarnRatio
+              ? 1
+              : 0;
+    const severity = Math.max(rttLossSeverity, bandwidthSeverity);
+
+    if (severity > 0) {
+      if (!this._netBadSince) this._netBadSince = t;
+    } else {
+      this._netBadSince = null;
+    }
+    const sustainedMs = this._netBadSince ? t - this._netBadSince : 0;
+    const transitioned = this.network.observe(severity, sustainedMs);
+    if (!transitioned) return;
+
+    const reasonFor = (level) => {
+      if (level === 2 || rttLossSeverity >= 1) {
+        if (rttMs >= this.thresholds.rttWarnMs) return "rtt";
+        if (maxLoss >= this.thresholds.lossWarnRatio) return "loss";
+      }
+      return "bandwidth";
+    };
+
+    if (transitioned === "warning") {
+      if (this.network.shouldToast("warning")) {
+        this._emit({
+          kind: "network",
+          level: "warning",
+          reason: reasonFor(severity),
+          action: "toast",
+          message: "Your network is unstable.",
+          detail: {
+            rttMs,
+            maxLossPct: +(maxLoss * 100).toFixed(2),
+            availMbps: +availMbps.toFixed(2),
+            bwLimitedRatio: +bwLimitedRatio.toFixed(2),
+          },
+        });
+      }
+    } else if (transitioned === "critical") {
+      // Path-driven cap. Independent of encoder cap; whichever floor is
+      // lower wins.
+      this._capOutbound("low", "network critical");
+      if (this.network.shouldToast("critical")) {
+        this._emit({
+          kind: "network",
+          level: "critical",
+          reason: reasonFor(severity),
+          action: "capLowAndToast",
+          message: "Poor connection — reducing video quality.",
+          detail: {
+            rttMs,
+            maxLossPct: +(maxLoss * 100).toFixed(2),
+            availMbps: +availMbps.toFixed(2),
+            bwLimitedRatio: +bwLimitedRatio.toFixed(2),
+          },
+        });
+      }
+    } else if (transitioned === "healthy") {
+      this._uncapOutbound("network recovered");
+      this._emit({
+        kind: "network",
+        level: "healthy",
+        reason: "recovered",
+        action: "uncap",
+      });
+    }
+  }
+
+  // Inbound: per-peer freezes on what we receive. The recv stats payload
+  // shape from StatsCollector.js puts per-participant video stats under
+  // `video[participantId]`. We track freeze duration deltas per peer.
+  _evalInbound(data) {
+    const t = now();
+    const perPeerVideo = data?.video || {};
+    for (const [peerId, vs] of Object.entries(perPeerVideo)) {
+      if (!vs || typeof vs !== "object") continue;
+      const freezeMs = (Number(vs.totalFreezesDuration) || 0) * 1000;
+      const baseline = this._freezeBaselineByPeer.get(peerId);
+      // First observation establishes a baseline; we measure window-rate
+      // afterwards.
+      if (!baseline) {
+        this._freezeBaselineByPeer.set(peerId, { freezeMs, ts: t });
+        continue;
+      }
+      const windowMs = t - baseline.ts;
+      if (windowMs < 5000) continue; // need a window
+      const dFreeze = freezeMs - baseline.freezeMs;
+      // Reset baseline so we measure the *next* window, not cumulative
+      this._freezeBaselineByPeer.set(peerId, { freezeMs, ts: t });
+
+      const severity =
+        dFreeze >= this.thresholds.freezeDurationSevereMs
+          ? 2
+          : dFreeze >= this.thresholds.freezeDurationDegradedMs
+            ? 1
+            : 0;
+
+      let state = this.inboundByPeer.get(peerId);
+      if (!state) {
+        state = new SignalState(`inbound:${peerId}`, this.thresholds);
+        this.inboundByPeer.set(peerId, state);
+      }
+      // For inbound we treat any "bad" sample as sustained immediately —
+      // freezes ARE sustained badness by their nature (deltas already are
+      // accumulator deltas over the window).
+      const sustainedMs = severity > 0 ? this.thresholds.critSustainedMs : 0;
+      const transitioned = state.observe(severity, sustainedMs);
+      if (!transitioned) continue;
+
+      if (transitioned === "warning") {
+        // Tile badge only; no toast.
+        this._emit({
+          kind: "inbound",
+          peerId,
+          level: "warning",
+          reason: "freezes",
+          action: "badgePeerTile",
+          detail: { freezeMsInWindow: dFreeze },
+        });
+      } else if (transitioned === "critical") {
+        // Ask server to give us a lower layer of THIS peer. Avoids
+        // affecting our other consumers.
+        this._capInbound(peerId, "low");
+        this._emit({
+          kind: "inbound",
+          peerId,
+          level: "critical",
+          reason: "freezes",
+          action: "requestLowerLayer",
+          detail: { freezeMsInWindow: dFreeze },
+        });
+      } else if (transitioned === "healthy") {
+        this._uncapInbound(peerId);
+        this._emit({
+          kind: "inbound",
+          peerId,
+          level: "healthy",
+          reason: "recovered",
+          action: "uncap",
+        });
+      }
+    }
+  }
+
+  // Auto-disable camera: triggers when ALL three signals have been at
+  // critical for autoDisableCameraMs. Severe sustained problem.
+  //
+  // Behavior: we never auto-disable the camera. We surface a banner
+  // suggestion with a "Disable camera" button (host wires this via
+  // suggestDisableCamera()) and a "Keep on" dismiss. The banner
+  // auto-dismisses after autoDisableGraceMs if the user ignores it,
+  // and re-shows after toastCooldownMs if conditions stay critical.
+  // This matches Meet/Zoom UX where the system *recommends* — it never
+  // surprises the user by killing their video stream.
+  _evalAutoDisableCamera() {
+    // Trigger when BOTH outbound and network are critical. Requiring
+    // two independent signals to agree is what makes this banner
+    // trustworthy: outbound alone fires on routine encoder backoffs,
+    // and network alone fires on transient RTT spikes. The user only
+    // wants to see "disable your camera" when their connection is
+    // genuinely impaired. Network evaluation now includes bandwidth
+    // pressure (availMbps + encoder-bw-limited ratio), so throttled
+    // uplinks correctly drive network → critical alongside outbound.
+    const triggerCritical =
+      this.outbound.level === "critical" &&
+      this.network.level === "critical";
+    const t = now();
+    if (triggerCritical) {
+      if (!this._allCriticalSince) this._allCriticalSince = t;
+    } else {
+      this._allCriticalSince = null;
+      if (this._autoDisableCountdownTimer) {
+        clearTimeout(this._autoDisableCountdownTimer);
+        this._autoDisableCountdownTimer = null;
+        this._emit({
+          kind: "autoDisableCamera",
+          level: "healthy",
+          reason: "recovered",
+          action: "cancelCountdown",
+        });
+      }
+      return;
+    }
+    // Cooldown after a prior banner dismissal (timeout OR user "Keep
+    // on"). Without this, the moment dismissed_timeout fires we'd
+    // immediately re-trip the trigger because _allCriticalSince is
+    // still set, producing a relentless show/dismiss loop while
+    // conditions stay bad.
+    const cooldownLeft = this._autoDisableLastDismissedAt
+      ? this.thresholds.toastCooldownMs -
+        (t - this._autoDisableLastDismissedAt)
+      : 0;
+    if (
+      this._allCriticalSince &&
+      t - this._allCriticalSince >= this.thresholds.autoDisableCameraMs &&
+      !this._autoDisableCountdownTimer &&
+      cooldownLeft <= 0
+    ) {
+      // action: 'countdown' tells the host to show the suggestion
+      // banner. graceMs is how long the banner stays open before
+      // auto-dismissing if the user does nothing.
+      this._emit({
+        kind: "autoDisableCamera",
+        level: "critical",
+        reason: "sustained_severe",
+        action: "countdown",
+        graceMs: this.thresholds.autoDisableGraceMs,
+        message:
+          "Your connection is poor. Disabling your camera may improve audio quality.",
+      });
+      this._autoDisableCountdownTimer = setTimeout(() => {
+        this._autoDisableCountdownTimer = null;
+        // Mark the dismissal time so the cooldown gate above prevents
+        // an immediate re-show on the next sample tick.
+        this._autoDisableLastDismissedAt = now();
+        // Banner times out — emit a dismiss so the host can hide it.
+        // We do NOT emit action='disable' here anymore; the camera
+        // stays on unless the user actively clicks the button.
+        this._emit({
+          kind: "autoDisableCamera",
+          level: "healthy",
+          reason: "dismissed_timeout",
+          action: "cancelCountdown",
+        });
+      }, this.thresholds.autoDisableGraceMs);
+    }
+  }
+
+  // User clicked "Keep camera on" in the toast.
+  cancelAutoDisableCamera() {
+    if (this._autoDisableCountdownTimer) {
+      clearTimeout(this._autoDisableCountdownTimer);
+      this._autoDisableCountdownTimer = null;
+    }
+    // Reset the all-critical timer so we don't immediately re-trigger.
+    this._allCriticalSince = null;
+    // User explicitly dismissed — apply the same cooldown the timeout
+    // path uses so a stuck-bad connection doesn't immediately re-show
+    // the banner the moment the all-critical timer rearms.
+    this._autoDisableLastDismissedAt = now();
+  }
+
+  // ---------- actions ----------
+
+  // Cap the outgoing simulcast to a target top-layer ('mid' | 'low').
+  // Mediasoup encodings carry rids 'l', 'm', 'h'; we disable layers above
+  // the target by setting their active=false via setParameters. The
+  // encoder stops producing them; bandwidth and CPU drop.
+  async _capOutbound(target, reason) {
+    const videoProducer = this._findVideoProducer();
+    if (!videoProducer) return;
+    const sender = videoProducer.rtpSender;
+    if (!sender || typeof sender.getParameters !== "function") return;
+    try {
+      const params = sender.getParameters();
+      if (!params.encodings || params.encodings.length < 2) return;
+      // Keep layers up to and including the target rid; disable above.
+      const keep = target === "mid" ? ["l", "m"] : ["l"];
+      let changed = false;
+      for (const enc of params.encodings) {
+        const wantActive = keep.includes(enc.rid);
+        if (enc.active !== wantActive) {
+          enc.active = wantActive;
+          changed = true;
+        }
+      }
+      if (!changed) return;
+      await sender.setParameters(params);
+      this._capState.outboundCapped = target;
+      this._log(`outbound cap → ${target} :: ${reason}`);
+    } catch (err) {
+      this._log(`outbound cap failed :: ${err?.message || err}`);
+    }
+  }
+
+  async _uncapOutbound(reason) {
+    if (!this._capState.outboundCapped) return;
+    const videoProducer = this._findVideoProducer();
+    if (!videoProducer) return;
+    const sender = videoProducer.rtpSender;
+    if (!sender || typeof sender.getParameters !== "function") return;
+    try {
+      const params = sender.getParameters();
+      let changed = false;
+      for (const enc of params.encodings || []) {
+        if (!enc.active) {
+          enc.active = true;
+          changed = true;
+        }
+      }
+      if (changed) await sender.setParameters(params);
+      this._capState.outboundCapped = false;
+      this._log(`outbound uncap :: ${reason}`);
+    } catch (err) {
+      this._log(`outbound uncap failed :: ${err?.message || err}`);
+    }
+  }
+
+  async _capInbound(peerId, target) {
+    // Asks the server to prefer a lower simulcast layer for this peer's
+    // producer when forwarding to us. Mediasoup consumer API: spatial
+    // layer 0 is lowest. Delegated to MediasoupManager which owns the
+    // consumer map and the signaling client.
+    if (this._capState.byPeerLow.has(peerId)) return;
+    try {
+      const ok = await this._sendSetPreferredLayers(peerId, 0);
+      if (ok) this._capState.byPeerLow.add(peerId);
+      this._log(`inbound cap peer ${peerId} → low :: ${ok}`);
+    } catch (err) {
+      this._log(`inbound cap failed :: ${err?.message || err}`);
+    }
+  }
+
+  async _uncapInbound(peerId) {
+    if (!this._capState.byPeerLow.has(peerId)) return;
+    try {
+      await this._sendSetPreferredLayers(peerId, 2);
+      this._capState.byPeerLow.delete(peerId);
+      this._log(`inbound uncap peer ${peerId}`);
+    } catch (err) {
+      this._log(`inbound uncap failed :: ${err?.message || err}`);
+    }
+  }
+
+  async _sendSetPreferredLayers(peerId, spatialLayer) {
+    if (!this.mediasoupManager) return false;
+    // The MediasoupManager already speaks media.consumer.setPreferredLayers
+    // to the server for layer switching today; we surface a thin wrapper.
+    if (typeof this.mediasoupManager.setPeerPreferredLayer === "function") {
+      return this.mediasoupManager.setPeerPreferredLayer(peerId, spatialLayer);
+    }
+    return false;
+  }
+
+  _findVideoProducer() {
+    if (!this.mediasoupManager) return null;
+    if (typeof this.mediasoupManager.getVideoProducer === "function") {
+      return this.mediasoupManager.getVideoProducer();
+    }
+    return null;
+  }
+
+  _emit(evt) {
+    // Always log into the debug ring, even if onQualityEvent throws.
+    try {
+      this._debugEvents.push({ ts: now(), ...evt });
+      if (this._debugEvents.length > 50) this._debugEvents.shift();
+    } catch (_e) {}
+    try {
+      this.onQualityEvent(evt);
+    } catch (e) {
+      this._log(`onQualityEvent threw :: ${e?.message || e}`);
+    }
+  }
+
+  /**
+   * Public: snapshot for the in-app debug modal. Returns a plain object
+   * safe to JSON-stringify and copy to clipboard. No PII; just monitor
+   * state, recent samples, and emitted events.
+   */
+  getDebugSnapshot() {
+    return {
+      generatedAt: new Date().toISOString(),
+      thresholds: this.thresholds,
+      state: {
+        outbound: {
+          level: this.outbound.level,
+          levelSinceMs: now() - this.outbound.levelSince,
+          recoveryStartedAt: this.outbound.recoveryStartedAt,
+        },
+        network: {
+          level: this.network.level,
+          levelSinceMs: now() - this.network.levelSince,
+          recoveryStartedAt: this.network.recoveryStartedAt,
+        },
+        inboundPeers: [...this.inboundByPeer.entries()].map(([pid, st]) => ({
+          peerId: pid,
+          level: st.level,
+          levelSinceMs: now() - st.levelSince,
+        })),
+        encoderBadSinceMs: this._encoderBadSince
+          ? now() - this._encoderBadSince
+          : 0,
+        netBadSinceMs: this._netBadSince ? now() - this._netBadSince : 0,
+        allCriticalSinceMs: this._allCriticalSince
+          ? now() - this._allCriticalSince
+          : 0,
+        autoDisableCameraScheduled: !!this._autoDisableCountdownTimer,
+        // Solo gate input. If this is 0, _onSample short-circuits and
+        // no evaluation runs — a non-zero value while you believe you
+        // are alone in the meeting means the gate is reading a phantom
+        // consumer (e.g. our own producer counted as a consumer, or a
+        // stale entry from a previous session).
+        remotePeerCount: (() => {
+          try { return this.getRemotePeerCount(); } catch { return null; }
+        })(),
+        outboundCapped: this._capState.outboundCapped,
+        inboundCappedPeers: [...this._capState.byPeerLow],
+        lastSendSampleAgeMs: this._lastSampleAt.send
+          ? now() - this._lastSampleAt.send
+          : null,
+        lastRecvSampleAgeMs: this._lastSampleAt.recv
+          ? now() - this._lastSampleAt.recv
+          : null,
+      },
+      // Last 10 samples per direction (chronological)
+      recentSendSamples: this._debugSamples
+        .filter((s) => s.dir === "send")
+        .slice(-10),
+      recentRecvSamples: this._debugSamples
+        .filter((s) => s.dir === "recv")
+        .slice(-10),
+      recentEvents: this._debugEvents.slice(-25),
+    };
+  }
+
+  _log(msg) {
+    if (typeof console !== "undefined") {
+      console.log(`QualityMonitor :: ${msg}`);
+    }
+  }
+}