@tokamakdev/plugin-location 0.1.0-beta.103 → 0.1.0-beta.104

package/README.md

@@ -1,8 +1,8 @@
 # @tokamakdev/plugin-location
 
-Location for tokamak applications and the web: positions on request, and
-updates, regions, significant changes and visits that reach the app's Worker
-off screen.
+Location for tokamak applications and the web: positions on request,
+long-term location awareness from significant changes, visits and regions,
+and continuous tracking, all of which reach the app's Worker off screen.
 
 ```sh
 npm install @tokamakdev/plugin-location
@@ -15,16 +15,20 @@ const position = await location.getCurrentPosition();
 const stop = location.watchPosition((next) => console.log(next.coords), console.error);
 
 await location.requestPermission({ background: true });
-await location.startUpdates({ activity: "fitness", accuracy: "high", distance: 10 });
 await location.addRegion({ id: "home", latitude: 51.5, longitude: -0.12, radius: 150 });
 ```
 
 ```ts
 // src/tokamak.ts
+import { location } from "@tokamakdev/plugin-location";
 import { onLocationUpdate, onRegionTransition } from "@tokamakdev/plugin-location/events";
+import { onStart } from "@tokamakdev/tok/events";
 
-onLocationUpdate(async ({ positions }, env) => {
-  await fetch("https://example.com/track", { method: "POST", body: JSON.stringify(positions) });
+onStart(async () => {
+  await location.setup({ significantChanges: true, visits: true });
+});
+onLocationUpdate(async ({ positions }) => {
+  await fetch("https://example.com/whereabouts", { method: "POST", body: JSON.stringify(positions) });
 });
 onRegionTransition(({ id, transition }) => console.log(id, transition));
 ```
@@ -131,13 +135,38 @@ The plugin's `onLocationUpdate`, `onRegionTransition`, `onVisit` and
 `onLocationError` methods receive the same events while the listening page or
 Worker runs, and return the function that removes the listener.
 
-## Updates
-
-`startUpdates(options)` starts continuous updates, replacing any running,
-until `stopUpdates()`. `getUpdates()` resolves with the running updates'
-options, or null. Updates need in-use permission, and reject with
-`NotAllowedError` without it. The plugin keeps them across launches and
-restarts.
+## Long-term awareness
+
+`setup(config)` keeps the app aware of where the device is over days, with
+little power and no indicator. Call it from `onStart` in `src/tokamak.ts`, so
+it applies at every launch; the plugin also keeps it and applies it again
+itself. The configuration replaces the previous one, and an invalid one
+rejects with `TypeError` and changes nothing. Apple platforms reject with
+`NotSupportedError` where the device cannot monitor significant changes.
+
+- `significantChanges` delivers moves of 500 metres or more, at most every 5
+  minutes, to `onLocationUpdate`, located from cellular and Wi-Fi rather than
+  GPS. Apple platforms use the significant-change service. Android uses a
+  low-power request with the same thresholds, which it limits to a few an hour
+  off screen. Without permission they start once the app has it on Apple
+  platforms, and on Android after the plugin's prompt or at the next launch.
+- `visits`, Apple only, delivers arrivals at and departures from the places
+  the user stays to `onVisit`. It uses the least power of all.
+
+With background permission, iOS relaunches the app for both, and Android starts
+the app's process for significant changes. [Regions](#regions) wake the app
+the same way.
+
+## Continuous tracking
+
+`startUpdates(options)` starts continuous updates for an activity the user
+follows, such as a run or navigation, replacing any running, until
+`stopUpdates()`. Off screen the system can show that the app is tracking:
+iOS's blue location pill with in-use permission, and the notification of
+Android's foreground service.
+`getUpdates()` resolves with the running updates' options, or null. Updates
+need in-use permission, and reject with `NotAllowedError` without it. The
+plugin keeps them across launches and restarts.
 
 **Apple** uses `CLLocationUpdate.liveUpdates`.
 
@@ -147,9 +176,9 @@ restarts.
 - Updates pause while the device is still and resume when it moves.
 - If iOS ends the app while updates run, it launches the app for the next
   update, and the plugin resumes them.
