@sessionvision/core 0.2.0 → 0.4.0

package/dist/sessionvision.esm.js

@@ -1,11 +1,14 @@
 /*!
- * Session Vision Core v0.2.0
+ * Session Vision Core v0.4.0
  * (c) 2026 Session Vision
  * Released under the MIT License
  */
 /**
  * Session Vision Snippet Type Definitions
  */
+/**
+ * Recording chunk configuration
+ */
 /**
  * Storage key constants
  */
@@ -29,8 +32,11 @@ const DEFAULT_CONFIG = {
     maskAllInputs: true,
     autocapture: {
         pageview: true,
-        clicks: true,
+        click: true,
         formSubmit: true,
+        rageClick: true,
+        deadClick: true,
+        formAbandonment: true,
     },
 };
 /**
@@ -47,9 +53,9 @@ const BUFFER_CONFIG = {
     RETRY_DELAYS_MS: [1000, 2000, 4000],
 };
 /**
- * Config cache TTL in milliseconds (1 hour)
+ * Config cache TTL in milliseconds (4 hours)
  */
-const CONFIG_CACHE_TTL_MS = 60 * 60 * 1000;
+const CONFIG_CACHE_TTL_MS = 4 * 60 * 60 * 1000;
 
 /**
  * Storage utility for localStorage and sessionStorage operations
@@ -350,8 +356,11 @@ function resolveConfig(projectToken, userConfig) {
             // Boolean: enable or disable all
             autocapture = {
                 pageview: userConfig.autocapture,
-                clicks: userConfig.autocapture,
+                click: userConfig.autocapture,
                 formSubmit: userConfig.autocapture,
+                rageClick: userConfig.autocapture,
+                deadClick: userConfig.autocapture,
+                formAbandonment: userConfig.autocapture,
             };
         }
         else if (typeof userConfig.autocapture === 'object') {
@@ -359,8 +368,11 @@ function resolveConfig(projectToken, userConfig) {
             const userAutocapture = userConfig.autocapture;
             autocapture = {
                 pageview: userAutocapture.pageview ?? DEFAULT_CONFIG.autocapture.pageview,
-                clicks: userAutocapture.clicks ?? DEFAULT_CONFIG.autocapture.clicks,
+                click: userAutocapture.click ?? DEFAULT_CONFIG.autocapture.click,
                 formSubmit: userAutocapture.formSubmit ?? DEFAULT_CONFIG.autocapture.formSubmit,
+                rageClick: userAutocapture.rageClick ?? DEFAULT_CONFIG.autocapture.rageClick,
+                deadClick: userAutocapture.deadClick ?? DEFAULT_CONFIG.autocapture.deadClick,
+                formAbandonment: userAutocapture.formAbandonment ?? DEFAULT_CONFIG.autocapture.formAbandonment,
             };
         }
     }
@@ -373,6 +385,7 @@ function resolveConfig(projectToken, userConfig) {
         optOut: userConfig?.optOut ?? DEFAULT_CONFIG.optOut,
         maskAllInputs: userConfig?.maskAllInputs ?? DEFAULT_CONFIG.maskAllInputs,
         autocapture,
+        recording: userConfig?.recording,
     };
 }
 /**
@@ -382,9 +395,9 @@ function getCacheKey(projectToken) {
     return `${STORAGE_KEYS.CONFIG_CACHE}_${projectToken}`;
 }
 /**
- * Get cached remote config if valid
+ * Get cached remote config if valid (exported for fast path in init.ts)
  */
