feat: implement Android experimental backend with CommandQueue API

Custom TextureView renderer with Choreographer render loop, CommandQueue
polling infrastructure, ViewModel resolution and property validation,
and example Compose test activities for manual testing.

Author: mfazekas

android/src/experimental/java/com/margelo/nitro/rive/ExperimentalAssetLoader.kt

@@ -110,9 +110,14 @@ object ExperimentalAssetLoader {
     // JPEG: FF D8 FF
     if (data[0] == 0xFF.toByte() && data[1] == 0xD8.toByte() &&
       data[2] == 0xFF.toByte()) return AssetType.IMAGE
-    // WebP: RIFF....WEBP
+    // RIFF container: WebP (RIFF....WEBP) or WAV (RIFF....WAVE)
     if (data[0] == 0x52.toByte() && data[1] == 0x49.toByte() &&
-      data[2] == 0x46.toByte() && data[3] == 0x46.toByte()) return AssetType.IMAGE
+      data[2] == 0x46.toByte() && data[3] == 0x46.toByte()) {
+      if (data.size >= 12 &&
+        data[8] == 0x57.toByte() && data[9] == 0x41.toByte() &&
+        data[10] == 0x56.toByte() && data[11] == 0x45.toByte()) return AssetType.AUDIO // "WAVE"
+      return AssetType.IMAGE // assume WebP for other RIFF
+    }
     // ID3 (MP3): 49 44 33
     if (data[0] == 0x49.toByte() && data[1] == 0x44.toByte() &&
       data[2] == 0x33.toByte()) return AssetType.AUDIO

android/src/experimental/java/com/margelo/nitro/rive/HybridRiveFile.kt

@@ -4,10 +4,13 @@ import android.util.Log
 import androidx.annotation.Keep
 import app.rive.Artboard
 import app.rive.RiveFile
+import app.rive.ViewModelInstance
 import app.rive.ViewModelSource
 import app.rive.core.CommandQueue
+import app.rive.runtime.kotlin.core.ViewModel.PropertyDataType
 import com.facebook.proguard.annotations.DoNotStrip
 import java.lang.ref.WeakReference
+import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.runBlocking
 
 @Keep
