@repliqo/sdk-react-native 0.3.8 → 0.4.0

package/dist/core/client.js

@@ -4,6 +4,7 @@ exports.AppAnalytics = void 0;
 const react_native_1 = require("react-native");
 const capture_1 = require("../snapshot/capture");
 const config_1 = require("./config");
+const storage_1 = require("./storage");
 const logger_1 = require("./logger");
 const api_client_1 = require("../transport/api.client");
 const batch_queue_1 = require("../transport/batch-queue");
@@ -18,6 +19,18 @@ class AppAnalytics {
         this.currentScreenEnteredAt = null;
         this.scrollOffsetY = 0;
         this.appStateSubscription = null;
+        /**
+         * User identity set via identify(). Kept for the process lifetime and
+         * automatically re-attached to every new session, so the host app only
+         * needs to call identify() once (e.g. after login).
+         */
+        this.identity = null;
+        /**
+         * Offline persistence backend (AsyncStorage-compatible). Null when the
+         * host app neither passed one nor has AsyncStorage installed — the SDK
+         * then behaves exactly as before (in-memory buffering only).
+         */
+        this.storage = null;
         /**
          * Registry of active ScrollViews on the current screen.
          * Each RepliqoScrollView registers its window-relative bounds and current
@@ -30,15 +43,63 @@ class AppAnalytics {
          * viewport position, while still mapping scrollable content correctly.
          */
         this.scrollViewRegistry = new Map();
+        /**
+         * Serialization chain for pending-crash read-modify-write operations.
+         * Two near-simultaneous crashes (e.g. an error cascade) would otherwise
+         * interleave getItem/setItem and lose one of the entries.
+         */
+        this.crashStoreLock = Promise.resolve();
+        /** Monotonic suffix so identical crashes get distinct keys. */
+        this.crashSeq = 0;
         this.config = (0, config_1.resolveConfig)(config);
         this.logger = new logger_1.Logger(this.config.debug);
         this.apiClient = new api_client_1.ApiClient(config_1.REPLIQO_API_URL, this.config.apiKey, this.logger);
-        this.eventQueue = new batch_queue_1.BatchQueue(this.config.batchSize, this.config.flushInterval, async (events) => {
-            if (!this.sessionId) {
-                this.logger.warn('Cannot flush events: no active session');
-                throw new Error('No active session');
+        // Events are stamped with their session at ENQUEUE time (__sessionId)
+        // and sent per session at flush time. Reading this.sessionId at flush
+        // time instead would attribute events buffered at the end of session A
+        // to session B if a new session starts before the flush.
+        //
+        // Delivery is per CONTIGUOUS RUN of same-session events (not a merged
+        // map) so the queue's prefix accounting stays exact even if sessions
+        // interleave in the buffer (e.g. restored old-session events landing
+        // between new-session events). On a transient failure we report the
+        // delivered prefix via PartialFlushError so the queue retries ONLY the
+        // remainder — never re-sending delivered events (duplicates) and never
+        // dropping unattempted ones alongside a poison run.
+        this.eventQueue = new batch_queue_1.BatchQueue(this.config.batchSize, this.config.flushInterval, async (queued) => {
+            // Split into contiguous same-session runs, preserving order.
+            const runs = [];
+            for (const { __sessionId, ...event } of queued) {
+                const last = runs[runs.length - 1];
+                if (last && last.sessionId === __sessionId) {
+                    last.events.push(event);
+                }
+                else {
+                    runs.push({ sessionId: __sessionId, events: [event] });
+                }
+            }
+            let consumed = 0;
+            for (const run of runs) {
+                try {
+                    await this.apiClient.sendEventsBatch(run.sessionId, run.events);
+                    consumed += run.events.length;
+                }
+                catch (err) {
+                    if (err instanceof batch_queue_1.NonRetryableFlushError) {
+                        // Poison run: permanently rejected. Count it as consumed
+                        // (dropped) and keep delivering the remaining runs.
+                        this.logger.warn(`Dropping ${run.events.length} events permanently rejected for session ${run.sessionId}`);
+                        consumed += run.events.length;
+                        continue;
+                    }
+                    // Transient failure: stop here. Anything already delivered or
+                    // dropped must not be retried.
+                    if (consumed > 0) {
+                        throw new batch_queue_1.PartialFlushError(consumed, true);
+                    }
+                    throw err;
+                }
             }
-            await this.apiClient.sendEventsBatch(this.sessionId, events);
         });
         this.screenVisitQueue = new batch_queue_1.BatchQueue(this.config.batchSize, this.config.flushInterval, async (visits) => {
             await this.apiClient.sendScreenVisitsBatch(visits);
@@ -61,14 +122,28 @@ class AppAnalytics {
             }, undefined, // default captureScreenshot provider
             (...args) => this.logger.log(...args), (...args) => this.logger.warn(...args));
         }
+        // Offline persistence: explicit storage from config, or auto-loaded
+        // AsyncStorage if the host app has it installed.
+        this.storage = this.config.storage ?? (0, storage_1.tryLoadAsyncStorage)();
         if (this.config.enableCrashTracking) {
             this.errorTracker = new error_tracker_1.ErrorTracker((crash) => {
-                // Crash reports are sent immediately (fire-and-forget), not batched
-                this.apiClient.sendCrashReport(crash).catch(() => { });
+                // Persist FIRST — on a fatal crash the app dies before the network
+                // request completes; the persisted copy is re-sent on next launch.
+                // Then send immediately and clear the persisted copy on success.
+                (async () => {
+                    const key = await this.persistCrash(crash);
+                    const sent = await this.apiClient.sendCrashReport(crash);
+                    if (sent && key) {
+                        await this.removePendingCrash(key);
+                    }
+                })().catch(() => { });
             });
             this.errorTracker.start();
         }
         this.setupAppStateListener();
+        // Re-send anything persisted by a previous run (events buffered at
+        // backgrounding, crashes whose send never completed).
+        this.restorePersistedData().catch(() => { });
         this.logger.log('SDK initialized with config:', {
             apiUrl: config_1.REPLIQO_API_URL,
             appId: this.config.appId,
@@ -112,17 +187,37 @@ class AppAnalytics {
                 instance.appStateSubscription.remove();
                 instance.appStateSubscription = null;
             }
-            // Attempt a final flush (fire-and-forget)
-            instance.flush().catch(() => { });
+            // Close the session on the server (also flushes remaining data).
+            // Fire-and-forget: destroy() is sync and must not block.
+            if (instance.sessionId) {
+                instance.endSession().catch(() => { });
+            }
+            else {
+                instance.flush().catch(() => { });
+            }
             AppAnalytics.instance = null;
         }
     }
     async startSession(deviceId, deviceInfo) {
+        // Calling startSession with a session already active would leak the
+        // previous session (left open forever on the backend) and strand its
+        // buffered events. Close it first.
+        if (this.sessionId) {
+            this.logger.warn('startSession called with an active session; ending it first');
+            await this.endSession();
+        }
         try {
             const response = await this.apiClient.startSession(deviceId, deviceInfo);
             this.sessionId = response.id;
             this.logger.log('Session started with ID:', this.sessionId);
             this.errorTracker?.setSessionId(this.sessionId);
+            // Re-attach a previously-set identity to the new session so the
+            // host app only needs to call identify() once per login.
+            if (this.identity) {
+                this.apiClient
+                    .identifySession(this.sessionId, this.identity.userId, this.identity.traits)
+                    .catch(() => { });
+            }
             if (this.snapshotCapture) {
                 this.snapshotCapture.setSessionId(this.sessionId);
                 this.snapshotCapture.reset();
@@ -223,12 +318,20 @@ class AppAnalytics {
             activeScrollOffset = 0;
             isFixed = true;
         }
+        else if (this.scrollOffsetY > 0) {
+            // No ScrollViews registered, but the host app is reporting scroll
+            // manually via setScrollOffset() (legacy integration without
+            // RepliqoScrollView). Honor it — otherwise those touches would be
+            // misclassified as fixed and land at the wrong heatmap position.
+            // Stale values are not a risk: onScreenEnter resets it to 0.
+            activeScrollOffset = this.scrollOffsetY;
+            isFixed = false;
+        }
         else {
-            // No ScrollViews registered at all. Two possible cases:
+            // No ScrollViews registered and no manual offset. Two cases:
             //   (a) The screen has no scrollable content → touch is fixed
             //   (b) RepliqoScrollView hasn't measured yet (first ~1 frame)
-            // Either way, marking as fixed is safer than guessing content
-            // position with stale scrollOffsetY from a previous screen.
+            // Either way, marking as fixed is safer than guessing.
             activeScrollOffset = 0;
             isFixed = true;
         }
@@ -245,7 +348,8 @@ class AppAnalytics {
             },
             timestamp: new Date().toISOString(),
         };
-        this.eventQueue.add(event);
+        // Stamp the ACTIVE session at enqueue time (see QueuedEvent).
+        this.eventQueue.add({ ...event, __sessionId: this.sessionId });
         this.logger.log('Touch tracked:', event);
     }
     trackNavigation(fromScreen, toScreen) {
@@ -262,7 +366,8 @@ class AppAnalytics {
             data: { fromScreen, toScreen },
             timestamp: new Date().toISOString(),
         };
-        this.eventQueue.add(event);
+        // Stamp the ACTIVE session at enqueue time (see QueuedEvent).
+        this.eventQueue.add({ ...event, __sessionId: this.sessionId });
         this.logger.log('Navigation tracked:', fromScreen, '->', toScreen);
     }
     trackCustomEvent(eventName, data) {
@@ -276,9 +381,40 @@ class AppAnalytics {
             data: { eventName, ...data },
             timestamp: new Date().toISOString(),
         };
-        this.eventQueue.add(event);
+        // Stamp the ACTIVE session at enqueue time (see QueuedEvent).
+        this.eventQueue.add({ ...event, __sessionId: this.sessionId });
         this.logger.log('Custom event tracked:', eventName);
     }
+    /**
+     * Identify the current user (call once after login). The identity is
+     * attached to the active session immediately and re-attached to every
+     * future session automatically until resetIdentity() is called.
+     *
+     * @param userId The host app's own user identifier.
+     * @param traits Optional free-form traits (plan, role, locale...).
+     *               Avoid PII you don't want stored (emails in plain text).
+     */
+    identify(userId, traits) {
+        if (!userId || typeof userId !== 'string') {
+            this.logger.warn('identify() requires a non-empty string userId');
+            return;
+        }
+        this.identity = { userId, traits };
+        this.logger.log('Identity set:', userId);
+        if (this.sessionId) {
+            this.apiClient
+                .identifySession(this.sessionId, userId, traits)
+                .catch(() => { });
+        }
+    }
+    /**
+     * Clear the stored identity (call on logout). Sessions started after
+     * this are anonymous again; already-identified sessions keep their user.
+     */
+    resetIdentity() {
+        this.identity = null;
+        this.logger.log('Identity cleared');
+    }
     reportError(error, metadata) {
         if (!this.errorTracker) {
             this.logger.warn('Cannot report error: crash tracking is not enabled');
@@ -365,6 +501,14 @@ class AppAnalytics {
         })();
     }
     onScreenEnter(screenName) {
+        // Re-entering the SAME screen (e.g. onReady + onStateChange both firing
+        // for the initial route) must not wipe the ScrollView registry that the
+        // screen's RepliqoScrollView already populated — touches in the gap
+        // until re-measure would be misclassified as fixed UI.
+        if (this.currentScreen === screenName) {
+            this.logger.log('Screen re-entered (no-op):', screenName);
+            return;
+        }
         this.currentScreen = screenName;
         this.currentScreenEnteredAt = new Date().toISOString();
         this.scrollOffsetY = 0;
@@ -447,6 +591,129 @@ class AppAnalytics {
     isInitialized() {
         return true;
     }
+    // ─── Offline persistence ────────────────────────────────────────────
+    /**
+     * Persist the un-flushed event buffer (called when backgrounding).
+     * Events carry their __sessionId stamp, so on restore they are still
+     * attributed to the session they belonged to.
+     */
+    async persistPendingEvents() {
+        if (!this.storage)
+            return;
+        try {
+            const pending = this.eventQueue.peekAll().slice(-storage_1.MAX_PERSISTED_EVENTS);
+            if (pending.length === 0) {
+                await this.storage.removeItem(storage_1.STORAGE_KEYS.pendingEvents);
+                return;
+            }
+            await this.storage.setItem(storage_1.STORAGE_KEYS.pendingEvents, JSON.stringify(pending));
+            this.logger.log('Persisted', pending.length, 'pending events');
+        }
+        catch (err) {
+            this.logger.warn('Failed to persist pending events:', err);
+        }
+    }
+    withCrashStoreLock(op) {
+        const run = this.crashStoreLock.then(op, op);
+        // Keep the chain alive regardless of op outcome.
+        this.crashStoreLock = run.catch(() => { });
+        return run;
+    }
+    /** Append a crash to the persisted pending list; returns its key. */
+    async persistCrash(crash) {
+        if (!this.storage)
+            return null;
+        const storage = this.storage;
+        try {
+            return await this.withCrashStoreLock(async () => {
+                const raw = await storage.getItem(storage_1.STORAGE_KEYS.pendingCrashes);
+                const list = raw
+                    ? JSON.parse(raw)
+                    : [];
+                // Unique per crash: identical timestamp+message pairs must not
+                // share a key or removePendingCrash would delete both.
+                const key = `${crash.timestamp}|${++this.crashSeq}|${crash.message}`.slice(0, 300);
+                list.push({ key, crash });
+                await storage.setItem(storage_1.STORAGE_KEYS.pendingCrashes, JSON.stringify(list.slice(-storage_1.MAX_PERSISTED_CRASHES)));
+                return key;
+            });
+        }
+        catch (err) {
+            this.logger.warn('Failed to persist crash:', err);
+            return null;
+        }
+    }
+    /** Remove a crash from the persisted pending list (after send success). */
+    async removePendingCrash(key) {
+        if (!this.storage)
+            return;
+        const storage = this.storage;
+        try {
+            await this.withCrashStoreLock(async () => {
+                const raw = await storage.getItem(storage_1.STORAGE_KEYS.pendingCrashes);
+                if (!raw)
+                    return;
+                const list = JSON.parse(raw);
+                const remaining = list.filter((entry) => entry.key !== key);
+                if (remaining.length === 0) {
+                    await storage.removeItem(storage_1.STORAGE_KEYS.pendingCrashes);
+                }
+                else {
+                    await storage.setItem(storage_1.STORAGE_KEYS.pendingCrashes, JSON.stringify(remaining));
+                }
+            });
+        }
+        catch {
+            // Best effort — a stale entry only means a duplicate crash report.
+        }
+    }
+    /**
+     * Restore data persisted by a previous run: re-enqueue events (still
+     * stamped with their original session) and re-send pending crashes.
+     * Called once from the constructor.
+     */
+    async restorePersistedData() {
+        if (!this.storage)
+            return;
+        // Events: re-enqueue and clear. They flush with the normal cycle.
+        try {
+            const raw = await this.storage.getItem(storage_1.STORAGE_KEYS.pendingEvents);
+            if (raw) {
+                await this.storage.removeItem(storage_1.STORAGE_KEYS.pendingEvents);
+                const events = JSON.parse(raw);
+                if (Array.isArray(events) && events.length > 0) {
+                    for (const event of events) {
+                        if (event && typeof event.__sessionId === 'string') {
+                            this.eventQueue.add(event);
+                        }
+                    }
+                    this.logger.log('Restored', events.length, 'persisted events');
+                }
+            }
+        }
+        catch (err) {
+            this.logger.warn('Failed to restore persisted events:', err);
+        }
+        // Crashes: send as a batch; clear only on success.
+        try {
+            const raw = await this.storage.getItem(storage_1.STORAGE_KEYS.pendingCrashes);
+            if (raw) {
+                const list = JSON.parse(raw);
+                if (Array.isArray(list) && list.length > 0) {
+                    await this.apiClient.sendCrashesBatch(list.map((e) => e.crash));
+                    await this.storage.removeItem(storage_1.STORAGE_KEYS.pendingCrashes);
+                    this.logger.log('Re-sent', list.length, 'persisted crash reports');
+                }
+                else {
+                    await this.storage.removeItem(storage_1.STORAGE_KEYS.pendingCrashes);
+                }
+            }
+        }
+        catch (err) {
+            // sendCrashesBatch throws on failure → keep the list for next launch.
+            this.logger.warn('Failed to re-send persisted crashes:', err);
+        }
+    }
     setupAppStateListener() {
         let wasInBackground = false;
         this.appStateSubscription = react_native_1.AppState.addEventListener('change', (nextAppState) => {
@@ -454,13 +721,34 @@ class AppAnalytics {
                 this.logger.log('App going to background, pausing snapshots + flushing');
                 this.stopSnapshotCapture();
                 wasInBackground = true;
-                this.flush().catch((error) => {
+                // Persist FIRST: iOS suspends JS within seconds of backgrounding,
+                // and a flush stalled on bad network (up to the 15s fetch timeout)
+                // would mean the persist never runs before the OS kills the app —
+                // exactly the scenario persistence exists for. A possible
+                // duplicate (flush succeeded after persisting) is the lesser
+                // evil, and the snapshot is refreshed after the flush anyway.
+                this.persistPendingEvents()
+                    .catch(() => { })
+                    .then(() => this.flush())
+                    .catch((error) => {
                     this.logger.error('Error flushing on app state change:', error);
+                })
+                    .finally(() => {
+                    // Refresh the snapshot with whatever is still undelivered
+                    // (empty ⇒ the key is removed, preventing stale re-sends).
+                    this.persistPendingEvents().catch(() => { });
                 });
             }
             else if (nextAppState === 'active' && wasInBackground) {
                 wasInBackground = false;
                 this.logger.log('App returned to foreground, resuming snapshots');
+                // The app survived the background stint — the in-memory buffer is
+                // authoritative again. Drop the persisted snapshot so a later
+                // crash doesn't re-send events that will be delivered normally
+                // from memory (it gets re-written on the next backgrounding).
+                if (this.storage) {
+                    this.storage.removeItem(storage_1.STORAGE_KEYS.pendingEvents).catch(() => { });
+                }
                 if (this.snapshotCapture && this.sessionId) {
                     this.startSnapshotCapture();
                 }

package/dist/core/config.d.ts

@@ -1,5 +1,5 @@
 import { SDKConfig } from '../types/events';
 export declare const REPLIQO_API_URL = "https://api-repliqo.odmservice.site";
-export declare const DEFAULT_CONFIG: Required<Omit<SDKConfig, 'apiKey' | 'appId'>>;
+export declare const DEFAULT_CONFIG: Required<Omit<SDKConfig, 'apiKey' | 'appId' | 'storage'>>;
 export type ResolvedConfig = SDKConfig & typeof DEFAULT_CONFIG;
 export declare function resolveConfig(config: SDKConfig): ResolvedConfig;

package/dist/core/config.js

@@ -24,5 +24,9 @@ exports.DEFAULT_CONFIG = {
     debug: false,
 };
 function resolveConfig(config) {
-    return { ...exports.DEFAULT_CONFIG, ...config };
+    // Strip keys whose value is explicitly `undefined` — otherwise
+    // `{ enableSnapshots: maybeUndefinedVar }` would silently override the
+    // default `true` with `undefined` and disable the feature.
+    const cleaned = Object.fromEntries(Object.entries(config).filter(([, v]) => v !== undefined));
+    return { ...exports.DEFAULT_CONFIG, ...cleaned };
 }

package/dist/core/storage.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal async key-value storage contract, compatible with
+ * @react-native-async-storage/async-storage (and trivially mockable).
+ *
+ * Used to persist analytics data across app kills:
+ *  - buffered events that couldn't be flushed before backgrounding
+ *  - crash reports (a fatal crash kills the app before the report's
+ *    network request can complete — persistence is the only way those
+ *    reports survive to the next launch)
+ */
+export interface PersistentStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Try to auto-load @react-native-async-storage/async-storage. Returns null
+ * when the host app doesn't have it installed — persistence is then
+ * disabled gracefully (in-memory only, pre-existing behavior).
+ */
+export declare function tryLoadAsyncStorage(): PersistentStorage | null;
+/** Storage keys namespaced to avoid colliding with the host app's data. */
+export declare const STORAGE_KEYS: {
+    readonly pendingEvents: "@repliqo/pending_events";
+    readonly pendingCrashes: "@repliqo/pending_crashes";
+};
+/** Caps so a long-offline device can't grow storage unboundedly. */
+export declare const MAX_PERSISTED_EVENTS = 500;
+export declare const MAX_PERSISTED_CRASHES = 20;

package/dist/core/storage.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PERSISTED_CRASHES = exports.MAX_PERSISTED_EVENTS = exports.STORAGE_KEYS = void 0;
+exports.tryLoadAsyncStorage = tryLoadAsyncStorage;
+/**
+ * Try to auto-load @react-native-async-storage/async-storage. Returns null
+ * when the host app doesn't have it installed — persistence is then
+ * disabled gracefully (in-memory only, pre-existing behavior).
+ */
+function tryLoadAsyncStorage() {
+    try {
+        const mod = require('@react-native-async-storage/async-storage');
+        const storage = mod?.default ?? mod;
+        if (storage &&
+            typeof storage.getItem === 'function' &&
+            typeof storage.setItem === 'function' &&
+            typeof storage.removeItem === 'function') {
+            return storage;
+        }
+    }
+    catch {
+        // Not installed — fine.
+    }
+    return null;
+}
+/** Storage keys namespaced to avoid colliding with the host app's data. */
+exports.STORAGE_KEYS = {
+    pendingEvents: '@repliqo/pending_events',
+    pendingCrashes: '@repliqo/pending_crashes',
+};
+/** Caps so a long-offline device can't grow storage unboundedly. */
+exports.MAX_PERSISTED_EVENTS = 500;
+exports.MAX_PERSISTED_CRASHES = 20;

package/dist/index.d.ts

@@ -12,5 +12,7 @@ export type { CrashReport } from './types/crash';
 export type { SnapshotCaptureConfig } from './snapshot/capture';
 export type { ScreenshotResult } from './snapshot/captureScreenshot';
 export { RepliqoScrollView } from './components/RepliqoScrollView';
+export { RepliqoFlatList } from './components/RepliqoFlatList';
+export type { PersistentStorage } from './core/storage';
 export { DEFAULT_CONFIG } from './core/config';
 export type { ResolvedConfig } from './core/config';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CONFIG = exports.RepliqoScrollView = exports.captureNativeFrame = exports.isNativeScreenCaptureAvailable = exports.captureScreenshot = exports.SnapshotCapture = exports.ErrorTracker = exports.trackScreenExit = exports.trackScreenEnter = exports.trackScreenChange = exports.useNavigationTracker = exports.TouchTracker = exports.AppAnalytics = void 0;
+exports.DEFAULT_CONFIG = exports.RepliqoFlatList = exports.RepliqoScrollView = exports.captureNativeFrame = exports.isNativeScreenCaptureAvailable = exports.captureScreenshot = exports.SnapshotCapture = exports.ErrorTracker = exports.trackScreenExit = exports.trackScreenEnter = exports.trackScreenChange = exports.useNavigationTracker = exports.TouchTracker = exports.AppAnalytics = void 0;
 // Main class
 var client_1 = require("./core/client");
 Object.defineProperty(exports, "AppAnalytics", { enumerable: true, get: function () { return client_1.AppAnalytics; } });
@@ -26,6 +26,8 @@ Object.defineProperty(exports, "captureNativeFrame", { enumerable: true, get: fu
 // Components
 var RepliqoScrollView_1 = require("./components/RepliqoScrollView");
 Object.defineProperty(exports, "RepliqoScrollView", { enumerable: true, get: function () { return RepliqoScrollView_1.RepliqoScrollView; } });
+var RepliqoFlatList_1 = require("./components/RepliqoFlatList");
+Object.defineProperty(exports, "RepliqoFlatList", { enumerable: true, get: function () { return RepliqoFlatList_1.RepliqoFlatList; } });
 // Config
 var config_1 = require("./core/config");
 Object.defineProperty(exports, "DEFAULT_CONFIG", { enumerable: true, get: function () { return config_1.DEFAULT_CONFIG; } });

package/dist/snapshot/capture.d.ts

@@ -22,6 +22,13 @@ export declare class SnapshotCapture {
     private log;
     private warn;
     constructor(config: SnapshotCaptureConfig, onSnapshot: (snapshot: SnapshotPayload) => void, provider?: ScreenshotProvider, log?: LogFn, warn?: LogFn);
+    /**
+     * Generation counter. Incremented on every start()/stop() so that timer
+     * chains from a PREVIOUS generation cannot reschedule themselves. Without
+     * it, a fast stop()→start() while a tick's capture is still in flight
+     * leaves two parallel timer chains alive (double capture rate).
+     */
+    private epoch;
     start(): void;
     stop(): void;
     captureNow(): Promise<void>;

package/dist/snapshot/capture.js

@@ -14,6 +14,13 @@ class SnapshotCapture {
         this.currentScreen = 'unknown';
         this.capturing = false;
         this.running = false;
+        /**
+         * Generation counter. Incremented on every start()/stop() so that timer
+         * chains from a PREVIOUS generation cannot reschedule themselves. Without
+         * it, a fast stop()→start() while a tick's capture is still in flight
+         * leaves two parallel timer chains alive (double capture rate).
+         */
+        this.epoch = 0;
         this.config = config;
         this.onSnapshot = onSnapshot;
         this.provider = provider;
@@ -24,11 +31,13 @@ class SnapshotCapture {
         if (this.running)
             return;
         this.running = true;
+        this.epoch++;
         this.log('Snapshot capture started (interval:', this.config.captureInterval, 'ms)');
-        this.scheduleNext();
+        this.scheduleNext(this.epoch);
     }
     stop() {
         this.running = false;
+        this.epoch++;
         if (this.timeoutId !== null) {
             clearTimeout(this.timeoutId);
             this.timeoutId = null;
@@ -38,13 +47,16 @@ class SnapshotCapture {
     async captureNow() {
         await this.tick();
     }
-    scheduleNext() {
-        if (!this.running)
+    scheduleNext(epoch) {
+        if (!this.running || epoch !== this.epoch)
             return;
         this.timeoutId = setTimeout(() => {
+            // Orphan timer from a previous generation — do nothing.
+            if (epoch !== this.epoch)
+                return;
             Promise.resolve(this.tick()).finally(() => {
-                if (this.running) {
-                    this.scheduleNext();
+                if (this.running && epoch === this.epoch) {
+                    this.scheduleNext(epoch);
                 }
             });
         }, this.config.captureInterval);

package/dist/trackers/error.tracker.d.ts

@@ -5,6 +5,7 @@ export declare class ErrorTracker {
     private sessionId;
     private currentScreen;
     private originalHandler;
+    private wrapperHandler;
     private isActive;
     constructor(onCrash: CrashCallback);
     setSessionId(id: string | null): void;
@@ -16,7 +17,31 @@ export declare class ErrorTracker {
      */
     reportError(error: Error, metadata?: Record<string, any>): void;
     private setupGlobalErrorHandler;
+    /**
+     * Handle an unhandled promise rejection. Guarded on isActive because the
+     * underlying trackers can't always be unregistered.
+     */
+    private handleUnhandledRejection;
+    /**
+     * Register with the mechanisms React Native ACTUALLY uses to surface
+     * unhandled promise rejections:
+     *
+     *  1. Hermes' native promise rejection tracker (Hermes engine).
+     *  2. The `promise` polyfill's rejection-tracking module (JSC and older
+     *     RN versions).
+     *
+     * A bare global callback (the old approach) is never invoked by RN — it
+     * silently captured nothing.
+     *
+     * KNOWN LIMITATION: these trackers hold a single handler — registering
+     * REPLACES whatever was installed before (RN's dev LogBox warning, or
+     * another SDK like Sentry if it initialized first), and there is no
+     * unregister API, so after stop() an inert handler remains installed.
+     * If you run multiple error-tracking SDKs, initialize Repliqo FIRST so
+     * the other SDK's handler wins, or disable enableCrashTracking.
+     */
     private setupUnhandledRejectionHandler;
+    private teardownUnhandledRejectionHandler;
     private restoreGlobalErrorHandler;
 }
 export {};