-function getCachedConfig(projectToken) {
+function getCachedRemoteConfig(projectToken) {
     const cached = getLocalStorage(getCacheKey(projectToken));
     if (!cached) {
         return null;
@@ -405,19 +418,38 @@ function setCachedConfig(projectToken, config) {
     };
     setLocalStorage(getCacheKey(projectToken), cached);
 }
+/**
+ * Resolve the recorder bundle URL relative to the SDK's apiHost
+ */
+function resolveRecorderUrl(config) {
+    return `${config.apiHost}/v${config.version}/sessionvision-recorder.min.js`;
+}
 /**
  * Fetch remote configuration from server
  */
-async function fetchRemoteConfig(resolvedConfig) {
+async function fetchRemoteConfig(resolvedConfig, options) {
     const { projectToken, debug } = resolvedConfig;
     // Check cache first
-    const cached = getCachedConfig(projectToken);
+    const cached = getCachedRemoteConfig(projectToken);
     if (cached) {
         if (debug) {
             console.log('[SessionVision] Using cached config');
         }
         return cached;
     }
+    // Speculative prefetch for first-time visitors: inject <link rel="prefetch">
+    // for the recorder bundle while the config fetch is in flight
+    if (options?.prefetchRecorder && typeof document !== 'undefined') {
+        try {
+            const link = document.createElement('link');
+            link.rel = 'prefetch';
+            link.href = resolveRecorderUrl(resolvedConfig);
+            document.head.appendChild(link);
+        }
+        catch {
+            // Ignore prefetch errors — best-effort optimization
+        }
+    }
     try {
         // Fetch config from CDN (static file hosted at apiHost)
         const url = `${resolvedConfig.apiHost}/static/config/${projectToken}`;
@@ -832,7 +864,7 @@ function getAutomaticProperties() {
         $timezone: getTimezone(),
         $locale: getLocale(),
         $connection_type: getConnectionType(),
-        $lib_version: "0.2.0"
+        $lib_version: "0.4.0"
             ,
     };
 }
@@ -935,6 +967,246 @@ function captureSystemEvent(eventName, properties = {}) {
     captureEvent(eventName, properties, { includeAutoProperties: true });
 }
 
+/**
+ * Payload compression module
+ * Uses CompressionStream API when available
+ */
+/**
+ * Check if compression is supported
+ */
+function isCompressionSupported() {
+    return (typeof CompressionStream !== 'undefined' &&
+        typeof ReadableStream !== 'undefined');
+}
+/**
+ * Compress a string using gzip
+ * Returns the compressed data as a Blob, or null if compression is not supported
+ */
+async function compressPayload(data) {
+    if (!isCompressionSupported()) {
+        return null;
+    }
+    try {
+        const encoder = new TextEncoder();
+        const inputBytes = encoder.encode(data);
+        const stream = new ReadableStream({
+            start(controller) {
+                controller.enqueue(inputBytes);
+                controller.close();
+            },
+        });
+        const compressedStream = stream.pipeThrough(new CompressionStream('gzip'));
+        const reader = compressedStream.getReader();
+        const chunks = [];
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+        }
+        // Combine chunks into a single Blob
+        return new Blob(chunks, { type: 'application/gzip' });
+    }
+    catch {
+        // Compression failed, return null to use uncompressed
+        return null;
+    }
+}
+/**
+ * Get the size of data in bytes
+ */
+function getByteSize(data) {
+    return new Blob([data]).size;
+}
+/**
+ * Check if payload should be compressed (based on size threshold)
+ * Only compress if payload is larger than 1KB
+ */
+function shouldCompress(data) {
+    return isCompressionSupported() && getByteSize(data) > 1024;
+}
+
+/**
+ * HTTP transport module
+ * Handles sending events to the ingest API
+ */
+let config$2 = null;
+let consecutiveFailures = 0;
+/**
+ * Set the configuration
+ */
+function setTransportConfig(cfg) {
+    config$2 = cfg;
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Send events to the ingest API
+ * Handles compression and retry logic
+ */
+async function sendEvents(payload) {
+    if (!config$2) {
+        console.warn('[SessionVision] SDK not initialized');
+        return false;
+    }
+    const url = `${config$2.ingestHost}/api/v1/ingest/events`;
+    const jsonPayload = JSON.stringify(payload);
+    // Try to compress if payload is large enough
+    const useCompression = shouldCompress(jsonPayload);
+    let body = jsonPayload;
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (useCompression) {
+        const compressed = await compressPayload(jsonPayload);
+        if (compressed) {
+            body = compressed;
+            headers['Content-Type'] = 'application/json';
+            headers['Content-Encoding'] = 'gzip';
+        }
+    }
+    // Attempt to send with retries
+    for (let attempt = 0; attempt <= BUFFER_CONFIG.MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body,
+                keepalive: true, // Keep connection alive for background sends
+            });
+            if (response.ok || response.status === 202) {
+                // Success
+                consecutiveFailures = 0;
+                if (config$2.debug) {
+                    console.log(`[SessionVision] Events sent successfully (${payload.events.length} events)`);
+                }
+                return true;
+            }
+            // Server error, might be worth retrying
+            if (response.status >= 500) {
+                throw new Error(`Server error: ${response.status}`);
+            }
+            // Client error (4xx), don't retry
+            if (config$2.debug) {
+                console.warn(`[SessionVision] Failed to send events: ${response.status}`);
+            }
+            return false;
+        }
+        catch (error) {
+            // Network error or server error, retry if attempts remaining
+            if (attempt < BUFFER_CONFIG.MAX_RETRIES) {
+                const delay = BUFFER_CONFIG.RETRY_DELAYS_MS[attempt] || 4000;
+                if (config$2.debug) {
+                    console.log(`[SessionVision] Retry ${attempt + 1}/${BUFFER_CONFIG.MAX_RETRIES} in ${delay}ms`);
+                }
+                await sleep(delay);
+            }
+            else {
+                // All retries exhausted
+                consecutiveFailures++;
+                if (config$2.debug) {
+                    console.warn('[SessionVision] Failed to send events after retries:', error);
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Check if we should stop retrying (3+ consecutive failures)
+ */
+function shouldStopRetrying() {
+    return consecutiveFailures >= 3;
+}
+
+/**
+ * Event buffer module
+ * Buffers events and flushes them periodically or when buffer is full
+ */
+let eventBuffer = [];
+let flushTimer = null;
+let config$1 = null;
+let isFlushing = false;
+/**
+ * Set the configuration
+ */
+function setBufferConfig(cfg) {
+    config$1 = cfg;
+}
+/**
+ * Add an event to the buffer
+ */
+function addToBuffer(event) {
+    // If we've had too many failures, drop events
+    if (shouldStopRetrying()) {
+        if (config$1?.debug) {
+            console.warn('[SessionVision] Too many failures, dropping event');
+        }
+        return;
+    }
+    eventBuffer.push(event);
+    // Flush if buffer is full
+    if (eventBuffer.length >= BUFFER_CONFIG.MAX_EVENTS) {
+        flush();
+    }
+}
+/**
+ * Flush the event buffer
+ * Sends all buffered events to the server
+ */
+async function flush() {
+    if (isFlushing || eventBuffer.length === 0 || !config$1) {
+        return;
+    }
+    isFlushing = true;
+    // Take events from buffer (FIFO eviction on failure)
+    const eventsToSend = [...eventBuffer];
+    eventBuffer = [];
+    const payload = {
+        projectToken: config$1.projectToken,
+        events: eventsToSend,
+    };
+    const success = await sendEvents(payload);
+    if (!success) {
+        // Re-add events to buffer if we haven't exceeded max retries
+        if (!shouldStopRetrying()) {
+            // Only keep most recent events up to max buffer size
+            const combined = [...eventsToSend, ...eventBuffer];
+            eventBuffer = combined.slice(-10);
+            if (config$1.debug && combined.length > BUFFER_CONFIG.MAX_EVENTS) {
+                console.warn(`[SessionVision] Buffer overflow, dropped ${combined.length - BUFFER_CONFIG.MAX_EVENTS} oldest events`);
+            }
+        }
+    }
+    isFlushing = false;
+}
+/**
+ * Start the flush timer
+ */
+function startFlushTimer() {
+    if (flushTimer) {
+        return;
+    }
+    flushTimer = setInterval(() => {
+        flush();
+    }, BUFFER_CONFIG.FLUSH_INTERVAL_MS);
+}
+/**
+ * Initialize visibility change handler for flushing on tab hide
+ */
+function initVisibilityHandler() {
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+            // Best-effort flush when tab is hidden
+            flush();
+        }
+    });
+}
+
 /**
  * Pageview tracking module
  * Handles initial page load and SPA navigation
@@ -958,6 +1230,9 @@ function capturePageview(customProperties = {}) {
         ...customProperties,
     };
     captureEvent('$pageview', properties);
+    // Flush immediately to ensure pageview is sent quickly
+    // This captures users who bounce before the 5-second interval
+    flush();
 }
 /**
  * Handle history state changes for SPA navigation
@@ -1210,331 +1485,607 @@ function maskPII(text) {
 }
 
 /**
- * Autocapture module
- * Handles automatic capture of clicks and form submissions
- */
-let isClickTrackingActive = false;
-let isFormTrackingActive = false;
-let config$2 = null;
-/**
- * Set the configuration
- */
-function setAutocaptureConfig(cfg) {
-    config$2 = cfg;
-}
-/**
- * Handle click events
- */
-function handleClick(event) {
-    const target = event.target;
-    if (!target || shouldIgnoreElement(target)) {
-        return;
+ * Rage Click Detection
+ *
+ * Detects rapid repeated clicks indicating user frustration.
+ * Emits a single $rage_click event after the click sequence ends.
+ */
+/** Elements that legitimately receive rapid clicks */
+const RAGE_CLICK_EXCLUDED_SELECTORS = [
+    'input[type="number"]',
+    'input[type="range"]',
+    '[role="spinbutton"]',
+    '[role="slider"]',
+    '[class*="quantity"]',
+    '[class*="stepper"]',
+    '[class*="increment"]',
+    '[class*="decrement"]',
+    '[class*="plus"]',
+    '[class*="minus"]',
+    'video',
+    'audio',
+    '[class*="player"]',
+    '[class*="volume"]',
+    '[class*="seek"]',
+    'canvas',
+];
+function shouldExcludeFromRageClick(element) {
+    if (element.closest('[data-sessionvision-no-rageclick]')) {
+        return true;
     }
-    // Find the most relevant interactive element
-    const element = getInteractiveParent(target) || target;
-    if (shouldIgnoreElement(element)) {
-        return;
+    for (const selector of RAGE_CLICK_EXCLUDED_SELECTORS) {
+        if (element.matches(selector) || element.closest(selector)) {
+            return true;
+        }
     }
-    const properties = {
-        $element_tag: getElementTag(element),
-        $element_text: maskPII(getElementText(element)),
-        $element_classes: getElementClasses(element),
-        $element_id: getElementId(element),
-        $element_selector: generateSelector(element),
-        $element_href: getElementHref(element),
-    };
-    captureEvent('$click', properties);
+    return false;
 }
-/**
- * Handle form submission events
- */
-function handleFormSubmit(event) {
-    const form = event.target;
-    if (!form || !(form instanceof HTMLFormElement)) {
-        return;
+class RageClickDetector {
+    constructor(_config) {
+        this.clicks = [];
+        this.emitTimeout = null;
+        this.threshold = RageClickDetector.DEFAULT_THRESHOLD;
+        this.windowMs = RageClickDetector.DEFAULT_WINDOW_MS;
+        this.radiusPx = RageClickDetector.DEFAULT_RADIUS_PX;
+    }
+    recordClick(event, element, properties) {
+        const now = Date.now();
+        this.clicks.push({
+            timestamp: now,
+            x: event.clientX,
+            y: event.clientY,
+            elementSelector: properties.$element_selector || '',
+            element,
+            properties,
+        });
+        // Remove expired clicks outside the window
+        this.clicks = this.clicks.filter((c) => now - c.timestamp <= this.windowMs);
+        // Reset the emit timeout - we'll check after the sequence ends
+        this.scheduleEmit();
+    }
+    scheduleEmit() {
+        if (this.emitTimeout) {
+            clearTimeout(this.emitTimeout);
+        }
+        this.emitTimeout = setTimeout(() => {
+            this.maybeEmitRageClick();
+        }, this.windowMs);
+    }
+    maybeEmitRageClick() {
+        if (this.clicks.length < this.threshold) {
+            this.clicks = [];
+            return;
+        }
+        const sameElement = this.clicks.every((c) => c.elementSelector === this.clicks[0].elementSelector);
+        const sameArea = this.isClickCluster(this.clicks);
+        if (sameElement || sameArea) {
+            this.emitRageClick();
+        }
+        this.clicks = [];
+    }
+    isClickCluster(clicks) {
+        for (let i = 0; i < clicks.length; i++) {
+            for (let j = i + 1; j < clicks.length; j++) {
+                const dx = clicks[i].x - clicks[j].x;
+                const dy = clicks[i].y - clicks[j].y;
+                const distance = Math.sqrt(dx * dx + dy * dy);
+                if (distance > this.radiusPx) {
+                    return false;
+                }
+            }
+        }
+        return true;
     }
-    if (shouldIgnoreElement(form)) {
-        return;
+    emitRageClick() {
+        const lastClick = this.clicks[this.clicks.length - 1];
+        const firstClick = this.clicks[0];
+        const duration = lastClick.timestamp - firstClick.timestamp;
+        let elementX = 0;
+        let elementY = 0;
+        try {
+            const rect = lastClick.element.getBoundingClientRect();
+            elementX = lastClick.x - rect.left;
+            elementY = lastClick.y - rect.top;
+        }
+        catch {
+            // Element may have been removed from DOM
+        }
+        const rageClickProperties = {
+            ...lastClick.properties,
+            $click_count: this.clicks.length,
+            $rage_click_duration_ms: duration,
+            $click_x: lastClick.x,
+            $click_y: lastClick.y,
+            $element_x: elementX,
+            $element_y: elementY,
+            $click_positions: this.clicks.map((c) => ({
+                x: c.x,
+                y: c.y,
+                timestamp: c.timestamp,
+            })),
+        };
+        captureEvent('$rage_click', rageClickProperties);
+    }
+    destroy() {
+        if (this.emitTimeout) {
+            clearTimeout(this.emitTimeout);
+            this.emitTimeout = null;
+        }
+        this.clicks = [];
     }
-    const properties = {
-        $form_id: form.id || null,
-        $form_action: form.action || '',
-        $form_method: (form.method || 'GET').toUpperCase(),
-        $form_name: form.name || null,
-    };
-    captureEvent('$form_submit', properties);
 }
+RageClickDetector.DEFAULT_THRESHOLD = 3;
+RageClickDetector.DEFAULT_WINDOW_MS = 1000;
+RageClickDetector.DEFAULT_RADIUS_PX = 30;
+
 /**
- * Initialize click tracking
- */
-function initClickTracking() {
-    if (isClickTrackingActive) {
-        return;
+ * Dead Click Detection
+ *
+ * Detects clicks that produce no visible DOM changes.
+ * Emits $dead_click events when no response is detected.
+ */
+/** Elements that may not cause visible DOM changes when clicked */
+const DEAD_CLICK_EXCLUDED_SELECTORS = [
+    'input[type="text"]',
+    'input[type="password"]',
+    'input[type="email"]',
+    'input[type="search"]',
+    'input[type="tel"]',
+    'input[type="url"]',
+    'textarea',
+    'select',
+    'video',
+    'audio',
+];
+function shouldExcludeFromDeadClick(element) {
+    if (element.closest('[data-sessionvision-no-deadclick]')) {
+        return true;
     }
-    isClickTrackingActive = true;
-    document.addEventListener('click', handleClick, { capture: true });
-}
-/**
- * Initialize form submission tracking
- */
-function initFormTracking() {
-    if (isFormTrackingActive) {
-        return;
+    for (const selector of DEAD_CLICK_EXCLUDED_SELECTORS) {
+        if (element.matches(selector) || element.closest(selector)) {
+            return true;
+        }
     }
-    isFormTrackingActive = true;
-    document.addEventListener('submit', handleFormSubmit, { capture: true });
+    return false;
 }
-/**
- * Initialize all autocapture based on configuration
- */
-function initAutocapture(cfg) {
-    config$2 = cfg;
-    if (config$2.autocapture.clicks) {
-        initClickTracking();
+class DeadClickDetector {
+    constructor(_config) {
+        this.pendingClick = null;
+        this.timeoutMs = DeadClickDetector.DEFAULT_TIMEOUT_MS;
+    }
+    monitorClick(event, element, properties) {
+        // Cancel any pending detection
+        this.cancelPending();
+        const timestamp = Date.now();
+        let mutationDetected = false;
+        const observer = new MutationObserver((mutations) => {
+            const meaningful = mutations.some((m) => this.isMeaningfulMutation(m, element));
+            if (meaningful) {
+                mutationDetected = true;
+                this.cancelPending();
+            }
+        });
+        observer.observe(document.body, {
+            childList: true,
+            attributes: true,
+            characterData: true,
+            subtree: true,
+        });
+        const timeout = setTimeout(() => {
+            if (!mutationDetected && this.pendingClick) {
+                this.emitDeadClick(this.pendingClick);
+            }
+            this.cancelPending();
+        }, this.timeoutMs);
+        this.pendingClick = {
+            x: event.clientX,
+            y: event.clientY,
+            element,
+            properties,
+            timestamp,
+            observer,
+            timeout,
+        };
+    }
+    cancelPending() {
+        if (this.pendingClick) {
+            this.pendingClick.observer.disconnect();
+            clearTimeout(this.pendingClick.timeout);
+            this.pendingClick = null;
+        }
     }
-    if (config$2.autocapture.formSubmit) {
-        initFormTracking();
+    isMeaningfulMutation(mutation, clickedElement) {
+        // Ignore class changes on clicked element (often just :active styles)
+        if (mutation.type === 'attributes' &&
+            mutation.attributeName === 'class' &&
+            mutation.target === clickedElement) {
+            return false;
+        }
+        // Ignore data-* attribute changes (often analytics)
+        if (mutation.type === 'attributes' && mutation.attributeName?.startsWith('data-')) {
+            return false;
+        }
+        // Ignore script/style/link/meta injections
+        if (mutation.type === 'childList') {
+            const ignoredNodes = ['SCRIPT', 'STYLE', 'LINK', 'META'];
+            const addedNonIgnored = Array.from(mutation.addedNodes).some((node) => !ignoredNodes.includes(node.nodeName));
+            if (!addedNonIgnored && mutation.removedNodes.length === 0) {
+                return false;
+            }
+        }
+        return true;
     }
-}
+    emitDeadClick(pending) {
+        let elementX = 0;
+        let elementY = 0;
+        try {
+            const rect = pending.element.getBoundingClientRect();
+            elementX = pending.x - rect.left;
+            elementY = pending.y - rect.top;
+        }
+        catch {
+            // Element may have been removed from DOM
+        }
+        const deadClickProperties = {
+            ...pending.properties,
+            $click_x: pending.x,
+            $click_y: pending.y,
+            $element_x: elementX,
+            $element_y: elementY,
+            $wait_duration_ms: Date.now() - pending.timestamp,
+            $element_is_interactive: isInteractiveElement(pending.element),
+        };
+        captureEvent('$dead_click', deadClickProperties);
+    }
+    destroy() {
+        this.cancelPending();
+    }
+}
+DeadClickDetector.DEFAULT_TIMEOUT_MS = 1000;
 
 /**
- * Payload compression module
- * Uses CompressionStream API when available
+ * Form Field Tracking
+ *
+ * Tracks form field interactions for abandonment analysis.
+ * Emits $form_start when user begins filling a form,
+ * $form_field_change when fields are modified.
  */
 /**
- * Check if compression is supported
+ * Form field tracker instance
  */
-function isCompressionSupported() {
-    return (typeof CompressionStream !== 'undefined' &&
-        typeof ReadableStream !== 'undefined');
+let isActive = false;
+const startedForms = new Map();
+/**
+ * Get form fields (inputs, textareas, selects)
+ */
+function getFormFields(form) {
+    const fields = form.querySelectorAll('input, textarea, select');
+    return Array.from(fields);
 }
 /**
- * Compress a string using gzip
- * Returns the compressed data as a Blob, or null if compression is not supported
+ * Get the index of a field within its form
  */
-async function compressPayload(data) {
-    if (!isCompressionSupported()) {
-        return null;
+function getFieldIndex(field, form) {
+    const fields = getFormFields(form);
+    return fields.indexOf(field);
+}
+/**
+ * Get the type of a form field
+ */
+function getFieldType(field) {
+    if (field instanceof HTMLInputElement) {
+        return field.type || 'text';
     }
-    try {
-        const encoder = new TextEncoder();
-        const inputBytes = encoder.encode(data);
-        const stream = new ReadableStream({
-            start(controller) {
-                controller.enqueue(inputBytes);
-                controller.close();
-            },
-        });
-        const compressedStream = stream.pipeThrough(new CompressionStream('gzip'));
-        const reader = compressedStream.getReader();
-        const chunks = [];
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            chunks.push(value);
-        }
-        // Combine chunks into a single Blob
-        return new Blob(chunks, { type: 'application/gzip' });
+    if (field instanceof HTMLTextAreaElement) {
+        return 'textarea';
     }
-    catch {
-        // Compression failed, return null to use uncompressed
-        return null;
+    if (field instanceof HTMLSelectElement) {
+        return 'select';
     }
+    return 'unknown';
 }
 /**
- * Get the size of data in bytes
+ * Check if a field has a value
  */
-function getByteSize(data) {
-    return new Blob([data]).size;
+function fieldHasValue(field) {
+    if (field instanceof HTMLInputElement) {
+        if (field.type === 'checkbox' || field.type === 'radio') {
+            return field.checked;
+        }
+        return field.value.length > 0;
+    }
+    if (field instanceof HTMLTextAreaElement) {
+        return field.value.length > 0;
+    }
+    if (field instanceof HTMLSelectElement) {
+        return field.selectedIndex > 0 || (field.selectedIndex === 0 && field.value !== '');
+    }
+    return false;
 }
 /**
- * Check if payload should be compressed (based on size threshold)
- * Only compress if payload is larger than 1KB
+ * Check if a field is a form field
  */
-function shouldCompress(data) {
-    return isCompressionSupported() && getByteSize(data) > 1024;
+function isFormField(element) {
+    return (element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement ||
+        element instanceof HTMLSelectElement);
 }
-
 /**
- * HTTP transport module
- * Handles sending events to the ingest API
- */
-let config$1 = null;
-let consecutiveFailures = 0;
-/**
- * Set the configuration
+ * Get the parent form of an element
  */
-function setTransportConfig(cfg) {
-    config$1 = cfg;
+function getParentForm(element) {
+    return element.closest('form');
 }
 /**
- * Sleep for a given number of milliseconds
+ * Handle focus events on form fields
  */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function handleFocusIn(event) {
+    const target = event.target;
+    if (!target || !isFormField(target)) {
+        return;
+    }
+    if (shouldIgnoreElement(target)) {
+        return;
+    }
+    const form = getParentForm(target);
+    if (!form || shouldIgnoreElement(form)) {
+        return;
+    }
+    const formSelector = generateSelector(form);
+    // Check if this form has already been started
+    if (startedForms.has(formSelector)) {
+        return;
+    }
+    // Emit $form_start
+    const fields = getFormFields(form);
+    const properties = {
+        $form_id: form.id || null,
+        $form_name: form.name || null,
+        $form_selector: formSelector,
+        $form_field_count: fields.length,
+    };
+    captureEvent('$form_start', properties);
+    // Track form state
+    startedForms.set(formSelector, {
+        startTime: Date.now(),
+        fieldCount: fields.length,
+        interactedFields: new Set(),
+        filledFields: new Set(),
+    });
 }
 /**
- * Send events to the ingest API
- * Handles compression and retry logic
+ * Handle change events on form fields
  */
-async function sendEvents(payload) {
-    if (!config$1) {
-        console.warn('[SessionVision] SDK not initialized');
-        return false;
+function handleChange(event) {
+    const target = event.target;
+    if (!target || !isFormField(target)) {
+        return;
     }
-    const url = `${config$1.ingestHost}/api/v1/ingest/events`;
-    const jsonPayload = JSON.stringify(payload);
-    // Try to compress if payload is large enough
-    const useCompression = shouldCompress(jsonPayload);
-    let body = jsonPayload;
-    const headers = {
-        'Content-Type': 'application/json',
-    };
-    if (useCompression) {
-        const compressed = await compressPayload(jsonPayload);
-        if (compressed) {
-            body = compressed;
-            headers['Content-Type'] = 'application/json';
-            headers['Content-Encoding'] = 'gzip';
+    if (shouldIgnoreElement(target)) {
+        return;
+    }
+    const form = getParentForm(target);
+    if (!form || shouldIgnoreElement(form)) {
+        return;
+    }
+    const formSelector = generateSelector(form);
+    const fieldSelector = generateSelector(target);
+    const formState = startedForms.get(formSelector);
+    // Track interaction even if form wasn't started (edge case)
+    if (!formState) {
+        // Start the form now
+        const fields = getFormFields(form);
+        const startProps = {
+            $form_id: form.id || null,
+            $form_name: form.name || null,
+            $form_selector: formSelector,
+            $form_field_count: fields.length,
+        };
+        captureEvent('$form_start', startProps);
+        startedForms.set(formSelector, {
+            startTime: Date.now(),
+            fieldCount: fields.length,
+            interactedFields: new Set([fieldSelector]),
+            filledFields: new Set(fieldHasValue(target) ? [fieldSelector] : []),
+        });
+    }
+    else {
+        // Update tracking
+        formState.interactedFields.add(fieldSelector);
+        if (fieldHasValue(target)) {
+            formState.filledFields.add(fieldSelector);
+        }
+        else {
+            formState.filledFields.delete(fieldSelector);
         }
     }
-    // Attempt to send with retries
-    for (let attempt = 0; attempt <= BUFFER_CONFIG.MAX_RETRIES; attempt++) {
-        try {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers,
-                body,
-                keepalive: true, // Keep connection alive for background sends
-            });
-            if (response.ok || response.status === 202) {
-                // Success
-                consecutiveFailures = 0;
-                if (config$1.debug) {
-                    console.log(`[SessionVision] Events sent successfully (${payload.events.length} events)`);
-                }
-                return true;
-            }
-            // Server error, might be worth retrying
-            if (response.status >= 500) {
-                throw new Error(`Server error: ${response.status}`);
-            }
-            // Client error (4xx), don't retry
-            if (config$1.debug) {
-                console.warn(`[SessionVision] Failed to send events: ${response.status}`);
+    // Emit $form_field_change
+    const properties = {
+        $form_selector: formSelector,
+        $field_selector: fieldSelector,
+        $field_name: target.name || null,
+        $field_type: getFieldType(target),
+        $field_index: getFieldIndex(target, form),
+        $has_value: fieldHasValue(target),
+    };
+    captureEvent('$form_field_change', properties);
+}
+/**
+ * Reset tracking for a specific form (called after submit)
+ */
+function resetForm(formSelector) {
+    startedForms.delete(formSelector);
+}
+/**
+ * Get form tracking data for enhanced submit event
+ */
+function getFormTrackingData(form) {
+    const formSelector = generateSelector(form);
+    const fields = getFormFields(form);
+    const formState = startedForms.get(formSelector);
+    if (!formState) {
+        // Form submitted without tracking (e.g., direct submit without field focus)
+        const filledFields = [];
+        for (const field of fields) {
+            if (fieldHasValue(field) && !shouldIgnoreElement(field)) {
+                filledFields.push(generateSelector(field));
             }
-            return false;
         }
-        catch (error) {
-            // Network error or server error, retry if attempts remaining
-            if (attempt < BUFFER_CONFIG.MAX_RETRIES) {
-                const delay = BUFFER_CONFIG.RETRY_DELAYS_MS[attempt] || 4000;
-                if (config$1.debug) {
-                    console.log(`[SessionVision] Retry ${attempt + 1}/${BUFFER_CONFIG.MAX_RETRIES} in ${delay}ms`);
-                }
-                await sleep(delay);
-            }
-            else {
-                // All retries exhausted
-                consecutiveFailures++;
-                if (config$1.debug) {
-                    console.warn('[SessionVision] Failed to send events after retries:', error);
-                }
-            }
+        return {
+            formSelector,
+            formFieldCount: fields.length,
+            formFieldsFilled: filledFields,
+            formFieldsInteracted: [],
+            formCompletionRate: fields.length > 0 ? filledFields.length / fields.length : 0,
+            formTimeToSubmitMs: null,
+        };
+    }
+    // Update filled fields snapshot at submit time
+    const currentFilledFields = [];
+    for (const field of fields) {
+        if (fieldHasValue(field) && !shouldIgnoreElement(field)) {
+            currentFilledFields.push(generateSelector(field));
         }
     }
-    return false;
+    const completionRate = fields.length > 0 ? currentFilledFields.length / fields.length : 0;
+    return {
+        formSelector,
+        formFieldCount: formState.fieldCount,
+        formFieldsFilled: currentFilledFields,
+        formFieldsInteracted: Array.from(formState.interactedFields),
+        formCompletionRate: Math.round(completionRate * 100) / 100,
+        formTimeToSubmitMs: Date.now() - formState.startTime,
+    };
 }
 /**
- * Check if we should stop retrying (3+ consecutive failures)
+ * Initialize form field tracking
  */
-function shouldStopRetrying() {
-    return consecutiveFailures >= 3;
+function initFormFieldTracking(_cfg) {
+    if (isActive) {
+        return;
+    }
+    isActive = true;
+    document.addEventListener('focusin', handleFocusIn, { capture: true });
+    document.addEventListener('change', handleChange, { capture: true });
 }
 
 /**
- * Event buffer module
- * Buffers events and flushes them periodically or when buffer is full
+ * Autocapture module
+ * Handles automatic capture of clicks, form submissions,
+ * rage clicks, and dead clicks
  */
-let eventBuffer = [];
-let flushTimer = null;
+let isClickTrackingActive = false;
+let isFormTrackingActive = false;
 let config = null;
-let isFlushing = false;
+let rageClickDetector = null;
+let deadClickDetector = null;
 /**
  * Set the configuration
  */
-function setBufferConfig(cfg) {
+function setAutocaptureConfig(cfg) {
     config = cfg;
 }
 /**
- * Add an event to the buffer
+ * Handle click events
  */
-function addToBuffer(event) {
-    // If we've had too many failures, drop events
-    if (shouldStopRetrying()) {
-        if (config?.debug) {
-            console.warn('[SessionVision] Too many failures, dropping event');
-        }
+function handleClick(event) {
+    const target = event.target;
+    if (!target || shouldIgnoreElement(target)) {
         return;
     }
-    eventBuffer.push(event);
-    // Flush if buffer is full
-    if (eventBuffer.length >= BUFFER_CONFIG.MAX_EVENTS) {
-        flush();
+    // Find the most relevant interactive element
+    const element = getInteractiveParent(target) || target;
+    if (shouldIgnoreElement(element)) {
+        return;
+    }
+    const properties = {
+        $element_tag: getElementTag(element),
+        $element_text: maskPII(getElementText(element)),
+        $element_classes: getElementClasses(element),
+        $element_id: getElementId(element),
+        $element_selector: generateSelector(element),
+        $element_href: getElementHref(element),
+    };
+    captureEvent('$click', properties);
+    // Feed click to frustration detectors
+    if (rageClickDetector && !shouldExcludeFromRageClick(element)) {
+        rageClickDetector.recordClick(event, element, properties);
+    }
+    if (deadClickDetector && !shouldExcludeFromDeadClick(element)) {
+        deadClickDetector.monitorClick(event, element, properties);
     }
 }
 /**
- * Flush the event buffer
- * Sends all buffered events to the server
+ * Handle form submission events
  */
-async function flush() {
-    if (isFlushing || eventBuffer.length === 0 || !config) {
+function handleFormSubmit(event) {
+    const form = event.target;
+    if (!form || !(form instanceof HTMLFormElement)) {
         return;
     }
-    isFlushing = true;
-    // Take events from buffer (FIFO eviction on failure)
-    const eventsToSend = [...eventBuffer];
-    eventBuffer = [];
-    const payload = {
-        projectToken: config.projectToken,
-        events: eventsToSend,
+    if (shouldIgnoreElement(form)) {
+        return;
+    }
+    // Get form field tracking data
+    const trackingData = getFormTrackingData(form);
+    const properties = {
+        $form_id: form.id || null,
+        $form_action: form.action || '',
+        $form_method: (form.method || 'GET').toUpperCase(),
+        $form_name: form.name || null,
+        $form_selector: trackingData.formSelector,
+        $form_field_count: trackingData.formFieldCount,
+        $form_fields_filled: trackingData.formFieldsFilled,
+        $form_fields_interacted: trackingData.formFieldsInteracted,
+        $form_completion_rate: trackingData.formCompletionRate,
+        $form_time_to_submit_ms: trackingData.formTimeToSubmitMs,
     };
-    const success = await sendEvents(payload);
-    if (!success) {
-        // Re-add events to buffer if we haven't exceeded max retries
-        if (!shouldStopRetrying()) {
-            // Only keep most recent events up to max buffer size
-            const combined = [...eventsToSend, ...eventBuffer];
-            eventBuffer = combined.slice(-10);
-            if (config.debug && combined.length > BUFFER_CONFIG.MAX_EVENTS) {
-                console.warn(`[SessionVision] Buffer overflow, dropped ${combined.length - BUFFER_CONFIG.MAX_EVENTS} oldest events`);
-            }
-        }
+    captureEvent('$form_submit', properties);
+    // Reset form tracking state after submit
+    resetForm(trackingData.formSelector);
+}
+/**
+ * Initialize click tracking
+ */
+function initClickTracking() {
+    if (isClickTrackingActive) {
+        return;
     }
-    isFlushing = false;
+    isClickTrackingActive = true;
+    document.addEventListener('click', handleClick, { capture: true });
 }
 /**
- * Start the flush timer
+ * Initialize form submission tracking
  */
-function startFlushTimer() {
-    if (flushTimer) {
+function initFormTracking() {
+    if (isFormTrackingActive) {
         return;
     }
-    flushTimer = setInterval(() => {
-        flush();
-    }, BUFFER_CONFIG.FLUSH_INTERVAL_MS);
+    isFormTrackingActive = true;
+    document.addEventListener('submit', handleFormSubmit, { capture: true });
 }
 /**
- * Initialize visibility change handler for flushing on tab hide
+ * Initialize all autocapture based on configuration
  */
-function initVisibilityHandler() {
-    document.addEventListener('visibilitychange', () => {
-        if (document.visibilityState === 'hidden') {
-            // Best-effort flush when tab is hidden
-            flush();
-        }
-    });
+function initAutocapture(cfg) {
+    config = cfg;
+    if (config.autocapture.click) {
+        initClickTracking();
+    }
+    if (config.autocapture.formSubmit) {
+        initFormTracking();
+    }
+    // Initialize form field tracking for abandonment analysis
+    if (config.autocapture.formAbandonment) {
+        initFormFieldTracking();
+    }
+    // Initialize frustration detectors
+    if (config.autocapture.rageClick) {
+        rageClickDetector = new RageClickDetector(config);
+    }
+    if (config.autocapture.deadClick) {
+        deadClickDetector = new DeadClickDetector(config);
+    }
 }
 
 /**
@@ -1588,10 +2139,24 @@ async function init(projectToken, config) {
         isInitialized = true;
         return;
     }
-    // Fetch remote config (async, don't block initialization)
-    fetchRemoteConfig(resolvedConfig).then((remoteConfig) => {
+    // FAST PATH: Check cached config synchronously to start recorder loading early.
+    // This avoids waiting for the network fetch on return visits.
+    let recorderAlreadyLoading = false;
+    const cachedConfig = getCachedRemoteConfig(resolvedConfig.projectToken);
+    if (cachedConfig?.recording?.enabled) {
+        recorderAlreadyLoading = true;
+        maybeLoadRecorder(cachedConfig, getSessionId());
+    }
+    // Always fetch fresh config to keep cache warm for next page load.
+    // Only prefetch recorder if: no cache yet AND recording isn't locally disabled.
+    const shouldPrefetch = !cachedConfig && resolvedConfig.recording !== false;
+    fetchRemoteConfig(resolvedConfig, { prefetchRecorder: shouldPrefetch }).then((remoteConfig) => {
         if (remoteConfig) {
             applyRemoteConfig(remoteConfig);
+            // Only trigger recorder loading if the fast path didn't already handle it.
+            if (!recorderAlreadyLoading) {
+                maybeLoadRecorder(remoteConfig, getSessionId());
+            }
         }
     });
     // Start event buffer flush timer
@@ -1668,6 +2233,208 @@ function registerOnce(properties) {
     }
     registerOnceProperties(properties);
 }
+/**
+ * Manually flush the event buffer
+ */
+function flushEvents() {
+    return flush();
+}
+// Cached remote config for startRecording() to check
+let lastRemoteConfig = null;
+// Track recording state locally so isRecording() can be synchronous
+let recordingActive = false;
+// Lightweight event emitter (lives in main SDK so listeners can register before recorder loads)
+const eventListeners = new Map();
+// Cache the SDK script base URL at load time (document.currentScript is only available synchronously)
+let cachedScriptBaseUrl = null;
+if (typeof document !== 'undefined' && document.currentScript) {
+    const src = document.currentScript.src;
+    if (src) {
+        cachedScriptBaseUrl = src.substring(0, src.lastIndexOf('/') + 1);
+    }
+}
+/**
+ * Get the recorder module from the global (set by the recorder bundle on load)
+ */
+function getRecorderModule() {
+    if (typeof window === 'undefined')
+        return null;
+    return (window
+        .__sessionvision_recorder ?? null);
+}
+/**
+ * Load the recorder bundle via script injection
+ */
+function loadRecorderBundle() {
+    return new Promise((resolve, reject) => {
+        // Already loaded?
+        const existing = getRecorderModule();
+        if (existing) {
+            resolve(existing);
+            return;
+        }
+        if (typeof document === 'undefined') {
+            reject(new Error('No document available'));
+            return;
+        }
+        // Resolve recorder URL from SDK script base or CDN
+        const baseUrl = cachedScriptBaseUrl || `${resolvedConfig?.apiHost}/v${resolvedConfig?.version}/`;
+        const url = `${baseUrl}sessionvision-recorder.min.js`;
+        const script = document.createElement('script');
+        script.src = url;
+        script.async = true;
+        script.onload = () => {
+            const mod = getRecorderModule();
+            if (mod) {
+                // Register pending event listeners with the newly loaded recorder
+                for (const [event, callbacks] of eventListeners) {
+                    for (const cb of callbacks) {
+                        mod.on(event, cb);
+                    }
+                }
+                resolve(mod);
+            }
+            else {
+                reject(new Error('Recorder bundle loaded but module not registered'));
+            }
+        };
+        script.onerror = () => {
+            reject(new Error(`Failed to load recorder bundle from ${url}`));
+        };
+        document.head.appendChild(script);
+    });
+}
+/**
+ * FNV-1a hash for deterministic sampling
+ */
+function hashSessionId(sessionId) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < sessionId.length; i++) {
+        hash ^= sessionId.charCodeAt(i);
+        hash = (hash * 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+/**
+ * Deterministic sampling based on session ID
+ */
+function shouldRecordSession(sampleRate, sessionId) {
+    if (sampleRate >= 1)
+        return true;
+    if (sampleRate <= 0)
+        return false;
+    const hash = hashSessionId(sessionId);
+    return hash % 100 < sampleRate * 100;
+}
+/**
+ * Load the recorder bundle if conditions are met
+ */
+async function maybeLoadRecorder(config, sessionId) {
+    // Gate 1: Remote config must have recording enabled
+    if (!config.recording?.enabled) {
+        return;
+    }
+    // Gate 2: Local config can force-disable recording
+    if (resolvedConfig?.recording === false) {
+        return;
+    }
+    // Gate 3: Deterministic sampling based on session ID
+    if (!shouldRecordSession(config.recording.sampleRate, sessionId)) {
+        if (resolvedConfig?.debug) {
+            console.log('[SessionVision] Session not sampled for recording');
+        }
+        return;
+    }
+    // Store remote config for later use by public API
+    lastRemoteConfig = config;
+    // Only now do we fetch the recorder bundle (separate HTTP request)
+    try {
+        const recorder = await loadRecorderBundle();
+        recorder.initRecorder(resolvedConfig, config);
+        recordingActive = true;
+    }
+    catch (error) {
+        if (resolvedConfig?.debug) {
+            console.warn('[SessionVision] Failed to load recorder:', error);
+        }
+        // Recorder failure must never affect core SDK functionality
+    }
+}
+/**
+ * Manually start recording. Respects remote config — no-op if recording.enabled is false.
+ * Bypasses sampling when recording is enabled.
+ */
+async function startRecording() {
+    if (!isInitialized || !resolvedConfig)
+        return;
+    if (resolvedConfig.recording === false)
+        return;
+    // Check remote config
+    const remoteConfig = lastRemoteConfig || getCachedRemoteConfig(resolvedConfig.projectToken);
+    if (!remoteConfig?.recording?.enabled)
+        return;
+    try {
+        const recorder = getRecorderModule() || (await loadRecorderBundle());
+        if (!recorder.isRecorderActive()) {
+            recorder.initRecorder(resolvedConfig, remoteConfig);
+            recordingActive = true;
+        }
+    }
+    catch (error) {
+        if (resolvedConfig.debug) {
+            console.warn('[SessionVision] Failed to start recording:', error);
+        }
+    }
+}
+/**
+ * Stop recording for this session
+ */
+function stopRecording() {
+    const recorder = getRecorderModule();
+    if (recorder) {
+        recorder.stopRecorder();
+    }
+    recordingActive = false;
+}
+/**
+ * Check if recording is active
+ */
+function isRecording() {
+    return recordingActive;
+}
+/**
+ * Tag the current recording with custom metadata
+ */
+function tagRecordingFn(tags) {
+    const recorder = getRecorderModule();
+    if (recorder) {
+        recorder.tagRecording(tags);
+    }
+}
+/**
+ * Subscribe to SDK events
+ */
+function onEvent(event, callback) {
+    if (!eventListeners.has(event)) {
+        eventListeners.set(event, new Set());
+    }
+    eventListeners.get(event).add(callback);
+    // Also register with recorder if already loaded
+    const recorder = getRecorderModule();
+    if (recorder) {
+        recorder.on(event, callback);
+    }
+}
+/**
+ * Unsubscribe from SDK events
+ */
+function offEvent(event, callback) {
+    eventListeners.get(event)?.delete(callback);
+    const recorder = getRecorderModule();
+    if (recorder) {
+        recorder.off(event, callback);
+    }
+}
 
 /**
  * Queue replay module
@@ -1739,7 +2506,7 @@ function getInitCalls(initArray) {
  * Session Vision JavaScript Snippet
  * Main SDK entry point
  *
- * @version "0.2.0"
+ * @version "0.4.0"
  */
 /**
  * Session Vision SDK instance
@@ -1748,7 +2515,7 @@ const sessionvision = {
     /**
      * SDK version
      */
-    version: "0.2.0" ,
+    version: "0.4.0" ,
     /**
      * Initialize the SDK with a project token and optional configuration
      *
@@ -1863,6 +2630,61 @@ const sessionvision = {
     registerOnce(properties) {
         registerOnce(properties);
     },
+    /**
+     * Manually flush the event buffer
+     * Useful before navigation or when you need to ensure events are sent immediately
+     *
+     * @returns Promise that resolves when the flush is complete
+     *
+     * @example
+     * ```js
+     * // Before navigating away
+     * await sessionvision.flushEvents();
+     * window.location.href = '/new-page';
+     * ```
+     */
+    flushEvents() {
+        return flushEvents();
+    },
+    /**
+     * Subscribe to SDK events (e.g., 'recording:error', 'recording:quota_exceeded')
+     */
+    on(event, callback) {
+        onEvent(event, callback);
+    },
+    /**
+     * Unsubscribe from SDK events
+     */
+    off(event, callback) {
+        offEvent(event, callback);
+    },
+    /**
+     * Manually start recording
+     * Respects remote config — no-op if recording.enabled is false
+     * Bypasses sampling when recording is enabled
+     */
+    startRecording() {
+        startRecording();
+    },
+    /**
+     * Stop recording for this session
+     */
+    stopRecording() {
+        stopRecording();
+    },
+    /**
+     * Check if recording is active
+     */
+    isRecording() {
+        return isRecording();
+    },
+    /**
+     * Tag the current recording with custom metadata
+     * Tags are accumulated in memory and sent with the next chunk upload
+     */
+    tagRecording(tags) {
+        tagRecordingFn(tags);
+    },
 };
 /**
  * Bootstrap the SDK