-- Off screen, updates need the `background-updates` build setting, which
-  shows the location indicator, or Always permission. `startUpdates` rejects
-  with `NeedsUIError` off screen on iOS.
+- Off screen, updates need Always permission, or the `background-updates`
+  build setting, whose background activity session shows the pill.
+  `startUpdates` rejects with `NeedsUIError` off screen on iOS.
 - From iOS 18, failures such as denied permission or lost location reach
   `onLocationError` once each.
 - `getCurrentPosition` and `watchPosition` can change the coordinates updates
@@ -197,16 +226,6 @@ and background permission off screen.
   happens. Adding a region again, as the plugin does after a restart, reports
   an entry again for a device inside.
 
-## Significant changes and visits
-
-On Apple platforms, `setup(config)` starts what runs at every launch:
-`significantChanges` delivers significant changes of location to
-`onLocationUpdate`, and `visits` delivers visits to `onVisit`. Call it from
-`onStart` in `src/tokamak.ts`. The configuration replaces the previous one,
-which the plugin keeps and applies again at each launch; an invalid one
-rejects with `TypeError` and changes nothing. With Always permission, the
-system relaunches the app for both. Android ignores `setup`'s keys.
-
 ## Platforms
 
 The web uses `navigator.geolocation`. `permission()` reports `inUse` from the

package/android/LocationPlugin.kt

