@tsachit/react-native-geo-service 1.0.2 → 1.0.4

package/README.md

@@ -6,7 +6,7 @@ Battery-efficient background geolocation for React Native — a lightweight, fre
 - Keeps tracking when the app is backgrounded or killed (headless mode)
 - Uses `FusedLocationProviderClient` on Android and `CLLocationManager` on iOS
 - **Adaptive accuracy** — GPS turns off automatically when the device is idle and wakes the moment movement is detected
-- **Debug panel** — draggable floating overlay that mounts automatically when `debug: true`, showing live metrics, GPS activity, and battery saving suggestions with no component needed in the app tree
+- **Debug panel** — draggable floating overlay showing live metrics, GPS activity, and battery saving suggestions; add `<GeoDebugOverlay />` once and it self-manages based on `debug: true` and tracking state
 - Fully configurable from JavaScript — no API keys, no license required
 
 ---
@@ -83,13 +83,17 @@ In your app's **`index.js`** (top level, outside any component):
 
 ```js
 import { AppRegistry } from 'react-native';
+import RNGSAppRegistry from '@tsachit/react-native-geo-service';
 import App from './App';
 
 AppRegistry.registerComponent('YourApp', () => App);
 
 // Handles location events when the React context is not active.
 // Runs even when the app is killed (foreground service must be running).
-AppRegistry.registerHeadlessTask('GeoServiceHeadlessTask', () => async (location) => {
+// Using RNGSAppRegistry.registerHeadlessTask() is preferred over
+// AppRegistry.registerHeadlessTask() directly — it automatically keeps
+// the debug panel's session store in sync while the app is killed.
+RNGSAppRegistry.registerHeadlessTask(async (location) => {
   console.log('[Background] Location:', location);
   // Send to your server using a pre-stored auth token (e.g. SecureStore/Keychain).
   // Do not rely on in-memory state — this JS context is isolated.
@@ -188,10 +192,12 @@ const tracking = await RNGeoService.isTracking();
 
 ### Register headless task via the module
 
-Alternatively to `AppRegistry.registerHeadlessTask`, you can use the helper:
+Use `registerHeadlessTask()` from the package instead of `AppRegistry.registerHeadlessTask()` directly — it wraps your handler to automatically keep the debug panel's session metrics in sync while the app is killed:
 
 ```ts
