@grainql/analytics-web 2.6.0 → 2.7.1

package/dist/index.global.dev.js

@@ -1,4 +1,4 @@
-/* Grain Analytics Web SDK v2.6.0 | MIT License | Development Build */
+/* Grain Analytics Web SDK v2.7.1 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;
@@ -22,23 +22,271 @@ var Grain = (() => {
   };
   var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+  // src/attention-quality.ts
+  var DEFAULT_OPTIONS, AttentionQualityManager;
+  var init_attention_quality = __esm({
+    "src/attention-quality.ts"() {
+      "use strict";
+      DEFAULT_OPTIONS = {
+        maxSectionDuration: 9e3,
+        // 9 seconds
+        minScrollDistance: 100,
+        // 100 pixels
+        idleThreshold: 3e4
+        // 30 seconds
+      };
+      AttentionQualityManager = class {
+        constructor(activityDetector, options = {}) {
+          this.isDestroyed = false;
+          // Page visibility tracking
+          this.isPageVisible = true;
+          this.visibilityChangeHandler = null;
+          // Section attention state
+          this.sectionStates = /* @__PURE__ */ new Map();
+          // Policies applied reasons (for debugging/traceability)
+          this.lastFilterReason = null;
+          this.activityDetector = activityDetector;
+          this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+            debug: options.debug ?? false
+          };
+          this.setupPageVisibilityTracking();
+        }
+        /**
+         * Setup page visibility tracking
+         */
+        setupPageVisibilityTracking() {
+          if (typeof document === "undefined")
+            return;
+          this.isPageVisible = document.visibilityState === "visible";
+          this.visibilityChangeHandler = () => {
+            const wasVisible = this.isPageVisible;
+            this.isPageVisible = document.visibilityState === "visible";
+            if (!this.isPageVisible && wasVisible) {
+              this.log("Page hidden - tracking paused");
+            } else if (this.isPageVisible && !wasVisible) {
+              this.log("Page visible - tracking resumed");
+              this.resetAllSections();
+            }
+          };
+          document.addEventListener("visibilitychange", this.visibilityChangeHandler);
+        }
+        /**
+         * Check if tracking should be allowed (global check)
+         * Returns true if tracking is allowed, false if it should be paused
+         */
+        shouldTrack() {
+          if (!this.isPageVisible) {
+            this.lastFilterReason = "page_hidden";
+            return false;
+          }
+          if (!this.activityDetector.isActive(this.options.idleThreshold)) {
+            this.lastFilterReason = "user_idle";
+            return false;
+          }
+          this.lastFilterReason = null;
+          return true;
+        }
+        /**
+         * Check if section view tracking should be allowed for a specific section
+         * @param sectionName - Section identifier
+         * @param currentScrollY - Current scroll position
+         * @returns Object with shouldTrack boolean and optional reason
+         */
+        shouldTrackSection(sectionName, currentScrollY) {
+          if (!this.shouldTrack()) {
+            return {
+              shouldTrack: false,
+              reason: this.lastFilterReason || "global_policy"
+            };
+          }
+          let state = this.sectionStates.get(sectionName);
+          if (!state) {
+            state = {
+              sectionName,
+              currentDuration: 0,
+              lastScrollPosition: currentScrollY,
+              lastResetTime: Date.now()
+            };
+            this.sectionStates.set(sectionName, state);
+          }
+          const scrollDistance = Math.abs(currentScrollY - state.lastScrollPosition);
+          const hasScrolledEnough = scrollDistance >= this.options.minScrollDistance;
+          if (hasScrolledEnough) {
+            this.log(`Section "${sectionName}": Attention reset due to ${Math.round(scrollDistance)}px scroll`);
+            state.currentDuration = 0;
+            state.lastScrollPosition = currentScrollY;
+            state.lastResetTime = Date.now();
+            return {
+              shouldTrack: true,
+              resetAttention: true
+            };
+          }
+          if (state.currentDuration >= this.options.maxSectionDuration) {
+            return {
+              shouldTrack: false,
+              reason: "max_duration_reached"
+            };
+          }
+          return {
+            shouldTrack: true
+          };
+        }
+        /**
+         * Update section duration (call this when tracking a section view event)
+         * @param sectionName - Section identifier
+         * @param durationMs - Duration to add to current attention block
+         */
+        updateSectionDuration(sectionName, durationMs) {
+          const state = this.sectionStates.get(sectionName);
+          if (state) {
+            state.currentDuration += durationMs;
+            if (state.currentDuration >= this.options.maxSectionDuration) {
+              this.log(`Section "${sectionName}": Max duration cap reached (${state.currentDuration}ms)`);
+            }
+          }
+        }
+        /**
+         * Reset attention for a specific section (call when user navigates to different section)
+         * @param sectionName - Section identifier
+         */
+        resetSection(sectionName) {
+          const state = this.sectionStates.get(sectionName);
+          if (state) {
+            this.log(`Section "${sectionName}": Attention reset (section exit)`);
+            state.currentDuration = 0;
+            state.lastResetTime = Date.now();
+          }
+        }
+        /**
+         * Reset all section attention states
+         */
+        resetAllSections() {
+          this.log("Resetting all section attention states");
+          for (const state of this.sectionStates.values()) {
+            state.currentDuration = 0;
+            state.lastResetTime = Date.now();
+          }
+        }
+        /**
+         * Get current attention state for a section (for debugging/monitoring)
+         */
+        getSectionState(sectionName) {
+          return this.sectionStates.get(sectionName);
+        }
+        /**
+         * Get reason why last tracking attempt was filtered
+         */
+        getLastFilterReason() {
+          return this.lastFilterReason;
+        }
+        /**
+         * Check if scroll tracking should be allowed
+         * Similar to shouldTrack() but also checks scroll-specific conditions
+         */
+        shouldTrackScroll(previousScrollY, currentScrollY) {
+          if (!this.shouldTrack()) {
+            return {
+              shouldTrack: false,
+              reason: this.lastFilterReason || "global_policy"
+            };
+          }
+          const scrollDistance = Math.abs(currentScrollY - previousScrollY);
+          if (scrollDistance < 10) {
+            return {
+              shouldTrack: false,
+              reason: "scroll_too_small"
+            };
+          }
+          return {
+            shouldTrack: true
+          };
+        }
+        /**
+         * Get all active policies as object (for monitoring/debugging)
+         */
+        getPolicies() {
+          return {
+            maxSectionDuration: this.options.maxSectionDuration,
+            minScrollDistance: this.options.minScrollDistance,
+            idleThreshold: this.options.idleThreshold
+          };
+        }
+        /**
+         * Get current tracking state (for monitoring/debugging)
+         */
+        getTrackingState() {
+          return {
+            isPageVisible: this.isPageVisible,
+            isUserActive: this.activityDetector.isActive(this.options.idleThreshold),
+            timeSinceLastActivity: this.activityDetector.getTimeSinceLastActivity(),
+            activeSections: this.sectionStates.size
+          };
+        }
+        /**
+         * Log debug messages
+         */
+        log(...args) {
+          if (this.options.debug) {
+            console.log("[AttentionQuality]", ...args);
+          }
+        }
+        /**
+         * Destroy and cleanup
+         */
+        destroy() {
+          if (this.isDestroyed)
+            return;
+          this.isDestroyed = true;
+          if (this.visibilityChangeHandler && typeof document !== "undefined") {
+            document.removeEventListener("visibilitychange", this.visibilityChangeHandler);
+            this.visibilityChangeHandler = null;
+          }
+          this.sectionStates.clear();
+        }
+      };
+    }
+  });
+
+  // src/text-utils.ts
+  function removeEmojis(text) {
+    if (!text)
+      return void 0;
+    return text.replace(/[\u{1F300}-\u{1F9FF}]/gu, "").replace(/[\u{1F600}-\u{1F64F}]/gu, "").replace(/[\u{1F680}-\u{1F6FF}]/gu, "").replace(/[\u{2600}-\u{26FF}]/gu, "").replace(/[\u{2700}-\u{27BF}]/gu, "").replace(/[\u{1F900}-\u{1F9FF}]/gu, "").replace(/[\u{1F1E0}-\u{1F1FF}]/gu, "").replace(/[\u{200D}]/gu, "").replace(/[\u{FE0F}]/gu, "").replace(/[\u{20E3}]/gu, "").trim();
+  }
+  function cleanElementText(text, maxLength = 100) {
+    if (!text)
+      return void 0;
+    const cleaned = removeEmojis(text);
+    if (!cleaned)
+      return void 0;
+    return cleaned.substring(0, maxLength) || void 0;
+  }
+  var init_text_utils = __esm({
+    "src/text-utils.ts"() {
+      "use strict";
+    }
+  });
+
   // src/heatmap-tracking.ts
   var heatmap_tracking_exports = {};
   __export(heatmap_tracking_exports, {
     HeatmapTrackingManager: () => HeatmapTrackingManager
   });