@@ -48,7 +48,8 @@ class TokamakLocationPlugin(
     /** Foreground location permissions, which the `precision` build setting declares. */
     private val foreground: Set<String> by lazy { setOf(COARSE, FINE).filter(declared::contains).toSet() }
 
-    private val updates = LocationUpdates(context)
+    private val updates = LocationUpdates(context, LocationUpdates.UPDATES)
+    private val significantChanges = LocationUpdates(context, LocationUpdates.SIGNIFICANT_CHANGES)
     private val regions = LocationRegions(context)
     private val events = LocationEvents(host)
 
@@ -64,13 +65,12 @@ class TokamakLocationPlugin(
 
     /** Starts the updates' foreground service again once the app is on screen. */
     override fun onIntent(intent: Intent) {
-        if (host.isInForeground) updates.startService()
+        if (host.isInForeground) startService()
     }
 
     override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
         when (method) {
-            // Significant changes and visits, setup's keys, are Apple's.
-            "setup" -> reply(Result.success(null))
+            "setup" -> setup(requireObject(arguments), reply)
             "getCurrentPosition" ->
                 withPermission { granted ->
                     if (granted) currentPosition(arguments as? JSONObject, reply) else reply(Result.failure(permissionDenied()))
@@ -81,7 +81,7 @@ class TokamakLocationPlugin(
             "openSettings" -> openSettings(reply)
             "startUpdates" -> startUpdates(requireObject(arguments), reply)
             "stopUpdates" -> {
-                updates.stop()
+                stopUpdates()
                 reply(Result.success(null))
             }
             "getUpdates" -> reply(Result.success(updates.options))
@@ -122,11 +122,19 @@ class TokamakLocationPlugin(
      * Throws `NeedsUIError` when asking would show UI while the app is in the background.
      */
     private fun withPermission(action: (Boolean) -> Unit) {
-        if (hasForegroundPermission()) {
-            action(true)
-            return
+        if (hasForegroundPermission()) action(true) else askForeground(foreground, action)
+    }
+
+    /**
+     * Asks for the foreground [permissions], then passes [action] whether the app has one, first
+     * starting what waited for permission.
+     */
+    private fun askForeground(permissions: Set<String>, action: (Boolean) -> Unit) {
+        host.requestPermissions(permissions) { granted ->
+            val allowed = granted.containsValue(true)
+            if (allowed) restore(updatesRemoved = false)
+            action(allowed)
         }
-        host.requestPermissions(foreground) { granted -> action(granted.containsValue(true)) }
     }
 
     private fun granted(permission: String): Boolean =
@@ -162,8 +170,8 @@ class TokamakLocationPlugin(
             throw TokamakPluginError.notSupported("Background location needs the location plugin's background build setting")
         }
         val asked = if (options.optionalString("precision") == "approximate") setOf(COARSE) else foreground
-        host.requestPermissions(asked) { granted ->
-            if (!background || !granted.containsValue(true)) return@requestPermissions reply(Result.success(permission()))
+        askForeground(asked) { allowed ->
+            if (!background || !allowed) return@askForeground reply(Result.success(permission()))
             runCatching { host.requestPermissions(setOf(BACKGROUND)) { reply(Result.success(permission())) } }
                 .onFailure { reply(Result.failure(it)) }
         }
@@ -173,11 +181,43 @@ class TokamakLocationPlugin(
         if (!hasForegroundPermission()) throw TokamakPluginError("NotAllowedError", "Location permission has not been granted")
     }
 
+    /** Starts updates in the foreground service when [options] name one, which stops otherwise. On failure, none run. */
     private fun startUpdates(options: JSONObject, reply: TokamakPluginReply) {
         requirePermission()
-        if (options.has("foregroundService")) requireService()
-        runCatching { updates.start(options) }
-            .onSuccess { reply(Result.success(null)) }
+        val notification = options.optJSONObject("foregroundService")
+        if (notification != null) requireService()
+        runCatching {
+            if (notification == null) TokamakLocationService.stop(context) else TokamakLocationService.start(context, notification)
+            updates.start(options)
+        }.onSuccess { reply(Result.success(null)) }
+            .onFailure {
+                stopUpdates()
+                reply(Result.failure(locationError(it)))
+            }
+    }
+
+    private fun stopUpdates() {
+        updates.stop()
+        TokamakLocationService.stop(context)
+    }
+
+    private fun startService() {
+        updates.options?.optJSONObject("foregroundService")?.let { TokamakLocationService.start(context, it) }
+    }
+
+    /**
+     * Starts significant changes when [config] names them, and stops them otherwise. Without
+     * permission they start once the app has it.
+     */
+    private fun setup(config: JSONObject, reply: TokamakPluginReply) {
+        val options = JSONObject(SIGNIFICANT_CHANGE_OPTIONS)
+        runCatching {
+            when {
+                !config.optBoolean("significantChanges") -> significantChanges.stop()
+                hasForegroundPermission() -> significantChanges.start(options)
+                else -> significantChanges.keep(options)
+            }
+        }.onSuccess { reply(Result.success(null)) }
             .onFailure { reply(Result.failure(locationError(it))) }
     }
 
@@ -201,13 +241,16 @@ class TokamakLocationPlugin(
     }
 
     /**
-     * Restores updates and regions, and starts the updates' foreground service on screen, or after a
-     * restart or an update with background permission. Reports a failure to `onLocationError`.
+     * Restores updates, significant changes and regions where the app has permission, as Android
+     * pauses them without it, and starts the updates' foreground service on screen, or after a restart
+     * or an update with background permission. Reports a failure to `onLocationError`.
      */
     internal fun restore(updatesRemoved: Boolean) {
+        if (!hasForegroundPermission()) return
         runCatching {
             updates.restore(updatesRemoved)
-            if (host.isInForeground || (updatesRemoved && granted(BACKGROUND))) updates.startService()
+            significantChanges.restore(updatesRemoved)
+            if (host.isInForeground || (updatesRemoved && granted(BACKGROUND))) startService()
         }.onFailure { events.fail(locationError(it)) }
         runCatching { regions.restore() }.onFailure { events.fail(locationError(it)) }
     }
@@ -369,5 +412,8 @@ class TokamakLocationPlugin(
         const val FINE = Manifest.permission.ACCESS_FINE_LOCATION
         const val COARSE = Manifest.permission.ACCESS_COARSE_LOCATION
         const val BACKGROUND = Manifest.permission.ACCESS_BACKGROUND_LOCATION
+
+        /** Apple's significant-change service's thresholds: 500 metres or more, at most every 5 minutes, without GPS. */
+        const val SIGNIFICANT_CHANGE_OPTIONS = """{"accuracy":"low","interval":300000,"distance":500}"""
     }
 }

package/android/LocationService.kt

@@ -5,6 +5,7 @@ import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.app.PendingIntent
 import android.app.Service
+import android.content.Context
 import android.content.Intent
 import android.content.pm.ServiceInfo
 import android.os.IBinder
@@ -25,7 +26,7 @@ class TokamakLocationService : Service() {
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
         val content =
             intent?.getStringExtra(NOTIFICATION_EXTRA)?.let(::JSONObject)
-                ?: LocationUpdates(this).options?.optJSONObject("foregroundService")
+                ?: LocationUpdates(this, LocationUpdates.UPDATES).options?.optJSONObject("foregroundService")
         if (content == null) {
             stopSelf()
             return START_NOT_STICKY
@@ -59,6 +60,16 @@ class TokamakLocationService : Service() {
 
     companion object {
         /** The start intent's notification, as JSON. */
-        const val NOTIFICATION_EXTRA = "com.tokamak.plugins.location.NOTIFICATION"
+        private const val NOTIFICATION_EXTRA = "com.tokamak.plugins.location.NOTIFICATION"
+
+        /** Starts the service showing [notification], or shows it in the running service. */
+        fun start(context: Context, notification: JSONObject) {
+            val start = Intent(context, TokamakLocationService::class.java).putExtra(NOTIFICATION_EXTRA, notification.toString())
+            context.startForegroundService(start)
+        }
+
+        fun stop(context: Context) {
+            context.stopService(Intent(context, TokamakLocationService::class.java))
+        }
     }
 }

package/android/LocationUpdates.kt

@@ -9,11 +9,8 @@ import android.location.LocationManager
 import android.location.LocationRequest
 import org.json.JSONObject
 
+/** The JSON of each kind of updates' options, by name. */
 private const val PREFERENCES = "tokamak.location"
-
-/** The JSON of the running updates' options, as `startUpdates` received them. */
-private const val UPDATES = "updates"
-private const val UPDATES_ACTION = "com.tokamak.plugins.location.UPDATES"
 private const val DEFAULT_INTERVAL_MILLIS = 10_000L
 
 private val QUALITIES =
@@ -24,55 +21,42 @@ private val QUALITIES =
     )
 
 /**
- * Continuous updates, which `LocationManager` sends to [TokamakLocationReceiver] through a
- * `PendingIntent`, starting the app's process when it has ended, with [TokamakLocationService] when
- * their options name a `foregroundService`. The options persist until [stop], and [restore] requests
- * them again where Android removed the request. Use it on the main thread.
+ * Location updates of one kind, [name]: `startUpdates`' or significant changes'. `LocationManager`
+ * sends them to [TokamakLocationReceiver] through a `PendingIntent`, starting the app's process when
+ * it has ended. Their options persist until [stop], and [restore] requests them where they are not
+ * running. Use it on the main thread.
  */
-internal class LocationUpdates(private val context: Context) {
+internal class LocationUpdates(private val context: Context, private val name: String) {
     private val manager = context.getSystemService(LocationManager::class.java)
     private val preferences = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
 
-    /** The options of the running updates, or null. */
+    /** The options of the updates, or null. */
     val options: JSONObject?
-        get() = preferences.getString(UPDATES, null)?.let(::JSONObject)
+        get() = preferences.getString(name, null)?.let(::JSONObject)
+
+    /** Keeps [options], which [restore] requests. */
+    fun keep(options: JSONObject) {
+        preferences.edit().putString(name, options.toString()).apply()
+    }
 
     /**
-     * Starts updates with [options], replacing any running, in the foreground service when they name
-     * one, which stops otherwise. Throws `SecurityException` without permission.
+     * Keeps [options] and requests updates with them, replacing others; the same options running
+     * change nothing. Throws `SecurityException` without permission.
      */
     fun start(options: JSONObject) {
-        val notification = options.optJSONObject("foregroundService")
-        if (notification == null) stopService() else startService(notification)
+        if (options.toString() == preferences.getString(name, null) && isRequested()) return
+        keep(options)
         request(options)
-        preferences.edit().putString(UPDATES, options.toString()).apply()
     }
 
     fun stop() {
-        preferences.edit().remove(UPDATES).apply()
-        stopService()
+        preferences.edit().remove(name).apply()
         pendingIntent(PendingIntent.FLAG_NO_CREATE)?.let {
             manager.removeUpdates(it)
             it.cancel()
         }
     }
 
-    /** Starts the running updates' foreground service, if they have one. */
-    fun startService() {
-        options?.optJSONObject("foregroundService")?.let(::startService)
-    }
-
-    private fun startService(notification: JSONObject) {
-        val start =
-            Intent(context, TokamakLocationService::class.java)
-                .putExtra(TokamakLocationService.NOTIFICATION_EXTRA, notification.toString())
-        context.startForegroundService(start)
-    }
-
-    private fun stopService() {
-        context.stopService(Intent(context, TokamakLocationService::class.java))
-    }
-
     /**
      * Requests the running updates again when Android [removed] the request, when their
      * `PendingIntent` no longer exists, or after a force stop, which removes the request on Android
@@ -80,9 +64,11 @@ internal class LocationUpdates(private val context: Context) {
      */
     fun restore(removed: Boolean) {
         val options = options ?: return
-        if (removed || forceStopped() || pendingIntent(PendingIntent.FLAG_NO_CREATE) == null) request(options)
+        if (removed || forceStopped() || !isRequested()) request(options)
     }
 
+    private fun isRequested(): Boolean = pendingIntent(PendingIntent.FLAG_NO_CREATE) != null
+
     /** Whether the app's process last ended by the user's force stop. */
     private fun forceStopped(): Boolean =
         context.getSystemService(ActivityManager::class.java)
@@ -98,7 +84,13 @@ internal class LocationUpdates(private val context: Context) {
                 .setMinUpdateDistanceMeters(options.optDouble("distance", 0.0).toFloat())
                 .build()
         val updates = checkNotNull(pendingIntent(PendingIntent.FLAG_UPDATE_CURRENT))
-        manager.requestLocationUpdates(provider(accuracy), request, updates)
+        try {
+            manager.requestLocationUpdates(provider(accuracy), request, updates)
+        } catch (error: Exception) {
+            // Without the `PendingIntent`, [restore] requests them again.
+            updates.cancel()
+            throw error
+        }
     }
 
     /** The fused provider when the device has one, and otherwise GPS for high accuracy and the network for less. */
@@ -114,7 +106,15 @@ internal class LocationUpdates(private val context: Context) {
         PendingIntent.getBroadcast(
             context,
             0,
-            Intent(context, TokamakLocationReceiver::class.java).setAction(UPDATES_ACTION),
+            Intent(context, TokamakLocationReceiver::class.java).setAction("com.tokamak.plugins.location.${name.uppercase()}"),
             flags or PendingIntent.FLAG_MUTABLE,
         )
+
+    companion object {
+        /** `startUpdates`' updates. */
+        const val UPDATES = "updates"
+
+        /** Significant changes, as `setup` starts them. */
+        const val SIGNIFICANT_CHANGES = "significantChanges"
+    }
 }

package/apple/LocationPlugin.swift

@@ -239,8 +239,11 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     }
   }
 
+  /// Core Location delivers each visit to every manager's delegate.
   func locationManager(_ manager: CLLocationManager, didVisit visit: CLVisit) {
-    events.visit(visit)
+    if manager === monitoring {
+      events.visit(visit)
+    }
   }
 
   /// Starts the significant changes and visits `config` names, and stops the

package/apple/LocationRegions.swift

@@ -7,6 +7,8 @@ import Foundation
 
 /// The JSON of each monitored region, as `addRegion` received it, by id.
 private let regionsKey = "tokamak.location.regions"
+/// The ids of the regions whose last transition was an entry.
+private let insideKey = "tokamak.location.inside"
 /// `CLMonitor` monitors at most 20 conditions for an app, and reports no
 /// error beyond them.
 private let regionLimit = 20
@@ -24,7 +26,7 @@ final class TokamakLocationRegions {
   init(events: TokamakLocationEvents) {
     self.events = events
     let monitor = Task { @MainActor in
-      await Self.protectedData()
+      await Self.firstUnlock()
       return await CLMonitor(monitorName)
     }
     self.monitor = monitor
@@ -51,6 +53,11 @@ final class TokamakLocationRegions {
     }
   }
 
+  private var inside: Set<String> {
+    get { Set(defaults.stringArray(forKey: insideKey) ?? []) }
+    set { defaults.set(Array(newValue), forKey: insideKey) }
+  }
+
   /// Monitors the region `region` describes, replacing one with the same id.
   /// It starts outside, so a device already inside reports an entry, as on
   /// Android.
@@ -71,11 +78,13 @@ final class TokamakLocationRegions {
     let center = CLLocationCoordinate2D(latitude: latitude, longitude: longitude)
     let condition = CLMonitor.CircularGeographicCondition(center: center, radius: radius)
     regions[id] = region
+    inside.remove(id)
     await monitor.add(condition, identifier: id, assuming: .unsatisfied)
   }
 
   func remove(_ id: String) async {
     regions[id] = nil
+    inside.remove(id)
     events.report([], region: id)
     await monitor.value.remove(id)
   }
@@ -98,19 +107,20 @@ final class TokamakLocationRegions {
     return all
   }
 
+  /// Reports the event's problems, and its transition when it changes whether the device is
+  /// inside the region, as events can repeat the state.
   private func receive(_ event: CLMonitor.Event) {
     let id = event.identifier
     if #available(iOS 18, macOS 15, *) {
       events.report(Self.problems(event), region: id)
     }
-    guard let region = regions[id] else { return }
-    switch event.state {
-    case .satisfied where region["onEntry"] as? Bool != false:
-      events.transition(id, entered: true, at: event.date)
-    case .unsatisfied where region["onExit"] as? Bool != false:
-      events.transition(id, entered: false, at: event.date)
-    default:
-      break
+    guard let region = regions[id], event.state == .satisfied || event.state == .unsatisfied
+    else { return }
+    let entered = event.state == .satisfied
+    guard entered != inside.contains(id) else { return }
+    inside = entered ? inside.union([id]) : inside.subtracting([id])
+    if region[entered ? "onEntry" : "onExit"] as? Bool != false {
+      events.transition(id, entered: entered, at: event.date)
     }
   }
 
@@ -133,22 +143,33 @@ final class TokamakLocationRegions {
       ),
       (
         event.persistenceUnavailable, "NotReadableError",
-        "Regions are unavailable until the device is first unlocked"
+        "The system cannot store the app's regions"
       ),
     ]
     return flags.filter(\.0).map { TokamakPluginError(name: $0.1, message: $0.2) }
   }
 
-  /// Returns once protected data is available, which `CLMonitor` needs.
+  /// Returns once the device has been unlocked since it booted, from when `CLMonitor` can read the
+  /// file that keeps its conditions, even while the device is locked.
   @MainActor
-  private static func protectedData() async {
+  private static func firstUnlock() async {
     #if os(iOS)
-      guard !UIApplication.shared.isProtectedDataAvailable else { return }
-      let available = NotificationCenter.default.notifications(
+      let unlocked = NotificationCenter.default.notifications(
         named: UIApplication.protectedDataDidBecomeAvailableNotification)
-      for await _ in available {
+      guard !unlockedSinceBoot() else { return }
+      for await _ in unlocked {
         return
       }
     #endif
   }
+
+  #if os(iOS)
+    /// Whether the device has been unlocked since it booted, as only then can a file protected
+    /// until the first unlock be written.
+    private static func unlockedSinceBoot() -> Bool {
+      let probe = FileManager.default.temporaryDirectory.appending(path: "TokamakLocation.unlocked")
+      let protection = Data.WritingOptions.completeFileProtectionUntilFirstUserAuthentication
+      return (try? Data().write(to: probe, options: protection)) != nil
+    }
+  #endif
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin-location",
-  "version": "0.1.0-beta.103",
+  "version": "0.1.0-beta.104",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -12,7 +12,7 @@
     "./events": "./events/index.ts"
   },
   "peerDependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.103"
+    "@tokamakdev/plugin": "0.1.0-beta.104"
   },
   "files": [
     "android",

package/src/index.ts

@@ -29,9 +29,10 @@ class Location extends Plugin {
   }
 
   /**
-   * Applies what runs at every launch, replacing the previous configuration, which the plugin keeps
+   * Applies long-term location awareness, replacing the previous configuration, which the plugin keeps
    * and applies again at each start. Rejects with `TypeError`, changing nothing, when a value is
-   * invalid.
+   * invalid, and on Apple platforms with `NotSupportedError` where the device cannot monitor
+   * significant changes.
    */
   async setup(config: SetupConfig): Promise<void> {
     validateSetup(config, "config");
@@ -77,11 +78,12 @@ class Location extends Plugin {
   }
 
   /**
-   * Starts continuous updates, replacing any running, until `stopUpdates`. Their positions reach
-   * `onLocationUpdate`, including after the system ended the app. Rejects with `NotAllowedError`
-   * without in-use permission, and on iOS with `NeedsUIError` off screen. Android's
-   * `foregroundService` rejects with `NotSupportedError` without the `background-updates` build
-   * setting, and with `NeedsUIError` when Android does not allow the service to start off screen.
+   * Starts continuous tracking, replacing any running, until `stopUpdates`; `setup` gives long-term
+   * awareness instead. The updates' positions reach `onLocationUpdate`, including after the system
+   * ended the app. Rejects with `NotAllowedError` without in-use permission, and on iOS with
+   * `NeedsUIError` off screen. Android's `foregroundService` rejects with `NotSupportedError`
+   * without the `background-updates` build setting, and with `NeedsUIError` when Android does not
+   * allow the service to start off screen.
    */
   async startUpdates(options: UpdateOptions = {}): Promise<void> {
     validateUpdateOptions(options, "options");

package/src/types.ts

@@ -25,13 +25,18 @@ export type PositionCallback = (position: Position) => void;
 export type PositionErrorCallback = (error: DOMException) => void;
 
 /**
- * What runs at every launch: `setup` starts what it names and stops what it leaves out. Apple only;
- * other platforms ignore these keys. Each relaunches the app for its events with Always permission.
+ * Long-term location awareness, which runs across launches and restarts, uses little power and shows
+ * no indicator: `setup` starts what it names and stops what it leaves out. Off screen it needs
+ * background permission, with which the system launches the app for its events.
  */
 export interface SetupConfig {
-  /** Delivers significant changes of location to `onLocationUpdate`. */
+  /**
+   * Delivers moves of 500 metres or more, at most every 5 minutes, to `onLocationUpdate`, located
+   * from cellular and Wi-Fi rather than GPS: Apple's significant-change service, and on Android a
+   * low-power request with the same thresholds, which Android limits to a few an hour off screen.
+   */
   readonly significantChanges?: boolean;
-  /** Delivers arrivals at and departures from places to `onVisit`. */
+  /** Apple only: delivers arrivals at and departures from places to `onVisit`. */
   readonly visits?: boolean;
 }
 
@@ -75,7 +80,12 @@ export type Activity =
   | "airborne"
   | "maritime";
 
-/** `startUpdates` options. Each is platform-specific: Apple's relaunching updates take only an `activity`. */
+/**
+ * `startUpdates` options, for continuous tracking such as a run or navigation, which can show the
+ * system's indicator: the blue pill on iOS with in-use permission, and the notification of
+ * Android's `foregroundService`. Each option is platform-specific: Apple's relaunching updates
+ * take only an `activity`.
+ */
 export interface UpdateOptions {
   /** Apple only: `"default"` by default. */
   readonly activity?: Activity;