@sessionvision/core 0.2.0 → 0.4.0

package/dist/sessionvision.js

@@ -1,5 +1,5 @@
 /*!
- * Session Vision Core v0.2.0
+ * Session Vision Core v0.4.0
  * (c) 2026 Session Vision
  * Released under the MIT License
  */
@@ -12,6 +12,9 @@
     /**
      * Session Vision Snippet Type Definitions
      */
+    /**
+     * Recording chunk configuration
+     */
     /**
      * Storage key constants
      */
@@ -35,8 +38,11 @@
         maskAllInputs: true,
         autocapture: {
             pageview: true,
-            clicks: true,
+            click: true,
             formSubmit: true,
+            rageClick: true,
+            deadClick: true,
+            formAbandonment: true,
         },
     };
     /**
@@ -53,9 +59,9 @@
         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
@@ -356,8 +362,11 @@
                 // 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') {
@@ -365,8 +374,11 @@
                 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,
                 };
             }
         }
@@ -379,6 +391,7 @@
             optOut: userConfig?.optOut ?? DEFAULT_CONFIG.optOut,
             maskAllInputs: userConfig?.maskAllInputs ?? DEFAULT_CONFIG.maskAllInputs,
             autocapture,
+            recording: userConfig?.recording,
         };
     }
     /**
@@ -388,9 +401,9 @@
         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;
@@ -411,19 +424,38 @@
         };
         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}`;
@@ -838,7 +870,7 @@
             $timezone: getTimezone(),
             $locale: getLocale(),
             $connection_type: getConnectionType(),
-            $lib_version: "0.2.0"
+            $lib_version: "0.4.0"
                 ,
         };
     }
@@ -941,6 +973,246 @@
         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
@@ -964,6 +1236,9 @@
             ...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
@@ -1216,331 +1491,607 @@
     }
 
     /**
-     * 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);
+        }
     }
 
     /**
@@ -1594,10 +2145,24 @@
             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
@@ -1674,6 +2239,208 @@
         }
         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
@@ -1745,7 +2512,7 @@
      * Session Vision JavaScript Snippet
      * Main SDK entry point
      *
-     * @version "0.2.0"
+     * @version "0.4.0"
      */
     /**
      * Session Vision SDK instance
@@ -1754,7 +2521,7 @@
         /**
          * SDK version
          */
-        version: "0.2.0" ,
+        version: "0.4.0" ,
         /**
          * Initialize the SDK with a project token and optional configuration
          *
@@ -1869,6 +2636,61 @@
         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