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

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
 
 ---
@@ -284,10 +284,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 +312,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
 
@@ -359,7 +358,7 @@ The panel is a **draggable, minimizable floating overlay** that starts minimized
 | Metric | Description |
 |--------|-------------|
 | Tracking for | How long the current session has been running |
-| Updates | Total location fixes received |
+| Geopoints | Total locations received |
 | Updates/min | Average frequency of location updates |
 | GPS active | % of session time the GPS chip was on vs idle |
 | Battery now | Current device battery level |
@@ -374,19 +373,15 @@ 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} />
 ```
 
@@ -419,7 +414,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

@@ -232,7 +232,7 @@ const GeoDebugPanel = ({ pollInterval = 30000 }) => {
             {/* ── 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="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'}/>

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>;
 /**

package/lib/index.js

@@ -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();
     });
 }
 /**

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.3",
   "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",
@@ -41,8 +39,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);