@tokamakdev/plugin-location 0.1.0-beta.137 → 0.1.0-beta.139

package/README.md

@@ -23,7 +23,7 @@ for await (const next of decodeValues<Position>(location.watchPosition())) {
   break; // Cancels the watch.
 }
 
-await location.requestPermission({ background: true });
+await location.requestPermission({ backgroundAlways: true });
 await location.addRegion({ id: "home", latitude: 51.5, longitude: -0.12, radius: 150 });
 ```
 
@@ -56,7 +56,7 @@ Wi-Fi and cell signals.
 decodes them. Cancelling the stream ends the native watch; errors terminate it.
 
 Both ask for in-use permission when the user has not answered. Off screen
-without background permission, the platforms stop locating the app, so
+without permission at all times, the platforms stop locating the app, so
 `getCurrentPosition` rejects with `NotAllowedError` there. iOS still locates
 the app for a few seconds after it leaves the screen. With approximate
 permission, Android gives an app a new position at most every 10 minutes, so
@@ -66,23 +66,24 @@ permission, Android gives an app a new position at most every 10 minutes, so
 
 `permission()` reports the app's permission without asking:
 
-- `inUse` and `background`, each `"granted"`, `"denied"` or `"prompt"`.
-  `background` is `"denied"` unless the `background` build setting declares
-  it. macOS has no separate background permission, so `background` equals
-  `inUse` there.
+- `inUse` and `backgroundAlways`, each `"granted"`, `"denied"` or `"prompt"`.
+  `backgroundAlways` is location at all times: Apple's Always, Android's
+  "Allow all the time". It is `"denied"` unless the `background-always` build
+  setting declares it. macOS has no separate permission at all times, so
+  `backgroundAlways` equals `inUse` there.
 - `precision`: `"precise"` or `"approximate"`, what the app gets or would get
   once allowed.
 
 `requestPermission(options)` asks for in-use permission where the user has not
 answered, and for what `options` names, then resolves with the permission:
 
-- `background: true` asks for background permission.
+- `backgroundAlways: true` asks for permission at all times.
   - **iOS** shows the Always prompt once, from When In Use. Asked before the
     user has answered, it gives provisional Always, which iOS confirms with
-    the user later. Without the `background` build setting it rejects with
+    the user later. Without the `background-always` build setting it rejects with
     `NotSupportedError`.
   - **Android** asks for in-use permission first, as Android grants
-    background permission only after it. From Android 11 the request opens
+    permission at all times only after it. From Android 11 the request opens
     the app's page in Settings, where the user picks "Allow all the time".
 - `precision: "precise"` asks for precise location where the user allowed
   approximate. Apple platforms grant it temporarily, while the app is in use,
@@ -103,7 +104,7 @@ Vite plugin's options, as `--location-<key>`, or as `TOKAMAK_LOCATION_<KEY>`:
 // vite.config.js
 tokamak({
   location: {
-    background: true,
+    "background-always": true,
     "background-updates": true,
     "accuracy-purposes": { Directions: "Shows directions from where you are" },
   },
@@ -112,11 +113,11 @@ tokamak({
 
 | Setting | Kind | Declares |
 |---|---|---|
-| `background` | boolean | Background permission: iOS's Always reason, Android's `ACCESS_BACKGROUND_LOCATION`. |
+| `background-always` | boolean | Location at all times: iOS's Always reason and the code that asks for Always, Android's `ACCESS_BACKGROUND_LOCATION`. |
 | `background-updates` | boolean | Updates off screen: iOS's `location` background mode, Android's location foreground service and its permissions. |
 | `precision` | `precise` or `approximate` | `approximate` declares approximate location only: iOS's `NSLocationDefaultAccuracyReduced`, and Android without `ACCESS_FINE_LOCATION`. macOS has no such declaration. |
 | `when-in-use-description` | string | Apple: the in-use prompt's reason, and macOS's only reason. |
-| `always-description` | string | iOS: the Always prompt's reason. Needs `background`. |
+| `always-description` | string | iOS: the Always prompt's reason. Needs `background-always`. |
 | `accuracy-purposes` | map of string | Apple: the reasons for temporary precise location, by purpose key. |
 
 Without a description the plugin uses a generic English reason. Declare only
@@ -174,7 +175,7 @@ monitor significant changes.
 - `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
+With permission at all times, iOS relaunches the app for both, and Android starts
 the app's process for significant changes. [Regions](#regions) wake the app
 the same way.
 
