@repliqo/sdk-react-native 0.3.7 → 0.4.0

package/src/core/client.ts

@@ -1,672 +1,953 @@
-import { AppState, AppStateStatus } from 'react-native';
-import {
-  AnalyticsEvent,
-  DeviceInfo,
-  ScreenVisit,
-  SDKConfig,
-} from '../types/events';
-import { SnapshotPayload } from '../types/snapshot';
-import { SnapshotCapture } from '../snapshot/capture';
-import { ResolvedConfig, resolveConfig, REPLIQO_API_URL } from './config';
-import { Logger } from './logger';
-import { ApiClient } from '../transport/api.client';
-import { BatchQueue } from '../transport/batch-queue';
-import { ErrorTracker } from '../trackers/error.tracker';
-import { captureNativeFrame, scanFullContent } from '../snapshot/NativeScreenCapture';
-
-export class AppAnalytics {
-  private static instance: AppAnalytics | null = null;
-
-  private config: ResolvedConfig;
-  private apiClient: ApiClient;
-  private eventQueue: BatchQueue<AnalyticsEvent>;
-  private screenVisitQueue: BatchQueue<ScreenVisit>;
-  private snapshotQueue: BatchQueue<SnapshotPayload>;
-  private snapshotCapture: SnapshotCapture | null = null;
-  private errorTracker: ErrorTracker | null = null;
-  private sessionId: string | null = null;
-  private currentScreen: string | null = null;
-  private currentScreenEnteredAt: string | null = null;
-  private scrollOffsetY: number = 0;
-  private logger: Logger;
-  private appStateSubscription: { remove: () => void } | null = null;
-
-  /**
-   * Registry of active ScrollViews on the current screen.
-   * Each RepliqoScrollView registers its window-relative bounds and current
-   * scroll state. Used by trackTouch to auto-detect:
-   *   - If touch is INSIDE a ScrollView → adjust Y by that ScrollView's
-   *     scrollOffset, mark as content touch
-   *   - If touch is OUTSIDE all ScrollViews → mark as fixed UI (no adjust)
-   *
-   * This makes heatmaps render fixed elements (nav bars, headers) at their
-   * viewport position, while still mapping scrollable content correctly.
-   */
-  private scrollViewRegistry = new Map<
-    string,
-    {
-      bounds: { x: number; y: number; width: number; height: number };
-      scrollOffsetY: number;
-    }
-  >();
-
-  private constructor(config: SDKConfig) {
-    this.config = resolveConfig(config);
-    this.logger = new Logger(this.config.debug);
-    this.apiClient = new ApiClient(
-      REPLIQO_API_URL,
-      this.config.apiKey,
-      this.logger,
-    );
-
-    this.eventQueue = new BatchQueue<AnalyticsEvent>(
-      this.config.batchSize,
-      this.config.flushInterval,
-      async (events: AnalyticsEvent[]) => {
-        if (!this.sessionId) {
-          this.logger.warn(
-            'Cannot flush events: no active session',
-          );
-          throw new Error('No active session');
-        }
-        await this.apiClient.sendEventsBatch(this.sessionId, events);
-      },
-    );
-
-    this.screenVisitQueue = new BatchQueue<ScreenVisit>(
-      this.config.batchSize,
-      this.config.flushInterval,
-      async (visits: ScreenVisit[]) => {
-        await this.apiClient.sendScreenVisitsBatch(visits);
-      },
-    );
-
-    // Snapshots are heavier (~15-30 KB JPEG each) so they use a smaller
-    // batch size, shorter flush interval, and a tighter memory cap than
-    // the event queue. All configurable via SDKConfig.
-    this.snapshotQueue = new BatchQueue<SnapshotPayload>(
-      this.config.snapshotBatchSize,
-      this.config.snapshotFlushInterval,
-      async (snapshots: SnapshotPayload[]) => {
-        await this.apiClient.sendSnapshotsBatch(snapshots);
-      },
-      this.config.snapshotMaxBufferSize,
-    );
-
-    this.eventQueue.startAutoFlush();
-    this.screenVisitQueue.startAutoFlush();
-    this.snapshotQueue.startAutoFlush();
-
-    if (this.config.enableSnapshots) {
-      this.snapshotCapture = new SnapshotCapture(
-        {
-          captureInterval: this.config.snapshotInterval,
-          maxSnapshotsPerSession: this.config.maxSnapshotsPerSession,
-        },
-        (snapshot: SnapshotPayload) => {
-          this.snapshotQueue.add(snapshot);
-        },
-        undefined, // default captureScreenshot provider
-        (...args: any[]) => this.logger.log(...args),
-        (...args: any[]) => this.logger.warn(...args),
-      );
-    }
-
-    if (this.config.enableCrashTracking) {
-      this.errorTracker = new ErrorTracker((crash) => {
-        // Crash reports are sent immediately (fire-and-forget), not batched
-        this.apiClient.sendCrashReport(crash).catch(() => {});
-      });
-      this.errorTracker.start();
-    }
-
-    this.setupAppStateListener();
-
-    this.logger.log('SDK initialized with config:', {
-      apiUrl: REPLIQO_API_URL,
-      appId: this.config.appId,
-      batchSize: this.config.batchSize,
-      flushInterval: this.config.flushInterval,
-      enableSnapshots: this.config.enableSnapshots,
-      snapshotInterval: this.config.snapshotInterval,
-      enableCrashTracking: this.config.enableCrashTracking,
-    });
-  }
-
-  static init(config: SDKConfig): AppAnalytics {
-    if (AppAnalytics.instance) {
-      AppAnalytics.instance.logger.warn(
-        'AppAnalytics already initialized. Returning existing instance.',
-      );
-      return AppAnalytics.instance;
-    }
-
-    AppAnalytics.instance = new AppAnalytics(config);
-    return AppAnalytics.instance;
-  }
-
-  static getInstance(): AppAnalytics {
-    if (!AppAnalytics.instance) {
-      throw new Error(
-        'AppAnalytics not initialized. Call AppAnalytics.init(config) first.',
-      );
-    }
-    return AppAnalytics.instance;
-  }
-
-  static destroy(): void {
-    if (AppAnalytics.instance) {
-      const instance = AppAnalytics.instance;
-      instance.logger.log('Destroying AppAnalytics instance');
-
-      if (instance.errorTracker) {
-        instance.errorTracker.stop();
-        instance.errorTracker = null;
-      }
-
-      if (instance.snapshotCapture) {
-        instance.snapshotCapture.stop();
-        instance.snapshotCapture = null;
-      }
-
-
-      instance.eventQueue.stopAutoFlush();
-      instance.screenVisitQueue.stopAutoFlush();
-      instance.snapshotQueue.stopAutoFlush();
-
-      if (instance.appStateSubscription) {
-        instance.appStateSubscription.remove();
-        instance.appStateSubscription = null;
-      }
-
-      // Attempt a final flush (fire-and-forget)
-      instance.flush().catch(() => {});
-
-      AppAnalytics.instance = null;
-    }
-  }
-
-  async startSession(
-    deviceId: string,
-    deviceInfo?: DeviceInfo,
-  ): Promise<string> {
-    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);
-
-      if (this.snapshotCapture) {
-        this.snapshotCapture.setSessionId(this.sessionId);
-        this.snapshotCapture.reset();
-
-        // Native capture (MediaProjection) is NOT started automatically.
-        // It requires a system dialog that is confusing if shown on every
-        // launch. The host app can call enableNativeCapture() explicitly
-        // when the user opts in. Until then, view-shot is used.
-        this.startSnapshotCapture();
-      }
-
-      return this.sessionId;
-    } catch (error) {
-      this.logger.error('Failed to start session:', error);
-      throw error;
-    }
-  }
-
-  async endSession(): Promise<void> {
-    if (!this.sessionId) {
-      this.logger.warn('No active session to end');
-      return;
-    }
-
-    // Stop snapshot capture
-    this.stopSnapshotCapture();
-
-    // Flush any pending screen exit
-    if (this.currentScreen && this.currentScreenEnteredAt) {
-      this.onScreenExit(this.currentScreen);
-    }
-
-    // Flush remaining data
-    await this.flush();
-
-    try {
-      await this.apiClient.endSession(this.sessionId);
-      this.logger.log('Session ended:', this.sessionId);
-    } catch (error) {
-      this.logger.error('Failed to end session:', error);
-    }
-
-    this.sessionId = null;
-    this.currentScreen = null;
-    this.currentScreenEnteredAt = null;
-
-    this.errorTracker?.setSessionId(null);
-
-    if (this.snapshotCapture) {
-      this.snapshotCapture.setSessionId(null);
-    }
-  }
-
-  /**
-   * Track a touch event for heatmap analysis.
-   *
-   * @param x Touch X coordinate, in WINDOW coordinates (must match the
-   *          coordinate system of `measureInWindow` — typically `pageX`
-   *          from a React Native gesture event).
-   * @param y Touch Y coordinate, in WINDOW coordinates (must match the
-   *          coordinate system of `measureInWindow` — typically `pageY`
-   *          from a React Native gesture event). On Android with edge-to-edge
-   *          enabled, ensure `pageY` excludes the status bar to stay
-   *          consistent with `measureInWindow`.
-   * @param screenName Optional screen name (defaults to current screen).
-   * @param extra Optional extra data to attach to the event.
-   */
-  trackTouch(
-    x: number,
-    y: number,
-    screenName?: string,
-    extra?: Record<string, any>,
-  ): void {
-    if (!this.sessionId) {
-      this.logger.warn('Cannot track touch: no active session');
-      return;
-    }
-
-    if (!this.config.enableTouchTracking) {
-      return;
-    }
-
-    // Auto-detect: find which (if any) registered ScrollView contains
-    // this touch. If multiple match (nested ScrollViews, e.g. FlatList
-    // inside ScrollView), pick the SMALLEST by area — the most-nested
-    // one is the actual scroll context for that touch.
-    let bestMatchOffset = 0;
-    let bestMatchArea = Infinity;
-    let foundMatch = false;
-
-    for (const info of this.scrollViewRegistry.values()) {
-      const { bounds } = info;
-      if (
-        x >= bounds.x &&
-        x <= bounds.x + bounds.width &&
-        y >= bounds.y &&
-        y <= bounds.y + bounds.height
-      ) {
-        const area = bounds.width * bounds.height;
-        if (area < bestMatchArea) {
-          bestMatchArea = area;
-          bestMatchOffset = info.scrollOffsetY;
-          foundMatch = true;
-        }
-      }
-    }
-
-    let activeScrollOffset: number;
-    let isFixed: boolean;
-
-    if (foundMatch) {
-      // Touch is inside a registered ScrollView → content touch
-      activeScrollOffset = bestMatchOffset;
-      isFixed = false;
-    } else if (this.scrollViewRegistry.size > 0) {
-      // ScrollViews ARE registered, but this touch is outside all of them
-      // → it's on fixed UI (nav bar, header, etc.)
-      activeScrollOffset = 0;
-      isFixed = true;
-    } else {
-      // No ScrollViews registered at all. Two possible 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.
-      activeScrollOffset = 0;
-      isFixed = true;
-    }
-
-    const adjustedY = y + activeScrollOffset;
-
-    const event: AnalyticsEvent = {
-      type: 'touch',
-      screenName: screenName || this.currentScreen || undefined,
-      data: {
-        x,
-        y: adjustedY,
-        scrollOffsetY: activeScrollOffset,
-        isFixed,
-        ...extra,
-      },
-      timestamp: new Date().toISOString(),
-    };
-
-    this.eventQueue.add(event);
-    this.logger.log('Touch tracked:', event);
-  }
-
-  trackNavigation(fromScreen: string, toScreen: string): void {
-    if (!this.sessionId) {
-      this.logger.warn('Cannot track navigation: no active session');
-      return;
-    }
-
-    if (!this.config.enableNavigationTracking) {
-      return;
-    }
-
-    const event: AnalyticsEvent = {
-      type: 'navigation',
-      screenName: toScreen,
-      data: { fromScreen, toScreen },
-      timestamp: new Date().toISOString(),
-    };
-
-    this.eventQueue.add(event);
-    this.logger.log('Navigation tracked:', fromScreen, '->', toScreen);
-  }
-
-  trackCustomEvent(eventName: string, data?: Record<string, any>): void {
-    if (!this.sessionId) {
-      this.logger.warn('Cannot track custom event: no active session');
-      return;
-    }
-
-    const event: AnalyticsEvent = {
-      type: 'custom',
-      screenName: this.currentScreen || undefined,
-      data: { eventName, ...data },
-      timestamp: new Date().toISOString(),
-    };
-
-    this.eventQueue.add(event);
-    this.logger.log('Custom event tracked:', eventName);
-  }
-
-  reportError(error: Error, metadata?: Record<string, any>): void {
-    if (!this.errorTracker) {
-      this.logger.warn(
-        'Cannot report error: crash tracking is not enabled',
-      );
-      return;
-    }
-
-    this.errorTracker.reportError(error, metadata);
-  }
-
-  /**
-   * Update the current scroll offset. Called by RepliqoScrollView
-   * or manually from the host app's ScrollView onScroll handler.
-   * The offset is added to touch Y coordinates for accurate heatmaps
-   * on scrollable screens.
-   *
-   * @deprecated Prefer registerScrollView + updateScrollViewOffset for
-   * auto-detection of fixed vs scrollable touches. Kept for backward compat.
-   */
-  setScrollOffset(y: number): void {
-    this.scrollOffsetY = y;
-  }
-
-  /**
-   * Register a ScrollView's window-relative bounds with the SDK.
-   * Called by RepliqoScrollView on layout. Used to auto-detect whether
-   * a touch is on scrollable content or on fixed UI (nav bars, headers).
-   */
-  registerScrollView(
-    id: string,
-    bounds: { x: number; y: number; width: number; height: number },
-  ): void {
-    const existing = this.scrollViewRegistry.get(id);
-    this.scrollViewRegistry.set(id, {
-      bounds,
-      scrollOffsetY: existing?.scrollOffsetY ?? 0,
-    });
-  }
-
-  /**
-   * Update the scroll offset for a previously-registered ScrollView.
-   * Called by RepliqoScrollView on every scroll event.
-   */
-  updateScrollViewOffset(id: string, scrollOffsetY: number): void {
-    const existing = this.scrollViewRegistry.get(id);
-    if (existing) {
-      existing.scrollOffsetY = scrollOffsetY;
-    }
-  }
-
-  /**
-   * Remove a ScrollView from the registry. Called by RepliqoScrollView
-   * on unmount.
-   */
-  unregisterScrollView(id: string): void {
-    this.scrollViewRegistry.delete(id);
-  }
-
-  /**
-   * Capture the current viewport as a tile for collaborative screen
-   * building. Called by RepliqoScrollView on scroll stops.
-   *
-   * The tile includes:
-   *  - `scrollOffsetY`: where in the full content this viewport belongs
-   *  - `viewportTop`: Y position (window logical px) of the ScrollView's
-   *    top edge. Used by the backend to crop each tile to just the
-   *    scrollable area, removing fixed headers/footers that would
-   *    otherwise duplicate in the composite.
-   *  - `windowHeight`: window height in logical px, for image-to-logical
-   *    scale computation during backend cropping.
-   */
-  captureScrollTile(
-    scrollOffsetY: number,
-    viewportHeight: number,
-    contentHeight: number,
-    viewportTop?: number,
-    windowHeight?: number,
-  ): void {
-    if (!this.sessionId || !this.currentScreen) return;
-    if (viewportHeight <= 0) return; // No real dimensions yet
-
-    const screenName = this.currentScreen;
-    const sessionId = this.sessionId;
-
-    // Fire-and-forget: capture + upload in background
-    (async () => {
-      try {
-        const frame = await captureNativeFrame();
-        if (!frame) return;
-
-        this.logger.log(
-          `Scroll tile: "${screenName}" Y=${Math.round(scrollOffsetY)} ` +
-            `vp=${Math.round(viewportHeight)} content=${Math.round(contentHeight)} ` +
-            `top=${viewportTop !== undefined ? Math.round(viewportTop) : '?'} ` +
-            `${Math.round(frame.image.length / 1024)}KB`,
-        );
-
-        await this.apiClient.uploadScreenTile(
-          sessionId,
-          screenName,
-          frame.image,
-          frame.width,
-          frame.height,
-          scrollOffsetY,
-          viewportHeight,
-          contentHeight,
-          viewportTop,
-          windowHeight,
-        );
-      } catch (err) {
-        this.logger.warn('Scroll tile failed:', err);
-      }
-    })();
-  }
-
-  /**
-   * Programmatically scroll-scan the current ScrollView and upload all
-   * tiles to the backend. Invisible to the user (~300-500ms).
-   */
-  private autoScanScreen(screenName: string): void {
-    (async () => {
-      try {
-        const tiles = await scanFullContent();
-        if (!tiles || tiles.length === 0) {
-          this.logger.log(`Auto-scan: no ScrollView found for "${screenName}"`);
-          return;
-        }
-
-        this.logger.log(
-          `Auto-scan: "${screenName}" captured ${tiles.length} tiles ` +
-            `(content=${tiles[0].contentHeight}px)`,
-        );
-
-        // Upload all tiles in parallel
-        const sessionId = this.sessionId!;
-        await Promise.all(
-          tiles.map((tile) =>
-            this.apiClient.uploadScreenTile(
-              sessionId,
-              screenName,
-              tile.image,
-              tile.width,
-              tile.height,
-              tile.scrollOffsetY,
-              tile.viewportHeight,
-              tile.contentHeight,
-            ).catch(() => {}),
-          ),
-        );
-
-        this.logger.log(`Auto-scan: "${screenName}" tiles uploaded`);
-      } catch (err) {
-        this.logger.warn('Auto-scan failed:', err);
-      }
-    })();
-  }
-
-  onScreenEnter(screenName: string): void {
-    this.currentScreen = screenName;
-    this.currentScreenEnteredAt = new Date().toISOString();
-    this.scrollOffsetY = 0;
-    // Clear the ScrollView registry — old screen's scrollviews are gone
-    this.scrollViewRegistry.clear();
-    this.errorTracker?.setCurrentScreen(screenName);
-    this.snapshotCapture?.setCurrentScreen(screenName);
-    // NOTE: autoScanScreen (PixelCopy / programmatic scroll) is DISABLED.
-    // React Native does NOT render off-screen content to the GPU or view
-    // tree, so programmatic scroll + View.draw()/PixelCopy produces blank
-    // tiles. Worse, those blank tiles poison the dedup cache and block
-    // real tiles captured during natural user scroll.
-    //
-    // Full-content capture relies entirely on RepliqoScrollView capturing
-    // viewport tiles as the user naturally scrolls through the content.
-
-    this.logger.log('Screen entered:', screenName);
-  }
-
-  onScreenExit(screenName: string): void {
-    if (
-      this.sessionId &&
-      this.currentScreen === screenName &&
-      this.currentScreenEnteredAt
-    ) {
-      const enteredAt = this.currentScreenEnteredAt;
-      const exitedAt = new Date().toISOString();
-      const duration =
-        new Date(exitedAt).getTime() - new Date(enteredAt).getTime();
-
-      const visit: ScreenVisit = {
-        sessionId: this.sessionId,
-        screenName,
-        enteredAt,
-        exitedAt,
-        duration,
-      };
-
-      this.screenVisitQueue.add(visit);
-      this.logger.log('Screen exited:', screenName, 'duration:', duration);
-    }
-
-    if (this.currentScreen === screenName) {
-      this.currentScreen = null;
-      this.currentScreenEnteredAt = null;
-      this.errorTracker?.setCurrentScreen(null);
-    }
-  }
-
-  async flush(): Promise<void> {
-    this.logger.log('Flushing queues...');
-    await Promise.all([
-      this.eventQueue.flush(),
-      this.screenVisitQueue.flush(),
-      this.snapshotQueue.flush(),
-    ]);
-    this.logger.log('Flush complete');
-  }
-
-  getSessionId(): string | null {
-    return this.sessionId;
-  }
-
-  getCurrentScreen(): string | null {
-    return this.currentScreen;
-  }
-
-  /**
-   * Force an immediate screenshot capture, outside the periodic schedule.
-   * Useful for capturing specific moments (e.g. right after a critical
-   * user action). Respects the in-flight lock and session cap.
-   */
-  async captureSnapshot(screenName?: string): Promise<void> {
-    if (!this.sessionId || !this.snapshotCapture) {
-      return;
-    }
-    if (screenName) {
-      this.snapshotCapture.setCurrentScreen(screenName);
-    }
-    await this.snapshotCapture.captureNow();
-  }
-
-  startSnapshotCapture(): void {
-    if (this.snapshotCapture) {
-      this.snapshotCapture.start();
-      this.logger.log('Snapshot capture started');
-    }
-  }
-
-  stopSnapshotCapture(): void {
-    if (this.snapshotCapture) {
-      this.snapshotCapture.stop();
-      this.logger.log('Snapshot capture stopped');
-    }
-  }
-
-  isInitialized(): boolean {
-    return true;
-  }
-
-  private setupAppStateListener(): void {
-    let wasInBackground = false;
-
-    this.appStateSubscription = AppState.addEventListener(
-      'change',
-      (nextAppState: AppStateStatus) => {
-        if (nextAppState === 'background' || nextAppState === 'inactive') {
-          this.logger.log(
-            'App going to background, pausing snapshots + flushing',
-          );
-          this.stopSnapshotCapture();
-          wasInBackground = true;
-
-          this.flush().catch((error) => {
-            this.logger.error('Error flushing on app state change:', error);
-          });
-        } else if (nextAppState === 'active' && wasInBackground) {
-          wasInBackground = false;
-          this.logger.log('App returned to foreground, resuming snapshots');
-
-          if (this.snapshotCapture && this.sessionId) {
-            this.startSnapshotCapture();
-          }
-        }
-      },
-    );
-  }
-}
+import { AppState, AppStateStatus } from 'react-native';
+import {
+  AnalyticsEvent,
+  DeviceInfo,
+  ScreenVisit,
+  SDKConfig,
+} from '../types/events';
+import { SnapshotPayload } from '../types/snapshot';
+import { CrashReport } from '../types/crash';
+import { SnapshotCapture } from '../snapshot/capture';
+import { ResolvedConfig, resolveConfig, REPLIQO_API_URL } from './config';
+import {
+  PersistentStorage,
+  tryLoadAsyncStorage,
+  STORAGE_KEYS,
+  MAX_PERSISTED_EVENTS,
+  MAX_PERSISTED_CRASHES,
+} from './storage';
+import { Logger } from './logger';
+import { ApiClient } from '../transport/api.client';
+import {
+  BatchQueue,
+  NonRetryableFlushError,
+  PartialFlushError,
+} from '../transport/batch-queue';
+import { ErrorTracker } from '../trackers/error.tracker';
+import { captureNativeFrame } from '../snapshot/NativeScreenCapture';
+
+/**
+ * An analytics event stamped with the session that was active when it was
+ * enqueued. Grouped per session at flush time so buffered events are never
+ * attributed to a newer session (cross-session contamination).
+ */
+type QueuedEvent = AnalyticsEvent & { __sessionId: string };
+
+export class AppAnalytics {
+  private static instance: AppAnalytics | null = null;
+
+  private config: ResolvedConfig;
+  private apiClient: ApiClient;
+  private eventQueue: BatchQueue<QueuedEvent>;
+  private screenVisitQueue: BatchQueue<ScreenVisit>;
+  private snapshotQueue: BatchQueue<SnapshotPayload>;
+  private snapshotCapture: SnapshotCapture | null = null;
+  private errorTracker: ErrorTracker | null = null;
+  private sessionId: string | null = null;
+  private currentScreen: string | null = null;
+  private currentScreenEnteredAt: string | null = null;
+  private scrollOffsetY: number = 0;
+  private logger: Logger;
+  private appStateSubscription: { remove: () => void } | null = 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).
+   */
+  private identity: {
+    userId: string;
+    traits?: Record<string, unknown>;
+  } | null = 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).
+   */
+  private storage: PersistentStorage | null = null;
+
+  /**
+   * Registry of active ScrollViews on the current screen.
+   * Each RepliqoScrollView registers its window-relative bounds and current
+   * scroll state. Used by trackTouch to auto-detect:
+   *   - If touch is INSIDE a ScrollView → adjust Y by that ScrollView's
+   *     scrollOffset, mark as content touch
+   *   - If touch is OUTSIDE all ScrollViews → mark as fixed UI (no adjust)
+   *
+   * This makes heatmaps render fixed elements (nav bars, headers) at their
+   * viewport position, while still mapping scrollable content correctly.
+   */
+  private scrollViewRegistry = new Map<
+    string,
+    {
+      bounds: { x: number; y: number; width: number; height: number };
+      scrollOffsetY: number;
+    }
+  >();
+
+  private constructor(config: SDKConfig) {
+    this.config = resolveConfig(config);
+    this.logger = new Logger(this.config.debug);
+    this.apiClient = new ApiClient(
+      REPLIQO_API_URL,
+      this.config.apiKey,
+      this.logger,
+    );
+
+    // 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 BatchQueue<QueuedEvent>(
+      this.config.batchSize,
+      this.config.flushInterval,
+      async (queued: QueuedEvent[]) => {
+        // Split into contiguous same-session runs, preserving order.
+        const runs: Array<{ sessionId: string; events: AnalyticsEvent[] }> = [];
+        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 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 PartialFlushError(consumed, true);
+            }
+            throw err;
+          }
+        }
+      },
+    );
+
+    this.screenVisitQueue = new BatchQueue<ScreenVisit>(
+      this.config.batchSize,
+      this.config.flushInterval,
+      async (visits: ScreenVisit[]) => {
+        await this.apiClient.sendScreenVisitsBatch(visits);
+      },
+    );
+
+    // Snapshots are heavier (~15-30 KB JPEG each) so they use a smaller
+    // batch size, shorter flush interval, and a tighter memory cap than
+    // the event queue. All configurable via SDKConfig.
+    this.snapshotQueue = new BatchQueue<SnapshotPayload>(
+      this.config.snapshotBatchSize,
+      this.config.snapshotFlushInterval,
+      async (snapshots: SnapshotPayload[]) => {
+        await this.apiClient.sendSnapshotsBatch(snapshots);
+      },
+      this.config.snapshotMaxBufferSize,
+    );
+
+    this.eventQueue.startAutoFlush();
+    this.screenVisitQueue.startAutoFlush();
+    this.snapshotQueue.startAutoFlush();
+
+    if (this.config.enableSnapshots) {
+      this.snapshotCapture = new SnapshotCapture(
+        {
+          captureInterval: this.config.snapshotInterval,
+          maxSnapshotsPerSession: this.config.maxSnapshotsPerSession,
+        },
+        (snapshot: SnapshotPayload) => {
+          this.snapshotQueue.add(snapshot);
+        },
+        undefined, // default captureScreenshot provider
+        (...args: any[]) => this.logger.log(...args),
+        (...args: any[]) => 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 ?? tryLoadAsyncStorage();
+
+    if (this.config.enableCrashTracking) {
+      this.errorTracker = new ErrorTracker((crash) => {
+        // 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: REPLIQO_API_URL,
+      appId: this.config.appId,
+      batchSize: this.config.batchSize,
+      flushInterval: this.config.flushInterval,
+      enableSnapshots: this.config.enableSnapshots,
+      snapshotInterval: this.config.snapshotInterval,
+      enableCrashTracking: this.config.enableCrashTracking,
+    });
+  }
+
+  static init(config: SDKConfig): AppAnalytics {
+    if (AppAnalytics.instance) {
+      AppAnalytics.instance.logger.warn(
+        'AppAnalytics already initialized. Returning existing instance.',
+      );
+      return AppAnalytics.instance;
+    }
+
+    AppAnalytics.instance = new AppAnalytics(config);
+    return AppAnalytics.instance;
+  }
+
+  static getInstance(): AppAnalytics {
+    if (!AppAnalytics.instance) {
+      throw new Error(
+        'AppAnalytics not initialized. Call AppAnalytics.init(config) first.',
+      );
+    }
+    return AppAnalytics.instance;
+  }
+
+  static destroy(): void {
+    if (AppAnalytics.instance) {
+      const instance = AppAnalytics.instance;
+      instance.logger.log('Destroying AppAnalytics instance');
+
+      if (instance.errorTracker) {
+        instance.errorTracker.stop();
+        instance.errorTracker = null;
+      }
+
+      if (instance.snapshotCapture) {
+        instance.snapshotCapture.stop();
+        instance.snapshotCapture = null;
+      }
+
+
+      instance.eventQueue.stopAutoFlush();
+      instance.screenVisitQueue.stopAutoFlush();
+      instance.snapshotQueue.stopAutoFlush();
+
+      if (instance.appStateSubscription) {
+        instance.appStateSubscription.remove();
+        instance.appStateSubscription = null;
+      }
+
+      // 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: string,
+    deviceInfo?: DeviceInfo,
+  ): Promise<string> {
+    // 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();
+
+        // Native capture (MediaProjection) is NOT started automatically.
+        // It requires a system dialog that is confusing if shown on every
+        // launch. The host app can call enableNativeCapture() explicitly
+        // when the user opts in. Until then, view-shot is used.
+        this.startSnapshotCapture();
+      }
+
+      return this.sessionId;
+    } catch (error) {
+      this.logger.error('Failed to start session:', error);
+      throw error;
+    }
+  }
+
+  async endSession(): Promise<void> {
+    if (!this.sessionId) {
+      this.logger.warn('No active session to end');
+      return;
+    }
+
+    // Stop snapshot capture
+    this.stopSnapshotCapture();
+
+    // Flush any pending screen exit
+    if (this.currentScreen && this.currentScreenEnteredAt) {
+      this.onScreenExit(this.currentScreen);
+    }
+
+    // Flush remaining data
+    await this.flush();
+
+    try {
+      await this.apiClient.endSession(this.sessionId);
+      this.logger.log('Session ended:', this.sessionId);
+    } catch (error) {
+      this.logger.error('Failed to end session:', error);
+    }
+
+    this.sessionId = null;
+    this.currentScreen = null;
+    this.currentScreenEnteredAt = null;
+
+    this.errorTracker?.setSessionId(null);
+
+    if (this.snapshotCapture) {
+      this.snapshotCapture.setSessionId(null);
+    }
+  }
+
+  /**
+   * Track a touch event for heatmap analysis.
+   *
+   * @param x Touch X coordinate, in WINDOW coordinates (must match the
+   *          coordinate system of `measureInWindow` — typically `pageX`
+   *          from a React Native gesture event).
+   * @param y Touch Y coordinate, in WINDOW coordinates (must match the
+   *          coordinate system of `measureInWindow` — typically `pageY`
+   *          from a React Native gesture event). On Android with edge-to-edge
+   *          enabled, ensure `pageY` excludes the status bar to stay
+   *          consistent with `measureInWindow`.
+   * @param screenName Optional screen name (defaults to current screen).
+   * @param extra Optional extra data to attach to the event.
+   */
+  trackTouch(
+    x: number,
+    y: number,
+    screenName?: string,
+    extra?: Record<string, any>,
+  ): void {
+    if (!this.sessionId) {
+      this.logger.warn('Cannot track touch: no active session');
+      return;
+    }
+
+    if (!this.config.enableTouchTracking) {
+      return;
+    }
+
+    // Auto-detect: find which (if any) registered ScrollView contains
+    // this touch. If multiple match (nested ScrollViews, e.g. FlatList
+    // inside ScrollView), pick the SMALLEST by area — the most-nested
+    // one is the actual scroll context for that touch.
+    let bestMatchOffset = 0;
+    let bestMatchArea = Infinity;
+    let foundMatch = false;
+
+    for (const info of this.scrollViewRegistry.values()) {
+      const { bounds } = info;
+      if (
+        x >= bounds.x &&
+        x <= bounds.x + bounds.width &&
+        y >= bounds.y &&
+        y <= bounds.y + bounds.height
+      ) {
+        const area = bounds.width * bounds.height;
+        if (area < bestMatchArea) {
+          bestMatchArea = area;
+          bestMatchOffset = info.scrollOffsetY;
+          foundMatch = true;
+        }
+      }
+    }
+
+    let activeScrollOffset: number;
+    let isFixed: boolean;
+
+    if (foundMatch) {
+      // Touch is inside a registered ScrollView → content touch
+      activeScrollOffset = bestMatchOffset;
+      isFixed = false;
+    } else if (this.scrollViewRegistry.size > 0) {
+      // ScrollViews ARE registered, but this touch is outside all of them
+      // → it's on fixed UI (nav bar, header, etc.)
+      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 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.
+      activeScrollOffset = 0;
+      isFixed = true;
+    }
+
+    const adjustedY = y + activeScrollOffset;
+
+    const event: AnalyticsEvent = {
+      type: 'touch',
+      screenName: screenName || this.currentScreen || undefined,
+      data: {
+        x,
+        y: adjustedY,
+        scrollOffsetY: activeScrollOffset,
+        isFixed,
+        ...extra,
+      },
+      timestamp: new Date().toISOString(),
+    };
+
+    // Stamp the ACTIVE session at enqueue time (see QueuedEvent).
+    this.eventQueue.add({ ...event, __sessionId: this.sessionId });
+    this.logger.log('Touch tracked:', event);
+  }
+
+  trackNavigation(fromScreen: string, toScreen: string): void {
+    if (!this.sessionId) {
+      this.logger.warn('Cannot track navigation: no active session');
+      return;
+    }
+
+    if (!this.config.enableNavigationTracking) {
+      return;
+    }
+
+    const event: AnalyticsEvent = {
+      type: 'navigation',
+      screenName: toScreen,
+      data: { fromScreen, toScreen },
+      timestamp: new Date().toISOString(),
+    };
+
+    // 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: string, data?: Record<string, any>): void {
+    if (!this.sessionId) {
+      this.logger.warn('Cannot track custom event: no active session');
+      return;
+    }
+
+    const event: AnalyticsEvent = {
+      type: 'custom',
+      screenName: this.currentScreen || undefined,
+      data: { eventName, ...data },
+      timestamp: new Date().toISOString(),
+    };
+
+    // 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: string, traits?: Record<string, unknown>): void {
+    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(): void {
+    this.identity = null;
+    this.logger.log('Identity cleared');
+  }
+
+  reportError(error: Error, metadata?: Record<string, any>): void {
+    if (!this.errorTracker) {
+      this.logger.warn(
+        'Cannot report error: crash tracking is not enabled',
+      );
+      return;
+    }
+
+    this.errorTracker.reportError(error, metadata);
+  }
+
+  /**
+   * Update the current scroll offset. Called by RepliqoScrollView
+   * or manually from the host app's ScrollView onScroll handler.
+   * The offset is added to touch Y coordinates for accurate heatmaps
+   * on scrollable screens.
+   *
+   * @deprecated Prefer registerScrollView + updateScrollViewOffset for
+   * auto-detection of fixed vs scrollable touches. Kept for backward compat.
+   */
+  setScrollOffset(y: number): void {
+    this.scrollOffsetY = y;
+  }
+
+  /**
+   * Register a ScrollView's window-relative bounds with the SDK.
+   * Called by RepliqoScrollView on layout. Used to auto-detect whether
+   * a touch is on scrollable content or on fixed UI (nav bars, headers).
+   */
+  registerScrollView(
+    id: string,
+    bounds: { x: number; y: number; width: number; height: number },
+  ): void {
+    const existing = this.scrollViewRegistry.get(id);
+    this.scrollViewRegistry.set(id, {
+      bounds,
+      scrollOffsetY: existing?.scrollOffsetY ?? 0,
+    });
+  }
+
+  /**
+   * Update the scroll offset for a previously-registered ScrollView.
+   * Called by RepliqoScrollView on every scroll event.
+   */
+  updateScrollViewOffset(id: string, scrollOffsetY: number): void {
+    const existing = this.scrollViewRegistry.get(id);
+    if (existing) {
+      existing.scrollOffsetY = scrollOffsetY;
+    }
+  }
+
+  /**
+   * Remove a ScrollView from the registry. Called by RepliqoScrollView
+   * on unmount.
+   */
+  unregisterScrollView(id: string): void {
+    this.scrollViewRegistry.delete(id);
+  }
+
+  /**
+   * Capture the current viewport as a tile for collaborative screen
+   * building. Called by RepliqoScrollView on scroll stops.
+   *
+   * The tile includes:
+   *  - `scrollOffsetY`: where in the full content this viewport belongs
+   *  - `viewportTop`: Y position (window logical px) of the ScrollView's
+   *    top edge. Used by the backend to crop each tile to just the
+   *    scrollable area, removing fixed headers/footers that would
+   *    otherwise duplicate in the composite.
+   *  - `windowHeight`: window height in logical px, for image-to-logical
+   *    scale computation during backend cropping.
+   */
+  captureScrollTile(
+    scrollOffsetY: number,
+    viewportHeight: number,
+    contentHeight: number,
+    viewportTop?: number,
+    windowHeight?: number,
+  ): void {
+    if (!this.sessionId || !this.currentScreen) return;
+    if (viewportHeight <= 0) return; // No real dimensions yet
+
+    const screenName = this.currentScreen;
+    const sessionId = this.sessionId;
+
+    // Fire-and-forget: capture + upload in background
+    (async () => {
+      try {
+        const frame = await captureNativeFrame();
+        if (!frame) return;
+
+        this.logger.log(
+          `Scroll tile: "${screenName}" Y=${Math.round(scrollOffsetY)} ` +
+            `vp=${Math.round(viewportHeight)} content=${Math.round(contentHeight)} ` +
+            `top=${viewportTop !== undefined ? Math.round(viewportTop) : '?'} ` +
+            `${Math.round(frame.image.length / 1024)}KB`,
+        );
+
+        await this.apiClient.uploadScreenTile(
+          sessionId,
+          screenName,
+          frame.image,
+          frame.width,
+          frame.height,
+          scrollOffsetY,
+          viewportHeight,
+          contentHeight,
+          viewportTop,
+          windowHeight,
+        );
+      } catch (err) {
+        this.logger.warn('Scroll tile failed:', err);
+      }
+    })();
+  }
+
+  onScreenEnter(screenName: string): void {
+    // 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;
+    // Clear the ScrollView registry — old screen's scrollviews are gone
+    this.scrollViewRegistry.clear();
+    this.errorTracker?.setCurrentScreen(screenName);
+    this.snapshotCapture?.setCurrentScreen(screenName);
+    // NOTE: full-content capture is NOT done via programmatic scroll +
+    // native capture. React Native does NOT render off-screen content to
+    // the GPU or view tree, so any programmatic-scroll approach produces
+    // blank tiles. Full-content heatmap backgrounds are built entirely
+    // from viewport tiles captured by RepliqoScrollView as the user
+    // naturally scrolls through the content.
+
+    this.logger.log('Screen entered:', screenName);
+  }
+
+  onScreenExit(screenName: string): void {
+    if (
+      this.sessionId &&
+      this.currentScreen === screenName &&
+      this.currentScreenEnteredAt
+    ) {
+      const enteredAt = this.currentScreenEnteredAt;
+      const exitedAt = new Date().toISOString();
+      const duration =
+        new Date(exitedAt).getTime() - new Date(enteredAt).getTime();
+
+      const visit: ScreenVisit = {
+        sessionId: this.sessionId,
+        screenName,
+        enteredAt,
+        exitedAt,
+        duration,
+      };
+
+      this.screenVisitQueue.add(visit);
+      this.logger.log('Screen exited:', screenName, 'duration:', duration);
+    }
+
+    if (this.currentScreen === screenName) {
+      this.currentScreen = null;
+      this.currentScreenEnteredAt = null;
+      this.errorTracker?.setCurrentScreen(null);
+    }
+  }
+
+  async flush(): Promise<void> {
+    this.logger.log('Flushing queues...');
+    await Promise.all([
+      this.eventQueue.flush(),
+      this.screenVisitQueue.flush(),
+      this.snapshotQueue.flush(),
+    ]);
+    this.logger.log('Flush complete');
+  }
+
+  getSessionId(): string | null {
+    return this.sessionId;
+  }
+
+  getCurrentScreen(): string | null {
+    return this.currentScreen;
+  }
+
+  /**
+   * Force an immediate screenshot capture, outside the periodic schedule.
+   * Useful for capturing specific moments (e.g. right after a critical
+   * user action). Respects the in-flight lock and session cap.
+   */
+  async captureSnapshot(screenName?: string): Promise<void> {
+    if (!this.sessionId || !this.snapshotCapture) {
+      return;
+    }
+    if (screenName) {
+      this.snapshotCapture.setCurrentScreen(screenName);
+    }
+    await this.snapshotCapture.captureNow();
+  }
+
+  startSnapshotCapture(): void {
+    if (this.snapshotCapture) {
+      this.snapshotCapture.start();
+      this.logger.log('Snapshot capture started');
+    }
+  }
+
+  stopSnapshotCapture(): void {
+    if (this.snapshotCapture) {
+      this.snapshotCapture.stop();
+      this.logger.log('Snapshot capture stopped');
+    }
+  }
+
+  isInitialized(): boolean {
+    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.
+   */
+  private async persistPendingEvents(): Promise<void> {
+    if (!this.storage) return;
+    try {
+      const pending = this.eventQueue.peekAll().slice(-MAX_PERSISTED_EVENTS);
+      if (pending.length === 0) {
+        await this.storage.removeItem(STORAGE_KEYS.pendingEvents);
+        return;
+      }
+      await this.storage.setItem(
+        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);
+    }
+  }
+
+  /**
+   * 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.
+   */
+  private crashStoreLock: Promise<unknown> = Promise.resolve();
+
+  private withCrashStoreLock<T>(op: () => Promise<T>): Promise<T> {
+    const run = this.crashStoreLock.then(op, op);
+    // Keep the chain alive regardless of op outcome.
+    this.crashStoreLock = run.catch(() => {});
+    return run;
+  }
+
+  /** Monotonic suffix so identical crashes get distinct keys. */
+  private crashSeq = 0;
+
+  /** Append a crash to the persisted pending list; returns its key. */
+  private async persistCrash(crash: CrashReport): Promise<string | null> {
+    if (!this.storage) return null;
+    const storage = this.storage;
+    try {
+      return await this.withCrashStoreLock(async () => {
+        const raw = await storage.getItem(STORAGE_KEYS.pendingCrashes);
+        const list: Array<{ key: string; crash: CrashReport }> = 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_KEYS.pendingCrashes,
+          JSON.stringify(list.slice(-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). */
+  private async removePendingCrash(key: string): Promise<void> {
+    if (!this.storage) return;
+    const storage = this.storage;
+    try {
+      await this.withCrashStoreLock(async () => {
+        const raw = await storage.getItem(STORAGE_KEYS.pendingCrashes);
+        if (!raw) return;
+        const list: Array<{ key: string; crash: CrashReport }> = JSON.parse(raw);
+        const remaining = list.filter((entry) => entry.key !== key);
+        if (remaining.length === 0) {
+          await storage.removeItem(STORAGE_KEYS.pendingCrashes);
+        } else {
+          await storage.setItem(
+            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.
+   */
+  private async restorePersistedData(): Promise<void> {
+    if (!this.storage) return;
+
+    // Events: re-enqueue and clear. They flush with the normal cycle.
+    try {
+      const raw = await this.storage.getItem(STORAGE_KEYS.pendingEvents);
+      if (raw) {
+        await this.storage.removeItem(STORAGE_KEYS.pendingEvents);
+        const events: QueuedEvent[] = 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_KEYS.pendingCrashes);
+      if (raw) {
+        const list: Array<{ key: string; crash: CrashReport }> = JSON.parse(raw);
+        if (Array.isArray(list) && list.length > 0) {
+          await this.apiClient.sendCrashesBatch(list.map((e) => e.crash));
+          await this.storage.removeItem(STORAGE_KEYS.pendingCrashes);
+          this.logger.log('Re-sent', list.length, 'persisted crash reports');
+        } else {
+          await this.storage.removeItem(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);
+    }
+  }
+
+  private setupAppStateListener(): void {
+    let wasInBackground = false;
+
+    this.appStateSubscription = AppState.addEventListener(
+      'change',
+      (nextAppState: AppStateStatus) => {
+        if (nextAppState === 'background' || nextAppState === 'inactive') {
+          this.logger.log(
+            'App going to background, pausing snapshots + flushing',
+          );
+          this.stopSnapshotCapture();
+          wasInBackground = true;
+
+          // 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_KEYS.pendingEvents).catch(() => {});
+          }
+
+          if (this.snapshotCapture && this.sessionId) {
+            this.startSnapshotCapture();
+          }
+        }
+      },
+    );
+  }
+}