@@ -61,18 +64,23 @@ class HybridRiveFile(
   override fun defaultArtboardViewModel(artboardBy: ArtboardBy?): HybridViewModelSpec? {
     val file = riveFile ?: return null
     return try {
-      val artboardNames = runBlocking { file.getArtboardNames() }
       val artboardName = when (artboardBy?.type) {
-        ArtboardByTypes.INDEX -> artboardNames.getOrNull(artboardBy.index!!.toInt())
+        ArtboardByTypes.INDEX -> {
+          val artboardNames = runBlocking { file.getArtboardNames() }
+          artboardNames.getOrNull(artboardBy.index!!.toInt())
+        }
         ArtboardByTypes.NAME -> artboardBy.name
-        null -> artboardNames.firstOrNull()
-      } ?: return null
+        null -> null
+      }
 
-      val artboard = Artboard.fromFile(file, artboardName)
+      val artboard = if (artboardName != null) {
+        Artboard.fromFile(file, artboardName)
+      } else {
+        Artboard.fromFile(file)
+      }
       val vmSource = ViewModelSource.DefaultForArtboard(artboard)
-      val vmNames = runBlocking { file.getViewModelNames() }
-      if (vmNames.isEmpty()) return null
-      HybridViewModel(file, riveWorker, vmNames.first(), this)
+      val resolvedName = runBlocking { resolveDefaultVMName(file, vmSource) }
+      HybridViewModel(file, riveWorker, resolvedName, this, vmSource)
     } catch (e: Exception) {
       Log.e(TAG, "defaultArtboardViewModel failed", e)
       null
@@ -133,6 +141,49 @@ class HybridRiveFile(
     weakViews.removeAll { it.get() == view }
   }
 
+  /**
+   * Resolves the actual ViewModel name for a DefaultForArtboard source.
+   * The new Rive SDK doesn't expose VM name from DefaultForArtboard directly,
+   * so we compare property values between the artboard VMI and named VMIs.
+   */
+  private suspend fun resolveDefaultVMName(
+    file: RiveFile,
+    vmSource: ViewModelSource.DefaultForArtboard
+  ): String {
+    val vmNames = file.getViewModelNames()
+    if (vmNames.size <= 1) return vmNames.firstOrNull() ?: "default"
+
+    val artboardVmi = ViewModelInstance.fromFile(file, vmSource.defaultInstance())
+    try {
+      // Find a string property to use as identifier for value comparison
+      val testPropName = vmNames.firstNotNullOfOrNull { name ->
+        file.getViewModelProperties(name)
+          .firstOrNull { it.type == PropertyDataType.STRING }
+          ?.name
+      } ?: return vmNames.first()
+
+      val artboardValue = try {
+        artboardVmi.getStringFlow(testPropName).first()
+      } catch (_: Exception) { return vmNames.first() }
+
+      for (name in vmNames) {
+        val namedVmi = ViewModelInstance.fromFile(file, ViewModelSource.Named(name).defaultInstance())
+        try {
+          val namedValue = try {
+            namedVmi.getStringFlow(testPropName).first()
+          } catch (_: Exception) { continue }
+          if (namedValue == artboardValue) return name
+        } finally {
+          namedVmi.close()
+        }
+      }
+    } finally {
+      artboardVmi.close()
+    }
+
+    return vmNames.firstOrNull() ?: "default"
+  }
+
   override fun dispose() {
     weakViews.clear()
     riveFile?.close()

android/src/experimental/java/com/margelo/nitro/rive/HybridRiveFileFactory.kt

@@ -1,7 +1,10 @@
 package com.margelo.nitro.rive
 
 import android.annotation.SuppressLint
+import android.os.Handler
+import android.os.Looper
 import android.util.Log
+import android.view.Choreographer
 import androidx.annotation.Keep
 import app.rive.RiveFile
 import app.rive.RiveFileSource
@@ -12,6 +15,49 @@ import com.margelo.nitro.core.Promise
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 
+/**
+ * Custom RiveLog logger that logs to Logcat and broadcasts error messages
+ * to registered listeners. This captures C++ errors from the Rive CommandQueue
+ * (e.g., "State machine not found", "Draw failed") that are otherwise silent.
+ */
+object RiveErrorLogger : app.rive.RiveLog.Logger {
+  private val logcat = app.rive.RiveLog.LogcatLogger()
+  private val listeners = mutableListOf<(String) -> Unit>()
+  private val reportedErrors = mutableSetOf<String>()
+
+  fun addListener(listener: (String) -> Unit) {
+    synchronized(listeners) { listeners.add(listener) }
+  }
+
+  fun removeListener(listener: (String) -> Unit) {
+    synchronized(listeners) { listeners.remove(listener) }
+  }
+
+  private fun broadcastError(tag: String, msg: String) {
+    val key = "$tag:$msg"
+    synchronized(reportedErrors) {
+      if (!reportedErrors.add(key)) return
+    }
+    synchronized(listeners) {
+      listeners.toList().forEach { it("[$tag] $msg") }
+    }
+  }
+
+  fun resetReportedErrors() {
+    synchronized(reportedErrors) { reportedErrors.clear() }
+  }
+
+  override fun v(tag: String, msg: () -> String) = logcat.v(tag, msg)
+  override fun d(tag: String, msg: () -> String) = logcat.d(tag, msg)
+  override fun i(tag: String, msg: () -> String) = logcat.i(tag, msg)
+  override fun w(tag: String, msg: () -> String) = logcat.w(tag, msg)
+  override fun e(tag: String, t: Throwable?, msg: () -> String) {
+    val message = msg()
+    logcat.e(tag, t) { message }
+    broadcastError(tag, message)
+  }
+}
+
 @Keep
 @DoNotStrip
 class HybridRiveFileFactory : HybridRiveFileFactorySpec() {
@@ -20,10 +66,42 @@ class HybridRiveFileFactory : HybridRiveFileFactorySpec() {
 
     @Volatile
     private var sharedWorker: CommandQueue? = null
+    private var pollingStarted = false
 
     @Synchronized
     fun getSharedWorker(): CommandQueue {
-      return sharedWorker ?: CommandQueue().also { sharedWorker = it }
+      if (app.rive.RiveLog.logger !is RiveErrorLogger) {
+        app.rive.RiveLog.logger = RiveErrorLogger
+        Log.d(TAG, "RiveErrorLogger installed")
+      }
+      return sharedWorker ?: CommandQueue().also {
+        sharedWorker = it
+        Log.d(TAG, "Created CommandQueue, refCount=${it.refCount}")
+        startPolling(it)
+      }
+    }
+
+    /**
+     * The experimental Rive SDK's CommandQueue needs to be polled every frame
+     * to process responses from the C++ command server. Without polling,
+     * all suspend functions (like RiveFile.fromSource) hang indefinitely.
+     */
+    private fun startPolling(worker: CommandQueue) {
+      if (pollingStarted) return
+      pollingStarted = true
+      Handler(Looper.getMainLooper()).post {
+        val callback = object : Choreographer.FrameCallback {
+          override fun doFrame(frameTimeNanos: Long) {
+            try {
+              worker.pollMessages()
+            } catch (e: Exception) {
+              Log.e(TAG, "pollMessages error", e)
+            }
+            Choreographer.getInstance().postFrameCallback(this)
+          }
+        }
+        Choreographer.getInstance().postFrameCallback(callback)
+      }
     }
   }
 

android/src/experimental/java/com/margelo/nitro/rive/HybridRiveView.kt

@@ -49,7 +49,11 @@ class HybridRiveView(val context: ThemedReactContext) : HybridRiveViewSpec() {
     private const val TAG = "HybridRiveView"
   }
 
-  override val view: RiveReactNativeView = RiveReactNativeView(context)
+  override val view: RiveReactNativeView = RiveReactNativeView(context).apply {
+    onError = { msg ->
+      this@HybridRiveView.onError(RiveError(type = RiveErrorType.UNKNOWN, message = msg))
+    }
+  }
   private var needsReload = false
   private var dataBindingChanged = false
   private var initialUpdate = true
@@ -157,13 +161,15 @@ class HybridRiveView(val context: ThemedReactContext) : HybridRiveViewSpec() {
       val hybridFile = file as? HybridRiveFile
       val riveFile = hybridFile?.riveFile ?: return@logged
 
+      val convertedFit = convertFit(fit, layoutScaleFactor?.toFloat()) ?: DefaultConfiguration.FIT
       val config = ViewConfiguration(
         artboardName = artboardName,
         stateMachineName = stateMachineName,
         autoPlay = autoPlay ?: DefaultConfiguration.AUTOPLAY,
         riveFile = riveFile,
+        riveWorker = HybridRiveFileFactory.getSharedWorker(),
         alignment = convertAlignment(alignment) ?: DefaultConfiguration.ALIGNMENT,
-        fit = convertFit(fit) ?: DefaultConfiguration.FIT,
+        fit = convertedFit,
         layoutScaleFactor = layoutScaleFactor?.toFloat() ?: DefaultConfiguration.LAYOUTSCALEFACTOR,
         bindData = dataBind.toBindData()
       )
@@ -225,7 +231,7 @@ class HybridRiveView(val context: ThemedReactContext) : HybridRiveViewSpec() {
     }
   }
 
-  private fun convertFit(fit: Fit?): RiveFit? {
+  private fun convertFit(fit: Fit?, layoutScaleFactor: Float? = null): RiveFit? {
     if (fit == null) return null
     return when (fit) {
       Fit.FILL -> RiveFit.Fill
@@ -235,7 +241,7 @@ class HybridRiveView(val context: ThemedReactContext) : HybridRiveViewSpec() {
       Fit.FITHEIGHT -> RiveFit.FitHeight()
       Fit.NONE -> RiveFit.None()
       Fit.SCALEDOWN -> RiveFit.ScaleDown()
-      Fit.LAYOUT -> RiveFit.Layout()
+      Fit.LAYOUT -> RiveFit.Layout(scaleFactor = layoutScaleFactor ?: 1f)
     }
   }
 

android/src/experimental/java/com/margelo/nitro/rive/HybridViewModel.kt

@@ -16,33 +16,43 @@ class HybridViewModel(
   private val riveFile: RiveFile,
   private val riveWorker: CommandQueue,
   private val viewModelName: String,
-  private val parentFile: HybridRiveFile
+  private val parentFile: HybridRiveFile,
+  private val vmSource: ViewModelSource = ViewModelSource.Named(viewModelName)
 ) : HybridViewModelSpec() {
   companion object {
     private const val TAG = "HybridViewModel"
   }
 
   override val propertyCount: Double
-    get() = 0.0
+    get() = try {
+      runBlocking { riveFile.getViewModelProperties(viewModelName) }.size.toDouble()
+    } catch (e: Exception) {
+      Log.e(TAG, "propertyCount failed", e)
+      0.0
+    }
 
   override val instanceCount: Double
-    get() = 0.0
+    get() = try {
+      runBlocking { riveFile.getViewModelInstanceNames(viewModelName) }.size.toDouble()
+    } catch (e: Exception) {
+      Log.e(TAG, "instanceCount failed", e)
+      0.0
+    }
 
   override val modelName: String
     get() = viewModelName
 
-  private val vmSource: ViewModelSource.Named
-    get() = ViewModelSource.Named(viewModelName)
-
   override fun createInstanceByIndex(index: Double): HybridViewModelInstanceSpec? {
     return createDefaultInstance()
   }
 
   override fun createInstanceByName(name: String): HybridViewModelInstanceSpec? {
     return try {
+      val instanceNames = runBlocking { riveFile.getViewModelInstanceNames(viewModelName) }
+      if (!instanceNames.contains(name)) return null
       val source = vmSource.namedInstance(name)
       val vmi = ViewModelInstance.fromFile(riveFile, source)
-      HybridViewModelInstance(vmi, riveWorker, parentFile)
+      HybridViewModelInstance(vmi, riveWorker, parentFile, viewModelName, name)
     } catch (e: Exception) {
       Log.e(TAG, "createInstanceByName('$name') failed", e)
       null
@@ -53,7 +63,7 @@ class HybridViewModel(
     return try {
       val source = vmSource.defaultInstance()
       val vmi = ViewModelInstance.fromFile(riveFile, source)
-      HybridViewModelInstance(vmi, riveWorker, parentFile)
+      HybridViewModelInstance(vmi, riveWorker, parentFile, viewModelName)
     } catch (e: Exception) {
       Log.e(TAG, "createDefaultInstance failed", e)
       null
@@ -64,7 +74,7 @@ class HybridViewModel(
     return try {
       val source = vmSource.blankInstance()
       val vmi = ViewModelInstance.fromFile(riveFile, source)
-      HybridViewModelInstance(vmi, riveWorker, parentFile)
+      HybridViewModelInstance(vmi, riveWorker, parentFile, viewModelName)
     } catch (e: Exception) {
       Log.e(TAG, "createInstance (blank) failed", e)
       null

android/src/experimental/java/com/margelo/nitro/rive/HybridViewModelArtboardProperty.kt

@@ -19,9 +19,9 @@ class HybridViewModelArtboardProperty(
 
   override fun set(artboard: HybridBindableArtboardSpec?) {
     val hybridArtboard = artboard as? HybridBindableArtboard ?: return
-    val file = riveFile.riveFile ?: return
+    val sourceFile = hybridArtboard.file.riveFile ?: return
     try {
-      val newArtboard = Artboard.fromFile(file, hybridArtboard.artboardName)
+      val newArtboard = Artboard.fromFile(sourceFile, hybridArtboard.artboardName)
       instance.setArtboard(path, newArtboard)
     } catch (e: Exception) {
       Log.e(TAG, "Failed to set artboard for path '$path'", e)

android/src/experimental/java/com/margelo/nitro/rive/HybridViewModelColorProperty.kt

@@ -28,7 +28,7 @@ class HybridViewModelColorProperty(
       }
     }
     set(value) {
-      instance.setColor(path, value.toInt())
+      instance.setColor(path, value.toLong().toInt())
     }
 
   override fun addListener(onChanged: (value: Double) -> Unit): () -> Unit {