@@ -212,18 +213,18 @@ app's process for each update.
 - `accuracy` is `"high"` (default), `"balanced"` or `"low"`; `distance` the
   metres between updates, 0 by default; `interval` the milliseconds between
   them, 10 seconds by default.
-- Off screen, updates need background permission and arrive a few times an
+- Off screen, updates need permission at all times and arrive a few times an
   hour, unless they run in a foreground service.
 - `foregroundService: { title, body, channel }` runs updates in a foreground
   service, with that notification in a channel of that name, at the requested
   rate off screen. It needs the `background-updates` build setting, and
-  rejects with `NotSupportedError` without it. Off screen it needs background
-  permission, and Android starts the service only within 10 seconds of an
+  rejects with `NotSupportedError` without it. Off screen it needs permission
+  at all times, and Android starts the service only within 10 seconds of an
   update; otherwise it rejects with `NeedsUIError`. A region transition does
   not allow the start.
 - The plugin requests updates again after a restart, an app update and a
   force stop, and starts the service again on screen, or after a restart or
-  update with background permission. Android restarts a service it ends for
+  update with permission at all times. Android restarts a service it ends for
   memory.
 
 ## Regions
@@ -237,7 +238,7 @@ entry. `getRegions()` resolves with the regions, each with its `state` on
 Apple platforms: `"inside"`, `"outside"` or `"unknown"`.
 
 Regions need precise location, and reject with `NotAllowedError` without it,
-and background permission off screen.
+and permission at all times off screen.
 
 - **Apple** uses `CLMonitor`, which monitors up to 20 regions; `addRegion`
   rejects with `QuotaExceededError` beyond them. iOS relaunches the app for a

package/android/Exports.generated.kt

@@ -137,14 +137,14 @@ class TokamakLocationPluginDispatch(host: TokamakHost) : TokamakDispatch<Tokamak
         private fun TokamakValue.asLocationPermission(): LocationPermission =
             LocationPermission(
                 inUse = this["inUse"].enum(Permission.entries),
-                background = this["background"].enum(Permission.entries),
+                backgroundAlways = this["backgroundAlways"].enum(Permission.entries),
                 precision = this["precision"].enum(Precision.entries),
             )
 
         private fun json(value: LocationPermission): JSONObject =
             JSONObject()
                 .put("inUse", jsonName(value.inUse.name))
-                .put("background", jsonName(value.background.name))
+                .put("backgroundAlways", jsonName(value.backgroundAlways.name))
                 .put("precision", jsonName(value.precision.name))
 
         private fun TokamakValue.asLocationUpdate(): LocationUpdate =
@@ -177,13 +177,13 @@ class TokamakLocationPluginDispatch(host: TokamakHost) : TokamakDispatch<Tokamak
 
         private fun TokamakValue.asPermissionRequest(): PermissionRequest =
             PermissionRequest(
-                background = this["background"].nullable { it.boolean() },
+                backgroundAlways = this["backgroundAlways"].nullable { it.boolean() },
                 precision = this["precision"].nullable { it.enum(Precision.entries) },
             )
 
         private fun json(value: PermissionRequest): JSONObject =
             JSONObject()
-                .putOpt("background", value.background)
+                .putOpt("backgroundAlways", value.backgroundAlways)
                 .putOpt("precision", value.precision?.let { jsonName(it.name) })
 
         private fun TokamakValue.asPosition(): Position =

package/android/Exports.kt

