@sessionsight/insights 1.0.0

package/src/recorder.ts

@@ -0,0 +1,1396 @@
+import { record } from 'rrweb';
+import type { eventWithTime } from 'rrweb';
+import { WorkerBridge } from './worker-bridge.js';
+import { getRegistryValue } from '@sessionsight/sdk-shared';
+import type { SessionMetadata, RecordOptions, PrivacyConfig } from './types.js';
+
+const PRE_BUFFER_MAX_MS = 5_000;
+const FLAG_CHECK_INTERVAL_MS = 6_000;
+
+// rrweb EventType constants
+const META_EVENT_TYPE = 4;
+const CUSTOM_EVENT_TYPE = 5;
+// rrweb FullSnapshot type
+const FULL_SNAPSHOT_EVENT_TYPE = 2;
+// rrweb IncrementalSnapshot type
+const INCREMENTAL_SNAPSHOT_EVENT_TYPE = 3;
+// rrweb IncrementalSource.Mutation
+const MUTATION_SOURCE = 0;
+// rrweb serialized NodeType.Element
+const SERIALIZED_ELEMENT_TYPE = 2;
+
+// ── PII Detection & Redaction ─────────────────────────────────────
+// These patterns are always applied regardless of privacy mode or
+// data-ss-unmask. They cannot be overridden by the site owner.
+
+function luhnCheck(digits: string): boolean {
+  let sum = 0;
+  let alternate = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = parseInt(digits[i]!, 10);
+    if (alternate) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alternate = !alternate;
+  }
+  return sum % 10 === 0;
+}
+
+// Credit cards: 13-19 digit sequences (with optional spaces/dashes) validated by Luhn
+const CREDIT_CARD_RE = /\b(\d[\d\s\-]{11,22}\d)\b/g;
+
+// SSN: 3-2-4 digit pattern. Area number cannot be 000, 666, or 900-999.
+const SSN_RE = /\b(?!000|666|9\d\d)(\d{3})[- ]?(?!00)(\d{2})[- ]?(?!0000)(\d{4})\b/g;
+
+// Email addresses
+const EMAIL_RE = /\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b/g;
+
+// Phone numbers: US 10-digit (with optional +1 country code)
+const PHONE_US_RE = /(?:\+?1[\s.\-]?)?\(?\d{3}\)?[\s.\-]?\d{3}[\s.\-]?\d{4}\b/g;
+// International: +country code followed by 7-14 digits with optional separators
+const PHONE_INTL_RE = /\+\d{1,3}[\s.\-]\d[\d\s.\-]{6,16}\d\b/g;
+
+// IBAN: 2-letter country code + 2 check digits + up to 30 alphanumeric (with optional spaces/dashes)
+const IBAN_RE = /\b[A-Z]{2}\d{2}[\s\-]?[\dA-Z]{4}[\s\-]?(?:[\dA-Z]{4}[\s\-]?){1,7}[\dA-Z]{1,4}\b/g;
+
+// API keys and tokens from common providers
+const API_KEY_RE = /\b(?:sk-[A-Za-z0-9]{20,}|sk_(?:live|test)_[A-Za-z0-9]{20,}|pk_(?:live|test)_[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36,}|gho_[A-Za-z0-9]{36,}|AKIA[A-Z0-9]{16})\b/g;
+
+const REDACTED = '[REDACTED]';
+
+/**
+ * Redact all recognized PII patterns from text. This runs on every code path
+ * (including data-ss-unmask) so sensitive data never reaches the server.
+ */
+function redactPII(text: string): string {
+  // IBAN first: the numeric portion of an IBAN can look like a credit card
+  // to the Luhn check, so redact IBANs before credit cards to avoid partial matches.
+  text = text.replace(IBAN_RE, REDACTED);
+
+  // Credit cards (Luhn-validated)
+  text = text.replace(CREDIT_CARD_RE, (match) => {
+    const digits = match.replace(/[\s\-]/g, '');
+    if (digits.length >= 13 && digits.length <= 19 && luhnCheck(digits)) {
+      return REDACTED;
+    }
+    return match;
+  });
+
+  text = text.replace(SSN_RE, REDACTED);
+  text = text.replace(EMAIL_RE, REDACTED);
+  text = text.replace(PHONE_US_RE, REDACTED);
+  text = text.replace(PHONE_INTL_RE, (match) => {
+    const digits = match.replace(/\D/g, '');
+    // Must have 8-15 digits total (E.164 range) to avoid matching arbitrary number sequences
+    if (digits.length >= 8 && digits.length <= 15) return REDACTED;
+    return match;
+  });
+  text = text.replace(API_KEY_RE, REDACTED);
+
+  return text;
+}
+
+/**
+ * Width-class character mapping for proportional fonts.
+ * Characters are grouped by approximate rendered width in common sans-serif fonts.
+ * Scrambling swaps within the same width class to minimize layout drift.
+ */
+const WIDTH_CLASSES_LOWER: Record<string, string[]> = {
+  narrow: ['i', 'j', 'l'],
+  semiNarrow: ['f', 'r', 't'],
+  medium: ['a', 'b', 'c', 'd', 'e', 'g', 'h', 'k', 'n', 'o', 'p', 'q', 's', 'u', 'v', 'x', 'y', 'z'],
+  wide: ['m', 'w'],
+};
+
+const WIDTH_CLASSES_UPPER: Record<string, string[]> = {
+  narrow: ['I', 'J'],
+  semiNarrow: ['E', 'F', 'L', 'T'],
+  medium: ['A', 'B', 'C', 'D', 'G', 'H', 'K', 'N', 'O', 'P', 'Q', 'R', 'S', 'U', 'V', 'X', 'Y', 'Z'],
+  wide: ['M', 'W'],
+};
+
+// Build lookup: char -> array of same-width-class chars
+const SCRAMBLE_MAP = new Map<string, string[]>();
+for (const group of Object.values(WIDTH_CLASSES_LOWER)) {
+  for (const ch of group) SCRAMBLE_MAP.set(ch, group);
+}
+for (const group of Object.values(WIDTH_CLASSES_UPPER)) {
+  for (const ch of group) SCRAMBLE_MAP.set(ch, group);
+}
+
+/**
+ * Scramble text by replacing each character with another character of similar rendered width.
+ * Preserves whitespace, punctuation, and character count. Digits rotate within 0-9.
+ * This minimizes layout drift while ensuring no PII reaches the server.
+ */
+function scrambleText(text: string): string {
+  // Preserve [REDACTED] tokens inserted by redactPII so they stay readable.
+  if (text.includes(REDACTED)) {
+    return text.split(REDACTED).map(part => scrambleText(part)).join(REDACTED);
+  }
+
+  let result = '';
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+    const widthClass = SCRAMBLE_MAP.get(ch);
+    if (widthClass) {
+      // Pick a different character from the same width class
+      const idx = widthClass.indexOf(ch);
+      result += widthClass[(idx + 1) % widthClass.length]!;
+    } else {
+      const code = ch.charCodeAt(0);
+      if (code >= 48 && code <= 57) {
+        // Digits: rotate by 3
+        result += String.fromCharCode(48 + ((code - 48 + 3) % 10));
+      } else {
+        // Whitespace, punctuation, symbols, non-Latin: keep as-is
+        result += ch;
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Resolve the masking directive for an element by walking up to the nearest
+ * data-ss-mask / data-ss-unmask ancestor. Returns 'mask', 'unmask', or null
+ * (use privacy mode default).
+ */
+function resolveMaskDirective(element: HTMLElement | null): 'mask' | 'unmask' | null {
+  if (!element) return null;
+  const nearest = element.closest('[data-ss-mask], [data-ss-unmask]');
+  if (!nearest) return null;
+  return nearest.hasAttribute('data-ss-mask') ? 'mask' : 'unmask';
+}
+
+// ── Masking Cache ────────────────────────────────────────────────
+// Most text nodes on a page are static between snapshots. Caching the
+// masking result avoids re-running 7 PII regexes + char-by-char scrambling
+// on every 30s checkout and mutation batch.
+
+const MASK_CACHE_MAX = 4_000;
+const maskCache = new Map<string, string>();
+
+function maskCacheGet(key: string): string | undefined {
+  return maskCache.get(key);
+}
+
+function maskCachePut(key: string, value: string): void {
+  if (maskCache.size >= MASK_CACHE_MAX) {
+    // Evict oldest quarter of entries (Map iterates in insertion order)
+    const evictCount = MASK_CACHE_MAX / 4;
+    let i = 0;
+    for (const k of maskCache.keys()) {
+      if (i++ >= evictCount) break;
+      maskCache.delete(k);
+    }
+  }
+  maskCache.set(key, value);
+}
+
+function maskCacheClear(): void {
+  maskCache.clear();
+}
+
+/**
+ * Apply the privacy masking decision for a given DOM element.
+ * Checks data-ss-mask / data-ss-unmask on the element and its ancestors,
+ * then falls back to the privacy mode default. Results are cached by
+ * (text, directive, privacyMode) to avoid redundant regex + scramble work.
+ */
+function applyMasking(text: string, element: HTMLElement | null, privacyMode: string): string {
+  const directive = resolveMaskDirective(element);
+  const cacheKey = `${directive ?? 'd'}:${privacyMode}:${text}`;
+  const cached = maskCacheGet(cacheKey);
+  if (cached !== undefined) return cached;
+
+  // Always redact PII first, before any other masking. This ensures sensitive
+  // patterns are caught even when text is about to be scrambled.
+  let result = redactPII(text);
+
+  if (directive === 'mask') {
+    result = scrambleText(result);
+  } else if (directive === 'unmask') {
+    // result already has PII redacted, no scramble needed
+  } else if (privacyMode === 'default') {
+    result = scrambleText(result);
+  }
+
+  maskCachePut(cacheKey, result);
+  return result;
+}
+
+// ── Serialized Event Placeholder Masking ──────────────────────────
+
+type SerializedNode = {
+  type: number;
+  tagName?: string;
+  attributes?: Record<string, any>;
+  childNodes?: SerializedNode[];
+  id?: number;
+};
+
+const PLACEHOLDER_INPUT_TAGS = new Set(['input', 'textarea']);
+
+/**
+ * Recursively walk a serialized rrweb node tree and scramble placeholder
+ * attributes on input/textarea elements. Respects data-ss-mask / data-ss-unmask
+ * attributes on the element itself and inherited from ancestor nodes.
+ *
+ * @param maskState - inherited masking: 'mask', 'unmask', or null (use mode default)
+ */
+function scramblePlaceholders(
+  node: SerializedNode,
+  privacyMode: string,
+  maskState: 'mask' | 'unmask' | null,
+): void {
+  if (node.type === SERIALIZED_ELEMENT_TYPE) {
+    // Update inherited mask state if this element has a data-ss attribute
+    const attrs = node.attributes;
+    if (attrs) {
+      if ('data-ss-unmask' in attrs) maskState = 'unmask';
+      else if ('data-ss-mask' in attrs) maskState = 'mask';
+    }
+
+    // Scramble placeholder if this is an input/textarea
+    if (attrs && PLACEHOLDER_INPUT_TAGS.has(node.tagName!) && typeof attrs.placeholder === 'string' && attrs.placeholder) {
+      // Always redact PII in placeholders
+      attrs.placeholder = redactPII(attrs.placeholder);
+      const shouldScramble =
+        maskState === 'mask' ||
+        (maskState !== 'unmask' && privacyMode === 'default');
+      if (shouldScramble) {
+        attrs.placeholder = scrambleText(attrs.placeholder);
+      }
+    }
+  }
+
+  // Recurse into children for all node types (Document, Element, etc.)
+  if (node.childNodes) {
+    for (const child of node.childNodes) {
+      scramblePlaceholders(child, privacyMode, maskState);
+    }
+  }
+}
+
+/**
+ * Process an rrweb event to scramble placeholder attributes on serialized
+ * input/textarea nodes. Handles FullSnapshot and IncrementalSnapshot (Mutation adds
+ * and attribute changes).
+ */
+function maskEventPlaceholders(event: eventWithTime, privacyMode: string): void {
+  // FullSnapshot: walk the entire serialized DOM tree
+  if (event.type === FULL_SNAPSHOT_EVENT_TYPE) {
+    const data = event.data as { node?: SerializedNode };
+    if (data.node) scramblePlaceholders(data.node, privacyMode, null);
+    return;
+  }
+
+  // IncrementalSnapshot with Mutation source: walk added nodes and attribute changes
+  if (event.type === INCREMENTAL_SNAPSHOT_EVENT_TYPE) {
+    const data = event.data as { source?: number; adds?: { node: SerializedNode }[]; attributes?: { id: number; attributes: Record<string, any> }[] };
+    if (data.source !== MUTATION_SOURCE) return;
+
+    // Added nodes can contain input/textarea with placeholders
+    if (data.adds) {
+      for (const add of data.adds) {
+        scramblePlaceholders(add.node, privacyMode, null);
+      }
+    }
+
+    // Attribute mutations can set placeholder directly
+    if (data.attributes) {
+      for (const attr of data.attributes) {
+        if (typeof attr.attributes.placeholder === 'string' && attr.attributes.placeholder) {
+          attr.attributes.placeholder = redactPII(attr.attributes.placeholder);
+          const shouldScramble = privacyMode === 'default';
+          if (shouldScramble) {
+            attr.attributes.placeholder = scrambleText(attr.attributes.placeholder);
+          }
+        }
+      }
+    }
+  }
+}
+
+// ── Page Exclusion Pattern Matching ────────────────────────────────
+
+function globToRegex(pattern: string): RegExp | null {
+  try {
+    // Escape regex special chars except *, then convert * to .*
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const regexStr = '^' + escaped.replace(/\*/g, '.*') + '$';
+    return new RegExp(regexStr);
+  } catch (e) {
+    console.warn('SessionSight: invalid excludePages pattern', pattern, e);
+    return null;
+  }
+}
+
+function matchesAnyPattern(path: string, patterns: RegExp[]): boolean {
+  for (const regex of patterns) {
+    if (regex.test(path)) return true;
+  }
+  return false;
+}
+
+export class Recorder {
+  private bridge: WorkerBridge;
+  private visitorId: string;
+  private preBuffer: eventWithTime[] = [];
+  private isRecording = false;
+  private stopRrweb: (() => void) | null = null;
+  private userId: string | null = null;
+  private userProperties: Record<string, string | number | boolean> = {};
+  private userPropertiesDirty = false;
+  private lastHref: string = '';
+  private lastEmittedFlagToken: string | null = null;
+  private flagCheckTimer: ReturnType<typeof setInterval> | null = null;
+  private origPushState: typeof history.pushState | null = null;
+  private origReplaceState: typeof history.replaceState | null = null;
+
+  // Form tracking state
+  private formStarted = new Set<string>();
+  private formStartTimestamps = new Map<string, number>();
+  private focusTimestamps = new Map<string, number>();
+
+  // Heatmap tracking state
+  private lastMouseMoveEmit = 0;
+
+  // Frustration signal: excessive scrolling
+  private scrollHistory: Array<{ y: number; t: number; dir: 'up' | 'down' }> = [];
+  private lastScrollDirection: 'up' | 'down' | null = null;
+  private lastScrollY = 0;
+
+  // Frustration signal: form field retries
+  private fieldFocusCounts = new Map<string, number[]>();
+
+  // Frustration signal: idle detection
+  private lastInteractionTime = 0;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private idleEmitted = false;
+  private static readonly IDLE_THRESHOLD_MS = 30_000;
+
+  // Error deduplication state
+  private lastErrorMessage = '';
+  private lastErrorTime = 0;
+
+  // Scroll depth tracking via IntersectionObserver sentinels
+  private static readonly SCROLL_DEPTH_THRESHOLDS = [25, 50, 75, 100];
+  private scrollDepthHits = new Set<number>();
+  private scrollSentinels: HTMLElement[] = [];
+  private scrollDepthObserver: IntersectionObserver | null = null;
+
+  // Delayed "settled" snapshot to capture fully-rendered page (after async content loads)
+  private settledSnapshotTimer: ReturnType<typeof setTimeout> | null = null;
+  private static readonly SETTLED_SNAPSHOT_DELAY_MS = 3_000;
+
+  // Tab visibility session lifecycle
+  private hiddenAt: number | null = null;
+  private static readonly VISIBILITY_GRACE_MS = 120_000; // 2 minutes
+  public endedByVisibility = false;
+  private isHidden = false;
+
+  private propertyId: string;
+  private privacyMode: 'default' | 'relaxed';
+  private excludePagePatterns: RegExp[];
+  private isPaused = false;
+
+  constructor(bridge: WorkerBridge, propertyId: string, visitorId: string, options?: { privacyMode?: 'default' | 'relaxed'; excludePages?: string[] }) {
+    this.bridge = bridge;
+    this.propertyId = propertyId;
+    this.visitorId = visitorId;
+    this.privacyMode = options?.privacyMode ?? 'default';
+    this.excludePagePatterns = (options?.excludePages ?? []).map(globToRegex).filter((r): r is RegExp => r !== null);
+
+    // Stop recording if the transport is killed (invalid API key, etc.)
+    this.bridge.onKilled(() => {
+      this.preBuffer = [];
+      this.isRecording = false;
+      if (this.stopRrweb) { this.stopRrweb(); this.stopRrweb = null; }
+    });
+  }
+
+  start(autoRecord: boolean): void {
+    try {
+      this.lastHref = window.location.href;
+
+      const initialPageExcluded = this.excludePagePatterns.length > 0 &&
+        matchesAnyPattern(window.location.pathname, this.excludePagePatterns);
+
+      // Set recording state BEFORE starting rrweb so the initial FullSnapshot
+      // goes to the bridge (not the preBuffer) when autoRecord is on.
+      if (autoRecord) {
+        this.isRecording = true;
+        this.bridge.postMetadata(this.collectMetadata());
+      }
+
+      // Always start rrweb — events go to either buffer or preBuffer.
+      // rrweb's record() emits its own Meta event (type 4) with href,
+      // so the initial page automatically appears in the pages list.
+      // Do NOT emit a second Meta event here — it would land after the
+      // FullSnapshot in the buffer, causing discardPriorSnapshots() to
+      // skip the FullSnapshot on backward seeks and break replay.
+      this.startRrweb();
+
+      // If the initial page is excluded, emit the placeholder event after rrweb
+      // has started (so the session has a valid FullSnapshot), then pause.
+      if (initialPageExcluded) {
+        this.emitCustomEvent('ss-page-excluded', { href: window.location.href });
+        this.bridge.flush();
+        this.isPaused = true;
+      }
+
+      // Track SPA navigations
+      this.patchHistoryMethods();
+      window.addEventListener('popstate', this.handleNavigation);
+
+      // Track user interactions
+      document.addEventListener('click', this.handleClick, true);
+      document.addEventListener('submit', this.handleFormSubmit, true);
+      document.addEventListener('focusin', this.handleFieldFocus, true);
+      document.addEventListener('focusout', this.handleFieldBlur, true);
+
+      // Heatmap tracking
+      document.addEventListener('click', this.handleHeatmapClick, true);
+      document.addEventListener('mousemove', this.handleHeatmapMouseMove, { capture: true, passive: true });
+      window.addEventListener('scroll', this.handleHeatmapScroll, { capture: true, passive: true });
+
+      // Scroll depth tracking via IntersectionObserver (replaces per-frame scroll checks)
+      this.setupScrollDepthObserver();
+
+      // Error tracking
+      window.addEventListener('error', this.handleWindowError);
+      window.addEventListener('unhandledrejection', this.handleUnhandledRejection);
+
+      // Idle detection
+      document.addEventListener('keydown', this.handleKeydown, true);
+      this.lastInteractionTime = Date.now();
+      this.resetIdleTimer();
+
+      document.addEventListener('visibilitychange', this.handleVisibilityChange);
+      window.addEventListener('beforeunload', this.handleBeforeUnload);
+
+      // Periodically check for flag evaluation tokens (cross-SDK registry lives on main thread)
+      this.flagCheckTimer = setInterval(() => this.checkFlagToken(), FLAG_CHECK_INTERVAL_MS);
+    } catch (e) {
+      // SDK must never break the host page
+      console.warn('SessionSight: failed to start recorder', e);
+    }
+  }
+
+  /** Start persisting events to the server. Call after init({ autoRecord: false }). */
+  beginRecording(options?: RecordOptions): void {
+    if (this.isRecording) return;
+
+    this.isRecording = true;
+
+    // Send metadata to the worker/bridge
+    this.bridge.postMetadata(this.collectMetadata());
+
+    // Drain pre-buffer: send kept events to the bridge
+    const preRecordSecs = Math.min(5, Math.max(0, options?.preRecordSecs || 0));
+    if (preRecordSecs > 0 && this.preBuffer.length > 0) {
+      const cutoff = Date.now() - preRecordSecs * 1000;
+      for (const e of this.preBuffer) {
+        if (e.timestamp >= cutoff) this.bridge.postEvent(e);
+      }
+    }
+    this.preBuffer = [];
+
+    // Trigger immediate flush so the first batch goes out
+    this.bridge.flush();
+  }
+
+  stop(): void {
+    if (this.settledSnapshotTimer) {
+      clearTimeout(this.settledSnapshotTimer);
+      this.settledSnapshotTimer = null;
+    }
+    if (this.flagCheckTimer) {
+      clearInterval(this.flagCheckTimer);
+      this.flagCheckTimer = null;
+    }
+    this.hiddenAt = null;
+    this.isHidden = false;
+    if (this.stopRrweb) {
+      this.stopRrweb();
+      this.stopRrweb = null;
+    }
+
+    this.unpatchHistoryMethods();
+    window.removeEventListener('popstate', this.handleNavigation);
+
+    document.removeEventListener('click', this.handleClick, true);
+    document.removeEventListener('submit', this.handleFormSubmit, true);
+    document.removeEventListener('focusin', this.handleFieldFocus, true);
+    document.removeEventListener('focusout', this.handleFieldBlur, true);
+
+    document.removeEventListener('click', this.handleHeatmapClick, true);
+    document.removeEventListener('mousemove', this.handleHeatmapMouseMove, { capture: true } as EventListenerOptions);
+    window.removeEventListener('scroll', this.handleHeatmapScroll, { capture: true } as EventListenerOptions);
+    this.teardownScrollDepthObserver();
+
+    window.removeEventListener('error', this.handleWindowError);
+    window.removeEventListener('unhandledrejection', this.handleUnhandledRejection);
+
+    document.removeEventListener('keydown', this.handleKeydown, true);
+    if (this.idleTimer) { clearTimeout(this.idleTimer); this.idleTimer = null; }
+
+    document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+    window.removeEventListener('beforeunload', this.handleBeforeUnload);
+
+    if (this.isRecording) {
+      this.bridge.flush();
+    }
+    this.isRecording = false;
+    this.bridge.destroy();
+    maskCacheClear();
+  }
+
+  getVisitorId(): string {
+    return this.visitorId;
+  }
+
+  getBridge(): WorkerBridge {
+    return this.bridge;
+  }
+
+  getPropertyId(): string {
+    return this.propertyId;
+  }
+
+  identify(userId: string, properties?: Record<string, string | number | boolean>): void {
+    this.userId = userId;
+    this.bridge.postIdentify(userId, properties);
+    if (properties) {
+      Object.assign(this.userProperties, properties);
+      this.userPropertiesDirty = true;
+      this.emitCustomEvent('set_user_properties', { ...properties });
+    }
+  }
+
+  /**
+   * Apply server-delivered privacy configuration. If settings differ from the
+   * current defaults, update the recorder and trigger a fresh FullSnapshot so
+   * replay uses the correct masking from this point forward.
+   */
+  applyPrivacyConfig(config: PrivacyConfig): void {
+    const modeChanged = config.privacyMode !== this.privacyMode;
+
+    // Update internal state from the server config
+    this.privacyMode = config.privacyMode;
+    this.excludePagePatterns = (config.excludePages ?? []).map(globToRegex).filter((r): r is RegExp => r !== null);
+
+    // Re-evaluate page exclusion with the new patterns
+    const shouldExclude = this.excludePagePatterns.length > 0 &&
+      matchesAnyPattern(window.location.pathname, this.excludePagePatterns);
+
+    if (shouldExclude && !this.isPaused) {
+      this.bridge.flush();
+      this.emitCustomEvent('ss-page-excluded', { href: window.location.href });
+      this.bridge.flush();
+      this.isPaused = true;
+    } else if (!shouldExclude && this.isPaused) {
+      this.isPaused = false;
+    }
+
+    // If the privacy mode changed, restart rrweb for a new FullSnapshot with correct masking
+    if (modeChanged && !this.isPaused) {
+      if (this.stopRrweb) this.stopRrweb();
+      this.startRrweb();
+    }
+  }
+
+  // ── rrweb lifecycle ────────────────────────────────────────────────
+
+  /**
+   * Stamp fixed dimensions onto data-ss-exclude elements so that when rrweb
+   * replaces them with empty placeholders (via blockSelector), the placeholders
+   * preserve the original layout space.
+   */
+  private stampExcludedDimensions(): void {
+    const excluded = document.querySelectorAll('[data-ss-exclude]');
+    for (const el of excluded) {
+      const htmlEl = el as HTMLElement;
+      // Skip if already stamped
+      if (htmlEl.style.getPropertyValue('--ss-stamped')) continue;
+      const rect = htmlEl.getBoundingClientRect();
+      htmlEl.style.setProperty('width', rect.width + 'px', 'important');
+      htmlEl.style.setProperty('height', rect.height + 'px', 'important');
+      htmlEl.style.setProperty('min-height', rect.height + 'px', 'important');
+      htmlEl.style.setProperty('box-sizing', 'border-box', 'important');
+      htmlEl.style.setProperty('--ss-stamped', '1');
+    }
+  }
+
+  private startRrweb(): void {
+    try {
+      const privacyMode = this.privacyMode;
+
+      // Stamp dimensions on excluded elements before rrweb starts.
+      // rrweb's blockSelector replaces these with empty <div> placeholders,
+      // but the inline width/height styles are preserved on the placeholder,
+      // so the layout space is maintained.
+      this.stampExcludedDimensions();
+
+      this.stopRrweb = record({
+        emit: (event: eventWithTime) => {
+          try {
+            // Scramble placeholder attributes in serialized nodes before buffering
+            maskEventPlaceholders(event, privacyMode);
+            this.pushEvent(event);
+          } catch (e) {
+            console.warn('SessionSight: error in rrweb emit callback', e);
+          }
+        },
+        // Take a full DOM snapshot every 30s so the replayer can seek without
+        // replaying every mutation from the start of the session.
+        checkoutEveryNms: 30_000,
+        // Default is 100ms (10fps) which makes scroll replay choppy.
+        sampling: { scroll: 50 },
+        inlineStylesheet: true,
+
+        // Replace excluded elements with empty placeholders (preserves inline styles)
+        blockSelector: '[data-ss-exclude]',
+
+        // Mask all input values, with custom logic respecting data-ss attributes
+        maskAllInputs: true,
+        maskInputFn: (text: string, element: HTMLElement): string => {
+          try {
+            return applyMasking(text, element, privacyMode);
+          } catch (e) {
+            console.warn('SessionSight: error in maskInputFn', e);
+            return text;
+          }
+        },
+
+        // Fire maskTextFn for every text node.
+        maskTextSelector: '*',
+        maskTextFn: (text: string, element: HTMLElement | null): string => {
+          try {
+            return applyMasking(text, element, privacyMode);
+          } catch (e) {
+            console.warn('SessionSight: error in maskTextFn', e);
+            return text;
+          }
+        },
+      }) ?? null;
+
+      this.scheduleSettledSnapshot();
+    } catch (e) {
+      console.warn('SessionSight: failed to start rrweb', e);
+    }
+  }
+
+  /**
+   * Schedule a delayed FullSnapshot to capture the page after async content
+   * has loaded (lazy images, client-rendered components, etc.). This gives
+   * the heatmap a much better baseline than the immediate rrweb snapshot.
+   */
+  private scheduleSettledSnapshot(): void {
+    if (this.settledSnapshotTimer) clearTimeout(this.settledSnapshotTimer);
+    this.settledSnapshotTimer = setTimeout(() => {
+      this.settledSnapshotTimer = null;
+      if (this.stopRrweb && !this.isPaused) record.takeFullSnapshot();
+    }, Recorder.SETTLED_SNAPSHOT_DELAY_MS);
+  }
+
+  /** Route an event to the bridge or pre-buffer */
+  private pushEvent(event: eventWithTime): void {
+    // When paused due to page exclusion, drop all events
+    if (this.isPaused) return;
+
+    // Drop events while tab is hidden so background mutations don't inflate
+    // lastEventAt on the server. The session will either resume or end when
+    // the tab becomes visible again.
+    if (this.isHidden) return;
+
+    if (this.isRecording) {
+      this.bridge.postEvent(event);
+      // Flush FullSnapshot immediately so replay data survives early bounces
+      if (event.type === FULL_SNAPSHOT_EVENT_TYPE) {
+        this.bridge.flush();
+      }
+    } else {
+      // Pre-buffer: keep last 5 seconds
+      this.preBuffer.push(event);
+      this.trimPreBuffer();
+    }
+  }
+
+  /** Trim pre-buffer to keep only the last 5 seconds of events */
+  private trimPreBuffer(): void {
+    if (this.preBuffer.length === 0) return;
+    const cutoff = Date.now() - PRE_BUFFER_MAX_MS;
+    // Find first event that's within the window
+    let firstValid = 0;
+    while (firstValid < this.preBuffer.length && this.preBuffer[firstValid]!.timestamp < cutoff) {
+      firstValid++;
+    }
+    if (firstValid > 0) {
+      this.preBuffer.splice(0, firstValid);
+    }
+  }
+
+  // ── Custom event helpers ───────────────────────────────────────────
+
+  private emitCustomEvent(tag: string, payload: Record<string, any>): void {
+    const event: eventWithTime = {
+      type: CUSTOM_EVENT_TYPE,
+      data: { tag, payload },
+      timestamp: Date.now(),
+    };
+    this.pushEvent(event);
+  }
+
+  // ── Form identification ────────────────────────────────────────────
+
+  private static readonly INPUT_SELECTOR = 'input:not([type="hidden"]):not([type="submit"]):not([type="button"]), textarea, select';
+
+  /** Find the nearest grouping container: <form>, [data-ss-form], or null (page-level). */
+  private getFormContainer(target: HTMLElement): HTMLElement | null {
+    return target.closest('form') || target.closest('[data-ss-form]');
+  }
+
+  private getFormInfo(container: HTMLElement | null): { formId: string; formName: string } {
+    const page = window.location.pathname;
+
+    if (!container) {
+      return { formId: `${page}:_page`, formName: page };
+    }
+
+    if (container.tagName === 'FORM') {
+      const allForms = Array.from(document.querySelectorAll('form'));
+      const index = allForms.indexOf(container as HTMLFormElement);
+      const indexStr = index >= 0 ? String(index) : '0';
+      const formId = `${page}:${container.id || indexStr}`;
+      const dataName = container.getAttribute('data-ss-form');
+      const formName = dataName || container.id || `Form ${index + 1}`;
+      return { formId, formName };
+    }
+
+    // [data-ss-form] container
+    const dataName = container.getAttribute('data-ss-form')!;
+    const formId = `${page}:${container.id || dataName}`;
+    return { formId, formName: dataName };
+  }
+
+  private getFieldInfo(el: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement, container: HTMLElement | null) {
+    const scope = container || document;
+    const inputs = Array.from(scope.querySelectorAll(Recorder.INPUT_SELECTOR));
+    const index = inputs.indexOf(el);
+    const fieldId = el.id || el.name || `field-${index}`;
+    const fieldName = el.name || el.id || `field-${index}`;
+    const fieldType = el.tagName === 'SELECT' ? 'select' : el.tagName === 'TEXTAREA' ? 'textarea' : (el as HTMLInputElement).type || 'text';
+
+    let fieldLabel = '';
+    if (el.id) {
+      const label = document.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+      if (label) fieldLabel = (label.textContent?.trim() || '').slice(0, 50);
+    }
+    if (!fieldLabel) {
+      const parent = el.closest('label');
+      if (parent) {
+        const clone = parent.cloneNode(true) as HTMLElement;
+        clone.querySelectorAll('input, textarea, select').forEach(c => c.remove());
+        fieldLabel = (clone.textContent?.trim() || '').slice(0, 50);
+      }
+    }
+    if (!fieldLabel) {
+      fieldLabel = el.getAttribute('placeholder')?.slice(0, 50) || fieldName;
+    }
+
+    return { fieldId, fieldName, fieldType, fieldLabel };
+  }
+
+  // ── Field focus/blur tracking ──────────────────────────────────────
+
+  private handleFieldFocus = (e: FocusEvent): void => {
+    try {
+      const target = e.target as HTMLElement;
+      if (!target) return;
+      if (!target.matches(Recorder.INPUT_SELECTOR)) return;
+
+      const container = this.getFormContainer(target);
+      const { formId, formName } = this.getFormInfo(container);
+      const field = this.getFieldInfo(target as HTMLInputElement, container);
+      const page = window.location.pathname;
+
+      if (!this.formStarted.has(formId)) {
+        this.formStarted.add(formId);
+        this.formStartTimestamps.set(formId, Date.now());
+        const scope = container || document;
+        const inputs = scope.querySelectorAll(Recorder.INPUT_SELECTOR);
+        this.emitCustomEvent('form_start', { formId, formName, page, fieldCount: inputs.length });
+      }
+
+      const focusKey = `${formId}:${field.fieldId}`;
+      this.focusTimestamps.set(focusKey, Date.now());
+      this.emitCustomEvent('field_focus', { formId, formName, page, ...field });
+
+      // Frustration signal: detect repeated field focus (form field retries)
+      const now = Date.now();
+      const focusTimes = this.fieldFocusCounts.get(focusKey) || [];
+      focusTimes.push(now);
+      // Keep only entries within 30 seconds
+      const retryCutoff = now - 30_000;
+      const recent = focusTimes.filter(t => t >= retryCutoff);
+      this.fieldFocusCounts.set(focusKey, recent);
+      if (recent.length >= 3) {
+        this.emitCustomEvent('form_field_retry', { formName, fieldName: field.fieldName, page, retries: recent.length });
+        this.fieldFocusCounts.set(focusKey, []);
+      }
+
+      // Reset idle timer on interaction
+      this.resetIdleTimer();
+    } catch (e2) {
+      console.warn('SessionSight: error in field focus handler', e2);
+    }
+  };
+
+  private handleFieldBlur = (e: FocusEvent): void => {
+    try {
+      const target = e.target as HTMLElement;
+      if (!target) return;
+      if (!target.matches(Recorder.INPUT_SELECTOR)) return;
+
+      const container = this.getFormContainer(target);
+      const { formId, formName } = this.getFormInfo(container);
+      const field = this.getFieldInfo(target as HTMLInputElement, container);
+      const page = window.location.pathname;
+
+      const focusKey = `${formId}:${field.fieldId}`;
+      const focusTime = this.focusTimestamps.get(focusKey);
+      const timeSpent = focusTime ? Date.now() - focusTime : 0;
+      this.focusTimestamps.delete(focusKey);
+
+      const el = target as HTMLInputElement;
+      let hasValue = false;
+      if (el.type === 'checkbox' || el.type === 'radio') hasValue = el.checked;
+      else hasValue = (el.value || '').trim().length > 0;
+
+      this.emitCustomEvent('field_blur', { formId, formName, page, ...field, timeSpent, hasValue });
+    } catch (e2) {
+      console.warn('SessionSight: error in field blur handler', e2);
+    }
+  };
+
+  // ── Click tracking ─────────────────────────────────────────────────
+
+  private handleClick = (e: MouseEvent): void => {
+    try {
+      const target = e.target as HTMLElement;
+      if (!target) return;
+      const el = target.closest('button, a, [role="button"], input[type="submit"], input[type="button"]') as HTMLElement | null;
+      if (!el) return;
+      const label = this.getElementLabel(el) || el.tagName.toLowerCase();
+
+      let href: string | undefined;
+      try {
+        const rawHref = (el as HTMLAnchorElement).href;
+        if (rawHref) href = new URL(rawHref, window.location.origin).pathname;
+      } catch {
+        // Malformed href, skip it
+      }
+
+      this.emitCustomEvent('click', {
+        label,
+        tag: el.tagName.toLowerCase(),
+        page: window.location.pathname,
+        href,
+      });
+    } catch (e) {
+      console.warn('SessionSight: error in click handler', e);
+    }
+  };
+
+  private getElementLabel(el: HTMLElement): string | null {
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel) return ariaLabel.slice(0, 80);
+    const text = el.textContent?.trim();
+    if (text && text.length <= 80) return text;
+    if (text) return text.slice(0, 77) + '...';
+    const title = el.getAttribute('title');
+    if (title) return title.slice(0, 80);
+    if (el.tagName === 'INPUT') {
+      const val = (el as HTMLInputElement).value;
+      if (val) return val.slice(0, 80);
+    }
+    return null;
+  }
+
+  // ── Form submit tracking ───────────────────────────────────────────
+
+  private handleFormSubmit = (e: Event): void => {
+    try {
+      const form = e.target as HTMLFormElement;
+      if (!form || form.tagName !== 'FORM') return;
+      const { formId, formName } = this.getFormInfo(form);
+      const page = window.location.pathname;
+      const inputs = form.querySelectorAll(Recorder.INPUT_SELECTOR);
+      const filledFields = Array.from(inputs).filter((input) => {
+        const el = input as HTMLInputElement;
+        if (el.type === 'checkbox' || el.type === 'radio') return el.checked;
+        return el.value.trim().length > 0;
+      }).length;
+      const startTime = this.formStartTimestamps.get(formId);
+      const timeToComplete = startTime ? Date.now() - startTime : 0;
+      this.emitCustomEvent('form_submit', { formId, formName, page, totalFields: inputs.length, filledFields, timeToComplete });
+    } catch (e2) {
+      console.warn('SessionSight: error in form submit handler', e2);
+    }
+  };
+
+  // ── Heatmap tracking ───────────────────────────────────────────────
+
+  private static readonly INTERACTIVE_SELECTOR = [
+    'a', 'button', 'select', 'textarea',
+    'input', 'label', 'summary', 'details',
+    '[role="button"]', '[role="link"]', '[role="tab"]',
+    '[role="radio"]', '[role="checkbox"]', '[role="option"]',
+    '[role="menuitem"]', '[role="switch"]', '[role="slider"]',
+    '[tabindex]', '[onclick]', '[data-action]',
+  ].join(', ');
+
+  private static readonly DEAD_CLICK_DEFER_MS = 400;
+
+  private handleHeatmapClick = (e: MouseEvent): void => {
+    try {
+      const target = e.target as HTMLElement | null;
+      // Walk up to find the nearest interactive ancestor
+      const interactive = target?.closest(Recorder.INTERACTIVE_SELECTOR) as HTMLElement | null;
+      const el = interactive || target;
+      const tagName = el?.tagName?.toLowerCase() || '';
+      const text = (el?.textContent || '').trim().slice(0, 100);
+      const href = (el as HTMLAnchorElement)?.href || '';
+
+      const clickData = {
+        x: Math.round((e.clientX / window.innerWidth) * 10000) / 100,
+        y: Math.round(((e.clientY + window.scrollY) / document.documentElement.scrollHeight) * 10000) / 100,
+        documentHeight: document.documentElement.scrollHeight,
+        viewportX: e.clientX,
+        viewportY: e.clientY,
+        page: window.location.pathname,
+        elementTag: tagName,
+        elementText: text,
+        elementHref: href,
+        isInteractive: true,
+      };
+
+      // If the element is clearly interactive, emit immediately
+      if (interactive) {
+        this.emitCustomEvent('mouse_click', clickData);
+      } else {
+        // Defer: watch for DOM mutations or URL changes that indicate the click did something
+        this.deferDeadClickCheck(clickData);
+      }
+
+      // Reset idle timer on click
+      this.resetIdleTimer();
+    } catch (e2) {
+      console.warn('SessionSight: error in heatmap click handler', e2);
+    }
+  };
+
+  private deferDeadClickCheck(clickData: Record<string, any>): void {
+    const startUrl = window.location.href;
+    let sawMutation = false;
+
+    // document.body can be null in edge cases (e.g. early script execution)
+    const observeTarget = document.body || document.documentElement;
+    if (!observeTarget) {
+      clickData.isInteractive = false;
+      this.emitCustomEvent('mouse_click', clickData);
+      return;
+    }
+
+    const observer = new MutationObserver(() => { sawMutation = true; });
+    try {
+      observer.observe(observeTarget, { childList: true, subtree: true });
+    } catch (e) {
+      console.warn('SessionSight: error observing mutations', e);
+      clickData.isInteractive = false;
+      this.emitCustomEvent('mouse_click', clickData);
+      return;
+    }
+
+    setTimeout(() => {
+      observer.disconnect();
+      const urlChanged = window.location.href !== startUrl;
+      clickData.isInteractive = sawMutation || urlChanged;
+      this.emitCustomEvent('mouse_click', clickData);
+    }, Recorder.DEAD_CLICK_DEFER_MS);
+  }
+
+  private handleHeatmapMouseMove = (e: MouseEvent): void => {
+    try {
+      const now = Date.now();
+      // Reset idle timer on mouse move (cheap check, no timeout reset every move)
+      if (now - this.lastInteractionTime > 5000) this.resetIdleTimer();
+      if (now - this.lastMouseMoveEmit < 500) return;
+      this.lastMouseMoveEmit = now;
+      this.emitCustomEvent('mouse_move', {
+        x: Math.round((e.clientX / window.innerWidth) * 10000) / 100,
+        y: Math.round(((e.clientY + window.scrollY) / document.documentElement.scrollHeight) * 10000) / 100,
+        documentHeight: document.documentElement.scrollHeight,
+        page: window.location.pathname,
+      });
+    } catch (e2) {
+      console.warn('SessionSight: error in mousemove handler', e2);
+    }
+  };
+
+  private handleHeatmapScroll = (): void => {
+    try {
+      const now = Date.now();
+      const scrollY = window.scrollY;
+
+      // Detect excessive scrolling: rapid direction changes
+      if (this.lastScrollY !== 0) {
+        const dir: 'up' | 'down' = scrollY > this.lastScrollY ? 'down' : 'up';
+        if (dir !== this.lastScrollDirection && this.lastScrollDirection !== null) {
+          this.scrollHistory.push({ y: scrollY, t: now, dir });
+          // Keep only entries within 3 seconds
+          const cutoff = now - 3000;
+          while (this.scrollHistory.length > 0 && this.scrollHistory[0]!.t < cutoff) {
+            this.scrollHistory.shift();
+          }
+          // 4+ direction reversals in 3s = excessive scrolling
+          if (this.scrollHistory.length >= 4) {
+            this.emitCustomEvent('excessive_scroll', { page: window.location.pathname, count: this.scrollHistory.length });
+            this.scrollHistory = [];
+          }
+        }
+        this.lastScrollDirection = dir;
+      }
+      this.lastScrollY = scrollY;
+
+      // Reset idle timer on scroll
+      this.resetIdleTimer();
+    } catch (e) {
+      console.warn('SessionSight: error in scroll handler', e);
+    }
+  };
+
+  // ── Scroll depth via IntersectionObserver ──────────────────────────
+
+  private setupScrollDepthObserver(): void {
+    this.teardownScrollDepthObserver();
+
+    if (typeof IntersectionObserver === 'undefined') return;
+
+    this.scrollDepthObserver = new IntersectionObserver((entries) => {
+      try {
+        for (const entry of entries) {
+          if (!entry.isIntersecting) continue;
+          const threshold = Number((entry.target as HTMLElement).dataset.ssDepth);
+          if (isNaN(threshold) || this.scrollDepthHits.has(threshold)) continue;
+
+          this.scrollDepthHits.add(threshold);
+          const scrollY = window.scrollY;
+          const maxScrollY = Math.max(1, document.documentElement.scrollHeight - window.innerHeight);
+          this.emitCustomEvent('scroll_depth', {
+            scrollY,
+            maxScrollY,
+            scrollPercent: threshold,
+            viewportHeight: window.innerHeight,
+            page: window.location.pathname,
+          });
+
+          // Take a FullSnapshot at 25/50/75% to capture reveal-on-scroll content
+          if (threshold < 100 && this.stopRrweb && !this.isPaused) {
+            record.takeFullSnapshot();
+          }
+
+          // Unobserve this sentinel since it already fired
+          this.scrollDepthObserver?.unobserve(entry.target);
+        }
+      } catch (e) {
+        console.warn('SessionSight: error in scroll depth observer', e);
+      }
+    }, { threshold: 0 });
+
+    this.placeSentinels();
+  }
+
+  private placeSentinels(): void {
+    // Remove existing sentinels before placing new ones
+    for (const el of this.scrollSentinels) el.remove();
+    this.scrollSentinels = [];
+
+    const docHeight = document.documentElement.scrollHeight;
+    for (const pct of Recorder.SCROLL_DEPTH_THRESHOLDS) {
+      if (this.scrollDepthHits.has(pct)) continue;
+      const sentinel = document.createElement('div');
+      sentinel.dataset.ssDepth = String(pct);
+      sentinel.setAttribute('aria-hidden', 'true');
+      sentinel.style.cssText = 'position:absolute;left:0;width:1px;height:1px;pointer-events:none;opacity:0;z-index:-1;';
+      // Place at the % offset from top. 100% = bottom of the document.
+      sentinel.style.top = `${Math.min(docHeight - 1, (pct / 100) * docHeight)}px`;
+      document.documentElement.appendChild(sentinel);
+      this.scrollSentinels.push(sentinel);
+      this.scrollDepthObserver?.observe(sentinel);
+    }
+  }
+
+  private teardownScrollDepthObserver(): void {
+    if (this.scrollDepthObserver) {
+      this.scrollDepthObserver.disconnect();
+      this.scrollDepthObserver = null;
+    }
+    for (const el of this.scrollSentinels) el.remove();
+    this.scrollSentinels = [];
+  }
+
+  // ── Error tracking ───────────────────────────────────────────────
+
+  private sanitizePii(str: string): string {
+    return str
+      // Strip email addresses
+      .replace(/[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}/g, '[email]')
+      // Strip phone numbers (various formats)
+      .replace(/(\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}/g, '[phone]')
+      // Strip query strings from URLs (may contain tokens/PII)
+      .replace(/(https?:\/\/[^\s?#]+)\?[^\s)"]*/g, '$1?[redacted]');
+  }
+
+  private stripQueryString(url: string): string {
+    try {
+      const u = new URL(url);
+      return u.origin + u.pathname;
+    } catch {
+      return url.replace(/\?.*$/, '');
+    }
+  }
+
+  private emitErrorEvent(data: {
+    message: string;
+    stack: string;
+    source: string;
+    lineno: number;
+    colno: number;
+    type: 'uncaught' | 'unhandled_rejection';
+  }): void {
+    const now = Date.now();
+    if (data.message === this.lastErrorMessage && now - this.lastErrorTime < 1000) return;
+    this.lastErrorMessage = data.message;
+    this.lastErrorTime = now;
+
+    this.emitCustomEvent('error', {
+      message: this.sanitizePii(data.message),
+      stack: this.sanitizePii(data.stack),
+      source: this.stripQueryString(data.source),
+      lineno: data.lineno,
+      colno: data.colno,
+      type: data.type,
+      page: window.location.pathname,
+    });
+  }
+
+  private handleWindowError = (e: ErrorEvent): void => {
+    this.emitErrorEvent({
+      message: e.message || 'Unknown error',
+      stack: (e.error?.stack || '').slice(0, 4000),
+      source: e.filename || '',
+      lineno: e.lineno || 0,
+      colno: e.colno || 0,
+      type: 'uncaught',
+    });
+  };
+
+  private handleUnhandledRejection = (e: PromiseRejectionEvent): void => {
+    const reason = e.reason;
+    const message = reason instanceof Error ? reason.message : String(reason || 'Unhandled rejection');
+    const stack = reason instanceof Error ? (reason.stack || '').slice(0, 4000) : '';
+    this.emitErrorEvent({
+      message,
+      stack,
+      source: '',
+      lineno: 0,
+      colno: 0,
+      type: 'unhandled_rejection',
+    });
+  };
+
+  // ── Idle detection ────────────────────────────────────────────────
+
+  private resetIdleTimer(): void {
+    this.lastInteractionTime = Date.now();
+    this.idleEmitted = false;
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+    }
+    this.idleTimer = setTimeout(() => this.checkIdle(), Recorder.IDLE_THRESHOLD_MS);
+  }
+
+  private checkIdle(): void {
+    if (this.idleEmitted) return;
+    if (document.visibilityState !== 'visible') return;
+    const elapsed = Date.now() - this.lastInteractionTime;
+    if (elapsed >= Recorder.IDLE_THRESHOLD_MS) {
+      this.idleEmitted = true;
+      this.emitCustomEvent('idle_detected', { duration: elapsed, page: window.location.pathname });
+    }
+  }
+
+  private handleKeydown = (): void => {
+    this.resetIdleTimer();
+  };
+
+  // ── SPA navigation tracking ────────────────────────────────────────
+
+  private patchHistoryMethods(): void {
+    const nativePushState = History.prototype.pushState;
+    const nativeReplaceState = History.prototype.replaceState;
+    this.origPushState = history.pushState.bind(history);
+    this.origReplaceState = history.replaceState.bind(history);
+    const self = this;
+    history.pushState = function (...args: Parameters<typeof history.pushState>) {
+      // Use saved original if available, fall back to native prototype method.
+      // Another library may hold a reference to this patched function after we
+      // unpatch (setting origPushState to null), so we must never throw.
+      const fn = self.origPushState || nativePushState.bind(history);
+      fn(...args);
+      try { self.handleNavigation(); } catch (e) { console.warn('SessionSight: error in pushState handler', e); }
+    };
+    history.replaceState = function (...args: Parameters<typeof history.replaceState>) {
+      const fn = self.origReplaceState || nativeReplaceState.bind(history);
+      fn(...args);
+      try { self.handleNavigation(); } catch (e) { console.warn('SessionSight: error in replaceState handler', e); }
+    };
+  }
+
+  private unpatchHistoryMethods(): void {
+    if (this.origPushState) { history.pushState = this.origPushState; this.origPushState = null; }
+    if (this.origReplaceState) { history.replaceState = this.origReplaceState; this.origReplaceState = null; }
+  }
+
+  private handleNavigation = (): void => {
+    try {
+      const currentHref = window.location.href;
+      if (currentHref === this.lastHref) return;
+      this.lastHref = currentHref;
+
+      // Check if the new page should be excluded
+      const shouldExclude = this.excludePagePatterns.length > 0 &&
+        matchesAnyPattern(window.location.pathname, this.excludePagePatterns);
+
+      if (shouldExclude && !this.isPaused) {
+        // Entering an excluded page: flush remaining events, emit placeholder, then pause
+        this.bridge.flush();
+        const metaEvent: eventWithTime = {
+          type: META_EVENT_TYPE,
+          data: { href: currentHref, width: window.innerWidth, height: window.innerHeight },
+          timestamp: Date.now(),
+        };
+        this.pushEvent(metaEvent);
+        this.emitCustomEvent('ss-page-excluded', { href: currentHref });
+        this.bridge.flush();
+        this.isPaused = true;
+        return;
+      }
+
+      if (!shouldExclude && this.isPaused) {
+        // Leaving an excluded page: resume and take a fresh FullSnapshot
+        this.isPaused = false;
+      }
+
+      // Flush all buffered events from the previous page before doing anything else.
+      // Without this, SPA navigations can cause in-flight fetches to be aborted,
+      // losing the entire previous page's recording.
+      this.bridge.flush();
+
+      // Previous page's text is now irrelevant, free the memory
+      maskCacheClear();
+
+      const metaEvent: eventWithTime = {
+        type: META_EVENT_TYPE,
+        data: { href: currentHref, width: window.innerWidth, height: window.innerHeight },
+        timestamp: Date.now(),
+      };
+      this.pushEvent(metaEvent);
+
+      // Cancel any pending settled snapshot before stopping rrweb, so it
+      // cannot fire during the 100ms gap before startRrweb() re-initialises.
+      if (this.settledSnapshotTimer) {
+        clearTimeout(this.settledSnapshotTimer);
+        this.settledSnapshotTimer = null;
+      }
+      // Restart rrweb for a fresh FullSnapshot of the new page.
+      // Null out stopRrweb so guards (scheduleSettledSnapshot, scroll handler)
+      // correctly skip takeFullSnapshot while recording is stopped.
+      if (this.stopRrweb) {
+        this.stopRrweb();
+        this.stopRrweb = null;
+      }
+      // Reset scroll depth tracking for the new page
+      this.scrollDepthHits.clear();
+      setTimeout(() => {
+        this.startRrweb();
+        this.setupScrollDepthObserver();
+      }, 100);
+    } catch (e) {
+      console.warn('SessionSight: error in navigation handler', e);
+    }
+  };
+
+  // ── Flag token check ────────────────────────────────────────────
+
+  private checkFlagToken(): void {
+    try {
+      const flagToken = getRegistryValue<string>('flagEvaluationToken');
+      if (flagToken && flagToken !== this.lastEmittedFlagToken) {
+        this.lastEmittedFlagToken = flagToken;
+        this.emitCustomEvent('flag_evaluation', { token: flagToken });
+      }
+    } catch (e) {
+      console.warn('SessionSight: error checking flag token', e);
+    }
+  }
+
+  private collectMetadata(): SessionMetadata {
+    return {
+      url: window.location.href,
+      referrer: document.referrer || '',
+      userAgent: navigator.userAgent,
+      screenWidth: window.innerWidth,
+      screenHeight: window.innerHeight,
+      language: navigator.language,
+    };
+  }
+
+  private handleVisibilityChange = (): void => {
+    try {
+      if (document.visibilityState === 'hidden') {
+        this.bridge.sendBeacon();
+        this.hiddenAt = Date.now();
+        this.isHidden = true;
+      } else {
+        this.isHidden = false;
+        // Check elapsed time since the tab was hidden. Browsers throttle/freeze
+        // setTimeout in background tabs, so a timestamp comparison is reliable
+        // where a timer is not.
+        if (this.hiddenAt && (Date.now() - this.hiddenAt) >= Recorder.VISIBILITY_GRACE_MS) {
+          this.hiddenAt = null;
+          this.endedByVisibility = true;
+          this.stop();
+        } else {
+          this.hiddenAt = null;
+        }
+      }
+    } catch (e) {
+      console.warn('SessionSight: error in visibility handler', e);
+    }
+  };
+
+  private handleBeforeUnload = (): void => {
+    try {
+      this.bridge.sendBeacon();
+    } catch (e) {
+      console.warn('SessionSight: error in beforeunload handler', e);
+    }
+  };
+}