@iternio/react-native-auto-play 0.6.0 → 0.7.0

package/README.md

@@ -25,6 +25,7 @@
 ## Requirements
 
 -   **iOS builds require Xcode 27+** (the iOS 27 SDK), even for apps that don't use any `mapConfig`/panel features — the library references `CPMapPanel`/`CPPanel` types internally behind `@available(iOS 27.0, *)` checks, but `@available` only defers *runtime* execution, not compile-time symbol resolution, so the SDK must be present to build at all.
+-   **`react-native-nitro-modules` 0.37.1 or newer** — the generated native bindings target that runtime shape; an older nitro-modules install fails at native build time.
 
 ## Installation
 
@@ -48,8 +49,8 @@
 
 #### Bundle identifier
 To get the CarPlay app showing up you need to set a proper Bundle Identifier:
--   Open   `example.xcodeproj`
--   Select the example target, go to the  **Signing & Capabilities**  tab.
+-   Open your app's `.xcodeproj` in Xcode.
+-   Select your app target, go to the  **Signing & Capabilities**  tab.
 -   Under  **Signing > Bundle Identifier**, enter your unique bundle ID (e.g.,  `at.g4rb4g3.autoplay.example`).
 
 #### Entitlements
@@ -178,7 +179,7 @@ This is an example that works for bare react-native (>= 0.82) and Expo SDK 57, c
 It is recommended to attach a listener to MapTemplate.onAppearanceDidChange and send maneuver updates based on this to make sure the colors are applied properly.
 Reason for this is that CarPlay does not allow for color updates on maneuvers shown on the screen. You need to send maneuvers with a new id to get them updated properly on the screen.
 The color properties do not need to handle the mode change, best practice is to use ThemedColor whenever possible and set appropriate light and dark mode colors.
-This is mainly required on CarPlay for now since Android Auto lacks light mode.
+This is mainly required on CarPlay. Android Auto redraws on its own when the day/night state changes, but note that Android Auto 17.8 introduced white templates in day mode while older versions always show dark templates. The car's day/night state (`isDarkMode`) is the same on both, so it does not tell you which template color you are drawn on. Use the `'default'` color for icons that have to stay readable in both cases, see **Icon colors and Android Auto light templates**.
 
 #### CPListTemplate day/night header
 
@@ -293,13 +294,21 @@ This library also supports Android Automotive. To enable Android Automotive supp
 
 -   **`isAutomotiveApp` flag**: You need to inform the library if this is an Automotive app by setting the `isAutomotiveApp` property to `true`. For Android Auto, it should be `false`.
 
-You can set these properties directly in your `android/gradle.properties` file:
+You can set these properties directly in your `android/gradle.properties` file. **Note the
+`ReactNativeAutoPlay_` prefix** — the library reads `rootProject.ext.<name>` first and falls
+back to the prefixed project property, so an unprefixed `isAutomotiveApp=true` in
+`gradle.properties` is silently ignored and you get an Android Auto build instead:
+
 ```properties
 # For Android Automotive
-minSdkVersion=29
-isAutomotiveApp=true
+ReactNativeAutoPlay_minSdkVersion=29
+ReactNativeAutoPlay_isAutomotiveApp=true
 ```
 
+If your app's `android/build.gradle` already defines `ext.minSdkVersion` (the React Native
+template does), that `rootProject.ext` value wins over the property above — raise it there
+instead.
+
 Alternatively, if you need to support different build variants (e.g., for both Android Auto and Android Automotive from the same codebase), using `react-native-config` is the recommended approach.
 
 1.  Install `react-native-config`:
@@ -443,14 +452,34 @@ It is also possible to use custom bundled images (e.g. PNG, WEBP or Vector Drawa
 - iOS: Add to your `Images.xcassets`
 - Android: Add to `res/drawable`
 
+### Icon colors and Android Auto light templates
+
+Starting with **Android Auto 17.8** the host can show white (light) templates in day mode. Older versions (e.g. 17.6) always use dark templates, even in day mode. Both report the same car app API level, so an app cannot tell them apart, and a fixed icon color that is readable on one (white on dark) can be invisible on the other (white on white).
+
+Use the color `'default'` for every monochrome icon that has to stay readable in both cases:
+
+```ts
+{ type: 'glyph', name: 'search', color: 'default' }
+{ type: 'asset', image: require('./icon.png'), color: 'default' }
+{ type: 'remote', uri: 'https://example.com/icon.png', color: 'default' }
+```
+
+-   **Android Auto**: the host tints the icon with its own default icon color for the template it is currently showing, so it follows dark and light templates on every Android Auto version.
+-   **CarPlay**: `'default'` resolves to black in light mode and white in dark mode, so it is safe to use on iOS and does not change anything there.
+-   **Glyphs** use `'default'` automatically when no `color` is set. Exception on Android Auto: a glyph with a non-transparent `backgroundColor` is not tinted, since the tint would recolor the background as well. It keeps the plain white (dark mode) / black (light mode) glyph color, so set `color` explicitly if that does not contrast with your background.
+-   **Asset and remote images** are not tinted unless you set a `color`, so colorful images such as a logo keep their original colors. Only pass `'default'` for monochrome icons.
+-   Any other color (a string or a `ThemedColor`) is applied as specified. Only use those where the color works on both dark and light templates, e.g. a colored icon.
+-   Known limitation: the host may not apply the tint to header action icons on Android Auto 17.8. That is an issue in Android Auto itself, not something the library can work around.
+
 ## Usage
 
 ### 1. Register the AutoPlay Components
 
-You need to register your AutoPlay components in your app's entry file (e.g., `index.js`). This includes setting up the headless task that runs when CarPlay or Android Auto is connected.
+You need to register your AutoPlay components in your app's entry file (e.g., `index.js`). Import `@iternio/react-native-auto-play/installTimers` — a side-effect-only module that replaces the global `setTimeout`/`setInterval`/`requestAnimationFrame` (and their `clear*`/`cancel*` counterparts) with versions that keep running while CarPlay/Android Auto is actively driving the car screen, even if the phone itself is backgrounded or its screen is locked. React Native's own timers throttle or pause in that state regardless of whether the app process is actually still alive, which would otherwise stall ETA updates and telemetry polling. It must run before any other module has a chance to capture a reference to the original globals, which means it must be your entry file's **first import** — ES import declarations are hoisted and evaluated in source order, so it needs to come before everything else, including `react-native` itself:
 
 ```javascript
 // index.js
+import '@iternio/react-native-auto-play/installTimers';
 import { AppRegistry } from 'react-native';
 import { name as appName } from './app.json';
 import App from './src/App';
@@ -576,7 +605,7 @@ All root components rendered by templates/scenes receive `RootComponentInitialPr
 
 -   `id`: Module identifier (e.g. `AutoPlayRoot`, `CarPlayDashboard`, or a cluster UUID).
 -   `rootTag`: React Native root tag.
--   `colorScheme`: `'light' | 'dark'` initial color scheme (listen to `onAppearanceDidChange` on `MapTemplate` for updates).
+-   `colorScheme`: `'light' | 'dark'` initial color scheme (listen to `onAppearanceDidChange` on `MapTemplate` for updates). On Android Auto this is the car's day/night state and does not tell you whether the templates are dark or white (17.8+ can show white templates in day mode, older versions never do).
 -   `window`: `{ width, height, scale }`.
 
 ### Template Configs (Props)
@@ -1259,14 +1288,34 @@ CarPlayDashboard.setButtons([
 - `setAttributedInactiveDescriptionVariants(variants)` — iOS only inactive text.
 - `addListenerColorScheme(cb)` / `addListenerZoom(cb)` / `addListenerCompass(cb)` / `addListenerSpeedLimit(cb)`.
 
+## Testing with Jest
+
+The real package needs native modules and ships ESM, so it can't run under Jest. Use the bundled CommonJS mock instead, one line in your Jest setup file:
+
+```js
+// jest.setup.js
+jest.mock('@iternio/react-native-auto-play', () =>
+  require('@iternio/react-native-auto-play/jest')
+);
+```
+
+Templates, `HybridAutoPlay`, `HybridVoice`, `AutoPlayCluster`, `CarPlayDashboard` and the hooks that need a car surface are safe no-ops (any method call returns `undefined`), `Constants.isIos27OrGreater` is `false`, and all types are unchanged. Tests that need to record constructions or assert on calls should extend it per test file:
+
+```ts
+jest.mock('@iternio/react-native-auto-play', () => {
+  const actual = jest.requireActual('@iternio/react-native-auto-play/jest');
+  return { ...actual, ListTemplate: class { push = jest.fn(() => Promise.resolve()); } };
+});
+```
+
+The same no-op surface is what `react-native-web` builds get automatically via `index.web.ts`.
+
 ## Known Issues
 
 ### iOS
 
 -   **Broken exceptions with `react-native-skia`**: When using `react-native-skia` exceptions on iOS are not reported correctly. This is fixed since version `2.4.19` of `react-native-skia`. For more details, see this [pull request](https://github.com/Shopify/react-native-skia/pull/3595) and [issue](https://github.com/Shopify/react-native-skia/issues/3635).
 -   **AppState on iOS**: The `AppState` module from React Native does not work correctly on iOS because this library uses scenes, which are not supported by the stock `AppState` module. This library provides a custom state listener that works for both Android and iOS. Use `HybridAutoPlay.addListenerRenderState` instead of `AppState`.
--   **Timers stop on screen lock**: iOS stops all timers when the device main screen is turned off. To ensure timers continue to run (which is often necessary for background tasks related to autoplay), a patch for `react-native` is required. A patch is included in the root `patches/` directory and can be applied using `patch-package`.
-In case you are using Expo SDK >= 56 make sure to set `buildReactNativeFromSource` to `true` in your app config for [expo-build-properties](https://docs.expo.dev/versions/latest/sdk/build-properties/#sharedbuildconfigfields), otherwise the patch can't be applied.
 -   **expo-splash-screen stuck on iOS**: The `expo-splash-screen` module is broken on iOS because it does not support scenes, which are used by this library. This can cause the splash screen to be stuck on either the mobile device or on CarPlay. To fix this, a patch for `expo-splash-screen` is included in the root `patches/` directory and can be applied using `patch-package`. After applying the patch, you can hide the splash screen for a specific scene by passing the module name to the `hide` or `hideAsync` function. The module name can be one of the values from the `AutoPlayModules` enum or the UUID of a cluster screen.
     ```tsx
     import { hideAsync } from 'expo-splash-screen';

package/android/src/automotive/AndroidManifest-nonnav.xml

@@ -58,8 +58,6 @@
             </intent-filter>
         </service>
 
-        <service android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.HeadlessTaskService" />
-
         <activity android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.SignInWithGoogleActivity" />
 
         <provider

package/android/src/automotive/AndroidManifest.xml

@@ -74,8 +74,6 @@
             </intent-filter>
         </service>
 
-        <service android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.HeadlessTaskService" />
-
         <activity android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.SignInWithGoogleActivity" />
 
         <provider

package/android/src/main/AndroidManifest-nonnav.xml

@@ -28,8 +28,6 @@
         <meta-data android:name="com.google.android.gms.car.application" android:resource="@xml/automotive_app_desc" tools:ignore="MetadataTagInsideApplicationTag" />
         <meta-data android:name="androidx.car.app.minCarApiLevel" android:value="1" />
 
-        <service android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.HeadlessTaskService" />
-
         <provider android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.ActivityRenderStateProvider" android:authorities="${applicationId}.ActivityRenderStateProvider" android:exported="false" />
     </application>
 </manifest>

package/android/src/main/AndroidManifest.xml

@@ -37,8 +37,6 @@
         <meta-data android:name="com.google.android.gms.car.application" android:resource="@xml/automotive_app_desc" tools:ignore="MetadataTagInsideApplicationTag" />
         <meta-data android:name="androidx.car.app.minCarApiLevel" android:value="1" />
 
-        <service android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.HeadlessTaskService" />
-
         <provider android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.ActivityRenderStateProvider" android:authorities="${applicationId}.ActivityRenderStateProvider" android:exported="false" />
     </application>
 </manifest>

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

@@ -5,14 +5,10 @@ import android.annotation.SuppressLint
 import android.app.Notification
 import android.app.NotificationChannel
 import android.app.NotificationManager
-import android.content.ComponentName
-import android.content.Intent
-import android.content.ServiceConnection
 import android.content.pm.ApplicationInfo
 import android.content.pm.PackageManager
 import android.graphics.Bitmap
 import android.os.Build
-import android.os.IBinder
 import android.util.Log
 import androidx.car.app.CarAppService
 import androidx.car.app.Session
@@ -23,6 +19,7 @@ import androidx.core.app.NotificationCompat
 import androidx.core.app.NotificationManagerCompat
 import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
+import com.facebook.react.ReactApplication
 import com.facebook.react.bridge.LifecycleEventListener
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.utils.AppInfo
@@ -30,7 +27,6 @@ import com.margelo.nitro.swe.iternio.reactnativeautoplay.utils.AppInfo
 class AndroidAutoService : CarAppService() {
     private lateinit var notificationManager: NotificationManager
 
-    private var isServiceBound = false
     private var isSessionStarted = false
     private var isReactAppStarted = false
 
@@ -48,6 +44,8 @@ class AndroidAutoService : CarAppService() {
         super.onCreate()
         instance = this
 
+        (application as? ReactApplication)?.reactHost?.start()
+
         NitroModules.applicationContext?.addLifecycleEventListener(reactLifecycleObserver)
 
         notificationManager = getSystemService(NotificationManager::class.java)
@@ -98,11 +96,6 @@ class AndroidAutoService : CarAppService() {
     }
 
     private val sessionLifecycleObserver = object : DefaultLifecycleObserver {
-        override fun onCreate(owner: LifecycleOwner) {
-            val serviceIntent = Intent(applicationContext, HeadlessTaskService::class.java)
-            bindService(serviceIntent, connection, BIND_AUTO_CREATE)
-        }
-
         override fun onResume(owner: LifecycleOwner) {
             isSessionStarted = true
         }
@@ -112,27 +105,10 @@ class AndroidAutoService : CarAppService() {
         }
 
         override fun onDestroy(owner: LifecycleOwner) {
-            if (isServiceBound) {
-                unbindService(connection)
-                isServiceBound = false
-            }
-
             this@AndroidAutoService.stopForeground(STOP_FOREGROUND_REMOVE)
         }
     }
 
-    private val connection: ServiceConnection = object : ServiceConnection {
-        override fun onServiceConnected(
-            className: ComponentName, service: IBinder
-        ) {
-            isServiceBound = true
-        }
-
-        override fun onServiceDisconnected(arg0: ComponentName) {
-            isServiceBound = false
-        }
-    }
-
     private fun createNotification(
         title: String?, text: String?, largeIcon: Bitmap?
     ): Notification {

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

@@ -0,0 +1,122 @@
+package com.margelo.nitro.swe.iternio.reactnativeautoplay
+
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import java.lang.ref.WeakReference
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicLong
+
+private class ScheduledTimer(
+    val callback: () -> Unit,
+    val interval: Long,
+    val repeats: Boolean,
+    var target: Long,
+)
+
+// Weak ref, so a stale instance (dev reload / host restart) can't tick forever in the queue.
+private class TickRunnable(target: HybridAutoPlayTiming) : Runnable {
+    private val ref = WeakReference(target)
+
+    override fun run() {
+        ref.get()?.tick()
+    }
+}
+
+/**
+ * Backs setTimeout/setInterval (see AutoPlayTimers.ts) with a plain Handler loop on the main
+ * Looper -- not Choreographer, which JavaTimerManager itself uses and only keeps ticking while
+ * the host is resumed or a headless JS task is running. See AutoPlayTiming.nitro.ts.
+ *
+ * Ticks at a fixed ~60Hz while any timer is pending and stops entirely once idle, rather than
+ * scheduling a delay to the next due target: postDelayed's dispatch is gated on uptimeMillis(),
+ * which pauses during deep sleep, so a long pre-sleep delay would need that much *awake* time
+ * after waking. A short, repeated delay only needs ~16ms of awake time, so it fires within
+ * about one frame of the device waking regardless of sleep length -- due timers are then found
+ * correctly because target/now use elapsedRealtime(), which counts straight through sleep.
+ */
+class HybridAutoPlayTiming : HybridAutoPlayTimingSpec() {
+    companion object {
+        private const val FRAME_DURATION_MS = 1000L / 60L
+
+        // RN's TimerManager also numbers ids from 1; offsetting avoids collisions with ids a
+        // pre-install caller (e.g. React's own scheduler) still holds against the original
+        // clearTimeout, now replaced.
+        private const val ID_OFFSET = 1_000_000_000L
+    }
+
+    private val handler = Handler(Looper.getMainLooper())
+    private val timers = ConcurrentHashMap<Double, ScheduledTimer>()
+    private val nextId = AtomicLong(ID_OFFSET)
+    private val isTicking = AtomicBoolean(false)
+    private val tickRunnable = TickRunnable(this)
+
+    private fun ensureTicking() {
+        if (isTicking.compareAndSet(false, true)) {
+            handler.postDelayed(tickRunnable, FRAME_DURATION_MS)
+        }
+    }
+
+    internal fun tick() {
+        // elapsedRealtime(), not uptimeMillis(): both are immune to NTP/manual clock changes,
+        // but unlike uptimeMillis() this one keeps counting through deep sleep.
+        val now = SystemClock.elapsedRealtime()
+
+        // Sort by (target, id): ConcurrentHashMap iteration order is unspecified, so
+        // setTimeout(a, 0); setTimeout(b, 0) could otherwise fire b before a.
+        val dueIds = timers.entries.filter { it.value.target <= now }
+            .sortedWith(compareBy({ it.value.target }, { it.key }))
+            .map { it.key }
+
+        for (id in dueIds) {
+            // Re-check membership: a same-tick callback may have cleared a later timer in
+            // this snapshotted list (e.g. `clearTimeout(t); t = setTimeout(...)`).
+            val timer = timers[id] ?: continue
+
+            if (timer.repeats) {
+                timer.target = now + timer.interval
+            } else {
+                timers.remove(id)
+            }
+
+            timer.callback()
+        }
+
+        if (timers.isNotEmpty()) {
+            handler.postDelayed(tickRunnable, FRAME_DURATION_MS)
+            return
+        }
+
+        isTicking.set(false)
+        // Reclaim: a concurrent createTimer() may have inserted an entry and found `isTicking`
+        // still true (skipping its own post) in the gap before the flag was cleared above.
+        if (timers.isNotEmpty()) {
+            ensureTicking()
+        }
+    }
+
+    override fun createTimer(callback: () -> Unit, durationMs: Double, repeats: Boolean): Double {
+        val interval = durationMs.toLong().coerceAtLeast(0)
+        val id = nextId.getAndIncrement().toDouble()
+        timers[id] = ScheduledTimer(
+            callback = callback,
+            interval = interval,
+            repeats = repeats,
+            target = SystemClock.elapsedRealtime() + interval,
+        )
+        ensureTicking()
+        return id
+    }
+
+    override fun deleteTimer(id: Double) {
+        timers.remove(id)
+    }
+
+    override fun dispose() {
+        handler.removeCallbacks(tickRunnable)
+        isTicking.set(false)
+        timers.clear()
+        super.dispose()
+    }
+}

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

@@ -36,6 +36,7 @@ import androidx.car.app.navigation.model.TravelEstimate
 import androidx.core.graphics.createBitmap
 import androidx.core.graphics.drawable.IconCompat
 import androidx.core.graphics.drawable.toBitmap
+import androidx.core.net.toUri
 import com.facebook.datasource.DataSources
 import com.facebook.drawee.backends.pipeline.Fresco
 import com.facebook.imagepipeline.image.CloseableBitmap
@@ -51,8 +52,8 @@ import com.margelo.nitro.swe.iternio.reactnativeautoplay.DurationWithTimeZone
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.ForkType
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.GlyphImage
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.KeepType
-import com.margelo.nitro.swe.iternio.reactnativeautoplay.ListTemplateConfig
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.ListImageType
+import com.margelo.nitro.swe.iternio.reactnativeautoplay.ListTemplateConfig
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.ManeuverType
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.NitroAction
 import com.margelo.nitro.swe.iternio.reactnativeautoplay.NitroActionType
@@ -82,7 +83,6 @@ import java.util.Calendar
 import java.util.Locale
 import java.util.TimeZone
 import kotlin.math.abs
-import androidx.core.net.toUri
 
 object Parser {
     // IMAGE_TYPE_MEDIUM was added to androidx.car.app in 1.8.0. Keep the protocol value here
@@ -182,7 +182,11 @@ object Parser {
         }.build()
     }
 
-    fun parseAction(context: CarContext, action: NitroAction, useParkedOnlyClickListener: Boolean = false): Action {
+    fun parseAction(
+        context: CarContext,
+        action: NitroAction,
+        useParkedOnlyClickListener: Boolean = false
+    ): Action {
         if (action.type == NitroActionType.APPICON) {
             return Action.APP_ICON
         }
@@ -219,11 +223,21 @@ object Parser {
     }
 
     fun parseImage(context: CarContext, image: Variant_GlyphImage_AssetImage_RemoteImage): CarIcon {
-        return parseImage(context, image.asFirstOrNull(), image.asSecondOrNull(), image.asThirdOrNull())
+        return parseImage(
+            context,
+            image.asFirstOrNull(),
+            image.asSecondOrNull(),
+            image.asThirdOrNull()
+        )
     }
 
     fun parseImage(context: CarContext, image: NitroImage): CarIcon {
-        return parseImage(context, image.asFirstOrNull(), image.asSecondOrNull(), image.asThirdOrNull())
+        return parseImage(
+            context,
+            image.asFirstOrNull(),
+            image.asSecondOrNull(),
+            image.asThirdOrNull()
+        )
     }
 
     fun parseImage(
@@ -234,8 +248,19 @@ object Parser {
     ): CarIcon {
         val bitmap = parseImageToBitmap(context, glyphImage, assetImage, remoteImage)
 
+        // the tint recolors every opaque pixel, so it would also fill the background drawn in SymbolFont
+        val hasGlyphBackground =
+            glyphImage != null && (glyphImage.backgroundColor.get(context) ushr 24) != 0
+
+        val applyDefaultTint = !hasGlyphBackground && (glyphImage?.color?.isDefault
+            ?: assetImage?.color?.isDefault ?: remoteImage?.color?.isDefault ?: false)
+
         bitmap?.let {
-            return CarIcon.Builder(IconCompat.createWithBitmap(it)).build()
+            return CarIcon.Builder(IconCompat.createWithBitmap(it)).apply {
+                if (applyDefaultTint) {
+                    setTint(CarColor.DEFAULT)
+                }
+            }.build()
         }
 
         // remote images might fail to load so we provide some placeholder then
@@ -353,7 +378,7 @@ object Parser {
                     }
                     row.onPress?.let {
                         setOnClickListener {
-                            row.onPress(null)
+                            it(null)
                         }
                     }
                     row.browsable?.let {
@@ -610,10 +635,14 @@ object Parser {
     private fun fetchSync(context: CarContext, imageRequest: ImageRequest): Bitmap? {
         val dataSource = try {
             Fresco.getImagePipeline().fetchDecodedImage(imageRequest, context)
-        } catch (_: Exception) { return null }
+        } catch (_: Exception) {
+            return null
+        }
         val result = try {
             DataSources.waitForFinalResult(dataSource)
-        } catch (_: Exception) { dataSource.close(); return null }
+        } catch (_: Exception) {
+            dataSource.close(); return null
+        }
         val image = result?.get()
         try {
             if (image is CloseableBitmap) {
@@ -624,7 +653,11 @@ object Parser {
                 return image.underlyingBitmap?.copy(Bitmap.Config.ARGB_8888, false)
             } else if (image is CloseableXml) {
                 val drawable = image.buildDrawable()
-                return 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
+                )
             }
         } catch (_: Exception) {
             // Any decode/copy failure (OOM, recycled bitmap, invalid config, …) should
@@ -759,10 +792,12 @@ object Parser {
                 }
                 nitroManeuver.angle?.let { roundaboutExitAngle ->
                     if (nitroManeuver.trafficSide == TrafficSide.LEFT) {
-                        val angle = ((180 + roundaboutExitAngle) % 360).toInt().let { if (it == 0) 360 else it }
+                        val angle = ((180 + roundaboutExitAngle) % 360).toInt()
+                            .let { if (it == 0) 360 else it }
                         setRoundaboutExitAngle(angle)
                     } else {
-                        val angle = ((180 - roundaboutExitAngle) % 360).toInt().let { if (it == 0) 360 else it }
+                        val angle = ((180 - roundaboutExitAngle) % 360).toInt()
+                            .let { if (it == 0) 360 else it }
                         setRoundaboutExitAngle(angle)
                     }
                 }
@@ -841,7 +876,7 @@ object Parser {
             mapConfig.mapButtons?.let { mapButtons ->
                 setMapController(
                     MapController.Builder().apply {
-                        setMapActionStrip(Parser.parseMapActions(context, mapButtons)).build()
+                        setMapActionStrip(parseMapActions(context, mapButtons)).build()
                         setPanModeListener { isInPanMode ->
                             mapConfig.onDidChangePanningInterface?.let {
                                 it(isInPanMode)
@@ -851,7 +886,7 @@ object Parser {
                 )
             }
             mapConfig.headerActions?.let { headerActions ->
-                setActionStrip(Parser.parseMapHeaderActions(context, headerActions))
+                setActionStrip(parseMapHeaderActions(context, headerActions))
             }
         }.build()
     }

package/installTimers.ts

@@ -0,0 +1,3 @@
+// Root re-export so `@iternio/react-native-auto-play/installTimers` is a deliberate, explicitly
+// published public entry point rather than a reach into src/ internals -- see src/installTimers.ts.
+import './src/installTimers';

package/installTimers.web.ts

@@ -0,0 +1,2 @@
+// Web/Jest counterpart to installTimers.ts, picked by Metro's platform resolution.
+import './src/installTimers.web';

package/ios/hybrid/HybridAutoPlayTiming.swift

@@ -0,0 +1,123 @@
+import Foundation
+import NitroModules
+
+private struct ScheduledTimer {
+    let callback: () -> Void
+    let interval: TimeInterval
+    let repeats: Bool
+    var target: TimeInterval
+}
+
+// Unlike ProcessInfo.systemUptime/mach_absolute_time(), keeps counting through sleep. RAW over
+// plain CLOCK_MONOTONIC: also immune to NTP frequency-discipline adjustments.
+private func now() -> TimeInterval {
+    TimeInterval(clock_gettime_nsec_np(CLOCK_MONOTONIC_RAW)) / 1_000_000_000
+}
+
+/// Backs setTimeout/setInterval (see AutoPlayTimers.ts) with a plain `Timer` -- not tied to
+/// `CADisplayLink`/screen refresh, so it keeps firing while the phone screen is locked and
+/// CarPlay is actively driving the external screen. See AutoPlayTiming.nitro.ts.
+///
+/// Ticks at a fixed ~60Hz while any timer is pending and stops entirely once idle, rather than
+/// scheduling a delay to the next due target: a `Timer`'s dispatch is gated on the run loop's
+/// own monotonic clock, which (like `mach_absolute_time()`) pauses during sleep, so a long
+/// pre-sleep delay would need that much *awake* time after waking. A short, repeated delay only
+/// needs ~16ms of awake time, so it fires within about one frame of the device waking
+/// regardless of sleep length.
+class HybridAutoPlayTiming: HybridAutoPlayTimingSpec {
+    private static let frameDuration: TimeInterval = 1.0 / 60.0
+
+    // RN's TimerManager also numbers ids from 1; offsetting avoids collisions with ids a
+    // pre-install caller (e.g. React's own scheduler) still holds against the original
+    // clearTimeout, now replaced.
+    private static let idOffset: Double = 1_000_000_000
+
+    private let lock = NSLock()
+    private var timers = [Double: ScheduledTimer]()
+    private var nextId: Double = HybridAutoPlayTiming.idOffset
+    private var timer: Timer?
+
+    deinit {
+        timer?.invalidate()
+    }
+
+    private func withLock<T>(_ body: () -> T) -> T {
+        lock.lock()
+        defer { lock.unlock() }
+        return body()
+    }
+
+    // Must be called while already holding `lock`.
+    private func scheduleTick() {
+        let next = Timer(timeInterval: HybridAutoPlayTiming.frameDuration, repeats: false) { [weak self] _ in
+            self?.tick()
+        }
+        RunLoop.main.add(next, forMode: .common)
+        timer = next
+    }
+
+    private func tick() {
+        let currentTime = now()
+
+        // Sort by (target, id): Dictionary iteration order is unspecified, so
+        // setTimeout(a, 0); setTimeout(b, 0) could otherwise fire b before a.
+        let dueIds = withLock {
+            timers.filter { $0.value.target <= currentTime }
+                .sorted { lhs, rhs in
+                    lhs.value.target != rhs.value.target
+                        ? lhs.value.target < rhs.value.target
+                        : lhs.key < rhs.key
+                }
+                .map(\.key)
+        }
+
+        for id in dueIds {
+            // Re-check membership: a same-tick callback may have cleared a later timer in
+            // this snapshotted list (e.g. `clearTimeout(t); t = setTimeout(...)`).
+            let callback: (() -> Void)? = withLock {
+                guard var entry = timers[id] else { return nil }
+                if entry.repeats {
+                    entry.target = now() + entry.interval
+                    timers[id] = entry
+                } else {
+                    timers.removeValue(forKey: id)
+                }
+                return entry.callback
+            }
+
+            callback?()
+        }
+
+        withLock {
+            timer = nil
+            if !timers.isEmpty {
+                scheduleTick()
+            }
+        }
+    }
+
+    func createTimer(callback: @escaping () -> Void, durationMs: Double, repeats: Bool) throws -> Double {
+        let interval = max(durationMs, 0) / 1000.0
+
+        return withLock {
+            let id = nextId
+            nextId += 1
+            timers[id] = ScheduledTimer(
+                callback: callback,
+                interval: interval,
+                repeats: repeats,
+                target: now() + interval
+            )
+            if timer == nil {
+                scheduleTick()
+            }
+            return id
+        }
+    }
+
+    func deleteTimer(id: Double) throws {
+        withLock {
+            _ = timers.removeValue(forKey: id)
+        }
+    }
+}

package/jest.js

@@ -0,0 +1,2 @@
+// CommonJS entry for Jest, see "Testing with Jest" in the README.
+module.exports = require('./lib-cjs/index.web');