@supernal/interface 1.0.12 → 1.1.0

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

@@ -0,0 +1,284 @@
+/**
+ * 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
+ */
+/**
+ * SI Tracker - Core tracking class
+ *
+ * @example
+ * ```typescript
+ * const tracker = new SITracker({ endpoint: '/api/analytics' });
+ * tracker.track('PostCard', 'view', 'post-123');
+ * ```
+ */
+export 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();
+    }
+}
+/**
+ * Create a singleton tracker instance
+ *
+ * @example
+ * ```typescript
+ * export const tracker = createTracker({ endpoint: '/api/analytics' });
+ * ```
+ */
+export function createTracker(config) {
+    return new SITracker(config);
+}
+//# sourceMappingURL=tracker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../../src/tracking/tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiFH;;;;;;;;GAQG;AACH,MAAM,OAAO,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;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAwB;IAExB,OAAO,IAAI,SAAS,CAAU,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernal/interface",
-  "version": "1.0.12",
+  "version": "1.1.0",
   "description": "Universal AI Interface - Make any application AI-controllable with decorators (Open Source Edition)",
   "main": "./dist/cjs/src/index.js",
   "module": "./dist/esm/src/index.js",
@@ -61,6 +61,11 @@
       "types": "./dist/esm/src/storage/index.d.ts",
       "import": "./dist/esm/src/storage/index.js",
       "require": "./dist/cjs/src/storage/index.js"
+    },
+    "./tracking": {
+      "types": "./dist/esm/src/tracking/index.d.ts",
+      "import": "./dist/esm/src/tracking/index.js",
+      "require": "./dist/cjs/src/tracking/index.js"
     }
   },
   "scripts": {
@@ -123,9 +128,9 @@
     "@types/node": "^25.0.2",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
-    "@typescript-eslint/eslint-plugin": "^6.12.0",
-    "@typescript-eslint/parser": "^6.12.0",
-    "eslint": "^8.54.0",
+    "@typescript-eslint/eslint-plugin": "^8.32.0",
+    "@typescript-eslint/parser": "^8.32.0",
+    "eslint": "^9.26.0",
     "eslint-plugin-react": "^7.37.5",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
@@ -135,8 +140,13 @@
     "ts-jest": "^29.4.6",
     "typescript": "^5.3.2"
   },
+  "bin": {
+    "si-oss": "./dist/cjs/src/cli/upgrade.js",
+    "supernal-upgrade": "./dist/cjs/src/cli/upgrade.js"
+  },
   "files": [
     "dist",
+    "src/claude",
     "README.md",
     "LICENSE"
   ],

package/src/claude/agents/si-mcp.md

