@bricks-soft/capacitor-location-tracking 0.0.0-stage → 8.0.1

package/android/src/main/java/com/brickssoft/locationtracking/service/NotificationFactory.kt

@@ -0,0 +1,338 @@
+package com.brickssoft.locationtracking.service
+
+import android.annotation.SuppressLint
+import android.app.Notification
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Color
+import android.graphics.drawable.AdaptiveIconDrawable
+import android.graphics.drawable.Drawable
+import android.os.Build
+import androidx.annotation.ColorInt
+import androidx.annotation.DrawableRes
+import androidx.annotation.RequiresApi
+import androidx.core.app.NotificationChannelCompat
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.res.ResourcesCompat
+import androidx.core.graphics.drawable.toBitmap
+import com.brickssoft.locationtracking.R
+import com.brickssoft.locationtracking.config.NotificationConfig
+import com.brickssoft.locationtracking.config.NotificationPriority
+import com.brickssoft.locationtracking.config.ResumeNotificationConfig
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+
+/**
+ * Builds the foreground-service notification and its channel from [NotificationConfig].
+ *
+ * - Channel id and name come from the config. The default name and text use the plugin string resources
+ *   (`lt_notification_channel_name`, `lt_notification_text`), so an app can translate them.
+ * - Channel importance follows `priority`: min → MIN, low → LOW, default → DEFAULT, high/max → HIGH.
+ *   **Android fixes a channel's importance when the channel is first created**; the app cannot change it
+ *   afterwards (only the user can). A later `priority` change therefore affects only the notification's own
+ *   priority (used below API 26). To apply a new importance, also change `channelId`.
+ * - The small icon is resolved from `drawable/name`, `mipmap/name` or `name`; an unknown or adaptive (launcher)
+ *   icon falls back to `lt_ic_notification`, because such a small icon shows as a white shape or breaks
+ *   `startForeground`.
+ * - The notification is ongoing, silent, alerts only once and is shown immediately
+ *   (`FOREGROUND_SERVICE_IMMEDIATE`). Tapping it opens the app; up to [Constants.MAX_NOTIFICATION_ACTIONS]
+ *   buttons broadcast to [NotificationActionReceiver].
+ */
+internal class NotificationFactory(context: Context) {
+    private val context: Context = context.applicationContext ?: context
+
+    /** Creates the channel, or updates its name if it exists. No-op below API 26. */
+    fun ensureChannel(config: NotificationConfig) {
+        val channel = NotificationChannelCompat.Builder(channelId(config), importanceFor(config.priority))
+            .setName(channelName(config))
+            .setShowBadge(false)
+            .setSound(null, null)
+            .setVibrationEnabled(false)
+            .build()
+        NotificationManagerCompat.from(context).createNotificationChannel(channel)
+    }
+
+    /** Ensures the channel, then builds the notification. */
+    fun build(config: NotificationConfig): Notification {
+        ensureChannel(config)
+        return compose(config)
+    }
+
+    /**
+     * The notification for the first `startForeground` of a service command. It is built without loading the config
+     * (no config store, no SharedPreferences, no JSON), so it is ready within milliseconds on a cold start:
+     * - [spec] is the notification fields that the sender copied into the start command (channel id and name,
+     *   priority, title, text, small icon, color; no action buttons, no large icon). Its channel is created with the
+     *   configured importance only if it does not exist yet (Android fixes a channel's importance at creation, so this
+     *   first creation must use the configured priority); an existing channel is left unchanged.
+     * - Without [spec] (a restart with a null intent), the default channel ([NotificationConfig.DEFAULT_CHANNEL_ID],
+     *   created only if it does not exist), the app label as title, `lt_notification_text` as text and the plugin icon:
+     *   the same content as [build] of `NotificationConfig()`.
+     *
+     * If [spec] cannot be built, the defaults are used. The service replaces this notification with the configured
+     * one (same id) once the config is loaded.
+     */
+    fun buildInitial(spec: NotificationConfig? = null): Initial {
+        if (spec != null) {
+            try {
+                ensureChannelExists(spec)
+                return Initial(spec, compose(spec))
+            } catch (e: Exception) {
+                Logger.e(TAG, "invalid notification fields in the start command; using the defaults", e)
+            }
+        }
+        val defaults = NotificationConfig()
+        ensureChannelExists(defaults)
+        return Initial(defaults, compose(defaults, R.drawable.lt_ic_notification))
+    }
+
+    /** A notification from [buildInitial] and the config whose content it shows. */
+    data class Initial(val config: NotificationConfig, val notification: Notification)
+
+    /** Creates the channel of [config] if it does not exist; an existing channel is not changed. No-op below API 26. */
+    private fun ensureChannelExists(config: NotificationConfig) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        if (NotificationManagerCompat.from(context).getNotificationChannelCompat(channelId(config)) == null) {
+            ensureChannel(config)
+        }
+    }
+
+    /** The notification for [config]; its channel must exist. [smallIcon] skips the icon lookup when given. */
+    private fun compose(config: NotificationConfig, @DrawableRes smallIcon: Int? = null): Notification {
+        val builder = NotificationCompat.Builder(context, channelId(config))
+            .setContentTitle(title(config))
+            .setContentText(text(config))
+            .setSmallIcon(smallIcon ?: resolveSmallIcon(config.smallIcon))
+            .setPriority(compatPriorityFor(config.priority))
+            .setCategory(NotificationCompat.CATEGORY_SERVICE)
+            .setOngoing(true)
+            .setSilent(true)
+            .setOnlyAlertOnce(true)
+            .setShowWhen(false)
+            .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
+        loadLargeIcon(config.largeIcon)?.let { builder.setLargeIcon(it) }
+        parseColor(config.color)?.let { builder.setColor(it) }
+        contentIntent()?.let { builder.setContentIntent(it) }
+        config.actions.take(Constants.MAX_NOTIFICATION_ACTIONS).forEachIndexed { index, action ->
+            builder.addAction(0, action.label, actionIntent(index, action.id))
+        }
+        return builder.build()
+    }
+
+    /**
+     * The resume notification (`notification.resume`): its own channel at default importance (the tracking channel is
+     * often `min`, which would hide it), the tracking notification's small icon and color, dismissed by a tap or after
+     * [timeoutMs]. The tap starts [LocationTrackingService] directly with [LocationTrackingService.ACTION_RESUME]:
+     * a service started from a notification gets while-in-use location access on Android 14+.
+     */
+    fun buildResume(config: NotificationConfig, timeoutMs: Long?): Notification {
+        val resume = config.resume
+        val channel = NotificationChannelCompat.Builder(Constants.RESUME_CHANNEL_ID, NotificationManagerCompat.IMPORTANCE_DEFAULT)
+            .setName(resumeChannelName(resume))
+            .setShowBadge(false)
+            .build()
+        NotificationManagerCompat.from(context).createNotificationChannel(channel)
+        val builder = NotificationCompat.Builder(context, Constants.RESUME_CHANNEL_ID)
+            .setContentTitle(resume.title?.takeIf { it.isNotBlank() } ?: appLabel())
+            .setContentText(resumeText(resume))
+            .setSmallIcon(resolveSmallIcon(config.smallIcon))
+            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+            .setCategory(NotificationCompat.CATEGORY_REMINDER)
+            .setAutoCancel(true)
+            .setContentIntent(resumeIntent(config))
+        parseColor(config.color)?.let { builder.setColor(it) }
+        timeoutMs?.let { builder.setTimeoutAfter(it) }
+        return builder.build()
+    }
+
+    /** [build], falling back to the default config if the configured notification cannot be built. */
+    fun buildSafely(config: NotificationConfig): Notification = try {
+        build(config)
+    } catch (e: Exception) {
+        Logger.e(TAG, "invalid notification config; using the defaults", e)
+        build(NotificationConfig())
+    }
+
+    /**
+     * `name` / `drawable/name` / `mipmap/name` → resource id, or [R.drawable.lt_ic_notification] if the name is
+     * unknown or names an adaptive launcher icon (it renders as a blank shape and crashes some Android 8.0 builds).
+     */
+    @DrawableRes
+    fun resolveSmallIcon(spec: String?): Int {
+        val id = resolveImage(spec)
+        return when {
+            id == 0 -> {
+                if (!spec.isNullOrBlank()) Logger.w(TAG, "small icon '$spec' not found; using the plugin icon")
+                R.drawable.lt_ic_notification
+            }
+            id != R.drawable.lt_ic_notification && isAdaptiveIcon(id) -> {
+                Logger.w(TAG, "small icon '$spec' is an adaptive launcher icon; using the plugin icon")
+                R.drawable.lt_ic_notification
+            }
+            else -> id
+        }
+    }
+
+    private fun isAdaptiveIcon(@DrawableRes id: Int): Boolean {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return false
+        return try {
+            Api26.isAdaptive(ResourcesCompat.getDrawable(context.resources, id, context.theme))
+        } catch (e: Exception) {
+            false
+        }
+    }
+
+    /** `name` / `drawable/name` / `mipmap/name` (an optional leading `@` is ignored) → resource id, or 0. */
+    @SuppressLint("DiscouragedApi") // names come from JS config, so they can only be resolved at runtime
+    fun resolveImage(spec: String?): Int {
+        val value = spec?.trim()?.removePrefix("@").orEmpty()
+        if (value.isEmpty()) return 0
+        val slash = value.indexOf('/')
+        val types = if (slash >= 0) listOf(value.substring(0, slash)) else IMAGE_TYPES
+        val name = if (slash >= 0) value.substring(slash + 1) else value
+        if (name.isEmpty() || types.any { it !in IMAGE_TYPES }) return 0
+        val resources = context.resources
+        for (type in types) {
+            val id = try {
+                resources.getIdentifier(name, type, context.packageName)
+            } catch (e: Exception) {
+                0
+            }
+            if (id != 0) return id
+        }
+        return 0
+    }
+
+    private fun loadLargeIcon(spec: String?): Bitmap? {
+        if (spec.isNullOrBlank()) return null
+        val id = resolveImage(spec)
+        if (id == 0) {
+            Logger.w(TAG, "large icon '$spec' not found")
+            return null
+        }
+        return try {
+            // decodeResource returns null for vector and adaptive drawables; render those instead.
+            BitmapFactory.decodeResource(context.resources, id)
+                ?: ResourcesCompat.getDrawable(context.resources, id, context.theme)?.toBitmap()
+        } catch (e: Exception) {
+            Logger.w(TAG, "could not load large icon '$spec'", e)
+            null
+        }
+    }
+
+    private fun title(config: NotificationConfig): CharSequence =
+        config.title?.takeIf { it.isNotBlank() } ?: appLabel()
+
+    private fun text(config: NotificationConfig): CharSequence =
+        if (config.text.isBlank() || config.text == NotificationConfig.DEFAULT_TEXT) {
+            context.getString(R.string.lt_notification_text)
+        } else {
+            config.text
+        }
+
+    private fun resumeText(resume: ResumeNotificationConfig): CharSequence =
+        if (resume.text.isBlank() || resume.text == ResumeNotificationConfig.DEFAULT_TEXT) {
+            context.getString(R.string.lt_resume_notification_text)
+        } else {
+            resume.text
+        }
+
+    private fun resumeChannelName(resume: ResumeNotificationConfig): CharSequence =
+        if (resume.channelName.isBlank() || resume.channelName == ResumeNotificationConfig.DEFAULT_CHANNEL_NAME) {
+            context.getString(R.string.lt_resume_channel_name)
+        } else {
+            resume.channelName
+        }
+
+    private fun channelId(config: NotificationConfig): String =
+        config.channelId.ifBlank { NotificationConfig.DEFAULT_CHANNEL_ID }
+
+    private fun channelName(config: NotificationConfig): CharSequence =
+        if (config.channelName.isBlank() || config.channelName == NotificationConfig.DEFAULT_CHANNEL_NAME) {
+            context.getString(R.string.lt_notification_channel_name)
+        } else {
+            config.channelName
+        }
+
+    private fun appLabel(): CharSequence = try {
+        context.applicationInfo.loadLabel(context.packageManager)
+    } catch (e: Exception) {
+        context.packageName
+    }
+
+    /** Opens the app like the launcher does (brings an existing task to the front). */
+    private fun contentIntent(): PendingIntent? {
+        val launch = context.packageManager.getLaunchIntentForPackage(context.packageName) ?: return null
+        // Without the package the intent matches the launcher's, so an existing task is resumed, not duplicated.
+        launch.setPackage(null)
+        launch.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED)
+        return PendingIntent.getActivity(context, Constants.RC_NOTIFICATION_CONTENT, launch, Constants.piImmutable())
+    }
+
+    /** Starts the service with [LocationTrackingService.ACTION_RESUME]; carries [config] for its first notification. */
+    private fun resumeIntent(config: NotificationConfig): PendingIntent {
+        val intent = Intent(context, LocationTrackingService::class.java).setAction(LocationTrackingService.ACTION_RESUME)
+        ServiceCommands.putNotification(intent, config)
+        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            PendingIntent.getForegroundService(context, Constants.RC_RESUME_NOTIFICATION, intent, Constants.piImmutable())
+        } else {
+            PendingIntent.getService(context, Constants.RC_RESUME_NOTIFICATION, intent, Constants.piImmutable())
+        }
+    }
+
+    private fun actionIntent(index: Int, id: String): PendingIntent {
+        val intent = Intent(context, NotificationActionReceiver::class.java)
+            .setAction(Constants.ACTION_NOTIFICATION_ACTION)
+            .putExtra(Constants.EXTRA_ACTION_ID, id)
+        return PendingIntent.getBroadcast(
+            context,
+            Constants.RC_NOTIFICATION_ACTION_BASE + index,
+            intent,
+            Constants.piImmutable(),
+        )
+    }
+
+    /** Keeps the API 26 class reference out of code that is verified on older devices. */
+    @RequiresApi(Build.VERSION_CODES.O)
+    internal object Api26 {
+        fun isAdaptive(drawable: Drawable?): Boolean = drawable is AdaptiveIconDrawable
+    }
+
+    companion object {
+        private const val TAG = "LT.Notification"
+        private val IMAGE_TYPES = listOf("drawable", "mipmap")
+
+        /** Channel importance for [priority]; applied only when the channel is created. */
+        fun importanceFor(priority: NotificationPriority): Int = when (priority) {
+            NotificationPriority.MIN -> NotificationManagerCompat.IMPORTANCE_MIN
+            NotificationPriority.LOW -> NotificationManagerCompat.IMPORTANCE_LOW
+            NotificationPriority.DEFAULT -> NotificationManagerCompat.IMPORTANCE_DEFAULT
+            NotificationPriority.HIGH, NotificationPriority.MAX -> NotificationManagerCompat.IMPORTANCE_HIGH
+        }
+
+        /** Notification priority for [priority] (effective below API 26). */
+        fun compatPriorityFor(priority: NotificationPriority): Int = when (priority) {
+            NotificationPriority.MIN -> NotificationCompat.PRIORITY_MIN
+            NotificationPriority.LOW -> NotificationCompat.PRIORITY_LOW
+            NotificationPriority.DEFAULT -> NotificationCompat.PRIORITY_DEFAULT
+            NotificationPriority.HIGH -> NotificationCompat.PRIORITY_HIGH
+            NotificationPriority.MAX -> NotificationCompat.PRIORITY_MAX
+        }
+
+        /** `#RRGGBB` / `#AARRGGBB` / color name → color int; null (logged) if blank or invalid. */
+        @ColorInt
+        fun parseColor(value: String?): Int? {
+            if (value.isNullOrBlank()) return null
+            return try {
+                Color.parseColor(value.trim())
+            } catch (e: IllegalArgumentException) {
+                Logger.w(TAG, "invalid notification color '$value'; ignored")
+                null
+            }
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/service/ServiceCommands.kt

@@ -0,0 +1,204 @@
+package com.brickssoft.locationtracking.service
+
+import android.content.Intent
+import android.os.Process
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.config.NotificationConfig
+import com.brickssoft.locationtracking.config.NotificationPriority
+import kotlin.random.Random
+
+/**
+ * The start/stop state machine that [DefaultServiceController] (the sender) and [LocationTrackingService] (the
+ * receiver) share inside one process. It exists because of one Android rule: after `startForegroundService()`, the
+ * service must call `startForeground()` before it stops. A `stopService()` that arrives before that makes the system
+ * crash the app with `ForegroundServiceDidNotStartInTimeException` ("Context.startForegroundService() did not then call
+ * Service.startForeground()").
+ *
+ * **Commands.** Every command the controller sends carries a sequence number ([EXTRA_SEQ], increasing within the
+ * process) and the process token ([EXTRA_ORIGIN] = [processToken]).
+ * - A **start** is sent with `startForegroundService()` and is marked [EXTRA_FOREGROUND_REQUIRED]. It also carries the
+ *   configured notification's channel, priority, title, text, small icon and color as plain string extras
+ *   ([putNotification]), so the service's first `startForeground()` uses the configured channel and content without
+ *   loading the config (see [ServiceCommand.notification]).
+ * - A **stop** is sent with `startService()` (action [LocationTrackingService.ACTION_STOP]). Android delivers commands
+ *   to `onStartCommand` in the order they were sent, so a stop is handled after every start sent before it, and each of
+ *   those starts has entered the foreground by then.
+ *
+ * **States.** A start is *pending* from the moment it was sent until `onStartCommand` has called `startForeground()`
+ * for it ([startHandled], called on success and on failure). The controller records:
+ * - `lastStart`: the sequence number of the last start that Android accepted;
+ * - `lastStop`: the sequence number of the last stop request (recorded before the stop command is sent, and also when
+ *   Android refuses the stop command);
+ * - `handledStart`: the sequence number of the last start that `onStartCommand` has handled.
+ *
+ * A start is pending while `lastStart > handledStart`. The latest request is a stop while `lastStop > lastStart`.
+ *
+ * **Transitions.**
+ * - `start()` while a start is pending and no stop followed it: nothing is sent, `start()` returns true (the pending
+ *   start will bring the service into the foreground). Otherwise a new start is sent.
+ * - `stop()`: records `lastStop`, then sends the stop command. `Context.stopService()` is used only when Android
+ *   refuses the stop command **and** no start is pending; while a start is pending the service stops itself after it
+ *   has entered the foreground (see below).
+ * - `onStartCommand(start s)`: calls `startForeground()` first, then [startHandled]. If [isStoppedAfter] (a stop was
+ *   requested after `s` and no start followed that stop), the service calls `stopSelf(startId)`. If the stop command is
+ *   still queued, Android ignores this `stopSelf` (a newer start id exists) and the stop command stops the service.
+ * - `onStartCommand(stop t)`: if [isStartedAfter] (a start was sent after `t`), the stop is ignored. Otherwise the service
+ *   calls `stopSelf(startId)`, which Android ignores when a newer command was already sent.
+ *
+ * Result: start → stop → start in one main-thread turn ends with the service running; start → stop ends with the
+ * service stopped after it entered the foreground once; no path calls `stopService()` while a start is pending.
+ *
+ * **Other processes.** A command whose [EXTRA_ORIGIN] differs from [processToken] was sent by an earlier process that
+ * died before `onStartCommand` ran (Android keeps undelivered commands and delivers them to the restarted service).
+ * Its sequence number means nothing here; the service decides from the persisted `enabled` flag instead.
+ *
+ * All state is guarded by one lock; no method blocks or performs I/O.
+ */
+internal object ServiceCommands {
+    /** Long: the command's sequence number in the sending process. */
+    const val EXTRA_SEQ = "com.brickssoft.locationtracking.service.EXTRA_SEQ"
+
+    /** String: the [processToken] of the process that sent the command. */
+    const val EXTRA_ORIGIN = "com.brickssoft.locationtracking.service.EXTRA_ORIGIN"
+
+    /** Boolean: the command was sent with `startForegroundService()`, so `onStartCommand` must call `startForeground()`. */
+    const val EXTRA_FOREGROUND_REQUIRED = "com.brickssoft.locationtracking.service.EXTRA_FOREGROUND_REQUIRED"
+
+    // The notification fields of a start command (see putNotification).
+    const val EXTRA_CHANNEL_ID = "com.brickssoft.locationtracking.service.EXTRA_CHANNEL_ID"
+    const val EXTRA_CHANNEL_NAME = "com.brickssoft.locationtracking.service.EXTRA_CHANNEL_NAME"
+    const val EXTRA_PRIORITY = "com.brickssoft.locationtracking.service.EXTRA_PRIORITY"
+    const val EXTRA_TITLE = "com.brickssoft.locationtracking.service.EXTRA_TITLE"
+    const val EXTRA_TEXT = "com.brickssoft.locationtracking.service.EXTRA_TEXT"
+    const val EXTRA_SMALL_ICON = "com.brickssoft.locationtracking.service.EXTRA_SMALL_ICON"
+    const val EXTRA_COLOR = "com.brickssoft.locationtracking.service.EXTRA_COLOR"
+
+    /** Identifies this process. It differs between processes (pid plus a random number drawn at process start). */
+    val processToken: String = "${Process.myPid()}-${Random.nextLong().toULong().toString(16)}"
+
+    private val lock = Any()
+    private var lastSeq = 0L
+    private var lastStart = 0L
+    private var lastStop = 0L
+    private var handledStart = 0L
+
+    /** The next sequence number. */
+    fun nextSeq(): Long = synchronized(lock) { ++lastSeq }
+
+    /** Android accepted start [seq]. */
+    fun startSent(seq: Long) = synchronized(lock) { if (seq > lastStart) lastStart = seq }
+
+    /** Stop [seq] was requested (whether or not Android accepts the stop command). */
+    fun stopRequested(seq: Long) = synchronized(lock) { if (seq > lastStop) lastStop = seq }
+
+    /** `onStartCommand` called `startForeground()` for start [seq] (successfully or not). */
+    fun startHandled(seq: Long) = synchronized(lock) { if (seq > handledStart) handledStart = seq }
+
+    /** True while a start from this process has not reached `startForeground()` yet. */
+    val isStartPending: Boolean get() = synchronized(lock) { lastStart > handledStart }
+
+    /** True while a start is pending and it is the latest request (no stop was requested after it). */
+    val isStartPendingAndLatest: Boolean
+        get() = synchronized(lock) { lastStart > handledStart && lastStart > lastStop }
+
+    /** True if a stop was requested after start [seq] and no start was sent after that stop. */
+    fun isStoppedAfter(seq: Long): Boolean = synchronized(lock) { lastStop > seq && lastStop > lastStart }
+
+    /** True if a start was sent after stop [seq]. */
+    fun isStartedAfter(seq: Long): Boolean = synchronized(lock) { lastStart > seq }
+
+    /** Adds the sequence number, origin and foreground marker to a command intent. */
+    fun stamp(intent: Intent, seq: Long, foregroundRequired: Boolean): Intent = intent
+        .putExtra(EXTRA_SEQ, seq)
+        .putExtra(EXTRA_ORIGIN, processToken)
+        .putExtra(EXTRA_FOREGROUND_REQUIRED, foregroundRequired)
+
+    /**
+     * Copies the fields of [config] that the first notification needs (channel id, channel name, priority, title, text,
+     * small icon, color) into [intent]. Action buttons and the large icon are not copied; the configured notification
+     * that replaces the first one has them.
+     */
+    fun putNotification(intent: Intent, config: NotificationConfig): Intent = intent
+        .putExtra(EXTRA_CHANNEL_ID, config.channelId)
+        .putExtra(EXTRA_CHANNEL_NAME, config.channelName)
+        .putExtra(EXTRA_PRIORITY, config.priority.wire)
+        .putExtra(EXTRA_TITLE, config.title)
+        .putExtra(EXTRA_TEXT, config.text)
+        .putExtra(EXTRA_SMALL_ICON, config.smallIcon)
+        .putExtra(EXTRA_COLOR, config.color)
+
+    /** The notification fields written by [putNotification], or null if [intent] has none. Never throws. */
+    fun notificationOf(intent: Intent): NotificationConfig? = try {
+        intent.getStringExtra(EXTRA_CHANNEL_ID)?.let { channelId ->
+            val defaults = NotificationConfig()
+            NotificationConfig(
+                title = intent.getStringExtra(EXTRA_TITLE),
+                text = intent.getStringExtra(EXTRA_TEXT) ?: defaults.text,
+                smallIcon = intent.getStringExtra(EXTRA_SMALL_ICON) ?: defaults.smallIcon,
+                color = intent.getStringExtra(EXTRA_COLOR),
+                priority = NotificationPriority.fromWire(intent.getStringExtra(EXTRA_PRIORITY)) ?: defaults.priority,
+                channelId = channelId,
+                channelName = intent.getStringExtra(EXTRA_CHANNEL_NAME) ?: defaults.channelName,
+            )
+        }
+    } catch (e: Exception) {
+        null
+    }
+
+    /** Test hook: forgets every command. */
+    @VisibleForTesting
+    fun reset() = synchronized(lock) {
+        lastSeq = 0L
+        lastStart = 0L
+        lastStop = 0L
+        handledStart = 0L
+    }
+}
+
+/**
+ * One `onStartCommand` intent, parsed without touching any component.
+ *
+ * @property kind what the command asks for.
+ * @property seq the sender's sequence number, or 0 if the intent has none.
+ * @property fromThisProcess true if [ServiceCommands.processToken] sent it; false for a command of an earlier process.
+ * @property foregroundRequired true if the sender used `startForegroundService()`.
+ * @property notification the notification fields the sender copied from its config ([ServiceCommands.putNotification]),
+ *   or null (null intent, stop command, or an intent without them).
+ */
+internal data class ServiceCommand(
+    val kind: Kind,
+    val seq: Long,
+    val fromThisProcess: Boolean,
+    val foregroundRequired: Boolean,
+    val notification: NotificationConfig? = null,
+) {
+    enum class Kind {
+        /** Null intent: the system restarted the service after its process died (`START_STICKY`). */
+        RESTART,
+        START,
+        STOP,
+
+        /** The resume notification was tapped ([LocationTrackingService.ACTION_RESUME]). */
+        RESUME,
+    }
+
+    companion object {
+        fun parse(intent: Intent?): ServiceCommand {
+            if (intent == null) return ServiceCommand(Kind.RESTART, 0L, fromThisProcess = false, foregroundRequired = false)
+            val kind = when (intent.action) {
+                LocationTrackingService.ACTION_STOP -> Kind.STOP
+                LocationTrackingService.ACTION_RESUME -> Kind.RESUME
+                else -> Kind.START
+            }
+            val origin = intent.getStringExtra(ServiceCommands.EXTRA_ORIGIN)
+            return ServiceCommand(
+                kind = kind,
+                seq = intent.getLongExtra(ServiceCommands.EXTRA_SEQ, 0L),
+                fromThisProcess = origin == ServiceCommands.processToken,
+                // A start without the marker still came through startForegroundService(): the controller sends no other.
+                foregroundRequired = intent.getBooleanExtra(ServiceCommands.EXTRA_FOREGROUND_REQUIRED, kind != Kind.STOP),
+                notification = if (kind != Kind.STOP) ServiceCommands.notificationOf(intent) else null,
+            )
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/service/ServiceController.kt

@@ -0,0 +1,22 @@
+package com.brickssoft.locationtracking.service
+
+/** Starts and stops the location foreground service. */
+interface ServiceController {
+    val isRunning: Boolean
+
+    /** Returns false if the OS refused to start the service (logged). */
+    fun start(): Boolean
+
+    fun stop()
+
+    /** Rebuilds the notification from the current config. */
+    fun refreshNotification()
+
+    /**
+     * Posts the resume notification (`notification.resume`), dismissed at [deadline] (epoch ms) if not null. Only logs
+     * when notifications are not allowed (`POST_NOTIFICATIONS`).
+     */
+    fun showResumeNotification(deadline: Long?) = Unit
+
+    fun cancelResumeNotification() = Unit
+}

package/android/src/main/java/com/brickssoft/locationtracking/service/ServiceDeps.kt

@@ -0,0 +1,61 @@
+package com.brickssoft.locationtracking.service
+
+import android.content.Context
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.Clock
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.EventBus
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.engine.TrackingEngine
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * The collaborators that [LocationTrackingService], [BootReceiver] and [NotificationActionReceiver] take from
+ * [Components]. [engine] is lazy so that components the caller does not need are never constructed.
+ *
+ * Tests set [override] to inject fakes instead of the real components.
+ *
+ * [from] loads [Components] (SharedPreferences, logger, native listeners) on its first call in a process, so the service
+ * calls it only off the main thread and only after `startForeground`.
+ */
+internal class ServiceDeps(
+    val configStore: ConfigStore,
+    val events: EventBus,
+    val scope: CoroutineScope,
+    val engine: Lazy<TrackingEngine>,
+    val clock: Clock,
+) {
+    /** Launches [block] on the engine in [scope]; failures are logged, never thrown. */
+    fun launchEngine(tag: String, what: String, block: suspend TrackingEngine.() -> Unit): Job = scope.launch {
+        try {
+            engine.value.block()
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Logger.e(tag, "$what failed", e)
+        }
+    }
+
+    companion object {
+        /** Test hook: when set, [from] returns its result instead of reading [Components]. */
+        @VisibleForTesting
+        @Volatile
+        var override: ((Context) -> ServiceDeps)? = null
+
+        fun from(context: Context): ServiceDeps {
+            override?.let { return it(context) }
+            val components = Components.get(context)
+            return ServiceDeps(
+                configStore = components.configStore,
+                events = components.events,
+                scope = components.scope,
+                engine = lazy { components.engine },
+                clock = components.clock,
+            )
+        }
+    }
+}