feat!: experimental Rive runtime backend (iOS + Android)

.editorconfig

@@ -33,6 +33,9 @@ ktlint_standard_string-template-indent = disabled
 ktlint_standard_backing-property-naming = disabled
 ktlint_standard_no-consecutive-comments = disabled
 ktlint_standard_no-empty-first-line-in-class-body = disabled
+ktlint_standard_condition-wrapping = disabled
+ktlint_standard_if-else-wrapping = disabled
+ktlint_standard_function-naming = disabled
 
 [nitrogen/generated/**/*.kt]
 ktlint = disabled

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           reporter: github-pr-review
           ktlint_version: "1.5.0"
-          android: true
+          fail_on_error: true
 
   lint:
     runs-on: ubuntu-latest
@@ -472,3 +472,198 @@ jobs:
         run: |
           echo "=== Checking logcat for errors ==="
           adb logcat -d -s ReactNativeJS:* RiveExample:* RNRive:* | tail -200 || echo "No logs found"
+
+  test-harness-ios-legacy:
+    runs-on: macos-latest
+    timeout-minutes: 90
+    env:
+      XCODE_VERSION: 16.4
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Use appropriate Xcode version
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: ${{ env.XCODE_VERSION }}
+
+      - name: Restore cocoapods
+        id: cocoapods-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            **/ios/Pods
+          key: ${{ runner.os }}-legacy-cocoapods-${{ hashFiles('example/ios/Podfile', '*.podspec') }}
+          restore-keys: |
+            ${{ runner.os }}-legacy-cocoapods-
+
+      - name: Install cocoapods
+        if: steps.cocoapods-cache.outputs.cache-hit != 'true'
+        run: |
+          cd example
+          bundle install
+          USE_RIVE_LEGACY=1 bundle exec pod install --project-directory=ios
+
+      - name: Save cocoapods cache
+        if: steps.cocoapods-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            **/ios/Pods
+          key: ${{ steps.cocoapods-cache.outputs.cache-key }}
+
+      - name: Restore iOS build cache
+        id: ios-build-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: example/ios/build
+          key: ${{ runner.os }}-ios-legacy-build-${{ env.XCODE_VERSION }}-${{ hashFiles('yarn.lock', 'ios/**', 'nitrogen/generated/ios/**', '*.podspec', 'example/ios/Podfile', 'example/ios/RiveExample/**') }}
+          restore-keys: |
+            ${{ runner.os }}-ios-legacy-build-${{ env.XCODE_VERSION }}-
+
+      - name: Build iOS app
+        if: steps.ios-build-cache.outputs.cache-hit != 'true'
+        working-directory: example/ios
+        run: |
+          set -o pipefail && xcodebuild \
+            -derivedDataPath build \
+            -workspace RiveExample.xcworkspace \
+            -scheme RiveExample \
+            -sdk iphonesimulator \
+            -configuration Debug \
+            build \
+            CODE_SIGNING_ALLOWED=NO
+
+      - name: Save iOS build cache
+        if: steps.ios-build-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: example/ios/build
+          key: ${{ steps.ios-build-cache.outputs.cache-primary-key }}
+
+      - name: Boot iOS Simulator
+        uses: futureware-tech/simulator-action@v4
+        with:
+          model: 'iPhone 16 Pro'
+          os_version: '18.6'
+
+      - name: Install app on simulator
+        run: xcrun simctl install booted example/ios/build/Build/Products/Debug-iphonesimulator/RiveExample.app
+
+      - name: Wait for simulator to be fully ready
+        run: |
+          echo "Waiting for simulator to be fully ready..."
+          sleep 10
+          xcrun simctl list devices | grep Booted
+
+      - name: Run harness tests on iOS
+        working-directory: example
+        run: |
+          for attempt in 1 2 3; do
+            echo "Attempt $attempt of 3"
+            if yarn test:harness:ios --verbose --testTimeout 120000; then
+              echo "Tests passed on attempt $attempt"
+              exit 0
+            fi
+            echo "Attempt $attempt failed, retrying..."
+            sleep 5
+          done
+          echo "All attempts failed"
+          exit 1
+
+      - name: Debug - Check for console logs
+        if: failure()
+        run: |
+          echo "=== Checking simulator logs for errors ==="
+          xcrun simctl spawn booted log show --predicate 'processImagePath CONTAINS "RiveExample"' --last 5m --style compact 2>&1 | tail -200 || echo "No logs found"
+
+  test-harness-android-legacy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      ANDROID_API_LEVEL: 35
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Install JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+
+      - name: Finalize Android SDK
+        run: |
+          /bin/bash -c "yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses > /dev/null"
+
+      - name: Enable legacy Rive backend
+        run: |
+          echo "USE_RIVE_LEGACY=true" >> example/android/gradle.properties
+
+      - name: Cache Gradle
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches
+          key: ${{ runner.os }}-gradle-harness-legacy-${{ hashFiles('example/android/gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-harness-legacy-
+            ${{ runner.os }}-gradle-harness-
+            ${{ runner.os }}-gradle-
+
+      - name: Restore Android build cache
+        id: android-build-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: example/android/app/build
+          key: ${{ runner.os }}-android-legacy-build-${{ env.ANDROID_API_LEVEL }}-${{ hashFiles('yarn.lock', 'android/**', 'nitrogen/generated/android/**', 'example/android/app/build.gradle', 'example/android/gradle.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-android-legacy-build-${{ env.ANDROID_API_LEVEL }}-
+
+      - name: Build Android app
+        if: steps.android-build-cache.outputs.cache-hit != 'true'
+        working-directory: example/android
+        env:
+          JAVA_OPTS: "-XX:MaxHeapSize=6g"
+        run: |
+          ./gradlew assembleDebug --no-daemon --console=plain -PreactNativeArchitectures=x86_64
+
+      - name: Save Android build cache
+        if: steps.android-build-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: example/android/app/build
+          key: ${{ steps.android-build-cache.outputs.cache-primary-key }}
+
+      - name: Enable KVM
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: Run harness tests on Android
+        uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: ${{ env.ANDROID_API_LEVEL }}
+          arch: x86_64
+          target: google_apis
+          force-avd-creation: false
+          emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
+          disable-animations: true
+          script: |
+            adb install example/android/app/build/outputs/apk/debug/app-debug.apk
+            sleep 10
+            cd example && for attempt in 1 2 3; do echo "Attempt $attempt of 3"; if timeout 300 env ANDROID_AVD=test yarn test:harness:android --verbose --testTimeout 120000; then echo "Tests passed on attempt $attempt"; exit 0; fi; echo "Attempt $attempt failed (exit $?), retrying..."; sleep 5; done; echo "All attempts failed"; exit 1
+
+      - name: Debug - Check logcat
+        if: failure() || cancelled()
+        run: |
+          echo "=== Checking logcat for errors ==="
+          adb logcat -d -s ReactNativeJS:* RiveExample:* RNRive:* | tail -200 || echo "No logs found"

RNRive.podspec

@@ -28,7 +28,15 @@ if !rive_ios_version
   raise "Internal Error: Failed to determine Rive iOS SDK version. Please ensure package.json contains 'runtimeVersions.ios'"
 end
 
-Pod::UI.puts "@rive-app/react-native: Rive iOS SDK #{rive_ios_version}"
+# The experimental runtime backend is used by default. Set USE_RIVE_LEGACY=1
+# (or $UseRiveLegacy = true in Podfile) to fall back to the legacy backend.
+use_legacy = ENV['USE_RIVE_LEGACY'] == '1' || (defined?($UseRiveLegacy) && $UseRiveLegacy)
+
+if use_legacy
+  Pod::UI.puts "@rive-app/react-native: Using legacy Rive runtime backend (iOS SDK #{rive_ios_version})"
+else
+  Pod::UI.puts "@rive-app/react-native: Using experimental Rive runtime backend"
+end
 
 # Xcode 26 workaround: strip .Swift Clang submodule from RiveRuntime's prebuilt
 # modulemaps to prevent ODR conflicts with locally-compiled Swift C++ interop.
@@ -65,11 +73,21 @@ Pod::Spec.new do |s|
 
   s.source_files = "ios/**/*.{h,m,mm,swift}"
 
+  if use_legacy
+    s.exclude_files = ["ios/new/**"]
+  else
+    s.exclude_files = ["ios/legacy/**"]
+  end
+
   s.public_header_files = ['ios/RCTSwiftLog.h']
   load 'nitrogen/generated/ios/RNRive+autolinking.rb'
   add_nitrogen_files(s)
 
-  s.dependency "RiveRuntime", rive_ios_version
+  s.dependency 'RiveRuntime', rive_ios_version
 
  install_modules_dependencies(s)
+
+  unless use_legacy
+    s.xcconfig = { 'OTHER_SWIFT_FLAGS' => '$(inherited) -DRIVE_EXPERIMENTAL_API' }
+  end
 end

android/build.gradle

@@ -111,10 +111,17 @@ android {
     targetCompatibility JavaVersion.VERSION_1_8
   }
 
+  def useLegacy = rootProject.findProperty('USE_RIVE_LEGACY') == 'true'
+
   sourceSets {
     main {
       java.srcDirs += ["generated/java",
                        "generated/jni"]
+      if (useLegacy) {
+        java.srcDirs += ["src/legacy/java"]
+      } else {
+        java.srcDirs += ["src/new/java"]
+      }
     }
   }
 }

android/src/main/java/com/margelo/nitro/rive/HybridRiveFile.kt → android/src/legacy/java/com/margelo/nitro/rive/HybridRiveFile.kt

@@ -138,6 +138,23 @@ class HybridRiveFile : HybridRiveFileSpec() {
     }
   }
 
+  override fun getEnums(): Promise<Array<RiveEnumDefinition>> {
+    val file = riveFile ?: return Promise.resolved(emptyArray())
+    return Promise.async {
+      try {
+        file.enums
+          .map { enum ->
+            RiveEnumDefinition(
+              name = enum.name,
+              values = enum.values.toTypedArray()
+            )
+          }.toTypedArray()
+      } catch (e: NoSuchMethodError) {
+        throw UnsupportedOperationException("getEnums requires rive-android SDK with enums support")
+      }
+    }
+  }
+
   override fun dispose() {
     scope.cancel()
     weakViews.clear()

android/src/main/java/com/margelo/nitro/rive/HybridRiveFileFactory.kt → android/src/legacy/java/com/margelo/nitro/rive/HybridRiveFileFactory.kt

@@ -20,6 +20,8 @@ data class FileAndCache(
 @Keep
 @DoNotStrip
 class HybridRiveFileFactory : HybridRiveFileFactorySpec() {
+  override val backend: String = "legacy"
+
   private fun buildRiveFile(
     data: ByteArray,
     referencedAssets: ReferencedAssetsType?

android/src/main/java/com/margelo/nitro/rive/HybridViewModelListProperty.kt → android/src/legacy/java/com/margelo/nitro/rive/HybridViewModelListProperty.kt

@@ -65,6 +65,26 @@ class HybridViewModelListProperty(private val listProperty: ViewModelListPropert
     return Promise.async { getInstanceAt(index) }
   }
 
+  override fun addInstanceAsync(instance: HybridViewModelInstanceSpec): Promise<Unit> {
+    return Promise.async { addInstance(instance) }
+  }
+
+  override fun addInstanceAtAsync(instance: HybridViewModelInstanceSpec, index: Double): Promise<Unit> {
+    return Promise.async { addInstanceAt(instance, index) }
+  }
+
+  override fun removeInstanceAsync(instance: HybridViewModelInstanceSpec): Promise<Unit> {
+    return Promise.async { removeInstance(instance) }
+  }
+
+  override fun removeInstanceAtAsync(index: Double): Promise<Unit> {
+    return Promise.async { removeInstanceAt(index) }
+  }
+
+  override fun swapAsync(index1: Double, index2: Double): Promise<Unit> {
+    return Promise.async { swap(index1, index2) }
+  }
+
   override fun addListener(onChanged: () -> Unit): () -> Unit {
     val remover = addListenerInternal { _ -> onChanged() }
     ensureValueListenerJob(listProperty.valueFlow.map { })

android/src/main/java/com/margelo/nitro/rive/DeprecationWarning.kt

@@ -0,0 +1,14 @@
+package com.margelo.nitro.rive
+
+object DeprecationWarning {
+    private val warned = mutableSetOf<String>()
+
+    fun warn(method: String, replacement: String) {
+        if (warned.add(method)) {
+            RiveLog.w(
+                "Deprecation",
+                "'$method' is deprecated and blocks the calling thread. Use '$replacement' instead.",
+            )
+        }
+    }
+}

android/src/main/java/com/margelo/nitro/rive/HybridRiveLogger.kt

@@ -0,0 +1,22 @@
+package com.margelo.nitro.rive
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+
+@Keep
+@DoNotStrip
+class HybridRiveLogger : HybridRiveLoggerSpec() {
+    override fun setHandler(handler: (level: String, tag: String, message: String) -> Unit) {
+        RiveLog.handler = handler
+    }
+
+    override fun resetHandler() {
+        RiveLog.handler = null
+    }
+
+    override fun setLogLevel(level: String) {
+        val parsed = RiveLogLevel.fromString(level)
+            ?: throw RuntimeException("Invalid log level '$level'. Use: debug, info, warn, error")
+        RiveLog.minLevel = parsed
+    }
+}