@supernal/interface 1.0.13 → 1.1.0

package/dist/cjs/src/tracking/tracker.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * Supernal Interface Interaction Tracking
+ *
+ * Tracks user interactions with SI components for analytics and AI analysis.
+ * Batches events to minimize network requests and handles offline gracefully.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SITracker = void 0;
+exports.createTracker = createTracker;
+/**
+ * SI Tracker - Core tracking class
+ *
+ * @example
+ * ```typescript
+ * const tracker = new SITracker({ endpoint: '/api/analytics' });
+ * tracker.track('PostCard', 'view', 'post-123');
+ * ```
+ */
+class SITracker {
+    constructor(config = {}) {
+        this.queue = [];
+        this.flushInterval = null;
+        this.engagementSessions = new Map();
+        this.scrollState = {
+            maxDepth: 0,
+            lastReportedDepth: 0,
+            lastUpdateTime: Date.now(),
+        };
+        this.userId = null;
+        this.config = {
+            endpoint: config.endpoint ?? '/api/v1/analytics',
+            batchSize: config.batchSize ?? 10,
+            flushIntervalMs: config.flushIntervalMs ?? 5000,
+            minEngagementMs: config.minEngagementMs ?? 3000,
+            scrollDebounceMs: config.scrollDebounceMs ?? 500,
+            debug: config.debug ?? false,
+            customFetch: config.customFetch ?? fetch,
+        };
+        this.isClient = typeof window !== 'undefined';
+        this.sessionId = this.generateSessionId();
+        if (this.isClient) {
+            this.startFlushInterval();
+            this.setupBeforeUnload();
+        }
+    }
+    /** Generate a unique session ID */
+    generateSessionId() {
+        if (!this.isClient)
+            return 'server-session';
+        // Try to reuse session ID from sessionStorage
+        const stored = sessionStorage.getItem('si_session_id');
+        if (stored)
+            return stored;
+        const id = `si_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
+        sessionStorage.setItem('si_session_id', id);
+        return id;
+    }
+    /** Log debug message */
+    log(...args) {
+        if (this.config.debug) {
+            console.log('[SI Tracking]', ...args);
+        }
+    }
+    /** Set the current user ID for tracking */
+    setUserId(userId) {
+        this.userId = userId;
+    }
+    /** Get current session ID */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /** Get queue length (for testing) */
+    getQueueLength() {
+        return this.queue.length;
+    }
+    /**
+     * Track an interaction
+     */
+    track(componentId, action, targetId, metadata) {
+        if (!this.isClient)
+            return;
+        const interaction = {
+            componentId,
+            action,
+            targetId,
+            metadata,
+            timestamp: Date.now(),
+            sessionId: this.sessionId,
+        };
+        this.queue.push(interaction);
+        this.log('Queued:', action, targetId);
+        // Flush if queue is full
+        if (this.queue.length >= this.config.batchSize) {
+            this.flush();
+        }
+    }
+    /** Alias for track - for click events */
+    trackClick(componentId, action, targetId, metadata) {
+        this.track(componentId, action, targetId, metadata);
+    }
+    /** Track view (impression) of a component */
+    trackView(componentId, targetId) {
+        this.track(componentId, 'view', targetId);
+    }
+    /** Start engagement tracking for a target */
+    startEngagement(targetId) {
+        if (!this.isClient)
+            return;
+        this.engagementSessions.set(targetId, {
+            targetId,
+            startTime: Date.now(),
+            scrollDepth: 0,
+            interactions: 0,
+        });
+        this.log('Engagement started:', targetId);
+    }
+    /** Record an interaction during engagement */
+    recordEngagementInteraction(targetId) {
+        const session = this.engagementSessions.get(targetId);
+        if (session) {
+            session.interactions++;
+        }
+    }
+    /** Update scroll depth for engagement session */
+    updateEngagementScrollDepth(targetId, depth) {
+        const session = this.engagementSessions.get(targetId);
+        if (session && depth > session.scrollDepth) {
+            session.scrollDepth = depth;
+        }
+    }
+    /** End engagement tracking and log the session */
+    endEngagement(targetId, componentId = 'Content') {
+        if (!this.isClient)
+            return;
+        const session = this.engagementSessions.get(targetId);
+        if (!session)
+            return;
+        const duration = Date.now() - session.startTime;
+        // Only track if engagement was meaningful
+        if (duration >= this.config.minEngagementMs) {
+            this.track(componentId, 'view', targetId, {
+                engagementDuration: duration,
+                scrollDepth: session.scrollDepth,
+                interactions: session.interactions,
+            });
+            this.log('Engagement ended:', targetId, { duration, ...session });
+        }
+        this.engagementSessions.delete(targetId);
+    }
+    /** Track scroll depth in feed */
+    trackScrollDepth(depth, componentId = 'Feed') {
+        if (!this.isClient)
+            return;
+        const now = Date.now();
+        // Only update if depth increased
+        if (depth > this.scrollState.maxDepth) {
+            this.scrollState.maxDepth = depth;
+        }
+        // Debounce reporting
+        if (now - this.scrollState.lastUpdateTime < this.config.scrollDebounceMs) {
+            return;
+        }
+        // Report at 25%, 50%, 75%, 100% milestones
+        const milestones = [25, 50, 75, 100];
+        const currentMilestone = milestones.find((m) => this.scrollState.maxDepth >= m && this.scrollState.lastReportedDepth < m);
+        if (currentMilestone) {
+            this.track(componentId, 'scroll', undefined, {
+                depth: currentMilestone,
+                maxDepth: this.scrollState.maxDepth,
+            });
+            this.scrollState.lastReportedDepth = currentMilestone;
+            this.log('Scroll milestone:', currentMilestone);
+        }
+        this.scrollState.lastUpdateTime = now;
+    }
+    /** Reset scroll tracking (e.g., on page navigation) */
+    resetScrollTracking() {
+        this.scrollState = {
+            maxDepth: 0,
+            lastReportedDepth: 0,
+            lastUpdateTime: Date.now(),
+        };
+    }
+    /** Start periodic flush interval */
+    startFlushInterval() {
+        if (this.flushInterval)
+            return;
+        this.flushInterval = setInterval(() => {
+            this.flush();
+        }, this.config.flushIntervalMs);
+    }
+    /** Stop flush interval */
+    stopFlushInterval() {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+            this.flushInterval = null;
+        }
+    }
+    /** Setup beforeunload handler to flush remaining events */
+    setupBeforeUnload() {
+        window.addEventListener('beforeunload', () => {
+            // End all engagement sessions
+            for (const targetId of this.engagementSessions.keys()) {
+                this.endEngagement(targetId);
+            }
+            // Use sendBeacon for reliable delivery
+            this.flushWithBeacon();
+        });
+        // Also handle visibility change for mobile
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden') {
+                this.flushWithBeacon();
+            }
+        });
+    }
+    /** Flush queued events to the API */
+    async flush() {
+        if (!this.isClient || this.queue.length === 0)
+            return;
+        const events = [...this.queue];
+        this.queue = [];
+        this.log('Flushing', events.length, 'events');
+        try {
+            const response = await this.config.customFetch(this.config.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    events,
+                    userId: this.userId,
+                }),
+            });
+            if (!response.ok) {
+                // Re-queue events on failure (with limit to prevent infinite growth)
+                if (this.queue.length < this.config.batchSize * 3) {
+                    this.queue.unshift(...events);
+                }
+                this.log('Flush failed, re-queued');
+            }
+        }
+        catch (error) {
+            // Re-queue events on network error
+            if (this.queue.length < this.config.batchSize * 3) {
+                this.queue.unshift(...events);
+            }
+            console.warn('[SI Tracking] Failed to flush events:', error);
+        }
+    }
+    /** Flush using sendBeacon (for unload events) */
+    flushWithBeacon() {
+        if (!this.isClient || this.queue.length === 0)
+            return;
+        const events = [...this.queue];
+        this.queue = [];
+        try {
+            const blob = new Blob([JSON.stringify({ events, userId: this.userId })], {
+                type: 'application/json',
+            });
+            navigator.sendBeacon(this.config.endpoint, blob);
+            this.log('Beacon sent', events.length, 'events');
+        }
+        catch (error) {
+            console.warn('[SI Tracking] Beacon failed:', error);
+        }
+    }
+    /** Cleanup (for testing or unmounting) */
+    destroy() {
+        this.stopFlushInterval();
+        this.flush();
+        this.engagementSessions.clear();
+    }
+}
+exports.SITracker = SITracker;
+/**
+ * Create a singleton tracker instance
+ *
+ * @example
+ * ```typescript
+ * export const tracker = createTracker({ endpoint: '/api/analytics' });
+ * ```
+ */
+function createTracker(config) {
+    return new SITracker(config);
+}
+//# sourceMappingURL=tracker.js.map

package/dist/cjs/src/tracking/tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../../src/tracking/tracker.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAqZH,sCAIC;AAxUD;;;;;;;;GAQG;AACH,MAAa,SAAS;IAcpB,YAAY,SAA0B,EAAE;QAbhC,UAAK,GAA6B,EAAE,CAAC;QAErC,kBAAa,GAA0C,IAAI,CAAC;QAC5D,uBAAkB,GAAmC,IAAI,GAAG,EAAE,CAAC;QAC/D,gBAAW,GAAgB;YACjC,QAAQ,EAAE,CAAC;YACX,iBAAiB,EAAE,CAAC;YACpB,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE;SAC3B,CAAC;QAEM,WAAM,GAAkB,IAAI,CAAC;QAInC,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,mBAAmB;YAChD,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE;YACjC,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;YAC/C,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;YAC/C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,GAAG;YAChD,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;YAC5B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,KAAK;SACzC,CAAC;QAEF,IAAI,CAAC,QAAQ,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAE1C,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC1B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,mCAAmC;IAC3B,iBAAiB;QACvB,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO,gBAAgB,CAAC;QAE5C,8CAA8C;QAC9C,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACvD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACrF,cAAc,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;QAC5C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,wBAAwB;IAChB,GAAG,CAAC,GAAG,IAAe;QAC5B,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,SAAS,CAAC,MAAqB;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,6BAA6B;IAC7B,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,qCAAqC;IACrC,cAAc;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CACH,WAAmB,EACnB,MAAe,EACf,QAAiB,EACjB,QAAkC;QAElC,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE3B,MAAM,WAAW,GAA2B;YAC1C,WAAW;YACX,MAAM;YACN,QAAQ;YACR,QAAQ;YACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QAEtC,yBAAyB;QACzB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,UAAU,CACR,WAAmB,EACnB,MAAe,EACf,QAAiB,EACjB,QAAkC;QAElC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;IAED,6CAA6C;IAC7C,SAAS,CAAC,WAAmB,EAAE,QAAiB;QAC9C,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAiB,EAAE,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED,6CAA6C;IAC7C,eAAe,CAAC,QAAgB;QAC9B,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE3B,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,EAAE;YACpC,QAAQ;YACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,8CAA8C;IAC9C,2BAA2B,CAAC,QAAgB;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;IAED,iDAAiD;IACjD,2BAA2B,CAAC,QAAgB,EAAE,KAAa;QACzD,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,OAAO,IAAI,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAC3C,OAAO,CAAC,WAAW,GAAG,KAAK,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,aAAa,CAAC,QAAgB,EAAE,WAAW,GAAG,SAAS;QACrD,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE3B,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;QAEhD,0CAA0C;QAC1C,IAAI,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;YAC5C,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,MAAiB,EAAE,QAAQ,EAAE;gBACnD,kBAAkB,EAAE,QAAQ;gBAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,YAAY,EAAE,OAAO,CAAC,YAAY;aACnC,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,iCAAiC;IACjC,gBAAgB,CAAC,KAAa,EAAE,WAAW,GAAG,MAAM;QAClD,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,iCAAiC;QACjC,IAAI,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;YACtC,IAAI,CAAC,WAAW,CAAC,QAAQ,GAAG,KAAK,CAAC;QACpC,CAAC;QAED,qBAAqB;QACrB,IAAI,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;YACzE,OAAO;QACT,CAAC;QAED,2CAA2C;QAC3C,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACrC,MAAM,gBAAgB,GAAG,UAAU,CAAC,IAAI,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,IAAI,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,iBAAiB,GAAG,CAAC,CAChF,CAAC;QAEF,IAAI,gBAAgB,EAAE,CAAC;YACrB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,QAAmB,EAAE,SAAS,EAAE;gBACtD,KAAK,EAAE,gBAAgB;gBACvB,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ;aACpC,CAAC,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;YACtD,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,cAAc,GAAG,GAAG,CAAC;IACxC,CAAC;IAED,uDAAuD;IACvD,mBAAmB;QACjB,IAAI,CAAC,WAAW,GAAG;YACjB,QAAQ,EAAE,CAAC;YACX,iBAAiB,EAAE,CAAC;YACpB,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE;SAC3B,CAAC;IACJ,CAAC;IAED,oCAAoC;IAC5B,kBAAkB;QACxB,IAAI,IAAI,CAAC,aAAa;YAAE,OAAO;QAE/B,IAAI,CAAC,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE;YACpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAClC,CAAC;IAED,0BAA0B;IAClB,iBAAiB;QACvB,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAClC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,2DAA2D;IACnD,iBAAiB;QACvB,MAAM,CAAC,gBAAgB,CAAC,cAAc,EAAE,GAAG,EAAE;YAC3C,8BAA8B;YAC9B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,EAAE,CAAC;gBACtD,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC;YAED,uCAAuC;YACvC,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,2CAA2C;QAC3C,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,GAAG,EAAE;YACjD,IAAI,QAAQ,CAAC,eAAe,KAAK,QAAQ,EAAE,CAAC;gBAC1C,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEtD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAEhB,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAE9C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;gBACnE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;iBACnC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,MAAM;oBACN,MAAM,EAAE,IAAI,CAAC,MAAM;iBACpB,CAAC;aACH,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,qEAAqE;gBACrE,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;oBAClD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;gBAChC,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;gBAClD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;YAChC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,uCAAuC,EAAE,KAAK,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IAED,iDAAiD;IACzC,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEtD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAEhB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE;gBACvE,IAAI,EAAE,kBAAkB;aACzB,CAAC,CAAC;YACH,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACjD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,OAAO;QACL,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;IAClC,CAAC;CACF;AAjTD,8BAiTC;AAED;;;;;;;GAOG;AACH,SAAgB,aAAa,CAC3B,MAAwB;IAExB,OAAO,IAAI,SAAS,CAAU,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/dist/esm/src/index.d.ts

@@ -50,4 +50,7 @@ export { TreeBuilder } from './background/navigation/RuntimeTreeBuilder';
 export { LocationContext } from './background/location/LocationContext';
 export declare const VERSION = "1.1.0";
 export declare const PACKAGE_NAME = "@supernal/interface";
+export { SITracker, createTracker, type SITrackerConfig, type SIInteraction, type SIBaseAction, } from './tracking/tracker';
+export { SITrackerProvider, useTracker, useSITrackingInit, useTrackClick, useTrackView, useTrackEngagement, useTrackScrollDepth, useTrackVisibility, createComponentTrackingHook, } from './tracking/hooks';
+export { TrackingProvider, withTracking, type SITrackingProviderProps, } from './tracking/SITrackingProvider';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,GACf,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,SAAS,EACT,eAAe,EACf,QAAQ,EACT,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,MAAM,EACN,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,EACb,cAAc,EACd,aAAa,EACb,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,UAAU,EACV,aAAa,EACb,WAAW,EACX,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,UAAU,GACX,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAG/F,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAGxF,cAAc,WAAW,CAAC;AAG1B,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD,cAAc,WAAW,CAAC;AAG1B,cAAc,QAAQ,CAAC;AAGvB,OAAO,KAAK,KAAK,MAAM,UAAU,CAAC;AAGlC,OAAO,EACL,eAAe,EAEf,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAQlB,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGzC,cAAc,SAAS,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGlE,cAAc,MAAM,CAAC;AAGrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGjE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACnF,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC9F,YAAY,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAGhF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAEL,aAAa,EACb,WAAW,EACX,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EAEpB,cAAc,EACd,MAAM,EACN,SAAS,EACT,iBAAiB,EACjB,UAAU,EAKV,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,uBAAuB,EACvB,yBAAyB,EACzB,2BAA2B,EAC3B,iBAAiB,EACjB,aAAa,IAAI,iBAAiB,GACnC,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACpB,MAAM,oCAAoC,CAAC;AAO5C,YAAY,EACV,SAAS,EACT,eAAe,EACf,YAAY,EACZ,UAAU,EACV,WAAW,EACX,OAAO,EACP,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,OAAO,CAAC;AAGf,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC1E,YAAY,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,eAAO,MAAM,OAAO,UAAU,CAAC;AAC/B,eAAO,MAAM,YAAY,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/index.js

@@ -76,6 +76,10 @@ export { LocationContext } from './background/location/LocationContext.js';
 // Version info
 export const VERSION = '1.1.0'; // Updated for MCP + State Management
 export const PACKAGE_NAME = '@supernal/interface';
+// Interaction Tracking
+export { SITracker, createTracker, } from './tracking/tracker.js';
+export { SITrackerProvider, useTracker, useSITrackingInit, useTrackClick, useTrackView, useTrackEngagement, useTrackScrollDepth, useTrackVisibility, createComponentTrackingHook, } from './tracking/hooks.js';
+export { TrackingProvider, withTracking, } from './tracking/SITrackingProvider.js';
 // Enterprise features not included in open source
 // Available at https://supernal.ai/enterprise:
 // - Test Generation (TestGenerator, ComponentTestGenerator, DocumentationGenerator)

package/dist/esm/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/tracking/SITrackingProvider.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SI Tracking Provider Component
+ *
+ * React component that provides the tracker instance to the component tree.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { SITracker, SITrackerConfig } from './tracker';
+export interface SITrackingProviderProps {
+    children: React.ReactNode;
+    /** Tracker configuration */
+    config?: SITrackerConfig;
+    /** Pre-created tracker instance (overrides config) */
+    tracker?: SITracker;
+    /** Current user ID for tracking */
+    userId?: string | null;
+    /** Callback when tracker is created */
+    onTrackerCreated?: (tracker: SITracker) => void;
+}
+/**
+ * Provider component that initializes SI tracking for your app
+ *
+ * @example
+ * ```tsx
+ * // With config
+ * function App() {
+ *   const { user } = useAuth();
+ *   return (
+ *     <SITrackingProvider
+ *       config={{ endpoint: '/api/analytics' }}
+ *       userId={user?.id}
+ *     >
+ *       <YourApp />
+ *     </SITrackingProvider>
+ *   );
+ * }
+ *
+ * // With existing tracker
+ * const tracker = createTracker({ endpoint: '/api/analytics' });
+ *
+ * function App() {
+ *   return (
+ *     <SITrackingProvider tracker={tracker}>
+ *       <YourApp />
+ *     </SITrackingProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function TrackingProvider({ children, config, tracker: externalTracker, userId, onTrackerCreated, }: SITrackingProviderProps): React.JSX.Element;
+/**
+ * Higher-order component to inject tracker
+ *
+ * @example
+ * ```tsx
+ * const TrackedComponent = withTracking(MyComponent);
+ * // MyComponent receives `tracker` prop
+ * ```
+ */
+export declare function withTracking<P extends {
+    tracker?: SITracker | null;
+}>(WrappedComponent: React.ComponentType<P>): React.FC<Omit<P, 'tracker'>>;
+//# sourceMappingURL=SITrackingProvider.d.ts.map

package/dist/esm/src/tracking/SITrackingProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SITrackingProvider.d.ts","sourceRoot":"","sources":["../../../../src/tracking/SITrackingProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAiB,MAAM,WAAW,CAAC;AAGtE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sDAAsD;IACtD,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,OAAO,EAAE,eAAe,EACxB,MAAM,EACN,gBAAgB,GACjB,EAAE,uBAAuB,qBAuBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE,EACnE,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,GACvC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAU9B"}

package/dist/esm/src/tracking/SITrackingProvider.js

@@ -0,0 +1,82 @@
+/**
+ * SI Tracking Provider Component
+ *
+ * React component that provides the tracker instance to the component tree.
+ *
+ * @packageDocumentation
+ */
+'use client';
+import React, { useMemo, useEffect } from 'react';
+import { createTracker } from './tracker.js';
+import { SITrackerProvider, useSITrackingInit, useTracker } from './hooks.js';
+/**
+ * Provider component that initializes SI tracking for your app
+ *
+ * @example
+ * ```tsx
+ * // With config
+ * function App() {
+ *   const { user } = useAuth();
+ *   return (
+ *     <SITrackingProvider
+ *       config={{ endpoint: '/api/analytics' }}
+ *       userId={user?.id}
+ *     >
+ *       <YourApp />
+ *     </SITrackingProvider>
+ *   );
+ * }
+ *
+ * // With existing tracker
+ * const tracker = createTracker({ endpoint: '/api/analytics' });
+ *
+ * function App() {
+ *   return (
+ *     <SITrackingProvider tracker={tracker}>
+ *       <YourApp />
+ *     </SITrackingProvider>
+ *   );
+ * }
+ * ```
+ */
+export function TrackingProvider({ children, config, tracker: externalTracker, userId, onTrackerCreated, }) {
+    // Create or use provided tracker
+    const tracker = useMemo(() => {
+        if (externalTracker)
+            return externalTracker;
+        const newTracker = createTracker(config);
+        onTrackerCreated?.(newTracker);
+        return newTracker;
+    }, [externalTracker, config, onTrackerCreated]);
+    // Sync user ID
+    useSITrackingInit(tracker, userId);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            // Only destroy if we created the tracker
+            if (!externalTracker) {
+                tracker.destroy();
+            }
+        };
+    }, [tracker, externalTracker]);
+    return React.createElement(SITrackerProvider, { value: tracker }, children);
+}
+/**
+ * Higher-order component to inject tracker
+ *
+ * @example
+ * ```tsx
+ * const TrackedComponent = withTracking(MyComponent);
+ * // MyComponent receives `tracker` prop
+ * ```
+ */
+export function withTracking(WrappedComponent) {
+    // Inner component that uses the hook
+    function WithTrackingInner(props) {
+        const tracker = useTracker();
+        return React.createElement(WrappedComponent, { ...props, tracker: tracker });
+    }
+    WithTrackingInner.displayName = `withTracking(${WrappedComponent.displayName || WrappedComponent.name || 'Component'})`;
+    return WithTrackingInner;
+}
+//# sourceMappingURL=SITrackingProvider.js.map

package/dist/esm/src/tracking/SITrackingProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SITrackingProvider.js","sourceRoot":"","sources":["../../../../src/tracking/SITrackingProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,CAAC;AAEb,OAAO,KAAK,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAA8B,aAAa,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAc3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,OAAO,EAAE,eAAe,EACxB,MAAM,EACN,gBAAgB,GACQ;IACxB,iCAAiC;IACjC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE;QAC3B,IAAI,eAAe;YAAE,OAAO,eAAe,CAAC;QAC5C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACzC,gBAAgB,EAAE,CAAC,UAAU,CAAC,CAAC;QAC/B,OAAO,UAAU,CAAC;IACpB,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAEhD,eAAe;IACf,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEnC,qBAAqB;IACrB,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,yCAAyC;YACzC,IAAI,CAAC,eAAe,EAAE,CAAC;gBACrB,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;IAE/B,OAAO,oBAAC,iBAAiB,IAAC,KAAK,EAAE,OAAO,IAAG,QAAQ,CAAqB,CAAC;AAC3E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,gBAAwC;IAExC,qCAAqC;IACrC,SAAS,iBAAiB,CAAC,KAAyB;QAClD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,OAAO,oBAAC,gBAAgB,OAAM,KAAW,EAAE,OAAO,EAAE,OAAO,GAAI,CAAC;IAClE,CAAC;IAED,iBAAiB,CAAC,WAAW,GAAG,gBAAgB,gBAAgB,CAAC,WAAW,IAAI,gBAAgB,CAAC,IAAI,IAAI,WAAW,GAAG,CAAC;IAExH,OAAO,iBAAiB,CAAC;AAC3B,CAAC"}

package/dist/esm/src/tracking/hooks.d.ts

@@ -0,0 +1,112 @@
+/**
+ * SI Tracking React Hooks
+ *
+ * React hooks for integrating Supernal Interface tracking into components.
+ *
+ * @packageDocumentation
+ */
+import type { SITracker, SIBaseAction } from './tracker';
+export declare const SITrackerProvider: import("react").Provider<SITracker<SIBaseAction> | null>;
+/**
+ * Get the tracker instance from context
+ */
+export declare function useTracker<TAction extends string = SIBaseAction>(): SITracker<TAction> | null;
+/**
+ * Hook to sync auth state with tracker
+ * Place this once in your app layout
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { user } = useAuth();
+ *   useSITrackingInit(tracker, user?.id);
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export declare function useSITrackingInit(tracker: SITracker | null, userId: string | null | undefined): void;
+/**
+ * Hook for tracking click events
+ *
+ * @example
+ * ```tsx
+ * const trackClick = useTrackClick(tracker, 'PostCard');
+ * <button onClick={() => trackClick('like', postId)}>Like</button>
+ * ```
+ */
+export declare function useTrackClick<TAction extends string = SIBaseAction>(tracker: SITracker<TAction> | null, componentId: string): (action: TAction, targetId?: string, metadata?: Record<string, unknown>) => void;
+/**
+ * Hook for tracking component views (impressions)
+ * Automatically tracks when component mounts
+ *
+ * @example
+ * ```tsx
+ * useTrackView(tracker, 'PostCard', post.id);
+ * ```
+ */
+export declare function useTrackView(tracker: SITracker | null, componentId: string, targetId?: string, options?: {
+    trackOnMount?: boolean;
+}): void;
+/**
+ * Hook for tracking engagement time on a specific target
+ * Automatically handles start/end of engagement session
+ *
+ * @example
+ * ```tsx
+ * const { recordInteraction } = useTrackEngagement(tracker, post.id);
+ * <button onClick={recordInteraction}>Interact</button>
+ * ```
+ */
+export declare function useTrackEngagement(tracker: SITracker | null, targetId: string, componentId?: string): {
+    recordInteraction: () => void;
+};
+/**
+ * Hook for tracking scroll depth in feed
+ * Attach to a scrollable container
+ *
+ * @example
+ * ```tsx
+ * const { handleScroll, resetScroll } = useTrackScrollDepth(tracker);
+ * <div onScroll={handleScroll}>...</div>
+ * ```
+ */
+export declare function useTrackScrollDepth(tracker: SITracker | null, componentId?: string): {
+    handleScroll: (event: React.UIEvent<HTMLElement>) => void;
+    resetScroll: () => void;
+};
+/**
+ * Hook for tracking intersection observer visibility
+ * Useful for tracking when components come into view in feed
+ *
+ * @example
+ * ```tsx
+ * const ref = useTrackVisibility(tracker, 'PostCard', post.id);
+ * <div ref={ref}>...</div>
+ * ```
+ */
+export declare function useTrackVisibility(tracker: SITracker | null, componentId: string, targetId?: string, options?: {
+    threshold?: number;
+}): React.RefCallback<HTMLElement>;
+/**
+ * Create a component-specific tracking hook factory
+ *
+ * @example
+ * ```typescript
+ * // Define your actions
+ * type PostActions = 'like' | 'unlike' | 'share' | 'bookmark';
+ *
+ * // Create hooks for PostCard
+ * export function usePostCardTracking(tracker: SITracker<PostActions>, postId: string) {
+ *   const trackClick = useTrackClick(tracker, 'PostCard');
+ *   const visibilityRef = useTrackVisibility(tracker, 'PostCard', postId);
+ *
+ *   return {
+ *     trackLike: () => trackClick('like', postId),
+ *     trackShare: () => trackClick('share', postId),
+ *     visibilityRef,
+ *   };
+ * }
+ * ```
+ */
+export declare function createComponentTrackingHook<TAction extends string, TReturn>(componentId: string, factory: (trackClick: (action: TAction, targetId?: string, metadata?: Record<string, unknown>) => void, tracker: SITracker<TAction>, targetId: string) => TReturn): (tracker: SITracker<TAction> | null, targetId: string) => TReturn | null;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/esm/src/tracking/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../../src/tracking/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAKzD,eAAO,MAAM,iBAAiB,0DAA4B,CAAC;AAE3D;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAS,MAAM,GAAG,YAAY,KAAK,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAE7F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,IAAI,CAMN;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,SAAS,MAAM,GAAG,YAAY,EACjE,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,EAClC,WAAW,EAAE,MAAM,YAGR,OAAO,aAAa,MAAM,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAO1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,IAAI,CAQN;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,QAAQ,EAAE,MAAM,EAChB,WAAW,SAAY,GACtB;IACD,iBAAiB,EAAE,MAAM,IAAI,CAAC;CAC/B,CA0BA;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,WAAW,SAAS,GACnB;IACD,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAC1D,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB,CA8BA;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAgDhC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,SAAS,MAAM,EAAE,OAAO,EACzE,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CACP,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC5F,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,EAC3B,QAAQ,EAAE,MAAM,KACb,OAAO,IAGV,SAAS,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,EAClC,UAAU,MAAM,KACf,OAAO,GAAG,IAAI,CAOlB"}