@obsrviq/tracker 0.5.0 → 0.7.0

package/src/transport.ts

@@ -16,15 +16,50 @@ export interface TransportOptions {
    *  the host persist progress synchronously so a later page load resumes without a
    *  seq collision even if an unload interrupts the in-flight request. */
   onSeqDispatch?: (nextSeq: number) => void;
+  /** Called after backpressure had to drop buffered DOM deltas — the host should
+   *  force a fresh rrweb FullSnapshot so the replay stream re-anchors instead of
+   *  playing corrupt deltas until the next scheduled checkpoint. */
+  onDomDrop?: () => void;
   /** test/observability hook */
   onFlush?: (info: { bytes: number; events: number; ok: boolean }) => void;
 }
 
 const MAX_BUFFER_EVENTS = 5000; // backpressure cap (R-5)
+/** Split batches whose JSON exceeds this before sending — well under the ingest
+ *  body cap (16MB gzip) even at gzip-hostile content, and keeps main-thread
+ *  stringify/compress work per flush bounded. */
+const MAX_BATCH_JSON_BYTES = 4 * 1024 * 1024;
+/** Target gzip size per unload piece — sendBeacon/keepalive cap in-flight bodies
+ *  at ~64KB, so pieces are kept comfortably under it. */
+const BEACON_PIECE_BYTES = 56 * 1024;
+/** localStorage spill of batches an unload couldn't beacon out (queue full /
+ *  oversized). Resent by the next page load. Bounded so we respect the ~5MB
+ *  origin quota shared with the app. */
+const SPILL_KEY = 'obsrviq.spill';
+const SPILL_MAX_BYTES = 1_500_000;
+const SPILL_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+// rrweb event types we need to recognise for snapshot-aware dropping.
+const RR_FULL_SNAPSHOT = 2;
+const RR_META = 4;
+
+/** Outcome of one network attempt — drives retry/split/drop decisions. */
+type SendResult = 'ok' | 'too_large' | 'fatal' | 'retry';
+
+interface SpillEntry {
+  /** siteKey — so multi-site pages only resend their own batches. */
+  k: string;
+  /** base64 of the gzipped, fully-stamped IngestBatch (self-contained). */
+  b: string;
+  ts: number;
+}
 
 export class Transport {
   private buffer: ObsrviqEvent[] = [];
   private seq: number;
+  /** Floor set by an unload flush that consumed seqs out-of-band (beacon pieces),
+   *  so the normal path can never re-use one of them. */
+  private seqFloor = 0;
   private timer: ReturnType<typeof setInterval> | undefined;
   private sending = false;
   private retryDelay = 1000;
@@ -38,33 +73,76 @@ export class Transport {
     this.timer = setInterval(() => void this.flush('timer'), this.opts.flushIntervalMs);
     document.addEventListener('visibilitychange', this.onVisibility, { capture: true });
     window.addEventListener('pagehide', this.onPageHide, { capture: true });
+    // Recover anything a previous page's unload had to spill to localStorage.
+    this.resendSpill();
   }
 
   enqueue(event: ObsrviqEvent) {
     if (this.stopped) return;
     this.buffer.push(event);
     // Backpressure: if we've buffered a lot, flush early; if still over after a
-    // failed flush, drop the oldest DOM events (keep structured signal).
+    // failed flush, shed DOM backlog without corrupting the delta stream.
     if (this.buffer.length >= MAX_BUFFER_EVENTS) {
       void this.flush('backpressure');
-      if (this.buffer.length >= MAX_BUFFER_EVENTS) {
-        this.buffer = this.buffer.filter((e, i) => e.type !== 'dom' || i % 2 === 0);
+      if (this.buffer.length >= MAX_BUFFER_EVENTS) this.shedDomBacklog();
+    }
+  }
+
+  /** Drop buffered DOM events WITHOUT breaking rrweb's delta chain. Deltas only
+   *  apply on top of everything before them, so arbitrary dropping corrupts the
+   *  replay until the next 30s checkpoint. Instead: if the buffer holds a
+   *  FullSnapshot, drop only the DOM events BEFORE it (the snapshot re-anchors
+   *  everything after). Otherwise drop ALL buffered DOM and ask the recorder for
+   *  a fresh FullSnapshot so the stream re-anchors immediately. Non-DOM events
+   *  (console/network/errors/…) are independent and kept. */
+  private shedDomBacklog() {
+    let snapIdx = -1;
+    for (let i = this.buffer.length - 1; i >= 0; i--) {
+      const e = this.buffer[i];
+      if (e?.type === 'dom' && (e.data as { type?: number } | undefined)?.type === RR_FULL_SNAPSHOT) {
+        snapIdx = i;
+        break;
       }
     }
+    if (snapIdx > 0) {
+      // Keep from the snapshot's preceding Meta (rrweb emits Meta → FullSnapshot).
+      let keepFrom = snapIdx;
+      const prev = this.buffer[snapIdx - 1];
+      if (prev?.type === 'dom' && (prev.data as { type?: number } | undefined)?.type === RR_META) {
+        keepFrom = snapIdx - 1;
+      }
+      const kept = this.buffer.filter((e, i) => e.type !== 'dom' || i >= keepFrom);
+      if (kept.length < this.buffer.length) {
+        this.buffer = kept;
+        if (this.buffer.length < MAX_BUFFER_EVENTS) return;
+      }
+    }
+    // No snapshot to anchor on (or one window alone overflows): drop all DOM and
+    // re-anchor with a fresh snapshot.
+    this.buffer = this.buffer.filter((e) => e.type !== 'dom');
+    // Pathological non-DOM flood: shed oldest half so the buffer stays bounded.
+    if (this.buffer.length >= MAX_BUFFER_EVENTS) {
+      this.buffer = this.buffer.slice(-Math.floor(MAX_BUFFER_EVENTS / 2));
+    }
+    this.opts.onDomDrop?.();
   }
 
   /** Build, compress, and send the current buffer. Returns true on success. */
   async flush(reason: 'timer' | 'hidden' | 'pagehide' | 'manual' | 'backpressure'): Promise<boolean> {
+    // Unload path is separate: it must run even mid-send (the in-flight fetch is
+    // about to be killed by navigation) and can't await anything.
+    if (reason === 'pagehide' || reason === 'hidden') return this.flushUnload();
+
     if (this.sending || this.buffer.length === 0) return true;
 
     // Hold non-unload sends until the per-site mask config has loaded, so a
     // remote-only custom key can't leak in the brief init fetch window. The fetch
     // is bounded (index.ts marks config ready within ~2s even on failure/timeout),
     // so this delays at most the first batch — it never blocks data indefinitely.
-    // Unload flushes (pagehide/hidden) can't wait, so they proceed best-effort.
-    const unloading = reason === 'pagehide' || reason === 'hidden';
-    if (!unloading && isMaskConfigPending()) {
-      if (!this.stopped) setTimeout(() => void this.flush('timer'), 200);
+    // A stopped transport can't wait (there'll be no retry) — its final flush
+    // proceeds best-effort with whatever keys have loaded, like the unload path.
+    if (isMaskConfigPending() && !this.stopped) {
+      setTimeout(() => void this.flush('timer'), 200);
       return true;
     }
 
@@ -80,6 +158,62 @@ export class Transport {
     // before the per-site config arrived.
     redactBatchSensitiveKeys(events);
 
+    let ok: boolean;
+    try {
+      ok = await this.sendEvents(events);
+    } finally {
+      this.sending = false;
+    }
+    // stop() during this send no-oped (sending guard) — drain what it left
+    // behind, since no timer remains to pick it up. Only on success: a failure
+    // just re-buffered, and retrying here would spin against a dead network.
+    if (ok && this.stopped && this.buffer.length > 0) void this.flush('manual');
+    return ok;
+  }
+
+  /** Send events as one or more seq-stamped batches: oversized batches split in
+   *  half (byte cap here, or a server 413), poison batches (other 4xx) are dropped
+   *  instead of retried forever, and transient failures re-buffer + back off. */
+  private async sendEvents(events: ObsrviqEvent[]): Promise<boolean> {
+    const queue: ObsrviqEvent[][] = [events];
+    while (queue.length > 0) {
+      const slice = queue[0]!;
+      const result = await this.dispatch(slice);
+      if (result === 'ok') {
+        queue.shift();
+        continue;
+      }
+      if (result === 'too_large' && slice.length > 1) {
+        const mid = Math.ceil(slice.length / 2);
+        queue.splice(0, 1, slice.slice(0, mid), slice.slice(mid));
+        continue;
+      }
+      if (result === 'fatal' || result === 'too_large') {
+        // Rejected outright (bad key / revoked site / single event over the cap):
+        // retrying can never succeed — drop this slice, keep sending the rest.
+        queue.shift();
+        continue;
+      }
+      // Transient (network / 5xx / 429): re-buffer everything left, in original
+      // order ahead of anything captured meanwhile, and retry with jitter.
+      this.buffer = ([] as ObsrviqEvent[]).concat(...queue, this.buffer);
+      if (this.buffer.length >= MAX_BUFFER_EVENTS) this.shedDomBacklog();
+      if (!this.stopped) {
+        const jitter = this.retryDelay * (0.5 + Math.random());
+        this.retryDelay = Math.min(this.retryDelay * 2, 30_000);
+        setTimeout(() => void this.flush('timer'), jitter);
+      }
+      return false;
+    }
+    this.retryDelay = 1000;
+    return true;
+  }
+
+  /** One batch → one network attempt. Owns seq assignment/advance. */
+  private async dispatch(events: ObsrviqEvent[]): Promise<SendResult> {
+    // Never re-use a seq an unload flush consumed out-of-band.
+    if (this.seqFloor > this.seq) this.seq = this.seqFloor;
+
     let batch: IngestBatch | null = {
       siteKey: this.opts.siteKey,
       sessionId: this.opts.sessionId,
@@ -94,10 +228,12 @@ export class Transport {
         batch = null;
       }
     }
-    if (!batch) {
-      this.sending = false;
-      return true; // dropped intentionally
-    }
+    if (!batch) return 'ok'; // dropped intentionally
+
+    const json = JSON.stringify(batch);
+    // Byte cap: split BEFORE compressing/sending rather than bounce off the
+    // server's body limit (a lost batch) — sendEvents halves it and retries.
+    if (json.length > MAX_BATCH_JSON_BYTES && events.length > 1) return 'too_large';
 
     // Reserve the next seq + stamp activity SYNCHRONOUSLY at dispatch — before any
     // network await. This is what session continuation persists, so an unload that
@@ -107,84 +243,188 @@ export class Transport {
     // active-but-offline session isn't wrongly treated as idle and split.
     this.opts.onSeqDispatch?.(this.seq + 1);
 
-    const json = JSON.stringify(batch);
-    const gz = gzipSync(new TextEncoder().encode(json));
-    const ok = await this.send(gz, reason === 'pagehide' || reason === 'hidden');
-    this.opts.onFlush?.({ bytes: gz.byteLength, events: events.length, ok });
-
-    if (ok) {
-      this.seq++;
-      this.retryDelay = 1000;
-      this.sending = false;
-      return true;
-    }
+    const gz = await gzipBytes(new TextEncoder().encode(json));
+    const result = await this.send(gz);
+    this.opts.onFlush?.({ bytes: gz.byteLength, events: events.length, ok: result === 'ok' });
+    if (result === 'ok') this.seq = Math.max(this.seq + 1, this.seqFloor);
+    return result;
+  }
 
-    // Failed: re-buffer (capped) and retry with jitter.
-    this.buffer = events.slice(-MAX_BUFFER_EVENTS).concat(this.buffer);
-    this.sending = false;
-    if (!this.stopped) {
-      const jitter = this.retryDelay * (0.5 + Math.random());
-      this.retryDelay = Math.min(this.retryDelay * 2, 30_000);
-      setTimeout(() => void this.flush('timer'), jitter);
+  private async send(bytes: Uint8Array): Promise<SendResult> {
+    const url = `${this.opts.endpoint.replace(/\/$/, '')}/v1/batch`;
+    // Normal flush: a plain fetch — NO `keepalive`, so there's no 64KB body cap
+    // and large FullSnapshot batches actually send. Await the real result so a
+    // failure re-buffers and retries instead of being silently dropped. A timeout
+    // aborts a hung request so it can't stall all future flushes (`sending` stays
+    // true until this resolves).
+    const ctrl = new AbortController();
+    const timeout = setTimeout(() => ctrl.abort(), 15_000);
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        body: bytes as unknown as BodyInit,
+        headers: {
+          'content-type': 'application/octet-stream',
+          'x-obsrviq-key': this.opts.siteKey,
+        },
+        credentials: 'omit',
+        mode: 'cors',
+        signal: ctrl.signal,
+      });
+      if (res.ok) return 'ok';
+      if (res.status === 413) return 'too_large';
+      // 408 (timeout) and 429 (rate limit) are transient; other 4xx means the
+      // server will never accept this batch — retrying just re-loses it later.
+      if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) return 'fatal';
+      return 'retry';
+    } catch {
+      return 'retry';
+    } finally {
+      clearTimeout(timeout);
     }
-    return false;
   }
 
-  private async send(bytes: Uint8Array, unloading: boolean): Promise<boolean> {
-    const url = `${this.opts.endpoint.replace(/\/$/, '')}/v1/batch`;
-    const headers = {
-      'content-type': 'application/octet-stream',
-      'x-obsrviq-key': this.opts.siteKey,
-    };
-    const body = bytes as unknown as BodyInit;
-
-    // Unload path: a normal fetch would be cancelled as the page goes away, so
-    // use sendBeacon (survives navigation) or a keepalive fetch. BOTH cap the
-    // body at ~64KB, so large (snapshot) batches are best-effort here — but the
-    // periodic flushes below send them reliably during normal operation.
-    if (unloading) {
-      const blob = new Blob([bytes as unknown as BlobPart], { type: 'application/octet-stream' });
-      if (typeof navigator.sendBeacon === 'function') {
+  /** Unload flush (pagehide / tab hidden). Fully synchronous — the page may be
+   *  gone before any await resolves. Ignores the `sending` guard (that in-flight
+   *  fetch is about to be cancelled; its seq is skipped via seqFloor), chunks the
+   *  tail into beacon-sized pieces (sendBeacon caps bodies at ~64KB — one big
+   *  batch would be rejected whole), and spills anything the beacon queue refuses
+   *  to localStorage for the next page load to resend. */
+  private flushUnload(): boolean {
+    if (this.buffer.length === 0) return true;
+    const events = this.buffer;
+    this.buffer = [];
+    // Best-effort masking: built-in + whatever custom keys have loaded by now
+    // (an unload can't wait for the config fetch).
+    redactBatchSensitiveKeys(events);
+
+    // The in-flight batch (if any) holds this.seq — start past it; a prior
+    // unload flush (hidden → pagehide) may have raised the floor further.
+    let seq = Math.max(this.sending ? this.seq + 1 : this.seq, this.seqFloor);
+
+    const pieces: Array<{ gz: Uint8Array; count: number }> = [];
+    const stack: ObsrviqEvent[][] = [events];
+    while (stack.length > 0) {
+      const slice = stack.shift()!;
+      let batch: IngestBatch | null = {
+        siteKey: this.opts.siteKey,
+        sessionId: this.opts.sessionId,
+        seq,
+        meta: this.opts.getMeta(),
+        events: slice,
+      };
+      if (this.opts.beforeSend) {
         try {
-          if (navigator.sendBeacon(url, blob)) return true;
+          batch = this.opts.beforeSend(batch);
         } catch {
-          /* fall through */
+          batch = null;
         }
       }
+      if (!batch) continue; // dropped intentionally
+      const gz = gzipSync(new TextEncoder().encode(JSON.stringify(batch)));
+      if (gz.byteLength > BEACON_PIECE_BYTES && slice.length > 1) {
+        // Too big for a beacon — halve and re-stamp (the seq wasn't consumed).
+        const mid = Math.ceil(slice.length / 2);
+        stack.unshift(slice.slice(0, mid), slice.slice(mid));
+        continue;
+      }
+      pieces.push({ gz, count: slice.length });
+      seq++;
+    }
+
+    // Persist seq progress BEFORE handing bytes to the beacon queue, so a resumed
+    // session can't collide with a piece that's still in flight after unload.
+    this.seqFloor = seq;
+    this.opts.onSeqDispatch?.(seq);
+
+    for (const { gz, count } of pieces) {
+      const sent = gz.byteLength <= BEACON_PIECE_BYTES && this.sendUnload(gz);
+      if (!sent) this.spill(gz); // beacon queue full / single oversized event
+      this.opts.onFlush?.({ bytes: gz.byteLength, events: count, ok: sent });
+    }
+    return true;
+  }
+
+  /** Fire-and-forget delivery that survives navigation. True = queued. */
+  private sendUnload(bytes: Uint8Array): boolean {
+    const url = `${this.opts.endpoint.replace(/\/$/, '')}/v1/batch`;
+    const blob = new Blob([bytes as unknown as BlobPart], { type: 'application/octet-stream' });
+    if (typeof navigator.sendBeacon === 'function') {
       try {
-        void fetch(url, { method: 'POST', body, headers, keepalive: true, credentials: 'omit', mode: 'cors' }).catch(
-          () => {},
-        );
-        return true;
+        if (navigator.sendBeacon(url, blob)) return true;
       } catch {
-        return false;
+        /* fall through */
       }
     }
-
-    // Normal flush: a plain fetch — NO `keepalive`, so there's no 64KB body cap
-    // and large FullSnapshot batches actually send. Await the real result so a
-    // failure (rejected / 4xx / 5xx / network) re-buffers and retries instead of
-    // being silently dropped. A timeout aborts a hung request so it can't stall
-    // all future flushes (`sending` stays true until this resolves).
-    const ctrl = new AbortController();
-    const timeout = setTimeout(() => ctrl.abort(), 15_000);
     try {
-      const res = await fetch(url, {
+      void fetch(url, {
         method: 'POST',
-        body,
-        headers,
+        body: bytes as unknown as BodyInit,
+        headers: {
+          'content-type': 'application/octet-stream',
+          'x-obsrviq-key': this.opts.siteKey,
+        },
+        keepalive: true,
         credentials: 'omit',
         mode: 'cors',
-        signal: ctrl.signal,
-      });
-      return res.ok;
+      }).catch(() => {});
+      return true;
     } catch {
       return false;
-    } finally {
-      clearTimeout(timeout);
     }
   }
 
+  /** Append one gzipped batch to the localStorage spill (bounded, oldest-first
+   *  eviction). Quota/private-mode failures mean the tail is lost — same as
+   *  before spilling existed. */
+  private spill(gz: Uint8Array) {
+    try {
+      const raw = window.localStorage.getItem(SPILL_KEY);
+      const entries: SpillEntry[] = raw ? (JSON.parse(raw) as SpillEntry[]) : [];
+      entries.push({ k: this.opts.siteKey, b: b64encode(gz), ts: Date.now() });
+      let total = entries.reduce((n, e) => n + e.b.length, 0);
+      while (entries.length > 0 && total > SPILL_MAX_BYTES) {
+        total -= entries[0]!.b.length;
+        entries.shift();
+      }
+      window.localStorage.setItem(SPILL_KEY, JSON.stringify(entries));
+    } catch {
+      /* unavailable / quota — drop */
+    }
+  }
+
+  /** Resend batches a previous page's unload spilled. Entries are claimed
+   *  (removed) up front so two tabs can't double-send; still-transient failures
+   *  are re-spilled for the next load. Fire-and-forget. */
+  private resendSpill() {
+    let mine: SpillEntry[] = [];
+    try {
+      const raw = window.localStorage.getItem(SPILL_KEY);
+      if (!raw) return;
+      const entries = JSON.parse(raw) as SpillEntry[];
+      const now = Date.now();
+      const fresh = entries.filter((e) => e && typeof e.b === 'string' && now - e.ts < SPILL_MAX_AGE_MS);
+      mine = fresh.filter((e) => e.k === this.opts.siteKey);
+      const others = fresh.filter((e) => e.k !== this.opts.siteKey);
+      if (others.length > 0) window.localStorage.setItem(SPILL_KEY, JSON.stringify(others));
+      else window.localStorage.removeItem(SPILL_KEY);
+    } catch {
+      return;
+    }
+    if (mine.length === 0) return;
+    void (async () => {
+      for (const entry of mine) {
+        try {
+          const result = await this.send(b64decode(entry.b));
+          if (result === 'retry') this.spill(b64decode(entry.b)); // network still down
+          // ok / fatal / too_large → done with it either way
+        } catch {
+          /* drop */
+        }
+      }
+    })();
+  }
+
   private onVisibility = () => {
     if (document.visibilityState === 'hidden') void this.flush('hidden');
   };
@@ -200,3 +440,35 @@ export class Transport {
     void this.flush('manual');
   }
 }
+
+/** gzip — browser-native async CompressionStream when available (keeps multi-MB
+ *  snapshot compression off the main thread), fflate's gzipSync otherwise. The
+ *  unload path always uses gzipSync directly (it can't await). */
+async function gzipBytes(bytes: Uint8Array): Promise<Uint8Array> {
+  if (typeof CompressionStream !== 'undefined') {
+    try {
+      const stream = new Blob([bytes as unknown as BlobPart])
+        .stream()
+        .pipeThrough(new CompressionStream('gzip'));
+      return new Uint8Array(await new Response(stream).arrayBuffer());
+    } catch {
+      /* fall back to sync */
+    }
+  }
+  return gzipSync(bytes);
+}
+
+function b64encode(bytes: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(bin);
+}
+
+function b64decode(s: string): Uint8Array {
+  const bin = atob(s);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}

package/src/util.ts

@@ -64,9 +64,23 @@ export function detectDevice(): {
   os?: string;
   browser?: string;
   viewport: { w: number; h: number };
+  tz?: string;
+  tzOffset?: number;
 } {
   const ua = navigator.userAgent;
   const viewport = { w: window.innerWidth, h: window.innerHeight };
+
+  // The visitor's own timezone — so the player can show wall-clock times in their
+  // local time, not just the viewer's. IANA name (DST-correct) plus a numeric
+  // offset EAST of UTC as a fallback label. Both best-effort.
+  let tz: string | undefined;
+  let tzOffset: number | undefined;
+  try {
+    tz = Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+    tzOffset = -new Date().getTimezoneOffset();
+  } catch {
+    /* Intl unavailable — omit timezone */
+  }
   let type: 'desktop' | 'mobile' | 'tablet' = 'desktop';
   if (/iPad|Tablet/i.test(ua)) type = 'tablet';
   else if (/Mobi|Android|iPhone/i.test(ua)) type = 'mobile';
@@ -84,7 +98,7 @@ export function detectDevice(): {
   else if (/Firefox\//.test(ua)) browser = 'Firefox';
   else if (/Safari\//.test(ua)) browser = 'Safari';
 
-  return { type, os, browser, viewport };
+  return { type, os, browser, viewport, tz, tzOffset };
 }
 
 /** Global Privacy Control / Do Not Track. */

package/src/websocket.ts

@@ -1,9 +1,12 @@
 import type { WsEvent } from '@obsrviq/types';
 import type { InstrumentCtx, Teardown } from './context.js';
 import { maskString } from './mask.js';
+import { tokenBucket } from './ratelimit.js';
 import { uuid } from './util.js';
 
 const FRAME_CAP = 4 * 1024; // 4 KB text-frame preview cap (mirrors network bodies)
+const MSG_RATE = 20; // sustained message-frame events/sec per socket
+const MSG_BURST = 40; // burst capacity
 
 function redactUrl(raw: string): string {
   try {
@@ -31,12 +34,14 @@ function frameInfo(data: unknown, capture: boolean): FrameInfo {
   if (typeof data === 'string') {
     const info: FrameInfo = { encoding: 'text', size: byteLen(data) };
     if (capture) {
-      const masked = maskString(data);
-      const truncated = masked.length > FRAME_CAP;
+      // Pre-cut giant frames (2× slack) so masking never regex-scans a multi-MB payload.
+      const cut = data.length > FRAME_CAP * 2 ? data.slice(0, FRAME_CAP * 2) : data;
+      const masked = maskString(cut);
+      const truncated = cut !== data || masked.length > FRAME_CAP;
       info.body = {
         preview: truncated ? masked.slice(0, FRAME_CAP) : masked,
         truncated,
-        redacted: masked !== data,
+        redacted: masked !== cut,
       };
     }
     return info;
@@ -80,16 +85,38 @@ export function instrumentWebSocket(ctx: InstrumentCtx): Teardown {
         const protos = protocols ? (Array.isArray(protocols) ? protocols : [protocols]) : undefined;
         const capture = ctx.config.captureNetworkBodies;
 
+        // Per-socket frame throttle — a chatty socket (100s of msg/s) must not
+        // flood the buffer. Dropped frames are counted and reported on the next
+        // captured frame (or the close event). Lifecycle events (open/close/error)
+        // are never throttled.
+        const bucket = tokenBucket(MSG_RATE, MSG_BURST);
+        let droppedFrames = 0;
+        const emitFrame = (dir: 'send' | 'recv', data: unknown) => {
+          ctx.markActivity(); // dropped frames still count as app activity
+          if (!bucket.take()) {
+            droppedFrames++;
+            return;
+          }
+          const info = frameInfo(data, capture);
+          const dropped = droppedFrames;
+          droppedFrames = 0;
+          emit({ connId, url: redUrl, kind: 'message', dir, ...info, droppedFrames: dropped || undefined });
+        };
+
         this.addEventListener('open', () => emit({ connId, url: redUrl, kind: 'open', protocols: protos }));
         this.addEventListener('close', (e) =>
-          emit({ connId, url: redUrl, kind: 'close', code: e.code, reason: e.reason || undefined, wasClean: e.wasClean }),
+          emit({
+            connId,
+            url: redUrl,
+            kind: 'close',
+            code: e.code,
+            reason: e.reason || undefined,
+            wasClean: e.wasClean,
+            droppedFrames: droppedFrames || undefined,
+          }),
         );
         this.addEventListener('error', () => emit({ connId, url: redUrl, kind: 'error' }));
-        this.addEventListener('message', (e: MessageEvent) => {
-          const info = frameInfo(e.data, capture);
-          emit({ connId, url: redUrl, kind: 'message', dir: 'recv', ...info });
-          ctx.markActivity();
-        });
+        this.addEventListener('message', (e: MessageEvent) => emitFrame('recv', e.data));
 
         // Capture outgoing frames by shadowing send() on this instance. Call the
         // real send FIRST — if it throws (e.g. send() while CONNECTING) the error
@@ -98,9 +125,7 @@ export function instrumentWebSocket(ctx: InstrumentCtx): Teardown {
         this.send = (data: string | ArrayBufferLike | Blob | ArrayBufferView) => {
           origSend(data);
           try {
-            const info = frameInfo(data, capture);
-            emit({ connId, url: redUrl, kind: 'message', dir: 'send', ...info });
-            ctx.markActivity();
+            emitFrame('send', data);
           } catch {
             /* ignore capture errors */
           }