@grainql/analytics-web 2.6.0 → 2.7.1

package/dist/attention-quality.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Attention Quality Manager for Grain Analytics
+ * Enforces policies to ensure tracked data represents genuine user attention
+ *
+ * Policies:
+ * 1. Page Visibility: Stop tracking when tab is hidden/backgrounded
+ * 2. User Activity: Stop tracking when user is idle (no mouse/keyboard/touch)
+ * 3. Section Duration Cap: Max attention per section before requiring transition
+ * 4. Scroll Distance: Minimum scroll distance to count as meaningful engagement
+ *
+ * See: ATTENTION_QUALITY_POLICY.md for detailed policy documentation
+ */
+import type { ActivityDetector } from './activity';
+export interface AttentionQualityOptions {
+    /**
+     * Maximum continuous attention duration per section (ms)
+     * Default: 9000 (9 seconds)
+     */
+    maxSectionDuration?: number;
+    /**
+     * Minimum scroll distance to reset attention timer (px)
+     * Default: 100
+     */
+    minScrollDistance?: number;
+    /**
+     * Idle threshold - stop tracking after this period of inactivity (ms)
+     * Default: 30000 (30 seconds)
+     */
+    idleThreshold?: number;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+interface SectionAttentionState {
+    sectionName: string;
+    currentDuration: number;
+    lastScrollPosition: number;
+    lastResetTime: number;
+}
+export declare class AttentionQualityManager {
+    private options;
+    private activityDetector;
+    private isDestroyed;
+    private isPageVisible;
+    private visibilityChangeHandler;
+    private sectionStates;
+    private lastFilterReason;
+    constructor(activityDetector: ActivityDetector, options?: AttentionQualityOptions);
+    /**
+     * Setup page visibility tracking
+     */
+    private setupPageVisibilityTracking;
+    /**
+     * Check if tracking should be allowed (global check)
+     * Returns true if tracking is allowed, false if it should be paused
+     */
+    shouldTrack(): boolean;
+    /**
+     * 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: string, currentScrollY: number): {
+        shouldTrack: boolean;
+        reason?: string;
+        resetAttention?: boolean;
+    };
+    /**
+     * 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: string, durationMs: number): void;
+    /**
+     * Reset attention for a specific section (call when user navigates to different section)
+     * @param sectionName - Section identifier
+     */
+    resetSection(sectionName: string): void;
+    /**
+     * Reset all section attention states
+     */
+    resetAllSections(): void;
+    /**
+     * Get current attention state for a section (for debugging/monitoring)
+     */
+    getSectionState(sectionName: string): SectionAttentionState | undefined;
+    /**
+     * Get reason why last tracking attempt was filtered
+     */
+    getLastFilterReason(): string | null;
+    /**
+     * Check if scroll tracking should be allowed
+     * Similar to shouldTrack() but also checks scroll-specific conditions
+     */
+    shouldTrackScroll(previousScrollY: number, currentScrollY: number): {
+        shouldTrack: boolean;
+        reason?: string;
+    };
+    /**
+     * Get all active policies as object (for monitoring/debugging)
+     */
+    getPolicies(): {
+        maxSectionDuration: number;
+        minScrollDistance: number;
+        idleThreshold: number;
+    };
+    /**
+     * Get current tracking state (for monitoring/debugging)
+     */
+    getTrackingState(): {
+        isPageVisible: boolean;
+        isUserActive: boolean;
+        timeSinceLastActivity: number;
+        activeSections: number;
+    };
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Destroy and cleanup
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=attention-quality.d.ts.map

package/dist/attention-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention-quality.d.ts","sourceRoot":"","sources":["../src/attention-quality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAQD,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAAwE;IACvF,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,uBAAuB,CAA6B;IAG5D,OAAO,CAAC,aAAa,CAA4C;IAGjE,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,gBAAgB,EAAE,gBAAgB,EAAE,OAAO,GAAE,uBAA4B;IAWrF;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAqBnC;;;OAGG;IACH,WAAW,IAAI,OAAO;IAiBtB;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG;QAC/D,WAAW,EAAE,OAAO,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B;IAkDD;;;;OAIG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAWpE;;;OAGG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IASvC;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAQxB;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAIvE;;OAEG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC;;;OAGG;IACH,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG;QAClE,WAAW,EAAE,OAAO,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAuBD;;OAEG;IACH,WAAW,IAAI;QACb,kBAAkB,EAAE,MAAM,CAAC;QAC3B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;KACvB;IAQD;;OAEG;IACH,gBAAgB,IAAI;QAClB,aAAa,EAAE,OAAO,CAAC;QACvB,YAAY,EAAE,OAAO,CAAC;QACtB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,cAAc,EAAE,MAAM,CAAC;KACxB;IASD;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,IAAI,IAAI;CAchB"}

package/dist/attention-quality.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * Attention Quality Manager for Grain Analytics
+ * Enforces policies to ensure tracked data represents genuine user attention
+ *
+ * Policies:
+ * 1. Page Visibility: Stop tracking when tab is hidden/backgrounded
+ * 2. User Activity: Stop tracking when user is idle (no mouse/keyboard/touch)
+ * 3. Section Duration Cap: Max attention per section before requiring transition
+ * 4. Scroll Distance: Minimum scroll distance to count as meaningful engagement
+ *
+ * See: ATTENTION_QUALITY_POLICY.md for detailed policy documentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttentionQualityManager = void 0;
+const DEFAULT_OPTIONS = {
+    maxSectionDuration: 9000, // 9 seconds
+    minScrollDistance: 100, // 100 pixels
+    idleThreshold: 30000, // 30 seconds
+};
+class AttentionQualityManager {
+    constructor(activityDetector, options = {}) {
+        this.isDestroyed = false;
+        // Page visibility tracking
+        this.isPageVisible = true;
+        this.visibilityChangeHandler = null;
+        // Section attention state
+        this.sectionStates = 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');
+                // Reset all section states when page becomes visible again
+                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() {
+        // Policy 1: Page Visibility
+        if (!this.isPageVisible) {
+            this.lastFilterReason = 'page_hidden';
+            return false;
+        }
+        // Policy 2: User Activity
+        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) {
+        // First check global tracking state
+        if (!this.shouldTrack()) {
+            return {
+                shouldTrack: false,
+                reason: this.lastFilterReason || 'global_policy',
+            };
+        }
+        // Get or create section state
+        let state = this.sectionStates.get(sectionName);
+        if (!state) {
+            state = {
+                sectionName,
+                currentDuration: 0,
+                lastScrollPosition: currentScrollY,
+                lastResetTime: Date.now(),
+            };
+            this.sectionStates.set(sectionName, state);
+        }
+        // Policy 4: Scroll Distance - Check if user has scrolled enough to reset attention
+        const scrollDistance = Math.abs(currentScrollY - state.lastScrollPosition);
+        const hasScrolledEnough = scrollDistance >= this.options.minScrollDistance;
+        if (hasScrolledEnough) {
+            // Reset attention timer due to meaningful scroll
+            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,
+            };
+        }
+        // Policy 3: Section Duration Cap
+        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) {
+        // First check global tracking state
+        if (!this.shouldTrack()) {
+            return {
+                shouldTrack: false,
+                reason: this.lastFilterReason || 'global_policy',
+            };
+        }
+        // Check if scroll is meaningful
+        const scrollDistance = Math.abs(currentScrollY - previousScrollY);
+        if (scrollDistance < 10) { // Minimum 10px to count as scroll
+            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;
+        // Remove visibility change listener
+        if (this.visibilityChangeHandler && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.visibilityChangeHandler);
+            this.visibilityChangeHandler = null;
+        }
+        // Clear section states
+        this.sectionStates.clear();
+    }
+}
+exports.AttentionQualityManager = AttentionQualityManager;
+//# sourceMappingURL=attention-quality.js.map

package/dist/cjs/attention-quality.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Attention Quality Manager for Grain Analytics
+ * Enforces policies to ensure tracked data represents genuine user attention
+ *
+ * Policies:
+ * 1. Page Visibility: Stop tracking when tab is hidden/backgrounded
+ * 2. User Activity: Stop tracking when user is idle (no mouse/keyboard/touch)
+ * 3. Section Duration Cap: Max attention per section before requiring transition
+ * 4. Scroll Distance: Minimum scroll distance to count as meaningful engagement
+ *
+ * See: ATTENTION_QUALITY_POLICY.md for detailed policy documentation
+ */
+import type { ActivityDetector } from './activity';
+export interface AttentionQualityOptions {
+    /**
+     * Maximum continuous attention duration per section (ms)
+     * Default: 9000 (9 seconds)
+     */
+    maxSectionDuration?: number;
+    /**
+     * Minimum scroll distance to reset attention timer (px)
+     * Default: 100
+     */
+    minScrollDistance?: number;
+    /**
+     * Idle threshold - stop tracking after this period of inactivity (ms)
+     * Default: 30000 (30 seconds)
+     */
+    idleThreshold?: number;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+interface SectionAttentionState {
+    sectionName: string;
+    currentDuration: number;
+    lastScrollPosition: number;
+    lastResetTime: number;
+}
+export declare class AttentionQualityManager {
+    private options;
+    private activityDetector;
+    private isDestroyed;
+    private isPageVisible;
+    private visibilityChangeHandler;
+    private sectionStates;
+    private lastFilterReason;
+    constructor(activityDetector: ActivityDetector, options?: AttentionQualityOptions);
+    /**
+     * Setup page visibility tracking
+     */
+    private setupPageVisibilityTracking;
+    /**
+     * Check if tracking should be allowed (global check)
+     * Returns true if tracking is allowed, false if it should be paused
+     */
+    shouldTrack(): boolean;
+    /**
+     * 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: string, currentScrollY: number): {
+        shouldTrack: boolean;
+        reason?: string;
+        resetAttention?: boolean;
+    };
+    /**
+     * 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: string, durationMs: number): void;
+    /**
+     * Reset attention for a specific section (call when user navigates to different section)
+     * @param sectionName - Section identifier
+     */
+    resetSection(sectionName: string): void;
+    /**
+     * Reset all section attention states
+     */
+    resetAllSections(): void;
+    /**
+     * Get current attention state for a section (for debugging/monitoring)
+     */
+    getSectionState(sectionName: string): SectionAttentionState | undefined;
+    /**
+     * Get reason why last tracking attempt was filtered
+     */
+    getLastFilterReason(): string | null;
+    /**
+     * Check if scroll tracking should be allowed
+     * Similar to shouldTrack() but also checks scroll-specific conditions
+     */
+    shouldTrackScroll(previousScrollY: number, currentScrollY: number): {
+        shouldTrack: boolean;
+        reason?: string;
+    };
+    /**
+     * Get all active policies as object (for monitoring/debugging)
+     */
+    getPolicies(): {
+        maxSectionDuration: number;
+        minScrollDistance: number;
+        idleThreshold: number;
+    };
+    /**
+     * Get current tracking state (for monitoring/debugging)
+     */
+    getTrackingState(): {
+        isPageVisible: boolean;
+        isUserActive: boolean;
+        timeSinceLastActivity: number;
+        activeSections: number;
+    };
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Destroy and cleanup
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=attention-quality.d.ts.map

package/dist/cjs/attention-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention-quality.d.ts","sourceRoot":"","sources":["../../src/attention-quality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAQD,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAAwE;IACvF,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,uBAAuB,CAA6B;IAG5D,OAAO,CAAC,aAAa,CAA4C;IAGjE,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,gBAAgB,EAAE,gBAAgB,EAAE,OAAO,GAAE,uBAA4B;IAWrF;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAqBnC;;;OAGG;IACH,WAAW,IAAI,OAAO;IAiBtB;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG;QAC/D,WAAW,EAAE,OAAO,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B;IAkDD;;;;OAIG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAWpE;;;OAGG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IASvC;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAQxB;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAIvE;;OAEG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC;;;OAGG;IACH,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG;QAClE,WAAW,EAAE,OAAO,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAuBD;;OAEG;IACH,WAAW,IAAI;QACb,kBAAkB,EAAE,MAAM,CAAC;QAC3B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;KACvB;IAQD;;OAEG;IACH,gBAAgB,IAAI;QAClB,aAAa,EAAE,OAAO,CAAC;QACvB,YAAY,EAAE,OAAO,CAAC;QACtB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,cAAc,EAAE,MAAM,CAAC;KACxB;IASD;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,IAAI,IAAI;CAchB"}