feat(car): Android Car App Library integration (#5633)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.agent_memory/session_context.md

@@ -12,12 +12,45 @@
 - Fix (NodeClusterMarkers.kt ONLY): icons baked in-scope via `rememberComposeBitmapDescriptor(node){ PulsingNodeChip }` into a snapshot stateMap; custom `private class NodeClusterRenderer : DefaultClusterRenderer` assigns them in onBeforeClusterItemRendered/onClusterItemUpdated (bg thread, READ-only — never composes, so the crash class is gone). Native info windows (super sets title/snippet) + onClusterItemInfoWindowClick→navigateToNodeDetails; precision circles drawn from the renderer's own `unclusteredItems` MutableState (clusterItemDecoration can't fire — `ClusterRendererItemState` is lib-internal). Strictly better than the elegant-euler Canvas branch — keeps the REAL Compose chip.
 - `compileGoogleDebugKotlin` + `spotlessCheck` + `detekt` PASS. NOT committed, NOT device-verified. Next: device-test (clusters show chips + info-window popups + no FATAL), then commit/push.
 
-## 2026-05-28 — Stabilized DatabaseManager withDb retry host test
-- Hardened `DatabaseManagerWithDbRetryTest` to remove CI race conditions by running the manager on a `StandardTestDispatcher(testScheduler)` instead of real `Dispatchers.IO`.
-- Added a `withTimeout(10_000)` guard around the test body to fail fast on coordination stalls instead of hanging/flapping.
-- Kept the deterministic retry trigger (`error("Connection pool is closed")`) and retained assertions that first attempt uses old DB and retry uses current DB.
-- Made teardown resilient with `if (::manager.isInitialized) manager.close()` so setup/early failures do not cascade into teardown crashes.
-- Verified with `:core:database:jvmTest --tests "org.meshtastic.core.database.DatabaseManagerWithDbRetryTest*"` and repeated it 5 consecutive runs without failures; `:core:database:detekt` also passed.
+## 2026-05-28 — Added comprehensive CarScreenDataBuilder unit coverage
+- Created `feature/car/src/test/kotlin/org/meshtastic/feature/car/util/CarScreenDataBuilderTest.kt` with 533 lines covering signal quality thresholds/boundaries, node UI mapping, node and conversation sorting, local stats fallbacks, uptime formatting, recent message limiting, contact key generation, and constants.
+- Restored the `MessageSnapshot` data class in `CarStateCoordinator.kt` and re-added `recentMessages()` plus `MAX_CONVERSATION_MESSAGES` in `CarScreenDataBuilder.kt` so the current source matched the requested pure-helper API surface for testing.
+- Verified with `./gradlew :feature:car:spotlessCheck :feature:car:detekt :feature:car:testFdroidDebugUnitTest --quiet` and the requested quiet test command (`./gradlew :feature:car:testFdroidDebugUnitTest --quiet 2>&1 | tail -20`), both successful.
+
+## 2026-05-28 — Lowered car min API to 7 and removed dead conversation code
+- Changed `feature/car` manifest `androidx.car.app.minCarApiLevel` metadata from 8 to 7.
+- Guarded `HomeScreen.showEmergencyAlert()` behind `carContext.carAppApiLevel >= 8` and logged unsupported API 7 hosts with Kermit.
+- Removed unused `ConversationScreen`, `CarTtsEngine`, message snapshot/cache/read-aloud plumbing, and now-unused car reply/read-aloud strings.
+- Simplified `CarStateCoordinator` and `CarScreenDataBuilder` to match the inline `ConversationItem` flow.
+- Verified with `./gradlew :feature:car:spotlessApply :feature:car:spotlessCheck :feature:car:detekt :feature:car:compileFdroidDebugKotlin --quiet 2>&1 | tail -30`.
+
+## 2026-05-28 — Migrated car home messages tab to ConversationItem
+- Reworked `feature/car` `HomeScreen` messaging tab to build CAL `ConversationItem` entries instead of browsable `Row`s, including `Person`/`CarMessage` helpers and native reply/mark-read callbacks.
+- Removed `HomeScreen` conversation navigation so the car host owns messaging affordances; `ConversationScreen` remains on disk for later cleanup phases.
+- Added `CarStateCoordinator.markAsRead()` using `packetRepository.clearUnreadCount(...)` with Kermit error logging via `runCatching`.
+- Verified with `./gradlew :feature:car:spotlessApply :feature:car:spotlessCheck :feature:car:detekt :feature:car:compileFdroidDebugKotlin` and the requested quiet compile command (`:feature:car:compileFdroidDebugKotlin --quiet 2>&1 | tail -20`), both successful.
+
+## 2026-05-28 — Implemented car conversation shortcuts and avatars
+- Added `feature/car/.../util/PersonIconFactory.kt` to render circular initial avatars using node-derived foreground/background colors for `Person` and shortcut icons.
+- Added `feature/car/.../service/ConversationShortcutManager.kt` to publish long-lived dynamic conversation shortcuts for favorite nodes and active channels, plus on-demand shortcut creation for notifications.
+- Wired `MeshtasticCarSession` to start/stop shortcut observation on a dedicated session coroutine scope.
+- Updated `CarNotificationManager` to ensure conversation shortcuts exist before posting and to attach both `shortcutId` and `LocusIdCompat` to messaging notifications.
+- Verified green with `./gradlew :feature:car:spotlessCheck :feature:car:detekt --quiet` and `./gradlew :feature:car:compileFdroidDebugKotlin --quiet 2>&1 | tail -20` after workspace bootstrap.
+
+## 2026-05-28 — Implemented car local stats tab and extracted screen data builder
+- Added `CarLocalStats` to `feature/car` UI models and exposed `localStatsState` from `CarStateCoordinator`.
+- Wired a new HomeScreen `Status` tab with battery, channel utilization, air utilization, node counts, uptime, and packet TX/RX rows.
+- Created `feature/car/.../util/CarScreenDataBuilder.kt` to centralize pure UI-model mapping helpers for nodes, conversations, local stats, uptime formatting, contact key building, and recent message selection.
+- Added the new `ic_car_status.xml` drawable plus status strings in `feature/car/src/main/res/values/strings.xml`.
+- Cleaned up `CarReplyReceiver` detekt violations that blocked module validation.
+- Ran `python3 scripts/sort-strings.py` and verified green with `./gradlew :feature:car:spotlessApply :feature:car:spotlessCheck :feature:car:detekt :feature:car:compileFdroidDebugKotlin :feature:car:testFdroidDebugUnitTest`.
+
+## 2026-05-28 — Implemented car module Phase 1 messaging wiring fixes
+- Replaced `CommandSender` usage in `feature/car` `CarStateCoordinator` with injected `SendMessageUseCase`, keeping the public `sendMessage()` API synchronous for UI callbacks while launching the use case on the coordinator scope after message-length validation.
+- Updated `CarNotificationManager` reply and mark-read notification actions with semantic action metadata and `setShowsUserInterface(false)` for automotive-friendly inline handling.
+- Reworked `CarReplyReceiver` into a `KoinComponent` that injects `SendMessageUseCase` and `PacketRepository`, then sends replies / clears unread counts asynchronously with Kermit error logging.
+- Added `android:permission="androidx.car.app.CarAppService"` to the `MeshtasticCarAppService` manifest declaration.
+- Verified with `./gradlew :feature:car:compileFdroidDebugKotlin --quiet` after required workspace bootstrap.
 
 ## 2026-05-21 — Upgraded Chirpy to a fully-personalized Live Diagnostic Node & Mesh Assistant
 - Integrated `NodeRepository` into `GeminiNanoDocAssistant.kt` and the Google AI Koin dependency injection module (`GoogleAiModule.kt`).

