@iternio/react-native-auto-play 0.3.11 → 0.3.12

package/README.md

@@ -613,7 +613,7 @@ This section lists the available listeners and lifecycle callbacks so you can wi
 | --- | --- | --- |
 | `HybridAutoPlay.addListener(event, cb)` | event: `'didConnect'` `'didDisconnect'` | Connection changes for the head unit. |
 | `HybridAutoPlay.addListenerRenderState(moduleName, cb)` | `cb(visibility: 'willAppear' \| 'didAppear' \| 'willDisappear' \| 'didDisappear')` | Use `AutoPlayModules.*` or a cluster UUID. |
-| `HybridAutoPlay.addListenerVoiceInput(cb)` | `cb(location?, query?)` | Android-only voice input. |
+| `HybridAutoPlay.addListenerVoiceInput(cb)` | `cb(location?, query?)` | Android-only. Fires when the OS triggers a voice input event (e.g. "Hey Google, navigate to…"). For in-app recording use `startVoiceInput` instead. |
 | `HybridAutoPlay.addSafeAreaInsetsListener(moduleName, cb)` | `cb(insets)` | Safe area inset changes for any module. |
 
 ```ts
@@ -760,10 +760,68 @@ new ListTemplate({
 }).push();
 ```
 
+### Voice Input
+
+The library provides a cross-platform in-app voice recording API built on top of the car microphone (when connected) or the device microphone (when no car is connected).
+
+#### Permission
+
+```ts
+// Check whether permission is already granted
+const granted = HybridAutoPlay.hasVoiceInputPermission();
+
+// Request permission if not yet granted
+const granted = await HybridAutoPlay.requestVoiceInputPermission();
+```
+
+#### Recording
+
+```ts
+// Start recording — resolves with a raw PCM ArrayBuffer (16 kHz, 16-bit, mono)
+// Recording stops automatically on silence or when maxDurationMs is reached
+const pcmBuffer = await HybridAutoPlay.startVoiceInput(
+  1500,       // silenceThresholdMs (default 1500)
+  10_000,     // maxDurationMs (default 10 000)
+  'Listening...' // text shown on the car screen while recording (iOS CarPlay)
+);
+
+// Stop recording early — resolves startVoiceInput with the audio captured so far
+HybridAutoPlay.stopVoiceInput();
+```
+
+On **Android**: uses `CarAudioRecord` when Android Auto is connected, otherwise falls back to standard `AudioRecord`.
+
+On **iOS**: presents `CPVoiceControlTemplate` on the car screen when CarPlay is connected, and captures audio via `AVAudioEngine`.
+
+#### OS-triggered voice input (Android only)
+
+`addListenerVoiceInput` fires when the OS itself initiates a voice action (e.g. "Hey Google, navigate to…"). It is a no-op on iOS — use `startVoiceInput` for in-app recording on both platforms.
+
+```ts
+const cleanup = HybridAutoPlay.addListenerVoiceInput((location, query) => {
+  console.log('Voice query:', query, 'near', location);
+});
+```
+
+#### useVoiceInput hook (Android only)
+
+A convenience hook that wires up `addListenerVoiceInput` and exposes the latest `location` and `query` values reactively.
+
+```tsx
+import { useVoiceInput } from '@iternio/react-native-auto-play';
+
+const MyScreen = () => {
+  const { location, query } = useVoiceInput();
+  return <Text>{query ?? 'Say something…'}</Text>;
+};
+```
+
+---
+
 ### Hooks
 
 -   `useMapTemplate()`: Get a reference to the parent `MapTemplate` instance.
--   `useVoiceInput()`: Access voice input functionality - Android Auto only.
+-   `useVoiceInput()`: Reactively exposes the latest OS-triggered voice input (`location`, `query`). Android only — for in-app recording use `startVoiceInput` / `stopVoiceInput` directly.
 -   `useSafeAreaInsets()`: Get safe area insets for any root component.
 -   `useFocusedEffect()`: A useEffect alternative that executes when the specified component is visible to the user - use any of the `AutoPlayModules` enum or a cluster uuid to sepcify the component the effect should listen for.
 -   `useAndroidAutoTelemetry()`: Access to car telemetry data on Android Auto and Android Automotive.

package/android/src/automotive/AndroidManifest.xml