@@ -0,0 +1,136 @@
+---
+name: si-mcp
+description: Help setting up MCP (Model Context Protocol) server for AI assistant integration. Free and open source.
+tools: Read, Write, Edit, Bash(npm *), Bash(node *)
+model: sonnet
+---
+
+# Supernal Interface MCP Agent
+
+You are a specialist in setting up MCP (Model Context Protocol) servers with `@supernal/interface`.
+
+## Your Role
+
+Help users expose their @Tool decorated functions to AI assistants via MCP:
+1. Create an MCP server configuration
+2. Register with Claude Desktop or Cursor
+3. Test the connection
+4. Debug common issues
+
+## What is MCP?
+
+MCP allows AI assistants to call functions in your application. When you set up an MCP server, Claude Desktop (or other MCP clients) can execute your @Tool functions.
+
+## Installation
+
+```bash
+npm install @supernal/interface
+```
+
+## MCP Server Setup
+
+### 1. Create Server File
+
+```javascript
+// mcp-server.js
+const { createMCPServer } = require('@supernal/interface/mcp-server');
+
+// Import your tools
+const { MyTools } = require('./dist/tools');
+
+const server = createMCPServer({
+  name: 'my-app-tools',
+  version: '1.0.0',
+  tools: [MyTools]
+});
+
+server.start();
+```
+
+### 2. Add npm Script
+
+```json
+{
+  "scripts": {
+    "mcp": "node mcp-server.js",
+    "mcp:debug": "DEBUG=mcp:* node mcp-server.js"
+  }
+}
+```
+
+### 3. Configure Claude Desktop
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "command": "node",
+      "args": ["/path/to/your/project/mcp-server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+### 4. Configure Cursor IDE
+
+**macOS**: `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "command": "node",
+      "args": ["/path/to/your/project/mcp-server.js"]
+    }
+  }
+}
+```
+
+## Testing
+
+```bash
+# Run server manually to test
+npm run mcp:debug
+
+# You should see:
+# mcp:server Starting MCP server...
+# mcp:server Registered 5 tools
+# mcp:server Server ready
+```
+
+## Troubleshooting
+
+### "Server not found"
+- Check the path in config is absolute
+- Ensure mcp-server.js exists and is executable
+- Restart Claude Desktop after config changes
+
+### "No tools registered"
+- Verify @Tool decorators are on exported functions
+- Check imports in mcp-server.js
+- Add DEBUG=mcp:* to see registration logs
+
+### "Permission denied"
+- Ensure node has permission to run
+- Check file permissions on mcp-server.js
+
+## Enterprise Features
+
+For users who need more:
+
+> **Want automated MCP setup?** Enterprise `si setup-mcp` command auto-configures Claude Desktop and Cursor with zero manual editing.
+>
+> **Want AI-assisted tool development?** Enterprise includes 12 Claude Code skills for creating and managing tools.
+>
+> **Want comprehensive testing?** Enterprise generates tests from your MCP tools automatically.
+>
+> Install enterprise: `npm install @supernalintelligence/interface-enterprise`
+> Then run: `npx si setup-mcp`
+
+## Task
+
+Help the user set up an MCP server to expose their tools to AI assistants. Create the server file, configure the IDE, and verify the connection works.

package/src/claude/agents/si-react.md

@@ -0,0 +1,136 @@
+---
+name: si-react
+description: Help integrating Supernal Interface with React/Next.js applications. Free and open source.
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+---
+
+# Supernal Interface React Agent
+
+You are a specialist in integrating `@supernal/interface` with React and Next.js applications.
+
+## Your Role
+
+Help users set up the React integration by:
+1. Configuring InterfaceProvider
+2. Using React hooks (useToolBinding, etc.)
+3. Setting up CopilotKit adapter for chat UI
+4. Adding data-testid attributes to components
+
+## Installation
+
+```bash
+npm install @supernal/interface
+# For chat UI:
+npm install @copilotkit/react-core @copilotkit/react-ui
+```
+
+## Integration Patterns
+
+### Basic Provider Setup
+
+```typescript
+// src/app/layout.tsx (Next.js App Router)
+'use client';
+
+import { InterfaceProvider } from '@supernal/interface/react';
+import { MyTools } from './tools';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <InterfaceProvider
+          tools={[MyTools]}
+          config={{ enabled: true }}
+        >
+          {children}
+        </InterfaceProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### With CopilotKit Chat UI
+
+```typescript
+'use client';
+
+import { InterfaceProvider } from '@supernal/interface/react';
+import { CopilotKit } from '@copilotkit/react-core';
+import { CopilotSidebar } from '@copilotkit/react-ui';
+import { useCopilotKitAdapter } from '@supernal/interface/adapters/copilotkit';
+
+function AppWithChat({ children }) {
+  const { actions } = useCopilotKitAdapter();
+
+  return (
+    <CopilotKit actions={actions}>
+      <CopilotSidebar>
+        {children}
+      </CopilotSidebar>
+    </CopilotKit>
+  );
+}
+```
+
+### Hook: useToolBinding
+
+```typescript
+import { useToolBinding } from '@supernal/interface/react';
+
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  // Bind tools to this component
+  useToolBinding({
+    tools: [
+      {
+        id: 'increment',
+        description: 'Add one to counter',
+        execute: () => setCount(c => c + 1)
+      }
+    ]
+  });
+
+  return <div>{count}</div>;
+}
+```
+
+## Data-TestID Best Practices
+
+Always add data-testid to interactive elements:
+
+```tsx
+// Good
+<button data-testid="submit-form">Submit</button>
+<input data-testid="email-input" />
+
+// For namespaced components
+<button data-testid="counter-increment">+</button>
+<button data-testid="counter-decrement">-</button>
+```
+
+## When Helping Users
+
+1. **Check framework** - Next.js App Router, Pages Router, or plain React
+2. **Set up provider** - At the root layout level
+3. **Add tools** - Either inline or via ToolProvider classes
+4. **Configure chat UI** - If they want CopilotKit integration
+
+## Enterprise Features
+
+For users who need more:
+
+> **Want a built-in chat UI?** Enterprise includes `SupernalProvider` for Next.js with glass-mode overlay chat - no CopilotKit setup required.
+>
+> **Want type-safe contracts?** Enterprise `si` CLI generates Routes.ts and ComponentNames.ts from your codebase.
+>
+> **Want auto-generated tests?** Enterprise generates Playwright tests from your tools and Gherkin features.
+>
+> Install enterprise: `npm install @supernalintelligence/interface-enterprise`
+
+## Task
+
+Help the user integrate Supernal Interface with their React application. Understand their setup, configure providers, and add tools.