.github/copilot-instructions.md

@@ -41,5 +41,6 @@ These are specific to the Copilot CLI environment and are not covered in AGENTS.
 
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
-shell commands, and other important information, read the current plan
+shell commands, and other important information, read the current plan at
+specs/20260521-153452-car-app-library-integration/plan.md
 <!-- SPECKIT END -->

.specify/feature.json

@@ -1 +1,3 @@
-{"feature_directory":"specs/20260520-153412-nav-tab-labels"}
+{
+  "feature_directory": "specs/20260521-153452-car-app-library-integration"
+}

androidApp/build.gradle.kts

@@ -267,6 +267,7 @@ dependencies {
     debugImplementation(libs.androidx.compose.ui.test.manifest)
     debugImplementation(libs.androidx.glance.preview)
 
+    googleImplementation(projects.feature.car)
     googleImplementation(libs.location.services)
     googleImplementation(libs.play.services.maps)
     googleImplementation(libs.maps.compose)

androidApp/src/google/kotlin/org/meshtastic/app/di/FlavorModule.kt

@@ -14,13 +14,22 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
+@file:Suppress("ktlint:standard:max-line-length")
+
 package org.meshtastic.app.di
 
 import org.koin.core.annotation.Module
 import org.meshtastic.app.map.prefs.di.GoogleMapsKoinModule
+import org.meshtastic.feature.car.di.FeatureCarModule
 
 @Module(
     includes =
-    [GoogleNetworkModule::class, GoogleMapsKoinModule::class, GoogleAiModule::class, AppFunctionsModule::class],
+    [
+        GoogleNetworkModule::class,
+        GoogleMapsKoinModule::class,
+        GoogleAiModule::class,
+        AppFunctionsModule::class,
+        FeatureCarModule::class,
+    ],
 )
 class FlavorModule

core/model/src/commonMain/kotlin/org/meshtastic/core/model/Node.kt

@@ -72,15 +72,7 @@ data class Node(
         get() = lastHeard > onlineTimeThreshold()
 
     val colors: Pair<Int, Int>
-        get() { // returns foreground and background @ColorInt for each 'num'
-            val r = (num and 0xFF0000) shr 16
-            val g = (num and 0x00FF00) shr 8
-            val b = num and 0x0000FF
-            val brightness = ((r * 0.299) + (g * 0.587) + (b * 0.114)) / 255
-            val foreground = if (brightness > 0.5) 0xFF000000.toInt() else 0xFFFFFFFF.toInt()
-            val background = (0xFF shl 24) or (r shl 16) or (g shl 8) or b
-            return foreground to background
-        }
+        get() = nodeColorsFromNum(num)
 
     val isUnknownUser
         get() = user.hw_model == HardwareModel.UNSET

core/model/src/commonMain/kotlin/org/meshtastic/core/model/NodeColors.kt

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2026 Meshtastic LLC
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.meshtastic.core.model
+
+private const val RED_WEIGHT = 0.299
+private const val GREEN_WEIGHT = 0.587
+private const val BLUE_WEIGHT = 0.114
+private const val BRIGHTNESS_THRESHOLD = 0.5
+private const val MAX_CHANNEL = 255
+private const val RED_MASK = 0xFF0000
+private const val GREEN_MASK = 0x00FF00
+private const val BLUE_MASK = 0x0000FF
+private const val ALPHA_MASK = 0xFF
+private const val RED_SHIFT = 16
+private const val GREEN_SHIFT = 8
+private const val ALPHA_SHIFT = 24
+private const val BLACK = 0xFF000000.toInt()
+private const val WHITE = 0xFFFFFFFF.toInt()
+
+/** Derives a unique color pair from a node number. Returns (foreground, background) as @ColorInt. */
+fun nodeColorsFromNum(nodeNum: Int): Pair<Int, Int> {
+    val r = (nodeNum and RED_MASK) shr RED_SHIFT
+    val g = (nodeNum and GREEN_MASK) shr GREEN_SHIFT
+    val b = nodeNum and BLUE_MASK
+    val brightness = ((r * RED_WEIGHT) + (g * GREEN_WEIGHT) + (b * BLUE_WEIGHT)) / MAX_CHANNEL
+    val foreground = if (brightness > BRIGHTNESS_THRESHOLD) BLACK else WHITE
+    val background = (ALPHA_MASK shl ALPHA_SHIFT) or (r shl RED_SHIFT) or (g shl GREEN_SHIFT) or b
+    return foreground to background
+}

feature/car/build.gradle.kts

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2026 Meshtastic LLC
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+plugins {
+    alias(libs.plugins.meshtastic.android.library)
+    alias(libs.plugins.meshtastic.android.library.flavors)
+    id("meshtastic.koin")
+}
+
+android {
+    namespace = "org.meshtastic.feature.car"
+
+    buildFeatures { buildConfig = true }
+
+    defaultConfig {
+        minSdk = 23
+        consumerProguardFiles("proguard-rules.pro")
+    }
+}
+
+dependencies {
+    implementation(projects.core.common)
+    implementation(projects.core.data)
+    implementation(projects.core.database)
+    implementation(projects.core.domain)
+    implementation(projects.core.model)
+    implementation(projects.core.repository)
+
+    implementation(libs.androidx.car.app)
+    implementation(libs.androidx.car.app.projected)
+
+    implementation(libs.koin.android)
+    implementation(libs.koin.annotations)
+
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.crashlytics)
+    implementation(libs.kermit)
+
+    testImplementation(libs.androidx.car.app.testing)
+    testImplementation(libs.koin.test)
+    testImplementation(kotlin("test-junit"))
+    testRuntimeOnly(libs.junit.vintage.engine)
+}

feature/car/proguard-rules.pro

@@ -0,0 +1,9 @@
+# Car App Library ProGuard/R8 rules
+
+# CarAppService must not be obfuscated (resolved by android:exported="true" in manifest,
+# but keep rule ensures R8 doesn't remove it during aggressive shrinking)
+-keep class org.meshtastic.feature.car.service.MeshtasticCarAppService { *; }
+
+# Keep Koin-annotated classes for runtime DI resolution
+-keep @org.koin.core.annotation.Single class * { *; }
+-keep @org.koin.core.annotation.Factory class * { *; }

feature/car/src/main/AndroidManifest.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application>
+        <service
+            android:name="org.meshtastic.feature.car.service.MeshtasticCarAppService"
+            android:exported="true"
+            android:permission="androidx.car.app.CarAppService">
+            <intent-filter>
+                <action android:name="androidx.car.app.CarAppService" />
+                <category android:name="androidx.car.app.category.MESSAGING" />
+            </intent-filter>
+        </service>
+
+        <receiver
+            android:name="org.meshtastic.feature.car.service.CarReplyReceiver"
+            android:exported="false" />
+
+        <meta-data
+            android:name="androidx.car.app.minCarApiLevel"
+            android:value="7" />
+    </application>
+</manifest>