@rapidmx/meet-plugin 0.14.1 → 0.16.0

package/dist/apps/shared/collab/whiteboardRender.js

@@ -0,0 +1,268 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Draws the whiteboard's elements on a 2D canvas, in board units (`protocol.ts`'s `BOARD_WIDTH` x `BOARD_HEIGHT`)
+ * scaled to the canvas. Each pen has its own look:
+ *
+ * - **ballpoint** - a thin, even, opaque line.
+ * - **sharpie** - a bolder opaque line with round ends.
+ * - **marker** - a broad, square-tipped, translucent stroke laid down in `multiply`, so it highlights what is under
+ * it instead of covering it, and doesn't darken where it overlaps itself (the stroke is one path).
+ * - **crayon** - a waxy translucent base speckled with grain, like wax catching on paper.
+ * - **pencil** - a coloring pencil: several fine, slightly offset, faint passes that build up a grainy line.
+ *
+ * The grain of a crayon or pencil comes from a random generator seeded by the element's id, so every participant's
+ * board draws the very same texture for the same stroke - it is not re-randomized per screen or per redraw.
+ */
+import { BOARD_HEIGHT, BOARD_WIDTH } from "./protocol.js";
+/** The board's paper color. */
+export const BOARD_BACKGROUND = "#ffffff";
+/** The font stack stamps are drawn in - each platform's color emoji font first. */
+export const STAMP_FONT_FAMILY = '"Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif';
+/** A small, fast, seedable PRNG (mulberry32) - returns numbers in [0, 1). */
+export function seededRandom(seed) {
+    let state = 2166136261;
+    for (let i = 0; i < seed.length; i++) {
+        state = Math.imul(state ^ seed.charCodeAt(i), 16777619);
+    }
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Clears the canvas to paper and draws `elements` in order, `scale` canvas pixels per board unit. */
+export function renderBoard(ctx, elements, scale) {
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalAlpha = 1;
+    ctx.globalCompositeOperation = "source-over";
+    ctx.fillStyle = BOARD_BACKGROUND;
+    ctx.fillRect(0, 0, BOARD_WIDTH * scale, BOARD_HEIGHT * scale);
+    ctx.setTransform(scale, 0, 0, scale, 0, 0);
+    for (const element of elements) {
+        drawElement(ctx, element);
+    }
+    ctx.restore();
+}
+export function drawElement(ctx, element) {
+    ctx.save();
+    switch (element.kind) {
+        case "stroke":
+            drawStroke(ctx, element);
+            break;
+        case "shape":
+            drawShape(ctx, element);
+            break;
+        case "stamp":
+            drawStamp(ctx, element);
+            break;
+    }
+    ctx.restore();
+}
+/** Traces a smooth path through `points` (curves through the midpoints between them), offset by (`dx`, `dy`). */
+function tracePath(ctx, points, dx = 0, dy = 0) {
+    ctx.beginPath();
+    ctx.moveTo(points[0] + dx, points[1] + dy);
+    if (points.length === 2) {
+        // A single tap still leaves a dot.
+        ctx.lineTo(points[0] + dx + 0.01, points[1] + dy);
+        return;
+    }
+    for (let i = 2; i < points.length - 2; i += 2) {
+        const midX = (points[i] + points[i + 2]) / 2;
+        const midY = (points[i + 1] + points[i + 3]) / 2;
+        ctx.quadraticCurveTo(points[i] + dx, points[i + 1] + dy, midX + dx, midY + dy);
+    }
+    ctx.lineTo(points[points.length - 2] + dx, points[points.length - 1] + dy);
+}
+function drawStroke(ctx, stroke) {
+    const { points, size, color } = stroke;
+    ctx.strokeStyle = color;
+    ctx.fillStyle = color;
+    ctx.lineJoin = "round";
+    ctx.lineCap = "round";
+    switch (stroke.pen) {
+        case "ballpoint":
+            ctx.lineWidth = Math.max(1.2, size * 0.6);
+            tracePath(ctx, points);
+            ctx.stroke();
+            return;
+        case "sharpie":
+            ctx.lineWidth = size * 1.4;
+            tracePath(ctx, points);
+            ctx.stroke();
+            return;
+        case "marker":
+            ctx.globalCompositeOperation = "multiply";
+            ctx.globalAlpha = 0.4;
+            ctx.lineCap = "square";
+            ctx.lineWidth = size * 3;
+            tracePath(ctx, points);
+            ctx.stroke();
+            return;
+        case "crayon":
+            drawCrayon(ctx, stroke);
+            return;
+        case "pencil":
+            drawPencil(ctx, stroke);
+            return;
+    }
+}
+function drawCrayon(ctx, stroke) {
+    const random = seededRandom(stroke.id);
+    const width = stroke.size * 1.8;
+    ctx.globalAlpha = 0.55;
+    ctx.lineWidth = width;
+    tracePath(ctx, stroke.points);
+    ctx.stroke();
+    // Grain: specks scattered across the stroke's width along every segment, more for a longer segment.
+    ctx.globalAlpha = 0.7;
+    const speck = Math.max(1, width / 6);
+    eachSegment(stroke.points, (x0, y0, x1, y1, length) => {
+        const count = Math.ceil((length * width) / 18);
+        for (let i = 0; i < count; i++) {
+            const t = random();
+            const spread = (random() - 0.5) * width;
+            const along = (random() - 0.5) * speck;
+            ctx.fillRect(x0 + (x1 - x0) * t + spread * 0.7 + along, y0 + (y1 - y0) * t + spread * 0.7 - along, speck, speck);
+        }
+    });
+}
+function drawPencil(ctx, stroke) {
+    const random = seededRandom(stroke.id);
+    ctx.lineWidth = Math.max(0.8, stroke.size * 0.45);
+    ctx.globalAlpha = 0.35;
+    const passes = 3;
+    const jitter = Math.max(0.6, stroke.size * 0.35);
+    for (let pass = 0; pass < passes; pass++) {
+        tracePath(ctx, stroke.points, (random() - 0.5) * jitter, (random() - 0.5) * jitter);
+        ctx.stroke();
+    }
+}
+/** Calls `visit` with each segment of `points` and its length; a single point is a zero-length segment. */
+function eachSegment(points, visit) {
+    if (points.length === 2) {
+        visit(points[0], points[1], points[0], points[1], 1);
+        return;
+    }
+    for (let i = 0; i < points.length - 2; i += 2) {
+        const [x0, y0, x1, y1] = [points[i], points[i + 1], points[i + 2], points[i + 3]];
+        visit(x0, y0, x1, y1, Math.hypot(x1 - x0, y1 - y0));
+    }
+}
+function drawShape(ctx, shape) {
+    const { x1, y1, x2, y2 } = shape;
+    ctx.strokeStyle = shape.color;
+    ctx.lineWidth = shape.size;
+    ctx.lineJoin = "round";
+    ctx.lineCap = "round";
+    ctx.beginPath();
+    const left = Math.min(x1, x2);
+    const top = Math.min(y1, y2);
+    const width = Math.abs(x2 - x1);
+    const height = Math.abs(y2 - y1);
+    switch (shape.shape) {
+        case "line":
+            ctx.moveTo(x1, y1);
+            ctx.lineTo(x2, y2);
+            break;
+        case "arrow": {
+            ctx.moveTo(x1, y1);
+            ctx.lineTo(x2, y2);
+            const angle = Math.atan2(y2 - y1, x2 - x1);
+            const head = Math.max(12, shape.size * 4);
+            for (const side of [-1, 1]) {
+                ctx.moveTo(x2, y2);
+                ctx.lineTo(x2 - head * Math.cos(angle + side * (Math.PI / 7)), y2 - head * Math.sin(angle + side * (Math.PI / 7)));
+            }
+            break;
+        }
+        case "rect":
+            ctx.moveTo(left, top);
+            ctx.lineTo(left + width, top);
+            ctx.lineTo(left + width, top + height);
+            ctx.lineTo(left, top + height);
+            ctx.closePath();
+            break;
+        case "ellipse":
+            ctx.ellipse(left + width / 2, top + height / 2, width / 2, height / 2, 0, 0, Math.PI * 2);
+            break;
+        case "triangle":
+            ctx.moveTo(left + width / 2, top);
+            ctx.lineTo(left + width, top + height);
+            ctx.lineTo(left, top + height);
+            ctx.closePath();
+            break;
+        case "star":
+            for (const [i, [px, py]] of starPoints(left, top, width, height).entries()) {
+                if (i === 0) {
+                    ctx.moveTo(px, py);
+                }
+                else {
+                    ctx.lineTo(px, py);
+                }
+            }
+            ctx.closePath();
+            break;
+    }
+    ctx.stroke();
+}
+/** The ten corners of a five-pointed star filling the given box, starting at its top point. */
+export function starPoints(left, top, width, height) {
+    const cx = left + width / 2;
+    const cy = top + height / 2;
+    const corners = [];
+    for (let i = 0; i < 10; i++) {
+        const radius = i % 2 === 0 ? 1 : 0.4;
+        const angle = -Math.PI / 2 + (i * Math.PI) / 5;
+        corners.push([cx + (Math.cos(angle) * radius * width) / 2, cy + (Math.sin(angle) * radius * height) / 2]);
+    }
+    return corners;
+}
+function drawStamp(ctx, stamp) {
+    ctx.font = `${stamp.size}px ${STAMP_FONT_FAMILY}`;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillStyle = "#000000";
+    ctx.fillText(stamp.stamp, stamp.x, stamp.y);
+}
+function distanceToSegment(px, py, x0, y0, x1, y1) {
+    const dx = x1 - x0;
+    const dy = y1 - y0;
+    const lengthSquared = dx * dx + dy * dy;
+    const t = lengthSquared === 0 ? 0 : Math.max(0, Math.min(1, ((px - x0) * dx + (py - y0) * dy) / lengthSquared));
+    return Math.hypot(px - (x0 + t * dx), py - (y0 + t * dy));
+}
+/** Whether the eraser at (`x`, `y`) with `radius`, in board units, touches `element`. A stroke or line counts its own
+ * width; a closed shape is touched on its outline's bounding box, a stamp anywhere on its square. */
+export function hitTest(element, x, y, radius) {
+    switch (element.kind) {
+        case "stroke": {
+            const reach = radius + element.size;
+            let hit = false;
+            eachSegment(element.points, (x0, y0, x1, y1) => {
+                hit = hit || distanceToSegment(x, y, x0, y0, x1, y1) <= reach;
+            });
+            return hit;
+        }
+        case "shape": {
+            const reach = radius + element.size;
+            if (element.shape === "line" || element.shape === "arrow") {
+                return distanceToSegment(x, y, element.x1, element.y1, element.x2, element.y2) <= reach;
+            }
+            const left = Math.min(element.x1, element.x2) - reach;
+            const right = Math.max(element.x1, element.x2) + reach;
+            const top = Math.min(element.y1, element.y2) - reach;
+            const bottom = Math.max(element.y1, element.y2) + reach;
+            return x >= left && x <= right && y >= top && y <= bottom;
+        }
+        case "stamp": {
+            const half = element.size / 2 + radius;
+            return Math.abs(x - element.x) <= half && Math.abs(y - element.y) <= half;
+        }
+    }
+}

package/dist/apps/shared/relay/AudioPlayer.d.ts

@@ -1,5 +1,8 @@
+import type { RelayReceiveDiagnostics } from "../webrtc/types.js";
 import { type Frame } from "./frames.js";
 import type { AudioContextLike, RelayEnv } from "./relayEnv.js";
+/** The playback half of `RelayReceiveDiagnostics.audio`. */
+export type AudioPlaybackStats = Pick<RelayReceiveDiagnostics["audio"], "playedMs" | "silentMs" | "gaps" | "gapMs" | "droppedLate" | "bufferedMs">;
 export declare const PLAYBACK_SAMPLE_RATE = 48000;
 /** How far ahead of the clock the first packet after a start or an underrun is scheduled. It is the jitter buffer:
  * packets arriving up to this late (relative to their neighbours) still play in order without a gap. */
@@ -38,8 +41,14 @@ export declare class AudioPlayer {
     private decoder;
     private nextTime;
     private readonly timestamps;
+    private readonly played;
+    private gaps;
+    private gapSeconds;
+    private droppedLate;
     /** `destination` is the node whose stream the peer's `MediaStream` carries. */
     constructor(env: RelayEnv, ctx: AudioContextLike, destination: unknown);
+    /** What playback has done so far - see `RelayReceiveDiagnostics`. */
+    stats(): AudioPlaybackStats;
     /** Feeds one reassembled audio frame (one Opus packet). */
     push(frame: Frame): void;
     close(): void;

package/dist/apps/shared/relay/AudioPlayer.js

@@ -1,9 +1,6 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
 import { TimestampUnwrapper } from "./frames.js";
 import { safeClose } from "./senderCommon.js";
+import { SilenceMeter } from "./SilenceMeter.js";
 export const PLAYBACK_SAMPLE_RATE = 48000;
 /** How far ahead of the clock the first packet after a start or an underrun is scheduled. It is the jitter buffer:
  * packets arriving up to this late (relative to their neighbours) still play in order without a gap. */
@@ -43,11 +40,27 @@ export class AudioPlayer {
         this.destination = destination;
         this.nextTime = 0;
         this.timestamps = new TimestampUnwrapper();
+        this.played = new SilenceMeter();
+        this.gaps = 0;
+        this.gapSeconds = 0;
+        this.droppedLate = 0;
+    }
+    /** What playback has done so far - see `RelayReceiveDiagnostics`. */
+    stats() {
+        return {
+            playedMs: this.played.totalMs,
+            silentMs: this.played.silentMs,
+            gaps: this.gaps,
+            gapMs: this.gapSeconds * 1000,
+            droppedLate: this.droppedLate,
+            bufferedMs: Math.max(0, this.nextTime - this.ctx.currentTime) * 1000,
+        };
     }
     /** Feeds one reassembled audio frame (one Opus packet). */
     push(frame) {
         const decoder = this.decoder ?? this.createDecoder();
         if (!decoder || decoder.decodeQueueSize > AUDIO_MAX_DECODE_QUEUE) {
+            this.droppedLate += 1;
             return;
         }
         try {
@@ -91,6 +104,7 @@ export class AudioPlayer {
         try {
             const now = this.ctx.currentTime;
             if (this.nextTime - now > MAX_AHEAD_SECONDS) {
+                this.droppedLate += 1;
                 return;
             }
             const buffer = this.ctx.createBuffer(1, data.numberOfFrames, data.sampleRate);
@@ -118,6 +132,12 @@ export class AudioPlayer {
                 source.onended = () => source.disconnect();
             }
             source.start(start);
+            this.played.feed(pcm, data.sampleRate);
+            if (start > this.nextTime && this.nextTime > 0) {
+                // Playback ran dry: everything between the end of the last block and this one is silence.
+                this.gaps += 1;
+                this.gapSeconds += start - this.nextTime;
+            }
             this.nextTime = start + buffer.duration;
         }
         catch {

package/dist/apps/shared/relay/AudioSender.d.ts

@@ -1,3 +1,4 @@
+import type { RelaySendDiagnostics } from "../webrtc/types.js";
 import { type SenderDeps } from "./senderCommon.js";
 export declare const AUDIO_SAMPLE_RATE = 48000;
 /** Frames per `ScriptProcessorNode` callback: about 43 ms, a compromise between latency and how often the main
@@ -35,7 +36,14 @@ export declare class AudioSender {
     private encoder;
     private baseMs;
     private samples;
+    /** Diagnostics, cumulative across capture sessions: what the capture path delivered (and how much of it was
+     * silent), the wall-clock time it was attached for, and what the encoder had to skip. */
+    private readonly captured;
+    private wallMs;
+    private encoderSkippedSamples;
     constructor(deps: SenderDeps);
+    /** The capture half of `RelaySendDiagnostics`. */
+    captureStats(): Pick<RelaySendDiagnostics, "audioCapturedMs" | "audioCaptureWallMs" | "audioSilentMs" | "audioEncoderSkippedMs">;
     setActive(active: boolean): void;
     setTrack(track: MediaStreamTrack | null): void;
     /** Brings the capture graph in line with (`active`, `track`): torn down when either is missing, rebuilt when

package/dist/apps/shared/relay/AudioSender.js

@@ -1,10 +1,7 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
 import { resumeAudioContext } from "./audioResume.js";
 import { KIND_AUDIO } from "./frames.js";
 import { safeClose } from "./senderCommon.js";
+import { SilenceMeter } from "./SilenceMeter.js";
 export const AUDIO_SAMPLE_RATE = 48000;
 /** Frames per `ScriptProcessorNode` callback: about 43 ms, a compromise between latency and how often the main
  * thread is interrupted. */
@@ -36,6 +33,20 @@ export class AudioSender {
         this.attachedTrack = null;
         this.baseMs = 0;
         this.samples = 0;
+        /** Diagnostics, cumulative across capture sessions: what the capture path delivered (and how much of it was
+         * silent), the wall-clock time it was attached for, and what the encoder had to skip. */
+        this.captured = new SilenceMeter();
+        this.wallMs = 0;
+        this.encoderSkippedSamples = 0;
+    }
+    /** The capture half of `RelaySendDiagnostics`. */
+    captureStats() {
+        return {
+            audioCapturedMs: this.captured.totalMs,
+            audioCaptureWallMs: this.wallMs + (this.attachedTrack ? this.deps.env.now() - this.baseMs : 0),
+            audioSilentMs: this.captured.silentMs,
+            audioEncoderSkippedMs: (this.encoderSkippedSamples * 1000) / AUDIO_SAMPLE_RATE,
+        };
     }
     setActive(active) {
         this.active = active;
@@ -84,6 +95,9 @@ export class AudioSender {
         }
     }
     detach() {
+        if (this.attachedTrack) {
+            this.wallMs += this.deps.env.now() - this.baseMs;
+        }
         this.attachedTrack = null;
         this.stopResume?.();
         this.stopResume = undefined;
@@ -109,11 +123,13 @@ export class AudioSender {
         const samples = input.length;
         const timestampUs = Math.round((this.samples * 1000000) / AUDIO_SAMPLE_RATE);
         this.samples += samples;
+        this.captured.feed(input, AUDIO_SAMPLE_RATE);
         if (!this.deps.canSend()) {
             return;
         }
         const encoder = this.encoder ?? this.createEncoder();
         if (!encoder || encoder.encodeQueueSize > AUDIO_MAX_ENCODE_QUEUE) {
+            this.encoderSkippedSamples += samples;
             return;
         }
         let audio;

package/dist/apps/shared/relay/RelayClient.d.ts

@@ -23,11 +23,16 @@ export declare const RELAY_BACKOFF_MAX_MS = 15000;
 /** How long a socket may take to become `ready` before it is abandoned and retried (a server that accepts the
  * upgrade but never answers the hello would otherwise hang the tier forever). */
 export declare const RELAY_HANDSHAKE_TIMEOUT_MS = 10000;
+/** How often a ready socket pings the server to time the round trip - often enough that the diagnostics panel (which
+ * polls every few seconds) always has a recent sample, rarely enough to cost nothing next to the media. */
+export declare const RELAY_PING_INTERVAL_MS = 2000;
 export interface RelayClientOptions {
     url: string;
     peerId: string;
     createSocket: (url: string) => RelaySocket;
     random: () => number;
+    /** A monotonic millisecond clock for timing pings. Defaults to `Date.now`. */
+    now?: () => number;
     /** Called with the sender's peer id (as stamped by the server) and the original payload. */
     onMedia: (peerId: string, payload: Uint8Array) => void;
 }
@@ -42,10 +47,15 @@ export declare class RelayClient {
     private wanted;
     private reconnectTimer;
     private handshakeTimer;
+    private pingTimer;
+    private lastRoundTripMs;
     private readonly decoder;
     constructor(options: RelayClientOptions);
     /** True once the server has answered the hello on the current socket, i.e. media may be sent. */
     get ready(): boolean;
+    /** The most recent ping's round trip to the server, in milliseconds - `undefined` until the first pong on the
+     * current socket (and for good on a server too old to answer pings). */
+    get roundTripMs(): number | undefined;
     /** The largest message `sendMedia()` will send: what the server announced in `ready` (validated and clamped), or
      * `MAX_MESSAGE_BYTES` before that, without one, and again after every disconnect until the next `ready`. The
      * frame fragmenter sizes its fragments from this. */
@@ -62,6 +72,12 @@ export declare class RelayClient {
     private openSocket;
     private handleMessage;
     private handleText;
+    /** Times the round trip of the ping that `t` came back from. Ignored before ready, for a `t` that isn't a number,
+     * or one from the future (nothing this client sent). */
+    private handlePong;
+    private now;
+    /** Stops pinging and forgets the last round trip - it described a socket that is gone. */
+    private stopPinging;
     private handleClose;
     /** Detaches and closes the current socket, if any, so its late events can't reach this client. */
     private detach;

package/dist/apps/shared/relay/RelayClient.js

@@ -13,13 +13,18 @@
  * older one, which accepts `MAX_MESSAGE_BYTES`). Nothing else may be sent before `ready`.
  * - `{"op":"want","peers":[...]}` REPLACES the set of senders this socket receives from (the server accepts at most
  * `MAX_WANTED_PEERS`). It has to be re-sent after every reconnect, because the server's set dies with the socket.
+ * - `{"op":"ping","t":<this client's clock>}`, every `RELAY_PING_INTERVAL_MS` once ready, is answered with
+ * `{"op":"pong","t":<the same>}`, which times the round trip to the server (`roundTripMs`) - over the same socket as
+ * the media, so it includes whatever the media has queued ahead of it. An older server ignores the ping and the
+ * round trip stays unknown.
  * - A binary message from the client is an opaque payload of at most `maxMessageBytes`. The server forwards it to
  * every socket that wants this sender as `[1 byte N][N bytes UTF-8 sender peer id][payload]`, stamping the sender
  * itself so a peer cannot speak as another.
  * - Binary messages may be dropped under backpressure and the socket may close at any moment, so this client
  * reconnects with exponential backoff and treats every media send as best effort.
  *
- * Authentication is the `jwt` cookie already in place (see `GuestSignalingClient`), so this client sets no cookie.
+ * Authentication is the `jwt` cookie already in place (see `../signaling/SignalingClient.ts`), so this client sets no
+ * cookie.
  */
 import { DEFAULT_MESSAGE_BYTES } from "./frames.js";
 /** The largest binary message an older server accepts - it closes the socket on a larger one (uWS's default limit).
@@ -46,6 +51,9 @@ export const RELAY_BACKOFF_MAX_MS = 15000;
 /** How long a socket may take to become `ready` before it is abandoned and retried (a server that accepts the
  * upgrade but never answers the hello would otherwise hang the tier forever). */
 export const RELAY_HANDSHAKE_TIMEOUT_MS = 10000;
+/** How often a ready socket pings the server to time the round trip - often enough that the diagnostics panel (which
+ * polls every few seconds) always has a recent sample, rarely enough to cost nothing next to the media. */
+export const RELAY_PING_INTERVAL_MS = 2000;
 const SOCKET_OPEN = 1;
 /** Views `data` as bytes when it is binary (an `ArrayBuffer` or a typed array), else `undefined`. Uses
  * `Object.prototype.toString` rather than `instanceof` so it works for a buffer from another realm too. */
@@ -73,6 +81,11 @@ export class RelayClient {
     get ready() {
         return this.isReady;
     }
+    /** The most recent ping's round trip to the server, in milliseconds - `undefined` until the first pong on the
+     * current socket (and for good on a server too old to answer pings). */
+    get roundTripMs() {
+        return this.lastRoundTripMs;
+    }
     /** The largest message `sendMedia()` will send: what the server announced in `ready` (validated and clamped), or
      * `MAX_MESSAGE_BYTES` before that, without one, and again after every disconnect until the next `ready`. The
      * frame fragmenter sizes its fragments from this. */
@@ -125,6 +138,7 @@ export class RelayClient {
         clearTimeout(this.reconnectTimer);
         clearTimeout(this.handshakeTimer);
         this.reconnectTimer = this.handshakeTimer = undefined;
+        this.stopPinging();
         this.detach();
     }
     openSocket() {
@@ -176,7 +190,15 @@ export class RelayClient {
         catch {
             return;
         }
-        if (!message || typeof message !== "object" || message.op !== "ready" || this.isReady) {
+        if (!message || typeof message !== "object") {
+            return;
+        }
+        const op = message.op;
+        if (op === "pong") {
+            this.handlePong(message.t);
+            return;
+        }
+        if (op !== "ready" || this.isReady) {
             return;
         }
         this.isReady = true;
@@ -189,12 +211,34 @@ export class RelayClient {
         this.handshakeTimer = undefined;
         // The server's wanted set is per socket, so it starts empty on every (re)connect.
         this.sendText({ op: "want", peers: this.wanted });
+        this.pingTimer = setInterval(() => this.sendText({ op: "ping", t: this.now() }), RELAY_PING_INTERVAL_MS);
+    }
+    /** Times the round trip of the ping that `t` came back from. Ignored before ready, for a `t` that isn't a number,
+     * or one from the future (nothing this client sent). */
+    handlePong(t) {
+        if (!this.isReady || typeof t !== "number") {
+            return;
+        }
+        const roundTrip = this.now() - t;
+        if (roundTrip >= 0) {
+            this.lastRoundTripMs = roundTrip;
+        }
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    /** Stops pinging and forgets the last round trip - it described a socket that is gone. */
+    stopPinging() {
+        clearInterval(this.pingTimer);
+        this.pingTimer = undefined;
+        this.lastRoundTripMs = undefined;
     }
     handleClose(socket) {
         if (socket !== this.socket) {
             return;
         }
         this.isReady = false;
+        this.stopPinging();
         // The next server might be a different one (a rolling upgrade), so the limit is learned afresh.
         this.messageLimit = MAX_MESSAGE_BYTES;
         clearTimeout(this.handshakeTimer);

package/dist/apps/shared/relay/RelayReceiver.d.ts

@@ -1,3 +1,4 @@
+import type { RelayReceiveDiagnostics } from "../webrtc/types.js";
 import type { AudioContextLike, RelayEnv } from "./relayEnv.js";
 /**
  * One remote participant as seen through the relay: reassembles their fragments, decodes them, and exposes the result
@@ -11,11 +12,15 @@ export declare class RelayReceiver {
     readonly stream: MediaStream;
     private readonly audioFrames;
     private readonly videoFrames;
+    private readonly audioCounter;
+    private readonly videoCounter;
     private readonly audio;
     private readonly video;
     constructor(env: RelayEnv, playbackContext: AudioContextLike);
     /** Handles one relayed payload from this sender (a media fragment). Anything malformed is ignored. */
     handleMedia(payload: Uint8Array): void;
+    /** A snapshot of what has been received from this peer - see `RelayReceiveDiagnostics`. */
+    diagnostics(): RelayReceiveDiagnostics;
     /** Releases the decoders and ends the stream's tracks. */
     close(): void;
 }

package/dist/apps/shared/relay/RelayReceiver.js

@@ -1,10 +1,29 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
 import { AudioPlayer } from "./AudioPlayer.js";
-import { decodeFragment, FrameReassembler, KIND_AUDIO } from "./frames.js";
+import { decodeFragment, FrameReassembler, KIND_AUDIO, seqIsNewer } from "./frames.js";
 import { VideoPlayer } from "./VideoPlayer.js";
+const SEQ_MODULUS = 0x10000;
+/** A jump in sequence numbers bigger than this is taken for the sender restarting its counter, not for that many
+ * lost frames. Ten seconds of 20 ms audio packets - far more than any real outage the stream would survive. */
+const MAX_COUNTED_SEQ_GAP = 500;
+/** Counts one kind's frames as they complete, and the ones the sequence numbers say never did. */
+class ReceiveCounter {
+    constructor() {
+        this.stats = { framesReceived: 0, framesLost: 0, bytesReceived: 0 };
+    }
+    fragment(bytes) {
+        this.stats.bytesReceived += bytes;
+    }
+    frame(frame) {
+        this.stats.framesReceived += 1;
+        if (this.lastSeq !== undefined && seqIsNewer(frame.seq, this.lastSeq)) {
+            const missing = ((frame.seq - this.lastSeq + SEQ_MODULUS) % SEQ_MODULUS) - 1;
+            if (missing <= MAX_COUNTED_SEQ_GAP) {
+                this.stats.framesLost += missing;
+            }
+        }
+        this.lastSeq = frame.seq;
+    }
+}
 /** The canvas is sized to the first decoded picture; until then it is this size. */
 const INITIAL_CANVAS_WIDTH = 320;
 const INITIAL_CANVAS_HEIGHT = 240;
@@ -22,6 +41,8 @@ export class RelayReceiver {
     constructor(env, playbackContext) {
         this.audioFrames = new FrameReassembler();
         this.videoFrames = new FrameReassembler();
+        this.audioCounter = new ReceiveCounter();
+        this.videoCounter = new ReceiveCounter();
         const destination = playbackContext.createMediaStreamDestination();
         this.audio = new AudioPlayer(env, playbackContext, destination);
         const canvas = env.createCanvas();
@@ -37,10 +58,14 @@ export class RelayReceiver {
         if (!fragment) {
             return;
         }
-        const frame = (fragment.kind === KIND_AUDIO ? this.audioFrames : this.videoFrames).push(fragment);
+        const isAudio = fragment.kind === KIND_AUDIO;
+        const counter = isAudio ? this.audioCounter : this.videoCounter;
+        counter.fragment(payload.length);
+        const frame = (isAudio ? this.audioFrames : this.videoFrames).push(fragment);
         if (!frame) {
             return;
         }
+        counter.frame(frame);
         if (frame.kind === KIND_AUDIO) {
             this.audio.push(frame);
         }
@@ -48,6 +73,13 @@ export class RelayReceiver {
             this.video?.push(frame);
         }
     }
+    /** A snapshot of what has been received from this peer - see `RelayReceiveDiagnostics`. */
+    diagnostics() {
+        return {
+            audio: { ...this.audioCounter.stats, ...this.audio.stats() },
+            video: { ...this.videoCounter.stats },
+        };
+    }
     /** Releases the decoders and ends the stream's tracks. */
     close() {
         this.audio.close();