-RNGeoService.registerHeadlessTask(async (location) => {
+import RNGSAppRegistry from '@tsachit/react-native-geo-service';
+
+RNGSAppRegistry.registerHeadlessTask(async (location) => {
   await sendToServer(location);
 });
 ```
@@ -246,7 +252,7 @@ Subscribe to location updates. Call `.remove()` on the returned subscription to
 Subscribe to location errors (e.g. permission revoked mid-session).
 
 ### `registerHeadlessTask(handler)` *(Android only)*
-Register a function to handle location events when the app is not in the foreground.
+Register a function to handle location events when the app is not in the foreground. Preferred over `AppRegistry.registerHeadlessTask()` directly — automatically keeps `GeoSessionStore` in sync so the debug panel shows accurate Geopoints counts while the app is killed.
 
 ### `getBatteryInfo(): Promise<BatteryInfo>`
 Returns battery and session tracking metrics. See [Debug mode](#debug-mode) below.
@@ -284,10 +290,10 @@ interface BatteryInfo {
   levelAtStart: number;           // battery level when start() was called
   drainSinceStart: number;        // total % dropped since start() (whole device)
 
-  updateCount: number;            // location fixes received this session
+  updateCount: number;            // total location received this session
   trackingElapsedSeconds: number; // seconds since start() was called
   gpsActiveSeconds: number;       // seconds the GPS chip was actively running
-  updatesPerMinute: number;       // average location fixes per minute
+  updatesPerMinute: number;       // average total location per minute
   drainRatePerHour: number;       // battery drain rate in %/hr (whole device)
 }
 ```
@@ -312,39 +318,38 @@ Set `debug: true` in `configure()` to enable debug features:
 - **iOS** — forces the blue location arrow in the status bar while tracking is active
 - **Android** — notification title changes to `[DEBUG] <title>` so you can confirm the foreground service is running
 - **Both** — verbose native logging via `console.log` / `Logcat`
-- **Both** — a floating debug panel appears automatically showing live metrics and battery saving suggestions
+- **Both** — a floating debug panel shows live metrics and battery saving suggestions; add `<GeoDebugOverlay />` once to your component tree and it self-manages visibility
 
-### Setup (one-time)
+### Setup
 
-Add one import to the **top** of your app's `index.js`, before `AppRegistry.registerComponent`. This registers the overlay host so the panel can mount itself automatically when `debug: true` — no component needed anywhere in the app.
+Add `<GeoDebugOverlay />` once to your component tree, co-located with wherever you call `RNGeoService.start()`. It self-manages visibility — it only shows when `debug: true` is set in `configure()` and tracking is active.
 
-```ts
-// index.js
-import 'react-native-gesture-handler';
-import '@tsachit/react-native-geo-service/debug-panel'; // ← add this once
-import { AppRegistry } from 'react-native';
-import App from './App';
-import { name as appName } from './app.json';
-
-AppRegistry.registerComponent(appName, () => App);
+```tsx
+import { GeoDebugOverlay } from '@tsachit/react-native-geo-service';
+
+// Render it alongside your navigation root or wherever tracking is used:
+return (
+  <>
+    <YourNavigator />
+    <GeoDebugOverlay />
+  </>
+);
 ```
 
-> **Why must it be in `index.js`?** React Native's `AppRegistry.setWrapperComponentProvider` must be called before `registerComponent` — the same reason `react-native-gesture-handler` must also be imported there. Placing it anywhere else (e.g. inside a hook or screen) is too late; the app root has already mounted.
-
-### Auto-mount debug panel
-
-Once the setup import is in place, the panel mounts and unmounts automatically:
+Then set `debug: true` in your config:
 
 ```ts
-// Panel appears automatically when tracking starts
 await RNGeoService.configure({ debug: true, ... });
-await RNGeoService.start(); // ← panel is now visible
+await RNGeoService.start(); // panel becomes visible automatically
 
-// Panel is removed when tracking stops
-await RNGeoService.stop();
+await RNGeoService.stop();  // panel hides automatically
 ```
 
-No `<GeoDebugPanel />` or `<GeoDebugOverlay />` needed anywhere in the component tree.
+> **Note:** `GeoDebugOverlay` is a standard React component — it renders nothing in production when `debug: false`. It is safe to leave in the tree at all times.
+
+| Minimized | Opened |
+|--------|-------------|
+| <img width="349" height="261" alt="image" src="https://github.com/user-attachments/assets/a6b43b93-7a93-485d-a68d-f4e4fe658011" /> | <img width="363" height="348" alt="image" src="https://github.com/user-attachments/assets/9c02ebc9-28f2-4983-982b-810c98a32dfe" /> |
 
 ### Debug panel behaviour
 
@@ -353,17 +358,19 @@ The panel is a **draggable, minimizable floating overlay** that starts minimized
 - **Tap the 📍 circle** to expand
 - **Drag** by holding the striped header bar
 - **Minimize** with the ⊖ button — collapses back to the 📍 circle
+- **Geopoints updates in real time** on every location event — no need to wait for the poll interval
 
-**Metrics shown:**
+**Metrics shown** (all values are cumulative across app restarts — see [GeoSessionStore](#geosessionstore)):
 
 | Metric | Description |
 |--------|-------------|
-| Tracking for | How long the current session has been running |
-| Updates | Total location fixes received |
+| Started | Local date/time the very first tracking session began |
+| Tracking for | Cumulative duration across all sessions |
+| Geopoints | Total locations received across all sessions |
 | Updates/min | Average frequency of location updates |
-| GPS active | % of session time the GPS chip was on vs idle |
+| GPS active | % of total time the GPS chip was on vs idle |
 | Battery now | Current device battery level |
-| Drained | Total device battery % dropped since `start()` |
+| Drained | Total device battery % dropped since first `start()` |
 | Drain rate | Battery consumed per hour (total device, not just location) |
 
 **Smart suggestions** are shown automatically:
@@ -374,22 +381,39 @@ The panel is a **draggable, minimizable floating overlay** that starts minimized
 - 🔴 Drain rate > 8%/hr → try `'balanced'` accuracy or longer update intervals
 - ✅ All metrics in range → confirms settings are efficient
 
-> **Note:** Battery drain is measured at the whole-device level since iOS and Android do not expose per-app battery consumption via public APIs. Use GPS active % and updates/min as the primary indicators of how much the package itself is contributing.
+> **Note:** Battery drain is measured at the whole-device level since iOS and Android do not expose per-app battery consumption via public APIs. Use GPS active % and updates/min as the primary indicators of how much this package contributes.
 
-### Manual usage (optional)
+### Manual panel (optional)
 
-If you prefer to control rendering yourself, `GeoDebugPanel` and `GeoDebugOverlay` are also exported for direct use — the `debug-panel` setup import is still required for them to render correctly.
+For a custom poll interval or always-visible panel, use `GeoDebugPanel` directly:
 
 ```tsx
-import { GeoDebugPanel, GeoDebugOverlay } from '@tsachit/react-native-geo-service';
-
-// Renders anywhere in your tree — self-hides when tracking is inactive:
-<GeoDebugOverlay />
+import { GeoDebugPanel } from '@tsachit/react-native-geo-service';
 
-// Always-visible panel with custom poll interval:
 <GeoDebugPanel pollInterval={15000} />
 ```
 
+### GeoSessionStore
+
+All debug panel metrics are stored in-memory on the native side and would normally reset every time tracking restarts (app killed, OS killed the service, device rebooted). `GeoSessionStore` persists snapshots to `AsyncStorage` so the panel shows **cumulative totals** across sessions.
+
+Requires [`@react-native-async-storage/async-storage`](https://github.com/react-native-async-storage/async-storage) to be installed in your app (optional peer dependency — the panel silently skips persistence if it is not present).
+
+**Session boundaries** are detected automatically: when `batteryLevelAtStart` changes between snapshots, the previous session is archived before the new one begins. This prevents double-counting when the Android foreground service keeps running after the app is reopened.
+
+The **"↺ Reset stats"** button inside the panel clears all accumulated data and the recorded start time so you can re-measure from scratch.
+
+If you use `RNGSAppRegistry.registerHeadlessTask()`, `GeoSessionStore` is updated automatically on each headless location event — no extra code required. If you register via `AppRegistry.registerHeadlessTask()` directly, you can increment the counter manually:
+
+```ts
+import { GeoSessionStore } from '@tsachit/react-native-geo-service';
+
+AppRegistry.registerHeadlessTask('GeoServiceHeadlessTask', () => async (location) => {
+  await sendToServer(location);
+  await GeoSessionStore.onHeadlessLocation();
+});
+```
+
 ---
 
 ## Headless mode explained
@@ -419,7 +443,7 @@ Upon relaunch, the module detects `UIApplicationLaunchOptionsLocationKey`, resto
 - On iOS, use `coarseTracking: true` if ~500m granularity is acceptable — uses cell towers only
 - On Android, increase `updateIntervalMs` (e.g. `10000`) to give FusedLocationProvider room to batch fixes
 - Set `motionActivity: 'automotiveNavigation'` or `'fitness'` so iOS applies activity-specific optimisations
-- Use the `GeoDebugPanel` to measure real-world impact and act on its suggestions
+- Use the debug overlay (`debug: true`) to measure real-world impact and act on its suggestions
 
 ---
 

package/lib/GeoDebugPanel.js

@@ -49,9 +49,14 @@ exports.GeoDebugPanel = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
 const index_1 = __importDefault(require("./index"));
+const GeoSessionStore_1 = require("./GeoSessionStore");
 const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = react_native_1.Dimensions.get('window');
 const PANEL_WIDTH = Math.round(SCREEN_WIDTH * 0.95);
 const PILL_SIZE = 50;
+// Conservative estimate used when the panel hasn't rendered yet (onLayout not fired)
+const PANEL_ESTIMATED_HEIGHT = 440;
+const PANEL_BOTTOM_MARGIN = 20;
+const PILL_INITIAL_BOTTOM_MARGIN = 120;
 // ─── Formatting helpers ──────────────────────────────────────────────────────
 function formatBattery(level) {
     return level < 0 ? 'N/A' : `${level.toFixed(1)}%`;
@@ -152,17 +157,35 @@ function makePanResponder(pan, lastPos, maxWidth, maxHeight, onTap) {
     });
 }
 // ─── Component ───────────────────────────────────────────────────────────────
+function formatStartedAt(ts) {
+    if (!ts)
+        return '—';
+    const d = new Date(ts);
+    return d.toLocaleString(undefined, {
+        month: 'short', day: 'numeric',
+        hour: '2-digit', minute: '2-digit',
+    });
+}
 const GeoDebugPanel = ({ pollInterval = 30000 }) => {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e;
     const [info, setInfo] = (0, react_1.useState)(null);
     const [minimized, setMinimized] = (0, react_1.useState)(true);
-    const pan = (0, react_1.useRef)(new react_native_1.Animated.ValueXY({ x: 8, y: SCREEN_HEIGHT - 320 })).current;
-    const lastPos = (0, react_1.useRef)({ x: 8, y: SCREEN_HEIGHT - 320 });
+    const [storeData, setStoreData] = (0, react_1.useState)({
+        accumulated: { updateCount: 0, elapsedSeconds: 0, gpsActiveSeconds: 0, drain: 0 },
+        lastSnapshot: null,
+        trackingStartedAt: null,
+    });
+    // Live count updated on every location event so Geopoints doesn't wait for the poll
+    const [realtimeCount, setRealtimeCount] = (0, react_1.useState)(0);
+    const initialY = SCREEN_HEIGHT - PANEL_ESTIMATED_HEIGHT - PILL_INITIAL_BOTTOM_MARGIN;
+    const pan = (0, react_1.useRef)(new react_native_1.Animated.ValueXY({ x: 8, y: initialY })).current;
+    const lastPos = (0, react_1.useRef)({ x: 8, y: initialY });
     const panelHeight = (0, react_1.useRef)(0);
     const pillPanResponder = (0, react_1.useRef)(makePanResponder(pan, lastPos, PILL_SIZE, PILL_SIZE, () => {
+        const expandedHeight = panelHeight.current > 0 ? panelHeight.current : PANEL_ESTIMATED_HEIGHT;
         const clamped = {
             x: Math.min(lastPos.current.x, SCREEN_WIDTH - PANEL_WIDTH),
-            y: Math.min(lastPos.current.y, SCREEN_HEIGHT - panelHeight.current),
+            y: Math.min(lastPos.current.y, SCREEN_HEIGHT - expandedHeight - PANEL_BOTTOM_MARGIN),
         };
         lastPos.current = clamped;
         pan.setValue(clamped);
@@ -188,13 +211,40 @@ const GeoDebugPanel = ({ pollInterval = 30000 }) => {
         try {
             const data = yield index_1.default.getBatteryInfo();
             setInfo(data);
+            // Persist snapshot and reload accumulated so totals stay up to date
+            yield GeoSessionStore_1.GeoSessionStore.saveSnapshot(data);
+            const store = yield GeoSessionStore_1.GeoSessionStore.load();
+            setStoreData(store);
         }
         catch (_) { }
     }), []);
+    const handleReset = (0, react_1.useCallback)(() => __awaiter(void 0, void 0, void 0, function* () {
+        yield GeoSessionStore_1.GeoSessionStore.clear();
+        setStoreData({ accumulated: { updateCount: 0, elapsedSeconds: 0, gpsActiveSeconds: 0, drain: 0 }, lastSnapshot: null, trackingStartedAt: null });
+        setRealtimeCount(0);
+    }), []);
     (0, react_1.useEffect)(() => {
+        // Load accumulated history on mount
+        GeoSessionStore_1.GeoSessionStore.load().then(setStoreData).catch(() => { });
         refresh();
         const id = setInterval(refresh, pollInterval);
-        return () => clearInterval(id);
+        // Real-time Geopoints counter — increments on every location event without waiting for the poll
+        const locationSub = index_1.default.onLocation(() => {
+            setRealtimeCount(c => c + 1);
+        });
+        // Save snapshot when app is sent to background so stats survive unexpected kills
+        const appStateSub = react_native_1.AppState.addEventListener('change', status => {
+            if (status === 'background' || status === 'inactive') {
+                index_1.default.getBatteryInfo()
+                    .then(GeoSessionStore_1.GeoSessionStore.saveSnapshot)
+                    .catch(() => { });
+            }
+        });
+        return () => {
+            clearInterval(id);
+            locationSub.remove();
+            appStateSub.remove();
+        };
     }, [refresh, pollInterval]);
     // ── Minimized pill ──
     if (minimized) {
@@ -203,16 +253,25 @@ const GeoDebugPanel = ({ pollInterval = 30000 }) => {
       </react_native_1.Animated.View>);
     }
     // Safely normalise — native side returns undefined for new fields until rebuilt
-    const elapsed = (_a = info === null || info === void 0 ? void 0 : info.trackingElapsedSeconds) !== null && _a !== void 0 ? _a : 0;
-    const updates = (_b = info === null || info === void 0 ? void 0 : info.updateCount) !== null && _b !== void 0 ? _b : 0;
-    const upm = (_c = info === null || info === void 0 ? void 0 : info.updatesPerMinute) !== null && _c !== void 0 ? _c : 0;
-    const gpsActive = (_d = info === null || info === void 0 ? void 0 : info.gpsActiveSeconds) !== null && _d !== void 0 ? _d : 0;
-    const level = (_e = info === null || info === void 0 ? void 0 : info.level) !== null && _e !== void 0 ? _e : -1;
-    const drain = (_f = info === null || info === void 0 ? void 0 : info.drainSinceStart) !== null && _f !== void 0 ? _f : 0;
-    const drainRate = (_g = info === null || info === void 0 ? void 0 : info.drainRatePerHour) !== null && _g !== void 0 ? _g : 0;
+    const sessionElapsed = (_a = info === null || info === void 0 ? void 0 : info.trackingElapsedSeconds) !== null && _a !== void 0 ? _a : 0;
+    const sessionGpsActive = (_b = info === null || info === void 0 ? void 0 : info.gpsActiveSeconds) !== null && _b !== void 0 ? _b : 0;
+    const sessionDrain = (_c = info === null || info === void 0 ? void 0 : info.drainSinceStart) !== null && _c !== void 0 ? _c : 0;
+    const level = (_d = info === null || info === void 0 ? void 0 : info.level) !== null && _d !== void 0 ? _d : -1;
+    // Use the higher of the native poll count vs the live subscription count
+    // so we never show a number lower than what the native side knows about
+    const sessionUpdates = Math.max((_e = info === null || info === void 0 ? void 0 : info.updateCount) !== null && _e !== void 0 ? _e : 0, realtimeCount);
+    // Combine current session with accumulated history from previous sessions
+    const acc = storeData.accumulated;
+    const elapsed = acc.elapsedSeconds + sessionElapsed;
+    const updates = acc.updateCount + sessionUpdates;
+    const gpsActive = acc.gpsActiveSeconds + sessionGpsActive;
+    const drain = acc.drain + sessionDrain;
+    const upm = elapsed > 0 ? updates / (elapsed / 60) : 0;
+    const drainRate = elapsed > 0 ? drain / (elapsed / 3600) : 0;
     const safeInfo = info
         ? Object.assign(Object.assign({}, info), { trackingElapsedSeconds: elapsed, updateCount: updates, updatesPerMinute: upm, gpsActiveSeconds: gpsActive, drainRatePerHour: drainRate }) : null;
     const suggestions = safeInfo ? getSuggestions(safeInfo) : [];
+    const startedAt = formatStartedAt(storeData.trackingStartedAt);
     // ── Expanded panel ──
     return (<react_native_1.Animated.View style={[styles.container, { transform: pan.getTranslateTransform() }]} onLayout={e => { panelHeight.current = e.nativeEvent.layout.height; }}>
       {/* Drag header */}
@@ -231,8 +290,9 @@ const GeoDebugPanel = ({ pollInterval = 30000 }) => {
         {info ? (<>
             {/* ── Metrics grid ── */}
             <react_native_1.View style={styles.grid}>
-              <MetricBox label="Tracking for" value={elapsed > 0 ? formatElapsed(elapsed) : '—'} desc="session duration"/>
-              <MetricBox label="Updates" value={`${updates}`} desc="location fixes received"/>
+              <MetricBox label="Started" value={startedAt} desc="first session began"/>
+              <MetricBox label="Tracking for" value={elapsed > 0 ? formatElapsed(elapsed) : '—'} desc="cumulative duration"/>
+              <MetricBox label="Geopoints" value={`${updates}`} desc="total locations received"/>
               <MetricBox label="Updates/min" value={upm > 0 ? upm.toFixed(1) : '—'} desc="higher = more battery"/>
               <MetricBox label="GPS active" value={elapsed > 0 ? formatGpsPercent(gpsActive, elapsed) : '—'} desc="lower = adaptive saving"/>
               <MetricBox label="Battery now" value={formatBattery(level)} desc={info.isCharging ? '⚡ charging' : 'not charging'}/>
@@ -248,6 +308,13 @@ const GeoDebugPanel = ({ pollInterval = 30000 }) => {
                 <react_native_1.Text style={[styles.suggestionText, { color: s.color }]}>{s.text}</react_native_1.Text>
               </react_native_1.View>))}
           </>) : (<react_native_1.Text style={styles.label}>Waiting for data…</react_native_1.Text>)}
+
+        {/* ── Reset button ── */}
+        <react_native_1.View style={styles.resetRow}>
+          <react_native_1.TouchableOpacity onPress={handleReset} hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}>
+            <react_native_1.Text style={styles.resetBtn}>↺ Reset stats</react_native_1.Text>
+          </react_native_1.TouchableOpacity>
+        </react_native_1.View>
       </react_native_1.View>
     </react_native_1.Animated.View>);
 };
@@ -298,7 +365,7 @@ const styles = react_native_1.StyleSheet.create({
         minWidth: '30%', flex: 1,
         alignItems: 'center',
     },
-    metricValue: { color: '#fff', fontWeight: 'bold', fontSize: 15 },
+    metricValue: { color: '#fff', fontWeight: 'bold', fontSize: 15, textAlign: 'center' },
     metricLabel: { color: 'rgba(255,255,255,0.5)', fontSize: 9, marginTop: 2, textAlign: 'center' },
     metricSub: { color: 'rgba(255,255,255,0.3)', fontSize: 8, textAlign: 'center' },
     // Suggestions
@@ -307,6 +374,9 @@ const styles = react_native_1.StyleSheet.create({
     suggestion: { flexDirection: 'row', alignItems: 'flex-start', marginBottom: 5, gap: 6 },
     suggestionEmoji: { fontSize: 12, lineHeight: 16 },
     suggestionText: { fontSize: 11, lineHeight: 16, flex: 1 },
+    // Reset
+    resetRow: { alignItems: 'flex-end', marginTop: 10 },
+    resetBtn: { color: 'rgba(255,255,255,0.45)', fontSize: 13, paddingVertical: 6, paddingHorizontal: 10 },
     // Minimized pill
     pill: {
         position: 'absolute',

package/lib/GeoSessionStore.d.ts

@@ -0,0 +1,65 @@
+/**
+ * GeoSessionStore — persists debug panel metrics across app sessions.
+ *
+ * Metrics live in-memory on the native side and reset whenever tracking
+ * restarts (app killed, OS killed the service, device rebooted). This store
+ * snapshots values to AsyncStorage so the debug panel can show cumulative
+ * totals spanning multiple sessions.
+ *
+ * Storage key: @rn_geo_service/debug_session
+ *
+ * Schema:
+ *   accumulated   — sum of all fully-closed previous sessions
+ *   lastSnapshot  — most recent known state; used to detect session boundaries
+ *   trackingStartedAt — Unix ms timestamp of the very first start() ever recorded
+ *                       (not overwritten until clear() is called)
+ */
+import type { BatteryInfo } from './types';
+export interface AccumulatedStats {
+    updateCount: number;
+    elapsedSeconds: number;
+    gpsActiveSeconds: number;
+    drain: number;
+}
+export interface SnapshotStats extends AccumulatedStats {
+    batteryLevelAtStart: number;
+}
+export interface StoreData {
+    accumulated: AccumulatedStats;
+    lastSnapshot: SnapshotStats | null;
+    /** Unix ms — when the very first session began. Null until first saveSnapshot(). */
+    trackingStartedAt: number | null;
+}
+/**
+ * Load accumulated stats + trackingStartedAt from storage.
+ * Returns zero defaults if nothing has been stored yet.
+ */
+declare function load(): Promise<StoreData>;
+/**
+ * Snapshot the current session's BatteryInfo into storage.
+ *
+ * - Detects session boundaries via batteryLevelAtStart:
+ *   if it differs from the stored lastSnapshot, the previous session is
+ *   archived into accumulated before storing the new snapshot.
+ * - Records trackingStartedAt on the very first call (never overwritten).
+ */
+declare function saveSnapshot(info: BatteryInfo): Promise<void>;
+/**
+ * Called from the Android headless task when the app is killed but the
+ * foreground service is still delivering location updates.
+ * Increments the updateCount in lastSnapshot by 1.
+ * Safe to call from a HeadlessJS context (no native bridge required).
+ */
+declare function onHeadlessLocation(): Promise<void>;
+/**
+ * Clear all accumulated data, lastSnapshot, and trackingStartedAt.
+ * The panel reverts to current-session-only view after calling this.
+ */
+declare function clear(): Promise<void>;
+export declare const GeoSessionStore: {
+    load: typeof load;
+    saveSnapshot: typeof saveSnapshot;
+    onHeadlessLocation: typeof onHeadlessLocation;
+    clear: typeof clear;
+};
+export {};

package/lib/GeoSessionStore.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * GeoSessionStore — persists debug panel metrics across app sessions.
+ *
+ * Metrics live in-memory on the native side and reset whenever tracking
+ * restarts (app killed, OS killed the service, device rebooted). This store
+ * snapshots values to AsyncStorage so the debug panel can show cumulative
+ * totals spanning multiple sessions.
+ *
+ * Storage key: @rn_geo_service/debug_session
+ *
+ * Schema:
+ *   accumulated   — sum of all fully-closed previous sessions
+ *   lastSnapshot  — most recent known state; used to detect session boundaries
+ *   trackingStartedAt — Unix ms timestamp of the very first start() ever recorded
+ *                       (not overwritten until clear() is called)
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeoSessionStore = void 0;
+const STORAGE_KEY = '@rn_geo_service/debug_session';
+// Lazily required so the package doesn't hard-crash if AsyncStorage is not
+// installed in the host app (it's a peerDependency).
+function getStorage() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return require('@react-native-async-storage/async-storage').default;
+    }
+    catch (_) {
+        return null;
+    }
+}
+const ZERO_ACCUMULATED = {
+    updateCount: 0,
+    elapsedSeconds: 0,
+    gpsActiveSeconds: 0,
+    drain: 0,
+};
+function addStats(a, b) {
+    return {
+        updateCount: a.updateCount + b.updateCount,
+        elapsedSeconds: a.elapsedSeconds + b.elapsedSeconds,
+        gpsActiveSeconds: a.gpsActiveSeconds + b.gpsActiveSeconds,
+        drain: a.drain + b.drain,
+    };
+}
+function readRaw() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const storage = getStorage();
+        if (!storage)
+            return { accumulated: Object.assign({}, ZERO_ACCUMULATED), lastSnapshot: null, trackingStartedAt: null };
+        try {
+            const raw = yield storage.getItem(STORAGE_KEY);
+            if (!raw)
+                return { accumulated: Object.assign({}, ZERO_ACCUMULATED), lastSnapshot: null, trackingStartedAt: null };
+            return JSON.parse(raw);
+        }
+        catch (_) {
+            return { accumulated: Object.assign({}, ZERO_ACCUMULATED), lastSnapshot: null, trackingStartedAt: null };
+        }
+    });
+}
+function writeRaw(data) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const storage = getStorage();
+        if (!storage)
+            return;
+        try {
+            yield storage.setItem(STORAGE_KEY, JSON.stringify(data));
+        }
+        catch (_) { }
+    });
+}
+/**
+ * Load accumulated stats + trackingStartedAt from storage.
+ * Returns zero defaults if nothing has been stored yet.
+ */
+function load() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return readRaw();
+    });
+}
+/**
+ * Snapshot the current session's BatteryInfo into storage.
+ *
+ * - Detects session boundaries via batteryLevelAtStart:
+ *   if it differs from the stored lastSnapshot, the previous session is
+ *   archived into accumulated before storing the new snapshot.
+ * - Records trackingStartedAt on the very first call (never overwritten).
+ */
+function saveSnapshot(info) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e;
+        const data = yield readRaw();
+        const newSnapshot = {
+            updateCount: (_a = info.updateCount) !== null && _a !== void 0 ? _a : 0,
+            elapsedSeconds: (_b = info.trackingElapsedSeconds) !== null && _b !== void 0 ? _b : 0,
+            gpsActiveSeconds: (_c = info.gpsActiveSeconds) !== null && _c !== void 0 ? _c : 0,
+            drain: (_d = info.drainSinceStart) !== null && _d !== void 0 ? _d : 0,
+            batteryLevelAtStart: (_e = info.levelAtStart) !== null && _e !== void 0 ? _e : -1,
+        };
+        let { accumulated, trackingStartedAt } = data;
+        // Detect session boundary — a different batteryLevelAtStart means start() was called again
+        if (data.lastSnapshot !== null &&
+            data.lastSnapshot.batteryLevelAtStart !== newSnapshot.batteryLevelAtStart) {
+            accumulated = addStats(accumulated, data.lastSnapshot);
+        }
+        // Record start time once — on the very first snapshot ever, or after a clear()
+        if (trackingStartedAt === null) {
+            trackingStartedAt = Date.now();
+        }
+        yield writeRaw({ accumulated, lastSnapshot: newSnapshot, trackingStartedAt });
+    });
+}
+/**
+ * Called from the Android headless task when the app is killed but the
+ * foreground service is still delivering location updates.
+ * Increments the updateCount in lastSnapshot by 1.
+ * Safe to call from a HeadlessJS context (no native bridge required).
+ */
+function onHeadlessLocation() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const data = yield readRaw();
+        const snap = (_a = data.lastSnapshot) !== null && _a !== void 0 ? _a : {
+            updateCount: 0,
+            elapsedSeconds: 0,
+            gpsActiveSeconds: 0,
+            drain: 0,
+            batteryLevelAtStart: -1,
+        };
+        yield writeRaw(Object.assign(Object.assign({}, data), { lastSnapshot: Object.assign(Object.assign({}, snap), { updateCount: snap.updateCount + 1 }) }));
+    });
+}
+/**
+ * Clear all accumulated data, lastSnapshot, and trackingStartedAt.
+ * The panel reverts to current-session-only view after calling this.
+ */
+function clear() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const storage = getStorage();
+        if (!storage)
+            return;
+        try {
+            yield storage.removeItem(STORAGE_KEY);
+        }
+        catch (_) { }
+    });
+}
+exports.GeoSessionStore = { load, saveSnapshot, onHeadlessLocation, clear };

package/lib/index.d.ts

@@ -4,9 +4,6 @@ export declare function _isDebugMode(): boolean;
 /**
  * Configure the geo service. Call this before start().
  * Safe to call multiple times; subsequent calls update the config.
- *
- * When debug: true, a draggable debug overlay is mounted automatically —
- * no component needs to be added to the app.
  */
 declare function configure(config: GeoServiceConfig): Promise<void>;
 /**
@@ -89,3 +86,5 @@ declare const RNGeoService: {
 export default RNGeoService;
 export { GeoDebugPanel } from './GeoDebugPanel';
 export { GeoDebugOverlay } from './GeoDebugOverlay';
+export { GeoSessionStore } from './GeoSessionStore';
+export type { AccumulatedStats, StoreData } from './GeoSessionStore';

package/lib/index.js

@@ -23,7 +23,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GeoDebugOverlay = exports.GeoDebugPanel = void 0;
+exports.GeoSessionStore = exports.GeoDebugOverlay = exports.GeoDebugPanel = void 0;
 exports._isDebugMode = _isDebugMode;
 const react_native_1 = require("react-native");
 __exportStar(require("./types"), exports);
@@ -61,28 +61,13 @@ function _isDebugMode() { return _debugMode; }
 /**
  * Configure the geo service. Call this before start().
  * Safe to call multiple times; subsequent calls update the config.
- *
- * When debug: true, a draggable debug overlay is mounted automatically —
- * no component needs to be added to the app.
  */
 function configure(config) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
-        const wasDebug = _debugMode;
         _debugMode = (_a = config.debug) !== null && _a !== void 0 ? _a : false;
         const merged = Object.assign(Object.assign({}, DEFAULT_CONFIG), config);
-        const result = nativeModule.configure(merged);
-        // Lazy require to avoid circular dependency at module init time.
-        // autoDebug → GeoDebugOverlay → GeoDebugPanel → index (all lazy references).
-        if (_debugMode && !wasDebug) {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            require('./autoDebug').mountDebugOverlay();
-        }
-        else if (!_debugMode && wasDebug) {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            require('./autoDebug').unmountDebugOverlay();
-        }
-        return result;
+        return nativeModule.configure(merged);
     });
 }
 /**
@@ -92,12 +77,7 @@ function configure(config) {
  */
 function start() {
     return __awaiter(this, void 0, void 0, function* () {
-        const result = nativeModule.start();
-        if (_debugMode) {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            require('./autoDebug').mountDebugOverlay();
-        }
-        return result;
+        return nativeModule.start();
     });
 }
 /**
@@ -105,12 +85,7 @@ function start() {
  */
 function stop() {
     return __awaiter(this, void 0, void 0, function* () {
-        const result = nativeModule.stop();
-        if (_debugMode) {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            require('./autoDebug').unmountDebugOverlay();
-        }
-        return result;
+        return nativeModule.stop();
     });
 }
 /**
@@ -173,7 +148,12 @@ function registerHeadlessTask(handler) {
     if (react_native_1.Platform.OS !== 'android')
         return;
     const taskName = DEFAULT_CONFIG.backgroundTaskName;
-    react_native_1.AppRegistry.registerHeadlessTask(taskName, () => handler);
+    react_native_1.AppRegistry.registerHeadlessTask(taskName, () => (location) => __awaiter(this, void 0, void 0, function* () {
+        // Keep GeoSessionStore's updateCount in sync while the app is killed
+        const { GeoSessionStore } = require('./GeoSessionStore');
+        yield GeoSessionStore.onHeadlessLocation();
+        yield handler(location);
+    }));
 }
 /**
  * Returns battery information including current level and drain since tracking started.
@@ -210,3 +190,5 @@ var GeoDebugPanel_1 = require("./GeoDebugPanel");
 Object.defineProperty(exports, "GeoDebugPanel", { enumerable: true, get: function () { return GeoDebugPanel_1.GeoDebugPanel; } });
 var GeoDebugOverlay_1 = require("./GeoDebugOverlay");
 Object.defineProperty(exports, "GeoDebugOverlay", { enumerable: true, get: function () { return GeoDebugOverlay_1.GeoDebugOverlay; } });
+var GeoSessionStore_1 = require("./GeoSessionStore");
+Object.defineProperty(exports, "GeoSessionStore", { enumerable: true, get: function () { return GeoSessionStore_1.GeoSessionStore; } });

package/lib/types.d.ts

@@ -146,7 +146,7 @@ export interface BatteryInfo {
     levelAtStart: number;
     /** Percentage points drained since tracking started */
     drainSinceStart: number;
-    /** How many location fixes have been delivered since start() */
+    /** How many total location have been delivered since start() */
     updateCount: number;
     /** Total seconds since start() was called */
     trackingElapsedSeconds: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsachit/react-native-geo-service",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Battery-efficient background geolocation for React Native with headless support",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -8,9 +8,7 @@
     "lib",
     "android",
     "ios",
-    "react-native-geo-service.podspec",
-    "debug-panel.js",
-    "debug-panel.d.ts"
+    "react-native-geo-service.podspec"
   ],
   "scripts": {
     "build": "tsc",
@@ -27,7 +25,13 @@
   "author": "Sachit Karki",
   "license": "MIT",
   "peerDependencies": {
-    "react-native": ">=0.60.0"
+    "react-native": ">=0.60.0",
+    "@react-native-async-storage/async-storage": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/react": "^18.3.28",
@@ -41,8 +45,5 @@
   "bugs": {
     "url": "https://github.com/tsachit/react-native-geo-service/issues"
   },
-  "homepage": "https://github.com/tsachit/react-native-geo-service#readme",
-  "dependencies": {
-    "react-native-root-siblings": "^5.0.1"
-  }
+  "homepage": "https://github.com/tsachit/react-native-geo-service#readme"
 }

package/debug-panel.d.ts

@@ -1 +0,0 @@
-export {};

package/debug-panel.js

@@ -1 +0,0 @@
-require('./lib/setup');

package/lib/autoDebug.d.ts

@@ -1,2 +0,0 @@
-export declare function mountDebugOverlay(): void;
-export declare function unmountDebugOverlay(): void;

package/lib/autoDebug.js

@@ -1,22 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.mountDebugOverlay = mountDebugOverlay;
-exports.unmountDebugOverlay = unmountDebugOverlay;
-const react_1 = __importDefault(require("react"));
-const react_native_root_siblings_1 = __importDefault(require("react-native-root-siblings"));
-const GeoDebugOverlay_1 = require("./GeoDebugOverlay");
-let sibling = null;
-function mountDebugOverlay() {
-    if (!sibling) {
-        sibling = new react_native_root_siblings_1.default(react_1.default.createElement(GeoDebugOverlay_1.GeoDebugOverlay));
-    }
-}
-function unmountDebugOverlay() {
-    if (sibling) {
-        sibling.destroy();
-        sibling = null;
-    }
-}

package/lib/setup.d.ts

@@ -1 +0,0 @@
-export {};

package/lib/setup.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Import this file ONCE at the top of your app's index.js, before
- * AppRegistry.registerComponent. This registers RootSiblingParent as
- * the app wrapper so GeoService can render the debug overlay automatically
- * when configure({ debug: true }) is called — no component needed in the tree.
- *
- * index.js:
- *   import '@tsachit/react-native-geo-service/setup';  // ← add this line
- *   import { AppRegistry } from 'react-native';
- *   import App from './App';
- *   AppRegistry.registerComponent('MyApp', () => App);
- */
-const react_native_1 = require("react-native");
-const react_native_root_siblings_1 = require("react-native-root-siblings");
-react_native_1.AppRegistry.setWrapperComponentProvider(() => react_native_root_siblings_1.RootSiblingParent);