fix(experimental): address review findings — coroutine scope, RiveUIView reuse, bind-before-ready (#289)

mfazekas · web-flow · commit 17674fa48710 · 2026-06-11T16:42:48.000+02:00
Addresses several correctness issues from the experimental runtime
review.

- **Android**: cancel auto-bind `CoroutineScope` on dispose; adds
`disposed` guard inside the Main-thread hop to prevent post-teardown
binding against a stale/reconfigured handle
- **iOS**: reuse existing `RiveUIView` on reconfigure by assigning
`riveUIView.rive = rive` instead of tearing down and recreating the view
— eliminates orphaned MTKView draw calls on file switch
- **iOS**: queue `bindViewModelInstance` calls that arrive before
`configTask` completes, then apply them once `riveInstance` is set —
previously the bind was silently dropped

Includes harness tests for the iOS fixes:
- `reconfigure.harness.tsx` — verifies animation still plays after
switching file prop and back
- `bind-before-ready.harness.tsx` — reproduces and verifies the
bind-before-ready race (failed before fix, passes after)
diff --git a/android/src/new/java/com/rive/RiveReactNativeView.kt b/android/src/new/java/com/rive/RiveReactNativeView.kt
@@ -22,6 +22,8 @@ import com.margelo.nitro.rive.RiveLog
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import kotlin.time.Duration
@@ -81,6 +83,8 @@ class RiveReactNativeView(context: ThemedReactContext) : FrameLayout(context) {
   @Volatile
   private var paused = false
 
+  private val viewScope = CoroutineScope(Dispatchers.Default + SupervisorJob())
+
   private val textureView = TextureView(context).apply {
     layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
     surfaceTextureListener = object : TextureView.SurfaceTextureListener {
@@ -290,16 +294,15 @@ class RiveReactNativeView(context: ThemedReactContext) : FrameLayout(context) {
         boundInstance = null
       }
       is BindData.Auto -> {
-        CoroutineScope(Dispatchers.Default).launch {
+        viewScope.launch {
           try {
             val vmNames = riveFile.getViewModelNames()
             if (vmNames.isEmpty()) return@launch
             withContext(Dispatchers.Main) {
+              if (disposed) return@withContext
               val art = artboard ?: return@withContext
               val source = ViewModelSource.DefaultForArtboard(art).defaultInstance()
               val instance = ViewModelInstance.fromFile(riveFile, source)
-              // A handle of 1L is the C++ null sentinel — the artboard has ViewModels but
-              // none is set as the default, so binding would fire "instance 0x1 not found".
               if (instance.instanceHandle.handle == 1L) {
                 Log.d(TAG, "Auto-binding skipped: no default ViewModel for artboard")
                 return@withContext
@@ -387,6 +390,7 @@ class RiveReactNativeView(context: ThemedReactContext) : FrameLayout(context) {
 
   fun dispose() {
     disposed = true
+    viewScope.cancel()
     RiveErrorLogger.removeListener(errorListener)
     stopRenderLoop()
     // Null handles to prevent any further draw calls.
diff --git a/example/__tests__/bind-before-ready.harness.tsx b/example/__tests__/bind-before-ready.harness.tsx
@@ -0,0 +1,96 @@
+import {
+  describe,
+  it,
+  expect,
+  render,
+  waitFor,
+  cleanup,
+} from 'react-native-harness';
+import { Platform, View } from 'react-native';
+import {
+  RiveView,
+  RiveFileFactory,
+  Fit,
+  type RiveFile,
+  type RiveViewRef,
+  type ViewModelInstance,
+} from '@rive-app/react-native';
+
+// bouncing_ball has a 'ypos' ViewModel property driven by the state machine
+const BOUNCING_BALL = require('../assets/rive/bouncing_ball.riv');
+
+function expectDefined<T>(value: T): asserts value is NonNullable<T> {
+  expect(value).toBeDefined();
+}
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('bindViewModelInstance before view ready', () => {
+  it('bind called before configure completes is applied', async () => {
+    // The race only exists on iOS experimental — riveInstance is set async
+    if (
+      Platform.OS !== 'ios' ||
+      RiveFileFactory.getBackend() !== 'experimental'
+    ) {
+      return;
+    }
+
+    const file = await RiveFileFactory.fromSource(BOUNCING_BALL, undefined);
+    const vm = file.defaultArtboardViewModel();
+    expectDefined(vm);
+    const instance: ViewModelInstance = vm.createDefaultInstance()!;
+    expectDefined(instance);
+
+    let ref: RiveViewRef | null = null;
+    let error: string | null = null;
+    let bindCalledBeforeReady = false;
+
+    // The hybridRef callback fires synchronously on mount, before the Swift
+    // configTask async work has had a chance to run — so riveInstance is nil
+    // at this point, and the bind will be silently dropped without the fix.
+    function TestView({ riveFile }: { riveFile: RiveFile }) {
+      return (
+        <View style={{ width: 200, height: 200 }}>
+          <RiveView
+            hybridRef={{
+              f: (r: RiveViewRef | null) => {
+                ref = r;
+                if (r && !bindCalledBeforeReady) {
+                  bindCalledBeforeReady = true;
+                  r.bindViewModelInstance(instance);
+                }
+              },
+            }}
+            style={{ flex: 1 }}
+            file={riveFile}
+            autoPlay
+            fit={Fit.Contain}
+            onError={(e) => {
+              error = e.message;
+            }}
+          />
+        </View>
+      );
+    }
+
+    await render(<TestView riveFile={file} />);
+    await waitFor(() => expect(ref).not.toBeNull(), { timeout: 5000 });
+
+    expect(bindCalledBeforeReady).toBe(true);
+
+    // Let the animation run
+    await delay(1200);
+
+    // ypos on OUR instance should be changing if the bind was applied.
+    // If the bind was silently dropped, ypos stays at its initial value
+    // because the state machine is driving a different (auto-bound) instance.
+    const ypos = instance.numberProperty('ypos');
+    expectDefined(ypos);
+    const v1 = ypos.value;
+    await delay(600);
+    expect(ypos.value).not.toBe(v1);
+
+    expect(error).toBeNull();
+    cleanup();
+  });
+});
diff --git a/example/__tests__/reconfigure.harness.tsx b/example/__tests__/reconfigure.harness.tsx
@@ -0,0 +1,108 @@
+import {
+  describe,
+  it,
+  expect,
+  render,
+  waitFor,
+  cleanup,
+} from 'react-native-harness';
+import { useState } from 'react';
+import { Platform, View } from 'react-native';
+import {
+  RiveView,
+  RiveFileFactory,
+  Fit,
+  type RiveFile,
+  type RiveViewRef,
+} from '@rive-app/react-native';
+
+const BOUNCING_BALL = require('../assets/rive/bouncing_ball.riv');
+const COUNTER = require('../assets/rive/counter.riv');
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+type TestContext = { ref: RiveViewRef | null; error: string | null };
+
+function SwitchableRiveView({
+  file,
+  context,
+}: {
+  file: RiveFile;
+  context: TestContext;
+}) {
+  return (
+    <View style={{ width: 200, height: 200 }}>
+      <RiveView
+        hybridRef={{
+          f: (ref: RiveViewRef | null) => {
+            context.ref = ref;
+          },
+        }}
+        style={{ flex: 1 }}
+        file={file}
+        autoPlay
+        fit={Fit.Contain}
+        onError={(e) => {
+          context.error = e.message;
+        }}
+      />
+    </View>
+  );
+}
+
+describe('RiveView reconfigure (file switch)', () => {
+  it('animation still plays after switching file prop and back', async () => {
+    // Fix only applies to iOS experimental — setupRiveUIView teardown churn
+    if (
+      Platform.OS !== 'ios' ||
+      RiveFileFactory.getBackend() !== 'experimental'
+    ) {
+      return;
+    }
+
+    const file1 = await RiveFileFactory.fromSource(BOUNCING_BALL, undefined);
+    const file2 = await RiveFileFactory.fromSource(COUNTER, undefined);
+    const context: TestContext = { ref: null, error: null };
+
+    let setFile!: (f: RiveFile) => void;
+    function Wrapper() {
+      const [file, _setFile] = useState<RiveFile>(file1);
+      setFile = _setFile;
+      return <SwitchableRiveView file={file} context={context} />;
+    }
+
+    await render(<Wrapper />);
+    await waitFor(() => expect(context.ref).not.toBeNull(), { timeout: 5000 });
+
+    // Confirm bouncing_ball is animating via its ypos ViewModel property
+    const vmi1 = context.ref!.getViewModelInstance();
+    expect(vmi1).not.toBeNull();
+    const ypos1 = vmi1!.numberProperty('ypos');
+    expect(ypos1).toBeDefined();
+    const valueBefore = ypos1!.value;
+    await delay(500);
+    expect(ypos1!.value).not.toBe(valueBefore);
+
+    // Switch to counter.riv — triggers setupRiveUIView reconfigure
+    setFile(file2);
+    await delay(600);
+    expect(context.error).toBeNull();
+
+    // Switch back to bouncing_ball — triggers setupRiveUIView again
+    setFile(file1);
+    await delay(600);
+    expect(context.error).toBeNull();
+
+    // Animation should still be running on the reconfigured view
+    const vmi2 = context.ref!.getViewModelInstance();
+    expect(vmi2).not.toBeNull();
+    const ypos2 = vmi2!.numberProperty('ypos');
+    expect(ypos2).toBeDefined();
+    const valueAfterSwitch = ypos2!.value;
+    await delay(500);
+    expect(ypos2!.value).not.toBe(valueAfterSwitch);
+
+    expect(context.error).toBeNull();
+    cleanup();
+  });
+});
diff --git a/ios/new/RiveReactNativeView.swift b/ios/new/RiveReactNativeView.swift
@@ -22,6 +22,7 @@ struct ViewConfiguration {
 class RiveReactNativeView: UIView {
   private var riveUIView: RiveUIView?
   private var riveInstance: RiveRuntime.Rive?
+  private var pendingBindInstance: ViewModelInstance?
   private var viewReadyContinuations: [CheckedContinuation<Void, Never>] = []
   private var isViewReady = false
   private var configTask: Task<Void, Never>?
@@ -87,6 +88,10 @@ class RiveReactNativeView: UIView {
 
           self.riveInstance = rive
           self.isPaused = !config.autoPlay
+          if let pending = self.pendingBindInstance {
+            self.pendingBindInstance = nil
+            rive.stateMachine.bindViewModelInstance(pending)
+          }
           self.setupRiveUIView(with: rive)
 
           if !self.isViewReady {
@@ -106,7 +111,12 @@ class RiveReactNativeView: UIView {
   }
 
   func bindViewModelInstance(viewModelInstance: ViewModelInstance) {
-    riveInstance?.stateMachine.bindViewModelInstance(viewModelInstance)
+    if let rive = riveInstance {
+      rive.stateMachine.bindViewModelInstance(viewModelInstance)
+    } else {
+      // configTask hasn't finished yet — queue it to apply once riveInstance is set
+      pendingBindInstance = viewModelInstance
+    }
   }
 
   func getViewModelInstance() -> ViewModelInstance? {
@@ -166,22 +176,24 @@ class RiveReactNativeView: UIView {
   // MARK: - Internal
 
   private func setupRiveUIView(with rive: RiveRuntime.Rive) {
-    // Remove existing view if any
-    // Note: The old RiveUIView's MTKView may still fire a few draw calls after removal,
-    // which can cause "state machine not found" errors if the old state machine is deallocated.
-    // This is a limitation of the experimental API - RiveUIView.rive is not publicly settable.
-    riveUIView?.removeFromSuperview()
-
-    let uiView = RiveUIView(rive: rive, isPaused: isPaused)
-    uiView.translatesAutoresizingMaskIntoConstraints = false
-    addSubview(uiView)
-    NSLayoutConstraint.activate([
-      uiView.leadingAnchor.constraint(equalTo: leadingAnchor),
-      uiView.trailingAnchor.constraint(equalTo: trailingAnchor),
-      uiView.topAnchor.constraint(equalTo: topAnchor),
-      uiView.bottomAnchor.constraint(equalTo: bottomAnchor),
-    ])
-    self.riveUIView = uiView
+    if let existing = riveUIView {
+      // Reuse the existing view — avoids tearing down the MTKView on every
+      // reconfigure, which previously caused orphaned draw calls ("state machine
+      // not found") from the old MTKView after removeFromSuperview.
+      existing.rive = rive
+      existing.isPaused = isPaused
+    } else {
+      let uiView = RiveUIView(rive: rive, isPaused: isPaused)
+      uiView.translatesAutoresizingMaskIntoConstraints = false
+      addSubview(uiView)
+      NSLayoutConstraint.activate([
+        uiView.leadingAnchor.constraint(equalTo: leadingAnchor),
+        uiView.trailingAnchor.constraint(equalTo: trailingAnchor),
+        uiView.topAnchor.constraint(equalTo: topAnchor),
+        uiView.bottomAnchor.constraint(equalTo: bottomAnchor),
+      ])
+      self.riveUIView = uiView
+    }
   }
 
   private func cleanup() {
@@ -191,6 +203,7 @@ class RiveReactNativeView: UIView {
     riveUIView?.removeFromSuperview()
     riveUIView = nil
     riveInstance = nil
+    pendingBindInstance = nil
   }
 
   deinit {
diff --git a/src/hooks/useViewModelInstance.ts b/src/hooks/useViewModelInstance.ts
@@ -174,8 +174,8 @@ function createInstance(
   if (instanceName) {
     try {
       vmi = source.createInstanceByName(instanceName);
-    } catch {
-      // experimental backend throws for non-existent names
+    } catch (e) {
+      console.warn(`createInstanceByName('${instanceName}') failed:`, e);
     }
     if (!vmi) {
       return {