@@ -19,6 +19,7 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
 
     <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
 
 
     <!-- Android Automotive specific permissions -->

package/android/src/main/AndroidManifest.xml

@@ -12,6 +12,7 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
 
     <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
 
     <!-- Android Auto specific permissions -->
     <uses-permission android:name="com.google.android.gms.permission.CAR_FUEL" />

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/HybridAutoPlay.kt

@@ -1,12 +1,22 @@
 package com.margelo.nitro.swe.iternio.reactnativeautoplay
 
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.content.ContextCompat
 import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.modules.core.PermissionAwareActivity
+import com.facebook.react.modules.core.PermissionListener
+import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.ArrayBuffer
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.template.AndroidAutoTemplate
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.template.MessageTemplate
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.utils.ThreadUtil
+import kotlinx.coroutines.suspendCancellableCoroutine
+import java.nio.ByteBuffer
 import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.CopyOnWriteArrayList
+import kotlin.coroutines.resume
 
 class HybridAutoPlay : HybridAutoPlaySpec() {
     init {
@@ -241,6 +251,84 @@ class HybridAutoPlay : HybridAutoPlaySpec() {
         }
     }
 
+    override fun hasVoiceInputPermission(): Boolean {
+        val context = NitroModules.applicationContext ?: return false
+        return ContextCompat.checkSelfPermission(
+            context, android.Manifest.permission.RECORD_AUDIO
+        ) == PackageManager.PERMISSION_GRANTED
+    }
+
+    override fun requestVoiceInputPermission(): Promise<Boolean> {
+        return Promise.async {
+            if (hasVoiceInputPermission()) {
+                return@async true
+            }
+
+            val carContext = AndroidAutoSession.getRootContext()
+
+            if (carContext != null) {
+                suspendCancellableCoroutine {
+                    carContext.requestPermissions(listOf(android.Manifest.permission.RECORD_AUDIO)) { approved, _ ->
+                        it.resume(approved.contains(android.Manifest.permission.RECORD_AUDIO))
+                    }
+                }
+            } else {
+                val context = NitroModules.applicationContext ?: return@async false
+                val activity =
+                    context.currentActivity as? PermissionAwareActivity ?: return@async false
+                val code = (Math.random() * 10000).toInt()
+
+                suspendCancellableCoroutine {
+                    activity.requestPermissions(
+                        arrayOf(android.Manifest.permission.RECORD_AUDIO),
+                        code,
+                        PermissionListener { requestCode, _, grantResults ->
+                            if (requestCode != code) {
+                                return@PermissionListener false
+                            }
+
+                            val granted =
+                                grantResults.isNotEmpty() && grantResults.first() == PackageManager.PERMISSION_GRANTED
+
+                            it.resume(granted)
+
+                            return@PermissionListener true
+                        })
+                }
+            }
+        }
+    }
+
+    override fun startVoiceInput(
+        silenceThresholdMs: Double?, maxDurationMs: Double?, listeningText: String?
+    ): Promise<ArrayBuffer> {
+        return Promise.async {
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+                throw UnsupportedOperationException("startVoiceInput requires at least API level ${Build.VERSION_CODES.O}")
+            }
+
+            val manager = VoiceInputManager(AndroidAutoSession.getRootContext())
+            voiceInputManager = manager
+
+            try {
+                val pcmBytes = manager.start(
+                    silenceThresholdMs = silenceThresholdMs?.toLong() ?: 1_500L,
+                    maxDurationMs = maxDurationMs?.toLong() ?: 10_000L,
+                )
+                val directBuffer =
+                    ByteBuffer.allocateDirect(pcmBytes.size).put(pcmBytes).rewind() as ByteBuffer
+                ArrayBuffer.wrap(directBuffer)
+            } finally {
+                voiceInputManager = null
+                manager.dispose()
+            }
+        }
+    }
+
+    override fun stopVoiceInput() {
+        voiceInputManager?.stop()
+    }
+
     companion object {
         const val TAG = "HybridAutoPlay"
 
@@ -251,6 +339,9 @@ class HybridAutoPlay : HybridAutoPlaySpec() {
 
         private val voiceInputListeners = CopyOnWriteArrayList<(Location?, String?) -> Unit>()
 
+        @Volatile
+        private var voiceInputManager: VoiceInputManager? = null
+
         private val safeAreaInsetsListeners =
             ConcurrentHashMap<String, CopyOnWriteArrayList<(SafeAreaInsets) -> Unit>>()
 

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/VoiceInputManager.kt

@@ -0,0 +1,214 @@
+package com.margelo.nitro.swe.iternio.reactnativeautoplay
+
+import android.content.pm.PackageManager
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioFormat
+import android.media.AudioManager
+import android.media.AudioRecord
+import android.media.MediaRecorder
+import android.os.Build
+import androidx.annotation.RequiresApi
+import androidx.car.app.CarContext
+import androidx.car.app.media.CarAudioRecord
+import androidx.core.content.ContextCompat
+import com.margelo.nitro.NitroModules
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+import java.io.ByteArrayOutputStream
+import kotlin.coroutines.Continuation
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+import kotlin.math.abs
+
+/**
+ * Captures 16-bit PCM audio (16 kHz, mono).
+ * When [carContext] is provided uses CarAudioRecord (Android Auto/Automotive).
+ * When [carContext] is null falls back to standard AudioRecord (phone-only).
+ */
+class VoiceInputManager(
+    private val carContext: CarContext?,
+) {
+    private var carAudioRecord: CarAudioRecord? = null
+    private var audioRecord: AudioRecord? = null
+    private var audioFocusRequest: AudioFocusRequest? = null
+    private var recordingJob: Job? = null
+    private var continuation: Continuation<ByteArray>? = null
+    private val scope = CoroutineScope(Dispatchers.IO)
+
+    @Volatile
+    private var isRecording = false
+
+    /**
+     * Acquires audio focus, starts recording, and suspends until stopped.
+     * Stops automatically after [silenceThresholdMs] of silence or [maxDurationMs] total.
+     * Returns the complete raw PCM buffer (Int16 LE, 16 kHz, mono).
+     */
+    @RequiresApi(Build.VERSION_CODES.O)
+    suspend fun start(
+        silenceThresholdMs: Long = 1_500,
+        maxDurationMs: Long = 10_000,
+    ): ByteArray = suspendCancellableCoroutine { cont ->
+        val appContext = NitroModules.applicationContext
+        if (appContext == null || ContextCompat.checkSelfPermission(
+                appContext,
+                android.Manifest.permission.RECORD_AUDIO,
+            ) != PackageManager.PERMISSION_GRANTED
+        ) {
+            cont.resumeWithException(SecurityException("RECORD_AUDIO permission not granted"))
+            return@suspendCancellableCoroutine
+        }
+
+        continuation = cont
+
+        val audioManager = appContext.getSystemService(AudioManager::class.java)
+
+        val audioAttributes =
+            AudioAttributes.Builder().setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE).build()
+
+        val focusRequest =
+            AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
+                .setAudioAttributes(audioAttributes).setOnAudioFocusChangeListener { state ->
+                    if (state == AudioManager.AUDIOFOCUS_LOSS) {
+                        stop()
+                    }
+                }.build()
+
+        if (audioManager.requestAudioFocus(focusRequest) != AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
+            continuation = null
+            cont.resumeWithException(IllegalStateException("Audio focus request denied"))
+            return@suspendCancellableCoroutine
+        }
+
+        audioFocusRequest = focusRequest
+
+        val bufferSize: Int
+
+        if (carContext != null) {
+            val record = CarAudioRecord.create(carContext)
+            carAudioRecord = record
+            bufferSize = CarAudioRecord.AUDIO_CONTENT_BUFFER_SIZE
+            isRecording = true
+            record.startRecording()
+        } else {
+            val minBuffer = AudioRecord.getMinBufferSize(
+                SAMPLE_RATE,
+                AudioFormat.CHANNEL_IN_MONO,
+                AudioFormat.ENCODING_PCM_16BIT,
+            )
+            bufferSize = maxOf(minBuffer, PHONE_BUFFER_SIZE)
+            val record = AudioRecord(
+                MediaRecorder.AudioSource.MIC,
+                SAMPLE_RATE,
+                AudioFormat.CHANNEL_IN_MONO,
+                AudioFormat.ENCODING_PCM_16BIT,
+                bufferSize,
+            )
+            audioRecord = record
+            isRecording = true
+            record.startRecording()
+        }
+
+        val outputStream = ByteArrayOutputStream()
+
+        recordingJob = scope.launch {
+            val buffer = ByteArray(bufferSize)
+            val recordingStart = System.currentTimeMillis()
+            var silenceStart: Long? = null
+
+            try {
+                while (isRecording) {
+                    val read = carAudioRecord?.read(buffer, 0, bufferSize) ?: audioRecord?.read(
+                        buffer,
+                        0,
+                        bufferSize,
+                    ) ?: -1
+
+                    if (read < 0) {
+                        break
+                    }
+
+                    if (read > 0) {
+                        outputStream.write(buffer, 0, read)
+
+                        val now = System.currentTimeMillis()
+                        val elapsedMs = now - recordingStart
+
+                        if (elapsedMs >= maxDurationMs) {
+                            break
+                        }
+
+                        // Silence detection — skip during warm-up
+                        if (elapsedMs >= WARMUP_MS) {
+                            var peak = 0
+                            var i = 0
+                            while (i < read - 1) {
+                                val sample =
+                                    (buffer[i].toInt() and 0xFF) or (buffer[i + 1].toInt() shl 8)
+                                val absSample = abs(sample.toShort().toInt())
+                                if (absSample > peak) peak = absSample
+                                i += 2
+                            }
+
+                            if (peak < SILENCE_AMPLITUDE_THRESHOLD) {
+                                if (silenceStart == null) {
+                                    silenceStart = now
+                                }
+                                if (now - silenceStart >= silenceThresholdMs) {
+                                    break
+                                }
+                            } else {
+                                silenceStart = null
+                            }
+                        }
+                    }
+                }
+            } finally {
+                releaseResources()
+                val capturedContinuation = continuation
+                continuation = null
+                capturedContinuation?.resume(outputStream.toByteArray())
+            }
+        }
+    }
+
+    fun stop() {
+        isRecording = false
+        carAudioRecord?.stopRecording()
+        audioRecord?.stop()
+    }
+
+    @RequiresApi(Build.VERSION_CODES.O)
+    private fun releaseResources() {
+        carAudioRecord?.stopRecording()
+        carAudioRecord = null
+        audioRecord?.stop()
+        audioRecord?.release()
+        audioRecord = null
+        recordingJob = null
+        audioFocusRequest?.let {
+            val audioManager = (NitroModules.applicationContext ?: carContext)?.getSystemService(
+                AudioManager::class.java,
+            )
+            audioManager?.abandonAudioFocusRequest(it)
+        }
+        audioFocusRequest = null
+    }
+
+    fun dispose() {
+        stop()
+        scope.cancel()
+    }
+
+    companion object {
+        private const val SILENCE_AMPLITUDE_THRESHOLD = 500
+        private const val WARMUP_MS = 500L
+        private const val SAMPLE_RATE = 16_000
+        private const val PHONE_BUFFER_SIZE = 3_200 // ~100ms at 16kHz/16-bit/mono
+    }
+}

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/template/MapTemplate.kt

@@ -377,7 +377,8 @@ class MapTemplate(
                 val notificationIcon = Parser.parseImageToBitmap(
                     context,
                     current.symbolImage.asFirstOrNull(),
-                    current.symbolImage.asSecondOrNull()
+                    current.symbolImage.asSecondOrNull(),
+                    current.symbolImage.asThirdOrNull()
                 )
 
                 val notificationText = currentStep.cue?.toString()

package/android/src/main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/template/Parser.kt

@@ -40,6 +40,7 @@ import com.facebook.datasource.DataSources
 import com.facebook.drawee.backends.pipeline.Fresco
 import com.facebook.imagepipeline.image.CloseableBitmap
 import com.facebook.imagepipeline.image.CloseableXml
+import com.facebook.imagepipeline.request.ImageRequest
 import com.facebook.imagepipeline.request.ImageRequestBuilder
 import com.facebook.react.views.imagehelper.ImageSource
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.AndroidAutoScreen
@@ -67,10 +68,11 @@ import com.margelo.nitro.swe.iternio.reactnativeautoplay.NitroRow
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.NitroSectionType
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.OffRampType
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.OnRampType
+import com.margelo.nitro.swe.iternio.reactnativeautoplay.RemoteImage
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.TrafficSide
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.TravelEstimates
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.TurnType
-import com.margelo.nitro.swe.iternio.reactnativeautoplay.Variant_GlyphImage_AssetImage
+import com.margelo.nitro.swe.iternio.reactnativeautoplay.Variant_GlyphImage_AssetImage_RemoteImage
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.utils.BitmapCache
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.utils.SymbolFont
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.utils.get
@@ -79,6 +81,7 @@ import java.util.Calendar
 import java.util.Locale
 import java.util.TimeZone
 import kotlin.math.abs
+import androidx.core.net.toUri
 
 object Parser {
     const val TAG = "Parser"
@@ -210,27 +213,35 @@ object Parser {
         }.build()
     }
 
-    fun parseImage(context: CarContext, image: Variant_GlyphImage_AssetImage): CarIcon {
-        return parseImage(context, image.asFirstOrNull(), image.asSecondOrNull())
+    fun parseImage(context: CarContext, image: Variant_GlyphImage_AssetImage_RemoteImage): CarIcon {
+        return parseImage(context, image.asFirstOrNull(), image.asSecondOrNull(), image.asThirdOrNull())
     }
 
     fun parseImage(context: CarContext, image: NitroImage): CarIcon {
-        return parseImage(context, image.asFirstOrNull(), image.asSecondOrNull())
+        return parseImage(context, image.asFirstOrNull(), image.asSecondOrNull(), image.asThirdOrNull())
     }
 
-    fun parseImage(context: CarContext, glyphImage: GlyphImage?, assetImage: AssetImage?): CarIcon {
-        val bitmap = parseImageToBitmap(context, glyphImage, assetImage)
+    fun parseImage(
+        context: CarContext,
+        glyphImage: GlyphImage?,
+        assetImage: AssetImage?,
+        remoteImage: RemoteImage?
+    ): CarIcon {
+        val bitmap = parseImageToBitmap(context, glyphImage, assetImage, remoteImage)
 
         bitmap?.let {
             return CarIcon.Builder(IconCompat.createWithBitmap(it)).build()
         }
 
-        // this should not be possible, we just wanna satisfy kotlin
-        return CarIcon.APP_ICON
+        // remote images might fail to load so we provide some placeholder then
+        return CarIcon.ALERT
     }
 
     fun parseImageToBitmap(
-        context: CarContext, glyphImage: GlyphImage?, assetImage: AssetImage?
+        context: CarContext,
+        glyphImage: GlyphImage?,
+        assetImage: AssetImage?,
+        remoteImage: RemoteImage?
     ): Bitmap? {
         glyphImage?.let {
             return SymbolFont.imageFromNitroImage(
@@ -240,6 +251,9 @@ object Parser {
         assetImage?.let {
             return parseAssetImage(context, it)
         }
+        remoteImage?.let {
+            return parseRemoteImage(context, it)
+        }
 
         return null
     }
@@ -251,10 +265,14 @@ object Parser {
     fun imageFromNitroImages(
         context: CarContext, images: List<NitroImage>
     ): IconCompat {
-        val bitmaps = images.map {
+        val bitmaps = images.mapNotNull {
             parseImageToBitmap(
-                context, it.asFirstOrNull(), it.asSecondOrNull()
-            )!!
+                context, it.asFirstOrNull(), it.asSecondOrNull(), it.asThirdOrNull()
+            )
+        }
+
+        if (bitmaps.isEmpty()) {
+            return IconCompat.createWithBitmap(createBitmap(1, 1))
         }
 
         val height = bitmaps.maxOf { it.height }
@@ -512,54 +530,106 @@ object Parser {
     }
 
     fun parseAssetImage(context: CarContext, assetImage: AssetImage): Bitmap? {
-        var bitmap = BitmapCache.get(context, assetImage)
+        BitmapCache.get(context, assetImage)?.let { return it }
 
-        if (bitmap != null) {
-            return bitmap
-        }
+        val imageRequest = buildImageRequest(ImageSource(context, assetImage.uri).uri)
+        val bitmap = fetchBitmap(context, imageRequest, timeoutMs = null) ?: return null
 
-        val source = ImageSource(context, assetImage.uri)
-        val imageRequest = ImageRequestBuilder.newBuilderWithSource(source.uri).disableDiskCache()
-            .disableMemoryCache().build()
+        return applyTintAndCache(
+            context = context,
+            color = assetImage.color,
+            bitmap = bitmap,
+            cache = { result -> BitmapCache.put(context, assetImage, result) }
+        )
+    }
+
+    fun parseRemoteImage(context: CarContext, remoteImage: RemoteImage): Bitmap? {
+        BitmapCache.get(context, remoteImage)?.let { return it }
+
+        val imageRequest = buildImageRequest(remoteImage.uri.toUri())
+        val timeoutMs = remoteImage.timeoutMs?.toLong() ?: 500L
+        val bitmap = fetchBitmap(context, imageRequest, timeoutMs = timeoutMs) ?: return null
+
+        return applyTintAndCache(
+            context = context,
+            color = remoteImage.color,
+            bitmap = bitmap,
+            cache = { result -> BitmapCache.put(context, remoteImage, result) }
+        )
+    }
 
-        val dataSource = Fresco.getImagePipeline().fetchDecodedImage(imageRequest, context)
-        val result = DataSources.waitForFinalResult(dataSource)
+    // Disable Fresco's own caching — BitmapCache handles all caching uniformly
+    private fun buildImageRequest(uri: android.net.Uri): ImageRequest =
+        ImageRequestBuilder.newBuilderWithSource(uri)
+            .disableDiskCache().disableMemoryCache().build()
+
+    /**
+     * Fetches a bitmap via Fresco's image pipeline.
+     * When [timeoutMs] is provided, the fetch runs on a background thread and is abandoned on timeout.
+     * When `null`, the fetch runs synchronously (bundled assets, no network I/O).
+     */
+    private fun fetchBitmap(
+        context: CarContext,
+        imageRequest: ImageRequest,
+        timeoutMs: Long?
+    ): Bitmap? {
+        if (timeoutMs == null) return fetchSync(context, imageRequest)
+
+        var fetched: Bitmap? = null
+        val thread = Thread { fetched = fetchSync(context, imageRequest) }
+        thread.start()
+        thread.join(timeoutMs)
+        if (thread.isAlive) {
+            // Fresco's waitForFinalResult is not interruptible, but setting the flag
+            // lets any subsequent interruptible call exit and signals intent to exit.
+            thread.interrupt()
+            return null
+        }
+        return fetched
+    }
 
+    private fun fetchSync(context: CarContext, imageRequest: ImageRequest): Bitmap? {
+        val dataSource = try {
+            Fresco.getImagePipeline().fetchDecodedImage(imageRequest, context)
+        } catch (_: Exception) { return null }
+        val result = try {
+            DataSources.waitForFinalResult(dataSource)
+        } catch (_: Exception) { dataSource.close(); return null }
         val image = result?.get()
         try {
             if (image is CloseableBitmap) {
-                bitmap = image.underlyingBitmap.copy(Bitmap.Config.ARGB_8888, false)
+                return image.underlyingBitmap.copy(Bitmap.Config.ARGB_8888, false)
             } else if (image is CloseableXml) {
                 val drawable = image.buildDrawable()
-                bitmap = drawable?.toBitmap(
-                    width = image.width, height = image.height, Bitmap.Config.ARGB_8888
-                )
+                return drawable?.toBitmap(width = image.width, height = image.height, Bitmap.Config.ARGB_8888)
             }
         } finally {
             image?.close()
             result?.close()
             dataSource.close()
         }
+        return null
+    }
 
-        if (bitmap == null) {
-            return null
-        }
-
-        assetImage.color?.get(context)?.let { color ->
-            val result = createBitmap(bitmap.width, bitmap.height)
-            val canvas = Canvas(result)
+    private fun applyTintAndCache(
+        context: CarContext,
+        color: NitroColor?,
+        bitmap: Bitmap,
+        cache: (Bitmap) -> Unit
+    ): Bitmap {
+        color?.get(context)?.let { tint ->
+            val tinted = createBitmap(bitmap.width, bitmap.height)
+            val canvas = Canvas(tinted)
             val paint = Paint()
 
-            paint.colorFilter = PorterDuffColorFilter(color, PorterDuff.Mode.SRC_IN)
+            paint.colorFilter = PorterDuffColorFilter(tint, PorterDuff.Mode.SRC_IN)
             canvas.drawBitmap(bitmap, 0f, 0f, paint)
 
-            BitmapCache.put(context, assetImage, result)
-
-            return result
+            cache(tinted)
+            return tinted
         }
 
-        BitmapCache.put(context, assetImage, bitmap)
-
+        cache(bitmap)
         return bitmap
     }