@@ -10,7 +10,7 @@ object LocationExports : TokamakExports<TokamakLocationPlugin> {
         e.call(TokamakLocationPlugin::recentPosition, doc = "The provider's last known position, when it is no older than `maximumAge`.")
         e.call(TokamakLocationPlugin::currentPosition, doc = "A new fix, or null when Android finds none. Cancelling the call stops locating.")
         e.stream(TokamakLocationPlugin::watchPosition, overflow = TokamakOverflow.DROP_OLDEST, doc = "Positions as the device moves.")
-        e.call(TokamakLocationPlugin::permission, doc = "The app's in-use and background permission, and the precision it gets.")
+        e.call(TokamakLocationPlugin::permission, doc = "The app's location permission, and the precision it gets.")
         e.call(TokamakLocationPlugin::requestPermission, doc = "Asks for the permission `request` names where the user has not answered.")
         e.call(TokamakLocationPlugin::servicesEnabled, doc = "Whether location services are on for the device.")
         e.call(TokamakLocationPlugin::openSettings, doc = "Opens the app's page in the system settings.")

package/android/LocationPlugin.kt

@@ -87,7 +87,7 @@ class TokamakLocationPlugin(
     /** Each position as the device moves, until the provider turns off. */
     fun watchPosition(): Flow<Position> = positions.watch().map(::Position).catch { throw locationError(it) }
 
-    /** The app's in-use and background permission, and the precision it gets, or would get once allowed. */
+    /** The app's location permission, and the precision it gets, or would get once allowed. */
     fun permission(): LocationPermission {
         val inUse = if (hasForegroundPermission()) Permission.Granted else state(COARSE)
         val background = if (BACKGROUND in declared) state(BACKGROUND) else Permission.Denied
@@ -100,9 +100,9 @@ class TokamakLocationPlugin(
      * Android grants background permission only to an app with foreground permission.
      */
     suspend fun requestPermission(request: PermissionRequest?): LocationPermission {
-        val background = request?.background == true
+        val background = request?.backgroundAlways == true
         if (background && BACKGROUND !in declared) {
-            throw TokamakPluginError.notSupported("Background location needs the location plugin's background build setting")
+            throw TokamakPluginError.notSupported("backgroundAlways needs the location plugin's background-always build setting")
         }
         val asked = if (request?.precision == Precision.Approximate) setOf(COARSE) else foreground
         val allowed = ask(asked).containsValue(true)

package/android/LocationTypes.kt

@@ -39,9 +39,9 @@ enum class Permission { Granted, Denied, Prompt }
 
 enum class Precision { Precise, Approximate }
 
-data class LocationPermission(val inUse: Permission, val background: Permission, val precision: Precision)
+data class LocationPermission(val inUse: Permission, val backgroundAlways: Permission, val precision: Precision)
 
-data class PermissionRequest(val background: Boolean?, val precision: Precision?)
+data class PermissionRequest(val backgroundAlways: Boolean?, val precision: Precision?)
 
 data class SetupConfig(val significantChanges: Boolean?)
 

package/apple/Exports.swift

@@ -8,7 +8,7 @@ extension TokamakLocationPlugin: TokamakExports {
     e.call(currentPosition, doc: "A new fix. Cancelling the call stops locating.")
     e.stream(watchPosition, overflow: .dropOldest, doc: "Positions as the device moves.")
     e.call(
-      permission, doc: "The app's in-use and background permission, and the precision it gets.")
+      permission, doc: "The app's location permission, and the precision it gets.")
     e.call(
       requestPermission,
       doc: "Asks for the permission `request` names where the user has not answered.")

package/apple/LocationPlugin.swift

@@ -39,7 +39,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   private let events: TokamakLocationEvents
   private let updates: TokamakLocationUpdates
   private let regions: TokamakLocationRegions
-  #if os(iOS)
+  #if os(iOS) && LOCATION_ALWAYS
     /// The `CLServiceSession` iOS 18 needs for updates and regions to reach an
     /// app that is not in use, held while the app has Always permission.
     private var alwaysSession: AnyObject?
@@ -107,7 +107,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     let status = authorization.authorizationStatus
     return LocationPermission(
       inUse: Self.state(status),
-      background: backgroundPermission(status),
+      backgroundAlways: alwaysPermission(status),
       precision: authorization.accuracyAuthorization == .reducedAccuracy ? .approximate : .precise
     )
   }
@@ -117,10 +117,10 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   /// location when `request` names a purpose.
   @MainActor
   func requestPermission(_ request: PermissionRequest?) async throws -> LocationPermission {
-    let always = request?.background == true
+    let always = request?.backgroundAlways == true
     if always && !Self.declaresAlways {
       throw TokamakPluginError.notSupported(
-        "Background location needs the location plugin's background build setting")
+        "backgroundAlways needs the location plugin's background-always build setting")
     }
     let purpose = try Self.purpose(request)
     let status = authorization.authorizationStatus
@@ -131,14 +131,21 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     return try await withCheckedThrowingContinuation { answer in
       prompts[UUID()] = Prompt(purpose: purpose, answer: answer)
       if always {
-        defaults.set(true, forKey: askedForAlwaysKey)
-        authorization.requestAlwaysAuthorization()
+        requestAlways()
       } else {
         authorization.requestWhenInUseAuthorization()
       }
     }
   }
 
+  /// Asks for Always permission, in a build that declares it.
+  private func requestAlways() {
+    #if LOCATION_ALWAYS
+      defaults.set(true, forKey: askedForAlwaysKey)
+      authorization.requestAlwaysAuthorization()
+    #endif
+  }
+
   /// Whether location services are on, which Core Location reports off the
   /// main thread.
   func servicesEnabled() async -> Bool {
@@ -268,7 +275,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     }
   }
 
-  private func backgroundPermission(_ status: CLAuthorizationStatus) -> Permission {
+  private func alwaysPermission(_ status: CLAuthorizationStatus) -> Permission {
     if status == .authorizedAlways { return .granted }
     let asks = status == .notDetermined ? Self.declaresAlways : canUpgradeToAlways(status)
     return asks ? .prompt : .denied
@@ -296,7 +303,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   }
 
   private func holdAlwaysSession() {
-    #if os(iOS)
+    #if os(iOS) && LOCATION_ALWAYS
       guard #available(iOS 18, *) else { return }
       let always = authorization.authorizationStatus == .authorizedAlways
       if always && alwaysSession == nil {
@@ -316,10 +323,13 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     }
   }
 
-  /// Whether the Info.plist declares Always permission, as the `background`
-  /// build setting does on iOS and every macOS build does.
-  private static let declaresAlways =
-    Bundle.main.object(forInfoDictionaryKey: "NSLocationAlwaysAndWhenInUseUsageDescription") != nil
+  #if LOCATION_ALWAYS
+    /// Whether the build declares Always permission, as the `background-always`
+    /// build setting does on iOS and every macOS build does.
+    private static let declaresAlways = true
+  #else
+    private static let declaresAlways = false
+  #endif
 
   private var askedForAlways: Bool {
     defaults.bool(forKey: askedForAlwaysKey)

package/apple/LocationTypes.swift

@@ -95,12 +95,12 @@ extension TokamakLocationPlugin {
 
   struct LocationPermission: Codable {
     let inUse: Permission
-    let background: Permission
+    let backgroundAlways: Permission
     let precision: Precision
   }
 
   struct PermissionRequest: Codable {
-    let background: Bool?
+    let backgroundAlways: Bool?
     let precision: Precision?
     /// The key in the app's `NSLocationTemporaryUsageDescriptionDictionary` of the reason to show.
     let purpose: String?

package/build/declarations.d.mts

@@ -1,6 +1,6 @@
 /** The location plugin's build settings, with their defaults applied. */
 export interface Settings {
-  background: boolean;
+  "background-always": boolean;
   "background-updates": boolean;
   precision: "precise" | "approximate";
   "when-in-use-description"?: string;
@@ -8,12 +8,16 @@ export interface Settings {
   "accuracy-purposes"?: Record<string, string>;
 }
 
-/** The file that declares what the settings ask for, the plugin section key naming it, and notices. */
+/**
+ * The file that declares what the settings ask for, the plugin section key naming it, the Swift
+ * compilation conditions of an Apple build, and notices.
+ */
 export interface Declarations {
   key: "plist" | "manifest";
   name: string;
   contents: string;
   notices: string[];
+  conditions?: string[];
 }
 
 export function declarations(platform: string, settings: Settings): Declarations | { problems: string[] };

package/build/declarations.mjs

@@ -6,11 +6,12 @@ const ALWAYS = "This app uses your location in the background for location featu
 
 /**
  * The file that declares what `settings` ask for on `platform`, the plugin section key that names
- * it, and notices for the build; or the problems with the settings.
+ * it, the Swift compilation conditions of an Apple build, and notices for the build; or the
+ * problems with the settings.
  */
 export function declarations(platform, settings) {
-  if (settings["always-description"] !== undefined && !settings.background) {
-    return { problems: ["always-description needs background, which declares the permission it describes"] };
+  if (settings["always-description"] !== undefined && !settings["background-always"]) {
+    return { problems: ["always-description needs background-always, which declares the permission it describes"] };
   }
   if (platform === "android") {
     return { key: "manifest", name: "AndroidManifest.xml", contents: androidManifest(settings), notices: [] };
@@ -19,7 +20,16 @@ export function declarations(platform, settings) {
     platform === "macos" && settings.precision === "approximate"
       ? ["macOS has no declaration of approximate location, so precision approximate applies to iOS and Android only"]
       : [];
-  return { key: "plist", name: "Info.plist", contents: plist(appleKeys(platform, settings)), notices };
+  const keys = appleKeys(platform, settings);
+  // Only a build that gives the Always reason compiles the code that asks for Always.
+  const always = "NSLocationAlwaysAndWhenInUseUsageDescription" in keys;
+  return {
+    key: "plist",
+    name: "Info.plist",
+    contents: plist(keys),
+    notices,
+    ...(always ? { conditions: ["LOCATION_ALWAYS"] } : {}),
+  };
 }
 
 /** The Info.plist keys of `settings` on the Apple `platform`. */
@@ -37,7 +47,7 @@ function appleKeys(platform, settings) {
     };
   }
   const keys = { NSLocationWhenInUseUsageDescription: whenInUse };
-  if (settings.background) keys.NSLocationAlwaysAndWhenInUseUsageDescription = settings["always-description"] ?? ALWAYS;
+  if (settings["background-always"]) keys.NSLocationAlwaysAndWhenInUseUsageDescription = settings["always-description"] ?? ALWAYS;
   if (settings["background-updates"]) keys.UIBackgroundModes = ["location"];
   if (settings.precision === "approximate") keys.NSLocationDefaultAccuracyReduced = true;
   return { ...keys, ...temporary };
@@ -47,7 +57,7 @@ function appleKeys(platform, settings) {
 function androidManifest(settings) {
   const permissions = ["ACCESS_COARSE_LOCATION", "RECEIVE_BOOT_COMPLETED"];
   if (settings.precision !== "approximate") permissions.push("ACCESS_FINE_LOCATION");
-  if (settings.background) permissions.push("ACCESS_BACKGROUND_LOCATION");
+  if (settings["background-always"]) permissions.push("ACCESS_BACKGROUND_LOCATION");
   if (settings["background-updates"]) permissions.push("FOREGROUND_SERVICE", "FOREGROUND_SERVICE_LOCATION");
   const service = settings["background-updates"]
     ? [

package/build/index.mjs

@@ -1,12 +1,12 @@
 // The location plugin's build script: tok runs it for each platform with the plugin's resolved
 // build settings on stdin. It writes the plugin's Info.plist or Android manifest into `output`
-// and prints the key that names it.
+// and prints the keys that name it and an Apple build's compilation conditions.
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { declarations } from "./declarations.mjs";
 
 const { platform, settings, output } = JSON.parse(readFileSync(0, "utf8"));
-const { key, name, contents, notices, problems } = declarations(platform, settings);
+const { key, name, contents, notices, conditions, problems } = declarations(platform, settings);
 if (problems) {
   console.error(problems.join("\n"));
   process.exit(1);
@@ -14,4 +14,4 @@ if (problems) {
 for (const notice of notices) console.error(notice);
 const path = join(output, name);
 writeFileSync(path, contents);
-console.log(JSON.stringify({ [key]: path }));
+console.log(JSON.stringify({ [key]: path, "compilation-conditions": conditions }));

package/package.json

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

package/src/android.generated.ts

@@ -21,7 +21,7 @@ export interface LocationErrorEvent {
 
 export interface LocationPermission {
   readonly inUse: Permission;
-  readonly background: Permission;
+  readonly backgroundAlways: Permission;
   readonly precision: Precision;
 }
 
@@ -41,7 +41,7 @@ export interface MonitoredRegion {
 export type Permission = "granted" | "denied" | "prompt";
 
 export interface PermissionRequest {
-  readonly background?: boolean;
+  readonly backgroundAlways?: boolean;
   readonly precision?: Precision;
 }
 
@@ -96,7 +96,7 @@ export interface Android {
   currentPosition(): Promise<Position | null>;
   /** Positions as the device moves. */
   watchPosition(): JsonStream<Position>;
-  /** The app's in-use and background permission, and the precision it gets. */
+  /** The app's location permission, and the precision it gets. */
   permission(): Promise<LocationPermission>;
   /** Asks for the permission `request` names where the user has not answered. */
   requestPermission(request?: PermissionRequest | null): Promise<LocationPermission>;

package/src/apple.generated.ts

@@ -22,7 +22,7 @@ export interface LocationErrorEvent {
 
 export interface LocationPermission {
   readonly inUse: Permission;
-  readonly background: Permission;
+  readonly backgroundAlways: Permission;
   readonly precision: Precision;
 }
 
@@ -44,7 +44,7 @@ export interface MonitoredRegion {
 export type Permission = "granted" | "denied" | "prompt";
 
 export interface PermissionRequest {
-  readonly background?: boolean;
+  readonly backgroundAlways?: boolean;
   readonly precision?: Precision;
   readonly purpose?: string;
 }
@@ -102,7 +102,7 @@ export interface Apple {
   currentPosition(): Promise<Position>;
   /** Positions as the device moves. */
   watchPosition(): JsonStream<Position>;
-  /** The app's in-use and background permission, and the precision it gets. */
+  /** The app's location permission, and the precision it gets. */
   permission(): Promise<LocationPermission>;
   /** Asks for the permission `request` names where the user has not answered. */
   requestPermission(request?: PermissionRequest | null): Promise<LocationPermission>;

package/src/index.ts

@@ -60,9 +60,9 @@ export function location(ctx: TokamakContext) {
       const position = await platformApi(ctx, { apple, android }, located.signal).currentPosition()
         .finally(() => { clearTimeout(timer); });
       if (position) return position;
-      // Android finds no position in the background without background permission.
+      // Android finds no position in the background without permission at all times.
       const background = await lifecycleStage(ctx) === "background";
-      throw background && (await native.permission()).background !== "granted" ? backgroundDenied() : unavailable("Location is unavailable");
+      throw background && (await native.permission()).backgroundAlways !== "granted" ? backgroundDenied() : unavailable("Location is unavailable");
     },
 
     /**
@@ -74,12 +74,12 @@ export function location(ctx: TokamakContext) {
       return native.watchPosition();
     },
 
-    /** The app's in-use and background permission, and the precision it gets. Never asks. */
+    /** The app's location permission, and the precision it gets. Never asks. */
     permission: (): Promise<LocationPermission> => native.permission(),
 
     /**
      * Asks for in-use permission, and for what `options` names, where the user has not answered.
-     * Android asks for background permission once in-use permission is granted. Rejects with
+     * Android asks for permission at all times once in-use permission is granted. Rejects with
      * `NeedsUIError` when a prompt would show off screen.
      */
     requestPermission: (options?: PermissionRequest): Promise<LocationPermission> => native.requestPermission(options),

package/src/types.ts

@@ -28,7 +28,7 @@ export type PositionErrorCallback = (error: DOMException) => void;
 /**
  * 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.
+ * permission at all times, with which the system launches the app for its events.
  */
 export interface SetupConfig {
   /**
@@ -50,16 +50,16 @@ export type Precision = "precise" | "approximate";
 export interface LocationPermission {
   /** Location while the app is in use. */
   readonly inUse: Permission;
-  /** Location while it is not: Apple's Always, Android's "Allow all the time". The same as `inUse` on macOS. */
-  readonly background: Permission;
+  /** Location at all times: Apple's Always, Android's "Allow all the time". The same as `inUse` on macOS. */
+  readonly backgroundAlways: Permission;
   /** The precision the app gets, or would get once allowed. */
   readonly precision: Precision;
 }
 
 /** What `requestPermission` asks for besides in-use permission. */
 export interface PermissionRequest {
-  /** Background permission, which needs the `background` build setting. */
-  readonly background?: boolean;
+  /** Location at all times, which needs the `background-always` build setting. */
+  readonly backgroundAlways?: boolean;
   /**
    * `"precise"` asks for precise location where the user allowed approximate: on Apple platforms
    * temporarily, for `purpose`. `"approximate"` asks Android for approximate location only.

package/tokamak-plugin.json

@@ -2,10 +2,10 @@
   "schemaVersion": 2,
   "id": "location",
   "settings": {
-    "background": {
+    "background-always": {
       "kind": "boolean",
       "default": false,
-      "description": "Declares background location permission: Apple's Always, Android's ACCESS_BACKGROUND_LOCATION"
+      "description": "Declares location permission at all times: Apple's Always, Android's ACCESS_BACKGROUND_LOCATION"
     },
     "background-updates": {
       "kind": "boolean",

package/web/index.ts

@@ -44,7 +44,7 @@ export async function permission(): Promise<LocationPermission> {
   const permissions = (globalThis as { navigator?: { permissions?: Permissions } }).navigator?.permissions;
   if (!permissions) throw new DOMException("The Permissions API is unavailable", "NotSupportedError");
   const { state } = await permissions.query({ name: "geolocation" });
-  return { inUse: state, background: "denied", precision: "precise" };
+  return { inUse: state, backgroundAlways: "denied", precision: "precise" };
 }
 
 /** Rejects as the web does for what only native apps have. */