-  var DEFAULT_OPTIONS, HeatmapTrackingManager;
+  var DEFAULT_OPTIONS2, HeatmapTrackingManager;
   var init_heatmap_tracking = __esm({
     "src/heatmap-tracking.ts"() {
       "use strict";
-      DEFAULT_OPTIONS = {
+      init_attention_quality();
+      init_text_utils();
+      DEFAULT_OPTIONS2 = {
         scrollDebounceDelay: 100,
         batchDelay: 2e3,
         maxBatchSize: 20,
         debug: false
       };
       HeatmapTrackingManager = class {
-        // 3 seconds - same as section tracking
         constructor(tracker, options = {}) {
           this.isDestroyed = false;
           // Tracking state
@@ -55,7 +303,19 @@ var Grain = (() => {
           this.lastScrollTime = Date.now();
           this.SPLIT_DURATION = 3e3;
           this.tracker = tracker;
-          this.options = { ...DEFAULT_OPTIONS, ...options };
+          this.options = { ...DEFAULT_OPTIONS2, ...options };
+          this.attentionQuality = new AttentionQualityManager(
+            tracker.getActivityDetector(),
+            {
+              maxSectionDuration: 9e3,
+              // 9 seconds per viewport section
+              minScrollDistance: 100,
+              // 100 pixels
+              idleThreshold: 3e4,
+              // 30 seconds
+              debug: this.options.debug
+            }
+          );
           if (typeof window !== "undefined" && typeof document !== "undefined") {
             if (document.readyState === "loading") {
               document.addEventListener("DOMContentLoaded", () => this.initialize());
@@ -133,12 +393,27 @@ var Grain = (() => {
               return;
             if (!this.tracker.hasConsent("analytics"))
               return;
+            if (!this.attentionQuality.shouldTrack()) {
+              this.log("Scroll tracking paused:", this.attentionQuality.getLastFilterReason());
+              return;
+            }
             const currentTime = Date.now();
             const duration = currentTime - this.currentScrollState.entryTime;
             if (duration > 1e3) {
               const scrollY = window.scrollY || window.pageYOffset;
               const viewportHeight = window.innerHeight;
               const pageHeight = document.documentElement.scrollHeight;
+              const sectionKey = `viewport_section_${this.currentScrollState.viewportSection}`;
+              const attentionCheck = this.attentionQuality.shouldTrackSection(sectionKey, scrollY);
+              if (attentionCheck.resetAttention) {
+                this.log(`Viewport section ${this.currentScrollState.viewportSection}: Attention reset`);
+                this.currentScrollState.entryTime = currentTime;
+                return;
+              }
+              if (!attentionCheck.shouldTrack) {
+                this.log(`Viewport section ${this.currentScrollState.viewportSection}: ${attentionCheck.reason}`);
+                return;
+              }
               const scrollData = {
                 pageUrl: window.location.href,
                 viewportSection: this.currentScrollState.viewportSection,
@@ -161,6 +436,7 @@ var Grain = (() => {
                 is_split: true
                 // Flag to indicate periodic tracking, not final exit
               }, { flush: true });
+              this.attentionQuality.updateSectionDuration(sectionKey, duration);
               this.currentScrollState.entryTime = currentTime;
             }
           }, this.SPLIT_DURATION);
@@ -210,7 +486,7 @@ var Grain = (() => {
           const pageX = Math.round(event.pageX);
           const pageY = Math.round(event.pageY);
           const elementTag = element.tagName?.toLowerCase() || "unknown";
-          const elementText = element.textContent?.trim().substring(0, 100);
+          const elementText = cleanElementText(element.textContent);
           const clickData = {
             pageUrl,
             xpath,
@@ -276,6 +552,8 @@ var Grain = (() => {
               };
               this.pendingScrolls.push(scrollData);
             }
+            const prevSectionKey = `viewport_section_${this.currentScrollState.viewportSection}`;
+            this.attentionQuality.resetSection(prevSectionKey);
           }
           if (!this.currentScrollState || this.currentScrollState.viewportSection !== viewportSection) {
             this.currentScrollState = {
@@ -448,6 +726,7 @@ var Grain = (() => {
             clearInterval(this.periodicScrollTimer);
             this.periodicScrollTimer = null;
           }
+          this.attentionQuality.destroy();
           this.flushPendingEvents();
         }
       };
@@ -463,6 +742,7 @@ var Grain = (() => {
   var init_interaction_tracking = __esm({
     "src/interaction-tracking.ts"() {
       "use strict";
+      init_text_utils();
       InteractionTrackingManager = class {
         constructor(tracker, interactions, config = {}) {
           this.isDestroyed = false;
@@ -541,7 +821,7 @@ var Grain = (() => {
             interaction_description: interaction.description,
             interaction_priority: interaction.priority,
             element_tag: element.tagName?.toLowerCase(),
-            element_text: element.textContent?.trim().substring(0, 100),
+            element_text: cleanElementText(element.textContent),
             element_id: element.id || void 0,
             element_class: element.className || void 0,
             ...isNavigationLink && { href: element.href },
@@ -720,11 +1000,12 @@ var Grain = (() => {
   __export(section_tracking_exports, {
     SectionTrackingManager: () => SectionTrackingManager
   });
-  var DEFAULT_OPTIONS2, SectionTrackingManager;
+  var DEFAULT_OPTIONS3, SectionTrackingManager;
   var init_section_tracking = __esm({
     "src/section-tracking.ts"() {
       "use strict";
-      DEFAULT_OPTIONS2 = {
+      init_attention_quality();
+      DEFAULT_OPTIONS3 = {
         minDwellTime: 1e3,
         // 1 second minimum
         scrollVelocityThreshold: 500,
@@ -737,7 +1018,6 @@ var Grain = (() => {
         debug: false
       };
       SectionTrackingManager = class {
-        // 3 seconds
         constructor(tracker, sections, options = {}) {
           this.isDestroyed = false;
           // Tracking state
@@ -758,7 +1038,19 @@ var Grain = (() => {
           this.SPLIT_DURATION = 3e3;
           this.tracker = tracker;
           this.sections = sections;
-          this.options = { ...DEFAULT_OPTIONS2, ...options };
+          this.options = { ...DEFAULT_OPTIONS3, ...options };
+          this.attentionQuality = new AttentionQualityManager(
+            tracker.getActivityDetector(),
+            {
+              maxSectionDuration: 9e3,
+              // 9 seconds
+              minScrollDistance: 100,
+              // 100 pixels
+              idleThreshold: 3e4,
+              // 30 seconds
+              debug: this.options.debug
+            }
+          );
           if (typeof window !== "undefined" && typeof document !== "undefined") {
             if (document.readyState === "loading") {
               document.addEventListener("DOMContentLoaded", () => this.initialize());
@@ -892,6 +1184,21 @@ var Grain = (() => {
             const now = Date.now();
             const duration = now - state.entryTime;
             if (duration >= this.options.minDwellTime) {
+              const currentScrollY = window.scrollY;
+              const attentionCheck = this.attentionQuality.shouldTrackSection(
+                state.config.sectionName,
+                currentScrollY
+              );
+              if (attentionCheck.resetAttention) {
+                this.log(`Section "${state.config.sectionName}": Attention reset, restarting timer`);
+                state.entryTime = now;
+                state.entryScrollSpeed = this.scrollVelocity;
+                return;
+              }
+              if (!attentionCheck.shouldTrack) {
+                this.log(`Section "${state.config.sectionName}": Tracking paused - ${attentionCheck.reason}`);
+                return;
+              }
               const viewData = {
                 sectionName: state.config.sectionName,
                 sectionType: state.config.sectionType,
@@ -922,6 +1229,7 @@ var Grain = (() => {
                   is_split: true
                   // Flag to indicate this is a periodic split, not final exit
                 });
+                this.attentionQuality.updateSectionDuration(state.config.sectionName, duration);
                 state.entryTime = now;
                 state.entryScrollSpeed = this.scrollVelocity;
               }
@@ -944,6 +1252,7 @@ var Grain = (() => {
          */
         handleSectionExit(state) {
           this.stopPeriodicTracking(state.config.sectionName);
+          this.attentionQuality.resetSection(state.config.sectionName);
           if (state.entryTime === null)
             return;
           state.exitTime = Date.now();
@@ -1140,6 +1449,7 @@ var Grain = (() => {
             this.intersectionObserver.disconnect();
             this.intersectionObserver = null;
           }
+          this.attentionQuality.destroy();
           this.sectionStates.clear();
           this.xpathCache.clear();
           this.pendingEvents = [];
@@ -5869,6 +6179,15 @@ var Grain = (() => {
     resetEventCountSinceLastHeartbeat() {
       this.eventCountSinceLastHeartbeat = 0;
     }
+    /**
+     * Get the activity detector (for internal use by tracking managers)
+     */
+    getActivityDetector() {
+      if (!this.activityDetector) {
+        throw new Error("Activity detector not initialized");
+      }
+      return this.activityDetector;
+    }
     /**
      * Get the effective user ID (public method)
      */